\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.14.0, 11月 01, 2025

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{13b}
@menu
* Python 有什麼新功能？:: 
* Python 教學:: 
* Python 的設置與使用:: 
* Python 語言參考手冊:: 
* Python 標準函式庫 (Standard Library): Python 標準函式庫 Standard Library. 
* 擴充和嵌入 Python 直譯器:: 
* Python/C API 參考手冊:: 
* 安裝 Python 模組:: 
* Python 如何達成任務:: 
* Python 常見問題:: 
* 已棄用項目:: 
* 術語表:: 
* 關於這份說明文件:: 
* 處理錯誤 (Bug): 處理錯誤 Bug. 
* 版權宣告:: 
* 沿革與授權:: 
* Python 模組索引:: 
* 索引:: 

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

Python 有什麼新功能？

* Python 3.14 有什麼新功能: Python 3 14 有什麼新功能. 
* Python 3.13 有什麼新功能: Python 3 13 有什麼新功能. 
* Python 3.12 有什麼新功能: Python 3 12 有什麼新功能. 
* Python 3.11 有什麼新功能: Python 3 11 有什麼新功能. 
* Python 3.10 有什麼新功能: Python 3 10 有什麼新功能. 
* Python 3.9 有什麼新功能: Python 3 9 有什麼新功能. 
* Python 3.8 有什麼新功能: Python 3 8 有什麼新功能. 
* Python 3.7 有什麼新功能: Python 3 7 有什麼新功能. 
* Python 3.6 有什麼新功能: Python 3 6 有什麼新功能. 
* Python 3.5 有什麼新功能: Python 3 5 有什麼新功能. 
* Python 3.4 有什麼新功能: Python 3 4 有什麼新功能. 
* Python 3.3 有什麼新功能: Python 3 3 有什麼新功能. 
* Python 3.2 有什麼新功能: Python 3 2 有什麼新功能. 
* Python 3.1 有什麼新功能: Python 3 1 有什麼新功能. 
* Python 3.0 有什麼新功能: Python 3 0 有什麼新功能. 
* Python 2.7 有什麼新功能: Python 2 7 有什麼新功能. 
* Python 2.6 有什麼新功能: Python 2 6 有什麼新功能. 
* Python 2.5 有什麼新功能: Python 2 5 有什麼新功能. 
* Python 2.4 有什麼新功能: Python 2 4 有什麼新功能. 
* Python 2.3 有什麼新功能: Python 2 3 有什麼新功能. 
* Python 2.2 有什麼新功能: Python 2 2 有什麼新功能. 
* Python 2.1 有什麼新功能: Python 2 1 有什麼新功能. 
* Python 2.0 有什麼新功能: Python 2 0 有什麼新功能. 
* Changelog（更動日誌）:: 

Python 3.14 有什麼新功能

* Summary: Summary -- Release highlights. Release highlights
* New features:: 
* Other language changes:: 
* New modules:: 
* Improved modules:: 
* 最佳化:: 
* 已移除:: 
* 已棄用:: 
* CPython 位元組碼變更:: 
* C API 變更:: 
* 建置變更:: 
* 移植至 Python 3.14: 移植至 Python 3 14. 

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:: 
* 改善錯誤訊息:: 
* PEP 784：標準函式庫中的 Zstandard 支援:: 
* 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. 
* Incremental garbage collection:: 
* Default interactive shell:: 

Improved modules

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

最佳化

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

已移除

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

已棄用

* New deprecations:: 
* Python 3.15 中待移除的項目: Python 3 15 中待移除的項目. 
* Python 3.16 中待移除的項目: Python 3 16 中待移除的項目. 
* Python 3.17 中待移除的項目: Python 3 17 中待移除的項目. 
* Python 3.19 中待移除的項目: Python 3 19 中待移除的項目. 
* 未來版本中的待移除項目:: 

CPython 位元組碼變更

* Pseudo-instructions:: 

C API 變更

* Python configuration C API:: 
* C API 中的新功能:: 
* Limited C API changes:: 
* 被移除的 C API:: 
* 已棄用的 C API:: 

已棄用的 C API

* Python 3.15 中待移除的項目: Python 3 15 中待移除的項目<2>. 
* Python 3.16 中待移除的項目: Python 3 16 中待移除的項目<2>. 
* Python 3.18 中待移除的項目: Python 3 18 中待移除的項目. 
* 未來版本中的待移除項目: 未來版本中的待移除項目<2>. 

建置變更

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

移植至 Python 3.14

* Python API 的變更:: 
* Changes in annotations (PEP 649 and PEP 749): Changes in annotations PEP 649 and PEP 749. 
* 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:: 

Python 3.13 有什麼新功能

* 發布重點摘要:: 
* 新增功能:: 
* 其他語言更動:: 
* 新增模組:: 
* 改進的模組:: 
* 最佳化: 最佳化<2>. 
* 被移除的模組和 API:: 
* New Deprecations:: 
* CPython 位元組碼變更: CPython 位元組碼變更<2>. 
* C API 變更: C API 變更<2>. 
* 建置變更: 建置變更<2>. 
* 移植至 Python 3.13: 移植至 Python 3 13. 
* 迴歸測試的變更:: 

新增功能

* A better interactive interpreter:: 
* 改善錯誤訊息: 改善錯誤訊息<2>. 
* 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. 
* 對行動平台的支援:: 

改進的模組

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

被移除的模組和 API

* PEP 594：從標準函式庫中移除「用完的電池」:: 
* 2to3:: 
* builtins:: 
* configparser: configparser<3>. 
* importlib.metadata: importlib metadata. 
* locale:: 
* opcode:: 
* optparse:: 
* pathlib: pathlib<5>. 
* re: re<3>. 
* tkinter.tix: tkinter tix. 
* turtle: turtle<2>. 
* typing: typing<3>. 
* unittest: unittest<2>. 
* urllib: urllib<3>. 
* webbrowser: webbrowser<2>. 

New Deprecations

* Python 3.14 中待移除的項目: Python 3 14 中待移除的項目. 
* Python 3.15 中待移除的項目: Python 3 15 中待移除的項目<3>. 
* Python 3.16 中待移除的項目: Python 3 16 中待移除的項目<3>. 
* Python 3.17 中待移除的項目: Python 3 17 中待移除的項目<2>. 
* 未來版本中的待移除項目: 未來版本中的待移除項目<3>. 

C API 變更

* 新增功能: 新增功能<2>. 
* Changed C APIs:: 
* Limited C API Changes:: 
* 移除的 C API:: 
* 器用的 C API:: 

器用的 C API

* Python 3.14 中待移除的項目: Python 3 14 中待移除的項目<2>. 
* Python 3.15 中待移除的項目: Python 3 15 中待移除的項目<4>. 
* Python 3.16 中待移除的項目: Python 3 16 中待移除的項目<4>. 
* Python 3.18 中待移除的項目: Python 3 18 中待移除的項目<2>. 
* 未來版本中的待移除項目: 未來版本中的待移除項目<4>. 

移植至 Python 3.13

* Python API 的變更: Python API 的變更<2>. 
* C API 中的改動: C API 中的改動<2>. 

Python 3.12 有什麼新功能

* 發布重點摘要: 發布重點摘要<2>. 
* 新增功能: 新增功能<3>. 
* 型別提示相關的新特性:: 
* 其他語言更動: 其他語言更動<2>. 
* 新增模組: 新增模組<2>. 
* 改進的模組: 改進的模組<2>. 
* 最佳化: 最佳化<3>. 
* CPython 位元組碼變更: CPython 位元組碼變更<3>. 
* Demos and Tools:: 
* 已棄用: 已棄用<2>. 
* 已移除: 已移除<2>. 
* 移植至 Python 3.12: 移植至 Python 3 12. 
* 建置變更: 建置變更<3>. 
* C API 變更: C API 變更<3>. 

新增功能

* PEP 695：型別參數語法:: 
* PEP 701; Syntactic formalization of f-strings: PEP 701 Syntactic formalization of f-strings. 
* PEP 684：直譯器各別持有的 GIL:: 
* PEP 669; Low impact monitoring for CPython: PEP 669 Low impact monitoring for CPython. 
* PEP 688：使緩衝區協定可在 Python 中存取:: 
* PEP 709; Comprehension inlining: PEP 709 Comprehension inlining. 
* 改善錯誤訊息: 改善錯誤訊息<3>. 

型別提示相關的新特性

* PEP 692; Using TypedDict for more precise **kwargs typing: PEP 692 Using TypedDict for more precise **kwargs typing. 
* PEP 698：覆蓋靜態型別的裝飾器:: 

改進的模組

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

已棄用

* Python 3.13 中待移除的項目: Python 3 13 中待移除的項目. 
* Python 3.14 中待移除的項目: Python 3 14 中待移除的項目<3>. 
* Python 3.15 中待移除的項目: Python 3 15 中待移除的項目<5>. 
* Python 3.16 中待移除的項目: Python 3 16 中待移除的項目<5>. 
* Python 3.17 中待移除的項目: Python 3 17 中待移除的項目<3>. 
* 未來版本中的待移除項目: 未來版本中的待移除項目<5>. 

已移除

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

移植至 Python 3.12

* Python API 的變更: Python API 的變更<3>. 

C API 變更

* 新增功能: 新增功能<4>. 
* 移植至 Python 3.12: 移植至 Python 3 12<2>. 
* 已棄用: 已棄用<3>. 
* 已移除: 已移除<3>. 

已棄用

* Python 3.14 中待移除的項目: Python 3 14 中待移除的項目<4>. 
* Python 3.15 中待移除的項目: Python 3 15 中待移除的項目<6>. 
* Python 3.16 中待移除的項目: Python 3 16 中待移除的項目<6>. 
* 未來版本中的待移除項目: 未來版本中的待移除項目<6>. 

Python 3.11 有什麼新功能

* 發布重點摘要: 發布重點摘要<3>. 
* 新增功能: 新增功能<5>. 
* 型別提示相關的新特性: 型別提示相關的新特性<2>. 
* 其他語言更動: 其他語言更動<3>. 
* 其他 CPython 實作更動:: 
* 新增模組: 新增模組<3>. 
* 改進的模組: 改進的模組<3>. 
* 最佳化: 最佳化<4>. 
* 更快的 CPython:: 
* CPython 位元組碼變更: CPython 位元組碼變更<4>. 
* 已棄用: 已棄用<4>. 
* Python 3.12 中待決議的移除項目: Python 3 12 中待決議的移除項目. 
* 已移除: 已移除<4>. 
* 移植至 Python 3.11: 移植至 Python 3 11. 
* 建置變更: 建置變更<4>. 
* C API 變更: C API 變更<4>. 
* Python 3.11.4 中顯著的變更: Python 3 11 4 中顯著的變更. 
* Python 3.11.5 中顯著的變更: Python 3 11 5 中顯著的變更. 

新增功能

* PEP 657：回溯 (traceback) 中更細緻的錯誤位置: PEP 657：回溯 traceback 中更細緻的錯誤位置. 
* PEP 654：例外群組與 except*:: 
* PEP 678：運用例外註解使其更加詳盡:: 
* Windows py.exe 啟動程式 (launcher) 的改進: Windows py exe 啟動程式 launcher 的改進. 

型別提示相關的新特性

* PEP 646：可變參數泛型 (variadic generics): PEP 646：可變參數泛型 variadic generics. 
* PEP 655：標記獨立 TypedDict 項目為必要或不必要:: 
* PEP 673：Self 型別:: 
* PEP 675：任意的文本字串型別 (Arbitrary literal string type): PEP 675：任意的文本字串型別 Arbitrary literal string type. 
* PEP 681：資料類別轉換 (Data class transforms): PEP 681：資料類別轉換 Data class transforms. 
* PEP 563 可能不是未來:: 

改進的模組

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

更快的 CPython

* 更快的啟動:: 
* 更快的運行程式:: 
* 雜項:: 
* FAQ:: 
* 關於:: 

更快的啟動

* 凍結引入 (Frozen imports) / 靜態程式碼物件 (Static code objects): 凍結引入 Frozen imports / 靜態程式碼物件 Static code objects. 

更快的運行程式

* 所需資源更少 (cheaper) 且惰性的 (lazy)) Python 幀 (frame): 所需資源更少 cheaper 且惰性的 lazy Python 幀 frame. 
* 行內 Python 函式呼叫:: 
* PEP 659：特化的適應性直譯器:: 

FAQ

* 我該如何在程式碼中取得這些加速？:: 
* Python 3.11 會不會使用更多記憶體？: Python 3 11 會不會使用更多記憶體？. 
* 我在我的程式當中沒感覺到任何加速，為什麼？:: 
* 有用到 JIT 編譯器嗎？:: 

CPython 位元組碼變更

* 新增 opcode:: 
* 被取代的操作碼 (opcode): 被取代的操作碼 opcode. 
* 有更動/被移除的 opcode:: 

已棄用

* 語言/內建:: 
* 模組:: 
* 標準函式庫:: 

C API 變更

* 新增功能: 新增功能<6>. 
* 移植至 Python 3.11: 移植至 Python 3 11<2>. 
* 已棄用: 已棄用<5>. 
* Python 3.12 中待決議的移除項目: Python 3 12 中待決議的移除項目<2>. 
* 已移除: 已移除<5>. 

Python 3.11.4 中顯著的變更

* tarfile: tarfile<2>. 

Python 3.11.5 中顯著的變更

* OpenSSL:: 

Python 3.10 有什麼新功能

* 發布重點摘要: 發布重點摘要<4>. 
* 新增功能: 新增功能<7>. 
* 與型別提示相關的新功能:: 
* 其他語言更動: 其他語言更動<4>. 
* 新模組:: 
* 改進的模組: 改進的模組<4>. 
* 最佳化: 最佳化<5>. 
* 已棄用: 已棄用<6>. 
* 已刪除:: 
* 移植到 Python 3.10: 移植到 Python 3 10. 
* CPython 位元組碼變更: CPython 位元組碼變更<5>. 
* 建置變更: 建置變更<5>. 
* C API 變更: C API 變更<5>. 
* Python 3.10.7 中顯著的安全性功能: Python 3 10 7 中顯著的安全性功能. 
* Python 3.10.8 中顯著的安全性功能: Python 3 10 8 中顯著的安全性功能. 
* Python 3.10.12 中顯著的變更: Python 3 10 12 中顯著的變更. 

新增功能

* 帶括號的情境管理器:: 
* 更好的錯誤訊息:: 
* PEP 626：用於除錯和其他工具的精確列號:: 
* PEP 634：結構模式匹配:: 
* 可選的 EncodingWarning 和 encoding="locale" 選項:: 

更好的錯誤訊息

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

PEP 634：結構模式匹配

* 語法和操作:: 
* 宣告式方法 (Declarative approach): 宣告式方法 Declarative approach. 
* 簡單模式：與字面值匹配:: 
* 具有字面值和變數的模式:: 
* 模式和類別:: 
* 巢狀模式:: 
* 複雜模式和萬用字元:: 
* Guard:: 
* 其他主要功能:: 

簡單模式：與字面值匹配

* 沒有萬用字元 (wildcard) 的行為: 沒有萬用字元 wildcard 的行為. 

模式和類別

* 具有位置參數的模式:: 

與型別提示相關的新功能

* PEP 604：新型聯集運算子:: 
* PEP 612：參數規範變數:: 
* PEP 613：型別別名 (TypeAlias): PEP 613：型別別名 TypeAlias. 
* PEP 647：使用者定義的型別防護:: 

改進的模組

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

dataclasses

* __slots__:: 
* 僅限關鍵字欄位 (Keyword-only fields): 僅限關鍵字欄位 Keyword-only fields. 

移植到 Python 3.10

* Python 語法的變化:: 
* Python API 的變更: Python API 的變更<4>. 
* C API 中的改動: C API 中的改動<3>. 

C API 變更

* PEP 652：維護穩定 ABI:: 
* 新增功能: 新增功能<8>. 
* 移植到 Python 3.10: 移植到 Python 3 10<2>. 
* 已棄用: 已棄用<7>. 
* 已刪除: 已刪除<2>. 

Python 3.10.12 中顯著的變更

* tarfile: tarfile<3>. 

Python 3.9 有什麼新功能

* 發布重點摘要: 發布重點摘要<5>. 
* You should check for DeprecationWarning in your code:: 
* 新增功能: 新增功能<9>. 
* 其他語言更動: 其他語言更動<5>. 
* 新模組: 新模組<2>. 
* 改進的模組: 改進的模組<5>. 
* 最佳化: 最佳化<6>. 
* 已棄用: 已棄用<8>. 
* 已移除: 已移除<6>. 
* 移植至 Python 3.9: 移植至 Python 3 9. 
* 建置變更: 建置變更<6>. 
* C API 變更: C API 變更<6>. 
* Python 3.9.1 中顯著的變更: Python 3 9 1 中顯著的變更. 
* Python 3.9.2 中顯著的變更: Python 3 9 2 中顯著的變更. 
* Python 3.9.3 中顯著的變更: Python 3 9 3 中顯著的變更. 
* Python 3.9.5 中顯著的變更: Python 3 9 5 中顯著的變更. 
* Python 3.9.14 中顯著的安全性功能: Python 3 9 14 中顯著的安全性功能. 
* Python 3.9.17 中顯著的變更: Python 3 9 17 中顯著的變更. 

新增功能

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

新模組

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

改進的模組

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

移植至 Python 3.9

* Python API 的變更: Python API 的變更<5>. 
* C API 中的改動: C API 中的改動<4>. 
* CPython 位元組碼變更: CPython 位元組碼變更<6>. 

C API 變更

* 新增功能: 新增功能<10>. 
* 移植至 Python 3.9: 移植至 Python 3 9<2>. 
* 已移除: 已移除<7>. 

Python 3.9.1 中顯著的變更

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

Python 3.9.2 中顯著的變更

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

Python 3.9.5 中顯著的變更

* urllib.parse: urllib parse<3>. 

Python 3.9.17 中顯著的變更

* tarfile: tarfile<4>. 

Python 3.8 有什麼新功能

* 發布重點摘要: 發布重點摘要<6>. 
* 新增功能: 新增功能<11>. 
* 其他語言更動: 其他語言更動<6>. 
* 新增模組: 新增模組<4>. 
* 改進的模組: 改進的模組<6>. 
* 最佳化: 最佳化<7>. 
* 建置和 C API 變更:: 
* 已棄用: 已棄用<9>. 
* API 與功能的移除:: 
* 移植至 Python 3.8: 移植至 Python 3 8. 
* Python 3.8.1 中顯著的變更: Python 3 8 1 中顯著的變更. 
* Python 3.8.2 中顯著的變更: Python 3 8 2 中顯著的變更. 
* Python 3.8.3 中顯著的變更: Python 3 8 3 中顯著的變更. 
* Python 3.8.8 中顯著的變更: Python 3 8 8 中顯著的變更. 
* Python 3.8.9 中顯著的變更: Python 3 8 9 中顯著的變更. 
* Python 3.8.10 中顯著的變更: Python 3 8 10 中顯著的變更. 
* Python 3.8.10 中顯著的變更: Python 3 8 10 中顯著的變更<2>. 
* Python 3.8.12 中顯著的變更: Python 3 8 12 中顯著的變更. 
* Python 3.8.14 中顯著的安全性功能: Python 3 8 14 中顯著的安全性功能. 
* Python 3.8.17 中顯著的變更: Python 3 8 17 中顯著的變更. 

新增功能

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

改進的模組

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

移植至 Python 3.8

* Python 行為的改變:: 
* Python API 的變更: Python API 的變更<6>. 
* C API 中的改動: C API 中的改動<5>. 
* CPython 位元組碼變更: CPython 位元組碼變更<7>. 
* Demos and Tools: Demos and Tools<2>. 

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

Python 3.8.10 中顯著的變更

* urllib.parse: urllib parse<4>. 

Python 3.8.12 中顯著的變更

* Python API 的變更: Python API 的變更<7>. 

Python 3.8.17 中顯著的變更

* tarfile: tarfile<6>. 

Python 3.7 有什麼新功能

* 發布重點摘要: 發布重點摘要<7>. 
* 新增功能: 新增功能<12>. 
* 其他語言更動: 其他語言更動<7>. 
* 新模組: 新模組<3>. 
* 改進的模組: 改進的模組<7>. 
* C API 變更: C API 變更<7>. 
* 建置變更: 建置變更<7>. 
* 最佳化: 最佳化<8>. 
* Other CPython Implementation Changes:: 
* 已棄用的 Python 行為:: 
* 已棄用的 Python 模組、函式和方法:: 
* Deprecated functions and types of the C API:: 
* Platform Support Removals:: 
* API 與功能的移除: API 與功能的移除<2>. 
* Module Removals:: 
* Windows-only Changes:: 
* 移植至 Python 3.7: 移植至 Python 3 7. 
* Python 3.7.1 中顯著的變更: Python 3 7 1 中顯著的變更. 
* Python 3.7.2 中顯著的變更: Python 3 7 2 中顯著的變更. 
* Python 3.7.6 中顯著的變更: Python 3 7 6 中顯著的變更. 
* Python 3.7.10 中顯著的變更: Python 3 7 10 中顯著的變更. 
* Python 3.7.11 中顯著的變更: Python 3 7 11 中顯著的變更. 
* Python 3.7.14 中顯著的安全性功能: Python 3 7 14 中顯著的安全性功能. 

新增功能

* PEP 563：延後評估註釋:: 
* 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 文件翻譯:: 
* Python Development Mode (-X dev): Python Development Mode -X dev. 

新模組

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

改進的模組

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

已棄用的 Python 模組、函式和方法

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

移植至 Python 3.7

* Python 行為的改變: Python 行為的改變<2>. 
* Python API 的變更: Python API 的變更<8>. 
* C API 中的改動: C API 中的改動<6>. 
* CPython 位元組碼變更: CPython 位元組碼變更<8>. 
* Windows-only Changes: Windows-only Changes<2>. 
* Other CPython implementation changes:: 

Python 3.6 有什麼新功能

* 發布重點摘要: 發布重點摘要<8>. 
* 新增功能: 新增功能<13>. 
* 其他語言更動: 其他語言更動<8>. 
* 新模組: 新模組<4>. 
* 改進的模組: 改進的模組<8>. 
* 最佳化: 最佳化<9>. 
* 建置和 C API 變更: 建置和 C API 變更<2>. 
* 其他改進:: 
* 已棄用: 已棄用<10>. 
* 已移除: 已移除<8>. 
* 移植至 Python 3.6: 移植至 Python 3 6. 
* Python 3.6.2 中顯著的變更: Python 3 6 2 中顯著的變更. 
* Python 3.6.4 中顯著的變更: Python 3 6 4 中顯著的變更. 
* Python 3.6.5 中顯著的變更: Python 3 6 5 中顯著的變更. 
* Python 3.6.7 中顯著的變更: Python 3 6 7 中顯著的變更. 
* Python 3.6.10 中顯著的變更: Python 3 6 10 中顯著的變更. 
* Python 3.6.13 中顯著的變更: Python 3 6 13 中顯著的變更. 
* Python 3.6.14 中顯著的變更: Python 3 6 14 中顯著的變更. 

新增功能

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

新模組

* secrets:: 

改進的模組

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

已棄用

* 新關鍵字:: 
* 已棄用的 Python 行為: 已棄用的 Python 行為<2>. 
* 已棄用的 Python 模組、函式和方法: 已棄用的 Python 模組、函式和方法<2>. 
* xml: xml<6>. 
* C API 的已棄用函式和型別:: 
* 已棄用的建置選項:: 

已棄用的 Python 模組、函式和方法

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

已移除

* API 與功能的移除: API 與功能的移除<3>. 

移植至 Python 3.6

* 'python' 命令的行為變更:: 
* Python API 的變更: Python API 的變更<9>. 
* C API 中的改動: C API 中的改動<7>. 
* CPython 位元組碼變更: CPython 位元組碼變更<9>. 

Python 3.6.2 中顯著的變更

* 新增 make regen-all 建置目標:: 
* 移除 make touch 建置目標:: 

Python 3.5 有什麼新功能

* 發布重點摘要: 發布重點摘要<9>. 
* 新增功能: 新增功能<14>. 
* 其他語言更動: 其他語言更動<9>. 
* 新增模組: 新增模組<5>. 
* 改進的模組: 改進的模組<9>. 
* 其他模組層級的變更:: 
* 最佳化: 最佳化<10>. 
* 建置和 C API 變更: 建置和 C API 變更<3>. 
* 已棄用: 已棄用<11>. 
* 已移除: 已移除<9>. 
* 移植至 Python 3.5: 移植至 Python 3 5. 
* Python 3.5.4 中顯著的變更: Python 3 5 4 中顯著的變更. 

新增功能

* PEP 492 - 使用 async 和 await 語法的協程:: 
* 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 - 型別提示:: 
* PEP 471 - os.scandir() function: PEP 471 - os scandir function -- a better and faster directory iterator. a better and faster directory iterator
* PEP 475; Retry system calls failing with EINTR: PEP 475 Retry system calls failing with EINTR. 
* PEP 479; Change StopIteration handling inside generators: PEP 479 Change StopIteration handling inside generators. 
* PEP 485; A function for testing approximate equality: PEP 485 A function for testing approximate equality. 
* PEP 486; Make the Python Launcher aware of virtual environments: PEP 486 Make the Python Launcher aware of virtual environments. 
* PEP 488; Elimination of PYO files: PEP 488 Elimination of PYO files. 
* PEP 489; Multi-phase extension module initialization: PEP 489 Multi-phase extension module initialization. 

新增模組

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

改進的模組

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

ssl

* 記憶體 BIO 支援:: 
* Application-Layer Protocol Negotiation Support:: 
* 其他變更:: 

已棄用

* 新關鍵字: 新關鍵字<2>. 
* 已棄用的 Python 行為: 已棄用的 Python 行為<3>. 
* 不支援的作業系統:: 
* 已棄用的 Python 模組、函式和方法: 已棄用的 Python 模組、函式和方法<3>. 

已移除

* API 與功能的移除: API 與功能的移除<4>. 

移植至 Python 3.5

* Python 行為的改變: Python 行為的改變<3>. 
* Python API 的變更: Python API 的變更<10>. 
* C API 中的改動: C API 中的改動<8>. 

Python 3.5.4 中顯著的變更

* 新增 make regen-all 建置目標: 新增 make regen-all 建置目標<2>. 
* 移除 make touch 建置目標: 移除 make touch 建置目標<2>. 

Python 3.4 有什麼新功能

* 發布重點摘要: 發布重點摘要<10>. 
* 新增功能: 新增功能<15>. 
* 新模組: 新模組<5>. 
* 改進的模組: 改進的模組<10>. 
* CPython 實作變更:: 
* 已棄用: 已棄用<12>. 
* 已移除: 已移除<10>. 
* 移植至 Python 3.4: 移植至 Python 3 4. 
* 3.4.3 中的變更: 3 4 3 中的變更. 

新增功能

* 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. 
* 編解碼器處理的改進:: 
* PEP 451：用於引入系統的 ModuleSpec 型別:: 
* 其他語言更動: 其他語言更動<10>. 

PEP 453: Explicit Bootstrapping of PIP in Python Installations

* Bootstrapping pip By Default:: 
* 文件更動:: 

新模組

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

改進的模組

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

CPython 實作變更

* 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. 
* 其他建置和 C API 變更:: 
* 其他改進: 其他改進<2>. 
* 顯著最佳化:: 

已棄用

* 已棄用的 Python API:: 
* 已棄用功能:: 

已移除

* 不再支援的作業系統:: 
* API 與功能的移除: API 與功能的移除<5>. 
* 程式碼的清除:: 

移植至 Python 3.4

* Changes in 'python' Command Behavior:: 
* Python API 的變更: Python API 的變更<11>. 
* C API 中的改動: C API 中的改動<9>. 

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. 

Python 3.3 有什麼新功能

* 發布重點摘要: 發布重點摘要<11>. 
* PEP 405：虛擬環境:: 
* 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：適用於 Windows 的 Python 啟動器:: 
* 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：函式簽名物件:: 
* PEP 421：新增 sys.implementation: PEP 421：新增 sys implementation. 
* 使用 importlib 作為 import 的實作:: 
* 其他語言更動: 其他語言更動<11>. 
* A Finer-Grained Import Lock:: 
* 內建函式和型別:: 
* 新模組: 新模組<6>. 
* 改進的模組: 改進的模組<11>. 
* 最佳化: 最佳化<11>. 
* 建置和 C API 變更: 建置和 C API 變更<4>. 
* 已棄用: 已棄用<13>. 
* 移植到 Python 3.3: 移植到 Python 3 3. 

PEP 3118: New memoryview implementation and buffer protocol documentation

* 功能:: 
* API 變更:: 

PEP 393: Flexible String Representation

* 功能性:: 
* 性能和資源使用情況:: 

PEP 421：新增 sys.implementation

* SimpleNamespace:: 

使用 importlib 作為 import 的實作

* 新 API:: 
* 明顯的變更:: 

新模組

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

改進的模組

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

decimal

* 功能: 功能<2>. 
* API 變更: API 變更<2>. 

email

* Policy Framework:: 
* Provisional Policy with New Header API:: 
* 其他 API 變更:: 

已棄用

* 不支援的作業系統: 不支援的作業系統<2>. 
* 已棄用的 Python 模組、函式和方法: 已棄用的 Python 模組、函式和方法<4>. 
* C API 中已棄用的函式和型別:: 
* 已棄用的功能:: 

移植到 Python 3.3

* 移植 Python 程式碼:: 
* Porting C code:: 
* Building C extensions:: 
* 命令列開關更改:: 

Python 3.2 有什麼新功能

* PEP 384; Defining a Stable ABI: PEP 384 Defining a Stable ABI. 
* PEP 389; Argparse 命令列剖析模組: PEP 389 Argparse 命令列剖析模組. 
* PEP 391; Dictionary Based Configuration for Logging: PEP 391 Dictionary Based Configuration for Logging. 
* PEP 3148：concurrent.futures 模組: PEP 3148：concurrent futures 模組. 
* 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. 
* 其他語言更動: 其他語言更動<12>. 
* New@comma{} Improved@comma{} and Deprecated Modules: New Improved and Deprecated Modules. 
* Multi-threading:: 
* 最佳化: 最佳化<12>. 
* Unicode:: 
* 編解碼器:: 
* 文件:: 
* IDLE:: 
* Code Repository:: 
* 建置和 C API 變更: 建置和 C API 變更<5>. 
* 移植至 Python 3.2: 移植至 Python 3 2. 

New, Improved, and Deprecated Modules

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

Python 3.1 有什麼新功能

* PEP 372：有序字典:: 
* PEP 378; Format Specifier for Thousands Separator: PEP 378 Format Specifier for Thousands Separator. 
* 其他語言更動: 其他語言更動<13>. 
* 新增、改進和棄用的模組:: 
* 最佳化: 最佳化<13>. 
* IDLE: IDLE<2>. 
* 建置和 C API 變更: 建置和 C API 變更<6>. 
* 移植至 Python 3.1: 移植至 Python 3 1. 

Python 3.0 有什麼新功能

* Common Stumbling Blocks:: 
* 語法變更概要:: 
* Changes Already Present In Python 2.6: Changes Already Present In Python 2 6. 
* 函式庫變更:: 
* PEP 3101; A New Approach To String Formatting: PEP 3101 A New Approach To String Formatting. 
* Changes To Exceptions:: 
* Miscellaneous Other Changes:: 
* 建置和 C API 變更: 建置和 C API 變更<7>. 
* 效能:: 
* Porting To Python 3.0: Porting To Python 3 0. 

Common Stumbling Blocks

* Print 是一個函式:: 
* Views And Iterators Instead Of Lists:: 
* Ordering Comparisons:: 
* 整數:: 
* Text Vs. Data Instead Of Unicode Vs. 8-bit: Text Vs Data Instead Of Unicode Vs 8-bit. 

語法變更概要

* 新增語法:: 
* 語法變更:: 
* 已被移除的語法:: 

Miscellaneous Other Changes

* Operators And Special Methods:: 
* Builtins:: 

Python 2.7 有什麼新功能

* Python 2.x 的未來: 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. 
* 其他語言更動: 其他語言更動<14>. 
* New and Improved Modules:: 
* 建置和 C API 變更: 建置和 C API 變更<8>. 
* Other Changes and Fixes:: 
* 移植至 Python 2.7: 移植至 Python 2 7. 
* New Features Added to Python 2.7 Maintenance Releases: New Features Added to Python 2 7 Maintenance Releases. 
* 致謝:: 

其他語言更動

* Interpreter Changes:: 
* 最佳化: 最佳化<14>. 

New and Improved Modules

* 新模組：importlib:: 
* 新模組：sysconfig:: 
* ttk; Themed Widgets for Tk: ttk Themed Widgets for Tk. 
* 改進模組：unittest:: 
* 改進模組：ElementTree 1.3: 改進模組：ElementTree 1 3. 

建置和 C API 變更

* 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

* 偵錯模式下的兩個新環境變數:: 
* 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. 
* 新增 make regen-all 建置目標: 新增 make regen-all 建置目標<3>. 
* 移除 make touch 建置目標: 移除 make touch 建置目標<3>. 

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

* Bootstrapping pip By Default: Bootstrapping pip By Default<2>. 
* 文件更動: 文件更動<2>. 

Python 2.6 有什麼新功能

* Python 3.0: Python 3 0. 
* Changes to the Development Process:: 
* PEP 343：'with' 陳述式:: 
* 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：新 I/O 函式庫:: 
* PEP 3118：修訂緩衝協定:: 
* 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. 
* 其他語言更動: 其他語言更動<15>. 
* New and Improved Modules: New and Improved Modules<2>. 
* Deprecations and Removals:: 
* 建置和 C API 變更: 建置和 C API 變更<9>. 
* Porting to Python 2.6: Porting to Python 2 6. 
* 致謝: 致謝<2>. 

Changes to the Development Process

* New Issue Tracker; Roundup: New Issue Tracker Roundup. 
* 新文件格式：使用 Sphinx 的 reStructuredText:: 

PEP 343：'with' 陳述式

* Writing Context Managers:: 
* contextlib 模組:: 

PEP 3141: A Type Hierarchy for Numbers

* The fractions Module:: 

其他語言更動

* 最佳化: 最佳化<15>. 
* Interpreter Changes: Interpreter Changes<2>. 

New and Improved Modules

* ast 模組:: 
* future_builtins 模組:: 
* 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:: 

建置和 C API 變更

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

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：'with' 陳述式: PEP 343：'with' 陳述式<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. 
* 其他語言更動: 其他語言更動<16>. 
* New@comma{} Improved@comma{} and Removed Modules: New Improved and Removed Modules. 
* 建置和 C API 變更: 建置和 C API 變更<10>. 
* Porting to Python 2.5: Porting to Python 2 5. 
* 致謝: 致謝<3>. 

PEP 343：'with' 陳述式

* Writing Context Managers: Writing Context Managers<2>. 
* contextlib 模組: contextlib 模組<2>. 

其他語言更動

* Interactive Interpreter Changes:: 
* 最佳化: 最佳化<16>. 

New, Improved, and Removed Modules

* ctypes 套件:: 
* ElementTree 套件:: 
* hashlib 套件:: 
* sqlite3 套件:: 
* wsgiref 套件:: 

建置和 C API 變更

* Port-Specific Changes:: 

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. 
* 其他語言更動: 其他語言更動<17>. 
* New@comma{} Improved@comma{} and Deprecated Modules: New Improved and Deprecated Modules<2>. 
* 建置和 C API 變更: 建置和 C API 變更<11>. 
* Porting to Python 2.4: Porting to Python 2 4. 
* 致謝: 致謝<4>. 

PEP 327: Decimal Data Type

* Why is Decimal needed?:: 
* Decimal 型別:: 
* Context 型別:: 

其他語言更動

* 最佳化: 最佳化<17>. 

New, Improved, and Deprecated Modules

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

建置和 C API 變更

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

Python 2.3 有什麼新功能

* PEP 218; A Standard Set Datatype: PEP 218 A Standard Set Datatype. 
* PEP 255：簡單產生器:: 
* 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:: 
* 其他語言更動: 其他語言更動<18>. 
* New@comma{} Improved@comma{} and Deprecated Modules: New Improved and Deprecated Modules<3>. 
* Pymalloc; A Specialized Object Allocator: Pymalloc A Specialized Object Allocator. 
* 建置和 C API 變更: 建置和 C API 變更<12>. 
* Other Changes and Fixes: Other Changes and Fixes<2>. 
* Porting to Python 2.3: Porting to Python 2 3. 
* 致謝: 致謝<5>. 

其他語言更動

* String Changes:: 
* 最佳化: 最佳化<18>. 

New, Improved, and Deprecated Modules

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

建置和 C API 變更

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

Python 2.2 有什麼新功能

* 簡介:: 
* PEPs 252 and 253; Type and Class Changes: PEPs 252 and 253 Type and Class Changes. 
* PEP 234：疊代器:: 
* PEP 255：簡單產生器: PEP 255：簡單產生器<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 變更:: 
* PEP 227; Nested Scopes: PEP 227 Nested Scopes. 
* New and Improved Modules: New and Improved Modules<3>. 
* 直譯器的變更與修正:: 
* 其他改動與修正:: 
* 致謝: 致謝<6>. 

PEPs 252 and 253: Type and Class Changes

* 舊的和新的類別:: 
* 描述器:: 
* Multiple Inheritance; The Diamond Rule: Multiple Inheritance The Diamond Rule. 
* Attribute Access:: 
* 相關連結:: 

Python 2.1 有什麼新功能

* 簡介: 簡介<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<3>. 
* 致謝: 致謝<7>. 

Python 2.0 有什麼新功能

* 簡介: 簡介<3>. 
* What About Python 1.6?: What About Python 1 6?. 
* New Development Process:: 
* Unicode: Unicode<2>. 
* 串列綜合運算（List Comprehension）:: 
* 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 模組:: 
* 模組變更:: 
* 新增模組: 新增模組<6>. 
* IDLE Improvements:: 
* Deleted and Deprecated Modules:: 
* 致謝: 致謝<8>. 

Other Core Changes

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

XML 模組

* SAX2 支援:: 
* DOM 支援:: 
* Relationship to PyXML:: 

Changelog（更動日誌）

* Python next:: 
* Python 3.14.0 final: Python 3 14 0 final. 
* Python 3.14.0 release candidate 3: Python 3 14 0 release candidate 3. 
* Python 3.14.0 release candidate 2: Python 3 14 0 release candidate 2. 
* Python 3.14.0 release candidate 1: Python 3 14 0 release candidate 1. 
* Python 3.14.0 beta 4: Python 3 14 0 beta 4. 
* Python 3.14.0 beta 3: Python 3 14 0 beta 3. 
* Python 3.14.0 beta 2: Python 3 14 0 beta 2. 
* 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

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

Python 3.14.0 final

* macOS:: 
* Windows: Windows<2>. 
* Tools/Demos: Tools/Demos<2>. 
* Security: Security<2>. 
* Library: Library<2>. 

Python 3.14.0 release candidate 3

* Windows: Windows<3>. 
* Tools/Demos: Tools/Demos<3>. 
* Security: Security<3>. 
* Library: Library<3>. 
* Core and Builtins: Core and Builtins<2>. 

Python 3.14.0 release candidate 2

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

Python 3.14.0 release candidate 1

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

Python 3.14.0 beta 4

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

Python 3.14.0 beta 3

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

Python 3.14.0 beta 2

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

Python 3.14.0 beta 1

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

Python 3.14.0 alpha 7

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

Python 3.14.0 alpha 6

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

Python 3.14.0 alpha 5

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

Python 3.14.0 alpha 4

* macOS: macOS<6>. 
* Tools/Demos: Tools/Demos<11>. 
* Tests: Tests<9>. 
* Library: Library<13>. 
* Core and Builtins: Core and Builtins<12>. 
* C API: C API<11>. 
* Build: Build<11>. 

Python 3.14.0 alpha 3

* Windows: Windows<10>. 
* Tools/Demos: Tools/Demos<12>. 
* Tests: Tests<10>. 
* Security: Security<12>. 
* Library: Library<14>. 
* Documentation: Documentation<8>. 
* Core and Builtins: Core and Builtins<13>. 
* C API: C API<12>. 
* Build: Build<12>. 

Python 3.14.0 alpha 2

* Windows: Windows<11>. 
* Tools/Demos: Tools/Demos<13>. 
* Tests: Tests<11>. 
* Security: Security<13>. 
* Library: Library<15>. 
* Documentation: Documentation<9>. 
* Core and Builtins: Core and Builtins<14>. 
* C API: C API<13>. 
* Build: Build<13>. 

Python 3.14.0 alpha 1

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

Python 3.13.0 beta 1

* Security: Security<15>. 
* Core and Builtins: Core and Builtins<16>. 
* Library: Library<17>. 
* Documentation: Documentation<11>. 
* Build: Build<15>. 
* Windows: Windows<13>. 
* macOS: macOS<8>. 
* IDLE: IDLE<7>. 
* C API: C API<15>. 

Python 3.13.0 alpha 6

* Core and Builtins: Core and Builtins<17>. 
* Library: Library<18>. 
* Documentation: Documentation<12>. 
* Tests: Tests<13>. 
* Build: Build<16>. 
* Windows: Windows<14>. 
* C API: C API<16>. 

Python 3.13.0 alpha 5

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

Python 3.13.0 alpha 4

* Security: Security<17>. 
* Core and Builtins: Core and Builtins<19>. 
* Library: Library<20>. 
* Documentation: Documentation<14>. 
* Tests: Tests<15>. 
* Build: Build<18>. 
* Windows: Windows<16>. 
* macOS: macOS<10>. 
* IDLE: IDLE<9>. 
* Tools/Demos: Tools/Demos<16>. 
* C API: C API<18>. 

Python 3.13.0 alpha 3

* Security: Security<18>. 
* Core and Builtins: Core and Builtins<20>. 
* Library: Library<21>. 
* Documentation: Documentation<15>. 
* Tests: Tests<16>. 
* Build: Build<19>. 
* Windows: Windows<17>. 
* macOS: macOS<11>. 
* IDLE: IDLE<10>. 
* C API: C API<19>. 

Python 3.13.0 alpha 2

* Core and Builtins: Core and Builtins<21>. 
* Library: Library<22>. 
* Tests: Tests<17>. 
* Build: Build<20>. 
* Windows: Windows<18>. 
* macOS: macOS<12>. 
* IDLE: IDLE<11>. 
* Tools/Demos: Tools/Demos<17>. 
* C API: C API<20>. 

Python 3.13.0 alpha 1

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

Python 3.12.0 beta 1

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

Python 3.12.0 alpha 7

* Core and Builtins: Core and Builtins<24>. 
* Library: Library<25>. 
* Documentation: Documentation<18>. 
* Tests: Tests<20>. 
* Build: Build<23>. 
* Windows: Windows<21>. 
* Tools/Demos: Tools/Demos<20>. 
* C API: C API<23>. 

Python 3.12.0 alpha 6

* Security: Security<21>. 
* Core and Builtins: Core and Builtins<25>. 
* Library: Library<26>. 
* Documentation: Documentation<19>. 
* Tests: Tests<21>. 
* Build: Build<24>. 
* Windows: Windows<22>. 
* macOS: macOS<15>. 
* C API: C API<24>. 

Python 3.12.0 alpha 5

* Security: Security<22>. 
* Core and Builtins: Core and Builtins<26>. 
* Library: Library<27>. 
* Documentation: Documentation<20>. 
* Tests: Tests<22>. 
* Build: Build<25>. 
* Windows: Windows<23>. 

Python 3.12.0 alpha 4

* Core and Builtins: Core and Builtins<27>. 
* Library: Library<28>. 
* Documentation: Documentation<21>. 
* Tests: Tests<23>. 
* Build: Build<26>. 
* Windows: Windows<24>. 
* macOS: macOS<16>. 
* Tools/Demos: Tools/Demos<21>. 
* C API: C API<25>. 

Python 3.12.0 alpha 3

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

Python 3.12.0 alpha 2

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

Python 3.12.0 alpha 1

* Security: Security<25>. 
* Core and Builtins: Core and Builtins<30>. 
* Library: Library<31>. 
* Documentation: Documentation<24>. 
* Tests: Tests<26>. 
* Build: Build<29>. 
* Windows: Windows<27>. 
* macOS: macOS<19>. 
* IDLE: IDLE<14>. 
* Tools/Demos: Tools/Demos<23>. 
* C API: C API<28>. 

Python 3.11.0 beta 1

* Security: Security<26>. 
* Core and Builtins: Core and Builtins<31>. 
* Library: Library<32>. 
* Documentation: Documentation<25>. 
* Tests: Tests<27>. 
* Build: Build<30>. 
* Windows: Windows<28>. 
* macOS: macOS<20>. 
* Tools/Demos: Tools/Demos<24>. 
* C API: C API<29>. 

Python 3.11.0 alpha 7

* Core and Builtins: Core and Builtins<32>. 
* Library: Library<33>. 
* Documentation: Documentation<26>. 
* Tests: Tests<28>. 
* Build: Build<31>. 
* Windows: Windows<29>. 
* macOS: macOS<21>. 
* Tools/Demos: Tools/Demos<25>. 
* C API: C API<30>. 

Python 3.11.0 alpha 6

* Core and Builtins: Core and Builtins<33>. 
* Library: Library<34>. 
* Documentation: Documentation<27>. 
* Tests: Tests<29>. 
* Build: Build<32>. 
* Windows: Windows<30>. 
* IDLE: IDLE<15>. 
* C API: C API<31>. 

Python 3.11.0 alpha 5

* Core and Builtins: Core and Builtins<34>. 
* Library: Library<35>. 
* Documentation: Documentation<28>. 
* Tests: Tests<30>. 
* Build: Build<33>. 
* Windows: Windows<31>. 
* macOS: macOS<22>. 
* IDLE: IDLE<16>. 
* C API: C API<32>. 

Python 3.11.0 alpha 4

* Core and Builtins: Core and Builtins<35>. 
* Library: Library<36>. 
* Documentation: Documentation<29>. 
* Tests: Tests<31>. 
* Build: Build<34>. 
* Windows: Windows<32>. 
* macOS: macOS<23>. 
* C API: C API<33>. 

Python 3.11.0 alpha 3

* Core and Builtins: Core and Builtins<36>. 
* Library: Library<37>. 
* Documentation: Documentation<30>. 
* Tests: Tests<32>. 
* Build: Build<35>. 
* Windows: Windows<33>. 
* macOS: macOS<24>. 
* C API: C API<34>. 

Python 3.11.0 alpha 2

* Core and Builtins: Core and Builtins<37>. 
* Library: Library<38>. 
* Documentation: Documentation<31>. 
* Tests: Tests<33>. 
* Build: Build<36>. 
* Windows: Windows<34>. 
* macOS: macOS<25>. 
* IDLE: IDLE<17>. 
* C API: C API<35>. 

Python 3.11.0 alpha 1

* Security: Security<27>. 
* Core and Builtins: Core and Builtins<38>. 
* Library: Library<39>. 
* Documentation: Documentation<32>. 
* Tests: Tests<34>. 
* Build: Build<37>. 
* Windows: Windows<35>. 
* macOS: macOS<26>. 
* IDLE: IDLE<18>. 
* Tools/Demos: Tools/Demos<26>. 
* C API: C API<36>. 

Python 3.10.0 beta 1

* Security: Security<28>. 
* Core and Builtins: Core and Builtins<39>. 
* Library: Library<40>. 
* Documentation: Documentation<33>. 
* Tests: Tests<35>. 
* Build: Build<38>. 
* Windows: Windows<36>. 
* macOS: macOS<27>. 
* IDLE: IDLE<19>. 
* C API: C API<37>. 

Python 3.10.0 alpha 7

* Security: Security<29>. 
* Core and Builtins: Core and Builtins<40>. 
* Library: Library<41>. 
* Documentation: Documentation<34>. 
* Tests: Tests<36>. 
* Build: Build<39>. 
* Windows: Windows<37>. 
* IDLE: IDLE<20>. 
* C API: C API<38>. 

Python 3.10.0 alpha 6

* Security: Security<30>. 
* Core and Builtins: Core and Builtins<41>. 
* Library: Library<42>. 
* Documentation: Documentation<35>. 
* Tests: Tests<37>. 
* Build: Build<40>. 
* Windows: Windows<38>. 
* macOS: macOS<28>. 
* IDLE: IDLE<21>. 
* C API: C API<39>. 

Python 3.10.0 alpha 5

* Security: Security<31>. 
* Core and Builtins: Core and Builtins<42>. 
* Library: Library<43>. 
* Documentation: Documentation<36>. 
* Tests: Tests<38>. 
* Build: Build<41>. 
* Windows: Windows<39>. 
* macOS: macOS<29>. 
* IDLE: IDLE<22>. 
* C API: C API<40>. 

Python 3.10.0 alpha 4

* Core and Builtins: Core and Builtins<43>. 
* Library: Library<44>. 
* Documentation: Documentation<37>. 
* Tests: Tests<39>. 
* Build: Build<42>. 
* macOS: macOS<30>. 
* Tools/Demos: Tools/Demos<27>. 
* C API: C API<41>. 

Python 3.10.0 alpha 3

* Security: Security<32>. 
* Core and Builtins: Core and Builtins<44>. 
* Library: Library<45>. 
* Documentation: Documentation<38>. 
* Tests: Tests<40>. 
* Build: Build<43>. 
* Windows: Windows<40>. 
* macOS: macOS<31>. 
* IDLE: IDLE<23>. 
* Tools/Demos: Tools/Demos<28>. 
* C API: C API<42>. 

Python 3.10.0 alpha 2

* Security: Security<33>. 
* Core and Builtins: Core and Builtins<45>. 
* Library: Library<46>. 
* Documentation: Documentation<39>. 
* Tests: Tests<41>. 
* Build: Build<44>. 
* Windows: Windows<41>. 
* macOS: macOS<32>. 
* IDLE: IDLE<24>. 
* C API: C API<43>. 

Python 3.10.0 alpha 1

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

Python 3.9.0 beta 1

* Security: Security<35>. 
* Core and Builtins: Core and Builtins<47>. 
* Library: Library<48>. 
* Documentation: Documentation<41>. 
* Tests: Tests<43>. 
* Build: Build<46>. 
* Windows: Windows<43>. 
* macOS: macOS<34>. 
* Tools/Demos: Tools/Demos<29>. 
* C API: C API<45>. 

Python 3.9.0 alpha 6

* Security: Security<36>. 
* Core and Builtins: Core and Builtins<48>. 
* Library: Library<49>. 
* Documentation: Documentation<42>. 
* Tests: Tests<44>. 
* Build: Build<47>. 
* Windows: Windows<44>. 
* macOS: macOS<35>. 
* IDLE: IDLE<26>. 
* Tools/Demos: Tools/Demos<30>. 
* C API: C API<46>. 

Python 3.9.0 alpha 5

* Security: Security<37>. 
* Core and Builtins: Core and Builtins<49>. 
* Library: Library<50>. 
* Documentation: Documentation<43>. 
* Tests: Tests<45>. 
* Build: Build<48>. 
* Windows: Windows<45>. 
* macOS: macOS<36>. 
* IDLE: IDLE<27>. 
* Tools/Demos: Tools/Demos<31>. 
* C API: C API<47>. 

Python 3.9.0 alpha 4

* Security: Security<38>. 
* Core and Builtins: Core and Builtins<50>. 
* Library: Library<51>. 
* Documentation: Documentation<44>. 
* Tests: Tests<46>. 
* Build: Build<49>. 
* Windows: Windows<46>. 
* IDLE: IDLE<28>. 
* C API: C API<48>. 

Python 3.9.0 alpha 3

* Core and Builtins: Core and Builtins<51>. 
* Library: Library<52>. 
* Documentation: Documentation<45>. 
* Build: Build<50>. 
* IDLE: IDLE<29>. 
* C API: C API<49>. 

Python 3.9.0 alpha 2

* Security: Security<39>. 
* Core and Builtins: Core and Builtins<52>. 
* Library: Library<53>. 
* Documentation: Documentation<46>. 
* Tests: Tests<47>. 
* Build: Build<51>. 
* Windows: Windows<47>. 
* macOS: macOS<37>. 
* IDLE: IDLE<30>. 
* C API: C API<50>. 

Python 3.9.0 alpha 1

* Security: Security<40>. 
* Core and Builtins: Core and Builtins<53>. 
* Library: Library<54>. 
* Documentation: Documentation<47>. 
* Tests: Tests<48>. 
* Build: Build<52>. 
* Windows: Windows<48>. 
* macOS: macOS<38>. 
* IDLE: IDLE<31>. 
* Tools/Demos: Tools/Demos<32>. 
* C API: C API<51>. 

Python 3.8.0 beta 1

* Security: Security<41>. 
* Core and Builtins: Core and Builtins<54>. 
* Library: Library<55>. 
* Documentation: Documentation<48>. 
* Tests: Tests<49>. 
* Build: Build<53>. 
* Windows: Windows<49>. 
* macOS: macOS<39>. 
* IDLE: IDLE<32>. 
* Tools/Demos: Tools/Demos<33>. 
* C API: C API<52>. 

Python 3.8.0 alpha 4

* Security: Security<42>. 
* Core and Builtins: Core and Builtins<55>. 
* Library: Library<56>. 
* Documentation: Documentation<49>. 
* Tests: Tests<50>. 
* Build: Build<54>. 
* Windows: Windows<50>. 
* macOS: macOS<40>. 
* IDLE: IDLE<33>. 
* Tools/Demos: Tools/Demos<34>. 
* C API: C API<53>. 

Python 3.8.0 alpha 3

* Security: Security<43>. 
* Core and Builtins: Core and Builtins<56>. 
* Library: Library<57>. 
* Documentation: Documentation<50>. 
* Tests: Tests<51>. 
* Build: Build<55>. 
* Windows: Windows<51>. 
* IDLE: IDLE<34>. 
* Tools/Demos: Tools/Demos<35>. 
* C API: C API<54>. 

Python 3.8.0 alpha 2

* Core and Builtins: Core and Builtins<57>. 
* Library: Library<58>. 
* Documentation: Documentation<51>. 
* Tests: Tests<52>. 
* Windows: Windows<52>. 
* IDLE: IDLE<35>. 

Python 3.8.0 alpha 1

* Security: Security<44>. 
* Core and Builtins: Core and Builtins<58>. 
* Library: Library<59>. 
* Documentation: Documentation<52>. 
* Tests: Tests<53>. 
* Build: Build<56>. 
* Windows: Windows<53>. 
* macOS: macOS<41>. 
* IDLE: IDLE<36>. 
* Tools/Demos: Tools/Demos<36>. 
* C API: C API<55>. 

Python 3.7.0 final

* Library: Library<60>. 
* C API: C API<56>. 

Python 3.7.0 release candidate 1

* Core and Builtins: Core and Builtins<59>. 
* Library: Library<61>. 
* Documentation: Documentation<53>. 
* Build: Build<57>. 
* Windows: Windows<54>. 
* IDLE: IDLE<37>. 

Python 3.7.0 beta 5

* Core and Builtins: Core and Builtins<60>. 
* Library: Library<62>. 
* Documentation: Documentation<54>. 
* Tests: Tests<54>. 
* Build: Build<58>. 
* macOS: macOS<42>. 
* IDLE: IDLE<38>. 

Python 3.7.0 beta 4

* Core and Builtins: Core and Builtins<61>. 
* Library: Library<63>. 
* Documentation: Documentation<55>. 
* Tests: Tests<55>. 
* Build: Build<59>. 
* Windows: Windows<55>. 
* macOS: macOS<43>. 
* IDLE: IDLE<39>. 
* Tools/Demos: Tools/Demos<37>. 

Python 3.7.0 beta 3

* Security: Security<45>. 
* Core and Builtins: Core and Builtins<62>. 
* Library: Library<64>. 
* Documentation: Documentation<56>. 
* Tests: Tests<56>. 
* Build: Build<60>. 
* Windows: Windows<56>. 
* macOS: macOS<44>. 
* IDLE: IDLE<40>. 
* Tools/Demos: Tools/Demos<38>. 
* C API: C API<57>. 

Python 3.7.0 beta 2

* Security: Security<46>. 
* Core and Builtins: Core and Builtins<63>. 
* Library: Library<65>. 
* Documentation: Documentation<57>. 
* Tests: Tests<57>. 
* Build: Build<61>. 
* Windows: Windows<57>. 
* macOS: macOS<45>. 
* IDLE: IDLE<41>. 
* Tools/Demos: Tools/Demos<39>. 

Python 3.7.0 beta 1

* Core and Builtins: Core and Builtins<64>. 
* Library: Library<66>. 
* Documentation: Documentation<58>. 
* Tests: Tests<58>. 
* Build: Build<62>. 
* Windows: Windows<58>. 
* macOS: macOS<46>. 
* C API: C API<58>. 

Python 3.7.0 alpha 4

* Core and Builtins: Core and Builtins<65>. 
* Library: Library<67>. 
* Documentation: Documentation<59>. 
* Tests: Tests<59>. 
* Windows: Windows<59>. 
* Tools/Demos: Tools/Demos<40>. 
* C API: C API<59>. 

Python 3.7.0 alpha 3

* Core and Builtins: Core and Builtins<66>. 
* Library: Library<68>. 
* Documentation: Documentation<60>. 
* Tests: Tests<60>. 
* Build: Build<63>. 
* Windows: Windows<60>. 
* macOS: macOS<47>. 
* IDLE: IDLE<42>. 
* Tools/Demos: Tools/Demos<41>. 
* C API: C API<60>. 

Python 3.7.0 alpha 2

* Core and Builtins: Core and Builtins<67>. 
* Library: Library<69>. 
* Documentation: Documentation<61>. 
* Build: Build<64>. 
* IDLE: IDLE<43>. 
* C API: C API<61>. 

Python 3.7.0 alpha 1

* Security: Security<47>. 
* Core and Builtins: Core and Builtins<68>. 
* Library: Library<70>. 
* Documentation: Documentation<62>. 
* Tests: Tests<61>. 
* Build: Build<65>. 
* Windows: Windows<61>. 
* IDLE: IDLE<44>. 
* Tools/Demos: Tools/Demos<42>. 
* C API: C API<62>. 

Python 3.6.6 release candidate 1

* Core and Builtins: Core and Builtins<69>. 
* Library: Library<71>. 
* Documentation: Documentation<63>. 
* Tests: Tests<62>. 
* Build: Build<66>. 
* Windows: Windows<62>. 
* macOS: macOS<48>. 
* IDLE: IDLE<45>. 
* Tools/Demos: Tools/Demos<43>. 
* C API: C API<63>. 

Python 3.6.5 final

* Tests: Tests<63>. 
* Build: Build<67>. 

Python 3.6.5 release candidate 1

* Security: Security<48>. 
* Core and Builtins: Core and Builtins<70>. 
* Library: Library<72>. 
* Documentation: Documentation<64>. 
* Tests: Tests<64>. 
* Build: Build<68>. 
* Windows: Windows<63>. 
* macOS: macOS<49>. 
* IDLE: IDLE<46>. 
* Tools/Demos: Tools/Demos<44>. 
* C API: C API<64>. 

Python 3.6.4 release candidate 1

* Core and Builtins: Core and Builtins<71>. 
* Library: Library<73>. 
* Documentation: Documentation<65>. 
* Tests: Tests<65>. 
* Build: Build<69>. 
* Windows: Windows<64>. 
* macOS: macOS<50>. 
* IDLE: IDLE<47>. 
* Tools/Demos: Tools/Demos<45>. 
* C API: C API<65>. 

Python 3.6.3 final

* Library: Library<74>. 
* Build: Build<70>. 

Python 3.6.3 release candidate 1

* Security: Security<49>. 
* Core and Builtins: Core and Builtins<72>. 
* Library: Library<75>. 
* Documentation: Documentation<66>. 
* Tests: Tests<66>. 
* Build: Build<71>. 
* Windows: Windows<65>. 
* IDLE: IDLE<48>. 
* Tools/Demos: Tools/Demos<46>. 

Python 3.6.2 release candidate 2

* Security: Security<50>. 

Python 3.6.2 release candidate 1

* Security: Security<51>. 
* Core and Builtins: Core and Builtins<73>. 
* Library: Library<76>. 
* IDLE: IDLE<49>. 
* C API: C API<66>. 
* Build: Build<72>. 
* Documentation: Documentation<67>. 
* Tools/Demos: Tools/Demos<47>. 
* Tests: Tests<67>. 
* Windows: Windows<66>. 

Python 3.6.1 final

* Core and Builtins: Core and Builtins<74>. 
* Build: Build<73>. 

Python 3.6.1 release candidate 1

* Core and Builtins: Core and Builtins<75>. 
* Library: Library<77>. 
* IDLE: IDLE<50>. 
* Windows: Windows<67>. 
* C API: C API<67>. 
* Documentation: Documentation<68>. 
* Tests: Tests<68>. 
* Build: Build<74>. 

Python 3.6.0 release candidate 2

* Core and Builtins: Core and Builtins<76>. 
* Tools/Demos: Tools/Demos<48>. 
* Windows: Windows<68>. 
* Build: Build<75>. 

Python 3.6.0 release candidate 1

* Core and Builtins: Core and Builtins<77>. 
* Library: Library<78>. 
* C API: C API<68>. 
* Documentation: Documentation<69>. 
* Tools/Demos: Tools/Demos<49>. 

Python 3.6.0 beta 4

* Core and Builtins: Core and Builtins<78>. 
* Library: Library<79>. 
* Documentation: Documentation<70>. 
* Tests: Tests<69>. 
* Build: Build<76>. 

Python 3.6.0 beta 3

* Core and Builtins: Core and Builtins<79>. 
* Library: Library<80>. 
* Windows: Windows<69>. 
* Build: Build<77>. 
* Tests: Tests<70>. 

Python 3.6.0 beta 2

* Core and Builtins: Core and Builtins<80>. 
* Library: Library<81>. 
* Windows: Windows<70>. 
* C API: C API<69>. 
* Build: Build<78>. 
* Tests: Tests<71>. 

Python 3.6.0 beta 1

* Core and Builtins: Core and Builtins<81>. 
* Library: Library<82>. 
* IDLE: IDLE<51>. 
* C API: C API<70>. 
* Tests: Tests<72>. 
* Build: Build<79>. 
* Tools/Demos: Tools/Demos<50>. 
* Windows: Windows<71>. 

Python 3.6.0 alpha 4

* Core and Builtins: Core and Builtins<82>. 
* Library: Library<83>. 
* IDLE: IDLE<52>. 
* Tests: Tests<73>. 
* Windows: Windows<72>. 
* Build: Build<80>. 

Python 3.6.0 alpha 3

* Security: Security<52>. 
* Core and Builtins: Core and Builtins<83>. 
* Library: Library<84>. 
* IDLE: IDLE<53>. 
* C API: C API<71>. 
* Build: Build<81>. 
* Tools/Demos: Tools/Demos<51>. 
* Documentation: Documentation<71>. 
* Tests: Tests<74>. 

Python 3.6.0 alpha 2

* Security: Security<53>. 
* Core and Builtins: Core and Builtins<84>. 
* Library: Library<85>. 
* IDLE: IDLE<54>. 
* Documentation: Documentation<72>. 
* Tests: Tests<75>. 
* Windows: Windows<73>. 
* Build: Build<82>. 
* C API: C API<72>. 
* Tools/Demos: Tools/Demos<52>. 

Python 3.6.0 alpha 1

* Security: Security<54>. 
* Core and Builtins: Core and Builtins<85>. 
* Library: Library<86>. 
* IDLE: IDLE<55>. 
* Documentation: Documentation<73>. 
* Tests: Tests<76>. 
* Build: Build<83>. 
* Windows: Windows<74>. 
* Tools/Demos: Tools/Demos<53>. 
* C API: C API<73>. 

Python 3.5.5 release candidate 1

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

Python 3.5.4 final

* Library: Library<88>. 

Python 3.5.4 release candidate 1

* Security: Security<56>. 
* Core and Builtins: Core and Builtins<87>. 
* Library: Library<89>. 
* Documentation: Documentation<74>. 
* Tests: Tests<77>. 
* Build: Build<84>. 
* Windows: Windows<75>. 
* C API: C API<74>. 

Python 3.5.3 release candidate 1

* Security: Security<57>. 
* Core and Builtins: Core and Builtins<88>. 
* Library: Library<90>. 
* IDLE: IDLE<56>. 
* C API: C API<75>. 
* Documentation: Documentation<75>. 
* Tests: Tests<78>. 
* Tools/Demos: Tools/Demos<54>. 
* Windows: Windows<76>. 
* Build: Build<85>. 

Python 3.5.2 final

* Core and Builtins: Core and Builtins<89>. 
* Tests: Tests<79>. 
* IDLE: IDLE<57>. 

Python 3.5.2 release candidate 1

* Security: Security<58>. 
* Core and Builtins: Core and Builtins<90>. 
* Library: Library<91>. 
* IDLE: IDLE<58>. 
* Documentation: Documentation<76>. 
* Tests: Tests<80>. 
* Build: Build<86>. 
* Windows: Windows<77>. 
* Tools/Demos: Tools/Demos<55>. 

Python 3.5.1 final

* Core and Builtins: Core and Builtins<91>. 
* Windows: Windows<78>. 

Python 3.5.1 release candidate 1

* Core and Builtins: Core and Builtins<92>. 
* Library: Library<92>. 
* IDLE: IDLE<59>. 
* Documentation: Documentation<77>. 
* Tests: Tests<81>. 
* Build: Build<87>. 
* Windows: Windows<79>. 
* Tools/Demos: Tools/Demos<56>. 

Python 3.5.0 final

* Build: Build<88>. 

Python 3.5.0 release candidate 4

* Library: Library<93>. 
* Build: Build<89>. 

Python 3.5.0 release candidate 3

* Core and Builtins: Core and Builtins<93>. 
* Library: Library<94>. 

Python 3.5.0 release candidate 2

* Core and Builtins: Core and Builtins<94>. 
* Library: Library<95>. 

Python 3.5.0 release candidate 1

* Core and Builtins: Core and Builtins<95>. 
* Library: Library<96>. 
* IDLE: IDLE<60>. 
* Documentation: Documentation<78>. 
* Tests: Tests<82>. 

Python 3.5.0 beta 4

* Core and Builtins: Core and Builtins<96>. 
* Library: Library<97>. 
* Build: Build<90>. 

Python 3.5.0 beta 3

* Core and Builtins: Core and Builtins<97>. 
* Library: Library<98>. 
* Tests: Tests<83>. 
* Documentation: Documentation<79>. 
* Build: Build<91>. 

Python 3.5.0 beta 2

* Core and Builtins: Core and Builtins<98>. 
* Library: Library<99>. 

Python 3.5.0 beta 1

* Core and Builtins: Core and Builtins<99>. 
* Library: Library<100>. 
* IDLE: IDLE<61>. 
* Tests: Tests<84>. 
* Documentation: Documentation<80>. 
* Tools/Demos: Tools/Demos<57>. 

Python 3.5.0 alpha 4

* Core and Builtins: Core and Builtins<100>. 
* Library: Library<101>. 
* Build: Build<92>. 
* Tests: Tests<85>. 
* Tools/Demos: Tools/Demos<58>. 
* C API: C API<76>. 

Python 3.5.0 alpha 3

* Core and Builtins: Core and Builtins<101>. 
* Library: Library<102>. 
* Build: Build<93>. 
* Tests: Tests<86>. 
* Tools/Demos: Tools/Demos<59>. 

Python 3.5.0 alpha 2

* Core and Builtins: Core and Builtins<102>. 
* Library: Library<103>. 
* Build: Build<94>. 
* C API: C API<77>. 
* Windows: Windows<80>. 

Python 3.5.0 alpha 1

* Core and Builtins: Core and Builtins<103>. 
* Library: Library<104>. 
* IDLE: IDLE<62>. 
* Build: Build<95>. 
* C API: C API<78>. 
* Documentation: Documentation<81>. 
* Tests: Tests<87>. 
* Tools/Demos: Tools/Demos<60>. 
* Windows: Windows<81>. 

Python 教學

* 淺嘗滋味:: 
* 使用 Python 直譯器:: 
* 一個非正式的 Python 簡介:: 
* 深入了解流程控制:: 
* 資料結構:: 
* 模組 (Module): 模組 Module. 
* 輸入和輸出:: 
* 錯誤和例外:: 
* Class（類別）:: 
* Python 標準函式庫概覽:: 
* Python 標準函式庫概覽——第二部份:: 
* 虛擬環境與套件:: 
* 現在可以來學習些什麼？:: 
* 互動式輸入編輯和歷史記錄替換:: 
* 浮點數運算：問題與限制:: 
* 附錄:: 

使用 Python 直譯器

* 啟動直譯器:: 
* 直譯器與它的環境:: 

啟動直譯器

* 傳遞引數:: 
* 互動模式:: 

直譯器與它的環境

* 原始碼的字元編碼 (encoding): 原始碼的字元編碼 encoding. 

一個非正式的 Python 簡介

* 把 Python 當作計算機使用:: 
* 初探程式設計的前幾步:: 

把 Python 當作計算機使用

* 數字 (Number): 數字 Number. 
* 文字:: 
* List（串列）:: 

深入了解流程控制

* if 陳述式:: 
* for 陳述式:: 
* range() 函式: range 函式. 
* break 和 continue 陳述式:: 
* 迴圈的 else 子句:: 
* pass 陳述式:: 
* match 陳述式:: 
* 定義函式 (function): 定義函式 function. 
* 深入了解函式定義:: 
* 間奏曲：程式碼風格 (Coding Style): 間奏曲：程式碼風格 Coding Style. 

深入了解函式定義

* 預設引數值:: 
* 關鍵字引數:: 
* 特殊參數:: 
* 任意引數列表 (Arbitrary Argument Lists): 任意引數列表 Arbitrary Argument Lists. 
* 拆解引數列表（Unpacking Argument Lists）:: 
* Lambda 運算式:: 
* 說明文件字串 (Documentation Strings): 說明文件字串 Documentation Strings. 
* 函式註釋 (Function Annotations): 函式註釋 Function Annotations. 

特殊參數

* 位置或關鍵字引數 (Positional-or-Keyword Arguments): 位置或關鍵字引數 Positional-or-Keyword Arguments. 
* 僅限位置參數 (Positional-Only Parameters): 僅限位置參數 Positional-Only Parameters. 
* 僅限關鍵字引數 (Keyword-Only Arguments): 僅限關鍵字引數 Keyword-Only Arguments. 
* 函式範例:: 
* 回顧:: 

資料結構

* 進一步了解 List（串列）:: 
* del 陳述式:: 
* Tuples 和序列 (Sequences): Tuples 和序列 Sequences. 
* 集合 (Sets): 集合 Sets. 
* 字典（Dictionary）:: 
* 迴圈技巧:: 
* 深入了解條件 (Condition): 深入了解條件 Condition. 
* 序列和其他資料類型之比較:: 

進一步了解 List（串列）

* 將 List 作為 Stack（堆疊）使用:: 
* 將 List 作為 Queue（佇列）使用:: 
* List Comprehensions（串列綜合運算）:: 
* 巢狀的 List Comprehensions:: 

模組 (Module)

* 深入了解模組:: 
* 標準模組:: 
* dir() 函式: dir 函式. 
* 套件 (Package): 套件 Package. 

深入了解模組

* 把模組當作腳本執行:: 
* 模組的搜尋路徑:: 
* 「編譯」Python 檔案:: 

套件 (Package)

* 從套件中 import *:: 
* 套件內引用:: 
* 多目錄中的套件:: 

輸入和輸出

* 更華麗的輸出格式:: 
* 讀寫檔案:: 

更華麗的輸出格式

* 格式化的字串文本 (Formatted String Literals): 格式化的字串文本 Formatted String Literals. 
* 字串的 format() method: 字串的 format method. 
* 手動格式化字串:: 
* 格式化字串的舊方法:: 

讀寫檔案

* 檔案物件的 method:: 
* 使用 json 儲存結構化資料:: 

錯誤和例外

* 語法錯誤 (Syntax Error): 語法錯誤 Syntax Error. 
* 例外 (Exception): 例外 Exception. 
* 處理例外:: 
* 引發例外:: 
* 例外鏈接 (Exception Chaining): 例外鏈接 Exception Chaining. 
* 使用者自定的例外:: 
* 定義清理動作:: 
* 預定義的清理動作:: 
* 引發及處理多個無關的例外:: 
* 用註解使例外更詳細:: 

Class（類別）

* 關於名稱與物件的一段話:: 
* Python 作用域 (Scope) 及命名空間 (Namespace): Python 作用域 Scope 及命名空間 Namespace. 
* 初見 class:: 
* 隨意的備註:: 
* 繼承 (Inheritance): 繼承 Inheritance. 
* 私有變數:: 
* 補充說明:: 
* 疊代器 (Iterator): 疊代器 Iterator. 
* 產生器 (Generator): 產生器 Generator. 
* 產生器運算式:: 

Python 作用域 (Scope) 及命名空間 (Namespace)

* 作用域和命名空間的範例:: 

初見 class

* Class definition（類別定義）語法:: 
* Class 物件:: 
* 實例物件:: 
* Method 物件:: 
* Class 及實例變數:: 

繼承 (Inheritance)

* 多重繼承:: 

Python 標準函式庫概覽

* 作業系統介面:: 
* 檔案之萬用字元 (File Wildcards): 檔案之萬用字元 File Wildcards. 
* 命令列引數:: 
* 錯誤輸出重新導向與程式終止:: 
* 字串樣式比對:: 
* 數學相關:: 
* 網路存取:: 
* 日期與時間:: 
* 資料壓縮:: 
* 效能量測:: 
* 品質控管:: 
* 標準模組庫:: 

Python 標準函式庫概覽——第二部份

* 輸出格式化 (Output Formatting): 輸出格式化 Output Formatting. 
* 模板化 (Templating): 模板化 Templating. 
* 二進制資料記錄編排 (Binary Data Record Layouts): 二進制資料記錄編排 Binary Data Record Layouts. 
* 多執行緒 (Multi-threading): 多執行緒 Multi-threading. 
* 日誌記錄 (Logging): 日誌記錄 Logging. 
* 弱引用 (Weak References): 弱引用 Weak References. 
* 使用於 List 的工具:: 
* 十進制浮點數運算 (Decimal Floating-Point Arithmetic): 十進制浮點數運算 Decimal Floating-Point Arithmetic. 

虛擬環境與套件

* 簡介: 簡介<4>. 
* 建立虛擬環境:: 
* 用 pip 管理套件:: 

互動式輸入編輯和歷史記錄替換

* Tab 鍵自動完成 (Tab Completion) 和歷史記錄編輯 (History Editing): Tab 鍵自動完成 Tab Completion 和歷史記錄編輯 History Editing. 
* 互動式直譯器的替代方案:: 

浮點數運算：問題與限制

* 表示法誤差 (Representation Error): 表示法誤差 Representation Error. 

附錄

* 互動模式: 互動模式<2>. 

互動模式

* 錯誤處理:: 
* 可執行的 Python 腳本:: 
* 互動式啟動檔案:: 
* 客製化模組:: 

Python 的設置與使用

* 命令列與環境:: 
* 在 Unix 平臺上使用 Python:: 
* 配置 Python:: 
* 在 Windows 上使用 Python:: 
* 於 macOS 使用 Python:: 
* 在 Android 上使用 Python:: 
* 在 iOS 上使用 Python:: 
* 編輯器與 IDE:: 

命令列與環境

* 命令列:: 
* 環境變數:: 

命令列

* 介面選項:: 
* Generic options:: 
* Miscellaneous options:: 
* Controlling color:: 

環境變數

* 除錯模式變數:: 

在 Unix 平臺上使用 Python

* 獲得並安裝 Python 的最新版本:: 
* 建置 Python:: 
* 與 Python 相關的路徑和檔案:: 
* 雜項: 雜項<2>. 
* 客製化 OpenSSL:: 

獲得並安裝 Python 的最新版本

* 在 Linux 上:: 
* 在 FreeBSD 和 OpenBSD 上:: 

在 Linux 上

* 安裝 IDLE:: 

配置 Python

* 建置需求:: 
* 產生的檔案:: 
* 設定選項:: 
* Python 建置系統:: 
* Compiler and linker flags:: 

產生的檔案

* 設定腳本:: 

設定選項

* 一般選項:: 
* C 編譯器選項。:: 
* Linker options:: 
* Options for third-party dependencies:: 
* WebAssembly 選項:: 
* 安裝選項:: 
* 效能選項:: 
* Python Debug Build:: 
* 偵錯選項:: 
* Linker options: Linker options<2>. 
* 函式庫選項:: 
* 安全性選項:: 
* macOS 選項:: 
* iOS 選項:: 
* Cross Compiling Options:: 

Python 建置系統

* 建置系統的主要檔案:: 
* 主要建置步驟:: 
* 主要 Makefile 目標:: 
* C 擴充模組:: 

主要 Makefile 目標

* 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

* 預處理器旗標:: 
* 編譯器旗標:: 
* Linker flags:: 

在 Windows 上使用 Python

* Python 安裝管理員:: 
* The embeddable package:: 
* nuget.org 套件: nuget org 套件. 
* Alternative bundles:: 
* Supported Windows versions:: 
* Removing the MAX_PATH limitation:: 
* UTF-8 模式:: 
* 找尋模組:: 
* 額外的模組:: 
* 編譯 Python 在 Windows:: 
* The full installer (deprecated): The full installer deprecated. 
* Python launcher for Windows (deprecated): Python launcher for Windows deprecated. 

Python 安裝管理員

* 安裝:: 
* 基本使用:: 
* Command help:: 
* 列出 runtimes:: 
* 安裝 runtimes:: 
* 離線安裝:: 
* 解除安裝 runtimes:: 
* 設定:: 
* Shebang lines:: 
* 進階安裝:: 
* Administrative configuration:: 
* Installing free-threaded binaries:: 
* Troubleshooting:: 

The embeddable package

* Python 應用程式:: 
* 嵌入 Python:: 

nuget.org 套件

* Free-threaded packages:: 

額外的模組

* PyWin32:: 
* cx_Freeze:: 

The full installer (deprecated)

* 安裝步驟:: 
* Removing the MAX_PATH limitation: Removing the MAX_PATH limitation<2>. 
* 無使用者介面安裝:: 
* 無下載安裝:: 
* Modifying an install:: 
* Installing free-threaded binaries: Installing free-threaded binaries<2>. 

Python launcher for Windows (deprecated)

* 開始:: 
* Shebang lines: Shebang lines<2>. 
* Arguments in shebang lines:: 
* Customization:: 
* Diagnostics:: 
* Dry run:: 
* 安裝隨選:: 
* Return codes:: 

開始

* From the command-line:: 
* 虛擬環境（Virtual environment）:: 
* From a script:: 
* 從檔案關聯:: 

Customization

* Customization via INI files:: 
* Customizing default Python versions:: 

於 macOS 使用 Python

* Using Python for macOS from python.org: Using Python for macOS from python org. 
* Alternative Distributions:: 
* 安裝額外的 Python 套件:: 
* 開發 GUI 程式:: 
* 進階主題:: 
* 其他資源:: 

Using Python for macOS from python.org

* 安裝步驟: 安裝步驟<2>. 
* 如何執行 Python 腳本:: 

進階主題

* Installing Free-threaded Binaries:: 
* 使用命令列安裝:: 
* 發行 Python 應用程式:: 
* App Store Compliance:: 

在 Android 上使用 Python

* 將 Python 加入 Android 應用程式:: 
* 建置用於 Android 的 Python 套件:: 

在 iOS 上使用 Python

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

Python at runtime on iOS

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

Installing Python on iOS

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

App Store Compliance

* Incompatible code in the standard library:: 
* Privacy manifests:: 

編輯器與 IDE

* IDLE: IDLE --- Python 編輯器與 shell. Python 編輯器與 shell
* 其他編輯器與 IDE:: 

Python 語言參考手冊

* 簡介: 簡介<5>. 
* 詞法分析:: 
* 資料模型:: 
* 執行模型:: 
* 模組引入系統:: 
* 運算式:: 
* 簡單陳述式:: 
* 複合陳述式:: 
* 最高層級元件:: 
* 完整的語法規格書:: 

簡介

* Alternate Implementations:: 
* Notation:: 

Notation

* 詞法和語法定義:: 

詞法分析

* Line structure:: 
* Other tokens:: 
* Names (identifiers and keywords): Names identifiers and keywords. 
* Literals:: 
* String and Bytes literals:: 
* Numeric literals:: 
* Operators and delimiters:: 

Line structure

* Logical lines:: 
* Physical lines:: 
* Comments:: 
* Encoding declarations:: 
* Explicit line joining:: 
* Implicit line joining:: 
* Blank lines:: 
* Indentation:: 
* Whitespace between tokens:: 
* End marker:: 

Names (identifiers and keywords)

* 關鍵字:: 
* 軟關鍵字:: 
* Reserved classes of identifiers:: 

String and Bytes literals

* 三引號字串:: 
* String prefixes:: 
* Formal grammar:: 
* 跳脫序列:: 
* 位元組常數:: 
* 原始字串常數:: 
* f-string（f 字串）:: 
* t-string（t 字串）:: 

跳脫序列

* Ignored end of line:: 
* 跳脫字元:: 
* 八進位字元:: 
* 十六進位字元:: 
* Named Unicode character:: 
* 十六進位 Unicode 字元:: 
* 無法辨識的跳脫序列:: 

Numeric literals

* Integer literals:: 
* 浮點數常數 (Floating-point literals): 浮點數常數 Floating-point literals. 
* Imaginary literals:: 

資料模型

* 物件、數值和型別:: 
* 標準型別階層:: 
* Special method names:: 
* 協程:: 

標準型別階層

* None:: 
* NotImplemented:: 
* Ellipsis:: 
* numbers.Number: numbers Number. 
* Sequences:: 
* Set（集合）型別:: 
* 對映:: 
* 可呼叫型別:: 
* 模組: 模組<2>. 
* Custom classes:: 
* 類別實例: 類別實例<2>. 
* I/O objects (also known as file objects): I/O objects also known as file objects. 
* Internal types:: 

numbers.Number

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

Sequences

* Immutable sequences:: 
* 可變序列:: 

對映

* 字典:: 

可呼叫型別

* 自訂函式:: 
* 實例方法:: 
* 產生器函式:: 
* Coroutine（協程）函式:: 
* 非同步產生器函式:: 
* 內建函式:: 
* 內建方法:: 
* Classes:: 
* 類別實例:: 

自訂函式

* 特殊唯讀屬性:: 
* 特殊可寫屬性:: 

模組

* Import-related attributes on module objects:: 
* 模組物件的其他可寫入屬性:: 
* 模組字典:: 

Custom classes

* 特殊屬性:: 
* 特殊方法:: 

類別實例

* 特殊屬性: 特殊屬性<2>. 

Internal types

* 程式碼物件:: 
* Frame objects:: 
* Traceback objects:: 
* Slice objects:: 
* Static method objects:: 
* Class method objects:: 

程式碼物件

* 特殊唯讀屬性: 特殊唯讀屬性<2>. 
* 用於程式碼物件的方法:: 

Frame objects

* 特殊唯讀屬性: 特殊唯讀屬性<3>. 
* 特殊可寫屬性: 特殊可寫屬性<2>. 
* Frame object methods:: 

Special method names

* Basic customization:: 
* Customizing attribute access:: 
* Customizing class creation:: 
* Customizing instance and subclass checks:: 
* Emulating generic types:: 
* Emulating callable objects:: 
* Emulating container types:: 
* Emulating numeric types:: 
* With 陳述式的情境管理器:: 
* Customizing positional arguments in class pattern matching:: 
* Emulating buffer types:: 
* Annotations:: 
* Special method lookup:: 

Customizing attribute access

* Customizing module attribute access:: 
* 實作描述器:: 
* Invoking Descriptors:: 
* __slots__: __slots__<2>. 

Customizing class creation

* Metaclasses:: 
* Resolving MRO entries:: 
* Determining the appropriate metaclass:: 
* Preparing the class namespace:: 
* Executing the class body:: 
* Creating the class object:: 
* Uses for metaclasses:: 

Emulating generic types

* The purpose of __class_getitem__:: 
* __class_getitem__ versus __getitem__:: 

協程

* Awaitable Objects:: 
* 協程物件:: 
* Asynchronous Iterators:: 
* Asynchronous Context Managers:: 

執行模型

* Structure of a program:: 
* Naming and binding:: 
* 例外:: 
* Runtime Components:: 

Naming and binding

* Binding of names:: 
* Resolution of names:: 
* 註釋作用域 (annotation scopes): 註釋作用域 annotation scopes. 
* Lazy evaluation:: 
* Builtins and restricted execution:: 
* Interaction with dynamic features:: 

Runtime Components

* General Computing Model:: 
* Python Runtime Model:: 

模組引入系統

* importlib: importlib<10>. 
* 套件:: 
* 搜尋:: 
* 載入:: 
* The Path Based Finder:: 
* Replacing the standard import system:: 
* Package Relative Imports:: 
* Special considerations for __main__:: 
* References:: 

套件

* 一般套件:: 
* 命名空間套件:: 

搜尋

* 模組快取:: 
* 尋檢器 (Finder) 與載入器 (Loader): 尋檢器 Finder 與載入器 Loader. 
* 引入掛鉤 (Import hooks): 引入掛鉤 Import hooks. 
* 元路徑:: 

載入

* 載入器:: 
* 子模組:: 
* 模組規格:: 
* __path__ attributes on modules:: 
* Module reprs:: 
* Cached bytecode invalidation:: 

The Path Based Finder

* Path entry finders:: 
* Path entry finder protocol:: 

Special considerations for __main__

* __main__.__spec__: __main__ __spec__. 

運算式

* 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

* Identifiers (Names): Identifiers Names. 
* Literals: Literals<2>. 
* 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

* String literal concatenation:: 

Yield expressions

* Generator-iterator methods:: 
* 模組: 模組<3>. 
* 非同步產生器函式: 非同步產生器函式<2>. 
* Asynchronous generator-iterator methods:: 

Primaries

* Attribute references:: 
* Subscriptions:: 
* Slicings:: 
* Calls:: 

Comparisons

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

簡單陳述式

* Expression statements:: 
* Assignment statements:: 
* assert 陳述式:: 
* pass 陳述式: pass 陳述式<2>. 
* del 陳述式: del 陳述式<2>. 
* return 陳述式:: 
* yield 陳述式:: 
* raise 陳述式:: 
* break 陳述式:: 
* continue 陳述式:: 
* import 陳述式:: 
* global 陳述式:: 
* nonlocal 陳述式:: 
* type 陳述式:: 

Assignment statements

* 擴增賦值陳述式:: 
* 註釋賦值陳述式:: 

import 陳述式

* Future statements:: 

複合陳述式

* if 陳述式: if 陳述式<2>. 
* while 陳述式:: 
* for 陳述式: for 陳述式<2>. 
* try 陳述式:: 
* with 陳述式:: 
* match 陳述式: match 陳述式<2>. 
* 函式定義:: 
* 類別定義:: 
* 協程: 協程<2>. 
* Type parameter lists:: 
* 註釋:: 

try 陳述式

* except 子句:: 
* except* 子句:: 
* else 子句:: 
* finally 子句:: 

match 陳述式

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

協程

* 協程函式定義:: 
* async for 陳述式:: 
* async with 陳述式:: 

Type parameter lists

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

最高層級元件

* 完整的 Python 程式:: 
* 檔案輸入:: 
* 互動式輸入:: 
* 運算式輸入:: 

Python 標準函式庫 (Standard Library)

* 簡介: 簡介<6>. 
* 內建函式: 內建函式<2>. 
* 內建常數:: 
* 內建型別:: 
* 內建的例外:: 
* 文本處理 (Text Processing) 服務: 文本處理 Text Processing 服務. 
* 二進位資料服務:: 
* 資料型別:: 
* 數值與數學模組:: 
* 函式程式設計模組:: 
* 檔案與目錄存取:: 
* 資料持久性 (Data Persistence): 資料持久性 Data Persistence. 
* 資料壓縮與保存:: 
* 檔案格式:: 
* 加密服務:: 
* 通用作業系統服務:: 
* 命令列介面函式庫:: 
* 並行執行 (Concurrent Execution): 並行執行 Concurrent Execution. 
* 網路與行程間通訊:: 
* 網際網路資料處理:: 
* 結構化標記處理工具:: 
* 網路協定 (Internet protocols) 及支援: 網路協定 Internet protocols 及支援. 
* 多媒體服務:: 
* 國際化:: 
* 以 Tk 打造圖形使用者介面 (Graphical User Interfaces): 以 Tk 打造圖形使用者介面 Graphical User Interfaces. 
* 開發工具:: 
* 除錯與效能分析:: 
* 軟體封裝與發布:: 
* Python Runtime 服務:: 
* 自訂 Python 直譯器:: 
* 引入模組:: 
* Python 語言服務:: 
* MS Windows 特有服務:: 
* Unix 特有服務:: 
* 模組命令列介面:: 
* 已被取代的模組:: 
* 已移除的模組:: 
* 安全性注意事項: 安全性注意事項<4>. 

簡介

* 可用性之標註:: 

可用性之標註

* WebAssembly 平台:: 
* 行動平台:: 

內建常數

* 由 site module（模組）所添增的常數:: 

內建型別

* 真值檢測:: 
* Boolean（布林）運算: Boolean（布林）運算 --- and or not. and, or, not
* 比較運算:: 
* 數值型別: 數值型別 --- int、float、complex. int、float、complex
* Boolean 型別 - bool:: 
* 疊代器型別:: 
* Sequence Types: Sequence Types --- list tuple range. list, tuple, range
* Text and Binary Sequence Type Methods Summary:: 
* Text Sequence Type: Text Sequence Type --- str. str
* Binary Sequence Types: Binary Sequence Types --- bytes bytearray memoryview. bytes, bytearray, memoryview
* Set Types: Set Types --- set frozenset. set, frozenset
* Mapping Types: Mapping Types --- dict. dict
* 情境管理器型別:: 
* 型別註釋的型別: 型別註釋的型別 --- 泛型別名 Generic Alias 、聯合 Union. 泛型別名 (Generic Alias)、聯合 (Union)
* 其他內建型別:: 
* 特殊屬性: 特殊屬性<3>. 
* Integer string conversion length limitation:: 

數值型別 --- int、float、complex

* 整數型別的位元運算:: 
* 整數型別的附加方法:: 
* 浮點數的附加方法:: 
* 複數的附加方法:: 
* 數值型別的雜湊:: 

疊代器型別

* Generator Types:: 

Sequence Types --- list, tuple, range

* Common Sequence Operations:: 
* 不可變序列型別:: 
* 可變序列型別:: 
* List（串列）: List（串列）<2>. 
* Tuples:: 
* Ranges:: 

Text Sequence Type --- str

* 字串方法:: 
* Formatted String Literals (f-strings): Formatted String Literals f-strings. 
* printf-style String Formatting:: 

Binary Sequence Types --- bytes, bytearray, memoryview

* Bytes Objects:: 
* Bytearray 物件:: 
* Bytes 和 Bytearray 的操作:: 
* printf-style Bytes Formatting:: 
* Memory Views:: 

Mapping Types --- dict

* 字典視圖物件:: 

型別註釋的型別 --- 泛型別名 (Generic Alias)、聯合 (Union)

* 泛型別名型別:: 
* 聯合型別 (Union Type): 聯合型別 Union Type. 

泛型別名型別

* 標準泛型類別:: 
* GenericAlias 物件的特殊屬性:: 

其他內建型別

* 模組: 模組<4>. 
* 類別與類別實例:: 
* 函式:: 
* 方法:: 
* 程式碼物件: 程式碼物件<2>. 
* Type Objects:: 
* Null 物件:: 
* Ellipsis 物件:: 
* NotImplemented 物件:: 
* 內部物件:: 

Integer string conversion length limitation

* 受影響的 API:: 
* 設定限制:: 
* 建議的配置:: 

內建的例外

* 例外的情境:: 
* 繼承自內建的例外:: 
* 基底類別 (base classes): 基底類別 base classes. 
* 實體例外:: 
* 警告:: 
* 例外群組:: 
* 例外階層:: 

實體例外

* 作業系統例外:: 

文本處理 (Text Processing) 服務

* string: string --- 常見的字串操作. 常見的字串操作
* string.templatelib: string templatelib --- 對模板字串字面值的支援. 對模板字串字面值的支援
* re: re --- 正規表示式 regular expression 操作. 正規表示式 (regular expression) 操作
* difflib: difflib --- 計算差異的輔助工具. 計算差異的輔助工具
* textwrap: textwrap --- 文字包裝與填充. 文字包裝與填充
* unicodedata: unicodedata --- Unicode 資料庫. Unicode 資料庫
* stringprep: stringprep --- 網際網路字串的準備. 網際網路字串的準備
* readline: readline --- GNU readline 介面. GNU readline 介面
* rlcompleter: rlcompleter --- GNU readline 的補全函式. GNU readline 的補全函式

string --- 常見的字串操作

* 字串常數:: 
* 自訂字串格式:: 
* 格式化文字語法:: 
* 模板字串 ($-strings): 模板字串 $-strings. 
* 輔助函式:: 

格式化文字語法

* 格式規格 (Format Specification) 迷你語言: 格式規格 Format Specification 迷你語言. 
* 格式範例:: 

string.templatelib --- 對模板字串字面值的支援

* 模板字串:: 
* Types:: 
* Helper functions:: 

re --- 正規表示式 (regular expression) 操作

* 正規表示式語法:: 
* 模組內容:: 
* Regular Expression Objects:: 
* Match Objects:: 
* Regular Expression Examples:: 

模組內容

* 旗標:: 
* 函式: 函式<2>. 
* 例外: 例外<2>. 

Regular Expression Examples

* Checking for a Pair:: 
* 模擬 scanf(): 模擬 scanf. 
* search() vs. match(): search vs match. 
* Making a Phonebook:: 
* Text Munging:: 
* Finding all Adverbs:: 
* Finding all Adverbs and their Positions:: 
* Raw String Notation:: 
* Writing a Tokenizer:: 

difflib --- 計算差異的輔助工具

* SequenceMatcher 物件:: 
* SequenceMatcher 範例:: 
* Differ Objects:: 
* Differ Example:: 
* difflib 的命令列介面:: 
* ndiff 範例：:: 

readline --- GNU readline 介面

* Init file:: 
* Line buffer:: 
* History file:: 
* History list:: 
* Startup hooks:: 
* Completion:: 
* 範例:: 

二進位資料服務

* struct: struct --- 將位元組直譯為打包起來的二進位資料. 將位元組直譯為打包起來的二進位資料
* codecs: codecs --- 編解碼器註冊表和基底類別. 編解碼器註冊表和基底類別

struct --- 將位元組直譯為打包起來的二進位資料

* 函式與例外:: 
* 格式字串:: 
* 應用:: 
* 類別:: 

格式字串

* 位元組順序、大小和對齊:: 
* 格式字元:: 
* 範例: 範例<2>. 

應用

* 原生格式:: 
* 標準格式:: 

codecs --- 編解碼器註冊表和基底類別

* Codec Base Classes:: 
* 編碼和 Unicode:: 
* 標準編碼:: 
* Python Specific Encodings:: 
* encodings: encodings --- Encodings package. Encodings package
* encodings.idna: encodings idna --- Internationalized Domain Names in Applications. Internationalized Domain Names in Applications
* encodings.mbcs: encodings mbcs --- Windows ANSI 碼頁. Windows ANSI 碼頁
* encodings.utf_8_sig: encodings utf_8_sig --- UTF-8 codec with BOM signature. UTF-8 codec with BOM signature

Codec Base Classes

* Error Handlers:: 
* Stateless Encoding and Decoding:: 
* Incremental Encoding and Decoding:: 
* 串流編碼和解碼:: 

Incremental Encoding and Decoding

* IncrementalEncoder 物件:: 
* IncrementalDecoder 物件:: 

串流編碼和解碼

* StreamWriter 物件:: 
* StreamReader 物件:: 
* StreamReaderWriter 物件:: 
* StreamRecoder 物件:: 

Python Specific Encodings

* Text Encodings:: 
* Binary Transforms:: 
* Standalone Codec Functions:: 
* Text Transforms:: 

資料型別

* datetime: datetime --- 日期與時間的基本型別. 日期與時間的基本型別
* zoneinfo: zoneinfo --- IANA 時區支援. IANA 時區支援
* calendar: calendar --- 日曆相關函式. 日曆相關函式
* collections: collections --- 容器資料型態. 容器資料型態
* collections.abc: collections abc --- 容器的抽象基底類別. 容器的抽象基底類別
* heapq: heapq --- 堆積佇列 heap queue 演算法. 堆積佇列 (heap queue) 演算法
* bisect: bisect --- 陣列二分演算法 Array bisection algorithm. 陣列二分演算法 (Array bisection algorithm)
* array: array --- 高效率的數值型陣列. 高效率的數值型陣列
* weakref: weakref --- 弱參照. 弱參照
* types: types --- 動態型別建立與內建型別名稱. 動態型別建立與內建型別名稱
* copy: copy --- 淺層 shallow 和深層 deep 複製操作. 淺層 (shallow) 和深層 (deep) 複製操作
* pprint: pprint --- 資料美化列印器. 資料美化列印器
* reprlib: reprlib --- repr 的替代實作. repr() 的替代實作
* enum: enum --- 對列舉的支援. 對列舉的支援
* graphlib —-- 使用類圖 (graph-like) 結構進行操作的功能: graphlib —-- 使用類圖 graph-like 結構進行操作的功能. 

datetime --- 日期與時間的基本型別

* Aware and Naive Objects:: 
* 常數:: 
* Available Types:: 
* timedelta 物件:: 
* date 物件:: 
* datetime 物件:: 
* time 物件:: 
* tzinfo 物件:: 
* timezone 物件:: 
* strftime() 與 strptime() 的行為: strftime 與 strptime 的行為. 

Available Types

* 常見屬性:: 
* Determining if an Object is Aware or Naive:: 

timedelta 物件

* 用法範例：timedelta:: 

date 物件

* 用法範例：date:: 

datetime 物件

* 用法範例：datetime:: 

time 物件

* 用法範例：time:: 

strftime() 與 strptime() 的行為

* strftime() 與 strptime() 格式碼: strftime 與 strptime 格式碼. 
* 技術細節:: 

zoneinfo --- IANA 時區支援

* 使用 ZoneInfo:: 
* 資料來源:: 
* ZoneInfo 類別:: 
* 函式: 函式<3>. 
* 全域變數:: 
* 例外與警告:: 

資料來源

* 設定資料來源:: 

設定資料來源

* 編譯時期設定:: 
* 環境設定:: 
* Runtime 設定:: 

ZoneInfo 類別

* 字串表示:: 
* 封裝（Pickle）序列化:: 

calendar --- 日曆相關函式

* 命令列用法:: 

collections --- 容器資料型態

* ChainMap 物件:: 
* Counter 物件:: 
* deque 物件:: 
* defaultdict 物件:: 
* namedtuple() 擁有具名欄位之 tuple 的工廠函式: namedtuple 擁有具名欄位之 tuple 的工廠函式. 
* OrderedDict 物件:: 
* UserDict 物件:: 
* UserList 物件:: 
* UserString 物件:: 

ChainMap 物件

* ChainMap 範例和用法:: 

deque 物件

* deque 用法:: 

defaultdict 物件

* defaultdict 範例:: 

OrderedDict 物件

* OrderedDict 範例與用法:: 

collections.abc --- 容器的抽象基底類別

* Collections Abstract Base Classes:: 
* 集合抽象基底類別的詳細描述:: 
* Examples and Recipes:: 

heapq --- 堆積佇列 (heap queue) 演算法

* 基礎範例:: 
* 優先佇列實作細節:: 
* 原理:: 

bisect --- 陣列二分演算法 (Array bisection algorithm)

* 效能考量:: 
* 搜尋一個已排序的 list:: 
* 範例: 範例<3>. 

weakref --- 弱參照

* 弱參照物件:: 
* 範例: 範例<4>. 
* 最終化器物件:: 
* 最終化器與 __del__() 方法的比較: 最終化器與 __del__ 方法的比較. 

types --- 動態型別建立與內建型別名稱

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

pprint --- 資料美化列印器

* 函式: 函式<4>. 
* PrettyPrinter 物件:: 
* 範例: 範例<5>. 

reprlib --- repr() 的替代實作

* Repr 物件:: 
* Subclassing Repr Objects:: 

enum --- 對列舉的支援

* 模組內容: 模組內容<2>. 
* 資料型別: 資料型別<2>. 
* 通用項目與裝飾器:: 
* 備註:: 

資料型別

* 支援的 __dunder__ 名稱:: 
* 支援的 _sunder_ 名稱:: 

graphlib —-- 使用類圖 (graph-like) 結構進行操作的功能

* 例外: 例外<3>. 

數值與數學模組

* numbers: numbers --- 數值的抽象基底類別. 數值的抽象基底類別
* math: math --- 數學函式. 數學函式
* cmath: cmath --- 複數的數學函式. 複數的數學函式
* decimal: decimal --- 十進位固定點和浮點運算. 十進位固定點和浮點運算
* fractions: fractions --- 有理數. 有理數
* random: random --- 產生偽隨機數. 產生偽隨機數
* statistics: statistics --- 數學統計函式. 數學統計函式

numbers --- 數值的抽象基底類別

* 數值的階層:: 
* 給型別實作者的註記:: 

給型別實作者的註記

* 加入更多數值 ABC:: 
* 實作算術操作:: 

math --- 數學函式

* 數論函式:: 
* 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:: 
* 特殊函式:: 
* 常數: 常數<2>. 

cmath --- 複數的數學函式

* 轉換到極座標和從極座標做轉換:: 
* 冪函數和對數函數:: 
* 三角函數:: 
* 雙曲函數:: 
* 分類函式:: 
* 常數: 常數<3>. 

decimal --- 十進位固定點和浮點運算

* Quick-start tutorial:: 
* Decimal objects:: 
* Context objects:: 
* 常數: 常數<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:: 
* 特殊值:: 

random --- 產生偽隨機數

* 簿記函式 (bookkeeping functions): 簿記函式 bookkeeping functions. 
* 回傳位元組的函式:: 
* 回傳整數的函式:: 
* 回傳序列的函式:: 
* 離散分布:: 
* 實數分布:: 
* 替代產生器:: 
* 關於 Reproducibility（復現性）的注意事項:: 
* 範例: 範例<6>. 
* 使用方案:: 
* 命令列用法: 命令列用法<2>. 
* 命令列範例:: 

statistics --- 數學統計函式

* 平均值與中央位置量數:: 
* 離度 (spread) 的測量: 離度 spread 的測量. 
* 兩個輸入之間的關係統計:: 
* 函式細節:: 
* 例外: 例外<4>. 
* NormalDist 物件:: 
* 範例與錦囊妙計:: 

範例與錦囊妙計

* 經典機率問題:: 
* 用於模擬的蒙地卡羅 (Monte Carlo) 輸入: 用於模擬的蒙地卡羅 Monte Carlo 輸入. 
* 近似二項分布:: 
* 單純貝氏分類器 (Naive bayesian classifier): 單純貝氏分類器 Naive bayesian classifier. 

函式程式設計模組

* itertools: itertools --- 建立產生高效率迴圈之疊代器的函式. 建立產生高效率迴圈之疊代器的函式
* functools: functools --- 可呼叫物件上的高階函式與操作. 可呼叫物件上的高階函式與操作
* operator: operator --- 標準運算子替代函式. 標準運算子替代函式

itertools --- 建立產生高效率迴圈之疊代器的函式

* Itertool 函式:: 
* Itertools 應用技巧:: 

functools --- 可呼叫物件上的高階函式與操作

* partial 物件:: 

operator --- 標準運算子替代函式

* 運算子與函式間的對映:: 
* 原地 (in-place) 運算子: 原地 in-place 運算子. 

檔案與目錄存取

* pathlib: pathlib --- 物件導向檔案系統路徑. 物件導向檔案系統路徑
* os.path: os path --- 常見的路徑名操作. 常見的路徑名操作
* stat: stat --- 直譯 stat 的結果. 直譯 stat() 的結果
* filecmp: filecmp --- 檔案與目錄比較. 檔案與目錄比較
* tempfile: tempfile --- 生成臨時檔案和目錄. 生成臨時檔案和目錄
* glob: glob --- Unix 風格的路徑名稱模式擴展. Unix 風格的路徑名稱模式擴展
* fnmatch: fnmatch --- Unix 檔案名稱模式比對. Unix 檔案名稱模式比對
* linecache: linecache --- 隨機存取文字列. 隨機存取文字列
* shutil — 高階檔案操作:: 

pathlib --- 物件導向檔案系統路徑

* 基本用法:: 
* 例外: 例外<5>. 
* 純路徑:: 
* 實體路徑:: 
* 模式語言 (pattern language): 模式語言 pattern language. 
* 與 glob 模組的比較:: 
* 與 os 和 os.path 模組的比較: 與 os 和 os path 模組的比較. 
* Protocols:: 

純路徑

* 通用屬性:: 
* 運算子:: 
* 對個別組成的存取:: 
* 方法與屬性:: 

實體路徑

* 剖析和產生 URI:: 
* 擴展和解析路徑:: 
* 查詢檔案類型和狀態:: 
* 讀取和寫入檔案:: 
* 讀取目錄:: 
* 建立檔案和目錄:: 
* 複製、移動和刪除:: 
* 權限和所有權:: 

與 os 和 os.path 模組的比較

* 對應工具:: 

filecmp --- 檔案與目錄比較

* The dircmp class:: 

tempfile --- 生成臨時檔案和目錄

* 範例: 範例<7>. 
* 已棄用的函式和變數:: 

glob --- Unix 風格的路徑名稱模式擴展

* 範例: 範例<8>. 

shutil — 高階檔案操作

* 目錄和檔案操作:: 
* Archiving operations:: 
* Querying the size of the output terminal:: 

目錄和檔案操作

* Platform-dependent efficient copy operations:: 
* copytree 範例:: 
* rmtree 範例:: 

Archiving operations

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

資料持久性 (Data Persistence)

* pickle: pickle --- Python 物件序列化. Python 物件序列化
* copyreg: copyreg --- 註冊 pickle 支援函式. 註冊 pickle 支援函式
* shelve: shelve --- Python object persistence. Python object persistence
* marshal: marshal --- 內部 Python 物件序列化. 內部 Python 物件序列化
* dbm: dbm --- Unix "databases" 的介面. Unix "databases" 的介面
* sqlite3: sqlite3 --- SQLite 資料庫的 DB-API 2 0 介面. SQLite 資料庫的 DB-API 2.0 介面

pickle --- Python 物件序列化

* 和其他 Python 模組的關係:: 
* 資料串流格式:: 
* 模組介面:: 
* 哪些物件能或不能被封裝、拆封？:: 
* Pickling 類別實例:: 
* 針對型別、函式或特定物件定製縮減函式:: 
* 帶外（Out-of-band）資料緩衝區:: 
* 限制全域物件:: 
* 效能: 效能<2>. 
* 範例: 範例<10>. 
* 命令列介面:: 

和其他 Python 模組的關係

* 和 marshal 的比較:: 
* 和 json 的比較:: 

Pickling 類別實例

* 外部物件持久化:: 
* 調度表:: 
* 處裡紀錄大量狀態的物件:: 

帶外（Out-of-band）資料緩衝區

* 供給者 API:: 
* 消費者 API:: 
* 範例: 範例<9>. 

copyreg --- 註冊 pickle 支援函式

* 範例: 範例<11>. 

shelve --- Python object persistence

* Restrictions:: 
* 範例: 範例<12>. 

dbm --- Unix "databases" 的介面

* dbm.sqlite3: dbm sqlite3 --- dbm 的 SQLite 後端. dbm 的 SQLite 後端
* dbm.gnu: dbm gnu --- GNU 資料庫管理器. GNU 資料庫管理器
* dbm.ndbm: dbm ndbm --- 新資料庫管理器. 新資料庫管理器
* dbm.dumb: dbm dumb --- 可攜式 DBM 實作. 可攜式 DBM 實作

sqlite3 --- SQLite 資料庫的 DB-API 2.0 介面

* 教學:: 
* Reference:: 
* How-to guides:: 
* 解釋:: 

Reference

* Module functions:: 
* Module constants:: 
* Connection 物件:: 
* Cursor 物件:: 
* Row 物件:: 
* Blob 物件:: 
* PrepareProtocol 物件:: 
* 例外: 例外<6>. 
* SQLite and Python types:: 
* Default adapters and converters (deprecated): Default adapters and converters deprecated. 
* 命令列介面: 命令列介面<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:: 
* 如何處理非 UTF-8 的文字編碼:: 

How to adapt custom Python types to SQLite values

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

解釋

* Transaction control:: 

Transaction control

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

資料壓縮與保存

* compression 套件:: 
* compression.zstd: compression zstd --- 與 Zstandard 格式相容的壓縮. 與 Zstandard 格式相容的壓縮
* zlib: zlib --- 相容於 gzip 的壓縮. 相容於 gzip 的壓縮
* gzip: gzip --- gzip 檔案的支援. gzip 檔案的支援
* bz2: bz2 --- bzip2 壓縮的支援. bzip2 壓縮的支援
* lzma: lzma --- 使用 LZMA 演算法進行壓縮. 使用 LZMA 演算法進行壓縮
* zipfile: zipfile --- 處理 ZIP 封存檔案. 處理 ZIP 封存檔案
* tarfile: tarfile --- 讀取與寫入 tar 封存檔案. 讀取與寫入 tar 封存檔案

compression.zstd --- 與 Zstandard 格式相容的壓縮

* 例外: 例外<7>. 
* Reading and writing compressed files:: 
* Compressing and decompressing data in memory:: 
* Zstandard 字典:: 
* Advanced parameter control:: 
* Miscellaneous:: 
* 範例: 範例<13>. 

gzip --- gzip 檔案的支援

* 用法範例:: 
* 命令列介面: 命令列介面<3>. 

命令列介面

* 命令列選項:: 

bz2 --- bzip2 壓縮的支援

* (De)compression of files: De compression of files. 
* Incremental (de)compression: Incremental de compression. 
* One-shot (de)compression: One-shot de compression. 
* 用法範例: 用法範例<2>. 

lzma --- 使用 LZMA 演算法進行壓縮

* 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:: 
* 範例: 範例<14>. 

zipfile --- 處理 ZIP 封存檔案

* ZipFile 物件:: 
* Path 物件:: 
* PyZipFile 物件:: 
* ZipInfo 物件:: 
* 命令列介面: 命令列介面<4>. 
* 解壓縮的陷阱:: 

命令列介面

* 命令列選項: 命令列選項<2>. 

解壓縮的陷阱

* 來自檔案本身:: 
* 檔案系統限制:: 
* 資源限制:: 
* 中斷:: 
* 解壓縮的預設行為:: 

tarfile --- 讀取與寫入 tar 封存檔案

* TarFile 物件:: 
* TarInfo 物件:: 
* Extraction filters:: 
* 命令列介面: 命令列介面<5>. 
* 範例: 範例<15>. 
* 支援的 tar 格式:: 
* Unicode issues:: 

Extraction filters

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

命令列介面

* 命令列選項: 命令列選項<3>. 

範例

* Reading examples:: 
* Writing examples:: 

檔案格式

* csv: csv --- CSV 檔案讀取及寫入. CSV 檔案讀取及寫入
* configparser: configparser --- 設定檔剖析器. 設定檔剖析器
* tomllib: tomllib --- 剖析 TOML 檔案. 剖析 TOML 檔案
* netrc: netrc --- netrc 檔案處理. netrc 檔案處理
* plistlib: plistlib --- 產生和剖析 Apple plist 檔案. 產生和剖析 Apple .plist 檔案

csv --- CSV 檔案讀取及寫入

* 模組內容: 模組內容<3>. 
* Dialect 與格式參數:: 
* 讀取器物件:: 
* 寫入器物件:: 
* 範例: 範例<16>. 

configparser --- 設定檔剖析器

* Quick Start:: 
* Supported Datatypes:: 
* Fallback Values:: 
* 支援的 INI 檔案結構:: 
* Unnamed Sections:: 
* Interpolation of values:: 
* Mapping Protocol Access:: 
* Customizing Parser Behaviour:: 
* Legacy API Examples:: 
* ConfigParser 物件:: 
* RawConfigParser 物件:: 
* 例外: 例外<8>. 

tomllib --- 剖析 TOML 檔案

* 範例: 範例<17>. 
* 轉換表:: 

netrc --- netrc 檔案處理

* netrc 物件:: 

plistlib --- 產生和剖析 Apple .plist 檔案

* 範例: 範例<18>. 

加密服務

* hashlib: hashlib --- 安全雜湊與訊息摘要. 安全雜湊與訊息摘要
* hmac: hmac --- 基於金鑰雜湊的訊息驗證. 基於金鑰雜湊的訊息驗證
* secrets: secrets --- 產生用於管理機密的安全亂數. 產生用於管理機密的安全亂數

hashlib --- 安全雜湊與訊息摘要

* 雜湊演算法:: 
* 用法:: 
* 建構函式:: 
* 屬性:: 
* 雜湊物件:: 
* SHAKE 可變長度摘要:: 
* 檔案雜湊:: 
* 密鑰的生成:: 
* BLAKE2:: 

BLAKE2

* 建立雜湊物件:: 
* 常數: 常數<5>. 
* 範例: 範例<19>. 
* 製作人員:: 

範例

* 簡單雜湊:: 
* 使用不同的摘要大小:: 
* 密鑰雜湊 (Keyed hashing): 密鑰雜湊 Keyed hashing. 
* 隨機雜湊 (Randomized hashing): 隨機雜湊 Randomized hashing. 
* 個人化:: 
* 樹狀模式:: 

secrets --- 產生用於管理機密的安全亂數

* 亂數:: 
* 產生權杖（token）:: 
* 其他函式:: 
* 應用技巧和典範實務（best practices）:: 

產生權杖（token）

* 權杖應當使用多少個位元組？:: 

通用作業系統服務

* os: os --- 各種作業系統介面. 各種作業系統介面
* io — 處理資料串流的核心工具:: 
* time: time --- 時間存取與轉換. 時間存取與轉換
* logging: logging --- Python 的日誌記錄工具. Python 的日誌記錄工具
* logging.config: logging config --- 日誌記錄配置. 日誌記錄配置
* logging.handlers: logging handlers --- 日誌紀錄處理器. 日誌紀錄處理器
* platform: platform --- 對底層平臺識別資料的存取. 對底層平臺識別資料的存取
* errno: errno --- 標準 errno 系統符號. 標準 errno 系統符號
* ctypes: ctypes --- 用於 Python 的外部函式庫. 用於 Python 的外部函式庫

os --- 各種作業系統介面

* File Names@comma{} Command Line Arguments@comma{} and Environment Variables: File Names Command Line Arguments and Environment Variables. 
* Python UTF-8 模式:: 
* 行程參數:: 
* File Object Creation:: 
* File Descriptor Operations:: 
* Files and Directories:: 
* 行程管理:: 
* 排程器介面:: 
* Miscellaneous System Information:: 
* Random numbers:: 

File Descriptor Operations

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

Files and Directories

* 計時器檔案描述器:: 
* Linux extended attributes:: 

io — 處理資料串流的核心工具

* 總覽:: 
* 文字編碼:: 
* 高階模組介面:: 
* 類別階層:: 
* Static Typing:: 
* Performance:: 

總覽

* 文字 I/O:: 
* 二進位 (Binary) I/O: 二進位 Binary I/O. 
* 原始 (Raw) I/O: 原始 Raw I/O. 

文字編碼

* 選擇性加入的編碼警告:: 

類別階層

* I/O 基礎類別:: 
* 原始檔案 I/O:: 
* Buffered Streams:: 
* 文字 I/O: 文字 I/O<2>. 

Performance

* 二進位 (Binary) I/O: 二進位 Binary I/O<2>. 
* 文字 I/O: 文字 I/O<3>. 
* Multi-threading: Multi-threading<2>. 
* Reentrancy:: 

time --- 時間存取與轉換

* 函式: 函式<5>. 
* 時鐘 ID 常數:: 
* 時區常數:: 

logging --- Python 的日誌記錄工具

* Logger 物件:: 
* Logging Levels:: 
* Handler Objects:: 
* Formatter Objects:: 
* Filter Objects:: 
* LogRecord 物件:: 
* LogRecord 屬性:: 
* LoggerAdapter 物件:: 
* 執行緒安全:: 
* 模組層級函式:: 
* 模組層級屬性:: 
* Integration with the warnings module:: 

logging.config --- 日誌記錄配置

* 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 --- 日誌紀錄處理器

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

platform ---  對底層平臺識別資料的存取

* 跨平台:: 
* Java 平台:: 
* Windows 平台:: 
* macOS 平台:: 
* iOS 平台:: 
* Unix 平台:: 
* Linux 平台:: 
* Android 平台:: 
* 命令列用法: 命令列用法<3>. 

ctypes --- 用於 Python 的外部函式庫

* ctypes 教學:: 
* ctypes reference:: 

ctypes 教學

* Loading dynamic link libraries:: 
* Accessing functions from loaded dlls:: 
* 呼叫函式:: 
* 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:: 
* 指標:: 
* Thread safety without the GIL:: 
* Type conversions:: 
* Incomplete Types:: 
* 回呼函式:: 
* Accessing values exported from dlls:: 
* Surprises:: 
* Variable-sized data types:: 

ctypes reference

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

命令列介面函式庫

* argparse: argparse --- 命令列選項、引數和子命令的剖析器. 命令列選項、引數和子命令的剖析器
* optparse: optparse --- 命令列選項剖析器. 命令列選項剖析器
* getpass: getpass --- 可攜式密碼輸入工具. 可攜式密碼輸入工具
* fileinput: fileinput --- 逐列疊代多個輸入串流. 逐列疊代多個輸入串流
* curses: curses --- 字元儲存格顯示的終端處理. 字元儲存格顯示的終端處理
* curses.textpad: curses textpad --- Text input widget for curses programs. Text input widget for curses programs
* curses.ascii: curses ascii --- ASCII 字元的工具程式. ASCII 字元的工具程式
* curses.panel: curses panel --- curses 的面板堆疊擴充. curses 的面板堆疊擴充
* cmd: cmd --- 以列為導向的命令直譯器支援. 以列為導向的命令直譯器支援

argparse --- 命令列選項、引數和子命令的剖析器

* ArgumentParser 物件:: 
* add_argument() 方法: add_argument 方法. 
* parse_args() 方法: parse_args 方法. 
* Other utilities:: 
* 例外: 例外<9>. 

ArgumentParser 物件

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

add_argument() 方法

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

parse_args() 方法

* Option value syntax:: 
* 無效引數:: 
* 包含 - 的引數:: 
* 引數縮寫 (前綴匹配): 引數縮寫 前綴匹配. 
* sys.argv 之外: sys argv 之外. 
* 命名空間物件:: 

Other utilities

* 子命令:: 
* FileType 物件:: 
* Argument groups:: 
* Mutual exclusion:: 
* Parser defaults:: 
* 印出幫助訊息:: 
* Partial parsing:: 
* Customizing file parsing:: 
* Exiting methods:: 
* Intermixed parsing:: 
* Registering custom types or actions:: 

例外

* Argparse 教學:: 
* 將 optparse 程式碼遷移到 argparse:: 

Argparse 教學

* 概念:: 
* 基本用法: 基本用法<2>. 
* 位置引數的介紹:: 
* 可選引數的介紹:: 
* 組合位置引數和可選引數:: 
* 更進階一點:: 
* 如何翻譯 argparse 輸出:: 
* 自定義型別轉換器:: 
* 結論:: 

可選引數的介紹

* 短選項:: 

更進階一點

* 指定不明確的引數:: 
* 相互衝突的選項:: 

optparse --- 命令列選項剖析器

* 選擇一個命令列參數剖析函式庫:: 
* Introduction:: 
* 背景:: 
* 教學: 教學<2>. 
* Reference Guide:: 
* Option Callbacks:: 
* Extending optparse:: 
* 例外: 例外<10>. 

背景

* 術語:: 
* What are options for?:: 
* What are positional arguments for?:: 

教學

* Understanding option actions:: 
* The store action:: 
* Handling boolean (flag) options: Handling boolean flag options. 
* Other actions:: 
* 預設值:: 
* Generating help:: 
* Printing a version string:: 
* How optparse handles errors:: 
* Putting it all together:: 

Generating help

* Grouping Options:: 

Reference Guide

* 建立剖析器:: 
* Populating the parser:: 
* 定義選項:: 
* 選項屬性:: 
* 標準選項動作:: 
* Standard option types:: 
* 剖析引數:: 
* Querying and manipulating your option parser:: 
* Conflicts between options:: 
* Cleanup:: 
* 其他方法:: 

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 --- 字元儲存格顯示的終端處理

* 函式: 函式<6>. 
* Window Objects:: 
* Constants:: 

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

* Textbox objects:: 

curses.panel --- curses 的面板堆疊擴充

* 函式: 函式<7>. 
* Panel Objects:: 

cmd --- 以列為導向的命令直譯器支援

* Cmd 物件:: 
* Cmd 範例:: 

並行執行 (Concurrent Execution)

* threading: threading --- 基於執行緒的平行性. 基於執行緒的平行性
* multiprocessing: multiprocessing --- 以行程為基礎的平行性. 以行程為基礎的平行性
* multiprocessing.shared_memory: multiprocessing shared_memory --- 對於共享記憶體的跨行程直接存取. 對於共享記憶體的跨行程直接存取
* concurrent 套件:: 
* concurrent.futures: concurrent futures --- 啟動平行任務. 啟動平行任務
* concurrent.interpreters: concurrent interpreters --- 在同一個行程中使用多個直譯器. 在同一個行程中使用多個直譯器
* subprocess: subprocess --- 子行程管理. 子行程管理
* sched: sched --- 事件排程器. 事件排程器
* queue: queue --- 同步佇列 synchronized queue 類別. 同步佇列 (synchronized queue) 類別
* contextvars: contextvars --- 情境變數. 情境變數
* _thread: _thread --- 低階執行緒 API. 低階執行緒 API

threading --- 基於執行緒的平行性

* Introduction: Introduction<2>. 
* 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. 

Reference

* Thread-local data:: 
* Thread 物件:: 
* Lock 物件:: 
* RLock 物件:: 
* Condition objects:: 
* Semaphore 物件:: 
* Semaphore 範例:: 
* Event objects:: 
* Timer 物件:: 
* Barrier 物件:: 

multiprocessing --- 以行程為基礎的平行性

* 簡介: 簡介<7>. 
* Reference: Reference<3>. 
* Programming guidelines:: 
* 範例: 範例<20>. 

簡介

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

Reference

* Process 與例外:: 
* Pipes and Queues:: 
* Miscellaneous: Miscellaneous<3>. 
* Connection Objects:: 
* Synchronization primitives:: 
* 共享的 ctypes 物件:: 
* Managers:: 
* Proxy Objects:: 
* Process Pools:: 
* Listeners and Clients:: 
* Authentication keys:: 
* Logging:: 
* multiprocessing.dummy 模組: multiprocessing dummy 模組. 

共享的 ctypes 物件

* multiprocessing.sharedctypes 模組: multiprocessing sharedctypes 模組. 

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 --- 啟動平行任務

* Executor 物件:: 
* ThreadPoolExecutor:: 
* InterpreterPoolExecutor:: 
* ProcessPoolExecutor:: 
* Future 物件:: 
* 模組函式:: 
* 例外類別:: 

ThreadPoolExecutor

* ThreadPoolExecutor 範例:: 

ProcessPoolExecutor

* ProcessPoolExecutor 範例:: 

concurrent.interpreters --- 在同一個行程中使用多個直譯器

* Key details:: 
* Introduction: Introduction<3>. 
* Reference: Reference<4>. 
* 基本用法: 基本用法<3>. 

Introduction

* Multiple Interpreters and Isolation:: 
* Running in an Interpreter:: 
* Concurrency and Parallelism:: 
* 直譯器之間的溝通:: 
* "Sharing" Objects:: 

Reference

* Interpreter objects:: 
* 例外: 例外<11>. 
* 在直譯器之間溝通:: 

subprocess --- 子行程管理

* Using the subprocess Module:: 
* 安全性注意事項:: 
* Popen Objects:: 
* Windows Popen Helpers:: 
* Older high-level API:: 
* Replacing Older Functions with the subprocess Module:: 
* Legacy Shell Invocation Functions:: 
* 註解:: 

Using the subprocess Module

* Frequently Used Arguments:: 
* Popen Constructor:: 
* 例外: 例外<12>. 

Windows Popen Helpers

* Windows Constants:: 

Replacing Older Functions with the subprocess Module

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

註解

* Timeout Behavior:: 
* Converting an argument sequence to a string on Windows:: 
* 停用 posix_spawn(): 停用 posix_spawn. 

sched --- 事件排程器

* 排程器物件:: 

queue --- 同步佇列 (synchronized queue) 類別

* 佇列物件:: 
* SimpleQueue 物件:: 

佇列物件

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

contextvars --- 情境變數

* 情境變數:: 
* 手動情境管理:: 
* 對 asyncio 的支援:: 

網路與行程間通訊

* asyncio: asyncio --- 非同步 I/O. 非同步 I/O
* socket — 低階網路介面:: 
* ssl: ssl --- socket 物件的 TLS/SSL 包裝器. socket 物件的 TLS/SSL 包裝器
* select: select --- 等待 I/O 完成. 等待 I/O 完成
* selectors: selectors --- 高階 I/O 多工. 高階 I/O 多工
* signal: signal --- 設定非同步事件的處理函式. 設定非同步事件的處理函式
* mmap: mmap --- 記憶體對映檔案的支援. 記憶體對映檔案的支援

asyncio --- 非同步 I/O

* Runners (執行器): Runners 執行器. 
* 協程與任務:: 
* 串流:: 
* 同步化原始物件 (Synchronization Primitives): 同步化原始物件 Synchronization Primitives. 
* 子行程:: 
* 佇列 (Queues): 佇列 Queues. 
* 例外: 例外<14>. 
* Call Graph Introspection:: 
* 事件迴圈:: 
* Futures:: 
* 傳輸與協定:: 
* Policies:: 
* 平臺支援:: 
* 擴充:: 
* 高階 API 索引:: 
* 低階 API 索引:: 
* 使用 asyncio 開發:: 

Runners (執行器)

* 運行一個 asyncio 程式:: 
* Runner context manager:: 
* Handling Keyboard Interruption:: 

協程與任務

* 協程: 協程<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 物件:: 

Task Groups

* Terminating a Task Group:: 

串流

* StreamReader:: 
* StreamWriter:: 
* 範例: 範例<21>. 

範例

* 使用串流的 TCP echo 用戶端:: 
* 使用串流的 TCP echo 伺服器:: 
* 取得 HTTP 標頭:: 
* 註冊一個使用串流來等待資料的開放 socket:: 

同步化原始物件 (Synchronization Primitives)

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

子行程

* 建立子行程:: 
* 常數: 常數<6>. 
* 與子行程互動:: 

與子行程互動

* 子行程與執行緒:: 
* 範例: 範例<22>. 

佇列 (Queues)

* Queue:: 
* Priority Queue（優先佇列）:: 
* LIFO Queue:: 
* 例外: 例外<13>. 
* 範例: 範例<23>. 

Call Graph Introspection

* 低階工具函式:: 

事件迴圈

* 事件迴圈方法:: 
* 回呼處理:: 
* Server 物件:: 
* 事件迴圈實作:: 
* 範例: 範例<24>. 

事件迴圈方法

* 啟動和停止迴圈:: 
* 排程回呼函式:: 
* 排程延遲的回呼函式:: 
* 建立 Futures 和 Tasks:: 
* 打開網路連線:: 
* 建立網路伺服器:: 
* 傳輸檔案:: 
* TLS 升級:: 
* 監視檔案描述器:: 
* 直接使用 socket 物件:: 
* DNS:: 
* 使用管道:: 
* Unix 訊號:: 
* 在執行緒池或行程池中執行程式碼:: 
* 錯誤處理 API:: 
* 啟用除錯模式:: 
* 運行子行程:: 

範例

* 使用 call_soon() 的 Hello World 範例: 使用 call_soon 的 Hello World 範例. 
* 使用 call_later() 顯示目前日期: 使用 call_later 顯示目前日期. 
* 監聽檔案描述器以進行讀取事件:: 
* 設定 SIGINT 和 SIGTERM 的訊號處理程式:: 

Futures

* Future 函式:: 
* Future 物件: Future 物件<2>. 

傳輸與協定

* Transports:: 
* Protocols: Protocols<2>. 
* 範例: 範例<25>. 

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

範例

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

平臺支援

* 所有平台:: 
* Windows: Windows<82>. 
* macOS: macOS<51>. 

Windows

* Windows 的子行程支援:: 

擴充

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

高階 API 索引

* 任務 (Tasks): 任務 Tasks. 
* 佇列 (Queues): 佇列 Queues<2>. 
* 子行程 (Subprocesses): 子行程 Subprocesses. 
* 串流 (Streams): 串流 Streams. 
* 同步化 (Synchronization): 同步化 Synchronization. 
* 例外: 例外<15>. 

低階 API 索引

* 取得事件迴圈:: 
* 事件迴圈方法: 事件迴圈方法<2>. 
* 傳輸:: 
* 協定:: 
* 事件迴圈 Policies:: 

使用 asyncio 開發

* 除錯模式:: 
* 並行性和多執行緒 (Concurrency and Multithreading): 並行性和多執行緒 Concurrency and Multithreading. 
* 執行阻塞的程式:: 
* 日誌記錄:: 
* 偵測從未被等待的 (never-awaited) 協程: 偵測從未被等待的 never-awaited 協程. 
* 偵測從未被取得的 (never-retrieved) 例外: 偵測從未被取得的 never-retrieved 例外. 

socket — 低階網路介面

* Socket 系列家族:: 
* 模組內容: 模組內容<4>. 
* Socket 物件:: 
* Notes on socket timeouts:: 
* 範例: 範例<26>. 

模組內容

* 例外: 例外<16>. 
* 常數: 常數<7>. 
* 函式: 函式<8>. 

函式

* 建立 sockets:: 
* 其他函式: 其他函式<2>. 

Notes on socket timeouts

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

ssl --- socket 物件的 TLS/SSL 包裝器

* 函式、常數與例外:: 
* SSL Sockets:: 
* SSL Contexts:: 
* Certificates:: 
* 範例: 範例<27>. 
* Notes on non-blocking sockets:: 
* 記憶體 BIO 支援: 記憶體 BIO 支援<2>. 
* SSL session:: 
* Security considerations: Security considerations<2>. 
* TLS 1.3: TLS 1 3. 

函式、常數與例外

* Socket 建立:: 
* 語境建立:: 
* 例外: 例外<17>. 
* 隨機產生:: 
* 認證處理:: 
* 常數: 常數<8>. 

Certificates

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

範例

* Testing for SSL support:: 
* Client-side operation:: 
* 伺服器端操作:: 

Security considerations

* Best defaults:: 
* 手動設定:: 
* Multi-processing:: 

手動設定

* 驗證憑證:: 
* 協定版本:: 
* Cipher selection:: 

select --- 等待 I/O 完成

* /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 --- 高階 I/O 多工

* 簡介: 簡介<8>. 
* Classes: Classes<2>. 
* 範例: 範例<28>. 

signal --- 設定非同步事件的處理函式

* 一般規則:: 
* 模組內容: 模組內容<5>. 
* 範例: 範例<29>. 
* 關於 SIGPIPE 的說明:: 
* 訊號處理程式與例外的說明:: 

一般規則

* Python 訊號處理程式的執行:: 
* 訊號和執行緒:: 

mmap --- 記憶體對映檔案的支援

* MADV_* 常數:: 
* MAP_* 常數:: 

網際網路資料處理

* email: email --- 郵件和 MIME 處理套件. 郵件和 MIME 處理套件
* json: json --- JSON 編碼器與解碼器. JSON 編碼器與解碼器
* mailbox: mailbox --- 以各種格式操作郵件信箱. 以各種格式操作郵件信箱
* mimetypes: mimetypes --- 將檔案名稱對映到 MIME 類型. 將檔案名稱對映到 MIME 類型
* base64: base64 --- Base16、Base32、Base64、Base85 資料編碼. Base16、Base32、Base64、Base85 資料編碼
* binascii: binascii --- 在二進位制和 ASCII 之間轉換. 在二進位制和 ASCII 之間轉換
* quopri: quopri --- 編碼和解碼 MIME 可列印字元資料. 編碼和解碼 MIME 可列印字元資料

email --- 郵件和 MIME 處理套件

* email.message：表示電子郵件訊息: email message：表示電子郵件訊息. 
* email.parser：剖析電子郵件訊息: email parser：剖析電子郵件訊息. 
* email.generator：產生 MIME 文件: email generator：產生 MIME 文件. 
* email.policy; Policy Objects: email policy Policy Objects. 
* email.errors：例外和缺陷類別: email errors：例外和缺陷類別. 
* email.headerregistry：自訂標頭物件: email headerregistry：自訂標頭物件. 
* email.contentmanager：管理 MIME 內容: email contentmanager：管理 MIME 內容. 
* email：範例:: 
* email.message.Message; Representing an email message using the compat32 API: email message Message Representing an email message using the compat32 API. 
* email.mime：從頭開始建立電子郵件和 MIME 物件: email mime：從頭開始建立電子郵件和 MIME 物件. 
* email.header：國際化標頭: email header：國際化標頭. 
* email.charset：字元集合的表示: email charset：字元集合的表示. 
* email.encoders：編碼器: email encoders：編碼器. 
* email.utils：雜項工具: email utils：雜項工具. 
* email.iterators：疊代器: email iterators：疊代器. 

email.parser：剖析電子郵件訊息

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

email.contentmanager：管理 MIME 內容

* Content Manager Instances:: 

json --- JSON 編碼器與解碼器

* 基本用法: 基本用法<4>. 
* 編碼器與解碼器:: 
* 例外: 例外<18>. 
* 合規性與互通性（Interoperability）:: 
* 命令列介面: 命令列介面<6>. 

合規性與互通性（Interoperability）

* 字元編碼格式:: 
* 正負無限與非數值:: 
* 物件內重複的名稱:: 
* 位於頂層的非物件及非列表值:: 
* 實作限制:: 

命令列介面

* 命令列選項: 命令列選項<4>. 

mailbox --- 以各種格式操作郵件信箱

* Mailbox 物件:: 
* Message 物件:: 
* 例外: 例外<19>. 
* 範例: 範例<30>. 

Mailbox 物件

* Mailbox 物件: Mailbox 物件<2>. 
* mbox 物件:: 
* MH 物件:: 
* Babyl 物件:: 
* MMDF 物件:: 

Message 物件

* MaildirMessage 物件:: 
* mboxMessage 物件:: 
* MHMessage 物件:: 
* BabylMessage 物件:: 
* MMDFMessage 物件:: 

mimetypes --- 將檔案名稱對映到 MIME 類型

* MimeTypes 物件:: 
* 命令列用法: 命令列用法<4>. 
* Command-line example:: 

base64 --- Base16、Base32、Base64、Base85 資料編碼

* RFC 4648 編碼:: 
* Base85 編碼:: 
* 舊版介面:: 
* 安全性注意事項: 安全性注意事項<2>. 

結構化標記處理工具

* html: html --- 超文本標記語言 HTML 支援. 超文本標記語言 (HTML) 支援
* html.parser: html parser --- 簡單的 HTML 和 XHTML 剖析器. 簡單的 HTML 和 XHTML 剖析器
* html.entities: html entities --- HTML 一般實體的定義. HTML 一般實體的定義
* XML 處理模組:: 
* xml.etree.cElementTree: xml etree cElementTree --- ElementTree XML API. ElementTree XML API
* xml.dom: xml dom --- Document 物件模型 API. Document 物件模型 API
* xml.dom.minidom: xml dom minidom --- 最小的 DOM 實作. 最小的 DOM 實作
* xml.dom.pulldom: xml dom pulldom --- 支援建置部分 DOM 樹. 支援建置部分 DOM 樹
* xml.sax: xml sax --- SAX2 剖析器支援. SAX2 剖析器支援
* xml.sax.handler: xml sax handler --- SAX 處理函式的基本類別. SAX 處理函式的基本類別
* xml.sax.saxutils: xml sax saxutils --- SAX 工具程式. SAX 工具程式
* xml.sax.xmlreader: xml sax xmlreader --- XML 剖析器的介面. XML 剖析器的介面
* xml.parsers.expat: xml parsers expat --- 使用 Expat 進行快速 XML 剖析. 使用 Expat 進行快速 XML 剖析

html.parser --- 簡單的 HTML 和 XHTML 剖析器

* HTML 剖析器應用程式範例:: 
* HTMLParser 方法:: 
* 範例: 範例<31>. 

XML 處理模組

* XML 安全性:: 

xml.etree.cElementTree --- ElementTree XML API

* 教學: 教學<3>. 
* XPath 支援:: 
* Reference: Reference<5>. 
* XInclude support:: 
* Reference: Reference<6>. 

教學

* XML tree and elements:: 
* 剖析 XML:: 
* Pull API for non-blocking parsing:: 
* Finding interesting elements:: 
* 改動 XML 檔案:: 
* 建立 XML 文件:: 
* Parsing XML with Namespaces:: 

XPath 支援

* 範例: 範例<32>. 
* 支援的 XPath 語法:: 

Reference

* 函式: 函式<9>. 

XInclude support

* 範例: 範例<33>. 

Reference

* 函式: 函式<10>. 
* Element 物件:: 
* ElementTree 物件:: 
* QName 物件:: 
* TreeBuilder 物件:: 
* XMLParser 物件:: 
* XMLPullParser 物件:: 
* 例外: 例外<20>. 

xml.dom --- Document 物件模型 API

* 模組內容: 模組內容<6>. 
* Objects in the DOM:: 
* Conformance:: 

Objects in the DOM

* DOMImplementation 物件:: 
* Node Objects:: 
* NodeList 物件:: 
* DocumentType 物件:: 
* Document Objects:: 
* Element Objects:: 
* Attr Objects:: 
* NamedNodeMap 物件:: 
* Comment Objects:: 
* Text and CDATASection Objects:: 
* ProcessingInstruction 物件:: 
* 例外: 例外<21>. 

Conformance

* Type Mapping:: 
* Accessor Methods:: 

xml.dom.minidom --- 最小的 DOM 實作

* DOM 物件:: 
* DOM 範例:: 
* minidom 和 DOM 標準:: 

xml.dom.pulldom --- 支援建置部分 DOM 樹

* DOMEventStream 物件:: 

xml.sax --- SAX2 剖析器支援

* SAXException 物件:: 

xml.sax.handler --- SAX 處理函式的基本類別

* ContentHandler 物件:: 
* DTDHandler 物件:: 
* EntityResolver 物件:: 
* ErrorHandler 物件:: 
* LexicalHandler 物件:: 

xml.sax.xmlreader --- XML 剖析器的介面

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

xml.parsers.expat --- 使用 Expat 進行快速 XML 剖析

* XMLParser 物件: XMLParser 物件<2>. 
* ExpatError 例外:: 
* 範例: 範例<34>. 
* Content Model Descriptions:: 
* Expat 錯誤常數:: 

網路協定 (Internet protocols) 及支援

* webbrowser: webbrowser --- 方便的網頁瀏覽器控制器. 方便的網頁瀏覽器控制器
* wsgiref: wsgiref --- WSGI 工具與參考實作. WSGI 工具與參考實作
* urllib: urllib --- URL 處理模組. URL 處理模組
* urllib.request: urllib request --- 用來開啟 URLs 的可擴充函式庫. 用來開啟 URLs 的可擴充函式庫
* urllib.response: urllib response --- Response classes used by urllib. Response classes used by urllib
* urllib.parse: urllib parse --- 將 URL 剖析成元件. 將 URL 剖析成元件
* urllib.error: urllib error --- urllib request 引發的例外類別. urllib.request 引發的例外類別
* urllib.robotparser: urllib robotparser --- robots txt 的剖析器. robots.txt 的剖析器
* http: http --- HTTP 模組. HTTP 模組
* http.client: http client --- HTTP 協定用戶端. HTTP 協定用戶端
* ftplib: ftplib --- FTP 協定用戶端. FTP 協定用戶端
* poplib: poplib --- POP3 協定用戶端. POP3 協定用戶端
* imaplib: imaplib --- IMAP4 協定用戶端. IMAP4 協定用戶端
* smtplib: smtplib --- SMTP 協定用戶端. SMTP 協定用戶端
* uuid: uuid --- RFC 9562 定義的 UUID 物件. RFC 9562 定義的 UUID 物件
* socketserver: socketserver --- 用於網路伺服器的框架. 用於網路伺服器的框架
* http.server — HTTP 伺服器: http server — HTTP 伺服器. 
* http.cookies: http cookies --- HTTP 狀態管理. HTTP 狀態管理
* http.cookiejar: http cookiejar --- HTTP 用戶端的 Cookie 處理. HTTP 用戶端的 Cookie 處理
* xmlrpc: xmlrpc --- XMLRPC 伺服器與用戶模組. XMLRPC 伺服器與用戶模組
* xmlrpc.client: xmlrpc client --- XML-RPC 用戶端存取. XML-RPC 用戶端存取
* xmlrpc.server: xmlrpc server --- 基本 XML-RPC 伺服器. 基本 XML-RPC 伺服器
* ipaddress: ipaddress --- IPv4/IPv6 操作函式庫. IPv4/IPv6 操作函式庫

webbrowser --- 方便的網頁瀏覽器控制器

* 瀏覽器控制器物件:: 

wsgiref --- WSGI 工具與參考實作

* wsgiref.util: wsgiref util -- WSGI 環境工具. WSGI 環境工具
* wsgiref.headers: wsgiref headers -- WSGI 回應標頭工具. WSGI 回應標頭工具
* wsgiref.simple_server: wsgiref simple_server -- 一個簡單的 WSGI HTTP 伺服器. 一個簡單的 WSGI HTTP 伺服器
* wsgiref.validate: wsgiref validate --- WSGI 符合性檢查. WSGI 符合性檢查
* wsgiref.handlers: wsgiref handlers -- 伺服器 / 閘道基本類別. 伺服器 / 閘道基本類別
* wsgiref.types: wsgiref types -- 用於靜態型別檢查的 WSGI 型別. 用於靜態型別檢查的 WSGI 型別
* 範例: 範例<35>. 

urllib.request --- 用來開啟 URLs 的可擴充函式庫

* Request 物件:: 
* OpenerDirector 物件:: 
* BaseHandler 物件:: 
* HTTPRedirectHandler 物件:: 
* HTTPCookieProcessor 物件:: 
* ProxyHandler 物件:: 
* HTTPPasswordMgr 物件:: 
* HTTPPasswordMgrWithPriorAuth 物件:: 
* AbstractBasicAuthHandler 物件:: 
* HTTPBasicAuthHandler 物件:: 
* ProxyBasicAuthHandler 物件:: 
* AbstractDigestAuthHandler 物件:: 
* HTTPDigestAuthHandler 物件:: 
* ProxyDigestAuthHandler 物件:: 
* HTTPHandler 物件:: 
* HTTPSHandler 物件:: 
* FileHandler 物件:: 
* DataHandler 物件:: 
* FTPHandler 物件:: 
* CacheFTPHandler 物件:: 
* UnknownHandler 物件:: 
* HTTPErrorProcessor 物件:: 
* 範例: 範例<36>. 
* 遺留介面:: 
* urllib.request 限制: urllib request 限制. 

urllib.parse --- 將 URL 剖析成元件

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

http --- HTTP 模組

* HTTP 狀態碼:: 
* HTTP 狀態分類:: 
* HTTP 方法:: 

http.client --- HTTP 協定用戶端

* HTTPConnection 物件:: 
* HTTPResponse 物件:: 
* 範例: 範例<37>. 
* HTTPMessage 物件:: 

ftplib --- FTP 協定用戶端

* 參考:: 

參考

* FTP 物件:: 
* FTP_TLS 物件:: 
* 模組變數:: 

poplib --- POP3 協定用戶端

* POP3 物件:: 
* POP3 範例:: 

imaplib --- IMAP4 協定用戶端

* IMAP4 物件:: 
* IMAP4 範例:: 

smtplib --- SMTP 協定用戶端

* SMTP 物件:: 
* SMTP 範例:: 

uuid --- RFC 9562 定義的 UUID 物件

* 命令列的用法:: 
* 範例: 範例<38>. 
* 命令列的範例:: 

socketserver --- 用於網路伺服器的框架

* Server Creation Notes:: 
* Server Objects:: 
* Request Handler Objects:: 
* 範例: 範例<39>. 

範例

* socketserver.TCPServer 範例: socketserver TCPServer 範例. 
* socketserver.UDPServer 範例: socketserver UDPServer 範例. 
* Asynchronous Mixins:: 

http.server — HTTP 伺服器

* 命令列介面: 命令列介面<7>. 
* 安全性注意事項: 安全性注意事項<3>. 

http.cookies --- HTTP 狀態管理

* Cookie 物件:: 
* Morsel 物件:: 
* 範例: 範例<40>. 

http.cookiejar --- HTTP 用戶端的 Cookie 處理

* CookieJar 與 FileCookieJar 物件:: 
* FileCookieJar 子類別及與網頁瀏覽器的合作:: 
* CookiePolicy 物件:: 
* DefaultCookiePolicy 物件:: 
* Cookie 物件: Cookie 物件<2>. 
* 範例: 範例<41>. 

xmlrpc.client --- XML-RPC 用戶端存取

* ServerProxy 物件:: 
* 日期時間物件:: 
* Binary Objects:: 
* Fault Objects:: 
* ProtocolError 物件:: 
* MultiCall 物件:: 
* 便捷的函式:: 
* Example of Client Usage:: 
* Example of Client and Server Usage:: 

xmlrpc.server --- 基本 XML-RPC 伺服器

* SimpleXMLRPCServer 物件:: 
* CGIXMLRPCRequestHandler:: 
* Documenting XMLRPC server:: 
* DocXMLRPCServer 物件:: 
* DocCGIXMLRPCRequestHandler:: 

SimpleXMLRPCServer 物件

* SimpleXMLRPCServer 範例:: 

ipaddress --- IPv4/IPv6 操作函式庫

* 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:: 
* 運算子: 運算子<2>. 

運算子

* 比較運算子:: 
* 算術運算子:: 

IP Network definitions

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

運算子

* Logical operators:: 
* 疊代:: 
* Networks as containers of addresses:: 

Interface objects

* 運算子: 運算子<4>. 

運算子

* Logical operators: Logical operators<2>. 

多媒體服務

* wave: wave --- 讀寫 WAV 檔案. 讀寫 WAV 檔案
* colorsys: colorsys --- 顏色系統間的轉換. 顏色系統間的轉換

wave --- 讀寫 WAV 檔案

* Wave_read 物件:: 
* Wave_write 物件:: 

國際化

* gettext: gettext --- 多語言國際化服務. 多語言國際化服務
* locale: locale --- 國際化服務. 國際化服務

gettext --- 多語言國際化服務

* GNU gettext API:: 
* Class-based API:: 
* Internationalizing your programs and modules:: 
* 致謝: 致謝<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 --- 國際化服務

* 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 打造圖形使用者介面 (Graphical User Interfaces)

* tkinter: tkinter --- Tcl/Tk 的 Python 介面. Tcl/Tk 的 Python 介面
* tkinter.colorchooser: tkinter colorchooser --- 顏色選擇對話框. 顏色選擇對話框
* tkinter.font: tkinter font --- Tkinter 字型包裝器. Tkinter 字型包裝器
* Tkinter 對話框:: 
* tkinter.messagebox: tkinter messagebox --- Tkinter 訊息提示. Tkinter 訊息提示
* tkinter.scrolledtext: tkinter scrolledtext --- 捲動文字小工具. 捲動文字小工具
* tkinter.dnd: tkinter dnd --- 拖放支援. 拖放支援
* tkinter.ttk: tkinter ttk --- Tk 主題化小工具. Tk 主題化小工具
* IDLE: IDLE --- Python 編輯器與 shell<2>. Python 編輯器與 shell
* turtle: turtle --- 龜圖學 Turtle graphics. 龜圖學 (Turtle graphics)

tkinter --- Tcl/Tk 的 Python 介面

* 架構:: 
* Tkinter 模組:: 
* Tkinter 應急指南:: 
* 執行緒模型:: 
* 實用參考:: 
* 檔案處理常式:: 

Tkinter 應急指南

* 一個 Hello World 程式:: 
* 重要的 Tk 概念:: 
* 了解 Tkinter 如何包裝 Tcl/Tk:: 
* 我該如何...？哪個選項可以...？: 我該如何 ？哪個選項可以 ？. 
* 瀏覽 Tcl/Tk 參考手冊:: 

實用參考

* 設定選項: 設定選項<2>. 
* Packer 佈局管理器:: 
* Packer 選項:: 
* 耦合元件變數:: 
* 視窗管理器:: 
* Tk 選項資料型別:: 
* 繫結與事件:: 
* index 參數:: 
* 圖片:: 

Tkinter 對話框

* tkinter.simpledialog: tkinter simpledialog --- 標準 Tkinter 輸入對話框. 標準 Tkinter 輸入對話框
* tkinter.filedialog: tkinter filedialog --- 檔案選擇對話框. 檔案選擇對話框
* tkinter.commondialog: tkinter commondialog --- Dialog window templates. Dialog window templates

tkinter.filedialog --- 檔案選擇對話框

* Native Load/Save Dialogs:: 

tkinter.ttk --- Tk 主題化小工具

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

Widget

* 標準選項:: 
* Scrollable Widget Options:: 
* Label Options:: 
* 相容性選項:: 
* Widget States:: 
* ttk.Widget: ttk Widget. 

Combobox

* 選項:: 
* Virtual events:: 
* ttk.Combobox: ttk Combobox. 

Spinbox

* 選項: 選項<2>. 
* Virtual events: Virtual events<2>. 
* ttk.Spinbox: ttk Spinbox. 

Notebook

* 選項: 選項<3>. 
* Tab Options:: 
* Tab Identifiers:: 
* 虛擬事件:: 
* ttk.Notebook: ttk Notebook. 

Progressbar

* 選項: 選項<4>. 
* ttk.Progressbar: ttk Progressbar. 

Separator

* 選項: 選項<5>. 

Sizegrip

* Platform-specific notes:: 
* Bugs:: 

Treeview

* 選項: 選項<6>. 
* Item Options:: 
* Tag Options:: 
* Column Identifiers:: 
* 虛擬事件: 虛擬事件<2>. 
* ttk.Treeview: ttk Treeview. 

Ttk Styling

* Layouts:: 

IDLE --- Python 編輯器與 shell

* 目錄:: 
* Editing and Navigation:: 
* Startup and Code Execution:: 
* Help and Preferences:: 
* idlelib: idlelib --- implementation of IDLE application. implementation of IDLE application

目錄

* 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:: 
* Code Context:: 
* Shell window:: 
* Text colors:: 

Startup and Code Execution

* 命令列用法: 命令列用法<5>. 
* Startup failure:: 
* Running user code:: 
* User output in Shell:: 
* Developing tkinter applications:: 
* Running without a subprocess:: 

Help and Preferences

* Help sources:: 
* 設定偏好:: 
* macOS 上的 IDLE:: 
* Extensions:: 

turtle --- 龜圖學 (Turtle graphics)

* 介紹:: 
* Get started:: 
* 教學: 教學<4>. 
* How to...: How to. 
* Turtle graphics reference:: 
* Methods of RawTurtle/Turtle and corresponding functions:: 
* Methods of TurtleScreen/Screen and corresponding functions:: 
* Public classes:: 
* 解釋: 解釋<2>. 
* Help and configuration:: 
* turtledemo: turtledemo --- Demo scripts. Demo scripts
* Changes since Python 2.6: Changes since Python 2 6. 
* Changes since Python 3.0: Changes since Python 3 0. 

教學

* 啟動一個烏龜環境:: 
* 基本繪圖:: 
* Making algorithmic patterns:: 

基本繪圖

* 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: typing --- 支援型別提示. 支援型別提示
* pydoc: pydoc --- 文件產生器與線上幫助系統. 文件產生器與線上幫助系統
* Python 開發模式:: 
* doctest: doctest --- 測試互動式 Python 範例. 測試互動式 Python 範例
* unittest: unittest --- 單元測試框架. 單元測試框架
* unittest.mock — mock 物件函式庫: unittest mock — mock 物件函式庫. 
* unittest.mock: unittest mock --- 入門指南. 入門指南
* test: test --- Python 的回歸測試 regression tests 套件. Python 的回歸測試 (regression tests) 套件
* test.support: test support --- Python 測試套件的工具. Python 測試套件的工具
* test.support.socket_helper: test support socket_helper --- 用於 socket 測試的工具. 用於 socket 測試的工具
* test.support.script_helper: test support script_helper --- 用於 Python 執行測試的工具. 用於 Python 執行測試的工具
* test.support.bytecode_helper: test support bytecode_helper --- 用於測試位元組碼能正確產生的支援工具. 用於測試位元組碼能正確產生的支援工具
* test.support.threading_helper: test support threading_helper --- Utilities for threading tests. Utilities for threading tests
* test.support.os_helper: test support os_helper --- 用於 os 測試的工具. 用於 os 測試的工具
* test.support.import_helper: test support import_helper --- 用於 import 測試的工具. 用於 import 測試的工具
* test.support.warnings_helper: test support warnings_helper --- 用於 warnings 測試的工具. 用於 warnings 測試的工具

typing --- 支援型別提示

* Python 型別系統的技術規範:: 
* 型別別名:: 
* NewType:: 
* 註釋 callable 物件:: 
* 泛型:: 
* 註釋元組 (tuple): 註釋元組 tuple. 
* 類別物件的型別:: 
* Annotating generators and coroutines:: 
* 使用者定義泛型型別:: 
* Any 型別:: 
* 標稱 (nominal) 子型別 vs 結構子型別: 標稱 nominal 子型別 vs 結構子型別. 
* 模組內容: 模組內容<7>. 
* 主要功能的棄用時程表:: 

模組內容

* 特別型別原語 (primitive): 特別型別原語 primitive. 
* 協定: 協定<2>. 
* ABCs and Protocols for working with I/O:: 
* 函式與裝飾器:: 
* Introspection helpers:: 
* 常數: 常數<9>. 
* 棄用的別名:: 

特別型別原語 (primitive)

* 特別型別:: 
* 特別型式:: 
* Building generic types and type aliases:: 
* Other special directives:: 

棄用的別名

* 內建型別的別名:: 
* collections 中型別的別名:: 
* Aliases to other concrete types:: 
* collections.abc 中容器 ABC 的別名: collections abc 中容器 ABC 的別名. 
* collections.abc 中非同步 ABC 的別名: collections abc 中非同步 ABC 的別名. 
* Aliases to other ABCs in collections.abc: Aliases to other ABCs in collections abc. 
* contextlib ABC 的別名:: 

Python 開發模式

* Python 開發模式的影響:: 
* ResourceWarning 範例:: 
* 檔案描述器的錯誤範例:: 

doctest --- 測試互動式 Python 範例

* 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. 
* 命令列用法: 命令列用法<6>. 
* 運作方式:: 
* 基礎 API:: 
* Unittest API:: 
* Advanced API:: 
* 偵錯:: 
* Soapbox:: 

運作方式

* Which Docstrings Are Examined?:: 
* How are Docstring Examples Recognized?:: 
* What's the Execution Context?:: 
* What About Exceptions?:: 
* 可選旗標:: 
* Directives:: 
* 警告: 警告<2>. 

Advanced API

* DocTest 物件:: 
* Example 物件:: 
* DocTestFinder 物件:: 
* DocTestParser 物件:: 
* TestResults 物件:: 
* DocTestRunner 物件:: 
* OutputChecker 物件:: 

unittest --- 單元測試框架

* 簡單範例:: 
* 命令列介面: 命令列介面<8>. 
* Test Discovery（測試探索）:: 
* Organizing test code:: 
* Re-using old test code:: 
* Skipping tests and expected failures:: 
* Distinguishing test iterations using subtests:: 
* 類別與函式:: 
* Class and Module Fixtures:: 
* Signal Handling:: 

命令列介面

* 命令列模式選項:: 

類別與函式

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

Loading and running tests

* load_tests 協定:: 

Class and Module Fixtures

* setUpClass 和 tearDownClass:: 
* setUpModule 和 tearDownModule:: 

unittest.mock — mock 物件函式庫

* 快速導引:: 
* Mock 類別:: 
* Patchers:: 
* MagicMock 以及魔術方法支援:: 
* 輔助函式: 輔助函式<2>. 
* side_effect、return_value 和 wraps 的優先順序:: 

Mock 類別

* 呼叫:: 
* 刪除屬性:: 
* Mock 名稱與名稱屬性:: 
* 如同屬性一般附加 mock:: 

Patchers

* patch:: 
* patch.object: patch object. 
* patch.dict: patch dict. 
* patch.multiple: patch multiple. 
* patch 方法：啟動與停止:: 
* patch 內建函式:: 
* TEST_PREFIX:: 
* 巢狀使用 Patch 裝飾器:: 
* 該 patch 何處:: 
* Patch 描述器與代理物件 (Proxy Objects): Patch 描述器與代理物件 Proxy Objects. 

MagicMock 以及魔術方法支援

* Mock 魔術方法:: 
* Magic Mock:: 

輔助函式

* sentinel（哨兵）:: 
* DEFAULT:: 
* call:: 
* create_autospec:: 
* ANY:: 
* FILTER_DIR:: 
* mock_open:: 
* Autospeccing（自動規格）:: 
* 密封 mock:: 

unittest.mock --- 入門指南

* 使用 Mock 的方式:: 
* Patch 裝飾器:: 
* 更多範例:: 

使用 Mock 的方式

* 使用 Mock 來 patching 方法:: 
* 對物件的方法呼叫使用 mock:: 
* Mock 類別: Mock 類別<2>. 
* 命名你的 mock:: 
* 追蹤所有呼叫:: 
* 設定回傳值和屬性:: 
* 透過 mock 引發例外:: 
* Side effect 函式以及可疊代物件:: 
* Mock 非同步可疊代物件:: 
* Mock 非同步情境管理器:: 
* 從現有物件建立 mock:: 
* 使用 side_effect 回傳各別檔案內容:: 

更多範例

* Mock 鍊接呼叫:: 
* 部分 mocking:: 
* Mock 產生器方法:: 
* 對每個測試方法應用相同的 patch:: 
* Mock Unbound Methods （未繫結方法）:: 
* 使用 mock 檢查多個呼叫:: 
* 應對可變引數:: 
* 巢狀使用 Patch:: 
* 使用 MagicMock 來 mock 字典:: 
* Mock 子類別及其屬性:: 
* 使用 patch.dict 來 mock import: 使用 patch dict 來 mock import. 
* 追蹤呼叫順序與更簡潔的呼叫斷言:: 
* 更複雜的引數匹配:: 

test --- Python 的回歸測試 (regression tests) 套件

* 撰寫 test 套件的單元測試:: 
* 使用命令列介面執行測試:: 

除錯與效能分析

* 稽核事件表:: 
* bdb: bdb --- 偵錯器框架. 偵錯器框架
* faulthandler: faulthandler --- 傾印 Python 回溯. 傾印 Python 回溯
* pdb: pdb --- Python 偵錯器. Python 偵錯器
* Python 的分析器:: 
* timeit: timeit --- 測量小量程式片段的執行時間. 測量小量程式片段的執行時間
* trace: trace --- 追蹤或追查 Python 陳述式執行. 追蹤或追查 Python 陳述式執行
* tracemalloc: tracemalloc --- 追蹤記憶體配置. 追蹤記憶體配置

faulthandler --- 傾印 Python 回溯

* 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:: 
* 範例: 範例<42>. 

Dumping the C stack

* C Stack Compatibility:: 

pdb --- Python 偵錯器

* 偵錯器命令:: 

Python 的分析器

* 分析器簡介:: 
* Instant User's Manual:: 
* profile 與 cProfile 模組參考文件:: 
* Stats 類別:: 
* What Is Deterministic Profiling?:: 
* 限制:: 
* 校正:: 
* Using a custom timer:: 

timeit --- 測量小量程式片段的執行時間

* 基礎範例: 基礎範例<2>. 
* Python 介面:: 
* 命令列介面: 命令列介面<9>. 
* 範例: 範例<43>. 

trace --- 追蹤或追查 Python 陳述式執行

* 命令列用法: 命令列用法<7>. 
* 程式介面:: 

命令列用法

* 主要選項:: 
* 修飾子（Modifier）:: 
* 篩選子（Filter）:: 

tracemalloc --- 追蹤記憶體配置

* 範例: 範例<44>. 
* API:: 

範例

* 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

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

軟體封裝與發布

* ensurepip: ensurepip --- pip 安裝器的初始建置 bootstrapping. pip 安裝器的初始建置 (bootstrapping)
* venv: venv --- 建立虛擬環境. 建立虛擬環境
* zipapp —-- 管理可執行的 Python zip 封存檔案:: 

ensurepip --- pip 安裝器的初始建置 (bootstrapping)

* 命令列介面: 命令列介面<10>. 
* 模組 API:: 

venv --- 建立虛擬環境

* 建立虛擬環境: 建立虛擬環境<2>. 
* 虛擬環境如何運作:: 
* API: API<2>. 
* 一個擴展 EnvBuilder 的範例:: 

zipapp —-- 管理可執行的 Python zip 封存檔案

* 基本範例:: 
* 命令列介面: 命令列介面<11>. 
* Python API:: 
* 範例: 範例<45>. 
* 指定直譯器:: 
* 使用 zipapp 建立獨立應用程式:: 
* Python Zip 應用程式封存檔案格式:: 

使用 zipapp 建立獨立應用程式

* 注意事項:: 

Python Runtime 服務

* sys: sys --- 系統特定的參數與函式. 系統特定的參數與函式
* sys.monitoring: sys monitoring --- 執行事件監控. 執行事件監控
* sysconfig: sysconfig --- 提供 Python 設定資訊的存取. 提供 Python 設定資訊的存取
* builtins: builtins --- 內建物件. 內建物件
* __main__: __main__ --- 頂層程式碼環境. 頂層程式碼環境
* warnings: warnings --- 警告控制. 警告控制
* dataclasses: dataclasses --- Data Classes. Data Classes
* contextlib: contextlib --- with 陳述式工具程式. with 陳述式工具程式
* abc: abc --- 抽象基底類別. 抽象基底類別
* atexit: atexit --- 退出處理函式. 退出處理函式
* traceback: traceback --- 列印或取得堆疊回溯 stack traceback. 列印或取得堆疊回溯 (stack traceback)
* __future__: __future__ --- Future 陳述式定義. Future 陳述式定義
* gc: gc --- 垃圾回收器介面 Garbage Collector interface. 垃圾回收器介面 (Garbage Collector interface)
* inspect: inspect --- 檢視活動物件. 檢視活動物件
* annotationlib: annotationlib --- 用於自我檢查註釋的功能. 用於自我檢查註釋的功能
* site: site --- Site-specific configuration hook. Site-specific configuration hook

sys.monitoring --- 執行事件監控

* 工具識別器:: 
* 事件:: 
* 開啟和關閉事件:: 
* 註冊回呼函式:: 

工具識別器

* 註冊和使用工具:: 

事件

* 區域事件:: 
* 已棄用的事件:: 
* 附屬事件 (ancillary events): 附屬事件 ancillary events. 
* 其他事件:: 
* STOP_ITERATION 事件:: 

開啟和關閉事件

* 全域設定事件:: 
* 各別程式碼物件事件:: 
* 停用事件:: 

註冊回呼函式

* 回呼函式引數:: 

sysconfig --- 提供 Python 設定資訊的存取

* Configuration variables:: 
* Installation paths:: 
* User scheme:: 
* Home scheme:: 
* Prefix scheme:: 
* 安裝路徑函式:: 
* 其他函式: 其他函式<3>. 
* 命令列用法: 命令列用法<8>. 

User scheme

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

Home scheme

* posix_home:: 

Prefix scheme

* posix_prefix:: 
* nt:: 

__main__ --- 頂層程式碼環境

* __name__ == '__main__':: 
* Python 套件中的 __main__.py: Python 套件中的 __main__ py. 
* import __main__:: 

__name__ == '__main__'

* 什麼是「頂層程式碼環境」？:: 
* 慣用 (Idiomatic) 用法: 慣用 Idiomatic 用法. 
* 打包時須考慮的事情:: 

Python 套件中的 __main__.py

* 慣用 (Idiomatic) 用法: 慣用 Idiomatic 用法<2>. 

warnings --- 警告控制

* 警告類別:: 
* 警告過濾器:: 
* 暫時抑制警告:: 
* 測試警告:: 
* 為新版相依套件更新程式碼:: 
* 可用的函式:: 
* 可用的情境管理器:: 
* 情境管理器的並行安全性:: 

警告過濾器

* 重複警告的抑制標準:: 
* 描述警告過濾器:: 
* 預設警告過濾器:: 
* 覆寫預設過濾器:: 

dataclasses --- Data Classes

* 模組內容: 模組內容<8>. 
* Post-init processing:: 
* 類別變數:: 
* Init-only variables:: 
* 凍結實例:: 
* 繼承:: 
* Re-ordering of keyword-only parameters in __init__(): Re-ordering of keyword-only parameters in __init__. 
* 預設工廠函式:: 
* 可變預設值:: 
* Descriptor-typed fields:: 

contextlib --- with 陳述式工具程式

* 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 --- 退出處理函式

* atexit 範例:: 

traceback --- 列印或取得堆疊回溯 (stack traceback)

* Module-Level Functions:: 
* TracebackException 物件:: 
* StackSummary 物件:: 
* FrameSummary 物件:: 
* Examples of Using the Module-Level Functions:: 
* TracebackException 的使用範例:: 

__future__ --- Future 陳述式定義

* 模組內容: 模組內容<9>. 

inspect --- 檢視活動物件

* Types and members:: 
* 取得原始碼:: 
* Introspecting callables with the Signature object:: 
* 類別與函式: 類別與函式<2>. 
* 直譯器堆疊:: 
* 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:: 
* 命令列介面: 命令列介面<12>. 

annotationlib --- 用於自我檢查註釋的功能

* Annotation semantics:: 
* Classes: Classes<3>. 
* Functions:: 
* Recipes: Recipes<2>. 
* STRING 格式的限制:: 
* FORWARDREF 格式的限制:: 
* Security implications of introspecting annotations:: 

Recipes

* Using annotations in a metaclass:: 

site --- Site-specific configuration hook

* sitecustomize:: 
* usercustomize:: 
* Readline configuration:: 
* 模組內容: 模組內容<10>. 
* 命令列介面: 命令列介面<13>. 

自訂 Python 直譯器

* code: code --- 直譯器基底類別. 直譯器基底類別
* codeop: codeop --- 編譯 Python 程式碼. 編譯 Python 程式碼

code --- 直譯器基底類別

* 互動式直譯器物件:: 
* 互動式控制台物件:: 

引入模組

* zipimport: zipimport --- 從 Zip 封存檔案匯入模組. 從 Zip 封存檔案匯入模組
* pkgutil: pkgutil --- 套件擴充工具程式. 套件擴充工具程式
* modulefinder: modulefinder --- 搜尋腳本所使用的模組. 搜尋腳本所使用的模組
* runpy: runpy --- 定位並執行 Python 模組. 定位並執行 Python 模組
* importlib: importlib --- import 的實作. import 的實作
* importlib.resources: importlib resources -- 套件資源的讀取、開啟與存取. 套件資源的讀取、開啟與存取
* importlib.resources.abc: importlib resources abc -- 資源的抽象基底類別. 資源的抽象基底類別
* importlib.metadata: importlib metadata -- 存取套件的元資料. 存取套件的元資料
* sys.path 模組搜尋路徑的初始化: sys path 模組搜尋路徑的初始化. 

zipimport --- 從 Zip 封存檔案匯入模組

* zipimporter 物件:: 
* 範例: 範例<46>. 

modulefinder --- 搜尋腳本所使用的模組

* ModuleFinder 的用法範例:: 

importlib --- import 的實作

* 簡介: 簡介<9>. 
* 函式: 函式<12>. 
* importlib.abc: importlib abc -- Abstract base classes related to import. Abstract base classes related to import
* importlib.machinery: importlib machinery -- Importers and path hooks. Importers and path hooks
* importlib.util: importlib util -- Utility code for importers. Utility code for importers
* 範例: 範例<47>. 

範例

* 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 -- 套件資源的讀取、開啟與存取

* Functional API:: 

importlib.metadata -- 存取套件的元資料

* Overview: Overview<2>. 
* Functional API: Functional API<2>. 
* 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

* 範例: 範例<48>. 

sys.path 模組搜尋路徑的初始化

* 虛擬環境:: 
* _pth 檔案:: 
* Embedded Python:: 

Python 語言服務

* ast: ast --- 抽象語法樹 Abstract Syntax Trees. 抽象語法樹 (Abstract Syntax Trees)
* symtable: symtable --- 存取編譯器的符號表. 存取編譯器的符號表
* token: token --- 與 Python 剖析樹一起使用的常數. 與 Python 剖析樹一起使用的常數
* keyword: keyword --- 檢驗 Python 關鍵字. 檢驗 Python 關鍵字
* tokenize: tokenize --- Tokenizer for Python source. Tokenizer for Python source
* tabnanny: tabnanny --- 偵測不良縮排. 偵測不良縮排
* pyclbr: pyclbr --- Python 模組瀏覽器支援. Python 模組瀏覽器支援
* py_compile — 編譯 Python 來源檔案:: 
* compileall: compileall --- 位元組編譯 Python 函式庫. 位元組編譯 Python 函式庫
* dis: dis --- Python bytecode 的反組譯器. Python bytecode 的反組譯器
* pickletools: pickletools --- pickle 開發者的工具. pickle 開發者的工具

ast --- 抽象語法樹 (Abstract Syntax Trees)

* 抽象文法 (Abstract Grammar): 抽象文法 Abstract Grammar. 
* 節點 (Node) 類別: 節點 Node 類別. 
* ast 輔助程式:: 
* 編譯器旗標: 編譯器旗標<2>. 
* 命令列用法: 命令列用法<9>. 

節點 (Node) 類別

* 根節點:: 
* 文本 (Literals): 文本 Literals. 
* 變數:: 
* 運算式: 運算式<2>. 
* 陳述式:: 
* 流程控制:: 
* 模式匹配 (pattern matching): 模式匹配 pattern matching. 
* Type annotations:: 
* 型別參數 (type parameters): 型別參數 type parameters. 
* 函式和類別定義:: 
* async 和 await:: 

運算式

* 下標 (Subscripting): 下標 Subscripting. 
* 綜合運算式 (comprehensions): 綜合運算式 comprehensions. 

陳述式

* 引入 (imports): 引入 imports. 

symtable --- 存取編譯器的符號表

* 產生符號表:: 
* 檢查符號表:: 
* 命令列用法: 命令列用法<10>. 

tokenize --- Tokenizer for Python source

* Tokenizing Input:: 
* 命令列用法: 命令列用法<11>. 
* 範例: 範例<49>. 

pyclbr --- Python 模組瀏覽器支援

* 函式物件:: 
* 類別物件:: 

py_compile — 編譯 Python 來源檔案

* 命令列介面: 命令列介面<14>. 

compileall --- 位元組編譯 Python 函式庫

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

dis --- Python bytecode 的反組譯器

* 命令列介面: 命令列介面<15>. 
* Bytecode analysis:: 
* 分析函式:: 
* Python 位元組碼指令:: 
* Opcode collections:: 

pickletools --- pickle 開發者的工具

* 命令列用法: 命令列用法<12>. 
* 程式化介面:: 

命令列用法

* 命令列選項: 命令列選項<5>. 

MS Windows 特有服務

* msvcrt: msvcrt --- MS VC++ runtime 提供的有用例程. MS VC++ runtime 提供的有用例程
* winreg: winreg --- Windows 註冊表存取. Windows 註冊表存取
* winsound: winsound --- Windows 的音效播放介面. Windows 的音效播放介面

msvcrt --- MS VC++ runtime 提供的有用例程

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

winreg --- Windows 註冊表存取

* 函式: 函式<13>. 
* 常數: 常數<10>. 
* Registry Handle Objects:: 

常數

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

Access Rights

* 64-bit Specific:: 

Unix 特有服務

* shlex: shlex --- 簡單的語法分析. 簡單的語法分析
* posix: posix --- 最常見的 POSIX 系統呼叫. 最常見的 POSIX 系統呼叫
* pwd: pwd --- 密碼資料庫. 密碼資料庫
* grp: grp --- 群組資料庫. 群組資料庫
* termios: termios --- POSIX 風格 tty 控制. POSIX 風格 tty 控制
* tty: tty --- 終端機控制函式. 終端機控制函式
* pty: pty --- 偽終端工具. 偽終端工具
* fcntl: fcntl --- fcntl 和 ioctl 系統呼叫. fcntl 和 ioctl 系統呼叫
* resource: resource --- 資源使用資訊. 資源使用資訊
* syslog: syslog --- Unix syslog 函式庫例程. Unix syslog 函式庫例程

shlex --- 簡單的語法分析

* shlex 物件:: 
* Parsing Rules:: 
* Improved Compatibility with Shells:: 

posix --- 最常見的 POSIX 系統呼叫

* 對大檔案 (Large File) 的支援: 對大檔案 Large File 的支援. 
* 值得注意的模組內容:: 

termios --- POSIX 風格 tty 控制

* 範例: 範例<50>. 

pty --- 偽終端工具

* 範例: 範例<51>. 

resource --- 資源使用資訊

* Resource Limits:: 
* Resource Usage:: 

syslog --- Unix syslog 函式庫例程

* 範例: 範例<52>. 

範例

* 簡單範例: 簡單範例<2>. 

已被取代的模組

* getopt: getopt --- 用於命令列選項的 C 風格剖析器. 用於命令列選項的 C 風格剖析器

已移除的模組

* aifc: aifc --- 讀寫 AIFF 與 AIFC 檔案. 讀寫 AIFF 與 AIFC 檔案
* asynchat: asynchat --- 非同步 socket 指令/回應處理函式. 非同步 socket 指令/回應處理函式
* asyncore: asyncore --- 非同步 socket 處理函式. 非同步 socket 處理函式
* audioop: audioop --- 操作原始聲音檔案. 操作原始聲音檔案
* cgi: cgi --- 通用閘道器介面支援. 通用閘道器介面支援
* cgitb: cgitb --- CGI 腳本的回溯管理器 traceback manager. CGI 腳本的回溯管理器 (traceback manager)
* chunk: chunk --- 讀取 IFF 分塊資料. 讀取 IFF 分塊資料
* crypt: crypt --- 用於檢查 Unix 密碼的函式. 用於檢查 Unix 密碼的函式
* distutils: distutils --- 建置與安裝 Python 模組. 建置與安裝 Python 模組
* imghdr: imghdr --- 判定圖片種類. 判定圖片種類
* imp: imp --- 存取引入系統內層. 存取引入系統內層
* mailcap: mailcap --- Mailcap 檔案處理. Mailcap 檔案處理
* msilib: msilib --- 讀寫 Microsoft Installer 檔案. 讀寫 Microsoft Installer 檔案
* nis: nis --- Sun NIS Yellow Pages 介面. Sun NIS (Yellow Pages) 介面
* nntplib: nntplib --- NNTP 協定用戶端. NNTP 協定用戶端
* ossaudiodev: ossaudiodev --- 對 OSS 相容聲音裝置的存取. 對 OSS 相容聲音裝置的存取
* pipes: pipes --- shell pipelines 介面. shell pipelines 介面
* smtpd: smtpd --- SMTP 伺服器. SMTP 伺服器
* sndhdr: sndhdr --- 判定聲音檔案的種類. 判定聲音檔案的種類
* spwd: spwd --- shadow 密碼資料庫. shadow 密碼資料庫
* sunau: sunau --- 讀寫 Sun AU 檔案. 讀寫 Sun AU 檔案
* telnetlib: telnetlib --- Telnet 用戶端. Telnet 用戶端
* uu: uu --- uuencode 檔案的編碼與解碼. uuencode 檔案的編碼與解碼
* xdrlib: xdrlib --- XDR 資料的編碼與解碼. XDR 資料的編碼與解碼

擴充和嵌入 Python 直譯器

* 推薦的第三方工具:: 
* 不使用第三方工具建立擴充:: 
* 在更大的應用程式中嵌入 CPython 運行環境 (runtime): 在更大的應用程式中嵌入 CPython 運行環境 runtime. 

不使用第三方工具建立擴充

* 以 C 或 C++ 擴充 Python:: 
* 擴充型別定義教學:: 
* Defining Extension Types; Assorted Topics: Defining Extension Types Assorted Topics. 
* 建立 C 與 C++ 擴充套件:: 
* 建置 Windows 上的 C 和 C++ 擴充:: 

以 C 或 C++ 擴充 Python

* 一個簡單範例:: 
* 插曲：錯誤與例外:: 
* 回到範例:: 
* 模組的方法表和初始化函式:: 
* Compilation and Linkage:: 
* Calling Python Functions from C:: 
* Extracting Parameters in Extension Functions:: 
* Keyword Parameters for Extension Functions:: 
* Building Arbitrary Values:: 
* 參照計數:: 
* Writing Extensions in C++:: 
* Providing a C API for an Extension Module:: 

參照計數

* Python 中的參照計數:: 
* Ownership Rules:: 
* Thin Ice:: 
* NULL 指標:: 

擴充型別定義教學

* 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++ 擴充套件

* 用 setuptools 建置 C 與 C++ 擴充套件:: 

建置 Windows 上的 C 和 C++ 擴充

* A Cookbook Approach:: 
* Differences Between Unix and Windows:: 
* Using DLLs in Practice:: 

在更大的應用程式中嵌入 CPython 運行環境 (runtime)

* 在其它 App 內嵌入 Python:: 

在其它 App 內嵌入 Python

* 非常高階的嵌入:: 
* 超越非常高階嵌入：概觀:: 
* 純嵌入:: 
* 擴充嵌入式 Python:: 
* 在 C++ 中嵌入 Python:: 
* 在類 Unix 系統下編譯和連結:: 

Python/C API 參考手冊

* 簡介: 簡介<10>. 
* C API 穩定性:: 
* The Very High Level Layer:: 
* 參照計數: 參照計數<3>. 
* 例外處理:: 
* Defining extension modules:: 
* 工具:: 
* 抽象物件層 (Abstract Objects Layer): 抽象物件層 Abstract Objects Layer. 
* 具體物件層:: 
* 初始化、終結化與執行緒:: 
* Python 初始化設定:: 
* 記憶體管理:: 
* 物件實作支援:: 
* API 和 ABI 版本管理:: 
* 監控 C API:: 
* Generating Execution Events:: 

簡介

* Language version compatibility:: 
* 編寫標準:: 
* 引入檔案 (include files): 引入檔案 include files. 
* 有用的巨集:: 
* 物件、型別和參照計數:: 
* 例外: 例外<22>. 
* 嵌入式Python:: 
* 除錯建置:: 
* Recommended third party tools:: 

物件、型別和參照計數

* 參照計數: 參照計數<2>. 
* 型別:: 

參照計數

* 參照計數詳細資訊:: 

C API 穩定性

* 不穩定的 C API:: 
* 穩定的應用程式二進位介面:: 
* 平台注意事項:: 
* 受限 API 的內容:: 

穩定的應用程式二進位介面

* 受限 C API:: 
* 穩定 ABI:: 
* 受限 API 範圍和性能:: 
* 受限 API 注意事項:: 

例外處理

* Printing and clearing:: 
* Raising exceptions:: 
* Issuing warnings:: 
* Querying the error indicator:: 
* 訊號處理:: 
* 例外類別: 例外類別<2>. 
* 例外物件:: 
* Unicode 例外物件:: 
* 遞迴控制:: 
* 例外和警告型別:: 

例外和警告型別

* 例外型別:: 
* OSError 別名:: 
* 警告型別:: 

Defining extension modules

* Multiple module instances:: 
* Initialization function:: 
* Multi-phase initialization:: 
* Legacy single-phase initialization:: 

工具

* 作業系統工具:: 
* 系統函式:: 
* 行程控制:: 
* 引入模組: 引入模組<2>. 
* 資料 marshal 操作的支援:: 
* 剖析引數與建置數值:: 
* 字串轉換與格式化:: 
* PyHash API:: 
* Reflection:: 
* 編解碼器註冊表和支援函式:: 
* PyTime C API:: 
* 對 Perf Map 的支援:: 

剖析引數與建置數值

* 剖析引數: 剖析引數<2>. 
* 建置數值:: 

剖析引數

* 字串與緩衝區:: 
* 數字:: 
* 其他物件:: 
* API 函式:: 

編解碼器註冊表和支援函式

* 編解碼器查找 API:: 
* 用於 Unicode 編碼錯誤處理程式的註冊 API:: 

PyTime C API

* 型別: 型別<2>. 
* 時鐘函式:: 
* 原始時鐘函式:: 
* 轉換函式:: 

抽象物件層 (Abstract Objects Layer)

* 物件協定:: 
* 呼叫協定 (Call Protocol): 呼叫協定 Call Protocol. 
* 數字協定:: 
* 序列協定:: 
* 對映協定:: 
* 疊代器協定:: 
* 緩衝協定 (Buffer Protocol): 緩衝協定 Buffer Protocol. 

呼叫協定 (Call Protocol)

* tp_call 協定:: 
* Vectorcall 協定:: 
* 物件呼叫 API:: 
* 呼叫支援 API:: 

Vectorcall 協定

* 遞迴控制: 遞迴控制<2>. 
* Vectorcall 支援 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. 

具體物件層

* 基礎物件:: 
* 數值物件:: 
* 序列物件:: 
* 容器物件:: 
* 函式物件: 函式物件<2>. 
* 其他物件: 其他物件<2>. 

基礎物件

* 型別物件:: 
* None 物件:: 

型別物件

* Creating Heap-Allocated Types:: 

數值物件

* 整數物件:: 
* Boolean（布林）物件:: 
* 浮點數（Floating-Point）物件:: 
* 複數物件:: 

整數物件

* Export API:: 
* PyLongWriter API:: 

浮點數（Floating-Point）物件

* Pack and Unpack functions:: 

Pack and Unpack functions

* Pack functions:: 
* Unpack functions:: 

複數物件

* 作為 C 結構的複數:: 
* 作為 Python 物件的複數:: 

序列物件

* 位元組物件 (Bytes Objects): 位元組物件 Bytes Objects. 
* 位元組陣列物件 (Byte Array Objects): 位元組陣列物件 Byte Array Objects. 
* Unicode 物件與編解碼器:: 
* Tuple（元組）物件:: 
* Struct Sequence Objects:: 
* List（串列）物件:: 

位元組陣列物件 (Byte Array Objects)

* 型別檢查巨集:: 
* 直接 API 函式:: 
* 巨集:: 

Unicode 物件與編解碼器

* Unicode 物件:: 
* 內建編解碼器:: 
* Methods and Slot Functions:: 
* PyUnicodeWriter:: 
* 已棄用的 API:: 

Unicode 物件

* Unicode 型別:: 
* Unicode Character Properties:: 
* Creating and accessing Unicode strings:: 
* Locale Encoding:: 
* 檔案系統編碼:: 
* wchar_t 支援:: 

內建編解碼器

* 泛用編解碼器:: 
* UTF-8 編解碼器:: 
* UTF-32 編解碼器:: 
* UTF-16 編解碼器:: 
* UTF-7 編解碼器:: 
* Unicode-Escape Codecs:: 
* Raw-Unicode-Escape Codecs:: 
* Latin-1 編解碼器:: 
* ASCII 編解碼器:: 
* Character Map Codecs:: 
* Windows 的 MBCS 編解碼器:: 

容器物件

* 字典物件:: 
* 集合物件:: 

函式物件

* 函式物件 (Function Objects): 函式物件 Function Objects. 
* 實例方法物件 (Instance Method Objects): 實例方法物件 Instance Method Objects. 
* 方法物件 (Method Objects): 方法物件 Method Objects. 
* Cell 物件:: 
* 程式碼物件: 程式碼物件<3>. 
* 程式碼物件旗標:: 
* 額外資訊:: 

其他物件

* 檔案物件 (File Objects): 檔案物件 File Objects. 
* 模組物件:: 
* 模組定義:: 
* Creating extension modules dynamically:: 
* 支援的函式:: 
* 疊代器（Iterator）物件:: 
* Descriptor（描述器）物件:: 
* 切片物件:: 
* MemoryView 物件:: 
* 弱參照物件: 弱參照物件<2>. 
* Capsules: Capsules<2>. 
* Frame 物件:: 
* 產生器 (Generator) 物件: 產生器 Generator 物件. 
* Coroutine（協程）物件:: 
* 情境變數物件（Context Variables Objects）:: 
* DateTime 物件:: 
* 型別提示物件:: 

模組定義

* 模組槽 (Module slots): 模組槽 Module slots. 

支援的函式

* Module lookup (single-phase initialization): Module lookup single-phase initialization. 

切片物件

* Ellipsis 物件: Ellipsis 物件<2>. 

Frame 物件

* Frame Locals Proxies:: 
* Internal Frames:: 

初始化、終結化與執行緒

* Python 初始化之前:: 
* Global configuration variables:: 
* Initializing and finalizing the interpreter:: 
* Process-wide parameters:: 
* Thread State and the Global Interpreter Lock:: 
* Sub-interpreter support:: 
* Asynchronous Notifications:: 
* Profiling and Tracing:: 
* Reference tracing:: 
* Advanced Debugger Support:: 
* Thread Local Storage Support:: 
* Synchronization Primitives:: 

Thread State and the Global Interpreter Lock

* Detaching the thread state from extension code:: 
* Non-Python created threads:: 
* Supporting subinterpreters in non-Python threads:: 
* Cautions about fork(): Cautions about fork. 
* Cautions regarding runtime finalization:: 
* 高階 API:: 
* 低階 API:: 

Sub-interpreter support

* 直譯器各別持有的 GIL:: 
* Bugs and caveats:: 

Thread Local Storage Support

* Thread Specific Storage (TSS) API: Thread Specific Storage TSS API. 
* 執行緒局部儲存 (Thread Local Storage@comma{} TLS) API：: 執行緒局部儲存 Thread Local Storage TLS API：. 

Thread Specific Storage (TSS) API

* Dynamic Allocation:: 
* 方法: 方法<2>. 

Synchronization Primitives

* Python Critical Section API:: 

Python 初始化設定

* PyInitConfig C API:: 
* Configuration Options:: 
* Runtime Python configuration API:: 
* PyConfig C API:: 
* Py_GetArgcArgv(): Py_GetArgcArgv. 
* Delaying main module execution:: 

PyInitConfig C API

* 範例: 範例<53>. 
* 建立設定:: 
* 錯誤處理: 錯誤處理<2>. 
* Get Options:: 
* Set Options:: 
* 模組: 模組<5>. 
* 初始化 Python:: 

PyConfig C API

* 範例: 範例<54>. 
* PyWideStringList:: 
* PyStatus:: 
* PyPreConfig:: 
* Preinitialize Python with PyPreConfig:: 
* PyConfig:: 
* Initialization with PyConfig:: 
* Isolated Configuration:: 
* Python Configuration:: 
* Python 路徑配置:: 

記憶體管理

* 總覽: 總覽<2>. 
* Allocator Domains:: 
* Raw 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:: 
* 範例: 範例<55>. 

The pymalloc allocator

* Customize pymalloc Arena Allocator:: 

物件實作支援

* 在 heap 上分配物件:: 
* 物件生命週期:: 
* 通用物件結構:: 
* 型別物件結構:: 
* 循環垃圾回收的支援:: 

物件生命週期

* 生命事件:: 
* Cyclic Isolate Destruction:: 
* 函式: 函式<14>. 

通用物件結構

* Base object types and macros:: 
* 實作函式與方法:: 
* Accessing attributes of extension types:: 

Accessing attributes of extension types

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

型別物件結構

* Quick Reference:: 
* PyTypeObject Definition:: 
* PyObject Slots:: 
* PyVarObject Slots:: 
* PyTypeObject Slots:: 
* 靜態型別:: 
* 堆積型別:: 
* Number Object Structures:: 
* 對映物件結構:: 
* 序列物件結構:: 
* 緩衝區物件結構:: 
* 非同步物件結構:: 
* Slot Type typedefs:: 
* 範例: 範例<56>. 

Quick Reference

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

循環垃圾回收的支援

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

API 和 ABI 版本管理

* Build-time version constants:: 
* Run-time version:: 
* Bit-packing macros:: 

Generating Execution Events

* Managing the Monitoring State:: 

安裝 Python 模組

* 關鍵術語:: 
* 基本用法: 基本用法<5>. 
* 我該如何...？: 我該如何 ？. 
* 常見的安裝問題:: 

我該如何...？

* ...在 Python 3.4 之前的 Python 版本中安裝 pip？: 在 Python 3 4 之前的 Python 版本中安裝 pip？. 
* ...只為目前的使用者安裝套件？: 只為目前的使用者安裝套件？. 
* ...安裝科學的 Python 套件？: 安裝科學的 Python 套件？. 
* ...平行安裝多個 Python 版本並使用它們？: 平行安裝多個 Python 版本並使用它們？. 

常見的安裝問題

* 在 Linux 上安裝套件至系統 Python:: 
* 未安裝 pip:: 
* 安裝二進制擴充 (binary extension): 安裝二進制擴充 binary extension. 

Python 如何達成任務

* asyncio 的概念性總覽:: 
* 遷移延伸模組到 Python 3:: 
* Curses Programming with Python:: 
* 描述器 (Descriptor) 指南: 描述器 Descriptor 指南. 
* 使用 GDB 來為 C API 擴充功能和 CPython 內部偵錯:: 
* Enum HOWTO:: 
* 函式程式設計 HOWTO:: 
* 如何使用 Logging 模組:: 
* Logging Cookbook:: 
* 如何使用正規表示式:: 
* Socket 程式設計指南:: 
* 排序技法:: 
* Unicode HOWTO:: 
* 如何使用 urllib 套件取得網路資源:: 
* ipaddress 模組介紹:: 
* 使用 DTrace 和 SystemTap 檢測 CPython:: 
* Python 對 Linux perf 分析器的支援:: 
* 註釋 (annotation) 最佳實踐: 註釋 annotation 最佳實踐. 
* 隔離擴充模組:: 
* 計時器檔案描述器 (timerfd) 指南: 計時器檔案描述器 timerfd 指南. 
* The Python 2.3 Method Resolution Order: The Python 2 3 Method Resolution Order. 
* Python 自由執行緒的支援:: 
* 支援自由執行緒的 C API 擴充:: 
* Remote debugging attachment protocol:: 
* Permission requirements:: 
* Locating the PyRuntime structure:: 
* 讀取 _Py_DebugOffsets:: 
* Locating the interpreter and thread state:: 
* Writing control information:: 
* Summary:: 

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

* 事件迴圈: 事件迴圈<2>. 
* 非同步函式與協程:: 
* Tasks:: 
* await:: 

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:: 
* 使用者輸入:: 
* For More Information:: 

What is curses?

* Python curses 模組:: 

Displaying Text

* Attributes and Color:: 

描述器 (Descriptor) 指南

* 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

* 摘要:: 
* Definition and introduction:: 
* 描述器協定:: 
* Overview of descriptor invocation:: 
* Invocation from an instance:: 
* Invocation from a class:: 
* Invocation from super:: 
* Summary of invocation logic:: 
* Automatic name notification:: 
* ORM 範例:: 

Pure Python Equivalents

* Properties:: 
* Functions and methods:: 
* Kinds of methods:: 
* Static methods:: 
* Class methods:: 
* Member objects and __slots__:: 

使用 GDB 來為 C API 擴充功能和 CPython 內部偵錯

* 先決條件:: 
* 使用偵錯建置與使用開發模式:: 
* 使用 python-gdb 擴充功能:: 
* 與 GDB 指令一起使用:: 

先決條件

* 使用從原始碼建置的 Python 進行設定:: 
* 從 Linux 發行版設定 Python:: 

使用 python-gdb 擴充功能

* 漂亮列印器:: 
* py-list:: 
* py-up 和 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:: 
* 比較:: 
* Allowed members and attributes of enumerations:: 
* Restricted Enum subclassing:: 
* Dataclass support:: 
* Pickling:: 
* Functional API: Functional API<3>. 
* Derived Enumerations:: 
* When to use __new__() vs. __init__(): When to use __new__ vs __init__. 
* Enums 和 Flags 有何不同？:: 
* Enum Cookbook:: 
* 子類別化 EnumType:: 

Derived Enumerations

* IntEnum:: 
* StrEnum:: 
* IntFlag:: 
* Flag:: 
* 其他: 其他<2>. 

When to use __new__() vs. __init__()

* Finer Points:: 

Finer Points

* 有支援的 __dunder__ 名稱:: 
* 有支援的 _sunder_ 名稱:: 
* _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:: 
* Flag 的成員組合:: 
* Flag and IntFlag minutia:: 

Enums 和 Flags 有何不同？

* Enum 類別:: 
* Flag 類別:: 
* Enum Members (aka instances): Enum Members aka instances. 
* Flag 成員:: 

Enum Cookbook

* 省略值:: 
* OrderedEnum:: 
* DuplicateFreeEnum:: 
* MultiValueEnum:: 
* Planet:: 
* TimePeriod:: 

省略值

* 使用 auto:: 
* 使用 object:: 
* Using a descriptive string:: 
* 使用自訂的 __new__(): 使用自訂的 __new__. 

函式程式設計 HOWTO

* 簡介: 簡介<11>. 
* 疊代器:: 
* 產生器運算式與串列綜合運算式:: 
* 產生器:: 
* 內建函式: 內建函式<3>. 
* itertools 模組:: 
* functools 模組:: 
* Small functions and the lambda expression:: 
* Revision History and Acknowledgements:: 
* References: References<2>. 

簡介

* 形式可證明性:: 
* 模組化:: 
* 容易除錯與測試:: 
* 可組合性:: 

疊代器

* Data Types That Support Iterators:: 

產生器

* Passing values into a generator:: 

itertools 模組

* 建立新的疊代器:: 
* Calling functions on elements:: 
* Selecting elements:: 
* Combinatoric functions:: 
* Grouping elements:: 

functools 模組

* operator 模組:: 

References

* General:: 
* Python 特有的:: 
* Python 說明文件:: 

如何使用 Logging 模組

* 基礎 Logging 指南:: 
* Advanced Logging Tutorial:: 
* Logging Levels: Logging Levels<2>. 
* Useful Handlers:: 
* Exceptions raised during logging:: 
* Using arbitrary objects as messages:: 
* 最佳化: 最佳化<19>. 
* 其他資源: 其他資源<2>. 

基礎 Logging 指南

* 什麼時候使用 logging:: 
* 一個簡單範例: 一個簡單範例<2>. 
* 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:: 
* 其他資源: 其他資源<3>. 

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

* 使用 concurrent.futures.ProcessPoolExecutor: 使用 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:: 

如何使用正規表示式

* 簡介: 簡介<12>. 
* 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:: 
* 模組層級函式: 模組層級函式<2>. 
* Compilation Flags:: 

More Pattern Power

* More Metacharacters:: 
* Grouping:: 
* Non-capturing and Named Groups:: 
* Lookahead Assertions:: 

Modifying Strings

* Splitting Strings:: 
* Search and Replace: Search and Replace<2>. 

Common Problems

* Use String Methods:: 
* match() versus search(): match versus search. 
* Greedy versus Non-Greedy:: 
* Using re.VERBOSE: Using re VERBOSE. 

Socket 程式設計指南

* Sockets:: 
* 建立一個 Socket:: 
* 使用一個 Socket:: 
* 結束連線:: 
* 非阻塞的 Sockets:: 

Sockets

* 歷史:: 

建立一個 Socket

* IPC:: 

使用一個 Socket

* 二進位資料:: 

結束連線

* Sockets 何時銷毀:: 

排序技法

* 基礎排序:: 
* 鍵函式 (key functions): 鍵函式 key functions. 
* Operator 模組函式以及部份函式 (partial function) 評估: Operator 模組函式以及部份函式 partial function 評估. 
* 升冪與降冪:: 
* 排序穩定性與複合排序:: 
* 裝飾-排序-移除裝飾 (decorate-sort-undecorate): 裝飾-排序-移除裝飾 decorate-sort-undecorate. 
* 比較函式 (comparison functions): 比較函式 comparison functions. 
* Strategies For Unorderable Types and Values:: 
* 雜項說明:: 
* 部份排序:: 

Unicode HOWTO

* Introduction to Unicode:: 
* Python's Unicode Support:: 
* Reading and Writing Unicode Data:: 
* 致謝: 致謝<10>. 

Introduction to Unicode

* 定義:: 
* Encodings:: 
* References: References<3>. 

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

Reading and Writing Unicode Data

* Unicode filenames:: 
* Tips for Writing Unicode-aware Programs:: 
* References: References<5>. 

Tips for Writing Unicode-aware Programs

* Converting Between File Encodings:: 
* Files in an Unknown Encoding:: 

如何使用 urllib 套件取得網路資源

* 簡介: 簡介<13>. 
* 從 URL 取得資源:: 
* Handling Exceptions:: 
* info and geturl:: 
* Openers and Handlers:: 
* Basic Authentication:: 
* Proxies:: 
* Sockets and Layers:: 
* 註腳:: 

從 URL 取得資源

* Data:: 
* Headers:: 

Handling Exceptions

* URLError:: 
* HTTPError:: 
* Wrapping it Up:: 

HTTPError

* Error Codes:: 

Wrapping it Up

* Number 1:: 
* Number 2:: 

ipaddress 模組介紹

* 建立 Address/Network/Interface 物件:: 
* 檢視 Address/Network/Interface 物件:: 
* Networks as lists of Addresses:: 
* 比較: 比較<2>. 
* Using IP Addresses with other modules:: 
* Getting more detail when instance creation fails:: 

建立 Address/Network/Interface 物件

* A Note on IP Versions:: 
* IP Host Addresses:: 
* 定義網路:: 
* Host Interfaces:: 

使用 DTrace 和 SystemTap 檢測 CPython

* 啟用靜態標記:: 
* 靜態 DTrace 探針:: 
* 靜態 SystemTap 標記:: 
* 可用的靜態標記:: 
* SystemTap Tapsets:: 
* 範例: 範例<57>. 

Python 對 Linux perf 分析器的支援

* 如何啟用 perf 分析支援:: 
* 如何獲得最佳結果:: 
* How to work without frame pointers:: 

註釋 (annotation) 最佳實踐

* 在 Python 3.10 及更高版本中存取物件的註釋字典: 在 Python 3 10 及更高版本中存取物件的註釋字典. 
* 在 Python 3.9 及更早版本中存取物件的註釋字典: 在 Python 3 9 及更早版本中存取物件的註釋字典. 
* 手動取消字串化註釋:: 
* 任何 Python 版本中 __annotations__ 的最佳實踐:: 
* __annotations__ 奇異之處:: 

隔離擴充模組

* Who should read this:: 
* 背景: 背景<2>. 
* Making Modules Safe with Multiple Interpreters:: 
* Heap Types:: 
* Open Issues:: 

背景

* 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:: 
* 定義 tp_dealloc:: 
* Not overriding tp_free:: 
* 避免使用 PyObject_New:: 

Open Issues

* Per-Class Scope:: 
* Lossless Conversion to Heap Types:: 

計時器檔案描述器 (timerfd) 指南

* 範例: 範例<58>. 

The Python 2.3 Method Resolution Order

* The beginning:: 
* The C3 Method Resolution Order:: 
* 範例: 範例<59>. 
* Bad Method Resolution Orders:: 
* The end:: 
* Resources:: 

Python 自由執行緒的支援

* 安裝: 安裝<2>. 
* Identifying free-threaded Python:: 
* The global interpreter lock in free-threaded Python:: 
* 執行緒安全: 執行緒安全<2>. 
* 已知限制:: 
* Behavioral changes:: 

已知限制

* 不滅化 (Immortalization): 不滅化 Immortalization. 
* Frame objects: Frame objects<2>. 
* 疊代器: 疊代器<2>. 
* 單執行緒效能:: 

Behavioral changes

* Context variables:: 
* Warning filters:: 

支援自由執行緒的 C API 擴充

* Identifying the Free-Threaded Build in C:: 
* 模組初始化:: 
* General API Guidelines:: 
* 借用參照:: 
* Memory Allocation APIs:: 
* Thread State and GIL APIs:: 
* Protecting Internal Extension State:: 
* Critical Sections:: 
* Building Extensions for the Free-Threaded Build:: 

模組初始化

* Multi-Phase Initialization:: 
* 單一階段初始化 (Single-Phase Initialization): 單一階段初始化 Single-Phase Initialization. 

General API Guidelines

* 容器執行緒安全性:: 

容器執行緒安全性

* PyDict_Next:: 

Critical Sections

* What Are Critical Sections?:: 
* Using Critical Sections:: 
* How Critical Sections Work:: 
* Deadlock Avoidance:: 
* Important Considerations:: 

Building Extensions for the Free-Threaded Build

* Limited C API and Stable ABI:: 
* Windows: Windows<83>. 

Python 常見問題

* 一般的 Python 常見問答集:: 
* 程式開發常見問答集:: 
* 設計和歷史常見問答集:: 
* 函式庫和擴充功能的常見問題:: 
* 擴充/嵌入常見問題集:: 
* 在 Windows 使用 Python 的常見問答集:: 
* 圖形使用者介面常見問答集:: 
* 「為什麼 Python 被安裝在我的機器上？」常見問答集:: 

一般的 Python 常見問答集

* 一般資訊:: 
* 在真實世界中的 Python:: 

一般資訊

* 什麼是 Python？:: 
* 什麼是 Python 軟體基金會？:: 
* 使用 Python 時有任何版權限制嗎？:: 
* 當初為什麼 Python 會被創造出來？:: 
* 什麼是 Python 擅長的事情？:: 
* Python 的版本編號系統是如何運作的？:: 
* 我要如何得到 Python 的原始碼複本？:: 
* 我要如何取得 Python 的說明文件？:: 
* 我從來沒有寫過程式，有沒有 Python 的教學？:: 
* 有沒有 Python 專屬的新聞群組或郵件討論群？:: 
* 如何取得 Python 的 beta 測試版本？:: 
* 如何提交 Python 的錯誤報告和修補程式？:: 
* 是否有關於 Python 的任何已出版文章可供參考？:: 
* 有沒有關於 Python 的書？:: 
* www.python.org 的真實位置在哪裡？: www python org 的真實位置在哪裡？. 
* 為什麼要取名為 Python？:: 
* 我需要喜歡「Monty Python 的飛行馬戲團」嗎？:: 

在真實世界中的 Python

* Python 的穩定性如何？:: 
* 有多少人在使用 Python？:: 
* 有沒有任何重要的專案使用 Python 完成開發？:: 
* Python 未來預期會有哪些新的開發？:: 
* 對 Python 提出不相容的變更建議是否適當？:: 
* Python 對於入門的程式設計師而言是否為好的語言？:: 

程式開發常見問答集

* 常見問題:: 
* 核心語言:: 
* 數字和字串:: 
* 效能: 效能<3>. 
* 序列（元組/串列）:: 
* 物件:: 
* 模組: 模組<6>. 

常見問題

* 是否有可以使用在程式碼階段@comma{}具有中斷點@comma{}步驟執行等功能的除錯器？: 是否有可以使用在程式碼階段 具有中斷點 步驟執行等功能的除錯器？. 
* 有沒有工具能夠幫忙找 bug 或執行靜態分析？:: 
* 如何從 Python 腳本建立獨立的二進位檔案？:: 
* Python 程式碼是否有編碼標準或風格指南？:: 

核心語言

* 為什麼當變數有值時，我仍得到錯誤訊息 UnboundLocalError？:: 
* Python 的區域變數和全域變數有什麼規則？:: 
* 為什麼以不同的值在迴圈中定義的 lambda 都回傳相同的結果？:: 
* 如何跨模組共享全域變數？:: 
* 在模組中使用 import 的「最佳實踐」有哪些？:: 
* 為什麼物件之間共享預設值？:: 
* How can I pass optional or keyword parameters from one function to another?:: 
* 引數 (arguments) 和參數 (parameters) 有什麼區別？: 引數 arguments 和參數 parameters 有什麼區別？. 
* 為什麼更改串列 'y' 也會更改串列 'x'？:: 
* 如何編寫帶有輸出參數的函式（透過傳參照呼叫 (call by reference)）？: 如何編寫帶有輸出參數的函式（透過傳參照呼叫 call by reference ）？. 
* 你如何在 Python 中建立高階函式？:: 
* 如何在 Python 中複製物件？:: 
* 如何找到物件的方法或屬性？:: 
* 我的程式碼如何發現物件的名稱？:: 
* 逗號運算子的優先級是什麼？:: 
* 是否有等效於 C 的 "?;" 三元運算子？: 是否有等效於 C 的 "? " 三元運算子？. 
* Is it possible to write obfuscated one-liners in Python?:: 
* 函式參數串列中的斜線 (/) 是什麼意思？: 函式參數串列中的斜線 / 是什麼意思？. 

數字和字串

* 如何指定十六進位和八進位整數？:: 
* 為什麼 -22 // 10 回傳 -3？:: 
* How do I get int literal attribute instead of SyntaxError?:: 
* 如何將字串轉換為數字？:: 
* 如何將數字轉換為字串？:: 
* 如何原地修改字串？:: 
* 如何使用字串呼叫函式/方法？:: 
* Is there an equivalent to Perl's chomp() for removing trailing newlines from strings?: Is there an equivalent to Perl's chomp for removing trailing newlines from strings?. 
* Is there a scanf() or sscanf() equivalent?: Is there a scanf or sscanf equivalent?. 
* What does UnicodeDecodeError or UnicodeEncodeError error mean?:: 
* Can I end a raw string with an odd number of backslashes?:: 

效能

* 我的程式太慢了。我該如何加快速度？:: 
* What is the most efficient way to concatenate many strings together?:: 

序列（元組/串列）

* 如何在元組和串列之間進行轉換？:: 
* 什麼是負索引？:: 
* How do I iterate over a sequence in reverse order?:: 
* 如何從串列中刪除重複項？:: 
* 如何從串列中刪除多個項目:: 
* How do you make an array in Python?:: 
* 如何建立多維度串列？:: 
* 如何將方法或函式應用於物件序列？:: 
* 為什麼 a_tuple[i] += ['item'] 做加法時會引發例外？:: 
* 我想做一個複雜的排序：你能用 Python 做一個 Schwartzian 變換嗎？:: 
* 如何根據另一個串列中的值對一個串列進行排序？:: 

物件

* 什麼是類別 (class)？: 什麼是類別 class ？. 
* 什麼是方法 (method)？: 什麼是方法 method ？. 
* 什麼是 self？:: 
* 如何檢查物件是否是給定類別的實例或其子類別的實例？:: 
* 什麼是委派 (delegation)？: 什麼是委派 delegation ？. 
* How do I call a method defined in a base class from a derived class that extends it?:: 
* 我可以如何組織我的程式碼以使得更改基底類別變的更容易？:: 
* 如何建立靜態類別資料和靜態類別方法？:: 
* 如何在 Python 中多載 (overload) 建構函式（或方法）？: 如何在 Python 中多載 overload 建構函式（或方法）？. 
* 我嘗試使用 __spam，但收到有關 _SomeClassName__spam 的錯誤。:: 
* 我的類別定義了 __del__ 但是當我刪除物件時它沒有被呼叫。:: 
* 我該如何取得給定類別的所有實例的串列？:: 
* 為什麼 id() 的結果看起來不唯一？: 為什麼 id 的結果看起來不唯一？. 
* 我什麼時候可以依靠 is 運算子進行識別性測試？:: 
* 子類別如何控制不可變實例中儲存的資料？:: 
* 如何快取方法呼叫？:: 

模組

* 如何建立 .pyc 檔案？: 如何建立 pyc 檔案？. 
* 如何找到目前模組名稱？:: 
* 要怎樣才能擁有相互引入的模組？:: 
* __import__('x.y.z') 回傳 <module 'x'>，那我怎麼得到 z？: __import__ 'x y z' 回傳 <module 'x'>，那我怎麼得到 z？. 
* 當我編輯需要引入的模組並重新引入它時，更動沒有反應出來。為什麼會這樣？:: 

設計和歷史常見問答集

* 為什麼 Python 使用縮排將陳述式進行分組？:: 
* 為什麼我會從簡單的數學運算得到奇怪的結果？:: 
* 為何浮點數運算如此不精確？:: 
* 為什麼 Python 字串不可變動？:: 
* 為何「self」在方法 (method) 定義和呼叫時一定要明確使用？: 為何「self」在方法 method 定義和呼叫時一定要明確使用？. 
* 為何我不能在運算式 (expression) 中使用指派運算？: 為何我不能在運算式 expression 中使用指派運算？. 
* 為何 Python 對於一些功能實作使用方法（像是 list.index()），另一些使用函式（像是 len(list)）？: 為何 Python 對於一些功能實作使用方法（像是 list index ），另一些使用函式（像是 len list ）？. 
* 為何 join() 是字串方法而非串列 (list) 或元組 (tuple) 方法？: 為何 join 是字串方法而非串列 list 或元組 tuple 方法？. 
* 例外處理有多快？:: 
* 為什麼 Python 內沒有 switch 或 case 陳述式？:: 
* 為何不能在直譯器上模擬執行緒，而要使用作業系統的特定實作方式？:: 
* 為何 lambda 運算式不能包含陳述式？:: 
* Python 可以被編譯成機器語言、C 語言或其他種語言嗎？:: 
* Python 如何管理記憶體？:: 
* 為何 CPython 不使用更多傳統的垃圾回收機制？:: 
* 當 CPython 結束時，為何所有的記憶體不會被釋放？:: 
* 為何要把元組 (tuple) 和串列 (list) 分成兩個資料型態？: 為何要把元組 tuple 和串列 list 分成兩個資料型態？. 
* 串列 (list) 在 CPython 中是怎麼實作的？: 串列 list 在 CPython 中是怎麼實作的？. 
* 字典 (dictionaries) 在 CPython 中是怎麼實作的？: 字典 dictionaries 在 CPython 中是怎麼實作的？. 
* 為何字典的鍵一定是不可變的？:: 
* 為何 list.sort() 不是回傳排序過的串列？: 為何 list sort 不是回傳排序過的串列？. 
* 如何在 Python 中指定和強制使用一個介面規範 (interface spec)？: 如何在 Python 中指定和強制使用一個介面規範 interface spec ？. 
* 為何沒有 goto 語法？:: 
* 為何純字串 (r-string) 不能以反斜線結尾？: 為何純字串 r-string 不能以反斜線結尾？. 
* 為何 Python 沒有屬性賦值的 with 陳述式？:: 
* 為何產生器 (generator) 不支援 with 陳述式？: 為何產生器 generator 不支援 with 陳述式？. 
* 為何 if、while、def、class 陳述式裡需要冒號？:: 
* 為何 Python 允許在串列和元組末端加上逗號？:: 

函式庫和擴充功能的常見問題

* 常見函式問題:: 
* 常見課題:: 
* 執行緒:: 
* 輸入與輸出:: 
* 網路 (Network)/網際網路 (Internet) 程式: 網路 Network /網際網路 Internet 程式. 
* 資料庫:: 
* 數學和數值:: 

常見函式問題

* 我如何找到執行任務 X 的模組或應用程式？:: 
* 哪裡可以找到 math.py (socket.py@comma{} regex.py@comma{} 等...) 來源檔案？: 哪裡可以找到 math py socket py regex py 等 來源檔案？. 
* 我如何使 Python script 執行在 Unix？:: 
* 是否有適用於 Python 的 curses/termcap 套件？:: 
* Python 中是否有等同於 C 的 onexit() 的函式？: Python 中是否有等同於 C 的 onexit 的函式？. 
* 為什麼我的訊號處理程式不起作用？:: 

常見課題

* 如何測試 Python 程式或元件？:: 
* 如何從文件字串建立文件？:: 
* How do I get a single keypress at a time?:: 

執行緒

* 如何使用執行緒編寫程式？:: 
* 我的執行緒似乎都沒有運行：為什麼？:: 
* How do I parcel out work among a bunch of worker threads?:: 
* 什麼樣的全域值變化是執行緒安全的？:: 
* 不能擺脫全域直譯器鎖嗎？:: 

輸入與輸出

* 如何刪除檔案？（以及其他檔案問題...）: 如何刪除檔案？（以及其他檔案問題 ）. 
* 如何複製檔案？:: 
* 如何讀取（或寫入）二進位制資料？:: 
* 我似乎無法在用 os.popen() 建立的 pipe 上使用 os.read()；為什麼？: 我似乎無法在用 os popen 建立的 pipe 上使用 os read ；為什麼？. 
* 如何存取序列 (RS232) 連接埠？: 如何存取序列 RS232 連接埠？. 
* 為什麼關閉 sys.stdout (stdin@comma{} stderr) 並沒有真正關閉它？: 為什麼關閉 sys stdout stdin stderr 並沒有真正關閉它？. 

網路 (Network)/網際網路 (Internet) 程式

* Python 有哪些 WWW 工具？:: 
* 我應該使用什麼模組來輔助產生 HTML？:: 
* 如何從 Python 腳本發送郵件？:: 
* 如何避免阻塞 socket 的 connect() 方法？: 如何避免阻塞 socket 的 connect 方法？. 

資料庫

* Python 中是否有任何資料庫套件的介面？:: 
* 你如何在 Python 中實作持久性物件？:: 

數學和數值

* 如何在 Python 中生成隨機數？:: 

擴充/嵌入常見問題集

* 我可以在 C 中建立自己的函式嗎？:: 
* 我可以在 C++ 中建立自己的函式嗎？:: 
* 寫 C 很難；還有其他選擇嗎？:: 
* 如何從 C 執行任意 Python 陳述式？:: 
* 如何計算來自 C 的任意 Python 運算式？:: 
* 如何從 Python 物件中提取 C 值？:: 
* 如何使用 Py_BuildValue() 建立任意長度的元組？: 如何使用 Py_BuildValue 建立任意長度的元組？. 
* 如何從 C 呼叫物件的方法？:: 
* 我如何捕捉 PyErr_Print() 的輸出（或任何印出到 stdout/stderr 的東西）？: 我如何捕捉 PyErr_Print 的輸出（或任何印出到 stdout/stderr 的東西）？. 
* 如何從 C 存取用 Python 編寫的模組？:: 
* 我如何從 Python 介接到 C++ 物件？:: 
* 我使用安裝檔案新增了一個模組，但 make 失敗了；為什麼？:: 
* 如何為擴充套件除錯？:: 
* 我想在我的 Linux 系統上編譯一個 Python 模組，但是缺少一些檔案。為什麼？:: 
* 如何從「無效輸入」區分出「不完整輸入」？:: 
* 如何找到未定義的 g++ 符號 __builtin_new 或 __pure_virtual？:: 
* 我可以用一些用 C 實作的方法和用 Python 實作的其他方法（例如透過繼承）建立一個物件類別嗎？:: 

在 Windows 使用 Python 的常見問答集

* 如何在 Windows 作業系統裡運行 Python 程式？:: 
* 如何使 Python 腳本可以執行？:: 
* 為什麼 Python 有時需要這麼長的時間才能開始？:: 
* 如何從 Python 腳本製作可執行檔？:: 
* *.pyd 檔是否與 DLL 相同？: * pyd 檔是否與 DLL 相同？. 
* 如何將 Python 嵌入 Windows 應用程式中？:: 
* 如何防止編輯器在我的 Python 原始碼中插入 tab？:: 
* 如何在不阻塞的情況下檢查 keypress？:: 
* 如何解決遺漏 api-ms-win-crt-runtime-l1-1-0.dll 的錯誤？: 如何解決遺漏 api-ms-win-crt-runtime-l1-1-0 dll 的錯誤？. 

圖形使用者介面常見問答集

* 圖形使用者介面 (GUI) 的常見問題: 圖形使用者介面 GUI 的常見問題. 
* Python 有哪些 GUI 套件？:: 
* Tkinter 的問答:: 

Tkinter 的問答

* 如何凍結 Tkinter 應用程式？:: 
* 是否可以在等待 I/O 時處理 Tk 事件？:: 
* 我無法讓鍵繫結 (key binding) 在 Tkinter 中作用：為什麼？: 我無法讓鍵繫結 key binding 在 Tkinter 中作用：為什麼？. 

「為什麼 Python 被安裝在我的機器上？」常見問答集

* 什麼是 Python？: 什麼是 Python？<2>. 
* 為什麼 Python 被安裝在我的機器上?:: 
* 我能夠自行刪除 Python 嗎？:: 

已棄用項目

* Python 3.15 中待移除的項目: Python 3 15 中待移除的項目<7>. 
* Python 3.16 中待移除的項目: Python 3 16 中待移除的項目<7>. 
* Python 3.17 中待移除的項目: Python 3 17 中待移除的項目<4>. 
* Python 3.19 中待移除的項目: Python 3 19 中待移除的項目<2>. 
* 未來版本中的待移除項目: 未來版本中的待移除項目<7>. 
* C API 的棄用項目:: 

C API 的棄用項目

* Python 3.15 中待移除的項目: Python 3 15 中待移除的項目<8>. 
* Python 3.18 中待移除的項目: Python 3 18 中待移除的項目<3>. 
* 未來版本中的待移除項目: 未來版本中的待移除項目<8>. 

關於這份說明文件

* Python 文件的貢獻者們:: 

處理錯誤 (Bug)

* 說明文件的錯誤:: 
* 使用 Python 問題追蹤系統:: 
* 開始讓自己貢獻 Python:: 

沿革與授權

* 軟體沿革:: 
* 關於存取或以其他方式使用 Python 的合約條款:: 
* 被收錄軟體的授權與致謝:: 

關於存取或以其他方式使用 Python 的合約條款

* PYTHON SOFTWARE FOUNDATION LICENSE VERSION 2:: 
* BEOPEN.COM LICENSE AGREEMENT FOR PYTHON 2.0: BEOPEN COM LICENSE AGREEMENT FOR PYTHON 2 0. 
* CNRI LICENSE AGREEMENT FOR PYTHON 1.6.1: CNRI LICENSE AGREEMENT FOR PYTHON 1 6 1. 
* CWI LICENSE AGREEMENT FOR PYTHON 0.9.0 THROUGH 1.2: CWI LICENSE AGREEMENT FOR PYTHON 0 9 0 THROUGH 1 2. 
* ZERO-CLAUSE BSD LICENSE FOR CODE IN THE PYTHON DOCUMENTATION:: 

被收錄軟體的授權與致謝

* Mersenne Twister:: 
* Sockets: Sockets<2>. 
* 非同步 socket 服務:: 
* Cookie 管理:: 
* 執行追蹤:: 
* UUencode 與 UUdecode 函式:: 
* XML 遠端程序呼叫:: 
* test_epoll:: 
* Select kqueue:: 
* SipHash24:: 
* strtod 與 dtoa:: 
* OpenSSL: OpenSSL<2>. 
* expat:: 
* libffi:: 
* zlib: zlib<4>. 
* cfuhash:: 
* libmpdec:: 
* W3C C14N 測試套件:: 
* mimalloc:: 
* asyncio: asyncio<15>. 
* Global Unbounded Sequences (GUS): Global Unbounded Sequences GUS. 
* Zstandard bindings:: 

@end detailmenu
@end menu

@node Python 有什麼新功能？,Python 教學,Top,Top
@anchor{whatsnew/index doc}@anchor{13c}@anchor{whatsnew/index python-documentation-contents}@anchor{13d}@anchor{whatsnew/index what-s-new-in-python}@anchor{13e}@anchor{whatsnew/index whatsnew-index}@anchor{13f}
@chapter Python 有什麼新功能？


「Python 有什麼新功能」這系列的說明是讓使用者知道 Python 各個主要更新版本之間的重大改變的地方。對於希望在新版本釋出時立即了解版本差異的使用者們來說，這些說明被歸類為「必讀」的等級。

@menu
* Python 3.14 有什麼新功能: Python 3 14 有什麼新功能. 
* Python 3.13 有什麼新功能: Python 3 13 有什麼新功能. 
* Python 3.12 有什麼新功能: Python 3 12 有什麼新功能. 
* Python 3.11 有什麼新功能: Python 3 11 有什麼新功能. 
* Python 3.10 有什麼新功能: Python 3 10 有什麼新功能. 
* Python 3.9 有什麼新功能: Python 3 9 有什麼新功能. 
* Python 3.8 有什麼新功能: Python 3 8 有什麼新功能. 
* Python 3.7 有什麼新功能: Python 3 7 有什麼新功能. 
* Python 3.6 有什麼新功能: Python 3 6 有什麼新功能. 
* Python 3.5 有什麼新功能: Python 3 5 有什麼新功能. 
* Python 3.4 有什麼新功能: Python 3 4 有什麼新功能. 
* Python 3.3 有什麼新功能: Python 3 3 有什麼新功能. 
* Python 3.2 有什麼新功能: Python 3 2 有什麼新功能. 
* Python 3.1 有什麼新功能: Python 3 1 有什麼新功能. 
* Python 3.0 有什麼新功能: Python 3 0 有什麼新功能. 
* Python 2.7 有什麼新功能: Python 2 7 有什麼新功能. 
* Python 2.6 有什麼新功能: Python 2 6 有什麼新功能. 
* Python 2.5 有什麼新功能: Python 2 5 有什麼新功能. 
* Python 2.4 有什麼新功能: Python 2 4 有什麼新功能. 
* Python 2.3 有什麼新功能: Python 2 3 有什麼新功能. 
* Python 2.2 有什麼新功能: Python 2 2 有什麼新功能. 
* Python 2.1 有什麼新功能: Python 2 1 有什麼新功能. 
* Python 2.0 有什麼新功能: Python 2 0 有什麼新功能. 
* Changelog（更動日誌）:: 

@end menu

@node Python 3 14 有什麼新功能,Python 3 13 有什麼新功能,,Python 有什麼新功能？
@anchor{whatsnew/3 14 doc}@anchor{140}@anchor{whatsnew/3 14 what-s-new-in-python-3-14}@anchor{141}
@section Python 3.14 有什麼新功能


@*編輯者: 
Adam Turner 和 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{142,,changelog}.


@subsubheading 也參考


@geindex Python Enhancement Proposals; PEP 745
PEP 745@footnote{https://peps.python.org/pep-0745/} - Python 3.14 發佈時程


@menu
* Summary: Summary -- Release highlights. Release highlights
* New features:: 
* Other language changes:: 
* New modules:: 
* Improved modules:: 
* 最佳化:: 
* 已移除:: 
* 已棄用:: 
* CPython 位元組碼變更:: 
* C API 變更:: 
* 建置變更:: 
* 移植至 Python 3.14: 移植至 Python 3 14. 

@end menu

@node Summary -- Release highlights,New features,,Python 3 14 有什麼新功能
@anchor{whatsnew/3 14 summary-release-highlights}@anchor{143}
@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{144,,template string literals},
@ref{145,,deferred evaluation of annotations},
and support for @ref{146,,subinterpreters} in
the standard library.

The library changes include significantly improved capabilities for
@ref{147,,introspection in asyncio},
@ref{148,,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{149,,Library Reference}
and @ref{14a,,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{14b,,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{145,,Deferred evaluation of annotations}

@item 
@geindex Python Enhancement Proposals; PEP 734
PEP 734@footnote{https://peps.python.org/pep-0734/}: @ref{146,,Multiple interpreters in the standard library}

@item 
@geindex Python Enhancement Proposals; PEP 750
PEP 750@footnote{https://peps.python.org/pep-0750/}: @ref{144,,Template strings}

@item 
@geindex Python Enhancement Proposals; PEP 758
PEP 758@footnote{https://peps.python.org/pep-0758/}: @ref{14c,,Allow except and except* expressions without brackets}

@item 
@geindex Python Enhancement Proposals; PEP 765
PEP 765@footnote{https://peps.python.org/pep-0765/}: @ref{14d,,Control flow in finally blocks}

@item 
@geindex Python Enhancement Proposals; PEP 768
PEP 768@footnote{https://peps.python.org/pep-0768/}: @ref{14e,,Safe external debugger interface for CPython}

@item 
@ref{14f,,A new type of interpreter}

@item 
@ref{150,,Free-threaded mode improvements}

@item 
@ref{151,,Improved error messages}

@item 
@ref{152,,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{148,,Zstandard support in the standard library}

@item 
@ref{147,,Asyncio introspection capabilities}

@item 
@ref{153,,Concurrent safe warnings control}

@item 
@ref{154,,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{155,,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{156,,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{157,,Free-threaded Python is officially supported}

@item 
@geindex Python Enhancement Proposals; PEP 761
PEP 761@footnote{https://peps.python.org/pep-0761/}: @ref{158,,PGP signatures have been discontinued for official releases}

@item 
@ref{159,,Windows and macOS binary releases now support the experimental just-in-time compiler}

@item 
@ref{156,,Binary releases for Android are now provided}
@end itemize

@node New features,Other language changes,Summary -- Release highlights,Python 3 14 有什麼新功能
@anchor{whatsnew/3 14 new-features}@anchor{15a}
@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:: 
* 改善錯誤訊息:: 
* PEP 784：標準函式庫中的 Zstandard 支援:: 
* 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
@anchor{whatsnew/3 14 pep-649-pep-749-deferred-evaluation-of-annotations}@anchor{15b}@anchor{whatsnew/3 14 whatsnew314-deferred-annotations}@anchor{145}
@subsubsection 
@geindex Python Enhancement Proposals; PEP 649
`PEP 649' & 
@geindex Python Enhancement Proposals; PEP 749
`PEP 749': Deferred evaluation of annotations


The @ref{15c,,annotations} on functions, classes, and modules are no
longer evaluated eagerly. Instead, annotations are stored in special-purpose
@ref{15d,,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{15e,,VALUE}
format (which evaluates annotations to runtime values, similar to the behavior in
earlier Python versions), the @ref{15f,,FORWARDREF} format
(which replaces undefined names with special markers), and the
@ref{160,,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{161,,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.

（由 Jelle Zijlstra 於 
@geindex Python Enhancement Proposals; PEP 749
PEP 749@footnote{https://peps.python.org/pep-0749/} 和 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/} 由 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/}

實作 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
@anchor{whatsnew/3 14 pep-734-multiple-interpreters-in-the-standard-library}@anchor{162}@anchor{whatsnew/3 14 whatsnew314-multiple-interpreters}@anchor{146}
@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{163,,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{f3,,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{164,,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{165,,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{164,,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{166,,隔離擴充模組}.
Isolating a module has a lot of overlap with what is required to support
@ref{150,,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{167,,concurrent.futures.InterpreterPoolExecutor}.

（由 Eric Snow 於 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
@anchor{whatsnew/3 14 pep-750-template-string-literals}@anchor{168}@anchor{whatsnew/3 14 whatsnew314-template-string-literals}@anchor{144}
@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{169,,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{16a,,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{16b,,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
@anchor{whatsnew/3 14 pep-768-safe-external-debugger-interface}@anchor{16c}@anchor{whatsnew/3 14 whatsnew314-remote-debugging}@anchor{14e}
@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{16d,,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{16e,,PYTHON_DISABLE_REMOTE_DEBUG} environment variable.

@item 
A @ref{16f,,-X disable-remote-debug} command-line option.

@item 
A @ref{170,,--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
@anchor{whatsnew/3 14 a-new-type-of-interpreter}@anchor{171}@anchor{whatsnew/3 14 whatsnew314-tail-call-interpreter}@anchor{14f}
@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
recommendeded 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{172,,--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,改善錯誤訊息,A new type of interpreter,New features
@anchor{whatsnew/3 14 free-threaded-mode-improvements}@anchor{173}@anchor{whatsnew/3 14 whatsnew314-free-threaded-cpython}@anchor{150}
@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{174,,sysconfig.get_config_var()}.

The new @ref{16f,,-X context_aware_warnings} flag controls if
@ref{153,,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{175,,thread_inherit_context} flag has been added,
which if enabled means that threads created with @ref{176,,threading.Thread}
start with a copy of the @ref{177,,Context()} of the caller of
@ref{178,,start()}.  Most significantly, this makes the warning
filtering context established by @ref{179,,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{3a,,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 改善錯誤訊息,PEP 784：標準函式庫中的 Zstandard 支援,Free-threaded mode improvements,New features
@anchor{whatsnew/3 14 improved-error-messages}@anchor{17a}@anchor{whatsnew/3 14 whatsnew314-improved-error-messages}@anchor{151}
@subsubsection 改善錯誤訊息



@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{17b,,elif} statements that follow an @ref{17c,,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{17d,,Conditional expressions} after @ref{17c,,else},
or one of @ref{17e,,pass}, @ref{17f,,break}, or @ref{180,,continue}
is passed before @ref{181,,if}, then the
error message highlights where the @ref{182,,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{183,,dict} or @ref{184,,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{185,,async with}
instead of @ref{186,,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 支援,Asyncio introspection capabilities,改善錯誤訊息,New features
@anchor{whatsnew/3 14 pep-784-zstandard-support-in-the-standard-library}@anchor{187}@anchor{whatsnew/3 14 whatsnew314-zstandard}@anchor{148}
@subsubsection 
@geindex Python Enhancement Proposals; PEP 784
`PEP 784'：標準函式庫中的 Zstandard 支援


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{8e,,lzma}, @ref{14,,bz2}, @ref{6b,,gzip} and @ref{139,,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{e4,,tarfile}, @ref{137,,zipfile}, and
@ref{ca,,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 支援,New features
@anchor{whatsnew/3 14 asyncio-introspection-capabilities}@anchor{188}@anchor{whatsnew/3 14 whatsnew314-asyncio-introspection}@anchor{147}
@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
@anchor{whatsnew/3 14 concurrent-safe-warnings-control}@anchor{189}@anchor{whatsnew/3 14 whatsnew314-concurrent-warnings-control}@anchor{153}
@subsubsection Concurrent safe warnings control


The @ref{179,,warnings.catch_warnings} context manager will now optionally
use a context variable for warning filters. This is enabled by setting
the @ref{18a,,context_aware_warnings} flag, either with the @code{-X}
command-line option or an environment variable. This gives predictable
warnings control when using @ref{179,,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.

（由 Neil Schemenauer 和 Kumar Aditya 於 gh-130010@footnote{https://github.com/python/cpython/issues/130010} 貢獻。）

@node Other language changes,New modules,New features,Python 3 14 有什麼新功能
@anchor{whatsnew/3 14 other-language-changes}@anchor{18b}
@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{18c,,-O} command-line option.
This includes writes to @code{__debug__}, incorrect use of @ref{18d,,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{18e,,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. 
* Incremental garbage collection:: 
* Default interactive shell:: 

@end menu

@node Built-ins,Command line and environment,,Other language changes
@anchor{whatsnew/3 14 built-ins}@anchor{18f}
@subsubsection Built-ins



@itemize *

@item 
The @ref{190,,bytes.fromhex()} and @ref{191,,bytearray.fromhex()} methods now accept
ASCII @ref{192,,bytes} and @ref{193,,bytes-like objects}.
(Contributed by Daniel Pope in gh-129349@footnote{https://github.com/python/cpython/issues/129349}.)

@item 
Add class methods @ref{194,,float.from_number()} and @ref{195,,complex.from_number()}
to convert a number to @ref{196,,float} or @ref{197,,complex} type correspondingly.
They raise a @ref{198,,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{199,,format()} or @ref{19a,,f-string（f 字串）}).
(Contributed by Sergey B Kirpichev in gh-87790@footnote{https://github.com/python/cpython/issues/87790}.)

@item 
The @ref{19b,,int()} function no longer delegates to @ref{19c,,__trunc__()}.
Classes that want to support conversion to @code{int()} must implement
either @ref{19d,,__int__()} or @ref{19e,,__index__()}.
(Contributed by Mark Dickinson in gh-119743@footnote{https://github.com/python/cpython/issues/119743}.)

@item 
The @ref{19f,,map()} function now has an optional keyword-only `strict' flag
like @ref{1a0,,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{165,,memoryview} type now supports subscription,
making it a @ref{1a1,,generic type}.
(Contributed by Brian Schubert in gh-126012@footnote{https://github.com/python/cpython/issues/126012}.)

@item 
Using @ref{1a2,,NotImplemented} in a boolean context
will now raise a @ref{198,,TypeError}.
This has raised a @ref{1a3,,DeprecationWarning} since Python 3.9.
(Contributed by Jelle Zijlstra in gh-118767@footnote{https://github.com/python/cpython/issues/118767}.)

@item 
Three-argument @ref{1a4,,pow()} now tries calling @ref{1a5,,__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{1a6,,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
@anchor{whatsnew/3 14 command-line-and-environment}@anchor{1a7}
@subsubsection Command line and environment



@itemize *

@item 
The import time flag can now track modules that are already loaded ('cached'),
via the new @ref{16f,,-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.

（由 Noah Kim 和 Adam Turner 於 gh-118655@footnote{https://github.com/python/cpython/issues/118655} 貢獻。）

@item 
The command-line option @ref{1a8,,-c} now automatically dedents its code
argument before execution. The auto-dedentation behavior mirrors
@ref{1a9,,textwrap.dedent()}.
(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
@anchor{whatsnew/3 14 pep-758-allow-except-and-except-expressions-without-brackets}@anchor{1aa}@anchor{whatsnew/3 14 whatsnew314-bracketless-except}@anchor{14c}
@subsubsection PEP 758: Allow @code{except} and @code{except*} expressions without brackets


The @ref{1ab,,except} and @ref{1ac,,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

（由 Pablo Galindo 和 Brett Cannon 於 
@geindex Python Enhancement Proposals; PEP 758
PEP 758@footnote{https://peps.python.org/pep-0758/} 和 gh-131831@footnote{https://github.com/python/cpython/issues/131831} 貢獻。）

@node PEP 765 Control flow in finally blocks,Incremental garbage collection,PEP 758 Allow except and except* expressions without brackets,Other language changes
@anchor{whatsnew/3 14 pep-765-control-flow-in-finally-blocks}@anchor{1ad}@anchor{whatsnew/3 14 whatsnew314-finally-syntaxwarning}@anchor{14d}
@subsubsection PEP 765: Control flow in @code{finally} blocks


The compiler now emits a @ref{1ae,,SyntaxWarning} when a @ref{1af,,return},
@ref{17f,,break}, or @ref{180,,continue} statement have the effect of
leaving a @ref{1b0,,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{1b1,,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{118,,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.

（由 Irit Katriel 於 gh-130080@footnote{https://github.com/python/cpython/issues/130080} 貢獻。）

@node Incremental garbage collection,Default interactive shell,PEP 765 Control flow in finally blocks,Other language changes
@anchor{whatsnew/3 14 incremental-garbage-collection}@anchor{1b2}@anchor{whatsnew/3 14 whatsnew314-incremental-gc}@anchor{152}
@subsubsection Incremental garbage collection


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{1b3,,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

（由 Mark Shannon 於 gh-108362@footnote{https://github.com/python/cpython/issues/108362} 貢獻。）

@node Default interactive shell,,Incremental garbage collection,Other language changes
@anchor{whatsnew/3 14 default-interactive-shell}@anchor{1b4}
@subsubsection Default interactive shell

@anchor{whatsnew/3 14 whatsnew314-pyrepl-highlighting}@anchor{154}

@itemize *

@item 
The default @ref{1b5,,interactive} shell now highlights Python syntax.
The feature is enabled by default, save if 
@geindex PYTHON_BASIC_REPL
@geindex 環境變數; PYTHON_BASIC_REPL
@ref{1b6,,PYTHON_BASIC_REPL}
or any other environment variable that disables colour is set.
See @ref{1b7,,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{1b8,,PYTHONSTARTUP} script.
Note that this function has no stability guarantees,
and may change or be removed.

（由 Łukasz Langa 於 gh-131507@footnote{https://github.com/python/cpython/issues/131507} 貢獻。）

@item 
The default @ref{1b5,,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,Improved modules,Other language changes,Python 3 14 有什麼新功能
@anchor{whatsnew/3 14 new-modules}@anchor{1b9}
@subsection New modules



@itemize *

@item 
@ref{6,,annotationlib}:
For introspecting @ref{15c,,annotations}.
See @ref{145,,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{148,,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{146,,PEP 734} for more details.
(Contributed by Eric Snow in gh-134939@footnote{https://github.com/python/cpython/issues/134939}.)

@item 
@ref{d9,,string.templatelib}:
Support for template string literals (t-strings).
See @ref{144,,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,最佳化,New modules,Python 3 14 有什麼新功能
@anchor{whatsnew/3 14 improved-modules}@anchor{1ba}
@subsection Improved modules


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

@end menu

@node argparse,ast,,Improved modules
@anchor{whatsnew/3 14 argparse}@anchor{1bb}
@subsubsection argparse



@itemize *

@item 
The default value of the @ref{1bc,,program name} for
@ref{1bd,,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{1bd,,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{1bd,,argparse.ArgumentParser}.
This can also be controlled by @ref{1b7,,environment variables}.
(Contributed by Hugo van Kemenade in gh-130645@footnote{https://github.com/python/cpython/issues/130645}.)
@end itemize

@node ast,asyncio,argparse,Improved modules
@anchor{whatsnew/3 14 ast}@anchor{1be}
@subsubsection ast



@itemize *

@item 
Add @ref{1bf,,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{1c0,,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{1c1,,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{1c2,,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{1c3,,--feature-version},
@ref{1c4,,--optimize}, and
@ref{1c5,,--show-empty}.
(Contributed by Semyon Moroz in gh-133367@footnote{https://github.com/python/cpython/issues/133367}.)
@end itemize

@node asyncio,calendar,ast,Improved modules
@anchor{whatsnew/3 14 asyncio}@anchor{1c6}
@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{1c7,,Task} constructor or the custom task factory.
(See @ref{1c8,,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{1c9,,asyncio.create_task()},
@ref{1ca,,asyncio.loop.create_task()},
@ref{1cb,,asyncio.TaskGroup.create_task()}.

（由 Thomas Grainger 於 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{1cc,,capture_call_graph()} and @ref{1cd,,print_call_graph()}.
See @ref{147,,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,concurrent futures,asyncio,Improved modules
@anchor{whatsnew/3 14 calendar}@anchor{1ce}
@subsubsection calendar

@anchor{whatsnew/3 14 whatsnew314-color-calendar}@anchor{1cf}

@itemize *

@item 
By default, today's date is highlighted in color in @ref{15,,calendar}'s
@ref{1d0,,command-line} text output.
This can be controlled by @ref{1b7,,environment variables}.
(Contributed by Hugo van Kemenade in gh-128317@footnote{https://github.com/python/cpython/issues/128317}.)
@end itemize

@node concurrent futures,configparser,calendar,Improved modules
@anchor{whatsnew/3 14 concurrent-futures}@anchor{1d1}
@subsubsection concurrent.futures

@anchor{whatsnew/3 14 whatsnew314-concurrent-futures-interp-pool}@anchor{167}

@itemize *

@item 
Add a new executor class, @ref{1d2,,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{146,,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{1d3}

@itemize *

@item 
On Unix platforms other than macOS, @ref{1d4,,'forkserver'} is now the default @ref{1d5,,start method} for
@ref{1d6,,ProcessPoolExecutor}
(replacing @ref{1d7,,'fork'}).
This change does not affect Windows or macOS, where @ref{1d8,,'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{1d6,,ProcessPoolExecutor}.

See @ref{1d9,,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}.

（由 Gregory P. Smith 於 gh-84559@footnote{https://github.com/python/cpython/issues/84559} 貢獻。）

@item 
Add two new methods to @ref{1d6,,ProcessPoolExecutor},
@ref{1da,,terminate_workers()}
and @ref{1db,,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{1dc,,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,Improved modules
@anchor{whatsnew/3 14 configparser}@anchor{1dd}
@subsubsection configparser



@itemize *

@item 
@code{configparser} will no longer write config files it cannot read,
to improve security.
Attempting to @ref{1de,,write()} keys containing
delimiters or beginning with the section header pattern will raise an
@ref{1df,,InvalidWriteError}.
(Contributed by Jacob Lincoln in gh-129270@footnote{https://github.com/python/cpython/issues/129270}.)
@end itemize

@node contextvars,ctypes,configparser,Improved modules
@anchor{whatsnew/3 14 contextvars}@anchor{1e0}
@subsubsection contextvars



@itemize *

@item 
Support the @ref{1e1,,context manager} protocol
for @ref{1e2,,Token} objects.
(Contributed by Andrew Svetlov in gh-129889@footnote{https://github.com/python/cpython/issues/129889}.)
@end itemize

@node ctypes,curses,contextvars,Improved modules
@anchor{whatsnew/3 14 ctypes}@anchor{1e3}
@subsubsection ctypes



@itemize *

@item 
The layout of @ref{1e4,,bit fields}
in @ref{1e5,,Structure} and @ref{1e6,,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{1e7,,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{1e5,,Structure}/@ref{1e6,,Union}
field descriptors is now available as @ref{1e8,,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{1e9,,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{1ea,,CopyComPointer()} function is now public.
(Contributed by Jun Komoda in gh-127275@footnote{https://github.com/python/cpython/issues/127275}.)

@item 
Add @ref{1eb,,memoryview_at()}, a function to create a
@ref{165,,memoryview} object that refers to the supplied pointer and
length. This works like @ref{1ec,,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{1ed,,c_float_complex},
@ref{1ee,,c_double_complex}, and @ref{1ef,,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{1f0,,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{1f1,,ctypes.POINTER()} types cache from a global internal cache
(@code{_pointer_type_cache}) to the @ref{1f2,,_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{1f3,,py_object} type now supports subscription,
making it a @ref{1a1,,generic type}.
(Contributed by Brian Schubert in gh-132168@footnote{https://github.com/python/cpython/issues/132168}.)

@item 
@code{ctypes} now supports @ref{1f4,,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,ctypes,Improved modules
@anchor{whatsnew/3 14 curses}@anchor{1f5}
@subsubsection curses



@itemize *

@item 
Add the @ref{1f6,,assume_default_colors()} function,
a refinement of the @ref{1f7,,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,decimal,curses,Improved modules
@anchor{whatsnew/3 14 datetime}@anchor{1f8}
@subsubsection datetime



@itemize *

@item 
Add the @ref{1f9,,strptime()} method to the
@ref{1fa,,datetime.date} and @ref{1fb,,datetime.time} classes.
(Contributed by Wannes Boeykens in gh-41431@footnote{https://github.com/python/cpython/issues/41431}.)
@end itemize

@node decimal,difflib,datetime,Improved modules
@anchor{whatsnew/3 14 decimal}@anchor{1fc}
@subsubsection decimal



@itemize *

@item 
Add @ref{1fd,,Decimal.from_number()} as an alternative constructor for
@ref{1fe,,Decimal}.
(Contributed by Serhiy Storchaka in gh-121798@footnote{https://github.com/python/cpython/issues/121798}.)

@item 
Expose @ref{1ff,,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,dis,decimal,Improved modules
@anchor{whatsnew/3 14 difflib}@anchor{200}
@subsubsection difflib



@itemize *

@item 
Comparison pages with highlighted changes generated by the
@ref{201,,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,Improved modules
@anchor{whatsnew/3 14 dis}@anchor{202}
@subsubsection dis



@itemize *

@item 
Add support for rendering full source location information of
@ref{203,,instructions}, rather than only the line number.
This feature is added to the following interfaces via the `show_positions'
keyword argument:


@itemize -

@item 
@ref{204,,dis.Bytecode}

@item 
@ref{205,,dis.dis()}

@item 
@ref{206,,dis.distb()}

@item 
@ref{207,,dis.disassemble()}
@end itemize

This feature is also exposed via @ref{208,,dis --show-positions}.
(Contributed by Bénédikt Tran in gh-123165@footnote{https://github.com/python/cpython/issues/123165}.)

@item 
Add the @ref{209,,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,dis,Improved modules
@anchor{whatsnew/3 14 errno}@anchor{20a}
@subsubsection errno



@itemize *

@item 
Add the @ref{20b,,EHWPOISON} error code constant.
(Contributed by James Roy in gh-126585@footnote{https://github.com/python/cpython/issues/126585}.)
@end itemize

@node faulthandler,fnmatch,errno,Improved modules
@anchor{whatsnew/3 14 faulthandler}@anchor{20c}
@subsubsection faulthandler



@itemize *

@item 
Add support for printing the C stack trace on systems that
@ref{20d,,support it} via the new
@ref{20e,,dump_c_stack()} function or via the `c_stack' argument
in @ref{20f,,faulthandler.enable()}.
(Contributed by Peter Bierma in gh-127604@footnote{https://github.com/python/cpython/issues/127604}.)
@end itemize

@node fnmatch,fractions,faulthandler,Improved modules
@anchor{whatsnew/3 14 fnmatch}@anchor{210}
@subsubsection fnmatch



@itemize *

@item 
Add @ref{211,,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,fnmatch,Improved modules
@anchor{whatsnew/3 14 fractions}@anchor{212}
@subsubsection fractions



@itemize *

@item 
A @ref{213,,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{214,,Fraction.from_number()} as an alternative constructor for
@ref{213,,Fraction}.
(Contributed by Serhiy Storchaka in gh-121797@footnote{https://github.com/python/cpython/issues/121797}.)
@end itemize

@node functools,getopt,fractions,Improved modules
@anchor{whatsnew/3 14 functools}@anchor{215}
@subsubsection functools



@itemize *

@item 
Add the @ref{216,,Placeholder} sentinel.
This may be used with the @ref{217,,partial()}
or @ref{218,,partialmethod()} functions to reserve a place
for positional arguments in the returned @ref{219,,partial object}.
(Contributed by Dominykas Grigonis in gh-119127@footnote{https://github.com/python/cpython/issues/119127}.)

@item 
Allow the `initial' parameter of @ref{21a,,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,Improved modules
@anchor{whatsnew/3 14 getopt}@anchor{21b}
@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
@anchor{whatsnew/3 14 getpass}@anchor{21c}
@subsubsection getpass



@itemize *

@item 
Support keyboard feedback in the @ref{21d,,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
@anchor{whatsnew/3 14 graphlib}@anchor{21e}
@subsubsection graphlib



@itemize *

@item 
Allow @ref{21f,,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
@anchor{whatsnew/3 14 heapq}@anchor{220}
@subsubsection heapq



@itemize *

@item 
The @code{heapq} module has improved support for working with max-heaps,
via the following new functions:


@itemize *

@item 
@ref{221,,heapify_max()}

@item 
@ref{222,,heappush_max()}

@item 
@ref{223,,heappop_max()}

@item 
@ref{224,,heapreplace_max()}

@item 
@ref{225,,heappushpop_max()}
@end itemize
@end itemize

@node hmac,http,heapq,Improved modules
@anchor{whatsnew/3 14 hmac}@anchor{226}
@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
@anchor{whatsnew/3 14 http}@anchor{227}
@subsubsection http



@itemize *

@item 
Directory lists and error pages generated by the @ref{76,,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{76,,http.server} module now supports serving over HTTPS using the
@ref{228,,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{229,,--tls-cert <path>}:
Path to the TLS certificate file.

@item 
@ref{22a,,--tls-key <path>}:
Optional path to the private key file.

@item 
@ref{22b,,--tls-password-file <path>}:
Optional path to the password file for the private key.
@end itemize

（由 Semyon Moroz 於 gh-85162@footnote{https://github.com/python/cpython/issues/85162} 貢獻。）
@end itemize

@node imaplib,inspect,http,Improved modules
@anchor{whatsnew/3 14 imaplib}@anchor{22c}
@subsubsection imaplib



@itemize *

@item 
Add @ref{22d,,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,io,imaplib,Improved modules
@anchor{whatsnew/3 14 inspect}@anchor{22e}
@subsubsection inspect



@itemize *

@item 
@ref{22f,,signature()} takes a new argument `annotation_format' to control
the @ref{230,,annotationlib.Format} used for representing annotations.
(Contributed by Jelle Zijlstra in gh-101552@footnote{https://github.com/python/cpython/issues/101552}.)

@item 
@ref{231,,Signature.format()} takes a new argument `unquote_annotations'.
If true, string @ref{15c,,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{232,,ispackage()} to determine whether an object is a
@ref{233,,package} or not.
(Contributed by Zhikang Yan in gh-125634@footnote{https://github.com/python/cpython/issues/125634}.)
@end itemize

@node io,json,inspect,Improved modules
@anchor{whatsnew/3 14 io}@anchor{234}
@subsubsection io



@itemize *

@item 
Reading text from a non-blocking stream with @code{read} may now raise a
@ref{235,,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{236,,Reader} and @ref{237,,Writer} protocols as simpler
alternatives to the pseudo-protocols @ref{238,,typing.IO},
@ref{239,,typing.TextIO}, and @ref{23a,,typing.BinaryIO}.
(Contributed by Sebastian Rittau in gh-127648@footnote{https://github.com/python/cpython/issues/127648}.)
@end itemize

@node json,linecache,io,Improved modules
@anchor{whatsnew/3 14 json}@anchor{23b}
@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{86,,json} module as a script using the @ref{23c,,-m} switch:
@code{python -m json}.
This is now preferred to @code{python -m json.tool},
which is @ref{23d,,soft deprecated}.
See the @ref{23e,,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{23e,,JSON command-line interface} is highlighted in color.
This can be controlled by @ref{1b7,,environment variables}.
(Contributed by Tomas Roun in gh-131952@footnote{https://github.com/python/cpython/issues/131952}.)
@end itemize

@node linecache,logging handlers,json,Improved modules
@anchor{whatsnew/3 14 linecache}@anchor{23f}
@subsubsection linecache



@itemize *

@item 
@ref{240,,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,linecache,Improved modules
@anchor{whatsnew/3 14 logging-handlers}@anchor{241}
@subsubsection logging.handlers



@itemize *

@item 
@ref{242,,QueueListener} objects now support the
@ref{1e1,,context manager} protocol.
(Contributed by Charles Machalow in gh-132106@footnote{https://github.com/python/cpython/issues/132106}.)

@item 
@ref{243,,QueueListener.start} now
raises a @ref{244,,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,mimetypes,logging handlers,Improved modules
@anchor{whatsnew/3 14 math}@anchor{245}
@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,multiprocessing,math,Improved modules
@anchor{whatsnew/3 14 mimetypes}@anchor{246}
@subsubsection mimetypes



@itemize *

@item 
Add a public @ref{247,,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,Improved modules
@anchor{whatsnew/3 14 multiprocessing}@anchor{248}
@subsubsection multiprocessing

@anchor{whatsnew/3 14 whatsnew314-multiprocessing-start-method}@anchor{249}

@itemize *

@item 
On Unix platforms other than macOS, @ref{1d4,,'forkserver'} is now the default @ref{1d5,,start method}
(replacing @ref{1d7,,'fork'}).
This change does not affect Windows or macOS, where @ref{1d8,,'spawn'} remains the default start method.

If the threading incompatible `fork' method is required, you must explicitly
request it via a context from @ref{24a,,get_context()} (preferred)
or change the default via @ref{24b,,set_start_method()}.

See @ref{1d9,,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}.

（由 Gregory P. Smith 於 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{24c,,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{24d,,list}

@item 
@ref{24e,,fromkeys()}, @code{reversed(d)}, @code{d | @{@}}, @code{@{@} | d},
@code{d |= @{'b': 2@}} for proxies of @ref{183,,dict}
@end itemize
@end quotation

（由 Roy Hyunjin Han 於 gh-103134@footnote{https://github.com/python/cpython/issues/103134} 貢獻。）

@item 
Add support for shared @ref{184,,set} objects via
@ref{24f,,SyncManager.set()}.
The @ref{184,,set()} in @ref{250,,Manager()} method is now available.
(Contributed by Mingyu Park in gh-129949@footnote{https://github.com/python/cpython/issues/129949}.)

@item 
Add the @ref{251,,interrupt()}
to @ref{252,,multiprocessing.Process} objects, which terminates the child
process by sending @ref{253,,SIGINT}. This enables
@ref{1b0,,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,multiprocessing,Improved modules
@anchor{whatsnew/3 14 operator}@anchor{254}
@subsubsection operator



@itemize *

@item 
Add @ref{255,,is_none()} and @ref{256,,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,os path,operator,Improved modules
@anchor{whatsnew/3 14 os}@anchor{257}
@subsubsection os



@itemize *

@item 
Add the @ref{258,,reload_environ()} function to update @ref{259,,os.environ} and
@ref{25a,,os.environb} with changes to the environment made by
@ref{25b,,os.putenv()}, by @ref{25c,,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{25d,,SCHED_DEADLINE} and @ref{25e,,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{25f,,readinto()} function to read into a
@ref{260,,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,pathlib,os,Improved modules
@anchor{whatsnew/3 14 os-path}@anchor{261}
@subsubsection os.path



@itemize *

@item 
The `strict' parameter to @ref{262,,realpath()} accepts a new value,
@ref{263,,ALLOW_MISSING}.
If used, errors other than @ref{264,,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,pdb,os path,Improved modules
@anchor{whatsnew/3 14 pathlib}@anchor{265}
@subsubsection pathlib



@itemize *

@item 
Add methods to @ref{266,,pathlib.Path} to recursively copy or move files and
directories:


@itemize *

@item 
@ref{267,,copy()} copies a file or directory tree to a destination.

@item 
@ref{268,,copy_into()} copies `into' a destination directory.

@item 
@ref{269,,move()} moves a file or directory tree to a destination.

@item 
@ref{26a,,move_into()} moves `into' a destination directory.
@end itemize

（由 Barney Gale 於 gh-73991@footnote{https://github.com/python/cpython/issues/73991} 貢獻。）

@item 
Add the @ref{26b,,info} attribute, which stores an object
implementing the new @ref{26c,,pathlib.types.PathInfo} protocol. The
object supports querying the file type and internally caching
@ref{26d,,stat()} results. Path objects generated by
@ref{26e,,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,pickle,pathlib,Improved modules
@anchor{whatsnew/3 14 pdb}@anchor{26f}
@subsubsection pdb



@itemize *

@item 
The @ref{aa,,pdb} module now supports remote attaching to a running Python process
using a new @ref{270,,-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{14e,,PEP 768}
and the new @ref{16d,,sys.remote_exec()} function to attach to the remote process
and send the PDB commands to it.

（由 Matt Wozniski and Pablo Galindo 於 gh-131591@footnote{https://github.com/python/cpython/issues/131591} 貢獻。）

@item 
Hardcoded breakpoints (@ref{271,,breakpoint()} and @ref{272,,set_trace()}) now
reuse the most recent @ref{273,,Pdb} instance that calls
@ref{274,,set_trace()}, instead of creating a new one each time.
As a result, all the instance specific data like @ref{275,,display} and
@ref{276,,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{273,,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{277,,sys.exit()}, instead of raising @ref{278,,bdb.BdbQuit}.
(Contributed by Tian Gao in gh-124704@footnote{https://github.com/python/cpython/issues/124704}.)

@item 
Inline breakpoints like @ref{271,,breakpoint()} or @ref{272,,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{279,,pdb.set_trace_async()} is added to support debugging asyncio
coroutines. @ref{18d,,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{1b5,,interactive}
shell, in addition to the newly added @code{colorize} argument of @ref{273,,pdb.Pdb}.
(Contributed by Tian Gao and Łukasz Langa in gh-133355@footnote{https://github.com/python/cpython/issues/133355}.)
@end itemize

@node pickle,platform,pdb,Improved modules
@anchor{whatsnew/3 14 pickle}@anchor{27a}
@subsubsection pickle



@itemize *

@item 
Set the default protocol version on the @ref{ab,,pickle} module to 5.
For more details, see @ref{27b,,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,pydoc,pickle,Improved modules
@anchor{whatsnew/3 14 platform}@anchor{27c}
@subsubsection platform



@itemize *

@item 
Add @ref{27d,,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,platform,Improved modules
@anchor{whatsnew/3 14 pydoc}@anchor{27e}
@subsubsection pydoc



@itemize *

@item 
@ref{15c,,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,socket,pydoc,Improved modules
@anchor{whatsnew/3 14 re}@anchor{27f}
@subsubsection re



@itemize *

@item 
Support @code{\z} as a synonym for @code{\Z} in @ref{be,,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{be,,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,ssl,re,Improved modules
@anchor{whatsnew/3 14 socket}@anchor{280}
@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{281,,BTPROTO_HCI} on FreeBSD.
(Contributed by Victor Stinner in gh-111178@footnote{https://github.com/python/cpython/issues/111178}.)

@item 
Add support for @ref{282,,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{283,,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{281,,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{281,,BTPROTO_HCI} on Linux.
(Contributed by Serhiy Storchaka in gh-132099@footnote{https://github.com/python/cpython/issues/132099}.)

@item 
Return `cid' in @ref{284,,getsockname()} for
@ref{283,,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,struct,socket,Improved modules
@anchor{whatsnew/3 14 ssl}@anchor{285}
@subsubsection ssl



@itemize *

@item 
Indicate through the @ref{286,,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,ssl,Improved modules
@anchor{whatsnew/3 14 struct}@anchor{287}
@subsubsection struct



@itemize *

@item 
Support the float complex and double complex C types in
the @ref{db,,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,sys,struct,Improved modules
@anchor{whatsnew/3 14 symtable}@anchor{288}
@subsubsection symtable



@itemize *

@item 
Expose the following @ref{289,,Symbol} methods:


@itemize *

@item 
@ref{28a,,is_comp_cell()}

@item 
@ref{28b,,is_comp_iter()}

@item 
@ref{28c,,is_free_class()}
@end itemize

（由 Bénédikt Tran 於 gh-120029@footnote{https://github.com/python/cpython/issues/120029} 貢獻。）
@end itemize

@node sys,sys monitoring,symtable,Improved modules
@anchor{whatsnew/3 14 sys}@anchor{28d}
@subsubsection sys



@itemize *

@item 
The previously undocumented special function @ref{28e,,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{28f,,sys._is_immortal()} for determining if an object is @ref{290,,immortal}.
(Contributed by Peter Bierma in gh-128509@footnote{https://github.com/python/cpython/issues/128509}.)

@item 
On FreeBSD, @ref{291,,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{1a3,,DeprecationWarning} for @ref{292,,sys._clear_type_cache()}. This
function was deprecated in Python 3.13 but it didn't raise a runtime warning.

@item 
Add @ref{16d,,sys.remote_exec()} to implement the new external debugger interface.
See @ref{14e,,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{293,,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,sysconfig,sys,Improved modules
@anchor{whatsnew/3 14 sys-monitoring}@anchor{294}
@subsubsection sys.monitoring



@itemize *

@item 
Add two new monitoring events, @ref{295,,BRANCH_LEFT} and
@ref{296,,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,tarfile,sys monitoring,Improved modules
@anchor{whatsnew/3 14 sysconfig}@anchor{297}
@subsubsection sysconfig



@itemize *

@item 
Add @code{ABIFLAGS} key to @ref{298,,get_config_vars()} on Windows.
(Contributed by Xuehai Pan in gh-131799@footnote{https://github.com/python/cpython/issues/131799}.)
@end itemize

@node tarfile,threading,sysconfig,Improved modules
@anchor{whatsnew/3 14 tarfile}@anchor{299}
@subsubsection tarfile



@itemize *

@item 
@ref{29a,,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{29b,,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{29c,,extract()} and @ref{29b,,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{29d,,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{29c,,extract()} and @ref{29b,,extractall()}
no longer extract rejected members when
@ref{29e,,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,tkinter,tarfile,Improved modules
@anchor{whatsnew/3 14 threading}@anchor{29f}
@subsubsection threading



@itemize *

@item 
@ref{178,,threading.Thread.start()} now sets the operating system thread name
to @ref{2a0,,threading.Thread.name}.
(Contributed by Victor Stinner in gh-59705@footnote{https://github.com/python/cpython/issues/59705}.)
@end itemize

@node tkinter,turtle,threading,Improved modules
@anchor{whatsnew/3 14 tkinter}@anchor{2a1}
@subsubsection tkinter



@itemize *

@item 
Make @ref{f6,,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,tkinter,Improved modules
@anchor{whatsnew/3 14 turtle}@anchor{2a2}
@subsubsection turtle



@itemize *

@item 
Add context managers for @ref{2a3,,turtle.fill()}, @ref{2a4,,turtle.poly()},
and @ref{2a5,,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,typing,turtle,Improved modules
@anchor{whatsnew/3 14 types}@anchor{2a6}
@subsubsection types



@itemize *

@item 
@ref{2a7,,types.UnionType} is now an alias for @ref{2a8,,typing.Union}.
See @ref{2a9,,below} for more details.
(Contributed by Jelle Zijlstra in gh-105499@footnote{https://github.com/python/cpython/issues/105499}.)
@end itemize

@node typing,unicodedata,types,Improved modules
@anchor{whatsnew/3 14 typing}@anchor{2aa}
@subsubsection typing

@anchor{whatsnew/3 14 whatsnew314-typing-union}@anchor{2a9}

@itemize *

@item 
The @ref{2a7,,types.UnionType} and @ref{2a8,,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{1c1,,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{2a7,,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 
在過去，舊式聯集是使用私有類別 @code{typing._UnionGenericAlias} 實作的。這個類別不再被需要，但為了向後相容性而保留，並計劃將在 Python 3.17 中移除。使用者應該改用文件中記錄的自我檢查輔助函式，例如 @ref{2ab,,get_origin()} 和 @ref{2ac,,typing.get_args()}，或者依賴私有實作細節。

@item 
It is now possible to use @ref{2a8,,typing.Union} itself in
@ref{2ad,,isinstance()} checks.
For example, @code{isinstance(int | str, typing.Union)} will return @code{True};
previously this raised @ref{198,,TypeError}.

@item 
The @code{__args__} attribute of @ref{2a8,,typing.Union} objects is
no longer writable.

@item 
It is no longer possible to set any attributes on @ref{2a8,,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

（由 Jelle Zijlstra 於 gh-105499@footnote{https://github.com/python/cpython/issues/105499} 貢獻。）

@item 
@ref{2ae,,TypeAliasType} now supports star unpacking.
@end itemize

@node unicodedata,unittest,typing,Improved modules
@anchor{whatsnew/3 14 unicodedata}@anchor{2af}
@subsubsection unicodedata



@itemize *

@item 
The Unicode database has been updated to Unicode 16.0.0.
@end itemize

@node unittest,urllib,unicodedata,Improved modules
@anchor{whatsnew/3 14 unittest}@anchor{2b0}
@subsubsection unittest

@anchor{whatsnew/3 14 whatsnew314-color-unittest}@anchor{2b1}

@itemize *

@item 
@ref{10c,,unittest} output is now colored by default.
This can be controlled by @ref{1b7,,environment variables}.
(Contributed by Hugo van Kemenade in gh-127221@footnote{https://github.com/python/cpython/issues/127221}.)

@item 
unittest discovery supports @ref{2b2,,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{2b3,,TestCase} class
that provide more specialized tests.


@itemize -

@item 
@ref{2b4,,assertHasAttr()} and
@ref{2b5,,assertNotHasAttr()} check whether the object
has a particular attribute.

@item 
@ref{2b6,,assertIsSubclass()} and
@ref{2b7,,assertNotIsSubclass()} check whether the object
is a subclass of a particular class, or of one of a tuple of classes.

@item 
@ref{2b8,,assertStartsWith()},
@ref{2b9,,assertNotStartsWith()},
@ref{2ba,,assertEndsWith()} and
@ref{2bb,,assertNotEndsWith()} check whether the Unicode
or byte string starts or ends with particular strings.
@end itemize

（由 Serhiy Storchaka 於 gh-71339@footnote{https://github.com/python/cpython/issues/71339} 貢獻。）
@end itemize

@node urllib,uuid,unittest,Improved modules
@anchor{whatsnew/3 14 urllib}@anchor{2bc}
@subsubsection urllib



@itemize *

@item 
Upgrade HTTP digest authentication algorithm for @ref{111,,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{2bd,,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{2be,,URLError} if a URL authority isn't local,
except on Windows where we return a UNC path as before.
@end itemize

In @ref{2bf,,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{2c0,,OSError}
exception to be raised.

（由 Barney Gale 於 gh-125866@footnote{https://github.com/python/cpython/issues/125866} 貢獻。）
@end itemize

@node uuid,webbrowser,urllib,Improved modules
@anchor{whatsnew/3 14 uuid}@anchor{2c1}
@subsubsection uuid



@itemize *

@item 
Add support for UUID versions 6, 7, and 8 via @ref{2c2,,uuid6()},
@ref{2c3,,uuid7()}, and @ref{2c4,,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{2c5,,NIL} and @ref{2c6,,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{2c7,,python -m uuid --count}.
(Contributed by Simon Legner in gh-131236@footnote{https://github.com/python/cpython/issues/131236}.)
@end itemize

@node webbrowser,zipfile,uuid,Improved modules
@anchor{whatsnew/3 14 webbrowser}@anchor{2c8}
@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{11b,,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,Improved modules
@anchor{whatsnew/3 14 zipfile}@anchor{2c9}
@subsubsection zipfile



@itemize *

@item 
Added @ref{2ca,,ZipInfo._for_archive}, a method
to resolve suitable defaults for a @ref{2cb,,ZipInfo} object
as used by @ref{2cc,,ZipFile.writestr}.
(Contributed by Bénédikt Tran in gh-123424@footnote{https://github.com/python/cpython/issues/123424}.)

@item 
@ref{2cc,,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 最佳化,已移除,Improved modules,Python 3 14 有什麼新功能
@anchor{whatsnew/3 14 optimizations}@anchor{2cd}
@subsection 最佳化



@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{2d,,csv}, @ref{67,,gettext}, @ref{81,,importlib.util}, @ref{8a,,locale},
@ref{93,,mimetypes}, @ref{a4,,optparse}, @ref{ab,,pickle}, @ref{b3,,pprint},
@ref{b5,,pstats}, @ref{c9,,shlex}, @ref{d1,,socket}, @ref{d8,,string}, @ref{dc,,subprocess},
@ref{f3,,threading}, @ref{102,,tomllib}, @ref{109,,types}, and @ref{137,,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{2ce,,sys.getrefcount()}
and @ref{2cf,,Py_REFCNT()} compared to previous versions of Python.
See @ref{2d0,,below} for details.
@end itemize

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

@end menu

@node asyncio<2>,base64,,最佳化
@anchor{whatsnew/3 14 id2}@anchor{2d1}
@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{1c7,,native tasks},
also reducing memory usage.
This enables external introspection tools such as
@ref{147,,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{1f4,,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,bdb,asyncio<2>,最佳化
@anchor{whatsnew/3 14 base64}@anchor{2d2}
@subsubsection base64



@itemize *

@item 
@ref{2d3,,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<2>,base64,最佳化
@anchor{whatsnew/3 14 bdb}@anchor{2d4}
@subsubsection bdb



@itemize *

@item 
The basic debugger now has a @ref{e0,,sys.monitoring}-based backend,
which can be selected via the passing @code{'monitoring'}
to the @ref{2d5,,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<2>,gc,bdb,最佳化
@anchor{whatsnew/3 14 id3}@anchor{2d6}
@subsubsection difflib



@itemize *

@item 
The @ref{2d7,,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,io<2>,difflib<2>,最佳化
@anchor{whatsnew/3 14 gc}@anchor{2d8}
@subsubsection gc



@itemize *

@item 
The new @ref{152,,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{2d9,,get_threshold()} and @ref{2da,,set_threshold()} have changed,
along with @ref{2db,,get_count()} and @ref{2dc,,get_stats()}.


@itemize -

@item 
For backwards compatibility, @ref{2d9,,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{2da,,set_threshold()} now ignores any items after the second.

@item 
@ref{2db,,get_count()} and @ref{2dc,,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.

（由 Mark Shannon 於 gh-108362@footnote{https://github.com/python/cpython/issues/108362} 貢獻。）
@end itemize

@node io<2>,pathlib<2>,gc,最佳化
@anchor{whatsnew/3 14 id4}@anchor{2dd}
@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<2>,pdb<2>,io<2>,最佳化
@anchor{whatsnew/3 14 id5}@anchor{2de}
@subsubsection pathlib



@itemize *

@item 
@ref{2df,,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<2>,uuid<2>,pathlib<2>,最佳化
@anchor{whatsnew/3 14 id6}@anchor{2e0}
@subsubsection pdb



@itemize *

@item 
@ref{aa,,pdb} now supports two backends, based on either
@ref{2e1,,sys.settrace()} or @ref{e0,,sys.monitoring}.
Using the @ref{2e2,,pdb CLI} or @ref{271,,breakpoint()}
will always use the @ref{e0,,sys.monitoring} backend.
Explicitly instantiating @ref{273,,pdb.Pdb} and its derived classes
will use the @ref{2e1,,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 uuid<2>,zlib,pdb<2>,最佳化
@anchor{whatsnew/3 14 id7}@anchor{2e3}
@subsubsection uuid



@itemize *

@item 
@ref{2e4,,uuid3()} and @ref{2e5,,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{2e6,,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,,uuid<2>,最佳化
@anchor{whatsnew/3 14 zlib}@anchor{2e7}
@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{139,,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.

（由 Steve Dower 於 gh-91349@footnote{https://github.com/python/cpython/issues/91349} 貢獻。）
@end itemize

@node 已移除,已棄用,最佳化,Python 3 14 有什麼新功能
@anchor{whatsnew/3 14 removed}@anchor{2e8}
@subsection 已移除


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

@end menu

@node argparse<2>,ast<2>,,已移除
@anchor{whatsnew/3 14 id8}@anchor{2e9}
@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{2ea,,add_argument_group()}
on an argument group now raises a @ref{2eb,,ValueError}.
Similarly, @ref{2ea,,add_argument_group()}
or @ref{2ec,,add_mutually_exclusive_group()}
on a mutually exclusive group now both raise @ref{2eb,,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<2>,asyncio<3>,argparse<2>,已移除
@anchor{whatsnew/3 14 id9}@anchor{2ed}
@subsubsection ast



@itemize *

@item 
Remove the following classes, which have been deprecated aliases of
@ref{2ee,,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{2ef,,NodeVisitor} subclasses will no longer be called
when the @code{NodeVisitor} subclass is visiting an AST.
Define a @code{visit_Constant} method instead.

（由 Alex Waygood 於 gh-119562@footnote{https://github.com/python/cpython/issues/119562} 貢獻。）

@item 
Remove the following deprecated properties on @ref{2ee,,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<3>,email,ast<2>,已移除
@anchor{whatsnew/3 14 id10}@anchor{2f0}
@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

（由 Kumar Aditya 於 gh-120804@footnote{https://github.com/python/cpython/issues/120804} 貢獻。）

@item 
@ref{2f1,,asyncio.get_event_loop()} now raises a @ref{244,,RuntimeError}
if there is no current event loop,
and no longer implicitly creates an event loop.

（由 Kumar Aditya 於 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{2f1,,asyncio.get_event_loop()}, most
of them can be replaced with @ref{2f2,,asyncio.run()}.

If you're running an async function, simply use @ref{2f2,,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{2f2,,asyncio.run()} and an
@ref{2f3,,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{2f4,,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,importlib abc,asyncio<3>,已移除
@anchor{whatsnew/3 14 email}@anchor{2f5}
@subsubsection email



@itemize *

@item 
Remove @ref{2f6,,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,已移除
@anchor{whatsnew/3 14 importlib-abc}@anchor{2f7}
@subsubsection importlib.abc



@itemize *

@item 
Remove deprecated @ref{7c,,importlib.abc} classes:


@itemize *

@item 
@code{ResourceReader}
(use @ref{2f8,,TraversableResources})

@item 
@code{Traversable}
(use @ref{2f9,,Traversable})

@item 
@code{TraversableResources}
(use @ref{2f8,,TraversableResources})
@end itemize

（由 Jason R. Coombs 和 Hugo van Kemenade 貢獻於 gh-93963@footnote{https://github.com/python/cpython/issues/93963}。）
@end itemize

@node itertools,pathlib<3>,importlib abc,已移除
@anchor{whatsnew/3 14 itertools}@anchor{2fa}
@subsubsection itertools



@itemize *

@item 
Remove support for copy, deepcopy, and pickle operations
from @ref{85,,itertools} iterators.
These have emitted a @ref{1a3,,DeprecationWarning} since Python 3.12.
(Contributed by Raymond Hettinger in gh-101588@footnote{https://github.com/python/cpython/issues/101588}.)
@end itemize

@node pathlib<3>,pkgutil,itertools,已移除
@anchor{whatsnew/3 14 id11}@anchor{2fb}
@subsubsection pathlib



@itemize *

@item 
Remove support for passing additional keyword arguments
to @ref{266,,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{2fc,,PurePath.relative_to()} and @ref{2fd,,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<3>,已移除
@anchor{whatsnew/3 14 pkgutil}@anchor{2fe}
@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,pkgutil,已移除
@anchor{whatsnew/3 14 pty}@anchor{2ff}
@subsubsection pty



@itemize *

@item 
Remove the @code{master_open()} and @code{slave_open()} functions,
which have been deprecated since Python 3.12.
Use @ref{300,,pty.openpty()} instead.
(Contributed by Nikita Sobolev in gh-118824@footnote{https://github.com/python/cpython/issues/118824}.)
@end itemize

@node sqlite3,urllib<2>,pty,已移除
@anchor{whatsnew/3 14 sqlite3}@anchor{301}
@subsubsection sqlite3



@itemize *

@item 
Remove @code{version} and @code{version_info} from
the @ref{d4,,sqlite3} module;
use @ref{302,,sqlite_version} and @ref{303,,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{304,,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,已移除
@anchor{whatsnew/3 14 id12}@anchor{305}
@subsubsection urllib



@itemize *

@item 
Remove the @code{Quoter} class from @ref{110,,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{111,,urllib.request},
which have been deprecated since Python 3.3.

@code{myopener.open()} can be replaced with @ref{306,,urlopen()}.
@code{myopener.retrieve()} can be replaced with
@ref{307,,urlretrieve()}.
Customisations to the opener classes can be replaced by passing
customized handlers to @ref{308,,build_opener()}.
(Contributed by Barney Gale in gh-84850@footnote{https://github.com/python/cpython/issues/84850}.)
@end itemize

@node 已棄用,CPython 位元組碼變更,已移除,Python 3 14 有什麼新功能
@anchor{whatsnew/3 14 deprecated}@anchor{309}
@subsection 已棄用


@menu
* New deprecations:: 
* Python 3.15 中待移除的項目: Python 3 15 中待移除的項目. 
* Python 3.16 中待移除的項目: Python 3 16 中待移除的項目. 
* Python 3.17 中待移除的項目: Python 3 17 中待移除的項目. 
* Python 3.19 中待移除的項目: Python 3 19 中待移除的項目. 
* 未來版本中的待移除項目:: 

@end menu

@node New deprecations,Python 3 15 中待移除的項目,,已棄用
@anchor{whatsnew/3 14 new-deprecations}@anchor{30a}
@subsubsection New deprecations



@itemize *

@item 
在 @ref{197,,complex()} 建構函式中將複數作為 `real' 或 `imag' 引數傳遞現在已被棄用；複數應該只作為單個位置引數傳遞。 (由 Serhiy Storchaka 於 gh-109218@footnote{https://github.com/python/cpython/issues/109218} 貢獻。)

@item 
@ref{7,,argparse}：


@itemize *

@item 
將未以文件記錄的關鍵字引數 `prefix_chars' 傳遞給 @ref{2ea,,add_argument_group()} 的做法現在已被棄用。（由 Savannah Ostrowski 於 gh-125563@footnote{https://github.com/python/cpython/issues/125563} 貢獻。）

@item 
Deprecated the @ref{30b,,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 
@code{asyncio.iscoroutinefunction()} 已被棄用並將在 Python 3.16 中移除；請改用 @ref{30c,,inspect.iscoroutinefunction()}。（由 Jiahao Li 和 Kumar Aditya 於 gh-122875@footnote{https://github.com/python/cpython/issues/122875} 貢獻。）

@item 
@ref{b,,asyncio} 策略系統已被棄用並將在 Python 3.16 中移除。特別是以下類別和函式已被棄用：


@itemize *

@item 
@ref{30d,,asyncio.AbstractEventLoopPolicy}

@item 
@ref{30e,,asyncio.DefaultEventLoopPolicy}

@item 
@ref{30f,,asyncio.WindowsSelectorEventLoopPolicy}

@item 
@ref{310,,asyncio.WindowsProactorEventLoopPolicy}

@item 
@ref{311,,asyncio.get_event_loop_policy()}

@item 
@ref{312,,asyncio.set_event_loop_policy()}
@end itemize

使用者應該使用 @ref{2f2,,asyncio.run()} 或 @ref{2f4,,asyncio.Runner} 搭配 `loop_factory' 引數來使用所需的事件迴圈實作。

例如在 Windows 上使用 @ref{313,,asyncio.SelectorEventLoop}：

@example
import asyncio

async def main():
    ...

asyncio.run(main(), loop_factory=asyncio.SelectorEventLoop)
@end example

（由 Kumar Aditya 於 gh-127949@footnote{https://github.com/python/cpython/issues/127949} 貢獻。）
@end itemize

@item 
@ref{1c,,codecs}: @ref{314,,codecs.open()} 函式已被棄用，並將在未來的 Python 版本中移除。請改用 @ref{315,,open()}。（由 Inada Naoki 於 gh-133036@footnote{https://github.com/python/cpython/issues/133036} 貢獻。）

@item 
@ref{2e,,ctypes}：


@itemize *

@item 
On non-Windows platforms, setting @ref{316,,Structure._pack_} to use a
MSVC-compatible default memory layout is now deprecated in favor of setting
@ref{1e7,,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{1f1,,ctypes.POINTER()} on a string is now deprecated.
Use @ref{317,,incomplete types}
for self-referential structures.
Also, the internal @code{ctypes._pointer_type_cache} is deprecated.
See @ref{1f1,,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{63,,functools}: 使用 `function' 或 `sequence' 關鍵字引數呼叫 @ref{21a,,functools.reduce()} 的 Python 實作已被棄用；這些參數將在 Python 3.16 中變為僅限位置引數。（由 Kirill Podoprigora 於 gh-121676@footnote{https://github.com/python/cpython/issues/121676} 貢獻。）

@item 
@ref{8b,,logging}: 對具有 `strm' 引數的自訂日誌記錄處理函式的支援已被棄用，並計劃在 Python 3.16 中移除。請改為使用 `stream' 引數來定義處理函式。（由 Mariusz Felisiak 於 gh-115032@footnote{https://github.com/python/cpython/issues/115032} 貢獻。）

@item 
@ref{93,,mimetypes}: 有效的副檔名為空字串或對 @ref{318,,mimetypes.MimeTypes.add_type()} 以 '.' 開頭。未加點的副檔名已被棄用，並將在 Python 3.16 中引發 @ref{2eb,,ValueError}。（由 Hugo van Kemenade 於 gh-75223@footnote{https://github.com/python/cpython/issues/75223} 貢獻。）

@item 
@code{nturl2path}:
This module is now deprecated. Call @ref{2bd,,urllib.request.url2pathname()}
and @ref{2bf,,pathname2url()} instead.
(Contributed by Barney Gale in gh-125866@footnote{https://github.com/python/cpython/issues/125866}.)

@item 
@ref{a5,,os}:
The @ref{319,,os.popen()} and @ref{31a,,os.spawn*} functions
are now @ref{23d,,soft deprecated}.
They should no longer be used to write new code.
The @ref{dc,,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{31b,,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{de,,symtable}:
Deprecate @ref{31c,,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{f6,,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{110,,urllib.parse}:
Accepting objects with false values (like @code{0} and @code{[]}) except empty
strings, bytes-like objects and @code{None} in @ref{31d,,parse_qsl()}
and @ref{31e,,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 Python 3 15 中待移除的項目,Python 3 16 中待移除的項目,New deprecations,已棄用
@anchor{whatsnew/3 14 pending-removal-in-python-3-15}@anchor{31f}
@subsubsection Python 3.15 中待移除的項目



@itemize *

@item 
引入系統 (import system)：


@itemize *

@item 
在模組上設定 @ref{320,,__cached__} 而沒有設定 @ref{321,,__spec__.cached} 的做法已被棄用。在 Python 3.15 中，引入系統或標準函式庫將不再設定或考慮 @code{__cached__}。(gh-97879@footnote{https://github.com/python/cpython/issues/97879})

@item 
在模組上設定 @ref{322,,__package__} 而沒有設定 @ref{323,,__spec__.parent} 的做法已被棄用。在 Python 3.15 中，引入系統或標準函式庫將不再設定或考慮 @code{__package__}。(gh-97879@footnote{https://github.com/python/cpython/issues/97879})
@end itemize

@item 
@ref{2e,,ctypes}：


@itemize *

@item 
自 Python 3.13 起，未記錄的 @code{ctypes.SetPointerType()} 函式已被棄用。
@end itemize

@item 
@ref{76,,http.server}：


@itemize *

@item 
過時且很少使用的 @ref{324,,CGIHTTPRequestHandler} 自 Python 3.13 起已被棄用。不存在直接的替代。`任何東西'都比 CGI 更好地將 Web 伺服器與請求處理程序介接起來。

@item 
自 Python 3.13 起，@code{python -m http.server} 命令列介面的 @code{--cgi} 旗標已被棄用。
@end itemize

@item 
@ref{7b,,importlib}：


@itemize *

@item 
@code{load_module()} method：請改用 @code{exec_module()}。
@end itemize

@item 
@ref{8a,,locale}：


@itemize *

@item 
@ref{325,,getdefaultlocale()} 已在 Python 3.11 中被棄用，原本計劃在 Python 3.13 中移除 (gh-90817@footnote{https://github.com/python/cpython/issues/90817})，但被延後至 Python 3.15。請改用 @ref{326,,getlocale()}、@ref{327,,setlocale()} 和 @ref{328,,getencoding()}。 (由 Hugo van Kemenade 於 gh-111187@footnote{https://github.com/python/cpython/issues/111187} 貢獻。)
@end itemize

@item 
@ref{a8,,pathlib}：


@itemize *

@item 
@ref{329,,PurePath.is_reserved()} 已自 Python 3.13 被棄用。請用 @ref{32a,,os.path.isreserved()} 來偵測 Windows 上的保留路徑。
@end itemize

@item 
@ref{af,,platform}：


@itemize *

@item 
自 Python 3.13 起，@ref{32b,,java_ver()} 已被棄用。此函式僅對 Jython 支援有用，具有令人困惑的 API，基本上未經測試。
@end itemize

@item 
@ref{e1,,sysconfig}：


@itemize *

@item 
@ref{32c,,sysconfig.is_python_build()} 的 `check_home' 引數自 Python 3.12 起已被棄用。
@end itemize

@item 
@ref{f3,,threading}：


@itemize *

@item 
@ref{32d,,RLock()} 在 Python 3.15 中將不接受任何引數。自 Python 3.14 起，傳遞任何引數的用法已被棄用，因為 Python 版本不允許任何引數，但 C 版本允許任意數量的位置或關鍵字引數，並忽略每個引數。
@end itemize

@item 
@ref{109,,types}：


@itemize *

@item 
@ref{32e,,types.CodeType}：自 3.10 起，存取 @ref{32f,,co_lnotab} 已在 
@geindex Python Enhancement Proposals; PEP 626
PEP 626@footnote{https://peps.python.org/pep-0626/} 中被棄用，並計劃在 3.12 中移除，但只在 3.12 中於適當時發出 @ref{1a3,,DeprecationWarning}。可能在 3.15 中移除。（由 Nikita Sobolev 於 gh-101866@footnote{https://github.com/python/cpython/issues/101866} 貢獻。）
@end itemize

@item 
@ref{10a,,typing}：


@itemize *

@item 
用於建立 @ref{330,,NamedTuple} 類別的未以文件記錄之關鍵字引數語法 (@code{Point = NamedTuple("Point", x=int, y=int)}) 已自 Python 3.13 棄用。請改用基於類別的語法或函式語法 (functional syntax)。

@item 
當使用 @ref{331,,TypedDict} 的函式語法時，未傳遞值給 `fields' 參數 (@code{TD = TypedDict("TD")}) 或傳遞 @code{None} (@code{TD = TypedDict("TD", None)}) 的做法自 Python 3.13 起已被棄用。請使用 @code{class TD(TypedDict): pass} 或 @code{TD = TypedDict("TD", @{@})} 來建立具有零個欄位的 TypedDict。

@item 
自 Python 3.13 起，@ref{332,,typing.no_type_check_decorator()} 裝飾器函式已被棄用。在 @ref{10a,,typing} 模組中使用了八年之後，它尚未得到任何主要型別檢查器的支援。
@end itemize

@item 
@ref{119,,wave}：


@itemize *

@item 
已棄用 @ref{333,,Wave_read} 和 @ref{334,,Wave_write} 類別的 @ref{335,,getmark()}、@code{setmark()} 和 @ref{336,,getmarkers()} 方法自 Python 3.13 被棄用。
@end itemize

@item 
@ref{138,,zipimport}：


@itemize *

@item 
@ref{337,,load_module()} 自 Python 3.10 被棄用。請改用 @ref{338,,exec_module()}。（由 Jiahao Li 於 gh-125746@footnote{https://github.com/python/cpython/issues/125746} 貢獻。）
@end itemize
@end itemize

@node Python 3 16 中待移除的項目,Python 3 17 中待移除的項目,Python 3 15 中待移除的項目,已棄用
@anchor{whatsnew/3 14 pending-removal-in-python-3-16}@anchor{339}
@subsubsection Python 3.16 中待移除的項目



@itemize *

@item 
引入系統 (import system)：


@itemize *

@item 
在模組上設定 @ref{33a,,__loader__} 而沒有設定 @ref{33b,,__spec__.loader} 的做法將於 Python 3.16 被棄用。在 Python 3.16 中，引入系統或標準函式庫將不再設定或考慮 @code{__loader__}。
@end itemize

@item 
@ref{8,,array}：


@itemize *

@item 
自 Python 3.3 起，@code{'u'} 格式碼 (@code{wchar_t}) 在文件中已被棄用，自 Python 3.13 起在 runtime 已被棄用。請使用 @code{'w'} 格式碼 (@ref{33c,,Py_UCS4}) 來取代 Unicode 字元。
@end itemize

@item 
@ref{b,,asyncio}：


@itemize *

@item 
@code{asyncio.iscoroutinefunction()} 已被棄用並將在 Python 3.16 中移除；請改用 @ref{30c,,inspect.iscoroutinefunction()}。（由 Jiahao Li 和 Kumar Aditya 於 gh-122875@footnote{https://github.com/python/cpython/issues/122875} 貢獻。）

@item 
@ref{b,,asyncio} 策略系統已被棄用並將在 Python 3.16 中移除。特別是以下類別和函式已被棄用：


@itemize *

@item 
@ref{30d,,asyncio.AbstractEventLoopPolicy}

@item 
@ref{30e,,asyncio.DefaultEventLoopPolicy}

@item 
@ref{30f,,asyncio.WindowsSelectorEventLoopPolicy}

@item 
@ref{310,,asyncio.WindowsProactorEventLoopPolicy}

@item 
@ref{311,,asyncio.get_event_loop_policy()}

@item 
@ref{312,,asyncio.set_event_loop_policy()}
@end itemize

使用者應該使用 @ref{2f2,,asyncio.run()} 或 @ref{2f4,,asyncio.Runner} 搭配 `loop_factory' 來使用所需的事件迴圈實作。

例如在 Windows 上使用 @ref{313,,asyncio.SelectorEventLoop}：

@example
import asyncio

async def main():
    ...

asyncio.run(main(), loop_factory=asyncio.SelectorEventLoop)
@end example

（由 Kumar Aditya 於 gh-127949@footnote{https://github.com/python/cpython/issues/127949} 貢獻。）
@end itemize

@item 
@ref{13,,builtins}：


@itemize *

@item 
自 Python 3.12 起，布林型別的位元反轉 @code{~True} 或 @code{~False} 已被棄用，因為它會產生不預期且不直觀的結果（@code{-2} 和 @code{-1}）。使用 @code{not x} 代替布林值的邏輯否定。在極少數情況下，你需要對底層的整數進行位元反轉，請明確轉換為 @code{~int(x)} (@code{~int(x)})。
@end itemize

@item 
@ref{63,,functools}：


@itemize *

@item 
自 Python 3.14 起，使用 `function' 或 `sequence' 關鍵字引數呼叫 @ref{21a,,functools.reduce()} 的 Python 實作已被棄用。
@end itemize

@item 
@ref{8b,,logging}：

對具有 `strm' 引數的自訂日誌記錄處理函式的支援已被棄用，並計劃在 Python 3.16 中移除。請改用 `stream' 引數。（由 Mariusz Felisiak 於 gh-115032@footnote{https://github.com/python/cpython/issues/115032} 貢獻。）

@item 
@ref{93,,mimetypes}：


@itemize *

@item 
有效的副檔名以 '.' 開頭或對 @ref{318,,mimetypes.MimeTypes.add_type()} 為空字串。未加點的副檔名已被棄用，並將在 Python 3.16 中引發 @ref{2eb,,ValueError}。（由 Hugo van Kemenade 於 gh-75223@footnote{https://github.com/python/cpython/issues/75223} 貢獻。）
@end itemize

@item 
@ref{ca,,shutil}：


@itemize *

@item 
自 Python 3.14 起，@code{ExecError} 例外已被棄用。自 Python 3.4 以來，它尚未被 @code{shutil} 中的任何函式使用，現在是 @ref{244,,RuntimeError} 的別名。
@end itemize

@item 
@ref{de,,symtable}：


@itemize *

@item 
自 Python 3.14 起，@ref{31c,,Class.get_methods} 方法已被棄用。
@end itemize

@item 
@ref{df,,sys}：


@itemize *

@item 
自 Python 3.13 起，@ref{33d,,_enablelegacywindowsfsencoding()} 函式已被棄用。請改用 
@geindex PYTHONLEGACYWINDOWSFSENCODING
@geindex 環境變數; PYTHONLEGACYWINDOWSFSENCODING
@ref{33e,,PYTHONLEGACYWINDOWSFSENCODING} 環境變數。
@end itemize

@item 
@ref{e1,,sysconfig}：


@itemize *

@item 
自 Python 3.14 起，@code{sysconfig.expand_makefile_vars()} 函式已被棄用。請改用 @ref{33f,,sysconfig.get_paths()} 的 @code{vars} 引數。
@end itemize

@item 
@ref{e4,,tarfile}：


@itemize *

@item 
自 Python 3.13 起，未以文件記錄和未被使用的 @code{TarFile.tarfile} 屬性已被棄用。
@end itemize
@end itemize

@node Python 3 17 中待移除的項目,Python 3 19 中待移除的項目,Python 3 16 中待移除的項目,已棄用
@anchor{whatsnew/3 14 pending-removal-in-python-3-17}@anchor{340}
@subsubsection Python 3.17 中待移除的項目



@itemize *

@item 
@ref{1f,,collections.abc}：


@itemize -

@item 
@ref{341,,collections.abc.ByteString} 預計在 Python 3.17 中移除。

使用 @code{isinstance(obj, collections.abc.Buffer)} 來測試 @code{obj} 是否在 runtime 實作了@ref{260,,緩衝區協定}。在型別註解的使用中，請用 @ref{342,,Buffer} 或明確指定你的程式碼所支援型別的聯集（例如 @code{bytes | bytearray | memoryview}）。

@code{ByteString} 最初被設計為一個抽象類別，以作為 @ref{192,,bytes} 和 @ref{343,,bytearray} 的超型別 (supertype)。然而由於 ABC 從未擁有任何方法，知道一個物件是 @code{ByteString} 的實例從未真正告訴你任何關於該物件的有用資訊。其他常見的緩衝區型別如 @ref{165,,memoryview} 也從未被理解為 @code{ByteString} 的子型別（無論是在 runtime 還是由靜態型別檢查器）。

更多細節請見 
@geindex Python Enhancement Proposals; PEP 688#current-options
PEP 688@footnote{https://peps.python.org/pep-0688/#current-options}。（由 Shantanu Jain 於 gh-91896@footnote{https://github.com/python/cpython/issues/91896} 貢獻。）
@end itemize

@item 
@ref{10a,,typing}：


@itemize -

@item 
在 Python 3.14 之前，舊式聯集是使用私有類別 @code{typing._UnionGenericAlias} 實作的。這個類別不再被需要，但為了向後相容性而保留，並計劃將在 Python 3.17 中移除。使用者應該改用文件中記錄的內省輔助函式，例如 @ref{2ab,,typing.get_origin()} 和 @ref{2ac,,typing.get_args()}，或者依賴私有實作細節。

@item 
@ref{344,,typing.ByteString} 自 Python 3.9 起已被棄用，預計在 Python 3.17 中移除。

使用 @code{isinstance(obj, collections.abc.Buffer)} 來測試 @code{obj} 是否在 runtime 實作了@ref{260,,緩衝區協定}。在型別註解的使用中，請用 @ref{342,,Buffer} 或明確指定你的程式碼所支援型別的聯集（例如 @code{bytes | bytearray | memoryview}）。

@code{ByteString} 最初被設計為一個抽象類別，以作為 @ref{192,,bytes} 和 @ref{343,,bytearray} 的超型別 (supertype)。然而由於 ABC 從未擁有任何方法，知道一個物件是 @code{ByteString} 的實例從未真正告訴你任何關於該物件的有用資訊。其他常見的緩衝區型別如 @ref{165,,memoryview} 也從未被理解為 @code{ByteString} 的子型別（無論是在 runtime 還是由靜態型別檢查器）。

更多細節請見 
@geindex Python Enhancement Proposals; PEP 688#current-options
PEP 688@footnote{https://peps.python.org/pep-0688/#current-options}。（由 Shantanu Jain 於 gh-91896@footnote{https://github.com/python/cpython/issues/91896} 貢獻。）
@end itemize
@end itemize

@node Python 3 19 中待移除的項目,未來版本中的待移除項目,Python 3 17 中待移除的項目,已棄用
@anchor{whatsnew/3 14 pending-removal-in-python-3-19}@anchor{345}
@subsubsection Python 3.19 中待移除的項目



@itemize *

@item 
@ref{2e,,ctypes}：


@itemize *

@item 
在非 Windows 平台上，透過設定 @ref{316,,_pack_} 而沒有設定 @ref{1e7,,_layout_} 來隱式地切換到與 MSVC 相容的結構佈局。
@end itemize
@end itemize

@node 未來版本中的待移除項目,,Python 3 19 中待移除的項目,已棄用
@anchor{whatsnew/3 14 pending-removal-in-future-versions}@anchor{346}
@subsubsection 未來版本中的待移除項目


以下 API 將在未來被移除，雖然目前尚未安排移除日期。


@itemize *

@item 
@ref{7,,argparse}：


@itemize *

@item 
巢狀引數群組和巢狀互斥群組已被棄用。

@item 
將未以文件記錄的關鍵字引數 `prefix_chars' 傳遞給 @ref{2ea,,add_argument_group()} 的做法現在已被棄用。

@item 
@ref{30b,,argparse.FileType} 型別轉換器已被棄用。
@end itemize

@item 
@ref{13,,builtins}：


@itemize *

@item 
產生器：@code{throw(type, exc, tb)} 和 @code{athrow(type, exc, tb)} 簽名已被棄用：請改用 @code{throw(exc)} 和 @code{athrow(exc)}，為單引數簽名。

@item 
目前 Python 接受數值字面值後面立即接關鍵字，例如 @code{0in x}、@code{1or x}、@code{0if 1else 2}。它讓運算式模糊且容易混淆，如 @code{[0x1for x in y]}（可以解釋為 @code{[0x1 for x in y]} 或 @code{[0x1f or x in y]}）。如果數值字面值後立即接 @ref{347,,and}、@ref{17c,,else}、@ref{348,,for}、@ref{181,,if}、@ref{349,,in}、@ref{34a,,is} 和 @ref{34b,,or} 之一的關鍵字，則會引發語法警告。在未來版本中，它將被更改為語法錯誤。(gh-87999@footnote{https://github.com/python/cpython/issues/87999})

@item 
@code{__index__()} 和 @code{__int__()} 方法回傳非 int 型別的支援：這些方法將需要回傳 @ref{19b,,int} 的嚴格子類別實例。

@item 
回傳 @ref{196,,float} 嚴格子類別 @code{__float__()} 方法的支援：這些方法將需要回傳 @ref{196,,float} 的實例。

@item 
回傳 @ref{197,,complex} 嚴格子類別 @code{__complex__()} 方法的支援：這些方法將需要回傳 @ref{197,,complex} 的實例。

@item 
將 @code{int()} 委派給 @code{__trunc__()} 方法。

@item 
在 @ref{197,,complex()} 建構子中將複數作為 `real' 或 `imag' 引數傳遞現在已被棄用；它應該只作為單個位置引數傳遞。 (由 Serhiy Storchaka 於 gh-109218@footnote{https://github.com/python/cpython/issues/109218} 貢獻。)
@end itemize

@item 
@ref{15,,calendar}：@code{calendar.January} 和 @code{calendar.February} 常數已被棄用並被 @ref{34c,,calendar.JANUARY} 和 @ref{34d,,calendar.FEBRUARY} 取代。 (由 Prince Roshan 於 gh-103636@footnote{https://github.com/python/cpython/issues/103636} 貢獻。)

@item 
@ref{1c,,codecs}：請改用 @ref{315,,open()} 而非 @ref{314,,codecs.open()}。(gh-133038@footnote{https://github.com/python/cpython/issues/133038})

@item 
@ref{32f,,codeobject.co_lnotab}：請改用 @ref{34e,,codeobject.co_lines()} 方法。

@item 
@ref{34,,datetime}：


@itemize *

@item 
@ref{34f,,utcnow()}：請改用 @code{datetime.datetime.now(tz=datetime.UTC)}。

@item 
@ref{350,,utcfromtimestamp()}：請改用 @code{datetime.datetime.fromtimestamp(timestamp, tz=datetime.UTC)}。
@end itemize

@item 
@ref{67,,gettext}：複數值必須是整數。

@item 
@ref{7b,,importlib}：


@itemize *

@item 
@ref{351,,cache_from_source()} `debug_override' 參數已被棄用：請改用 `optimization' 參數。
@end itemize

@item 
@ref{7e,,importlib.metadata}：


@itemize *

@item 
@code{EntryPoints} 元組介面。

@item 
回傳值上的隱式 @code{None}。
@end itemize

@item 
@ref{8b,,logging}：自 Python 3.3 起，@code{warn()} 方法已被棄用，請改用 @ref{352,,warning()}。

@item 
@ref{8f,,mailbox}：已棄用 StringIO 輸入和文本模式，請改用 BytesIO 和二進位模式。

@item 
@ref{a5,,os}：在多執行緒行程中呼叫 @ref{353,,os.register_at_fork()}。

@item 
@code{pydoc.ErrorDuringImport}：`exc_info' 參數的元組值已被棄用，請用例外實例。

@item 
@ref{be,,re}：現在對正規表示式中的數值群組參照和群組名稱用了更嚴格的規則。現在只有 ASCII 數碼序列被接受作為數值參照。位元組模式和替換字串中的群組名稱現在只能包含 ASCII 字母、數碼和底線。（由 Serhiy Storchaka 於 gh-91760@footnote{https://github.com/python/cpython/issues/91760} 貢獻。）

@item 
@code{sre_compile}、@code{sre_constants} 和 @code{sre_parse} 模組。

@item 
@ref{ca,,shutil}：@ref{354,,rmtree()} 的 `onerror' 參數在 Python 3.12 中已被棄用；請改用 `onexc' 參數。

@item 
@ref{d5,,ssl} 選項和協定：


@itemize *

@item 
不帶協定引數的 @ref{355,,ssl.SSLContext} 已被棄用。

@item 
@ref{355,,ssl.SSLContext}：@ref{356,,set_npn_protocols()} 和 @code{selected_npn_protocol()} 已被棄用：請改用 ALPN。

@item 
@code{ssl.OP_NO_SSL*} 選項

@item 
@code{ssl.OP_NO_TLS*} 選項

@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{f3,,threading} 方法：


@itemize *

@item 
@code{threading.Condition.notifyAll()}：請用 @ref{357,,notify_all()}。

@item 
@code{threading.Event.isSet()}：請用 @ref{358,,is_set()}。

@item 
@code{threading.Thread.isDaemon()}、@ref{359,,threading.Thread.setDaemon()}：請用 @ref{35a,,threading.Thread.daemon} 屬性。

@item 
@code{threading.Thread.getName()}、@ref{35b,,threading.Thread.setName()}：請用 @ref{2a0,,threading.Thread.name} 屬性。

@item 
@code{threading.currentThread()}：請用 @ref{35c,,threading.current_thread()}。

@item 
@code{threading.activeCount()}：請用 @ref{35d,,threading.active_count()}。
@end itemize

@item 
@ref{35e,,typing.Text} (gh-92332@footnote{https://github.com/python/cpython/issues/92332})。

@item 
內部類別 @code{typing._UnionGenericAlias} 不再用於實作 @ref{2a8,,typing.Union}。為了保持與此私有類別使用者的相容性，直到至少 Python 3.17 都將提供一個相容性 shim。（由 Jelle Zijlstra 於 gh-105499@footnote{https://github.com/python/cpython/issues/105499} 貢獻。）

@item 
@ref{35f,,unittest.IsolatedAsyncioTestCase}：從測試案例中回傳非 @code{None} 的值已被棄用。

@item 
@ref{110,,urllib.parse} 已棄用函式：請改用 @ref{360,,urlparse()}。


@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{11e,,wsgiref}：@code{SimpleHandler.stdout.write()} 不應該進行部分寫入。

@item 
@ref{12b,,xml.etree.ElementTree}：已棄用對 @ref{361,,Element} 的真值測試。在未來版本中，它將始終回傳 @code{True}。請改用明確的 @code{len(elem)} 或 @code{elem is not None} 測試。

@item 
@ref{292,,sys._clear_type_cache()} 已被棄用：請改用 @ref{362,,sys._clear_internal_caches()}。
@end itemize

@node CPython 位元組碼變更,C API 變更,已棄用,Python 3 14 有什麼新功能
@anchor{whatsnew/3 14 cpython-bytecode-changes}@anchor{363}
@subsection CPython 位元組碼變更



@itemize *

@item 
Replaced the opcode @code{BINARY_SUBSCR} by the @ref{364,,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{365,,BUILD_INTERPOLATION} and @ref{366,,BUILD_TEMPLATE}
opcodes to construct new @ref{16b,,Interpolation}
and @ref{16a,,Template} instances, respectively.
(Contributed by Lysandros Nikolaou and others in gh-132661@footnote{https://github.com/python/cpython/issues/132661};
see also @ref{144,,PEP 750; Template strings}).

@item 
Remove the @code{BUILD_CONST_KEY_MAP} opcode.
Use @ref{367,,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{368,,LOAD_COMMON_CONSTANT} and add support for loading
@ref{369,,NotImplementedError}.

@item 
Add the @ref{36a,,LOAD_FAST_BORROW} and @ref{36b,,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{36c,,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{36d,,LOAD_SPECIAL} instruction.
Generate code for @ref{186,,with} and @ref{185,,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{36e,,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 位元組碼變更
@anchor{whatsnew/3 14 pseudo-instructions}@anchor{36f}
@subsubsection Pseudo-instructions



@itemize *

@item 
Add the @code{ANNOTATIONS_PLACEHOLDER} pseudo instruction
to support partially executed module-level annotations with
@ref{145,,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{370,,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{371,,JUMP_IF_TRUE} and @ref{372,,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 @ref{373,,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{374,,NOT_TAKEN} pseudo instruction, used by @ref{e0,,sys.monitoring}
to record branch events (such as @ref{295,,BRANCH_LEFT}).
(Contributed by Mark Shannon in gh-122548@footnote{https://github.com/python/cpython/issues/122548}.)
@end itemize

@node C API 變更,建置變更,CPython 位元組碼變更,Python 3 14 有什麼新功能
@anchor{whatsnew/3 14 c-api-changes}@anchor{375}
@subsection C API 變更


@menu
* Python configuration C API:: 
* C API 中的新功能:: 
* Limited C API changes:: 
* 被移除的 C API:: 
* 已棄用的 C API:: 

@end menu

@node Python configuration C API,C API 中的新功能,,C API 變更
@anchor{whatsnew/3 14 python-configuration-c-api}@anchor{376}@anchor{whatsnew/3 14 whatsnew314-capi-config}@anchor{155}
@subsubsection Python configuration C API


Add a @ref{377,,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{378,,PyConfig C API} by adding
@ref{379,,PyInitConfig_AddModule()} which can be used to add a built-in extension
module; a feature previously referred to as the "inittab".

Add @ref{37a,,PyConfig_Get()} and @ref{37b,,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).

（由 Victor Stinner 於 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/} 和 
@geindex Python Enhancement Proposals; PEP 587
PEP 587@footnote{https://peps.python.org/pep-0587/}


@node C API 中的新功能,Limited C API changes,Python configuration C API,C API 變更
@anchor{whatsnew/3 14 new-features-in-the-c-api}@anchor{37c}
@subsubsection C API 中的新功能



@itemize *

@item 
Add @ref{37d,,Py_PACK_VERSION()} and @ref{37e,,Py_PACK_FULL_VERSION()},
two new macros for bit-packing Python version numbers.
This is useful for comparisons with @ref{37f,,Py_Version}
or @ref{380,,PY_VERSION_HEX}.
(Contributed by Petr Viktorin in gh-128629@footnote{https://github.com/python/cpython/issues/128629}.)

@item 
Add @ref{381,,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 
新增用於操作目前 runtime Python 直譯器配置的函式（@ref{155,,PEP 741：Python 配置 C API}）：


@itemize *

@item 
@ref{37a,,PyConfig_Get()}

@item 
@ref{382,,PyConfig_GetInt()}

@item 
@ref{37b,,PyConfig_Set()}

@item 
@ref{383,,PyConfig_Names()}
@end itemize

（由 Victor Stinner 於 gh-107954@footnote{https://github.com/python/cpython/issues/107954} 貢獻。）

@item 
新增用於配置 Python 初始化的函式（@ref{155,,PEP 741：Python 配置 C API}）：


@itemize *

@item 
@ref{384,,Py_InitializeFromInitConfig()}

@item 
@ref{379,,PyInitConfig_AddModule()}

@item 
@ref{385,,PyInitConfig_Create()}

@item 
@ref{386,,PyInitConfig_Free()}

@item 
@ref{387,,PyInitConfig_FreeStrList()}

@item 
@ref{388,,PyInitConfig_GetError()}

@item 
@ref{389,,PyInitConfig_GetExitCode()}

@item 
@ref{38a,,PyInitConfig_GetInt()}

@item 
@ref{38b,,PyInitConfig_GetStr()}

@item 
@ref{38c,,PyInitConfig_GetStrList()}

@item 
@ref{38d,,PyInitConfig_HasOption()}

@item 
@ref{38e,,PyInitConfig_SetInt()}

@item 
@ref{38f,,PyInitConfig_SetStr()}

@item 
@ref{390,,PyInitConfig_SetStrList()}
@end itemize

（由 Victor Stinner 於 gh-107954@footnote{https://github.com/python/cpython/issues/107954} 貢獻。）

@item 
Add @ref{391,,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{392,,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{393,,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{394,,PyImport_ImportModuleAttr()} and
@ref{395,,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{396,,PyIter_NextItem()} to replace @ref{397,,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{398,,PyLong_GetSign()} function to get the sign of @ref{19b,,int} objects.
(Contributed by Sergey B Kirpichev in gh-116560@footnote{https://github.com/python/cpython/issues/116560}.)

@item 
Add @ref{399,,PyLong_IsPositive()}, @ref{39a,,PyLong_IsNegative()}
and @ref{39b,,PyLong_IsZero()} for checking if @ref{39c,,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{19b,,int} objects:


@itemize *

@item 
@ref{39d,,PyLong_AsInt32()}

@item 
@ref{39e,,PyLong_AsInt64()}

@item 
@ref{39f,,PyLong_AsUInt32()}

@item 
@ref{3a0,,PyLong_AsUInt64()}

@item 
@ref{3a1,,PyLong_FromInt32()}

@item 
@ref{3a2,,PyLong_FromInt64()}

@item 
@ref{3a3,,PyLong_FromUInt32()}

@item 
@ref{3a4,,PyLong_FromUInt64()}
@end itemize

（由 Victor Stinner 於 gh-120389@footnote{https://github.com/python/cpython/issues/120389} 貢獻。）

@item 
Add a new import and export API for Python @ref{19b,,int} objects
(
@geindex Python Enhancement Proposals; PEP 757
PEP 757@footnote{https://peps.python.org/pep-0757/}):


@itemize *

@item 
@ref{3a5,,PyLong_GetNativeLayout()}

@item 
@ref{3a6,,PyLong_Export()}

@item 
@ref{3a7,,PyLong_FreeExport()}

@item 
@ref{3a8,,PyLongWriter_Create()}

@item 
@ref{3a9,,PyLongWriter_Finish()}

@item 
@ref{3aa,,PyLongWriter_Discard()}
@end itemize

（由 Sergey B Kirpichev 和 Victor Stinner 於 gh-102471@footnote{https://github.com/python/cpython/issues/102471} 貢獻。）

@item 
Add @ref{3ab,,PyMonitoring_FireBranchLeftEvent()} and
@ref{3ac,,PyMonitoring_FireBranchRightEvent()} for generating
@ref{295,,BRANCH_LEFT} and @ref{296,,BRANCH_RIGHT}
events, respectively.
(Contributed by Mark Shannon in gh-122548@footnote{https://github.com/python/cpython/issues/122548}.)

@item 
Add @ref{3ad,,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{3ae,,PyType_GetBaseByToken()} and @ref{3af,,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{3b0,,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{3b1,,PyUnicodeWriter} API to create a Python @ref{169,,str}
object, with the following functions:


@itemize *

@item 
@ref{3b2,,PyUnicodeWriter_Create()}

@item 
@ref{3b3,,PyUnicodeWriter_DecodeUTF8Stateful()}

@item 
@ref{3b4,,PyUnicodeWriter_Discard()}

@item 
@ref{3b5,,PyUnicodeWriter_Finish()}

@item 
@ref{3b6,,PyUnicodeWriter_Format()}

@item 
@ref{3b7,,PyUnicodeWriter_WriteASCII()}

@item 
@ref{3b8,,PyUnicodeWriter_WriteChar()}

@item 
@ref{3b9,,PyUnicodeWriter_WriteRepr()}

@item 
@ref{3ba,,PyUnicodeWriter_WriteStr()}

@item 
@ref{3bb,,PyUnicodeWriter_WriteSubstring()}

@item 
@ref{3bc,,PyUnicodeWriter_WriteUCS4()}

@item 
@ref{3bd,,PyUnicodeWriter_WriteUTF8()}

@item 
@ref{3be,,PyUnicodeWriter_WriteWideChar()}
@end itemize

（由 Victor Stinner 於 gh-119182@footnote{https://github.com/python/cpython/issues/119182} 貢獻。）

@item 
The @code{k} and @code{K} formats in @ref{3bf,,PyArg_ParseTuple()} and
similar functions now use @ref{19e,,__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{3c0,,Py_BuildValue()}
that produces a Python @ref{3c1,,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{3c2,,PyUnstable_IsImmortal()} for determining if
an object is @ref{290,,immortal}, for debugging purposes.
(Contributed by Peter Bierma in gh-128509@footnote{https://github.com/python/cpython/issues/128509}.)

@item 
Add @ref{3c3,,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{3c4,,PyUnstable_Object_IsUniquelyReferenced()} as
a replacement for @code{Py_REFCNT(op) == 1} on @ref{1f4,,free threaded} builds.
(Contributed by Peter Bierma in gh-133140@footnote{https://github.com/python/cpython/issues/133140}.)

@item 
Add @ref{3c5,,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{2cf,,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,被移除的 C API,C API 中的新功能,C API 變更
@anchor{whatsnew/3 14 limited-c-api-changes}@anchor{3c6}
@subsubsection Limited C API changes



@itemize *

@item 
In the limited C API version 3.14 and newer, @ref{3c7,,Py_TYPE()} and
@ref{2cf,,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{3c8,,PySequence_Fast_GET_SIZE},
@ref{3c9,,PySequence_Fast_GET_ITEM},
and @ref{3ca,,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 被移除的 C API,已棄用的 C API,Limited C API changes,C API 變更
@anchor{whatsnew/3 14 removed-c-apis}@anchor{3cb}@anchor{whatsnew/3 14 whatsnew314-c-api-removed}@anchor{3cc}
@subsubsection 被移除的 C API



@itemize *

@item 
Creating @ref{3cd,,immutable types} with
mutable bases was deprecated in Python 3.12,
and now raises a @ref{198,,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{3ce,,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{3cf,,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{3d0,,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 已棄用的 C API,,被移除的 C API,C API 變更
@anchor{whatsnew/3 14 deprecated-c-apis}@anchor{3d1}@anchor{whatsnew/3 14 whatsnew314-c-api-deprecated}@anchor{3d2}
@subsubsection 已棄用的 C API



@itemize *

@item 
The @code{Py_HUGE_VAL} macro is now @ref{23d,,soft deprecated}.
Use @code{Py_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{23d,,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{3bf,,PyArg_ParseTuple()} and other @ref{3d3,,argument parsing} functions if `items' contains format units
which store a @ref{3d4,,borrowed buffer} or a
@ref{3d5,,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{3ab,,PyMonitoring_FireBranchLeftEvent()} and
@ref{3ac,,PyMonitoring_FireBranchRightEvent()}.

@item 
The previously undocumented function @ref{3d6,,PySequence_In()} is
now @ref{23d,,soft deprecated}.
Use @ref{3d7,,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
* Python 3.15 中待移除的項目: Python 3 15 中待移除的項目<2>. 
* Python 3.16 中待移除的項目: Python 3 16 中待移除的項目<2>. 
* Python 3.18 中待移除的項目: Python 3 18 中待移除的項目. 
* 未來版本中的待移除項目: 未來版本中的待移除項目<2>. 

@end menu

@node Python 3 15 中待移除的項目<2>,Python 3 16 中待移除的項目<2>,,已棄用的 C API
@anchor{whatsnew/3 14 id13}@anchor{3d8}
@subsubsection Python 3.15 中待移除的項目



@itemize *

@item 
@ref{3d9,,PyImport_ImportModuleNoBlock()}：請改用 @ref{3da,,PyImport_ImportModule()}。

@item 
@ref{3db,,PyWeakref_GetObject()} 和 @ref{3dc,,PyWeakref_GET_OBJECT()}：請改用 @ref{3dd,,PyWeakref_GetRef()}。可以使用 pythoncapi-compat 專案@footnote{https://github.com/python/pythoncapi-compat/}來為 Python 3.12 和更早版本取得 @ref{3dd,,PyWeakref_GetRef()}。

@item 
@ref{3de,,Py_UNICODE} 型別與 @code{Py_UNICODE_WIDE} 巨集：請改用 @code{wchar_t}。

@item 
@code{PyUnicode_AsDecodedObject()}：請改用 @ref{3df,,PyCodec_Decode()}。

@item 
@code{PyUnicode_AsDecodedUnicode()}：請改用 @ref{3df,,PyCodec_Decode()}；請注意某些編解碼器（例如 "base64"）可能會回傳非 @ref{169,,str} 的型別，例如 @ref{192,,bytes}。

@item 
@code{PyUnicode_AsEncodedObject()}：請改用 @ref{3e0,,PyCodec_Encode()}。

@item 
@code{PyUnicode_AsEncodedUnicode()}：請改用 @ref{3e0,,PyCodec_Encode()}；請注意某些編解碼器（例如 "base64"）可能會回傳非 @ref{192,,bytes} 的型別，例如 @ref{169,,str}。

@item 
Python 初始化函式，自 Python 3.13 起已被棄用：


@itemize *

@item 
@ref{3e1,,Py_GetPath()}：請改用 @ref{37a,,PyConfig_Get("module_search_paths")} (@ref{3e2,,sys.path})。

@item 
@ref{3e3,,Py_GetPrefix()}：請改用 @ref{37a,,PyConfig_Get("base_prefix")} (@ref{3e4,,sys.base_prefix})。如果需要處理@ref{3e5,,虛擬環境}，請改用 @ref{37a,,PyConfig_Get("prefix")} (@ref{3e6,,sys.prefix})。

@item 
@ref{3e7,,Py_GetExecPrefix()}：請改用 @ref{37a,,PyConfig_Get("base_exec_prefix")} (@ref{3e8,,sys.base_exec_prefix})。如果需要處理@ref{3e5,,虛擬環境}，請改用 @ref{37a,,PyConfig_Get("exec_prefix")} (@ref{3e9,,sys.exec_prefix})。

@item 
@ref{3ea,,Py_GetProgramFullPath()}：請改用 @ref{37a,,PyConfig_Get("executable")} (@ref{3eb,,sys.executable})。

@item 
@ref{3ec,,Py_GetProgramName()}：請改用 @ref{37a,,PyConfig_Get("executable")} (@ref{3eb,,sys.executable})。

@item 
@ref{3ed,,Py_GetPythonHome()}：請改用 @ref{37a,,PyConfig_Get("home")} 或 
@geindex PYTHONHOME
@geindex 環境變數; PYTHONHOME
@ref{3ee,,PYTHONHOME} 環境變數。
@end itemize

pythoncapi-compat 專案@footnote{https://github.com/python/pythoncapi-compat/} 可以用來為 Python 3.13 和更早版本取得 @ref{37a,,PyConfig_Get()}。

@item 
用於配置 Python 初始化的函式，自 Python 3.11 起已被棄用：


@itemize *

@item 
@code{PySys_SetArgvEx()}：請改用 @ref{3ef,,PyConfig.argv}。

@item 
@code{PySys_SetArgv()}：請改用 @ref{3ef,,PyConfig.argv}。

@item 
@code{Py_SetProgramName()}：請改用 @ref{3f0,,PyConfig.program_name}。

@item 
@code{Py_SetPythonHome()}：請改用 @ref{3f1,,PyConfig.home}。

@item 
@ref{3f2,,PySys_ResetWarnOptions()}：請改為清除 @ref{3f3,,sys.warnoptions} 和 @code{warnings.filters}。
@end itemize

應改用帶有 @ref{3f4,,PyConfig} 的 @ref{3f5,,Py_InitializeFromConfig()} API。

@item 
全域配置變數：


@itemize *

@item 
@ref{3f6,,Py_DebugFlag}：請改用 @ref{3f7,,PyConfig.parser_debug} 或 @ref{37a,,PyConfig_Get("parser_debug")}。

@item 
@ref{3f8,,Py_VerboseFlag}：請改用 @ref{3f9,,PyConfig.verbose} 或 @ref{37a,,PyConfig_Get("verbose")}。

@item 
@ref{3fa,,Py_QuietFlag}：請改用 @ref{3fb,,PyConfig.quiet} 或 @ref{37a,,PyConfig_Get("quiet")}。

@item 
@ref{3fc,,Py_InteractiveFlag}：請改用 @ref{3fd,,PyConfig.interactive} 或 @ref{37a,,PyConfig_Get("interactive")}。

@item 
@ref{3fe,,Py_InspectFlag}：請改用 @ref{3ff,,PyConfig.inspect} 或 @ref{37a,,PyConfig_Get("inspect")}。

@item 
@ref{400,,Py_OptimizeFlag}：請改用 @ref{401,,PyConfig.optimization_level} 或 @ref{37a,,PyConfig_Get("optimization_level")}。

@item 
@ref{402,,Py_NoSiteFlag}：請改用 @ref{403,,PyConfig.site_import} 或 @ref{37a,,PyConfig_Get("site_import")}。

@item 
@ref{404,,Py_BytesWarningFlag}：請改用 @ref{405,,PyConfig.bytes_warning} 或 @ref{37a,,PyConfig_Get("bytes_warning")}。

@item 
@ref{406,,Py_FrozenFlag}：請改用 @ref{407,,PyConfig.pathconfig_warnings} 或 @ref{37a,,PyConfig_Get("pathconfig_warnings")}。

@item 
@ref{408,,Py_IgnoreEnvironmentFlag}：請改用 @ref{409,,PyConfig.use_environment} 或 @ref{37a,,PyConfig_Get("use_environment")}。

@item 
@ref{40a,,Py_DontWriteBytecodeFlag}：請改用 @ref{40b,,PyConfig.write_bytecode} 或 @ref{37a,,PyConfig_Get("write_bytecode")}。

@item 
@ref{40c,,Py_NoUserSiteDirectory}：請改用 @ref{40d,,PyConfig.user_site_directory} 或 @ref{37a,,PyConfig_Get("user_site_directory")}。

@item 
@ref{40e,,Py_UnbufferedStdioFlag}：請改用 @ref{40f,,PyConfig.buffered_stdio} 或 @ref{37a,,PyConfig_Get("buffered_stdio")}。

@item 
@ref{410,,Py_HashRandomizationFlag}：請改用 @ref{411,,PyConfig.use_hash_seed} 和 @ref{412,,PyConfig.hash_seed} 或 @ref{37a,,PyConfig_Get("hash_seed")}。

@item 
@ref{413,,Py_IsolatedFlag}：請改用 @ref{414,,PyConfig.isolated} 或 @ref{37a,,PyConfig_Get("isolated")}。

@item 
@ref{415,,Py_LegacyWindowsFSEncodingFlag}：請改用 @ref{416,,PyPreConfig.legacy_windows_fs_encoding} 或 @ref{37a,,PyConfig_Get("legacy_windows_fs_encoding")}。

@item 
@ref{417,,Py_LegacyWindowsStdioFlag}：請改用 @ref{418,,PyConfig.legacy_windows_stdio} 或 @ref{37a,,PyConfig_Get("legacy_windows_stdio")}。

@item 
@code{Py_FileSystemDefaultEncoding}、@code{Py_HasFileSystemDefaultEncoding}：請改用 @ref{419,,PyConfig.filesystem_encoding} 或 @ref{37a,,PyConfig_Get("filesystem_encoding")}。

@item 
@code{Py_FileSystemDefaultEncodeErrors}：請改用 @ref{41a,,PyConfig.filesystem_errors} 或 @ref{37a,,PyConfig_Get("filesystem_errors")}。

@item 
@code{Py_UTF8Mode}：請改用 @ref{41b,,PyPreConfig.utf8_mode} 或 @ref{37a,,PyConfig_Get("utf8_mode")}。（請參閱 @ref{41c,,Py_PreInitialize()}）
@end itemize

應改用帶有 @ref{3f4,,PyConfig} 的 @ref{3f5,,Py_InitializeFromConfig()} API 來設定這些選項。或者也可以使用 @ref{37a,,PyConfig_Get()} 在執行時取得這些選項。
@end itemize

@node Python 3 16 中待移除的項目<2>,Python 3 18 中待移除的項目,Python 3 15 中待移除的項目<2>,已棄用的 C API
@anchor{whatsnew/3 14 id14}@anchor{41d}
@subsubsection Python 3.16 中待移除的項目



@itemize *

@item 
@code{libmpdecimal} 的打包副本 (bundled copy)。
@end itemize

@node Python 3 18 中待移除的項目,未來版本中的待移除項目<2>,Python 3 16 中待移除的項目<2>,已棄用的 C API
@anchor{whatsnew/3 14 pending-removal-in-python-3-18}@anchor{41e}
@subsubsection Python 3.18 中待移除的項目



@itemize *

@item 
以下私有函式已被棄用，並計劃在 Python 3.18 中移除：


@itemize *

@item 
@code{_PyBytes_Join()}：請改用 @ref{381,,PyBytes_Join()}。

@item 
@code{_PyDict_GetItemStringWithError()}：請改用 @ref{41f,,PyDict_GetItemStringRef()}。

@item 
@code{_PyDict_Pop()}：請改用 @ref{420,,PyDict_Pop()}。

@item 
@code{_PyLong_Sign()}：請改用 @ref{398,,PyLong_GetSign()}。

@item 
@code{_PyLong_FromDigits()} 和 @code{_PyLong_New()}：請改用 @ref{3a8,,PyLongWriter_Create()}。

@item 
@code{_PyThreadState_UncheckedGet()}：請改用 @ref{421,,PyThreadState_GetUnchecked()}。

@item 
@code{_PyUnicode_AsString()}：請改用 @ref{422,,PyUnicode_AsUTF8()}。

@item 
@code{_PyUnicodeWriter_Init()}：將 @code{_PyUnicodeWriter_Init(&writer)} 替換為 @ref{3b2,,writer = PyUnicodeWriter_Create(0)}。

@item 
@code{_PyUnicodeWriter_Finish()}：將 @code{_PyUnicodeWriter_Finish(&writer)} 替換為 @ref{3b5,,PyUnicodeWriter_Finish(writer)}。

@item 
@code{_PyUnicodeWriter_Dealloc()}：將 @code{_PyUnicodeWriter_Dealloc(&writer)} 替換為 @ref{3b4,,PyUnicodeWriter_Discard(writer)}。

@item 
@code{_PyUnicodeWriter_WriteChar()}：將 @code{_PyUnicodeWriter_WriteChar(&writer, ch)} 替換為 @ref{3b8,,PyUnicodeWriter_WriteChar(writer@comma{} ch)}。

@item 
@code{_PyUnicodeWriter_WriteStr()}：將 @code{_PyUnicodeWriter_WriteStr(&writer, str)} 替換為 @ref{3ba,,PyUnicodeWriter_WriteStr(writer@comma{} str)}。

@item 
@code{_PyUnicodeWriter_WriteSubstring()}：將 @code{_PyUnicodeWriter_WriteSubstring(&writer, str, start, end)} 替換為 @ref{3bb,,PyUnicodeWriter_WriteSubstring(writer@comma{} str@comma{} start@comma{} end)}。

@item 
@code{_PyUnicodeWriter_WriteASCIIString()}：將 @code{_PyUnicodeWriter_WriteASCIIString(&writer, str)} 替換為 @ref{3b7,,PyUnicodeWriter_WriteASCII(writer@comma{} str)}。

@item 
@code{_PyUnicodeWriter_WriteLatin1String()}：將 @code{_PyUnicodeWriter_WriteLatin1String(&writer, str)} 替換為 @ref{3bd,,PyUnicodeWriter_WriteUTF8(writer@comma{} str)}。

@item 
@code{_PyUnicodeWriter_Prepare()}：（無替代方案）。

@item 
@code{_PyUnicodeWriter_PrepareKind()}：（無替代方案）。

@item 
@code{_Py_HashPointer()}：請改用 @ref{423,,Py_HashPointer()}。

@item 
@code{_Py_fopen_obj()}：請改用 @ref{391,,Py_fopen()}。
@end itemize

可以使用 pythoncapi-compat project@footnote{https://github.com/python/pythoncapi-compat/} 來取得這些於 Python 3.13 及更早版本的新公開函式。（由 Victor Stinner 在 gh-128863@footnote{https://github.com/python/cpython/issues/128863} 貢獻）
@end itemize

@node 未來版本中的待移除項目<2>,,Python 3 18 中待移除的項目,已棄用的 C API
@anchor{whatsnew/3 14 id15}@anchor{424}
@subsubsection 未來版本中的待移除項目


下列 API 已被棄用並將會被移除，不過目前尚未訂定移除日期。


@itemize *

@item 
@ref{425,,Py_TPFLAGS_HAVE_FINALIZE}：自 Python 3.8 起不再需要

@item 
@ref{426,,PyErr_Fetch()}：請改用 @ref{427,,PyErr_GetRaisedException()}。

@item 
@ref{428,,PyErr_NormalizeException()}：請改用 @ref{427,,PyErr_GetRaisedException()}。

@item 
@ref{429,,PyErr_Restore()}：請改用 @ref{42a,,PyErr_SetRaisedException()}。

@item 
@ref{42b,,PyModule_GetFilename()}：請改用 @ref{42c,,PyModule_GetFilenameObject()}。

@item 
@ref{42d,,PyOS_AfterFork()}：請改用 @ref{42e,,PyOS_AfterFork_Child()}。

@item 
@ref{42f,,PySlice_GetIndicesEx()}：請改用 @ref{430,,PySlice_Unpack()} 和 @ref{431,,PySlice_AdjustIndices()}。

@item 
@ref{432,,PyUnicode_READY()}：自 Python 3.12 起不再需要

@item 
@code{PyErr_Display()}：請改用 @ref{433,,PyErr_DisplayException()}。

@item 
@code{_PyErr_ChainExceptions()}：請改用 @code{_PyErr_ChainExceptions1}。

@item 
@code{PyBytesObject.ob_shash} 成員：請改為呼叫 @ref{434,,PyObject_Hash()}。

@item 
執行緒局部儲存 (Thread Local Storage, TLS) API：


@itemize *

@item 
@ref{435,,PyThread_create_key()}：請改用 @ref{436,,PyThread_tss_alloc()}。

@item 
@ref{437,,PyThread_delete_key()}：請改用 @ref{438,,PyThread_tss_free()}。

@item 
@ref{439,,PyThread_set_key_value()}：請改用 @ref{43a,,PyThread_tss_set()}。

@item 
@ref{43b,,PyThread_get_key_value()}：請改用 @ref{43c,,PyThread_tss_get()}。

@item 
@ref{43d,,PyThread_delete_key_value()}：請改用 @ref{43e,,PyThread_tss_delete()}。

@item 
@ref{43f,,PyThread_ReInitTLS()}：自 Python 3.7 起不再需要。
@end itemize
@end itemize

@node 建置變更,移植至 Python 3 14,C API 變更,Python 3 14 有什麼新功能
@anchor{whatsnew/3 14 build-changes}@anchor{440}@anchor{whatsnew/3 14 whatsnew314-build-changes}@anchor{156}
@subsection 建置變更



@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{2e,,ctypes}, @ref{e7,,termios}, and @ref{5d,,fcntl}, as well as
experimental support for the new @ref{441,,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{442,,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{443,,--disable-safety} @code{configure} option to disable them,
or the @ref{444,,--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{172,,--with-tail-call-interp}
may be used to enable the experimental tail call interpreter.
See @ref{14f,,A new type of interpreter} for further details.

@item 
To disable the new remote debugging support, use the
@ref{170,,--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,,建置變更
@anchor{whatsnew/3 14 build-details-json}@anchor{445}@anchor{whatsnew/3 14 whatsnew314-build-details}@anchor{446}
@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{447,,'stdlib'} @ref{e1,,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,建置變更
@anchor{whatsnew/3 14 discontinuation-of-pgp-signatures}@anchor{448}@anchor{whatsnew/3 14 whatsnew314-no-more-pgp}@anchor{158}
@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,建置變更
@anchor{whatsnew/3 14 free-threaded-python-is-officially-supported}@anchor{449}@anchor{whatsnew/3 14 whatsnew314-free-threaded-now-supported}@anchor{157}
@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 的接受@footnote{https://discuss.python.org/t/84319/123}


@node Binary releases for the experimental just-in-time compiler,,Free-threaded Python is officially supported,建置變更
@anchor{whatsnew/3 14 binary-releases-for-the-experimental-just-in-time-compiler}@anchor{44a}@anchor{whatsnew/3 14 whatsnew314-jit-compiler}@anchor{159}
@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{44b,,PYTHON_JIT=1} as an
environment variable. Downstream source builds and redistributors can use the
@ref{44c,,--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{293,,sys._jit} namespace.
@ref{44d,,sys._jit.is_available()} can be used to determine if the current executable
supports JIT compilation, while @ref{44e,,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 移植至 Python 3 14,,建置變更,Python 3 14 有什麼新功能
@anchor{whatsnew/3 14 porting-to-python-3-14}@anchor{14b}
@subsection 移植至 Python 3.14


本節列出了前面描述的更改以及可能需要更改程式碼的其他錯誤修復。

@menu
* Python API 的變更:: 
* Changes in annotations (PEP 649 and PEP 749): Changes in annotations PEP 649 and PEP 749. 
* C API 中的改動:: 

@end menu

@node Python API 的變更,Changes in annotations PEP 649 and PEP 749,,移植至 Python 3 14
@anchor{whatsnew/3 14 changes-in-the-python-api}@anchor{44f}
@subsubsection Python API 的變更



@itemize *

@item 
On Unix platforms other than macOS, `forkserver' is now the default
@ref{1d5,,start method} for @ref{98,,multiprocessing}
and @ref{1d6,,ProcessPoolExecutor}, instead of `fork'.

See @ref{1d3,,(1)} and
@ref{249,,(2)} for details.

If you encounter @ref{450,,NameError}s or pickling errors coming out of
@ref{98,,multiprocessing} or @ref{24,,concurrent.futures}, see the
@ref{1d9,,forkserver restrictions}.

This change does not affect Windows or macOS, where @ref{1d8,,'spawn'} remains the default start method.

@item 
@ref{217,,functools.partial} is now a method descriptor.
Wrap it in @ref{451,,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{152,,garbage collector is now incremental},
which means that the behavior of @ref{1b3,,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{452,,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{2a7,,types.UnionType} is now an alias for @ref{2a8,,typing.Union},
causing changes in some behaviors.
See @ref{2a9,,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{145,,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{291,,sys.platform} no longer contains the major version number.
@end itemize

@node Changes in annotations PEP 649 and PEP 749,C API 中的改動,Python API 的變更,移植至 Python 3 14
@anchor{whatsnew/3 14 changes-in-annotations-pep-649-and-pep-749}@anchor{453}@anchor{whatsnew/3 14 whatsnew314-porting-annotations}@anchor{161}
@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{145,,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{454}
@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{455}
@subsubsection Implications for readers of @code{__annotations__}


If your code reads the @ref{456,,__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{457,,annotationlib.get_annotations()} with
the @ref{15f,,FORWARDREF} format,
as the @ref{33,,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{230,,Format} enum and
the @ref{457,,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{458}
@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{459,,annotationlib.get_annotate_from_class_namespace()} during class
construction and @ref{457,,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{45a}
@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{45b,,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 C API 中的改動,,Changes in annotations PEP 649 and PEP 749,移植至 Python 3 14
@anchor{whatsnew/3 14 changes-in-the-c-api}@anchor{45c}
@subsubsection C API 中的改動



@itemize *

@item 
@ref{45d,,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 @ref{45d,,Py_Finalize()} and is then reused after a
call to @ref{45e,,Py_Initialize()}.  Any issues arising from this behavior will
normally result in crashes during the execution of the subsequent call to
@ref{45e,,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{45f,,Unicode Exception Objects} C API
now raises a @ref{198,,TypeError} if its exception argument is not
a @ref{460,,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{2d0}

@itemize *

@item 
The interpreter internally avoids some reference count modifications when
loading objects onto the operands stack by @ref{3d5,,borrowing}
references when possible. This can lead to smaller reference count values
compared to previous Python versions. C API extensions that checked
@ref{2cf,,Py_REFCNT()} of @code{1} to determine if an function argument is not
referenced by any other code should instead use
@ref{3c5,,PyUnstable_Object_IsUniqueReferencedTemporary()} as a safer replacement.

@item 
被提升為公開 C API 的私有函式：


@itemize *

@item 
@code{_PyBytes_Join()}: @ref{381,,PyBytes_Join()}

@item 
@code{_PyLong_IsNegative()}: @ref{39a,,PyLong_IsNegative()}

@item 
@code{_PyLong_IsPositive()}: @ref{399,,PyLong_IsPositive()}

@item 
@code{_PyLong_IsZero()}: @ref{39b,,PyLong_IsZero()}

@item 
@code{_PyLong_Sign()}: @ref{398,,PyLong_GetSign()}

@item 
@code{_PyUnicodeWriter_Dealloc()}: @ref{3b4,,PyUnicodeWriter_Discard()}

@item 
@code{_PyUnicodeWriter_Finish()}: @ref{3b5,,PyUnicodeWriter_Finish()}

@item 
@code{_PyUnicodeWriter_Init()}: 使用 @ref{3b2,,PyUnicodeWriter_Create()}

@item 
@code{_PyUnicodeWriter_Prepare()}: (無替代方案)

@item 
@code{_PyUnicodeWriter_PrepareKind()}: (無替代方案)

@item 
@code{_PyUnicodeWriter_WriteChar()}: @ref{3b8,,PyUnicodeWriter_WriteChar()}

@item 
@code{_PyUnicodeWriter_WriteStr()}: @ref{3ba,,PyUnicodeWriter_WriteStr()}

@item 
@code{_PyUnicodeWriter_WriteSubstring()}: @ref{3bb,,PyUnicodeWriter_WriteSubstring()}

@item 
@code{_PyUnicode_EQ()}: @ref{3b0,,PyUnicode_Equal()}

@item 
@code{_PyUnicode_Equal()}: @ref{3b0,,PyUnicode_Equal()}

@item 
@code{_Py_GetConfig()}: @ref{37a,,PyConfig_Get()} 和 @ref{382,,PyConfig_GetInt()}

@item 
@code{_Py_HashBytes()}: @ref{393,,Py_HashBuffer()}

@item 
@code{_Py_fopen_obj()}: @ref{391,,Py_fopen()}

@item 
@code{PyMutex_IsLocked()} : @ref{461,,PyMutex_IsLocked()}
@end itemize

pythoncapi-compat project@footnote{https://github.com/python/pythoncapi-compat/} 可以用來在 Python 3.13 和更早版本中獲得這些新函式。
@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 3 13 有什麼新功能,Python 3 12 有什麼新功能,Python 3 14 有什麼新功能,Python 有什麼新功能？
@anchor{whatsnew/3 13 doc}@anchor{462}@anchor{whatsnew/3 13 translation-repo}@anchor{463}@anchor{whatsnew/3 13 what-s-new-in-python-3-13}@anchor{464}
@section Python 3.13 有什麼新功能


@*編輯者: 
Adam Turner 和 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.

本文介紹了 Python 3.13 與 3.12 相比多了哪些新功能。Python 3.13 已於 2024 年 10 月 7 日發布。完整詳情請見  @ref{142,,changelog}。


@subsubheading 也參考


@geindex Python Enhancement Proposals; PEP 719
PEP 719@footnote{https://peps.python.org/pep-0719/} -- Python 3.13 發佈時程


@menu
* 發布重點摘要:: 
* 新增功能:: 
* 其他語言更動:: 
* 新增模組:: 
* 改進的模組:: 
* 最佳化: 最佳化<2>. 
* 被移除的模組和 API:: 
* New Deprecations:: 
* CPython 位元組碼變更: CPython 位元組碼變更<2>. 
* C API 變更: C API 變更<2>. 
* 建置變更: 建置變更<2>. 
* 移植至 Python 3.13: 移植至 Python 3 13. 
* 迴歸測試的變更:: 

@end menu

@node 發布重點摘要,新增功能,,Python 3 13 有什麼新功能
@anchor{whatsnew/3 13 summary-release-highlights}@anchor{465}
@subsection 發布重點摘要


@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{466,,interactive interpreter}@anchor{whatsnew/3 13 whatsnew313-better-interactive-interpreter}@anchor{466},
experimental support for running in a @ref{467,,free-threaded mode}@anchor{whatsnew/3 13 whatsnew313-free-threaded-cpython}@anchor{467} (
@geindex Python Enhancement Proposals; PEP 703
PEP 703@footnote{https://peps.python.org/pep-0703/}),
and a @ref{468,,Just-In-Time compiler}@anchor{whatsnew/3 13 whatsnew313-jit-compiler}@anchor{468} (
@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{469,,locals()} builtin now has @ref{46a,,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{46b,,been removed}@anchor{whatsnew/3 13 whatsnew313-pep594}@anchor{46b} 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{149,,Library Reference}
and @ref{14a,,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{46c,,Porting to Python 3.13} for guidance on upgrading from
earlier versions of Python.


__________________________________________________________________


@c PEP-sized items next.

直譯器改進：


@itemize *

@item 
A greatly improved @ref{466,,interactive interpreter} and
@ref{46d,,improved error messages}.

@item 
@geindex Python Enhancement Proposals; PEP 667
PEP 667@footnote{https://peps.python.org/pep-0667/}: The @ref{469,,locals()} builtin now has
@ref{46a,,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{46e,,global interpreter lock} disabled. See @ref{467,,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{468,,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{466,,interactive interpreter},
as well as in @ref{46d,,tracebacks}
and @ref{46f,,doctest} output.
This can be disabled through the 
@geindex PYTHON_COLORS
@geindex 環境變數; PYTHON_COLORS
@ref{470,,PYTHON_COLORS} and NO_COLOR@footnote{https://no-color.org/}
environment variables.
@end itemize

Python 資料模型改進：


@itemize *

@item 
@ref{471,,__static_attributes__} stores the names of attributes accessed
through @code{self.X} in any function in a class body.

@item 
@ref{472,,__firstlineno__} records the first line number of a class
definition.
@end itemize

標準函式庫中的顯著改進


@itemize *

@item 
Add a new @ref{473,,PythonFinalizationError} exception, raised when an operation
is blocked during @ref{474,,finalization}.

@item 
The @ref{7,,argparse} module now supports deprecating command-line options,
positional arguments, and subcommands.

@item 
The new functions @ref{475,,base64.z85encode()} and @ref{476,,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{1c0,,copy.replace()} function,
with support for many builtin types and any class defining
the @ref{477,,__replace__()} method.

@item 
新的 @ref{39,,dbm.sqlite3} 模組現在是預設的 @ref{35,,dbm} 後端。

@item 
The @ref{a5,,os} module has a @ref{478,,suite of new functions}
for working with Linux's timer notification file descriptors.

@item 
現在 @ref{bd,,random} 模組有一個@ref{479,,命令列介面}。
@end itemize

安全性改進：


@itemize *

@item 
@ref{47a,,ssl.create_default_context()} sets @ref{47b,,ssl.VERIFY_X509_PARTIAL_CHAIN}
and @ref{47c,,ssl.VERIFY_X509_STRICT} as default flags.
@end itemize

C API 改進：


@itemize *

@item 
The @ref{47d,,Py_mod_gil} slot is now used to indicate that
an extension module supports running with the @ref{164,,GIL} disabled.

@item 
The @ref{47e,,PyTime C API} has been added,
providing access to system clocks.

@item 
@ref{47f,,PyMutex} is a new lightweight mutex that occupies a single byte.

@item 
There is a new @ref{480,,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

新增型別特性：


@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 696
PEP 696@footnote{https://peps.python.org/pep-0696/}: Type parameters (@ref{481,,typing.TypeVar}, @ref{482,,typing.ParamSpec},
and @ref{483,,typing.TypeVarTuple}) now support defaults.

@item 
@geindex Python Enhancement Proposals; PEP 702
PEP 702@footnote{https://peps.python.org/pep-0702/}: The new @ref{484,,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{485,,typing.ReadOnly} can be used to mark an item of a
@ref{331,,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{486,,typing.TypeIs} provides more intuitive
type narrowing behavior, as an alternative to @ref{487,,typing.TypeGuard}.
@end itemize

平台支援：


@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 730
PEP 730@footnote{https://peps.python.org/pep-0730/}: Apple's iOS is now an @ref{488,,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{488,,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} 現在作為 
@geindex Python Enhancement Proposals; PEP 11#tier-2
tier 2@footnote{https://peps.python.org/pep-0011/#tier-2} 平台支援。

@item 
@code{wasm32-emscripten} 不再是官方支援的平台。
@end itemize

重要的移除：


@itemize *

@item 
@ref{46b,,PEP 594}: 剩下的 19 個 "dead batteries" （遺留標準函式庫模組）已自標準函式庫中移除：@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} 和 @code{xdrlib}.

@item 
Remove the @code{2to3} tool and @code{lib2to3} module
(deprecated in Python 3.11).

@item 
移除 @code{tkinter.tix} 模組（在 Python 3.6 中已棄用）。

@item 
移除 @code{locale.resetlocale()} 函式。

@item 
移除 @code{typing.io} 和 @code{typing.re} 命名空間。

@item 
Remove chained @ref{489,,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 新增功能,其他語言更動,發布重點摘要,Python 3 13 有什麼新功能
@anchor{whatsnew/3 13 new-features}@anchor{48a}
@subsection 新增功能


@menu
* A better interactive interpreter:: 
* 改善錯誤訊息: 改善錯誤訊息<2>. 
* 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. 
* 對行動平台的支援:: 

@end menu

@node A better interactive interpreter,改善錯誤訊息<2>,,新增功能
@anchor{whatsnew/3 13 a-better-interactive-interpreter}@anchor{48b}
@subsubsection A better interactive interpreter


Python now uses a new @ref{1b5,,interactive} shell by default, based on code
from the PyPy project@footnote{https://pypy.org/}.
When the user starts the @ref{48c,,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{1b7,,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{48d,,>>>} and @ref{48e,,...} 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{1b6,,PYTHON_BASIC_REPL} environment variable.
For more on interactive mode, see @ref{48f,,互動模式}.

(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 改善錯誤訊息<2>,Free-threaded CPython,A better interactive interpreter,新增功能
@anchor{whatsnew/3 13 improved-error-messages}@anchor{490}@anchor{whatsnew/3 13 whatsnew313-improved-error-messages}@anchor{46d}
@subsubsection 改善錯誤訊息



@itemize *

@item 
The interpreter now uses color by default when displaying tracebacks in the
terminal. This feature @ref{1b7,,can be controlled}
via the new 
@geindex PYTHON_COLORS
@geindex 環境變數; PYTHON_COLORS
@ref{470,,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

（由 Shantanu Jain 在 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

（由 Pablo Galindo Salgado 和 Shantanu Jain 於 gh-107944@footnote{https://github.com/python/cpython/issues/107944} 中貢獻。）
@end itemize

@node Free-threaded CPython,An experimental just-in-time JIT compiler,改善錯誤訊息<2>,新增功能
@anchor{whatsnew/3 13 free-threaded-cpython}@anchor{491}
@subsubsection Free-threaded CPython


CPython now has experimental support for running in a free-threaded mode,
with the @ref{46e,,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{492,,Windows}
and @ref{493,,macOS} installers,
or CPython can be built from source with the @ref{494,,--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{495,,PYTHON_GIL} or
the command-line option @ref{16f,,-X gil=1}.

To check if the current interpreter supports free-threading, @ref{496,,python -VV}
and @ref{497,,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{164,,GIL} disabled should
use the @ref{47d,,Py_mod_gil} slot. Extensions using single-phase init should
use @ref{498,,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{495,,PYTHON_GIL} environment variable or the
@ref{16f,,-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,新增功能
@anchor{whatsnew/3 13 an-experimental-just-in-time-jit-compiler}@anchor{499}
@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{49a,,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,對行動平台的支援,An experimental just-in-time JIT compiler,新增功能
@anchor{whatsnew/3 13 defined-mutation-semantics-for-locals}@anchor{49b}@anchor{whatsnew/3 13 whatsnew313-locals-semantics}@anchor{46a}
@subsubsection Defined mutation semantics for @code{locals()}


Historically, the expected result of mutating the return value of
@ref{469,,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{49c,,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{469,,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{49d,,exec()} and @ref{49e,,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{49f,,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{4a0,,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{4a1,,Python APIs} and @ref{4a2,,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 對行動平台的支援,,Defined mutation semantics for locals,新增功能
@anchor{whatsnew/3 13 support-for-mobile-platforms}@anchor{4a3}@anchor{whatsnew/3 13 whatsnew313-platform-support}@anchor{488}
@subsubsection 對行動平台的支援


@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 其他語言更動,新增模組,新增功能,Python 3 13 有什麼新功能
@anchor{whatsnew/3 13 other-language-changes}@anchor{4a4}
@subsection 其他語言更動



@itemize *

@item 
The compiler now strips common leading whitespace
from every line in a docstring.
This reduces the size of the @ref{4a5,,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{3e,,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

（由 Inada Naoki 在 gh-81283@footnote{https://github.com/python/cpython/issues/81283} 中貢獻。）

@item 
@ref{4a6,,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

（由 Jelle Zijlstra 在 gh-109118@footnote{https://github.com/python/cpython/issues/109118} 和 gh-118160@footnote{https://github.com/python/cpython/issues/118160} 中貢獻。）

@item 
@ref{45b,,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{4a7,,global} declarations are now permitted in @ref{1ab,,except} blocks
when that global is used in the @ref{17c,,else} block.
Previously this raised an erroneous @ref{18e,,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{4a8,,PYTHON_FROZEN_MODULES}, a new environment variable that
determines whether frozen modules are ignored by the import machinery,
equivalent to the @ref{16f,,-X frozen_modules} command-line option.
(Contributed by Yilei Yang in gh-111374@footnote{https://github.com/python/cpython/issues/111374}.)

@item 
Add @ref{4a9,,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{4aa,,PYTHON_PERF_JIT_SUPPORT}
and command-line option @ref{16f,,-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{4ab,,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{471,,__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{49d,,exec()} and @ref{49e,,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{4ac,,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{4ad,,__name__} attribute on @ref{4ae,,property} objects.
(Contributed by Eugene Toder in gh-101860@footnote{https://github.com/python/cpython/issues/101860}.)

@item 
Add @ref{473,,PythonFinalizationError}, a new exception derived from
@ref{244,,RuntimeError} and used to signal when operations are blocked
during @ref{474,,finalization}.
The following callables now raise @code{PythonFinalizationError},
instead of @ref{244,,RuntimeError}:


@itemize *

@item 
@ref{4af,,_thread.start_new_thread()}

@item 
@ref{4b0,,os.fork()}

@item 
@ref{4b1,,os.forkpty()}

@item 
@ref{4b2,,subprocess.Popen}
@end itemize

（由 Victor Stinner 在 gh-114570@footnote{https://github.com/python/cpython/issues/114570} 中貢獻。）

@item 
允許 @ref{4b3,,str.replace()} 的 `count' 引數為關鍵字。（由 Hugo van Kemenade 在 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{8e,,lzma}, @ref{e4,,tarfile}, and @ref{137,,zipfile} modules.
(Contributed by Serhiy Storchaka in gh-115961@footnote{https://github.com/python/cpython/issues/115961}.)
@end itemize

@node 新增模組,改進的模組,其他語言更動,Python 3 13 有什麼新功能
@anchor{whatsnew/3 13 new-modules}@anchor{4b4}
@subsection 新增模組



@itemize *

@item 
@ref{39,,dbm.sqlite3}: An SQLite backend for @ref{35,,dbm}.
(Contributed by Raymond Hettinger and Erlend E. Aasland in gh-100414@footnote{https://github.com/python/cpython/issues/100414}.)
@end itemize

@node 改進的模組,最佳化<2>,新增模組,Python 3 13 有什麼新功能
@anchor{whatsnew/3 13 improved-modules}@anchor{4b5}
@subsection 改進的模組


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

@end menu

@node argparse<3>,array,,改進的模組
@anchor{whatsnew/3 13 argparse}@anchor{4b6}
@subsubsection argparse



@itemize *

@item 
Add the `deprecated' parameter to the
@ref{4b7,,add_argument()}
and @code{add_parser()} methods, to enable deprecating
command-line options, positional arguments, and subcommands.
(Contributed by Serhiy Storchaka in gh-83648@footnote{https://github.com/python/cpython/issues/83648}.)
@end itemize

@node array,ast<3>,argparse<3>,改進的模組
@anchor{whatsnew/3 13 array}@anchor{4b8}
@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{4b9,,array.array} as a @ref{4ba,,MutableSequence}
by implementing the @ref{4bb,,clear()} method.
(Contributed by Mike Zimin in gh-114894@footnote{https://github.com/python/cpython/issues/114894}.)
@end itemize

@node ast<3>,asyncio<4>,array,改進的模組
@anchor{whatsnew/3 13 ast}@anchor{4bc}
@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{4bd,,Load()}.
(Previously, in all cases, the attribute would be missing on the newly
constructed AST node instance.)

In all other cases, where a required argument is omitted,
the node constructor will emit a @ref{1a3,,DeprecationWarning}.
This will raise an exception in Python 3.15.
Similarly, passing a keyword argument to the constructor
that does not map to a field on the AST node is now deprecated,
and will raise an exception in Python 3.15.

These changes do not apply to user-defined subclasses of @ref{4be,,ast.AST}
unless the class opts in to the new behavior
by defining the @ref{4bf,,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{1c2,,ast.parse()} now accepts an optional argument `optimize'
which is passed on to @ref{4ac,,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<4>,base64<2>,ast<3>,改進的模組
@anchor{whatsnew/3 13 asyncio}@anchor{4c0}
@subsubsection asyncio



@itemize *

@item 
@ref{4c1,,asyncio.as_completed()} now returns an object that is both an
@ref{4c2,,asynchronous iterator} and a plain @ref{4c3,,iterator}
of @ref{4c4,,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{4c5,,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{4c6,,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{4c7,,Queue.shutdown}
and @ref{4c8,,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{4c9,,Server.close_clients()} and @ref{4ca,,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{4cb,,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{4cc,,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{4cd,,ExceptionGroup},
it will now call the parent task's @ref{4ce,,cancel()} method.
This ensures that a @ref{4cf,,CancelledError} will be raised
at the next @ref{18d,,await}, so the cancellation is not lost.

An added benefit of these changes is that task groups now preserve
the cancellation count (@ref{4d0,,cancelling()}).

In order to handle some corner cases, @ref{4d1,,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{1cb,,TaskGroup.create_task()} is called on an inactive
@ref{4cc,,TaskGroup}, the given coroutine will be closed (which
prevents a @ref{4d2,,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{1c7,,Task}
and to custom task factories.

This affects the following function and methods:
@ref{1c9,,asyncio.create_task()},
@ref{1ca,,asyncio.loop.create_task()},
@ref{1cb,,asyncio.TaskGroup.create_task()}.
(Contributed by Thomas Grainger in gh-128307@footnote{https://github.com/python/cpython/issues/128307}.)
@end itemize

@node base64<2>,compileall,asyncio<4>,改進的模組
@anchor{whatsnew/3 13 base64}@anchor{4d3}
@subsubsection base64



@itemize *

@item 
Add @ref{475,,z85encode()} and @ref{476,,z85decode()} functions
for encoding @ref{192,,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<2>,base64<2>,改進的模組
@anchor{whatsnew/3 13 compileall}@anchor{4d4}
@subsubsection compileall



@itemize *

@item 
The default number of worker threads and processes is now selected using
@ref{4d5,,os.process_cpu_count()} instead of @ref{4d6,,os.cpu_count()}.
(Contributed by Victor Stinner in gh-109649@footnote{https://github.com/python/cpython/issues/109649}.)
@end itemize

@node concurrent futures<2>,configparser<2>,compileall,改進的模組
@anchor{whatsnew/3 13 concurrent-futures}@anchor{4d7}
@subsubsection concurrent.futures



@itemize *

@item 
The default number of worker threads and processes is now selected using
@ref{4d5,,os.process_cpu_count()} instead of @ref{4d6,,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<2>,改進的模組
@anchor{whatsnew/3 13 configparser}@anchor{4d8}
@subsubsection configparser



@itemize *

@item 
@ref{4d9,,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<2>,configparser<2>,改進的模組
@anchor{whatsnew/3 13 copy}@anchor{4da}
@subsubsection copy



@itemize *

@item 
The new @ref{1c0,,replace()} function and the @ref{477,,replace protocol} make creating modified copies of objects much simpler.
This is especially useful when working with immutable objects.
The following types support the @ref{1c0,,replace()} function
and implement the replace protocol:


@itemize *

@item 
@ref{4db,,collections.namedtuple()}

@item 
@ref{4dc,,dataclasses.dataclass}

@item 
@ref{4dd,,datetime.datetime}、@ref{1fa,,datetime.date}、@ref{1fb,,datetime.time}

@item 
@ref{4de,,inspect.Signature}、@ref{4df,,inspect.Parameter}

@item 
@ref{4e0,,types.SimpleNamespace}

@item 
@ref{4e1,,程式碼物件}
@end itemize

Any user-defined class can also support @ref{1c0,,copy.replace()} by defining
the @ref{477,,__replace__()} method.
(Contributed by Serhiy Storchaka in gh-108751@footnote{https://github.com/python/cpython/issues/108751}.)
@end itemize

@node ctypes<2>,dbm,copy,改進的模組
@anchor{whatsnew/3 13 ctypes}@anchor{4e2}
@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{1e5,,ctypes.Structure} objects have a new @ref{4e3,,_align_}
attribute which allows the alignment of the structure being packed to/from
memory to be specified explicitly.
(Contributed by Matt Sanderson in gh-112433@footnote{https://github.com/python/cpython/issues/112433})
@end itemize

@node dbm,dis<2>,ctypes<2>,改進的模組
@anchor{whatsnew/3 13 dbm}@anchor{4e4}
@subsubsection dbm



@itemize *

@item 
Add @ref{39,,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,改進的模組
@anchor{whatsnew/3 13 dis}@anchor{4e5}
@subsubsection dis



@itemize *

@item 
Change the output of @ref{3c,,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{4e6,,-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{4e7,,get_instructions()} no longer represents cache entries
as separate instructions.
Instead, it returns them as part of the @ref{203,,Instruction},
in the new `cache_info' field.
The `show_caches' argument to @ref{4e7,,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<2>,dis<2>,改進的模組
@anchor{whatsnew/3 13 doctest}@anchor{4e8}@anchor{whatsnew/3 13 whatsnew313-doctest}@anchor{46f}
@subsubsection doctest



@itemize *

@item 
@ref{3e,,doctest} output is now colored by default.
This can be controlled via the new 
@geindex PYTHON_COLORS
@geindex 環境變數; PYTHON_COLORS
@ref{470,,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{1b7,,Controlling color}.
(Contributed by Hugo van Kemenade in gh-117225@footnote{https://github.com/python/cpython/issues/117225}.)

@item 
The @ref{4e9,,DocTestRunner.run()} method now counts the number of skipped tests.
Add the @ref{4ea,,DocTestRunner.skips} and @ref{4eb,,TestResults.skipped} attributes.
(Contributed by Victor Stinner in gh-108794@footnote{https://github.com/python/cpython/issues/108794}.)
@end itemize

@node email<2>,enum,doctest,改進的模組
@anchor{whatsnew/3 13 email}@anchor{4ec}
@subsubsection email



@itemize *

@item 
Headers with embedded newlines are now quoted on output.
The @ref{44,,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{4ed,,verify_generated_headers}.
(Contributed by Bas Bloemsaat and Petr Viktorin in gh-121650@footnote{https://github.com/python/cpython/issues/121650}.)

@item 
@ref{4ee,,getaddresses()} and @ref{4ef,,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<2>,改進的模組
@anchor{whatsnew/3 13 enum}@anchor{4f0}
@subsubsection enum



@itemize *

@item 
公開 @ref{4f1,,EnumDict} 以更好地支援 @ref{4f2,,EnumType} 的子類別。
@end itemize

@node fractions<2>,glob,enum,改進的模組
@anchor{whatsnew/3 13 fractions}@anchor{4f3}
@subsubsection fractions



@itemize *

@item 
@ref{213,,Fraction} objects now support the standard
@ref{4f4,,format specification mini-language} rules
for fill, alignment, sign handling, minimum width, and grouping.
(Contributed by Mark Dickinson in gh-111320@footnote{https://github.com/python/cpython/issues/111320}.)
@end itemize

@node glob,importlib,fractions<2>,改進的模組
@anchor{whatsnew/3 13 glob}@anchor{4f5}
@subsubsection glob



@itemize *

@item 
Add @ref{4f6,,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,改進的模組
@anchor{whatsnew/3 13 importlib}@anchor{4f7}
@subsubsection importlib



@itemize *

@item 
The following functions in @ref{7f,,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{4f8,,is_resource()}

@item 
@ref{4f9,,open_binary()}

@item 
@ref{4fa,,open_text()}

@item 
@ref{4fb,,path()}

@item 
@ref{4fc,,read_binary()}

@item 
@ref{4fd,,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{4fe,,contents()} remains deprecated in favor of
the fully-featured @ref{2f9,,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,改進的模組
@anchor{whatsnew/3 13 io}@anchor{4ff}
@subsubsection io



@itemize *

@item 
The @ref{500,,IOBase} finalizer now logs any errors raised by
the @ref{501,,close()} method with @ref{502,,sys.unraisablehook}.
Previously, errors were ignored silently by default,
and only logged in @ref{503,,Python Development Mode}
or when using a @ref{504,,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>,改進的模組
@anchor{whatsnew/3 13 ipaddress}@anchor{505}
@subsubsection ipaddress



@itemize *

@item 
Add the @ref{506,,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{507,,IPv4Address}, @ref{508,,IPv6Address},
@ref{509,,IPv4Network}, and @ref{50a,,IPv6Network}.
(Contributed by Jakub Stasiak in gh-113171@footnote{https://github.com/python/cpython/issues/113171}.)
@end itemize

@node itertools<2>,marshal,ipaddress,改進的模組
@anchor{whatsnew/3 13 itertools}@anchor{50b}
@subsubsection itertools



@itemize *

@item 
@ref{50c,,batched()} has a new `strict' parameter,
which raises a @ref{2eb,,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<2>,itertools<2>,改進的模組
@anchor{whatsnew/3 13 marshal}@anchor{50d}
@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<2>,mimetypes<2>,marshal,改進的模組
@anchor{whatsnew/3 13 math}@anchor{50e}
@subsubsection math



@itemize *

@item 
The new function @ref{50f,,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<2>,mmap,math<2>,改進的模組
@anchor{whatsnew/3 13 mimetypes}@anchor{510}
@subsubsection mimetypes



@itemize *

@item 
Add the @ref{511,,guess_file_type()} function to guess a MIME type
from a filesystem path.
Using paths with @ref{512,,guess_type()} is now @ref{23d,,soft deprecated}.
(Contributed by Serhiy Storchaka in gh-66543@footnote{https://github.com/python/cpython/issues/66543}.)
@end itemize

@node mmap,multiprocessing<2>,mimetypes<2>,改進的模組
@anchor{whatsnew/3 13 mmap}@anchor{513}
@subsubsection mmap



@itemize *

@item 
@ref{514,,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{514,,mmap} has a new @ref{515,,seekable()} method
that can be used when a seekable file-like object is required.
The @ref{516,,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{514,,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<2>,mmap,改進的模組
@anchor{whatsnew/3 13 multiprocessing}@anchor{517}
@subsubsection multiprocessing



@itemize *

@item 
The default number of worker threads and processes is now selected using
@ref{4d5,,os.process_cpu_count()} instead of @ref{4d6,,os.cpu_count()}.
(Contributed by Victor Stinner in gh-109649@footnote{https://github.com/python/cpython/issues/109649}.)
@end itemize

@node os<2>,os path<2>,multiprocessing<2>,改進的模組
@anchor{whatsnew/3 13 os}@anchor{518}
@subsubsection os



@itemize *

@item 
Add @ref{4d5,,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{4d6,,cpu_count()} and @ref{4d5,,process_cpu_count()} can be overridden
through the new environment variable 
@geindex PYTHON_CPU_COUNT
@geindex 環境變數; PYTHON_CPU_COUNT
@ref{519,,PYTHON_CPU_COUNT}
or the new command-line option @ref{16f,,-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{478,,low level interface} to Linux's
@code{timer file descriptors@footnote{https://manpages.debian.org/timerfd_create(2)}}
via @ref{51a,,timerfd_create()},
@ref{51b,,timerfd_settime()}, @ref{51c,,timerfd_settime_ns()},
@ref{51d,,timerfd_gettime()}, @ref{51e,,timerfd_gettime_ns()},
@ref{51f,,TFD_NONBLOCK}, @ref{520,,TFD_CLOEXEC},
@ref{521,,TFD_TIMER_ABSTIME}, and @ref{522,,TFD_TIMER_CANCEL_ON_SET}
(Contributed by Masaru Tsuchiyama in gh-108277@footnote{https://github.com/python/cpython/issues/108277}.)

@item 
@ref{523,,lchmod()} and the `follow_symlinks' argument of @ref{524,,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{525,,fchmod()} and support for file descriptors in @ref{524,,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{526,,mkdir()} and @ref{527,,makedirs()} now support passing
a `mode' value of @code{0o700} to apply access control to the new directory.
This implicitly affects @ref{528,,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{529,,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{529,,posix_spawn()} can now use the @ref{52a,,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<2>,pathlib<4>,os<2>,改進的模組
@anchor{whatsnew/3 13 os-path}@anchor{52b}
@subsubsection os.path



@itemize *

@item 
Add @ref{32a,,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{52c,,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{262,,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<4>,pdb<3>,os path<2>,改進的模組
@anchor{whatsnew/3 13 pathlib}@anchor{52d}
@subsubsection pathlib



@itemize *

@item 
Add @ref{52e,,UnsupportedOperation}, which is raised instead of
@ref{369,,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{266,,Path} objects
from 'file' URIs (@code{file:///}), @ref{52f,,Path.from_uri()}.
(Contributed by Barney Gale in gh-107465@footnote{https://github.com/python/cpython/issues/107465}.)

@item 
Add @ref{530,,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{531,,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{532,,Path.glob()} and @ref{533,,rglob()}.
(Contributed by Barney Gale in gh-77609@footnote{https://github.com/python/cpython/issues/77609}.)

@item 
@ref{532,,Path.glob()} and @ref{533,,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{534,,Path.is_file},
@ref{535,,Path.is_dir},
@ref{536,,Path.owner()}, and @ref{537,,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<3>,queue,pathlib<4>,改進的模組
@anchor{whatsnew/3 13 pdb}@anchor{538}
@subsubsection pdb



@itemize *

@item 
@ref{271,,breakpoint()} and @ref{272,,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{539,,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{136,,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{53a,,pm()} using
the new @ref{53b,,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<3>,改進的模組
@anchor{whatsnew/3 13 queue}@anchor{53c}
@subsubsection queue



@itemize *

@item 
Add @ref{53d,,Queue.shutdown} and @ref{53e,,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<2>,queue,改進的模組
@anchor{whatsnew/3 13 random}@anchor{53f}
@subsubsection random



@itemize *

@item 
Add a @ref{479,,command-line interface}.
(Contributed by Hugo van Kemenade in gh-118131@footnote{https://github.com/python/cpython/issues/118131}.)
@end itemize

@node re<2>,shutil,random,改進的模組
@anchor{whatsnew/3 13 re}@anchor{540}
@subsubsection re



@itemize *

@item 
Rename @code{re.error} to @ref{541,,PatternError} for improved clarity.
@code{re.error} is kept for backward compatibility.
@end itemize

@node shutil,site,re<2>,改進的模組
@anchor{whatsnew/3 13 shutil}@anchor{542}
@subsubsection shutil



@itemize *

@item 
Support the `dir_fd' and `follow_symlinks' keyword arguments
in @ref{543,,chown()}.
(Contributed by Berker Peksag and Tahia K in gh-62308@footnote{https://github.com/python/cpython/issues/62308})
@end itemize

@node site,sqlite3<2>,shutil,改進的模組
@anchor{whatsnew/3 13 site}@anchor{544}
@subsubsection site



@itemize *

@item 
@code{.pth} files are now decoded using UTF-8 first,
and then with the @ref{545,,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<2>,ssl<2>,site,改進的模組
@anchor{whatsnew/3 13 sqlite3}@anchor{546}
@subsubsection sqlite3



@itemize *

@item 
A @ref{547,,ResourceWarning} is now emitted if a @ref{548,,Connection}
object is not @ref{549,,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{54a,,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<2>,statistics,sqlite3<2>,改進的模組
@anchor{whatsnew/3 13 ssl}@anchor{54b}
@subsubsection ssl



@itemize *

@item 
The @ref{47a,,create_default_context()} API now includes
@ref{47b,,VERIFY_X509_PARTIAL_CHAIN} and @ref{47c,,VERIFY_X509_STRICT}
in its default flags.

@cartouche
@quotation 備註 
@ref{47c,,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

（由 William Woodruff 在 gh-112389@footnote{https://github.com/python/cpython/issues/112389} 中貢獻。）
@end itemize

@node statistics,subprocess,ssl<2>,改進的模組
@anchor{whatsnew/3 13 statistics}@anchor{54c}
@subsubsection statistics



@itemize *

@item 
Add @ref{54d,,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{54e,,kde_random()} for sampling from an
estimated probability density function created by @ref{54d,,kde()}.
(Contributed by Raymond Hettinger in gh-115863@footnote{https://github.com/python/cpython/issues/115863}.)
@end itemize

@node subprocess,sys<2>,statistics,改進的模組
@anchor{whatsnew/3 13 subprocess}@anchor{54f}@anchor{whatsnew/3 13 whatsnew313-subprocess}@anchor{550}
@subsubsection subprocess



@itemize *

@item 
The @ref{dc,,subprocess} module now uses the @ref{529,,posix_spawn()} function in
more situations.

Notably, when `close_fds' is @code{True} (the default),
@ref{529,,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{dc,,subprocess}
to never use @ref{529,,posix_spawn()}.
Please report your reason and platform details in
the @ref{551,,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<2>,tempfile,subprocess,改進的模組
@anchor{whatsnew/3 13 sys}@anchor{552}
@subsubsection sys



@itemize *

@item 
Add the @ref{553,,_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<2>,改進的模組
@anchor{whatsnew/3 13 tempfile}@anchor{554}
@subsubsection tempfile



@itemize *

@item 
On Windows, the default mode @code{0o700} used by @ref{528,,tempfile.mkdtemp()} now
limits access to the new directory due to changes to @ref{526,,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<2>,tempfile,改進的模組
@anchor{whatsnew/3 13 time}@anchor{555}
@subsubsection time



@itemize *

@item 
On Windows, @ref{556,,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{557,,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<2>,traceback,time,改進的模組
@anchor{whatsnew/3 13 tkinter}@anchor{558}
@subsubsection tkinter



@itemize *

@item 
Add @ref{f6,,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{f6,,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{183,,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{19b,,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{559,,element_create()} method of
@ref{55a,,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<2>,tkinter<2>,改進的模組
@anchor{whatsnew/3 13 traceback}@anchor{55b}
@subsubsection traceback



@itemize *

@item 
Add the @ref{55c,,exc_type_str} attribute
to @ref{55d,,TracebackException},
which holds a string display of the `exc_type'.
Deprecate the @ref{55e,,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{55f,,TracebackException.format_exception_only()} to (recursively) format
the nested exceptions of a @ref{560,,BaseExceptionGroup} instance.
(Contributed by Irit Katriel in gh-105292@footnote{https://github.com/python/cpython/issues/105292}.)
@end itemize

@node types<2>,typing<2>,traceback,改進的模組
@anchor{whatsnew/3 13 types}@anchor{561}
@subsubsection types



@itemize *

@item 
@ref{4e0,,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<2>,unicodedata<2>,types<2>,改進的模組
@anchor{whatsnew/3 13 typing}@anchor{562}
@subsubsection typing



@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 705
PEP 705@footnote{https://peps.python.org/pep-0705/}: Add @ref{485,,ReadOnly}, a special typing construct
to mark a @ref{331,,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{486,,TypeIs}, a typing construct
that can be used to instruct a type checker how to narrow a type.

@item 
Add @ref{563,,NoDefault}, a sentinel object used to represent
the defaults of some parameters in the @ref{10a,,typing} module.
(Contributed by Jelle Zijlstra in gh-116126@footnote{https://github.com/python/cpython/issues/116126}.)

@item 
Add @ref{564,,get_protocol_members()} to return the set of members
defining a @ref{565,,typing.Protocol}.
(Contributed by Jelle Zijlstra in gh-104873@footnote{https://github.com/python/cpython/issues/104873}.)

@item 
Add @ref{566,,is_protocol()} to check whether a class
is a @ref{565,,Protocol}.
(Contributed by Jelle Zijlstra in gh-104873@footnote{https://github.com/python/cpython/issues/104873}.)

@item 
@ref{567,,ClassVar} can now be nested in @ref{568,,Final},
and vice versa.
(Contributed by Mehdi Drissi in gh-89547@footnote{https://github.com/python/cpython/issues/89547}.)
@end itemize

@node unicodedata<2>,venv,typing<2>,改進的模組
@anchor{whatsnew/3 13 unicodedata}@anchor{569}
@subsubsection unicodedata



@itemize *

@item 
Update the Unicode database to version 15.1.0@footnote{https://www.unicode.org/versions/Unicode15.1.0/}.
(Contributed by James Gerity in gh-109559@footnote{https://github.com/python/cpython/issues/109559}.)
@end itemize

@node venv,warnings,unicodedata<2>,改進的模組
@anchor{whatsnew/3 13 venv}@anchor{56a}
@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{56b,,EnvBuilder} and @ref{56c,,create()}),
and opt-out via the CLI, using @code{--without-scm-ignore-files}.
(Contributed by Brett Cannon in gh-108125@footnote{https://github.com/python/cpython/issues/108125}.)
@end itemize

@node warnings,xml,venv,改進的模組
@anchor{whatsnew/3 13 warnings}@anchor{56d}
@subsubsection warnings



@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 702
PEP 702@footnote{https://peps.python.org/pep-0702/}: The new @ref{484,,warnings.deprecated()} decorator provides a way to
communicate deprecations to a @ref{56e,,static type checker}
and to warn on usage of deprecated classes and functions.
A @ref{1a3,,DeprecationWarning} may also be emitted when
a decorated function or class is used at runtime.
(Contributed by Jelle Zijlstra in gh-104003@footnote{https://github.com/python/cpython/issues/104003}.)
@end itemize

@node xml,zipimport,warnings,改進的模組
@anchor{whatsnew/3 13 xml}@anchor{56f}
@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{570,,xml.etree.ElementTree.XMLParser.flush()}

@item 
@ref{571,,xml.etree.ElementTree.XMLPullParser.flush()}

@item 
@ref{572,,xml.parsers.expat.xmlparser.GetReparseDeferralEnabled()}

@item 
@ref{573,,xml.parsers.expat.xmlparser.SetReparseDeferralEnabled()}

@item 
@code{xml.sax.expatreader.ExpatParser.flush()}
@end itemize

（由 Sebastian Pipping 在 gh-115623@footnote{https://github.com/python/cpython/issues/115623} 中貢獻。）

@item 
Add the @code{close()} method for the iterator returned by
@ref{574,,iterparse()} for explicit cleanup.
(Contributed by Serhiy Storchaka in gh-69893@footnote{https://github.com/python/cpython/issues/69893}.)
@end itemize

@node zipimport,,xml,改進的模組
@anchor{whatsnew/3 13 zipimport}@anchor{575}
@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 最佳化<2>,被移除的模組和 API,改進的模組,Python 3 13 有什麼新功能
@anchor{whatsnew/3 13 optimizations}@anchor{576}
@subsection 最佳化



@itemize *

@item 
Several standard library modules have had
their import times significantly improved.
For example, the import time of the @ref{10a,,typing} module
has been reduced by around a third by removing dependencies
on @ref{be,,re} and @ref{27,,contextlib}.
Other modules to enjoy import-time speedups include
@ref{54,,email.utils}, @ref{5a,,enum}, @ref{63,,functools},
@ref{7e,,importlib.metadata}, and @ref{f3,,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{577,,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{dc,,subprocess} module now uses the @ref{529,,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{550,,subprocess} section above for details.
(Contributed by Jakub Kulik in gh-113117@footnote{https://github.com/python/cpython/issues/113117}.)
@end itemize

@node 被移除的模組和 API,New Deprecations,最佳化<2>,Python 3 13 有什麼新功能
@anchor{whatsnew/3 13 removed-modules-and-apis}@anchor{578}
@subsection 被移除的模組和 API


@menu
* PEP 594：從標準函式庫中移除「用完的電池」:: 
* 2to3:: 
* builtins:: 
* configparser: configparser<3>. 
* importlib.metadata: importlib metadata. 
* locale:: 
* opcode:: 
* optparse:: 
* pathlib: pathlib<5>. 
* re: re<3>. 
* tkinter.tix: tkinter tix. 
* turtle: turtle<2>. 
* typing: typing<3>. 
* unittest: unittest<2>. 
* urllib: urllib<3>. 
* webbrowser: webbrowser<2>. 

@end menu

@node PEP 594：從標準函式庫中移除「用完的電池」,2to3,,被移除的模組和 API
@anchor{whatsnew/3 13 pep-594-remove-dead-batteries-from-the-standard-library}@anchor{579}
@subsubsection PEP 594：從標準函式庫中移除「用完的電池」


@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/} 提議從標準函式庫中移除因為歷史、過時或不安全狀態而被稱為「用完的電池 (dead batteries)」的 19 個模組。以下所有模組在 Python 3.11 中已被棄用，現在已被移除：


@itemize *

@item 
@code{aifc}


@itemize *

@item 
standard-aifc@footnote{https://pypi.org/project/standard-aifc/}：PyPI 上的 @code{aifc} 函式庫重新發布版。
@end itemize

@item 
@code{audioop}


@itemize *

@item 
audioop-lts@footnote{https://pypi.org/project/audioop-lts/}：PyPI 上的 @code{audioop-lts} 函式庫。
@end itemize

@item 
@code{chunk}


@itemize *

@item 
standard-chunk@footnote{https://pypi.org/project/standard-chunk/}：PyPI 上的 @code{chunk} 函式庫重新發布版。
@end itemize

@item 
@code{cgi} 和 @code{cgitb}


@itemize *

@item 
@code{cgi.FieldStorage}，在於 @code{GET} 和 @code{HEAD} 請求中通常可以被 @ref{31d,,urllib.parse.parse_qsl()} 取代，而在於 @code{POST} 和 @code{PUT} 請求中可以被 @ref{48,,email.message} 模組或 multipart@footnote{https://pypi.org/project/multipart/} 函式庫取代。

@item 
@code{cgi.parse()} 能夠以在所需的查詢字串上直接呼叫 @ref{31e,,urllib.parse.parse_qs()} 來取代，除非輸入為 @code{multipart/form-data}，而這種情況則應該如下所述地將 @code{cgi.parse_multipart()} 給替換掉。

@item 
@code{cgi.parse_header()} can be replaced with the functionality
in the @ref{3f,,email} package, which implements the same MIME RFCs.
For example, with @ref{57a,,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()} 可以被 @ref{3f,,email} 函式庫中實作相同 MIME RFCs 的功能取代，或者可以被 multipart@footnote{https://pypi.org/project/multipart/} 函式庫取代，例如 @ref{57a,,email.message.EmailMessage} 和 @ref{57b,,email.message.Message} 類別。

@item 
standard-cgi@footnote{https://pypi.org/project/standard-cgi/} 和 standard-cgitb@footnote{https://pypi.org/project/standard-cgitb/}：PyPI 上的 @code{cgi} 和 @code{cgitb} 函式庫重新發布版。
@end itemize

@item 
@code{crypt} and the private @code{_crypt} extension.
The @ref{6c,,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/}：適用於你的軟體與伺服器的現代密碼雜湊演算法。

@item 
argon2-cffi@footnote{https://pypi.org/project/argon2-cffi/}：安全的 Argon2 密碼雜湊演算法。

@item 
legacycrypt@footnote{https://pypi.org/project/legacycrypt/}：對 POSIX crypt 函式庫呼叫及相關功能的 @ref{2e,,ctypes} 包裝。

@item 
crypt_r@footnote{https://pypi.org/project/crypt_r/}：對 @code{crypt} 模組的分支 (fork)，對 @code{crypt_r(3)@footnote{https://manpages.debian.org/crypt_r(3)}} 函式庫呼叫及相關功能的包裝。

@item 
standard-crypt@footnote{https://pypi.org/project/standard-crypt/} 和 deprecated-crypt-alternative@footnote{https://pypi.org/project/deprecated-crypt-alternative/}：PyPI 上的 @code{crypt} 函式庫重新發布版和 @code{_crypt} 函式庫的重新實作。
@end itemize

@item 
@code{imghdr}：請改用 filetype@footnote{https://pypi.org/project/filetype/}、puremagic@footnote{https://pypi.org/project/puremagic/} 或 python-magic@footnote{https://pypi.org/project/python-magic/} 函式庫。例如 @code{puremagic.what()} 函式可以取代 @code{imghdr} 過去所支援所有文件格式的 @code{imghdr.what()} 函式。


@itemize *

@item 
standard-imghdr@footnote{https://pypi.org/project/standard-imghdr/}：PyPI 上的 @code{imghdr} 函式庫重新發布版。
@end itemize

@item 
@code{mailcap}：請改用 @ref{93,,mimetypes} 模組。


@itemize *

@item 
standard-mailcap@footnote{https://pypi.org/project/standard-mailcap/}：PyPI 上的 @code{mailcap} 函式庫重新發布版。
@end itemize

@item 
@code{msilib}

@item 
@code{nis}

@item 
@code{nntplib}：請改用 PyPI 上的 pynntp@footnote{https://pypi.org/project/pynntp/} 函式庫。


@itemize *

@item 
standard-nntplib@footnote{https://pypi.org/project/standard-nntplib/}：PyPI 上的 @code{nntplib} 函式庫重新發布版。
@end itemize

@item 
@code{ossaudiodev}：音訊播放方面，請改用 PyPI 上的 pygame@footnote{https://pypi.org/project/pygame/} 函式庫。

@item 
@code{pipes}：請改用 @ref{dc,,subprocess} 模組。使用 @ref{57c,,shlex.quote()} 來取代未以文件紀錄的 @code{pipes.quote} 函式。


@itemize *

@item 
standard-pipes@footnote{https://pypi.org/project/standard-pipes/}：PyPI 上的 @code{pipes} 函式庫重新發布版。
@end itemize

@item 
@code{sndhdr}：請改用 filetype@footnote{https://pypi.org/project/filetype/}、puremagic@footnote{https://pypi.org/project/puremagic/} 或 python-magic@footnote{https://pypi.org/project/python-magic/} 函式庫。


@itemize *

@item 
standard-sndhdr@footnote{https://pypi.org/project/standard-sndhdr/}：PyPI 上的 @code{sndhdr} 函式庫重新發布版。
@end itemize

@item 
@code{spwd}：請改用 PyPI 上的 python-pam@footnote{https://pypi.org/project/python-pam/} 函式庫。

@item 
@code{sunau}


@itemize *

@item 
standard-sunau@footnote{https://pypi.org/project/standard-sunau/}：PyPI 上的 @code{sunau} 函式庫重新發布版。
@end itemize

@item 
@code{telnetlib}：請改用 PyPI 上的 telnetlib3@footnote{https://pypi.org/project/telnetlib3/} 或 Exscript@footnote{https://pypi.org/project/Exscript/} 函式庫。


@itemize *

@item 
standard-telnetlib@footnote{https://pypi.org/project/standard-telnetlib/}：PyPI 上的 @code{telnetlib} 函式庫重新發布版。
@end itemize

@item 
@code{uu}：請改用 @ref{f,,base64} 模組來作為當代的替代方案。


@itemize *

@item 
standard-uu@footnote{https://pypi.org/project/standard-uu/}：PyPI 上的 @code{uu} 函式庫重新發布版。
@end itemize

@item 
@code{xdrlib}


@itemize *

@item 
standard-xdrlib@footnote{https://pypi.org/project/standard-xdrlib/}：PyPI 上的 @code{xdrlib} 函式庫重新發布版。
@end itemize
@end itemize

（由 Victor Stinner 和 Zachary Ware 在 gh-104773@footnote{https://github.com/python/cpython/issues/104773} 和 gh-104780@footnote{https://github.com/python/cpython/issues/104780} 中貢獻。）

@node 2to3,builtins,PEP 594：從標準函式庫中移除「用完的電池」,被移除的模組和 API
@anchor{whatsnew/3 13 to3}@anchor{57d}
@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,被移除的模組和 API
@anchor{whatsnew/3 13 builtins}@anchor{57e}
@subsubsection builtins



@itemize *

@item 
Remove support for chained @ref{489,,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{4ae,,property}.
The core design of this feature was flawed and led to several problems.
To "pass-through" a @ref{489,,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{244,,RuntimeError} when calling @ref{57f,,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,被移除的模組和 API
@anchor{whatsnew/3 13 id3}@anchor{580}
@subsubsection configparser



@itemize *

@item 
Remove the undocumented @code{LegacyInterpolation} class,
deprecated in the docstring since Python 3.2,
and at runtime since Python 3.11.
(Contributed by Hugo van Kemenade in gh-104886@footnote{https://github.com/python/cpython/issues/104886}.)
@end itemize

@node importlib metadata,locale,configparser<3>,被移除的模組和 API
@anchor{whatsnew/3 13 importlib-metadata}@anchor{581}
@subsubsection importlib.metadata



@itemize *

@item 
Remove deprecated subscript (@ref{582,,__getitem__()}) access for
@ref{583,,EntryPoint} objects.
(Contributed by Jason R. Coombs in gh-113175@footnote{https://github.com/python/cpython/issues/113175}.)
@end itemize

@node locale,opcode,importlib metadata,被移除的模組和 API
@anchor{whatsnew/3 13 locale}@anchor{584}
@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,被移除的模組和 API
@anchor{whatsnew/3 13 opcode}@anchor{585}
@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{3c,,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<5>,opcode,被移除的模組和 API
@anchor{whatsnew/3 13 optparse}@anchor{586}
@subsubsection optparse



@itemize *

@item 
This module is no longer considered @ref{23d,,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<5>,re<3>,optparse,被移除的模組和 API
@anchor{whatsnew/3 13 id4}@anchor{587}
@subsubsection pathlib



@itemize *

@item 
Remove the ability to use @ref{266,,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<3>,tkinter tix,pathlib<5>,被移除的模組和 API
@anchor{whatsnew/3 13 id5}@anchor{588}
@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<3>,被移除的模組和 API
@anchor{whatsnew/3 13 tkinter-tix}@anchor{589}
@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<3>,tkinter tix,被移除的模組和 API
@anchor{whatsnew/3 13 turtle}@anchor{58a}
@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<3>,unittest<2>,turtle<2>,被移除的模組和 API
@anchor{whatsnew/3 13 id6}@anchor{58b}
@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{10a,,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{331,,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<2>,urllib<3>,typing<3>,被移除的模組和 API
@anchor{whatsnew/3 13 unittest}@anchor{58c}
@subsubsection unittest



@itemize *

@item 
移除以下在 Python 3.11 中已被棄用的 @ref{10c,,unittest} 函式：


@itemize *

@item 
@code{unittest.findTestCases()}

@item 
@code{unittest.makeSuite()}

@item 
@code{unittest.getTestCaseNames()}
@end itemize

改用 @ref{58d,,TestLoader} 方法：


@itemize *

@item 
@ref{58e,,loadTestsFromModule()}

@item 
@ref{58f,,loadTestsFromTestCase()}

@item 
@ref{590,,getTestCaseNames()}
@end itemize

（由 Hugo van Kemenade 在 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<2>,unittest<2>,被移除的模組和 API
@anchor{whatsnew/3 13 urllib}@anchor{591}
@subsubsection urllib



@itemize *

@item 
Remove the `cafile', `capath', and `cadefault' parameters of the
@ref{306,,urllib.request.urlopen()} function, deprecated in Python 3.6.
Use the `context' parameter instead with an @ref{355,,SSLContext} instance.
The @ref{592,,ssl.SSLContext.load_cert_chain()} function
can be used to load specific certificates,
or let @ref{47a,,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<2>,,urllib<3>,被移除的模組和 API
@anchor{whatsnew/3 13 webbrowser}@anchor{593}
@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{594,,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 位元組碼變更<2>,被移除的模組和 API,Python 3 13 有什麼新功能
@anchor{whatsnew/3 13 new-deprecations}@anchor{595}
@subsection New Deprecations



@itemize *

@item 
@ref{596,,使用者定義函式}：


@itemize *

@item 
Deprecate assignment to a function's @ref{597,,__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{33c,,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{2e,,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{23d,,Soft-deprecate} the @ref{598,,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{3a,,decimal}：


@itemize *

@item 
Deprecate the non-standard and undocumented @ref{1fe,,Decimal}
format specifier @code{'N'},
which is only supported in the @code{decimal} module's C implementation.
(Contributed by Serhiy Storchaka in gh-89902@footnote{https://github.com/python/cpython/issues/89902}.)
@end itemize

@item 
@ref{3c,,dis}：


@itemize *

@item 
Deprecate the @code{HAVE_ARGUMENT} separator.
Check membership in @ref{599,,hasarg} instead.
(Contributed by Irit Katriel in gh-109319@footnote{https://github.com/python/cpython/issues/109319}.)
@end itemize

@item 
@ref{67,,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{68,,glob}：


@itemize *

@item 
Deprecate the undocumented @code{glob0()} and @code{glob1()} functions.
Use @ref{59a,,glob()} and pass a @ref{59b,,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{76,,http.server}：


@itemize *

@item 
Deprecate @ref{324,,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{23d,,Soft-deprecate} file path arguments
to @ref{512,,guess_type()},
use @ref{511,,guess_file_type()} instead.
(Contributed by Serhiy Storchaka in gh-66543@footnote{https://github.com/python/cpython/issues/66543}.)
@end itemize

@item 
@ref{be,,re}：


@itemize *

@item 
Deprecate passing the optional `maxsplit', `count', or `flags' arguments
as positional arguments to the module-level
@ref{59c,,split()}, @ref{59d,,sub()}, and @ref{59e,,subn()} functions.
These parameters will become @ref{59f,,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 @ref{329,,PurePath.is_reserved()},
to be removed in Python 3.15.
Use @ref{32a,,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 @ref{32b,,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{ba,,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{d4,,sqlite3}：


@itemize *

@item 
Deprecate passing more than one positional argument to
the @ref{5a0,,connect()} function
and the @ref{548,,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{5a1,,Connection.create_function()}
and @ref{5a2,,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{5a3,,set_authorizer()},
@ref{5a4,,set_progress_handler()}, and
@ref{5a5,,set_trace_callback()}
@ref{548,,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{df,,sys}：


@itemize *

@item 
Deprecate the @ref{33d,,_enablelegacywindowsfsencoding()} function,
to be removed in Python 3.16.
Use the 
@geindex PYTHONLEGACYWINDOWSFSENCODING
@geindex 環境變數; PYTHONLEGACYWINDOWSFSENCODING
@ref{33e,,PYTHONLEGACYWINDOWSFSENCODING} environment variable instead.
(Contributed by Inada Naoki in gh-73427@footnote{https://github.com/python/cpython/issues/73427}.)
@end itemize

@item 
@ref{e4,,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{104,,traceback}：


@itemize *

@item 
Deprecate the @ref{55e,,TracebackException.exc_type} attribute.
Use @ref{55c,,TracebackException.exc_type_str} instead.
(Contributed by Irit Katriel in gh-112332@footnote{https://github.com/python/cpython/issues/112332}.)
@end itemize

@item 
@ref{10a,,typing}：


@itemize *

@item 
Deprecate the undocumented keyword argument syntax for creating
@ref{330,,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{330,,NamedTuple} or @ref{331,,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 
棄用 @ref{332,,typing.no_type_check_decorator()} 裝飾器函式。將在 Python 3.15 中移除。在 @ref{10a,,typing} 模組中經過八年後，它至今仍未被任何主要的型別檢查器所支援。（由 Alex Waygood 在 gh-106309@footnote{https://github.com/python/cpython/issues/106309} 中貢獻。）

@item 
Deprecate @ref{5a6,,typing.AnyStr}.
In Python 3.16, it will be removed from @code{typing.__all__},
and a @ref{1a3,,DeprecationWarning} will be emitted at runtime
when it is imported or accessed.
It will be removed entirely in Python 3.18.
Use the new @ref{5a7,,type parameter syntax} instead.
(Contributed by Michael The in gh-107116@footnote{https://github.com/python/cpython/issues/107116}.)
@end itemize

@item 
@ref{119,,wave}：


@itemize *

@item 
Deprecate the @ref{335,,getmark()}, @code{setmark()},
and @ref{336,,getmarkers()} methods of
the @ref{333,,Wave_read} and @ref{334,,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
* Python 3.14 中待移除的項目: Python 3 14 中待移除的項目. 
* Python 3.15 中待移除的項目: Python 3 15 中待移除的項目<3>. 
* Python 3.16 中待移除的項目: Python 3 16 中待移除的項目<3>. 
* Python 3.17 中待移除的項目: Python 3 17 中待移除的項目<2>. 
* 未來版本中的待移除項目: 未來版本中的待移除項目<3>. 

@end menu

@node Python 3 14 中待移除的項目,Python 3 15 中待移除的項目<3>,,New Deprecations
@anchor{whatsnew/3 13 pending-removal-in-python-3-14}@anchor{5a8}
@subsubsection Python 3.14 中待移除的項目



@itemize *

@item 
@ref{7,,argparse}：@code{argparse.BooleanOptionalAction} 的 `type'、`choices' 和 `metavar' 參數已被棄用，將在 3.14 中移除。 (由 Nikita Sobolev 於 gh-92248@footnote{https://github.com/python/cpython/issues/92248} 貢獻。)

@item 
@ref{9,,ast}：自 Python 3.8 起，下列功能已在文件中被棄用，現在在存取或使用時會於 runtime 發出 @ref{1a3,,DeprecationWarning}，並將在 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

請改用 @ref{2ee,,ast.Constant}。（由 Serhiy Storchaka 於 gh-90953@footnote{https://github.com/python/cpython/issues/90953} 貢獻。）

@item 
@ref{b,,asyncio}：


@itemize *

@item 
已棄用並將在 Python 3.14 中移除的 child watcher 類別：@code{asyncio.MultiLoopChildWatcher}、@code{asyncio.FastChildWatcher}、@code{asyncio.AbstractChildWatcher} 和 @code{asyncio.SafeChildWatcher}。 (由 Kumar Aditya 於 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()} 和 @code{asyncio.AbstractEventLoopPolicy.get_child_watcher()} 已被棄用並將在 Python 3.14 中移除。（由 Kumar Aditya 於 gh-94597@footnote{https://github.com/python/cpython/issues/94597} 貢獻。）

@item 
預設事件迴圈策略的 @ref{2f1,,get_event_loop()} 方法現在會在沒有設定目前事件迴圈且決定建立一個時發出 @ref{1a3,,DeprecationWarning}。 (由 Serhiy Storchaka 和 Guido van Rossum 於 gh-100160@footnote{https://github.com/python/cpython/issues/100160} 貢獻。)
@end itemize

@item 
@ref{3f,,email}：已棄用 @ref{2f6,,email.utils.localtime()} 中的 `isdst' 參數。（由 Alan Williams 於 gh-72346@footnote{https://github.com/python/cpython/issues/72346} 貢獻。）

@item 
@ref{7c,,importlib.abc} 的已棄用類別：


@itemize *

@item 
@code{importlib.abc.ResourceReader}

@item 
@code{importlib.abc.Traversable}

@item 
@code{importlib.abc.TraversableResources}
@end itemize

請改用 @ref{80,,importlib.resources.abc} 類別：


@itemize *

@item 
@ref{2f9,,importlib.resources.abc.Traversable}

@item 
@ref{2f8,,importlib.resources.abc.TraversableResources}
@end itemize

（由 Jason R. Coombs 和 Hugo van Kemenade 貢獻於 gh-93963@footnote{https://github.com/python/cpython/issues/93963}。）

@item 
@ref{85,,itertools} 有不以文件記錄、效率低下、過去常有 bug 且不一致的 copy、deepcopy 和 pickle 操作支援。將在 3.14 中移除以大幅減少程式碼量和維護負擔。 (由 Raymond Hettinger 於 gh-101588@footnote{https://github.com/python/cpython/issues/101588} 貢獻。)

@item 
@ref{98,,multiprocessing}：預設的啟動方法將在 Linux、BSD 和其他非 macOS POSIX 平台上更改為更安全的 方法，目前 @code{'fork'} 是預設值 (gh-84559@footnote{https://github.com/python/cpython/issues/84559})。對此增加一個 runtime 警告被認為太過擾人，因為 大多數程式碼不會在意。請使用 @ref{24a,,get_context()} 或 @ref{24b,,set_start_method()} API 來明確指定你的程式碼何時`需要' @code{'fork'}。請參閱 @ref{1d5,,Contexts and start methods}。

@item 
@ref{a8,,pathlib}：已棄用 @ref{2fd,,is_relative_to()} 和 @ref{2fc,,relative_to()}：額外引數的傳遞已被棄用。

@item 
@ref{ae,,pkgutil}：@code{pkgutil.find_loader()} 和 @code{pkgutil.get_loader()} 現在會引發 @ref{1a3,,DeprecationWarning}；請改用 @ref{5a9,,importlib.util.find_spec()}。 (由 Nikita Sobolev 於 gh-97850@footnote{https://github.com/python/cpython/issues/97850} 貢獻。)

@item 
@ref{b6,,pty}：


@itemize *

@item 
@code{master_open()}：請用 @ref{300,,pty.openpty()}。

@item 
@code{slave_open()}：請用 @ref{300,,pty.openpty()}。
@end itemize

@item 
@ref{d4,,sqlite3}：


@itemize *

@item 
@code{version} 和 @code{version_info}。

@item 
@ref{5aa,,execute()} 和 @ref{5ab,,executemany()}，如果使用 @ref{5ac,,named placeholders} 且 `parameters' 是序列而不是 @ref{183,,dict}。
@end itemize

@item 
@ref{10e,,urllib}：@code{urllib.parse.Quoter} 已被棄用：它並非預期的公開 API。(由 Gregory P. Smith 於 gh-88168@footnote{https://github.com/python/cpython/issues/88168} 貢獻。)
@end itemize

@node Python 3 15 中待移除的項目<3>,Python 3 16 中待移除的項目<3>,Python 3 14 中待移除的項目,New Deprecations
@anchor{whatsnew/3 13 pending-removal-in-python-3-15}@anchor{5ad}
@subsubsection Python 3.15 中待移除的項目



@itemize *

@item 
引入系統 (import system)：


@itemize *

@item 
在模組上設定 @ref{320,,__cached__} 而沒有設定 @ref{321,,__spec__.cached} 的做法已被棄用。在 Python 3.15 中，引入系統或標準函式庫將不再設定或考慮 @code{__cached__}。(gh-97879@footnote{https://github.com/python/cpython/issues/97879})

@item 
在模組上設定 @ref{322,,__package__} 而沒有設定 @ref{323,,__spec__.parent} 的做法已被棄用。在 Python 3.15 中，引入系統或標準函式庫將不再設定或考慮 @code{__package__}。(gh-97879@footnote{https://github.com/python/cpython/issues/97879})
@end itemize

@item 
@ref{2e,,ctypes}：


@itemize *

@item 
自 Python 3.13 起，未記錄的 @code{ctypes.SetPointerType()} 函式已被棄用。
@end itemize

@item 
@ref{76,,http.server}：


@itemize *

@item 
過時且很少使用的 @ref{324,,CGIHTTPRequestHandler} 自 Python 3.13 起已被棄用。不存在直接的替代。`任何東西'都比 CGI 更好地將 Web 伺服器與請求處理程序介接起來。

@item 
自 Python 3.13 起，@code{python -m http.server} 命令列介面的 @code{--cgi} 旗標已被棄用。
@end itemize

@item 
@ref{7b,,importlib}：


@itemize *

@item 
@code{load_module()} method：請改用 @code{exec_module()}。
@end itemize

@item 
@ref{8a,,locale}：


@itemize *

@item 
@ref{325,,getdefaultlocale()} 已在 Python 3.11 中被棄用，原本計劃在 Python 3.13 中移除 (gh-90817@footnote{https://github.com/python/cpython/issues/90817})，但被延後至 Python 3.15。請改用 @ref{326,,getlocale()}、@ref{327,,setlocale()} 和 @ref{328,,getencoding()}。 (由 Hugo van Kemenade 於 gh-111187@footnote{https://github.com/python/cpython/issues/111187} 貢獻。)
@end itemize

@item 
@ref{a8,,pathlib}：


@itemize *

@item 
@ref{329,,PurePath.is_reserved()} 已自 Python 3.13 被棄用。請用 @ref{32a,,os.path.isreserved()} 來偵測 Windows 上的保留路徑。
@end itemize

@item 
@ref{af,,platform}：


@itemize *

@item 
自 Python 3.13 起，@ref{32b,,java_ver()} 已被棄用。此函式僅對 Jython 支援有用，具有令人困惑的 API，基本上未經測試。
@end itemize

@item 
@ref{e1,,sysconfig}：


@itemize *

@item 
@ref{32c,,sysconfig.is_python_build()} 的 `check_home' 引數自 Python 3.12 起已被棄用。
@end itemize

@item 
@ref{f3,,threading}：


@itemize *

@item 
@ref{32d,,RLock()} 在 Python 3.15 中將不接受任何引數。自 Python 3.14 起，傳遞任何引數的用法已被棄用，因為 Python 版本不允許任何引數，但 C 版本允許任意數量的位置或關鍵字引數，並忽略每個引數。
@end itemize

@item 
@ref{109,,types}：


@itemize *

@item 
@ref{32e,,types.CodeType}：自 3.10 起，存取 @ref{32f,,co_lnotab} 已在 
@geindex Python Enhancement Proposals; PEP 626
PEP 626@footnote{https://peps.python.org/pep-0626/} 中被棄用，並計劃在 3.12 中移除，但只在 3.12 中於適當時發出 @ref{1a3,,DeprecationWarning}。可能在 3.15 中移除。（由 Nikita Sobolev 於 gh-101866@footnote{https://github.com/python/cpython/issues/101866} 貢獻。）
@end itemize

@item 
@ref{10a,,typing}：


@itemize *

@item 
用於建立 @ref{330,,NamedTuple} 類別的未以文件記錄之關鍵字引數語法 (@code{Point = NamedTuple("Point", x=int, y=int)}) 已自 Python 3.13 棄用。請改用基於類別的語法或函式語法 (functional syntax)。

@item 
當使用 @ref{331,,TypedDict} 的函式語法時，未傳遞值給 `fields' 參數 (@code{TD = TypedDict("TD")}) 或傳遞 @code{None} (@code{TD = TypedDict("TD", None)}) 的做法自 Python 3.13 起已被棄用。請使用 @code{class TD(TypedDict): pass} 或 @code{TD = TypedDict("TD", @{@})} 來建立具有零個欄位的 TypedDict。

@item 
自 Python 3.13 起，@ref{332,,typing.no_type_check_decorator()} 裝飾器函式已被棄用。在 @ref{10a,,typing} 模組中使用了八年之後，它尚未得到任何主要型別檢查器的支援。
@end itemize

@item 
@ref{119,,wave}：


@itemize *

@item 
已棄用 @ref{333,,Wave_read} 和 @ref{334,,Wave_write} 類別的 @ref{335,,getmark()}、@code{setmark()} 和 @ref{336,,getmarkers()} 方法自 Python 3.13 被棄用。
@end itemize

@item 
@ref{138,,zipimport}：


@itemize *

@item 
@ref{337,,load_module()} 自 Python 3.10 被棄用。請改用 @ref{338,,exec_module()}。（由 Jiahao Li 於 gh-125746@footnote{https://github.com/python/cpython/issues/125746} 貢獻。）
@end itemize
@end itemize

@node Python 3 16 中待移除的項目<3>,Python 3 17 中待移除的項目<2>,Python 3 15 中待移除的項目<3>,New Deprecations
@anchor{whatsnew/3 13 pending-removal-in-python-3-16}@anchor{5ae}
@subsubsection Python 3.16 中待移除的項目



@itemize *

@item 
引入系統 (import system)：


@itemize *

@item 
在模組上設定 @ref{33a,,__loader__} 而沒有設定 @ref{33b,,__spec__.loader} 的做法將於 Python 3.16 被棄用。在 Python 3.16 中，引入系統或標準函式庫將不再設定或考慮 @code{__loader__}。
@end itemize

@item 
@ref{8,,array}：


@itemize *

@item 
自 Python 3.3 起，@code{'u'} 格式碼 (@code{wchar_t}) 在文件中已被棄用，自 Python 3.13 起在 runtime 已被棄用。請使用 @code{'w'} 格式碼 (@ref{33c,,Py_UCS4}) 來取代 Unicode 字元。
@end itemize

@item 
@ref{b,,asyncio}：


@itemize *

@item 
@code{asyncio.iscoroutinefunction()} 已被棄用並將在 Python 3.16 中移除；請改用 @ref{30c,,inspect.iscoroutinefunction()}。（由 Jiahao Li 和 Kumar Aditya 於 gh-122875@footnote{https://github.com/python/cpython/issues/122875} 貢獻。）

@item 
@ref{b,,asyncio} 策略系統已被棄用並將在 Python 3.16 中移除。特別是以下類別和函式已被棄用：


@itemize *

@item 
@ref{30d,,asyncio.AbstractEventLoopPolicy}

@item 
@ref{30e,,asyncio.DefaultEventLoopPolicy}

@item 
@ref{30f,,asyncio.WindowsSelectorEventLoopPolicy}

@item 
@ref{310,,asyncio.WindowsProactorEventLoopPolicy}

@item 
@ref{311,,asyncio.get_event_loop_policy()}

@item 
@ref{312,,asyncio.set_event_loop_policy()}
@end itemize

使用者應該使用 @ref{2f2,,asyncio.run()} 或 @ref{2f4,,asyncio.Runner} 搭配 `loop_factory' 來使用所需的事件迴圈實作。

例如在 Windows 上使用 @ref{313,,asyncio.SelectorEventLoop}：

@example
import asyncio

async def main():
    ...

asyncio.run(main(), loop_factory=asyncio.SelectorEventLoop)
@end example

（由 Kumar Aditya 於 gh-127949@footnote{https://github.com/python/cpython/issues/127949} 貢獻。）
@end itemize

@item 
@ref{13,,builtins}：


@itemize *

@item 
自 Python 3.12 起，布林型別的位元反轉 @code{~True} 或 @code{~False} 已被棄用，因為它會產生不預期且不直觀的結果（@code{-2} 和 @code{-1}）。使用 @code{not x} 代替布林值的邏輯否定。在極少數情況下，你需要對底層的整數進行位元反轉，請明確轉換為 @code{~int(x)} (@code{~int(x)})。
@end itemize

@item 
@ref{63,,functools}：


@itemize *

@item 
自 Python 3.14 起，使用 `function' 或 `sequence' 關鍵字引數呼叫 @ref{21a,,functools.reduce()} 的 Python 實作已被棄用。
@end itemize

@item 
@ref{8b,,logging}：

對具有 `strm' 引數的自訂日誌記錄處理函式的支援已被棄用，並計劃在 Python 3.16 中移除。請改用 `stream' 引數。（由 Mariusz Felisiak 於 gh-115032@footnote{https://github.com/python/cpython/issues/115032} 貢獻。）

@item 
@ref{93,,mimetypes}：


@itemize *

@item 
有效的副檔名以 '.' 開頭或對 @ref{318,,mimetypes.MimeTypes.add_type()} 為空字串。未加點的副檔名已被棄用，並將在 Python 3.16 中引發 @ref{2eb,,ValueError}。（由 Hugo van Kemenade 於 gh-75223@footnote{https://github.com/python/cpython/issues/75223} 貢獻。）
@end itemize

@item 
@ref{ca,,shutil}：


@itemize *

@item 
自 Python 3.14 起，@code{ExecError} 例外已被棄用。自 Python 3.4 以來，它尚未被 @code{shutil} 中的任何函式使用，現在是 @ref{244,,RuntimeError} 的別名。
@end itemize

@item 
@ref{de,,symtable}：


@itemize *

@item 
自 Python 3.14 起，@ref{31c,,Class.get_methods} 方法已被棄用。
@end itemize

@item 
@ref{df,,sys}：


@itemize *

@item 
自 Python 3.13 起，@ref{33d,,_enablelegacywindowsfsencoding()} 函式已被棄用。請改用 
@geindex PYTHONLEGACYWINDOWSFSENCODING
@geindex 環境變數; PYTHONLEGACYWINDOWSFSENCODING
@ref{33e,,PYTHONLEGACYWINDOWSFSENCODING} 環境變數。
@end itemize

@item 
@ref{e1,,sysconfig}：


@itemize *

@item 
自 Python 3.14 起，@code{sysconfig.expand_makefile_vars()} 函式已被棄用。請改用 @ref{33f,,sysconfig.get_paths()} 的 @code{vars} 引數。
@end itemize

@item 
@ref{e4,,tarfile}：


@itemize *

@item 
自 Python 3.13 起，未以文件記錄和未被使用的 @code{TarFile.tarfile} 屬性已被棄用。
@end itemize
@end itemize

@node Python 3 17 中待移除的項目<2>,未來版本中的待移除項目<3>,Python 3 16 中待移除的項目<3>,New Deprecations
@anchor{whatsnew/3 13 pending-removal-in-python-3-17}@anchor{5af}
@subsubsection Python 3.17 中待移除的項目



@itemize *

@item 
@ref{1f,,collections.abc}：


@itemize -

@item 
@ref{341,,collections.abc.ByteString} 預計在 Python 3.17 中移除。

使用 @code{isinstance(obj, collections.abc.Buffer)} 來測試 @code{obj} 是否在 runtime 實作了@ref{260,,緩衝區協定}。在型別註解的使用中，請用 @ref{342,,Buffer} 或明確指定你的程式碼所支援型別的聯集（例如 @code{bytes | bytearray | memoryview}）。

@code{ByteString} 最初被設計為一個抽象類別，以作為 @ref{192,,bytes} 和 @ref{343,,bytearray} 的超型別 (supertype)。然而由於 ABC 從未擁有任何方法，知道一個物件是 @code{ByteString} 的實例從未真正告訴你任何關於該物件的有用資訊。其他常見的緩衝區型別如 @ref{165,,memoryview} 也從未被理解為 @code{ByteString} 的子型別（無論是在 runtime 還是由靜態型別檢查器）。

更多細節請見 
@geindex Python Enhancement Proposals; PEP 688#current-options
PEP 688@footnote{https://peps.python.org/pep-0688/#current-options}。（由 Shantanu Jain 於 gh-91896@footnote{https://github.com/python/cpython/issues/91896} 貢獻。）
@end itemize

@item 
@ref{10a,,typing}：


@itemize -

@item 
在 Python 3.14 之前，舊式聯集是使用私有類別 @code{typing._UnionGenericAlias} 實作的。這個類別不再被需要，但為了向後相容性而保留，並計劃將在 Python 3.17 中移除。使用者應該改用文件中記錄的內省輔助函式，例如 @ref{2ab,,typing.get_origin()} 和 @ref{2ac,,typing.get_args()}，或者依賴私有實作細節。

@item 
@ref{344,,typing.ByteString} 自 Python 3.9 起已被棄用，預計在 Python 3.17 中移除。

使用 @code{isinstance(obj, collections.abc.Buffer)} 來測試 @code{obj} 是否在 runtime 實作了@ref{260,,緩衝區協定}。在型別註解的使用中，請用 @ref{342,,Buffer} 或明確指定你的程式碼所支援型別的聯集（例如 @code{bytes | bytearray | memoryview}）。

@code{ByteString} 最初被設計為一個抽象類別，以作為 @ref{192,,bytes} 和 @ref{343,,bytearray} 的超型別 (supertype)。然而由於 ABC 從未擁有任何方法，知道一個物件是 @code{ByteString} 的實例從未真正告訴你任何關於該物件的有用資訊。其他常見的緩衝區型別如 @ref{165,,memoryview} 也從未被理解為 @code{ByteString} 的子型別（無論是在 runtime 還是由靜態型別檢查器）。

更多細節請見 
@geindex Python Enhancement Proposals; PEP 688#current-options
PEP 688@footnote{https://peps.python.org/pep-0688/#current-options}。（由 Shantanu Jain 於 gh-91896@footnote{https://github.com/python/cpython/issues/91896} 貢獻。）
@end itemize
@end itemize

@node 未來版本中的待移除項目<3>,,Python 3 17 中待移除的項目<2>,New Deprecations
@anchor{whatsnew/3 13 pending-removal-in-future-versions}@anchor{5b0}
@subsubsection 未來版本中的待移除項目


以下 API 將在未來被移除，雖然目前尚未安排移除日期。


@itemize *

@item 
@ref{7,,argparse}：


@itemize *

@item 
巢狀引數群組和巢狀互斥群組已被棄用。

@item 
將未以文件記錄的關鍵字引數 `prefix_chars' 傳遞給 @ref{2ea,,add_argument_group()} 的做法現在已被棄用。

@item 
@ref{30b,,argparse.FileType} 型別轉換器已被棄用。
@end itemize

@item 
@ref{13,,builtins}：


@itemize *

@item 
產生器：@code{throw(type, exc, tb)} 和 @code{athrow(type, exc, tb)} 簽名已被棄用：請改用 @code{throw(exc)} 和 @code{athrow(exc)}，為單引數簽名。

@item 
目前 Python 接受數值字面值後面立即接關鍵字，例如 @code{0in x}、@code{1or x}、@code{0if 1else 2}。它讓運算式模糊且容易混淆，如 @code{[0x1for x in y]}（可以解釋為 @code{[0x1 for x in y]} 或 @code{[0x1f or x in y]}）。如果數值字面值後立即接 @ref{347,,and}、@ref{17c,,else}、@ref{348,,for}、@ref{181,,if}、@ref{349,,in}、@ref{34a,,is} 和 @ref{34b,,or} 之一的關鍵字，則會引發語法警告。在未來版本中，它將被更改為語法錯誤。(gh-87999@footnote{https://github.com/python/cpython/issues/87999})

@item 
@code{__index__()} 和 @code{__int__()} 方法回傳非 int 型別的支援：這些方法將需要回傳 @ref{19b,,int} 的嚴格子類別實例。

@item 
回傳 @ref{196,,float} 嚴格子類別 @code{__float__()} 方法的支援：這些方法將需要回傳 @ref{196,,float} 的實例。

@item 
回傳 @ref{197,,complex} 嚴格子類別 @code{__complex__()} 方法的支援：這些方法將需要回傳 @ref{197,,complex} 的實例。

@item 
將 @code{int()} 委派給 @code{__trunc__()} 方法。

@item 
在 @ref{197,,complex()} 建構子中將複數作為 `real' 或 `imag' 引數傳遞現在已被棄用；它應該只作為單個位置引數傳遞。 (由 Serhiy Storchaka 於 gh-109218@footnote{https://github.com/python/cpython/issues/109218} 貢獻。)
@end itemize

@item 
@ref{15,,calendar}：@code{calendar.January} 和 @code{calendar.February} 常數已被棄用並被 @ref{34c,,calendar.JANUARY} 和 @ref{34d,,calendar.FEBRUARY} 取代。 (由 Prince Roshan 於 gh-103636@footnote{https://github.com/python/cpython/issues/103636} 貢獻。)

@item 
@ref{1c,,codecs}：請改用 @ref{315,,open()} 而非 @ref{314,,codecs.open()}。(gh-133038@footnote{https://github.com/python/cpython/issues/133038})

@item 
@ref{32f,,codeobject.co_lnotab}：請改用 @ref{34e,,codeobject.co_lines()} 方法。

@item 
@ref{34,,datetime}：


@itemize *

@item 
@ref{34f,,utcnow()}：請改用 @code{datetime.datetime.now(tz=datetime.UTC)}。

@item 
@ref{350,,utcfromtimestamp()}：請改用 @code{datetime.datetime.fromtimestamp(timestamp, tz=datetime.UTC)}。
@end itemize

@item 
@ref{67,,gettext}：複數值必須是整數。

@item 
@ref{7b,,importlib}：


@itemize *

@item 
@ref{351,,cache_from_source()} `debug_override' 參數已被棄用：請改用 `optimization' 參數。
@end itemize

@item 
@ref{7e,,importlib.metadata}：


@itemize *

@item 
@code{EntryPoints} 元組介面。

@item 
回傳值上的隱式 @code{None}。
@end itemize

@item 
@ref{8b,,logging}：自 Python 3.3 起，@code{warn()} 方法已被棄用，請改用 @ref{352,,warning()}。

@item 
@ref{8f,,mailbox}：已棄用 StringIO 輸入和文本模式，請改用 BytesIO 和二進位模式。

@item 
@ref{a5,,os}：在多執行緒行程中呼叫 @ref{353,,os.register_at_fork()}。

@item 
@code{pydoc.ErrorDuringImport}：`exc_info' 參數的元組值已被棄用，請用例外實例。

@item 
@ref{be,,re}：現在對正規表示式中的數值群組參照和群組名稱用了更嚴格的規則。現在只有 ASCII 數碼序列被接受作為數值參照。位元組模式和替換字串中的群組名稱現在只能包含 ASCII 字母、數碼和底線。（由 Serhiy Storchaka 於 gh-91760@footnote{https://github.com/python/cpython/issues/91760} 貢獻。）

@item 
@code{sre_compile}、@code{sre_constants} 和 @code{sre_parse} 模組。

@item 
@ref{ca,,shutil}：@ref{354,,rmtree()} 的 `onerror' 參數在 Python 3.12 中已被棄用；請改用 `onexc' 參數。

@item 
@ref{d5,,ssl} 選項和協定：


@itemize *

@item 
不帶協定引數的 @ref{355,,ssl.SSLContext} 已被棄用。

@item 
@ref{355,,ssl.SSLContext}：@ref{356,,set_npn_protocols()} 和 @code{selected_npn_protocol()} 已被棄用：請改用 ALPN。

@item 
@code{ssl.OP_NO_SSL*} 選項

@item 
@code{ssl.OP_NO_TLS*} 選項

@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{f3,,threading} 方法：


@itemize *

@item 
@code{threading.Condition.notifyAll()}：請用 @ref{357,,notify_all()}。

@item 
@code{threading.Event.isSet()}：請用 @ref{358,,is_set()}。

@item 
@code{threading.Thread.isDaemon()}、@ref{359,,threading.Thread.setDaemon()}：請用 @ref{35a,,threading.Thread.daemon} 屬性。

@item 
@code{threading.Thread.getName()}、@ref{35b,,threading.Thread.setName()}：請用 @ref{2a0,,threading.Thread.name} 屬性。

@item 
@code{threading.currentThread()}：請用 @ref{35c,,threading.current_thread()}。

@item 
@code{threading.activeCount()}：請用 @ref{35d,,threading.active_count()}。
@end itemize

@item 
@ref{35e,,typing.Text} (gh-92332@footnote{https://github.com/python/cpython/issues/92332})。

@item 
內部類別 @code{typing._UnionGenericAlias} 不再用於實作 @ref{2a8,,typing.Union}。為了保持與此私有類別使用者的相容性，直到至少 Python 3.17 都將提供一個相容性 shim。（由 Jelle Zijlstra 於 gh-105499@footnote{https://github.com/python/cpython/issues/105499} 貢獻。）

@item 
@ref{35f,,unittest.IsolatedAsyncioTestCase}：從測試案例中回傳非 @code{None} 的值已被棄用。

@item 
@ref{110,,urllib.parse} 已棄用函式：請改用 @ref{360,,urlparse()}。


@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{11e,,wsgiref}：@code{SimpleHandler.stdout.write()} 不應該進行部分寫入。

@item 
@ref{12b,,xml.etree.ElementTree}：已棄用對 @ref{361,,Element} 的真值測試。在未來版本中，它將始終回傳 @code{True}。請改用明確的 @code{len(elem)} 或 @code{elem is not None} 測試。

@item 
@ref{292,,sys._clear_type_cache()} 已被棄用：請改用 @ref{362,,sys._clear_internal_caches()}。
@end itemize

@node CPython 位元組碼變更<2>,C API 變更<2>,New Deprecations,Python 3 13 有什麼新功能
@anchor{whatsnew/3 13 cpython-bytecode-changes}@anchor{5b1}
@subsection CPython 位元組碼變更



@itemize *

@item 
The oparg of @ref{5b2,,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{5b3,,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 變更<2>,建置變更<2>,CPython 位元組碼變更<2>,Python 3 13 有什麼新功能
@anchor{whatsnew/3 13 c-api-changes}@anchor{5b4}
@subsection C API 變更


@menu
* 新增功能: 新增功能<2>. 
* Changed C APIs:: 
* Limited C API Changes:: 
* 移除的 C API:: 
* 器用的 C API:: 

@end menu

@node 新增功能<2>,Changed C APIs,,C API 變更<2>
@anchor{whatsnew/3 13 id7}@anchor{5b5}
@subsubsection 新增功能



@itemize *

@item 
Add the @ref{480,,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{5b6,,PyMonitoringState}

@item 
@ref{5b7,,PyMonitoring_FirePyStartEvent()}

@item 
@ref{5b8,,PyMonitoring_FirePyResumeEvent()}

@item 
@ref{5b9,,PyMonitoring_FirePyReturnEvent()}

@item 
@ref{5ba,,PyMonitoring_FirePyYieldEvent()}

@item 
@ref{5bb,,PyMonitoring_FireCallEvent()}

@item 
@ref{5bc,,PyMonitoring_FireLineEvent()}

@item 
@ref{5bd,,PyMonitoring_FireJumpEvent()}

@item 
@code{PyMonitoring_FireBranchEvent}

@item 
@ref{5be,,PyMonitoring_FireCReturnEvent()}

@item 
@ref{5bf,,PyMonitoring_FirePyThrowEvent()}

@item 
@ref{5c0,,PyMonitoring_FireRaiseEvent()}

@item 
@ref{5c1,,PyMonitoring_FireCRaiseEvent()}

@item 
@ref{5c2,,PyMonitoring_FireReraiseEvent()}

@item 
@ref{5c3,,PyMonitoring_FireExceptionHandledEvent()}

@item 
@ref{5c4,,PyMonitoring_FirePyUnwindEvent()}

@item 
@ref{5c5,,PyMonitoring_FireStopIterationEvent()}

@item 
@ref{5c6,,PyMonitoring_EnterScope()}

@item 
@ref{5c7,,PyMonitoring_ExitScope()}
@end itemize

（由 Irit Katriel 在 gh-111997@footnote{https://github.com/python/cpython/issues/111997} 中貢獻。）

@item 
Add @ref{47f,,PyMutex}, a lightweight mutex that occupies a single byte,
and the new @ref{5c8,,PyMutex_Lock()} and @ref{5c9,,PyMutex_Unlock()} functions.
@code{PyMutex_Lock()} will release the @ref{164,,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{5ca,,PyTime C API} to provide access to system clocks:


@itemize *

@item 
@ref{5cb,,PyTime_t}。

@item 
@ref{5cc,,PyTime_MIN} 和 @ref{5cd,,PyTime_MAX}。

@item 
@ref{5ce,,PyTime_AsSecondsDouble()}。

@item 
@ref{5cf,,PyTime_Monotonic()}。

@item 
@ref{5d0,,PyTime_MonotonicRaw()}。

@item 
@ref{5d1,,PyTime_PerfCounter()}。

@item 
@ref{5d2,,PyTime_PerfCounterRaw()}。

@item 
@ref{5d3,,PyTime_Time()}。

@item 
@ref{5d4,,PyTime_TimeRaw()}。
@end itemize

（由 Victor Stinner 和 Petr Viktorin 在 gh-110850@footnote{https://github.com/python/cpython/issues/110850} 中貢獻。）

@item 
Add the @ref{5d5,,PyDict_ContainsString()} function
with the same behavior as @ref{5d6,,PyDict_Contains()},
but `key' is specified as a const char* UTF-8 encoded bytes string,
rather than a @ref{5d7,,PyObject}*.
(Contributed by Victor Stinner in gh-108314@footnote{https://github.com/python/cpython/issues/108314}.)

@item 
Add the @ref{5d8,,PyDict_GetItemRef()} and @ref{41f,,PyDict_GetItemStringRef()}
functions,
which behave similarly to @ref{5d9,,PyDict_GetItemWithError()},
but return a  @ref{5da,,strong reference} instead of a @ref{3d5,,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{5db,,PyDict_SetDefaultRef()} function,
which behaves similarly to @ref{5dc,,PyDict_SetDefault()},
but returns a @ref{5da,,strong reference} instead of a @ref{3d5,,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{420,,PyDict_Pop()} and @ref{5dd,,PyDict_PopString()} functions
to remove a key from a dictionary and optionally return the removed value.
This is similar to @ref{5de,,dict.pop()},
though there is no default value,
and @ref{5df,,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{5e0,,PyMapping_GetOptionalItem()}
and @ref{5e1,,PyMapping_GetOptionalItemString()} functions
as alternatives to @ref{5e2,,PyObject_GetItem()}
and @ref{5e3,,PyMapping_GetItemString()} respectively.
The new functions do not raise @ref{5df,,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{5e4,,PyObject_GetOptionalAttr()}
and @ref{5e5,,PyObject_GetOptionalAttrString()} functions
as alternatives to  @ref{5e6,,PyObject_GetAttr()}
and @ref{5e7,,PyObject_GetAttrString()} respectively.
The new functions do not raise @ref{5e8,,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{5e9,,PyErr_FormatUnraisable()} function
as an extension to @ref{5ea,,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{5da,,strong reference} instead of
a @ref{3d5,,borrowed reference} for frame locals, globals, and builtins,
as part of @ref{46a,,PEP 667}:


@itemize *

@item 
@ref{5eb,,PyEval_GetFrameBuiltins()} 取代 @ref{5ec,,PyEval_GetBuiltins()}

@item 
@ref{5ed,,PyEval_GetFrameGlobals()} 取代 @ref{5ee,,PyEval_GetGlobals()}

@item 
@ref{5ef,,PyEval_GetFrameLocals()} 取代 @ref{5f0,,PyEval_GetLocals()}
@end itemize

（由 Mark Shannon 和 Tian Gao 在 gh-74929@footnote{https://github.com/python/cpython/issues/74929} 中貢獻。）

@item 
Add the @ref{5f1,,Py_GetConstant()} and @ref{5f2,,Py_GetConstantBorrowed()}
functions to get @ref{5da,,strong}
or @ref{3d5,,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{5f3,,PyImport_AddModuleRef()} function
as a replacement for @ref{5f4,,PyImport_AddModule()}
that returns a @ref{5da,,strong reference} instead of a @ref{3d5,,borrowed reference}.
(Contributed by Victor Stinner in gh-105922@footnote{https://github.com/python/cpython/issues/105922}.)

@item 
Add the @ref{5f5,,Py_IsFinalizing()} function to check
whether the main Python interpreter is
@ref{474,,shutting down}.
(Contributed by Victor Stinner in gh-108014@footnote{https://github.com/python/cpython/issues/108014}.)

@item 
Add the @ref{5f6,,PyList_GetItemRef()} function
as a replacement for @ref{5f7,,PyList_GetItem()}
that returns a @ref{5da,,strong reference} instead of a @ref{3d5,,borrowed reference}.
(Contributed by Sam Gross in gh-114329@footnote{https://github.com/python/cpython/issues/114329}.)

@item 
Add the @ref{5f8,,PyList_Extend()} and @ref{5f9,,PyList_Clear()} functions,
mirroring the Python @ref{5fa,,list.extend()} and @ref{5fb,,list.clear()} methods.
(Contributed by Victor Stinner in gh-111138@footnote{https://github.com/python/cpython/issues/111138}.)

@item 
Add the @ref{5fc,,PyLong_AsInt()} function.
It behaves similarly to @ref{5fd,,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{5fe,,PyLong_AsNativeBytes()}, @ref{5ff,,PyLong_FromNativeBytes()},
and @ref{600,,PyLong_FromUnsignedNativeBytes()} functions
to simplify converting between native integer types
and Python @ref{19b,,int} objects.
(Contributed by Steve Dower in gh-111140@footnote{https://github.com/python/cpython/issues/111140}.)

@item 
Add @ref{601,,PyModule_Add()} function, which is similar to
@ref{602,,PyModule_AddObjectRef()} and @ref{603,,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{604,,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{423,,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{605,,PyObject_VisitManagedDict()} and
@ref{606,,PyObject_ClearManagedDict()} functions.
which must be called by the traverse and clear functions of a type using
the @ref{607,,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{608,,PyRefTracer_SetTracer()}
and @ref{609,,PyRefTracer_GetTracer()} functions,
which enable tracking object creation and destruction
in the same way that the @ref{105,,tracemalloc} module does.
(Contributed by Pablo Galindo in gh-93502@footnote{https://github.com/python/cpython/issues/93502}.)

@item 
Add the @ref{60a,,PySys_AuditTuple()} function
as an alternative to @ref{60b,,PySys_Audit()}
that takes event arguments as a Python @ref{60c,,tuple} object.
(Contributed by Victor Stinner in gh-85283@footnote{https://github.com/python/cpython/issues/85283}.)

@item 
Add the @ref{421,,PyThreadState_GetUnchecked()} function
as an alternative to @ref{60d,,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{60e,,PyType_GetFullyQualifiedName()} function
to get the type's fully qualified name.
The module name is prepended if @ref{60f,,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{610,,PyType_GetModuleName()} function
to get the type's module name. This is equivalent to getting the
@ref{60f,,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{611,,PyUnicode_EqualToUTF8AndSize()}
and @ref{612,,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{3dd,,PyWeakref_GetRef()} function
as an alternative to  @ref{3db,,PyWeakref_GetObject()}
that returns a @ref{5da,,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{613,,PyObject_HasAttrWithError()} 取代 @ref{614,,PyObject_HasAttr()}。

@item 
@ref{615,,PyObject_HasAttrStringWithError()} 取代 @ref{616,,PyObject_HasAttrString()}。

@item 
@ref{617,,PyMapping_HasKeyWithError()} 取代 @ref{618,,PyMapping_HasKey()}。

@item 
@ref{619,,PyMapping_HasKeyStringWithError()} 取代 @ref{61a,,PyMapping_HasKeyString()}。
@end itemize

The new functions return @code{-1} for errors
and the standard @code{1} for true and @code{0} for false.

（由 Serhiy Storchaka 在 gh-108511@footnote{https://github.com/python/cpython/issues/108511} 中貢獻。）
@end itemize

@node Changed C APIs,Limited C API Changes,新增功能<2>,C API 變更<2>
@anchor{whatsnew/3 13 changed-c-apis}@anchor{61b}
@subsubsection Changed C APIs



@itemize *

@item 
The `keywords' parameter of @ref{61c,,PyArg_ParseTupleAndKeywords()}
and @ref{61d,,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{61e,,PY_CXX_CONST} macro.
(Contributed by Serhiy Storchaka in gh-65210@footnote{https://github.com/python/cpython/issues/65210}.)

@item 
@ref{61c,,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{61f,,PyUnstable_Code_GetFirstFree()}.
(Contributed by Bogdan Romanyuk in gh-115781@footnote{https://github.com/python/cpython/issues/115781}.)

@item 
The @ref{620,,PyDict_GetItem()}, @ref{621,,PyDict_GetItemString()},
@ref{618,,PyMapping_HasKey()}, @ref{61a,,PyMapping_HasKeyString()},
@ref{614,,PyObject_HasAttr()}, @ref{616,,PyObject_HasAttrString()},
and @ref{622,,PySys_GetObject()} functions,
each of which clears all errors which occurred when calling them
now reports these errors using @ref{502,,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{623,,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{624,,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{504,,debug mode}
or @ref{625,,with assertions},
@ref{626,,PyTuple_SET_ITEM()} and @ref{627,,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,移除的 C API,Changed C APIs,C API 變更<2>
@anchor{whatsnew/3 13 limited-c-api-changes}@anchor{628}
@subsubsection Limited C API Changes



@itemize *

@item 
The following functions are now included in the Limited C API:


@itemize *

@item 
@ref{629,,PyMem_RawMalloc()}

@item 
@ref{62a,,PyMem_RawCalloc()}

@item 
@ref{62b,,PyMem_RawRealloc()}

@item 
@ref{62c,,PyMem_RawFree()}

@item 
@ref{60b,,PySys_Audit()}

@item 
@ref{60a,,PySys_AuditTuple()}

@item 
@ref{62d,,PyType_GetModuleByDef()}
@end itemize

（由 Victor Stinner 貢獻於 gh-85283@footnote{https://github.com/python/cpython/issues/85283}、gh-85283@footnote{https://github.com/python/cpython/issues/85283} 和 gh-116936@footnote{https://github.com/python/cpython/issues/116936}。）

@item 
Python built with @ref{62e,,--with-trace-refs} (tracing references)
now supports the @ref{62f,,Limited API}.
(Contributed by Victor Stinner in gh-108634@footnote{https://github.com/python/cpython/issues/108634}.)
@end itemize

@node 移除的 C API,器用的 C API,Limited C API Changes,C API 變更<2>
@anchor{whatsnew/3 13 removed-c-apis}@anchor{630}
@subsubsection 移除的 C API



@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{551,,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{260,,緩衝協定 (Buffer Protocol)} instead.


@itemize *

@item 
@code{PyObject_CheckReadBuffer()}:
Use @ref{631,,PyObject_CheckBuffer()} to test
whether the object supports the buffer protocol.
Note that @ref{631,,PyObject_CheckBuffer()} doesn't guarantee
that @ref{632,,PyObject_GetBuffer()} will succeed.
To test if the object is actually readable,
see the next example of @ref{632,,PyObject_GetBuffer()}.

@item 
@code{PyObject_AsCharBuffer()}、@code{PyObject_AsReadBuffer()}：請改用 @ref{632,,PyObject_GetBuffer()} 和 @ref{633,,PyBuffer_Release()}。

@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()}：請改用 @ref{632,,PyObject_GetBuffer()} 和 @ref{633,,PyBuffer_Release()}。

@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

（由 Inada Naoki 貢獻於 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()}：請改用 @ref{634,,PyObject_CallNoArgs()} 或 @ref{635,,PyObject_Call()}。

@cartouche
@quotation 警告 
In @ref{635,,PyObject_Call()}, positional arguments must be a @ref{60c,,tuple}
and must not be @code{NULL},
and keyword arguments must be a @ref{183,,dict} or @code{NULL},
whereas the removed functions checked argument types
and accepted @code{NULL} positional and keyword arguments.
To replace @code{PyEval_CallObjectWithKeywords(func, NULL, kwargs)} with
@ref{635,,PyObject_Call()},
pass an empty tuple as positional arguments using
@ref{636,,PyTuple_New(0)}.
@end quotation
@end cartouche

@item 
@code{PyEval_CallFunction()}：請改用 @ref{637,,PyObject_CallFunction()}。

@item 
@code{PyEval_CallMethod()}：請改用 @ref{638,,PyObject_CallMethod()}。

@item 
@code{PyCFunction_Call()}：請改用 @code{PyCFunction_Call()}。
@end itemize

（由 Victor Stinner 貢獻於 gh-105107@footnote{https://github.com/python/cpython/issues/105107}。）

@item 
移除以下設定 Python 初始化的舊函式，這些函式在 Python 3.11 中已被棄用：


@itemize *

@item 
@code{PySys_AddWarnOptionUnicode()}：請改用 @ref{639,,PyConfig.warnoptions}。

@item 
@code{PySys_AddWarnOption()}：請改用 @ref{639,,PyConfig.warnoptions}。

@item 
@code{PySys_AddXOption()}：請改用 @ref{63a,,PyConfig.xoptions}。

@item 
@code{PySys_HasWarnOptions()}：請改用 @ref{63a,,PyConfig.xoptions}。

@item 
@code{PySys_SetPath()}：請改用 @ref{63b,,PyConfig.module_search_paths}。

@item 
@code{Py_SetPath()}：請改用 @ref{63b,,PyConfig.module_search_paths}。

@item 
@code{Py_SetStandardStreamEncoding()}：請改用 @ref{63c,,PyConfig.stdio_encoding} 並設定可能的 @ref{418,,PyConfig.legacy_windows_stdio}（在 Windows 上）。

@item 
@code{_Py_SetProgramFullPath()}：請改用 @ref{63d,,PyConfig.executable}。
@end itemize

請改用 @ref{63e,,Python 初始化設定}的新 @ref{3f4,,PyConfig} API (
@geindex Python Enhancement Proposals; PEP 587
PEP 587@footnote{https://peps.python.org/pep-0587/})，這是在 Python 3.8 中新增的。（由 Victor Stinner 於 gh-105145@footnote{https://github.com/python/cpython/issues/105145} 貢獻。）

@item 
移除 @code{PyEval_AcquireLock()} 和 @code{PyEval_ReleaseLock()} 函式，這些函式在 Python 3.2 中已被廢棄。它們不會更新目前的執行緒狀態。可以用以下函式取代：


@itemize *

@item 
@ref{63f,,PyEval_SaveThread()} 和 @ref{640,,PyEval_RestoreThread()}；

@item 
低階的 @ref{641,,PyEval_AcquireThread()} 和 @ref{640,,PyEval_RestoreThread()}；

@item 
或 @ref{642,,PyGILState_Ensure()} 與 @ref{643,,PyGILState_Release()}。
@end itemize

（由 Victor Stinner 貢獻於 gh-105182@footnote{https://github.com/python/cpython/issues/105182}。）

@item 
移除在 Python 3.9 中已被棄用的 @code{PyEval_ThreadsInitialized()} 函式。自 Python 3.7 起，@code{Py_Initialize()} 總是會建立 GIL：呼叫 @code{PyEval_InitThreads()} 不會有任何作用，而 @code{PyEval_ThreadsInitialized()} 總是會回傳非零值。（由 Victor Stinner 於 gh-105182@footnote{https://github.com/python/cpython/issues/105182} 貢獻。）

@item 
移除 @code{_PyInterpreterState_Get()} 這個對 @ref{644,,PyInterpreterState_Get()} 的別名，這個別名是為了與 Python 3.8 的向後相容性而保留的。pythoncapi-compat 專案@footnote{https://github.com/python/pythoncapi-compat/}可以用於在 Python 3.8 和更舊的版本中取得 @ref{644,,PyInterpreterState_Get()}。（由 Victor Stinner 於 gh-106320@footnote{https://github.com/python/cpython/issues/106320} 貢獻。）

@item 
移除私有的 @code{_PyObject_FastCall()} 函式：請改用自 Python 3.8 起可用的 @code{PyObject_Vectorcall()} 函式（
@geindex Python Enhancement Proposals; PEP 590
PEP 590@footnote{https://peps.python.org/pep-0590/}）。（由 Victor Stinner 於 gh-106023@footnote{https://github.com/python/cpython/issues/106023} 貢獻。）

@item 
移除只包含私有函式的 @code{cpython/pytime.h} 標頭檔。（由 Victor Stinner 於 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 
移除舊的垃圾桶巨集 @code{Py_TRASHCAN_SAFE_BEGIN} 和 @code{Py_TRASHCAN_SAFE_END}。請將兩者都替換為新的巨集 @code{Py_TRASHCAN_BEGIN} 和 @code{Py_TRASHCAN_END}。（由 Irit Katriel 在 gh-105111@footnote{https://github.com/python/cpython/issues/105111} 中貢獻。）
@end itemize

@node 器用的 C API,,移除的 C API,C API 變更<2>
@anchor{whatsnew/3 13 deprecated-c-apis}@anchor{645}
@subsubsection 器用的 C API



@itemize *

@item 
棄用舊的 Python 初始化函式：


@itemize *

@item 
@ref{3f2,,PySys_ResetWarnOptions()}：請改為清除 @ref{3f3,,sys.warnoptions} 和 @code{warnings.filters}。

@item 
@ref{3e7,,Py_GetExecPrefix()}：請改用 @ref{3e9,,sys.exec_prefix}。

@item 
@ref{3e1,,Py_GetPath()}：請改用 @ref{3e2,,sys.path}。

@item 
@ref{3e3,,Py_GetPrefix()}：請改用 @ref{3e6,,sys.prefix}。

@item 
@ref{3ea,,Py_GetProgramFullPath()}：請改用 @ref{3eb,,sys.executable}。

@item 
@ref{3ec,,Py_GetProgramName()}：請改用 @ref{3eb,,sys.executable}。

@item 
@ref{3ed,,Py_GetPythonHome()}：請改用 @ref{3f1,,PyConfig.home} 或 
@geindex PYTHONHOME
@geindex 環境變數; PYTHONHOME
@ref{3ee,,PYTHONHOME} 環境變數。
@end itemize

（由 Victor Stinner 在 gh-105145@footnote{https://github.com/python/cpython/issues/105145} 中貢獻。）

@item 
@ref{23d,,軟性棄用} @ref{5ec,,PyEval_GetBuiltins()}、@ref{5ee,,PyEval_GetGlobals()} 和 @ref{5f0,,PyEval_GetLocals()} 函式，這些函式會回傳一個@ref{3d5,,借用參照}。（作為 
@geindex Python Enhancement Proposals; PEP 667
PEP 667@footnote{https://peps.python.org/pep-0667/} 一部分的軟性棄用。）

@item 
棄用 @ref{3d9,,PyImport_ImportModuleNoBlock()} 函式，這只是自 Python 3.3 起的 @ref{3da,,PyImport_ImportModule()} 的別名。（由 Victor Stinner 在 gh-105396@footnote{https://github.com/python/cpython/issues/105396} 中貢獻。）

@item 
@ref{23d,,軟性棄用} @ref{603,,PyModule_AddObject()} 函式。應該改用 @ref{601,,PyModule_Add()} 或 @ref{602,,PyModule_AddObjectRef()}。（由 Serhiy Storchaka 在 gh-86493@footnote{https://github.com/python/cpython/issues/86493} 中貢獻。）

@item 
棄用舊的 @code{Py_UNICODE} 和 @code{PY_UNICODE_TYPE} 型別以及 @code{Py_UNICODE_WIDE} 定義。請直接使用 @code{wchar_t} 型別。自 Python 3.3 起，@code{Py_UNICODE} 和 @code{PY_UNICODE_TYPE} 只是 @code{wchar_t} 的別名。（由 Victor Stinner 在 gh-105156@footnote{https://github.com/python/cpython/issues/105156} 中貢獻。）

@item 
棄用 @ref{3db,,PyWeakref_GetObject()} 和 @ref{3dc,,PyWeakref_GET_OBJECT()} 函式，這些函式會回傳一個@ref{3d5,,借用參照}。請改用新的 @ref{3dd,,PyWeakref_GetRef()} 函式，這個函式會回傳一個@ref{5da,,強參照}。pythoncapi-compat 專案@footnote{https://github.com/python/pythoncapi-compat/}可以用於在 Python 3.12 和更舊的版本中取得 @ref{3dd,,PyWeakref_GetRef()}。（由 Victor Stinner 在 gh-105927@footnote{https://github.com/python/cpython/issues/105927} 中貢獻。）
@end itemize

@c Add deprecations above alphabetically, not here at the end.

@menu
* Python 3.14 中待移除的項目: Python 3 14 中待移除的項目<2>. 
* Python 3.15 中待移除的項目: Python 3 15 中待移除的項目<4>. 
* Python 3.16 中待移除的項目: Python 3 16 中待移除的項目<4>. 
* Python 3.18 中待移除的項目: Python 3 18 中待移除的項目<2>. 
* 未來版本中的待移除項目: 未來版本中的待移除項目<4>. 

@end menu

@node Python 3 14 中待移除的項目<2>,Python 3 15 中待移除的項目<4>,,器用的 C API
@anchor{whatsnew/3 13 id8}@anchor{646}
@subsubsection Python 3.14 中待移除的項目



@itemize *

@item 
@ref{647,,PyDictObject} 中的 @code{ma_version_tag} 欄位，用於擴充模組 (
@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 
使用可變基底建立@ref{3cd,,不可變型別} (gh-95388@footnote{https://github.com/python/cpython/issues/95388})。
@end itemize

@node Python 3 15 中待移除的項目<4>,Python 3 16 中待移除的項目<4>,Python 3 14 中待移除的項目<2>,器用的 C API
@anchor{whatsnew/3 13 id9}@anchor{648}
@subsubsection Python 3.15 中待移除的項目



@itemize *

@item 
@ref{3d9,,PyImport_ImportModuleNoBlock()}：請改用 @ref{3da,,PyImport_ImportModule()}。

@item 
@ref{3db,,PyWeakref_GetObject()} 和 @ref{3dc,,PyWeakref_GET_OBJECT()}：請改用 @ref{3dd,,PyWeakref_GetRef()}。可以使用 pythoncapi-compat 專案@footnote{https://github.com/python/pythoncapi-compat/}來為 Python 3.12 和更早版本取得 @ref{3dd,,PyWeakref_GetRef()}。

@item 
@ref{3de,,Py_UNICODE} 型別與 @code{Py_UNICODE_WIDE} 巨集：請改用 @code{wchar_t}。

@item 
@code{PyUnicode_AsDecodedObject()}：請改用 @ref{3df,,PyCodec_Decode()}。

@item 
@code{PyUnicode_AsDecodedUnicode()}：請改用 @ref{3df,,PyCodec_Decode()}；請注意某些編解碼器（例如 "base64"）可能會回傳非 @ref{169,,str} 的型別，例如 @ref{192,,bytes}。

@item 
@code{PyUnicode_AsEncodedObject()}：請改用 @ref{3e0,,PyCodec_Encode()}。

@item 
@code{PyUnicode_AsEncodedUnicode()}：請改用 @ref{3e0,,PyCodec_Encode()}；請注意某些編解碼器（例如 "base64"）可能會回傳非 @ref{192,,bytes} 的型別，例如 @ref{169,,str}。

@item 
Python 初始化函式，自 Python 3.13 起已被棄用：


@itemize *

@item 
@ref{3e1,,Py_GetPath()}：請改用 @ref{37a,,PyConfig_Get("module_search_paths")} (@ref{3e2,,sys.path})。

@item 
@ref{3e3,,Py_GetPrefix()}：請改用 @ref{37a,,PyConfig_Get("base_prefix")} (@ref{3e4,,sys.base_prefix})。如果需要處理@ref{3e5,,虛擬環境}，請改用 @ref{37a,,PyConfig_Get("prefix")} (@ref{3e6,,sys.prefix})。

@item 
@ref{3e7,,Py_GetExecPrefix()}：請改用 @ref{37a,,PyConfig_Get("base_exec_prefix")} (@ref{3e8,,sys.base_exec_prefix})。如果需要處理@ref{3e5,,虛擬環境}，請改用 @ref{37a,,PyConfig_Get("exec_prefix")} (@ref{3e9,,sys.exec_prefix})。

@item 
@ref{3ea,,Py_GetProgramFullPath()}：請改用 @ref{37a,,PyConfig_Get("executable")} (@ref{3eb,,sys.executable})。

@item 
@ref{3ec,,Py_GetProgramName()}：請改用 @ref{37a,,PyConfig_Get("executable")} (@ref{3eb,,sys.executable})。

@item 
@ref{3ed,,Py_GetPythonHome()}：請改用 @ref{37a,,PyConfig_Get("home")} 或 
@geindex PYTHONHOME
@geindex 環境變數; PYTHONHOME
@ref{3ee,,PYTHONHOME} 環境變數。
@end itemize

pythoncapi-compat 專案@footnote{https://github.com/python/pythoncapi-compat/} 可以用來為 Python 3.13 和更早版本取得 @ref{37a,,PyConfig_Get()}。

@item 
用於配置 Python 初始化的函式，自 Python 3.11 起已被棄用：


@itemize *

@item 
@code{PySys_SetArgvEx()}：請改用 @ref{3ef,,PyConfig.argv}。

@item 
@code{PySys_SetArgv()}：請改用 @ref{3ef,,PyConfig.argv}。

@item 
@code{Py_SetProgramName()}：請改用 @ref{3f0,,PyConfig.program_name}。

@item 
@code{Py_SetPythonHome()}：請改用 @ref{3f1,,PyConfig.home}。

@item 
@ref{3f2,,PySys_ResetWarnOptions()}：請改為清除 @ref{3f3,,sys.warnoptions} 和 @code{warnings.filters}。
@end itemize

應改用帶有 @ref{3f4,,PyConfig} 的 @ref{3f5,,Py_InitializeFromConfig()} API。

@item 
全域配置變數：


@itemize *

@item 
@ref{3f6,,Py_DebugFlag}：請改用 @ref{3f7,,PyConfig.parser_debug} 或 @ref{37a,,PyConfig_Get("parser_debug")}。

@item 
@ref{3f8,,Py_VerboseFlag}：請改用 @ref{3f9,,PyConfig.verbose} 或 @ref{37a,,PyConfig_Get("verbose")}。

@item 
@ref{3fa,,Py_QuietFlag}：請改用 @ref{3fb,,PyConfig.quiet} 或 @ref{37a,,PyConfig_Get("quiet")}。

@item 
@ref{3fc,,Py_InteractiveFlag}：請改用 @ref{3fd,,PyConfig.interactive} 或 @ref{37a,,PyConfig_Get("interactive")}。

@item 
@ref{3fe,,Py_InspectFlag}：請改用 @ref{3ff,,PyConfig.inspect} 或 @ref{37a,,PyConfig_Get("inspect")}。

@item 
@ref{400,,Py_OptimizeFlag}：請改用 @ref{401,,PyConfig.optimization_level} 或 @ref{37a,,PyConfig_Get("optimization_level")}。

@item 
@ref{402,,Py_NoSiteFlag}：請改用 @ref{403,,PyConfig.site_import} 或 @ref{37a,,PyConfig_Get("site_import")}。

@item 
@ref{404,,Py_BytesWarningFlag}：請改用 @ref{405,,PyConfig.bytes_warning} 或 @ref{37a,,PyConfig_Get("bytes_warning")}。

@item 
@ref{406,,Py_FrozenFlag}：請改用 @ref{407,,PyConfig.pathconfig_warnings} 或 @ref{37a,,PyConfig_Get("pathconfig_warnings")}。

@item 
@ref{408,,Py_IgnoreEnvironmentFlag}：請改用 @ref{409,,PyConfig.use_environment} 或 @ref{37a,,PyConfig_Get("use_environment")}。

@item 
@ref{40a,,Py_DontWriteBytecodeFlag}：請改用 @ref{40b,,PyConfig.write_bytecode} 或 @ref{37a,,PyConfig_Get("write_bytecode")}。

@item 
@ref{40c,,Py_NoUserSiteDirectory}：請改用 @ref{40d,,PyConfig.user_site_directory} 或 @ref{37a,,PyConfig_Get("user_site_directory")}。

@item 
@ref{40e,,Py_UnbufferedStdioFlag}：請改用 @ref{40f,,PyConfig.buffered_stdio} 或 @ref{37a,,PyConfig_Get("buffered_stdio")}。

@item 
@ref{410,,Py_HashRandomizationFlag}：請改用 @ref{411,,PyConfig.use_hash_seed} 和 @ref{412,,PyConfig.hash_seed} 或 @ref{37a,,PyConfig_Get("hash_seed")}。

@item 
@ref{413,,Py_IsolatedFlag}：請改用 @ref{414,,PyConfig.isolated} 或 @ref{37a,,PyConfig_Get("isolated")}。

@item 
@ref{415,,Py_LegacyWindowsFSEncodingFlag}：請改用 @ref{416,,PyPreConfig.legacy_windows_fs_encoding} 或 @ref{37a,,PyConfig_Get("legacy_windows_fs_encoding")}。

@item 
@ref{417,,Py_LegacyWindowsStdioFlag}：請改用 @ref{418,,PyConfig.legacy_windows_stdio} 或 @ref{37a,,PyConfig_Get("legacy_windows_stdio")}。

@item 
@code{Py_FileSystemDefaultEncoding}、@code{Py_HasFileSystemDefaultEncoding}：請改用 @ref{419,,PyConfig.filesystem_encoding} 或 @ref{37a,,PyConfig_Get("filesystem_encoding")}。

@item 
@code{Py_FileSystemDefaultEncodeErrors}：請改用 @ref{41a,,PyConfig.filesystem_errors} 或 @ref{37a,,PyConfig_Get("filesystem_errors")}。

@item 
@code{Py_UTF8Mode}：請改用 @ref{41b,,PyPreConfig.utf8_mode} 或 @ref{37a,,PyConfig_Get("utf8_mode")}。（請參閱 @ref{41c,,Py_PreInitialize()}）
@end itemize

應改用帶有 @ref{3f4,,PyConfig} 的 @ref{3f5,,Py_InitializeFromConfig()} API 來設定這些選項。或者也可以使用 @ref{37a,,PyConfig_Get()} 在執行時取得這些選項。
@end itemize

@node Python 3 16 中待移除的項目<4>,Python 3 18 中待移除的項目<2>,Python 3 15 中待移除的項目<4>,器用的 C API
@anchor{whatsnew/3 13 id10}@anchor{649}
@subsubsection Python 3.16 中待移除的項目



@itemize *

@item 
@code{libmpdecimal} 的打包副本 (bundled copy)。
@end itemize

@node Python 3 18 中待移除的項目<2>,未來版本中的待移除項目<4>,Python 3 16 中待移除的項目<4>,器用的 C API
@anchor{whatsnew/3 13 pending-removal-in-python-3-18}@anchor{64a}
@subsubsection Python 3.18 中待移除的項目



@itemize *

@item 
以下私有函式已被棄用，並計劃在 Python 3.18 中移除：


@itemize *

@item 
@code{_PyBytes_Join()}：請改用 @ref{381,,PyBytes_Join()}。

@item 
@code{_PyDict_GetItemStringWithError()}：請改用 @ref{41f,,PyDict_GetItemStringRef()}。

@item 
@code{_PyDict_Pop()}：請改用 @ref{420,,PyDict_Pop()}。

@item 
@code{_PyLong_Sign()}：請改用 @ref{398,,PyLong_GetSign()}。

@item 
@code{_PyLong_FromDigits()} 和 @code{_PyLong_New()}：請改用 @ref{3a8,,PyLongWriter_Create()}。

@item 
@code{_PyThreadState_UncheckedGet()}：請改用 @ref{421,,PyThreadState_GetUnchecked()}。

@item 
@code{_PyUnicode_AsString()}：請改用 @ref{422,,PyUnicode_AsUTF8()}。

@item 
@code{_PyUnicodeWriter_Init()}：將 @code{_PyUnicodeWriter_Init(&writer)} 替換為 @ref{3b2,,writer = PyUnicodeWriter_Create(0)}。

@item 
@code{_PyUnicodeWriter_Finish()}：將 @code{_PyUnicodeWriter_Finish(&writer)} 替換為 @ref{3b5,,PyUnicodeWriter_Finish(writer)}。

@item 
@code{_PyUnicodeWriter_Dealloc()}：將 @code{_PyUnicodeWriter_Dealloc(&writer)} 替換為 @ref{3b4,,PyUnicodeWriter_Discard(writer)}。

@item 
@code{_PyUnicodeWriter_WriteChar()}：將 @code{_PyUnicodeWriter_WriteChar(&writer, ch)} 替換為 @ref{3b8,,PyUnicodeWriter_WriteChar(writer@comma{} ch)}。

@item 
@code{_PyUnicodeWriter_WriteStr()}：將 @code{_PyUnicodeWriter_WriteStr(&writer, str)} 替換為 @ref{3ba,,PyUnicodeWriter_WriteStr(writer@comma{} str)}。

@item 
@code{_PyUnicodeWriter_WriteSubstring()}：將 @code{_PyUnicodeWriter_WriteSubstring(&writer, str, start, end)} 替換為 @ref{3bb,,PyUnicodeWriter_WriteSubstring(writer@comma{} str@comma{} start@comma{} end)}。

@item 
@code{_PyUnicodeWriter_WriteASCIIString()}：將 @code{_PyUnicodeWriter_WriteASCIIString(&writer, str)} 替換為 @ref{3b7,,PyUnicodeWriter_WriteASCII(writer@comma{} str)}。

@item 
@code{_PyUnicodeWriter_WriteLatin1String()}：將 @code{_PyUnicodeWriter_WriteLatin1String(&writer, str)} 替換為 @ref{3bd,,PyUnicodeWriter_WriteUTF8(writer@comma{} str)}。

@item 
@code{_PyUnicodeWriter_Prepare()}：（無替代方案）。

@item 
@code{_PyUnicodeWriter_PrepareKind()}：（無替代方案）。

@item 
@code{_Py_HashPointer()}：請改用 @ref{423,,Py_HashPointer()}。

@item 
@code{_Py_fopen_obj()}：請改用 @ref{391,,Py_fopen()}。
@end itemize

可以使用 pythoncapi-compat project@footnote{https://github.com/python/pythoncapi-compat/} 來取得這些於 Python 3.13 及更早版本的新公開函式。（由 Victor Stinner 在 gh-128863@footnote{https://github.com/python/cpython/issues/128863} 貢獻）
@end itemize

@node 未來版本中的待移除項目<4>,,Python 3 18 中待移除的項目<2>,器用的 C API
@anchor{whatsnew/3 13 id11}@anchor{64b}
@subsubsection 未來版本中的待移除項目


下列 API 已被棄用並將會被移除，不過目前尚未訂定移除日期。


@itemize *

@item 
@ref{425,,Py_TPFLAGS_HAVE_FINALIZE}：自 Python 3.8 起不再需要

@item 
@ref{426,,PyErr_Fetch()}：請改用 @ref{427,,PyErr_GetRaisedException()}。

@item 
@ref{428,,PyErr_NormalizeException()}：請改用 @ref{427,,PyErr_GetRaisedException()}。

@item 
@ref{429,,PyErr_Restore()}：請改用 @ref{42a,,PyErr_SetRaisedException()}。

@item 
@ref{42b,,PyModule_GetFilename()}：請改用 @ref{42c,,PyModule_GetFilenameObject()}。

@item 
@ref{42d,,PyOS_AfterFork()}：請改用 @ref{42e,,PyOS_AfterFork_Child()}。

@item 
@ref{42f,,PySlice_GetIndicesEx()}：請改用 @ref{430,,PySlice_Unpack()} 和 @ref{431,,PySlice_AdjustIndices()}。

@item 
@ref{432,,PyUnicode_READY()}：自 Python 3.12 起不再需要

@item 
@code{PyErr_Display()}：請改用 @ref{433,,PyErr_DisplayException()}。

@item 
@code{_PyErr_ChainExceptions()}：請改用 @code{_PyErr_ChainExceptions1}。

@item 
@code{PyBytesObject.ob_shash} 成員：請改為呼叫 @ref{434,,PyObject_Hash()}。

@item 
執行緒局部儲存 (Thread Local Storage, TLS) API：


@itemize *

@item 
@ref{435,,PyThread_create_key()}：請改用 @ref{436,,PyThread_tss_alloc()}。

@item 
@ref{437,,PyThread_delete_key()}：請改用 @ref{438,,PyThread_tss_free()}。

@item 
@ref{439,,PyThread_set_key_value()}：請改用 @ref{43a,,PyThread_tss_set()}。

@item 
@ref{43b,,PyThread_get_key_value()}：請改用 @ref{43c,,PyThread_tss_get()}。

@item 
@ref{43d,,PyThread_delete_key_value()}：請改用 @ref{43e,,PyThread_tss_delete()}。

@item 
@ref{43f,,PyThread_ReInitTLS()}：自 Python 3.7 起不再需要。
@end itemize
@end itemize

@node 建置變更<2>,移植至 Python 3 13,C API 變更<2>,Python 3 13 有什麼新功能
@anchor{whatsnew/3 13 build-changes}@anchor{64c}@anchor{whatsnew/3 13 pythoncapi-compat-project}@anchor{64d}
@subsection 建置變更



@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{488,,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{488,,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} 不再是 
@geindex Python Enhancement Proposals; PEP 11
PEP 11@footnote{https://peps.python.org/pep-0011/} 支援的平台。（由 Brett Cannon 在 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{d4,,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{64e,,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{64f,,--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{62e,,--with-trace-refs}
(tracing references) is now ABI compatible with the Python release build
and @ref{504,,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{62f,,limited C API}.
(Contributed by Victor Stinner in gh-85283@footnote{https://github.com/python/cpython/issues/85283}.)
@end itemize

@node 移植至 Python 3 13,迴歸測試的變更,建置變更<2>,Python 3 13 有什麼新功能
@anchor{whatsnew/3 13 porting-to-python-3-13}@anchor{46c}
@subsection 移植至 Python 3.13


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

@menu
* Python API 的變更: Python API 的變更<2>. 
* C API 中的改動: C API 中的改動<2>. 

@end menu

@node Python API 的變更<2>,C API 中的改動<2>,,移植至 Python 3 13
@anchor{whatsnew/3 13 changes-in-the-python-api}@anchor{650}
@subsubsection Python API 的變更

@anchor{whatsnew/3 13 pep667-porting-notes-py}@anchor{4a1}

@itemize *

@item 
@ref{46a,,PEP 667} introduces several changes
to the semantics of @ref{469,,locals()} and @ref{4a0,,f_locals}:


@itemize *

@item 
Calling @ref{469,,locals()} in an @ref{49c,,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{469,,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{4a0,,FrameType.f_locals} in an
@ref{49c,,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{217,,functools.partial} now emits a @ref{651,,FutureWarning}
when used as a method.
The behavior will change in future Python versions.
Wrap it in @ref{451,,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{2c0,,OSError} is now raised by @ref{652,,getpass.getuser()}
for any failure to retrieve a username,
instead of @ref{653,,ImportError} on non-Unix platforms
or @ref{5df,,KeyError} on Unix platforms where the password database is empty.

@item 
The value of the @code{mode} attribute of @ref{654,,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{655,,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{656,,mailbox.Maildir} 現在會忽略以點號 (@code{.}) 開頭的檔案。 (由 Zackery Spytz 在 gh-65559@footnote{https://github.com/python/cpython/issues/65559} 貢獻。)

@item 
@ref{532,,pathlib.Path.glob()} and @ref{533,,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{f3,,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 C API 中的改動<2>,,Python API 的變更<2>,移植至 Python 3 13
@anchor{whatsnew/3 13 changes-in-the-c-api}@anchor{657}
@subsubsection 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{658,,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}.

有舊巨集的 @code{tp_dealloc} 函式，例如：

@example
static void
mytype_dealloc(mytype *p)
@{
    PyObject_GC_UnTrack(p);
    Py_TRASHCAN_SAFE_BEGIN(p);
    ...
    Py_TRASHCAN_SAFE_END
@}
@end example

應該改為使用新的巨集，如下所示：

@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{4a2}

@itemize *

@item 
@ref{46a,,PEP 667} introduces several changes
to frame-related functions:


@itemize *

@item 
The effects of mutating the dictionary returned from
@ref{5f0,,PyEval_GetLocals()} in an @ref{49c,,optimized scope} have changed.
New dict entries added this way will now `only' be visible to
subsequent @ref{5f0,,PyEval_GetLocals()} calls in that frame,
as @ref{659,,PyFrame_GetLocals()}, @ref{469,,locals()},
and @ref{4a0,,FrameType.f_locals} no longer access
the same underlying cached dictionary.
Changes made to entries for actual variable names and names added via
the write-through proxy interfaces will be overwritten on subsequent calls
to @ref{5f0,,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{659,,PyFrame_GetLocals()} in an @ref{49c,,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{65a,,PyDict_Copy()}),
or by calling the new @ref{5ef,,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{659,,PyFrame_GetLocals()} was first introduced.

@item 
@code{PyFrame_LocalsToFast()} no longer has any effect.
Calling this function is redundant now that @ref{659,,PyFrame_GetLocals()}
returns a write-through proxy for @ref{49c,,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{420,,PyDict_Pop()} 或 @ref{5dd,,PyDict_PopString()}；

@item 
@code{_PyDict_GetItemWithError()}：@ref{5d8,,PyDict_GetItemRef()}；

@item 
@code{_PyErr_WriteUnraisableMsg()}：@ref{5e9,,PyErr_FormatUnraisable()}；

@item 
@code{_PyEval_SetTrace()}：@ref{65b,,PyEval_SetTrace()} 或 @ref{65c,,PyEval_SetTraceAllThreads()}；

@item 
@code{_PyList_Extend()}：@ref{5f8,,PyList_Extend()}；

@item 
@code{_PyLong_AsInt()}：@ref{5fc,,PyLong_AsInt()}；

@item 
@code{_PyMem_RawStrdup()}：@code{strdup()}；

@item 
@code{_PyMem_Strdup()}：@code{strdup()}；

@item 
@code{_PyObject_ClearManagedDict()}：@ref{606,,PyObject_ClearManagedDict()}；

@item 
@code{_PyObject_VisitManagedDict()}：@ref{605,,PyObject_VisitManagedDict()}；

@item 
@code{_PyThreadState_UncheckedGet()}：@ref{421,,PyThreadState_GetUnchecked()}；

@item 
@code{_PyTime_AsSecondsDouble()}：@ref{5ce,,PyTime_AsSecondsDouble()}；

@item 
@code{_PyTime_GetMonotonicClock()}：@ref{5cf,,PyTime_Monotonic()} 或 @ref{5d0,,PyTime_MonotonicRaw()}；

@item 
@code{_PyTime_GetPerfCounter()}：@ref{5d1,,PyTime_PerfCounter()} 或 @ref{5d2,,PyTime_PerfCounterRaw()}；

@item 
@code{_PyTime_GetSystemClock()}：@ref{5d3,,PyTime_Time()} 或 @ref{5d4,,PyTime_TimeRaw()}；

@item 
@code{_PyTime_MAX}：@ref{5cd,,PyTime_MAX}；

@item 
@code{_PyTime_MIN}：@ref{5cc,,PyTime_MIN}；

@item 
@code{_PyTime_t}：@ref{5cb,,PyTime_t}；

@item 
@code{_Py_HashPointer()}：@ref{423,,Py_HashPointer()}；

@item 
@code{_Py_IsFinalizing()}：@ref{5f5,,Py_IsFinalizing()}。
@end itemize

可以使用 pythoncapi-compat 專案@footnote{https://github.com/python/pythoncapi-compat/}來在 Python 3.12 及更舊的版本中取用大部分的這些新函式。
@end itemize

@node 迴歸測試的變更,,移植至 Python 3 13,Python 3 13 有什麼新功能
@anchor{whatsnew/3 13 regression-test-changes}@anchor{65d}
@subsection 迴歸測試的變更



@itemize *

@item 
使用 @code{configure} @ref{65e,,--with-pydebug} 建置的 Python 現在支援 @ref{16f,,-X presite=package.module} 命令列選項。如果使用它就會指定一個應該在直譯器生命週期的早期階段、在執行 @code{site.py} 之前被引入的模組。(由 Łukasz Langa 在 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 Python 3 12 有什麼新功能,Python 3 11 有什麼新功能,Python 3 13 有什麼新功能,Python 有什麼新功能？
@anchor{whatsnew/3 12 doc}@anchor{65f}@anchor{whatsnew/3 12 translation-repo}@anchor{660}@anchor{whatsnew/3 12 what-s-new-in-python-3-12}@anchor{661}
@section Python 3.12 有什麼新功能


@*編輯者: 
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.

本文介紹了 Python 3.12 與 3.11 相比多了哪些新功能。 Python 3.12 於 2023 年 10 月 2 日發布。完整詳情請見  @ref{142,,changelog}。


@subsubheading 也參考


@geindex Python Enhancement Proposals; PEP 693
PEP 693@footnote{https://peps.python.org/pep-0693/} -- Python 3.12 發佈時程


@menu
* 發布重點摘要: 發布重點摘要<2>. 
* 新增功能: 新增功能<3>. 
* 型別提示相關的新特性:: 
* 其他語言更動: 其他語言更動<2>. 
* 新增模組: 新增模組<2>. 
* 改進的模組: 改進的模組<2>. 
* 最佳化: 最佳化<3>. 
* CPython 位元組碼變更: CPython 位元組碼變更<3>. 
* Demos and Tools:: 
* 已棄用: 已棄用<2>. 
* 已移除: 已移除<2>. 
* 移植至 Python 3.12: 移植至 Python 3 12. 
* 建置變更: 建置變更<3>. 
* C API 變更: C API 變更<3>. 

@end menu

@node 發布重點摘要<2>,新增功能<3>,,Python 3 12 有什麼新功能
@anchor{whatsnew/3 12 summary-release-highlights}@anchor{662}
@subsection 發布重點摘要


@c This section singles out the most important changes in Python 3.12.
@c Brevity is key.

Python 3.12 是 Python 程式語言的穩定版本，包含了語言和標準函式庫的綜合變更。標準函式庫的變更主要集中在清理棄用的 API、可用性和正確性。值得注意的是，@code{distutils} 套件已從標準函式庫中移除。@ref{a5,,os} 和 @ref{a8,,pathlib} 中的檔案系統支援進行了許多改進，並且有數個模組得到更好的效能。

語言變更主要集中在可用性，因為 @ref{663,,f-字串}已經移除了許多限制，並且持續改進 'Did you mean ...' 建議。新的@ref{664,,型別參數語法}和 @ref{665,,type} 陳述式改進了@ref{1a1,,泛型型別}和@ref{666,,型別別名}在與靜態型別檢查器一起使用上的效率。

這篇文章並不試圖提供所有新功能的完整規格，而是提供一個方便的概覽。完整詳情應參考文件，如@ref{149,,標準函式庫參考}和@ref{14a,,語言參考}。如果你想了解某個新功能的完整實作和設計理念，請參考該功能的 PEP；但請注意 PEP 通常在功能完全實作後就不再更新。


__________________________________________________________________


@c PEP-sized items next.

新增語法特性：


@itemize *

@item 
@ref{664,,PEP 695}，型別參數語法和 @ref{665,,type} 陳述式
@end itemize

新增語法特性：


@itemize *

@item 
@ref{667,,PEP 701}，文法中的 @ref{663,,f-字串}
@end itemize

直譯器改進：


@itemize *

@item 
@ref{668,,PEP 684}，直譯器各別持有的 @ref{46e,,GIL}

@item 
@ref{669,,PEP 669}，低影響監控

@item 
@ref{66a,,Improved 'Did you mean ...' suggestions}@anchor{whatsnew/3 12 improved-error-messages}@anchor{66a}
for @ref{450,,NameError}, @ref{653,,ImportError}, and @ref{18e,,SyntaxError} exceptions
@end itemize

Python 資料模型改進：


@itemize *

@item 
@ref{66b,,PEP 688}, using the @ref{260,,buffer protocol} from Python
@end itemize

標準函式庫中的顯著改進


@itemize *

@item 
@ref{266,,pathlib.Path} 類別現在支援子類別化

@item 
@ref{a5,,os} 模組在 Windows 支援上有了數項改進

@item 
一個@ref{66c,,命令列介面}已被加入 @ref{d4,,sqlite3} 模組中

@item 
@ref{2ad,,isinstance()} checks against @ref{66d,,runtime-checkable protocols} enjoy a speed up of between two and 20 times

@item 
@ref{b,,asyncio} 套件進行了許多效能改進，一些基準測試顯示速度提高了 75%。

@item 
一個@ref{66e,,命令列介面}已被加入 @ref{116,,uuid} 模組中

@item 
Due to the changes in @ref{667,,PEP 701},
producing tokens via the @ref{101,,tokenize} module is up to 64% faster.
@end itemize

安全性改進：


@itemize *

@item 
Replace the builtin @ref{6c,,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 改進：


@itemize *

@item 
@ref{66f,,PEP 697}，不穩定 C API 層

@item 
@ref{670,,PEP 683}, immortal objects
@end itemize

CPython 實作改進：


@itemize *

@item 
@ref{671,,PEP 709}, comprehension inlining

@item 
@ref{4a9,,CPython support} for the Linux @code{perf} profiler

@item 
Implement stack overflow protection on supported platforms
@end itemize

新增型別特性：


@itemize *

@item 
@ref{672,,PEP 692}、使用 @ref{331,,TypedDict} 來標註 @ref{673,,**kwargs}

@item 
@ref{674,,PEP 698}、@ref{675,,typing.override()} 裝飾器
@end itemize

重要的棄用、刪除或限制：


@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{169,,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{117,,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{676,,activated}
virtual environment.

@item 
@code{asynchat}、@code{asyncore} 和 @code{imp} 模組以及幾個 @ref{2b3,,unittest.TestCase} 的@ref{677,,方法別名}已被刪除。
@end itemize

@node 新增功能<3>,型別提示相關的新特性,發布重點摘要<2>,Python 3 12 有什麼新功能
@anchor{whatsnew/3 12 new-features}@anchor{678}
@subsection 新增功能


@menu
* PEP 695：型別參數語法:: 
* PEP 701; Syntactic formalization of f-strings: PEP 701 Syntactic formalization of f-strings. 
* PEP 684：直譯器各別持有的 GIL:: 
* PEP 669; Low impact monitoring for CPython: PEP 669 Low impact monitoring for CPython. 
* PEP 688：使緩衝區協定可在 Python 中存取:: 
* PEP 709; Comprehension inlining: PEP 709 Comprehension inlining. 
* 改善錯誤訊息: 改善錯誤訊息<3>. 

@end menu

@node PEP 695：型別參數語法,PEP 701 Syntactic formalization of f-strings,,新增功能<3>
@anchor{whatsnew/3 12 pep-695-type-parameter-syntax}@anchor{679}@anchor{whatsnew/3 12 whatsnew312-pep695}@anchor{664}
@subsubsection PEP 695：型別參數語法


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{67a,,generic classes} and @ref{67b,,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{67c,,type aliases}
using the @ref{665,,type} statement, which creates an instance of
@ref{2ae,,TypeAliasType}:

@example
type Point = tuple[float, float]
@end example

型別別名也可以是@ref{67d,,泛型}：

@example
type Point[T] = tuple[T, T]
@end example

The new syntax allows declaring @ref{483,,TypeVarTuple}
and @ref{482,,ParamSpec} parameters, as well as @ref{481,,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
type IntOrStrSequence[T: (int, str)] = Sequence[T]  # 帶有限制的 TypeVar
@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{67e,,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{5a7,,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{4a6,,annotation scope}. Annotation scopes behave for the
most part like function scopes, but interact differently with enclosing class scopes.
In Python 3.13, @ref{15c,,annotations} will also be evaluated in
annotation scopes.

詳情請見 
@geindex Python Enhancement Proposals; PEP 695
PEP 695@footnote{https://peps.python.org/pep-0695/}。

（PEP 由 Eric Traut 撰寫。由 Jelle Zijlstra、Eric Traut 和其他人在 gh-103764@footnote{https://github.com/python/cpython/issues/103764} 中實作。）

@node PEP 701 Syntactic formalization of f-strings,PEP 684：直譯器各別持有的 GIL,PEP 695：型別參數語法,新增功能<3>
@anchor{whatsnew/3 12 pep-701-syntactic-formalization-of-f-strings}@anchor{67f}@anchor{whatsnew/3 12 whatsnew312-pep701}@anchor{667}
@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{663,,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{18e,,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{680,,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

詳情請見 
@geindex Python Enhancement Proposals; PEP 701
PEP 701@footnote{https://peps.python.org/pep-0701/}。

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{18e,,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：直譯器各別持有的 GIL,PEP 669 Low impact monitoring for CPython,PEP 701 Syntactic formalization of f-strings,新增功能<3>
@anchor{whatsnew/3 12 pep-684-a-per-interpreter-gil}@anchor{681}@anchor{whatsnew/3 12 whatsnew312-pep684}@anchor{668}
@subsubsection PEP 684：直譯器各別持有的 GIL


@geindex Python Enhancement Proposals; PEP 684
PEP 684@footnote{https://peps.python.org/pep-0684/} 引入了直譯器各別持有的 @ref{46e,,GIL}，因此子直譯器現在可以使用各個直譯器特有的 GIL 來建立。這使得 Python 程式可以充分利用多個 CPU 核心。目前這僅透過 C-API 使用，不過 Python API 
@geindex Python Enhancement Proposals; PEP 554
預計在 3.13 中釋出@footnote{https://peps.python.org/pep-0554/}。

Use the new @ref{682,,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;
@}
/* 新的直譯器現在會在目前執行緒中啟用。 */
@end example

For further examples how to use the C-API for sub-interpreters with a
per-interpreter GIL, see @code{Modules/_xxsubinterpretersmodule.c}.

（由 Eric Snow 於 gh-104210@footnote{https://github.com/python/cpython/issues/104210} 等貢獻。）

@node PEP 669 Low impact monitoring for CPython,PEP 688：使緩衝區協定可在 Python 中存取,PEP 684：直譯器各別持有的 GIL,新增功能<3>
@anchor{whatsnew/3 12 pep-669-low-impact-monitoring-for-cpython}@anchor{683}@anchor{whatsnew/3 12 whatsnew312-pep669}@anchor{669}
@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{e0,,API} for profilers,
debuggers, and other tools to monitor events in CPython.
It covers a wide range of events, including calls,
returns, lines, exceptions, jumps, and more.
This means that you only pay for what you use, providing support
for near-zero overhead debuggers and coverage tools.
See  @ref{e0,,sys.monitoring} for details.

（由 Mark Shannon 於 gh-103082@footnote{https://github.com/python/cpython/issues/103082} 中貢獻。）

@node PEP 688：使緩衝區協定可在 Python 中存取,PEP 709 Comprehension inlining,PEP 669 Low impact monitoring for CPython,新增功能<3>
@anchor{whatsnew/3 12 pep-688-making-the-buffer-protocol-accessible-in-python}@anchor{684}@anchor{whatsnew/3 12 whatsnew312-pep688}@anchor{66b}
@subsubsection PEP 688：使緩衝區協定可在 Python 中存取


@geindex Python Enhancement Proposals; PEP 688
PEP 688@footnote{https://peps.python.org/pep-0688/} introduces a way to use the @ref{260,,buffer protocol}
from Python code. Classes that implement the @ref{685,,__buffer__()} method
are now usable as buffer types.

The new @ref{342,,collections.abc.Buffer} ABC provides a standard
way to represent buffer objects, for example in type annotations.
The new @ref{686,,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,改善錯誤訊息<3>,PEP 688：使緩衝區協定可在 Python 中存取,新增功能<3>
@anchor{whatsnew/3 12 pep-709-comprehension-inlining}@anchor{687}@anchor{whatsnew/3 12 whatsnew312-pep709}@anchor{671}
@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{de,,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{469,,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

（由 Carl Meyer 和 Vladimir Matveev 於 
@geindex Python Enhancement Proposals; PEP 709
PEP 709@footnote{https://peps.python.org/pep-0709/} 中貢獻。）

@node 改善錯誤訊息<3>,,PEP 709 Comprehension inlining,新增功能<3>

@subsubsection 改善錯誤訊息



@itemize *

@item 
Modules from the standard library are now potentially suggested as part of
the error messages displayed by the interpreter when a @ref{450,,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{450,,NameError} exceptions for instances.
Now if a @ref{450,,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{18e,,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{653,,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 型別提示相關的新特性,其他語言更動<2>,新增功能<3>,Python 3 12 有什麼新功能
@anchor{whatsnew/3 12 new-features-related-to-type-hints}@anchor{688}
@subsection 型別提示相關的新特性


本節涵蓋了影響
@geindex Python Enhancement Proposals; PEP 484
型別提示@footnote{https://peps.python.org/pep-0484/}和 @ref{10a,,typing} 模組的主要變更。

@menu
* PEP 692; Using TypedDict for more precise **kwargs typing: PEP 692 Using TypedDict for more precise **kwargs typing. 
* PEP 698：覆蓋靜態型別的裝飾器:: 

@end menu

@node PEP 692 Using TypedDict for more precise **kwargs typing,PEP 698：覆蓋靜態型別的裝飾器,,型別提示相關的新特性
@anchor{whatsnew/3 12 pep-692-using-typeddict-for-more-precise-kwargs-typing}@anchor{689}@anchor{whatsnew/3 12 whatsnew312-pep692}@anchor{672}
@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

詳情請見 
@geindex Python Enhancement Proposals; PEP 692
PEP 692@footnote{https://peps.python.org/pep-0692/}。

（由 Franek Magiera 於 gh-103629@footnote{https://github.com/python/cpython/issues/103629} 中貢獻。）

@node PEP 698：覆蓋靜態型別的裝飾器,,PEP 692 Using TypedDict for more precise **kwargs typing,型別提示相關的新特性
@anchor{whatsnew/3 12 pep-698-override-decorator-for-static-typing}@anchor{68a}@anchor{whatsnew/3 12 whatsnew312-pep698}@anchor{674}
@subsubsection PEP 698：覆蓋靜態型別的裝飾器


A new decorator @ref{675,,typing.override()} has been added to the @ref{10a,,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
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

詳情請見 
@geindex Python Enhancement Proposals; PEP 698
PEP 698@footnote{https://peps.python.org/pep-0698/}。

（由 Steven Troxler 於 gh-101561@footnote{https://github.com/python/cpython/issues/101561} 中貢獻。）

@node 其他語言更動<2>,新增模組<2>,型別提示相關的新特性,Python 3 12 有什麼新功能
@anchor{whatsnew/3 12 other-language-changes}@anchor{68b}
@subsection 其他語言更動



@itemize *

@item 
The parser now raises @ref{18e,,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{1ae,,SyntaxWarning}, instead of @ref{1a3,,DeprecationWarning}.
For example, @code{re.compile("\d+\.\d+")} now emits a @ref{1ae,,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{18e,,SyntaxError} will eventually be raised,
instead of @ref{1ae,,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{1ae,,SyntaxWarning}, instead of
@ref{1a3,,DeprecationWarning}.
In a future Python version they will be eventually a @ref{18e,,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{244,,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{4cd,,ExceptionGroup}
and raises one other exception, that exception is no longer wrapped in an
@ref{4cd,,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{68c,,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{3c1,,bool} and @ref{19b,,int}.
(Contributed by Serhiy Storchaka in gh-60203@footnote{https://github.com/python/cpython/issues/60203}.)

@item 
@ref{165,,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{68d,,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{68e,,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{1c2,,ast.parse()} now raises @ref{18e,,SyntaxError} instead of @ref{2eb,,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{e4,,tarfile}, and @ref{68f,,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{690,,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{691,,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 
透過新的環境變數 
@geindex PYTHONPERFSUPPORT
@geindex 環境變數; PYTHONPERFSUPPORT
@ref{692,,PYTHONPERFSUPPORT} 和命令列選項 @ref{16f,,-X perf} 以及新的 @ref{693,,sys.activate_stack_trampoline()}、@ref{694,,sys.deactivate_stack_trampoline()} 和 @ref{695,,sys.is_stack_trampoline_active()} 函式，新增對@ref{4a9,,效能分析器的支援}。（由 Pablo Galindo 設計。由 Pablo Galindo 和 Christian Heimes 貢獻，Gregory P. Smith [Google] 和 Mark Shannon 在 gh-96123@footnote{https://github.com/python/cpython/issues/96123} 中也有貢獻。）
@end itemize

@node 新增模組<2>,改進的模組<2>,其他語言更動<2>,Python 3 12 有什麼新功能
@anchor{whatsnew/3 12 new-modules}@anchor{696}
@subsection 新增模組



@itemize *

@item 
無。
@end itemize

@node 改進的模組<2>,最佳化<3>,新增模組<2>,Python 3 12 有什麼新功能
@anchor{whatsnew/3 12 improved-modules}@anchor{697}
@subsection 改進的模組


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

@end menu

@node array<2>,asyncio<5>,,改進的模組<2>
@anchor{whatsnew/3 12 array}@anchor{698}
@subsubsection array



@itemize *

@item 
The @ref{4b9,,array.array} class now supports subscripting, making it a
@ref{1a1,,generic type}. (Contributed by Jelle Zijlstra in gh-98658@footnote{https://github.com/python/cpython/issues/98658}.)
@end itemize

@node asyncio<5>,calendar<2>,array<2>,改進的模組<2>
@anchor{whatsnew/3 12 asyncio}@anchor{699}
@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{69a,,sendmsg()} if the platform
supports it. (Contributed by Kumar Aditya in gh-91166@footnote{https://github.com/python/cpython/issues/91166}.)

@item 
Add @ref{69b,,asyncio.eager_task_factory()} and @ref{69c,,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{69d,,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{2f2,,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{69e,,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{69f,,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{6a0,,asyncio.wait()} and @ref{4c1,,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<2>,csv,asyncio<5>,改進的模組<2>
@anchor{whatsnew/3 12 calendar}@anchor{6a1}
@subsubsection calendar



@itemize *

@item 
Add enums @ref{6a2,,calendar.Month} and @ref{6a3,,calendar.Day}
defining months of the year and days of the week.
(Contributed by Prince Roshan in gh-103636@footnote{https://github.com/python/cpython/issues/103636}.)
@end itemize

@node csv,dis<3>,calendar<2>,改進的模組<2>
@anchor{whatsnew/3 12 csv}@anchor{6a4}
@subsubsection csv



@itemize *

@item 
Add @ref{6a5,,csv.QUOTE_NOTNULL} and @ref{6a6,,csv.QUOTE_STRINGS} flags to
provide finer grained control of @code{None} and empty strings by
@ref{6a7,,reader} and @ref{6a8,,writer} objects.
@end itemize

@node dis<3>,fractions<3>,csv,改進的模組<2>
@anchor{whatsnew/3 12 dis}@anchor{6a9}
@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{3c,,dis} module.
@ref{6aa,,HAVE_ARGUMENT} is still relevant to real opcodes,
but it is not useful for pseudo instructions. Use the new
@ref{599,,dis.hasarg} collection instead.
(Contributed by Irit Katriel in gh-94216@footnote{https://github.com/python/cpython/issues/94216}.)

@item 
Add the @ref{6ab,,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,dis<3>,改進的模組<2>
@anchor{whatsnew/3 12 fractions}@anchor{6ac}
@subsubsection fractions



@itemize *

@item 
Objects of type @ref{213,,fractions.Fraction} now support float-style
formatting. (Contributed by Mark Dickinson in gh-100161@footnote{https://github.com/python/cpython/issues/100161}.)
@end itemize

@node importlib resources,inspect<2>,fractions<3>,改進的模組<2>
@anchor{whatsnew/3 12 importlib-resources}@anchor{6ad}
@subsubsection importlib.resources



@itemize *

@item 
@ref{6ae,,importlib.resources.as_file()} 現在支援資源目錄。（由 Jason R. Coombs 於 gh-97930@footnote{https://github.com/python/cpython/issues/97930} 中貢獻。）

@item 
將 @ref{6af,,importlib.resources.files()} 的第一個參數重新命名為 `anchor'。（由 Jason R. Coombs 於 gh-100598@footnote{https://github.com/python/cpython/issues/100598} 中貢獻。）
@end itemize

@node inspect<2>,itertools<3>,importlib resources,改進的模組<2>
@anchor{whatsnew/3 12 inspect}@anchor{6b0}
@subsubsection inspect



@itemize *

@item 
新增 @ref{6b1,,inspect.markcoroutinefunction()} 以標記會回傳 @ref{6b2,,coroutine} 的同步函式，以供 @ref{30c,,inspect.iscoroutinefunction()} 使用。（由 Carlton Gibson 於 gh-99247@footnote{https://github.com/python/cpython/issues/99247} 中貢獻。）

@item 
新增 @ref{6b3,,inspect.getasyncgenstate()} 和 @ref{6b4,,inspect.getasyncgenlocals()} 以確定非同步產生器的目前狀態。（由 Thomas Krennwallner 於 gh-79940@footnote{https://github.com/python/cpython/issues/79940} 中貢獻。）

@item 
@ref{6b5,,inspect.getattr_static()} 的效能已大幅改善。大多數對該函式的呼叫應該比 Python 3.11 中快至少 2 倍。（由 Alex Waygood 於 gh-103193@footnote{https://github.com/python/cpython/issues/103193} 中貢獻。）
@end itemize

@node itertools<3>,math<3>,inspect<2>,改進的模組<2>
@anchor{whatsnew/3 12 itertools}@anchor{6b6}
@subsubsection itertools



@itemize *

@item 
新增 @ref{50c,,itertools.batched()} 以將元素收集到大小均等的元組中，其中最後一批次可能比其他的少。（由 Raymond Hettinger 於 gh-98363@footnote{https://github.com/python/cpython/issues/98363} 中貢獻。）
@end itemize

@node math<3>,os<3>,itertools<3>,改進的模組<2>
@anchor{whatsnew/3 12 math}@anchor{6b7}
@subsubsection math



@itemize *

@item 
新增 @ref{6b8,,math.sumprod()} 以計算乘積總和。（由 Raymond Hettinger 於 gh-100485@footnote{https://github.com/python/cpython/issues/100485} 中貢獻。）

@item 
Extend @ref{6b9,,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<3>,os path<3>,math<3>,改進的模組<2>
@anchor{whatsnew/3 12 os}@anchor{6ba}
@subsubsection os



@itemize *

@item 
Add @ref{6bb,,os.PIDFD_NONBLOCK} to open a file descriptor
for a process with @ref{69d,,os.pidfd_open()} in non-blocking mode.
(Contributed by Kumar Aditya in gh-93312@footnote{https://github.com/python/cpython/issues/93312}.)

@item 
@ref{6bc,,os.DirEntry} now includes an @ref{6bd,,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{6be,,os.listdrives()}, @ref{6bf,,os.listvolumes()} and @ref{6c0,,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{26d,,os.stat()} and @ref{6c1,,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<3>,pathlib<6>,os<3>,改進的模組<2>
@anchor{whatsnew/3 12 os-path}@anchor{6c2}
@subsubsection os.path



@itemize *

@item 
新增 @ref{6c3,,os.path.isjunction()} 以檢查給定路徑是否為連結點 (junction)。（由 Charles Machalow 於 gh-99547@footnote{https://github.com/python/cpython/issues/99547} 中貢獻。）

@item 
新增 @ref{6c4,,os.path.splitroot()} 以將路徑分割為三元組 @code{(drive, root, tail)}。（由 Barney Gale 於 gh-101000@footnote{https://github.com/python/cpython/issues/101000} 中貢獻。）
@end itemize

@node pathlib<6>,platform<2>,os path<3>,改進的模組<2>
@anchor{whatsnew/3 12 pathlib}@anchor{6c5}
@subsubsection pathlib



@itemize *

@item 
Add support for subclassing @ref{6c6,,pathlib.PurePath} and
@ref{266,,pathlib.Path}, plus their Posix- and Windows-specific variants.
Subclasses may override the @ref{6c7,,pathlib.PurePath.with_segments()} method
to pass information between path instances.

@item 
Add @ref{6c8,,pathlib.Path.walk()} for walking the directory trees and generating
all file or directory names within them, similar to @ref{6c9,,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{2fc,,pathlib.PurePath.relative_to()}
to allow the insertion of @code{..} entries in the result; this behavior is
more consistent with @ref{6ca,,os.path.relpath()}.
(Contributed by Domenico Ragusa in gh-84538@footnote{https://github.com/python/cpython/issues/84538}.)

@item 
Add @ref{6cb,,pathlib.Path.is_junction()} as a proxy to @ref{6c3,,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{532,,pathlib.Path.glob()},
@ref{533,,pathlib.Path.rglob()} and @ref{6cc,,pathlib.PurePath.match()} for matching
the path's case sensitivity, allowing for more precise control over the matching process.
@end itemize

@node platform<2>,pdb<4>,pathlib<6>,改進的模組<2>
@anchor{whatsnew/3 12 platform}@anchor{6cd}
@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<4>,random<2>,platform<2>,改進的模組<2>
@anchor{whatsnew/3 12 pdb}@anchor{6ce}
@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<4>,改進的模組<2>
@anchor{whatsnew/3 12 random}@anchor{6cf}
@subsubsection random



@itemize *

@item 
新增 @ref{6d0,,random.binomialvariate()}。（由 Raymond Hettinger 於 gh-81620@footnote{https://github.com/python/cpython/issues/81620} 中貢獻。）

@item 
將預設值 @code{lambd=1.0} 加入至 @ref{6d1,,random.expovariate()} 中。（由 Raymond Hettinger 在 gh-100234@footnote{https://github.com/python/cpython/issues/100234} 中貢獻。）
@end itemize

@node shutil<2>,sqlite3<3>,random<2>,改進的模組<2>
@anchor{whatsnew/3 12 shutil}@anchor{6d2}
@subsubsection shutil



@itemize *

@item 
@ref{6d3,,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{354,,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{6d4,,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{6d4,,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{6d4,,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<3>,statistics<2>,shutil<2>,改進的模組<2>
@anchor{whatsnew/3 12 sqlite3}@anchor{6d5}
@subsubsection sqlite3



@itemize *

@item 
新增@ref{66c,,命令列介面}。（由 Erlend E. Aasland 於 gh-77617@footnote{https://github.com/python/cpython/issues/77617} 中貢獻。）

@item 
Add the @ref{6d6,,sqlite3.Connection.autocommit} attribute
to @ref{548,,sqlite3.Connection}
and the `autocommit' parameter to @ref{5a0,,sqlite3.connect()}
to control 
@geindex Python Enhancement Proposals; PEP 249
PEP 249@footnote{https://peps.python.org/pep-0249/}-compliant
@ref{6d7,,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{6d8,,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{6d9,,sqlite3.Connection.getconfig()} and
@ref{6da,,sqlite3.Connection.setconfig()} to @ref{548,,sqlite3.Connection}
to make configuration changes to a database connection.
(Contributed by Erlend E. Aasland in gh-103489@footnote{https://github.com/python/cpython/issues/103489}.)
@end itemize

@node statistics<2>,sys<3>,sqlite3<3>,改進的模組<2>
@anchor{whatsnew/3 12 statistics}@anchor{6db}
@subsubsection statistics



@itemize *

@item 
Extend @ref{6dc,,statistics.correlation()} to include as a @code{ranked} method
for computing the Spearman correlation of ranked data.
(Contributed by Raymond Hettinger in gh-95861@footnote{https://github.com/python/cpython/issues/95861}.)
@end itemize

@node sys<3>,tempfile<2>,statistics<2>,改進的模組<2>
@anchor{whatsnew/3 12 sys}@anchor{6dd}
@subsubsection sys



@itemize *

@item 
Add the @ref{e0,,sys.monitoring} namespace to expose the new @ref{669,,PEP 669} monitoring API.
(Contributed by Mark Shannon in gh-103082@footnote{https://github.com/python/cpython/issues/103082}.)

@item 
Add @ref{693,,sys.activate_stack_trampoline()} and
@ref{694,,sys.deactivate_stack_trampoline()} for activating and deactivating
stack profiler trampolines,
and @ref{695,,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{6de,,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{6df,,sys.last_type}, @ref{6e0,,sys.last_value} and @ref{6e1,,sys.last_traceback}.
(Contributed by Irit Katriel in gh-102778@footnote{https://github.com/python/cpython/issues/102778}.)

@item 
@ref{6e2,,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{6e3,,sys.setrecursionlimit()} and @ref{6e4,,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<2>,sys<3>,改進的模組<2>
@anchor{whatsnew/3 12 tempfile}@anchor{6e5}
@subsubsection tempfile



@itemize *

@item 
@ref{6e6,,tempfile.NamedTemporaryFile} 函式新增了一個選擇性參數 `delete_on_close' （由 Evgeny Zorin 於 gh-58451@footnote{https://github.com/python/cpython/issues/58451} 中貢獻。）

@item 
@ref{528,,tempfile.mkdtemp()} 現在總是會傳回絕對路徑，即使提供給 `dir' 參數的引數是相對路徑。
@end itemize

@node threading<2>,tkinter<3>,tempfile<2>,改進的模組<2>
@anchor{whatsnew/3 12 threading}@anchor{6e7}
@subsubsection threading



@itemize *

@item 
Add @ref{6e8,,threading.settrace_all_threads()} and
@ref{6e9,,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<3>,tokenize,threading<2>,改進的模組<2>
@anchor{whatsnew/3 12 tkinter}@anchor{6ea}
@subsubsection tkinter



@itemize *

@item 
@code{tkinter.Canvas.coords()} now flattens its arguments.
It now accepts not only coordinates as separate arguments
(@code{x1, y1, x2, y2, ...}) and a sequence of coordinates
(@code{[x1, y1, x2, y2, ...]}), but also coordinates grouped in pairs
(@code{(x1, y1), (x2, y2), ...} and @code{[(x1, y1), (x2, y2), ...]}),
like @code{create_*()} methods.
(Contributed by Serhiy Storchaka in gh-94473@footnote{https://github.com/python/cpython/issues/94473}.)
@end itemize

@node tokenize,types<3>,tkinter<3>,改進的模組<2>
@anchor{whatsnew/3 12 tokenize}@anchor{6eb}
@subsubsection tokenize



@itemize *

@item 
The @ref{101,,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{6ec,,移植至 Python 3.12} for more information on the
changes to the @ref{101,,tokenize} module.
@end itemize

@node types<3>,typing<4>,tokenize,改進的模組<2>
@anchor{whatsnew/3 12 types}@anchor{6ed}
@subsubsection types



@itemize *

@item 
Add @ref{6ee,,types.get_original_bases()} to allow for further introspection of
@ref{6ef,,使用者定義泛型型別} 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<4>,unicodedata<3>,types<3>,改進的模組<2>
@anchor{whatsnew/3 12 typing}@anchor{6f0}@anchor{whatsnew/3 12 whatsnew-typing-py312}@anchor{6f1}
@subsubsection typing



@itemize *

@item 
@ref{2ad,,isinstance()} checks against
@ref{66d,,runtime-checkable protocols} now use
@ref{6b5,,inspect.getattr_static()} rather than @ref{6f2,,hasattr()} to lookup whether
attributes exist. This means that descriptors and @ref{6f3,,__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{2ad,,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)  # 沒有改變，即便 HasX 現在有 "y" 屬性
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{2ad,,isinstance()} checks against
@ref{66d,,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{331,,typing.TypedDict} and @ref{330,,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 
新增 @code{frozen_default} 參數至 @ref{6f4,,typing.dataclass_transform()}。（由 Erik De Bonte 於 gh-99957@footnote{https://github.com/python/cpython/issues/99957} 中貢獻。）
@end itemize

@node unicodedata<3>,unittest<3>,typing<4>,改進的模組<2>
@anchor{whatsnew/3 12 unicodedata}@anchor{6f5}
@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<3>,uuid<3>,unicodedata<3>,改進的模組<2>
@anchor{whatsnew/3 12 unittest}@anchor{6f6}
@subsubsection unittest


新增 @code{--durations} 命令列選項，顯示 N 個最慢的測試案例：

@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

（由 Giampaolo Rodola 於 gh-48330@footnote{https://github.com/python/cpython/issues/48330} 中貢獻。）

@node uuid<3>,,unittest<3>,改進的模組<2>
@anchor{whatsnew/3 12 uuid}@anchor{6f7}
@subsubsection uuid



@itemize *

@item 
新增一個@ref{66e,,命令列介面}。（由 Adam Chhina 於 gh-88597@footnote{https://github.com/python/cpython/issues/88597} 中貢獻。）
@end itemize

@node 最佳化<3>,CPython 位元組碼變更<3>,改進的模組<2>,Python 3 12 有什麼新功能
@anchor{whatsnew/3 12 optimizations}@anchor{6f8}
@subsection 最佳化



@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{59d,,re.sub()} and
@ref{59e,,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 
透過延遲運算較繁重的字串格式化來加速 @ref{1c7,,asyncio.Task} 的建立。（由 Itamar Oren 於 gh-103793@footnote{https://github.com/python/cpython/issues/103793} 中貢獻。）

@item 
The @ref{6f9,,tokenize.tokenize()} and @ref{6fa,,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{101,,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{1a6,,super()} method calls and attribute loads via the
new @ref{6fb,,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 位元組碼變更<3>,Demos and Tools,最佳化<3>,Python 3 12 有什麼新功能
@anchor{whatsnew/3 12 cpython-bytecode-changes}@anchor{6fc}
@subsection CPython 位元組碼變更



@itemize *

@item 
移除 @code{LOAD_METHOD} 指令。它已經合併至 @ref{6fd,,LOAD_ATTR}。@ref{6fd,,LOAD_ATTR} 現在會像舊的 @code{LOAD_METHOD} 指令一樣行為，如果其 oparg 的低位元 (low bit) 有被設定。（由 Ken Jin 於 gh-93429@footnote{https://github.com/python/cpython/issues/93429} 中貢獻。）

@item 
移除 @code{JUMP_IF_FALSE_OR_POP} 和 @code{JUMP_IF_TRUE_OR_POP} 指令。（由 Irit Katriel 於 gh-102859@footnote{https://github.com/python/cpython/issues/102859} 中貢獻。）

@item 
移除 @code{PRECALL} 指令。（由 Mark Shannon 於 gh-92925@footnote{https://github.com/python/cpython/issues/92925} 中貢獻。）

@item 
新增 @ref{6fe,,BINARY_SLICE} 和 @ref{6ff,,STORE_SLICE} 指令。（由 Mark Shannon 於 gh-94163@footnote{https://github.com/python/cpython/issues/94163} 中貢獻。）

@item 
新增 @ref{700,,CALL_INTRINSIC_1} 指令。（由 Mark Shannon 於 gh-99005@footnote{https://github.com/python/cpython/issues/99005} 中貢獻。）

@item 
新增 @ref{701,,CALL_INTRINSIC_2} 指令。（由 Irit Katriel 於 gh-101799@footnote{https://github.com/python/cpython/issues/101799} 中貢獻。）

@item 
新增 @ref{702,,CLEANUP_THROW} 指令。（由 Brandt Bucher 於 gh-90997@footnote{https://github.com/python/cpython/issues/90997} 中貢獻。）

@item 
新增 @code{END_SEND} 指令。（由 Mark Shannon 於 gh-103082@footnote{https://github.com/python/cpython/issues/103082} 中貢獻。）

@item 
新增 @ref{703,,LOAD_FAST_AND_CLEAR} 指令作為 
@geindex Python Enhancement Proposals; PEP 709
PEP 709@footnote{https://peps.python.org/pep-0709/} 實作的一部分。（由 Carl Meyer 於 gh-101441@footnote{https://github.com/python/cpython/issues/101441} 中貢獻。）

@item 
新增 @ref{704,,LOAD_FAST_CHECK} 指令。（由 Dennis Sweeney 於 gh-93143@footnote{https://github.com/python/cpython/issues/93143} 中貢獻。）

@item 
新增 @ref{705,,LOAD_FROM_DICT_OR_DEREF}、@ref{706,,LOAD_FROM_DICT_OR_GLOBALS} 和 @ref{707,,LOAD_LOCALS} 操作碼作為 
@geindex Python Enhancement Proposals; PEP 695
PEP 695@footnote{https://peps.python.org/pep-0695/} 實作的一部分。移除 @code{LOAD_CLASSDEREF} 操作碼，可以用 @ref{707,,LOAD_LOCALS} 加上 @ref{705,,LOAD_FROM_DICT_OR_DEREF} 來取代。（由 Jelle Zijlstra 於 gh-103764@footnote{https://github.com/python/cpython/issues/103764} 中貢獻。）

@item 
新增 @ref{6fb,,LOAD_SUPER_ATTR} 指令。（由 Carl Meyer 和 Vladimir Matveev 於 gh-103497@footnote{https://github.com/python/cpython/issues/103497} 中貢獻。）

@item 
新增 @code{RETURN_CONST} 指令。（由 Wenyang Wang 於 gh-101632@footnote{https://github.com/python/cpython/issues/101632} 中貢獻。）
@end itemize

@node Demos and Tools,已棄用<2>,CPython 位元組碼變更<3>,Python 3 12 有什麼新功能
@anchor{whatsnew/3 12 demos-and-tools}@anchor{708}
@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 已棄用<2>,已移除<2>,Demos and Tools,Python 3 12 有什麼新功能
@anchor{whatsnew/3 12 deprecated}@anchor{709}
@subsection 已棄用



@itemize *

@item 
@ref{7,,argparse}：@code{argparse.BooleanOptionalAction} 的 `type'、`choices' 和 `metavar' 參數已被棄用，將在 3.14 中移除。 (由 Nikita Sobolev 於 gh-92248@footnote{https://github.com/python/cpython/issues/92248} 貢獻。)

@item 
@ref{9,,ast}：以下 @ref{9,,ast} 功能自 Python 3.8 起已在文件中被棄用，現在在存取或使用時會在 runtime 發出 @ref{1a3,,DeprecationWarning}，並將在 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

請改用 @ref{2ee,,ast.Constant}。（由 Serhiy Storchaka 於 gh-90953@footnote{https://github.com/python/cpython/issues/90953} 貢獻。）

@item 
@ref{b,,asyncio}：


@itemize *

@item 
已棄用並將在 Python 3.14 中移除的 child watcher 類別：@code{asyncio.MultiLoopChildWatcher}、@code{asyncio.FastChildWatcher}、@code{asyncio.AbstractChildWatcher} 和 @code{asyncio.SafeChildWatcher}。 (由 Kumar Aditya 於 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()} 和 @code{asyncio.AbstractEventLoopPolicy.get_child_watcher()} 已被棄用並將在 Python 3.14 中移除。（由 Kumar Aditya 於 gh-94597@footnote{https://github.com/python/cpython/issues/94597} 貢獻。）

@item 
預設事件迴圈策略的 @ref{2f1,,get_event_loop()} 方法現在會在沒有設定目前事件迴圈且決定建立一個時發出 @ref{1a3,,DeprecationWarning}。 (由 Serhiy Storchaka 和 Guido van Rossum 於 gh-100160@footnote{https://github.com/python/cpython/issues/100160} 貢獻。)
@end itemize

@item 
@ref{15,,calendar}：@code{calendar.January} 和 @code{calendar.February} 常數已被棄用並被 @ref{34c,,calendar.JANUARY} 和 @ref{34d,,calendar.FEBRUARY} 取代。 (由 Prince Roshan 於 gh-103636@footnote{https://github.com/python/cpython/issues/103636} 貢獻。)

@item 
@ref{1f,,collections.abc}：棄用 @ref{341,,collections.abc.ByteString}。

使用 @code{isinstance(obj, collections.abc.Buffer)} 來測試 @code{obj} 是否在 runtime 實作了@ref{260,,緩衝區協定}。在型別註解的使用中，請用 @ref{342,,Buffer} 或明確指定你的程式碼所支援型別的聯集（例如 @code{bytes | bytearray | memoryview}）。

@code{ByteString} 最初被設計為一個抽象類別，以作為 @ref{192,,bytes} 和 @ref{343,,bytearray} 的超型別 (supertype)。然而由於 ABC 從未擁有任何方法，知道一個物件是 @code{ByteString} 的實例從未真正告訴你任何關於該物件的有用資訊。其他常見的緩衝區型別如 @ref{165,,memoryview} 也從未被理解為 @code{ByteString} 的子型別（無論是在 runtime 還是由靜態型別檢查器）。

更多細節請見 
@geindex Python Enhancement Proposals; PEP 688#current-options
PEP 688@footnote{https://peps.python.org/pep-0688/#current-options}。（由 Shantanu Jain 於 gh-91896@footnote{https://github.com/python/cpython/issues/91896} 貢獻。）

@item 
@ref{34,,datetime}: @ref{4dd,,datetime.datetime}'s @ref{34f,,utcnow()} and
@ref{350,,utcfromtimestamp()} are deprecated and will be
removed in a future version. Instead, use timezone-aware objects to represent
datetimes in UTC: respectively, call @ref{70a,,now()} and
@ref{70b,,fromtimestamp()}  with the `tz' parameter set to
@ref{70c,,datetime.UTC}.
(Contributed by Paul Ganssle in gh-103857@footnote{https://github.com/python/cpython/issues/103857}.)

@item 
@ref{3f,,email}：棄用 @ref{2f6,,email.utils.localtime()} 中的 `isdst' 參數。（由 Alan Williams 於 gh-72346@footnote{https://github.com/python/cpython/issues/72346} 中貢獻。）

@item 
@ref{7c,,importlib.abc}：棄用下列類別，預定於 Python 3.14 中移除：


@itemize *

@item 
@code{importlib.abc.ResourceReader}

@item 
@code{importlib.abc.Traversable}

@item 
@code{importlib.abc.TraversableResources}
@end itemize

請改用 @ref{80,,importlib.resources.abc} 類別：


@itemize *

@item 
@ref{2f9,,importlib.resources.abc.Traversable}

@item 
@ref{2f8,,importlib.resources.abc.TraversableResources}
@end itemize

（由 Jason R. Coombs 和 Hugo van Kemenade 貢獻於 gh-93963@footnote{https://github.com/python/cpython/issues/93963}。）

@item 
@ref{85,,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 @ref{98,,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{24a,,get_context()} or
@ref{24b,,set_start_method()} APIs to explicitly specify when
your code `requires' @code{'fork'}.  See @ref{1d5,,contexts and start methods}.

@item 
@ref{ae,,pkgutil}：@code{pkgutil.find_loader()} 和 @code{pkgutil.get_loader()} 已被棄用並將在 Python 3.14 中移除；請改用 @ref{5a9,,importlib.util.find_spec()}。（由 Nikita Sobolev 於 gh-97850@footnote{https://github.com/python/cpython/issues/97850} 中貢獻。）

@item 
@ref{b6,,pty}: The module has two undocumented @code{master_open()} and @code{slave_open()}
functions that have been deprecated since Python 2 but only gained a
proper @ref{1a3,,DeprecationWarning} in 3.12. Remove them in 3.14.
(Contributed by Soumendra Ganguly and Gregory P. Smith in gh-85984@footnote{https://github.com/python/cpython/issues/85984}.)

@item 
@ref{a5,,os}：


@itemize *

@item 
The @code{st_ctime} fields return by @ref{26d,,os.stat()} and @ref{6c1,,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{4b0,,os.fork()} can now raise a
@ref{1a3,,DeprecationWarning} when it can detect being called from a
multithreaded process. There has always been a fundamental incompatibility
with the POSIX platform when doing so. Even if such code `appeared' to work.
We added the warning to raise awareness as issues encountered by code doing
this are becoming more frequent. See the @ref{4b0,,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
@ref{98,,multiprocessing} start method such as @code{"spawn"} or @code{"forkserver"}.

@item 
@ref{ca,,shutil}：@ref{354,,shutil.rmtree()} 的 `onerror' 引數已被棄用，請改用 `onexc'。（由 Irit Katriel 於 gh-102828@footnote{https://github.com/python/cpython/issues/102828} 中貢獻。）

@item 
@ref{d4,,sqlite3}：


@itemize *

@item 
@ref{70d,,default adapters and converters} are now deprecated.
Instead, use the @ref{70e,,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{5aa,,execute()}, @ref{1a3,,DeprecationWarning} is now emitted
when @ref{5ac,,named placeholders} are used together with
parameters supplied as a @ref{70f,,sequence} instead of as a @ref{183,,dict}.
Starting from Python 3.14, using named placeholders with parameters supplied
as a sequence will raise a @ref{304,,ProgrammingError}.
(Contributed by Erlend E. Aasland in gh-101698@footnote{https://github.com/python/cpython/issues/101698}.)
@end itemize

@item 
@ref{df,,sys}：@ref{6df,,sys.last_type}、@ref{6e0,,sys.last_value} 和 @ref{6e1,,sys.last_traceback} 欄位已被棄用。請改用 @ref{6de,,sys.last_exc}。（由 Irit Katriel 於 gh-102778@footnote{https://github.com/python/cpython/issues/102778} 中貢獻。）

@item 
@ref{e4,,tarfile}: Extracting tar archives without specifying `filter' is deprecated until
Python 3.14, when @code{'data'} filter will become the default.
See @ref{690,,Extraction filters} for details.

@item 
@ref{10a,,typing}：


@itemize *

@item 
@ref{710,,typing.Hashable} and @ref{711,,typing.Sized}, aliases for
@ref{712,,collections.abc.Hashable} and @ref{713,,collections.abc.Sized} respectively, are
deprecated. (gh-94309@footnote{https://github.com/python/cpython/issues/94309}.)

@item 
自 Python 3.9 起已被棄用的 @ref{344,,typing.ByteString} 現在在使用時會發出 @ref{1a3,,DeprecationWarning}。（由 Alex Waygood 於 gh-91896@footnote{https://github.com/python/cpython/issues/91896} 中貢獻。）
@end itemize

@item 
@ref{12b,,xml.etree.ElementTree}: The module now emits @ref{1a3,,DeprecationWarning}
when testing the truth value of an @ref{361,,xml.etree.ElementTree.Element}.
Before, the Python implementation emitted @ref{651,,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{714,,coroutine throw()}, @ref{715,,generator throw()} and
@ref{716,,async generator throw()} are deprecated and
may be removed in a future version of Python. Use the single-arg versions
of these functions instead. (Contributed by Ofey Chan in gh-89874@footnote{https://github.com/python/cpython/issues/89874}.)

@item 
@ref{1a3,,DeprecationWarning} is now raised when @ref{322,,__package__} on a
module differs from
@ref{323,,__spec__.parent} (previously
it was @ref{717,,ImportWarning}).
(Contributed by Brett Cannon in gh-65961@footnote{https://github.com/python/cpython/issues/65961}.)

@item 
Setting @ref{322,,__package__} or @ref{320,,__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 
自 3.10 起，於程式碼物件存取 @ref{32f,,co_lnotab} 的功能已在 
@geindex Python Enhancement Proposals; PEP 626
PEP 626@footnote{https://peps.python.org/pep-0626/} 中被棄用，但只在 3.12 中於適時發出 @ref{1a3,,DeprecationWarning}。可能在 3.15 中移除。（由 Nikita Sobolev 於 gh-101866@footnote{https://github.com/python/cpython/issues/101866} 貢獻。）
@end itemize

@menu
* Python 3.13 中待移除的項目: Python 3 13 中待移除的項目. 
* Python 3.14 中待移除的項目: Python 3 14 中待移除的項目<3>. 
* Python 3.15 中待移除的項目: Python 3 15 中待移除的項目<5>. 
* Python 3.16 中待移除的項目: Python 3 16 中待移除的項目<5>. 
* Python 3.17 中待移除的項目: Python 3 17 中待移除的項目<3>. 
* 未來版本中的待移除項目: 未來版本中的待移除項目<5>. 

@end menu

@node Python 3 13 中待移除的項目,Python 3 14 中待移除的項目<3>,,已棄用<2>
@anchor{whatsnew/3 12 pending-removal-in-python-3-13}@anchor{718}
@subsubsection Python 3.13 中待移除的項目


模組（請見 
@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

其他模組：


@itemize *

@item 
@code{lib2to3} 和 @code{2to3} 程式 (gh-84540@footnote{https://github.com/python/cpython/issues/84540})
@end itemize

API：


@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{489,,classmethod} 描述器鏈接 (gh-89519@footnote{https://github.com/python/cpython/issues/89519})

@item 
@ref{7f,,importlib.resources} 的已棄用方法：


@itemize *

@item 
@code{contents()}

@item 
@code{is_resource()}

@item 
@code{open_binary()}

@item 
@code{open_text()}

@item 
@code{path()}

@item 
@code{read_binary()}

@item 
@code{read_text()}
@end itemize

請改用 @ref{6af,,importlib.resources.files()}。請參閱 importlib-resources: Migrating from Legacy@footnote{https://importlib-resources.readthedocs.io/en/latest/using.html#migrating-from-legacy} (gh-106531@footnote{https://github.com/python/cpython/issues/106531})
@end itemize

@node Python 3 14 中待移除的項目<3>,Python 3 15 中待移除的項目<5>,Python 3 13 中待移除的項目,已棄用<2>
@anchor{whatsnew/3 12 pending-removal-in-python-3-14}@anchor{719}
@subsubsection Python 3.14 中待移除的項目



@itemize *

@item 
@ref{7,,argparse}：@code{argparse.BooleanOptionalAction} 的 `type'、`choices' 和 `metavar' 參數已被棄用，將在 3.14 中移除。 (由 Nikita Sobolev 於 gh-92248@footnote{https://github.com/python/cpython/issues/92248} 貢獻。)

@item 
@ref{9,,ast}：自 Python 3.8 起，下列功能已在文件中被棄用，現在在存取或使用時會於 runtime 發出 @ref{1a3,,DeprecationWarning}，並將在 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

請改用 @ref{2ee,,ast.Constant}。（由 Serhiy Storchaka 於 gh-90953@footnote{https://github.com/python/cpython/issues/90953} 貢獻。）

@item 
@ref{b,,asyncio}：


@itemize *

@item 
已棄用並將在 Python 3.14 中移除的 child watcher 類別：@code{asyncio.MultiLoopChildWatcher}、@code{asyncio.FastChildWatcher}、@code{asyncio.AbstractChildWatcher} 和 @code{asyncio.SafeChildWatcher}。 (由 Kumar Aditya 於 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()} 和 @code{asyncio.AbstractEventLoopPolicy.get_child_watcher()} 已被棄用並將在 Python 3.14 中移除。（由 Kumar Aditya 於 gh-94597@footnote{https://github.com/python/cpython/issues/94597} 貢獻。）

@item 
預設事件迴圈策略的 @ref{2f1,,get_event_loop()} 方法現在會在沒有設定目前事件迴圈且決定建立一個時發出 @ref{1a3,,DeprecationWarning}。 (由 Serhiy Storchaka 和 Guido van Rossum 於 gh-100160@footnote{https://github.com/python/cpython/issues/100160} 貢獻。)
@end itemize

@item 
@ref{3f,,email}：已棄用 @ref{2f6,,email.utils.localtime()} 中的 `isdst' 參數。（由 Alan Williams 於 gh-72346@footnote{https://github.com/python/cpython/issues/72346} 貢獻。）

@item 
@ref{7c,,importlib.abc} 的已棄用類別：


@itemize *

@item 
@code{importlib.abc.ResourceReader}

@item 
@code{importlib.abc.Traversable}

@item 
@code{importlib.abc.TraversableResources}
@end itemize

請改用 @ref{80,,importlib.resources.abc} 類別：


@itemize *

@item 
@ref{2f9,,importlib.resources.abc.Traversable}

@item 
@ref{2f8,,importlib.resources.abc.TraversableResources}
@end itemize

（由 Jason R. Coombs 和 Hugo van Kemenade 貢獻於 gh-93963@footnote{https://github.com/python/cpython/issues/93963}。）

@item 
@ref{85,,itertools} 有不以文件記錄、效率低下、過去常有 bug 且不一致的 copy、deepcopy 和 pickle 操作支援。將在 3.14 中移除以大幅減少程式碼量和維護負擔。 (由 Raymond Hettinger 於 gh-101588@footnote{https://github.com/python/cpython/issues/101588} 貢獻。)

@item 
@ref{98,,multiprocessing}：預設的啟動方法將在 Linux、BSD 和其他非 macOS POSIX 平台上更改為更安全的 方法，目前 @code{'fork'} 是預設值 (gh-84559@footnote{https://github.com/python/cpython/issues/84559})。對此增加一個 runtime 警告被認為太過擾人，因為 大多數程式碼不會在意。請使用 @ref{24a,,get_context()} 或 @ref{24b,,set_start_method()} API 來明確指定你的程式碼何時`需要' @code{'fork'}。請參閱 @ref{1d5,,Contexts and start methods}。

@item 
@ref{a8,,pathlib}：已棄用 @ref{2fd,,is_relative_to()} 和 @ref{2fc,,relative_to()}：額外引數的傳遞已被棄用。

@item 
@ref{ae,,pkgutil}：@code{pkgutil.find_loader()} 和 @code{pkgutil.get_loader()} 現在會引發 @ref{1a3,,DeprecationWarning}；請改用 @ref{5a9,,importlib.util.find_spec()}。 (由 Nikita Sobolev 於 gh-97850@footnote{https://github.com/python/cpython/issues/97850} 貢獻。)

@item 
@ref{b6,,pty}：


@itemize *

@item 
@code{master_open()}：請用 @ref{300,,pty.openpty()}。

@item 
@code{slave_open()}：請用 @ref{300,,pty.openpty()}。
@end itemize

@item 
@ref{d4,,sqlite3}：


@itemize *

@item 
@code{version} 和 @code{version_info}。

@item 
@ref{5aa,,execute()} 和 @ref{5ab,,executemany()}，如果使用 @ref{5ac,,named placeholders} 且 `parameters' 是序列而不是 @ref{183,,dict}。
@end itemize

@item 
@ref{10e,,urllib}：@code{urllib.parse.Quoter} 已被棄用：它並非預期的公開 API。(由 Gregory P. Smith 於 gh-88168@footnote{https://github.com/python/cpython/issues/88168} 貢獻。)
@end itemize

@node Python 3 15 中待移除的項目<5>,Python 3 16 中待移除的項目<5>,Python 3 14 中待移除的項目<3>,已棄用<2>
@anchor{whatsnew/3 12 pending-removal-in-python-3-15}@anchor{71a}
@subsubsection Python 3.15 中待移除的項目



@itemize *

@item 
引入系統 (import system)：


@itemize *

@item 
在模組上設定 @ref{320,,__cached__} 而沒有設定 @ref{321,,__spec__.cached} 的做法已被棄用。在 Python 3.15 中，引入系統或標準函式庫將不再設定或考慮 @code{__cached__}。(gh-97879@footnote{https://github.com/python/cpython/issues/97879})

@item 
在模組上設定 @ref{322,,__package__} 而沒有設定 @ref{323,,__spec__.parent} 的做法已被棄用。在 Python 3.15 中，引入系統或標準函式庫將不再設定或考慮 @code{__package__}。(gh-97879@footnote{https://github.com/python/cpython/issues/97879})
@end itemize

@item 
@ref{2e,,ctypes}：


@itemize *

@item 
自 Python 3.13 起，未記錄的 @code{ctypes.SetPointerType()} 函式已被棄用。
@end itemize

@item 
@ref{76,,http.server}：


@itemize *

@item 
過時且很少使用的 @ref{324,,CGIHTTPRequestHandler} 自 Python 3.13 起已被棄用。不存在直接的替代。`任何東西'都比 CGI 更好地將 Web 伺服器與請求處理程序介接起來。

@item 
自 Python 3.13 起，@code{python -m http.server} 命令列介面的 @code{--cgi} 旗標已被棄用。
@end itemize

@item 
@ref{7b,,importlib}：


@itemize *

@item 
@code{load_module()} method：請改用 @code{exec_module()}。
@end itemize

@item 
@ref{8a,,locale}：


@itemize *

@item 
@ref{325,,getdefaultlocale()} 已在 Python 3.11 中被棄用，原本計劃在 Python 3.13 中移除 (gh-90817@footnote{https://github.com/python/cpython/issues/90817})，但被延後至 Python 3.15。請改用 @ref{326,,getlocale()}、@ref{327,,setlocale()} 和 @ref{328,,getencoding()}。 (由 Hugo van Kemenade 於 gh-111187@footnote{https://github.com/python/cpython/issues/111187} 貢獻。)
@end itemize

@item 
@ref{a8,,pathlib}：


@itemize *

@item 
@ref{329,,PurePath.is_reserved()} 已自 Python 3.13 被棄用。請用 @ref{32a,,os.path.isreserved()} 來偵測 Windows 上的保留路徑。
@end itemize

@item 
@ref{af,,platform}：


@itemize *

@item 
自 Python 3.13 起，@ref{32b,,java_ver()} 已被棄用。此函式僅對 Jython 支援有用，具有令人困惑的 API，基本上未經測試。
@end itemize

@item 
@ref{e1,,sysconfig}：


@itemize *

@item 
@ref{32c,,sysconfig.is_python_build()} 的 `check_home' 引數自 Python 3.12 起已被棄用。
@end itemize

@item 
@ref{f3,,threading}：


@itemize *

@item 
@ref{32d,,RLock()} 在 Python 3.15 中將不接受任何引數。自 Python 3.14 起，傳遞任何引數的用法已被棄用，因為 Python 版本不允許任何引數，但 C 版本允許任意數量的位置或關鍵字引數，並忽略每個引數。
@end itemize

@item 
@ref{109,,types}：


@itemize *

@item 
@ref{32e,,types.CodeType}：自 3.10 起，存取 @ref{32f,,co_lnotab} 已在 
@geindex Python Enhancement Proposals; PEP 626
PEP 626@footnote{https://peps.python.org/pep-0626/} 中被棄用，並計劃在 3.12 中移除，但只在 3.12 中於適當時發出 @ref{1a3,,DeprecationWarning}。可能在 3.15 中移除。（由 Nikita Sobolev 於 gh-101866@footnote{https://github.com/python/cpython/issues/101866} 貢獻。）
@end itemize

@item 
@ref{10a,,typing}：


@itemize *

@item 
用於建立 @ref{330,,NamedTuple} 類別的未以文件記錄之關鍵字引數語法 (@code{Point = NamedTuple("Point", x=int, y=int)}) 已自 Python 3.13 棄用。請改用基於類別的語法或函式語法 (functional syntax)。

@item 
當使用 @ref{331,,TypedDict} 的函式語法時，未傳遞值給 `fields' 參數 (@code{TD = TypedDict("TD")}) 或傳遞 @code{None} (@code{TD = TypedDict("TD", None)}) 的做法自 Python 3.13 起已被棄用。請使用 @code{class TD(TypedDict): pass} 或 @code{TD = TypedDict("TD", @{@})} 來建立具有零個欄位的 TypedDict。

@item 
自 Python 3.13 起，@ref{332,,typing.no_type_check_decorator()} 裝飾器函式已被棄用。在 @ref{10a,,typing} 模組中使用了八年之後，它尚未得到任何主要型別檢查器的支援。
@end itemize

@item 
@ref{119,,wave}：


@itemize *

@item 
已棄用 @ref{333,,Wave_read} 和 @ref{334,,Wave_write} 類別的 @ref{335,,getmark()}、@code{setmark()} 和 @ref{336,,getmarkers()} 方法自 Python 3.13 被棄用。
@end itemize

@item 
@ref{138,,zipimport}：


@itemize *

@item 
@ref{337,,load_module()} 自 Python 3.10 被棄用。請改用 @ref{338,,exec_module()}。（由 Jiahao Li 於 gh-125746@footnote{https://github.com/python/cpython/issues/125746} 貢獻。）
@end itemize
@end itemize

@node Python 3 16 中待移除的項目<5>,Python 3 17 中待移除的項目<3>,Python 3 15 中待移除的項目<5>,已棄用<2>
@anchor{whatsnew/3 12 pending-removal-in-python-3-16}@anchor{71b}
@subsubsection Python 3.16 中待移除的項目



@itemize *

@item 
引入系統 (import system)：


@itemize *

@item 
在模組上設定 @ref{33a,,__loader__} 而沒有設定 @ref{33b,,__spec__.loader} 的做法將於 Python 3.16 被棄用。在 Python 3.16 中，引入系統或標準函式庫將不再設定或考慮 @code{__loader__}。
@end itemize

@item 
@ref{8,,array}：


@itemize *

@item 
自 Python 3.3 起，@code{'u'} 格式碼 (@code{wchar_t}) 在文件中已被棄用，自 Python 3.13 起在 runtime 已被棄用。請使用 @code{'w'} 格式碼 (@ref{33c,,Py_UCS4}) 來取代 Unicode 字元。
@end itemize

@item 
@ref{b,,asyncio}：


@itemize *

@item 
@code{asyncio.iscoroutinefunction()} 已被棄用並將在 Python 3.16 中移除；請改用 @ref{30c,,inspect.iscoroutinefunction()}。（由 Jiahao Li 和 Kumar Aditya 於 gh-122875@footnote{https://github.com/python/cpython/issues/122875} 貢獻。）

@item 
@ref{b,,asyncio} 策略系統已被棄用並將在 Python 3.16 中移除。特別是以下類別和函式已被棄用：


@itemize *

@item 
@ref{30d,,asyncio.AbstractEventLoopPolicy}

@item 
@ref{30e,,asyncio.DefaultEventLoopPolicy}

@item 
@ref{30f,,asyncio.WindowsSelectorEventLoopPolicy}

@item 
@ref{310,,asyncio.WindowsProactorEventLoopPolicy}

@item 
@ref{311,,asyncio.get_event_loop_policy()}

@item 
@ref{312,,asyncio.set_event_loop_policy()}
@end itemize

使用者應該使用 @ref{2f2,,asyncio.run()} 或 @ref{2f4,,asyncio.Runner} 搭配 `loop_factory' 來使用所需的事件迴圈實作。

例如在 Windows 上使用 @ref{313,,asyncio.SelectorEventLoop}：

@example
import asyncio

async def main():
    ...

asyncio.run(main(), loop_factory=asyncio.SelectorEventLoop)
@end example

（由 Kumar Aditya 於 gh-127949@footnote{https://github.com/python/cpython/issues/127949} 貢獻。）
@end itemize

@item 
@ref{13,,builtins}：


@itemize *

@item 
自 Python 3.12 起，布林型別的位元反轉 @code{~True} 或 @code{~False} 已被棄用，因為它會產生不預期且不直觀的結果（@code{-2} 和 @code{-1}）。使用 @code{not x} 代替布林值的邏輯否定。在極少數情況下，你需要對底層的整數進行位元反轉，請明確轉換為 @code{~int(x)} (@code{~int(x)})。
@end itemize

@item 
@ref{63,,functools}：


@itemize *

@item 
自 Python 3.14 起，使用 `function' 或 `sequence' 關鍵字引數呼叫 @ref{21a,,functools.reduce()} 的 Python 實作已被棄用。
@end itemize

@item 
@ref{8b,,logging}：

對具有 `strm' 引數的自訂日誌記錄處理函式的支援已被棄用，並計劃在 Python 3.16 中移除。請改用 `stream' 引數。（由 Mariusz Felisiak 於 gh-115032@footnote{https://github.com/python/cpython/issues/115032} 貢獻。）

@item 
@ref{93,,mimetypes}：


@itemize *

@item 
有效的副檔名以 '.' 開頭或對 @ref{318,,mimetypes.MimeTypes.add_type()} 為空字串。未加點的副檔名已被棄用，並將在 Python 3.16 中引發 @ref{2eb,,ValueError}。（由 Hugo van Kemenade 於 gh-75223@footnote{https://github.com/python/cpython/issues/75223} 貢獻。）
@end itemize

@item 
@ref{ca,,shutil}：


@itemize *

@item 
自 Python 3.14 起，@code{ExecError} 例外已被棄用。自 Python 3.4 以來，它尚未被 @code{shutil} 中的任何函式使用，現在是 @ref{244,,RuntimeError} 的別名。
@end itemize

@item 
@ref{de,,symtable}：


@itemize *

@item 
自 Python 3.14 起，@ref{31c,,Class.get_methods} 方法已被棄用。
@end itemize

@item 
@ref{df,,sys}：


@itemize *

@item 
自 Python 3.13 起，@ref{33d,,_enablelegacywindowsfsencoding()} 函式已被棄用。請改用 
@geindex PYTHONLEGACYWINDOWSFSENCODING
@geindex 環境變數; PYTHONLEGACYWINDOWSFSENCODING
@ref{33e,,PYTHONLEGACYWINDOWSFSENCODING} 環境變數。
@end itemize

@item 
@ref{e1,,sysconfig}：


@itemize *

@item 
自 Python 3.14 起，@code{sysconfig.expand_makefile_vars()} 函式已被棄用。請改用 @ref{33f,,sysconfig.get_paths()} 的 @code{vars} 引數。
@end itemize

@item 
@ref{e4,,tarfile}：


@itemize *

@item 
自 Python 3.13 起，未以文件記錄和未被使用的 @code{TarFile.tarfile} 屬性已被棄用。
@end itemize
@end itemize

@node Python 3 17 中待移除的項目<3>,未來版本中的待移除項目<5>,Python 3 16 中待移除的項目<5>,已棄用<2>
@anchor{whatsnew/3 12 pending-removal-in-python-3-17}@anchor{71c}
@subsubsection Python 3.17 中待移除的項目



@itemize *

@item 
@ref{1f,,collections.abc}：


@itemize -

@item 
@ref{341,,collections.abc.ByteString} 預計在 Python 3.17 中移除。

使用 @code{isinstance(obj, collections.abc.Buffer)} 來測試 @code{obj} 是否在 runtime 實作了@ref{260,,緩衝區協定}。在型別註解的使用中，請用 @ref{342,,Buffer} 或明確指定你的程式碼所支援型別的聯集（例如 @code{bytes | bytearray | memoryview}）。

@code{ByteString} 最初被設計為一個抽象類別，以作為 @ref{192,,bytes} 和 @ref{343,,bytearray} 的超型別 (supertype)。然而由於 ABC 從未擁有任何方法，知道一個物件是 @code{ByteString} 的實例從未真正告訴你任何關於該物件的有用資訊。其他常見的緩衝區型別如 @ref{165,,memoryview} 也從未被理解為 @code{ByteString} 的子型別（無論是在 runtime 還是由靜態型別檢查器）。

更多細節請見 
@geindex Python Enhancement Proposals; PEP 688#current-options
PEP 688@footnote{https://peps.python.org/pep-0688/#current-options}。（由 Shantanu Jain 於 gh-91896@footnote{https://github.com/python/cpython/issues/91896} 貢獻。）
@end itemize

@item 
@ref{10a,,typing}：


@itemize -

@item 
在 Python 3.14 之前，舊式聯集是使用私有類別 @code{typing._UnionGenericAlias} 實作的。這個類別不再被需要，但為了向後相容性而保留，並計劃將在 Python 3.17 中移除。使用者應該改用文件中記錄的內省輔助函式，例如 @ref{2ab,,typing.get_origin()} 和 @ref{2ac,,typing.get_args()}，或者依賴私有實作細節。

@item 
@ref{344,,typing.ByteString} 自 Python 3.9 起已被棄用，預計在 Python 3.17 中移除。

使用 @code{isinstance(obj, collections.abc.Buffer)} 來測試 @code{obj} 是否在 runtime 實作了@ref{260,,緩衝區協定}。在型別註解的使用中，請用 @ref{342,,Buffer} 或明確指定你的程式碼所支援型別的聯集（例如 @code{bytes | bytearray | memoryview}）。

@code{ByteString} 最初被設計為一個抽象類別，以作為 @ref{192,,bytes} 和 @ref{343,,bytearray} 的超型別 (supertype)。然而由於 ABC 從未擁有任何方法，知道一個物件是 @code{ByteString} 的實例從未真正告訴你任何關於該物件的有用資訊。其他常見的緩衝區型別如 @ref{165,,memoryview} 也從未被理解為 @code{ByteString} 的子型別（無論是在 runtime 還是由靜態型別檢查器）。

更多細節請見 
@geindex Python Enhancement Proposals; PEP 688#current-options
PEP 688@footnote{https://peps.python.org/pep-0688/#current-options}。（由 Shantanu Jain 於 gh-91896@footnote{https://github.com/python/cpython/issues/91896} 貢獻。）
@end itemize
@end itemize

@node 未來版本中的待移除項目<5>,,Python 3 17 中待移除的項目<3>,已棄用<2>
@anchor{whatsnew/3 12 pending-removal-in-future-versions}@anchor{71d}
@subsubsection 未來版本中的待移除項目


以下 API 將在未來被移除，雖然目前尚未安排移除日期。


@itemize *

@item 
@ref{7,,argparse}：


@itemize *

@item 
巢狀引數群組和巢狀互斥群組已被棄用。

@item 
將未以文件記錄的關鍵字引數 `prefix_chars' 傳遞給 @ref{2ea,,add_argument_group()} 的做法現在已被棄用。

@item 
@ref{30b,,argparse.FileType} 型別轉換器已被棄用。
@end itemize

@item 
@ref{13,,builtins}：


@itemize *

@item 
產生器：@code{throw(type, exc, tb)} 和 @code{athrow(type, exc, tb)} 簽名已被棄用：請改用 @code{throw(exc)} 和 @code{athrow(exc)}，為單引數簽名。

@item 
目前 Python 接受數值字面值後面立即接關鍵字，例如 @code{0in x}、@code{1or x}、@code{0if 1else 2}。它讓運算式模糊且容易混淆，如 @code{[0x1for x in y]}（可以解釋為 @code{[0x1 for x in y]} 或 @code{[0x1f or x in y]}）。如果數值字面值後立即接 @ref{347,,and}、@ref{17c,,else}、@ref{348,,for}、@ref{181,,if}、@ref{349,,in}、@ref{34a,,is} 和 @ref{34b,,or} 之一的關鍵字，則會引發語法警告。在未來版本中，它將被更改為語法錯誤。(gh-87999@footnote{https://github.com/python/cpython/issues/87999})

@item 
@code{__index__()} 和 @code{__int__()} 方法回傳非 int 型別的支援：這些方法將需要回傳 @ref{19b,,int} 的嚴格子類別實例。

@item 
回傳 @ref{196,,float} 嚴格子類別 @code{__float__()} 方法的支援：這些方法將需要回傳 @ref{196,,float} 的實例。

@item 
回傳 @ref{197,,complex} 嚴格子類別 @code{__complex__()} 方法的支援：這些方法將需要回傳 @ref{197,,complex} 的實例。

@item 
將 @code{int()} 委派給 @code{__trunc__()} 方法。

@item 
在 @ref{197,,complex()} 建構子中將複數作為 `real' 或 `imag' 引數傳遞現在已被棄用；它應該只作為單個位置引數傳遞。 (由 Serhiy Storchaka 於 gh-109218@footnote{https://github.com/python/cpython/issues/109218} 貢獻。)
@end itemize

@item 
@ref{15,,calendar}：@code{calendar.January} 和 @code{calendar.February} 常數已被棄用並被 @ref{34c,,calendar.JANUARY} 和 @ref{34d,,calendar.FEBRUARY} 取代。 (由 Prince Roshan 於 gh-103636@footnote{https://github.com/python/cpython/issues/103636} 貢獻。)

@item 
@ref{1c,,codecs}：請改用 @ref{315,,open()} 而非 @ref{314,,codecs.open()}。(gh-133038@footnote{https://github.com/python/cpython/issues/133038})

@item 
@ref{32f,,codeobject.co_lnotab}：請改用 @ref{34e,,codeobject.co_lines()} 方法。

@item 
@ref{34,,datetime}：


@itemize *

@item 
@ref{34f,,utcnow()}：請改用 @code{datetime.datetime.now(tz=datetime.UTC)}。

@item 
@ref{350,,utcfromtimestamp()}：請改用 @code{datetime.datetime.fromtimestamp(timestamp, tz=datetime.UTC)}。
@end itemize

@item 
@ref{67,,gettext}：複數值必須是整數。

@item 
@ref{7b,,importlib}：


@itemize *

@item 
@ref{351,,cache_from_source()} `debug_override' 參數已被棄用：請改用 `optimization' 參數。
@end itemize

@item 
@ref{7e,,importlib.metadata}：


@itemize *

@item 
@code{EntryPoints} 元組介面。

@item 
回傳值上的隱式 @code{None}。
@end itemize

@item 
@ref{8b,,logging}：自 Python 3.3 起，@code{warn()} 方法已被棄用，請改用 @ref{352,,warning()}。

@item 
@ref{8f,,mailbox}：已棄用 StringIO 輸入和文本模式，請改用 BytesIO 和二進位模式。

@item 
@ref{a5,,os}：在多執行緒行程中呼叫 @ref{353,,os.register_at_fork()}。

@item 
@code{pydoc.ErrorDuringImport}：`exc_info' 參數的元組值已被棄用，請用例外實例。

@item 
@ref{be,,re}：現在對正規表示式中的數值群組參照和群組名稱用了更嚴格的規則。現在只有 ASCII 數碼序列被接受作為數值參照。位元組模式和替換字串中的群組名稱現在只能包含 ASCII 字母、數碼和底線。（由 Serhiy Storchaka 於 gh-91760@footnote{https://github.com/python/cpython/issues/91760} 貢獻。）

@item 
@code{sre_compile}、@code{sre_constants} 和 @code{sre_parse} 模組。

@item 
@ref{ca,,shutil}：@ref{354,,rmtree()} 的 `onerror' 參數在 Python 3.12 中已被棄用；請改用 `onexc' 參數。

@item 
@ref{d5,,ssl} 選項和協定：


@itemize *

@item 
不帶協定引數的 @ref{355,,ssl.SSLContext} 已被棄用。

@item 
@ref{355,,ssl.SSLContext}：@ref{356,,set_npn_protocols()} 和 @code{selected_npn_protocol()} 已被棄用：請改用 ALPN。

@item 
@code{ssl.OP_NO_SSL*} 選項

@item 
@code{ssl.OP_NO_TLS*} 選項

@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{f3,,threading} 方法：


@itemize *

@item 
@code{threading.Condition.notifyAll()}：請用 @ref{357,,notify_all()}。

@item 
@code{threading.Event.isSet()}：請用 @ref{358,,is_set()}。

@item 
@code{threading.Thread.isDaemon()}、@ref{359,,threading.Thread.setDaemon()}：請用 @ref{35a,,threading.Thread.daemon} 屬性。

@item 
@code{threading.Thread.getName()}、@ref{35b,,threading.Thread.setName()}：請用 @ref{2a0,,threading.Thread.name} 屬性。

@item 
@code{threading.currentThread()}：請用 @ref{35c,,threading.current_thread()}。

@item 
@code{threading.activeCount()}：請用 @ref{35d,,threading.active_count()}。
@end itemize

@item 
@ref{35e,,typing.Text} (gh-92332@footnote{https://github.com/python/cpython/issues/92332})。

@item 
內部類別 @code{typing._UnionGenericAlias} 不再用於實作 @ref{2a8,,typing.Union}。為了保持與此私有類別使用者的相容性，直到至少 Python 3.17 都將提供一個相容性 shim。（由 Jelle Zijlstra 於 gh-105499@footnote{https://github.com/python/cpython/issues/105499} 貢獻。）

@item 
@ref{35f,,unittest.IsolatedAsyncioTestCase}：從測試案例中回傳非 @code{None} 的值已被棄用。

@item 
@ref{110,,urllib.parse} 已棄用函式：請改用 @ref{360,,urlparse()}。


@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{11e,,wsgiref}：@code{SimpleHandler.stdout.write()} 不應該進行部分寫入。

@item 
@ref{12b,,xml.etree.ElementTree}：已棄用對 @ref{361,,Element} 的真值測試。在未來版本中，它將始終回傳 @code{True}。請改用明確的 @code{len(elem)} 或 @code{elem is not None} 測試。

@item 
@ref{292,,sys._clear_type_cache()} 已被棄用：請改用 @ref{362,,sys._clear_internal_caches()}。
@end itemize

@node 已移除<2>,移植至 Python 3 12,已棄用<2>,Python 3 12 有什麼新功能
@anchor{whatsnew/3 12 removed}@anchor{71e}@anchor{whatsnew/3 12 whatsnew312-removed}@anchor{71f}
@subsection 已移除


@menu
* asynchat 和 asyncore:: 
* configparser: configparser<4>. 
* distutils:: 
* ensurepip:: 
* enum: enum<2>. 
* ftplib:: 
* gzip:: 
* hashlib:: 
* importlib: importlib<2>. 
* imp:: 
* io: io<4>. 
* locale: locale<2>. 
* smtpd:: 
* sqlite3: sqlite3<4>. 
* ssl: ssl<3>. 
* unittest: unittest<4>. 
* webbrowser: webbrowser<3>. 
* xml.etree.ElementTree: xml etree ElementTree. 
* zipimport: zipimport<2>. 
* 其他:: 

@end menu

@node asynchat 和 asyncore,configparser<4>,,已移除<2>
@anchor{whatsnew/3 12 asynchat-and-asyncore}@anchor{720}
@subsubsection asynchat 和 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 和 asyncore,已移除<2>
@anchor{whatsnew/3 12 configparser}@anchor{721}
@subsubsection configparser



@itemize *

@item 
根據 gh-89336@footnote{https://github.com/python/cpython/issues/89336}，已移除了在 3.2 中被 @ref{26,,configparser} 棄用的幾個名稱：


@itemize *

@item 
@ref{722,,configparser.ParsingError} 不再具有 @code{filename} 屬性或引數。請改用 @code{source} 屬性和引數。

@item 
@ref{26,,configparser} 不再具有 @code{SafeConfigParser} 類別。請改用較短的 @ref{4d9,,ConfigParser} 名稱。

@item 
@ref{4d9,,configparser.ConfigParser} 不再具有 @code{readfp} 方法。請改用 @ref{723,,read_file()}。
@end itemize
@end itemize

@node distutils,ensurepip,configparser<4>,已移除<2>
@anchor{whatsnew/3 12 distutils}@anchor{724}@anchor{whatsnew/3 12 whatsnew312-removed-distutils}@anchor{725}
@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,已移除<2>
@anchor{whatsnew/3 12 ensurepip}@anchor{726}
@subsubsection ensurepip



@itemize *

@item 
Remove the bundled setuptools wheel from @ref{59,,ensurepip},
and stop installing setuptools in environments created by @ref{117,,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).

（由 Pradyun Gedam 於 gh-95299@footnote{https://github.com/python/cpython/issues/95299} 中貢獻。）
@end itemize

@node enum<2>,ftplib,ensurepip,已移除<2>
@anchor{whatsnew/3 12 enum}@anchor{727}
@subsubsection enum



@itemize *

@item 
移除 @ref{5a,,enum} 的 @code{EnumMeta.__getattr__}，對於列舉屬性的存取不再會需要它。
@end itemize

@node ftplib,gzip,enum<2>,已移除<2>
@anchor{whatsnew/3 12 ftplib}@anchor{728}
@subsubsection ftplib



@itemize *

@item 
移除 @ref{62,,ftplib} 的 @code{FTP_TLS.ssl_version} 類別屬性：請改用 `context' 參數。（由 Victor Stinner 於 gh-94172@footnote{https://github.com/python/cpython/issues/94172} 中貢獻。）
@end itemize

@node gzip,hashlib,ftplib,已移除<2>
@anchor{whatsnew/3 12 gzip}@anchor{729}
@subsubsection gzip



@itemize *

@item 
Remove the @code{filename} attribute of @ref{6b,,gzip}'s @ref{654,,gzip.GzipFile},
deprecated since Python 2.6, use the @ref{72a,,name} attribute
instead. In write mode, the @code{filename} attribute added @code{'.gz'} file
extension if it was not present.
(Contributed by Victor Stinner in gh-94196@footnote{https://github.com/python/cpython/issues/94196}.)
@end itemize

@node hashlib,importlib<2>,gzip,已移除<2>
@anchor{whatsnew/3 12 hashlib}@anchor{72b}
@subsubsection hashlib



@itemize *

@item 
Remove the pure Python implementation of @ref{6c,,hashlib}'s
@ref{72c,,hashlib.pbkdf2_hmac()}, deprecated in Python 3.10. Python 3.10 and
newer requires OpenSSL 1.1.1 (
@geindex Python Enhancement Proposals; PEP 644
PEP 644@footnote{https://peps.python.org/pep-0644/}): this OpenSSL version provides
a C implementation of @ref{72c,,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>
@anchor{whatsnew/3 12 importlib}@anchor{72d}
@subsubsection importlib



@itemize *

@item 
現已完成清理 @ref{7b,,importlib} 中許多過去已經棄用的東西：


@itemize *

@item 
對 @code{module_repr()} 的參照和支援已刪除。（由 Barry Warsaw 在 gh-97850@footnote{https://github.com/python/cpython/issues/97850} 中貢獻。）

@item 
@code{importlib.util.set_package}、@code{importlib.util.set_loader} 和 @code{importlib.util.module_for_loader} 已全部刪除。（由 Brett Cannon 和 Nikita Sobolev 在 gh-65961@footnote{https://github.com/python/cpython/issues/65961} 和 gh-97850@footnote{https://github.com/python/cpython/issues/97850} 貢獻。）

@item 
對 @code{find_loader()} 和 @code{find_module()} API 的支援已被刪除。（由 Barry Warsaw 在 gh-98040@footnote{https://github.com/python/cpython/issues/98040} 中貢獻。）

@item 
@code{importlib.abc.Finder}、@code{pkgutil.ImpImporter} 和 @code{pkgutil.ImpLoader} 已被刪除。（由 Barry Warsaw 在 gh-98040@footnote{https://github.com/python/cpython/issues/98040} 中貢獻。）
@end itemize
@end itemize

@node imp,io<4>,importlib<2>,已移除<2>
@anchor{whatsnew/3 12 imp}@anchor{72e}@anchor{whatsnew/3 12 whatsnew312-removed-imp}@anchor{72f}
@subsubsection imp



@itemize *

@item 
@code{imp} 模組已被移除。（由 Barry Warsaw 在 gh-98040@footnote{https://github.com/python/cpython/issues/98040} 中貢獻。）

要遷移的話請參考以下對應表：

@quotation


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

imp

@tab

importlib

@item

@code{imp.NullImporter}

@tab

將 @code{None} 插入 @code{sys.path_importer_cache}

@item

@code{imp.cache_from_source()}

@tab

@ref{351,,importlib.util.cache_from_source()}

@item

@code{imp.find_module()}

@tab

@ref{5a9,,importlib.util.find_spec()}

@item

@code{imp.get_magic()}

@tab

@ref{730,,importlib.util.MAGIC_NUMBER}

@item

@code{imp.get_suffixes()}

@tab

@ref{731,,importlib.machinery.SOURCE_SUFFIXES}、@ref{732,,importlib.machinery.EXTENSION_SUFFIXES} 和 @ref{733,,importlib.machinery.BYTECODE_SUFFIXES}

@item

@code{imp.get_tag()}

@tab

@ref{734,,sys.implementation.cache_tag}

@item

@code{imp.load_module()}

@tab

@ref{735,,importlib.import_module()}

@item

@code{imp.new_module(name)}

@tab

@code{types.ModuleType(name)}

@item

@code{imp.reload()}

@tab

@ref{736,,importlib.reload()}

@item

@code{imp.source_from_cache()}

@tab

@ref{737,,importlib.util.source_from_cache()}

@item

@code{imp.load_source()}

@tab

`見下文'

@end multitable

@end quotation

用以下取代 @code{imp.load_source()}：

@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)
    # 此模組都會被執行且不會被快取於 sys.modules。
    # 要快取模組的話可以把下面一行取消註解
    # sys.modules[module.__name__] = module
    loader.exec_module(module)
    return module
@end example

@item 
移除 @code{imp} 函式和屬性、沒有替代方案：


@itemize *

@item 
未以文件記錄的函式：


@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()} 常數：@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<2>,imp,已移除<2>
@anchor{whatsnew/3 12 io}@anchor{738}
@subsubsection io



@itemize *

@item 
Remove @ref{83,,io}'s @code{io.OpenWrapper} and @code{_pyio.OpenWrapper}, deprecated in Python
3.10: just use @ref{315,,open()} instead. The @ref{315,,open()} (@ref{739,,io.open()})
function is a built-in function. Since Python 3.10, @code{_pyio.open()} is
also a static method.
(Contributed by Victor Stinner in gh-94169@footnote{https://github.com/python/cpython/issues/94169}.)
@end itemize

@node locale<2>,smtpd,io<4>,已移除<2>
@anchor{whatsnew/3 12 locale}@anchor{73a}
@subsubsection locale



@itemize *

@item 
Remove @ref{8a,,locale}'s @code{locale.format()} function, deprecated in Python 3.7:
use @ref{73b,,locale.format_string()} instead.
(Contributed by Victor Stinner in gh-94226@footnote{https://github.com/python/cpython/issues/94226}.)
@end itemize

@node smtpd,sqlite3<4>,locale<2>,已移除<2>
@anchor{whatsnew/3 12 smtpd}@anchor{73c}
@subsubsection smtpd



@itemize *

@item 
根據 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/} 的時間表移除 @code{smtpd} 模組，它在 Python 3.4.7 和 3.5.4 中已被棄用。請改用 PyPI 上的 aiosmtpd@footnote{https://pypi.org/project/aiosmtpd/} 模組或任何其他基於 @ref{b,,asyncio} 的伺服器。
@end itemize

@node sqlite3<4>,ssl<3>,smtpd,已移除<2>
@anchor{whatsnew/3 12 id2}@anchor{73d}
@subsubsection sqlite3



@itemize *

@item 
以下未以文件記錄的 @ref{d4,,sqlite3} 功能已在 Python 3.10 中被棄用、現在已被移除：


@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{169,,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}.

（由 Erlend E. Aasland 於 gh-92548@footnote{https://github.com/python/cpython/issues/92548} 中貢獻。）
@end itemize

@node ssl<3>,unittest<4>,sqlite3<4>,已移除<2>
@anchor{whatsnew/3 12 ssl}@anchor{73e}
@subsubsection ssl



@itemize *

@item 
Remove @ref{d5,,ssl}'s @code{ssl.RAND_pseudo_bytes()} function, deprecated in Python 3.6:
use @ref{73f,,os.urandom()} or @ref{740,,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{355,,ssl.SSLContext} object and call its
@ref{741,,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<4>,webbrowser<3>,ssl<3>,已移除<2>
@anchor{whatsnew/3 12 id3}@anchor{742}
@subsubsection unittest



@itemize *

@item 
移除許多 @ref{10c,,unittest} 中被棄用已久的功能：
@anchor{whatsnew/3 12 unittest-testcase-removed-aliases}@anchor{677}

@itemize *

@item 
許多 @ref{2b3,,TestCase} 方法別名：


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxx} 
@headitem

已棄用的別名

@tab

方法名稱

@tab

已棄用於

@item

@code{failUnless}

@tab

@ref{743,,assertTrue()}

@tab

3.1

@item

@code{failIf}

@tab

@ref{744,,assertFalse()}

@tab

3.1

@item

@code{failUnlessEqual}

@tab

@ref{745,,assertEqual()}

@tab

3.1

@item

@code{failIfEqual}

@tab

@ref{746,,assertNotEqual()}

@tab

3.1

@item

@code{failUnlessAlmostEqual}

@tab

@ref{747,,assertAlmostEqual()}

@tab

3.1

@item

@code{failIfAlmostEqual}

@tab

@ref{748,,assertNotAlmostEqual()}

@tab

3.1

@item

@code{failUnlessRaises}

@tab

@ref{749,,assertRaises()}

@tab

3.1

@item

@code{assert_}

@tab

@ref{743,,assertTrue()}

@tab

3.2

@item

@code{assertEquals}

@tab

@ref{745,,assertEqual()}

@tab

3.2

@item

@code{assertNotEquals}

@tab

@ref{746,,assertNotEqual()}

@tab

3.2

@item

@code{assertAlmostEquals}

@tab

@ref{747,,assertAlmostEqual()}

@tab

3.2

@item

@code{assertNotAlmostEquals}

@tab

@ref{748,,assertNotAlmostEqual()}

@tab

3.2

@item

@code{assertRegexpMatches}

@tab

@ref{74a,,assertRegex()}

@tab

3.2

@item

@code{assertRaisesRegexp}

@tab

@ref{74b,,assertRaisesRegex()}

@tab

3.2

@item

@code{assertNotRegexpMatches}

@tab

@ref{74c,,assertNotRegex()}

@tab

3.5

@end multitable


你可以使用 @indicateurl{https://github.com/isidentical/teyit} 來自動現代化你的單元測試。

@item 
未以文件記錄且已失效的 @ref{2b3,,TestCase} 方法 @code{assertDictContainsSubset}（自 Python 3.2 起已棄用）。

@item 
Undocumented @ref{58e,,TestLoader.loadTestsFromModule} parameter `use_load_tests'
(deprecated and ignored since Python 3.5).

@item 
對 @ref{74d,,TextTestResult} 類別的別名：@code{_TextTestResult}（自 Python 3.2 起已棄用）。
@end itemize

（由 Serhiy Storchaka 於 gh-89325@footnote{https://github.com/python/cpython/issues/89325} 中貢獻。）
@end itemize

@node webbrowser<3>,xml etree ElementTree,unittest<4>,已移除<2>
@anchor{whatsnew/3 12 webbrowser}@anchor{74e}
@subsubsection webbrowser



@itemize *

@item 
Remove support for obsolete browsers from @ref{11b,,webbrowser}.
The removed browsers include: Grail, Mosaic, Netscape, Galeon, Skipstone,
Iceape, Firebird, and Firefox versions 35 and below (gh-102871@footnote{https://github.com/python/cpython/issues/102871}).
@end itemize

@node xml etree ElementTree,zipimport<2>,webbrowser<3>,已移除<2>
@anchor{whatsnew/3 12 xml-etree-elementtree}@anchor{74f}
@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{750,,copy.copy()} function instead.  The C implementation of @ref{12b,,xml.etree.ElementTree}
has no @code{copy()} method, only a @code{__copy__()} method.
(Contributed by Victor Stinner in gh-94383@footnote{https://github.com/python/cpython/issues/94383}.)
@end itemize

@node zipimport<2>,其他,xml etree ElementTree,已移除<2>
@anchor{whatsnew/3 12 zipimport}@anchor{751}
@subsubsection zipimport



@itemize *

@item 
Remove @ref{138,,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 其他,,zipimport<2>,已移除<2>
@anchor{whatsnew/3 12 others}@anchor{752}
@subsubsection 其他



@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{62,,ftplib}, @ref{78,,imaplib}, @ref{b1,,poplib} and @ref{cf,,smtplib} modules,
and the `key_file', `cert_file' and `check_hostname' parameters from the
@ref{73,,http.client} module,
all deprecated since Python 3.6. Use the `context' parameter
(`ssl_context' in @ref{78,,imaplib}) instead.
(Contributed by Victor Stinner in gh-94172@footnote{https://github.com/python/cpython/issues/94172}.)

@item 
移除數個標準函式庫模組與測試中的 @code{Jython} 相容性修補程式。（由 Nikita Sobolev 於 gh-99482@footnote{https://github.com/python/cpython/issues/99482} 中貢獻。）

@item 
移除 @ref{2e,,ctypes} 模組中的 @code{_use_broken_old_ctypes_structure_semantics_} 旗標。（由 Nikita Sobolev 於 gh-99285@footnote{https://github.com/python/cpython/issues/99285} 中貢獻。）
@end itemize

@node 移植至 Python 3 12,建置變更<3>,已移除<2>,Python 3 12 有什麼新功能
@anchor{whatsnew/3 12 porting-to-python-3-12}@anchor{753}@anchor{whatsnew/3 12 whatsnew312-porting-to-python312}@anchor{6ec}
@subsection 移植至 Python 3.12


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

@menu
* Python API 的變更: Python API 的變更<3>. 

@end menu

@node Python API 的變更<3>,,,移植至 Python 3 12
@anchor{whatsnew/3 12 changes-in-the-python-api}@anchor{754}
@subsubsection 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{198,,TypeError}. Also, the exception raised for non-integer values such as
@code{randrange(10.5)} or @code{randrange('10')} has been changed from @ref{2eb,,ValueError} to
@ref{198,,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{1bd,,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{755,,locale.getpreferredencoding(False)})
to @ref{756,,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{757,,shlex.split()}: Passing @code{None} for `s' argument now raises an
exception, rather than reading @ref{758,,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{343,,bytearray} and @ref{165,,memoryview} types: only the exact
@ref{192,,bytes} type is accepted for bytes strings.
(Contributed by Victor Stinner in gh-98393@footnote{https://github.com/python/cpython/issues/98393}.)

@item 
@ref{759,,syslog.openlog()} and @ref{75a,,syslog.closelog()} now fail if used in subinterpreters.
@ref{75b,,syslog.syslog()} may still be used in subinterpreters,
but now only if @ref{759,,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{e2,,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{75c,,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{6e2,,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{e4,,tarfile} or
@ref{68f,,shutil.unpack_archive()}, pass the `filter' argument to limit features
that may be surprising or dangerous.
See @ref{690,,Extraction filters} for details.

@item 
The output of the @ref{6f9,,tokenize.tokenize()} and @ref{6fa,,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{75d,,tokenize.TokenError} as incomplete
multiline strings do.

@item 
Some incomplete or invalid Python code now raises @ref{75d,,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{75e,,TabError}.
@end itemize

@item 
The @ref{f3,,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 建置變更<3>,C API 變更<3>,移植至 Python 3 12,Python 3 12 有什麼新功能
@anchor{whatsnew/3 12 build-changes}@anchor{75f}
@subsection 建置變更



@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

（由 Zhang Na 於 gh-90656@footnote{https://github.com/python/cpython/issues/90656} 中貢獻。）

@item 
@code{PYTHON_FOR_REGEN} 現在需要 Python 3.10 或更新的版本。

@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 變更<3>,,建置變更<3>,Python 3 12 有什麼新功能
@anchor{whatsnew/3 12 c-api-changes}@anchor{760}
@subsection C API 變更


@menu
* 新增功能: 新增功能<4>. 
* 移植至 Python 3.12: 移植至 Python 3 12<2>. 
* 已棄用: 已棄用<3>. 
* 已移除: 已移除<3>. 

@end menu

@node 新增功能<4>,移植至 Python 3 12<2>,,C API 變更<3>
@anchor{whatsnew/3 12 id4}@anchor{761}
@subsubsection 新增功能

@anchor{whatsnew/3 12 whatsnew312-pep697}@anchor{66f}

@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 697
PEP 697@footnote{https://peps.python.org/pep-0697/}: Introduce the @ref{762,,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.

程式碼物件建構函式：


@itemize -

@item 
@code{PyUnstable_Code_New()}（自 @code{PyCode_New} 重新命名）

@item 
@code{PyUnstable_Code_NewWithPosOnlyArgs()}（自 @code{PyCode_NewWithPosOnlyArgs} 重新命名）
@end itemize

程式碼物件的額外儲存 (
@geindex Python Enhancement Proposals; PEP 523
PEP 523@footnote{https://peps.python.org/pep-0523/})：


@itemize -

@item 
@code{PyUnstable_Eval_RequestCodeExtraIndex()}（自 @code{_PyEval_RequestCodeExtraIndex} 重新命名）

@item 
@code{PyUnstable_Code_GetExtra()}（自 @code{_PyCode_GetExtra} 重新命名）

@item 
@code{PyUnstable_Code_SetExtra()}（自 @code{_PyCode_SetExtra} 重新命名）
@end itemize

原始名稱將可繼續使用，直到相應的 API 發生變更。

（由 Petr Viktorin 於 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{763,,PyType_Spec.basicsize} 可以為零或負數來指定繼承或擴充基底類別大小。

@item 
@ref{764,,PyObject_GetTypeData()} and @ref{765,,PyType_GetTypeDataSize()}
added to allow access to subclass-specific instance data.

@item 
@ref{766,,Py_TPFLAGS_ITEMS_AT_END} and @ref{767,,PyObject_GetItemData()}
added to allow safely extending certain variable-sized types, including
@ref{768,,PyType_Type}.

@item 
@ref{769,,Py_RELATIVE_OFFSET} added to allow defining
@ref{76a,,members} in terms of a subclass-specific struct.
@end itemize

（由 Petr Viktorin 於 gh-103509@footnote{https://github.com/python/cpython/issues/103509} 中貢獻。）

@item 
Add the new @ref{62f,,limited C API} function @ref{76b,,PyType_FromMetaclass()},
which generalizes the existing @ref{76c,,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{76d,,the vectorcall protocol} was added to the
@ref{76e,,Limited API}:


@itemize *

@item 
@ref{76f,,Py_TPFLAGS_HAVE_VECTORCALL}

@item 
@ref{770,,PyVectorcall_NARGS()}

@item 
@ref{771,,PyVectorcall_Call()}

@item 
@ref{772,,vectorcallfunc}
@end itemize

The @ref{76f,,Py_TPFLAGS_HAVE_VECTORCALL} flag is now removed from a class
when the class's @ref{773,,__call__()} method is reassigned.
This makes vectorcall safe to use with mutable types (i.e. heap types
without the immutable flag, @ref{3cd,,Py_TPFLAGS_IMMUTABLETYPE}).
Mutable types that do not override @ref{774,,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{607,,Py_TPFLAGS_MANAGED_DICT} and @ref{775,,Py_TPFLAGS_MANAGED_WEAKREF}
flags have been added. This allows extensions classes to support object
@ref{776,,__dict__} and weakrefs with less bookkeeping,
using less memory and with faster access.

@item 
API for performing calls using
@ref{76d,,the vectorcall protocol} was added to the
@ref{76e,,Limited API}:


@itemize *

@item 
@ref{777,,PyObject_Vectorcall()}

@item 
@ref{778,,PyObject_VectorcallMethod()}

@item 
@ref{779,,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{76e,,Limited API}. (Contributed
by Wenzel Jakob in gh-98586@footnote{https://github.com/python/cpython/issues/98586}.)

@item 
Add two new public functions,
@ref{77a,,PyEval_SetProfileAllThreads()} and
@ref{65c,,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{77b,,PyFunction_SetVectorcall()} to the C API
which sets the vectorcall field of a given @ref{77c,,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{3ce,,PyDict_AddWatcher()},
@ref{77d,,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{77e,,PyType_AddWatcher()} and @ref{77f,,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{780,,PyCode_AddWatcher()} and @ref{781,,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{782,,PyFrame_GetVar()} and @ref{783,,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{427,,PyErr_GetRaisedException()} and @ref{42a,,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{426,,PyErr_Fetch()} and @ref{429,,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{784,,PyException_GetArgs()} and @ref{785,,PyException_SetArgs()}
as convenience functions for retrieving and modifying
the @ref{786,,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{433,,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{670}

@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}：定義物件的參照計數

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} 這現在將初始化參照計數

@code{_Py_IMMORTAL_REFCNT}（與 @code{Py_BUILD_CORE} 一起使用時）。
@end table

@item 

@table @asis

@item @code{SSTATE_INTERNED_IMMORTAL} 駐留的 (interned) unicode 物件的識別字

那是不滅的。
@end table

@item 

@table @asis

@item @code{SSSTATE_INTERNED_IMMORTAL_STATIC} 駐留的 unicode 的識別字

不滅且靜態的物體
@end table

@item 

@table @asis

@item @code{sys.getunicodeinternedsize} 這會回傳 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

（由 Eddie Elizondo 於 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/}：新增新的 @ref{682,,Py_NewInterpreterFromConfig()} 函式和 @ref{787,,PyInterpreterConfig}，它們可用於建立具有自己的 GIL 的子直譯器。（有關更多資訊，請參閱 @ref{668,,PEP 684：直譯器各別持有的 GIL}。）（由 Eric Snow 在 gh-104110@footnote{https://github.com/python/cpython/issues/104110} 中貢獻。）

@item 
In the limited C API version 3.12, @ref{788,,Py_INCREF()} and
@ref{789,,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 移植至 Python 3 12<2>,已棄用<3>,新增功能<4>,C API 變更<3>
@anchor{whatsnew/3 12 id5}@anchor{78a}
@subsubsection 移植至 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{3bf,,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{78b,,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{78c,,__subclasses__()} (using @ref{638,,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{623,,PyUnicode_FromFormat()} and
@ref{78d,,PyUnicode_FromFormatV()}.
(Contributed by Serhiy Storchaka in gh-98836@footnote{https://github.com/python/cpython/issues/98836}.)

@item 
An unrecognized format character in @ref{623,,PyUnicode_FromFormat()} and
@ref{78d,,PyUnicode_FromFormatV()} now sets a @ref{78e,,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{623,,PyUnicode_FromFormat()} and
@ref{78d,,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{776,,__dict__} or weak reference slot
should use @ref{607,,Py_TPFLAGS_MANAGED_DICT} and
@ref{775,,Py_TPFLAGS_MANAGED_WEAKREF} instead of @code{tp_dictoffset} and
@code{tp_weaklistoffset}, respectively.
The use of @code{tp_dictoffset} and @code{tp_weaklistoffset} is still
supported, but does not fully support multiple inheritance
(gh-95589@footnote{https://github.com/python/cpython/issues/95589}), and performance may be worse.
Classes declaring @ref{607,,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{78f,,PyObject_ClearWeakRefs()}, as before.

@item 
The @ref{790,,PyUnicode_FSDecoder()} function no longer accepts bytes-like
paths, like @ref{343,,bytearray} and @ref{165,,memoryview} types: only the exact
@ref{192,,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{791,,Py_CLEAR}, @ref{792,,Py_SETREF} and @ref{793,,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{794,,PyErr_SetObject()}, @ref{795,,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{796,,PyType_FromSpec()}

@item 
@ref{797,,PyType_FromSpecWithBases()}

@item 
@ref{76c,,PyType_FromModuleAndSpec()}
@end itemize

Creating classes whose metaclass overrides @ref{798,,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{76b,,PyType_FromMetaclass()} (added in Python 3.12)
already disallows creating classes whose metaclass overrides @code{tp_new}
(@ref{799,,__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{79a,,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{79b,,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{79c,,calling}
the metaclass.

@item 
If you `know' the @code{tp_new} can be skipped safely, filter the deprecation
warning out using @ref{179,,warnings.catch_warnings()} from Python.
@end itemize

@item 
@ref{79d,,PyOS_InputHook} and @ref{79e,,PyOS_ReadlineFunctionPointer} are no
longer called in @ref{163,,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{39c,,PyLongObject} has had its internals changed for better performance.
Although the internals of @ref{39c,,PyLongObject} are private, they are used
by some extension modules.
The internal fields should no longer be accessed directly, instead the API
functions beginning @code{PyLong_...} should be used instead.
Two new `unstable' API functions are provided for efficient access to the
value of @ref{39c,,PyLongObject}s which fit into a single machine word:


@itemize *

@item 
@ref{79f,,PyUnstable_Long_IsCompact()}

@item 
@ref{7a0,,PyUnstable_Long_CompactValue()}
@end itemize

@item 
Custom allocators, set via @ref{7a1,,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 已棄用<3>,已移除<3>,移植至 Python 3 12<2>,C API 變更<3>
@anchor{whatsnew/3 12 id6}@anchor{7a2}
@subsubsection 已棄用



@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{647,,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 
棄用全域配置變數：


@itemize *

@item 
@ref{3f6,,Py_DebugFlag}：請改用 @ref{3f7,,PyConfig.parser_debug}

@item 
@ref{3f8,,Py_VerboseFlag}：請改用 @ref{3f9,,PyConfig.verbose}

@item 
@ref{3fa,,Py_QuietFlag}：請改用 @ref{3fb,,PyConfig.quiet}

@item 
@ref{3fc,,Py_InteractiveFlag}：請改用 @ref{3fd,,PyConfig.interactive}

@item 
@ref{3fe,,Py_InspectFlag}：請改用 @ref{3ff,,PyConfig.inspect}

@item 
@ref{400,,Py_OptimizeFlag}：請改用 @ref{401,,PyConfig.optimization_level}

@item 
@ref{402,,Py_NoSiteFlag}：請改用 @ref{403,,PyConfig.site_import}

@item 
@ref{404,,Py_BytesWarningFlag}：請改用 @ref{405,,PyConfig.bytes_warning}

@item 
@ref{406,,Py_FrozenFlag}：請改用 @ref{407,,PyConfig.pathconfig_warnings}

@item 
@ref{408,,Py_IgnoreEnvironmentFlag}：請改用 @ref{409,,PyConfig.use_environment}

@item 
@ref{40a,,Py_DontWriteBytecodeFlag}：請改用 @ref{40b,,PyConfig.write_bytecode}

@item 
@ref{40c,,Py_NoUserSiteDirectory}：請改用 @ref{40d,,PyConfig.user_site_directory}

@item 
@ref{40e,,Py_UnbufferedStdioFlag}：請改用 @ref{40f,,PyConfig.buffered_stdio}

@item 
@ref{410,,Py_HashRandomizationFlag}：請改用 @ref{411,,PyConfig.use_hash_seed} 和 @ref{412,,PyConfig.hash_seed}

@item 
@ref{413,,Py_IsolatedFlag}：請改用 @ref{414,,PyConfig.isolated}

@item 
@ref{415,,Py_LegacyWindowsFSEncodingFlag}：請改用 @ref{416,,PyPreConfig.legacy_windows_fs_encoding}

@item 
@ref{417,,Py_LegacyWindowsStdioFlag}：請改用 @ref{418,,PyConfig.legacy_windows_stdio}

@item 
@code{Py_FileSystemDefaultEncoding}：請改用 @ref{419,,PyConfig.filesystem_encoding}

@item 
@code{Py_HasFileSystemDefaultEncoding}：請改用 @ref{419,,PyConfig.filesystem_encoding}

@item 
@code{Py_FileSystemDefaultEncodeErrors}：請改用 @ref{41a,,PyConfig.filesystem_errors}

@item 
@code{Py_UTF8Mode}：請改用 @ref{41b,,PyPreConfig.utf8_mode}（參見 @ref{41c,,Py_PreInitialize()}）
@end itemize

@ref{3f5,,Py_InitializeFromConfig()} API 應改為與 @ref{3f4,,PyConfig} 一起使用。（由 Victor Stinner 於 gh-77782@footnote{https://github.com/python/cpython/issues/77782} 中貢獻。）

@item 
Creating @ref{3cd,,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 
@code{structmember.h} 標頭已棄用，但仍可使用，且還沒有移除它的計畫。

現在只需包含 @code{Python.h} 即可使用其內容，如果缺少，則新增 @code{Py} 前綴：


@itemize -

@item 
@ref{76a,,PyMemberDef}、@ref{7a3,,PyMember_GetOne()} 和 @ref{7a4,,PyMember_SetOne()}

@item 
型別巨集，如 @ref{7a5,,Py_T_INT}、@ref{7a6,,Py_T_DOUBLE} 等（以前為 @code{T_INT}、 @code{T_DOUBLE} 等）

@item 
@ref{7a7,,Py_READONLY}（先前為 @code{READONLY}）和 @ref{7a8,,Py_AUDIT_READ}（先前全大寫）旗標
@end itemize

數個項目不再從 @code{Python.h} 中公開：


@itemize -

@item 
@ref{7a9,,T_OBJECT}（請改用 @ref{7aa,,Py_T_OBJECT_EX}）

@item 
@ref{7ab,,T_NONE}（先前未記錄於文件上，且相當古怪）

@item 
不做任何事的巨集 @code{WRITE_RESTRICTED}。

@item 
@code{RESTRICTED} 和 @code{READ_RESTRICTED} 這兩個巨集，相當於 @ref{7a8,,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.

（由 Petr Viktorin 在 gh-47146@footnote{https://github.com/python/cpython/issues/47146} 中貢獻，其基於 Alexander Belopolsky 和 Matthias Braun 的前期工作。）

@item 
@ref{426,,PyErr_Fetch()} and @ref{429,,PyErr_Restore()} are deprecated.
Use @ref{427,,PyErr_GetRaisedException()} and
@ref{42a,,PyErr_SetRaisedException()} instead.
(Contributed by Mark Shannon in gh-101578@footnote{https://github.com/python/cpython/issues/101578}.)

@item 
@code{PyErr_Display()} 已棄用，請改用 @ref{433,,PyErr_DisplayException()}。（由 Irit Katriel 於 gh-102755@footnote{https://github.com/python/cpython/issues/102755} 中貢獻。）

@item 
@code{_PyErr_ChainExceptions} 已棄用，請改用 @code{_PyErr_ChainExceptions1}。（由 Irit Katriel 於 gh-102192@footnote{https://github.com/python/cpython/issues/102192} 中貢獻。）

@item 
使用 @ref{796,,PyType_FromSpec()}、@ref{797,,PyType_FromSpecWithBases()} 或 @ref{76c,,PyType_FromModuleAndSpec()} 建立一個其元類別覆寫 @ref{798,,tp_new} 的類別已被棄用。請改為呼叫元類別。
@end itemize

@c Add deprecations above alphabetically, not here at the end.

@menu
* Python 3.14 中待移除的項目: Python 3 14 中待移除的項目<4>. 
* Python 3.15 中待移除的項目: Python 3 15 中待移除的項目<6>. 
* Python 3.16 中待移除的項目: Python 3 16 中待移除的項目<6>. 
* 未來版本中的待移除項目: 未來版本中的待移除項目<6>. 

@end menu

@node Python 3 14 中待移除的項目<4>,Python 3 15 中待移除的項目<6>,,已棄用<3>
@anchor{whatsnew/3 12 id7}@anchor{7ac}
@subsubsection Python 3.14 中待移除的項目



@itemize *

@item 
@ref{647,,PyDictObject} 中的 @code{ma_version_tag} 欄位，用於擴充模組 (
@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 
使用可變基底建立@ref{3cd,,不可變型別} (gh-95388@footnote{https://github.com/python/cpython/issues/95388})。
@end itemize

@node Python 3 15 中待移除的項目<6>,Python 3 16 中待移除的項目<6>,Python 3 14 中待移除的項目<4>,已棄用<3>
@anchor{whatsnew/3 12 id8}@anchor{7ad}
@subsubsection Python 3.15 中待移除的項目



@itemize *

@item 
@ref{3d9,,PyImport_ImportModuleNoBlock()}：請改用 @ref{3da,,PyImport_ImportModule()}。

@item 
@ref{3db,,PyWeakref_GetObject()} 和 @ref{3dc,,PyWeakref_GET_OBJECT()}：請改用 @ref{3dd,,PyWeakref_GetRef()}。可以使用 pythoncapi-compat 專案@footnote{https://github.com/python/pythoncapi-compat/}來為 Python 3.12 和更早版本取得 @ref{3dd,,PyWeakref_GetRef()}。

@item 
@ref{3de,,Py_UNICODE} 型別與 @code{Py_UNICODE_WIDE} 巨集：請改用 @code{wchar_t}。

@item 
@code{PyUnicode_AsDecodedObject()}：請改用 @ref{3df,,PyCodec_Decode()}。

@item 
@code{PyUnicode_AsDecodedUnicode()}：請改用 @ref{3df,,PyCodec_Decode()}；請注意某些編解碼器（例如 "base64"）可能會回傳非 @ref{169,,str} 的型別，例如 @ref{192,,bytes}。

@item 
@code{PyUnicode_AsEncodedObject()}：請改用 @ref{3e0,,PyCodec_Encode()}。

@item 
@code{PyUnicode_AsEncodedUnicode()}：請改用 @ref{3e0,,PyCodec_Encode()}；請注意某些編解碼器（例如 "base64"）可能會回傳非 @ref{192,,bytes} 的型別，例如 @ref{169,,str}。

@item 
Python 初始化函式，自 Python 3.13 起已被棄用：


@itemize *

@item 
@ref{3e1,,Py_GetPath()}：請改用 @ref{37a,,PyConfig_Get("module_search_paths")} (@ref{3e2,,sys.path})。

@item 
@ref{3e3,,Py_GetPrefix()}：請改用 @ref{37a,,PyConfig_Get("base_prefix")} (@ref{3e4,,sys.base_prefix})。如果需要處理@ref{3e5,,虛擬環境}，請改用 @ref{37a,,PyConfig_Get("prefix")} (@ref{3e6,,sys.prefix})。

@item 
@ref{3e7,,Py_GetExecPrefix()}：請改用 @ref{37a,,PyConfig_Get("base_exec_prefix")} (@ref{3e8,,sys.base_exec_prefix})。如果需要處理@ref{3e5,,虛擬環境}，請改用 @ref{37a,,PyConfig_Get("exec_prefix")} (@ref{3e9,,sys.exec_prefix})。

@item 
@ref{3ea,,Py_GetProgramFullPath()}：請改用 @ref{37a,,PyConfig_Get("executable")} (@ref{3eb,,sys.executable})。

@item 
@ref{3ec,,Py_GetProgramName()}：請改用 @ref{37a,,PyConfig_Get("executable")} (@ref{3eb,,sys.executable})。

@item 
@ref{3ed,,Py_GetPythonHome()}：請改用 @ref{37a,,PyConfig_Get("home")} 或 
@geindex PYTHONHOME
@geindex 環境變數; PYTHONHOME
@ref{3ee,,PYTHONHOME} 環境變數。
@end itemize

pythoncapi-compat 專案@footnote{https://github.com/python/pythoncapi-compat/} 可以用來為 Python 3.13 和更早版本取得 @ref{37a,,PyConfig_Get()}。

@item 
用於配置 Python 初始化的函式，自 Python 3.11 起已被棄用：


@itemize *

@item 
@code{PySys_SetArgvEx()}：請改用 @ref{3ef,,PyConfig.argv}。

@item 
@code{PySys_SetArgv()}：請改用 @ref{3ef,,PyConfig.argv}。

@item 
@code{Py_SetProgramName()}：請改用 @ref{3f0,,PyConfig.program_name}。

@item 
@code{Py_SetPythonHome()}：請改用 @ref{3f1,,PyConfig.home}。

@item 
@ref{3f2,,PySys_ResetWarnOptions()}：請改為清除 @ref{3f3,,sys.warnoptions} 和 @code{warnings.filters}。
@end itemize

應改用帶有 @ref{3f4,,PyConfig} 的 @ref{3f5,,Py_InitializeFromConfig()} API。

@item 
全域配置變數：


@itemize *

@item 
@ref{3f6,,Py_DebugFlag}：請改用 @ref{3f7,,PyConfig.parser_debug} 或 @ref{37a,,PyConfig_Get("parser_debug")}。

@item 
@ref{3f8,,Py_VerboseFlag}：請改用 @ref{3f9,,PyConfig.verbose} 或 @ref{37a,,PyConfig_Get("verbose")}。

@item 
@ref{3fa,,Py_QuietFlag}：請改用 @ref{3fb,,PyConfig.quiet} 或 @ref{37a,,PyConfig_Get("quiet")}。

@item 
@ref{3fc,,Py_InteractiveFlag}：請改用 @ref{3fd,,PyConfig.interactive} 或 @ref{37a,,PyConfig_Get("interactive")}。

@item 
@ref{3fe,,Py_InspectFlag}：請改用 @ref{3ff,,PyConfig.inspect} 或 @ref{37a,,PyConfig_Get("inspect")}。

@item 
@ref{400,,Py_OptimizeFlag}：請改用 @ref{401,,PyConfig.optimization_level} 或 @ref{37a,,PyConfig_Get("optimization_level")}。

@item 
@ref{402,,Py_NoSiteFlag}：請改用 @ref{403,,PyConfig.site_import} 或 @ref{37a,,PyConfig_Get("site_import")}。

@item 
@ref{404,,Py_BytesWarningFlag}：請改用 @ref{405,,PyConfig.bytes_warning} 或 @ref{37a,,PyConfig_Get("bytes_warning")}。

@item 
@ref{406,,Py_FrozenFlag}：請改用 @ref{407,,PyConfig.pathconfig_warnings} 或 @ref{37a,,PyConfig_Get("pathconfig_warnings")}。

@item 
@ref{408,,Py_IgnoreEnvironmentFlag}：請改用 @ref{409,,PyConfig.use_environment} 或 @ref{37a,,PyConfig_Get("use_environment")}。

@item 
@ref{40a,,Py_DontWriteBytecodeFlag}：請改用 @ref{40b,,PyConfig.write_bytecode} 或 @ref{37a,,PyConfig_Get("write_bytecode")}。

@item 
@ref{40c,,Py_NoUserSiteDirectory}：請改用 @ref{40d,,PyConfig.user_site_directory} 或 @ref{37a,,PyConfig_Get("user_site_directory")}。

@item 
@ref{40e,,Py_UnbufferedStdioFlag}：請改用 @ref{40f,,PyConfig.buffered_stdio} 或 @ref{37a,,PyConfig_Get("buffered_stdio")}。

@item 
@ref{410,,Py_HashRandomizationFlag}：請改用 @ref{411,,PyConfig.use_hash_seed} 和 @ref{412,,PyConfig.hash_seed} 或 @ref{37a,,PyConfig_Get("hash_seed")}。

@item 
@ref{413,,Py_IsolatedFlag}：請改用 @ref{414,,PyConfig.isolated} 或 @ref{37a,,PyConfig_Get("isolated")}。

@item 
@ref{415,,Py_LegacyWindowsFSEncodingFlag}：請改用 @ref{416,,PyPreConfig.legacy_windows_fs_encoding} 或 @ref{37a,,PyConfig_Get("legacy_windows_fs_encoding")}。

@item 
@ref{417,,Py_LegacyWindowsStdioFlag}：請改用 @ref{418,,PyConfig.legacy_windows_stdio} 或 @ref{37a,,PyConfig_Get("legacy_windows_stdio")}。

@item 
@code{Py_FileSystemDefaultEncoding}、@code{Py_HasFileSystemDefaultEncoding}：請改用 @ref{419,,PyConfig.filesystem_encoding} 或 @ref{37a,,PyConfig_Get("filesystem_encoding")}。

@item 
@code{Py_FileSystemDefaultEncodeErrors}：請改用 @ref{41a,,PyConfig.filesystem_errors} 或 @ref{37a,,PyConfig_Get("filesystem_errors")}。

@item 
@code{Py_UTF8Mode}：請改用 @ref{41b,,PyPreConfig.utf8_mode} 或 @ref{37a,,PyConfig_Get("utf8_mode")}。（請參閱 @ref{41c,,Py_PreInitialize()}）
@end itemize

應改用帶有 @ref{3f4,,PyConfig} 的 @ref{3f5,,Py_InitializeFromConfig()} API 來設定這些選項。或者也可以使用 @ref{37a,,PyConfig_Get()} 在執行時取得這些選項。
@end itemize

@node Python 3 16 中待移除的項目<6>,未來版本中的待移除項目<6>,Python 3 15 中待移除的項目<6>,已棄用<3>
@anchor{whatsnew/3 12 id9}@anchor{7ae}
@subsubsection Python 3.16 中待移除的項目



@itemize *

@item 
@code{libmpdecimal} 的打包副本 (bundled copy)。
@end itemize

@node 未來版本中的待移除項目<6>,,Python 3 16 中待移除的項目<6>,已棄用<3>
@anchor{whatsnew/3 12 id10}@anchor{7af}
@subsubsection 未來版本中的待移除項目


下列 API 已被棄用並將會被移除，不過目前尚未訂定移除日期。


@itemize *

@item 
@ref{425,,Py_TPFLAGS_HAVE_FINALIZE}：自 Python 3.8 起不再需要

@item 
@ref{426,,PyErr_Fetch()}：請改用 @ref{427,,PyErr_GetRaisedException()}。

@item 
@ref{428,,PyErr_NormalizeException()}：請改用 @ref{427,,PyErr_GetRaisedException()}。

@item 
@ref{429,,PyErr_Restore()}：請改用 @ref{42a,,PyErr_SetRaisedException()}。

@item 
@ref{42b,,PyModule_GetFilename()}：請改用 @ref{42c,,PyModule_GetFilenameObject()}。

@item 
@ref{42d,,PyOS_AfterFork()}：請改用 @ref{42e,,PyOS_AfterFork_Child()}。

@item 
@ref{42f,,PySlice_GetIndicesEx()}：請改用 @ref{430,,PySlice_Unpack()} 和 @ref{431,,PySlice_AdjustIndices()}。

@item 
@ref{432,,PyUnicode_READY()}：自 Python 3.12 起不再需要

@item 
@code{PyErr_Display()}：請改用 @ref{433,,PyErr_DisplayException()}。

@item 
@code{_PyErr_ChainExceptions()}：請改用 @code{_PyErr_ChainExceptions1}。

@item 
@code{PyBytesObject.ob_shash} 成員：請改為呼叫 @ref{434,,PyObject_Hash()}。

@item 
執行緒局部儲存 (Thread Local Storage, TLS) API：


@itemize *

@item 
@ref{435,,PyThread_create_key()}：請改用 @ref{436,,PyThread_tss_alloc()}。

@item 
@ref{437,,PyThread_delete_key()}：請改用 @ref{438,,PyThread_tss_free()}。

@item 
@ref{439,,PyThread_set_key_value()}：請改用 @ref{43a,,PyThread_tss_set()}。

@item 
@ref{43b,,PyThread_get_key_value()}：請改用 @ref{43c,,PyThread_tss_get()}。

@item 
@ref{43d,,PyThread_delete_key_value()}：請改用 @ref{43e,,PyThread_tss_delete()}。

@item 
@ref{43f,,PyThread_ReInitTLS()}：自 Python 3.7 起不再需要。
@end itemize
@end itemize

@node 已移除<3>,,已棄用<3>,C API 變更<3>
@anchor{whatsnew/3 12 id11}@anchor{7b0}
@subsubsection 已移除



@itemize *

@item 
移除 @code{token.h} 標頭檔案。從未有任何公開的 tokenizer C API。@code{token.h} 標頭檔案的設計是僅限用於 Python 內部。（由 Victor Stinner 於 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 
移除 @code{PyUnicode_InternImmortal()} 函式巨集。（由 Victor Stinner 於 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 Python 3 11 有什麼新功能,Python 3 10 有什麼新功能,Python 3 12 有什麼新功能,Python 有什麼新功能？
@anchor{whatsnew/3 11 doc}@anchor{7b1}@anchor{whatsnew/3 11 translation-repo}@anchor{7b2}@anchor{whatsnew/3 11 what-s-new-in-python-3-11}@anchor{7b3}
@section Python 3.11 有什麼新功能


@*編輯者: 
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.

此文章解釋了 Python 3.11 和 3.10 相比多了哪些新功能。Python 3.11 於 2022 年 10 月 24 日發布。完整細節請見 @ref{142,,Changelog（更動日誌）}。

@menu
* 發布重點摘要: 發布重點摘要<3>. 
* 新增功能: 新增功能<5>. 
* 型別提示相關的新特性: 型別提示相關的新特性<2>. 
* 其他語言更動: 其他語言更動<3>. 
* 其他 CPython 實作更動:: 
* 新增模組: 新增模組<3>. 
* 改進的模組: 改進的模組<3>. 
* 最佳化: 最佳化<4>. 
* 更快的 CPython:: 
* CPython 位元組碼變更: CPython 位元組碼變更<4>. 
* 已棄用: 已棄用<4>. 
* Python 3.12 中待決議的移除項目: Python 3 12 中待決議的移除項目. 
* 已移除: 已移除<4>. 
* 移植至 Python 3.11: 移植至 Python 3 11. 
* 建置變更: 建置變更<4>. 
* C API 變更: C API 變更<4>. 
* Python 3.11.4 中顯著的變更: Python 3 11 4 中顯著的變更. 
* Python 3.11.5 中顯著的變更: Python 3 11 5 中顯著的變更. 

@end menu

@node 發布重點摘要<3>,新增功能<5>,,Python 3 11 有什麼新功能
@anchor{whatsnew/3 11 summary-release-highlights}@anchor{7b4}@anchor{whatsnew/3 11 whatsnew311-summary}@anchor{7b5}
@subsection 發布重點摘要


@c This section singles out the most important changes in Python 3.11.
@c Brevity is key.


@itemize *

@item 
Python 3.11 比 Python 3.10 快了 10-60%。我們使用了標準基準量測套裝軟體 (benchmark suite) 測得平均加速了 1.25x。細節請見@ref{7b6,,更快的 CPython}。
@end itemize

@c PEP-sized items next.

新增語法特性：


@itemize *

@item 
@ref{7b7,,PEP 654：例外群組與 except*}
@end itemize

新的內建功能：


@itemize *

@item 
@ref{7b8,,PEP 678：運用例外註解使其更加詳盡}
@end itemize

新增標準函式庫模組：


@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 680
PEP 680@footnote{https://peps.python.org/pep-0680/}：@ref{102,,tomllib} — 在標準函式庫中支援 TOML@footnote{https://toml.io/} 檔案的剖析
@end itemize

直譯器的改進：


@itemize *

@item 
@ref{7b9,,PEP 657：回溯 (traceback) 中更細緻的錯誤位置}

@item 
新增 @ref{7ba,,-P} 命令列選項和 
@geindex PYTHONSAFEPATH
@geindex 環境變數; PYTHONSAFEPATH
@ref{7bb,,PYTHONSAFEPATH} 環境變數以停用自動於 @ref{3e2,,sys.path} 的開頭@ref{7bc,,加上一個有潛在安全問題的路徑}
@end itemize

新增型別特性：


@itemize *

@item 
@ref{7bd,,PEP 646：可變參數泛型 (variadic generics)}

@item 
@ref{7be,,PEP 655：標記獨立 TypedDict 項目為必要或不必要}

@item 
@ref{7bf,,PEP 673：Self 型別}

@item 
@ref{7c0,,PEP 675：任意的文本字串型別 (Arbitrary literal string type)}

@item 
@ref{7c1,,PEP 681：資料類別轉換 (Data class transforms)}
@end itemize

重要的棄用、移除與限制：


@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/}：@ref{7c2,,許多標準函式庫中的遺留模組已被棄用}且將於 Python 3.13 移除

@item 
@geindex Python Enhancement Proposals; PEP 624
PEP 624@footnote{https://peps.python.org/pep-0624/}：@ref{7c3,,Py_UNICODE 編碼器 API 已被移除}

@item 
@geindex Python Enhancement Proposals; PEP 670
PEP 670@footnote{https://peps.python.org/pep-0670/}：@ref{7c4,,轉換為靜態行內函式的巨集}
@end itemize

@node 新增功能<5>,型別提示相關的新特性<2>,發布重點摘要<3>,Python 3 11 有什麼新功能
@anchor{whatsnew/3 11 new-features}@anchor{7c5}@anchor{whatsnew/3 11 whatsnew311-features}@anchor{7c6}
@subsection 新增功能


@menu
* PEP 657：回溯 (traceback) 中更細緻的錯誤位置: PEP 657：回溯 traceback 中更細緻的錯誤位置. 
* PEP 654：例外群組與 except*:: 
* PEP 678：運用例外註解使其更加詳盡:: 
* Windows py.exe 啟動程式 (launcher) 的改進: Windows py exe 啟動程式 launcher 的改進. 

@end menu

@node PEP 657：回溯 traceback 中更細緻的錯誤位置,PEP 654：例外群組與 except*,,新增功能<5>
@anchor{whatsnew/3 11 pep-657-fine-grained-error-locations-in-tracebacks}@anchor{7c7}@anchor{whatsnew/3 11 whatsnew311-pep657}@anchor{7b9}
@subsubsection PEP 657：回溯 (traceback) 中更細緻的錯誤位置


當要印出回溯，直譯器現在會指出造成錯誤的確切運算式，而非只說明是哪一行。例如：

@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

前一版本的直譯器只會標明是哪一行，無法辨認哪一個物件是 @code{None}。當處理多層的巢狀 @ref{183,,dict} 物件和多個函式呼叫時，這種強化錯誤提示也可能非常有用：

@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

在複雜的計算運算式中也是：

@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

此外，強化回溯特性所使用的資訊可以透過一般的 API 來取得，以用來使 @ref{4a5,,bytecode} @ref{7c8,,指示 (instruction)}與原始碼位置相互關聯。此項資訊可以用以下方式取得：


@itemize -

@item 
Python 中的 @ref{7c9,,codeobject.co_positions()} 方法。

@item 
C API 中的 @ref{7ca,,PyCode_Addr2Location()} 函式。
@end itemize

詳情請見 
@geindex Python Enhancement Proposals; PEP 657
PEP 657@footnote{https://peps.python.org/pep-0657/}。（由 Pablo Galindo、Batuhan Taskaya 與 Ammar Askar 於 bpo-43950@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43950} 中所貢獻。）

@cartouche
@quotation 備註 
這個特性必須要將欄的位置 (column position) 儲存於 @ref{7cb,,程式碼物件}，這可能會導致直譯器用於編譯 Python 檔案的記憶體使用量與硬碟使用量增加。為了避免儲存多餘的資訊且停用印出多餘的回溯資訊，請用 @ref{16f,,-X no_debug_ranges} 命令列選項或是 
@geindex PYTHONNODEBUGRANGES
@geindex 環境變數; PYTHONNODEBUGRANGES
@ref{7cc,,PYTHONNODEBUGRANGES} 環境變數。
@end quotation
@end cartouche

@node PEP 654：例外群組與 except*,PEP 678：運用例外註解使其更加詳盡,PEP 657：回溯 traceback 中更細緻的錯誤位置,新增功能<5>
@anchor{whatsnew/3 11 pep-654-exception-groups-and-except}@anchor{7cd}@anchor{whatsnew/3 11 whatsnew311-pep654}@anchor{7b7}
@subsubsection PEP 654：例外群組與 @code{except*}


@geindex Python Enhancement Proposals; PEP 654
PEP 654@footnote{https://peps.python.org/pep-0654/} 引入了新的的語言特性，可讓程式同時引發並處理多個相互無關的例外。內建型別 @ref{4cd,,ExceptionGroup} 和 @ref{560,,BaseExceptionGroup} 使得程式可為多個例外組成群組並同時引發，新的 @ref{1ac,,except*} 語法也將 @ref{1ab,,except} 泛用化、能夠比對例外群組的子群組。

詳情請見 
@geindex Python Enhancement Proposals; PEP 654
PEP 654@footnote{https://peps.python.org/pep-0654/}。

（由 Irit Katriel 於 bpo-45292@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45292} 中所貢獻。PEP 由 Irit Katriel、Yury Selivanov 與 Guido van Rossum 撰寫。）

@node PEP 678：運用例外註解使其更加詳盡,Windows py exe 啟動程式 launcher 的改進,PEP 654：例外群組與 except*,新增功能<5>
@anchor{whatsnew/3 11 pep-678-exceptions-can-be-enriched-with-notes}@anchor{7ce}@anchor{whatsnew/3 11 whatsnew311-pep678}@anchor{7b8}
@subsubsection PEP 678：運用例外註解使其更加詳盡


新增 @ref{7cf,,add_note()} 方法到 @ref{7d0,,BaseException}。當上下文資訊在例外被引發時無法被取得，這個方法就可以用來為例外添加更多資訊。被添加的註解會在預設回溯中出現。

詳情請見 
@geindex Python Enhancement Proposals; PEP 678
PEP 678@footnote{https://peps.python.org/pep-0678/}。

（由 Irit Katriel 於 bpo-45607@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45607} 中所貢獻。PEP 由 Zac Hatfield-Dodds 所撰寫）

@node Windows py exe 啟動程式 launcher 的改進,,PEP 678：運用例外註解使其更加詳盡,新增功能<5>
@anchor{whatsnew/3 11 whatsnew311-windows-launcher}@anchor{7d1}@anchor{whatsnew/3 11 windows-py-exe-launcher-improvements}@anchor{7d2}
@subsubsection Windows @code{py.exe} 啟動程式 (launcher) 的改進


Python 3.11 所包含的 @ref{7d3,,Python 安裝管理員} 複製品有了顯著的改善。它現在支援 
@geindex Python Enhancement Proposals; PEP 514
PEP 514@footnote{https://peps.python.org/pep-0514/} 所定義的公司/標籤 (tag) 語法，可用 @code{-V:@var{<company>}/@var{<tag>}} 引數來取代受限的 @code{-@var{<major>}.@var{<minor>}}。這允許了 python.org@footnote{https://www.python.org} 上的 @code{PythonCore} 以外的發行版本發布。

使用 @code{-V:} 選擇器時，可以省略公司或標籤，但會搜尋所有安裝。例如，@code{-V:OtherPython/} 將選擇 @code{OtherPython} 註冊的「最佳」標籤，而 @code{-V:3.11} 或 @code{-V:/3.11} 將選擇帶有 @code{3.11} 標籤的「最佳」發行版。

當使用遺留的 @code{-@var{<major>}}、@code{-@var{<major>}.@var{<minor>}}、@code{-@var{<major>}-@var{<bitness>}} 或 @code{-@var{<major>}.@var{<minor>}-@var{<bitness>}} 引數時，所有過去版本的行為都應該保留下來，且只有 @code{PythonCore} 中的發布版本會被選用。然而，@code{-64} 後綴現在暗示了「非 32-bit」（不用一定要是 x86-64），因為現在有多個支援 64-bit 的平台。32-bit 運行程式會在檢查運行程式之標籤是否帶有 @code{-32} 後綴時被偵測出來。所有 Python 3.5 以後發布版本的 32-bit 建置中都有這個行為。
@anchor{whatsnew/3 11 new-feat-related-type-hints-311}@anchor{7d4}
@node 型別提示相關的新特性<2>,其他語言更動<3>,新增功能<5>,Python 3 11 有什麼新功能
@anchor{whatsnew/3 11 new-features-related-to-type-hints}@anchor{7d5}@anchor{whatsnew/3 11 whatsnew311-typing-features}@anchor{7d6}
@subsection 型別提示相關的新特性


這個部分涵蓋影響 
@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/} 型別提示 (type hints) 與 @ref{10a,,typing} 模組的重大變更。

@menu
* PEP 646：可變參數泛型 (variadic generics): PEP 646：可變參數泛型 variadic generics. 
* PEP 655：標記獨立 TypedDict 項目為必要或不必要:: 
* PEP 673：Self 型別:: 
* PEP 675：任意的文本字串型別 (Arbitrary literal string type): PEP 675：任意的文本字串型別 Arbitrary literal string type. 
* PEP 681：資料類別轉換 (Data class transforms): PEP 681：資料類別轉換 Data class transforms. 
* PEP 563 可能不是未來:: 

@end menu

@node PEP 646：可變參數泛型 variadic generics,PEP 655：標記獨立 TypedDict 項目為必要或不必要,,型別提示相關的新特性<2>
@anchor{whatsnew/3 11 pep-646-variadic-generics}@anchor{7d7}@anchor{whatsnew/3 11 whatsnew311-pep646}@anchor{7bd}
@subsubsection PEP 646：可變參數泛型 (variadic generics)


@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/} 先前引入了 @ref{481,,TypeVar}，開啟了帶有單一型別的泛型參數化。
@geindex Python Enhancement Proposals; PEP 646
PEP 646@footnote{https://peps.python.org/pep-0646/} 新增 @ref{483,,TypeVarTuple}，開啟了帶有`任意'數量型別的參數化 (parameterisation)。換句話說，@ref{483,,TypeVarTuple} 是`可變的'型別變數，啟用了`可變的'泛型。

這使其有非常多用例，特別是它允許了像是 NumPy 和 Tensorflow 的數值運算函式庫中類似陣列結構的型別可用 `shape' 陣列來被參數化。靜態型別檢查工具現在也能夠為使用這些函式庫的程式捕捉到維度相關的錯誤。

詳情請見 
@geindex Python Enhancement Proposals; PEP 646
PEP 646@footnote{https://peps.python.org/pep-0646/}。

（由 Matthew Rahtz 於 bpo-43224@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43224} 中所貢獻，由 Serhiy Storchaka 與 Jelle Zijlstra 協助。PEP 由 Mark Mendoza、Matthew Rahtz、Pradeep Kumar Srinivasan 與 Vincent Siles 所撰寫）

@node PEP 655：標記獨立 TypedDict 項目為必要或不必要,PEP 673：Self 型別,PEP 646：可變參數泛型 variadic generics,型別提示相關的新特性<2>
@anchor{whatsnew/3 11 pep-655-marking-individual-typeddict-items-as-required-or-not-required}@anchor{7d8}@anchor{whatsnew/3 11 whatsnew311-pep655}@anchor{7be}
@subsubsection PEP 655：標記獨立 @code{TypedDict} 項目為必要或不必要


@ref{7d9,,Required} 與 @ref{7da,,NotRequired} 提供了標記一個獨立項目在 @ref{331,,TypedDict} 中是否必須存在的直覺方法。在這之前，這只有透過繼承才有可能做得到。

所有欄位都預設為是必要的，除非 `total' 參數有被設為 @code{False}，那麼所有欄位就會是非必要的。例如，這個範例指定了要有一個必要鍵與一個非必要鍵的 @code{TypedDict}：

@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

以下定義等同於：

@example
class Movie(TypedDict, total=False):
   title: Required[str]
   year: int
@end example

詳情請見 
@geindex Python Enhancement Proposals; PEP 655
PEP 655@footnote{https://peps.python.org/pep-0655/}。

（由 David Foster 與 Jelle Zijlstra 於 bpo-47087@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47087} 中所貢獻。PEP 由 David Foster 所撰寫）

@node PEP 673：Self 型別,PEP 675：任意的文本字串型別 Arbitrary literal string type,PEP 655：標記獨立 TypedDict 項目為必要或不必要,型別提示相關的新特性<2>
@anchor{whatsnew/3 11 pep-673-self-type}@anchor{7db}@anchor{whatsnew/3 11 whatsnew311-pep673}@anchor{7bf}
@subsubsection PEP 673：@code{Self} 型別


新的 @ref{7dc,,Self} 標註提供了一種簡單直觀的方法來標註那些會回傳其類別實例的方法。這與 
@geindex Python Enhancement Proposals; PEP 484#annotating-instance-and-class-methods
PEP 484@footnote{https://peps.python.org/pep-0484/#annotating-instance-and-class-methods} 中指定的基於 @ref{481,,TypeVar} 的方法相同，但更簡潔且更易於遵循。

常見用例包括作為 @ref{489,,classmethod} 的替代建構函式和會回傳 @code{self} 的 @ref{7dd,,__enter__()} 方法：

@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{7dc,,Self} 也可用於標註與其封閉類類別 (enclosing class) 相同的方法參數或屬性。

詳情請見 
@geindex Python Enhancement Proposals; PEP 673
PEP 673@footnote{https://peps.python.org/pep-0673/}。

（由 James Hilton-Balfe 於 bpo-46534@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46534} 中所貢獻。PEP 由 Pradeep Kumar Srinivasan 與 James Hilton-Balfe 所撰寫）

@node PEP 675：任意的文本字串型別 Arbitrary literal string type,PEP 681：資料類別轉換 Data class transforms,PEP 673：Self 型別,型別提示相關的新特性<2>
@anchor{whatsnew/3 11 pep-675-arbitrary-literal-string-type}@anchor{7de}@anchor{whatsnew/3 11 whatsnew311-pep675}@anchor{7c0}
@subsubsection PEP 675：任意的文本字串型別 (Arbitrary literal string type)


新的 @ref{7df,,LiteralString} 標註可用於標示一個函式參數可為任何文本字串型別 (literal string type)。這允許函式接受任意的文本字串型別，以及從其他文本字串建立的字串。型別檢查器就可以強制需審慎處理的函式（例如會執行 SQL 陳述式或 shell 命令的函式）僅會以靜態引數呼叫，從而提供針對注入攻擊的保護。

例如一個 SQL 查詢函式 (query function) 可以被標註為：

@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)               # 型別檢查器錯誤
    run_query(                                # 型別檢查器錯誤
        f"SELECT * FROM students WHERE name = @{arbitrary_string@}"
    )
@end example

詳情請見 
@geindex Python Enhancement Proposals; PEP 675
PEP 675@footnote{https://peps.python.org/pep-0675/}。

（由 Jelle Zijlstra 於 bpo-47088@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47088} 中所貢獻。PEP 由 Pradeep Kumar Srinivasan 與 Graham Bleaney 所撰寫）

@node PEP 681：資料類別轉換 Data class transforms,PEP 563 可能不是未來,PEP 675：任意的文本字串型別 Arbitrary literal string type,型別提示相關的新特性<2>
@anchor{whatsnew/3 11 pep-681-data-class-transforms}@anchor{7e0}@anchor{whatsnew/3 11 whatsnew311-pep681}@anchor{7c1}
@subsubsection PEP 681：資料類別轉換 (Data class transforms)


@ref{6f4,,dataclass_transform} 可以用來裝飾一個類別、元類別 (metaclass)、或是一個本身就是裝飾器的函式。@code{@@dataclass_transform()} 的存在會讓一個靜態型別檢查器知道被裝飾物件會在運行程式做出轉換類別的「魔法」，賦予其類似 @ref{4dc,,dataclass} 的行為。

舉例來說：

@example
# create_model 裝飾器是由一個函式庫定義。
@@typing.dataclass_transform()
def create_model(cls: Type[T]) -> Type[T]:
    cls.__init__ = ...
    cls.__eq__ = ...
    cls.__ne__ = ...
    return cls

# create_model 裝飾器現在可以被用來建立新的模型類別：
@@create_model
class CustomerModel:
    id: int
    name: str

c = CustomerModel(id=327, name="Eric Idle")
@end example

詳情請見 
@geindex Python Enhancement Proposals; PEP 681
PEP 681@footnote{https://peps.python.org/pep-0681/}。

（由 Jelle Zijlstra 於 gh-91860@footnote{https://github.com/python/cpython/issues/91860} 中所貢獻。PEP 由 Erik De Bonte 與 Eric Traut 所撰寫）

@node PEP 563 可能不是未來,,PEP 681：資料類別轉換 Data class transforms,型別提示相關的新特性<2>
@anchor{whatsnew/3 11 pep-563-may-not-be-the-future}@anchor{7e1}@anchor{whatsnew/3 11 whatsnew311-pep563-deferred}@anchor{7e2}
@subsubsection PEP 563 可能不是未來


@geindex Python Enhancement Proposals; PEP 563
PEP 563@footnote{https://peps.python.org/pep-0563/} 推遲對註釋的求值 (Postponed Evaluation of Annotations)（@code{from __future__ import annotations} @ref{45b,,future 陳述式}）最初計劃在 Python 3.10 中發布，但已被無限期擱置。請參閱來自指導委員會 (Steering Counsil) 的訊息@footnote{https://mail.python.org/archives/list/python-dev@@python.org/message/VIZEBX5EYMSYIJNDBF6DMUMZOCWHARSO/}以獲得更多資訊。

@node 其他語言更動<3>,其他 CPython 實作更動,型別提示相關的新特性<2>,Python 3 11 有什麼新功能
@anchor{whatsnew/3 11 other-language-changes}@anchor{7e3}@anchor{whatsnew/3 11 whatsnew311-other-lang-changes}@anchor{7e4}
@subsection 其他語言更動



@itemize *

@item 
星號拆解 (starred unpacking) 運算式現在可以在 @ref{348,,for} 陳述式中使用。（詳情請見 bpo-46725@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46725}。）

@item 
非同步@ref{7e5,,綜合運算 (comprehension)} 現在允許在@ref{7e6,,非同步函式中的內部綜合運算 (inside comprehension)}。在這種情況下，外部綜合運算 (outer comprehension) 隱晦地變成了非同步的了。（由 Serhiy Storchaka 在 bpo-33346@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33346} 中貢獻。）

@item 
現在在不支援 @ref{1e1,,context manager} 協定的物件上使用 @ref{186,,with} 陳述式和 @ref{7e7,,contextlib.ExitStack.enter_context()} 或在不支援 @ref{7e8,,asynchronous context manager} 協定的物件上使用 @ref{185,,async with} 陳述式和 @ref{7e9,,contextlib.AsyncExitStack.enter_async_context()}，會引發 @ref{198,,TypeError} 而不是 @ref{5e8,,AttributeError}。（由 Serhiy Storchaka 在 bpo-12022@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12022} 和 bpo-44471@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44471} 中貢獻。）

@item 
Added @ref{7ea,,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{343,,bytearray}, @ref{184,,set}, @ref{7eb,,frozenset},
@ref{7ec,,collections.OrderedDict}, @ref{7ed,,collections.deque},
@ref{7ee,,weakref.WeakSet}, and @ref{7ef,,datetime.tzinfo} now copies and
pickles instance attributes implemented as @ref{7f0,,slots}.
This change has an unintended side effect: It trips up a small minority
of existing Python projects not expecting @ref{7ea,,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{7bc}

@itemize *

@item 
新增了一個 @ref{7ba,,-P} 命令列選項和一個 
@geindex PYTHONSAFEPATH
@geindex 環境變數; PYTHONSAFEPATH
@ref{7bb,,PYTHONSAFEPATH} 環境變數，它們禁用了當使用 @ref{1a8,,-c} 和 @ref{23c,,-m} 以在運行腳本或目前目錄時自動添加到腳本目錄的 @ref{3e2,,sys.path}。這確保只有 stdlib 和已安裝的模組會被 @ref{7f1,,import} 取用，以避免不小心或被惡意地將模組與本地（通常是使用者可寫入的）目錄中的模組重疊。（由 Victor Stinner 在 gh-57684@footnote{https://github.com/python/cpython/issues/57684} 中貢獻。）

@item 
@code{"z"} 選項被新增到 @ref{4f4,,格式規格 (Format Specification) 迷你語言}，它會強迫負的 0 在進位到格式精度後成為正的。更多詳情請見 
@geindex Python Enhancement Proposals; PEP 682
PEP 682@footnote{https://peps.python.org/pep-0682/}。（由 John Belmonte 於 gh-90153@footnote{https://github.com/python/cpython/issues/90153} 中貢獻。）

@item 
@ref{3e2,,sys.path} 不再接受位元組。支援已在 Python 3.2 和 3.6 之間的某個時間停止，直到 Python 3.10.0 發布後才引起人們的注意。此外，由於混合使用 @ref{169,,str} 和 @ref{192,,bytes} 鍵時 @ref{7f2,,-b} 和 @ref{7f3,,sys.path_importer_cache} 會出現的交互作用，恢復這項支援會出現問題。（由 Thomas Grainger 在 gh-91181@footnote{https://github.com/python/cpython/issues/91181} 中貢獻。）
@end itemize

@node 其他 CPython 實作更動,新增模組<3>,其他語言更動<3>,Python 3 11 有什麼新功能
@anchor{whatsnew/3 11 other-cpython-implementation-changes}@anchor{7f4}@anchor{whatsnew/3 11 whatsnew311-other-implementation-changes}@anchor{7f5}
@subsection 其他 CPython 實作更動



@itemize *

@item 
為支援 @ref{7f6,,typing.SupportsComplex} 與 @ref{7f7,,typing.SupportsBytes} 協定，實作了 @ref{197,,complex} 與 @ref{192,,bytes} 的特殊方法 @ref{7f8,,__complex__()} 與 @ref{7f9,,__bytes__()}。（由 Mark Dickinson 和 Donghee Na 於 bpo-24234@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24234} 中所貢獻。）

@item 
新增 @code{siphash13} 以作為內部的雜湊演算法，它有與 @code{siphash24} 相似的安全特性，但是在處理較長的輸入時會更快一些。現在是 @ref{169,,str}、@ref{192,,bytes} 和一些其他型別的 @ref{7fa,,hash()} 預設演算法。
@geindex Python Enhancement Proposals; PEP 552
PEP 552@footnote{https://peps.python.org/pep-0552/} @ref{7fb,,基於雜湊的 .pyc 檔案} 現在也使用 @code{siphash13}。（由 Inada Naoki 於 bpo-29410@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29410} 中貢獻。）

@item 
當一個仍有效的例外被 @ref{7fc,,raise} 陳述式在沒有參數的情況下重新引發，被附於該例外的追蹤資訊現在都會是 @code{sys.exc_info()[1].__traceback__}。這代表對於目前 @ref{1ab,,except} 子句的追蹤上做的改動會反映在被重複引發的例外上。（由 Irit Katriel 於 bpo-45711@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45711} 中貢獻。）

@item 
有被處理的例外在直譯器狀態的表示（也就是 @code{exc_info} 或 @code{_PyErr_StackItem}）現在只會有 @code{exc_value} 欄位；@code{exc_type} 和 @code{exc_traceback} 已被移除，現在只能透過 @code{exc_value} 來取得它們。（由 Irit Katriel 於 bpo-45711@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45711} 中貢獻。）

@item 
新增@ref{7fd,,命令列選項} @code{AppendPath}，已增加於 Windows 安裝程式。它的行為類似於 @code{PrependPath}，但在安裝和腳本目錄後面附加而非新增於它們前面。（由 Bastian Neuburger 在 bpo-44934@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44934} 中貢獻。）

@item 
初始化中若是要用 @ref{63b,,PyConfig.module_search_paths} 來初始化 @ref{3e2,,sys.path}，則現在 @ref{7fe,,PyConfig.module_search_paths_set} 必須被設為 1。否則，初始化會重新計算路徑並取代所有被加到 @code{module_search_paths} 的值。

@item 
@ref{7ff,,--help} 選項的輸出現在會在 50 列、80 欄的大小之內，@ref{800,,Python 環境變數}和 @ref{16f,,-X} 選項的資訊現在能夠分別透過 @ref{801,,--help-env} 和 @ref{802,,--help-xoptions} 旗標與 @ref{803,,--help-all} 一起使用來取得。（由 Éric Araujo 於 bpo-46142@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46142} 中貢獻。）

@item 
在除 2（binary、二進制）、4、8（octal、八進制）、16（hexadecimal、十六進制）或 32 以外的基數中，例如以 10（decimal、十進制）為基數，進行 @ref{19b,,int} 和 @ref{169,,str} 之間的轉換且字串形式的位數超過限制，現在會引發 @ref{2eb,,ValueError}，以避免由於演算法複雜性而導致的潛在阻斷服務攻擊 (denial of service attacks)。這是針對 
@geindex Common Vulnerabilities and Exposures; CVE 2020-10735
CVE 2020-10735@footnote{https://www.cve.org/CVERecord?id=CVE-2020-10735} 的緩解措施，可以透過環境變數、命令列旗標或 @ref{df,,sys} API 來設定或禁用此限制。請參閱@ref{804,,整數字串轉換長度限制} 文件。預設限制為字串形式的 4300 位數字。
@end itemize

@node 新增模組<3>,改進的模組<3>,其他 CPython 實作更動,Python 3 11 有什麼新功能
@anchor{whatsnew/3 11 new-modules}@anchor{805}@anchor{whatsnew/3 11 whatsnew311-new-modules}@anchor{806}
@subsection 新增模組



@itemize *

@item 
@ref{102,,tomllib}：用於剖析 TOML@footnote{https://toml.io/}。詳情請見 
@geindex Python Enhancement Proposals; PEP 680
PEP 680@footnote{https://peps.python.org/pep-0680/}。（由 Taneli Hukkinen 於 bpo-40059@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40059} 中所貢獻。）

@item 
@ref{122,,wsgiref.types}：
@geindex Python Enhancement Proposals; PEP 3333
WSGI@footnote{https://peps.python.org/pep-3333/} 限定型別，用於靜態型別檢查。（Sebastian Rittau 於 bpo-42012@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42012} 中所貢獻。）
@end itemize

@node 改進的模組<3>,最佳化<4>,新增模組<3>,Python 3 11 有什麼新功能
@anchor{whatsnew/3 11 improved-modules}@anchor{807}@anchor{whatsnew/3 11 whatsnew311-improved-modules}@anchor{808}
@subsection 改進的模組


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

@end menu

@node asyncio<6>,contextlib,,改進的模組<3>
@anchor{whatsnew/3 11 asyncio}@anchor{809}@anchor{whatsnew/3 11 whatsnew311-asyncio}@anchor{80a}
@subsubsection asyncio



@itemize *

@item 
添加了 @ref{4cc,,TaskGroup} 類別，為一個會持有任務群組並在退出時等待全部完成的@ref{80b,,非同步情境管理器 (asynchronous context manager)}。對於新程式碼，建議直接使用 @ref{1c9,,create_task()} 和 @ref{80c,,gather()}。（由 Yury Selivanov 和其他人在 gh-90908@footnote{https://github.com/python/cpython/issues/90908} 中貢獻。）

@item 
新增 @ref{80d,,timeout()}，是一個用來為一個非同步操作設置超時的非同步情境管理器，新的程式建議直接使用它以取代 @ref{80e,,wait_for()}。（由 Andrew Svetlov 於 gh-90927@footnote{https://github.com/python/cpython/issues/90927} 貢獻。）

@item 
新增 @ref{2f4,,Runner} 類別，它會對外公布了 @ref{2f2,,run()} 的使用機制。（由 Andrew Svetlov 於 gh-91218@footnote{https://github.com/python/cpython/issues/91218} 貢獻。）

@item 
於 asyncio 函式庫的同步化原始物件中新增 @ref{80f,,Barrier} 類別與和其相關的 @ref{810,,BrokenBarrierError} 例外。（由 Yves Duprat 和 Andrew Svetlov in gh-87518@footnote{https://github.com/python/cpython/issues/87518} 貢獻。）

@item 
在 @ref{811,,asyncio.loop.create_connection()} 新增關鍵字引數 `all_errors'，這樣多個連接錯誤就可以一起用一個 @ref{4cd,,ExceptionGroup} 來引發。

@item 
新增 @ref{812,,asyncio.StreamWriter.start_tls()} 方法，用來將已存在的串流連線升級至 TLS。（由 Ian Good 於 bpo-34975@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34975} 中貢獻。）

@item 
在事件迴圈增加原始資料元 (raw datagram) socket 函式：@ref{813,,sock_sendto()}、@ref{814,,sock_recvfrom()} 和 @ref{815,,sock_recvfrom_into()}。以上在 @ref{313,,SelectorEventLoop} 和 @ref{816,,ProactorEventLoop} 中都有實作。（由 Alex Grönholm 在 bpo-46805@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46805} 中貢獻。）

@item 
於 @ref{1c7,,Task} 新增 @ref{4d0,,cancelling()} 和 @ref{4d1,,uncancel()} 方法。這些預期是只用於內部，尤其是 @ref{4cc,,TaskGroup}。
@end itemize

@node contextlib,dataclasses,asyncio<6>,改進的模組<3>
@anchor{whatsnew/3 11 contextlib}@anchor{817}@anchor{whatsnew/3 11 whatsnew311-contextlib}@anchor{818}
@subsubsection contextlib



@itemize *

@item 
添加了非平行安全的 @ref{819,,chdir()} 情境管理器來更改目前工作目錄，然後在退出時恢復它。@ref{81a,,chdir()} 的簡單包裝器。（由 Filipe Laíns 在 bpo-25625@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25625} 中貢獻）
@end itemize

@node dataclasses,datetime<2>,contextlib,改進的模組<3>
@anchor{whatsnew/3 11 dataclasses}@anchor{81b}@anchor{whatsnew/3 11 whatsnew311-dataclasses}@anchor{81c}
@subsubsection dataclasses



@itemize *

@item 
更改欄位預設的可變性檢查 (mutability check)，僅允許預設值是 @ref{81d,,hashable} 而不是任何非 @ref{183,,dict}、@ref{24d,,list} 或 @ref{184,,set} 實例的物件。（由 Eric V. Smith 在 bpo-44674@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44674} 中貢獻。）
@end itemize

@node datetime<2>,enum<3>,dataclasses,改進的模組<3>
@anchor{whatsnew/3 11 datetime}@anchor{81e}@anchor{whatsnew/3 11 whatsnew311-datetime}@anchor{81f}
@subsubsection datetime



@itemize *

@item 
新增 @ref{70c,,datetime.UTC}，一個 @ref{820,,datetime.timezone.utc} 的方便別名。（由 Kabir Kwatra 於 gh-91973@footnote{https://github.com/python/cpython/issues/91973} 所貢獻。）

@item 
@ref{821,,datetime.date.fromisoformat()}、@ref{822,,datetime.time.fromisoformat()} 和 @ref{823,,datetime.datetime.fromisoformat()} 現在可以用來剖析大部分的 ISO 8601 格式（除了那些支援分數形式的小時與分鐘）。（由 Paul Ganssle 於 gh-80010@footnote{https://github.com/python/cpython/issues/80010} 中所貢獻。）
@end itemize

@node enum<3>,fcntl,datetime<2>,改進的模組<3>
@anchor{whatsnew/3 11 enum}@anchor{824}@anchor{whatsnew/3 11 whatsnew311-enum}@anchor{825}
@subsubsection enum



@itemize *

@item 
@code{EnumMeta} 更名為 @ref{4f2,,EnumType}（@code{EnumMeta} 保留為別名）。

@item 
增加 @ref{826,,StrEnum}，列舉 (enum) 內的成員必須是字串。

@item 
新增 @ref{827,,ReprEnum}，它只修改成員的 @ref{828,,__repr__()}，同時回傳成員的文本值 (literal value)（而不是名稱），以用於（為 @ref{169,,str()}、@ref{199,,format()} 和 @ref{663,,f-string} 所使用的）@ref{829,,__str__()} 和 @ref{82a,,__format__()}。

@item 
改變了 @ref{82b,,Enum.__format__()} （被 @ref{199,,format()}、@ref{82c,,str.format()} 和 @ref{663,,f-string} 預設使用），以使其與 @ref{82d,,enum.Enum.__str__} 產生相同結果：對於繼承自 @ref{827,,ReprEnum} 的列舉，這會是成員之值；而其他的列舉會是列舉與成員名稱（例如 @code{Color.RED}）。

@item 
新增 `boundary' 類別參數與其選項到 @ref{82e,,Flag} 列舉和 @ref{82f,,FlagBoundary} 列舉以控制處理超出範圍旗標數值的方法。

@item 
新增了 @ref{830,,verify()} 列舉裝飾器和 @ref{831,,EnumCheck} 列舉及其選項，以根據幾個特定限制檢查列舉類別。

@item 
新增 @ref{832,,member()} 與 @ref{833,,nonmember()} 裝飾器以確保被裝飾的物件會/不會被轉換成一個列舉成員。

@item 
新增 @ref{834,,property()} 裝飾器，它的作用類似 @ref{4ae,,property()} 但是是用於列舉，用以替代 @ref{835,,types.DynamicClassAttribute()}。

@item 
新增 @ref{836,,global_enum()} 列舉裝飾器，用來調整 @ref{828,,__repr__()} 和 @ref{829,,__str__()} 以模組成員形式而非列舉類別來顯示值。例如，@ref{837,,re.RegexFlag} 的 @ref{838,,ASCII} 成員的 @code{'re.ASCII'}，而非 @code{'RegexFlag.ASCII'}。

@item 
強化 @ref{82e,,Flag} 以支援使用 @ref{839,,len()}、疊代 (iteration) 和 @ref{349,,in}/@ref{83a,,not in} 於其成員。例如，以下程式現在能夠作用了：@code{len(AFlag(3)) == 2 and list(AFlag(3)) == (AFlag.ONE, AFlag.TWO)}

@item 
更改了 @ref{83b,,Enum} 和 @ref{82e,,Flag} 以在呼叫 @ref{83c,,__init_subclass__()} 之前就定義成員；@ref{83d,,dir()} 現在包括來自混合資料型別的方法。

@item 
更改 @ref{82e,,Flag} 以僅考慮主要值（2 的次方）規範，而複合值（@code{3}、@code{6}、@code{10} 等）被視為別名；倒置旗標 (inverted flags) 會被強制轉換為正等價的值。
@end itemize

@node fcntl,fractions<4>,enum<3>,改進的模組<3>
@anchor{whatsnew/3 11 fcntl}@anchor{83e}@anchor{whatsnew/3 11 whatsnew311-fcntl}@anchor{83f}
@subsubsection fcntl



@itemize *

@item 
FreeBSD 上，@code{F_DUP2FD} 和 @code{F_DUP2FD_CLOEXEC} 旗標分別有被支援，前者等同於 @code{dup2} 用法，而後者設定了 @code{FD_CLOEXEC} 旗標。
@end itemize

@node fractions<4>,functools<2>,fcntl,改進的模組<3>
@anchor{whatsnew/3 11 fractions}@anchor{840}@anchor{whatsnew/3 11 whatsnew311-fractions}@anchor{841}
@subsubsection fractions



@itemize *

@item 
支援有 
@geindex Python Enhancement Proposals; PEP 515
PEP 515@footnote{https://peps.python.org/pep-0515/} 風格的 @ref{213,,Fraction} 以字串初始化。（Sergey B Kirpichev 於 bpo-44258@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44258} 中所貢獻。）

@item 
@ref{213,,Fraction} 現在有實作了一個 @code{__int__} 方法，因此 @code{isinstance(some_fraction, typing.SupportsInt)} 的檢查會通過。（由 Mark Dickinson 在 bpo-44547@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44547} 中貢獻。）
@end itemize

@node functools<2>,gzip<2>,fractions<4>,改進的模組<3>
@anchor{whatsnew/3 11 functools}@anchor{842}@anchor{whatsnew/3 11 whatsnew311-functools}@anchor{843}
@subsubsection functools



@itemize *

@item 
@ref{844,,functools.singledispatch()} 現在支援 @ref{2a7,,types.UnionType} 和 @ref{2a8,,typing.Union} 作為調度 (dispatch) 引數的標註。

@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

（由 Yurii Karabas 於 bpo-46014@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46014} 中所貢獻。）
@end itemize

@node gzip<2>,hashlib<2>,functools<2>,改進的模組<3>
@anchor{whatsnew/3 11 gzip}@anchor{845}@anchor{whatsnew/3 11 whatsnew311-gzip}@anchor{846}
@subsubsection gzip



@itemize *

@item 
The @ref{847,,gzip.compress()} function is now faster when used with the
`mtime=0' argument as it delegates the compression entirely to a single
@ref{848,,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{6b,,gzip}
module. Now, when using @ref{847,,compress()} with `mtime=0', it may be
set to a different value by the underlying zlib C library Python was linked
against.
(See gh-112346@footnote{https://github.com/python/cpython/issues/112346} for details on the side effect.)
@end itemize

@node hashlib<2>,IDLE 和 idlelib,gzip<2>,改進的模組<3>
@anchor{whatsnew/3 11 hashlib}@anchor{849}@anchor{whatsnew/3 11 whatsnew311-hashlib}@anchor{84a}
@subsubsection hashlib



@itemize *

@item 
@ref{84b,,hashlib.blake2b()} 與 @ref{84c,,hashlib.blake2s()} 現在偏好使用 libb2@footnote{https://www.blake2.net/} 多於 Python 自發行版的複製。（由 Christian Heimes 於 bpo-47095@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47095} 中所貢獻。）

@item 
帶有 SHA3 和 SHAKE 演算法的內部 @code{_sha3} 模組現在使用 `tiny_sha3' 而不是 `Keccak 程式碼套件'來減少程式碼和二進位檔案大小。@ref{6c,,hashlib} 模組更喜歡來自 OpenSSL 的 SHA3 和 SHAKE 最佳化實作。此更改僅影響沒有 OpenSSL 支援的安裝。（由 Christian Heimes 在 bpo-47098@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47098} 中貢獻。）

@item 
新增 @ref{84d,,hashlib.file_digest()}，是個能夠為檔案或類檔案物件做高效率雜湊的幫助函式。（由 Christian Heimes 於 gh-89313@footnote{https://github.com/python/cpython/issues/89313} 中貢獻。）
@end itemize

@node IDLE 和 idlelib,inspect<3>,hashlib<2>,改進的模組<3>
@anchor{whatsnew/3 11 idle-and-idlelib}@anchor{84e}@anchor{whatsnew/3 11 whatsnew311-idle}@anchor{84f}
@subsubsection IDLE 和 idlelib



@itemize *

@item 
在 @code{.pyi} 檔案施用語法突顯 (syntax highlight)。（由 Alex Waygood 與 Terry Jan Reedy 於 bpo-45447@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45447} 中所貢獻。）

@item 
當帶有輸入與輸出地儲存 Shell 時，也會包含提示字元。（由 Terry Jan Reedy 於 gh-95191@footnote{https://github.com/python/cpython/issues/95191} 中所貢獻。）
@end itemize

@node inspect<3>,locale<3>,IDLE 和 idlelib,改進的模組<3>
@anchor{whatsnew/3 11 inspect}@anchor{850}@anchor{whatsnew/3 11 whatsnew311-inspect}@anchor{851}
@subsubsection inspect



@itemize *

@item 
添加 @ref{852,,getmembers_static()} 以回傳所有成員，而不會通過描述器協定 (descriptor protocol) 觸發動態查找。（由 Weipeng Hong 在 bpo-30533@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30533} 中貢獻。）

@item 
新增 @ref{853,,inspect.ismethodwrapper()}，用來檢查一個物件的型別是否為 @ref{854,,MethodWrapperType}。（由 Hakan Çelik 於 bpo-29418@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29418} 中所貢獻。）

@item 
更改 @ref{82,,inspect} 模組中與幀相關的函式以回傳新的 @ref{855,,FrameInfo} 和 @ref{856,,Traceback} 類別實例（向後相容之前類似於 @ref{857,,named tuple} 的介面），包括擴充的 
@geindex Python Enhancement Proposals; PEP 657
PEP 657@footnote{https://peps.python.org/pep-0657/} 位置資訊（結束行號、欄和結束欄）。受影響的功能是：


@itemize *

@item 
@ref{858,,inspect.getframeinfo()}

@item 
@ref{859,,inspect.getouterframes()}

@item 
@ref{85a,,inspect.getinnerframes()},

@item 
@ref{85b,,inspect.stack()}

@item 
@ref{85c,,inspect.trace()}
@end itemize

（由 Pablo Galindo 於 gh-88116@footnote{https://github.com/python/cpython/issues/88116} 中所貢獻。）
@end itemize

@node locale<3>,logging,inspect<3>,改進的模組<3>
@anchor{whatsnew/3 11 locale}@anchor{85d}@anchor{whatsnew/3 11 whatsnew311-locale}@anchor{85e}
@subsubsection locale



@itemize *

@item 
新增 @ref{328,,locale.getencoding()} 以取得目前的區域編碼 (locale encoding)。和 @code{locale.getpreferredencoding(False)} 類似但不考慮 @ref{85f,,Python UTF-8 模式}。
@end itemize

@node logging,math<4>,locale<3>,改進的模組<3>
@anchor{whatsnew/3 11 logging}@anchor{860}@anchor{whatsnew/3 11 whatsnew311-logging}@anchor{861}
@subsubsection logging



@itemize *

@item 
新增 @ref{862,,getLevelNamesMapping()} 以回傳一個日誌級別名稱（例如 @code{'CRITICAL'}）指到對應的 @ref{863,,Logging Levels} 數值（例如，預設為 @code{50}）的對映。（由 Andrei Kulakovin 於 gh-88024@footnote{https://github.com/python/cpython/issues/88024} 中貢獻。）

@item 
添加了一個 @ref{864,,createSocket()} 方法到 @ref{865,,SysLogHandler}，以匹配 @ref{866,,SocketHandler.createSocket()} 。如果沒有已啟用的 socket，它會在處理程式初始化期間和發出一個事件時自動呼叫。（由 Kirill Pinchuk 在 gh-88457@footnote{https://github.com/python/cpython/issues/88457} 中貢獻。）
@end itemize

@node math<4>,operator<2>,logging,改進的模組<3>
@anchor{whatsnew/3 11 math}@anchor{867}@anchor{whatsnew/3 11 whatsnew311-math}@anchor{868}
@subsubsection math



@itemize *

@item 
新增 @ref{869,,math.exp2()}：回傳 2 的 x 次方。（由 Gideon Mitchell 於 bpo-45917@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45917} 中所貢獻。）

@item 
新增 @ref{86a,,math.cbrt()}：回傳 x 的立方根。（由 Ajith Ramachandran 於 bpo-44357@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44357} 中所貢獻。）

@item 
為了與 IEEE 754 規範保持一致，更改了兩個 @ref{86b,,math.pow()} 邊角案例 (corner case) 的行為。@code{math.pow(0.0, -math.inf)} 和 @code{math.pow(-0.0, -math.inf)} 現在回傳 @code{inf}，之前它們會引發 @ref{2eb,,ValueError}。（由 Mark Dickinson 在 bpo-44339@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44339} 中貢獻。）

@item 
@ref{86c,,math.nan} 現為隨時可用。（由 Victor Stinner 於 bpo-46917@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46917} 中所貢獻。）
@end itemize

@node operator<2>,os<4>,math<4>,改進的模組<3>
@anchor{whatsnew/3 11 operator}@anchor{86d}@anchor{whatsnew/3 11 whatsnew311-operator}@anchor{86e}
@subsubsection operator



@itemize *

@item 
新增 @code{operator.call} 函式，使得 @code{operator.call(obj, *args, **kwargs) == obj(*args, **kwargs)}。（由 Antony Lee 於 bpo-44019@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44019} 中所貢獻。）
@end itemize

@node os<4>,pathlib<7>,operator<2>,改進的模組<3>
@anchor{whatsnew/3 11 os}@anchor{86f}@anchor{whatsnew/3 11 whatsnew311-os}@anchor{870}
@subsubsection os



@itemize *

@item 
在 Windows 上，@ref{73f,,os.urandom()} 現在使用 @code{BCryptGenRandom()} 以取代被棄用的 @code{CryptGenRandom()}。（由 Donghee Na 於 bpo-44611@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44611} 中所貢獻。）
@end itemize

@node pathlib<7>,re<4>,os<4>,改進的模組<3>
@anchor{whatsnew/3 11 pathlib}@anchor{871}@anchor{whatsnew/3 11 whatsnew311-pathlib}@anchor{872}
@subsubsection pathlib



@itemize *

@item 
如果 `pattern' 以路徑名稱元件分隔符號 @ref{873,,sep} 或 @ref{874,,altsep} 結尾，@ref{532,,glob()} 和 @ref{533,,rglob()} 只回傳目錄。（由 Eisuke Kawasima 於 bpo-22276@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22276} 與 bpo-33392@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33392} 中所貢獻。）
@end itemize

@node re<4>,shutil<3>,pathlib<7>,改進的模組<3>
@anchor{whatsnew/3 11 re}@anchor{875}@anchor{whatsnew/3 11 whatsnew311-re}@anchor{876}
@subsubsection re



@itemize *

@item 
現在正規表示式 (regular expression) 是有支援原子性群組 (atomic grouping) (@code{(?>...)}) 和佔有性量詞 (possessive quantifier) (@code{*+}, @code{++}, @code{?+}, @code{@{m,n@}+}) 的。（由 Jeffrey C. Jacobs 和 Serhiy Storchaka 在 bpo-433030@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=433030} 中貢獻。）
@end itemize

@node shutil<3>,socket<2>,re<4>,改進的模組<3>
@anchor{whatsnew/3 11 shutil}@anchor{877}@anchor{whatsnew/3 11 whatsnew311-shutil}@anchor{878}
@subsubsection shutil



@itemize *

@item 
新增 @ref{354,,shutil.rmtree()} 的可選參數 `dir_fd'。（由 Serhiy Storchaka 於 bpo-46245@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46245} 中所貢獻。）
@end itemize

@node socket<2>,sqlite3<5>,shutil<3>,改進的模組<3>
@anchor{whatsnew/3 11 socket}@anchor{879}@anchor{whatsnew/3 11 whatsnew311-socket}@anchor{87a}
@subsubsection socket



@itemize *

@item 
新增 NetBSD 對於 CAN Socket 的支援。（由 Thomas Klausner 於 bpo-30512@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30512} 中所貢獻。）

@item 
當連接失敗時，@ref{87b,,create_connection()} 有個選項可以引發一個包含所有錯誤的 @ref{4cd,,ExceptionGroup}，而非只引發最後一個錯誤。（由 Irit Katriel 於 bpo-29980@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29980} 中貢獻。）
@end itemize

@node sqlite3<5>,string,socket<2>,改進的模組<3>
@anchor{whatsnew/3 11 sqlite3}@anchor{87c}@anchor{whatsnew/3 11 whatsnew311-sqlite3}@anchor{87d}
@subsubsection sqlite3



@itemize *

@item 
現在可以透過將 @ref{87e,,None} 傳遞給 @ref{5a3,,set_authorizer()} 來停用 authorizer。（由  Erlend E. Aasland 於 bpo-44491@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44491} 中貢獻。）

@item 
定序 (collation) 名稱 @ref{87f,,create_collation()} 現在可以包含任何 Unicode 字元。帶有無效字元的定序名稱現在會引發 @ref{880,,UnicodeEncodeError} 而不是 @ref{304,,sqlite3.ProgrammingError}。（由 Erlend E. Aasland 在 bpo-44688@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44688} 中貢獻。）

@item 
@ref{d4,,sqlite3} 例外現在包含 SQLite 擴充錯誤碼和 SQLite 錯誤名稱（分別為 @ref{881,,sqlite_errorcode} 和 @ref{882,,sqlite_errorname}）。（由 Aviv Palivoda、Daniel Shahaf 和 Erlend E. Aasland 在 bpo-16379@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16379} 和 bpo-24139@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24139} 中貢獻。）

@item 
將 @ref{883,,setlimit()} 和 @ref{884,,getlimit()} 新增到 @ref{548,,sqlite3.Connection} 以根據連線來設定和取得 SQLite 限制。（由 Erlend E. Aasland 在 bpo-45243@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45243} 中貢獻。）

@item 
@ref{d4,,sqlite3} 現在會基於底層 SQLite 函式庫編譯時所使用的預設執行緒模式來設定 @ref{885,,sqlite3.threadsafety}。（由 Erlend E. Aasland 在 bpo-45613@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45613} 中貢獻。）

@item 
@ref{d4,,sqlite3} 如果啟用回呼回溯 (callback traceback)，C 回呼現在使用無法被引發的例外。使用者現在可以註冊一個@ref{502,,無法被引發的掛鈎處理程式 (unraisable hook handler)} 來改善他們的除錯體驗。（由 Erlend E. Aasland 在 bpo-45828@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45828} 中貢獻。）

@item 
跨越不同回滾 (rollback) 的拿取動作不再引發 @ref{886,,InterfaceError}，我們將其留給 SQLite 函式庫來處理這些情況。（由 Erlend E. Aasland 在 bpo-44092@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44092} 中貢獻。）

@item 
將 @ref{887,,serialize()} 和 @ref{888,,deserialize()} 新增到 @ref{548,,sqlite3.Connection} 以用於序列化和反序列化資料庫。（由 Erlend E. Aasland 在 bpo-41930@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41930} 中貢獻。）

@item 
於 @ref{548,,sqlite3.Connection} 加入 @ref{889,,create_window_function()} 已建立聚合視窗函式 (aggregate window function)。（由 Erlend E. Aasland 於 bpo-34916@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34916} 中貢獻。）

@item 
在 @ref{548,,sqlite3.Connection} 新增 @ref{88a,,blobopen()}。 @ref{88b,,sqlite3.Blob} 允許對 blob 進行增量 I/O 操作 (incremental I/O operations)。（由 Aviv Palivoda 和 Erlend E. Aasland 在 bpo-24905@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24905} 中貢獻。）
@end itemize

@node string,sys<4>,sqlite3<5>,改進的模組<3>
@anchor{whatsnew/3 11 string}@anchor{88c}@anchor{whatsnew/3 11 whatsnew311-string}@anchor{88d}
@subsubsection string



@itemize *

@item 
新增 @ref{88e,,get_identifiers()} 和 @ref{88f,,is_valid()} 於 @ref{890,,string.Template}，分別能夠回傳所有合格的預留位置 (placeholder) 與是否有任何不合格的預留位置存在。（由 Ben Kehoe 於 gh-90465@footnote{https://github.com/python/cpython/issues/90465} 中貢獻。）
@end itemize

@node sys<4>,sysconfig<2>,string,改進的模組<3>
@anchor{whatsnew/3 11 sys}@anchor{891}@anchor{whatsnew/3 11 whatsnew311-sys}@anchor{892}
@subsubsection sys



@itemize *

@item 
@ref{893,,sys.exc_info()} 現在從 @code{value}（例外實例）衍生出 @code{type} 和 @code{traceback} 欄位，因此當例外在處理過程中被修改時，變更會反映在 @code{exc_info()} 後續呼叫的結果中。（由 Irit Katriel 在 bpo-45711@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45711} 中貢獻。）

@item 
新增會回傳活躍例外實例 (active exception instance) 的 @ref{894,,sys.exception()}（等價於 @code{sys.exc_info()[1]}）。（由 Irit Katriel 於 bpo-46328@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46328} 中所貢獻。）

@item 
新增 @ref{895,,sys.flags.safe_path} 旗標。（由 Victor Stinner 於 gh-57684@footnote{https://github.com/python/cpython/issues/57684} 中所貢獻。）
@end itemize

@node sysconfig<2>,tempfile<3>,sys<4>,改進的模組<3>
@anchor{whatsnew/3 11 sysconfig}@anchor{896}@anchor{whatsnew/3 11 whatsnew311-sysconfig}@anchor{897}
@subsubsection sysconfig



@itemize *

@item 
新增了三個@ref{447,,安裝方案}（`posix_venv'、`nt_venv' 和 `venv'），它們在 Python 建立新的虛擬環境或在虛擬環境中執行環境使用。前兩個方案（`posix_venv' 和 `nt_venv'）是非 Windows 和 Windows 作業系統所特有的，`venv' 本質上會根據 Python 運行的作業系統來做為其中之一的別名。這對修改 @ref{898,,sysconfig.get_preferred_scheme()} 的下游發布者很有用。建立新虛擬環境的第三方程式碼應該使用新的 `venv' 安裝方案來確定路徑，就像 @ref{117,,venv} 一樣。（由 Miro Hrončok 在 bpo-45413@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45413} 中貢獻。）
@end itemize

@node tempfile<3>,threading<3>,sysconfig<2>,改進的模組<3>
@anchor{whatsnew/3 11 tempfile}@anchor{899}@anchor{whatsnew/3 11 whatsnew311-tempfile}@anchor{89a}
@subsubsection tempfile



@itemize *

@item 
@ref{89b,,SpooledTemporaryFile} 物件現在完整實作了 @ref{89c,,io.BufferedIOBase} 或 @ref{89d,,io.TextIOBase} 的方法（取決於檔案模式），這使它們能夠正確地使用需要類檔案物件的 API，例如壓縮模組。（由 Carey Metcalfe 在 gh-70363@footnote{https://github.com/python/cpython/issues/70363} 中貢獻。）
@end itemize

@node threading<3>,time<2>,tempfile<3>,改進的模組<3>
@anchor{whatsnew/3 11 threading}@anchor{89e}@anchor{whatsnew/3 11 whatsnew311-threading}@anchor{89f}
@subsubsection threading



@itemize *

@item 
在 Unix 上，如果 @code{sem_clockwait()} 函式在 C 函式庫（glibc 2.30 與其更新的版本）中可被使用，則 @ref{8a0,,threading.Lock.acquire()} 方法現在會使用單調時鐘 (@code{time. CLOCK_MONOTONIC}) 用於超時 (timeout)，而不是使用系統時鐘 (@ref{8a1,,time.CLOCK_REALTIME})，以免受系統時鐘變化的影響。 由 Victor Stinner 在 bpo-41710@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41710} 中貢獻。）
@end itemize

@node time<2>,tkinter<4>,threading<3>,改進的模組<3>
@anchor{whatsnew/3 11 time}@anchor{8a2}@anchor{whatsnew/3 11 whatsnew311-time}@anchor{8a3}
@subsubsection time



@itemize *

@item 
在 Unix 上，如果可用的話，@ref{8a4,,time.sleep()} 現在會使用 @code{clock_nanosleep()} 或 @code{nanosleep()} 函式，其解析度為 1 納秒（10@w{^-9} 秒），而不是使用解析度為 1 微秒（10@w{^-6} 秒）的 @code{select()}。（由 Benjamin Szőke 和 Victor Stinner 在 bpo-21302@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21302} 中貢獻。）

@item 
在 Windows 8.1 或更新的平台上，@ref{8a4,,time.sleep()} 現在使用了一個基於高解析度計時器@footnote{https://docs.microsoft.com/en-us/windows-hardware/drivers/kernel/high-resolution-timers}的可等待 (waitable) 計時器，解析度為 100 奈秒（即 10@w{^-7} 秒）。在這之前，它只有 1 微秒（10@w{^-3} 秒） 的解析度。（由 Benjamin Szőke、Donghee Na、Eryk Sun 和 Victor Stinner 於 bpo-21302@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21302} 與 bpo-45429@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45429} 中貢獻。）
@end itemize

@node tkinter<4>,traceback<2>,time<2>,改進的模組<3>
@anchor{whatsnew/3 11 tkinter}@anchor{8a5}@anchor{whatsnew/3 11 whatsnew311-tkinter}@anchor{8a6}
@subsubsection tkinter



@itemize *

@item 
新增了 @code{info_patchlevel()} 方法，它會回傳 Tcl 函式庫的確切版本以作為類似於 @ref{8a7,,sys.version_info} 的附名元組。（由 Serhiy Storchaka 在 gh-91827@footnote{https://github.com/python/cpython/issues/91827} 中貢獻。）
@end itemize

@node traceback<2>,typing<5>,tkinter<4>,改進的模組<3>
@anchor{whatsnew/3 11 traceback}@anchor{8a8}@anchor{whatsnew/3 11 whatsnew311-traceback}@anchor{8a9}
@subsubsection traceback



@itemize *

@item 
新增 @ref{8aa,,traceback.StackSummary.format_frame_summary()} 以允許使用者覆蓋回溯中出現的幀及它們的格式。（由 Ammar Askar 在 bpo-44569@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44569} 中貢獻。）

@item 
新增 @ref{8ab,,traceback.TracebackException.print()}，它會印出格式化的 @ref{55d,,TracebackException} 實例至一個檔案。（由 Irit Katriel 在 bpo-33809@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33809} 中貢獻。）
@end itemize

@node typing<5>,unicodedata<4>,traceback<2>,改進的模組<3>
@anchor{whatsnew/3 11 typing}@anchor{8ac}@anchor{whatsnew/3 11 whatsnew311-typing}@anchor{8ad}
@subsubsection typing


重大變更請見 @ref{7d4,,型別提示相關的新特性}。


@itemize *

@item 
新增 @ref{8ae,,typing.assert_never()} 和 @ref{8af,,typing.Never}。 @ref{8ae,,typing.assert_never()} 可用於要型別檢查器確認某行程式碼是否不可觸及。在執行環境，它會引發 @ref{8b0,,AssertionError}。（由 Jelle Zijlstra 在 gh-90633@footnote{https://github.com/python/cpython/issues/90633} 中貢獻。）

@item 
新增 @ref{8b1,,typing.reveal_type()}，這可用於請求型別檢查器為給定運算式推斷出什麼型別。在執行環境它會印出接收到的值的型別。（由 Jelle Zijlstra 在 gh-90572@footnote{https://github.com/python/cpython/issues/90572} 中貢獻。）

@item 
新增 @ref{8b2,,typing.assert_type()}，這可用於要型別檢查器確認它為給定運算式推斷的型別是否與給定型別相符。在執行環境，它只會回傳接收到的值。（由 Jelle Zijlstra 在 gh-90638@footnote{https://github.com/python/cpython/issues/90638} 中貢獻。）

@item 
@ref{331,,typing.TypedDict} 型別現可為泛型。（由 Samodya Abeysiriwardane 於 gh-89026@footnote{https://github.com/python/cpython/issues/89026} 中所貢獻。）

@item 
@ref{330,,NamedTuple} 型別現可為泛型。（由 Serhiy Storchaka 於 bpo-43923@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43923} 中所貢獻。）

@item 
允許繼承 @ref{8b3,,typing.Any}，這能有效避免與高度動態類別（例如 mock）相關的型別檢查器錯誤。（由 Shantanu Jain 在 gh-91154@footnote{https://github.com/python/cpython/issues/91154} 中貢獻。）

@item 
@ref{8b4,,typing.final()} 裝飾器現在會在被裝飾的物件上設定 @code{__final__} 屬性。（由 Serhiy Storchaka 於 gh-90500@footnote{https://github.com/python/cpython/issues/90500} 中所貢獻。）

@item 
@ref{8b5,,typing.get_overloads()} 函式可用於自我檢查 (introspect) 一個函式的過載 (overload)。@ref{8b6,,typing.clear_overloads()} 可用於清除一個函式的所有已註冊過載。（由 Jelle Zijlstra 在 gh-89263@footnote{https://github.com/python/cpython/issues/89263} 中貢獻。）

@item 
@ref{565,,Protocol} 子類別的 @ref{8b7,,__init__()} 方法現在被保留。（由 Adrian Garcia Badarasco 在 gh-88970@footnote{https://github.com/python/cpython/issues/88970} 中貢獻。）

@item 
空元組型別 (@code{Tuple[()]}) 的表示法得到簡化，這會影響自我檢查 (introspection)，例如 @code{get_args(Tuple[()])} 的求值現在會是 @code{()} 而不是 @code{((),)}。（由 Serhiy Storchaka 在 gh-91137@footnote{https://github.com/python/cpython/issues/91137} 中貢獻。）

@item 
通過刪除私有 @code{typing._type_check} 函式中的可呼叫檢查，放寬型別標註的執行環境要求。（由 Gregory Beauregard 在 gh-90802@footnote{https://github.com/python/cpython/issues/90802} 中貢獻。）

@item 
作為@ref{8b8,,PEP 585 泛化別名}中的前向參照，@ref{8b9,,typing.get_type_hints()} 現支援了為字串求值 (evaluate)。（由 Niklas Rosenstein 在 gh-85542@footnote{https://github.com/python/cpython/issues/85542} 中貢獻。）

@item 
@ref{8b9,,typing.get_type_hints()} 不再將 @ref{8ba,,Optional} 新增到預設為 @code{None} 的參數中。（由 Nikita Sobolev 在 gh-90353@footnote{https://github.com/python/cpython/issues/90353} 中貢獻。）

@item 
@ref{8b9,,typing.get_type_hints()} 現在支援為無修飾 (bare) 字串化 (stringified) 的 @ref{567,,ClassVar} 標註來求值。（由 Gregory Beauregard 在 gh-90711@footnote{https://github.com/python/cpython/issues/90711} 中貢獻。）

@item 
@ref{8bb,,typing.no_type_check()} 不再修改外部類別和函式。它現在也正確地將類別方法標記為不需進行型別檢查。（由 Nikita Sobolev 在 gh-90729@footnote{https://github.com/python/cpython/issues/90729} 中貢獻。）
@end itemize

@node unicodedata<4>,unittest<5>,typing<5>,改進的模組<3>
@anchor{whatsnew/3 11 unicodedata}@anchor{8bc}@anchor{whatsnew/3 11 whatsnew311-unicodedata}@anchor{8bd}
@subsubsection unicodedata



@itemize *

@item 
Unicode 資料庫被更新為 14.0.0 版本。（Benjamin Peterson 於 bpo-45190@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45190} 中所貢獻。）
@end itemize

@node unittest<5>,venv<2>,unicodedata<4>,改進的模組<3>
@anchor{whatsnew/3 11 unittest}@anchor{8be}@anchor{whatsnew/3 11 whatsnew311-unittest}@anchor{8bf}
@subsubsection unittest



@itemize *

@item 
新增 @ref{2b3,,TestCase} 類別的 @ref{8c0,,enterContext()} 與 @ref{8c1,,enterClassContext()} 方法、 @ref{35f,,IsolatedAsyncioTestCase} 類別 的 @ref{8c2,,enterAsyncContext()} 方法、@ref{8c3,,unittest.enterModuleContext()} 函式。（由 Serhiy Storchaka 於 bpo-45046@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45046} 貢獻。）
@end itemize

@node venv<2>,warnings<2>,unittest<5>,改進的模組<3>
@anchor{whatsnew/3 11 venv}@anchor{8c4}@anchor{whatsnew/3 11 whatsnew311-venv}@anchor{8c5}
@subsubsection venv



@itemize *

@item 
建立新的 Python 虛擬環境時，`venv' @ref{447,,sysconfig 安裝方案}會被用於確定環境內的路徑。當 Python 在虛擬環境中運行時，預設使用相同的安裝方案。這意味著下游發布者可以在不改變虛擬環境行為的情況下更改預設的 sysconfig 安裝方案。建立新虛擬環境的第三方程式碼也應該這樣做。（由 Miro Hrončok 在 bpo-45413@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45413} 中貢獻。）
@end itemize

@node warnings<2>,zipfile<2>,venv<2>,改進的模組<3>
@anchor{whatsnew/3 11 warnings}@anchor{8c6}@anchor{whatsnew/3 11 whatsnew311-warnings}@anchor{8c7}
@subsubsection warnings



@itemize *

@item 
@ref{179,,warnings.catch_warnings()} 現在接受 @ref{8c8,,warnings.simplefilter()} 的引數，提供了一種更簡潔的方法來在本地端忽略警告或將它們轉換為錯誤。（由 Zac Hatfield-Dodds 在 bpo-47074@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47074} 中貢獻。）
@end itemize

@node zipfile<2>,,warnings<2>,改進的模組<3>
@anchor{whatsnew/3 11 whatsnew311-zipfile}@anchor{8c9}@anchor{whatsnew/3 11 zipfile}@anchor{8ca}
@subsubsection zipfile



@itemize *

@item 
新增了對指定成員名稱編碼的支援，以便在 @ref{8cb,,ZipFile} 的目錄和檔案標頭中讀取元資料 (metadata)。（由 Stephen J. Turnbull 和 Serhiy Storchaka 在 bpo-28080@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28080} 中貢獻。）

@item 
新增 @ref{8cc,,ZipFile.mkdir()} 以在 ZIP 歸檔中建立新的目錄。（由 Sam Ezeh 於 gh-49083@footnote{https://github.com/python/cpython/issues/49083} 貢獻。）

@item 
於 @ref{8cd,,zipfile.Path} 新增 @ref{8ce,,stem}、@ref{8cf,,suffix} 和 @ref{8d0,,suffixes}。（由 Miguel Brito 於 gh-88261@footnote{https://github.com/python/cpython/issues/88261} 貢獻。）
@end itemize

@node 最佳化<4>,更快的 CPython,改進的模組<3>,Python 3 11 有什麼新功能
@anchor{whatsnew/3 11 optimizations}@anchor{8d1}@anchor{whatsnew/3 11 whatsnew311-optimizations}@anchor{8d2}
@subsection 最佳化


這個部分會涵蓋到特定的最佳化，但獨立於擁有自己一個說明的@ref{7b6,,更快的 CPython} 計畫。


@itemize *

@item 
編譯器現在對僅包含格式程式碼 @code{%s}、@code{%r} 和 @code{%a} 的字串文本 (string literal) 進行簡單的 @ref{8d3,,printf 風格 % 格式化 (printf-style % formatting)} 最佳化並使其與相應的 @ref{663,,f-string} 運算式一樣快。（由 Serhiy Storchaka 在 bpo-28307@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28307} 中貢獻。）

@item 
整數除法 (@code{//}) 為了編譯器最佳化而被調校過。現在將 @ref{19b,,int} 除以小於 @code{2**30} 的值時，在 x86-64 上快了大約 20%。（由 Gregory P. Smith 和 Tim Peters 在 gh-90564@footnote{https://github.com/python/cpython/issues/90564} 中貢獻。）

@item 
針對小於 @code{2**30} 的整數，@ref{68e,,sum()} 現在快了將近 30%。（由 Stefan Behnel 於 gh-68264@footnote{https://github.com/python/cpython/issues/68264} 中所貢獻。）

@item 
調整 list 大小在常見情況下增進了效能，為 @ref{8d4,,list.append()} 加快了約 15% 並為簡單的 @ref{8d5,,list comprehension} 加快了高達 20-30%（由 Dennis Sweeney 在 gh-91165@footnote{https://github.com/python/cpython/issues/91165} 中貢獻。）

@item 
當所有鍵都是 Unicode 物件時，字典不儲存雜湊值，減少了 @ref{183,,dict} 的大小。例如，@code{sys.getsizeof(dict.fromkeys("abcdefg"))} 在 64-bit 平台上從 352 位元組減少到 272 位元組（減少 23%）。（由 Inada Naoki 在 bpo-46845@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46845} 中貢獻。）

@item 
使用 @ref{8d6,,asyncio.DatagramProtocol} 以透過 UDP 傳輸大文件時，現在速度提高了幾個數量級，傳輸 ≈60 MiB 檔案的速度提高了 100 多倍。（由 msoxzw 在 gh-91487@footnote{https://github.com/python/cpython/issues/91487} 中貢獻。）

@item 
@ref{92,,math} 函式 @ref{8d7,,comb()} 和 @ref{8d8,,perm()} 針對較大引數現在快了 ≈10 倍（對於更大的 `k' 有更大的加速）。（由 Serhiy Storchaka 在 bpo-37295@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37295} 中貢獻。）

@item 
@ref{d7,,statistics} 函式 @ref{8d9,,mean()}、@ref{8da,,variance()} 和 @ref{8db,,stdev()} 現在會一次性的消耗疊代器，而不是先將它們轉換為 @ref{24d,,list}，這讓速度提升為兩倍並可以節省大量記憶體空間。（由 Raymond Hettinger 在 gh-90415@footnote{https://github.com/python/cpython/issues/90415} 中貢獻。）

@item 
@ref{8dc,,unicodedata.normalize()} 現在在常數時間內規範化 (normalize) 純 ASCII 字串。（由 Donghee Na 在 bpo-44987@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44987} 中貢獻。）
@end itemize

@node 更快的 CPython,CPython 位元組碼變更<4>,最佳化<4>,Python 3 11 有什麼新功能
@anchor{whatsnew/3 11 faster-cpython}@anchor{8dd}@anchor{whatsnew/3 11 whatsnew311-faster-cpython}@anchor{7b6}
@subsection 更快的 CPython


當使用基準量測套裝軟體 pyperformance@footnote{https://github.com/python/pyperformance} 量測並以 GCC 於 Ubuntu Linux 上編譯，Python 3.11 平均比 Python 3.10 快了 25%@footnote{https://github.com/faster-cpython/ideas#published-results}。根據程式工作量可能有所不同，整體加速程度可達 10-60%。

此計畫專注在 Python 的 @ref{8de,,更快的啟動} 和 @ref{8df,,更快的運行程式}。不在此專案內的最佳化被獨立列出在 @ref{8d2,,最佳化}。

@menu
* 更快的啟動:: 
* 更快的運行程式:: 
* 雜項:: 
* FAQ:: 
* 關於:: 

@end menu

@node 更快的啟動,更快的運行程式,,更快的 CPython
@anchor{whatsnew/3 11 faster-startup}@anchor{8e0}@anchor{whatsnew/3 11 whatsnew311-faster-startup}@anchor{8de}
@subsubsection 更快的啟動


@menu
* 凍結引入 (Frozen imports) / 靜態程式碼物件 (Static code objects): 凍結引入 Frozen imports / 靜態程式碼物件 Static code objects. 

@end menu

@node 凍結引入 Frozen imports / 靜態程式碼物件 Static code objects,,,更快的啟動
@anchor{whatsnew/3 11 frozen-imports-static-code-objects}@anchor{8e1}@anchor{whatsnew/3 11 whatsnew311-faster-imports}@anchor{8e2}
@subsubsection 凍結引入 (Frozen imports) / 靜態程式碼物件 (Static code objects)


Python 將@ref{4a5,,位元組碼}於 @ref{8e3,,__pycache__} 目錄中存為快取來加速模組的載入。

在先前的 3.10 中，執行 Python 模組會像是這樣：

@example
Read __pycache__ -> Unmarshal -> Heap allocated code object -> Evaluate
@end example

在 Python 3.11 中，核心模組在 Python 啟動時必須被「凍結」，這意味著它們的@ref{7cb,,程式碼物件}（和位元組碼）是由直譯器靜態分配的。這將模組執行過程中的步驟減少為：

@example
Statically allocated code object -> Evaluate
@end example

在 Python 3.11 中直譯器啟動速度快了 10-15%。這對於使用 Python 所撰寫的短暫程式有著巨大影響。

（由 Eric Snow、Guido van Rossum 與 Kumar Aditya 於多個 issue 中貢獻。）

@node 更快的運行程式,雜項,更快的啟動,更快的 CPython
@anchor{whatsnew/3 11 faster-runtime}@anchor{8e4}@anchor{whatsnew/3 11 whatsnew311-faster-runtime}@anchor{8df}
@subsubsection 更快的運行程式


@menu
* 所需資源更少 (cheaper) 且惰性的 (lazy)) Python 幀 (frame): 所需資源更少 cheaper 且惰性的 lazy Python 幀 frame. 
* 行內 Python 函式呼叫:: 
* PEP 659：特化的適應性直譯器:: 

@end menu

@node 所需資源更少 cheaper 且惰性的 lazy Python 幀 frame,行內 Python 函式呼叫,,更快的運行程式
@anchor{whatsnew/3 11 cheaper-lazy-python-frames}@anchor{8e5}@anchor{whatsnew/3 11 whatsnew311-lazy-python-frames}@anchor{8e6}
@subsubsection 所需資源更少 (cheaper) 且惰性的 (lazy)) Python 幀 (frame)


每當 Python 呼叫 Python 函式時，就會建立保存執行資訊的 Python 幀。以下是針對幀而做的新最佳化：


@itemize -

@item 
使幀的建立過程更有效率。

@item 
在 C 堆疊 (stack) 中盡量重複利用幀的空間來避免記憶體分配。

@item 
讓內部幀結構只包含必要資訊，使其更加精簡。在過去，幀必須帶有額外的偵錯與記憶體管理的資訊。
@end itemize

舊式@ref{8e7,,幀物件}現在僅在除錯器或 Python 自我檢查函式（例如 @ref{8e8,,sys._getframe()} 或 @ref{8e9,,inspect.currentframe()}）請求時才建立。對於大多數使用者程式碼，根本不會建立任何幀物件。結果幾乎所有 Python 函式呼叫都顯著加速。我們以 pyperformance 測得了 3-7% 的加速。

（由 Mark Shannon 於 bpo-44590@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44590} 中所貢獻。）
@anchor{whatsnew/3 11 inline-calls}@anchor{8ea}
@node 行內 Python 函式呼叫,PEP 659：特化的適應性直譯器,所需資源更少 cheaper 且惰性的 lazy Python 幀 frame,更快的運行程式
@anchor{whatsnew/3 11 inlined-python-function-calls}@anchor{8eb}@anchor{whatsnew/3 11 whatsnew311-inline-calls}@anchor{8ec}
@subsubsection 行內 Python 函式呼叫


在 Python 函式呼叫期間，Python 將呼叫一個正在求值的 C 函式來直譯該函式的程式碼，這有效地將純 Python 遞迴限制在對 C 堆疊的安全範圍內。

在 3.11 中，當 CPython 檢測到 Python 程式碼呼叫另一個 Python 函式時，它會設立一個新框架 (frame)，並「跳轉」到新框架內的新程式碼，這避免了呼叫整個 C 直譯函式。

現在大多數 Python 函式的呼叫因為不會佔用 C 堆疊空間而被加速。在斐波那契 (fibonacci) 或階乘等簡單遞迴函式中，觀察到 1.7 倍的加速。這也意味著遞迴函式可以遞迴得更深（如果使用者有增加@ref{6e3,,遞迴限制}）。我們在 pyperformance 測得 1-3% 的改進。

（由 Pablo Galindo 與 Mark Shannon 於 bpo-45256@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45256} 中所貢獻。）

@node PEP 659：特化的適應性直譯器,,行內 Python 函式呼叫,更快的運行程式
@anchor{whatsnew/3 11 pep-659-specializing-adaptive-interpreter}@anchor{8ed}@anchor{whatsnew/3 11 whatsnew311-pep659}@anchor{49a}
@subsubsection PEP 659：特化的適應性直譯器


@geindex Python Enhancement Proposals; PEP 659
PEP 659@footnote{https://peps.python.org/pep-0659/} 是加速 CPython 專案的關鍵部分之一。一般的想法是，雖然 Python 是一種動態語言，但大多數程式碼都有物件和型別很少去更改的區域。這個概念被稱為`型別穩定 (type stability)'。

在執行環境，Python 將嘗試在執行中的程式碼內尋找常用模式和型別穩定，然後 Python 將用更特化的操作替換目前操作。這種特化操作運用了僅適用於那些用例/型別的快速路徑，這通常優於它們的泛用對應 (generic counterparts)。這也引入了另一個稱為`行內快取 (inline caching)'的概念，其中 Python 將繁重操作的結果直接快取在@ref{4a5,,位元組碼}中。

特化程式 (specializer) 還將某些常用指示 (common instruction) 組合成一個超級指示 (superinstruction)，這減少了執行期間的開銷。

Python 只會在看到「熱」（被多次執行的）程式碼時特化，這可以防止 Python 將時間浪費在只運行一次的程式碼上。當程式碼過於動態或用途發生變化時，Python 也可以去特化 (de-specialize)。特化會定期被嘗試執行，而嘗試的成本也不會太高，這讓特化得以適應新的環境。

（PEP 由 Mark Shannon 撰寫、概念啟發自 Stefan Brunthaler。詳情請見 
@geindex Python Enhancement Proposals; PEP 659
PEP 659@footnote{https://peps.python.org/pep-0659/}。由 Mark Shannon 和 Brandt Bucher 實作，Irit Katriel 和 Dennis Sweeney 亦提供了額外的幫助。）

@c If I missed out anyone, please add them.


@multitable {xxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxx} 
@headitem

操作

@tab

形式

@tab

特化

@tab

操作加速程度（上限）

@tab

貢獻者

@item

二元操作

@tab

@code{x + x}

@code{x - x}

@code{x * x}

@tab

常見型別如 @ref{19b,,int}、@ref{196,,float} 與 @ref{169,,str} 的二元加法、乘法與減法，為底層型別採取了特製的快速路徑。

@tab

10%

@tab

Mark Shannon,
Donghee Na,
Brandt Bucher,
Dennis Sweeney

@item

下標

@tab

@code{a[i]}

@tab

下標容器型別如 @ref{24d,,list}、@ref{60c,,tuple} 和 @ref{183,,dict} 直接索引底層的資料結構。

下標自定義 @ref{582,,__getitem__()} 也是行內的，類似於 @ref{8ea,,行內 Python 函式呼叫}。

@tab

10-25%

@tab

Irit Katriel,
Mark Shannon

@item

儲存下標

@tab

@code{a[i] = z}

@tab

類似於上面的下標特化。

@tab

10-25%

@tab

Dennis Sweeney

@item

呼叫

@tab

@code{f(arg)}

@code{C(arg)}

@tab

常見內建 (C) 函式和型別的呼叫，例如 @ref{839,,len()} 和 @ref{169,,str}，會直接呼叫它們的 C 版本底層，這避免了通過內部呼叫的慣例。

@tab

20%

@tab

Mark Shannon,
Ken Jin

@item

載入全域變數

@tab

@code{print}

@code{len}

@tab

全域/內建之命名空間內的物件索引被快取起來。載入全域與內建變數不需要任何命名空間的查找。

@tab

@footnote{
類似的最佳化自從 Python 3.8 就存在。3.11 特別處理了更多形式並減少效能開銷 (overhead)。
}

@tab

Mark Shannon

@item

載入屬性

@tab

@code{o.attr}

@tab

和載入全域變數類似，類別/物件之命名空間內的屬性索引被快取起來。在大部分情況中，載入屬性不需要任何命名空間的查找。

@tab

@footnote{
類似的最佳化自從 Python 3.10 就存在。3.11 特別處理了更多形式。此外，所有屬性載入也被 @uref{https://bugs.python.org/issue?@@action=redirect&bpo=45947,bpo-45947} 所加速。
}

@tab

Mark Shannon

@item

載入要呼叫的方法

@tab

@code{o.meth()}

@tab

方法的真實記憶體地址被快取 (cache) 起來，方法的載入現在不需要命名空間的查找 -- 即便有很長繼承鏈結的類別也是。

@tab

10-20%

@tab

Ken Jin,
Mark Shannon

@item

儲存屬性

@tab

@code{o.attr = z}

@tab

和載入屬性的最佳化相似。

@tab

2% 於 pyperformance 中

@tab

Mark Shannon

@item

拆解 (unpack) 序列

@tab

@code{*seq}

@tab

為像是 @ref{24d,,list} 和 @ref{60c,,tuple} 的常見容器所特化，避免了內部呼叫慣例。

@tab

8%

@tab

Brandt Bucher

@end multitable


@node 雜項,FAQ,更快的運行程式,更快的 CPython
@anchor{whatsnew/3 11 misc}@anchor{8ee}@anchor{whatsnew/3 11 whatsnew311-faster-cpython-misc}@anchor{8ef}
@subsubsection 雜項



@itemize *

@item 
物件現在因為使用了惰性建立的物件命名空間所以需要更少的記憶體。它們的命名空間字典現在也更自由地共享鍵。（由 Mark Shannon 於 bpo-45340@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45340} 和 bpo-40116@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40116} 貢獻。 ）

@item 
實作了「無代價 (Zero-cost)」的例外，消除了在沒有例外被引發時的 @ref{8f0,,try} 陳述式開銷。（由 Mark Shannon 於 bpo-40222@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40222} 貢獻。）

@item 
在直譯器內使用更簡潔的例外表示法將捕獲一個例外所需的時間減少了大約 10%。 由 Irit Katriel 在 bpo-45711@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45711} 中貢獻。）

@item 
@ref{be,,re} 的正規表示式比對引擎部分被重構，且現在會有支援的平台上使用 computed gotos（或者「執行緒程式碼 (threaded code)」），因此 Python 3.11 在執行 pyperformance 正規表示式基準量測@footnote{https://pyperformance.readthedocs.io/benchmarks.html#regex-dna}的表現上比起 Python 3.10 快了 10%。（由 Brandt Bucher 於 gh-91404@footnote{https://github.com/python/cpython/issues/91404} 中貢獻。）
@end itemize

@node FAQ,關於,雜項,更快的 CPython
@anchor{whatsnew/3 11 faq}@anchor{8f1}@anchor{whatsnew/3 11 whatsnew311-faster-cpython-faq}@anchor{8f2}
@subsubsection FAQ


@menu
* 我該如何在程式碼中取得這些加速？:: 
* Python 3.11 會不會使用更多記憶體？: Python 3 11 會不會使用更多記憶體？. 
* 我在我的程式當中沒感覺到任何加速，為什麼？:: 
* 有用到 JIT 編譯器嗎？:: 

@end menu

@node 我該如何在程式碼中取得這些加速？,Python 3 11 會不會使用更多記憶體？,,FAQ
@anchor{whatsnew/3 11 faster-cpython-faq-my-code}@anchor{8f3}@anchor{whatsnew/3 11 how-should-i-write-my-code-to-utilize-these-speedups}@anchor{8f4}
@subsubsection 我該如何在程式碼中取得這些加速？


撰寫符合 Python 風格 (Pythonic) 且依循常見最佳實踐的程式碼就好，你不需要改變你的程式碼。CPython 加速計畫中，我們為所觀察到的常見程式編寫模式來做最佳化。

@node Python 3 11 會不會使用更多記憶體？,我在我的程式當中沒感覺到任何加速，為什麼？,我該如何在程式碼中取得這些加速？,FAQ
@anchor{whatsnew/3 11 faster-cpython-faq-memory}@anchor{8f5}@anchor{whatsnew/3 11 will-cpython-3-11-use-more-memory}@anchor{8f6}
@subsubsection Python 3.11 會不會使用更多記憶體？


也許不會。我們預期不會有超出 3.10 20% 的記憶體使用量。這數字會和上述禎物件與物件字典的記憶體最佳化而有所偏差。

@node 我在我的程式當中沒感覺到任何加速，為什麼？,有用到 JIT 編譯器嗎？,Python 3 11 會不會使用更多記憶體？,FAQ
@anchor{whatsnew/3 11 faster-cpython-ymmv}@anchor{8f7}@anchor{whatsnew/3 11 i-don-t-see-any-speedups-in-my-workload-why}@anchor{8f8}
@subsubsection 我在我的程式當中沒感覺到任何加速，為什麼？


某些程式中不會有顯著的好處。如果你的程式花了大部分的時間在 I/O 操作上，或已經將大部分計算用像是 numpy 的 C 擴充函式庫處理，那就不會有明顯的加速。這個計畫是對純 Python 的工作負荷最有幫助。

此外，pyperformance 數值為一個幾何平均數 (geometric mean)。即便在 pyperformance 基準量測中，某些測試稍微慢了一些，但其他加快了將近兩倍！

@node 有用到 JIT 編譯器嗎？,,我在我的程式當中沒感覺到任何加速，為什麼？,FAQ
@anchor{whatsnew/3 11 faster-cpython-jit}@anchor{8f9}@anchor{whatsnew/3 11 is-there-a-jit-compiler}@anchor{8fa}
@subsubsection 有用到 JIT 編譯器嗎？


沒有，我們還在探索其他最佳化方式。

@node 關於,,FAQ,更快的 CPython
@anchor{whatsnew/3 11 about}@anchor{8fb}@anchor{whatsnew/3 11 whatsnew311-faster-cpython-about}@anchor{8fc}
@subsubsection 關於


CPython 加速計畫探索了各種 @ref{8fd,,CPython} 最佳化的可能性。主要團隊由微軟 (microsoft) 所資助以全職發展該計畫，Pablo Galindo Salgado 亦由彭博有限合夥企業 (Bloomberg LP) 資助來兼職開發，更有許許多多來自社群的自發性貢獻者。

@node CPython 位元組碼變更<4>,已棄用<4>,更快的 CPython,Python 3 11 有什麼新功能
@anchor{whatsnew/3 11 cpython-bytecode-changes}@anchor{8fe}@anchor{whatsnew/3 11 whatsnew311-bytecode-changes}@anchor{8ff}
@subsection CPython 位元組碼變更


位元組碼現在包含行內快取條目，它們採用新添加的 @ref{900,,CACHE} 指示的形式。許多操作碼預期後面要有確切數量的快取，並指示直譯器在執行環境跳過它們。傳遞的 (populated) 快取看起來像任意指示，因此在讀取或修改包含加速資料的原始且適應 (adaptive) 位元組碼時應格外小心。

@menu
* 新增 opcode:: 
* 被取代的操作碼 (opcode): 被取代的操作碼 opcode. 
* 有更動/被移除的 opcode:: 

@end menu

@node 新增 opcode,被取代的操作碼 opcode,,CPython 位元組碼變更<4>
@anchor{whatsnew/3 11 new-opcodes}@anchor{901}@anchor{whatsnew/3 11 whatsnew311-added-opcodes}@anchor{902}
@subsubsection 新增 opcode



@itemize *

@item 
@code{ASYNC_GEN_WRAP}、@ref{903,,RETURN_GENERATOR} 和 @ref{904,,SEND} 被用於產生器與協程。

@item 
@ref{905,,COPY_FREE_VARS}，避免了為閉包 (closure) 而生的特殊呼叫方 (caller-side) 程式碼的需求。

@item 
@ref{906,,JUMP_BACKWARD_NO_INTERRUPT}，用於某些不需要處理中斷的循環。

@item 
@ref{907,,MAKE_CELL} 被用於建立 @ref{908,,Cell 物件}。

@item 
@ref{909,,CHECK_EG_MATCH} 和 @code{PREP_RERAISE_STAR}，處理 
@geindex Python Enhancement Proposals; PEP 654
PEP 654@footnote{https://peps.python.org/pep-0654/} 所加入的@ref{7b7,,新增例外群組和 except*}。

@item 
@ref{90a,,PUSH_EXC_INFO} 被用於例外處理函式。

@item 
@ref{5b3,,RESUME}，為無操作 (no-po)，用於內部追查、除錯和最佳化檢查。
@end itemize

@node 被取代的操作碼 opcode,有更動/被移除的 opcode,新增 opcode,CPython 位元組碼變更<4>
@anchor{whatsnew/3 11 replaced-opcodes}@anchor{90b}@anchor{whatsnew/3 11 whatsnew311-replaced-opcodes}@anchor{90c}
@subsubsection 被取代的操作碼 (opcode)



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

被取代的操作碼

@tab

新的操作碼

@tab

註記

@item


@display
@code{BINARY_*}@w{ }
@code{INPLACE_*}@w{ }
@end display



@tab

@ref{364,,BINARY_OP}

@tab

以單一一個操作碼來取代所有數值的、二進位/原位 (in-place) 操作碼

@item


@display
@code{CALL_FUNCTION}@w{ }
@code{CALL_FUNCTION_KW}@w{ }
@code{CALL_METHOD}@w{ }
@end display



@tab


@display
@ref{90d,,CALL}@w{ }
@code{KW_NAMES}@w{ }
@code{PRECALL}@w{ }
@ref{90e,,PUSH_NULL}@w{ }
@end display



@tab

將方法的引數搬移 (argument shifting) 與關鍵字引數的處理分離開來；允許更好的呼叫特化

@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{90f,,COPY}@w{ }
@ref{910,,SWAP}@w{ }
@end display



@tab

堆疊操作指示

@item


@display
@code{JUMP_IF_NOT_EXC_MATCH}@w{ }
@end display



@tab


@display
@ref{911,,CHECK_EXC_MATCH}@w{ }
@end display



@tab

現在執行檢查但不跳位 (jump)

@item


@display
@code{JUMP_ABSOLUTE}@w{ }
@code{POP_JUMP_IF_FALSE}@w{ }
@code{POP_JUMP_IF_TRUE}@w{ }
@end display



@tab


@display
@ref{912,,JUMP_BACKWARD}@w{ }
@code{POP_JUMP_BACKWARD_IF_*}@w{ }
@code{POP_JUMP_FORWARD_IF_*}@w{ }
@end display



@tab

參見 @footnote{
所有跳位操作碼 (jump opcode) 現在都是相對的，包括現有的 @code{JUMP_IF_TRUE_OR_POP} 和 @code{JUMP_IF_FALSE_OR_POP}。該引數現在是目前指示 (instruction) 的偏移量而不是絕對位置。
}；每個方向的 @code{TRUE}、@code{FALSE}、@code{NONE} 和 @code{NOT_NONE} 變體

@item


@display
@code{SETUP_WITH}@w{ }
@code{SETUP_ASYNC_WITH}@w{ }
@end display



@tab

@code{BEFORE_WITH}

@tab

@ref{186,,with} 區塊設置

@end multitable

@anchor{whatsnew/3 11 whatsnew311-changed-opcodes}@anchor{913}@anchor{whatsnew/3 11 whatsnew311-removed-opcodes}@anchor{914}
@node 有更動/被移除的 opcode,,被取代的操作碼 opcode,CPython 位元組碼變更<4>
@anchor{whatsnew/3 11 changed-removed-opcodes}@anchor{915}@anchor{whatsnew/3 11 whatsnew311-changed-removed-opcodes}@anchor{916}
@subsubsection 有更動/被移除的 opcode



@itemize *

@item 
更改了 @ref{917,,MATCH_CLASS} 和 @ref{918,,MATCH_KEYS} ，不再推送一個額外的布林值來表示成功/失敗。取而代之的是會在失敗時推送 @code{None}，而非一個包含提取值的元組。

@item 
更改了運作於例外的操作碼以反映它們現在在堆疊中的表示為一項而不是三項（請參閱 gh-89874@footnote{https://github.com/python/cpython/issues/89874}）。

@item 
刪除 @code{COPY_DICT_WITHOUT_KEYS}、@code{GEN_START}、@code{POP_BLOCK}、@code{SETUP_FINALLY} 和 @code{YIELD_FROM}。
@end itemize
@anchor{whatsnew/3 11 whatsnew311-deprecated}@anchor{919}
@node 已棄用<4>,Python 3 12 中待決議的移除項目,CPython 位元組碼變更<4>,Python 3 11 有什麼新功能
@anchor{whatsnew/3 11 deprecated}@anchor{91a}@anchor{whatsnew/3 11 whatsnew311-python-api-deprecated}@anchor{91b}
@subsection 已棄用


這個部分列出了在 Python 3.11 中棄用的 Python API。

被棄用的 C API 被@ref{91c,,獨立列出}。
@anchor{whatsnew/3 11 whatsnew311-deprecated-language}@anchor{91d}
@menu
* 語言/內建:: 
* 模組:: 
* 標準函式庫:: 

@end menu

@node 語言/內建,模組,,已棄用<4>
@anchor{whatsnew/3 11 language-builtins}@anchor{91e}@anchor{whatsnew/3 11 whatsnew311-deprecated-builtins}@anchor{91f}
@subsubsection 語言/內建



@itemize *

@item 
鏈接 @ref{489,,classmethod} 描述器（在 bpo-19072@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19072} 中引入）現已棄用。它不能再用於包裝其他描述器，例如 @ref{4ae,,property}。此功能的核心設計存在缺陷，並導致了許多下游問題。要「傳遞通過 (pass-through)」@ref{489,,classmethod}，請考慮使用 Python 3.10 中添加的 @code{__wrapped__} 屬性。（由 Raymond Hettinger 在 gh-89519@footnote{https://github.com/python/cpython/issues/89519} 中貢獻。）

@item 
值大於 @code{0o377}（十進位為 255）的字串和位元組文本值 (bytes literal) 中的八進位跳脫 (octal escape) 現在會產生 @ref{1a3,,DeprecationWarning}。在未來的 Python 版本中，他們將引發一個 @ref{1ae,,SyntaxWarning} 並最終引發一個 @ref{18e,,SyntaxError}。（由 Serhiy Storchaka 在 gh-81548@footnote{https://github.com/python/cpython/issues/81548} 中貢獻。）

@item 
@ref{19b,,int()} 到 @ref{19c,,__trunc__()} 的授權 (delegation) 現已棄用。當 @code{type(a)} 有實作 @code{__trunc__()} 但沒有 @ref{19d,,__int__()} 或 @ref{19e,,__index__()}，呼叫 @code{int(a)} 現在會引發一個 @ref{1a3,,DeprecationWarning}。（由 Zackery Spytz 在 bpo-44977@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44977} 中貢獻。）
@end itemize

@node 模組,標準函式庫,語言/內建,已棄用<4>
@anchor{whatsnew/3 11 modules}@anchor{920}@anchor{whatsnew/3 11 whatsnew311-deprecated-modules}@anchor{921}
@subsubsection 模組

@anchor{whatsnew/3 11 whatsnew311-pep594}@anchor{7c2}

@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/} 引領下列模組的棄用，並排訂於 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


（由 Brett Cannon 和 Victor Stinner 分別於 bpo-47061@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47061} 與 gh-68966@footnote{https://github.com/python/cpython/issues/68966} 中所貢獻。）

@item 
@code{asynchat}、@code{asyncore} 和 @code{smtpd} 至少在 Python 3.6 以前就被棄用，它們的文件與棄用警告現在已被更新為會提示它們即將於 Python 3.12 中移除。（由 Hugo van Kemenade 於 bpo-47022@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47022} 中貢獻。）

@item 
:mod:!lib2to3` 套件和 @code{2to3} 工具現已棄用，可能無法剖析 Python 3.10 或更新版本。有關詳細資訊請參閱 
@geindex Python Enhancement Proposals; PEP 617
PEP 617@footnote{https://peps.python.org/pep-0617/}，它引入了新的 PEG 剖析器。（由 Victor Stinner 在 bpo-40360@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40360} 中貢獻。）

@item 
未被記錄於文件中的 @code{sre_compile}、@code{sre_constants} 和 @code{sre_parse} 模組現在已被棄用。（由 Serhiy Storchaka 在 bpo-47152@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47152} 中貢獻。）
@end itemize

@node 標準函式庫,,模組,已棄用<4>
@anchor{whatsnew/3 11 standard-library}@anchor{922}@anchor{whatsnew/3 11 whatsnew311-deprecated-stdlib}@anchor{923}
@subsubsection 標準函式庫



@itemize *

@item 
以下 @ref{26,,configparser} 相關項目已在 Python 3.2 中棄用，它們的棄用警告現在會提示它們即將於 Python 3.12 中移除：


@itemize *

@item 
@code{configparser.SafeConfigParser} 類別

@item 
@code{configparser.ParsingError.filename} 屬性

@item 
@code{configparser.RawConfigParser.readfp()} 方法
@end itemize

（由 Hugo van Kemenade 於 bpo-45173@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45173} 中所貢獻。）

@item 
@code{configparser.LegacyInterpolation} 自 Python 3.2 起已在文件字串中棄用，並且未在 @ref{26,,configparser} 文件中列出。它現在會發出一個 @ref{1a3,,DeprecationWarning} 並將在 Python 3.13 中刪除。請改用 @ref{924,,configparser.BasicInterpolation} 或 @ref{925,,configparser.ExtendedInterpolation}。（由 Hugo van Kemenade 在 bpo-46607@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46607} 中貢獻。）

@item 
舊的 @ref{7f,,importlib.resources} 函式集因為不支援定位套件子目錄中的資源而被棄用、並將在未來的 Python 版本中刪除，取而代之的是在 Python 3.9 中添加的替代方案：


@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 
@ref{325,,locale.getdefaultlocale()} 函式已被棄用且將於 Python 3.15 中移除。請改用 @ref{327,,locale.setlocale()}、@ref{755,,locale.getpreferredencoding(False)} 和 @ref{326,,locale.getlocale()}。（Victor Stinner 於 gh-90817@footnote{https://github.com/python/cpython/issues/90817} 中所貢獻。）

@item 
@code{locale.resetlocale()} 函式已棄用並將於 Python 3.13 中移除，請改用 @code{locale.setlocale(locale.LC_ALL, "")}。（由 Victor Stinner 於 gh-90817@footnote{https://github.com/python/cpython/issues/90817} 中所貢獻。）

@item 
現在將對@ref{926,,正規表示式}中的數值群組參照 (numerical group references) 和群組名稱套用更嚴格的規則。現在只接受 ASCII 數字序列作為數值參照，並且 @ref{192,,bytes} 模式 (pattern) 的群組名稱和替換字串中只能包含 ASCII 字母、數字和底線。目前，會針對違反這些規則的語法發出棄用警告。（由 Serhiy Storchaka 在 gh-91760@footnote{https://github.com/python/cpython/issues/91760} 中貢獻。）

@item 
在 @ref{be,,re} 模組中，@code{re.template()} 函式和相應的 @code{re.TEMPLATE} 和 @code{re.T} 旗標被棄用，因為它們沒被記錄於文件中並且缺乏明顯的目的。它們將在 Python 3.13 中被刪除。（由 Serhiy Storchaka 和 Miro Hrončok 在 gh-92728@footnote{https://github.com/python/cpython/issues/92728} 中貢獻。）

@item 
@code{turtle.settiltangle()} 自 Python 3.1 以來已被棄用；它現在會發出棄用警告，並將在 Python 3.13 中刪除。請改用 @ref{927,,turtle.tiltangle()}（它之前被錯誤地標記為已棄用，其文件字串現在已更正）。（由 Hugo van Kemenade 在 bpo-45837@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45837} 中貢獻。）

@item 
僅用於支援 Python 2 和 Python 3 程式碼間相容性的 @ref{35e,,typing.Text} 現已棄用。目前未計劃刪除它，但鼓勵用戶盡可能使用 @ref{169,,str} 代替。（由 Alex Waygood 在 gh-92332@footnote{https://github.com/python/cpython/issues/92332} 中貢獻。）

@item 
用於建構 @ref{331,,typing.TypedDict} 型別的關鍵字引數語法現已棄用。將在 Python 3.13 中停止支援。（由 Jingchen Ye 在 gh-90224@footnote{https://github.com/python/cpython/issues/90224} 中貢獻。）

@item 
@code{webbrowser.MacOSX} 已被棄用且將於 Python 3.13 中移除。它並沒有被測試過、沒紀錄於文件、也沒有被 @ref{11b,,webbrowser} 本身使用。（由 Donghee Na 於 bpo-42255@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42255}。）

@item 
回傳從 @ref{2b3,,TestCase} 和 @ref{35f,,IsolatedAsyncioTestCase} 測試方法（預設的 @code{None} 值除外）給定值的行為現已棄用。

@item 
棄用以下並沒有正式紀錄於文件中的 @ref{10c,,unittest} 函式，並預計於 Python 3.13 中移除：


@itemize *

@item 
@code{unittest.findTestCases()}

@item 
@code{unittest.makeSuite()}

@item 
@code{unittest.getTestCaseNames()}
@end itemize

改用 @ref{58d,,TestLoader} 方法：


@itemize *

@item 
@ref{58e,,unittest.TestLoader.loadTestsFromModule()}

@item 
@ref{58f,,unittest.TestLoader.loadTestsFromTestCase()}

@item 
@ref{590,,unittest.TestLoader.getTestCaseNames()}
@end itemize

（由 Erlend E. Aasland 於 bpo-5846@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5846} 中所貢獻。）

@item 
@code{unittest.TestProgram.usageExit()} 被標記為已棄用，即將在 3.13 中移除（由 Carlos Damázio 在 gh-67048@footnote{https://github.com/python/cpython/issues/67048} 中貢獻。）
@end itemize
@anchor{whatsnew/3 11 whatsnew311-pending-removal}@anchor{928}
@node Python 3 12 中待決議的移除項目,已移除<4>,已棄用<4>,Python 3 11 有什麼新功能
@anchor{whatsnew/3 11 pending-removal-in-python-3-12}@anchor{929}@anchor{whatsnew/3 11 whatsnew311-python-api-pending-removal}@anchor{92a}
@subsection Python 3.12 中待決議的移除項目


下列 API 已在先前的 Python 發布版本中棄用，並將於 Python 3.12 中移除。

待定的 C API 移除項目為@ref{92b,,獨立列出的}。


@itemize *

@item 
@code{asynchat} 模組

@item 
@code{asyncore} 模組

@item 
@ref{92c,,整個 distutils 套件}

@item 
@code{imp} 模組

@item 
@ref{238,,typing.io} 命名空間

@item 
@ref{92d,,typing.re} 命名空間

@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} 環境變數

@item 
@ref{10c,,unittest} 中被棄用的別名：

@quotation


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxx} 
@headitem

已棄用的別名

@tab

方法名稱

@tab

棄用於

@item

@code{failUnless}

@tab

@ref{743,,assertTrue()}

@tab

3.1

@item

@code{failIf}

@tab

@ref{744,,assertFalse()}

@tab

3.1

@item

@code{failUnlessEqual}

@tab

@ref{745,,assertEqual()}

@tab

3.1

@item

@code{failIfEqual}

@tab

@ref{746,,assertNotEqual()}

@tab

3.1

@item

@code{failUnlessAlmostEqual}

@tab

@ref{747,,assertAlmostEqual()}

@tab

3.1

@item

@code{failIfAlmostEqual}

@tab

@ref{748,,assertNotAlmostEqual()}

@tab

3.1

@item

@code{failUnlessRaises}

@tab

@ref{749,,assertRaises()}

@tab

3.1

@item

@code{assert_}

@tab

@ref{743,,assertTrue()}

@tab

3.2

@item

@code{assertEquals}

@tab

@ref{745,,assertEqual()}

@tab

3.2

@item

@code{assertNotEquals}

@tab

@ref{746,,assertNotEqual()}

@tab

3.2

@item

@code{assertAlmostEquals}

@tab

@ref{747,,assertAlmostEqual()}

@tab

3.2

@item

@code{assertNotAlmostEquals}

@tab

@ref{748,,assertNotAlmostEqual()}

@tab

3.2

@item

@code{assertRegexpMatches}

@tab

@ref{74a,,assertRegex()}

@tab

3.2

@item

@code{assertRaisesRegexp}

@tab

@ref{74b,,assertRaisesRegex()}

@tab

3.2

@item

@code{assertNotRegexpMatches}

@tab

@ref{74c,,assertNotRegex()}

@tab

3.5

@end multitable

@end quotation
@end itemize
@anchor{whatsnew/3 11 whatsnew311-removed}@anchor{92e}
@node 已移除<4>,移植至 Python 3 11,Python 3 12 中待決議的移除項目,Python 3 11 有什麼新功能
@anchor{whatsnew/3 11 removed}@anchor{92f}@anchor{whatsnew/3 11 whatsnew311-python-api-removed}@anchor{930}
@subsection 已移除


此部分列出 Python 3.11 中移除的 Python API。

被移除的 C API 被@ref{931,,獨立列出}。


@itemize *

@item 
刪除了 @code{@@asyncio.coroutine()} @ref{932,,decorator} 使遺留的基於生成器的協程 (generator-based coroutine) 與 @ref{933,,async} / @ref{18d,,await} 程式碼相容。該函式自 Python 3.8 起已被棄用，計劃於 Python 3.10 刪除。請改用 @ref{7e6,,async def}。（由 Illia Volochii 在 bpo-43216@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43216} 中貢獻。）

@item 
移除除錯模式中用於包裝遺留基於產生器之協程物件的 @code{asyncio.coroutines.CoroWrapper}。（由 Illia Volochii 於 bpo-43216@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43216} 中貢獻。）

@item 
因為有重大的安全性考量，Python 3.9 中停用的 @ref{934,,asyncio.loop.create_datagram_endpoint()} 之 `reuse_address' 參數目前已經移除。這是因為 UDP socket 選項 @code{SO_REUSEADDR} 的行為所致。（由 Hugo van Kemenade 於 bpo-45129@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45129} 中貢獻。）

@item 
移除 Python 3.9 中棄用的 @code{binhex} 模組，與其相關且相似的 @ref{11,,binascii} 函式也一併被移除：


@itemize *

@item 
@code{binascii.a2b_hqx()}

@item 
@code{binascii.b2a_hqx()}

@item 
@code{binascii.rlecode_hqx()}

@item 
@code{binascii.rldecode_hqx()}
@end itemize

@ref{935,,binascii.crc_hqx()} 維持可用。

（由 Victor Stinner 於 bpo-45085@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45085} 中所貢獻。）

@item 
移除 Python 3.9 中棄用的 @code{distutils} @code{bdist_msi} 命令。請改用 @code{bdist_wheel}（wheel 套件）。（由 Hugo van Kemenade 於 bpo-45124@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45124} 中貢獻。）

@item 
將 @ref{936,,xml.dom.pulldom.DOMEventStream}、@ref{937,,wsgiref.util.FileWrapper} 和 @ref{938,,fileinput.FileInput} 自 Python 3.9 中棄用的 @ref{582,,__getitem__()} 方法移除。(由 Hugo van Kemenade 在 bpo-45132@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45132} 中貢獻。)

@item 
刪除了已棄用的 @ref{67,,gettext} 函式 @code{lgettext()}、@code{ldgettext()}、@code{lngettext()} 和 @code{ldngettext()}，也刪除了 @code{bind_textdomain_codeset()} 函式、@code{NullTranslations.output_charset()} 和 @code{NullTranslations.set_output_charset()} 方法，以及 @code{translation()} 和 @code{install()} 的 `codeset' 參數，因為它們僅被用於 @code{l*gettext()} 函式。（由 Donghee Na 和 Serhiy Storchaka 在 bpo-44235@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44235} 中貢獻。）

@item 
於 @ref{82,,inspect} 模組中移除：


@itemize *

@item 
Python 3.0 中棄用的 @code{getargspec()}；改用 @ref{22f,,inspect.signature()} 或 @ref{939,,inspect.getfullargspec()}。

@item 
Python 3.5 中棄用的 @code{formatargspec()} 函式；請直接用 @ref{22f,,inspect.signature()} 函式或 @ref{4de,,inspect.Signature} 物件。

@item 
Python 3.5 中停用且沒有被紀錄於文件上的 @code{Signature.from_builtin()} 和 @code{Signature.from_function()} 方法；改用 @ref{93a,,Signature.from_callable()} 方法。
@end itemize

（由 Hugo van Kemenade 於 bpo-45320@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45320} 中所貢獻。）

@item 
自 @ref{6c6,,pathlib.PurePath} 中移除 @ref{93b,,__class_getitem__()} 方法，因為它是前一版本中誤加且沒被使用。（由 Nikita Sobolev 於 bpo-46483@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46483} 中所貢獻。）

@item 
移除 @code{smtpd} 模組中的 @code{MailmanProxy} 類別，因為它無法獨立於外部套件 @code{mailman} 使用。（由 Donghee Na 於 bpo-35800@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35800} 貢獻。）

@item 
移除 @code{_tkinter.TkappType} 已被棄用的 @code{split()} 方法。（由 Erlend E. Aasland 於 bpo-38371@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38371} 貢獻。）

@item 
從 @ref{10c,,unittest} 中刪除了命名空間套件支援。它在 Python 3.4 中引入，但自 Python 3.7 以來已無法運作。（由 Inada Naoki 在 bpo-23882@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23882} 中貢獻。）

@item 
將未被記錄於文件中的私有方法 @code{float.__set_format__()} 移除，它過去是 Python 3.7 中的 @code{float.__setformat__()}。它的文件字串 (docstring) 說到：「你大概不會想要使用這個函式，它只為了讓 Python 測試系列套件 (suite) 使用而存在。」（由 Victor Stinner 於 bpo-46852@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46852} 中貢獻。）

@item 
移除 @code{--experimental-isolated-subinterpreters} 配置旗標（與對應的 @code{EXPERIMENTAL_ISOLATED_SUBINTERPRETERS} 巨集）。

@item 
Pynche@footnote{https://pypi.org/project/Pynche/} --- Python 風格的自然色彩與色調編輯器 --- 已被移出 @code{Tools/scripts}，獨立開發@footnote{https://gitlab.com/warsaw/pynche/-/tree/main}於 Python 原始碼之外。
@end itemize
@anchor{whatsnew/3 11 whatsnew311-porting}@anchor{93c}
@node 移植至 Python 3 11,建置變更<4>,已移除<4>,Python 3 11 有什麼新功能
@anchor{whatsnew/3 11 porting-to-python-3-11}@anchor{93d}@anchor{whatsnew/3 11 whatsnew311-python-api-porting}@anchor{93e}
@subsection 移植至 Python 3.11


本部分列出了之前描述的 Python API 中可能需要你去更改 Python 程式碼的變更和其他錯誤修復。

C API 的移植被@ref{93f,,獨立列出}。


@itemize *

@item 
@ref{315,,open()}、@ref{739,,io.open()}、@ref{314,,codecs.open()} 和 @ref{938,,fileinput.FileInput} 不再接受 @code{'U'}（"universal newline"，通用換行符）文件模式。在 Python 3 中，每當以文本模式 (text mode) 打開檔案時，預設情況下會使用「通用換行符」模式，並且自 Python 3.3 以來就不推薦使用 @code{'U'} 旗標。這些函式的 @ref{940,,newline 參數}控制了通用換行符的作用方式。（由 Victor Stinner 在 bpo-37330@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37330} 中貢獻。）

@item 
@ref{4be,,ast.AST} 節點位置現在會在提供給 @ref{4ac,,compile()} 和其他相關函式時被驗證。如果檢測到無效位置，則會引發 @ref{2eb,,ValueError}。（由 Pablo Galindo 在 gh-93351@footnote{https://github.com/python/cpython/issues/93351} 中貢獻）

@item 
在 Python 3.8 中棄用後，禁止將非 @ref{941,,concurrent.futures.ThreadPoolExecutor} 執行器傳遞給 @ref{942,,asyncio.loop.set_default_executor()}。（由 Illia Volochii 在 bpo-43234@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43234} 中貢獻。）

@item 
@ref{15,,calendar}：@ref{943,,calendar.LocaleTextCalendar} 和 @ref{944,,calendar.LocaleHTMLCalendar} 類別如果沒有指定語言環境，現在會使用 @ref{326,,locale.getlocale()} 而非 @ref{325,,locale.getdefaultlocale()}。（由 Victor Stinner 在 bpo-46659@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46659} 中貢獻。）

@item 
@ref{aa,,pdb} 模組現在會讀取 @code{'UTF-8'} 編碼的 @code{.pdbrc} 配置檔案。（Srinivas Reddy Thatiparthy (శ్రీనివాస్  రెడ్డి తాటిపర్తి) 於 bpo-41137@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41137} 貢獻。）

@item 
@ref{945,,random.sample()} 的 `population' 參數必須是一個序列，不再支援 @ref{184,,set} 到 @ref{24d,,list} 的自動轉換。此外，如果抽樣大小大於總體大小，則會引發 @ref{2eb,,ValueError}。（由 Raymond Hettinger 在 bpo-40465@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40465} 中貢獻。）

@item 
刪除了 @ref{946,,random.shuffle()} 的 `random' 可選參數。它以前是用於隨機排列 (shuffle) 的任意隨機函式；現在都會使用 @ref{947,,random.random()}（這是它以前的預設值）。

@item 
在 @ref{be,,re} @ref{926,,正規表示式語法} 中，全域行內旗標（例如 @code{(?i)}）現在只能在正規表示式的開頭使用。自 Python 3.6 以來，在其他地方使用它們已被棄用。（由 Serhiy Storchaka 在 bpo-47066@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47066} 中貢獻。）

@item 
在 @ref{be,,re} 模組中修復了幾個長期存在的錯誤，在極少數情況下，這些錯誤可能會導致捕獲群組 (capture group) 得到錯誤的結果。因此，這可能會在這些情況下更改捕獲的輸出。（Ma Lin 在 bpo-35859@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35859} 中貢獻。）
@end itemize

@node 建置變更<4>,C API 變更<4>,移植至 Python 3 11,Python 3 11 有什麼新功能
@anchor{whatsnew/3 11 build-changes}@anchor{948}@anchor{whatsnew/3 11 whatsnew311-build-changes}@anchor{949}
@subsection 建置變更



@itemize *

@item 
CPython 現在有 
@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 支援@footnote{https://peps.python.org/pep-0011/#tier-3} 以用於交叉編譯至 WebAssembly@footnote{https://webassembly.org/} 平台 Emscripten@footnote{https://emscripten.org/}（@code{wasm32-unknown-emscripten}，即瀏覽器中的 Python）和 WebAssembly 系統介面 (WASI)@footnote{https://wasi.dev/} (@code{wasm32-unknown-wasi})。這個靈感來自過往的貢獻，例如 Pyodide@footnote{https://pyodide.org/}。這些平台提供了有限的 POSIX API 子集；Python 標準函式庫功能和與網路、行程、執行緒、訊號、mmap、用戶/群組相關的模組不開放使用或無法正常使用。（Emscripten 由 Christian Heimes 和 Ethan Smith 在 gh-84461@footnote{https://github.com/python/cpython/issues/84461} 貢獻，WASI 由 Christian Heimes 在 gh-90473@footnote{https://github.com/python/cpython/issues/90473} 貢獻；平台在 gh-95085@footnote{https://github.com/python/cpython/issues/95085} 中推廣）

@item 
建置 CPython 現在必須要有：


@itemize *

@item 
C11@footnote{https://en.cppreference.com/w/c/11} 編譯器與標準函式庫。可選的 C11 特性@footnote{https://en.wikipedia.org/wiki/C11_(C_standard_revision)#Optional_features} 並非必要。（由 Victor Stinner 於 bpo-46656@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46656}、bpo-45440@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45440} 和 bpo-46640@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46640} 中貢獻。）

@item 
對 IEEE 754@footnote{https://en.wikipedia.org/wiki/IEEE_754} 浮點數的支援（由 Victor Stinner 於 bpo-46917@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46917} 中所貢獻。）
@end itemize

@item 
@code{Py_NO_NAN} 巨集已被移除。因為 CPython 現在需要 IEEE 754 浮點數，NaN 數值皆為可得的。（由 Victor Stinner 在 bpo-46656@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46656} 中貢獻。）

@item 
@ref{f6,,tkinter} 套件現在必須要有 Tcl/Tk@footnote{https://www.tcl.tk} 8.5.12 或更新的版本。（由 Serhiy Storchaka 於 bpo-46996@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46996} 中所貢獻。）

@item 
大多數 stdlib 擴充模組的依賴套件、編譯器旗標 (compiler flag) 和鏈接器旗標 (linker flags) 現在可以透過 @code{configure} 檢測出來。（當可用時）pkg-config@footnote{https://www.freedesktop.org/wiki/Software/pkg-config/} 會檢測出 libffi、libnsl、libsqlite3、zlib、bzip2、liblzma、libcrypt、Tcl/Tk 和 uuid 旗標。@ref{f6,,tkinter} 現在需要一個 pkg-config 命令來檢測 Tcl/Tk@footnote{https://www.tcl.tk} 標頭檔和函式庫的開發設定。（由 Christian Heimes 和 Erlend Egeberg Aasland 在 bpo-45847@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45847}、bpo-45747@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45747} 和 bpo-45763@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45763} 中貢獻。）

@item 
libpython 不再鏈接到 libcrypt。（由 Mike Gilbert 在 bpo-45433@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45433} 中貢獻。）

@item 
CPython 現在可以透過將 @code{thin} 傳遞給 @ref{94a,,--with-lto}（也就是 @code{--with-lto=thin}）來以 ThinLTO@footnote{https://clang.llvm.org/docs/ThinLTO.html} 選項建置。（由 Donghee Na 與 Brett Holman 於 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} 和 @code{Modules/makesetup} 已得到改進和綁定。現在可以通過 @code{makesetup} 建置擴充模組。除了一些測試模組外，所有模組都可以靜態鏈接到主要的二進制文件或函式庫中。（由 Brett Cannon 和 Christian Heimes 在 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} 和 bpo-43974@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43974} 中貢獻。）

@cartouche
@quotation 備註 
使用環境變數 @code{TCLTK_CFLAGS} 和 @code{TCLTK_LIBS} 以手動指定 Tcl/Tk 標頭檔和函式庫的位置。@code{configure} 選項 @code{—with-tcltk-includes} 和 @code{—with-tcltk-libs} 已被刪除。

RHEL 7 和 CentOS 7 上的開發套件並無提供 @code{tcl.pc} 和 @code{tk.pc}；要使用 @code{TCLTK_LIBS="-ltk8.5 -ltkstub8.5 -ltcl8.5"}。目錄 @code{Misc/rhel7} 包含 @code{.pc} 檔案與如何使用 RHEL 7 和 CentOS 7 的 Tcl/Tk 與 OpenSSL 建置 Python 的指示。
@end quotation
@end cartouche

@item 
CPython 現在預設使用 30-bit 數字來實作 Python @ref{19b,,int}。以前，在 @code{SIZEOF_VOID_P >= 8} 的平台上預設使用 30-bit 數字，否則使用 15-bit 數字，但仍能通過配置腳本的 @ref{94b,,--enable-big-digits} 選項或（於 Windows）@code{PC/pyconfig.h} 中的 @code{PYLONG_BITS_IN_DIGIT} 變數來明確請求使用 15-bit 數字，但此選項可能會在將來的某個時候被刪除。（由 Mark Dickinson 在 bpo-45569@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45569} 中貢獻。）
@end itemize

@node C API 變更<4>,Python 3 11 4 中顯著的變更,建置變更<4>,Python 3 11 有什麼新功能
@anchor{whatsnew/3 11 c-api-changes}@anchor{94c}@anchor{whatsnew/3 11 whatsnew311-c-api}@anchor{94d}
@subsection C API 變更


@menu
* 新增功能: 新增功能<6>. 
* 移植至 Python 3.11: 移植至 Python 3 11<2>. 
* 已棄用: 已棄用<5>. 
* Python 3.12 中待決議的移除項目: Python 3 12 中待決議的移除項目<2>. 
* 已移除: 已移除<5>. 

@end menu

@node 新增功能<6>,移植至 Python 3 11<2>,,C API 變更<4>
@anchor{whatsnew/3 11 id5}@anchor{94e}@anchor{whatsnew/3 11 whatsnew311-c-api-new-features}@anchor{94f}
@subsubsection 新增功能



@itemize *

@item 
新增 @ref{950,,PyType_GetName()} 函式來取得型別的短名。（由 Hai Shi 於 bpo-42035@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42035} 中所貢獻。）

@item 
新增 @ref{951,,PyType_GetQualName()} 函式來取得型別的合格名稱 (qualified name)。（由 Hai Shi 於 bpo-42035@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42035} 中所貢獻。）

@item 
在受限 C API (limited C API) 中新增 @ref{952,,PyThreadState_EnterTracing()} 和 @ref{953,,PyThreadState_LeaveTracing()} 函式來中止和繼續追蹤 (tracing) 和性能分析 (profiling)。（由 Victor Stinner 於 bpo-43760@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43760} 中貢獻。）

@item 
添加了 @ref{37f,,Py_Version} 常數，其值與 @ref{380,,PY_VERSION_HEX} 相同。（由 Gabriele N. Tornetta 在 bpo-43931@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43931} 中貢獻。）

@item 
@ref{954,,Py_buffer} 與 API 目前是受限 API 與穩定 ABI 中的一部分：


@itemize *

@item 
@ref{631,,PyObject_CheckBuffer()}

@item 
@ref{632,,PyObject_GetBuffer()}

@item 
@ref{955,,PyBuffer_GetPointer()}

@item 
@ref{956,,PyBuffer_SizeFromFormat()}

@item 
@ref{957,,PyBuffer_ToContiguous()}

@item 
@ref{958,,PyBuffer_FromContiguous()}

@item 
@ref{959,,PyObject_CopyData()}

@item 
@ref{95a,,PyBuffer_IsContiguous()}

@item 
@ref{95b,,PyBuffer_FillContiguousStrides()}

@item 
@ref{95c,,PyBuffer_FillInfo()}

@item 
@ref{633,,PyBuffer_Release()}

@item 
@ref{95d,,PyMemoryView_FromBuffer()}

@item 
@ref{95e,,bf_getbuffer} 與 @ref{95f,,bf_releasebuffer} 型別插槽 (type slot)
@end itemize

（由 Christian Heimes 於 bpo-45459@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45459} 中所貢獻。）

@item 
新增 @ref{62d,,PyType_GetModuleByDef()} 函式，它將被用於取得定義一個方法的模組，以免這項資訊無法直接被取得（透過 @ref{960,,PyCMethod}）。（由 Petr Viktorin 於 bpo-46613@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46613} 中所貢獻。）

@item 
新增函式以打包 (pack) 和取出 (unpack) C double（序列化和反序列化）：@ref{961,,PyFloat_Pack2()}、@ref{962,,PyFloat_Pack4()}、@ref{963,,PyFloat_Pack8()}、@ref{964,,PyFloat_Unpack2()} , @ref{965,,PyFloat_Unpack4()} 和 @ref{966,,PyFloat_Unpack8()}。（由 Victor Stinner 在 bpo-46906@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46906} 中貢獻。）

@item 
新增取得幀物件屬性的函式：@ref{967,,PyFrame_GetBuiltins()}、@ref{968,,PyFrame_GetGenerator()}、@ref{969,,PyFrame_GetGlobals()}、@ref{96a,,PyFrame_GetLasti()}。

@item 
添加了兩個新函式來獲得和設置仍在作用的例外實例：@ref{96b,,PyErr_GetHandledException()} 和 @ref{96c,,PyErr_SetHandledException()}。這些是 @ref{96d,,PyErr_SetExcInfo()} 和 @ref{96e,,PyErr_GetExcInfo()} 的替代品，它們與例外的遺留三元組表示法一起作用。（由 Irit Katriel 在 bpo-46343@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46343} 中貢獻。）

@item 
新增 @ref{96f,,PyConfig.safe_path} 成員。（由 Victor Stinner 於 gh-57684@footnote{https://github.com/python/cpython/issues/57684} 中所貢獻。）
@end itemize

@node 移植至 Python 3 11<2>,已棄用<5>,新增功能<6>,C API 變更<4>
@anchor{whatsnew/3 11 id6}@anchor{970}@anchor{whatsnew/3 11 whatsnew311-c-api-porting}@anchor{93f}
@subsubsection 移植至 Python 3.11

@anchor{whatsnew/3 11 whatsnew311-pep670}@anchor{7c4}

@itemize *

@item 
一些巨集已轉換為行內靜態函式以避免巨集陷阱 (macro pitfalls)@footnote{https://gcc.gnu.org/onlinedocs/cpp/Macro-Pitfalls.html}。這種變化對用戶來說應該是透明的，因為替換函式會將它們的引數轉換為預期的型別，以避免由於靜態型別檢查而產生的編譯器警告。但是，當受限 C API 設置為 >=3.11 時，這些轉換不會完成，使用者需要將引數轉換為他們期望的型別。有關更多詳細資訊，請參閱 
@geindex Python Enhancement Proposals; PEP 670
PEP 670@footnote{https://peps.python.org/pep-0670/}。（由 Victor Stinner 和 Erlend E. Aasland 在 gh-89653@footnote{https://github.com/python/cpython/issues/89653} 中貢獻。）

@item 
@ref{96d,,PyErr_SetExcInfo()} 不再使用 @code{type} 和 @code{traceback} 引數，直譯器現在從例外實例（@code{value} 引數）中獲得這些值。該函式仍會偷用這三個引數的參照。（由 Irit Katriel 在 bpo-45711@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45711} 中貢獻。）

@item 
@ref{96e,,PyErr_GetExcInfo()} 現在從例外實例的結果（@code{value} 欄位）中導出 @code{type} 和 @code{traceback} 欄位。（由 Irit Katriel 在 bpo-45711@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45711} 中貢獻。）

@item 
@ref{971,,_frozen} 有一個新的 @code{is_package} 欄位來表示凍結模組是否為一個套件。以前 @code{size} 欄位中的負值是指標，現在只有非負值可用於 @code{size}。（由 Kumar Aditya 在 bpo-46608@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46608} 中貢獻。）

@item 
@ref{972,,_PyFrameEvalFunction()} 現在將 @code{_PyInterpreterFrame*} 作為其第二個參數，而不是 @code{PyFrameObject*}。有關如何使用此函式指標型別的更多詳細資訊，請參閱 
@geindex Python Enhancement Proposals; PEP 523
PEP 523@footnote{https://peps.python.org/pep-0523/}。

@item 
@code{PyCode_New()} 和 @code{PyCode_NewWithPosOnlyArgs()} 現在採用額外的 @code{exception_table} 引數。如果可能的話應該避免使用這些函式。要取得自定義程式碼物件，使用編譯器建立一個程式碼物件，然後使用 @code{replace} 方法來得到修改後的版本。

@item 
@ref{973,,PyCodeObject} 不再會有 @code{co_code}、@code{co_varnames}、@code{co_cellvars} 和 @code{co_freevars} 欄位。分別被改為透過 C API 的 @ref{974,,PyCode_GetCode()}、@ref{975,,PyCode_GetVarnames()}、@ref{976,,PyCode_GetCellvars()} 和 @ref{977,,PyCode_GetFreevars()} 來存取。（由 Brandt Bucher 在 bpo-46841@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46841}、Ken Jin 在 gh-92154@footnote{https://github.com/python/cpython/issues/92154} 與 gh-94936@footnote{https://github.com/python/cpython/issues/94936} 中貢獻。）

@item 
舊的回收筒巨集 (trashcan macro) (@code{Py_TRASHCAN_SAFE_BEGIN}/@code{Py_TRASHCAN_SAFE_END}) 現在已經被棄用，它們應被新的巨集 @code{Py_TRASHCAN_BEGIN} 和 @code{Py_TRASHCAN_END} 所取代。

一個用到老舊巨集的 tp_dealloc 函式，像是：

@example
static void
mytype_dealloc(mytype *p)
@{
    PyObject_GC_UnTrack(p);
    Py_TRASHCAN_SAFE_BEGIN(p);
    ...
    Py_TRASHCAN_SAFE_END
@}
@end example

應該要搬遷到新的巨集，如下所示：

@example
static void
mytype_dealloc(mytype *p)
@{
    PyObject_GC_UnTrack(p);
    Py_TRASHCAN_BEGIN(p, mytype_dealloc)
    ...
    Py_TRASHCAN_END
@}
@end example

請注意 @code{Py_TRASHCAN_BEGIN} 有第二個引數，它應該是它所在的釋放函式 (deallocation function)。

為支援舊版 Python 在同一份程式碼中，你可以定義以下巨集並在程式碼中使用它們（要歸功於 @code{mypy} 程式碼，這些是從那邊複製過來的）：

@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 
如果一個型別是以 @ref{978,,Py_TPFLAGS_HAVE_GC} 旗標來定義，但卻沒有遍歷函式 (traverse function) (@ref{979,,PyTypeObject.tp_traverse})，那 @ref{97a,,PyType_Ready()} 函式現在會引發一個錯誤。（由 Victor Stinner 於 bpo-44263@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44263} 中貢獻。）

@item 
帶有 @ref{3cd,,Py_TPFLAGS_IMMUTABLETYPE} 旗標的堆積型別現在可以繼承 
@geindex Python Enhancement Proposals; PEP 590
PEP 590@footnote{https://peps.python.org/pep-0590/} 向量呼叫協定 (vectorcall protocol)。以前這僅適用於 @ref{97b,,static types}。（由 Erlend E. Aasland 在 bpo-43908@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43908} 中貢獻）。

@item 
由於 @ref{3c7,,Py_TYPE()} 更改為行內靜態函式 (inline static function)，因此 @code{Py_TYPE(obj) = new_type} 必須替換為 @code{Py_SET_TYPE(obj, new_type)}：參見 @ref{97c,,Py_SET_TYPE()} 函式（自 Python 3.9 起可用）。為了向後相容，可以使用這個巨集：

@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

（由 Victor Stinner 於 bpo-39573@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39573} 中所貢獻。）

@item 
由於 @ref{97d,,Py_SIZE()} 更改為行內靜態函式，因此 @code{Py_SIZE(obj) = new_size} 必須替換為 @code{Py_SET_SIZE(obj, new_size)}：參見 @ref{97e,,Py_SET_SIZE()} 函式（自 Python 3.9 起可用）。為了向後相容，可以使用這個巨集：

@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

（由 Victor Stinner 於 bpo-39573@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39573} 中所貢獻。）

@item 
當 @code{Py_LIMITED_API} 巨集被設定為 @code{0x030b0000}（Python 3.11）或以上，@code{<Python.h>} 不再會包含標頭檔 @code{<stdlib.h>}、@code{<stdio.h>}、@code{<errno.h>} 和 @code{<string.h>}。C 擴充程式應該要清楚的在 @code{#include <Python.h>} 之後引入標頭檔案。（由 Victor Stinner 於 bpo-45434@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45434} 中貢獻。）

@item 
非受限 API (non-limited API) 檔案 @code{cellobject.h}、@code{classobject.h}、@code{code.h}、@code{context.h}、@code{funcobject.h}、@code{genobject. h} 和 @code{longintrepr.h} 已移至 @code{Include/cpython} 目錄。此外，@code{eval.h} 標頭檔已被刪除。不能直接引入這些文件，因為它們已被包含在 @code{Python.h} 中：@ref{97f,,引入檔案}。如果它們已被直接引入，請考慮改為引入 @code{Python.h}。 （由 Victor Stinner 在 bpo-35134@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35134} 中貢獻。）

@item 
@code{PyUnicode_CHECK_INTERNED()} 巨集已從受限 C API 中移出，它從來沒辦法被使用，因為它使用了受限 C API 不提供的內部結構。（由 Victor Stinner 於 bpo-46007@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46007} 中所貢獻。）

@item 
以下用於幀 (frame) 的函式與型別現在可直接透過 @code{#include <Python.h>} 來使用，不必再加上 @code{#include <frameobject.h>}：


@itemize *

@item 
@ref{980,,PyFrame_Check()}

@item 
@ref{981,,PyFrame_GetBack()}

@item 
@ref{967,,PyFrame_GetBuiltins()}

@item 
@ref{968,,PyFrame_GetGenerator()}

@item 
@ref{969,,PyFrame_GetGlobals()}

@item 
@ref{96a,,PyFrame_GetLasti()}

@item 
@ref{659,,PyFrame_GetLocals()}

@item 
@ref{982,,PyFrame_Type}
@end itemize

（由 Victor Stinner 於 gh-93937@footnote{https://github.com/python/cpython/issues/93937} 中所貢獻。）
@end itemize
@anchor{whatsnew/3 11 pyframeobject-3-11-hiding}@anchor{983}

@itemize *

@item 
@ref{984,,PyFrameObject} 結構成員已經從公開的 C API 中移除。

雖然文件指出 @ref{984,,PyFrameObject} 欄位隨時可能發生變化，但它們已經穩定了很長時間，並被用於幾個流行的擴充套件中。

Python 3.11 中，幀的結構被重新編制來為性能做最佳化，有些作為舊版實作細節的欄位被整個移除。

@ref{984,,PyFrameObject} 欄位：


@itemize *

@item 
@code{f_back}：使用 @ref{981,,PyFrame_GetBack()}。

@item 
@code{f_blockstack}：已移除。

@item 
@code{f_builtins}：使用 @ref{967,,PyFrame_GetBuiltins()}。

@item 
@code{f_code}：使用 @ref{985,,PyFrame_GetCode()}。

@item 
@code{f_gen}：使用 @ref{968,,PyFrame_GetGenerator()}。

@item 
@code{f_globals}：使用 @ref{969,,PyFrame_GetGlobals()}。

@item 
@code{f_iblock}：已移除。

@item 
@code{f_lasti}：使用 @ref{96a,,PyFrame_GetLasti()}。程式碼中 @code{f_lasti} 有與 @code{PyCode_Addr2Line()} 同時使用的部分應該改用 @ref{986,,PyFrame_GetLineNumber()}；它可能會更快。

@item 
@code{f_lineno}：使用 @ref{986,,PyFrame_GetLineNumber()}

@item 
@code{f_locals}：使用 @ref{659,,PyFrame_GetLocals()}。

@item 
@code{f_stackdepth}：已移除。

@item 
@code{f_state}：無公開 API（重新命名為 @code{f_frame.f_state}）。

@item 
@code{f_trace}：無公開 API。

@item 
@code{f_trace_lines}：使用 @code{PyObject_GetAttrString((PyObject*)frame, "f_trace_lines")}。

@item 
@code{f_trace_opcodes}：使用 @code{PyObject_GetAttrString((PyObject*)frame, "f_trace_opcodes")}。

@item 
@code{f_localsplus}：無公開 API（重新命名為 @code{f_frame.localsplus}）。

@item 
@code{f_valuestack}：已移除。
@end itemize

Python 幀物件的建立現為惰性的 (lazily)，一個副作用是 @ref{987,,f_back} 成員不能被直接存取，因為其職的計算也是惰性的，要改呼叫 @ref{981,,PyFrame_GetBack()}。

直接存取 @ref{4a0,,f_locals} 的除錯器`必須'改為呼叫 @ref{659,,PyFrame_GetLocals()}。他們不再需要呼叫 @code{PyFrame_FastToLocalsWithError()} 或 @code{PyFrame_LocalsToFast()}，事實上他們不應該呼叫這些函式。框架的必要更新現在由虛擬機管理。

@code{PyFrame_GetCode()} 在 Python 3.8 以前的程式定義：

@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{PyFrame_GetBack()} 在 Python 3.8 以前的程式定義：

@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

或是使用 pythoncap_compat 計畫@footnote{https://github.com/python/pythoncapi-compat}來在舊版 Python 函式中取得這兩個函式。

@item 
@ref{988,,PyThreadState} 結構成員的改動：


@itemize *

@item 
@code{frame}：已移除，改用 @ref{989,,PyThreadState_GetFrame()}（bpo-40429@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40429} 於 Python 3.9 新增的函式）。警告：會回傳 @ref{5da,,strong reference} 的函式必須呼叫 @ref{98a,,Py_XDECREF()}。

@item 
@code{tracing}：已變更，改用 @ref{952,,PyThreadState_EnterTracing()} 和 @ref{953,,PyThreadState_LeaveTracing()}（bpo-43760@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43760} 於 Python 3.11 中新增的函式）。

@item 
@code{recursion_depth}：已移除，請改用 @code{(tstate->recursion_limit - tstate->recursion_remaining)}。

@item 
@code{stackcheck_counter}：已移除。
@end itemize

@code{PyThreadState_GetFrame()} 在 Python 3.8 以前的程式定義：

@example
#if PY_VERSION_HEX < 0x030900B1
static inline PyFrameObject* PyThreadState_GetFrame(PyThreadState *tstate)
@{
    Py_XINCREF(tstate->frame);
    return tstate->frame;
@}
#endif
@end example

@code{PyThreadState_EnterTracing()} 與 @code{PyThreadState_LeaveTracing()} 在 Python 3.10 以前的程式定義：

@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

或是使用 pythoncap-compat 專案@footnote{https://github.com/python/pythoncapi-compat}來在舊版 Python 函式中取得它們。

@item 
鼓勵發布者們使用最佳化過的 Blake2 函式庫 libb2@footnote{https://www.blake2.net/} 來建置 Python。

@item 
初始化中若是要用 @ref{63b,,PyConfig.module_search_paths} 來初始化 @ref{3e2,,sys.path}，則現在 @ref{7fe,,PyConfig.module_search_paths_set} 必須被設為 1。否則，初始化會重新計算路徑並取代所有被加到 @code{module_search_paths} 的值。

@item 
@ref{98b,,PyConfig_Read()} 不再計算初始搜尋路徑，並且不會將任何值填充到 @ref{63b,,PyConfig.module_search_paths} 中。若要計算預設路徑然後修改它們，完成初始化並使用 @ref{622,,PySys_GetObject()} 以取得 @ref{3e2,,sys.path} 作為 Python 列表物件並直接修改它。
@end itemize

@node 已棄用<5>,Python 3 12 中待決議的移除項目<2>,移植至 Python 3 11<2>,C API 變更<4>
@anchor{whatsnew/3 11 id7}@anchor{98c}@anchor{whatsnew/3 11 whatsnew311-c-api-deprecated}@anchor{91c}
@subsubsection 已棄用



@itemize *

@item 
棄用以下用來配置 Python 初始化的函式：


@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

請改用 @ref{63e,,Python 初始化配置}中新的 @ref{3f4,,PyConfig} API。（由 Victor Stinner 於 gh-88279@footnote{https://github.com/python/cpython/issues/88279} 中所貢獻。）

@item 
棄用 @ref{98d,,PyBytesObject} 中的 @code{ob_shash} 成員。請改用 @ref{434,,PyObject_Hash()}。（由 Inada Naoki 於 bpo-46864@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46864} 中所貢獻。）
@end itemize

@node Python 3 12 中待決議的移除項目<2>,已移除<5>,已棄用<5>,C API 變更<4>
@anchor{whatsnew/3 11 id8}@anchor{98e}@anchor{whatsnew/3 11 whatsnew311-c-api-pending-removal}@anchor{92b}
@subsubsection Python 3.12 中待決議的移除項目


以下 C API 已於先前 Python 發布版本中棄用，並將於 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{432,,PyUnicode_READY()}

@item 
@code{PyUnicode_WSTR_LENGTH()}

@item 
@code{_PyUnicode_AsUnicode()}

@item 
@code{PyUnicode_WCHAR_KIND}

@item 
@ref{98f,,PyUnicodeObject}

@item 
@code{PyUnicode_InternImmortal()}
@end itemize

@node 已移除<5>,,Python 3 12 中待決議的移除項目<2>,C API 變更<4>
@anchor{whatsnew/3 11 id9}@anchor{990}@anchor{whatsnew/3 11 whatsnew311-c-api-removed}@anchor{931}
@subsubsection 已移除



@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 
移除以下使用到 @code{errno} 變數的數學巨集：


@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

（由 Victor Stinner 於 bpo-45412@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45412} 中所貢獻。）

@item 
移除在 Python 3.3 中棄用的 @code{Py_UNICODE_COPY()} 和 @code{Py_UNICODE_FILL()}。請改用 @code{PyUnicode_CopyCharacters()} 或 @code{memcpy()}（@code{wchar_t*} 字串）和 @code{PyUnicode_Fill()} 函式。（由 Victor Stinner 於 bpo-41123@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41123} 中所貢獻。）

@item 
移除 @code{pystrhex.h} 標頭檔案。它只有包含私有函式。C 的擴充應該只要引入主要的 @code{<Python.h>} 標頭檔案。（由 Victor Stinner 於 bpo-45434@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45434} 中所貢獻。）

@item 
移除 @code{Py_FORCE_DOUBLE()} 巨集。它先前被用於 @code{Py_IS_INFINITY()} 巨集。（由 Victor Stinner 於 bpo-45440@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45440} 中所貢獻。）

@item 
當 @ref{658,,Py_LIMITED_API} 有被定義時，以下項目將無法被取得：


@itemize *

@item 
@ref{991,,PyMarshal_WriteLongToFile()}

@item 
@ref{992,,PyMarshal_WriteObjectToFile()}

@item 
@ref{993,,PyMarshal_ReadObjectFromString()}

@item 
@ref{994,,PyMarshal_WriteObjectToString()}

@item 
@code{Py_MARSHAL_VERSION} 巨集
@end itemize

These are not part of the @ref{995,,limited API}.

（由 Victor Stinner 於 bpo-45474@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45474} 中所貢獻。）

@item 
將 @ref{3dc,,PyWeakref_GET_OBJECT()} 排除於受限 C API 之外，它因為 @code{PyWeakReference} 結構在受限 C API 中過於晦澀而從未運作。（由 Victor Stinner 於 bpo-35134@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35134} 中所貢獻。）

@item 
移除 @code{PyHeapType_GET_MEMBERS()} 巨集，它是不小心才被放到公開的 C API 中，應該只能被 Python 內部所使用。請改用 @code{PyTypeObject.tp_members}。（由 Victor Stinner 於 bpo-40170@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40170} 中所貢獻。）

@item 
移除 @code{HAVE_PY_SET_53BIT_PRECISION} 巨集（移動至內部 C API）。（由 Victor Stinner 於 bpo-45412@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45412} 中所貢獻。）
@end itemize
@anchor{whatsnew/3 11 whatsnew311-pep624}@anchor{7c3}

@itemize *

@item 
移除 @ref{3de,,Py_UNICODE} 編碼器 API，它們自從 Python 3.3 就被棄用，非常少用且和推薦的替代方案已無太大關聯。

被移除的函式為：


@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

詳情請見 
@geindex Python Enhancement Proposals; PEP 624
PEP 624@footnote{https://peps.python.org/pep-0624/} 與
@geindex Python Enhancement Proposals; PEP 624#alternative-apis
搬遷指南@footnote{https://peps.python.org/pep-0624/#alternative-apis}。（由 Inada Naoki 於 bpo-44029@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44029} 中所貢獻。）
@end itemize

@node Python 3 11 4 中顯著的變更,Python 3 11 5 中顯著的變更,C API 變更<4>,Python 3 11 有什麼新功能
@anchor{whatsnew/3 11 notable-changes-in-3-11-4}@anchor{996}
@subsection Python 3.11.4 中顯著的變更


@menu
* tarfile: tarfile<2>. 

@end menu

@node tarfile<2>,,,Python 3 11 4 中顯著的變更
@anchor{whatsnew/3 11 tarfile}@anchor{997}
@subsubsection tarfile



@itemize *

@item 
The extraction methods in @ref{e4,,tarfile}, and @ref{68f,,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{690,,Extraction filters} for details.
In Python 3.12, use without the `filter' argument will show a
@ref{1a3,,DeprecationWarning}.
In Python 3.14, the default will switch to @code{'data'}.
(Contributed by Petr Viktorin in 
@geindex Python Enhancement Proposals; PEP 706
PEP 706@footnote{https://peps.python.org/pep-0706/}.)
@end itemize

@node Python 3 11 5 中顯著的變更,,Python 3 11 4 中顯著的變更,Python 3 11 有什麼新功能
@anchor{whatsnew/3 11 notable-changes-in-3-11-5}@anchor{998}
@subsection Python 3.11.5 中顯著的變更


@menu
* OpenSSL:: 

@end menu

@node OpenSSL,,,Python 3 11 5 中顯著的變更
@anchor{whatsnew/3 11 openssl}@anchor{999}
@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 Python 3 10 有什麼新功能,Python 3 9 有什麼新功能,Python 3 11 有什麼新功能,Python 有什麼新功能？
@anchor{whatsnew/3 10 doc}@anchor{99a}@anchor{whatsnew/3 10 translation-repo}@anchor{99b}@anchor{whatsnew/3 10 what-s-new-in-python-3-10}@anchor{99c}
@section Python 3.10 有什麼新功能


@*編輯者: 
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.

本文介紹了 Python 3.10 與 3.9 相比多了哪些新功能。Python 3.10 已於 2021 年 10 月 4 日發布。有關完整詳細資訊，請參閱 @ref{142,,changelog}。

@menu
* 發布重點摘要: 發布重點摘要<4>. 
* 新增功能: 新增功能<7>. 
* 與型別提示相關的新功能:: 
* 其他語言更動: 其他語言更動<4>. 
* 新模組:: 
* 改進的模組: 改進的模組<4>. 
* 最佳化: 最佳化<5>. 
* 已棄用: 已棄用<6>. 
* 已刪除:: 
* 移植到 Python 3.10: 移植到 Python 3 10. 
* CPython 位元組碼變更: CPython 位元組碼變更<5>. 
* 建置變更: 建置變更<5>. 
* C API 變更: C API 變更<5>. 
* Python 3.10.7 中顯著的安全性功能: Python 3 10 7 中顯著的安全性功能. 
* Python 3.10.8 中顯著的安全性功能: Python 3 10 8 中顯著的安全性功能. 
* Python 3.10.12 中顯著的變更: Python 3 10 12 中顯著的變更. 

@end menu

@node 發布重點摘要<4>,新增功能<7>,,Python 3 10 有什麼新功能
@anchor{whatsnew/3 10 summary-release-highlights}@anchor{99d}
@subsection 發布重點摘要


@c This section singles out the most important changes in Python 3.10.
@c Brevity is key.

@c PEP-sized items next.

新增語法特性：


@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 634
PEP 634@footnote{https://peps.python.org/pep-0634/}，結構模式匹配 (Structural Pattern Matching)：規範

@item 
@geindex Python Enhancement Proposals; PEP 635
PEP 635@footnote{https://peps.python.org/pep-0635/}，結構模式匹配：動機和基本原理

@item 
@geindex Python Enhancement Proposals; PEP 636
PEP 636@footnote{https://peps.python.org/pep-0636/}，結構模式匹配：教學

@item 
bpo-12782@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12782}，現在正式允許帶括號的情境管理器 (context manager)。
@end itemize

標準函式庫中的新功能：


@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 618
PEP 618@footnote{https://peps.python.org/pep-0618/}，新增可選的長度檢查到 zip。
@end itemize

直譯器改進：


@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 626
PEP 626@footnote{https://peps.python.org/pep-0626/}，用於除錯和其他工具的精確列號。
@end itemize

新的 typing 功能：


@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 604
PEP 604@footnote{https://peps.python.org/pep-0604/}，允許將聯集型別 (union types) 寫為 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

重要的棄用、刪除或限制：


@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 644
PEP 644@footnote{https://peps.python.org/pep-0644/}，需要 OpenSSL 1.1.1 或更高版本

@item 
@geindex Python Enhancement Proposals; PEP 632
PEP 632@footnote{https://peps.python.org/pep-0632/}，棄用 distutils 模組。

@item 
@geindex Python Enhancement Proposals; PEP 623
PEP 623@footnote{https://peps.python.org/pep-0623/}，棄用並準備刪除 PyUnicodeObject 中的 wstr 成員。

@item 
@geindex Python Enhancement Proposals; PEP 624
PEP 624@footnote{https://peps.python.org/pep-0624/}，刪除 Py_UNICODE 編碼器 API

@item 
@geindex Python Enhancement Proposals; PEP 597
PEP 597@footnote{https://peps.python.org/pep-0597/}，新增可選的 EncodingWarning
@end itemize

@node 新增功能<7>,與型別提示相關的新功能,發布重點摘要<4>,Python 3 10 有什麼新功能
@anchor{whatsnew/3 10 new-features}@anchor{99e}
@subsection 新增功能


@menu
* 帶括號的情境管理器:: 
* 更好的錯誤訊息:: 
* PEP 626：用於除錯和其他工具的精確列號:: 
* PEP 634：結構模式匹配:: 
* 可選的 EncodingWarning 和 encoding="locale" 選項:: 

@end menu

@node 帶括號的情境管理器,更好的錯誤訊息,,新增功能<7>
@anchor{whatsnew/3 10 parenthesized-context-managers}@anchor{99f}@anchor{whatsnew/3 10 whatsnew310-pep563}@anchor{9a0}
@subsubsection 帶括號的情境管理器


現在支援使用成對的括號來將多個情境管理器以數行表示。這允許了與過去的引入陳述式 (import statement) 類似的方法來格式化一組多行的情境管理器集合。例如，以下範例現在都是有效的：

@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

也可以在封閉群組的末尾使用逗號：

@example
with (
    CtxManager1() as example1,
    CtxManager2() as example2,
    CtxManager3() as example3,
):
    ...
@end example

此新語法使用新剖析器的非 LL(1) 功能。檢查 
@geindex Python Enhancement Proposals; PEP 617
PEP 617@footnote{https://peps.python.org/pep-0617/} 了解更多詳細資訊。

（由 Guido van Rossum、Pablo Galindo 和 Lysandros Nikolaou 在 bpo-12782@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12782} 和 bpo-40334@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40334} 中貢獻。）

@node 更好的錯誤訊息,PEP 626：用於除錯和其他工具的精確列號,帶括號的情境管理器,新增功能<7>
@anchor{whatsnew/3 10 better-error-messages}@anchor{9a1}
@subsubsection 更好的錯誤訊息


@menu
* SyntaxErrors:: 
* IndentationErrors:: 
* AttributeErrors:: 
* NameErrors:: 

@end menu

@node SyntaxErrors,IndentationErrors,,更好的錯誤訊息
@anchor{whatsnew/3 10 syntaxerrors}@anchor{9a2}
@subsubsection SyntaxErrors


當剖析包含未成對括號或方括號的程式碼時，直譯器現在會包含未成對括號的位置，而不是顯示 `SyntaxError: unexpected EOF while parsing' 或指向某些不正確的位置。例如，以下程式碼（注意未閉合的 @code{@{} ）：

@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

以前版本的直譯器會在奇怪的地方顯示有語法錯誤：

@example
File "example.py", line 3
    some_other_code = foo()
                    ^
SyntaxError: invalid syntax
@end example

但在 Python 3.10 中，會發出一個資訊更豐富的錯誤：

@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

同樣地，涉及未成對字串字面值（單引號和三引號）的錯誤現在會指向字串的開頭，而不是報告 EOF/EOL。

這些改進是受到 PyPy 直譯器的啟發。

（由 Pablo Galindo 在 bpo-42864@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42864} 和 Batuhan Taskaya 在 bpo-40176@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40176} 中貢獻。）

直譯器引發的 @ref{18e,,SyntaxError} 例外現在會突顯 (highlight) 構成語法錯誤之運算式的完整錯誤範圍，而不僅是檢測到問題的位置。如此一來，過去（像 Python 3.10 之前）的：

@example
>>> foo(x, z for z in range(10), t, w)
  File "<stdin>", line 1
    foo(x, z for z in range(10), t, w)
           ^
SyntaxError: Generator expression must be parenthesized
@end example

現在 Python 3.10 則會將例外顯示為：

@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

此改進由 Pablo Galindo 在 bpo-43914@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43914} 中貢獻。

已合併了大量針對 @ref{18e,,SyntaxError} 例外的新專用訊息。一些最值得注意的如下：


@itemize *

@item 
在區塊之前缺少 @code{:}:

@example
>>> if rocket.position > event_horizon
  File "<stdin>", line 1
    if rocket.position > event_horizon
                                      ^
SyntaxError: expected ':'
@end example

（由 Pablo Galindo 在 bpo-42997@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42997} 中貢獻。）

@item 
綜合運算目標中未加括號的元組：

@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

（由 Pablo Galindo 在 bpo-43017@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43017} 中貢獻。）

@item 
容器字面值 (collection literals) 中和運算式之間缺少逗號：

@example
>>> items = @{
... x: 1,
... y: 2
... z: 3,
  File "<stdin>", line 3
    y: 2
       ^
SyntaxError: invalid syntax. Perhaps you forgot a comma?
@end example

（由 Pablo Galindo 在 bpo-43822@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43822} 中貢獻。）

@item 
不帶括號的多個例外型別：

@example
>>> try:
...     build_dyson_sphere()
... except NotEnoughScienceError, NotEnoughResourcesError:
  File "<stdin>", line 3
    except NotEnoughScienceError, NotEnoughResourcesError:
           ^
SyntaxError: multiple exception types must be parenthesized
@end example

（由 Pablo Galindo 在 bpo-43149@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43149} 中貢獻。）

@item 
字典字面值中缺少 @code{:} 和值：

@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

（由 Pablo Galindo 在 bpo-43823@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43823} 中貢獻。）

@item 
沒有 @code{except} 或 @code{finally} 區塊的 @code{try} 區塊：

@example
>>> try:
...     x = 2
... something = 3
  File "<stdin>", line 3
    something  = 3
    ^^^^^^^^^
SyntaxError: expected 'except' or 'finally' block
@end example

（由 Pablo Galindo 在 bpo-44305@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44305} 中貢獻。）

@item 
於比較中使用 @code{=} 而非 @code{==}：

@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

（由 Pablo Galindo 在 bpo-43797@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43797} 中貢獻。）

@item 
f 字串中使用 @code{*}：

@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

（由 Pablo Galindo 在 bpo-41064@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41064} 中貢獻。）
@end itemize

@node IndentationErrors,AttributeErrors,SyntaxErrors,更好的錯誤訊息
@anchor{whatsnew/3 10 indentationerrors}@anchor{9a3}
@subsubsection IndentationErrors


許多 @ref{9a4,,IndentationError} 例外現在支援更多關於哪種區塊需要縮進的情境，包括陳述式的位置：

@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,更好的錯誤訊息
@anchor{whatsnew/3 10 attributeerrors}@anchor{9a5}
@subsubsection AttributeErrors


當印出 @ref{5e8,,AttributeError} 時，@code{PyErr_Display()} 將提供引發例外的物件中類似屬性名稱的建議：

@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

（由 Pablo Galindo 在 bpo-38530@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38530} 中貢獻。）

@cartouche
@quotation 警告 
請注意，如果未呼叫 @code{PyErr_Display()} 來顯示錯誤（可能為了要使用其他自定義錯誤顯示函式），則此操作將不起作用。這是 IPython 等某些 REPL 中的常見狀況。
@end quotation
@end cartouche

@node NameErrors,,AttributeErrors,更好的錯誤訊息
@anchor{whatsnew/3 10 nameerrors}@anchor{9a6}
@subsubsection NameErrors


當印出直譯器引發的 @ref{450,,NameError} 時，@code{PyErr_Display()} 將在引發例外的函式中提供類似變數名稱的建議：

@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

（由 Pablo Galindo 在 bpo-38530@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38530} 中貢獻。）

@cartouche
@quotation 警告 
請注意，如果未呼叫 @code{PyErr_Display()} 來顯示錯誤，則此操作將不起作用，如果使用其他自定義錯誤顯示函式，則可能會發生這種情況。這是 IPython 等某些 REPL 中的常見場景。
@end quotation
@end cartouche

@node PEP 626：用於除錯和其他工具的精確列號,PEP 634：結構模式匹配,更好的錯誤訊息,新增功能<7>
@anchor{whatsnew/3 10 pep-626-precise-line-numbers-for-debugging-and-other-tools}@anchor{9a7}
@subsubsection PEP 626：用於除錯和其他工具的精確列號


PEP 626 為除錯、分析 (profiling) 和覆蓋 (coverage) 工具帶來了更精確、更可靠的列號 (line numbers)。為所有已執行的程式碼列且僅針對已執行的程式碼行產生具有正確列號的追蹤事件。

影格 (frame) 物件的 @ref{9a8,,f_lineno} 屬性總會包含預期的列號。

@ref{4e1,,程式碼物件}的 @ref{32f,,co_lnotab} 屬性已棄用，並將在 3.12 中刪除。需要從偏移量轉換為列號的程式碼應使用新的 @ref{34e,,co_lines()} 方法。

@node PEP 634：結構模式匹配,可選的 EncodingWarning 和 encoding="locale" 選項,PEP 626：用於除錯和其他工具的精確列號,新增功能<7>
@anchor{whatsnew/3 10 pep-634-structural-pattern-matching}@anchor{9a9}
@subsubsection PEP 634：結構模式匹配


已新增結構模式匹配 (structural pattern matching)，其形式為具有關聯操作之模式的 `match 陳述式' 和 `case 陳述式'。模式由序列、對映、原始資料型別 (primitive data types) 以及類別實例組成。模式匹配使程式能夠從複雜的資料型別中提取資訊，在資料結構上進行分支，並根據不同形式的資料應用特定的操作。

@menu
* 語法和操作:: 
* 宣告式方法 (Declarative approach): 宣告式方法 Declarative approach. 
* 簡單模式：與字面值匹配:: 
* 具有字面值和變數的模式:: 
* 模式和類別:: 
* 巢狀模式:: 
* 複雜模式和萬用字元:: 
* Guard:: 
* 其他主要功能:: 

@end menu

@node 語法和操作,宣告式方法 Declarative approach,,PEP 634：結構模式匹配
@anchor{whatsnew/3 10 syntax-and-operations}@anchor{9aa}
@subsubsection 語法和操作


模式匹配的通用語法是：

@example
match subject:
    case <pattern_1>:
        <action_1>
    case <pattern_2>:
        <action_2>
    case <pattern_3>:
        <action_3>
    case _:
        <action_wildcard>
@end example

match 陳述式採用一個運算式，並將其值與作為一個或多個 case 區塊給出的連續模式進行比較。具體來說，模式匹配是透過以下方式進行操作：


@enumerate 

@item 
使用具有型態 (type) 和特徵 (shape) 的資料 (主語 @code{subject})

@item 
@code{match} 陳述式中 @code{subject} 的求值 (evaluating)

@item 
從上到下將主語與 @code{case} 陳述式中的每個模式進行比較，直到確認匹配。

@item 
執行與已確認匹配模式對應的操作

@item 
如果未確認完全匹配，則最後一種情況，即萬用字元 @code{_} （如果有提供）將作為匹配到的情況。如未有任何匹配且不存在萬用字元的 case，則整個 match 區塊會是個無操作 (no-op)。
@end enumerate

@node 宣告式方法 Declarative approach,簡單模式：與字面值匹配,語法和操作,PEP 634：結構模式匹配
@anchor{whatsnew/3 10 declarative-approach}@anchor{9ab}
@subsubsection 宣告式方法 (Declarative approach)


讀者可能會透過使用 C、Java 或 JavaScript（以及許多其他語言）中的 switch 陳述式將主語（資料物件）與字面值 (literal)（模式）進行匹配的簡單範例來了解模式匹配。 switch 語句通常用於將物件/運算式與包含字面值的 case 陳述式進行比較。

更強大的模式匹配範例可以在 Scala 和 Elixir 等語言中找到。對於結構模式匹配，該方法是「宣告式的 (declarative)」，並且明確地說明了資料匹配的條件（模式）。

雖然使用巢狀 "if" 陳述式的「命令式 (imperative)」指令系列可用於完成類似於結構模式匹配的操作，但它不如「宣告式 (declarative)」方法清晰。相反地，「聲明式」方法規定了匹配所需滿足的條件，並且因其明確表達模式而更具可讀性。雖然結構模式匹配可以用其最簡單的形式達成，將變數與 case 陳述式中的字面值進行比較，但它對 Python 的真正價值在於它對主語的型態和特徵的處理。

@node 簡單模式：與字面值匹配,具有字面值和變數的模式,宣告式方法 Declarative approach,PEP 634：結構模式匹配
@anchor{whatsnew/3 10 simple-pattern-match-to-a-literal}@anchor{9ac}
@subsubsection 簡單模式：與字面值匹配


讓我們將此範例視為最簡單形式的模式匹配：一個值（主語）與多個文字（模式）匹配。在下面的範例中，@code{status} 是匹配陳述式的主語。這些模式是每個 case 陳述式，其中文字表示請求狀態程式碼。與案例相關的操作在匹配後執行：

@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

如果上面的函式傳遞了 418 @code{status}，則回傳 "I'm a teapot"。如果上面的函式傳遞了 500 @code{status}，則帶有 @code{_} 的 case 語句將作為萬用字元進行匹配，並回傳 "Something's wrong with the internet"。請注意最後一個區塊：變數名稱 @code{_} 充當 `萬用字元' 並確保主語始終匹配。@code{_} 的使用是可選的。

你可以使用 @code{|} ("or") 將多個字面值組合在一個模式中：

@example
case 401 | 403 | 404:
    return "Not allowed"
@end example

@menu
* 沒有萬用字元 (wildcard) 的行為: 沒有萬用字元 wildcard 的行為. 

@end menu

@node 沒有萬用字元 wildcard 的行為,,,簡單模式：與字面值匹配
@anchor{whatsnew/3 10 behavior-without-the-wildcard}@anchor{9ad}
@subsubsection 沒有萬用字元 (wildcard) 的行為


如果我們透過刪除最後一個 case 區塊來修改上面的範例，則範例將變為：

@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

如果在 case 陳述式中不使用 @code{_}，則可能不存在匹配項目。如果不存在匹配項目，則該行為是無操作 (no-op)。例如，如果 @code{status} 為 500，則不會有任何操作。

@node 具有字面值和變數的模式,模式和類別,簡單模式：與字面值匹配,PEP 634：結構模式匹配
@anchor{whatsnew/3 10 patterns-with-a-literal-and-variable}@anchor{9ae}
@subsubsection 具有字面值和變數的模式


模式看起來就像解包賦值 (unpacking assignment)，並且模式可用於繫結 (bind) 變數。在此範例中，可以將資料點解包為其 x 坐標和 y 坐標：

@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

第一個模式有兩個字面值 @code{(0, 0)}，並且可以被認為是上面顯示的字面值模式的擴充。接下來的兩個模式組合了一個字面值和一個變數，並且變數`繫結'來自主語（@code{point}）的值。第四個模式捕獲兩個值，這使得它在概念上類似於解包賦值 @code{(x, y) = point}。

@node 模式和類別,巢狀模式,具有字面值和變數的模式,PEP 634：結構模式匹配
@anchor{whatsnew/3 10 patterns-and-classes}@anchor{9af}
@subsubsection 模式和類別


如果你使用類別來建構資料，則可以用類別名稱與後面的引數列表組合成的建構函式作為模式。該模式能夠將實例屬性捕獲到變數中：

@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
* 具有位置參數的模式:: 

@end menu

@node 具有位置參數的模式,,,模式和類別
@anchor{whatsnew/3 10 patterns-with-positional-parameters}@anchor{9b0}
@subsubsection 具有位置參數的模式


你可以將位置參數與一些會為其屬性排序的內建類別（例如 dataclasses）一起使用。你還可以通過在類別中設定 @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

@node 巢狀模式,複雜模式和萬用字元,模式和類別,PEP 634：結構模式匹配
@anchor{whatsnew/3 10 nested-patterns}@anchor{9b1}
@subsubsection 巢狀模式


模式可以任意巢套。例如，如果我們的資料是一個簡短的座標點列表，則可以這樣匹配：

@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 複雜模式和萬用字元,Guard,巢狀模式,PEP 634：結構模式匹配
@anchor{whatsnew/3 10 complex-patterns-and-the-wildcard}@anchor{9b2}
@subsubsection 複雜模式和萬用字元


到目前為止，範例在最後一個 case 陳述式中單獨使用了 @code{_}。萬用字元可以用在更複雜的模式中，像是 @code{('error', code, _)}。例如：

@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

在上述情況下，值像是 ('error', code, 100) 和 ('error', code, 800) 的 @code{test_variable} 將會成功匹配。

@node Guard,其他主要功能,複雜模式和萬用字元,PEP 634：結構模式匹配
@anchor{whatsnew/3 10 guard}@anchor{9b3}
@subsubsection Guard


我們可以在模式中新增一個 @code{if} 子句，稱為 "guard"。如果 guard 為 false，則 @code{match} 會繼續嘗試下一個 case 區塊。請注意，值的捕獲發生在 guard 的求值 (evaluate) 之前：

@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 其他主要功能,,Guard,PEP 634：結構模式匹配
@anchor{whatsnew/3 10 other-key-features}@anchor{9b4}
@subsubsection 其他主要功能


其他幾個主要功能：


@itemize -

@item 
與賦值的解包一樣，tuple 和 list 模式具有完全相同的含義，並且實際上匹配任意序列。從技術上來說，主語必須是一個序列。因此，一個重要的例外是模式不會去匹配疊代器。另外，為了防止常常出錯，序列模式也不會去匹配字串。

@item 
序列模式支援萬用字元：@code{[x, y, *rest]} 和 @code{(x, y, *rest)} 與解包賦值中的萬用字元類似。 @code{*} 後面的名稱也可能是 @code{_}，因此 @code{(x, y, *_)} 會匹配至少兩個項目的序列，且不繫結其餘項目。

@item 
對映模式： @code{@{"bandwidth": b, "latency": l@}} 從字典中捕獲 @code{"bandwidth"} 和 @code{"latency"} 值。與序列模式不同，額外的鍵將被忽略。也支援萬用字元 @code{**rest}。（但是 @code{**_} 是多餘的，所以是不允許的。）

@item 
可以使用 @code{as} 關鍵字捕獲子模式：

@example
case (Point(x1, y1), Point(x2, y2) as p2): ...
@end example

這將繫結 x1、y1、x2、y2，如同沒有 @code{as} 子句的情況下所預期的，並將 p2 繫結到主語的整個第二項目。

@item 
大多數字面值都是通過相等進行比較的。然而，單例 @code{True}、@code{False} 和 @code{None} 是按標識值 (identity) 來進行比較的。

@item 
附名常數 (named constant) 可以在模式中使用。這些附名常數必須有帶有點的名稱 (dotted name)，以防止常數被直譯為捕獲的變數：

@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

有關完整規範，請參閱 
@geindex Python Enhancement Proposals; PEP 634
PEP 634@footnote{https://peps.python.org/pep-0634/}。動機和基本原理位於 
@geindex Python Enhancement Proposals; PEP 635
PEP 635@footnote{https://peps.python.org/pep-0635/} 中，較完整的教學位於 
@geindex Python Enhancement Proposals; PEP 636
PEP 636@footnote{https://peps.python.org/pep-0636/} 中。

@node 可選的 EncodingWarning 和 encoding="locale" 選項,,PEP 634：結構模式匹配,新增功能<7>
@anchor{whatsnew/3 10 optional-encodingwarning-and-encoding-locale-option}@anchor{9b5}@anchor{whatsnew/3 10 whatsnew310-pep597}@anchor{9b6}
@subsubsection 可選的 @code{EncodingWarning} 和 @code{encoding="locale"} 選項


@ref{9b7,,TextIOWrapper} 和 @ref{315,,open()} 的預設編碼取決於平台和區域設定。由於大多數 Unix 平台都使用 UTF-8，因此在打開 UTF-8 檔案（例如 JSON、YAML、TOML、Markdown）時省略 @code{encoding} 選項是個常見的 bug，例如：

@example
# BUG: "rb" mode or encoding="utf-8" should be used.
with open("data.json") as f:
    data = json.load(f)
@end example

為了發現這種錯誤，新增了一個可選的 @code{EncodingWarning}。當 @ref{895,,sys.flags.warn_default_encoding} 為 true 且使用特定於語言環境的預設編碼時，會發出該信號。

新增 @code{-X warn_default_encoding} 選項和 
@geindex PYTHONWARNDEFAULTENCODING
@geindex 環境變數; PYTHONWARNDEFAULTENCODING
@ref{9b8,,PYTHONWARNDEFAULTENCODING} 來啟用警告。

更多資訊請見 @ref{9b9,,文字編碼}。

@node 與型別提示相關的新功能,其他語言更動<4>,新增功能<7>,Python 3 10 有什麼新功能
@anchor{whatsnew/3 10 new-feat-related-type-hints}@anchor{9ba}@anchor{whatsnew/3 10 new-features-related-to-type-hints}@anchor{9bb}
@subsection 與型別提示相關的新功能


本節介紹影響 
@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/} 型別提示和 @ref{10a,,typing} 模組的主要更改。

@menu
* PEP 604：新型聯集運算子:: 
* PEP 612：參數規範變數:: 
* PEP 613：型別別名 (TypeAlias): PEP 613：型別別名 TypeAlias. 
* PEP 647：使用者定義的型別防護:: 

@end menu

@node PEP 604：新型聯集運算子,PEP 612：參數規範變數,,與型別提示相關的新功能
@anchor{whatsnew/3 10 pep-604-new-type-union-operator}@anchor{9bc}
@subsubsection PEP 604：新型聯集運算子


引入了一種新的聯集運算子，該運算子啟用像是 @code{X | Y} 的語法。這提供了一種在型別提示中更清晰的方式來表達「型別 X 或型別 Y」，來取代使用 @ref{2a8,,typing.Union}。

在以前版本的 Python 中，要使用接受多種型別之引數的型別提示的函式，要使用 @ref{2a8,,typing.Union}：

@example
def square(number: Union[int, float]) -> Union[int, float]:
    return number ** 2
@end example

現在可以用更簡潔的方式編寫型別提示：

@example
def square(number: int | float) -> int | float:
    return number ** 2
@end example

這種新語法也接受作為 @ref{2ad,,isinstance()} 和 @ref{9bd,,issubclass()} 的第二個引數：

@example
>>> isinstance(1, int | str)
True
@end example

更多資訊請見 @ref{9be,,聯合型別 (Union Type)} 與 
@geindex Python Enhancement Proposals; PEP 604
PEP 604@footnote{https://peps.python.org/pep-0604/}。

（由 Maggie Moss 和 Philippe Prados 在 bpo-41428@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41428} 中貢獻，由 Yurii Karabas 和 Serhiy Storchaka 在 bpo-44490@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44490} 中補充。）

@node PEP 612：參數規範變數,PEP 613：型別別名 TypeAlias,PEP 604：新型聯集運算子,與型別提示相關的新功能
@anchor{whatsnew/3 10 pep-612-parameter-specification-variables}@anchor{9bf}
@subsubsection PEP 612：參數規範變數


@ref{10a,,typing} 模組中新增了兩個新選項，用於改進為 
@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/} @code{Callable} 的靜態型別檢查器 (static type checker) 所提供的資訊。

第一個是參數規範變數 (parameter specification variable)。它們用於將一個可呼叫物件的參數型別轉發到另一個可呼叫物件 -- 這是高階函式和裝飾器中常見的模式。使用範例可以在 @ref{482,,typing.ParamSpec} 中找到。在過去是沒有簡單的方法可以如此精確地來為參數型別的依賴關係做型別註釋。

第二個選項是新的 @code{Concatenate} 運算子。它與參數規範變數結合使用，來對一個高階、會新增或刪除另一個可呼叫物件參數的可呼叫物件進行型別註釋。使用範例可以在 @ref{9c0,,typing.Concatenate} 中找到。

請參閱 @ref{9c1,,typing.Callable}、@ref{482,,typing.ParamSpec}、@ref{9c0,,typing.Concatenate}、@ref{9c2,,typing.ParamSpecArgs}、@ref{9c3,,typing.ParamSpecKwargs} 和 
@geindex Python Enhancement Proposals; PEP 612
PEP 612@footnote{https://peps.python.org/pep-0612/} 以了解更多詳情。

（由 Ken Jin 在 bpo-41559@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41559} 中貢獻、Jelle Zijlstra 在 bpo-43783@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43783} 中進行了小幅改進。PEP 由 Mark Mendoza 編寫。）

@node PEP 613：型別別名 TypeAlias,PEP 647：使用者定義的型別防護,PEP 612：參數規範變數,與型別提示相關的新功能
@anchor{whatsnew/3 10 pep-613-typealias}@anchor{9c4}
@subsubsection PEP 613：型別別名 (TypeAlias)


@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/} 引入了型別別名 (type aliases) 的概念，只要求它們是最高階、未註釋的賦值 (top-level unannotated assignments)。這種簡單性有時使型別檢查器難以區分型別別名和普通賦值，尤其是在涉及傳遞參照 (reference) 或無效型別時。比較如下：

@example
StrCache = 'Cache[str]'  # a type alias
LOG_PREFIX = 'LOG[DEBUG]'  # a module constant
@end example

現在 @ref{10a,,typing} 模組有一個特殊值 @ref{9c5,,TypeAlias}，它可以讓你更明確地宣告型別別名：

@example
StrCache: TypeAlias = 'Cache[str]'  # a type alias
LOG_PREFIX = 'LOG[DEBUG]'  # a module constant
@end example

更多資訊請見 
@geindex Python Enhancement Proposals; PEP 613
PEP 613@footnote{https://peps.python.org/pep-0613/}。

（由 Mikhail Golubev 在 bpo-41923@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41923} 中貢獻。）

@node PEP 647：使用者定義的型別防護,,PEP 613：型別別名 TypeAlias,與型別提示相關的新功能
@anchor{whatsnew/3 10 pep-647-user-defined-type-guards}@anchor{9c6}
@subsubsection PEP 647：使用者定義的型別防護


@ref{487,,TypeGuard}（型別防護）已新增到 @ref{10a,,typing} 模組中，用以註釋型別防護函式並改進在型別窄縮 (type narrowing) 期間提供給靜態型別檢查器的資訊。有關更多資訊，請參閱 @ref{487,,TypeGuard} 的文件和 
@geindex Python Enhancement Proposals; PEP 647
PEP 647@footnote{https://peps.python.org/pep-0647/}。

（由 Ken Jin 和 Guido van Rossum 在 bpo-43766@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43766} 中貢獻。PEP 由 Eric Traut 編寫。）

@node 其他語言更動<4>,新模組,與型別提示相關的新功能,Python 3 10 有什麼新功能
@anchor{whatsnew/3 10 other-language-changes}@anchor{9c7}
@subsection 其他語言更動



@itemize *

@item 
@ref{19b,,int} 型別有一個新方法 @ref{9c8,,int.bit_count()}，回傳給定整數的二進位展開式中 1 的數量，也稱為總體計數 (population count)。（由 Niklas Fiekas 在 bpo-29882@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29882} 中貢獻。）

@item 
@ref{9c9,,dict.keys()}、@ref{9ca,,dict.values()} 和 @ref{9cb,,dict.items()} 回傳的視圖 (view) 現在都有一個 @code{mapping} 屬性，該屬性提供 @ref{691,,types.MappingProxyType} 包裝原始的字典物件。（由 Dennis Sweeney 在 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/}：@ref{1a0,,zip()} 函式現在有一個可選的 @code{strict} 旗標，用於要求所有可疊代物件具有相同的長度。

@item 
採用整數引數的內建函式和擴充函式不再接受 @ref{1fe,,Decimal}、@ref{213,,Fraction} 以及其他只能在有損失的情況下轉換為整數的物件（例如有 @ref{19d,,__int__()} 方法，但沒有 @ref{19e,,__index__()} 方法）。（由 Serhiy Storchaka 在 bpo-37999@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37999} 中貢獻。）

@item 
如果 @ref{9cc,,object.__ipow__()} 回傳 @ref{1a2,,NotImplemented}，則該運算子將按預期正確回退到 @ref{9cd,,object.__pow__()} 和 @ref{1a5,,object.__rpow__()} 。（由 Alex Shkop 在 bpo-38302@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38302} 中貢獻。）

@item 
現在可以在集合字面值 (set literals) 和集合綜合運算 (set comprehensions) 以及序列索引（但不能是切片）中使用不帶括號的賦值運算式 (assignment expressions)。

@item 
函式有一個新的 @code{__builtins__} 屬性，用於在執行函式時查找內建符號，而不是查找 @code{__globals__['__builtins__']} 。如果 @code{__globals__["__builtins__"]} 存在，則屬性會以此做初始化，否則從目前內建物件 (builtins) 初始化。（由 Mark Shannon 在 bpo-42990@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42990} 中貢獻。）

@item 
新增兩個內建函式 -- @ref{9ce,,aiter()} 和 @ref{9cf,,anext()}，分別為 @ref{9d0,,iter()} 和 @ref{9d1,,next()} 提供非同步的對應函式。（由 Joshua Bronson、Daniel Pope 和 Justin Wang 在 bpo-31861@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31861} 中貢獻。）

@item 
靜態方法 (@ref{451,,@@staticmethod}) 和類別方法 (@ref{489,,@@classmethod}) 現在繼承方法屬性 (@code{__module__}, @code{__name__}, @code{__qualname__}, @code{__doc__}, @code{__annotations__}) 並有一個新的 @code{__wrapped__} 屬性。此外，靜態方法現在可以像是常規函式般呼叫。（由 Victor Stinner 在 bpo-43682@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43682} 中貢獻。）

@item 
複雜目標（除 
@geindex Python Enhancement Proposals; PEP 526
PEP 526@footnote{https://peps.python.org/pep-0526/} 定義的 @code{simple name} 目標之外的所有內容）的註釋不再使用 @code{from __future__ import comments} 造成任何執行環境 (runtime) 影響。（由 Batuhan Taskaya 在 bpo-42737@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42737} 中貢獻。）

@item 
類別和模組物件現在會根據需求來延遲建立 (lazy-create) 空的註釋字典 (annotations dicts)。註釋字典儲存在物件的 @code{__dict__} 中以達成向後相容性。這改進了 @code{__annotations__} 使用方式的最佳實踐方法；有關更多資訊，請參閱 @ref{9d2,,註釋 (annotation) 最佳實踐}。（由 Larry Hastings 在 bpo-43901@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43901} 中貢獻。）

@item 
附名運算式或由 @code{yield}、@code{yield from}、@code{await} 組成的註釋現在在 @code{from __future__ import comments} 下被禁止，因為它們有些不預期的行為。（由 Batuhan Taskaya 在 bpo-42725@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42725} 中貢獻。）

@item 
未繫結變數 (unbound variable)、@code{super()} 和其他可能會改變處理註釋之符號表 (symbol table) 的運算式，現在在 @code{from __future__ import comments} 下變得無效。（由 Batuhan Taskaya 在 bpo-42725@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42725} 中貢獻。）

@item 
@ref{196,,float} 型別和 @ref{1fe,,decimal.Decimal} 型別的 NaN 值的雜湊值現在取決於物件的標識值 (identity)。以前即使 NaN 值彼此不相等，它們也總是被雜湊為 @code{0}。由於在建立包含多個 NaN 的字典和集合時出現過多的雜湊衝突 (hash collision)，可能導致潛在的二次方執行環境行為 (quadratic runtime behavior)。（由 Raymond Hettinger 在 bpo-43475@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43475} 中貢獻。）

@item 
刪除 @ref{9d3,,__debug__} 常數時將引發 @ref{18e,,SyntaxError} （而不是 @ref{450,,NameError}）。（由 Donghee Na 在 bpo-45000@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45000} 中貢獻。）

@item 
@ref{18e,,SyntaxError} 例外現在具有 @code{end_lineno} 和 @code{end_offset} 屬性。如果未被決定，它們將會是 @code{None}。（由 Pablo Galindo 在 bpo-43914@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43914} 中貢獻。）
@end itemize

@node 新模組,改進的模組<4>,其他語言更動<4>,Python 3 10 有什麼新功能
@anchor{whatsnew/3 10 new-modules}@anchor{9d4}
@subsection 新模組



@itemize *

@item 
無。
@end itemize

@node 改進的模組<4>,最佳化<5>,新模組,Python 3 10 有什麼新功能
@anchor{whatsnew/3 10 improved-modules}@anchor{9d5}
@subsection 改進的模組


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

@end menu

@node asyncio<7>,argparse<4>,,改進的模組<4>
@anchor{whatsnew/3 10 asyncio}@anchor{9d6}
@subsubsection asyncio


新增缺少的 @ref{9d7,,connect_accepted_socket()} 方法。（由 Alex Grönholm 在 bpo-41332@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41332} 中貢獻。）

@node argparse<4>,array<3>,asyncio<7>,改進的模組<4>
@anchor{whatsnew/3 10 argparse}@anchor{9d8}
@subsubsection argparse


argparse 幫助中的誤導性用詞「可選引數 (optional arguments)」已被替換為「選項 (options)」。某些依賴於精確輸出匹配的測試可能需要進行調整。（由 Raymond Hettinger 在 bpo-9694@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9694} 中貢獻。）

@node array<3>,asynchat asyncore smtpd,argparse<4>,改進的模組<4>
@anchor{whatsnew/3 10 array}@anchor{9d9}
@subsubsection array


@ref{4b9,,array.array} 的 @ref{9da,,index()} 方法現在具有可選的 `start' 和 `stop' 參數。（由 Anders Lorentsen 和 Zackery Spytz 在 bpo-31956@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31956} 中貢獻。）

@node asynchat asyncore smtpd,base64<3>,array<3>,改進的模組<4>
@anchor{whatsnew/3 10 asynchat-asyncore-smtpd}@anchor{9db}
@subsubsection asynchat, asyncore, smtpd


自 Python 3.6 起，這些模組在其文件中被標記為已棄用。引入時的 @ref{1a3,,DeprecationWarning} 現已新增到這三個模組中。

@node base64<3>,bdb<2>,asynchat asyncore smtpd,改進的模組<4>
@anchor{whatsnew/3 10 base64}@anchor{9dc}
@subsubsection base64


新增 @ref{9dd,,base64.b32hexencode()} 和 @ref{9de,,base64.b32hexdecode()} 以支援擴充十六進位字母的 Base32 編碼 (Base32 Encoding with Extended Hex Alphabet)。

@node bdb<2>,bisect,base64<3>,改進的模組<4>
@anchor{whatsnew/3 10 bdb}@anchor{9df}
@subsubsection bdb


新增 @code{clearBreakpoints()} 來重置所有設定的斷點。（由 Irit Katriel 在 bpo-24160@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24160} 中貢獻。）

@node bisect,codecs,bdb<2>,改進的模組<4>
@anchor{whatsnew/3 10 bisect}@anchor{9e0}
@subsubsection bisect


新增向 @ref{12,,bisect} 模組 API 提供 `key' 函式的可能性。（由 Raymond Hettinger 在 bpo-4356@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4356} 中貢獻。）

@node codecs,collections abc,bisect,改進的模組<4>
@anchor{whatsnew/3 10 codecs}@anchor{9e1}
@subsubsection codecs


新增 @ref{9e2,,codecs.unregister()} 函式來取消註冊 (unregister) 一個編解碼器的搜尋功能。（Hai Shi 在 bpo-41842@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41842} 中貢獻。）

@node collections abc,contextlib<2>,codecs,改進的模組<4>
@anchor{whatsnew/3 10 collections-abc}@anchor{9e3}
@subsubsection collections.abc


@ref{9e4,,collections.abc.Callable} 的@ref{8b8,,參數化泛型 (parameterized generic)} 的 @code{__args__} 現在與 @ref{9c1,,typing.Callable} 一致。@ref{9e4,,collections.abc.Callable} 泛型現在會將型別參數攤平，類似於 @ref{9c1,,typing.Callable} 目前的做法。這意味著 @code{collections.abc.Callable[[int, str], str]} 將具有 @code{(int, str, str)} 的 @code{__args__}；在以前這是 @code{([int, str], str)}。為了允許此更改，現在可以對 @ref{9e5,,types.GenericAlias} 進行子類別化，並且在下標 (subscript) @ref{9e4,,collections.abc.Callable} 型別時將回傳子類別。請注意，對於無效形式的 @ref{9e4,,collections.abc.Callable} 參數化可能會引發 @ref{198,,TypeError}，而在 Python 3.9 中該參數可能會無引發例外地傳遞。（由 Ken Jin 在 bpo-42195@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42195} 中貢獻。）

@node contextlib<2>,curses<2>,collections abc,改進的模組<4>
@anchor{whatsnew/3 10 contextlib}@anchor{9e6}
@subsubsection contextlib


新增 @ref{9e7,,contextlib.aclosing()} 情境管理器以安全地關閉非同步產生器和表示非同步釋放資源的物件。（由 Joongi Kim 和 John Belmonte 在 bpo-41229@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41229} 中貢獻。）

向 @ref{9e8,,contextlib.nullcontext()} 新增非同步情境管理器支援。（由 Tom Gringauz 在 bpo-41543@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41543} 中貢獻。）

新增 @ref{9e9,,AsyncContextDecorator}，用於支援將非同步情境管理器作為裝飾器使用。

@node curses<2>,dataclasses<2>,contextlib<2>,改進的模組<4>
@anchor{whatsnew/3 10 curses}@anchor{9ea}
@subsubsection curses


ncurses 6.1 中新增的擴充顏色函式將由 @ref{9eb,,curses.color_content()}、@ref{9ec,,curses.init_color()}、@ref{9ed,,curses.init_pair()} 和 @ref{9ee,,curses.pair_content()} 透明地使用。新函式 @ref{9ef,,curses.has_extended_color_support()} 表示了底層的 ncurses 函式庫是否支援擴充顏色。（由 Jeffrey Kintscher 和 Hans Petter Jansson 在 bpo-36982@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36982} 中貢獻。）

如果 @code{BUTTON5_*} 常數是由底層 @ref{2f,,curses} 函式庫提供的，那麼它們現在會在 curses 模組中公開。（由 Zackery Spytz 在 bpo-39273@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39273} 中貢獻。）

@node dataclasses<2>,distutils<2>,curses<2>,改進的模組<4>
@anchor{whatsnew/3 10 dataclasses}@anchor{9f0}
@subsubsection dataclasses


@menu
* __slots__:: 
* 僅限關鍵字欄位 (Keyword-only fields): 僅限關鍵字欄位 Keyword-only fields. 

@end menu

@node __slots__,僅限關鍵字欄位 Keyword-only fields,,dataclasses<2>
@anchor{whatsnew/3 10 slots}@anchor{9f1}
@subsubsection __slots__


在 @ref{4dc,,dataclasses.dataclass()} 裝飾器中新增了 @code{slots} 參數。（由 Yurii Karabas 在 bpo-42269@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42269} 中貢獻）

@node 僅限關鍵字欄位 Keyword-only fields,,__slots__,dataclasses<2>
@anchor{whatsnew/3 10 keyword-only-fields}@anchor{9f2}
@subsubsection 僅限關鍵字欄位 (Keyword-only fields)


dataclasses 現在支援在產生的 __init__ 方法中包含僅限關鍵字的欄位。有多種方法可以指定僅限關鍵字欄位。

你可以說每個欄位都是關鍵字：

@example
from dataclasses import dataclass

@@dataclass(kw_only=True)
class Birthday:
    name: str
    birthday: datetime.date
@end example

@code{name} 和 @code{birthday} 都是產生的 __init__ 方法的僅限關鍵字參數。

你可以在每個欄位的基礎上指定僅限關鍵字：

@example
from dataclasses import dataclass, field

@@dataclass
class Birthday:
    name: str
    birthday: datetime.date = field(kw_only=True)
@end example

這裡只有 @code{birthday} 是僅限關鍵字。如果你在各個欄位上設定 @code{kw_only}，請注意，由於僅限關鍵字欄位需要遵循非僅限關鍵字欄位，因此會有欄位重新排序的相關規則。詳細資訊請參閱完整的 dataclasses 文件。

你還可以指定 KW_ONLY 標記後面的所有欄位均為僅限關鍵字欄位。這可能是最常見的用法：

@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

這裡的 @code{z} 和 @code{t} 是僅限關鍵字參數，而 @code{x} 和 @code{y} 則不是。（由 Eric V. Smith 在 bpo-43532@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43532} 中貢獻。）

@node distutils<2>,doctest<2>,dataclasses<2>,改進的模組<4>
@anchor{whatsnew/3 10 distutils}@anchor{9f3}@anchor{whatsnew/3 10 distutils-deprecated}@anchor{92c}
@subsubsection distutils


整個 @code{distutils} 套件已被棄用，將在 Python 3.12 中刪除。它指定套件建置的功能已經完全被第三方套件 @code{setuptools} 和 @code{packaging} 所取代，並且大多數其他常用的 API 都可以在標準函式庫的其他地方被找到（例如 @ref{af,,platform} 、@ref{ca,,shutil}、@ref{dc,,subprocess} 或 @ref{e1,,sysconfig}）。目前沒有將 @code{distutils} 遷移任何其他地方的計畫，且使用其他功能的應用程式應該開始規劃如何取得程式碼的私有副本。請參閱 
@geindex Python Enhancement Proposals; PEP 632
PEP 632@footnote{https://peps.python.org/pep-0632/} 的討論。

Python 3.8 中不推薦使用的 @code{bdist_wininst} 命令已被刪除。現在建議使用 @code{bdist_wheel} 命令來在 Windows 上發布二進位套件。（由 Victor Stinner 在 bpo-42802@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42802} 中貢獻。）

@node doctest<2>,encodings,distutils<2>,改進的模組<4>
@anchor{whatsnew/3 10 doctest}@anchor{9f4}
@subsubsection doctest


當模組未定義 @code{__loader__} 時，回退到 @code{__spec__.loader} 。（由 Brett Cannon 在 bpo-42133@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42133} 中貢獻。）

@node encodings,enum<4>,doctest<2>,改進的模組<4>
@anchor{whatsnew/3 10 encodings}@anchor{9f5}
@subsubsection encodings


@ref{9f6,,encodings.normalize_encoding()} 現在會忽略非 ASCII 字元。（Hai Shi 在 bpo-39337@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39337} 中貢獻。）

@node enum<4>,fileinput,encodings,改進的模組<4>
@anchor{whatsnew/3 10 enum}@anchor{9f7}
@subsubsection enum


@ref{83b,,Enum} @ref{828,,__repr__()} 現在會回傳 @code{enum_name.member_name} 、@ref{829,,__str__()} 現在會回傳 @code{member_name} 。可用作模組常數的標準函式庫列舉會有 @code{module_name.member_name} 的 @ref{1c1,,repr()}。（由 Ethan Furman 在 bpo-40066@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40066} 中貢獻。）

新增 @ref{826,,enum.StrEnum}，為所有成員都是字串的列舉。（由 Ethan Furman 在 bpo-41816@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41816} 中貢獻。）

@node fileinput,faulthandler<2>,enum<4>,改進的模組<4>
@anchor{whatsnew/3 10 fileinput}@anchor{9f8}
@subsubsection fileinput


在 @ref{9f9,,fileinput.input()} 和 @ref{938,,fileinput.FileInput} 中新增 `encoding' 和 `errors' 參數。（由 Inada Naoki 在 bpo-43712@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43712} 中貢獻。）

當 `mode' 為 "r" 並且檔案有被壓縮時，@ref{9fa,,fileinput.hook_compressed()} 現在會回傳 @ref{9b7,,TextIOWrapper} 物件（和未壓縮檔案一樣）。（由 Inada Naoki 在 bpo-5758@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5758} 中貢獻。）

@node faulthandler<2>,gc<2>,fileinput,改進的模組<4>
@anchor{whatsnew/3 10 faulthandler}@anchor{9fb}
@subsubsection faulthandler


@ref{5c,,faulthandler} 模組現在可以檢測垃圾收集器 (garbage collector) 在收集期間是否發生嚴重錯誤。（由 Victor Stinner 在 bpo-44466@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44466} 中貢獻。）

@node gc<2>,glob<2>,faulthandler<2>,改進的模組<4>
@anchor{whatsnew/3 10 gc}@anchor{9fc}
@subsubsection gc


為 @ref{9fd,,gc.get_objects()}、@ref{9fe,,gc.get_referrers()} 和 @ref{9ff,,gc.get_referents()} 新增稽核掛鉤 (audit hooks)。（由 Pablo Galindo 在 bpo-43439@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43439} 中貢獻。）

@node glob<2>,hashlib<3>,gc<2>,改進的模組<4>
@anchor{whatsnew/3 10 glob}@anchor{a00}
@subsubsection glob


在 @ref{59a,,glob()} 和 @ref{a01,,iglob()} 中新增 `root_dir' 和 `dir_fd' 參數，允許指定搜尋的根目錄。（由 Serhiy Storchaka 在 bpo-38144@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38144} 中貢獻。）

@node hashlib<3>,hmac<2>,glob<2>,改進的模組<4>
@anchor{whatsnew/3 10 hashlib}@anchor{a02}
@subsubsection hashlib


hashlib 模組需要 OpenSSL 1.1.1 或更高版本。（由 Christian Heimes 在 
@geindex Python Enhancement Proposals; PEP 644
PEP 644@footnote{https://peps.python.org/pep-0644/} 和 bpo-43669@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43669} 中貢獻。）

hashlib 模組初步支援 OpenSSL 3.0.0。（由 Christian Heimes 在 bpo-38820@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38820} 和其他問題中貢獻。）

純 Python 的 @ref{72c,,pbkdf2_hmac()} 後備 (fallback) 已被棄用。將來只有在有 OpenSSL 支援的建置 Python 中才能夠使用 PBKDF2-HMAC。（由 Christian Heimes 在 bpo-43880@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43880} 中貢獻。）

@node hmac<2>,IDLE 和 idlelib<2>,hashlib<3>,改進的模組<4>
@anchor{whatsnew/3 10 hmac}@anchor{a03}
@subsubsection hmac


hmac 模組現在在內部使用 OpenSSL 的 HMAC 實作。（由 Christian Heimes 在 bpo-40645@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40645} 中貢獻。）

@node IDLE 和 idlelib<2>,importlib metadata<2>,hmac<2>,改進的模組<4>
@anchor{whatsnew/3 10 idle-and-idlelib}@anchor{a04}
@subsubsection IDLE 和 idlelib


讓 IDLE 叫用 @ref{a05,,sys.excepthook()} （在沒有 @code{-n} 的情況下啟動時）。使用者掛鉤 (user hooks) 在以前是被忽略的。（由 Ken Hilton 在 bpo-43008@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43008} 中貢獻。）

重新排列設定對話框。將 General 分頁拆分為 Windows 和 Shell/Ed 分頁。將擴充 Help 選單的幫助來源移至 Extensions 分頁。為新選項騰出空間並縮短對話框，而後者使對話框更好地適應較小的螢幕。（由 Terry Jan Reedy 在 bpo-40468@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40468} 中貢獻。）將縮排空間設定從 Font 分頁移至新的 Windows 分頁。（由 Mark Roseman 和 Terry Jan Reedy 在 bpo-33962@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33962} 中貢獻。）

上述更改已向後移植到 3.9 維護版本。

新增 Shell 側邊欄。將主要提示字元 (@code{>>>}) 移至側邊欄。將輔助提示字元（@code{...}）新增到側邊欄。點擊左鍵再拖動能夠選擇一行或多行文字，和編輯器列號側邊欄操作一樣。選擇文字列後點擊右鍵會顯示帶有「一併複製提示字元 (copy with prompts)」的情境選單，這會將側邊欄中提示字元與所選文字並排，此選項也會出現在文字的情境選單上。（由 Tal Einat 在 bpo-37903@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37903} 中貢獻。）

使用空格而不是製表符號 (tab) 來縮進交互式程式碼。這能夠使交互式程式碼條目「看起來正確」。新增 shell 側邊欄的主要動機是實現這一點。（由 Terry Jan Reedy 在 bpo-37892@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37892} 中貢獻。）

突顯 (highlight) 模式匹配陳述式中的新@ref{a06,,軟關鍵字 (soft keywords)} @ref{a07,,match}、@ref{a07,,case} 和 @ref{a08,,_}。然而這種突顯並不完美，並且在某些罕見的情況下會出錯，包括 @code{case} 模式中的一些 @code{_}。（由 Tal Einat 在 bpo-44010@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44010} 中貢獻。）

3.10 維護版本中的新增功能。

將語法突顯 (syntax highlighting) 應用於 @code{.pyi} 檔案。（由 Alex Waygood 和 Terry Jan Reedy 在 bpo-45447@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45447} 中貢獻。）

保存帶有輸入和輸出的 Shell 時，會包含提示字元。（由 Terry Jan Reedy 在 gh-95191@footnote{https://github.com/python/cpython/issues/95191} 中貢獻。）

@node importlib metadata<2>,inspect<4>,IDLE 和 idlelib<2>,改進的模組<4>
@anchor{whatsnew/3 10 importlib-metadata}@anchor{a09}
@subsubsection importlib.metadata


與 @code{importlib_metadata} 4.6 功能相同（歷史@footnote{https://importlib-metadata.readthedocs.io/en/latest/history.html}）。

@ref{583,,importlib.metadata 入口點}現在透過新的 @ref{583,,importlib.metadata.EntryPoints} 類別提供了以群組和名稱選擇入口點的更好體驗。有關棄用與用法的更多資訊，請參閱文件中的相容性說明。

新增了 @ref{a0a,,importlib.metadata.packages_distributions()} 用於將頂階 Python 模組和套件解析出 @ref{a0b,,importlib.metadata.Distribution}。

@node inspect<4>,itertools<4>,importlib metadata<2>,改進的模組<4>
@anchor{whatsnew/3 10 inspect}@anchor{a0c}
@subsubsection inspect


當模組未定義 @code{__loader__} 時，回退到 @code{__spec__.loader} 。（由 Brett Cannon 在 bpo-42133@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42133} 中貢獻。）

新增 @ref{a0d,,inspect.get_annotations()}，它可以安全地計算物件上定義的註釋。它是存取各種型別物件註釋的怪作法 (quirks) 的變通解法 (work around)，並且對其檢查的物件做出很少的假設。 @ref{a0d,,inspect.get_annotations()} 也可以正確地取消字串化註釋 (stringized annotations)。 @ref{a0d,,inspect.get_annotations()} 現在被認為是存取任何 Python 物件上定義的註釋字典的最佳實踐；有關使用註釋的最佳實踐的更多資訊，請參閱 @ref{9d2,,註釋 (annotation) 最佳實踐}。相關地，@ref{22f,,inspect.signature()}、@ref{93a,,inspect.Signature.from_callable()} 和 @code{inspect.Signature.from_function()} 現在呼叫 @ref{a0d,,inspect.get_annotations()} 來檢索註釋。這意味著 @ref{22f,,inspect.signature()} 和 @ref{93a,,inspect.Signature.from_callable()} 現在也可以取消字串化註釋。（由 Larry Hastings 在 bpo-43817@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43817} 中貢獻。）

@node itertools<4>,linecache<2>,inspect<4>,改進的模組<4>
@anchor{whatsnew/3 10 itertools}@anchor{a0e}
@subsubsection itertools


新增 @ref{a0f,,itertools.pairwise()}。（由 Raymond Hettinger 在 bpo-38200@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38200} 中貢獻。）

@node linecache<2>,os<5>,itertools<4>,改進的模組<4>
@anchor{whatsnew/3 10 linecache}@anchor{a10}
@subsubsection linecache


當模組未定義 @code{__loader__} 時，回退到 @code{__spec__.loader} 。（由 Brett Cannon 在 bpo-42133@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42133} 中貢獻。）

@node os<5>,os path<4>,linecache<2>,改進的模組<4>
@anchor{whatsnew/3 10 os}@anchor{a11}
@subsubsection os


為 VxWorks RTOS 新增 @ref{4d6,,os.cpu_count()} 支援。（由 Peixing Xin 在 bpo-41440@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41440} 中貢獻。）

新增函式 @ref{a12,,os.eventfd()} 和相關幫助程式來包裝 Linux 上的 @code{eventfd2} 系統呼叫。（由 Christian Heimes 在 bpo-41001@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41001} 中貢獻。）

新增 @ref{a13,,os.splice()} 以允許在兩個檔案描述器 (file descriptor) 之間移動資料，而無需在核心地址空間 (kernel address space) 和使用者地址空間 (user address space) 之間進行複製，其中檔案描述器之一必須是個 pipe。（由 Pablo Galindo 在 bpo-41625@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41625} 中貢獻。）

為 macOS 新增 @ref{a14,,O_EVTONLY}、@ref{a15,,O_FSYNC}、@ref{a16,,O_SYMLINK} 和 @ref{a17,,O_NOFOLLOW_ANY}。（由 Donghee Na 在 bpo-43106@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43106} 中貢獻。）

@node os path<4>,pathlib<8>,os<5>,改進的模組<4>
@anchor{whatsnew/3 10 os-path}@anchor{a18}
@subsubsection os.path


@ref{262,,os.path.realpath()} 現在接受一個 `strict' 僅限關鍵字引數。當設定為 @code{True} 時，如果路徑不存在或遇到符號鏈接循環 (symlink loop)，則會引發 @ref{2c0,,OSError}。（由 Barney Gale 在 bpo-43757@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43757} 中貢獻。）

@node pathlib<8>,platform<3>,os path<4>,改進的模組<4>
@anchor{whatsnew/3 10 pathlib}@anchor{a19}
@subsubsection pathlib


新增 @ref{a1a,,PurePath.parents} 對於切片的支援。 （由 Joshua Cannon 在 bpo-35498@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35498} 中貢獻。）

向 @ref{a1a,,PurePath.parents} 新增負索引支援。（由 Yaroslav Pankovych 在 bpo-21041@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21041} 中貢獻。）

新增替代 @code{link_to()} 的 @ref{a1b,,Path.hardlink_to} 方法。新方法與 @ref{a1c,,symlink_to()} 具有相同的引數順序。（由 Barney Gale 在 bpo-39950@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39950} 中貢獻。）

@ref{a1d,,pathlib.Path.stat()} 和 @ref{a1e,,chmod()} 現在接受 `follow_symlinks' 僅限關鍵字引數，以與 @ref{a5,,os} 模組中的相應函式保持一致。（由 Barney Gale 在 bpo-39906@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39906} 中貢獻。）

@node platform<3>,pprint,pathlib<8>,改進的模組<4>
@anchor{whatsnew/3 10 platform}@anchor{a1f}
@subsubsection platform


新增 @ref{a20,,platform.freedesktop_os_release()} 以從 freedesktop.org os-release@footnote{https://www.freedesktop.org/software/systemd/man/os-release.html} 標準檔案中檢索出作業系統識別。（由 Christian Heimes 在 bpo-28468@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28468} 中貢獻。）

@node pprint,py_compile,platform<3>,改進的模組<4>
@anchor{whatsnew/3 10 pprint}@anchor{a21}
@subsubsection pprint


@ref{a22,,pprint.pprint()} 現在接受新的 @code{underscore_numbers} 關鍵字引數。（由 sblondon 在 bpo-42914@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42914} 中貢獻。）

@ref{b3,,pprint} 現在可以漂亮地印出 @ref{4dc,,dataclasses.dataclass} 實例。（由 Lewis Gaul 在 bpo-43080@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43080} 中貢獻。）

@node py_compile,pyclbr,pprint,改進的模組<4>
@anchor{whatsnew/3 10 py-compile}@anchor{a23}
@subsubsection py_compile


將 @code{--quiet} 選項新增到 @ref{b8,,py_compile} 的命令列介面。（由 Gregory Schevchenko 在 bpo-38731@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38731} 中貢獻。）

@node pyclbr,shelve,py_compile,改進的模組<4>
@anchor{whatsnew/3 10 pyclbr}@anchor{a24}
@subsubsection pyclbr


將 @code{end_lineno} 屬性新增到 @ref{a25,,pyclbr.readmodule()} 和 @ref{a26,,pyclbr.readmodule_ex()} 回傳的樹中的 @code{Function} 和 @code{Class} 物件。它與現有的（開始） @code{lineno} 匹配。（由 Aviral Srivastava 在 bpo-38307@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38307} 中貢獻。）

@node shelve,statistics<3>,pyclbr,改進的模組<4>
@anchor{whatsnew/3 10 shelve}@anchor{a27}
@subsubsection shelve


現在，@ref{c8,,shelve} 模組在建立 shelve 時預設使用 @ref{a28,,pickle.DEFAULT_PROTOCOL}，而不是 @ref{ab,,pickle} 的協定 @code{3}。（由 Zackery Spytz 在 bpo-34204@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34204} 中貢獻。）

@node statistics<3>,site<2>,shelve,改進的模組<4>
@anchor{whatsnew/3 10 statistics}@anchor{a29}
@subsubsection statistics


新增 @ref{a2a,,covariance()}、Pearson @ref{6dc,,correlation()} 和簡單 @ref{a2b,,linear_regression()} 函式。（由 Tymoteusz Wołodźko 在 bpo-38490@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38490} 中貢獻。）

@node site<2>,socket<3>,statistics<3>,改進的模組<4>
@anchor{whatsnew/3 10 site}@anchor{a2c}
@subsubsection site


當模組未定義 @code{__loader__} 時，回退到 @code{__spec__.loader} 。（由 Brett Cannon 在 bpo-42133@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42133} 中貢獻。）

@node socket<3>,ssl<4>,site<2>,改進的模組<4>
@anchor{whatsnew/3 10 socket}@anchor{a2d}
@subsubsection socket


@ref{a2e,,socket.timeout} 例外現在是 @ref{a2f,,TimeoutError} 的別名。（由 Christian Heimes 在 bpo-42413@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42413} 中貢獻。）

新增使用 @code{IPPROTO_MPTCP} 建立 MPTCP socket 的選項（由 Rui Cunha 在 bpo-43571@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43571} 中貢獻。）

新增 @code{IP_RECVTOS} 選項以接收服務型別 (type of service, ToS) 或 DSCP/ECN 欄位（由 Georg Sauthoff 在 44077 中貢獻。）

@node ssl<4>,sqlite3<6>,socket<3>,改進的模組<4>
@anchor{whatsnew/3 10 ssl}@anchor{a30}
@subsubsection ssl


ssl 模組需要 OpenSSL 1.1.1 或更高版本。（由 Christian Heimes 在 
@geindex Python Enhancement Proposals; PEP 644
PEP 644@footnote{https://peps.python.org/pep-0644/} 和 bpo-43669@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43669} 中貢獻。）

ssl 模組初步支援 OpenSSL 3.0.0 和新選項 @ref{a31,,OP_IGNORE_UNEXPECTED_EOF}。（由 Christian Heimes 於 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} 和 bpo-43811@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43811} 貢獻。)

已棄用函式和使用已棄用常數現在會導致 @ref{1a3,,DeprecationWarning}。 @ref{a32,,ssl.SSLContext.options} 預設設定有 @ref{a33,,OP_NO_SSLv2} 和 @ref{a34,,OP_NO_SSLv3}，因此無法再次發出設定該旗標的警告。@ref{a35,,棄用部分}包含已棄用功能的列表。（由 Christian Heimes 在 bpo-43880@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43880} 中貢獻。）

ssl 模組現在具有更安全的預設設定。預設情況下禁用沒有前向保密或 SHA-1 MAC 的密碼。安全級別 2 禁止安全性低於 112 位元的弱 RSA、DH 和 ECC 密鑰。 @ref{355,,SSLContext} 預設為最低協定版本 TLS 1.2。設定基於 Hynek Schlawack 的研究。（由 Christian Heimes 在 bpo-43998@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43998} 中貢獻。）

不再正式支援已棄用的協定 SSL 3.0、TLS 1.0 和 TLS 1.1。 Python 不會主動阻止它們。然而，OpenSSL 建置選項、發行版配置、發行商補丁和密碼套件可能會阻止交握的成功。

向 @ref{a36,,ssl.get_server_certificate()} 函式新增 `timeout' 參數。（由 Zackery Spytz 在 bpo-31870@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31870} 中貢獻。）

ssl 模組使用堆疊類型 (heap-types) 和多階段初始化 (multi-phase initialization)。（由 Christian Heimes 在 bpo-42333@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42333} 中貢獻。）

新增驗證旗標 @ref{47b,,VERIFY_X509_PARTIAL_CHAIN}。（由 l0x 在 bpo-40849@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40849} 中貢獻。）

@node sqlite3<6>,sys<5>,ssl<4>,改進的模組<4>
@anchor{whatsnew/3 10 sqlite3}@anchor{a37}
@subsubsection sqlite3


新增 @ref{5a0,,connect()}、@ref{a38,,enable_load_extension()} 和 @ref{6d8,,load_extension()} 的稽核事件。（由 Erlend E. Aasland 在 bpo-43762@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43762} 中貢獻。）

@node sys<5>,_thread,sqlite3<6>,改進的模組<4>
@anchor{whatsnew/3 10 sys}@anchor{a39}
@subsubsection sys


新增 @ref{a3a,,sys.orig_argv} 屬性：傳遞給 Python 可執行檔案的原始命令列引數列表。（由 Victor Stinner 在 bpo-23427@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23427} 中貢獻。）

新增 @ref{a3b,,sys.stdlib_module_names}，其中包含標準函式庫模組的名稱列表。 （由 Victor Stinner 在 bpo-42955@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42955} 中貢獻。）

@node _thread,threading<4>,sys<5>,改進的模組<4>
@anchor{whatsnew/3 10 thread}@anchor{a3c}
@subsubsection _thread


@ref{a3d,,_thread.interrupt_main()} 現在需要一個可選的信號編號來進行模擬（預設值仍然是 @ref{253,,signal.SIGINT}）。（由 Antoine Pitrou 在 bpo-43356@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43356} 中貢獻。）

@node threading<4>,traceback<3>,_thread,改進的模組<4>
@anchor{whatsnew/3 10 threading}@anchor{a3e}
@subsubsection threading


新增 @ref{a3f,,threading.gettrace()} 和 @ref{a40,,threading.getprofile()} 分別取得 @ref{a41,,threading.settrace()} 和 @ref{a42,,threading.setprofile()} 設定的函式。（由 Mario Corchero 在 bpo-42251@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42251} 中貢獻。）

新增 @ref{a43,,threading.__excepthook__} 以允許取得 @ref{a44,,threading.excepthook()} 的原始值，以防它被設定為損壞或不同的值。（由 Mario Corchero 在 bpo-42308@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42308} 中貢獻。）

@node traceback<3>,types<4>,threading<4>,改進的模組<4>
@anchor{whatsnew/3 10 traceback}@anchor{a45}
@subsubsection traceback


@ref{a46,,format_exception()}、@ref{a47,,format_exception_only()} 和 @ref{a48,,print_exception()} 函式現在可以將例外物件作為僅限位置引數。（由 Zackery Spytz 和 Matthias Bussonnier 在 bpo-26389@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26389} 中貢獻。）

@node types<4>,typing<6>,traceback<3>,改進的模組<4>
@anchor{whatsnew/3 10 types}@anchor{a49}
@subsubsection types


重新引入 @ref{a4a,,types.EllipsisType}、@ref{a4b,,types.NoneType} 和 @ref{a4c,,types.NotImplementedType} 類別，提供一組易於型別檢查器直譯的新型別。（由 Bas van Beek 在 bpo-41810@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41810} 中貢獻。）

@node typing<6>,unittest<6>,types<4>,改進的模組<4>
@anchor{whatsnew/3 10 typing}@anchor{a4d}
@subsubsection typing


有關重大更改，請參閱@ref{9ba,,與型別提示相關的新功能}。

@ref{a4e,,typing.Literal} 的行為已更改為符合 
@geindex Python Enhancement Proposals; PEP 586
PEP 586@footnote{https://peps.python.org/pep-0586/} 並匹配 PEP 中指定的靜態型別檢查器的行為。


@enumerate 

@item 
@code{Literal} 現在可以刪除重複參數。

@item 
@code{Literal} 物件之間的相等性比較現在與順序無關。

@item 
現在型別的比較會優先於 @code{Literal} 的比較。例如，@code{Literal[0] == Literal[False]} 先前之求值為 @code{True}，但現在它是 @code{False}。為了支援此更改，內部使用的型別快取現在支援了型別的辨認。

@item 
如果 @code{Literal} 物件的任一參數不是@ref{81d,,可雜湊的}，那麼它們現在將在相等性比較期間引發 @ref{198,,TypeError} 例外。請注意，使用不可雜湊的參數宣告 @code{Literal} 不會引發錯誤：

@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

（由 Yurii Karabas 在 bpo-42345@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42345} 中貢獻。）

新增函式 @ref{a4f,,typing.is_typeddict()} 來自我審查 (introspect) 註釋是否為 @ref{331,,typing.TypedDict}。（由 Patrick Reader 在 bpo-41792@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41792} 中貢獻。）

僅宣告了資料變數的 @code{typing.Protocol} 子類別現在在使用 @code{isinstance} 檢查時會引發 @code{TypeError} ，除非它們用 @ref{66d,,runtime_checkable()} 裝飾。此前，這些檢查都是悄無聲息地通過的。如果使用者需要執行環境協定 (runtime protocol)，則應該使用 @code{runtime_checkable()} 裝飾器來裝飾其子類別。（由 Yurii Karabas 在 bpo-38908@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38908} 中貢獻。）

從 @code{typing.io} 和 @code{typing.re} 子模組引入現在將發出 @ref{1a3,,DeprecationWarning}。這些子模組自 Python 3.8 起已被棄用，並將在未來版本的 Python 中刪除。屬於這些子模組的任何內容都應該直接從 @ref{10a,,typing} 引入。 （由 Sebastian Rittau 在 bpo-38291@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38291} 中貢獻。）

@node unittest<6>,urllib parse,typing<6>,改進的模組<4>
@anchor{whatsnew/3 10 unittest}@anchor{a50}
@subsubsection unittest


新增方法 @ref{a51,,assertNoLogs()} 以補足現有的 @ref{a52,,assertLogs()}。（由 Kit Yan Choi 在 bpo-39385@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39385} 中貢獻。）

@node urllib parse,xml<2>,unittest<6>,改進的模組<4>
@anchor{whatsnew/3 10 urllib-parse}@anchor{a53}
@subsubsection urllib.parse


Python 3.10 之前的 Python 版本允許在 @ref{31e,,urllib.parse.parse_qs()} 和 @ref{31d,,urllib.parse.parse_qsl()} 中使用 @code{;} 和 @code{&} 作為查詢參數 (query parameter) 的分隔符號。出於安全考慮，並且為了符合更新的 W3C 建議，已將其更改為僅允許單個分隔符號鍵，預設為 @code{&}。此更改還會影響 @code{cgi.parse()} 和 @code{cgi.parse_multipart()}，因為它們在內部使用受影響的函式。有關更多詳細資訊，請參閱各自的文件。（由 Adam Goldschmidt、Senthil Kumaran 和 Ken Jin 在 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{110,,urllib.parse} preventing such attacks. The removal
characters are controlled by a new module level variable
@code{urllib.parse._UNSAFE_URL_BYTES_TO_REMOVE}. (See gh-88048@footnote{https://github.com/python/cpython/issues/88048})

@node xml<2>,zipimport<3>,urllib parse,改進的模組<4>
@anchor{whatsnew/3 10 xml}@anchor{a54}
@subsubsection xml


新增 @ref{a55,,LexicalHandler} 類別到 @ref{130,,xml.sax.handler} 模組。（由 Jonathan Gossage 和 Zackery Spytz 在 bpo-35018@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35018} 中貢獻。）

@node zipimport<3>,,xml<2>,改進的模組<4>
@anchor{whatsnew/3 10 zipimport}@anchor{a56}
@subsubsection zipimport


新增與 
@geindex Python Enhancement Proposals; PEP 451
PEP 451@footnote{https://peps.python.org/pep-0451/} 相關的方法：@ref{a57,,find_spec()}、@ref{a58,,zipimport.zipimporter.create_module()} 和 @ref{338,,zipimport.zipimporter.exec_module()}。（由 Brett Cannon 在 bpo-42131@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42131} 中貢獻。）

新增 @ref{a59,,invalidate_caches()} 方法。（由 Desmond Cheong 在 bpo-14678@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14678} 中貢獻。）

@node 最佳化<5>,已棄用<6>,改進的模組<4>,Python 3 10 有什麼新功能
@anchor{whatsnew/3 10 optimizations}@anchor{a5a}
@subsection 最佳化



@itemize *

@item 
建構函式 @ref{169,,str()}、@ref{192,,bytes()} 和 @ref{343,,bytearray()} 現在更快了（對於小型物件大約快了 30--40%）。（由 Serhiy Storchaka 在 bpo-41334@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41334} 中貢獻。）

@item 
@ref{c3,,runpy} 模組現在引入更少的模組。@code{python3 -m module-name} 指令啟動時間平均快了 1.4 倍。在 Linux 上，@code{python3 -I -m module-name} 在 Python 3.9 上引入 69 個模組，而在 Python 3.10 上僅引入 51 個模組 (-18)。（由 Victor Stinner 在 bpo-41006@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41006} 和 bpo-41718@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41718} 中貢獻。）

@item 
@code{LOAD_ATTR} 指令現在使用新的「操作碼快取 (per opcode cache)」機制。現在一般屬性的速度提高了約 36%，槽位 (slot) 的速度提高了 44%。（由 Pablo Galindo 和 Yury Selivanov 在 bpo-42093@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42093} 中以及 Guido van Rossum 在 bpo-42927@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42927} 中貢獻，基於最初在 PyPy 和 MicroPython 中實作的想法。）

@item 
當使用 @ref{a5b,,--enable-optimizations} 建置 Python 時，現在 @code{-fno-semantic-interposition} 被新增到編譯和鏈接列 (link line) 中。這使得使用 @ref{a5c,,--enable-shared} 和 @code{gcc} 建立的 Python 直譯器的建置速度提高了 30%。請參閱本文@footnote{https://developers.redhat.com/blog/2020/06/25/red-hat-enterprise-linux-8-2-brings-faster-python-3-8-run-speeds/} 以了解詳情。（由 Victor Stinner 和 Pablo Galindo 在 bpo-38980@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38980} 中貢獻。）

@item 
對 @ref{14,,bz2} / @ref{8e,,lzma} / @ref{139,,zlib} 模組使用新的輸出緩衝區管理程式碼，並將 @code{.readall()} 函式新增到 @code{_compression.DecompressReader} 類別。 bz2 解壓縮速度提高了 1.09x ~ 1.17x，lzma 解壓縮速度提高了 1.20x ~ 1.32x，@code{GzipFile.read(-1)} 速度提高了 1.11x ~ 1.18x。（由 Ma Lin 於 bpo-41486@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41486} 貢獻、由 Gregory P. Smith 審閱）

@item 
使用字串化註釋時，建立函式時不再建立函式的註釋字典。取而代之的是它們被儲存為字串元組，且函式物件會根據需求才將其延遲轉換 (lazily convert) 為註釋字典。此最佳化將定義帶有註釋的函式所需的 CPU 時間減少了一半。（由 Yurii Karabas 和 Inada Naoki 在 bpo-42202@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42202} 中貢獻。）

@item 
像是 @code{str1 in str2} 和 @code{str2.find(str1)} 之類的子字串搜尋函式現在有時會使用 Crochemore & Perrin 的「雙向」字串搜尋演算法來避免作用於長字串上時發生二次方行為 (quadratic behavior)。（由 Dennis Sweeney 在 bpo-41972@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41972} 中貢獻）

@item 
向 @code{_PyType_Lookup()} 新增微最佳化以提高快取命中的常見情況下的型別屬性快取查找性能。這使得直譯器平均速度提高了 1.04 倍。（由 Dino Viehland 在 bpo-43452@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43452} 中貢獻。）

@item 
以下內建函式現在支援更快的 
@geindex Python Enhancement Proposals; PEP 590
PEP 590@footnote{https://peps.python.org/pep-0590/} vectorcall 呼叫慣例：@ref{19f,,map()}、@ref{a5d,,filter()}、@ref{a5e,,reversed()}、@ref{3c1,,bool()} 和 @ref{196,,float()}。（由 Donghee Na 和 Jeroen Demeyer 在 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} 和 bpo-41870@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41870} 中貢獻。）

@item 
通過刪除內部 @code{RLock}，@ref{a5f,,BZ2File} 的性能得到了改進。這使得 @code{BZ2File} 在面對多個同時的讀取器或寫入器時執行緒不安全，就像 @ref{6b,,gzip} 和 @ref{8e,,lzma} 中的等效類別一樣。（由 Inada Naoki 在 bpo-43785@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43785} 中貢獻。）
@end itemize

@node 已棄用<6>,已刪除,最佳化<5>,Python 3 10 有什麼新功能
@anchor{whatsnew/3 10 deprecated}@anchor{a60}@anchor{whatsnew/3 10 whatsnew310-deprecated}@anchor{a35}
@subsection 已棄用



@itemize *

@item 
目前 Python 接受緊跟關鍵字的數字字面值 (numeric literals)，例如 @code{0in x}、@code{1or x}、@code{0if 1else 2}。它允許了令人困惑和不明確的運算式，例如 @code{[0x1for x in y]} （可以直譯為 @code{[0x1 for x in y]} 或 @code{[0x1f or x in y]} ）。從此版本開始，如果數字字面值後緊跟關鍵字 @ref{347,,and}、@ref{17c,,else}、@ref{348,,for}、@ref{181,,if}、@ref{349,,in}、@ref{34a,,is} 與 @ref{34b,,or} 其中之一，則會引發棄用警告。在未來的版本中，它將被變更為語法警告，最後成為為語法錯誤。（由 Serhiy Storchaka 在 bpo-43833@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43833} 中貢獻。）

@item 
從這個版本開始，我們將齊心協力開始清理為相容 Python 2.7 而保留的舊引入語義。具體來說， @code{find_loader()}/@code{find_module()} （被 @ref{a61,,find_spec()} 取代）、@ref{a62,,load_module()} （被 @ref{a63,,exec_module()} 取代）、 @code{module_repr()} （引入系統負責處理你）、@code{__package__} 屬性（由 @code{__spec__.parent} 取代）、 @code{__loader__} 屬性（由 @code{__spec__.loader} 取代）和 @code{__cached__} 屬性（由 @code{__spec__.cached} 取代）將慢慢被刪除（以及 @ref{7b,,importlib} 中的其他類別和方法）。將酌情引發 @ref{717,,ImportWarning} 和/或 @ref{1a3,,DeprecationWarning} 以幫助識別在此轉換期間需要更新的程式碼。

@item 
整個 @code{distutils} 命名空間已棄用，將在 Python 3.12 中刪除。請參閱@ref{92c,,模組更改} 以取得更多資訊。

@item 
@ref{a64,,random.randrange()} 的非整數引數已棄用。@ref{2eb,,ValueError} 已被棄用，取而代之的是 @ref{198,,TypeError}。（由 Serhiy Storchaka 和 Raymond Hettinger 在 bpo-37319@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37319} 中貢獻。）

@item 
@ref{7b,,importlib} 的各種 @code{load_module()} 方法自 Python 3.6 起已被記錄為已棄用，但現在也會觸發 @ref{1a3,,DeprecationWarning}。請改用 @ref{a63,,exec_module()}。（由 Brett Cannon 在 bpo-26131@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26131} 中貢獻。）

@item 
@code{zimport.zipimporter.load_module()} 已被棄用，請用 @ref{338,,exec_module()}。（由 Brett Cannon 在 bpo-26131@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26131} 中貢獻。）

@item 
引入系統使用 @ref{a62,,load_module()} 現在會觸發 @ref{717,,ImportWarning}，因為 @ref{a63,,exec_module()} 是目前首選。（由 Brett Cannon 在 bpo-26131@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26131} 中貢獻。）

@item 
引入系統使用 @code{importlib.abc.MetaPathFinder.find_module()} 和 @code{importlib.abc.PathEntryFinder.find_module()} 現在會觸發 @ref{717,,ImportWarning}，因為 @ref{a61,,importlib.abc.MetaPathFinder.find_spec()} 和 @ref{a65,,importlib.abc.PathEntryFinder.find_spec()} 分別是替代方案的首選。你可以使用 @ref{a66,,importlib.util.spec_from_loader()} 來幫助移植。（由 Brett Cannon 在 bpo-42134@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42134} 中貢獻。）

@item 
引入系統使用 @code{importlib.abc.PathEntryFinder.find_loader()} 現在會觸發 @ref{717,,ImportWarning}，因為 @ref{a65,,importlib.abc.PathEntryFinder.find_spec()} 是首選。你可以使用 @ref{a66,,importlib.util.spec_from_loader()} 來幫助移植。（由 Brett Cannon 在 bpo-43672@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43672} 中貢獻。）

@item 
@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()} ) 和 @code{importlib.abc.PathEntryFinder.find_loader()} (@code{importlib.machinery.FileFinder.find_loader()} ) 現在引發 @ref{1a3,,DeprecationWarning} 並計劃在 Python 3.12 中刪除（之前它們已在 Python 3.4 中被記錄為已棄用）。（由 Brett Cannon 在 bpo-42135@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42135} 中貢獻。）

@item 
@code{importlib.abc.Finder} 已被棄用（包括其唯一方法 @code{find_module()}）。@ref{a67,,importlib.abc.MetaPathFinder} 和 @ref{a68,,importlib.abc.PathEntryFinder} 都不再從該類別繼承。使用者應該根據需求來選擇其一以繼承。（由 Brett Cannon 在 bpo-42135@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42135} 中貢獻。）

@item 
棄用 @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} 和 @code{pkgutil.ImpLoader} 均已更新，將於 Python 3.12 列為預定的刪除版本（它們開始在過去版本的 Python 中引發 @ref{1a3,,DeprecationWarning}） 。（由 Brett Cannon 在 bpo-43720@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43720} 中貢獻。）

@item 
引入系統現在在模組上使用 @code{__spec__} 屬性，然後才會回退使用 @code{module_repr()} 作為模組的 @code{__repr__()} 方法。計劃在 Python 3.12 中刪除 @code{module_repr()} 的使用。（由 Brett Cannon 在 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()} 和 @code{importlib.machinery.BuiltinLoader.module_repr()} 已棄用並計劃在 Python 3.12 中刪除。（由 Brett Cannon 在 bpo-42136@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42136} 中貢獻。）

@item 
自 Python 3.3 起，@code{sqlite3.OptimizedUnicode} 就沒有文件記錄並且已過時，當時它被用作 @ref{169,,str} 的別名。它現已被棄用，並計劃在 Python 3.12 中刪除。（由 Erlend E. Aasland 在 bpo-42264@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42264} 中貢獻。）

@item 
未記錄於說明文件的內建函式 @code{sqlite3.enable_shared_cache} 現已棄用，計劃在 Python 3.12 中刪除。SQLite3 文件強烈建議不去使用它。有關更多詳細資訊，請參閱 SQLite3 文件@footnote{https://sqlite.org/c3ref/enable_shared_cache.html}。如果必須使用共享快取，請使用 @code{cache=shared} 查詢參數以 URI 模式打開資料庫。（由 Erlend E. Aasland 在 bpo-24464@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24464} 中貢獻。）

@item 
以下 @code{threading} 方法現已棄用：


@itemize *

@item 
@code{threading.currentThread} => @ref{35c,,threading.current_thread()}

@item 
@code{threading.activeCount} => @ref{35d,,threading.active_count()}

@item 
@code{threading.Condition.notifyAll} =>
@ref{357,,threading.Condition.notify_all()}

@item 
@code{threading.Event.isSet} => @ref{358,,threading.Event.is_set()}

@item 
@code{threading.Thread.setName} => @ref{2a0,,threading.Thread.name}

@item 
@code{threading.thread.getName} => @ref{2a0,,threading.Thread.name}

@item 
@code{threading.Thread.isDaemon} => @ref{35a,,threading.Thread.daemon}

@item 
@code{threading.Thread.setDaemon} => @ref{35a,,threading.Thread.daemon}
@end itemize

（由 Jelle Zijlstra 在 gh-87889@footnote{https://github.com/python/cpython/issues/87889} 中貢獻。）

@item 
@code{pathlib.Path.link_to()} 已棄用並計劃在 Python 3.12 中刪除。請改用 @ref{a1b,,pathlib.Path.hardlink_to()}。（由 Barney Gale 在 bpo-39950@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39950} 中貢獻。）

@item 
@code{cgi.log()} 已棄用並計劃在 Python 3.12 中刪除。（由 Inada Naoki 在 bpo-41139@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41139} 中貢獻。）

@item 
自 Python 3.6、Python 3.7 或 OpenSSL 1.1.0 起，以下 @ref{d5,,ssl} 功能已被棄用，並將在 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}、和 @code{OP_NO_TLSv1_3} 已被替換為 @code{minimum_version} 和 @code{maximum_version}。

@item 
@code{PROTOCOL_SSLv2}、@code{PROTOCOL_SSLv3}、@code{PROTOCOL_SSLv23}、@code{PROTOCOL_TLSv1}、@code{PROTOCOL_TLSv1_1}、@code{PROTOCOL_TLSv1_2} 和 @code{PROTOCOL_TLS} 已棄用，取而代之的是 @ref{a69,,PROTOCOL_TLS_CLIENT} 和 @ref{a6a,,PROTOCOL_TLS_SERVER}

@item 
@code{wrap_socket()} 被替換為 @ref{741,,ssl.SSLContext.wrap_socket()}

@item 
@code{match_hostname()}

@item 
@code{RAND_pseudo_bytes()}, @code{RAND_egd()}

@item 
NPN 功能如 @ref{a6b,,ssl.SSLSocket.selected_npn_protocol()} 和 @ref{356,,ssl.SSLContext.set_npn_protocols()} 已被 ALPN 取代。
@end itemize

@item 
執行緒除錯（@code{PYTHONTHREADDEBUG} 環境變數）在 Python 3.10 中已棄用，並將在 Python 3.12 中刪除。此功能需要一個 @ref{504,,Python 的除錯用建置版本}。（由 Victor Stinner 在 bpo-44584@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44584} 中貢獻。）

@item 
從 @code{typing.io} 和 @code{typing.re} 子模組引入現在將發出 @ref{1a3,,DeprecationWarning}。這些子模組將在 Python 的未來版本中刪除。屬於這些子模組的任何內容都應該直接從 @ref{10a,,typing} 引入。（由 Sebastian Rittau 在 bpo-38291@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38291} 中貢獻。）
@end itemize

@node 已刪除,移植到 Python 3 10,已棄用<6>,Python 3 10 有什麼新功能
@anchor{whatsnew/3 10 removed}@anchor{a6c}@anchor{whatsnew/3 10 whatsnew310-removed}@anchor{a6d}
@subsection 已刪除



@itemize *

@item 
刪除了 @ref{197,,complex} 類別的特殊方法 @code{__int__}、@code{__float__}、@code{__floordiv__}、@code{__mod__}、@code{__divmod__}、@code{__rfloordiv__}、@code{__rmod__} 和 @code{__rdivmod__} 。它們都會引發 @ref{198,,TypeError}。（由 Serhiy Storchaka 在 bpo-41974@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41974} 中貢獻。）

@item 
@code{_markupbase} 模組中私有、未於文件記錄的 @code{ParserBase.error()} 方法已被刪除。@ref{a6e,,html.parser.HTMLParser} 是 @code{ParserBase} 的唯一子類別，它的 @code{error()} 實作已在 Python 3.5 中刪除。（由 Berker Peksag 在 bpo-31844@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31844} 中貢獻。）

@item 
刪除了 @code{unicodedata.ucnhash_CAPI} 屬性，該屬性是內部 PyCapsule 物件。相關的私有 @code{_PyUnicode_Name_CAPI} 結構已移至內部 C API。（由 Victor Stinner 在 bpo-42157@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42157} 中貢獻。）

@item 
刪除了由於切換到新的 PEG 剖析器而在 3.9 中被棄用的 @code{parser} 模組。僅由舊剖析器使用的所有 C 原始碼和標頭檔也已被刪除，包括 @code{node.h}、@code{parser.h}、@code{graminit.h} 和 @code{grammar.h}。

@item 
刪除了公開 C API 函式 @code{PyParser_SimpleParseStringFlags}、@code{PyParser_SimpleParseStringFlagsFilename}、@code{PyParser_SimpleParseFileFlags} 和 @code{PyNode_Compile}，這些函式由於切換到新的 PEG 剖析器而在 3.9 中被棄用。

@item 
刪除了 @code{formatter} 模組，該模組在 Python 3.4 中已棄用。它有些過時、很少被使用，也沒有經過測試。它最初計劃在 Python 3.6 中刪除，但此類別的刪除被推遲到 Python 2.7 EOL 之後。現有使用者應該將他們使用的任何類別複製到他們的程式碼中。（由 Donghee Na 和 Terry J. Reedy 在 bpo-42299@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42299} 中貢獻。）

@item 
刪除了 @code{PyModule_GetWarningsModule()} 函式，該函式現在無用，因為 @code{_warnings} 模組在 2.6 中已轉換為內建模組。（由 Hai Shi 在 bpo-42599@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42599} 中貢獻。）

@item 
從 @ref{1e,,collections} 模組中刪除已棄用的、對 @ref{a6f,,Collections Abstract Base Classes} 的別名。（由 Victor Stinner 在 bpo-37324@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37324} 中貢獻。）

@item 
在 Python 3.8 中棄用後，@code{loop} 參數已從大多數 @ref{b,,asyncio} 的@ref{a70,,高階 API} 中刪除。這一變化的背後動機是多方面的：


@enumerate 

@item 
這簡化了高階 API。

@item 
自 Python 3.7 以來，高階 API 中的函式一直隱式取得目前執行緒正在運行的事件循環。在大多數正常用例中，不需要將事件循環傳遞給 API。

@item 
事件循環的傳遞很容易出錯，尤其是在處理在不同執行緒中運行的循環時。
@end enumerate

請注意，低階 API 仍會接受 @code{loop}。有關如何替換現有程式碼的範例，請參閱 @ref{a71,,Python API 的變更}。

（由 Yurii Karabas、Andrew Svetlov、Yury Selivanov 和 Kyle Stanley 在 bpo-42392@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42392} 中貢獻。）
@end itemize

@node 移植到 Python 3 10,CPython 位元組碼變更<5>,已刪除,Python 3 10 有什麼新功能
@anchor{whatsnew/3 10 porting-to-python-3-10}@anchor{a72}
@subsection 移植到 Python 3.10


本節列出了前面描述的更改以及可能需要更改程式碼的其他錯誤修復。

@menu
* Python 語法的變化:: 
* Python API 的變更: Python API 的變更<4>. 
* C API 中的改動: C API 中的改動<3>. 

@end menu

@node Python 語法的變化,Python API 的變更<4>,,移植到 Python 3 10
@anchor{whatsnew/3 10 changes-in-the-python-syntax}@anchor{a73}
@subsubsection Python 語法的變化



@itemize *

@item 
如果數字字面值後面緊跟關鍵字（如 @code{0in x}），在以前是有效的語法，但現在在編譯時會發出棄用警告。在未來的版本中，它將更改為語法警告，最後更改為語法錯誤。要消除警告並使程式碼與未來版本相容，只需在數字字面值和以下關鍵字之間新增一個空格即可。（由 Serhiy Storchaka 在 bpo-43833@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43833} 中貢獻。）
@end itemize

@node Python API 的變更<4>,C API 中的改動<3>,Python 語法的變化,移植到 Python 3 10
@anchor{whatsnew/3 10 changes-in-the-python-api}@anchor{a74}@anchor{whatsnew/3 10 changes-python-api}@anchor{a71}
@subsubsection Python API 的變更



@itemize *

@item 
@ref{a46,,format_exception()}、@ref{a47,,format_exception_only()} 和 @ref{104,,traceback} 模組中的 @ref{a48,,print_exception()} 函式的 `etype' 參數已重命名為 `exc'。（由 Zackery Spytz 和 Matthias Bussonnier 在 bpo-26389@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26389} 中貢獻。）

@item 
@ref{d,,atexit}：在 Python 退出時，如果一個使用 @ref{a75,,atexit.register()} 註冊的回呼 (callback) 失敗，該例外現在會被記錄下來。在以前只記錄一些例外，並且最後一個例外總是被默默地忽略。（由 Victor Stinner 在 bpo-42639@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42639} 中貢獻。）

@item 
@ref{9e4,,collections.abc.Callable} 泛型現在會攤平型別參數，類似於 @ref{9c1,,typing.Callable} 目前的做法。這意味著 @code{collections.abc.Callable[[int, str], str]} 將具有 @code{(int, str, str)} 的 @code{__args__}；以前這是 @code{([int, str], str)}。透過 @ref{2ac,,typing.get_args()} 或 @code{__args__} 存取參數的程式碼需要考慮此變更。此外，對於無效形式的參數化 @ref{9e4,,collections.abc.Callable}，可能會引發 @ref{198,,TypeError}，而在 Python 3.9 中，該參數可能已被默默地傳遞。（由 Ken Jin 在 bpo-42195@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42195} 中貢獻。）

@item 
如果給定參數不適合 16 位元無符號整數 (16-bit unsigned integer)，@ref{a76,,socket.htons()} 和 @ref{a77,,socket.ntohs()} 現在會引發 @ref{a78,,OverflowError} 而不是 @ref{1a3,,DeprecationWarning}。（由 Erlend E. Aasland 在 bpo-42393@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42393} 中貢獻。）

@item 
在 Python 3.8 中棄用後，@code{loop} 參數已從大多數 @ref{b,,asyncio} 的@ref{a70,,高階 API} 中刪除。

目前如下所示的協程：

@example
async def foo(loop):
    await asyncio.sleep(1, loop=loop)
@end example

應替換為：

@example
async def foo():
    await asyncio.sleep(1)
@end example

如果 @code{foo()} 被專門設計為 `不' 在目前執行緒的事件循環中運行（例如在另一個執行緒的事件循環中運行），請考慮改用 @ref{a79,,asyncio.run_coroutine_threadsafe()}。

（由 Yurii Karabas、Andrew Svetlov、Yury Selivanov 和 Kyle Stanley 在 bpo-42392@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42392} 中貢獻。）

@item 
如果 `globals' 字典沒有 @code{"__builtins__"} 鍵，則 @ref{a7a,,types.FunctionType} 建構函式現在會繼承目前的內建物件，而不是使用 @code{@{"None": None@}}：相同行為如 @ref{49e,,eval()} 和 @ref{49d,,exec()} 函式。在 Python 中使用 @code{def function(...): ...} 定義函式不受影響，全域變數不能用此語法覆蓋：它也繼承目前的內建物件。（由 Victor Stinner 在 bpo-42990@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42990} 中貢獻。）
@end itemize

@node C API 中的改動<3>,,Python API 的變更<4>,移植到 Python 3 10
@anchor{whatsnew/3 10 changes-in-the-c-api}@anchor{a7b}
@subsubsection C API 中的改動



@itemize *

@item 
由於切換到新的 PEG 剖析器，C API 函式 @code{PyParser_SimpleParseStringFlags}、@code{PyParser_SimpleParseStringFlagsFilename}、@code{PyParser_SimpleParseFileFlags}、@code{PyNode_Compile} 和被這些函式使用的型別 @code{struct _node} 被刪除。

現在應該將源程式碼直接（例如透過 @ref{a7c,,Py_CompileString()}）編譯為程式碼物件。然後可以（例如透過 @ref{a7d,,PyEval_EvalCode()}）為產生的程式碼物件求值 (evaluated)。

具體來說：


@itemize *

@item 
後跟有 @code{PyNode_Compile} 呼叫的 @code{PyParser_SimpleParseStringFlags} 呼叫，可以替換為呼叫 @ref{a7c,,Py_CompileString()}。

@item 
沒有 @code{PyParser_SimpleParseFileFlags} 的直接替代品。要從 @code{FILE *} 引數編譯程式碼，你需要用 C 讀取檔案並將結果緩衝區傳遞給 @ref{a7c,,Py_CompileString()}。

@item 
要編譯給定 @code{char *} 檔案名稱的檔案，請顯式打開該檔案，讀取它並編譯結果。一種方法是使用 @ref{83,,io} 模組和 @ref{3da,,PyImport_ImportModule()}、@ref{638,,PyObject_CallMethod()}、@ref{a7e,,PyBytes_AsString()} 和 @ref{a7c,,Py_CompileString()}，如下所示。（宣告和錯誤處理在此被省略。）：

@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 
對於 @code{FrameObject} 物件，@ref{a7f,,f_lasti} 成員現在表示了字碼偏移量 (wordcode offset)，而不是位元組碼字串的簡單偏移量。這意味著這個數字需要乘以 2 才能與需要位元組偏移量的 API 一起使用（例如 @ref{a80,,PyCode_Addr2Line()}）。還要注意，@code{FrameObject} 物件的 @code{f_lasti} 成員不被認為是穩定的：請改用 @ref{986,,PyFrame_GetLineNumber()}。
@end itemize
@end itemize

@node CPython 位元組碼變更<5>,建置變更<5>,移植到 Python 3 10,Python 3 10 有什麼新功能
@anchor{whatsnew/3 10 cpython-bytecode-changes}@anchor{a81}
@subsection CPython 位元組碼變更



@itemize *

@item 
@code{MAKE_FUNCTION} 指令現在接受字典或字串元組作為函式的註釋。（由 Yurii Karabas 和 Inada Naoki 在 bpo-42202@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42202} 中貢獻。）
@end itemize

@node 建置變更<5>,C API 變更<5>,CPython 位元組碼變更<5>,Python 3 10 有什麼新功能
@anchor{whatsnew/3 10 build-changes}@anchor{a82}
@subsection 建置變更



@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 644
PEP 644@footnote{https://peps.python.org/pep-0644/}：Python 現在需要 OpenSSL 1.1.1 或更高版本。不再支援 OpenSSL 1.0.2。（由 Christian Heimes 在 bpo-43669@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43669} 中貢獻。）

@item 
現在需要 C99 函式 @code{snprintf()} 和 @code{vsnprintf()} 來建置 Python。 （由 Victor Stinner 在 bpo-36020@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36020} 中貢獻。）

@item 
@ref{d4,,sqlite3} 需要 SQLite 3.7.15 或更新版本。（由 Sergey Fedoseev 和 Erlend E. Aasland 在 bpo-40744@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40744} 和 bpo-40810@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40810} 中貢獻。）

@item 
@ref{d,,atexit} 模組現在必須都被建置為內建模組。（由 Victor Stinner 在 bpo-42639@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42639} 中貢獻。）

@item 
將 @ref{a83,,--disable-test-modules} 選項新增到 @code{configure} 腳本中：不建置也不安裝測試模組。（由 Xavier de Gaye、Thomas Petazzoni 和 Peixing Xin 在 bpo-27640@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27640} 中貢獻。）

@item 
將 @ref{a84,,--with-wheel-pkg-dir=PATH 選項} 新增到 @code{./configure} 腳本中。如果有指定，@ref{59,,ensurepip} 模組會在此目錄中查找 @code{setuptools} 和 @code{pip} wheel 套件：如果兩者都存在，則使用這些 wheel 套件而不是 ensurepip 捆綁的 wheel 套件。

一些 Linux 發行版的打包策略建議不要一併包入依賴項目。例如，Fedora 在 @code{/usr/share/python-wheels/} 目錄中安裝 wheel 套件，並且不安裝 @code{ensurepip._bundled} 套件。

（由 Victor Stinner 在 bpo-42856@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42856} 中貢獻。）

@item 
新增 @ref{a85,,configure --without-static-libpython 選項} 以不建置 @code{libpythonMAJOR.MINOR.a} 靜態函式庫且不安裝 @code{python.o} 目標檔案。

（由 Victor Stinner 在 bpo-43103@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43103} 中貢獻。）

@item 
如果可用，@code{configure} 腳本現在使用 @code{pkg-config} 工具程式 (utility) 來檢測 Tcl/Tk 標頭檔和函式庫的位置。和以前一樣，可以使用 @code{--with-tcltk-includes} 和 @code{--with-tcltk-libs} 配置選項顯式指定這些位置。（由 Manolis Stamatogiannakis 在 bpo-42603@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42603} 中貢獻。）

@item 
將 @ref{a86,,--with-openssl-rpath} 選項新增到 @code{configure} 腳本中。該選項簡化了使用自定義 OpenSSL 安裝建置 Python 的過程，例如 @code{./configure --with-openssl=/path/to/openssl --with-openssl-rpath=auto}。（由 Christian Heimes 在 bpo-43466@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43466} 中貢獻。）
@end itemize

@node C API 變更<5>,Python 3 10 7 中顯著的安全性功能,建置變更<5>,Python 3 10 有什麼新功能
@anchor{whatsnew/3 10 c-api-changes}@anchor{a87}
@subsection C API 變更


@menu
* PEP 652：維護穩定 ABI:: 
* 新增功能: 新增功能<8>. 
* 移植到 Python 3.10: 移植到 Python 3 10<2>. 
* 已棄用: 已棄用<7>. 
* 已刪除: 已刪除<2>. 

@end menu

@node PEP 652：維護穩定 ABI,新增功能<8>,,C API 變更<5>
@anchor{whatsnew/3 10 pep-652-maintaining-the-stable-abi}@anchor{a88}
@subsubsection PEP 652：維護穩定 ABI


用於擴充模組或嵌入 Python 的穩定 ABI（應用程式二進位介面）現已明確定義。 @ref{76e,,C API 穩定性} 描述了 C API 和 ABI 穩定性保證以及使用穩定 ABI 的最佳實踐。

（由 Petr Viktorin 在 
@geindex Python Enhancement Proposals; PEP 652
PEP 652@footnote{https://peps.python.org/pep-0652/} 和 bpo-43795@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43795} 中貢獻。）

@node 新增功能<8>,移植到 Python 3 10<2>,PEP 652：維護穩定 ABI,C API 變更<5>
@anchor{whatsnew/3 10 id1}@anchor{a89}
@subsubsection 新增功能



@itemize *

@item 
@ref{a8a,,PyNumber_Index()} 的結果現在都具有精確的 @ref{19b,,int} 型別。在以前，結果可能是 @code{int} 子類別的實例。（由 Serhiy Storchaka 在 bpo-40792@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40792} 中貢獻。）

@item 
將新的 @ref{a8b,,orig_argv} 成員新增到 @ref{3f4,,PyConfig} 結構：傳遞給 Python 可執行檔案的原始命令列參數列表。（由 Victor Stinner 在 bpo-23427@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23427} 中貢獻。）

@item 
新增了 @ref{a8c,,PyDateTime_DATE_GET_TZINFO()} 和 @ref{a8d,,PyDateTime_TIME_GET_TZINFO()} 巨集，用於存取 @ref{4dd,,datetime.datetime} 和 @ref{1fb,,datetime.time} 物件的 @code{tzinfo} 屬性。（由 Zackery Spytz 在 bpo-30155@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30155} 中貢獻。）

@item 
新增 @ref{a8e,,PyCodec_Unregister()} 函式來取消註冊編解碼器搜尋函式。（由 Hai Shi 在 bpo-41842@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41842} 中貢獻。）

@item 
新增了 @ref{a8f,,PyIter_Send()} 函式，以允許將值發送到疊代器中，而不會引發 @code{StopIteration} 例外。（由 Vladimir Matveev 在 bpo-41756@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41756} 中貢獻。）

@item 
將 @ref{a90,,PyUnicode_AsUTF8AndSize()} 新增到受限 C API (limited C API) 中。（由 Alex Gaynor 在 bpo-41784@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41784} 中貢獻。）

@item 
新增 @ref{602,,PyModule_AddObjectRef()} 函式：類似於 @ref{603,,PyModule_AddObject()} 但成功時不竊取對值的參照。（由 Victor Stinner 在 bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741} 中貢獻。）

@item 
新增 @ref{a91,,Py_NewRef()} 和 @ref{a92,,Py_XNewRef()} 函式來增加物件的參照計數並回傳物件。（由 Victor Stinner 在 bpo-42262@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42262} 中貢獻。）

@item 
@ref{797,,PyType_FromSpecWithBases()} 和 @ref{76c,,PyType_FromModuleAndSpec()} 函式現在接受單個類別作為 `bases' 引數。（由 Serhiy Storchaka 在 bpo-42423@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42423} 中貢獻。）

@item 
@ref{76c,,PyType_FromModuleAndSpec()} 函式現在接受 NULL @code{tp_doc} 槽位。（由 Hai Shi 在 bpo-41832@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41832} 中貢獻。）

@item 
@ref{a93,,PyType_GetSlot()} 函式可以接受@ref{97b,,靜態型別 (static type)}。（由 Hai Shi 和 Petr Viktorin 在 bpo-41073@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41073} 中貢獻。）

@item 
向 C-API 新增 @ref{a94,,PySet_CheckExact()} 函式，以檢查物件是否是 @ref{184,,set} 的實例而不是子型別的實例。（由 Pablo Galindo 在 bpo-43277@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43277} 中貢獻。）

@item 
新增 @ref{a95,,PyErr_SetInterruptEx()}，它允許傳遞信號編號來進行模擬。（由 Antoine Pitrou 在 bpo-43356@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43356} 中貢獻。）

@item 
如 @ref{504,,Python 是在除錯模式 (debug mode)} 下建置的（如果有定義 @code{Py_DEBUG} 巨集），現在會支援受限 C API。在受限 C API 中，如果 Python 是在除錯模式下建置的，並且 @code{Py_LIMITED_API} 巨集的目標是 Python 3.10 或更新版本，@ref{788,,Py_INCREF()} 和 @ref{789,,Py_DECREF()} 函式現在的實作是不透明函式呼叫，而不是直接存取 @ref{a96,,PyObject.ob_refcnt} 成員。在除錯模式下支援受限 C API 成為可能，因為自 Python 3.8 以來，@ref{5d7,,PyObject} 結構在發布和除錯模式下是相同的（請參閱:issue:@cite{36465}）。

@ref{62e,,--with-trace-refs} 特殊建置（@code{Py_TRACE_REFS} 巨集）仍不支援受限 C API。（由 Victor Stinner 在 bpo-43688@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43688} 中貢獻。）

@item 
新增 @ref{a97,,Py_Is(x@comma{} y)} 函式來測試 `x' 物件是否為 `y' 物件，與 Python 中的 @code{x is y} 相同。還新增 @ref{a98,,Py_IsNone()}、@ref{a99,,Py_IsTrue()}、@ref{a9a,,Py_IsFalse()} 函式來分別測試物件是否為 @code{None} 單例、 @code{True} 單例或 @code{False} 單例。（由 Victor Stinner 在 bpo-43753@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43753} 中貢獻。）

@item 
新增函式以從 C 程式碼控制垃圾收集器：@ref{a9b,,PyGC_Enable()}、@ref{a9c,,PyGC_Disable()}、@ref{a9d,,PyGC_IsEnabled()}。這些函式使得能夠從 C 程式碼啟用、停用和查詢垃圾收集器的狀態，而無需引入 @ref{64,,gc} 模組。

@item 
新增 @ref{79b,,Py_TPFLAGS_DISALLOW_INSTANTIATION} 型別旗標以禁止建立型別實例。（由 Victor Stinner 在 bpo-43916@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43916} 中貢獻。）

@item 
新增 @ref{3cd,,Py_TPFLAGS_IMMUTABLETYPE} 型別旗標用於建立不可變型別物件：無法設定或刪除型別屬性。（由 Victor Stinner 和 Erlend E. Aasland 在 bpo-43908@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43908} 中貢獻。）
@end itemize

@node 移植到 Python 3 10<2>,已棄用<7>,新增功能<8>,C API 變更<5>
@anchor{whatsnew/3 10 id2}@anchor{a9e}
@subsubsection 移植到 Python 3.10



@itemize *

@item 
現在必須定義 @code{PY_SSIZE_T_CLEAN} 巨集以使用 @ref{3bf,,PyArg_ParseTuple()} 和 @ref{3c0,,Py_BuildValue()} 格式，這些格式使用 @code{#}: @code{es#}, @code{et#}、@code{s#}、@code{u#}、@code{y#}、@code{z#}、@code{U#} 和 @code{Z#}。請參閱 @ref{3d3,,剖析引數與建置數值} 和 
@geindex Python Enhancement Proposals; PEP 353
PEP 353@footnote{https://peps.python.org/pep-0353/}。（由 Victor Stinner 在 bpo-40943@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40943} 中貢獻。）

@item 
由於 @ref{2cf,,Py_REFCNT()} 更改為行內靜態函式 (inline static function)，因此 @code{Py_REFCNT(obj) = new_refcnt} 必須替換為 @code{Py_SET_REFCNT(obj, new_refcnt)} ：參見 @ref{a9f,,Py_SET_REFCNT()} （自 Python 3.9 起可用）。為了向後相容，可以使用該巨集：

@example
#if PY_VERSION_HEX < 0x030900A4
#  define Py_SET_REFCNT(obj, refcnt) ((Py_REFCNT(obj) = (refcnt)), (void)0)
#endif
@end example

（由 Victor Stinner 在 bpo-39573@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39573} 中貢獻。）

@item 
由於過去的種種原因，過去在不持有 @ref{164,,GIL} 的情況下呼叫 @ref{620,,PyDict_GetItem()} 是被允許的。目前已被禁止。（由 Victor Stinner 在 bpo-40839@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40839} 中貢獻。）

@item 
@code{PyUnicode_FromUnicode(NULL, size)} 和 @code{PyUnicode_FromStringAndSize(NULL, size)} 現在會引發 @code{DeprecationWarning}。請改用 @ref{aa0,,PyUnicode_New()} 來分配沒有初始資料的 Unicode 物件。（由 Inada Naoki 在 bpo-36346@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36346} 中貢獻。）

@item 
PyCapsule API @code{unicodedata.ucnhash_CAPI} 的私有 @code{_PyUnicode_Name_CAPI} 結構已移至內部 C API。（由 Victor Stinner 在 bpo-42157@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42157} 中貢獻。）

@item 
如果在 @ref{45e,,Py_Initialize()} 之前（Python 初始化之前）被呼叫，@ref{3e1,,Py_GetPath()}、@ref{3e3,,Py_GetPrefix()}、@ref{3e7,,Py_GetExecPrefix()}、@ref{3ea,,Py_GetProgramFullPath()}、@ref{3ed,,Py_GetPythonHome()} 和 @ref{3ec,,Py_GetProgramName()} 現在會回傳 @code{NULL}。使用新的 @ref{63e,,Python 初始化設定} API 來取得 @ref{aa1,,Python 路徑配置}。（由 Victor Stinner 在 bpo-42260@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42260} 中貢獻。）

@item 
@ref{627,,PyList_SET_ITEM()}、@ref{626,,PyTuple_SET_ITEM()} 和 @ref{aa2,,PyCell_SET()} 巨集不能再用作左值 (l-value) 或右值 (r-value)。例如，@code{x = PyList_SET_ITEM(a, b, c)} 和 @code{PyList_SET_ITEM(a, b, c) = x} 現在會失敗並出現編譯器錯誤。它可以防止如 @code{if (PyList_SET_ITEM (a, b, c) < 0) ...} 測試之類的錯誤。（由 Zackery Spytz 和 Victor Stinner 在 bpo-30459@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30459} 中貢獻。）

@item 
非受限 API 檔案 @code{odictobject.h}、@code{parser_interface.h}、@code{picklebufobject.h}、@code{pyarena.h}、@code{pyctype.h}、@code{pydebug.h}、@code{pyfpe.h} 和 @code{pytime.h} 已移至 @code{Include/cpython} 目錄。這些檔案不得直接被引入，因為它們已於 @code{Python.h} 中引入；請參閱 @ref{97f,,引入檔案 (include files)}。如果直接引入它們，請考慮改為引入 @code{Python.h}。（由 Nicholas Sim 在 bpo-35134@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35134} 中貢獻。）

@item 
使用 @ref{3cd,,Py_TPFLAGS_IMMUTABLETYPE} 型別旗標來建立不可變型別物件。不要依賴 @ref{aa3,,Py_TPFLAGS_HEAPTYPE} 來決定型別物件是否可變；應改為檢查是否設定了 @ref{3cd,,Py_TPFLAGS_IMMUTABLETYPE}。（由 Victor Stinner 和 Erlend E. Aasland 在 bpo-35134@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35134} 中貢獻。）

@item 
未以說明文件記錄的函式 @code{Py_FrozenMain} 已從受限 API 中刪除。該函式主要用於 Python 的自定義建置。（由 Petr Viktorin 在 bpo-26241@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26241} 中貢獻。）
@end itemize

@node 已棄用<7>,已刪除<2>,移植到 Python 3 10<2>,C API 變更<5>
@anchor{whatsnew/3 10 id3}@anchor{aa4}
@subsubsection 已棄用



@itemize *

@item 
@code{PyUnicode_InternImmortal()} 函式現已棄用，並將在 Python 3.12 中刪除：請改用 @ref{aa5,,PyUnicode_InternInPlace()}。（由 Victor Stinner 在 bpo-41692@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41692} 中貢獻。）
@end itemize

@node 已刪除<2>,,已棄用<7>,C API 變更<5>
@anchor{whatsnew/3 10 id4}@anchor{aa6}
@subsubsection 已刪除



@itemize *

@item 
刪除了操作 @code{Py_UNICODE*} 字串的 @code{Py_UNICODE_str*} 函式。（由 Inada Naoki 在 bpo-41123@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41123} 中貢獻。）


@itemize *

@item 
@code{Py_UNICODE_strlen}：使用 @ref{aa7,,PyUnicode_GetLength()} 或 @ref{aa8,,PyUnicode_GET_LENGTH}

@item 
@code{Py_UNICODE_strcat}：使用 @ref{aa9,,PyUnicode_CopyCharacters()} 或 @ref{623,,PyUnicode_FromFormat()}

@item 
@code{Py_UNICODE_strcpy}、@code{Py_UNICODE_strncpy}：使用 @ref{aa9,,PyUnicode_CopyCharacters()} 或 @ref{aaa,,PyUnicode_Substring()}

@item 
@code{Py_UNICODE_strcmp}：使用 @ref{aab,,PyUnicode_Compare()}

@item 
@code{Py_UNICODE_strncmp}：使用 @ref{aac,,PyUnicode_Tailmatch()}

@item 
@code{Py_UNICODE_strchr}、@code{Py_UNICODE_strrchr}：使用 @ref{aad,,PyUnicode_FindChar()}
@end itemize

@item 
刪除了 @code{PyUnicode_GetMax()}。請改用新的 (
@geindex Python Enhancement Proposals; PEP 393
PEP 393@footnote{https://peps.python.org/pep-0393/}) API。（由 Inada Naoki 在 bpo-41103@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41103} 中貢獻。）

@item 
刪除了 @code{PyLong_FromUnicode()}。請改用 @ref{aae,,PyLong_FromUnicodeObject()}。（由 Inada Naoki 在 bpo-41103@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41103} 中貢獻。）

@item 
刪除了 @code{PyUnicode_AsUnicodeCopy()}。請改用 @ref{aaf,,PyUnicode_AsUCS4Copy()} 或 @ref{ab0,,PyUnicode_AsWideCharString()} （由 Inada Naoki 在 bpo-41103@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41103} 中貢獻。）

@item 
刪除了 @code{_Py_CheckRecursionLimit} 變數：它已被 @ref{ab1,,PyInterpreterState} 結構的 @code{ceval.recursion_limit} 取代。（由 Victor Stinner 在 bpo-41834@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41834} 中貢獻。）

@item 
刪除了未被說明文件記錄的巨集 @code{Py_ALLOW_RECURSION} 和 @code{Py_END_ALLOW_RECURSION} 以及 @ref{ab1,,PyInterpreterState} 結構的 @code{recursion_ritic} 欄位。（由 Serhiy Storchaka 在 bpo-41936@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41936} 中貢獻。）

@item 
刪除了未被說明文件記錄的 @code{PyOS_InitInterrupts()} 函式。初始化 Python 已經隱式安裝信號處理程式：請參閱 @ref{ab2,,PyConfig.install_signal_handlers}。（由 Victor Stinner 在 bpo-41713@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41713} 中貢獻。）

@item 
刪除 @code{PyAST_Validate()} 函式。不再可能使用公開 C API 來建置 AST 物件（@code{mod_ty} 類型）。該函式已被排除在受限 C API 之外 (
@geindex Python Enhancement Proposals; PEP 384
PEP 384@footnote{https://peps.python.org/pep-0384/})。（由 Victor Stinner 在 bpo-43244@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43244} 中貢獻。）

@item 
刪除 @code{symtable.h} 標頭檔和未被說明文件記錄的函式：


@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

@code{Py_SymtableString()} 函式錯誤地成為穩定 ABI 的一部分，但它因為 @code{symtable.h} 標頭檔被排除在受限 C API 之外而無法使用。

請改用 Python @ref{de,,symtable} 模組。（由 Victor Stinner 在 bpo-43244@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43244} 中貢獻。）

@item 
從受限 C API 標頭和 @code{python3.dll} （在 Windows 上提供穩定 ABI 的函式庫）中刪除 @ref{79e,,PyOS_ReadlineFunctionPointer()}。由於該函式採用 FILE* 引數，因此無法保證其 ABI 穩定性。（由 Petr Viktorin 在 bpo-43868@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43868} 中貢獻。）

@item 
刪除 @code{ast.h}、@code{asdl.h} 和 @code{Python-ast.h} 標頭檔。這些函式沒有文件記錄，並且被排除在受限 C API 之外。這些標頭檔定義的大多數名稱都沒有前綴 @code{Py}，因此可能會產生名稱衝突。例如，@code{Python-ast.h} 定義了一個 @code{Yield} 巨集，它與 Windows @code{<winbase.h>} 標頭使用的 @code{Yield} 有名稱衝突。請改用 Python @ref{9,,ast} 模組。（由 Victor Stinner 在 bpo-43244@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43244} 中貢獻。）

@item 
刪除編譯器和使用 @code{struct _mod} 的剖析器函式，因為公開 AST C API 已被刪除：


@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

這些函式沒有文件記錄，並且被排除在受限 C API 之外。（由 Victor Stinner 在 bpo-43244@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43244} 中貢獻。）

@item 
刪除包含以下函式的 @code{pyarena.h} 標頭檔：


@itemize *

@item 
@code{PyArena_New()}

@item 
@code{PyArena_Free()}

@item 
@code{PyArena_Malloc()}

@item 
@code{PyArena_AddPyObject()}
@end itemize

這些函式沒有文件記錄、被排除在受限 C API 之外，並僅被編譯器於內部使用。（由 Victor Stinner 在 bpo-43244@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43244} 中貢獻。）

@item 
為了 Python 最佳化，已刪除 @code{PyThreadState.use_tracing} 成員。（由 Mark Shannon 在 bpo-43760@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43760} 中貢獻。）
@end itemize

@node Python 3 10 7 中顯著的安全性功能,Python 3 10 8 中顯著的安全性功能,C API 變更<5>,Python 3 10 有什麼新功能
@anchor{whatsnew/3 10 notable-security-feature-in-3-10-7}@anchor{ab3}
@subsection Python 3.10.7 中顯著的安全性功能


Converting between @ref{19b,,int} and @ref{169,,str} in bases other than 2
(binary), 4, 8 (octal), 16 (hexadecimal), or 32 such as base 10 (decimal)
now raises a @ref{2eb,,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{df,,sys} APIs. See the @ref{804,,integer string conversion length limitation} documentation.  The default limit
is 4300 digits in string form.

@node Python 3 10 8 中顯著的安全性功能,Python 3 10 12 中顯著的變更,Python 3 10 7 中顯著的安全性功能,Python 3 10 有什麼新功能
@anchor{whatsnew/3 10 notable-security-feature-in-3-10-8}@anchor{ab4}
@subsection Python 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 Python 3 10 12 中顯著的變更,,Python 3 10 8 中顯著的安全性功能,Python 3 10 有什麼新功能
@anchor{whatsnew/3 10 notable-changes-in-3-10-12}@anchor{ab5}
@subsection Python 3.10.12 中顯著的變更


@menu
* tarfile: tarfile<3>. 

@end menu

@node tarfile<3>,,,Python 3 10 12 中顯著的變更
@anchor{whatsnew/3 10 tarfile}@anchor{ab6}
@subsubsection tarfile



@itemize *

@item 
The extraction methods in @ref{e4,,tarfile}, and @ref{68f,,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{690,,Extraction filters} for details.
In Python 3.12, use without the `filter' argument will show a
@ref{1a3,,DeprecationWarning}.
In Python 3.14, the default will switch to @code{'data'}.
(Contributed by Petr Viktorin in 
@geindex Python Enhancement Proposals; PEP 706
PEP 706@footnote{https://peps.python.org/pep-0706/}.)
@end itemize

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Python 3 9 有什麼新功能,Python 3 8 有什麼新功能,Python 3 10 有什麼新功能,Python 有什麼新功能？
@anchor{whatsnew/3 9 doc}@anchor{ab7}@anchor{whatsnew/3 9 translation-repo}@anchor{ab8}@anchor{whatsnew/3 9 what-s-new-in-python-3-9}@anchor{ab9}
@section Python 3.9 有什麼新功能


@*編輯者: 
Ł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.

本文介紹了 Python 3.9 與 3.8 相比多了哪些新功能。Python 3.9 已於 2020 年 10 月 5 日發布。有關完整詳細資訊，請參閱 @ref{142,,changelog}。


@subsubheading 也參考


@geindex Python Enhancement Proposals; PEP 596
PEP 596@footnote{https://peps.python.org/pep-0596/} - Python 3.9 發佈時程


@menu
* 發布重點摘要: 發布重點摘要<5>. 
* You should check for DeprecationWarning in your code:: 
* 新增功能: 新增功能<9>. 
* 其他語言更動: 其他語言更動<5>. 
* 新模組: 新模組<2>. 
* 改進的模組: 改進的模組<5>. 
* 最佳化: 最佳化<6>. 
* 已棄用: 已棄用<8>. 
* 已移除: 已移除<6>. 
* 移植至 Python 3.9: 移植至 Python 3 9. 
* 建置變更: 建置變更<6>. 
* C API 變更: C API 變更<6>. 
* Python 3.9.1 中顯著的變更: Python 3 9 1 中顯著的變更. 
* Python 3.9.2 中顯著的變更: Python 3 9 2 中顯著的變更. 
* Python 3.9.3 中顯著的變更: Python 3 9 3 中顯著的變更. 
* Python 3.9.5 中顯著的變更: Python 3 9 5 中顯著的變更. 
* Python 3.9.14 中顯著的安全性功能: Python 3 9 14 中顯著的安全性功能. 
* Python 3.9.17 中顯著的變更: Python 3 9 17 中顯著的變更. 

@end menu

@node 發布重點摘要<5>,You should check for DeprecationWarning in your code,,Python 3 9 有什麼新功能
@anchor{whatsnew/3 9 summary-release-highlights}@anchor{aba}
@subsection 發布重點摘要


@c This section singles out the most important changes in Python 3.9.
@c Brevity is key.

新增語法特性：


@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

新的內建功能：


@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{69d,,os.pidfd_open()} added that allows process management without races
and signals.
@end itemize

直譯器的改進：


@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{92,,math}, @ref{a3,,operator}, @ref{c1,,resource},
@ref{f4,,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{6a,,grp},
@code{_hashlib}, @ref{b7,,pwd}, @code{_posixsubprocess}, @ref{bd,,random},
@ref{c6,,select}, @ref{db,,struct}, @ref{e7,,termios}, @ref{139,,zlib}) are now using
the stable ABI defined by PEP 384.
@end itemize

新的函式庫模組：


@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{13a,,zoneinfo} module;

@item 
an implementation of a topological sort of a graph is now provided in
the new @ref{69,,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,新增功能<9>,發布重點摘要<5>,Python 3 9 有什麼新功能
@anchor{whatsnew/3 9 you-should-check-for-deprecationwarning-in-your-code}@anchor{abb}
@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{1a3,,DeprecationWarning} warning for
several years. For example, using @code{collections.Mapping} instead of
@code{collections.abc.Mapping} emits a @ref{1a3,,DeprecationWarning} since Python
3.3, released in 2012.

Test your application with the @ref{abc,,-W} @code{default} command-line option to see
@ref{1a3,,DeprecationWarning} and @ref{abd,,PendingDeprecationWarning}, or even with
@ref{abc,,-W} @code{error} to treat them as errors. @ref{1b1,,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{a6f,,Abstract Base Classes} in
the @ref{1e,,collections} module, like @code{collections.Mapping} alias to
@ref{abe,,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{503,,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{abf,,已移除} section.

@node 新增功能<9>,其他語言更動<5>,You should check for DeprecationWarning in your code,Python 3 9 有什麼新功能
@anchor{whatsnew/3 9 new-features}@anchor{ac0}
@subsection 新增功能


@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,,新增功能<9>
@anchor{whatsnew/3 9 dictionary-merge-update-operators}@anchor{ac1}
@subsubsection Dictionary Merge & Update Operators


Merge (@code{|}) and update (@code{|=}) operators have been added to the built-in
@ref{183,,dict} class. Those complement the existing @code{dict.update} and
@code{@{**d1, **d2@}} methods of merging dictionaries.

範例：

@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,新增功能<9>
@anchor{whatsnew/3 9 new-string-methods-to-remove-prefixes-and-suffixes}@anchor{ac2}
@subsubsection New String Methods to Remove Prefixes and Suffixes


@ref{ac3,,str.removeprefix(prefix)} and
@ref{ac4,,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,新增功能<9>
@anchor{whatsnew/3 9 type-hinting-generics-in-standard-collections}@anchor{ac5}
@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
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,新增功能<9>
@anchor{whatsnew/3 9 new-parser}@anchor{ac6}
@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 其他語言更動<5>,新模組<2>,新增功能<9>,Python 3 9 有什麼新功能
@anchor{whatsnew/3 9 other-language-changes}@anchor{ac7}
@subsection 其他語言更動



@itemize *

@item 
@ref{ac8,,__import__()} now raises @ref{653,,ImportError} instead of
@ref{2eb,,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{81a,,os.chdir()}. As a side effect, the traceback also displays the
absolute path for @ref{1,,__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{503,,Python Development Mode} and in @ref{504,,debug build}, the
`encoding' and `errors' arguments are now checked for string encoding and
decoding operations. Examples: @ref{315,,open()}, @ref{ac9,,str.encode()} and
@ref{aca,,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{192,,bytes} and @ref{343,,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{932,,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{10a,,typing} module. Docstrings are now shown for
all special forms and special generic aliases (like @code{Union} and @code{List}).
Using @ref{acb,,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{acc,,aclose()} / @ref{acd,,asend()} /
@ref{716,,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{349,,in} operator and functions
@ref{ace,,contains()}, @ref{acf,,indexOf()} and
@ref{ad0,,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 新模組<2>,改進的模組<5>,其他語言更動<5>,Python 3 9 有什麼新功能
@anchor{whatsnew/3 9 new-modules}@anchor{ad1}
@subsection 新模組


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

@end menu

@node zoneinfo,graphlib<2>,,新模組<2>
@anchor{whatsnew/3 9 zoneinfo}@anchor{ad2}
@subsubsection zoneinfo


The @ref{13a,,zoneinfo} module brings support for the IANA time zone database to
the standard library. It adds @ref{ad3,,zoneinfo.ZoneInfo}, a concrete
@ref{7ef,,datetime.tzinfo} implementation backed by the system's time zone data.

範例：

@example
>>> from zoneinfo import ZoneInfo
>>> from datetime import datetime, timedelta

>>> # 日光節約時間
>>> dt = datetime(2020, 10, 31, 12, tzinfo=ZoneInfo("America/Los_Angeles"))
>>> print(dt)
2020-10-31 12:00:00-07:00
>>> dt.tzname()
'PDT'

>>> # 標準時間
>>> dt += timedelta(days=7)
>>> print(dt)
2020-11-07 12:00:00-08:00
>>> print(dt.tzname())
PST
@end example

As a fall-back source of data for platforms that don't ship the IANA database,
the tzdata@footnote{https://pypi.org/project/tzdata/} module was released as a first-party package -- distributed via
PyPI and maintained by the CPython core team.


@subsubheading 也參考



@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

由 Paul Ganssle 撰寫 PEP 與實作
@end table


@node graphlib<2>,,zoneinfo,新模組<2>
@anchor{whatsnew/3 9 graphlib}@anchor{ad4}
@subsubsection graphlib


A new module, @ref{69,,graphlib}, was added that contains the
@ref{ad5,,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 改進的模組<5>,最佳化<6>,新模組<2>,Python 3 9 有什麼新功能
@anchor{whatsnew/3 9 improved-modules}@anchor{ad6}
@subsection 改進的模組


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

@end menu

@node ast<4>,asyncio<8>,,改進的模組<5>
@anchor{whatsnew/3 9 ast}@anchor{ad7}
@subsubsection ast


Added the `indent' option to @ref{ad8,,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{ad9,,ast.unparse()} as a function in the @ref{9,,ast} module that can
be used to unparse an @ref{4be,,ast.AST} object and produce a string with code
that would produce an equivalent @ref{4be,,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<8>,compileall<2>,ast<4>,改進的模組<5>
@anchor{whatsnew/3 9 asyncio}@anchor{ada}
@subsubsection asyncio


Due to significant security concerns, the `reuse_address' parameter of
@ref{934,,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{6b2,,coroutine} @ref{adb,,shutdown_default_executor()}
that schedules a shutdown for the default executor that waits on the
@ref{941,,ThreadPoolExecutor} to finish closing. Also,
@ref{2f2,,asyncio.run()} has been updated to use the new @ref{6b2,,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{6b2,,coroutine} @ref{adc,,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{add,,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{80e,,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{198,,TypeError} when calling incompatible
methods with an @ref{ade,,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<3>,asyncio<8>,改進的模組<5>
@anchor{whatsnew/3 9 compileall}@anchor{adf}
@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<3>,curses<3>,compileall<2>,改進的模組<5>
@anchor{whatsnew/3 9 concurrent-futures}@anchor{ae0}
@subsubsection concurrent.futures


Added a new `cancel_futures' parameter to
@ref{ae1,,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{941,,ThreadPoolExecutor}
and @ref{1d6,,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{1d6,,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<3>,concurrent futures<3>,改進的模組<5>
@anchor{whatsnew/3 9 curses}@anchor{ae2}
@subsubsection curses


Added @ref{ae3,,curses.get_escdelay()}, @ref{ae4,,curses.set_escdelay()},
@ref{ae5,,curses.get_tabsize()}, and @ref{ae6,,curses.set_tabsize()} functions.
(Contributed by Anthony Sottile in bpo-38312@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38312}.)

@node datetime<3>,distutils<3>,curses<3>,改進的模組<5>
@anchor{whatsnew/3 9 datetime}@anchor{ae7}
@subsubsection datetime


The @ref{ae8,,isocalendar()} of @ref{1fa,,datetime.date}
and @ref{ae9,,isocalendar()} of @ref{4dd,,datetime.datetime}
methods now returns a @ref{4db,,namedtuple()} instead of a @ref{60c,,tuple}.
(Contributed by Donghee Na in bpo-24416@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24416}.)

@node distutils<3>,fcntl<2>,datetime<3>,改進的模組<5>
@anchor{whatsnew/3 9 distutils}@anchor{aea}
@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>,改進的模組<5>
@anchor{whatsnew/3 9 fcntl}@anchor{aeb}
@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<3>,fcntl<2>,改進的模組<5>
@anchor{whatsnew/3 9 ftplib}@anchor{aec}
@subsubsection ftplib


@ref{aed,,FTP} and @ref{aee,,FTP_TLS} now raise a @ref{2eb,,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<3>,hashlib<4>,ftplib<2>,改進的模組<5>
@anchor{whatsnew/3 9 gc}@anchor{aef}
@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{af0,,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<4>,http<2>,gc<3>,改進的模組<5>
@anchor{whatsnew/3 9 hashlib}@anchor{af1}
@subsubsection hashlib


The @ref{6c,,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 和 idlelib<3>,hashlib<4>,改進的模組<5>
@anchor{whatsnew/3 9 http}@anchor{af2}
@subsubsection http


HTTP status codes @code{103 EARLY_HINTS}, @code{418 IM_A_TEAPOT} and @code{425 TOO_EARLY} are added to
@ref{af3,,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 和 idlelib<3>,imaplib<2>,http<2>,改進的模組<5>
@anchor{whatsnew/3 9 idle-and-idlelib}@anchor{af4}
@subsubsection IDLE 和 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{a05,,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 和 idlelib<3>,改進的模組<5>
@anchor{whatsnew/3 9 imaplib}@anchor{af5}
@subsubsection imaplib


@ref{af6,,IMAP4} and @ref{af7,,IMAP4_SSL} now have
an optional `timeout' parameter for their constructors.
Also, the @ref{af8,,open()} method now has an optional `timeout' parameter
with this change. The overridden methods of @ref{af7,,IMAP4_SSL} and
@ref{af9,,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{afa,,imaplib.IMAP4.unselect()} is added.
@ref{afa,,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{afb,,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<5>,imaplib<2>,改進的模組<5>
@anchor{whatsnew/3 9 importlib}@anchor{afc}
@subsubsection importlib


To improve consistency with import statements, @ref{afd,,importlib.util.resolve_name()}
now raises @ref{653,,ImportError} instead of @ref{2eb,,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{6af,,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<5>,ipaddress<2>,importlib<3>,改進的模組<5>
@anchor{whatsnew/3 9 inspect}@anchor{afe}
@subsubsection inspect


@ref{aff,,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<5>,inspect<5>,改進的模組<5>
@anchor{whatsnew/3 9 ipaddress}@anchor{b00}
@subsubsection ipaddress


@ref{84,,ipaddress} now supports IPv6 Scoped Addresses (IPv6 address with suffix @code{%<scope_id>}).

Scoped IPv6 addresses can be parsed using @ref{508,,ipaddress.IPv6Address}.
If present, scope zone ID is available through the @ref{b01,,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{84,,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<5>,multiprocessing<3>,ipaddress<2>,改進的模組<5>
@anchor{whatsnew/3 9 math}@anchor{b02}
@subsubsection math


Expanded the @ref{b03,,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{b04,,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{6b9,,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{b05,,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<5>,改進的模組<5>
@anchor{whatsnew/3 9 multiprocessing}@anchor{b06}
@subsubsection multiprocessing


The @ref{b07,,multiprocessing.SimpleQueue} class has a new
@ref{b08,,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<6>,multiprocessing<3>,改進的模組<5>
@anchor{whatsnew/3 9 nntplib}@anchor{b09}
@subsubsection nntplib


@code{NNTP} and @code{NNTP_SSL} now raise a @ref{2eb,,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<6>,pathlib<9>,nntplib,改進的模組<5>
@anchor{whatsnew/3 9 os}@anchor{b0a}
@subsubsection os


Added @ref{b0b,,CLD_KILLED} and @ref{b0c,,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{69d,,os.pidfd_open()} (bpo-38692@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38692}) and
@ref{b0d,,os.P_PIDFD} (bpo-38713@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38713}) for process management with file
descriptors.

The @ref{25c,,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{25b,,os.putenv()} and @ref{25c,,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{b0e,,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<9>,pdb<5>,os<6>,改進的模組<5>
@anchor{whatsnew/3 9 pathlib}@anchor{b0f}
@subsubsection pathlib


Added @ref{b10,,pathlib.Path.readlink()} which acts similarly to
@ref{b11,,os.readlink()}.
(Contributed by Girts Folkmanis in bpo-30618@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30618})

@node pdb<5>,poplib,pathlib<9>,改進的模組<5>
@anchor{whatsnew/3 9 pdb}@anchor{b12}
@subsubsection pdb


On Windows now @ref{273,,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<2>,pdb<5>,改進的模組<5>
@anchor{whatsnew/3 9 poplib}@anchor{b13}
@subsubsection poplib


@ref{b14,,POP3} and @ref{b15,,POP3_SSL} now raise a @ref{2eb,,ValueError}
if the given timeout for their constructor is zero to prevent the creation of
a non-blocking socket. (Contributed by Donghee Na in bpo-39259@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39259}.)

@node pprint<2>,pydoc<2>,poplib,改進的模組<5>
@anchor{whatsnew/3 9 pprint}@anchor{b16}
@subsubsection pprint


@ref{b3,,pprint} can now pretty-print @ref{4e0,,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<2>,改進的模組<5>
@anchor{whatsnew/3 9 pydoc}@anchor{b17}
@subsubsection pydoc


The documentation string is now shown not only for class, function,
method etc, but for any object that has its own @ref{b18,,__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>,改進的模組<5>
@anchor{whatsnew/3 9 random}@anchor{b19}
@subsubsection random


Added a new @ref{b1a,,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>,改進的模組<5>
@anchor{whatsnew/3 9 signal}@anchor{b1b}
@subsubsection signal


Exposed the Linux-specific @ref{b1c,,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<4>,signal,改進的模組<5>
@anchor{whatsnew/3 9 smtplib}@anchor{b1d}
@subsubsection smtplib


@ref{b1e,,SMTP} and @ref{b1f,,SMTP_SSL} now raise a @ref{2eb,,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{b20,,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<4>,time<3>,smtplib,改進的模組<5>
@anchor{whatsnew/3 9 socket}@anchor{b21}
@subsubsection socket


The @ref{d1,,socket} module now exports the @ref{b22,,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{b23,,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{b24,,socket.send_fds()} and
@ref{b25,,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<6>,socket<4>,改進的模組<5>
@anchor{whatsnew/3 9 time}@anchor{b26}
@subsubsection time


On AIX, @ref{b27,,thread_time()} is now implemented with @code{thread_cputime()}
which has nanosecond resolution, rather than
@code{clock_gettime(CLOCK_THREAD_CPUTIME_ID)} which has a resolution of 10 milliseconds.
(Contributed by Batuhan Taskaya in bpo-40192@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40192})

@node sys<6>,tracemalloc,time<3>,改進的模組<5>
@anchor{whatsnew/3 9 sys}@anchor{b28}
@subsubsection sys


Added a new @ref{b29,,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{b2a,,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<7>,sys<6>,改進的模組<5>
@anchor{whatsnew/3 9 tracemalloc}@anchor{b2b}
@subsubsection tracemalloc


Added @ref{b2c,,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<7>,unicodedata<5>,tracemalloc,改進的模組<5>
@anchor{whatsnew/3 9 typing}@anchor{b2d}
@subsubsection typing


@geindex Python Enhancement Proposals; PEP 593
PEP 593@footnote{https://peps.python.org/pep-0593/} introduced an @ref{b2e,,typing.Annotated} type to decorate existing
types with context-specific metadata and new @code{include_extras} parameter to
@ref{8b9,,typing.get_type_hints()} to access the metadata at runtime. (Contributed
by Till Varoquaux and Konstantin Kashin.)

@node unicodedata<5>,venv<3>,typing<7>,改進的模組<5>
@anchor{whatsnew/3 9 unicodedata}@anchor{b2f}
@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<3>,xml<3>,unicodedata<5>,改進的模組<5>
@anchor{whatsnew/3 9 venv}@anchor{b30}
@subsubsection venv


The activation scripts provided by @ref{117,,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<3>,,venv<3>,改進的模組<5>
@anchor{whatsnew/3 9 xml}@anchor{b31}
@subsubsection xml


White space characters within attributes are now preserved when serializing
@ref{12b,,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 最佳化<6>,已棄用<8>,改進的模組<5>,Python 3 9 有什麼新功能
@anchor{whatsnew/3 9 optimizations}@anchor{b32}
@subsection 最佳化



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

（由 Serhiy Storchaka 在 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{dc,,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{b33,,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{b34,,range}, @ref{60c,,tuple}, @ref{184,,set},
@ref{7eb,,frozenset}, @ref{24d,,list}, @ref{183,,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{b35,,floor division} of float operation now has a better performance. Also
the message of @ref{b36,,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 已棄用<8>,已移除<6>,最佳化<6>,Python 3 9 有什麼新功能
@anchor{whatsnew/3 9 deprecated}@anchor{b37}
@subsection 已棄用



@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{b38,,math.factorial()} accepts @ref{196,,float} instances with
non-negative integer values (like @code{5.0}).  It raises a @ref{2eb,,ValueError}
for non-integral and negative floats.  It is now deprecated.  In future
Python versions it will raise a @ref{198,,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{1a2,,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{198,,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{bd,,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{87e,,None}, @ref{19b,,int},
@ref{196,,float}, @ref{169,,str}, @ref{192,,bytes}, and @ref{343,,bytearray}.

@item 
Opening the @ref{654,,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{6a0,,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

（由 Victor Stinner 在 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{164,,GIL} is initialized
by @ref{45e,,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{757,,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{abd,,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{946,,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 已移除<6>,移植至 Python 3 9,已棄用<8>,Python 3 9 有什麼新功能
@anchor{whatsnew/3 9 removed}@anchor{b39}@anchor{whatsnew/3 9 removed-in-python-39}@anchor{abf}
@subsection 已移除



@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{4b9,,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{87e,,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{b3a,,sys.getswitchinterval()} and @ref{b3b,,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{b3c,,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{176,,threading.Thread}
has been removed. It was deprecated since Python 3.8.
Use @ref{b3d,,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{b3e,,ElementTree} and
@ref{361,,Element} in the @ref{12b,,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{b3f,,load()}, @ref{b40,,loads()}, @ref{b41,,dump()}, and
@ref{b42,,dumps()} functions. Additionally, the `use_builtin_types' parameter was
removed, standard @ref{192,,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{b43,,base64.encodebytes()} and
@ref{b44,,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{b03,,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{a5f,,bz2.BZ2File} has been removed. Since
Python 3.0, it was ignored and using it emitted a @ref{1a3,,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{b45,,json.loads()} has been removed.
As of Python 3.1, it was deprecated and ignored; using it has emitted a
@ref{1a3,,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{3f4,,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{330,,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{69e,,asyncio.current_task()} and @ref{b46,,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{a6e,,html.parser.HTMLParser} class
has been removed (it was deprecated since Python 3.4).  @ref{b47,,html.unescape()}
should be used for converting character references to the corresponding
unicode characters.
@end itemize

@node 移植至 Python 3 9,建置變更<6>,已移除<6>,Python 3 9 有什麼新功能
@anchor{whatsnew/3 9 porting-to-python-3-9}@anchor{b48}
@subsection 移植至 Python 3.9


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

@menu
* Python API 的變更: Python API 的變更<5>. 
* C API 中的改動: C API 中的改動<4>. 
* CPython 位元組碼變更: CPython 位元組碼變更<6>. 

@end menu

@node Python API 的變更<5>,C API 中的改動<4>,,移植至 Python 3 9
@anchor{whatsnew/3 9 changes-in-the-python-api}@anchor{b49}
@subsubsection Python API 的變更



@itemize *

@item 
@ref{ac8,,__import__()} and @ref{afd,,importlib.util.resolve_name()} now raise
@ref{653,,ImportError} where it previously raised @ref{2eb,,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{117,,venv} activation scripts no longer special-case when
@code{__VENV_PROMPT__} is set to @code{""}.

@item 
The @ref{b4a,,select.epoll.unregister()} method no longer ignores the
@ref{b4b,,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{a5f,,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{7b,,importlib} module now ignores the 
@geindex PYTHONCASEOK
@geindex 環境變數; PYTHONCASEOK
@ref{b4c,,PYTHONCASEOK}
environment variable when the @ref{b4d,,-E} or @ref{b4e,,-I} command line
options are being used.

@item 
The `encoding' parameter has been added to the classes @ref{aed,,ftplib.FTP} and
@ref{aee,,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{adb,,asyncio.loop.shutdown_default_executor()} has been added to
@ref{b4f,,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{b50,,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{6c6,,PurePath} now returns @ref{1a2,,NotImplemented}
instead of raising a @ref{198,,TypeError} when passed something other than an
instance of @code{str} or @ref{6c6,,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{84,,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{b51,,socket.inet_aton()} treats leading zeros as octal
notatation. glibc implementation of modern @ref{b52,,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{b53,,codecs.lookup()} now normalizes the encoding name the same way as
@ref{9f6,,encodings.normalize_encoding()}, except that @ref{b53,,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 C API 中的改動<4>,CPython 位元組碼變更<6>,Python API 的變更<5>,移植至 Python 3 9
@anchor{whatsnew/3 9 changes-in-the-c-api}@anchor{b54}
@subsubsection C API 中的改動



@itemize *

@item 
Instances of @ref{b55,,heap-allocated types} (such as those created with
@ref{796,,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{979,,tp_traverse} function,
ensure that all custom @code{tp_traverse} functions of heap-allocated types
visit the object's type.

@quotation

範例：

@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{b55,,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

（更多資訊請見 bpo-35810@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35810} 與 bpo-40217@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40217}。）

@item 
The functions @code{PyEval_CallObject}, @code{PyEval_CallFunction},
@code{PyEval_CallMethod} and @code{PyEval_CallObjectWithKeywords} are deprecated.
Use @ref{635,,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 位元組碼變更<6>,,C API 中的改動<4>,移植至 Python 3 9
@anchor{whatsnew/3 9 cpython-bytecode-changes}@anchor{b56}
@subsubsection CPython 位元組碼變更



@itemize *

@item 
The @code{LOAD_ASSERTION_ERROR} opcode was added for handling the
@ref{b57,,assert} statement. Previously, the assert statement would not work
correctly if the @ref{8b0,,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{b58,,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

（由 Mark Shannon 在 bpo-39156@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39156} 中貢獻。）
@end itemize

@node 建置變更<6>,C API 變更<6>,移植至 Python 3 9,Python 3 9 有什麼新功能
@anchor{whatsnew/3 9 build-changes}@anchor{b59}
@subsection 建置變更



@itemize *

@item 
Added @code{--with-platlibdir} option to the @code{configure} script: name of the
platform-specific library directory, stored in the new @ref{b29,,sys.platlibdir}
attribute. See @ref{b29,,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{b5a,,--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 變更<6>,Python 3 9 1 中顯著的變更,建置變更<6>,Python 3 9 有什麼新功能
@anchor{whatsnew/3 9 c-api-changes}@anchor{b5b}
@subsection C API 變更


@menu
* 新增功能: 新增功能<10>. 
* 移植至 Python 3.9: 移植至 Python 3 9<2>. 
* 已移除: 已移除<7>. 

@end menu

@node 新增功能<10>,移植至 Python 3 9<2>,,C API 變更<6>
@anchor{whatsnew/3 9 id1}@anchor{b5c}
@subsubsection 新增功能



@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 573
PEP 573@footnote{https://peps.python.org/pep-0573/}: Added @ref{76c,,PyType_FromModuleAndSpec()} to associate
a module with a class; @ref{b5d,,PyType_GetModule()} and
@ref{b5e,,PyType_GetModuleState()} to retrieve the module and its state; and
@ref{960,,PyCMethod} and @ref{b5f,,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{985,,PyFrame_GetCode()} function: get a frame code.
Added @ref{981,,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{986,,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{b60,,PyThreadState_GetInterpreter()} and
@ref{644,,PyInterpreterState_Get()} functions to get the interpreter.
Added @ref{989,,PyThreadState_GetFrame()} function to get the current frame of a
Python thread state.
Added @ref{b61,,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{634,,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{3d0,,Py_EnterRecursiveCall()} and @ref{b62,,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

（由 Victor Stinner 在 38644 和 39542 中貢獻。）

@item 
The @ref{b63,,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{b64,,PyObject_GC_IsTracked()} and
@ref{b65,,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{b66,,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 移植至 Python 3 9<2>,已移除<7>,新增功能<10>,C API 變更<6>
@anchor{whatsnew/3 9 id2}@anchor{b67}
@subsubsection 移植至 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{b68,,m_traverse},
@ref{b69,,m_clear} and @ref{b6a,,m_free}
functions of @ref{b6b,,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{b6c,,Py_mod_exec} function). More precisely, these functions are not called
if @ref{b6d,,m_size} is greater than 0 and the module state (as
returned by @ref{b6e,,PyModule_GetState()}) is @code{NULL}.

Extension modules without module state (@code{m_size <= 0}) are not affected.

@item 
If @ref{b6f,,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{3e2,,sys.path} when
the @code{-E} option is used (if @ref{409,,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{b70,,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{b71,,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{b72,,PyObject_IS_GC()} macro was converted to a function.

@item 
The @code{PyObject_NEW()} macro becomes an alias to the
@ref{b73,,PyObject_New} macro, and the @code{PyObject_NEW_VAR()} macro
becomes an alias to the @ref{b74,,PyObject_NewVar} macro. They no longer
access directly the @ref{b75,,PyTypeObject.tp_basicsize} member.

@item 
@code{PyObject_GET_WEAKREFS_LISTPTR()} macro was converted to a function:
the macro accessed directly the @ref{b76,,PyTypeObject.tp_weaklistoffset}
member.

@item 
@ref{631,,PyObject_CheckBuffer()} macro was converted to a function: the macro
accessed directly the @ref{b77,,PyTypeObject.tp_as_buffer} member.

@item 
@ref{b78,,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{b79,,PyTypeObject.tp_as_number} member.
@end itemize

（更多資訊請見 bpo-40170@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40170}。）
@end itemize

@node 已移除<7>,,移植至 Python 3 9<2>,C API 變更<6>
@anchor{whatsnew/3 9 id3}@anchor{b7a}
@subsubsection 已移除



@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{b7b,,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

（由 Victor Stinner 在 38644 和 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{b7c,,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{aac,,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 Python 3 9 1 中顯著的變更,Python 3 9 2 中顯著的變更,C API 變更<6>,Python 3 9 有什麼新功能
@anchor{whatsnew/3 9 notable-changes-in-python-3-9-1}@anchor{b7d}
@subsection Python 3.9.1 中顯著的變更


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

@end menu

@node typing<8>,macOS 11 0 Big Sur and Apple Silicon Mac support,,Python 3 9 1 中顯著的變更
@anchor{whatsnew/3 9 id4}@anchor{b7e}
@subsubsection typing


The behavior of @ref{a4e,,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{198,,TypeError} exception during
equality comparisons if any of their parameters are not @ref{81d,,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

（由 Yurii Karabas 在 bpo-42345@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42345} 中貢獻。）

@node macOS 11 0 Big Sur and Apple Silicon Mac support,,typing<8>,Python 3 9 1 中顯著的變更
@anchor{whatsnew/3 9 macos-11-0-big-sur-and-apple-silicon-mac-support}@anchor{b7f}
@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").

（由 Ronald Oussoren 和 Lawrence D'Anna 在 bpo-41100@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41100} 中貢獻。）

@node Python 3 9 2 中顯著的變更,Python 3 9 3 中顯著的變更,Python 3 9 1 中顯著的變更,Python 3 9 有什麼新功能
@anchor{whatsnew/3 9 notable-changes-in-python-3-9-2}@anchor{b80}
@subsection Python 3.9.2 中顯著的變更


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

@end menu

@node collections abc<2>,urllib parse<2>,,Python 3 9 2 中顯著的變更
@anchor{whatsnew/3 9 collections-abc}@anchor{b81}
@subsubsection collections.abc


@ref{9e4,,collections.abc.Callable} generic now flattens type parameters, similar
to what @ref{9c1,,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{9e5,,types.GenericAlias} can now be subclassed, and a subclass will
be returned when subscripting the @ref{9e4,,collections.abc.Callable} type.
Code which accesses the arguments via @ref{2ac,,typing.get_args()} or @code{__args__}
need to account for this change.  A @ref{1a3,,DeprecationWarning} may be emitted for
invalid forms of parameterizing @ref{9e4,,collections.abc.Callable} which may have
passed silently in Python 3.9.1.  This @ref{1a3,,DeprecationWarning} will
become a @ref{198,,TypeError} in Python 3.10.
(Contributed by Ken Jin in bpo-42195@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42195}.)

@node urllib parse<2>,,collections abc<2>,Python 3 9 2 中顯著的變更
@anchor{whatsnew/3 9 urllib-parse}@anchor{b82}
@subsubsection urllib.parse


Earlier Python versions allowed using both @code{;} and @code{&} as
query parameter separators in @ref{31e,,urllib.parse.parse_qs()} and
@ref{31d,,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 Python 3 9 3 中顯著的變更,Python 3 9 5 中顯著的變更,Python 3 9 2 中顯著的變更,Python 3 9 有什麼新功能
@anchor{whatsnew/3 9 notable-changes-in-python-3-9-3}@anchor{b83}
@subsection Python 3.9.3 中顯著的變更


A security fix alters the @ref{aed,,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 Python 3 9 5 中顯著的變更,Python 3 9 14 中顯著的安全性功能,Python 3 9 3 中顯著的變更,Python 3 9 有什麼新功能
@anchor{whatsnew/3 9 notable-changes-in-python-3-9-5}@anchor{b84}
@subsection Python 3.9.5 中顯著的變更


@menu
* urllib.parse: urllib parse<3>. 

@end menu

@node urllib parse<3>,,,Python 3 9 5 中顯著的變更
@anchor{whatsnew/3 9 id5}@anchor{b85}
@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{110,,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 Python 3 9 14 中顯著的安全性功能,Python 3 9 17 中顯著的變更,Python 3 9 5 中顯著的變更,Python 3 9 有什麼新功能
@anchor{whatsnew/3 9 notable-security-feature-in-3-9-14}@anchor{b86}
@subsection Python 3.9.14 中顯著的安全性功能


Converting between @ref{19b,,int} and @ref{169,,str} in bases other than 2
(binary), 4, 8 (octal), 16 (hexadecimal), or 32 such as base 10 (decimal)
now raises a @ref{2eb,,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{df,,sys} APIs. See the @ref{804,,integer string conversion length limitation} documentation.  The default limit
is 4300 digits in string form.

@node Python 3 9 17 中顯著的變更,,Python 3 9 14 中顯著的安全性功能,Python 3 9 有什麼新功能
@anchor{whatsnew/3 9 notable-changes-in-3-9-17}@anchor{b87}
@subsection Python 3.9.17 中顯著的變更


@menu
* tarfile: tarfile<4>. 

@end menu

@node tarfile<4>,,,Python 3 9 17 中顯著的變更
@anchor{whatsnew/3 9 tarfile}@anchor{b88}
@subsubsection tarfile



@itemize *

@item 
The extraction methods in @ref{e4,,tarfile}, and @ref{68f,,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{690,,Extraction filters} for details.
In Python 3.12, use without the `filter' argument will show a
@ref{1a3,,DeprecationWarning}.
In Python 3.14, the default will switch to @code{'data'}.
(Contributed by Petr Viktorin in 
@geindex Python Enhancement Proposals; PEP 706
PEP 706@footnote{https://peps.python.org/pep-0706/}.)
@end itemize

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Python 3 8 有什麼新功能,Python 3 7 有什麼新功能,Python 3 9 有什麼新功能,Python 有什麼新功能？
@anchor{whatsnew/3 8 doc}@anchor{b89}@anchor{whatsnew/3 8 translation-repo}@anchor{b8a}@anchor{whatsnew/3 8 what-s-new-in-python-3-8}@anchor{b8b}
@section 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.

@*編輯者: 
Raymond Hettinger


本文介紹了 Python 3.8 與 3.7 相比多了哪些新功能。Python 3.8 已於 2019 年 10 月 14 日發布。有關完整詳細資訊，請參閱 @ref{142,,changelog}。

@c from datetime import date
@c from math import cos, radians
@c from unicodedata import normalize
@c import re
@c import math

@menu
* 發布重點摘要: 發布重點摘要<6>. 
* 新增功能: 新增功能<11>. 
* 其他語言更動: 其他語言更動<6>. 
* 新增模組: 新增模組<4>. 
* 改進的模組: 改進的模組<6>. 
* 最佳化: 最佳化<7>. 
* 建置和 C API 變更:: 
* 已棄用: 已棄用<9>. 
* API 與功能的移除:: 
* 移植至 Python 3.8: 移植至 Python 3 8. 
* Python 3.8.1 中顯著的變更: Python 3 8 1 中顯著的變更. 
* Python 3.8.2 中顯著的變更: Python 3 8 2 中顯著的變更. 
* Python 3.8.3 中顯著的變更: Python 3 8 3 中顯著的變更. 
* Python 3.8.8 中顯著的變更: Python 3 8 8 中顯著的變更. 
* Python 3.8.9 中顯著的變更: Python 3 8 9 中顯著的變更. 
* Python 3.8.10 中顯著的變更: Python 3 8 10 中顯著的變更. 
* Python 3.8.10 中顯著的變更: Python 3 8 10 中顯著的變更<2>. 
* Python 3.8.12 中顯著的變更: Python 3 8 12 中顯著的變更. 
* Python 3.8.14 中顯著的安全性功能: Python 3 8 14 中顯著的安全性功能. 
* Python 3.8.17 中顯著的變更: Python 3 8 17 中顯著的變更. 

@end menu

@node 發布重點摘要<6>,新增功能<11>,,Python 3 8 有什麼新功能
@anchor{whatsnew/3 8 summary-release-highlights}@anchor{b8c}
@subsection 發布重點摘要


@c This section singles out the most important changes in Python 3.8.
@c Brevity is key.

@c PEP-sized items next.

@node 新增功能<11>,其他語言更動<6>,發布重點摘要<6>,Python 3 8 有什麼新功能
@anchor{whatsnew/3 8 new-features}@anchor{b8d}
@subsection 新增功能


@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,,新增功能<11>
@anchor{whatsnew/3 8 assignment-expressions}@anchor{b8e}
@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{839,,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.

完整敘述請見 
@geindex Python Enhancement Proposals; PEP 572
PEP 572@footnote{https://peps.python.org/pep-0572/}。

（由 Emily Morehouse 在 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,新增功能<11>
@anchor{whatsnew/3 8 positional-only-parameters}@anchor{b8f}
@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 不得為關鍵字引數
f(10, 20, 30, 40, 50, f=60)           # e 必須為關鍵字引數
@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{b90,,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{839,,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{d7,,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 和 b 被用於兩種方式
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

完整敘述請見 
@geindex Python Enhancement Proposals; PEP 570
PEP 570@footnote{https://peps.python.org/pep-0570/}。

（由 Pablo Galindo 在 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,新增功能<11>
@anchor{whatsnew/3 8 parallel-filesystem-cache-for-compiled-bytecode-files}@anchor{b91}
@subsubsection Parallel filesystem cache for compiled bytecode files


The new 
@geindex PYTHONPYCACHEPREFIX
@geindex 環境變數; PYTHONPYCACHEPREFIX
@ref{b92,,PYTHONPYCACHEPREFIX} setting (also available as
@ref{16f,,-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{b93,,sys.pycache_prefix}
(@ref{87e,,None} indicates the default location in @code{__pycache__}
subdirectories).

（由 Carl Meyer 在 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,新增功能<11>
@anchor{whatsnew/3 8 debug-build-uses-the-same-abi-as-release-build}@anchor{b94}
@subsubsection Debug build uses the same ABI as release build


Python now uses the same ABI whether it's built in release or debug mode. On
Unix, when Python is built in debug mode, it is now possible to load C
extensions built in release mode and C extensions built using the stable ABI.

Release builds and @ref{504,,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{28e,,sys.getobjects()} function and the 
@geindex PYTHONDUMPREFS
@geindex 環境變數; PYTHONDUMPREFS
@ref{b95,,PYTHONDUMPREFS}
environment variable, can be set using the new @ref{62e,,./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,新增功能<11>
@anchor{whatsnew/3 8 bpo-36817-whatsnew}@anchor{b96}@anchor{whatsnew/3 8 f-strings-support-for-self-documenting-expressions-and-debugging}@anchor{b97}
@subsubsection f-strings support @code{=} for self-documenting expressions and debugging


Added an @code{=} specifier to @ref{663,,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
>>> user = 'eric_idle'
>>> member_since = date(1975, 7, 31)
>>> f'@{user=@} @{member_since=@}'
"user='eric_idle' member_since=datetime.date(1975, 7, 31)"
@end example

The usual @ref{19a,,f-string format specifiers} allow more
control over how the result of the expression is displayed:

@example
>>> delta = date.today() - member_since
>>> f'@{user=!s@}  @{delta.days=:,d@}'
'user=eric_idle  delta.days=16,075'
@end example

The @code{=} specifier will display the whole expression so that
calculations can be shown:

@example
>>> print(f'@{theta=@}  @{cos(radians(theta))=:.3f@}')
theta=30  cos(radians(theta))=0.866
@end example

（由 Eric V. Smith 和 Larry Hastings 在 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,新增功能<11>
@anchor{whatsnew/3 8 pep-578-python-runtime-audit-hooks}@anchor{b98}
@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.

完整細節請見 
@geindex Python Enhancement Proposals; PEP 578
PEP 578@footnote{https://peps.python.org/pep-0578/}。

@node PEP 587 Python Initialization Configuration,PEP 590 Vectorcall a fast calling protocol for CPython,PEP 578 Python Runtime Audit Hooks,新增功能<11>
@anchor{whatsnew/3 8 pep-587-python-initialization-configuration}@anchor{b99}
@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{3f4,,PyConfig}

@item 
@ref{b9a,,PyPreConfig}

@item 
@ref{b9b,,PyStatus}

@item 
@ref{b9c,,PyWideStringList}
@end itemize

New functions:


@itemize *

@item 
@ref{b9d,,PyConfig_Clear()}

@item 
@ref{b9e,,PyConfig_InitIsolatedConfig()}

@item 
@ref{b9f,,PyConfig_InitPythonConfig()}

@item 
@ref{98b,,PyConfig_Read()}

@item 
@ref{ba0,,PyConfig_SetArgv()}

@item 
@ref{ba1,,PyConfig_SetBytesArgv()}

@item 
@ref{ba2,,PyConfig_SetBytesString()}

@item 
@ref{ba3,,PyConfig_SetString()}

@item 
@ref{ba4,,PyPreConfig_InitIsolatedConfig()}

@item 
@ref{ba5,,PyPreConfig_InitPythonConfig()}

@item 
@ref{ba6,,PyStatus_Error()}

@item 
@ref{ba7,,PyStatus_Exception()}

@item 
@ref{ba8,,PyStatus_Exit()}

@item 
@ref{ba9,,PyStatus_IsError()}

@item 
@ref{baa,,PyStatus_IsExit()}

@item 
@ref{bab,,PyStatus_NoMemory()}

@item 
@ref{bac,,PyStatus_Ok()}

@item 
@ref{bad,,PyWideStringList_Append()}

@item 
@ref{bae,,PyWideStringList_Insert()}

@item 
@ref{baf,,Py_BytesMain()}

@item 
@ref{bb0,,Py_ExitStatusException()}

@item 
@ref{3f5,,Py_InitializeFromConfig()}

@item 
@ref{41c,,Py_PreInitialize()}

@item 
@ref{bb1,,Py_PreInitializeFromArgs()}

@item 
@ref{bb2,,Py_PreInitializeFromBytesArgs()}

@item 
@ref{bb3,,Py_RunMain()}
@end itemize

This PEP also adds @code{_PyRuntimeState.preconfig} (@ref{b9a,,PyPreConfig} type)
and @code{PyInterpreterState.config} (@ref{3f4,,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{63e,,Python Initialization Configuration} for the
documentation.

完整敘述請見 
@geindex Python Enhancement Proposals; PEP 587
PEP 587@footnote{https://peps.python.org/pep-0587/}。

（由 Victor Stinner 在 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,新增功能<11>
@anchor{whatsnew/3 8 pep-590-vectorcall-a-fast-calling-protocol-for-cpython}@anchor{bb4}
@subsubsection PEP 590: Vectorcall: a fast calling protocol for CPython


@ref{76d,,Vectorcall 協定} is added to the Python/C API.
It is meant to formalize existing optimizations which were already done
for various classes.
Any @ref{97b,,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.

完整敘述請見 
@geindex Python Enhancement Proposals; PEP 590
PEP 590@footnote{https://peps.python.org/pep-0590/}。

（由 Jeroen Demeyer、Mark Shannon 和 Petr Viktorin 在 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,新增功能<11>
@anchor{whatsnew/3 8 pickle-protocol-5-with-out-of-band-data-buffers}@anchor{bb5}
@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.

完整敘述請見 
@geindex Python Enhancement Proposals; PEP 574
PEP 574@footnote{https://peps.python.org/pep-0574/}。

（由 Antoine Pitrou 在 bpo-36785@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36785} 中貢獻。）

@node 其他語言更動<6>,新增模組<4>,新增功能<11>,Python 3 8 有什麼新功能
@anchor{whatsnew/3 8 other-language-changes}@anchor{bb6}
@subsection 其他語言更動



@itemize *

@item 
A @ref{180,,continue} statement was illegal in the @ref{1b0,,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{3c1,,bool}, @ref{19b,,int}, and @ref{213,,fractions.Fraction} types
now have an @ref{bb7,,as_integer_ratio()} method like that found in
@ref{196,,float} and @ref{1fe,,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{19b,,int}, @ref{196,,float} and @ref{197,,complex} will now
use the @ref{19e,,__index__()} special method, if available and the
corresponding method @ref{19d,,__int__()}, @ref{bb8,,__float__()}
or @ref{7f8,,__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{be,,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

（由 Jonathan Eunice 和 Serhiy Storchaka 在 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{a5e,,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{bb9,,yield} and
@ref{1af,,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

（由 David Cuthbert 和 Jordan Chapman 在 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{1ae,,SyntaxWarning} with a helpful suggestion.
This improves on just having a @ref{198,,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{1fa,,datetime.date} or
@ref{4dd,,datetime.datetime} and @ref{bba,,datetime.timedelta} objects now return
an instance of the subclass, rather than the base class. This also affects
the return type of operations whose implementation (directly or indirectly)
uses @ref{bba,,datetime.timedelta} arithmetic, such as
@ref{bbb,,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{bbc,,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{32e,,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{8d9,,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

（由 Victor Stinner 在 bpo-37032@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37032} 中貢獻。）

@item 
For integers, the three-argument form of the @ref{1a4,,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

（由 Mark Dickinson 在 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

（由 Jörn Heissler 在 bpo-35224@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35224} 中貢獻。）

@item 
The @ref{bbd,,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{bbe,,__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 新增模組<4>,改進的模組<6>,其他語言更動<6>,Python 3 8 有什麼新功能
@anchor{whatsnew/3 8 new-modules}@anchor{bbf}
@subsection 新增模組



@itemize *

@item 
The new @ref{7e,,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

（由 Barry Warsaw 和 Jason R. Coombs 在 bpo-34632@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34632} 中貢獻。）
@end itemize

@node 改進的模組<6>,最佳化<7>,新增模組<4>,Python 3 8 有什麼新功能
@anchor{whatsnew/3 8 improved-modules}@anchor{bc0}
@subsection 改進的模組


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

@end menu

@node ast<5>,asyncio<9>,,改進的模組<6>
@anchor{whatsnew/3 8 ast}@anchor{bc1}
@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{bc2,,ast.get_source_segment()} returns the source code
for a specific AST node.

（由 Ivan Levkivskyi 在 bpo-33416@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33416} 中貢獻。）

@ref{1c2,,ast.parse()} 函式有一些新旗標：


@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{933,,async} and @ref{18d,,await} as non-reserved words.
@end itemize

（由 Guido van Rossum 在 bpo-35766@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35766} 中貢獻。）

@node asyncio<9>,builtins（內建）,ast<5>,改進的模組<6>
@anchor{whatsnew/3 8 asyncio}@anchor{bc3}
@subsubsection asyncio


@ref{2f2,,asyncio.run()} has graduated from the provisional to stable API. This
function can be used to execute a @ref{6b2,,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

這`大致'等價於：

@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{2f2,,asyncio.run()} should be the preferred way of running asyncio programs.

（由 Yury Selivanov 在 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{18d,,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

（由 Yury Selivanov 在 bpo-37028@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37028} 中貢獻。）

The exception @ref{4cf,,asyncio.CancelledError} now inherits from
@ref{7d0,,BaseException} rather than @ref{bc4,,Exception} and no longer inherits
from @ref{bc5,,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{816,,ProactorEventLoop}.
(Contributed by Victor Stinner in bpo-34687@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34687}.)

@ref{816,,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{816,,ProactorEventLoop} can now be interrupted by
@ref{bbc,,KeyboardInterrupt} ("CTRL+C").
(Contributed by Vladimir Matveev in bpo-23057@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23057}.)

Added @ref{bc6,,asyncio.Task.get_coro()} for getting the wrapped coroutine
within an @ref{1c7,,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{1c9,,asyncio.create_task()} or
the @ref{1ca,,create_task()} event loop method, or by
calling the @ref{bc7,,set_name()} method on the task object. The
task name is visible in the @code{repr()} output of @ref{1c7,,asyncio.Task} and
can also be retrieved using the @ref{bc8,,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{811,,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（內建）,collections,asyncio<9>,改進的模組<6>
@anchor{whatsnew/3 8 builtins}@anchor{bc9}
@subsubsection builtins（內建）


The @ref{4ac,,compile()} built-in has been improved to accept the
@code{ast.PyCF_ALLOW_TOP_LEVEL_AWAIT} flag. With this new flag passed,
@ref{4ac,,compile()} will allow top-level @code{await}, @code{async for} and @code{async with}
constructs that are usually considered invalid syntax. Asynchronous code object
marked with the @code{CO_COROUTINE} flag may then be returned.
(Contributed by Matthias Bussonnier in bpo-34616@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34616})

@node collections,cProfile,builtins（內建）,改進的模組<6>
@anchor{whatsnew/3 8 collections}@anchor{bca}
@subsubsection collections


The @ref{bcb,,_asdict()} method for
@ref{4db,,collections.namedtuple()} now returns a @ref{183,,dict} instead of a
@ref{7ec,,collections.OrderedDict}. This works because regular dicts have
guaranteed ordering since Python 3.7. If the extra features of
@code{OrderedDict} are required, the suggested remediation is to cast the
result to the desired type: @code{OrderedDict(nt._asdict())}.
(Contributed by Raymond Hettinger in bpo-35864@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35864}.)

@node cProfile,csv<2>,collections,改進的模組<6>
@anchor{whatsnew/3 8 cprofile}@anchor{bcc}
@subsubsection cProfile


The @ref{bcd,,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

（由 Scott Sanderson 在 bpo-29235@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29235} 中貢獻。）

@node csv<2>,curses<4>,cProfile,改進的模組<6>
@anchor{whatsnew/3 8 csv}@anchor{bce}
@subsubsection csv


The @ref{bcf,,csv.DictReader} now returns instances of @ref{183,,dict} instead of
a @ref{7ec,,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<3>,csv<2>,改進的模組<6>
@anchor{whatsnew/3 8 curses}@anchor{bd0}
@subsubsection curses


Added a new variable holding structured version information for the
underlying ncurses library: @ref{bd1,,ncurses_version}.
(Contributed by Serhiy Storchaka in bpo-31680@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31680}.)

@node ctypes<3>,datetime<4>,curses<4>,改進的模組<6>
@anchor{whatsnew/3 8 ctypes}@anchor{bd2}
@subsubsection ctypes


On Windows, @ref{bd3,,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{bd4,,add_dll_directory()}.
(Contributed by Steve Dower in bpo-36085@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36085}.)

@node datetime<4>,functools<3>,ctypes<3>,改進的模組<6>
@anchor{whatsnew/3 8 datetime}@anchor{bd5}
@subsubsection datetime


Added new alternate constructors @ref{bd6,,datetime.date.fromisocalendar()} and
@ref{bd7,,datetime.datetime.fromisocalendar()}, which construct @ref{1fa,,date} and
@ref{4dd,,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<3>,gc<4>,datetime<4>,改進的模組<6>
@anchor{whatsnew/3 8 functools}@anchor{bd8}
@subsubsection functools


@ref{bd9,,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

（由 Raymond Hettinger 在 bpo-36772@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36772} 中貢獻。）

Added a new @ref{75c,,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

（由 Carl Meyer 在 bpo-21145@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21145} 中貢獻）

Added a new @ref{bda,,functools.singledispatchmethod()} decorator that converts
methods into @ref{bdb,,generic functions} using
@ref{bdc,,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

（由 Ethan Smith 在 bpo-32380@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32380} 中貢獻）

@node gc<4>,gettext,functools<3>,改進的模組<6>
@anchor{whatsnew/3 8 gc}@anchor{bdd}
@subsubsection gc


@ref{9fd,,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<4>,改進的模組<6>
@anchor{whatsnew/3 8 gettext}@anchor{bde}
@subsubsection gettext


Added @ref{bdf,,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 和 idlelib<4>,gettext,改進的模組<6>
@anchor{whatsnew/3 8 gzip}@anchor{be0}
@subsubsection gzip


Added the `mtime' parameter to @ref{847,,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{be1,,BadGzipFile} exception is now raised instead of @ref{2c0,,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 和 idlelib<4>,inspect<6>,gzip<3>,改進的模組<6>
@anchor{whatsnew/3 8 idle-and-idlelib}@anchor{be2}
@subsubsection IDLE 和 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<6>,io<5>,IDLE 和 idlelib<4>,改進的模組<6>
@anchor{whatsnew/3 8 inspect}@anchor{be3}
@subsubsection inspect


The @ref{be4,,inspect.getdoc()} function can now find docstrings for @code{__slots__}
if that attribute is a @ref{183,,dict} where the values are docstrings.
This provides documentation options similar to what we already have
for @ref{4ae,,property()}, @ref{489,,classmethod()}, and @ref{451,,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

（由 Raymond Hettinger 在 bpo-36326@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36326} 中貢獻。）

@node io<5>,itertools<5>,inspect<6>,改進的模組<6>
@anchor{whatsnew/3 8 io}@anchor{be5}
@subsubsection io


In development mode (@ref{16f,,-X} @code{env}) and in @ref{504,,debug build}, the
@ref{500,,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>,改進的模組<6>
@anchor{whatsnew/3 8 itertools}@anchor{be6}
@subsubsection itertools


The @ref{be7,,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

（由 Lisa Roach 在 bpo-34659@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34659} 中貢獻。）

@node json tool,logging<2>,itertools<5>,改進的模組<6>
@anchor{whatsnew/3 8 json-tool}@anchor{be8}
@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<6>,json tool,改進的模組<6>
@anchor{whatsnew/3 8 logging}@anchor{be9}
@subsubsection logging


Added a `force' keyword argument to @ref{bea,,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<6>,mmap<2>,logging<2>,改進的模組<6>
@anchor{whatsnew/3 8 math}@anchor{beb}
@subsubsection math


Added new function @ref{bec,,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{bed,,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{bee,,math.prod()}, as analogous function to @ref{68e,,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

（由 Pablo Galindo 在 bpo-35606@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35606} 中貢獻。）

Added two new combinatoric functions @ref{8d8,,math.perm()} and @ref{8d7,,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

（由 Yash Aggarwal、Keller Fuchs、Serhiy Storchaka 和 Raymond Hettinger 在 bpo-37128@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37128}、bpo-37178@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37178} 和 bpo-35431@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35431} 中貢獻。）

Added a new function @ref{bef,,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{bf0,,math.sqrt()}:

@example
>>> r = 650320427
>>> s = r ** 2
>>> isqrt(s - 1)         # 正確
650320426
>>> floor(sqrt(s - 1))   # 錯誤
650320427
@end example

（由 Mark Dickinson 在 bpo-36887@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36887} 中貢獻。）

The function @ref{b38,,math.factorial()} no longer accepts arguments that are not
int-like. (Contributed by Pablo Galindo in bpo-33083@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33083}.)

@node mmap<2>,multiprocessing<4>,math<6>,改進的模組<6>
@anchor{whatsnew/3 8 mmap}@anchor{bf1}
@subsubsection mmap


The @ref{514,,mmap.mmap} class now has an @ref{bf2,,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<7>,mmap<2>,改進的模組<6>
@anchor{whatsnew/3 8 multiprocessing}@anchor{bf3}
@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<7>,os path<5>,multiprocessing<4>,改進的模組<6>
@anchor{whatsnew/3 8 os}@anchor{bf4}
@subsubsection os


Added new function @ref{bd4,,add_dll_directory()} on Windows for providing
additional search paths for native dependencies when importing extension
modules or loading DLLs using @ref{2e,,ctypes}.
(Contributed by Steve Dower in bpo-36085@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36085}.)

A new @ref{bf5,,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{26d,,os.stat()} will now traverse anything supported by the
operating system, while @ref{6c1,,os.lstat()} will only open reparse points that
identify as "name surrogates" while others are opened as for @ref{26d,,os.stat()}.
In all cases, @ref{bf6,,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{bf7,,os.stat_result.st_reparse_tag} attribute.

On Windows, @ref{b11,,os.readlink()} is now able to read directory junctions. Note
that @ref{bf8,,islink()} will return @code{False} for directory junctions,
and so code that checks @code{islink} first will continue to treat junctions as
directories, while code that handles errors from @ref{b11,,os.readlink()} may now
treat junctions as links.

（由 Steve Dower 在 bpo-37834@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37834} 中貢獻。）

@node os path<5>,pathlib<10>,os<7>,改進的模組<6>
@anchor{whatsnew/3 8 os-path}@anchor{bf9}
@subsubsection os.path


@ref{a6,,os.path} functions that return a boolean result like
@ref{bfa,,exists()}, @ref{bfb,,lexists()}, @ref{bfc,,isdir()},
@ref{bfd,,isfile()}, @ref{bf8,,islink()}, and @ref{bfe,,ismount()}
now return @code{False} instead of raising @ref{2eb,,ValueError} or its subclasses
@ref{880,,UnicodeEncodeError} and @ref{bff,,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{c00,,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{bfc,,isdir()} on Windows no longer returns @code{True} for a link to a
non-existent directory.

@ref{262,,realpath()} on Windows now resolves reparse points, including
symlinks and directory junctions.

（由 Steve Dower 在 bpo-37834@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37834} 中貢獻。）

@node pathlib<10>,pickle<2>,os path<5>,改進的模組<6>
@anchor{whatsnew/3 8 pathlib}@anchor{c01}
@subsubsection pathlib


@ref{266,,pathlib.Path} methods that return a boolean result like
@ref{c02,,exists()}, @ref{535,,is_dir()},
@ref{534,,is_file()}, @ref{c03,,is_mount()},
@ref{c04,,is_symlink()}, @ref{c05,,is_block_device()},
@ref{c06,,is_char_device()}, @ref{c07,,is_fifo()},
@ref{c08,,is_socket()} now return @code{False} instead of raising
@ref{2eb,,ValueError} or its subclass @ref{880,,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<2>,plistlib,pathlib<10>,改進的模組<6>
@anchor{whatsnew/3 8 pickle}@anchor{c09}
@subsubsection pickle


@ref{ab,,pickle} extensions subclassing the C-optimized @ref{c0a,,Pickler}
can now override the pickling logic of functions and classes by defining the
special @ref{c0b,,reducer_override()} method.
(Contributed by Pierre Glaser and Olivier Grisel in bpo-35900@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35900}.)

@node plistlib,pprint<3>,pickle<2>,改進的模組<6>
@anchor{whatsnew/3 8 plistlib}@anchor{c0c}
@subsubsection plistlib


Added new @ref{c0d,,plistlib.UID} and enabled support for reading and writing
NSKeyedArchiver-encoded binary plists.
(Contributed by Jon Janzen in bpo-26707@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26707}.)

@node pprint<3>,py_compile<2>,plistlib,改進的模組<6>
@anchor{whatsnew/3 8 pprint}@anchor{c0e}
@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{c0f,,pprint.pp()} that is
like @ref{a22,,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)                  # 原本的順序
@{'source': 'input.txt',
 'operation': 'filter',
 'destination': 'output.txt'@}
>>> pprint(d, width=40)              # 以字母順序排序鍵
@{'destination': 'output.txt',
 'operation': 'filter',
 'source': 'input.txt'@}
@end example

（由 Rémi Lapeyre 在 bpo-30670@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30670} 中貢獻。）

@node py_compile<2>,shlex,pprint<3>,改進的模組<6>
@anchor{whatsnew/3 8 py-compile}@anchor{c10}
@subsubsection py_compile


@ref{c11,,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>,改進的模組<6>
@anchor{whatsnew/3 8 shlex}@anchor{c12}
@subsubsection shlex


The new @ref{c13,,shlex.join()} function acts as the inverse of @ref{757,,shlex.split()}.
(Contributed by Bo Bayles in bpo-32102@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32102}.)

@node shutil<4>,socket<5>,shlex,改進的模組<6>
@anchor{whatsnew/3 8 shutil}@anchor{c14}
@subsubsection shutil


@ref{c15,,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{6d3,,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{e4,,tarfile} module.
(Contributed by C.A.M. Gerlach in bpo-30661@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30661}.)

@ref{354,,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<5>,ssl<5>,shutil<4>,改進的模組<6>
@anchor{whatsnew/3 8 socket}@anchor{c16}
@subsubsection socket


Added @ref{c17,,create_server()} and @ref{c18,,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{c19,,socket.if_nameindex()}, @ref{c1a,,socket.if_nametoindex()}, and
@ref{c1b,,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<5>,statistics<4>,socket<5>,改進的模組<6>
@anchor{whatsnew/3 8 ssl}@anchor{c1c}
@subsubsection ssl


Added @ref{c1d,,post_handshake_auth} to enable and
@ref{c1e,,verify_client_post_handshake()} to initiate TLS 1.3
post-handshake authentication.
(Contributed by Christian Heimes in bpo-34670@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34670}.)

@node statistics<4>,sys<7>,ssl<5>,改進的模組<6>
@anchor{whatsnew/3 8 statistics}@anchor{c1f}
@subsubsection statistics


Added @ref{c20,,statistics.fmean()} as a faster, floating-point variant of
@ref{8d9,,statistics.mean()}.  (Contributed by Raymond Hettinger and
Steven D'Aprano in bpo-35904@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35904}.)

新增 @ref{c21,,statistics.geometric_mean()}（由 Raymond Hettinger 在 bpo-27181@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27181} 中貢獻。）

Added @ref{c22,,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{c23,,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{c24,,statistics.NormalDist}, a tool for creating
and manipulating normal distributions of a random variable.
(Contributed by Raymond Hettinger in bpo-36018@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36018}.)

@example
>>> temperature_feb = NormalDist.from_samples([4, 12, -3, 2, 7, 14])
>>> temperature_feb.mean
6.0
>>> temperature_feb.stdev
6.356099432828281

>>> temperature_feb.cdf(3)            # Chance of being under 3 degrees
0.3184678262814532
>>> # Relative chance of being 7 degrees versus 10 degrees
>>> temperature_feb.pdf(7) / temperature_feb.pdf(10)
1.2039930378537762

>>> el_niño = NormalDist(4, 2.5)
>>> temperature_feb += el_niño        # Add in a climate effect
>>> temperature_feb
NormalDist(mu=10.0, sigma=6.830080526611674)

>>> temperature_feb * (9/5) + 32      # Convert to Fahrenheit
NormalDist(mu=50.0, sigma=12.294144947901014)
>>> temperature_feb.samples(3)        # Generate random samples
[7.672102882379219, 12.000027119750287, 4.647488369766392]
@end example

@node sys<7>,tarfile<5>,statistics<4>,改進的模組<6>
@anchor{whatsnew/3 8 sys}@anchor{c25}
@subsubsection sys


Add new @ref{502,,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{1b3,,gc.collect()}).
(Contributed by Victor Stinner in bpo-36829@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36829}.)

@node tarfile<5>,threading<5>,sys<7>,改進的模組<6>
@anchor{whatsnew/3 8 tarfile}@anchor{c26}
@subsubsection tarfile


The @ref{e4,,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<5>,tokenize<2>,tarfile<5>,改進的模組<6>
@anchor{whatsnew/3 8 threading}@anchor{c27}
@subsubsection threading


Add a new @ref{a44,,threading.excepthook()} function which handles uncaught
@ref{c28,,threading.Thread.run()} exception. It can be overridden to control how
uncaught @ref{c28,,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{c29,,threading.get_native_id()} function and
a @ref{c2a,,native_id}
attribute to the @ref{176,,threading.Thread} class. These return the native
integral Thread ID of the current thread assigned by the kernel.
This feature is only available on certain platforms, see
@ref{c29,,get_native_id} for more information.
(Contributed by Jake Tesler in bpo-36084@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36084}.)

@node tokenize<2>,tkinter<5>,threading<5>,改進的模組<6>
@anchor{whatsnew/3 8 tokenize}@anchor{c2b}
@subsubsection tokenize


The @ref{101,,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<5>,time<4>,tokenize<2>,改進的模組<6>
@anchor{whatsnew/3 8 tkinter}@anchor{c2c}
@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<9>,tkinter<5>,改進的模組<6>
@anchor{whatsnew/3 8 time}@anchor{c2d}
@subsubsection time


Added new clock @ref{c2e,,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<9>,unicodedata<6>,time<4>,改進的模組<6>
@anchor{whatsnew/3 8 typing}@anchor{c2f}
@subsubsection typing


The @ref{10a,,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{331,,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{a4e,,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{568,,typing.Final} and @ref{8b4,,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{565,,typing.Protocol} and
@ref{66d,,typing.runtime_checkable()}.  Simple ABCs like
@ref{c30,,typing.SupportsInt} are now @code{Protocol} subclasses.

@item 
新的協定類別 @ref{c31,,typing.SupportsIndex}。

@item 
新的函式 @ref{2ab,,typing.get_origin()} 和 @ref{2ac,,typing.get_args()}。
@end itemize

@node unicodedata<6>,unittest<7>,typing<9>,改進的模組<6>
@anchor{whatsnew/3 8 unicodedata}@anchor{c32}
@subsubsection unicodedata


The @ref{10b,,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{c33,,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<7>,venv<4>,unicodedata<6>,改進的模組<6>
@anchor{whatsnew/3 8 unittest}@anchor{c34}
@subsubsection unittest


Added @ref{c35,,AsyncMock} to support an asynchronous version of
@ref{c36,,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{c37,,addModuleCleanup()} and
@ref{c38,,addClassCleanup()} to unittest to support
cleanups for @ref{c39,,setUpModule()} and
@ref{c3a,,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{10c,,unittest} module gained support for coroutines to be used as test cases
with @ref{35f,,unittest.IsolatedAsyncioTestCase}.
(Contributed by Andrew Svetlov in bpo-32972@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32972}.)

範例：

@example
import unittest


class TestRequest(unittest.IsolatedAsyncioTestCase):

    async def asyncSetUp(self):
        self.connection = await AsyncConnection()

    async def test_get(self):
        response = await self.connection.get("https://example.com")
        self.assertEqual(response.status_code, 200)

    async def asyncTearDown(self):
        await self.connection.close()


if __name__ == "__main__":
    unittest.main()
@end example

@node venv<4>,weakref,unittest<7>,改進的模組<6>
@anchor{whatsnew/3 8 venv}@anchor{c3b}
@subsubsection venv


@ref{117,,venv} now includes an @code{Activate.ps1} script on all platforms for
activating virtual environments under PowerShell Core 6.1.
(Contributed by Brett Cannon in bpo-32718@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32718}.)

@node weakref,xml<4>,venv<4>,改進的模組<6>
@anchor{whatsnew/3 8 weakref}@anchor{c3c}
@subsubsection weakref


The proxy objects returned by @ref{c3d,,weakref.proxy()} now support the matrix
multiplication operators @code{@@} and @code{@@=} in addition to the other
numeric operators. (Contributed by Mark Dickinson in bpo-36669@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36669}.)

@node xml<4>,xmlrpc,weakref,改進的模組<6>
@anchor{whatsnew/3 8 xml}@anchor{c3e}
@subsubsection xml


As mitigation against DTD and external entity retrieval, the
@ref{128,,xml.dom.minidom} and @ref{12f,,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{12b,,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{12b,,xml.etree.ElementTree} module provides a new function
@ref{c3f,,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{c40,,xml.etree.ElementTree.XMLParser} can
receive namespace declaration events through the new callback methods
@code{start_ns()} and @code{end_ns()}.  Additionally, the
@ref{c41,,xml.etree.ElementTree.TreeBuilder} target can be configured
to process events about comments and processing instructions to include
them in the generated tree.
(Contributed by Stefan Behnel in bpo-36676@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36676} and bpo-36673@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36673}.)

@node xmlrpc,,xml<4>,改進的模組<6>
@anchor{whatsnew/3 8 xmlrpc}@anchor{c42}
@subsubsection xmlrpc


@ref{c43,,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 最佳化<7>,建置和 C API 變更,改進的模組<6>,Python 3 8 有什麼新功能
@anchor{whatsnew/3 8 optimizations}@anchor{c44}
@subsection 最佳化



@itemize *

@item 
The @ref{dc,,subprocess} module can now use the @ref{529,,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

（由 Joannah Nanjekye 和 Victor Stinner 在 bpo-35537@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35537} 中貢獻。）

@item 
@ref{c45,,shutil.copyfile()}, @ref{c46,,shutil.copy()}, @ref{c47,,shutil.copy2()},
@ref{c15,,shutil.copytree()} and @ref{c48,,shutil.move()} use platform-specific
"fast-copy" syscalls on Linux and macOS in order to copy the file
more efficiently.
"fast-copy" means that the copying operation occurs within the kernel,
avoiding the use of userspace buffers in Python as in
"@code{outfd.write(infd.read())}".
On Windows @ref{c45,,shutil.copyfile()} uses a bigger default buffer size (1 MiB
instead of 16 KiB) and a @ref{165,,memoryview()}-based variant of
@ref{c49,,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{c4a,,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{c15,,shutil.copytree()} uses @ref{c4b,,os.scandir()} function and all copy
functions depending from it use cached @ref{26d,,os.stat()} values. The speedup
for copying a directory with 8000 files is around +9% on Linux, +20% on
Windows and +30% on a Windows SMB share. Also the number of @ref{26d,,os.stat()}
syscalls is reduced by 38% making @ref{c15,,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{c4c,,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{c4d,,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{c4e,,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{4db,,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{24d,,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 建置和 C API 變更,已棄用<9>,最佳化<7>,Python 3 8 有什麼新功能
@anchor{whatsnew/3 8 build-and-c-api-changes}@anchor{c4f}
@subsection 建置和 C API 變更



@itemize *

@item 
Default @ref{c50,,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

（由 Victor Stinner 在 bpo-35134@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35134} 和 bpo-35081@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35081} 中貢獻，該工作由 Eric Snow 在 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{788,,Py_INCREF()}, @ref{789,,Py_DECREF()}

@item 
@ref{c51,,Py_XINCREF()}, @ref{98a,,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

（由 Victor Stinner 在 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{c52,,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.

（由 Antoine Pitrou 在 bpo-32430@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32430} 中貢獻。）

@item 
Functions that convert Python number to C integer like
@ref{5fd,,PyLong_AsLong()} and argument parsing functions like
@ref{3bf,,PyArg_ParseTuple()} with integer converting format units like @code{'i'}
will now use the @ref{19e,,__index__()} special method instead of
@ref{19d,,__int__()}, if available.  The deprecation warning will be
emitted for objects with the @code{__int__()} method but without the
@code{__index__()} method (like @ref{1fe,,Decimal} and
@ref{213,,Fraction}).  @ref{c53,,PyNumber_Check()} will now return
@code{1} for objects implementing @code{__index__()}.
@ref{c54,,PyNumber_Long()}, @ref{c55,,PyNumber_Float()} and
@ref{c56,,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{c57,,PyObject_Init()} (and its parallel macro @code{PyObject_INIT})
instead of in @ref{c58,,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{3eb,,sys.executable} to the program full
path (@ref{3ea,,Py_GetProgramFullPath()}) rather than to the program name
(@ref{3ec,,Py_GetProgramName()}).
(Contributed by Victor Stinner in bpo-38234@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38234}.)
@end itemize

@node 已棄用<9>,API 與功能的移除,建置和 C API 變更,Python 3 8 有什麼新功能
@anchor{whatsnew/3 8 deprecated}@anchor{c59}
@subsection 已棄用



@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{12b,,ElementTree} module now emit a
@ref{1a3,,DeprecationWarning} instead of @ref{abd,,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{941,,concurrent.futures.ThreadPoolExecutor} to
@ref{942,,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{582,,__getitem__()} methods of @ref{936,,xml.dom.pulldom.DOMEventStream},
@ref{937,,wsgiref.util.FileWrapper} and @ref{938,,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{330,,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{2ee,,Constant} should be used instead.
(Contributed by Serhiy Storchaka in bpo-32892@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32892}.)

@item 
@ref{2ef,,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{c5a,,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{932,,decorator} is deprecated and will be
removed in version 3.10.  Instead of @code{@@asyncio.coroutine}, use
@ref{7e6,,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{c5b,,asyncio.sleep()}, @ref{80c,,asyncio.gather()}, @ref{c5c,,asyncio.shield()},
@ref{80e,,asyncio.wait_for()}, @ref{6a0,,asyncio.wait()}, @ref{4c1,,asyncio.as_completed()},
@ref{1c7,,asyncio.Task}, @ref{c5d,,asyncio.Lock}, @ref{2f3,,asyncio.Event},
@ref{c5e,,asyncio.Condition}, @ref{c5f,,asyncio.Semaphore},
@ref{c60,,asyncio.BoundedSemaphore}, @ref{c61,,asyncio.Queue},
@ref{c62,,asyncio.create_subprocess_exec()}, and
@ref{c63,,asyncio.create_subprocess_shell()}.

@item 
The explicit passing of coroutine objects to @ref{6a0,,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{67,,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{c64,,translation()} and
@ref{c65,,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{176,,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{1fe,,Decimal}s,
@ref{213,,Fraction}s and any other objects that can be converted
to integers only with a loss (e.g. that have the @ref{19d,,__int__()}
method but do not have the @ref{19e,,__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{218,,functools.partialmethod()}, @ref{c66,,weakref.finalize()},
@ref{c67,,profile.Profile.runcall()}, @code{cProfile.Profile.runcall()},
@ref{c68,,bdb.Bdb.runcall()}, @ref{c69,,trace.Trace.runfunc()} and
@ref{c6a,,curses.wrapper()}.

@item 
`function' in @ref{c6b,,unittest.TestCase.addCleanup()}.

@item 
`fn' in the @ref{c6c,,submit()} method of
@ref{941,,concurrent.futures.ThreadPoolExecutor} and
@ref{1d6,,concurrent.futures.ProcessPoolExecutor}.

@item 
`callback' in @ref{c6d,,contextlib.ExitStack.callback()},
@code{contextlib.AsyncExitStack.callback()} and
@ref{c6e,,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{c66,,weakref.finalize()}.
@end itemize

In future releases of Python, they will be @ref{c6f,,positional-only}.
(Contributed by Serhiy Storchaka in bpo-36492@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36492}.)
@end itemize

@node API 與功能的移除,移植至 Python 3 8,已棄用<9>,Python 3 8 有什麼新功能
@anchor{whatsnew/3 8 api-and-feature-removals}@anchor{c70}
@subsection API 與功能的移除


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{319,,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{c71,,time.perf_counter()} or
@ref{c72,,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{e4,,tarfile} module.
It is not documented and deprecated since Python 3.3.

@item 
The @ref{c40,,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{59f,,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{c40,,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{d4,,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{9f9,,fileinput.input()} and
@ref{938,,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 移植至 Python 3 8,Python 3 8 1 中顯著的變更,API 與功能的移除,Python 3 8 有什麼新功能
@anchor{whatsnew/3 8 porting-to-python-3-8}@anchor{c73}
@subsection 移植至 Python 3.8


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

@menu
* Python 行為的改變:: 
* Python API 的變更: Python API 的變更<6>. 
* C API 中的改動: C API 中的改動<5>. 
* CPython 位元組碼變更: CPython 位元組碼變更<7>. 
* Demos and Tools: Demos and Tools<2>. 

@end menu

@node Python 行為的改變,Python API 的變更<6>,,移植至 Python 3 8
@anchor{whatsnew/3 8 changes-in-python-behavior}@anchor{c74}
@subsubsection Python 行為的改變



@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{1ae,,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{3c1,,bool},
@ref{19b,,int}, @ref{196,,float}, @ref{197,,complex} and few classes from
the standard library.  They now inherit @code{__str__()} from @ref{c75,,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{291,,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{640,,PyEval_RestoreThread()},
@ref{c76,,Py_END_ALLOW_THREADS()}, and @ref{642,,PyGILState_Ensure()}. If this
behavior is not desired, guard the call by checking @code{_Py_IsFinalizing()}
or @ref{c77,,sys.is_finalizing()}.
(Contributed by Joannah Nanjekye in bpo-36475@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36475}.)
@end itemize

@node Python API 的變更<6>,C API 中的改動<5>,Python 行為的改變,移植至 Python 3 8
@anchor{whatsnew/3 8 changes-in-the-python-api}@anchor{c78}
@subsubsection Python API 的變更



@itemize *

@item 
The @ref{c79,,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{4b2,,subprocess.Popen} can now use @ref{529,,os.posix_spawn()} in some cases
for better performance. On Windows Subsystem for Linux and QEMU User
Emulation, the @ref{4b2,,Popen} constructor using
@ref{529,,os.posix_spawn()} no longer raises an exception on errors like
"missing program".  Instead the child process fails with a
non-zero @ref{c7a,,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{4b2,,subprocess.Popen} is no longer
compatible with subinterpreters. The use of the parameter in a
subinterpreter now raises @ref{244,,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{c7b,,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{319,,os.popen()} instead.
(Contributed by Victor Stinner in bpo-35345@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35345}.)

@item 
The @ref{c7c,,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{c7d,,selection()} method of the
@ref{c7e,,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{c7f,,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{c80,,writexml()}, @ref{c81,,toxml()}
and @ref{c82,,toprettyxml()} methods of
@ref{128,,xml.dom.minidom} and the @ref{c83,,write()}
method of @ref{12b,,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{36,,dbm.dumb} database opened with flags @code{'r'} is now read-only.
@ref{c84,,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{c40,,XMLParser} will no longer be called and will
emit a @ref{4d2,,RuntimeWarning} instead of a @ref{1a3,,DeprecationWarning}.
Define the @ref{c85,,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{244,,RuntimeError} is now raised when the custom metaclass doesn't
provide the @code{__classcell__} entry in the namespace passed to
@code{type.__new__}.  A @ref{1a3,,DeprecationWarning} was emitted in Python
3.6--3.7.  (Contributed by Serhiy Storchaka in bpo-23722@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23722}.)

@item 
The @ref{bcd,,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{c45,,shutil.copyfile()}, @ref{c46,,shutil.copy()}, @ref{c47,,shutil.copy2()},
@ref{c15,,shutil.copytree()} and @ref{c48,,shutil.move()} use platform-specific
"fast-copy" syscalls (see
@ref{c4a,,Platform-dependent efficient copy operations} section).

@item 
@ref{c45,,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{ab1,,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{c86,,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{128,,xml.dom.minidom} and @ref{12f,,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{35,,dbm} database (@ref{36,,dbm.dumb},
@ref{37,,dbm.gnu} or @ref{38,,dbm.ndbm}) raises @code{error} (@ref{c87,,dbm.dumb.error},
@ref{c88,,dbm.gnu.error} or @ref{c89,,dbm.ndbm.error}) instead of @ref{5df,,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{2ee,,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{c00,,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{4cf,,asyncio.CancelledError} now inherits from
@ref{7d0,,BaseException} rather than @ref{bc4,,Exception} and no longer inherits
from @ref{bc5,,concurrent.futures.CancelledError}.
(Contributed by Yury Selivanov in bpo-32528@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32528}.)

@item 
The function @ref{80e,,asyncio.wait_for()} now correctly waits for cancellation
when using an instance of @ref{1c7,,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{c8a,,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{c8b,,asyncio.BufferedProtocol} has graduated to the stable API.
@end itemize
@anchor{whatsnew/3 8 bpo-36085-whatsnew}@anchor{c8c}

@itemize *

@item 
DLL dependencies for extension modules and DLLs loaded with @ref{2e,,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{bd4,,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 @ref{bd4,,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{32e,,types.CodeType} has a new parameter in the second position of the
constructor (`posonlyargcount') to support positional-only arguments defined
in 
@geindex Python Enhancement Proposals; PEP 570
PEP 570@footnote{https://peps.python.org/pep-0570/}. The first argument (`argcount') now represents the total
number of positional arguments (including positional-only arguments). The new
@code{replace()} method of @ref{32e,,types.CodeType} can be used to make the code
future-proof.

@item 
The parameter @code{digestmod} for @ref{c8d,,hmac.new()} no longer uses the MD5 digest
by default.
@end itemize

@node C API 中的改動<5>,CPython 位元組碼變更<7>,Python API 的變更<6>,移植至 Python 3 8
@anchor{whatsnew/3 8 changes-in-the-c-api}@anchor{c8e}
@subsubsection C API 中的改動



@itemize *

@item 
The @ref{c8f,,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{42e,,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{3bf,,PyArg_ParseTuple()}, @ref{3c0,,Py_BuildValue()}, @ref{637,,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{3d3,,剖析引數與建置數值} 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{796,,PyType_FromSpec()}) hold a reference to their type object.
Increasing the reference count of these type objects has been moved from
@ref{c58,,PyType_GenericAlloc()} to the more low-level functions,
@ref{c57,,PyObject_Init()} and @code{PyObject_INIT}.
This makes types created through @ref{796,,PyType_FromSpec()} behave like
other classes in managed code.

@ref{97b,,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{788,,Py_INCREF} on the type object after allocating an
instance - if any.
This may happen after calling @ref{b73,,PyObject_New},
@ref{b74,,PyObject_NewVar}, @ref{c90,,PyObject_GC_New()},
@ref{c91,,PyObject_GC_NewVar()}, or any other custom allocator that uses
@ref{c57,,PyObject_Init()} or @code{PyObject_INIT}.

範例：

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

（由 Eddie Elizondo 在 bpo-35810@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35810} 中貢獻。）

@item 
The @ref{c92,,Py_DEPRECATED()} macro has been implemented for MSVC.
The macro now must be placed before the symbol name.

範例：

@example
Py_DEPRECATED(3.8) PyAPI_FUNC(int) Py_OldFunction(void);
@end example

（由 Zackery Spytz 在 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{c93,,PyTypeObject}
exported by a third-party extension module is supposed to have all the
slots expected in the current Python version, including
@ref{c94,,tp_finalize} (@ref{425,,Py_TPFLAGS_HAVE_FINALIZE}
is not checked anymore before reading @ref{c94,,tp_finalize}).

（由 Antoine Pitrou 在 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{c95,,在 Windows 上使用 Python} 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.

（由 Steve Dower 在 bpo-37351@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37351} 中貢獻。）
@end itemize

@node CPython 位元組碼變更<7>,Demos and Tools<2>,C API 中的改動<5>,移植至 Python 3 8
@anchor{whatsnew/3 8 cpython-bytecode-changes}@anchor{c96}
@subsubsection CPython 位元組碼變更



@itemize *

@item 
The interpreter loop  has been simplified by moving the logic of unrolling
the stack of blocks into the compiler.  The compiler emits now explicit
instructions for adjusting the stack of values and calling the
cleaning-up code for @ref{17f,,break}, @ref{180,,continue} and
@ref{1af,,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}.

（由 Mark Shannon、Antoine Pitrou 和 Serhiy Storchaka 在 bpo-17611@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17611} 中貢獻。）

@item 
Added new opcode @ref{c97,,END_ASYNC_FOR} for handling exceptions raised
when awaiting a next item in an @ref{c98,,async for} loop.
(Contributed by Serhiy Storchaka in bpo-33041@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33041}.)

@item 
The @ref{c99,,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 位元組碼變更<7>,移植至 Python 3 8
@anchor{whatsnew/3 8 demos-and-tools}@anchor{c9a}
@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 Python 3 8 1 中顯著的變更,Python 3 8 2 中顯著的變更,移植至 Python 3 8,Python 3 8 有什麼新功能
@anchor{whatsnew/3 8 notable-changes-in-python-3-8-1}@anchor{c9b}
@subsection Python 3.8.1 中顯著的變更


Due to significant security concerns, the `reuse_address' parameter of
@ref{934,,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 Python 3 8 2 中顯著的變更,Python 3 8 3 中顯著的變更,Python 3 8 1 中顯著的變更,Python 3 8 有什麼新功能
@anchor{whatsnew/3 8 notable-changes-in-python-3-8-2}@anchor{c9c}
@subsection Python 3.8.2 中顯著的變更


Fixed a regression with the @code{ignore} callback of @ref{c15,,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 Python 3 8 3 中顯著的變更,Python 3 8 8 中顯著的變更,Python 3 8 2 中顯著的變更,Python 3 8 有什麼新功能
@anchor{whatsnew/3 8 notable-changes-in-python-3-8-3}@anchor{c9d}
@subsection 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 Python 3 8 8 中顯著的變更,Python 3 8 9 中顯著的變更,Python 3 8 3 中顯著的變更,Python 3 8 有什麼新功能
@anchor{whatsnew/3 8 notable-changes-in-python-3-8-8}@anchor{c9e}
@subsection Python 3.8.8 中顯著的變更


Earlier Python versions allowed using both @code{;} and @code{&} as
query parameter separators in @ref{31e,,urllib.parse.parse_qs()} and
@ref{31d,,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 Python 3 8 9 中顯著的變更,Python 3 8 10 中顯著的變更,Python 3 8 8 中顯著的變更,Python 3 8 有什麼新功能
@anchor{whatsnew/3 8 notable-changes-in-python-3-8-9}@anchor{c9f}
@subsection Python 3.8.9 中顯著的變更


A security fix alters the @ref{aed,,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 Python 3 8 10 中顯著的變更,Python 3 8 10 中顯著的變更<2>,Python 3 8 9 中顯著的變更,Python 3 8 有什麼新功能
@anchor{whatsnew/3 8 notable-changes-in-python-3-8-10}@anchor{ca0}
@subsection 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>,,,Python 3 8 10 中顯著的變更
@anchor{whatsnew/3 8 macos-11-0-big-sur-and-apple-silicon-mac-support}@anchor{ca1}
@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 Python 3 8 10 中顯著的變更<2>,Python 3 8 12 中顯著的變更,Python 3 8 10 中顯著的變更,Python 3 8 有什麼新功能
@anchor{whatsnew/3 8 id1}@anchor{ca2}
@subsection Python 3.8.10 中顯著的變更


@menu
* urllib.parse: urllib parse<4>. 

@end menu

@node urllib parse<4>,,,Python 3 8 10 中顯著的變更<2>
@anchor{whatsnew/3 8 urllib-parse}@anchor{ca3}
@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{110,,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 Python 3 8 12 中顯著的變更,Python 3 8 14 中顯著的安全性功能,Python 3 8 10 中顯著的變更<2>,Python 3 8 有什麼新功能
@anchor{whatsnew/3 8 notable-changes-in-python-3-8-12}@anchor{ca4}
@subsection Python 3.8.12 中顯著的變更


@menu
* Python API 的變更: Python API 的變更<7>. 

@end menu

@node Python API 的變更<7>,,,Python 3 8 12 中顯著的變更
@anchor{whatsnew/3 8 id2}@anchor{ca5}
@subsubsection Python API 的變更


Starting with Python 3.8.12 the @ref{84,,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{b51,,socket.inet_aton()} treats leading zeros as octal notation.
glibc implementation of modern @ref{b52,,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 Python 3 8 14 中顯著的安全性功能,Python 3 8 17 中顯著的變更,Python 3 8 12 中顯著的變更,Python 3 8 有什麼新功能
@anchor{whatsnew/3 8 notable-security-feature-in-3-8-14}@anchor{ca6}
@subsection Python 3.8.14 中顯著的安全性功能


Converting between @ref{19b,,int} and @ref{169,,str} in bases other than 2
(binary), 4, 8 (octal), 16 (hexadecimal), or 32 such as base 10 (decimal)
now raises a @ref{2eb,,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{df,,sys} APIs. See the @ref{804,,integer string conversion length limitation} documentation.  The default limit
is 4300 digits in string form.

@node Python 3 8 17 中顯著的變更,,Python 3 8 14 中顯著的安全性功能,Python 3 8 有什麼新功能
@anchor{whatsnew/3 8 notable-changes-in-3-8-17}@anchor{ca7}
@subsection Python 3.8.17 中顯著的變更


@menu
* tarfile: tarfile<6>. 

@end menu

@node tarfile<6>,,,Python 3 8 17 中顯著的變更
@anchor{whatsnew/3 8 id3}@anchor{ca8}
@subsubsection tarfile



@itemize *

@item 
The extraction methods in @ref{e4,,tarfile}, and @ref{68f,,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{690,,Extraction filters} for details.
In Python 3.12, use without the `filter' argument will show a
@ref{1a3,,DeprecationWarning}.
In Python 3.14, the default will switch to @code{'data'}.
(Contributed by Petr Viktorin in 
@geindex Python Enhancement Proposals; PEP 706
PEP 706@footnote{https://peps.python.org/pep-0706/}.)
@end itemize

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Python 3 7 有什麼新功能,Python 3 6 有什麼新功能,Python 3 8 有什麼新功能,Python 有什麼新功能？
@anchor{whatsnew/3 7 doc}@anchor{ca9}@anchor{whatsnew/3 7 translation-repo}@anchor{caa}@anchor{whatsnew/3 7 what-s-new-in-python-3-7}@anchor{cab}
@section Python 3.7 有什麼新功能


@*編輯者: 
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.

本文介紹了 Python 3.7 與 3.6 相比多了哪些新功能。Python 3.7 已於 2018 年 6 月 27 日發布。有關完整詳細資訊，請參閱 @ref{142,,changelog}。

@menu
* 發布重點摘要: 發布重點摘要<7>. 
* 新增功能: 新增功能<12>. 
* 其他語言更動: 其他語言更動<7>. 
* 新模組: 新模組<3>. 
* 改進的模組: 改進的模組<7>. 
* C API 變更: C API 變更<7>. 
* 建置變更: 建置變更<7>. 
* 最佳化: 最佳化<8>. 
* Other CPython Implementation Changes:: 
* 已棄用的 Python 行為:: 
* 已棄用的 Python 模組、函式和方法:: 
* Deprecated functions and types of the C API:: 
* Platform Support Removals:: 
* API 與功能的移除: API 與功能的移除<2>. 
* Module Removals:: 
* Windows-only Changes:: 
* 移植至 Python 3.7: 移植至 Python 3 7. 
* Python 3.7.1 中顯著的變更: Python 3 7 1 中顯著的變更. 
* Python 3.7.2 中顯著的變更: Python 3 7 2 中顯著的變更. 
* Python 3.7.6 中顯著的變更: Python 3 7 6 中顯著的變更. 
* Python 3.7.10 中顯著的變更: Python 3 7 10 中顯著的變更. 
* Python 3.7.11 中顯著的變更: Python 3 7 11 中顯著的變更. 
* Python 3.7.14 中顯著的安全性功能: Python 3 7 14 中顯著的安全性功能. 

@end menu

@node 發布重點摘要<7>,新增功能<12>,,Python 3 7 有什麼新功能
@anchor{whatsnew/3 7 summary-release-highlights}@anchor{cac}
@subsection 發布重點摘要


@c This section singles out the most important changes in Python 3.7.
@c Brevity is key.

新增語法特性：


@itemize *

@item 
@ref{cad,,PEP 563}, postponed evaluation of type annotations.
@end itemize

Backwards incompatible syntax changes:


@itemize *

@item 
@ref{933,,async} 和 @ref{18d,,await} 現為保留關鍵字。
@end itemize

新的函式庫模組：


@itemize *

@item 
@ref{28,,contextvars}: @ref{cae,,PEP 567 -- Context Variables}

@item 
@ref{33,,dataclasses}: @ref{caf,,PEP 557 -- Data Classes}

@item 
@ref{cb0,,importlib.resources}
@end itemize

新的內建功能：


@itemize *

@item 
@ref{cb1,,PEP 553}, the new @ref{271,,breakpoint()} function.
@end itemize

Python 資料模型改進：


@itemize *

@item 
@ref{cb2,,PEP 562}, customization of access to
module attributes.

@item 
@ref{cb3,,PEP 560}, core support for typing module and
generic types.

@item 
the insertion-order preservation nature of @ref{cb4,,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

標準函式庫中的顯著改進


@itemize *

@item 
The @ref{b,,asyncio} module has received new features, significant
@ref{cb5,,usability and performance improvements}.

@item 
The @ref{f4,,time} module gained support for
@ref{cb6,,functions with nanosecond resolution}.
@end itemize

CPython 實作改進：


@itemize *

@item 
Avoiding the use of ASCII as a default text encoding:


@itemize *

@item 
@ref{cb7,,PEP 538}, legacy C locale coercion

@item 
@ref{cb8,,PEP 540}, forced UTF-8 runtime mode
@end itemize

@item 
@ref{cb9,,PEP 552}, deterministic .pycs

@item 
@ref{cba,,新版 Python 開發模式}

@item 
@ref{cbb,,PEP 565}, improved @ref{1a3,,DeprecationWarning}
handling
@end itemize

C API 改進：


@itemize *

@item 
@ref{cbc,,PEP 539}, new C API for thread-local storage
@end itemize

Documentation improvements:


@itemize *

@item 
@ref{cbd,,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{cbe,,最佳化} section lists them in detail.

For a list of changes that may affect compatibility with previous Python
releases please refer to the @ref{cbf,,移植至 Python 3.7} section.

@node 新增功能<12>,其他語言更動<7>,發布重點摘要<7>,Python 3 7 有什麼新功能
@anchor{whatsnew/3 7 new-features}@anchor{cc0}
@subsection 新增功能


@menu
* PEP 563：延後評估註釋:: 
* 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 文件翻譯:: 
* Python Development Mode (-X dev): Python Development Mode -X dev. 

@end menu

@node PEP 563：延後評估註釋,PEP 538 Legacy C Locale Coercion,,新增功能<12>
@anchor{whatsnew/3 7 pep-563-postponed-evaluation-of-annotations}@anchor{cc1}@anchor{whatsnew/3 7 whatsnew37-pep563}@anchor{cad}
@subsubsection PEP 563：延後評估註釋


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{8b9,,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

這將在 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：延後評估註釋,新增功能<12>
@anchor{whatsnew/3 7 pep-538-legacy-c-locale-coercion}@anchor{cc2}@anchor{whatsnew/3 7 whatsnew37-pep538}@anchor{cb7}
@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{cc3,,PYTHONCOERCECLOCALE}
environment variable. Automatically setting @code{LC_CTYPE} this way means that
both the core interpreter and locale-aware C extensions (such as
@ref{bf,,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{758,,stdin} and
@ref{cc4,,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{b2a,,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{b2a,,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{cb8,,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

由 Nick Coghlan 撰寫 PEP 與實作。
@end table


@node PEP 540 Forced UTF-8 Runtime Mode,PEP 553 Built-in breakpoint,PEP 538 Legacy C Locale Coercion,新增功能<12>
@anchor{whatsnew/3 7 pep-540-forced-utf-8-runtime-mode}@anchor{cc5}@anchor{whatsnew/3 7 whatsnew37-pep540}@anchor{cb8}
@subsubsection PEP 540: Forced UTF-8 Runtime Mode


The new @ref{16f,,-X} @code{utf8} command line option and 
@geindex PYTHONUTF8
@geindex 環境變數; PYTHONUTF8
@ref{cc6,,PYTHONUTF8}
environment variable can be used to enable the @ref{85f,,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{758,,sys.stdin} and
@ref{cc4,,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{cb8,,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

由 Victor Stinner 撰寫 PEP 與實作
@end table


@node PEP 553 Built-in breakpoint,PEP 539 New C API for Thread-Local Storage,PEP 540 Forced UTF-8 Runtime Mode,新增功能<12>
@anchor{whatsnew/3 7 pep-553-built-in-breakpoint}@anchor{cc7}@anchor{whatsnew/3 7 whatsnew37-pep553}@anchor{cb1}
@subsubsection PEP 553: Built-in @code{breakpoint()}


Python 3.7 includes the new built-in @ref{271,,breakpoint()} function as
an easy and consistent way to enter the Python debugger.

Built-in @code{breakpoint()} calls @ref{cc8,,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{cc9,,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/} -- 內建的 breakpoint()

由 Barry Warsaw 撰寫 PEP 與實作
@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,新增功能<12>
@anchor{whatsnew/3 7 pep-539-new-c-api-for-thread-local-storage}@anchor{cca}@anchor{whatsnew/3 7 whatsnew37-pep539}@anchor{cbc}
@subsubsection PEP 539: New C API for Thread-Local Storage


While Python provides a C API for thread-local storage support; the existing
@ref{ccb,,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{ccc,,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{ccd,,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 由 Erik M. Bray 撰寫；由 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,新增功能<12>
@anchor{whatsnew/3 7 pep-562-customization-of-access-to-module-attributes}@anchor{cce}@anchor{whatsnew/3 7 whatsnew37-pep562}@anchor{cb2}
@subsubsection PEP 562: Customization of Access to Module Attributes


Python 3.7 allows defining @ref{ccf,,__getattr__()} on modules and will call
it whenever a module attribute is otherwise not found.  Defining
@ref{cd0,,__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/} -- @code{__getattr__} 與 @code{__dir__} 模組

由 Ivan Levkivskyi 撰寫 PEP 與實作
@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,新增功能<12>
@anchor{whatsnew/3 7 pep-564-new-time-functions-with-nanosecond-resolution}@anchor{cd1}@anchor{whatsnew/3 7 whatsnew37-pep564}@anchor{cb6}
@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{557,,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{f4,,time}
module:


@itemize *

@item 
@ref{cd2,,time.clock_gettime_ns()}

@item 
@ref{cd3,,time.clock_settime_ns()}

@item 
@ref{cd4,,time.monotonic_ns()}

@item 
@ref{cd5,,time.perf_counter_ns()}

@item 
@ref{cd6,,time.process_time_ns()}

@item 
@ref{cd7,,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{cd7,,time.time_ns()} is
approximately 3 times better than that of @ref{557,,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

由 Victor Stinner 撰寫 PEP 與實作
@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,新增功能<12>
@anchor{whatsnew/3 7 pep-565-show-deprecationwarning-in-main}@anchor{cd8}@anchor{whatsnew/3 7 whatsnew37-pep565}@anchor{cbb}
@subsubsection PEP 565: Show DeprecationWarning in @code{__main__}


The default handling of @ref{1a3,,DeprecationWarning} has been changed such that
these warnings are once more shown by default, but only when the code
triggering them is running directly in the @ref{1,,__main__} module.  As a result,
developers of single file scripts and those using Python interactively should
once again start seeing deprecation warnings for the APIs they use, but
deprecation warnings triggered by imported application, library and framework
modules will continue to be hidden by default.

As a result of this change, the standard library now allows developers to choose
between three different deprecation warning behaviours:


@itemize *

@item 
@ref{651,,FutureWarning}: always displayed by default, recommended for warnings
intended to be seen by application end users (e.g. for deprecated application
configuration settings).

@item 
@ref{1a3,,DeprecationWarning}: displayed by default only in @ref{1,,__main__} and when
running tests, recommended for warnings intended to be seen by other Python
developers where a version upgrade may result in changed behaviour or an
error.

@item 
@ref{abd,,PendingDeprecationWarning}: displayed by default only when running
tests, intended for cases where a future version upgrade will change the
warning category to @ref{1a3,,DeprecationWarning} or @ref{651,,FutureWarning}.
@end itemize

Previously both @ref{1a3,,DeprecationWarning} and @ref{abd,,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/} -- 在 @code{__main__} 中顯示 DeprecationWarning

由 Nick Coghlan 撰寫 PEP 與實作
@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__,新增功能<12>
@anchor{whatsnew/3 7 pep-560-core-support-for-typing-module-and-generic-types}@anchor{cd9}@anchor{whatsnew/3 7 whatsnew37-pep560}@anchor{cb3}
@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{10a,,typing}
module are extensively used by the community, so this restriction is removed.
The PEP introduces two special methods @ref{93b,,__class_getitem__()} and
@ref{cda,,__mro_entries__()}, these methods are now used by most classes and special
constructs in @ref{10a,,typing}. As a result, the speed of various operations
with types increased up to 7 times, the generic types can be used without
metaclass conflicts, and several long standing bugs in @ref{10a,,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

由 Ivan Levkivskyi 撰寫 PEP 與實作
@end table


@node PEP 552 Hash-based pyc Files,PEP 545：Python 文件翻譯,PEP 560 Core Support for typing module and Generic Types,新增功能<12>
@anchor{whatsnew/3 7 pep-552-hash-based-pyc-files}@anchor{cdb}@anchor{whatsnew/3 7 whatsnew37-pep552}@anchor{cb9}
@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{b8,,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.

更多資訊請見 @ref{7fb,,Cached bytecode invalidation}。


@subsubheading 也參考



@table @asis

@geindex Python Enhancement Proposals; PEP 552

@item PEP 552@footnote{https://peps.python.org/pep-0552/} -- Deterministic pycs

由 Benjamin Peterson 撰寫 PEP 與實作
@end table


@node PEP 545：Python 文件翻譯,Python Development Mode -X dev,PEP 552 Hash-based pyc Files,新增功能<12>
@anchor{whatsnew/3 7 pep-545-python-documentation-translations}@anchor{cdc}@anchor{whatsnew/3 7 whatsnew37-pep545}@anchor{cbd}
@subsubsection PEP 545：Python 文件翻譯


@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 
日文：@indicateurl{https://docs.python.org/ja/}

@item 
法文：@indicateurl{https://docs.python.org/fr/}

@item 
韓文：@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 文件翻譯

PEP 由 Julien Palard、Inada Naoki 與 Victor Stinner 撰寫。
@end table


@node Python Development Mode -X dev,,PEP 545：Python 文件翻譯,新增功能<12>
@anchor{whatsnew/3 7 python-development-mode-x-dev}@anchor{cdd}@anchor{whatsnew/3 7 whatsnew37-devmode}@anchor{cba}
@subsubsection Python Development Mode (-X dev)


The new @ref{16f,,-X} @code{dev} command line option or the new
@geindex PYTHONDEVMODE
@geindex 環境變數; PYTHONDEVMODE
@ref{cde,,PYTHONDEVMODE} environment variable can be used to enable
@ref{503,,Python Development Mode}.  When in development mode, Python performs
additional runtime checks that are too expensive to be enabled by default.
See @ref{503,,Python Development Mode} documentation for the full
description.

@node 其他語言更動<7>,新模組<3>,新增功能<12>,Python 3 7 有什麼新功能
@anchor{whatsnew/3 7 other-language-changes}@anchor{cdf}
@subsection 其他語言更動



@itemize *

@item 
An @ref{18d,,await} expression and comprehensions containing an
@ref{c98,,async for} clause were illegal in the expressions in
@ref{19a,,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{190,,bytes.fromhex()} and @ref{191,,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{169,,str}, @ref{192,,bytes}, and @ref{343,,bytearray} gained support for
the new @ref{ce0,,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{653,,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{ce1,,types.TracebackType} can now be instantiated from Python code, and
the @ref{ce2,,tb_next} attribute on
@ref{ce3,,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{23c,,-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{16f,,-X} @code{importtime} option or the
@geindex PYTHONPROFILEIMPORTTIME
@geindex 環境變數; PYTHONPROFILEIMPORTTIME
@ref{ce4,,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 新模組<3>,改進的模組<7>,其他語言更動<7>,Python 3 7 有什麼新功能
@anchor{whatsnew/3 7 new-modules}@anchor{ce5}
@subsection 新模組


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

@end menu

@node contextvars<2>,dataclasses<3>,,新模組<3>
@anchor{whatsnew/3 7 contextvars}@anchor{ce6}@anchor{whatsnew/3 7 whatsnew37-pep567}@anchor{cae}
@subsubsection contextvars


The new @ref{28,,contextvars} module and a set of
@ref{ce7,,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{3a,,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/} -- 情境變數

由 Yury Selivanov 撰寫 PEP 與實作
@end table


@node dataclasses<3>,importlib resources<2>,contextvars<2>,新模組<3>
@anchor{whatsnew/3 7 dataclasses}@anchor{ce8}@anchor{whatsnew/3 7 whatsnew37-pep557}@anchor{caf}
@subsubsection dataclasses


The new @ref{4dc,,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{828,,__repr__()}, @ref{ce9,,__eq__()}, and
@ref{cea,,__hash__()} are generated automatically.

範例：

@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

由 Eric V. Smith 撰寫 PEP 與實作
@end table


@node importlib resources<2>,,dataclasses<3>,新模組<3>
@anchor{whatsnew/3 7 importlib-resources}@anchor{ceb}@anchor{whatsnew/3 7 whatsnew37-importlib-resources}@anchor{cb0}
@subsubsection importlib.resources


The new @ref{7f,,importlib.resources} module provides several new APIs and one
new ABC for access to, opening, and reading `resources' inside packages.
Resources are roughly similar to files inside packages, but they needn't
be actual files on the physical file system.  Module loaders can provide a
@code{get_resource_reader()} function which returns
a @ref{cec,,importlib.abc.ResourceReader} instance to support this
new API.  Built-in file path loaders and zip file loaders both support this.

由 Barry Warsaw 與 Brett Cannon 在 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 改進的模組<7>,C API 變更<7>,新模組<3>,Python 3 7 有什麼新功能
@anchor{whatsnew/3 7 improved-modules}@anchor{ced}
@subsection 改進的模組


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

@end menu

@node argparse<5>,asyncio<10>,,改進的模組<7>
@anchor{whatsnew/3 7 argparse}@anchor{cee}
@subsubsection argparse


The new @ref{cef,,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<10>,binascii,argparse<5>,改進的模組<7>
@anchor{whatsnew/3 7 asyncio}@anchor{cf0}@anchor{whatsnew/3 7 whatsnew37-asyncio}@anchor{cb5}
@subsubsection asyncio


The @ref{b,,asyncio} module has received many new features, usability and
@ref{cf1,,performance improvements}.  Notable changes
include:


@itemize *

@item 
The new @ref{3cf,,provisional} @ref{2f2,,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{cf2,,loop.call_soon()},
@ref{cf3,,loop.call_soon_threadsafe()},
@ref{cf4,,loop.call_later()},
@ref{cf5,,loop.call_at()}, and
@ref{cf6,,Future.add_done_callback()}
have a new optional keyword-only `context' parameter.
@ref{1c7,,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{1c9,,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{cf7,,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{cf8,,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{69e,,asyncio.current_task()} function returns the currently running
@ref{1c7,,Task} instance, and the new @ref{b46,,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{c8b,,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{cf9,,asyncio.get_running_loop()} function returns the currently
running loop, and raises a @ref{244,,RuntimeError} if no loop is running.
This is in contrast with @ref{2f1,,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{cfa,,StreamWriter.wait_closed()}
coroutine method allows waiting until the stream writer is closed.  The new
@ref{cfb,,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{cfc,,loop.sock_sendfile()}
coroutine method allows sending files using @ref{cfd,,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{cfe,,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{cff,,Server.get_loop()} allows doing the same for
@ref{d00,,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{d00,,asyncio.Server} begin
serving.  Previously, the server would start serving immediately when created.
The new `start_serving' keyword argument to
@ref{d01,,loop.create_server()} and
@ref{4c5,,loop.create_unix_server()},
as well as @ref{d02,,Server.start_serving()}, and
@ref{d03,,Server.serve_forever()}
can be used to decouple server instantiation and serving.  The new
@ref{d04,,Server.is_serving()} method returns @code{True}
if the server is serving.  @ref{d00,,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

（由 Yury Selivanov 在 bpo-32662@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32662} 中貢獻。）

@item 
Callback objects returned by
@ref{cf4,,loop.call_later()}
gained the new @ref{d05,,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{934,,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{d06,,asyncio.open_connection()}, @ref{d07,,asyncio.start_server()} functions,
@ref{811,,loop.create_connection()},
@ref{d01,,loop.create_server()},
@ref{9d7,,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{d08,,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{933,,async}/@ref{18d,,await} syntax.
(Contributed by Andrew Svetlov in bpo-32193@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32193}.)

@item 
The new @ref{d09,,ReadTransport.is_reading()}
method can be used to determine the reading state of the transport.
Additionally, calls to
@ref{d0a,,ReadTransport.resume_reading()}
and @ref{d0b,,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{59b,,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{d0c,,deprecated}.

@node binascii,calendar<3>,asyncio<10>,改進的模組<7>
@anchor{whatsnew/3 7 binascii}@anchor{d0d}
@subsubsection binascii


The @ref{d0e,,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<3>,collections<2>,binascii,改進的模組<7>
@anchor{whatsnew/3 7 calendar}@anchor{d0f}
@subsubsection calendar


The @ref{d10,,HTMLCalendar} class has new class attributes which ease
the customization of CSS classes in the produced HTML calendar.
(Contributed by Oz Tiram in bpo-30095@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30095}.)

@node collections<2>,compileall<3>,calendar<3>,改進的模組<7>
@anchor{whatsnew/3 7 collections}@anchor{d11}
@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<4>,collections<2>,改進的模組<7>
@anchor{whatsnew/3 7 compileall}@anchor{d12}
@subsubsection compileall


@ref{d13,,compileall.compile_dir()} learned the new `invalidation_mode' parameter,
which can be used to enable
@ref{cb9,,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<4>,contextlib<3>,compileall<3>,改進的模組<7>
@anchor{whatsnew/3 7 concurrent-futures}@anchor{d14}
@subsubsection concurrent.futures


@ref{1d6,,ProcessPoolExecutor} and
@ref{941,,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{1d6,,ProcessPoolExecutor}
can now take the multiprocessing context via the new `mp_context' argument.
(Contributed by Thomas Moreau in bpo-31540@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31540}.)

@node contextlib<3>,cProfile<2>,concurrent futures<4>,改進的模組<7>
@anchor{whatsnew/3 7 contextlib}@anchor{d15}
@subsubsection contextlib


The new @ref{9e8,,nullcontext()} is a simpler and faster no-op
context manager than @ref{d16,,ExitStack}.
(Contributed by Jesse-Bakker in bpo-10049@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10049}.)

The new @ref{d17,,asynccontextmanager()},
@ref{d18,,AbstractAsyncContextManager}, and
@ref{d19,,AsyncExitStack} have been added to
complement their synchronous counterparts.  (Contributed
by Jelle Zijlstra in bpo-29679@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29679} and bpo-30241@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30241},
and by Alexander Mohr and Ilya Kulakov in bpo-29302@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29302}.)

@node cProfile<2>,crypt,contextlib<3>,改進的模組<7>
@anchor{whatsnew/3 7 cprofile}@anchor{d1a}
@subsubsection cProfile


The @ref{2b,,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<5>,cProfile<2>,改進的模組<7>
@anchor{whatsnew/3 7 crypt}@anchor{d1b}
@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<5>,dbm<2>,crypt,改進的模組<7>
@anchor{whatsnew/3 7 datetime}@anchor{d1c}
@subsubsection datetime


The new @ref{823,,datetime.fromisoformat()}
method constructs a @ref{4dd,,datetime} object from a string
in one of the formats output by
@ref{d1d,,datetime.isoformat()}.
(Contributed by Paul Ganssle in bpo-15873@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15873}.)

The @ref{7ef,,tzinfo} class now supports sub-minute offsets.
(Contributed by Alexander Belopolsky in bpo-5288@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5288}.)

@node dbm<2>,decimal<2>,datetime<5>,改進的模組<7>
@anchor{whatsnew/3 7 dbm}@anchor{d1e}
@subsubsection dbm


@ref{36,,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<2>,改進的模組<7>
@anchor{whatsnew/3 7 decimal}@anchor{d1f}
@subsubsection decimal


The @ref{3a,,decimal} module now uses @ref{cae,,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>,改進的模組<7>
@anchor{whatsnew/3 7 dis}@anchor{d20}
@subsubsection dis


The @ref{205,,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>,改進的模組<7>
@anchor{whatsnew/3 7 distutils}@anchor{d21}
@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<4>,distutils<4>,改進的模組<7>
@anchor{whatsnew/3 7 enum}@anchor{d22}
@subsubsection enum


The @ref{83b,,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{83b,,Enum}
classes will raise a @ref{198,,TypeError} (e.g. @code{1 in Color}); similarly,
attempting to check for non-Flag objects in a @ref{82e,,Flag} member will
raise @ref{198,,TypeError} (e.g. @code{1 in Perm.RW}); currently, both operations
return @ref{d23,,False} instead and are deprecated.
(Contributed by Ethan Furman in bpo-33217@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33217}.)

@node functools<4>,gc<5>,enum<5>,改進的模組<7>
@anchor{whatsnew/3 7 functools}@anchor{d24}
@subsubsection functools


@ref{844,,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<5>,hmac<3>,functools<4>,改進的模組<7>
@anchor{whatsnew/3 7 gc}@anchor{d25}
@subsubsection gc


The new @ref{d26,,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{d27,,gc.unfreeze()} functions
reverses this operation.  Additionally, @ref{d28,,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,gc<5>,改進的模組<7>
@anchor{whatsnew/3 7 hmac}@anchor{d29}
@subsubsection hmac


The @ref{6e,,hmac} module now has an optimized one-shot @ref{d2a,,digest()}
function, which is up to three times faster than @ref{d2b,,HMAC()}.
(Contributed by Christian Heimes in bpo-32433@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32433}.)

@node http client,http server,hmac<3>,改進的模組<7>
@anchor{whatsnew/3 7 http-client}@anchor{d2c}
@subsubsection http.client


@ref{d2d,,HTTPConnection} and @ref{d2e,,HTTPSConnection}
now support the new `blocksize' argument for improved upload throughput.
(Contributed by Nir Soffer in bpo-31945@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31945}.)

@node http server,idlelib 與 IDLE,http client,改進的模組<7>
@anchor{whatsnew/3 7 http-server}@anchor{d2f}
@subsubsection http.server


@ref{d30,,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{d30,,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{d31,,ThreadingHTTPServer} class
uses threads to handle requests using @ref{d32,,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 與 IDLE,importlib<4>,http server,改進的模組<7>
@anchor{whatsnew/3 7 idlelib-and-idle}@anchor{d33}
@subsubsection idlelib 與 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 與 IDLE,改進的模組<7>
@anchor{whatsnew/3 7 importlib}@anchor{d34}
@subsubsection importlib


The @ref{cec,,importlib.abc.ResourceReader} ABC was introduced to
support the loading of resources from packages.  See also
@ref{cb0,,importlib.resources}.
(Contributed by Barry Warsaw, Brett Cannon in bpo-32248@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32248}.)

@ref{736,,importlib.reload()} now raises @ref{d35,,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{5a9,,importlib.util.find_spec()} now raises @ref{d35,,ModuleNotFoundError} instead of
@ref{5e8,,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{d36,,importlib.util.source_hash()} can be used to compute the hash of
the passed source.  A @ref{cb9,,hash-based .pyc file}
embeds the value returned by this function.

@node io<6>,ipaddress<3>,importlib<4>,改進的模組<7>
@anchor{whatsnew/3 7 io}@anchor{d37}
@subsubsection io


The new @ref{d38,,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>,改進的模組<7>
@anchor{whatsnew/3 7 ipaddress}@anchor{d39}
@subsubsection ipaddress


The new @code{subnet_of()} and @code{supernet_of()} methods of
@ref{50a,,ipaddress.IPv6Network} and @ref{509,,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<4>,ipaddress<3>,改進的模組<7>
@anchor{whatsnew/3 7 itertools}@anchor{d3a}
@subsubsection itertools


@ref{d3b,,itertools.islice()} now accepts
@ref{19e,,integer-like objects} as start, stop,
and slice arguments.
(Contributed by Will Roberts in bpo-30537@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30537}.)

@node locale<4>,logging<3>,itertools<6>,改進的模組<7>
@anchor{whatsnew/3 7 locale}@anchor{d3c}
@subsubsection locale


The new `monetary' argument to @ref{73b,,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{755,,locale.getpreferredencoding()} function now always returns @code{'UTF-8'}
on Android or when in the @ref{cb8,,forced UTF-8 mode}.

@node logging<3>,math<7>,locale<4>,改進的模組<7>
@anchor{whatsnew/3 7 logging}@anchor{d3d}
@subsubsection logging


@ref{d3e,,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{d3f,,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{d40,,logging.config.fileConfig()}.
(Contributed by Preston Landers in bpo-31080@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31080}.)

@node math<7>,mimetypes<3>,logging<3>,改進的模組<7>
@anchor{whatsnew/3 7 math}@anchor{d41}
@subsubsection math


The new @ref{d42,,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<3>,msilib,math<7>,改進的模組<7>
@anchor{whatsnew/3 7 mimetypes}@anchor{d43}
@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<3>,改進的模組<7>
@anchor{whatsnew/3 7 msilib}@anchor{d44}
@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<8>,msilib,改進的模組<7>
@anchor{whatsnew/3 7 multiprocessing}@anchor{d45}
@subsubsection multiprocessing


The new @ref{d46,,Process.close()} method
explicitly closes the process object and releases all resources associated
with it.  @ref{2eb,,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{d47,,Process.kill()} method can
be used to terminate the process using the @ref{d48,,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{252,,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<8>,pathlib<11>,multiprocessing<5>,改進的模組<7>
@anchor{whatsnew/3 7 os}@anchor{d49}
@subsubsection os


@ref{d4a,,os.fwalk()} now accepts the `path' argument as @ref{192,,bytes}.
(Contributed by Serhiy Storchaka in bpo-28682@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28682}.)

@ref{c4b,,os.scandir()} gained support for @ref{d4b,,file descriptors}.
(Contributed by Serhiy Storchaka in bpo-25996@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25996}.)

The new @ref{353,,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{d4c,,os.preadv()} (combine the functionality of @ref{d4d,,os.readv()} and
@ref{d4e,,os.pread()}) and @ref{d4f,,os.pwritev()} functions (combine the functionality
of @ref{d50,,os.writev()} and @ref{d51,,os.pwrite()}). (Contributed by Pablo Galindo in
bpo-31368@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31368}.)

The mode argument of @ref{527,,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{d52,,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{26d,,os.stat()} now contains the
@ref{d53,,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<11>,pdb<6>,os<8>,改進的模組<7>
@anchor{whatsnew/3 7 pathlib}@anchor{d54}
@subsubsection pathlib


The new @ref{c03,,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<6>,py_compile<3>,pathlib<11>,改進的模組<7>
@anchor{whatsnew/3 7 pdb}@anchor{d55}
@subsubsection pdb


@ref{272,,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<6>,改進的模組<7>
@anchor{whatsnew/3 7 py-compile}@anchor{d56}
@subsubsection py_compile


@ref{c11,,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>,改進的模組<7>
@anchor{whatsnew/3 7 pydoc}@anchor{d57}
@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<5>,pydoc<3>,改進的模組<7>
@anchor{whatsnew/3 7 queue}@anchor{d58}
@subsubsection queue


The new @ref{d59,,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<5>,signal<2>,queue<2>,改進的模組<7>
@anchor{whatsnew/3 7 re}@anchor{d5a}
@subsubsection re


The flags @ref{838,,re.ASCII}, @ref{d5b,,re.LOCALE} and @ref{d5c,,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{59c,,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{d5b,,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{651,,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{750,,copy.copy()} and @ref{d5d,,copy.deepcopy()}.
(Contributed by Serhiy Storchaka in bpo-10076@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10076}.)

@node signal<2>,socket<6>,re<5>,改進的模組<7>
@anchor{whatsnew/3 7 signal}@anchor{d5e}
@subsubsection signal


The new `warn_on_full_buffer' argument to the @ref{d5f,,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<6>,socketserver,signal<2>,改進的模組<7>
@anchor{whatsnew/3 7 socket}@anchor{d60}
@subsubsection socket


The new @ref{d61,,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{d62,,socket.close()} function closes the passed socket file descriptor.
This function should be used instead of @ref{d63,,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{d1,,socket} module now exposes the @ref{d64,,socket.TCP_CONGESTION} (Linux 2.6.13), @ref{d64,,socket.TCP_USER_TIMEOUT} (Linux 2.6.37), and @ref{d64,,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{d65,,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<7>,socket<6>,改進的模組<7>
@anchor{whatsnew/3 7 socketserver}@anchor{d66}
@subsubsection socketserver


@ref{d67,,socketserver.ThreadingMixIn.server_close} now waits until all non-daemon
threads complete. @ref{d67,,socketserver.ForkingMixIn.server_close} now waits
until all child processes complete.

Add a new @ref{d68,,socketserver.ForkingMixIn.block_on_close} class attribute to
@ref{d69,,socketserver.ForkingMixIn} and @ref{d32,,socketserver.ThreadingMixIn}
classes. Set the class attribute to @code{False} to get the pre-3.7 behaviour.

@node sqlite3<7>,ssl<6>,socketserver,改進的模組<7>
@anchor{whatsnew/3 7 sqlite3}@anchor{d6a}
@subsubsection sqlite3


@ref{548,,sqlite3.Connection} now exposes the @ref{d6b,,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{5a0,,sqlite3.connect()} now accepts any
@ref{59b,,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<6>,string<2>,sqlite3<7>,改進的模組<7>
@anchor{whatsnew/3 7 ssl}@anchor{d6c}
@subsubsection ssl


The @ref{d5,,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{d6d,,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{d6e,,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{d6f,,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{d70,,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{d71,,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{ade,,SSLSocket} and @ref{d72,,SSLObject} no longer have a public
constructor.  Direct instantiation was never a documented and supported
feature.  Instances must be created with @ref{355,,SSLContext} methods
@ref{741,,wrap_socket()} and @ref{d73,,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{d74,,SSLContext.minimum_version}
and @ref{d75,,SSLContext.maximum_version}.
Supported protocols are indicated by several new flags, such as
@ref{d76,,HAS_TLSv1_1}.
(Contributed by Christian Heimes in bpo-32609@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32609}.)

Added @ref{c1d,,ssl.SSLContext.post_handshake_auth} to enable and
@ref{c1e,,ssl.SSLSocket.verify_client_post_handshake()} to initiate TLS 1.3
post-handshake authentication.
(Contributed by Christian Heimes in gh-78851@footnote{https://github.com/python/cpython/issues/78851}.)

@node string<2>,subprocess<2>,ssl<6>,改進的模組<7>
@anchor{whatsnew/3 7 string}@anchor{d77}
@subsubsection string


@ref{890,,string.Template} now lets you to optionally modify the regular
expression pattern for braced placeholders and non-braced placeholders
separately.  (Contributed by Barry Warsaw in bpo-1198569@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1198569}.)

@node subprocess<2>,sys<8>,string<2>,改進的模組<7>
@anchor{whatsnew/3 7 subprocess}@anchor{d78}
@subsubsection subprocess


The @ref{d79,,subprocess.run()} function accepts the new `capture_output'
keyword argument.  When true, stdout and stderr will be captured.
This is equivalent to passing @ref{d7a,,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{4b2,,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{4b2,,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{bbc,,KeyboardInterrupt} during @ref{d7b,,subprocess.call()},
@ref{d79,,subprocess.run()}, or in a @ref{4b2,,Popen}
context manager.  It now waits a short amount of time for the child
to exit, before continuing the handling of the @code{KeyboardInterrupt}
exception.
(Contributed by Gregory P. Smith in bpo-25942@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25942}.)

@node sys<8>,time<5>,subprocess<2>,改進的模組<7>
@anchor{whatsnew/3 7 sys}@anchor{d7c}
@subsubsection sys


The new @ref{cc8,,sys.breakpointhook()} hook function is called by the
built-in @ref{271,,breakpoint()}.
(Contributed by Barry Warsaw in bpo-31353@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31353}.)

On Android, the new @ref{d7d,,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{d7e,,sys.get_coroutine_origin_tracking_depth()} function returns
the current coroutine origin tracking depth, as set by
the new @ref{d7f,,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<6>,sys<8>,改進的模組<7>
@anchor{whatsnew/3 7 time}@anchor{d80}
@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{f4,,time} module:


@itemize *

@item 
@ref{cd2,,time.clock_gettime_ns()}

@item 
@ref{cd3,,time.clock_settime_ns()}

@item 
@ref{cd4,,time.monotonic_ns()}

@item 
@ref{cd5,,time.perf_counter_ns()}

@item 
@ref{cd6,,time.process_time_ns()}

@item 
@ref{cd7,,time.time_ns()}
@end itemize

New clock identifiers have been added:


@itemize *

@item 
@ref{d81,,time.CLOCK_BOOTTIME} (Linux): Identical to
@ref{d82,,time.CLOCK_MONOTONIC}, except it also includes any time that the
system is suspended.

@item 
@ref{d83,,time.CLOCK_PROF} (FreeBSD, NetBSD and OpenBSD): High-resolution
per-process CPU timer.

@item 
@ref{d84,,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{b27,,time.thread_time()} and @ref{d85,,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{d86,,time.pthread_getcpuclockid()} function returns the clock ID
of the thread-specific CPU-time clock.

@node tkinter<6>,tracemalloc<2>,time<5>,改進的模組<7>
@anchor{whatsnew/3 7 tkinter}@anchor{d87}
@subsubsection tkinter


The new @ref{d88,,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<5>,tkinter<6>,改進的模組<7>
@anchor{whatsnew/3 7 tracemalloc}@anchor{d89}
@subsubsection tracemalloc


@ref{d8a,,tracemalloc.Traceback} behaves more like regular tracebacks,
sorting the frames from oldest to most recent.
@ref{d8b,,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<5>,unicodedata<7>,tracemalloc<2>,改進的模組<7>
@anchor{whatsnew/3 7 types}@anchor{d8c}
@subsubsection types


The new @ref{d8d,,WrapperDescriptorType},
@ref{854,,MethodWrapperType}, @ref{d8e,,MethodDescriptorType},
and @ref{d8f,,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{d90,,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<7>,unittest<8>,types<5>,改進的模組<7>
@anchor{whatsnew/3 7 unicodedata}@anchor{d91}
@subsubsection unicodedata


The internal @ref{10b,,unicodedata} database has been upgraded to use Unicode 11@footnote{https://www.unicode.org/versions/Unicode11.0.0/}. (Contributed by Benjamin
Peterson.)

@node unittest<8>,unittest mock,unicodedata<7>,改進的模組<7>
@anchor{whatsnew/3 7 unittest}@anchor{d92}
@subsubsection unittest


The new @code{-k} command-line option allows filtering tests by a name
substring or a Unix shell-like pattern.
For example, @code{python -m unittest -k foo} runs
@code{foo_tests.SomeTest.test_something}, @code{bar_tests.SomeTest.test_foo},
but not @code{bar_tests.FooTest.test_something}.
(Contributed by Jonas Haag in bpo-32071@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32071}.)

@node unittest mock,urllib parse<5>,unittest<8>,改進的模組<7>
@anchor{whatsnew/3 7 unittest-mock}@anchor{d93}
@subsubsection unittest.mock


The @ref{d94,,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{d95,,seal()} function allows sealing
@ref{c36,,Mock} instances, which will disallow further creation
of attribute mocks.  The seal is applied recursively to all attributes that
are themselves mocks.
(Contributed by Mario Corchero in bpo-30541@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30541}.)

@node urllib parse<5>,uu,unittest mock,改進的模組<7>
@anchor{whatsnew/3 7 urllib-parse}@anchor{d96}
@subsubsection urllib.parse


@ref{d97,,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<5>,改進的模組<7>
@anchor{whatsnew/3 7 uu}@anchor{d98}
@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<3>,uu,改進的模組<7>
@anchor{whatsnew/3 7 uuid}@anchor{d99}
@subsubsection uuid


The new @ref{d9a,,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{d9b,,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{d9c,,uuid.uuid1()}.  If only locally administered MAC addresses are
available, the first such one found is returned.
(Contributed by Barry Warsaw in bpo-32107@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32107}.)

@node warnings<3>,xml<5>,uuid<4>,改進的模組<7>
@anchor{whatsnew/3 7 warnings}@anchor{d9d}
@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{7f2,,-b}
and the new CPython-specific @ref{16f,,-X} @code{dev} option) are always passed
to the warnings machinery via the @ref{3f3,,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{7f2,,-b} (or @code{-bb})

@item 
any filters specified with the @ref{abc,,-W} option

@item 
any filters specified with the 
@geindex PYTHONWARNINGS
@geindex 環境變數; PYTHONWARNINGS
@ref{d9e,,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{504,,CPython debug builds}, all warnings are now displayed
by default (the implicit filter list is empty)
@end itemize

（由 Nick Coghlan 和 Victor Stinner 在 bpo-20361@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20361}、bpo-32043@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32043} 和 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{cbb,,PEP 565; Show DeprecationWarning in __main__} for details.
(Contributed by Nick Coghlan in bpo-31975@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31975}.)

@node xml<5>,xml etree,warnings<3>,改進的模組<7>
@anchor{whatsnew/3 7 xml}@anchor{d9f}
@subsubsection xml


As mitigation against DTD and external entity retrieval, the
@ref{128,,xml.dom.minidom} and @ref{12f,,xml.sax} modules no longer process
external entities by default.
(Contributed by Christian Heimes in gh-61441@footnote{https://github.com/python/cpython/issues/61441}.)

@node xml etree,xmlrpc server,xml<5>,改進的模組<7>
@anchor{whatsnew/3 7 xml-etree}@anchor{da0}
@subsubsection xml.etree


@ref{da1,,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,改進的模組<7>
@anchor{whatsnew/3 7 xmlrpc-server}@anchor{da2}
@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,改進的模組<7>
@anchor{whatsnew/3 7 zipapp}@anchor{da3}
@subsubsection zipapp


Function @ref{da4,,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{da4,,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,改進的模組<7>
@anchor{whatsnew/3 7 zipfile}@anchor{da5}
@subsubsection zipfile


@ref{8cb,,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 變更<7>,建置變更<7>,改進的模組<7>,Python 3 7 有什麼新功能
@anchor{whatsnew/3 7 c-api-changes}@anchor{da6}
@subsection C API 變更


A new API for thread-local storage has been implemented.  See
@ref{cbc,,PEP 539; New C API for Thread-Local Storage} for an overview and
@ref{ccc,,Thread Specific Storage (TSS) API} for a complete reference.
(Contributed by Masayuki Yamamoto in bpo-25658@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25658}.)

The new @ref{cae,,context variables} functionality
exposes a number of @ref{ce7,,new C APIs}.

The new @ref{da7,,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{da8,,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{da9,,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{105,,tracemalloc} now exposes a C API through the new
@ref{daa,,PyTraceMalloc_Track()} and @ref{dab,,PyTraceMalloc_Untrack()}
functions.
(Contributed by Victor Stinner in bpo-30054@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30054}.)

The new @ref{dac,,import__find__load__start} and
@ref{dac,,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{76a,,PyMemberDef}, @ref{dad,,PyGetSetDef},
@ref{dae,,PyStructSequence_Field}, @ref{daf,,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{a90,,PyUnicode_AsUTF8AndSize()} and @ref{422,,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{db0,,PyMapping_Keys()}, @ref{db1,,PyMapping_Values()} and
@ref{db2,,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{430,,PySlice_Unpack()} and @ref{431,,PySlice_AdjustIndices()}.
(Contributed by Serhiy Storchaka in bpo-27867@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27867}.)

@ref{42d,,PyOS_AfterFork()} is deprecated in favour of the new functions
@ref{db3,,PyOS_BeforeFork()}, @ref{db4,,PyOS_AfterFork_Parent()} and
@ref{42e,,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{db5,,PyTimeZone_FromOffset()} and @ref{db6,,PyTimeZone_FromOffsetAndName()},
and access to the UTC singleton with @ref{db7,,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{db8,,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{ab0,,PyUnicode_AsWideCharString()} now raises a @ref{2eb,,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{45e,,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{cbf,,移植至 Python 3.7} section in this
document and the @ref{db9,,Python 初始化之前} section in the C API documentation
for more details.

The new @ref{dba,,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{dbb,,Py_DecodeLocale()}, @ref{dbc,,Py_EncodeLocale()} now use the UTF-8
encoding when the @ref{cb8,,UTF-8 mode} is enabled.
(Contributed by Victor Stinner in bpo-29240@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29240}.)

@ref{dbd,,PyUnicode_DecodeLocaleAndSize()} and @ref{dbe,,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{aad,,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 建置變更<7>,最佳化<8>,C API 變更<7>,Python 3 7 有什麼新功能
@anchor{whatsnew/3 7 build-changes}@anchor{dbf}
@subsection 建置變更


Support for building @code{--without-threads} has been removed.  The
@ref{f3,,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{2e,,_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{d5,,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 最佳化<8>,Other CPython Implementation Changes,建置變更<7>,Python 3 7 有什麼新功能
@anchor{whatsnew/3 7 optimizations}@anchor{dc0}@anchor{whatsnew/3 7 whatsnew37-perf}@anchor{cbe}
@subsection 最佳化


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{cf1}
The @ref{b,,asyncio} module received a number of notable optimizations for
commonly used functions:


@itemize *

@item 
The @ref{2f1,,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{dc1,,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{80c,,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{c5b,,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{cb3,,PEP 560 work}, the import time
of @ref{10a,,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{dc2,,sorted()} and @ref{dc3,,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{dc4,,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{6f2,,hasattr()} and @ref{dc5,,getattr()} are now about 4 times faster when
`name' is not found and `obj' does not override @ref{6f3,,object.__getattr__()}
or @ref{dc6,,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{4db,,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{dc7,,datetime.date.fromordinal()} and @ref{dc8,,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{d4a,,os.fwalk()} function is now up to 2 times faster thanks to
the use of @ref{c4b,,os.scandir()}.
(Contributed by Serhiy Storchaka in bpo-25996@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25996}.)

The speed of the @ref{354,,shutil.rmtree()} function has been improved by
20--40% thanks to the use of the @ref{c4b,,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{be,,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{dc9,,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{dca,,modify()} methods of classes
@ref{dcb,,selectors.EpollSelector}, @ref{dcc,,selectors.PollSelector}
and @ref{dcd,,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{2ad,,isinstance()}
and @ref{9bd,,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{1fa,,datetime.date} and @ref{4dd,,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{4b9,,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{dce,,math.erf()} and @ref{dcf,,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,已棄用的 Python 行為,最佳化<8>,Python 3 7 有什麼新功能
@anchor{whatsnew/3 7 other-cpython-implementation-changes}@anchor{dd0}
@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{dd1,,f_trace_lines} and @ref{dd2,,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{469,,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 已棄用的 Python 行為,已棄用的 Python 模組、函式和方法,Other CPython Implementation Changes,Python 3 7 有什麼新功能
@anchor{whatsnew/3 7 deprecated-python-behavior}@anchor{dd3}
@subsection 已棄用的 Python 行為


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{dd4,,generator iterator} object), while generator
expressions won't attempt to interleave their implicit output with the output
from any explicit yield expressions.  In Python 3.7, such expressions emit
@ref{1a3,,DeprecationWarning} when compiled, in Python 3.8 this will be a
@ref{18e,,SyntaxError}.
(Contributed by Serhiy Storchaka in bpo-10544@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10544}.)

Returning a subclass of @ref{197,,complex} from @ref{7f8,,object.__complex__()} is
deprecated and will be an error in future Python versions.  This makes
@code{__complex__()} consistent with @ref{19d,,object.__int__()} and
@ref{bb8,,object.__float__()}.
(Contributed by Serhiy Storchaka in bpo-28894@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28894}.)

@node 已棄用的 Python 模組、函式和方法,Deprecated functions and types of the C API,已棄用的 Python 行為,Python 3 7 有什麼新功能
@anchor{whatsnew/3 7 deprecated-python-modules-functions-and-methods}@anchor{dd5}
@subsection 已棄用的 Python 模組、函式和方法


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

@end menu

@node aifc,asyncio<11>,,已棄用的 Python 模組、函式和方法
@anchor{whatsnew/3 7 aifc}@anchor{dd6}
@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<11>,collections<3>,aifc,已棄用的 Python 模組、函式和方法
@anchor{whatsnew/3 7 id2}@anchor{dd7}@anchor{whatsnew/3 7 whatsnew37-asyncio-deprecated}@anchor{d0c}
@subsubsection asyncio


Support for directly @code{await}-ing instances of @ref{c5d,,asyncio.Lock} and
other asyncio synchronization primitives has been deprecated.  An
asynchronous context manager must be used in order to acquire and release
the synchronization resource.
(Contributed by Andrew Svetlov in bpo-32253@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32253}.)

The @code{asyncio.Task.current_task()} and @code{asyncio.Task.all_tasks()}
methods have been deprecated.
(Contributed by Andrew Svetlov in bpo-32250@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32250}.)

@node collections<3>,dbm<3>,asyncio<11>,已棄用的 Python 模組、函式和方法
@anchor{whatsnew/3 7 id3}@anchor{dd8}
@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<3>,enum<6>,collections<3>,已棄用的 Python 模組、函式和方法
@anchor{whatsnew/3 7 id4}@anchor{dd9}
@subsubsection dbm


@ref{36,,dbm.dumb} now supports reading read-only files and no longer writes the
index file when it is not changed.  A deprecation warning is now emitted
if the index file is missing and recreated in the @code{'r'} and @code{'w'}
modes (this will be an error in future Python releases).
(Contributed by Serhiy Storchaka in bpo-28847@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28847}.)

@node enum<6>,gettext<2>,dbm<3>,已棄用的 Python 模組、函式和方法
@anchor{whatsnew/3 7 id5}@anchor{dda}
@subsubsection enum


In Python 3.8, attempting to check for non-Enum objects in @ref{83b,,Enum}
classes will raise a @ref{198,,TypeError} (e.g. @code{1 in Color}); similarly,
attempting to check for non-Flag objects in a @ref{82e,,Flag} member will
raise @ref{198,,TypeError} (e.g. @code{1 in Perm.RW}); currently, both operations
return @ref{d23,,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>,已棄用的 Python 模組、函式和方法
@anchor{whatsnew/3 7 gettext}@anchor{ddb}
@subsubsection gettext


Using non-integer value for selecting a plural form in @ref{67,,gettext} is
now deprecated.  It never correctly worked. (Contributed by Serhiy Storchaka
in bpo-28692@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28692}.)

@node importlib<5>,locale<5>,gettext<2>,已棄用的 Python 模組、函式和方法
@anchor{whatsnew/3 7 id6}@anchor{ddc}
@subsubsection importlib


Methods
@code{MetaPathFinder.find_module()}
(replaced by
@ref{a61,,MetaPathFinder.find_spec()})
and
@code{PathEntryFinder.find_loader()}
(replaced by
@ref{a65,,PathEntryFinder.find_spec()})
both deprecated in Python 3.4 now emit @ref{1a3,,DeprecationWarning}.
(Contributed by Matthias Bussonnier in bpo-29576@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29576}.)

The @ref{ddd,,importlib.abc.ResourceLoader} ABC has been deprecated in
favour of @ref{cec,,importlib.abc.ResourceReader}.

@node locale<5>,macpath,importlib<5>,已棄用的 Python 模組、函式和方法
@anchor{whatsnew/3 7 id7}@anchor{dde}
@subsubsection locale


@code{locale.format()} has been deprecated, use @ref{73b,,locale.format_string()}
instead.  (Contributed by Garvit in bpo-10379@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10379}.)

@node macpath,threading<6>,locale<5>,已棄用的 Python 模組、函式和方法
@anchor{whatsnew/3 7 macpath}@anchor{ddf}
@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<6>,socket<7>,macpath,已棄用的 Python 模組、函式和方法
@anchor{whatsnew/3 7 threading}@anchor{de0}
@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{f3,,threading} instead.
(Contributed by Antoine Pitrou in bpo-31370@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31370}.)

@node socket<7>,ssl<7>,threading<6>,已棄用的 Python 模組、函式和方法
@anchor{whatsnew/3 7 id8}@anchor{de1}
@subsubsection socket


The silent argument value truncation in @ref{a76,,socket.htons()} and
@ref{a77,,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<7>,sunau,socket<7>,已棄用的 Python 模組、函式和方法
@anchor{whatsnew/3 7 id9}@anchor{de2}
@subsubsection ssl


@code{ssl.wrap_socket()} is deprecated.  Use
@ref{741,,ssl.SSLContext.wrap_socket()} instead.
(Contributed by Christian Heimes in bpo-28124@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28124}.)

@node sunau,sys<9>,ssl<7>,已棄用的 Python 模組、函式和方法
@anchor{whatsnew/3 7 sunau}@anchor{de3}
@subsubsection sunau


@code{sunau.openfp()} has been deprecated and will be removed in Python 3.9.
Use @code{sunau.open()} instead.
(Contributed by Brian Curtin in bpo-31985@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31985}.)

@node sys<9>,wave,sunau,已棄用的 Python 模組、函式和方法
@anchor{whatsnew/3 7 id10}@anchor{de4}
@subsubsection sys


Deprecated @code{sys.set_coroutine_wrapper()} and
@code{sys.get_coroutine_wrapper()}.

The undocumented @code{sys.callstats()} function has been deprecated and
will be removed in a future Python version.
(Contributed by Victor Stinner in bpo-28799@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28799}.)

@node wave,,sys<9>,已棄用的 Python 模組、函式和方法
@anchor{whatsnew/3 7 wave}@anchor{de5}
@subsubsection wave


@code{wave.openfp()} has been deprecated and will be removed in Python 3.9.
Use @ref{b3c,,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,已棄用的 Python 模組、函式和方法,Python 3 7 有什麼新功能
@anchor{whatsnew/3 7 deprecated-functions-and-types-of-the-c-api}@anchor{de6}
@subsection Deprecated functions and types of the C API


Function @ref{42f,,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{42d,,PyOS_AfterFork()} has been deprecated.  Use @ref{db3,,PyOS_BeforeFork()},
@ref{db4,,PyOS_AfterFork_Parent()} or @ref{42e,,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 與功能的移除<2>,Deprecated functions and types of the C API,Python 3 7 有什麼新功能
@anchor{whatsnew/3 7 id11}@anchor{de7}@anchor{whatsnew/3 7 platform-support-removals}@anchor{d6f}
@subsection Platform Support Removals



@itemize *

@item 
FreeBSD 9 and older are no longer officially supported.

@item 
For full Unicode support, including within extension modules, *nix platforms
are now expected to provide at least one of @code{C.UTF-8} (full locale),
@code{C.utf8} (full locale) or @code{UTF-8} (@code{LC_CTYPE}-only locale) as an
alternative to the legacy @code{ASCII}-based @code{C} locale.

@item 
OpenSSL 0.9.8 and 1.0.1 are no longer supported, which means building CPython
3.7 with SSL/TLS support on older platforms still using these versions
requires custom build options that link to a more recent version of OpenSSL.

Notably, this issue affects the Debian 8 (aka "jessie") and Ubuntu 14.04
(aka "Trusty") LTS Linux distributions, as they still use OpenSSL 1.0.1 by
default.

Debian 9 ("stretch") and Ubuntu 16.04 ("xenial"), as well as recent releases
of other LTS Linux releases (e.g. RHEL/CentOS 7.5, SLES 12-SP3), use OpenSSL
1.0.2 or later, and remain supported in the default build configuration.

CPython's own CI configuration file@footnote{https://github.com/python/cpython/blob/v3.7.13/.travis.yml} provides an
example of using the SSL
compatibility testing infrastructure@footnote{https://github.com/python/cpython/tree/3.14/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 與功能的移除<2>,Module Removals,Platform Support Removals,Python 3 7 有什麼新功能
@anchor{whatsnew/3 7 api-and-feature-removals}@anchor{de8}
@subsection API 與功能的移除


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{59d,,re.sub()} were deprecated in Python 3.5, and will now
cause an error.

@item 
Removed support of the `exclude' argument in @ref{de9,,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{dea,,splitdrive()}
instead.

@item 
@ref{4db,,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{3c1,,bool()}, @ref{196,,float()}, @ref{24d,,list()} and @ref{60c,,tuple()} no
longer take keyword arguments.  The first argument of @ref{19b,,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{deb,,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{c7,,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{ade,,ssl.SSLSocket} and @ref{d72,,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{355,,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 與功能的移除<2>,Python 3 7 有什麼新功能
@anchor{whatsnew/3 7 module-removals}@anchor{dec}
@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,移植至 Python 3 7,Module Removals,Python 3 7 有什麼新功能
@anchor{whatsnew/3 7 windows-only-changes}@anchor{ded}
@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 移植至 Python 3 7,Python 3 7 1 中顯著的變更,Windows-only Changes,Python 3 7 有什麼新功能
@anchor{whatsnew/3 7 porting-to-python-3-7}@anchor{dee}@anchor{whatsnew/3 7 porting-to-python-37}@anchor{cbf}
@subsection 移植至 Python 3.7


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

@menu
* Python 行為的改變: Python 行為的改變<2>. 
* Python API 的變更: Python API 的變更<8>. 
* C API 中的改動: C API 中的改動<6>. 
* CPython 位元組碼變更: CPython 位元組碼變更<8>. 
* Windows-only Changes: Windows-only Changes<2>. 
* Other CPython implementation changes:: 

@end menu

@node Python 行為的改變<2>,Python API 的變更<8>,,移植至 Python 3 7
@anchor{whatsnew/3 7 changes-in-python-behavior}@anchor{def}
@subsubsection Python 行為的改變



@itemize *

@item 
@ref{933,,async} and @ref{18d,,await} names are now reserved keywords.
Code using these names as identifiers will now raise a @ref{18e,,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{df0,,StopIteration} exceptions raised directly or indirectly in
coroutines and generators are transformed into @ref{244,,RuntimeError}
exceptions.
(Contributed by Yury Selivanov in bpo-32670@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32670}.)

@item 
@ref{df1,,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{18e,,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{23c,,-m} switch, the initial working directory is now added
to @ref{3e2,,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 Python API 的變更<8>,C API 中的改動<6>,Python 行為的改變<2>,移植至 Python 3 7
@anchor{whatsnew/3 7 changes-in-the-python-api}@anchor{df2}
@subsubsection Python API 的變更



@itemize *

@item 
@ref{d67,,socketserver.ThreadingMixIn.server_close} now waits until all
non-daemon threads complete.  Set the new
@ref{d68,,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{d67,,socketserver.ForkingMixIn.server_close} now waits until all
child processes complete. Set the new
@ref{d68,,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{df3,,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{df4,,pkgutil.walk_packages()} now raises a @ref{2eb,,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{df5,,string.Formatter.format()}
is now @ref{c6f,,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{df6,,key},
@ref{df7,,value} and
@ref{df8,,coded_value} of class
@ref{df9,,http.cookies.Morsel} are now read-only.
Assigning to them was deprecated in Python 3.5.
Use the @ref{dfa,,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{527,,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{dfb,,struct.Struct.format} type is now @ref{169,,str} instead of
@ref{192,,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{d1,,socket}, calling @ref{dfc,,socket.fromshare()}
on a socket created by @ref{dfd,,socket.share} in older
Python versions is not supported.

@item 
@code{repr} for @ref{7d0,,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{bba,,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{354,,shutil.rmtree()} is now implemented using the @ref{c4b,,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{651,,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{be,,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{651,,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{59d,,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').

（由 Serhiy Storchaka 在 bpo-25054@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25054} 和 bpo-32308@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32308} 中貢獻。）

@item 
Change @ref{dfe,,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{d8a,,tracemalloc.Traceback} frames are now sorted from oldest to most
recent to be more consistent with @ref{104,,traceback}.
(Contributed by Jesse Bakker in bpo-32121@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32121}.)

@item 
On OSes that support @ref{dff,,socket.SOCK_NONBLOCK} or
@ref{e00,,socket.SOCK_CLOEXEC} bit flags, the
@ref{e01,,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{4b2,,subprocess.Popen} was changed from @ref{d23,,False} to @ref{e02,,True}
when redirecting the standard handles. If you previously depended on handles
being inherited when using @ref{4b2,,subprocess.Popen} with standard io
redirection, you will have to pass @code{close_fds=False} to preserve the
previous behaviour, or use
@ref{e03,,STARTUPINFO.lpAttributeList}.

@item 
@ref{e04,,importlib.machinery.PathFinder.invalidate_caches()} -- which implicitly
affects @ref{e05,,importlib.invalidate_caches()} -- now deletes entries
in @ref{7f3,,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{e06,,loop.sock_recv()},
@ref{e07,,loop.sock_sendall()},
@ref{e08,,loop.sock_accept()},
@ref{e09,,loop.getaddrinfo()},
@ref{e0a,,loop.getnameinfo()}
have been changed to be proper coroutine methods to match their
documentation.  Previously, these methods returned @ref{dc1,,asyncio.Future}
instances.
(Contributed by Yury Selivanov in bpo-32327@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32327}.)

@item 
@ref{e0b,,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{dfb,,Struct.format} is now a @ref{169,,str} instance
instead of a @ref{192,,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{e0c,,ArgumentParser.add_subparsers()}.
(Contributed by Anthony Sottile in bpo-26510@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26510}.)

@item 
@ref{e0d,,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{e0e,,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{e0f,,Calendar.itermonthdays3} and
@ref{e10,,Calendar.itermonthdays4} can be used.
The new methods return tuples and are not restricted by the range supported by
@ref{1fa,,datetime.date}.
(Contributed by Alexander Belopolsky in bpo-28292@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28292}.)

@item 
@ref{e11,,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{941,,concurrent.futures.ThreadPoolExecutor}
and @ref{1d6,,concurrent.futures.ProcessPoolExecutor} now raises
a @ref{244,,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{4d9,,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 C API 中的改動<6>,CPython 位元組碼變更<8>,Python API 的變更<8>,移植至 Python 3 7
@anchor{whatsnew/3 7 changes-in-the-c-api}@anchor{e12}
@subsubsection C API 中的改動


The function @ref{42f,,PySlice_GetIndicesEx()} is considered unsafe for
resizable sequences.  If the slice indices are not instances of @ref{19b,,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{430,,PySlice_Unpack()} and
@ref{431,,PySlice_AdjustIndices()}.
(Contributed by Serhiy Storchaka in bpo-27867@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27867}.)

@node CPython 位元組碼變更<8>,Windows-only Changes<2>,C API 中的改動<6>,移植至 Python 3 7
@anchor{whatsnew/3 7 cpython-bytecode-changes}@anchor{e13}
@subsubsection CPython 位元組碼變更


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 位元組碼變更<8>,移植至 Python 3 7
@anchor{whatsnew/3 7 id12}@anchor{e14}
@subsubsection Windows-only Changes


The file used to override @ref{3e2,,sys.path} is now called
@code{<python-executable>._pth} instead of @code{'sys.path'}.
See @ref{e15,,找尋模組} 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>,移植至 Python 3 7
@anchor{whatsnew/3 7 id13}@anchor{e16}
@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{404,,Py_BytesWarningFlag} to a value greater than one is no longer
sufficient to both emit @ref{e17,,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 Python 3 7 1 中顯著的變更,Python 3 7 2 中顯著的變更,移植至 Python 3 7,Python 3 7 有什麼新功能
@anchor{whatsnew/3 7 notable-changes-in-python-3-7-1}@anchor{e18}
@subsection Python 3.7.1 中顯著的變更


Starting in 3.7.1, @ref{45e,,Py_Initialize()} now consistently reads and respects
all of the same environment settings as @ref{e19,,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{408,,Py_IgnoreEnvironmentFlag} to 1 before
calling @ref{45e,,Py_Initialize()}.

In 3.7.1 the C API for Context Variables
@ref{e1a,,was updated} to use
@ref{5d7,,PyObject} pointers.  See also bpo-34762@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34762}.

In 3.7.1 the @ref{101,,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 Python 3 7 2 中顯著的變更,Python 3 7 6 中顯著的變更,Python 3 7 1 中顯著的變更,Python 3 7 有什麼新功能
@anchor{whatsnew/3 7 notable-changes-in-python-3-7-2}@anchor{e1b}
@subsection Python 3.7.2 中顯著的變更


In 3.7.2, @ref{117,,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 Python 3 7 6 中顯著的變更,Python 3 7 10 中顯著的變更,Python 3 7 2 中顯著的變更,Python 3 7 有什麼新功能
@anchor{whatsnew/3 7 notable-changes-in-python-3-7-6}@anchor{e1c}
@subsection Python 3.7.6 中顯著的變更


Due to significant security concerns, the `reuse_address' parameter of
@ref{934,,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 Python 3 7 10 中顯著的變更,Python 3 7 11 中顯著的變更,Python 3 7 6 中顯著的變更,Python 3 7 有什麼新功能
@anchor{whatsnew/3 7 notable-changes-in-python-3-7-10}@anchor{e1d}
@subsection Python 3.7.10 中顯著的變更


Earlier Python versions allowed using both @code{;} and @code{&} as
query parameter separators in @ref{31e,,urllib.parse.parse_qs()} and
@ref{31d,,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 Python 3 7 11 中顯著的變更,Python 3 7 14 中顯著的安全性功能,Python 3 7 10 中顯著的變更,Python 3 7 有什麼新功能
@anchor{whatsnew/3 7 notable-changes-in-python-3-7-11}@anchor{e1e}
@subsection Python 3.7.11 中顯著的變更


A security fix alters the @ref{aed,,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{110,,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 Python 3 7 14 中顯著的安全性功能,,Python 3 7 11 中顯著的變更,Python 3 7 有什麼新功能
@anchor{whatsnew/3 7 notable-security-feature-in-3-7-14}@anchor{e1f}
@subsection Python 3.7.14 中顯著的安全性功能


Converting between @ref{19b,,int} and @ref{169,,str} in bases other than 2
(binary), 4, 8 (octal), 16 (hexadecimal), or 32 such as base 10 (decimal)
now raises a @ref{2eb,,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{df,,sys} APIs. See the @ref{804,,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 Python 3 6 有什麼新功能,Python 3 5 有什麼新功能,Python 3 7 有什麼新功能,Python 有什麼新功能？
@anchor{whatsnew/3 6 doc}@anchor{e20}@anchor{whatsnew/3 6 translation-repo}@anchor{e21}@anchor{whatsnew/3 6 what-s-new-in-python-3-6}@anchor{e22}
@section Python 3.6 有什麼新功能


@*編輯者: 
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.

本文介紹了 Python 3.6 與 3.5 相比多了哪些新功能。Python 3.6 已於 2016 年 12 月 23 日發布。完整詳情請見 changelog@footnote{https://docs.python.org/3.6/whatsnew/changelog.html}。


@subsubheading 也參考


@geindex Python Enhancement Proposals; PEP 494
PEP 494@footnote{https://peps.python.org/pep-0494/} - Python 3.6 發佈時程


@menu
* 發布重點摘要: 發布重點摘要<8>. 
* 新增功能: 新增功能<13>. 
* 其他語言更動: 其他語言更動<8>. 
* 新模組: 新模組<4>. 
* 改進的模組: 改進的模組<8>. 
* 最佳化: 最佳化<9>. 
* 建置和 C API 變更: 建置和 C API 變更<2>. 
* 其他改進:: 
* 已棄用: 已棄用<10>. 
* 已移除: 已移除<8>. 
* 移植至 Python 3.6: 移植至 Python 3 6. 
* Python 3.6.2 中顯著的變更: Python 3 6 2 中顯著的變更. 
* Python 3.6.4 中顯著的變更: Python 3 6 4 中顯著的變更. 
* Python 3.6.5 中顯著的變更: Python 3 6 5 中顯著的變更. 
* Python 3.6.7 中顯著的變更: Python 3 6 7 中顯著的變更. 
* Python 3.6.10 中顯著的變更: Python 3 6 10 中顯著的變更. 
* Python 3.6.13 中顯著的變更: Python 3 6 13 中顯著的變更. 
* Python 3.6.14 中顯著的變更: Python 3 6 14 中顯著的變更. 

@end menu

@node 發布重點摘要<8>,新增功能<13>,,Python 3 6 有什麼新功能
@anchor{whatsnew/3 6 summary-release-highlights}@anchor{e23}
@subsection 發布重點摘要


新增語法特性：


@itemize *

@item 
@ref{e24,,PEP 498}, formatted string literals.

@item 
@ref{e25,,PEP 515}, underscores in numeric literals.

@item 
@ref{e26,,PEP 526}, syntax for variable annotations.

@item 
@ref{e27,,PEP 525}, asynchronous generators.

@item 
@ref{e28,,PEP 530}: asynchronous comprehensions.
@end itemize

新的函式庫模組：


@itemize *

@item 
@ref{c5,,secrets}: @ref{e29,,PEP 506 -- Adding A Secrets Module To The Standard Library}.
@end itemize

CPython 實作改進：


@itemize *

@item 
The @ref{cb4,,dict} type has been reimplemented to use
a @ref{e2a,,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{e2b,,new protocol}.

@item 
The class attribute definition order is
@ref{e2c,,now preserved}.

@item 
The order of elements in @code{**kwargs} now
@ref{e2d,,corresponds to the order} in which keyword
arguments were passed to the function.

@item 
DTrace and SystemTap @ref{e2e,,probing support} has
been added.

@item 
The new @ref{e2f,,PYTHONMALLOC} environment variable
can now be used to debug the interpreter memory allocation and access
errors.
@end itemize

標準函式庫中的顯著改進


@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{e30,,file system path protocol} has been
implemented to support @ref{59b,,path-like objects}.
All standard library functions operating on paths have been updated to
work with the new protocol.

@item 
The @ref{34,,datetime} module has gained support for
@ref{e31,,Local Time Disambiguation}.

@item 
The @ref{10a,,typing} module received a number of
@ref{e32,,improvements}.

@item 
The @ref{105,,tracemalloc} module has been significantly reworked
and is now used to provide better output for @ref{547,,ResourceWarning}
as well as provide better diagnostics for memory allocation errors.
See the @ref{e2f,,PYTHONMALLOC section} for more
information.
@end itemize

安全性改進：


@itemize *

@item 
The new @ref{c5,,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{73f,,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 
@ref{6c,,hashlib} 與 @ref{d5,,ssl} 模組現在支援 OpenSSL 1.1.0。

@item 
The default settings and feature set of the @ref{d5,,ssl} module have been
improved.

@item 
The @ref{6c,,hashlib} module received support for the BLAKE2, SHA-3 and SHAKE
hash algorithms and the @ref{e33,,scrypt()} key derivation function.
@end itemize

Windows 改進：


@itemize *

@item 
@ref{e34,,PEP 528} and @ref{e35,,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{e36,,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{e15,,the documentation} for more information.

@item 
A @code{python36.zip} file now works as a landmark to infer
@geindex PYTHONHOME
@geindex 環境變數; PYTHONHOME
@ref{3ee,,PYTHONHOME}. See @ref{e15,,the documentation} for
more information.
@end itemize

@node 新增功能<13>,其他語言更動<8>,發布重點摘要<8>,Python 3 6 有什麼新功能
@anchor{whatsnew/3 6 new-features}@anchor{e37}@anchor{whatsnew/3 6 pypy-dict-implementation}@anchor{e38}
@subsection 新增功能


@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,,新增功能<13>
@anchor{whatsnew/3 6 pep-498-formatted-string-literals}@anchor{e39}@anchor{whatsnew/3 6 whatsnew36-pep498}@anchor{e24}
@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{19a,,formatted string literals}.

Formatted string literals are prefixed with @code{'f'} and are similar to
the format strings accepted by @ref{82c,,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{199,,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@}@}"  # 巢狀欄位
'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.

由 Eric V. Smith 撰寫 PEP 與實作。
@end table

@ref{19a,,Feature documentation}.


@node PEP 526 Syntax for variable annotations,PEP 515 Underscores in Numeric Literals,PEP 498 Formatted string literals,新增功能<13>
@anchor{whatsnew/3 6 pep-526-syntax-for-variable-annotations}@anchor{e3a}@anchor{whatsnew/3 6 whatsnew36-pep526}@anchor{e26}
@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,新增功能<13>
@anchor{whatsnew/3 6 pep-515-underscores-in-numeric-literals}@anchor{e3b}@anchor{whatsnew/3 6 whatsnew36-pep515}@anchor{e25}
@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{4f4,,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

由 Georg Brandl 與 Serhiy Storchaka 撰寫 PEP。
@end table


@node PEP 525 Asynchronous Generators,PEP 530 Asynchronous Comprehensions,PEP 515 Underscores in Numeric Literals,新增功能<13>
@anchor{whatsnew/3 6 pep-525-asynchronous-generators}@anchor{e3c}@anchor{whatsnew/3 6 whatsnew36-pep525}@anchor{e27}
@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

由 Yury Selivanov 撰寫 PEP 與實作。
@end table


@node PEP 530 Asynchronous Comprehensions,PEP 487 Simpler customization of class creation,PEP 525 Asynchronous Generators,新增功能<13>
@anchor{whatsnew/3 6 pep-530-asynchronous-comprehensions}@anchor{e3d}@anchor{whatsnew/3 6 whatsnew36-pep530}@anchor{e28}
@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

由 Yury Selivanov 撰寫 PEP 與實作。
@end table


@node PEP 487 Simpler customization of class creation,PEP 487 Descriptor Protocol Enhancements,PEP 530 Asynchronous Comprehensions,新增功能<13>
@anchor{whatsnew/3 6 pep-487-simpler-customization-of-class-creation}@anchor{e3e}@anchor{whatsnew/3 6 whatsnew36-pep487}@anchor{e2b}
@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{1a6,,super()} calls to work correctly from
@ref{83c,,__init_subclass__()} implementations, custom metaclasses must
ensure that the new @code{__classcell__} namespace entry is propagated to
@code{type.__new__} (as described in @ref{e3f,,Creating the class object}).


@subsubheading 也參考



@table @asis

@geindex Python Enhancement Proposals; PEP 487

@item PEP 487@footnote{https://peps.python.org/pep-0487/} -- Simpler customization of class creation

由 Martin Teichmann 撰寫 PEP 與實作。
@end table

@ref{e40,,Feature documentation}


@node PEP 487 Descriptor Protocol Enhancements,PEP 519 Adding a file system path protocol,PEP 487 Simpler customization of class creation,新增功能<13>
@anchor{whatsnew/3 6 pep-487-descriptor-protocol-enhancements}@anchor{e41}@anchor{whatsnew/3 6 whatsnew36-pep487-descriptors}@anchor{e42}
@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{e43,,__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

由 Martin Teichmann 撰寫 PEP 與實作。
@end table

@ref{e44,,Feature documentation}


@node PEP 519 Adding a file system path protocol,PEP 495 Local Time Disambiguation,PEP 487 Descriptor Protocol Enhancements,新增功能<13>
@anchor{whatsnew/3 6 pep-519-adding-a-file-system-path-protocol}@anchor{e45}@anchor{whatsnew/3 6 whatsnew36-pep519}@anchor{e30}
@subsubsection PEP 519: Adding a file system path protocol


File system paths have historically been represented as @ref{169,,str}
or @ref{192,,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{19b,,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{e46,,os.PathLike} has been defined. By implementing the
@ref{e47,,__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{169,,str} or
@ref{192,,bytes} object. This means an object is considered
@ref{59b,,path-like} if it implements
@ref{e46,,os.PathLike} or is a @ref{169,,str} or @ref{192,,bytes} object
which represents a file system path. Code can use @ref{e48,,os.fspath()},
@ref{e49,,os.fsdecode()}, or @ref{e4a,,os.fsencode()} to explicitly get a
@ref{169,,str} and/or @ref{192,,bytes} representation of a path-like
object.

The built-in @ref{315,,open()} function has been updated to accept
@ref{e46,,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{6bc,,os.DirEntry} class
and relevant classes in @ref{a8,,pathlib} have also been updated to
implement @ref{e46,,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{59b,,path-like objects} without any
code changes, or at least very minimal ones (e.g. calling
@ref{e48,,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{266,,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

由 Brett Cannon 與 Koos Zevenhoven 撰寫 PEP。
@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,新增功能<13>
@anchor{whatsnew/3 6 pep-495-local-time-disambiguation}@anchor{e4b}@anchor{whatsnew/3 6 whatsnew36-pep495}@anchor{e31}
@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{4dd,,datetime.datetime} and @ref{1fb,,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{e4c,,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,新增功能<13>
@anchor{whatsnew/3 6 pep-529-change-windows-filesystem-encoding-to-utf-8}@anchor{e4d}@anchor{whatsnew/3 6 whatsnew36-pep529}@anchor{e35}
@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{e4e,,sys.getfilesystemencoding()}, which now defaults to @code{'utf-8'}.

Applications that do not use str to represent paths should use
@ref{e4a,,os.fsencode()} and @ref{e49,,os.fsdecode()} to ensure their bytes are
correctly encoded. To revert to the previous behaviour, set
@geindex PYTHONLEGACYWINDOWSFSENCODING
@geindex 環境變數; PYTHONLEGACYWINDOWSFSENCODING
@ref{33e,,PYTHONLEGACYWINDOWSFSENCODING} or call
@ref{33d,,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,新增功能<13>
@anchor{whatsnew/3 6 pep-528-change-windows-console-encoding-to-utf-8}@anchor{e4f}@anchor{whatsnew/3 6 whatsnew36-pep528}@anchor{e34}
@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{e50,,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

由 Steve Dower 撰寫 PEP 與實作。
@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,新增功能<13>
@anchor{whatsnew/3 6 pep-520-preserving-class-attribute-definition-order}@anchor{e51}@anchor{whatsnew/3 6 whatsnew36-pep520}@anchor{e2c}
@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{e52,,__dict__} attribute.

Also, the effective default class `execution' namespace (returned from
@ref{e53,,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

由 Eric Snow 撰寫 PEP 與實作。
@end table


@node PEP 468 Preserving Keyword Argument Order,New dict implementation,PEP 520 Preserving Class Attribute Definition Order,新增功能<13>
@anchor{whatsnew/3 6 pep-468-preserving-keyword-argument-order}@anchor{e54}@anchor{whatsnew/3 6 whatsnew36-pep468}@anchor{e2d}
@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

由 Eric Snow 撰寫 PEP 與實作。
@end table


@node New dict implementation,PEP 523 Adding a frame evaluation API to CPython,PEP 468 Preserving Keyword Argument Order,新增功能<13>
@anchor{whatsnew/3 6 new-dict-implementation}@anchor{e55}@anchor{whatsnew/3 6 whatsnew36-compactdict}@anchor{e2a}
@subsubsection New dict implementation


The @ref{cb4,,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{183,,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,新增功能<13>
@anchor{whatsnew/3 6 pep-523-adding-a-frame-evaluation-api-to-cpython}@anchor{e56}@anchor{whatsnew/3 6 whatsnew36-pep523}@anchor{e57}
@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

由 Brett Cannon 與 Dino Viehland 撰寫 PEP。
@end table


@node PYTHONMALLOC environment variable,DTrace and SystemTap probing support,PEP 523 Adding a frame evaluation API to CPython,新增功能<13>
@anchor{whatsnew/3 6 pythonmalloc-environment-variable}@anchor{e58}@anchor{whatsnew/3 6 whatsnew36-pythonmalloc}@anchor{e2f}
@subsubsection PYTHONMALLOC environment variable


The new 
@geindex PYTHONMALLOC
@geindex 環境變數; PYTHONMALLOC
@ref{e59,,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{e5a,,PyObject_Free()} called on a memory block allocated by
@ref{e5b,,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{46e,,GIL} is held when allocator
functions of @ref{e5c,,PYMEM_DOMAIN_OBJ} (ex: @ref{e5d,,PyObject_Malloc()}) and
@ref{e5e,,PYMEM_DOMAIN_MEM} (ex: @ref{e5b,,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{e5f,,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{105,,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

（由 Victor Stinner 於 bpo-26516@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26516} 和 bpo-26564@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26564} 中貢獻。）

@node DTrace and SystemTap probing support,,PYTHONMALLOC environment variable,新增功能<13>
@anchor{whatsnew/3 6 dtrace-and-systemtap-probing-support}@anchor{e60}@anchor{whatsnew/3 6 whatsnew36-tracing}@anchor{e2e}
@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{504,,debug builds} or
providing application-specific profiling/debugging code.

More details in @ref{e61,,使用 DTrace 和 SystemTap 檢測 CPython}.

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 其他語言更動<8>,新模組<4>,新增功能<13>,Python 3 6 有什麼新功能
@anchor{whatsnew/3 6 other-language-changes}@anchor{e62}
@subsection 其他語言更動


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{1ae,,SyntaxWarning}.

@item 
It is now possible to set a @ref{e63,,special method} to
@code{None} to indicate that the corresponding operation is not available.
For example, if a class sets @ref{e64,,__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{e65,,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{d35,,ModuleNotFoundError}
(subclass of @ref{653,,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 新模組<4>,改進的模組<8>,其他語言更動<8>,Python 3 6 有什麼新功能
@anchor{whatsnew/3 6 new-modules}@anchor{e66}
@subsection 新模組


@menu
* secrets:: 

@end menu

@node secrets,,,新模組<4>
@anchor{whatsnew/3 6 secrets}@anchor{e67}@anchor{whatsnew/3 6 whatsnew36-pep506}@anchor{e29}
@subsubsection secrets


The main purpose of the new @ref{c5,,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{bd,,random} module
should `NOT' be used for security purposes.  Use @ref{c5,,secrets}
on Python 3.6+ and @ref{73f,,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

由 Steven D'Aprano 撰寫 PEP 與實作。
@end table


@node 改進的模組<8>,最佳化<9>,新模組<4>,Python 3 6 有什麼新功能
@anchor{whatsnew/3 6 improved-modules}@anchor{e68}
@subsection 改進的模組


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

@end menu

@node array<4>,ast<6>,,改進的模組<8>
@anchor{whatsnew/3 6 array}@anchor{e69}
@subsubsection array


Exhausted iterators of @ref{4b9,,array.array} will now stay exhausted even
if the iterated array is extended.  This is consistent with the behavior
of other mutable sequences.

由 Serhiy Storchaka 於 bpo-26492@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26492} 中貢獻。

@node ast<6>,asyncio<12>,array<4>,改進的模組<8>
@anchor{whatsnew/3 6 ast}@anchor{e6a}
@subsubsection ast


The new @ref{2ee,,ast.Constant} AST node has been added.  It can be used
by external AST optimizers for the purposes of constant folding.

由 Victor Stinner 於 bpo-26146@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26146} 中貢獻。

@node asyncio<12>,binascii<2>,ast<6>,改進的模組<8>
@anchor{whatsnew/3 6 asyncio}@anchor{e6b}
@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{2f1,,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{e6c,,ensure_future()} function and all functions that
use it, such as @ref{e6d,,loop.run_until_complete()},
now accept all kinds of @ref{4c4,,awaitable objects}.
(Contributed by Yury Selivanov.)

@item 
New @ref{a79,,run_coroutine_threadsafe()} function to submit
coroutines to event loops from other threads.
(Contributed by Vincent Michel.)

@item 
New @ref{e6e,,Transport.is_closing()}
method to check if the transport is closing or closed.
(Contributed by Yury Selivanov.)

@item 
The @ref{d01,,loop.create_server()}
method can now accept a list of hosts.
(Contributed by Yann Sionneau.)

@item 
New @ref{e6f,,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{dc1,,asyncio.Future} implementation.
(Contributed by Yury Selivanov in bpo-27041@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27041}.)

@item 
New @ref{e70,,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{4cb,,StreamReader.readuntil()}
method to read data from the stream until a separator bytes
sequence appears.
(Contributed by Mark Korenberg.)

@item 
The performance of @ref{e71,,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{e09,,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{e72,,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{e73,,Future.set_exception}
will now raise @ref{198,,TypeError} when passed an instance of
the @ref{df0,,StopIteration} exception.
(Contributed by Chris Angelico in bpo-26221@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26221}.)

@item 
New @ref{9d7,,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{e74,,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{dc1,,Future} and @ref{1c7,,Task}
classes now have an optimized C implementation which makes asyncio
code up to 30% faster.
(Contributed by Yury Selivanov and INADA Naoki in bpo-26081@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26081}
and bpo-28544@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28544}.)
@end itemize

@node binascii<2>,cmath,asyncio<12>,改進的模組<8>
@anchor{whatsnew/3 6 binascii}@anchor{e75}
@subsubsection binascii


The @ref{e76,,b2a_base64()} function now accepts an optional `newline'
keyword argument to control whether the newline character is appended to the
return value.
(Contributed by Victor Stinner in bpo-25357@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25357}.)

@node cmath,collections<4>,binascii<2>,改進的模組<8>
@anchor{whatsnew/3 6 cmath}@anchor{e77}
@subsubsection cmath


The new @ref{e78,,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{e79,,cmath.inf} and @ref{e7a,,cmath.nan} to
match @ref{e7b,,math.inf} and @ref{86c,,math.nan}, and also @ref{e7c,,cmath.infj}
and @ref{e7d,,cmath.nanj} to match the format used by complex repr.
(Contributed by Mark Dickinson in bpo-23229@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23229}.)

@node collections<4>,concurrent futures<5>,cmath,改進的模組<8>
@anchor{whatsnew/3 6 collections}@anchor{e7e}
@subsubsection collections


The new @ref{e7f,,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{e80,,Reversible} abstract base class represents
iterable classes that also provide the @ref{e81,,__reversed__()} method.
(Contributed by Ivan Levkivskyi in bpo-25987@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25987}.)

The new @ref{e82,,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{4db,,namedtuple()} function now accepts an optional
keyword argument `module', which, when specified, is used for
the @ref{60f,,__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{4db,,namedtuple()} are now keyword-only.
(Contributed by Raymond Hettinger in bpo-25628@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25628}.)

Recursive @ref{7ed,,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<5>,contextlib<4>,collections<4>,改進的模組<8>
@anchor{whatsnew/3 6 concurrent-futures}@anchor{e83}
@subsubsection concurrent.futures


The @ref{941,,ThreadPoolExecutor}
class constructor now accepts an optional `thread_name_prefix' argument
to make it possible to customize the names of the threads created by the
pool.
(Contributed by Gregory P. Smith in bpo-27664@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27664}.)

@node contextlib<4>,datetime<6>,concurrent futures<5>,改進的模組<8>
@anchor{whatsnew/3 6 contextlib}@anchor{e84}
@subsubsection contextlib


The @ref{e85,,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{10a,,typing} module as
@ref{e86,,typing.ContextManager}.
(Contributed by Brett Cannon in bpo-25609@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25609}.)

@node datetime<6>,decimal<3>,contextlib<4>,改進的模組<8>
@anchor{whatsnew/3 6 datetime}@anchor{e87}
@subsubsection datetime


The @ref{4dd,,datetime} and @ref{1fb,,time} classes have
the new @ref{e88,,fold} attribute used to disambiguate local time
when necessary.  Many functions in the @ref{34,,datetime} have been
updated to support local time disambiguation.
See @ref{e31,,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{e89,,datetime.strftime()} and
@ref{e8a,,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{d1d,,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{e8b,,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<6>,改進的模組<8>
@anchor{whatsnew/3 6 decimal}@anchor{e8c}
@subsubsection decimal


New @ref{e8d,,Decimal.as_integer_ratio()}
method that returns a pair @code{(n, d)} of integers that represent the given
@ref{1fe,,Decimal} instance as a fraction, in lowest terms and
with a positive denominator:

@example
>>> Decimal('-3.14').as_integer_ratio()
(-157, 50)
@end example

（由 Stefan Krah 和 Mark Dickinson 於 bpo-25928@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25928} 中貢獻。）

@node distutils<5>,email<3>,decimal<3>,改進的模組<8>
@anchor{whatsnew/3 6 distutils}@anchor{e8e}
@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<3>,encodings<2>,distutils<5>,改進的模組<8>
@anchor{whatsnew/3 6 email}@anchor{e8f}
@subsubsection email


The new email API, enabled via the `policy' keyword to various constructors, is
no longer provisional.  The @ref{3f,,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{49,,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{e90,,DecodedGenerator} now supports the `policy'
keyword.

There is a new @ref{53,,policy} attribute,
@ref{e91,,message_factory}, that controls what class is used
by default when the parser creates new message objects.  For the
@ref{e92,,email.policy.compat32} policy this is @ref{57b,,Message},
for the new policies it is @ref{57a,,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<3>,改進的模組<8>
@anchor{whatsnew/3 6 encodings}@anchor{e93}
@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<3>,encodings<2>,改進的模組<8>
@anchor{whatsnew/3 6 enum}@anchor{e94}
@subsubsection enum


Two new enumeration base classes have been added to the @ref{5a,,enum} module:
@ref{82e,,Flag} and @ref{e95,,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{e95,,IntFlag} class for their constants.

The new @ref{e96,,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<3>,fileinput<2>,enum<7>,改進的模組<8>
@anchor{whatsnew/3 6 faulthandler}@anchor{e97}
@subsubsection faulthandler


On Windows, the @ref{5c,,faulthandler} module now installs a handler for Windows
exceptions: see @ref{20f,,faulthandler.enable()}. (Contributed by Victor Stinner in
bpo-23848@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23848}.)

@node fileinput<2>,hashlib<5>,faulthandler<3>,改進的模組<8>
@anchor{whatsnew/3 6 fileinput}@anchor{e98}
@subsubsection fileinput


@ref{e99,,hook_encoded()} now supports the `errors' argument.
(Contributed by Joseph Hackman in bpo-25788@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25788}.)

@node hashlib<5>,http client<2>,fileinput<2>,改進的模組<8>
@anchor{whatsnew/3 6 hashlib}@anchor{e9a}
@subsubsection hashlib


@ref{6c,,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{84b,,blake2b()}
and @ref{84c,,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{e9b,,sha3_224()}, @ref{e9c,,sha3_256()},
@ref{e9d,,sha3_384()}, @ref{e9e,,sha3_512()}, and SHAKE hash functions
@ref{e9f,,shake_128()} and @ref{ea0,,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{e33,,scrypt()} is now
available with OpenSSL 1.1.0 and newer.
(Contributed by Christian Heimes in bpo-27928@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27928}.)

@node http client<2>,idlelib 與 IDLE<2>,hashlib<5>,改進的模組<8>
@anchor{whatsnew/3 6 http-client}@anchor{ea1}
@subsubsection http.client


@ref{ea2,,HTTPConnection.request()} and
@ref{ea3,,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 與 IDLE<2>,importlib<6>,http client<2>,改進的模組<8>
@anchor{whatsnew/3 6 idlelib-and-idle}@anchor{ea4}
@subsubsection idlelib 與 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<7>,idlelib 與 IDLE<2>,改進的模組<8>
@anchor{whatsnew/3 6 importlib}@anchor{ea5}
@subsubsection importlib


Import now raises the new exception @ref{d35,,ModuleNotFoundError}
(subclass of @ref{653,,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{ea6,,importlib.util.LazyLoader} now calls
@ref{ea7,,create_module()} on the wrapped loader, removing the
restriction that @ref{ea8,,importlib.machinery.BuiltinImporter} and
@ref{ea9,,importlib.machinery.ExtensionFileLoader} couldn't be used with
@ref{ea6,,importlib.util.LazyLoader}.

@ref{351,,importlib.util.cache_from_source()},
@ref{737,,importlib.util.source_from_cache()}, and
@ref{eaa,,importlib.util.spec_from_file_location()} now accept a
@ref{59b,,path-like object}.

@node inspect<7>,json<2>,importlib<6>,改進的模組<8>
@anchor{whatsnew/3 6 inspect}@anchor{eab}
@subsubsection inspect


The @ref{22f,,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{939,,inspect.getfullargspec()} has been reversed. While this function is
convenient for single/source Python 2/3 code bases, the richer
@ref{22f,,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<2>,logging<4>,inspect<7>,改進的模組<8>
@anchor{whatsnew/3 6 json}@anchor{eac}
@subsubsection json


@ref{ead,,json.load()} and @ref{b45,,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<8>,json<2>,改進的模組<8>
@anchor{whatsnew/3 6 logging}@anchor{eae}
@subsubsection logging


The new @ref{eaf,,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<8>,multiprocessing<6>,logging<4>,改進的模組<8>
@anchor{whatsnew/3 6 math}@anchor{eb0}
@subsubsection math


The tau (`τ') constant has been added to the @ref{92,,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<9>,math<8>,改進的模組<8>
@anchor{whatsnew/3 6 multiprocessing}@anchor{eb1}
@subsubsection multiprocessing


@ref{24c,,Proxy Objects} returned by
@ref{250,,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<9>,pathlib<12>,multiprocessing<6>,改進的模組<8>
@anchor{whatsnew/3 6 os}@anchor{eb2}
@subsubsection os


See the summary of @ref{e30,,PEP 519} for details on how the
@ref{a5,,os} and @ref{a6,,os.path} modules now support
@ref{59b,,path-like objects}.

@ref{c4b,,scandir()} now supports @ref{192,,bytes} paths on Windows.

A new @ref{eb3,,close()} method allows explicitly closing a
@ref{c4b,,scandir()} iterator.  The @ref{c4b,,scandir()} iterator now
supports the @ref{1e1,,context manager} protocol.  If a @code{scandir()}
iterator is neither exhausted nor explicitly closed a @ref{547,,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{73f,,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{eb4,,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<12>,pdb<7>,os<9>,改進的模組<8>
@anchor{whatsnew/3 6 pathlib}@anchor{eb5}
@subsubsection pathlib


@ref{a8,,pathlib} now supports @ref{59b,,path-like objects}.
(Contributed by Brett Cannon in bpo-27186@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27186}.)

細節請見 @ref{e30,,PEP 519} 中的摘要。

@node pdb<7>,pickle<3>,pathlib<12>,改進的模組<8>
@anchor{whatsnew/3 6 pdb}@anchor{eb6}
@subsubsection pdb


The @ref{273,,Pdb} class constructor has a new optional `readrc' argument
to control whether @code{.pdbrc} files should be read.

@node pickle<3>,pickletools,pdb<7>,改進的模組<8>
@anchor{whatsnew/3 6 pickle}@anchor{eb7}
@subsubsection pickle


Objects that need @code{__new__} called with keyword arguments can now be pickled
using @ref{27b,,pickle protocols} older than protocol version 4.
Protocol version 4 already supports this case.  (Contributed by Serhiy
Storchaka in bpo-24164@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24164}.)

@node pickletools,pydoc<4>,pickle<3>,改進的模組<8>
@anchor{whatsnew/3 6 pickletools}@anchor{eb8}
@subsubsection pickletools


@ref{eb9,,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,改進的模組<8>
@anchor{whatsnew/3 6 pydoc}@anchor{eba}
@subsubsection pydoc


The @ref{ba,,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{acb,,help()} and @ref{ba,,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<6>,pydoc<4>,改進的模組<8>
@anchor{whatsnew/3 6 random}@anchor{ebb}
@subsubsection random


The new @ref{ebc,,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<6>,readline,random<4>,改進的模組<8>
@anchor{whatsnew/3 6 re}@anchor{ebd}
@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{ebe,,Match} objects now support
@ref{19e,,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<6>,改進的模組<8>
@anchor{whatsnew/3 6 readline}@anchor{ebf}
@subsubsection readline


Added @ref{ec0,,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,改進的模組<8>
@anchor{whatsnew/3 6 rlcompleter}@anchor{ec1}
@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,改進的模組<8>
@anchor{whatsnew/3 6 shlex}@anchor{ec2}
@subsubsection shlex


The @ref{ec3,,shlex} has much
@ref{ec4,,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<8>,shlex<2>,改進的模組<8>
@anchor{whatsnew/3 6 site}@anchor{ec5}
@subsubsection site


When specifying paths to add to @ref{3e2,,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<8>,socket<8>,site<3>,改進的模組<8>
@anchor{whatsnew/3 6 sqlite3}@anchor{ec6}
@subsubsection sqlite3


@ref{ec7,,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<8>,socketserver<2>,sqlite3<8>,改進的模組<8>
@anchor{whatsnew/3 6 socket}@anchor{ec8}
@subsubsection socket


The @ref{ec9,,ioctl()} function now supports the
@ref{eca,,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{ecb,,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{ecc,,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{ecd,,AF_ALG} to interface with Linux Kernel crypto API. @code{ALG_*},
@code{SOL_ALG} and @ref{ece,,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<8>,socket<8>,改進的模組<8>
@anchor{whatsnew/3 6 socketserver}@anchor{ecf}
@subsubsection socketserver


Servers based on the @ref{d2,,socketserver} module, including those
defined in @ref{76,,http.server}, @ref{135,,xmlrpc.server} and
@ref{121,,wsgiref.simple_server}, now support the @ref{1e1,,context manager}
protocol.
(Contributed by Aviv Palivoda in bpo-26404@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26404}.)

The @ref{ed0,,wfile} attribute of
@ref{ed1,,StreamRequestHandler} classes now implements
the @ref{89c,,io.BufferedIOBase} writable interface.  In particular,
calling @ref{ed2,,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<8>,statistics<5>,socketserver<2>,改進的模組<8>
@anchor{whatsnew/3 6 ssl}@anchor{ed3}
@subsubsection ssl


@ref{d5,,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{355,,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{ed4,,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{ed5,,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{ed6,,IntEnum} and
@ref{e95,,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{355,,SSLContext}
were added.
(Contributed by Christian Heimes in bpo-28085@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28085}.)

Added @ref{c1d,,ssl.SSLContext.post_handshake_auth} to enable and
@ref{c1e,,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<8>,改進的模組<8>
@anchor{whatsnew/3 6 statistics}@anchor{ed7}
@subsubsection statistics


A new @ref{ed8,,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<3>,statistics<5>,改進的模組<8>
@anchor{whatsnew/3 6 struct}@anchor{ed9}
@subsubsection struct


@ref{db,,struct} now supports IEEE 754 half-precision floats via the @code{'e'}
format specifier.
(Contributed by Eli Stevens, Mark Dickinson in bpo-11734@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11734}.)

@node subprocess<3>,sys<10>,struct<2>,改進的模組<8>
@anchor{whatsnew/3 6 subprocess}@anchor{eda}
@subsubsection subprocess


@ref{4b2,,subprocess.Popen} destructor now emits a @ref{547,,ResourceWarning} warning
if the child process is still running. Use the context manager protocol (@code{with
proc: ...}) or explicitly call the @ref{edb,,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{4b2,,subprocess.Popen} constructor and all functions that pass arguments
through to it now accept `encoding' and `errors' arguments. Specifying either
of these will enable text mode for the `stdin', `stdout' and `stderr' streams.
(Contributed by Steve Dower in bpo-6135@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6135}.)

@node sys<10>,telnetlib,subprocess<3>,改進的模組<8>
@anchor{whatsnew/3 6 sys}@anchor{edc}
@subsubsection sys


The new @ref{edd,,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{ede,,getwindowsversion()} function
now includes the `platform_version' field which contains the accurate major
version, minor version and build number of the current operating system,
rather than the version that is being emulated for the process
(Contributed by Steve Dower in bpo-27932@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27932}.)

@node telnetlib,time<6>,sys<10>,改進的模組<8>
@anchor{whatsnew/3 6 telnetlib}@anchor{edf}
@subsubsection telnetlib


@code{telnetlib.Telnet} is now a context manager (contributed by
Stéphane Wirtel in bpo-25485@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25485}).

@node time<6>,timeit,telnetlib,改進的模組<8>
@anchor{whatsnew/3 6 time}@anchor{ee0}
@subsubsection time


The @ref{ee1,,struct_time} attributes @code{tm_gmtoff} and
@code{tm_zone} are now available on all platforms.

@node timeit,tkinter<7>,time<6>,改進的模組<8>
@anchor{whatsnew/3 6 timeit}@anchor{ee2}
@subsubsection timeit


The new @ref{ee3,,Timer.autorange()} convenience
method has been added to call @ref{ee4,,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{f5,,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<7>,traceback<4>,timeit,改進的模組<8>
@anchor{whatsnew/3 6 tkinter}@anchor{ee5}
@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<7>,改進的模組<8>
@anchor{whatsnew/3 6 traceback}@anchor{ee6}@anchor{whatsnew/3 6 whatsnew36-traceback}@anchor{e65}
@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

（由 Emanuel Barry 於 bpo-26823@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26823} 中貢獻。）

@node tracemalloc<3>,typing<10>,traceback<4>,改進的模組<8>
@anchor{whatsnew/3 6 tracemalloc}@anchor{ee7}
@subsubsection tracemalloc


The @ref{105,,tracemalloc} module now supports tracing memory allocations in
multiple different address spaces.

The new @ref{ee8,,DomainFilter} filter class has been added
to filter block traces by their address space (domain).

（由 Victor Stinner 於 bpo-26588@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26588} 中貢獻。）

@node typing<10>,unicodedata<8>,tracemalloc<3>,改進的模組<8>
@anchor{whatsnew/3 6 typing}@anchor{ee9}@anchor{whatsnew/3 6 whatsnew36-typing}@anchor{e32}
@subsubsection typing


Since the @ref{10a,,typing} module is @ref{3cf,,provisional},
all changes introduced in Python 3.6 have also been
backported to Python 3.5.x.

The @ref{10a,,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{e86,,typing.ContextManager} class has been added for
representing @ref{e85,,contextlib.AbstractContextManager}.
(Contributed by Brett Cannon in bpo-25609@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25609}.)

The @ref{eea,,typing.Collection} class has been added for
representing @ref{e7f,,collections.abc.Collection}.
(Contributed by Ivan Levkivskyi in bpo-27598@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27598}.)

The @ref{567,,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{eeb,,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{eec,,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<8>,unittest mock<2>,typing<10>,改進的模組<8>
@anchor{whatsnew/3 6 unicodedata}@anchor{eed}
@subsubsection unicodedata


The @ref{10b,,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<8>,改進的模組<8>
@anchor{whatsnew/3 6 unittest-mock}@anchor{eee}
@subsubsection unittest.mock


@ref{c36,,Mock} 類別有以下改進：


@itemize *

@item 
Two new methods, @ref{eef,,Mock.assert_called()} and @ref{ef0,,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{ef1,,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>,改進的模組<8>
@anchor{whatsnew/3 6 urllib-request}@anchor{ef2}
@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{ef3,,AbstractHTTPHandler}
now falls back to use chunked transfer encoding.
(Contributed by Demian Brecht and Rolf Krahl in bpo-12319@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12319}.)

@node urllib robotparser,venv<5>,urllib request,改進的模組<8>
@anchor{whatsnew/3 6 urllib-robotparser}@anchor{ef4}
@subsubsection urllib.robotparser


@ref{ef5,,RobotFileParser} now supports the @code{Crawl-delay} and
@code{Request-rate} extensions.
(Contributed by Nikolay Bogoychev in bpo-16099@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16099}.)

@node venv<5>,warnings<4>,urllib robotparser,改進的模組<8>
@anchor{whatsnew/3 6 venv}@anchor{ef6}
@subsubsection venv


@ref{117,,venv} accepts a new parameter @code{--prompt}. This parameter provides an
alternative prefix for the virtual environment. (Proposed by Łukasz Balcerzak
and ported to 3.6 by Stéphane Wirtel in bpo-22829@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22829}.)

@node warnings<4>,winreg,venv<5>,改進的模組<8>
@anchor{whatsnew/3 6 warnings}@anchor{ef7}
@subsubsection warnings


A new optional `source' parameter has been added to the
@ref{ef8,,warnings.warn_explicit()} function: the destroyed object which emitted a
@ref{547,,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{547,,ResourceWarning} warning is logged, the @ref{105,,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{105,,tracemalloc} is tracing Python memory allocations and if the
@ref{118,,warnings} module was already imported.

@node winreg,winsound,warnings<4>,改進的模組<8>
@anchor{whatsnew/3 6 winreg}@anchor{ef9}
@subsubsection winreg


Added the 64-bit integer type @ref{efa,,REG_QWORD}.
(Contributed by Clement Rouault in bpo-23026@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23026}.)

@node winsound,xmlrpc client,winreg,改進的模組<8>
@anchor{whatsnew/3 6 winsound}@anchor{efb}
@subsubsection winsound


Allowed keyword arguments to be passed to @ref{efc,,Beep},
@ref{efd,,MessageBeep}, and @ref{efe,,PlaySound} (bpo-27982@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27982}).

@node xmlrpc client,zipfile<4>,winsound,改進的模組<8>
@anchor{whatsnew/3 6 xmlrpc-client}@anchor{eff}
@subsubsection xmlrpc.client


The @ref{134,,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<2>,xmlrpc client,改進的模組<8>
@anchor{whatsnew/3 6 zipfile}@anchor{f00}
@subsubsection zipfile


A new @ref{f01,,ZipInfo.from_file()} class method
allows making a @ref{2cb,,ZipInfo} instance from a filesystem file.
A new @ref{f02,,ZipInfo.is_dir()} method can be used
to check if the @ref{2cb,,ZipInfo} instance represents a directory.
(Contributed by Thomas Kluyver in bpo-26039@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26039}.)

The @ref{655,,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<2>,,zipfile<4>,改進的模組<8>
@anchor{whatsnew/3 6 zlib}@anchor{f03}
@subsubsection zlib


The @ref{848,,compress()} and @ref{f04,,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 最佳化<9>,建置和 C API 變更<2>,改進的模組<8>,Python 3 6 有什麼新功能
@anchor{whatsnew/3 6 optimizations}@anchor{f05}
@subsection 最佳化



@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{dc1,,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{1c7,,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{10a,,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{190,,bytes.fromhex()} and @ref{191,,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{e5b,,PyMem_Malloc()} domain
(@ref{e5e,,PYMEM_DOMAIN_MEM}) now use the @ref{f06,,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{f07,,pickle.load()} and @ref{f08,,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{f09,,keyword arguments} to a function has an
overhead in comparison with passing @ref{f0a,,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{59a,,glob()} and @ref{a01,,iglob()} functions in the
@ref{68,,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{c4b,,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{12b,,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{213,,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 建置和 C API 變更<2>,其他改進,最佳化<9>,Python 3 6 有什麼新功能
@anchor{whatsnew/3 6 build-and-c-api-changes}@anchor{f0b}
@subsection 建置和 C API 變更



@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{46e,,GIL} must now be held when allocator
functions of @ref{e5c,,PYMEM_DOMAIN_OBJ} (ex: @ref{e5d,,PyObject_Malloc()}) and
@ref{e5e,,PYMEM_DOMAIN_MEM} (ex: @ref{e5b,,PyMem_Malloc()}) domains are called.

@item 
New @ref{f0c,,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{61c,,PyArg_ParseTupleAndKeywords()} now supports @ref{c6f,,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{f0d,,PyErr_SetImportErrorSubclass()} function allows for
specifying a subclass of @ref{653,,ImportError} to raise.
(Contributed by Eric Snow in bpo-15767@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15767}.)

@item 
The new @ref{f0e,,PyErr_ResourceWarning()} function can be used to generate
a @ref{547,,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{f0f,,PyOS_FSPath()} function returns the file system
representation of a @ref{59b,,path-like object}.
(Contributed by Brett Cannon in bpo-27186@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27186}.)

@item 
The @ref{f10,,PyUnicode_FSConverter()} and @ref{790,,PyUnicode_FSDecoder()}
functions will now accept @ref{59b,,path-like objects}.
@end itemize

@node 其他改進,已棄用<10>,建置和 C API 變更<2>,Python 3 6 有什麼新功能
@anchor{whatsnew/3 6 other-improvements}@anchor{f11}
@subsection 其他改進



@itemize *

@item 
When @ref{f12,,--version} (short form: @ref{496,,-V}) is supplied twice,
Python prints @ref{497,,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 已棄用<10>,已移除<8>,其他改進,Python 3 6 有什麼新功能
@anchor{whatsnew/3 6 deprecated}@anchor{f13}
@subsection 已棄用


@menu
* 新關鍵字:: 
* 已棄用的 Python 行為: 已棄用的 Python 行為<2>. 
* 已棄用的 Python 模組、函式和方法: 已棄用的 Python 模組、函式和方法<2>. 
* xml: xml<6>. 
* C API 的已棄用函式和型別:: 
* 已棄用的建置選項:: 

@end menu

@node 新關鍵字,已棄用的 Python 行為<2>,,已棄用<10>
@anchor{whatsnew/3 6 new-keywords}@anchor{f14}
@subsubsection 新關鍵字


@code{async} and @code{await} are not recommended to be used as variable, class,
function or module names.  Introduced by 
@geindex Python Enhancement Proposals; PEP 492
PEP 492@footnote{https://peps.python.org/pep-0492/} in Python 3.5, they will
become proper keywords in Python 3.7.  Starting in Python 3.6, the use of
@code{async} or @code{await} as names will generate a @ref{1a3,,DeprecationWarning}.

@node 已棄用的 Python 行為<2>,已棄用的 Python 模組、函式和方法<2>,新關鍵字,已棄用<10>
@anchor{whatsnew/3 6 deprecated-python-behavior}@anchor{f15}
@subsubsection 已棄用的 Python 行為


Raising the @ref{df0,,StopIteration} exception inside a generator will now
generate a @ref{1a3,,DeprecationWarning}, and will trigger a @ref{244,,RuntimeError}
in Python 3.7.  See @ref{f16,,PEP 479; Change StopIteration handling inside generators} for details.

The @ref{df1,,__aiter__()} method is now expected to return an asynchronous
iterator directly instead of returning an awaitable as previously.
Doing the former will trigger a @ref{1a3,,DeprecationWarning}.  Backward
compatibility will be removed in Python 3.7.
(Contributed by Yury Selivanov in bpo-27243@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27243}.)

A backslash-character pair that is not a valid escape sequence now generates
a @ref{1a3,,DeprecationWarning}.  Although this will eventually become a
@ref{18e,,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{717,,ImportWarning}.
(Contributed by Rose Ames in bpo-25791@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25791}.)

@node 已棄用的 Python 模組、函式和方法<2>,xml<6>,已棄用的 Python 行為<2>,已棄用<10>
@anchor{whatsnew/3 6 deprecated-python-modules-functions-and-methods}@anchor{f17}
@subsubsection 已棄用的 Python 模組、函式和方法


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

@end menu

@node asynchat,asyncore,,已棄用的 Python 模組、函式和方法<2>
@anchor{whatsnew/3 6 asynchat}@anchor{f18}
@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<4>,asynchat,已棄用的 Python 模組、函式和方法<2>
@anchor{whatsnew/3 6 asyncore}@anchor{f19}
@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<4>,distutils<6>,asyncore,已棄用的 Python 模組、函式和方法<2>
@anchor{whatsnew/3 6 dbm}@anchor{f1a}
@subsubsection dbm


Unlike other @ref{35,,dbm} implementations, the @ref{36,,dbm.dumb} module
creates databases with the @code{'rw'} mode and allows modifying the database
opened with the @code{'r'} mode.  This behavior is now deprecated and will
be removed in 3.8.
(Contributed by Serhiy Storchaka in bpo-21708@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21708}.)

@node distutils<6>,grp,dbm<4>,已棄用的 Python 模組、函式和方法<2>
@anchor{whatsnew/3 6 id2}@anchor{f1b}
@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>,已棄用的 Python 模組、函式和方法<2>
@anchor{whatsnew/3 6 grp}@anchor{f1c}
@subsubsection grp


The support of non-integer arguments in @ref{f1d,,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<10>,grp,已棄用的 Python 模組、函式和方法<2>
@anchor{whatsnew/3 6 id3}@anchor{f1e}
@subsubsection importlib


The @ref{f1f,,importlib.machinery.SourceFileLoader.load_module()} and
@ref{f20,,importlib.machinery.SourcelessFileLoader.load_module()} methods
are now deprecated. They were the only remaining implementations of
@ref{a62,,importlib.abc.Loader.load_module()} in @ref{7b,,importlib} that had not
been deprecated in previous versions of Python in favour of
@ref{a63,,importlib.abc.Loader.exec_module()}.

The @ref{f21,,importlib.machinery.WindowsRegistryFinder} class is now
deprecated. As of 3.6.0, it is still added to @ref{f22,,sys.meta_path} by
default (on Windows), but this may change in future releases.

@node os<10>,re<7>,importlib<7>,已棄用的 Python 模組、函式和方法<2>
@anchor{whatsnew/3 6 id4}@anchor{f23}
@subsubsection os


Undocumented support of general @ref{193,,bytes-like objects}
as paths in @ref{a5,,os} functions, @ref{4ac,,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<7>,ssl<9>,os<10>,已棄用的 Python 模組、函式和方法<2>
@anchor{whatsnew/3 6 id5}@anchor{f24}
@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<9>,tkinter<8>,re<7>,已棄用的 Python 模組、函式和方法<2>
@anchor{whatsnew/3 6 id6}@anchor{f25}
@subsubsection ssl


OpenSSL 0.9.8, 1.0.0 and 1.0.1 are deprecated and no longer supported.
In the future the @ref{d5,,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{62,,ftplib}, @ref{73,,http.client}, @ref{78,,imaplib}, @ref{b1,,poplib},
and @ref{cf,,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{d5,,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<8>,venv<6>,ssl<9>,已棄用的 Python 模組、函式和方法<2>
@anchor{whatsnew/3 6 id7}@anchor{f26}
@subsubsection tkinter


The @code{tkinter.tix} module is now deprecated.  @ref{f6,,tkinter} users
should use @ref{ff,,tkinter.ttk} instead.

@node venv<6>,,tkinter<8>,已棄用的 Python 模組、函式和方法<2>
@anchor{whatsnew/3 6 id8}@anchor{f27}@anchor{whatsnew/3 6 whatsnew36-venv}@anchor{f28}
@subsubsection venv


The @code{pyvenv} script has been deprecated in favour of @code{python3 -m venv}.
This prevents confusion as to what Python interpreter @code{pyvenv} is
connected to and thus what Python interpreter will be used by the virtual
environment.  (Contributed by Brett Cannon in bpo-25154@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25154}.)

@node xml<6>,C API 的已棄用函式和型別,已棄用的 Python 模組、函式和方法<2>,已棄用<10>
@anchor{whatsnew/3 6 xml}@anchor{f29}
@subsubsection xml



@itemize *

@item 
As mitigation against DTD and external entity retrieval, the
@ref{128,,xml.dom.minidom} and @ref{12f,,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 C API 的已棄用函式和型別,已棄用的建置選項,xml<6>,已棄用<10>
@anchor{whatsnew/3 6 deprecated-functions-and-types-of-the-c-api}@anchor{f2a}
@subsubsection C API 的已棄用函式和型別


Undocumented functions @code{PyUnicode_AsEncodedObject()},
@code{PyUnicode_AsDecodedObject()}, @code{PyUnicode_AsEncodedUnicode()}
and @code{PyUnicode_AsDecodedUnicode()} are deprecated now.
Use the @ref{f2b,,generic codec based API} instead.

@node 已棄用的建置選項,,C API 的已棄用函式和型別,已棄用<10>
@anchor{whatsnew/3 6 deprecated-build-options}@anchor{f2c}
@subsubsection 已棄用的建置選項


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 已移除<8>,移植至 Python 3 6,已棄用<10>,Python 3 6 有什麼新功能
@anchor{whatsnew/3 6 removed}@anchor{f2d}
@subsection 已移除


@menu
* API 與功能的移除: API 與功能的移除<3>. 

@end menu

@node API 與功能的移除<3>,,,已移除<8>
@anchor{whatsnew/3 6 api-and-feature-removals}@anchor{f2e}
@subsubsection API 與功能的移除



@itemize *

@item 
Unknown escapes consisting of @code{'\'} and an ASCII letter in
regular expressions will now cause an error.  In replacement templates for
@ref{59d,,re.sub()} they are still allowed, but deprecated.
The @ref{d5b,,re.LOCALE} flag can now only be used with binary patterns.

@item 
@code{inspect.getmoduleinfo()} was removed (was deprecated since CPython 3.3).
@ref{f2f,,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 
@ref{104,,traceback} 模組中的 @code{traceback.Ignore} 類別和 @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} 方法已被移除。它們是自 Python 3.2 以來已棄用的未記錄方法，等效的功能現在可從私有方法獲得。

@item 
The @code{tk_menuBar()} and @code{tk_bindForTraversal()} dummy methods in
@ref{f6,,tkinter} widget classes were removed (corresponding Tk commands
were obsolete since Tk 4.0).

@item 
The @ref{655,,open()} method of the @ref{8cb,,zipfile.ZipFile}
class no longer supports the @code{'U'} mode (was deprecated since Python 3.4).
Use @ref{9b7,,io.TextIOWrapper} for reading compressed text files in
@ref{f30,,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 
已棄用的 @code{asynchat.fifo} 類別已移除。
@end itemize

@node 移植至 Python 3 6,Python 3 6 2 中顯著的變更,已移除<8>,Python 3 6 有什麼新功能
@anchor{whatsnew/3 6 porting-to-python-3-6}@anchor{f31}
@subsection 移植至 Python 3.6


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

@menu
* 'python' 命令的行為變更:: 
* Python API 的變更: Python API 的變更<9>. 
* C API 中的改動: C API 中的改動<7>. 
* CPython 位元組碼變更: CPython 位元組碼變更<9>. 

@end menu

@node 'python' 命令的行為變更,Python API 的變更<9>,,移植至 Python 3 6
@anchor{whatsnew/3 6 changes-in-python-command-behavior}@anchor{f32}
@subsubsection 'python' 命令的行為變更



@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 Python API 的變更<9>,C API 中的改動<7>,'python' 命令的行為變更,移植至 Python 3 6
@anchor{whatsnew/3 6 changes-in-the-python-api}@anchor{f33}
@subsubsection Python API 的變更



@itemize *

@item 
@ref{315,,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{d4,,sqlite3} no longer implicitly commits an open transaction before DDL
statements.

@item 
On Linux, @ref{73f,,os.urandom()} now blocks until the system urandom entropy pool
is initialized to increase the security.

@item 
When @ref{a63,,importlib.abc.Loader.exec_module()} is defined,
@ref{ea7,,importlib.abc.Loader.create_module()} must also be defined.

@item 
@ref{f34,,PyErr_SetImportError()} now sets @ref{198,,TypeError} when its `msg'
argument is not set. Previously only @code{NULL} was returned.

@item 
The format of the @ref{32f,,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{9a8,,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{f35,,urllib.parse.urlsplit()} and @ref{360,,urlparse()} results
now raises @ref{2eb,,ValueError} for out-of-range values, rather than
returning @ref{87e,,None}.  See bpo-20059@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20059}.

@item 
The @code{imp} module now raises a @ref{1a3,,DeprecationWarning} instead of
@ref{abd,,PendingDeprecationWarning}.

@item 
The following modules have had missing APIs added to their
@ref{f36,,__all__} attributes to match the documented APIs:
@ref{15,,calendar}, @code{cgi}, @ref{2d,,csv},
@ref{12b,,ElementTree}, @ref{5a,,enum},
@ref{5f,,fileinput}, @ref{62,,ftplib}, @ref{8b,,logging}, @ref{8f,,mailbox},
@ref{93,,mimetypes}, @ref{a4,,optparse}, @ref{b0,,plistlib}, @code{smtpd},
@ref{dc,,subprocess}, @ref{e4,,tarfile}, @ref{f3,,threading} and
@ref{119,,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{717,,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{653,,ImportError} will be raised. Previously, @ref{78e,,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{d2,,socketserver} module, including those
defined in @ref{76,,http.server}, @ref{135,,xmlrpc.server} and
@ref{121,,wsgiref.simple_server}, now only catch exceptions derived
from @ref{bc4,,Exception}. Therefore if a request handler raises
an exception like @ref{f37,,SystemExit} or @ref{bbc,,KeyboardInterrupt},
@ref{f38,,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{f39,,PermissionError} instead of
@ref{5df,,KeyError} if the user doesn't have privileges.

@item 
The @ref{f3a,,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 
在 @ref{86,,json} 模組中，@ref{f3b,,dump()}、@ref{f3c,,dumps()}、@ref{ead,,load()} 和 @ref{b45,,loads()} 函式以及 @ref{f3d,,JSONEncoder} 和 @ref{f3e,,JSONDecoder} 類別建構函式的所有可選引數現在都是@ref{59f,,僅限關鍵字}引數。（由 Serhiy Storchaka 在 bpo-18726@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18726} 中貢獻。）

@item 
Subclasses of @ref{f3f,,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{f3f,,type} (other than the metaclass hint, @code{metaclass}) is now
consistently delegated to @ref{83c,,object.__init_subclass__()}. This means that
@ref{799,,type.__new__} and @ref{8b7,,type.__init__} both now accept arbitrary keyword arguments,
but @ref{83c,,object.__init_subclass__()} (which is called from
@ref{799,,type.__new__}) will reject them by default.
Custom metaclasses accepting additional keyword arguments will need to adjust
their calls to @ref{799,,type.__new__}
(whether direct or via @ref{1a6,,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{111,,urllib.request} module and the
@ref{ea2,,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{bcf,,DictReader} now returns rows of type
@ref{7ec,,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{4db,,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{f40,,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{af6,,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{f41,,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{f42,,pkgutil.iter_modules()} and @ref{df4,,pkgutil.walk_packages()}
functions now return @ref{f43,,ModuleInfo} named tuples.
(Contributed by Ramchandra Apte in bpo-17211@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17211}.)

@item 
@ref{59d,,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{8cb,,zipfile.ZipFile} will now raise @ref{369,,NotImplementedError} for
unrecognized compression values.  Previously a plain @ref{244,,RuntimeError}
was raised.  Additionally, calling @ref{8cb,,ZipFile} methods
on a closed ZipFile or calling the @ref{f44,,write()} method
on a ZipFile created with mode @code{'r'} will raise a @ref{2eb,,ValueError}.
Previously, a @ref{244,,RuntimeError} was raised in those scenarios.

@item 
when custom metaclasses are combined with zero-argument @ref{1a6,,super()} or
direct references from methods to the implicit @code{__class__} closure
variable, the implicit @code{__classcell__} namespace entry must now be passed
up to @code{type.__new__} for initialisation. Failing to do so will result in
a @ref{1a3,,DeprecationWarning} in Python 3.6 and a @ref{244,,RuntimeError} in
Python 3.8.

@item 
With the introduction of @ref{d35,,ModuleNotFoundError}, import system consumers
may start expecting import system replacements to raise that more specific
exception when appropriate, rather than the less-specific @ref{653,,ImportError}.
To provide future compatibility with such consumers, implementers of
alternative import systems that completely replace @ref{ac8,,__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 C API 中的改動<7>,CPython 位元組碼變更<9>,Python API 的變更<9>,移植至 Python 3 6
@anchor{whatsnew/3 6 changes-in-the-c-api}@anchor{f45}
@subsubsection C API 中的改動



@itemize *

@item 
The @ref{e5b,,PyMem_Malloc()} allocator family now uses the @ref{f06,,pymalloc allocator} rather than the system @code{malloc()}. Applications calling
@ref{e5b,,PyMem_Malloc()} without holding the GIL can now crash. Set the
@geindex PYTHONMALLOC
@geindex 環境變數; PYTHONMALLOC
@ref{e59,,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{f46,,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 位元組碼變更<9>,,C API 中的改動<7>,移植至 Python 3 6
@anchor{whatsnew/3 6 cpython-bytecode-changes}@anchor{f47}
@subsubsection CPython 位元組碼變更


There have been several major changes to the @ref{4a5,,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{f48,,BUILD_STRING} opcodes as part
of the  @ref{e24,,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{f49,,MAKE_FUNCTION}, @code{CALL_FUNCTION},
@code{CALL_FUNCTION_KW} and @code{BUILD_MAP_UNPACK_WITH_CALL} opcodes
have been modified, the new @ref{f4a,,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{f4b,,SETUP_ANNOTATIONS} and @code{STORE_ANNOTATION} opcodes
have been added to support the new @ref{f4c,,variable annotation} syntax.
(Contributed by Ivan Levkivskyi in bpo-27985@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27985}.)
@end itemize

@node Python 3 6 2 中顯著的變更,Python 3 6 4 中顯著的變更,移植至 Python 3 6,Python 3 6 有什麼新功能
@anchor{whatsnew/3 6 notable-changes-in-python-3-6-2}@anchor{f4d}
@subsection Python 3.6.2 中顯著的變更


@menu
* 新增 make regen-all 建置目標:: 
* 移除 make touch 建置目標:: 

@end menu

@node 新增 make regen-all 建置目標,移除 make touch 建置目標,,Python 3 6 2 中顯著的變更
@anchor{whatsnew/3 6 new-make-regen-all-build-target}@anchor{f4e}
@subsubsection 新增 @code{make regen-all} 建置目標


To simplify cross-compilation, and to ensure that CPython can reliably be
compiled without requiring an existing version of Python to already be
available, the autotools-based build system no longer attempts to implicitly
recompile generated files based on file modification times.

Instead, a new @code{make regen-all} command has been added to force regeneration
of these files when desired (e.g. after an initial version of Python has
already been built based on the pregenerated versions).

More selective regeneration targets are also defined - see
Makefile.pre.in@footnote{https://github.com/python/cpython/tree/3.14/Makefile.pre.in} for details.

（由 Victor Stinner 於 bpo-23404@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23404} 中貢獻。）


在 3.6.2 版被加入.


@node 移除 make touch 建置目標,,新增 make regen-all 建置目標,Python 3 6 2 中顯著的變更
@anchor{whatsnew/3 6 removal-of-make-touch-build-target}@anchor{f4f}
@subsubsection 移除 @code{make touch} 建置目標


The @code{make touch} build target previously used to request implicit regeneration
of generated files by updating their modification times has been removed.

它已被新的 @code{make regen-all} 目標取代。

（由 Victor Stinner 於 bpo-23404@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23404} 中貢獻。）


在 3.6.2 版的變更.


@node Python 3 6 4 中顯著的變更,Python 3 6 5 中顯著的變更,Python 3 6 2 中顯著的變更,Python 3 6 有什麼新功能
@anchor{whatsnew/3 6 notable-changes-in-python-3-6-4}@anchor{f50}
@subsection 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 Python 3 6 5 中顯著的變更,Python 3 6 7 中顯著的變更,Python 3 6 4 中顯著的變更,Python 3 6 有什麼新功能
@anchor{whatsnew/3 6 notable-changes-in-python-3-6-5}@anchor{f51}
@subsection Python 3.6.5 中顯著的變更


The @ref{df3,,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 Python 3 6 7 中顯著的變更,Python 3 6 10 中顯著的變更,Python 3 6 5 中顯著的變更,Python 3 6 有什麼新功能
@anchor{whatsnew/3 6 notable-changes-in-python-3-6-7}@anchor{f52}
@subsection Python 3.6.7 中顯著的變更


@ref{128,,xml.dom.minidom} and @ref{12f,,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{101,,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 Python 3 6 10 中顯著的變更,Python 3 6 13 中顯著的變更,Python 3 6 7 中顯著的變更,Python 3 6 有什麼新功能
@anchor{whatsnew/3 6 notable-changes-in-python-3-6-10}@anchor{f53}
@subsection Python 3.6.10 中顯著的變更


Due to significant security concerns, the `reuse_address' parameter of
@ref{934,,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 Python 3 6 13 中顯著的變更,Python 3 6 14 中顯著的變更,Python 3 6 10 中顯著的變更,Python 3 6 有什麼新功能
@anchor{whatsnew/3 6 notable-changes-in-python-3-6-13}@anchor{f54}
@subsection Python 3.6.13 中顯著的變更


Earlier Python versions allowed using both @code{;} and @code{&} as
query parameter separators in @ref{31e,,urllib.parse.parse_qs()} and
@ref{31d,,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 Python 3 6 14 中顯著的變更,,Python 3 6 13 中顯著的變更,Python 3 6 有什麼新功能
@anchor{whatsnew/3 6 notable-changes-in-python-3-6-14}@anchor{f55}
@subsection Python 3.6.14 中顯著的變更


A security fix alters the @ref{aed,,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{110,,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 Python 3 5 有什麼新功能,Python 3 4 有什麼新功能,Python 3 6 有什麼新功能,Python 有什麼新功能？
@anchor{whatsnew/3 5 doc}@anchor{f56}@anchor{whatsnew/3 5 translation-repo}@anchor{f57}@anchor{whatsnew/3 5 what-s-new-in-python-3-5}@anchor{f58}
@section Python 3.5 有什麼新功能


@*編輯者: 
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.

本文介紹了 Python 3.5 與 3.4 相比多了哪些新功能。Python 3.1 已於 2015 年 9 月 13 日發布。完整詳情請見 changelog@footnote{https://docs.python.org/3.5/whatsnew/changelog.html}。


@subsubheading 也參考


@geindex Python Enhancement Proposals; PEP 478
PEP 478@footnote{https://peps.python.org/pep-0478/} - Python 3.5 發佈時程


@menu
* 發布重點摘要: 發布重點摘要<9>. 
* 新增功能: 新增功能<14>. 
* 其他語言更動: 其他語言更動<9>. 
* 新增模組: 新增模組<5>. 
* 改進的模組: 改進的模組<9>. 
* 其他模組層級的變更:: 
* 最佳化: 最佳化<10>. 
* 建置和 C API 變更: 建置和 C API 變更<3>. 
* 已棄用: 已棄用<11>. 
* 已移除: 已移除<9>. 
* 移植至 Python 3.5: 移植至 Python 3 5. 
* Python 3.5.4 中顯著的變更: Python 3 5 4 中顯著的變更. 

@end menu

@node 發布重點摘要<9>,新增功能<14>,,Python 3 5 有什麼新功能
@anchor{whatsnew/3 5 summary-release-highlights}@anchor{f59}
@subsection 發布重點摘要


新增語法特性：


@itemize *

@item 
@ref{f5a,,PEP 492}，使用 async 和 await 語法的協程

@item 
@ref{f5b,,PEP 465}, a new matrix multiplication operator: @code{a @@ b}.

@item 
@ref{f5c,,PEP 448}, additional unpacking generalizations.
@end itemize

新的函式庫模組：


@itemize *

@item 
@ref{10a,,typing}：@ref{f5d,,PEP 484 -- 型別提示}。

@item 
@ref{136,,zipapp}：@ref{f5e,,PEP 441 改進 Python ZIP 應用程式支援}。
@end itemize

新的內建功能


@itemize *

@item 
@code{bytes % args}, @code{bytearray % args}: @ref{f5f,,PEP 461} --
Adding @code{%} formatting to bytes and bytearray.

@item 
New @ref{f60,,bytes.hex()}, @ref{f61,,bytearray.hex()} and @ref{f62,,memoryview.hex()}
methods. (Contributed by Arnon Yaari in bpo-9951@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9951}.)

@item 
@ref{165,,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{f63,,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 實作改進：


@itemize *

@item 
When the @code{LC_TYPE} locale is the POSIX locale (@code{C} locale),
@ref{758,,sys.stdin} and @ref{cc4,,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{f64,,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{f65,,PEP 489 overview}.)
@end itemize

標準函式庫中的顯著改進


@itemize *

@item 
@ref{7ec,,collections.OrderedDict} is now
@ref{f66,,implemented in C}, which makes it
4 to 100 times faster.

@item 
The @ref{d5,,ssl} module gained
@ref{f67,,support for Memory BIO}, which decouples SSL
protocol handling from network IO.

@item 
The new @ref{c4b,,os.scandir()} function provides a
@ref{f68,,better and significantly faster way}
of directory traversal.

@item 
@ref{bd9,,functools.lru_cache()} has been mostly
@ref{f69,,reimplemented in C}, yielding much better
performance.

@item 
The new @ref{d79,,subprocess.run()} function provides a
@ref{f6a,,streamlined way to run subprocesses}.

@item 
The @ref{104,,traceback} module has been significantly
@ref{f6b,,enhanced} for improved
performance and developer convenience.
@end itemize

安全性改進：


@itemize *

@item 
SSLv3 is now disabled throughout the standard library.
It can still be enabled by instantiating a @ref{355,,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 改進：


@itemize *

@item 
Windows 的新安裝程式取代了舊的 MSI。詳情請參見 @ref{c95,,在 Windows 上使用 Python}。

@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 新增功能<14>,其他語言更動<9>,發布重點摘要<9>,Python 3 5 有什麼新功能
@anchor{whatsnew/3 5 new-features}@anchor{f6c}
@subsection 新增功能


@menu
* PEP 492 - 使用 async 和 await 語法的協程:: 
* 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 - 型別提示:: 
* PEP 471 - os.scandir() function: PEP 471 - os scandir function -- a better and faster directory iterator. a better and faster directory iterator
* PEP 475; Retry system calls failing with EINTR: PEP 475 Retry system calls failing with EINTR. 
* PEP 479; Change StopIteration handling inside generators: PEP 479 Change StopIteration handling inside generators. 
* PEP 485; A function for testing approximate equality: PEP 485 A function for testing approximate equality. 
* PEP 486; Make the Python Launcher aware of virtual environments: PEP 486 Make the Python Launcher aware of virtual environments. 
* PEP 488; 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 - 使用 async 和 await 語法的協程,PEP 465 - A dedicated infix operator for matrix multiplication,,新增功能<14>
@anchor{whatsnew/3 5 pep-492-coroutines-with-async-and-await-syntax}@anchor{f6d}@anchor{whatsnew/3 5 whatsnew-pep-492}@anchor{f5a}
@subsubsection PEP 492 - 使用 async 和 await 語法的協程


@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{4c4,,awaitable objects},
@ref{f6e,,coroutine functions},
@ref{f6f,,asynchronous iteration},
and @ref{7e8,,asynchronous context managers}.

Coroutine functions are declared using the new @ref{7e6,,async def} syntax:

@example
>>> async def coro():
...     return 'spam'
@end example

Inside a coroutine function, the new @ref{18d,,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{4c4,,awaitable} protocol by
defining the @ref{f70,,__await__()} method.

PEP 492 also adds @ref{c98,,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

將輸出：

@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{c98,,async for} and @ref{185,,async with} can only
be used inside a coroutine function declared with @ref{7e6,,async def}.

Coroutine functions are intended to be run inside a compatible event loop,
such as the @ref{f71,,asyncio loop}.

@cartouche
@quotation 備註 

在 3.5.2 版的變更: Starting with CPython 3.5.2, @code{__aiter__} can directly return
@ref{4c2,,asynchronous iterators}.  Returning
an @ref{4c4,,awaitable} object will result in a
@ref{abd,,PendingDeprecationWarning}.

更多細節請見 @ref{f72,,Asynchronous Iterators} 文件部分。

@end quotation
@end cartouche


@subsubheading 也參考



@table @asis

@geindex Python Enhancement Proposals; PEP 492

@item PEP 492@footnote{https://peps.python.org/pep-0492/} -- 使用 async 和 await 語法的協程

由 Yury Selivanov 撰寫 PEP 與實作。
@end table


@node PEP 465 - A dedicated infix operator for matrix multiplication,PEP 448 - Additional Unpacking Generalizations,PEP 492 - 使用 async 和 await 語法的協程,新增功能<14>
@anchor{whatsnew/3 5 pep-465-a-dedicated-infix-operator-for-matrix-multiplication}@anchor{f73}@anchor{whatsnew/3 5 whatsnew-pep-465}@anchor{f5b}
@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{f74,,__matmul__()},
@ref{f75,,__rmatmul__()}, and @ref{f76,,__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

由 Nathaniel J. Smith 撰寫 PEP；由 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,新增功能<14>
@anchor{whatsnew/3 5 pep-448-additional-unpacking-generalizations}@anchor{f77}@anchor{whatsnew/3 5 whatsnew-pep-448}@anchor{f5c}
@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{f78,,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{f79,,Expression lists} and @ref{f7a,,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 - 型別提示,PEP 448 - Additional Unpacking Generalizations,新增功能<14>
@anchor{whatsnew/3 5 pep-461-percent-formatting-support-for-bytes-and-bytearray}@anchor{f7b}@anchor{whatsnew/3 5 whatsnew-pep-461}@anchor{f5f}
@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{f7c,,interpolation operator} to @ref{192,,bytes}
and @ref{343,,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.

範例：

@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 - 型別提示,PEP 471 - os scandir function -- a better and faster directory iterator,PEP 461 - percent formatting support for bytes and bytearray,新增功能<14>
@anchor{whatsnew/3 5 pep-484-type-hints}@anchor{f7d}@anchor{whatsnew/3 5 whatsnew-pep-484}@anchor{f5d}
@subsubsection PEP 484 - 型別提示


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{3cf,,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{456,,__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{8b3,,Any} which is consistent with (i.e. assignable to
and from) all types.


@subsubheading 也參考



@itemize *

@item 
@ref{10a,,typing} 模組文件

@item 

@table @asis

@geindex Python Enhancement Proposals; PEP 484

@item PEP 484@footnote{https://peps.python.org/pep-0484/} -- 型別提示

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/} -- 型別提示理論

由 Guido van Rossum 撰寫 PEP
@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 - 型別提示,新增功能<14>
@anchor{whatsnew/3 5 pep-471-os-scandir-function-a-better-and-faster-directory-iterator}@anchor{f7e}@anchor{whatsnew/3 5 whatsnew-pep-471}@anchor{f68}
@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{c4b,,os.scandir()},
to the standard library.  Additionally, @ref{6c9,,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{26d,,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{c4b,,os.scandir()} to display all
the files (excluding directories) in the given `path' that don't start with
@code{'.'}. The @ref{f7f,,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

在 Victor Stinner 協助下由 Ben Hoyt 撰寫 PEP 與實作。
@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,新增功能<14>
@anchor{whatsnew/3 5 pep-475-retry-system-calls-failing-with-eintr}@anchor{f80}@anchor{whatsnew/3 5 whatsnew-pep-475}@anchor{f81}
@subsubsection PEP 475: Retry system calls failing with EINTR


An @ref{f82,,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{f83,,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

和：

@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{f83,,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{315,,open()} 和 @ref{739,,io.open()}；

@item 
@ref{5c,,faulthandler} 模組的函式；

@item 
@ref{a5,,os} functions: @ref{f84,,fchdir()}, @ref{525,,fchmod()},
@ref{f85,,fchown()}, @ref{f86,,fdatasync()}, @ref{f87,,fstat()},
@ref{f88,,fstatvfs()}, @ref{f89,,fsync()}, @ref{f8a,,ftruncate()},
@ref{f8b,,mkfifo()}, @ref{f8c,,mknod()}, @ref{f8d,,open()},
@ref{f8e,,posix_fadvise()}, @ref{f8f,,posix_fallocate()}, @ref{d4e,,pread()},
@ref{d51,,pwrite()}, @ref{f90,,read()}, @ref{d4d,,readv()}, @ref{cfd,,sendfile()},
@ref{f91,,wait3()}, @ref{f92,,wait4()}, @ref{f93,,wait()},
@ref{f94,,waitid()}, @ref{f95,,waitpid()}, @ref{f96,,write()},
@ref{d50,,writev()};

@item 
special cases: @ref{d63,,os.close()} and @ref{d52,,os.dup2()} now ignore
@ref{f82,,EINTR} errors; the syscall is not retried (see the PEP
for the rationale);

@item 
@ref{c6,,select} functions: @ref{f97,,devpoll.poll()},
@ref{f98,,epoll.poll()},
@ref{f99,,kqueue.control()},
@ref{f9a,,poll.poll()}, @ref{f9b,,select()};

@item 
methods of the @ref{f9c,,socket} class: @ref{f9d,,accept()},
@ref{f9e,,connect()} (except for non-blocking sockets),
@ref{f9f,,recv()}, @ref{fa0,,recvfrom()},
@ref{fa1,,recvmsg()}, @ref{fa2,,send()},
@ref{fa3,,sendall()}, @ref{69a,,sendmsg()},
@ref{fa4,,sendto()};

@item 
@ref{fa5,,signal.sigtimedwait()} 和 @ref{fa6,,signal.sigwaitinfo()}；

@item 
@ref{8a4,,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,新增功能<14>
@anchor{whatsnew/3 5 pep-479-change-stopiteration-handling-inside-generators}@anchor{fa7}@anchor{whatsnew/3 5 whatsnew-pep-479}@anchor{f16}
@subsubsection PEP 479: Change StopIteration handling inside generators


The interaction of generators and @ref{df0,,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{244,,RuntimeError} before it exits the generator frame.  The main goal of
this change is to ease debugging in the situation where an unguarded
@ref{9d1,,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{fa8,,__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{abd,,PendingDeprecationWarning} will be
raised whenever a @ref{df0,,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,新增功能<14>
@anchor{whatsnew/3 5 pep-485-a-function-for-testing-approximate-equality}@anchor{fa9}@anchor{whatsnew/3 5 whatsnew-pep-485}@anchor{faa}
@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{fab,,math.isclose()} and @ref{fac,,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,新增功能<14>
@anchor{whatsnew/3 5 pep-486-make-the-python-launcher-aware-of-virtual-environments}@anchor{fad}@anchor{whatsnew/3 5 whatsnew-pep-486}@anchor{fae}
@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

由 Paul Moore 撰寫 PEP 與實作。
@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,新增功能<14>
@anchor{whatsnew/3 5 pep-488-elimination-of-pyo-files}@anchor{faf}@anchor{whatsnew/3 5 whatsnew-pep-488}@anchor{f64}
@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{18c,,-O} or @ref{fb0,,-OO}. Consequently, bytecode files generated from
@ref{18c,,-O}, and @ref{fb0,,-OO} may now exist simultaneously.
@ref{351,,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/} -- 消除 PYO 檔案

由 Brett Cannon 撰寫 PEP 與實作。
@end table


@node PEP 489 Multi-phase extension module initialization,,PEP 488 Elimination of PYO files,新增功能<14>
@anchor{whatsnew/3 5 pep-489-multi-phase-extension-module-initialization}@anchor{fb1}@anchor{whatsnew/3 5 whatsnew-pep-489}@anchor{f65}
@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/} -- 多階段擴充模組初始化

PEP written by Petr Viktorin, Stefan Behnel, and Nick Coghlan;
implemented by Petr Viktorin.
@end table


@node 其他語言更動<9>,新增模組<5>,新增功能<14>,Python 3 5 有什麼新功能
@anchor{whatsnew/3 5 other-language-changes}@anchor{fb2}
@subsection 其他語言更動


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{7f2,,-b} option now affects comparisons of @ref{192,,bytes} with
@ref{19b,,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{fb3,,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{4db,,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 新增模組<5>,改進的模組<9>,其他語言更動<9>,Python 3 5 有什麼新功能
@anchor{whatsnew/3 5 new-modules}@anchor{fb4}
@subsection 新增模組


@menu
* typing: typing<11>. 
* zipapp: zipapp<2>. 

@end menu

@node typing<11>,zipapp<2>,,新增模組<5>
@anchor{whatsnew/3 5 typing}@anchor{fb5}
@subsubsection typing


The new @ref{10a,,typing} @ref{3cf,,provisional} module
provides standard definitions and tools for function type annotations.
See @ref{f5d,,Type Hints} for more information.

@node zipapp<2>,,typing<11>,新增模組<5>
@anchor{whatsnew/3 5 whatsnew-zipapp}@anchor{f5e}@anchor{whatsnew/3 5 zipapp}@anchor{fb6}
@subsubsection zipapp


The new @ref{136,,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

模組實作由 Paul Moore 在 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/} -- 改進 Python ZIP 應用程式支援


@node 改進的模組<9>,其他模組層級的變更,新增模組<5>,Python 3 5 有什麼新功能
@anchor{whatsnew/3 5 improved-modules}@anchor{fb7}
@subsection 改進的模組


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

@end menu

@node argparse<6>,asyncio<13>,,改進的模組<9>
@anchor{whatsnew/3 5 argparse}@anchor{fb8}
@subsubsection argparse


The @ref{1bd,,ArgumentParser} class now allows disabling
@ref{fb9,,abbreviated usage} of long options by setting
@ref{fba,,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<13>,bz2,argparse<6>,改進的模組<9>
@anchor{whatsnew/3 5 asyncio}@anchor{fbb}
@subsubsection asyncio


Since the @ref{b,,asyncio} module is @ref{3cf,,provisional},
all changes introduced in Python 3.5 have also been backported to Python 3.4.x.

Python 3.4.0 以來 @ref{b,,asyncio} 模組的顯著變更：


@itemize *

@item 
New debugging APIs: @ref{fbc,,loop.set_debug()}
and @ref{fbd,,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{fbe,,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{1ca,,loop.create_task()}
to conveniently create and schedule a new @ref{1c7,,Task}
for a coroutine.  The @code{create_task} method is also used by all
asyncio functions that wrap coroutines into tasks, such as
@ref{6a0,,asyncio.wait()}, @ref{80c,,asyncio.gather()}, etc.
(Contributed by Victor Stinner.)

@item 
A new @ref{fbf,,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{e6c,,ensure_future()}.
(Contributed by Yury Selivanov.)

@item 
New @ref{1c8,,loop.set_task_factory()} and
@ref{fc0,,loop.get_task_factory()}
methods to customize the task factory that @ref{1ca,,loop.create_task()} method uses.  (Contributed by Yury
Selivanov.)

@item 
New @ref{fc1,,Queue.join()} and
@ref{fc2,,Queue.task_done()} queue methods.
(Contributed by Victor Stinner.)

@item 
The @code{JoinableQueue} class was removed, in favor of the
@ref{c61,,asyncio.Queue} class.
(Contributed by Victor Stinner.)
@end itemize

3.5.1 的更新：


@itemize *

@item 
The @ref{e6c,,ensure_future()} function and all functions that
use it, such as @ref{e6d,,loop.run_until_complete()},
now accept all kinds of @ref{4c4,,awaitable objects}.
(Contributed by Yury Selivanov.)

@item 
New @ref{a79,,run_coroutine_threadsafe()} function to submit
coroutines to event loops from other threads.
(Contributed by Vincent Michel.)

@item 
New @ref{e6e,,Transport.is_closing()}
method to check if the transport is closing or closed.
(Contributed by Yury Selivanov.)

@item 
The @ref{d01,,loop.create_server()}
method can now accept a list of hosts.
(Contributed by Yann Sionneau.)
@end itemize

3.5.2 的更新：


@itemize *

@item 
New @ref{e6f,,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{dc1,,asyncio.Future} implementation.
(Contributed by Yury Selivanov.)

@item 
New @ref{e70,,loop.get_exception_handler()}
method to get the current exception handler.
(Contributed by Yury Selivanov.)

@item 
New @ref{4cb,,StreamReader.readuntil()}
method to read data from the stream until a separator bytes
sequence appears.
(Contributed by Mark Korenberg.)

@item 
The @ref{811,,loop.create_connection()}
and @ref{d01,,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{fc3,,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<13>,改進的模組<9>
@anchor{whatsnew/3 5 bz2}@anchor{fc4}
@subsubsection bz2


The @ref{fc5,,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,改進的模組<9>
@anchor{whatsnew/3 5 cgi}@anchor{fc6}
@subsubsection cgi


The @code{FieldStorage} class now supports the @ref{1e1,,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,改進的模組<9>
@anchor{whatsnew/3 5 cmath}@anchor{fc7}
@subsubsection cmath


A new function @ref{fac,,isclose()} provides a way to test for approximate
equality.  (Contributed by Chris Barker and Tal Einat in bpo-24270@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24270}.)

@node code,collections<5>,cmath<2>,改進的模組<9>
@anchor{whatsnew/3 5 code}@anchor{fc8}
@subsubsection code


The @ref{fc9,,InteractiveInterpreter.showtraceback()}
method now prints the full chained traceback, just like the interactive
interpreter.  (Contributed by Claudiu Popa in bpo-17442@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17442}.)

@node collections<5>,collections abc<3>,code,改進的模組<9>
@anchor{whatsnew/3 5 collections}@anchor{fca}
@subsubsection collections

@anchor{whatsnew/3 5 whatsnew-ordereddict}@anchor{f66}
The @ref{7ec,,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{a5e,,reversed()} iteration.
(Contributed by Serhiy Storchaka in bpo-19505@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19505}.)

The @ref{7ed,,deque} class now defines
@ref{fcb,,index()}, @ref{fcc,,insert()}, and
@ref{fcd,,copy()}, and supports the @code{+} and @code{*} operators.
This allows deques to be recognized as a @ref{4ba,,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{4db,,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

（由 Berker Peksag 在 bpo-24064@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24064} 中貢獻。）

The @ref{fce,,UserString} class now implements the
@ref{fcf,,__getnewargs__()}, @ref{fd0,,__rmod__()}, @ref{fd1,,casefold()},
@ref{fd2,,format_map()}, @ref{fd3,,isprintable()}, and @ref{fd4,,maketrans()}
methods to match the corresponding methods of @ref{169,,str}.
(Contributed by Joe Jevnik in bpo-22189@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22189}.)

@node collections abc<3>,compileall<4>,collections<5>,改進的模組<9>
@anchor{whatsnew/3 5 collections-abc}@anchor{fd5}
@subsubsection collections.abc


The @code{Sequence.index()} method now
accepts `start' and `stop' arguments to match the corresponding methods
of @ref{60c,,tuple}, @ref{24d,,list}, etc.
(Contributed by Devin Jeanpierre in bpo-23086@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23086}.)

A new @ref{fd6,,Generator} abstract base class. (Contributed
by Stefan Behnel in bpo-24018@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24018}.)

New @ref{fd7,,Awaitable}, @ref{fd8,,Coroutine},
@ref{fd9,,AsyncIterator}, and
@ref{fda,,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<6>,collections abc<3>,改進的模組<9>
@anchor{whatsnew/3 5 compileall}@anchor{fdb}
@subsubsection compileall


A new @ref{21,,compileall} option, @code{-j @var{N}}, allows running `N' workers
simultaneously to perform parallel bytecode compilation.
The @ref{d13,,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{d13,,compile_dir()},
@ref{fdc,,compile_file()}, and @ref{fdd,,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<6>,configparser<5>,compileall<4>,改進的模組<9>
@anchor{whatsnew/3 5 concurrent-futures}@anchor{fde}
@subsubsection concurrent.futures


The @ref{1dc,,Executor.map()} method now accepts a
`chunksize' argument to allow batching of tasks to improve performance when
@ref{1d6,,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{941,,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<5>,concurrent futures<6>,改進的模組<9>
@anchor{whatsnew/3 5 configparser}@anchor{fdf}
@subsubsection configparser


@ref{26,,configparser} now provides a way to customize the conversion
of values by specifying a dictionary of converters in the
@ref{4d9,,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
>>> 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

（由 Łukasz Langa 在 bpo-18159@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18159} 中貢獻。）

@node contextlib<5>,csv<3>,configparser<5>,改進的模組<9>
@anchor{whatsnew/3 5 contextlib}@anchor{fe0}
@subsubsection contextlib


The new @ref{fe1,,redirect_stderr()} @ref{1e1,,context manager} (similar to
@ref{fe2,,redirect_stdout()}) makes it easier for utility scripts to
handle inflexible APIs that write their output to @ref{b2a,,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

（由 Berker Peksag 在 bpo-22389@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22389} 中貢獻。）

@node csv<3>,curses<5>,contextlib<5>,改進的模組<9>
@anchor{whatsnew/3 5 csv}@anchor{fe3}
@subsubsection csv


@ref{fe4,,writerow()} 方法現在支援任意可疊代物件，而不僅限於序列。（由 Serhiy Storchaka 在 bpo-23171@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23171} 中貢獻。）

@node curses<5>,dbm<5>,csv<3>,改進的模組<9>
@anchor{whatsnew/3 5 curses}@anchor{fe5}
@subsubsection curses


The new @ref{fe6,,update_lines_cols()} function updates the @ref{fe7,,LINES}
and @ref{fe8,,COLS} module variables.  This is useful for detecting
manual screen resizing.  (Contributed by Arnon Yaari in bpo-4254@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4254}.)

@node dbm<5>,difflib<3>,curses<5>,改進的模組<9>
@anchor{whatsnew/3 5 dbm}@anchor{fe9}
@subsubsection dbm


@ref{c84,,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<3>,distutils<7>,dbm<5>,改進的模組<9>
@anchor{whatsnew/3 5 difflib}@anchor{fea}
@subsubsection difflib


The charset of HTML documents generated by
@ref{feb,,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{fec,,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<3>,改進的模組<9>
@anchor{whatsnew/3 5 distutils}@anchor{fed}
@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<4>,distutils<7>,改進的模組<9>
@anchor{whatsnew/3 5 doctest}@anchor{fee}
@subsubsection doctest


The @ref{fef,,DocTestSuite()} function returns an empty
@ref{ff0,,unittest.TestSuite} if `module' contains no docstrings, instead of
raising @ref{2eb,,ValueError}.  (Contributed by Glenn Jones in bpo-15916@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15916}.)

@node email<4>,enum<8>,doctest<3>,改進的模組<9>
@anchor{whatsnew/3 5 email}@anchor{ff1}
@subsubsection email


A new policy option @ref{ff2,,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{e92,,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{ff3,,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{ff4,,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{ff5,,mime.text.MIMEText} constructor now
accepts a @ref{ff6,,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<4>,email<4>,改進的模組<9>
@anchor{whatsnew/3 5 enum}@anchor{ff7}
@subsubsection enum


The @ref{83b,,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

（由 Ethan Furman 在 bpo-21706@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21706} 中貢獻。）

@node faulthandler<4>,functools<5>,enum<8>,改進的模組<9>
@anchor{whatsnew/3 5 faulthandler}@anchor{ff8}
@subsubsection faulthandler


The @ref{20f,,enable()}, @ref{ff9,,register()},
@ref{ffa,,dump_traceback()} and
@ref{ffb,,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<5>,glob<3>,faulthandler<4>,改進的模組<9>
@anchor{whatsnew/3 5 functools}@anchor{ffc}
@subsubsection functools

@anchor{whatsnew/3 5 whatsnew-lrucache}@anchor{f69}
Most of the @ref{bd9,,lru_cache()} machinery is now implemented in C, making
it significantly faster.  (Contributed by Matt Joiner, Alexey Kachayev, and
Serhiy Storchaka in bpo-14373@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14373}.)

@node glob<3>,gzip<4>,functools<5>,改進的模組<9>
@anchor{whatsnew/3 5 glob}@anchor{ffd}
@subsubsection glob


The @ref{a01,,iglob()} and @ref{59a,,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<3>,改進的模組<9>
@anchor{whatsnew/3 5 gzip}@anchor{ffe}
@subsubsection gzip


The `mode' argument of the @ref{654,,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>,改進的模組<9>
@anchor{whatsnew/3 5 heapq}@anchor{fff}
@subsubsection heapq


Element comparison in @ref{1000,,merge()} can now be customized by
passing a @ref{1001,,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

（由 Raymond Hettinger 在 bpo-13742@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13742} 中貢獻。）

@node http<3>,http client<3>,heapq<2>,改進的模組<9>
@anchor{whatsnew/3 5 http}@anchor{1002}
@subsubsection http


A new @ref{af3,,HTTPStatus} enum that defines a set of
HTTP status codes, reason phrases and long descriptions written in English.
(Contributed by Demian Brecht in bpo-21793@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21793}.)

@node http client<3>,idlelib 與 IDLE<3>,http<3>,改進的模組<9>
@anchor{whatsnew/3 5 http-client}@anchor{1003}
@subsubsection http.client


@ref{1004,,HTTPConnection.getresponse()}
now raises a @ref{1005,,RemoteDisconnected} exception when a
remote server connection is closed unexpectedly.  Additionally, if a
@ref{1006,,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

（由 Martin Panter 在 bpo-3566@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3566} 中貢獻。）

@node idlelib 與 IDLE<3>,imaplib<3>,http client<3>,改進的模組<9>
@anchor{whatsnew/3 5 idlelib-and-idle}@anchor{1007}
@subsubsection idlelib 與 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 與 IDLE<3>,改進的模組<9>
@anchor{whatsnew/3 5 imaplib}@anchor{1008}
@subsubsection imaplib


The @ref{af6,,IMAP4} class now supports the @ref{1e1,,context manager} protocol.
When used in a @ref{186,,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{78,,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{1009,,IMAP4.enable()}
method.  A new @ref{100a,,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{78,,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>,改進的模組<9>
@anchor{whatsnew/3 5 imghdr}@anchor{100b}
@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<8>,imghdr,改進的模組<9>
@anchor{whatsnew/3 5 importlib}@anchor{100c}
@subsubsection importlib


The @ref{ea6,,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{100d,,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{100e,,util.module_from_spec()}
function is now the preferred way to create a new module.  As opposed to
creating a @ref{100f,,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<8>,io<7>,importlib<8>,改進的模組<9>
@anchor{whatsnew/3 5 inspect}@anchor{1010}
@subsubsection inspect


Both the @ref{4de,,Signature} and @ref{4df,,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{1011,,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

（由 Yury Selivanov 在 bpo-24190@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24190} 中貢獻。）

A new class method
@ref{93a,,Signature.from_callable()} makes
subclassing of @ref{4de,,Signature} easier.  (Contributed
by Yury Selivanov and Eric Snow in bpo-17373@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17373}.)

The @ref{22f,,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{f6e,,coroutine functions} and
@ref{6b2,,coroutine objects} has been added:
@ref{1012,,iscoroutine()}, @ref{30c,,iscoroutinefunction()},
@ref{1013,,isawaitable()}, @ref{1014,,getcoroutinelocals()},
and @ref{1015,,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{85b,,stack()}, @ref{85c,,trace()},
@ref{859,,getouterframes()}, and @ref{85a,,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<8>,改進的模組<9>
@anchor{whatsnew/3 5 io}@anchor{1016}
@subsubsection io


A new @ref{1017,,BufferedIOBase.readinto1()}
method, that uses at most one call to the underlying raw stream's
@ref{1018,,RawIOBase.read()} or
@ref{1019,,RawIOBase.readinto()} methods.
(Contributed by Nikolaus Rath in bpo-20578@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20578}.)

@node ipaddress<4>,json<3>,io<7>,改進的模組<9>
@anchor{whatsnew/3 5 ipaddress}@anchor{101a}
@subsubsection ipaddress


Both the @ref{509,,IPv4Network} and @ref{50a,,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

（由 Peter Moody 和 Antoine Pitrou 在 bpo-16531@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16531} 中貢獻。）

A new @ref{101b,,reverse_pointer} attribute for the
@ref{507,,IPv4Address} and @ref{508,,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

（由 Leon Weber 在 bpo-20480@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20480} 中貢獻。）

@node json<3>,linecache<3>,ipaddress<4>,改進的模組<9>
@anchor{whatsnew/3 5 json}@anchor{101c}
@subsubsection json


The @ref{87,,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{101d,,JSONDecodeError} instead of
@ref{2eb,,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<6>,json<3>,改進的模組<9>
@anchor{whatsnew/3 5 linecache}@anchor{101e}
@subsubsection linecache


A new @ref{101f,,lazycache()} function can be used to capture information
about a non-file-based module to permit getting its lines later via
@ref{240,,getline()}. This avoids doing I/O until a line is actually
needed, without having to carry the module globals around indefinitely.
(Contributed by Robert Collins in bpo-17911@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17911}.)

@node locale<6>,logging<5>,linecache<3>,改進的模組<9>
@anchor{whatsnew/3 5 locale}@anchor{1020}
@subsubsection locale


A new @ref{1021,,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

（由 Cédric Krier 在 bpo-13918@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13918} 中貢獻。）

@node logging<5>,lzma,locale<6>,改進的模組<9>
@anchor{whatsnew/3 5 logging}@anchor{1022}
@subsubsection logging


All logging methods (@ref{d3e,,Logger} @ref{1023,,log()},
@ref{1024,,exception()}, @ref{1025,,critical()},
@ref{1026,,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

（由 Yury Selivanov 在 bpo-20537@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20537} 中貢獻。）

The @ref{1027,,handlers.HTTPHandler} class now
accepts an optional @ref{355,,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{242,,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<9>,logging<5>,改進的模組<9>
@anchor{whatsnew/3 5 lzma}@anchor{1028}
@subsubsection lzma


The @ref{1029,,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<9>,multiprocessing<7>,lzma,改進的模組<9>
@anchor{whatsnew/3 5 math}@anchor{102a}
@subsubsection math


Two new constants have been added to the @ref{92,,math} module: @ref{e7b,,inf}
and @ref{86c,,nan}.  (Contributed by Mark Dickinson in bpo-23185@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23185}.)

一個新函式 @ref{fab,,isclose()} 提供了測試近似相等性的方式。（由 Chris Barker 和 Tal Einat 在 bpo-24270@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24270} 中貢獻。）

A new @ref{b03,,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<9>,改進的模組<9>
@anchor{whatsnew/3 5 multiprocessing}@anchor{102b}
@subsubsection multiprocessing


@ref{102c,,sharedctypes.synchronized()}
objects now support the @ref{1e1,,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<11>,multiprocessing<7>,改進的模組<9>
@anchor{whatsnew/3 5 operator}@anchor{102d}
@subsubsection operator


@ref{102e,,attrgetter()}, @ref{c4e,,itemgetter()},
and @ref{102f,,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{1030,,matmul()} and @ref{1031,,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<11>,pathlib<13>,operator<3>,改進的模組<9>
@anchor{whatsnew/3 5 os}@anchor{1032}
@subsubsection os


The new @ref{c4b,,scandir()} function returning an iterator of
@ref{6bc,,DirEntry} objects has been added.  If possible, @ref{c4b,,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{1033,,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{73f,,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{1034,,get_blocking()} and @ref{1035,,set_blocking()} functions allow
getting and setting a file descriptor's blocking mode (@ref{1036,,O_NONBLOCK}.)
(Contributed by Victor Stinner in bpo-22054@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22054}.)

Windows 現在支援 @ref{1037,,truncate()} 和 @ref{f8a,,ftruncate()} 函式。（由 Steve Dower 在 bpo-23668@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23668} 中貢獻。）

There is a new @ref{1038,,os.path.commonpath()} function returning the longest
common sub-path of each passed pathname.  Unlike the
@ref{1039,,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

（由 Rafik Draoui 和 Serhiy Storchaka 在 bpo-10395@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10395} 中貢獻。）

@node pathlib<13>,pickle<4>,os<11>,改進的模組<9>
@anchor{whatsnew/3 5 pathlib}@anchor{103a}
@subsubsection pathlib


The new @ref{103b,,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{266,,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

（由 Vajrasky Kok 和 Antoine Pitrou 在 bpo-19775@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19775} 中貢獻。）

The @ref{103c,,Path.mkdir()} method now accepts a new optional
`exist_ok' argument to match @code{mkdir -p} and @ref{527,,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{103d,,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{103e,,Path.home()} class method can be used to get
a @ref{266,,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{103f,,Path.write_text()},
@ref{1040,,Path.read_text()},
@ref{1041,,Path.write_bytes()},
@ref{2df,,Path.read_bytes()} methods to simplify
read/write operations on files.

以下程式碼片段將會建立或重寫已存在的檔案 @code{~/spam42}：

@example
>>> import pathlib
>>> p = pathlib.Path('~/spam42')
>>> p.expanduser().write_text('ham')
3
@end example

（由 Christopher Welborn 在 bpo-20218@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20218} 中貢獻。）

@node pickle<4>,poplib<2>,pathlib<13>,改進的模組<9>
@anchor{whatsnew/3 5 pickle}@anchor{1042}
@subsubsection pickle


Nested objects, such as unbound methods or nested classes, can now be pickled
using @ref{27b,,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<8>,pickle<4>,改進的模組<9>
@anchor{whatsnew/3 5 poplib}@anchor{1043}
@subsubsection poplib


A new @ref{1044,,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<8>,readline<2>,poplib<2>,改進的模組<9>
@anchor{whatsnew/3 5 re}@anchor{1045}
@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

（由 Serhiy Storchaka 在 bpo-9179@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9179} 中貢獻。）

The number of capturing groups in regular expressions is no longer limited to
100.  (Contributed by Serhiy Storchaka in bpo-22437@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22437}.)

The @ref{59d,,sub()} and @ref{59e,,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{541,,re.error} exceptions have new attributes,
@ref{1046,,msg}, @ref{1047,,pattern},
@ref{1048,,pos}, @ref{1049,,lineno},
and @ref{104a,,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

（由 Serhiy Storchaka 在 bpo-22578@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22578} 中貢獻。）

@node readline<2>,selectors,re<8>,改進的模組<9>
@anchor{whatsnew/3 5 readline}@anchor{104b}
@subsubsection readline


A new @ref{104c,,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>,改進的模組<9>
@anchor{whatsnew/3 5 selectors}@anchor{104d}
@subsubsection selectors


The new @ref{dcd,,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,改進的模組<9>
@anchor{whatsnew/3 5 shutil}@anchor{104e}
@subsubsection shutil


The @ref{c48,,move()} function now accepts a `copy_function' argument,
allowing, for example, the @ref{c46,,copy()} function to be used instead of
the default @ref{c47,,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}.)

@ref{6d3,,make_archive()} 函式現在支援 `xztar' 格式。（由 Serhiy Storchaka 在 bpo-5411@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5411} 中貢獻。）

@node signal<3>,smtpd<2>,shutil<5>,改進的模組<9>
@anchor{whatsnew/3 5 signal}@anchor{104f}
@subsubsection signal


On Windows, the @ref{d5f,,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{cb,,signal} module have been converted into
@ref{5a,,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>,改進的模組<9>
@anchor{whatsnew/3 5 smtpd}@anchor{1050}
@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>,改進的模組<9>
@anchor{whatsnew/3 5 smtplib}@anchor{1051}
@subsubsection smtplib


A new @ref{1052,,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{1053,,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{1054,,SMTP.sendmail()} and
@ref{1055,,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<9>,smtplib<2>,改進的模組<9>
@anchor{whatsnew/3 5 sndhdr}@anchor{1056}
@subsubsection sndhdr


The @code{what()} and @code{whathdr()} functions  now return
a @ref{4db,,namedtuple()}.  (Contributed by Claudiu Popa in
bpo-18615@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18615}.)

@node socket<9>,ssl<10>,sndhdr,改進的模組<9>
@anchor{whatsnew/3 5 socket}@anchor{1057}
@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{1058,,socket.sendfile()} method allows
sending a file over a socket by using the high-performance @ref{cfd,,os.sendfile()}
function on UNIX, resulting in uploads being from 2 to 3 times faster than when
using plain @ref{fa2,,socket.send()}.
(Contributed by Giampaolo Rodola' in bpo-17552@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17552}.)

The @ref{fa3,,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{1059,,socket.listen()}
method is now optional.  By default it is set to
@ref{105a,,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<10>,sqlite3<9>,socket<9>,改進的模組<9>
@anchor{whatsnew/3 5 ssl}@anchor{105b}
@subsubsection ssl


@menu
* 記憶體 BIO 支援:: 
* Application-Layer Protocol Negotiation Support:: 
* 其他變更:: 

@end menu

@node 記憶體 BIO 支援,Application-Layer Protocol Negotiation Support,,ssl<10>
@anchor{whatsnew/3 5 memory-bio-support}@anchor{105c}@anchor{whatsnew/3 5 whatsnew-sslmemorybio}@anchor{f67}
@subsubsection 記憶體 BIO 支援


（由 Geert Jansen 在 bpo-21965@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21965} 中貢獻。）

The new @ref{d72,,SSLObject} class has been added to provide SSL protocol
support for cases when the network I/O capabilities of @ref{ade,,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{105d,,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{ade,,SSLSocket}'s readiness
model ("select/poll") is inefficient.

A new @ref{d73,,SSLContext.wrap_bio()} method can be used
to create a new @code{SSLObject} instance.

@node Application-Layer Protocol Negotiation Support,其他變更,記憶體 BIO 支援,ssl<10>
@anchor{whatsnew/3 5 application-layer-protocol-negotiation-support}@anchor{105e}
@subsubsection Application-Layer Protocol Negotiation Support


（由 Benjamin Peterson 在 bpo-20188@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20188} 中貢獻。）

Where OpenSSL support is present, the @ref{d5,,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{105f,,SSLContext.set_alpn_protocols()}
can be used to specify which protocols a socket should advertise during
the TLS handshake.

The new
@ref{1060,,SSLSocket.selected_alpn_protocol()}
returns the protocol that was selected during the TLS handshake.
The @ref{1061,,HAS_ALPN} flag indicates whether ALPN support is present.

@node 其他變更,,Application-Layer Protocol Negotiation Support,ssl<10>
@anchor{whatsnew/3 5 other-changes}@anchor{1062}
@subsubsection 其他變更


There is a new @ref{1063,,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{ade,,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{1064,,ssl.SSLWantReadError} or @ref{1065,,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{1066,,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{19b,,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{1067,,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{1068,,SSLSocket.do_handshake()},
@ref{1069,,SSLSocket.read()},
@code{SSLSocket.shutdown()}, and
@ref{106a,,SSLSocket.write()} methods of the @ref{ade,,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}.)

@code{match_hostname()} 函式現在支援 IP 位址的比對。（由 Antoine Pitrou 在 bpo-23239@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23239} 中貢獻。）

@node sqlite3<9>,subprocess<4>,ssl<10>,改進的模組<9>
@anchor{whatsnew/3 5 sqlite3}@anchor{106b}
@subsubsection sqlite3


The @ref{106c,,Row} class now fully supports the sequence protocol,
in particular @ref{a5e,,reversed()} iteration and slice indexing.
(Contributed by Claudiu Popa in bpo-10203@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10203}; by Lucas Sinclair,
Jessica McKellar, and  Serhiy Storchaka in bpo-13583@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13583}.)

@node subprocess<4>,sys<11>,sqlite3<9>,改進的模組<9>
@anchor{whatsnew/3 5 subprocess}@anchor{106d}@anchor{whatsnew/3 5 whatsnew-subprocess}@anchor{f6a}
@subsubsection subprocess


新增 @ref{d79,,run()} 函式。它運行指定的命令並回傳一個 @ref{106e,,CompletedProcess} 物件，該物件描述了一個已完成的行程。新的 API 更加一致，並且是以較為推薦方法來叫用子行程，適用於不需要與早期 Python 版本保持相容性的 Python 程式碼。（由 Thomas Kluyver 在 bpo-23342@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23342} 中貢獻。）

範例：

@example
>>> subprocess.run(["ls", "-l"])  # 沒有捕捉到輸出
CompletedProcess(args=['ls', '-l'], returncode=0)

>>> subprocess.run("exit 1", shell=True, check=True)
Traceback (most recent call last):
  ...
subprocess.CalledProcessError: Command 'exit 1' returned non-zero exit status 1

>>> subprocess.run(["ls", "-l", "/dev/null"], stdout=subprocess.PIPE)
CompletedProcess(args=['ls', '-l', '/dev/null'], returncode=0,
stdout=b'crw-rw-rw- 1 root root 1, 3 Jan 23 16:23 /dev/null\n')
@end example

@node sys<11>,sysconfig<3>,subprocess<4>,改進的模組<9>
@anchor{whatsnew/3 5 sys}@anchor{106f}
@subsubsection sys


A new @code{set_coroutine_wrapper()} function allows setting a global
hook that will be called whenever a @ref{6b2,,coroutine object}
is created by an @ref{7e6,,async def} function.  A corresponding
@code{get_coroutine_wrapper()} can be used to obtain a currently set
wrapper.  Both functions are @ref{3cf,,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{c77,,is_finalizing()} function can be used to check if the Python
interpreter is @ref{474,,shutting down}.
(Contributed by Antoine Pitrou in bpo-22696@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22696}.)

@node sysconfig<3>,tarfile<7>,sys<11>,改進的模組<9>
@anchor{whatsnew/3 5 sysconfig}@anchor{1070}
@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<7>,threading<7>,sysconfig<3>,改進的模組<9>
@anchor{whatsnew/3 5 tarfile}@anchor{1071}
@subsubsection tarfile


The `mode' argument of the @ref{1072,,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{29b,,TarFile.extractall()} and
@ref{29c,,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{1073,,TarFile.list()} now accepts an optional
`members' keyword argument that can be set to a subset of the list returned
by @ref{1074,,TarFile.getmembers()}.
(Contributed by Serhiy Storchaka in bpo-21549@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21549}.)

@node threading<7>,time<7>,tarfile<7>,改進的模組<9>
@anchor{whatsnew/3 5 threading}@anchor{1075}
@subsubsection threading


Both the @ref{8a0,,Lock.acquire()} and
@ref{1076,,RLock.acquire()} methods
now use a monotonic clock for timeout management.
(Contributed by Victor Stinner in bpo-22043@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22043}.)

@node time<7>,timeit<2>,threading<7>,改進的模組<9>
@anchor{whatsnew/3 5 time}@anchor{1077}
@subsubsection time


@ref{556,,monotonic()} 函式現在總是可用的。（由 Victor Stinner 在 bpo-22043@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22043} 中貢獻。）

@node timeit<2>,tkinter<9>,time<7>,改進的模組<9>
@anchor{whatsnew/3 5 timeit}@anchor{1078}
@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{1079,,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<9>,traceback<5>,timeit<2>,改進的模組<9>
@anchor{whatsnew/3 5 tkinter}@anchor{107a}
@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<6>,tkinter<9>,改進的模組<9>
@anchor{whatsnew/3 5 traceback}@anchor{107b}@anchor{whatsnew/3 5 whatsnew-traceback}@anchor{f6b}
@subsubsection traceback


New @ref{107c,,walk_stack()} and @ref{107d,,walk_tb()}
functions to conveniently traverse frame and
@ref{ce3,,traceback objects}.
(Contributed by Robert Collins in bpo-17911@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17911}.)

New lightweight classes: @ref{55d,,TracebackException},
@ref{107e,,StackSummary}, and @ref{107f,,FrameSummary}.
(Contributed by Robert Collins in bpo-17911@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17911}.)

Both the @ref{1080,,print_tb()} and @ref{1081,,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<6>,unicodedata<9>,traceback<5>,改進的模組<9>
@anchor{whatsnew/3 5 types}@anchor{1082}
@subsubsection types


A new @ref{1083,,coroutine()} function to transform
@ref{dd4,,generator} and
@ref{fd6,,generator-like} objects into
@ref{4c4,,awaitables}.
(Contributed by Yury Selivanov in bpo-24017@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24017}.)

A new type called @ref{1084,,CoroutineType}, which is used for
@ref{6b2,,coroutine} objects created by @ref{7e6,,async def} functions.
(Contributed by Yury Selivanov in bpo-24400@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24400}.)

@node unicodedata<9>,unittest<9>,types<6>,改進的模組<9>
@anchor{whatsnew/3 5 unicodedata}@anchor{1085}
@subsubsection unicodedata


@ref{10b,,unicodedata} 模組現在使用來自 Unicode 8.0.0@footnote{https://unicode.org/versions/Unicode8.0.0/} 的資料。

@node unittest<9>,unittest mock<3>,unicodedata<9>,改進的模組<9>
@anchor{whatsnew/3 5 unittest}@anchor{1086}
@subsubsection unittest


The @ref{58e,,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{1087,,TestLoader.errors} attribute of the
@ref{58d,,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<9>,改進的模組<9>
@anchor{whatsnew/3 5 unittest-mock}@anchor{1088}
@subsubsection unittest.mock


@ref{c36,,Mock} 類別有以下改進：


@itemize *

@item 
The class constructor has a new `unsafe' parameter, which causes mock
objects to raise @ref{5e8,,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{1089,,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{108a,,MagicMock} class now supports
@ref{108b,,__truediv__()}, @ref{108c,,__divmod__()}
and @ref{f74,,__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{108d,,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>,改進的模組<9>
@anchor{whatsnew/3 5 urllib}@anchor{108e}
@subsubsection urllib


A new
@ref{108f,,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{1090,,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{306,,request.urlopen()} function accepts an
@ref{355,,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{1091,,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>,改進的模組<9>
@anchor{whatsnew/3 5 wsgiref}@anchor{1092}
@subsubsection wsgiref


The `headers' argument of the @ref{1093,,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,改進的模組<9>
@anchor{whatsnew/3 5 xmlrpc}@anchor{1094}
@subsubsection xmlrpc


The @ref{c43,,client.ServerProxy} class now supports
the @ref{1e1,,context manager} protocol.
(Contributed by Claudiu Popa in bpo-20627@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20627}.)

The @ref{c43,,client.ServerProxy} constructor now accepts
an optional @ref{355,,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>,改進的模組<9>
@anchor{whatsnew/3 5 xml-sax}@anchor{1095}
@subsubsection xml.sax


SAX parsers now support a character stream of the
@ref{1096,,xmlreader.InputSource} object.
(Contributed by Serhiy Storchaka in bpo-2175@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2175}.)

@ref{1097,,parseString()} 現在接受一個 @ref{169,,str} 實例。（由 Serhiy Storchaka 在 bpo-10590@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10590} 中貢獻。）

@node zipfile<5>,,xml sax,改進的模組<9>
@anchor{whatsnew/3 5 zipfile}@anchor{1098}
@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{655,,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 其他模組層級的變更,最佳化<10>,改進的模組<9>,Python 3 5 有什麼新功能
@anchor{whatsnew/3 5 other-module-level-changes}@anchor{1099}
@subsection 其他模組層級的變更


Many functions in the @ref{94,,mmap}, @code{ossaudiodev}, @ref{d1,,socket},
@ref{d5,,ssl}, and @ref{1c,,codecs} modules now accept writable
@ref{193,,bytes-like objects}.
(Contributed by Serhiy Storchaka in bpo-23001@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23001}.)

@node 最佳化<10>,建置和 C API 變更<3>,其他模組層級的變更,Python 3 5 有什麼新功能
@anchor{whatsnew/3 5 optimizations}@anchor{109a}
@subsection 最佳化


The @ref{6c9,,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{c4b,,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{84,,ipaddress} @ref{509,,IPv4Network} and
@ref{50a,,IPv6Network} have been massively sped up, such as
@ref{109b,,subnets()}, @ref{109c,,supernet()},
@ref{109d,,summarize_address_range()}, @ref{109e,,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{84,,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{109f,,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{10a0,,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{f3c,,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{10a1,,PyObject_IsInstance()} and @ref{10a2,,PyObject_IsSubclass()}
functions have been sped up in the common case that the second argument
has @ref{f3f,,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{bd,,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{4ae,,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}.)

@ref{213,,fractions.Fraction} 的實例化現在快了 30%。（由 Stefan Behnel 在 bpo-22464@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22464} 中貢獻。）

String methods @ref{10a3,,find()}, @ref{10a4,,rfind()}, @ref{10a5,,split()},
@ref{10a6,,partition()} and the @ref{349,,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 建置和 C API 變更<3>,已棄用<11>,最佳化<10>,Python 3 5 有什麼新功能
@anchor{whatsnew/3 5 build-and-c-api-changes}@anchor{10a7}
@subsection 建置和 C API 變更


新增了 @code{calloc} 函式：


@itemize *

@item 
@ref{62a,,PyMem_RawCalloc()},

@item 
@ref{10a8,,PyMem_Calloc()},

@item 
@ref{10a9,,PyObject_Calloc()}.
@end itemize

（由 Victor Stinner 在 bpo-21233@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21233} 中貢獻。）

New encoding/decoding helper functions:


@itemize *

@item 
@ref{dbb,,Py_DecodeLocale()}（取代 @code{_Py_char2wchar()}），

@item 
@ref{dbc,,Py_EncodeLocale()}（取代 @code{_Py_wchar2char()}）。
@end itemize

（由 Victor Stinner 在 bpo-18395@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18395} 中貢獻。）

A new @ref{10aa,,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{10ab,,PyErr_FormatV()} function similar to @ref{10ac,,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}.)

新增 @ref{10ad,,PyExc_RecursionError} 例外。（由 Georg Brandl 在 bpo-19235@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19235} 中貢獻。）

New @ref{10ae,,PyModule_FromDefAndSpec()}, @ref{10af,,PyModule_FromDefAndSpec2()},
and @ref{10b0,,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{10b1,,PyNumber_MatrixMultiply()} and
@ref{10b2,,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.)

@ref{c94,,PyTypeObject.tp_finalize} 插槽現在是穩定 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>} 是 Python 版本的主要號碼；對於 Python 3.5 來說這是 @code{3}。

@item 
@code{<minor>} 是 Python 版本的次要號碼；對於 Python 3.5 來說這是 @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>} 是 Python 版本的主要號碼；對於 Python 3.5 來說這是 @code{3}。

@item 
@code{<minor>} 是 Python 版本的次要號碼；對於 Python 3.5 來說這是 @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 已棄用<11>,已移除<9>,建置和 C API 變更<3>,Python 3 5 有什麼新功能
@anchor{whatsnew/3 5 deprecated}@anchor{10b3}
@subsection 已棄用


@menu
* 新關鍵字: 新關鍵字<2>. 
* 已棄用的 Python 行為: 已棄用的 Python 行為<3>. 
* 不支援的作業系統:: 
* 已棄用的 Python 模組、函式和方法: 已棄用的 Python 模組、函式和方法<3>. 

@end menu

@node 新關鍵字<2>,已棄用的 Python 行為<3>,,已棄用<11>
@anchor{whatsnew/3 5 new-keywords}@anchor{10b4}
@subsubsection 新關鍵字


@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 已棄用的 Python 行為<3>,不支援的作業系統,新關鍵字<2>,已棄用<11>
@anchor{whatsnew/3 5 deprecated-python-behavior}@anchor{10b5}
@subsubsection 已棄用的 Python 行為


Raising the @ref{df0,,StopIteration} exception inside a generator will now generate a silent
@ref{abd,,PendingDeprecationWarning}, which will become a non-silent deprecation
warning in Python 3.6 and will trigger a @ref{244,,RuntimeError} in Python 3.7.
See @ref{f16,,PEP 479; Change StopIteration handling inside generators}
for details.

@node 不支援的作業系統,已棄用的 Python 模組、函式和方法<3>,已棄用的 Python 行為<3>,已棄用<11>
@anchor{whatsnew/3 5 unsupported-operating-systems}@anchor{10b6}
@subsubsection 不支援的作業系統


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 已棄用的 Python 模組、函式和方法<3>,,不支援的作業系統,已棄用<11>
@anchor{whatsnew/3 5 deprecated-python-modules-functions-and-methods}@anchor{10b7}
@subsubsection 已棄用的 Python 模組、函式和方法


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{e6c,,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{df6,,key},
@ref{df7,,value} and
@ref{df8,,coded_value} of @ref{df9,,http.cookies.Morsel}
objects is deprecated.  Use the @ref{dfa,,set()} method
instead.  In addition, the undocumented `LegalChars' parameter of
@ref{dfa,,set()} is deprecated, and is now ignored.

Passing a format string as keyword argument `format_string' to the
@ref{df5,,format()} method of the @ref{10b8,,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{4de,,inspect.Signature} are deprecated.  Use the new
@ref{93a,,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{82,,inspect} @ref{939,,getfullargspec()},
@ref{10b9,,getcallargs()}, and @code{formatargspec()} functions are
deprecated in favor of the @ref{22f,,inspect.signature()} API. (Contributed by Yury
Selivanov in bpo-20438@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20438}.)

@ref{10ba,,getargvalues()} and @ref{10bb,,formatargvalues()} functions
were inadvertently marked as deprecated with the release of Python 3.5.0.

Use of @ref{d5b,,re.LOCALE} flag with str patterns or @ref{838,,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{58e,,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 已移除<9>,移植至 Python 3 5,已棄用<11>,Python 3 5 有什麼新功能
@anchor{whatsnew/3 5 removed}@anchor{10bc}
@subsection 已移除


@menu
* API 與功能的移除: API 與功能的移除<4>. 

@end menu

@node API 與功能的移除<4>,,,已移除<9>
@anchor{whatsnew/3 5 api-and-feature-removals}@anchor{10bd}
@subsubsection API 與功能的移除


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{62,,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 
已移除 @code{.pyo} 檔案的概念。

@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 移植至 Python 3 5,Python 3 5 4 中顯著的變更,已移除<9>,Python 3 5 有什麼新功能
@anchor{whatsnew/3 5 porting-to-python-3-5}@anchor{10be}
@subsection 移植至 Python 3.5


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

@menu
* Python 行為的改變: Python 行為的改變<3>. 
* Python API 的變更: Python API 的變更<10>. 
* C API 中的改動: C API 中的改動<8>. 

@end menu

@node Python 行為的改變<3>,Python API 的變更<10>,,移植至 Python 3 5
@anchor{whatsnew/3 5 changes-in-python-behavior}@anchor{10bf}
@subsubsection Python 行為的改變



@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{18e,,SyntaxError}, as generator
expressions must be put in parentheses if not a sole argument to a function.
@end itemize

@node Python API 的變更<10>,C API 中的改動<8>,Python 行為的改變<3>,移植至 Python 3 5
@anchor{whatsnew/3 5 changes-in-the-python-api}@anchor{10c0}
@subsubsection 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{f83,,InterruptedError} if the Python signal handler does not
raise an exception.

@item 
Before Python 3.5, a @ref{1fb,,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{1064,,ssl.SSLWantReadError} or @ref{1065,,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{a6e,,HTMLParser},
@code{HTMLParser.error()}, and the @code{HTMLParserError} exception have been
removed.  (Contributed by Ezio Melotti in bpo-15114@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15114}.)
The `convert_charrefs' argument of @ref{a6e,,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{193,,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{264,,FileNotFoundError} will no longer be raised and instead
@ref{10c1,,find_spec()} will return @code{None}
`without' caching @code{None} in @ref{7f3,,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{73,,http.client} and @ref{76,,http.server}
were refactored into a common @ref{af3,,HTTPStatus} enum.  The values in
@ref{73,,http.client} and @ref{76,,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{a63,,exec_module()}
it is now expected to also define
@ref{ea7,,create_module()} (raises a
@ref{1a3,,DeprecationWarning} now, will be an error in Python 3.6). If the loader
inherits from @ref{10c2,,importlib.abc.Loader} then there is nothing to do, else
simply define @ref{ea7,,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{59c,,re.split()} function always ignored empty pattern matches, so the
@code{"x*"} pattern worked the same as @code{"x+"}, and the @code{"\b"} pattern never
worked.  Now @ref{59c,,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{df9,,http.cookies.Morsel} dict-like interface has been made self
consistent:  morsel comparison now takes the @ref{df6,,key}
and @ref{df7,,value} into account,
@ref{10c3,,copy()} now results in a
@ref{df9,,Morsel} instance rather than a @ref{183,,dict}, and
@ref{10c4,,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{dfa,,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{351,,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{d1,,socket} module now exports the @ref{10c5,,CAN_RAW_FD_FRAMES}
constant on linux 3.6 and greater.

@item 
The @ref{1066,,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{19b,,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{cf,,smtplib} module now uses @ref{b2a,,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{10c6,,str.startswith()} and @ref{10c7,,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{be4,,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{ba,,pydoc}
module and the @ref{acb,,help()} function.
(Contributed by Serhiy Storchaka in bpo-15582@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15582}.)

@item 
Nested @ref{217,,functools.partial()} calls are now flattened.  If you were
relying on the previous behavior, you can now either add an attribute to a
@ref{217,,functools.partial()} object or you can create a subclass of
@ref{217,,functools.partial()}.
(Contributed by Alexander Belopolsky in bpo-7830@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7830}.)
@end itemize

@node C API 中的改動<8>,,Python API 的變更<10>,移植至 Python 3 5
@anchor{whatsnew/3 5 changes-in-the-c-api}@anchor{10c8}
@subsubsection 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{10c9,,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{623,,PyUnicode_FromFormat()}-like functions
to format the @ref{1c1,,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{60f,,__module__} attribute breaks pickling and
introspection, a deprecation warning is now raised for builtin types without
the @ref{60f,,__module__} attribute.  This will be an @ref{5e8,,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{c93,,PyTypeObject} was replaced with a
@ref{10ca,,tp_as_async} slot.  Refer to @ref{10cb,,Coroutine（協程）物件} for
new types, structures and functions.
@end itemize

@node Python 3 5 4 中顯著的變更,,移植至 Python 3 5,Python 3 5 有什麼新功能
@anchor{whatsnew/3 5 notable-changes-in-python-3-5-4}@anchor{10cc}
@subsection Python 3.5.4 中顯著的變更


@menu
* 新增 make regen-all 建置目標: 新增 make regen-all 建置目標<2>. 
* 移除 make touch 建置目標: 移除 make touch 建置目標<2>. 

@end menu

@node 新增 make regen-all 建置目標<2>,移除 make touch 建置目標<2>,,Python 3 5 4 中顯著的變更
@anchor{whatsnew/3 5 new-make-regen-all-build-target}@anchor{10cd}
@subsubsection 新增 @code{make regen-all} 建置目標


To simplify cross-compilation, and to ensure that CPython can reliably be
compiled without requiring an existing version of Python to already be
available, the autotools-based build system no longer attempts to implicitly
recompile generated files based on file modification times.

Instead, a new @code{make regen-all} command has been added to force regeneration
of these files when desired (e.g. after an initial version of Python has
already been built based on the pregenerated versions).

More selective regeneration targets are also defined - see
Makefile.pre.in@footnote{https://github.com/python/cpython/tree/3.14/Makefile.pre.in} for details.

（由 Victor Stinner 在 bpo-23404@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23404} 中貢獻。）


在 3.5.4 版被加入.


@node 移除 make touch 建置目標<2>,,新增 make regen-all 建置目標<2>,Python 3 5 4 中顯著的變更
@anchor{whatsnew/3 5 removal-of-make-touch-build-target}@anchor{10ce}
@subsubsection 移除 @code{make touch} 建置目標


The @code{make touch} build target previously used to request implicit regeneration
of generated files by updating their modification times has been removed.

它已被新的 @code{make regen-all} 目標取代。

（由 Victor Stinner 在 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 Python 3 4 有什麼新功能,Python 3 3 有什麼新功能,Python 3 5 有什麼新功能,Python 有什麼新功能？
@anchor{whatsnew/3 4 doc}@anchor{10cf}@anchor{whatsnew/3 4 translation-repo}@anchor{10d0}@anchor{whatsnew/3 4 what-s-new-in-python-3-4}@anchor{10d1}
@section Python 3.4 有什麼新功能


@*作者: 
R. David Murray <@email{rdmurray@@bitdance.com}> （編輯者）


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

本文介紹了 Python 3.4 與 3.3 相比多了哪些新功能。Python 3.1 已於 2014 年 3 月 16 日發布。完整詳情請見 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 發佈時程


@menu
* 發布重點摘要: 發布重點摘要<10>. 
* 新增功能: 新增功能<15>. 
* 新模組: 新模組<5>. 
* 改進的模組: 改進的模組<10>. 
* CPython 實作變更:: 
* 已棄用: 已棄用<12>. 
* 已移除: 已移除<10>. 
* 移植至 Python 3.4: 移植至 Python 3 4. 
* 3.4.3 中的變更: 3 4 3 中的變更. 

@end menu

@node 發布重點摘要<10>,新增功能<15>,,Python 3 4 有什麼新功能
@anchor{whatsnew/3 4 summary-release-highlights}@anchor{10d2}
@subsection 發布重點摘要


@c This section singles out the most important changes in Python 3.4.
@c Brevity is key.

新增語法特性：


@itemize *

@item 
Python 3.4 沒有新增任何新的語法特性。
@end itemize

其他新特性：


@itemize *

@item 
@ref{10d3,,pip should always be available} (
@geindex Python Enhancement Proposals; PEP 453
PEP 453@footnote{https://peps.python.org/pep-0453/}).

@item 
@ref{10d4,,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{10d5,,isolated mode}
(bpo-16499@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16499}).

@item 
@ref{10d6,,improvements in the handling of codecs}
that are not text encodings (multiple issues).

@item 
@ref{10d7,,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{91,,marshal} format has been made @ref{10d8,,more compact and efficient} (bpo-16475@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16475}).
@end itemize

新的函式庫模組：


@itemize *

@item 
@ref{b,,asyncio}: @ref{10d9,,新的用於非同步 IO 的臨時 API} (
@geindex Python Enhancement Proposals; PEP 3156
PEP 3156@footnote{https://peps.python.org/pep-3156/})。

@item 
@ref{59,,ensurepip}: @ref{10da,,初始建置 pip 安裝程式} (
@geindex Python Enhancement Proposals; PEP 453
PEP 453@footnote{https://peps.python.org/pep-0453/})。

@item 
@ref{5a,,enum}: @ref{10db,,支援列舉型別} (
@geindex Python Enhancement Proposals; PEP 435
PEP 435@footnote{https://peps.python.org/pep-0435/})。

@item 
@ref{a8,,pathlib}: @ref{10dc,,物件導向檔案系統路徑} (
@geindex Python Enhancement Proposals; PEP 428
PEP 428@footnote{https://peps.python.org/pep-0428/})。

@item 
@ref{c7,,selectors}: @ref{10dd,,High-level and efficient I/O multiplexing}, built upon the @ref{c6,,select} module primitives (part
of 
@geindex Python Enhancement Proposals; PEP 3156
PEP 3156@footnote{https://peps.python.org/pep-3156/}).

@item 
@ref{d7,,statistics}: A basic @ref{10de,,numerically stable statistics library} (
@geindex Python Enhancement Proposals; PEP 450
PEP 450@footnote{https://peps.python.org/pep-0450/}).

@item 
@ref{105,,tracemalloc}: @ref{10df,,追蹤 Python 記憶體配置} (
@geindex Python Enhancement Proposals; PEP 454
PEP 454@footnote{https://peps.python.org/pep-0454/})。
@end itemize

顯著改進的函式庫模組：


@itemize *

@item 
@ref{10e0,,Single-dispatch generic functions} in
@ref{63,,functools} (
@geindex Python Enhancement Proposals; PEP 443
PEP 443@footnote{https://peps.python.org/pep-0443/}).

@item 
新的 @ref{ab,,pickle} @ref{10e1,,協定 4} (
@geindex Python Enhancement Proposals; PEP 3154
PEP 3154@footnote{https://peps.python.org/pep-3154/})。

@item 
@ref{98,,multiprocessing} 現在有@ref{10e2,,一個選項可以避免在 Unix 上使用 os.fork} (bpo-8713@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8713})。

@item 
@ref{3f,,email} has a new submodule, @ref{41,,contentmanager}, and
a new @ref{57b,,Message} subclass
(@ref{57a,,EmailMessage}) that @ref{10e3,,simplify MIME handling} (bpo-18891@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18891}).

@item 
The @ref{82,,inspect} and @ref{ba,,pydoc} modules are now capable of
correct introspection of a much wider variety of callable objects,
which improves the output of the Python @ref{acb,,help()} system.

@item 
@ref{84,,ipaddress} 模組 API 已宣告為穩定版本
@end itemize

安全性改進：


@itemize *

@item 
@ref{10e4,,Secure and interchangeable hash algorithm}
(
@geindex Python Enhancement Proposals; PEP 456
PEP 456@footnote{https://peps.python.org/pep-0456/}).

@item 
@ref{10d4,,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 
用於@ref{10d5,,隔離模式}的新命令列選項 (bpo-16499@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16499})。

@item 
@ref{98,,multiprocessing} now has @ref{10e2,,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 
新的 @ref{72c,,hashlib.pbkdf2_hmac()} 函式提供了基於密碼的 PKCS#5 密鑰生成函式 2@footnote{https://en.wikipedia.org/wiki/PBKDF2}。

@item 
@ref{d5,,ssl} @ref{10e5,,對 TLSv1.1 和 TLSv1.2 的支援}。

@item 
@ref{10e6,,Retrieving certificates from the Windows system cert store support} for @ref{d5,,ssl}.

@item 
@ref{10e7,,Server-side SNI (Server Name Indication) support} for @ref{d5,,ssl}.

@item 
The @ref{355,,ssl.SSLContext} class has a @ref{10e8,,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{10e9,,ssl.SSLContext.load_verify_locations()}).
@end itemize

CPython 實作改進：


@itemize *

@item 
@ref{10ea,,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{10ea,,module globals are no longer set to None during finalization} (bpo-18214@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18214}).

@item 
@ref{10eb,,Configurable memory allocators} (
@geindex Python Enhancement Proposals; PEP 445
PEP 445@footnote{https://peps.python.org/pep-0445/}).

@item 
@ref{10ec,,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 新增功能<15>,新模組<5>,發布重點摘要<10>,Python 3 4 有什麼新功能
@anchor{whatsnew/3 4 new-features}@anchor{10ed}
@subsection 新增功能


@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. 
* 編解碼器處理的改進:: 
* PEP 451：用於引入系統的 ModuleSpec 型別:: 
* 其他語言更動: 其他語言更動<10>. 

@end menu

@node PEP 453 Explicit Bootstrapping of PIP in Python Installations,PEP 446 Newly Created File Descriptors Are Non-Inheritable,,新增功能<15>
@anchor{whatsnew/3 4 pep-453-explicit-bootstrapping-of-pip-in-python-installations}@anchor{10ee}@anchor{whatsnew/3 4 whatsnew-pep-453}@anchor{10d3}
@subsubsection PEP 453: Explicit Bootstrapping of PIP in Python Installations


@menu
* Bootstrapping pip By Default:: 
* 文件更動:: 

@end menu

@node Bootstrapping pip By Default,文件更動,,PEP 453 Explicit Bootstrapping of PIP in Python Installations
@anchor{whatsnew/3 4 bootstrapping-pip-by-default}@anchor{10ef}
@subsubsection Bootstrapping pip By Default


The new @ref{59,,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{117,,venv}
module make use of the @ref{59,,ensurepip} module to make @code{pip} readily
available in virtual environments. When using the command line utility,
@code{pip} is installed by default, while when using the @ref{117,,venv} module
@ref{10f0,,API} installation of @code{pip} must be requested explicitly.

For CPython @ref{10f1,,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 文件更動,,Bootstrapping pip By Default,PEP 453 Explicit Bootstrapping of PIP in Python Installations
@anchor{whatsnew/3 4 documentation-changes}@anchor{10f2}
@subsubsection 文件更動


As part of this change, the @ref{10f3,,安裝 Python 模組} and
distributing-index sections of the documentation have been
completely redesigned as short getting started and FAQ documents. Most
packaging documentation has now been moved out to the Python Packaging
Authority maintained Python Packaging User Guide@footnote{https://packaging.python.org} and the documentation of the individual
projects.

However, as this migration is currently still incomplete, the legacy
versions of those guides remaining available as @ref{10f4,,用 setuptools 建置 C 與 C++ 擴充套件}
and @ref{10f5,,用 setuptools 建置 C 與 C++ 擴充套件}.


@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,編解碼器處理的改進,PEP 453 Explicit Bootstrapping of PIP in Python Installations,新增功能<15>
@anchor{whatsnew/3 4 pep-446-newly-created-file-descriptors-are-non-inheritable}@anchor{10f6}@anchor{whatsnew/3 4 whatsnew-pep-446}@anchor{10d4}
@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{10f7,,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{10f8,,os.get_inheritable()}、@ref{10f9,,os.set_inheritable()}

@item 
@ref{10fa,,os.get_handle_inheritable()}、@ref{10fb,,os.set_handle_inheritable()}

@item 
@ref{10fc,,socket.socket.get_inheritable()}、@ref{10fd,,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/} - 使新建立的檔案描述器不可繼承

由 Victor Stinner 撰寫 PEP 與實作。
@end table


@node 編解碼器處理的改進,PEP 451：用於引入系統的 ModuleSpec 型別,PEP 446 Newly Created File Descriptors Are Non-Inheritable,新增功能<15>
@anchor{whatsnew/3 4 codec-handling-improvements}@anchor{10d6}@anchor{whatsnew/3 4 improvements-to-codec-handling}@anchor{10fe}
@subsubsection 編解碼器處理的改進


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{169,,str},
@ref{192,,bytes} and @ref{343,,bytearray} types, has historically obscured that
fact.

As a key step in clarifying the situation, the @ref{10ff,,codecs.encode()} and
@ref{1100,,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{169,,str}, @ref{192,,bytes} and
@ref{343,,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{1101,,Binary Transforms} and @ref{1102,,Text Transforms}.

（由 Nick Coghlan 在 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} 和 bpo-19619@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19619} 中貢獻。）

@node PEP 451：用於引入系統的 ModuleSpec 型別,其他語言更動<10>,編解碼器處理的改進,新增功能<15>
@anchor{whatsnew/3 4 pep-451-a-modulespec-type-for-the-import-system}@anchor{1103}@anchor{whatsnew/3 4 whatsnew-pep-451}@anchor{10d7}
@subsubsection PEP 451：用於引入系統的 ModuleSpec 型別


@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{1104,,已棄用} section for a list of methods that should be replaced and
their replacements.

@node 其他語言更動<10>,,PEP 451：用於引入系統的 ModuleSpec 型別,新增功能<15>
@anchor{whatsnew/3 4 other-language-changes}@anchor{1105}
@subsubsection 其他語言更動


Some smaller changes made to the core Python language are:


@itemize *

@item 
Unicode database updated to UCD version 6.3.

@item 
@ref{1106,,min()} and @ref{1107,,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{1108,,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{fb3,,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{fb3,,codec} @code{cp1125}.  (Contributed by
Serhiy Storchaka in bpo-19668@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19668}.)

@item 
@ref{192,,bytes}.join() and @ref{343,,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{19b,,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{57f,,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{165,,memoryview} is now registered as a @ref{1f,,Sequence},
and supports the @ref{a5e,,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{acb,,help()} have been modified and improved in
several cases as a result of the introduction of Argument Clinic and other
changes to the @ref{82,,inspect} and @ref{ba,,pydoc} modules.

@item 
@ref{1109,,__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 新模組<5>,改進的模組<10>,新增功能<15>,Python 3 4 有什麼新功能
@anchor{whatsnew/3 4 new-modules}@anchor{110a}
@subsection 新模組


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

@end menu

@node asyncio<14>,ensurepip<2>,,新模組<5>
@anchor{whatsnew/3 4 asyncio}@anchor{110b}@anchor{whatsnew/3 4 whatsnew-asyncio}@anchor{10d9}
@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{3cf,,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

由 Guido van Rossum 撰寫 PEP 與帶領實作。
@end table


@node ensurepip<2>,enum<9>,asyncio<14>,新模組<5>
@anchor{whatsnew/3 4 ensurepip}@anchor{110c}@anchor{whatsnew/3 4 whatsnew-ensurepip}@anchor{10da}
@subsubsection ensurepip


The new @ref{59,,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{59,,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<14>,ensurepip<2>,新模組<5>
@anchor{whatsnew/3 4 enum}@anchor{110d}@anchor{whatsnew/3 4 whatsnew-enum}@anchor{10db}
@subsubsection enum


The new @ref{5a,,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{d1,,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<14>,selectors<2>,enum<9>,新模組<5>
@anchor{whatsnew/3 4 pathlib}@anchor{110e}@anchor{whatsnew/3 4 whatsnew-pathlib}@anchor{10dc}
@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{3cf,,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

由 Antoine Pitrou 撰寫 PEP 與實作。
@end table


@node selectors<2>,statistics<6>,pathlib<14>,新模組<5>
@anchor{whatsnew/3 4 selectors}@anchor{110f}@anchor{whatsnew/3 4 whatsnew-selectors}@anchor{10dd}
@subsubsection selectors


The new @ref{c7,,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{c6,,select} module primitives.

@node statistics<6>,tracemalloc<4>,selectors<2>,新模組<5>
@anchor{whatsnew/3 4 statistics}@anchor{1110}@anchor{whatsnew/3 4 whatsnew-statistics}@anchor{10de}
@subsubsection statistics


The new @ref{d7,,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

由 Steven D'Aprano 撰寫 PEP 與實作
@end table


@node tracemalloc<4>,,statistics<6>,新模組<5>
@anchor{whatsnew/3 4 tracemalloc}@anchor{1111}@anchor{whatsnew/3 4 whatsnew-tracemalloc}@anchor{10df}
@subsubsection tracemalloc


The new @ref{105,,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

由 Victor Stinner 撰寫 PEP 與實作
@end table


@node 改進的模組<10>,CPython 實作變更,新模組<5>,Python 3 4 有什麼新功能
@anchor{whatsnew/3 4 improved-modules}@anchor{1112}
@subsection 改進的模組


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

@end menu

@node abc,aifc<2>,,改進的模組<10>
@anchor{whatsnew/3 4 abc}@anchor{1113}
@subsubsection abc


New function @ref{1114,,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{1115,,ABC} has @ref{1116,,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<7>,abc,改進的模組<10>
@anchor{whatsnew/3 4 aifc}@anchor{1117}
@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{186,,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{193,,bytes-like object}.  (Contributed by Serhiy
Storchaka in bpo-8311@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8311}.)

@node argparse<7>,audioop,aifc<2>,改進的模組<10>
@anchor{whatsnew/3 4 argparse}@anchor{1118}
@subsubsection argparse


The @ref{30b,,FileType} class now accepts `encoding' and
`errors' arguments, which are passed through to @ref{315,,open()}.  (Contributed
by Lucas Maystre in bpo-11175@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11175}.)

@node audioop,base64<4>,argparse<7>,改進的模組<10>
@anchor{whatsnew/3 4 audioop}@anchor{1119}
@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{193,,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<4>,collections<6>,audioop,改進的模組<10>
@anchor{whatsnew/3 4 base64}@anchor{111a}
@subsubsection base64


The encoding and decoding functions in @ref{f,,base64} now accept any
@ref{193,,bytes-like object} in cases where it previously required a
@ref{192,,bytes} or @ref{343,,bytearray} instance.  (Contributed by Nick Coghlan in
bpo-17839@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17839}.)

New functions @ref{111b,,a85encode()}, @ref{111c,,a85decode()},
@ref{111d,,b85encode()}, and @ref{111e,,b85decode()} provide the ability to
encode and decode binary data from and to @code{Ascii85} and the git/mercurial
@code{Base85} formats, respectively.  The @code{a85} functions have options that can
be used to make them compatible with the variants of the @code{Ascii85} encoding,
including the Adobe variant.  (Contributed by Martin Morrison, the Mercurial
project, Serhiy Storchaka, and Antoine Pitrou in bpo-17618@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17618}.)

@node collections<6>,colorsys,base64<4>,改進的模組<10>
@anchor{whatsnew/3 4 collections}@anchor{111f}
@subsubsection collections


The @ref{1120,,ChainMap.new_child()} method now accepts an `m' argument specifying
the child map to add to the chain.  This allows an existing mapping and/or a
custom mapping type to be used for the child.  (Contributed by Vinay Sajip in
bpo-16613@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16613}.)

@node colorsys,contextlib<6>,collections<6>,改進的模組<10>
@anchor{whatsnew/3 4 colorsys}@anchor{1121}
@subsubsection colorsys


The number of digits in the coefficients for the RGB --- YIQ conversions have
been expanded so that they match the FCC NTSC versions.  The change in
results should be less than 1% and may better match results found elsewhere.
(Contributed by Brian Landers and Serhiy Storchaka in bpo-14323@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14323}.)

@node contextlib<6>,dbm<6>,colorsys,改進的模組<10>
@anchor{whatsnew/3 4 contextlib}@anchor{1122}
@subsubsection contextlib


The new @ref{1123,,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{fe2,,contextlib.redirect_stdout()} context manager makes it easier
for utility scripts to handle inflexible APIs that write their output to
@ref{cc4,,sys.stdout} and don't provide any options to redirect it.  Using the
context manager, the @ref{cc4,,sys.stdout} output can be redirected to any
other stream or, in conjunction with @ref{1124,,io.StringIO}, to a string.
The latter can be especially useful, for example, to capture output
from a function that was written to implement a command line interface.
It is recommended only for utility scripts because it affects the
global state of @ref{cc4,,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{1125,,discussion} of the
differences between single use, reusable and reentrant context managers.

@node dbm<6>,dis<5>,contextlib<6>,改進的模組<10>
@anchor{whatsnew/3 4 dbm}@anchor{1126}
@subsubsection dbm


@ref{1127,,dbm.open()} objects now support the context management protocol.  When
used in a @ref{186,,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<6>,改進的模組<10>
@anchor{whatsnew/3 4 dis}@anchor{1128}
@subsubsection dis


Functions @ref{1129,,show_code()}, @ref{205,,dis()}, @ref{206,,distb()}, and
@ref{207,,disassemble()} now accept a keyword-only `file' argument that
controls where they write their output.

The @ref{3c,,dis} module is now built around an @ref{203,,Instruction} class
that provides object oriented access to the details of each individual bytecode
operation.

A new method, @ref{4e7,,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{3c,,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{3c,,dis} module have been rewritten to use
these new components.

In addition, a new application-friendly class @ref{204,,Bytecode} provides
an object-oriented API for inspecting bytecode in both in human-readable form
and for iterating over instructions.  The @ref{204,,Bytecode} constructor
takes the same arguments that @ref{4e7,,get_instructions()} does (plus an
optional `current_offset'), and the resulting object can be iterated to produce
@ref{203,,Instruction} objects.  But it also has a @ref{112a,,dis}
method, equivalent to calling @ref{205,,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{204,,Bytecode} also has a class method,
@ref{112b,,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)}).

（由 Nick Coghlan、Ryan Kelly 和 Thomas Kluyver 在 bpo-11816@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11816} 中以及 Claudiu Popa 在 bpo-17916@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17916} 中貢獻。）

New function @ref{112c,,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<5>,dis<5>,改進的模組<10>
@anchor{whatsnew/3 4 doctest}@anchor{112d}
@subsubsection doctest


A new @ref{112e,,option flag}, @ref{112f,,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{3e,,doctest} command line interface now uses @ref{7,,argparse}, and has two
new options, @code{-o} and @code{-f}.  @code{-o} allows @ref{112e,,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{10c,,unittest} CLI).  (Contributed by R. David Murray in bpo-11390@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11390}.)

@ref{3e,,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<5>,filecmp,doctest<4>,改進的模組<10>
@anchor{whatsnew/3 4 email}@anchor{1130}
@subsubsection email


@ref{1131,,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{44,,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{1132,,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{57b,,Message} @ref{1133,,__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{1134,,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{10e3}
A pair of new subclasses of @ref{57b,,Message} have been added
(@ref{57a,,EmailMessage} and @ref{1135,,MIMEPart}), along with a new sub-module,
@ref{41,,contentmanager} and a new @ref{53,,policy} attribute
@ref{1136,,content_manager}.  All documentation is
currently in the new module, which is being added as part of email's new
@ref{3cf,,provisional API}.  These classes provide a number of new methods that
make extracting content from and inserting content into email messages much
easier.  For details, see the @ref{41,,contentmanager} documentation and
the @ref{1137,,email：範例}.  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<6>,email<5>,改進的模組<10>
@anchor{whatsnew/3 4 filecmp}@anchor{1138}
@subsubsection filecmp


A new @ref{1139,,clear_cache()} function provides the ability to clear the
@ref{5e,,filecmp} comparison cache, which uses @ref{26d,,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{113a,,DEFAULT_IGNORES} provides the list of
directories that are used as the default value for the `ignore' parameter of
the @ref{113b,,dircmp()} function.  (Contributed by Eli Bendersky in
bpo-15442@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15442}.)

@node functools<6>,gc<6>,filecmp,改進的模組<10>
@anchor{whatsnew/3 4 functools}@anchor{113c}
@subsubsection functools


The new @ref{218,,partialmethod()} descriptor brings partial argument
application to descriptors, just as @ref{217,,partial()} provides
for normal callables. The new descriptor also makes it easier to get
arbitrary callables (including @ref{217,,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{10e0}
The new @ref{844,,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

由 Łukasz Langa 撰寫 PEP 與實作。
@end table


@ref{113d,,total_ordering()} now supports a return value of
@ref{1a2,,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{217,,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<6>,glob<4>,functools<6>,改進的模組<10>
@anchor{whatsnew/3 4 gc}@anchor{113e}
@subsubsection gc


New function @ref{2dc,,get_stats()} returns a list of three per-generation
dictionaries containing the collections statistics since interpreter startup.
(Contributed by Antoine Pitrou in bpo-16351@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16351}.)

@node glob<4>,hashlib<6>,gc<6>,改進的模組<10>
@anchor{whatsnew/3 4 glob}@anchor{113f}
@subsubsection glob


A new function @ref{1140,,escape()} provides a way to escape special characters
in a filename so that they do not become part of the globbing expansion but are
instead matched literally.  (Contributed by Serhiy Storchaka in bpo-8402@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8402}.)

@node hashlib<6>,hmac<4>,glob<4>,改進的模組<10>
@anchor{whatsnew/3 4 hashlib}@anchor{1141}
@subsubsection hashlib


新的 @ref{72c,,hashlib.pbkdf2_hmac()} 函式提供了基於密碼的 PKCS#5 密鑰生成函式 2@footnote{https://en.wikipedia.org/wiki/PBKDF2}。（由 Christian Heimes 在 bpo-18582@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18582} 中貢獻。）

The @ref{1142,,name} attribute of @ref{6c,,hashlib} hash objects is now
a formally supported interface.  It has always existed in CPython's
@ref{6c,,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<6>,改進的模組<10>
@anchor{whatsnew/3 4 hmac}@anchor{1143}
@subsubsection hmac


@ref{6e,,hmac} now accepts @code{bytearray} as well as @code{bytes} for the `key'
argument to the @ref{c8d,,new()} function, and the `msg' parameter to both the
@ref{c8d,,new()} function and the @ref{1144,,update()} method now
accepts any type supported by the @ref{6c,,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{c8d,,hmac.new()} function may now be any hash
digest name recognized by @ref{6c,,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{1145,,block_size} and @ref{1146,,name}
attributes (and the formal documentation of the @ref{1147,,digest_size}
attribute), the @ref{6e,,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>,改進的模組<10>
@anchor{whatsnew/3 4 html}@anchor{1148}
@subsubsection html


New function @ref{b47,,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{a6e,,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{a6e,,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 與 IDLE<4>,html,改進的模組<10>
@anchor{whatsnew/3 4 http}@anchor{1149}
@subsubsection http


@ref{114a,,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{114b,,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{76,,http.server} @ref{114c,,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 與 IDLE<4>,importlib<9>,http<4>,改進的模組<10>
@anchor{whatsnew/3 4 idlelib-and-idle}@anchor{114d}
@subsubsection idlelib 與 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<9>,idlelib 與 IDLE<4>,改進的模組<10>
@anchor{whatsnew/3 4 importlib}@anchor{114e}
@subsubsection importlib


The @ref{114f,,InspectLoader} ABC defines a new method,
@ref{100d,,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{114f,,InspectLoader} also now has a default implementation
for the @ref{1150,,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{736,,reload()} function has been moved from @code{imp} to
@ref{7b,,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{81,,importlib.util} now has a @ref{730,,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{81,,importlib.util} functions @ref{351,,cache_from_source()}
and @ref{737,,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{7b,,importlib} bootstrap @ref{1151,,NamespaceLoader} now conforms to
the @ref{114f,,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{81,,importlib.util} has a new function @ref{1152,,decode_source()}
that decodes source from bytes using universal newline processing.  This is
useful for implementing @ref{1153,,InspectLoader.get_source()} methods.

@ref{ea9,,importlib.machinery.ExtensionFileLoader} now has a
@ref{1154,,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<9>,ipaddress<5>,importlib<9>,改進的模組<10>
@anchor{whatsnew/3 4 inspect}@anchor{1155}
@subsubsection inspect


The @ref{82,,inspect} module now offers a basic @ref{1156,,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{1157,,unwrap()} makes it easy to unravel wrapper function chains
created by @ref{1158,,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{5a,,enum} module, the
@ref{82,,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{939,,getfullargspec()} and @code{getargspec()}
now use the @ref{22f,,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{217,,functools.partial()} objects and more. Note that, unlike
@ref{22f,,signature()}, these functions still ignore @code{__wrapped__}
attributes, and report the already bound first argument for bound methods,
so it is still necessary to update your code to use
@ref{22f,,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{22f,,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<9>,改進的模組<10>
@anchor{whatsnew/3 4 ipaddress}@anchor{1159}
@subsubsection ipaddress


@ref{84,,ipaddress} was added to the standard library in Python 3.3 as a
@ref{3cf,,provisional API}. With the release of Python 3.4, this qualification
has been removed: @ref{84,,ipaddress} is now considered a stable API, covered
by the normal standard library requirements to maintain backwards
compatibility.

A new @ref{115a,,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>,改進的模組<10>
@anchor{whatsnew/3 4 logging}@anchor{115b}
@subsubsection logging


The @ref{115c,,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{115d,,SocketHandler} and
@ref{115e,,DatagramHandler} now support Unix domain sockets (by
setting `port' to @code{None}).  (Contributed by Vinay Sajip in commit
ce46195b56a9.)

@ref{d40,,fileConfig()} now accepts a
@ref{115f,,configparser.RawConfigParser} subclass instance for the `fname'
parameter.  This facilitates using a configuration file when logging
configuration is just a part of the overall application configuration, or where
the application modifies the configuration before passing it to
@ref{d40,,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{1160,,logging.config.listen()} function can now be validated before being
processed by supplying a verification function as the argument to the new
`verify' keyword argument.  (Contributed by Vinay Sajip in bpo-15452@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15452}.)

@node marshal<2>,mmap<3>,logging<6>,改進的模組<10>
@anchor{whatsnew/3 4 marshal}@anchor{1161}@anchor{whatsnew/3 4 whatsnew-marshal-3}@anchor{10d8}
@subsubsection marshal


The default @ref{91,,marshal} version has been bumped to 3.  The code implementing
the new version restores the Python2 behavior of recording only one copy of
interned strings and preserving the interning on deserialization, and extends
this "one copy" ability to any object type (including handling recursive
references).  This reduces both the size of @code{.pyc} files and the amount of
memory a module occupies in memory when it is loaded from a @code{.pyc} (or
@code{.pyo}) file.  (Contributed by Kristján Valur Jónsson in bpo-16475@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16475},
with additional speedups by Antoine Pitrou in bpo-19219@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19219}.)

@node mmap<3>,multiprocessing<8>,marshal<2>,改進的模組<10>
@anchor{whatsnew/3 4 mmap}@anchor{1162}
@subsubsection mmap


mmap objects are now @ref{1108,,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<3>,改進的模組<10>
@anchor{whatsnew/3 4 multiprocessing}@anchor{1163}
@subsubsection multiprocessing

@anchor{whatsnew/3 4 whatsnew-multiprocessing-no-fork}@anchor{10e2}
On Unix two new @ref{1d5,,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{1164,,get_all_start_methods()} reports all start methods
available on the platform, @ref{1165,,get_start_method()} reports
the current start method, and @ref{24b,,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{24a,,get_context()} returns a context that uses a specified
start method.  It has the same API as the @ref{98,,multiprocessing} module itself,
so you can use it to create @ref{1166,,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{c3,,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<12>,multiprocessing<8>,改進的模組<10>
@anchor{whatsnew/3 4 operator}@anchor{1167}
@subsubsection operator


New function @ref{1168,,length_hint()} provides an implementation of the
specification for how the @ref{1109,,__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<12>,pdb<8>,operator<4>,改進的模組<10>
@anchor{whatsnew/3 4 os}@anchor{1169}
@subsubsection os


There are new functions to get and set the @ref{10f7,,inheritable flag} of a file descriptor (@ref{10f8,,os.get_inheritable()},
@ref{10f9,,os.set_inheritable()}) or a Windows handle
(@ref{10fa,,os.get_handle_inheritable()}, @ref{10fb,,os.set_handle_inheritable()}).

New function @ref{4d6,,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{116a,,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{116b,,os.path.samestat()} is now available on the Windows platform (and the
@ref{116c,,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{bfe,,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{f8d,,os.open()} supports two new flags on platforms that provide them,
@ref{116d,,O_PATH} (un-opened file descriptor), and @ref{116e,,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<8>,pickle<5>,os<12>,改進的模組<10>
@anchor{whatsnew/3 4 pdb}@anchor{116f}
@subsubsection pdb


@ref{aa,,pdb} has been enhanced to handle generators, @ref{bb9,,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{1170,,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{1171,,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<5>,plistlib<2>,pdb<8>,改進的模組<10>
@anchor{whatsnew/3 4 pickle}@anchor{1172}@anchor{whatsnew/3 4 whatsnew-protocol-4}@anchor{10e1}
@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{799,,__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 協定 4

由 Antoine Pitrou 撰寫 PEP、Alexandre Vassalotti 實作。
@end table


@node plistlib<2>,poplib<3>,pickle<5>,改進的模組<10>
@anchor{whatsnew/3 4 plistlib}@anchor{1173}
@subsubsection plistlib


@ref{b0,,plistlib} now has an API that is similar to the standard pattern for
stdlib serialization protocols, with new @ref{b3f,,load()},
@ref{b41,,dump()}, @ref{b40,,loads()}, and @ref{b42,,dumps()}
functions.  (The older API is now deprecated.)  In addition to the already
supported XML plist format (@ref{1174,,FMT_XML}), it also now supports
the binary plist format (@ref{1175,,FMT_BINARY}).  (Contributed by Ronald
Oussoren and others in bpo-14455@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14455}.)

@node poplib<3>,pprint<4>,plistlib<2>,改進的模組<10>
@anchor{whatsnew/3 4 poplib}@anchor{1176}
@subsubsection poplib


Two new methods have been added to @ref{b1,,poplib}: @ref{1177,,capa()},
which returns the list of capabilities advertised by the POP server, and
@ref{1178,,stls()}, which switches a clear-text POP3 session into an
encrypted POP3 session if the POP server supports it.  (Contributed by Lorenzo
Catucci in bpo-4473@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4473}.)

@node pprint<4>,pty<2>,poplib<3>,改進的模組<10>
@anchor{whatsnew/3 4 pprint}@anchor{1179}
@subsubsection pprint


The @ref{b3,,pprint} module's @ref{117a,,PrettyPrinter} class and its
@ref{117b,,pformat()}, and @ref{a22,,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<4>,改進的模組<10>
@anchor{whatsnew/3 4 pty}@anchor{117c}
@subsubsection pty


@ref{117d,,pty.spawn()} now returns the status value from @ref{f95,,os.waitpid()} on
the child process, instead of @code{None}.  (Contributed by Gregory P. Smith.)

@node pydoc<5>,re<9>,pty<2>,改進的模組<10>
@anchor{whatsnew/3 4 pydoc}@anchor{117e}
@subsubsection pydoc


The @ref{ba,,pydoc} module is now based directly on the @ref{22f,,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{ba,,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{ba,,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{82,,inspect} module.

As the @ref{acb,,help()} builtin is based on @ref{ba,,pydoc}, the above changes also
affect the behaviour of @ref{acb,,help()}.

@node re<9>,resource,pydoc<5>,改進的模組<10>
@anchor{whatsnew/3 4 re}@anchor{117f}
@subsubsection re


New @ref{1180,,fullmatch()} function and @ref{1181,,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{1182,,regex objects} now includes the pattern
and the flags; the repr of @ref{1183,,match objects} now
includes the start, end, and the part of the string that matched.  (Contributed
by Hugo Lopes Tavares and Serhiy Storchaka in bpo-13592@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13592} and
bpo-17087@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17087}.)

@node resource,select,re<9>,改進的模組<10>
@anchor{whatsnew/3 4 resource}@anchor{1184}
@subsubsection resource


New @ref{1185,,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{1186,,RLIMIT_MSGQUEUE},
@ref{1187,,RLIMIT_NICE}, @ref{1188,,RLIMIT_RTPRIO},
@ref{1189,,RLIMIT_RTTIME}, and @ref{118a,,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{118b,,RLIMIT_SBSIZE}, @ref{118c,,RLIMIT_SWAP}, and
@ref{118d,,RLIMIT_NPTS}.  (Contributed by Claudiu Popa in
bpo-19343@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19343}.)

@node select,shelve<2>,resource,改進的模組<10>
@anchor{whatsnew/3 4 select}@anchor{118e}
@subsubsection select


@ref{118f,,epoll} objects now support the context management protocol.
When used in a @ref{186,,with} statement, the @ref{1190,,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{1191,,devpoll} objects now have @ref{1192,,fileno()} and
@ref{1193,,close()} methods, as well as a new attribute
@ref{1194,,closed}.  (Contributed by Victor Stinner in
bpo-18794@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18794}.)

@node shelve<2>,shutil<6>,select,改進的模組<10>
@anchor{whatsnew/3 4 shelve}@anchor{1195}
@subsubsection shelve


@ref{1196,,Shelf} instances may now be used in @ref{186,,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<2>,改進的模組<10>
@anchor{whatsnew/3 4 shutil}@anchor{1197}
@subsubsection shutil


@ref{c45,,copyfile()} now raises a specific @ref{1198,,Error} subclass,
@ref{1199,,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>,改進的模組<10>
@anchor{whatsnew/3 4 smtpd}@anchor{119a}
@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<10>,smtpd<3>,改進的模組<10>
@anchor{whatsnew/3 4 smtplib}@anchor{119b}
@subsubsection smtplib


@ref{119c,,SMTPException} is now a subclass of @ref{2c0,,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<10>,sqlite3<10>,smtplib<3>,改進的模組<10>
@anchor{whatsnew/3 4 socket}@anchor{119d}
@subsubsection socket


The socket module now supports the @ref{119e,,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{10f7,,inheritable flag}, @ref{10fc,,get_inheritable()} and
@ref{10fd,,set_inheritable()}.

The @code{socket.AF_*} and @code{socket.SOCK_*} constants are now enumeration values
using the new @ref{5a,,enum} module.  This allows meaningful names to be printed
during debugging, instead of integer "magic numbers".

The @ref{119f,,AF_LINK} constant is now available on BSD and OSX.

@ref{b52,,inet_pton()} and @ref{11a0,,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<10>,ssl<11>,socket<10>,改進的模組<10>
@anchor{whatsnew/3 4 sqlite3}@anchor{11a1}
@subsubsection sqlite3


A new boolean parameter to the @ref{5a0,,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<11>,stat,sqlite3<10>,改進的模組<10>
@anchor{whatsnew/3 4 ssl}@anchor{11a2}
@subsubsection ssl

@anchor{whatsnew/3 4 whatsnew-tls-11-12}@anchor{10e5}
@ref{11a3,,PROTOCOL_TLSv1_1} and @ref{11a4,,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{10e8}
New function @ref{47a,,create_default_context()} provides a standard way to
obtain an @ref{355,,SSLContext} whose settings are intended to be a
reasonable balance between compatibility and security.  These settings are
more stringent than the defaults provided by the @ref{355,,SSLContext}
constructor, and may be adjusted in the future, without prior deprecation, if
best-practice security requirements change.  The new recommended best
practice for using stdlib libraries that support SSL is to use
@ref{47a,,create_default_context()} to obtain an @ref{355,,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{355,,SSLContext} method @ref{10e9,,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{11a5,,get_default_verify_paths()} returns
a named tuple of the paths and environment variables that the
@ref{11a6,,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{355,,SSLContext} has a new method,
@ref{11a7,,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{11a8,,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{355,,SSLContext} has a new
attribute @ref{11a9,,verify_flags} that can be used to control the
certificate verification process by setting it to some combination of the new
constants @ref{11aa,,VERIFY_DEFAULT}, @ref{11ab,,VERIFY_CRL_CHECK_LEAF},
@ref{11ac,,VERIFY_CRL_CHECK_CHAIN}, or @ref{47c,,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{355,,SSLContext} method @ref{11ad,,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{11ae,,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{11af,,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{10e6}
Two new windows-only functions, @ref{11b0,,enum_certificates()} and
@ref{11b1,,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{10e7}
Support for server-side SNI (Server Name Indication) using the new
@ref{11b2,,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{11b3,,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<11>,改進的模組<10>
@anchor{whatsnew/3 4 stat}@anchor{11b4}
@subsubsection stat


The @ref{d6,,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{11b5,,ST_MODE} flags, @ref{11b6,,S_IFDOOR},
@ref{11b7,,S_IFPORT}, and @ref{11b8,,S_IFWHT}.  (Contributed by
Christian Hiemes in bpo-11016@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11016}.)

@node struct<3>,subprocess<5>,stat,改進的模組<10>
@anchor{whatsnew/3 4 struct}@anchor{11b9}
@subsubsection struct


New function @ref{11ba,,iter_unpack} and a new
@ref{11bb,,struct.Struct.iter_unpack()} method on compiled formats provide streamed
unpacking of a buffer containing repeated instances of a given format of data.
(Contributed by Antoine Pitrou in bpo-17804@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17804}.)

@node subprocess<5>,sunau<2>,struct<3>,改進的模組<10>
@anchor{whatsnew/3 4 subprocess}@anchor{11bc}
@subsubsection subprocess


@ref{11bd,,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{11be,,getoutput()} and @ref{11bf,,getstatusoutput()} now
work on Windows.  This change was actually inadvertently made in 3.3.4.
(Contributed by Tim Golden in bpo-10197@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10197}.)

@node sunau<2>,sys<12>,subprocess<5>,改進的模組<10>
@anchor{whatsnew/3 4 sunau}@anchor{11c0}
@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{186,,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{193,,bytes-like object}.  (Contributed by Serhiy Storchaka in bpo-8311@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8311}.)

@node sys<12>,tarfile<8>,sunau<2>,改進的模組<10>
@anchor{whatsnew/3 4 sys}@anchor{11c1}
@subsubsection sys


New function @ref{11c2,,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{e5d,,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{441,,interactive mode}, it checks for an @ref{11c3,,__interactivehook__} attribute
on the @ref{df,,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{1b8,,PYTHONSTARTUP} file is read, so it can be set there.  The @ref{cc,,site}
module @ref{11c4,,sets it} to a function that enables tab
completion and history saving (in @code{~/.python-history}) if the platform
supports @ref{bf,,readline}.  If you do not want this (new) behavior, you can
override it in 
@geindex PYTHONSTARTUP
@geindex 環境變數; PYTHONSTARTUP
@ref{1b8,,PYTHONSTARTUP}, @ref{cd,,sitecustomize}, or
@ref{114,,usercustomize} by deleting this attribute from @ref{df,,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<8>,textwrap,sys<12>,改進的模組<10>
@anchor{whatsnew/3 4 tarfile}@anchor{11c5}
@subsubsection tarfile


The @ref{e4,,tarfile} module now supports a simple @ref{11c6,,命令列介面} when
called as a script directly or via @code{-m}.  This can be used to create and
extract tarfile archives.  (Contributed by Berker Peksag in bpo-13477@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13477}.)

@node textwrap,threading<8>,tarfile<8>,改進的模組<10>
@anchor{whatsnew/3 4 textwrap}@anchor{11c7}
@subsubsection textwrap


The @ref{11c8,,TextWrapper} class has two new attributes/constructor
arguments: @ref{11c9,,max_lines}, which limits the number of
lines in the output, and @ref{11ca,,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{11cb,,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<8>,traceback<6>,textwrap,改進的模組<10>
@anchor{whatsnew/3 4 threading}@anchor{11cc}
@subsubsection threading


The @ref{176,,Thread} object representing the main thread can be
obtained from the new @ref{11cd,,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<7>,threading<8>,改進的模組<10>
@anchor{whatsnew/3 4 traceback}@anchor{11ce}
@subsubsection traceback


A new @ref{11cf,,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<7>,urllib<5>,traceback<6>,改進的模組<10>
@anchor{whatsnew/3 4 types}@anchor{11d0}
@subsubsection types


A new @ref{835,,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{5a,,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<10>,types<7>,改進的模組<10>
@anchor{whatsnew/3 4 urllib}@anchor{11d1}
@subsubsection urllib


@ref{111,,urllib.request} now supports @code{data:} URLs via the
@ref{11d2,,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{11d3,,Request} class
can now be specified by setting a @ref{11d4,,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{11d3,,Request} objects are now reusable: if the
@ref{11d5,,full_url} or @ref{11d6,,data}
attributes are modified, all relevant internal properties are updated.  This
means, for example, that it is now possible to use the same
@ref{11d3,,Request} object in more than one
@ref{11d7,,OpenerDirector.open()} call with different `data' arguments, or to
modify a @ref{11d3,,Request}'s @code{url} rather than recomputing it
from scratch.  There is also a new
@ref{11d8,,remove_header()} method that can be used to remove
headers from a @ref{11d3,,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{11d9,,HTTPError} objects now have a
@ref{11da,,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<10>,venv<7>,urllib<5>,改進的模組<10>
@anchor{whatsnew/3 4 unittest}@anchor{11db}
@subsubsection unittest


The @ref{2b3,,TestCase} class has a new method,
@ref{11dc,,subTest()}, that produces a context manager whose
@ref{186,,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{11dd,,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{11de,,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{11df,,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{11e0,,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{ff0,,TestSuite} now drops references to tests as soon as the test
has been run, if the test is successful.  On Python interpreters that do
garbage collection, this allows the tests to be garbage collected if nothing
else is holding a reference to the test.  It is possible to override this
behavior by creating a @ref{ff0,,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{a52,,assertLogs()},
will ensure that a given block of code emits a log message using the
@ref{8b,,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{11e1,,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{10d,,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{11e2,,mock_open()} objects now have @code{readline} and @code{readlines}
methods.  (Contributed by Toshio Kuratomi in bpo-17467@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17467}.)

@node venv<7>,wave<2>,unittest<10>,改進的模組<10>
@anchor{whatsnew/3 4 venv}@anchor{11e3}
@subsubsection venv


@ref{117,,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{56b,,EnvBuilder} and the @ref{56c,,create()} convenience function
take a new keyword argument `with_pip', which defaults to @code{False}, that
controls whether or not @ref{56b,,EnvBuilder} ensures that @code{pip} is
installed in the virtual environment.  (Contributed by Nick Coghlan in
bpo-19552@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19552} as part of the 
@geindex Python Enhancement Proposals; PEP 453
PEP 453@footnote{https://peps.python.org/pep-0453/} implementation.)

@node wave<2>,weakref<2>,venv<7>,改進的模組<10>
@anchor{whatsnew/3 4 wave}@anchor{11e4}
@subsubsection wave


The @ref{11e5,,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{b3c,,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{119,,wave} can now @ref{11e6,,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{11e7,,writeframesraw()} and
@ref{11e8,,writeframes()} methods now accept any @ref{193,,bytes-like object}.  (Contributed by Serhiy Storchaka in bpo-8311@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8311}.)

@node weakref<2>,xml etree<2>,wave<2>,改進的模組<10>
@anchor{whatsnew/3 4 weakref}@anchor{11e9}
@subsubsection weakref


New @ref{11ea,,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{c66,,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{11eb,,ref} is now
exposed via the @ref{11ec,,__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>,改進的模組<10>
@anchor{whatsnew/3 4 xml-etree}@anchor{11ed}
@subsubsection xml.etree


A new parser, @ref{11ee,,XMLPullParser}, allows a
non-blocking applications to parse XML documents.  An example can be
seen at @ref{11ef,,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{12b,,xml.etree.ElementTree} @ref{11f0,,tostring()} and
@ref{11f1,,tostringlist()} functions, and the
@ref{b3e,,ElementTree}
@ref{c83,,write()} method, now have a
`short_empty_elements' @ref{59f,,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>,改進的模組<10>
@anchor{whatsnew/3 4 zipfile}@anchor{11f2}
@subsubsection zipfile


The @ref{11f3,,writepy()} method of the
@ref{11f4,,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{8cb,,ZipFile} and
@ref{11f4,,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 實作變更,已棄用<12>,改進的模組<10>,Python 3 4 有什麼新功能
@anchor{whatsnew/3 4 cpython-implementation-changes}@anchor{11f5}
@subsection CPython 實作變更


@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. 
* 其他建置和 C API 變更:: 
* 其他改進: 其他改進<2>. 
* 顯著最佳化:: 

@end menu

@node PEP 445 Customization of CPython Memory Allocators,PEP 442 Safe Object Finalization,,CPython 實作變更
@anchor{whatsnew/3 4 pep-445-customization-of-cpython-memory-allocators}@anchor{11f6}@anchor{whatsnew/3 4 whatsnew-pep-445}@anchor{10eb}
@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

由 Victor Stinner 撰寫 PEP 與實作。
@end table


@node PEP 442 Safe Object Finalization,PEP 456 Secure and Interchangeable Hash Algorithm,PEP 445 Customization of CPython Memory Allocators,CPython 實作變更
@anchor{whatsnew/3 4 pep-442-safe-object-finalization}@anchor{11f7}@anchor{whatsnew/3 4 whatsnew-pep-442}@anchor{10ea}
@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{11f8,,__del__()} methods, as well as
generators with @ref{1b0,,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{87e,,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/} -- 安全的物件最終化

由 Antoine Pitrou 撰寫 PEP 與實作。
@end table


@node PEP 456 Secure and Interchangeable Hash Algorithm,PEP 436 Argument Clinic,PEP 442 Safe Object Finalization,CPython 實作變更
@anchor{whatsnew/3 4 pep-456-secure-and-interchangeable-hash-algorithm}@anchor{11f9}@anchor{whatsnew/3 4 whatsnew-pep-456}@anchor{10e4}
@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{11fa,,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,其他建置和 C API 變更,PEP 456 Secure and Interchangeable Hash Algorithm,CPython 實作變更
@anchor{whatsnew/3 4 pep-436-argument-clinic}@anchor{11fb}@anchor{whatsnew/3 4 whatsnew-pep-436}@anchor{10ec}
@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{ba,,pydoc} and @ref{82,,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

由 Larry Hastings 撰寫 PEP 與實作。
@end table


@node 其他建置和 C API 變更,其他改進<2>,PEP 436 Argument Clinic,CPython 實作變更
@anchor{whatsnew/3 4 other-build-and-c-api-changes}@anchor{11fc}
@subsubsection 其他建置和 C API 變更



@itemize *

@item 
The new @ref{a93,,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{623,,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{11fd,,PyStructSequence_InitType2()} supplements the
existing @ref{11fe,,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{11ff,,PyObject_LengthHint()} is the C API equivalent
of @ref{1168,,operator.length_hint()}.  (Contributed by Armin Ronacher in
bpo-16148@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16148}.)
@end itemize

@node 其他改進<2>,顯著最佳化,其他建置和 C API 變更,CPython 實作變更
@anchor{whatsnew/3 4 other-improvements}@anchor{1200}@anchor{whatsnew/3 4 other-improvements-3-4}@anchor{1201}
@subsubsection 其他改進

@anchor{whatsnew/3 4 whatsnew-isolated-mode}@anchor{10d5}

@itemize *

@item 
The @ref{1202,,python} command has a new @ref{1203,,option}, @code{-I}, which causes it to run in "isolated mode",
which means that @ref{3e2,,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{bf,,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 
@ref{1204,,python 迴歸測試套裝} 的 @code{-R} 選項現在也可以透過使用 @ref{11c2,,sys.getallocatedblocks()} 來檢查記憶體配置洩漏。（由 Antoine Pitrou 在 bpo-13390@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13390} 貢獻。）

@item 
@code{python -m} 現在可以使用於命名空間套件。

@item 
The @ref{d6,,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{e53,,__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{1205,,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{8e,,lzma}, and @ref{6b,,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 顯著最佳化,,其他改進<2>,CPython 實作變更
@anchor{whatsnew/3 4 significant-optimizations}@anchor{1206}
@subsubsection 顯著最佳化



@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{be,,re},
@ref{1e,,collections} and @ref{8a,,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{a5f,,bz2.BZ2File} is now as fast or faster than the Python2 version for
most cases.  @ref{1207,,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{1208,,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{dc,,subprocess}.  (Contributed
by Richard Oudkerk in bpo-15758@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15758}.)

@item 
@ref{1209,,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{73f,,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 已棄用<12>,已移除<10>,CPython 實作變更,Python 3 4 有什麼新功能
@anchor{whatsnew/3 4 deprecated}@anchor{120a}@anchor{whatsnew/3 4 deprecated-3-4}@anchor{1104}
@subsection 已棄用


This section covers various APIs and other features that have been deprecated
in Python 3.4, and will be removed in Python 3.5 or later.  In most (but not
all) cases, using the deprecated APIs will produce a @ref{1a3,,DeprecationWarning}
when the interpreter is run with deprecation warnings enabled (for example, by
using @code{-Wd}).

@menu
* 已棄用的 Python API:: 
* 已棄用功能:: 

@end menu

@node 已棄用的 Python API,已棄用功能,,已棄用<12>
@anchor{whatsnew/3 4 deprecations-in-the-python-api}@anchor{120b}
@subsubsection 已棄用的 Python API



@itemize *

@item 
As mentioned in @ref{10d7,,PEP 451：用於引入系統的 ModuleSpec 型別}, a number of @ref{7b,,importlib}
methods and functions are deprecated: @code{importlib.find_loader()} is
replaced by @ref{5a9,,importlib.util.find_spec()};
@code{importlib.machinery.PathFinder.find_module()} is replaced by
@ref{120c,,importlib.machinery.PathFinder.find_spec()};
@code{importlib.abc.MetaPathFinder.find_module()} is replaced by
@ref{a61,,importlib.abc.MetaPathFinder.find_spec()};
@code{importlib.abc.PathEntryFinder.find_loader()} and
@code{find_module()} are replaced by
@ref{a65,,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{a63,,importlib.abc.Loader.exec_module()},
@ref{120d,,importlib.abc.InspectLoader.exec_module()}
@ref{120e,,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{c8d,,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{62,,ftplib} module has been documented
as deprecated in its docstring for quite some time.  It now emits a
@ref{1a3,,DeprecationWarning} and will be removed completely in Python 3.5.

@item 
The undocumented `endtime' argument to @ref{edb,,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{a6e,,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{b3f,,load()}, @ref{b41,,dump()},
@ref{b40,,loads()}, and @ref{b42,,dumps()}.  @code{Data()}
is deprecated in favor of just using the @ref{192,,bytes} constructor.

@item 
The @ref{e1,,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{9b7,,io.TextIOWrapper} (if needed) and its `newline'
argument.

@item 
The `parser' argument of @ref{574,,xml.etree.ElementTree.iterparse()} has
been deprecated, as has the `html' argument of
@ref{c40,,XMLParser()}.  To prepare for the removal of the
latter, all arguments to @code{XMLParser} should be passed by keyword.
@end itemize

@node 已棄用功能,,已棄用的 Python API,已棄用<12>
@anchor{whatsnew/3 4 deprecated-features}@anchor{120f}
@subsubsection 已棄用功能



@itemize *

@item 
Running @ref{1210,,IDLE --- Python 編輯器與 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 已移除<10>,移植至 Python 3 4,已棄用<12>,Python 3 4 有什麼新功能
@anchor{whatsnew/3 4 removed}@anchor{1211}
@subsection 已移除


@menu
* 不再支援的作業系統:: 
* API 與功能的移除: API 與功能的移除<5>. 
* 程式碼的清除:: 

@end menu

@node 不再支援的作業系統,API 與功能的移除<5>,,已移除<10>
@anchor{whatsnew/3 4 operating-systems-no-longer-supported}@anchor{1212}
@subsubsection 不再支援的作業系統


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 與功能的移除<5>,程式碼的清除,不再支援的作業系統,已移除<10>
@anchor{whatsnew/3 4 api-and-feature-removals}@anchor{1213}
@subsubsection API 與功能的移除


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{7b,,importlib}.
(Contributed by Taras Lyapun in bpo-15641@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15641}.)

@item 
The `strict' argument to @ref{d2d,,HTTPConnection} and
@ref{d2e,,HTTPSConnection} has been removed.  HTTP 0.9-style
"Simple Responses" are no longer supported.

@item 
The deprecated @ref{11d3,,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{91,,marshal}.  (Contributed by Dan Riti in bpo-15480@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15480}.)

@item 
@ref{4de,,inspect.Signature}: positional-only parameters are now required
to have a valid name.

@item 
@ref{82a,,object.__format__()} no longer accepts non-empty format strings, it now
raises a @ref{198,,TypeError} instead.  Using a non-empty string has been
deprecated since Python 3.2.  This change has been made to prevent a
situation where previously working (but incorrect) code would start failing
if an object gained a __format__ method, which means that your code may now
raise a @ref{198,,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{1214,,SequenceMatcher} object
(bpo-13248@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13248}).
@end itemize

@node 程式碼的清除,,API 與功能的移除<5>,已移除<10>
@anchor{whatsnew/3 4 code-cleanups}@anchor{1215}
@subsubsection 程式碼的清除



@itemize *

@item 
The unused and undocumented internal @code{Scanner} class has been removed from
the @ref{ba,,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{d6,,stat} constants that were included in
the @ref{e4,,tarfile} module namespace have been removed.
@end itemize

@node 移植至 Python 3 4,3 4 3 中的變更,已移除<10>,Python 3 4 有什麼新功能
@anchor{whatsnew/3 4 porting-to-python-3-4}@anchor{1216}
@subsection 移植至 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:: 
* Python API 的變更: Python API 的變更<11>. 
* C API 中的改動: C API 中的改動<9>. 

@end menu

@node Changes in 'python' Command Behavior,Python API 的變更<11>,,移植至 Python 3 4
@anchor{whatsnew/3 4 changes-in-python-command-behavior}@anchor{1217}
@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{1218,,PYTHONPATH} to an empty value was `not' equivalent to not setting it
at all: setting 
@geindex PYTHONPATH
@geindex 環境變數; PYTHONPATH
@ref{1218,,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{1201,,其他改進} above).
@end itemize

@node Python API 的變更<11>,C API 中的改動<9>,Changes in 'python' Command Behavior,移植至 Python 3 4
@anchor{whatsnew/3 4 changes-in-the-python-api}@anchor{1219}
@subsubsection Python API 的變更



@itemize *

@item 
The ABCs defined in @ref{7c,,importlib.abc} now either raise the appropriate
exception or return a default value instead of raising
@ref{369,,NotImplementedError} blindly. This will only affect code calling
@ref{1a6,,super()} and falling through all the way to the ABCs. For compatibility,
catch both @ref{369,,NotImplementedError} or the appropriate exception as needed.

@item 
The module type now initializes the @ref{322,,__package__} and
@ref{33a,,__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{121a,,importlib.machinery.FrozenImporter},
or if Python 2 compatibility is necessary you can use @code{imp.is_frozen()}.

@item 
@ref{c11,,py_compile.compile()} now raises @ref{121b,,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{121c,,importlib.abc.SourceLoader.get_source()} no longer raises
@ref{653,,ImportError} when the source code being loaded triggers a
@ref{18e,,SyntaxError} or @ref{bff,,UnicodeDecodeError}. As @ref{653,,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{121d,,functools.update_wrapper()} and @ref{1158,,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{1157,,inspect.unwrap()} to access the first function in the chain that has
no @code{__wrapped__} attribute.

@item 
@ref{939,,inspect.getfullargspec()} has been reimplemented on top of
@ref{22f,,inspect.signature()} and hence handles a much wider variety of callable
objects than it did in the past. It is expected that additional builtin and
extension module callables will gain signature metadata over the course of
the Python 3.4 series. Code that assumes that
@ref{939,,inspect.getfullargspec()} will fail on non-Python callables may need
to be adjusted accordingly.

@item 
@ref{121e,,importlib.machinery.PathFinder} now passes on the current working
directory to objects in @ref{121f,,sys.path_hooks} for the empty string. This
results in @ref{7f3,,sys.path_importer_cache} never containing @code{'@w{'}}, thus
iterating through @ref{7f3,,sys.path_importer_cache} based on @ref{3e2,,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{d2d,,HTTPConnection}
and @ref{d2e,,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{18e,,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{11b3,,ssl.SSLSocket.getpeercert()} and @ref{1068,,ssl.SSLSocket.do_handshake()}
now raise an @ref{2c0,,OSError} with @code{ENOTCONN} when the @code{SSLSocket} is not
connected, instead of the previous behavior of raising an
@ref{5e8,,AttributeError}.  In addition, @ref{11b3,,getpeercert()}
will raise a @ref{2eb,,ValueError} if the handshake has not yet been done.

@item 
@ref{1220,,base64.b32decode()} now raises a @ref{1221,,binascii.Error} when the
input string contains non-b32-alphabet characters, instead of a
@ref{198,,TypeError}.  This particular @ref{198,,TypeError} was missed when the other
@ref{198,,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{2eb,,ValueError} rather than the previous more mysterious
@ref{5e8,,AttributeError} (bpo-9177@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9177}).

@item 
@ref{1222,,slice.indices()} no longer produces an @ref{a78,,OverflowError} for huge
values.  As a consequence of this fix, @ref{1222,,slice.indices()} now raises a
@ref{2eb,,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{197,,complex} constructor, unlike the @ref{19,,cmath} functions, was
incorrectly accepting @ref{196,,float} values if an object's @code{__complex__}
special method returned one.  This now raises a @ref{198,,TypeError}.
(bpo-16290@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16290}.)

@item 
The @ref{19b,,int} constructor in 3.2 and 3.3 erroneously accepts @ref{196,,float}
values for the `base' parameter.  It is unlikely anyone was doing this, but
if so, it will now raise a @ref{198,,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{4b0,,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{1223,,__kwdefaults__}.
(Contributed by Yury Selivanov in bpo-20625@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20625}.)

@item 
@ref{1142,,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{ff0,,unittest.TestSuite} now drops references to tests after they
are run, test harnesses that reuse a @ref{ff0,,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{10c,,unittest} is designed to provide.  However, if the lack
of isolation is considered acceptable, the old behavior can be restored by
creating a @ref{ff0,,TestSuite} subclass that defines a
@code{_removeTestAtIndex} method that does nothing (see
@ref{1224,,TestSuite.__iter__()}) (bpo-11798@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11798}).

@item 
@ref{10c,,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{59c,,re.split()}, @ref{1225,,re.findall()}, and @ref{59d,,re.sub()} functions, and
the @ref{1226,,group()} and @ref{1227,,groups()} methods of
@code{match} objects now always return a `bytes' object when the string
to be matched is a @ref{193,,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{a6e,,HTMLParser}
currently defaults to @code{False} for backward compatibility, but will
eventually be changed to default to @code{True}.  It is recommended that you add
this keyword, with the appropriate value, to any
@ref{a6e,,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{c8d,,hmac.new()} function will in the
future have no default, all calls to @ref{c8d,,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{174,,sysconfig.get_config_var()} with the @code{SO} key, or looking
@code{SO} up in the results of a call to @ref{298,,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{9b7,,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{f3b,,json.dump()} and @ref{f3c,,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{3e,,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
@ref{1f,,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 C API 中的改動<9>,,Python API 的變更<11>,移植至 Python 3 4
@anchor{whatsnew/3 4 changes-in-the-c-api}@anchor{1228}
@subsubsection C API 中的改動



@itemize *

@item 
@ref{1229,,PyEval_EvalFrameEx()}, @ref{122a,,PyObject_Repr()}, and
@ref{122b,,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{426,,PyErr_Fetch()} or
is being deliberately replaced with a different exception), an explicit
@ref{122c,,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{f34,,PyErr_SetImportError()} now sets @ref{198,,TypeError} when its `msg'
argument is not set. Previously only @code{NULL} was returned with no exception
set.

@item 
The result of the @ref{79e,,PyOS_ReadlineFunctionPointer} callback must
now be a string allocated by @ref{629,,PyMem_RawMalloc()} or
@ref{62b,,PyMem_RawRealloc()}, or @code{NULL} if an error occurred, instead of a
string allocated by @ref{e5b,,PyMem_Malloc()} or @ref{122d,,PyMem_Realloc()}
(bpo-16742@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16742})

@item 
@ref{439,,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{984,,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 3 4 3 中的變更,,移植至 Python 3 4,Python 3 4 有什麼新功能
@anchor{whatsnew/3 4 changed-in-3-4-3}@anchor{122e}
@subsection 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,,,3 4 3 中的變更
@anchor{whatsnew/3 4 pep-476}@anchor{122f}@anchor{whatsnew/3 4 pep-476-enabling-certificate-verification-by-default-for-stdlib-http-clients}@anchor{1230}
@subsubsection PEP 476: Enabling certificate verification by default for stdlib http clients


@ref{73,,http.client} and modules which use it, such as @ref{111,,urllib.request} and
@ref{134,,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 Python 3 3 有什麼新功能,Python 3 2 有什麼新功能,Python 3 4 有什麼新功能,Python 有什麼新功能？
@anchor{whatsnew/3 3 doc}@anchor{1231}@anchor{whatsnew/3 3 translation-repo}@anchor{1232}@anchor{whatsnew/3 3 what-s-new-in-python-3-3}@anchor{1233}
@section 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.

本文介紹了 Python 3.3 與 3.2 相比多了哪些新功能。Python 3.1 已於 2012 年 9 月 29 日發布。完整詳情請見 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 發佈時程


@menu
* 發布重點摘要: 發布重點摘要<11>. 
* PEP 405：虛擬環境:: 
* 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：適用於 Windows 的 Python 啟動器:: 
* 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：函式簽名物件:: 
* PEP 421：新增 sys.implementation: PEP 421：新增 sys implementation. 
* 使用 importlib 作為 import 的實作:: 
* 其他語言更動: 其他語言更動<11>. 
* A Finer-Grained Import Lock:: 
* 內建函式和型別:: 
* 新模組: 新模組<6>. 
* 改進的模組: 改進的模組<11>. 
* 最佳化: 最佳化<11>. 
* 建置和 C API 變更: 建置和 C API 變更<4>. 
* 已棄用: 已棄用<13>. 
* 移植到 Python 3.3: 移植到 Python 3 3. 

@end menu

@node 發布重點摘要<11>,PEP 405：虛擬環境,,Python 3 3 有什麼新功能
@anchor{whatsnew/3 3 summary-release-highlights}@anchor{1234}
@subsection 發布重點摘要


@c This section singles out the most important changes in Python 3.3.
@c Brevity is key.

新增語法特性：


@itemize *

@item 
New @code{yield from} expression for @ref{1235,,generator delegation}.

@item 
@ref{169,,str} 物件再次接受 @code{u'unicode'} 語法。
@end itemize

新的函式庫模組：


@itemize *

@item 
@ref{5c,,faulthandler} (helps debugging low-level crashes)

@item 
@ref{84,,ipaddress} (high-level objects representing IP addresses and masks)

@item 
@ref{8e,,lzma} (compress data using the XZ / LZMA algorithm)

@item 
@ref{10d,,unittest.mock} (replace parts of your system under test with mock objects)

@item 
@ref{117,,venv} (Python @ref{1236,,virtual environments}, as in the
popular @code{virtualenv} package)
@end itemize

新的內建功能：


@itemize *

@item 
重新設計 @ref{1237,,I/O 例外層次結構}。
@end itemize

實作改進：


@itemize *

@item 
Rewritten @ref{1238,,import machinery} based on @ref{7b,,importlib}.

@item 
More compact @ref{1239,,unicode strings}.

@item 
More compact @ref{123a,,attribute dictionaries}.
@end itemize

顯著改進的函式庫模組：


@itemize *

@item 
C Accelerator for the @ref{123b,,decimal} module.

@item 
Better unicode handling in the @ref{123c,,email} module
(@ref{123d,,provisional}).
@end itemize

安全性改進：


@itemize *

@item 
預設情況下，雜湊隨機化處於打開狀態。
@end itemize

Please read on for a comprehensive list of user-facing changes.

@node PEP 405：虛擬環境,PEP 420 Implicit Namespace Packages,發布重點摘要<11>,Python 3 3 有什麼新功能
@anchor{whatsnew/3 3 pep-405}@anchor{1236}@anchor{whatsnew/3 3 pep-405-virtual-environments}@anchor{123e}
@subsection PEP 405：虛擬環境


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{117,,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 虛擬環境

由 Carl Meyer 撰寫 PEP；由 Carl Meyer 與 Vinay Sajip 實作
@end table


@node PEP 420 Implicit Namespace Packages,PEP 3118 New memoryview implementation and buffer protocol documentation,PEP 405：虛擬環境,Python 3 3 有什麼新功能
@anchor{whatsnew/3 3 pep-420-implicit-namespace-packages}@anchor{123f}
@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

由 Eric V. Smith 撰寫 PEP；由 Eric V. Smith 和 Barry Warsaw 實施
@end table


@node PEP 3118 New memoryview implementation and buffer protocol documentation,PEP 393 Flexible String Representation,PEP 420 Implicit Namespace Packages,Python 3 3 有什麼新功能
@anchor{whatsnew/3 3 pep-3118-new-memoryview-implementation-and-buffer-protocol-documentation}@anchor{1240}@anchor{whatsnew/3 3 pep-3118-update}@anchor{1241}
@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
* 功能:: 
* API 變更:: 

@end menu

@node 功能,API 變更,,PEP 3118 New memoryview implementation and buffer protocol documentation
@anchor{whatsnew/3 3 features}@anchor{1242}
@subsubsection 功能



@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 變更,,功能,PEP 3118 New memoryview implementation and buffer protocol documentation
@anchor{whatsnew/3 3 api-changes}@anchor{1243}
@subsubsection API 變更



@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{1244,,Build and C API Changes} and @ref{1245,,Porting C code}.
@end itemize

（由 Stefan Krah 在 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/} - 修訂緩衝協定


@node PEP 393 Flexible String Representation,PEP 397：適用於 Windows 的 Python 啟動器,PEP 3118 New memoryview implementation and buffer protocol documentation,Python 3 3 有什麼新功能
@anchor{whatsnew/3 3 pep-393}@anchor{1239}@anchor{whatsnew/3 3 pep-393-flexible-string-representation}@anchor{1246}
@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
* 功能性:: 
* 性能和資源使用情況:: 

@end menu

@node 功能性,性能和資源使用情況,,PEP 393 Flexible String Representation
@anchor{whatsnew/3 3 functionality}@anchor{1247}
@subsubsection 功能性


@geindex Python Enhancement Proposals; PEP 393
PEP 393@footnote{https://peps.python.org/pep-0393/} 引入的更改如下：


@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{839,,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{1248,,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 
@code{./configure} 旗標 @code{--with-wide-unicode} 已被刪除。
@end itemize

@node 性能和資源使用情況,,功能性,PEP 393 Flexible String Representation
@anchor{whatsnew/3 3 performance-and-resource-usage}@anchor{1249}
@subsubsection 性能和資源使用情況


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 由 Martin von Löwis 撰寫；由 Torsten Becker 和 Martin von Löwis 實作。
@end table


@node PEP 397：適用於 Windows 的 Python 啟動器,PEP 3151 Reworking the OS and IO exception hierarchy,PEP 393 Flexible String Representation,Python 3 3 有什麼新功能
@anchor{whatsnew/3 3 pep-397}@anchor{124a}@anchor{whatsnew/3 3 pep-397-python-launcher-for-windows}@anchor{124b}
@subsection PEP 397：適用於 Windows 的 Python 啟動器


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/} - 適用於 Windows 的 Python 啟動器

由 Mark Hammond 和 Martin v. Löwis 撰寫 PEP；由 Vinay Sajip 實作。
@end table

啟動器文件：@ref{7d3,,Python 安裝管理員}

Installer PATH modification: @ref{124c,,Python 安裝管理員}


@node PEP 3151 Reworking the OS and IO exception hierarchy,PEP 380 Syntax for Delegating to a Subgenerator,PEP 397：適用於 Windows 的 Python 啟動器,Python 3 3 有什麼新功能
@anchor{whatsnew/3 3 pep-3151}@anchor{1237}@anchor{whatsnew/3 3 pep-3151-reworking-the-os-and-io-exception-hierarchy}@anchor{124d}
@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{2c0,,OSError}, @ref{124e,,IOError}, @ref{124f,,EnvironmentError},
@ref{1250,,WindowsError}, @code{mmap.error}, @ref{1251,,socket.error} or
@ref{1252,,select.error}.  All these exception types are now only one:
@ref{2c0,,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{5b,,errno} module, you can catch the adequate
@ref{2c0,,OSError} subclass.  The available subclasses are the following:


@itemize *

@item 
@ref{235,,BlockingIOError}

@item 
@ref{1253,,ChildProcessError}

@item 
@ref{1006,,ConnectionError}

@item 
@ref{121b,,FileExistsError}

@item 
@ref{264,,FileNotFoundError}

@item 
@ref{f83,,InterruptedError}

@item 
@ref{1254,,IsADirectoryError}

@item 
@ref{1255,,NotADirectoryError}

@item 
@ref{f39,,PermissionError}

@item 
@ref{1256,,ProcessLookupError}

@item 
@ref{a2f,,TimeoutError}
@end itemize

And the @ref{1006,,ConnectionError} itself has finer-grained subclasses:


@itemize *

@item 
@ref{1257,,BrokenPipeError}

@item 
@ref{1258,,ConnectionAbortedError}

@item 
@ref{1259,,ConnectionRefusedError}

@item 
@ref{125a,,ConnectionResetError}
@end itemize

Thanks to the new exceptions, common usages of the @ref{5b,,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{5b,,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

由 Antoine Pitrou 撰寫 PEP 與實作
@end table


@geindex yield;yield from（在有什麼新功能中）

@node PEP 380 Syntax for Delegating to a Subgenerator,PEP 409 Suppressing exception context,PEP 3151 Reworking the OS and IO exception hierarchy,Python 3 3 有什麼新功能
@anchor{whatsnew/3 3 pep-380}@anchor{1235}@anchor{whatsnew/3 3 pep-380-syntax-for-delegating-to-a-subgenerator}@anchor{125b}
@subsection PEP 380: Syntax for Delegating to a Subgenerator


PEP 380 adds the @code{yield from} expression, allowing a @ref{125c,,generator} to
delegate
part of its operations to another generator. This allows a section of code
containing @ref{bb9,,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,Python 3 3 有什麼新功能
@anchor{whatsnew/3 3 pep-409-suppressing-exception-context}@anchor{125d}
@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,Python 3 3 有什麼新功能
@anchor{whatsnew/3 3 pep-414-explicit-unicode-literals}@anchor{125e}
@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

由 Armin Ronacher 撰寫 PEP。
@end table


@node PEP 3155 Qualified name for classes and functions,PEP 412 Key-Sharing Dictionary,PEP 414 Explicit Unicode literals,Python 3 3 有什麼新功能
@anchor{whatsnew/3 3 pep-3155-qualified-name-for-classes-and-functions}@anchor{125f}
@subsection PEP 3155: Qualified name for classes and functions


Functions and class objects have a new @ref{1260,,__qualname__}
attribute representing
the "path" from the module top-level to their definition.  For global functions
and classes, this is the same as @ref{1261,,__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
>>> 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
>>> 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

由 Antoine Pitrou 撰寫 PEP 與實作。
@end table


@node PEP 412 Key-Sharing Dictionary,PEP 362：函式簽名物件,PEP 3155 Qualified name for classes and functions,Python 3 3 有什麼新功能
@anchor{whatsnew/3 3 pep-412}@anchor{123a}@anchor{whatsnew/3 3 pep-412-key-sharing-dictionary}@anchor{1262}
@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/} - 密鑰共享字典

由 Mark Shannon 撰寫 PEP 與實作。
@end table


@node PEP 362：函式簽名物件,PEP 421：新增 sys implementation,PEP 412 Key-Sharing Dictionary,Python 3 3 有什麼新功能
@anchor{whatsnew/3 3 pep-362-function-signature-object}@anchor{1263}
@subsection PEP 362：函式簽名物件


A new function @ref{22f,,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{217,,functools.partial()}
objects.  New classes @ref{4de,,inspect.Signature}, @ref{4df,,inspect.Parameter}
and @ref{1264,,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/}: - 函式簽名物件

PEP 由 Brett Cannon、Yury Selivanov、Larry Hastings、Jiwon Seo 撰寫；由 Yury Selivanov 實作。
@end table


@node PEP 421：新增 sys implementation,使用 importlib 作為 import 的實作,PEP 362：函式簽名物件,Python 3 3 有什麼新功能
@anchor{whatsnew/3 3 pep-421-adding-sys-implementation}@anchor{1265}
@subsection PEP 421：新增 sys.implementation


A new attribute on the @ref{df,,sys} module exposes details specific to the
implementation of the currently running interpreter.  The initial set of
attributes on @ref{734,,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{7b,,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：新增 sys implementation
@anchor{whatsnew/3 3 simplenamespace}@anchor{1266}
@subsubsection SimpleNamespace


The implementation of @code{sys.implementation} also introduces a new type to
Python: @ref{4e0,,types.SimpleNamespace}.  In contrast to a mapping-based
namespace, like @ref{183,,dict}, @code{SimpleNamespace} is attribute-based, like
@ref{c75,,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/} - 新增 sys.implementation

由 Eric Snow 撰寫 PEP 與實作。
@end table


@node 使用 importlib 作為 import 的實作,其他語言更動<11>,PEP 421：新增 sys implementation,Python 3 3 有什麼新功能
@anchor{whatsnew/3 3 importlib}@anchor{1238}@anchor{whatsnew/3 3 using-importlib-as-the-implementation-of-import}@anchor{1267}
@subsection 使用 importlib 作為 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{ac8,,__import__()} function is now powered by @ref{1268,,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{1269,,Porting Python code} section of this document.

@menu
* 新 API:: 
* 明顯的變更:: 

@end menu

@node 新 API,明顯的變更,,使用 importlib 作為 import 的實作
@anchor{whatsnew/3 3 new-apis}@anchor{126a}
@subsubsection 新 API


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{7b,,importlib} package.

The abstract base classes defined in @ref{7c,,importlib.abc} have been expanded
to properly delineate between @ref{126b,,meta path finders}
and @ref{126c,,path entry finders} by introducing
@ref{a67,,importlib.abc.MetaPathFinder} and
@ref{a68,,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{126d,,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{121f,,sys.path_hooks}.

For loaders, the new abstract base class @ref{126e,,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{126f,,importlib.machinery.SourceFileLoader}), sourceless bytecode files
(@ref{1270,,importlib.machinery.SourcelessFileLoader}), and extension modules
(@ref{ea9,,importlib.machinery.ExtensionFileLoader}) are now available for
direct use.

@ref{653,,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{e05,,importlib.invalidate_caches()} function will now call the method with
the same name on all finders cached in @ref{7f3,,sys.path_importer_cache} to help
clean up any stored state as necessary.

@node 明顯的變更,,新 API,使用 importlib 作為 import 的實作
@anchor{whatsnew/3 3 visible-changes}@anchor{1271}
@subsubsection 明顯的變更


For potential required changes to code, see the @ref{1269,,Porting Python code}
section.

Beyond the expanse of what @ref{7b,,importlib} now exposes, there are other
visible changes to import. The biggest is that @ref{f22,,sys.meta_path} and
@ref{121f,,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{7b,,importlib} and import itself is setting the attribute post-load.

@code{None} is now inserted into @ref{7f3,,sys.path_importer_cache} when no finder
can be found on @ref{121f,,sys.path_hooks}. Since @code{imp.NullImporter} is not
directly exposed on @ref{121f,,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{1269,,Porting Python code} section of this document.

（由 Brett Cannon 實作）

@node 其他語言更動<11>,A Finer-Grained Import Lock,使用 importlib 作為 import 的實作,Python 3 3 有什麼新功能
@anchor{whatsnew/3 3 other-language-changes}@anchor{1272}
@subsection 其他語言更動


對核心 Python 語言所做的一些較小的更改包括：


@itemize *

@item 
Added support for Unicode name aliases and named sequences.
Both @ref{1273,,unicodedata.lookup()} and @code{'\N@{...@}'} now resolve name aliases,
and @ref{1273,,unicodedata.lookup()} resolves named sequences too.

（由 Ezio Melotti 在 bpo-12753@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12753} 中貢獻。）

@item 
Unicode 資料庫更新至 UCD 版本 6.1.0

@item 
Equality comparisons on @ref{b34,,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{192,,bytes} and @ref{343,,bytearray} objects now accept an
integer between 0 and 255 as their first argument.

（由 Petri Lehtinen 在 bpo-12170@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12170} 中貢獻。）

@item 
The @code{rjust()}, @code{ljust()}, and @code{center()} methods of @ref{192,,bytes}
and @ref{343,,bytearray} now accept a @ref{343,,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{24d,,list} and @ref{343,,bytearray}:
@code{copy()} and @code{clear()} (bpo-10516@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10516}).  Consequently,
@ref{4ba,,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"..."}.

（由 Antoine Pitrou 在 bpo-13748@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13748} 中貢獻。）

@item 
@ref{1274,,dict.setdefault()} now does only one lookup for the given key, making
it atomic when used with built-in types.

（由 Filip Gruszczyński 在 bpo-13521@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13521} 中貢獻。）

@item 
The error messages produced when a function call does not match the function
signature have been significantly improved.

（由 Benjamin Peterson 貢獻。）
@end itemize

@node A Finer-Grained Import Lock,內建函式和型別,其他語言更動<11>,Python 3 3 有什麼新功能
@anchor{whatsnew/3 3 a-finer-grained-import-lock}@anchor{1275}
@subsection A Finer-Grained Import Lock


Previous versions of CPython have always relied on a global import lock.
This led to unexpected annoyances, such as deadlocks when importing a module
would trigger code execution in a different thread as a side-effect.
Clumsy workarounds were sometimes employed, such as the
@ref{3d9,,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.

（由 Antoine Pitrou 在 bpo-9260@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9260} 中貢獻。）

@node 內建函式和型別,新模組<6>,A Finer-Grained Import Lock,Python 3 3 有什麼新功能
@anchor{whatsnew/3 3 builtin-functions-and-types}@anchor{1276}
@subsection 內建函式和型別



@itemize *

@item 
@ref{315,,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{1277,,os.O_CLOEXEC} for
example. The @code{'x'} mode was added: open for exclusive creation, failing if
the file already exists.

@item 
@ref{1170,,print()}: added the `flush' keyword argument. If the `flush' keyword
argument is true, the stream is forcibly flushed.

@item 
@ref{7fa,,hash()}: hash randomization is enabled by default, see
@ref{cea,,object.__hash__()} and 
@geindex PYTHONHASHSEED
@geindex 環境變數; PYTHONHASHSEED
@ref{1278,,PYTHONHASHSEED}.

@item 
The @ref{169,,str} type gets a new @ref{fd1,,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 新模組<6>,改進的模組<11>,內建函式和型別,Python 3 3 有什麼新功能
@anchor{whatsnew/3 3 new-modules}@anchor{1279}
@subsection 新模組


@menu
* faulthandler: faulthandler<5>. 
* ipaddress: ipaddress<6>. 
* lzma: lzma<2>. 

@end menu

@node faulthandler<5>,ipaddress<6>,,新模組<6>
@anchor{whatsnew/3 3 faulthandler}@anchor{127a}
@subsubsection faulthandler


This new debug module @ref{5c,,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{20f,,faulthandler.enable()} to install fault handlers for the
@ref{127b,,SIGSEGV}, @ref{127c,,SIGFPE}, @ref{127d,,SIGABRT},
@ref{127e,,SIGBUS}, and @ref{127f,,SIGILL} signals.
You can also enable them at startup by setting the 
@geindex PYTHONFAULTHANDLER
@geindex 環境變數; PYTHONFAULTHANDLER
@ref{1280,,PYTHONFAULTHANDLER}
environment variable or by using @ref{16f,,-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<5>,新模組<6>
@anchor{whatsnew/3 3 ipaddress}@anchor{1281}
@subsubsection ipaddress


The new @ref{84,,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).

（由 Google 和 Peter Moody 在 
@geindex Python Enhancement Proposals; PEP 3144
PEP 3144@footnote{https://peps.python.org/pep-3144/} 中貢獻。）

@node lzma<2>,,ipaddress<6>,新模組<6>
@anchor{whatsnew/3 3 lzma}@anchor{1282}
@subsubsection lzma


The newly added @ref{8e,,lzma} module provides data compression and decompression
using the LZMA algorithm, including support for the @code{.xz} and @code{.lzma}
file formats.

（由 Nadeem Vawda 和 Per Øyvind Karlsen 在 bpo-6715@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6715} 中貢獻。）

@node 改進的模組<11>,最佳化<11>,新模組<6>,Python 3 3 有什麼新功能
@anchor{whatsnew/3 3 improved-modules}@anchor{1283}
@subsection 改進的模組


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

@end menu

@node abc<2>,array<5>,,改進的模組<11>
@anchor{whatsnew/3 3 abc}@anchor{1284}
@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{1285,,abc.abstractproperty} 已被棄用，請改 @ref{4ae,,property} 和 @ref{1286,,abc.abstractmethod()}。

@item 
@ref{1287,,abc.abstractclassmethod} 已被棄用，請改用 @ref{489,,classmethod} 和 @ref{1286,,abc.abstractmethod()}。

@item 
@ref{1288,,abc.abstractstaticmethod} 已被棄用，請改用 @ref{451,,staticmethod} 和 @ref{1286,,abc.abstractmethod()}。
@end itemize

（由 Darren Dale 在 bpo-11610@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11610} 中貢獻。）

@ref{1289,,abc.ABCMeta.register()} now returns the registered subclass, which means
it can now be used as a class decorator (bpo-10868@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10868}).

@node array<5>,base64<5>,abc<2>,改進的模組<11>
@anchor{whatsnew/3 3 array}@anchor{128a}
@subsubsection array


The @ref{8,,array} module supports the long long type using @code{q} and
@code{Q} type codes.

（由 Oren Tirosh 和 Hirokazu Yamamoto 在 bpo-1172711@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1172711} 中貢獻。）

@node base64<5>,binascii<3>,array<5>,改進的模組<11>
@anchor{whatsnew/3 3 base64}@anchor{128b}
@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<3>,bz2<2>,base64<5>,改進的模組<11>
@anchor{whatsnew/3 3 binascii}@anchor{128c}
@subsubsection binascii


In addition to the binary objects they normally accept, the @code{a2b_} functions
now all also accept ASCII-only strings as input.  (Contributed by Antoine
Pitrou in bpo-13637@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13637}.)

@node bz2<2>,codecs<2>,binascii<3>,改進的模組<11>
@anchor{whatsnew/3 3 bz2}@anchor{128d}
@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{128e,,bz2.open()} function: open a bzip2-compressed file in binary or
text mode.

@item 
@ref{a5f,,bz2.BZ2File} can now read from and write to arbitrary file-like
objects, by means of its constructor's `fileobj' argument.

（由 Nadeem Vawda 在 bpo-5863@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5863} 中貢獻。）

@item 
@ref{a5f,,bz2.BZ2File} and @ref{128f,,bz2.decompress()} can now decompress
multi-stream inputs (such as those produced by the @code{pbzip2} tool).
@ref{a5f,,bz2.BZ2File} can now also be used to create this type of file, using
the @code{'a'} (append) mode.

（由 Nir Aides 在 bpo-1625@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1625} 中貢獻。）

@item 
@ref{a5f,,bz2.BZ2File} now implements all of the @ref{89c,,io.BufferedIOBase} API,
except for the @code{detach()} and @code{truncate()} methods.
@end itemize

@node codecs<2>,collections<7>,bz2<2>,改進的模組<11>
@anchor{whatsnew/3 3 codecs}@anchor{1290}
@subsubsection codecs


The @ref{57,,mbcs} codec has been rewritten to handle correctly
@code{replace} and @code{ignore} error handlers on all Windows versions.  The
@ref{57,,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})

@code{unicode_internal} 編解碼器已被棄用。

@node collections<7>,contextlib<7>,codecs<2>,改進的模組<11>
@anchor{whatsnew/3 3 collections}@anchor{1291}
@subsubsection collections


Addition of a new @ref{e11,,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{1292,,Counter} class now supports the unary @code{+} and @code{-}
operators, as well as the in-place operators @code{+=}, @code{-=}, @code{|=}, and
@code{&=}.  (Contributed by Raymond Hettinger in bpo-13121@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13121}.)

@node contextlib<7>,crypt<2>,collections<7>,改進的模組<11>
@anchor{whatsnew/3 3 contextlib}@anchor{1293}
@subsubsection contextlib


@ref{d16,,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{f3,,threading} module).

(bpo-13585@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13585})

@node crypt<2>,curses<6>,contextlib<7>,改進的模組<11>
@anchor{whatsnew/3 3 crypt}@anchor{1294}
@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<7>,crypt<2>,改進的模組<11>
@anchor{whatsnew/3 3 curses}@anchor{1295}
@subsubsection curses



@itemize *

@item 
If the @ref{2f,,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{1296,,curses.window} 有一個新的 @ref{1297,,curses.window.encoding} 屬性。

@item 
@ref{1296,,curses.window} 類別有一個新的 @ref{1298,,get_wch()} 方法來獲取寬字元

@item 
The @ref{2f,,curses} module has a new @ref{1299,,unget_wch()} function to
push a wide character so the next @ref{1298,,get_wch()} will return
it
@end itemize

（由 Iñigo Serna 在 bpo-6755@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6755} 中貢獻。）

@node datetime<7>,decimal<4>,curses<6>,改進的模組<11>
@anchor{whatsnew/3 3 datetime}@anchor{129a}
@subsubsection datetime



@itemize *

@item 
Equality comparisons between naive and aware @ref{4dd,,datetime}
instances now return @ref{d23,,False} instead of raising @ref{198,,TypeError}
(bpo-15006@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15006}).

@item 
New @ref{129b,,datetime.datetime.timestamp()} method: Return POSIX timestamp
corresponding to the @ref{4dd,,datetime} instance.

@item 
The @ref{e89,,datetime.datetime.strftime()} method supports formatting years
older than 1000.

@item 
The @ref{bbb,,datetime.datetime.astimezone()} method can now be
called without arguments to convert datetime instance to the system
timezone.
@end itemize

@node decimal<4>,email<6>,datetime<7>,改進的模組<11>
@anchor{whatsnew/3 3 decimal}@anchor{129c}@anchor{whatsnew/3 3 new-decimal}@anchor{123b}
@subsubsection decimal



@table @asis

@item bpo-7652@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7652} - integrate fast native decimal arithmetic.

由 Stefan Krah 編寫的 C 模組和 libmpdec。
@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
* 功能: 功能<2>. 
* API 變更: API 變更<2>. 

@end menu

@node 功能<2>,API 變更<2>,,decimal<4>
@anchor{whatsnew/3 3 id1}@anchor{129d}
@subsubsection 功能



@itemize *

@item 
The @ref{129e,,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{129f,,HAVE_THREADS} is set to @code{False}.
@end itemize

@node API 變更<2>,,功能<2>,decimal<4>
@anchor{whatsnew/3 3 id2}@anchor{12a0}
@subsubsection API 變更



@itemize *

@item 
The C module has the following context limits, depending on the machine
architecture:

@quotation


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

@tab

32 位元

@tab

64 位元

@item

@ref{12a1,,MAX_PREC}

@tab

@code{425000000}

@tab

@code{999999999999999999}

@item

@ref{12a2,,MAX_EMAX}

@tab

@code{425000000}

@tab

@code{999999999999999999}

@item

@ref{12a3,,MIN_EMIN}

@tab

@code{-425000000}

@tab

@code{-999999999999999999}

@end multitable

@end quotation

@item 
In the context templates (@ref{12a4,,DefaultContext},
@ref{12a5,,BasicContext} and @ref{12a6,,ExtendedContext})
the magnitude of @ref{12a7,,Emax} and
@ref{12a8,,Emin} has changed to @code{999999}.

@item 
The @ref{1fe,,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{12a9,,InvalidOperation} is raised and the result is NaN. In the
latter case it is always possible to use @ref{12aa,,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{12ab,,exp()} and @ref{12ac,,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{12ad,,MutableMapping}.  For speed reasons,
@ref{12ae,,flags} and @ref{12af,,traps} always
refer to the same @ref{12ad,,MutableMapping} that the context
was initialized with. If a new signal dictionary is assigned,
@ref{12ae,,flags} and @ref{12af,,traps}
are updated with the new values, but they do not reference the RHS
dictionary.

@item 
Pickling a @ref{12b0,,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{12b0,,Context} constructor has been
changed to match the order displayed by @ref{1c1,,repr()}.

@item 
@ref{12b1,,quantize()} 方法中的 @code{watchexp} 參數已棄用。
@end itemize

@node email<6>,ftplib<3>,decimal<4>,改進的模組<11>
@anchor{whatsnew/3 3 email}@anchor{12b2}@anchor{whatsnew/3 3 new-email}@anchor{123c}
@subsubsection email


@menu
* Policy Framework:: 
* Provisional Policy with New Header API:: 
* 其他 API 變更:: 

@end menu

@node Policy Framework,Provisional Policy with New Header API,,email<6>
@anchor{whatsnew/3 3 policy-framework}@anchor{12b3}
@subsubsection Policy Framework


The email package now has a @ref{53,,policy} framework.  A
@ref{12b4,,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{12b5,,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{52,,parser}, or when a
@ref{57b,,Message} object is created, or when an email is
serialized using a @ref{44,,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{e92,,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{12b6,,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,其他 API 變更,Policy Framework,email<6>
@anchor{whatsnew/3 3 provisional-policy-with-new-header-api}@anchor{12b7}
@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{123d,,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{12b8,,EmailPolicy},
and add the following additional controls:


@multitable {xxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

refold_source

@tab

Controls whether or not headers parsed by a
@ref{52,,parser} are refolded by the
@ref{44,,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{45,,email.header} @ref{12b9,,decode_header()} or
@ref{12ba,,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

解碼為 unicode 是自動完成的：

@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 其他 API 變更,,Provisional Policy with New Header API,email<6>
@anchor{whatsnew/3 3 other-api-changes}@anchor{12bb}
@subsubsection 其他 API 變更


New @ref{12bc,,BytesHeaderParser}, added to the @ref{52,,parser}
module to complement @ref{12bd,,HeaderParser} and complete the Bytes
API.

新工具函式：


@itemize *

@item 
@ref{12be,,format_datetime()}: given a @ref{4dd,,datetime},
produce a string formatted for use in an email header.

@item 
@ref{12bf,,parsedate_to_datetime()}: given a date string from
an email header, convert it into an aware @ref{4dd,,datetime},
or a naive @ref{4dd,,datetime} if the offset is @code{-0000}.

@item 
@ref{2f6,,localtime()}: With no argument, returns the
current local time as an aware @ref{4dd,,datetime} using the local
@ref{12c0,,timezone}.  Given an aware @ref{4dd,,datetime},
converts it into an aware @ref{4dd,,datetime} using the
local @ref{12c0,,timezone}.
@end itemize

@node ftplib<3>,functools<7>,email<6>,改進的模組<11>
@anchor{whatsnew/3 3 ftplib}@anchor{12c1}
@subsubsection ftplib



@itemize *

@item 
@ref{aed,,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{aee,,FTP_TLS} class now provides a new
@ref{12c2,,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{12c3,,ftplib.FTP.mlsd()} method which provides a parsable directory
listing format and deprecates @ref{12c4,,ftplib.FTP.nlst()} and
@ref{12c5,,ftplib.FTP.dir()}.  (Contributed by Giampaolo Rodolà in bpo-11072@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11072}.)
@end itemize

@node functools<7>,gc<7>,ftplib<3>,改進的模組<11>
@anchor{whatsnew/3 3 functools}@anchor{12c6}
@subsubsection functools


The @ref{bd9,,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<7>,hmac<5>,functools<7>,改進的模組<11>
@anchor{whatsnew/3 3 gc}@anchor{12c7}
@subsubsection gc


It is now possible to register callbacks invoked by the garbage collector
before and after collection using the new @ref{12c8,,callbacks} list.

@node hmac<5>,http<5>,gc<7>,改進的模組<11>
@anchor{whatsnew/3 3 hmac}@anchor{12c9}
@subsubsection hmac


A new @ref{12ca,,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>,改進的模組<11>
@anchor{whatsnew/3 3 http}@anchor{12cb}
@subsubsection http


@ref{12cc,,http.server.BaseHTTPRequestHandler} now buffers the headers and writes
them all at once when @ref{12cd,,end_headers()} is
called.  A new method @ref{12ce,,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{76,,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{12cf,,http.client.HTTPResponse} now has a
@ref{12d0,,readinto()} method, which means it can be used
as an @ref{12d1,,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>,改進的模組<11>
@anchor{whatsnew/3 3 html}@anchor{12d2}
@subsubsection html


@ref{a6e,,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{12d3,,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{70,,html.entities} module.  The dictionary is
now also used by @ref{a6e,,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<10>,html<2>,改進的模組<11>
@anchor{whatsnew/3 3 imaplib}@anchor{12d4}
@subsubsection imaplib


The @ref{af7,,IMAP4_SSL} constructor now accepts an SSLContext
parameter to control parameters of the secure channel.

（由 Sijin Joseph 在 bpo-8808@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8808} 中貢獻。）

@node inspect<10>,io<8>,imaplib<4>,改進的模組<11>
@anchor{whatsnew/3 3 inspect}@anchor{12d5}
@subsubsection inspect


A new @ref{12d6,,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.

（由 Meador Inge 與 Nick Coghlan 在 bpo-13062@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13062} 中貢獻。）

A new @ref{12d7,,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.

（由 Meador Inge 於 bpo-15153@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15153} 中貢獻。）

@node io<8>,itertools<7>,inspect<10>,改進的模組<11>
@anchor{whatsnew/3 3 io}@anchor{12d8}
@subsubsection io


The @ref{739,,open()} function has a new @code{'x'} mode that can be used to
exclusively create a new file, and raise a @ref{121b,,FileExistsError} if the file
already exists. It is based on the C11 'x' mode to fopen().

（由 David Townshend 於 bpo-12760@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12760} 中貢獻。）

The constructor of the @ref{9b7,,TextIOWrapper} class has a new
`write_through' optional argument. If `write_through' is @code{True}, calls to
@code{write()} are guaranteed not to be buffered: any data
written on the @ref{9b7,,TextIOWrapper} object is immediately handled to its
underlying binary buffer.

@node itertools<7>,logging<7>,io<8>,改進的模組<11>
@anchor{whatsnew/3 3 itertools}@anchor{12d9}
@subsubsection itertools


@ref{be7,,accumulate()} now takes an optional @code{func} argument for
providing a user-supplied binary function.

@node logging<7>,math<10>,itertools<7>,改進的模組<11>
@anchor{whatsnew/3 3 logging}@anchor{12da}
@subsubsection logging


The @ref{bea,,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{865,,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<10>,mmap<4>,logging<7>,改進的模組<11>
@anchor{whatsnew/3 3 math}@anchor{12db}
@subsubsection math


The @ref{92,,math} module has a new function, @ref{12dc,,log2()},  which returns
the base-2 logarithm of `x'.

（由 Mark Dickinson 於 bpo-11888@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11888} 中撰寫）

@node mmap<4>,multiprocessing<9>,math<10>,改進的模組<11>
@anchor{whatsnew/3 3 mmap}@anchor{12dd}
@subsubsection mmap


The @ref{12de,,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<4>,改進的模組<11>
@anchor{whatsnew/3 3 multiprocessing}@anchor{12df}
@subsubsection multiprocessing


The new @ref{12e0,,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{12e1,,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{252,,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{12e2,,multiprocessing.Process.sentinel} allows a
program to wait on multiple @ref{252,,Process} objects at one
time using the appropriate OS primitives (for example, @ref{c6,,select} on
posix systems).

New methods @ref{12e3,,multiprocessing.pool.Pool.starmap()} and
@ref{12e4,,starmap_async()} provide
@ref{12e5,,itertools.starmap()} equivalents to the existing
@ref{12e6,,multiprocessing.pool.Pool.map()} and
@ref{12e7,,map_async()} functions.  (Contributed by Hynek
Schlawack in bpo-12708@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12708}.)

@node nntplib<2>,os<13>,multiprocessing<9>,改進的模組<11>
@anchor{whatsnew/3 3 nntplib}@anchor{12e8}
@subsubsection nntplib


The @code{nntplib.NNTP} class now supports the context management protocol to
unconditionally consume @ref{1251,,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

（由 Giampaolo Rodolà 於 bpo-9795@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9795} 中貢獻。）

@node os<13>,pdb<9>,nntplib<2>,改進的模組<11>
@anchor{whatsnew/3 3 os}@anchor{12e9}
@subsubsection os



@itemize *

@item 
The @ref{a5,,os} module has a new @ref{12ea,,pipe2()} function that makes it
possible to create a pipe with @ref{1277,,O_CLOEXEC} or
@ref{1036,,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{cfd,,sendfile()} function which provides
an efficient "zero-copy" way for copying data from one file (or socket)
descriptor to another. The phrase "zero-copy" refers to the fact that all of
the copying of data between the two descriptors is done entirely by the
kernel, with no copying of data into userspace buffers. @ref{cfd,,sendfile()}
can be used to efficiently copy data from a file on disk to a network socket,
e.g. for downloading a file.

（由 Ross Lagerwall 和 Giampaolo Rodolà 於 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{d4a,,fwalk()} function similar to
@ref{6c9,,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{12eb,,paths relative to directory descriptors}) and/or `follow_symlinks' (@ref{12ec,,not following symlinks}):
@ref{12ed,,access()}, @ref{12ee,,chflags()}, @ref{524,,chmod()}, @ref{12ef,,chown()},
@ref{12f0,,link()}, @ref{6c1,,lstat()}, @ref{526,,mkdir()}, @ref{f8b,,mkfifo()},
@ref{f8c,,mknod()}, @ref{f8d,,open()}, @ref{b11,,readlink()}, @ref{12f1,,remove()},
@ref{12f2,,rename()}, @ref{12f3,,replace()}, @ref{12f4,,rmdir()}, @ref{26d,,stat()},
@ref{12f5,,symlink()}, @ref{12f6,,unlink()}, @ref{12f7,,utime()}.  Platform
support for using these parameters can be checked via the sets
@ref{12f8,,os.supports_dir_fd} and @ref{12f9,,os.supports_follow_symlinks}.

@item 
The following functions now support a file descriptor for their path argument:
@ref{81a,,chdir()}, @ref{524,,chmod()}, @ref{12ef,,chown()},
@ref{12fa,,execve()}, @ref{12fb,,listdir()}, @ref{12fc,,pathconf()}, @ref{bfa,,exists()},
@ref{26d,,stat()}, @ref{12fd,,statvfs()}, @ref{12f7,,utime()}.  Platform support
for this can be checked via the @ref{12fe,,os.supports_fd} set.
@end itemize

@item 
@ref{12ed,,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{12ff,,supports_effective_ids} set.

@item 
The @ref{a5,,os} module has two new functions: @ref{1300,,getpriority()} and
@ref{1301,,setpriority()}. They can be used to get or set process
niceness/priority in a fashion similar to @ref{1302,,os.nice()} but extended to all
processes instead of just the current one.

（由 Giampaolo Rodolà 於 bpo-10784@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10784} 提交補丁。）

@item 
The new @ref{12f3,,os.replace()} function allows cross-platform renaming of a
file with overwriting the destination.  With @ref{12f2,,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{26d,,stat()}, @ref{f87,,fstat()},
and @ref{6c1,,lstat()}) now support reading a file's timestamps
with nanosecond precision.  Symmetrically, @ref{12f7,,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{1303,,os.get_terminal_size()} function queries the size of the
terminal attached to a file descriptor. See also
@ref{1304,,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{1305,,getxattr()}, @ref{1306,,listxattr()}, @ref{1307,,removexattr()},
@ref{1308,,setxattr()}.

@item 
New interface to the scheduler. These functions
control how a process is allocated CPU time by the operating system. New
functions:
@ref{1309,,sched_get_priority_max()}, @ref{130a,,sched_get_priority_min()},
@ref{130b,,sched_getaffinity()}, @ref{130c,,sched_getparam()},
@ref{130d,,sched_getscheduler()}, @ref{130e,,sched_rr_get_interval()},
@ref{130f,,sched_setaffinity()}, @ref{1310,,sched_setparam()},
@ref{1311,,sched_setscheduler()}, @ref{1312,,sched_yield()},

@item 
New functions to control the file system:


@itemize *

@item 
@ref{f8e,,posix_fadvise()}: Announces an intention to access data in a
specific pattern thus allowing the kernel to make optimizations.

@item 
@ref{f8f,,posix_fallocate()}: Ensures that enough disk space is allocated
for a file.

@item 
@ref{1313,,sync()}: Force write of everything to disk.
@end itemize

@item 
其他新的 posix 函式：


@itemize *

@item 
@ref{1314,,lockf()}: Apply, test or remove a POSIX lock on an open file descriptor.

@item 
@ref{d4e,,pread()}: Read from a file descriptor at an offset, the file
offset remains unchanged.

@item 
@ref{d51,,pwrite()}: Write to a file descriptor from an offset, leaving
the file offset unchanged.

@item 
@ref{d4d,,readv()}: Read from a file descriptor into a number of writable buffers.

@item 
@ref{1037,,truncate()}: Truncate the file corresponding to `path', so that
it is at most `length' bytes in size.

@item 
@ref{f94,,waitid()}: Wait for the completion of one or more child processes.

@item 
@ref{d50,,writev()}: Write the contents of `buffers' to a file descriptor,
where `buffers' is an arbitrary sequence of buffers.

@item 
@ref{1315,,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{1316,,times()} and @ref{1317,,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{1318,,lseek()}
function, such as @code{os.SEEK_HOLE} and @code{os.SEEK_DATA}.

@item 
New constants @ref{1319,,RTLD_LAZY}, @ref{131a,,RTLD_NOW},
@ref{131b,,RTLD_GLOBAL}, @ref{131c,,RTLD_LOCAL}, @ref{131d,,RTLD_NODELETE},
@ref{131e,,RTLD_NOLOAD}, and @ref{131f,,RTLD_DEEPBIND} are available on
platforms that support them.   These are for use with the
@ref{1320,,sys.setdlopenflags()} function, and supersede the similar constants
defined in @ref{2e,,ctypes} and @code{DLFCN}.  (Contributed by Victor Stinner
in bpo-13226@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13226}.)

@item 
@ref{12f5,,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<9>,pickle<6>,os<13>,改進的模組<11>
@anchor{whatsnew/3 3 pdb}@anchor{1321}
@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.

（由 Georg Brandl 在 bpo-14210@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14210} 中貢獻）

@node pickle<6>,pydoc<6>,pdb<9>,改進的模組<11>
@anchor{whatsnew/3 3 pickle}@anchor{1322}
@subsubsection pickle


@ref{c0a,,pickle.Pickler} objects now have an optional
@ref{1323,,dispatch_table} attribute allowing per-pickler
reduction functions to be set.

（由 Richard Oudkerk 在 bpo-14166@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14166} 中貢獻。）

@node pydoc<6>,re<10>,pickle<6>,改進的模組<11>
@anchor{whatsnew/3 3 pydoc}@anchor{1324}
@subsubsection pydoc


The Tk GUI and the @code{serve()} function have been removed from the
@ref{ba,,pydoc} module: @code{pydoc -g} and @code{serve()} have been deprecated
in Python 3.2.

@node re<10>,sched,pydoc<6>,改進的模組<11>
@anchor{whatsnew/3 3 re}@anchor{1325}
@subsubsection re


@ref{169,,str} regular expressions now support @code{\u} and @code{\U} escapes.

（由 Serhiy Storchaka 在 bpo-3665@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3665} 中貢獻。）

@node sched,select<2>,re<10>,改進的模組<11>
@anchor{whatsnew/3 3 sched}@anchor{1326}
@subsubsection sched



@itemize *

@item 
@ref{1327,,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{1328,,scheduler} in
non-blocking applications.  (Contributed by Giampaolo Rodolà in bpo-13449@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13449}.)

@item 
@ref{1328,,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{1328,,scheduler} class
constructor are now optional and defaults to @ref{557,,time.time()} and
@ref{8a4,,time.sleep()} respectively.  (Contributed by Chris Clark in
bpo-13245@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13245}.)

@item 
@ref{1329,,enter()} 和 @ref{132a,,enterabs()} `argument' 參數現在是可選的。（由 Chris Clark 在 bpo-13245@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13245} 中貢獻。）

@item 
@ref{1329,,enter()} 和 @ref{132a,,enterabs()} 現在接受 `kwargs' 參數。（由 Chris Clark 在 bpo-13245@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13245} 中貢獻。）
@end itemize

@node select<2>,shlex<3>,sched,改進的模組<11>
@anchor{whatsnew/3 3 select}@anchor{132b}
@subsubsection select


Solaris and derivative platforms have a new class @ref{1191,,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>,改進的模組<11>
@anchor{whatsnew/3 3 shlex}@anchor{132c}
@subsubsection shlex


The previously undocumented helper function @code{quote} from the
@code{pipes} modules has been moved to the @ref{c9,,shlex} module and
documented.  @ref{57c,,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>,改進的模組<11>
@anchor{whatsnew/3 3 shutil}@anchor{132d}
@subsubsection shutil



@itemize *

@item 
新功能：


@itemize *

@item 
@ref{132e,,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{543,,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{1304,,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{c47,,copy2()} and @ref{132f,,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{c48,,move()} now
handles symlinks the way the posix @code{mv} command does, recreating the
symlink rather than copying the target file contents.  (Contributed by
Jonathan Niehof in bpo-9993@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9993}.)  @ref{c48,,move()} now also returns
the @code{dst} argument as its result.

@item 
@ref{354,,rmtree()} is now resistant to symlink attacks on platforms
which support the new @code{dir_fd} parameter in @ref{f8d,,os.open()} and
@ref{12f6,,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>,改進的模組<11>
@anchor{whatsnew/3 3 signal}@anchor{1330}
@subsubsection signal



@itemize *

@item 
@ref{cb,,signal} 模組有了新的函式：


@itemize *

@item 
@ref{1331,,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{1332,,pthread_kill()}：向執行緒發送訊號；

@item 
@ref{1333,,sigpending()}：檢查未定的函式；

@item 
@ref{1334,,sigwait()}：等待訊號；

@item 
@ref{fa6,,sigwaitinfo()}：等待訊號，回傳有關該訊號的詳細資訊；

@item 
@ref{fa5,,sigtimedwait()}：類似於 @ref{fa6,,sigwaitinfo()} 但有超時。
@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{1335,,signal.signal()} 和 @ref{1336,,signal.siginterrupt()} 會引發 OSError，而不是 RuntimeError：OSError 有一個 errno 屬性。
@end itemize

@node smtpd<4>,smtplib<4>,signal<4>,改進的模組<11>
@anchor{whatsnew/3 3 smtpd}@anchor{1337}
@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<11>,smtpd<4>,改進的模組<11>
@anchor{whatsnew/3 3 smtplib}@anchor{1338}
@subsubsection smtplib


The @ref{b1e,,SMTP}, @ref{b1f,,SMTP_SSL}, and
@ref{b20,,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{b1e,,SMTP} 現在支援情境管理協定，允許在 @code{with} 陳述式中使用 @code{SMTP} 實例。（由 Giampaolo Rodolà 在 bpo-11289@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11289} 中貢獻。）

@ref{b1f,,SMTP_SSL} 構造函式和 @ref{1339,,starttls()} 方法現在接受 SSLContext 參數來控制安全通道的參數。（由 Kasun Herath 在 bpo-8809@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8809} 中貢獻。）

@node socket<11>,socketserver<3>,smtplib<4>,改進的模組<11>
@anchor{whatsnew/3 3 socket}@anchor{133a}
@subsubsection socket



@itemize *

@item 
當底層平台支援時，@ref{f9c,,socket} 類現在公開了額外的方法來處理輔助資料：


@itemize *

@item 
@ref{69a,,sendmsg()}

@item 
@ref{fa1,,recvmsg()}

@item 
@ref{133b,,recvmsg_into()}
@end itemize

（由 David Watson 在 bpo-6560@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6560} 中貢獻，其基於 Heiko Wundram 的早期補丁）

@item 
@ref{f9c,,socket} 類別現在支援 Linux (@indicateurl{https://lwn.net/Articles/253425}) 上的 PF_CAN 協定系列 (@indicateurl{https://en.wikipedia.org/wiki/Socketcan})。

（在 bpo-10141@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10141} 中由 Matthias Fuchs 貢獻、並由 Tiago Gonçalves 更新。）

@item 
@ref{f9c,,socket} 類別現在支援 PF_RDS 協定系列（@indicateurl{https://en.wikipedia.org/wiki/Reliable_Datagram_Sockets} 和 https://oss.oracle.com/projects/rds@footnote{https://web.archive.org/web/20130115155505/https://oss.oracle.com/projects/rds/}）。

@item 
@ref{f9c,,socket} 類別現在支援 OS X 上的 @code{PF_SYSTEM} 協定系列。（由 Michael Goderbauer 在 bpo-13777@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13777} 中貢獻。）

@item 
New function @ref{133c,,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<11>,socket<11>,改進的模組<11>
@anchor{whatsnew/3 3 socketserver}@anchor{133d}
@subsubsection socketserver


@ref{133e,,BaseServer} now has an overridable method
@ref{133f,,service_actions()} that is called by the
@ref{1340,,serve_forever()} method in the service loop.
@ref{d69,,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<11>,ssl<12>,socketserver<3>,改進的模組<11>
@anchor{whatsnew/3 3 sqlite3}@anchor{1341}
@subsubsection sqlite3


New @ref{548,,sqlite3.Connection} method
@ref{5a5,,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<12>,stat<2>,sqlite3<11>,改進的模組<11>
@anchor{whatsnew/3 3 ssl}@anchor{1342}
@subsubsection ssl



@itemize *

@item 
@ref{d5,,ssl} 模組有兩個新的隨機生成函式：


@itemize *

@item 
@ref{740,,RAND_bytes()}：生成加密的強偽隨機位元組。

@item 
@code{RAND_pseudo_bytes()}：生成偽隨機位元組。
@end itemize

（由 Victor Stinner 在 bpo-12049@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12049} 中貢獻。）

@item 
The @ref{d5,,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{592,,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{1343,,load_dh_params()} and
@ref{1344,,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{1345,,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{1346,,compression()} method.  The new attribute
@ref{1347,,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{356,,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{1348,,library} and @ref{1349,,reason} attributes.
(Contributed by Antoine Pitrou in bpo-14837@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14837}.)

@item 
The @ref{a36,,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{134a,,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<12>,改進的模組<11>
@anchor{whatsnew/3 3 stat}@anchor{134b}
@subsubsection stat


The undocumented tarfile.filemode function has been moved to
@ref{134c,,stat.filemode()}. It can be used to convert a file's mode to a string of
the form '-rwxrwxrwx'.

（由 Giampaolo Rodolà 在 bpo-14807@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14807} 中貢獻。）

@node struct<4>,subprocess<6>,stat<2>,改進的模組<11>
@anchor{whatsnew/3 3 struct}@anchor{134d}
@subsubsection struct


The @ref{db,,struct} module now supports @code{ssize_t} and @code{size_t} via the
new codes @code{n} and @code{N}, respectively.  (Contributed by Antoine Pitrou
in bpo-3163@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3163}.)

@node subprocess<6>,sys<13>,struct<4>,改進的模組<11>
@anchor{whatsnew/3 3 subprocess}@anchor{134e}
@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{134f,,DEVNULL} allows suppressing output in a
platform-independent fashion.  (Contributed by Ross Lagerwall in
bpo-5870@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5870}.)

@node sys<13>,tarfile<9>,subprocess<6>,改進的模組<11>
@anchor{whatsnew/3 3 sys}@anchor{1350}
@subsubsection sys


The @ref{df,,sys} module has a new @ref{1351,,thread_info} @ref{857,,named tuple} holding information about the thread implementation
(bpo-11223@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11223}).

@node tarfile<9>,tempfile<4>,sys<13>,改進的模組<11>
@anchor{whatsnew/3 3 tarfile}@anchor{1352}
@subsubsection tarfile


@ref{e4,,tarfile} 現在透過 @ref{8e,,lzma} 模組支援 @code{lzma} 編碼。（由 Lars Gustäbel 在 bpo-5689@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5689} 中貢獻。）

@node tempfile<4>,textwrap<2>,tarfile<9>,改進的模組<11>
@anchor{whatsnew/3 3 tempfile}@anchor{1353}
@subsubsection tempfile


@ref{89b,,tempfile.SpooledTemporaryFile}'s @code{truncate()} method now accepts
a @code{size} parameter.  (Contributed by Ryan Kelly in bpo-9957@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9957}.)

@node textwrap<2>,threading<9>,tempfile<4>,改進的模組<11>
@anchor{whatsnew/3 3 textwrap}@anchor{1354}
@subsubsection textwrap


The @ref{f2,,textwrap} module has a new @ref{577,,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<9>,time<8>,textwrap<2>,改進的模組<11>
@anchor{whatsnew/3 3 threading}@anchor{1355}
@subsubsection threading


@ref{1356,,threading.Condition}, @ref{1357,,threading.Semaphore},
@ref{1358,,threading.BoundedSemaphore}, @ref{1359,,threading.Event}, and
@ref{135a,,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{176,,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{135b,,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<8>,threading<9>,改進的模組<11>
@anchor{whatsnew/3 3 time}@anchor{135c}
@subsubsection time


@geindex Python Enhancement Proposals; PEP 418
PEP 418@footnote{https://peps.python.org/pep-0418/} 向 @ref{f4,,time} 模組新增了新功能：


@itemize *

@item 
@ref{135d,,get_clock_info()}：取得時鐘資訊。

@item 
@ref{556,,monotonic()}：單調時鐘（不能倒退），不受系統時鐘更新的影響。

@item 
@ref{c71,,perf_counter()}: Performance counter with the highest available
resolution to measure a short duration.

@item 
@ref{c72,,process_time()}：目前行程的系統和使用者 CPU 時間總和。
@end itemize

其他新功能：


@itemize *

@item 
@ref{135e,,clock_getres()}、@ref{135f,,clock_gettime()} 和 @ref{1360,,clock_settime()} 函式帶有 @code{CLOCK_@var{xxx}} 常數。（由 Victor Stinner 在 bpo-10278@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10278} 中貢獻。）
@end itemize

To improve cross platform consistency, @ref{8a4,,sleep()} now raises a
@ref{2eb,,ValueError} when passed a negative sleep value.  Previously this was an
error on posix, but produced an infinite sleep on Windows.

@node types<8>,unittest<11>,time<8>,改進的模組<11>
@anchor{whatsnew/3 3 types}@anchor{1361}
@subsubsection types


Add a new @ref{691,,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{1362,,types.new_class()} and @ref{1363,,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<11>,urllib<6>,types<8>,改進的模組<11>
@anchor{whatsnew/3 3 unittest}@anchor{1364}
@subsubsection unittest


@ref{749,,assertRaises()}, @ref{74b,,assertRaisesRegex()}, @ref{1365,,assertWarns()}, and
@ref{1366,,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{1367,,unittest.TestCase.run()} 現在回傳 @ref{1368,,TestResult} 物件。

@node urllib<6>,webbrowser<4>,unittest<11>,改進的模組<11>
@anchor{whatsnew/3 3 urllib}@anchor{1369}
@subsubsection urllib


The @ref{11d3,,Request} class, now accepts a `method' argument
used by @ref{136a,,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<4>,xml etree ElementTree<2>,urllib<6>,改進的模組<11>
@anchor{whatsnew/3 3 webbrowser}@anchor{136b}
@subsubsection webbrowser


The @ref{11b,,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<3>,webbrowser<4>,改進的模組<11>
@anchor{whatsnew/3 3 xml-etree-elementtree}@anchor{136c}
@subsubsection xml.etree.ElementTree


The @ref{12b,,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{361,,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<3>,,xml etree ElementTree<2>,改進的模組<11>
@anchor{whatsnew/3 3 zlib}@anchor{136d}
@subsubsection zlib


New attribute @ref{136e,,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{136f,,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 最佳化<11>,建置和 C API 變更<4>,改進的模組<11>,Python 3 3 有什麼新功能
@anchor{whatsnew/3 3 optimizations}@anchor{1370}
@subsection 最佳化


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.

（由 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} 和 bpo-15026@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15026} 貢獻。）
@end itemize

@node 建置和 C API 變更<4>,已棄用<13>,最佳化<11>,Python 3 3 有什麼新功能
@anchor{whatsnew/3 3 build-and-c-api-changes}@anchor{1244}
@subsection 建置和 C API 變更


Python 建置程序和 C API 的變更包括：


@itemize *

@item 
新的 
@geindex Python Enhancement Proposals; PEP 3118
PEP 3118@footnote{https://peps.python.org/pep-3118/} 相關功能：


@itemize *

@item 
@ref{1371,,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 
高階 API：


@itemize *

@item 
@ref{aa9,,PyUnicode_CopyCharacters()}

@item 
@ref{aad,,PyUnicode_FindChar()}

@item 
@ref{aa7,,PyUnicode_GetLength()}, @ref{aa8,,PyUnicode_GET_LENGTH}

@item 
@ref{aa0,,PyUnicode_New()}

@item 
@ref{aaa,,PyUnicode_Substring()}

@item 
@ref{1372,,PyUnicode_ReadChar()}, @ref{1373,,PyUnicode_WriteChar()}
@end itemize

@item 
低階 API：


@itemize *

@item 
@ref{1374,,Py_UCS1}、@ref{1375,,Py_UCS2}、@ref{33c,,Py_UCS4} 型別

@item 
@ref{1376,,PyASCIIObject} 和 @ref{1377,,PyCompactUnicodeObject} 結構

@item 
@ref{432,,PyUnicode_READY}

@item 
@ref{1378,,PyUnicode_FromKindAndData()}

@item 
@ref{1379,,PyUnicode_AsUCS4()}, @ref{aaf,,PyUnicode_AsUCS4Copy()}

@item 
@ref{137a,,PyUnicode_DATA}, @ref{137b,,PyUnicode_1BYTE_DATA},
@ref{137c,,PyUnicode_2BYTE_DATA}, @ref{137d,,PyUnicode_4BYTE_DATA}

@item 
@ref{137e,,PyUnicode_KIND} with @code{PyUnicode_Kind} enum:
@code{PyUnicode_WCHAR_KIND}, @ref{137f,,PyUnicode_1BYTE_KIND},
@ref{1380,,PyUnicode_2BYTE_KIND}, @ref{1381,,PyUnicode_4BYTE_KIND}

@item 
@ref{1382,,PyUnicode_READ}, @ref{1383,,PyUnicode_READ_CHAR}, @ref{1384,,PyUnicode_WRITE}

@item 
@ref{1385,,PyUnicode_MAX_CHAR_VALUE}
@end itemize
@end itemize

@item 
@ref{3bf,,PyArg_ParseTuple} 現在接受 @ref{343,,bytearray} 為 @code{c} 格式 (bpo-12380@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12380})。
@end itemize

@node 已棄用<13>,移植到 Python 3 3,建置和 C API 變更<4>,Python 3 3 有什麼新功能
@anchor{whatsnew/3 3 deprecated}@anchor{1386}
@subsection 已棄用


@menu
* 不支援的作業系統: 不支援的作業系統<2>. 
* 已棄用的 Python 模組、函式和方法: 已棄用的 Python 模組、函式和方法<4>. 
* C API 中已棄用的函式和型別:: 
* 已棄用的功能:: 

@end menu

@node 不支援的作業系統<2>,已棄用的 Python 模組、函式和方法<4>,,已棄用<13>
@anchor{whatsnew/3 3 unsupported-operating-systems}@anchor{1387}
@subsubsection 不支援的作業系統


由於缺乏維護者，OS/2 和 VMS 不再受支援。

Windows 2000 and Windows platforms which set @code{COMSPEC} to @code{command.com}
are no longer supported due to maintenance burden.

OSF 支援在 3.2 中已棄用，現已完全刪除。

@node 已棄用的 Python 模組、函式和方法<4>,C API 中已棄用的函式和型別,不支援的作業系統<2>,已棄用<13>
@anchor{whatsnew/3 3 deprecated-python-modules-functions-and-methods}@anchor{1388}
@subsubsection 已棄用的 Python 模組、函式和方法



@itemize *

@item 
Passing a non-empty string to @code{object.__format__()} is deprecated, and
will produce a @ref{198,,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{12c4,,ftplib.FTP.nlst()} 和 @ref{12c5,,ftplib.FTP.dir()}：使用 @ref{12c3,,ftplib.FTP.mlsd()}

@item 
@code{platform.popen()}：使用 @ref{dc,,subprocess} 模組。請特別檢查 @ref{1389,,Replacing Older Functions with the subprocess Module} 部分 (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{c71,,time.perf_counter()} or @ref{c72,,time.process_time()} function instead,
depending on your requirements, to have a well defined behaviour.

@item 
@code{os.stat_float_times()} 函式已棄用。

@item 
@ref{4,,abc} 模組：


@itemize *

@item 
@ref{1285,,abc.abstractproperty} 已被棄用，請改 @ref{4ae,,property} 和 @ref{1286,,abc.abstractmethod()}。

@item 
@ref{1287,,abc.abstractclassmethod} 已被棄用，請改用 @ref{489,,classmethod} 和 @ref{1286,,abc.abstractmethod()}。

@item 
@ref{1288,,abc.abstractstaticmethod} 已被棄用，請改用 @ref{451,,staticmethod} 和 @ref{1286,,abc.abstractmethod()}。
@end itemize

@item 
@ref{7b,,importlib} 套件：


@itemize *

@item 
@ref{138a,,importlib.abc.SourceLoader.path_mtime()} is now deprecated in favour of
@ref{138b,,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 C API 中已棄用的函式和型別,已棄用的功能,已棄用的 Python 模組、函式和方法<4>,已棄用<13>
@anchor{whatsnew/3 3 deprecated-functions-and-types-of-the-c-api}@anchor{138c}
@subsubsection C API 中已棄用的函式和型別


@ref{3de,,Py_UNICODE} 已被 
@geindex Python Enhancement Proposals; PEP 393
PEP 393@footnote{https://peps.python.org/pep-0393/} 棄用，並將在 Python 4 中刪除。所有使用此型別的函式均已棄用：

Unicode functions and methods using @ref{3de,,Py_UNICODE} and
@ref{3de,,Py_UNICODE}* types:


@itemize *

@item 
@code{PyUnicode_FromUnicode}：使用 @ref{138d,,PyUnicode_FromWideChar()} 或 @ref{1378,,PyUnicode_FromKindAndData()}

@item 
@code{PyUnicode_AS_UNICODE}、@code{PyUnicode_AsUnicode()}、@code{PyUnicode_AsUnicodeAndSize()}：使用 @ref{ab0,,PyUnicode_AsWideCharString()}

@item 
@code{PyUnicode_AS_DATA}：將 @ref{137a,,PyUnicode_DATA} 與 @ref{1382,,PyUnicode_READ} 和 @ref{1384,,PyUnicode_WRITE} 一起使用

@item 
@code{PyUnicode_GET_SIZE}、@code{PyUnicode_GetSize()}：使用 @ref{aa8,,PyUnicode_GET_LENGTH} 或 @ref{aa7,,PyUnicode_GetLength()}

@item 
@code{PyUnicode_GET_DATA_SIZE}：使用 @code{PyUnicode_GET_LENGTH(str) * PyUnicode_KIND(str)}（僅適用於準備好的字串）

@item 
@code{PyUnicode_AsUnicodeCopy()}：使用 @ref{aaf,,PyUnicode_AsUCS4Copy()} 或 @ref{ab0,,PyUnicode_AsWideCharString()}

@item 
@code{PyUnicode_GetMax()}
@end itemize

操作 Py_UNICODE* 字串的函式和巨集：


@itemize *

@item 
@code{Py_UNICODE_strlen()}：使用 @ref{aa7,,PyUnicode_GetLength()} 或 @ref{aa8,,PyUnicode_GET_LENGTH}

@item 
@code{Py_UNICODE_strcat()}：使用 @ref{aa9,,PyUnicode_CopyCharacters()} 或 @ref{623,,PyUnicode_FromFormat()}

@item 
@code{Py_UNICODE_strcpy()}、@code{Py_UNICODE_strncpy()}、@code{Py_UNICODE_COPY()}：使用 @ref{aa9,,PyUnicode_CopyCharacters()} 或 @ref{aaa,,PyUnicode_Substring()}

@item 
@code{Py_UNICODE_strcmp()}：使用 @ref{aab,,PyUnicode_Compare()}

@item 
@code{Py_UNICODE_strncmp()}: 使用 @ref{aac,,PyUnicode_Tailmatch()}

@item 
@code{Py_UNICODE_strchr()}, @code{Py_UNICODE_strrchr()}: 使用 @ref{aad,,PyUnicode_FindChar()}

@item 
@code{Py_UNICODE_FILL()}: 使用 @ref{138e,,PyUnicode_Fill()}

@item 
@code{Py_UNICODE_MATCH}
@end itemize

編碼器：


@itemize *

@item 
@code{PyUnicode_Encode()}：使用 @code{PyUnicode_AsEncodedObject()}

@item 
@code{PyUnicode_EncodeUTF7()}

@item 
@code{PyUnicode_EncodeUTF8()}：使用 @ref{422,,PyUnicode_AsUTF8()} 或 @ref{138f,,PyUnicode_AsUTF8String()}

@item 
@code{PyUnicode_EncodeUTF32()}

@item 
@code{PyUnicode_EncodeUTF16()}

@item 
@code{PyUnicode_EncodeUnicodeEscape()} 使用 @ref{1390,,PyUnicode_AsUnicodeEscapeString()}

@item 
@code{PyUnicode_EncodeRawUnicodeEscape()} 使用 @ref{1391,,PyUnicode_AsRawUnicodeEscapeString()}

@item 
@code{PyUnicode_EncodeLatin1()}: 使用 @ref{1392,,PyUnicode_AsLatin1String()}

@item 
@code{PyUnicode_EncodeASCII()}：使用 @ref{1393,,PyUnicode_AsASCIIString()}

@item 
@code{PyUnicode_EncodeCharmap()}

@item 
@code{PyUnicode_TranslateCharmap()}

@item 
@code{PyUnicode_EncodeMBCS()}：使用 @ref{1394,,PyUnicode_AsMBCSString()} 或 @ref{1395,,PyUnicode_EncodeCodePage()} （帶有 @code{CP_ACP} code_page）

@item 
@code{PyUnicode_EncodeDecimal()}、@code{PyUnicode_TransformDecimalToASCII()}
@end itemize

@node 已棄用的功能,,C API 中已棄用的函式和型別,已棄用<13>
@anchor{whatsnew/3 3 deprecated-features}@anchor{1396}
@subsubsection 已棄用的功能


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{3de,,Py_UNICODE}) API.

@node 移植到 Python 3 3,,已棄用<13>,Python 3 3 有什麼新功能
@anchor{whatsnew/3 3 porting-to-python-3-3}@anchor{1397}
@subsection 移植到 Python 3.3


本節列出了前面描述的更改以及可能需要你更改程式碼的其他錯誤修復。

@menu
* 移植 Python 程式碼:: 
* Porting C code:: 
* Building C extensions:: 
* 命令列開關更改:: 

@end menu

@node 移植 Python 程式碼,Porting C code,,移植到 Python 3 3
@anchor{whatsnew/3 3 porting-python-code}@anchor{1269}@anchor{whatsnew/3 3 portingpythoncode}@anchor{1398}
@subsubsection 移植 Python 程式碼



@itemize *

@item 
Hash randomization is enabled by default. Set the 
@geindex PYTHONHASHSEED
@geindex 環境變數; PYTHONHASHSEED
@ref{1278,,PYTHONHASHSEED}
environment variable to @code{0} to disable hash randomization. See also the
@ref{cea,,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{f4,,time} and @ref{34,,datetime}:
@ref{a78,,OverflowError} is now raised instead of @ref{2eb,,ValueError} if a
timestamp is out of range. @ref{2c0,,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{e05,,importlib.invalidate_caches()} to clear
out the cache for the finders to notice the new file.

@item 
@ref{653,,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{ac8,,__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{735,,importlib.import_module()} rather than call @ref{ac8,,__import__()} directly.

@item 
@ref{ac8,,__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{f22,,sys.meta_path} and @ref{121f,,sys.path_hooks} now have finders on
them by default, you will most likely want to use @ref{1399,,list.insert()} instead
of @ref{8d4,,list.append()} to add to those lists.

@item 
Because @code{None} is now inserted into @ref{7f3,,sys.path_importer_cache}, if you
are clearing out entries in the dictionary of paths that do not have a
finder, you will need to remove keys paired with values of @code{None} `and'
@code{imp.NullImporter} to be backwards-compatible. This will lead to extra
overhead on older versions of Python that re-insert @code{None} into
@ref{7f3,,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{126c,,path entry finders}.

@item 
@ref{ae,,pkgutil} has been converted to use @ref{7b,,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{139a,,pkgutil.iter_importers()} and @ref{df4,,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{12b9,,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{139b,,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{139c,,poplib.POP3.quit()} may now raise protocol errors like all other
@code{poplib} methods.  Code that assumes @code{quit} does not raise
@ref{139d,,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 
自 Python 2.4 以來已棄用的 @ref{139e,,email.parser.Parser} 的 @code{strict} 引數終於被刪除了。

@item 
已棄用的方法 @code{unittest.TestCase.assertSameElements} 已被刪除。

@item 
已棄用的變數 @code{time.accept2dyear} 已被刪除。

@item 
The deprecated @code{Context._clamp} attribute has been removed from the
@ref{3a,,decimal} module.  It was previously replaced by the public attribute
@ref{139f,,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{cf,,smtplib}, since its functionality has long been provided directly
by @ref{13a0,,socket.socket.makefile()}.

@item 
Passing a negative value to @ref{8a4,,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{8a7,,sys.version_info}
to make the decision.

@item 
Code that used to work around the fact that the @ref{f3,,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,移植 Python 程式碼,移植到 Python 3 3
@anchor{whatsnew/3 3 porting-c-code}@anchor{1245}
@subsubsection Porting C code



@itemize *

@item 
In the course of changes to the buffer API the undocumented
@code{smalltable} member of the
@ref{954,,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{1239,,PEP 393}, the @ref{3de,,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{13a1,,Unicode API}.

However, if you only have been using high-level functions such as
@ref{13a2,,PyUnicode_Concat()}, @ref{13a3,,PyUnicode_Join()} or
@ref{623,,PyUnicode_FromFormat()}, your code will automatically take
advantage of the new unicode representations.

@item 
@ref{13a4,,PyImport_GetMagicNumber()} 現在在失敗時回傳 @code{-1}。

@item 
As a negative value for the `level' argument to @ref{ac8,,__import__()} is no
longer valid, the same now holds for @ref{13a5,,PyImport_ImportModuleLevel()}.
This also means that the value of `level' used by
@ref{13a6,,PyImport_ImportModuleEx()} is now @code{0} instead of @code{-1}.
@end itemize

@node Building C extensions,命令列開關更改,Porting C code,移植到 Python 3 3
@anchor{whatsnew/3 3 building-c-extensions}@anchor{13a7}
@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).

（於 bpo-14040@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14040} 中實作。）
@end itemize

@node 命令列開關更改,,Building C extensions,移植到 Python 3 3
@anchor{whatsnew/3 3 command-line-switch-changes}@anchor{13a8}
@subsubsection 命令列開關更改



@itemize *

@item 
The -Q command-line flag and related artifacts have been removed.  Code
checking sys.flags.division_warning will need updating.

（由 Éric Araujo 於 bpo-10998@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10998} 中實作。）

@item 
When @code{python} is started with @ref{13a9,,-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}，由 Carl Meyer 貢獻並由 É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 Python 3 2 有什麼新功能,Python 3 1 有什麼新功能,Python 3 3 有什麼新功能,Python 有什麼新功能？
@anchor{whatsnew/3 2 doc}@anchor{13aa}@anchor{whatsnew/3 2 translation-repo}@anchor{13ab}@anchor{whatsnew/3 2 what-s-new-in-python-3-2}@anchor{13ac}
@section Python 3.2 有什麼新功能


@*作者: 
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 發佈時程


@menu
* PEP 384; Defining a Stable ABI: PEP 384 Defining a Stable ABI. 
* PEP 389; Argparse 命令列剖析模組: PEP 389 Argparse 命令列剖析模組. 
* PEP 391; Dictionary Based Configuration for Logging: PEP 391 Dictionary Based Configuration for Logging. 
* PEP 3148：concurrent.futures 模組: PEP 3148：concurrent futures 模組. 
* 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. 
* 其他語言更動: 其他語言更動<12>. 
* New@comma{} Improved@comma{} and Deprecated Modules: New Improved and Deprecated Modules. 
* Multi-threading:: 
* 最佳化: 最佳化<12>. 
* Unicode:: 
* 編解碼器:: 
* 文件:: 
* IDLE:: 
* Code Repository:: 
* 建置和 C API 變更: 建置和 C API 變更<5>. 
* 移植至 Python 3.2: 移植至 Python 3 2. 

@end menu

@node PEP 384 Defining a Stable ABI,PEP 389 Argparse 命令列剖析模組,,Python 3 2 有什麼新功能
@anchor{whatsnew/3 2 pep-384-defining-a-stable-abi}@anchor{13ad}
@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/} - 定義一個穩定 ABI

由 Martin von Löwis 撰寫 PEP。
@end table


@node PEP 389 Argparse 命令列剖析模組,PEP 391 Dictionary Based Configuration for Logging,PEP 384 Defining a Stable ABI,Python 3 2 有什麼新功能
@anchor{whatsnew/3 2 pep-389-argparse-command-line-parsing-module}@anchor{13ae}
@subsection PEP 389: Argparse 命令列剖析模組


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/} - 新命令列剖析模組

由 Steven Bethard 撰寫 PEP。
@end table

@ref{13af,,將 optparse 程式碼遷移到 argparse} for details on the differences from @ref{a4,,optparse}.


@node PEP 391 Dictionary Based Configuration for Logging,PEP 3148：concurrent futures 模組,PEP 389 Argparse 命令列剖析模組,Python 3 2 有什麼新功能
@anchor{whatsnew/3 2 pep-391-dictionary-based-configuration-for-logging}@anchor{13b0}
@subsection PEP 391:  Dictionary Based Configuration for Logging


The @ref{8b,,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{13b1,,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

由 Vinay Sajip 撰寫 PEP。
@end table


@node PEP 3148：concurrent futures 模組,PEP 3147 PYC Repository Directories,PEP 391 Dictionary Based Configuration for Logging,Python 3 2 有什麼新功能
@anchor{whatsnew/3 2 pep-3148-the-concurrent-futures-module}@anchor{13b2}
@subsection PEP 3148：@code{concurrent.futures} 模組


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{13b3,,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{c6c,,submit()} for scheduling a callable and
returning a @ref{13b3,,Future} object;
@ref{1dc,,map()} for scheduling many asynchronous calls
at a time, and @ref{ae1,,shutdown()} for freeing
resources.  The class is a @ref{1e1,,context manager} and can be used in a
@ref{186,,with} statement to assure that resources are automatically released
when currently pending futures are done executing.

A simple of example of @ref{941,,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

由 Brian Quinlan 撰寫 PEP。
@end table

@ref{13b4,,Code for Threaded Parallel URL reads}, an
example using threads to fetch multiple web pages in parallel.

@ref{13b5,,Code for computing prime numbers in parallel}, an example demonstrating
@ref{1d6,,ProcessPoolExecutor}.


@node PEP 3147 PYC Repository Directories,PEP 3149 ABI Version Tagged so Files,PEP 3148：concurrent futures 模組,Python 3 2 有什麼新功能
@anchor{whatsnew/3 2 pep-3147-pyc-repository-directories}@anchor{13b6}
@subsection PEP 3147:  PYC Repository Directories


Python's scheme for caching bytecode in `.pyc' files did not work well in
environments with multiple Python interpreters.  If one interpreter encountered
a cached file created by another interpreter, it would recompile the source and
overwrite the cached file, thus losing the benefits of caching.

The issue of "pyc fights" has become more pronounced as it has become
commonplace for Linux distributions to ship with multiple versions of Python.
These conflicts also arise with CPython alternatives such as Unladen Swallow.

To solve this problem, Python's import machinery has been extended to use
distinct filenames for each interpreter.  Instead of Python 3.2 and Python 3.3 and
Unladen Swallow each competing for a file called "mymodule.pyc", they will now
look for "mymodule.cpython-32.pyc", "mymodule.cpython-33.pyc", and
"mymodule.unladen10.pyc".  And to prevent all of these new files from
cluttering source directories, the `pyc' files are now collected in a
"__pycache__" directory stored under the package directory.

Aside from the filenames and target directories, the new scheme has a few
aspects that are visible to the programmer:


@itemize *

@item 
Imported modules now have a @ref{320,,__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{b8,,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{7c,,importlib.abc} module has been updated with new @ref{13b7,,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

由 Barry Warsaw 撰寫 PEP。
@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,Python 3 2 有什麼新功能
@anchor{whatsnew/3 2 pep-3149-abi-version-tagged-so-files}@anchor{13b8}
@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{e1,,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

由 Barry Warsaw 撰寫 PEP。
@end table


@node PEP 3333 Python Web Server Gateway Interface v1 0 1,其他語言更動<12>,PEP 3149 ABI Version Tagged so Files,Python 3 2 有什麼新功能
@anchor{whatsnew/3 2 pep-3333-python-web-server-gateway-interface-v1-0-1}@anchor{13b9}
@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{169,,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{169,,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{11e,,wsgiref} module has a new function,
@ref{13ba,,wsgiref.handlers.read_environ()} for transcoding CGI variables from
@ref{259,,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

由 Phillip Eby 撰寫 PEP。
@end table


@node 其他語言更動<12>,New Improved and Deprecated Modules,PEP 3333 Python Web Server Gateway Interface v1 0 1,Python 3 2 有什麼新功能
@anchor{whatsnew/3 2 other-language-changes}@anchor{13bb}
@subsection 其他語言更動


Some smaller changes made to the core Python language are:


@itemize *

@item 
String formatting for @ref{199,,format()} and @ref{82c,,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{fd2,,str.format_map()} method that extends the
capabilities of the existing @ref{82c,,str.format()} method by accepting arbitrary
@ref{13bc,,mapping} objects.  This new method makes it possible to use string
formatting with any of Python's many dictionary-like objects such as
@ref{13bd,,defaultdict}, @ref{1196,,Shelf},
@ref{4d9,,ConfigParser}, or @ref{35,,dbm}.  It is also useful with
custom @ref{183,,dict} subclasses that normalize keys before look-up or that
supply a @ref{13be,,__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{895,,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

（由 Marcin Wojdyr 在 bpo-1772833@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1772833} 中貢獻）。

@item 
The @ref{6f2,,hasattr()} function works by calling @ref{dc5,,getattr()} and detecting
whether an exception is raised.  This technique allows it to detect methods
created dynamically by @ref{6f3,,__getattr__()} or @ref{dc6,,__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{5e8,,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{169,,str()} of a float or complex number is now the same as its
@ref{1c1,,repr()}. Previously, the @ref{169,,str()} form was shorter but that just
caused confusion and is no longer needed now that the shortest possible
@ref{1c1,,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{165,,memoryview} objects now have a @ref{13bf,,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{1ab,,except} clause
is cleared, so this code which used to work with Python 2.6, raised a
@ref{18e,,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

（請見 bpo-4617@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4617}。）

@item 
@ref{13c0,,Struct sequence types} are now subclasses of tuple.
This means that C structures like those returned by @ref{26d,,os.stat()},
@ref{13c1,,time.gmtime()}, and @ref{8a7,,sys.version_info} now work like a
@ref{857,,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{d9e,,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{547,,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{118,,warnings}
module, or on the command line.

A @ref{547,,ResourceWarning} is issued at interpreter shutdown if the
@ref{13c2,,gc.garbage} list isn't empty, and if @ref{13c3,,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{547,,ResourceWarning} is also issued when a @ref{13c4,,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{b34,,range} objects now support `index' and `count' methods. This is part
of an effort to make more objects fully implement the
@ref{13c5,,collections.Sequence} @ref{13b7,,abstract base class}.  As a result, the
language will have a more uniform API.  In addition, @ref{b34,,range} objects
now support slicing and negative indices, even with values larger than
@ref{13c6,,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

（由 Daniel Stutzbach 在 bpo-9213@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9213}、Alexander Belopolsky 在 bpo-2690@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2690}、Nick Coghlan 在 bpo-10889@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10889} 中貢獻。）

@item 
The @ref{13c7,,callable()} builtin function from Py2.x was resurrected.  It provides
a concise, readable alternative to using an @ref{13b7,,abstract base class} in an
expression like @code{isinstance(x, collections.Callable)}:

@example
>>> callable(max)
True
>>> callable(20)
False
@end example

（請見 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,其他語言更動<12>,Python 3 2 有什麼新功能
@anchor{whatsnew/3 2 new-improved-and-deprecated-modules}@anchor{13c8}
@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{3f,,email} package, @ref{8f,,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{1e1,,context manager} to support
convenient and reliable resource clean-up using a @ref{186,,with} statement.

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

@end menu

@node email<7>,elementtree,,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 email}@anchor{13c9}
@subsubsection email


The usability of the @ref{3f,,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{192,,bytes} rather than @ref{169,,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{13ca,,message_from_bytes()} and
@ref{13cb,,message_from_binary_file()}, and new classes
@ref{13cc,,BytesFeedParser} and @ref{13cd,,BytesParser}
allow binary message data to be parsed into model objects.

@item 
Given bytes input to the model, @ref{13ce,,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{13cf,,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{13d0,,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{cf,,smtplib} @ref{b1e,,SMTP} class now accepts a byte string
for the `msg' argument to the @ref{1054,,sendmail()} method,
and a new method, @ref{1055,,send_message()} accepts a
@ref{57b,,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<8>,email<7>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 elementtree}@anchor{13d1}
@subsubsection elementtree


The @ref{12b,,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{13d2,,xml.etree.ElementTree.fromstringlist()} which builds an XML document
from a sequence of fragments

@item 
@ref{13d3,,xml.etree.ElementTree.register_namespace()} for registering a global
namespace prefix

@item 
@ref{11f1,,xml.etree.ElementTree.tostringlist()} for string representation
including all sublists

@item 
@ref{13d4,,xml.etree.ElementTree.Element.extend()} for appending a sequence of zero
or more elements

@item 
@ref{13d5,,xml.etree.ElementTree.Element.iterfind()} searches an element and
subelements

@item 
@ref{13d6,,xml.etree.ElementTree.Element.itertext()} creates a text iterator over
an element and its subelements

@item 
@ref{13d7,,xml.etree.ElementTree.TreeBuilder.end()} closes the current element

@item 
@ref{c85,,xml.etree.ElementTree.TreeBuilder.doctype()} handles a doctype
declaration
@end itemize

有兩個方法已被棄用：


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

（由 Florent Xicluna 和 Fredrik Lundh 貢獻，bpo-6472@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6472}。）

@node functools<8>,itertools<8>,elementtree,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 functools}@anchor{13d8}
@subsubsection functools



@itemize *

@item 
The @ref{63,,functools} module includes a new decorator for caching function
calls.  @ref{bd9,,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{1158,,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{13d9,,__annotations__} if
defined.  And now it also gracefully skips over missing attributes such as
@ref{13da,,__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{113d,,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{113d,,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.

（由 Raymond Hettinger 貢獻。）

@item 
To aid in porting programs from Python 2, the @ref{13db,,functools.cmp_to_key()}
function converts an old-style comparison function to
modern @ref{1001,,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.

（由 Raymond Hettinger 貢獻。）
@end itemize

@node itertools<8>,collections<8>,functools<8>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 itertools}@anchor{13dc}
@subsubsection itertools



@itemize *

@item 
The @ref{85,,itertools} module has a new @ref{be7,,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{be7,,accumulate()}, see the @ref{13dd,,examples for the random module}.

（由 Raymond Hettinger 貢獻，並結合了 Mark Dickinson 的設計建議。）
@end itemize

@node collections<8>,threading<10>,itertools<8>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 collections}@anchor{13de}
@subsubsection collections



@itemize *

@item 
The @ref{1292,,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{13df,,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

（由 Raymond Hettinger 貢獻。）

@item 
The @ref{7ec,,collections.OrderedDict} class has a new method
@ref{13e0,,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

（由 Raymond Hettinger 貢獻。）

@item 
The @ref{7ed,,collections.deque} class grew two new methods
@ref{13e1,,count()} and @ref{13e2,,reverse()} that
make them more substitutable for @ref{24d,,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

（由 Raymond Hettinger 貢獻。）
@end itemize

@node threading<10>,datetime 和 time,collections<8>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 threading}@anchor{13e3}
@subsubsection threading


The @ref{f3,,threading} module has a new @ref{13e4,,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{13e4,,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{13e5,,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{13e6,,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'.

（在 bpo-8777@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8777} 中由 Kristján Valur Jónsson 貢獻、Jeffrey Yasskin 進行 API 審查。）

@node datetime 和 time,math<11>,threading<10>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 datetime-and-time}@anchor{13e7}
@subsubsection datetime 和 time



@itemize *

@item 
The @ref{34,,datetime} module has a new type @ref{12c0,,timezone} that
implements the @ref{7ef,,tzinfo} interface by returning a fixed UTC
offset and timezone name. This makes it easier to create timezone-aware
datetime objects:

@example
>>> from datetime import datetime, timezone

>>> datetime.now(timezone.utc)
datetime.datetime(2010, 12, 8, 21, 4, 2, 923754, tzinfo=datetime.timezone.utc)

>>> datetime.strptime("01/01/2000 12:00 +0000", "%m/%d/%Y %H:%M %z")
datetime.datetime(2000, 1, 1, 12, 0, tzinfo=datetime.timezone.utc)
@end example

@item 
Also, @ref{bba,,timedelta} objects can now be multiplied by
@ref{196,,float} and divided by @ref{196,,float} and @ref{19b,,int} objects.
And @ref{bba,,timedelta} objects can now divide one another.

@item 
The @ref{e8a,,datetime.date.strftime()} method is no longer restricted to years
after 1900.  The new supported year range is from 1000 to 9999 inclusive.

@item 
Whenever a two-digit year is used in a time tuple, the interpretation has been
governed by @code{time.accept2dyear}.  The default is @code{True} which means that
for a two-digit year, the century is guessed according to the POSIX rules
governing the @code{%y} strptime format.

Starting with Py3.2, use of the century guessing heuristic will emit a
@ref{1a3,,DeprecationWarning}.  Instead, it is recommended that
@code{time.accept2dyear} be set to @code{False} so that large date ranges
can be used without guesswork:

@example
>>> import time, warnings
>>> warnings.resetwarnings()      # remove the default warning filters

>>> time.accept2dyear = True      # guess whether 11 means 11 or 2011
>>> time.asctime((11, 1, 1, 12, 34, 56, 4, 1, 0))
Warning (from warnings module):
  ...
DeprecationWarning: Century info guessed for a 2-digit year.
'Fri Jan  1 12:34:56 2011'

>>> time.accept2dyear = False     # use the full range of allowable dates
>>> time.asctime((11, 1, 1, 12, 34, 56, 4, 1, 0))
'Fri Jan  1 12:34:56 11'
@end example

Several functions now have significantly expanded date ranges.  When
@code{time.accept2dyear} is false, the @ref{13e8,,time.asctime()} function will
accept any year that fits in a C int, while the @ref{13e9,,time.mktime()} and
@ref{13ea,,time.strftime()} functions will accept the full range supported by the
corresponding operating system functions.
@end itemize

（由 Alexander Belopolsky 和 Victor Stinner 在 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} 和 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<11>,abc<3>,datetime 和 time,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 math}@anchor{13eb}
@subsubsection math


The @ref{92,,math} module has been updated with six new functions inspired by the
C99 standard.

The @ref{13ec,,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{13ed,,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{dce,,erf()} function computes a probability integral or Gaussian error function@footnote{https://en.wikipedia.org/wiki/Error_function}.  The
complementary error function, @ref{dcf,,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{13ee,,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{13ef,,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

（由 Mark Dickinson 貢獻。）

@node abc<3>,io<9>,math<11>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 abc}@anchor{13f0}
@subsubsection abc


The @ref{4,,abc} module now supports @ref{1287,,abstractclassmethod()} and
@ref{1288,,abstractstaticmethod()}.

These tools make it possible to define an @ref{13b7,,abstract base class} that
requires a particular @ref{489,,classmethod()} or @ref{451,,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{13f1}
@subsubsection io


The @ref{109f,,io.BytesIO} has a new method, @ref{13f2,,getbuffer()}, which
provides functionality similar to @ref{165,,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

（由 Antoine Pitrou 在 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{13f3}
@subsubsection reprlib


When writing a @ref{828,,__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{24d,,list} and @ref{184,,set} handle
self-reference by displaying "..." in the recursive part of the representation
string.

To help write such @ref{828,,__repr__()} methods, the @ref{c0,,reprlib} module has a new
decorator, @ref{13f4,,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

（由 Raymond Hettinger 在 bpo-9826@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9826} 和 bpo-9840@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9840} 中貢獻。）

@node logging<8>,csv<4>,reprlib,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 logging}@anchor{13f5}
@subsubsection logging


In addition to dictionary-based configuration described above, the
@ref{8b,,logging} package has many other improvements.

The logging documentation has been augmented by a @ref{13f6,,basic tutorial}, an @ref{13f7,,advanced tutorial}, and a @ref{13f8,,cookbook} of
logging recipes.  These documents are the fastest way to learn about logging.

The @ref{bea,,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{82c,,str.format()} style, or
can be set to "$" for the shell-style formatting provided by
@ref{890,,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{13f9,,StreamHandler} directed to
@ref{b2a,,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{13fa,,logging.raiseExceptions}.  The new default handler is stored in
@ref{13fb,,logging.lastResort}.

The use of filters has been simplified.  Instead of creating a
@ref{13fc,,Filter} object, the predicate can be any Python callable that
returns @code{True} or @code{False}.

There were a number of other improvements that add flexibility and simplify
configuration.  See the module documentation for a full listing of changes in
Python 3.2.

@node csv<4>,contextlib<8>,logging<8>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 csv}@anchor{13fd}
@subsubsection csv


The @ref{2d,,csv} module now supports a new dialect, @ref{13fe,,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{13ff,,csv.DictWriter} has a new method,
@ref{1400,,writeheader()} for writing-out an initial row to document
the field names:

@example
>>> import csv, sys
>>> w = csv.DictWriter(sys.stdout, ['name', 'dept'], dialect='unix')
>>> w.writeheader()
"name","dept"
>>> w.writerows([
...     @{'name': 'tom', 'dept': 'accounting'@},
...     @{'name': 'susan', 'dept': 'Salesl'@}])
"tom","accounting"
"susan","sales"
@end example

(New dialect suggested by Jay Talbot in bpo-5975@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5975}, and the new method
suggested by Ed Abraham in bpo-1537721@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1537721}.)

@node contextlib<8>,decimal and fractions,csv<4>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 contextlib}@anchor{1401}
@subsubsection contextlib


There is a new and slightly mind-blowing tool
@ref{1402,,ContextDecorator} that is helpful for creating a
@ref{1e1,,context manager} that does double duty as a function decorator.

As a convenience, this new functionality is used by
@ref{1403,,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{186,,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{1403,,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{186,,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.

（由 Michael Foord 在 bpo-9110@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9110} 中貢獻。）

@node decimal and fractions,ftp,contextlib<8>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 decimal-and-fractions}@anchor{1404}
@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{11fa,,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{1fe,,decimal.Decimal} constructor now accepts @ref{196,,float} objects
directly so there in no longer a need to use the @ref{1405,,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{1fe,,Decimal} objects can be directly compared with @ref{196,,float}
and @ref{213,,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{213,,fractions.Fraction} so that the
@ref{1406,,from_float()} and @ref{1407,,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{3a,,decimal} module is that the
@ref{139f,,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}).

（由 Mark Dickinson 和 Raymond Hettinger 貢獻。）

@node ftp,popen,decimal and fractions,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 ftp}@anchor{1408}
@subsubsection ftp


The @ref{aed,,ftplib.FTP} class now supports the context management protocol to
unconditionally consume @ref{1251,,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{514,,mmap.mmap} and @ref{9f9,,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

（由 Tarek Ziadé 和 Giampaolo Rodolà 在 bpo-4972@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4972} 中貢獻，由 Georg Brandl 在 bpo-8046@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8046} 和 bpo-1286@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1286} 中貢獻。）

The @ref{aee,,FTP_TLS} class now accepts a `context' parameter, which is a
@ref{355,,ssl.SSLContext} object allowing bundling SSL configuration options,
certificates and private keys into a single (potentially long-lived) structure.

（由 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{1409}
@subsubsection popen


The @ref{319,,os.popen()} and @ref{4b2,,subprocess.Popen()} functions now support
@ref{186,,with} statements for auto-closing of the file descriptors.

（由 Antoine Pitrou 和 Brian Curtin 在 bpo-7461@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7461} 和 bpo-10554@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10554} 中貢獻。）

@node select<3>,gzip 和 zipfile,popen,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 select}@anchor{140a}
@subsubsection select


The @ref{c6,,select} module now exposes a new, constant attribute,
@ref{140b,,PIPE_BUF}, which gives the minimum number of bytes which are
guaranteed not to block when @ref{f9b,,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 和 zipfile,tarfile<10>,select<3>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 gzip-and-zipfile}@anchor{140c}
@subsubsection gzip 和 zipfile


@ref{654,,gzip.GzipFile} now implements the @ref{89c,,io.BufferedIOBase}
@ref{13b7,,abstract base class} (except for @code{truncate()}).  It also has a
@ref{140d,,peek()} method and supports unseekable as well as
zero-padded file objects.

The @ref{6b,,gzip} module also gains the @ref{847,,compress()} and
@ref{140e,,decompress()} functions for easier in-memory compression and
decompression.  Keep in mind that text needs to be encoded as @ref{192,,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

（由 Anand B. Pillai 在 bpo-3488@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3488} 中貢獻；由 Antoine Pitrou、Nir Aides 和 Brian Curtin 在 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} 和 bpo-2846@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2846} 中貢獻。）

Also, the @ref{655,,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{140f,,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<10>,hashlib<7>,gzip 和 zipfile,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 tarfile}@anchor{1410}
@subsubsection tarfile


The @ref{1411,,TarFile} class can now be used as a context manager.  In
addition, its @ref{de9,,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{f09,,keyword argument}.  The user-supplied filter function accepts a
@ref{1412,,TarInfo} object and returns an updated
@ref{1412,,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

（由 Tarek Ziadé 提議並由 Lars Gustäbel 實作於 bpo-6856@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6856}。）

@node hashlib<7>,ast<7>,tarfile<10>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 hashlib}@anchor{1413}
@subsubsection hashlib


The @ref{6c,,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

（由 Carl Chenet 在 bpo-7418@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7418} 中提議。）

@node ast<7>,os<14>,hashlib<7>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 ast}@anchor{1414}
@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{e0d,,ast.literal_eval()} function serves as a secure alternative to
the builtin @ref{49e,,eval()} function which is easily abused.  Python 3.2 adds
@ref{192,,bytes} and @ref{184,,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

（由 Benjamin Peterson 和 Georg Brandl 實作。）

@node os<14>,shutil<8>,ast<7>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 os}@anchor{1415}
@subsubsection os


Different operating systems use various encodings for filenames and environment
variables.  The @ref{a5,,os} module provides two new functions,
@ref{e4a,,fsencode()} and @ref{e49,,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{1416,,os.supports_bytes_environ} constant will be
true.

For direct access to encoded environment variables (if available),
use the new @ref{1417,,os.getenvb()} function or use @ref{25a,,os.environb}
which is a bytes version of @ref{259,,os.environ}.

（由 Victor Stinner 貢獻。）

@node shutil<8>,sqlite3<12>,os<14>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 shutil}@anchor{1418}
@subsubsection shutil


The @ref{c15,,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{c47,,shutil.copy2()} is used by default.
@end itemize

（由 Tarek Ziadé 貢獻。）

In addition, the @ref{ca,,shutil} module now supports @ref{1419,,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{6d3,,make_archive()} and
@ref{68f,,unpack_archive()}.  By default, both operate on the current
directory (which can be set by @ref{81a,,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

（由 Tarek Ziadé 貢獻。）

@node sqlite3<12>,html<3>,shutil<8>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 sqlite3}@anchor{141a}
@subsubsection sqlite3


The @ref{d4,,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{a38,,sqlite3.Connection.enable_load_extension()} and
@ref{6d8,,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

（由 R. David Murray 和 Shashwat Anand 貢獻；bpo-8845@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8845}。）

@node html<3>,socket<12>,sqlite3<12>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 html}@anchor{141b}
@subsubsection html


A new @ref{6f,,html} module was introduced with only a single function,
@ref{1209,,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<12>,ssl<13>,html<3>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 socket}@anchor{141c}
@subsubsection socket


The @ref{d1,,socket} module has two new improvements.


@itemize *

@item 
Socket objects now have a @ref{141d,,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{87b,,socket.create_connection()} now supports the context management protocol
to unconditionally consume @ref{1251,,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<13>,nntp,socket<12>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 ssl}@anchor{141e}
@subsubsection ssl


The @ref{d5,,ssl} module added a number of features to satisfy common requirements
for secure (encrypted, authenticated) internet connections:


@itemize *

@item 
A new class, @ref{355,,SSLContext}, serves as a container for persistent
SSL data, such as protocol settings, certificates, private keys, and various
other options. It includes a @ref{741,,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{741,,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{d5,,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{741,,ssl.SSLContext.wrap_socket()}.

@item 
Various options have been added to the @ref{d5,,ssl} module, such as
@ref{a33,,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{141f,,ssl.OPENSSL_VERSION} (a string),
@ref{1420,,ssl.OPENSSL_VERSION_INFO} (a 5-tuple), and
@ref{1421,,ssl.OPENSSL_VERSION_NUMBER} (an integer).
@end itemize

（由 Antoine Pitrou 在 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} 和 bpo-8321@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8321} 中貢獻。）

@node nntp,certificates,ssl<13>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 nntp}@anchor{1422}
@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.

（由 Antoine Pitrou 在 bpo-9360@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9360} 中和 Andrew Vant 在 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{1423}
@subsubsection certificates


@ref{d2e,,http.client.HTTPSConnection}, @ref{1424,,urllib.request.HTTPSHandler}
and @ref{306,,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<4>,certificates,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 imaplib}@anchor{1425}
@subsubsection imaplib


Support for explicit TLS on standard IMAP4 connections has been added through
the new @ref{1426,,imaplib.IMAP4.starttls} method.

（由 Lorenzo M. Catucci 和 Antoine Pitrou 於 bpo-4471@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4471} 貢獻。）

@node http client<4>,unittest<12>,imaplib<5>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 http-client}@anchor{1427}
@subsubsection http.client


There were a number of small API improvements in the @ref{73,,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{d2d,,HTTPConnection} and
@ref{d2e,,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{d2e,,HTTPSConnection}.

The @ref{ea2,,request()} method on connection objects
allowed an optional `body' argument so that a @ref{13c4,,file object} could be used
to supply the content of the request.  Conveniently, the `body' argument now
also accepts an @ref{1428,,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{1429,,set_tunnel()} method that sets the host and
port for HTTP Connect tunneling.

To match the behavior of @ref{76,,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<12>,random<5>,http client<4>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 unittest}@anchor{142a}
@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

（由 Michael Foord 貢獻。）

@item 
Experimentation at the interactive prompt is now easier because the
@ref{2b3,,unittest.TestCase} class can now be instantiated without
arguments:

@example
>>> from unittest import TestCase
>>> TestCase().assertEqual(pow(2, 3), 8)
@end example

（由 Michael Foord 貢獻。）

@item 
The @ref{10c,,unittest} module has two new methods,
@ref{1365,,assertWarns()} and
@ref{1366,,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

（由 Antoine Pitrou 於 bpo-9754@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9754} 貢獻。）

Another new method, @ref{142b,,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

（由 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{142c,,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{74a,,assertRegex()} is the new name for
@code{assertRegexpMatches()} which was misnamed because the
test uses @ref{142d,,re.search()}, not @ref{142e,,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{be,,re} module, and it has unambiguous
camel-casing.

（由 Raymond Hettinger 貢獻，由 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

舊名稱

@tab

Preferred Name

@item

@code{assert_()}

@tab

@ref{743,,assertTrue()}

@item

@code{assertEquals()}

@tab

@ref{745,,assertEqual()}

@item

@code{assertNotEquals()}

@tab

@ref{746,,assertNotEqual()}

@item

@code{assertAlmostEquals()}

@tab

@ref{747,,assertAlmostEqual()}

@item

@code{assertNotAlmostEquals()}

@tab

@ref{748,,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.

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

（由 Raymond Hettinger 貢獻。）
@end itemize

@node random<5>,poplib<4>,unittest<12>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 random}@anchor{142f}
@subsubsection random


The integer methods in the @ref{bd,,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{a64,,randrange()},
@ref{1430,,randint()}, @ref{1431,,choice()}, @ref{946,,shuffle()} and
@ref{945,,sample()}.

（由 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{1432}
@subsubsection poplib


@ref{b15,,POP3_SSL} class now accepts a `context' parameter, which is a
@ref{355,,ssl.SSLContext} object allowing bundling SSL configuration options,
certificates and private keys into a single (potentially long-lived)
structure.

（由 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{1433}
@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.

（由 Giampaolo Rodolà 貢獻；bpo-6706@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6706}。）

@node tempfile<5>,inspect<11>,asyncore<2>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 tempfile}@anchor{1434}
@subsubsection tempfile


The @ref{e6,,tempfile} module has a new context manager,
@ref{1435,,TemporaryDirectory} which provides easy deterministic
cleanup of temporary directories:

@example
with tempfile.TemporaryDirectory() as tmpdirname:
    print('created temporary dir:', tmpdirname)
@end example

（由 Neil Schedulenauer 和 Nick Coghlan 貢獻；bpo-5178@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5178}。）

@node inspect<11>,pydoc<7>,tempfile<5>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 inspect}@anchor{1436}
@subsubsection inspect



@itemize *

@item 
The @ref{82,,inspect} module has a new function
@ref{1437,,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

（由 Rodolfo Eckhardt 和 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{82,,inspect} module has a new function, @ref{6b5,,getattr_static()}.
Unlike @ref{6f2,,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

（由 Michael Foord 貢獻。）
@end quotation

@node pydoc<7>,dis<6>,inspect<11>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 pydoc}@anchor{1438}
@subsubsection pydoc


The @ref{ba,,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

（由 Ron Adam 貢獻；bpo-2001@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2001}。）

@node dis<6>,dbm<7>,pydoc<7>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 dis}@anchor{1439}
@subsubsection dis


The @ref{3c,,dis} module gained two new functions for inspecting code,
@ref{143a,,code_info()} and @ref{1129,,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{205,,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.

（由 Nick Coghlan 在 bpo-9147@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9147} 中貢獻。）

@node dbm<7>,ctypes<4>,dis<6>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 dbm}@anchor{143b}
@subsubsection dbm


All database modules now support the @code{get()} and @code{setdefault()} methods.

（由 Ray Allen 在 bpo-9523@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9523} 中建議。）

@node ctypes<4>,site<4>,dbm<7>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 ctypes}@anchor{143c}
@subsubsection ctypes


A new type, @ref{143d,,ctypes.c_ssize_t} represents the C @code{ssize_t} datatype.

@node site<4>,sysconfig<4>,ctypes<4>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 site}@anchor{143e}
@subsubsection site


The @ref{cc,,site} module has three new functions useful for reporting on the
details of a given Python installation.


@itemize *

@item 
@ref{143f,,getsitepackages()} lists all global site-packages directories.

@item 
@ref{1440,,getuserbase()} reports on the user's base directory where data can
be stored.

@item 
@ref{1441,,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

（由 Tarek Ziadé 在 bpo-6693@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6693} 中貢獻。）

@node sysconfig<4>,pdb<10>,site<4>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 sysconfig}@anchor{1442}
@subsubsection sysconfig


The new @ref{e1,,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{1443,,get_platform()} returning values like `linux-i586' or
`macosx-10.6-ppc'.

@item 
@ref{1444,,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{33f,,get_paths()} makes a dictionary containing installation paths
for the current installation scheme.

@item 
@ref{298,,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<10>,configparser<6>,sysconfig<4>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 pdb}@anchor{1445}
@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 
現在 @ref{273,,Pdb} 類別建構函式接受 `nosigint' 引數。

@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

（由 Georg Brandl、Antonio Cuni 和 Ilya Sandler 貢獻。）

@node configparser<6>,urllib parse<6>,pdb<10>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 configparser}@anchor{1446}
@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{4d9,,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{925,,ExtendedInterpolation}:

@example
>>> parser = ConfigParser(interpolation=ExtendedInterpolation())
>>> parser.read_dict(@{'buildout': @{'directory': '/home/ambv/zope9'@},
...                   'custom': @{'prefix': '/usr/local'@}@})
>>> parser.read_string("""
... [buildout]
... parts =
...   zope9
...   instance
... find-links =
...   $@{buildout:directory@}/downloads/dist
...
... [zope9]
... recipe = plone.recipe.zope9install
... location = /opt/zope
...
... [instance]
... recipe = plone.recipe.zope9instance
... zope9-location = $@{zope9:location@}
... zope-conf = $@{custom:prefix@}/etc/zope.conf
... """)
>>> parser['buildout']['find-links']
'\n/home/ambv/zope9/downloads/dist'
>>> parser['instance']['zope-conf']
'/usr/local/etc/zope.conf'
>>> instance = parser['instance']
>>> instance['zope-conf']
'/usr/local/etc/zope.conf'
>>> instance['zope9-location']
'/opt/zope'
@end example

A number of smaller features were also introduced, like support for specifying
encoding in read operations, specifying fallback values for get-functions, or
reading directly from dictionaries and strings.

(All changes contributed by Łukasz Langa.)

@c XXX consider showing a difflib example

@node urllib parse<6>,mailbox,configparser<6>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 urllib-parse}@anchor{1447}
@subsubsection urllib.parse


A number of usability improvements were made for the @ref{110,,urllib.parse} module.

The @ref{360,,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{1448,,urldefrag()} function now returns a @ref{857,,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{1090,,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{1449,,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{144a,,Parsing ASCII Encoded Bytes}, all the @ref{110,,urllib.parse}
functions now accept ASCII-encoded byte strings as input, so long as they are
not mixed with regular strings.  If ASCII-encoded byte strings are given as
parameters, the return types will also be an ASCII-encoded byte strings:

@example
>>> urllib.parse.urlparse(b'http://www.python.org:80/about/')
ParseResultBytes(scheme=b'http', netloc=b'www.python.org:80',
                 path=b'/about/', params=b'@w{'}, query=b'@w{'}, fragment=b'@w{'})
@end example

(Work by Nick Coghlan, Dan Mahn, and Senthil Kumaran in bpo-2987@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2987},
bpo-5468@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5468}, and bpo-9873@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9873}.)

@node mailbox,turtledemo,urllib parse<6>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 mailbox}@anchor{144b}
@subsubsection mailbox


Thanks to a concerted effort by R. David Murray, the @ref{8f,,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{192,,bytes} because various parts of a message may have different encodings.

The solution harnessed the @ref{3f,,email} package's binary support for parsing
arbitrary email messages.  In addition, the solution required a number of API
changes.

As expected, the @ref{144c,,add()} method for
@ref{144d,,mailbox.Mailbox} objects now accepts binary input.

@ref{1124,,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{144e,,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{144f,,get_bytes()}
method that returns a @ref{192,,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{1450,,get_string()} method, but that approach
is not very useful.  Instead, it is best to extract messages from
a @ref{1451,,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{1452}
@subsubsection turtledemo


The demonstration code for the @ref{107,,turtle} module was moved from the `Demo'
directory to main library.  It includes over a dozen sample scripts with
lively displays.  Being on @ref{3e2,,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,最佳化<12>,New Improved and Deprecated Modules,Python 3 2 有什麼新功能
@anchor{whatsnew/3 2 multi-threading}@anchor{1453}
@subsection Multi-threading



@itemize *

@item 
The mechanism for serializing execution of concurrently running Python threads
(generally known as the @ref{164,,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{b3b,,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).

（由 Antoine Pitrou 貢獻。）

@item 
Regular and recursive locks now accept an optional `timeout' argument to their
@ref{8a0,,acquire()} method.  (Contributed by Antoine Pitrou;
bpo-7316@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7316}.)

@item 
Similarly, @ref{1454,,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 最佳化<12>,Unicode,Multi-threading,Python 3 2 有什麼新功能
@anchor{whatsnew/3 2 optimizations}@anchor{1455}
@subsection 最佳化


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{184,,set} as a @ref{7eb,,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.

（由 Alexandre Vassalotti、Antoine Pitrou 和 Unladen Swallow 團隊在 bpo-9410@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9410} 和 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{dc3,,list.sort()} and @ref{dc2,,sorted()} now runs faster and uses less memory
when called with a @ref{1001,,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.

（由 Antoine Pitrou 在 bpo-7451@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7451} 中貢獻、由 Raymond Hettinger 和 Antoine Pitrou 在 bpo-10314@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10314} 中貢獻。）

@item 
Recursive locks (created with the @ref{32d,,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.

（由 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{10a5,,split()},
@ref{1456,,rsplit()}, @ref{1457,,splitlines()} and @ref{4b3,,replace()} methods on
@ref{192,,bytes}, @ref{343,,bytearray} and @ref{169,,str} objects. Likewise, the
algorithm is also used by @ref{10a4,,rfind()}, @ref{1458,,rindex()}, @ref{1456,,rsplit()} and
@ref{1459,,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{12cc,,BaseHTTPRequestHandler}
has more efficient buffering (bpo-3709@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3709} by Andrew Schaaf).  The
@ref{102e,,operator.attrgetter()} function has been sped-up (bpo-10160@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10160} by
Christos Georgiou).  And @ref{4d9,,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,編解碼器,最佳化<12>,Python 3 2 有什麼新功能
@anchor{whatsnew/3 2 unicode}@anchor{145a}
@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 編解碼器,文件,Unicode,Python 3 2 有什麼新功能
@anchor{whatsnew/3 2 codecs}@anchor{145b}
@subsection 編解碼器


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{bff,,UnicodeDecodeError} when it encounters an
undecodable byte sequence and an @ref{880,,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{e4,,tarfile} uses @code{'utf-8'} encoding on Windows (instead of
@code{'mbcs'}) and the @code{'surrogateescape'} error handler on all operating
systems.

@node 文件,IDLE,編解碼器,Python 3 2 有什麼新功能
@anchor{whatsnew/3 2 documentation}@anchor{145c}
@subsection 文件


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{145d,,內建函式}.  In the case of @ref{85,,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{63,,functools} module
documentation has a quick link at the top labeled:

@quotation

`Source code' Lib/functools.py@footnote{https://github.com/python/cpython/tree/3.14/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{be,,re}
module has an extensive section, @ref{145e,,Regular Expression Examples}.  Likewise, the
@ref{85,,itertools} module continues to be updated with new
@ref{145f,,Itertools 應用技巧}.

@item 
The @ref{34,,datetime} module now has an auxiliary implementation in pure Python.
No functionality was changed.  This just provides an easier-to-read alternate
implementation.

（由 Alexander Belopolsky 在 bpo-9528@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9528} 中貢獻。）

@item 
The unmaintained @code{Demo} directory has been removed.  Some demos were
integrated into the documentation, some were moved to the @code{Tools/demo}
directory, and others were removed altogether.

（由 Georg Brandl 在 bpo-7962@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7962} 中貢獻。）
@end itemize

@node IDLE,Code Repository,文件,Python 3 2 有什麼新功能
@anchor{whatsnew/3 2 idle}@anchor{1460}
@subsection IDLE



@itemize *

@item 
The format menu now has an option to clean source files by stripping
trailing whitespace.

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

（由 Kevin Walzer、Ned Deily 和 Ronald Oussoren 貢獻；bpo-6075@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6075}。）
@end itemize

@node Code Repository,建置和 C API 變更<5>,IDLE,Python 3 2 有什麼新功能
@anchor{whatsnew/3 2 code-repository}@anchor{1461}
@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 建置和 C API 變更<5>,移植至 Python 3 2,Code Repository,Python 3 2 有什麼新功能
@anchor{whatsnew/3 2 build-and-c-api-changes}@anchor{1462}
@subsection 建置和 C API 變更


Python 建置程序和 C API 的變更包括：


@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{1463,,unicodedata.numeric()} now returns the correct value
for large code points, and @ref{1c1,,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}.

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

（由 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{1464,,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{184,,set} and @ref{183,,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).

（由 Raymond Hettinger 建議並由 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{1465,,sys.argv} without also modifying @ref{3e2,,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{1466,,PyLong_AsLongLongAndOverflow()} which
is analogous to @ref{1467,,PyLong_AsLongAndOverflow()}.  They both serve to
convert Python @ref{19b,,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{1468,,PyUnicode_CompareWithASCIIString()} function now returns `not
equal' if the Python string is `NUL' terminated.

@item 
There is a new function @ref{1469,,PyErr_NewExceptionWithDoc()} that is
like @ref{146a,,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 移植至 Python 3 2,,建置和 C API 變更<5>,Python 3 2 有什麼新功能
@anchor{whatsnew/3 2 porting-to-python-3-2}@anchor{146b}
@subsection 移植至 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{146c,,get()} and
@ref{146d,,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{146d,,set()} and
@ref{146e,,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{146f,,DuplicateSectionError} or
@ref{1470,,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{343,,bytearray} objects can no longer be used as filenames; instead,
they should be converted to @ref{192,,bytes}.

@item 
The @code{array.tostring()} and @code{array.fromstring()} have been renamed to
@ref{1471,,array.tobytes()} and
@ref{1472,,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*()} 函式：


@itemize *

@item 
"t#" 格式已被移除：請改用 "s#" 或 "s*"

@item 
"w" 和 "w#" 格式已被移除：請改用 "w*"
@end itemize

@item 
The @code{PyCObject} type, deprecated in 3.1, has been removed.  To wrap
opaque C pointers in Python objects, the @ref{1473,,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{1474,,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{1475,,bytes.maketrans()} and
@ref{1476,,bytearray.maketrans()}.  This change solves the confusion around which
types were supported by the @ref{d8,,string} module.  Now, @ref{169,,str},
@ref{192,,bytes}, and @ref{343,,bytearray} each have their own `maketrans' and
`translate' methods with intermediate translation tables of the appropriate
type.

（由 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{186,,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

（由 Georg Brandl 和 Mattias Brändström 貢獻；appspot 問題 53094@footnote{https://codereview.appspot.com/53094}。）

@item 
@ref{1477,,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{12b,,xml.etree.ElementTree} class now raises an
@ref{1478,,xml.etree.ElementTree.ParseError} when a parse fails. Previously it
raised an @ref{1479,,xml.parsers.expat.ExpatError}.

@item 
The new, longer @ref{169,,str()} value on floats may break doctests which rely on
the old output format.

@item 
In @ref{4b2,,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{111,,urllib.request}
and @ref{73,,http.client}.  Such support is still present on the server side
(in @ref{76,,http.server}).

（由 Antoine Pitrou 於 bpo-10711@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10711} 貢獻。）

@item 
SSL sockets in timeout mode now raise @ref{a2e,,socket.timeout} when a timeout
occurs, rather than a generic @ref{147a,,SSLError}.

（由 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{63f,,PyEval_SaveThread()}
and @ref{640,,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.

（由 Giampaolo Rodola 在 bpo-6706@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6706} 中貢獻。）

@item 
Due to the new @ref{164,,GIL} implementation, @code{PyEval_InitThreads()}
cannot be called before @ref{45e,,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 Python 3 1 有什麼新功能,Python 3 0 有什麼新功能,Python 3 2 有什麼新功能,Python 有什麼新功能？
@anchor{whatsnew/3 1 doc}@anchor{147b}@anchor{whatsnew/3 1 translation-repo}@anchor{147c}@anchor{whatsnew/3 1 what-s-new-in-python-3-1}@anchor{147d}
@section Python 3.1 有什麼新功能


@*作者: 
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.

本文介紹了 Python 3.1 與 3.0 相比的新功能。Python 3.1 已於 2009 年 6 月 27 日發布。

@menu
* PEP 372：有序字典:: 
* PEP 378; Format Specifier for Thousands Separator: PEP 378 Format Specifier for Thousands Separator. 
* 其他語言更動: 其他語言更動<13>. 
* 新增、改進和棄用的模組:: 
* 最佳化: 最佳化<13>. 
* IDLE: IDLE<2>. 
* 建置和 C API 變更: 建置和 C API 變更<6>. 
* 移植至 Python 3.1: 移植至 Python 3 1. 

@end menu

@node PEP 372：有序字典,PEP 378 Format Specifier for Thousands Separator,,Python 3 1 有什麼新功能
@anchor{whatsnew/3 1 pep-372-ordered-dictionaries}@anchor{147e}
@subsection 
@geindex Python Enhancement Proposals; PEP 372
`PEP 372'：有序字典


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{7ec,,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{4db,,collections.namedtuple()} now
returns an ordered dictionary with the values appearing in the same order as
the underlying tuple indices.  The @ref{86,,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/} - 有序字典

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,其他語言更動<13>,PEP 372：有序字典,Python 3 1 有什麼新功能
@anchor{whatsnew/3 1 pep-378-format-specifier-for-thousands-separator}@anchor{147f}
@subsection PEP 378: Format Specifier for Thousands Separator


The built-in @ref{199,,format()} function and the @ref{82c,,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{19b,,int}, @ref{196,,float}, @ref{197,,complex}
and @ref{1fe,,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 其他語言更動<13>,新增、改進和棄用的模組,PEP 378 Format Specifier for Thousands Separator,Python 3 1 有什麼新功能
@anchor{whatsnew/3 1 other-language-changes}@anchor{1480}
@subsection 其他語言更動


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{19b,,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

（由 Fredrik Johansson、Victor Stinner、Raymond Hettinger 和 Mark Dickinson 貢獻；bpo-3439@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3439}。）

@item 
The fields in @ref{199,,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@}'}.

（由 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{1475,,bytes.maketrans()} and @ref{1476,,bytearray.maketrans()}.
This change solves the confusion around which types were supported by the
@ref{d8,,string} module. Now, @ref{169,,str}, @ref{192,,bytes}, and
@ref{343,,bytearray} each have their own `maketrans' and `translate'
methods with intermediate translation tables of the appropriate type.

（由 Georg Brandl 貢獻；bpo-5675@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5675}。）

@item 
The syntax of the @ref{186,,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.

（由 Georg Brandl 和 Mattias Brändström 貢獻；appspot 問題 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

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

（由 Eric Smith 和 Mark Dickinson 貢獻；bpo-1580@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1580}）
@end itemize

@node 新增、改進和棄用的模組,最佳化<13>,其他語言更動<13>,Python 3 1 有什麼新功能
@anchor{whatsnew/3 1 new-improved-and-deprecated-modules}@anchor{1481}
@subsection 新增、改進和棄用的模組



@itemize *

@item 
Added a @ref{1292,,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

（由 Raymond Hettinger 貢獻；bpo-1696199@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1696199}。）

@item 
Added a new module, @ref{ff,,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.

（由 Guilherme Polo 貢獻；bpo-2983@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2983}。）

@item 
The @ref{654,,gzip.GzipFile} and @ref{a5f,,bz2.BZ2File} classes now support
the context management protocol:

@example
>>> # 在寫入後自動關閉檔案
>>> with gzip.GzipFile(filename, "wb") as f:
...     f.write(b"xxx")
@end example

（由 Antoine Pitrou 貢獻。）

@item 
The @ref{3a,,decimal} module now supports methods for creating a
decimal object from a binary @ref{196,,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.

（由 Raymond Hettinger 和 Mark Dickinso 貢獻。）

@item 
The @ref{85,,itertools} module grew two new functions.  The
@ref{1482,,itertools.combinations_with_replacement()} function is one of
four for generating combinatorics including permutations and Cartesian
products.  The @ref{1483,,itertools.compress()} function mimics its namesake
from APL.  Also, the existing @ref{1484,,itertools.count()} function now has
an optional `step' argument and can accept any type of counting
sequence including @ref{213,,fractions.Fraction} and
@ref{1fe,,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

（由 Raymond Hettinger 貢獻。）

@item 
@ref{4db,,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

（由 Raymond Hettinger 貢獻；bpo-1818@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1818}。）

@item 
The @ref{59d,,re.sub()}、@ref{59e,,re.subn()} 和 @ref{59c,,re.split()} 函式現在接受一個 flags 參數。

（由 Gregory Smith 貢獻。）

@item 
The @ref{8b,,logging} module now implements a simple @ref{1485,,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

（由 Vinay Sajip 貢獻；bpo-4384@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4384}）。

@item 
The @ref{c3,,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.

（由 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{138,,zipimport} (or any other conformant 
@geindex Python Enhancement Proposals; PEP 302
PEP 302@footnote{https://peps.python.org/pep-0302/} loader).

（由 Alexander Belopolsky 貢獻；bpo-4201@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4201}。）

@item 
@ref{217,,functools.partial} objects can now be pickled.
@end itemize

@quotation

（由 Antoine Pitrou 和 Jesse Noller 建議。由 Jack Diederich 實作；bpo-5228@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5228}。）
@end quotation


@itemize *

@item 
Add @ref{ba,,pydoc} help topics for symbols so that @code{help('@@')}
works as expected in the interactive environment.

（由 David Laban 貢獻；bpo-4739@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4739}。）

@item 
The @ref{10c,,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{186,,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{1486,,assertSetEqual()},
@ref{1487,,assertDictEqual()},
@code{assertDictContainsSubset()},
@ref{1488,,assertListEqual()},
@ref{1489,,assertTupleEqual()},
@ref{148a,,assertSequenceEqual()},
@ref{74b,,assertRaisesRegexp()},
@ref{148b,,assertIsNone()},
and @ref{148c,,assertIsNotNone()}.

（由 Benjamin Peterson 和 Antoine Pitrou 貢獻。）

@item 
The @ref{83,,io} 模組為 @ref{148d,,seek()} 方法新增了三個常數：@ref{148e,,SEEK_SET}、@ref{148f,,SEEK_CUR} 和 @ref{1490,,SEEK_END}。

@item 
The @ref{8a7,,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

（由 Ross Light 貢獻；bpo-4285@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4285}。）

@item 
The @code{nntplib} and @ref{78,,imaplib} modules now support IPv6.

（由 Derek Morr 貢獻；bpo-1655@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1655} 和 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.

（由 Alexandre Vassalotti 和 Antoine Pitrou 貢獻，bpo-6137@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6137}。）

@item 
A new module, @ref{7b,,importlib} was added.  It provides a complete, portable,
pure Python reference implementation of the @ref{7f1,,import} statement and its
counterpart, the @ref{ac8,,__import__()} function.  It represents a substantial
step forward in documenting and defining the actions that take place during
imports.

（由 Brett Cannon 貢獻。）
@end itemize

@node 最佳化<13>,IDLE<2>,新增、改進和棄用的模組,Python 3 1 有什麼新功能
@anchor{whatsnew/3 1 optimizations}@anchor{1491}
@subsection 最佳化


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.

（由 Amaury Forgeot d'Arc 和 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.

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

（由 Antoine Pitrou 和其他一些參與者共同貢獻，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.

（由 Antoine Pitrou 和 Amaury Forgeot d'Arc 貢獻，bpo-4868@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4868}。）

@item 
The @ref{86,,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{169,,str}, not with @ref{192,,bytes}.  That change makes the
module closely match the JSON specification@footnote{https://json.org/}
which is defined in terms of Unicode.

（由 Bob Ippolito 貢獻，由 Antoine Pitrou 和 Benjamin Peterson 轉換為 Py3.1；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.

（由 Jake McGuire 和 Antoine Pitrou 貢獻；bpo-5084@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5084}。）
@end itemize

@node IDLE<2>,建置和 C API 變更<6>,最佳化<13>,Python 3 1 有什麼新功能
@anchor{whatsnew/3 1 idle}@anchor{1492}
@subsection IDLE



@itemize *

@item 
IDLE's format menu now provides an option to strip trailing whitespace
from a source file.

（由 Roger D. Serwy 貢獻；bpo-5150@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5150}。）
@end itemize

@node 建置和 C API 變更<6>,移植至 Python 3 1,IDLE<2>,Python 3 1 有什麼新功能
@anchor{whatsnew/3 1 build-and-c-api-changes}@anchor{1493}
@subsection 建置和 C API 變更


Python 建置程序和 C API 的變更包括：


@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{1494,,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

（由 Mark Dickinson 貢獻；bpo-4258@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4258}。）

@item 
The @ref{1495,,PyLong_AsUnsignedLongLong()} function now handles a negative
`pylong' by raising @ref{a78,,OverflowError} instead of @ref{198,,TypeError}.

（由 Mark Dickinson 和 Lisandro Dalcrin 貢獻；bpo-5175@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5175}。）

@item 
已棄用 @code{PyNumber_Int()}。請改用 @ref{c54,,PyNumber_Long()}。

（由 Mark Dickinson 貢獻；bpo-4910@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4910}。）

@item 
Added a new @ref{1496,,PyOS_string_to_double()} function to replace the
deprecated functions @code{PyOS_ascii_strtod()} and @code{PyOS_ascii_atof()}.

（由 Mark Dickinson 貢獻；bpo-5914@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5914}。）

@item 
Added @ref{1473,,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.

（由 Larry Hastings 貢獻；bpo-5630@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5630}。）
@end itemize

@node 移植至 Python 3 1,,建置和 C API 變更<6>,Python 3 1 有什麼新功能
@anchor{whatsnew/3 1 porting-to-python-3-1}@anchor{1497}
@subsection 移植至 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{'}'計算自然對數的底。

    >>> 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 Python 3 0 有什麼新功能,Python 2 7 有什麼新功能,Python 3 1 有什麼新功能,Python 有什麼新功能？
@anchor{whatsnew/3 0 doc}@anchor{1498}@anchor{whatsnew/3 0 translation-repo}@anchor{1499}@anchor{whatsnew/3 0 what-s-new-in-python-3-0}@anchor{149a}
@section Python 3.0 有什麼新功能


@c XXX Add trademark info for Apple, Microsoft.

@*作者: 
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:: 
* 語法變更概要:: 
* Changes Already Present In Python 2.6: Changes Already Present In Python 2 6. 
* 函式庫變更:: 
* PEP 3101; A New Approach To String Formatting: PEP 3101 A New Approach To String Formatting. 
* Changes To Exceptions:: 
* Miscellaneous Other Changes:: 
* 建置和 C API 變更: 建置和 C API 變更<7>. 
* 效能:: 
* Porting To Python 3.0: Porting To Python 3 0. 

@end menu

@node Common Stumbling Blocks,語法變更概要,,Python 3 0 有什麼新功能
@anchor{whatsnew/3 0 common-stumbling-blocks}@anchor{149b}
@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 是一個函式:: 
* Views And Iterators Instead Of Lists:: 
* Ordering Comparisons:: 
* 整數:: 
* Text Vs. Data Instead Of Unicode Vs. 8-bit: Text Vs Data Instead Of Unicode Vs 8-bit. 

@end menu

@node Print 是一個函式,Views And Iterators Instead Of Lists,,Common Stumbling Blocks
@anchor{whatsnew/3 0 print-is-a-function}@anchor{149c}
@subsubsection Print 是一個函式


@code{print} 陳述式已經被 @ref{1170,,print()} 函式所取代，且舊 @code{print} 陳述式的大部分特殊語法也被關鍵字引數所取代 (
@geindex Python Enhancement Proposals; PEP 3105
PEP 3105@footnote{https://peps.python.org/pep-3105/})。範例如下：

@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{1170,,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{1170,,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 是一個函式,Common Stumbling Blocks
@anchor{whatsnew/3 0 views-and-iterators-instead-of-lists}@anchor{149d}
@subsubsection Views And Iterators Instead Of Lists


一些眾所周知的 API 不再回傳串列：


@itemize *

@item 
@ref{183,,dict} methods @ref{9c9,,dict.keys()}, @ref{9cb,,dict.items()} and
@ref{9ca,,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{19f,,map()} and @ref{a5d,,filter()} return iterators.  If you really need
a list and the input sequences are all of equal length, a quick
fix is to wrap @ref{19f,,map()} in @ref{24d,,list()}, e.g. @code{list(map(...))},
but a better fix is
often to use a list comprehension (especially when the original code
uses @ref{149e,,lambda}), or rewriting the code so it doesn't need a
list at all.  Particularly tricky is @ref{19f,,map()} invoked for the
side effects of the function; the correct transformation is to use a
regular @ref{348,,for} loop (since creating a list would just be
wasteful).

If the input sequences are not of equal length, @ref{19f,,map()} will
stop at the termination of the shortest of the sequences. For full
compatibility with @ref{19f,,map()} from Python 2.x, also wrap the sequences in
@ref{149f,,itertools.zip_longest()}, e.g. @code{map(func, *sequences)} becomes
@code{list(map(func, itertools.zip_longest(*sequences)))}.

@item 
@ref{b34,,range()} now behaves like @code{xrange()} used to behave, except
it works with values of arbitrary size.  The latter no longer
exists.

@item 
@ref{1a0,,zip()} 現在會回傳一個疊代器。
@end itemize

@node Ordering Comparisons,整數,Views And Iterators Instead Of Lists,Common Stumbling Blocks
@anchor{whatsnew/3 0 ordering-comparisons}@anchor{14a0}
@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{198,,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{dc2,,sorted()} and @ref{dc3,,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{14a1,,__lt__()} for sorting,
@ref{ce9,,__eq__()} with @ref{cea,,__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 整數,Text Vs Data Instead Of Unicode Vs 8-bit,Ordering Comparisons,Common Stumbling Blocks
@anchor{whatsnew/3 0 integers}@anchor{14a2}
@subsubsection 整數



@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 237
PEP 237@footnote{https://peps.python.org/pep-0237/}: Essentially, @code{long} renamed to @ref{19b,,int}.
That is, there is only one built-in integral type, named
@ref{19b,,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{13c6,,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{1c1,,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{169,,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,,整數,Common Stumbling Blocks
@anchor{whatsnew/3 0 text-vs-data-instead-of-unicode-vs-8-bit}@anchor{14a3}
@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{169,,str}, the type used to hold data is
@ref{192,,bytes}.  The biggest difference with the 2.x situation is
that any attempt to mix text and data in Python 3.0 raises
@ref{198,,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{bff,,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{169,,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{169,,str} and @ref{192,,bytes} types cannot be mixed, you
must always explicitly convert between them.  Use @ref{ac9,,str.encode()}
to go from @ref{169,,str} to @ref{192,,bytes}, and @ref{aca,,bytes.decode()}
to go from @ref{192,,bytes} to @ref{169,,str}.  You can also use
@code{bytes(s, encoding=...)} and @code{str(b, encoding=...)},
respectively.

@item 
Like @ref{169,,str}, the @ref{192,,bytes} type is immutable.  There is a
separate `mutable' type to hold buffered binary data,
@ref{343,,bytearray}.  Nearly all APIs that accept @ref{192,,bytes} also
accept @ref{343,,bytearray}.  The mutable API is based on
@ref{4ba,,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{169,,str} instead.  The @ref{169,,str} and @ref{192,,bytes} types
don't have functionality enough in common to warrant a shared base
class.  The @code{2to3} tool (see below) replaces every occurrence of
@code{basestring} with @ref{169,,str}.

@item 
Files opened as text files (still the default mode for @ref{315,,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{758,,sys.stdin}, @ref{cc4,,sys.stdout} and
@ref{b2a,,sys.stderr} are now unicode-only text files (i.e., they are
instances of @ref{89d,,io.TextIOBase}).  To read and write bytes data
with these streams, you need to use their @ref{14a4,,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{315,,open()} and many functions in the
@ref{a5,,os} module) that take filenames accept @ref{192,,bytes} objects
as well as strings, and a few APIs have a way to ask for a
@ref{192,,bytes} return value.  Thus, @ref{12fb,,os.listdir()} returns a
list of @ref{192,,bytes} instances if the argument is a @ref{192,,bytes}
instance, and @ref{c79,,os.getcwdb()} returns the current working
directory as a @ref{192,,bytes} instance.  Note that when
@ref{12fb,,os.listdir()} returns a list of strings, filenames that
cannot be decoded properly are omitted rather than raising
@ref{460,,UnicodeError}.

@item 
Some system APIs like @ref{259,,os.environ} and @ref{1465,,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{1c1,,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{83,,io} module and use @ref{1124,,io.StringIO} or
@ref{109f,,io.BytesIO} for text and data respectively.

@item 
也請見為了 Python 3.0 所更新的 @ref{14a5,,Unicode HOWTO}。
@end itemize

@node 語法變更概要,Changes Already Present In Python 2 6,Common Stumbling Blocks,Python 3 0 有什麼新功能
@anchor{whatsnew/3 0 overview-of-syntax-changes}@anchor{14a6}
@subsection 語法變更概要


This section gives a brief overview of every `syntactic' change in
Python 3.0.

@menu
* 新增語法:: 
* 語法變更:: 
* 已被移除的語法:: 

@end menu

@node 新增語法,語法變更,,語法變更概要
@anchor{whatsnew/3 0 new-syntax}@anchor{14a7}
@subsubsection 新增語法



@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{456,,__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{14a8,,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

這會將 `a' 設為 @code{0}、將 `b' 設為 @code{4}，並將 `rest' 設為 @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{14a9,,bin()}.

@item 
Bytes literals are introduced with a leading @code{b} or @code{B}, and
there is a new corresponding built-in function, @ref{192,,bytes()}.
@end itemize

@node 語法變更,已被移除的語法,新增語法,語法變更概要
@anchor{whatsnew/3 0 changed-syntax}@anchor{14aa}
@subsubsection 語法變更



@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{7fc,,raise} statement syntax:
@code{raise [@var{expr} [from @var{expr}]]}.  See below.

@item 
@code{as} and @ref{186,,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{1ab,,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

現在必須使用：

@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{c75,,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{24d,,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 已被移除的語法,,語法變更,語法變更概要
@anchor{whatsnew/3 0 removed-syntax}@anchor{14ab}
@subsubsection 已被移除的語法



@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 
移除反引號（請改用 @ref{1c1,,repr()}）。

@item 
移除 @code{<>}（請改用 @code{!=}）。

@item 
Removed keyword: @ref{49d,,exec()} is no longer a keyword; it remains as
a function.  (Fortunately the function syntax was also accepted in
2.x.)  Also note that @ref{49d,,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{14ac,,from} `module' @ref{7f1,,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{7f1,,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,函式庫變更,語法變更概要,Python 3 0 有什麼新功能
@anchor{whatsnew/3 0 changes-already-present-in-python-2-6}@anchor{14ad}
@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{14ae,,Python 2.6 有什麼新功能} should be
consulted for longer descriptions.


@itemize *

@item 
@ref{14af,,PEP 343：'with' 陳述式}.  The @ref{186,,with} statement is now a standard
feature and no longer needs to be imported from the @ref{0,,__future__}.
Also check out @ref{14b0,,Writing Context Managers} and
@ref{14b1,,contextlib 模組}.

@item 
@ref{14b2,,PEP 366; Explicit Relative Imports From a Main Module}.  This enhances the usefulness of the @ref{23c,,-m}
option when the referenced module lives in a package.

@item 
@ref{14b3,,PEP 370; Per-user site-packages Directory}。

@item 
@ref{14b4,,PEP 371; The multiprocessing Package}。

@item 
@ref{14b5,,PEP 3101; Advanced String Formatting}.  Note: the 2.6 description mentions the
@ref{199,,format()} method for both 8-bit and Unicode strings.  In 3.0,
only the @ref{169,,str} type (text strings with Unicode support)
supports this method; the @ref{192,,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{14b6,,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{14b7,,PEP 3110; Exception-Handling Changes}.  The @ref{1ab,,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{14b8,,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{192,,bytes}.

@item 
@ref{14b9,,PEP 3116：新 I/O 函式庫}.  The @ref{83,,io} module is now the standard way of
doing file I/O.  The built-in @ref{315,,open()} function is now an
alias for @ref{739,,io.open()} and has additional keyword arguments
`encoding', `errors', `newline' and `closefd'.  Also note that an
invalid `mode' argument now raises @ref{2eb,,ValueError}, not
@ref{124e,,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{14ba,,PEP 3118：修訂緩衝協定}.  The old builtin @code{buffer()} is now really gone;
the new builtin @ref{165,,memoryview()} provides (mostly) similar
functionality.

@item 
@ref{14bb,,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{183,,dict}
and @ref{24d,,list} conform to the @ref{12ad,,collections.MutableMapping}
and @ref{4ba,,collections.MutableSequence} ABCs, respectively.

@item 
@ref{14bc,,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{14bd,,PEP 3129; Class Decorators}。

@item 
@ref{14be,,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{61,,fractions} module which implements @ref{14bf,,numbers.Rational}.
@end itemize

@node 函式庫變更,PEP 3101 A New Approach To String Formatting,Changes Already Present In Python 2 6,Python 3 0 有什麼新功能
@anchor{whatsnew/3 0 library-changes}@anchor{14c0}
@subsection 函式庫變更


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{6c,,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 
一些模組因為舊名稱違反了 
@geindex Python Enhancement Proposals; PEP 8
PEP 8@footnote{https://peps.python.org/pep-0008/} 或其他原因而被重新命名。以下為變更清單：


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

舊名

@tab

新名

@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 @ref{ab,,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{83,,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{35,,dbm}（@code{anydbm}、@code{dbhash}、@code{dbm}、@code{dumbdbm}、@code{gdbm}、@code{whichdb}）。

@item 
@ref{6f,,html}（@code{HTMLParser}、@code{htmlentitydefs}）。

@item 
@ref{72,,http}（@code{httplib}、@code{BaseHTTPServer}、@code{CGIHTTPServer}、@code{SimpleHTTPServer}、@code{Cookie}、@code{cookielib}）。

@item 
@ref{f6,,tkinter} (all @code{Tkinter}-related modules except
@ref{107,,turtle}).  The target audience of @ref{107,,turtle} doesn't
really care about @ref{f6,,tkinter}.  Also note that as of Python
2.6, the functionality of @ref{107,,turtle} has been greatly enhanced.

@item 
@ref{10e,,urllib}（@code{urllib}、@code{urllib2}、@code{urlparse}、@code{robotparse}）。

@item 
@ref{133,,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 
移除 @code{sets}。請使用內建的 @ref{184,,set()} 類別。

@item 
Cleanup of the @ref{df,,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{6df,,sys.last_type}
etc. remain.)

@item 
Cleanup of the @ref{4b9,,array.array} type: the @code{read()} and
@code{write()} methods are gone; use @ref{14c1,,fromfile()} and
@ref{14c2,,tofile()} instead.  Also, the @code{'c'} typecode for array is
gone -- use either @code{'b'} for bytes or @code{'u'} for Unicode
characters.

@item 
清理 @ref{a3,,operator} 模組：移除 @code{sequenceIncludes()} 和 @code{isCallable()}。

@item 
Cleanup of the @code{thread} module: @code{acquire_lock()} and
@code{release_lock()} are gone; use @ref{8a0,,acquire()} and
@ref{14c3,,release()} instead.

@item 
清理 @ref{bd,,random} 模組：移除 @code{jumpahead()} API。

@item 
移除 @code{new} 模組。

@item 
The functions @code{os.tmpnam()}, @code{os.tempnam()} and
@code{os.tmpfile()} have been removed in favor of the @ref{e6,,tempfile}
module.

@item 
The @ref{101,,tokenize} module has been changed to work with bytes.  The
main entry point is now @ref{6f9,,tokenize.tokenize()}, instead of
generate_tokens.

@item 
@code{string.letters} and its friends (@code{string.lowercase} and
@code{string.uppercase}) are gone.  Use
@ref{14c4,,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 @ref{13,,builtins}, not @code{__builtins__}!
@end itemize

@node PEP 3101 A New Approach To String Formatting,Changes To Exceptions,函式庫變更,Python 3 0 有什麼新功能
@anchor{whatsnew/3 0 pep-3101-a-new-approach-to-string-formatting}@anchor{14c5}
@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,Python 3 0 有什麼新功能
@anchor{whatsnew/3 0 changes-to-exceptions}@anchor{14c6}
@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{7d0,,BaseException}.  This is the root of the exception
hierarchy.  This is not new as a recommendation, but the
`requirement' to inherit from @ref{7d0,,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{bc4,,Exception};
@ref{7d0,,BaseException} should only be used as a base class for
exceptions that should only be handled at the top level, such as
@ref{f37,,SystemExit} or @ref{bbc,,KeyboardInterrupt}.  The recommended
idiom for handling all exceptions except for this latter category is
to use @ref{1ab,,except} @ref{bc4,,Exception}.

@item 
@code{StandardError} 已被移除。

@item 
Exceptions no longer behave as sequences.  Use the @ref{786,,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{14c7,,__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{1ab,,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{1ab,,except} or @ref{1b0,,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{14c8,,__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{14c9,,__cause__} attribute of the secondary exception.  The
traceback printed when an unhandled exception occurs walks the chain
of @code{__cause__} and @ref{14c8,,__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{14c7,,__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{893,,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,建置和 C API 變更<7>,Changes To Exceptions,Python 3 0 有什麼新功能
@anchor{whatsnew/3 0 miscellaneous-other-changes}@anchor{14ca}
@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{14cb}
@subsubsection Operators And Special Methods



@itemize *

@item 
@code{!=} now returns the opposite of @code{==}, unless @code{==} returns
@ref{1a2,,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{14cc,,__setitem__()} or
@ref{14cd,,__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{9d1,,next()} method has been renamed to
@ref{14ce,,__next__()}.

@item 
The @code{__oct__()} and @code{__hex__()} special methods are removed
-- @ref{14cf,,oct()} and @ref{14d0,,hex()} use @ref{19e,,__index__()} now to convert
the argument to an integer.

@item 
移除對 @code{__members__} 和 @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{14d1,,__closure__},
@ref{597,,__code__}, @ref{14d2,,__defaults__},
@ref{14d3,,__dict__}, @ref{13da,,__doc__},
@ref{14d4,,__globals__}, @ref{14d5,,__name__},
respectively.

@item 
@code{__nonzero__()} 現在為 @ref{14d6,,__bool__()}。
@end itemize

@node Builtins,,Operators And Special Methods,Miscellaneous Other Changes
@anchor{whatsnew/3 0 builtins}@anchor{14d7}
@subsubsection Builtins



@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 3135
PEP 3135@footnote{https://peps.python.org/pep-3135/}: New @ref{1a6,,super()}.  You can now invoke @ref{1a6,,super()}
without arguments and (assuming this is in a regular instance method
defined inside a @ref{14d8,,class} statement) the right class and
instance will automatically be chosen.  With arguments, the behavior
of @ref{1a6,,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{14d9,,input()}.  That
is, the new @ref{14d9,,input()} function reads a line from
@ref{758,,sys.stdin} and returns it with the trailing newline stripped.
It raises @ref{14da,,EOFError} if the input is terminated prematurely.
To get the old behavior of @ref{14d9,,input()}, use @code{eval(input())}.

@item 
A new built-in function @ref{9d1,,next()} was added to call the
@ref{14ce,,__next__()} method on an object.

@item 
The @ref{14db,,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{14dc,,sys.intern()}.

@item 
移除 @code{apply()}。請使用 @code{f(*args)} 來替換 @code{apply(f, args)}。

@item 
Removed @ref{13c7,,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 
移除 @code{execfile()}。請使用 @code{exec(open(fn).read())} 來替換 @code{execfile(fn)}。

@item 
Removed the @code{file} type.  Use @ref{315,,open()}.  There are now several
different kinds of streams that open can return in the @ref{83,,io} module.

@item 
Removed @code{reduce()}.  Use @ref{21a,,functools.reduce()} if you really
need it; however, 99 percent of the time an explicit @ref{348,,for}
loop is more readable.

@item 
移除 @code{reload()}。請使用 @code{imp.reload()}。

@item 
Removed. @code{dict.has_key()} -- use the @ref{349,,in} operator
instead.
@end itemize

@c ======================================================================

@node 建置和 C API 變更<7>,效能,Miscellaneous Other Changes,Python 3 0 有什麼新功能
@anchor{whatsnew/3 0 build-and-c-api-changes}@anchor{14dd}
@subsection 建置和 C API 變更


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/}：新的緩衝 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{14de,,PyObject_HEAD} conform to standard C.

@item 
No more C API support for restricted execution.

@item 
@code{PyNumber_Coerce()}, @code{PyNumber_CoerceEx()},
@code{PyMember_Get()}, and @code{PyMember_Set()} C APIs are removed.

@item 
New C API @ref{3d9,,PyImport_ImportModuleNoBlock()}, works like
@ref{3da,,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 
移除 C API 中的 @code{METH_OLDARGS} 和 @code{WITH_CYCLE_GC}。
@end itemize

@c ======================================================================

@node 效能,Porting To Python 3 0,建置和 C API 變更<7>,Python 3 0 有什麼新功能
@anchor{whatsnew/3 0 performance}@anchor{14df}
@subsection 效能


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,,效能,Python 3 0 有什麼新功能
@anchor{whatsnew/3 0 porting-to-python-3-0}@anchor{14e0}
@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{14e1,,遷移延伸模組到 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 Python 2 7 有什麼新功能,Python 2 6 有什麼新功能,Python 3 0 有什麼新功能,Python 有什麼新功能？
@anchor{whatsnew/2 7 doc}@anchor{14e2}@anchor{whatsnew/2 7 translation-repo}@anchor{14e3}@anchor{whatsnew/2 7 what-s-new-in-python-2-7}@anchor{14e4}
@section Python 2.7 有什麼新功能


@*作者: 
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{1fe,,Decimal} class.
There are some useful additions to the standard library, such as a
greatly enhanced @ref{10c,,unittest} module, the @ref{7,,argparse} module
for parsing command-line options, convenient @ref{7ec,,OrderedDict}
and @ref{1292,,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
* Python 2.x 的未來: 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. 
* 其他語言更動: 其他語言更動<14>. 
* New and Improved Modules:: 
* 建置和 C API 變更: 建置和 C API 變更<8>. 
* Other Changes and Fixes:: 
* 移植至 Python 2.7: 移植至 Python 2 7. 
* New Features Added to Python 2.7 Maintenance Releases: New Features Added to Python 2 7 Maintenance Releases. 
* 致謝:: 

@end menu

@node Python 2 x 的未來,Changes to the Handling of Deprecation Warnings,,Python 2 7 有什麼新功能
@anchor{whatsnew/2 7 the-future-for-python-2-x}@anchor{14e5}@anchor{whatsnew/2 7 whatsnew27-python31}@anchor{14e6}
@subsection 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{14e7,,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,Python 2 x 的未來,Python 2 7 有什麼新功能
@anchor{whatsnew/2 7 changes-to-the-handling-of-deprecation-warnings}@anchor{14e8}
@subsection Changes to the Handling of Deprecation Warnings


For Python 2.7, a policy decision was made to silence warnings only of
interest to developers by default.  @ref{1a3,,DeprecationWarning} and its
descendants are now ignored unless otherwise requested, preventing
users from seeing warnings triggered by an application.  This change
was also made in the branch that became Python 3.2. (Discussed
on stdlib-sig and carried out in bpo-7319@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7319}.)

In previous releases, @ref{1a3,,DeprecationWarning} messages were
enabled by default, providing Python developers with a clear
indication of where their code may break in a future major version
of Python.

However, there are increasingly many users of Python-based
applications who are not directly involved in the development of
those applications.  @ref{1a3,,DeprecationWarning} messages are
irrelevant to such users, making them worry about an application
that's actually working correctly and burdening application developers
with responding to these concerns.

You can re-enable display of @ref{1a3,,DeprecationWarning} messages by
running Python with the @ref{abc,,-Wdefault} (short form:
@ref{abc,,-Wd}) switch, or by setting the 
@geindex PYTHONWARNINGS
@geindex 環境變數; PYTHONWARNINGS
@ref{d9e,,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,Python 2 7 有什麼新功能
@anchor{whatsnew/2 7 python-3-1-features}@anchor{14e9}
@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{186,,with} statement.

@item 
A new version of the @ref{83,,io} library, rewritten in C for performance.

@item 
The ordered-dictionary type described in @ref{14ea,,PEP 372; Adding an Ordered Dictionary to collections}.

@item 
The new @code{","} format specifier described in @ref{14eb,,PEP 378; Format Specifier for Thousands Separator}.

@item 
@ref{165,,memoryview} 物件。

@item 
A small subset of the @ref{7b,,importlib} module,
@ref{14ec,,described below}.

@item 
The @ref{1c1,,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{14db,,round()} function is also now correctly rounded.

@item 
The @ref{1473,,PyCapsule} type, used to provide a C API for extension modules.

@item 
@ref{1467,,PyLong_AsLongAndOverflow()} C API 函式。
@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,Python 2 7 有什麼新功能
@anchor{whatsnew/2 7 pep-0372}@anchor{14ea}@anchor{whatsnew/2 7 pep-372-adding-an-ordered-dictionary-to-collections}@anchor{14ed}
@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{7ec,,OrderedDict} class in the @ref{1e,,collections} module.

The @ref{7ec,,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{14ee,,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{7ec,,OrderedDict} with a regular dictionary
ignores the insertion order and just compares the keys and values.

How does the @ref{7ec,,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{bcb,,_asdict()} method for
@ref{4db,,collections.namedtuple()} now returns an ordered dictionary with the
values appearing in the same order as the underlying tuple indices.

@item 
The @ref{86,,json} module's @ref{f3e,,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/} - 在 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,Python 2 7 有什麼新功能
@anchor{whatsnew/2 7 pep-0378}@anchor{14eb}@anchor{whatsnew/2 7 pep-378-format-specifier-for-thousands-separator}@anchor{14ef}
@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{8a,,locale} module,
which can use different separators ("," in North America, "." in
Europe) and different grouping sizes, but @ref{8a,,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{82c,,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{8a,,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

由 Raymond Hettinger 撰寫 PEP；由 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>,Python 2 7 有什麼新功能
@anchor{whatsnew/2 7 pep-389-the-argparse-module-for-parsing-command-lines}@anchor{14f0}
@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{65,,getopt}, @ref{a4,,optparse}, and
@ref{7,,argparse}.  The @ref{65,,getopt} module closely resembles the C
library's @code{getopt()} function, so it remains useful if you're writing a
Python prototype that will eventually be rewritten in C.
@ref{a4,,optparse} becomes redundant, but there are no plans to remove it
because there are many scripts still using it, and there's no
automated way to update these scripts.  (Making the @ref{7,,argparse}
API consistent with @ref{a4,,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}.

以下是個範例：

@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{30b,,FileType}, which will
automatically open files for you and understands that @code{'-'} means
standard input or output.


@subsubheading 也參考



@table @asis

@item @ref{7,,argparse} 文件

argparse 模組的文件頁面。

@item @ref{13af,,將 optparse 程式碼遷移到 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

由 Steven Bethard 撰寫 PEP 與實作。
@end table


@node PEP 391 Dictionary-Based Configuration For Logging,PEP 3106 Dictionary Views,PEP 389 The argparse Module for Parsing Command Lines,Python 2 7 有什麼新功能
@anchor{whatsnew/2 7 pep-391-dictionary-based-configuration-for-logging}@anchor{14f1}
@subsection PEP 391: Dictionary-Based Configuration For Logging


The @ref{8b,,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{8b,,logging} also supports a @ref{d40,,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{13b1,,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{14f2,,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{8b,,logging} module, all
implemented by Vinay Sajip, are:

@c rev79293


@itemize *

@item 
The @ref{865,,SysLogHandler} class now supports
syslogging over TCP.  The constructor has a `socktype' parameter
giving the type of socket to use, either @ref{14f3,,socket.SOCK_DGRAM}
for UDP or @ref{14f4,,socket.SOCK_STREAM} for TCP.  The default
protocol remains UDP.

@item 
@ref{d3e,,Logger} instances gained a @ref{14f5,,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{14f6,,LoggerAdapter} class gained an
@ref{14f7,,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

由 Vinay Sajip 撰寫 PEP 與實作。
@end table


@node PEP 3106 Dictionary Views,PEP 3137 The memoryview Object,PEP 391 Dictionary-Based Configuration For Logging,Python 2 7 有什麼新功能
@anchor{whatsnew/2 7 pep-3106-dictionary-views}@anchor{14f8}
@subsection PEP 3106: Dictionary Views


The dictionary methods @ref{9c9,,keys()}, @ref{9ca,,values()}, and
@ref{9cb,,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{9c9,,keys()},
@ref{9ca,,values()}, and @ref{9cb,,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{9c9,,keys()},
@ref{9ca,,values()}, and @ref{9cb,,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,其他語言更動<14>,PEP 3106 Dictionary Views,Python 2 7 有什麼新功能
@anchor{whatsnew/2 7 pep-3137-the-memoryview-object}@anchor{14f9}
@subsection PEP 3137: The memoryview Object


The @ref{165,,memoryview} object provides a view of another object's
memory content that matches the @ref{192,,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{165,,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 其他語言更動<14>,New and Improved Modules,PEP 3137 The memoryview Object,Python 2 7 有什麼新功能
@anchor{whatsnew/2 7 other-language-changes}@anchor{14fa}
@subsection 其他語言更動


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() # 空集合
set([])
>>> @{@}    # 空字典
@{@}
@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{186,,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

等價於：

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

（於 @indicateurl{https://codereview.appspot.com/53094} 提出；由 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{169,,str()} on
floats and complex numbers; the @ref{196,,float} and @ref{197,,complex}
constructors;
numeric formatting; serializing and
deserializing floats and complex numbers using the
@ref{91,,marshal}, @ref{ab,,pickle}
and @ref{86,,json} modules;
parsing of float and imaginary literals in Python code;
and @ref{1fe,,Decimal}-to-float conversion.

Related to this, the @ref{1c1,,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{14fb,,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

（由 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{82c,,str.format()} method now supports automatic numbering of the replacement
fields.  This makes using @ref{82c,,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{82c,,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{199,,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{82a,,object.__format__()} method now triggers
a @ref{abd,,PendingDeprecationWarning} if it's passed a format string,
because the @code{__format__()} method for @ref{c75,,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{19b,,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

（由 Fredrik Johansson 和 Victor Stinner 貢獻；bpo-3439@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3439}。）

@item 
The @ref{7f1,,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{343,,bytearray} type's @ref{14fc,,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{489,,@@classmethod} and
@ref{451,,@@staticmethod} to wrap
methods as class or static methods, the wrapper object now
exposes the wrapped function as their @ref{14fd,,__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{5e8,,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{124e,,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{4ac,,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:: 
* 最佳化: 最佳化<14>. 

@end menu

@node Interpreter Changes,最佳化<14>,,其他語言更動<14>
@anchor{whatsnew/2 7 interpreter-changes}@anchor{14fe}@anchor{whatsnew/2 7 new-27-interpreter}@anchor{14ff}
@subsubsection Interpreter Changes


A new environment variable, 
@geindex PYTHONWARNINGS
@geindex 環境變數; PYTHONWARNINGS
@ref{d9e,,PYTHONWARNINGS},
allows controlling warnings.  It should be set to a string
containing warning settings, equivalent to those
used with the @ref{abc,,-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{75,,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 最佳化<14>,,Interpreter Changes,其他語言更動<14>
@anchor{whatsnew/2 7 optimizations}@anchor{1500}
@subsubsection 最佳化


Several performance enhancements have been added:


@itemize *

@item 
A new opcode was added to perform the initial setup for
@ref{186,,with} statements, looking up the @ref{7dd,,__enter__()} and
@ref{1501,,__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

（由 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{343,,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,建置和 C API 變更<8>,其他語言更動<14>,Python 2 7 有什麼新功能
@anchor{whatsnew/2 7 new-and-improved-modules}@anchor{1502}
@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{2d5,,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{165,,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{a5f,,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{1292,,Counter} class in the @ref{1e,,collections}
module is useful for tallying data.  @ref{1292,,Counter} instances
behave mostly like dictionaries but return zero for missing keys instead of
raising a @ref{5df,,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{1292,,Counter} methods.
@ref{1503,,most_common()} returns the N most common
elements and their counts.  @ref{1504,,elements()}
returns an iterator over the contained elements, repeating each
element as many times as its count.
@ref{13df,,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

由 Raymond Hettinger 貢獻；bpo-1696199@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1696199}。

@c revision 79660

New class: @ref{7ec,,OrderedDict} is described in the earlier
section @ref{14ea,,PEP 372; Adding an Ordered Dictionary to collections}.

New method: The @ref{7ed,,deque} data type now has a
@ref{13e1,,count()} method that returns the number of
contained elements equal to the supplied argument `x', and a
@ref{13e2,,reverse()} method that reverses the elements
of the deque in-place.  @ref{7ed,,deque} also exposes its maximum
length as the read-only @ref{1505,,maxlen} attribute.
(Both features added by Raymond Hettinger.)

The @ref{4db,,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{abe,,Mapping} abstract base class now
returns @ref{1a2,,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

（由 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{186,,with}
statement, has been deprecated, because the @code{with} statement
now supports multiple context managers.

@item 
The @ref{74,,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{d5d,,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{2e,,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{34,,datetime} module's @ref{bba,,timedelta} class
gained a @ref{1506,,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{1fe,,Decimal} class gained a
@ref{1405,,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{1fe,,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{1fe,,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{12b0,,Context} class now accept integers
as well as @ref{1fe,,Decimal} instances; the only exceptions are the
@ref{1507,,canonical()} and @ref{1508,,is_canonical()}
methods.  (Patch by Juan José Conti; bpo-7633@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7633}.)

When using @ref{1fe,,Decimal} instances with a string's
@ref{82c,,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{12a9,,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{3b,,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{3e,,doctest} module's @ref{1509,,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{3f,,email} module's @ref{57b,,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{213,,Fraction} class now accepts a single float or
@ref{1fe,,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{198,,TypeError}.
This fixes an oversight, making the @ref{213,,Fraction}
match the other numeric types.

@c revision 79455

@item 
New class: @ref{aee,,FTP_TLS} in
the @ref{62,,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{150a,,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{113d,,total_ordering()} in the @ref{63,,functools}
module takes a class that defines an @ref{ce9,,__eq__()} method and one of
@ref{14a1,,__lt__()}, @ref{150b,,__le__()}, @ref{150c,,__gt__()}, or @ref{150d,,__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{13db,,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{dc2,,sorted()}, @ref{1106,,min()} and @ref{1107,,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{64,,gc} module's @ref{150e,,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{6b,,gzip} module's @ref{654,,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{89c,,io.BufferedIOBase} ABC, so you can wrap it with
@ref{140f,,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{6b,,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{6c,,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{12cf,,HTTPResponse} class used by the @ref{72,,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{d2d,,HTTPConnection} and @ref{d2e,,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{78,,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{82,,inspect} module's @ref{10b9,,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

由 George Sakkis 貢獻；bpo-3135@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3135}。

@item 
Updated module: The @ref{83,,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{89d,,io.TextIOBase} class now
has an @ref{150f,,errors} attribute giving the error setting
used for encoding and decoding errors (one of @code{'strict'}, @code{'replace'},
@code{'ignore'}).

The @ref{1510,,io.FileIO} class now raises an @ref{2c0,,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{1511,,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{1512,,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{1484,,itertools.count()} function now has a `step' argument that
allows incrementing by values other than 1.  @ref{1484,,count()} also
now allows keyword arguments, and using non-integer values such as
floats or @ref{1fe,,Decimal} instances.  (Implemented by Raymond
Hettinger; bpo-5032@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5032}.)

@ref{1512,,itertools.combinations()} and @ref{1513,,itertools.product()}
previously raised @ref{2eb,,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{86,,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{7ec,,collections.OrderedDict} type, @ref{ead,,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{8f,,mailbox} module's @ref{656,,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{92,,math} module gained
@ref{dce,,erf()} and @ref{dcf,,erfc()} for the error function and the complementary error function,
@ref{13ed,,expm1()} which computes @code{e**x - 1} with more precision than
using @ref{1514,,exp()} and subtracting 1,
@ref{13ee,,gamma()} for the Gamma function, and
@ref{13ef,,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{1166,,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{1515,,getresgid()} and @ref{1516,,getresuid()}, which return the
real, effective, and saved GIDs and UIDs;
@ref{1517,,setresgid()} and @ref{1518,,setresuid()}, which set
real, effective, and saved GIDs and UIDs to new values;
@ref{1519,,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{4b0,,os.fork()} function now re-initializes the import lock in
the child process; this fixes problems on Solaris when @ref{4b0,,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{151a,,normpath()} and
@ref{151b,,abspath()} functions now preserve Unicode; if their input path
is a Unicode string, the return value is also a Unicode string.
(@ref{151a,,normpath()} fixed by Matt Giuca in bpo-5827@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5827};
@ref{151b,,abspath()} fixed by Ezio Melotti in bpo-3426@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3426}.)

@item 
The @ref{ba,,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{be,,re} module's @ref{59c,,split()}, @ref{59d,,sub()}, and @ref{59e,,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{49f,,run_path()} in the @ref{c3,,runpy} module
will execute the code at a provided `path' argument.  `path' can be
the path of a Python source file (@code{example.py}), a compiled
bytecode file (@code{example.pyc}), a directory
(@code{./package/}), or a zip archive (@code{example.zip}).  If a
directory or zip path is provided, it will be added to the front of
@code{sys.path} and the module @ref{1,,__main__} will be imported.  It's
expected that the directory or zip contains a @code{__main__.py};
if it doesn't, some other @code{__main__.py} might be imported from
a location later in @code{sys.path}.  This makes more of the machinery
of @ref{c3,,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{ca,,shutil} module, @ref{6d3,,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{ca,,shutil}'s @ref{c45,,copyfile()} and @ref{c15,,copytree()}
functions now raise a @ref{151c,,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{cb,,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{cc,,site} module, three new functions
return various site- and user-specific paths.
@ref{143f,,getsitepackages()} returns a list containing all
global site-packages directories,
@ref{1441,,getusersitepackages()} returns the path of the user's
site-packages directory, and
@ref{1440,,getuserbase()} returns the value of the @ref{151d,,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{cc,,site} module now reports exceptions occurring
when the @ref{cd,,sitecustomize} module is imported, and will no longer
catch and swallow the @ref{bbc,,KeyboardInterrupt} exception.  (Fixed by
Victor Stinner; bpo-3137@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3137}.)

@item 
The @ref{87b,,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{151e,,recv_into()} and @ref{151f,,recvfrom_into()}
methods will now write into objects that support the buffer API, most usefully
the @ref{343,,bytearray} and @ref{165,,memoryview} objects.  (Implemented by
Antoine Pitrou; bpo-8104@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8104}.)

@item 
The @ref{d2,,SocketServer} module's @ref{1520,,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{1521,,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{1522,,handle_timeout()}
will be called and @ref{1523,,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{d4,,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{6d8,,load_extension()} to load a particular shared library.
(Updated by Gerhard Häring.)

@item 
The @ref{d5,,ssl} module's @ref{ade,,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{741,,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{141f,,ssl.OPENSSL_VERSION} (a string),
@ref{1420,,ssl.OPENSSL_VERSION_INFO} (a 5-tuple), and
@ref{1421,,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{db,,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{1524,,struct.error} exception.  (Changed by Mark Dickinson;
bpo-1523@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1523}.)  The @ref{1477,,pack()} function will also
attempt to use @ref{19e,,__index__()} to convert and pack non-integers
before trying the @ref{19d,,__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{dc,,subprocess} module's
@ref{11bd,,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{1525,,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

（由 Gregory P. Smith 所貢獻。）

The @ref{dc,,subprocess} module will now retry its internal system calls
on receiving an @ref{f82,,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{1526,,is_declared_global()} in the @ref{de,,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{e2,,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{8a7,,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{ede,,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{e4,,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{e4,,tarfile} now supports filtering the @ref{1412,,TarInfo}
objects being added to a tar file.  When you call @ref{de9,,add()},
you may supply an optional `filter' argument
that's a callable.  The `filter' callable will be passed the
@ref{1412,,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{1411,,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{1527,,wait()} method of the @ref{1359,,threading.Event} class
now returns the internal flag on exit.  This means the method will usually
return true because @ref{1527,,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{10b,,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{110,,urlparse} module's @ref{f35,,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{110,,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{7ee,,WeakSet} class in the @ref{11a,,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{12b,,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{134,,xmlrpclib} and
@ref{135,,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{1528,,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{137,,zipfile} module's @ref{8cb,,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{137,,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{1529,,read()} and
@ref{152a,,readline()} now works correctly.
(Contributed by Nir Aides; bpo-7610@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7610}.)

The @ref{152b,,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{2cc,,writestr()} method now has an optional `compress_type' parameter
that lets you override the default compression method specified in the
@ref{8cb,,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
* 新模組：importlib:: 
* 新模組：sysconfig:: 
* ttk; Themed Widgets for Tk: ttk Themed Widgets for Tk. 
* 改進模組：unittest:: 
* 改進模組：ElementTree 1.3: 改進模組：ElementTree 1 3. 

@end menu

@node 新模組：importlib,新模組：sysconfig,,New and Improved Modules
@anchor{whatsnew/2 7 importlib-section}@anchor{14ec}@anchor{whatsnew/2 7 new-module-importlib}@anchor{152c}
@subsubsection 新模組：importlib


Python 3.1 includes the @ref{7b,,importlib} package, a re-implementation
of the logic underlying Python's @ref{7f1,,import} statement.
@ref{7b,,importlib} is useful for implementers of Python interpreters and
to users who wish to write new importers that can participate in the
import process.  Python 2.7 doesn't contain the complete
@ref{7b,,importlib} package, but instead has a tiny subset that contains
a single function, @ref{735,,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{735,,import_module()} both inserts the imported
module into @code{sys.modules} and returns the module object.

以下是一些範例：

@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{7b,,importlib} was implemented by Brett Cannon and introduced in
Python 3.1.

@node 新模組：sysconfig,ttk Themed Widgets for Tk,新模組：importlib,New and Improved Modules
@anchor{whatsnew/2 7 new-module-sysconfig}@anchor{152d}
@subsubsection 新模組：sysconfig


The @ref{e1,,sysconfig} module has been pulled out of the Distutils
package, becoming a new top-level module in its own right.
@ref{e1,,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{174,,get_config_var()} returns variables from Python's
Makefile and the @code{pyconfig.h} file.

@item 
@ref{298,,get_config_vars()} returns a dictionary containing
all of the configuration variables.

@item 
@ref{152e,,get_path()} returns the configured path for
a particular type of module: the standard library,
site-specific modules, platform-specific modules, etc.

@item 
@ref{32c,,is_python_build()} returns true if you're running a
binary from a Python source tree, and false otherwise.
@end itemize

Consult the @ref{e1,,sysconfig} documentation for more details and for
a complete list of functions.

The Distutils package and @ref{e1,,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,改進模組：unittest,新模組：sysconfig,New and Improved Modules
@anchor{whatsnew/2 7 ttk-themed-widgets-for-tk}@anchor{152f}
@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{ff,,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{ff,,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 改進模組：unittest,改進模組：ElementTree 1 3,ttk Themed Widgets for Tk,New and Improved Modules
@anchor{whatsnew/2 7 unittest-section}@anchor{1530}@anchor{whatsnew/2 7 updated-module-unittest}@anchor{1531}
@subsubsection 改進模組：unittest


The @ref{10c,,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{10c,,unittest} module documentation for more details.
(Developed in bpo-6001@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6001}.)

The @ref{11de,,main()} function supports some other new options:


@itemize *

@item 
@ref{1532,,-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{1533,,-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{1534,,removeHandler()} decorator that can be used to mark tests that
should have the control-C handling disabled.

@item 
@ref{1535,,-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{11df,,SkipTest} exception to skip a
test (bpo-1034053@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1034053}).

The error messages for @ref{745,,assertEqual()},
@ref{743,,assertTrue()}, and @ref{744,,assertFalse()}
failures now provide more information.  If you set the
@ref{1536,,longMessage} attribute of your @ref{2b3,,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{749,,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

（由 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{c39,,setUpModule()} and @ref{1537,,tearDownModule()}
functions.  Classes can have @ref{c3a,,setUpClass()} and
@ref{1538,,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{c6b,,addCleanup()} and
@ref{1539,,doCleanups()} were added.
@ref{c6b,,addCleanup()} lets you add cleanup functions that
will be called unconditionally (after @ref{153a,,setUp()} if
@ref{153a,,setUp()} fails, otherwise after @ref{153b,,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{10c,,unittest}.


@itemize *

@item 
@ref{148b,,assertIsNone()} and @ref{148c,,assertIsNotNone()} take one
expression and verify that the result is or is not @code{None}.

@item 
@ref{153c,,assertIs()} and @ref{153d,,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{153e,,assertIsInstance()} and
@ref{153f,,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{1540,,assertGreater()}, @ref{1541,,assertGreaterEqual()},
@ref{1542,,assertLess()}, and @ref{1543,,assertLessEqual()} compare
two quantities.

@item 
@ref{1544,,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{745,,assertEqual()}.

@item 
@ref{74a,,assertRegexpMatches()} and
@ref{74c,,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{74b,,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{1545,,assertIn()} and @ref{1546,,assertNotIn()}
tests whether `first' is or is not in  `second'.

@item 
@ref{142b,,assertItemsEqual()} tests whether two provided sequences
contain the same elements.

@item 
@ref{1486,,assertSetEqual()} compares whether two sets are equal, and
only reports the differences between the sets in case of error.

@item 
Similarly, @ref{1488,,assertListEqual()} and @ref{1489,,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{745,,assertEqual()}.
More generally, @ref{148a,,assertSequenceEqual()} compares two sequences
and can optionally check whether both sequences are of a
particular type.

@item 
@ref{1487,,assertDictEqual()} compares two dictionaries and reports the
differences; it's now used by default when you compare two dictionaries
using @ref{745,,assertEqual()}.  @code{assertDictContainsSubset()} checks whether
all of the key/value pairs in `first' are found in `second'.

@item 
@ref{747,,assertAlmostEqual()} and @ref{748,,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{1547,,loadTestsFromName()} properly honors the
@ref{1548,,suiteClass} attribute of
the @ref{58d,,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{745,,assertEqual()} method to handle
new data types.  The @ref{1549,,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{11de,,unittest.main()} now takes an optional @code{exit} argument.  If
false, @ref{11de,,main()} doesn't call @ref{277,,sys.exit()}, allowing
@ref{11de,,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{1368,,TestResult} has new @ref{154a,,startTestRun()} and
@ref{154b,,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 改進模組：ElementTree 1 3,,改進模組：unittest,New and Improved Modules
@anchor{whatsnew/2 7 elementtree-section}@anchor{154c}@anchor{whatsnew/2 7 updated-module-elementtree-1-3}@anchor{154d}
@subsubsection 改進模組：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{c40,,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{1478,,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{c83,,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{154e,,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{13d3,,register_namespace()}.  In XML mode,
you can use the true/false `xml_declaration' parameter to suppress the
XML declaration.

@item 
New @ref{361,,Element} method:
@ref{13d4,,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)

# 輸出 <root><item>1</item>...</root>
print ET.tostring(new)
@end example

@item 
New @ref{361,,Element} method:
@ref{154f,,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{361,,Element} method:
@ref{13d6,,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>""")

# 輸出 ['\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{651,,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 建置和 C API 變更<8>,Other Changes and Fixes,New and Improved Modules,Python 2 7 有什麼新功能
@anchor{whatsnew/2 7 build-and-c-api-changes}@anchor{1550}
@subsection 建置和 C API 變更


Python 建置程序和 C API 的變更包括：


@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{b6f,,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{1551,,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{1469,,PyErr_NewExceptionWithDoc()} creates a new
exception class, just as the existing @ref{146a,,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{986,,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{1467,,PyLong_AsLongAndOverflow()} and
@ref{1466,,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{1496,,PyOS_string_to_double()} function was added.  The old
@code{PyOS_ascii_strtod()} and @code{PyOS_ascii_atof()} functions
are now deprecated.

@item 
New function: @code{PySys_SetArgvEx()} sets the value of
@code{sys.argv} and can optionally update @code{sys.path} to include the
directory containing the script named by @code{sys.argv[0]} depending
on the value of an `updatepath' parameter.

This function was added to close a security hole for applications
that embed Python.  The old function, @code{PySys_SetArgv()}, would
always update @code{sys.path}, and sometimes it would add the current
directory.  This meant that, if you ran an application embedding
Python in a directory controlled by someone else, attackers could
put a Trojan-horse module in the directory (say, a file named
@code{os.py}) that your application would then import and run.

If you maintain a C/C++ application that embeds Python, check
whether you're calling @code{PySys_SetArgv()} and carefully consider
whether the application should be using @code{PySys_SetArgvEx()}
with `updatepath' set to false.

Security issue reported as 
@geindex Common Vulnerabilities and Exposures; CVE 2008-5983
CVE 2008-5983@footnote{https://www.cve.org/CVERecord?id=CVE-2008-5983};
discussed in bpo-5753@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5753}, and fixed by Antoine Pitrou.

@item 
New macros: the Python header files now define the following macros:
@code{Py_ISALNUM},
@code{Py_ISALPHA},
@code{Py_ISDIGIT},
@code{Py_ISLOWER},
@code{Py_ISSPACE},
@code{Py_ISUPPER},
@code{Py_ISXDIGIT},
@code{Py_TOLOWER}, and @code{Py_TOUPPER}.
All of these functions are analogous to the C
standard macros for classifying characters, but ignore the current
locale setting, because in
several places Python needs to analyze characters in a
locale-independent way.  (Added by Eric Smith;
bpo-5793@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5793}.)

@c XXX these macros don't seem to be described in the c-api docs.

@item 
Removed function: @code{PyEval_CallObject()} is now only available
as a macro.  A function version was being kept around to preserve
ABI linking compatibility, but that was in 1997; it can certainly be
deleted by now.  (Removed by Antoine Pitrou; bpo-8276@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8276}.)

@item 
New format codes: the @code{PyString_FromFormat()},
@code{PyString_FromFormatV()}, and @ref{10ac,,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{4b0,,os.fork()} might fail because the child is created with only a
single thread running, the thread performing the @ref{4b0,,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{4b0,,os.fork()}, and will also clean up any locks created using the
@ref{f3,,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{45d,,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{76a,,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{2e,,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{12c,,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,,建置和 C API 變更<8>
@anchor{whatsnew/2 7 capsules}@anchor{1552}@anchor{whatsnew/2 7 whatsnew27-capsules}@anchor{1553}
@subsubsection Capsules


Python 3.1 adds a new C datatype, @ref{1473,,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{d1,,socket} module's API is exposed as @code{socket.CAPI},
and @ref{10b,,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{1554,,PyCapsule_IsValid()} would
detect the mismatched name and return false.  Refer to
@ref{1555,,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{abd,,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,建置和 C API 變更<8>
@anchor{whatsnew/2 7 port-specific-changes-windows}@anchor{1556}
@subsubsection Port-Specific Changes: Windows



@itemize *

@item 
The @ref{97,,msvcrt} module now contains some constants from
the @code{crtassem.h} header file:
@ref{1557,,CRT_ASSEMBLY_VERSION},
@ref{1558,,VC_ASSEMBLY_PUBLICKEYTOKEN},
and @ref{1559,,LIBRARIES_ASSEMBLY_NAME_PREFIX}.
(Contributed by David Cournapeau; bpo-4365@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4365}.)

@item 
The @ref{11c,,_winreg} module for accessing the registry now implements
the @ref{155a,,CreateKeyEx()} and @ref{155b,,DeleteKeyEx()}
functions, extended versions of previously supported functions that
take several extra arguments.  The @ref{155c,,DisableReflectionKey()},
@ref{155d,,EnableReflectionKey()}, and @ref{155e,,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{155f,,os.kill()} function now works on Windows.  The signal value
can be the constants @ref{1560,,CTRL_C_EVENT},
@ref{1561,,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{12fb,,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,建置和 C API 變更<8>
@anchor{whatsnew/2 7 port-specific-changes-mac-os-x}@anchor{1562}
@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,建置和 C API 變更<8>
@anchor{whatsnew/2 7 port-specific-changes-freebsd}@anchor{1563}
@subsubsection Port-Specific Changes: FreeBSD



@itemize *

@item 
FreeBSD 7.1's @code{SO_SETFIB} constant, used with the @ref{f9c,,socket()} methods
@ref{ecb,,getsockopt()}/@ref{ecc,,setsockopt()} to select an
alternate routing table, is now available in the @ref{d1,,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,移植至 Python 2 7,建置和 C API 變更<8>,Python 2 7 有什麼新功能
@anchor{whatsnew/2 7 other-changes-and-fixes}@anchor{1564}
@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{315,,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{1565,,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 移植至 Python 2 7,New Features Added to Python 2 7 Maintenance Releases,Other Changes and Fixes,Python 2 7 有什麼新功能
@anchor{whatsnew/2 7 porting-to-python-2-7}@anchor{1566}
@subsection 移植至 Python 2.7


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


@itemize *

@item 
The @ref{b34,,range()} function processes its arguments more
consistently; it will now call @ref{19d,,__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{199,,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{169,,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{186,,with} statement, the special
methods @ref{7dd,,__enter__()} and @ref{1501,,__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{c75,,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{1501,,__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{5e8,,AttributeError}
as you would expect.  Fixed by Benjamin Peterson; bpo-7604@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7604}.)
@end itemize

標準函式庫中：


@itemize *

@item 
Operations with @ref{4dd,,datetime} instances that resulted in a year
falling outside the supported range didn't always raise
@ref{a78,,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{1fe,,Decimal} instances with a string's
@ref{199,,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{12a9,,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{12b,,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{1124,,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{e2,,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{e4,,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{110,,urlparse} module's @ref{f35,,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{198,,TypeError} exception
instead of triggering a @ref{1a3,,DeprecationWarning} (bpo-5080@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5080}).

@item 
Use the new @ref{1496,,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,致謝,移植至 Python 2 7,Python 2 7 有什麼新功能
@anchor{whatsnew/2 7 new-features-added-to-python-2-7-maintenance-releases}@anchor{1567}@anchor{whatsnew/2 7 py27-maintenance-enhancements}@anchor{14e7}
@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
* 偵錯模式下的兩個新環境變數:: 
* 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. 
* 新增 make regen-all 建置目標: 新增 make regen-all 建置目標<3>. 
* 移除 make touch 建置目標: 移除 make touch 建置目標<3>. 

@end menu

@node 偵錯模式下的兩個新環境變數,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{1568}
@subsubsection 偵錯模式下的兩個新環境變數


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


在 2.7.15 版被加入.


@node PEP 434 IDLE Enhancement Exception for All Branches,PEP 466 Network Security Enhancements for Python 2 7,偵錯模式下的兩個新環境變數,New Features Added to Python 2 7 Maintenance Releases
@anchor{whatsnew/2 7 pep-434-idle-enhancement-exception-for-all-branches}@anchor{1569}
@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{156a}
@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.

Python 2.7.7 中新增的 
@geindex Python Enhancement Proposals; PEP 466
PEP 466@footnote{https://peps.python.org/pep-0466/} 相關功能：


@itemize *

@item 
@ref{12ca,,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

Python 2.7.8 中新增的 
@geindex Python Enhancement Proposals; PEP 466
PEP 466@footnote{https://peps.python.org/pep-0466/} 相關功能：


@itemize *

@item 
@ref{72c,,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

Python 2.7.9 中新增的 
@geindex Python Enhancement Proposals; PEP 466
PEP 466@footnote{https://peps.python.org/pep-0466/} 相關功能：


@itemize *

@item 
Most of Python 3.4's @ref{d5,,ssl} module was backported. This means @ref{d5,,ssl}
now supports Server Name Indication, TLS1.x settings, access to the platform
certificate store, the @ref{355,,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{73f,,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{156b,,hashlib.algorithms_guaranteed} and
@ref{156c,,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{156d}
@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>. 
* 文件更動: 文件更動<2>. 

@end menu

@node Bootstrapping pip By Default<2>,文件更動<2>,,PEP 477 Backport ensurepip PEP 453 to Python 2 7
@anchor{whatsnew/2 7 bootstrapping-pip-by-default}@anchor{156e}
@subsubsection Bootstrapping pip By Default


The new @ref{59,,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{10f1,,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 文件更動<2>,,Bootstrapping pip By Default<2>,PEP 477 Backport ensurepip PEP 453 to Python 2 7
@anchor{whatsnew/2 7 documentation-changes}@anchor{156f}
@subsubsection 文件更動


As part of this change, the @ref{10f3,,安裝 Python 模組} and
distributing-index sections of the documentation have been
completely redesigned as short getting started and FAQ documents. Most
packaging documentation has now been moved out to the Python Packaging
Authority maintained Python Packaging User Guide@footnote{https://packaging.python.org} and the documentation of the individual
projects.

However, as this migration is currently still incomplete, the legacy
versions of those guides remaining available as @ref{10f4,,用 setuptools 建置 C 與 C++ 擴充套件}
and @ref{10f5,,用 setuptools 建置 C 與 C++ 擴充套件}.


@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{1570}
@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{72,,httplib} and modules which use it, such as
@ref{111,,urllib2} and @ref{134,,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,新增 make regen-all 建置目標<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{1571}
@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 新增 make regen-all 建置目標<3>,移除 make touch 建置目標<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{1572}
@subsubsection 新增 @code{make regen-all} 建置目標


To simplify cross-compilation, and to ensure that CPython can reliably be
compiled without requiring an existing version of Python to already be
available, the autotools-based build system no longer attempts to implicitly
recompile generated files based on file modification times.

Instead, a new @code{make regen-all} command has been added to force regeneration
of these files when desired (e.g. after an initial version of Python has
already been built based on the pregenerated versions).

More selective regeneration targets are also defined - see
Makefile.pre.in@footnote{https://github.com/python/cpython/tree/3.14/Makefile.pre.in} for details.

（由 Victor Stinner 於 bpo-23404@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23404} 中貢獻。）


在 2.7.14 版被加入.


@node 移除 make touch 建置目標<3>,,新增 make regen-all 建置目標<3>,New Features Added to Python 2 7 Maintenance Releases
@anchor{whatsnew/2 7 removal-of-make-touch-build-target}@anchor{1573}
@subsubsection 移除 @code{make touch} 建置目標


The @code{make touch} build target previously used to request implicit regeneration
of generated files by updating their modification times has been removed.

已被新的 @code{make regen-all} 目標取代。

（由 Victor Stinner 於 bpo-23404@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23404} 中貢獻。）


在 2.7.14 版的變更.


@c ======================================================================

@node 致謝,,New Features Added to Python 2 7 Maintenance Releases,Python 2 7 有什麼新功能
@anchor{whatsnew/2 7 acknowledgements}@anchor{1574}@anchor{whatsnew/2 7 acks27}@anchor{1575}
@subsection 致謝


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 Python 2 6 有什麼新功能,Python 2 5 有什麼新功能,Python 2 7 有什麼新功能,Python 有什麼新功能？
@anchor{whatsnew/2 6 doc}@anchor{1576}@anchor{whatsnew/2 6 translation-repo}@anchor{1577}@anchor{whatsnew/2 6 what-s-new-in-python-2-6}@anchor{1578}@anchor{whatsnew/2 6 whats-new-in-2-6}@anchor{14ae}
@section Python 2.6 有什麼新功能


@*作者: 
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.

本文介紹了已於 2008 年 10 月 1 日發布的 Python 2.6 有哪些新功能。發布時間表請見 
@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{86,,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：'with' 陳述式:: 
* 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：新 I/O 函式庫:: 
* PEP 3118：修訂緩衝協定:: 
* 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. 
* 其他語言更動: 其他語言更動<15>. 
* New and Improved Modules: New and Improved Modules<2>. 
* Deprecations and Removals:: 
* 建置和 C API 變更: 建置和 C API 變更<9>. 
* Porting to Python 2.6: Porting to Python 2 6. 
* 致謝: 致謝<2>. 

@end menu

@node Python 3 0,Changes to the Development Process,,Python 2 6 有什麼新功能
@anchor{whatsnew/2 6 python-3-0}@anchor{1579}
@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{21a,,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{14a9,,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：'with' 陳述式,Python 3 0,Python 2 6 有什麼新功能
@anchor{whatsnew/2 6 changes-to-the-development-process}@anchor{157a}
@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. 
* 新文件格式：使用 Sphinx 的 reStructuredText:: 

@end menu

@node New Issue Tracker Roundup,新文件格式：使用 Sphinx 的 reStructuredText,,Changes to the Development Process
@anchor{whatsnew/2 6 new-issue-tracker-roundup}@anchor{157b}
@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}

Python 問題追蹤系統。

@item @indicateurl{https://bugs.jython.org}:

Jython 問題追蹤系統。

@item @indicateurl{https://roundup.sourceforge.io/}

Roundup downloads and documentation.

@item @indicateurl{https://svn.python.org/view/tracker/importer/}

Martin von Löwis 的轉換腳本。
@end table


@node 新文件格式：使用 Sphinx 的 reStructuredText,,New Issue Tracker Roundup,Changes to the Development Process
@anchor{whatsnew/2 6 new-documentation-format-restructuredtext-using-sphinx}@anchor{157c}
@subsubsection 新文件格式：使用 Sphinx 的 reStructuredText


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 Python 文件撰寫@footnote{https://devguide.python.org/documenting/}

說明如何為 Python 撰寫文件。

@item Sphinx@footnote{https://www.sphinx-doc.org/}

Sphinx 工具鏈的文件和程式碼。

@item Docutils@footnote{https://docutils.sourceforge.io}

底層 reStructuredText 剖析器和工具集。
@end table


@node PEP 343：'with' 陳述式,PEP 366 Explicit Relative Imports From a Main Module,Changes to the Development Process,Python 2 6 有什麼新功能
@anchor{whatsnew/2 6 pep-0343}@anchor{14af}@anchor{whatsnew/2 6 pep-343-the-with-statement}@anchor{157d}
@subsection PEP 343：'with' 陳述式


The previous version, Python 2.5, added the '@ref{186,,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{186,,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{186,,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{7dd,,__enter__()} and @ref{1501,,__exit__()}
methods).

The object's @ref{7dd,,__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{1501,,__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{186,,with}' statement. File objects are one example:

@example
with open('/etc/passwd', 'r') as f:
    for line in f:
        print line
        ... 更多處理程式碼 ...
@end example

After this statement has executed, the file object in `f' will have been
automatically closed, even if the @ref{348,,for} loop raised an exception
part-way through the block.

@cartouche
@quotation 備註 
In this case, `f' is the same object created by @ref{315,,open()}, because
@ref{7dd,,__enter__()} returns `self'.
@end quotation
@end cartouche

The @ref{f3,,threading} module's locks and condition variables  also support the
'@ref{186,,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{157e,,localcontext()} function in the @ref{3a,,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:: 
* contextlib 模組:: 

@end menu

@node Writing Context Managers,contextlib 模組,,PEP 343：'with' 陳述式
@anchor{whatsnew/2 6 new-26-context-managers}@anchor{14b0}@anchor{whatsnew/2 6 writing-context-managers}@anchor{157f}
@subsubsection Writing Context Managers


Under the hood, the '@ref{186,,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{7dd,,__enter__()} and
@ref{1501,,__exit__()} methods.

@item 
The context manager's @ref{7dd,,__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 
`BLOCK' 中的程式碼會被執行。

@item 
If `BLOCK' raises an exception, the context manager's @ref{1501,,__exit__()} method
is called with three arguments, the exception details (@code{type, value, traceback},
the same values returned by @ref{893,,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{186,,with}' statement will
never realize anything went wrong.

@item 
If `BLOCK' didn't raise an exception,  the @ref{1501,,__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 ...')
    # ... 更多操作 ...
@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{7dd,,__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{186,,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{1501,,__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{1af,,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 contextlib 模組,,Writing Context Managers,PEP 343：'with' 陳述式
@anchor{whatsnew/2 6 new-module-contextlib}@anchor{14b1}@anchor{whatsnew/2 6 the-contextlib-module}@anchor{1580}
@subsubsection contextlib 模組


The @ref{27,,contextlib} module provides some functions and a decorator that
are useful when writing objects for use with the '@ref{186,,with}' statement.

The decorator is called @ref{1403,,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{bb9,,yield} will be
executed as the @ref{7dd,,__enter__()} method, and the value yielded will
be the method's return value that will get bound to the variable in the
'@ref{186,,with}' statement's @code{as} clause, if any.  The code after
the @code{yield} will be executed in the @ref{1501,,__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{186,,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{1581,,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/} - "with" 陳述式

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{186,,with}' statement, which can be helpful in learning how the statement
works.
@end table

@ref{27,,contextlib} 模組的文件。


@c ======================================================================

@node PEP 366 Explicit Relative Imports From a Main Module,PEP 370 Per-user site-packages Directory,PEP 343：'with' 陳述式,Python 2 6 有什麼新功能
@anchor{whatsnew/2 6 pep-0366}@anchor{14b2}@anchor{whatsnew/2 6 pep-366-explicit-relative-imports-from-a-main-module}@anchor{1582}
@subsection PEP 366: Explicit Relative Imports From a Main Module


Python's @ref{23c,,-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{322,,module.__package__} attribute.
When this attribute is present, relative imports will be
relative to the value of this attribute instead of the
@ref{1583,,__name__} attribute.

PEP 302-style importers can then set @ref{322,,__package__} as necessary.
The @ref{c3,,runpy} module that implements the @ref{23c,,-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,Python 2 6 有什麼新功能
@anchor{whatsnew/2 6 pep-0370}@anchor{14b3}@anchor{whatsnew/2 6 pep-370-per-user-site-packages-directory}@anchor{1584}
@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 和 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{1585,,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{1586,,-s} option or setting the 
@geindex PYTHONNOUSERSITE
@geindex 環境變數; PYTHONNOUSERSITE
@ref{1587,,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

由 Christian Heimes 撰寫 PEP 與實作。
@end table


@c ======================================================================

@node PEP 371 The multiprocessing Package,PEP 3101 Advanced String Formatting,PEP 370 Per-user site-packages Directory,Python 2 6 有什麼新功能
@anchor{whatsnew/2 6 pep-0371}@anchor{14b4}@anchor{whatsnew/2 6 pep-371-the-multiprocessing-package}@anchor{1588}
@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{f3,,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{252,,Process}, which is passed a callable object and
a collection of arguments.  The @ref{1589,,start()} method
sets the callable running in a subprocess, after which you can call
the @ref{158a,,is_alive()} method to check whether the
subprocess is still running and the @ref{158b,,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):
    "計算階乘。"
    # 如果 N 是 4 的倍數，則此函式將花費更多時間。
    if (N % 4) == 0:
        time.sleep(.05 * N/4)

    # 計算結果
    fact = 1L
    for i in range(1, N+1):
        fact = fact * i

    # 將結果放進佇列裡
    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{158c,,Queue} is used to communicate the result of the factorial.
The @ref{158c,,Queue} object is stored in a global variable.
The child process will use the value of the variable when the child
was created; because it's a @ref{158c,,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{1166,,Pool} and
@ref{250,,Manager}, provide higher-level interfaces.
@ref{1166,,Pool} will create a fixed number of worker
processes, and requests can then be distributed to the workers by calling
@ref{158d,,apply()} or
@ref{158e,,apply_async()} to add a single request, and
@ref{12e6,,map()} or
@ref{12e7,,map_async()} to add a number of
requests.  The following code uses a @ref{1166,,Pool} to
spread requests across 5 worker processes and retrieve a list of results:

@example
from multiprocessing import Pool

def factorial(N, dictionary):
    "計算階乘。"
    ...
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{250,,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{183,,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.
@ref{250,,Manager}'s methods also include
@ref{158f,,Lock()},
@ref{1590,,RLock()},
and @ref{1591,,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 也參考


@ref{98,,multiprocessing} 模組的文件。


@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,Python 2 6 有什麼新功能
@anchor{whatsnew/2 6 pep-3101}@anchor{14b5}@anchor{whatsnew/2 6 pep-3101-advanced-string-formatting}@anchor{1592}
@subsection PEP 3101: Advanced String Formatting


In Python 3.0, the @code{%} operator is supplemented by a more powerful string
formatting method, @ref{199,,format()}.  Support for the @ref{82c,,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

字元

@tab

效果

@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{1593,,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{82a,,__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{199,,format()} builtin that will format a single
value.  It calls the type's @ref{82a,,__format__()} method with the
provided specifier:

@example
>>> format(75.6564, '.2f')
'75.66'
@end example


@subsubheading 也參考



@table @asis

@item @ref{1593,,格式化文字語法}

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

由 Talin 撰寫 PEP、由 Eric Smith 實作。
@end table


@c ======================================================================

@node PEP 3105 print As a Function,PEP 3110 Exception-Handling Changes,PEP 3101 Advanced String Formatting,Python 2 6 有什麼新功能
@anchor{whatsnew/2 6 pep-3105}@anchor{14b6}@anchor{whatsnew/2 6 pep-3105-print-as-a-function}@anchor{1594}
@subsection PEP 3105: @code{print} As a Function


The @code{print} statement becomes the @ref{1170,,print()} function in Python 3.0.
Making @ref{1170,,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/} - 將 print 變成函式

由 Georg Brandl 撰寫 PEP。
@end table


@c ======================================================================

@node PEP 3110 Exception-Handling Changes,PEP 3112 Byte Literals,PEP 3105 print As a Function,Python 2 6 有什麼新功能
@anchor{whatsnew/2 6 pep-3110}@anchor{14b7}@anchor{whatsnew/2 6 pep-3110-exception-handling-changes}@anchor{1595}
@subsection PEP 3110: Exception-Handling Changes


One error that Python programmers occasionally make
is writing the following code:

@example
try:
    ...
except TypeError, ValueError:  # 錯誤！
    ...
@end example

The author is probably trying to catch both @ref{198,,TypeError} and
@ref{2eb,,ValueError} exceptions, but this code actually does something
different: it will catch @ref{198,,TypeError} and bind the resulting
exception object to the local name @code{"ValueError"}.  The
@ref{2eb,,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

由 Collin Winter 撰寫 PEP 與實作。
@end table


@c ======================================================================

@node PEP 3112 Byte Literals,PEP 3116：新 I/O 函式庫,PEP 3110 Exception-Handling Changes,Python 2 6 有什麼新功能
@anchor{whatsnew/2 6 pep-3112}@anchor{14b8}@anchor{whatsnew/2 6 pep-3112-byte-literals}@anchor{1596}
@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{192,,bytes} constructor.  For future compatibility,
Python 2.6 adds @ref{192,,bytes} as a synonym for the @ref{169,,str} type,
and it also supports the @code{b'@w{'}} notation.

The 2.6 @ref{169,,str} differs from 3.0's @ref{192,,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{169,,str()} of the list.

The primary use of @ref{192,,bytes} in 2.6 will be to write tests of
object type such as @code{isinstance(x, bytes)}.  This will help the 2to3
converter, which can't tell whether 2.x code intends strings to
contain either characters or 8-bit bytes; you can now
use either @ref{192,,bytes} or @ref{169,,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 字元
@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{98d,,PyBytesObject}.  Python 2.6 uses @code{#define}
to support using the names @ref{98d,,PyBytesObject()},
@ref{1597,,PyBytes_Check()}, @ref{1598,,PyBytes_FromStringAndSize()},
and all the other functions and macros used with strings.

Instances of the @ref{192,,bytes} type are immutable just
as strings are.  A new @ref{343,,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{1599,,startswith()}/@ref{159a,,endswith()},
@ref{159b,,find()}/@ref{159c,,rfind()},
and some of the methods of lists, such as @ref{159d,,append()},
@ref{159e,,pop()},  and @ref{159f,,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{15a0,,PyByteArray_FromObject()},
@ref{15a1,,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：新 I/O 函式庫,PEP 3118：修訂緩衝協定,PEP 3112 Byte Literals,Python 2 6 有什麼新功能
@anchor{whatsnew/2 6 pep-3116}@anchor{14b9}@anchor{whatsnew/2 6 pep-3116-new-i-o-library}@anchor{15a2}
@subsection PEP 3116：新 I/O 函式庫


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{83,,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{83,,io} module:


@itemize *

@item 
@ref{12d1,,RawIOBase} defines raw I/O operations: @ref{1018,,read()},
@ref{1019,,readinto()}, @ref{15a3,,write()},
@ref{148d,,seek()}, @ref{15a4,,tell()}, @ref{1511,,truncate()},
and @ref{501,,close()}.
Most of the methods of this class will often map to a single system call.
There are also @ref{15a5,,readable()}, @ref{15a6,,writable()},
and @ref{15a7,,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{89c,,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{12d1,,RawIOBase},
and adds a @ref{15a8,,raw} attribute holding the underlying
raw object.

There are five concrete classes implementing this ABC.
@ref{15a9,,BufferedWriter} and @ref{140f,,BufferedReader} are for objects
that support write-only or read-only usage that have a @ref{148d,,seek()}
method for random access.  @ref{15aa,,BufferedRandom} objects support
read and write access upon the same underlying stream, and
@ref{15ab,,BufferedRWPair} is for objects such as TTYs that have both
read and write operations acting upon unconnected streams of data.
The @ref{109f,,BytesIO} class supports reading, writing, and seeking
over an in-memory buffer.

@geindex universal newlines;What's new（有什麼新功能）

@item 
@ref{89d,,TextIOBase}: Provides functions for reading and writing
strings (remember, strings will be Unicode in Python 3.0),
and supporting @ref{f30,,universal newlines}.  @ref{89d,,TextIOBase} defines
the @ref{bf,,readline()} method and supports iteration upon
objects.

There are two concrete implementations.  @ref{9b7,,TextIOWrapper}
wraps a buffered I/O object, supporting all of the methods for
text I/O and adding a @ref{14a4,,buffer} attribute for access
to the underlying object.  @ref{1124,,StringIO} simply buffers
everything in memory without ever writing anything to disk.

(In Python 2.6, @ref{1124,,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{83,,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{83,,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：修訂緩衝協定,PEP 3119 Abstract Base Classes,PEP 3116：新 I/O 函式庫,Python 2 6 有什麼新功能
@anchor{whatsnew/2 6 pep-3118}@anchor{14ba}@anchor{whatsnew/2 6 pep-3118-revised-buffer-protocol}@anchor{15ac}
@subsection PEP 3118：修訂緩衝協定


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{be,,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{632,,PyObject_GetBuffer()} specifies
constraints upon the memory returned.  Some examples are:


@itemize *

@item 
@ref{15ad,,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{15ae,,PyBUF_C_CONTIGUOUS} and @ref{15af,,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{3bf,,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：修訂緩衝協定,Python 2 6 有什麼新功能
@anchor{whatsnew/2 6 pep-3119}@anchor{14bb}@anchor{whatsnew/2 6 pep-3119-abstract-base-classes}@anchor{15b0}
@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{1116,,ABCMeta}, special handling of
this metaclass by the @ref{2ad,,isinstance()} and @ref{9bd,,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{e64,,__iter__()}, and
@code{Container} means the class defines a @ref{15b1,,__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{1289,,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{1289,,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
# 註冊 Python 的型別
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{1286,,@@~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,Python 2 6 有什麼新功能
@anchor{whatsnew/2 6 pep-3127}@anchor{14bc}@anchor{whatsnew/2 6 pep-3127-integer-literal-support-and-syntax}@anchor{15b2}
@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{14cf,,oct()} builtin still returns numbers
prefixed with a leading zero, and a new @ref{14a9,,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{19b,,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,Python 2 6 有什麼新功能
@anchor{whatsnew/2 6 pep-3129}@anchor{14bd}@anchor{whatsnew/2 6 pep-3129-class-decorators}@anchor{15b3}
@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

這等價於：

@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/} - 類別裝飾器

由 Collin Winter 撰寫 PEP。
@end table


@c ======================================================================

@node PEP 3141 A Type Hierarchy for Numbers,其他語言更動<15>,PEP 3129 Class Decorators,Python 2 6 有什麼新功能
@anchor{whatsnew/2 6 pep-3141}@anchor{14be}@anchor{whatsnew/2 6 pep-3141-a-type-hierarchy-for-numbers}@anchor{15b4}
@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{61,,fractions} module.  (It's called
@code{Fraction} instead of @code{Rational} to avoid
a name clash with @ref{14bf,,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{14db,,round()}, @ref{15b5,,math.floor()}, @ref{15b6,,math.ceil()}, and adds a new
one, @ref{15b7,,math.trunc()}, that's been backported to Python 2.6.
@ref{15b7,,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

由 Jeffrey Yasskin 撰寫 PEP。
@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{15b8}
@subsubsection The @code{fractions} Module


To fill out the hierarchy of numeric types, the @ref{61,,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{61,,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 其他語言更動<15>,New and Improved Modules<2>,PEP 3141 A Type Hierarchy for Numbers,Python 2 6 有什麼新功能
@anchor{whatsnew/2 6 other-language-changes}@anchor{15b9}
@subsection 其他語言更動


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{6f2,,hasattr()} function was catching and ignoring all errors,
under the assumption that they meant a @code{__getattr__()} method
was failing somehow and the return value of @ref{6f2,,hasattr()} would
therefore be @code{False}.  This logic shouldn't be applied to
@ref{bbc,,KeyboardInterrupt} and @ref{f37,,SystemExit}, however; Python 2.6
will no longer discard such exceptions when @ref{6f2,,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

（由 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{df0,,StopIteration} exception will be raised.  (Backported
in bpo-2719@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2719}.)

@item 
Tuples now have @ref{15ba,,index()} and @ref{15bb,,count()} methods
matching the list type's @ref{15bc,,index()} and @ref{15bd,,count()} methods:

@example
>>> t = (0,1,2,3,4,0,1,2)
>>> t.index(3)
3
>>> t.count(0)
2
@end example

（由 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')  # 所有輸入的交集
set(['2'])
>>> s.difference('246', '789')
set(['1', '0', '3', '5'])
@end example

（由 Raymond Hettinger 所貢獻。）

@item 
Many floating-point features were added.  The @ref{196,,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{92,,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{14d0,,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{197,,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{198,,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{15be,,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{15bf,,GeneratorExit} exception now subclasses
@ref{7d0,,BaseException} instead of @ref{bc4,,Exception}.  This means
that an exception handler that does @code{except Exception:}
will not inadvertently catch @ref{15bf,,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{4ac,,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{197,,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{83d,,dir()} function now checks for a @code{__dir__()}
method on the objects it receives.  This method must return a list
of strings containing the names of valid attributes for the object,
and lets the object control the value that @ref{83d,,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{15c0,,__self__}, and @code{im_func} is also available as
@ref{14fd,,__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{469,,locals()} function inside a
@ref{14d8,,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
* 最佳化: 最佳化<15>. 
* Interpreter Changes: Interpreter Changes<2>. 

@end menu

@node 最佳化<15>,Interpreter Changes<2>,,其他語言更動<15>
@anchor{whatsnew/2 6 optimizations}@anchor{15c1}
@subsubsection 最佳化



@itemize *

@item 
The @ref{118,,warnings} module has been rewritten in C.  This makes
it possible to invoke warnings from the parser, and may also
make the interpreter's startup faster.
(Contributed by Neal Norwitz and Brett Cannon; bpo-1631171@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1631171}.)

@item 
Type objects now have a cache of methods that can reduce
the work required to find the correct method implementation
for a particular class; once cached, the interpreter doesn't need to
traverse base classes to figure out the right method to call.
The cache is cleared if a base class or the class itself is modified,
so the cache should remain correct even in the face of Python's dynamic
nature.
(Original optimization implemented by Armin Rigo, updated for
Python 2.6 by Kevin Jacobs; bpo-1700288@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1700288}.)

By default, this change is only applied to types that are included with
the Python core.  Extension modules may not necessarily be compatible with
this cache,
so they must explicitly add @code{Py_TPFLAGS_HAVE_VERSION_TAG}
to the module's @code{tp_flags} field to enable the method cache.
(To be compatible with the method cache, the extension module's code
must not directly access and modify the @code{tp_dict} member of
any of the types it implements.  Most modules don't do this,
but it's impossible for the Python interpreter to determine that.
See bpo-1878@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1878} for some discussion.)

@item 
Function calls that use keyword arguments are significantly faster
by doing a quick pointer comparison, usually saving the time of a
full string comparison.  (Contributed by Raymond Hettinger, after an
initial implementation by Antoine Pitrou; bpo-1819@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1819}.)

@item 
All of the functions in the @ref{db,,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{1501,,__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>,,最佳化<15>,其他語言更動<15>
@anchor{whatsnew/2 6 interpreter-changes}@anchor{15c2}@anchor{whatsnew/2 6 new-26-interpreter}@anchor{15c3}
@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{16f,,-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{15c4,,-B} switch to the Python interpreter,
or by setting the 
@geindex PYTHONDONTWRITEBYTECODE
@geindex 環境變數; PYTHONDONTWRITEBYTECODE
@ref{15c5,,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{1205,,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,其他語言更動<15>,Python 2 6 有什麼新功能
@anchor{whatsnew/2 6 new-and-improved-modules}@anchor{15c6}
@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{110,,urlparse} module.
The versions still available in the @code{cgi} module will
trigger @ref{abd,,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.

（由 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

（由 Raymond Hettinger 所貢獻。）

@item 
The @ref{75,,Cookie} module's @ref{df9,,Morsel} objects now support an
@ref{15c7,,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{2f,,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{32,,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{34,,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{3a,,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{3b,,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{aed,,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{63,,functools} module.  In Python 3.0, the builtin has been
dropped and @code{reduce()} is only available from @ref{63,,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{66,,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{59a,,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{6d,,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{6d,,heapq} is now implemented to only use less-than comparison,
instead of the less-than-or-equal comparison it previously used.
This makes @ref{6d,,heapq}'s usage of a type match the
@ref{dc3,,list.sort()} method.
(Contributed by Raymond Hettinger.)

@item 
An optional @code{timeout} parameter, specifying a timeout measured in
seconds, was added to the @ref{d2d,,httplib.HTTPConnection} and
@ref{d2e,,HTTPSConnection} class constructors.  (Added by Facundo
Batista.)

@item 
Most of the @ref{82,,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{85,,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{85,,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

（均由 Raymond Hettinger 所貢獻。）

@item 
The @ref{8b,,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{92,,math} module:


@itemize *

@item 
@ref{15c8,,isinf()} and @ref{15c9,,isnan()} determine whether a given float
is a (positive or negative) infinity or a NaN (Not a Number), respectively.

@item 
@ref{15ca,,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{b38,,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{15cb,,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{15cc,,acosh()}, @ref{15cd,,asinh()}
and @ref{15ce,,atanh()} compute the inverse hyperbolic functions.

@item 
@ref{15cf,,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{14be,,PEP 3141's type hierarchy for numbers}.
@end itemize

@item 
The @ref{92,,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{2eb,,ValueError} across almost all platforms,
while @code{sqrt(float('NaN'))} should return a NaN on all IEEE 754
platforms.  Where Annex 'F' of the C99 standard recommends signaling
'divide-by-zero' or 'invalid', Python will raise @ref{2eb,,ValueError}.
Where Annex 'F' of the C99 standard recommends signaling 'overflow',
Python will raise @ref{a78,,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}.)

（由 Christian Heimes 和 Mark Dickinson 所貢獻。）

@item 
@ref{514,,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
>>> # 等價於 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

（經 Gregory Petrosyan 建議後由 Georg Brandl 所貢獻。）

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

（經 Barry Warsaw 建議後由 Georg Brandl 所貢獻。）

@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{d6,,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{dc,,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{25c,,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{6c9,,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{15d0,,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{15d1,,pdb.post_mortem()} function, used to begin debugging a
traceback, will now use the traceback returned by @ref{893,,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

（由 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{bd,,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{be,,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{c2,,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{c4,,sched} module's @code{scheduler} instances now
have a read-only @ref{bb,,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{c6,,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{c15,,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{ca,,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

（由 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{cb,,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{15d2,,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.

（由 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{cf,,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{d1,,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{d2,,SocketServer} module now support
calling a @ref{1522,,handle_timeout()} method after a span of inactivity
specified by the server's @ref{1521,,timeout} attribute.  (Contributed
by Michael Pomraning.)  The @ref{1340,,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{d4,,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{db,,struct} module now supports the C99 _Bool type,
using the format character @code{'?'}.
(Contributed by David Remahl.)

@item 
The @ref{4b2,,Popen} objects provided by the @ref{dc,,subprocess} module
now have @ref{15d3,,terminate()}, @ref{15d4,,kill()}, and @ref{15d5,,send_signal()} methods.
On Windows, @code{send_signal()} only supports the @ref{15d6,,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{df,,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{15c4,,-B}
switch to the Python interpreter, or by setting the
@geindex PYTHONDONTWRITEBYTECODE
@geindex 環境變數; PYTHONDONTWRITEBYTECODE
@ref{15c5,,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{15d7,,sys.getprofile()} and @ref{15d8,,sys.gettrace()}.
(Contributed by Georg Brandl; bpo-1648@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1648}.)

@item 
The @ref{e4,,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.

（所有更改均由 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{6e6,,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{ea,,test.test_support} module gained a number
of context managers useful for writing tests.
@ref{15d9,,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")
    # ... 觸發警告的程式碼 ...
    assert str(wrec.message) == "function is outdated"
    assert len(wrec.warnings) == 1, "Multiple warnings raised"
@end example

（由 Brett Cannon 貢獻。）

@item 
The @ref{f2,,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

（由 Dwayne Bailey 貢獻；bpo-1581073@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1581073}。）

@item 
The @ref{f3,,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{f3,,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{f5,,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{107,,turtle} module for turtle graphics was greatly enhanced by
Gregor Lingl.  New features in the module include:


@itemize *

@item 
更好的海龜移動和旋轉動畫。

@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{306,,urllib.urlopen} function and the
@code{urllib.ftpwrapper} class constructor, as well as the
@ref{306,,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

（由 Facundo Batista 新增。）

@item 
The Unicode database provided by the @ref{10b,,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{118,,warnings} module's @code{formatwarning()} and @code{showwarning()}
gained an optional `line' argument that can be used to supply the
line of source code.  (Added as part of bpo-1631171@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1631171}, which re-implemented
part of the @ref{118,,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{135,,SimpleXMLRPCServer} and @ref{135,,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{134,,xmlrpclib} module no longer automatically converts
@ref{1fa,,datetime.date} and @ref{1fb,,datetime.time} to the
@ref{15da,,xmlrpclib.DateTime} type; the conversion semantics were
not necessarily correct for all applications.  Code using
@code{xmlrpclib} should convert @code{date} and @ref{1fb,,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{137,,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

（由 Alan McIntyre 貢獻；bpo-467924@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=467924}。）

The @ref{315,,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{137,,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
* ast 模組:: 
* future_builtins 模組:: 
* 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 ast 模組,future_builtins 模組,,New and Improved Modules<2>
@anchor{whatsnew/2 6 the-ast-module}@anchor{15db}
@subsubsection @code{ast} 模組


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{49e,,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 future_builtins 模組,The json module JavaScript Object Notation,ast 模組,New and Improved Modules<2>
@anchor{whatsnew/2 6 the-future-builtins-module}@anchor{15dc}
@subsubsection @code{future_builtins} 模組


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.

此模組中的函式目前包括：


@itemize *

@item 
@code{ascii(obj)}: equivalent to @ref{1c1,,repr()}.  In Python 3.0,
@ref{1c1,,repr()} will return a Unicode string, while @ref{15dd,,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{14cf,,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,future_builtins 模組,New and Improved Modules<2>
@anchor{whatsnew/2 6 the-json-module-javascript-object-notation}@anchor{15de}
@subsubsection The @code{json} module: JavaScript Object Notation


The new @ref{86,,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{86,,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) # 為資料編碼
>>> in_json
'@{"parrot": 42, "spam": "foo"@}'
>>> json.loads(in_json) # 解碼為 Python 物件
@{"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{86,,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{15df}
@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

# Create data structure
data_struct = dict(lastAccessed=datetime.datetime.now(),
                   version=1,
                   categories=('Personal','Shared','Private'))

# Create string containing XML.
plist_str = plistlib.writePlistToString(data_struct)
new_struct = plistlib.readPlistFromString(plist_str)
print data_struct
print new_struct

# Write data structure to a file and read it back.
plistlib.writePlist(data_struct, '/tmp/customizations.plist')
new_struct = plistlib.readPlist('/tmp/customizations.plist')

# read/writePlist accepts file-like objects as well as paths.
plistlib.writePlist(data_struct, sys.stdout)
@end example

@c ======================================================================

@node ctypes Enhancements,Improved SSL Support,The plistlib module A Property-List Parser,New and Improved Modules<2>
@anchor{whatsnew/2 6 ctypes-enhancements}@anchor{15e0}
@subsubsection ctypes Enhancements


Thomas Heller continued to maintain and enhance the
@ref{2e,,ctypes} module.

@ref{2e,,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{2e,,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{2e,,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{2e,,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{15e1}
@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{d5,,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{d1,,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{d5,,ssl} module.


@c ======================================================================

@node Deprecations and Removals,建置和 C API 變更<9>,New and Improved Modules<2>,Python 2 6 有什麼新功能
@anchor{whatsnew/2 6 deprecations-and-removals}@anchor{15e2}
@subsection Deprecations and Removals



@itemize *

@item 
String exceptions have been removed.  Attempting to use them raises a
@ref{198,,TypeError}.

@item 
Changes to the @ref{bc4,,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{786,,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{3f,,email}
package instead.

@item 
The @code{md5} module has been deprecated; use the @ref{6c,,hashlib} module
instead.

@item 
The @code{posixfile} module has been deprecated; @ref{15e3,,fcntl.lockf()}
provides better locking.

@item 
The @code{popen2} module has been deprecated; use the @ref{dc,,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{184,,set} and @ref{7eb,,frozenset} types.

@item 
The @code{sha} module has been deprecated; use the @ref{6c,,hashlib} module
instead.
@end itemize

@c ======================================================================

@node 建置和 C API 變更<9>,Porting to Python 2 6,Deprecations and Removals,Python 2 6 有什麼新功能
@anchor{whatsnew/2 6 build-and-c-api-changes}@anchor{15e4}
@subsection 建置和 C API 變更


Python 建置程序和 C API 的變更包括：


@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{15ac,,the PEP 3118 section},
adds @ref{632,,PyObject_GetBuffer()} and @ref{633,,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{653,,ImportError}.  A new API
function, @ref{3d9,,PyImport_ImportModuleNoBlock()}, will look for a
module in @code{sys.modules} first, then try to import it after
acquiring an import lock.  If the import lock is held by another
thread, an @ref{653,,ImportError} is raised.
(Contributed by Christian Heimes.)

@item 
Several functions return information about the platform's
floating-point support.  @ref{15e5,,PyFloat_GetMax()} returns
the maximum representable floating-point value,
and @ref{15e6,,PyFloat_GetMin()} returns the minimum
positive value.  @ref{15e7,,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{15e8,,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{15e9,,PyModule_AddStringMacro}
and @ref{15ea,,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{97d,,Py_SIZE()},
@code{Py_Type()} became @ref{3c7,,Py_TYPE()}, and
@code{Py_Refcnt()} became @ref{2cf,,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>,,建置和 C API 變更<9>
@anchor{whatsnew/2 6 port-specific-changes-windows}@anchor{15eb}
@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{15ec,,getwch()} function reads a keypress and returns a Unicode
value, as does the @ref{15ed,,getwche()} function.  The @ref{15ee,,putwch()} function
takes a Unicode character and writes it to the console.
(Contributed by Christian Heimes.)

@item 
@ref{15d0,,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{d1,,socket} module's socket objects now have an
@ref{ec9,,ioctl()} method that provides a limited interface to the
@code{WSAIoctl()} system interface.

@item 
The @ref{11c,,_winreg} module now has a function,
@ref{15ef,,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{186,,with} statements. (Contributed by Christian Heimes.)

@ref{11c,,_winreg} also has better support for x64 systems,
exposing the @ref{155c,,DisableReflectionKey()}, @ref{155d,,EnableReflectionKey()},
and @ref{155e,,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>,建置和 C API 變更<9>
@anchor{whatsnew/2 6 port-specific-changes-mac-os-x}@anchor{15f0}
@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>,建置和 C API 變更<9>
@anchor{whatsnew/2 6 port-specific-changes-irix}@anchor{15f1}
@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,致謝<2>,建置和 C API 變更<9>,Python 2 6 有什麼新功能
@anchor{whatsnew/2 6 porting-to-python-2-6}@anchor{15f2}
@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{198,,TypeError}.

@item 
The @code{__init__()} method of @ref{7ed,,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{8b7,,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{198,,TypeError}.  This will affect
@code{__init__()} methods that end up calling the corresponding
method on @ref{c75,,object} (perhaps through using @ref{1a6,,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{ac8,,__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{653,,ImportError}.

@item 
C API: the @ref{15f3,,PyImport_Import()} and @ref{3da,,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{15be,,PyObject_HashNotImplemented()}.

@item 
The @ref{d1,,socket} module exception @ref{1251,,socket.error} now inherits
from @ref{124e,,IOError}.  Previously it wasn't a subclass of
@code{StandardError} but now it is, through @ref{124e,,IOError}.
(Implemented by Gregory P. Smith; bpo-1706815@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1706815}.)

@item 
The @ref{134,,xmlrpclib} module no longer automatically converts
@ref{1fa,,datetime.date} and @ref{1fb,,datetime.time} to the
@ref{15da,,xmlrpclib.DateTime} type; the conversion semantics were
not necessarily correct for all applications.  Code using
@code{xmlrpclib} should convert @code{date} and @ref{1fb,,time}
instances. (bpo-1330538@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1330538})

@item 
(3.0-warning mode) The @ref{bc4,,Exception} class now warns
when accessed using slicing or index access; having
@ref{bc4,,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 致謝<2>,,Porting to Python 2 6,Python 2 6 有什麼新功能
@anchor{whatsnew/2 6 acknowledgements}@anchor{15f4}@anchor{whatsnew/2 6 acks}@anchor{15f5}
@subsection 致謝


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 Python 2 5 有什麼新功能,Python 2 4 有什麼新功能,Python 2 6 有什麼新功能,Python 有什麼新功能？
@anchor{whatsnew/2 5 doc}@anchor{15f6}@anchor{whatsnew/2 5 translation-repo}@anchor{15f7}@anchor{whatsnew/2 5 what-s-new-in-python-2-5}@anchor{15f8}
@section Python 2.5 有什麼新功能


@*作者: 
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{2e,,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{15f9,,PEP 308; Conditional Expressions}.  The new '@ref{186,,with}' statement will make
writing cleanup code easier (section @ref{15fa,,PEP 343：'with' 陳述式}).  Values can now be passed
into generators (section @ref{15fb,,PEP 342; New Generator Features}).  Imports are now visible as either
absolute or relative (section @ref{15fc,,PEP 328; Absolute and Relative Imports}).  Some corner cases of exception
handling are handled better (section @ref{15fd,,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：'with' 陳述式: PEP 343：'with' 陳述式<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. 
* 其他語言更動: 其他語言更動<16>. 
* New@comma{} Improved@comma{} and Removed Modules: New Improved and Removed Modules. 
* 建置和 C API 變更: 建置和 C API 變更<10>. 
* Porting to Python 2.5: Porting to Python 2 5. 
* 致謝: 致謝<3>. 

@end menu

@node PEP 308 Conditional Expressions,PEP 309 Partial Function Application,,Python 2 5 有什麼新功能
@anchor{whatsnew/2 5 pep-308}@anchor{15f9}@anchor{whatsnew/2 5 pep-308-conditional-expressions}@anchor{15fe}
@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,Python 2 5 有什麼新功能
@anchor{whatsnew/2 5 pep-309}@anchor{15ff}@anchor{whatsnew/2 5 pep-309-partial-function-application}@anchor{1600}
@subsection PEP 309: Partial Function Application


The @ref{63,,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{63,,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,Python 2 5 有什麼新功能
@anchor{whatsnew/2 5 pep-314}@anchor{1601}@anchor{whatsnew/2 5 pep-314-metadata-for-python-software-packages-v1-1}@anchor{1602}
@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,Python 2 5 有什麼新功能
@anchor{whatsnew/2 5 pep-328}@anchor{15fc}@anchor{whatsnew/2 5 pep-328-absolute-and-relative-imports}@anchor{1603}
@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{d8,,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{d8,,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{7f1,,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{d8,,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                 # 引入 A.B.D
from .. import E                # 引入 A.E
from ..F import G               # 引入 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

由 Aahz 撰寫 PEP；由 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,Python 2 5 有什麼新功能
@anchor{whatsnew/2 5 pep-338}@anchor{1604}@anchor{whatsnew/2 5 pep-338-executing-modules-as-scripts}@anchor{1605}
@subsection PEP 338: Executing Modules as Scripts


The @ref{23c,,-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{c3,,runpy}.

The @ref{c3,,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{138,,zipimport} module.  This means you can add a .zip archive's path to
@code{sys.path} and then use the @ref{23c,,-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

由 Nick Coghlan 撰寫 PEP 與實作。
@end table


@c ======================================================================

@node PEP 341 Unified try/except/finally,PEP 342 New Generator Features,PEP 338 Executing Modules as Scripts,Python 2 5 有什麼新功能
@anchor{whatsnew/2 5 pep-341}@anchor{15fd}@anchor{whatsnew/2 5 pep-341-unified-try-except-finally}@anchor{1606}
@subsection PEP 341: Unified try/except/finally


Until Python 2.5, the @ref{8f0,,try} statement came in two flavours. You could
use a @ref{1b0,,finally} block to ensure that code is always executed, or one or
more @ref{1ab,,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{1ab,,except} blocks and a @ref{1b0,,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{1ab,,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

由 Georg Brandl 撰寫 PEP；由 Thomas Lee 實作。
@end table


@c ======================================================================

@node PEP 342 New Generator Features,PEP 343：'with' 陳述式<2>,PEP 341 Unified try/except/finally,Python 2 5 有什麼新功能
@anchor{whatsnew/2 5 pep-342}@anchor{15fb}@anchor{whatsnew/2 5 pep-342-new-generator-features}@anchor{1607}
@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{bb9,,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{9d1,,next()} method, picking up after the @code{yield} statement.

In Python 2.3, @ref{bb9,,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{bb9,,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{bb9,,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{bb9,,yield} expression returns the
specified `value'.  If the regular @ref{9d1,,next()} method is called, the
@code{yield} returns @ref{87e,,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{bb9,,yield} will usually return @ref{87e,,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{bb9,,yield} expression
where the generator's execution is paused.

@item 
@code{close()} raises a new @ref{15bf,,GeneratorExit} exception inside the generator
to terminate the iteration.  On receiving this exception, the generator's code
must either raise @ref{15bf,,GeneratorExit} or @ref{df0,,StopIteration}.  Catching the
@ref{15bf,,GeneratorExit} exception and returning a value is illegal and will trigger
a @ref{244,,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{15bf,,GeneratorExit} occurs, I suggest
using a @code{try: ... finally:} suite instead of  catching @ref{15bf,,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{1af,,return} statement), but coroutines can be entered,
exited, and resumed at many different points (the @ref{bb9,,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{1b0,,finally} clause will now always get a
chance to run.  The syntactic restriction that you couldn't mix @ref{bb9,,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{186,,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：'with' 陳述式<2>,PEP 352 Exceptions as New-Style Classes,PEP 342 New Generator Features,Python 2 5 有什麼新功能
@anchor{whatsnew/2 5 pep-343}@anchor{15fa}@anchor{whatsnew/2 5 pep-343-the-with-statement}@anchor{1608}
@subsection PEP 343：'with' 陳述式


The '@ref{186,,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{186,,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{7dd,,__enter__()} and @ref{1501,,__exit__()}
methods.

The object's @ref{7dd,,__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{1501,,__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{186,,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{348,,for} loop raised an exception
part-way through the block.

@cartouche
@quotation 備註 
In this case, `f' is the same object created by @ref{315,,open()}, because
@ref{7dd,,__enter__()} returns `self'.
@end quotation
@end cartouche

The @ref{f3,,threading} module's locks and condition variables  also support the
'@ref{186,,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{3a,,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>. 
* contextlib 模組: contextlib 模組<2>. 

@end menu

@node Writing Context Managers<2>,contextlib 模組<2>,,PEP 343：'with' 陳述式<2>
@anchor{whatsnew/2 5 new-25-context-managers}@anchor{1609}@anchor{whatsnew/2 5 writing-context-managers}@anchor{160a}
@subsubsection Writing Context Managers


Under the hood, the '@ref{186,,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{7dd,,__enter__()} and @ref{1501,,__exit__()}
methods.

@item 
The context manager's @ref{7dd,,__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{893,,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{186,,with}' statement will
never realize anything went wrong.

@item 
If `BLOCK' didn't raise an exception,  the @ref{1501,,__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{7dd,,__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{186,,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{1501,,__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{1af,,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 contextlib 模組<2>,,Writing Context Managers<2>,PEP 343：'with' 陳述式<2>
@anchor{whatsnew/2 5 contextlibmod}@anchor{160b}@anchor{whatsnew/2 5 the-contextlib-module}@anchor{160c}
@subsubsection contextlib 模組


The new @ref{27,,contextlib} module provides some functions and a decorator that
are useful for writing objects for use with the '@ref{186,,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{bb9,,yield} will be executed as the
@ref{7dd,,__enter__()} method, and the value yielded will be the method's return
value that will get bound to the variable in the '@ref{186,,with}' statement's
@code{as} clause, if any.  The code after the @ref{bb9,,yield} will be
executed in the @ref{1501,,__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{186,,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/} - "with" 陳述式

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{186,,with}' statement, which can be helpful in learning how the statement
works.
@end table

@ref{27,,contextlib} 模組的文件。


@c ======================================================================

@node PEP 352 Exceptions as New-Style Classes,PEP 353 Using ssize_t as the index type,PEP 343：'with' 陳述式<2>,Python 2 5 有什麼新功能
@anchor{whatsnew/2 5 pep-352}@anchor{160d}@anchor{whatsnew/2 5 pep-352-exceptions-as-new-style-classes}@anchor{160e}
@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{bc4,,Exception} class and all the standard built-in exceptions
(@ref{450,,NameError}, @ref{2eb,,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{bbc,,KeyboardInterrupt} and @ref{f37,,SystemExit}
aren't errors, though, and usually represent an explicit action such as the user
hitting @code{Control}-@code{C} or code calling @ref{277,,sys.exit()}.  A bare @code{except:} will
catch all exceptions, so you commonly need to list @ref{bbc,,KeyboardInterrupt} and
@ref{f37,,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{bbc,,KeyboardInterrupt} and @ref{f37,,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{7d0,,BaseException} or some descendant of @ref{7d0,,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{bc4,,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,Python 2 5 有什麼新功能
@anchor{whatsnew/2 5 pep-353}@anchor{160f}@anchor{whatsnew/2 5 pep-353-using-ssize-t-as-the-index-type}@anchor{1610}
@subsection PEP 353: Using ssize_t as the index type


A wide-ranging change to Python's C API, using a new  @ref{c4c,,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{5d7,,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{c4c,,Py_ssize_t} to store their size.   Functions such as
@ref{1611,,PyList_Size()}  now return @ref{c4c,,Py_ssize_t}.  Code in extension modules
may therefore need to have some variables changed to @ref{c4c,,Py_ssize_t}.

The @ref{3bf,,PyArg_ParseTuple()} and @ref{3c0,,Py_BuildValue()} functions have a new
conversion code, @code{n}, for @ref{c4c,,Py_ssize_t}.   @ref{3bf,,PyArg_ParseTuple()}'s
@code{s#} and @code{t#} still output int by default, but you can define the
macro  @code{PY_SSIZE_T_CLEAN} before including @code{Python.h}  to make
them return @ref{c4c,,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

由 Martin von Löwis 撰寫 PEP 與實作。
@end table


@c ======================================================================

@node PEP 357 The '__index__' method,其他語言更動<16>,PEP 353 Using ssize_t as the index type,Python 2 5 有什麼新功能
@anchor{whatsnew/2 5 pep-357}@anchor{1612}@anchor{whatsnew/2 5 pep-357-the-index-method}@anchor{1613}
@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{198,,TypeError} if this requirement isn't met.

A corresponding @ref{1614,,nb_index} slot was added to the C-level
@ref{1615,,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

由 Travis Oliphant 撰寫 PEP 與實作。
@end table


@c ======================================================================

@node 其他語言更動<16>,New Improved and Removed Modules,PEP 357 The '__index__' method,Python 2 5 有什麼新功能
@anchor{whatsnew/2 5 other-lang}@anchor{1616}@anchor{whatsnew/2 5 other-language-changes}@anchor{1617}
@subsection 其他語言更動


Here are all of the changes that Python 2.5 makes to the core Python language.


@itemize *

@item 
The @ref{183,,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]   # 印出 1, 2
print d[3], d[4]   # 印出 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'.

一些範例：

@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

（由 Georg Brandl 實作、後有 Tom Lynn 提出建議。）

@c RFE #1491485

@item 
The @ref{1106,,min()} and @ref{1107,,max()} built-in functions gained a @code{key} keyword
parameter analogous to the @code{key} argument for @code{sort()}.  This parameter
supplies a function that takes a single argument and is called for every value
in the list; @ref{1106,,min()}/@ref{1107,,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

（由 Steven Bethard 和 Raymond Hettinger 所貢獻。）

@item 
Two new built-in functions, @ref{1618,,any()} and @ref{1619,,all()}, evaluate whether an
iterator contains any true or false values.  @ref{1618,,any()} returns @ref{e02,,True}
if any value returned by the iterator is true; otherwise it will return
@ref{d23,,False}.  @ref{1619,,all()} returns @ref{e02,,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{161a,,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{161b,,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)   # 無法將 chr(128) 轉換為 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) 可以被轉換
True
@end example

Previously this would raise a @ref{bff,,UnicodeDecodeError} exception, but in 2.5
this could result in puzzling problems when accessing a dictionary.  If you
looked up @code{unichr(128)} and @code{chr(128)} was being used as a key, you'd get a
@ref{bff,,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{161b,,UnicodeWarning} was introduced.

（由 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{161c,,-v} switch to
log all the paths searched. In Python 2.5, a new @ref{717,,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{abc,,-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

（由 Brett Cannon 實作。）
@end itemize

@c ======================================================================

@menu
* Interactive Interpreter Changes:: 
* 最佳化: 最佳化<16>. 

@end menu

@node Interactive Interpreter Changes,最佳化<16>,,其他語言更動<16>
@anchor{whatsnew/2 5 interactive}@anchor{161d}@anchor{whatsnew/2 5 interactive-interpreter-changes}@anchor{161e}
@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{7ff,,--help}
and @ref{f12,,--version}; on Windows,  it also accepts the @ref{161f,,/?} option
for displaying a help message. (Implemented by Georg Brandl.)

@c ======================================================================

@node 最佳化<16>,,Interactive Interpreter Changes,其他語言更動<16>
@anchor{whatsnew/2 5 optimizations}@anchor{1620}@anchor{whatsnew/2 5 opts}@anchor{1621}
@subsubsection 最佳化


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{184,,set} and
@ref{7eb,,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{bf,,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{2eb,,ValueError} from the @code{read*()} method.
(Implemented by Thomas Wouters.)

@c Patch 1397960

@item 
The @ref{db,,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{be,,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,建置和 C API 變更<10>,其他語言更動<16>,Python 2 5 有什麼新功能
@anchor{whatsnew/2 5 modules}@anchor{1622}@anchor{whatsnew/2 5 new-improved-and-removed-modules}@anchor{1623}
@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 @ref{1c,,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{183,,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{24d,,list()} or @ref{19b,,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

（由 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{2eb,,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{186,,with}' statement.  See section @ref{160b,,contextlib 模組}
for more about this module.

@item 
New module: The @ref{2b,,cProfile} module is a C implementation of  the existing
@ref{b4,,profile} module that has much lower overhead. The module's interface is
the same as @ref{b4,,profile}: you run @code{cProfile.run('main()')} to profile a
function, can save profile data to a file, etc.  It's not yet known if the
Hotshot profiler, which is also written in C but doesn't match the
@ref{b4,,profile} module's interface, will continue to be maintained in future
versions of Python.  (Contributed by Armin Rigo.)

Also, the @ref{b5,,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{2d,,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.

（由 Skip Montanaro 和 Andrew McNamara 所貢獻。）

@item 
The @ref{4dd,,datetime} class in the @ref{34,,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{1624,,time.strptime()} and
@ref{13ea,,time.strftime()}:

@example
from datetime import datetime

ts = datetime.strptime('10:13:15 2006-03-07',
                       '%H:%M:%S %Y-%m-%d')
@end example

@item 
The @code{SequenceMatcher.get_matching_blocks()} method in the @ref{3b,,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{3e,,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{3f,,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{5f,,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{14d9,,input()} function to allow opening files in binary or @ref{f30,,universal newlines} mode.  Another new parameter, `openhook', lets you use a function
other than @ref{315,,open()}  to open the input files.  Once you're iterating over
the set of files, the @code{FileInput} object's new @ref{1625,,fileno()} returns
the file descriptor for the currently opened file. (Contributed by Georg
Brandl.)

@item 
In the @ref{64,,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{1b3,,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{6d,,heapq}
module  now support a @code{key} keyword parameter similar to the one provided by
the @ref{1106,,min()}/@ref{1107,,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

（由 Raymond Hettinger 所貢獻。）

@item 
The @ref{d3b,,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

（由 Raymond Hettinger 所貢獻。）

@item 
The @ref{199,,format()} function in the @ref{8a,,locale} module has been modified and
two new functions were added, @code{format_string()} and @code{currency()}.

The @ref{199,,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{199,,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.

（由 Georg Brandl 所貢獻。）

@c Patch 1180296

@item 
The @ref{8f,,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{26d,,os.stat()} will now return time
values as floats.  (This doesn't necessarily mean that @ref{26d,,os.stat()} will
return times that are precise to fractions of a second; not all systems support
such precision.)

Constants named @ref{148e,,os.SEEK_SET}, @ref{148f,,os.SEEK_CUR}, and
@ref{1490,,os.SEEK_END} have been added; these are the parameters to the
@ref{1318,,os.lseek()} function.  Two new constants for locking are
@ref{1626,,os.O_SHLOCK} and @ref{1627,,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{1628,,resource.getrusage()} function. @code{wait4(pid)} does take a process ID.
(Contributed by Chad J. Schroeder.)

On FreeBSD, the @ref{26d,,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{bbd,,__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{158c,,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{c2,,rlcompleter} module is no longer  dependent on importing the
@ref{bf,,readline} module and therefore now works on non-Unix platforms. (Patch
from Robert Kiendl.)

@c Patch #1472854

@item 
The @ref{135,,SimpleXMLRPCServer} and @ref{135,,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{d1,,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{db,,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{be,,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{1629,,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{162a,,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{e4,,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{f3,,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{10b,,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{162b,,unicodedata.ucd_3_2_0}.

@item 
New module: the  @ref{116,,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

（由 Ka-Ping Yee 所貢獻。）

@item 
The @ref{11a,,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{11b,,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{315,,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{134,,xmlrpclib} module now supports returning  @ref{4dd,,datetime} objects
for the XML-RPC date type.  Supply  @code{use_datetime=True} to the @ref{162c,,loads()}
function or the @code{Unmarshaller} class to enable this feature. (Contributed
by Skip Montanaro.)

@c Patch 1120353

@item 
The @ref{137,,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{139,,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
* ctypes 套件:: 
* ElementTree 套件:: 
* hashlib 套件:: 
* sqlite3 套件:: 
* wsgiref 套件:: 

@end menu

@node ctypes 套件,ElementTree 套件,,New Improved and Removed Modules
@anchor{whatsnew/2 5 module-ctypes}@anchor{162d}@anchor{whatsnew/2 5 the-ctypes-package}@anchor{162e}
@subsubsection ctypes 套件


The @ref{2e,,ctypes} package, written by Thomas Heller, has been added  to the
standard library.  @ref{2e,,ctypes} lets you call arbitrary functions  in shared
libraries or DLLs.  Long-time users may remember the @code{dl} module, which
provides functions for loading shared libraries and calling functions in them.
The @ref{2e,,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{2e,,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{1f3,,py_object} type
constructor that will create a  @ref{5d7,,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 現在為 @{'abc', 1@}.
@end example

Don't forget to use @ref{1f3,,py_object()}; if it's omitted you end  up with a
segmentation fault.

@ref{2e,,ctypes} has been around for a while, but people still write  and
distribution hand-coded extension modules because you can't rely on
@ref{2e,,ctypes} being present. Perhaps developers will begin to write  Python
wrappers atop a library accessed through @ref{2e,,ctypes} instead of extension
modules, now that @ref{2e,,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

@ref{2e,,ctypes} 模組的文件。


@c ======================================================================

@node ElementTree 套件,hashlib 套件,ctypes 套件,New Improved and Removed Modules
@anchor{whatsnew/2 5 module-etree}@anchor{162f}@anchor{whatsnew/2 5 the-elementtree-package}@anchor{1630}
@subsubsection ElementTree 套件


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

操作

@tab

結果

@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 hashlib 套件,sqlite3 套件,ElementTree 套件,New Improved and Removed Modules
@anchor{whatsnew/2 5 module-hashlib}@anchor{1631}@anchor{whatsnew/2 5 the-hashlib-package}@anchor{1632}
@subsubsection hashlib 套件


A new @ref{6c,,hashlib} module, written by Gregory P. Smith,  has been added to
replace the @code{md5} and @code{sha} modules.  @ref{6c,,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 也參考


@ref{6c,,hashlib} 模組的文件。


@c ======================================================================

@node sqlite3 套件,wsgiref 套件,hashlib 套件,New Improved and Removed Modules
@anchor{whatsnew/2 5 module-sqlite}@anchor{1633}@anchor{whatsnew/2 5 the-sqlite3-package}@anchor{1634}
@subsubsection sqlite3 套件


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{d4,,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

@ref{d4,,sqlite3} 模組的文件。


@table @asis

@geindex Python Enhancement Proposals; PEP 249

@item PEP 249@footnote{https://peps.python.org/pep-0249/} - Database API Specification 2.0

由 Marc-André Lemburg 撰寫 PEP。
@end table


@c ======================================================================

@node wsgiref 套件,,sqlite3 套件,New Improved and Removed Modules
@anchor{whatsnew/2 5 module-wsgiref}@anchor{1635}@anchor{whatsnew/2 5 the-wsgiref-package}@anchor{1636}
@subsubsection wsgiref 套件


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{11e,,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

由 Phillip J. Eby 撰寫 PEP。
@end table


@c ======================================================================

@node 建置和 C API 變更<10>,Porting to Python 2 5,New Improved and Removed Modules,Python 2 5 有什麼新功能
@anchor{whatsnew/2 5 build-and-c-api-changes}@anchor{1637}@anchor{whatsnew/2 5 build-api}@anchor{1638}
@subsection 建置和 C API 變更


Python 建置程序和 C API 的變更包括：


@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{c4c,,Py_ssize_t} type definition instead of
int.  See the earlier section @ref{160f,,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{4ac,,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{e5b,,PyMem_Malloc()},
@ref{122d,,PyMem_Realloc()}, and @ref{1639,,PyMem_Free()} are one family that allocates
raw memory, while @ref{e5d,,PyObject_Malloc()}, @ref{163a,,PyObject_Realloc()}, and
@ref{e5a,,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{163b,,PySet_New()}
and @ref{163c,,PyFrozenSet_New()} to create a new set, @ref{163d,,PySet_Add()} and
@ref{163e,,PySet_Discard()} to add and remove elements, and @ref{163f,,PySet_Contains()}
and @ref{1640,,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{1629,,Py_GetBuildInfo()} function that returns a
string of build information like this: @code{"trunk:45355:45356M, Apr 13 2006,
07:42:19"}.   (Contributed by Barry Warsaw.)

@item 
Two new macros can be used to indicate C functions that are local to the
current file so that a faster calling convention can be used.
@code{Py_LOCAL(type)} declares the function as returning a value of the
specified `type' and uses a fast-calling qualifier.
@code{Py_LOCAL_INLINE(type)} does the same thing and also requests the
function be inlined.  If macro @code{PY_LOCAL_AGGRESSIVE} is defined before
@code{python.h} is included, a set of more aggressive optimizations are enabled
for the module; you should benchmark the results to find out if these
optimizations actually make the code faster.  (Contributed by Fredrik Lundh at
the NeedForSpeed sprint.)

@item 
@code{PyErr_NewException(name, base, dict)} can now accept a tuple of base
classes as its `base' argument.  (Contributed by Georg Brandl.)

@item 
The @code{PyErr_Warn()} function for issuing warnings is now deprecated in
favour of @code{PyErr_WarnEx(category, message, stacklevel)} which lets you
specify the number of stack frames separating this function and the caller.  A
`stacklevel' of 1 is the function calling @ref{1641,,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,,,建置和 C API 變更<10>
@anchor{whatsnew/2 5 port-specific-changes}@anchor{1642}@anchor{whatsnew/2 5 ports}@anchor{1643}
@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,致謝<3>,建置和 C API 變更<10>,Python 2 5 有什麼新功能
@anchor{whatsnew/2 5 porting}@anchor{1644}@anchor{whatsnew/2 5 porting-to-python-2-5}@anchor{1645}
@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{15fb,,PEP 342; New Generator Features},
it's now possible for @code{gi_frame} to be @code{None}.

@item 
A new warning, @ref{161b,,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{bff,,UnicodeDecodeError} exception.

@item 
Library: the @ref{2d,,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{8a,,locale} module's  @ref{199,,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{bbd,,__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{135,,SimpleXMLRPCServer} and @ref{135,,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{c4c,,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{160f,,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 致謝<3>,,Porting to Python 2 5,Python 2 5 有什麼新功能
@anchor{whatsnew/2 5 acknowledgements}@anchor{1646}
@subsection 致謝


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 Python 2 4 有什麼新功能,Python 2 3 有什麼新功能,Python 2 5 有什麼新功能,Python 有什麼新功能？
@anchor{whatsnew/2 4 doc}@anchor{1647}@anchor{whatsnew/2 4 translation-repo}@anchor{1648}@anchor{whatsnew/2 4 what-s-new-in-python-2-4}@anchor{1649}
@section Python 2.4 有什麼新功能


@*作者: 
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. 
* 其他語言更動: 其他語言更動<17>. 
* New@comma{} Improved@comma{} and Deprecated Modules: New Improved and Deprecated Modules<2>. 
* 建置和 C API 變更: 建置和 C API 變更<11>. 
* Porting to Python 2.4: Porting to Python 2 4. 
* 致謝: 致謝<4>. 

@end menu

@node PEP 218 Built-In Set Objects,PEP 237 Unifying Long Integers and Integers,,Python 2 4 有什麼新功能
@anchor{whatsnew/2 4 pep-218-built-in-set-objects}@anchor{164a}
@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{7eb,,frozenset()} type is an immutable version of @ref{184,,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,Python 2 4 有什麼新功能
@anchor{whatsnew/2 4 pep-237-unifying-long-integers-and-integers}@anchor{164b}
@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{651,,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,Python 2 4 有什麼新功能
@anchor{whatsnew/2 4 pep-289-generator-expressions}@anchor{164c}
@subsection PEP 289: Generator Expressions


The iterator feature introduced in Python 2.2 and the @ref{85,,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/} - 產生器運算式

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,Python 2 4 有什麼新功能
@anchor{whatsnew/2 4 pep-292-simpler-string-substitutions}@anchor{164d}
@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{2eb,,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{d8,,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{5df,,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,Python 2 4 有什麼新功能
@anchor{whatsnew/2 4 pep-318-decorators-for-functions-and-methods}@anchor{164e}
@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{164f,,def} statement
in the usual way, and pass the resulting method to a @ref{451,,staticmethod()} or
@ref{489,,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{489,,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{489,,classmethod()}, @ref{451,,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{14d5,,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,Python 2 4 有什麼新功能
@anchor{whatsnew/2 4 pep-322-reverse-iteration}@anchor{1650}
@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{a5e,,reversed()} is
easier to read, runs faster, and uses substantially less memory.

Note that @ref{a5e,,reversed()} only accepts sequences, not arbitrary iterators.  If
you want to reverse an iterator, first convert it to  a list with @ref{24d,,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,Python 2 4 有什麼新功能
@anchor{whatsnew/2 4 pep-324-new-subprocess-module}@anchor{1651}
@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{dc,,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{dc,,subprocess} contains a
single class called @ref{4b2,,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{1652,,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{f30,,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{1652,,os.system()}:

@example
sts = subprocess.call(['dpkg', '-i', '/tmp/new-package.deb'])
if sts == 0:
    # 成功
    ...
else:
    # dpkg 回傳一個錯誤
    ...
@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{dc,,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 - 新的行程模組

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,Python 2 4 有什麼新功能
@anchor{whatsnew/2 4 pep-327-decimal-data-type}@anchor{1653}
@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?:: 
* Decimal 型別:: 
* Context 型別:: 

@end menu

@node Why is Decimal needed?,Decimal 型別,,PEP 327 Decimal Data Type
@anchor{whatsnew/2 4 why-is-decimal-needed}@anchor{1654}
@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 Decimal 型別,Context 型別,Why is Decimal needed?,PEP 327 Decimal Data Type
@anchor{whatsnew/2 4 the-decimal-type}@anchor{1655}
@subsubsection @code{Decimal} 型別


A new module, @ref{3a,,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{92,,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 Context 型別,,Decimal 型別,PEP 327 Decimal Data Type
@anchor{whatsnew/2 4 the-context-type}@anchor{1656}
@subsubsection @code{Context} 型別


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{3a,,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{3a,,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,Python 2 4 有什麼新功能
@anchor{whatsnew/2 4 pep-328-multi-line-imports}@anchor{1657}
@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{7f1,,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,其他語言更動<17>,PEP 328 Multi-line Imports,Python 2 4 有什麼新功能
@anchor{whatsnew/2 4 pep-331-locale-independent-float-string-conversions}@anchor{1658}
@subsection PEP 331: Locale-Independent Float/String Conversions


The @ref{8a,,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{8a,,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 其他語言更動<17>,New Improved and Deprecated Modules<2>,PEP 331 Locale-Independent Float/String Conversions,Python 2 4 有什麼新功能
@anchor{whatsnew/2 4 other-language-changes}@anchor{1659}
@subsection 其他語言更動


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{184,,set()} and @ref{7eb,,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{165a,,dict.update()} method now accepts the same argument forms as the
@ref{183,,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{149e,,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{dc3,,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

（由 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{23c,,-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{1a0,,zip()} built-in function and @code{itertools.izip()} now return an
empty list if called with no arguments. Previously they raised a
@ref{198,,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

（由 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{87e,,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
* 最佳化: 最佳化<17>. 

@end menu

@node 最佳化<17>,,,其他語言更動<17>
@anchor{whatsnew/2 4 optimizations}@anchor{165b}
@subsubsection 最佳化



@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{5fa,,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{24d,,list()}, @ref{60c,,tuple()}, @ref{19f,,map()}, @ref{a5d,,filter()}, and @ref{1a0,,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<2>,建置和 C API 變更<11>,其他語言更動<17>,Python 2 4 有什麼新功能
@anchor{whatsnew/2 4 new-improved-and-deprecated-modules}@anchor{165c}
@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{f3,,threading} modules, now take
advantage of @ref{7ed,,collections.deque} for improved performance.  (Contributed
by Raymond Hettinger.)

@item 
The @ref{26,,ConfigParser} classes have been enhanced slightly. The @ref{165d,,read()}
method now returns a list of the files that were successfully parsed, and the
@ref{146d,,set()} method raises @ref{198,,TypeError} if passed a `value' argument that
isn't a string.   (Contributed by John Belmonte and David Goodger.)

@item 
The @ref{2f,,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{3b,,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{3f,,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{6d,,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{72,,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{78,,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{85,,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

（由 Hye-Shik Chang 所貢獻。）

@item 
@ref{85,,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{24d,,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{8a,,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{8b,,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{8b,,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.

（由 Vinay Sajip 所實作。）

@item 
The @ref{91,,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{19f,,map()}
or @ref{dc2,,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)) # 以第二個元組項目來排序串列
[('d', 1), ('c', 2), ('b', 3), ('a', 4)]
@end example

（由 Raymond Hettinger 所貢獻。）

@item 
The @ref{a4,,optparse} module was updated in various ways.  The module now passes
its messages through @ref{165e,,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{3f,,email} package. To this end, the
@ref{165f,,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{bd,,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{be,,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{be,,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{244,,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{cb,,signal} module now performs tighter error-checking on the parameters
to the @ref{1335,,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{244,,RuntimeError} exception.

@item 
Two new functions were added to the @ref{d1,,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 @ref{d,,atexit}.

@item 
The @ref{e4,,tarfile} module now generates GNU-format tar files by default.
(Contributed by Lars Gustäbel.)

@item 
The @ref{f3,,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{f5,,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{11a,,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{134,,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<2>
@anchor{whatsnew/2 4 cookielib}@anchor{1660}
@subsubsection cookielib


The @ref{74,,cookielib} library supports client-side handling for HTTP cookies,
mirroring the @ref{75,,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{111,,urllib2} has been changed to interact with @ref{74,,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<2>
@anchor{whatsnew/2 4 doctest}@anchor{1661}
@subsubsection doctest


The @ref{3e,,doctest} module underwent considerable refactoring thanks to Edward
Loper and Tim Peters.  Testing can still be as simple as running
@ref{1662,,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{1663,,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{1664,,doctest.REPORT_UDIFF} (unified diffs),
@ref{1665,,doctest.REPORT_CDIFF} (context diffs), or @ref{1666,,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{1664,,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 建置和 C API 變更<11>,Porting to Python 2 4,New Improved and Deprecated Modules<2>,Python 2 4 有什麼新功能
@anchor{whatsnew/2 4 build-and-c-api-changes}@anchor{1667}
@subsection 建置和 C API 變更


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{1668,,Py_RETURN_NONE}, @ref{1669,,Py_RETURN_TRUE}, and
@ref{166a,,Py_RETURN_FALSE}. (Contributed by Brett Cannon.)

@item 
Another new macro, @ref{791,,Py_CLEAR},  decreases the reference count of
`obj' and sets `obj' to the null pointer.  (Contributed by Jim Fulton.)

@item 
A new function, @code{PyTuple_Pack(N, obj1, obj2, ..., objN)}, constructs
tuples from a variable length argument list of Python objects.  (Contributed by
Raymond Hettinger.)

@item 
A new function, @code{PyDict_Contains(d, k)}, implements fast dictionary
lookups without masking exceptions raised during the look-up process.
(Contributed by Raymond Hettinger.)

@item 
The Py_IS_NAN(X) macro returns 1 if  its float or double argument
`X' is a NaN.   (Contributed by Tim Peters.)

@item 
C code can avoid unnecessary locking by using the new
@code{PyEval_ThreadsInitialized()} function to tell  if any thread operations
have been performed.  If this function  returns false, no lock operations are
needed. (Contributed by Nick Coghlan.)

@item 
A new function, @ref{61d,,PyArg_VaParseTupleAndKeywords()}, is the same as
@ref{61c,,PyArg_ParseTupleAndKeywords()} but takes a  @code{va_list} instead of a
number of arguments. (Contributed by Greg Chapman.)

@item 
A new method flag, @ref{166b,,METH_COEXIST}, allows a function defined in slots
to co-exist with a @ref{166c,,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>,,,建置和 C API 變更<11>
@anchor{whatsnew/2 4 port-specific-changes}@anchor{166d}
@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,致謝<4>,建置和 C API 變更<11>,Python 2 4 有什麼新功能
@anchor{whatsnew/2 4 porting-to-python-2-4}@anchor{166e}
@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{651,,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{1a0,,zip()} built-in function and @code{itertools.izip()} now return  an
empty list instead of raising a @ref{198,,TypeError} exception if called with no
arguments.

@item 
You can no longer compare the @code{date} and @ref{4dd,,datetime} instances
provided by the @ref{34,,datetime} module.  Two  instances of different classes
will now always be unequal, and  relative comparisons (@code{<}, @code{>}) will raise
a @ref{198,,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{166f,,fcntl.ioctl()} now warns if the `mutate'  argument is omitted and
relevant.

@item 
The @ref{e4,,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{87e,,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{244,,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 致謝<4>,,Porting to Python 2 4,Python 2 4 有什麼新功能
@anchor{whatsnew/2 4 acknowledgements}@anchor{1670}@anchor{whatsnew/2 4 acks}@anchor{1671}
@subsection 致謝


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 Python 2 3 有什麼新功能,Python 2 2 有什麼新功能,Python 2 4 有什麼新功能,Python 有什麼新功能？
@anchor{whatsnew/2 3 doc}@anchor{1672}@anchor{whatsnew/2 3 translation-repo}@anchor{1673}@anchor{whatsnew/2 3 what-s-new-in-python-2-3}@anchor{1674}
@section Python 2.3 有什麼新功能


@*作者: 
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{68e,,sum()} and @ref{1675,,enumerate()}.  The @ref{349,,in}
operator can now be used for substring searches (e.g. @code{"ab" in "abc"} returns
@ref{e02,,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：簡單產生器:: 
* 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:: 
* 其他語言更動: 其他語言更動<18>. 
* New@comma{} Improved@comma{} and Deprecated Modules: New Improved and Deprecated Modules<3>. 
* Pymalloc; A Specialized Object Allocator: Pymalloc A Specialized Object Allocator. 
* 建置和 C API 變更: 建置和 C API 變更<12>. 
* Other Changes and Fixes: Other Changes and Fixes<2>. 
* Porting to Python 2.3: Porting to Python 2 3. 
* 致謝: 致謝<5>. 

@end menu

@node PEP 218 A Standard Set Datatype,PEP 255：簡單產生器,,Python 2 3 有什麼新功能
@anchor{whatsnew/2 3 pep-218-a-standard-set-datatype}@anchor{1676}
@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.

以下是個簡單範例：

@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{1677,,union()} and
@ref{1678,,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{1679,,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                  # 另一種標記法
Set([1, 2, 3, 4, 5, 6])
>>> S1.intersection(S2)
Set([])
>>> S1 & S2                  # 另一種標記法
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{167a,,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：簡單產生器,PEP 263 Source Code Encodings,PEP 218 A Standard Set Datatype,Python 2 3 有什麼新功能
@anchor{whatsnew/2 3 pep-255-simple-generators}@anchor{167b}@anchor{whatsnew/2 3 section-generators}@anchor{167c}
@subsection PEP 255：簡單產生器


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{bb9,,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{1af,,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.

以下是產生器函式最簡單的範例：

@example
def generate_ints(N):
    for i in range(N):
        yield i
@end example

A new keyword, @ref{bb9,,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{bb9,,yield} statement, the generator outputs the value of @code{i},
similar to a @ref{1af,,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{8f0,,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{1af,,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{df0,,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{9d1,,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{181,,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/} - 簡單產生器

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：簡單產生器,Python 2 3 有什麼新功能
@anchor{whatsnew/2 3 pep-263-source-code-encodings}@anchor{167d}@anchor{whatsnew/2 3 section-encodings}@anchor{167e}
@subsection PEP 263: Source Code Encodings


Python source files can now be declared as being in different character set
encodings.  Encodings are declared by including a specially formatted comment in
the first or second line of the source file.  For example, a UTF-8 file can be
declared with:

@example
#!/usr/bin/env python
# -*- coding: UTF-8 -*-
@end example

Without such an encoding declaration, the default encoding used is 7-bit ASCII.
Executing or importing modules that contain string literals with 8-bit
characters and have no encoding declaration will result in a
@ref{1a3,,DeprecationWarning} being signalled by Python 2.3; in 2.4 this will be a
syntax error.

The encoding declaration only affects Unicode string literals, which will be
converted to Unicode using the specified encoding.  Note that Python identifiers
are still restricted to ASCII characters, so you can't have variable names that
use characters outside of the usual alphanumerics.


@subsubheading 也參考



@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,Python 2 3 有什麼新功能
@anchor{whatsnew/2 3 pep-273-importing-modules-from-zip-archives}@anchor{167f}
@subsection PEP 273: Importing Modules from ZIP Archives


The new @ref{138,,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{1680,,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,Python 2 3 有什麼新功能
@anchor{whatsnew/2 3 pep-277-unicode-file-name-support-for-windows-nt}@anchor{1681}
@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{315,,open()} built-in function. If a Unicode string is passed to
@ref{12fb,,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{460,,UnicodeError}
to be raised. Applications can test whether arbitrary Unicode strings are
supported as file names by checking @ref{1682,,os.path.supports_unicode_filenames},
a Boolean value.

Under MacOS, @ref{12fb,,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,Python 2 3 有什麼新功能
@anchor{whatsnew/2 3 pep-278-universal-newline-support}@anchor{1683}
@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{f30,,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,Python 2 3 有什麼新功能
@anchor{whatsnew/2 3 pep-279-enumerate}@anchor{1684}@anchor{whatsnew/2 3 section-enumerate}@anchor{1685}
@subsection PEP 279：enumerate()


A new built-in function, @ref{1675,,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{1675,,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,Python 2 3 有什麼新功能
@anchor{whatsnew/2 3 pep-282-the-logging-package}@anchor{1686}
@subsection PEP 282: The logging Package


A standard package for writing logs, @ref{8b,,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{d3e,,Logger} class is the primary class. Most application code will deal
with one or more @ref{d3e,,Logger} objects, each one used by a particular
subsystem of the application. Each @ref{d3e,,Logger} is identified by a name, and
names are organized into a hierarchy using @code{.}  as the component separator.
For example, you might have @ref{d3e,,Logger} instances named @code{server},
@code{server.auth} and @code{server.network}.  The latter two instances are below
@code{server} in the hierarchy.  This means that if you turn up the verbosity for
@code{server} or direct @code{server} messages to a different handler, the changes
will also apply to records logged to @code{server.auth} and @code{server.network}.
There's also a root @ref{d3e,,Logger} that's the parent of all other loggers.

For simple uses, the @ref{8b,,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{1687,,setLevel()} method
on the root logger.

Notice the @ref{352,,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{1688,,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{d3e,,Logger}
can prevent this by setting its @ref{1689,,propagate} attribute to @ref{d23,,False}.

There are more classes provided by the @ref{8b,,logging} package that can be
customized.  When a @ref{d3e,,Logger} instance is told to log a message, it
creates a @ref{11e1,,LogRecord} instance that is sent to any number of different
@ref{168a,,Handler} instances.  Loggers and handlers can also have an attached list
of filters, and each filter can cause the @ref{11e1,,LogRecord} to be ignored or
can modify the record before passing it along.  When they're finally output,
@ref{11e1,,LogRecord} instances are converted to text by a @ref{168b,,Formatter}
class.  All of these classes can be replaced by your own specially written
classes.

With all of these features the @ref{8b,,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,Python 2 3 有什麼新功能
@anchor{whatsnew/2 3 pep-285-a-boolean-type}@anchor{168c}@anchor{whatsnew/2 3 section-bool}@anchor{168d}
@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{e02,,True} and @ref{d23,,False}.  (@ref{e02,,True} and
@ref{d23,,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{3c1,,bool}; the constructor for it
takes any Python value and converts it to @ref{e02,,True} or @ref{d23,,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{181,,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{19b,,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{e02,,True} and @ref{d23,,False} in a sentence: they're alternative
ways to spell the integer values 1 and 0, with the single difference that
@ref{169,,str()} and @ref{1c1,,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,Python 2 3 有什麼新功能
@anchor{whatsnew/2 3 pep-293-codec-error-handling-callbacks}@anchor{168e}
@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{460,,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{168f,,codecs.register_error()}, and codecs then
can access the error handler with @ref{1690,,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,Python 2 3 有什麼新功能
@anchor{whatsnew/2 3 pep-301-package-index-and-metadata-for-distutils}@anchor{1691}@anchor{whatsnew/2 3 section-pep301}@anchor{1692}
@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,Python 2 3 有什麼新功能
@anchor{whatsnew/2 3 pep-302-new-import-hooks}@anchor{1693}@anchor{whatsnew/2 3 section-pep302}@anchor{1680}
@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{df,,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{653,,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,Python 2 3 有什麼新功能
@anchor{whatsnew/2 3 pep-305-comma-separated-files}@anchor{1694}@anchor{whatsnew/2 3 section-pep305}@anchor{1695}
@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{2d,,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{6a7,,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{6a8,,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 檔案 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,Python 2 3 有什麼新功能
@anchor{whatsnew/2 3 pep-307-pickle-enhancements}@anchor{1696}@anchor{whatsnew/2 3 section-pep307}@anchor{1697}
@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{1698,,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{1699,,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{7ea,,__getstate__()}, @ref{bbe,,__setstate__()}, and @ref{fcf,,__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,其他語言更動<18>,PEP 307 Pickle Enhancements,Python 2 3 有什麼新功能
@anchor{whatsnew/2 3 extended-slices}@anchor{169a}@anchor{whatsnew/2 3 section-slices}@anchor{169b}
@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{198,,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{582,,__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{b34,,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{68d,,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{19b,,int}, @ref{169,,str}, etc., underwent
the same change.

@c ======================================================================

@node 其他語言更動<18>,New Improved and Deprecated Modules<3>,Extended Slices,Python 2 3 有什麼新功能
@anchor{whatsnew/2 3 other-language-changes}@anchor{169c}
@subsection 其他語言更動


Here are all of the changes that Python 2.3 makes to the core Python language.


@itemize *

@item 
The @ref{bb9,,yield} statement is now always a keyword, as described in
section @ref{167c,,PEP 255：簡單產生器} of this document.

@item 
A new built-in function @ref{1675,,enumerate()} was added, as described in section
@ref{1685,,PEP 279：enumerate()} of this document.

@item 
Two new constants, @ref{e02,,True} and @ref{d23,,False} were added along with the
built-in @ref{3c1,,bool} type, as described in section @ref{168d,,PEP 285; A Boolean Type} of this
document.

@item 
The @ref{19b,,int()} type constructor will now return a long integer instead of
raising an @ref{a78,,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{169b,,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{68e,,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{5df,,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{183,,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

（由 Just van Rossum 所貢獻。）

@item 
The @ref{b57,,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{18c,,-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{109,,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{abd,,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{abc,,-Walways;;PendingDeprecationWarning;;} on the command line or
use @ref{169d,,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{abd,,PendingDeprecationWarning}.

@item 
Using @code{None} as a variable name will now result in a @ref{1ae,,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{169e,,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

在 2.3 中你會得到這個：

@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{169f,,__name__} and @ref{16a0,,__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{16a1,,__class__} attribute.
@end itemize

@c ======================================================================

@menu
* String Changes:: 
* 最佳化: 最佳化<18>. 

@end menu

@node String Changes,最佳化<18>,,其他語言更動<18>
@anchor{whatsnew/2 3 string-changes}@anchor{16a2}
@subsubsection String Changes



@itemize *

@item 
The @ref{349,,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{e02,,True} if `X' is a substring of `Y'.  If `X' is the empty
string, the result is always @ref{e02,,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{10a3,,find()} string method.

@item 
The @ref{16a3,,strip()}, @ref{16a4,,lstrip()}, and @ref{16a5,,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{10c6,,startswith()} and @ref{10c7,,endswith()} string methods now accept negative
numbers for the `start' and `end' parameters.

@item 
Another new string method is @ref{16a6,,zfill()}, originally a function in the
@ref{d8,,string} module.  @ref{16a6,,zfill()} pads a numeric string with zeros on the
left until it's the specified width. Note that the @code{%} operator is still more
flexible and powerful than @ref{16a6,,zfill()}.

@example
>>> '45'.zfill(4)
'0045'
>>> '12345'.zfill(4)
'12345'
>>> 'goofy'.zfill(6)
'0goofy'
@end example

（由 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{e02,,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 最佳化<18>,,String Changes,其他語言更動<18>
@anchor{whatsnew/2 3 optimizations}@anchor{16a7}
@subsubsection 最佳化



@itemize *

@item 
The creation of new-style class instances has been made much faster; they're
now faster than classic classes!

@item 
The @ref{dc3,,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{16a8,,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<3>,Pymalloc A Specialized Object Allocator,其他語言更動<18>,Python 2 3 有什麼新功能
@anchor{whatsnew/2 3 new-improved-and-deprecated-modules}@anchor{16a9}
@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{139,,zlib}-compressed data. (Contributed by Gustavo Niemeyer.)

@item 
A set of standard date/time types has been added in the new @ref{34,,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{16aa,,CC},
@geindex CFLAGS
@geindex 環境變數; CFLAGS
@ref{16ab,,CFLAGS}, @code{CPP}, 
@geindex LDFLAGS
@geindex 環境變數; LDFLAGS
@ref{16ac,,LDFLAGS}, and 
@geindex CPPFLAGS
@geindex 環境變數; CPPFLAGS
@ref{16ad,,CPPFLAGS}
environment variables, using them to override the settings in Python's
configuration (contributed by Robert Weber).

@item 
Previously the @ref{3e,,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{fef,,DocTestSuite()} function creates a
@ref{ff0,,unittest.TestSuite} object from a set of @ref{3e,,doctest} tests.

@item 
The new @code{gc.get_referents(object)} function returns a list of all the
objects referenced by `object'.

@item 
The @ref{65,,getopt} module gained a new function, @ref{16ae,,gnu_getopt()}, that
supports the same arguments as the existing @ref{16af,,getopt()} function but uses
GNU-style scanning mode. The existing @ref{16af,,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

（由 Peter Åstrand 所貢獻。）

@item 
The @ref{6a,,grp}, @ref{b7,,pwd}, and @ref{c1,,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{6b,,gzip} module can now handle files exceeding 2 GiB.

@item 
The new @ref{6d,,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{6d,,heapq} module provides @ref{16b0,,heappush()} and @ref{16b1,,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

（由 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{77,,idlelib} package.

@item 
The @ref{78,,imaplib} module now supports IMAP over SSL. (Contributed by Piers
Lauder and Tino Lange.)

@item 
The @ref{85,,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{e02,,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{92,,math} module, @code{degrees(rads)} and
@code{radians(degs)}, convert between radians and degrees.  Other functions in
the @ref{92,,math} module such as @ref{16b2,,math.sin()} and @ref{16b3,,math.cos()} have always
required input values measured in radians.  Also, an optional `base' argument
was added to @ref{16b4,,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{557,,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{16b5,,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{12c,,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{16b6,,buffer_text} attribute to @ref{e02,,True} will enable buffering.

@item 
The @code{sample(population, k)} function was added to the @ref{bd,,random}
module.  `population' is a sequence or @code{xrange} object containing the
elements of a population, and @ref{945,,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{bd,,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{bf,,readline} module also gained a number of new functions:
@ref{16b7,,get_history_item()}, @ref{16b8,,get_current_history_length()}, and
@ref{16b9,,redisplay()}.

@item 
The @code{rexec} and @code{Bastion} modules have been declared dead, and
attempts to import them will fail with a @ref{244,,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{ca,,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{cb,,signal}
but then removed again as it proved impossible to make it work reliably across
platforms.

@item 
The @ref{d1,,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{a2e,,socket.timeout} exception.

The original timeout implementation was by Tim O'Malley.  Michael Gilfix
integrated it into the Python @ref{d1,,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{d1,,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{e4,,tarfile} module  allows reading from and writing to
@code{tar}-format archive files. (Contributed by Lars Gustäbel.)

@item 
The new @ref{f2,,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{16ba,,fill()} is built on top of @ref{16bb,,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{11c8,,TextWrapper} class that actually implements
the text wrapping strategy.   Both the @ref{11c8,,TextWrapper} class and the
@ref{16bb,,wrap()} and @ref{16ba,,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{f3,,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{f3,,threading}
module. Code can call functions and use classes in @code{_threading} whether or
not threads are supported, avoiding an @ref{181,,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{f4,,time} module's @ref{1624,,strptime()} function has long been an annoyance
because it uses the platform C library's @ref{1624,,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{f5,,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{16bc,,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{c8,,shelve}
module.

Adding the mix-in as a superclass provides the full dictionary interface
whenever the class defines @ref{582,,__getitem__()}, @ref{14cc,,__setitem__()},
@ref{14cd,,__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

（由 Raymond Hettinger 所貢獻。）

@item 
The DOM implementation in @ref{128,,xml.dom.minidom} can now generate XML output
in a particular encoding by providing an optional encoding argument to the
@ref{c81,,toxml()} and @ref{c82,,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{d1,,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{62,,ftplib})
also support Unicode host names; @code{httplib} also sends HTTP @code{Host}
headers using the ACE version of the domain name.  @ref{10e,,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{da,,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<3>
@anchor{whatsnew/2 3 date-time-type}@anchor{16bd}
@subsubsection Date/Time Type


Date and time types suitable for expressing timestamps were added as the
@ref{34,,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{1fa,,date}, representing a day, month, and year;
@ref{1fb,,time}, consisting of hour, minute, and second; and @ref{4dd,,datetime},
which contains all the attributes of both @ref{1fa,,date} and @ref{1fb,,time}.
There's also a @ref{bba,,timedelta} class representing differences between two
points in time, and time zone logic is implemented by classes inheriting from
the abstract @ref{7ef,,tzinfo} class.

You can create instances of @ref{1fa,,date} and @ref{1fb,,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{16be,,today()} class method returns the
current local date.

Once created, instances of the date/time classes are all immutable. There are a
number of methods for producing formatted strings from objects:

@example
>>> import datetime
>>> now = datetime.datetime.now()
>>> now.isoformat()
'2002-12-30T21:27:03.994956'
>>> now.ctime()  # Only available on date, datetime
'Mon Dec 30 21:27:03 2002'
>>> now.strftime('%Y %d %b')
'2002 30 Dec'
@end example

The @ref{16bf,,replace()} method allows modifying one or more fields  of a
@ref{1fa,,date} or @ref{4dd,,datetime} instance, returning a new instance:

@example
>>> d = datetime.datetime.now()
>>> d
datetime.datetime(2002, 12, 30, 22, 15, 38, 827738)
>>> d.replace(year=2001, hour = 12)
datetime.datetime(2001, 12, 30, 12, 15, 38, 827738)
>>>
@end example

Instances can be compared, hashed, and converted to strings (the result is the
same as that of @ref{d1d,,isoformat()}).  @ref{1fa,,date} and @ref{4dd,,datetime}
instances can be subtracted from each other, and added to @ref{bba,,timedelta}
instances.  The largest missing feature is that there's no standard library
support for parsing strings and getting back a @ref{1fa,,date} or
@ref{4dd,,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<3>
@anchor{whatsnew/2 3 the-optparse-module}@anchor{16c0}
@subsubsection The optparse Module


The @ref{65,,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{16c1,,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{16c2,,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

更多細節請見 module 文件。

Optik was written by Greg Ward, with suggestions from the readers of the Getopt
SIG.

@c ======================================================================

@node Pymalloc A Specialized Object Allocator,建置和 C API 變更<12>,New Improved and Deprecated Modules<3>,Python 2 3 有什麼新功能
@anchor{whatsnew/2 3 pymalloc-a-specialized-object-allocator}@anchor{16c3}@anchor{whatsnew/2 3 section-pymalloc}@anchor{16c4}
@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{e5d,,PyObject_Malloc()}, it has to be freed using @ref{e5a,,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{e5b,,PyMem_Malloc()}, @ref{122d,,PyMem_Realloc()}, and @ref{1639,,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{e5d,,PyObject_Malloc()}, @ref{163a,,PyObject_Realloc()}, and @ref{e5a,,PyObject_Free()}.

@item 
To allocate and free Python objects, use the "object" family
@ref{b73,,PyObject_New}, @ref{b74,,PyObject_NewVar}, and @ref{16c5,,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 建置和 C API 變更<12>,Other Changes and Fixes<2>,Pymalloc A Specialized Object Allocator,Python 2 3 有什麼新功能
@anchor{whatsnew/2 3 build-and-c-api-changes}@anchor{16c6}
@subsection 建置和 C API 變更


Python 建置程序和 C API 的變更包括：


@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{16c7,,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{16c8,,METH_NOARGS} flag, signalling that there are no arguments,
and the argument checking can then be removed.  If compatibility with pre-2.2
versions of Python is important, the code could use @code{PyArg_ParseTuple(args,
"")} instead, but this will be slower than using @ref{16c8,,METH_NOARGS}.

@item 
@ref{3bf,,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{16c9,,METH_CLASS} or @ref{16ca,,METH_STATIC} flags in a
method's @ref{16cb,,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{60f,,__module__} and
@ref{169f,,__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>,,,建置和 C API 變更<12>
@anchor{whatsnew/2 3 port-specific-changes}@anchor{16cc}
@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{5d,,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,建置和 C API 變更<12>,Python 2 3 有什麼新功能
@anchor{whatsnew/2 3 other-changes-and-fixes}@anchor{16cd}@anchor{whatsnew/2 3 section-other}@anchor{16a8}
@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{16ce,,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{16cf,,-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{18c,,-O}.

C extensions that access the @ref{9a8,,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{9a8,,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,致謝<5>,Other Changes and Fixes<2>,Python 2 3 有什麼新功能
@anchor{whatsnew/2 3 porting-to-python-2-3}@anchor{16d0}
@subsection Porting to Python 2.3


This section lists previously described changes that may require changes to your
code:


@itemize *

@item 
@ref{bb9,,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{19b,,int()} type constructor will now return a long integer instead of
raising an @ref{a78,,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{167e,,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{651,,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{1ae,,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 致謝<5>,,Porting to Python 2 3,Python 2 3 有什麼新功能
@anchor{whatsnew/2 3 acknowledgements}@anchor{16d1}@anchor{whatsnew/2 3 acks}@anchor{16d2}
@subsection 致謝


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 Python 2 2 有什麼新功能,Python 2 1 有什麼新功能,Python 2 3 有什麼新功能,Python 有什麼新功能？
@anchor{whatsnew/2 2 doc}@anchor{16d3}@anchor{whatsnew/2 2 translation-repo}@anchor{16d4}@anchor{whatsnew/2 2 what-s-new-in-python-2-2}@anchor{16d5}
@section Python 2.2 有什麼新功能


@*作者: 
A.M. Kuchling


@c $Id: whatsnew22.tex 37315 2004-09-10 19:33:00Z akuchling $

@menu
* 簡介:: 
* PEPs 252 and 253; Type and Class Changes: PEPs 252 and 253 Type and Class Changes. 
* PEP 234：疊代器:: 
* PEP 255：簡單產生器: PEP 255：簡單產生器<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 變更:: 
* PEP 227; Nested Scopes: PEP 227 Nested Scopes. 
* New and Improved Modules: New and Improved Modules<3>. 
* 直譯器的變更與修正:: 
* 其他改動與修正:: 
* 致謝: 致謝<6>. 

@end menu

@node 簡介,PEPs 252 and 253 Type and Class Changes,,Python 2 2 有什麼新功能
@anchor{whatsnew/2 2 introduction}@anchor{16d6}
@subsection 簡介


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：疊代器,簡介,Python 2 2 有什麼新功能
@anchor{whatsnew/2 2 peps-252-and-253-type-and-class-changes}@anchor{16d7}
@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{16d8,,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{6f3,,__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{16d9,,相關連結}, "Related Links", for
further sources of information about Python 2.2's new object model.

@menu
* 舊的和新的類別:: 
* 描述器:: 
* Multiple Inheritance; The Diamond Rule: Multiple Inheritance The Diamond Rule. 
* Attribute Access:: 
* 相關連結:: 

@end menu

@node 舊的和新的類別,描述器,,PEPs 252 and 253 Type and Class Changes
@anchor{whatsnew/2 2 old-and-new-classes}@anchor{16da}
@subsubsection 舊的和新的類別


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{c75,,object}, the base class for all built-in types, has also been
added so if no built-in type is suitable, you can just subclass
@ref{c75,,object}:

@example
class C(object):
    def __init__ (self):
        ...
    ...
@end example

This means that @ref{14d8,,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{c75,,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{19b,,int()},
@ref{196,,float()}, and @ref{169,,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{183,,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 描述器,Multiple Inheritance The Diamond Rule,舊的和新的類別,PEPs 252 and 253 Type and Class Changes
@anchor{whatsnew/2 2 descriptors}@anchor{16db}
@subsubsection 描述器


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{776,,__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{1261,,__name__} 是屬性的名稱。

@item 
@ref{b18,,__doc__} 是屬性的文件字串 (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{16dc,,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{451,,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,描述器,PEPs 252 and 253 Type and Class Changes
@anchor{whatsnew/2 2 multiple-inheritance-the-diamond-rule}@anchor{16dd}
@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{1a6,,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{1a6,,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,相關連結,Multiple Inheritance The Diamond Rule,PEPs 252 and 253 Type and Class Changes
@anchor{whatsnew/2 2 attribute-access}@anchor{16de}
@subsubsection Attribute Access


A fair number of sophisticated Python classes define hooks for attribute access
using @ref{6f3,,__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{dc6,,__getattribute__()} is `always' called whenever any attribute is
accessed, while the old @ref{6f3,,__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{776,,__dict__}. @ref{6f3,,__getattr__()} methods also end up being called by Python
when it checks for other methods such as @ref{828,,__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{4ae,,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{776,,__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{16df,,__slots__} class attribute. Python
objects are usually very dynamic; at any time it's possible to define a new
attribute on an instance by just doing @code{obj.new_attr=1}.   A new-style class
can define a class attribute named @ref{16df,,__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{5e8,,AttributeError} on the attempt to assign to an
attribute not listed in @ref{16df,,__slots__}.

@node 相關連結,,Attribute Access,PEPs 252 and 253 Type and Class Changes
@anchor{whatsnew/2 2 related-links}@anchor{16e0}@anchor{whatsnew/2 2 sect-rellinks}@anchor{16d9}
@subsubsection 相關連結


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{16e1,,描述器 (Descriptor) 指南} 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：疊代器,PEP 255：簡單產生器<2>,PEPs 252 and 253 Type and Class Changes,Python 2 2 有什麼新功能
@anchor{whatsnew/2 2 pep-234-iterators}@anchor{16e2}
@subsection PEP 234：疊代器


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{582,,__getitem__()} method that looks something like this:

@example
def __getitem__(self, index):
    return <next item>
@end example

@ref{582,,__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{348,,for} loops.
Consider some file-like object that wants to be looped over; the `index'
parameter is essentially meaningless, as the class probably assumes that a
series of @ref{582,,__getitem__()} calls will be made with `index' incrementing by
one each time.  In other words, the presence of the @ref{582,,__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{582,,__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{16e3,,tp_iter}
function in order to return an iterator, and extension types that want to behave
as iterators can define a @ref{16e4,,tp_iternext} function.

So, after all this, what do iterators actually do?  They have one required
method, @ref{9d1,,next()}, which takes no arguments and returns the next value.  When
there are no more values to be returned, calling @ref{9d1,,next()} should raise the
@ref{df0,,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{348,,for} statement no longer expects a sequence; it
expects something for which @ref{9d0,,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{16e3,,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{9d0,,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{349,,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{bf,,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{9d1,,next()} method.


@subsubheading 也參考



@table @asis

@geindex Python Enhancement Proposals; PEP 234

@item PEP 234@footnote{https://peps.python.org/pep-0234/} - 疊代器

由 Ka-Ping Yee 和 GvR 撰寫；由 Python Labs 團隊實作，主要為 GvR 和 Tim Peters 所貢獻。
@end table


@c ======================================================================

@node PEP 255：簡單產生器<2>,PEP 237 Unifying Long Integers and Integers<2>,PEP 234：疊代器,Python 2 2 有什麼新功能
@anchor{whatsnew/2 2 pep-255-simple-generators}@anchor{16e5}
@subsection PEP 255：簡單產生器


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{1af,,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{bb9,,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{bb9,,yield} statement, the generator outputs the value of @code{i},
similar to a @ref{1af,,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{8f0,,try}...@ref{1b0,,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{1af,,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{df0,,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{9d1,,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{181,,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/} - 簡單產生器

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：簡單產生器<2>,Python 2 2 有什麼新功能
@anchor{whatsnew/2 2 pep-237-unifying-long-integers-and-integers}@anchor{16e6}
@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{198,,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{a78,,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{f3f,,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 變更,PEP 237 Unifying Long Integers and Integers<2>,Python 2 2 有什麼新功能
@anchor{whatsnew/2 2 pep-238-changing-the-division-operator}@anchor{16e7}
@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{108b,,__truediv__()} and @ref{16e8,,__floordiv__()}
to overload the two division operators.  At the C level, there are also slots in
the @ref{1615,,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 變更,PEP 227 Nested Scopes,PEP 238 Changing the Division Operator,Python 2 2 有什麼新功能
@anchor{whatsnew/2 2 unicode-changes}@anchor{16e9}
@subsection Unicode 變更


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{2eb,,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{139,,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/} - 支援 'wide' Unicode 字元

由 Paul Prescod 撰寫。
@end table


@c ======================================================================

@node PEP 227 Nested Scopes,New and Improved Modules<3>,Unicode 變更,Python 2 2 有什麼新功能
@anchor{whatsnew/2 2 pep-227-nested-scopes}@anchor{16ea}
@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{450,,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{149e,,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{164f,,def}, @ref{14d8,,class}, or @ref{7f1,,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{149e,,lambda} expressions with free variables, the compiler
will flag this by raising a @ref{18e,,SyntaxError} exception.

To make the preceding explanation a bit clearer, here's an example:

@example
x = 1
def f():
    # 下一行為語法錯誤
    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>,直譯器的變更與修正,PEP 227 Nested Scopes,Python 2 2 有什麼新功能
@anchor{whatsnew/2 2 new-and-improved-modules}@anchor{16eb}
@subsection New and Improved Modules



@itemize *

@item 
The @ref{134,,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{135,,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{6e,,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{16ec,,tm_year}. The enhanced functions include
@ref{26d,,stat()}, @ref{f87,,fstat()}, @ref{12fd,,statvfs()}, and @ref{f88,,fstatvfs()} in the
@ref{a5,,os} module, and @ref{16ed,,localtime()}, @ref{13c1,,gmtime()}, and @ref{1624,,strptime()} in
the @ref{f4,,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{d1,,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{db,,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{acb,,help()} that uses the @ref{ba,,pydoc} module introduced in Python 2.1 to
provide interactive help. @code{help(object)} displays any available help text
about `object'.  @ref{acb,,help()} with no argument puts you in an online help
utility, where you can enter the names of functions, classes, or modules to read
their help text. (Contributed by Guido van Rossum, using Ka-Ping Yee's
@ref{ba,,pydoc} module.)

@item 
Various bugfixes and performance improvements have been made to the SRE engine
underlying the @ref{be,,re} module.  For example, the @ref{59d,,re.sub()} and
@ref{59c,,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{16ee,,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{cf,,smtplib} module now supports 
@geindex RFC; RFC 2487
RFC 2487@footnote{https://datatracker.ietf.org/doc/html/rfc2487.html}, "Secure SMTP over TLS", so
it's now possible to encrypt the SMTP traffic between a Python program and the
mail transport agent being handed a message.  @ref{cf,,smtplib} also supports SMTP
authentication.  (Contributed by Gerhard Häring.)

@item 
The @ref{78,,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{3f,,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{3b,,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{d8,,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{16ef,,MimeTypes} class, which takes a list of
filenames to be parsed.  (Contributed by Fred L. Drake, Jr.)

@item 
A @ref{135a,,Timer} class was added to the @ref{f3,,threading} module that allows
scheduling an activity to happen at some future time.  (Contributed by Itamar
Shtull-Trauring.)
@end itemize

@c ======================================================================

@node 直譯器的變更與修正,其他改動與修正,New and Improved Modules<3>,Python 2 2 有什麼新功能
@anchor{whatsnew/2 2 interpreter-changes-and-fixes}@anchor{16f0}
@subsection 直譯器的變更與修正


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{16f1,,PyEval_SetProfile()} and @ref{65b,,PyEval_SetTrace()}. The existing
@ref{16f2,,sys.setprofile()} and @ref{2e1,,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{16f3,,PyInterpreterState_Head()} and
@ref{16f4,,PyInterpreterState_Next()} let a caller walk through all the existing
interpreter objects; @ref{16f5,,PyInterpreterState_ThreadHead()} and
@ref{16f6,,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 
將 @code{Py_TPFLAGS_GC} 重新命名為 @ref{978,,Py_TPFLAGS_HAVE_GC}。

@item 

@table @asis

@item Use @ref{c90,,PyObject_GC_New()} or @ref{c91,,PyObject_GC_NewVar()} to allocate

objects, and @ref{16f7,,PyObject_GC_Del()} to deallocate them.
@end table

@item 
Rename @code{PyObject_GC_Init()} to @ref{16f8,,PyObject_GC_Track()} and
@code{PyObject_GC_Fini()} to @ref{16f9,,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{3bf,,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{16fa,,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{5d7,,PyObject}* variables that will be
filled in with argument values.

@item 
Two new flags @ref{16c8,,METH_NOARGS} and @ref{16fb,,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{16fc,,METH_VARARGS}.  Also, the old
@code{METH_OLDARGS} style of writing C methods is  now officially deprecated.

@item 
Two new wrapper functions, @ref{16fd,,PyOS_snprintf()} and @ref{16fe,,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{16ff,,_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 其他改動與修正,致謝<6>,直譯器的變更與修正,Python 2 2 有什麼新功能
@anchor{whatsnew/2 2 other-changes-and-fixes}@anchor{1700}
@subsection 其他改動與修正


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.

一些較顯著的變更為：


@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{198,,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{1701,,ReferenceError} exception has therefore moved from the @ref{11a,,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{4ac,,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{349,,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{1702,,sys.getdlopenflags()} and @ref{1320,,sys.setdlopenflags()} functions.
(Contributed by Bram Stolk.)

@item 
The @ref{1a4,,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{198,,TypeError} exception.
@end itemize

@c ======================================================================

@node 致謝<6>,,其他改動與修正,Python 2 2 有什麼新功能
@anchor{whatsnew/2 2 acknowledgements}@anchor{1703}
@subsection 致謝


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 Python 2 1 有什麼新功能,Python 2 0 有什麼新功能,Python 2 2 有什麼新功能,Python 有什麼新功能？
@anchor{whatsnew/2 1 doc}@anchor{1704}@anchor{whatsnew/2 1 translation-repo}@anchor{1705}@anchor{whatsnew/2 1 what-s-new-in-python-2-1}@anchor{1706}
@section Python 2.1 有什麼新功能


@*作者: 
A.M. Kuchling


@c $Id: whatsnew21.tex 50964 2006-07-30 03:03:43Z fred.drake $

@menu
* 簡介: 簡介<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<3>. 
* 致謝: 致謝<7>. 

@end menu

@node 簡介<2>,PEP 227 Nested Scopes<2>,,Python 2 1 有什麼新功能
@anchor{whatsnew/2 1 introduction}@anchor{1707}
@subsection 簡介


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,簡介<2>,Python 2 1 有什麼新功能
@anchor{whatsnew/2 1 pep-227-nested-scopes}@anchor{1708}
@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{450,,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{149e,,lambda} expression clumsier, and this was a problem in practice.
In code which uses @ref{149e,,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{164f,,def}, @ref{14d8,,class}, or @ref{7f1,,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{149e,,lambda} expressions with free variables, the compiler
will flag this by raising a @ref{18e,,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>,Python 2 1 有什麼新功能
@anchor{whatsnew/2 1 pep-236-future-directives}@anchor{1709}
@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{7f1,,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,Python 2 1 有什麼新功能
@anchor{whatsnew/2 1 pep-207-rich-comparisons}@anchor{170a}
@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

操作

@tab

方法名稱

@item

@code{<}

@tab

@ref{14a1,,__lt__()}

@item

@code{<=}

@tab

@ref{150b,,__le__()}

@item

@code{>}

@tab

@ref{150c,,__gt__()}

@item

@code{>=}

@tab

@ref{150d,,__ge__()}

@item

@code{==}

@tab

@ref{ce9,,__eq__()}

@item

@code{!=}

@tab

@ref{170b,,__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,Python 2 1 有什麼新功能
@anchor{whatsnew/2 1 pep-230-warning-framework}@anchor{170c}
@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{118,,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{170d,,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{be,,re} module right
now.  The warning can be suppressed by calling

@example
import warnings
warnings.filterwarnings(action = 'ignore',
                        message='.*regex module is deprecated',
                        category=DeprecationWarning,
                        module = '__main__')
@end example

This adds a filter that will apply only to warnings of the class
@ref{1a3,,DeprecationWarning} triggered in the @ref{1,,__main__} module, and applies
a regular expression to only match the message about the @code{regex} module
being deprecated, and will cause such warnings to be ignored.  Warnings can also
be printed only once, printed every time the offending code is executed, or
turned into exceptions that will cause the program to stop (unless the
exceptions are caught in the usual way, of course).

Functions were also added to Python's C API for issuing warnings; refer to PEP
230 or to Python's API documentation for the details.


@subsubheading 也參考



@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,Python 2 1 有什麼新功能
@anchor{whatsnew/2 1 pep-229-new-build-system}@anchor{170e}
@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,Python 2 1 有什麼新功能
@anchor{whatsnew/2 1 pep-205-weak-references}@anchor{170f}
@subsection PEP 205: Weak References


Weak references, available through the @ref{11a,,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{11a,,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,Python 2 1 有什麼新功能
@anchor{whatsnew/2 1 pep-232-function-attributes}@anchor{1710}
@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{13da,,__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{14d3,,__dict__}. Unlike the @ref{e52,,__dict__} attribute of class instances, in
functions you can actually assign a new dictionary to @ref{14d3,,__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,Python 2 1 有什麼新功能
@anchor{whatsnew/2 1 pep-235-importing-modules-on-case-insensitive-platforms}@anchor{1711}
@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{7f1,,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{653,,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{b4c,,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,Python 2 1 有什麼新功能
@anchor{whatsnew/2 1 pep-217-interactive-display-hook}@anchor{1712}
@subsection PEP 217: Interactive Display Hook


When using the Python interpreter interactively, the output of commands is
displayed using the built-in @ref{1c1,,repr()} function. In Python 2.1, the variable
@ref{1713,,sys.displayhook()} can be set to a callable object which will be called
instead of @ref{1c1,,repr()}. For example, you can set it to a special
pretty-printing function:

@example
>>> # 建立一個遞迴的資料結構
... L = [1,2,3]
>>> L.append(L)
>>> L # 顯示 Python 的預設輸出
[1, 2, 3, [...]]
>>> # 使用 pprint.pprint() 作為顯示函式
... 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

由 Moshe Zadka 撰寫與實作。
@end table


@c ======================================================================

@node PEP 208 New Coercion Model,PEP 241 Metadata in Python Packages,PEP 217 Interactive Display Hook,Python 2 1 有什麼新功能
@anchor{whatsnew/2 1 pep-208-new-coercion-model}@anchor{1714}
@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{198,,TypeError} will be raised.  Numeric methods written in Python can also
return @code{Py_NotImplemented}, causing the interpreter to act as if the method
did not exist (perhaps raising a @ref{198,,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,Python 2 1 有什麼新功能
@anchor{whatsnew/2 1 pep-241-metadata-in-python-packages}@anchor{1715}
@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<3>,PEP 241 Metadata in Python Packages,Python 2 1 有什麼新功能
@anchor{whatsnew/2 1 new-and-improved-modules}@anchor{1716}
@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{3e,,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{3b,,difflib} module contains a class, @ref{1214,,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{31,,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{126,,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{a05,,sys.excepthook()} can be set to a callable object.  When an exception isn't
caught by any @ref{8f0,,try}...@ref{1ab,,except} blocks, the exception will be
passed to @ref{a05,,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{f4,,time} module, such as @ref{13e8,,asctime()} and
@ref{16ed,,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{62,,ftplib} module now defaults to retrieving files in passive mode,
because passive mode is more likely to work from behind a firewall.  This
request came from the Debian bug tracking system, since other Debian packages
use @ref{62,,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{d1,,socket} module,
contributed by Grant Edwards.

@item 
The @ref{b5,,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{8e8,,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<3>,致謝<7>,New and Improved Modules<4>,Python 2 1 有什麼新功能
@anchor{whatsnew/2 1 other-changes-and-fixes}@anchor{1717}
@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{1718,,PyMem_New}, it has to be freed
using @ref{1719,,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{bf,,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{171a,,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{df,,sys} or @ref{d8,,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{1c1,,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{3da,,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 致謝<7>,,Other Changes and Fixes<3>,Python 2 1 有什麼新功能
@anchor{whatsnew/2 1 acknowledgements}@anchor{171b}
@subsection 致謝


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 Python 2 0 有什麼新功能,Changelog（更動日誌）,Python 2 1 有什麼新功能,Python 有什麼新功能？
@anchor{whatsnew/2 0 doc}@anchor{171c}@anchor{whatsnew/2 0 translation-repo}@anchor{171d}@anchor{whatsnew/2 0 what-s-new-in-python-2-0}@anchor{171e}
@section Python 2.0 有什麼新功能


@*作者: 
A.M. Kuchling 和 Moshe Zadka


@c $Id: whatsnew20.tex 50964 2006-07-30 03:03:43Z fred.drake $

@menu
* 簡介: 簡介<3>. 
* What About Python 1.6?: What About Python 1 6?. 
* New Development Process:: 
* Unicode: Unicode<2>. 
* 串列綜合運算（List Comprehension）:: 
* 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 模組:: 
* 模組變更:: 
* 新增模組: 新增模組<6>. 
* IDLE Improvements:: 
* Deleted and Deprecated Modules:: 
* 致謝: 致謝<8>. 

@end menu

@node 簡介<3>,What About Python 1 6?,,Python 2 0 有什麼新功能
@anchor{whatsnew/2 0 introduction}@anchor{171f}
@subsection 簡介


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,簡介<3>,Python 2 0 有什麼新功能
@anchor{whatsnew/2 0 what-about-python-1-6}@anchor{1720}
@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?,Python 2 0 有什麼新功能
@anchor{whatsnew/2 0 new-development-process}@anchor{1721}
@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 Comprehension）,New Development Process,Python 2 0 有什麼新功能
@anchor{whatsnew/2 0 unicode}@anchor{1722}
@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{10b,,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{be,,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 Comprehension）,Augmented Assignment,Unicode<2>,Python 2 0 有什麼新功能
@anchor{whatsnew/2 0 list-comprehensions}@anchor{1723}
@subsection 串列綜合運算（List Comprehension）


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{19f,,map()} and @ref{a5d,,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{149e,,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
# 語法錯誤
[ x,y for x in seq1 for y in seq2]
# 正確
[ (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 Comprehension）,Python 2 0 有什麼新功能
@anchor{whatsnew/2 0 augmented-assignment}@anchor{1724}
@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,Python 2 0 有什麼新功能
@anchor{whatsnew/2 0 string-methods}@anchor{1725}
@subsection String Methods


Until now string-manipulation functionality was in the @ref{d8,,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{d8,,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{d8,,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,Python 2 0 有什麼新功能
@anchor{whatsnew/2 0 garbage-collection-of-cycles}@anchor{1726}
@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{64,,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,Python 2 0 有什麼新功能
@anchor{whatsnew/2 0 other-core-changes}@anchor{1727}
@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{1728}
@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{1c1,,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{169,,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{349,,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{1729,,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{450,,NameError} exception when code refers to a local variable before the
variable has been assigned a value.  For example, the following code raises an
exception on the @code{print} statement in both 1.5.2 and 2.0; in 1.5.2 a
@ref{450,,NameError} exception is raised, while 2.0 raises a new
@ref{172a,,UnboundLocalError} exception. @ref{172a,,UnboundLocalError} is a subclass of
@ref{450,,NameError}, so any existing code that expects @ref{450,,NameError} to be
raised should still work.

@example
def f():
    print "i=",i
    i = i + 1
f()
@end example

Two new exceptions, @ref{75e,,TabError} and @ref{9a4,,IndentationError}, have been
introduced.  They're both subclasses of @ref{18e,,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{172b}
@subsubsection Changes to Built-in Functions


A new built-in, @code{zip(seq1, seq2, ...)}, has been added.  @ref{1a0,,zip()}
returns a list of tuples where each tuple contains the i-th element from each of
the argument sequences.  The difference between @ref{1a0,,zip()} and @code{map(None,
seq1, seq2)} is that @ref{19f,,map()} pads the sequences with @code{None} if the
sequences aren't all of the same length, while @ref{1a0,,zip()} truncates the
returned list to the length of the shortest argument sequence.

The @ref{19b,,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{198,,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{df,,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{6e4,,sys.getrecursionlimit()} and
@ref{6e3,,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,Python 2 0 有什麼新功能
@anchor{whatsnew/2 0 porting-to-2-0}@anchor{172c}
@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{8d4,,append()} and @ref{1399,,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{198,,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{3bf,,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{d1,,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{172d,,socket.connect_ex} and @ref{172e,,socket.bind}
are similarly easy-going.  2.0alpha1 tightened these functions up, but because
the documentation actually used the erroneous multiple argument form, many
people wrote code which would break with the stricter checking.  GvR backed out
the changes in the face of public reaction, so for the @ref{d1,,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{5e8,,AttributeError} and @ref{450,,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{198,,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{169,,str()} of a long
integer no longer has a trailing 'L' character, though @ref{1c1,,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{1c1,,repr()} of a float now uses a different formatting precision
than @ref{169,,str()}.  @ref{1c1,,repr()} uses @code{%.17g} format string for C's
@code{sprintf()}, while @ref{169,,str()} uses @code{%.12g} as before.  The effect is that
@ref{1c1,,repr()} may occasionally show more decimal places than  @ref{169,,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,Python 2 0 有什麼新功能
@anchor{whatsnew/2 0 extending-embedding-changes}@anchor{172f}
@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{2ad,,isinstance()} and @ref{9bd,,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{603,,PyModule_AddObject()},
@ref{1730,,PyModule_AddIntConstant()}, and @ref{1731,,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{1732,,PyOS_getsig()} gets
a signal handler and @ref{1733,,PyOS_setsig()} will set a new handler.

@c ======================================================================

@node Distutils Making Modules Easy to Install,XML 模組,Extending/Embedding Changes,Python 2 0 有什麼新功能
@anchor{whatsnew/2 0 distutils-making-modules-easy-to-install}@anchor{1734}
@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 模組,模組變更,Distutils Making Modules Easy to Install,Python 2 0 有什麼新功能
@anchor{whatsnew/2 0 xml-modules}@anchor{1735}
@subsection XML 模組


Python 1.5.2 included a simple XML parser in the form of the @code{xmllib}
module, contributed by Sjoerd Mullender.  Since 1.5.2's release, two different
interfaces for processing XML have become common: SAX2 (version 2 of the Simple
API for XML) provides an event-driven interface with some similarities to
@code{xmllib}, and the DOM (Document Object Model) provides a tree-based
interface, transforming an XML document into a tree of nodes that can be
traversed and modified.  Python 2.0 includes a SAX2 interface and a stripped-down
DOM interface as part of the @ref{126,,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 支援:: 
* DOM 支援:: 
* Relationship to PyXML:: 

@end menu

@node SAX2 支援,DOM 支援,,XML 模組
@anchor{whatsnew/2 0 sax2-support}@anchor{1736}
@subsubsection SAX2 支援


SAX defines an event-driven interface for parsing XML.  To use SAX, you must
write a SAX handler class.  Handler classes inherit from various classes
provided by SAX, and override various methods that will then be called by the
XML parser.  For example, the @ref{1737,,startElement()} and @ref{1738,,endElement()}
methods are called for every starting and end tag encountered by the parser, the
@ref{1739,,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 支援,Relationship to PyXML,SAX2 支援,XML 模組
@anchor{whatsnew/2 0 dom-support}@anchor{173a}
@subsubsection DOM 支援


The Document Object Model is a tree-based representation for an XML document.  A
top-level @code{Document} instance is the root of the tree, and has a single
child which is the top-level @code{Element} instance. This @code{Element}
has children nodes representing character data and any sub-elements, which may
have further children of their own, and so forth.  Using the DOM you can
traverse the resulting tree any way you like, access element and attribute
values, insert and delete nodes, and convert the tree back into XML.

The DOM is useful for modifying XML documents, because you can create a DOM
tree, modify it by adding new nodes or rearranging subtrees, and then produce a
new XML document as output.  You can also construct a DOM tree manually and
convert it to XML, which can be a more flexible way of producing XML output than
simply writing @code{<tag1>}...@code{</tag1>} to a file.

The DOM implementation included with Python lives in the @ref{128,,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 支援,XML 模組
@anchor{whatsnew/2 0 relationship-to-pyxml}@anchor{173b}
@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{126,,xml} package.

The answer is that Python 2.0's @ref{126,,xml} package isn't compatible with PyXML,
but can be made compatible by installing a recent version PyXML.  Many
applications can get by with the XML support that is included with Python 2.0,
but more complicated applications will require that the full PyXML package will
be installed.  When installed, PyXML versions 0.6.0 or greater will replace the
@ref{126,,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 模組變更,新增模組<6>,XML 模組,Python 2 0 有什麼新功能
@anchor{whatsnew/2 0 module-changes}@anchor{173c}
@subsection 模組變更


Lots of improvements and bugfixes were made to Python's extensive standard
library; some of the affected modules include @ref{bf,,readline},
@ref{26,,ConfigParser}, @code{cgi}, @ref{15,,calendar}, @ref{b2,,posix}, @ref{bf,,readline},
@code{xmllib}, @code{aifc}, @code{chunk}, @ref{119,,wave}, @ref{bd,,random}, @ref{c8,,shelve},
and @code{nntplib}.  Consult the CVS logs for the exact patch-by-patch details.

Brian Gallew contributed OpenSSL support for the @ref{d1,,socket} module.  OpenSSL
is an implementation of the Secure Socket Layer, which encrypts the data being
sent over a socket.  When compiling Python, you can edit @code{Modules/Setup}
to include SSL support, which adds an additional function to the @ref{d1,,socket}
module: @code{socket.ssl(socket, keyfile, certfile)}, which takes a socket
object and returns an SSL socket.  The @ref{72,,httplib} and @ref{10e,,urllib} modules
were also changed to support @code{https://} URLs, though no one has implemented
FTP or SMTP over SSL.

The @ref{72,,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{2f,,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{be,,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 新增模組<6>,IDLE Improvements,模組變更,Python 2 0 有什麼新功能
@anchor{whatsnew/2 0 new-modules}@anchor{173d}
@subsection 新增模組


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 @ref{d,,atexit} module instead, importing @ref{d,,atexit} and
calling @ref{a75,,atexit.register()} with  the function to be called on exit.
(Contributed by Skip Montanaro.)

@item 
@ref{1c,,codecs}, @code{encodings}, @ref{10b,,unicodedata}:  Added as part of the new
Unicode support.

@item 
@ref{5e,,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{67,,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{be,,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{113,,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{e3,,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{11b,,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{10e,,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{11c,,_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{137,,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{6b,,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,新增模組<6>,Python 2 0 有什麼新功能
@anchor{whatsnew/2 0 idle-improvements}@anchor{173e}
@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,致謝<8>,IDLE Improvements,Python 2 0 有什麼新功能
@anchor{whatsnew/2 0 deleted-and-deprecated-modules}@anchor{173f}
@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 致謝<8>,,Deleted and Deprecated Modules,Python 2 0 有什麼新功能
@anchor{whatsnew/2 0 acknowledgements}@anchor{1740}
@subsection 致謝


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（更動日誌）」是從 Misc/NEWS.d@footnote{https://github.com/python/cpython/tree/3.14/Misc/NEWS.d} 目錄樹內容檔案建置@footnote{https://pypi.org/project/blurb/}的一個 HTML 版本，其中包含了 Python 目前版本中的`所有'重要變更。

@node Changelog（更動日誌）,,Python 2 0 有什麼新功能,Python 有什麼新功能？
@anchor{whatsnew/changelog doc}@anchor{1741}@anchor{whatsnew/changelog changelog}@anchor{142}@anchor{whatsnew/changelog id1}@anchor{1742}@anchor{whatsnew/changelog translation-repo}@anchor{1743}
@section Changelog（更動日誌）


@menu
* Python next:: 
* Python 3.14.0 final: Python 3 14 0 final. 
* Python 3.14.0 release candidate 3: Python 3 14 0 release candidate 3. 
* Python 3.14.0 release candidate 2: Python 3 14 0 release candidate 2. 
* Python 3.14.0 release candidate 1: Python 3 14 0 release candidate 1. 
* Python 3.14.0 beta 4: Python 3 14 0 beta 4. 
* Python 3.14.0 beta 3: Python 3 14 0 beta 3. 
* Python 3.14.0 beta 2: Python 3 14 0 beta 2. 
* 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 14 0 final,,Changelog（更動日誌）
@anchor{whatsnew/changelog python-next}@anchor{1744}
@subsection Python next


`Release date: XXXX-XX-XX'

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

@end menu

@node Windows,Tools/Demos,,Python next
@anchor{whatsnew/changelog windows}@anchor{1745}
@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.
@end itemize

@node Tools/Demos,Tests,Windows,Python next
@anchor{whatsnew/changelog tools-demos}@anchor{1746}
@subsubsection Tools/Demos



@itemize -

@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-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-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.
@end itemize

@node Tests,Security,Tools/Demos,Python next
@anchor{whatsnew/changelog tests}@anchor{1747}
@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{10c,,unittest} which is run by it with
redirected output will output in color.

@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.
@end itemize

@node Security,Library,Tests,Python next
@anchor{whatsnew/changelog security}@anchor{1748}
@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-139283@footnote{https://github.com/python/cpython/issues/139283}: @ref{d4,,sqlite3}: correctly handle maximum number of rows to
fetch in @ref{1749,,Cursor.fetchmany} and reject
negative values for @ref{174a,,Cursor.arraysize}.
Patch by Bénédikt Tran.

@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{a6e,,html.parser.HTMLParser}.

@item 
gh-136065@footnote{https://github.com/python/cpython/issues/136065}: Fix quadratic complexity in @ref{15d0,,os.path.expandvars()}.
@end itemize

@node Library,IDLE<3>,Security,Python next
@anchor{whatsnew/changelog library}@anchor{174b}
@subsubsection Library



@itemize -

@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-120057@footnote{https://github.com/python/cpython/issues/120057}: Add @ref{258,,os.reload_environ()} to @code{os.__all__}.

@item 
gh-140228@footnote{https://github.com/python/cpython/issues/140228}: Avoid making unnecessary filesystem calls for frozen modules in
@ref{89,,linecache} when the global module cache is not present.

@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-140634@footnote{https://github.com/python/cpython/issues/140634}: Fix a reference counting bug in
@code{os.sched_param.__reduce__()}.

@item 
gh-140633@footnote{https://github.com/python/cpython/issues/140633}: Ignore @ref{5e8,,AttributeError} when setting a module's
@code{__file__} attribute when loading an extension module packaged as Apple
Framework.

@item 
gh-140593@footnote{https://github.com/python/cpython/issues/140593}: @ref{12c,,xml.parsers.expat}: Fix a memory leak that could affect
users with @ref{174c,,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{1018,,io.RawIOBase.read()}, validate that the count of
bytes returned by @ref{1019,,io.RawIOBase.readinto()} is valid (inside the
provided buffer).

@item 
gh-138162@footnote{https://github.com/python/cpython/issues/138162}: Fix @ref{14f6,,logging.LoggerAdapter} with @code{merge_extra=True}
and without the `extra' argument.

@item 
gh-138774@footnote{https://github.com/python/cpython/issues/138774}: @ref{ad9,,ast.unparse()} now generates full source code when
handling @ref{174d,,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{4b9,,array.array} when creating arrays
from an empty @ref{169,,str} and the @code{u} type code.

@item 
gh-140272@footnote{https://github.com/python/cpython/issues/140272}: Fix memory leak in the @code{clear()} method of the
@ref{37,,dbm.gnu} database.

@item 
gh-140041@footnote{https://github.com/python/cpython/issues/140041}: Fix import of @ref{2e,,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{6e,,hmac} when it was using the
hacl-star backend. Discovered by @code{@@ashm-dev} using AddressSanitizer.

@item 
gh-139905@footnote{https://github.com/python/cpython/issues/139905}: Add suggestion to error message for @ref{174e,,typing.Generic}
subclasses when @code{cls.__parameters__} is missing due to a parent class
failing to call @ref{83c,,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{174f,,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{e0c,,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{76,,http.server}: fix default handling of HTTP/0.9 requests in
@ref{12cc,,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-63161@footnote{https://github.com/python/cpython/issues/63161}: Fix @ref{1750,,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-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-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-139289@footnote{https://github.com/python/cpython/issues/139289}: Do a real lazy-import on @ref{c2,,rlcompleter} in @ref{aa,,pdb} and
restore the existing completer after importing @ref{c2,,rlcompleter}.

@item 
gh-139210@footnote{https://github.com/python/cpython/issues/139210}: Fix use-after-free when reporting unknown event in
@ref{574,,xml.etree.ElementTree.iterparse()}. Patch by Ken Jin.

@item 
gh-138860@footnote{https://github.com/python/cpython/issues/138860}: Lazy import @ref{c2,,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{1751,,concurrent.interpreters.create()}
when the process is out of memory.

@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{ba,,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-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{f2,,textwrap}.

@item 
gh-139001@footnote{https://github.com/python/cpython/issues/139001}: Fix race condition in @ref{266,,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-138993@footnote{https://github.com/python/cpython/issues/138993}: Dedent @ref{1752,,credits} text.

@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-130567@footnote{https://github.com/python/cpython/issues/130567}: Fix possible crash in @ref{1753,,locale.strxfrm()} due to a platform
bug on macOS.

@item 
gh-138859@footnote{https://github.com/python/cpython/issues/138859}: Fix generic type parameterization raising a @ref{198,,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{1754,,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-138779@footnote{https://github.com/python/cpython/issues/138779}: Support device numbers larger than @code{2**63-1} for the
@ref{1755,,st_rdev} field of the @ref{16b5,,os.stat_result}
structure.

@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{113,,urllib.robotparser} module. No longer ignore trailing @code{?}.
Distinguish raw special characters @code{?}, @code{=} and @code{&} from the
percent-encoded ones.

@item 
gh-111788@footnote{https://github.com/python/cpython/issues/111788}: Fix parsing errors in the @ref{113,,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{1756,,zoneinfo.reset_tzpath()} will now convert any
@ref{e46,,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 @ref{e46,,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-138008@footnote{https://github.com/python/cpython/issues/138008}: Fix segmentation faults in the @ref{2e,,ctypes} module due to
invalid @ref{1757,,argtypes}. Patch by Dung Nguyen.

@item 
gh-60462@footnote{https://github.com/python/cpython/issues/60462}: Fix @ref{1753,,locale.strxfrm()} on Solaris (and possibly other
platforms).

@item 
gh-138239@footnote{https://github.com/python/cpython/issues/138239}: The REPL now highlights @ref{665,,type} as a soft keyword in
@ref{665,,type statements}.

@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 an
@ref{484,,@@warnings.deprecated}-decorated base class
may not invoke the correct @ref{83c,,__init_subclass__()} method in
cases involving multiple inheritance. Patch by Brian Schubert.

@item 
gh-137317@footnote{https://github.com/python/cpython/issues/137317}: @ref{22f,,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{13a,,zoneinfo} module if the C
implementation of the @ref{34,,datetime} module is not available.

@item 
gh-137490@footnote{https://github.com/python/cpython/issues/137490}: Handle @ref{1758,,ECANCELED} in the same way as
@ref{f82,,EINTR} in @ref{fa6,,signal.sigwaitinfo()} on NetBSD.

@item 
gh-137477@footnote{https://github.com/python/cpython/issues/137477}: Fix @code{inspect.getblock()}, @ref{174f,,inspect.getsourcelines()}
and @ref{1759,,inspect.getsource()} for generator expressions.

@item 
gh-137044@footnote{https://github.com/python/cpython/issues/137044}: Return large limit values as positive integers instead of
negative integers in @ref{175a,,resource.getrlimit()}. Accept large values and
reject negative values (except @ref{175b,,RLIM_INFINITY}) for limits
in @ref{175c,,resource.setrlimit()}.

@item 
gh-75989@footnote{https://github.com/python/cpython/issues/75989}: @ref{29b,,tarfile.TarFile.extractall()} and
@ref{29c,,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{b3d,,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
@ref{b3d,,threading.Thread.is_alive} calls.

@item 
gh-137273@footnote{https://github.com/python/cpython/issues/137273}: Fix debug assertion failure in @ref{327,,locale.setlocale()} on
Windows.

@item 
gh-137239@footnote{https://github.com/python/cpython/issues/137239}: @ref{6d,,heapq}: Update @code{heapq.__all__} with @code{*_max}
functions.

@item 
gh-81325@footnote{https://github.com/python/cpython/issues/81325}: @ref{1411,,tarfile.TarFile} now accepts a @ref{59b,,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{5c,,faulthandler} when printing C stack traces.

@item 
gh-136914@footnote{https://github.com/python/cpython/issues/136914}: Fix retrieval of @ref{175d,,doctest.DocTest.lineno} for objects
decorated with @ref{175e,,functools.cache()} or
@ref{75c,,functools.cached_property}.

@item 
gh-136912@footnote{https://github.com/python/cpython/issues/136912}: @ref{d2a,,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{bd3,,ctypes.CDLL} without name when passing
a handle as an argument.

@item 
gh-136234@footnote{https://github.com/python/cpython/issues/136234}: Fix @ref{175f,,asyncio.WriteTransport.writelines()} to be robust to
connection failure, by using the same behavior as
@ref{1760,,write()}.

@item 
gh-136507@footnote{https://github.com/python/cpython/issues/136507}: Fix mimetypes CLI to handle multiple file parameters.

@item 
gh-135386@footnote{https://github.com/python/cpython/issues/135386}: Fix opening a @ref{39,,dbm.sqlite3} database for reading from
read-only file or directory.

@item 
gh-135444@footnote{https://github.com/python/cpython/issues/135444}: Fix @ref{4c6,,asyncio.DatagramTransport.sendto()} to account for
datagram header size when data cannot be sent.

@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-134698@footnote{https://github.com/python/cpython/issues/134698}: Fix a crash when calling methods of @ref{355,,ssl.SSLContext} or
@ref{ade,,ssl.SSLSocket} across multiple threads.

@item 
gh-125996@footnote{https://github.com/python/cpython/issues/125996}: Fix thread safety of @ref{7ec,,collections.OrderedDict}. Patch by
Kumar Aditya.

@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-127081@footnote{https://github.com/python/cpython/issues/127081}: Fix libc thread safety issues with @ref{35,,dbm} by performing
stateful operations in critical sections.

@item 
gh-132551@footnote{https://github.com/python/cpython/issues/132551}: Make @ref{109f,,io.BytesIO} safe in @ref{1f4,,free-threaded} build.

@item 
gh-131788@footnote{https://github.com/python/cpython/issues/131788}: Make @code{ResourceTracker.send} from @ref{98,,multiprocessing}
re-entrant safe

@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-102431@footnote{https://github.com/python/cpython/issues/102431}: Clarify constraints for "logical" arguments in methods of
@ref{12b0,,decimal.Context}.

@item 
gh-78319@footnote{https://github.com/python/cpython/issues/78319}: UTF8 support for the IMAP APPEND command has been made RFC
compliant.

@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-41839@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41839}: Allow negative priority values from
@ref{130a,,os.sched_get_priority_min()} and @ref{1309,,os.sched_get_priority_max()}
functions.
@end itemize

@node IDLE<3>,Core and Builtins,Library,Python next
@anchor{whatsnew/changelog idle}@anchor{1761}
@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 Core and Builtins,C API,IDLE<3>,Python next
@anchor{whatsnew/changelog core-and-builtins}@anchor{1762}
@subsubsection Core and Builtins



@itemize -

@item 
gh-140576@footnote{https://github.com/python/cpython/issues/140576}: Fixed crash in @ref{6fa,,tokenize.generate_tokens()} in case of
specific incorrect input. Patch by Mikhail Efimov.

@item 
gh-140551@footnote{https://github.com/python/cpython/issues/140551}: Fixed crash in @ref{183,,dict} if @ref{1763,,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{19f,,map()} with @code{strict=True} when the input iterables have different
lengths. Patch by Mikhail Efimov.

@item 
gh-140471@footnote{https://github.com/python/cpython/issues/140471}: Fix potential buffer overflow in @ref{4be,,ast.AST} node
initialization when encountering malformed @ref{1764,,_fields}
containing non-@ref{169,,str}.

@item 
gh-140431@footnote{https://github.com/python/cpython/issues/140431}: Fix a crash in Python's @ref{1765,,garbage collector} due to partially initialized @ref{6b2,,coroutine} objects when
coroutine origin tracking depth is enabled
(@ref{d7f,,sys.set_coroutine_origin_tracking_depth()}).

@item 
gh-140398@footnote{https://github.com/python/cpython/issues/140398}: Fix memory leaks in @ref{bf,,readline} functions
@ref{1766,,read_init_file()}, @ref{1767,,read_history_file()},
@ref{1768,,write_history_file()}, and
@ref{104c,,append_history_file()} when @ref{60b,,PySys_Audit()} fails.

@item 
gh-140406@footnote{https://github.com/python/cpython/issues/140406}: Fix memory leak when an object's @ref{cea,,__hash__()}
method returns an object that isn't an @ref{19b,,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-140306@footnote{https://github.com/python/cpython/issues/140306}: Fix memory leaks in cross-interpreter channel operations and
shared namespace handling.

@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-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-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-140067@footnote{https://github.com/python/cpython/issues/140067}: Fix memory leak in sub-interpreter creation.

@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{2ae,,typing.TypeAliasType}, @ref{481,,typing.TypeVar},
@ref{482,,typing.ParamSpec}, or @ref{483,,typing.TypeVarTuple} and its
@code{__name__} attribute. Patch by Mikhail Efimov.

@item 
gh-139988@footnote{https://github.com/python/cpython/issues/139988}: Fix a memory leak when failing to create a
@ref{2a8,,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{4ac,,compile()} and @ref{1652,,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-139640@footnote{https://github.com/python/cpython/issues/139640}: @ref{1c2,,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-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-116738@footnote{https://github.com/python/cpython/issues/116738}: Make @ref{94,,mmap} thread-safe on the @ref{1f4,,free threaded} build.

@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-138944@footnote{https://github.com/python/cpython/issues/138944}: Fix @ref{18e,,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-105487@footnote{https://github.com/python/cpython/issues/105487}: Remove non-existent @ref{1769,,__copy__()},
@ref{176a,,__deepcopy__()}, and @ref{16a0,,__bases__} from the
@ref{176b,,__dir__()} entries of @ref{9e5,,types.GenericAlias}.

@item 
gh-69605@footnote{https://github.com/python/cpython/issues/69605}: Fix some standard library submodules missing from the
@ref{48c,,REPL} auto-completion of imports.

@item 
gh-116738@footnote{https://github.com/python/cpython/issues/116738}: Make @ref{2b,,cProfile} thread-safe on the @ref{1f4,,free threaded} build.

@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-137433@footnote{https://github.com/python/cpython/issues/137433}: Fix a potential deadlock in the @ref{1f4,,free threading} build
when daemon threads enable or disable profiling or tracing while the main
thread is shutting down the interpreter.

@item 
gh-137400@footnote{https://github.com/python/cpython/issues/137400}: Fix a crash in the @ref{1f4,,free threading} build when disabling
profiling or tracing across all threads with
@ref{77a,,PyEval_SetProfileAllThreads()} or
@ref{65c,,PyEval_SetTraceAllThreads()} or their Python equivalents
@ref{6e8,,threading.settrace_all_threads()} and
@ref{6e9,,threading.setprofile_all_threads()}.

@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-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-128640@footnote{https://github.com/python/cpython/issues/128640}: Fix a crash when using threads inside of a subinterpreter.
@end itemize

@node C API,Build,Core and Builtins,Python next
@anchor{whatsnew/changelog c-api}@anchor{176c}
@subsubsection C API



@itemize -

@item 
gh-140487@footnote{https://github.com/python/cpython/issues/140487}: Fix @ref{176d,,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{2cf,,Py_REFCNT()} definition on limited C API 3.11-3.13.
Patch by Victor Stinner.
@end itemize

@node Build,,C API,Python next
@anchor{whatsnew/changelog build}@anchor{176e}
@subsubsection Build



@itemize -

@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-140189@footnote{https://github.com/python/cpython/issues/140189}: iOS builds were added to CI.

@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-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}.
@end itemize

@node Python 3 14 0 final,Python 3 14 0 release candidate 3,Python next,Changelog（更動日誌）
@anchor{whatsnew/changelog python-3-14-0-final}@anchor{176f}
@subsection Python 3.14.0 final


`Release date: 2025-10-07'

@menu
* macOS:: 
* Windows: Windows<2>. 
* Tools/Demos: Tools/Demos<2>. 
* Security: Security<2>. 
* Library: Library<2>. 

@end menu

@node macOS,Windows<2>,,Python 3 14 0 final
@anchor{whatsnew/changelog macos}@anchor{1770}
@subsubsection macOS



@itemize -

@item 
gh-124111@footnote{https://github.com/python/cpython/issues/124111}: Update macOS installer to use Tcl/Tk 8.6.17.

@item 
gh-139573@footnote{https://github.com/python/cpython/issues/139573}: Updated bundled version of OpenSSL to 3.0.18.
@end itemize

@node Windows<2>,Tools/Demos<2>,macOS,Python 3 14 0 final
@anchor{whatsnew/changelog id2}@anchor{1771}
@subsubsection Windows



@itemize -

@item 
gh-139573@footnote{https://github.com/python/cpython/issues/139573}: Updated bundled version of OpenSSL to 3.0.18.
@end itemize

@node Tools/Demos<2>,Security<2>,Windows<2>,Python 3 14 0 final
@anchor{whatsnew/changelog id3}@anchor{1772}
@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.
@end itemize

@node Security<2>,Library<2>,Tools/Demos<2>,Python 3 14 0 final
@anchor{whatsnew/changelog id4}@anchor{1773}
@subsubsection Security



@itemize -

@item 
gh-139400@footnote{https://github.com/python/cpython/issues/139400}: @ref{12c,,xml.parsers.expat}: Make sure that parent Expat parsers
are only garbage-collected once they are no longer referenced by
subparsers created by
@ref{1774,,ExternalEntityParserCreate()}. Patch by
Sebastian Pipping.
@end itemize

@node Library<2>,,Security<2>,Python 3 14 0 final
@anchor{whatsnew/changelog id5}@anchor{1775}
@subsubsection Library



@itemize -

@item 
gh-139312@footnote{https://github.com/python/cpython/issues/139312}: Upgrade bundled libexpat to 2.7.3
@end itemize

@node Python 3 14 0 release candidate 3,Python 3 14 0 release candidate 2,Python 3 14 0 final,Changelog（更動日誌）
@anchor{whatsnew/changelog python-3-14-0-release-candidate-3}@anchor{1776}
@subsection Python 3.14.0 release candidate 3


`Release date: 2025-09-18'

@menu
* Windows: Windows<3>. 
* Tools/Demos: Tools/Demos<3>. 
* Security: Security<3>. 
* Library: Library<3>. 
* Core and Builtins: Core and Builtins<2>. 

@end menu

@node Windows<3>,Tools/Demos<3>,,Python 3 14 0 release candidate 3
@anchor{whatsnew/changelog id6}@anchor{1777}
@subsubsection Windows



@itemize -

@item 
gh-138896@footnote{https://github.com/python/cpython/issues/138896}: Fix error installing C runtime on non-updated Windows machines
@end itemize

@node Tools/Demos<3>,Security<3>,Windows<3>,Python 3 14 0 release candidate 3
@anchor{whatsnew/changelog id7}@anchor{1778}
@subsubsection Tools/Demos



@itemize -

@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.
@end itemize

@node Security<3>,Library<3>,Tools/Demos<3>,Python 3 14 0 release candidate 3
@anchor{whatsnew/changelog id8}@anchor{1779}
@subsubsection Security



@itemize -

@item 
gh-135661@footnote{https://github.com/python/cpython/issues/135661}: Fix CDATA section parsing in @ref{a6e,,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.
@end itemize

@node Library<3>,Core and Builtins<2>,Security<3>,Python 3 14 0 release candidate 3
@anchor{whatsnew/changelog id9}@anchor{177a}
@subsubsection Library



@itemize -

@item 
gh-138998@footnote{https://github.com/python/cpython/issues/138998}: Update bundled libexpat to 2.7.2

@item 
gh-118803@footnote{https://github.com/python/cpython/issues/118803}: Add back @ref{341,,collections.abc.ByteString} and
@ref{344,,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-137226@footnote{https://github.com/python/cpython/issues/137226}: Fix @ref{8b9,,typing.get_type_hints()} calls on generic
@ref{331,,typing.TypedDict} classes defined with string annotations.

@item 
gh-138804@footnote{https://github.com/python/cpython/issues/138804}: Raise @ref{198,,TypeError} instead of @ref{5e8,,AttributeError} when an
argument of incorrect type is passed to @ref{57c,,shlex.quote()}. This restores
the behavior of the function prior to 3.14.

@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-138514@footnote{https://github.com/python/cpython/issues/138514}: Raise @ref{2eb,,ValueError} when a multi-character string is passed
to the `echo_char' parameter of @ref{21d,,getpass.getpass()}. Patch by Benjamin
Johnson.

@item 
gh-138515@footnote{https://github.com/python/cpython/issues/138515}: @ref{3f,,email} is added to Emscripten build.

@item 
gh-99948@footnote{https://github.com/python/cpython/issues/99948}: @ref{f40,,ctypes.util.find_library()} now works in Emscripten build.

@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{158c,,queue.Queue} interface.

@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-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-90548@footnote{https://github.com/python/cpython/issues/90548}: Fix @code{musl} detection for @ref{177b,,platform.libc_ver()} on Alpine
Linux if compiled with --strip-all.

@item 
gh-136134@footnote{https://github.com/python/cpython/issues/136134}: @code{SMTP.auth_cram_md5()} now raises an
@ref{119c,,SMTPException} instead of a @ref{2eb,,ValueError} if Python has
been built without MD5 support. In particular, @ref{b1e,,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{177c,,IMAP4.login_cram_md5} now
raises an @ref{177d,,IMAP4.error} if CRAM-MD5
authentication is not supported. 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{48c,,repl}.
@end itemize

@node Core and Builtins<2>,,Library<3>,Python 3 14 0 release candidate 3
@anchor{whatsnew/changelog id10}@anchor{177e}
@subsubsection Core and Builtins



@itemize -

@item 
gh-71810@footnote{https://github.com/python/cpython/issues/71810}: Raise @ref{a78,,OverflowError} for @code{(-1).to_bytes()} for signed
conversions when bytes count is zero.  Patch by Sergey B Kirpichev.

@item 
gh-138192@footnote{https://github.com/python/cpython/issues/138192}: Fix @ref{28,,contextvars} initialization so that all
subinterpreters are assigned the @ref{177f,,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{60c,,tuple}.

@item 
gh-138372@footnote{https://github.com/python/cpython/issues/138372}: Fix @ref{1ae,,SyntaxWarning} emitted for erroneous subscript
expressions involving @ref{1780,,template string literals}. Patch
by Brian Schubert.

@item 
gh-138318@footnote{https://github.com/python/cpython/issues/138318}: The default REPL now avoids highlighting built-in names (for
instance @ref{184,,set} or @ref{199,,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-137384@footnote{https://github.com/python/cpython/issues/137384}: Fix a crash when using the @ref{118,,warnings} module in a
finalizer at shutdown. Patch by Kumar Aditya.

@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-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{1b8,,PYTHONSTARTUP} is given. Patch by Adam Hartz.
@end itemize

@node Python 3 14 0 release candidate 2,Python 3 14 0 release candidate 1,Python 3 14 0 release candidate 3,Changelog（更動日誌）
@anchor{whatsnew/changelog python-3-14-0-release-candidate-2}@anchor{1781}
@subsection Python 3.14.0 release candidate 2


`Release date: 2025-08-14'

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

@end menu

@node macOS<2>,Windows<4>,,Python 3 14 0 release candidate 2
@anchor{whatsnew/changelog id11}@anchor{1782}
@subsubsection macOS



@itemize -

@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<4>,Library<4>,macOS<2>,Python 3 14 0 release candidate 2
@anchor{whatsnew/changelog id12}@anchor{1783}
@subsubsection Windows



@itemize -

@item 
gh-137134@footnote{https://github.com/python/cpython/issues/137134}: Update Windows installer to ship with SQLite 3.50.4.
@end itemize

@node Library<4>,Documentation,Windows<4>,Python 3 14 0 release candidate 2
@anchor{whatsnew/changelog id13}@anchor{1784}
@subsubsection Library



@itemize -

@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-137282@footnote{https://github.com/python/cpython/issues/137282}: Fix tab completion and @ref{83d,,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-137226@footnote{https://github.com/python/cpython/issues/137226}: Fix behavior of @ref{1785,,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-130522@footnote{https://github.com/python/cpython/issues/130522}: Fix unraisable @ref{198,,TypeError} raised during
@ref{474,,interpreter shutdown} in the @ref{f3,,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{2bd,,urllib.request.url2pathname()}. This fixes a
regression in earlier pre-releases of Python 3.14.

@item 
gh-130577@footnote{https://github.com/python/cpython/issues/130577}: @ref{e4,,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-135228@footnote{https://github.com/python/cpython/issues/135228}: When @ref{33,,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 @ref{33,,dataclasses}.
@end itemize

@node Documentation,Core and Builtins<3>,Library<4>,Python 3 14 0 release candidate 2
@anchor{whatsnew/changelog documentation}@anchor{1786}
@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.
@end itemize

@node Core and Builtins<3>,C API<2>,Documentation,Python 3 14 0 release candidate 2
@anchor{whatsnew/changelog id14}@anchor{1787}
@subsubsection Core and Builtins



@itemize -

@item 
gh-137400@footnote{https://github.com/python/cpython/issues/137400}: Fix a crash in the @ref{1f4,,free threading} build when disabling
profiling or tracing across all threads with
@ref{77a,,PyEval_SetProfileAllThreads()} or
@ref{65c,,PyEval_SetTraceAllThreads()} or their Python equivalents
@ref{6e8,,threading.settrace_all_threads()} and
@ref{6e9,,threading.setprofile_all_threads()}.

@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{17e,,pass} statement to ensure that the node's body is never empty.
There was a @ref{2eb,,ValueError} in @ref{4ac,,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-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-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.
@end itemize

@node C API<2>,Build<2>,Core and Builtins<3>,Python 3 14 0 release candidate 2
@anchor{whatsnew/changelog id15}@anchor{1788}
@subsubsection C API



@itemize -

@item 
gh-137573@footnote{https://github.com/python/cpython/issues/137573}: Mark @code{_PyOptimizer_Optimize} as @ref{1789,,Py_NO_INLINE} to
prevent stack overflow crashes on macOS.
@end itemize

@node Build<2>,,C API<2>,Python 3 14 0 release candidate 2
@anchor{whatsnew/changelog id16}@anchor{178a}
@subsubsection Build



@itemize -

@item 
gh-132339@footnote{https://github.com/python/cpython/issues/132339}: Add support for OpenSSL 3.5.
@end itemize

@node Python 3 14 0 release candidate 1,Python 3 14 0 beta 4,Python 3 14 0 release candidate 2,Changelog（更動日誌）
@anchor{whatsnew/changelog python-3-14-0-release-candidate-1}@anchor{178b}
@subsection Python 3.14.0 release candidate 1


`Release date: 2025-07-22'

@menu
* Tools/Demos: Tools/Demos<4>. 
* Security: Security<4>. 
* Library: Library<5>. 
* Core and Builtins: Core and Builtins<4>. 
* C API: C API<3>. 
* Build: Build<3>. 

@end menu

@node Tools/Demos<4>,Security<4>,,Python 3 14 0 release candidate 1
@anchor{whatsnew/changelog id17}@anchor{178c}
@subsubsection Tools/Demos



@itemize -

@item 
gh-136251@footnote{https://github.com/python/cpython/issues/136251}: Fixes and usability improvements for
@code{Tools/wasm/emscripten/web_example}
@end itemize

@node Security<4>,Library<5>,Tools/Demos<4>,Python 3 14 0 release candidate 1
@anchor{whatsnew/changelog id18}@anchor{178d}
@subsubsection Security



@itemize -

@item 
gh-135661@footnote{https://github.com/python/cpython/issues/135661}: Fix parsing attributes with whitespaces around the @code{=}
separator in @ref{a6e,,html.parser.HTMLParser} according to the HTML5
standard.

@item 
gh-118350@footnote{https://github.com/python/cpython/issues/118350}: Fix support of escapable raw text mode (elements "textarea" and
"title") in @ref{a6e,,html.parser.HTMLParser}.
@end itemize

@node Library<5>,Core and Builtins<4>,Security<4>,Python 3 14 0 release candidate 1
@anchor{whatsnew/changelog id19}@anchor{178e}
@subsubsection Library



@itemize -

@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-124621@footnote{https://github.com/python/cpython/issues/124621}: pyrepl now works in Emscripten.

@item 
gh-136874@footnote{https://github.com/python/cpython/issues/136874}: Discard URL query and fragment in
@ref{2bd,,urllib.request.url2pathname()}.

@item 
gh-130645@footnote{https://github.com/python/cpython/issues/130645}: Enable color help by default in @ref{7,,argparse}.

@item 
gh-136549@footnote{https://github.com/python/cpython/issues/136549}: Fix signature of @ref{a44,,threading.excepthook()}.

@item 
gh-136523@footnote{https://github.com/python/cpython/issues/136523}: Fix @ref{334,,wave.Wave_write} emitting an unraisable when open
raises.

@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{1d2,,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{fb0,,-OO}.

@item 
gh-136380@footnote{https://github.com/python/cpython/issues/136380}: Raises @ref{5e8,,AttributeError} when accessing
@ref{1d2,,concurrent.futures.InterpreterPoolExecutor} and subinterpreters
are not available.

@item 
gh-134759@footnote{https://github.com/python/cpython/issues/134759}: Fix @ref{172a,,UnboundLocalError} in
@ref{13ce,,email.message.Message.get_payload()} when the payload to decode is a
@ref{192,,bytes} object. Patch by Kliment Lamonov.

@item 
gh-134657@footnote{https://github.com/python/cpython/issues/134657}: @ref{b,,asyncio}: Remove some private names from
@code{asyncio.__all__}.
@end itemize

@node Core and Builtins<4>,C API<3>,Library<5>,Python 3 14 0 release candidate 1
@anchor{whatsnew/changelog id20}@anchor{178f}
@subsubsection Core and Builtins



@itemize -

@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-136421@footnote{https://github.com/python/cpython/issues/136421}: Fix crash when initializing @ref{34,,datetime} concurrently.

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

@item 
gh-136517@footnote{https://github.com/python/cpython/issues/136517}: Fixed a typo that prevented printing of uncollectable objects
when the @ref{13c3,,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-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{169,,str}. Also, disallow implicit concatenation of t-string literals
with string or f-string literals.

@item 
gh-116738@footnote{https://github.com/python/cpython/issues/116738}: Make functions in @ref{6a,,grp} thread-safe on the @ref{1f4,,free threaded} build.

@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-133136@footnote{https://github.com/python/cpython/issues/133136}: Limit excess memory usage in the @ref{1f4,,free threading} build
when a large dictionary or list is resized and accessed by multiple
threads.

@item 
gh-91153@footnote{https://github.com/python/cpython/issues/91153}: Fix a crash when a @ref{343,,bytearray} is concurrently mutated
during item assignment.

@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.
@end itemize

@node C API<3>,Build<3>,Core and Builtins<4>,Python 3 14 0 release candidate 1
@anchor{whatsnew/changelog id21}@anchor{1790}
@subsubsection C API



@itemize -

@item 
gh-112068@footnote{https://github.com/python/cpython/issues/112068}: Revert support of nullable arguments in @ref{1791,,PyArg_Parse()}.

@item 
gh-133296@footnote{https://github.com/python/cpython/issues/133296}: New variants for the critical section API that accept one or
two @ref{47f,,PyMutex} pointers rather than @ref{5d7,,PyObject} instances
are now public in the non-limited C API.

@item 
gh-134009@footnote{https://github.com/python/cpython/issues/134009}: Expose @ref{461,,PyMutex_IsLocked()} as part of the public C API.
@end itemize

@node Build<3>,,C API<3>,Python 3 14 0 release candidate 1
@anchor{whatsnew/changelog id22}@anchor{1792}
@subsubsection Build



@itemize -

@item 
gh-135621@footnote{https://github.com/python/cpython/issues/135621}: PyREPL no longer depends on the @ref{2f,,curses} standard library.
Contributed by Łukasz Langa.
@end itemize

@node Python 3 14 0 beta 4,Python 3 14 0 beta 3,Python 3 14 0 release candidate 1,Changelog（更動日誌）
@anchor{whatsnew/changelog python-3-14-0-beta-4}@anchor{1793}
@subsection Python 3.14.0 beta 4


`Release date: 2025-07-08'

@menu
* Tools/Demos: Tools/Demos<5>. 
* Tests: Tests<2>. 
* Security: Security<5>. 
* Library: Library<6>. 
* Documentation: Documentation<2>. 
* Core and Builtins: Core and Builtins<5>. 
* C API: C API<4>. 
* Build: Build<4>. 

@end menu

@node Tools/Demos<5>,Tests<2>,,Python 3 14 0 beta 4
@anchor{whatsnew/changelog id23}@anchor{1794}
@subsubsection Tools/Demos



@itemize -

@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-133600@footnote{https://github.com/python/cpython/issues/133600}: Backport file reorganization for Tools/wasm/wasi.

This should make backporting future code changes easier. It also
simplifies instructions around how to do WASI builds in the devguide.
@end itemize

@node Tests<2>,Security<5>,Tools/Demos<5>,Python 3 14 0 beta 4
@anchor{whatsnew/changelog id24}@anchor{1795}
@subsubsection Tests



@itemize -

@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.
@end itemize

@node Security<5>,Library<6>,Tests<2>,Python 3 14 0 beta 4
@anchor{whatsnew/changelog id25}@anchor{1796}
@subsubsection Security



@itemize -

@item 
gh-136053@footnote{https://github.com/python/cpython/issues/136053}: @ref{91,,marshal}: fix a possible crash when deserializing
@ref{68d,,slice} objects.

@item 
gh-135661@footnote{https://github.com/python/cpython/issues/135661}: Fix parsing start and end tags in
@ref{a6e,,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".

@item 
[Reverted in gh-136927@footnote{https://github.com/python/cpython/issues/136927}] Whitespaces between the @code{=} separator and attribute name or value are no
longer ignored. E.g. @code{<a foo =bar>} produces two attributes "foo" and
"=bar", both with value None; @code{<a foo= bar>} produces two attributes:
"foo" with value "" and "bar" with value None.
@end itemize

@item 
gh-102555@footnote{https://github.com/python/cpython/issues/102555}: Fix comment parsing in @ref{a6e,,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{<--->}.
@end itemize

@node Library<6>,Documentation<2>,Security<5>,Python 3 14 0 beta 4
@anchor{whatsnew/changelog id26}@anchor{1797}
@subsubsection Library



@itemize -

@item 
gh-136286@footnote{https://github.com/python/cpython/issues/136286}: Fix pickling failures for protocols 0 and 1 for many objects
realted to subinterpreters.

@item 
gh-136316@footnote{https://github.com/python/cpython/issues/136316}: Improve support for evaluating nested forward references in
@ref{1798,,typing.evaluate_forward_ref()}.

@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{1799,,zoneinfo.ZoneInfoNotFoundError} is raised rather than a
@ref{f39,,PermissionError}. Patch by Victor Stinner.

@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{1624,,time.strptime()}. This affects locales
az_AZ, ber_DZ, ber_MA and crh_UA.

@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-53203@footnote{https://github.com/python/cpython/issues/53203}: Fix @ref{1624,,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-91555@footnote{https://github.com/python/cpython/issues/91555}: An earlier change, which was introduced in 3.14.0b2, has been
reverted. It disabled logging for a logger during handling of log messages
for that logger. Since the reversion, the behaviour should be as it was
before 3.14.0b2.

@item 
gh-135878@footnote{https://github.com/python/cpython/issues/135878}: Fixes a crash of @ref{4e0,,types.SimpleNamespace} on @ref{1f4,,free threading} builds, when several threads were calling its
@ref{828,,__repr__()} method at the same time.

@item 
gh-135836@footnote{https://github.com/python/cpython/issues/135836}: Fix @ref{1729,,IndexError} in @ref{811,,asyncio.loop.create_connection()}
that could occur when non-@ref{2c0,,OSError} exception is raised during
connection and socket's @code{close()} raises @code{OSError}.

@item 
gh-135836@footnote{https://github.com/python/cpython/issues/135836}: Fix @ref{1729,,IndexError} in @ref{811,,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{198,,TypeError} instead of @ref{78e,,SystemError} when
@code{_interpreters.set___main___attrs()} is passed a non-dict object.
Patch by Brian Schubert.

@item 
gh-135815@footnote{https://github.com/python/cpython/issues/135815}: @ref{9f,,netrc}: skip security checks if @ref{179a,,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{c83,,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-135645@footnote{https://github.com/python/cpython/issues/135645}: Added @code{supports_isolated_interpreters} field to
@ref{734,,sys.implementation}.

@item 
gh-135646@footnote{https://github.com/python/cpython/issues/135646}: Raise consistent @ref{450,,NameError} exceptions in
@ref{1785,,annotationlib.ForwardRef.evaluate()}

@item 
gh-135557@footnote{https://github.com/python/cpython/issues/135557}: Fix races on @ref{6d,,heapq} updates and @ref{24d,,list} reads on
the @ref{1f4,,free threaded} build.

@item 
gh-119180@footnote{https://github.com/python/cpython/issues/119180}: Only fetch globals and locals if necessary in
@ref{457,,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-135487@footnote{https://github.com/python/cpython/issues/135487}: Fix @code{reprlib.Repr.repr_int()} when given integers with
more than @ref{179b,,sys.get_int_max_str_digits()} digits. Patch by Bénédikt
Tran.

@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-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{1fe,,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{213,,Fraction} formatting, for example @code{format(Fraction(1,
3), '.016f')}.

@item 
gh-87790@footnote{https://github.com/python/cpython/issues/87790}: Support underscore and comma as thousands separators in the
fractional part for @ref{213,,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{1fe,,Decimal}'s formatting.  Patch by
Sergey B Kirpichev.

@item 
gh-130664@footnote{https://github.com/python/cpython/issues/130664}: Handle corner-case for @ref{213,,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{196,,float}'s.
@end itemize

@node Documentation<2>,Core and Builtins<5>,Library<6>,Python 3 14 0 beta 4
@anchor{whatsnew/changelog id27}@anchor{179c}
@subsubsection Documentation



@itemize -

@item 
gh-136155@footnote{https://github.com/python/cpython/issues/136155}: EPUB builds are fixed by excluding non-XHTML-compatible tags.
@end itemize

@node Core and Builtins<5>,C API<4>,Documentation<2>,Python 3 14 0 beta 4
@anchor{whatsnew/changelog id28}@anchor{179d}
@subsubsection Core and Builtins



@itemize -

@item 
gh-109700@footnote{https://github.com/python/cpython/issues/109700}: Fix memory error handling in @ref{5dc,,PyDict_SetDefault()}.

@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-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{1f4,,free threading}
build.

@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-135607@footnote{https://github.com/python/cpython/issues/135607}: Fix potential @ref{11a,,weakref} races in an object's destructor on
the @ref{1f4,,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-135543@footnote{https://github.com/python/cpython/issues/135543}: Emit @code{sys.remote_exec} audit event when
@ref{16d,,sys.remote_exec()} is called and migrate @code{remote_debugger_script}
to @code{cpython.remote_debugger_script}.

@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.
@end itemize

@node C API<4>,Build<4>,Core and Builtins<5>,Python 3 14 0 beta 4
@anchor{whatsnew/changelog id29}@anchor{179e}
@subsubsection C API



@itemize -

@item 
gh-135906@footnote{https://github.com/python/cpython/issues/135906}: Fix compilation errors when compiling the internal headers with
a C++ compiler.
@end itemize

@node Build<4>,,C API<4>,Python 3 14 0 beta 4
@anchor{whatsnew/changelog id30}@anchor{179f}
@subsubsection Build



@itemize -

@item 
gh-134273@footnote{https://github.com/python/cpython/issues/134273}: Add support for configuring compiler flags for the JIT with
@code{CFLAGS_JIT}
@end itemize

@node Python 3 14 0 beta 3,Python 3 14 0 beta 2,Python 3 14 0 beta 4,Changelog（更動日誌）
@anchor{whatsnew/changelog python-3-14-0-beta-3}@anchor{17a0}
@subsection Python 3.14.0 beta 3


`Release date: 2025-06-17'

@menu
* Windows: Windows<5>. 
* Tests: Tests<3>. 
* Security: Security<6>. 
* Library: Library<7>. 
* Documentation: Documentation<3>. 
* Core and Builtins: Core and Builtins<6>. 
* C API: C API<5>. 
* Build: Build<5>. 

@end menu

@node Windows<5>,Tests<3>,,Python 3 14 0 beta 3
@anchor{whatsnew/changelog id31}@anchor{17a1}
@subsubsection Windows



@itemize -

@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{47f,,PyMutex} while the main thread is shutting down
the interpreter.
@end itemize

@node Tests<3>,Security<6>,Windows<5>,Python 3 14 0 beta 3
@anchor{whatsnew/changelog id32}@anchor{17a2}
@subsubsection Tests



@itemize -

@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-135120@footnote{https://github.com/python/cpython/issues/135120}: Add @code{test.support.subTests()}.
@end itemize

@node Security<6>,Library<7>,Tests<3>,Python 3 14 0 beta 3
@anchor{whatsnew/changelog id33}@anchor{17a3}
@subsubsection Security



@itemize -

@item 
gh-135462@footnote{https://github.com/python/cpython/issues/135462}: Fix quadratic complexity in processing specially crafted input
in @ref{a6e,,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-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}.
@end itemize

@node Library<7>,Documentation<3>,Security<6>,Python 3 14 0 beta 3
@anchor{whatsnew/changelog id34}@anchor{17a4}
@subsubsection Library



@itemize -

@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{17a5,,os.getlogin()} failing for longer usernames on
BSD-based platforms.

@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{c36,,unittest.mock.Mock} generation on
@ref{4dc,,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-133967@footnote{https://github.com/python/cpython/issues/133967}: Do not normalize @ref{8a,,locale} name 'C.UTF-8' to 'en_US.UTF-8'.

@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-135276@footnote{https://github.com/python/cpython/issues/135276}: Backported bugfixes in zipfile.Path from zipp 3.23. Fixed
@code{.name}, @code{.stem} and other basename-based properties on Windows when
working with a zipfile on disk.

@item 
gh-135244@footnote{https://github.com/python/cpython/issues/135244}: @ref{116,,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{d9c,,uuid1()} and
@ref{2c2,,uuid6()}.

@item 
gh-134970@footnote{https://github.com/python/cpython/issues/134970}: Fix the "unknown action" exception in
@ref{2ea,,argparse.ArgumentParser.add_argument_group()} to correctly replace
the action class.

@item 
gh-134718@footnote{https://github.com/python/cpython/issues/134718}: @ref{ad8,,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-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{3e,,doctest}s run with
@ref{10c,,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-134637@footnote{https://github.com/python/cpython/issues/134637}: Fix performance regression in calling a @ref{2e,,ctypes} function
pointer in @ref{1f4,,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{17a6,,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-134151@footnote{https://github.com/python/cpython/issues/134151}: @ref{3f,,email}: Fix @ref{198,,TypeError} in
@ref{17a7,,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-134210@footnote{https://github.com/python/cpython/issues/134210}: @ref{17a8,,curses.window.getch()} now correctly handles signals.
Patch by Bénédikt Tran.

@item 
gh-134152@footnote{https://github.com/python/cpython/issues/134152}: @ref{3f,,email}: Fix parsing of email message ID with invalid
domain.

@item 
gh-133489@footnote{https://github.com/python/cpython/issues/133489}: @ref{1208,,random.getrandbits()} can now generate more that 2@w{^31} bits. @ref{17a9,,random.randbytes()} can now generate more that 256
MiB.

@item 
gh-132813@footnote{https://github.com/python/cpython/issues/132813}: Improve error messages for incorrect types and values of
@ref{17aa,,csv.Dialect} attributes.

@item 
gh-132969@footnote{https://github.com/python/cpython/issues/132969}: Prevent the @ref{1d6,,ProcessPoolExecutor}
executor thread, which remains running when @ref{ae1,,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-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-131884@footnote{https://github.com/python/cpython/issues/131884}: Fix formatting issues in @ref{f3b,,json.dump()} when both `indent'
and `skipkeys' are used.

@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.
@end itemize

@node Documentation<3>,Core and Builtins<6>,Library<7>,Python 3 14 0 beta 3
@anchor{whatsnew/changelog id35}@anchor{17ab}
@subsubsection Documentation



@itemize -

@item 
gh-135171@footnote{https://github.com/python/cpython/issues/135171}: Document that the @ref{4c3,,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<6>,C API<5>,Documentation<3>,Python 3 14 0 beta 3
@anchor{whatsnew/changelog id36}@anchor{17ac}
@subsubsection Core and Builtins



@itemize -

@item 
gh-135496@footnote{https://github.com/python/cpython/issues/135496}: Fix typo in the f-string conversion type error ("exclamanation"
-> "exclamation").

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

@item 
gh-135171@footnote{https://github.com/python/cpython/issues/135171}: Reverts the behavior of async generator expressions when
created with object w/o __aiter__ method to the pre-3.13 behavior of
raising a TypeError.

@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-135171@footnote{https://github.com/python/cpython/issues/135171}: Reverts the behavior of generator expressions when created with
a non-iterable to the pre-3.13 behavior of raising a TypeError. It is no
longer possible to cause a crash in the debugger by altering the generator
expression's local variables. This is achieved by moving the @code{GET_ITER}
instruction back to the creation of the generator expression and adding an
additional check to @code{FOR_ITER}.

@item 
gh-116738@footnote{https://github.com/python/cpython/issues/116738}: Make methods in @ref{6d,,heapq} thread-safe on the @ref{1f4,,free threaded} build.

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

@item 
gh-134908@footnote{https://github.com/python/cpython/issues/134908}: Fix crash when iterating over lines in a text file on the
@ref{1f4,,free threaded} build.

@item 
gh-132617@footnote{https://github.com/python/cpython/issues/132617}: Fix @ref{165a,,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-134679@footnote{https://github.com/python/cpython/issues/134679}: Fix crash in the @ref{1f4,,free threading} build's QSBR code that
could occur when changing an object's @code{__dict__} attribute.

@item 
gh-127682@footnote{https://github.com/python/cpython/issues/127682}: No longer call @code{__iter__} twice in list comprehensions. This
brings the behavior of list comprehensions in line with other forms of
iteration

@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.
@end itemize

@node C API<5>,Build<5>,Core and Builtins<6>,Python 3 14 0 beta 3
@anchor{whatsnew/changelog id37}@anchor{17ad}
@subsubsection C API



@itemize -

@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{17ae,,PyObject_DelAttr()} and
@ref{17af,,PyObject_DelAttrString()} as macros in the limited C API 3.12 and
older. Patch by Victor Stinner.

@item 
gh-133968@footnote{https://github.com/python/cpython/issues/133968}: Add @ref{3b7,,PyUnicodeWriter_WriteASCII()} function to write an
ASCII string into a @ref{3b1,,PyUnicodeWriter}. The function is faster than
@ref{3bd,,PyUnicodeWriter_WriteUTF8()}, but has an undefined behavior if the
input string contains non-ASCII characters. Patch by Victor Stinner.
@end itemize

@node Build<5>,,C API<5>,Python 3 14 0 beta 3
@anchor{whatsnew/changelog id38}@anchor{17b0}
@subsubsection Build



@itemize -

@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-134774@footnote{https://github.com/python/cpython/issues/134774}: Fix @ref{17b1,,Py_DEBUG} macro redefinition warnings on Windows
debug builds. Patch by Chris Eibl.

@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.
@end itemize

@node Python 3 14 0 beta 2,Python 3 14 0 beta 1,Python 3 14 0 beta 3,Changelog（更動日誌）
@anchor{whatsnew/changelog python-3-14-0-beta-2}@anchor{17b2}
@subsection Python 3.14.0 beta 2


`Release date: 2025-05-26'

@menu
* Windows: Windows<6>. 
* Tools/Demos: Tools/Demos<6>. 
* Tests: Tests<4>. 
* Security: Security<7>. 
* Library: Library<8>. 
* Core and Builtins: Core and Builtins<7>. 
* C API: C API<6>. 
* Build: Build<6>. 

@end menu

@node Windows<6>,Tools/Demos<6>,,Python 3 14 0 beta 2
@anchor{whatsnew/changelog id39}@anchor{17b3}
@subsubsection Windows



@itemize -

@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{262,,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{174,,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.
@end itemize

@node Tools/Demos<6>,Tests<4>,Windows<6>,Python 3 14 0 beta 2
@anchor{whatsnew/changelog id40}@anchor{17b4}
@subsubsection Tools/Demos



@itemize -

@item 
gh-134215@footnote{https://github.com/python/cpython/issues/134215}: @ref{48c,,REPL} import autocomplete only suggests private modules
when explicitly specified.
@end itemize

@node Tests<4>,Security<7>,Tools/Demos<6>,Python 3 14 0 beta 2
@anchor{whatsnew/changelog id41}@anchor{17b5}
@subsubsection Tests



@itemize -

@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<7>,Library<8>,Tests<4>,Python 3 14 0 beta 2
@anchor{whatsnew/changelog id42}@anchor{17b6}
@subsubsection Security



@itemize -

@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-128840@footnote{https://github.com/python/cpython/issues/128840}: Short-circuit the processing of long IPv6 addresses early in
@ref{84,,ipaddress} to prevent excessive memory consumption and a minor
denial-of-service.
@end itemize

@node Library<8>,Core and Builtins<7>,Security<7>,Python 3 14 0 beta 2
@anchor{whatsnew/changelog id43}@anchor{17b7}
@subsubsection Library



@itemize -

@item 
gh-132710@footnote{https://github.com/python/cpython/issues/132710}: If possible, ensure that @ref{d9b,,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-80334@footnote{https://github.com/python/cpython/issues/80334}: @ref{17b8,,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-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{4c5,,create_unix_server()}. Contributed by Christian
Harries.

@item 
gh-134323@footnote{https://github.com/python/cpython/issues/134323}: Fix the @ref{17b9,,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-134209@footnote{https://github.com/python/cpython/issues/134209}: @ref{2f,,curses}: The @ref{17ba,,curses.window.instr()} and
@ref{17bb,,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-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{172a,,UnboundLocalError} that could occur during
@ref{3f,,email} header parsing if an expected trailing delimiter is missing
in some contexts.

@item 
gh-134168@footnote{https://github.com/python/cpython/issues/134168}: @ref{76,,http.server}: Fix IPv6 address binding and
@ref{17bc,,--directory} handling when using HTTPS.

@item 
gh-62184@footnote{https://github.com/python/cpython/issues/62184}: Remove import of C implementation of @ref{1510,,io.FileIO} from
Python implementation which has its own implementation

@item 
gh-133982@footnote{https://github.com/python/cpython/issues/133982}: Emit @ref{4d2,,RuntimeWarning} in the Python implementation of
@ref{83,,io} when the @ref{13c4,,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{e4,,tarfile} module now handles @ref{880,,UnicodeEncodeError}
in the same way as @ref{2c0,,OSError} when cannot extract a member.

@item 
gh-134097@footnote{https://github.com/python/cpython/issues/134097}: Fix interaction of the new @ref{48c,,REPL} and @ref{16f,,-X showrefcount} command line option.

@item 
gh-133889@footnote{https://github.com/python/cpython/issues/133889}: The generated directory listing page in
@ref{d30,,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{d30,,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{1d4,,forkserver} start method.
Patch by Bénédikt Tran.

@item 
gh-134062@footnote{https://github.com/python/cpython/issues/134062}: @ref{84,,ipaddress}: fix collisions in @ref{cea,,__hash__()}
for @ref{509,,IPv4Network} and @ref{50a,,IPv6Network}
objects.

@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{2eb,,ValueError} in @ref{315,,open()} if `opener' returns a
negative file-descriptor in the Python implementation of @ref{83,,io} to
match the C implementation.

@item 
gh-133960@footnote{https://github.com/python/cpython/issues/133960}: Simplify and improve @ref{1798,,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-133653@footnote{https://github.com/python/cpython/issues/133653}: Fix @ref{1bd,,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-132641@footnote{https://github.com/python/cpython/issues/132641}: Fixed a race in @ref{bd9,,functools.lru_cache()} under
free-threading.

@item 
gh-133783@footnote{https://github.com/python/cpython/issues/133783}: Fix bug with applying @ref{1c0,,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{457,,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{a6e,,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{331,,typing.TypedDict} classes defined under
@code{from __future__ import annotations} and inheriting from another
@code{TypedDict} had an incorrect @code{__annotations__} attribute.

@item 
gh-133581@footnote{https://github.com/python/cpython/issues/133581}: Improve unparsing of t-strings in @ref{ad9,,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-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-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-132493@footnote{https://github.com/python/cpython/issues/132493}: Avoid accessing @code{__annotations__} unnecessarily in
@ref{22f,,inspect.signature()}.

@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{17bd,,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{12b,,xml.etree.ElementTree}: Fix a crash in
@ref{176a,,Element.__deepcopy__} when the element is
concurrently mutated. Patch by Bénédikt Tran.

@item 
gh-91555@footnote{https://github.com/python/cpython/issues/91555}: Ignore log messages generated during handling of log messages,
to avoid deadlock or infinite recursion. [NOTE: This change has since been
reverted.]

@item 
gh-125028@footnote{https://github.com/python/cpython/issues/125028}: @ref{216,,functools.Placeholder} cannot be passed to
@ref{217,,functools.partial()} as a keyword argument.

@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{17be,,html.parser.HTMLParser.close()} no longer loses data when
the @code{<script>} tag is not closed. Patch by Waylan Limberg.

@item 
gh-69426@footnote{https://github.com/python/cpython/issues/69426}: Fix @ref{a6e,,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-28494@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28494}: Improve Zip file validation false positive rate in
@ref{152b,,zipfile.is_zipfile()}.
@end itemize

@node Core and Builtins<7>,C API<6>,Library<8>,Python 3 14 0 beta 2
@anchor{whatsnew/changelog id44}@anchor{17bf}
@subsubsection Core and Builtins



@itemize -

@item 
gh-134381@footnote{https://github.com/python/cpython/issues/134381}: Fix @ref{244,,RuntimeError} when using a not-started
@ref{176,,threading.Thread} after calling @ref{4b0,,os.fork()}

@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-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-69605@footnote{https://github.com/python/cpython/issues/69605}: When auto-completing an import in the @ref{48c,,REPL}, finding no
candidates now issues no suggestion, rather than suggestions from the
current namespace.

@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{48c,,REPL}.

@item 
gh-134119@footnote{https://github.com/python/cpython/issues/134119}: Fix crash when calling @ref{9d1,,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{17c0,,sys.modules} after its initial import. Patch by
Nico-Posada.

@item 
gh-133999@footnote{https://github.com/python/cpython/issues/133999}: Fix @ref{18e,,SyntaxError} regression in @ref{1ab,,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{16d,,sys.remote_exec()} for non-ASCII paths in non-UTF-8
locales and non-UTF-8 paths in UTF-8 locales.

@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{17c1,,__annotations__}
attributes of classes defined under @code{from __future__ import annotations}
had no effect.

@item 
gh-132762@footnote{https://github.com/python/cpython/issues/132762}: @ref{24e,,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{2eb,,ValueError} when constants @code{True}, @code{False} or
@code{None} are used as an identifier after NFKC normalization.

@item 
gh-132542@footnote{https://github.com/python/cpython/issues/132542}: Update @ref{c2a,,Thread.native_id}
after @code{fork(2)@footnote{https://manpages.debian.org/fork(2)}} to ensure accuracy. Patch by Noam Cohen.
@end itemize

@node C API<6>,Build<6>,Core and Builtins<7>,Python 3 14 0 beta 2
@anchor{whatsnew/changelog id45}@anchor{17c2}
@subsubsection C API



@itemize -

@item 
gh-134144@footnote{https://github.com/python/cpython/issues/134144}: Fix crash when calling @ref{17c3,,Py_EndInterpreter()} with a
@ref{17c4,,thread state} that isn't the initial thread for the interpreter.
@end itemize

@node Build<6>,,C API<6>,Python 3 14 0 beta 2
@anchor{whatsnew/changelog id46}@anchor{17c5}
@subsubsection Build



@itemize -

@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-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
@end itemize

@node Python 3 14 0 beta 1,Python 3 14 0 alpha 7,Python 3 14 0 beta 2,Changelog（更動日誌）
@anchor{whatsnew/changelog python-3-14-0-beta-1}@anchor{17c6}
@subsection Python 3.14.0 beta 1


`Release date: 2025-05-06'

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

@end menu

@node Windows<7>,Tools/Demos<7>,,Python 3 14 0 beta 1
@anchor{whatsnew/changelog id47}@anchor{17c7}
@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{298,,sysconfig.get_config_vars()} on
Windows. Patch by Xuehai Pan.
@end itemize

@node Tools/Demos<7>,Tests<5>,Windows<7>,Python 3 14 0 beta 1
@anchor{whatsnew/changelog id48}@anchor{17c8}
@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<5>,Security<8>,Tools/Demos<7>,Python 3 14 0 beta 1
@anchor{whatsnew/changelog id49}@anchor{17c9}
@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<8>,Library<9>,Tests<5>,Python 3 14 0 beta 1
@anchor{whatsnew/changelog id50}@anchor{17ca}
@subsubsection Security



@itemize -

@item 
gh-115322@footnote{https://github.com/python/cpython/issues/115322}: The underlying extension modules behind @ref{bf,,readline}:,
@ref{dc,,subprocess}, and @ref{2e,,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<9>,IDLE<4>,Security<8>,Python 3 14 0 beta 1
@anchor{whatsnew/changelog id51}@anchor{17cb}
@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{13f4,,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{457,,annotationlib.get_annotations()} succeed with the
@code{FORWARDREF} format if evaluating the annotations throws an exception
other than @ref{450,,NameError} or @ref{5e8,,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{17cc,,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{17cd,,fnmatch.translate()} and
@ref{4f6,,glob.translate()}.

@item 
gh-133306@footnote{https://github.com/python/cpython/issues/133306}: Support @code{\z} as a synonym for @code{\Z} in @ref{be,,regular expressions}.

@item 
gh-133300@footnote{https://github.com/python/cpython/issues/133300}: Make @ref{1bd,,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{17ce,,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
@ref{aa,,pdb}.

@item 
gh-133139@footnote{https://github.com/python/cpython/issues/133139}: Add the @ref{1f6,,curses.assume_default_colors()} function, a
refinement of the @ref{1f7,,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{17cf,,subprocess.TimeoutExpired}
when the func @ref{d79,,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{314,,codecs.open()} is now deprecated. Use @ref{315,,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{19e,,__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{1072,,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{db,,struct} module.  Patch by Sergey B
Kirpichev.

@item 
gh-132915@footnote{https://github.com/python/cpython/issues/132915}: @ref{17d0,,fcntl.fcntl()} and @ref{166f,,fcntl.ioctl()} can now detect a
buffer overflow and raise @ref{78e,,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{17d1,,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{2a8,,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{17d0,,fcntl.fcntl()} now supports arbitrary @ref{193,,bytes-like objects}, not only @ref{192,,bytes}. @ref{166f,,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{1785,,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{d1,,sockets}.

@item 
gh-132673@footnote{https://github.com/python/cpython/issues/132673}: Fix @ref{8b0,,AssertionError} raised on @ref{1e5,,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{17d2,,multiprocessing.Lock}
and @ref{17d3,,multiprocessing.RLock} classes.

@item 
gh-121468@footnote{https://github.com/python/cpython/issues/121468}: Add @ref{279,,pdb.set_trace_async()} function to support
@ref{18d,,await} statements in @ref{aa,,pdb}.

@item 
gh-132493@footnote{https://github.com/python/cpython/issues/132493}: @ref{565,,typing.Protocol} now uses
@ref{457,,annotationlib.get_annotations()} when checking whether or not an
instance implements the protocol with @ref{2ad,,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{17d4,,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{4b9,,array.array}.

@item 
gh-132099@footnote{https://github.com/python/cpython/issues/132099}: The Bluetooth socket with the @ref{281,,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{12f0,,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{565,,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{17d5,,annotationlib.type_repr()} and provide better handling for function
objects.

@item 
gh-132426@footnote{https://github.com/python/cpython/issues/132426}: Add @ref{459,,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{281,,BTPROTO_HCI}).

@item 
gh-131913@footnote{https://github.com/python/cpython/issues/131913}: Add a shortcut function
@ref{251,,multiprocessing.Process.interrupt()} alongside the existing
@ref{17d6,,multiprocessing.Process.terminate()} and
@ref{d47,,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{243,,QueueListener.start} now raises a @ref{244,,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{2e,,ctypes} with @code{restype} @ref{1f3,,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{6f3,,object.__getattr__()} in @ref{104,,traceback}.

@item 
gh-125866@footnote{https://github.com/python/cpython/issues/125866}: Add optional `add_scheme' argument to
@ref{2bf,,urllib.request.pathname2url()}; when set to true, a complete URL is
returned. Likewise add optional `require_scheme' argument to
@ref{2bd,,url2pathname()}; when set to true, a complete URL is
accepted.

@item 
gh-132308@footnote{https://github.com/python/cpython/issues/132308}: A @ref{55d,,traceback.TracebackException} now correctly renders
the @code{__context__} and @code{__cause__} attributes from @ref{17d7,,falsey} @ref{bc4,,Exception}, and the @code{exceptions} attribute from falsey
@ref{4cd,,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{17d8,,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{78e,,SystemError} in @ref{2b,,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{457,,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{198,,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{1fe,,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{1d6,,concurrent.futures.ProcessPoolExecutor}
and @ref{941,,concurrent.futures.ThreadPoolExecutor}.

@item 
gh-132106@footnote{https://github.com/python/cpython/issues/132106}: @ref{242,,logging.handlers.QueueListener} now implements the
context manager protocol, allowing it to be used in a @ref{186,,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{22f,,inspect.signature()}. Preserve class signature after wrapping with
@ref{484,,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{c9,,shlex} module,
and improve the performance of @ref{57c,,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{282,,BTPROTO_SCO} in sockets on
FreeBSD.

@item 
gh-131757@footnote{https://github.com/python/cpython/issues/131757}: Make @ref{bd9,,functools.lru_cache()} call the cached function
unlocked to allow concurrency.

@item 
gh-131423@footnote{https://github.com/python/cpython/issues/131423}: @ref{d5,,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{1624,,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{1f1,,ctypes.POINTER()} types cache from a global internal
cache (@code{_pointer_type_cache}) to the
@ref{1f2,,ctypes._CData.__pointer_type__} attribute of the corresponding
@ref{2e,,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{1254,,IsADirectoryError}.

@item 
gh-123471@footnote{https://github.com/python/cpython/issues/123471}: Make concurrent iterations over @ref{17d9,,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{821,,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{4d9,,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{6d,,heapq} max-heap functions @ref{221,,heapq.heapify_max()},
@ref{222,,heapq.heappush_max()}, @ref{223,,heapq.heappop_max()}, and
@ref{224,,heapq.heapreplace_max()} public. Previous underscored naming is kept
for backwards compatibility. Additionally, the missing function
@ref{225,,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{4ac,,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{21d,,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{961,,PyFloat_Pack2()} and @ref{964,,PyFloat_Unpack2()} for
NaN's with payload.  This corrects round-trip for @ref{17da,,struct.unpack()}
and @ref{1477,,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{473,,PythonFinalizationError}.

@item 
gh-130167@footnote{https://github.com/python/cpython/issues/130167}: Improve speed of @ref{2d7,,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{92,,math} module.

@item 
gh-128384@footnote{https://github.com/python/cpython/issues/128384}: Make @ref{179,,warnings.catch_warnings} use a context variable
for holding the warning filtering state if the
@ref{18a,,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 the @ref{16f,,-X context_aware_warnings} command-line option or by the
@geindex PYTHON_CONTEXT_AWARE_WARNINGS
@geindex 環境變數; PYTHON_CONTEXT_AWARE_WARNINGS
@ref{17db,,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{1a3,,DeprecationWarning} for
@ref{292,,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{1ca,,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{20e,,faulthandler.dump_c_stack()} or via the `c_stack'
argument in @ref{20f,,faulthandler.enable()}.

@item 
gh-127385@footnote{https://github.com/python/cpython/issues/127385}: Add the @code{F_DUPFD_QUERY} constant to the @ref{5d,,fcntl} module.

@item 
gh-126838@footnote{https://github.com/python/cpython/issues/126838}: Add `resolve_host' keyword-only parameter to
@ref{2bd,,urllib.request.url2pathname()}, and fix handling of file URLs with
authorities.

@item 
gh-82129@footnote{https://github.com/python/cpython/issues/82129}: Fix @ref{450,,NameError} when calling @ref{8b9,,typing.get_type_hints()}
on a @ref{4dc,,dataclasses.dataclass()} created by
@ref{17dc,,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{198,,TypeError} in the C implementation of
@ref{1510,,io.FileIO}, @ref{140f,,io.BufferedReader}, @ref{15a9,,io.BufferedWriter}
and @ref{15aa,,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{84d,,hashlib.file_digest()} now raises @ref{235,,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{1ff,,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{11b,,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{2f,,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{318,,mimetypes.MimeTypes.add_type()}. Patch by Hugo van Kemenade.
@end itemize

@node IDLE<4>,Documentation<4>,Library<9>,Python 3 14 0 beta 1
@anchor{whatsnew/changelog id52}@anchor{17dd}
@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<4>,Core and Builtins<8>,IDLE<4>,Python 3 14 0 beta 1
@anchor{whatsnew/changelog id53}@anchor{17de}
@subsubsection Documentation



@itemize -

@item 
gh-107006@footnote{https://github.com/python/cpython/issues/107006}: Move documentation and example code for
@ref{17df,,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<8>,C API<7>,Documentation<4>,Python 3 14 0 beta 1
@anchor{whatsnew/changelog id54}@anchor{17e0}
@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{962,,PyFloat_Pack4()}
and @ref{965,,PyFloat_Unpack4()} on RISC-V.

@item 
gh-133197@footnote{https://github.com/python/cpython/issues/133197}: Improve @ref{18e,,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{44d,,sys._jit.is_available()}, @ref{44e,,sys._jit.is_enabled()}, and
@ref{17e1,,sys._jit.is_active()}.

@item 
gh-133194@footnote{https://github.com/python/cpython/issues/133194}: @ref{1c2,,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.

@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{83,,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{183,,dict}
and @ref{184,,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{4b0,,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{16dc,,__get__()} of a
@ref{17e2,,method} with a @ref{87e,,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.

@item 
gh-132737@footnote{https://github.com/python/cpython/issues/132737}: Support profiling code that requires @code{__main__}, such as
@ref{ab,,pickle}.

@item 
gh-132639@footnote{https://github.com/python/cpython/issues/132639}: Added @ref{5fe,,PyLong_AsNativeBytes()},
@ref{5ff,,PyLong_FromNativeBytes()} and
@ref{600,,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{118,,warnings}
filters.

@item 
gh-132457@footnote{https://github.com/python/cpython/issues/132457}: Make @ref{451,,staticmethod()} and @ref{489,,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{49d,,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{17e3,,type.__annotate__} was not deleted, when
@ref{17c1,,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{789,,Py_DECREF()}. Third-party extension objects no longer need to use
the "trashcan" mechanism, as protection is now built into the
@ref{789,,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{185,,async with} (resp. @ref{186,,with}) instead of @ref{186,,with}
(resp. @ref{185,,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{1a4,,pow()} now try calling
@ref{1a5,,__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{49d,,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{175,,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{176,,threading.Thread} will, by default, use a copy of the
@ref{177,,contextvars.Context} from the caller of
@ref{178,,threading.Thread.start()} rather than using an empty context.

@item 
Add the @ref{16f,,-X thread_inherit_context} command-line option and
@geindex PYTHON_THREAD_INHERIT_CONTEXT
@geindex 環境變數; PYTHON_THREAD_INHERIT_CONTEXT
@ref{17e4,,PYTHON_THREAD_INHERIT_CONTEXT} environment variable, which set the
@ref{175,,thread_inherit_context} flag.

@item 
Add the @code{context} keyword parameter to @ref{176,,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{18e,,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{16f,,-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{198,,TypeError} occurs during
@ref{165a,,dict.update()}

@item 
gh-103997@footnote{https://github.com/python/cpython/issues/103997}: String arguments passed to "-c" are now automatically dedented
as if by @ref{1a9,,textwrap.dedent()}. This allows "python -c" invocations to
be indented in shell scripts without causing indentation errors. (Patch by
Jon Crall and Steven Sun)

@item 
gh-89562@footnote{https://github.com/python/cpython/issues/89562}: Remove @code{hostflags} member from @code{PySSLContext} struct.
@end itemize

@node C API<7>,Build<7>,Core and Builtins<8>,Python 3 14 0 beta 1
@anchor{whatsnew/changelog id55}@anchor{17e5}
@subsubsection C API



@itemize -

@item 
gh-133166@footnote{https://github.com/python/cpython/issues/133166}: Fix regression where @ref{62d,,PyType_GetModuleByDef()} returns
NULL without setting @ref{198,,TypeError} when a static type is passed.

@item 
gh-133164@footnote{https://github.com/python/cpython/issues/133164}: Add @ref{3c5,,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{2cf,,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{3c4,,PyUnstable_Object_IsUniquelyReferenced()} as a
replacement for @code{Py_REFNCT(op) == 1} on @ref{1f4,,free threaded} builds of Python.

@item 
gh-131747@footnote{https://github.com/python/cpython/issues/131747}: On non-Windows platforms, deprecate using
@ref{316,,ctypes.Structure._pack_} to use a Windows-compatible layout on
non-Windows platforms. The layout should be specified explicitly by
setting @ref{1e7,,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{1376,,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{1791,,PyArg_Parse()} now
support the @ref{19e,,__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{17e6,,K} format in @ref{3c0,,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{1e8,,ctypes.CField} with a `byte_size' that does
not match the actual type size now raises a @ref{2eb,,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{1791,,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{3bf,,PyArg_ParseTuple()} and other
@ref{3d3,,argument parsing} functions if `items' contains format
units which store a @ref{3d4,,borrowed buffer} or a
@ref{3d5,,borrowed reference}.
@end itemize

@node Build<7>,,C API<7>,Python 3 14 0 beta 1
@anchor{whatsnew/changelog id56}@anchor{17e7}
@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{17e8}
@subsection Python 3.14.0 alpha 7


`Release date: 2025-04-08'

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

@end menu

@node macOS<3>,Windows<8>,,Python 3 14 0 alpha 7
@anchor{whatsnew/changelog id57}@anchor{17e9}
@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<8>,Tools/Demos<8>,macOS<3>,Python 3 14 0 alpha 7
@anchor{whatsnew/changelog id58}@anchor{17ea}
@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{11d,,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{139,,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<8>,Tests<6>,Windows<8>,Python 3 14 0 alpha 7
@anchor{whatsnew/changelog id59}@anchor{17eb}
@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<6>,Security<9>,Tools/Demos<8>,Python 3 14 0 alpha 7
@anchor{whatsnew/changelog id60}@anchor{17ec}
@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{17ed,,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<9>,Library<10>,Tests<6>,Python 3 14 0 alpha 7
@anchor{whatsnew/changelog id61}@anchor{17ee}
@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<10>,Documentation<5>,Security<9>,Python 3 14 0 alpha 7
@anchor{whatsnew/changelog id62}@anchor{17ef}
@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{dc,,subprocess} to control the use of
@ref{529,,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{484,,warnings.deprecated}. Patch by Xuehai Pan.

@item 
gh-132168@footnote{https://github.com/python/cpython/issues/132168}: The @ref{1f3,,ctypes.py_object} type now supports subscription,
making it a @ref{1a1,,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{8cb,,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{d1,,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{d8,,string} module.
Patch by Adam Turner.

@item 
gh-125434@footnote{https://github.com/python/cpython/issues/125434}: Display thread name in @ref{5c,,faulthandler}. Patch by Victor
Stinner.

@item 
gh-132002@footnote{https://github.com/python/cpython/issues/132002}: Fix crash when deallocating @ref{17f0,,contextvars.ContextVar}
with weird unahashable string names.

@item 
gh-131938@footnote{https://github.com/python/cpython/issues/131938}: @ref{12b,,xml.etree.ElementTree}: update the error message when an
element to remove via @ref{17f1,,Element.remove} is not found. Patch by Bénédikt
Tran.

@item 
gh-115942@footnote{https://github.com/python/cpython/issues/115942}: Add @ref{17b9,,threading.RLock.locked()},
@ref{17f2,,multiprocessing.Lock.locked()}, @ref{17f3,,multiprocessing.RLock.locked()},
and allow @ref{158f,,multiprocessing.managers.SyncManager.Lock()} and
@ref{1590,,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{2e,,ctypes} on the
@ref{1f4,,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{ad9,,unparse()} function to a helper module.

@item 
gh-107369@footnote{https://github.com/python/cpython/issues/107369}: Improved performance of @ref{577,,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{1a9,,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{d1,,socket}: Fix code parsing AF_BLUETOOTH socket addresses.

@item 
gh-60115@footnote{https://github.com/python/cpython/issues/60115}: Support frozen modules for @ref{240,,linecache.getline()}.

@item 
gh-131492@footnote{https://github.com/python/cpython/issues/131492}: Fix a resource leak when constructing a @ref{654,,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{1430,,random.randint()}.

@item 
gh-131461@footnote{https://github.com/python/cpython/issues/131461}: Fix @ref{547,,ResourceWarning} when constructing a
@ref{654,,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{2bd,,urllib.request.url2pathname()} and
@ref{2bf,,pathname2url()} instead.

@item 
gh-126367@footnote{https://github.com/python/cpython/issues/126367}: Fix issue where @ref{2bd,,urllib.request.url2pathname()} raised
@ref{2c0,,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{177b,,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{ef8,,warnings.warn_explicit()}.

@item 
gh-70647@footnote{https://github.com/python/cpython/issues/70647}: When creating a @ref{34,,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{21f,,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{2c7,,python -m uuid --count}.

@item 
gh-126895@footnote{https://github.com/python/cpython/issues/126895}: Fix @ref{bf,,readline} in @ref{1f4,,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{8a,,locale} using lazy import @code{re}.
Patch by Semyon Moroz.

@item 
gh-129598@footnote{https://github.com/python/cpython/issues/129598}: Fix @ref{ad9,,ast.unparse()} when @ref{17f4,,ast.Interactive} contains
multiple statements.

@item 
gh-85162@footnote{https://github.com/python/cpython/issues/85162}: The @ref{76,,http.server} module now includes built-in support for
HTTPS servers exposed by @ref{228,,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{17d8,,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{17d8,,annotationlib.ForwardRef} objects no longer cache their
value when they are successfully evaluated. Successive calls to
@ref{1785,,annotationlib.ForwardRef.evaluate()} may return different values.

@item 
gh-117779@footnote{https://github.com/python/cpython/issues/117779}: Fix reading duplicated entries in @ref{137,,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{1e5,,Structure}/@ref{1e6,,Union}
field descriptors is now available as @ref{1e8,,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{12b,,xml.etree.ElementTree}: Fix a crash in
@ref{17f5,,Element.find},
@ref{17f6,,Element.findtext} and
@ref{17f7,,Element.findall} when the
tag to find implements an @ref{ce9,,__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{57b,,email.message.Message}
objects, either through @ref{17f8,,email.message.Message.__setitem__()} or
@ref{17f9,,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{2eb,,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{31b,,pathlib.Path.as_uri()} instead.

@item 
gh-126033@footnote{https://github.com/python/cpython/issues/126033}: @ref{12b,,xml.etree.ElementTree}: Fix a crash in
@ref{17f1,,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{211,,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<5>,Core and Builtins<9>,Library<10>,Python 3 14 0 alpha 7
@anchor{whatsnew/changelog id63}@anchor{17fa}
@subsubsection Documentation



@itemize -

@item 
gh-131417@footnote{https://github.com/python/cpython/issues/131417}: Mention @ref{dc1,,asyncio.Future} and @ref{1c7,,asyncio.Task} in
generic classes list.
@end itemize

@node Core and Builtins<9>,C API<8>,Documentation<5>,Python 3 14 0 alpha 7
@anchor{whatsnew/changelog id64}@anchor{17fb}
@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{8d4,,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{17fc,,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{16d,,sys.remote_exec()} function to the @ref{df,,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{1f4,,free-threaded} build.

@item 
gh-131670@footnote{https://github.com/python/cpython/issues/131670}: Fix @ref{9cf,,anext()} failing on sync @ref{17fd,,__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{3a1,,PyLong_FromInt32()}, @ref{3a3,,PyLong_FromUInt32()},
@ref{3a2,,PyLong_FromInt64()} and @ref{3a4,,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.

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

@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{f37,,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{b34,,range} by using a freelist.
@end itemize

@node C API<8>,Build<8>,Core and Builtins<9>,Python 3 14 0 alpha 7
@anchor{whatsnew/changelog id65}@anchor{17fe}
@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<8>,,C API<8>,Python 3 14 0 alpha 7
@anchor{whatsnew/changelog id66}@anchor{17ff}
@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{1800}
@subsection Python 3.14.0 alpha 6


`Release date: 2025-03-14'

@menu
* macOS: macOS<4>. 
* Windows: Windows<9>. 
* Tools/Demos: Tools/Demos<9>. 
* Tests: Tests<7>. 
* Security: Security<10>. 
* Library: Library<11>. 
* Documentation: Documentation<6>. 
* Core and Builtins: Core and Builtins<10>. 
* C API: C API<9>. 
* Build: Build<9>. 

@end menu

@node macOS<4>,Windows<9>,,Python 3 14 0 alpha 6
@anchor{whatsnew/changelog id67}@anchor{1801}
@subsubsection macOS



@itemize -

@item 
gh-128540@footnote{https://github.com/python/cpython/issues/128540}: Ensure web browser is launched by @ref{1802,,webbrowser.open()} on
macOS, even for @code{file://} URLs.
@end itemize

@node Windows<9>,Tools/Demos<9>,macOS<4>,Python 3 14 0 alpha 6
@anchor{whatsnew/changelog id68}@anchor{1803}
@subsubsection Windows



@itemize -

@item 
gh-131020@footnote{https://github.com/python/cpython/issues/131020}: pylauncher@footnote{https://github.com/python/cpython/tree/3.14/PC/launcher2.c} correctly detects a BOM
when searching for the shebang. Fix by Chris Eibl.
@end itemize

@node Tools/Demos<9>,Tests<7>,Windows<9>,Python 3 14 0 alpha 6
@anchor{whatsnew/changelog id69}@anchor{1804}
@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<7>,Security<10>,Tools/Demos<9>,Python 3 14 0 alpha 6
@anchor{whatsnew/changelog id70}@anchor{1805}
@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{17d3,,multiprocessing.RLock}.

@item 
gh-126332@footnote{https://github.com/python/cpython/issues/126332}: Add unit tests for pyrepl.
@end itemize

@node Security<10>,Library<11>,Tests<7>,Python 3 14 0 alpha 6
@anchor{whatsnew/changelog id71}@anchor{1806}
@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<11>,Documentation<6>,Security<10>,Python 3 14 0 alpha 6
@anchor{whatsnew/changelog id72}@anchor{1807}
@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{201,,difflib.HtmlDiff}.

@item 
gh-131196@footnote{https://github.com/python/cpython/issues/131196}: Improve performance of @ref{1808,,uuid.UUID.hex} and
@ref{829,,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{8a4,,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{82e,,enum.Flag}.

@item 
gh-130959@footnote{https://github.com/python/cpython/issues/130959}: Fix pure-Python implementation of
@ref{822,,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{654,,gzip.GzipFile} before it is closed now emits a
@ref{547,,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{1d0,,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{1809,,code.interact()} call.

@item 
gh-130608@footnote{https://github.com/python/cpython/issues/130608}: Remove `dirs_exist_ok' argument from @ref{267,,pathlib.Path.copy()}
and @ref{268,,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{116,,uuid} module
documentation. These directives previously created entries in the general
index for @ref{d9b,,getnode()} as well as the @ref{d9c,,uuid1()},
@ref{2e4,,uuid3()}, @ref{2e6,,uuid4()}, @ref{2e5,,uuid5()}, and
@ref{2c4,,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{271,,breakpoint()} or
@ref{272,,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{267,,pathlib.Path.copy()} or
@ref{269,,move()} has fresh @ref{26b,,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{267,,Path.copy} by making better
use of @ref{26b,,info} internally.

@item 
gh-130285@footnote{https://github.com/python/cpython/issues/130285}: Fix corner case for @ref{945,,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{278,,bdb.BdbQuit} when @ref{aa,,pdb} is started from an interactive console
using @ref{271,,breakpoint()} or @ref{272,,pdb.set_trace()}.

@item 
gh-107773@footnote{https://github.com/python/cpython/issues/107773}: Make @ref{34,,datetime} subclass @ref{828,,__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{50c,,itertools.batched} safe
under free-threading.

@item 
gh-57537@footnote{https://github.com/python/cpython/issues/57537}: Support breakpoints for @ref{138,,zipimport} modules on @ref{aa,,pdb}

@item 
gh-130230@footnote{https://github.com/python/cpython/issues/130230}: Fix crash in @ref{1a4,,pow()} with only @ref{1fe,,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{bda,,functools.singledispatchmethod} methods
and descriptors.

@item 
gh-128520@footnote{https://github.com/python/cpython/issues/128520}: Apply type conversion consistently in @ref{6c6,,pathlib.PurePath}
and @ref{266,,Path} methods can accept a path object as an
argument, such as @ref{6cc,,match()} and
@ref{180a,,rename()}. The argument is now converted to path object
if it lacks a @ref{6c7,,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{dc,,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{198,,TypeError} in
@ref{180b,,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{1c2,,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{822,,datetime.time.fromisoformat()} and
@ref{823,,datetime.datetime.fromisoformat()}. Patch by Semyon Moroz.

@item 
gh-85795@footnote{https://github.com/python/cpython/issues/85795}: Using @ref{1a6,,super()} and @code{__class__} @ref{180c,,closure variable}
in user-defined methods of @ref{330,,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{82,,inspect} and removing @ref{d8,,string}. Patch by Semyon Moroz.

@item 
gh-129726@footnote{https://github.com/python/cpython/issues/129726}: Fix @ref{654,,gzip.GzipFile} raising an unraisable exception
during garbage collection when referring to a temporary object by breaking
the reference loop with @ref{11a,,weakref}.

@item 
gh-127750@footnote{https://github.com/python/cpython/issues/127750}: Remove broken @ref{bda,,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{184,,set} to
@ref{180d,,multiprocessing.managers.SyncManager} via @ref{24f,,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{1e2,,contextvars.Token}.
Patch by Andrew Svetlov.

@item 
gh-97850@footnote{https://github.com/python/cpython/issues/97850}: Update the deprecation warning of
@ref{a62,,importlib.abc.Loader.load_module()}.

@item 
gh-129678@footnote{https://github.com/python/cpython/issues/129678}: @ref{4d9,,configparser.ConfigParser}: do not write an empty
unnamed section

@item 
gh-128641@footnote{https://github.com/python/cpython/issues/128641}: Restore @ref{165d,,configparser.ConfigParser.read()} performance.

@item 
gh-129569@footnote{https://github.com/python/cpython/issues/129569}: Fix @ref{8dc,,unicodedata.normalize()} to always return a built-in
@ref{169,,str} object when given an input of a @ref{169,,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{107c,,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{d1,,socket} @code{BTPROTO_L2CAP} sockaddr tuple.

@item 
gh-128703@footnote{https://github.com/python/cpython/issues/128703}: Fix @ref{512,,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{654,,gzip.GzipFile}'s
@ref{180e,,readinto()} and
@ref{1017,,readinto1()} implementations, avoiding unnecessary
allocations. Patch by Chris Markiewicz.

@item 
gh-128184@footnote{https://github.com/python/cpython/issues/128184}: Improve display of @ref{17d8,,annotationlib.ForwardRef} object
within @ref{4de,,inspect.Signature} representations. This also fixes a
@ref{450,,NameError} that was raised when using @ref{4dc,,dataclasses.dataclass()}
on classes with unresolvable forward references.

@item 
gh-128041@footnote{https://github.com/python/cpython/issues/128041}: Add
@ref{1da,,concurrent.futures.ProcessPoolExecutor.terminate_workers()} and
@ref{1db,,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{236,,io.Reader} and @ref{237,,io.Writer} as
alternatives to @ref{238,,typing.IO}, @ref{239,,typing.TextIO}, and
@ref{23a,,typing.BinaryIO}.

@item 
gh-109798@footnote{https://github.com/python/cpython/issues/109798}: Added additional information into error messages in
@ref{34,,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 @ref{337,,zipimport.zipimporter.load_module()}
removal time to 3.15. Use @ref{338,,zipimport.zipimporter.exec_module()}
instead.

@item 
gh-74028@footnote{https://github.com/python/cpython/issues/74028}: Add the optional @code{buffersize} parameter to
@ref{1dc,,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{2c3,,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{2c2,,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{315,,open()} on platforms where @ref{f87,,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{2a7,,types.UnionType} an alias for
@ref{2a8,,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<6>,Core and Builtins<10>,Library<11>,Python 3 14 0 alpha 6
@anchor{whatsnew/changelog id73}@anchor{180f}
@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{1810,,PyUnicode_RSplit()},
@ref{1811,,PyUnicode_Partition()} and @ref{1812,,PyUnicode_RPartition()}.
@end itemize

@node Core and Builtins<10>,C API<9>,Documentation<6>,Python 3 14 0 alpha 6
@anchor{whatsnew/changelog id74}@anchor{1813}
@subsubsection Core and Builtins



@itemize -

@item 
gh-131141@footnote{https://github.com/python/cpython/issues/131141}: Fix data race in @ref{e0,,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{16f2,,sys.setprofile()} and @ref{2e1,,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{1f4,,free threading} build when
constructing a @ref{1b,,code} object with @ref{1814,,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{1f4,,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{5b3,,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{df,,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{469,,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{343,,bytearray} functions for @ref{1f4,,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{d35,,ModuleNotFoundError}.

@item 
gh-129107@footnote{https://github.com/python/cpython/issues/129107}: Make @ref{343,,bytearray} iterator safe under @ref{1f4,,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.

@item 
gh-129983@footnote{https://github.com/python/cpython/issues/129983}: Fix data race in compile_template in @code{sre.c}.

@item 
gh-129967@footnote{https://github.com/python/cpython/issues/129967}: Fix a race condition in the @ref{1f4,,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{181,,if} or after an
@ref{17c,,else} keyword.

@item 
gh-129349@footnote{https://github.com/python/cpython/issues/129349}: @ref{190,,bytes.fromhex()} and @ref{191,,bytearray.fromhex()} now accepts
ASCII @ref{192,,bytes} and @ref{193,,bytes-like objects}.

@item 
gh-129149@footnote{https://github.com/python/cpython/issues/129149}: Add fast path for medium-size integers in
@ref{1815,,PyLong_FromSsize_t()}. Patch by Chris Eibl.

@item 
gh-129107@footnote{https://github.com/python/cpython/issues/129107}: Make the @ref{343,,bytearray} safe under @ref{1f4,,free threading}.

@item 
gh-128974@footnote{https://github.com/python/cpython/issues/128974}: Fix a crash in @ref{829,,UnicodeError.__str__}
when custom attributes implement @ref{829,,__str__()} with
side-effects. Patch by Bénédikt Tran.

@item 
gh-126085@footnote{https://github.com/python/cpython/issues/126085}: @ref{2ae,,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{4ac,,compile()}. Patch by Pablo Galindo.

@item 
gh-121464@footnote{https://github.com/python/cpython/issues/121464}: Make concurrent iterations over the same @ref{1675,,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{199,,format()} or @ref{19a,,f-string（f 字串）}).  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{482,,typing.ParamSpec} and have been specialized with a nested type
variable.

@item 
gh-120608@footnote{https://github.com/python/cpython/issues/120608}: Adapt @ref{a5e,,reversed()} for use in the free-threading build. The
@ref{a5e,,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.

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

@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<9>,Build<9>,Core and Builtins<10>,Python 3 14 0 alpha 6
@anchor{whatsnew/changelog id75}@anchor{1816}
@subsubsection C API



@itemize -

@item 
gh-111178@footnote{https://github.com/python/cpython/issues/111178}: Fix @ref{960,,PyCMethod} API: replace @code{size_t nargs} with
@code{Py_ssize_t nargs} in @ref{960,,PyCMethod}. Patch by Victor Stinner.

@item 
gh-130947@footnote{https://github.com/python/cpython/issues/130947}: Add again @ref{1817,,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{3b2,,writer = PyUnicodeWriter_Create(0)}.

@item 
@code{_PyUnicodeWriter_Finish()}:
replace @code{_PyUnicodeWriter_Finish(&writer)} with
@ref{3b5,,PyUnicodeWriter_Finish(writer)}.

@item 
@code{_PyUnicodeWriter_Dealloc()}:
replace @code{_PyUnicodeWriter_Dealloc(&writer)} with
@ref{3b4,,PyUnicodeWriter_Discard(writer)}.

@item 
@code{_PyUnicodeWriter_WriteChar()}:
replace @code{_PyUnicodeWriter_WriteChar(&writer, ch)} with
@ref{3b8,,PyUnicodeWriter_WriteChar(writer@comma{} ch)}.

@item 
@code{_PyUnicodeWriter_WriteStr()}:
replace @code{_PyUnicodeWriter_WriteStr(&writer, str)} with
@ref{3ba,,PyUnicodeWriter_WriteStr(writer@comma{} str)}.

@item 
@code{_PyUnicodeWriter_WriteSubstring()}:
replace @code{_PyUnicodeWriter_WriteSubstring(&writer, str, start, end)} with
@ref{3bb,,PyUnicodeWriter_WriteSubstring(writer@comma{} str@comma{} start@comma{} end)}.

@item 
@code{_PyUnicodeWriter_WriteASCIIString()}:
replace @code{_PyUnicodeWriter_WriteASCIIString(&writer, str)} with
@ref{3bd,,PyUnicodeWriter_WriteUTF8(writer@comma{} str)}.

@item 
@code{_PyUnicodeWriter_WriteLatin1String()}:
replace @code{_PyUnicodeWriter_WriteLatin1String(&writer, str)} with
@ref{3bd,,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{3c0,,Py_BuildValue()} that
allows to take a C integer and produce a Python @ref{3c1,,bool} object.
Patch by Pablo Galindo.
@end itemize

@node Build<9>,,C API<9>,Python 3 14 0 alpha 6
@anchor{whatsnew/changelog id76}@anchor{1818}
@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{442,,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{1819}
@subsection Python 3.14.0 alpha 5


`Release date: 2025-02-11'

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

@end menu

@node macOS<5>,Tools/Demos<10>,,Python 3 14 0 alpha 5
@anchor{whatsnew/changelog id77}@anchor{181a}
@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<10>,Tests<8>,macOS<5>,Python 3 14 0 alpha 5
@anchor{whatsnew/changelog id78}@anchor{181b}
@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<8>,Security<11>,Tools/Demos<10>,Python 3 14 0 alpha 5
@anchor{whatsnew/changelog id79}@anchor{181c}
@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<11>,Library<12>,Tests<8>,Python 3 14 0 alpha 5
@anchor{whatsnew/changelog id80}@anchor{181d}
@subsubsection Security



@itemize -

@item 
gh-105704@footnote{https://github.com/python/cpython/issues/105704}: When using @ref{f35,,urllib.parse.urlsplit()} and
@ref{360,,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{78,,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{181e,,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<12>,IDLE<5>,Security<11>,Python 3 14 0 alpha 5
@anchor{whatsnew/changelog id81}@anchor{181f}
@subsubsection Library



@itemize -

@item 
gh-129939@footnote{https://github.com/python/cpython/issues/129939}: Comparison pages with highlighted changes generated by the
@ref{201,,difflib.HtmlDiff} class now support dark mode.

@item 
gh-129928@footnote{https://github.com/python/cpython/issues/129928}: Raise @ref{304,,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{118,,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{8a,,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{1820,,calendar.TextCalendar} API. Patch by
Hugo van Kemenade.

@item 
gh-129603@footnote{https://github.com/python/cpython/issues/129603}: Fix bugs where @ref{106c,,sqlite3.Row} objects could segfault if
their inherited @ref{1821,,description} was set to @code{None}.
Patch by Erlend Aasland.

@item 
gh-129559@footnote{https://github.com/python/cpython/issues/129559}: Add @ref{1822,,bytearray.resize()} method so @ref{343,,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{2e,,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{502,,sys.unraisablehook()} instead of @ref{a05,,sys.excepthook()} and not
setting @ref{6de,,sys.last_exc} and other variables.

@item 
gh-129403@footnote{https://github.com/python/cpython/issues/129403}: Corrected @ref{2eb,,ValueError} message for
@ref{80f,,asyncio.Barrier} and @ref{13e4,,threading.Barrier}.

@item 
gh-129409@footnote{https://github.com/python/cpython/issues/129409}: Fix an integer overflow in the @ref{2d,,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{865,,logging.handlers.SysLogHandler}.

@item 
gh-118761@footnote{https://github.com/python/cpython/issues/118761}: Always lazy import @code{warnings} in @ref{f3,,threading}. Patch by
Taneli Hukkinen.

@item 
gh-118761@footnote{https://github.com/python/cpython/issues/118761}: Improve import time of @ref{dc,,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{d4,,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{25f,,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{25f,,os.readinto()} to read into a @ref{260,,buffer object} from a file descriptor.

@item 
gh-128772@footnote{https://github.com/python/cpython/issues/128772}: Fix @ref{ba,,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{32c,,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{33f,,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{4cc,,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{b5,,pstats} and @ref{137,,zipfile} by up to
20%, by removing unnecessary imports to @ref{10a,,typing}. Patch by Bénédikt
Tran.

@item 
gh-128978@footnote{https://github.com/python/cpython/issues/128978}: Fix a @ref{450,,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{4b9,,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{102,,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{105,,tracemalloc}: Fix race conditions when
@ref{1823,,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{67,,gettext} by up to ten times, by
importing @ref{be,,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{1824,,hashlib.sha256()} under @ref{1f4,,free threading}.

@item 
gh-118761@footnote{https://github.com/python/cpython/issues/118761}: Reduce the import time of @ref{2d,,csv} by up to five times, by
importing @ref{be,,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{1ca,,asyncio.loop.create_task()},  @ref{1c9,,asyncio.create_task()} and
@ref{1cb,,asyncio.TaskGroup.create_task()}, by passing on all `kwargs' to the
task factory set by @ref{1c8,,asyncio.loop.set_task_factory()}.

@item 
gh-118761@footnote{https://github.com/python/cpython/issues/118761}: Improve the performance of @ref{2d3,,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{be,,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{2e,,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{259,,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{118,,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 @ref{118,,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{28f,,sys._is_immortal()} for identifying @ref{290,,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{2c5,,uuid.NIL} and @ref{2c6,,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{2cc,,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{1825,,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{655,,ZipFile.open}.

@item 
gh-127975@footnote{https://github.com/python/cpython/issues/127975}: Avoid reusing quote types in @ref{ad9,,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{1826,,importlib.machinery.DEBUG_BYTECODE_SUFFIXES},
@ref{1827,,importlib.machinery.OPTIMIZED_BYTECODE_SUFFIXES},
@ref{f21,,importlib.machinery.WindowsRegistryFinder},
@ref{ddd,,importlib.abc.ResourceLoader},
@ref{138a,,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{26b,,pathlib.Path.info} attribute, which stores an object
implementing the @ref{26c,,pathlib.types.PathInfo} protocol (also new). The
object supports querying the file type and internally caching
@ref{26d,,stat()} results. Path objects generated by
@ref{26e,,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{1828,,logging.handlers.SMTPHandler}.

@item 
gh-127096@footnote{https://github.com/python/cpython/issues/127096}: Do not recreate unnamed section on every read in
@ref{4d9,,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{1829,,tokenize.untokenize()}.

@item 
gh-91048@footnote{https://github.com/python/cpython/issues/91048}: Add @ref{1cc,,asyncio.capture_call_graph()} and
@ref{1cd,,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{1f0,,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{78,,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{92,,math}
module (@ref{bf0,,math.sqrt()}, @ref{16b4,,math.log()} and @ref{15ce,,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{182a,,os.copy_file_range()} in @ref{c46,,shutil.copy()},
@ref{c47,,shutil.copy2()}, and @ref{c45,,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{10b8,,string.Formatter} in auto-numbering mode, which allows format
strings like '@{.name@}' and '@{[1]@}'.
@end itemize

@node IDLE<5>,Documentation<7>,Library<12>,Python 3 14 0 alpha 5
@anchor{whatsnew/changelog id82}@anchor{182b}
@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<7>,Core and Builtins<11>,IDLE<5>,Python 3 14 0 alpha 5
@anchor{whatsnew/changelog id83}@anchor{182c}
@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{182d,,string.printable} is not printable in the
POSIX sense. In particular, @ref{fd3,,string.printable.isprintable()} returns @ref{d23,,False}. Patch by Bénédikt Tran.
@end itemize

@node Core and Builtins<11>,C API<10>,Documentation<7>,Python 3 14 0 alpha 5
@anchor{whatsnew/changelog id84}@anchor{182e}
@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{17b1,,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{182f,,PyList_Insert()} in free-threading
builds.

@item 
gh-129668@footnote{https://github.com/python/cpython/issues/129668}: Fix race condition when raising @ref{181e,,MemoryError} in the free
threaded build.

@item 
gh-129643@footnote{https://github.com/python/cpython/issues/129643}: Fix thread safety of @ref{1830,,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{291,,sys.platform} doesn't contain the major
version anymore. It is always @code{'freebsd'}, instead of @code{'freebsd13'} or
@code{'freebsd14'}.

@item 
gh-129345@footnote{https://github.com/python/cpython/issues/129345}: Fix null pointer dereference in @ref{759,,syslog.openlog()} when an
audit hook raises an exception.

@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{1831,,PyLong_FromUnsignedLong()}, @ref{1832,,PyLong_FromUnsignedLongLong()}
and @ref{1833,,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{df,,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{1834,,UnicodeError.start} and
@ref{1835,,UnicodeError.end} values in the @ref{1836,,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{1834,,UnicodeError.start} and
@ref{1835,,UnicodeError.end} values in the
@ref{1837,,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{1834,,UnicodeError.start} and
@ref{1835,,UnicodeError.end} values in the
@ref{1838,,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{19b,,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.

@item 
gh-126349@footnote{https://github.com/python/cpython/issues/126349}: Add @ref{2a3,,turtle.fill()}, @ref{2a4,,turtle.poly()} and
@ref{2a5,,turtle.no_animation()} context managers. Patch by Marie Roald and
Yngve Mardal Moe.

@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{f39,,PermissionError}.
Patch by Alex Willmer.

@item 
gh-112713@footnote{https://github.com/python/cpython/issues/112713}: Added support for the @code{Partitioned} cookie flag in
@ref{75,,http.cookies}.
@end itemize

@node C API<10>,Build<10>,Core and Builtins<11>,Python 3 14 0 alpha 5
@anchor{whatsnew/changelog id85}@anchor{1839}
@subsubsection C API



@itemize -

@item 
gh-129533@footnote{https://github.com/python/cpython/issues/129533}: Update @ref{a9b,,PyGC_Enable()}, @ref{a9c,,PyGC_Disable()},
@ref{a9d,,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{137e,,PyUnicode_KIND()} and @ref{137a,,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{1817,,PySequence_Fast()} from the limited C API, since
this function has to be used with @ref{3c9,,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{3c2,,PyUnstable_IsImmortal()} for determining whether an
object is @ref{290,,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{37a,,PyConfig_Get()} and @ref{37b,,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{3cf,,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{183a,,PyUnstable_TryIncRef()} and
@ref{183b,,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{394,,PyImport_ImportModuleAttr()} and
@ref{395,,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{381,,PyBytes_Join()}.

@item 
@code{_PyDict_GetItemStringWithError()}: use @ref{41f,,PyDict_GetItemStringRef()}.

@item 
@code{_PyDict_Pop()}: use @ref{420,,PyDict_Pop()}.

@item 
@code{_PyLong_Sign()}: use @ref{398,,PyLong_GetSign()}.

@item 
@code{_PyLong_FromDigits()} and @code{_PyLong_New()}:
use @ref{3a8,,PyLongWriter_Create()}.

@item 
@code{_PyThreadState_UncheckedGet()}: use @ref{421,,PyThreadState_GetUnchecked()}.

@item 
@code{_PyUnicode_AsString()}: use @ref{422,,PyUnicode_AsUTF8()}.

@item 
@code{_Py_HashPointer()}: use @ref{423,,Py_HashPointer()}.

@item 
@code{_Py_fopen_obj()}: use @ref{391,,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{3a,,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{1fe,,Decimal} instance is small.  Patch by Sergey B
Kirpichev.
@end itemize

@node Build<10>,,C API<10>,Python 3 14 0 alpha 5
@anchor{whatsnew/changelog id86}@anchor{183c}
@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{183d}
@subsection Python 3.14.0 alpha 4


`Release date: 2025-01-14'

@menu
* macOS: macOS<6>. 
* Tools/Demos: Tools/Demos<11>. 
* Tests: Tests<9>. 
* Library: Library<13>. 
* Core and Builtins: Core and Builtins<12>. 
* C API: C API<11>. 
* Build: Build<11>. 

@end menu

@node macOS<6>,Tools/Demos<11>,,Python 3 14 0 alpha 4
@anchor{whatsnew/changelog id87}@anchor{183e}
@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<11>,Tests<9>,macOS<6>,Python 3 14 0 alpha 4
@anchor{whatsnew/changelog id88}@anchor{183f}
@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<9>,Library<13>,Tools/Demos<11>,Python 3 14 0 alpha 4
@anchor{whatsnew/changelog id89}@anchor{1840}
@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<13>,Core and Builtins<12>,Tests<9>,Python 3 14 0 alpha 4
@anchor{whatsnew/changelog id90}@anchor{1841}
@subsubsection Library



@itemize -

@item 
gh-128731@footnote{https://github.com/python/cpython/issues/128731}: Fix @ref{547,,ResourceWarning} in
@ref{1842,,urllib.robotparser.RobotFileParser.read()}.

@item 
gh-71339@footnote{https://github.com/python/cpython/issues/71339}: Add new assertion methods for @ref{10c,,unittest}:
@ref{2b4,,assertHasAttr()},
@ref{2b5,,assertNotHasAttr()},
@ref{2b6,,assertIsSubclass()},
@ref{2b7,,assertNotIsSubclass()}
@ref{2b8,,assertStartsWith()},
@ref{2b9,,assertNotStartsWith()},
@ref{2ba,,assertEndsWith()} and
@ref{2bb,,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{be,,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{1798,,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{f6,,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{1ca,,asyncio.loop.create_task()} and @ref{1cb,,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{cf3,,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{2e,,ctypes} pointers concurrently on the
@ref{1f4,,free threaded} build.

@item 
gh-128400@footnote{https://github.com/python/cpython/issues/128400}: Only show the current thread in @ref{5c,,faulthandler} on the
@ref{1f4,,free threaded} build to prevent races.

@item 
gh-128400@footnote{https://github.com/python/cpython/issues/128400}: Fix crash when using @ref{ffa,,faulthandler.dump_traceback()} while
other threads are active on the @ref{1f4,,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{2a8,,typing.Union} and
@ref{2a7,,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{c4d,,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{750,,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{1843,,ctypes._CFuncPtr} objects
concurrently on the @ref{1f4,,free threaded} build.

@item 
gh-128062@footnote{https://github.com/python/cpython/issues/128062}: Revert the font of @ref{108,,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{f6,,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{ba,,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{2e,,ctypes} and @ref{37,,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{655,,zipfile.ZipFile.open()}.

@item 
gh-127688@footnote{https://github.com/python/cpython/issues/127688}: Add the @ref{25d,,SCHED_DEADLINE} and @ref{25e,,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{217,,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{1166,,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{13ce,,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{1258,,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{147a,,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{6e6,,tempfile.NamedTemporaryFile} will now issue a
@ref{547,,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{1844,,XML_ERROR_NOT_STARTED} of Expat >=2.6.4
in @ref{12d,,xml.parsers.expat.errors}.

@item 
gh-126225@footnote{https://github.com/python/cpython/issues/126225}: @ref{65,,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{1845,,SO_REUSEPORT_LB} constant to @ref{d1,,socket}
for FreeBSD.

@item 
gh-121720@footnote{https://github.com/python/cpython/issues/121720}: @ref{4f1,,enum.EnumDict} can now be used without resorting to
private API.

@item 
gh-123424@footnote{https://github.com/python/cpython/issues/123424}: Add @ref{2ca,,zipfile.ZipInfo._for_archive()} setting default
properties on @ref{2cb,,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{21a,,functools.reduce()} with a @code{function} or @code{sequence} as a
@ref{f09,,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{1eb,,ctypes.memoryview_at()} now exists to create a
@ref{165,,memoryview} object that refers to the supplied pointer and length.
This works like @ref{1ec,,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<12>,C API<11>,Library<13>,Python 3 14 0 alpha 4
@anchor{whatsnew/changelog id91}@anchor{1846}
@subsubsection Core and Builtins



@itemize -

@item 
gh-128078@footnote{https://github.com/python/cpython/issues/128078}: Fix a @ref{78e,,SystemError} when using @ref{9cf,,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{1f4,,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{1376,,PyASCIIObject} layout to handle interned field
with the atomic operation. Patch by Donghee Na.

@item 
gh-128192@footnote{https://github.com/python/cpython/issues/128192}: Upgrade HTTP digest authentication algorithm for
@ref{111,,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}.

@item 
gh-126868@footnote{https://github.com/python/cpython/issues/126868}: Increase usage of freelist for @ref{19b,,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{1ac,,except*} does not
properly check the return value of an @ref{4cd,,ExceptionGroup}'s
@ref{1847,,split()} function, leading to a crash in some
cases. Now when @ref{1847,,split()} returns an invalid
object, @ref{1ac,,except*} raises a @ref{198,,TypeError} with
the original raised @ref{4cd,,ExceptionGroup} object chained to it.

@item 
gh-128030@footnote{https://github.com/python/cpython/issues/128030}: Avoid error from calling @code{PyModule_GetFilenameObject} on a
non-module object when importing a non-existent symbol from a non-module
object.

@item 
gh-128035@footnote{https://github.com/python/cpython/issues/128035}: Indicate through @ref{286,,ssl.HAS_PHA} whether the @ref{d5,,ssl}
module supports TLSv1.3 post-handshake client authentication (PHA). Patch
by Will Childs-Klein.

@item 
gh-127274@footnote{https://github.com/python/cpython/issues/127274}: Add a new flag, @code{CO_METHOD}, to @ref{1848,,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{1849,,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{3e4,,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{184a,,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<11>,Build<11>,Core and Builtins<12>,Python 3 14 0 alpha 4
@anchor{whatsnew/changelog id92}@anchor{184b}
@subsubsection C API



@itemize -

@item 
gh-128400@footnote{https://github.com/python/cpython/issues/128400}: @ref{b71,,Py_FatalError()} no longer shows all threads on the
@ref{1f4,,free threaded} build to prevent crashes.

@item 
gh-128629@footnote{https://github.com/python/cpython/issues/128629}: Add macros @ref{37d,,Py_PACK_VERSION()} and
@ref{37e,,Py_PACK_FULL_VERSION()} for bit-packing Python version numbers.

@item 
gh-128008@footnote{https://github.com/python/cpython/issues/128008}: Add @ref{184c,,PyWeakref_IsDead()} function, which tests if a weak
reference is dead.

@item 
gh-127350@footnote{https://github.com/python/cpython/issues/127350}: Add @ref{391,,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{392,,Py_fclose()} function to
close a file, function needed for Windows support. Patch by Victor
Stinner.
@end itemize

@node Build<11>,,C API<11>,Python 3 14 0 alpha 4
@anchor{whatsnew/changelog id93}@anchor{184d}
@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{2f,,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{d4,,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{184e}
@subsection Python 3.14.0 alpha 3


`Release date: 2024-12-17'

@menu
* Windows: Windows<10>. 
* Tools/Demos: Tools/Demos<12>. 
* Tests: Tests<10>. 
* Security: Security<12>. 
* Library: Library<14>. 
* Documentation: Documentation<8>. 
* Core and Builtins: Core and Builtins<13>. 
* C API: C API<12>. 
* Build: Build<12>. 

@end menu

@node Windows<10>,Tools/Demos<12>,,Python 3 14 0 alpha 3
@anchor{whatsnew/changelog id94}@anchor{184f}
@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{107,,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<12>,Tests<10>,Windows<10>,Python 3 14 0 alpha 3
@anchor{whatsnew/changelog id95}@anchor{1850}
@subsubsection Tools/Demos



@itemize -

@item 
gh-126700@footnote{https://github.com/python/cpython/issues/126700}: Add support for multi-argument @ref{67,,gettext} functions in
@code{pygettext.py}.
@end itemize

@node Tests<10>,Security<12>,Tools/Demos<12>,Python 3 14 0 alpha 3
@anchor{whatsnew/changelog id96}@anchor{1851}
@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{3c,,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{83,,io} behavior
using strace.
@end itemize

@node Security<12>,Library<14>,Tests<10>,Python 3 14 0 alpha 3
@anchor{whatsnew/changelog id97}@anchor{1852}
@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{175f,,asyncio.WriteTransport.writelines()}.
@end itemize

@node Library<14>,Documentation<8>,Security<12>,Python 3 14 0 alpha 3
@anchor{whatsnew/changelog id98}@anchor{1853}
@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{1f4,,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{298,,sysconfig.get_config_vars()},
@ref{33f,,sysconfig.get_paths()}, and siblings, returning outdated cached data
if the value  of @ref{3e6,,sys.prefix} or @ref{3e9,,sys.exec_prefix} changes.
Overwriting @ref{3e6,,sys.prefix} or @ref{3e9,,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{e9,,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{4de,,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{c6,,select} module.

@item 
gh-127065@footnote{https://github.com/python/cpython/issues/127065}: Make @ref{102f,,operator.methodcaller()} thread-safe and re-entrant
safe.

@item 
gh-127321@footnote{https://github.com/python/cpython/issues/127321}: @ref{272,,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{e1,,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{209,,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{26e,,pathlib.Path.iterdir()}.

@item 
gh-127257@footnote{https://github.com/python/cpython/issues/127257}: In @ref{d5,,ssl}, system call failures that OpenSSL reports using
@code{ERR_LIB_SYS} are now raised as @ref{2c0,,OSError}.

@item 
gh-59705@footnote{https://github.com/python/cpython/issues/59705}: On Linux, @ref{176,,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{1854,,EXACT_TOKEN_TYPES} in
@code{token.__all__}.

@item 
gh-127331@footnote{https://github.com/python/cpython/issues/127331}: @ref{d5,,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{298,,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{1ea,,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{87e,,None}
was passed as the first value.

@item 
gh-127217@footnote{https://github.com/python/cpython/issues/127217}: Fix @ref{2bf,,urllib.request.pathname2url()} for paths starting with
multiple slashes on Posix.

@item 
gh-125866@footnote{https://github.com/python/cpython/issues/125866}: @ref{2bf,,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{10c,,unittest} output. Patch by Hugo van
Kemenade.

@item 
gh-127035@footnote{https://github.com/python/cpython/issues/127035}: Fix @ref{6d4,,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{2bf,,urllib.request.pathname2url()} and
@ref{2bd,,url2pathname()} no longer convert Windows drive
letters to uppercase.

@item 
gh-127078@footnote{https://github.com/python/cpython/issues/127078}: Fix issue where @ref{2bd,,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{2bd,,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{102f,,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{1855,,urllib.response.addinfourl.url} for
@code{file:} URLs that express relative paths and absolute Windows paths. The
canonical URL generated by @ref{2bf,,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{eb9,,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{6a,,grp}: Make @ref{1856,,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{1484,,itertools.count} objects when
the count value is @ref{13c6,,sys.maxsize}.

@item 
gh-126615@footnote{https://github.com/python/cpython/issues/126615}: The @ref{1e9,,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{cc,,site}
disabled (see @ref{13a9,,-S}), @ref{3e6,,sys.prefix} and
@ref{3e4,,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{103,,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{198,,TypeError} in
@code{_pydatetime.timedelta.__new__()} if the passed arguments are not
@ref{19b,,int} or @ref{196,,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{1857,,GetoptError} error message when a
long option prefix matches multiple accepted options in
@ref{16af,,getopt.getopt()} and @ref{16ae,,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{2bd,,urllib.request.url2pathname()} and
@ref{2bf,,pathname2url()} always used UTF-8 when quoting and
unquoting file URIs. They now use the @ref{756,,filesystem encoding and error handler}.

@item 
gh-126780@footnote{https://github.com/python/cpython/issues/126780}: Fix @ref{151a,,os.path.normpath()} for drive-relative paths on
Windows.

@item 
gh-126775@footnote{https://github.com/python/cpython/issues/126775}: Make @ref{1858,,linecache.checkcache()} thread safe and GC
re-entrancy safe.

@item 
gh-126601@footnote{https://github.com/python/cpython/issues/126601}: Fix issue where @ref{2bf,,urllib.request.pathname2url()} raised
@ref{2c0,,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{20b,,EHWPOISON} error code to @ref{5b,,errno}.

@item 
gh-118201@footnote{https://github.com/python/cpython/issues/118201}: Fixed intermittent failures of @ref{1859,,os.confstr},
@ref{12fc,,os.pathconf} and @ref{185a,,os.sysconf} on iOS and Android.

@item 
gh-86463@footnote{https://github.com/python/cpython/issues/86463}: The @code{usage} parameter of @ref{1bd,,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{75,,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{104c,,readline.append_history_file()} now raises a
@ref{2eb,,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{152b,,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{17cd,,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{252,,multiprocessing.Process} reporting a @code{.exitcode}
of 1 even on success when using the @code{"fork"} start method while using a
@ref{941,,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<8>,Core and Builtins<13>,Library<14>,Python 3 14 0 alpha 3
@anchor{whatsnew/changelog id99}@anchor{185b}
@subsubsection Documentation



@itemize -

@item 
gh-127347@footnote{https://github.com/python/cpython/issues/127347}: Publicly expose @ref{185c,,traceback.print_list()} in
@code{traceback.__all__}.
@end itemize

@node Core and Builtins<13>,C API<12>,Documentation<8>,Python 3 14 0 alpha 3
@anchor{whatsnew/changelog id100}@anchor{185d}
@subsubsection Core and Builtins



@itemize -

@item 
gh-127740@footnote{https://github.com/python/cpython/issues/127740}: Fix error message in @ref{190,,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{653,,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{165,,memoryview}
object on the @ref{1f4,,free-threaded} build.

@item 
gh-127238@footnote{https://github.com/python/cpython/issues/127238}: Correct error message for @ref{185e,,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{197,,complex}'s @ref{185f,,_Py_c_pow()}.

@item 
gh-127133@footnote{https://github.com/python/cpython/issues/127133}: Calling @ref{2ea,,argparse.ArgumentParser.add_argument_group()} on
an argument group, and calling
@ref{2ea,,argparse.ArgumentParser.add_argument_group()} or
@ref{2ec,,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.

@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{974,,PyCode_GetCode()}, @ref{975,,PyCode_GetVarnames()},
@ref{976,,PyCode_GetCellvars()}, or @ref{977,,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{685,,__buffer__()} of @ref{343,,bytearray} crashing
when @ref{1860,,READ} or
@ref{1861,,WRITE} are passed as flags.

@item 
gh-126937@footnote{https://github.com/python/cpython/issues/126937}: Fix @ref{198,,TypeError} when a @ref{1e5,,ctypes.Structure} has a
field size that doesn't fit into an unsigned 16-bit integer. Instead, the
maximum number of `bits' is @ref{13c6,,sys.maxsize}.

@item 
gh-126868@footnote{https://github.com/python/cpython/issues/126868}: Increase performance of @ref{19b,,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{1862,,memoryview.index()} to @ref{165,,memoryview} objects.
Patch by Bénédikt Tran.

@item 
gh-125420@footnote{https://github.com/python/cpython/issues/125420}: Add @ref{1863,,memoryview.count()} to @ref{165,,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<12>,Build<12>,Core and Builtins<13>,Python 3 14 0 alpha 3
@anchor{whatsnew/changelog id101}@anchor{1864}
@subsubsection C API



@itemize -

@item 
gh-127896@footnote{https://github.com/python/cpython/issues/127896}: The previously undocumented function @ref{3d6,,PySequence_In()} is
@ref{23d,,soft deprecated}. Use @ref{3d7,,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{1865,,PyUnstable_AtExit()}.

@item 
gh-127691@footnote{https://github.com/python/cpython/issues/127691}: The @ref{45f,,Unicode Exception Objects} C API
now raises a @ref{198,,TypeError} if its exception argument is not a
@ref{460,,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{1835,,UnicodeEncodeError.end} retrieved by @ref{1866,,PyUnicodeEncodeError_GetEnd()}
lies in @code{[min(1, objlen), max(min(1, objlen), objlen)]} where `objlen'
is the length of @ref{1867,,UnicodeEncodeError.object}.
Similar arguments apply to @ref{bff,,UnicodeDecodeError} and
@ref{1868,,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{1f4,,free-threaded} build.

@item 
gh-123378@footnote{https://github.com/python/cpython/issues/123378}: Ensure that the value of @ref{1834,,UnicodeEncodeError.start} retrieved by @ref{1869,,PyUnicodeEncodeError_GetStart()}
lies in @code{[0, max(0, objlen - 1)]} where `objlen' is the length of
@ref{1867,,UnicodeEncodeError.object}. Similar arguments
apply to @ref{bff,,UnicodeDecodeError} and @ref{1868,,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{235,,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{19b,,int} objects
(
@geindex Python Enhancement Proposals; PEP 757
PEP 757@footnote{https://peps.python.org/pep-0757/}):


@itemize *

@item 
@ref{3a5,,PyLong_GetNativeLayout()};

@item 
@ref{3a6,,PyLong_Export()};

@item 
@ref{3a7,,PyLong_FreeExport()};

@item 
@ref{3a8,,PyLongWriter_Create()};

@item 
@ref{3a9,,PyLongWriter_Finish()};

@item 
@ref{3aa,,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<12>,,C API<12>,Python 3 14 0 alpha 3
@anchor{whatsnew/changelog id102}@anchor{186a}
@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{186b}
@subsection Python 3.14.0 alpha 2


`Release date: 2024-11-19'

@menu
* Windows: Windows<11>. 
* Tools/Demos: Tools/Demos<13>. 
* Tests: Tests<11>. 
* Security: Security<13>. 
* Library: Library<15>. 
* Documentation: Documentation<9>. 
* Core and Builtins: Core and Builtins<14>. 
* C API: C API<13>. 
* Build: Build<13>. 

@end menu

@node Windows<11>,Tools/Demos<13>,,Python 3 14 0 alpha 2
@anchor{whatsnew/changelog id103}@anchor{186c}
@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{78e,,SystemError} when @ref{277,,sys.exit()} is called with
@code{0xffffffff} on Windows.

@item 
gh-125550@footnote{https://github.com/python/cpython/issues/125550}: Enable the @ref{7d3,,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<13>,Tests<11>,Windows<11>,Python 3 14 0 alpha 2
@anchor{whatsnew/changelog id104}@anchor{186d}
@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<11>,Security<13>,Tools/Demos<13>,Python 3 14 0 alpha 2
@anchor{whatsnew/changelog id105}@anchor{186e}
@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<13>,Library<15>,Tests<11>,Python 3 14 0 alpha 2
@anchor{whatsnew/changelog id106}@anchor{186f}
@subsubsection Security



@itemize -

@item 
gh-126623@footnote{https://github.com/python/cpython/issues/126623}: Upgrade libexpat to 2.6.4
@end itemize

@node Library<15>,Documentation<9>,Security<13>,Python 3 14 0 alpha 2
@anchor{whatsnew/changelog id107}@anchor{1870}
@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{298,,sysconfig.get_config_vars()} incorrectly having the same value as
@ref{3e4,,sys.base_prefix} and @ref{3e8,,sys.base_exec_prefix},
respectively, inside virtual environments. They now accurately reflect
@ref{3e6,,sys.prefix} and @ref{3e9,,sys.exec_prefix}.

@item 
gh-67877@footnote{https://github.com/python/cpython/issues/67877}: Fix memory leaks when @ref{be,,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{91,,marshal} now supports @ref{68d,,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{298,,sysconfig.get_config_vars()},
@ref{33f,,sysconfig.get_paths()}, and their siblings when the @ref{cc,,site}
initialization happens after @ref{e1,,sysconfig} has built a cache for
@ref{298,,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{2bd,,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{e46,,os.PathLike} to be a base for Protocols.

@item 
gh-126699@footnote{https://github.com/python/cpython/issues/126699}: Allow @ref{fd9,,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{108d,,unittest.mock.patch()} or
@ref{1871,,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{1484,,itertools.count} with an
initial count of @ref{13c6,,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{2bf,,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{1872,,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{be,,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{3e2,,sys.path}
during the importing of @ref{1873,,multiprocessing.set_forkserver_preload()}
modules in the same manner as @ref{3e2,,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{3e2,,sys.path}
during forkserver preload imports instead of the absolute path from
@ref{1874,,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{17d2,,multiprocessing.Lock} and
@ref{17d3,,multiprocessing.RLock} @code{repr} values no longer say "unknown" on
macOS.

@item 
gh-126476@footnote{https://github.com/python/cpython/issues/126476}: Raise @ref{1875,,calendar.IllegalMonthError} (now a subclass of
@ref{1729,,IndexError}) for @ref{1876,,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{1877,,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{177,,contextvars.Context} type to
@ref{abe,,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{1878,,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{12ad,,collections.abc.MutableMapping}
and @ref{4ba,,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{16ae,,getopt.gnu_getopt()}.

@item 
gh-126374@footnote{https://github.com/python/cpython/issues/126374}: Add support for options with optional arguments in the
@ref{65,,getopt} module.

@item 
gh-126363@footnote{https://github.com/python/cpython/issues/126363}: Speed up pattern parsing in @ref{532,,pathlib.Path.glob()} by
skipping creation of a @ref{266,,pathlib.Path} object for the pattern.

@item 
gh-126353@footnote{https://github.com/python/cpython/issues/126353}: @ref{2f1,,asyncio.get_event_loop()} now does not implicitly creates
an event loop. It now raises a @ref{244,,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{1879,,curses.napms()} when
@ref{187a,,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{187b,,os.sched_param} objects.

@item 
gh-126138@footnote{https://github.com/python/cpython/issues/126138}: Fix a use-after-free crash on @ref{1c7,,asyncio.Task} objects
whose underlying coroutine yields an object that implements an evil
@ref{dc6,,__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{258,,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{2bf,,urllib.request.pathname2url()} and
@ref{2bd,,url2pathname()} removed slashes from Windows DOS
drive paths and URLs.

@item 
gh-126223@footnote{https://github.com/python/cpython/issues/126223}: Raise a @ref{880,,UnicodeEncodeError} instead of a
@ref{78e,,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{2bf,,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{df9,,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{1764,,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{d5,,ssl}.

@item 
gh-126080@footnote{https://github.com/python/cpython/issues/126080}: Fix a use-after-free crash on @ref{1c7,,asyncio.Task} objects for
which the underlying event loop implements an evil
@ref{dc6,,__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{1c7,,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{c4b,,os.scandir()}.

@item 
gh-125984@footnote{https://github.com/python/cpython/issues/125984}: Fix use-after-free crashes on @ref{dc1,,asyncio.Future} objects
for which the underlying event loop implements an evil
@ref{dc6,,__getattribute__()}. Reported by Nico-Posada. Patch by
Bénédikt Tran.

@item 
gh-125926@footnote{https://github.com/python/cpython/issues/125926}: Fix @ref{1091,,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{cf2,,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{187c,,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{21a,,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{187d,,email.policy.EmailPolicy.header_source_parse()} and
@ref{187e,,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{cef,,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{1a6,,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{111,,urllib.request}. They had previously raised
@ref{1a3,,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{1877,,persistent_id}
and @ref{187f,,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{b45,,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{b45,,json.loads()}.

@item 
gh-52551@footnote{https://github.com/python/cpython/issues/52551}: Use @code{wcsftime()} to implement @ref{13ea,,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{232,,inspect.ispackage()} to determine whether an
object is a @ref{233,,package} or not.

@item 
gh-125614@footnote{https://github.com/python/cpython/issues/125614}: In the @ref{15f,,FORWARDREF} format of
@ref{6,,annotationlib}, fix bug where nested expressions were not returned
as @ref{17d8,,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{2ea,,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{8a0,,threading.Lock.acquire()}, @ref{1076,,threading.RLock.acquire()}, and
@ref{13e5,,threading.Thread.join()} now interrupts the function call and raises
a @ref{bbc,,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{736,,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{1d6,,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{117,,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{13ea,,time.strftime()}, the
@ref{e89,,strftime()} method of the @ref{34,,datetime} classes
@ref{4dd,,datetime}, @ref{1fa,,date} and
@ref{1fb,,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{d5,,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{117,,venv} activation
scripts.

@item 
gh-124694@footnote{https://github.com/python/cpython/issues/124694}: We've added
@ref{1d2,,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{30b,,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{2c4,,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{27d,,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{137,,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{e4,,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{12d6,,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{1255,,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{151b,,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{110,,urllib.parse} functions @ref{31d,,parse_qsl()} and
@ref{31e,,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{1166,,multiprocessing.pool.Pool}.

@item 
bpo-46128@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46128}: Strip @ref{35f,,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<9>,Core and Builtins<14>,Library<15>,Python 3 14 0 alpha 2
@anchor{whatsnew/changelog id108}@anchor{1880}
@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{c75,,object} type in the lists of documented
types. Change by Furkan Onder and Martin Panter.
@end itemize

@node Core and Builtins<14>,C API<13>,Documentation<9>,Python 3 14 0 alpha 2
@anchor{whatsnew/changelog id109}@anchor{1881}
@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{2eb,,ValueError} is raised instead of @ref{78e,,SystemError}
when trying to iterate over a released @ref{165,,memoryview} object.

@item 
gh-126688@footnote{https://github.com/python/cpython/issues/126688}: Fix a crash when calling @ref{4b0,,os.fork()} on some operating
systems, including SerenityOS.

@item 
gh-126066@footnote{https://github.com/python/cpython/issues/126066}: Fix @ref{7b,,importlib} to not write an incomplete .pyc files when
a ulimit or some other operating system mechanism is preventing the write
to go through fully.

@item 
gh-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__}.

@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{170d,,warnings.warn()}. Patch by Daehee Kim.

@item 
gh-126312@footnote{https://github.com/python/cpython/issues/126312}: Fix crash during garbage collection on an object frozen by
@ref{d26,,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{7cb,,程式碼物件} like lambda,
annotation and type alias, we no longer  add @code{None} to its
@ref{1814,,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{fa8,,future statement} with an unknown future feature.

@item 
gh-126072@footnote{https://github.com/python/cpython/issues/126072}: Add a new attribute in @ref{1848,,co_flags} to indicate
whether the first item in @ref{1814,,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{105,,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{1882,,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{165,,memoryview} type now supports subscription, making
it a @ref{1a1,,generic type}.

@item 
gh-125837@footnote{https://github.com/python/cpython/issues/125837}: Adds @ref{36c,,LOAD_SMALL_INT} and @ref{373,,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{cc4,,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{9fd,,gc.get_objects()} or @ref{9fe,,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{105,,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{451,,staticmethod} and @ref{489,,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{653,,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{19f,,map()} built-in now has an optional keyword-only
`strict' flag like @ref{1a0,,zip()} to check that all the iterables are of
equal length. Patch by Wannes Boeykens.

@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<13>,Build<13>,Core and Builtins<14>,Python 3 14 0 alpha 2
@anchor{whatsnew/changelog id110}@anchor{1883}
@subsubsection C API



@itemize -

@item 
gh-126554@footnote{https://github.com/python/cpython/issues/126554}: Fix error handling in @ref{bd3,,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{399,,PyLong_IsPositive()}, @ref{39a,,PyLong_IsNegative()}
and @ref{39b,,PyLong_IsZero()} for checking if a @ref{39c,,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{77d,,PyDict_Watch()}) on an object's attribute dictionary
(@ref{776,,__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{3c3,,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{3ad,,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{23d,,soft deprecated}.
@end itemize

@node Build<13>,,C API<13>,Python 3 14 0 alpha 2
@anchor{whatsnew/changelog id111}@anchor{1884}
@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{1885}
@subsection Python 3.14.0 alpha 1


`Release date: 2024-10-15'

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

@end menu

@node macOS<7>,Windows<12>,,Python 3 14 0 alpha 1
@anchor{whatsnew/changelog id112}@anchor{1886}
@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<12>,Tools/Demos<14>,macOS<7>,Python 3 14 0 alpha 1
@anchor{whatsnew/changelog id113}@anchor{1887}
@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<14>,Tests<12>,Windows<12>,Python 3 14 0 alpha 1
@anchor{whatsnew/changelog id114}@anchor{1888}
@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<12>,Security<14>,Tools/Demos<14>,Python 3 14 0 alpha 1
@anchor{whatsnew/changelog id115}@anchor{1889}
@subsubsection Tests



@itemize -

@item 
gh-125041@footnote{https://github.com/python/cpython/issues/125041}: Re-enable skipped tests for @ref{139,,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{188a,,pkgutil.extend_path()}. Patch by Andreas
Stocker.

@item 
gh-99242@footnote{https://github.com/python/cpython/issues/99242}: @ref{188b,,os.getloadavg()} may throw @ref{2c0,,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{188c,,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<14>,Library<16>,Tests<12>,Python 3 14 0 alpha 1
@anchor{whatsnew/changelog id116}@anchor{188d}
@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{526,,os.mkdir()} on Windows to work
correctly on non-English machines.

@item 
gh-118486@footnote{https://github.com/python/cpython/issues/118486}: @ref{526,,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{528,,tempfile.mkdtemp()} in scenarios where the
base temporary directory is more permissive than the default.
@end itemize

@node Library<16>,IDLE<6>,Security<14>,Python 3 14 0 alpha 1
@anchor{whatsnew/changelog id117}@anchor{188e}
@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{1624,,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{188f,,WeakKeyDictionary} and
@ref{1890,,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{847,,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{ad3,,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{f6,,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{1bd,,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{db,,struct} module.

@item 
gh-125069@footnote{https://github.com/python/cpython/issues/125069}: Fix an issue where providing a @ref{6c6,,pathlib.PurePath} object
as an initializer argument to a second @ref{6c6,,PurePath} object
with a different @ref{531,,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{1b6,,PYTHON_BASIC_REPL} environment variable is set,
the @ref{cc,,site} module no longer imports the @code{_pyrepl} module.
Moreover, the @ref{cc,,site} module now respects @ref{b4d,,-E} and
@ref{b4e,,-I} command line options: ignore 
@geindex PYTHON_BASIC_REPL
@geindex 環境變數; PYTHON_BASIC_REPL
@ref{1b6,,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{452,,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{4cc,,asyncio.TaskGroup} and the python implementation of
@ref{dc1,,asyncio.Future}

@item 
gh-53203@footnote{https://github.com/python/cpython/issues/53203}: Fix @ref{1624,,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{2f,,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{d1,,socket} module.

@item 
gh-117151@footnote{https://github.com/python/cpython/issues/117151}: The default buffer size used by @ref{c49,,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{bfa,,os.path.exists()} and
@ref{bfb,,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{4b7,,add_argument()},
@ref{e0c,,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{8b,,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{59,,ensurepip},
@ref{86,,json}, @ref{aa,,pdb}, @ref{d4,,sqlite3}, @ref{101,,tokenize}, @ref{117,,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{d06,,asyncio.open_connection()} when used with @code{happy_eyeballs_delay}

@item 
gh-124390@footnote{https://github.com/python/cpython/issues/124390}: Fixed @ref{8b0,,AssertionError} when using
@code{asyncio.staggered.staggered_race()} with
@ref{69b,,asyncio.eager_task_factory}.

@item 
gh-85935@footnote{https://github.com/python/cpython/issues/85935}: @ref{4b7,,argparse.ArgumentParser.add_argument()} now raises an
exception if an @ref{1891,,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{1892,,tomllib.loads()} raise @ref{198,,TypeError} not
@ref{5e8,,AttributeError} on bad input types that do not have the @code{replace}
attribute. Improve error message when @ref{192,,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{2ae,,typing.TypeAliasType} with incorrect
@code{type_params} argument. Now it raises a @ref{198,,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{1bc,,prog} default value for
@ref{1bd,,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{22f,,inspect.signature()}. Add an `quote_annotation_strings' parameter to
@ref{231,,inspect.Signature.format()}. Use the new functionality to improve the
display of annotations in signatures in @ref{ba,,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{177,,context}. Contributed by Bartosz Sławecki.

@item 
gh-61181@footnote{https://github.com/python/cpython/issues/61181}: Fix support of @ref{1893,,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{1894,,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{9ff,,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{1895,,curses.resizeterm()} and @ref{1896,,curses.resize_term()}.

@item 
gh-124498@footnote{https://github.com/python/cpython/issues/124498}: Fix @ref{2ae,,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{1893,,choices} in @ref{7,,argparse}.
Positional arguments with @ref{1897,,nargs} equal to @code{'?'} or @code{'*'} no
longer check @ref{1898,,default} against @code{choices}. Optional arguments with
@code{nargs} equal to @code{'?'} no longer check @ref{1899,,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{13ea,,time.strftime()} no longer accepts negative years on Android.

@item 
gh-123014@footnote{https://github.com/python/cpython/issues/123014}: @ref{69d,,os.pidfd_open()} and @ref{b1c,,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{4dc,,dataclasses.dataclass()} in
@ref{189a,,unittest.mock.create_autospec()}. Now @code{create_autospec} will check
for potential dataclasses and use @ref{189b,,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{1897,,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{1897,,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{189c,,_fields_} attribute of
@ref{1e5,,ctypes.Structure} and @ref{1e6,,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{84,,ipaddress} module.

@item 
gh-111513@footnote{https://github.com/python/cpython/issues/111513}: Improve the error message that may be raised by
@ref{dc8,,datetime.date.fromtimestamp()}.

@item 
gh-124248@footnote{https://github.com/python/cpython/issues/124248}: Fixed potential crash when using @ref{db,,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{117,,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{b27,,time.thread_time()} and
@ref{d85,,time.thread_time_ns()} on NetBSD.

@item 
gh-123934@footnote{https://github.com/python/cpython/issues/123934}: Fix @ref{108a,,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{10b,,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{bd,,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{a3b,,sys.stdlib_module_names}. Patch by
Victor Stinner.

@item 
gh-84808@footnote{https://github.com/python/cpython/issues/84808}: Fix error handling in @ref{f9c,,socket} method
@ref{172d,,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{273,,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{117,,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{189d,,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{1759,,inspect.getsource()} for classes in
@ref{1f,,collections.abc} and @ref{3a,,decimal} (for pure Python implementation)
modules. @ref{189e,,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{eb9,,pickletools.dis()}.

@item 
gh-123504@footnote{https://github.com/python/cpython/issues/123504}: Fixed reference leak in the finalization of @ref{f6,,tkinter}.

@item 
gh-123430@footnote{https://github.com/python/cpython/issues/123430}: Pages generated by the @ref{76,,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{198,,TypeError} when
@ref{6a7,,csv.reader()}, @ref{6a8,,csv.writer()}, or @ref{189f,,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{563,,typing.NoDefault} by moving it to
the static types array.

@item 
gh-123409@footnote{https://github.com/python/cpython/issues/123409}: Fix @ref{18a0,,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{7ee,,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{18a1,,CONTAINS_OP} oparg in @ref{3c,,dis}
output. Patch by Alexandr153.

@item 
gh-123341@footnote{https://github.com/python/cpython/issues/123341}: Add @ref{93b,,__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{18a2,,IS_OP} oparg in @ref{3c,,dis}
output.

@item 
gh-119518@footnote{https://github.com/python/cpython/issues/119518}: Speed up normalization of @ref{6c6,,pathlib.PurePath} and
@ref{266,,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{8cd,,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{268,,pathlib.Path.copy_into()} and
@ref{26a,,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{169,,str()}.  Patch by Sergey B Kirpichev.

@item 
gh-123240@footnote{https://github.com/python/cpython/issues/123240}: Raise audit events for the @ref{14d9,,input()} in the new REPL.

@item 
gh-76960@footnote{https://github.com/python/cpython/issues/76960}: Fix @ref{1091,,urllib.parse.urljoin()} and
@ref{1448,,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{d5,,ssl}
when the @ref{18a3,,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{13d4,,xml.etree.ElementTree.Element.extend()} and
@ref{361,,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{18a4,,urllib.parse.urlunsplit()} and @ref{18a5,,urllib.parse.urlunparse()}.

@item 
gh-123165@footnote{https://github.com/python/cpython/issues/123165}: Add support for rendering @ref{18a6,,Positions} in
@ref{3c,,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{ca,,shutil} function since Python 3.4. It's now an alias for
@ref{244,,RuntimeError}.

@item 
gh-123085@footnote{https://github.com/python/cpython/issues/123085}: In a bare call to @ref{6af,,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{75,,http.cookies}.

@item 
gh-123049@footnote{https://github.com/python/cpython/issues/123049}: Add support for @ref{18a7,,UNNAMED_SECTION} in
@ref{146e,,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{1759,,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{8cd,,zipfile.Path} objects now sanitize names from the
zipfile.

@item 
gh-122873@footnote{https://github.com/python/cpython/issues/122873}: Enable @ref{86,,json} module to work as a script using the
@ref{23c,,-m} switch: @code{python -m json}. See the @ref{23e,,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{30c,,inspect.iscoroutinefunction()}.

@item 
gh-116263@footnote{https://github.com/python/cpython/issues/116263}: @ref{18a8,,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{8b,,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{18a9,,PicklingError} is now raised more often instead of
@ref{880,,UnicodeEncodeError}, @ref{2eb,,ValueError} and @ref{5e8,,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{17dc,,dataclasses.make_dataclass()} to customize the functional creation of
dataclasses.

@item 
gh-118814@footnote{https://github.com/python/cpython/issues/118814}: Fix the @ref{481,,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{18aa,,code.InteractiveInterpreter} with non-default
@ref{a05,,sys.excepthook()}. Save correct tracebacks in
@ref{6e1,,sys.last_traceback} and update @code{__traceback__} attribute of
@ref{6e0,,sys.last_value} and @ref{6de,,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{5d,,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{48c,,REPL} interprets
@ref{18ab,,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{d5,,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{18aa,,code.InteractiveInterpreter}, handle exceptions
caused by calling a non-default @ref{a05,,sys.excepthook()}. Before, the
exception bubbled up to the caller, ending the @ref{48c,,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{e89,,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{2eb,,ValueError}s raised by @ref{26d,,os.stat()} in
@ref{113b,,filecmp.dircmp} and @ref{18ac,,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{3f,,email} headers with embedded newlines are now quoted on
output. The @ref{44,,generator} will now refuse to serialize (write)
headers that are unsafely folded or delimited; see
@ref{4ed,,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{bc6,,asyncio.Task.get_coro()} when using an
eager task factory.

@item 
gh-105733@footnote{https://github.com/python/cpython/issues/105733}: @ref{598,,ctypes.ARRAY()} is now @ref{23d,,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{2ae,,typing.TypeAliasType}

@item 
@code{evaluate_bound}, @code{evaluate_constraints}, and @code{evaluate_default} on @ref{481,,typing.TypeVar}

@item 
@code{evaluate_default} on @ref{482,,typing.ParamSpec}

@item 
@code{evaluate_default} on @ref{483,,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{2eb,,ValueError}s raised by @ref{26d,,os.stat()} in
@ref{89,,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{13b1,,logging.config.dictConfig()} accept any object
implementing the Queue public API. See the @ref{18ad,,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{2d,,csv} now correctly parses numeric fields (when used with
@ref{18ae,,csv.QUOTE_NONNUMERIC} or @ref{6a6,,csv.QUOTE_STRINGS}) which start
with an escape character.

@item 
gh-122088@footnote{https://github.com/python/cpython/issues/122088}: @ref{484,,@@warnings.deprecated} now copies the coroutine status of
functions and methods so that @ref{30c,,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{269,,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
@ref{31c,,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{18e,,SyntaxError} raised
in new repl. Patch by Sergey B Kirpichev.

@item 
gh-121797@footnote{https://github.com/python/cpython/issues/121797}: Add alternative @ref{213,,Fraction} constructor
@ref{214,,Fraction.from_number()}.

@item 
gh-121798@footnote{https://github.com/python/cpython/issues/121798}: Add alternative @ref{1fe,,Decimal} constructor
@ref{1fd,,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{113b,,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{db,,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{92,,math} functions @ref{bef,,isqrt()}, @ref{16b4,,log()},
@ref{12dc,,log2()} and @ref{18af,,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{13e4,,threading.Barrier} constructor. Patch by Clinton Christian
(pygeek).

@item 
gh-121450@footnote{https://github.com/python/cpython/issues/121450}: Hard-coded breakpoints (@ref{271,,breakpoint()} and
@ref{272,,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{6c9,,os.walk()} by simplifying exception
handling.

@item 
gh-121423@footnote{https://github.com/python/cpython/issues/121423}: Improve import time of @ref{d1,,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{138,,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{18b0,,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{12e1,,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{1a3,,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{48c,,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{1bf,,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{8c8,,warnings.simplefilter()} and @ref{169d,,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{1c0,,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{18b1,,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{217,,functools.partial} will be a method
descriptor.

@item 
gh-121027@footnote{https://github.com/python/cpython/issues/121027}: Make the @ref{217,,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{828,,__repr__()} of
@ref{218,,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{f6,,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{2e,,ctypes} as
@ref{1ed,,c_float_complex}, @ref{1ee,,c_double_complex} and
@ref{1ef,,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{f6,,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{18b2,,contextvars.Context.run()}.

@item 
gh-120782@footnote{https://github.com/python/cpython/issues/120782}: Fix wrong references of the @ref{34,,datetime} types after
reloading the module.

@item 
gh-120713@footnote{https://github.com/python/cpython/issues/120713}: @ref{e89,,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{3c,,dis} output.

@item 
gh-41431@footnote{https://github.com/python/cpython/issues/41431}: Add @ref{18b3,,datetime.time.strptime()} and
@ref{1f9,,datetime.date.strptime()}. Contributed by Wannes Boeykens.

@item 
gh-120743@footnote{https://github.com/python/cpython/issues/120743}: @ref{23d,,Soft deprecate} @ref{319,,os.popen()} and
@ref{31a,,os.spawn*} functions. They should no longer be used to
write new code. The @ref{dc,,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{c36,,unittest.mock.Mock} object when
using @ref{189a,,unittest.mock.create_autospec()}.

@item 
gh-111259@footnote{https://github.com/python/cpython/issues/111259}: @ref{be,,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{11e1,,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{507,,ipaddress.IPv4Address} and
@ref{508,,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{18b4,,asyncio.Runner.run()} to accept @ref{4c4,,awaitable}
objects instead of simply @ref{6b2,,coroutine}s.

@item 
gh-120541@footnote{https://github.com/python/cpython/issues/120541}: Improve the prompt in the "less" pager when @ref{acb,,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{10c,,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{18b5,,inspect.ismethoddescriptor()} to check also for
the lack of @ref{18b6,,__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{847,,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{101,,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{33,,dataclasses}, @ref{331,,typing.TypedDict}, and
@ref{330,,typing.NamedTuple}.

@item 
gh-119600@footnote{https://github.com/python/cpython/issues/119600}: Fix @ref{108d,,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 @ref{2b,,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{213,,Fraction}.

@item 
gh-114053@footnote{https://github.com/python/cpython/issues/114053}: Fix edge-case bug where @ref{8b9,,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{450,,NameError} when calling
@ref{a0d,,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{dc8,,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{59d,,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{272,,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{ff,,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{18b7,,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{34,,datetime} no longer crashes in certain complex reference
cycle situations.

@item 
gh-119698@footnote{https://github.com/python/cpython/issues/119698}: Fix @ref{31c,,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{18b8,,concurrent.futures.InvalidStateError} to module's
@code{__all__}.

@item 
gh-119933@footnote{https://github.com/python/cpython/issues/119933}: Add the @ref{18b9,,symtable.SymbolTableType} enumeration to
represent the possible outputs of the
@ref{18ba,,symtable.SymbolTable.get_type} method. Patch by Bénédikt Tran.

@item 
gh-120029@footnote{https://github.com/python/cpython/issues/120029}: Expose @ref{289,,symtable.Symbol} methods
@ref{28c,,is_free_class()},
@ref{28b,,is_comp_iter()} and
@ref{28a,,is_comp_cell()}. Patch by Bénédikt Tran.

@item 
gh-120108@footnote{https://github.com/python/cpython/issues/120108}: Fix calling @ref{d5d,,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{f6,,tkinter} with Tcl 9.0.

@item 
gh-120057@footnote{https://github.com/python/cpython/issues/120057}: Added the @ref{259,,os.environ.refresh()} method to
update @ref{259,,os.environ} with changes to the environment made by
@ref{25b,,os.putenv()}, by @ref{25c,,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{18bb,,symtable.Symbol.is_type_parameter()} in the
@ref{de,,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{18bc,,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{2e,,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{34,,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{213,,Fraction} and complex, the fraction is now converted to
@ref{196,,float} instead of @ref{197,,complex}.

@item 
gh-119770@footnote{https://github.com/python/cpython/issues/119770}: Make @ref{e7,,termios} @code{ioctl()} constants positive. Patch by
Victor Stinner.

@item 
gh-89727@footnote{https://github.com/python/cpython/issues/89727}: Fix issue with @ref{354,,shutil.rmtree()} where a
@ref{f63,,RecursionError} is raised on deep directory trees.

@item 
gh-119577@footnote{https://github.com/python/cpython/issues/119577}: The @ref{1a3,,DeprecationWarning} emitted when testing the truth
value of an @ref{361,,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{354,,shutil.rmtree()} where a
@ref{f63,,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{101,,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{d4a,,os.fwalk()} where a @ref{f63,,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{18e,,SyntaxError} from @ref{4ac,,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{be,,re}. Patch by Jelle Zijlstra.

@item 
gh-119127@footnote{https://github.com/python/cpython/issues/119127}: Positional arguments of @ref{217,,functools.partial()} objects now
support placeholders via @ref{216,,functools.Placeholder}.

@item 
gh-113892@footnote{https://github.com/python/cpython/issues/113892}: Now, the method @code{sock_connect} of
@ref{816,,asyncio.ProactorEventLoop} raises a @ref{2eb,,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{166f,,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{822,,datetime.time.fromisoformat()} that were
previously parsed incorrectly.

@item 
gh-111201@footnote{https://github.com/python/cpython/issues/111201}: Remove dependency to @ref{bf,,readline} from the new Python REPL.

@item 
gh-119189@footnote{https://github.com/python/cpython/issues/119189}: When using the @code{**} operator or @ref{1a4,,pow()} with
@ref{213,,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{18bd,,pathlib.PurePath.with_suffix()} didn't
raise @ref{198,,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{3f,,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{267,,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{18be,,pathlib.PurePath.suffix} and related attributes and methods. For
example, the @ref{18bf,,suffixes} of
@code{PurePath('foo.bar.')} are now @code{['.bar', '.']} rather than @code{[]}.
This brings file extension splitting in line with
@ref{18c0,,os.path.splitext()}.

@item 
gh-118924@footnote{https://github.com/python/cpython/issues/118924}: Remove @code{version} and @code{version_info} from
@ref{d4,,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{d4,,sqlite3} queries. Patch by Erlend E. Aasland.

@item 
gh-118895@footnote{https://github.com/python/cpython/issues/118895}: Setting attributes on @ref{563,,typing.NoDefault} now raises
@ref{5e8,,AttributeError} instead of @ref{198,,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{110,,urllib.parse}. It had previously raised a @ref{1a3,,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{300,,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{4bd,,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{1a3,,DeprecationWarning} since Python 3.12.

@item 
gh-118798@footnote{https://github.com/python/cpython/issues/118798}: The `isdst' parameter has been removed from
@ref{2f6,,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{266,,pathlib.Path}.

@item 
gh-101357@footnote{https://github.com/python/cpython/issues/101357}: Suppress all @ref{2c0,,OSError} exceptions from
@ref{c02,,pathlib.Path.exists()} and @code{is_*()} methods, rather than a
selection of more common errors. The new behaviour is consistent with
@ref{bfa,,os.path.exists()}, @ref{bfc,,os.path.isdir()}, etc. Use
@ref{a1d,,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{2fc,,pathlib.PurePath.relative_to()} and
@ref{2fd,,is_relative_to()}.

@item 
gh-118507@footnote{https://github.com/python/cpython/issues/118507}: Fix @ref{bfd,,os.path.isfile()} on Windows for pipes. Speedup
@ref{6c3,,os.path.isjunction()} and @ref{bfb,,os.path.lexists()} on Windows with a
native implementation.

@item 
gh-118772@footnote{https://github.com/python/cpython/issues/118772}: Allow @ref{481,,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{262,,os.path.realpath()} now suppresses any @ref{2c0,,OSError} from
@ref{b11,,os.readlink()} when `strict' mode is disabled (the default).

@item 
gh-118263@footnote{https://github.com/python/cpython/issues/118263}: Speed up @ref{6c4,,os.path.splitroot()} & @ref{151a,,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{4dc,,dataclasses.dataclass()} not creating a
@code{__weakref__} slot when subclassing @ref{174e,,typing.Generic}.

@item 
gh-117766@footnote{https://github.com/python/cpython/issues/117766}: Always use @ref{169,,str()} to print @code{choices} in @ref{7,,argparse}.

@item 
gh-106531@footnote{https://github.com/python/cpython/issues/106531}: In @ref{7f,,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{4de,,inspect.Signature}
instance.  Patch by Sergey B Kirpichev.

@item 
gh-115808@footnote{https://github.com/python/cpython/issues/115808}: Add @ref{255,,operator.is_none()} and @ref{256,,operator.is_not_none()}
functions.

@item 
gh-114264@footnote{https://github.com/python/cpython/issues/114264}: Improve performance of @ref{d5d,,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{18c1,,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{16df,,__slots__} dict. Otherwise, the supplied string is
only available in the corresponding @ref{18c2,,dataclasses.Field} object.

In order to support this feature we are changing the @code{__slots__} format
in dataclasses from @ref{60c,,tuple} to @ref{183,,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{18c3,,ssl.SSLSocket.get_verified_chain()} and
@ref{18c4,,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{18a8,,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{823,,datetime.datetime.fromisoformat()} and
@ref{822,,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{103,,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{3c1,,bool}, @ref{169,,str}, @ref{343,,bytearray}, or @ref{19b,,int}.

@item 
gh-87106@footnote{https://github.com/python/cpython/issues/87106}: Fixed handling in @ref{180b,,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{24c,,proxy objects} in the @code{multiprocessing} module:


@itemize *

@item 
@code{clear()} and @code{copy()} for proxies of @ref{24d,,list}

@item 
@ref{24e,,fromkeys()}, @code{reversed(d)}, @code{d | @{@}}, @code{@{@} | d},
@code{d |= @{'b': 2@}} for proxies of @ref{183,,dict}
@end itemize

@item 
bpo-45767@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45767}: Fix integer conversion in @ref{18c5,,os.major()}, @ref{18c6,,os.minor()},
and @ref{18c7,,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{1bd,,argparse.ArgumentParser}.

@item 
bpo-41843@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41843}: Solaris now uses @ref{cfd,,os.sendfile()} fast-copy syscall for more
efficient @ref{ca,,shutil} file copy related functions.

@item 
bpo-15987@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15987}: Implemented @ref{1bf,,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{18a5,,urllib.parse.urlunparse()} and
@ref{18a4,,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<6>,Documentation<10>,Library<16>,Python 3 14 0 alpha 1
@anchor{whatsnew/changelog id118}@anchor{18c8}
@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<10>,Core and Builtins<15>,IDLE<6>,Python 3 14 0 alpha 1
@anchor{whatsnew/changelog id119}@anchor{18c9}
@subsubsection Documentation



@itemize -

@item 
gh-124872@footnote{https://github.com/python/cpython/issues/124872}: Added definitions for @ref{18ca,,context}, @ref{18cb,,current context},
and @ref{18cc,,context management protocol}, updated related definitions to be
consistent, and expanded the documentation for
@ref{177,,contextvars.Context}.

@item 
gh-125018@footnote{https://github.com/python/cpython/issues/125018}: The @ref{7e,,importlib.metadata} documentation now includes
semantic cross-reference targets for the significant documented APIs. This
means intersphinx references like @ref{18cd,,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{18ce,,unittest.mock.patch.dict()}

@item 
gh-121749@footnote{https://github.com/python/cpython/issues/121749}: Fix documentation for @ref{602,,PyModule_AddObjectRef()}.

@item 
gh-120012@footnote{https://github.com/python/cpython/issues/120012}: Clarify the behaviours of @ref{18cf,,multiprocessing.Queue.empty()}
and @ref{18d0,,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{801,,--help-env}.

@item 
bpo-34008@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34008}: The @ref{e19,,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<15>,C API<14>,Documentation<10>,Python 3 14 0 alpha 1
@anchor{whatsnew/changelog id120}@anchor{18d1}
@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{18d2,,__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.

@item 
gh-125008@footnote{https://github.com/python/cpython/issues/125008}: Fix @ref{1829,,tokenize.untokenize()} producing invalid syntax for
double braces preceded by certain escape characters.

@item 
gh-124871@footnote{https://github.com/python/cpython/issues/124871}: Fix compiler bug (in some versions of 3.13) where an assertion
fails during reachability analysis.

@item 
gh-123378@footnote{https://github.com/python/cpython/issues/123378}: Fix a crash in the @ref{829,,__str__()} method of
@ref{460,,UnicodeError} objects when the @ref{1834,,UnicodeError.start} and
@ref{1835,,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{471,,__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{18d3,,_PyInterpreterFrame} struct now uses a tagged pointer.
Profilers and debuggers that uses this field should clear the least
significant bit to recover the @ref{5d7,,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{165,,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

@item 
gh-123614@footnote{https://github.com/python/cpython/issues/123614}: Add @ref{18d4,,turtle.save()} to easily save Turtle drawings as
PostScript files. Patch by Marie Roald and Yngve Mardal Moe.

@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{18e,,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{198,,TypeError} when builtin magic
methods are used without the required args.

@item 
gh-123440@footnote{https://github.com/python/cpython/issues/123440}: Improve @ref{18e,,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{1a0,,zip()} iterator
safe under free-threading.

@item 
gh-123275@footnote{https://github.com/python/cpython/issues/123275}: Support @ref{16f,,-X gil=1} and 
@geindex PYTHON_GIL
@geindex 環境變數; PYTHON_GIL
@ref{495,,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{18e,,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{18d5,,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{18e,,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{45e,,Py_Initialize()} from a non-main thread.

@item 
gh-118093@footnote{https://github.com/python/cpython/issues/118093}: Add three specializations for @ref{370,,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{18d6,,while} statements have
consistent offsets for @ref{e0,,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{16f,,-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{b75,,tp_basicsize} now accounts for non-sequence
fields that aren't included in the @ref{97d,,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{471,,__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{348,,for}
loops from correctly firing @ref{18d7,,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{4a0,,frame.f_locals} now supports arbitrary hashable objects
as keys.

@item 
gh-122239@footnote{https://github.com/python/cpython/issues/122239}: When a @ref{24d,,list}, @ref{60c,,tuple} or @ref{183,,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{18c,,-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{68e,,sum()} now always use compensated summation.  Also, for integer items
in above specializations: @ref{18d8,,PyLong_AsDouble()} is used, instead of
@ref{1467,,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{367,,BUILD_MAP} instead.

@item 
gh-122029@footnote{https://github.com/python/cpython/issues/122029}: Emit @code{c_call} events in @ref{16f2,,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).

@item 
gh-121999@footnote{https://github.com/python/cpython/issues/121999}: The default extraction filter for the @ref{e4,,tarfile} module is
now set to @ref{29a,,'data'}.

@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{65b,,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{18e,,SyntaxError} message if the user tries to use
@ref{bb9,,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{18d,,await} or asynchronous
comprehensions in code removed by the @ref{18c,,-O} option was not flagged
by the Python compiler. Now, such code raises @ref{18e,,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{2eb,,ValueError} messages for @ref{15bc,,list.index()},
@ref{18d9,,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{18da,,index()} and @ref{18db,,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{68e,,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

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

@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{5fe,,PyLong_AsNativeBytes()} no longer uses
@ref{19e,,__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{45d,,Py_Finalize()} and @ref{f0c,,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{36d,,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{14dc,,sys.intern()} are again
garbage-collected when no longer used, as per the documentation. Strings
interned with the C function @ref{aa5,,PyUnicode_InternInPlace()} are still
immortal. Internals of the string interning mechanism have been changed.
This may affect performance and identities of @ref{169,,str} objects.

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

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

@item 
gh-120380@footnote{https://github.com/python/cpython/issues/120380}: Fix Python implementation of @ref{c0a,,pickle.Pickler} for
@ref{192,,bytes} and @ref{343,,bytearray} objects when using protocol version
5. Patch by Bénédikt Tran.

@item 
gh-120397@footnote{https://github.com/python/cpython/issues/120397}: Improve the throughput by up to two times for the
@ref{18dc,,str.count()}, @ref{18dd,,bytes.count()} and @ref{18de,,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{1b6,,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{18e,,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{79d,,PyOS_InputHook()} in the new REPL. Patch by Pablo
Galindo

@item 
gh-119180@footnote{https://github.com/python/cpython/issues/119180}: @ref{489,,classmethod()} and @ref{451,,staticmethod()} now wrap the
@ref{456,,__annotations__} and @ref{18df,,__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{4a6,,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{19b,,int()} to
@ref{19c,,__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{197,,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{fd2,,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{368,,LOAD_COMMON_CONSTANT} and add support for
@ref{369,,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{df0,,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{118,,warnings} module had not yet been imported.

@item 
gh-119057@footnote{https://github.com/python/cpython/issues/119057}: Improve @ref{b36,,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{1a2,,NotImplemented} in a boolean context now raises
@ref{198,,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{5fa,,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.

@item 
gh-115801@footnote{https://github.com/python/cpython/issues/115801}: Raise @code{TypeError} when passing a string to
@ref{18e0,,difflib.unified_diff()} and @ref{18e1,,difflib.context_diff()}.

@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{828,,__repr__()} output of
@ref{4be,,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{45d,,Py_Finalize()} now deletes all interned strings.

@item 
gh-84978@footnote{https://github.com/python/cpython/issues/84978}: Add class methods @ref{194,,float.from_number()} and
@ref{195,,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<14>,Build<14>,Core and Builtins<15>,Python 3 14 0 alpha 1
@anchor{whatsnew/changelog id121}@anchor{18e2}
@subsubsection C API



@itemize -

@item 
gh-123961@footnote{https://github.com/python/cpython/issues/123961}: Convert the @ref{18e3,,curses.window} static
type exposed by the @code{PyCursesWindow_Type} macro in
@code{Include/py_curses.h} to a @ref{b55,,heap type}. Patch by
Bénédikt Tran.

@item 
gh-124502@footnote{https://github.com/python/cpython/issues/124502}: Add @ref{3b0,,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{647,,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{3ae,,PyType_GetBaseByToken()} and @ref{3af,,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{2cf,,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{796,,PyType_FromSpec()}, @ref{797,,PyType_FromSpecWithBases()}
and @ref{76c,,PyType_FromModuleAndSpec()} will now fail if the metaclass of
the new type has custom @ref{798,,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{385,,PyInitConfig_Create()}

@item 
@ref{386,,PyInitConfig_Free()}

@item 
@ref{388,,PyInitConfig_GetError()}

@item 
@ref{389,,PyInitConfig_GetExitCode()}

@item 
@ref{38d,,PyInitConfig_HasOption()}

@item 
@ref{38a,,PyInitConfig_GetInt()}

@item 
@ref{38b,,PyInitConfig_GetStr()}

@item 
@ref{38c,,PyInitConfig_GetStrList()}

@item 
@ref{387,,PyInitConfig_FreeStrList()}

@item 
@ref{38e,,PyInitConfig_SetInt()}

@item 
@ref{38f,,PyInitConfig_SetStr()}

@item 
@ref{390,,PyInitConfig_SetStrList()}

@item 
@ref{379,,PyInitConfig_AddModule()}

@item 
@ref{384,,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{37a,,PyConfig_Get()}

@item 
@ref{382,,PyConfig_GetInt()}

@item 
@ref{37b,,PyConfig_Set()}

@item 
@ref{383,,PyConfig_Names()}
@end itemize

Patch by Victor Stinner.

@item 
gh-123465@footnote{https://github.com/python/cpython/issues/123465}: @ref{769,,Py_RELATIVE_OFFSET} is now allowed in
@ref{76a,,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{18e4,,tp_vectorcall} via the @ref{796,,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{393,,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{5f0,,PyEval_GetLocals()} to avoid @ref{78e,,SystemError}
("bad argument to internal function"). Patch by Victor Stinner.

@item 
gh-116622@footnote{https://github.com/python/cpython/issues/116622}: Make @ref{18e5,,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{396,,PyIter_NextItem()} to replace @ref{397,,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{381,,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{15d2,,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{aa5,,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{18e6,,PyUnicode_InternFromString()},
@ref{18e7,,PyDict_SetItemString()}, @ref{18e8,,PyObject_SetAttrString()},
@ref{17af,,PyObject_DelAttrString()}, @ref{18e6,,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{18e9,,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{19b,,int}:


@itemize *

@item 
@ref{3a1,,PyLong_FromInt32()}

@item 
@ref{3a3,,PyLong_FromUInt32()}

@item 
@ref{3a2,,PyLong_FromInt64()}

@item 
@ref{3a4,,PyLong_FromUInt64()}

@item 
@ref{39d,,PyLong_AsInt32()}

@item 
@ref{39f,,PyLong_AsUInt32()}

@item 
@ref{39e,,PyLong_AsInt64()}

@item 
@ref{3a0,,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{3c7,,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{623,,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{5b,,errno} in @ref{185f,,_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{3b1,,PyUnicodeWriter} API to create a Python
@ref{169,,str} object:


@itemize *

@item 
@ref{3b2,,PyUnicodeWriter_Create()}.

@item 
@ref{3b4,,PyUnicodeWriter_Discard()}.

@item 
@ref{3b5,,PyUnicodeWriter_Finish()}.

@item 
@ref{3b8,,PyUnicodeWriter_WriteChar()}.

@item 
@ref{3bd,,PyUnicodeWriter_WriteUTF8()}.

@item 
@ref{3bc,,PyUnicodeWriter_WriteUCS4()}.

@item 
@ref{3be,,PyUnicodeWriter_WriteWideChar()}.

@item 
@ref{3ba,,PyUnicodeWriter_WriteStr()}.

@item 
@ref{3b9,,PyUnicodeWriter_WriteRepr()}.

@item 
@ref{3bb,,PyUnicodeWriter_WriteSubstring()}.

@item 
@ref{3b6,,PyUnicodeWriter_Format()}.

@item 
@ref{3b3,,PyUnicodeWriter_DecodeUTF8Stateful()}.
@end itemize

Patch by Victor Stinner.

@item 
gh-119613@footnote{https://github.com/python/cpython/issues/119613}: Soft deprecate the @code{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{3cd,,immutable types}
with mutable bases was deprecated since 3.12 and now raises a
@ref{198,,TypeError}.

@item 
gh-119585@footnote{https://github.com/python/cpython/issues/119585}: Fix crash when a thread state that was created by
@ref{642,,PyGILState_Ensure()} calls a destructor that during
@ref{18ea,,PyThreadState_Clear()} that calls back into
@ref{642,,PyGILState_Ensure()} and @ref{643,,PyGILState_Release()}. This might
occur when in the free-threaded build or when using thread-local variables
whose destructors call @ref{642,,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{23d,,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{18eb,,PyContext_AddWatcher()} and
@ref{18ec,,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{18ed,,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{18ee,,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{47f,,PyMutex} public in the non-limited C API.

@item 
gh-116560@footnote{https://github.com/python/cpython/issues/116560}: Add @ref{398,,PyLong_GetSign()} function.  Patch by Sergey B
Kirpichev.

@item 
gh-97588@footnote{https://github.com/python/cpython/issues/97588}: Fix creating bitfields in @ref{2e,,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<14>,,C API<14>,Python 3 14 0 alpha 1
@anchor{whatsnew/changelog id122}@anchor{18ef}
@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{62e,,--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{e1,,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{18f0,,--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{264,,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{2f,,curses} and @ref{31,,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{497,,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{18f1}
@subsection Python 3.13.0 beta 1


`Release date: 2024-05-08'

@menu
* Security: Security<15>. 
* Core and Builtins: Core and Builtins<16>. 
* Library: Library<17>. 
* Documentation: Documentation<11>. 
* Build: Build<15>. 
* Windows: Windows<13>. 
* macOS: macOS<8>. 
* IDLE: IDLE<7>. 
* C API: C API<15>. 

@end menu

@node Security<15>,Core and Builtins<16>,,Python 3 13 0 beta 1
@anchor{whatsnew/changelog id123}@anchor{18f2}
@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{6c,,hashlib}
to be used with libraries that do not to support every algorithm that
upstream OpenSSL does.
@end itemize

@node Core and Builtins<16>,Library<17>,Security<15>,Python 3 13 0 beta 1
@anchor{whatsnew/changelog id124}@anchor{18f3}
@subsubsection Core and Builtins



@itemize -

@item 
gh-118414@footnote{https://github.com/python/cpython/issues/118414}: Add instrumented opcodes to YIELD_VALUE assertion for tracing
cases.

@item 
gh-117953@footnote{https://github.com/python/cpython/issues/117953}: When a builtin or extension module is imported for the first
time, while a subinterpreter is active, the module's init function is now
run by the main interpreter first before import continues in the
subinterpreter. Consequently, single-phase init modules now fail in an
isolated subinterpreter without the init function running under that
interpreter, whereas before it would run under the subinterpreter `before'
failing, potentially leaving behind global state and callbacks and
otherwise leaving the module in an inconsistent state.

@item 
gh-117549@footnote{https://github.com/python/cpython/issues/117549}: Don't use designated initializer syntax in inline functions in
internal headers. They cause problems for C++ or MSVC users who aren't yet
using the latest C++ standard (C++20). While internal, pycore_backoff.h,
is included (indirectly, via pycore_code.h) by some key 3rd party software
that does so for speed.

@item 
gh-95382@footnote{https://github.com/python/cpython/issues/95382}: Improve performance of @ref{f3c,,json.dumps()} and @ref{f3b,,json.dump()}
when using the argument `indent'. Depending on the data the encoding using
@ref{f3c,,json.dumps()} with `indent' can be up to 2 to 3 times faster.

@item 
gh-116322@footnote{https://github.com/python/cpython/issues/116322}: In @code{--disable-gil} builds, the GIL will be enabled while
loading C extension modules. If the module indicates that it supports
running without the GIL, the GIL will be disabled once loading is
complete. Otherwise, the GIL will remain enabled for the remainder of the
interpreter's lifetime. This behavior does not apply if the GIL has been
explicitly enabled or disabled with @code{PYTHON_GIL} or @code{-Xgil}.

@item 
gh-118513@footnote{https://github.com/python/cpython/issues/118513}: Fix incorrect @ref{172a,,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{3a,,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{18f4,,sys.set_asyncgen_hooks()} not to be partially set when
raising @ref{198,,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{1b5,,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{4a0,,FrameType.f_locals} and @ref{659,,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{4a6,,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{18e,,SyntaxError} message for imports without names,
like in @code{from x import} and @code{import} cases. It now points out to users
that @ref{7f1,,import} expects at least one name after it.

@item 
gh-118090@footnote{https://github.com/python/cpython/issues/118090}: Improve @ref{18e,,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{4a6,,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{4d2,,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{192,,bytes} and
@ref{343,,bytearray} methods by adapting them to the
@ref{18f5,,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{169,,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{2e1,,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{608,,PyRefTracer_SetTracer()} and @ref{609,,PyRefTracer_GetTracer()}, that
allows to track object creation and destruction the same way the
@ref{105,,tracemalloc} module does. Patch by Pablo Galindo

@item 
gh-107674@footnote{https://github.com/python/cpython/issues/107674}: Improved the performance of @ref{2e1,,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{5e8,,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{49d,,exec()} and
@ref{49e,,eval()} to be passed as keywords.
@end itemize

@node Library<17>,Documentation<11>,Core and Builtins<16>,Python 3 13 0 beta 1
@anchor{whatsnew/changelog id125}@anchor{18f6}
@subsubsection Library



@itemize -

@item 
gh-118418@footnote{https://github.com/python/cpython/issues/118418}: A @ref{1a3,,DeprecationWarning} is now emitted if you fail to pass
a value to the new `type_params' parameter of @code{typing._eval_type()} or
@code{typing.ForwardRef._evaluate()}. (Using either of these private and
undocumented functions is discouraged to begin with, but failing to pass a
value to the @code{type_params} parameter may lead to incorrect behaviour on
Python 3.12 or newer.)

@item 
gh-118660@footnote{https://github.com/python/cpython/issues/118660}: Add an optional second type parameter to
@ref{e86,,typing.ContextManager} and @ref{18f7,,typing.AsyncContextManager},
representing the return types of @ref{1501,,__exit__()} and
@ref{18f8,,__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{18f9,,typing.Generator} and
@ref{18fa,,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{548,,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{22f,,inspect.signature()} for non-comparable callables.

@item 
gh-118402@footnote{https://github.com/python/cpython/issues/118402}: Fix @ref{22f,,inspect.signature()} for the result of the
@ref{13db,,functools.cmp_to_key()} call.

@item 
gh-116622@footnote{https://github.com/python/cpython/issues/116622}: On Android, @ref{1443,,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{102e,,operator.attrgetter}, @ref{c4e,,operator.itemgetter}, and
@ref{102f,,operator.methodcaller} instances.

@item 
gh-118314@footnote{https://github.com/python/cpython/issues/118314}: Fix an edge case in @ref{18fb,,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{54a,,sqlite3.Connection.iterdump()} could fail
if a custom @ref{18fc,,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{6b5,,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{82,,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{a0f,,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{4be,,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{189a,,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{18fd,,typing.Unpack}
is used with the builtin @ref{60c,,tuple}. @code{typing.Unpack} now raises
@ref{198,,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{bd,,random} module. Patch
by Hugo van Kemenade.

@item 
gh-118107@footnote{https://github.com/python/cpython/issues/118107}: Fix @ref{138,,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{151a,,os.path.normpath()} for UNC paths on Windows. Speed up
@ref{6c4,,os.path.splitroot()} with a native implementation.

@item 
gh-117535@footnote{https://github.com/python/cpython/issues/117535}: Change the unknown filename of @ref{118,,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{450,,NameError} when calling
@ref{8b9,,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{18fe,,tarfile.TarFile.addfile()}

@item 
gh-117995@footnote{https://github.com/python/cpython/issues/117995}: Don't raise @ref{1a3,,DeprecationWarning} when a @ref{70f,,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{13ce,,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{e4,,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{532,,pathlib.Path.glob()} by omitting an initial
@ref{535,,is_dir()} call. As a result of this change,
@ref{532,,glob()} can no longer raise @ref{2c0,,OSError}.

@item 
gh-77102@footnote{https://github.com/python/cpython/issues/77102}: @ref{cc,,site} module now parses @code{.pth} file with UTF-8 first,
and @ref{545,,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{532,,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{26e,,pathlib.Path.iterdir()} by using
@ref{c4b,,os.scandir()} internally.

@item 
gh-117586@footnote{https://github.com/python/cpython/issues/117586}: Speed up @ref{6c8,,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{4cb,,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{18ff,,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{1038,,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{1900,,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{6ca,,os.path.relpath()}.

@item 
gh-117586@footnote{https://github.com/python/cpython/issues/117586}: Speed up @ref{532,,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{1901,,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{262,,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{4cc,,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{4cd,,ExceptionGroup}, it will now call the parent task's
@ref{4ce,,cancel()} method. This ensures that a
@ref{4cf,,asyncio.CancelledError} will be raised at the next @ref{18d,,await},
so the cancellation is not lost.

An added benefit of these changes is that task groups now preserve the
cancellation count (@ref{4d0,,asyncio.Task.cancelling()}).

In order to handle some corner cases, @ref{4d1,,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{486,,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{c00,,os.path.expanduser()} on Posix.

@item 
gh-117394@footnote{https://github.com/python/cpython/issues/117394}: @ref{bfe,,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{3f,,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{511,,mimetypes.guess_file_type()} function which works
with file path. Passing file path instead of URL in
@ref{512,,guess_type()} is @ref{23d,,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{5e8,,AttributeError} and
@ref{653,,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{ad8,,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{8e,,lzma},
@ref{e4,,tarfile} and @ref{137,,zipfile}. The value of the @code{mode}
attribute of @ref{654,,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{655,,zipfile.ZipFile.open()} was changed from @code{'r'} to @code{'rb'}.

@item 
gh-82062@footnote{https://github.com/python/cpython/issues/82062}: Fix @ref{22f,,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{6c6,,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{93b,,__class_getitem__()} to
@ref{1902,,types.GeneratorType} and @ref{1084,,types.CoroutineType} for type
hinting purposes. Patch by James Hilton-Balfe.

@item 
gh-108191@footnote{https://github.com/python/cpython/issues/108191}: The @ref{4e0,,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{1903,,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{f6,,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{543,,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<11>,Build<15>,Library<17>,Python 3 13 0 beta 1
@anchor{whatsnew/changelog id126}@anchor{1904}
@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<15>,Windows<13>,Documentation<11>,Python 3 13 0 beta 1
@anchor{whatsnew/changelog id127}@anchor{1905}
@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{64f,,--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{3a,,decimal} dependencies if the @ref{64f,,--with-system-libmpdec} option
is given.
@end itemize

@node Windows<13>,macOS<8>,Build<15>,Python 3 13 0 beta 1
@anchor{whatsnew/changelog id128}@anchor{1906}
@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{526,,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<8>,IDLE<7>,Windows<13>,Python 3 13 0 beta 1
@anchor{whatsnew/changelog id129}@anchor{1907}
@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<7>,C API<15>,macOS<8>,Python 3 13 0 beta 1
@anchor{whatsnew/changelog id130}@anchor{1908}
@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<15>,,IDLE<7>,Python 3 13 0 beta 1
@anchor{whatsnew/changelog id131}@anchor{1909}
@subsubsection C API



@itemize -

@item 
gh-118124@footnote{https://github.com/python/cpython/issues/118124}: Fix @code{Py_BUILD_ASSERT} and
@code{Py_BUILD_ASSERT_EXPR} for non-constant expressions: use
@code{static_assert()} on C11 and newer. Patch by Victor Stinner.

@item 
gh-110850@footnote{https://github.com/python/cpython/issues/110850}: Add "Raw" variant of PyTime functions


@itemize *

@item 
@ref{5d0,,PyTime_MonotonicRaw()}

@item 
@ref{5d2,,PyTime_PerfCounterRaw()}

@item 
@ref{5d4,,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{190a,,Py_SetPythonHome()}

@item 
@ref{190b,,Py_SetProgramName()}

@item 
@ref{190c,,PySys_SetArgvEx()}

@item 
@ref{190d,,PySys_SetArgv()}
@end itemize

Patch by Victor Stinner.

@item 
gh-117929@footnote{https://github.com/python/cpython/issues/117929}: Restore removed @ref{190e,,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{823,,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{190f}
@subsection Python 3.13.0 alpha 6


`Release date: 2024-04-09'

@menu
* Core and Builtins: Core and Builtins<17>. 
* Library: Library<18>. 
* Documentation: Documentation<12>. 
* Tests: Tests<13>. 
* Build: Build<16>. 
* Windows: Windows<14>. 
* C API: C API<16>. 

@end menu

@node Core and Builtins<17>,Library<18>,,Python 3 13 0 alpha 6
@anchor{whatsnew/changelog id132}@anchor{1910}
@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{192,,bytes} and
@ref{343,,bytearray} methods by adapting them to the
@ref{18f5,,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{169,,str} methods
by adapting them to the @ref{18f5,,METH_FASTCALL} calling convention:


@itemize *

@item 
@ref{18dc,,count()}

@item 
@ref{10c7,,endswith()}

@item 
@ref{10a3,,find()}

@item 
@ref{1911,,index()}

@item 
@ref{10a4,,rfind()}

@item 
@ref{1458,,rindex()}

@item 
@ref{10c6,,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{4be,,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{6c,,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{1912,,CALL} event.

@item 
gh-113964@footnote{https://github.com/python/cpython/issues/113964}: Starting new threads and process creation through
@ref{4b0,,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{1912,,CALL}

@item 
gh-116554@footnote{https://github.com/python/cpython/issues/116554}: @code{list.sort()} now exploits more cases of partial ordering,
particularly those with long descending runs with sub-runs of equal
values. Those are recognized as single runs now (previously, each block of
repeated values caused a new run to be created).

@item 
gh-114099@footnote{https://github.com/python/cpython/issues/114099}: Added a Loader that can discover extension modules in an
iOS-style Frameworks folder.

@item 
gh-115775@footnote{https://github.com/python/cpython/issues/115775}: Compiler populates the new @code{__static_attributes__} field on a
class with the names of attributes of this class which are accessed
through self.X from any function in its body.

@item 
gh-115776@footnote{https://github.com/python/cpython/issues/115776}: The array of values, the @code{PyDictValues} struct is now
embedded in the object during allocation. This provides better performance
in the common case, and does not degrade as much when the object's
@code{__dict__} is materialized.

@item 
gh-108362@footnote{https://github.com/python/cpython/issues/108362}: Implement an incremental cyclic garbage collector. By
collecting the old generation in increments, there is no need for a full
heap scan. This can hugely reduce maximum pause time for programs with
large heaps.

Reduce the number of generations from three to two. The old generation is
split into two spaces, "visited" and "pending".

Collection happens in two steps:: * An increment is formed from the young
generation and a small part of the pending space. * This increment is
scanned and the survivors moved to the end of the visited space.

When the collecting space becomes empty, the two spaces are swapped.

@item 
gh-109870@footnote{https://github.com/python/cpython/issues/109870}: Dataclasses now calls @ref{49d,,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}.

@item 
bpo-24612@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24612}: Improve the @ref{18e,,SyntaxError} that happens when 'not' appears
after an operator. Patch by Pablo Galindo
@end itemize

@node Library<18>,Documentation<12>,Core and Builtins<17>,Python 3 13 0 alpha 6
@anchor{whatsnew/changelog id133}@anchor{1913}
@subsubsection Library



@itemize -

@item 
gh-117648@footnote{https://github.com/python/cpython/issues/117648}: Improve performance of @ref{1900,,os.path.join()} and
@ref{c00,,os.path.expanduser()}.

@item 
gh-117584@footnote{https://github.com/python/cpython/issues/117584}: Raise @ref{198,,TypeError} for non-paths in
@ref{6ca,,posixpath.relpath}.

@item 
gh-117467@footnote{https://github.com/python/cpython/issues/117467}: Preserve mailbox ownership when rewriting in
@ref{1914,,mailbox.mbox.flush}. Patch by Tony
Mountifield.

@item 
gh-114848@footnote{https://github.com/python/cpython/issues/114848}: Raise @ref{264,,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{a2f,,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{59a,,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{4d9,,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{654,,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{d5,,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{dc,,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{d13,,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{3c,,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{100f,,types.ModuleType}.

@item 
gh-117084@footnote{https://github.com/python/cpython/issues/117084}: Fix @ref{137,,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{1915,,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{8b3,,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{18b7,,datetime.datetime.strptime()} and @ref{1624,,time.strptime()} which always
fails to parse a date string with a @ref{2eb,,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{edb,,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{557,,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{110,,urllib.parse} functions @ref{31e,,parse_qs()} and
@ref{31d,,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{1916,,ipaddress.IPv4Address.is_private} (see these docs for details)

@item 
@ref{115a,,ipaddress.IPv4Address.is_global}

@item 
@ref{1917,,ipaddress.IPv6Address.is_private}

@item 
@ref{1918,,ipaddress.IPv6Address.is_global}
@end itemize

Also in the corresponding @ref{509,,ipaddress.IPv4Network} and
@ref{50a,,ipaddress.IPv6Network} attributes.

@item 
gh-63283@footnote{https://github.com/python/cpython/issues/63283}: In @ref{56,,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{1919,,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{50f,,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{7f,,importlib.resources} functions
@ref{4f8,,is_resource()},
@ref{4f9,,open_binary()},
@ref{4fa,,open_text()}, @ref{4fb,,path()},
@ref{4fc,,read_binary()}, and
@ref{4fd,,read_text()} are un-deprecated, and support
subdirectories via multiple positional arguments. The
@ref{4fe,,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{2e,,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{d4a,,os.fwalk()} and @ref{354,,shutil.rmtree()} on
opening named pipe.

@item 
gh-71052@footnote{https://github.com/python/cpython/issues/71052}: Implement @ref{f40,,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{116,,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{d5,,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{262,,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{4c9,,asyncio.Server.close_clients()} and
@ref{4ca,,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{c61,,asyncio.Queue} termination with
@ref{4c7,,shutdown()} method.

@item 
gh-89739@footnote{https://github.com/python/cpython/issues/89739}: The @ref{138,,zipimport} module can now read ZIP64 files.

@item 
bpo-33533@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33533}: @ref{4c1,,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{191a,,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{1759,,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{4cb,,asyncio.StreamReader.readuntil()}, stopping when one of them is
encountered.

@item 
gh-66543@footnote{https://github.com/python/cpython/issues/66543}: Make @ref{512,,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{11e0,,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<12>,Tests<13>,Library<18>,Python 3 13 0 alpha 6
@anchor{whatsnew/changelog id134}@anchor{191b}
@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<13>,Build<16>,Documentation<12>,Python 3 13 0 alpha 6
@anchor{whatsnew/changelog id135}@anchor{191c}
@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<16>,Windows<14>,Tests<13>,Python 3 13 0 alpha 6
@anchor{whatsnew/changelog id136}@anchor{191d}
@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<14>,C API<16>,Build<16>,Python 3 13 0 alpha 6
@anchor{whatsnew/changelog id137}@anchor{191e}
@subsubsection Windows



@itemize -

@item 
gh-117267@footnote{https://github.com/python/cpython/issues/117267}: Ensure @code{DirEntry.stat().st_ctime} behaves consistently with
@ref{26d,,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{191f,,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{556,,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<16>,,Windows<14>,Python 3 13 0 alpha 6
@anchor{whatsnew/changelog id138}@anchor{1920}
@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{1921,,_PyBytes_Resize()} can now be called for bytes objects
with reference count > 1, including 1-byte bytes objects. It creates a new
bytes object and destroys the old one if it has reference count > 1.

@item 
gh-117021@footnote{https://github.com/python/cpython/issues/117021}: Fix integer overflow in @code{PyLong_AsPid()} on non-Windows
64-bit platforms.

@item 
gh-115756@footnote{https://github.com/python/cpython/issues/115756}: @code{PyCode_GetFirstFree()} is an ustable API now and has
been renamed to @ref{61f,,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{62d,,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{5f1,,Py_GetConstant()} and
@ref{5f2,,Py_GetConstantBorrowed()} functions to get constants. For example,
@code{Py_GetConstant(Py_CONSTANT_ZERO)} returns a @ref{5da,,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{623,,PyUnicode_FromFormat()}: format the fully qualified name of an
object type and of a type: call @ref{610,,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{610,,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{60e,,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{62f,,limited C API}. Patch by Victor Stinner.

@item 
gh-111140@footnote{https://github.com/python/cpython/issues/111140}: Add additional flags to @ref{5fe,,PyLong_AsNativeBytes()} and
@ref{5ff,,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{604,,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{1922}
@subsection Python 3.13.0 alpha 5


`Release date: 2024-03-12'

@menu
* Security: Security<16>. 
* Core and Builtins: Core and Builtins<18>. 
* Library: Library<19>. 
* Documentation: Documentation<13>. 
* Tests: Tests<14>. 
* Build: Build<17>. 
* Windows: Windows<15>. 
* macOS: macOS<9>. 
* IDLE: IDLE<8>. 
* Tools/Demos: Tools/Demos<15>. 
* C API: C API<17>. 

@end menu

@node Security<16>,Core and Builtins<18>,,Python 3 13 0 alpha 5
@anchor{whatsnew/changelog id139}@anchor{1923}
@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{570,,xml.etree.ElementTree.XMLParser.flush()}

@item 
@ref{571,,xml.etree.ElementTree.XMLPullParser.flush()}

@item 
@ref{572,,xml.parsers.expat.xmlparser.GetReparseDeferralEnabled()}

@item 
@ref{573,,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{11a7,,ssl.SSLContext.cert_store_stats()} and
@ref{11a8,,ssl.SSLContext.get_ca_certs()} now correctly lock access to the
certificate store, when the @ref{355,,ssl.SSLContext} is shared across
multiple threads.
@end itemize

@node Core and Builtins<18>,Library<19>,Security<16>,Python 3 13 0 alpha 5
@anchor{whatsnew/changelog id140}@anchor{1924}
@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{68c,,PyErr_CheckSignals()} and the evaluation breaker.
Patch by Pablo Galindo

@item 
gh-112087@footnote{https://github.com/python/cpython/issues/112087}: @ref{24d,,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{18e,,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{1925,,bytearray.extend()} is called with a @ref{169,,str} object.

@item 
gh-112175@footnote{https://github.com/python/cpython/issues/112175}: Every @code{PyThreadState} now has its own @code{eval_breaker},
allowing specific threads to be interrupted.

@item 
gh-115154@footnote{https://github.com/python/cpython/issues/115154}: Fix a bug that was causing the @ref{1829,,tokenize.untokenize()}
function to handle unicode named literals incorrectly. Patch by Pablo
Galindo

@item 
gh-112433@footnote{https://github.com/python/cpython/issues/112433}: Add ability to force alignment of @ref{1e5,,ctypes.Structure} by
way of the new @code{_align_} attribute on the class.

@item 
gh-104090@footnote{https://github.com/python/cpython/issues/104090}: The multiprocessing resource tracker now exits with non-zero
status code if a resource leak was detected. It still exits with status
code 0 otherwise.

@item 
gh-105858@footnote{https://github.com/python/cpython/issues/105858}: Improve the constructors for @ref{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<19>,Documentation<13>,Core and Builtins<18>,Python 3 13 0 alpha 5
@anchor{whatsnew/changelog id141}@anchor{1926}
@subsubsection Library



@itemize -

@item 
gh-116600@footnote{https://github.com/python/cpython/issues/116600}: Fix @ref{1c1,,repr()} for global @ref{82e,,Flag} members.

@item 
gh-116349@footnote{https://github.com/python/cpython/issues/116349}: @ref{32b,,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{10a,,typing}: implement 
@geindex Python Enhancement Proposals; PEP 705
PEP 705@footnote{https://peps.python.org/pep-0705/} which adds
@ref{485,,typing.ReadOnly} support to @ref{331,,typing.TypedDict}.

@item 
gh-116325@footnote{https://github.com/python/cpython/issues/116325}: @ref{10a,,typing}: raise @ref{18e,,SyntaxError} instead of
@ref{5e8,,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{ba,,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{11b,,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{189a,,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{1c2,,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{1927,,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{f4,,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{110,,urllib.parse} functions @ref{31e,,parse_qs()} and
@ref{31d,,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{6a8,,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{2d,,csv}. @ref{6a8,,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{ad9,,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{4ae,,property} methods @ref{1928,,getter()},
@ref{1929,,setter()} and @ref{192a,,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{1157,,inspect.unwrap()} for types with the @code{__wrapper__}
data descriptor. Fix @ref{93a,,inspect.Signature.from_callable()} for builtins
@ref{489,,classmethod()} and @ref{451,,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{93a,,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{ba,,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{ea6,,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{2eb,,ValueError}
exception when passed an empty iterable. Previously, @ref{1729,,IndexError} was
raised.

@code{posixpath.commonpath()} now raises a @ref{198,,TypeError} exception when
passed @code{None}. Previously, @ref{2eb,,ValueError} was raised.

@item 
gh-114610@footnote{https://github.com/python/cpython/issues/114610}: Fix bug where @ref{192b,,pathlib.PurePath.with_stem()} converted a
non-empty path suffix to a stem when given an empty `stem' argument. It
now raises @ref{2eb,,ValueError}, just like
@ref{18bd,,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{47b,,ssl.VERIFY_X509_PARTIAL_CHAIN} and
@code{VERIFY_X509_STRICT} to the default SSL context created with
@ref{47a,,ssl.create_default_context()}.

@item 
gh-112281@footnote{https://github.com/python/cpython/issues/112281}: Allow creating @ref{9be,,union of types} for
@ref{b2e,,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{722,,configparser.ParsingError} from
@ref{165d,,read()} and
@ref{723,,read_file()} methods of
@ref{4d9,,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{149e,,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{113b,,filecmp.dircmp} like @ref{192c,,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{192d,,module} name in the @ref{1c1,,repr()} of
@ref{217,,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{115c,,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{192e,,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{bda,,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{11c3,,sys.__interactivehook__} on
startup. The default implementation of @ref{11c3,,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<13>,Tests<14>,Library<19>,Python 3 13 0 alpha 5
@anchor{whatsnew/changelog id142}@anchor{192f}
@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{116,,uuid} on Linux.
@end itemize

@node Tests<14>,Build<17>,Documentation<13>,Python 3 13 0 alpha 5
@anchor{whatsnew/changelog id143}@anchor{1930}
@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<17>,Windows<15>,Tests<14>,Python 3 13 0 alpha 5
@anchor{whatsnew/changelog id144}@anchor{1931}
@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{291,,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<15>,macOS<9>,Build<17>,Python 3 13 0 alpha 5
@anchor{whatsnew/changelog id145}@anchor{1932}
@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{7d3,,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{7d3,,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<9>,IDLE<8>,Windows<15>,Python 3 13 0 alpha 5
@anchor{whatsnew/changelog id146}@anchor{1933}
@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<8>,Tools/Demos<15>,macOS<9>,Python 3 13 0 alpha 5
@anchor{whatsnew/changelog id147}@anchor{1934}
@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<15>,C API<17>,IDLE<8>,Python 3 13 0 alpha 5
@anchor{whatsnew/changelog id148}@anchor{1935}
@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<17>,,Tools/Demos<15>,Python 3 13 0 alpha 5
@anchor{whatsnew/changelog id149}@anchor{1936}
@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{1937,,PyHASH_MODULUS}, @ref{1938,,PyHASH_BITS},
@ref{1939,,PyHASH_INF} and @ref{193a,,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{193b}
@subsection Python 3.13.0 alpha 4


`Release date: 2024-02-15'

@menu
* Security: Security<17>. 
* Core and Builtins: Core and Builtins<19>. 
* Library: Library<20>. 
* Documentation: Documentation<14>. 
* Tests: Tests<15>. 
* Build: Build<18>. 
* Windows: Windows<16>. 
* macOS: macOS<10>. 
* IDLE: IDLE<9>. 
* Tools/Demos: Tools/Demos<16>. 
* C API: C API<18>. 

@end menu

@node Security<17>,Core and Builtins<19>,,Python 3 13 0 alpha 4
@anchor{whatsnew/changelog id150}@anchor{193c}
@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{fcb,,collections.deque.index()} when
the deque is concurrently modified.
@end itemize

@node Core and Builtins<19>,Library<20>,Security<17>,Python 3 13 0 alpha 4
@anchor{whatsnew/changelog id151}@anchor{193d}
@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{a5e,,reversed()}. Patch by Donghee Na

@item 
gh-114570@footnote{https://github.com/python/cpython/issues/114570}: Add @ref{473,,PythonFinalizationError} exception. This exception
derived from @ref{244,,RuntimeError} is raised when an operation is blocked
during the @ref{474,,Python finalization}. Patch by
Victor Stinner.

@item 
gh-114695@footnote{https://github.com/python/cpython/issues/114695}: Add @ref{362,,sys._clear_internal_caches()}, which clears all
internal performance-related caches (and deprecate the less-general
@ref{292,,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{1a6,,super()} inside a comprehension in a class body.

@item 
gh-112069@footnote{https://github.com/python/cpython/issues/112069}: Adapt @ref{184,,set} and @ref{7eb,,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{19e,,__index__()} method as for @ref{19b,,int}.

@item 
gh-114887@footnote{https://github.com/python/cpython/issues/114887}: Changed socket type validation in
@ref{934,,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{193e,,chr()} builtin function now always raises
@ref{2eb,,ValueError} for values outside the valid range. Previously it raised
@ref{a78,,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{4d2,,RuntimeWarning} emitted when assign an integer-like
value that is not an instance of @ref{19b,,int} to an attribute that
corresponds to a C struct member of @ref{193f,,type} T_UINT
and T_ULONG. Fix a double @ref{4d2,,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{d59,,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{7ed,,collections.deque} to use Argument Clinic.

@item 
gh-112050@footnote{https://github.com/python/cpython/issues/112050}: Make methods on @ref{7ed,,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{f3f,,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<20>,Documentation<14>,Core and Builtins<19>,Python 3 13 0 alpha 4
@anchor{whatsnew/changelog id152}@anchor{1940}
@subsubsection Library



@itemize -

@item 
gh-115392@footnote{https://github.com/python/cpython/issues/115392}: Fix a bug in @ref{3e,,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{199,,format()} bugs when using the C implementation
of @ref{1fe,,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{213,,fractions.Fraction} and
@ref{197,,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{10a,,typing} generic aliases (including generic aliases created using
@ref{b2e,,typing.Annotated}). Previously only @ref{5e8,,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{11ee,,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{59a,,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{e4,,tarfile} and @ref{137,,zipfile}.

@item 
gh-115060@footnote{https://github.com/python/cpython/issues/115060}: Speed up @ref{532,,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{e7,,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{e4,,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{4bb,,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{1fa,,date}-@ref{4dd,,datetime}
comparison. Now the special comparison methods like @code{__eq__} and
@code{__lt__} return @ref{1a2,,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{198,,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{1fe,,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{532,,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{7e,,importlib.metadata} and
@ref{54,,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{ade,,ssl.SSLSocket} creation.

@item 
gh-77749@footnote{https://github.com/python/cpython/issues/77749}: @ref{1941,,email.policy.EmailPolicy.fold()} now always encodes
non-ASCII characters in headers if @ref{ff4,,utf8}
is false.

@item 
gh-83383@footnote{https://github.com/python/cpython/issues/83383}: Synchronization of the @ref{36,,dbm.dumb} database is now no-op if
there was no modification since opening or last synchronization. The
directory file for a newly created empty @ref{36,,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{54a,,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{12c0,,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{574,,xml.etree.ElementTree.iterparse()}.

@item 
gh-109653@footnote{https://github.com/python/cpython/issues/109653}: Reduce the import time of @ref{f3,,threading} module by ~50%.
Patch by Daniel Hollas.

@item 
gh-114492@footnote{https://github.com/python/cpython/issues/114492}: Make the result of @ref{1942,,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{1943,,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{39,,dbm.sqlite3} as a backend to @ref{35,,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{2c0,,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{f40,,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{5d,,fcntl}
module on Linux, macOS, FreeBSD and NetBSD.

@item 
gh-114328@footnote{https://github.com/python/cpython/issues/114328}: The @ref{1944,,tty.setcbreak()} and new @ref{1945,,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{33,,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{2c0,,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{59b,,path-like objects} as patterns
in @ref{532,,pathlib.Path.glob()} and @ref{533,,rglob()}.

@item 
gh-112202@footnote{https://github.com/python/cpython/issues/112202}: Ensure that a @ref{1946,,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{ba,,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{17aa,,csv.Dialect}
constructor. @ref{2eb,,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{6a5,,QUOTE_NOTNULL} and
@ref{6a6,,QUOTE_STRINGS} in @ref{6a7,,csv.reader()}.

@item 
gh-113225@footnote{https://github.com/python/cpython/issues/113225}: Speed up @ref{6c8,,pathlib.Path.walk()} by using
@ref{1947,,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{16bf,,datetime.datetime.replace()},
@ref{1948,,datetime.date.replace()} and @ref{1949,,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{f6,,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{103,,trace}. Instead of checking if a
directory exists and creating it, directly call @ref{527,,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{194a,,mailbox.mbox} and
@ref{194b,,mailbox.MMDF}.

@item 
gh-106233@footnote{https://github.com/python/cpython/issues/106233}: Fix stacklevel in @code{InvalidTZPathWarning} during
@ref{13a,,zoneinfo} module import.

@item 
gh-105102@footnote{https://github.com/python/cpython/issues/105102}: Allow @ref{1e6,,ctypes.Union} to be nested in
@ref{1e5,,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{158c,,queue.Queue} termination with
@ref{53d,,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{194c,,os.posix_openpt()},
@ref{194d,,os.grantpt()}, @ref{194e,,os.unlockpt()}, and @ref{194f,,os.ptsname()}.

@item 
gh-102512@footnote{https://github.com/python/cpython/issues/102512}: When @ref{4b0,,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{32a,,os.path.isreserved()}, which identifies reserved
pathnames such as "NUL", "AUX" and "CON". This function is only available
on Windows.

Deprecate @ref{329,,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<14>,Tests<15>,Library<20>,Python 3 13 0 alpha 4
@anchor{whatsnew/changelog id153}@anchor{1950}
@subsubsection Documentation



@itemize -

@item 
gh-115233@footnote{https://github.com/python/cpython/issues/115233}: Fix an example for @ref{14f6,,LoggerAdapter} in the
Logging Cookbook.

@item 
gh-114123@footnote{https://github.com/python/cpython/issues/114123}: Move the @ref{2d,,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<15>,Build<18>,Documentation<14>,Python 3 13 0 alpha 4
@anchor{whatsnew/changelog id154}@anchor{1951}
@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<18>,Windows<16>,Tests<15>,Python 3 13 0 alpha 4
@anchor{whatsnew/changelog id155}@anchor{1952}
@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{6a,,grp} module.
@end itemize

@node Windows<16>,macOS<10>,Build<18>,Python 3 13 0 alpha 4
@anchor{whatsnew/changelog id156}@anchor{1953}
@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<10>,IDLE<9>,Windows<16>,Python 3 13 0 alpha 4
@anchor{whatsnew/changelog id157}@anchor{1954}
@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{1955,,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<9>,Tools/Demos<16>,macOS<10>,Python 3 13 0 alpha 4
@anchor{whatsnew/changelog id158}@anchor{1956}
@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<16>,C API<18>,IDLE<9>,Python 3 13 0 alpha 4
@anchor{whatsnew/changelog id159}@anchor{1957}
@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{1958,,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<18>,,Tools/Demos<16>,Python 3 13 0 alpha 4
@anchor{whatsnew/changelog id160}@anchor{1959}
@subsubsection C API



@itemize -

@item 
gh-111140@footnote{https://github.com/python/cpython/issues/111140}: Adds @ref{5fe,,PyLong_AsNativeBytes()},
@ref{5ff,,PyLong_FromNativeBytes()} and
@ref{600,,PyLong_FromUnsignedNativeBytes()} functions.

@item 
gh-114685@footnote{https://github.com/python/cpython/issues/114685}: @ref{95c,,PyBuffer_FillInfo()} now raises a @ref{78e,,SystemError} if
called with @ref{195a,,PyBUF_READ} or @ref{195b,,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{632,,PyObject_GetBuffer()} now raises a @ref{78e,,SystemError} if
called with @ref{195a,,PyBUF_READ} or @ref{195b,,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{5f6,,PyList_GetItemRef()}, which is similar to
@ref{5f7,,PyList_GetItem()} but returns a @ref{5da,,strong reference} instead of
a @ref{3d5,,borrowed reference}.

@item 
gh-110850@footnote{https://github.com/python/cpython/issues/110850}: Add PyTime C API:


@itemize *

@item 
@ref{5cb,,PyTime_t} type.

@item 
@ref{5cc,,PyTime_MIN} and @ref{5cd,,PyTime_MAX} constants.

@item 
@ref{5ce,,PyTime_AsSecondsDouble()},
@ref{5cf,,PyTime_Monotonic()}, @ref{5d1,,PyTime_PerfCounter()}, and
@ref{5d3,,PyTime_Time()} functions.
@end itemize

Patch by Victor Stinner.

@item 
gh-112066@footnote{https://github.com/python/cpython/issues/112066}: Add @ref{5db,,PyDict_SetDefaultRef()}: insert a key and value into
a dictionary if the key is not already present. This is similar to
@ref{1274,,dict.setdefault()}, but returns an integer value indicating if the
key was already present. It is also similar to
@ref{5dc,,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{195c}
@subsection Python 3.13.0 alpha 3


`Release date: 2024-01-17'

@menu
* Security: Security<18>. 
* Core and Builtins: Core and Builtins<20>. 
* Library: Library<21>. 
* Documentation: Documentation<15>. 
* Tests: Tests<16>. 
* Build: Build<19>. 
* Windows: Windows<17>. 
* macOS: macOS<11>. 
* IDLE: IDLE<10>. 
* C API: C API<19>. 

@end menu

@node Security<18>,Core and Builtins<20>,,Python 3 13 0 alpha 3
@anchor{whatsnew/changelog id161}@anchor{195d}
@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<20>,Library<21>,Security<18>,Python 3 13 0 alpha 3
@anchor{whatsnew/changelog id162}@anchor{195e}
@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{1a6,,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{1c2,,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{1106,,min()} and @ref{1107,,max()}.

@item 
gh-112943@footnote{https://github.com/python/cpython/issues/112943}: Correctly compute end column offsets for multiline tokens in
the @ref{101,,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{14d9,,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{195f,,zlib.crc32()} and @ref{1960,,binascii.crc32()} could produce incorrect
results on multi-gigabyte inputs. Including when using @ref{137,,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{1015,,getcoroutinestate()} and @ref{1437,,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{1961,,PyComplex_RealAsDouble()}/@ref{1962,,PyComplex_ImagAsDouble()} now
tries to convert an object to a @ref{197,,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{553,,sys._is_interned()}.
@end itemize

@node Library<21>,Documentation<15>,Core and Builtins<20>,Python 3 13 0 alpha 3
@anchor{whatsnew/changelog id163}@anchor{1963}
@subsubsection Library



@itemize -

@item 
gh-114077@footnote{https://github.com/python/cpython/issues/114077}: Fix possible @ref{a78,,OverflowError} in
@ref{1058,,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{213,,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{54a,,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{2cb,,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{f6,,tkinter} method @code{winfo_pathname()} on 64-bit
Windows.

@item 
gh-113868@footnote{https://github.com/python/cpython/issues/113868}: Added @ref{1964,,mmap.MAP_NORESERVE}, @ref{1965,,mmap.MAP_NOEXTEND},
@ref{1966,,mmap.MAP_HASSEMAPHORE}, @ref{1967,,mmap.MAP_NOCACHE},
@ref{1968,,mmap.MAP_JIT}, @ref{1969,,mmap.MAP_RESILIENT_CODESIGN},
@ref{196a,,mmap.MAP_RESILIENT_MEDIA}, @ref{196b,,mmap.MAP_32BIT},
@ref{196c,,mmap.MAP_TRANSLATED_ALLOW_EXECUTE}, @ref{196d,,mmap.MAP_UNIX03} and
@ref{196e,,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{4cc,,asyncio.TaskGroup()} and @ref{80d,,asyncio.timeout()} context
managers now handle @ref{4cf,,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{a2f,,TimeoutError} in the context of the exception that
was raised during exiting an expired @ref{80d,,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{196f,,asyncio.Condition.wait()} now re-raises the same
@code{CancelledError} instance that may have caused it to be interrupted.
Fixed race condition in @ref{1970,,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{f4,,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{137,,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{6c6,,pathlib.PurePath} and
not its private base class @code{PurePathBase}.

@item 
gh-113594@footnote{https://github.com/python/cpython/issues/113594}: Fix @ref{880,,UnicodeEncodeError} in @ref{3f,,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{91,,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{b40,,plistlib.loads()}.

@item 
gh-89850@footnote{https://github.com/python/cpython/issues/89850}: Add default implementations of
@ref{1877,,pickle.Pickler.persistent_id()} and
@ref{187f,,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{c0a,,pickle.Pickler} and
@ref{1971,,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{1972,,assert_has_calls()} failure.

@item 
gh-101225@footnote{https://github.com/python/cpython/issues/101225}: Increase the backlog for
@ref{1973,,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{12e1,,multiprocessing.connection.Connection} to them.

@item 
gh-113568@footnote{https://github.com/python/cpython/issues/113568}: Raise audit events from @ref{266,,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{10d,,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{565,,Protocol}
classes that were not marked as @ref{66d,,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{df0,,StopIteration} into @ref{244,,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{532,,pathlib.Path.glob()} by using
@ref{1947,,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{dc,,subprocess} module can now use the
@ref{529,,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{525,,os.fchmod()} and a file descriptor in
@ref{524,,os.chmod()} on Windows.

@item 
gh-113188@footnote{https://github.com/python/cpython/issues/113188}: Fix @ref{1974,,shutil.copymode()} and @ref{132f,,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{529,,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{523,,os.lchmod()} and the `follow_symlinks'
argument in @ref{524,,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{1335,,signal.signal()} and @ref{1975,,signal.getsignal()} no longer
call @code{repr} on callable handlers. @ref{2f2,,asyncio.run()} and
@ref{18b4,,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{3c,,dis} module functions add cache information to the
@ref{203,,Instruction} instance rather than creating fake
@ref{203,,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{e2,,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{e7,,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{1435,,tempfile.TemporaryDirectory()} cleanup on Windows.

@item 
gh-94692@footnote{https://github.com/python/cpython/issues/94692}: @ref{354,,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{1976,,pathlib.Path.absolute()}. Patch by Barney Gale.

@item 
gh-74690@footnote{https://github.com/python/cpython/issues/74690}: Speedup @ref{9bd,,issubclass()} checks against simple
@ref{66d,,runtime-checkable protocols} by around
6%. Patch by Alex Waygood.

@item 
gh-74690@footnote{https://github.com/python/cpython/issues/74690}: Speedup @ref{2ad,,isinstance()} checks by roughly 20% for
@ref{66d,,runtime-checkable protocols} that only
have one callable member. Speedup @ref{9bd,,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{354,,shutil.rmtree()}.

@item 
gh-112640@footnote{https://github.com/python/cpython/issues/112640}: Add @code{kwdefaults} parameter to @ref{a7a,,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{1c9,,asyncio.create_task()}.

@item 
gh-112618@footnote{https://github.com/python/cpython/issues/112618}: Fix a caching bug relating to @ref{b2e,,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{dc,,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{4b2,,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{c1b,,socket.if_indextoname()} with specific value
(UINT_MAX). Fix an integer overflow in @ref{c1b,,socket.if_indextoname()} on
64-bit non-Windows platforms.

@item 
gh-112578@footnote{https://github.com/python/cpython/issues/112578}: Fix a spurious @ref{4d2,,RuntimeWarning} when executing the
@ref{137,,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{1977,,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{331,,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{d5,,ssl} module.

@item 
gh-112414@footnote{https://github.com/python/cpython/issues/112414}: Fix regression in Python 3.12 where calling @ref{1c1,,repr()} on a
module that had been imported using a custom @ref{1978,,loader} could fail
with @ref{5e8,,AttributeError}. Patch by Alex Waygood.

@item 
gh-112358@footnote{https://github.com/python/cpython/issues/112358}: Revert change to @ref{1979,,struct.Struct} initialization that
broke some cases of subclassing.

@item 
gh-112405@footnote{https://github.com/python/cpython/issues/112405}: Optimize @ref{2fc,,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{197a,,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{9bd,,issubclass()}
against a @ref{565,,typing.Protocol} that has non-method members. Patch by
Randolf Scholz.

@item 
gh-112137@footnote{https://github.com/python/cpython/issues/112137}: Change @ref{3c,,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{55d,,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{6d0,,random.binomialvariate()}

@item 
gh-112292@footnote{https://github.com/python/cpython/issues/112292}: Fix a crash in @ref{bf,,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{3c,,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{ba,,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{197b,,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{330,,typing.NamedTuple} class, ensure
@ref{e43,,__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{559,,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{f6,,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{213,,fractions.Fraction}.

@item 
gh-111049@footnote{https://github.com/python/cpython/issues/111049}: Fix crash during garbage collection of the @ref{109f,,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{4ee,,email.utils.getaddresses()} and
@ref{4ef,,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{197c,,cmd.Cmd.do_help()} now cleans docstrings with
@ref{197d,,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{1927,,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{6c6,,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{137,,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{a0f,,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{536,,pathlib.Path.owner()} and @ref{537,,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{49f,,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{484,,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{197e,,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{1435,,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{652,,getpass.getuser()} now raises @ref{2c0,,OSError} for all
failures rather than @ref{653,,ImportError} on systems lacking the @ref{b7,,pwd}
module or @ref{5df,,KeyError} if the password database is empty.

@item 
bpo-34321@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34321}: @ref{514,,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{354,,shutil.rmtree()} function now ignores errors when
calling @ref{d63,,os.close()} when `ignore_errors' is @code{True}, and
@ref{d63,,os.close()} no longer retried after error.

@item 
bpo-35928@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35928}: @ref{9b7,,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{c48,,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{c0a,,pickle.Pickler} and
@ref{1971,,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{169d,,warnings.filterwarnings()} and
@ref{8c8,,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{354,,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{4ab,,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{656,,mailbox.Maildir} now ignores files with a leading dot.
@end itemize

@node Documentation<15>,Tests<16>,Library<21>,Python 3 13 0 alpha 3
@anchor{whatsnew/changelog id164}@anchor{197f}
@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<16>,Build<19>,Documentation<15>,Python 3 13 0 alpha 3
@anchor{whatsnew/changelog id165}@anchor{1980}
@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{52c,,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{6d3,,shutil.make_archive}.

@item 
gh-112769@footnote{https://github.com/python/cpython/issues/112769}: The tests now correctly compare zlib version when
@ref{136f,,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{dc,,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<19>,Windows<17>,Tests<16>,Python 3 13 0 alpha 3
@anchor{whatsnew/changelog id166}@anchor{1981}
@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{18c5,,os.major()}, @ref{18c7,,os.makedev()}, and @ref{18c6,,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<17>,macOS<11>,Build<19>,Python 3 13 0 alpha 3
@anchor{whatsnew/changelog id167}@anchor{1982}
@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{26d,,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{33d,,sys._enablelegacywindowsfsencoding()}. Use
@geindex PYTHONLEGACYWINDOWSFSENCODING
@geindex 環境變數; PYTHONLEGACYWINDOWSFSENCODING
@ref{33e,,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{514,,mmap.mmap} when using a non-ASCII
`tagname' argument on Windows.
@end itemize

@node macOS<11>,IDLE<10>,Windows<17>,Python 3 13 0 alpha 3
@anchor{whatsnew/changelog id168}@anchor{1983}
@subsubsection macOS



@itemize -

@item 
gh-113666@footnote{https://github.com/python/cpython/issues/113666}: Add the following constants to module @ref{d6,,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{f94,,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{38,,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<10>,C API<19>,macOS<11>,Python 3 13 0 alpha 3
@anchor{whatsnew/changelog id169}@anchor{1984}
@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<19>,,IDLE<10>,Python 3 13 0 alpha 3
@anchor{whatsnew/changelog id170}@anchor{1985}
@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{3bf,,PyArg_ParseTuple()}-like functions.

@item 
gh-111545@footnote{https://github.com/python/cpython/issues/111545}: Add @ref{423,,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{61c,,PyArg_ParseTupleAndKeywords()} and
@ref{61d,,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{1986}
@subsection Python 3.13.0 alpha 2


`Release date: 2023-11-22'

@menu
* Core and Builtins: Core and Builtins<21>. 
* Library: Library<22>. 
* Tests: Tests<17>. 
* Build: Build<20>. 
* Windows: Windows<18>. 
* macOS: macOS<12>. 
* IDLE: IDLE<11>. 
* Tools/Demos: Tools/Demos<17>. 
* C API: C API<20>. 

@end menu

@node Core and Builtins<21>,Library<22>,,Python 3 13 0 alpha 2
@anchor{whatsnew/changelog id171}@anchor{1987}
@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{776,,__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{57f,,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{1988,,BaseExceptionGroup.derive()},
@ref{1989,,BaseExceptionGroup.subgroup()}, and @ref{1847,,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{5b2,,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{18e,,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{1ae,,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{4a8,,PYTHON_FROZEN_MODULES}. It determines whether or not frozen
modules are ignored by the import machinery, equivalent of the @ref{16f,,-X frozen_modules} command-line option.

@item 
gh-111354@footnote{https://github.com/python/cpython/issues/111354}: Remove @code{oparg} from @ref{5b2,,YIELD_VALUE}. Change @code{oparg}
of @ref{5b3,,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{4a7,,global} declaration in an
@ref{1ab,,except} block is rejected when the global is used in the
@ref{17c,,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{181e,,MemoryError}
exceptions using the @ref{104,,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{181e,,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{504,,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{489,,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{4ae,,property}.  The core design of this feature was flawed and
caused a number of downstream problems.  To "pass-through" a
@ref{489,,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<22>,Tests<17>,Core and Builtins<21>,Python 3 13 0 alpha 2
@anchor{whatsnew/changelog id172}@anchor{198a}
@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{d1,,socket} module when
present in C at build time for use with @ref{198b,,socket.getnameinfo()}.

@item 
gh-109538@footnote{https://github.com/python/cpython/issues/109538}: Issue warning message instead of having @ref{244,,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{d38,,io.TextIOWrapper.reconfigure()} when pass
invalid arguments, e.g. non-string encoding.

@item 
gh-111460@footnote{https://github.com/python/cpython/issues/111460}: @ref{2f,,curses}: restore wide character support (including
@ref{1299,,curses.unget_wch()} and @ref{1298,,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{1123,,contextlib.suppress} now supports suppressing
exceptions raised as part of a @ref{560,,BaseExceptionGroup}, in addition to
the recent support for @ref{4cd,,ExceptionGroup}.

@item 
gh-111835@footnote{https://github.com/python/cpython/issues/111835}: The @ref{514,,mmap.mmap} class now has an
@ref{515,,seekable()} method that can be used when a seekable
file-like object is required. The @ref{516,,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{25b,,os.putenv()} and @ref{25c,,os.unsetenv()} on Windows.

@item 
gh-111768@footnote{https://github.com/python/cpython/issues/111768}: @ref{198c,,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{17cc,,cmd.Cmd} in an
except block

@item 
gh-111541@footnote{https://github.com/python/cpython/issues/111541}: Fix @ref{3e,,doctest} for @ref{18e,,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{f4,,time}: Make @ref{135f,,time.clock_gettime()} and
@ref{cd2,,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{d07,,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{f6,,tkinter} widgets.

@item 
gh-111246@footnote{https://github.com/python/cpython/issues/111246}: @ref{4c5,,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{198d,,io.text_encoding()}, @ref{198e,,io.DEFAULT_BUFFER_SIZE},
and @ref{198f,,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{2fc,,pathlib.PurePath.relative_to()} and
@ref{2fd,,is_relative_to()}.

@item 
gh-111342@footnote{https://github.com/python/cpython/issues/111342}: Fixed typo in @ref{6b8,,math.sumprod()}.

@item 
gh-68166@footnote{https://github.com/python/cpython/issues/68166}: Remove mention of not supported "vsapi" element type in
@ref{559,,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{a47,,traceback.format_exception_only()}, which allows to format
@ref{4cd,,ExceptionGroup} instances.

@item 
gh-79033@footnote{https://github.com/python/cpython/issues/79033}: Another attempt at fixing @ref{1990,,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{f4,,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{c6,,select} not checking for errors when initializing.

@item 
gh-111230@footnote{https://github.com/python/cpython/issues/111230}: Fix @ref{d5,,ssl} not checking for errors when initializing.

@item 
gh-111174@footnote{https://github.com/python/cpython/issues/111174}: Fix crash in @ref{13f2,,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{3e,,doctest} output comparison for exceptions with notes.

@item 
gh-110910@footnote{https://github.com/python/cpython/issues/110910}: Fix invalid state handling in @ref{4cc,,asyncio.TaskGroup} and
@ref{1991,,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{1040,,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{18e,,SyntaxError}

@item 
gh-80675@footnote{https://github.com/python/cpython/issues/80675}: Set @code{f_trace_lines = True} on all frames upon
@ref{272,,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{2f4,,asyncio.Runner} loop_factory kwarg
in @ref{35f,,unittest.IsolatedAsyncioTestCase}

@item 
gh-110392@footnote{https://github.com/python/cpython/issues/110392}: Fix @ref{1992,,tty.setraw()} and @ref{1944,,tty.setcbreak()}: previously
they returned partially modified list of the original tty attributes.
@ref{1993,,tty.cfmakeraw()} and @ref{1945,,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{67,,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{1994,,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{506,,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{de,,symtable} module and improve the
repr of @ref{289,,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{8b8,,Generic Alias Types} for @code{[]} use in typing contexts.

@item 
gh-72904@footnote{https://github.com/python/cpython/issues/72904}: Add @ref{4f6,,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{1995,,mailbox.Maildir.get_info()},
@ref{1996,,mailbox.Maildir.set_info()}, @ref{1997,,mailbox.Maildir.get_flags()},
@ref{1998,,mailbox.Maildir.set_flags()}, @ref{1999,,mailbox.Maildir.add_flag()},
@ref{199a,,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{1809,,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{73,,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<17>,Build<20>,Library<22>,Python 3 13 0 alpha 2
@anchor{whatsnew/changelog id173}@anchor{199b}
@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{ea,,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{cc,,site}.
@end itemize

@node Build<20>,Windows<18>,Tests<17>,Python 3 13 0 alpha 2
@anchor{whatsnew/changelog id174}@anchor{199c}
@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{62f,,limited C API}. Patch by Victor
Stinner.
@end itemize

@node Windows<18>,macOS<12>,Build<20>,Python 3 13 0 alpha 2
@anchor{whatsnew/changelog id175}@anchor{199d}
@subsubsection Windows



@itemize -

@item 
gh-111856@footnote{https://github.com/python/cpython/issues/111856}: Fixes @ref{f87,,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{199e,,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<12>,IDLE<11>,Windows<18>,Python 3 13 0 alpha 2
@anchor{whatsnew/changelog id176}@anchor{199f}
@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{1903,,tkinter.Tk()} instance
is destroyed.
@end itemize

@node IDLE<11>,Tools/Demos<17>,macOS<12>,Python 3 13 0 alpha 2
@anchor{whatsnew/changelog id177}@anchor{19a0}
@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<17>,C API<20>,IDLE<11>,Python 3 13 0 alpha 2
@anchor{whatsnew/changelog id178}@anchor{19a1}
@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<20>,,Tools/Demos<17>,Python 3 13 0 alpha 2
@anchor{whatsnew/changelog id179}@anchor{19a2}
@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{421,,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{420,,PyDict_Pop()} and @ref{5dd,,PyDict_PopString()}
functions: remove a key from a dictionary and optionally return the
removed value. This is similar to @ref{5de,,dict.pop()}, but without the
default value and not raising @ref{5df,,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{5f8,,PyList_Extend()} and @ref{5f9,,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{a9f,,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{5e9,,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{61c,,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{60b,,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{629,,PyMem_RawMalloc()}, @ref{62a,,PyMem_RawCalloc()},
@ref{62b,,PyMem_RawRealloc()} and @ref{62c,,PyMem_RawFree()} to the limited C
API. Patch by Victor Stinner.

@item 
gh-106672@footnote{https://github.com/python/cpython/issues/106672}: Functions @ref{620,,PyDict_GetItem()},
@ref{621,,PyDict_GetItemString()}, @ref{618,,PyMapping_HasKey()},
@ref{61a,,PyMapping_HasKeyString()}, @ref{614,,PyObject_HasAttr()},
@ref{616,,PyObject_HasAttrString()}, and @ref{622,,PySys_GetObject()}, which
clear all errors occurred during calling the function, report now them
using @ref{502,,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{d5,,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{19a3}
@subsection Python 3.13.0 alpha 1


`Release date: 2023-10-13'

@menu
* Security: Security<19>. 
* Core and Builtins: Core and Builtins<22>. 
* Library: Library<23>. 
* Documentation: Documentation<16>. 
* Tests: Tests<18>. 
* Build: Build<21>. 
* Windows: Windows<19>. 
* macOS: macOS<13>. 
* IDLE: IDLE<12>. 
* Tools/Demos: Tools/Demos<18>. 
* C API: C API<21>. 

@end menu

@node Security<19>,Core and Builtins<22>,,Python 3 13 0 alpha 1
@anchor{whatsnew/changelog id180}@anchor{19a4}
@subsubsection Security



@itemize -

@item 
gh-108310@footnote{https://github.com/python/cpython/issues/108310}: Fixed an issue where instances of @ref{ade,,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{54,,email.utils} security improvement change
released in 3.12beta4 that unintentionally caused
@ref{4ee,,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{6c,,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{39c,,PyLongObject} objects. Patch by Illia Volochii.
@end itemize

@node Core and Builtins<22>,Library<23>,Security<19>,Python 3 13 0 alpha 1
@anchor{whatsnew/changelog id181}@anchor{19a5}
@subsubsection Core and Builtins



@itemize -

@item 
gh-110782@footnote{https://github.com/python/cpython/issues/110782}: Fix crash when @ref{481,,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{104,,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{184,,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{16f,,-X uops} enabled.

@item 
gh-110514@footnote{https://github.com/python/cpython/issues/110514}: Add @code{PY_THROW} to @ref{16f2,,sys.setprofile()} events

@item 
gh-110489@footnote{https://github.com/python/cpython/issues/110489}: Optimise @ref{15b6,,math.ceil()} when the input is exactly a float,
resulting in about a 10% improvement.

@item 
gh-110455@footnote{https://github.com/python/cpython/issues/110455}: Guard @code{assert(tstate->thread_id > 0)} with @code{#ifndef
HAVE_PTHREAD_STUBS}. This allows for for pydebug builds to work under
WASI which (currently) lacks thread support.

@item 
gh-110309@footnote{https://github.com/python/cpython/issues/110309}: Remove unnecessary empty constant nodes in the ast of f-string
specs.

@item 
gh-110259@footnote{https://github.com/python/cpython/issues/110259}: Correctly identify the format spec in f-strings (with single or
triple quotes) that have multiple lines in the expression part and include
a formatting spec. Patch by Pablo Galindo

@item 
gh-110237@footnote{https://github.com/python/cpython/issues/110237}: Fix missing error checks for calls to @code{PyList_Append} in
@code{_PyEval_MatchClass}.

@item 
gh-110164@footnote{https://github.com/python/cpython/issues/110164}: regrtest: If the @code{SOURCE_DATE_EPOCH} environment variable is
defined, regrtest now disables tests randomization. Patch by Victor
Stinner.

@item 
gh-109889@footnote{https://github.com/python/cpython/issues/109889}: Fix the compiler's redundant NOP detection algorithm to skip
over NOPs with no line number when looking for the next instruction's
lineno.

@item 
gh-109853@footnote{https://github.com/python/cpython/issues/109853}: @code{sys.path[0]} is now set correctly for subinterpreters.

@item 
gh-109923@footnote{https://github.com/python/cpython/issues/109923}: Set line number on the @code{POP_TOP} that follows a
@code{RETURN_GENERATOR}.

@item 
gh-105716@footnote{https://github.com/python/cpython/issues/105716}: Subinterpreters now correctly handle the case where they have
threads running in the background.  Before, such threads would interfere
with cleaning up and destroying them, as well as prevent running another
script.

@item 
gh-109369@footnote{https://github.com/python/cpython/issues/109369}: The internal eval_breaker and supporting flags, plus the
monitoring version have been merged into a single atomic integer to speed
up checks.

@item 
gh-109823@footnote{https://github.com/python/cpython/issues/109823}: Fix bug where compiler does not adjust labels when removing an
empty basic block which is a jump target.

@item 
gh-109793@footnote{https://github.com/python/cpython/issues/109793}: The main thread no longer exits prematurely when a
subinterpreter is cleaned up during runtime finalization.  The bug was a
problem particularly because, when triggered, the Python process would
always return with a 0 exitcode, even if it failed.

@item 
gh-109719@footnote{https://github.com/python/cpython/issues/109719}: Fix missing jump target labels when compiler reorders cold/warm
blocks.

@item 
gh-109595@footnote{https://github.com/python/cpython/issues/109595}: Add @ref{16f,,-X cpu_count}  command line option to
override return results of @ref{4d6,,os.cpu_count()} and
@ref{4d5,,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{789,,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{19a6,,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{367,,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{18e,,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{370,,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{16f,,-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{912,,JUMP_BACKWARD} at the end
of a for loop.

@item 
gh-108113@footnote{https://github.com/python/cpython/issues/108113}: The @ref{4ac,,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{1c2,,ast.parse()} now accepts an optional argument @code{optimize} which is
passed on to the @ref{4ac,,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{16f,,-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{16c8,,METH_NOARGS} and
@ref{16fb,,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{19a7,,ctypes.pointer()} and
@ref{1f1,,ctypes.POINTER()}.

@item 
gh-105848@footnote{https://github.com/python/cpython/issues/105848}: Modify the bytecode so that the actual callable for a
@ref{90d,,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{169,,str} objects by @ref{19b,,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{19a8,,ctypes.c_char_p}, @ref{19a9,,ctypes.c_wchar_p} and
@ref{19aa,,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{16f,,-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{6a,,grp} and
@ref{d1,,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{38,,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{37,,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{1c2,,ast.parse()}.

@item 
gh-106917@footnote{https://github.com/python/cpython/issues/106917}: Fix classmethod-style @ref{1a6,,super()} method calls (i.e., where
the second argument to @ref{1a6,,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{16f,,-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{19ab,,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{4b3,,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{19ac,,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{19ad,,ast.JoinedStr} node for
it instead of an one-element @ref{19ad,,ast.JoinedStr} with an empty string
@ref{2ee,,ast.Constant}.

@item 
gh-100288@footnote{https://github.com/python/cpython/issues/100288}: Specialize @ref{6fd,,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{87e,,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{e4e,,sys.getfilesystemencoding()} and
@ref{edd,,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{19ae,,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{1847,,BaseExceptionGroup.split()} and
@ref{1989,,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{19af,,TO_BOOL} instruction, which performs boolean
conversions for @ref{19b0,,POP_JUMP_IF_TRUE}, @ref{19b1,,POP_JUMP_IF_FALSE},
and @ref{19b2,,UNARY_NOT} (which all expect exact @ref{3c1,,bool} values now).
Also, modify the oparg of @ref{b58,,COMPARE_OP} to include an optional
"boolean conversion" flag.

@item 
gh-98931@footnote{https://github.com/python/cpython/issues/98931}: Ensure custom @ref{18e,,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{1ae,,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{2eb,,ValueError} if the @code{delay} argument to
@ref{c5b,,asyncio.sleep()} is a NaN (matching @ref{8a4,,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{101,,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{19b3,,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{75d,,tokenize.TokenError} exceptions instead
of @ref{18e,,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{101,,tokenize} module. Patch by Pablo Galindo

@item 
gh-104635@footnote{https://github.com/python/cpython/issues/104635}: Eliminate redundant @ref{19b4,,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{101,,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{4ae,,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{5e8,,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{a07,,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{198,,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{1a6,,super()} calls on types with custom
@ref{19b5,,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{1759,,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{101,,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{101,,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{19b6,,__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{4b0,,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{f3,,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{101,,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{19b7,,generator.close()}.

@item 
gh-89091@footnote{https://github.com/python/cpython/issues/89091}: Raise @ref{4d2,,RuntimeWarning} for unawaited async generator
methods like @ref{acd,,asend()}, @ref{716,,athrow()} and
@ref{acc,,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{18d2,,__reduce_ex__()} or @ref{bbd,,__reduce__()} to
@code{None}, pickling will result in a @ref{198,,TypeError}.

@item 
gh-101006@footnote{https://github.com/python/cpython/issues/101006}: Improve error handling when read @ref{91,,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<23>,Documentation<16>,Core and Builtins<22>,Python 3 13 0 alpha 1
@anchor{whatsnew/changelog id182}@anchor{19b8}
@subsubsection Library



@itemize -

@item 
gh-110786@footnote{https://github.com/python/cpython/issues/110786}: @ref{e1,,sysconfig}'s CLI now ignores @ref{1257,,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{e1,,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{19b9,,asyncio.EventLoop} for use with the
@ref{2f2,,asyncio.run()} `loop_factory' kwarg to avoid calling the asyncio
policy system.

@item 
gh-110682@footnote{https://github.com/python/cpython/issues/110682}: @ref{66d,,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{19ba,,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{198,,TypeError} would
be overwritten by @ref{a78,,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{67,,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{1fe,,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{1403,,contextmanager()} and
@ref{d17,,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{19bb,,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{118,,warnings} within those modules.
Patch by Alex Waygood.

@item 
gh-110273@footnote{https://github.com/python/cpython/issues/110273}: @ref{19bc,,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{bd,,random}. Patch by Alex Waygood.

@item 
gh-110222@footnote{https://github.com/python/cpython/issues/110222}: Add support of struct sequence objects in @ref{1c0,,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{4d6,,os.cpu_count()} with
@ref{4d5,,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{f39,,PermissionError} and get the process exit code. If the process is
still running, raise again the @ref{f39,,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{de,,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{298,,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{be,,re} functions such as @ref{1225,,re.findall()},
@ref{59c,,re.split()}, @ref{142d,,re.search()} and @ref{59d,,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{54,,email.utils} by around 43%.
This results in the import time of @ref{48,,email.message} falling by around
18%, which in turn reduces the import time of @ref{7e,,importlib.metadata} by
around 6%. Patch by Alex Waygood.

@item 
gh-109818@footnote{https://github.com/python/cpython/issues/109818}: Fix @ref{13f4,,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{244,,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{bfc,,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{63,,functools} by around 13%. Patch by
Alex Waygood.

@item 
gh-109590@footnote{https://github.com/python/cpython/issues/109590}: @ref{6d4,,shutil.which()} will prefer files with an extension in
@code{PATHEXT} if the given mode includes @code{os.X_OK} on win32. If no
@code{PATHEXT} match is found, a file without an extension in @code{PATHEXT} can
be returned. This change will have @ref{6d4,,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{5a,,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{10a,,typing} by around a third.
Patch by Alex Waygood.

@item 
gh-109649@footnote{https://github.com/python/cpython/issues/109649}: Add @ref{4d5,,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{26d,,os.stat()} and @ref{19bd,,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{18c3,,ssl.SSLSocket.get_verified_chain()} and
@ref{18c4,,ssl.SSLSocket.get_unverified_chain()} methods.

Contributed by Mateusz Nowak.

@item 
gh-109559@footnote{https://github.com/python/cpython/issues/109559}: Update @ref{10b,,unicodedata} database to Unicode 15.1.0.

@item 
gh-109543@footnote{https://github.com/python/cpython/issues/109543}: Remove unnecessary @ref{6f2,,hasattr()} check during
@ref{331,,typing.TypedDict} creation.

@item 
gh-109495@footnote{https://github.com/python/cpython/issues/109495}: Remove unnecessary extra @code{__slots__} in
@ref{4dd,,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{8b,,logging}: Use a context manager for lock acquisition.

@item 
gh-109096@footnote{https://github.com/python/cpython/issues/109096}: @ref{324,,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{19be,,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{19bf,,pathlib.Path.resolve()} now treats symlink loops like
other errors: in strict mode, @ref{2c0,,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{4e0,,types.SimpleNamespace} in
@ref{1c0,,copy.replace()}.

@item 
gh-109164@footnote{https://github.com/python/cpython/issues/109164}: @ref{aa,,pdb}: Replace @ref{65,,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{66c,,sqlite3 command-line interface} (@code{python -m sqlite3}).

@item 
gh-108987@footnote{https://github.com/python/cpython/issues/108987}: Fix @ref{4af,,_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{ad9,,ast.unparse()} when unparsing f-strings
containing many quote types.

@item 
gh-108469@footnote{https://github.com/python/cpython/issues/108469}: @ref{ad9,,ast.unparse()} now supports new @ref{663,,f-string} syntax
introduced in Python 3.12. Note that the @ref{663,,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{1c0,,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{198,,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{548,,sqlite3.Connection} APIs:


@itemize *

@item 
@ref{5a3,,set_authorizer()}

@item 
@ref{5a4,,set_progress_handler()}

@item 
@ref{5a5,,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{481,,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{51a,,os.timerfd_create()}, @ref{51b,,os.timerfd_settime()},
@ref{51d,,os.timerfd_gettime()}, @ref{51c,,os.timerfd_settime_ns()}, and
@ref{51e,,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{e4,,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{54a,,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{8a4,,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{548,,sqlite3.Connection} APIs:


@itemize *

@item 
@ref{5a1,,create_function()}

@item 
@ref{5a2,,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{7ec,,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{548,,sqlite3.Connection} and
@ref{549,,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{d4,,sqlite3} now emits an @ref{547,,ResourceWarning} if a
@ref{548,,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{75c,,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{3e,,doctest} module. Patch by Tyler Smart.

@item 
gh-107963@footnote{https://github.com/python/cpython/issues/107963}: Fix @ref{1873,,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{151a,,os.path.normpath()} to handle embedded null
characters without truncating the path.

@item 
gh-81555@footnote{https://github.com/python/cpython/issues/81555}: @ref{128,,xml.dom.minidom} now only quotes @code{"} in attributes.

@item 
gh-50002@footnote{https://github.com/python/cpython/issues/50002}: @ref{128,,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{5a0,,sqlite3.connect()} and the @ref{548,,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{14f6,,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{2c0,,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{29a,,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{107,,turtle}.

@item 
gh-107782@footnote{https://github.com/python/cpython/issues/107782}: @ref{ba,,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{59c,,re.split()}, @ref{59d,,re.sub()} and
@ref{59e,,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{19c0,,logging.getHandlerNames()}.

@item 
gh-107715@footnote{https://github.com/python/cpython/issues/107715}: Fix @ref{19c1,,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{f6,,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{547,,ResourceWarning} when @ref{19c2,,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{52f,,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{6ee,,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{13f4,,reprlib.recursive_repr()}.

@item 
gh-107406@footnote{https://github.com/python/cpython/issues/107406}: Implement new @code{__repr__()} method for
@ref{1979,,struct.Struct}. Now it returns @code{Struct(<format repr>)}.

@item 
gh-107369@footnote{https://github.com/python/cpython/issues/107369}: Optimize @ref{577,,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{26e,,pathlib.Path.iterdir()} did not raise
@ref{2c0,,OSError} until iterated.

@item 
gh-105578@footnote{https://github.com/python/cpython/issues/105578}: Deprecate @ref{5a6,,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{bdf,,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{19c3,,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{cfd,,os.sendfile()} implementation.

@item 
gh-83006@footnote{https://github.com/python/cpython/issues/83006}: Document behavior of @ref{132e,,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{139e,,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{2eb,,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{3c,,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{1759,,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{e1,,sysconfig}.

@item 
gh-105726@footnote{https://github.com/python/cpython/issues/105726}: Added @code{__slots__} to
@ref{e85,,contextlib.AbstractContextManager} and
@ref{d18,,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{c7,,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{d5,,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{5a,,enum}

@item 
gh-106664@footnote{https://github.com/python/cpython/issues/106664}: @ref{c7,,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{117,,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{19c4,,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{c7,,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{be,,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{481,,typing.TypeVar},
@ref{482,,typing.ParamSpec}, @ref{9c2,,typing.ParamSpecArgs},
@ref{9c3,,typing.ParamSpecKwargs}, and @ref{483,,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{75c,,functools.cached_property()}. This better matches the
pre-3.12 behavior and improves compatibility for users subclassing
@ref{75c,,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{6cc,,pathlib.PurePath.match()}. This bug was introduced in Python 3.12.0
beta 1.

@item 
gh-106309@footnote{https://github.com/python/cpython/issues/106309}: Deprecate @ref{332,,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{653,,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{f3,,threading}, so that @code{_DummyThread} cannot be joined even with
@code{-OO}.

@item 
gh-106238@footnote{https://github.com/python/cpython/issues/106238}: Fix rare concurrency bug in lock acquisition by the logging
package.

@item 
gh-106152@footnote{https://github.com/python/cpython/issues/106152}: Added PY_THROW event hook for @ref{2b,,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{e48,,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{565,,typing.Protocol} class that had one or
more non-callable members would raise @ref{198,,TypeError} when
@ref{9bd,,issubclass()} was called against it, even if it defined a custom
@code{__subclasshook__} method. The behaviour in Python 3.11 and lower --
which has now been restored -- was not to raise @ref{198,,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{52e,,pathlib.UnsupportedOperation}, which is raised instead
of @ref{369,,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{112c,,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{ad9,,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{535,,pathlib.Path.is_dir()} and @ref{534,,is_file()}, defaulting
to @code{True}.

@item 
gh-105570@footnote{https://github.com/python/cpython/issues/105570}: Deprecate two methods of creating @ref{331,,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{2e,,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{bc7,,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{19c5,,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{df,,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{3a,,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{4b9,,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{13a,,zoneinfo} where exceptions could be
overwritten.

@item 
gh-105375@footnote{https://github.com/python/cpython/issues/105375}: Fix bugs in @ref{5b,,errno} where exceptions could be overwritten.

@item 
gh-105566@footnote{https://github.com/python/cpython/issues/105566}: Deprecate creating a @ref{330,,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{b2e,,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{10a,,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{651,,FutureWarning} from @ref{532,,pathlib.Path.glob()} and
@ref{533,,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{d4,,sqlite3} where an exception could be
overwritten in the @ref{87f,,collation}
callback.

@item 
gh-105382@footnote{https://github.com/python/cpython/issues/105382}: Remove `cafile', `capath' and `cadefault' parameters of the
@ref{306,,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{8b,,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{19c6,,logging.Logger.warning()} method,
@code{logging.LoggerAdapter.warning()} method and @ref{352,,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{a47,,traceback.format_exception_only()} to
recurse into the nested exception of a @ref{560,,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{565,,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{22f,,inspect.signature()}

@item 
gh-105144@footnote{https://github.com/python/cpython/issues/105144}: Fix a recent regression in the @ref{10a,,typing} module. The
regression meant that doing @code{class Foo(X, typing.Protocol)}, where @code{X}
was a class that had @ref{1116,,abc.ABCMeta} as its metaclass, would then
cause subsequent @code{isinstance(1, X)} calls to erroneously raise
@ref{198,,TypeError}. Patch by Alex Waygood.

@item 
gh-62948@footnote{https://github.com/python/cpython/issues/62948}: The @ref{500,,io.IOBase} finalizer now logs the @code{close()} method
errors with @ref{502,,sys.unraisablehook}. Previously, errors were ignored
silently by default, and only logged in @ref{503,,Python Development Mode} or on @ref{504,,Python built on debug mode}.  Patch
by Victor Stinner.

@item 
gh-105096@footnote{https://github.com/python/cpython/issues/105096}: @ref{119,,wave}: Deprecate the @code{getmark()}, @code{setmark()} and
@code{getmarkers()} methods of the @ref{333,,wave.Wave_read} and
@ref{334,,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{6c6,,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{19c7,,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{66d,,typing.runtime_checkable()} and @ref{174e,,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{16df,,__slots__} to @ref{e46,,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{331,,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{564,,typing.get_protocol_members()} to return the set of
members defining a @ref{565,,typing.Protocol}.  Add
@ref{566,,typing.is_protocol()} to check whether a class is a
@ref{565,,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{eec,,typing.NewType}. Patch by Jelle Zijlstra.

@item 
gh-104835@footnote{https://github.com/python/cpython/issues/104835}: Removed the following @ref{10c,,unittest} functions, deprecated in
Python 3.11:


@itemize *

@item 
@code{unittest.findTestCases()}

@item 
@code{unittest.makeSuite()}

@item 
@code{unittest.getTestCaseNames()}
@end itemize

Use @ref{58d,,TestLoader} methods instead:


@itemize *

@item 
@ref{58e,,unittest.TestLoader.loadTestsFromModule()}

@item 
@ref{58f,,unittest.TestLoader.loadTestsFromTestCase()}

@item 
@ref{590,,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{11b,,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{266,,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{19c8,,ast.ClassDef}, @ref{19c9,,ast.AsyncFunctionDef}, and
@ref{19ca,,ast.FunctionDef} to better preserve backward compatibility. Patch
by Jelle Zijlstra

@item 
gh-104797@footnote{https://github.com/python/cpython/issues/104797}: Allow @ref{565,,typing.Protocol} classes to inherit from
@ref{342,,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{dc,,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{6c,,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{532,,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{c4b,,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{203,,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{9e5,,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{532,,pathlib.Path.glob()} and
@ref{533,,rglob()}, defaulting to false.

@item 
gh-102541@footnote{https://github.com/python/cpython/issues/102541}: Hide traceback in @ref{acb,,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{32d,,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{6cc,,pathlib.PurePath.match()}.

@item 
gh-84867@footnote{https://github.com/python/cpython/issues/84867}: @ref{58d,,unittest.TestLoader} no longer loads test cases from
exact @ref{2b3,,unittest.TestCase} and @ref{19cb,,unittest.FunctionTestCase}
classes.

@item 
gh-99203@footnote{https://github.com/python/cpython/issues/99203}: Restore following CPython <= 3.10.5 behavior of
@ref{6d3,,shutil.make_archive()}: do not create an empty archive if
@code{root_dir} is not a directory, and, in that case, raise
@ref{264,,FileNotFoundError} or @ref{1255,,NotADirectoryError} regardless of
@code{format} choice. Beyond the brought-back behavior, the function may now
also raise these exceptions in @code{dry_run} mode.

@item 
gh-80480@footnote{https://github.com/python/cpython/issues/80480}: Emit @ref{1a3,,DeprecationWarning} for @ref{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{189a,,unittest.mock.create_autospec()} now properly returns
coroutine functions compatible with @ref{30c,,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{10a,,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{84,,ipaddress}. Patch
by Oleksandr Pavliuk.

@item 
bpo-44850@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44850}: Improve performance of @ref{102f,,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{11e2,,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{bda,,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{10d,,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{10d,,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<16>,Tests<18>,Library<23>,Python 3 13 0 alpha 1
@anchor{whatsnew/changelog id183}@anchor{19cc}
@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{3c,,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{787,,PyInterpreterConfig} and
@ref{682,,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{2f,,curses} module variables
@ref{fe7,,LINES} and @ref{fe8,,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{bd9,,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{55d,,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{55d,,traceback.TracebackException}
class.

@item 
gh-104943@footnote{https://github.com/python/cpython/issues/104943}: Remove mentions of old Python versions in
@ref{330,,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{196,,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<18>,Build<21>,Documentation<16>,Python 3 13 0 alpha 1
@anchor{whatsnew/changelog id184}@anchor{19cd}
@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{106,,tty}.

@item 
gh-81002@footnote{https://github.com/python/cpython/issues/81002}: Add tests for @ref{e7,,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{8a4,,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{1474,,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{ea,,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{4e9,,doctest.DocTestRunner.run()} method now counts the
number of skipped tests. Add @ref{4ea,,doctest.DocTestRunner.skips} and
@ref{4eb,,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{19ce,,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<21>,Windows<19>,Tests<18>,Python 3 13 0 alpha 1
@anchor{whatsnew/changelog id185}@anchor{19cf}
@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{19d0,,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{62e,,--with-trace-refs}
(tracing references) is now ABI compatible with Python release build and
@ref{504,,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{62f,,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{d4,,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<19>,macOS<13>,Build<21>,Python 3 13 0 alpha 1
@anchor{whatsnew/changelog id186}@anchor{19d1}
@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{262,,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{262,,realpath()} to behave consistently when
passed a path containing an embedded null character on Windows. In strict
mode, it now raises @ref{2c0,,OSError} instead of the unexpected
@ref{2eb,,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{7d3,,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{c47,,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{26d,,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{1915,,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<13>,IDLE<12>,Windows<19>,Python 3 13 0 alpha 1
@anchor{whatsnew/changelog id187}@anchor{19d2}
@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<12>,Tools/Demos<18>,macOS<13>,Python 3 13 0 alpha 1
@anchor{whatsnew/changelog id188}@anchor{19d3}
@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<18>,C API<21>,IDLE<12>,Python 3 13 0 alpha 1
@anchor{whatsnew/changelog id189}@anchor{19d4}
@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{62f,,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<21>,,Tools/Demos<18>,Python 3 13 0 alpha 1
@anchor{whatsnew/changelog id190}@anchor{19d5}
@subsubsection C API



@itemize -

@item 
gh-85283@footnote{https://github.com/python/cpython/issues/85283}: If the @ref{658,,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{611,,PyUnicode_EqualToUTF8AndSize()} and
@ref{612,,PyUnicode_EqualToUTF8()} functions.

@item 
gh-110235@footnote{https://github.com/python/cpython/issues/110235}: Raise @ref{198,,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{19d6,,PyImport_GetImporter()} now sets RuntimeError if it
fails to get @ref{121f,,sys.path_hooks} or @ref{7f3,,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{47f,,PyMutex} internal-only lightweight locking API.

@item 
gh-85283@footnote{https://github.com/python/cpython/issues/85283}: Add @ref{60a,,PySys_AuditTuple()} function: similar to
@ref{60b,,PySys_Audit()}, but pass event arguments as a Python @ref{60c,,tuple}
object.  Patch by Victor Stinner.

@item 
gh-108867@footnote{https://github.com/python/cpython/issues/108867}: Add @ref{421,,PyThreadState_GetUnchecked()} function: similar to
@ref{60d,,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{613,,PyObject_HasAttrWithError()},
@ref{615,,PyObject_HasAttrStringWithError()},
@ref{617,,PyMapping_HasKeyWithError()} and
@ref{619,,PyMapping_HasKeyStringWithError()}.

@item 
gh-107073@footnote{https://github.com/python/cpython/issues/107073}: Add @ref{605,,PyObject_VisitManagedDict()} and
@ref{606,,PyObject_ClearManagedDict()} functions which must be called by the
traverse and clear functions of a type using
@ref{607,,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{62e,,--with-trace-refs}
(tracing references) now supports the @ref{62f,,Limited API}.
Patch by Victor Stinner.

@item 
gh-108014@footnote{https://github.com/python/cpython/issues/108014}: Add @ref{5fc,,PyLong_AsInt()} function: similar to
@ref{5fd,,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{5d5,,PyDict_ContainsString()} function: same as
@ref{5d6,,PyDict_Contains()}, but `key' is specified as a const char* UTF-8 encoded bytes string, rather than a @ref{5d7,,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{5f5,,Py_IsFinalizing()} function: check if the main
Python interpreter is @ref{474,,shutting down}. Patch
by Victor Stinner.

@item 
gh-107916@footnote{https://github.com/python/cpython/issues/107916}: C API functions @ref{19d7,,PyErr_SetFromErrnoWithFilename()},
@ref{19d8,,PyErr_SetExcFromWindowsErrWithFilename()} and
@ref{19d9,,PyErr_SetFromWindowsErrWithFilename()} save now the error code
before calling @ref{19da,,PyUnicode_DecodeFSDefault()}.

@item 
gh-107915@footnote{https://github.com/python/cpython/issues/107915}: Such C API functions as @code{PyErr_SetString()},
@code{PyErr_Format()}, @code{PyErr_SetFromErrnoWithFilename()} and many others
no longer crash or ignore errors if it failed to format the error message
or decode the filename. Instead, they keep a corresponding error.

@item 
gh-107810@footnote{https://github.com/python/cpython/issues/107810}: Improve @ref{1a3,,DeprecationWarning} for uses of
@ref{19db,,PyType_Spec} with metaclasses that have custom @code{tp_new}.

@item 
gh-107249@footnote{https://github.com/python/cpython/issues/107249}: Implement the @ref{19dc,,Py_UNUSED} macro for Windows MSVC
compiler. Patch by Victor Stinner.

@item 
gh-107226@footnote{https://github.com/python/cpython/issues/107226}: @ref{602,,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{422,,PyUnicode_AsUTF8()}. It was kept for backward compatibility with
Python 3.0 - 3.2. The @ref{422,,PyUnicode_AsUTF8()} is available since Python
3.3. The @ref{138f,,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{17ae,,PyObject_DelAttr()} and
@ref{17af,,PyObject_DelAttrString()} macros to functions. Patch by Victor
Stinner.

@item 
gh-106307@footnote{https://github.com/python/cpython/issues/106307}: Add @ref{5e0,,PyMapping_GetOptionalItem()} function.

@item 
gh-106521@footnote{https://github.com/python/cpython/issues/106521}: Add @ref{5e4,,PyObject_GetOptionalAttr()} and
@ref{5e5,,PyObject_GetOptionalAttrString()} functions.

@item 
gh-106320@footnote{https://github.com/python/cpython/issues/106320}: Remove @code{_PyInterpreterState_Get()} alias to
@ref{644,,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{504,,debug mode} or
@ref{625,,with assertions}, @ref{626,,PyTuple_SET_ITEM()}
and @ref{627,,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{5d8,,PyDict_GetItemRef()} and
@ref{41f,,PyDict_GetItemStringRef()} functions: similar to
@ref{5d9,,PyDict_GetItemWithError()} but returning a @ref{5da,,strong reference}
instead of a @ref{3d5,,borrowed reference}. Patch by Victor Stinner.

@item 
gh-105927@footnote{https://github.com/python/cpython/issues/105927}: Deprecate the @ref{3db,,PyWeakref_GetObject()} and
@ref{3dc,,PyWeakref_GET_OBJECT()} functions: use the new
@ref{3dd,,PyWeakref_GetRef()} function instead. Patch by Victor Stinner.

@item 
gh-105927@footnote{https://github.com/python/cpython/issues/105927}: Add @ref{3dd,,PyWeakref_GetRef()} function: similar to
@ref{3db,,PyWeakref_GetObject()} but returns a @ref{5da,,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{5f3,,PyImport_AddModuleRef()}: similar to
@ref{5f4,,PyImport_AddModule()}, but return a @ref{5da,,strong reference}
instead of a @ref{3d5,,borrowed reference}. Patch by Victor Stinner.

@item 
gh-105227@footnote{https://github.com/python/cpython/issues/105227}: The new @ref{19dd,,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{19de,,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{19df,,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{788,,Py_INCREF()} and
@ref{789,,Py_DECREF()} functions are now implemented as opaque function calls
to hide implementation details. Patch by Victor Stinner.

@item 
gh-105396@footnote{https://github.com/python/cpython/issues/105396}: Deprecate the @ref{3d9,,PyImport_ImportModuleNoBlock()} function
which is just an alias to @ref{3da,,PyImport_ImportModule()} since Python
3.3. Patch by Victor Stinner.

@item 
gh-103968@footnote{https://github.com/python/cpython/issues/103968}: @ref{76b,,PyType_FromMetaclass()} now allows metaclasses with
@code{tp_new} set to @code{NULL}.

@item 
gh-105268@footnote{https://github.com/python/cpython/issues/105268}: Remove the old private, undocumented and untested
@code{_PyGC_FINALIZED()} macro which was kept for backward compatibility with
Python 3.8 and older. Patch by Victor Stinner.

@item 
gh-105182@footnote{https://github.com/python/cpython/issues/105182}: Remove @code{PyEval_AcquireLock()} and @code{PyEval_ReleaseLock()}
functions, deprecated in Python 3.2. Patch by Victor Stinner.

@item 
gh-105182@footnote{https://github.com/python/cpython/issues/105182}: Remove @code{PyEval_InitThreads()} and
@code{PyEval_ThreadsInitialized()} functions, deprecated in Python 3.9. Patch
by Victor Stinner.

@item 
gh-105145@footnote{https://github.com/python/cpython/issues/105145}: Deprecate old Python initialization functions:


@itemize *

@item 
@ref{3f2,,PySys_ResetWarnOptions()}

@item 
@ref{3e7,,Py_GetExecPrefix()}

@item 
@ref{3e1,,Py_GetPath()}

@item 
@ref{3e3,,Py_GetPrefix()}

@item 
@ref{3ea,,Py_GetProgramFullPath()}

@item 
@ref{3ec,,Py_GetProgramName()}

@item 
@ref{3ed,,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{632,,PyObject_GetBuffer()} and @ref{633,,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{634,,PyObject_CallNoArgs()} and @ref{635,,PyObject_Call()} (positional
arguments must not be `NULL') instead.

@item 
@code{PyEval_CallFunction()}: use @ref{637,,PyObject_CallFunction()} instead.

@item 
@code{PyEval_CallMethod()}: use @ref{638,,PyObject_CallMethod()} instead.

@item 
@code{PyCFunction_Call()}: use @ref{635,,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{1ac,,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{3bf,,PyArg_ParseTuple()} and
@ref{3c0,,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{79d,,PyOS_InputHook} or
@ref{79e,,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{601,,PyModule_Add()} function: similar to
@ref{602,,PyModule_AddObjectRef()} and @ref{603,,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{3c0,,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{19e0}
@subsection Python 3.12.0 beta 1


`Release date: 2023-05-22'

@menu
* Security: Security<20>. 
* Core and Builtins: Core and Builtins<23>. 
* Library: Library<24>. 
* Documentation: Documentation<17>. 
* Tests: Tests<19>. 
* Build: Build<22>. 
* Windows: Windows<20>. 
* macOS: macOS<14>. 
* IDLE: IDLE<13>. 
* Tools/Demos: Tools/Demos<19>. 
* C API: C API<22>. 

@end menu

@node Security<20>,Core and Builtins<23>,,Python 3 12 0 beta 1
@anchor{whatsnew/changelog id191}@anchor{19e1}
@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{6c,,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{f35,,urllib.parse.urlsplit()} now strips leading C0 control and
space characters following the specification for URLs defined by WHATWG in
response to 
@geindex Common Vulnerabilities and Exposures; CVE 2023-24329
CVE 2023-24329@footnote{https://www.cve.org/CVERecord?id=CVE-2023-24329}. Patch by Illia Volochii.
@end itemize

@node Core and Builtins<23>,Library<24>,Security<20>,Python 3 12 0 beta 1
@anchor{whatsnew/changelog id192}@anchor{19e2}
@subsubsection Core and Builtins



@itemize -

@item 
gh-102856@footnote{https://github.com/python/cpython/issues/102856}: Implement PEP 701 changes in the @ref{101,,tokenize} module. Patch
by Marta Gómez Macías and Pablo Galindo Salgado

@item 
gh-104615@footnote{https://github.com/python/cpython/issues/104615}: Fix wrong ordering of assignments in code like @code{a, a = x, y}.
Contributed by Carl Meyer.

@item 
gh-104572@footnote{https://github.com/python/cpython/issues/104572}: Improve syntax error message for invalid constructs in
@geindex Python Enhancement Proposals; PEP 695
PEP 695@footnote{https://peps.python.org/pep-0695/} contexts and in annotations when @code{from __future__ import
annotations} is active.

@item 
gh-104482@footnote{https://github.com/python/cpython/issues/104482}: Fix three error handling bugs in ast.c's validation of pattern
matching statements.

@item 
gh-102818@footnote{https://github.com/python/cpython/issues/102818}: Do not add a frame to the traceback in the @code{sys.setprofile}
and @code{sys.settrace} trampoline functions. This ensures that frames are
not duplicated if an exception is raised in the callback function, and
ensures that frames are not omitted if a C callback is used and that does
not add the frame.

@item 
gh-104405@footnote{https://github.com/python/cpython/issues/104405}: Fix an issue where some @ref{4a5,,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{24d,,list} or @ref{60c,,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{616,,PyObject_HasAttrString()}

@item 
gh-104066@footnote{https://github.com/python/cpython/issues/104066}: Improve the performance of @ref{6f2,,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{e02,,True}, @ref{d23,,False}, and @ref{87e,,None}) in the main interpreter
loop.

@item 
gh-103899@footnote{https://github.com/python/cpython/issues/103899}: Provide a helpful hint in the @ref{198,,TypeError} message when
accidentally calling a @ref{192d,,module} object that has a callable attribute
of the same name (such as @ref{205,,dis.dis()} or @ref{4dd,,datetime.datetime}).

@item 
gh-103845@footnote{https://github.com/python/cpython/issues/103845}: Remove both line and instruction instrumentation before adding
new ones for monitoring, to avoid newly added instrumentation being
removed immediately.

@item 
gh-103763@footnote{https://github.com/python/cpython/issues/103763}: Implement 
@geindex Python Enhancement Proposals; PEP 695
PEP 695@footnote{https://peps.python.org/pep-0695/}, adding syntactic support for generic
classes, generic functions, and type aliases.

A new @code{type X = ...} syntax is added for type aliases, which resolves at
runtime to an instance of the new class @code{typing.TypeAliasType}. The
value is lazily evaluated and is accessible through the @code{.__value__}
attribute. This is implemented as a new AST node @code{ast.TypeAlias}.

New syntax (@code{class X[T]: ...}, @code{def func[T](): ...}) is added for
defining generic functions and classes. This is implemented as a new
@code{type_params} attribute on the AST nodes for classes and functions. This
node holds instances of the new AST classes @code{ast.TypeVar},
@code{ast.ParamSpec}, and @code{ast.TypeVarTuple}.

@code{typing.TypeVar}, @code{typing.ParamSpec}, @code{typing.ParamSpecArgs},
@code{typing.ParamSpecKwargs}, @code{typing.TypeVarTuple}, and
@code{typing.Generic} are now implemented in C rather than Python.

There are new bytecode instructions @code{LOAD_LOCALS},
@code{LOAD_CLASSDICT_OR_GLOBAL}, and @code{LOAD_CLASSDICT_OR_DEREF} to support
correct resolution of names in class namespaces.

Patch by Eric Traut, Larry Hastings, and Jelle Zijlstra.

@item 
gh-103801@footnote{https://github.com/python/cpython/issues/103801}: Adds three minor linting fixes to the wasm module caught that
were caught by ruff.

@item 
gh-103793@footnote{https://github.com/python/cpython/issues/103793}: Optimized asyncio Task creation by deferring expensive string
formatting (task name generation) from Task creation to the first time
@code{get_name} is called. This makes asyncio benchmarks up to 5% faster.

@item 
gh-102310@footnote{https://github.com/python/cpython/issues/102310}: Change the error range for invalid bytes literals.

@item 
gh-103590@footnote{https://github.com/python/cpython/issues/103590}: Do not wrap a single exception raised from a @code{try-except*}
construct in an @ref{4cd,,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{1ac,,except*}.

@item 
gh-103492@footnote{https://github.com/python/cpython/issues/103492}: Clarify @ref{1ae,,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{6fb,,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{244,,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{5e8,,AttributeError} now retains the @code{name} attribute when
pickled and unpickled.

@item 
gh-103242@footnote{https://github.com/python/cpython/issues/103242}: Migrate @ref{1344,,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{900,,CACHE} entries for
@ref{90d,,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{11eb,,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{165,,memoryview} objects (such
as @code{memoryview(ctypes.c_uint8(42))}) now raises a @ref{198,,TypeError}.
Previously this returned @code{1}, which was not consistent with
@code{mem_0d[0]} raising an @ref{1729,,IndexError}.

@item 
bpo-31821@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31821}: Fix @code{pause_reading()} to work when called from
@code{connection_made()} in @ref{b,,asyncio}.
@end itemize

@node Library<24>,Documentation<17>,Core and Builtins<23>,Python 3 12 0 beta 1
@anchor{whatsnew/changelog id193}@anchor{19e3}
@subsubsection Library



@itemize -

@item 
gh-104600@footnote{https://github.com/python/cpython/issues/104600}: @ref{121d,,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{9bd,,issubclass()} check comparing a class
@code{X} against a @ref{66d,,runtime-checkable protocol} @code{Y} with non-callable members would not
cause @ref{198,,TypeError} to be raised if an @ref{2ad,,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{6cc,,pathlib.PurePath.match()}

@item 
gh-75367@footnote{https://github.com/python/cpython/issues/75367}: Fix data descriptor detection in
@ref{6b5,,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{10a,,typing}.

@item 
gh-102613@footnote{https://github.com/python/cpython/issues/102613}: Fix issue where @ref{532,,pathlib.Path.glob()} raised
@ref{f63,,RecursionError} when walking deep directory trees.

@item 
gh-103000@footnote{https://github.com/python/cpython/issues/103000}: Improve performance of @ref{19e4,,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{198b,,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{532,,pathlib.Path.glob()} raised @ref{2c0,,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{532,,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{532,,pathlib.Path.glob()} returned incomplete
results when it encountered a @ref{f39,,PermissionError}. This method now
suppresses all @ref{2c0,,OSError} exceptions, except those raised from calling
@ref{535,,is_dir()} on the top-level path.

@item 
gh-104144@footnote{https://github.com/python/cpython/issues/104144}: Optimize @ref{4cc,,asyncio.TaskGroup} when using
@ref{69b,,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{80c,,asyncio.gather()} when using
@ref{69b,,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{532,,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{532,,pathlib.Path.glob()} by using
@ref{19e5,,re.IGNORECASE} to implement case-insensitive matching.

@item 
gh-104102@footnote{https://github.com/python/cpython/issues/104102}: Improve performance of @ref{532,,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{18fd,,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{3c,,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{19e6,,turtle.teleport()} to the @ref{107,,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{19e7,,io.open_code()} for files to be executed instead of
raw @ref{315,,open()}

@item 
gh-68968@footnote{https://github.com/python/cpython/issues/68968}: Fixed garbled output of @ref{745,,assertEqual()}
when an input lacks final newline.

@item 
gh-100370@footnote{https://github.com/python/cpython/issues/100370}: Fix potential @ref{a78,,OverflowError} in
@ref{88a,,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{d4,,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{f35,,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{3c,,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{34f,,datetime.datetime.utcnow()} and
@ref{350,,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{1123,,contextlib.suppress} now supports suppressing
exceptions raised as part of an @ref{4cd,,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{bd7,,datetime.datetime.fromisocalendar()} in the
implementation of @ref{18b7,,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{19e8,,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{d1,,socket} constants for source-specific multicast. Patch
by Reese Hyde.

@item 
gh-103673@footnote{https://github.com/python/cpython/issues/103673}: @ref{d2,,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{739,,io.open()} with
@ref{19e7,,io.open_code()}. The new method would also call into the hook set by
@ref{19e9,,PyFile_SetOpenCodeHook()}.

@item 
gh-103556@footnote{https://github.com/python/cpython/issues/103556}: Now creating @ref{4de,,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{1976,,pathlib.Path.absolute()} and
@ref{19ea,,cwd()} by joining paths only when necessary. Also
improve performance of @ref{19eb,,pathlib.PurePath.is_absolute()} on Posix by
skipping path parsing and normalization.

@item 
gh-103538@footnote{https://github.com/python/cpython/issues/103538}: Remove @code{_tkinter} module code guarded by definition of the
@code{TK_AQUA} macro which was only needed for Tk 8.4.7 or earlier and was
never actually defined by any build system or documented for manual use.

@item 
gh-103533@footnote{https://github.com/python/cpython/issues/103533}: Update @ref{2b,,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{6c6,,pathlib.PurePath} and
@ref{266,,Path}.

@item 
gh-103489@footnote{https://github.com/python/cpython/issues/103489}: Add @ref{6d9,,getconfig()} and
@ref{6da,,setconfig()} to @ref{548,,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{547,,ResourceWarning} in
@ref{d2d,,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{175f,,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{fa2,,socket.socket.send()} or @ref{69a,,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{4dc,,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{168b,,logging.Formatter} @code{defaults}
parameter to @ref{13b1,,logging.config.dictConfig()} and
@ref{d40,,logging.config.fileConfig()}. Patch by Bar Harel.

@item 
gh-103092@footnote{https://github.com/python/cpython/issues/103092}: Adapt the @ref{11c,,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{2ad,,isinstance()} checks against
@ref{66d,,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{10a,,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{6f1,,"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{6e,,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{77,,idlelib}.

@item 
gh-103285@footnote{https://github.com/python/cpython/issues/103285}: Improve performance of @ref{bc2,,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{11d,,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{108d,,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{6c7,,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{19ec,,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{1900,,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{76,,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{6b5,,inspect.getattr_static()}. Patch by
Alex Waygood.

@item 
gh-103176@footnote{https://github.com/python/cpython/issues/103176}: @ref{6e2,,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{6d8,,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{19ed,,dataclasses.astuple()} and
@ref{19e4,,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{e4,,tarfile}, and
@ref{68f,,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{690,,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{532,,pathlib.Path.glob()} and @ref{533,,rglob()}.

@item 
gh-101819@footnote{https://github.com/python/cpython/issues/101819}: Isolate the @ref{83,,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{341,,collections.abc.ByteString}

@item 
gh-101362@footnote{https://github.com/python/cpython/issues/101362}: Speed up @ref{266,,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{3c,,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{10c,,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{6c6,,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{1993,,tty.cfmakeraw()} and @ref{1945,,tty.cfmakecbreak()} to
@ref{106,,tty} and modernize, the behavior of @ref{1992,,tty.setraw()} and
@ref{1944,,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{6ee,,types.get_original_bases()} to provide further
introspection for types.

@item 
gh-101640@footnote{https://github.com/python/cpython/issues/101640}: @ref{1bd,,argparse.ArgumentParser} now catches errors when
writing messages, such as when @ref{b2a,,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{6b,,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{d2d,,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{5a9,,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{4b2,,subprocess.Popen}.

@item 
gh-94906@footnote{https://github.com/python/cpython/issues/94906}: Support multiple steps in @ref{6b9,,math.nextafter()}. Patch by
Shantanu Jain and Matthias Gorgens.

@item 
gh-51574@footnote{https://github.com/python/cpython/issues/51574}: Make @ref{528,,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{137,,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{11b,,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{532,,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{6a6,,QUOTE_STRINGS} and @ref{6a5,,QUOTE_NOTNULL}
to the suite of @ref{2d,,csv} module quoting styles.

@item 
bpo-24964@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24964}: Added
@ref{19c5,,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{19ee,,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<17>,Tests<19>,Library<24>,Python 3 12 0 beta 1
@anchor{whatsnew/changelog id194}@anchor{19ef}
@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<19>,Build<22>,Documentation<17>,Python 3 12 0 beta 1
@anchor{whatsnew/changelog id195}@anchor{19f0}
@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{13a,,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{31a,,os.spawn*} tests failing on Windows
when the working directory or interpreter path contains spaces.
@end itemize

@node Build<22>,Windows<20>,Tests<19>,Python 3 12 0 beta 1
@anchor{whatsnew/changelog id196}@anchor{19f1}
@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<20>,macOS<14>,Build<22>,Python 3 12 0 beta 1
@anchor{whatsnew/changelog id197}@anchor{19f2}
@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{132f,,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{198,,TypeError} was raised when calling
@code{ntpath.realpath()} with a bytes parameter in some cases.
@end itemize

@node macOS<14>,IDLE<13>,Windows<20>,Python 3 12 0 beta 1
@anchor{whatsnew/changelog id198}@anchor{19f3}
@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<13>,Tools/Demos<19>,macOS<14>,Python 3 12 0 beta 1
@anchor{whatsnew/changelog id199}@anchor{19f4}
@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<19>,C API<22>,IDLE<13>,Python 3 12 0 beta 1
@anchor{whatsnew/changelog id200}@anchor{19f5}
@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{19dc,,Py_UNUSED}. Patch by Erlend E.
Aasland.
@end itemize

@node C API<22>,,Tools/Demos<19>,Python 3 12 0 beta 1
@anchor{whatsnew/changelog id201}@anchor{19f6}
@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{79f,,PyUnstable_Long_IsCompact()} and
@ref{7a0,,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{796,,PyType_FromSpec()} and its variants now allow creating
classes whose metaclass overrides @ref{798,,tp_new}. The
@code{tp_new} is ignored. This behavior is deprecated and will be disallowed
in 3.14+. The new @ref{76b,,PyType_FromMetaclass()} already disallows it.

@item 
gh-103743@footnote{https://github.com/python/cpython/issues/103743}: Add @ref{19f7,,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{19f8,,PyUnstable_WritePerfMapEntry()},
@ref{19f9,,PyUnstable_PerfMapState_Init()} and
@ref{19fa,,PyUnstable_PerfMapState_Fini()}. These allow extension modules (JIT
compilers in particular) to write to perf-map files in a thread safe
manner. The @ref{19fb,,Python 對 Linux perf 分析器的支援} 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{763,,PyType_Spec.basicsize} can now be zero or negative,
@ref{764,,PyObject_GetTypeData()} can be used to get subclass-specific data,
and @ref{766,,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{19fc,,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{623,,PyUnicode_FromFormat()} and @ref{78d,,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{19fd}
@subsection Python 3.12.0 alpha 7


`Release date: 2023-04-04'

@menu
* Core and Builtins: Core and Builtins<24>. 
* Library: Library<25>. 
* Documentation: Documentation<18>. 
* Tests: Tests<20>. 
* Build: Build<23>. 
* Windows: Windows<21>. 
* Tools/Demos: Tools/Demos<20>. 
* C API: C API<23>. 

@end menu

@node Core and Builtins<24>,Library<25>,,Python 3 12 0 alpha 7
@anchor{whatsnew/changelog id202}@anchor{19fe}
@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{900,,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{6de,,sys.last_exc} and deprecate @ref{6df,,sys.last_type},
@ref{6e0,,sys.last_value} and @ref{6e1,,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{b58,,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{433,,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{900,,CACHE} entries used by
@ref{19ab,,LOAD_GLOBAL}.

@item 
gh-102491@footnote{https://github.com/python/cpython/issues/102491}: Improve import time of @code{platform} by removing IronPython
version parsing. The IronPython version parsing was not functional (see
@indicateurl{https://github.com/IronLanguages/ironpython3/issues/1667}).

@item 
gh-101291@footnote{https://github.com/python/cpython/issues/101291}: Rearrage bits in first field (after header) of PyLongObject. *
Bits 0 and 1: 1 - sign. I.e. 0 for positive numbers, 1 for zero and 2 for
negative numbers. * Bit 2 reserved (probably for the immortal bit) * Bits
3+ the unsigned size.

This makes a few operations slightly more efficient, and will enable a
more compact and faster 2s-complement representation of most ints in
future.

@item 
gh-102397@footnote{https://github.com/python/cpython/issues/102397}: Fix segfault from race condition in signal handling during
garbage collection. Patch by Kumar Aditya.

@item 
gh-102406@footnote{https://github.com/python/cpython/issues/102406}: @ref{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.

@item 
gh-102027@footnote{https://github.com/python/cpython/issues/102027}: Fix SSE2 and SSE3 detection in @code{_blake2} internal module.
Patch by Max Bachmann.

@item 
gh-101865@footnote{https://github.com/python/cpython/issues/101865}: Deprecate @code{co_lnotab} in code objects, schedule it for
removal in Python 3.14

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Adapt @code{_pickle} to 
@geindex Python Enhancement Proposals; PEP 687
PEP 687@footnote{https://peps.python.org/pep-0687/}. Patch by Mohamed Koubaa
and Erlend Aasland.
@end itemize

@node Library<25>,Documentation<18>,Core and Builtins<24>,Python 3 12 0 alpha 7
@anchor{whatsnew/changelog id203}@anchor{19ff}
@subsubsection Library



@itemize -

@item 
gh-103085@footnote{https://github.com/python/cpython/issues/103085}: Pure python @ref{328,,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{273,,Pdb} that raise @ref{18e,,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{3c,,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{2ad,,isinstance()} checks against @ref{66d,,runtime-checkable protocols} now use
@ref{6b5,,inspect.getattr_static()} rather than @ref{6f2,,hasattr()} to lookup
whether attributes exist. This means that descriptors and
@ref{6f3,,__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{273,,Pdb} that raise @ref{18e,,SyntaxError}. Patch by Tian Gao.

@item 
gh-102947@footnote{https://github.com/python/cpython/issues/102947}: Improve traceback when @ref{189b,,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{1991,,asyncio.Timeout} context manager now works reliably
even when performing cleanup due to task cancellation.  Previously it
could raise a @ref{4cf,,CancelledError} instead of an
@ref{1a00,,TimeoutError} in such cases.

@item 
gh-102871@footnote{https://github.com/python/cpython/issues/102871}: Remove support for obsolete browsers from @ref{11b,,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{16b4,,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{354,,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{482,,ParamSpec}. Previously, if the
@code{ParamSpec} was substituted with a parameters list that itself contained
a @ref{481,,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{6c6,,pathlib.PurePath} and @ref{266,,Path} subclasses were not
called in some circumstances.

@item 
gh-78530@footnote{https://github.com/python/cpython/issues/78530}: @ref{6a0,,asyncio.wait()} now accepts generators yielding tasks.
Patch by Kumar Aditya.

@item 
gh-102748@footnote{https://github.com/python/cpython/issues/102748}: @ref{69f,,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{482,,ParamSpec}. (Use square brackets to
represent a parameter list.)

@item 
gh-100112@footnote{https://github.com/python/cpython/issues/100112}: @ref{bc6,,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{6be,,os.listdrives()}, @ref{6bf,,os.listvolumes()} and
@ref{6c0,,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{e4,,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{6b3,,inspect.getasyncgenstate()} and
@ref{6b4,,inspect.getasyncgenlocals()}. Patch by Thomas Krennwallner.

@item 
gh-102103@footnote{https://github.com/python/cpython/issues/102103}: Add @code{module} argument to @ref{17dc,,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{cc,,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{33,,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{10e9,,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{1435,,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{1a01,,unittest.TextTestRunner} and
@ref{74d,,unittest.TextTestResult} constructors accept a new `durations'
keyword argument. Subclasses should take this into account or accept
@code{**kwargs}. Added @ref{1a02,,unittest.TestResult.addDuration()} method and
@ref{19ce,,unittest.TestResult.collectedDurations} attribute.

(Contributed by Giampaolo Rodola)

@item 
gh-98169@footnote{https://github.com/python/cpython/issues/98169}: Fix @ref{19ed,,dataclasses.astuple()} crash when
@ref{13bd,,collections.defaultdict} is present in the attributes.

@item 
gh-96931@footnote{https://github.com/python/cpython/issues/96931}: Fix incorrect results from @ref{1067,,ssl.SSLSocket.shared_ciphers()}

@item 
gh-95495@footnote{https://github.com/python/cpython/issues/95495}: When built against OpenSSL 3.0, the @ref{d5,,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{1a03,,SSLEOFError}, matching the
behavior in previous versions of OpenSSL. The
@ref{a32,,options} attribute on @ref{355,,SSLContext} also
no longer includes @ref{a31,,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{2e4,,uuid.uuid3()} and @ref{2e5,,uuid.uuid5()} functions support
@ref{192,,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{2f6,,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<18>,Tests<20>,Library<25>,Python 3 12 0 alpha 7
@anchor{whatsnew/changelog id204}@anchor{1a04}
@subsubsection Documentation



@itemize -

@item 
gh-103112@footnote{https://github.com/python/cpython/issues/103112}: Add docstring to @ref{1825,,http.client.HTTPResponse.read()} to fix
@code{pydoc} output.
@end itemize

@node Tests<20>,Build<23>,Documentation<18>,Python 3 12 0 alpha 7
@anchor{whatsnew/changelog id205}@anchor{1a05}
@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<23>,Windows<21>,Tests<20>,Python 3 12 0 alpha 7
@anchor{whatsnew/changelog id206}@anchor{1a06}
@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<21>,Tools/Demos<20>,Build<23>,Python 3 12 0 alpha 7
@anchor{whatsnew/changelog id207}@anchor{1a07}
@subsubsection Windows



@itemize -

@item 
gh-102690@footnote{https://github.com/python/cpython/issues/102690}: Update @ref{11b,,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<20>,C API<23>,Windows<21>,Python 3 12 0 alpha 7
@anchor{whatsnew/changelog id208}@anchor{1a08}
@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<23>,,Tools/Demos<20>,Python 3 12 0 alpha 7
@anchor{whatsnew/changelog id209}@anchor{1a09}
@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{1a0a}
@subsection Python 3.12.0 alpha 6


`Release date: 2023-03-07'

@menu
* Security: Security<21>. 
* Core and Builtins: Core and Builtins<25>. 
* Library: Library<26>. 
* Documentation: Documentation<19>. 
* Tests: Tests<21>. 
* Build: Build<24>. 
* Windows: Windows<22>. 
* macOS: macOS<15>. 
* C API: C API<24>. 

@end menu

@node Security<21>,Core and Builtins<25>,,Python 3 12 0 alpha 6
@anchor{whatsnew/changelog id210}@anchor{1a0b}
@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{6c,,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{4b2,,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<25>,Library<26>,Security<21>,Python 3 12 0 alpha 6
@anchor{whatsnew/changelog id211}@anchor{1a0c}
@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{1a0d,,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{1a0e,,socket.getaddrinfo} no longer raises
@ref{a78,,OverflowError} for @ref{19b,,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{1a0f,,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{701,,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{105,,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<26>,Documentation<19>,Core and Builtins<25>,Python 3 12 0 alpha 6
@anchor{whatsnew/changelog id212}@anchor{1a10}
@subsubsection Library



@itemize -

@item 
gh-102302@footnote{https://github.com/python/cpython/issues/102302}: Micro-optimise hashing of @ref{4df,,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{4b7,,argparse.ArgumentParser.add_argument()} were dropped. Patch by Yeojin
Kim.

@item 
gh-91038@footnote{https://github.com/python/cpython/issues/91038}: @ref{1a11,,platform.platform()} now has boolean default arguments.

@item 
gh-81652@footnote{https://github.com/python/cpython/issues/81652}: Add @ref{1a12,,mmap.MAP_ALIGNED_SUPER} FreeBSD and
@ref{1a13,,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{d52,,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{109f,,io.BytesIO} if
@ref{11d9,,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{6c,,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{78e,,SystemError} when
the callable object exhausts the iterator but forgets to either return a
sentinel value or raise @ref{df0,,StopIteration}.

@item 
gh-87634@footnote{https://github.com/python/cpython/issues/87634}: Remove locking behavior from @ref{75c,,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{89,,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{213,,fractions.Fraction} for small components. The
private argument @code{_normalize} of the @ref{213,,fractions.Fraction}
constructor has been removed.

@item 
gh-101693@footnote{https://github.com/python/cpython/issues/101693}: In @ref{5aa,,sqlite3.Cursor.execute()}, @ref{1a3,,DeprecationWarning} is
now emitted when @ref{5ac,,named placeholders} are used
together with parameters supplied as a @ref{70f,,sequence} instead of as a
@ref{183,,dict}. Starting from Python 3.14, using named placeholders with
parameters supplied as a sequence will raise a
@ref{304,,ProgrammingError}. Patch by Erlend E. Aasland.

@item 
gh-101446@footnote{https://github.com/python/cpython/issues/101446}: Change repr of @ref{7ec,,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{6c6,,pathlib.PurePath} construction by handling
arguments more uniformly. When a @ref{266,,pathlib.Path} argument is
supplied, we use its string representation rather than joining its parts
with @ref{1900,,os.path.join()}.

@item 
gh-101362@footnote{https://github.com/python/cpython/issues/101362}: Speed up @ref{6c6,,pathlib.PurePath} construction by calling
@ref{1900,,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{266,,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{1a14,,pty.fork()} to use
@ref{1a15,,os.login_tty()}.

A @ref{1a3,,DeprecationWarning} is now raised by @code{pty.master_open()} and
@code{pty.slave_open()}. They were undocumented and deprecated long long ago
in the docstring in favor of @ref{300,,pty.openpty()}.

@item 
gh-101561@footnote{https://github.com/python/cpython/issues/101561}: Add a new decorator @ref{675,,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{e3,,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{60,,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{85,,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{1976,,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{13a,,zoneinfo}. Patch by Erlend E. Aasland.

@item 
gh-96764@footnote{https://github.com/python/cpython/issues/96764}: @ref{80e,,asyncio.wait_for()} now uses @ref{80d,,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{1a16,,lzma.LZMADecompressor} and
@ref{1a17,,bz2.BZ2Decompressor} objects without calling @code{__init__()}, and
fix leakage of locks and internal buffers when calling the @code{__init__()}
methods of @ref{1a16,,lzma.LZMADecompressor}, @ref{1a18,,lzma.LZMACompressor},
@ref{1a19,,bz2.BZ2Compressor}, and @ref{1a17,,bz2.BZ2Decompressor} objects
multiple times.
@end itemize

@node Documentation<19>,Tests<21>,Library<26>,Python 3 12 0 alpha 6
@anchor{whatsnew/changelog id213}@anchor{1a1a}
@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{1a1b,,asyncio.Task.print_stack()} description for
@code{file=None}. Patch by Oleg Iarygin.
@end itemize

@node Tests<21>,Build<24>,Documentation<19>,Python 3 12 0 alpha 6
@anchor{whatsnew/changelog id214}@anchor{1a1c}
@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<24>,Windows<22>,Tests<21>,Python 3 12 0 alpha 6
@anchor{whatsnew/changelog id215}@anchor{1a1d}
@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{1a1e,,--with-strict-overflow}. Patch by Matthias Görgens and Shantanu
Jain.
@end itemize

@node Windows<22>,macOS<15>,Build<24>,Python 3 12 0 alpha 6
@anchor{whatsnew/changelog id216}@anchor{1a1f}
@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<15>,C API<24>,Windows<22>,Python 3 12 0 alpha 6
@anchor{whatsnew/changelog id217}@anchor{1a20}
@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<24>,,macOS<15>,Python 3 12 0 alpha 6
@anchor{whatsnew/changelog id218}@anchor{1a21}
@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{427,,PyErr_GetRaisedException()} and
@ref{42a,,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{426,,PyErr_Fetch()} and @ref{429,,PyErr_Restore()}. This is less error
prone and a bit more efficient.

Add @ref{784,,PyException_GetArgs()} and @ref{785,,PyException_SetArgs()} as
convenience functions for retrieving and modifying the
@ref{786,,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{1a22}
@subsection Python 3.12.0 alpha 5


`Release date: 2023-02-07'

@menu
* Security: Security<22>. 
* Core and Builtins: Core and Builtins<26>. 
* Library: Library<27>. 
* Documentation: Documentation<20>. 
* Tests: Tests<22>. 
* Build: Build<25>. 
* Windows: Windows<23>. 

@end menu

@node Security<22>,Core and Builtins<26>,,Python 3 12 0 alpha 5
@anchor{whatsnew/changelog id219}@anchor{1a23}
@subsubsection Security



@itemize -

@item 
gh-99108@footnote{https://github.com/python/cpython/issues/99108}: Replace the builtin @ref{6c,,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<26>,Library<27>,Security<22>,Python 3 12 0 alpha 5
@anchor{whatsnew/changelog id221}@anchor{1a24}
@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{1a25,,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{180,,continue} or
@ref{17f,,break} which are not in a loop. Patch by Donghee Na.

@item 
gh-101372@footnote{https://github.com/python/cpython/issues/101372}: Fix @ref{c33,,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{1a26,,sys.getsizeof()} reporting for @ref{19b,,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{181e,,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{19b,,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{5b2,,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{b58,,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{17df,,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{5df,,KeyError} to be raised out of
@code{importlib/_bootstrap}.  In addition to the straightforward cases,
this could also happen when garbage collection leads to a warning being
emitted -- as happens when it collects an open socket or file)

@item 
gh-100726@footnote{https://github.com/python/cpython/issues/100726}: Optimize construction of @code{range} object for medium size
integers.

@item 
gh-100712@footnote{https://github.com/python/cpython/issues/100712}: Added option to build cpython with specialization disabled, by
setting @code{ENABLE_SPECIALIZATION=False} in @code{opcode}, followed by
@code{make regen-all}.

@item 
bpo-32780@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32780}: Inter-field padding is now inserted into the PEP3118 format
strings obtained from @ref{1e5,,ctypes.Structure} objects, reflecting their
true representation in memory.
@end itemize

@node Library<27>,Documentation<20>,Core and Builtins<26>,Python 3 12 0 alpha 5
@anchor{whatsnew/changelog id222}@anchor{1a27}
@subsubsection Library



@itemize -

@item 
gh-101541@footnote{https://github.com/python/cpython/issues/101541}: [Enum] - fix psuedo-flag creation

@item 
gh-101570@footnote{https://github.com/python/cpython/issues/101570}: Upgrade pip wheel bundled with ensurepip (pip 23.0)

@item 
gh-101323@footnote{https://github.com/python/cpython/issues/101323}: Fix a bug where errors where not thrown by
zlib._ZlibDecompressor if encountered during decompressing.

@item 
gh-101317@footnote{https://github.com/python/cpython/issues/101317}: Add `ssl_shutdown_timeout' parameter for
@ref{812,,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{d1,,socket} when when a libc @code{getaddrinfo()} implementation leaves
garbage in an output pointer when returning an error. Original patch by
Sergey G. Brester.

@item 
gh-101143@footnote{https://github.com/python/cpython/issues/101143}: Remove unused references to @ref{1a28,,TimerHandle} in
@code{asyncio.base_events.BaseEventLoop._add_callback}.

@item 
gh-101144@footnote{https://github.com/python/cpython/issues/101144}: Make @ref{1872,,zipfile.Path.open()} and
@ref{1a29,,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{198,,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{8b9,,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{6c4,,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{170d,,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{1e5,,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{213,,fractions.Fraction} instances.

@item 
gh-99266@footnote{https://github.com/python/cpython/issues/99266}: Preserve more detailed error messages in @ref{2e,,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{1a2a,,sys._getframemodulename()}.

@item 
gh-88597@footnote{https://github.com/python/cpython/issues/88597}: @ref{116,,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{1a2b,,c_byte} to @ref{1a2c,,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{12b,,xml.etree.ElementTree} module now emits
@ref{1a3,,DeprecationWarning} when testing the truth value of an
@ref{361,,xml.etree.ElementTree.Element}. Before, the Python implementation
emitted @ref{651,,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{266,,pathlib.Path} accepted and ignored
keyword arguments. Patch provided by Yurii Karabas.

@item 
gh-77772@footnote{https://github.com/python/cpython/issues/77772}: @ref{bd3,,ctypes.CDLL}, @ref{1a2d,,ctypes.OleDLL},
@ref{1a2e,,ctypes.WinDLL}, and @ref{1a2f,,ctypes.PyDLL} now accept
@ref{59b,,path-like objects} as their @code{name} argument.
Patch by Robert Hoelzl.
@end itemize

@node Documentation<20>,Tests<22>,Library<27>,Python 3 12 0 alpha 5
@anchor{whatsnew/changelog id223}@anchor{1a30}
@subsubsection Documentation



@itemize -

@item 
gh-88324@footnote{https://github.com/python/cpython/issues/88324}: Reword @ref{dc,,subprocess} to emphasize default behavior of
`stdin', `stdout', and `stderr' arguments. Remove inaccurate statement
about child file handle inheritance.
@end itemize

@node Tests<22>,Build<25>,Documentation<20>,Python 3 12 0 alpha 5
@anchor{whatsnew/changelog id224}@anchor{1a31}
@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<25>,Windows<23>,Tests<22>,Python 3 12 0 alpha 5
@anchor{whatsnew/changelog id225}@anchor{1a32}
@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{647,,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<23>,,Build<25>,Python 3 12 0 alpha 5
@anchor{whatsnew/changelog id226}@anchor{1a33}
@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{1a34}
@subsection Python 3.12.0 alpha 4


`Release date: 2023-01-10'

@menu
* Core and Builtins: Core and Builtins<27>. 
* Library: Library<28>. 
* Documentation: Documentation<21>. 
* Tests: Tests<23>. 
* Build: Build<26>. 
* Windows: Windows<24>. 
* macOS: macOS<16>. 
* Tools/Demos: Tools/Demos<21>. 
* C API: C API<25>. 

@end menu

@node Core and Builtins<27>,Library<28>,,Python 3 12 0 alpha 4
@anchor{whatsnew/changelog id227}@anchor{1a35}
@subsubsection Core and Builtins



@itemize -

@item 
gh-100776@footnote{https://github.com/python/cpython/issues/100776}: Fix misleading default value in @ref{14d9,,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{700,,CALL_INTRINSIC_1} instruction. Remove
@code{IMPORT_STAR}, @code{PRINT_EXPR} and
@code{STOPITERATION_ERROR}, replacing them with the
@ref{700,,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{18e,,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{1a36,,int.is_integer()} to improve duck type compatibility
between @ref{19b,,int} and @ref{196,,float}.

@item 
gh-100425@footnote{https://github.com/python/cpython/issues/100425}: Improve the accuracy of @code{sum()} with compensated summation.

@item 
gh-100374@footnote{https://github.com/python/cpython/issues/100374}: Fix incorrect result and delay in @ref{1a37,,socket.getfqdn()}. Patch
by Dominic Socular.

@item 
gh-100357@footnote{https://github.com/python/cpython/issues/100357}: Convert @code{vars}, @code{dir}, @code{next}, @code{getattr}, and @code{iter}
to argument clinic.

@item 
gh-100117@footnote{https://github.com/python/cpython/issues/100117}: Improve the output of @ref{34e,,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{b58,,COMPARE_OP} for
@ref{196,,float} values.

@item 
gh-100222@footnote{https://github.com/python/cpython/issues/100222}: Redefine the @code{_Py_CODEUNIT} typedef as a union to describe
its layout to the C compiler, avoiding type punning and improving clarity.

@item 
gh-99955@footnote{https://github.com/python/cpython/issues/99955}: Internal compiler functions (in compile.c) now consistently
return -1 on error and 0 on success.

@item 
gh-100188@footnote{https://github.com/python/cpython/issues/100188}: The @code{BINARY_SUBSCR_LIST_INT} and @code{BINARY_SUBSCR_TUPLE_INT}
instructions are no longer used for negative integers because those
instructions always miss when encountering negative integers.

@item 
gh-99110@footnote{https://github.com/python/cpython/issues/99110}: Initialize frame->previous in frameobject.c to fix a
segmentation fault when accessing frames created by @code{PyFrame_New()}.

@item 
gh-94155@footnote{https://github.com/python/cpython/issues/94155}: Improved the hashing algorithm for code objects, mitigating some
hash collisions.

@item 
gh-99540@footnote{https://github.com/python/cpython/issues/99540}: @code{None} now hashes to a constant value. This is not a
requirements change.

@item 
gh-100143@footnote{https://github.com/python/cpython/issues/100143}: When built with @code{--enable-pystats}, stats collection is now
off by default. To enable it early at startup, pass the @code{-Xpystats}
flag.  Stats are now always dumped, even if switched off.

@item 
gh-100146@footnote{https://github.com/python/cpython/issues/100146}: Improve @code{BUILD_LIST} opcode so that it works similarly to the
@code{BUILD_TUPLE} opcode, by stealing references from the stack rather than
repeatedly using stack operations to set list elements.  Implementation
details are in a new private API @code{_PyList_FromArraySteal()}.

@item 
gh-100110@footnote{https://github.com/python/cpython/issues/100110}: Specialize @code{FOR_ITER} for tuples.

@item 
gh-100050@footnote{https://github.com/python/cpython/issues/100050}: Honor existing errors obtained when searching for mismatching
parentheses in the tokenizer. Patch by Pablo Galindo

@item 
gh-92216@footnote{https://github.com/python/cpython/issues/92216}: Improve the performance of @ref{6f2,,hasattr()} for type objects with
a missing attribute.

@item 
gh-99582@footnote{https://github.com/python/cpython/issues/99582}: Freeze @ref{138,,zipimport} module into @code{_bootstrap_python}.

@item 
gh-99554@footnote{https://github.com/python/cpython/issues/99554}: Pack debugging location tables more efficiently during bytecode
compilation.

@item 
gh-98522@footnote{https://github.com/python/cpython/issues/98522}: Add an internal version number to code objects, to give better
versioning of inner functions and comprehensions, and thus better
specialization of those functions. This change is invisible to both Python
and C extensions.

@item 
gh-94603@footnote{https://github.com/python/cpython/issues/94603}: Improve performance of @code{list.pop} for small lists.

@item 
gh-89051@footnote{https://github.com/python/cpython/issues/89051}: Add @ref{1a38,,ssl.OP_LEGACY_SERVER_CONNECT}

@item 
bpo-32782@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32782}: @code{ctypes} arrays of length 0 now report a correct itemsize
when a @code{memoryview} is constructed from them, rather than always giving
a value of 0.
@end itemize

@node Library<28>,Documentation<21>,Core and Builtins<27>,Python 3 12 0 alpha 4
@anchor{whatsnew/changelog id228}@anchor{1a39}
@subsubsection Library



@itemize -

@item 
gh-100833@footnote{https://github.com/python/cpython/issues/100833}: Speed up @ref{15cb,,math.fsum()} by removing defensive @code{volatile}
qualifiers.

@item 
gh-100805@footnote{https://github.com/python/cpython/issues/100805}: Modify @ref{1431,,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{1a3a,,email.message.Message.__contains__()} twice as fast.

@item 
gh-91851@footnote{https://github.com/python/cpython/issues/91851}: Microoptimizations for @ref{1a3b,,fractions.Fraction.__round__()},
@ref{1a3c,,fractions.Fraction.__ceil__()} and
@ref{1a3d,,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{6c9,,os.walk()} by using
@ref{2ad,,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{d06,,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{1976,,pathlib.Path.absolute()} by nearly
2x. This comes at the cost of a performance regression in
@ref{19ea,,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{d95,,unittest.mock.seal()} with
@ref{c35,,unittest.mock.AsyncMock}.

@item 
gh-100488@footnote{https://github.com/python/cpython/issues/100488}: Add @code{Fraction.is_integer()} to check whether a
@ref{213,,fractions.Fraction} is an integer. This improves duck type
compatibility with @ref{196,,float} and @ref{19b,,int}.

@item 
gh-100474@footnote{https://github.com/python/cpython/issues/100474}: @ref{76,,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{cf9,,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{69e,,asyncio.current_task()} for a
4x-6x speedup.

@item 
gh-100272@footnote{https://github.com/python/cpython/issues/100272}: Fix JSON serialization of OrderedDict.  It now preserves the
order of keys.

@item 
gh-83076@footnote{https://github.com/python/cpython/issues/83076}: Instantiation of @code{Mock()} and @code{AsyncMock()} is now 3.8x
faster.

@item 
gh-100234@footnote{https://github.com/python/cpython/issues/100234}: Set a default value of 1.0 for the @code{lambd} parameter in
random.expovariate().

@item 
gh-100228@footnote{https://github.com/python/cpython/issues/100228}: A @ref{1a3,,DeprecationWarning} may be raised when @ref{4b0,,os.fork()}
or @ref{4b1,,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{13ff,,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{1a3e,,datetime.time.strftime()} to `format'. Rename the `t' parameter of
@ref{70b,,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{11d9,,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{6c9,,os.walk()} where a @ref{f63,,RecursionError}
would occur on deep directory structures by adjusting the implementation
of @ref{6c9,,os.walk()} to be iterative instead of recursive.

@item 
gh-94943@footnote{https://github.com/python/cpython/issues/94943}: Add @ref{1a3f,,Dataclass support} to the @ref{83b,,Enum}
@ref{1a40,,__repr__()}. When inheriting from a
@ref{4dc,,dataclass}, only show the field names in the value
section of the member @ref{1c1,,repr()}, and not the dataclass' class name.

@item 
gh-83035@footnote{https://github.com/python/cpython/issues/83035}: Fix @ref{1759,,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{6b1,,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{3e,,doctest} failure on @ref{854,,types.MethodWrapperType}
in modules.

@item 
gh-85267@footnote{https://github.com/python/cpython/issues/85267}: Several improvements to @ref{22f,,inspect.signature()}'s handling of
@code{__text_signature}. - Fixes a case where @ref{22f,,inspect.signature()}
dropped parameters - Fixes a case where @ref{22f,,inspect.signature()} raised
@ref{75d,,tokenize.TokenError} - Allows @ref{22f,,inspect.signature()} to
understand defaults involving binary operations of constants -
@ref{22f,,inspect.signature()} is documented as only raising @ref{198,,TypeError}
or @ref{2eb,,ValueError}, but sometimes raised @ref{244,,RuntimeError}. These
cases now raise @ref{2eb,,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{69a,,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{1a41,,urllib.parse.unquote()} and
@ref{1a42,,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{d17,,asynccontextmanager()}, which caused it to propagate
exceptions with incorrect tracebacks and fix a 3.11 regression in
@ref{1403,,contextmanager()}, which caused it to propagate
exceptions with incorrect tracebacks for @ref{df0,,StopIteration}.

@item 
gh-78707@footnote{https://github.com/python/cpython/issues/78707}: Deprecate passing more than one positional argument to
@ref{2fc,,pathlib.PurePath.relative_to()} and
@ref{2fd,,is_relative_to()}.

@item 
gh-92122@footnote{https://github.com/python/cpython/issues/92122}: Fix reStructuredText syntax errors in docstrings in the
@ref{5a,,enum} module.

@item 
gh-91851@footnote{https://github.com/python/cpython/issues/91851}: Optimize the @ref{213,,Fraction} arithmetics for small
components.

@item 
bpo-24132@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24132}: Make @ref{6c6,,pathlib.PurePath} and @ref{266,,Path}
subclassable (private to start). Previously, attempting to instantiate a
subclass resulted in an @ref{5e8,,AttributeError} being raised. Patch by
Barney Gale.

@item 
bpo-40447@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40447}: Accept @ref{e46,,os.PathLike} (such as @ref{266,,pathlib.Path}) in
the @code{stripdir} arguments of @ref{fdc,,compileall.compile_file()} and
@ref{d13,,compileall.compile_dir()}.

@item 
bpo-36880@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36880}: Fix a reference counting issue when a @ref{2e,,ctypes} callback
with return type @ref{1f3,,py_object} returns @code{None}, which could
cause crashes.
@end itemize

@node Documentation<21>,Tests<23>,Library<28>,Python 3 12 0 alpha 4
@anchor{whatsnew/changelog id229}@anchor{1a43}
@subsubsection Documentation



@itemize -

@item 
gh-100616@footnote{https://github.com/python/cpython/issues/100616}: Document existing @code{attr} parameter to
@ref{1a44,,curses.window.vline()} function in @ref{2f,,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{d13,,compileall.compile_dir()} and @ref{fdc,,compileall.compile_file()} could
be @ref{192,,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<23>,Build<26>,Documentation<21>,Python 3 12 0 alpha 4
@anchor{whatsnew/changelog id230}@anchor{1a45}
@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<26>,Windows<24>,Tests<23>,Python 3 12 0 alpha 4
@anchor{whatsnew/changelog id231}@anchor{1a46}
@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<24>,macOS<16>,Build<26>,Python 3 12 0 alpha 4
@anchor{whatsnew/changelog id232}@anchor{1a47}
@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{1a48,,asyncio.Protocol.data_received()} receives an
immutable @ref{192,,bytes} object (as documented), instead of
@ref{343,,bytearray}.

@item 
bpo-43984@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43984}: @ref{1a49,,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{2c0,,OSError}.
@end itemize

@node macOS<16>,Tools/Demos<21>,Windows<24>,Python 3 12 0 alpha 4
@anchor{whatsnew/changelog id233}@anchor{1a4a}
@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<21>,C API<25>,macOS<16>,Python 3 12 0 alpha 4
@anchor{whatsnew/changelog id234}@anchor{1a4b}
@subsubsection Tools/Demos



@itemize -

@item 
bpo-45256@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45256}: Fix a bug that caused an @ref{5e8,,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<25>,,Tools/Demos<21>,Python 3 12 0 alpha 4
@anchor{whatsnew/changelog id235}@anchor{1a4c}
@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{791,,Py_CLEAR}, @ref{792,,Py_SETREF} and
@ref{793,,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{1a4d}
@subsection Python 3.12.0 alpha 3


`Release date: 2022-12-06'

@menu
* Security: Security<23>. 
* Core and Builtins: Core and Builtins<28>. 
* Library: Library<29>. 
* Documentation: Documentation<22>. 
* Tests: Tests<24>. 
* Build: Build<27>. 
* Windows: Windows<25>. 
* macOS: macOS<17>. 
* Tools/Demos: Tools/Demos<22>. 
* C API: C API<26>. 

@end menu

@node Security<23>,Core and Builtins<28>,,Python 3 12 0 alpha 3
@anchor{whatsnew/changelog id236}@anchor{1a4e}
@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{76,,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{64,,gc} module
@end itemize

@node Core and Builtins<28>,Library<29>,Security<23>,Python 3 12 0 alpha 3
@anchor{whatsnew/changelog id237}@anchor{1a4f}
@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{780,,PyCode_AddWatcher()} and
@ref{781,,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{4cd,,ExceptionGroup} subclass can wrap a
@ref{7d0,,BaseException}.

@item 
gh-99547@footnote{https://github.com/python/cpython/issues/99547}: Add a function to os.path to check if a path is a junction:
isjunction. Add similar functionality to pathlib.Path as is_junction.

@item 
gh-99370@footnote{https://github.com/python/cpython/issues/99370}: Fix zip path for venv created from a non-installed python on
POSIX platforms.

@item 
gh-99377@footnote{https://github.com/python/cpython/issues/99377}: Add audit events for thread creation and clear operations.

@item 
gh-98686@footnote{https://github.com/python/cpython/issues/98686}: Remove the @code{BINARY_OP_GENERIC} and @code{COMPARE_OP_GENERIC}
"specializations".

@item 
gh-99298@footnote{https://github.com/python/cpython/issues/99298}: Remove the remaining error paths for attribute specializations,
and refuse to specialize attribute accesses on types that haven't had
@ref{97a,,PyType_Ready()} called on them yet.

@item 
gh-99127@footnote{https://github.com/python/cpython/issues/99127}: Allow some features of @ref{e2,,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{b34,,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{2eb,,ValueError} instead of @ref{78e,,SystemError} when
methods of uninitialized @ref{198f,,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{1510,,io.FileIO} when the
opener returns an invalid file descriptor.
@end itemize

@node Library<29>,Documentation<22>,Core and Builtins<28>,Python 3 12 0 alpha 3
@anchor{whatsnew/changelog id238}@anchor{1a50}
@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{6f4,,typing.dataclass_transform()}.

@item 
gh-79033@footnote{https://github.com/python/cpython/issues/79033}: Fix @ref{1990,,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{2b3,,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{2f2,,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{1a51,,ast.increment_lineno()} to also cover
@ref{1a52,,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{483,,TypeVarTuple} and one or more
@ref{481,,TypeVar}.

@item 
gh-99379@footnote{https://github.com/python/cpython/issues/99379}: Fix substitution of @ref{482,,ParamSpec} followed by
@ref{483,,TypeVarTuple} in generic aliases.

@item 
gh-99344@footnote{https://github.com/python/cpython/issues/99344}: Fix substitution of @ref{483,,TypeVarTuple} and
@ref{482,,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{2e,,ctypes}.

@item 
gh-99201@footnote{https://github.com/python/cpython/issues/99201}: Fix @ref{1729,,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{2fc,,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{2f1,,asyncio.get_event_loop()} and many other @ref{b,,asyncio}
functions like @ref{e6c,,asyncio.ensure_future()}, @ref{c5c,,asyncio.shield()} or
@ref{80c,,asyncio.gather()}, and also the
@code{get_event_loop()} method of
@code{asyncio.BaseDefaultEventLoopPolicy} now raise a
@ref{244,,RuntimeError} if called when there is no running event loop and the
current event loop was not set. Previously they implicitly created and set
a new current event loop. @ref{1a3,,DeprecationWarning} is no longer emitted
if there is no running event loop but the current event loop was set.

@item 
gh-97966@footnote{https://github.com/python/cpython/issues/97966}: On @code{uname_result}, restored expectation that @code{_fields} and
@code{_asdict} would include all six properties including @code{processor}.

@item 
gh-98248@footnote{https://github.com/python/cpython/issues/98248}: Provide informative error messages in @ref{1477,,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{1916,,is_private} properties in the
@ref{84,,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{1a53,,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{d06,,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{e8a,,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<22>,Tests<24>,Library<29>,Python 3 12 0 alpha 3
@anchor{whatsnew/changelog id239}@anchor{1a54}
@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{3c1,,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{f93,,os.wait*} family of functions, and improved the docs for
@ref{f94,,os.waitid()} with more explanation of the possible argument
constants.
@end itemize

@node Tests<24>,Build<27>,Documentation<22>,Python 3 12 0 alpha 3
@anchor{whatsnew/changelog id240}@anchor{1a55}
@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<27>,Windows<25>,Tests<24>,Python 3 12 0 alpha 3
@anchor{whatsnew/changelog id241}@anchor{1a56}
@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<25>,macOS<17>,Build<27>,Python 3 12 0 alpha 3
@anchor{whatsnew/changelog id242}@anchor{1a57}
@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{497,,sys.version} and @code{sys._git} on
Windows

@item 
gh-99442@footnote{https://github.com/python/cpython/issues/99442}: Fix handling in @ref{7d3,,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{1927,,multiprocessing.shared_memory.SharedMemory} on Windows.
@end itemize

@node macOS<17>,Tools/Demos<22>,Windows<25>,Python 3 12 0 alpha 3
@anchor{whatsnew/changelog id243}@anchor{1a58}
@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<22>,C API<26>,macOS<17>,Python 3 12 0 alpha 3
@anchor{whatsnew/changelog id244}@anchor{1a59}
@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<26>,,Tools/Demos<22>,Python 3 12 0 alpha 3
@anchor{whatsnew/changelog id245}@anchor{1a5a}
@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{658,,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{1a5b,,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{7a9,,T_OBJECT}, @ref{7ab,,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{1a5c}
@subsection Python 3.12.0 alpha 2


`Release date: 2022-11-14'

@menu
* Security: Security<24>. 
* Core and Builtins: Core and Builtins<29>. 
* Library: Library<30>. 
* Documentation: Documentation<23>. 
* Tests: Tests<25>. 
* Build: Build<28>. 
* Windows: Windows<26>. 
* macOS: macOS<18>. 
* C API: C API<27>. 

@end menu

@node Security<24>,Core and Builtins<29>,,Python 3 12 0 alpha 2
@anchor{whatsnew/changelog id246}@anchor{1a5d}
@subsubsection Security



@itemize -

@item 
gh-98433@footnote{https://github.com/python/cpython/issues/98433}: The IDNA codec decoder used on DNS hostnames by @ref{d1,,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{10e,,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<29>,Library<30>,Security<24>,Python 3 12 0 alpha 2
@anchor{whatsnew/changelog id247}@anchor{1a5e}
@subsubsection Core and Builtins



@itemize -

@item 
gh-81057@footnote{https://github.com/python/cpython/issues/81057}: The docs clearly say that @code{PyImport_Inittab},
@ref{1a5f,,PyImport_AppendInittab()}, and @ref{1a60,,PyImport_ExtendInittab()}
should not be used after @ref{45e,,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{988,,PyThreadState} and
@ref{ab1,,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{1ac,,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{5c,,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{18e,,SyntaxError} for a @ref{8f0,,try} block
with both @ref{1ab,,except} and @ref{1ac,,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{1a61,,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{450,,NameError} exceptions for
instances. Now if a @ref{450,,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{1ae,,SyntaxWarning}, instead of
@ref{1a3,,DeprecationWarning}. In a future Python version they will be
eventually a @ref{18e,,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{1ae,,SyntaxWarning}, instead of
@ref{1a3,,DeprecationWarning}.  For example, @code{re.compile("\d+\.\d+")} now
emits a @ref{1ae,,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{18e,,SyntaxError} will eventually be raised,
instead of @ref{1ae,,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{18e,,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{481,,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{1a0d,,FOR_ITER} for generators. Saves
multiple layers of dispatch and checking to get from the
@ref{1a0d,,FOR_ITER} instruction in the caller to the @ref{5b3,,RESUME} in
the generator.

@item 
gh-98762@footnote{https://github.com/python/cpython/issues/98762}: Fix source locations of @ref{a07,,match} sub-patterns.

@item 
gh-98586@footnote{https://github.com/python/cpython/issues/98586}: Added the methods @ref{777,,PyObject_Vectorcall()} and
@ref{778,,PyObject_VectorcallMethod()} to the @ref{76e,,Limited API}
along with the auxiliary macro constant
@ref{779,,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{16df,,__slots__}) could behave incorrectly or crash instead of
raising a @ref{198,,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{4d2,,RuntimeWarning} and assign
@ref{87e,,None} to any fast locals that are left unbound after jumps or
@ref{1a62,,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{1229,,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{1a63,,RETURN_VALUE}, @ref{5b2,,YIELD_VALUE}, and
@ref{903,,RETURN_GENERATOR}, which now clear the frame.

@item 
gh-98415@footnote{https://github.com/python/cpython/issues/98415}: Fix detection of MAC addresses for @ref{116,,uuid} on certain OSs.
Patch by Chaim Sanders

@item 
gh-98686@footnote{https://github.com/python/cpython/issues/98686}: Quicken all code objects, and specialize adaptive bytecode
instructions more aggressively.

@item 
gh-92119@footnote{https://github.com/python/cpython/issues/92119}: Print exception class name instead of its string representation
when raising errors from @ref{2e,,ctypes} calls.

@item 
gh-91058@footnote{https://github.com/python/cpython/issues/91058}: @ref{653,,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{1a0d,,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{1a64,,ETH_P_ALL} and some of the
@ref{1a65,,ETHERTYPE_* constants} in @ref{d1,,socket}.
Patch by Noam Cohen.

@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.
@end itemize

@node Library<30>,Documentation<23>,Core and Builtins<29>,Python 3 12 0 alpha 2
@anchor{whatsnew/changelog id248}@anchor{1a66}
@subsubsection Library



@itemize -

@item 
gh-99418@footnote{https://github.com/python/cpython/issues/99418}: Fix bug in @ref{360,,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{1a67,,secrets.token_hex()}.

@item 
gh-74044@footnote{https://github.com/python/cpython/issues/74044}: Fixed bug where @ref{22f,,inspect.signature()} reported incorrect
arguments for decorated methods.

@item 
gh-99275@footnote{https://github.com/python/cpython/issues/99275}: Fix @code{SystemError} in @ref{2e,,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{c24,,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{bec,,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{104,,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{1a68,,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{104,,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{be,,re} module which in very rare
circumstances prevented compilation of a regular expression containing a
@ref{1a69,,conditional expression} without the
"else" branch.

@item 
gh-98703@footnote{https://github.com/python/cpython/issues/98703}: Fix @ref{1a6a,,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{4b9,,array.array} class now supports subscripting, making
it a @ref{1a1,,generic type}.

@item 
gh-98284@footnote{https://github.com/python/cpython/issues/98284}: Improved @ref{198,,TypeError} message for undefined abstract
methods of a @ref{1115,,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{59b,,path-like objects} in @code{os.ismount()}.

@item 
gh-94172@footnote{https://github.com/python/cpython/issues/94172}: @ref{62,,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{62,,ftplib}, @ref{78,,imaplib}, @ref{b1,,poplib} and @ref{cf,,smtplib} modules,
and the `key_file', `cert_file' and `check_hostname' parameters from the
@ref{73,,http.client} module, all deprecated since Python 3.6. Use the
`context' parameter (`ssl_context' in @ref{78,,imaplib}) instead. Patch by
Victor Stinner.

@item 
gh-83638@footnote{https://github.com/python/cpython/issues/83638}: Add the @ref{6d6,,autocommit} attribute to
@ref{548,,sqlite3.Connection} and the `autocommit' parameter to
@ref{5a0,,sqlite3.connect()} to control 
@geindex Python Enhancement Proposals; PEP 249
PEP 249@footnote{https://peps.python.org/pep-0249/}-compliant @ref{6d7,,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{174,,sysconfig.get_config_var()} to incorrectly return @ref{87e,,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{189a,,unittest.mock.create_autospec()} after it was sealed with
@ref{d95,,unittest.mock.seal()} function.

@item 
bpo-38523@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38523}: @ref{c15,,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{2fc,,pathlib.PurePath.relative_to()}.

@item 
bpo-36267@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36267}: Fix IndexError in @ref{1bd,,argparse.ArgumentParser} when a
@code{store_true} action is given an explicit argument.
@end itemize

@node Documentation<23>,Tests<25>,Library<30>,Python 3 12 0 alpha 2
@anchor{whatsnew/changelog id249}@anchor{1a6b}
@subsubsection Documentation



@itemize -

@item 
gh-98832@footnote{https://github.com/python/cpython/issues/98832}: Changes wording of docstring for @ref{26e,,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<25>,Build<28>,Documentation<23>,Python 3 12 0 alpha 2
@anchor{whatsnew/changelog id250}@anchor{1a6c}
@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{10a,,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<28>,Windows<26>,Tests<25>,Python 3 12 0 alpha 2
@anchor{whatsnew/changelog id251}@anchor{1a6d}
@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{64f,,--with-system-libmpdec} is passed to @code{configure}. Don't
use vendored @code{libexpat} headers if @ref{1a6e,,--with-system-expat} is
passed to @code{configure}.
@end itemize

@node Windows<26>,macOS<18>,Build<28>,Python 3 12 0 alpha 2
@anchor{whatsnew/changelog id252}@anchor{1a6f}
@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{7d3,,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<18>,C API<27>,Windows<26>,Python 3 12 0 alpha 2
@anchor{whatsnew/changelog id253}@anchor{1a70}
@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<27>,,macOS<18>,Python 3 12 0 alpha 2
@anchor{whatsnew/changelog id254}@anchor{1a71}
@subsubsection C API



@itemize -

@item 
gh-98724@footnote{https://github.com/python/cpython/issues/98724}: The @ref{791,,Py_CLEAR}, @ref{792,,Py_SETREF} and
@ref{793,,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{dc,,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{1a72,,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{782,,PyFrame_GetVar()} and @ref{783,,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{1a73}
@subsection Python 3.12.0 alpha 1


`Release date: 2022-10-25'

@menu
* Security: Security<25>. 
* Core and Builtins: Core and Builtins<30>. 
* Library: Library<31>. 
* Documentation: Documentation<24>. 
* Tests: Tests<26>. 
* Build: Build<29>. 
* Windows: Windows<27>. 
* macOS: macOS<19>. 
* IDLE: IDLE<14>. 
* Tools/Demos: Tools/Demos<23>. 
* C API: C API<28>. 

@end menu

@node Security<25>,Core and Builtins<30>,,Python 3 12 0 alpha 1
@anchor{whatsnew/changelog id255}@anchor{1a74}
@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{1d5,,"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{76,,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<30>,Library<31>,Security<25>,Python 3 12 0 alpha 1
@anchor{whatsnew/changelog id256}@anchor{1a75}
@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{450,,NameError} is raised to the top level. Patch by Pablo Galindo

@item 
gh-97997@footnote{https://github.com/python/cpython/issues/97997}: Add running column offset to the tokenizer state to avoid
calculating AST column information with pointer arithmetic.

@item 
gh-97973@footnote{https://github.com/python/cpython/issues/97973}: Modify the tokenizer to return all necessary information the
parser needs to set location information in the AST nodes, so that the
parser does not have to calculate those doing pointer arithmetic.

@item 
gh-96078@footnote{https://github.com/python/cpython/issues/96078}: @ref{1312,,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{13a,,zoneinfo} to Argument Clinic.

@item 
gh-97912@footnote{https://github.com/python/cpython/issues/97912}: The compiler now avoids quadratic behavior when finding which
instructions should use the @ref{704,,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{1a76,,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{68c,,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{1a77,,./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{3e2,,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{18e,,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{1a78,,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{16f,,-X int_max_str_digits} option with no value (invalid) when the
@geindex PYTHONINTMAXSTRDIGITS
@geindex 環境變數; PYTHONINTMAXSTRDIGITS
@ref{1a79,,PYTHONINTMAXSTRDIGITS} environment variable is set to a valid
limit. Patch by Victor Stinner.

@item 
gh-95921@footnote{https://github.com/python/cpython/issues/95921}: Fix overly-broad source position information for chained
comparisons used as branching conditions.

@item 
gh-96821@footnote{https://github.com/python/cpython/issues/96821}: Fix undefined behaviour in @code{audioop.c}.

@item 
gh-96821@footnote{https://github.com/python/cpython/issues/96821}: Fix undefined behaviour in @code{_testcapimodule.c}.

@item 
gh-95778@footnote{https://github.com/python/cpython/issues/95778}: When @ref{2eb,,ValueError} is raised if an integer is larger than
the limit, mention the @ref{185e,,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{78e,,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{165,,memoryview} now supports half-floats. Patch by Donghee
Na and Antoine Pitrou.

@item 
gh-96678@footnote{https://github.com/python/cpython/issues/96678}: Fix case of undefined behavior in ceval.c

@item 
gh-64373@footnote{https://github.com/python/cpython/issues/64373}: Convert @code{_functools} to argument clinic.

@item 
gh-96641@footnote{https://github.com/python/cpython/issues/96641}: Do not expose @code{KeyWrapper} in @code{_functools}.

@item 
gh-96636@footnote{https://github.com/python/cpython/issues/96636}: Ensure that tracing, @code{sys.setrace()}, is turned on
immediately. In pre-release versions of 3.11, some tracing events might
have been lost when turning on tracing in a @code{__del__} method or
interrupt.

@item 
gh-96572@footnote{https://github.com/python/cpython/issues/96572}: Fix use after free in trace refs build mode. Patch by Kumar
Aditya.

@item 
gh-96611@footnote{https://github.com/python/cpython/issues/96611}: When loading a file with invalid UTF-8 inside a multi-line
string, a correct SyntaxError is emitted.

@item 
gh-96612@footnote{https://github.com/python/cpython/issues/96612}: Make sure that incomplete frames do not show up in tracemalloc
traces.

@item 
gh-90230@footnote{https://github.com/python/cpython/issues/90230}: Fix compiler warnings and test failures when building with
@code{--enable-pystats}.

@item 
gh-96587@footnote{https://github.com/python/cpython/issues/96587}: Correctly raise @code{SyntaxError} on exception groups (
@geindex Python Enhancement Proposals; PEP 654
PEP 654@footnote{https://peps.python.org/pep-0654/})
on python versions prior to 3.11

@item 
gh-96569@footnote{https://github.com/python/cpython/issues/96569}: Remove two cases of undefined behavior, by adding NULL checks.

@item 
gh-96582@footnote{https://github.com/python/cpython/issues/96582}: Fix possible @code{NULL} pointer dereference in
@code{_PyThread_CurrentFrames}. Patch by Kumar Aditya.

@item 
gh-91079@footnote{https://github.com/python/cpython/issues/91079}: Separate Python recursion checking from C recursion checking
which reduces the chance of C stack overflow and allows the recursion
limit to be increased safely.

@item 
gh-93911@footnote{https://github.com/python/cpython/issues/93911}: Fix an issue that could prevent @ref{6fd,,LOAD_ATTR} from
specializing properly when accessing properties.

@item 
gh-96348@footnote{https://github.com/python/cpython/issues/96348}: Emit a DeprecationWarning when @ref{715,,throw()},
@ref{714,,throw()} or @ref{716,,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{5e8,,AttributeError} missing @code{name} and @code{obj}
attributes in @ref{dc6,,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{693,,sys.activate_stack_trampoline()} and
@ref{694,,sys.deactivate_stack_trampoline()} function in the @ref{df,,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{695,,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{642,,PyGILState_Ensure()} when allocating
new thread state. Patch by Kumar Aditya.

@item 
gh-96046@footnote{https://github.com/python/cpython/issues/96046}: @ref{97a,,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{1a7a,,ENOTCAPABLE} is now mapped to
@ref{f39,,PermissionError}. The @ref{5b,,errno} modules exposes the new error
number. @code{getpath.py} now ignores @ref{f39,,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{8f0,,try}/@ref{1ab,,except} blocks to
handle exceptions raised during @ref{19b7,,close()} or
@ref{715,,throw()} calls through a suspended frame.

@item 
gh-95977@footnote{https://github.com/python/cpython/issues/95977}: Optimized calling @ref{16dc,,__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{989,,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{196,,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{24d,,list} from @ref{10a5,,str.split()}
and @ref{1456,,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{16f9,,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{f63,,RecursionError} is
now raised instead. Patch by Pablo Galindo

@item 
gh-93351@footnote{https://github.com/python/cpython/issues/93351}: @ref{4be,,ast.AST} node positions are now validated when provided
to @ref{4ac,,compile()} and other related functions. If invalid positions are
detected, a @ref{2eb,,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{1a61,,EXTENDED_ARG} instructions in unquickened code. Consumers of
non-adaptive bytecode should be able to handle extended arguments the same
way they were handled in CPython 3.10 and older.

@item 
gh-91409@footnote{https://github.com/python/cpython/issues/91409}: Fix incorrect source location info caused by certain
optimizations in the bytecode compiler.

@item 
gh-95023@footnote{https://github.com/python/cpython/issues/95023}: Implement @ref{1a7b,,os.setns()} and  @ref{1a7c,,os.unshare()} for Linux.
Patch by Noam Cohen.

@item 
gh-94036@footnote{https://github.com/python/cpython/issues/94036}: Fix incorrect source location info for some multi-line attribute
accesses and method calls.

@item 
gh-94938@footnote{https://github.com/python/cpython/issues/94938}: Fix error detection in some builtin functions when keyword
argument name is an instance of a str subclass with overloaded @code{__eq__}
and @code{__hash__}. Previously it could cause SystemError or other undesired
behavior.

@item 
gh-94996@footnote{https://github.com/python/cpython/issues/94996}: @ref{1c2,,ast.parse()} will no longer parse function definitions with
positional-only params when passed @code{feature_version} less than @code{(3,
8)}. Patch by Shantanu Jain.

@item 
gh-94739@footnote{https://github.com/python/cpython/issues/94739}: Allow jumping within, out of, and across exception handlers in
the debugger.

@item 
gh-94949@footnote{https://github.com/python/cpython/issues/94949}: @ref{1c2,,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{1c2,,ast.parse()} will no longer parse assignment expressions
when passed @code{feature_version} less than @code{(3, 8)}. Patch by Shantanu
Jain.

@item 
gh-91256@footnote{https://github.com/python/cpython/issues/91256}: Ensures the program name is known for help text during
interpreter startup.

@item 
gh-94869@footnote{https://github.com/python/cpython/issues/94869}: Fix the column offsets for some expressions in multi-line
f-strings @ref{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{343,,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{691,,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{6fe,,BINARY_SLICE} and @ref{6ff,,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{9e5,,types.GenericAlias} no longer relays the @code{__class__}
attribute. For example, @code{isinstance(list[int], type)} no longer returns
@code{True}.

@item 
gh-93678@footnote{https://github.com/python/cpython/issues/93678}: Refactor the compiler to reduce boilerplate and repetition.

@item 
gh-93671@footnote{https://github.com/python/cpython/issues/93671}: Fix some exponential backtrace case happening with deeply nested
sequence patterns in match statements. Patch by Pablo Galindo

@item 
gh-93662@footnote{https://github.com/python/cpython/issues/93662}: Make sure that the end column offsets are correct in multi-line
method calls. Previously, the end column could precede the column offset.

@item 
gh-93461@footnote{https://github.com/python/cpython/issues/93461}: @ref{e05,,importlib.invalidate_caches()} now drops entries from
@ref{7f3,,sys.path_importer_cache} with a relative path as name. This solves
a caching issue when a process changes its current working directory.

@code{FileFinder} no longer inserts a dot in the path, e.g. @code{/egg/./spam}
is now @code{/egg/spam}.

@item 
gh-93621@footnote{https://github.com/python/cpython/issues/93621}: Change order of bytecode instructions emitted for
@ref{186,,with} and @ref{185,,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{974,,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{76b,,PyType_FromMetaclass()}, which
generalizes the existing @ref{76c,,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{76b,,PyType_FromMetaclass()} is available in the Limited
API, which provides a path towards migrating more binding tools onto the
Stable ABI.

@item 
gh-93021@footnote{https://github.com/python/cpython/issues/93021}: Fix the @code{__text_signature__} for @code{__get__()} methods
implemented in C. Patch by Jelle Zijlstra.

@item 
gh-89914@footnote{https://github.com/python/cpython/issues/89914}: The operand of the @code{YIELD_VALUE} instruction is set to the
stack depth. This is done to help frame handling on @code{yield} and may
assist debuggers.

@item 
gh-92955@footnote{https://github.com/python/cpython/issues/92955}: Fix memory leak in code object's lines and positions iterators
as they were not finalized at exit. Patch by Kumar Aditya.

@item 
gh-92930@footnote{https://github.com/python/cpython/issues/92930}: Fixed a crash in @code{_pickle.c} from mutating collections during
@code{__reduce__} or @code{persistent_id}.

@item 
gh-90690@footnote{https://github.com/python/cpython/issues/90690}: The PRECALL instruction has been removed. It offered only a
small advantage for specialization and is not needed in the vast majority
of cases.

@item 
gh-92914@footnote{https://github.com/python/cpython/issues/92914}: Always round the allocated size for lists up to the nearest even
number.

@item 
gh-92858@footnote{https://github.com/python/cpython/issues/92858}: Improve error message for some suites with syntax error before
':'

@item 
gh-90473@footnote{https://github.com/python/cpython/issues/90473}: Decrease default recursion limit on WASI to address limited call
stack size.

@item 
gh-92804@footnote{https://github.com/python/cpython/issues/92804}: Fix memory leak in @code{memoryview} iterator as it was not
finalized at exit. Patch by Kumar Aditya.

@item 
gh-92777@footnote{https://github.com/python/cpython/issues/92777}: Specialize @code{LOAD_METHOD} for objects with lazy dictionaries.
Patch by Ken Jin.

@item 
gh-92658@footnote{https://github.com/python/cpython/issues/92658}: Add support for connecting and binding to Hyper-V sockets on
Windows Hyper-V hosts and guests.

@item 
gh-92236@footnote{https://github.com/python/cpython/issues/92236}: Remove spurious "LINE" event when starting a generator or
coroutine, visible tracing functions implemented in C.

@item 
gh-91102@footnote{https://github.com/python/cpython/issues/91102}: @code{_warnings.warn_explicit()} is ported to Argument Clinic.

@item 
gh-92619@footnote{https://github.com/python/cpython/issues/92619}: Make the compiler duplicate an exit block only if none of its
instructions have a lineno (previously only the first instruction in the
block was checked, leading to unnecessarily duplicated blocks).

@item 
gh-88750@footnote{https://github.com/python/cpython/issues/88750}: The deprecated debug build only @code{PYTHONTHREADDEBUG}
environment variable no longer does anything.

@item 
gh-92261@footnote{https://github.com/python/cpython/issues/92261}: Fix hang when trying to iterate over a @code{typing.Union}.

@item 
gh-91432@footnote{https://github.com/python/cpython/issues/91432}: Specialized the @ref{1a0d,,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{24d,,list} and
@ref{60c,,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<31>,Documentation<24>,Core and Builtins<30>,Python 3 12 0 alpha 1
@anchor{whatsnew/changelog id257}@anchor{1a7d}
@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{816,,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{343,,bytearray} and @ref{165,,memoryview} types: only the exact
@ref{192,,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{864,,createSocket()} method
was added to @ref{865,,SysLogHandler}.

@item 
gh-96035@footnote{https://github.com/python/cpython/issues/96035}: Fix bug in @ref{360,,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{16f2,,sys.setprofile()} and @ref{2e1,,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{117,,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{75b,,syslog.syslog()} in multi-threaded
applications. On macOS, the libc @code{syslog()} function is not thread-safe,
so @ref{75b,,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{514,,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{81,,importlib.util}.

@item 
gh-97837@footnote{https://github.com/python/cpython/issues/97837}: Change deprecate warning message in @ref{10c,,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{5e8,,AttributeError} when @ref{11bd,,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{450,,NameError} and @ref{5e8,,AttributeError} spelling suggestions
provided since gh-82711@footnote{https://github.com/python/cpython/issues/82711} are now also emitted by the pure Python
@ref{104,,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{a0d,,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{187c,,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{e3,,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{1a7e,,process_exited()} called before the
@ref{1a7f,,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{1a80,,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{10b,,unicodedata} database to Unicode 15.0.0.

@item 
gh-96735@footnote{https://github.com/python/cpython/issues/96735}: Fix undefined behaviour in @ref{17da,,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{14bf,,numbers.Rational}'s to
@ref{196,,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{10a,,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{f9c,,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{82,,inspect}, fix overeager replacement of "@code{typing.}" in
formatting annotations.

@item 
gh-89258@footnote{https://github.com/python/cpython/issues/89258}: Added a @ref{1a81,,getChildren()} method to
@ref{d3e,,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{128,,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{1a82,,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{1a83,,strftime() 與 strptime() 的行為}.

@item 
gh-95899@footnote{https://github.com/python/cpython/issues/95899}: Fix @ref{2f4,,asyncio.Runner} to call
@ref{1a84,,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{35f,,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{1a80,,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{4cf,,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{af3,,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{4cc,,asyncio.TaskGroup} to propagate exception when
@ref{4cf,,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{6c6,,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{180b,,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{1a85,,EPERM} or
@ref{1a86,,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{2f2,,asyncio.run()} for @ref{1c7,,asyncio.Task}
implementations without @ref{4d1,,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{3f,,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{1a87,,os.EFD_CLOEXEC},
@ref{1a88,,os.EFD_NONBLOCK} and @ref{1a89,,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{1dc,,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{d4,,sqlite3} regression where @code{*args} and @code{**kwds}
were incorrectly relayed from @ref{5a0,,connect()} to the
@ref{548,,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{5f,,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{1991,,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{1c2,,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{d4,,sqlite3} @ref{66c,,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{f5,,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{1a6a,,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{104,,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{710,,typing.Hashable} and
@ref{711,,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{10a,,typing}. Previously an error message saying @code{Some type variables
... are not listed in Generic[...]} was shown. @ref{10a,,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{7b,,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{2f2,,asyncio.run()} and
@ref{35f,,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{1979,,struct.Struct} when it was not completely
initialized by initializing it in @ref{799,,__new__()}.  Patch by Kumar
Aditya.

@item 
gh-94510@footnote{https://github.com/python/cpython/issues/94510}: Re-entrant calls to @ref{16f2,,sys.setprofile()} and
@ref{2e1,,sys.settrace()} now raise @ref{244,,RuntimeError}. Patch by Pablo
Galindo.

@item 
gh-92336@footnote{https://github.com/python/cpython/issues/92336}: Fix bug where @ref{240,,linecache.getline()} fails on bad files with
@ref{bff,,UnicodeDecodeError} or @ref{18e,,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{4cc,,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{750,,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{138,,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{757,,shlex.split()}: Passing @code{None} for `s' argument now
raises an exception, rather than reading @ref{758,,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{ba,,pydoc} text output.

@item 
gh-89988@footnote{https://github.com/python/cpython/issues/89988}: Fix memory leak in @ref{c0a,,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{d4,,sqlite3} @ref{70d,,default adapters and converters}. Patch by Erlend E. Aasland.

@item 
gh-94254@footnote{https://github.com/python/cpython/issues/94254}: Fixed types of @ref{db,,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{6d3,,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{3c,,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{73b,,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{355,,ssl.SSLContext} object and call its
@ref{741,,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{73f,,os.urandom()} or @ref{740,,ssl.RAND_bytes()} instead.
Patch by Victor Stinner.

@item 
gh-94199@footnote{https://github.com/python/cpython/issues/94199}: @ref{6c,,hashlib}: Remove the pure Python implementation of
@ref{72c,,hashlib.pbkdf2_hmac()}, deprecated in Python 3.10. Python 3.10 and
newer requires OpenSSL 1.1.1 (
@geindex Python Enhancement Proposals; PEP 644
PEP 644@footnote{https://peps.python.org/pep-0644/}): this OpenSSL version provides a
C implementation of @ref{72c,,pbkdf2_hmac()} which is faster. Patch by
Victor Stinner.

@item 
gh-94196@footnote{https://github.com/python/cpython/issues/94196}: @ref{6b,,gzip}: Remove the @code{filename} attribute of
@ref{654,,gzip.GzipFile}, deprecated since Python 2.6, use the
@ref{72a,,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{315,,open()} instead. The @ref{315,,open()}
(@ref{739,,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{ed4,,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{30c,,inspect.iscoroutinefunction()},
@ref{1a8a,,inspect.isgeneratorfunction()}, and
@ref{1a8b,,inspect.isasyncgenfunction()} now properly return @code{True} for
duck-typed function-like objects like instances of
@ref{c35,,unittest.mock.AsyncMock}.

This makes @ref{30c,,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{d4,,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{82e,,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{be,,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{e6,,tempfile}.

@item 
gh-93820@footnote{https://github.com/python/cpython/issues/93820}: Fixed a regression when @ref{750,,copy.copy()}-ing @ref{82e,,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{11a,,weakref} classes
@ref{1a8c,,ReferenceType}, @ref{1a8d,,ProxyType},
@ref{1a8e,,CallableProxyType}. It makes them pickleable.

@item 
gh-91389@footnote{https://github.com/python/cpython/issues/91389}: Fix an issue where @ref{3c,,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{750,,copy.copy()} and @ref{d5d,,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{d4,,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{1a8f,,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{5d,,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{6ae,,importlib.resources.as_file()} context manager to
remove the temporary file if destroyed late during Python finalization:
keep a local reference to the @ref{12f1,,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{6bb,,os.PIDFD_NONBLOCK} flag to open a file descriptor
for a process with @ref{69d,,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{198,,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{1bd,,argparse.ArgumentParser} to use
@ref{756,,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{a1a,,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{13b1,,logging.config.dictConfig()} to
usefully configure @ref{1a90,,QueueHandler} and
@ref{242,,QueueListener} as a pair, and add
@ref{1a91,,logging.getHandlerByName()} and @ref{19c0,,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{c5f,,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{8b,,logging} module for use
with @ref{b,,asyncio} tasks.

@item 
gh-74696@footnote{https://github.com/python/cpython/issues/74696}: @ref{6d3,,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{60,,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{5a0,,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{ad9,,ast.unparse()} when @code{ImportFrom.level} is @code{None}

@item 
gh-92932@footnote{https://github.com/python/cpython/issues/92932}: Now @ref{205,,dis()} and @ref{4e7,,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{266,,pathlib.Path} arguments in addition to @ref{169,,str} paths. Patch
by David Foster.

@item 
gh-87901@footnote{https://github.com/python/cpython/issues/87901}: Removed the @code{encoding} argument from @ref{319,,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{1a92,,c_time_t} to @ref{2e,,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{dc,,subprocess} now fails early on Emscripten and WASI
platforms to work around missing @ref{1a93,,os.pipe()} on WASI.

@item 
gh-89325@footnote{https://github.com/python/cpython/issues/89325}: Removed many old deprecated @ref{10c,,unittest} features:
@ref{2b3,,TestCase} method aliases, undocumented and broken
@ref{2b3,,TestCase} method @code{assertDictContainsSubset},
undocumented @ref{58e,,TestLoader.loadTestsFromModule} parameter `use_load_tests', and
an underscored alias of the @ref{74d,,TextTestResult} class.

@item 
gh-92734@footnote{https://github.com/python/cpython/issues/92734}: Allow multi-element reprs emitted by @ref{c0,,reprlib} to be
pretty-printed using configurable indentation.

@item 
gh-92671@footnote{https://github.com/python/cpython/issues/92671}: Fixed @ref{ad9,,ast.unparse()} for empty tuples in the assignment
target context.

@item 
gh-91581@footnote{https://github.com/python/cpython/issues/91581}: @ref{350,,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{1a94,,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{6c8,,pathlib.Path.walk()} as an alternative to
@ref{6c9,,os.walk()}.

@item 
gh-92550@footnote{https://github.com/python/cpython/issues/92550}: Fix @ref{533,,pathlib.Path.rglob()} for empty pattern.

@item 
gh-92591@footnote{https://github.com/python/cpython/issues/92591}: Allow @ref{8b,,logging} filters to return a
@ref{11e1,,logging.LogRecord} instance so that filters attached to
@ref{168a,,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{d4,,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{1a95,,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{266,,pathlib.Path} deprecated method @code{link_to} has been
removed. Use 3.10's @ref{a1b,,hardlink_to()} method instead as
its semantics are consistent with that of
@ref{a1c,,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{93b,,__class_getitem__()} to
@ref{bcf,,csv.DictReader} and @ref{13ff,,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{d1,,socket}.

@item 
gh-91810@footnote{https://github.com/python/cpython/issues/91810}: @ref{b3e,,ElementTree} method
@ref{c83,,write()} and function
@ref{11f0,,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{dea,,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{1d6,,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{70b,,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{59d,,re.sub()} and @ref{59e,,re.subn()} and corresponding @ref{1a96,,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{8cb,,zipfile.ZipFile} now raises @ref{1a97,,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{4ae,,property()}.

@item 
gh-90005@footnote{https://github.com/python/cpython/issues/90005}: @ref{2e,,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{13ff,,DictWriter} and
@ref{bcf,,DictReader} now coerce the @code{fieldnames} argument to a
@ref{24d,,list} if it is an iterator.

@item 
bpo-35540@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35540}: Fix @ref{19e4,,dataclasses.asdict()} crash when
@ref{13bd,,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{192,,bytes} on @ref{3e2,,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{c03,,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{acb,,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{481,,typing.TypeVar}, @ref{482,,typing.ParamSpec},
@ref{483,,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{175d,,doctest.DocTest.lineno} to @code{None} when an object
does not have @ref{b18,,__doc__}.

@item 
bpo-46197@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46197}: Fix @ref{59,,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{10c,,unittest}: methods
@ref{8c0,,enterContext()} and
@ref{8c1,,enterClassContext()} of class
@ref{2b3,,TestCase}, method
@ref{8c2,,enterAsyncContext()} of class
@ref{35f,,IsolatedAsyncioTestCase} and function
@ref{8c3,,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{c29,,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{6e6,,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{13be,,__missing__()} when a value is not found. This matches the
behavior of @ref{183,,dict}. Patch by Bar Harel.

@item 
bpo-38693@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38693}: @ref{7b,,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{adb,,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{2f4,,asyncio.Runner} or @ref{2f2,,asyncio.run()}, the
default timeout is 5 minutes.

@item 
bpo-34828@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34828}: @ref{54a,,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{119,,wave} module.

@item 
bpo-26253@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26253}: Allow adjustable compression level for tarfile streams in
@ref{1072,,tarfile.open()}.
@end itemize

@node Documentation<24>,Tests<26>,Library<31>,Python 3 12 0 alpha 1
@anchor{whatsnew/changelog id258}@anchor{1a98}
@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{e0d,,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{1a99,,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{1a9a,,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{d4,,sqlite3} behavior when
@ref{1a9b,,How to use the connection context manager}.

@item 
gh-87260@footnote{https://github.com/python/cpython/issues/87260}: Align @ref{d4,,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{abc,,-W} and 
@geindex PYTHONWARNINGS
@geindex 環境變數; PYTHONWARNINGS
@ref{d9e,,PYTHONWARNINGS} are
matched literally and case-insensitively, rather than as regular
expressions, in @ref{118,,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{6c6,,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{be4,,inspect.getdoc()},
@ref{1a9c,,inspect.getmodule()}, and @ref{1a9d,,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{1a9e,,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<26>,Build<29>,Documentation<24>,Python 3 12 0 alpha 1
@anchor{whatsnew/changelog id259}@anchor{1a9f}
@subsubsection Tests



@itemize -

@item 
gh-95027@footnote{https://github.com/python/cpython/issues/95027}: On Windows, when the Python test suite is run with the @code{-jN}
option, the ANSI code page is now used as the encoding for the stdout
temporary file, rather than using UTF-8 which can lead to decoding errors.
Patch by Victor Stinner.

@item 
gh-96624@footnote{https://github.com/python/cpython/issues/96624}: Fixed the failure of repeated runs of @code{test.test_unittest}
caused by side effects in @code{test_dotted_but_module_not_loaded}.

@item 
gh-95243@footnote{https://github.com/python/cpython/issues/95243}: Mitigate the inherent race condition from using
find_unused_port() in testSockName() by trying to find an unused port a
few times before failing. Patch by Ross Burton.

@item 
gh-95573@footnote{https://github.com/python/cpython/issues/95573}: Lib/test/test_asyncio/test_ssl.py@footnote{https://github.com/python/cpython/tree/3.14/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{1aa0,,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{be,,re} exponentional slowdown when
using rjsmin.

@item 
gh-91330@footnote{https://github.com/python/cpython/issues/91330}: Added more tests for @ref{33,,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{1aa1,,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{1aa2,,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{1a26,,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{524,,os.chmod()} is
now a dummy function on WASI. Skip all tests that depend on working
@ref{524,,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<29>,Windows<27>,Tests<26>,Python 3 12 0 alpha 1
@anchor{whatsnew/changelog id260}@anchor{1aa3}
@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{10d,,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{c1,,resource}
module, @ref{1516,,getresuid()}, @ref{1515,,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{5b,,errno}, @ref{c6,,select}, and @ref{d1,,socket}
constants.

@item 
gh-95174@footnote{https://github.com/python/cpython/issues/95174}: Python now skips missing @ref{d1,,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{e5a,,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{bf,,readline} and @ref{2f,,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<27>,macOS<19>,Build<29>,Python 3 12 0 alpha 1
@anchor{whatsnew/changelog id261}@anchor{1aa4}
@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
@ref{98,,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{1652,,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{7d3,,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{a38,,enable_load_extension()}
@ref{d4,,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{7d3,,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{7d3,,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{7d3,,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{137,,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{1303,,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{1aa5,,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<19>,IDLE<14>,Windows<27>,Python 3 12 0 alpha 1
@anchor{whatsnew/changelog id262}@anchor{1aa6}
@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{f8b,,os.mkfifo()} or @ref{f8c,,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<14>,Tools/Demos<23>,macOS<19>,Python 3 12 0 alpha 1
@anchor{whatsnew/changelog id263}@anchor{1aa7}
@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<23>,C API<28>,IDLE<14>,Python 3 12 0 alpha 1
@anchor{whatsnew/changelog id264}@anchor{1aa8}
@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<28>,,Tools/Demos<23>,Python 3 12 0 alpha 1
@anchor{whatsnew/changelog id266}@anchor{1aa9}
@subsubsection C API



@itemize -

@item 
gh-98393@footnote{https://github.com/python/cpython/issues/98393}: The @ref{790,,PyUnicode_FSDecoder()} function no longer accepts
bytes-like paths, like @ref{343,,bytearray} and @ref{165,,memoryview} types:
only the exact @ref{192,,bytes} type is accepted for bytes strings. Patch by
Victor Stinner.

@item 
gh-91051@footnote{https://github.com/python/cpython/issues/91051}: Add @ref{77f,,PyType_Watch()} and related APIs to allow callbacks
on @ref{1aaa,,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{804,,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{607,,Py_TPFLAGS_MANAGED_DICT}
and @ref{775,,Py_TPFLAGS_MANAGED_WEAKREF} instead.

@item 
gh-95781@footnote{https://github.com/python/cpython/issues/95781}: An unrecognized format character in
@ref{623,,PyUnicode_FromFormat()} and @ref{78d,,PyUnicode_FromFormatV()} now
sets a @ref{78e,,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{76f,,Py_TPFLAGS_HAVE_VECTORCALL}, @ref{770,,PyVectorcall_NARGS()} and
@ref{771,,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{623,,PyUnicode_FromFormat()} and @ref{78d,,PyUnicode_FromFormatV()}. Patch
by Philip Georgi.

@item 
gh-93012@footnote{https://github.com/python/cpython/issues/93012}: The @ref{76f,,Py_TPFLAGS_HAVE_VECTORCALL} flag is now removed
from a class when the class's @ref{773,,__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{774,,tp_call} now inherit the
@ref{76f,,Py_TPFLAGS_HAVE_VECTORCALL} flag.

@item 
gh-95388@footnote{https://github.com/python/cpython/issues/95388}: Creating @ref{3cd,,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{975,,PyCode_GetVarnames()}, @ref{976,,PyCode_GetCellvars()}
and @ref{977,,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{61c,,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{980,,PyFrame_Check()}

@item 
@ref{981,,PyFrame_GetBack()}

@item 
@ref{967,,PyFrame_GetBuiltins()}

@item 
@ref{968,,PyFrame_GetGenerator()}

@item 
@ref{969,,PyFrame_GetGlobals()}

@item 
@ref{96a,,PyFrame_GetLasti()}

@item 
@ref{659,,PyFrame_GetLocals()}

@item 
@ref{982,,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{76b,,PyType_FromMetaclass()} (and other @code{PyType_From*}
functions) now check that offsets and the base class's
@ref{b75,,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{77a,,PyEval_SetProfileAllThreads()} and
@ref{65c,,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{f3,,threading} module
(@ref{6e9,,threading.setprofile_all_threads()} and
@ref{6e8,,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{408,,Py_IgnoreEnvironmentFlag}, in the documentation: the
@ref{3f5,,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{408,,Py_IgnoreEnvironmentFlag}: the @ref{3f5,,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{63b,,PyConfig.module_search_paths} are
ignored unless @ref{7fe,,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{77b,,PyFunction_SetVectorcall()} to the C API
which sets the vectorcall field of a given @ref{77c,,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{796,,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{1aab}
@subsection Python 3.11.0 beta 1


`Release date: 2022-05-06'

@menu
* Security: Security<26>. 
* Core and Builtins: Core and Builtins<31>. 
* Library: Library<32>. 
* Documentation: Documentation<25>. 
* Tests: Tests<27>. 
* Build: Build<30>. 
* Windows: Windows<28>. 
* macOS: macOS<20>. 
* Tools/Demos: Tools/Demos<24>. 
* C API: C API<29>. 

@end menu

@node Security<26>,Core and Builtins<31>,,Python 3 11 0 beta 1
@anchor{whatsnew/changelog id267}@anchor{1aac}
@subsubsection Security



@itemize -

@item 
gh-57684@footnote{https://github.com/python/cpython/issues/57684}: Add the @ref{7ba,,-P} command line option and the
@geindex PYTHONSAFEPATH
@geindex 環境變數; PYTHONSAFEPATH
@ref{7bb,,PYTHONSAFEPATH} environment variable to not prepend a potentially
unsafe path to @ref{3e2,,sys.path}. Patch by Victor Stinner.
@end itemize

@node Core and Builtins<31>,Library<32>,Security<26>,Python 3 11 0 beta 1
@anchor{whatsnew/changelog id268}@anchor{1aad}
@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{5e8,,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{49d,,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{2a7,,types.UnionType} instantiation. Based on patch
provided by Yurii Karabas.

@item 
gh-89373@footnote{https://github.com/python/cpython/issues/89373}: If Python is built in debug mode, Python now ensures that
deallocator functions leave the current exception unchanged. Patch by
Victor Stinner.

@item 
gh-91632@footnote{https://github.com/python/cpython/issues/91632}: Fix a minor memory leak at exit: release the memory of the
@code{generic_alias_iterator} type. Patch by Donghee Na.

@item 
gh-81548@footnote{https://github.com/python/cpython/issues/81548}: Octal escapes with value larger than @code{0o377} now produce a
@ref{1a3,,DeprecationWarning}. In a future Python version they will be a
@ref{1ae,,SyntaxWarning} and eventually a @ref{18e,,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{2ad,,isinstance()} and @ref{9bd,,issubclass()} checks for
@ref{2a7,,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{984,,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{7d0,,BaseException} (added
in an earlier version of 3.11) with the final design of 
@geindex Python Enhancement Proposals; PEP 678
PEP 678@footnote{https://peps.python.org/pep-0678/}.
Namely, @ref{7d0,,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{19b0,,POP_JUMP_IF_TRUE}, @ref{19b1,,POP_JUMP_IF_FALSE},
@ref{1aae,,POP_JUMP_IF_NONE} and @ref{1aaf,,POP_JUMP_IF_NOT_NONE} virtual,
mapping to new relative jump opcodes.

@item 
bpo-45317@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45317}: Add internal documentation explaining design of new (for 3.11)
frame stack.

@item 
bpo-47197@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47197}: ctypes used to mishandle @code{void} return types, so that for
instance a function declared like @code{ctypes.CFUNCTYPE(None, ctypes.c_int)}
would be called with signature @code{int f(int)} instead of @code{void f(int)}.
Wasm targets require function pointers to be called with the correct
signatures so this led to crashes. The problem is now fixed.

@item 
bpo-47120@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47120}: Make opcodes @code{JUMP_IF_TRUE_OR_POP} and
@code{JUMP_IF_FALSE_OR_POP} relative rather than absolute.

@item 
bpo-47177@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47177}: Replace the @code{f_lasti} member of the internal
@code{_PyInterpreterFrame} structure with a @code{prev_instr} pointer, which
reduces overhead in the main interpreter loop. The @code{f_lasti} attribute
of Python-layer frame objects is preserved for backward-compatibility.

@item 
bpo-46961@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46961}: Integer mod/remainder operations, including the three-argument
form of @ref{1a4,,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{1ab0,,pickle.PickleBuffer}, @code{testcapi.RecursingInfinitelyError},
and @ref{9e5,,types.GenericAlias}.

The functions affected are 24 methods in @ref{2e,,ctypes}.

Patch by Oleg Iarygin.

@item 
bpo-46942@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46942}: Use Argument Clinic for the @ref{1ab1,,types.MethodType}
constructor.  Patch by Oleg Iarygin.

@item 
bpo-46764@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46764}: Fix wrapping bound methods with @@classmethod

@item 
bpo-43464@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43464}: Optimize @code{set.intersection()} for non-set arguments.

@item 
bpo-46721@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46721}: Optimize @code{set.issuperset()} for non-set argument.

@item 
bpo-46509@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46509}: Add type-specialized versions of the @code{Py_DECREF()}, and use
them for @code{float}, @code{int}, @code{str}, @code{bool}, and @code{None} to avoid
pointer-chasing at runtime where types are known at C compile time.

@item 
bpo-46045@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46045}: Do not use POSIX semaphores on NetBSD

@item 
bpo-36819@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36819}: Fix crashes in built-in encoders with error handlers that
return position less or equal than the starting position of non-encodable
characters.

@item 
bpo-34093@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34093}: @code{marshal.dumps()} uses @code{FLAG_REF} for all interned strings.
This makes output more deterministic and helps reproducible build.

@item 
bpo-26579@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26579}: Added @code{object.__getstate__} which provides the default
implementation of the @code{__getstate__()} method.

Copying and pickling instances of subclasses of builtin types bytearray,
set, frozenset, collections.OrderedDict, collections.deque,
weakref.WeakSet, and datetime.tzinfo now copies and pickles instance
attributes implemented as slots.
@end itemize

@node Library<32>,Documentation<25>,Core and Builtins<31>,Python 3 11 0 beta 1
@anchor{whatsnew/changelog id269}@anchor{1ab2}
@subsubsection Library



@itemize -

@item 
gh-87901@footnote{https://github.com/python/cpython/issues/87901}: Add the `encoding' parameter to @ref{319,,os.popen()}.

@item 
gh-90997@footnote{https://github.com/python/cpython/issues/90997}: Fix an issue where @ref{3c,,dis} utilities may interpret populated
inline cache entries as valid instructions.

@item 
gh-92332@footnote{https://github.com/python/cpython/issues/92332}: Deprecate @ref{35e,,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{3c,,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{dc,,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{823,,datetime.datetime.fromisoformat()},
@ref{821,,datetime.date.fromisoformat()} and
@ref{822,,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{1403,,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{4dc,,@@~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{93b,,__class_getitem__()} to
@ref{14f6,,logging.LoggerAdapter} and @ref{13f9,,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{4df,,inspect.Parameter} now raises @ref{2eb,,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{9e5,,types.GenericAlias}. Patch by Jelle Zijlstra.

@item 
gh-88089@footnote{https://github.com/python/cpython/issues/88089}: Add support for generic @ref{330,,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{11be,,subprocess.getoutput()} and @ref{11bf,,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{1ab3,,multiprocessing.Queue} `after' the last write of buffered data to
the write end of the pipe to avoid @ref{1257,,BrokenPipeError} at garbage
collection and at @ref{1ab4,,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{dc,,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{1ab5,,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{6f4,,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{1ab6,,argparse.Action} repr
output.

@item 
gh-91827@footnote{https://github.com/python/cpython/issues/91827}: In the @ref{f6,,tkinter} module add method @code{info_patchlevel()}
which returns the exact version of the Tcl library as a named tuple
similar to @ref{8a7,,sys.version_info}.

@item 
gh-84461@footnote{https://github.com/python/cpython/issues/84461}: Add @ref{1ab7,,--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{1ab8,,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{1ab9,,signal.raise_signal()} and @ref{155f,,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{8ae,,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{8b9,,typing.get_type_hints()} for
@ref{9e4,,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{be,,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{e1,,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{be,,re} module, fix @ref{1181,,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{be,,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{87b,,create_connection()} in an @ref{4cd,,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{be,,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{d4,,sqlite3}, @code{SQLITE_MISUSE} result codes are now mapped
to @ref{886,,InterfaceError} instead of
@ref{304,,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{82,,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{858,,inspect.getframeinfo()},
@ref{859,,inspect.getouterframes()}, @ref{85a,,inspect.getinnerframes()},
@ref{85b,,inspect.stack()} and @ref{85c,,inspect.trace()}. Patch by Pablo Galindo.

@item 
gh-69093@footnote{https://github.com/python/cpython/issues/69093}: Add indexing and slicing support to @ref{88b,,sqlite3.Blob}. Patch
by Aviv Palivoda and Erlend E. Aasland.

@item 
gh-69093@footnote{https://github.com/python/cpython/issues/69093}: Add @ref{1e1,,context manager} support to @ref{88b,,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{be,,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{3c,,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{179,,warnings.catch_warnings()} now accepts arguments for
@ref{8c8,,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{d1,,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{328,,locale.getencoding()} to get the current locale
encoding. It is similar to @code{locale.getpreferredencoding(False)} but
ignores the @ref{85f,,Python UTF-8 Mode}.

@item 
bpo-42012@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42012}: Add @ref{122,,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{be,,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{157e,,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{3f,,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{8b5,,typing.get_overloads()} and
@ref{8b6,,typing.clear_overloads()}. Patch by Jelle Zijlstra.

@item 
bpo-44807@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44807}: @ref{565,,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{1d6,,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{1aba,,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{d1,,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{76,,http.server} which specifies the HTTP version to which the server is
conformant (HTTP/1.1 conformant servers can now be run from the
command-line interface of module @ref{76,,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{9c0,,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{89c,,io.BufferedIOBase} or
@ref{89d,,io.TextIOBase} interface for
@ref{89b,,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{d4,,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{331,,TypedDict} subclasses to also include
@ref{174e,,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{4b2,,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{889,,create_window_function()} to
@ref{548,,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{2d,,csv} to use Argument Clinic for
@ref{1abb,,csv.field_size_limit()}, @ref{1abc,,csv.get_dialect()},
@ref{1abd,,csv.unregister_dialect()} and @ref{1abe,,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{304,,ProgrammingError} instead of segfaulting
on recursive usage of cursors in @ref{d4,,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{355,,SSLContext}.

@item 
bpo-22276@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22276}: @ref{266,,Path} methods @ref{532,,glob()} and
@ref{533,,rglob()} return only directories if `pattern' ends with
a pathname components separator (@code{/} or @ref{873,,sep}). Patch by
Eisuke Kawashima.

@item 
bpo-24905@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24905}: Add @ref{88a,,blobopen()} to
@ref{548,,sqlite3.Connection}. @ref{88b,,sqlite3.Blob} allows incremental I/O
operations on blobs. Patch by Aviv Palivoda and Erlend E. Aasland.
@end itemize

@node Documentation<25>,Tests<27>,Library<32>,Python 3 11 0 beta 1
@anchor{whatsnew/changelog id270}@anchor{1abf}
@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{68f,,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{c15,,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{76e,,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{1ac0,,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{1ac1,,runpy.run_module()} and
@ref{49f,,runpy.run_path()}. Original patch by Andrew Brezovsky.
@end itemize

@node Tests<27>,Build<30>,Documentation<25>,Python 3 11 0 beta 1
@anchor{whatsnew/changelog id271}@anchor{1ac2}
@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{10c,,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{1ac3,,ipaddress.IPv4Interface} and
@ref{1ac4,,ipaddress.IPv6Interface} construction with tuple arguments.
Original patch and tests by louisom.
@end itemize

@node Build<30>,Windows<28>,Tests<27>,Python 3 11 0 beta 1
@anchor{whatsnew/changelog id272}@anchor{1ac5}
@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<28>,macOS<20>,Build<30>,Python 3 11 0 beta 1
@anchor{whatsnew/changelog id273}@anchor{1ac6}
@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{7d3,,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{26d,,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<20>,Tools/Demos<24>,Windows<28>,Python 3 11 0 beta 1
@anchor{whatsnew/changelog id274}@anchor{1ac7}
@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<24>,C API<29>,macOS<20>,Python 3 11 0 beta 1
@anchor{whatsnew/changelog id275}@anchor{1ac8}
@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<29>,,Tools/Demos<24>,Python 3 11 0 beta 1
@anchor{whatsnew/changelog id276}@anchor{1ac9}
@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{974,,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{1a25,,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{2cf,,Py_REFCNT()}, @ref{3c7,,Py_TYPE()}, @ref{97d,,Py_SIZE()} and
@ref{1aca,,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{1acb,,PyOS_CheckStack()} is now exported in the Stable ABI on
Windows.

@item 
bpo-47169@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47169}: @code{PyThread_get_thread_native_id()} is excluded from the
stable ABI on platforms where it doesn't exist (like Solaris).

@item 
bpo-46343@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46343}: Added @ref{96b,,PyErr_GetHandledException()} and
@ref{96c,,PyErr_SetHandledException()} as simpler alternatives to
@ref{96e,,PyErr_GetExcInfo()} and @ref{96d,,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{1acc}
@subsection Python 3.11.0 alpha 7


`Release date: 2022-04-05'

@menu
* Core and Builtins: Core and Builtins<32>. 
* Library: Library<33>. 
* Documentation: Documentation<26>. 
* Tests: Tests<28>. 
* Build: Build<31>. 
* Windows: Windows<29>. 
* macOS: macOS<21>. 
* Tools/Demos: Tools/Demos<25>. 
* C API: C API<30>. 

@end menu

@node Core and Builtins<32>,Library<33>,,Python 3 11 0 alpha 7
@anchor{whatsnew/changelog id277}@anchor{1acd}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-47212@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47212}: Raise @ref{9a4,,IndentationError} instead of @ref{18e,,SyntaxError} for
a bare @code{except} with no following indent. Improve @ref{18e,,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{909,,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{911,,CHECK_EXC_MATCH} + jump.

@item 
bpo-47120@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47120}: Replace the absolute jump opcode @ref{1ace,,JUMP_NO_INTERRUPT} by
the relative @ref{906,,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{2c0,,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{912,,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{984,,PyFrameObject} by calling @ref{659,,PyFrame_GetLocals()}.

@item 
bpo-47070@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47070}: Improve performance of @code{array_inplace_repeat} by reducing the
number of invocations of @code{memcpy}. Refactor the @code{repeat} and inplace
@code{repeat} methods of @code{array}, @code{bytes}, @code{bytearray} and
@code{unicodeobject} to use the common @code{_PyBytes_Repeat}.

@item 
bpo-47053@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47053}: Reduce de-optimization in the specialized
@code{BINARY_OP_INPLACE_ADD_UNICODE} opcode.

@item 
bpo-47045@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47045}: Remove the @code{f_state} field from the _PyInterpreterFrame
struct. Add the @code{owner} field to the _PyInterpreterFrame struct to make
ownership explicit to simplify clearing and deallocing frames and
generators.

@item 
bpo-46968@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46968}: Check for the existence of the "sys/auxv.h" header in
@ref{5c,,faulthandler} to avoid compilation problems in systems where this
header doesn't exist. Patch by Pablo Galindo

@item 
bpo-46329@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46329}: Use low bit of @code{LOAD_GLOBAL} to indicate whether to push a
@code{NULL} before the global. Helps streamline the call sequence a bit.

@item 
bpo-46841@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46841}: Quicken bytecode in-place by storing it as part of the
corresponding @code{PyCodeObject}.

@item 
bpo-47012@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47012}: Speed up iteration of @ref{192,,bytes} and @ref{343,,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{8d4,,list.append()} and list
comprehensions by optimizing for the common case, where no resize is
needed. Patch by Dennis Sweeney.

@item 
bpo-47005@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47005}: Improve performance of @code{bytearray_repeat} and
@code{bytearray_irepeat} by reducing the number of invocations of @code{memcpy}.

@item 
bpo-46829@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46829}: Deprecate passing a message into @ref{1acf,,asyncio.Future.cancel()}
and @ref{4ce,,asyncio.Task.cancel()}

@item 
bpo-46993@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46993}: Speed up @ref{343,,bytearray} creation from @ref{24d,,list} and
@ref{60c,,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{18f5,,METH_FASTCALL} calling convention. Patch by Kumar Aditya.

@item 
bpo-46841@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46841}: Modify @ref{1ad0,,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{90d,,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{1928,,getter},
@ref{1929,,setter}, and @ref{192a,,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<33>,Documentation<26>,Core and Builtins<32>,Python 3 11 0 alpha 7
@anchor{whatsnew/changelog id278}@anchor{1ad1}
@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{be,,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{1c7,,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{be,,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{fc3,,asyncio.loop.sock_connect()} to only resolve names for
@ref{1ad2,,socket.AF_INET} or @ref{1ad3,,socket.AF_INET6} families. Resolution
may not make sense for other families, like @ref{1ad4,,socket.AF_BLUETOOTH}
and @ref{1ad5,,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{156c,,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{893,,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{6c,,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{6c,,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{7df,,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{142d,,re.search()}, @ref{59c,,re.split()},
@ref{1225,,re.findall()}, @ref{16ee,,re.finditer()} and @ref{59d,,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{16ee,,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{8cb,,zipfile.ZipFile} constructor and the @code{--metadata-encoding}
option in the @ref{137,,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{198d,,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{1960,,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{1960,,binascii.crc32()} release the GIL when computing on
larger inputs as @ref{195f,,zlib.crc32()} and @ref{6c,,hashlib} do.

This also boosts performance on Windows as it now uses the zlib crc32
implementation for @ref{1960,,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{be,,regular expressions}.

@item 
bpo-47062@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47062}: Implement @ref{2f4,,asyncio.Runner} context manager.

@item 
bpo-46382@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46382}: @ref{4dc,,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{6a0,,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{84d,,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{c5f,,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{f9b,,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{8b3,,typing.Any}. Patch by Shantanu
Jain.

@item 
bpo-46995@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46995}: Deprecate missing @ref{bc7,,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{1c9,,asyncio.create_task()} and @ref{1ca,,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{5c,,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{86c,,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{d00,,asyncio.Server}. Patch by Stefan Zabka.

@item 
bpo-23325@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23325}: The @ref{cb,,signal} module no longer assumes that
@ref{1ad6,,SIG_IGN} and @ref{1ad7,,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{b7,,pwd} module is now optional.
@ref{c00,,os.path.expanduser()} returns the path when the @ref{b7,,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{102,,tomllib} module. Adds support for parsing
TOML.

@item 
bpo-464471@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=464471}: @ref{80d,,asyncio.timeout()} and @ref{1ad8,,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{b2e,,typing.Annotated} to wrap @ref{9c2,,typing.ParamSpecArgs} and
@ref{1ad9,,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{447,,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{117,,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{1ada,,sysconfig.get_default_scheme()} and
@ref{898,,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{8b9,,typing.get_type_hints()} now supports evaluating strings
as forward references in @ref{8b8,,PEP 585 generic aliases}.

@item 
bpo-46607@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46607}: Add @ref{1a3,,DeprecationWarning} to @code{LegacyInterpolation},
deprecated in the docstring since Python 3.2. Will be removed in Python
3.13. Use @code{BasicInterpolation} or @code{ExtendedInterpolation}
instead.

@item 
bpo-26120@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26120}: @ref{ba,,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{8b2,,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{354,,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{eec,,typing.NewType}.

@item 
bpo-40296@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40296}: Fix supporting generic aliases in @ref{ba,,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{8b,,logging} module so that it is consistent across all
logging functions and, as advertised, similar to the @code{stacklevel}
argument used in @ref{170d,,warn()}.

@item 
bpo-24959@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24959}: Fix bug where @ref{10c,,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{d4,,sqlite3}.


@itemize *

@item 
Raise @ref{886,,InterfaceError} instead of
@ref{304,,ProgrammingError} for @code{SQLITE_MISUSE} errors.

@item 
Don't overwrite @ref{1adb,,BufferError} with @ref{2eb,,ValueError} when conversion to
BLOB fails.

@item 
Raise @ref{304,,ProgrammingError} instead of @ref{1adc,,Warning} if
user tries to @ref{5aa,,execute()} more than one SQL statement.

@item 
Raise @ref{304,,ProgrammingError} instead of @ref{2eb,,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{887,,serialize()} and
@ref{888,,deserialize()} support to @ref{d4,,sqlite3}. Patch
by Erlend E. Aasland.

@item 
bpo-33178@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33178}: Added @ref{1add,,ctypes.BigEndianUnion} and
@ref{1ade,,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{be,,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<26>,Tests<28>,Library<33>,Python 3 11 0 alpha 7
@anchor{whatsnew/changelog id279}@anchor{1adf}
@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{1960,,binascii.crc32()} / @ref{1ae0,,zlib.adler32()} / @ref{195f,,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{1ae1,,擴充型別定義教學} 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{bbc,,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<28>,Build<31>,Documentation<26>,Python 3 11 0 alpha 7
@anchor{whatsnew/changelog id280}@anchor{1ae2}
@subsubsection Tests



@itemize -

@item 
bpo-47205@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47205}: Skip test for @ref{130b,,sched_getaffinity()} and
@ref{130f,,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{adc,,asyncio.to_thread()} tests to use
@ref{35f,,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{cfd,,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<31>,Windows<29>,Tests<28>,Python 3 11 0 alpha 7
@anchor{whatsnew/changelog id281}@anchor{1ae3}
@subsubsection Build



@itemize -

@item 
bpo-40280@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40280}: Add configure option @ref{1ae4,,--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{f6,,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{d4,,sqlite3} extension module are found.
@end itemize

@node Windows<29>,macOS<21>,Build<31>,Python 3 11 0 alpha 7
@anchor{whatsnew/changelog id282}@anchor{1ae5}
@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{7d3,,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<21>,Tools/Demos<25>,Windows<29>,Python 3 11 0 alpha 7
@anchor{whatsnew/changelog id283}@anchor{1ae6}
@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{117,,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<25>,C API<30>,macOS<21>,Python 3 11 0 alpha 7
@anchor{whatsnew/changelog id284}@anchor{1ae7}
@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<30>,,Tools/Demos<25>,Python 3 11 0 alpha 7
@anchor{whatsnew/changelog id285}@anchor{1ae8}
@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{1ae9,,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{d7e,,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{1aea,,sys.get_asyncgen_hooks()} and
@ref{18f4,,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{961,,PyFloat_Pack2()}, @ref{962,,PyFloat_Pack4()},
@ref{963,,PyFloat_Pack8()}, @ref{964,,PyFloat_Unpack2()},
@ref{965,,PyFloat_Unpack4()} and @ref{966,,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{1aeb}
@subsection Python 3.11.0 alpha 6


`Release date: 2022-03-07'

@menu
* Core and Builtins: Core and Builtins<33>. 
* Library: Library<34>. 
* Documentation: Documentation<27>. 
* Tests: Tests<29>. 
* Build: Build<32>. 
* Windows: Windows<30>. 
* IDLE: IDLE<15>. 
* C API: C API<31>. 

@end menu

@node Core and Builtins<33>,Library<34>,,Python 3 11 0 alpha 6
@anchor{whatsnew/changelog id286}@anchor{1aec}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-46940@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46940}: Avoid overriding @ref{5e8,,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{364,,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{1aed,,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{b58,,COMPARE_OP} followed by @ref{1a61,,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{6fd,,LOAD_ATTR},
@code{LOAD_METHOD}, and @ref{1aee,,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{b58,,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{1aef,,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{19ab,,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{364,,BINARY_OP} caches inline using a new
@ref{900,,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{6fd,,LOAD_ATTR} and
@ref{1aee,,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{b58,,COMPARE_OP} when collecting
specialization stats.

@item 
bpo-46329@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46329}: Fix specialization stats gathering for @code{PRECALL}
instructions.

@item 
bpo-46794@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46794}: Bump up the libexpat version into 2.4.6

@item 
bpo-46823@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46823}: Implement a specialized combined opcode
@code{LOAD_FAST__LOAD_ATTR_INSTANCE_VALUE}.  Patch by Dennis Sweeney.

@item 
bpo-46820@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46820}: Fix parsing a numeric literal immediately (without spaces)
followed by "not in" keywords, like in @code{1not in x}. Now the parser only
emits a warning, not a syntax error.

@item 
bpo-46329@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46329}: Move @code{KW_NAMES} before @code{PRECALL} instruction in call
sequence. Change @code{operand} of @code{CALL} to match @code{PRECALL} for easier
specialization.

@item 
bpo-46808@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46808}: Remove the @code{NEXT_BLOCK} macro from compile.c, and make the
compiler automatically generate implicit blocks when they are needed.

@item 
bpo-46329@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46329}: Add @code{PUSH_NULL} instruction. This is used as a prefix when
evaluating a callable, so that the stack has the same shape for methods
and other calls. @code{PRECALL_FUNCTION} and @code{PRECALL_METHOD} are merged
into a single @code{PRECALL} instruction.

There is no change in semantics.

@item 
bpo-46762@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46762}: Fix an assert failure in debug builds when a '<', '>', or '='
is the last character in an f-string that's missing a closing right brace.

@item 
bpo-46730@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46730}: Message of AttributeError caused by getting, setting or
deleting a property without the corresponding function now mentions that
the attribute is in fact a property and also specifies type of the class
that it belongs to.

@item 
bpo-46724@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46724}: Make sure that all backwards jumps use the @code{JUMP_ABSOLUTE}
instruction, rather than @code{JUMP_FORWARD} with an argument of
@code{(2**32)+offset}.

@item 
bpo-46732@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46732}: Correct the docstring for the @ref{14d6,,__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{364,,BINARY_OP}.

@item 
bpo-46707@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46707}: Avoid potential exponential backtracking when producing some
syntax errors involving lots of brackets. Patch by Pablo Galindo.

@item 
bpo-46323@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46323}: @ref{2e,,ctypes} now allocates memory on the stack instead of on
the heap to pass arguments while calling a Python callback function. Patch
by Donghee Na.

@item 
bpo-45923@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45923}: Add a quickened form of @ref{5b3,,RESUME} that skips quickening
checks.

@item 
bpo-46702@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46702}: Specialize @ref{1aef,,UNPACK_SEQUENCE} for @ref{60c,,tuple} and
@ref{24d,,list} unpackings.

@item 
bpo-46072@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46072}: Opcode pair stats are now gathered with @code{--enable-pystats}.
Defining @code{DYNAMIC_EXECUTION_PROFILE} or  @code{DXPAIRS} no longer has any
effect.

@item 
bpo-46675@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46675}: Allow more than 16 items in a split dict before it is combined.
The limit is now 254.

@item 
bpo-40479@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40479}: Add a missing call to @code{va_end()} in
@code{Modules/_hashopenssl.c}.

@item 
bpo-46323@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46323}: Use @ref{777,,PyObject_Vectorcall()} while calling ctypes callback
function. Patch by Donghee Na.

@item 
bpo-46615@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46615}: When iterating over sets internally in @code{setobject.c}, acquire
strong references to the resulting items from the set.  This prevents
crashes in corner-cases of various set operations where the set gets
mutated.

@item 
bpo-45828@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45828}: The bytecode compiler now attempts to apply runtime stack
manipulations at compile-time (whenever it is feasible to do so).

@item 
bpo-30496@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30496}: Fixed a minor portability issue in the implementation of
@ref{1af0,,PyLong_FromLong()}, and added a fast path for single-digit integers
to @ref{1af1,,PyLong_FromLongLong()}.
@end itemize

@node Library<34>,Documentation<27>,Core and Builtins<33>,Python 3 11 0 alpha 6
@anchor{whatsnew/changelog id287}@anchor{1af2}
@subsubsection Library



@itemize -

@item 
bpo-25707@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25707}: Fixed a file leak in @ref{574,,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{1af3,,unittest.doModuleCleanups()} in @ref{10c,,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{1af4,,find()} and @ref{1af5,,rfind()} for
@code{find()} and @code{rfind()}.

@item 
bpo-46736@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46736}: @ref{d30,,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{1a68,,asyncio.DatagramTransport}.

@item 
bpo-46827@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46827}: Support UDP sockets in  @ref{fc3,,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{198,,TypeError} if @ref{ade,,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{354,,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{4cf,,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{1af6,,urllib.request.HTTPPasswordMgr.find_user_password()} and
@ref{1af7,,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{1af8,,random.gauss()} and @ref{1af9,,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{3c,,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{1afa,,typing.ForwardRef} now
includes the @code{module} parameter of @ref{1afa,,typing.ForwardRef} when it is
set.

@item 
bpo-46643@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46643}: In @ref{8b9,,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{e4,,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{331,,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{482,,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{80c,,asyncio.gather()} when initial type
check fails.

@item 
bpo-46659@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46659}: The @ref{943,,calendar.LocaleTextCalendar} and
@ref{944,,calendar.LocaleHTMLCalendar} classes now use
@ref{326,,locale.getlocale()}, instead of using
@ref{325,,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{325,,locale.getdefaultlocale()} function is deprecated and
will be removed in Python 3.13. Use @ref{327,,locale.setlocale()},
@ref{755,,locale.getpreferredencoding(False)}
and @ref{326,,locale.getlocale()} functions instead.  Patch by Victor Stinner.

@item 
bpo-46655@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46655}: In @ref{8b9,,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{12b,,xml.etree.ElementTree} module. Now, instantiating an
@ref{c40,,xml.etree.ElementTree.XMLParser} with a @code{target=None} keyword
provides a default @ref{c41,,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{d1,,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{8bb,,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{266,,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{7dc,,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{8af,,typing.Never} and @ref{8ae,,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{1afa,,typing.ForwardRef} now honor the @code{module} parameter of
@ref{1afa,,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{d5,,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{8b9,,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{837,,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{2e,,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{1afb,,is_tarfile()} method when using
`fileobj' argument: position in the `fileobj' was advanced forward which
made it unreadable with @ref{1afc,,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{4d9,,configparser.ConfigParser} constructor raise
@ref{198,,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{853,,inspect.ismethodwrapper()} and fix
@ref{1afd,,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<27>,Tests<29>,Library<34>,Python 3 11 0 alpha 6
@anchor{whatsnew/changelog id288}@anchor{1afe}
@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<29>,Build<32>,Documentation<27>,Python 3 11 0 alpha 6
@anchor{whatsnew/changelog id289}@anchor{1aff}
@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<32>,Windows<30>,Tests<29>,Python 3 11 0 alpha 6
@anchor{whatsnew/changelog id290}@anchor{1b00}
@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{971,,_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<30>,IDLE<15>,Build<32>,Python 3 11 0 alpha 6
@anchor{whatsnew/changelog id291}@anchor{1b01}
@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<15>,C API<31>,Windows<30>,Python 3 11 0 alpha 6
@anchor{whatsnew/changelog id292}@anchor{1b02}
@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<31>,,IDLE<15>,Python 3 11 0 alpha 6
@anchor{whatsnew/changelog id293}@anchor{1b03}
@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{984,,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{62d,,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{1b04}
@subsection Python 3.11.0 alpha 5


`Release date: 2022-02-03'

@menu
* Core and Builtins: Core and Builtins<34>. 
* Library: Library<35>. 
* Documentation: Documentation<28>. 
* Tests: Tests<30>. 
* Build: Build<33>. 
* Windows: Windows<31>. 
* macOS: macOS<22>. 
* IDLE: IDLE<16>. 
* C API: C API<32>. 

@end menu

@node Core and Builtins<34>,Library<35>,,Python 3 11 0 alpha 5
@anchor{whatsnew/changelog id294}@anchor{1b05}
@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{1a6,,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{19b,,int()} to @code{__trunc__()} is now
deprecated. Calling @code{int(a)} when @code{type(a)} implements
@code{__trunc__()} but not @code{__int__()} or @code{__index__()} now raises
a @ref{1a3,,DeprecationWarning}.

@item 
bpo-46458@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46458}: Reorder code emitted by the compiler for a
@ref{8f0,,try}-@ref{1ab,,except} block so that the @ref{17c,,else} block's
code immediately follows the @ref{8f0,,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{1675,,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{90f,,COPY} and @ref{910,,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{1b06,,PyWeakref_NewRef()} which can trigger a garbage collection which
can indirectly modify @code{PyTypeObject.tp_subclasses}. Patch by Victor
Stinner.

@item 
bpo-46417@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46417}: @code{python -X showrefcount} now shows the total reference count
after clearing and destroyed the main Python interpreter. Previously, it
was shown before. Patch by Victor Stinner.

@item 
bpo-43683@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43683}: Add ASYNC_GEN_WRAP opcode to wrap the value to be yielded in
async generators. Removes the need to special case async generators in the
@code{YIELD_VALUE} instruction.

@item 
bpo-46407@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46407}: Optimize some modulo operations in @code{Objects/longobject.c}.
Patch by Jeremiah Vivian.

@item 
bpo-46409@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46409}: Add new @code{RETURN_GENERATOR} bytecode to make generators.
Simplifies calling Python functions in the VM, as they no longer any need
to special case generator functions.

Also add @code{JUMP_NO_INTERRUPT} bytecode that acts like @code{JUMP_ABSOLUTE},
but does not check for interrupts.

@item 
bpo-46406@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46406}: The integer division @code{//} implementation has been optimized
to better let the compiler understand its constraints. It can be 20%
faster on the amd64 platform when dividing an int by a value smaller than
@code{2**30}.

@item 
bpo-46383@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46383}: Fix invalid signature of @code{_zoneinfo}'s @code{module_free}
function to resolve a crash on wasm32-emscripten platform.

@item 
bpo-46361@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46361}: Ensure that "small" integers created by @ref{1b07,,int.from_bytes()}
and @ref{1fe,,decimal.Decimal} are properly cached.

@item 
bpo-46161@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46161}: Fix the class building error when the arguments are constants
and CALL_FUNCTION_EX is used.

@item 
bpo-46028@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46028}: Fixes calculation of @code{sys._base_executable} when inside a
virtual environment that uses symlinks with different binary names than
the base environment provides.

@item 
bpo-46091@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46091}: Correctly calculate indentation levels for lines with
whitespace character that are ended by line continuation characters. Patch
by Pablo Galindo

@item 
bpo-30512@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30512}: Add CAN Socket support for NetBSD.

@item 
bpo-46045@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46045}: Do not use POSIX semaphores on NetBSD

@item 
bpo-44024@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44024}: Improve the @ref{198,,TypeError} message for non-string second
arguments passed to the built-in functions @ref{dc5,,getattr()} and
@ref{6f2,,hasattr()}. Patch by Géry Ogam.
@end itemize

@node Library<35>,Documentation<28>,Core and Builtins<34>,Python 3 11 0 alpha 5
@anchor{whatsnew/changelog id295}@anchor{1b08}
@subsubsection Library



@itemize -

@item 
bpo-46624@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46624}: Restore support for non-integer arguments of
@ref{a64,,random.randrange()} and @ref{1430,,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{8b9,,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{11c8,,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{10c,,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{8b9,,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{ce1,,types.TracebackType} and
@ref{1b09,,types.FrameType}. Calculate them directly from the caught
exception without calling @ref{893,,sys.exc_info()}.

@item 
bpo-46491@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46491}: Allow @ref{b2e,,typing.Annotated} to wrap @ref{568,,typing.Final} and
@ref{567,,typing.ClassVar}. Patch by Gregory Beauregard.

@item 
bpo-46483@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46483}: Remove @ref{93b,,__class_getitem__()} from
@ref{6c6,,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{76,,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{198,,TypeError} with a
relevant error message on invalid arg. Previously it allowed a cryptic
@ref{5e8,,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{9e5,,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{13b1,,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{1b0a,,__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{8b1,,typing.reveal_type()}. Patch by Jelle Zijlstra.

@item 
bpo-40280@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40280}: @ref{dc,,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{26e,,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{1976,,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{bef,,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{83b,,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{22f,,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{e6c,,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{1b0b,,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{13a,,zoneinfo} to rely on importlib.resources
traversable API.

@item 
bpo-46103@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46103}: Now @ref{1b0c,,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{1b0d,,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{482,,ParamSpec} in
@ref{9c0,,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<28>,Tests<30>,Library<35>,Python 3 11 0 alpha 5
@anchor{whatsnew/changelog id296}@anchor{1b0e}
@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<30>,Build<33>,Documentation<28>,Python 3 11 0 alpha 5
@anchor{whatsnew/changelog id297}@anchor{1b0f}
@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{f63,,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{4b0,,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{dc,,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<33>,Windows<31>,Tests<30>,Python 3 11 0 alpha 5
@anchor{whatsnew/changelog id298}@anchor{1b10}
@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<31>,macOS<22>,Build<33>,Python 3 11 0 alpha 5
@anchor{whatsnew/changelog id299}@anchor{1b11}
@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<22>,IDLE<16>,Windows<31>,Python 3 11 0 alpha 5
@anchor{whatsnew/changelog id300}@anchor{1b12}
@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<16>,C API<32>,macOS<22>,Python 3 11 0 alpha 5
@anchor{whatsnew/changelog id301}@anchor{1b13}
@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<32>,,IDLE<16>,Python 3 11 0 alpha 5
@anchor{whatsnew/changelog id302}@anchor{1b14}
@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{954,,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{1b15}
@subsection Python 3.11.0 alpha 4


`Release date: 2022-01-13'

@menu
* Core and Builtins: Core and Builtins<35>. 
* Library: Library<36>. 
* Documentation: Documentation<29>. 
* Tests: Tests<31>. 
* Build: Build<34>. 
* Windows: Windows<32>. 
* macOS: macOS<23>. 
* C API: C API<33>. 

@end menu

@node Core and Builtins<35>,Library<36>,,Python 3 11 0 alpha 4
@anchor{whatsnew/changelog id303}@anchor{1b16}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-46070@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46070}: @ref{17c3,,Py_EndInterpreter()} now explicitly untracks all objects
currently tracked by the GC. Previously, if an object was used later by
another interpreter, calling @ref{16f9,,PyObject_GC_UnTrack()} on the object
crashed if the previous or the next object of the @code{PyGC_Head}
structure became a dangling pointer. Patch by Victor Stinner.

@item 
bpo-46347@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46347}: Fix memory leak in PyEval_EvalCodeEx.

@item 
bpo-46339@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46339}: Fix a crash in the parser when retrieving the error text for
multi-line f-strings expressions that do not start in the first line of
the string. Patch by Pablo Galindo

@item 
bpo-46331@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46331}: Do not set line number of instruction storing doc-string. Fixes
regression introduced in 3.11 alpha.

@item 
bpo-46314@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46314}: Remove spurious "call" event when creating a lambda function
that was accidentally introduced in 3.11a4.

@item 
bpo-46289@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46289}: ASDL declaration of @code{FormattedValue} has changed to reflect
@code{conversion} field is not optional.

@item 
bpo-46297@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46297}: Fixed an interpreter crash on bootup with multiple PythonPaths
set in the Windows registry. Patch by Derzsi Dániel.

@item 
bpo-46237@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46237}: Fix the line number of tokenizer errors inside f-strings. Patch
by Pablo Galindo.

@item 
bpo-46263@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46263}: We always expect the "use_frozen_modules" config to be set, now
that getpath.c was rewritten in pure Python and the logic improved.

@item 
bpo-46006@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46006}: Fix a regression when a type method like @code{__init__()} is
modified in a subinterpreter. Fix a regression in
@code{_PyUnicode_EqualToASCIIId()} and type @code{update_slot()}. Revert the
change which made the Unicode dictionary of interned strings compatible
with subinterpreters: the internal interned dictionary is shared again by
all interpreters. Patch by Victor Stinner.

@item 
bpo-45923@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45923}: Add RESUME opcode. This is a logical no-op. It is emitted by
the compiler anywhere a Python function can be entered. It is used by the
interpreter to perform tracing and optimizer checks.

@item 
bpo-46208@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46208}: Fix the regression of os.path.normpath("A/../../B") not
returning expected "../B" but "B".

@item 
bpo-46240@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46240}: Correct the error message for unclosed parentheses when the
tokenizer doesn't reach the end of the source when the error is reported.
Patch by Pablo Galindo

@item 
bpo-46009@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46009}: Remove the @code{GEN_START} opcode.

@item 
bpo-46235@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46235}: Certain sequence multiplication operations like @code{[0] * 1_000}
are now faster due to reference-counting optimizations. Patch by Dennis
Sweeney.

@item 
bpo-46221@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46221}: @code{PREP_RERAISE_STAR} no longer pushes @code{lasti} to the
stack.

@item 
bpo-46202@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46202}: Remove @code{POP_EXCEPT_AND_RERAISE} and replace it by an
equivalent sequence of other opcodes.

@item 
bpo-46085@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46085}: Fix iterator cache mechanism of @code{OrderedDict}.

@item 
bpo-46055@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46055}: Speed up shifting operation involving integers less than
@code{PyLong_BASE}. Patch by Xinhang Xu.

@item 
bpo-46110@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46110}: Add a maximum recursion check to the PEG parser to avoid stack
overflow. Patch by Pablo Galindo

@item 
bpo-46107@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46107}: Fix bug where @code{ExceptionGroup.split()} and
@code{ExceptionGroup.subgroup()} did not copy the exception group's
@code{__note__} field to the parts.

@item 
bpo-45711@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45711}: The interpreter state's representation of handled exceptions
(a.k.a exc_info, or _PyErr_StackItem) now has only the @code{exc_value}
field, @code{exc_type} and @code{exc_traceback} have been removed as their
values can be derived from @code{exc_value}.

@item 
bpo-44525@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44525}: Replace the four call bytecode instructions which one pre-call
instruction and two call instructions.

Removes @code{CALL_FUNCTION}, @code{CALL_FUNCTION_KW}, @code{CALL_METHOD} and
@code{CALL_METHOD_KW}.

Adds @code{CALL_NO_KW} and @code{CALL_KW} call instructions, and
@code{PRECALL_METHOD} prefix for pairing with @code{LOAD_METHOD}.

@item 
bpo-46039@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46039}: Remove the @code{YIELD_FROM} instruction and replace it with the
@code{SEND} instruction which performs the same operation, but without the
loop.

@item 
bpo-45635@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45635}: The code called from @code{_PyErr_Display()} was refactored
to improve error handling. It now exits immediately upon an unrecoverable
error.

@item 
bpo-46054@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46054}: Fix parser error when parsing non-utf8 characters in source
files. Patch by Pablo Galindo.

@item 
bpo-46042@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46042}: Improve the location of the caret in @ref{18e,,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{1aaf,,POP_JUMP_IF_NOT_NONE} and
@ref{1aae,,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{c3,,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.

@item 
bpo-46000@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46000}: Improve compatibility of the @ref{2f,,curses} module with NetBSD
curses.

@item 
bpo-44525@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44525}: Specialize the CALL_FUNCTION instruction for calls to builtin
types with a single argument. Speeds up @code{range(x)}, @code{list(x)}, and
specifically @code{type(obj)}.

@item 
bpo-42918@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42918}: Fix bug where the built-in @ref{4ac,,compile()} function did not
always raise a @ref{18e,,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{184,,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{37f,,Py_Version} constant which bears the same
value as @ref{380,,PY_VERSION_HEX}. Patch by Gabriele N. Tornetta.
@end itemize

@node Library<36>,Documentation<29>,Core and Builtins<35>,Python 3 11 0 alpha 4
@anchor{whatsnew/changelog id304}@anchor{1b17}
@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{894,,sys.exception()} method which returns the active
exception instance.

@item 
bpo-46307@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46307}: Add @ref{88f,,string.Template.is_valid()} and
@ref{88e,,string.Template.get_identifiers()} methods.

@item 
bpo-46306@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46306}: Assume that @ref{32e,,types.CodeType} always has
@code{types.CodeType.co_firstlineno} in @ref{3e,,doctest}.

@item 
bpo-40479@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40479}: Fix @ref{6c,,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{482,,typing.ParamSpec} and
@ref{481,,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{1b18,,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{117,,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{8d7,,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{59a,,glob()} and
@ref{a01,,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{1b19,,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{74d,,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{2eb,,ValueError} with clear message
when trying to render usage for an empty mutually exclusive group.
Previously it raised a cryptic @ref{1729,,IndexError}.

@item 
bpo-45615@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45615}: Functions in the @ref{104,,traceback} module raise @ref{198,,TypeError}
rather than @ref{5e8,,AttributeError} when an exception argument is not of
type @ref{7d0,,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{cb,,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{844,,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{82,,inspect}, patch by Kumar Aditya.

@item 
bpo-46018@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46018}: Ensure that @ref{13ed,,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{5d,,fcntl} module.

@item 
bpo-45755@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45755}: @ref{10a,,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{1b1a,,multiprocessing.Event} objects, patch by Kumar Aditya.

@item 
bpo-45643@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45643}: Added @ref{1b1b,,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{886,,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{a2f,,TimeoutError}, keep these
names as deprecated aliases.
@end itemize

@node Documentation<29>,Tests<31>,Library<36>,Python 3 11 0 alpha 4
@anchor{whatsnew/changelog id305}@anchor{1b1c}
@subsubsection Documentation



@itemize -

@item 
bpo-46196@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46196}: Document method @ref{1b1d,,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{10a,,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{1b1e,,globals()} function.
@end itemize

@node Tests<31>,Build<34>,Documentation<29>,Python 3 11 0 alpha 4
@anchor{whatsnew/changelog id306}@anchor{1b1f}
@subsubsection Tests



@itemize -

@item 
bpo-46296@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46296}: Add a test case for @ref{5a,,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{35f,,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<34>,Windows<32>,Tests<31>,Python 3 11 0 alpha 4
@anchor{whatsnew/changelog id307}@anchor{1b20}
@subsubsection Build



@itemize -

@item 
bpo-44133@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44133}: When Python is configured with
@ref{a85,,--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{a5c,,--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{118f,,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<32>,macOS<23>,Build<34>,Python 3 11 0 alpha 4
@anchor{whatsnew/changelog id308}@anchor{1b21}
@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<23>,C API<33>,Windows<32>,Python 3 11 0 alpha 4
@anchor{whatsnew/changelog id309}@anchor{1b22}
@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<33>,,macOS<23>,Python 3 11 0 alpha 4
@anchor{whatsnew/changelog id310}@anchor{1b23}
@subsubsection C API



@itemize -

@item 
bpo-46236@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46236}: Fix a bug in @ref{1a76,,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{955,,PyBuffer_GetPointer()},
@ref{958,,PyBuffer_FromContiguous()}, @ref{957,,PyBuffer_ToContiguous()} and
@ref{95d,,PyMemoryView_FromBuffer()} now take buffer info by @code{const
Py_buffer *} instead of @code{Py_buffer *}, as they do not need mutability.
@ref{958,,PyBuffer_FromContiguous()} also now takes the source buffer as
@code{const void *}, and similarly @ref{955,,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{1b24,,PyCapsule_Import()} is a no-op now.

@item 
bpo-45855@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45855}: Replaced deprecated usage of
@ref{3d9,,PyImport_ImportModuleNoBlock()} with
@ref{3da,,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{1b25}
@subsection Python 3.11.0 alpha 3


`Release date: 2021-12-08'

@menu
* Core and Builtins: Core and Builtins<36>. 
* Library: Library<37>. 
* Documentation: Documentation<30>. 
* Tests: Tests<32>. 
* Build: Build<35>. 
* Windows: Windows<33>. 
* macOS: macOS<24>. 
* C API: C API<34>. 

@end menu

@node Core and Builtins<36>,Library<37>,,Python 3 11 0 alpha 3
@anchor{whatsnew/changelog id311}@anchor{1b26}
@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{18e,,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{7d0,,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{1b27,,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{893,,sys.exc_info()} and @ref{96e,,PyErr_GetExcInfo()} if the exception
instance is modified while the exception is handled, as well as
@ref{96d,,PyErr_SetExcInfo()}, which now ignores the @code{type} and
@code{traceback} arguments provided to it.

@item 
bpo-45727@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45727}: Refine the custom syntax error that suggests that a comma may
be missing to trigger only when the expressions are detected between
parentheses or brackets. Patch by Pablo Galindo

@item 
bpo-45885@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45885}: Specialized the @code{COMPARE_OP} opcode using the PEP 659
machinery.

@item 
bpo-45786@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45786}: Allocate space for the interpreter frame in the frame object,
to avoid an additional allocation when the frame object outlives the frame
activation.

@item 
bpo-45614@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45614}: Fix @ref{104,,traceback} display for exceptions with invalid module
name.

@item 
bpo-45813@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45813}: Fix crash when calling coro.cr_frame.clear() after coroutine
has been freed.

@item 
bpo-45811@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45811}: Improve the tokenizer errors when encountering invisible
control characters in the parser. Patch by Pablo Galindo

@item 
bpo-45848@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45848}: Allow the parser to obtain error lines directly from encoded
files. Patch by Pablo Galindo

@item 
bpo-45709@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45709}: Restore behavior from 3.10 when tracing an exception raised
within a with statement.

@item 
bpo-44525@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44525}: Adds new @ref{905,,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{364,,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{4b0,,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{364,,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{df,,sys} and
@ref{e1,,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<37>,Documentation<30>,Core and Builtins<36>,Python 3 11 0 alpha 3
@anchor{whatsnew/changelog id312}@anchor{1b28}
@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{361,,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{426,,PyErr_Fetch()}, and before they are stored as an
exc_info triplet. This brings @ref{b,,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{74d,,unittest.TextTestResult} and
@ref{1a01,,unittest.TextTestRunner} flush now the output stream more often.

@item 
bpo-45917@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45917}: Added @ref{869,,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{5c,,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{d4,,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{a2b,,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{3c,,dis} produced an incorrect oparg when
@ref{1a61,,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{3e2,,sys.path}
location while the program is running, calling the
@ref{e05,,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{d90,,types.resolve_bases()} and @ref{1362,,types.new_class()} for
@ref{9e5,,types.GenericAlias} instance as a base.

@item 
bpo-45663@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45663}: Fix @ref{1b29,,dataclasses.is_dataclass()} for dataclasses which are
subclasses of @ref{9e5,,types.GenericAlias}.

@item 
bpo-45662@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45662}: Fix the repr of @ref{1ad9,,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{8a4,,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{8d7,,math.comb()} and @ref{8d8,,math.perm()}.

@item 
bpo-45514@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45514}: Deprecated legacy functions in @ref{7f,,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{ad5,,graphlib.TopologicalSorter}.

@item 
bpo-44733@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44733}: Add @code{max_tasks_per_child} to
@ref{1d6,,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{852,,inspect.getmembers_static()} , it return all members
without triggering dynamic lookup via the descriptor protocol. Patch by
Weipeng Hong.
@end itemize

@node Documentation<30>,Tests<32>,Library<37>,Python 3 11 0 alpha 3
@anchor{whatsnew/changelog id313}@anchor{1b2a}
@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{f3f,,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{19ed,,astuple()} and
@ref{19e4,,asdict()} docs, warning about deepcopy being applied and
providing a workaround.
@end itemize

@node Tests<32>,Build<35>,Documentation<30>,Python 3 11 0 alpha 3
@anchor{whatsnew/changelog id314}@anchor{1b2b}
@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{bd9,,functools.lru_cache()}
to @code{test_functools}.
@end itemize

@node Build<35>,Windows<33>,Tests<32>,Python 3 11 0 alpha 3
@anchor{whatsnew/changelog id315}@anchor{1b2c}
@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{cb,,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{3a,,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{d4,,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{139,,zlib}, @ref{14,,bz2}, and
@ref{8e,,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<33>,macOS<24>,Build<35>,Python 3 11 0 alpha 3
@anchor{whatsnew/changelog id316}@anchor{1b2d}
@subsubsection Windows



@itemize -

@item 
bpo-46105@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46105}: Fixed calculation of @ref{3e2,,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<24>,C API<34>,Windows<33>,Python 3 11 0 alpha 3
@anchor{whatsnew/changelog id317}@anchor{1b2e}
@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<34>,,macOS<24>,Python 3 11 0 alpha 3
@anchor{whatsnew/changelog id318}@anchor{1b2f}
@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{1b30}
@subsection Python 3.11.0 alpha 2


`Release date: 2021-11-05'

@menu
* Core and Builtins: Core and Builtins<37>. 
* Library: Library<38>. 
* Documentation: Documentation<31>. 
* Tests: Tests<33>. 
* Build: Build<36>. 
* Windows: Windows<34>. 
* macOS: macOS<25>. 
* IDLE: IDLE<17>. 
* C API: C API<35>. 

@end menu

@node Core and Builtins<37>,Library<38>,,Python 3 11 0 alpha 2
@anchor{whatsnew/changelog id319}@anchor{1b31}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-45716@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45716}: Improve the @ref{18e,,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{a3b,,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{653,,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{1b32,,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{16f,,-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{4cd,,ExceptionGroup} and
@ref{560,,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<38>,Documentation<31>,Core and Builtins<37>,Python 3 11 0 alpha 2
@anchor{whatsnew/changelog id320}@anchor{1b33}
@subsubsection Library



@itemize -

@item 
bpo-45679@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45679}: Fix caching of multi-value @ref{a4e,,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{d4,,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{d4,,sqlite3} now sets @ref{885,,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{5a0,,sqlite3.connect()} now correctly raises @ref{181e,,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{a22,,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{1b34,,operator.call()} to @code{operator.__all__}. Patch by
Kreusada.

@item 
bpo-42174@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42174}: @ref{1304,,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{1151,,importlib.machinery.NamespaceLoader} is
now public, and implements the @ref{114f,,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{13a,,zoneinfo} in the @ref{34,,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{654,,gzip.GzipFile},
@ref{a5f,,bz2.BZ2File}, and @ref{1207,,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{1afa,,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{1b35,,email.utils.parsedate_tz()} crashing with
@ref{172a,,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{1b36,,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{c5e,,asyncio.Condition} with explicit
@ref{c5d,,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{17aa,,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{3e,,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{1a9c,,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{2d,,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{134,,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{17aa,,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{d2d,,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{883,,setlimit()} and
@ref{884,,getlimit()} to @ref{548,,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{82,,inspect} module:


@itemize *

@item 

@table @asis

@item the @code{getargspec} function, deprecated since Python 3.0;

use @ref{22f,,inspect.signature()} or @ref{939,,inspect.getfullargspec()} instead.
@end table

@item 
the @code{formatargspec} function, deprecated since Python 3.5;
use the @ref{22f,,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{93a,,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{e6,,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{819,,chdir()} context
manager to change the current working directory and then restore it on
exit. Simple wrapper around @ref{81a,,chdir()}.

@item 
bpo-24139@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24139}: Add support for SQLite extended result codes in
@ref{1b37,,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{213,,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{10e,,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<31>,Tests<33>,Library<38>,Python 3 11 0 alpha 2
@anchor{whatsnew/changelog id321}@anchor{1b38}
@subsubsection Documentation



@itemize -

@item 
bpo-45726@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45726}: Improve documentation for @ref{844,,functools.singledispatch()} and
@ref{bda,,functools.singledispatchmethod}.

@item 
bpo-45680@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45680}: Amend the docs on @code{GenericAlias} objects to clarify that
non-container classes can also implement @code{__class_getitem__}. Patch
contributed by Alex Waygood.

@item 
bpo-45618@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45618}: Update Sphinx version used to build the documentation to 4.2.0.
Patch by Maciej Olko.

@item 
bpo-45655@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45655}: Add a new "relevant PEPs" section to the top of the
documentation for the @code{typing} module. Patch by Alex Waygood.

@item 
bpo-45604@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45604}: Add @code{level} argument to @code{multiprocessing.log_to_stderr}
function docs.

@item 
bpo-45516@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45516}: Add protocol description to the
@ref{1b39,,importlib.abc.TraversableResources} documentation.

@item 
bpo-45464@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45464}: Mention in the documentation of @ref{1b3a,,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
@ref{1b3b,,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<33>,Build<36>,Documentation<31>,Python 3 11 0 alpha 2
@anchor{whatsnew/changelog id322}@anchor{1b3c}
@subsubsection Tests



@itemize -

@item 
bpo-45678@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45678}: Add tests for scenarios in which
@ref{bda,,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{206,,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{d4,,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<36>,Windows<34>,Tests<33>,Python 3 11 0 alpha 2
@anchor{whatsnew/changelog id323}@anchor{1b3d}
@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{92,,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{497,,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<34>,macOS<25>,Build<36>,Python 3 11 0 alpha 2
@anchor{whatsnew/changelog id324}@anchor{1b3e}
@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<25>,IDLE<17>,Windows<34>,Python 3 11 0 alpha 2
@anchor{whatsnew/changelog id325}@anchor{1b3f}
@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<17>,C API<35>,macOS<25>,Python 3 11 0 alpha 2
@anchor{whatsnew/changelog id326}@anchor{1b40}
@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<35>,,IDLE<17>,Python 3 11 0 alpha 2
@anchor{whatsnew/changelog id327}@anchor{1b41}
@subsubsection C API



@itemize -

@item 
bpo-29103@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29103}: @ref{76c,,PyType_FromSpec*} now
copies the class name from the spec to a buffer owned by the class, so the
original can be safely deallocated. Patch by Petr Viktorin.

@item 
bpo-45522@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45522}: The internal freelists for frame, float, list, dict, async
generators, and context objects can now be disabled.

@item 
bpo-35134@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35134}: Exclude @ref{3dc,,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{97f,,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{991,,PyMarshal_WriteLongToFile()}

@item 
@ref{992,,PyMarshal_WriteObjectToFile()}

@item 
@ref{993,,PyMarshal_ReadObjectFromString()}

@item 
@ref{994,,PyMarshal_WriteObjectToString()}

@item 
the @code{Py_MARSHAL_VERSION} macro
@end itemize

These are not part of the @ref{995,,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{952,,PyThreadState_EnterTracing()}, and
@ref{953,,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{b70,,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{1b42}
@subsection Python 3.11.0 alpha 1


`Release date: 2021-10-05'

@menu
* Security: Security<27>. 
* Core and Builtins: Core and Builtins<38>. 
* Library: Library<39>. 
* Documentation: Documentation<32>. 
* Tests: Tests<34>. 
* Build: Build<37>. 
* Windows: Windows<35>. 
* macOS: macOS<26>. 
* IDLE: IDLE<18>. 
* Tools/Demos: Tools/Demos<26>. 
* C API: C API<36>. 

@end menu

@node Security<27>,Core and Builtins<38>,,Python 3 11 0 alpha 1
@anchor{whatsnew/changelog id328}@anchor{1b43}
@subsubsection Security



@itemize -

@item 
bpo-42278@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42278}: Replaced usage of @ref{1b44,,tempfile.mktemp()} with
@ref{1435,,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{a07,,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{91,,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{cf,,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{73,,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<38>,Library<39>,Security<27>,Python 3 11 0 alpha 1
@anchor{whatsnew/changelog id329}@anchor{1b45}
@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{9e5,,types.GenericAlias} objects.

@item 
bpo-45155@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45155}: @ref{1b46,,int.to_bytes()} and @ref{1b07,,int.from_bytes()} now take a
default value of @code{"big"} for the @code{byteorder} argument.
@ref{1b46,,int.to_bytes()} also takes a default value of @code{1} for the
@code{length} argument.

@item 
bpo-44219@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44219}: Release the GIL while performing @code{isatty} system calls on
arbitrary file descriptors. In particular, this affects @ref{1b47,,os.isatty()},
@ref{1b48,,os.device_encoding()} and @ref{9b7,,io.TextIOWrapper}. By extension,
@ref{739,,io.open()} in text mode is also affected. This change solves a
deadlock in @ref{1b47,,os.isatty()}. Patch by Vincent Michel in bpo-44219@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44219}.

@item 
bpo-44959@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44959}: Added fallback to extension modules with '.sl' suffix on HP-UX

@item 
bpo-45121@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45121}: Fix issue where @code{Protocol.__init__} raises @code{RecursionError}
when it's called directly or via @code{super()}. Patch provided by Yurii
Karabas.

@item 
bpo-44348@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44348}: The deallocator function of the @ref{7d0,,BaseException} type now
uses the trashcan mechanism to prevent stack overflow. For example, when a
@ref{f63,,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{315,,open()}, @ref{739,,io.open()}, @ref{314,,codecs.open()} and
@ref{938,,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{104,,traceback} module was using qualname already).

@item 
bpo-34561@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34561}: List sorting now uses the merge-ordering strategy from Munro
and Wild's @code{powersort()}. Unlike the former strategy, this is provably
near-optimal in the entropy of the distribution of run lengths. Most uses
of @code{list.sort()} probably won't see a significant time difference, but
may see significant improvements in cases where the former strategy was
exceptionally poor. However, as these are all fast linear-time
approximations to a problem that's inherently at best quadratic-time to
solve truly optimally, it's also possible to contrive cases where the
former strategy did better.

@item 
bpo-45056@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45056}: Compiler now removes trailing unused constants from co_consts.

@item 
bpo-45020@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45020}: Add a new command line option, "-X frozen_modules=[on|off]" to
opt out of (or into) using optional frozen modules.  This defaults to "on"
(or "off" if it's running out of the source tree).

@item 
bpo-45012@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45012}: In @ref{b2,,posix}, release GIL during @code{stat()}, @code{lstat()},
and @code{fstatat()} syscalls made by @ref{19bd,,os.DirEntry.stat()}. Patch by
Stanisław Skonieczny.

@item 
bpo-45018@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45018}: Fixed pickling of range iterators that iterated for over
@code{2**32} times.

@item 
bpo-45000@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45000}: A @ref{18e,,SyntaxError} is now raised when trying to delete
@ref{9d3,,__debug__}. Patch by Donghee Na.

@item 
bpo-44963@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44963}: Implement @code{send()} and @code{throw()} methods for
@code{anext_awaitable} objects. Patch by Pablo Galindo.

@item 
bpo-44962@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44962}: Fix a race in WeakKeyDictionary, WeakValueDictionary and
WeakSet when two threads attempt to commit the last pending removal. This
fixes asyncio.create_task and fixes a data loss in asyncio.run where
shutdown_asyncgens is not run

@item 
bpo-24234@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24234}: Implement the @code{__bytes__()} special method on the
@ref{192,,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{197,,complex} type, so a complex number @code{z} passes an @code{isinstance(z,
typing.SupportsComplex)} check.

@item 
bpo-44954@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44954}: Fixed a corner case bug where the result of
@code{float.fromhex('0x.8p-1074')} was rounded the wrong way.

@item 
bpo-44947@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44947}: Refine the syntax error for trailing commas in import
statements. Patch by Pablo Galindo.

@item 
bpo-44945@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44945}: Specialize the BINARY_ADD instruction using the PEP 659
machinery. Adds five new instructions:


@itemize *

@item 
BINARY_ADD_ADAPTIVE

@item 
BINARY_ADD_FLOAT

@item 
BINARY_ADD_INT

@item 
BINARY_ADD_UNICODE

@item 
BINARY_ADD_UNICODE_INPLACE_FAST
@end itemize

@item 
bpo-44929@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44929}: Fix some edge cases of @code{enum.Flag} string representation in
the REPL. Patch by Pablo Galindo.

@item 
bpo-44914@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44914}: Class version tags are no longer recycled.

This means that a version tag serves as a unique identifier for the state
of a class. We rely on this for effective specialization of the LOAD_ATTR
and other instructions.

@item 
bpo-44698@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44698}: Restore behaviour of complex exponentiation with integer-valued
exponent of type @ref{196,,float} or @ref{197,,complex}.

@item 
bpo-44895@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44895}: A debug variable 
@geindex PYTHONDUMPREFSFILE
@geindex 環境變數; PYTHONDUMPREFSFILE
@ref{1b49,,PYTHONDUMPREFSFILE} is added for
creating a dump file which is generated by @ref{62e,,--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{18e,,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{10a,,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{1a2,,NotImplemented}.

@item 
bpo-44661@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44661}: Update @code{property_descr_set} to use vectorcall if possible.
Patch by Donghee Na.

@item 
bpo-44662@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44662}: Add @code{__module__} to @code{types.Union}. This also fixes
@code{types.Union} issues with @code{typing.Annotated}. Patch provided by Yurii
Karabas.

@item 
bpo-44655@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44655}: Include the name of the type in unset __slots__ attribute
errors. Patch by Pablo Galindo

@item 
bpo-44655@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44655}: Don't include a missing attribute with the same name as the
failing one when offering suggestions for missing attributes. Patch by
Pablo Galindo

@item 
bpo-44646@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44646}: Fix the hash of the union type: it no longer depends on the
order of arguments.

@item 
bpo-44636@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44636}: Collapse union of equal types. E.g. the result of @code{int | int}
is now @code{int}. Fix comparison of the union type with non-hashable
objects. E.g. @code{int | str == @{@}} no longer raises a TypeError.

@item 
bpo-44611@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44611}: On Windows, @ref{73f,,os.urandom()}: uses BCryptGenRandom API
instead of CryptGenRandom API which is deprecated from Microsoft Windows
API. Patch by Donghee Na.

@item 
bpo-44635@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44635}: Convert @code{None} to @code{type(None)} in the union type
constructor.

@item 
bpo-26280@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26280}: Implement adaptive specialization for BINARY_SUBSCR

Three specialized forms of BINARY_SUBSCR are added:


@itemize *

@item 
BINARY_SUBSCR_LIST_INT

@item 
BINARY_SUBSCR_TUPLE_INT

@item 
BINARY_SUBSCR_DICT
@end itemize

@item 
bpo-44589@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44589}: Mapping patterns in @code{match} statements with two or more equal
literal keys will now raise a @ref{18e,,SyntaxError} at compile-time.

@item 
bpo-44606@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44606}: Fix @code{__instancecheck__} and @code{__subclasscheck__} for the
union type.

@item 
bpo-42073@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42073}: The @code{@@classmethod} decorator can now wrap other
classmethod-like descriptors.

@item 
bpo-41972@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41972}: Tuned the string-searching algorithm of fastsearch.h to have a
shorter inner loop for most cases.

@item 
bpo-44590@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44590}: All necessary data for executing a Python function (local
variables, stack, etc) is now kept in a per-thread stack. Frame objects
are lazily allocated on demand. This increases performance by about 7% on
the standard benchmark suite. Introspection and debugging are unaffected
as frame objects are always available when needed. Patch by Mark Shannon.

@item 
bpo-44584@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44584}: The threading debug (@code{PYTHONTHREADDEBUG} environment
variable) is deprecated in Python 3.10 and will be removed in Python 3.12.
This feature requires a debug build of Python. Patch by Victor Stinner.

@item 
bpo-43895@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43895}: An obsolete internal cache of shared object file handles added
in 1995 that attempted, but did not guarantee, that a .so would not be
dlopen'ed twice to work around flaws in mid-1990s posix-ish operating
systems has been removed from dynload_shlib.c.

@item 
bpo-44490@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44490}: @ref{10a,,typing} now searches for type parameters in
@code{types.Union} objects. @code{get_type_hints} will also properly resolve
annotations with nested @code{types.Union} objects. Patch provided by Yurii
Karabas.

@item 
bpo-43950@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43950}: Code objects can now provide the column information for
instructions when available. This is levaraged during traceback printing
to show the expressions responsible for errors.

Contributed by Pablo Galindo, Batuhan Taskaya and Ammar Askar as part of
@geindex Python Enhancement Proposals; PEP 657
PEP 657@footnote{https://peps.python.org/pep-0657/}.

@item 
bpo-44562@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44562}: Remove uses of @ref{16f7,,PyObject_GC_Del()} in error path when
initializing @ref{9e5,,types.GenericAlias}.

@item 
bpo-41486@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41486}: Fix a memory consumption and copying performance regression in
earlier 3.10 beta releases if someone used an output buffer larger than
4GiB with zlib.decompress on input data that expands that large.

@item 
bpo-43908@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43908}: Heap types with the @ref{3cd,,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{97b,,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{7fa,,hash()} of
@ref{c3d,,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{198,,TypeError} is now raised instead of an
@ref{5e8,,AttributeError} in @ref{186,,with} and @ref{185,,async with}
statements for objects which do not support the @ref{1e1,,context manager} or
@ref{7e8,,asynchronous context manager} protocols correspondingly.

@item 
bpo-44297@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44297}: Make sure that the line number is set when entering a
comprehension scope. This ensures that backtraces including generator
expressions show the correct line number.

@item 
bpo-44456@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44456}: Improve the syntax error when mixing positional and keyword
patterns. Patch by Pablo Galindo.

@item 
bpo-44409@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44409}: Fix error location information for tokenizer errors raised on
initialization of the tokenizer. Patch by Pablo Galindo.

@item 
bpo-44396@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44396}: Fix a possible crash in the tokenizer when raising syntax
errors for unclosed strings. Patch by Pablo Galindo.

@item 
bpo-44376@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44376}: Exact integer exponentiation (like @code{i**2} or @code{pow(i, 2)})
with a small exponent is much faster, due to reducing overhead in such
cases.

@item 
bpo-44313@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44313}: Directly imported objects and modules (through import and from
import statements) don't generate @code{LOAD_METHOD}/@code{CALL_METHOD} for
directly accessed objects on their namespace. They now use the regular
@code{LOAD_ATTR}/@code{CALL_FUNCTION}.

@item 
bpo-44338@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44338}: Implement adaptive specialization for LOAD_GLOBAL

Two specialized forms of LOAD_GLOBAL are added:


@itemize *

@item 
LOAD_GLOBAL_MODULE

@item 
LOAD_GLOBAL_BUILTIN
@end itemize

@item 
bpo-44368@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44368}: Improve syntax errors for invalid "as" targets. Patch by Pablo
Galindo

@item 
bpo-44349@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44349}: Fix an edge case when displaying text from files with encoding
in syntax errors. Patch by Pablo Galindo.

@item 
bpo-44337@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44337}: Initial implementation of adaptive specialization of LOAD_ATTR

Four specialized forms of LOAD_ATTR are added:


@itemize *

@item 
LOAD_ATTR_SLOT

@item 
LOAD_ATTR_SPLIT_KEYS

@item 
LOAD_ATTR_WITH_HINT

@item 
LOAD_ATTR_MODULE
@end itemize

@item 
bpo-44335@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44335}: Fix a regression when identifying incorrect characters in
syntax errors. Patch by Pablo Galindo

@item 
bpo-43693@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43693}: Computation of the offsets of cell variables is done in the
compiler instead of at runtime. This reduces the overhead of handling cell
and free variables, especially in the case where a variable is both an
argument and cell variable.

@item 
bpo-44317@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44317}: Improve tokenizer error with improved locations. Patch by Pablo
Galindo.

@item 
bpo-44304@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44304}: Fix a crash in the @ref{d4,,sqlite3} module that happened when the
garbage collector clears @code{sqlite.Statement} objects. Patch by Pablo
Galindo

@item 
bpo-44305@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44305}: Improve error message for @code{try} blocks without @code{except} or
@code{finally} blocks. Patch by Pablo Galindo.

@item 
bpo-43413@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43413}: Constructors of subclasses of some builtin classes (e.g.
@ref{60c,,tuple}, @ref{24d,,list}, @ref{7eb,,frozenset}) no longer accept
arbitrary keyword arguments. [reverted in 3.11a4] Subclass of @ref{184,,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{f3f,,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{82c,,str.format()}.

@item 
bpo-11105@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11105}: When compiling @ref{4be,,ast.AST} objects with recursive
references through @ref{4ac,,compile()}, the interpreter doesn't crash anymore
instead it raises a @ref{f63,,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<39>,Documentation<32>,Core and Builtins<38>,Python 3 11 0 alpha 1
@anchor{whatsnew/changelog id330}@anchor{1b4a}
@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{8a0,,threading.Lock.acquire()}
method now uses the monotonic clock (@ref{d82,,time.CLOCK_MONOTONIC}) for
the timeout, rather than using the system clock
(@ref{8a1,,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{f3,,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{13e5,,Thread.join()} method of the @ref{f3,,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{8a4,,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{8a4,,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{1b4b,,unittest.TestCase.debug()} raises now a
@ref{11df,,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{c45,,copyfile()},
@ref{c46,,copy()}, @ref{c47,,copy2()} raising
@ref{264,,FileNotFoundError} when source is a directory, which should raise
@ref{1254,,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{205,,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{8a4,,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{722,,ParsingError} class, the @code{readfp()} method of
the @ref{4d9,,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{8dc,,unicodedata.normalize()}. Patch by Donghee Na.

@item 
bpo-35474@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35474}: Calling @ref{1b4c,,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{8b9,,typing.get_type_hints()} now works with
@ref{568,,Final} wrapped in @ref{1afa,,ForwardRef}.

@item 
bpo-45162@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45162}: Remove many old deprecated @ref{10c,,unittest} features:


@itemize *

@item 
"@code{fail*}" and "@code{assert*}" aliases of @ref{2b3,,TestCase} methods.

@item 
Broken from start @ref{2b3,,TestCase} method @code{assertDictContainsSubset()}.

@item 
Ignored @code{<unittest.TestLoader.loadTestsFromModule> TestLoader.loadTestsFromModule()} parameter `use_load_tests'.

@item 
Old alias @code{_TextTestResult} of @ref{74d,,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{582,,__getitem__()} methods of
@ref{936,,xml.dom.pulldom.DOMEventStream}, @ref{937,,wsgiref.util.FileWrapper}
and @ref{938,,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{934,,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{1368,,unittest.TestResult} methods
@ref{1b4d,,addFailure()},
@ref{1b4e,,addError()},
@ref{1b4f,,addSkip()} and
@ref{1b50,,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{10c,,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{935,,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{8aa,,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{1367,,run()} now always return a
@ref{1368,,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{10c,,unittest}:


@itemize *

@item 
Functions registered with @ref{c37,,addModuleCleanup()} were not called unless the user defines @code{tearDownModule()} in their test module.

@item 
Functions registered with @ref{c38,,addClassCleanup()} were not called if @code{tearDownClass} is set to @code{None}.

@item 
Buffering in @ref{1368,,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{10d,,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{847,,gzip.compress()} and
@ref{140e,,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{184,,set} and @ref{7eb,,frozenset} objects are
always @ref{91,,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{11b,,webbrowser} itself. Patch by Donghee Na.

@item 
bpo-44955@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44955}: Method @ref{154b,,stopTestRun()} is now always
called in pair with method @ref{154a,,startTestRun()} for
@ref{1368,,TestResult} objects implicitly created in
@ref{1367,,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{1b51,,ReadError} when a zlib error
occurs during file extraction.

@item 
bpo-44935@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44935}: @ref{dc,,subprocess} on Solaris now also uses
@ref{529,,os.posix_spawn()} for better performance.

@item 
bpo-44911@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44911}: @ref{35f,,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{1b0d,,argparse.BooleanOptionalAction}'s default value is no
longer printed twice when used with
@ref{1b52,,argparse.ArgumentDefaultsHelpFormatter}.

@item 
bpo-44860@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44860}: Fix the @code{posix_user} scheme in @ref{e1,,sysconfig} to not depend
on @ref{b29,,sys.platlibdir}.

@item 
bpo-44859@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44859}: Improve error handling in @ref{d4,,sqlite3} and raise more
accurate exceptions.


@itemize *

@item 
@ref{181e,,MemoryError} is now raised instead of @ref{1adc,,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{1adc,,sqlite3.Warning} when the statement contains surrogate characters in @code{Connection.__call__()} and @code{Cursor.execute()}.

@item 
@ref{198,,TypeError} is now raised instead of @ref{2eb,,ValueError} for non-string script argument in @code{Cursor.executescript()}.

@item 
@ref{2eb,,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{10f9,,os.set_inheritable()} function on FreeBSD 14 for
file descriptor opened with the @ref{116d,,O_PATH} flag: ignore the
@ref{b4b,,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{181e,,MemoryError} raised in user-defined functions will now
produce a @code{MemoryError} in @ref{d4,,sqlite3}. @ref{a78,,OverflowError} will
now be converted to @ref{1b53,,DataError}. Previously
@ref{1b54,,OperationalError} was produced in these cases.

@item 
bpo-44822@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44822}: @ref{d4,,sqlite3} user-defined functions and aggregators returning
@ref{169,,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{482,,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{565,,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{14ee,,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{6f9,,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{dc5,,getattr()} on
@ref{4ae,,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{1b55,,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{fdc,,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{87f,,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{a78,,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{22f,,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{1759,,inspect.getsource()}
when examining a class in the interactive session. Instead of
@ref{198,,TypeError}, it should be @ref{2c0,,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{60,,fnmatch}, the cache size for compiled regex patterns
(@ref{bd9,,functools.lru_cache()}) was bumped up from 256 to 32768, affecting
functions: @ref{1b56,,fnmatch.fnmatch()}, @ref{1b57,,fnmatch.fnmatchcase()},
@ref{1b58,,fnmatch.filter()}.

@item 
bpo-41928@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41928}: Update @ref{c45,,shutil.copyfile()} to raise
@ref{264,,FileNotFoundError} instead of confusing @ref{1254,,IsADirectoryError}
when a path ending with a @code{os.path.sep} does not exist;
@ref{c46,,shutil.copy()} and @ref{c47,,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{104,,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{acf,,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{117a,,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{1b59,,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{57a,,email.message.EmailMessage}.

@item 
bpo-44468@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44468}: @ref{8b9,,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{d4,,sqlite3} authorizer callback by
passing @ref{87e,,None} to @ref{5a3,,set_authorizer()}. Patch
by Erlend E. Aasland.

@item 
bpo-43977@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43977}: Set the proper @ref{1b5a,,Py_TPFLAGS_MAPPING} and
@ref{1b5b,,Py_TPFLAGS_SEQUENCE} flags for subclasses created before a
parent has been registered as a @ref{abe,,collections.abc.Mapping} or
@ref{13c5,,collections.abc.Sequence}.

@item 
bpo-44482@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44482}: Fix very unlikely resource leak in @ref{68,,glob} in alternate
Python implementations.

@item 
bpo-44466@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44466}: The @ref{5c,,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{198,,TypeError} is now raised instead of an
@ref{5e8,,AttributeError} in @ref{7e7,,contextlib.ExitStack.enter_context()} and
@ref{7e9,,contextlib.AsyncExitStack.enter_async_context()} for objects which do
not support the @ref{1e1,,context manager} or @ref{7e8,,asynchronous context manager} protocols correspondingly.

@item 
bpo-44404@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44404}: @ref{f6,,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{107f,,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{978,,Py_TPFLAGS_HAVE_GC} flag. Patch by
Victor Stinner.

@item 
bpo-44422@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44422}: The @ref{1b5c,,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{198,,TypeError}.

@item 
bpo-44389@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44389}: Fix deprecation of @ref{1b5d,,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{d5,,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{e1,,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{86a,,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{862,,logging.getLevelNamesMapping()}

@item 
bpo-44260@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44260}: The @ref{1b5e,,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{67,,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{932,,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{d4,,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{213,,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{1917,,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{ad9,,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{6e,,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{6c,,hashlib}
algorithms support.

@item 
bpo-44095@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44095}: @ref{8cd,,zipfile.Path} now supports @ref{8ce,,zipfile.Path.stem},
@ref{8d0,,zipfile.Path.suffixes}, and @ref{8cf,,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{10a,,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{ad9,,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{f42,,pkgutil.iter_modules()} with a list of @ref{266,,pathlib.Path} objects

@item 
bpo-44059@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44059}: Register the SerenityOS Browser in the @ref{11b,,webbrowser}
module.

@item 
bpo-36515@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36515}: The @ref{6c,,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{110,,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{110,,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{d30,,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{5e8,,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{d4,,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{181e,,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{181e,,MemoryError} in @ref{68f,,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{848,,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{735,,importlib.import_module()} and @ref{1268,,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{941,,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{a48,,traceback.print_exception()}, @ref{a46,,traceback.format_exception()} and
@ref{a47,,traceback.format_exception_only()}.

@item 
bpo-33809@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33809}: Add the @ref{8ab,,traceback.TracebackException.print()} method which
prints the formatted exception information.

@item 
bpo-42862@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42862}: @ref{d4,,sqlite3} now utilizes @ref{bd9,,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{11bd,,subprocess.check_output()} now raises @ref{2eb,,ValueError}
when the invalid keyword argument `check' is passed by user code.
Previously such use would fail later with a @ref{198,,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{d4,,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{82,,inspect} - by Anthony Sottile.

@item 
bpo-41402@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41402}: Fix @ref{1b5f,,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{1072,,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{f3,,threading} synchronization objects:
@ref{1357,,Semaphore}, @ref{1358,,BoundedSemaphore},
@ref{1359,,Event} and @ref{13e4,,Barrier}.

@item 
bpo-5846@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5846}: Deprecated the following @ref{10c,,unittest} functions, scheduled
for removal in Python 3.13:


@itemize *

@item 
@code{findTestCases()}

@item 
@code{makeSuite()}

@item 
@code{getTestCaseNames()}
@end itemize

Use @ref{58d,,TestLoader} methods instead:


@itemize *

@item 
@ref{58e,,unittest.TestLoader.loadTestsFromModule()}

@item 
@ref{58f,,unittest.TestLoader.loadTestsFromTestCase()}

@item 
@ref{590,,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{d17,,contextlib.asynccontextmanager()} to match
@ref{1403,,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{4ee,,email.utils.getaddresses()} now accepts
@ref{1b60,,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{d4,,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<32>,Tests<34>,Library<39>,Python 3 11 0 alpha 1
@anchor{whatsnew/changelog id331}@anchor{1b61}
@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{1b62,,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{1b46,,int.to_bytes()} and
@ref{1b07,,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{6d3,,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{192c,,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{ad0,,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{16bb,,textwrap.wrap()},
@ref{16ba,,textwrap.fill()}, and @ref{11cb,,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{137,,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{152e,,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{33,,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{13bd,,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<34>,Build<37>,Documentation<32>,Python 3 11 0 alpha 1
@anchor{whatsnew/changelog id332}@anchor{1b63}
@subsubsection Tests



@itemize -

@item 
bpo-40173@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40173}: Fix @ref{1b64,,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{330,,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{d95,,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{b29,,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{1b3,,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{161a,,id()} is preserved when @code{obj
* 1} is used on @ref{169,,str} and @ref{192,,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{1b65,,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{bf0,,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{1a03,,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<37>,Windows<35>,Tests<34>,Python 3 11 0 alpha 1
@anchor{whatsnew/changelog id333}@anchor{1b66}
@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<35>,macOS<26>,Build<37>,Python 3 11 0 alpha 1
@anchor{whatsnew/changelog id334}@anchor{1b67}
@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{f3,,threading}, such as with @ref{8a0,,threading.Lock.acquire()} or
@ref{1b68,,threading.Condition.wait()}.

@item 
bpo-42686@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42686}: Build @ref{d4,,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<26>,IDLE<18>,Windows<35>,Python 3 11 0 alpha 1
@anchor{whatsnew/changelog id335}@anchor{1b69}
@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{f40,,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<18>,Tools/Demos<26>,macOS<26>,Python 3 11 0 alpha 1
@anchor{whatsnew/changelog id336}@anchor{1b6a}
@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{a07,,match} statement's @ref{a06,,soft keywords}: @ref{a07,,match}, @ref{a07,,case}, and
@ref{a08,,_}. 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<26>,C API<36>,IDLE<18>,Python 3 11 0 alpha 1
@anchor{whatsnew/changelog id337}@anchor{1b6b}
@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<36>,,Tools/Demos<26>,Python 3 11 0 alpha 1
@anchor{whatsnew/changelog id338}@anchor{1b6c}
@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{2eb,,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{1b6d,,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{1789,,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{3c1,,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{951,,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{bb3,,Py_RunMain()} now resets @code{PyImport_Inittab} to
its initial value at exit. It must be possible to call
@ref{1a5f,,PyImport_AppendInittab()} or @ref{1a60,,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{988,,PyThreadState} members like
@code{_tstate->trash_delete_nesting}, whereas the @ref{988,,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{995,,受限 API 的內容} now shows the public name
@ref{984,,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{1aca,,Py_IS_TYPE()} no longer uses @ref{3c7,,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{3c7,,Py_TYPE()} and @ref{97d,,Py_SIZE()} macros to
static inline functions. The @ref{97c,,Py_SET_TYPE()} and
@ref{97e,,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{97a,,PyType_Ready()} function now raises an error if a
type is defined with the @ref{978,,Py_TPFLAGS_HAVE_GC} flag set but has no
traverse function (@ref{979,,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{3f4,,PyConfig} API of the @ref{63e,,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{a8e,,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{950,,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{1b6e}
@subsection Python 3.10.0 beta 1


`Release date: 2021-05-03'

@menu
* Security: Security<28>. 
* Core and Builtins: Core and Builtins<39>. 
* Library: Library<40>. 
* Documentation: Documentation<33>. 
* Tests: Tests<35>. 
* Build: Build<38>. 
* Windows: Windows<36>. 
* macOS: macOS<27>. 
* IDLE: IDLE<19>. 
* C API: C API<37>. 

@end menu

@node Security<28>,Core and Builtins<39>,,Python 3 10 0 beta 1
@anchor{whatsnew/changelog id339}@anchor{1b6f}
@subsubsection Security



@itemize -

@item 
bpo-43434@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43434}: Creating @ref{548,,sqlite3.Connection} objects now also produces
@code{sqlite3.connect} and @code{sqlite3.connect/handle} @ref{1b70,,auditing events}. Previously these events were only produced by
@ref{5a0,,sqlite3.connect()} calls. Patch by Erlend E. Aasland.

@item 
bpo-43998@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43998}: The @ref{d5,,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{355,,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{110,,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{a38,,sqlite3.Connection.enable_load_extension()}, and
@ref{6d8,,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{59a,,glob.glob()} and
@ref{a01,,glob.iglob()}.

@item 
bpo-36384@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36384}: @ref{84,,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{b51,,socket.inet_aton()} treats leading zeros as octal notation. glibc
implementation of modern @ref{b52,,inet_pton()} does not accept any
leading zeros. For a while the @ref{84,,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{1b71,,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{73,,http.client} module.
@end itemize

@node Core and Builtins<39>,Library<40>,Security<28>,Python 3 10 0 beta 1
@anchor{whatsnew/changelog id340}@anchor{1b72}
@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{1b73,,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.

@item 
bpo-43908@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43908}: Make @ref{be,,re} types immutable. Patch by Erlend E. Aasland.

@item 
bpo-43908@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43908}: Make the @ref{4b9,,array.array} type immutable. Patch by Erlend
E. Aasland.

@item 
bpo-43901@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43901}: Change class and module objects to lazy-create empty
annotations dicts on demand.  The annotations dicts are stored in the
object's __dict__ for backwards compatibility.

@item 
bpo-43892@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43892}: Match patterns now use new dedicated AST nodes (@code{MatchValue},
@code{MatchSingleton}, @code{MatchSequence}, @code{MatchStar}, @code{MatchMapping},
@code{MatchClass}) rather than reusing expression AST nodes. @code{MatchAs} and
@code{MatchOr} are now defined as pattern nodes rather than as expression
nodes. Patch by Nick Coghlan.

@item 
bpo-42725@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42725}: Usage of @code{await}/@code{yield}/@code{yield from} and named
expressions within an annotation is now forbidden when PEP 563 is
activated.

@item 
bpo-43754@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43754}: When performing structural pattern matching (
@geindex Python Enhancement Proposals; PEP 634
PEP 634@footnote{https://peps.python.org/pep-0634/}),
captured names are now left unbound until the `entire' pattern has matched
successfully.

@item 
bpo-42737@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42737}: Annotations for complex targets (everything beside simple
names) no longer cause any runtime effects with @code{from __future__ import
annotations}.

@item 
bpo-43914@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43914}: @ref{18e,,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{9a4,,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{450,,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{1b74,,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{451,,@@staticmethod}) and class methods
(@ref{489,,@@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{1b75,,__match_args__} is no longer allowed to be a
list.

@item 
bpo-43683@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43683}: Add GEN_START opcode. Marks start of generator, including
async, or coroutine and handles sending values to a newly created
generator or coroutine.

@item 
bpo-43105@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43105}: Importlib now resolves relative paths when creating module spec
objects from file locations.

@item 
bpo-43682@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43682}: Static methods (@ref{451,,@@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{f63,,RecursionError} is now raised instead.

@item 
bpo-38530@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38530}: When printing @ref{5e8,,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<40>,Documentation<33>,Core and Builtins<39>,Python 3 10 0 beta 1
@anchor{whatsnew/changelog id341}@anchor{1b76}
@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{1b77,,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{31d,,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{8b9,,typing.get_type_hints()} receives no namespace dictionary
arguments, @ref{8b9,,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{107,,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{10e9,,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{10e,,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{a0d,,inspect.get_annotations()}, which safely computes the
annotations defined on an object.  It works around the quirks of accessing
the annotations from various types of objects, and makes very few
assumptions about the object passed in. @ref{a0d,,inspect.get_annotations()}
can also correctly un-stringize stringized annotations.

@ref{22f,,inspect.signature()}, @code{inspect.from_callable()}, and
@code{inspect.from_function()} now call @ref{a0d,,inspect.get_annotations()} to
retrieve annotations.  This means @ref{22f,,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{d5,,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{d5,,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{f37,,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{a5f,,bz2.BZ2File},
@ref{654,,gzip.GzipFile}, and @ref{1207,,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{739,,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{5df,,KeyError} raised in @ref{8b9,,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{4b2,,subprocess.Popen} args are provided as a string or
as @ref{266,,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{2ad,,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{a31,,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{6b,,gzip} and @ref{8e,,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{d5,,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{10a,,typing} module by adding
@code{TypeGuard}.

@item 
bpo-25264@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25264}: @ref{262,,os.path.realpath()} now accepts a `strict' keyword-only
argument. When set to @code{True}, @ref{2c0,,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{482,,typing.ParamSpec} are now instances of the new classes
@ref{9c2,,typing.ParamSpecArgs} and @ref{9c3,,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{9f9,,fileinput.input()} and @ref{938,,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{1b75,,__match_args__} generation
could fail for some @ref{33,,dataclasses}.

@item 
bpo-43752@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43752}: Fix @ref{d4,,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{f6,,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{35c,,threading.current_thread()}

@item 
@code{activeCount} => @ref{35d,,threading.active_count()}

@item 
@code{Condition.notifyAll} => @ref{357,,threading.Condition.notify_all()}

@item 
@code{Event.isSet} => @ref{358,,threading.Event.is_set()}

@item 
@code{Thread.setName} => @ref{2a0,,threading.Thread.name}

@item 
@code{thread.getName} => @ref{2a0,,threading.Thread.name}

@item 
@code{Thread.isDaemon} => @ref{35a,,threading.Thread.daemon}

@item 
@code{Thread.setDaemon} => @ref{35a,,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{1b78,,turtle.textinput()} and @ref{1b79,,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{d6e,,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{1072,,tarfile.open()} when @ref{8e,,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{192,,bytes} @code{separator} argument in
@code{urllib.parse.parse_qs} and @code{urllib.parse.parse_qsl} when parsing
@ref{169,,str} query strings. Previously, this raised a @code{TypeError}.

@item 
bpo-43296@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43296}: Improve @ref{d4,,sqlite3} error handling: @code{sqlite3_value_blob()}
errors that set @code{SQLITE_NOMEM} now raise @ref{181e,,MemoryError}. Patch by
Erlend E. Aasland.

@item 
bpo-43312@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43312}: New functions @ref{898,,sysconfig.get_preferred_scheme()} and
@ref{1ada,,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{d6b,,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{e1,,sysconfig}.

@item 
bpo-41282@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41282}: @code{distutils.sysconfig} has been merged to @ref{e1,,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{4dc,,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{8b9,,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{2f1,,asyncio.get_event_loop()} without
running event loop. Emit deprecation warning for @ref{b,,asyncio} functions
which implicitly create a @ref{dc1,,Future} or
@ref{1c7,,Task} objects if there is no running event loop and no
explicit `loop' argument is passed: @ref{e6c,,ensure_future()},
@ref{1b7a,,wrap_future()}, @ref{80c,,gather()},
@ref{c5c,,shield()}, @ref{4c1,,as_completed()} and constructors of
@ref{dc1,,Future}, @ref{1c7,,Task},
@ref{1b7b,,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{8e,,lzma} / @ref{139,,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{a36,,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{19bc,,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{1b7c,,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{a1d,,pathlib.Path.stat()} and @ref{a1e,,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{c00,,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{103d,,pathlib.Path.expanduser()} and @ref{103e,,home()} now
consistently raise @ref{244,,RuntimeError} exception when a home directory
cannot be resolved. Previously a @ref{5df,,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{a36,,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{19a9,,ctypes.c_wchar_p} type: embedded null characters would cause a
@ref{2eb,,ValueError} to be raised. Patch by Zackery Spytz.
@end itemize

@node Documentation<33>,Tests<35>,Library<40>,Python 3 10 0 beta 1
@anchor{whatsnew/changelog id342}@anchor{1b7d}
@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{1b5a,,Py_TPFLAGS_MAPPING} and
@ref{1b5b,,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<35>,Build<38>,Documentation<33>,Python 3 10 0 beta 1
@anchor{whatsnew/changelog id343}@anchor{1b7e}
@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{12f3,,os.replace()} rather than @ref{12f2,,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{a44,,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<38>,Windows<36>,Tests<35>,Python 3 10 0 beta 1
@anchor{whatsnew/changelog id344}@anchor{1b7f}
@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<36>,macOS<27>,Build<38>,Python 3 10 0 beta 1
@anchor{whatsnew/changelog id345}@anchor{1b80}
@subsubsection Windows



@itemize -

@item 
bpo-35306@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35306}: Adds additional arguments to @ref{1b81,,os.startfile()} function.

@item 
bpo-43538@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43538}: Avoid raising errors from @ref{c02,,pathlib.Path.exists()} when
passed an invalid filename.

@item 
bpo-38822@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38822}: Fixed @ref{26d,,os.stat()} failing on inaccessible directories with
a trailing slash, rather than falling back to the parent directory's
metadata. This implicitly affected @ref{bfa,,os.path.exists()} and
@ref{bfc,,os.path.isdir()}.

@item 
bpo-26227@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26227}: Fixed decoding of host names in @ref{1b82,,socket.gethostbyaddr()}
and @ref{1b83,,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<27>,IDLE<19>,Windows<36>,Python 3 10 0 beta 1
@anchor{whatsnew/changelog id346}@anchor{1b84}
@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<19>,C API<37>,macOS<27>,Python 3 10 0 beta 1
@anchor{whatsnew/changelog id347}@anchor{1b85}
@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<37>,,IDLE<19>,Python 3 10 0 beta 1
@anchor{whatsnew/changelog id348}@anchor{1b86}
@subsubsection C API



@itemize -

@item 
bpo-43916@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43916}: Add a new @ref{79b,,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{a9b,,PyGC_Enable()}, @ref{a9c,,PyGC_Disable()},
@ref{a9d,,PyGC_IsEnabled()}, corresponding to the functions in the
@ref{64,,gc} module.

@item 
bpo-43908@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43908}: Introduce @ref{3cd,,Py_TPFLAGS_IMMUTABLETYPE} flag for
immutable type objects, and modify @ref{97a,,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{10a8,,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{79e,,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{a97,,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{a98,,Py_IsNone()}, @ref{a99,,Py_IsTrue()}, @ref{a9a,,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{1b87}
@subsection Python 3.10.0 alpha 7


`Release date: 2021-04-05'

@menu
* Security: Security<29>. 
* Core and Builtins: Core and Builtins<40>. 
* Library: Library<41>. 
* Documentation: Documentation<34>. 
* Tests: Tests<36>. 
* Build: Build<39>. 
* Windows: Windows<37>. 
* IDLE: IDLE<20>. 
* C API: C API<38>. 

@end menu

@node Security<29>,Core and Builtins<40>,,Python 3 10 0 alpha 7
@anchor{whatsnew/changelog id349}@anchor{1b88}
@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{ba,,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{62,,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{aed,,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{9fd,,gc.get_objects()},
@ref{9fe,,gc.get_referrers()} and @ref{9ff,,gc.get_referents()}. Patch by Pablo
Galindo.
@end itemize

@node Core and Builtins<40>,Library<41>,Security<29>,Python 3 10 0 alpha 7
@anchor{whatsnew/changelog id350}@anchor{1b89}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-27129@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27129}: Update CPython bytecode magic number.

@item 
bpo-43672@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43672}: Raise ImportWarning when calling find_loader().

@item 
bpo-43660@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43660}: Fix crash that happens when replacing @code{sys.stderr} with a
callable that can remove the object while an exception is being printed.
Patch by Pablo Galindo.

@item 
bpo-27129@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27129}: The bytecode interpreter uses instruction, rather byte, offsets
internally. This reduces the number of EXTENDED_ARG instructions needed
and streamlines instruction dispatch a bit.

@item 
bpo-40645@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40645}: Fix reference leak in the @code{_hashopenssl} extension. Patch
by Pablo Galindo.

@item 
bpo-42134@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42134}: Calls to find_module() by the import system now raise
ImportWarning.

@item 
bpo-41064@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41064}: Improve the syntax error for invalid usage of double starred
elements ('**') in f-strings. Patch by Pablo Galindo.

@item 
bpo-43575@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43575}: Speed up calls to @code{map()} by using the 
@geindex Python Enhancement Proposals; PEP 590
PEP 590@footnote{https://peps.python.org/pep-0590/}
@code{vectorcall} calling convention. Patch by Donghee Na.

@item 
bpo-42137@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42137}: The import system now prefers using @code{__spec__} for
@code{ModuleType.__repr__} over @code{module_repr()}.

@item 
bpo-43452@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43452}: Added micro-optimizations to @code{_PyType_Lookup()} to improve
cache lookup performance in the common case of cache hits.

@item 
bpo-43555@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43555}: Report the column offset for @ref{18e,,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{dbb,,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{13c0,,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{1501,,__exit__()} is always called in with statements, even
for interrupts.
@end itemize

@node Library<41>,Documentation<34>,Core and Builtins<40>,Python 3 10 0 alpha 7
@anchor{whatsnew/changelog id351}@anchor{1b8a}
@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{c43,,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{9da,,index()} method of @ref{4b9,,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{355,,ssl.SSLContext} debug callback
with @ref{1b8b,,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{6e,,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{9b8,,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{a22,,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{1b8c,,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{a3b,,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{1435,,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{73,,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{213,,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{d4,,sqlite3} error handling: If
@code{sqlite3_column_text()} and @code{sqlite3_column_blob()} set
@code{SQLITE_NOMEM}, @ref{181e,,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{d4,,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{18b7,,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{1b8d,,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{c48,,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{1b8e,,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{1b8f,,tempfile.gettempdir()} and @ref{1b90,,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{1b91,,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<34>,Tests<36>,Library<41>,Python 3 10 0 alpha 7
@anchor{whatsnew/changelog id352}@anchor{1b92}
@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{556,,time.monotonic()},
@ref{c71,,time.perf_counter()}, @ref{c72,,time.process_time()}, or
@ref{b27,,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<36>,Build<39>,Documentation<34>,Python 3 10 0 alpha 7
@anchor{whatsnew/changelog id353}@anchor{1b93}
@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<39>,Windows<37>,Tests<36>,Python 3 10 0 alpha 7
@anchor{whatsnew/changelog id354}@anchor{1b94}
@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<37>,IDLE<20>,Build<39>,Python 3 10 0 alpha 7
@anchor{whatsnew/changelog id355}@anchor{1b95}
@subsubsection Windows



@itemize -

@item 
bpo-43440@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43440}: Build @ref{d4,,sqlite3} with the @code{R*Tree} module enabled. Patch
by Erlend E. Aasland.
@end itemize

@node IDLE<20>,C API<38>,Windows<37>,Python 3 10 0 alpha 7
@anchor{whatsnew/changelog id356}@anchor{1b96}
@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<38>,,IDLE<20>,Python 3 10 0 alpha 7
@anchor{whatsnew/changelog id357}@anchor{1b97}
@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{788,,Py_INCREF()} and @ref{789,,Py_DECREF()} functions are now implemented
as opaque function calls, rather than accessing directly the
@ref{a96,,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{5d7,,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{de,,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{1b98}
@subsection Python 3.10.0 alpha 6


`Release date: 2021-03-01'

@menu
* Security: Security<30>. 
* Core and Builtins: Core and Builtins<41>. 
* Library: Library<42>. 
* Documentation: Documentation<35>. 
* Tests: Tests<37>. 
* Build: Build<40>. 
* Windows: Windows<38>. 
* macOS: macOS<28>. 
* IDLE: IDLE<21>. 
* C API: C API<39>. 

@end menu

@node Security<30>,Core and Builtins<41>,,Python 3 10 0 alpha 6
@anchor{whatsnew/changelog id358}@anchor{1b99}
@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<41>,Library<42>,Security<30>,Python 3 10 0 alpha 6
@anchor{whatsnew/changelog id359}@anchor{1b9a}
@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{a94,,PySet_CheckExact()} function to the C-API to
check if an object is an instance of @ref{184,,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{a7a,,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{49e,,eval()} and @ref{49d,,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{18e,,SyntaxError} message for missing comma
in literals. Patch by Pablo Galindo.

@item 
bpo-42819@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42819}: @ref{bf,,readline}: Explicitly disable bracketed paste in the
interactive interpreter, even if it's set in the inputrc, is enabled by
default (eg GNU Readline 8.1), or a user calls
@code{readline.read_init_file()}. The Python REPL has not implemented
bracketed paste support. Also, bracketed mode writes the @code{"\x1b[?2004h"}
escape sequence into stdout which causes test failures in applications
that don't support it. It can still be explicitly enabled by calling
@code{readline.parse_and_bind("set enable-bracketed-paste on")}. Patch by
Dustin Rodrigues.

@item 
bpo-42808@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42808}: Simple calls to @code{type(object)} are now faster due to the
@code{vectorcall} calling convention. Patch by Dennis Sweeney.

@item 
bpo-42217@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42217}: Make the compiler merges same co_code and co_linetable objects
in a module like already did for co_consts.

@item 
bpo-41972@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41972}: Substring search functions such as @code{str1 in str2} and
@code{str2.find(str1)} now sometimes use the "Two-Way" string comparison
algorithm to avoid quadratic behavior on long strings.

@item 
bpo-42128@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42128}: Implement 
@geindex Python Enhancement Proposals; PEP 634
PEP 634@footnote{https://peps.python.org/pep-0634/} (structural pattern matching). Patch by
Brandt Bucher.

@item 
bpo-40692@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40692}: In the @ref{1d6,,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.

@item 
bpo-38302@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38302}: If @ref{9cc,,object.__ipow__()} returns @ref{1a2,,NotImplemented}, the
operator will correctly fall back to @ref{9cd,,object.__pow__()} and
@ref{1a5,,object.__rpow__()} as expected.
@end itemize

@node Library<42>,Documentation<35>,Core and Builtins<41>,Python 3 10 0 alpha 6
@anchor{whatsnew/changelog id360}@anchor{1b9b}
@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{a48,,print_exception()} and
@ref{a46,,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{d4,,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{d4,,sqlite3} error handling:
@code{sqlite3_column_name()} failures now result in @ref{181e,,MemoryError}. Patch
by Erlend E. Aasland.

@item 
bpo-40956@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40956}: Fix segfault in @ref{d6b,,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{1b9c,,readline.get_begidx()} and @ref{1b9d,,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{104,,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{a14,,O_EVTONLY}, @ref{a15,,O_FSYNC},
@ref{a16,,O_SYMLINK} and @ref{a17,,O_NOFOLLOW_ANY} for macOS. Patch by
Donghee Na.

@item 
bpo-42960@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42960}: Adds @ref{1b9e,,resource.RLIMIT_KQUEUES} constant from FreeBSD to
the @ref{c1,,resource} module.

@item 
bpo-42151@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42151}: Make the pure Python implementation of
@ref{12b,,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<35>,Tests<37>,Library<42>,Python 3 10 0 alpha 6
@anchor{whatsnew/changelog id361}@anchor{1b9f}
@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<37>,Build<40>,Documentation<35>,Python 3 10 0 alpha 6
@anchor{whatsnew/changelog id362}@anchor{1ba0}
@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<40>,Windows<38>,Tests<37>,Python 3 10 0 alpha 6
@anchor{whatsnew/changelog id363}@anchor{1ba1}
@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<38>,macOS<28>,Build<40>,Python 3 10 0 alpha 6
@anchor{whatsnew/changelog id364}@anchor{1ba2}
@subsubsection Windows



@itemize -

@item 
bpo-43155@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43155}: @ref{1ba3,,PyCMethod_New()} is now present in @code{python3.lib}.
@end itemize

@node macOS<28>,IDLE<21>,Windows<38>,Python 3 10 0 alpha 6
@anchor{whatsnew/changelog id365}@anchor{1ba4}
@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<21>,C API<39>,macOS<28>,Python 3 10 0 alpha 6
@anchor{whatsnew/changelog id366}@anchor{1ba5}
@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<39>,,IDLE<21>,Python 3 10 0 alpha 6
@anchor{whatsnew/changelog id367}@anchor{1ba6}
@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{1ba7,,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{97f,,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{97f,,Include Files}.

@item 
bpo-40170@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40170}: @ref{c52,,PyExceptionClass_Name()} is now always declared as a
function, in order to hide implementation details. The macro accessed
@ref{1ba8,,PyTypeObject.tp_name} directly.  Patch by Erlend E. Aasland.

@item 
bpo-43239@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43239}: The @ref{1ba9,,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{1baa,,PyIter_Check()} is now always declared as a function, in
order to hide implementation details. The macro accessed
@ref{16e4,,PyTypeObject.tp_iternext} directly. Patch by Erlend E. Aasland.

@item 
bpo-40170@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40170}: Convert @ref{1bab,,PyDescr_IsData()} macro to a function to hide
implementation details: The macro accessed
@ref{1bac,,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{1bad,,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{1bae}
@subsection Python 3.10.0 alpha 5


`Release date: 2021-02-02'

@menu
* Security: Security<31>. 
* Core and Builtins: Core and Builtins<42>. 
* Library: Library<43>. 
* Documentation: Documentation<36>. 
* Tests: Tests<38>. 
* Build: Build<41>. 
* Windows: Windows<39>. 
* macOS: macOS<29>. 
* IDLE: IDLE<22>. 
* C API: C API<40>. 

@end menu

@node Security<31>,Core and Builtins<42>,,Python 3 10 0 alpha 5
@anchor{whatsnew/changelog id368}@anchor{1baf}
@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{1bb0,,ctypes.c_double} and @ref{1bb1,,ctypes.c_longdouble} values.
@end itemize

@node Core and Builtins<42>,Library<43>,Security<31>,Python 3 10 0 alpha 5
@anchor{whatsnew/changelog id369}@anchor{1bb2}
@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{b71,,Py_FatalError()} calls in the compiler with
regular @ref{78e,,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{45e,,Py_Initialize()} /
@ref{45d,,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{18e,,SyntaxError} in some multi-line expressions.

@item 
bpo-42823@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42823}: frame.f_lineno is correct even if frame.f_trace is set to True

@item 
bpo-37324@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37324}: Remove deprecated aliases to
@ref{a6f,,Collections Abstract Base Classes} from the @ref{1e,,collections}
module.

@item 
bpo-41994@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41994}: Fixed possible leak in @code{import} when @code{sys.modules} is not a
@code{dict}.

@item 
bpo-27772@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27772}: In string formatting, preceding the `width' field by @code{'0'} no
longer affects the default alignment for strings.
@end itemize

@node Library<43>,Documentation<36>,Core and Builtins<42>,Python 3 10 0 alpha 5
@anchor{whatsnew/changelog id370}@anchor{1bb3}
@subsubsection Library



@itemize -

@item 
bpo-43108@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43108}: Fixed a reference leak in the @ref{2f,,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{101,,tokenize} by 20-30%.  Patch by
Anthony Sottile.

@item 
bpo-42323@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42323}: Fix @ref{6b9,,math.nextafter()} for NaN on AIX.

@item 
bpo-42955@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42955}: Add @ref{a3b,,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{55d,,TracebackException}'s new @code{compact}
param in @ref{1368,,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{55d,,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{b71,,Py_FatalError()} function and the
@ref{5c,,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{55d,,TracebackException}
to allow it to handle long exception chains.

@item 
bpo-42901@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42901}: [Enum] move member creation from @code{EnumMeta.__new__} to
@code{_proto_member.__set_name__}, allowing members to be created and visible
in @code{__init_subclass__}.

@item 
bpo-42780@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42780}: Fix os.set_inheritable() for O_PATH file descriptors on Linux.

@item 
bpo-42866@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42866}: Fix a reference leak in the @code{getcodec()} function of CJK
codecs. Patch by Victor Stinner.

@item 
bpo-42846@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42846}: Convert the 6 CJK codec extension modules (_codecs_cn,
_codecs_hk, _codecs_iso2022, _codecs_jp, _codecs_kr and _codecs_tw) to the
multiphase initialization API (
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}). Patch by Victor Stinner.

@item 
bpo-42851@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42851}: remove __init_subclass__ support for Enum members

@item 
bpo-42834@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42834}: Make internal caches of the @code{_json} module compatible with
subinterpreters.

@item 
bpo-41748@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41748}: Fix HTMLParser parsing rules for element attributes containing
commas with spaces. Patch by Karl Dubost.

@item 
bpo-40810@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40810}: Require SQLite 3.7.15 or newer. Patch by Erlend E. Aasland.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Convert the _multibytecodec extension module (CJK codecs) to
multi-phase initialization (
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).  Patch by Erlend E. Aasland.

@item 
bpo-42802@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42802}: The distutils @code{bdist_wininst} command deprecated in Python
3.8 has been removed. The distutils @code{bdist_wheel} command is now
recommended to distribute binary packages on Windows.

@item 
bpo-24464@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24464}: The undocumented built-in function
@code{sqlite3.enable_shared_cache} is now deprecated, scheduled for removal
in Python 3.12.  Its use is strongly discouraged by the SQLite3
documentation.  Patch by Erlend E. Aasland.

@item 
bpo-42384@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42384}: Make pdb populate sys.path[0] exactly the same as regular
python execution.

@item 
bpo-42383@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42383}: Fix pdb: previously pdb would fail to restart the debugging
target if it was specified using a relative path and the current directory
changed.

@item 
bpo-42005@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42005}: Fix CLI of @ref{2b,,cProfile} and @ref{b4,,profile} to catch
@ref{1257,,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{2f,,curses} module if available.

@item 
bpo-33289@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33289}: Correct call to @ref{f7,,tkinter.colorchooser} to return RGB
triplet of ints instead of floats.  Patch by Cheryl Sabella.
@end itemize

@node Documentation<36>,Tests<38>,Library<43>,Python 3 10 0 alpha 5
@anchor{whatsnew/changelog id371}@anchor{1bb4}
@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<38>,Build<41>,Documentation<36>,Python 3 10 0 alpha 5
@anchor{whatsnew/changelog id372}@anchor{1bb5}
@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{d4,,sqlite3} tests. Patch by Erlend E.
Aasland.

@item 
bpo-40810@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40810}: In @ref{d4,,sqlite3}, fix @code{CheckTraceCallbackContent} for SQLite
pre 3.7.15.
@end itemize

@node Build<41>,Windows<39>,Tests<38>,Python 3 10 0 alpha 5
@anchor{whatsnew/changelog id373}@anchor{1bb6}
@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{59,,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<39>,macOS<29>,Build<41>,Python 3 10 0 alpha 5
@anchor{whatsnew/changelog id374}@anchor{1bb7}
@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<29>,IDLE<22>,Windows<39>,Python 3 10 0 alpha 5
@anchor{whatsnew/changelog id375}@anchor{1bb8}
@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<22>,C API<40>,macOS<29>,Python 3 10 0 alpha 5
@anchor{whatsnew/changelog id376}@anchor{1bb9}
@subsubsection IDLE



@itemize -

@item 
bpo-43008@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43008}: Make IDLE invoke @ref{a05,,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<40>,,IDLE<22>,Python 3 10 0 alpha 5
@anchor{whatsnew/changelog id377}@anchor{1bba}
@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{1bbb,,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{1bbc}
@subsection Python 3.10.0 alpha 4


`Release date: 2021-01-04'

@menu
* Core and Builtins: Core and Builtins<43>. 
* Library: Library<44>. 
* Documentation: Documentation<37>. 
* Tests: Tests<39>. 
* Build: Build<42>. 
* macOS: macOS<30>. 
* Tools/Demos: Tools/Demos<27>. 
* C API: C API<41>. 

@end menu

@node Core and Builtins<43>,Library<44>,,Python 3 10 0 alpha 4
@anchor{whatsnew/changelog id378}@anchor{1bbd}
@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{1a8,,-c} command line option. Patch by
Victor Stinner.

@item 
bpo-30858@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30858}: Improve error location in expressions that contain assignments.
Patch by Pablo Galindo and Lysandros Nikolaou.

@item 
bpo-42615@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42615}: Remove jump commands made redundant by the deletion of
unreachable bytecode blocks

@item 
bpo-42639@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42639}: Make the @ref{d,,atexit} module state per-interpreter. It is now
safe have more than one @ref{d,,atexit} module instance. Patch by Donghee Na
and Victor Stinner.

@item 
bpo-32381@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32381}: Fix encoding name when running a @code{.pyc} file on Windows:
@ref{1bbe,,PyRun_SimpleFileExFlags()} now uses the correct encoding to
decode the filename.

@item 
bpo-42195@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42195}: The @code{__args__} of the parameterized generics for
@ref{9c1,,typing.Callable} and @ref{9e4,,collections.abc.Callable} are now
consistent.  The @code{__args__} for @ref{9e4,,collections.abc.Callable} are
now flattened while @ref{9c1,,typing.Callable}'s have not changed.  To allow
this change, @ref{9e5,,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{76c,,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/}).

@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<44>,Documentation<37>,Core and Builtins<43>,Python 3 10 0 alpha 4
@anchor{whatsnew/changelog id379}@anchor{1bbf}
@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{1bc0,,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{2ac,,typing.get_args()} and @ref{2ab,,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{dc,,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{fe,,tkinter.simpledialog}),
message boxes (@ref{fc,,tkinter.messagebox}) or color choose dialog
(@ref{f7,,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{1bc1,,collections.deque.remove()}.

@item 
bpo-35728@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35728}: Added a root parameter to @ref{1bc2,,tkinter.font.nametofont()}.

@item 
bpo-15303@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15303}: @ref{f6,,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{2f,,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{1bc3,,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{f6,,tkinter} functions and constructors which need a default
root window raise now @ref{244,,RuntimeError} with descriptive message instead
of obscure @ref{5e8,,AttributeError} or @ref{450,,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{502,,sys.unraisablehook}, rather than logging them directly into
@ref{b2a,,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{a75,,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{10a,,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{e0d,,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{945,,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{104,,traceback} and the interpreter
in formatting of SyntaxError with lineno not set (@ref{104,,traceback} was
changed to match interpreter).

@item 
bpo-42393@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42393}: Raise @ref{a78,,OverflowError} instead of silent truncation in
@ref{a77,,socket.ntohs()} and @ref{a76,,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{a64,,random.randrange()} argument handling to match
@ref{b34,,range()}.


@itemize *

@item 
The integer test and conversion in @code{randrange()} now uses
@ref{1bc4,,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{331,,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{22f,,inspect.signature()} and @ref{93a,,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{1035,,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<37>,Tests<39>,Library<44>,Python 3 10 0 alpha 4
@anchor{whatsnew/changelog id380}@anchor{1bc5}
@subsubsection Documentation



@itemize -

@item 
bpo-17140@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17140}: Add documentation for the
@ref{1bc6,,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<39>,Build<42>,Documentation<37>,Python 3 10 0 alpha 4
@anchor{whatsnew/changelog id381}@anchor{1bc7}
@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<42>,macOS<30>,Tests<39>,Python 3 10 0 alpha 4
@anchor{whatsnew/changelog id382}@anchor{1bc8}
@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<30>,Tools/Demos<27>,Build<42>,Python 3 10 0 alpha 4
@anchor{whatsnew/changelog id383}@anchor{1bc9}
@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<27>,C API<41>,macOS<30>,Python 3 10 0 alpha 4
@anchor{whatsnew/changelog id384}@anchor{1bca}
@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<41>,,Tools/Demos<27>,Python 3 10 0 alpha 4
@anchor{whatsnew/changelog id385}@anchor{1bcb}
@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{c1,,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{1bcc}
@subsection Python 3.10.0 alpha 3


`Release date: 2020-12-07'

@menu
* Security: Security<32>. 
* Core and Builtins: Core and Builtins<44>. 
* Library: Library<45>. 
* Documentation: Documentation<38>. 
* Tests: Tests<40>. 
* Build: Build<43>. 
* Windows: Windows<40>. 
* macOS: macOS<31>. 
* IDLE: IDLE<23>. 
* Tools/Demos: Tools/Demos<28>. 
* C API: C API<42>. 

@end menu

@node Security<32>,Core and Builtins<44>,,Python 3 10 0 alpha 3
@anchor{whatsnew/changelog id386}@anchor{1bcd}
@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<44>,Library<45>,Security<32>,Python 3 10 0 alpha 3
@anchor{whatsnew/changelog id387}@anchor{1bce}
@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{1765,,garbage collector}:


@itemize -

@item 
@ref{7ec,,collections.OrderedDict.items()}

@item 
@ref{9cb,,dict.items()}

@item 
@ref{1675,,enumerate()}

@item 
@ref{21a,,functools.reduce()}

@item 
@ref{1512,,itertools.combinations()}

@item 
@ref{1482,,itertools.combinations_with_replacement()}

@item 
@ref{1bcf,,itertools.permutations()}

@item 
@ref{1513,,itertools.product()}

@item 
@ref{149f,,itertools.zip_longest()}

@item 
@ref{1a0,,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{7f2,,-b} is specified. Speed up comparison of bytarray
objects with non-buffer object.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port the @code{_warnings} extension module to the multi-phase
initialization API (
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}). Patch by Victor Stinner.

@item 
bpo-41686@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41686}: On Windows, the @code{SIGINT} event, @code{_PyOS_SigintEvent()}, is
now created even if Python is configured to not install signal handlers
(if @ref{ab2,,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{9e5,,types.GenericAlias} objects can now be the targets of
weakrefs.

@item 
bpo-42282@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42282}: Optimise constant subexpressions that appear as part of named
expressions (previously the AST optimiser did not descend into named
expressions). Patch by Nick Coghlan.

@item 
bpo-42266@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42266}: Fixed a bug with the LOAD_ATTR opcode cache that was not
respecting monkey-patching a class-level attribute to make it a
descriptor. Patch by Pablo Galindo.

@item 
bpo-40077@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40077}: Convert @ref{bb,,queue} to use heap types.

@item 
bpo-42246@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42246}: Improved accuracy of line tracing events and f_lineno attribute
of Frame objects. See PEP 626 for details.

@item 
bpo-40077@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40077}: Convert @ref{94,,mmap} to use heap types.

@item 
bpo-42233@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42233}: Allow @code{GenericAlias} objects to use @ref{9be,,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<45>,Documentation<38>,Core and Builtins<44>,Python 3 10 0 alpha 3
@anchor{whatsnew/changelog id388}@anchor{1bd0}
@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{2c0,,OSError} instead of
@ref{1729,,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{1759,,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{55d,,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{a20,,platform.freedesktop_os_release()} function to parse
freedesktop.org @code{os-release} files.

@item 
bpo-42299@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42299}: Removed the @code{formatter} module, which was deprecated in
Python 3.4. It is somewhat obsolete, little used, and not tested. It was
originally scheduled to be removed in Python 3.6, but such removals were
delayed until after Python 2.7 EOL. Existing users should copy whatever
classes they use into their code. Patch by Donghee Na and and Terry J.
Reedy.

@item 
bpo-26131@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26131}: Deprecate zipimport.zipimporter.load_module() in favour of
exec_module().

@item 
bpo-41818@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41818}: Updated tests for the pty library. test_basic() has been
changed to test_openpty(); this additionally checks if slave termios and
slave winsize are being set properly by pty.openpty(). In order to add
support for FreeBSD, NetBSD, OpenBSD, and Darwin, this also adds
test_master_read(), which demonstrates that pty.spawn() should not depend
on an OSError to exit from its copy loop.

@item 
bpo-42392@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42392}: Remove loop parameter from @code{__init__} in all
@code{asyncio.locks} and @code{asyncio.Queue} classes. Patch provided by Yurii
Karabas.

@item 
bpo-15450@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15450}: Make @ref{113b,,filecmp.dircmp} respect subclassing. Now the
@ref{1bd1,,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{a2e,,socket.timeout} is now an alias of
@ref{a2f,,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{7b,,importlib} external bootstrap code:
@code{importlib._bootstrap_external} now uses regular imports to import
builtin modules. When it is imported, the builtin @ref{ac8,,__import__()}
function is already fully working and so can be used to import builtin
modules like @ref{df,,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{557,,time.time()}, @ref{c71,,time.perf_counter()} and
@ref{556,,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{1bd2,,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{c71,,time.perf_counter()} on Windows and @ref{556,,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{cd5,,time.perf_counter_ns()} and @ref{cd4,,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{f6,,tkinter} on macOS.

@item 
bpo-42350@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42350}: Fix the @ref{176,,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{a43,,threading.__excepthook__} to allow retrieving the
original value of @ref{a44,,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{169,,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{a3f,,threading.gettrace()} and
@ref{a40,,threading.getprofile()} to retrieve the functions set by
@ref{a41,,threading.settrace()} and @ref{a42,,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{1b48,,os.device_encoding()} function now returns
@code{'UTF-8'} rather than the device encoding if the @ref{85f,,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{a46,,traceback.format_exception()},
@ref{a47,,traceback.format_exception_only()}, and
@ref{a48,,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{d4,,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{1bd3,,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{a13,,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{1bd4,,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{a1a,,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{111,,urllib.request} and @ref{73,,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{a12,,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{b9,,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{a1a,,pathlib.PurePath.parents}.
@end itemize

@node Documentation<38>,Tests<40>,Library<45>,Python 3 10 0 alpha 3
@anchor{whatsnew/changelog id389}@anchor{1bd5}
@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<40>,Build<43>,Documentation<38>,Python 3 10 0 alpha 3
@anchor{whatsnew/changelog id390}@anchor{1bd6}
@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<43>,Windows<40>,Tests<40>,Python 3 10 0 alpha 3
@anchor{whatsnew/changelog id391}@anchor{1bd7}
@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<40>,macOS<31>,Build<43>,Python 3 10 0 alpha 3
@anchor{whatsnew/changelog id392}@anchor{1bd8}
@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<31>,IDLE<23>,Windows<40>,Python 3 10 0 alpha 3
@anchor{whatsnew/changelog id393}@anchor{1bd9}
@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<23>,Tools/Demos<28>,macOS<31>,Python 3 10 0 alpha 3
@anchor{whatsnew/changelog id394}@anchor{1bda}
@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<28>,C API<42>,IDLE<23>,Python 3 10 0 alpha 3
@anchor{whatsnew/changelog id395}@anchor{1bdb}
@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<42>,,Tools/Demos<28>,Python 3 10 0 alpha 3
@anchor{whatsnew/changelog id396}@anchor{1bdc}
@subsubsection C API



@itemize -

@item 
bpo-42423@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42423}: The @ref{797,,PyType_FromSpecWithBases()} and
@ref{76c,,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{c6,,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{64,,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{3c7,,Py_TYPE()} and @ref{97d,,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{de,,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{6a,,grp} and @ref{b7,,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{ab2,,PyConfig.install_signal_handlers}. Patch by Victor Stinner.

@item 
bpo-40170@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40170}: The @code{Py_TRASHCAN_BEGIN} macro no longer accesses PyTypeObject
attributes, but now can get the condition by calling the new private
@code{_PyTrash_cond()} function which hides implementation details.

@item 
bpo-42260@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42260}: @ref{3e1,,Py_GetPath()}, @ref{3e3,,Py_GetPrefix()},
@ref{3e7,,Py_GetExecPrefix()}, @ref{3ea,,Py_GetProgramFullPath()},
@ref{3ed,,Py_GetPythonHome()} and @ref{3ec,,Py_GetProgramName()} functions now
return @code{NULL} if called before @ref{45e,,Py_Initialize()} (before Python is
initialized). Use the new @ref{63e,,Python Initialization Configuration API} to get the @ref{aa1,,Python Path Configuration.}. Patch by Victor Stinner.

@item 
bpo-42260@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42260}: The @ref{98b,,PyConfig_Read()} function now only parses
@ref{3ef,,PyConfig.argv} arguments once: @ref{1bdd,,PyConfig.parse_argv}
is set to @code{2} after arguments are parsed. Since Python arguments are
strippped from @ref{3ef,,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{a91,,Py_NewRef()} and @ref{a92,,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{45e,,Py_Initialize()} is called twice, the second call
now updates more @ref{df,,sys} attributes for the configuration, rather than
only @ref{1465,,sys.argv}. Patch by Victor Stinner.

@item 
bpo-41832@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41832}: The @ref{76c,,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{602,,PyModule_AddObjectRef()} function: similar to
@ref{603,,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{18f5,,METH_FASTCALL} calling convention is added to the
limited API. The functions  @ref{b63,,PyModule_AddType()},
@ref{76c,,PyType_FromModuleAndSpec()}, @ref{b5d,,PyType_GetModule()} and
@ref{b5e,,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{a93,,PyType_GetSlot()} can now accept static types.

@item 
bpo-30459@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30459}: @ref{627,,PyList_SET_ITEM()}, @ref{626,,PyTuple_SET_ITEM()} and
@ref{aa2,,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{1bde}
@subsection Python 3.10.0 alpha 2


`Release date: 2020-11-03'

@menu
* Security: Security<33>. 
* Core and Builtins: Core and Builtins<45>. 
* Library: Library<46>. 
* Documentation: Documentation<39>. 
* Tests: Tests<41>. 
* Build: Build<44>. 
* Windows: Windows<41>. 
* macOS: macOS<32>. 
* IDLE: IDLE<24>. 
* C API: C API<43>. 

@end menu

@node Security<33>,Core and Builtins<45>,,Python 3 10 0 alpha 2
@anchor{whatsnew/changelog id397}@anchor{1bdf}
@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<45>,Library<46>,Security<33>,Python 3 10 0 alpha 2
@anchor{whatsnew/changelog id398}@anchor{1be0}
@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{18e,,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{197,,complex} class.  They
always raised a @ref{198,,TypeError}.

@item 
bpo-41902@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41902}: Micro optimization when compute
@ref{1be1,,sq_item} and
@ref{1be2,,mp_subscript} of @ref{b34,,range}. Patch by
Donghee Na.

@item 
bpo-41894@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41894}: When loading a native module and a load failure occurs, prevent
a possible UnicodeDecodeError when not running in a UTF-8 locale by
decoding the load error message using the current locale's encoding.

@item 
bpo-41902@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41902}: Micro optimization for range.index if step is 1. Patch by
Donghee Na.

@item 
bpo-41435@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41435}: Add @code{sys._current_exceptions()} function to retrieve a
dictionary mapping each thread's identifier to the topmost exception
currently active in that thread at the time the function is called.

@item 
bpo-38605@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38605}: Enable @code{from __future__ import annotations} (
@geindex Python Enhancement Proposals; PEP 563
PEP 563@footnote{https://peps.python.org/pep-0563/}) by
default. The values found in @ref{456,,__annotations__} dicts are now
strings, for example @code{@{"x": "int"@}} instead of @code{@{"x": int@}}.
@end itemize

@node Library<46>,Documentation<39>,Core and Builtins<45>,Python 3 10 0 alpha 2
@anchor{whatsnew/changelog id399}@anchor{1be3}
@subsubsection Library



@itemize -

@item 
bpo-35455@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35455}: On Solaris, @ref{b27,,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{1c1,,repr()} of @ref{10a,,typing} types containing
@ref{8b8,,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{1b55,,logging.FileHandler} class now keeps a reference to
the builtin @ref{315,,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{10b,,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{4b2,,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{1be4,,InvalidFileException} and @ref{f63,,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{1fb,,datetime.time} subclasses.
Patch by Dean Inwood.

@item 
bpo-19270@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19270}: @ref{1be5,,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{16bb,,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{4b2,,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{d4,,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{f40,,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{9c5,,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{9f6,,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{4dc,,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{6d4,,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 @ref{2b,,cProfile} / @ref{b4,,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{c8,,shelve} module now uses
@ref{a28,,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{74,,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<39>,Tests<41>,Library<46>,Python 3 10 0 alpha 2
@anchor{whatsnew/changelog id400}@anchor{1be6}
@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{1be7,,classes} and @ref{1be8,,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{8b8,,generic alias type} and
@ref{9e5,,types.GenericAlias}. Also added an entry in glossary for
@ref{1a1,,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<41>,Build<44>,Documentation<39>,Python 3 10 0 alpha 2
@anchor{whatsnew/changelog id401}@anchor{1be9}
@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<44>,Windows<41>,Tests<41>,Python 3 10 0 alpha 2
@anchor{whatsnew/changelog id402}@anchor{1bea}
@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<41>,macOS<32>,Build<44>,Python 3 10 0 alpha 2
@anchor{whatsnew/changelog id403}@anchor{1beb}
@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<32>,IDLE<24>,Windows<41>,Python 3 10 0 alpha 2
@anchor{whatsnew/changelog id404}@anchor{1bec}
@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<24>,C API<43>,macOS<32>,Python 3 10 0 alpha 2
@anchor{whatsnew/changelog id405}@anchor{1bed}
@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<43>,,IDLE<24>,Python 3 10 0 alpha 2
@anchor{whatsnew/changelog id406}@anchor{1bee}
@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{16cb,,PyMethodDef}'s lifetime is managed through
the @code{self} argument of a @ref{166c,,PyCFunction}.

@item 
bpo-40423@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40423}: The @ref{dc,,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{1bef,,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{1bf0}
@subsection Python 3.10.0 alpha 1


`Release date: 2020-10-05'

@menu
* Security: Security<34>. 
* Core and Builtins: Core and Builtins<46>. 
* Library: Library<47>. 
* Documentation: Documentation<40>. 
* Tests: Tests<42>. 
* Build: Build<45>. 
* Windows: Windows<42>. 
* macOS: macOS<33>. 
* IDLE: IDLE<25>. 
* C API: C API<44>. 

@end menu

@node Security<34>,Core and Builtins<46>,,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id407}@anchor{1bf1}
@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<46>,Library<47>,Security<34>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id408}@anchor{1bf2}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-41909@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41909}: Fixed stack overflow in @ref{9bd,,issubclass()} and
@ref{2ad,,isinstance()} when getting the @code{__bases__} attribute leads to
infinite recursion.

@item 
bpo-41922@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41922}: Speed up calls to @code{reversed()} by using the 
@geindex Python Enhancement Proposals; PEP 590
PEP 590@footnote{https://peps.python.org/pep-0590/}
@code{vectorcall} calling convention. Patch by Donghee Na.

@item 
bpo-41873@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41873}: Calls to @code{float()} are now faster due to the @code{vectorcall}
calling convention. Patch by Dennis Sweeney.

@item 
bpo-41870@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41870}: Speed up calls to @code{bool()} by using the 
@geindex Python Enhancement Proposals; PEP 590
PEP 590@footnote{https://peps.python.org/pep-0590/}
@code{vectorcall} calling convention. Patch by Donghee Na.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port the @code{_bisect} module to the multi-phase
initialization API (
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).

@item 
bpo-39934@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39934}: Correctly count control blocks in 'except' in compiler. Ensures
that a syntax error, rather a fatal error, occurs for deeply nested, named
exception handlers.

@item 
bpo-41780@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41780}: Fix @code{__dir__()} of @ref{9e5,,types.GenericAlias}. Patch by
Batuhan Taskaya.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port the @code{_lsprof} extension module to multi-phase
initialization (
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port the @ref{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{e7,,termios} extension module to multi-phase
initialization (
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Convert the @code{_sha256} extension module types to heap
types.

@item 
bpo-41690@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41690}: Fix a possible stack overflow in the parser when parsing
functions and classes with a huge amount of arguments. Patch by Pablo
Galindo.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port the @code{_overlapped} extension module to multi-phase
initialization (
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port the @code{_curses_panel} extension module to
multi-phase initialization (
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port the @code{_opcode} extension module to multi-phase
initialization (
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).

@item 
bpo-41681@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41681}: Fixes the wrong error description in the error raised by using
2 @code{,} in format string in f-string and @ref{82c,,str.format()}.

@item 
bpo-41675@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41675}: The implementation of @ref{1336,,signal.siginterrupt()} now uses
@code{sigaction()} (if it is available in the system) instead of the
deprecated @code{siginterrupt()}. Patch by Pablo Galindo.

@item 
bpo-41670@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41670}: Prevent line trace being skipped on platforms not compiled with
@code{USE_COMPUTED_GOTOS}. Fixes issue where some lines nested within a
try-except block were not being traced on Windows.

@item 
bpo-41654@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41654}: Fix a crash that occurred when destroying subclasses of
@ref{181e,,MemoryError}. Patch by Pablo Galindo.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port the @ref{139,,zlib} extension module to multi-phase
initialization (
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).

@item 
bpo-41631@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41631}: The @code{_ast} module uses again a global state. Using a module
state per module instance is causing subtle practical problems. For
example, the Mercurial project replaces the @code{__import__()} function to
implement lazy import, whereas Python expected that @code{import _ast} always
return a fully initialized @code{_ast} module.

@item 
bpo-40077@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40077}: Convert @code{_operator} to use @ref{796,,PyType_FromSpec()}.

@item 
bpo-1653741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1653741}: Port @code{_sha3} to multi-phase init.  Convert static types
to heap types.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port the @code{_blake2} extension module to the multi-phase
initialization API (
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).

@item 
bpo-41533@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41533}: Free the stack allocated in @code{va_build_stack} if
@code{do_mkstack} fails and the stack is not a @code{small_stack}.

@item 
bpo-41531@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41531}: Fix a bug that was dropping keys when compiling dict literals
with more than 0xFFFF elements. Patch by Pablo Galindo.

@item 
bpo-41525@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41525}: The output of @code{python --help} contains now only ASCII
characters.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port the @code{_sha1}, @code{_sha512}, and @code{_md5}
extension modules to multi-phase initialization API (
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).

@item 
bpo-41431@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41431}: Optimize @code{dict_merge()} for copying dict (e.g. @code{dict(d)}
and @code{@{@}.update(d)}).

@item 
bpo-41428@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41428}: Implement PEP 604. This supports (int | str) etc. in place of
Union[str, int].

@item 
bpo-41340@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41340}: Removed fallback implementation for @code{strdup}.

@item 
bpo-38156@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38156}: Handle interrupts that come after EOF correctly in
@code{PyOS_StdioReadline}.

@item 
bpo-41342@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41342}: @ref{14db,,round()} with integer argument is now faster (9--60%).

@item 
bpo-41334@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41334}: Constructors @ref{169,,str()}, @ref{192,,bytes()} and @ref{343,,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

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port @code{winapi} to multiphase initialization

@item 
bpo-41215@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41215}: Use non-NULL default values in the PEG parser keyword list to
overcome a bug that was preventing Python from being properly compiled
when using the XLC compiler. Patch by Pablo Galindo.

@item 
bpo-41218@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41218}: Python 3.8.3 had a regression where compiling with
ast.PyCF_ALLOW_TOP_LEVEL_AWAIT would aggressively mark list comprehension
with CO_COROUTINE. Now only list comprehension making use of async/await
will tagged as so.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port @ref{5c,,faulthandler} to multiphase initialization.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port @code{sha256} to multiphase initialization

@item 
bpo-41175@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41175}: Guard against a NULL pointer dereference within bytearrayobject
triggered by the @code{bytearray() + bytearray()} operation.

@item 
bpo-41100@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41100}: add arm64 to the allowable Mac OS arches in mpdecimal.h

@item 
bpo-41094@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41094}: Fix decoding errors with audit when open files with non-ASCII
names on non-UTF-8 locale.

@item 
bpo-39960@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39960}: The "hackcheck" that prevents sneaking around a type's
__setattr__() by calling the superclass method was rewritten to allow C
implemented heap types.

@item 
bpo-41084@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41084}: Prefix the error message with 'f-string: ', when parsing an
f-string expression which throws a @ref{18e,,SyntaxError}.

@item 
bpo-40521@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40521}: Empty frozensets are no longer singletons.

@item 
bpo-41076@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41076}: Pre-feed the parser with the location of the f-string
expression, not the f-string itself, which allows us to skip the shifting
of the AST node locations after the parsing is completed.

@item 
bpo-41056@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41056}: Fixes a reference to deallocated stack space during startup
when constructing sys.path involving a relative symlink when code was
supplied via -c.  (discovered via Coverity)

@item 
bpo-41061@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41061}: Fix incorrect expressions and asserts in hashtable code and
tests.

@item 
bpo-41052@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41052}: Opt out serialization/deserialization for _random.Random

@item 
bpo-40939@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40939}: Rename @code{PyPegen*} functions to @code{PyParser*}, so that we can
remove the old set of @code{PyParser*} functions that were using the old
parser, but keep everything backwards-compatible.

@item 
bpo-35975@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35975}: Stefan Behnel reported that cf_feature_version is used even
when PyCF_ONLY_AST is not set. This is against the intention and against
the documented behavior, so it's been fixed.

@item 
bpo-40939@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40939}: Remove the remaining files from the old parser and the
@code{symbol} module.

@item 
bpo-40077@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40077}: Convert @code{_bz2} to use @ref{796,,PyType_FromSpec()}.

@item 
bpo-41006@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41006}: The @code{encodings.latin_1} module is no longer imported at
startup. Now it is only imported when it is the filesystem encoding or the
stdio encoding.

@item 
bpo-40636@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40636}: @ref{1a0,,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{2eb,,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{18e,,SyntaxError} text to be empty
when a file ends with a line ending in a line continuation character (i.e.
backslash). The error text should contain the text of the last line.

@item 
bpo-40958@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40958}: Fix a possible buffer overflow in the PEG parser when gathering
information for emitting syntax errors. Patch by Pablo Galindo.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port @code{_dbm} to multiphase initialization.

@item 
bpo-40957@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40957}: Fix refleak in _Py_fopen_obj() when PySys_Audit() fails

@item 
bpo-40950@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40950}: Add a state to the @code{nis} module (
@geindex Python Enhancement Proposals; PEP 3121
PEP 3121@footnote{https://peps.python.org/pep-3121/}) and apply
the multiphase initialization. Patch by Donghee Na.

@item 
bpo-40947@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40947}: The Python @ref{aa1,,Path Configuration} now
takes @ref{1bf3,,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{18e,,SyntaxError} for valid
input due to this. For example, an empty line following a line
continuation character was interpreted as a @ref{18e,,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{691,,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{2eb,,ValueError} when validating custom AST's where the
constants @code{True}, @code{False} and @code{None} are used within a
@ref{1bf4,,ast.Name} node.

@item 
bpo-40854@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40854}: Allow overriding @ref{b29,,sys.platlibdir} via a new
@geindex PYTHONPLATLIBDIR
@geindex 環境變數; PYTHONPLATLIBDIR
@ref{1bf5,,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{5d,,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{349,,in} operator and functions
@ref{ace,,contains()}, @ref{acf,,indexOf()} and
@ref{ad0,,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{b34,,range} object now always has exact type @ref{19b,,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{18e,,SyntaxError} in the expression part of an
fstring, the filename attribute of the @ref{18e,,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{797,,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{3c7,,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{715,,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{198,,TypeError} messages about missing or extra
arguments now include the function's @ref{1bf6,,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{715,,generator.throw()} on a generator that has yielded from a @code{yield
from}.

@item 
bpo-4022@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4022}: Improve performance of generators by not raising internal
StopIteration.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port @ref{94,,mmap} to multiphase initialization.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port @code{_lzma} to multiphase initialization.

@item 
bpo-37999@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37999}: Builtin and extension functions that take integer arguments no
longer accept @ref{1fe,,Decimal}s, @ref{213,,Fraction}s and other objects that can be converted to integers only with a loss
(e.g. that have the @ref{19d,,__int__()} method but do not have the
@ref{19e,,__index__()} method).

@item 
bpo-29882@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29882}: Add @ref{9c8,,int.bit_count()}, counting the number of ones in the
binary representation of an integer. Patch by Niklas Fiekas.

@item 
bpo-36982@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36982}: Use ncurses extended color functions when available to support
terminals with 256 colors, and add the new function
@ref{9ef,,curses.has_extended_color_support()} to indicate whether extended
color support is provided by the underlying ncurses library.

@item 
bpo-19569@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19569}: Add the private macros @code{_Py_COMP_DIAG_PUSH},
@code{_Py_COMP_DIAG_IGNORE_DEPR_DECLS}, and @code{_Py_COMP_DIAG_POP}.

@item 
bpo-26680@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26680}: The int type now supports the x.is_integer() method for
compatibility with float.
@end itemize

@node Library<47>,Documentation<40>,Core and Builtins<46>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id409}@anchor{1bf7}
@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{e0d,,ast.literal_eval()}. Also
document stripping of spaces and tabs for @ref{49e,,eval()}.

@item 
bpo-41773@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41773}: Note in documentation that @ref{ebc,,random.choices()} doesn't
support non-finite weights, raise @ref{2eb,,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{de,,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{9e2,,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{16bc,,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{176,,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{a4a,,types.EllipsisType}, @ref{a4c,,types.NotImplementedType}
and @ref{a4b,,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{4c3,,iterator} to @ref{165,,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{2f2,,asyncio.run()}. This allows
setting @code{PYTHONASYNCIODEBUG} or @code{-X dev} to enable asyncio debug mode
when using @ref{2f2,,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{d4,,sqlite3} with
@ref{304,,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{304,,ProgrammingError} message for absent parameter
in @ref{d4,,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{d4,,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{80e,,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{80e,,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{1257,,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{4d6,,os.cpu_count()} support for VxWorks RTOS.

@item 
bpo-41316@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41316}: Fix the @ref{e4,,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{116,,uuid}.

@item 
bpo-35328@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35328}: Set the environment variable @code{VIRTUAL_ENV_PROMPT} at
@ref{117,,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{1343,,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{4b9,,array.array} as a
@ref{4ba,,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{174e,,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{2c0,,OSError} to ignore error if the filesystem
is read-only, instead of only ignoring @ref{264,,FileNotFoundError} and
@ref{f39,,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{103,,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{21a,,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{c6,,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{1bf8,,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{59a,,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{ad3,,zoneinfo.ZoneInfo} from being subclassed.

@item 
bpo-35018@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35018}: Add the @ref{a55,,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{59,,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{dc,,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{88,,keyword} module.

@item 
bpo-23427@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23427}: Add @ref{a3a,,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{168b,,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{2d,,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{c6,,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{1bf9,,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{63,,functools} module has been moved to a new
@ref{69,,graphlib} module to better accommodate the new tools and keep the
original scope of the @ref{63,,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{6a7,,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{d4,,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{1bc4,,operator.index()} now always has exact type
@ref{19b,,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{11b,,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{2e,,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{1bfa,,PyErr_Print()}.

@item 
bpo-16995@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16995}: Add @ref{9dd,,base64.b32hexencode()} and @ref{9de,,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{d5,,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{1bfb,,os.RWF_APPEND} flag for @ref{d4f,,os.pwritev()}.

@item 
bpo-40737@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40737}: Fix possible reference leak for @ref{d4,,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{1a51,,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{6c,,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{1bfc,,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{1c2,,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{1a0e,,socket.getaddrinfo()}
no longer uses an internal lock to prevent race conditions when calling
@code{getaddrinfo()} which is thread-safe since macOS 10.5. Python 3.9
requires macOS 10.6 or newer. The internal lock caused random hang on fork
when another thread was calling @ref{1a0e,,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{b63,,PyModule_AddType()}.

@item 
bpo-32309@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32309}: Added a new @ref{6b2,,coroutine} @ref{adc,,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{add,,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{1bfd,,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{b8,,py_compile}. Patch by Gregory Schevchenko.

@item 
bpo-35714@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35714}: @ref{1524,,struct.error} is now raised if there is a null character
in a @ref{db,,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{59a,,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{6a8,,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{198,,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{1365,,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{a6e,,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<40>,Tests<42>,Library<47>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id410}@anchor{1bfe}
@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{1bff,,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<42>,Build<45>,Documentation<40>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id411}@anchor{1c00}
@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{ea,,test.support}: Rename @code{blacklist} parameter of
@ref{1c01,,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{9da,,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{1c02,,skip_if_broken_multiprocessing_synchronize()} function
to the @ref{ea,,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{78,,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<45>,Windows<42>,Tests<42>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id412}@anchor{1c03}
@subsubsection Build



@itemize -

@item 
bpo-38249@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38249}: Update @ref{da9,,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{13a,,zoneinfo} module and its tests
were not included when Python is installed with @code{make}.
@end itemize

@node Windows<42>,macOS<33>,Build<45>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id413}@anchor{1c04}
@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<33>,IDLE<25>,Windows<42>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id414}@anchor{1c05}
@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<25>,C API<44>,macOS<33>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id415}@anchor{1c06}
@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<44>,,IDLE<25>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id416}@anchor{1c07}
@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{ab1,,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{aa5,,PyUnicode_InternInPlace()}
instead. Patch by Victor Stinner.

@item 
bpo-41842@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41842}: Add @ref{a8e,,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{ab1,,PyInterpreterState}
structure. Patch by Victor Stinner.

@item 
bpo-41689@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41689}: Types created with @ref{796,,PyType_FromSpec()} now make any
signature in their @code{tp_doc} slot accessible from @code{__text_signature__}.

@item 
bpo-41524@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41524}: Fix bug in PyOS_mystrnicmp and PyOS_mystricmp that incremented
pointers beyond the end of a string.

@item 
bpo-41324@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41324}: Add a minimal decimal capsule API.  The API supports fast
conversions between Decimals up to 38 digits and their triple
representation as a C struct.

@item 
bpo-30155@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30155}: Add @ref{a8c,,PyDateTime_DATE_GET_TZINFO()} and
@ref{a8d,,PyDateTime_TIME_GET_TZINFO()} macros for accessing the @code{tzinfo}
attributes of @ref{4dd,,datetime.datetime} and @ref{1fb,,datetime.time}
objects.

@item 
bpo-40170@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40170}: Revert @ref{1c08,,PyType_HasFeature()} change: it reads again
directly the @ref{1b73,,PyTypeObject.tp_flags} member when the limited C
API is not used, rather than always calling @ref{1c09,,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{632,,PyObject_GetBuffer()} and @ref{633,,PyBuffer_Release()}.

@item 
bpo-36346@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36346}: Raises DeprecationWarning for @code{PyUnicode_FromUnicode(NULL,
size)} and @code{PyUnicode_FromStringAndSize(NULL, size)} with @code{size > 0}.

@item 
bpo-36346@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36346}: Mark @code{Py_UNICODE_COPY}, @code{Py_UNICODE_FILL},
@code{PyUnicode_WSTR_LENGTH}, @code{PyUnicode_FromUnicode},
@code{PyUnicode_AsUnicode}, and @code{PyUnicode_AsUnicodeAndSize} as deprecated
in C. Remove @code{Py_UNICODE_MATCH} which was deprecated and broken since
Python 3.3.

@item 
bpo-40989@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40989}: The @code{PyObject_INIT()} and @code{PyObject_INIT_VAR()}
macros become aliases to, respectively, @ref{c57,,PyObject_Init()} and
@ref{1c0a,,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{3bf,,PyArg_ParseTuple()} and @ref{3c0,,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{3d3,,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{1c0b,,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{620,,PyDict_GetItem()} without @ref{164,,GIL} held had
been allowed for historical reason. It is no longer allowed.

@item 
bpo-40826@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40826}: @code{PyOS_InterruptOccurred()} now fails with a fatal error
if it is called with the GIL released.

@item 
bpo-40792@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40792}: The result of @ref{a8a,,PyNumber_Index()} now always has exact
type @ref{19b,,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{2cf,,Py_REFCNT()} and @ref{97d,,Py_SIZE()} macros to
static inline functions. They cannot be used as l-value anymore: use
@ref{a9f,,Py_SET_REFCNT()} and @ref{97e,,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{5d7,,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{1c0c}
@subsection Python 3.9.0 beta 1


`Release date: 2020-05-19'

@menu
* Security: Security<35>. 
* Core and Builtins: Core and Builtins<47>. 
* Library: Library<48>. 
* Documentation: Documentation<41>. 
* Tests: Tests<43>. 
* Build: Build<46>. 
* Windows: Windows<43>. 
* macOS: macOS<34>. 
* Tools/Demos: Tools/Demos<29>. 
* C API: C API<45>. 

@end menu

@node Security<35>,Core and Builtins<47>,,Python 3 9 0 beta 1
@anchor{whatsnew/changelog id417}@anchor{1c0d}
@subsubsection Security



@itemize -

@item 
bpo-40501@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40501}: @ref{116,,uuid} no longer uses @ref{2e,,ctypes} to load
@code{libuuid} or @code{rpcrt4.dll} at runtime.
@end itemize

@node Core and Builtins<47>,Library<48>,Security<35>,Python 3 9 0 beta 1
@anchor{whatsnew/changelog id418}@anchor{1c0e}
@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{1c0f,,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{1a82,,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{5b,,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{7fa,,hash()} and @ref{a5e,,reversed()} to
@ref{c3d,,weakref.proxy} objects. Patch by Pablo Galindo.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port @ref{e2,,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{715,,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{b33,,PyLong_FromDouble()} for values
that fit into long.
@end itemize

@node Library<48>,Documentation<41>,Core and Builtins<47>,Python 3 9 0 beta 1
@anchor{whatsnew/changelog id419}@anchor{1c10}
@subsubsection Library



@itemize -

@item 
bpo-40662@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40662}: Fixed @ref{bc2,,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{1c11,,available_timezones()} function to the
@ref{13a,,zoneinfo} module. Patch by Paul Ganssle.

@item 
bpo-40645@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40645}: The @ref{d2b,,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{6c,,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{6c,,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{be4,,inspect.getdoc()}.

@item 
bpo-40607@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40607}: When cancelling a task due to timeout, @ref{80e,,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{13a,,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{d5,,ssl} and @ref{6c,,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{1c7,,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{bd9,,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{1c7,,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{e0d,,ast.literal_eval()} in the
presence of malformed @ref{1c12,,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{1c13,,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{f08,,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{37,,dbm.gnu} to use gdbm_count if possible when
calling @ref{839,,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{1c14,,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{b08,,close()} method to
the @ref{b07,,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{108a,,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{afa,,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{691,,types.MappingProxyType} is now reversible.

@item 
bpo-39075@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39075}: The repr for @ref{4e0,,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{b27,,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{1fa,,datetime.date} and
@ref{4dd,,datetime.datetime} now return a @ref{857,,named tuple} instead of a
@ref{60c,,tuple}.
@end itemize

@node Documentation<41>,Tests<43>,Library<48>,Python 3 9 0 beta 1
@anchor{whatsnew/changelog id420}@anchor{1c15}
@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{6a0,,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{f08,,pickle.loads()} in the docs
@end itemize

@node Tests<43>,Build<46>,Documentation<41>,Python 3 9 0 beta 1
@anchor{whatsnew/changelog id421}@anchor{1c16}
@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<46>,Windows<43>,Tests<43>,Python 3 9 0 beta 1
@anchor{whatsnew/changelog id422}@anchor{1c17}
@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<43>,macOS<34>,Build<46>,Python 3 9 0 beta 1
@anchor{whatsnew/changelog id423}@anchor{1c18}
@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<34>,Tools/Demos<29>,Windows<43>,Python 3 9 0 beta 1
@anchor{whatsnew/changelog id424}@anchor{1c19}
@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<29>,C API<45>,macOS<34>,Python 3 9 0 beta 1
@anchor{whatsnew/changelog id425}@anchor{1c1a}
@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<45>,,Tools/Demos<29>,Python 3 9 0 beta 1
@anchor{whatsnew/changelog id426}@anchor{1c1b}
@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{989,,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{b7c,,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{981,,PyFrame_GetBack()} function: get the frame next
outer frame.

@item 
bpo-40421@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40421}: New @ref{985,,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{797,,PyType_FromSpecWithBases()} will visit its class object when
traversing references in the garbage collector (implemented as an
extension of the provided @ref{979,,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{1c1c}
@subsection Python 3.9.0 alpha 6


`Release date: 2020-04-27'

@menu
* Security: Security<36>. 
* Core and Builtins: Core and Builtins<48>. 
* Library: Library<49>. 
* Documentation: Documentation<42>. 
* Tests: Tests<44>. 
* Build: Build<47>. 
* Windows: Windows<44>. 
* macOS: macOS<35>. 
* IDLE: IDLE<26>. 
* Tools/Demos: Tools/Demos<30>. 
* C API: C API<46>. 

@end menu

@node Security<36>,Core and Builtins<48>,,Python 3 9 0 alpha 6
@anchor{whatsnew/changelog id427}@anchor{1c1d}
@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{1b71,,AbstractBasicAuthHandler} class of the
@ref{111,,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<48>,Library<49>,Security<36>,Python 3 9 0 alpha 6
@anchor{whatsnew/changelog id428}@anchor{1c1e}
@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{c1,,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{92,,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{796,,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{18ea,,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<49>,Documentation<42>,Core and Builtins<48>,Python 3 9 0 alpha 6
@anchor{whatsnew/changelog id429}@anchor{1c1f}
@subsubsection Library



@itemize -

@item 
bpo-40398@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40398}: @ref{2ac,,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{2ab,,typing.get_origin()}, @ref{2ac,,typing.get_args()}
and @ref{8b9,,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{dc,,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{f95,,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{481,,typing.TypeVar}. Patch by Weipeng Hong.

@item 
bpo-40275@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40275}: The @ref{8b,,logging} package is now imported lazily in
@ref{10c,,unittest} only when the @ref{a52,,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{10c,,unittest} only when the @ref{35f,,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{10a,,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{be4,,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{ba,,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{17a9,,random.randbytes()} function and
@ref{b1a,,random.Random.randbytes()} method to generate random bytes.

@item 
bpo-40277@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40277}: @ref{4db,,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{19e7,,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{1d6,,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{de,,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{330,,typing.NamedTuple} class.

@item 
bpo-36517@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36517}: Multiple inheritance with @ref{330,,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{c3,,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{b0e,,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{32d,,threading.RLock}
and @ref{1356,,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{1359,,threading.Event} to
@code{_at_fork_reinit()}.

@item 
bpo-25780@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25780}: Expose @ref{b22,,CAN_RAW_JOIN_FILTERS} in the
@ref{d1,,socket} module.

@item 
bpo-39503@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39503}: @ref{1b71,,AbstractBasicAuthHandler} of
@ref{111,,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{17c0,,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{1c20,,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{1890,,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{188f,,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{1c21,,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{e11,,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{1882,,sys.audit()} failures in
@ref{18f4,,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{1759,,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{757,,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<42>,Tests<44>,Library<49>,Python 3 9 0 alpha 6
@anchor{whatsnew/changelog id430}@anchor{1c22}
@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{1c23,,資料模型} docs to include @ref{183,,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{1c24,,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<44>,Build<47>,Documentation<42>,Python 3 9 0 alpha 6
@anchor{whatsnew/changelog id431}@anchor{1c25}
@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{1c26,,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{aed,,ftplib.FTP} and
@ref{aee,,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<47>,Windows<44>,Tests<44>,Python 3 9 0 alpha 6
@anchor{whatsnew/changelog id432}@anchor{1c27}
@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<44>,macOS<35>,Build<47>,Python 3 9 0 alpha 6
@anchor{whatsnew/changelog id433}@anchor{1c28}
@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<35>,IDLE<26>,Windows<44>,Python 3 9 0 alpha 6
@anchor{whatsnew/changelog id434}@anchor{1c29}
@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<26>,Tools/Demos<30>,macOS<35>,Python 3 9 0 alpha 6
@anchor{whatsnew/changelog id435}@anchor{1c2a}
@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<30>,C API<46>,IDLE<26>,Python 3 9 0 alpha 6
@anchor{whatsnew/changelog id436}@anchor{1c2b}
@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{b0e,,os.waitstatus_to_exitcode()} to convert @ref{1652,,os.system()} exit status
into an exit code.
@end itemize

@node C API<46>,,Tools/Demos<30>,Python 3 9 0 alpha 6
@anchor{whatsnew/changelog id437}@anchor{1c2c}
@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{b72,,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{b64,,PyObject_GC_IsTracked()} and
@ref{b65,,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{b73,,PyObject_New()} macro, and the @code{PyObject_NEW_VAR()} macro
becomes an alias to the @ref{b74,,PyObject_NewVar()} macro, to hide
implementation details. They no longer access directly the
@ref{b75,,PyTypeObject.tp_basicsize} member.

@item 
bpo-40170@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40170}: @ref{1c08,,PyType_HasFeature()} now always calls
@ref{1c09,,PyType_GetFlags()} to hide implementation details. Previously, it
accessed directly the @ref{1b73,,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{b76,,PyTypeObject.tp_weaklistoffset} member.

@item 
bpo-40170@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40170}: Convert @ref{631,,PyObject_CheckBuffer()} macro to a function to
hide implementation details: the macro accessed directly the
@ref{b77,,PyTypeObject.tp_as_buffer} member.

@item 
bpo-40170@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40170}: Always declare @ref{b78,,PyIndex_Check()} as an opaque function to
hide implementation details: remove @code{PyIndex_Check()} macro. The macro
accessed directly the @ref{b79,,PyTypeObject.tp_as_number} member.

@item 
bpo-39947@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39947}: Add @ref{b61,,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{1c2d}
@subsection Python 3.9.0 alpha 5


`Release date: 2020-03-23'

@menu
* Security: Security<37>. 
* Core and Builtins: Core and Builtins<49>. 
* Library: Library<50>. 
* Documentation: Documentation<43>. 
* Tests: Tests<45>. 
* Build: Build<48>. 
* Windows: Windows<45>. 
* macOS: macOS<36>. 
* IDLE: IDLE<27>. 
* Tools/Demos: Tools/Demos<31>. 
* C API: C API<47>. 

@end menu

@node Security<37>,Core and Builtins<49>,,Python 3 9 0 alpha 5
@anchor{whatsnew/changelog id438}@anchor{1c2e}
@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<49>,Library<50>,Security<37>,Python 3 9 0 alpha 5
@anchor{whatsnew/changelog id439}@anchor{1c2f}
@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{b6f,,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{b6f,,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{640,,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{45d,,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{78e,,SystemError} in
@code{math.@{atan2,copysign,remainder@}()} when the first argument cannot be
converted to a @ref{196,,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{932,,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{422,,PyUnicode_AsUTF8()} and
@ref{a90,,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{1a2,,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<50>,Documentation<43>,Core and Builtins<49>,Python 3 9 0 alpha 5
@anchor{whatsnew/changelog id440}@anchor{1c30}
@subsubsection Library



@itemize -

@item 
bpo-39830@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39830}: Add @ref{8cd,,zipfile.Path} to @code{__all__} in the @ref{137,,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{d9b,,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{60b,,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{7ec,,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{1c31,,unittest.mock.AsyncMock.await_args_list} has call
objects in the order of awaited arguments instead of using
@ref{1c32,,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{259,,os.environ} and @ref{25a,,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{1c33,,random.Random.seed()} method when a @ref{3c1,,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{1973,,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{ad8,,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{ad9,,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{87,,json.tool} to catch @ref{1257,,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{1a9c,,inspect.getmodule()} when it tried to loop through
@ref{17c0,,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{dc,,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{13bd,,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{1d6,,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{d13,,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{691,,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{7b,,importlib} module now ignores the
@geindex PYTHONCASEOK
@geindex 環境變數; PYTHONCASEOK
@ref{b4c,,PYTHONCASEOK} environment variable when the @ref{b4d,,-E} or
@ref{b4e,,-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{1c34,,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{af3,,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{1c35,,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{84,,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<43>,Tests<45>,Library<50>,Python 3 9 0 alpha 5
@anchor{whatsnew/changelog id441}@anchor{1c36}
@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{100,,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{3c,,dis}
@end itemize

@node Tests<45>,Build<48>,Documentation<43>,Python 3 9 0 alpha 5
@anchor{whatsnew/changelog id442}@anchor{1c37}
@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{3e2,,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<48>,Windows<45>,Tests<45>,Python 3 9 0 alpha 5
@anchor{whatsnew/changelog id443}@anchor{1c38}
@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{dc,,subprocess} module if the @ref{dc,,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{b29,,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<45>,macOS<36>,Build<48>,Python 3 9 0 alpha 5
@anchor{whatsnew/changelog id444}@anchor{1c39}
@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{f3,,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<36>,IDLE<27>,Windows<45>,Python 3 9 0 alpha 5
@anchor{whatsnew/changelog id445}@anchor{1c3a}
@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<27>,Tools/Demos<31>,macOS<36>,Python 3 9 0 alpha 5
@anchor{whatsnew/changelog id446}@anchor{1c3b}
@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<31>,C API<47>,IDLE<27>,Python 3 9 0 alpha 5
@anchor{whatsnew/changelog id447}@anchor{1c3c}
@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<47>,,Tools/Demos<31>,Python 3 9 0 alpha 5
@anchor{whatsnew/changelog id448}@anchor{1c3d}
@subsubsection C API



@itemize -

@item 
bpo-40024@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40024}: Add @ref{b63,,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{989,,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{b60,,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{644,,PyInterpreterState_Get()} function to the limited C
API.

@item 
bpo-35370@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35370}: If @ref{60b,,PySys_Audit()} fails in @ref{16f1,,PyEval_SetProfile()}
or @ref{65b,,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{1c3e,,PyDescr_NewMethod()} and @ref{1c3f,,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{da9,,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{1aa2,,PyNumber_ToBase()} now raises a @ref{78e,,SystemError}
instead of crashing when called with invalid base.

@item 
bpo-39882@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39882}: The @ref{b71,,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{b68,,m_traverse},
@ref{b69,,m_clear} and @ref{b6a,,m_free}
functions of @ref{b6b,,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{b6c,,Py_mod_exec} function). More precisely, these functions are not
called if @ref{b6d,,m_size} is greater than 0 and the module
state (as returned by @ref{b6e,,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{1c40,,_PyInterpreterState_GetEvalFrameFunc()} and
@ref{1c41,,_PyInterpreterState_SetEvalFrameFunc()} C functions. The
@ref{972,,_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{1c42}
@subsection Python 3.9.0 alpha 4


`Release date: 2020-02-25'

@menu
* Security: Security<38>. 
* Core and Builtins: Core and Builtins<50>. 
* Library: Library<51>. 
* Documentation: Documentation<44>. 
* Tests: Tests<46>. 
* Build: Build<49>. 
* Windows: Windows<46>. 
* IDLE: IDLE<28>. 
* C API: C API<48>. 

@end menu

@node Security<38>,Core and Builtins<50>,,Python 3 9 0 alpha 4
@anchor{whatsnew/changelog id449}@anchor{1c43}
@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<50>,Library<51>,Security<38>,Python 3 9 0 alpha 4
@anchor{whatsnew/changelog id450}@anchor{1c44}
@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{1aca,,Py_IS_TYPE()}. Patch by
Donghee Na.

@item 
bpo-39619@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39619}: Enable use of @ref{1c45,,os.chroot()} on HP-UX systems.

@item 
bpo-39573@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39573}: Add @ref{1aca,,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{16ed,,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{b35,,floor division} of float operation now has a better
performance. Also the message of @ref{b36,,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{183,,dict} (and @ref{1c46,,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<51>,Documentation<44>,Core and Builtins<50>,Python 3 9 0 alpha 4
@anchor{whatsnew/changelog id451}@anchor{1c47}
@subsubsection Library



@itemize -

@item 
bpo-30566@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30566}: Fix @ref{1729,,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{b03,,math.gcd()} and @ref{b04,,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{1c48,,io.UnsupportedOperation} in
@code{io.BufferedReader.truncate()} when it is called on a read-only
@ref{140f,,io.BufferedReader} instance.

@item 
bpo-39479@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39479}: Add @ref{b04,,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{ba,,pydoc} and @ref{103,,trace} modules now use the
@ref{e1,,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{213,,fractions.Fraction} if the numerator
and/or the denominator is an @ref{19b,,int} subclass. The @ref{b03,,math.gcd()}
function is now used to normalize the `numerator' and `denominator'.
@ref{b03,,math.gcd()} always return a @ref{19b,,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{6c9,,os.walk()}, @ref{d4a,,os.fwalk()},
@ref{532,,pathlib.Path.glob()} and @ref{533,,pathlib.Path.rglob()}.

@item 
bpo-39559@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39559}: Remove unused, undocumented argument @code{getters} from
@ref{d9b,,uuid.getnode()}

@item 
bpo-38149@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38149}: @ref{1882,,sys.audit()} is now called only once per call of
@ref{59a,,glob.glob()} and @ref{a01,,glob.iglob()}.

@item 
bpo-39546@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39546}: Fix a regression in @ref{1bd,,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{935,,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{b2e,,typing.Annotated} and @code{include_extras} parameter
to @ref{8b9,,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{189a,,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{e4,,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{ae1,,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{108a,,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<44>,Tests<46>,Library<51>,Python 3 9 0 alpha 4
@anchor{whatsnew/changelog id452}@anchor{1c49}
@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<46>,Build<49>,Documentation<44>,Python 3 9 0 alpha 4
@anchor{whatsnew/changelog id453}@anchor{1c4a}
@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{16ed,,time.localtime()} fails with @ref{a78,,OverflowError}. It is the case on
AIX 6.1 for example.
@end itemize

@node Build<49>,Windows<46>,Tests<46>,Python 3 9 0 alpha 4
@anchor{whatsnew/changelog id454}@anchor{1c4b}
@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<46>,IDLE<28>,Build<49>,Python 3 9 0 alpha 4
@anchor{whatsnew/changelog id455}@anchor{1c4c}
@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{103e,,home()} and @ref{103d,,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{c00,,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<28>,C API<48>,Windows<46>,Python 3 9 0 alpha 4
@anchor{whatsnew/changelog id456}@anchor{1c4d}
@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{bbc,,KeyboardInterrupt} or
shell restart occurs.  Patch by Zackery Spytz.
@end itemize

@node C API<48>,,IDLE<28>,Python 3 9 0 alpha 4
@anchor{whatsnew/changelog id457}@anchor{1c4e}
@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{92,,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{97e,,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{1c4f,,PyUnicode_IsIdentifier()} does not call
@ref{b71,,Py_FatalError()} anymore if the string is not ready.

@item 
bpo-39573@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39573}: Add @ref{97c,,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{a9f,,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{1c08,,PyType_HasFeature()}, @ref{1c50,,PyType_Check()} and
@ref{1c51,,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{c57,,PyObject_Init()} and @ref{1c0a,,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{18ea,,PyThreadState_Clear()} function now calls the
@code{PyThreadState.on_delete} callback. Previously, that happened in
@ref{1c52,,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{1c53}
@subsection Python 3.9.0 alpha 3


`Release date: 2020-01-24'

@menu
* Core and Builtins: Core and Builtins<51>. 
* Library: Library<52>. 
* Documentation: Documentation<45>. 
* Build: Build<50>. 
* IDLE: IDLE<29>. 
* C API: C API<49>. 

@end menu

@node Core and Builtins<51>,Library<52>,,Python 3 9 0 alpha 3
@anchor{whatsnew/changelog id458}@anchor{1c54}
@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{6d,,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{63,,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{af0,,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{1106,,min()} or
@ref{1107,,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{b34,,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{1c55,,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{1c56,,-u} command-line option or setting the
@geindex PYTHONUNBUFFERED
@geindex 環境變數; PYTHONUNBUFFERED
@ref{1c57,,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{1c55,,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<52>,Documentation<45>,Core and Builtins<51>,Python 3 9 0 alpha 3
@anchor{whatsnew/changelog id459}@anchor{1c58}
@subsubsection Library



@itemize -

@item 
bpo-39430@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39430}: Fixed race condition in lazy imports in @ref{e4,,tarfile}.

@item 
bpo-39413@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39413}: The @ref{25c,,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{c15,,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{25b,,os.putenv()} and @ref{25c,,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{25b,,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{1afb,,tarfile.is_tarfile()} to be used with file and
file-like objects, like @ref{152b,,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{b45,,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{6b,,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{a5f,,bz2.BZ2File}. Since
Python 3.0, it was ignored and using it was emitting
@ref{1a3,,DeprecationWarning}. Pass an open file object, to control how the
file is opened. The `compresslevel' parameter becomes keyword-only.

@item 
bpo-39353@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39353}: Deprecate binhex4 and hexbin4 standards. Deprecate the
@code{binhex} module and the following @ref{11,,binascii} functions:
@code{b2a_hqx()}, @code{a2b_hqx()},
@code{rlecode_hqx()}, @code{rledecode_hqx()},
@ref{935,,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{b43,,base64.encodebytes()} and
@ref{b44,,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{b03,,math.gcd()} instead.

@item 
bpo-39329@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39329}: @ref{b20,,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{aee,,FTP_TLS} and @ref{aee,,FTP_TLS} now raise
a @ref{2eb,,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{b1e,,SMTP} and @ref{b1f,,SMTP_SSL} now raise
a @ref{2eb,,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{b05,,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{2eb,,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{6b9,,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{b14,,POP3} and @ref{b15,,POP3_SSL} now raise a
@ref{2eb,,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{76,,http.server} module is imported.

@item 
bpo-39239@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39239}: The @ref{b4a,,select.epoll.unregister()} method no longer ignores
the @ref{b4b,,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{1c59,,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{89b,,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{e46,,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{af6,,IMAP4} and @ref{af7,,IMAP4_SSL} now
have an optional `timeout' parameter for their constructors. Also, the
@ref{af8,,open()} method now has an optional `timeout' parameter
with this change. The overridden methods of @ref{af7,,IMAP4_SSL}
and @ref{af9,,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{15d5,,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{c7a,,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{759,,syslog.openlog()} was called without arguments.

@item 
bpo-38293@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38293}: Add @ref{750,,copy.copy()} and @ref{d5d,,copy.deepcopy()} support to
@ref{4ae,,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<45>,Build<50>,Library<52>,Python 3 9 0 alpha 3
@anchor{whatsnew/changelog id460}@anchor{1c5a}
@subsubsection Documentation



@itemize -

@item 
bpo-39381@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39381}: Mention in docs that @ref{2f1,,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{82,,inspect} docs' @ref{1c5b,,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<50>,IDLE<29>,Documentation<45>,Python 3 9 0 alpha 3
@anchor{whatsnew/changelog id461}@anchor{1c5c}
@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<29>,C API<49>,Build<50>,Python 3 9 0 alpha 3
@anchor{whatsnew/changelog id462}@anchor{1c5d}
@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<49>,,IDLE<29>,Python 3 9 0 alpha 3
@anchor{whatsnew/changelog id463}@anchor{1c5e}
@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{1c5f}
@subsection Python 3.9.0 alpha 2


`Release date: 2019-12-18'

@menu
* Security: Security<39>. 
* Core and Builtins: Core and Builtins<52>. 
* Library: Library<53>. 
* Documentation: Documentation<46>. 
* Tests: Tests<47>. 
* Build: Build<51>. 
* Windows: Windows<47>. 
* macOS: macOS<37>. 
* IDLE: IDLE<30>. 
* C API: C API<50>. 

@end menu

@node Security<39>,Core and Builtins<52>,,Python 3 9 0 alpha 2
@anchor{whatsnew/changelog id464}@anchor{1c60}
@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{934,,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{74,,http.cookiejar}. Patch by
Ben Caller.
@end itemize

@node Core and Builtins<52>,Library<53>,Security<39>,Python 3 9 0 alpha 2
@anchor{whatsnew/changelog id465}@anchor{1c61}
@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{60b,,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{a05,,sys.excepthook()} and
@ref{502,,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{24d,,list} and
@ref{184,,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{252,,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<53>,Documentation<46>,Core and Builtins<52>,Python 3 9 0 alpha 2
@anchor{whatsnew/changelog id466}@anchor{1c62}
@subsubsection Library



@itemize -

@item 
bpo-39033@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39033}: Fix @ref{450,,NameError} in @ref{138,,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{4b9,,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{1253,,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{bf,,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{76,,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{8b9,,typing.get_type_hints()} properly handles functions
decorated with @ref{1158,,functools.wraps()}.

@item 
bpo-38870@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38870}: Expose @ref{ad9,,ast.unparse()} as a function of the @ref{9,,ast}
module that can be used to unparse an @ref{4be,,ast.AST} object and produce
a string with code that would produce an equivalent @ref{4be,,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{331,,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{11b3,,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{12f0,,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{1c34,,urllib.request.AbstractDigestAuthHandler}.

@item 
bpo-38712@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38712}: Add the Linux-specific @ref{b1c,,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{5a,,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{3e,,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<46>,Tests<47>,Library<53>,Python 3 9 0 alpha 2
@anchor{whatsnew/changelog id467}@anchor{1c63}
@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{18b7,,datetime.datetime.strptime()} accepts for @code{%Z}. Patch by Karl
Dubost.
@end itemize

@node Tests<47>,Build<51>,Documentation<46>,Python 3 9 0 alpha 2
@anchor{whatsnew/changelog id468}@anchor{1c64}
@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{ea,,test.support} constants: @ref{1c65,,LOOPBACK_TIMEOUT},
@ref{1c66,,INTERNET_TIMEOUT},
@ref{1b65,,SHORT_TIMEOUT} and
@ref{1c67,,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{15cb,,math.fsum()} that was failing due to
constant folding.

@item 
bpo-38991@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38991}: @ref{ea,,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{f39,,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{198,,TypeError} when passing target as a string with
@ref{1871,,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<51>,Windows<47>,Tests<47>,Python 3 9 0 alpha 2
@anchor{whatsnew/changelog id469}@anchor{1c68}
@subsubsection Build



@itemize -

@item 
bpo-37404@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37404}: @ref{b,,asyncio} now raises @ref{198,,TypeError} when calling
incompatible methods with an @ref{ade,,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<47>,macOS<37>,Build<51>,Python 3 9 0 alpha 2
@anchor{whatsnew/changelog id470}@anchor{1c69}
@subsubsection Windows



@itemize -

@item 
bpo-39007@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39007}: Add auditing events to functions in @ref{11c,,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<37>,IDLE<30>,Windows<47>,Python 3 9 0 alpha 2
@anchor{whatsnew/changelog id471}@anchor{1c6a}
@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<30>,C API<50>,macOS<37>,Python 3 9 0 alpha 2
@anchor{whatsnew/changelog id472}@anchor{1c6b}
@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<50>,,IDLE<30>,Python 3 9 0 alpha 2
@anchor{whatsnew/changelog id473}@anchor{1c6c}
@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{1c6d}
@subsection Python 3.9.0 alpha 1


`Release date: 2019-11-19'

@menu
* Security: Security<40>. 
* Core and Builtins: Core and Builtins<53>. 
* Library: Library<54>. 
* Documentation: Documentation<47>. 
* Tests: Tests<48>. 
* Build: Build<52>. 
* Windows: Windows<48>. 
* macOS: macOS<38>. 
* IDLE: IDLE<31>. 
* Tools/Demos: Tools/Demos<32>. 
* C API: C API<51>. 

@end menu

@node Security<40>,Core and Builtins<53>,,Python 3 9 0 alpha 1
@anchor{whatsnew/changelog id474}@anchor{1c6e}
@subsubsection Security



@itemize -

@item 
bpo-38722@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38722}: @ref{c3,,runpy} now uses @ref{19e7,,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{2e,,ctypes} module.

@item 
bpo-38418@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38418}: Fixes audit event for @ref{1652,,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{1c6f,,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{1c70,,命令列與環境}).

@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{59,,ensurepip}, @ref{62,,ftplib},
@ref{68,,glob}, @ref{78,,imaplib}, @code{nntplib}, @ref{aa,,pdb}, @ref{b1,,poplib},
@ref{ca,,shutil}, @ref{cf,,smtplib}, @ref{d4,,sqlite3}, @ref{dc,,subprocess},
@code{telnetlib}, @ref{e6,,tempfile} and @ref{11b,,webbrowser}, as well as
@ref{12fb,,os.listdir()}, @ref{c4b,,os.scandir()} and @ref{271,,breakpoint()}.

@item 
bpo-37364@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37364}: @ref{19e7,,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<53>,Library<54>,Security<40>,Python 3 9 0 alpha 1
@anchor{whatsnew/changelog id475}@anchor{1c71}
@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{244,,RuntimeError} exception in @code{float.__getformat__()}.

@item 
bpo-38639@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38639}: Optimized @ref{15b5,,math.floor()}, @ref{15b6,,math.ceil()} and
@ref{15b7,,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{192,,bytes} and @ref{343,,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{343,,bytearray}, @ref{4b9,,array} and
@ref{514,,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{16f8,,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{183,,dict} constructor and the
@ref{165a,,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{2f2,,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{c33,,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{b53,,codecs.lookup()} to normalize the encoding name the
same way than @ref{9f6,,encodings.normalize_encoding()}, except that
@ref{b53,,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{17f,,break} and @ref{180,,continue}
in the @ref{1b0,,finally} block when the corresponding @ref{8f0,,try}
block contains @ref{1af,,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{1be1,,sq_item} of @ref{343,,bytearray}. Patch by
Sergey Fedoseev.

@item 
bpo-37802@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37802}: Slightly improve performance of
@ref{1831,,PyLong_FromUnsignedLong()}, @ref{1832,,PyLong_FromUnsignedLongLong()}
and @ref{1833,,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{1ae,,SyntaxWarning} instead
of @ref{1a3,,DeprecationWarning} for invalid escape sequences in string and
bytes literals.

@item 
bpo-37757@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37757}: 
@geindex Python Enhancement Proposals; PEP 572
PEP 572@footnote{https://peps.python.org/pep-0572/}: As described in the PEP, assignment expressions now
raise @ref{18e,,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{f91,,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{b57,,assert} statement now works properly if the
@ref{8b0,,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{1268,,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{a05,,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{1925,,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{b3a,,sys.getswitchinterval()} and @ref{b3b,,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{315,,open()}, @ref{ac9,,str.encode()} and @ref{aca,,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{315,,open()}, @ref{739,,io.open()}, @ref{314,,codecs.open()} and
@ref{938,,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{60b,,PySys_Audit()} call in @ref{514,,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{956,,PyBuffer_SizeFromFormat()} function
(previously documented but not implemented): call @ref{1c72,,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{c29,,threading.get_native_id()} now also supports NetBSD.

@item 
bpo-37077@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37077}: Add @ref{c29,,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{68e,,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{489,,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<54>,Documentation<47>,Core and Builtins<53>,Python 3 9 0 alpha 1
@anchor{whatsnew/changelog id476}@anchor{1c73}
@subsubsection Library



@itemize -

@item 
bpo-36589@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36589}: The @ref{fe6,,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{198,,TypeError} messages for @ref{1900,,os.path.join()} to
include @ref{e46,,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{19e7,,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{315,,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{b0d,,os.P_PIDFD} constant, which may be passed to
@ref{f94,,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{69d,,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{5d,,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{ae3,,curses.get_escdelay()}, @ref{ae4,,curses.set_escdelay()},
@ref{ae5,,curses.get_tabsize()}, and @ref{ae6,,curses.set_tabsize()} functions - by
Anthony Sottile.

@item 
bpo-38586@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38586}: Now @ref{d40,,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{b0b,,CLD_KILLED} and @ref{b0c,,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{cfd,,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{512,,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{1ad9,,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{11b6,,stat.S_IFDOOR}, @ref{11b7,,stat.S_IFPORT},
@ref{11b8,,stat.S_IFWHT}, @ref{1c74,,stat.S_ISDOOR()}, @ref{1c75,,stat.S_ISPORT()}, and
@ref{1c76,,stat.S_ISWHT()} values to the Python implementation of @ref{d6,,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{330,,typing.NamedTuple} are now
pickleable.

@item 
bpo-38332@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38332}: Prevent @ref{5df,,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{1c77,,smtplib.SMTPNotSupportedError} to the @ref{cf,,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{654,,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{d4e,,os.pread()} to accept
@ref{c4c,,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{330,,NamedTuple} and
@ref{331,,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{34,,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{106c,,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{eef,,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{106c,,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{2f2,,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{59b,,path-like object} as @code{directory}
argument to the @ref{d30,,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{cb,,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{10a,,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{6b5,,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{ea8,,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{ad8,,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{5d,,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{ad8,,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{c5a,,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{5c,,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{1c78,,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{3b,,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{109f,,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{da7,,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{3f,,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{d1,,socket}.

@item 
bpo-37685@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37685}: Fixed comparisons of @ref{bba,,datetime.timedelta} and
@ref{12c0,,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{1299,,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{1c79,,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{1a2,,NotImplemented} for unsupported type of
the other operand. This allows the other operand to play role (for example
the equality comparison with @ref{1c7a,,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{12c0,,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{5a,,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{1a2,,NotImplemented} in Python implementation of
@code{__eq__} for @ref{bba,,timedelta} and @ref{1fb,,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{1c7b,,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{130f,,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{c79,,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{bb,,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{4e0,,types.SimpleNamespace}. Patch by Carl Bordum Hansen.

@item 
bpo-26967@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26967}: An @ref{1bd,,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{1c7c,,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{5a2,,sqlite3.Connection.create_aggregate()},
@ref{5a1,,sqlite3.Connection.create_function()},
@ref{5a3,,sqlite3.Connection.set_authorizer()},
@ref{5a4,,sqlite3.Connection.set_progress_handler()}
@ref{5a5,,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{19bc,,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{b38,,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{1c7d,,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{8e,,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{5e8,,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{244,,RuntimeError} raised by
@ref{b46,,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{d79,,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{7ed,,collections.deque} in
@ref{c5d,,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{b24,,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{1c7e,,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{1c1,,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{1c7f,,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{18fb,,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{b10,,readlink()}. Patch by Girts Folkmanis.

@item 
bpo-32498@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32498}: Made @ref{1a41,,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{c48,,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<47>,Tests<48>,Library<54>,Python 3 9 0 alpha 1
@anchor{whatsnew/changelog id477}@anchor{1c80}
@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{3f,,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{244,,RuntimeError} is raised if
@ref{4b0,,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{603,,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{2e1,,sys.settrace()} docs.

@item 
bpo-37878@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37878}: Make @ref{1c81,,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{111,,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{656,,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{18b7,,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{34,,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{59b,,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<48>,Build<52>,Documentation<47>,Python 3 9 0 alpha 1
@anchor{whatsnew/changelog id478}@anchor{1c82}
@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{ea,,test.support}:
@ref{1c65,,LOOPBACK_TIMEOUT},
@ref{1c66,,INTERNET_TIMEOUT},
@ref{1b65,,SHORT_TIMEOUT} and
@ref{1c67,,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{1c83,,os.setsid()} and @ref{1c84,,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{34,,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{176,,threading.Thread} exception using
@ref{a44,,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{1c85,,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{1c86,,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{502,,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{1c87,,unittest.skip()} is
uncalled. Patch by Naitree Zhu.
@end itemize

@node Build<52>,Windows<48>,Tests<48>,Python 3 9 0 alpha 1
@anchor{whatsnew/changelog id479}@anchor{1c88}
@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{169,,str} and by the
@ref{10b,,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{1c89,,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<48>,macOS<38>,Build<52>,Python 3 9 0 alpha 1
@anchor{whatsnew/changelog id480}@anchor{1c8a}
@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{4d6,,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{262,,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{26d,,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{b11,,os.readlink()} (or
indirectly through @ref{262,,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{1c8b,,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{bfa,,exists()} and a valid result from @ref{26d,,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{6c1,,os.lstat()} and other reparse points as regular files in
@ref{26d,,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{653,,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{3eb,,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{1c8b,,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{1c8c,,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<38>,IDLE<31>,Windows<48>,Python 3 9 0 alpha 1
@anchor{whatsnew/changelog id481}@anchor{1c8d}
@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<31>,Tools/Demos<32>,macOS<38>,Python 3 9 0 alpha 1
@anchor{whatsnew/changelog id482}@anchor{1c8e}
@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<32>,C API<51>,IDLE<31>,Python 3 9 0 alpha 1
@anchor{whatsnew/changelog id483}@anchor{1c8f}
@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{1c90,,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<51>,,Tools/Demos<32>,Python 3 9 0 alpha 1
@anchor{whatsnew/changelog id484}@anchor{1c91}
@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{3d0,,Py_EnterRecursiveCall()} and
@ref{b62,,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{b70,,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{1791,,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{c3d,,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{3eb,,sys.executable} to the
program full path (@ref{3ea,,Py_GetProgramFullPath()}) rather than to the
program name (@ref{3ec,,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{da9,,Py_UNREACHABLE()} macro now calls
@ref{b71,,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{635,,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{635,,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{1c92,,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{18f5,,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{634,,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{1c93,,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{1c94}
@subsection Python 3.8.0 beta 1


`Release date: 2019-06-04'

@menu
* Security: Security<41>. 
* Core and Builtins: Core and Builtins<54>. 
* Library: Library<55>. 
* Documentation: Documentation<48>. 
* Tests: Tests<49>. 
* Build: Build<53>. 
* Windows: Windows<49>. 
* macOS: macOS<39>. 
* IDLE: IDLE<32>. 
* Tools/Demos: Tools/Demos<33>. 
* C API: C API<52>. 

@end menu

@node Security<41>,Core and Builtins<54>,,Python 3 8 0 beta 1
@anchor{whatsnew/changelog id485}@anchor{1c95}
@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{111,,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<54>,Library<55>,Security<41>,Python 3 8 0 beta 1
@anchor{whatsnew/changelog id486}@anchor{1c96}
@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{19b,,int}, @ref{196,,float} and
@ref{197,,complex} will now use the @ref{19e,,__index__()} special
method, if available and the corresponding method @ref{19d,,__int__()},
@ref{bb8,,__float__()} or @ref{7f8,,__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{bf5,,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{32e,,types.CodeType}).

@item 
bpo-37007@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37007}: Implement @ref{c19,,socket.if_nameindex()},
@ref{c1a,,socket.if_nametoindex()}, and @ref{c1b,,socket.if_indextoname()} on
Windows.

@item 
bpo-36829@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36829}: @ref{5ea,,PyErr_WriteUnraisable()} now creates a traceback object
if there is no current traceback. Moreover, call
@ref{428,,PyErr_NormalizeException()} and @ref{1c97,,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{18e,,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{3c1,,bool}, @ref{19b,,int}, @ref{196,,float}, @ref{197,,complex} and few
classes from the standard library. They now inherit @code{__str__()} from
@ref{c75,,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{895,,sys.flags} and @ref{1c98,,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<55>,Documentation<48>,Core and Builtins<54>,Python 3 8 0 beta 1
@anchor{whatsnew/changelog id487}@anchor{1c99}
@subsubsection Library



@itemize -

@item 
bpo-37128@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37128}: Added @ref{8d8,,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{c62,,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{4af,,_thread.start_new_thread()} now logs uncaught exception
raised by the function using @ref{502,,sys.unraisablehook()}, rather than
@ref{a05,,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{c35,,unittest.mock.AsyncMock} setup for autospeccing. Document newly
implemented async methods in @ref{108a,,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{1c9a,,symtable.symtable()} now accepts the same input types for
source code as the built-in @ref{4ac,,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{a44,,threading.excepthook()} function which handles
uncaught @ref{c28,,threading.Thread.run()} exception. It can be overridden to
control how uncaught @ref{c28,,threading.Thread.run()} exceptions are handled.

@item 
bpo-36996@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36996}: Handle @ref{108d,,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{9d1,,next()} with the mock resulting
from @ref{11e2,,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{9f9,,fileinput.input()} and @ref{938,,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 @ref{1e,,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{450,,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{132f,,shutil.copystat()} now ignores @ref{1c9b,,errno.EINVAL} on
@ref{1308,,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{1b7b,,asyncio.StreamReader} and @ref{19c2,,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{c63,,asyncio.create_subprocess_shell()} and
@ref{c62,,asyncio.create_subprocess_exec()} to use @code{asyncio.Stream}
instead of deprecated @code{StreamReader} and @code{StreamWriter}.
Deprecate @ref{1b7b,,asyncio.StreamReader} and @ref{19c2,,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{bef,,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{d4,,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{502,,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{1b3,,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{242,,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{be1,,BadGzipFile} exception to the @ref{6b,,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{c11,,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{1c9c,,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{1400,,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{11e2,,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{8d7,,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{1435,,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{21a,,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{1c9d,,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{c9,,shlex} module now exposes @ref{c13,,shlex.join()}, the
inverse of @ref{757,,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{4b2,,subprocess.Popen()} on Windows.  The `args' parameter now accepts a
@ref{59b,,path-like object} if `shell' is @code{False} and a sequence containing
bytes and path-like objects. The `executable' parameter now accepts a
bytes and @ref{59b,,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{1c9e,,pathlib.Path.unlink} now accepts a `missing_ok'
parameter to avoid a @ref{264,,FileNotFoundError} from being raised. Patch by
Robert Buchholz.

@item 
bpo-32941@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32941}: Allow @ref{514,,mmap.mmap} objects to access the madvise() system
call (through @ref{bf2,,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{18ce,,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<48>,Tests<49>,Library<55>,Python 3 8 0 beta 1
@anchor{whatsnew/changelog id488}@anchor{1c9f}
@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<49>,Build<53>,Documentation<48>,Python 3 8 0 beta 1
@anchor{whatsnew/changelog id489}@anchor{1ca0}
@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{1c86,,test.support.catch_unraisable_exception()} rather than
@ref{1ca1,,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{1c86,,test.support.catch_unraisable_exception()}: context
manager catching unraisable exception using @ref{502,,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{34,,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<53>,Windows<49>,Tests<49>,Python 3 8 0 beta 1
@anchor{whatsnew/changelog id490}@anchor{1ca2}
@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<49>,macOS<39>,Build<53>,Python 3 8 0 beta 1
@anchor{whatsnew/changelog id491}@anchor{1ca3}
@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{c92,,Py_DEPRECATED()} macro has been implemented for
MSVC.
@end itemize

@node macOS<39>,IDLE<32>,Windows<49>,Python 3 8 0 beta 1
@anchor{whatsnew/changelog id492}@anchor{1ca4}
@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<32>,Tools/Demos<33>,macOS<39>,Python 3 8 0 beta 1
@anchor{whatsnew/changelog id493}@anchor{1ca5}
@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<33>,C API<52>,IDLE<32>,Python 3 8 0 beta 1
@anchor{whatsnew/changelog id494}@anchor{1ca6}
@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<52>,,Tools/Demos<33>,Python 3 8 0 beta 1
@anchor{whatsnew/changelog id495}@anchor{1ca7}
@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{1ca8,,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{42e,,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{1ca9}
@subsection Python 3.8.0 alpha 4


`Release date: 2019-05-06'

@menu
* Security: Security<42>. 
* Core and Builtins: Core and Builtins<55>. 
* Library: Library<56>. 
* Documentation: Documentation<49>. 
* Tests: Tests<50>. 
* Build: Build<54>. 
* Windows: Windows<50>. 
* macOS: macOS<40>. 
* IDLE: IDLE<33>. 
* Tools/Demos: Tools/Demos<34>. 
* C API: C API<53>. 

@end menu

@node Security<42>,Core and Builtins<55>,,Python 3 8 0 alpha 4
@anchor{whatsnew/changelog id496}@anchor{1caa}
@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{6d4,,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,
@ref{6d4,,shutil.which()} and the @ref{dc,,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<55>,Library<56>,Security<42>,Python 3 8 0 alpha 4
@anchor{whatsnew/changelog id497}@anchor{1cab}
@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{105,,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{291,,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{640,,PyEval_RestoreThread()}, @ref{c76,,Py_END_ALLOW_THREADS()}, and
@ref{642,,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{1484,,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{88,,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{16f8,,PyObject_GC_Track()} calls in the
@ref{ab,,pickle} module. Patch by Zackery Spytz.
@end itemize

@node Library<56>,Documentation<49>,Core and Builtins<55>,Python 3 8 0 alpha 4
@anchor{whatsnew/changelog id498}@anchor{1cac}
@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{938,,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{3eb,,sys.executable} is
@code{None} or an empty string: use @ref{1874,,os.getcwd()} to initialize
@code{project_base}.  Fix also the distutils build command: don't use
@ref{3eb,,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{6d4,,shutil.which()} and @code{distutils.spawn.find_executable}
now use @code{os.confstr("CS_PATH")} if available instead of
@ref{1cad,,os.defpath}, if the @code{PATH} environment variable is not set.
Moreover, don't use @code{os.confstr("CS_PATH")} nor @ref{1cad,,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{16f,,-X} @code{dev}) and in debug build,
the @ref{500,,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{13e9,,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{73,,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{108d,,unittest.mock.patch()} object will now return @code{None} instead of
raising @ref{244,,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{bd6,,datetime.date.fromisocalendar()} and
@ref{bd7,,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{7a,,imp} module, and the initializer for
@ref{1cae,,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{c17,,create_server()} and
@ref{c18,,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{489,,classmethod()} and @ref{451,,staticmethod()} to
@ref{189a,,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{c36,,unittest.mock.Mock}.

@item 
bpo-34547@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34547}: @ref{1c9c,,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{1caf,,xml.sax.parse()} now supports @ref{59b,,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<49>,Tests<50>,Library<56>,Python 3 8 0 alpha 4
@anchor{whatsnew/changelog id499}@anchor{1cb0}
@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{11e,,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{11e,,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<50>,Build<54>,Documentation<49>,Python 3 8 0 alpha 4
@anchor{whatsnew/changelog id500}@anchor{1cb1}
@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{1cb2,,errno.ENETUNREACH} error.

@item 
bpo-36611@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36611}: Fix @code{test_sys.test_getallocatedblocks()} when
@ref{105,,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<54>,Windows<50>,Tests<50>,Python 3 8 0 alpha 4
@anchor{whatsnew/changelog id501}@anchor{1cb3}
@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{28e,,sys.getobjects()} function
and the 
@geindex PYTHONDUMPREFS
@geindex 環境變數; PYTHONDUMPREFS
@ref{b95,,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<50>,macOS<40>,Build<54>,Python 3 8 0 alpha 4
@anchor{whatsnew/changelog id502}@anchor{1cb4}
@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{bd4,,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<40>,IDLE<33>,Windows<50>,Python 3 8 0 alpha 4
@anchor{whatsnew/changelog id503}@anchor{1cb5}
@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<33>,Tools/Demos<34>,macOS<40>,Python 3 8 0 alpha 4
@anchor{whatsnew/changelog id504}@anchor{1cb6}
@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<34>,C API<53>,IDLE<33>,Python 3 8 0 alpha 4
@anchor{whatsnew/changelog id505}@anchor{1cb7}
@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<53>,,Tools/Demos<34>,Python 3 8 0 alpha 4
@anchor{whatsnew/changelog id506}@anchor{1cb8}
@subsubsection C API



@itemize -

@item 
bpo-36763@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36763}: Fix memory leak in @code{Py_SetStandardStreamEncoding()}:
release memory if the function is called twice.

@item 
bpo-36641@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36641}: PyDoc_VAR(name) and @ref{1c24,,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{e5f,,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{dbb,,Py_DecodeLocale()} before
@ref{45e,,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{1cb9,,PyDate_FromTimestamp()} function were incorrectly
interpreted as a single timestamp rather than an arguments tuple, which
causes existing code to start raising @ref{198,,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{1cba}
@subsection Python 3.8.0 alpha 3


`Release date: 2019-03-25'

@menu
* Security: Security<43>. 
* Core and Builtins: Core and Builtins<56>. 
* Library: Library<57>. 
* Documentation: Documentation<50>. 
* Tests: Tests<51>. 
* Build: Build<55>. 
* Windows: Windows<51>. 
* IDLE: IDLE<34>. 
* Tools/Demos: Tools/Demos<35>. 
* C API: C API<54>. 

@end menu

@node Security<43>,Core and Builtins<56>,,Python 3 8 0 alpha 3
@anchor{whatsnew/changelog id507}@anchor{1cbb}
@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{1cbc,,http.cookiejar.DefaultCookiePolicy} policy. Patch
by Karthikeyan Singaravelan.
@end itemize

@node Core and Builtins<56>,Library<57>,Security<43>,Python 3 8 0 alpha 3
@anchor{whatsnew/changelog id508}@anchor{1cbd}
@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{3e2,,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{4ac,,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{f07,,pickle.load()}, @ref{1cbe,,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{19e,,__index__()} special method will be used
instead of @ref{19d,,__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<57>,Documentation<50>,Core and Builtins<56>,Python 3 8 0 alpha 3
@anchor{whatsnew/changelog id509}@anchor{1cbf}
@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{e4,,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{8b,,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{514,,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{1cc0,,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{59b,,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{12e0,,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{189a,,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<50>,Tests<51>,Library<57>,Python 3 8 0 alpha 3
@anchor{whatsnew/changelog id510}@anchor{1cc1}
@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<51>,Build<55>,Documentation<50>,Python 3 8 0 alpha 3
@anchor{whatsnew/changelog id511}@anchor{1cc2}
@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<55>,Windows<51>,Tests<51>,Python 3 8 0 alpha 3
@anchor{whatsnew/changelog id512}@anchor{1cc3}
@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<51>,IDLE<34>,Build<55>,Python 3 8 0 alpha 3
@anchor{whatsnew/changelog id513}@anchor{1cc4}
@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<34>,Tools/Demos<35>,Windows<51>,Python 3 8 0 alpha 3
@anchor{whatsnew/changelog id514}@anchor{1cc5}
@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<35>,C API<54>,IDLE<34>,Python 3 8 0 alpha 3
@anchor{whatsnew/changelog id515}@anchor{1cc6}
@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<54>,,Tools/Demos<35>,Python 3 8 0 alpha 3
@anchor{whatsnew/changelog id516}@anchor{1cc7}
@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{1cc8}
@subsection Python 3.8.0 alpha 2


`Release date: 2019-02-25'

@menu
* Core and Builtins: Core and Builtins<57>. 
* Library: Library<58>. 
* Documentation: Documentation<51>. 
* Tests: Tests<52>. 
* Windows: Windows<52>. 
* IDLE: IDLE<35>. 

@end menu

@node Core and Builtins<57>,Library<58>,,Python 3 8 0 alpha 2
@anchor{whatsnew/changelog id517}@anchor{1cc9}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-36052@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36052}: Raise a @ref{18e,,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{e46,,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{dc3,,list.sort()} when sorting objects
with @code{ob_type->tp_richcompare == NULL}.  Patch by Zackery Spytz.
@end itemize

@node Library<58>,Documentation<51>,Core and Builtins<57>,Python 3 8 0 alpha 2
@anchor{whatsnew/changelog id518}@anchor{1cca}
@subsubsection Library



@itemize -

@item 
bpo-35512@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35512}: @ref{18ce,,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{6d4,,shutil.which()}.

@item 
bpo-35960@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35960}: Fix @ref{18c1,,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{1ccb,,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{142d,,re.search()}, @ref{1225,,re.findall()}, @ref{59d,,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{11a,,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{bee,,math.prod()} as analogous function to
@ref{68e,,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{4dd,,datetime.datetime}
subclasses and @ref{bba,,datetime.timedelta} now returns an object of the
same type as the @ref{4dd,,datetime.datetime} subclass. As a result,
@ref{bbb,,datetime.datetime.astimezone()} and alternate constructors like
@ref{70a,,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{c43,,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<51>,Tests<52>,Library<58>,Python 3 8 0 alpha 2
@anchor{whatsnew/changelog id519}@anchor{1ccc}
@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<52>,Windows<52>,Documentation<51>,Python 3 8 0 alpha 2
@anchor{whatsnew/changelog id520}@anchor{1ccd}
@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<52>,IDLE<35>,Tests<52>,Python 3 8 0 alpha 2
@anchor{whatsnew/changelog id521}@anchor{1cce}
@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<35>,,Windows<52>,Python 3 8 0 alpha 2
@anchor{whatsnew/changelog id522}@anchor{1ccf}
@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{1cd0}
@subsection Python 3.8.0 alpha 1


`Release date: 2019-02-03'

@menu
* Security: Security<44>. 
* Core and Builtins: Core and Builtins<58>. 
* Library: Library<59>. 
* Documentation: Documentation<52>. 
* Tests: Tests<53>. 
* Build: Build<56>. 
* Windows: Windows<53>. 
* macOS: macOS<41>. 
* IDLE: IDLE<36>. 
* Tools/Demos: Tools/Demos<36>. 
* C API: C API<55>. 

@end menu

@node Security<44>,Core and Builtins<58>,,Python 3 8 0 alpha 1
@anchor{whatsnew/changelog id523}@anchor{1cd1}
@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{b4e,,-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{b4d,,-E} and
@ref{1586,,-s} options (enabled by @ref{b4e,,-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{cfd,,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<58>,Library<59>,Security<44>,Python 3 8 0 alpha 1
@anchor{whatsnew/changelog id524}@anchor{1cd2}
@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{199,,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{623,,PyUnicode_FromFormat()} and @code{%s} in @ref{1cd3,,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{78e,,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{82c,,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{138,,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{d1,,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{2eb,,ValueError} instead of @ref{a78,,OverflowError} in case
of a negative @code{_length_} in a @ref{1cd4,,ctypes.Array} subclass.  Also
raise @ref{198,,TypeError} instead of @ref{5e8,,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{1ae,,SyntaxWarning} raised as an exception at code generation
time will be now replaced with a @ref{18e,,SyntaxError} for better error
reporting.

@item 
bpo-34983@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34983}: Expose @ref{1cd5,,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{192,,bytes} and @ref{343,,bytearray} constructors no longer
convert unexpected exceptions (e.g. @ref{181e,,MemoryError} and
@ref{bbc,,KeyboardInterrupt}) to @ref{198,,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{192,,bytes()} when the @ref{24d,,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{1ae,,SyntaxWarning} is now emitted instead of a
@ref{1a3,,DeprecationWarning} for invalid escape sequences in string and bytes
literals.

@item 
bpo-34854@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34854}: Fixed a crash in compiling string annotations containing a
lambda with a keyword-only argument that doesn't have a default value.

@item 
bpo-34850@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34850}: The compiler now produces a @ref{1ae,,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{28e,,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{315,,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{5e8,,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{501,,io.IOBase.close()}, ensure that the
@ref{1cd6,,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{1bbe,,PyRun_SimpleFileExFlags()}
before calling @ref{1bfa,,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{1baa,,PyIter_Check()}, @ref{b78,,PyIndex_Check()} and
@ref{c52,,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{13c2,,gc.garbage} list. @ref{b7c,,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{244,,RuntimeError} is now raised when the custom metaclass
doesn't provide the @code{__classcell__} entry in the namespace passed to
@code{type.__new__}.  A @ref{1a3,,DeprecationWarning} was emitted in Python
3.6--3.7.

@item 
bpo-33499@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33499}: Add 
@geindex PYTHONPYCACHEPREFIX
@geindex 環境變數; PYTHONPYCACHEPREFIX
@ref{b92,,PYTHONPYCACHEPREFIX} environment variable and
@ref{16f,,-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{138,,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{c97,,END_ASYNC_FOR} and fixes the
following issues:


@itemize *

@item 
Setting global @ref{1cd7,,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{180,,continue} statement is now allowed in the
@ref{1b0,,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{17f,,break}, @ref{180,,continue} and
@ref{1af,,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<59>,Documentation<52>,Core and Builtins<58>,Python 3 8 0 alpha 1
@anchor{whatsnew/changelog id525}@anchor{1cd8}
@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{529,,os.posix_spawn()} and @ref{1cd9,,os.posix_spawnp()} now have a
`setsid' parameter.

@item 
bpo-23846@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23846}: @ref{816,,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{1cd9,,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{92,,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{c2e,,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{acb,,help()} and
@ref{ba,,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{b90,,divmod()}
function on @ref{213,,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{dc,,subprocess} module can now use the
@ref{529,,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{2e,,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{d9c,,uuid.uuid1()} now calls @ref{cd7,,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{c71,,time.perf_counter()} rather than
@ref{557,,time.time()} to measure the execution time of a test:
@ref{557,,time.time()} can go backwards, whereas @ref{c71,,time.perf_counter()} is
monotonic.

@item 
bpo-35502@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35502}: Fixed reference leaks in
@ref{c41,,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{1955,,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{c36,,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{82,,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{547,,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{5df,,KeyError} on calling @ref{1cda,,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{cc,,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{177b,,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{f9b,,select.select()} where, in some cases, the
file descriptor sequences were returned unmodified after a signal
interruption, even though the file descriptors might not be ready yet.
@ref{f9b,,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{1cdb,,platform.uname()} now redirects @code{stderr} to
@ref{1cdc,,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{319,,os.popen()} instead.

@item 
bpo-35344@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35344}: On macOS, @ref{1a11,,platform.platform()} now uses
@ref{1cdd,,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{df3,,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{1c7c,,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{198f,,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{67,,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{1340,,socketserver.BaseServer.serve_forever()} now exits
immediately if it's @ref{1cde,,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{108a,,unittest.mock.MagicMock} now supports the
@code{__fspath__} method (from @ref{e46,,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{361,,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{30c,,inspect.iscoroutinefunction()},
@ref{1a8a,,inspect.isgeneratorfunction()} and @ref{1a8b,,inspect.isasyncgenfunction()}
work with @ref{217,,functools.partial()}. Patch by Pablo Galindo.

@item 
bpo-34521@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34521}: Use @ref{1cdf,,socket.CMSG_SPACE()} to calculate ancillary data size
instead of @ref{1ce0,,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{ba,,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{1ce1,,mimetypes.MimeTypes.guess_type()} now accepts
@ref{59b,,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{12b,,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{b1e,,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{1ce2,,digest()} and
@ref{1ce3,,hexdigest()} methods for the SHAKE algorithm in the
@ref{6c,,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{1b4b,,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{c11,,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{1ce4,,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{138,,zipimport}.

@item 
bpo-32892@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32892}: The parser now represents all constants as
@ref{2ee,,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{ef1,,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{13ea,,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{523,,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{c37,,addModuleCleanup()} and
@ref{c38,,addClassCleanup()} to unittest to support cleanups
for @ref{c39,,setUpModule()} and
@ref{c3a,,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{dc,,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{dc,,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{1cad,,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{2eb,,ValueError} is now raised by
@ref{1ce5,,multiprocessing.Queue.put()} and @ref{1ce6,,multiprocessing.Queue.get()}
instead of @ref{8b0,,AssertionError} and @ref{2c0,,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{137,,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{103,,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{9bd,,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{1ce7,,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{b11,,os.readlink()} now accepts @ref{59b,,path-like} and @ref{192,,bytes} objects on Windows.

@item 
bpo-22602@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22602}: The UTF-7 decoder now raises @ref{bff,,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{c86,,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{18bd,,pathlib.PurePath.with_suffix()} when
formatting an error message.

@item 
bpo-18540@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18540}: The @ref{af6,,imaplib.IMAP4} and @ref{af7,,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{749,,assertRaises()},
@ref{74b,,assertRaisesRegex()},
@ref{1365,,assertWarns()} and
@ref{1366,,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{582,,__getitem__()} methods of
@ref{936,,xml.dom.pulldom.DOMEventStream}, @ref{937,,wsgiref.util.FileWrapper}
and @ref{938,,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{1ce8,,dbm.gnu.open()} and @ref{1ce9,,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{1055,,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{bc8,,get_name()} and
@ref{bc7,,set_name()}) and is visible in the @ref{1c1,,repr()} output.
An initial name can also be set using the new @code{name} keyword argument to
@ref{1c9,,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{d4,,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{1304,,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{5a2,,sqlite3.Connection.create_aggregate()},
@ref{5a1,,sqlite3.Connection.create_function()},
@ref{5a3,,sqlite3.Connection.set_authorizer()},
@ref{5a4,,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{2d,,csv} reader are now @ref{3c1,,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{198,,TypeError} raised in methods
@code{__adapt__()} and @code{__conform__()} in the @ref{d4,,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{736,,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{1220,,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{6c,,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{5a1,,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{556,,time.monotonic()} instead of the system clock @ref{557,,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{ff,,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{d4d,,os.readv()}, @ref{d50,,os.writev()},
@ref{d4c,,os.preadv()} and @ref{d4f,,os.pwritev()} and in @ref{cfd,,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{750,,copy.copy()} and @ref{d5d,,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{c15,,shutil.copytree()} uses @ref{c4b,,os.scandir()} function and
all copy functions depending from it use cached @ref{26d,,os.stat()} values.
The speedup for copying a directory with 8000 files is around +9% on
Linux, +20% on Windows and + 30% on a Windows SMB share. Also the number
of @ref{26d,,os.stat()} syscalls is reduced by 38% making
@ref{c15,,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{bfa,,exists()}, @ref{bfb,,lexists()}, @ref{bfc,,isdir()},
@ref{bfd,,isfile()}, @ref{bf8,,islink()}, and
@ref{bfe,,ismount()}, and @ref{266,,pathlib.Path} methods that return a
boolean result like @ref{c02,,exists()},
@ref{535,,is_dir()}, @ref{534,,is_file()},
@ref{c03,,is_mount()}, @ref{c04,,is_symlink()},
@ref{c05,,is_block_device()},
@ref{c06,,is_char_device()}, @ref{c07,,is_fifo()},
@ref{c08,,is_socket()} now return @code{False} instead of raising
@ref{2eb,,ValueError} or its subclasses @ref{880,,UnicodeEncodeError} and
@ref{bff,,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{177b,,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{198,,TypeError} instead of @ref{78e,,SystemError} when
performed on @ref{514,,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{11b,,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{80e,,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{c45,,shutil.copyfile()}, @ref{c46,,shutil.copy()},
@ref{c47,,shutil.copy2()}, @ref{c15,,shutil.copytree()} and @ref{c48,,shutil.move()} use
platform-specific fast-copy syscalls on Linux and macOS in order to copy
the file more efficiently. On Windows @ref{c45,,shutil.copyfile()} uses a
bigger default buffer size (1 MiB instead of 16 KiB) and a
@ref{165,,memoryview()}-based variant of @ref{c49,,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{d9c,,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{6fa,,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{d2,,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{108a,,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{1cea,,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{7ec,,collections.OrderedDict} to the standard
@ref{183,,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{c40,,XMLParser}.  The
@code{doctype()} method defined in a subclass will no longer be called.
Deprecated methods @code{getchildren()} and @code{getiterator()} in the
@ref{12b,,ElementTree} module emit now a @ref{1a3,,DeprecationWarning}
instead of @ref{abd,,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{73,,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{11e2,,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{198,,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{38,,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{112c,,dis.stack_effect()}.

@item 
bpo-27485@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27485}: Rename and deprecate undocumented functions in
@ref{110,,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{1ceb,,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{112c,,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{1cec,,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{4fe,,importlib.resources.contents()} and
@ref{1ced,,importlib.abc.ResourceReader.contents()} return an @ref{1428,,iterable}
instead of an @ref{4c3,,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{23c,,-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{3e2,,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{7f3,,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{1cee,,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{529,,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{84,,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{119,,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{f6,,tkinter}, @code{after_cancel(None)} now raises a
@ref{2eb,,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{17cd,,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{36,,dbm.dumb} database opened with flags 'r' is now
read-only. @ref{c84,,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{ff,,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{1cef,,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{bd1,,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{4dd,,datetime}, @ref{1fa,,date} and
@ref{1fb,,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{548,,sqlite3.Connection} now exposes a
@ref{d6b,,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{2e,,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<52>,Tests<53>,Library<59>,Python 3 8 0 alpha 1
@anchor{whatsnew/changelog id526}@anchor{1cf0}
@subsubsection Documentation



@itemize -

@item 
bpo-21257@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21257}: Document @ref{1cf1,,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{54,,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{d06,,asyncio.open_connection()},
@ref{d07,,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{136,,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{ea,,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{5e8,,AttributeError}.

@item 
bpo-32614@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32614}: Modify RE examples in documentation to use raw strings to
prevent @ref{1a3,,DeprecationWarning} and add text to REGEX HOWTO to highlight
the deprecation.

@item 
bpo-20709@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20709}: Remove the paragraph where we explain that os.utime() does not
support a directory as path under Windows. Patch by Jan-Philip Gehrcke

@item 
bpo-32722@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32722}: Remove the bad example in the tutorial of the Generator
Expression. Patch by Stéphane Wirtel

@item 
bpo-31972@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31972}: Improve docstrings for @code{pathlib.PurePath} subclasses.

@item 
bpo-30607@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30607}: Use the externalized @code{python-docs-theme} package when
building the documentation.

@item 
bpo-8243@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8243}: Add a note about curses.addch and curses.addstr exception
behavior when writing outside a window, or pad.

@item 
bpo-32337@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32337}: Update documentation related with @code{dict} order.

@item 
bpo-25041@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25041}: Document @code{AF_PACKET} in the @ref{d1,,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<53>,Build<56>,Documentation<52>,Python 3 8 0 alpha 1
@anchor{whatsnew/changelog id527}@anchor{1cf2}
@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{557,,time.time()} with @ref{556,,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<56>,Windows<53>,Tests<53>,Python 3 8 0 alpha 1
@anchor{whatsnew/changelog id528}@anchor{1cf3}
@subsubsection Build



@itemize -

@item 
bpo-34691@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34691}: The _contextvars module is now built into the core Python
library on Windows.

@item 
bpo-35683@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35683}: Improved Azure Pipelines build steps and now verifying layouts
correctly

@item 
bpo-35642@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35642}: Remove asynciomodule.c from pythoncore.vcxproj

@item 
bpo-35550@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35550}: Fix incorrect Solaris #ifdef checks to look for __sun && __SVR4
instead of sun when compiling.

@item 
bpo-35499@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35499}: @code{make profile-opt} no longer replaces @code{CFLAGS_NODIST} with
@code{CFLAGS}. It now adds profile-guided optimization (PGO) flags to
@code{CFLAGS_NODIST}: existing @code{CFLAGS_NODIST} flags are kept.

@item 
bpo-35257@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35257}: Avoid leaking the linker flags from Link Time Optimizations
(LTO) into distutils when compiling C extensions.

@item 
bpo-35351@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35351}: When building Python with clang and LTO, LTO flags are no
longer passed into CFLAGS to build third-party C extensions through
distutils.

@item 
bpo-35139@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35139}: Fix a compiler error when statically linking @code{pyexpat} in
@code{Modules/Setup}.

@item 
bpo-35059@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35059}: PCbuild: Set InlineFunctionExpansion to OnlyExplicitInline
("/Ob1" option) in pyproject.props in Debug mode to expand functions
marked as inline. This change should make Python compiled in Debug mode a
little bit faster on Windows.

@item 
bpo-35011@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35011}: Restores the use of pyexpatns.h to isolate our embedded copy of
the expat C library so that its symbols do not conflict at link or dynamic
loading time with an embedding application or other extension modules with
their own version of libexpat.

@item 
bpo-28015@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28015}: Have --with-lto works correctly with clang.

@item 
bpo-34765@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34765}: Update the outdated install-sh file to the latest revision from
automake v1.16.1

@item 
bpo-34585@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34585}: Check for floating-point byte order in configure.ac using
compilation tests instead of executing code, so that these checks work in
cross-compiled builds.

@item 
bpo-34710@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34710}: Fixed SSL module build with OpenSSL & pedantic CFLAGS.

@item 
bpo-34582@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34582}: Add JUnit XML output for regression tests and update Azure
DevOps builds.

@item 
bpo-34081@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34081}: Make Sphinx warnings as errors in the Docs Makefile.

@item 
bpo-34555@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34555}: Fix for case where it was not possible to have both
@code{HAVE_LINUX_VM_SOCKETS_H} and @code{HAVE_SOCKADDR_ALG} be undefined.

@item 
bpo-33015@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33015}: Fix an undefined behaviour in the pthread implementation of
@code{PyThread_start_new_thread()}: add a function wrapper to always
return @code{NULL}.

@item 
bpo-34245@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34245}: The Python shared library is now installed with write
permission (mode 0755), which is the standard way of installing such
libraries.

@item 
bpo-34121@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34121}: Fix detection of C11 atomic support on clang.

@item 
bpo-32430@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32430}: Rename Modules/Setup.dist to Modules/Setup, and remove the
necessity to copy the former manually to the latter when updating the
local source tree.

@item 
bpo-30345@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30345}: Add -g to LDFLAGS when compiling with LTO to get debug symbols.

@item 
bpo-5755@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5755}: Move @code{-Wstrict-prototypes} option to @code{CFLAGS_NODIST} from
@code{OPT}. This option emitted annoying warnings when building extension
modules written in C++.

@item 
bpo-33614@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33614}: Ensures module definition files for the stable ABI on Windows
are correctly regenerated.

@item 
bpo-33648@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33648}: The --with-c-locale-warning configuration flag has been
removed. It has had no effect for about a year.

@item 
bpo-33522@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33522}: Enable CI builds on Visual Studio Team Services at
@indicateurl{https://python.visualstudio.com/cpython}

@item 
bpo-33512@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33512}: configure's check for "long double" has been simplified

@item 
bpo-33483@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33483}: C compiler is now correctly detected from the standard
environment variables. --without-gcc and --with-icc options have been
removed.

@item 
bpo-33394@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33394}: Enable the verbose build for extension modules, when GNU make
is passed macros on the command line.

@item 
bpo-33393@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33393}: Update config.guess and config.sub files.

@item 
bpo-33377@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33377}: Add new triplets for mips r6 and riscv variants (used in
extension suffixes).

@item 
bpo-32232@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32232}: By default, modules configured in @code{Modules/Setup} are no
longer built with @code{-DPy_BUILD_CORE}. Instead, modules that specifically
need that preprocessor definition include it in their individual entries.

@item 
bpo-33182@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33182}: The embedding tests can once again be built with clang 6.0

@item 
bpo-33163@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33163}: Upgrade pip to 9.0.3 and setuptools to v39.0.1.

@item 
bpo-33012@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33012}: gcc 8 has added a new warning heuristic to detect invalid
function casts and a stock python build seems to hit that warning quite
often.  The most common is the cast of a METH_NOARGS function (that uses
just one argument) to a PyCFunction. Fix this by adding a dummy argument
to all functions that implement METH_NOARGS.

@item 
bpo-32898@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32898}: Fix the python debug build when using COUNT_ALLOCS.

@item 
bpo-29442@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29442}: Replace optparse with argparse in setup.py
@end itemize

@node Windows<53>,macOS<41>,Build<56>,Python 3 8 0 alpha 1
@anchor{whatsnew/changelog id529}@anchor{1cf4}
@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{2c0,,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{b11,,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<41>,IDLE<36>,Windows<53>,Python 3 8 0 alpha 1
@anchor{whatsnew/changelog id530}@anchor{1cf5}
@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<36>,Tools/Demos<36>,macOS<41>,Python 3 8 0 alpha 1
@anchor{whatsnew/changelog id531}@anchor{1cf6}
@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{1b8,,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<36>,C API<55>,IDLE<36>,Python 3 8 0 alpha 1
@anchor{whatsnew/changelog id532}@anchor{1cf7}
@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<55>,,Tools/Demos<36>,Python 3 8 0 alpha 1
@anchor{whatsnew/changelog id533}@anchor{1cf8}
@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{1921,,_PyBytes_Resize()} for empty bytes objects.

@item 
bpo-35322@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35322}: Fix memory leak in @ref{dbe,,PyUnicode_EncodeLocale()} and
@ref{1cf9,,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{788,,Py_INCREF()}, @ref{789,,Py_DECREF()}, @ref{c51,,Py_XINCREF()},
@ref{98a,,Py_XDECREF()}, @code{PyObject_INIT()},
@code{PyObject_INIT_VAR()}.

@item 
bpo-35296@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35296}: @code{make install} now also installs the internal API:
@code{Include/internal/*.h} header files.

@item 
bpo-35081@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35081}: Internal APIs surrounded by @code{#ifdef Py_BUILD_CORE} have been
moved from @code{Include/*.h} headers to new header files
@code{Include/internal/pycore_*.h}.

@item 
bpo-35259@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35259}: Conditionally declare @ref{f0c,,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{18e5,,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{78e,,SystemError} in
@ref{61c,,PyArg_ParseTupleAndKeywords()} when the @code{w*} format unit is used
for optional parameter.

@item 
bpo-32455@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32455}: Added @code{PyCompile_OpcodeStackEffectWithJump()}.

@item 
bpo-34008@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34008}: Py_Main() can again be called after Py_Initialize(), as in
Python 3.6.

@item 
bpo-32500@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32500}: Fixed error messages for @ref{1cfa,,PySequence_Size()},
@ref{1cfb,,PySequence_GetItem()}, @ref{1cfc,,PySequence_SetItem()} and
@ref{1cfd,,PySequence_DelItem()} called with a mapping and
@ref{1cfe,,PyMapping_Size()} called with a sequence.

@item 
bpo-33818@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33818}: @ref{c52,,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{1cff,,PyUnicode_AsWideChar()} and
@ref{ab0,,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{1d00}
@subsection Python 3.7.0 final


`Release date: 2018-06-27'

@menu
* Library: Library<60>. 
* C API: C API<56>. 

@end menu

@node Library<60>,C API<56>,,Python 3 7 0 final
@anchor{whatsnew/changelog id534}@anchor{1d01}
@subsubsection Library



@itemize -

@item 
bpo-33851@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33851}: Fix @ref{1d02,,ast.get_docstring()} for a node that lacks a
docstring.
@end itemize

@node C API<56>,,Library<60>,Python 3 7 0 final
@anchor{whatsnew/changelog id535}@anchor{1d03}
@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{1d04}
@subsection Python 3.7.0 release candidate 1


`Release date: 2018-06-12'

@menu
* Core and Builtins: Core and Builtins<59>. 
* Library: Library<61>. 
* Documentation: Documentation<53>. 
* Build: Build<57>. 
* Windows: Windows<54>. 
* IDLE: IDLE<37>. 

@end menu

@node Core and Builtins<59>,Library<61>,,Python 3 7 0 release candidate 1
@anchor{whatsnew/changelog id536}@anchor{1d05}
@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<61>,Documentation<53>,Core and Builtins<59>,Python 3 7 0 release candidate 1
@anchor{whatsnew/changelog id537}@anchor{1d06}
@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{198,,TypeError} instead of @ref{78e,,SystemError} when
performed on @ref{514,,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<53>,Build<57>,Library<61>,Python 3 7 0 release candidate 1
@anchor{whatsnew/changelog id538}@anchor{1d07}
@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{d06,,asyncio.open_connection()},
@ref{d07,,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<57>,Windows<54>,Documentation<53>,Python 3 7 0 release candidate 1
@anchor{whatsnew/changelog id539}@anchor{1d08}
@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<54>,IDLE<37>,Build<57>,Python 3 7 0 release candidate 1
@anchor{whatsnew/changelog id540}@anchor{1d09}
@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<37>,,Windows<54>,Python 3 7 0 release candidate 1
@anchor{whatsnew/changelog id541}@anchor{1d0a}
@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{1d0b}
@subsection Python 3.7.0 beta 5


`Release date: 2018-05-30'

@menu
* Core and Builtins: Core and Builtins<60>. 
* Library: Library<62>. 
* Documentation: Documentation<54>. 
* Tests: Tests<54>. 
* Build: Build<58>. 
* macOS: macOS<42>. 
* IDLE: IDLE<38>. 

@end menu

@node Core and Builtins<60>,Library<62>,,Python 3 7 0 beta 5
@anchor{whatsnew/changelog id542}@anchor{1d0c}
@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{13c2,,gc.garbage} list. @ref{b7c,,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<62>,Documentation<54>,Core and Builtins<60>,Python 3 7 0 beta 5
@anchor{whatsnew/changelog id543}@anchor{1d0d}
@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{80e,,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{d9c,,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{d2,,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{2e,,ctypes}.  Patch by Segev Finer.
@end itemize

@node Documentation<54>,Tests<54>,Library<62>,Python 3 7 0 beta 5
@anchor{whatsnew/changelog id544}@anchor{1d0e}
@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<54>,Build<58>,Documentation<54>,Python 3 7 0 beta 5
@anchor{whatsnew/changelog id545}@anchor{1d0f}
@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<58>,macOS<42>,Tests<54>,Python 3 7 0 beta 5
@anchor{whatsnew/changelog id546}@anchor{1d10}
@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<42>,IDLE<38>,Build<58>,Python 3 7 0 beta 5
@anchor{whatsnew/changelog id547}@anchor{1d11}
@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<38>,,macOS<42>,Python 3 7 0 beta 5
@anchor{whatsnew/changelog id548}@anchor{1d12}
@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{1d13}
@subsection Python 3.7.0 beta 4


`Release date: 2018-05-02'

@menu
* Core and Builtins: Core and Builtins<61>. 
* Library: Library<63>. 
* Documentation: Documentation<55>. 
* Tests: Tests<55>. 
* Build: Build<59>. 
* Windows: Windows<55>. 
* macOS: macOS<43>. 
* IDLE: IDLE<39>. 
* Tools/Demos: Tools/Demos<37>. 

@end menu

@node Core and Builtins<61>,Library<63>,,Python 3 7 0 beta 4
@anchor{whatsnew/changelog id549}@anchor{1d14}
@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<63>,Documentation<55>,Core and Builtins<61>,Python 3 7 0 beta 4
@anchor{whatsnew/changelog id550}@anchor{1d15}
@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{38,,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{1cec,,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{4fe,,importlib.resources.contents()} and
@ref{1ced,,importlib.abc.ResourceReader.contents()} return an @ref{1428,,iterable}
instead of an @ref{4c3,,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{23c,,-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{3e2,,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{7f3,,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{198,,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{1cee,,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{529,,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<55>,Tests<55>,Library<63>,Python 3 7 0 beta 4
@anchor{whatsnew/changelog id551}@anchor{1d16}
@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<55>,Build<59>,Documentation<55>,Python 3 7 0 beta 4
@anchor{whatsnew/changelog id552}@anchor{1d17}
@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<59>,Windows<55>,Tests<55>,Python 3 7 0 beta 4
@anchor{whatsnew/changelog id553}@anchor{1d18}
@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<55>,macOS<43>,Build<59>,Python 3 7 0 beta 4
@anchor{whatsnew/changelog id554}@anchor{1d19}
@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<43>,IDLE<39>,Windows<55>,Python 3 7 0 beta 4
@anchor{whatsnew/changelog id555}@anchor{1d1a}
@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<39>,Tools/Demos<37>,macOS<43>,Python 3 7 0 beta 4
@anchor{whatsnew/changelog id556}@anchor{1d1b}
@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<37>,,IDLE<39>,Python 3 7 0 beta 4
@anchor{whatsnew/changelog id557}@anchor{1d1c}
@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{1d1d}
@subsection Python 3.7.0 beta 3


`Release date: 2018-03-29'

@menu
* Security: Security<45>. 
* Core and Builtins: Core and Builtins<62>. 
* Library: Library<64>. 
* Documentation: Documentation<56>. 
* Tests: Tests<56>. 
* Build: Build<60>. 
* Windows: Windows<56>. 
* macOS: macOS<44>. 
* IDLE: IDLE<40>. 
* Tools/Demos: Tools/Demos<38>. 
* C API: C API<57>. 

@end menu

@node Security<45>,Core and Builtins<62>,,Python 3 7 0 beta 3
@anchor{whatsnew/changelog id558}@anchor{1d1e}
@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<62>,Library<64>,Security<45>,Python 3 7 0 beta 3
@anchor{whatsnew/changelog id559}@anchor{1d1f}
@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<64>,Documentation<56>,Core and Builtins<62>,Python 3 7 0 beta 3
@anchor{whatsnew/changelog id560}@anchor{1d20}
@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{84,,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{119,,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{f6,,tkinter}, @code{after_cancel(None)} now raises a
@ref{2eb,,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{548,,sqlite3.Connection} now exposes a
@ref{d6b,,backup} method, if the underlying SQLite
library is at version 3.6.11 or higher.  Patch by Lele Gaifax.
@end itemize

@node Documentation<56>,Tests<56>,Library<64>,Python 3 7 0 beta 3
@anchor{whatsnew/changelog id561}@anchor{1d21}
@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{136,,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<56>,Build<60>,Documentation<56>,Python 3 7 0 beta 3
@anchor{whatsnew/changelog id562}@anchor{1d22}
@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<60>,Windows<56>,Tests<56>,Python 3 7 0 beta 3
@anchor{whatsnew/changelog id563}@anchor{1d23}
@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<56>,macOS<44>,Build<60>,Python 3 7 0 beta 3
@anchor{whatsnew/changelog id564}@anchor{1d24}
@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<44>,IDLE<40>,Windows<56>,Python 3 7 0 beta 3
@anchor{whatsnew/changelog id565}@anchor{1d25}
@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<40>,Tools/Demos<38>,macOS<44>,Python 3 7 0 beta 3
@anchor{whatsnew/changelog id566}@anchor{1d26}
@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{1b8,,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<38>,C API<57>,IDLE<40>,Python 3 7 0 beta 3
@anchor{whatsnew/changelog id567}@anchor{1d27}
@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<57>,,Tools/Demos<38>,Python 3 7 0 beta 3
@anchor{whatsnew/changelog id568}@anchor{1d28}
@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{1d29}
@subsection Python 3.7.0 beta 2


`Release date: 2018-02-27'

@menu
* Security: Security<46>. 
* Core and Builtins: Core and Builtins<63>. 
* Library: Library<65>. 
* Documentation: Documentation<57>. 
* Tests: Tests<57>. 
* Build: Build<61>. 
* Windows: Windows<57>. 
* macOS: macOS<45>. 
* IDLE: IDLE<41>. 
* Tools/Demos: Tools/Demos<39>. 

@end menu

@node Security<46>,Core and Builtins<63>,,Python 3 7 0 beta 2
@anchor{whatsnew/changelog id569}@anchor{1d2a}
@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<63>,Library<65>,Security<46>,Python 3 7 0 beta 2
@anchor{whatsnew/changelog id570}@anchor{1d2b}
@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<65>,Documentation<57>,Core and Builtins<63>,Python 3 7 0 beta 2
@anchor{whatsnew/changelog id571}@anchor{1d2c}
@subsubsection Library



@itemize -

@item 
bpo-32960@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32960}: For dataclasses, disallow inheriting frozen from non-frozen
classes, and also disallow inheriting non-frozen from frozen classes. This
restriction will be relaxed at a future date.

@item 
bpo-32713@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32713}: Fixed tarfile.itn handling of out-of-bounds float values. Patch
by Joffrey Fuhrer.

@item 
bpo-32951@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32951}: Direct instantiation of SSLSocket and SSLObject objects is now
prohibited. The constructors were never documented, tested, or designed as
public constructors. Users were suppose to use ssl.wrap_socket() or
SSLContext.

@item 
bpo-32929@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32929}: Remove the tri-state parameter "hash", and add the boolean
"unsafe_hash". If unsafe_hash is True, add a __hash__ function, but if a
__hash__ exists, raise TypeError.  If unsafe_hash is False, add a __hash__
based on the values of eq= and frozen=.  The unsafe_hash=False behavior is
the same as the old hash=None behavior.  unsafe_hash=False is the default,
just as hash=None used to be.

@item 
bpo-32947@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32947}: Add OP_ENABLE_MIDDLEBOX_COMPAT and test workaround for TLSv1.3
for future compatibility with OpenSSL 1.1.1.

@item 
bpo-30622@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30622}: The ssl module now detects missing NPN support in LibreSSL.

@item 
bpo-32922@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32922}: dbm.open() now encodes filename with the filesystem encoding
rather than default encoding.

@item 
bpo-32859@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32859}: In @code{os.dup2}, don't check every call whether the @code{dup3}
syscall exists or not.

@item 
bpo-32556@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32556}: nt._getfinalpathname, nt._getvolumepathname and
nt._getdiskusage now correctly convert from bytes.

@item 
bpo-25988@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25988}: Emit a @ref{1a3,,DeprecationWarning} when using or importing an ABC
directly from @ref{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{17cd,,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{ff,,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<57>,Tests<57>,Library<65>,Python 3 7 0 beta 2
@anchor{whatsnew/changelog id572}@anchor{1d2d}
@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{ea,,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{5e8,,AttributeError}.

@item 
bpo-32614@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32614}: Modify RE examples in documentation to use raw strings to
prevent @ref{1a3,,DeprecationWarning} and add text to REGEX HOWTO to highlight
the deprecation.

@item 
bpo-31972@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31972}: Improve docstrings for @code{pathlib.PurePath} subclasses.
@end itemize

@node Tests<57>,Build<61>,Documentation<57>,Python 3 7 0 beta 2
@anchor{whatsnew/changelog id573}@anchor{1d2e}
@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<61>,Windows<57>,Tests<57>,Python 3 7 0 beta 2
@anchor{whatsnew/changelog id574}@anchor{1d2f}
@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<57>,macOS<45>,Build<61>,Python 3 7 0 beta 2
@anchor{whatsnew/changelog id575}@anchor{1d30}
@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{b11,,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<45>,IDLE<41>,Windows<57>,Python 3 7 0 beta 2
@anchor{whatsnew/changelog id576}@anchor{1d31}
@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<41>,Tools/Demos<39>,macOS<45>,Python 3 7 0 beta 2
@anchor{whatsnew/changelog id577}@anchor{1d32}
@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<39>,,IDLE<41>,Python 3 7 0 beta 2
@anchor{whatsnew/changelog id578}@anchor{1d33}
@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{1d34}
@subsection Python 3.7.0 beta 1


`Release date: 2018-01-30'

@menu
* Core and Builtins: Core and Builtins<64>. 
* Library: Library<66>. 
* Documentation: Documentation<58>. 
* Tests: Tests<58>. 
* Build: Build<62>. 
* Windows: Windows<58>. 
* macOS: macOS<46>. 
* C API: C API<58>. 

@end menu

@node Core and Builtins<64>,Library<66>,,Python 3 7 0 beta 1
@anchor{whatsnew/changelog id579}@anchor{1d35}
@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<66>,Documentation<58>,Core and Builtins<64>,Python 3 7 0 beta 1
@anchor{whatsnew/changelog id580}@anchor{1d36}
@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{e7,,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{16b5,,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{cfa,,asyncio.StreamWriter.wait_closed()} and
@ref{cfb,,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{70b,,datetime.datetime.fromtimestamp()} did not
call __new__ in @ref{4dd,,datetime.datetime} subclasses.

@item 
bpo-32403@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32403}: Improved speed of @ref{1fa,,datetime.date} and
@ref{4dd,,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{7f,,importlib.resources} and
@ref{cec,,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{ddd,,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{59b,,path-like object}. If `args' is given
as a sequence, it's first element can now be a @ref{59b,,path-like object} as
well.

@item 
bpo-31900@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31900}: The @ref{df3,,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{82c,,str.format()} method when formatting a number
(@ref{19b,,int}, @ref{196,,float}, @ref{196,,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<58>,Tests<58>,Library<66>,Python 3 7 0 beta 1
@anchor{whatsnew/changelog id581}@anchor{1d37}
@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<58>,Build<62>,Documentation<58>,Python 3 7 0 beta 1
@anchor{whatsnew/changelog id582}@anchor{1d38}
@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<62>,Windows<58>,Tests<58>,Python 3 7 0 beta 1
@anchor{whatsnew/changelog id583}@anchor{1d39}
@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{b8,,py_compile} will always create hash-based @code{.pyc} files.
@end itemize

@node Windows<58>,macOS<46>,Build<62>,Python 3 7 0 beta 1
@anchor{whatsnew/changelog id584}@anchor{1d3a}
@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<46>,C API<58>,Windows<58>,Python 3 7 0 beta 1
@anchor{whatsnew/changelog id585}@anchor{1d3b}
@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<58>,,macOS<46>,Python 3 7 0 beta 1
@anchor{whatsnew/changelog id586}@anchor{1d3c}
@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{1d3d}
@subsection Python 3.7.0 alpha 4


`Release date: 2018-01-08'

@menu
* Core and Builtins: Core and Builtins<65>. 
* Library: Library<67>. 
* Documentation: Documentation<59>. 
* Tests: Tests<59>. 
* Windows: Windows<59>. 
* Tools/Demos: Tools/Demos<40>. 
* C API: C API<59>. 

@end menu

@node Core and Builtins<65>,Library<67>,,Python 3 7 0 alpha 4
@anchor{whatsnew/changelog id587}@anchor{1d3e}
@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{1d3f,,-R} option now turns on hash randomization when
the 
@geindex PYTHONHASHSEED
@geindex 環境變數; PYTHONHASHSEED
@ref{1278,,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<67>,Documentation<59>,Core and Builtins<65>,Python 3 7 0 alpha 4
@anchor{whatsnew/changelog id588}@anchor{1d40}
@subsubsection Library



@itemize -

@item 
bpo-32506@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32506}: Now that dict is defined as keeping insertion order, drop
OrderedDict and just use plain dict.

@item 
bpo-32279@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32279}: Add params to dataclasses.make_dataclasses(): init, repr, eq,
order, hash, and frozen.  Pass them through to dataclass().

@item 
bpo-32278@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32278}: Make type information optional on dataclasses.make_dataclass().
If omitted, the string 'typing.Any' is used.

@item 
bpo-32499@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32499}: Add dataclasses.is_dataclass(obj), which returns True if obj is
a dataclass or an instance of one.

@item 
bpo-32468@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32468}: Improve frame repr() to mention filename, code name and current
line number.

@item 
bpo-23749@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23749}: asyncio: Implement loop.start_tls()

@item 
bpo-32441@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32441}: Return the new file descriptor (i.e., the second argument) from
@code{os.dup2}. Previously, @code{None} was always returned.

@item 
bpo-32422@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32422}: @code{functools.lru_cache} uses less memory (3 words for each
cached key) and takes about 1/3 time for cyclic GC.

@item 
bpo-31721@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31721}: Prevent Python crash from happening when Future._log_traceback
is set to True manually.  Now it can only be set to False, or a ValueError
is raised.

@item 
bpo-32415@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32415}: asyncio: Add Task.get_loop() and Future.get_loop()

@item 
bpo-26133@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26133}: Don't unsubscribe signals in asyncio UNIX event loop on
interpreter shutdown.

@item 
bpo-32363@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32363}: Make asyncio.Task.set_exception() and set_result() raise
NotImplementedError. Task._step() and Future.__await__() raise proper
exceptions when they are in an invalid state, instead of raising an
AssertionError.

@item 
bpo-32357@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32357}: Optimize asyncio.iscoroutine() and loop.create_task() for
non-native coroutines (e.g. async/await compiled with Cython).
'loop.create_task(python_coroutine)' used to be 20% faster than
'loop.create_task(cython_coroutine)'.  Now, the latter is as fast.

@item 
bpo-32356@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32356}: asyncio.transport.resume_reading() and pause_reading() are now
idempotent. New transport.is_reading() method is added.

@item 
bpo-32355@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32355}: Optimize asyncio.gather(); now up to 15% faster.

@item 
bpo-32351@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32351}: Use fastpath in asyncio.sleep if delay<0 (2x boost)

@item 
bpo-32348@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32348}: Optimize asyncio.Future schedule/add/remove callback.  The
optimization shows 3-6% performance improvements of async/await code.

@item 
bpo-32331@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32331}: Fix socket.settimeout() and socket.setblocking() to keep
socket.type as is. Fix socket.socket() constructor to reset any bit flags
applied to socket's type.  This change only affects OSes that have
SOCK_NONBLOCK and/or SOCK_CLOEXEC.

@item 
bpo-32248@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32248}: Add @ref{cec,,importlib.abc.ResourceReader} as an ABC for loaders
to provide a unified API for reading resources contained within packages.
Also add @ref{7f,,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{f35,,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{59d,,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{823,,datetime.datetime.fromisoformat()},
@ref{822,,datetime.time.fromisoformat()} and
@ref{821,,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{1d6,,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<59>,Tests<59>,Library<67>,Python 3 7 0 alpha 4
@anchor{whatsnew/changelog id589}@anchor{1d41}
@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<59>,Windows<59>,Documentation<59>,Python 3 7 0 alpha 4
@anchor{whatsnew/changelog id590}@anchor{1d42}
@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<59>,Tools/Demos<40>,Tests<59>,Python 3 7 0 alpha 4
@anchor{whatsnew/changelog id591}@anchor{1d43}
@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<40>,C API<59>,Windows<59>,Python 3 7 0 alpha 4
@anchor{whatsnew/changelog id592}@anchor{1d44}
@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<59>,,Tools/Demos<40>,Python 3 7 0 alpha 4
@anchor{whatsnew/changelog id593}@anchor{1d45}
@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{1d46}
@subsection Python 3.7.0 alpha 3


`Release date: 2017-12-05'

@menu
* Core and Builtins: Core and Builtins<66>. 
* Library: Library<68>. 
* Documentation: Documentation<60>. 
* Tests: Tests<60>. 
* Build: Build<63>. 
* Windows: Windows<60>. 
* macOS: macOS<47>. 
* IDLE: IDLE<42>. 
* Tools/Demos: Tools/Demos<41>. 
* C API: C API<60>. 

@end menu

@node Core and Builtins<66>,Library<68>,,Python 3 7 0 alpha 3
@anchor{whatsnew/changelog id594}@anchor{1d47}
@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<68>,Documentation<60>,Core and Builtins<66>,Python 3 7 0 alpha 3
@anchor{whatsnew/changelog id595}@anchor{1d48}
@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{1d49,,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{deb,,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{c00,,os.path.expanduser()} to find the @code{~/.netrc} file in
@ref{1b77,,netrc.netrc}.  If it does not exist, @ref{264,,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{4db,,collections.namedtuple()} in the
@ref{1d4a,,RobotFileParser.parse()}
method. Initial patch by Robin Wellner.

@item 
bpo-12382@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12382}: @code{msilib.OpenDatabase()} now raises a better exception
message when it couldn't open or create an MSI file.  Initial patch by
William Tisäter.

@item 
bpo-19610@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19610}: @code{setup()} now warns about invalid types for some fields. The
@code{distutils.dist.Distribution} class now warns when @code{classifiers},
@code{keywords} and @code{platforms} fields are not specified as a list or a
string.

@item 
bpo-32071@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32071}: Added the @code{-k} command-line option to @code{python -m unittest}
to run only tests that match the given pattern(s).

@item 
bpo-10049@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10049}: Added `nullcontext' no-op context manager to contextlib. This
provides a simpler and faster alternative to ExitStack() when handling
optional context managers.

@item 
bpo-28684@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28684}: The new test.support.skip_unless_bind_unix_socket() decorator
is used here to skip asyncio tests that fail because the platform lacks a
functional bind() function for unix domain sockets (as it is the case for
non root users on the recent Android versions that run now SELinux in
enforcing mode).

@item 
bpo-32110@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32110}: @code{codecs.StreamReader.read(n)} now returns not more than `n'
characters/bytes for non-negative `n'. This makes it compatible with
@code{read()} methods of other file-like objects.

@item 
bpo-27535@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27535}: The warnings module doesn't leak memory anymore in the hidden
warnings registry for the "ignore" action of warnings filters.
warn_explicit() function doesn't add the warning key to the registry
anymore for the "ignore" action.

@item 
bpo-32088@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32088}: warnings:  When Python is build is debug mode (@code{Py_DEBUG}),
@ref{1a3,,DeprecationWarning}, @ref{abd,,PendingDeprecationWarning} and
@ref{717,,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{59b,,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{1d4b,,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{d81,,time.CLOCK_BOOTTIME},
@ref{d83,,time.CLOCK_PROF} and @ref{d84,,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{1d4c,,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{50a,,ipaddress.IPv6Network} and @ref{509,,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{f4,,time} module:
@ref{cd2,,clock_gettime_ns()}, @ref{cd3,,clock_settime_ns()},
@ref{cd4,,monotonic_ns()}, @ref{cd5,,perf_counter_ns()},
@ref{cd6,,process_time_ns()}, @ref{cd7,,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{165d,,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{af3,,http.HTTPStatus}. Patch by Vitor Pereira.
@end itemize

@node Documentation<60>,Tests<60>,Library<68>,Python 3 7 0 alpha 3
@anchor{whatsnew/changelog id596}@anchor{1d4d}
@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<60>,Build<63>,Documentation<60>,Python 3 7 0 alpha 3
@anchor{whatsnew/changelog id597}@anchor{1d4e}
@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<63>,Windows<60>,Tests<60>,Python 3 7 0 alpha 3
@anchor{whatsnew/changelog id598}@anchor{1d4f}
@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<60>,macOS<47>,Build<63>,Python 3 7 0 alpha 3
@anchor{whatsnew/changelog id599}@anchor{1d50}
@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<47>,IDLE<42>,Windows<60>,Python 3 7 0 alpha 3
@anchor{whatsnew/changelog id600}@anchor{1d51}
@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<42>,Tools/Demos<41>,macOS<47>,Python 3 7 0 alpha 3
@anchor{whatsnew/changelog id601}@anchor{1d52}
@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<41>,C API<60>,IDLE<42>,Python 3 7 0 alpha 3
@anchor{whatsnew/changelog id602}@anchor{1d53}
@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<60>,,Tools/Demos<41>,Python 3 7 0 alpha 3
@anchor{whatsnew/changelog id603}@anchor{1d54}
@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{1d55}
@subsection Python 3.7.0 alpha 2


`Release date: 2017-10-16'

@menu
* Core and Builtins: Core and Builtins<67>. 
* Library: Library<69>. 
* Documentation: Documentation<61>. 
* Build: Build<64>. 
* IDLE: IDLE<43>. 
* C API: C API<61>. 

@end menu

@node Core and Builtins<67>,Library<69>,,Python 3 7 0 alpha 2
@anchor{whatsnew/changelog id604}@anchor{1d56}
@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{ce4,,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<69>,Documentation<61>,Core and Builtins<67>,Python 3 7 0 alpha 2
@anchor{whatsnew/changelog id605}@anchor{1d57}
@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{1d6,,concurrent.futures.ProcessPoolExecutor} constructor. Also, free
job resources in @ref{1d6,,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<61>,Build<64>,Library<69>,Python 3 7 0 alpha 2
@anchor{whatsnew/changelog id606}@anchor{1d58}
@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<64>,IDLE<43>,Documentation<61>,Python 3 7 0 alpha 2
@anchor{whatsnew/changelog id607}@anchor{1d59}
@subsubsection Build



@itemize -

@item 
bpo-31696@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31696}: Improve compiler version information in @ref{497,,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<43>,C API<61>,Build<64>,Python 3 7 0 alpha 2
@anchor{whatsnew/changelog id608}@anchor{1d5a}
@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<61>,,IDLE<43>,Python 3 7 0 alpha 2
@anchor{whatsnew/changelog id609}@anchor{1d5b}
@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{1d5c}
@subsection Python 3.7.0 alpha 1


`Release date: 2017-09-19'

@menu
* Security: Security<47>. 
* Core and Builtins: Core and Builtins<68>. 
* Library: Library<70>. 
* Documentation: Documentation<62>. 
* Tests: Tests<61>. 
* Build: Build<65>. 
* Windows: Windows<61>. 
* IDLE: IDLE<44>. 
* Tools/Demos: Tools/Demos<42>. 
* C API: C API<62>. 

@end menu

@node Security<47>,Core and Builtins<68>,,Python 3 7 0 alpha 1
@anchor{whatsnew/changelog id610}@anchor{1d5d}
@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<68>,Library<70>,Security<47>,Python 3 7 0 alpha 1
@anchor{whatsnew/changelog id611}@anchor{1d5e}
@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{a78,,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{16f2,,sys.setprofile()} function,
@ref{2b,,cProfile} or @ref{b4,,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<70>,Documentation<62>,Core and Builtins<68>,Python 3 7 0 alpha 1
@anchor{whatsnew/changelog id612}@anchor{1d5f}
@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{169,,str} instead of
@ref{192,,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<62>,Tests<61>,Library<70>,Python 3 7 0 alpha 1
@anchor{whatsnew/changelog id613}@anchor{1d60}
@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{192,,bytes()} and @ref{343,,bytearray()} are
now their respective type definitions, rather than the corresponding
builtin function entries. Use @ref{1d61,,bytes} and
@ref{1d62,,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<61>,Build<65>,Documentation<62>,Python 3 7 0 alpha 1
@anchor{whatsnew/changelog id614}@anchor{1d63}
@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<65>,Windows<61>,Tests<61>,Python 3 7 0 alpha 1
@anchor{whatsnew/changelog id615}@anchor{1d64}
@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<61>,IDLE<44>,Build<65>,Python 3 7 0 alpha 1
@anchor{whatsnew/changelog id616}@anchor{1d65}
@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<44>,Tools/Demos<42>,Windows<61>,Python 3 7 0 alpha 1
@anchor{whatsnew/changelog id617}@anchor{1d66}
@subsubsection IDLE



@itemize -

@item 
bpo-31493@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31493}: IDLE code context -- fix code update and font update timers.
Canceling timers prevents a warning message when test_idle completes.

@item 
bpo-31488@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31488}: IDLE - Update non-key options in former extension classes. When
applying configdialog changes, call .reload for each feature class. Change
ParenMatch so updated options affect existing instances attached to
existing editor windows.

@item 
bpo-31477@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31477}: IDLE - Improve rstrip entry in doc. Strip trailing whitespace
strips more than blank spaces.  Multiline string literals are not skipped.

@item 
bpo-31480@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31480}: IDLE - make tests pass with zzdummy extension disabled by
default.

@item 
bpo-31421@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31421}: Document how IDLE runs tkinter programs. IDLE calls tcl/tk
update in the background in order to make live interaction and
experimentation with tkinter applications much easier.

@item 
bpo-31414@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31414}: IDLE -- fix tk entry box tests by deleting first. Adding to an
int entry is not the same as deleting and inserting because int('@w{'}) will
fail.

@item 
bpo-31051@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31051}: Rearrange IDLE configdialog GenPage into Window, Editor, and
Help sections.

@item 
bpo-30617@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30617}: IDLE - Add docstrings and tests for outwin subclass of editor.
Move some data and functions from the class to module level. Patch by
Cheryl Sabella.

@item 
bpo-31287@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31287}: IDLE - Do not modify tkinter.message in test_configdialog.

@item 
bpo-27099@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27099}: Convert IDLE's built-in 'extensions' to regular features. About
10 IDLE features were implemented as supposedly optional extensions. Their
different behavior could be confusing or worse for users and not good for
maintenance. Hence the conversion. The main difference for users is that
user configurable key bindings for builtin features are now handled
uniformly. Now, editing a binding in a keyset only affects its value in
the keyset. All bindings are defined together in the system-specific
default keysets in config-extensions.def. All custom keysets are saved as
a whole in config-extension.cfg.  All take effect as soon as one clicks
Apply or Ok. The affected events are '<<force-open-completions>>',
'<<expand-word>>', '<<force-open-calltip>>', '<<flash-paren>>',
'<<format-paragraph>>', '<<run-module>>', '<<check-module>>', and
'<<zoom-height>>'.  Any (global) customizations made before 3.6.3 will not
affect their keyset-specific customization after 3.6.3. and vice versa.
Initial patch by Charles Wohlganger.

@item 
bpo-31206@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31206}: IDLE: Factor HighPage(Frame) class from ConfigDialog. Patch by
Cheryl Sabella.

@item 
bpo-31001@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31001}: Add tests for configdialog highlight tab.  Patch by Cheryl
Sabella.

@item 
bpo-31205@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31205}: IDLE: Factor KeysPage(Frame) class from ConfigDialog.  The
slightly modified tests continue to pass.  Patch by Cheryl Sabella.

@item 
bpo-31130@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31130}: IDLE -- stop leaks in test_configdialog. Initial patch by
Victor Stinner.

@item 
bpo-31002@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31002}: Add tests for configdialog keys tab. Patch by Cheryl Sabella.

@item 
bpo-19903@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19903}: IDLE: Calltips use @code{inspect.signature} instead of
@code{inspect.getfullargspec}. This improves calltips for builtins converted
to use Argument Clinic. Patch by Louie Lu.

@item 
bpo-31083@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31083}: IDLE - Add an outline of a TabPage class in configdialog.
Update existing classes to match outline. Initial patch by Cheryl Sabella.

@item 
bpo-31050@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31050}: Factor GenPage(Frame) class from ConfigDialog. The slightly
modified tests continue to pass. Patch by Cheryl Sabella.

@item 
bpo-31004@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31004}: IDLE - Factor FontPage(Frame) class from ConfigDialog. Slightly
modified tests continue to pass. Fix General tests. Patch mostly by Cheryl
Sabella.

@item 
bpo-30781@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30781}: IDLE - Use ttk widgets in ConfigDialog. Patches by Terry Jan
Reedy and Cheryl Sabella.

@item 
bpo-31060@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31060}: IDLE - Finish rearranging methods of ConfigDialog Grouping
methods pertaining to each tab and the buttons will aid writing tests and
improving the tabs and will enable splitting the groups into classes.

@item 
bpo-30853@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30853}: IDLE -- Factor a VarTrace class out of ConfigDialog. Instance
tracers manages pairs consisting of a tk variable and a callback function.
When tracing is turned on, setting the variable calls the function.  Test
coverage for the new class is 100%.

@item 
bpo-31003@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31003}: IDLE: Add more tests for General tab.

@item 
bpo-30993@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30993}: IDLE - Improve configdialog font page and tests. In
configdialog: Document causal pathways in create_font_tab docstring.
Simplify some attribute names. Move set_samples calls to var_changed_font
(idea from Cheryl Sabella).  Move related functions to positions after the
create widgets function. In test_configdialog: Fix test_font_set so not
order dependent.  Fix renamed test_indent_scale so it tests the widget.
Adjust tests for movement of set_samples call.  Add tests for load
functions.  Put all font tests in one class and tab indent tests in
another.  Except for two lines, these tests completely cover the related
functions.

@item 
bpo-30981@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30981}: IDLE -- Add more configdialog font page tests.

@item 
bpo-28523@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28523}: IDLE: replace 'colour' with 'color' in configdialog.

@item 
bpo-30917@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30917}: Add tests for idlelib.config.IdleConf. Increase coverage from
46% to 96%. Patch by Louie Lu.

@item 
bpo-30934@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30934}: Document coverage details for idlelib tests. Add section to
idlelib/idle-test/README.txt. Include check that branches are taken both
ways. Exclude IDLE-specific code that does not run during unit tests.

@item 
bpo-30913@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30913}: IDLE: Document ConfigDialog tk Vars, methods, and widgets in
docstrings This will facilitate improving the dialog and splitting up the
class. Original patch by Cheryl Sabella.

@item 
bpo-30899@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30899}: IDLE: Add tests for ConfigParser subclasses in config. Patch by
Louie Lu.

@item 
bpo-30881@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30881}: IDLE: Add docstrings to browser.py. Patch by Cheryl Sabella.

@item 
bpo-30851@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30851}: IDLE: Remove unused variables in configdialog.  One is a
duplicate, one is set but cannot be altered by users. Patch by Cheryl
Sabella.

@item 
bpo-30870@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30870}: IDLE: In Settings dialog, select font with Up, Down keys as
well as mouse. Initial patch by Louie Lu.

@item 
bpo-8231@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8231}: IDLE: call config.IdleConf.GetUserCfgDir only once.

@item 
bpo-30779@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30779}: IDLE: Factor ConfigChanges class from configdialog, put in
config; test. * In config, put dump test code in a function; run it and
unittest in   'if __name__ == '__main__'. * Add class config.ConfigChanges
based on changes_class_v4.py on bpo issue. * Add class
test_config.ChangesTest, partly using configdialog_tests_v1.py. * Revise
configdialog to use ConfigChanges; see tracker msg297804. * Revise
test_configdialog to match configdialog changes. * Remove configdialog
functions unused or moved to ConfigChanges. Cheryl Sabella contributed
parts of the patch.

@item 
bpo-30777@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30777}: IDLE: configdialog - Add docstrings and fix comments. Patch by
Cheryl Sabella.

@item 
bpo-30495@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30495}: IDLE: Improve textview with docstrings, PEP8 names, and more
tests. Patch by Cheryl Sabella.

@item 
bpo-30723@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30723}: IDLE: Make several improvements to parenmatch. Add 'parens'
style to highlight both opener and closer. Make 'default' style, which is
not default, a synonym for 'opener'. Make time-delay work the same with
all styles. Add help for config dialog extensions tab, including help for
parenmatch. Add new tests.  Original patch by Charles Wohlganger.

@item 
bpo-30674@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30674}: IDLE: add docstrings to grep module. Patch by Cheryl Sabella

@item 
bpo-21519@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21519}: IDLE's basic custom key entry dialog now detects duplicates
properly. Original patch by Saimadhav Heblikar.

@item 
bpo-29910@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29910}: IDLE no longer deletes a character after commenting out a
region by a key shortcut.  Add @code{return 'break'} for this and other
potential conflicts between IDLE and default key bindings.

@item 
bpo-30728@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30728}: Review and change idlelib.configdialog names. Lowercase method
and attribute names. Replace 'colour' with 'color', expand overly cryptic
names, delete unneeded underscores. Replace @code{import *} with specific
imports. Patches by Cheryl Sabella.

@item 
bpo-6739@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6739}: IDLE: Verify user-entered key sequences by trying to bind them
with tk. Add tests for all 3 validation functions. Original patch by G
Polo.  Tests added by Cheryl Sabella.

@item 
bpo-15786@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15786}: Fix several problems with IDLE's autocompletion box. The
following should now work: clicking on selection box items; using the
scrollbar; selecting an item by hitting Return. Hangs on MacOSX should no
longer happen. Patch by Louie Lu.

@item 
bpo-25514@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25514}: Add doc subsubsection about IDLE failure to start. Popup
no-connection message directs users to this section.

@item 
bpo-30642@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30642}: Fix reference leaks in IDLE tests. Patches by Louie Lu and
Terry Jan Reedy.

@item 
bpo-30495@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30495}: Add docstrings for textview.py and use PEP8 names. Patches by
Cheryl Sabella and Terry Jan Reedy.

@item 
bpo-30290@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30290}: Help-about: use pep8 names and add tests. Increase coverage to
100%. Patches by Louie Lu, Cheryl Sabella, and Terry Jan Reedy.

@item 
bpo-30303@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30303}: Add _utest option to textview; add new tests. Increase coverage
to 100%. Patches by Louie Lu and Terry Jan Reedy.

@item 
bpo-29071@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29071}: IDLE colors f-string prefixes (but not invalid ur prefixes).

@item 
bpo-28572@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28572}: Add 10% to coverage of IDLE's test_configdialog. Update and
augment description of the configuration system.
@end itemize

@node Tools/Demos<42>,C API<62>,IDLE<44>,Python 3 7 0 alpha 1
@anchor{whatsnew/changelog id618}@anchor{1d67}
@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<62>,,Tools/Demos<42>,Python 3 7 0 alpha 1
@anchor{whatsnew/changelog id619}@anchor{1d68}
@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{1d69}
@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{1d6a}
@subsection Python 3.6.6 release candidate 1


`Release date: 2018-06-11'

@menu
* Core and Builtins: Core and Builtins<69>. 
* Library: Library<71>. 
* Documentation: Documentation<63>. 
* Tests: Tests<62>. 
* Build: Build<66>. 
* Windows: Windows<62>. 
* macOS: macOS<48>. 
* IDLE: IDLE<45>. 
* Tools/Demos: Tools/Demos<43>. 
* C API: C API<63>. 

@end menu

@node Core and Builtins<69>,Library<71>,,Python 3 6 6 release candidate 1
@anchor{whatsnew/changelog id620}@anchor{1d6b}
@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{13c2,,gc.garbage} list. @ref{b7c,,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<71>,Documentation<63>,Core and Builtins<69>,Python 3 6 6 release candidate 1
@anchor{whatsnew/changelog id621}@anchor{1d6c}
@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{198,,TypeError} instead of @ref{78e,,SystemError} when
performed on @ref{514,,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{38,,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{1cec,,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{1cee,,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{84,,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{2e,,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<63>,Tests<62>,Library<71>,Python 3 6 6 release candidate 1
@anchor{whatsnew/changelog id622}@anchor{1d6d}
@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{136,,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<62>,Build<66>,Documentation<63>,Python 3 6 6 release candidate 1
@anchor{whatsnew/changelog id623}@anchor{1d6e}
@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<66>,Windows<62>,Tests<62>,Python 3 6 6 release candidate 1
@anchor{whatsnew/changelog id624}@anchor{1d6f}
@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<62>,macOS<48>,Build<66>,Python 3 6 6 release candidate 1
@anchor{whatsnew/changelog id625}@anchor{1d70}
@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<48>,IDLE<45>,Windows<62>,Python 3 6 6 release candidate 1
@anchor{whatsnew/changelog id626}@anchor{1d71}
@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<45>,Tools/Demos<43>,macOS<48>,Python 3 6 6 release candidate 1
@anchor{whatsnew/changelog id627}@anchor{1d72}
@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<43>,C API<63>,IDLE<45>,Python 3 6 6 release candidate 1
@anchor{whatsnew/changelog id628}@anchor{1d73}
@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<63>,,Tools/Demos<43>,Python 3 6 6 release candidate 1
@anchor{whatsnew/changelog id629}@anchor{1d74}
@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{1d75}
@subsection Python 3.6.5 final


`Release date: 2018-03-28'

@menu
* Tests: Tests<63>. 
* Build: Build<67>. 

@end menu

@node Tests<63>,Build<67>,,Python 3 6 5 final
@anchor{whatsnew/changelog id630}@anchor{1d76}
@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<67>,,Tests<63>,Python 3 6 5 final
@anchor{whatsnew/changelog id631}@anchor{1d77}
@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{1d78}
@subsection Python 3.6.5 release candidate 1


`Release date: 2018-03-13'

@menu
* Security: Security<48>. 
* Core and Builtins: Core and Builtins<70>. 
* Library: Library<72>. 
* Documentation: Documentation<64>. 
* Tests: Tests<64>. 
* Build: Build<68>. 
* Windows: Windows<63>. 
* macOS: macOS<49>. 
* IDLE: IDLE<46>. 
* Tools/Demos: Tools/Demos<44>. 
* C API: C API<64>. 

@end menu

@node Security<48>,Core and Builtins<70>,,Python 3 6 5 release candidate 1
@anchor{whatsnew/changelog id632}@anchor{1d79}
@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<70>,Library<72>,Security<48>,Python 3 6 5 release candidate 1
@anchor{whatsnew/changelog id633}@anchor{1d7a}
@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<72>,Documentation<64>,Core and Builtins<70>,Python 3 6 5 release candidate 1
@anchor{whatsnew/changelog id634}@anchor{1d7b}
@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{f6,,tkinter}, @code{after_cancel(None)} now raises a
@ref{2eb,,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{f35,,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{df3,,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{82c,,str.format()} method when formatting a number
(@ref{19b,,int}, @ref{196,,float}, @ref{196,,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<64>,Tests<64>,Library<72>,Python 3 6 5 release candidate 1
@anchor{whatsnew/changelog id635}@anchor{1d7c}
@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{5e8,,AttributeError}.

@item 
bpo-32614@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32614}: Modify RE examples in documentation to use raw strings to
prevent @ref{1a3,,DeprecationWarning} and add text to REGEX HOWTO to highlight
the deprecation.

@item 
bpo-31972@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31972}: Improve docstrings for @code{pathlib.PurePath} subclasses.

@item 
bpo-17799@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17799}: Explain real behaviour of sys.settrace and sys.setprofile and
their C-API counterparts regarding which type of events are received in
each function. Patch by Pablo Galindo Salgado.
@end itemize

@node Tests<64>,Build<68>,Documentation<64>,Python 3 6 5 release candidate 1
@anchor{whatsnew/changelog id636}@anchor{1d7d}
@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<68>,Windows<63>,Tests<64>,Python 3 6 5 release candidate 1
@anchor{whatsnew/changelog id637}@anchor{1d7e}
@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<63>,macOS<49>,Build<68>,Python 3 6 5 release candidate 1
@anchor{whatsnew/changelog id638}@anchor{1d7f}
@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{b11,,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<49>,IDLE<46>,Windows<63>,Python 3 6 5 release candidate 1
@anchor{whatsnew/changelog id639}@anchor{1d80}
@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<46>,Tools/Demos<44>,macOS<49>,Python 3 6 5 release candidate 1
@anchor{whatsnew/changelog id640}@anchor{1d81}
@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{1b8,,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<44>,C API<64>,IDLE<46>,Python 3 6 5 release candidate 1
@anchor{whatsnew/changelog id641}@anchor{1d82}
@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<64>,,Tools/Demos<44>,Python 3 6 5 release candidate 1
@anchor{whatsnew/changelog id642}@anchor{1d83}
@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{1d84}
@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{1d85}
@subsection Python 3.6.4 release candidate 1


`Release date: 2017-12-05'

@menu
* Core and Builtins: Core and Builtins<71>. 
* Library: Library<73>. 
* Documentation: Documentation<65>. 
* Tests: Tests<65>. 
* Build: Build<69>. 
* Windows: Windows<64>. 
* macOS: macOS<50>. 
* IDLE: IDLE<47>. 
* Tools/Demos: Tools/Demos<45>. 
* C API: C API<65>. 

@end menu

@node Core and Builtins<71>,Library<73>,,Python 3 6 4 release candidate 1
@anchor{whatsnew/changelog id643}@anchor{1d86}
@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<73>,Documentation<65>,Core and Builtins<71>,Python 3 6 4 release candidate 1
@anchor{whatsnew/changelog id644}@anchor{1d87}
@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{4db,,collections.namedtuple()} in the
@ref{1d4a,,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<65>,Tests<65>,Library<73>,Python 3 6 4 release candidate 1
@anchor{whatsnew/changelog id645}@anchor{1d88}
@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<65>,Build<69>,Documentation<65>,Python 3 6 4 release candidate 1
@anchor{whatsnew/changelog id646}@anchor{1d89}
@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<69>,Windows<64>,Tests<65>,Python 3 6 4 release candidate 1
@anchor{whatsnew/changelog id647}@anchor{1d8a}
@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<64>,macOS<50>,Build<69>,Python 3 6 4 release candidate 1
@anchor{whatsnew/changelog id648}@anchor{1d8b}
@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<50>,IDLE<47>,Windows<64>,Python 3 6 4 release candidate 1
@anchor{whatsnew/changelog id649}@anchor{1d8c}
@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<47>,Tools/Demos<45>,macOS<50>,Python 3 6 4 release candidate 1
@anchor{whatsnew/changelog id650}@anchor{1d8d}
@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<45>,C API<65>,IDLE<47>,Python 3 6 4 release candidate 1
@anchor{whatsnew/changelog id651}@anchor{1d8e}
@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<65>,,Tools/Demos<45>,Python 3 6 4 release candidate 1
@anchor{whatsnew/changelog id652}@anchor{1d8f}
@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{1d90}
@subsection Python 3.6.3 final


`Release date: 2017-10-03'

@menu
* Library: Library<74>. 
* Build: Build<70>. 

@end menu

@node Library<74>,Build<70>,,Python 3 6 3 final
@anchor{whatsnew/changelog id653}@anchor{1d91}
@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<70>,,Library<74>,Python 3 6 3 final
@anchor{whatsnew/changelog id654}@anchor{1d92}
@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{1d93}
@subsection Python 3.6.3 release candidate 1


`Release date: 2017-09-18'

@menu
* Security: Security<49>. 
* Core and Builtins: Core and Builtins<72>. 
* Library: Library<75>. 
* Documentation: Documentation<66>. 
* Tests: Tests<66>. 
* Build: Build<71>. 
* Windows: Windows<65>. 
* IDLE: IDLE<48>. 
* Tools/Demos: Tools/Demos<46>. 

@end menu

@node Security<49>,Core and Builtins<72>,,Python 3 6 3 release candidate 1
@anchor{whatsnew/changelog id655}@anchor{1d94}
@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<72>,Library<75>,Security<49>,Python 3 6 3 release candidate 1
@anchor{whatsnew/changelog id656}@anchor{1d95}
@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<75>,Documentation<66>,Core and Builtins<72>,Python 3 6 3 release candidate 1
@anchor{whatsnew/changelog id657}@anchor{1d96}
@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<66>,Tests<66>,Library<75>,Python 3 6 3 release candidate 1
@anchor{whatsnew/changelog id658}@anchor{1d97}
@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<66>,Build<71>,Documentation<66>,Python 3 6 3 release candidate 1
@anchor{whatsnew/changelog id659}@anchor{1d98}
@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<71>,Windows<65>,Tests<66>,Python 3 6 3 release candidate 1
@anchor{whatsnew/changelog id660}@anchor{1d99}
@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<65>,IDLE<48>,Build<71>,Python 3 6 3 release candidate 1
@anchor{whatsnew/changelog id661}@anchor{1d9a}
@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<48>,Tools/Demos<46>,Windows<65>,Python 3 6 3 release candidate 1
@anchor{whatsnew/changelog id662}@anchor{1d9b}
@subsubsection IDLE



@itemize -

@item 
bpo-31493@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31493}: IDLE code context -- fix code update and font update timers.
Canceling timers prevents a warning message when test_idle completes.

@item 
bpo-31488@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31488}: IDLE - Update non-key options in former extension classes. When
applying configdialog changes, call .reload for each feature class. Change
ParenMatch so updated options affect existing instances attached to
existing editor windows.

@item 
bpo-31477@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31477}: IDLE - Improve rstrip entry in doc. Strip trailing whitespace
strips more than blank spaces.  Multiline string literals are not skipped.

@item 
bpo-31480@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31480}: IDLE - make tests pass with zzdummy extension disabled by
default.

@item 
bpo-31421@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31421}: Document how IDLE runs tkinter programs. IDLE calls tcl/tk
update in the background in order to make live interaction and
experimentation with tkinter applications much easier.

@item 
bpo-31414@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31414}: IDLE -- fix tk entry box tests by deleting first. Adding to an
int entry is not the same as deleting and inserting because int('@w{'}) will
fail.

@item 
bpo-31051@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31051}: Rearrange IDLE configdialog GenPage into Window, Editor, and
Help sections.

@item 
bpo-30617@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30617}: IDLE - Add docstrings and tests for outwin subclass of editor.
Move some data and functions from the class to module level. Patch by
Cheryl Sabella.

@item 
bpo-31287@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31287}: IDLE - Do not modify tkinter.message in test_configdialog.

@item 
bpo-27099@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27099}: Convert IDLE's built-in 'extensions' to regular features. About
10 IDLE features were implemented as supposedly optional extensions. Their
different behavior could be confusing or worse for users and not good for
maintenance. Hence the conversion. The main difference for users is that
user configurable key bindings for builtin features are now handled
uniformly. Now, editing a binding in a keyset only affects its value in
the keyset. All bindings are defined together in the system-specific
default keysets in config-extensions.def. All custom keysets are saved as
a whole in config-extension.cfg.  All take effect as soon as one clicks
Apply or Ok. The affected events are '<<force-open-completions>>',
'<<expand-word>>', '<<force-open-calltip>>', '<<flash-paren>>',
'<<format-paragraph>>', '<<run-module>>', '<<check-module>>', and
'<<zoom-height>>'.  Any (global) customizations made before 3.6.3 will not
affect their keyset-specific customization after 3.6.3. and vice versa.
Initial patch by Charles Wohlganger.

@item 
bpo-31206@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31206}: IDLE: Factor HighPage(Frame) class from ConfigDialog. Patch by
Cheryl Sabella.

@item 
bpo-31001@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31001}: Add tests for configdialog highlight tab.  Patch by Cheryl
Sabella.

@item 
bpo-31205@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31205}: IDLE: Factor KeysPage(Frame) class from ConfigDialog.  The
slightly modified tests continue to pass.  Patch by Cheryl Sabella.

@item 
bpo-31130@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31130}: IDLE -- stop leaks in test_configdialog. Initial patch by
Victor Stinner.

@item 
bpo-31002@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31002}: Add tests for configdialog keys tab. Patch by Cheryl Sabella.

@item 
bpo-19903@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19903}: IDLE: Calltips use @code{inspect.signature} instead of
@code{inspect.getfullargspec}. This improves calltips for builtins converted
to use Argument Clinic. Patch by Louie Lu.

@item 
bpo-31083@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31083}: IDLE - Add an outline of a TabPage class in configdialog.
Update existing classes to match outline. Initial patch by Cheryl Sabella.

@item 
bpo-31050@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31050}: Factor GenPage(Frame) class from ConfigDialog. The slightly
modified tests continue to pass. Patch by Cheryl Sabella.

@item 
bpo-31004@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31004}: IDLE - Factor FontPage(Frame) class from ConfigDialog. Slightly
modified tests continue to pass. Fix General tests. Patch mostly by Cheryl
Sabella.

@item 
bpo-30781@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30781}: IDLE - Use ttk widgets in ConfigDialog. Patches by Terry Jan
Reedy and Cheryl Sabella.

@item 
bpo-31060@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31060}: IDLE - Finish rearranging methods of ConfigDialog Grouping
methods pertaining to each tab and the buttons will aid writing tests and
improving the tabs and will enable splitting the groups into classes.

@item 
bpo-30853@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30853}: IDLE -- Factor a VarTrace class out of ConfigDialog. Instance
tracers manages pairs consisting of a tk variable and a callback function.
When tracing is turned on, setting the variable calls the function.  Test
coverage for the new class is 100%.

@item 
bpo-31003@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31003}: IDLE: Add more tests for General tab.

@item 
bpo-30993@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30993}: IDLE - Improve configdialog font page and tests. In
configdialog: Document causal pathways in create_font_tab docstring.
Simplify some attribute names. Move set_samples calls to var_changed_font
(idea from Cheryl Sabella).  Move related functions to positions after the
create widgets function. In test_configdialog: Fix test_font_set so not
order dependent.  Fix renamed test_indent_scale so it tests the widget.
Adjust tests for movement of set_samples call.  Add tests for load
functions.  Put all font tests in one class and tab indent tests in
another.  Except for two lines, these tests completely cover the related
functions.

@item 
bpo-30981@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30981}: IDLE -- Add more configdialog font page tests.

@item 
bpo-28523@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28523}: IDLE: replace 'colour' with 'color' in configdialog.

@item 
bpo-30917@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30917}: Add tests for idlelib.config.IdleConf. Increase coverage from
46% to 96%. Patch by Louie Lu.

@item 
bpo-30934@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30934}: Document coverage details for idlelib tests. Add section to
idlelib/idle-test/README.txt. Include check that branches are taken both
ways. Exclude IDLE-specific code that does not run during unit tests.

@item 
bpo-30913@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30913}: IDLE: Document ConfigDialog tk Vars, methods, and widgets in
docstrings This will facilitate improving the dialog and splitting up the
class. Original patch by Cheryl Sabella.

@item 
bpo-30899@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30899}: IDLE: Add tests for ConfigParser subclasses in config. Patch by
Louie Lu.

@item 
bpo-30881@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30881}: IDLE: Add docstrings to browser.py. Patch by Cheryl Sabella.

@item 
bpo-30851@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30851}: IDLE: Remove unused variables in configdialog.  One is a
duplicate, one is set but cannot be altered by users. Patch by Cheryl
Sabella.

@item 
bpo-30870@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30870}: IDLE: In Settings dialog, select font with Up, Down keys as
well as mouse. Initial patch by Louie Lu.

@item 
bpo-8231@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8231}: IDLE: call config.IdleConf.GetUserCfgDir only once.

@item 
bpo-30779@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30779}: IDLE: Factor ConfigChanges class from configdialog, put in
config; test. * In config, put dump test code in a function; run it and
unittest in   'if __name__ == '__main__'. * Add class config.ConfigChanges
based on changes_class_v4.py on bpo issue. * Add class
test_config.ChangesTest, partly using configdialog_tests_v1.py. * Revise
configdialog to use ConfigChanges; see tracker msg297804. * Revise
test_configdialog to match configdialog changes. * Remove configdialog
functions unused or moved to ConfigChanges. Cheryl Sabella contributed
parts of the patch.

@item 
bpo-30777@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30777}: IDLE: configdialog - Add docstrings and fix comments. Patch by
Cheryl Sabella.

@item 
bpo-30495@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30495}: IDLE: Improve textview with docstrings, PEP8 names, and more
tests. Patch by Cheryl Sabella.

@item 
bpo-30723@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30723}: IDLE: Make several improvements to parenmatch. Add 'parens'
style to highlight both opener and closer. Make 'default' style, which is
not default, a synonym for 'opener'. Make time-delay work the same with
all styles. Add help for config dialog extensions tab, including help for
parenmatch. Add new tests.  Original patch by Charles Wohlganger.

@item 
bpo-30674@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30674}: IDLE: add docstrings to grep module. Patch by Cheryl Sabella

@item 
bpo-21519@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21519}: IDLE's basic custom key entry dialog now detects duplicates
properly. Original patch by Saimadhav Heblikar.

@item 
bpo-29910@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29910}: IDLE no longer deletes a character after commenting out a
region by a key shortcut.  Add @code{return 'break'} for this and other
potential conflicts between IDLE and default key bindings.

@item 
bpo-30728@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30728}: Review and change idlelib.configdialog names. Lowercase method
and attribute names. Replace 'colour' with 'color', expand overly cryptic
names, delete unneeded underscores. Replace @code{import *} with specific
imports. Patches by Cheryl Sabella.

@item 
bpo-6739@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6739}: IDLE: Verify user-entered key sequences by trying to bind them
with tk. Add tests for all 3 validation functions. Original patch by G
Polo.  Tests added by Cheryl Sabella.
@end itemize

@node Tools/Demos<46>,,IDLE<48>,Python 3 6 3 release candidate 1
@anchor{whatsnew/changelog id663}@anchor{1d9c}
@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{1d9d}
@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{1d9e}
@subsection Python 3.6.2 release candidate 2


`Release date: 2017-07-07'

@menu
* Security: Security<50>. 

@end menu

@node Security<50>,,,Python 3 6 2 release candidate 2
@anchor{whatsnew/changelog id664}@anchor{1d9f}
@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{1da0}
@subsection Python 3.6.2 release candidate 1


`Release date: 2017-06-17'

@menu
* Security: Security<51>. 
* Core and Builtins: Core and Builtins<73>. 
* Library: Library<76>. 
* IDLE: IDLE<49>. 
* C API: C API<66>. 
* Build: Build<72>. 
* Documentation: Documentation<67>. 
* Tools/Demos: Tools/Demos<47>. 
* Tests: Tests<67>. 
* Windows: Windows<66>. 

@end menu

@node Security<51>,Core and Builtins<73>,,Python 3 6 2 release candidate 1
@anchor{whatsnew/changelog id665}@anchor{1da1}
@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<73>,Library<76>,Security<51>,Python 3 6 2 release candidate 1
@anchor{whatsnew/changelog id666}@anchor{1da2}
@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{a78,,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<76>,IDLE<49>,Core and Builtins<73>,Python 3 6 2 release candidate 1
@anchor{whatsnew/changelog id667}@anchor{1da3}
@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<49>,C API<66>,Library<76>,Python 3 6 2 release candidate 1
@anchor{whatsnew/changelog id668}@anchor{1da4}
@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<66>,Build<72>,IDLE<49>,Python 3 6 2 release candidate 1
@anchor{whatsnew/changelog id669}@anchor{1da5}
@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<72>,Documentation<67>,C API<66>,Python 3 6 2 release candidate 1
@anchor{whatsnew/changelog id670}@anchor{1da6}
@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<67>,Tools/Demos<47>,Build<72>,Python 3 6 2 release candidate 1
@anchor{whatsnew/changelog id671}@anchor{1da7}
@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{192,,bytes()} and @ref{343,,bytearray()} are
now their respective type definitions, rather than the corresponding
builtin function entries. Use @ref{1d61,,bytes} and
@ref{1d62,,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<47>,Tests<67>,Documentation<67>,Python 3 6 2 release candidate 1
@anchor{whatsnew/changelog id672}@anchor{1da8}
@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<67>,Windows<66>,Tools/Demos<47>,Python 3 6 2 release candidate 1
@anchor{whatsnew/changelog id673}@anchor{1da9}
@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<66>,,Tests<67>,Python 3 6 2 release candidate 1
@anchor{whatsnew/changelog id674}@anchor{1daa}
@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{1dab}
@subsection Python 3.6.1 final


`Release date: 2017-03-21'

@menu
* Core and Builtins: Core and Builtins<74>. 
* Build: Build<73>. 

@end menu

@node Core and Builtins<74>,Build<73>,,Python 3 6 1 final
@anchor{whatsnew/changelog id675}@anchor{1dac}
@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<73>,,Core and Builtins<74>,Python 3 6 1 final
@anchor{whatsnew/changelog id676}@anchor{1dad}
@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{1dae}
@subsection Python 3.6.1 release candidate 1


`Release date: 2017-03-04'

@menu
* Core and Builtins: Core and Builtins<75>. 
* Library: Library<77>. 
* IDLE: IDLE<50>. 
* Windows: Windows<67>. 
* C API: C API<67>. 
* Documentation: Documentation<68>. 
* Tests: Tests<68>. 
* Build: Build<74>. 

@end menu

@node Core and Builtins<75>,Library<77>,,Python 3 6 1 release candidate 1
@anchor{whatsnew/changelog id677}@anchor{1daf}
@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<77>,IDLE<50>,Core and Builtins<75>,Python 3 6 1 release candidate 1
@anchor{whatsnew/changelog id678}@anchor{1db0}
@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<50>,Windows<67>,Library<77>,Python 3 6 1 release candidate 1
@anchor{whatsnew/changelog id679}@anchor{1db1}
@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<67>,C API<67>,IDLE<50>,Python 3 6 1 release candidate 1
@anchor{whatsnew/changelog id680}@anchor{1db2}
@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<67>,Documentation<68>,Windows<67>,Python 3 6 1 release candidate 1
@anchor{whatsnew/changelog id681}@anchor{1db3}
@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<68>,Tests<68>,C API<67>,Python 3 6 1 release candidate 1
@anchor{whatsnew/changelog id682}@anchor{1db4}
@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<68>,Build<74>,Documentation<68>,Python 3 6 1 release candidate 1
@anchor{whatsnew/changelog id683}@anchor{1db5}
@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<74>,,Tests<68>,Python 3 6 1 release candidate 1
@anchor{whatsnew/changelog id684}@anchor{1db6}
@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{1db7}
@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{1db8}
@subsection Python 3.6.0 release candidate 2


`Release date: 2016-12-16'

@menu
* Core and Builtins: Core and Builtins<76>. 
* Tools/Demos: Tools/Demos<48>. 
* Windows: Windows<68>. 
* Build: Build<75>. 

@end menu

@node Core and Builtins<76>,Tools/Demos<48>,,Python 3 6 0 release candidate 2
@anchor{whatsnew/changelog id685}@anchor{1db9}
@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<48>,Windows<68>,Core and Builtins<76>,Python 3 6 0 release candidate 2
@anchor{whatsnew/changelog id686}@anchor{1dba}
@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<68>,Build<75>,Tools/Demos<48>,Python 3 6 0 release candidate 2
@anchor{whatsnew/changelog id687}@anchor{1dbb}
@subsubsection Windows



@itemize -

@item 
bpo-28896@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28896}: Deprecate WindowsRegistryFinder.
@end itemize

@node Build<75>,,Windows<68>,Python 3 6 0 release candidate 2
@anchor{whatsnew/changelog id688}@anchor{1dbc}
@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{1dbd}
@subsection Python 3.6.0 release candidate 1


`Release date: 2016-12-06'

@menu
* Core and Builtins: Core and Builtins<77>. 
* Library: Library<78>. 
* C API: C API<68>. 
* Documentation: Documentation<69>. 
* Tools/Demos: Tools/Demos<49>. 

@end menu

@node Core and Builtins<77>,Library<78>,,Python 3 6 0 release candidate 1
@anchor{whatsnew/changelog id689}@anchor{1dbe}
@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<78>,C API<68>,Core and Builtins<77>,Python 3 6 0 release candidate 1
@anchor{whatsnew/changelog id690}@anchor{1dbf}
@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<68>,Documentation<69>,Library<78>,Python 3 6 0 release candidate 1
@anchor{whatsnew/changelog id691}@anchor{1dc0}
@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<69>,Tools/Demos<49>,C API<68>,Python 3 6 0 release candidate 1
@anchor{whatsnew/changelog id692}@anchor{1dc1}
@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<49>,,Documentation<69>,Python 3 6 0 release candidate 1
@anchor{whatsnew/changelog id693}@anchor{1dc2}
@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{1dc3}
@subsection Python 3.6.0 beta 4


`Release date: 2016-11-21'

@menu
* Core and Builtins: Core and Builtins<78>. 
* Library: Library<79>. 
* Documentation: Documentation<70>. 
* Tests: Tests<69>. 
* Build: Build<76>. 

@end menu

@node Core and Builtins<78>,Library<79>,,Python 3 6 0 beta 4
@anchor{whatsnew/changelog id694}@anchor{1dc4}
@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<79>,Documentation<70>,Core and Builtins<78>,Python 3 6 0 beta 4
@anchor{whatsnew/changelog id695}@anchor{1dc5}
@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<70>,Tests<69>,Library<79>,Python 3 6 0 beta 4
@anchor{whatsnew/changelog id696}@anchor{1dc6}
@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<69>,Build<76>,Documentation<70>,Python 3 6 0 beta 4
@anchor{whatsnew/changelog id697}@anchor{1dc7}
@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<76>,,Tests<69>,Python 3 6 0 beta 4
@anchor{whatsnew/changelog id698}@anchor{1dc8}
@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{1dc9}
@subsection Python 3.6.0 beta 3


`Release date: 2016-10-31'

@menu
* Core and Builtins: Core and Builtins<79>. 
* Library: Library<80>. 
* Windows: Windows<69>. 
* Build: Build<77>. 
* Tests: Tests<70>. 

@end menu

@node Core and Builtins<79>,Library<80>,,Python 3 6 0 beta 3
@anchor{whatsnew/changelog id699}@anchor{1dca}
@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<80>,Windows<69>,Core and Builtins<79>,Python 3 6 0 beta 3
@anchor{whatsnew/changelog id700}@anchor{1dcb}
@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<69>,Build<77>,Library<80>,Python 3 6 0 beta 3
@anchor{whatsnew/changelog id701}@anchor{1dcc}
@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<77>,Tests<70>,Windows<69>,Python 3 6 0 beta 3
@anchor{whatsnew/changelog id702}@anchor{1dcd}
@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<70>,,Build<77>,Python 3 6 0 beta 3
@anchor{whatsnew/changelog id703}@anchor{1dce}
@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{1dcf}
@subsection Python 3.6.0 beta 2


`Release date: 2016-10-10'

@menu
* Core and Builtins: Core and Builtins<80>. 
* Library: Library<81>. 
* Windows: Windows<70>. 
* C API: C API<69>. 
* Build: Build<78>. 
* Tests: Tests<71>. 

@end menu

@node Core and Builtins<80>,Library<81>,,Python 3 6 0 beta 2
@anchor{whatsnew/changelog id704}@anchor{1dd0}
@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<81>,Windows<70>,Core and Builtins<80>,Python 3 6 0 beta 2
@anchor{whatsnew/changelog id705}@anchor{1dd1}
@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<70>,C API<69>,Library<81>,Python 3 6 0 beta 2
@anchor{whatsnew/changelog id706}@anchor{1dd2}
@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<69>,Build<78>,Windows<70>,Python 3 6 0 beta 2
@anchor{whatsnew/changelog id707}@anchor{1dd3}
@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<78>,Tests<71>,C API<69>,Python 3 6 0 beta 2
@anchor{whatsnew/changelog id708}@anchor{1dd4}
@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<71>,,Build<78>,Python 3 6 0 beta 2
@anchor{whatsnew/changelog id709}@anchor{1dd5}
@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{1dd6}
@subsection Python 3.6.0 beta 1


`Release date: 2016-09-12'

@menu
* Core and Builtins: Core and Builtins<81>. 
* Library: Library<82>. 
* IDLE: IDLE<51>. 
* C API: C API<70>. 
* Tests: Tests<72>. 
* Build: Build<79>. 
* Tools/Demos: Tools/Demos<50>. 
* Windows: Windows<71>. 

@end menu

@node Core and Builtins<81>,Library<82>,,Python 3 6 0 beta 1
@anchor{whatsnew/changelog id710}@anchor{1dd7}
@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<82>,IDLE<51>,Core and Builtins<81>,Python 3 6 0 beta 1
@anchor{whatsnew/changelog id711}@anchor{1dd8}
@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{73f,,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{eb4,,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<51>,C API<70>,Library<82>,Python 3 6 0 beta 1
@anchor{whatsnew/changelog id712}@anchor{1dd9}
@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<70>,Tests<72>,IDLE<51>,Python 3 6 0 beta 1
@anchor{whatsnew/changelog id713}@anchor{1dda}
@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<72>,Build<79>,C API<70>,Python 3 6 0 beta 1
@anchor{whatsnew/changelog id714}@anchor{1ddb}
@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<79>,Tools/Demos<50>,Tests<72>,Python 3 6 0 beta 1
@anchor{whatsnew/changelog id715}@anchor{1ddc}
@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<50>,Windows<71>,Build<79>,Python 3 6 0 beta 1
@anchor{whatsnew/changelog id716}@anchor{1ddd}
@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<71>,,Tools/Demos<50>,Python 3 6 0 beta 1
@anchor{whatsnew/changelog id717}@anchor{1dde}
@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{1ddf}
@subsection Python 3.6.0 alpha 4


`Release date: 2016-08-15'

@menu
* Core and Builtins: Core and Builtins<82>. 
* Library: Library<83>. 
* IDLE: IDLE<52>. 
* Tests: Tests<73>. 
* Windows: Windows<72>. 
* Build: Build<80>. 

@end menu

@node Core and Builtins<82>,Library<83>,,Python 3 6 0 alpha 4
@anchor{whatsnew/changelog id718}@anchor{1de0}
@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<83>,IDLE<52>,Core and Builtins<82>,Python 3 6 0 alpha 4
@anchor{whatsnew/changelog id719}@anchor{1de1}
@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<52>,Tests<73>,Library<83>,Python 3 6 0 alpha 4
@anchor{whatsnew/changelog id720}@anchor{1de2}
@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<73>,Windows<72>,IDLE<52>,Python 3 6 0 alpha 4
@anchor{whatsnew/changelog id721}@anchor{1de3}
@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<72>,Build<80>,Tests<73>,Python 3 6 0 alpha 4
@anchor{whatsnew/changelog id722}@anchor{1de4}
@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<80>,,Windows<72>,Python 3 6 0 alpha 4
@anchor{whatsnew/changelog id723}@anchor{1de5}
@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{1de6}
@subsection Python 3.6.0 alpha 3


`Release date: 2016-07-11'

@menu
* Security: Security<52>. 
* Core and Builtins: Core and Builtins<83>. 
* Library: Library<84>. 
* IDLE: IDLE<53>. 
* C API: C API<71>. 
* Build: Build<81>. 
* Tools/Demos: Tools/Demos<51>. 
* Documentation: Documentation<71>. 
* Tests: Tests<74>. 

@end menu

@node Security<52>,Core and Builtins<83>,,Python 3 6 0 alpha 3
@anchor{whatsnew/changelog id724}@anchor{1de7}
@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<83>,Library<84>,Security<52>,Python 3 6 0 alpha 3
@anchor{whatsnew/changelog id725}@anchor{1de8}
@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<84>,IDLE<53>,Core and Builtins<83>,Python 3 6 0 alpha 3
@anchor{whatsnew/changelog id726}@anchor{1de9}
@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<53>,C API<71>,Library<84>,Python 3 6 0 alpha 3
@anchor{whatsnew/changelog id727}@anchor{1dea}
@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<71>,Build<81>,IDLE<53>,Python 3 6 0 alpha 3
@anchor{whatsnew/changelog id728}@anchor{1deb}
@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<81>,Tools/Demos<51>,C API<71>,Python 3 6 0 alpha 3
@anchor{whatsnew/changelog id729}@anchor{1dec}
@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<51>,Documentation<71>,Build<81>,Python 3 6 0 alpha 3
@anchor{whatsnew/changelog id730}@anchor{1ded}
@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<71>,Tests<74>,Tools/Demos<51>,Python 3 6 0 alpha 3
@anchor{whatsnew/changelog id731}@anchor{1dee}
@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<74>,,Documentation<71>,Python 3 6 0 alpha 3
@anchor{whatsnew/changelog id732}@anchor{1def}
@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{1df0}
@subsection Python 3.6.0 alpha 2


`Release date: 2016-06-13'

@menu
* Security: Security<53>. 
* Core and Builtins: Core and Builtins<84>. 
* Library: Library<85>. 
* IDLE: IDLE<54>. 
* Documentation: Documentation<72>. 
* Tests: Tests<75>. 
* Windows: Windows<73>. 
* Build: Build<82>. 
* C API: C API<72>. 
* Tools/Demos: Tools/Demos<52>. 

@end menu

@node Security<53>,Core and Builtins<84>,,Python 3 6 0 alpha 2
@anchor{whatsnew/changelog id733}@anchor{1df1}
@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{73f,,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<84>,Library<85>,Security<53>,Python 3 6 0 alpha 2
@anchor{whatsnew/changelog id734}@anchor{1df2}
@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<85>,IDLE<54>,Core and Builtins<84>,Python 3 6 0 alpha 2
@anchor{whatsnew/changelog id735}@anchor{1df3}
@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{82,,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{d8,,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<54>,Documentation<72>,Library<85>,Python 3 6 0 alpha 2
@anchor{whatsnew/changelog id736}@anchor{1df4}
@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<72>,Tests<75>,IDLE<54>,Python 3 6 0 alpha 2
@anchor{whatsnew/changelog id737}@anchor{1df5}
@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<75>,Windows<73>,Documentation<72>,Python 3 6 0 alpha 2
@anchor{whatsnew/changelog id738}@anchor{1df6}
@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<73>,Build<82>,Tests<75>,Python 3 6 0 alpha 2
@anchor{whatsnew/changelog id739}@anchor{1df7}
@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<82>,C API<72>,Windows<73>,Python 3 6 0 alpha 2
@anchor{whatsnew/changelog id740}@anchor{1df8}
@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<72>,Tools/Demos<52>,Build<82>,Python 3 6 0 alpha 2
@anchor{whatsnew/changelog id741}@anchor{1df9}
@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<52>,,C API<72>,Python 3 6 0 alpha 2
@anchor{whatsnew/changelog id742}@anchor{1dfa}
@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{1dfb}
@subsection Python 3.6.0 alpha 1


`Release date: 2016-05-16'

@menu
* Security: Security<54>. 
* Core and Builtins: Core and Builtins<85>. 
* Library: Library<86>. 
* IDLE: IDLE<55>. 
* Documentation: Documentation<73>. 
* Tests: Tests<76>. 
* Build: Build<83>. 
* Windows: Windows<74>. 
* Tools/Demos: Tools/Demos<53>. 
* C API: C API<73>. 

@end menu

@node Security<54>,Core and Builtins<85>,,Python 3 6 0 alpha 1
@anchor{whatsnew/changelog id743}@anchor{1dfc}
@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<85>,Library<86>,Security<54>,Python 3 6 0 alpha 1
@anchor{whatsnew/changelog id744}@anchor{1dfd}
@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{e5b,,PyMem_Malloc()} domain
(@ref{e5e,,PYMEM_DOMAIN_MEM}) now use the @ref{f06,,pymalloc allocator} rather than system @code{malloc()}. Applications calling
@ref{e5b,,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{e5b,,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{105,,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{e5d,,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{e59,,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{e5f,,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{1dfe,,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<86>,IDLE<55>,Core and Builtins<85>,Python 3 6 0 alpha 1
@anchor{whatsnew/changelog id745}@anchor{1dff}
@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{1304,,shutil.get_terminal_size()}, catch
@ref{5e8,,AttributeError} instead of @ref{450,,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{73f,,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{7b,,importlib} module now emits an @ref{653,,ImportError}
rather than a @ref{198,,TypeError} if @ref{ac8,,__import__()} is tried during the
Python shutdown process but @ref{3e2,,sys.path} is already cleared (set to
@code{None}).

@item 
bpo-21925@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21925}: @ref{1cc0,,warnings.formatwarning()} now catches exceptions when
calling @ref{240,,linecache.getline()} and
@ref{1e00,,tracemalloc.get_object_traceback()} to be able to log
@ref{547,,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{105,,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{f0e,,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{a25,,pyclbr.readmodule()} and @ref{a26,,pyclbr.readmodule_ex()}
to support importing packages.

@item 
bpo-26499@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26499}: Account for remaining Content-Length in HTTPResponse.readline()
and read1(). Based on patch by Silent Ghost. Also document that
HTTPResponse now supports these methods.

@item 
bpo-25320@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25320}: Handle sockets in directories unittest discovery is scanning.
Patch from Victor van den Elzen.

@item 
bpo-16181@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16181}: cookiejar.http2time() now returns None if year is higher than
datetime.MAXYEAR.

@item 
bpo-26513@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26513}: Fixes platform module detection of Windows Server

@item 
bpo-23718@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23718}: Fixed parsing time in week 0 before Jan 1.  Original patch by
Tamás Bence Gedai.

@item 
bpo-26323@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26323}: Add Mock.assert_called() and Mock.assert_called_once() methods
to unittest.mock. Patch written by Amit Saha.

@item 
bpo-20589@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20589}: Invoking Path.owner() and Path.group() on Windows now raise
NotImplementedError instead of ImportError.

@item 
bpo-26177@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26177}: Fixed the keys() method for Canvas and Scrollbar widgets.

@item 
bpo-15068@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15068}: Got rid of excessive buffering in fileinput. The bufsize
parameter is now deprecated and ignored.

@item 
bpo-19475@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19475}: Added an optional argument timespec to the datetime isoformat()
method to choose the precision of the time component.

@item 
bpo-2202@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2202}: Fix UnboundLocalError in
AbstractDigestAuthHandler.get_algorithm_impls. Initial patch by Mathieu
Dupuy.

@item 
bpo-26167@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26167}: Minimized overhead in copy.copy() and copy.deepcopy().
Optimized copying and deepcopying bytearrays, NotImplemented, slices,
short lists, tuples, dicts, sets.

@item 
bpo-25718@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25718}: Fixed pickling and copying the accumulate() iterator with total
is None.

@item 
bpo-26475@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26475}: Fixed debugging output for regular expressions with the (?x)
flag.

@item 
bpo-26482@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26482}: Allowed pickling recursive dequeues.

@item 
bpo-26335@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26335}: Make mmap.write() return the number of bytes written like other
write methods.  Patch by Jakub Stasiak.

@item 
bpo-26457@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26457}: Fixed the subnets() methods in IP network classes for the case
when resulting prefix length is equal to maximal prefix length. Based on
patch by Xiang Zhang.

@item 
bpo-26385@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26385}: Remove the file if the internal open() call in
NamedTemporaryFile() fails. Patch by Silent Ghost.

@item 
bpo-26402@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26402}: Fix XML-RPC client to retry when the server shuts down a
persistent connection.  This was a regression related to the new
http.client.RemoteDisconnected exception in 3.5.0a4.

@item 
bpo-25913@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25913}: Leading @code{<~} is optional now in base64.a85decode() with
adobe=True.  Patch by Swati Jaiswal.

@item 
bpo-26186@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26186}: Remove an invalid type check in importlib.util.LazyLoader.

@item 
bpo-26367@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26367}: importlib.__import__() raises ImportError like
builtins.__import__() when @code{level} is specified but without an
accompanying package specified.

@item 
bpo-26309@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26309}: In the "socketserver" module, shut down the request (closing
the connected socket) when verify_request() returns false.  Patch by Aviv
Palivoda.

@item 
bpo-23430@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23430}: Change the socketserver module to only catch exceptions raised
from a request handler that are derived from Exception (instead of
BaseException). Therefore SystemExit and KeyboardInterrupt no longer
trigger the handle_error() method, and will now to stop a single-threaded
server.

@item 
bpo-25995@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25995}: os.walk() no longer uses FDs proportional to the tree depth.

@item 
bpo-25994@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25994}: Added the close() method and the support of the context manager
protocol for the os.scandir() iterator.

@item 
bpo-23992@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23992}: multiprocessing: make MapResult not fail-fast upon exception.

@item 
bpo-26243@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26243}: Support keyword arguments to zlib.compress().  Patch by Aviv
Palivoda.

@item 
bpo-26117@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26117}: The os.scandir() iterator now closes file descriptor not only
when the iteration is finished, but when it was failed with error.

@item 
bpo-25949@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25949}: __dict__ for an OrderedDict instance is now created only when
needed.

@item 
bpo-25911@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25911}: Restored support of bytes paths in os.walk() on Windows.

@item 
bpo-26045@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26045}: Add UTF-8 suggestion to error message when posting a
non-Latin-1 string with http.client.

@item 
bpo-26039@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26039}: Added zipfile.ZipInfo.from_file() and zipinfo.ZipInfo.is_dir().
Patch by Thomas Kluyver.

@item 
bpo-12923@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12923}: Reset FancyURLopener's redirect counter even if there is an
exception. Based on patches by Brian Brazil and Daniel Rocco.

@item 
bpo-25945@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25945}: Fixed a crash when unpickle the functools.partial object with
wrong state. Fixed a leak in failed functools.partial constructor. "args"
and "keywords" attributes of functools.partial have now always types tuple
and dict correspondingly.

@item 
bpo-26202@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26202}: copy.deepcopy() now correctly copies range() objects with
non-atomic attributes.

@item 
bpo-23076@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23076}: Path.glob() now raises a ValueError if it's called with an
invalid pattern. Patch by Thomas Nyberg.

@item 
bpo-19883@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19883}: Fixed possible integer overflows in zipimport.

@item 
bpo-26227@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26227}: On Windows, getnameinfo(), gethostbyaddr() and
gethostbyname_ex() functions of the socket module now decode the hostname
from the ANSI code page rather than UTF-8.

@item 
bpo-26099@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26099}: The site module now writes an error into stderr if
sitecustomize module can be imported but executing the module raise an
ImportError. Same change for usercustomize.

@item 
bpo-26147@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26147}: xmlrpc now works with strings not encodable with used non-UTF-8
encoding.

@item 
bpo-25935@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25935}: Garbage collector now breaks reference loops with OrderedDict.

@item 
bpo-16620@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16620}: Fixed AttributeError in msilib.Directory.glob().

@item 
bpo-26013@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26013}: Added compatibility with broken protocol 2 pickles created in
old Python 3 versions (3.4.3 and lower).

@item 
bpo-26129@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26129}: Deprecated accepting non-integers in grp.getgrgid().

@item 
bpo-25850@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25850}: Use cross-compilation by default for 64-bit Windows.

@item 
bpo-25822@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25822}: Add docstrings to the fields of urllib.parse results. Patch
contributed by Swati Jaiswal.

@item 
bpo-22642@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22642}: Convert trace module option parsing mechanism to argparse.
Patch contributed by SilentGhost.

@item 
bpo-24705@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24705}: Fix sysconfig._parse_makefile not expanding $@{@} vars appearing
before $() vars.

@item 
bpo-26069@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26069}: Remove the deprecated apis in the trace module.

@item 
bpo-22138@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22138}: Fix mock.patch behavior when patching descriptors. Restore
original values after patching. Patch contributed by Sean McCully.

@item 
bpo-25672@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25672}: In the ssl module, enable the SSL_MODE_RELEASE_BUFFERS mode
option if it is safe to do so.

@item 
bpo-26012@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26012}: Don't traverse into symlinks for @code{**} pattern in
pathlib.Path.[r]glob().

@item 
bpo-24120@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24120}: Ignore PermissionError when traversing a tree with
pathlib.Path.[r]glob(). Patch by Ulrich Petri.

@item 
bpo-21815@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21815}: Accept ] characters in the data portion of imap responses, in
order to handle the flags with square brackets accepted and produced by
servers such as gmail.

@item 
bpo-25447@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25447}: fileinput now uses sys.stdin as-is if it does not have a buffer
attribute (restores backward compatibility).

@item 
bpo-25971@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25971}: Optimized creating Fractions from floats by 2 times and from
Decimals by 3 times.

@item 
bpo-25802@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25802}: Document as deprecated the remaining implementations of
importlib.abc.Loader.load_module().

@item 
bpo-25928@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25928}: Add Decimal.as_integer_ratio().

@item 
bpo-25447@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25447}: Copying the lru_cache() wrapper object now always works,
independently from the type of the wrapped object (by returning the
original object unchanged).

@item 
bpo-25768@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25768}: Have the functions in compileall return booleans instead of
ints and add proper documentation and tests for the return values.

@item 
bpo-24103@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24103}: Fixed possible use after free in ElementTree.XMLPullParser.

@item 
bpo-25860@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25860}: os.fwalk() no longer skips remaining directories when error
occurs. Original patch by Samson Lee.

@item 
bpo-25914@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25914}: Fixed and simplified OrderedDict.__sizeof__.

@item 
bpo-25869@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25869}: Optimized deepcopying ElementTree; it is now 20 times faster.

@item 
bpo-25873@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25873}: Optimized iterating ElementTree.  Iterating elements
Element.iter() is now 40% faster, iterating text Element.itertext() is now
up to 2.5 times faster.

@item 
bpo-25902@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25902}: Fixed various refcount issues in ElementTree iteration.

@item 
bpo-22227@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22227}: The TarFile iterator is reimplemented using generator. This
implementation is simpler that using class.

@item 
bpo-25638@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25638}: Optimized ElementTree.iterparse(); it is now 2x faster.
Optimized ElementTree parsing; it is now 10% faster.

@item 
bpo-25761@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25761}: Improved detecting errors in broken pickle data.

@item 
bpo-25717@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25717}: Restore the previous behaviour of tolerating most fstat()
errors when opening files.  This was a regression in 3.5a1, and stopped
anonymous temporary files from working in special cases.

@item 
bpo-24903@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24903}: Fix regression in number of arguments compileall accepts when
'-d' is specified.  The check on the number of arguments has been dropped
completely as it never worked correctly anyway.

@item 
bpo-25764@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25764}: In the subprocess module, preserve any exception caused by
fork() failure when preexec_fn is used.

@item 
bpo-25771@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25771}: Tweak the exception message for importlib.util.resolve_name()
when 'package' isn't specified but necessary.

@item 
bpo-6478@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6478}: _strptime's regexp cache now is reset after changing timezone
with time.tzset().

@item 
bpo-14285@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14285}: When executing a package with the "python -m package" option,
and package initialization fails, a proper traceback is now reported.  The
"runpy" module now lets exceptions from package initialization pass back
to the caller, rather than raising ImportError.

@item 
bpo-19771@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19771}: Also in runpy and the "-m" option, omit the irrelevant message
". . . is a package and cannot be directly executed" if the package could
not even be initialized (e.g. due to a bad @code{*.pyc} file).

@item 
bpo-25177@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25177}: Fixed problem with the mean of very small and very large
numbers. As a side effect, statistics.mean and statistics.variance should
be significantly faster.

@item 
bpo-25718@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25718}: Fixed copying object with state with boolean value is false.

@item 
bpo-10131@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10131}: Fixed deep copying of minidom documents.  Based on patch by
Marian Ganisin.

@item 
bpo-7990@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7990}: dir() on ElementTree.Element now lists properties: "tag",
"text", "tail" and "attrib".  Original patch by Santoso Wijaya.

@item 
bpo-25725@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25725}: Fixed a reference leak in pickle.loads() when unpickling
invalid data including tuple instructions.

@item 
bpo-25663@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25663}: In the Readline completer, avoid listing duplicate global
names, and search the global namespace before searching builtins.

@item 
bpo-25688@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25688}: Fixed file leak in ElementTree.iterparse() raising an error.

@item 
bpo-23914@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23914}: Fixed SystemError raised by unpickler on broken pickle data.

@item 
bpo-25691@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25691}: Fixed crash on deleting ElementTree.Element attributes.

@item 
bpo-25624@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25624}: ZipFile now always writes a ZIP_STORED header for directory
entries.  Patch by Dingyuan Wang.

@item 
bpo-25626@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25626}: Change three zlib functions to accept sizes that fit in
Py_ssize_t, but internally cap those sizes to UINT_MAX.  This resolves a
regression in 3.5 where GzipFile.read() failed to read chunks larger than
2 or 4 GiB.  The change affects the zlib.Decompress.decompress()
max_length parameter, the zlib.decompress() bufsize parameter, and the
zlib.Decompress.flush() length parameter.

@item 
bpo-25583@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25583}: Avoid incorrect errors raised by os.makedirs(exist_ok=True)
when the OS gives priority to errors such as EACCES over EEXIST.

@item 
bpo-25593@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25593}: Change semantics of EventLoop.stop() in asyncio.

@item 
bpo-6973@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6973}: When we know a subprocess.Popen process has died, do not allow
the send_signal(), terminate(), or kill() methods to do anything as they
could potentially signal a different process.

@item 
bpo-23883@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23883}: Added missing APIs to __all__ to match the documented APIs for
the following modules: calendar, csv, enum, fileinput, ftplib, logging,
optparse, tarfile, threading and wave.  Also added a
test.support.check__all__() helper. Patches by Jacek Kołodziej, Mauro S.
M. Rodrigues and Joel Taddei.

@item 
bpo-25590@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25590}: In the Readline completer, only call getattr() once per
attribute.  Also complete names of attributes such as properties and slots
which are listed by dir() but not yet created on an instance.

@item 
bpo-25498@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25498}: Fix a crash when garbage-collecting ctypes objects created by
wrapping a memoryview.  This was a regression made in 3.5a1.  Based on
patch by Eryksun.

@item 
bpo-25584@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25584}: Added "escape" to the __all__ list in the glob module.

@item 
bpo-25584@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25584}: Fixed recursive glob() with patterns starting with @code{**}.

@item 
bpo-25446@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25446}: Fix regression in smtplib's AUTH LOGIN support.

@item 
bpo-18010@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18010}: Fix the pydoc web server's module search function to handle
exceptions from importing packages.

@item 
bpo-25554@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25554}: Got rid of circular references in regular expression parsing.

@item 
bpo-18973@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18973}: Command-line interface of the calendar module now uses argparse
instead of optparse.

@item 
bpo-25510@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25510}: fileinput.FileInput.readline() now returns b'@w{'} instead of '@w{'} at
the end if the FileInput was opened with binary mode. Patch by Ryosuke
Ito.

@item 
bpo-25503@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25503}: Fixed inspect.getdoc() for inherited docstrings of properties.
Original patch by John Mark Vandenberg.

@item 
bpo-25515@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25515}: Always use os.urandom as a source of randomness in uuid.uuid4.

@item 
bpo-21827@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21827}: Fixed textwrap.dedent() for the case when largest common
whitespace is a substring of smallest leading whitespace. Based on patch
by Robert Li.

@item 
bpo-25447@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25447}: The lru_cache() wrapper objects now can be copied and pickled
(by returning the original object unchanged).

@item 
bpo-25390@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25390}: typing: Don't crash on Union[str, Pattern].

@item 
bpo-25441@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25441}: asyncio: Raise error from drain() when socket is closed.

@item 
bpo-25410@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25410}: Cleaned up and fixed minor bugs in C implementation of
OrderedDict.

@item 
bpo-25411@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25411}: Improved Unicode support in SMTPHandler through better use of
the email package. Thanks to user simon04 for the patch.

@item 
Move the imp module from a PendingDeprecationWarning to
DeprecationWarning.

@item 
bpo-25407@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25407}: Remove mentions of the formatter module being removed in Python
3.6.

@item 
bpo-25406@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25406}: Fixed a bug in C implementation of OrderedDict.move_to_end()
that caused segmentation fault or hang in iterating after moving several
items to the start of ordered dict.

@item 
bpo-25382@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25382}: pickletools.dis() now outputs implicit memo index for the
MEMOIZE opcode.

@item 
bpo-25357@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25357}: Add an optional newline parameter to binascii.b2a_base64().
base64.b64encode() uses it to avoid a memory copy.

@item 
bpo-24164@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24164}: Objects that need calling @code{__new__} with keyword arguments,
can now be pickled using pickle protocols older than protocol version 4.

@item 
bpo-25364@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25364}: zipfile now works in threads disabled builds.

@item 
bpo-25328@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25328}: smtpd's SMTPChannel now correctly raises a ValueError if both
decode_data and enable_SMTPUTF8 are set to true.

@item 
bpo-16099@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16099}: RobotFileParser now supports Crawl-delay and Request-rate
extensions.  Patch by Nikolay Bogoychev.

@item 
bpo-25316@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25316}: distutils raises OSError instead of DistutilsPlatformError when
MSVC is not installed.

@item 
bpo-25380@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25380}: Fixed protocol for the STACK_GLOBAL opcode in
pickletools.opcodes.

@item 
bpo-23972@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23972}: Updates asyncio datagram create method allowing reuseport and
reuseaddr socket options to be set prior to binding the socket. Mirroring
the existing asyncio create_server method the reuseaddr option for
datagram sockets defaults to True if the O/S is 'posix' (except if the
platform is Cygwin). Patch by Chris Laws.

@item 
bpo-25304@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25304}: Add asyncio.run_coroutine_threadsafe().  This lets you submit a
coroutine to a loop from another thread, returning a
concurrent.futures.Future.  By Vincent Michel.

@item 
bpo-25232@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25232}: Fix CGIRequestHandler to split the query from the URL at the
first question mark (?) rather than the last. Patch from Xiang Zhang.

@item 
bpo-24657@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24657}: Prevent CGIRequestHandler from collapsing slashes in the query
part of the URL as if it were a path. Patch from Xiang Zhang.

@item 
bpo-25287@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25287}: Don't add crypt.METHOD_CRYPT to crypt.methods if it's not
supported. Check if it is supported, it may not be supported on OpenBSD
for example.

@item 
bpo-23600@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23600}: Default implementation of tzinfo.fromutc() was returning wrong
results in some cases.

@item 
bpo-25203@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25203}: Failed readline.set_completer_delims() no longer left the
module in inconsistent state.

@item 
bpo-25011@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25011}: rlcompleter now omits private and special attribute names
unless the prefix starts with underscores.

@item 
bpo-25209@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25209}: rlcompleter now can add a space or a colon after completed
keyword.

@item 
bpo-22241@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22241}: timezone.utc name is now plain 'UTC', not 'UTC-00:00'.

@item 
bpo-23517@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23517}: fromtimestamp() and utcfromtimestamp() methods of
datetime.datetime now round microseconds to nearest with ties going to
nearest even integer (ROUND_HALF_EVEN), as round(float), instead of
rounding towards -Infinity (ROUND_FLOOR).

@item 
bpo-23552@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23552}: Timeit now warns when there is substantial (4x) variance
between best and worst times. Patch from Serhiy Storchaka.

@item 
bpo-24633@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24633}: site-packages/README -> README.txt.

@item 
bpo-24879@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24879}: help() and pydoc can now list named tuple fields in the order
they were defined rather than alphabetically.  The ordering is determined
by the _fields attribute if present.

@item 
bpo-24874@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24874}: Improve speed of itertools.cycle() and make its pickle more
compact.

@item 
Fix crash in itertools.cycle.__setstate__() when the first argument wasn't
a list.

@item 
bpo-20059@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20059}: urllib.parse raises ValueError on all invalid ports. Patch by
Martin Panter.

@item 
bpo-24360@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24360}: Improve __repr__ of argparse.Namespace() for invalid
identifiers.  Patch by Matthias Bussonnier.

@item 
bpo-23426@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23426}: run_setup was broken in distutils. Patch from Alexander
Belopolsky.

@item 
bpo-13938@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13938}: 2to3 converts StringTypes to a tuple. Patch from Mark Hammond.

@item 
bpo-2091@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2091}: open() accepted a 'U' mode string containing '+', but 'U' can
only be used with 'r'. Patch from Jeff Balogh and John O'Connor.

@item 
bpo-8585@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8585}: improved tests for zipimporter2. Patch from Mark Lawrence.

@item 
bpo-18622@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18622}: unittest.mock.mock_open().reset_mock would recurse infinitely.
Patch from Nicola Palumbo and Laurent De Buyst.

@item 
bpo-24426@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24426}: Fast searching optimization in regular expressions now works
for patterns that starts with capturing groups.  Fast searching
optimization now can't be disabled at compile time.

@item 
bpo-23661@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23661}: unittest.mock side_effects can now be exceptions again. This
was a regression vs Python 3.4. Patch from Ignacio Rossi

@item 
bpo-13248@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13248}: Remove deprecated inspect.getmoduleinfo function.

@item 
bpo-25578@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25578}: Fix (another) memory leak in SSLSocket.getpeercer().

@item 
bpo-25530@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25530}: Disable the vulnerable SSLv3 protocol by default when creating
ssl.SSLContext.

@item 
bpo-25569@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25569}: Fix memory leak in SSLSocket.getpeercert().

@item 
bpo-25471@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25471}: Sockets returned from accept() shouldn't appear to be
nonblocking.

@item 
bpo-25319@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25319}: When threading.Event is reinitialized, the underlying condition
should use a regular lock rather than a recursive lock.

@item 
Skip getaddrinfo if host is already resolved. Patch by A. Jesse Jiryu
Davis.

@item 
bpo-26050@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26050}: Add asyncio.StreamReader.readuntil() method. Patch by Марк
Коренберг.

@item 
bpo-25924@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25924}: Avoid unnecessary serialization of getaddrinfo(3) calls on OS X
versions 10.5 or higher.  Original patch by A. Jesse Jiryu Davis.

@item 
bpo-26406@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26406}: Avoid unnecessary serialization of getaddrinfo(3) calls on
current versions of OpenBSD and NetBSD.  Patch by A. Jesse Jiryu Davis.

@item 
bpo-26848@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26848}: Fix asyncio/subprocess.communicate() to handle empty input.
Patch by Jack O'Connor.

@item 
bpo-27040@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27040}: Add loop.get_exception_handler method

@item 
bpo-27041@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27041}: asyncio: Add loop.create_future method
@end itemize

@node IDLE<55>,Documentation<73>,Library<86>,Python 3 6 0 alpha 1
@anchor{whatsnew/changelog id746}@anchor{1e01}
@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<73>,Tests<76>,IDLE<55>,Python 3 6 0 alpha 1
@anchor{whatsnew/changelog id747}@anchor{1e02}
@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<76>,Build<83>,Documentation<73>,Python 3 6 0 alpha 1
@anchor{whatsnew/changelog id748}@anchor{1e03}
@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<83>,Windows<74>,Tests<76>,Python 3 6 0 alpha 1
@anchor{whatsnew/changelog id749}@anchor{1e04}
@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<74>,Tools/Demos<53>,Build<83>,Python 3 6 0 alpha 1
@anchor{whatsnew/changelog id750}@anchor{1e05}
@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<53>,C API<73>,Windows<74>,Python 3 6 0 alpha 1
@anchor{whatsnew/changelog id751}@anchor{1e06}
@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<73>,,Tools/Demos<53>,Python 3 6 0 alpha 1
@anchor{whatsnew/changelog id752}@anchor{1e07}
@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{1e08}
@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{1e09}
@subsection Python 3.5.5 release candidate 1


`Release date: 2018-01-23'

@menu
* Security: Security<55>. 
* Core and Builtins: Core and Builtins<86>. 
* Library: Library<87>. 

@end menu

@node Security<55>,Core and Builtins<86>,,Python 3 5 5 release candidate 1
@anchor{whatsnew/changelog id753}@anchor{1e0a}
@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<86>,Library<87>,Security<55>,Python 3 5 5 release candidate 1
@anchor{whatsnew/changelog id754}@anchor{1e0b}
@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<87>,,Core and Builtins<86>,Python 3 5 5 release candidate 1
@anchor{whatsnew/changelog id755}@anchor{1e0c}
@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{1e0d}
@subsection Python 3.5.4 final


`Release date: 2017-08-07'

@menu
* Library: Library<88>. 

@end menu

@node Library<88>,,,Python 3 5 4 final
@anchor{whatsnew/changelog id756}@anchor{1e0e}
@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{1e0f}
@subsection Python 3.5.4 release candidate 1


`Release date: 2017-07-23'

@menu
* Security: Security<56>. 
* Core and Builtins: Core and Builtins<87>. 
* Library: Library<89>. 
* Documentation: Documentation<74>. 
* Tests: Tests<77>. 
* Build: Build<84>. 
* Windows: Windows<75>. 
* C API: C API<74>. 

@end menu

@node Security<56>,Core and Builtins<87>,,Python 3 5 4 release candidate 1
@anchor{whatsnew/changelog id757}@anchor{1e10}
@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<87>,Library<89>,Security<56>,Python 3 5 4 release candidate 1
@anchor{whatsnew/changelog id758}@anchor{1e11}
@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{a78,,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<89>,Documentation<74>,Core and Builtins<87>,Python 3 5 4 release candidate 1
@anchor{whatsnew/changelog id759}@anchor{1e12}
@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<74>,Tests<77>,Library<89>,Python 3 5 4 release candidate 1
@anchor{whatsnew/changelog id760}@anchor{1e13}
@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<77>,Build<84>,Documentation<74>,Python 3 5 4 release candidate 1
@anchor{whatsnew/changelog id761}@anchor{1e14}
@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<84>,Windows<75>,Tests<77>,Python 3 5 4 release candidate 1
@anchor{whatsnew/changelog id762}@anchor{1e15}
@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<75>,C API<74>,Build<84>,Python 3 5 4 release candidate 1
@anchor{whatsnew/changelog id763}@anchor{1e16}
@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<74>,,Windows<75>,Python 3 5 4 release candidate 1
@anchor{whatsnew/changelog id764}@anchor{1e17}
@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{1e18}
@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{1e19}
@subsection Python 3.5.3 release candidate 1


`Release date: 2017-01-02'

@menu
* Security: Security<57>. 
* Core and Builtins: Core and Builtins<88>. 
* Library: Library<90>. 
* IDLE: IDLE<56>. 
* C API: C API<75>. 
* Documentation: Documentation<75>. 
* Tests: Tests<78>. 
* Tools/Demos: Tools/Demos<54>. 
* Windows: Windows<76>. 
* Build: Build<85>. 

@end menu

@node Security<57>,Core and Builtins<88>,,Python 3 5 3 release candidate 1
@anchor{whatsnew/changelog id765}@anchor{1e1a}
@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<88>,Library<90>,Security<57>,Python 3 5 3 release candidate 1
@anchor{whatsnew/changelog id766}@anchor{1e1b}
@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<90>,IDLE<56>,Core and Builtins<88>,Python 3 5 3 release candidate 1
@anchor{whatsnew/changelog id767}@anchor{1e1c}
@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<56>,C API<75>,Library<90>,Python 3 5 3 release candidate 1
@anchor{whatsnew/changelog id768}@anchor{1e1d}
@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<75>,Documentation<75>,IDLE<56>,Python 3 5 3 release candidate 1
@anchor{whatsnew/changelog id769}@anchor{1e1e}
@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<75>,Tests<78>,C API<75>,Python 3 5 3 release candidate 1
@anchor{whatsnew/changelog id770}@anchor{1e1f}
@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<78>,Tools/Demos<54>,Documentation<75>,Python 3 5 3 release candidate 1
@anchor{whatsnew/changelog id771}@anchor{1e20}
@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<54>,Windows<76>,Tests<78>,Python 3 5 3 release candidate 1
@anchor{whatsnew/changelog id772}@anchor{1e21}
@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<76>,Build<85>,Tools/Demos<54>,Python 3 5 3 release candidate 1
@anchor{whatsnew/changelog id773}@anchor{1e22}
@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<85>,,Windows<76>,Python 3 5 3 release candidate 1
@anchor{whatsnew/changelog id774}@anchor{1e23}
@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{1e24}
@subsection Python 3.5.2 final


`Release date: 2016-06-26'

@menu
* Core and Builtins: Core and Builtins<89>. 
* Tests: Tests<79>. 
* IDLE: IDLE<57>. 

@end menu

@node Core and Builtins<89>,Tests<79>,,Python 3 5 2 final
@anchor{whatsnew/changelog id775}@anchor{1e25}
@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<79>,IDLE<57>,Core and Builtins<89>,Python 3 5 2 final
@anchor{whatsnew/changelog id776}@anchor{1e26}
@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<57>,,Tests<79>,Python 3 5 2 final
@anchor{whatsnew/changelog id777}@anchor{1e27}
@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{1e28}
@subsection Python 3.5.2 release candidate 1


`Release date: 2016-06-12'

@menu
* Security: Security<58>. 
* Core and Builtins: Core and Builtins<90>. 
* Library: Library<91>. 
* IDLE: IDLE<58>. 
* Documentation: Documentation<76>. 
* Tests: Tests<80>. 
* Build: Build<86>. 
* Windows: Windows<77>. 
* Tools/Demos: Tools/Demos<55>. 

@end menu

@node Security<58>,Core and Builtins<90>,,Python 3 5 2 release candidate 1
@anchor{whatsnew/changelog id778}@anchor{1e29}
@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{73f,,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<90>,Library<91>,Security<58>,Python 3 5 2 release candidate 1
@anchor{whatsnew/changelog id779}@anchor{1e2a}
@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<91>,IDLE<58>,Core and Builtins<90>,Python 3 5 2 release candidate 1
@anchor{whatsnew/changelog id780}@anchor{1e2b}
@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{d8,,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{1304,,shutil.get_terminal_size()}, catch
@ref{5e8,,AttributeError} instead of @ref{450,,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{73f,,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{1cc0,,warnings.formatwarning()} now catches exceptions on
@code{linecache.getline(...)} to be able to log @ref{547,,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{a25,,pyclbr.readmodule()} and @ref{a26,,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<58>,Documentation<76>,Library<91>,Python 3 5 2 release candidate 1
@anchor{whatsnew/changelog id781}@anchor{1e2c}
@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<76>,Tests<80>,IDLE<58>,Python 3 5 2 release candidate 1
@anchor{whatsnew/changelog id782}@anchor{1e2d}
@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<80>,Build<86>,Documentation<76>,Python 3 5 2 release candidate 1
@anchor{whatsnew/changelog id783}@anchor{1e2e}
@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<86>,Windows<77>,Tests<80>,Python 3 5 2 release candidate 1
@anchor{whatsnew/changelog id784}@anchor{1e2f}
@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<77>,Tools/Demos<55>,Build<86>,Python 3 5 2 release candidate 1
@anchor{whatsnew/changelog id785}@anchor{1e30}
@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<55>,,Windows<77>,Python 3 5 2 release candidate 1
@anchor{whatsnew/changelog id786}@anchor{1e31}
@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{1e32}
@subsection Python 3.5.1 final


`Release date: 2015-12-06'

@menu
* Core and Builtins: Core and Builtins<91>. 
* Windows: Windows<78>. 

@end menu

@node Core and Builtins<91>,Windows<78>,,Python 3 5 1 final
@anchor{whatsnew/changelog id787}@anchor{1e33}
@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<78>,,Core and Builtins<91>,Python 3 5 1 final
@anchor{whatsnew/changelog id788}@anchor{1e34}
@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{1e35}
@subsection Python 3.5.1 release candidate 1


`Release date: 2015-11-22'

@menu
* Core and Builtins: Core and Builtins<92>. 
* Library: Library<92>. 
* IDLE: IDLE<59>. 
* Documentation: Documentation<77>. 
* Tests: Tests<81>. 
* Build: Build<87>. 
* Windows: Windows<79>. 
* Tools/Demos: Tools/Demos<56>. 

@end menu

@node Core and Builtins<92>,Library<92>,,Python 3 5 1 release candidate 1
@anchor{whatsnew/changelog id789}@anchor{1e36}
@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<92>,IDLE<59>,Core and Builtins<92>,Python 3 5 1 release candidate 1
@anchor{whatsnew/changelog id790}@anchor{1e37}
@subsubsection Library



@itemize -

@item 
bpo-25626@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25626}: Change three zlib functions to accept sizes that fit in
Py_ssize_t, but internally cap those sizes to UINT_MAX.  This resolves a
regression in 3.5 where GzipFile.read() failed to read chunks larger than
2 or 4 GiB.  The change affects the zlib.Decompress.decompress()
max_length parameter, the zlib.decompress() bufsize parameter, and the
zlib.Decompress.flush() length parameter.

@item 
bpo-25583@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25583}: Avoid incorrect errors raised by os.makedirs(exist_ok=True)
when the OS gives priority to errors such as EACCES over EEXIST.

@item 
bpo-25593@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25593}: Change semantics of EventLoop.stop() in asyncio.

@item 
bpo-6973@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6973}: When we know a subprocess.Popen process has died, do not allow
the send_signal(), terminate(), or kill() methods to do anything as they
could potentially signal a different process.

@item 
bpo-25590@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25590}: In the Readline completer, only call getattr() once per
attribute.

@item 
bpo-25498@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25498}: Fix a crash when garbage-collecting ctypes objects created by
wrapping a memoryview.  This was a regression made in 3.5a1.  Based on
patch by Eryksun.

@item 
bpo-25584@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25584}: Added "escape" to the __all__ list in the glob module.

@item 
bpo-25584@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25584}: Fixed recursive glob() with patterns starting with @code{**}.

@item 
bpo-25446@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25446}: Fix regression in smtplib's AUTH LOGIN support.

@item 
bpo-18010@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18010}: Fix the pydoc web server's module search function to handle
exceptions from importing packages.

@item 
bpo-25554@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25554}: Got rid of circular references in regular expression parsing.

@item 
bpo-25510@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25510}: fileinput.FileInput.readline() now returns b'@w{'} instead of '@w{'} at
the end if the FileInput was opened with binary mode. Patch by Ryosuke
Ito.

@item 
bpo-25503@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25503}: Fixed inspect.getdoc() for inherited docstrings of properties.
Original patch by John Mark Vandenberg.

@item 
bpo-25515@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25515}: Always use os.urandom as a source of randomness in uuid.uuid4.

@item 
bpo-21827@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21827}: Fixed textwrap.dedent() for the case when largest common
whitespace is a substring of smallest leading whitespace. Based on patch
by Robert Li.

@item 
bpo-25447@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25447}: The lru_cache() wrapper objects now can be copied and pickled
(by returning the original object unchanged).

@item 
bpo-25390@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25390}: typing: Don't crash on Union[str, Pattern].

@item 
bpo-25441@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25441}: asyncio: Raise error from drain() when socket is closed.

@item 
bpo-25410@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25410}: Cleaned up and fixed minor bugs in C implementation of
OrderedDict.

@item 
bpo-25411@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25411}: Improved Unicode support in SMTPHandler through better use of
the email package. Thanks to user simon04 for the patch.

@item 
bpo-25407@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25407}: Remove mentions of the formatter module being removed in Python
3.6.

@item 
bpo-25406@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25406}: Fixed a bug in C implementation of OrderedDict.move_to_end()
that caused segmentation fault or hang in iterating after moving several
items to the start of ordered dict.

@item 
bpo-25364@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25364}: zipfile now works in threads disabled builds.

@item 
bpo-25328@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25328}: smtpd's SMTPChannel now correctly raises a ValueError if both
decode_data and enable_SMTPUTF8 are set to true.

@item 
bpo-25316@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25316}: distutils raises OSError instead of DistutilsPlatformError when
MSVC is not installed.

@item 
bpo-25380@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25380}: Fixed protocol for the STACK_GLOBAL opcode in
pickletools.opcodes.

@item 
bpo-23972@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23972}: Updates asyncio datagram create method allowing reuseport and
reuseaddr socket options to be set prior to binding the socket. Mirroring
the existing asyncio create_server method the reuseaddr option for
datagram sockets defaults to True if the O/S is 'posix' (except if the
platform is Cygwin). Patch by Chris Laws.

@item 
bpo-25304@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25304}: Add asyncio.run_coroutine_threadsafe().  This lets you submit a
coroutine to a loop from another thread, returning a
concurrent.futures.Future.  By Vincent Michel.

@item 
bpo-25232@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25232}: Fix CGIRequestHandler to split the query from the URL at the
first question mark (?) rather than the last. Patch from Xiang Zhang.

@item 
bpo-24657@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24657}: Prevent CGIRequestHandler from collapsing slashes in the query
part of the URL as if it were a path. Patch from Xiang Zhang.

@item 
bpo-24483@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24483}: C implementation of functools.lru_cache() now calculates key's
hash only once.

@item 
bpo-22958@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22958}: Constructor and update method of weakref.WeakValueDictionary
now accept the self and the dict keyword arguments.

@item 
bpo-22609@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22609}: Constructor of collections.UserDict now accepts the self
keyword argument.

@item 
bpo-25111@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25111}: Fixed comparison of traceback.FrameSummary.

@item 
bpo-25262@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25262}: Added support for BINBYTES8 opcode in Python implementation of
unpickler. Highest 32 bits of 64-bit size for BINUNICODE8 and BINBYTES8
opcodes no longer silently ignored on 32-bit platforms in C
implementation.

@item 
bpo-25034@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25034}: Fix string.Formatter problem with auto-numbering and nested
format_specs. Patch by Anthon van der Neut.

@item 
bpo-25233@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25233}: Rewrite the guts of asyncio.Queue and asyncio.Semaphore to be
more understandable and correct.

@item 
bpo-25203@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25203}: Failed readline.set_completer_delims() no longer left the
module in inconsistent state.

@item 
bpo-23600@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23600}: Default implementation of tzinfo.fromutc() was returning wrong
results in some cases.

@item 
bpo-23329@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23329}: Allow the ssl module to be built with older versions of
LibreSSL.

@item 
Prevent overflow in _Unpickler_Read.

@item 
bpo-25047@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25047}: The XML encoding declaration written by Element Tree now
respects the letter case given by the user. This restores the ability to
write encoding names in uppercase like "UTF-8", which worked in Python 2.

@item 
bpo-25135@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25135}: Make deque_clear() safer by emptying the deque before clearing.
This helps avoid possible reentrancy issues.

@item 
bpo-19143@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19143}: platform module now reads Windows version from kernel32.dll to
avoid compatibility shims.

@item 
bpo-25092@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25092}: Fix datetime.strftime() failure when errno was already set to
EINVAL.

@item 
bpo-23517@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23517}: Fix rounding in fromtimestamp() and utcfromtimestamp() methods
of datetime.datetime: microseconds are now rounded to nearest with ties
going to nearest even integer (ROUND_HALF_EVEN), instead of being rounding
towards minus infinity (ROUND_FLOOR). It's important that these methods
use the same rounding mode than datetime.timedelta to keep the property:
(datetime(1970,1,1) + timedelta(seconds=t)) ==
datetime.utcfromtimestamp(t). It also the rounding mode used by
round(float) for example.

@item 
bpo-25155@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25155}: Fix datetime.datetime.now() and datetime.datetime.utcnow() on
Windows to support date after year 2038. It was a regression introduced in
Python 3.5.0.

@item 
bpo-25108@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25108}: Omitted internal frames in traceback functions print_stack(),
format_stack(), and extract_stack() called without arguments.

@item 
bpo-25118@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25118}: Fix a regression of Python 3.5.0 in os.waitpid() on Windows.

@item 
bpo-24684@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24684}: socket.socket.getaddrinfo() now calls
PyUnicode_AsEncodedString() instead of calling the encode() method of the
host, to handle correctly custom string with an encode() method which
doesn't return a byte string. The encoder of the IDNA codec is now called
directly instead of calling the encode() method of the string.

@item 
bpo-25060@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25060}: Correctly compute stack usage of the BUILD_MAP opcode.

@item 
bpo-24857@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24857}: Comparing call_args to a long sequence now correctly returns a
boolean result instead of raising an exception.  Patch by A Kaptur.

@item 
bpo-23144@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23144}: Make sure that HTMLParser.feed() returns all the data, even
when convert_charrefs is True.

@item 
bpo-24982@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24982}: shutil.make_archive() with the "zip" format now adds entries
for directories (including empty directories) in ZIP file.

@item 
bpo-25019@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25019}: Fixed a crash caused by setting non-string key of expat parser.
Based on patch by John Leitch.

@item 
bpo-16180@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16180}: Exit pdb if file has syntax error, instead of trapping user in
an infinite loop.  Patch by Xavier de Gaye.

@item 
bpo-24891@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24891}: Fix a race condition at Python startup if the file descriptor
of stdin (0), stdout (1) or stderr (2) is closed while Python is creating
sys.stdin, sys.stdout and sys.stderr objects. These attributes are now set
to None if the creation of the object failed, instead of raising an
OSError exception. Initial patch written by Marco Paolini.

@item 
bpo-24992@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24992}: Fix error handling and a race condition (related to garbage
collection) in collections.OrderedDict constructor.

@item 
bpo-24881@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24881}: Fixed setting binary mode in Python implementation of FileIO on
Windows and Cygwin.  Patch from Akira Li.

@item 
bpo-25578@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25578}: Fix (another) memory leak in SSLSocket.getpeercer().

@item 
bpo-25530@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25530}: Disable the vulnerable SSLv3 protocol by default when creating
ssl.SSLContext.

@item 
bpo-25569@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25569}: Fix memory leak in SSLSocket.getpeercert().

@item 
bpo-25471@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25471}: Sockets returned from accept() shouldn't appear to be
nonblocking.

@item 
bpo-25319@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25319}: When threading.Event is reinitialized, the underlying condition
should use a regular lock rather than a recursive lock.

@item 
bpo-21112@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21112}: Fix regression in unittest.expectedFailure on subclasses. Patch
from Berker Peksag.

@item 
bpo-24764@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24764}: cgi.FieldStorage.read_multi() now ignores the Content-Length
header in part headers. Patch written by Peter Landry and reviewed by
Pierre Quentel.

@item 
bpo-24913@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24913}: Fix overrun error in deque.index(). Found by John Leitch and
Bryce Darling.

@item 
bpo-24774@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24774}: Fix docstring in http.server.test. Patch from Chiu-Hsiang Hsu.

@item 
bpo-21159@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21159}: Improve message in
configparser.InterpolationMissingOptionError. Patch from Łukasz Langa.

@item 
bpo-20362@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20362}: Honour TestCase.longMessage correctly in assertRegex. Patch
from Ilia Kurenkov.

@item 
bpo-23572@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23572}: Fixed functools.singledispatch on classes with false
metaclasses.  Patch by Ethan Furman.

@item 
asyncio: ensure_future() now accepts awaitable objects.
@end itemize

@node IDLE<59>,Documentation<77>,Library<92>,Python 3 5 1 release candidate 1
@anchor{whatsnew/changelog id791}@anchor{1e38}
@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<77>,Tests<81>,IDLE<59>,Python 3 5 1 release candidate 1
@anchor{whatsnew/changelog id792}@anchor{1e39}
@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<81>,Build<87>,Documentation<77>,Python 3 5 1 release candidate 1
@anchor{whatsnew/changelog id793}@anchor{1e3a}
@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<87>,Windows<79>,Tests<81>,Python 3 5 1 release candidate 1
@anchor{whatsnew/changelog id794}@anchor{1e3b}
@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<79>,Tools/Demos<56>,Build<87>,Python 3 5 1 release candidate 1
@anchor{whatsnew/changelog id795}@anchor{1e3c}
@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<56>,,Windows<79>,Python 3 5 1 release candidate 1
@anchor{whatsnew/changelog id796}@anchor{1e3d}
@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{1e3e}
@subsection Python 3.5.0 final


`Release date: 2015-09-13'

@menu
* Build: Build<88>. 

@end menu

@node Build<88>,,,Python 3 5 0 final
@anchor{whatsnew/changelog id797}@anchor{1e3f}
@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{1e40}
@subsection Python 3.5.0 release candidate 4


`Release date: 2015-09-09'

@menu
* Library: Library<93>. 
* Build: Build<89>. 

@end menu

@node Library<93>,Build<89>,,Python 3 5 0 release candidate 4
@anchor{whatsnew/changelog id798}@anchor{1e41}
@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<89>,,Library<93>,Python 3 5 0 release candidate 4
@anchor{whatsnew/changelog id799}@anchor{1e42}
@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{1e43}
@subsection Python 3.5.0 release candidate 3


`Release date: 2015-09-07'

@menu
* Core and Builtins: Core and Builtins<93>. 
* Library: Library<94>. 

@end menu

@node Core and Builtins<93>,Library<94>,,Python 3 5 0 release candidate 3
@anchor{whatsnew/changelog id800}@anchor{1e44}
@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<94>,,Core and Builtins<93>,Python 3 5 0 release candidate 3
@anchor{whatsnew/changelog id801}@anchor{1e45}
@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{1e46}
@subsection Python 3.5.0 release candidate 2


`Release date: 2015-08-25'

@menu
* Core and Builtins: Core and Builtins<94>. 
* Library: Library<95>. 

@end menu

@node Core and Builtins<94>,Library<95>,,Python 3 5 0 release candidate 2
@anchor{whatsnew/changelog id802}@anchor{1e47}
@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<95>,,Core and Builtins<94>,Python 3 5 0 release candidate 2
@anchor{whatsnew/changelog id803}@anchor{1e48}
@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{1e49}
@subsection Python 3.5.0 release candidate 1


`Release date: 2015-08-09'

@menu
* Core and Builtins: Core and Builtins<95>. 
* Library: Library<96>. 
* IDLE: IDLE<60>. 
* Documentation: Documentation<78>. 
* Tests: Tests<82>. 

@end menu

@node Core and Builtins<95>,Library<96>,,Python 3 5 0 release candidate 1
@anchor{whatsnew/changelog id804}@anchor{1e4a}
@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<96>,IDLE<60>,Core and Builtins<95>,Python 3 5 0 release candidate 1
@anchor{whatsnew/changelog id805}@anchor{1e4b}
@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<60>,Documentation<78>,Library<96>,Python 3 5 0 release candidate 1
@anchor{whatsnew/changelog id806}@anchor{1e4c}
@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<78>,Tests<82>,IDLE<60>,Python 3 5 0 release candidate 1
@anchor{whatsnew/changelog id807}@anchor{1e4d}
@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<82>,,Documentation<78>,Python 3 5 0 release candidate 1
@anchor{whatsnew/changelog id808}@anchor{1e4e}
@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{1e4f}
@subsection Python 3.5.0 beta 4


`Release date: 2015-07-26'

@menu
* Core and Builtins: Core and Builtins<96>. 
* Library: Library<97>. 
* Build: Build<90>. 

@end menu

@node Core and Builtins<96>,Library<97>,,Python 3 5 0 beta 4
@anchor{whatsnew/changelog id809}@anchor{1e50}
@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<97>,Build<90>,Core and Builtins<96>,Python 3 5 0 beta 4
@anchor{whatsnew/changelog id810}@anchor{1e51}
@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<90>,,Library<97>,Python 3 5 0 beta 4
@anchor{whatsnew/changelog id811}@anchor{1e52}
@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{1e53}
@subsection Python 3.5.0 beta 3


`Release date: 2015-07-05'

@menu
* Core and Builtins: Core and Builtins<97>. 
* Library: Library<98>. 
* Tests: Tests<83>. 
* Documentation: Documentation<79>. 
* Build: Build<91>. 

@end menu

@node Core and Builtins<97>,Library<98>,,Python 3 5 0 beta 3
@anchor{whatsnew/changelog id812}@anchor{1e54}
@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<98>,Tests<83>,Core and Builtins<97>,Python 3 5 0 beta 3
@anchor{whatsnew/changelog id813}@anchor{1e55}
@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<83>,Documentation<79>,Library<98>,Python 3 5 0 beta 3
@anchor{whatsnew/changelog id814}@anchor{1e56}
@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<79>,Build<91>,Tests<83>,Python 3 5 0 beta 3
@anchor{whatsnew/changelog id815}@anchor{1e57}
@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<91>,,Documentation<79>,Python 3 5 0 beta 3
@anchor{whatsnew/changelog id816}@anchor{1e58}
@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{1e59}
@subsection Python 3.5.0 beta 2


`Release date: 2015-05-31'

@menu
* Core and Builtins: Core and Builtins<98>. 
* Library: Library<99>. 

@end menu

@node Core and Builtins<98>,Library<99>,,Python 3 5 0 beta 2
@anchor{whatsnew/changelog id817}@anchor{1e5a}
@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<99>,,Core and Builtins<98>,Python 3 5 0 beta 2
@anchor{whatsnew/changelog id818}@anchor{1e5b}
@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{1e5c}
@subsection Python 3.5.0 beta 1


`Release date: 2015-05-24'

@menu
* Core and Builtins: Core and Builtins<99>. 
* Library: Library<100>. 
* IDLE: IDLE<61>. 
* Tests: Tests<84>. 
* Documentation: Documentation<80>. 
* Tools/Demos: Tools/Demos<57>. 

@end menu

@node Core and Builtins<99>,Library<100>,,Python 3 5 0 beta 1
@anchor{whatsnew/changelog id819}@anchor{1e5d}
@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<100>,IDLE<61>,Core and Builtins<99>,Python 3 5 0 beta 1
@anchor{whatsnew/changelog id820}@anchor{1e5e}
@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<61>,Tests<84>,Library<100>,Python 3 5 0 beta 1
@anchor{whatsnew/changelog id821}@anchor{1e5f}
@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<84>,Documentation<80>,IDLE<61>,Python 3 5 0 beta 1
@anchor{whatsnew/changelog id822}@anchor{1e60}
@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<80>,Tools/Demos<57>,Tests<84>,Python 3 5 0 beta 1
@anchor{whatsnew/changelog id823}@anchor{1e61}
@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<57>,,Documentation<80>,Python 3 5 0 beta 1
@anchor{whatsnew/changelog id824}@anchor{1e62}
@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{1e63}
@subsection Python 3.5.0 alpha 4


`Release date: 2015-04-19'

@menu
* Core and Builtins: Core and Builtins<100>. 
* Library: Library<101>. 
* Build: Build<92>. 
* Tests: Tests<85>. 
* Tools/Demos: Tools/Demos<58>. 
* C API: C API<76>. 

@end menu

@node Core and Builtins<100>,Library<101>,,Python 3 5 0 alpha 4
@anchor{whatsnew/changelog id825}@anchor{1e64}
@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<101>,Build<92>,Core and Builtins<100>,Python 3 5 0 alpha 4
@anchor{whatsnew/changelog id826}@anchor{1e65}
@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{fa3,,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{f9e,,socket.socket.connect()} now waits until the connection
completes instead of raising @ref{f83,,InterruptedError} if the connection is
interrupted by signals, signal handlers don't raise an exception and the
socket is blocking or has a timeout. @ref{f9e,,socket.socket.connect()} still
raise @ref{f83,,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<92>,Tests<85>,Library<101>,Python 3 5 0 alpha 4
@anchor{whatsnew/changelog id827}@anchor{1e66}
@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<85>,Tools/Demos<58>,Build<92>,Python 3 5 0 alpha 4
@anchor{whatsnew/changelog id828}@anchor{1e67}
@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<58>,C API<76>,Tests<85>,Python 3 5 0 alpha 4
@anchor{whatsnew/changelog id829}@anchor{1e68}
@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<76>,,Tools/Demos<58>,Python 3 5 0 alpha 4
@anchor{whatsnew/changelog id830}@anchor{1e69}
@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{1e6a}
@subsection Python 3.5.0 alpha 3


`Release date: 2015-03-28'

@menu
* Core and Builtins: Core and Builtins<101>. 
* Library: Library<102>. 
* Build: Build<93>. 
* Tests: Tests<86>. 
* Tools/Demos: Tools/Demos<59>. 

@end menu

@node Core and Builtins<101>,Library<102>,,Python 3 5 0 alpha 3
@anchor{whatsnew/changelog id831}@anchor{1e6b}
@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<102>,Build<93>,Core and Builtins<101>,Python 3 5 0 alpha 3
@anchor{whatsnew/changelog id832}@anchor{1e6c}
@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{fa6,,signal.sigwaitinfo()} and @ref{fa5,,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<93>,Tests<86>,Library<102>,Python 3 5 0 alpha 3
@anchor{whatsnew/changelog id833}@anchor{1e6d}
@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<86>,Tools/Demos<59>,Build<93>,Python 3 5 0 alpha 3
@anchor{whatsnew/changelog id834}@anchor{1e6e}
@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<59>,,Tests<86>,Python 3 5 0 alpha 3
@anchor{whatsnew/changelog id835}@anchor{1e6f}
@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{1e70}
@subsection Python 3.5.0 alpha 2


`Release date: 2015-03-09'

@menu
* Core and Builtins: Core and Builtins<102>. 
* Library: Library<103>. 
* Build: Build<94>. 
* C API: C API<77>. 
* Windows: Windows<80>. 

@end menu

@node Core and Builtins<102>,Library<103>,,Python 3 5 0 alpha 2
@anchor{whatsnew/changelog id836}@anchor{1e71}
@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<103>,Build<94>,Core and Builtins<102>,Python 3 5 0 alpha 2
@anchor{whatsnew/changelog id837}@anchor{1e72}
@subsubsection Library



@itemize -

@item 
bpo-22524@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22524}: New os.scandir() function, part of the 
@geindex Python Enhancement Proposals; PEP 471
PEP 471@footnote{https://peps.python.org/pep-0471/}:
"os.scandir() function -- a better and faster directory iterator". Patch
written by Ben Hoyt.

@item 
bpo-23103@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23103}: Reduced the memory consumption of IPv4Address and IPv6Address.

@item 
bpo-21793@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21793}: BaseHTTPRequestHandler again logs response code as numeric, not
as stringified enum.  Patch by Demian Brecht.

@item 
bpo-23476@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23476}: In the ssl module, enable OpenSSL's X509_V_FLAG_TRUSTED_FIRST
flag on certificate stores when it is available.

@item 
bpo-23576@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23576}: Avoid stalling in SSL reads when EOF has been reached in the
SSL layer but the underlying connection hasn't been closed.

@item 
bpo-23504@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23504}: Added an __all__ to the types module.

@item 
bpo-23563@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23563}: Optimized utility functions in urllib.parse.

@item 
bpo-7830@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7830}: Flatten nested functools.partial.

@item 
bpo-20204@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20204}: Added the __module__ attribute to _tkinter classes.

@item 
bpo-19980@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19980}: Improved help() for non-recognized strings.  help('@w{'}) now shows
the help on str.  help('help') now shows the help on help(). Original
patch by Mark Lawrence.

@item 
bpo-23521@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23521}: Corrected pure python implementation of timedelta division.
Eliminated OverflowError from @code{timedelta * float} for some floats;
Corrected rounding in timedelta true division.

@item 
bpo-21619@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21619}: Popen objects no longer leave a zombie after exit in the with
statement if the pipe was broken.  Patch by Martin Panter.

@item 
bpo-22936@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22936}: Make it possible to show local variables in tracebacks for both
the traceback module and unittest.

@item 
bpo-15955@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15955}: Add an option to limit the output size in bz2.decompress().
Patch by Nikolaus Rath.

@item 
bpo-6639@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6639}: Module-level turtle functions no longer raise TclError after
closing the window.

@item 
bpo-814253@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=814253}: Group references and conditional group references now work in
lookbehind assertions in regular expressions. (See also: bpo-9179@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9179})

@item 
bpo-23215@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23215}: Multibyte codecs with custom error handlers that ignores errors
consumed too much memory and raised SystemError or MemoryError. Original
patch by Aleksi Torhamo.

@item 
bpo-5700@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5700}: io.FileIO() called flush() after closing the file. flush() was
not called in close() if closefd=False.

@item 
bpo-23374@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23374}: Fixed pydoc failure with non-ASCII files when stdout encoding
differs from file system encoding (e.g. on Mac OS).

@item 
bpo-23481@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23481}: Remove RC4 from the SSL module's default cipher list.

@item 
bpo-21548@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21548}: Fix pydoc.synopsis() and pydoc.apropos() on modules with empty
docstrings.

@item 
bpo-22885@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22885}: Fixed arbitrary code execution vulnerability in the dbm.dumb
module. Original patch by Claudiu Popa.

@item 
bpo-23239@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23239}: ssl.match_hostname() now supports matching of IP addresses.

@item 
bpo-23146@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23146}: Fix mishandling of absolute Windows paths with forward slashes
in pathlib.

@item 
bpo-23096@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23096}: Pickle representation of floats with protocol 0 now is the same
for both Python and C implementations.

@item 
bpo-19105@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19105}: pprint now more efficiently uses free space at the right.

@item 
bpo-14910@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14910}: Add allow_abbrev parameter to argparse.ArgumentParser. Patch by
Jonathan Paugh, Steven Bethard, paul j3 and Daniel Eriksson.

@item 
bpo-21717@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21717}: tarfile.open() now supports 'x' (exclusive creation) mode.

@item 
bpo-23344@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23344}: marshal.dumps() is now 20-25% faster on average.

@item 
bpo-20416@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20416}: marshal.dumps() with protocols 3 and 4 is now 40-50% faster on
average.

@item 
bpo-23421@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23421}: Fixed compression in tarfile CLI.  Patch by wdv4758h.

@item 
bpo-23367@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23367}: Fix possible overflows in the unicodedata module.

@item 
bpo-23361@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23361}: Fix possible overflow in Windows subprocess creation code.

@item 
logging.handlers.QueueListener now takes a respect_handler_level keyword
argument which, if set to True, will pass messages to handlers taking
handler levels into account.

@item 
bpo-19705@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19705}: turtledemo now has a visual sorting algorithm demo.  Original
patch from Jason Yeo.

@item 
bpo-23801@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23801}: Fix issue where cgi.FieldStorage did not always ignore the
entire preamble to a multipart body.
@end itemize

@node Build<94>,C API<77>,Library<103>,Python 3 5 0 alpha 2
@anchor{whatsnew/changelog id838}@anchor{1e73}
@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<77>,Windows<80>,Build<94>,Python 3 5 0 alpha 2
@anchor{whatsnew/changelog id839}@anchor{1e74}
@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<80>,,C API<77>,Python 3 5 0 alpha 2
@anchor{whatsnew/changelog id840}@anchor{1e75}
@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{1e76}
@subsection Python 3.5.0 alpha 1


`Release date: 2015-02-08'

@menu
* Core and Builtins: Core and Builtins<103>. 
* Library: Library<104>. 
* IDLE: IDLE<62>. 
* Build: Build<95>. 
* C API: C API<78>. 
* Documentation: Documentation<81>. 
* Tests: Tests<87>. 
* Tools/Demos: Tools/Demos<60>. 
* Windows: Windows<81>. 

@end menu

@node Core and Builtins<103>,Library<104>,,Python 3 5 0 alpha 1
@anchor{whatsnew/changelog id841}@anchor{1e77}
@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<104>,IDLE<62>,Core and Builtins<103>,Python 3 5 0 alpha 1
@anchor{whatsnew/changelog id842}@anchor{1e78}
@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{c77,,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{c4c,,Py_ssize_t()} type instead of
int for the size to support reading more than 2 GB at once. On
Windows, the size is truncated to INT_MAX. As any call to os.read(), the
OS may read less bytes than the number of requested bytes.

@item 
bpo-21942@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21942}: Fixed source file viewing in pydoc's server mode on Windows.

@item 
bpo-11259@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11259}: asynchat.async_chat().set_terminator() now raises a ValueError
if the number of received bytes is negative.

@item 
bpo-12523@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12523}: asynchat.async_chat.push() now raises a TypeError if it doesn't
get a bytes string

@item 
bpo-21707@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21707}: Add missing kwonlyargcount argument to
ModuleFinder.replace_paths_in_code().

@item 
bpo-20639@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20639}: calling Path.with_suffix('@w{'}) allows removing the suffix again.
Patch by July Tikhonov.

@item 
bpo-21714@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21714}: Disallow the construction of invalid paths using
Path.with_name().  Original patch by Antony Lee.

@item 
bpo-15014@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15014}: Added 'auth' method to smtplib to make implementing auth
mechanisms simpler, and used it internally in the login method.

@item 
bpo-21151@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21151}: Fixed a segfault in the winreg module when @code{None} is passed
as a @code{REG_BINARY} value to SetValueEx.  Patch by John Ehresman.

@item 
bpo-21090@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21090}: io.FileIO.readall() does not ignore I/O errors anymore. Before,
it ignored I/O errors if at least the first C call read() succeed.

@item 
bpo-5800@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5800}: headers parameter of wsgiref.headers.Headers is now optional.
Initial patch by Pablo Torres Navarrete and SilentGhost.

@item 
bpo-21781@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21781}: ssl.RAND_add() now supports strings longer than 2 GB.

@item 
bpo-21679@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21679}: Prevent extraneous fstat() calls during open().  Patch by
Bohuslav Kabrda.

@item 
bpo-21863@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21863}: cProfile now displays the module name of C extension functions,
in addition to their own name.

@item 
bpo-11453@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11453}: asyncore: emit a ResourceWarning when an unclosed file_wrapper
object is destroyed. The destructor now closes the file if needed. The
close() method can now be called twice: the second call does nothing.

@item 
bpo-21858@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21858}: Better handling of Python exceptions in the sqlite3 module.

@item 
bpo-21476@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21476}: Make sure the email.parser.BytesParser TextIOWrapper is
discarded after parsing, so the input file isn't unexpectedly closed.

@item 
bpo-20295@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20295}: imghdr now recognizes OpenEXR format images.

@item 
bpo-21729@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21729}: Used the "with" statement in the dbm.dumb module to ensure
files closing. Patch by Claudiu Popa.

@item 
bpo-21491@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21491}: socketserver: Fix a race condition in child processes reaping.

@item 
bpo-21719@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21719}: Added the @code{st_file_attributes} field to os.stat_result on
Windows.

@item 
bpo-21832@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21832}: Require named tuple inputs to be exact strings.

@item 
bpo-21722@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21722}: The distutils "upload" command now exits with a non-zero return
code when uploading fails.  Patch by Martin Dengler.

@item 
bpo-21723@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21723}: asyncio.Queue: support any type of number (ex: float) for the
maximum size. Patch written by Vajrasky Kok.

@item 
bpo-21711@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21711}: support for "site-python" directories has now been removed from
the site module (it was deprecated in 3.4).

@item 
bpo-17552@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17552}: new socket.sendfile() method allowing a file to be sent over a
socket by using high-performance os.sendfile() on UNIX. Patch by Giampaolo
Rodola'.

@item 
bpo-18039@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18039}: dbm.dump.open() now always creates a new database when the flag
has the value 'n'.  Patch by Claudiu Popa.

@item 
bpo-21326@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21326}: Add a new is_closed() method to asyncio.BaseEventLoop.
run_forever() and run_until_complete() methods of asyncio.BaseEventLoop
now raise an exception if the event loop was closed.

@item 
bpo-21766@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21766}: Prevent a security hole in CGIHTTPServer by URL unquoting paths
before checking for a CGI script at that path.

@item 
bpo-21310@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21310}: Fixed possible resource leak in failed open().

@item 
bpo-21256@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21256}: Printout of keyword args should be in deterministic order in a
mock function call. This will help to write better doctests.

@item 
bpo-21677@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21677}: Fixed chaining nonnormalized exceptions in io close() methods.

@item 
bpo-11709@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11709}: Fix the pydoc.help function to not fail when sys.stdin is not a
valid file.

@item 
bpo-21515@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21515}: tempfile.TemporaryFile now uses os.O_TMPFILE flag is available.

@item 
bpo-13223@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13223}: Fix pydoc.writedoc so that the HTML documentation for methods
that use 'self' in the example code is generated correctly.

@item 
bpo-21463@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21463}: In urllib.request, fix pruning of the FTP cache.

@item 
bpo-21618@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21618}: The subprocess module could fail to close open fds that were
inherited by the calling process and already higher than POSIX resource
limits would otherwise allow.  On systems with a functioning /proc/self/fd
or /dev/fd interface the max is now ignored and all fds are closed.

@item 
bpo-20383@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20383}: Introduce importlib.util.module_from_spec() as the preferred
way to create a new module.

@item 
bpo-21552@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21552}: Fixed possible integer overflow of too long string lengths in
the tkinter module on 64-bit platforms.

@item 
bpo-14315@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14315}: The zipfile module now ignores extra fields in the central
directory that are too short to be parsed instead of letting a
struct.unpack error bubble up as this "bad data" appears in many real
world zip files in the wild and is ignored by other zip tools.

@item 
bpo-13742@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13742}: Added "key" and "reverse" parameters to heapq.merge(). (First
draft of patch contributed by Simon Sapin.)

@item 
bpo-21402@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21402}: tkinter.ttk now works when default root window is not set.

@item 
bpo-3015@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3015}: @code{_tkinter.create()} now creates @code{tkapp} object with
@code{wantobjects=1} by default.

@item 
bpo-10203@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10203}: sqlite3.Row now truly supports sequence protocol.  In
particular it supports reverse() and negative indices.  Original patch by
Claudiu Popa.

@item 
bpo-18807@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18807}: If copying (no symlinks) specified for a venv, then the python
interpreter aliases (python, python3) are now created by copying rather
than symlinking.

@item 
bpo-20197@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20197}: Added support for the WebP image type in the imghdr module.
Patch by Fabrice Aneche and Claudiu Popa.

@item 
bpo-21513@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21513}: Speedup some properties of IP addresses (IPv4Address,
IPv6Address) such as .is_private or .is_multicast.

@item 
bpo-21137@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21137}: Improve the repr for threading.Lock() and its variants by
showing the "locked" or "unlocked" status.  Patch by Berker Peksag.

@item 
bpo-21538@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21538}: The plistlib module now supports loading of binary plist files
when reference or offset size is not a power of two.

@item 
bpo-21455@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21455}: Add a default backlog to socket.listen().

@item 
bpo-21525@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21525}: Most Tkinter methods which accepted tuples now accept lists
too.

@item 
bpo-22166@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22166}: With the assistance of a new internal _codecs._forget_codec
helping function, test_codecs now clears the encoding caches to avoid the
appearance of a reference leak

@item 
bpo-22236@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22236}: Tkinter tests now don't reuse default root window.  New root
window is created for every test class.

@item 
bpo-10744@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10744}: Fix 
@geindex Python Enhancement Proposals; PEP 3118
PEP 3118@footnote{https://peps.python.org/pep-3118/} format strings on ctypes objects with a
nontrivial shape.

@item 
bpo-20826@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20826}: Optimize ipaddress.collapse_addresses().

@item 
bpo-21487@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21487}: Optimize ipaddress.summarize_address_range() and
ipaddress.@{IPv4Network,IPv6Network@}.subnets().

@item 
bpo-21486@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21486}: Optimize parsing of netmasks in ipaddress.IPv4Network and
ipaddress.IPv6Network.

@item 
bpo-13916@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13916}: Disallowed the surrogatepass error handler for non UTF-*
encodings.

@item 
bpo-20998@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20998}: Fixed re.fullmatch() of repeated single character pattern with
ignore case. Original patch by Matthew Barnett.

@item 
bpo-21075@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21075}: fileinput.FileInput now reads bytes from standard stream if
binary mode is specified.  Patch by Sam Kimbrel.

@item 
bpo-19775@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19775}: Add a samefile() method to pathlib Path objects.  Initial patch
by Vajrasky Kok.

@item 
bpo-21226@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21226}: Set up modules properly in PyImport_ExecCodeModuleObject (and
friends).

@item 
bpo-21398@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21398}: Fix a unicode error in the pydoc pager when the documentation
contains characters not encodable to the stdout encoding.

@item 
bpo-16531@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16531}: ipaddress.IPv4Network and ipaddress.IPv6Network now accept an
(address, netmask) tuple argument, so as to easily construct network
objects from existing addresses.

@item 
bpo-21156@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21156}: importlib.abc.InspectLoader.source_to_code() is now a
staticmethod.

@item 
bpo-21424@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21424}: Simplified and optimized heaqp.nlargest() and nmsmallest() to
make fewer tuple comparisons.

@item 
bpo-21396@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21396}: Fix TextIOWrapper(..., write_through=True) to not force a
flush() on the underlying binary stream.  Patch by akira.

@item 
bpo-18314@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18314}: Unlink now removes junctions on Windows. Patch by Kim Gräsman

@item 
bpo-21088@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21088}: Bugfix for curses.window.addch() regression in 3.4.0. In
porting to Argument Clinic, the first two arguments were reversed.

@item 
bpo-21407@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21407}: _decimal: The module now supports function signatures.

@item 
bpo-10650@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10650}: Remove the non-standard 'watchexp' parameter from the
Decimal.quantize() method in the Python version.  It had never been
present in the C version.

@item 
bpo-21469@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21469}: Reduced the risk of false positives in robotparser by checking
to make sure that robots.txt has been read or does not exist prior to
returning True in can_fetch().

@item 
bpo-19414@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19414}: Have the OrderedDict mark deleted links as unusable. This gives
an early failure if the link is deleted during iteration.

@item 
bpo-21421@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21421}: Add __slots__ to the MappingViews ABC. Patch by Josh Rosenberg.

@item 
bpo-21101@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21101}: Eliminate double hashing in the C speed-up code for
collections.Counter().

@item 
bpo-21321@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21321}: itertools.islice() now releases the reference to the source
iterator when the slice is exhausted.  Patch by Anton Afanasyev.

@item 
bpo-21057@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21057}: TextIOWrapper now allows the underlying binary stream's read()
or read1() method to return an arbitrary bytes-like object (such as a
memoryview). Patch by Nikolaus Rath.

@item 
bpo-20951@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20951}: SSLSocket.send() now raises either SSLWantReadError or
SSLWantWriteError on a non-blocking socket if the operation would block.
Previously, it would return 0.  Patch by Nikolaus Rath.

@item 
bpo-13248@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13248}: removed previously deprecated asyncore.dispatcher __getattr__
cheap inheritance hack.

@item 
bpo-9815@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9815}: assertRaises now tries to clear references to local variables in
the exception's traceback.

@item 
bpo-19940@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19940}: ssl.cert_time_to_seconds() now interprets the given time string
in the UTC timezone (as specified in RFC 5280), not the local timezone.

@item 
bpo-13204@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13204}: Calling sys.flags.__new__ would crash the interpreter, now it
raises a TypeError.

@item 
bpo-19385@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19385}: Make operations on a closed dbm.dumb database always raise the
same exception.

@item 
bpo-21207@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21207}: Detect when the os.urandom cached fd has been closed or
replaced, and open it anew.

@item 
bpo-21291@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21291}: subprocess's Popen.wait() is now thread safe so that multiple
threads may be calling wait() or poll() on a Popen instance at the same
time without losing the Popen.returncode value.

@item 
bpo-21127@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21127}: Path objects can now be instantiated from str subclass
instances (such as @code{numpy.str_}).

@item 
bpo-15002@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15002}: urllib.response object to use _TemporaryFileWrapper (and
_TemporaryFileCloser) facility. Provides a better way to handle file
descriptor close. Patch contributed by Christian Theune.

@item 
bpo-12220@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12220}: mindom now raises a custom ValueError indicating it doesn't
support spaces in URIs instead of letting a 'split' ValueError bubble up.

@item 
bpo-21068@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21068}: The ssl.PROTOCOL* constants are now enum members.

@item 
bpo-21276@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21276}: posixmodule: Don't define USE_XATTRS on KFreeBSD and the Hurd.

@item 
bpo-21262@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21262}: New method assert_not_called for Mock. It raises AssertionError
if the mock has been called.

@item 
bpo-21238@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21238}: New keyword argument @code{unsafe} to Mock. It raises
@code{AttributeError} 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{6e6,,tempfile.NamedTemporaryFile()}, close the file descriptor if
@ref{739,,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{758,,sys.stdin} and @ref{cc4,,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<62>,Build<95>,Library<104>,Python 3 5 0 alpha 1
@anchor{whatsnew/changelog id843}@anchor{1e79}
@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<95>,C API<78>,IDLE<62>,Python 3 5 0 alpha 1
@anchor{whatsnew/changelog id844}@anchor{1e7a}
@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<78>,Documentation<81>,Build<95>,Python 3 5 0 alpha 1
@anchor{whatsnew/changelog id845}@anchor{1e7b}
@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{dbb,,Py_DecodeLocale()},
rename @code{_Py_wchar2char()} to @ref{dbc,,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<81>,Tests<87>,C API<78>,Python 3 5 0 alpha 1
@anchor{whatsnew/changelog id846}@anchor{1e7c}
@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<87>,Tools/Demos<60>,Documentation<81>,Python 3 5 0 alpha 1
@anchor{whatsnew/changelog id847}@anchor{1e7d}
@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<60>,Windows<81>,Tests<87>,Python 3 5 0 alpha 1
@anchor{whatsnew/changelog id848}@anchor{1e7e}
@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<81>,,Tools/Demos<60>,Python 3 5 0 alpha 1
@anchor{whatsnew/changelog id849}@anchor{1e7f}
@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{1e80}@anchor{tutorial/index the-python-tutorial}@anchor{1e81}@anchor{tutorial/index translation-repo}@anchor{1e82}@anchor{tutorial/index tutorial-index}@anchor{1e83}
@chapter Python 教學


@cartouche
@quotation 小訣竅 
這份教學是為了那些對 Python 語言有興趣的程式設計師而設計的，`不是'對於程式設計`新手'的入門教學。
@end quotation
@end cartouche

Python 是一種易學、功能強大的程式語言。它有高效能的高階資料結構，也有簡單但有效的方法去實現物件導向程式設計。Python 優雅的語法和動態型別，結合其直譯特性，使它成為眾多領域和大多數平臺上，撰寫腳本和快速開發應用程式的理想語言。

使用者可以自由且免費地從 Python 官網上 (@indicateurl{https://www.python.org/}) 取得各大平台上用的 Python 直譯器和標準函式庫，下載其源碼或二進位形式執行檔，同時，也可以將其自由地散佈。另外，Python 官網也提供了許多自由且免費的第三方 Python 模組、程式與工具、以及額外說明文件，有興趣的使用者，可在官網上找到相關的發行版本與連結網址。

使用 C 或 C++（或其他可被 C 呼叫的程式語言），可以很容易在 Python 直譯器內新增功能函式及資料型別。同時，對可讓使用者自製功能的應用程式來說，Python 也適合作為其擴充用介面語言 (extension language)。

這份教學將非常規地介紹 Python 語言與系統的基本概念及功能。請注意，它預期你對程式設計有基本的了解。實際用 Python 直譯器進行實際操作將有助於學習，但所有範例都是獨立完整的，所以這份教學也可以離線閱讀。

若想了解 Python 標準物件和模組的描述，請參閱 @ref{149,,Python 標準函式庫 (Standard Library)}。在 @ref{14a,,Python 語言參考手冊} 中，你可以學到 Python 語言更正規的定義。想用 C 或 C++ 寫延伸套件 (extensions) 的讀者，請閱讀 @ref{1e84,,擴充和嵌入 Python 直譯器} 和 @ref{1e85,,Python/C API 參考手冊} 。此外，市面上也能找到更深入的 Python 學習書。

這份教學中，我們不會介紹每一個功能，甚至，也不打算介紹完每一個常用功能。取而代之，我們的重心將放在介紹 Python 中最值得一提的那些功能，幫助你了解 Python 語言的特色與風格。讀完教學後，你將有能力閱讀和撰寫 Python 模組與程式，也做好進一步學習 @ref{149,,Python 標準函式庫 (Standard Library)} 中各類型的 Python 函式庫模組的準備。

@ref{1e86,,術語表} 頁面也值得細讀。

@menu
* 淺嘗滋味:: 
* 使用 Python 直譯器:: 
* 一個非正式的 Python 簡介:: 
* 深入了解流程控制:: 
* 資料結構:: 
* 模組 (Module): 模組 Module. 
* 輸入和輸出:: 
* 錯誤和例外:: 
* Class（類別）:: 
* Python 標準函式庫概覽:: 
* Python 標準函式庫概覽——第二部份:: 
* 虛擬環境與套件:: 
* 現在可以來學習些什麼？:: 
* 互動式輸入編輯和歷史記錄替換:: 
* 浮點數運算：問題與限制:: 
* 附錄:: 

@end menu

@node 淺嘗滋味,使用 Python 直譯器,,Python 教學
@anchor{tutorial/appetite doc}@anchor{1e87}@anchor{tutorial/appetite tut-intro}@anchor{1e88}@anchor{tutorial/appetite whetting-your-appetite}@anchor{1e89}
@section 淺嘗滋味


如果你經常在電腦上工作，最終總能發現有些工作你會想要自動化。舉例來說，你會想在很多文字檔案裡做相同的搜尋取代，或者是用個複雜的規則重新命名或整理一群照片。也有可能你想寫個自己的小資料庫，一個專門的 GUI 應用程式，或一個小遊戲。

如果你是一個職業軟體開發者，你可能要操作數個 C/C++/Java 程式庫，卻覺得平常寫程式碼、編譯、測試、再編譯的流程太慢；有可能你正為了一個程式庫撰寫一套測試集，但發現寫測試單調乏味；也有可能你正在開發一個能使用某一語言擴充的程式，但並不想要為了這程式特別設計一個全新的擴充語言。

在上述的例子中，Python 正是你合適的語言。

也許你可以為了某些任務而寫個 Unix shell 腳本或者 Windows 批次檔來處理，但 shell 腳本最適合於搬動檔案或更動文字內容，而不適於圖形應用程式或遊戲。你可以為此寫個 C/C++/Java 程式，但僅僅是完成個草稿也需要很長的開發時間。相較而言，Python 更易於使用，並能在 Windows、macOS、Unix 作業系統上執行，且能更快速地幫助你完成工作。

Python 即便易用也是個貨真價實的程式語言。它提供比 shell 腳本、批次檔更多樣的程式架構與更多的支援。另一方面，Python 提供比 C 更豐富的錯語檢查。相較於 C，Python 作為一個「非常高階的程式語言」，它內建了高階的資料型別如彈性的數列與字典。因為這些多用途的資料型別，Python 適用解決比 Awk（甚至是 Perl）能處理的更多問題上。至少在許多事情中，使用 Python 處理起來跟其他語言是同樣容易的。

Python 允許你把程式切割成許多模組 (module) 並將他們重覆運用至其他 Python 程式中。Python 自帶了一個很大集合的標準模組，它們能做為你程式的基礎——或把它們當作一開始學寫 Python 程式的範例。有些模組提供了如檔案 I/O、系統呼叫、socket 的功能，甚至提供了 Tk 等圖形介面工具庫 (GUI toolkit) 的介面。

Python 是個直譯式語言，因為不需要編譯與連結，能為你在開發過程中省下可觀的時間。它的直譯器能互動地使用，因此能很方便地實驗每個語言的功能、寫些用完即丟的程式、幫助測試一些從細部開始開發的函式。它也是個好用的計算機。

Python 讓程式寫得精簡並易讀。用 Python 實作的程式長度往往遠比用 C、C++、Java 實作的短。這有以下幾個原因：


@itemize *

@item 
Python 高階的資料型別能在一陳述式 (statement) 中表達很複雜的操作；

@item 
陳述式的段落以縮排為區隔而非括號；

@item 
不需要宣告變數和引數。
@end itemize

Python 是`可擴充的'：如果你會寫 C 程式，那麼要加個新的內建函式或模組到直譯器中是很容易的。無論是為了用最快速的執行速度完成一些關鍵的操作，或是讓 Python 連結到一些僅以二進位形式 (binary form) 釋出的程式庫（例如特定供應商的繪圖程式庫）。如果你想更多這樣的結合，你其實也可以把 Python 直譯器連結到用 C 寫的應用程式，並在該應用程式中使用 Python 寫擴充或者作為下達指令的語言。

順帶一提，這個語言是以 BBC 的戲劇《Monty Python's Flying Circus》命名，與爬蟲類完全沒有關係。在說明文件中引用他們的喜劇不但沒問題，這甚至是個被鼓勵的行為！

如果你現在已經躍躍欲試，你會想了解 Python 更多細節，而學習語言的最好方式就是直接使用它。接下來這個教學就將帶領你，一邊閱讀，一邊將所學用在 Python 直譯器中玩耍。

在下個章節中，將會解說如何使用該直譯器。這也許只是個普通的資訊，但你必須試著操作接下來呈現的範例。

接下來的教學裡，將會透過許多範例介紹 Python 語言與其系統的諸多特色。一開始是簡單的運算式 (expression)、陳述式 (statement) 和資料型別 (data type)；接著是函式 (function) 與模組 (module)；最後會接觸一些較進階的主題如例外 (exception) 與使用者自定義類別 (class)。

@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 教學
@anchor{tutorial/interpreter doc}@anchor{1e8a}@anchor{tutorial/interpreter translation-repo}@anchor{1e8b}@anchor{tutorial/interpreter tut-using}@anchor{1e8c}@anchor{tutorial/interpreter using-the-python-interpreter}@anchor{1e8d}
@section 使用 Python 直譯器


@menu
* 啟動直譯器:: 
* 直譯器與它的環境:: 

@end menu

@node 啟動直譯器,直譯器與它的環境,,使用 Python 直譯器
@anchor{tutorial/interpreter invoking-the-interpreter}@anchor{1e8e}@anchor{tutorial/interpreter tut-invoking}@anchor{1e8f}
@subsection 啟動直譯器


在有安裝的機器上 Python 直譯器通常是被安裝在 @code{/usr/local/bin/python3.14}；把 @code{/usr/local/bin} 放在 Unix shell 的搜尋路徑中就可以透過輸入指令來啟動它：

@example
python3.14
@end example

能啟動 Python @footnote{
在 Unix 中，Python 3.x 直譯器預設安裝不會以 @code{python} 作為執行檔名稱，以避免與現有的 Python 2.x 執行檔名稱衝突。
}。因為直譯器存放的目錄是個安裝選項，其他的目錄也是有可能的；請洽談在地的 Python 達人或者系統管理員。（例如：@code{/usr/local/python} 是個很常見的另類存放路徑。）

Windows 系統中，從 @ref{1e90,,Microsoft Store} 安裝 Python 後，就可以使用 @code{python3.14} 命令了。如果安裝了 @ref{7d3,,py.exe launcher} ，則可以使用 @code{py} 命令。請參閱 @ref{1e91,,Python 安裝管理員} 了解其他啟動 Python 的方式。

在主提示符輸入一個 end-of-file 字元（在 Unix 上為 @code{Control}-@code{D}；在 Windows 上為 @code{Control}-@code{Z}）會使得直譯器以零退出狀況 (zero exit status) 離開。如果上述的做法沒有效，也可以輸入指令 @code{quit()} 離開直譯器。

直譯器的指令列編輯功能有很多，在支援 GNU Readline@footnote{https://tiswww.case.edu/php/chet/readline/rltop.html} 函式庫的系統上包含：互動編輯、歷史取代、指令補完等功能。最快檢查有無支援指令列編輯的方法為：在第一個 Python 提示符後輸入 @code{Control}-@code{P}，如果出現嗶嗶聲，就代表有支援；見附錄@ref{1e92,,互動式輸入編輯和歷史記錄替換}介紹相關的快速鍵。如果什麼事都沒有發生，或者出現一個 @code{^P}，就代表並沒有指令列編輯功能；此時只能使用 backspace 去除該行的字元。

這個直譯器使用起來像是 Unix shell：如果它被呼叫時連結至一個 tty 裝置，它會互動式地讀取並執行指令；如果被呼叫時給定檔名為引數或者使用 stdin 傳入檔案內容，它會將這個檔案視為`腳本'來閱讀。

另一個啟動直譯器的方式為 @code{python -c command [arg] ...}，它會執行在 `command' 裡的指令（們），行為如同 shell 的 @ref{1a8,,-c} 選項。因為 Python 的指令包含空白等 shell 用到的特殊字元，通常建議用引號把 `command' 包起來。

有些 Python 模組使用上如腳本般一樣方便。透過 @code{python -m module [arg] ...} 可以執行 `module' 模組的原始碼，就如同直接傳入那個模組的完整路徑一樣的行為。

當要執行一個腳本檔時，有時候會希望在腳本結束時進入互動模式。此時可在執行腳本的指令加入 @ref{16cf,,-i}。

所有指令可用的參數都詳記在@ref{1c70,,命令列與環境}。

@menu
* 傳遞引數:: 
* 互動模式:: 

@end menu

@node 傳遞引數,互動模式,,啟動直譯器
@anchor{tutorial/interpreter argument-passing}@anchor{1e93}@anchor{tutorial/interpreter tut-argpassing}@anchor{1e94}
@subsubsection 傳遞引數


當直擇器收到腳本的名稱和額外的引數後，他們會轉換為由字串所組成的 list（串列）並指派給 @code{sys} 模組的 @code{argv} 變數。你可以執行 @code{import sys} 取得這個串列。這個串列的長度至少為一；當沒有給任何腳本名稱和引數時， @code{sys.argv[0]} 為空字串。當腳本名為 @code{'-'}（指標準輸入）時， @code{sys.argv[0]} 為 @code{'-'}。當使用 @ref{1a8,,-c} `command' 時， @code{sys.argv[0]} 為 @code{'-c'}。當使用 @ref{23c,,-m} `module' 時， @code{sys.argv[0]} 為該模組存在的完整路徑。其餘非 @ref{1a8,,-c} `command' 或 @ref{23c,,-m} `module' 的選項不會被 Python 直譯器吸收掉，而是留在 @code{sys.argv} 變數中給後續的 command 或 module 使用。

@node 互動模式,,傳遞引數,啟動直譯器
@anchor{tutorial/interpreter interactive-mode}@anchor{1e95}@anchor{tutorial/interpreter tut-interactive}@anchor{441}
@subsubsection 互動模式


在終端 (tty) 輸入並執行指令時，直譯器在`互動模式（interactive mode）'中運行。在這種模式中，會顯示`主提示符'，提示輸入下一條指令，主提示符通常用三個大於號（@code{>>>}）表示；輸入連續行時，顯示`次要提示符'，預設是三個點（@code{...}）。進入直譯器時，首先顯示歡迎訊息、版本訊息、版權聲明，然後才是提示符：

@example
$ python3.14
Python 3.14 (default, April 4 2024, 09:25:04)
[GCC 10.2.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>>
@end example

@c XXX update for new releases

接續多行的情況出現在需要多行才能建立完整指令時。舉例來說，像是 @ref{181,,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

更多有關互動模式的使用，請見@ref{48f,,互動模式}。

@node 直譯器與它的環境,,啟動直譯器,使用 Python 直譯器
@anchor{tutorial/interpreter the-interpreter-and-its-environment}@anchor{1e96}@anchor{tutorial/interpreter tut-interp}@anchor{1e97}
@subsection 直譯器與它的環境


@menu
* 原始碼的字元編碼 (encoding): 原始碼的字元編碼 encoding. 

@end menu

@node 原始碼的字元編碼 encoding,,,直譯器與它的環境
@anchor{tutorial/interpreter source-code-encoding}@anchor{1e98}@anchor{tutorial/interpreter tut-source-encoding}@anchor{1e99}
@subsubsection 原始碼的字元編碼 (encoding)


預設 Python 原始碼檔案的字元編碼使用 UTF-8。在這個編碼中，世界上多數語言的文字可以同時被使用在字串內容、識別名 (identifier) 及註解中 --- 雖然在標準函式庫中只使用 ASCII 字元作為識別名，這也是個任何 portable 程式碼需遵守的慣例。如果要正確地顯示所有字元，你的編輯器需要能夠認識檔案為 UTF-8，並且需要能顯示檔案中所有字元的字型。

如果不使用預設編碼，則要聲明檔案的編碼，檔案的`第一'行要寫成特殊註解。語法如下：

@example
# -*- coding: encoding -*-
@end example

其中， `encoding' 可以是 Python 支援的任意一種 @ref{1c,,codecs}。

比如，聲明使用 Windows-1252 編碼，源碼檔案要寫成：

@example
# -*- coding: cp1252 -*-
@end example

`第一行'的規則也有一種例外情況，在源碼以 @ref{1e9a,,UNIX "shebang" line} 行開頭時。此時，編碼聲明要寫在檔案的第二行。例如：

@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 簡介,深入了解流程控制,使用 Python 直譯器,Python 教學
@anchor{tutorial/introduction doc}@anchor{1e9b}@anchor{tutorial/introduction an-informal-introduction-to-python}@anchor{1e9c}@anchor{tutorial/introduction translation-repo}@anchor{1e9d}@anchor{tutorial/introduction tut-informal}@anchor{1e9e}
@section 一個非正式的 Python 簡介


在下面的例子中，輸入與輸出的區別在於有無提示字元（prompt，@ref{48d,,>>>} 和 @ref{48e,,...}）：如果要重做範例，你必須在提示字元出現的時候，輸入提示字元後方的所有內容；那些非提示字元開始的文字行是直譯器的輸出。注意到在範例中，若出現單行只有次提示字元時，代表該行你必須直接換行；這被使用在多行指令結束輸入時。


@geindex # (hash);comment（註解）

在本手冊中的許多範例中，即便他們為互動式地輸入，仍然包含註解。Python 中的註解 (comments) 由 hash 字元 @code{#} 開始一直到該行結束。註解可以從該行之首、空白後、或程式碼之後開始，但不會出現在字串文本 (string literal) 之中。hash 字元在字串文本之中時仍視為一 hash 字元。因為註解只是用來說明程式而不會被 Python 解讀，在練習範例時不一定要輸入。

一些範例如下：

@example
# 這是第一個註解
spam = 1  # 這是第二個註解
          # ... 現在是第三個！
text = "# 這不是註解，因為它在引號內。"
@end example

@menu
* 把 Python 當作計算機使用:: 
* 初探程式設計的前幾步:: 

@end menu

@node 把 Python 當作計算機使用,初探程式設計的前幾步,,一個非正式的 Python 簡介
@anchor{tutorial/introduction tut-calculator}@anchor{1e9f}@anchor{tutorial/introduction using-python-as-a-calculator}@anchor{1ea0}
@subsection 把 Python 當作計算機使用


讓我們來試試一些簡單的 Python 指令。啟動直譯器並等待第一個主提示字元 @code{>>>} 出現。（應該不會等太久）

@menu
* 數字 (Number): 數字 Number. 
* 文字:: 
* List（串列）:: 

@end menu

@node 數字 Number,文字,,把 Python 當作計算機使用
@anchor{tutorial/introduction numbers}@anchor{1ea1}@anchor{tutorial/introduction tut-numbers}@anchor{1ea2}
@subsubsection 數字 (Number)


直譯器如同一台簡單的計算機：你可以輸入一個 expression（運算式），它會寫出該式的值。Expression 的語法可以使用：運算子 @code{+}、@code{-}、@code{*} 和 @code{/} 可以用來執行運算；括號 @code{()} 可以用來分群。例如：

@example
>>> 2 + 2
4
>>> 50 - 5*6
20
>>> (50 - 5*6) / 4
5.0
>>> 8 / 5  # 除法總是回傳浮點數
1.6
@end example

整數數字（即 @code{2}、@code{4}、@code{20}）為 @ref{19b,,int} 型態，數字有小數點部份的（即 @code{5.0}、@code{1.6}）為 @ref{196,,float} 型態。我們將在之後的教學中看到更多數字相關的型態。

除法 (@code{/}) 永遠回傳一個 float。如果要做 @ref{b35,,floor division} 並拿到整數的結果，你可以使用 @code{//} 運算子；計算餘數可以使用 @code{%}：

@example
>>> 17 / 3  # 傳統除法回傳浮點數
5.666666666666667
>>>
>>> 17 // 3  # 下取整除法捨棄小數部分
5
>>> 17 % 3  # % 運算子回傳除法的餘數
2
>>> 5 * 3 + 2  # 下取整商 * 除數 + 餘數
17
@end example

在 Python 中，計算冪次 (powers) 可以使用 @code{**} 運算子 @footnote{
因為 @code{**} 擁有較 @code{-} 高的優先次序，@code{-3**2} 會被解釋為 @code{-(3**2)} 並得到 @code{-9}。如果要避免這樣的優先順序以得到 @code{9}，你可以使用 @code{(-3)**2}。
}：

@example
>>> 5 ** 2  # 5 的平方
25
>>> 2 ** 7  # 2 的 7 次方
128
@end example

等於符號 (@code{=}) 可以用於為變數賦值。賦值完之後，在下個指示字元前並不會顯示任何結果：

@example
>>> width = 20
>>> height = 5 * 9
>>> width * height
900
@end example

如果一個變數未被「定義 (defined)」（即變數未被賦值），試著使用它時會出現一個錯誤：

@example
>>> n  # 嘗試存取未定義的變數
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
NameError: name 'n' is not defined
@end example

浮點數的運算有完善的支援，運算子 (operator) 遇上混合的運算元 (operand) 時會把整數的運算元轉換為浮點數：

@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{19b,,int} 和 @ref{196,,float}，Python 還支援了其他的數字型態，包含 @ref{1fe,,Decimal} 和 @ref{213,,Fraction}。Python 亦內建支援@ref{1ea3,,複數 (complex numbers)}，並使用 @code{j} 和 @code{J} 後綴來指定虛數的部份（即 @code{3+5j}）。

@node 文字,List（串列）,數字 Number,把 Python 當作計算機使用
@anchor{tutorial/introduction text}@anchor{1ea4}@anchor{tutorial/introduction tut-strings}@anchor{1ea5}
@subsubsection 文字


Python 可以操作文本（由 @ref{169,,str} 型別表示，即所謂的「字串 (strings)」）和數字。這包括字元 "@code{!}"、單詞 "@code{rabbit}"、名稱 "@code{Paris}"、句子 "@code{Got your back.}" 等等。"@code{Yay! :)}"。它們可以用單引號 (@code{'...'}) 或雙引號 (@code{"..."}) 括起來，會具有相同的結果 @footnote{
不像其他語言，特殊符號如 @code{\n} 在單 (@code{'...'}) 和雙 (@code{"..."}) 引號中有相同的意思。兩種引號的唯一差別，在於使用單引號時，不需要跳脫 @code{"}（但必須跳脫 @code{\'}），反之亦同。
}。

@example
>>> 'spam eggs'  # 單引號
'spam eggs'
>>> "Paris rabbit got your back :)! Yay!"  # 雙引號
'Paris rabbit got your back :)! Yay!'
>>> '1975'  # 以引號包含的數字和數值也是字串
'1975'
@end example

要引用引文，我們需要在其前面加上 @code{\} 來「跳脫」它。或者我們也可以使用其他種類的引號：

@example
>>> 'doesn\'t'  # 用 \' 來跳脫單引號...
"doesn't"
>>> "doesn't"  # ...或改用雙引號
"doesn't"
>>> '"Yes," they said.'
'"Yes," they said.'
>>> "\"Yes,\" they said."
'"Yes," they said.'
>>> '"Isn\'t," they said.'
'"Isn\'t," they said.'
@end example

在 Python shell 中，字串定義和輸出字串可能看起來不同。@ref{1170,,print()} 函式透過省略引號並印出跳脫字元和特殊字元來生成更具可讀性的輸出：

@example
>>> s = 'First line.\nSecond line.'  # \n 表示換行
>>> s  # 沒有 print()，特殊字元會包含在字串中
'First line.\nSecond line.'
>>> print(s)  # 有 print()，特殊字元會被直譯，所以 \n 會產生新的一行
First line.
Second line.
@end example

如果你不希望字元前出現 @code{\} 就被當成特殊字元時，可以改使用 `raw string'，在第一個包圍引號前加上 @code{r} ：

@example
>>> print('C:\some\name')  # 這裡 \n 表示換行！
C:\some
ame
>>> print(r'C:\some\name')  # 注意引號前的 r
C:\some\name
@end example

原始字串有一個微妙的地方：原始字串可能不會以奇數個 @code{\} 字元結尾；請參閱@ref{1ea6,,常見問答集}來了解更多資訊和解決方法。

字串文本可以跨越數行。其中一方式是使用三個重覆引號：@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{+} 運算子連接 (concatenate)，並用 @code{*} 重覆該字串的內容：

@example
>>> # 3 次 'un'，接著是 'ium'
>>> 3 * 'un' + 'ium'
'unununium'
@end example

兩個以上相鄰的字串文本（`string literal'，即被引號包圍的字串）會被自動連接起來：

@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'  # 無法串接變數和字串字面值
  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

字串可以被「索引 `indexed'」(下標，即 subscripted)，第一個字元的索引值為 0。沒有獨立表示字元的型別；一個字元就是一個大小為 1 的字串：

@example
>>> word = 'Python'
>>> word[0]  # 位置 0 的字元
'P'
>>> word[5]  # 位置 5 的字元
'n'
@end example

索引值可以是負的，此時改成從右開始計數：

@example
>>> word[-1]  # 最後一個字元
'n'
>>> word[-2]  # 倒數第二個字元
'o'
>>> word[-6]
'P'
@end example

注意到因為 -0 等同於 0，負的索引值由 -1 開始。

除了索引外，字串亦支援「切片 `slicing'」。索引用來拿到單獨的字元，而切片則可以讓你拿到一個子字串 (substring)：

@example
>>> word[0:2]  # 從位置 0 (包含) 到 2 (不包含) 的字元
'Py'
>>> word[2:5]  # 從位置 2 (包含) 到 5 (不包含) 的字元
'tho'
@end example

切片索引 (slice indices) 有很常用的預設值，省略起點索引值時預設為 0，而省略第二個索引值時預設整個字串被包含在 slice 中：

@example
>>> word[:2]   # 從開頭到位置 2 (不包含) 的字元
'Py'
>>> word[4:]   # 從位置 4 (包含) 到結尾的字元
'on'
>>> word[-2:]  # 從倒數第二個 (包含) 到結尾的字元
'on'
@end example

注意到起點永遠被包含，而結尾永遠不被包含。這確保了 @code{s[:i] + s[i:]} 永遠等於 @code{s}：

@example
>>> word[:2] + word[2:]
'Python'
>>> word[:4] + word[4:]
'Python'
@end example

這裡有個簡單記住 slice 是如何運作的方式。想像 slice 的索引值指著字元們之間，其中第一個字元的左側邊緣由 0 計數。則 `n' 個字元的字串中最後一個字元的右側邊緣會有索引值 `n'，例如：

@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' 的 slice 包含了標示 `i' 和 `j' 邊緣間的所有字元。

對非負數的索引值而言，一個 slice 的長度等於其索引值之差，如果索引值落在字串邊界內。例如，@code{word[1:3]} 的長度是 2。

嘗試使用一個過大的索引值會造成錯誤：

@example
>>> word[42]  # 這只有六個字母
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
IndexError: string index out of range
@end example

然而，超出範圍的索引值在 slice 中會被妥善的處理：

@example
>>> word[4:42]
'on'
>>> word[42:]
'@w{'}
@end example

Python 字串無法被改變 --- 它們是 @ref{1ea7,,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{839,,len()} 回傳一個字串的長度：

@example
>>> s = 'supercalifragilisticexpialidocious'
>>> len(s)
34
@end example


@subsubheading 也參考



@table @asis

@item @ref{1ea8,,Text Sequence Type --- str}

字串是 `sequence 型別'的範例之一，並支援該型別常用的操作。

@item @ref{1ea9,,字串方法}

字串支援非常多種基本轉換和搜尋的 method（方法）。

@item @ref{19a,,f-string（f 字串）}

包含有運算式的字串文本。

@item @ref{1593,,格式化文字語法}

關於透過 @ref{82c,,str.format()} 字串格式化 (string formatting) 的資訊。

@item @ref{8d3,,printf-style String Formatting}

在字串為 @code{%} 運算子的左運算元時，將觸發舊的字串格式化操作，更多的細節在本連結中介紹。
@end table


@node List（串列）,,文字,把 Python 當作計算機使用
@anchor{tutorial/introduction lists}@anchor{1eaa}@anchor{tutorial/introduction tut-lists}@anchor{1eab}
@subsubsection List（串列）


Python 理解數種複合型資料型別，用來組合不同的數值。當中最多樣變化的型別為 `list'，可以寫成一系列以逗號分隔的數值（稱之元素，即 item），包含在方括號之中。List 可以包合不同型別的元素，但通常這些元素會有相同的型別：

@example
>>> squares = [1, 4, 9, 16, 25]
>>> squares
[1, 4, 9, 16, 25]
@end example

如同字串（以及其他內建的 @ref{70f,,sequence} 型別），list 可以被索引和切片 (slice)：

@example
>>> squares[0]  # 索引回傳項目
1
>>> squares[-1]
25
>>> squares[-3:]  # 切片回傳新串列
[9, 16, 25]
@end example

List 對支援如接合 (concatenation) 等操作：

@example
>>> squares + [36, 49, 64, 81, 100]
[1, 4, 9, 16, 25, 36, 49, 64, 81, 100]
@end example

不同於字串是 @ref{1ea7,,immutable}，list 是 @ref{1eac,,mutable} 型別，即改變 list 的內容是可能的：

@example
>>> cubes = [1, 8, 27, 65, 125]  # 這裡有問題
>>> 4 ** 3  # 4 的立方是 64，不是 65！
64
>>> cubes[3] = 64  # 替換錯誤的值
>>> cubes
[1, 8, 27, 64, 125]
@end example

你也可以在 list 的最後加入新元素，透過使用 @ref{8d4,,list.append()} `方法'（我們稍後會看到更多方法的說明）：

@example
>>> cubes.append(216)  # 加入 6 的立方
>>> cubes.append(7 ** 3)  # 以及 7 的立方
>>> cubes
[1, 8, 27, 64, 125, 216, 343]
@end example

Python 中的簡單賦值永遠不會複製資料。當你將 list 指派給變數時，該變數會參照`現有 list'。任何透過一個變數對 list 所做的更改都將能夠透過參照該變數的所有其他變數看到。

@example
>>> rgb = ["Red", "Green", "Blue"]
>>> rgba = rgb
>>> id(rgb) == id(rgba)  # 它們參照到同一物件
True
>>> rgba.append("Alph")
>>> rgb
["Red", "Green", "Blue", "Alph"]
@end example

所有切片操作都會回傳一個新的 list ，包含要求的元素。這意謂著以下這個切片回傳了原本 list 的@ref{1ead,,淺複製}：

@example
>>> correct_rgba = rgba[:]
>>> correct_rgba[-1] = "Alpha"
>>> correct_rgba
["Red", "Green", "Blue", "Alpha"]
>>> rgba
["Red", "Green", "Blue", "Alph"]
@end example

也可以對 slice 賦值，這能改變 list 的大小，甚至是清空一個 list：

@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']
>>> # 透過將所有元素替換為空串列的方式來清空串列
>>> letters[:] = []
>>> letters
[]
@end example

內建的函式 @ref{839,,len()} 亦可以作用在 list 上：

@example
>>> letters = ['a', 'b', 'c', 'd']
>>> len(letters)
4
@end example

也可以嵌套多層 list （建立 list 包含其他 list），例如：

@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{1eae}@anchor{tutorial/introduction tut-firststeps}@anchor{1eaf}
@subsection 初探程式設計的前幾步


當然，我們可以用 Python 來處理比 2 加 2 更複雜的工作。例如，我們可以印出費氏數列@footnote{https://zh.wikipedia.org/zh-tw/%E6%96%90%E6%B3%A2%E9%82%A3%E5%A5%91%E6%95%B0%E5%88%97}的首幾項序列：

@example
>>> # 費波那契數列
>>> # 以兩個元素的和來決定下一個元素
>>> 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。在最後一行同樣的賦值再被使用了一次，示範了等號的右項運算 (expression) 會先被計算 (evaluate)，賦值再發生。右項的運算式由左至右依序被計算。

@item 
@ref{18d6,,while} 迴圈只要它的條件為真（此範例：@code{a < 10}），將會一直重覆執行。在 Python 中如同 C 語言，任何非零的整數值為真 (true)；零為假 (false)。條件可以是字串、list、甚至是任何序列型別；任何非零長度的序列為真，空的序列即為假。本例子使用的條件是個簡單的比較。標準的比較運算子 (comparison operators) 使用如同 C 語言一樣的符號：@code{<}（小於）、@code{>}（大於）、@code{==}（等於）、@code{<=}（小於等於）、@code{>=}（大於等於）以及 @code{!=}（不等於）。

@item 
迴圈的主體會`縮排'：縮排在 Python 中用來關連一群陳述式。在互動式提示字元中，你必須在迴圈內的每一行一開始鍵入 tab 或者（數個）空白來維持縮排。實務上，你會先在文字編輯器中準備好比較複雜的輸入；多數編輯器都有自動縮排的功能。當一個複合陳述式以互動地方式輸入，必須在結束時多加一行空行來代表結束（因為語法剖析器無法判斷你何時輸入複合陳述的最後一行）。注意在一個縮排段落內的縮排方式與數量必須維持一致。

@item 
@ref{1170,,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{1eb0}@anchor{tutorial/controlflow more-control-flow-tools}@anchor{1eb1}@anchor{tutorial/controlflow translation-repo}@anchor{1eb2}@anchor{tutorial/controlflow tut-morecontrol}@anchor{1eb3}
@section 深入了解流程控制


除了剛才介紹的 @ref{18d6,,while}，這章節還會介紹一些 Python 的陳述式語法。

@menu
* if 陳述式:: 
* for 陳述式:: 
* range() 函式: range 函式. 
* break 和 continue 陳述式:: 
* 迴圈的 else 子句:: 
* pass 陳述式:: 
* match 陳述式:: 
* 定義函式 (function): 定義函式 function. 
* 深入了解函式定義:: 
* 間奏曲：程式碼風格 (Coding Style): 間奏曲：程式碼風格 Coding Style. 

@end menu

@node if 陳述式,for 陳述式,,深入了解流程控制
@anchor{tutorial/controlflow if-statements}@anchor{1eb4}@anchor{tutorial/controlflow tut-if}@anchor{1eb5}
@subsection @code{if} 陳述式


或許最常見的陳述式種類就是 @ref{181,,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{17b,,elif} 敘述，且 @ref{17c,,else} 敘述並不是必要的。關鍵字 @code{elif} 是「else if」的縮寫，用來避免過多的縮排。一個 @code{if} ... @code{elif} ... @code{elif} ... 序列可以用來替代其他程式語言中的 @code{switch} 或 @code{case} 陳述式。

如果你要將同一個值與多個常數進行比較，或者檢查特定的型別或屬性，你可能會發現 @code{match} 陳述式也很有用。更多的細節，請參閱 @ref{1eb6,,match 陳述式}。

@node for 陳述式,range 函式,if 陳述式,深入了解流程控制
@anchor{tutorial/controlflow for-statements}@anchor{1eb7}@anchor{tutorial/controlflow tut-for}@anchor{1eb8}
@subsection @code{for} 陳述式


@geindex statement（陳述式）;for

在 Python 中的 @ref{348,,for} 陳述式有點不同於在 C 或 Pascal 中的慣用方式。相較於只能疊代 (iterate) 一個等差數列（如 Pascal），或給予使用者定義疊代步驟與終止條件（如 C），Python 的 @code{for} 陳述式疊代任何序列（list 或者字串）的元素，順序與它們出現在序列中的順序相同。例如（無意雙關）：

@c One suggestion was to give a real C example here, but that may only serve to
@c confuse non-C programmers.

@example
>>> # 測量一些字串：
>>> words = ['cat', 'window', 'defenestrate']
>>> for w in words:
...     print(w, len(w))
...
cat 3
window 6
defenestrate 12
@end example

在疊代一個集合的同時修改該集合的內容，很難取得想要的結果。比較直觀的替代方式，是疊代該集合的副本，或建立一個新的集合：

@example
# 建立一個範例集合
users = @{'Hans': 'active', 'Éléonore': 'inactive', '景太郎': 'active'@}

# 策略：對副本進行疊代
for user, status in users.copy().items():
    if status == 'inactive':
        del users[user]

# 策略：建立一個新集合
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{1eb9}@anchor{tutorial/controlflow tut-range}@anchor{1eba}
@subsection @code{range()} 函式


如果你需要疊代一個數列的話，使用內建 @ref{b34,,range()} 函式就很方便。它可以生成一等差數列：

@example
>>> for i in range(5):
...     print(i)
...
0
1
2
3
4
@end example

給定的結束值永遠不會出現在生成的序列中；@code{range(10)} 生成的 10 個數值，即對應存取一個長度為 10 的序列內每一個項目的索引值。也可以讓 range 從其他數值開始計數，或者給定不同的公差（甚至為負；有時稱之為 step）：

@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

欲疊代一個序列的索引值，你可以搭配使用 @ref{b34,,range()} 和 @ref{839,,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{1675,,enumerate()} 函式將更為方便，詳見@ref{1ebb,,迴圈技巧}。

如果直接印出一個 range 則會出現奇怪的輸出：

@example
>>> range(10)
range(0, 10)
@end example

在很多情況下，由 @ref{b34,,range()} 回傳的物件表現得像是一個 list（串列）一樣，但實際上它並不是。它是一個在疊代時能夠回傳所要求的序列中所有項目的物件，但它不會真正建出這個序列的 list，以節省空間。

我們稱這樣的物件為 @ref{1428,,iterable}（可疊代物件），意即能作為函式及架構中可以一直取得項目直到取盡的對象。我們已經了解 @ref{348,,for} 陳述式就是如此的架構，另一個使用 iterable 的函式範例是 @ref{68e,,sum()}：

@example
>>> sum(range(4))  # 0 + 1 + 2 + 3
6
@end example

待會我們可以看到更多回傳 iterable 和使用 iterable 為引數的函式。在@ref{1ebc,,資料結構}章節中，我們會討論更多關於 @ref{24d,,list()} 的細節。

@node break 和 continue 陳述式,迴圈的 else 子句,range 函式,深入了解流程控制
@anchor{tutorial/controlflow break-and-continue-statements}@anchor{1ebd}@anchor{tutorial/controlflow tut-break}@anchor{1ebe}
@subsection @code{break} 和 @code{continue} 陳述式


@ref{17f,,break} 陳述式，終止包含它的最內部 @ref{348,,for} 或 @ref{18d6,,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{180,,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{1ebf}
@node 迴圈的 else 子句,pass 陳述式,break 和 continue 陳述式,深入了解流程控制
@anchor{tutorial/controlflow break-and-continue-statements-and-else-clauses-on-loops}@anchor{1ec0}@anchor{tutorial/controlflow else-clauses-on-loops}@anchor{1ec1}
@subsection 迴圈的 @code{else} 子句


在 @code{for} 或 @code{while} 迴圈中，@code{break} 陳述句可能與 @code{else} 子句配對。如果迴圈完成而沒有執行 @code{break}，@code{else} 子句會被執行。

在 @ref{348,,for} 迴圈中，@code{else} 子句會在迴圈完成最終的疊代後執行。

在 @ref{18d6,,while} 迴圈中，它會在迴圈條件變為 false 後執行。

在任何一種迴圈中，如果迴圈由 @ref{17f,,break} 終止，則不會執行 @code{else} 子句。當然其他提早結束迴圈的方式（例如 @ref{1af,,return} 或引發例外）也會跳過 @ref{17c,,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:
...         # 迴圈結束但沒有找到因數
...         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} 迴圈，`並非' @code{if} 陳述式。）

理解 else 子句的一個方法是將它想像成與迴圈內的 @code{if} 配對。當迴圈執行時，它會運行如 if/if/if/else 的序列。@code{if} 在迴圈內，會遇到多次。如果條件曾經為真，@code{break} 就會發生。如果條件從未為真，迴圈外的 @code{else} 子句就會執行。

當 @code{else} 子句用於迴圈時，相較於搭配 @code{if} 陳述式使用，它的行為與 @ref{8f0,,try} 陳述式中的 @code{else} 子句更為相似：@code{try} 陳述式的 @code{else} 子句在沒有發生例外 (exception) 時執行，而迴圈的 @code{else} 子句在沒有任何 @code{break} 發生時執行。更多有關 @code{try} 陳述式和例外的介紹，見@ref{1ec2,,處理例外}。

@geindex ...;ellipsis literal

@node pass 陳述式,match 陳述式,迴圈的 else 子句,深入了解流程控制
@anchor{tutorial/controlflow pass-statements}@anchor{1ec3}@anchor{tutorial/controlflow tut-pass}@anchor{1ec4}
@subsection @code{pass} 陳述式


@ref{17e,,pass} 陳述式不執行任何動作。它可用在語法上需要一個陳述式但程式不需要執行任何動作的時候。例如：

@example
>>> while True:
...     pass  # 忙碌等待鍵盤中斷 (Ctrl+C)
...
@end example

這經常用於建立簡單的 class（類別）：

@example
>>> class MyEmptyClass:
...     pass
...
@end example

@ref{17e,,pass} 亦可作為一個函式或條件判斷主體的預留位置，在你撰寫新的程式碼時讓你保持在更抽象的思維層次。@code{pass} 會直接被忽略：

@example
>>> def initlog(*args):
...     pass   # 記得要實作這個！
...
@end example

在最後這個例子中，許多人會使用刪節號字面值 @code{...} 來取代 @code{pass}。這種用法對 Python 並沒有特殊的意義，且並非語言定義的一部分（你也可以在這裡使用任何常數運算式），但 @code{...} 也慣例上被用作預留主體 (placeholder body)。見 @ref{1ec5,,Ellipsis 物件}。

@node match 陳述式,定義函式 function,pass 陳述式,深入了解流程控制
@anchor{tutorial/controlflow match-statements}@anchor{1ec6}@anchor{tutorial/controlflow tut-match}@anchor{1eb6}
@subsection @code{match} 陳述式


@ref{a07,,match} 陳述式會拿取一個運算式，並將其值與多個連續的模式 (pattern) 進行比較，這些模式是以一個或多個 case 區塊來表示。表面上，這類似 C、Java 或 JavaScript（以及許多其他語言）中的 switch 陳述式，但它與 Rust 或 Haskell 等語言中的模式匹配 (pattern matching) 更為相近。只有第一個匹配成功的模式會被執行，而它也可以將成分（序列元素或物件屬性）從值中提取到變數中。如果沒有任何的 case 匹配成功，則不會執行任何的分支。

最簡單的形式，是將一個主題值 (subject value) 與一個或多個字面值 (literal) 進行比較：

@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

請注意最後一段：「變數名稱」@code{_} 是作為`通用字元 (wildcard)'的角色，且永遠不會匹配失敗。

你可以使用 @code{|}（「或」）來將多個字面值組合在單一模式中：

@example
case 401 | 403 | 404:
    return "Not allowed"
@end example

模式可以看起來像是拆解賦值 (unpacking assignment)，且可以用來連結變數：

@example
# point 是一個 (x, y) 元組
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

請仔細研究那個例子！第一個模式有兩個字面值，可以想作是之前所述的字面值模式的延伸。但是接下來的兩個模式結合了一個字面值和一個變數，且該變數`繫結 (bind)' 了來自主題 (@code{point}) 的一個值。第四個模式會擷取兩個值，這使得它在概念上類似於拆解賦值 @code{(x, y) = point}。

如果你要用 class 來結構化你的資料，你可以使用該 class 的名稱加上一個引數列表，類似一個建構式 (constructor)，但它能夠將屬性擷取到變數中：

@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

你可以將位置參數 (positional parameter) 與一些能夠排序其屬性的內建 class（例如 dataclasses）一起使用。你也可以透過在 class 中設定特殊屬性 @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

理解模式的一種推薦方法，是將它們看作是你會放在賦值 (assignment) 左側內容的一種延伸形式，這樣就可以了解哪些變數會被設為何值。只有獨立的名稱（像是上面的 @code{var}）能被 match 陳述式賦值。點分隔名稱（如 @code{foo.bar}）、屬性名稱（上面的 @code{x=} 及 @code{y=}）或 class 名稱（由它們後面的 "(...)" 被辨識，如上面的 @code{Point}）則永遠無法被賦值。

模式可以任意地被巢套 (nested)。例如，如果我們有一個由某些點所組成的簡短 list，我們就可以像這樣加入 @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)」。如果該防護為假，則 @code{match} 會繼續嘗試下一個 case 區塊。請注意，值的擷取會發生在防護的評估之前：

@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 
與拆解賦值的情況類似，tuple（元組）和 list 模式具有完全相同的意義，而且實際上可以匹配任意的序列。一個重要的例外，是它們不能匹配疊代器 (iterator) 或字串。

@item 
序列模式 (sequence pattern) 可支援擴充拆解 (extended unpacking)：@code{[x, y, *rest]} 與 @code{(x, y, *rest)} 的作用類似於拆解賦值。@code{*} 後面的名稱也可以是 @code{_}，所以 @code{(x, y, *_)} 會匹配一個至少兩項的序列，且不會連結那兩項以外的其餘項。

@item 
對映模式 (mapping pattern)：@code{@{"bandwidth": b, "latency": l@}} 能從一個 dictionary（字典）中擷取 @code{"bandwidth"} 及 @code{"latency"} 的值。與序列模式不同，額外的鍵 (key) 會被忽略。一種像是 @code{**rest} 的拆解方式，也是可被支援的。（但 @code{**_} 則是多餘的做法，所以它並不被允許。）

@item 
使用關鍵字 @code{as} 可以擷取子模式 (subpattern)：

@example
case (Point(x1, y1), Point(x2, y2) as p2): ...
@end example

將會擷取輸入的第二個元素作為 @code{p2}（只要該輸入是一個由兩個點所組成的序列）。

@item 
大部分的字面值是藉由相等性 (equality) 來比較，但是單例物件 (singleton) @code{True}、@code{False} 和 @code{None} 是藉由標識值 (identity) 來比較。

@item 
模式可以使用附名常數 (named constant)。這些模式必須是點分隔名稱，以免它們被解釋為擷取變數：

@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 定義函式 function,深入了解函式定義,match 陳述式,深入了解流程控制
@anchor{tutorial/controlflow defining-functions}@anchor{1ec7}@anchor{tutorial/controlflow tut-functions}@anchor{1ec8}
@subsection 定義函式 (function)


我們可以建立一個函式來產生費式數列到任何一個上界：

@example
>>> def fib(n):    # 寫出小於 n 的費氏數列
...     """印出小於 n 的費氏數列。"""
...     a, b = 0, 1
...     while a < n:
...         print(a, end=' ')
...         a, b = b, a+b
...     print()
...
>>> # 現在呼叫我們剛才定義的函式：
>>> fib(2000)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 1597
@end example

@geindex ddocumentation strings（說明字串）
@geindex docstrings（說明字串）
@geindex strings（字串）@comma{} documentation（說明文件）

關鍵字 @ref{164f,,def} 介紹一個函式的`定義'。它之後必須連著該函式的名稱和置於括號之中的一串參數。自下一行起，所有縮排的陳述式成為該函式的主體。

一個函式的第一個陳述式可以是一個字串文本；該字串文本被視為該函式的說明文件字串，即 `docstring'。（關於 docstring 的細節請參見@ref{1ec9,,說明文件字串 (Documentation Strings)}段落。）有些工具可以使用 docstring 來自動產生線上或可列印的文件，或讓使用者能以互動的方式在原始碼中瀏覽文件。在原始碼中加入 docstring 是個好慣例，應該養成這樣的習慣。

函式`執行'時會建立一個新的符號表 (symbol table) 來儲存該函式內的區域變數 (local variable)。更精確地說，所有在函式內的變數賦值都會把該值儲存在一個區域符號表。然而，在引用一個變數時，會先從區域符號表開始搜尋，其次為外層函式的區域符號表，其次為全域符號表 (global symbol table)，最後為所有內建的名稱。因此，在函式中，全域變數及外層函式變數雖然可以被引用，但無法被直接賦值（除非全域變數是在 @ref{4a7,,global} 陳述式中被定義，或外層函式變數在 @ref{14a8,,nonlocal} 陳述式中被定義）。

在一個函式被呼叫的時候，實際傳入的參數（引數）會被加入至該函式的區域符號表。因此，引數傳入的方式為`傳值呼叫 (call by value)'（這裡傳遞的`值'永遠是一個物件的`參照 (reference)'，而不是該物件的值）。 @footnote{
實際上，`傳址呼叫 (call by object reference)' 的說法可能較為貼切。因為，若傳遞的是一個可變物件時，呼叫者將看得見被呼叫者對物件做出的任何改變（例如被插入 list 內的新項目）。
} 當一個函式呼叫別的函式或遞迴呼叫它自己時，在被呼叫的函式中會建立一個新的區域符號表。

函式定義時，會把該函式名稱加入至目前的符號表。函式名稱的值帶有一個型別，並被直譯器辨識為使用者自定函式 (user-defined function)。該值可以被指定給別的變數名，使該變數名也可以被當作函式使用。這是常見的重新命名方式：

@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} 是個函式，而是個程序 (procedure)，因為它並沒有回傳值。實際上，即使一個函式缺少一個 @ref{1af,,return} 陳述式，它亦有一個固定的回傳值。這個值稱為 @code{None}（它是一個內建名稱）。在直譯器中單獨使用 @code{None} 時，通常不會被顯示。你可以使用 @ref{1170,,print()} 來看到它：

@example
>>> fib(0)
>>> print(fib(0))
None
@end example

如果要寫一個函式回傳費式數列的 list 而不是直接印出它，這也很容易：

@example
>>> def fib2(n):  # 回傳到 n 為止的費氏數列
...     """回傳包含到 n 為止的費氏數列的串列。"""
...     result = []
...     a, b = 0, 1
...     while a < n:
...         result.append(a)    # 見下方
...         a, b = b, a+b
...     return result
...
>>> f100 = fib2(100)    # 呼叫它
>>> f100                # 寫出結果
[0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]
@end example

這個例子一樣示範了一些新的 Python 特性：


@itemize *

@item 
@ref{1af,,return} 陳述式會讓一個函式回傳一個值。單獨使用 @code{return} 不外加一個運算式作為引數時會回傳 @code{None}。一個函式執行到結束也會回傳 @code{None}。

@item 
@code{result.append(a)} 陳述式呼叫了一個 list 物件 @code{result} 的 `method（方法）'。method 為「屬於」一個物件的函式，命名規則為 @code{obj.methodname}，其中 @code{obj} 為某個物件（亦可為一運算式），而 @code{methodname} 為該 method 的名稱，並由該物件的型別所定義。不同的型別定義不同的 method。不同型別的 method 可以擁有一樣的名稱而不會讓 Python 混淆。（你可以使用 `class'（類別）定義自己的物件型別和 method，見 @ref{1eca,,Class（類別）}）範例中的 @ref{8d4,,append()} method 定義在 list 物件中；它會在該 list 的末端加入一個新的元素。這個例子等同於 @code{result = result + [a]}，但更有效率。
@end itemize

@node 深入了解函式定義,間奏曲：程式碼風格 Coding Style,定義函式 function,深入了解流程控制
@anchor{tutorial/controlflow more-on-defining-functions}@anchor{1ecb}@anchor{tutorial/controlflow tut-defining}@anchor{1ecc}
@subsection 深入了解函式定義


定義函式時使用的引數 (argument) 數量是可變的。總共有三種可以組合使用的形式。

@menu
* 預設引數值:: 
* 關鍵字引數:: 
* 特殊參數:: 
* 任意引數列表 (Arbitrary Argument Lists): 任意引數列表 Arbitrary Argument Lists. 
* 拆解引數列表（Unpacking Argument Lists）:: 
* Lambda 運算式:: 
* 說明文件字串 (Documentation Strings): 說明文件字串 Documentation Strings. 
* 函式註釋 (Function Annotations): 函式註釋 Function Annotations. 

@end menu

@node 預設引數值,關鍵字引數,,深入了解函式定義
@anchor{tutorial/controlflow default-argument-values}@anchor{1ecd}@anchor{tutorial/controlflow tut-defaultargs}@anchor{1ece}
@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

此例也使用了關鍵字 @ref{349,,in}，用於測試序列中是否包含某個特定值。

預設值是在函式定義當下，於`定義時'的作用域中求值，所以：

@example
i = 5

def f(arg=i):
    print(arg)

i = 6
f()
@end example

將會輸出 @code{5}。

`重要警告'：預設值只求值一次。當預設值為可變物件，例如 list、dictionary（字典）或許多類別實例時，會產生不同的結果。例如，以下函式於後續呼叫時會累積曾經傳遞的引數：

@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 關鍵字引數,特殊參數,預設引數值,深入了解函式定義
@anchor{tutorial/controlflow keyword-arguments}@anchor{1ecf}@anchor{tutorial/controlflow tut-keywordargs}@anchor{1ed0}
@subsubsection 關鍵字引數


函式也可以使用@ref{f09,,關鍵字引數}，以 @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 個位置引數
parrot(voltage=1000)                                  # 1 個關鍵字引數
parrot(voltage=1000000, action='VOOOOOM')             # 2 個關鍵字引數
parrot(action='VOOOOOM', voltage=1000000)             # 2 個關鍵字引數
parrot('a million', 'bereft of life', 'jump')         # 3 個位置引數
parrot('a thousand', state='pushing up the daisies')  # 1 個位置引數、1 個關鍵字引數
@end example

但以下呼叫方式都無效：

@example
parrot()                     # 缺少必要引數
parrot(voltage=5.0, 'dead')  # 關鍵字引數後面的非關鍵字引數
parrot(110, voltage=220)     # 同一個引數有重複值
parrot(actor='John Cleese')  # 未知的關鍵字引數
@end example

函式呼叫時，關鍵字引數 (keyword argument) 必須在位置引數 (positional argument) 後面。所有傳遞的關鍵字引數都必須匹配一個可被函式接受的引數（@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} 形式時，它接收一個 dictionary（字典，詳見 @ref{cb4,,Mapping Types --- dict}），該字典包含所有可對應形式參數以外的關鍵字引數。@code{**name} 可以與 @code{*name} 參數（下一小節介紹）組合使用，@code{*name} 接收一個 @ref{1ed1,,tuple}，該 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

注意，關鍵字引數的輸出順序與呼叫函式時被提供的順序必定一致。

@node 特殊參數,任意引數列表 Arbitrary Argument Lists,關鍵字引數,深入了解函式定義
@anchor{tutorial/controlflow special-parameters}@anchor{1ed2}
@subsubsection 特殊參數


在預設情況，引數能以位置或明確地以關鍵字傳遞给 Python 函式。為了程式的可讀性及效能，限制引數的傳遞方式是合理的，如此，開發者只需查看函式定義，即可確定各項目是按位置，按位置或關鍵字，還是按關鍵字傳遞。

函式定義可能如以下樣式：

@example
def f(pos1, pos2, /, pos_or_kwd, *, kwd1, kwd2):
      -----------    ----------     ----------
        |             |                  |
        |        Positional or keyword   |
        |                                - Keyword only
         -- Positional only
@end example

@code{/} 和 @code{*} 是選擇性的。這些符號若被使用，是表明引數被傳遞給函式的參數種類：僅限位置、位置或關鍵字、僅限關鍵字。關鍵字參數也稱為附名參數 (named parameters)。

@menu
* 位置或關鍵字引數 (Positional-or-Keyword Arguments): 位置或關鍵字引數 Positional-or-Keyword Arguments. 
* 僅限位置參數 (Positional-Only Parameters): 僅限位置參數 Positional-Only Parameters. 
* 僅限關鍵字引數 (Keyword-Only Arguments): 僅限關鍵字引數 Keyword-Only Arguments. 
* 函式範例:: 
* 回顧:: 

@end menu

@node 位置或關鍵字引數 Positional-or-Keyword Arguments,僅限位置參數 Positional-Only Parameters,,特殊參數
@anchor{tutorial/controlflow positional-or-keyword-arguments}@anchor{1ed3}
@subsubsection 位置或關鍵字引數 (Positional-or-Keyword Arguments)


若函式定義中未使用 @code{/} 和 @code{*} 時，引數可以按位置或關鍵字傳遞給函式。

@node 僅限位置參數 Positional-Only Parameters,僅限關鍵字引數 Keyword-Only Arguments,位置或關鍵字引數 Positional-or-Keyword Arguments,特殊參數
@anchor{tutorial/controlflow positional-only-parameters}@anchor{1ed4}
@subsubsection 僅限位置參數 (Positional-Only Parameters)


此處再詳述一些細節，特定參數可以標記為`僅限位置'。若參數為`僅限位置'時，它們的順序很重要，且這些參數不能用關鍵字傳遞。僅限位置參數必須放在 @code{/}（斜線）之前。@code{/} 用於在邏輯上分開僅限位置參數與其餘參數。如果函式定義中沒有 @code{/}，則表示沒有任何僅限位置參數。

@code{/} 後面的參數可以是`位置或關鍵字'或`僅限關鍵字'參數。

@node 僅限關鍵字引數 Keyword-Only Arguments,函式範例,僅限位置參數 Positional-Only Parameters,特殊參數
@anchor{tutorial/controlflow keyword-only-arguments}@anchor{1ed5}
@subsubsection 僅限關鍵字引數 (Keyword-Only Arguments)


要把參數標記為`僅限關鍵字'，表明參數必須以關鍵字引數傳遞，必須在引數列表中第一個`僅限關鍵字'參數前放上 @code{*}。

@node 函式範例,回顧,僅限關鍵字引數 Keyword-Only Arguments,特殊參數
@anchor{tutorial/controlflow function-examples}@anchor{1ed6}
@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} 是我們最熟悉的形式，對呼叫方式沒有任何限制，可以按位置或關鍵字傳遞引數：

@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} 的函式定義透過 @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{**kwds} 內有 @code{name} 這個鍵，可能與位置引數 @code{name} 產生潛在衝突：

@example
def foo(name, **kwds):
    return 'name' in kwds
@end example

呼叫該函式不可能回傳 @code{True}，因為關鍵字 @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'} 也可以當作關鍵字引數中的鍵：

@example
>>> def foo(name, /, **kwds):
...     return 'name' in kwds
...
>>> foo(1, **@{'name': 2@})
True
@end example

換句話說，僅限位置參數的名稱可以在 @code{**kwds} 中使用，而不產生歧義。

@node 回顧,,函式範例,特殊參數
@anchor{tutorial/controlflow recap}@anchor{1ed7}
@subsubsection 回顧


此用例決定哪些參數可以用於函式定義：

@example
def f(pos1, pos2, /, pos_or_kwd, *, kwd1, kwd2):
@end example

說明：


@itemize *

@item 
如果不想讓使用者使用參數名稱，請使用僅限位置。當參數名稱沒有實際意義時，若你想控制引數在函式呼叫的排列順序，或同時使用位置參數和任意關鍵字時，這種方式很有用。

@item 
當參數名稱有意義，且明確的名稱可讓函式定義更易理解，或是你不希望使用者依賴引數被傳遞時的位置時，請使用僅限關鍵字。

@item 
對於應用程式介面 (API)，使用僅限位置，以防止未來參數名稱被修改時造成 API 的中斷性變更。
@end itemize

@node 任意引數列表 Arbitrary Argument Lists,拆解引數列表（Unpacking Argument Lists）,特殊參數,深入了解函式定義
@anchor{tutorial/controlflow arbitrary-argument-lists}@anchor{1ed8}@anchor{tutorial/controlflow tut-arbitraryargs}@anchor{1ed9}
@subsubsection 任意引數列表 (Arbitrary Argument Lists)


@geindex * （星號）;於函式呼叫中

最後，有個較不常用的選項，是規定函式被呼叫時，可以使用任意數量的引數。這些引數會被包裝進一個 tuple 中（詳見 @ref{1ed1,,Tuples 和序列 (Sequences)}）。在可變數量的引數之前，可能有零個或多個普通引數：

@example
def write_multiple_items(file, separator, *args):
    file.write(separator.join(args))
@end example

通常，這些 `variadic'（可變的）引數會出現在參數列表的最末端，這樣它們就可以把所有傳遞給函式的剩餘輸入引數都撈起來。出現在 @code{*args} 參數後面的任何參數必須是「僅限關鍵字」引數，意即它們只能作為關鍵字引數，而不能用作位置引數。

@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 Argument Lists）,Lambda 運算式,任意引數列表 Arbitrary Argument Lists,深入了解函式定義
@anchor{tutorial/controlflow tut-unpacking-arguments}@anchor{1eda}@anchor{tutorial/controlflow unpacking-argument-lists}@anchor{1edb}
@subsubsection 拆解引數列表（Unpacking Argument Lists）


當引數們已經存在一個 list 或 tuple 裡，但為了滿足一個需要個別位置引數的函式呼叫，而去拆解它們時，情況就剛好相反。例如，內建的 @ref{b34,,range()} 函式要求分開的 `start' 和 `stop' 引數。如果這些引數不是分開的，則要在呼叫函式時，用 @code{*} 運算子把引數們從 list 或 tuple 中拆解出來：

@example
>>> list(range(3, 6))            # 使用分離引數的一般呼叫
[3, 4, 5]
>>> args = [3, 6]
>>> list(range(*args))            # 以從串列解包而得的引數呼叫
[3, 4, 5]
@end example

@geindex **;於函式呼叫中

同樣地，dictionary（字典）可以用 @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 運算式,說明文件字串 Documentation Strings,拆解引數列表（Unpacking Argument Lists）,深入了解函式定義
@anchor{tutorial/controlflow lambda-expressions}@anchor{1edc}@anchor{tutorial/controlflow tut-lambda}@anchor{1edd}
@subsubsection Lambda 運算式


@ref{149e,,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{dc3,,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 說明文件字串 Documentation Strings,函式註釋 Function Annotations,Lambda 運算式,深入了解函式定義
@anchor{tutorial/controlflow documentation-strings}@anchor{1ede}@anchor{tutorial/controlflow tut-docstrings}@anchor{1ec9}
@subsubsection 說明文件字串 (Documentation Strings)


@geindex docstrings（說明字串）
@geindex ddocumentation strings（說明字串）
@geindex strings（字串）@comma{} documentation（說明文件）

以下是關於說明文件字串內容和格式的慣例。

第一行都是一段關於此物件目的之簡短摘要。為保持簡潔，不應在這裡明確地陳述物件的名稱或型別，因為有其他方法可以達到相同目的（除非該名稱剛好是一個描述函式運算的動詞）。這一行應以大寫字母開頭，以句號結尾。

文件字串為多行時，第二行應為空白行，在視覺上將摘要與其餘描述分開。後面幾行可包含一或多個段落，描述此物件的呼叫慣例、副作用等。

Python 剖析器 (parser) 不會去除 Python 中多行字串的縮排，因此，處理說明文件的工具應在必要時去除縮排。這項操作遵循以下慣例：在字串第一行`之後'的第一個非空白行決定了整個說明文件字串的縮排量（不能用第一行的縮排，因為它通常與字串的開頭引號們相鄰，其縮排在字串文本中並不明顯），然後，所有字串行開頭處與此縮排量「等價」的空白字元會被去除。不應出現比上述縮進量更少的字串行，但若真的出現了，這些行的全部前導空白字元都應被去除。展開 tab 鍵後（通常為八個空格），應測試空白字元量是否等價。

下面是多行說明字串的一個範例：

@example
>>> def my_function():
...     """不做任何事，但有文件說明。
...
...     不，真的，它什麼都不做。
...     """
...     pass
...
>>> print(my_function.__doc__)
Do nothing, but document it.

No, really, it doesn't do anything.
@end example

@node 函式註釋 Function Annotations,,說明文件字串 Documentation Strings,深入了解函式定義
@anchor{tutorial/controlflow function-annotations}@anchor{1edf}@anchor{tutorial/controlflow tut-annotations}@anchor{1ee0}
@subsubsection 函式註釋 (Function Annotations)


@geindex function（函式）;annotations（註釋）
@geindex ->;function annotations（函式註釋）
@geindex ; （冒號）;function annotations（函式註釋）

@ref{1ee1,,函式註釋}是選擇性的元資料（metadata）資訊，描述使用者定義函式所使用的型別（更多資訊詳見 
@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{1ee2,,註釋}以 dictionary（字典）的形式存放在函式的 @ref{456,,__annotations__} 屬性中，且不會影響函式的任何其他部分。參數註釋的定義方式是在參數名稱後加一個冒號，冒號後面跟著一個對註釋求值的運算式。回傳註釋的定義方式是在參數列表和 @ref{164f,,def} 陳述式結尾的冒號中間，用一個 @code{->} 文字接著一個運算式。以下範例註釋了一個必要引數、一個選擇性引數，以及回傳值：

@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 間奏曲：程式碼風格 Coding Style,,深入了解函式定義,深入了解流程控制
@anchor{tutorial/controlflow intermezzo-coding-style}@anchor{1ee3}@anchor{tutorial/controlflow tut-codingstyle}@anchor{1ee4}
@subsection 間奏曲：程式碼風格 (Coding Style)


@geindex coding（程式編寫）;style（風格）

現在你即將要寫更長、更複雜的 Python 程式，是時候討論一下`編碼樣式'了。大多數語言都能以不同的樣式被書寫（或更精確地說，被`格式化'），而有些樣式比其他的更具可讀性。能讓其他人輕鬆閱讀你的程式碼永遠是一個好主意，而使用優良的編碼樣式對此有極大的幫助。

對於 Python，大多數的專案都遵循 
@geindex Python Enhancement Proposals; PEP 8
PEP 8@footnote{https://peps.python.org/pep-0008/} 的樣式指南；它推行的編碼樣式相當可讀且賞心悅目。每個 Python 開發者都應該花點時間研讀；這裡是該指南的核心重點：


@itemize *

@item 
用 4 個空格縮排，不要用 tab 鍵。

4 個空格是小縮排（容許更大的巢套深度）和大縮排（較易閱讀）之間的折衷方案。Tab 鍵會造成混亂，最好別用。

@item 
換行，使一行不超過 79 個字元。

換行能讓使用小顯示器的使用者方便閱讀，也可以在較大顯示器上並排陳列多個程式碼檔案。

@item 
用空行分隔函式和 class（類別），及函式內較大塊的程式碼。

@item 
如果可以，把註解放在單獨一行。

@item 
使用說明字串。

@item 
運算子前後、逗號後要加空格，但不要直接放在括號內側：@code{a = f(1, 2) + g(3, 4)}。

@item 
Class 和函式的命名樣式要一致；按慣例，命名 class 用 @code{UpperCamelCase}（駝峰式大小寫），命名函式與 method 用 @code{lowercase_with_underscores}（小寫加底線）。永遠用 @code{self} 作為 method 第一個引數的名稱（關於 class 和 method，詳見 @ref{1ee5,,初見 class}）。

@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 資料結構,模組 Module,深入了解流程控制,Python 教學
@anchor{tutorial/datastructures doc}@anchor{1ee6}@anchor{tutorial/datastructures data-structures}@anchor{1ee7}@anchor{tutorial/datastructures translation-repo}@anchor{1ee8}@anchor{tutorial/datastructures tut-structures}@anchor{1ebc}
@section 資料結構


這個章節將會更深入的介紹一些你已經學過的東西的細節上，並且加入一些你還沒有接觸過的部分。

@menu
* 進一步了解 List（串列）:: 
* del 陳述式:: 
* Tuples 和序列 (Sequences): Tuples 和序列 Sequences. 
* 集合 (Sets): 集合 Sets. 
* 字典（Dictionary）:: 
* 迴圈技巧:: 
* 深入了解條件 (Condition): 深入了解條件 Condition. 
* 序列和其他資料類型之比較:: 

@end menu

@node 進一步了解 List（串列）,del 陳述式,,資料結構
@anchor{tutorial/datastructures more-on-lists}@anchor{1ee9}@anchor{tutorial/datastructures tut-morelists}@anchor{1eea}
@subsection 進一步了解 List（串列）


List（串列）這個資料型態，具有更多操作的方法。下面條列了所有關於 list 物件的 method：


@deffn {方法} list.append (x)

將一個新的項目加到 list 的尾端。與 @code{a[len(a):] = [x]} 類似。
@end deffn


@deffn {方法} list.extend (iterable)

將 iterable（可疊代物件）接到 list 的尾端。與 @code{a[len(a):] = iterable} 類似。
@end deffn


@deffn {方法} list.insert (i, x)

將一個項目插入至 list 中給定的位置。第一個引數為插入處前元素的索引值，所以 @code{a.insert(0, x)}  會插入在 list 首位，而 @code{a.insert(len(a), x)} 則相當於 @code{a.append(x)}。
@end deffn


@deffn {方法} list.remove (x)

刪除 list 中第一個值等於 `x' 的元素。若 list 中無此元素則會觸發 @ref{2eb,,ValueError}。
@end deffn


@deffn {方法} list.pop ([i])

移除 list 中給定位置的項目，並回傳它。如果沒有指定位置， @code{a.pop()} 將會移除 list 中最後的項目並回傳它。若 list 是空的或是索引值超出範圍，則會引發 @ref{1729,,IndexError} 例外。
@end deffn


@deffn {方法} list.clear ()

刪除 list 中所有項目。與 @code{del a[:]} 類似。
@end deffn


@deffn {方法} list.index (x[, start[, end]])

回傳 list 中第一個出現 `x' 的（從零開始的）索引值。若 list 中無此項目，則丟出 @ref{2eb,,ValueError} 錯誤。

引數 `start' 和 `end' 的定義跟在 slice 表示法中相同，搜尋的動作被這兩個引數限定在 list 中特定的子序列。但要注意的是，回傳的索引值是從 list 的開頭開始算，而不是從 `start' 開始算。
@end deffn


@deffn {方法} list.count (x)

回傳 `x' 在 list 中所出現的次數。
@end deffn


@deffn {方法} list.sort (*, key=None, reverse=False)

將 list 中的項目排序。（可使用引數來進行客製化的排序，請參考 @ref{dc2,,sorted()} 部分的解釋）
@end deffn


@deffn {方法} list.reverse ()

將 list 中的項目前後順序反過來。
@end deffn


@deffn {方法} list.copy ()

回傳一個淺複製 (shallow copy) 的 list。與 @code{a[:]} 類似。
@end deffn

以下是一個使用到許多 list 物件方法的例子：

@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)  # 從位置 4 開始找到下一個 banana
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} 或者是 @code{sort}，並沒有印出回傳值，事實上，他們回傳預設值 @code{None} @footnote{
其他語言可以回傳變更後的物件，這就允許 method 的串連，例如 @code{d->insert("a")->remove("b")->sort();}。
}。這是一個用於 Python 中所有可變資料結構的設計法則。

另外你可能也會發現，不是所有資料都可以被排序或比較。例如，@code{[None, 'hello', 10]} 就不可排序，因為整數不能與字串比較，而 @code{None} 不能與其他型別比較。有些型別根本就沒有被定義彼此之間的大小順序，例如，@code{3+4j < 5+7j} 就是一個無效的比較。

@menu
* 將 List 作為 Stack（堆疊）使用:: 
* 將 List 作為 Queue（佇列）使用:: 
* List Comprehensions（串列綜合運算）:: 
* 巢狀的 List Comprehensions:: 

@end menu

@node 將 List 作為 Stack（堆疊）使用,將 List 作為 Queue（佇列）使用,,進一步了解 List（串列）
@anchor{tutorial/datastructures tut-lists-as-stacks}@anchor{1eeb}@anchor{tutorial/datastructures using-lists-as-stacks}@anchor{1eec}
@subsubsection 將 List 作為 Stack（堆疊）使用


List 的操作方法使得它非常簡單可以用來實作 stack（堆疊）。Stack 為一個遵守最後加入元素最先被取回（後進先出，"last-in, first-out"）規則的資料結構。你可以使用方法 @ref{8d4,,append()} 將一個項目放到堆疊的頂層。而使用方法 @ref{1eed,,pop()} 且不給定索引值去取得堆疊最上面的項目。舉例而言：

@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 將 List 作為 Queue（佇列）使用,List Comprehensions（串列綜合運算）,將 List 作為 Stack（堆疊）使用,進一步了解 List（串列）
@anchor{tutorial/datastructures tut-lists-as-queues}@anchor{1eee}@anchor{tutorial/datastructures using-lists-as-queues}@anchor{1eef}
@subsubsection 將 List 作為 Queue（佇列）使用


我們也可以將 list 當作 queue（佇列）使用，即最先加入元素最先被取回（先進先出，"first-in, first-out"）的資料結構。然而，list 在這種使用方式下效率較差。使用 @code{append} 和 @code{pop} 來加入和取出尾端的元素較快，而使用 @code{insert} 和 @code{pop} 來插入和取出頭端的元素較慢（因為其他元素都需要挪動一格）。

如果要實作 queue，請使用 @ref{7ed,,collections.deque}，其被設計成能快速的從頭尾兩端加入和取出。例如：

@example
>>> from collections import deque
>>> queue = deque(["Eric", "John", "Michael"])
>>> queue.append("Terry")           # Terry 加進來
>>> queue.append("Graham")          # Graham 加進來
>>> queue.popleft()                 # 第一個加進來的現在離開
'Eric'
>>> queue.popleft()                 # 第二個加進來的現在離開
'John'
>>> queue                           # queue 裡剩下的會按照加進來的順序排列
deque(['Michael', 'Terry', 'Graham'])
@end example

@node List Comprehensions（串列綜合運算）,巢狀的 List Comprehensions,將 List 作為 Queue（佇列）使用,進一步了解 List（串列）
@anchor{tutorial/datastructures list-comprehensions}@anchor{1ef0}@anchor{tutorial/datastructures tut-listcomps}@anchor{1ef1}
@subsubsection List Comprehensions（串列綜合運算）


List comprehension（串列綜合運算）讓你可以用簡潔的方法建立 list。常見的應用是基於一個序列或 iterable（可疊代物件），將每一個元素經過某個運算的結果串接起來成為新的 list，或是建立一個子序列，其每一個元素皆滿足一個特定的條件。

舉例來說，假設我們要建立一個「平方的 list」：

@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}，其在迴圈結束後仍然存在。我們可以這樣產生平方串列而不造成任何 side effects（副作用）：

@example
squares = list(map(lambda x: x**2, range(10)))
@end example

或與此相等的：

@example
squares = [x**2 for x in range(10)]
@end example

這樣更簡潔和易讀。

一個 list comprehension 的組成，是在一對方括號內，放入一個 expression（運算式）、一個 @code{for} 子句、再接著零個或多個 @code{for} 或 @code{if} 子句。結果會是一個新的 list，內容是在後面的 @code{for} 和 @code{if} 子句情境下，對前面運算式求值的結果。例如，這個 list comprehension 組合了兩個 list 中彼此相異的元素：

@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{348,,for} 和 @ref{181,,if} 在這兩段程式裡的順序是相同的。

如果 expression 是一個 tuple（例如上面例子中的 @code{(x, y)}），它必須加上括號：

@example
>>> vec = [-4, -2, 0, 2, 4]
>>> # 建立一個值加倍的新串列
>>> [x*2 for x in vec]
[-8, -4, 0, 4, 8]
>>> # 過濾串列以排除負數
>>> [x for x in vec if x >= 0]
[0, 2, 4]
>>> # 對所有元素套用函式
>>> [abs(x) for x in vec]
[4, 2, 0, 2, 4]
>>> # 對每個元素呼叫方法
>>> freshfruit = ['  banana', '  loganberry ', 'passion fruit  ']
>>> [weapon.strip() for weapon in freshfruit]
['banana', 'loganberry', 'passion fruit']
>>> # 建立像 (數字, 平方) 的 2-元組串列
>>> [(x, x**2) for x in range(6)]
[(0, 0), (1, 1), (2, 4), (3, 9), (4, 16), (5, 25)]
>>> # 元組必須加上括號，否則會產生錯誤
>>> [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

List comprehensions 可以含有複雜的 expression 和巢狀的函式：

@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 巢狀的 List Comprehensions,,List Comprehensions（串列綜合運算）,進一步了解 List（串列）
@anchor{tutorial/datastructures nested-list-comprehensions}@anchor{1ef2}
@subsubsection 巢狀的 List Comprehensions


在 list comprehesion 中開頭的 expression 可以是任何形式的 expression，包括再寫一個 list comprehension。

考慮以下表示 3x4 矩陣的範例，使用 list 包含 3 個長度為 4 的 list ：

@example
>>> matrix = [
...     [1, 2, 3, 4],
...     [5, 6, 7, 8],
...     [9, 10, 11, 12],
... ]
@end example

以下的 list comprehesion 會將矩陣的行與列作轉置：

@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

如同我們在上一節看到的，內部的 list comprehension 會依據後面的 @ref{348,,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):
...     # 下面這三行實作了巢狀的 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 functions) 而不是複雜的流程控制陳述式。在這個例子中，使用 @ref{1a0,,zip()} 函式會非常有效率：

@example
>>> list(zip(*matrix))
[(1, 5, 9), (2, 6, 10), (3, 7, 11), (4, 8, 12)]
@end example

關於星號的更多細節，請參考@ref{1eda,,拆解引數列表（Unpacking Argument Lists）}。

@node del 陳述式,Tuples 和序列 Sequences,進一步了解 List（串列）,資料結構
@anchor{tutorial/datastructures the-del-statement}@anchor{1ef3}@anchor{tutorial/datastructures tut-del}@anchor{1ef4}
@subsection @code{del} 陳述式


有一個方法可以藉由索引而不是值來刪除 list 中的項目：@ref{1a62,,del} 陳述式。這和 @ref{1eed,,pop()} method 傳回一個值不同，@code{del} 陳述式可以用來刪除 list 中的片段或者清空整個 list（我們之前藉由指派一個空的 list 給想刪除的片段來完成這件事）。例如：

@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{1a62,,del} 也可以用來刪除整個變數：

@example
>>> del a
@end example

刪除之後，對 @code{a} 的參照將會造成錯誤（至少在另一個值又被指派到它之前）。我們將在後面看到更多關於 @ref{1a62,,del} 的其他用法。

@node Tuples 和序列 Sequences,集合 Sets,del 陳述式,資料結構
@anchor{tutorial/datastructures tuples-and-sequences}@anchor{1ef5}@anchor{tutorial/datastructures tut-tuples}@anchor{1ed1}
@subsection Tuples 和序列 (Sequences)


我們看到 list 和字串 (string) 有許多共同的特性，像是索引操作 (indexing) 以及切片操作 (slicing) 。他們是`序列'資料類型中的兩個例子（請參考@ref{1ef6,,Sequence Types --- list@comma{} tuple@comma{} range}）。由於 Python 是個持續發展中的語言，未來可能還會有其他的序列資料類型加入。接著要介紹是下一個標準序列資料類型：`tuple'。

一個 tuple 是由若干個值藉由逗號區隔而組成，例如：

@example
>>> t = 12345, 54321, 'hello!'
>>> t[0]
12345
>>> t
(12345, 54321, 'hello!')
>>> # Tuple 可以為巢狀的：
>>> u = t, (1, 2, 3, 4, 5)
>>> u
((12345, 54321, 'hello!'), (1, 2, 3, 4, 5))
>>> # Tuple 為不可變的：
>>> t[0] = 88888
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: 'tuple' object does not support item assignment
>>> # but they can contain mutable objects:
>>> v = ([1, 2, 3], [3, 2, 1])
>>> v
([1, 2, 3], [3, 2, 1])
@end example

如同我們看到的，被輸出的 tuple 總是以括號包著，如此巢狀的 tuple 才能被正確的直譯 (interpret)；他們可以是以被括號包著或不被包著的方式當作輸入，雖然括號的使用常常是有其必要的（譬如此 tuple 是一個較大的運算式的一部分）。指派東西給 tuple 中的個別項目是不行的，但是可以建立含有可變物件（譬如 list）的 tuple。

雖然 tuple 和 list 看起來很類似，但是他們通常用在不同的情況與不同目的。 tuple 是 @ref{1ea7,,immutable}（不可變的），通常儲存異質的元素序列，並可經由拆解 (unpacking)（請參考本節後段）或索引 (indexing) 來存取（或者在使用 @ref{4db,,namedtuples} 的時候藉由屬性 (attribute) 來存取）。List 是 @ref{1eac,,mutable}（可變的），其元素通常是同質的且可藉由疊代整個 list 來存取。

一個特別的議題是，關於建立一個含有 0 個或 1 個項目的 tuple：語法上會採納一些奇怪的用法。空的 tuple 藉由一對空括號來建立；含有一個項目的 tuple 經由一個值加上一個逗點來建立（用括號把一個單一的值包住是不夠的）。醜，但有效率。例如：

@example
>>> empty = ()
>>> singleton = 'hello',    # <-- 注意後面有個逗號
>>> 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')，可運用在任何位在等號右邊的序列。序列拆解要求等號左邊的變數數量必須與等號右邊的序列中的元素數量相同。注意，多重指派就只是 tuple packing 和序列拆解的結合而已。

@node 集合 Sets,字典（Dictionary）,Tuples 和序列 Sequences,資料結構
@anchor{tutorial/datastructures sets}@anchor{1ef7}@anchor{tutorial/datastructures tut-sets}@anchor{1ef8}
@subsection 集合 (Sets)


Python 也包含了一種用在 `set'（集合）的資料類型。一個 set 是一組無序且沒有重複的元素。基本的使用方式包括了隸屬資格檢測和消除重複元素。 Set 物件也支援聯集、交集、差集和互斥等數學運算。

大括號或 @ref{184,,set()} 函式都可以用來建立 set。注意：要建立一個空的 set，你必須使用 @code{set()} 而不是 @code{@{@}}；後者會建立一個空的 dictionary，一種我們將在下一節討論的資料結構。

這裡是一個簡單的演示：

@example
>>> basket = @{'apple', 'orange', 'apple', 'pear', 'orange', 'banana'@}
>>> print(basket)                      # 確認重複值已被移除
@{'orange', 'banana', 'pear', 'apple'@}
>>> 'orange' in basket                 # 快速成員測試
True
>>> 'crabgrass' in basket
False

>>> # 示範對兩個字的唯一字母進行集合運算
>>>
>>> a = set('abracadabra')
>>> b = set('alacazam')
>>> a                                  # a 中的唯一字母
@{'a', 'r', 'b', 'c', 'd'@}
>>> a - b                              # 在 a 中但不在 b 中的字母
@{'r', 'd', 'b'@}
>>> a | b                              # 在 a 或 b 或兩者中的字母
@{'a', 'c', 'r', 'd', 'b', 'm', 'z', 'l'@}
>>> a & b                              # 同時在 a 和 b 中的字母
@{'a', 'c'@}
>>> a ^ b                              # 在 a 或 b 中但不在兩者中的字母
@{'r', 'd', 'b', 'm', 'z', 'l'@}
@end example

和 @ref{1ef1,,list comprehensions} 類似，也有 set comprehensions（集合綜合運算）：

@example
>>> a = @{x for x in 'abracadabra' if x not in 'abc'@}
>>> a
@{'r', 'd'@}
@end example

@node 字典（Dictionary）,迴圈技巧,集合 Sets,資料結構
@anchor{tutorial/datastructures dictionaries}@anchor{1ef9}@anchor{tutorial/datastructures tut-dictionaries}@anchor{1efa}
@subsection 字典（Dictionary）


下一個常用的 Python 內建資料類型為 `dictionary'（請參考@ref{cb4,,Mapping Types --- dict}）。 Dictionary 有時被稱為「關聯記憶體」(associative memories) 或「關聯陣列」(associative arrays)。不像序列是由一個範圍內的數字當作索引，dictionary 是由`鍵' (key) 來當索引，鍵可以是任何不可變的類型；字串和數字都可以當作鍵。Tuple 也可以當作鍵，如果他們只含有字串、數字或 tuple；若一個 tuple 直接或間接地含有任何可變的物件，它就不能當作鍵。你無法使用 list 當作鍵，因為 list 可以經由索引指派 (index assignment)、切片指派 (slice assignment) 或是像 @ref{8d4,,append()} 和 @ref{5fa,,extend()} 等方法被修改。

思考 dictionary 最好的方式是把它想成是一組`鍵值'對 (`key: value' pair) 的 set，其中鍵在同一個 dictionary 裡必須是獨一無二的。使用一對大括號可建立一個空的 dictionary：@code{@{@}}。將一串由逗號分隔的鍵值對置於大括號則可初始化字典的鍵值對。這同樣也是字典輸出時的格式。

Dictionary 主要的操作為藉由鍵來儲存一個值並且可藉由該鍵來取出該值。也可以使用 @code{del} 來刪除鍵值對。如果我們使用用過的鍵來儲存，該鍵所對應的較舊的值會被覆蓋。

使用下標 (@code{d[key]}) 來取出一個不存在的鍵所對應的值會引發 @ref{5df,,KeyError}。為了避免在存取一個可能不存在的鍵時發生這個錯誤，可以改用 @ref{1efb,,get()} 方法，如果該鍵不存在於字典中，該方法會回傳 @code{None}（或者一個指定的預設值）。

對 dictionary 使用 @code{list(d)} 會得到一個包含該字典所有鍵的 list，其排列順序為插入時的順序。（若想要排序，則使用 @code{sorted(d)} 代替即可）。如果想確認一個鍵是否已存在於字典中，可使用關鍵字 @ref{349,,in}。

這是個使用一個 dictionary 的簡單範例：

@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

函式 @ref{183,,dict()} 可直接透過一串鍵值對序列來建立 dictionary：

@example
>>> dict([('sape', 4139), ('guido', 4127), ('jack', 4098)])
@{'sape': 4139, 'guido': 4127, 'jack': 4098@}
@end example

此外，dict comprehensions 也可以透過任意鍵與值的運算式來建立 dictionary ：

@example
>>> @{x: x**2 for x in (2, 4, 6)@}
@{2: 4, 4: 16, 6: 36@}
@end example

當鍵是簡單的字串時，使用關鍵字引數 (keyword arguments) 有時會較為簡潔：

@example
>>> dict(sape=4139, guido=4127, jack=4098)
@{'sape': 4139, 'guido': 4127, 'jack': 4098@}
@end example

@node 迴圈技巧,深入了解條件 Condition,字典（Dictionary）,資料結構
@anchor{tutorial/datastructures looping-techniques}@anchor{1efc}@anchor{tutorial/datastructures tut-loopidioms}@anchor{1ebb}
@subsection 迴圈技巧


當對 dictionary 作迴圈時，鍵以及其對應的值可以藉由使用 @ref{9cb,,items()} method 來同時取得：

@example
>>> knights = @{'gallahad': 'the pure', 'robin': 'the brave'@}
>>> for k, v in knights.items():
...     print(k, v)
...
gallahad the pure
robin the brave
@end example

當對序列作迴圈時，位置索引及其對應的值可以藉由使用 @ref{1675,,enumerate()} 函式來同時取得：

@example
>>> for i, v in enumerate(['tic', 'tac', 'toe']):
...     print(i, v)
...
0 tic
1 tac
2 toe
@end example

要同時對兩個以上的序列作迴圈，可以將其以成對的方式放入 @ref{1a0,,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

要對序列作反向的迴圈，首先先寫出正向的序列，再對其使用 @ref{a5e,,reversed()} 函式：

@example
>>> for i in reversed(range(1, 10, 2)):
...     print(i)
...
9
7
5
3
1
@end example

要以迴圈對序列作排序，使用 @ref{dc2,,sorted()} 函式會得到一個新的經排序過的 list ，但不會改變原本的序列：

@example
>>> basket = ['apple', 'orange', 'apple', 'pear', 'orange', 'banana']
>>> for i in sorted(basket):
...     print(i)
...
apple
apple
banana
orange
orange
pear
@end example

對序列使用 @ref{184,,set()} 可去除重複元素。對序列使用 @ref{dc2,,sorted()} 加上 @ref{184,,set()}，則是對經過排序後的非重複元素跑迴圈的慣用方法：

@example
>>> basket = ['apple', 'orange', 'apple', 'pear', 'orange', 'banana']
>>> for f in sorted(set(basket)):
...     print(f)
...
apple
banana
orange
pear
@end example

有時我們會想要以迴圈來改變的一個 list，但是，通常建立一個新的 list 會更簡單且安全：

@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 深入了解條件 Condition,序列和其他資料類型之比較,迴圈技巧,資料結構
@anchor{tutorial/datastructures more-on-conditions}@anchor{1efd}@anchor{tutorial/datastructures tut-conditions}@anchor{1efe}
@subsection 深入了解條件 (Condition)


使用在 @code{while} 和 @code{if} 陳述式的條件句可以包含任何運算子，而不是只有比較運算子 (comparisons) 。

比較運算子 @code{in} 和 @code{not in} 用於隸屬資格檢測，在容器中檢查一個值是否存在（或不存在）。運算子 @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} 和 @code{C} 為真但 @code{B} 為假，則 @code{A and B and C} 的運算並不會執行到 @code{C}。當運算結果被當成一般值而非布林值時，短路運算子的回傳值為最後被求值的引數。

將一個比較運算或其他布林運算式的結果指派給一個變數是可以的。例如：

@example
>>> string1, string2, string3 = '@w{'}, 'Trondheim', 'Hammer Dance'
>>> non_null = string1 or string2 or string3
>>> non_null
'Trondheim'
@end example

注意，Python 與 C 語言不一樣，在運算式裡進行指派必須外顯地使用@ref{1eff,,海象運算子} @code{:=}。 這樣做避免了在 C 語言裡常見的一種問題：想要打 @code{==} 卻在運算式裡輸入 @code{=}。

@node 序列和其他資料類型之比較,,深入了解條件 Condition,資料結構
@anchor{tutorial/datastructures comparing-sequences-and-other-types}@anchor{1f00}@anchor{tutorial/datastructures tut-comparing}@anchor{1f01}
@subsection 序列和其他資料類型之比較


序列物件通常可以拿來和其他相同類型的物件做比較。這種比較使用`詞典式 (lexicographical)' 順序：首先比較各自最前面的那項，若不相同，便可決定結果；若相同，則比較下一項，以此類推，直到其中一個序列完全用完。如果被拿出來比較的兩項本身又是相同的序列類型，則詞典式比較會遞迴地執行。如果兩個序列所有的項目都相等，則此兩個序列被認為是相等的。如果其中一個序列是另一個的子序列，則較短的那個序列為較小的序列。字串的詞典式順序使用 Unicode 的編碼位置 (code point) 編號來排序個別字元。以下是一些相同序列類型的比較：

@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，等等。否則直譯器會選擇丟出一個 @ref{198,,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 模組 Module,輸入和輸出,資料結構,Python 教學
@anchor{tutorial/modules doc}@anchor{1f02}@anchor{tutorial/modules modules}@anchor{1f03}@anchor{tutorial/modules translation-repo}@anchor{1f04}@anchor{tutorial/modules tut-modules}@anchor{1f05}
@section 模組 (Module)


如果從 Python 直譯器離開後又再次進入，之前（幫函式或變數）做的定義都會消失。因此，想要寫一些比較長的程式時，你最好使用編輯器來準備要輸入給直譯器的內容，並且用該檔案來運行它。這就是一個`腳本 (script)'。隨著你的程式越變越長，你可能會想要把它分開成幾個檔案，讓它比較好維護。你可能也會想用一個你之前已經在其他程式寫好的函式，但不想要複製該函式的原始定義到所有使用它的程式裡。

為了支援這一點，Python 有一種方法可以將定義放入檔案中，並在互動模式下的直譯器中使用它們。這種檔案稱為`模組 (module)'；模組中的定義可以被 `import' 到其他模組中，或是被 `import' 至`主 (main)' 模組（在最頂層執行的腳本，以及互動模式下，所使用的變數集合）。

模組是指包含 Python 定義和語句的檔案，檔案名稱是模組名稱加上 @code{.py}。在模組中，模組的名稱（作為字串）會是全域變數 @code{__name__} 的值。例如，用你喜歡的文字編輯器在資料夾中創一個名為 @code{fibo.py} 的檔案，內容如下：

@example
# 費波那契數模組

def fib(n):
    """寫出費波那契數列至第 n 位。"""
    a, b = 0, 1
    while a < n:
        print(a, end=' ')
        a, b = b, a+b
    print()

def fib2(n):
    """回傳費波那契數列至第 n 位。"""
    result = []
    a, b = 0, 1
    while a < n:
        result.append(a)
        a, b = b, a+b
    return result
@end example

現在進入 Python 直譯器並用以下指令 import 這個模組：

@example
>>> import fibo
@end example

這並不會將 @code{fibo} 中定義的函式名稱直接加入目前的 @ref{1f06,,namespace} 中（詳情請見 @ref{1f07,,Python 作用域 (Scope) 及命名空間 (Namespace)}）；它只會加入 @code{fibo} 的模組名稱。使用此模組名稱，就可以存取函式：

@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
* 深入了解模組:: 
* 標準模組:: 
* dir() 函式: dir 函式. 
* 套件 (Package): 套件 Package. 

@end menu

@node 深入了解模組,標準模組,,模組 Module
@anchor{tutorial/modules more-on-modules}@anchor{1f08}@anchor{tutorial/modules tut-moremodules}@anchor{1f09}
@subsection 深入了解模組


模組可以包含可執行的陳述式以及函式的定義。這些陳述式是作為模組的初始化，它們只會在`第一次'被 import 時才會執行。@footnote{
實際上，函式定義也是「被執行」的「陳述式」；在執行模組階層的函式定義時，會將函式名稱加到模組的全域命名空間。
}（如果檔案被當成腳本執行，也會執行它們）。

每個模組都有它自己的私有命名空間 (namespace)，模組內定義的函式會把該模組的私有符號表當成全域命名空間使用。因此，模組的作者可以在模組中使用全域變數，而不必擔心和使用者的全域變數發生意外的名稱衝突。另一方面，如果你知道自己在做什麼，你可以用這個方式取用模組的全域變數，以和引用函式一樣的寫法，@code{modname.itemname}。

在一個模組中可以 import 其他模組。把所有的 @ref{7f1,,import} 陳述式放在模組（就這邊來說，腳本也是一樣）的最開頭是個慣例，但並沒有強制。如放置在模組的最高層（不在任何函式或 class 中），被 import 的模組名稱將被加入全域命名空間中。

@ref{7f1,,import} 陳述式有另一種變形寫法，可以直接將名稱從欲 import 的模組，直接 import 至原模組的命名空間中。例如：

@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

在 import 之後的名稱會被導入，但定義該函式的整個模組名稱並不會被引入在區域命名空間中（因此，示例中的 @code{fibo} 未被定義）。

甚至還有另一種變形寫法，可以 import 模組定義的所有名稱：

@example
>>> from fibo import *
>>> fib(500)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377
@end example

這個寫法會 import 模組中所有的名稱，除了使用底線 (@code{_}) 開頭的名稱。大多數情況下，Python 程式設計師不大使用這個功能，因為它在直譯器中引入了一組未知的名稱，並且可能覆蓋了某些你已經定義的內容。

請注意，一般情況下並不建議從模組或套件中 import @code{*} 的做法，因為它通常會導致可讀性較差的程式碼。但若是使用它來在互動模式中節省打字時間，則是可以接受的。

如果模組名稱後面出現 @code{as}，則 @code{as} 之後的名稱將直接和被 import 模組綁定在一起。

@example
>>> import fibo as fib
>>> fib.fib(500)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377
@end example

這個 import 方式和 @code{import fibo} 實質上是一樣的，唯一的差別是現在要用 @code{fib} 使用模組。

在使用 @ref{14ac,,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 備註 
出於效率原因，每個模組在每個直譯器 session 中僅會被 import 一次。因此，如果你更改了模組，則必須重啟直譯器——或者，如果只是一個想要在互動模式下測試的模組，可以使用 @ref{736,,importlib.reload()}。例如：@code{import importlib; importlib.reload(modulename)}。
@end quotation
@end cartouche

@menu
* 把模組當作腳本執行:: 
* 模組的搜尋路徑:: 
* 「編譯」Python 檔案:: 

@end menu

@node 把模組當作腳本執行,模組的搜尋路徑,,深入了解模組
@anchor{tutorial/modules executing-modules-as-scripts}@anchor{1f0a}@anchor{tutorial/modules tut-modulesasscripts}@anchor{1f0b}
@subsubsection 把模組當作腳本執行


當使用以下內容運行 Python 模組時：

@example
python fibo.py <arguments>
@end example

如同使用 import 指令，模組中的程式碼會被執行，但 @code{__name__} 被設為 @code{"__main__"}。這意味著，透過在模組的末尾添加以下程式碼：

@example
if __name__ == "__main__":
    import sys
    fib(int(sys.argv[1]))
@end example

你可以將檔案作為腳本也同時可以作為被 import 的模組，因為剖析 (parse) 命令列的程式碼只會在當模組是「主」檔案時，才會執行：

@example
$ python fibo.py 50
0 1 1 2 3 5 8 13 21 34
@end example

如果此模組是被 import 的，則該段程式碼不會被執行：

@example
>>> import fibo
>>>
@end example

這通常是用來為模組提供方便的使用者介面，或者用於測試目的（執行測試套件時，以腳本的方式執行模組）。

@node 模組的搜尋路徑,「編譯」Python 檔案,把模組當作腳本執行,深入了解模組
@anchor{tutorial/modules the-module-search-path}@anchor{1f0c}@anchor{tutorial/modules tut-searchpath}@anchor{1f0d}
@subsubsection 模組的搜尋路徑


@geindex module（模組）;search（搜尋）;path（路徑）

Import 一個名為 @code{spam} 的模組時，直譯器首先會搜尋具有該名稱的內建模組。模組名稱列在 @ref{1f0e,,sys.builtin_module_names} 當中。如果找不到，接下來會在變數 @ref{3e2,,sys.path} 所給定的資料夾清單之中，搜尋一個名為 @code{spam.py} 的檔案。@ref{3e2,,sys.path} 從這些位置開始進行初始化：


@itemize *

@item 
輸入腳本所位在的資料夾（如未指定檔案時，則是目前資料夾）。

@item 
@geindex PYTHONPATH
@geindex 環境變數; PYTHONPATH
@ref{1218,,PYTHONPATH}（一連串和 shell 變數 
@geindex PATH
@geindex 環境變數; PATH
@code{PATH} 的語法相同的資料夾名稱）。

@item 
與安裝相關的預設值（按慣例會包含一個 @code{site-packages} 資料夾，它是由 @ref{cc,,site} 模組所處理）。
@end itemize

在 @ref{1849,,sys.path 模組搜尋路徑的初始化} 有更多的細節。

@cartouche
@quotation 備註 
在支援符號連結 (symlink) 的檔案系統中，輸入腳本的所在資料夾是在跟隨符號連結之後才被計算的。換言之，包含符號連結的資料夾`並沒有'增加到模組的搜尋路徑中。
@end quotation
@end cartouche

初始化之後，Python 程式可以修改 @ref{3e2,,sys.path}。執行中腳本的所在資料夾會在搜尋路徑的開頭，在標準函式庫路徑之前。這代表該資料夾中的腳本會優先被載入，而不是函式庫資料夾中相同名稱的模組。除非是有意要做這樣的替換，否則這是一個錯誤。 請參見@ref{1f0f,,標準模組}以瞭解更多資訊。

@c %
@c Do we need stuff on zip files etc. ? DUBOIS

@node 「編譯」Python 檔案,,模組的搜尋路徑,深入了解模組
@anchor{tutorial/modules compiled-python-files}@anchor{1f10}@anchor{tutorial/modules tut-pycache}@anchor{8e3}
@subsubsection 「編譯」Python 檔案


為了加快載入模組的速度，Python 將每個模組的編譯版本暫存在 @code{__pycache__} 資料夾下，並命名為 @code{module.`version'.pyc}， 這裡的 version 是編譯後的檔案的格式名稱，且名稱通常會包含 Python 的版本編號。例如，在 CPython 3.3 中，spam.py 的編譯版本將被暫存為 @code{__pycache__/spam.cpython-33.pyc}。此命名準則可以讓來自不同版本的編譯模組和 Python 的不同版本同時共存。

Python 根據原始碼最後修改的日期，檢查編譯版本是否過期而需要重新編譯。這是一個完全自動的過程。另外，編譯後的模組獨立於平台，因此不同架構的作業系統之間可以共用同一函式庫。

Python 在兩種情況下不檢查快取 (cache)。首先，它總是重新編譯且不儲存直接從命令列載入的模組的結果。第二，如果沒有源模組，則不會檢查快取。要支援非源模組（僅編譯）的發布，編譯後的模組必須位於原始資料夾中，並且不能有源模組。

一些給專家的秘訣：


@itemize *

@item 
可以在 Python 指令上使用開關參數 (switch) @ref{18c,,-O} 或 @ref{fb0,,-OO} 來減小已編譯模組的大小。開關參數 @code{-O} 刪除 assert（斷言）陳述式，而 @code{-OO} 同時刪除 assert 陳述式和 __doc__ 字串。由於有些程式可能依賴於上述這些內容，因此只有在你知道自己在做什麼時，才應使用此參數。「已優化」模組有 @code{opt-} 標記，且通常較小。未來的版本可能會改變優化的效果。

@item 
讀取 @code{.pyc} 檔案時，程式的執行速度並不會比讀取 @code{.py} 檔案快。唯一比較快的地方是載入的速度。

@item 
模組 @ref{21,,compileall} 可以為資料夾中的所有模組建立 .pyc 檔。

@item 
更多的細節，包括決策流程圖，請參考
@geindex Python Enhancement Proposals; PEP 3147
PEP 3147@footnote{https://peps.python.org/pep-3147/}。
@end itemize

@node 標準模組,dir 函式,深入了解模組,模組 Module
@anchor{tutorial/modules standard-modules}@anchor{1f11}@anchor{tutorial/modules tut-standardmodules}@anchor{1f0f}
@subsection 標準模組


@geindex module（模組）;sys

Python 附帶了一個標準模組庫，詳細的介紹在另一份文件，稱為「Python 函式庫參考手冊」（簡稱為「函式庫參考手冊」）。有些模組是直譯器中內建的；它們使一些不屬於語言核心但依然內建的運算得以存取，其目的是為了提高效率，或提供作業系統基本操作（例如系統呼叫）。這些模組的集合是一個組態選項，它們取決於底層平台。例如：@ref{11c,,winreg} 模組僅供 Windows 使用。值得注意的模組是 @ref{df,,sys}，它被內建在每個 Python 直譯器中。變數 @code{sys.ps1} 和 @code{sys.ps2} 則用來定義主、次提示字元的字串：

@example
>>> import sys
>>> sys.ps1
'>>> '
>>> sys.ps2
'... '
>>> sys.ps1 = 'C> '
C> print('Yuck!')
Yuck!
C>
@end example

只有直譯器在互動模式時，才需要定義這兩個變數。

變數 @code{sys.path} 是一個字串 list，它決定直譯器的模組搜尋路徑。它的初始值為環境變數 
@geindex PYTHONPATH
@geindex 環境變數; PYTHONPATH
@ref{1218,,PYTHONPATH} 中提取的預設路徑，或是當 
@geindex PYTHONPATH
@geindex 環境變數; PYTHONPATH
@ref{1218,,PYTHONPATH} 未設定時，從內建預設值提取。你可以用標準的 list 操作修改該變數：

@example
>>> import sys
>>> sys.path.append('/ufs/guido/lib/python')
@end example

@node dir 函式,套件 Package,標準模組,模組 Module
@anchor{tutorial/modules the-dir-function}@anchor{1f12}@anchor{tutorial/modules tut-dir}@anchor{1f13}
@subsection @code{dir()} 函式


內建函式 @ref{83d,,dir()} 用於找出模組定義的所有名稱。它回傳一個排序後的字串 list：

@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{83d,,dir()} 列出目前已定義的名稱：

@example
>>> a = [1, 2, 3, 4, 5]
>>> import fibo
>>> fib = fibo.fib
>>> dir()
['__builtins__', '__name__', 'a', 'fib', 'fibo', 'sys']
@end example

請注意，它列出所有類型的名稱：變數、模組、函式等。

@geindex module（模組）;builtins（內建）

@ref{83d,,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 套件 Package,,dir 函式,模組 Module
@anchor{tutorial/modules packages}@anchor{1f14}@anchor{tutorial/modules tut-packages}@anchor{1f15}
@subsection 套件 (Package)


套件是一種使用「點分隔模組名稱」組織 Python 模組命名空間的方法。例如，模組名稱 @code{A.B} 表示套件 @code{A} 中名為 @code{B} 的子模組。正如模組使用時，不同模組的作者不需擔心與其他模組的全域變數名稱重複，點分隔模組名稱的使用，也讓多模組套件（像 NumPy 或 Pillow）的作者們不須擔心其他套件的模組名稱。

假設你想設計一個能統一處理音訊檔案及音訊數據的模組集（「套件」）。因為音訊檔案有很多的不同的格式（通常以它們的副檔名來辨識，例如：@code{.wav}、@code{.aiff}、@code{.au}），因此，為了不同檔案格式之間的轉換，你會需要建立和維護一個不斷增長的模組集合。為了要達成對音訊數據的許多不同作業（例如，音訊混合、增加回聲、套用等化器功能、創造人工立體音效），你將編寫一系列無止盡的模組來執行這些作業。以下是你的套件可能的架構（以階層式檔案系統的方式表示）：

@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

Import 套件時，Python 會搜尋 @code{sys.path} 裡的目錄，尋找套件的子目錄。

目錄中必須含有 @code{__init__.py} 檔案，才會被 Pyhon 當成套件（除非有使用 @ref{2b2,,namespace package}，為一個相對進階的功能）；這樣可以避免一些以常用名稱命名（例如 @code{string}）的目錄，無意中隱藏了較晚出現在模組搜尋路徑中的有效模組。在最簡單的情況，@code{__init__.py} 可以只是一個空白檔案；但它也可以執行套件的初始化程式碼，或設置 @code{__all__} 變數，之後會詳述。

套件使用者可以從套件中 import 個別模組，例如：

@example
import sound.effects.echo
@end example

這樣就載入了子模組 @code{sound.effects.echo}。引用時必須用它的全名：

@example
sound.effects.echo.echofilter(input, output, delay=0.7, atten=4)
@end example

另一種 import 子模組的方法是：

@example
from sound.effects import echo
@end example

這段程式碼一樣可以載入子模組 @code{echo}，並且不加套件前綴也可以使用，因此能以如下方式使用：

@example
echo.echofilter(input, output, delay=0.7, atten=4)
@end example

另一種變化是直接 import 所需的函式或變數：

@example
from sound.effects.echo import echofilter
@end example

同樣地，這樣也會載入子模組 @code{echo}，但它的函式 @code{echofilter()} 就可以直接使用：

@example
echofilter(input, output, delay=0.7, atten=4)
@end example

請注意，使用 @code{from package import item} 時，item 可以是套件的子模組（或子套件），也可以是套件中被定義的名稱，像是函式、class （類別）或變數。@code{import} 陳述式首先測試套件中有沒有定義該 item；如果沒有，則會假設它是模組，並嘗試載入。如果還是找不到 item，則會引發 @ref{653,,ImportError} 例外。

相反地，使用 @code{import item.subitem.subsubitem} 語法時，除了最後一項之外，每一項都必須是套件；最後一項可以是模組或套件，但不能是前一項中定義的 class、函式或變數。

@menu
* 從套件中 import *:: 
* 套件內引用:: 
* 多目錄中的套件:: 

@end menu

@node 從套件中 import *,套件內引用,,套件 Package
@anchor{tutorial/modules importing-from-a-package}@anchor{1f16}@anchor{tutorial/modules tut-pkg-import-star}@anchor{1f17}
@subsubsection 從套件中 import *


@geindex __all__

當使用者寫下 @code{from sound.effects import *} 時，會發生什麼事？理想情況下，我們可能希望程式碼會去檔案系統，尋找套件中存在的子模組，並將它們全部 import。這會花費較長的時間，且 import 子模組的過程可能會有不必要的副作用，這些副作用只有在明確地 import 子模組時才會發生。

唯一的解法是由套件作者為套件提供明確的索引。@ref{7f1,,import} 陳述式使用以下慣例：如果套件的 @code{__init__.py} 程式碼有定義一個名為 @code{__all__} 的 list，若遇到 @code{from package import *} 的時候，它就會是要被 import 的模組名稱。發布套件的新版本時，套件作者可自行決定是否更新此 list。如果套件作者認為沒有人會從他的套件中 import *，他也可能會決定不支援這個 list。舉例來說，@code{sound/effects/__init__.py} 檔案可包含以下程式碼：

@example
__all__ = ["echo", "surround", "reverse"]
@end example

意思是，@code{from sound.effects import *} 將會 import @code{sound.effects} 套件中，這三個被提名的子模組。

請注意，子模組可能會被區域定義 (locally defined) 的名稱遮蔽。例如，如果你在 @code{sound/effects/__init__.py} 檔案中新增了一個 @code{reverse} 函式，則 @code{from sound.effects import *} 只會引入兩個子模組 @code{echo} 和 @code{surround}，但`不是' @code{reverse} 子模組，因為它被區域定義的 @code{reverse} 函式遮蔽了：

@example
__all__ = [
    "echo",      # 指向 'echo.py' 檔案
    "surround",  # 指向 'surround.py' 檔案
    "reverse",   # !!! 現在指向 'reverse' 函式 !!!
]

def reverse(msg: str):  #  <-- 在 'from sound.effects import *' 的情況下
    return msg[::-1]    #     這個名稱遮蔽了 'reverse.py' 子模組
@end example

如果 @code{__all__} 沒有被定義，@code{from sound.effects import *} 陳述式`並不會'把 @code{sound.effects} 套件中所有子模組都 import 到目前的命名空間；它只保證 @code{sound.effects} 套件有被 import（可能會運行 @code{__init__.py} 中的初始化程式碼），然後 import 套件中被定義的全部名稱。這包含 @code{__init__.py} 定義（以及被明確載入的子模組）的任何名稱。它也包括任何之前被 @ref{7f1,,import} 陳述式明確載入的套件子模組。請看以下程式碼：

@example
import sound.effects.echo
import sound.effects.surround
from sound.effects import *
@end example

此例中，當 @code{from...import} 陳述式被執行時，@code{echo} 和 @code{surround} 模組被 import 進目前的命名空間，因為它們是在 @code{sound.effects} 套件裡定義的。（當 @code{__all__} 有被定義時，這規則也有效。）

雖然，有些特定模組的設計，讓你使用 @code{import *} 時，該模組只會輸出遵循特定樣式的名稱，但在正式環境 (production) 的程式碼中這仍然被視為是不良習慣。

記住，使用 @code{from package import specific_submodule} 不會有任何問題！實際上，這是推薦用法，除非 import 的模組需要用到的子模組和其他套件的子模組同名。

@node 套件內引用,多目錄中的套件,從套件中 import *,套件 Package
@anchor{tutorial/modules id2}@anchor{1f18}@anchor{tutorial/modules intra-package-references}@anchor{1f19}
@subsubsection 套件內引用


當套件的結構為多個子套件的組合時（如同範例中的 @code{sound} 套件），可以使用「絕對 (absolute) import」，引用同層套件中的子模組。例如，要在 @code{sound.filters.vocoder} 模組中使用 @code{sound.effects} 中的 @code{echo} 模組時，可以用 @code{from sound.effects import echo}。

你也可以用 @code{from module import name} 的 import 陳述式，編寫「相對 (relative) import」。這些 import 使用前導句號指示相對 import 中的目前套件和母套件。例如，在 @code{urround} 模組中，你可以使用：

@example
from . import echo
from .. import formats
from ..filters import equalizer
@end example

請注意，相對 import 的運作是以目前模組的套件名稱為依據。因為主模組並沒有套件，所以如果一個模組預期被用作 Python 應用程式的主模組，那它必須永遠使用絕對引入。

@node 多目錄中的套件,,套件內引用,套件 Package
@anchor{tutorial/modules packages-in-multiple-directories}@anchor{1f1a}
@subsubsection 多目錄中的套件


套件也支援一個特殊屬性 @ref{1f1b,,__path__}。它在初始化時是一個字串的@ref{70f,,序列}的 @code{__init__.py} 檔案所在的目錄名稱，初始化時機是在這個檔案的程式碼被執行之前。這個變數可以被修改，但這樣做會影響將來對套件內的模組和子套件的搜尋。

雖然這個特色不太常被需要，但它可用於擴充套件中的模組集合。

@subsubheading 註解


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node 輸入和輸出,錯誤和例外,模組 Module,Python 教學
@anchor{tutorial/inputoutput doc}@anchor{1f1c}@anchor{tutorial/inputoutput input-and-output}@anchor{1f1d}@anchor{tutorial/inputoutput translation-repo}@anchor{1f1e}@anchor{tutorial/inputoutput tut-io}@anchor{1f1f}
@section 輸入和輸出


有數種方式可以顯示程式的輸出；資料可以以人類易讀的形式印出，或是寫入檔案以供未來所使用。這章節會討論幾種不同的方式。

@menu
* 更華麗的輸出格式:: 
* 讀寫檔案:: 

@end menu

@node 更華麗的輸出格式,讀寫檔案,,輸入和輸出
@anchor{tutorial/inputoutput fancier-output-formatting}@anchor{1f20}@anchor{tutorial/inputoutput tut-formatting}@anchor{1f21}
@subsection 更華麗的輸出格式


目前為止我們已經學過兩種寫值的方式：`運算式陳述 (expression statements)' 與 @ref{1170,,print()} 函式。（第三種方法是使用檔案物件的 @ref{1f22,,write()} 方法；標準輸出的檔案是使用 @code{sys.stdout} 來達成的。詳細的資訊請參考對應的函式庫說明。）

通常你會想要對輸出格式有更多地控制，而不是僅列印出以空格隔開的值。以下是幾種格式化輸出的方式。


@itemize *

@item 
要使用@ref{1f23,,格式化字串文本 (formatted string literals)}，需在字串開始前的引號或連續三個引號前加上 @code{f} 或 @code{F}。你可以在這個字串中使用 @code{@{} 與 @code{@}} 包夾 Python 的運算式，引用變數或其他字面值 (literal values)。

@example
>>> year = 2016
>>> event = 'Referendum'
>>> f'Results of the @{year@} @{event@}'
'Results of the 2016 Referendum'
@end example

@item 
字串的 @ref{82c,,str.format()} method 需要更多手動操作。你還是可以用 @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{4f4,,格式規格 (Format Specification) 迷你語言}）。

@item 
最後，你還可以自己用字串切片 (slicing) 和串接 (concatenation) 操作，完成所有的字串處理，建立任何你能想像的排版格式。字串型別有一些 method，能以給定的欄寬填補字串，這些運算也很有用。
@end itemize

如果你不需要華麗的輸出，只想快速顯示變數以進行除錯，可以用 @ref{1c1,,repr()} 或 @ref{169,,str()} 函式把任何的值轉換為字串。

@ref{169,,str()} 函式的用意是回傳一個人類易讀的表示法，而 @ref{1c1,,repr()} 的用意是產生直譯器可讀取的表示法（如果沒有等效的語法，則造成 @ref{18e,,SyntaxError}）。如果物件沒有人類易讀的特定表示法，@ref{169,,str()} 會回傳與 @ref{1c1,,repr()} 相同的值。有許多的值，像是數字，或 list 及 dictionary 等結構，使用這兩個函式會有相同的表示法。而字串，則較為特別，有兩種不同的表示法。

一些範例：

@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...
>>> # 字串的 repr() 會加上字串引號和反斜線：
>>> hello = 'hello, world\n'
>>> hellos = repr(hello)
>>> print(hellos)
'hello, world\n'
>>> # repr() 的引數可以是任何 Python 物件：
>>> repr((x, y, ('spam', 'eggs')))
"(32.5, 40000, ('spam', 'eggs'))"
@end example

@ref{d8,,string} 模組包含一個基於正規表示式 (regular expressions)、透過 @ref{890,,string.Template} 的簡單模板化手段的支援。這提供了另一種將值替換到字串中的方式，使用像 @code{$x} 這樣的佔位符號，並用來自字典的值取代它們。這種語法較易用，但它在格式化方面提供的控制較少。

@geindex formatted string literal（格式化的字串常數）
@geindex interpolated string literal（內插字串常數）
@geindex string（字串）;formatted literal（格式化的文本）
@geindex string（字串）;interpolated literal（插值常數）
@geindex f-string（f 字串）
@geindex fstring（f 字串）

@menu
* 格式化的字串文本 (Formatted String Literals): 格式化的字串文本 Formatted String Literals. 
* 字串的 format() method: 字串的 format method. 
* 手動格式化字串:: 
* 格式化字串的舊方法:: 

@end menu

@node 格式化的字串文本 Formatted String Literals,字串的 format method,,更華麗的輸出格式
@anchor{tutorial/inputoutput formatted-string-literals}@anchor{1f24}@anchor{tutorial/inputoutput tut-f-strings}@anchor{1f23}
@subsubsection 格式化的字串文本 (Formatted String Literals)


@ref{19a,,格式化的字串文本}（簡稱為 f-字串），透過在字串加入前綴 @code{f} 或 @code{F}，並將運算式編寫為 @code{@{expression@}}，讓你可以在字串內加入 Python 運算式的值。

格式說明符 (format 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{15dd,,ascii()}，@code{'!s'} 會套用 @ref{169,,str()}，@code{'!r'} 會套用 @ref{1c1,,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

@code{=} 說明符可用於將一個運算式擴充為該運算式的文字、一個等號、以及對該運算式求值 (evaluate) 後的表示法：

@example
>>> bugs = 'roaches'
>>> count = 13
>>> area = 'living room'
>>> print(f'Debugging @{bugs=@} @{count=@} @{area=@}')
Debugging bugs='roaches' count=13 area='living room'
@end example

更多關於 @code{=} 說明符的資訊請見@ref{b96,,自文件性運算式 (self-documenting expressions)}。若要參考這些格式化字串的規格，詳見 @ref{4f4,,格式規格 (Format Specification) 迷你語言} 參考指南。

@node 字串的 format method,手動格式化字串,格式化的字串文本 Formatted String Literals,更華麗的輸出格式
@anchor{tutorial/inputoutput the-string-format-method}@anchor{1f25}@anchor{tutorial/inputoutput tut-string-format}@anchor{1f26}
@subsubsection 字串的 format() method


@ref{82c,,str.format()} method 的基本用法如下：

@example
>>> print('We are the @{@} who say "@{@}!"'.format('knights', 'Ni'))
We are the knights who say "Ni!"
@end example

大括號及其內的字元（稱為格式欄位）會被取代為傳遞給 @ref{82c,,str.format()} method 的物件。大括號中的數字表示該物件在傳遞給 @ref{82c,,str.format()} method 時所在的位置。

@example
>>> print('@{0@} and @{1@}'.format('spam', 'eggs'))
spam and eggs
>>> print('@{1@} and @{0@}'.format('spam', 'eggs'))
eggs and spam
@end example

如果在 @ref{82c,,str.format()} method 中使用關鍵字引數，可以使用引數名稱去引用它們的值。

@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

如果你有一個不想分割的長格式化字串，比較好的方式是按名稱而不是按位置來引用變數。這項操作可以透過傳遞字典 (dict)，並用方括號 @code{'[]'} 使用鍵 (key) 來輕鬆完成。

@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} 字典當作關鍵字引數來傳遞，也有一樣的結果。

@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

與內建函式 @ref{1ceb,,vars()} 組合使用時，這種方式特別實用。該函式可以回傳一個包含所有區域變數的 dictionary：

@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{82c,,str.format()} 進行字串格式化的完整概述，請見@ref{1593,,格式化文字語法}。

@node 手動格式化字串,格式化字串的舊方法,字串的 format method,更華麗的輸出格式
@anchor{tutorial/inputoutput manual-string-formatting}@anchor{1f27}
@subsubsection 手動格式化字串


下面是以手動格式化完成的同一個平方及立方的表：

@example
>>> for x in range(1, 11):
...     print(repr(x).rjust(2), repr(x*x).rjust(3), end=' ')
...     # 注意前一列使用的 'end'
...     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{1170,,print()} 讓每欄之間加入一個空格的方法：這種方法總是在其引數間加入空格。）

字串物件的 @ref{1f28,,str.rjust()} method 透過在左側填補空格，使字串以給定的欄寬進行靠右對齊。類似的 method 還有 @ref{1f29,,str.ljust()} 和 @ref{1f2a,,str.center()}。這些 method 不寫入任何內容，只回傳一個新字串，如果輸入的字串太長，它們不會截斷字串，而是不做任何改變地回傳；雖然這樣會弄亂欄的編排，但這通常還是比另一種情況好，那種情況會讓值變得不正確。（如果你真的想截斷字串，可以加入像 @code{x.ljust(n)[:n]} 這樣的切片運算。）

另一種 method 是 @ref{16a6,,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{1f2b}
@subsubsection 格式化字串的舊方法


% 運算子（modulo，模數）也可用於字串格式化。在 @code{format % values} 中（其中 `format' 是個字串），`format' 內的 @code{%} 轉換規格會被 `values' 的零個或多個元素所取代。此運算常被稱為字串插值 (string interpolation)。例如：

@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{8d3,,printf-style String Formatting}小節。

@node 讀寫檔案,,更華麗的輸出格式,輸入和輸出
@anchor{tutorial/inputoutput reading-and-writing-files}@anchor{1f2c}@anchor{tutorial/inputoutput tut-files}@anchor{1f2d}
@subsection 讀寫檔案


@geindex built-in function（內建函式）;open
@geindex object（物件）;file（檔案）

@ref{315,,open()} 回傳一個 @ref{13c4,,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' 開啟，意即，從檔案中讀取或寫入字串時，都以特定編碼方式 `encoding' 進行編碼。如未指定 `encoding'，則預設值會取決於系統平台（見 @ref{315,,open()}）。因為 UTF-8 是現時的標準，除非你很清楚該用什麼編碼，否則推薦使用 @code{encoding="utf-8"}。在 mode 後面加上 @code{'b'} 會以 `binary mode'（二進制模式）開啟檔案，二進制模式資料以 @ref{192,,bytes} 物件的形式被讀寫。以二進制模式開啟檔案時不可以指定 `encoding'。

在文字模式 (text mode) 下，讀取時會預設把平台特定的行尾符號（Unix 上為 @code{\n}，Windows 上為 @code{\r\n}）轉換為 @code{\n}。在文字模式下寫入時，預設會把 @code{\n} 出現之處轉換回平台特定的行尾符號。這種在幕後對檔案資料的修改方式對文字檔案來說沒有問題，但會毀壞像是 @code{JPEG} 或 @code{EXE} 檔案中的二進制資料。在讀寫此類檔案時，注意一定要使用二進制模式。

在處理檔案物件時，使用 @ref{186,,with} 關鍵字是個好習慣。優點是，當它的套件結束後，即使在某個時刻引發了例外，檔案仍會正確地被關閉。使用 @code{with} 也比寫等效的 @ref{8f0,,try}-@ref{1b0,,finally} 區塊，來得簡短許多：

@example
>>> with open('workfile', encoding="utf-8") as f:
...     read_data = f.read()

>>> # 我們可以檢查確認該檔案已經自動被關閉。
>>> f.closed
True
@end example

如果你沒有使用 @ref{186,,with} 關鍵字，則應呼叫 @code{f.close()} 關閉檔案，可以立即釋放被它所使用的系統資源。

@cartouche
@quotation 警告 
呼叫 @code{f.write()} 時，若未使用 @code{with} 關鍵字或呼叫 @code{f.close()}，即使程式成功退出，也`可能'導致 @code{f.write()} 的引數沒有被完全寫入硬碟。
@end quotation
@end cartouche

@c See also https://bugs.python.org/issue17852

不論是透過 @ref{186,,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
* 檔案物件的 method:: 
* 使用 json 儲存結構化資料:: 

@end menu

@node 檔案物件的 method,使用 json 儲存結構化資料,,讀寫檔案
@anchor{tutorial/inputoutput methods-of-file-objects}@anchor{1f2e}@anchor{tutorial/inputoutput tut-filemethods}@anchor{1f2f}
@subsubsection 檔案物件的 method


本節其餘的範例皆假設一個名為 @code{f} 的檔案物件已被建立。

要讀取檔案的內容，可呼叫 @code{f.read(size)}，它可讀取一部份的資料，並以字串（文字模式）或位元組串物件（二進制模式）形式回傳。`size' 是個選擇性的數字引數。當 `size' 被省略或為負數時，檔案的全部內容會被讀取並回傳；如果檔案是機器記憶體容量的兩倍大時，這會是你的問題。否則，最多只有等同於 `size' 數量的字元（文字模式）或 `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

想從檔案中讀取多行時，可以對檔案物件進行迴圈。這種方法能有效地使用記憶體、快速，且程式碼簡潔：

@example
>>> for line in f:
...     print(line, end='@w{'})
...
This is the first line of the file.
Second line of the file
@end example

如果你想把一個檔案的所有行讀進一個 list 裡，可以用 @code{list(f)} 或 @code{f.readlines()}。

@code{f.write(string)} 把 `string' 的內容寫入檔案，並回傳寫入的字元數。

@example
>>> f.write('This is a test\n')
15
@end example

寫入其他類型的物件之前，要先把它們轉換為字串（文字模式）或位元組串物件（二進制模式）：

@example
>>> value = ('the answer', 42)
>>> s = str(value)  # 將元組轉換成字串
>>> f.write(s)
18
@end example

@code{f.tell()} 回傳一個整數，它給出檔案物件在檔案中的目前位置，在二進制模式下表示為檔案開始至今的位元組數，在文字模式下表示為一個意義不明的數字。

使用 @code{f.seek(offset, whence)} 可以改變檔案物件的位置。位置計算方法是從一個參考點增加 `offset' 的偏移量；參考點則由引數 `whence' 來選擇。當 `whence' 值為 0 時，表示使用檔案開頭，1 表示使用目前的檔案位置，2 表示使用檔案末端作為參考點。`whence' 可省略，其預設值為 0，即以檔案開頭作為參考點。

@example
>>> f = open('workfile', 'rb+')
>>> f.write(b'0123456789abcdef')
16
>>> f.seek(5)      # 跳到檔案中的第六個位元組
5
>>> f.read(1)
b'5'
>>> f.seek(-3, 2)  # 跳到結尾前的第三個位元組
13
>>> f.read(1)
b'd'
@end example

在文字檔案（開啟時模式字串未加入 @code{b} 的檔案）中，只允許以檔案開頭為參考點進行尋找（但 @code{seek(0, 2)} 尋找檔案最末端是例外），且只有從 @code{f.tell()} 回傳的值，或是 0，才是有效的 `offset' 值。其他任何 `offset' 值都會產生未定義的行為。

檔案物件還有一些附加的 method，像是較不常使用的 @ref{1f30,,isatty()} 和 @ref{1511,,truncate()}；檔案物件的完整指南詳見程式庫參考手冊。

@node 使用 json 儲存結構化資料,,檔案物件的 method,讀寫檔案
@anchor{tutorial/inputoutput saving-structured-data-with-json}@anchor{1f31}@anchor{tutorial/inputoutput tut-json}@anchor{1f32}
@subsubsection 使用 @code{json} 儲存結構化資料


@geindex module（模組）;json

字串可以簡單地從檔案中被寫入和讀取。數字則稍嫌麻煩，因為 @ref{1f33,,read()} method 只回傳字串，這些字串必須傳遞給像 @ref{19b,,int()} 這樣的函式，它接受 @code{'123'} 這樣的字串，並回傳數值 123。當你想儲存像是巢狀 list 和 dictionary（字典）等複雜的資料類型時，手動剖析 (parsing) 和序列化 (serializing) 就變得複雜。

相較於讓使用者不斷地編寫和除錯程式碼才能把複雜的資料類型儲存到檔案，Python 支援一個普及的資料交換格式，稱為 JSON (JavaScript Object Notation)@footnote{https://json.org}。標準模組 @ref{86,,json} 可接收 Python 資料階層，並將它們轉換為字串表示法；這個過程稱為 `serializing'（序列化）。從字串表示法中重建資料則稱為 `deserializing'（反序列化）。在序列化和反序列化之間，表示物件的字串可以被儲存在檔案或資料中，或通過網路連接發送到遠端的機器。

@cartouche
@quotation 備註 
JSON 格式經常地使用於現代應用程式的資料交換。許多程序設計師早已對它耳熟能詳，使它成為提升互操作性 (interoperability) 的好選擇。
@end quotation
@end cartouche

如果你有一個物件 @code{x}，只需一行簡單的程式碼即可檢視它的 JSON 字串表示法：

@example
>>> import json
>>> x = [1, 'simple', 'list']
>>> json.dumps(x)
'[1, "simple", "list"]'
@end example

@ref{f3c,,dumps()} 函式有一個變體，稱為 @ref{f3b,,dump()}，它單純地將物件序列化為 @ref{1f34,,text file}。因此，如果 @code{f} 是一個為了寫入而開啟的 @ref{1f34,,text file} 物件，我們可以這樣做：

@example
json.dump(x, f)
@end example

若 @code{f} 是一個已開啟、可讀取的 @ref{1f35,,binary file} 或 @ref{1f34,,text file} 物件，要再次解碼物件的話：

@example
x = json.load(f)
@end example

@cartouche
@quotation 備註 
JSON 檔案必須以 UTF-8 格式編碼。在開啟 JSON 檔案以作為一個可讀取與寫入的 @ref{1f34,,text file} 時，要用 @code{encoding="utf-8"}。
@end quotation
@end cartouche

這種簡單的序列化技術可以處理 list 和 dictionary，但要在 JSON 中序列化任意的 class（類別）實例，則需要一些額外的工作。@ref{86,,json} 模組的參考資料包含對此的說明。


@subsubheading 也參考


@ref{ab,,pickle} - pickle 模組

與 @ref{1f32,,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 錯誤和例外,Class（類別）,輸入和輸出,Python 教學
@anchor{tutorial/errors doc}@anchor{1f36}@anchor{tutorial/errors errors-and-exceptions}@anchor{1f37}@anchor{tutorial/errors translation-repo}@anchor{1f38}@anchor{tutorial/errors tut-errors}@anchor{1f39}
@section 錯誤和例外


到目前為止還沒有提到錯誤訊息，但如果你嘗試運行範例，你可能會發現一些錯誤訊息。常見的（至少）兩種不同的錯誤類別為：`語法錯誤 (syntax error)' 和`例外 (exception)'。

@menu
* 語法錯誤 (Syntax Error): 語法錯誤 Syntax Error. 
* 例外 (Exception): 例外 Exception. 
* 處理例外:: 
* 引發例外:: 
* 例外鏈接 (Exception Chaining): 例外鏈接 Exception Chaining. 
* 使用者自定的例外:: 
* 定義清理動作:: 
* 預定義的清理動作:: 
* 引發及處理多個無關的例外:: 
* 用註解使例外更詳細:: 

@end menu

@node 語法錯誤 Syntax Error,例外 Exception,,錯誤和例外
@anchor{tutorial/errors syntax-errors}@anchor{1f3a}@anchor{tutorial/errors tut-syntaxerrors}@anchor{1f3b}
@subsection 語法錯誤 (Syntax Error)


語法錯誤又稱剖析錯誤 (parsing error)，它或許是學習 Python 的過程最常聽見的抱怨：

@example
>>> while True print('Hello world')
  File "<stdin>", line 1
    while True print('Hello world')
               ^^^^^
SyntaxError: invalid syntax
@end example

剖析器 (parser) 會重複犯錯的那一行，並用一個小箭頭指向該行檢測到錯誤的地方，但請注意這並非都會是應該去修改的地方。此例中，錯誤是在 @ref{1170,,print()} 函式中被檢測到，因為在它前面少了一個冒號 (@code{':'})。

檔案名稱（此例中為 @code{<stdin>}）和列號會被印出來，所以如果訊息是來自一個檔案時，就可以知道去哪裡找問題。

@node 例外 Exception,處理例外,語法錯誤 Syntax Error,錯誤和例外
@anchor{tutorial/errors exceptions}@anchor{1f3c}@anchor{tutorial/errors tut-exceptions}@anchor{1f3d}
@subsection 例外 (Exception)


即使一段陳述式或運算式使用了正確的語法，嘗試執行時仍可能導致錯誤。執行時檢測到的錯誤稱為`例外'，例外不一定都很嚴重：你很快就能學會在 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{b36,,ZeroDivisionError}、@ref{450,,NameError} 和 @ref{198,,TypeError}。作為例外類型被印出的字串，就是發生的內建例外 (built-in exception) 的名稱。所有的內建例外都是如此運作，但對於使用者自定的例外則不一定需要遵守（雖然這是一個有用的慣例）。標準例外名稱是內建的識別字 (identifier)，不是保留關鍵字 (reserved keyword)。

此行其餘部分，根據例外的類型及導致例外的原因，說明例外的細節。

錯誤訊息的開頭，用堆疊回溯 (stack traceback) 的形式顯示發生例外的語境。一般來說，它含有一個列出源程式碼行 (source line) 的堆疊回溯；但它不會顯示從標準輸入中讀取的程式碼。

@ref{1b3a,,內建的例外}章節列出內建的例外及它們的意義。

@node 處理例外,引發例外,例外 Exception,錯誤和例外
@anchor{tutorial/errors handling-exceptions}@anchor{1f3e}@anchor{tutorial/errors tut-handling}@anchor{1ec2}
@subsection 處理例外


編寫程式處理選定的例外是可行的。以下範例會要求使用者輸入內容，直到有效的整數被輸入為止，但它允許使用者中斷程式（使用 @code{Control}-@code{C} 或作業系統支援的指令）；請注意，由使用者產生的程式中斷會引發 @ref{bbc,,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{8f0,,try} 陳述式運作方式如下。


@itemize *

@item 
首先，執行 `try 子句'（@ref{8f0,,try} 和 @ref{1ab,,except} 關鍵字之間的陳述式）。

@item 
如果沒有發生例外，則 `except 子句'會被跳過，@ref{8f0,,try} 陳述式執行完畢。

@item 
如果執行 @ref{8f0,,try} 子句時發生了例外，則該子句中剩下的部分會被跳過。如果例外的類型與 @ref{1ab,,except} 關鍵字後面的例外名稱相符，則 `except 子句'被執行，然後，繼續執行 try/except 區塊之後的程式碼。

@item 
如果發生的例外未符合 `except 子句' 中的例外名稱，則將其傳遞到外層的 @ref{8f0,,try} 陳述式；如果仍無法找到處理者，則它是一個`未處理例外 (unhandled exception)'，執行將停止，並顯示錯誤訊息。
@end itemize

@ref{8f0,,try} 陳述式可以有不只一個 `except 子句'，為不同的例外指定處理者，而最多只有一個處理者會被執行。處理者只處理對應的 try 子句中發生的例外，而不會處理同一 @code{try} 陳述式裡其他處理者內的例外。一個 `except 子句'可以用一組括號內的 tuple 列舉多個例外，例如：

@example
... except (RuntimeError, TypeError, NameError):
...     pass
@end example

@ref{1ab,,except} 子句中的一個類別符合該類別本身或它的衍生類別的例外（但不是反過來 -- 列出一個衍生類別的 `except 子句'不會符合它的基底類別的例外）。例如，以下程式碼會按照 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 子句'的順序被反轉（把 @code{except B} 放到第一個），則會印出 B、B、B ­­——第一個符合的 `except 子句'會被觸發。

當例外發生時，它可能有相關聯的值，也就是例外的`引數'。引數的存在與否及它的類型，是取決於例外的類型。

`except 子句'可以在例外名稱後面指定一個變數。這個變數被綁定到一個例外實例 (instance)，其引數通常儲存在 @code{args} 屬性中。為了方便，內建例外型別定義了 @ref{829,,__str__()} 以印出所有引數而不需顯式地取用 @code{.args}：

@example
>>> try:
...     raise Exception('spam', 'eggs')
... except Exception as inst:
...     print(type(inst))    # 例外的型別
...     print(inst.args)     # 儲存在 .args 中的引數
...     print(inst)          # __str__ 使得引數可以直接被印出，
...                          # 但可能在例外的子類別中被覆蓋
...     x, y = inst.args     # 解包引數
...     print('x =', x)
...     print('y =', y)
...
<class 'Exception'>
('spam', 'eggs')
('spam', 'eggs')
x = spam
y = eggs
@end example

例外的 @ref{829,,__str__()} 輸出會被印在未處理例外訊息的最後一部分（「細節」）。

@ref{7d0,,BaseException} 是由全部的例外所共用的 base class。它的 subclass（子類別）之一，@ref{bc4,,Exception}，則是所有非嚴重例外 (non-fatal exception) 的 base class。有些例外不是 @ref{bc4,,Exception} 的 subclass，而它們通常不會被處理，因為它們是用來指示程式應該終止。這些例外包括了由 @ref{277,,sys.exit()} 所引發的 @ref{f37,,SystemExit}，以及當使用者想要中斷程式時所引發的 @ref{bbc,,KeyboardInterrupt}。

@ref{bc4,,Exception} 可以用作通配符 (wildcard) 來捕獲（幾乎）所有的例外。然而，比較好的做法是盡可能具體地說明我們打算處理的例外類型，並容許任何非預期例外的傳遞 (propagate)。

處理 @ref{bc4,,Exception} 的最常見模式，是先將該例外印出或記錄，然後再重新引發它（也允許一個呼叫函式 (caller) 來處理該例外）：

@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{8f0,,try} ... @ref{1ab,,except} 陳述式有一個選擇性的 `else 子句'，使用時，該子句必須放在所有 `except 子句'之後。如果一段程式碼必須被執行，但 `try 子句'又沒有引發例外時，這個子句很有用。例如：

@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{8f0,,try} 子句添加額外的程式碼要好，因為這可以避免意外地捕獲不是由 @code{try} ... @code{except} 陳述式保護的程式碼所引發的例外。

例外的處理者不僅處理 `try 子句'內立即發生的例外，還處理 `try 子句'內（即使是間接地）呼叫的函式內部發生的例外。例如：

@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 引發例外,例外鏈接 Exception Chaining,處理例外,錯誤和例外
@anchor{tutorial/errors raising-exceptions}@anchor{1f3f}@anchor{tutorial/errors tut-raising}@anchor{1f40}
@subsection 引發例外


@ref{7fc,,raise} 陳述式可讓程式設計師強制引發指定的例外。例如：

@example
>>> raise NameError('HiThere')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
    raise NameError('HiThere')
NameError: HiThere
@end example

@ref{7fc,,raise} 唯一的引數就是要引發的例外。該引數必須是一個例外實例或例外 class（衍生自 @ref{7d0,,BaseException} 的 class，例如 @ref{bc4,,Exception} 與它的 subclass）。如果一個例外 class 被傳遞，它會不含引數地呼叫它的建構函式 (constructor) ，使它被自動建立實例 (implicitly instantiated)：

@example
raise ValueError  # 'raise ValueError()' 的簡寫
@end example

如果你只想判斷是否引發了例外，但並不打算處理它，則可以使用簡單的 @ref{7fc,,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 例外鏈接 Exception Chaining,使用者自定的例外,引發例外,錯誤和例外
@anchor{tutorial/errors exception-chaining}@anchor{1f41}@anchor{tutorial/errors tut-exception-chaining}@anchor{1f42}
@subsection 例外鏈接 (Exception Chaining)


如果在 @ref{1ab,,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{7fc,,raise} 陳述式容許一個選擇性的 @ref{7fc,,from} 子句：

@example
# exc 必須是例外實例或 None。
raise RuntimeError from 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} 來停用自動例外鏈接：

@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{1b3a,,內建的例外}。

@node 使用者自定的例外,定義清理動作,例外鏈接 Exception Chaining,錯誤和例外
@anchor{tutorial/errors tut-userexceptions}@anchor{1f43}@anchor{tutorial/errors user-defined-exceptions}@anchor{1f44}
@subsection 使用者自定的例外


程式可以透過建立新的例外 class 來命名自己的例外（深入了解 Python class，詳見@ref{1eca,,Class（類別）}）。不論是直接還是間接地，例外通常應該從 @ref{bc4,,Exception} class 衍生出來。

例外 class 可被定義來做任何其他 class 能夠做的事，但通常會讓它維持簡單，只提供一些屬性，讓關於錯誤的資訊可被例外的處理者抽取出來。

大多數的例外定義，都會以「Error」作為名稱結尾，類似於標準例外的命名。

許多標準模組會定義它們自己的例外，以報告在其定義的函式中發生的錯誤。

@node 定義清理動作,預定義的清理動作,使用者自定的例外,錯誤和例外
@anchor{tutorial/errors defining-clean-up-actions}@anchor{1f45}@anchor{tutorial/errors tut-cleanup}@anchor{1f46}
@subsection 定義清理動作


@ref{8f0,,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{1b0,,finally} 子句存在，則 @code{finally} 子句會是 @ref{8f0,,try} 陳述式結束前執行的最後一項任務。不論 @code{try} 陳述式是否產生例外，都會執行 @code{finally} 子句。以下幾點將探討例外發生時，比較複雜的情況：


@itemize *

@item 
若一個例外發生於 @code{try} 子句的執行過程，則該例外會被某個 @ref{1ab,,except} 子句處理。如果該例外沒有被 @code{except} 子句處理，它會在 @code{finally} 子句執行後被重新引發。

@item 
一個例外可能發生於 @code{except} 或 @code{else} 子句的執行過程。同樣地，該例外會在 @code{finally} 子句執行後被重新引發。

@item 
如果 @code{finally} 子句執行 @ref{17f,,break}、@ref{180,,continue} 或 @ref{1af,,return} 陳述式，則例外不會被重新引發。這可能會令人困惑，因此不建議這麼做。從 3.14 版本開始，編譯器會為此發出 @ref{1ae,,SyntaxWarning}（詳見 
@geindex Python Enhancement Proposals; PEP 765
PEP 765@footnote{https://peps.python.org/pep-0765/}）。

@item 
如果 @code{try} 陳述式遇到 @ref{17f,,break}、@ref{180,,continue} 或 @ref{1af,,return} 陳述式，則 @code{finally} 子句會在執行 @code{break}、@code{continue} 或 @code{return} 陳述式之前先執行。

@item 
如果 @code{finally} 子句中包含 @code{return} 陳述式，則回傳值會是來自 @code{finally} 子句的 @code{return} 陳述式的回傳值，而不是來自 @code{try} 子句的 @code{return} 陳述式的回傳值。這可能會令人困惑，因此不建議這麼做。從 3.14 版本開始，編譯器會為此發出 @ref{1ae,,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{1b0,,finally} 子句在任何情況下都會被執行。兩個字串相除所引發的 @ref{198,,TypeError} 沒有被 @ref{1ab,,except} 子句處理，因此會在 @code{finally} 子句執行後被重新引發。

在真實應用程式中，@ref{1b0,,finally} 子句對於釋放外部資源（例如檔案或網路連線）很有用，無論該資源的使用是否成功。

@node 預定義的清理動作,引發及處理多個無關的例外,定義清理動作,錯誤和例外
@anchor{tutorial/errors predefined-clean-up-actions}@anchor{1f47}@anchor{tutorial/errors tut-cleanup-with}@anchor{1f48}
@subsection 預定義的清理動作


某些物件定義了在物件不再被需要時的標準清理動作，無論使用該物件的作業是成功或失敗。請看以下範例，它嘗試開啟一個檔案，並印出檔案內容至螢幕。

@example
for line in open("myfile.txt"):
    print(line, end="")
@end example

這段程式碼的問題在於，執行完該程式碼後，它讓檔案在一段不確定的時間內處於開啟狀態。在簡單腳本中這不是問題，但對於較大的應用程式來說可能會是個問題。@ref{186,,with} 陳述式讓物件（例如檔案）在被使用時，能保證它們總是及時、正確地被清理。

@example
with open("myfile.txt") as f:
    for line in f:
        print(line, end="")
@end example

陳述式執行完畢後，就算是在處理內容時遇到問題，檔案 `f' 總是會被關閉。和檔案一樣，提供預定義清理動作的物件會在說明文件中表明這一點。

@node 引發及處理多個無關的例外,用註解使例外更詳細,預定義的清理動作,錯誤和例外
@anchor{tutorial/errors raising-and-handling-multiple-unrelated-exceptions}@anchor{1f49}@anchor{tutorial/errors tut-exception-groups}@anchor{1f4a}
@subsection 引發及處理多個無關的例外


在某些情況下，必須回報已經發生的多個例外。在並行框架 (concurrency framework) 中經常會出現這種情況，當平行的 (parallel) 某些任務可能已經失效，但還有其他用例 (use case) 希望能繼續執行並收集多個例外，而不是只有引發第一個例外時。

內建的 @ref{4cd,,ExceptionGroup} 會包裝一個例外實例 (exception instance) 的 list（串列），使得它們可以一起被引發。由於它本身就是一個例外，因此它也可以像任何其他例外一樣被捕獲。

@example
>>> def f():
...     excs = [OSError('error 1'), SystemError('error 2')]
...     raise ExceptionGroup('there were problems', excs)
...
>>> f()
  + Exception Group Traceback (most recent call last):
  |   File "<stdin>", line 1, in <module>
  |     f()
  |     ~^^
  |   File "<stdin>", line 3, in f
  |     raise ExceptionGroup('there were problems', excs)
  | ExceptionGroup: there were problems (2 sub-exceptions)
  +-+---------------- 1 ----------------
    | OSError: error 1
    +---------------- 2 ----------------
    | SystemError: error 2
    +------------------------------------
>>> try:
...     f()
... except Exception as e:
...     print(f'caught @{type(e)@}: e')
...
caught <class 'ExceptionGroup'>: e
>>>
@end example

若使用 @code{except*} 代替 @code{except}，我們可以選擇性地只處理該群組中與特定類型匹配的例外。在以下範例中，展示了一個巢狀的例外群組 (exception group)，每個 @code{except*} 子句分別從該群組中提取一個特定類型的例外，同時讓所有其他的例外都傳遞到其他子句，最後再被重新引發。

@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 用註解使例外更詳細,,引發及處理多個無關的例外,錯誤和例外
@anchor{tutorial/errors enriching-exceptions-with-notes}@anchor{1f4b}@anchor{tutorial/errors tut-exception-notes}@anchor{1f4c}
@subsection 用註解使例外更詳細


當一個例外是為了被引發而建立時，它通常會伴隨著一些資訊被初始化，這些資訊描述了當下發生的錯誤。在某些情況，在例外被捕獲之後添加資訊會很有用。為此，例外具有一個 @code{add_note(note)} method（方法），它可以接受一個字串並將其添加到例外的註解清單中。標準的回溯呈現會在例外之後列出所有的註解，並按照其被添加的順序來排列。

@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 Class（類別）,Python 標準函式庫概覽,錯誤和例外,Python 教學
@anchor{tutorial/classes doc}@anchor{1f4d}@anchor{tutorial/classes classes}@anchor{1f4e}@anchor{tutorial/classes translation-repo}@anchor{1f4f}@anchor{tutorial/classes tut-classes}@anchor{1eca}
@section Class（類別）


Class 提供了一種結合資料與功能的手段。建立一個 class 將會新增一個物件的`型別 (type)'，並且允許建立該型別的新`實例 (instance)'。每一個 class 實例可以擁有一些維持該實例狀態的屬性 (attribute)。Class 實例也可以有一些（由其 class 所定義的）method（方法），用於修改該實例的狀態。

與其他程式語言相比，Python 的 class 機制為 class 增加了最少的新語法跟語意。他混合了 C++ 和 Modula-3 的 class 機制。Python 的 class 提供了所有物件導向程式設計 (Object Oriented Programming) 的標準特色：class 繼承機制允許多個 base class（基底類別），一個 derived class（衍生類別）可以覆寫 (override) 其 base class 的任何 method，且一個 method 可以用相同的名稱呼叫其 base class 的 method。物件可以包含任意數量及任意種類的資料。如同模組一樣，class 也具有 Python 的動態特性：他們在執行期 (runtime) 被建立，且可以在建立之後被修改。

在 C++ 的術語中，class 成員（包含資料成員）通常都是`公開'的（除了以下內容：@ref{1f50,,私有變數}），而所有的成員函式都是`虛擬'的。如同在 Modula-3 中一樣，Python 並沒有提供簡寫可以從物件的 method 裡參照其成員：method 函式與一個外顯的 (explicit)、第一個代表物件的引數被宣告，而此引數是在呼叫時隱性地 (implicitly) 被提供。如同在 Smalltak 中，class 都是物件，這為 import 及重新命名提供了語意。不像 C++ 和 Modula-3，Pyhon 內建的型別可以被使用者以 base class 用於其他擴充 (extension)。另外，如同在 C++ 中，大多數有著特別語法的內建運算子（算術運算子、下標等）都可以為了 class 實例而被重新定義。

（由於缺乏普遍能接受的術語來討論 class，我偶爾會使用 Smalltalk 和 C++ 的術語。我會使用 Modula-3 的術語，因為它比 C++ 更接近 Python 的物件導向語意，但我預期比較少的讀者會聽過它。）

@menu
* 關於名稱與物件的一段話:: 
* Python 作用域 (Scope) 及命名空間 (Namespace): Python 作用域 Scope 及命名空間 Namespace. 
* 初見 class:: 
* 隨意的備註:: 
* 繼承 (Inheritance): 繼承 Inheritance. 
* 私有變數:: 
* 補充說明:: 
* 疊代器 (Iterator): 疊代器 Iterator. 
* 產生器 (Generator): 產生器 Generator. 
* 產生器運算式:: 

@end menu

@node 關於名稱與物件的一段話,Python 作用域 Scope 及命名空間 Namespace,,Class（類別）
@anchor{tutorial/classes a-word-about-names-and-objects}@anchor{1f51}@anchor{tutorial/classes tut-object}@anchor{1f52}
@subsection 關於名稱與物件的一段話


物件有個體性 (individuality)，且多個名稱（在多個作用域 (scope) ）可以被連結到相同的物件。這在其他語言中被稱為別名 (aliasing)。初次接觸 Python 時通常不會注意這件事，而在處理不可變的基本型別（數值、字串、tuple）時，它也可以安全地被忽略。然而，別名在含有可變物件（如 list（串列）、dictionary（字典）、和大多數其他的型別）的 Python 程式碼語意中，可能會有意外的效果。這通常有利於程式，因為別名在某些方面表現得像指標 (pointer)。舉例來說，在實作時傳遞一個物件是便宜的，因為只有指標被傳遞；假如函式修改了一個作為引數傳遞的物件，呼叫函式者 (caller) 能夠見到這些改變——這消除了在 Pascal 中兩個相異引數傳遞機制的需求。

@node Python 作用域 Scope 及命名空間 Namespace,初見 class,關於名稱與物件的一段話,Class（類別）
@anchor{tutorial/classes python-scopes-and-namespaces}@anchor{1f53}@anchor{tutorial/classes tut-scopes}@anchor{1f07}
@subsection Python 作用域 (Scope) 及命名空間 (Namespace)


在介紹 class 之前，我必須先告訴你一些關於 Python 作用域的規則。Class definition（類別定義）以命名空間展現了一些俐落的技巧，而你需要了解作用域和命名空間的運作才能完整理解正在發生的事情。順帶一提，關於這個主題的知識對任何進階的 Python 程式設計師都是很有用的。

讓我們從一些定義開始。

`命名空間'是從名稱到物件的對映。大部分的命名空間現在都是以 Python 的 dictionary 被實作，但通常不會以任何方式被察覺（除了性能），且它可能會在未來改變。命名空間的例子有：內建名稱的集合（包含如 @ref{1f54,,abs()} 的函式，和內建的例外名稱）；模組中的全域 (global) 名稱；和在函式呼叫中的區域 (local) 名稱。某種意義上，物件中的屬性集合也會形成一個命名空間。關於命名空間的重要一點是，不同命名空間中的名稱之間絕對沒有關係；舉例來說，兩個不一樣的模組都可以定義一個 @code{maximize} 函式而不會混淆——模組的使用者必須為它加上前綴 (prefix) 模組名稱。

順帶一提，我使用`屬性 (attribute)' 這個字，統稱句號 (dot) 後面的任何名稱——例如，運算式中的 @code{z.real}，@code{real} 是物件 @code{z} 的一個屬性。嚴格來說，模組中名稱的參照都是屬性參照：在運算式 @code{modname.funcname} 中，@code{modname} 是模組物件而 @code{funcname} 是它的屬性。在這種情況下，模組的屬性和模組中定義的全域名稱碰巧有一個直接的對映：他們共享了相同的命名空間！@footnote{
有一個例外。模組物件有一個秘密的唯讀屬性，稱為 @ref{776,,__dict__}，它回傳用於實作模組命名空間的 dictionary；@code{__dict__} 這個名稱是一個屬性但不是全域名稱。顯然，使用此屬性將違反命名空間實作的抽象化，而應該僅限用於事後除錯器 (post-mortem debugger) 之類的東西。
}

屬性可以是唯讀的或可寫的。在後者的情況下，對屬性的賦值是可能的。模組屬性是可寫的：你可以寫 @code{modname.the_answer = 42}。可寫屬性也可以用 @ref{1a62,,del} 陳述式刪除。例如，@code{del modname.the_answer} 將從名為 @code{modname} 的物件中刪除屬性 @code{the_answer}。

命名空間在不同的時刻被建立，並且有不同的壽命。當 Python 直譯器啟動時，含有內建名稱的命名空間會被建立，並且永遠不會被刪除。當模組定義被讀入時，模組的全域命名空間會被建立；一般情況下，模組的命名空間也會持續到直譯器結束。被直譯器的頂層呼叫 (top-level invocation) 執行的陳述式，不論是從腳本檔案讀取的或是互動模式中的，會被視為一個稱為 @ref{1,,__main__} 的模組的一部分，因此它們具有自己的全域命名空間。（內建名稱實際上也存在一個模組中，它被稱為 @ref{13,,builtins}。）

函式的區域命名空間是在呼叫函式時建立的，而當函式返回，或引發了未在函式中處理的例外時，此命名空間將會被刪除。（實際上，忘記是描述實際發生的事情的更好方法。） 當然，每個遞迴呼叫 (recursive invocation) 都有自己的區域命名空間。

`作用域'是 Python 程式中的一個文本區域 (textual region)，在此區域，命名空間是可直接存取的。這裡的「可直接存取的」意思是，對一個名稱的非限定參照 (unqualified reference) 可以在命名空間內嘗試尋找該名稱。

儘管作用域是靜態地被決定，但它們是動態地被使用的。在執行期間內的任何時間點，都會有 3 或 4 個巢狀的作用域，其命名空間是可以被直接存取的：


@itemize *

@item 
最內層作用域，會最先被搜尋，而它包含了區域名稱

@item 
任何外圍函式 (enclosing function) 的作用域，會從最近的外圍作用域開始搜尋，它包含了非區域 (non-local) 和非全域 (non-global) 的名稱

@item 
倒數第二個作用域，包含目前模組的全域名稱

@item 
最外面的作用域（最後搜尋），是包含內建名稱的命名空間
@end itemize

如果一個名稱被宣告為全域，則所有的參照和賦值將直接轉到包含模組全域名稱的倒數第二個作用域。要重新連結最內層作用域以外找到的變數，可以使用 @ref{14a8,,nonlocal} 陳述式；如果那些變數沒有被宣告為 nonlocal，則它們會是唯讀的（嘗試寫入這樣的變數只會在最內層的作用域內建立一個`新的'區域變數，同名的外部變數則維持不變）。

通常，區域作用域會參照（文本的）目前函式的區域名稱。在函式外部，區域作用域與全域作用域參照相同的命名空間：模組的命名空間。然而，Class definition 會在區域作用域中放置另一個命名空間。

務必要了解，作用域是按文本被決定的：在模組中定義的函式，其全域作用域便是該模組的命名空間，無論函式是從何處或以什麼別名被呼叫。另一方面，對名稱的實際搜尋是在執行時期 (run time) 動態完成的——但是，語言定義的發展，正朝向在「編譯」時期 (compile time) 的靜態名稱解析 (static name resolution)，所以不要太依賴動態名稱解析 (dynamic name resolution)！ （事實上，局部變數已經是靜態地被決定。）

一個 Python 的特殊癖好是——假如沒有 @ref{4a7,,global} 或 @ref{14a8,,nonlocal} 陳述式的效果——名稱的賦值 (assignment) 都會指向最內層作用域。賦值不會複製資料——它們只會把名稱連結至物件。刪除也是一樣：陳述式 @code{del x} 會從區域作用域參照的命名空間移除 @code{x} 的連結。事實上，引入新名稱的所有運算都使用區域作用域：特別是 @ref{7f1,,import} 陳述式和函式定義，會連結區域作用域內的模組或函式名稱。

@ref{4a7,,global} 陳述式可以用來表示特定變數存活在全域作用域，應該被重新綁定到那裡；@ref{14a8,,nonlocal} 陳述式表示特定變數存活在外圍作用域內，應該被重新綁定到那裡。

@menu
* 作用域和命名空間的範例:: 

@end menu

@node 作用域和命名空間的範例,,,Python 作用域 Scope 及命名空間 Namespace
@anchor{tutorial/classes scopes-and-namespaces-example}@anchor{1f55}@anchor{tutorial/classes tut-scopeexample}@anchor{1f56}
@subsubsection 作用域和命名空間的範例


這是一個範例，演示如何參照不同的作用域和命名空間，以及 @ref{4a7,,global} 和 @ref{14a8,,nonlocal} 如何影響變數的綁定：

@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' 對 `spam' 的連結。@ref{14a8,,nonlocal} 賦值改變了 `scope_test' 對 `spam' 的連結，而 @ref{4a7,,global} 賦值改變了模組層次的連結。

你還可以發現，在 @ref{4a7,,global} 賦值之前，沒有對 `spam' 的連結。

@node 初見 class,隨意的備註,Python 作用域 Scope 及命名空間 Namespace,Class（類別）
@anchor{tutorial/classes a-first-look-at-classes}@anchor{1f57}@anchor{tutorial/classes tut-firstclasses}@anchor{1ee5}
@subsection 初見 class


Class 採用一些新的語法，三個新的物件型別，以及一些新的語意。

@menu
* Class definition（類別定義）語法:: 
* Class 物件:: 
* 實例物件:: 
* Method 物件:: 
* Class 及實例變數:: 

@end menu

@node Class definition（類別定義）語法,Class 物件,,初見 class
@anchor{tutorial/classes class-definition-syntax}@anchor{1f58}@anchor{tutorial/classes tut-classdefinition}@anchor{1f59}
@subsubsection Class definition（類別定義）語法


Class definition 最簡單的形式如下：

@example
class ClassName:
    <statement-1>
    .
    .
    .
    <statement-N>
@end example

Class definition，如同函式定義（@ref{164f,,def} 陳述式），必須在它們有任何效果前先執行。（你可以想像把 class definition 放在一個 @ref{181,,if} 陳述式的分支，或在函式裡。）

在實作時，class definition 內的陳述式通常會是函式定義，但其他陳述式也是允許的，有時很有用——我們稍後會回到這裡。Class 中的函式定義通常會有一個獨特的引數列表形式，取決於 method 的呼叫慣例——再一次地，這將會在稍後解釋。

當進入 class definition，一個新的命名空間將會被建立，並且作為區域作用域——因此，所有區域變數的賦值將進入這個新的命名空間。特別是，函式定義會在這裡連結新函式的名稱。

正常地（從結尾處）離開 class definition 時，一個 `class 物件'會被建立。基本上這是一個包裝器 (wrapper)，裝著 class definition 建立的命名空間內容；我們將在下一節中更加了解 class 物件。原始的區域作用域（在進入 class definition 之前已生效的作用域）會恢復，在此 class 物件會被連結到 class definition 標頭中給出的 class 名稱（在範例中為 @code{ClassName}）。

@node Class 物件,實例物件,Class definition（類別定義）語法,初見 class
@anchor{tutorial/classes class-objects}@anchor{1f5a}@anchor{tutorial/classes tut-classobjects}@anchor{1f5b}
@subsubsection Class 物件


Class 物件支援兩種運算：屬性參照 (attribute reference) 和實例化 (instantiation)。

`屬性參照'使用 Python 中所有屬性參照的標準語法：@code{obj.name}。有效的屬性名稱是 class 物件被建立時，class 的命名空間中所有的名稱。所以，如果 class definition 看起來像這樣：

@example
class MyClass:
    """一個簡單的類別範例"""
    i = 12345

    def f(self):
        return 'hello world'
@end example

那麼 @code{MyClass.i} 和 @code{MyClass.f} 都是有效的屬性參照，會分別回傳一個整數和一個函式物件。Class 屬性也可以被指派 (assign)，所以你可以透過賦值改變 @code{MyClass.i} 的值。@ref{1f5c,,__doc__} 也是一個有效的屬性，會回傳屬於該 class 的說明字串 (docstring)：@code{"A simple example class"}。

Class `實例化'使用了函式記法 (function notation)。就好像 class 物件是一個沒有參數的函式，它回傳一個新的 class 實例。例如（假設是上述的 class）：

@example
x = MyClass()
@end example

建立 class 的一個新`實例'，並將此物件指派給區域變數 @code{x}。

實例化運算（「呼叫」一個 class 物件）會建立一個空的物件。許多 class 喜歡在建立物件時有著自訂的特定實例初始狀態。因此，class 可以定義一個名為 @ref{8b7,,__init__()} 的特別 method，像這樣：

@example
def __init__(self):
    self.data = []
@end example

當 class 定義了 @ref{8b7,,__init__()} method，class 實例化會為新建的 class 實例自動叫用 @code{__init__()}。所以在這個範例中，一個新的、初始化的實例可以如此獲得：

@example
x = MyClass()
@end example

當然，@ref{8b7,,__init__()} method 可能為了更多的彈性而有引數。在這種情況下，要給 class 實例化運算子的引數會被傳遞給 @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 實例物件,Method 物件,Class 物件,初見 class
@anchor{tutorial/classes instance-objects}@anchor{1f5d}@anchor{tutorial/classes tut-instanceobjects}@anchor{1f5e}
@subsubsection 實例物件


現在，我們可以如何處理實例物件？實例物件能理解的唯一運算就是屬性參照。有兩種有效的屬性名稱：資料屬性 (data attribute) 和 method。

`資料屬性'對應 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

另一種執行個體屬性參考是 `方法' (method)。方法是"屬於"一個物件的函式。

@geindex object（物件）;method（方法）

實例物件的有效 method 名稱取決於其 class。根據定義，一個 class 中所有的函式物件屬性，就定義了實例的對應 method。所以在我們的例子中，@code{x.f} 是一個有效的 method 參照，因為 @code{MyClass.f} 是一個函式，但 @code{x.i} 不是，因為 @code{MyClass.i} 不是。但 @code{x.f} 與 @code{MyClass.f} 是不一樣的——它是一個 `method 物件'，而不是函式物件。

@node Method 物件,Class 及實例變數,實例物件,初見 class
@anchor{tutorial/classes method-objects}@anchor{1f5f}@anchor{tutorial/classes tut-methodobjects}@anchor{1f60}
@subsubsection Method 物件


通常，一個 method 在它被連結後隨即被呼叫：

@example
x.f()
@end example

如果像上面一樣 @code{x = MyClass()}，這將回傳字串 @code{'hello world'}。然而，並沒有必要立即呼叫一個 method：@code{x.f} 是一個 method 物件，並且可以被儲藏起來，之後再被呼叫。舉例來說：

@example
xf = x.f
while True:
    print(xf())
@end example

將會持續印出 @code{hello world} 直到天荒地老。

當一個 method 被呼叫時究竟會發生什麼事？你可能已經注意到 @code{x.f()} 被呼叫時沒有任何的引數，儘管 @code{f()} 的函式定義有指定一個引數。這個引數發生了什麼事？當一個需要引數的函式被呼叫而沒有給任何引數時，Python 肯定會引發例外——即使該引數實際上沒有被使用...

事實上，你可能已經猜到了答案：method 的特殊之處在於，實例物件會作為函式中的第一個引數被傳遞。在我們的例子中，@code{x.f()} 這個呼叫等同於 @code{MyClass.f(x)}。一般來說，呼叫一個有 `n' 個引數的 method，等同於呼叫一個對應函式，其引數列表 (argument list) 被建立時，會在第一個引數前插入該 method 的實例物件。

一般來說，方法的工作原理如下。當一個實例的非資料屬性被參照時，將會搜尋該實例的 class。如果該名稱是一個有效的 class 屬性，而且是一個函式物件，則對實例物件和函式物件的參照都會被打包到方法物件中。當使用引數串列呼叫方法物件時，會根據實例物件和引數串列來建構一個新的引數串列，並使用該新引數串列來呼叫函式物件。

@node Class 及實例變數,,Method 物件,初見 class
@anchor{tutorial/classes class-and-instance-variables}@anchor{1f61}@anchor{tutorial/classes tut-class-and-instance-variables}@anchor{1f62}
@subsubsection Class 及實例變數


一般來說，實例變數用於每一個實例的獨特資料，而 class 變數用於該 class 的所有實例共享的屬性和 method：

@example
class Dog:

    kind = 'canine'         # 所有實例共享的類別變數

    def __init__(self, name):
        self.name = name    # 每個實例獨有的實例變數

>>> d = Dog('Fido')
>>> e = Dog('Buddy')
>>> d.kind                  # 為所有 Dog 實例所共享
'canine'
>>> e.kind                  # 為所有 Dog 實例所共享
'canine'
>>> d.name                  # d 獨有
'Fido'
>>> e.name                  # e 獨有
'Buddy'
@end example

如同在@ref{1f52,,關於名稱與物件的一段話}的討論，共享的資料若涉及 @ref{1eac,,mutable} 物件，如 list 和 dictionary，可能會產生意外的影響。舉例來說，下列程式碼的 `tricks' list 不應該作為一個 class 變數使用，因為這個 list 將會被所有的 `Dog' 實例所共享：

@example
class Dog:

    tricks = []             # 誤用類別變數

    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                # 出乎意料地被所有 dog 共享
['roll over', 'play dead']
@end example

正確的 class 設計應該使用實例變數：

@example
class Dog:

    def __init__(self, name):
        self.name = name
        self.tricks = []    # 為每一個 dog 建立空 list

    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 隨意的備註,繼承 Inheritance,初見 class,Class（類別）
@anchor{tutorial/classes random-remarks}@anchor{1f63}@anchor{tutorial/classes tut-remarks}@anchor{1f64}
@subsection 隨意的備註


@c These should perhaps be placed more carefully...

如果屬性名稱同時出現在一個實例和一個 class 中，則屬性的尋找會以實例為優先：

@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

資料屬性可能被 method 或是被物件的一般使用者（「用戶端」）所參照。也就是說，class 不可用於實作純粹抽象的資料型別。事實上，在 Python 中沒有任何可能的方法，可強制隱藏資料——這都是基於慣例。（另一方面，以 C 編寫的 Python 實作可以完全隱藏實作細節並且在必要時控制物件的存取；這可以被以 C 編寫的 Python 擴充所使用。）

用戶端應該小心使用資料屬性——用戶端可能會因為覆寫他們的資料屬性，而破壞了被 method 維護的不變性。注意，用戶端可以增加他們自己的資料屬性到實例物件，但不影響 method 的有效性，只要避免名稱衝突即可——再一次提醒，命名慣例可以在這裡節省很多麻煩。

在 method 中參照資料屬性（或其他 method！）是沒有簡寫的。我發現這實際上增加了 method 的可閱讀性：在瀏覽 method 時，絕不會混淆區域變數和實例變數。

通常，方法的第一個引數稱為 @code{self}。這僅僅只是一個慣例：@code{self} 這個名字對 Python 來說完全沒有特別的意義。但請注意，如果不遵循慣例，你的程式碼可能對其他 Python 程式設計師來說可讀性較低，此外，也可以想像一個可能因信任此慣例而編寫的 `class 瀏覽器 (browser)' 程式。

任何一個作為 class 屬性的函式物件都為該 class 的實例定義了一個相應的 method。函式定義不一定要包含在 class definition 的文本中：將函式物件指定給 class 中的區域變數也是可以的。例如：

@example
# 在類別以外定義的函式
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} 都是 class @code{C} 的屬性，並指向函式物件，所以他們都是class @code{C} 實例的 method —— @code{h} 與 @code{g} 是完全一樣的。請注意，這種做法通常只會使該程式的讀者感到困惑。

Method 可以藉由使用 @code{self} 引數的 method 屬性，呼叫其他 method：

@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

Method 可以用與一般函式相同的方式參照全域名稱。與 method 相關的全域作用域，就是包含其定義的模組。（class 永遠不會被用作全域作用域。）雖然人們很少有在 method 中使用全域資料的充分理由，但全域作用域仍有許多合法的使用：比方說，被 import 至全域作用域的函式和模組，可以被 method 以及在該作用域中定義的函式和 class 所使用。通常，包含 method 的 class，它本身就是被定義在這個全域作用域，在下一節，我們將看到 method 想要參照自己的 class 的一些好原因。

每個值都是一個物件，因此都具有一個 `class'，也可以稱為它的 `type（型別）'。它以 @code{object.__class__} 被儲存。

@node 繼承 Inheritance,私有變數,隨意的備註,Class（類別）
@anchor{tutorial/classes inheritance}@anchor{1f65}@anchor{tutorial/classes tut-inheritance}@anchor{1f66}
@subsection 繼承 (Inheritance)


當然，如果沒有支援繼承，「class」這個語言特色就不值得被稱為 class。一個 derived class（衍生類別）定義的語法看起來如下：

@example
class DerivedClassName(BaseClassName):
    <statement-1>
    .
    .
    .
    <statement-N>
@end example

名稱 @code{BaseClassName} 必須被定義於作用域可及的命名空間，且該作用域要包含 derived class 定義。要代替 base class（基底類別）的名稱，用其他任意的運算式也是被允許的。這會很有用，例如，當一個 base class 是在另一個模組中被定義時：

@example
class DerivedClassName(modname.BaseClassName):
@end example

執行 derived class 定義的過程，與執行 base class 相同。當 class 物件被建構時，base class 會被記住。這是用於解析屬性參照：如果一個要求的屬性無法在該 class 中找到，則會繼續在 base class 中搜尋。假如該 base class 本身也是衍生自其他 class，則這個規則會遞迴地被應用。

關於 derived class 的實例化並沒有特別之處：@code{DerivedClassName()} 會建立該 class 的一個新實例。Method 的參照被解析如下：對應的 class 屬性會被搜尋，如果需要，沿著 base class 的繼承鍊往下走，如果這產生了一個函式物件，則該 method 的參照是有效的。

Derived class 可以覆寫其 base class 的 method。因為 method 在呼叫同一個物件的其他 method 時沒有特別的特權，所以當 base class 的一個 method 在呼叫相同 base class 中定義的另一個 method 時，最終可能會呼叫到一個覆寫它的 derived class 中的 method。（給 C++ 程式設計師：Python 中所有 method 實際上都是 @code{virtual}。）

一個在 derived class 覆寫的 method 可能事實上是想要擴充而非單純取代 base class 中相同名稱的 method。要直接呼叫 base class 的 method 有一個簡單的方法：只要呼叫 @code{BaseClassName.methodname(self, arguments)}。這有時對用戶端也很有用。（請注意，只有在 base class 在全域作用域可以用 @code{BaseClassName} 被存取時，這方法才有效。）

Python 有兩個內建函式可以用於繼承：


@itemize *

@item 
使用 @ref{2ad,,isinstance()} 判斷一個實例的型別：@code{isinstance(obj, int)} 只有在 @code{obj.__class__} 是 @ref{19b,,int} 或衍伸自 @ref{19b,,int} 時，結果才會是 @code{True}。

@item 
使用 @ref{9bd,,issubclass()} 判斷 class 繼承：@code{issubclass(bool, int)} 會是 @code{True}，因為 @ref{3c1,,bool} 是 @ref{19b,,int} 的 subclass（子類別）。但是，@code{issubclass(float, int)} 是 @code{False}，因為 @ref{196,,float} 並不是 @ref{19b,,int} 的 subclass。
@end itemize

@menu
* 多重繼承:: 

@end menu

@node 多重繼承,,,繼承 Inheritance
@anchor{tutorial/classes multiple-inheritance}@anchor{1f67}@anchor{tutorial/classes tut-multiple}@anchor{1f68}
@subsubsection 多重繼承


Python 也支援多重繼承的形式。一個有多個 base class 的 class definition 看起來像這樣子：

@example
class DerivedClassName(Base1, Base2, Base3):
    <statement-1>
    .
    .
    .
    <statement-N>
@end example

在大多數情況下，最簡單的例子裡，你可以這樣思考，對於繼承自 parent class（父類別）的屬性，其搜尋規則為：深度優先、從左到右、在階層裡重疊的相同 class 中不重複搜尋。因此，假如有一個屬性在 @code{DerivedClassName} 沒有被找到，則在 @code{Base1} 搜尋它，接著（遞迴地）在 @code{Base1} 的 base class 中搜尋，假如在那裡又沒有找到的話，會在 @code{Base2} 搜尋，依此類推。

事實上，它稍微複雜一些；method 的解析順序是動態地變化，以支援對 @ref{1a6,,super()} 的合作呼叫。這個方式在其他的多重繼承語言中，稱為呼叫下一個方法 (call-next-method)，且比在單一繼承語言中的 super call（超級呼叫）來得更強大。

動態排序是必要的，因為多重繼承的所有情況都表現一或多的菱形關係（其中至少一個 parent class 可以從最底層 class 透過多個路徑存取）。例如，所有的 class 都繼承自 @ref{c75,,object}，因此任何多重繼承的情況都提供了多個到達 @ref{c75,,object} 的路徑。為了避免 base class 被多次存取，動態演算法以這些方式將搜尋順序線性化 (linearize)：保留每個 class 中規定的從左到右的順序、對每個 parent 只會呼叫一次、使用單調的 (monotonic) 方式（意思是，一個 class 可以被 subclassed（子類別化），而不會影響其 parent 的搜尋優先順序）。總之，這些特性使設計出可靠又可擴充、具有多重繼承的 class 成為可能。更多資訊，請見 @ref{169e,,The Python 2.3 Method Resolution Order}。

@node 私有變數,補充說明,繼承 Inheritance,Class（類別）
@anchor{tutorial/classes private-variables}@anchor{1f69}@anchor{tutorial/classes tut-private}@anchor{1f50}
@subsection 私有變數


「私有」(private) 實例變數，指的是不在物件內部便無法存取的變數，這在 Python 中是不存在的。但是，大多數 Python 的程式碼都遵守一個慣例：前綴為一個底線的名稱（如：@code{_spam}）應被視為 API （應用程式介面）的非公有 (non-public) 部分（無論它是函式、方法或是資料成員）。這被視為一個實作細節，如有調整，亦不另行通知。

@geindex name（名稱）;mangling（修飾）

既然 class 私有的成員已有一個有效的用例（即避免名稱與 subclass 定義的名稱衝突），這種機制也存在另一個有限的支援，稱為 `name mangling'（名稱修飾）。任何格式為 @code{__spam}（至少兩個前導下底線，最多一個尾隨下底線）的物件名稱 (identifier) 會被文本地被替換為 @code{_classname__spam}，在此 @code{classname} 就是去掉前導下底線的目前 class 名稱。只要這個修飾是在 class 的定義之中發生，它就會在不考慮該物件名稱的語法位置的情況下完成。


@subsubheading 也參考


參閱@ref{1f6a,,私有名稱修飾規格}的詳情與特殊情況。


名稱修飾對於讓 subclass 覆寫 method 而不用破壞 class 內部的 method 呼叫，是有幫助的。舉例來說：

@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   # 原始 update() 方法的私有副本

class MappingSubclass(Mapping):

    def update(self, keys, values):
        # 為 update() 提供新的函式簽名
        # 但不會破壞 __init__()
        for item in zip(keys, values):
            self.items_list.append(item)
@end example

在上例中，就算在 @code{MappingSubclass} 當中加入 @code{__update} 識別符，也能順利運作，因為在 @code{Mapping} class 中，它會被替換為 @code{_Mapping__update}，而在 @code{MappingSubclass} class 中，它會被替換為 @code{_MappingSubclass__update}。

請注意，修飾規則是被設計來避免意外；它仍可能存取或修改一個被視為私有的變數。這在特殊情況下甚至可能很有用，例如在除錯器 (debugger)。

另外也注意，傳遞給 @code{exec()} 或 @code{eval()} 的程式碼不會把叫用 class 的名稱視為目前的 class；這和 @code{global} 陳述式的效果類似，該效果同樣僅限於整體被位元組編譯後 (byte-compiled) 的程式碼。同樣的限制適用於 @code{getattr()}，@code{setattr()} 和 @code{delattr()}，以及直接參照 @code{__dict__} 時。

@node 補充說明,疊代器 Iterator,私有變數,Class（類別）
@anchor{tutorial/classes odds-and-ends}@anchor{1f6b}@anchor{tutorial/classes tut-odds}@anchor{1f6c}
@subsection 補充說明


如果有一種資料型別，類似於 Pascal 的「record」或 C 的「struct」，可以將一些有名稱的資料項目捆綁在一起，有時候這會很有用。符合語言習慣的做法是使用 @ref{33,,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 程式碼，經常能以傳遞一個 class 來替代，此 class 模擬該資料型別的多種 method。例如，如果你有一個函式，它會從一個檔案物件來格式化某些資料，你也可以定義一個有 @ref{1f33,,read()} 和 @ref{1f6d,,readline()} method 的 class 作為替代方式，從字串緩衝區取得資料，並將其作為引數來傳遞。

@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{1f6e,,實例的 method 物件}也具有屬性：@ref{15c0,,m.__self__} 就是帶有 method @code{m()} 的實例物件，而 @ref{14fd,,m.__func__} 則是該 method 所對應的@ref{596,,函式物件}。

@node 疊代器 Iterator,產生器 Generator,補充說明,Class（類別）
@anchor{tutorial/classes iterators}@anchor{1f6f}@anchor{tutorial/classes tut-iterators}@anchor{1f70}
@subsection 疊代器 (Iterator)


到目前為止，你可能已經注意到大多數的容器 (container) 物件都可以使用 @ref{348,,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

這種存取風格清晰、簡潔且方便。疊代器的使用在 Python 中處處可見且用法一致。在幕後，@ref{348,,for} 陳述式會在容器物件上呼叫 @ref{9d0,,iter()}。該函式回傳一個疊代器物件，此物件定義了 @ref{14ce,,__next__()} method，而此 method 會逐一存取容器中的元素。當元素用盡時，@ref{14ce,,__next__()} 將引發 @ref{df0,,StopIteration} 例外，來通知 @code{for} 終止迴圈。你可以使用內建函式 @ref{9d1,,next()} 來呼叫 @ref{14ce,,__next__()} method；這個例子展示了它的運作方式：

@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

看過疊代器協定的幕後機制後，在你的 class 加入疊代器的行為就很容易了。定義一個 @ref{1f71,,__iter__()} method 來回傳一個帶有 @ref{14ce,,__next__()} method 的物件。如果 class 已定義了 @code{__next__()}，則 @code{__iter__()} 可以只回傳 @code{self}：

@example
class Reverse:
    """用於向後迴圈遍歷序列的疊代器。"""
    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 產生器 Generator,產生器運算式,疊代器 Iterator,Class（類別）
@anchor{tutorial/classes generators}@anchor{1f72}@anchor{tutorial/classes tut-generators}@anchor{1f73}
@subsection 產生器 (Generator)


@ref{125c,,產生器}是一個用於建立疊代器的簡單而強大的工具。它們的寫法和常規的函式一樣，但當它們要回傳資料時，會使用 @ref{bb9,,yield} 陳述式。每次在產生器上呼叫 @ref{9d1,,next()} 時，它會從上次離開的位置恢復執行（它會記得所有資料值以及上一個被執行的陳述式）。以下範例顯示，建立產生器可以相當地容易：

@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

任何可以用產生器來完成的事，也能用以 class 為基礎的疊代器來完成，如同前一節的描述。而讓產生器的程式碼更為精簡的原因是，@ref{1f74,,__iter__()} 和 @ref{1f75,,__next__()} method 會自動被建立。

另一個關鍵的特性在於，區域變數和執行狀態會在每次呼叫之間自動被儲存。這使得該函式比使用 @code{self.index} 和 @code{self.data} 這種實例變數的方式更容易編寫且更為清晰。

除了會自動建立 method 和儲存程式狀態，當產生器終止時，它們還會自動引發 @ref{df0,,StopIteration}。這些特性結合在一起，使建立疊代器能與編寫常規函式一樣容易。

@node 產生器運算式,,產生器 Generator,Class（類別）
@anchor{tutorial/classes generator-expressions}@anchor{1f76}@anchor{tutorial/classes tut-genexps}@anchor{1f77}
@subsection 產生器運算式


某些簡單的產生器可以寫成如運算式一般的簡潔程式碼，所用的語法類似 list comprehension（串列綜合運算），但外層為括號而非方括號。這種運算式被設計用於產生器將立即被外圍函式 (enclosing function) 所使用的情況。產生器運算式與完整的產生器定義相比，程式碼較精簡但功能較少，也比等效的 list comprehension 更為節省記憶體。

例如：

@example
>>> sum(i*i for i in range(10))                 # 平方和
285

>>> xvec = [10, 20, 30]
>>> yvec = [7, 5, 3]
>>> sum(x*y for x,y in zip(xvec, yvec))         # 向量內積
260

>>> unique_words = set(word for line in page  for word in line.split())

>>> valedictorian = max((student.gpa, student.name) for student in graduates)

>>> data = 'golf'
>>> list(data[i] for i in range(len(data)-1, -1, -1))
['f', 'l', 'o', 'g']
@end example

@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 標準函式庫概覽——第二部份,Class（類別）,Python 教學
@anchor{tutorial/stdlib doc}@anchor{1f78}@anchor{tutorial/stdlib brief-tour-of-the-standard-library}@anchor{1f79}@anchor{tutorial/stdlib translation-repo}@anchor{1f7a}@anchor{tutorial/stdlib tut-brieftour}@anchor{1f7b}
@section Python 標準函式庫概覽


@menu
* 作業系統介面:: 
* 檔案之萬用字元 (File Wildcards): 檔案之萬用字元 File Wildcards. 
* 命令列引數:: 
* 錯誤輸出重新導向與程式終止:: 
* 字串樣式比對:: 
* 數學相關:: 
* 網路存取:: 
* 日期與時間:: 
* 資料壓縮:: 
* 效能量測:: 
* 品質控管:: 
* 標準模組庫:: 

@end menu

@node 作業系統介面,檔案之萬用字元 File Wildcards,,Python 標準函式庫概覽
@anchor{tutorial/stdlib operating-system-interface}@anchor{1f7c}@anchor{tutorial/stdlib tut-os-interface}@anchor{1f7d}
@subsection 作業系統介面


@ref{a5,,os} 模組提供了數十個與作業系統溝通的函式：

@example
>>> import os
>>> os.getcwd()      # 回傳目前的工作目錄
'C:\\Python314'
>>> os.chdir('/server/accesslogs')   # 改變目前的工作目錄
>>> os.system('mkdir today')   # 在系統 shell 中執行 mkdir 指令
0
@end example

務必使用 @code{import os} 而非 @code{from os import *}。這將避免因系統不同而有實作差異的 @ref{f8d,,os.open()} 覆蓋內建函式 @ref{315,,open()}。

@geindex built-in function（內建函式）;help（幫助）

在使用 @ref{a5,,os} 諸如此類大型模組時搭配內建函式 @ref{83d,,dir()} 和 @ref{acb,,help()} 是非常有用的：

@example
>>> import os
>>> dir(os)
<returns a list of all module functions>
>>> help(os)
<returns an extensive manual page created from the module's docstrings>
@end example

對於日常檔案和目錄管理任務，@ref{ca,,shutil} 模組提供了更容易使用的高階介面：

@example
>>> import shutil
>>> shutil.copyfile('data.db', 'archive.db')
'archive.db'
>>> shutil.move('/build/executables', 'installdir')
'installdir'
@end example

@node 檔案之萬用字元 File Wildcards,命令列引數,作業系統介面,Python 標準函式庫概覽
@anchor{tutorial/stdlib file-wildcards}@anchor{1f7e}@anchor{tutorial/stdlib tut-file-wildcards}@anchor{1f7f}
@subsection 檔案之萬用字元 (File Wildcards)


@ref{68,,glob} 模組提供了一函式可以從目錄萬用字元中搜尋並產生檔案列表：

@example
>>> import glob
>>> glob.glob('*.py')
['primes.py', 'random.py', 'quote.py']
@end example

@node 命令列引數,錯誤輸出重新導向與程式終止,檔案之萬用字元 File Wildcards,Python 標準函式庫概覽
@anchor{tutorial/stdlib command-line-arguments}@anchor{1f80}@anchor{tutorial/stdlib tut-command-line-arguments}@anchor{1f81}
@subsection 命令列引數


通用工具腳本常需要處理命令列引數。這些引數會以 list（串列）形式存放在 @ref{df,,sys} 模組的 `argv' 屬性中。例如以下 @code{demo.py} 檔案：

@example
# demo.py 檔案
import sys
print(sys.argv)
@end example

以下是在命令列運行 @code{python demo.py one two three} 的輸出：

@example
['demo.py', 'one', 'two', 'three']
@end example

@ref{7,,argparse} 模組提供了一種更複雜的機制來處理命令列引數。以下腳本可擷取一個或多個檔案名稱，並可選擇要顯示的行數：

@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} 在命令列執行時，該腳本會將 @code{args.lines} 設為 @code{5}，並將 @code{args.filenames} 設為 @code{['alpha.txt', 'beta.txt']}。

@node 錯誤輸出重新導向與程式終止,字串樣式比對,命令列引數,Python 標準函式庫概覽
@anchor{tutorial/stdlib error-output-redirection-and-program-termination}@anchor{1f82}@anchor{tutorial/stdlib tut-stderr}@anchor{1f83}
@subsection 錯誤輸出重新導向與程式終止


@ref{df,,sys} 模組也有 `stdin'，`stdout'，和 `stderr' 等屬性。即使當 `stdout' 被重新導向時，後者 `stderr' 可輸出警告和錯誤訊息：

@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

終止腳本最直接的方式就是利用 @code{sys.exit()}。

@node 字串樣式比對,數學相關,錯誤輸出重新導向與程式終止,Python 標準函式庫概覽
@anchor{tutorial/stdlib string-pattern-matching}@anchor{1f84}@anchor{tutorial/stdlib tut-string-pattern-matching}@anchor{1f85}
@subsection 字串樣式比對


@ref{be,,re} 模組提供正規表示式 (regular expression) 做進階的字串處理。當要處理複雜的比對以及操作時，正規表示式是簡潔且經過最佳化的解決方案：

@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

當只需要簡單的字串操作時，因為可讀性以及方便除錯，字串本身的 method 是比較建議的：

@example
>>> 'tea for too'.replace('too', 'two')
'tea for two'
@end example

@node 數學相關,網路存取,字串樣式比對,Python 標準函式庫概覽
@anchor{tutorial/stdlib mathematics}@anchor{1f86}@anchor{tutorial/stdlib tut-mathematics}@anchor{1f87}
@subsection 數學相關


@ref{92,,math} 模組提供了 C 函式庫中底層的浮點數運算的函式：

@example
>>> import math
>>> math.cos(math.pi / 4)
0.70710678118654757
>>> math.log(1024, 2)
10.0
@end example

@ref{bd,,random} 模組提供了隨機選擇的工具：

@example
>>> import random
>>> random.choice(['apple', 'pear', 'banana'])
'apple'
>>> random.sample(range(100), 10)   # 不重複抽樣
[30, 83, 16, 4, 8, 81, 41, 50, 18, 33]
>>> random.random()    # 區間 [0.0, 1.0) 中的隨機浮點數
0.17970987693706186
>>> random.randrange(6)    # 從 range(6) 中隨機選擇整數
4
@end example

@ref{d7,,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 網路存取,日期與時間,數學相關,Python 標準函式庫概覽
@anchor{tutorial/stdlib internet-access}@anchor{1f88}@anchor{tutorial/stdlib tut-internet-access}@anchor{1f89}
@subsection 網路存取


Python 中有許多存取網路以及處理網路協定。最簡單的兩個例子包括 @ref{111,,urllib.request} 模組可以從網址抓取資料以及 @ref{cf,,smtplib} 可以用來寄郵件：

@example
>>> from urllib.request import urlopen
>>> with urlopen('http://worldtimeapi.org/api/timezone/etc/UTC.txt') as response:
...     for line in response:
...         line = line.decode()             # 將 bytes 轉換為 str
...         if line.startswith('datetime'):
...             print(line.rstrip())         # 移除最後面的換行符號
...
datetime: 2022-01-01T01:36:47.689215+00:00

>>> import smtplib
>>> server = smtplib.SMTP('localhost')
>>> server.sendmail('soothsayer@@example.org', 'jcaesar@@example.org',
... """To: jcaesar@@example.org
... From: soothsayer@@example.org
...
... Beware the Ides of March.
... """)
>>> server.quit()
@end example

（注意第二個例子中需要在本地端執行一個郵件伺服器。）

@node 日期與時間,資料壓縮,網路存取,Python 標準函式庫概覽
@anchor{tutorial/stdlib dates-and-times}@anchor{1f8a}@anchor{tutorial/stdlib tut-dates-and-times}@anchor{1f8b}
@subsection 日期與時間


@ref{34,,datetime} 模組提供許多 class 可以操作日期以及時間，從簡單從複雜都有。模組支援日期與時間的運算，而實作的重點是有效率的成員擷取以達到輸出格式化以及操作。模組也提供支援時區換算的類別。

@example
>>> # 能夠輕易建立與格式化
>>> from datetime import date
>>> now = date.today()
>>> now
datetime.date(2003, 12, 2)
>>> now.strftime("%m-%d-%y. %d %b %Y is a %A on the %d day of %B.")
'12-02-03. 02 Dec 2003 is a Tuesday on the 02 day of December.'

>>> # 支援運算
>>> birthday = date(1964, 7, 31)
>>> age = now - birthday
>>> age.days
14368
@end example

@node 資料壓縮,效能量測,日期與時間,Python 標準函式庫概覽
@anchor{tutorial/stdlib data-compression}@anchor{1f8c}@anchor{tutorial/stdlib tut-data-compression}@anchor{1f8d}
@subsection 資料壓縮


常見的解壓縮以及壓縮格式都有直接支援的模組。包括：@ref{139,,zlib}、@ref{6b,,gzip}、@ref{14,,bz2}、@ref{8e,,lzma}、@ref{137,,zipfile} 以及 @ref{e4,,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 效能量測,品質控管,資料壓縮,Python 標準函式庫概覽
@anchor{tutorial/stdlib performance-measurement}@anchor{1f8e}@anchor{tutorial/stdlib tut-performance-measurement}@anchor{1f8f}
@subsection 效能量測


有一些 Python 使用者很想了解同個問題的不同實作方法的效能差異。Python 提供了評估效能差異的工具。

舉例來說，有人可能會試著用 tuple 的打包機制來交換引數代替傳統的方式。@ref{f5,,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{f5,,timeit} 模組提供這麼細的粒度，@ref{b4,,profile} 模組以及 @ref{b5,,pstats} 模組則提供了一些在大型的程式碼識別時間使用上關鍵的區塊 (time critical section) 的工具。

@node 品質控管,標準模組庫,效能量測,Python 標準函式庫概覽
@anchor{tutorial/stdlib quality-control}@anchor{1f90}@anchor{tutorial/stdlib tut-quality-control}@anchor{1f91}
@subsection 品質控管


達到高品質軟體的一個方法，是在開發時對每個函式寫測試，以及在開發過程中要不斷地跑這些測試。

@ref{3e,,doctest} 模組提供了一個工具，掃描模組並根據程式中內嵌的文件字串執行測試。撰寫測試如同簡單地將它的呼叫及輸出結果剪下並貼上到文件字串中。透過提供範例給使用者，它強化了說明文件，並允許 doctest 模組確認程式碼的結果與說明文件一致：

@example
def average(values):
    """計算數字串列的算術平均數。

    >>> print(average([20, 30, 70]))
    40.0
    """
    return sum(values) / len(values)

import doctest
doctest.testmod()   # 自動驗證內嵌的測試
@end example

@ref{10c,,unittest} 模組不像 @ref{3e,,doctest} 模組這般容易，但是它讓你可以在另外一個檔案裡撰寫更完整的測試集：

@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()  # 從命令列呼叫會執行所有測試
@end example

@node 標準模組庫,,品質控管,Python 標準函式庫概覽
@anchor{tutorial/stdlib batteries-included}@anchor{1f92}@anchor{tutorial/stdlib tut-batteries-included}@anchor{1f93}
@subsection 標準模組庫


"Batteries included" 是 Python 的設計哲學。這個理念可以透過使用它的大型套件，感受複雜與強大的功能，來得到印證。例如：


@itemize *

@item 
使用 @ref{134,,xmlrpc.client} 和 @ref{135,,xmlrpc.server} 模組使實作遠端程序呼叫變得更為容易。即使模組名稱裡有 XML，使用者並不需要直接操作 XML 檔案或事先具備相關知識。

@item 
函式庫 @ref{3f,,email} 套件用來管理 MIME 和其他 
@geindex RFC; RFC 2822
RFC 2822@footnote{https://datatracker.ietf.org/doc/html/rfc2822.html} 相關電子郵件訊息的文件。相異於 @ref{cf,,smtplib} 和 @ref{b1,,poplib} 這些實際用來發送與接收訊息的模組，email 套件擁有更完整的工具集，可用於建立與解碼複雜訊息結構（包含附件檔案）以及實作編碼與標頭協定。

@item 
@ref{86,,json} 套件對 JSON 資料交換格式的剖析，提供強大的支援。@ref{2d,,csv} 模組則提供直接讀寫 CSV（以逗號分隔值的檔案格式，通常資料庫和電子表格都有支援）。@ref{12b,,xml.etree.ElementTree}、@ref{127,,xml.dom} 與 @ref{12f,,xml.sax} 套件則支援 XML 的處理。綜觀所有，這些模組和套件都簡化了 Python 應用程式與其他工具之間的資料交換。

@item 
@code{sqllite3} 模組是 SQLite 資料庫函式庫的一層包裝，提供一個具持久性的資料庫，可以使用稍微非標準的 SQL 語法來對它進行更新與存取。

@item 
有數種支援國際化的模組，包括 @ref{67,,gettext}、@ref{8a,,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 Python 標準函式庫概覽——第二部份,虛擬環境與套件,Python 標準函式庫概覽,Python 教學
@anchor{tutorial/stdlib2 doc}@anchor{1f94}@anchor{tutorial/stdlib2 brief-tour-of-the-standard-library-part-ii}@anchor{1f95}@anchor{tutorial/stdlib2 translation-repo}@anchor{1f96}@anchor{tutorial/stdlib2 tut-brieftourtwo}@anchor{1f97}
@section Python 標準函式庫概覽——第二部份


第二部分涵蓋更多支援專業程式設計所需要的進階模組。這些模組很少出現在小腳本中。

@menu
* 輸出格式化 (Output Formatting): 輸出格式化 Output Formatting. 
* 模板化 (Templating): 模板化 Templating. 
* 二進制資料記錄編排 (Binary Data Record Layouts): 二進制資料記錄編排 Binary Data Record Layouts. 
* 多執行緒 (Multi-threading): 多執行緒 Multi-threading. 
* 日誌記錄 (Logging): 日誌記錄 Logging. 
* 弱引用 (Weak References): 弱引用 Weak References. 
* 使用於 List 的工具:: 
* 十進制浮點數運算 (Decimal Floating-Point Arithmetic): 十進制浮點數運算 Decimal Floating-Point Arithmetic. 

@end menu

@node 輸出格式化 Output Formatting,模板化 Templating,,Python 標準函式庫概覽——第二部份
@anchor{tutorial/stdlib2 output-formatting}@anchor{1f98}@anchor{tutorial/stdlib2 tut-output-formatting}@anchor{1f99}
@subsection 輸出格式化 (Output Formatting)


@ref{c0,,reprlib} 模組提供了一個 @ref{1c1,,repr()} 的版本，專門用來以簡短的形式顯示大型或深層的巢狀容器：

@example
>>> import reprlib
>>> reprlib.repr(set('supercalifragilisticexpialidocious'))
"@{'a', 'c', 'd', 'e', 'f', 'g', ...@}"
@end example

@ref{b3,,pprint} 模組能對內建和使用者自定的物件提供更複雜的列印控制，並且是以直譯器可讀的方式。當結果超過一行時，「漂亮的印表機」會加入換行和縮排，以更清楚地顯示資料結構：

@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

@ref{f2,,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

@ref{8a,,locale} 模組能存取一個含有特定文化相關資料格式的資料庫。locale 模組的 format 函式有一個 grouping 屬性，可直接以群分隔符 (group separator) 將數字格式化：

@example
>>> import locale
>>> locale.setlocale(locale.LC_ALL, 'English_United States.1252')
'English_United States.1252'
>>> conv = locale.localeconv()          # 取得慣例的對映
>>> 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,二進制資料記錄編排 Binary Data Record Layouts,輸出格式化 Output Formatting,Python 標準函式庫概覽——第二部份
@anchor{tutorial/stdlib2 templating}@anchor{1f9a}@anchor{tutorial/stdlib2 tut-templating}@anchor{1f9b}
@subsection 模板化 (Templating)


@ref{d8,,string} 模組包含一個多功能的 @ref{890,,Template} class，提供的簡化語法適合使用者進行編輯時使用。它容許使用者客製化自己的應用程式，但不必對原應用程式做出變更。

格式化方式是使用佔位符號名稱 (placeholder name)，它是由 @code{$} 加上合法的 Python 識別符（字母、數字和下底線）構成。使用大括號包覆佔位符號以允許在後面接上更多的字母和數字而無需插入空格。使用 @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

如果在 dictionary 或關鍵字引數中未提供某個佔位符號的值，那麼 @ref{1f9c,,substitute()} method 將引發 @ref{5df,,KeyError}。對於郵件合併 (mail-merge) 類型的應用程式，使用者提供的資料有可能是不完整的，此時使用 @ref{1f9d,,safe_substitute()} method 會更適當——如果資料有缺少，它會保持佔位符號不變：

@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

Template 的 subclass（子類別）可以指定自訂的分隔符號 (delimiter)。例如，一個相片瀏覽器的批次重新命名功能，可以選擇用百分號作為現在日期、照片序號或檔案格式的佔位符號：

@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

模板化的另一個應用，是將程式邏輯與多樣的輸出格式細節分離開來。這樣就可以為 XML 檔案、純文字報表和 HTML 網路報表替換自訂的模板。

@node 二進制資料記錄編排 Binary Data Record Layouts,多執行緒 Multi-threading,模板化 Templating,Python 標準函式庫概覽——第二部份
@anchor{tutorial/stdlib2 tut-binary-formats}@anchor{1f9e}@anchor{tutorial/stdlib2 working-with-binary-data-record-layouts}@anchor{1f9f}
@subsection 二進制資料記錄編排 (Binary Data Record Layouts)


@ref{db,,struct} 模組提供了 @ref{1477,,pack()} 和 @ref{17da,,unpack()} 函式，用於處理可變動長度的二進制記錄格式。以下範例說明，如何在不使用 @ref{137,,zipfile} 模組的情況下，使用迴圈瀏覽一個 ZIP 檔案中的標頭資訊 (header information)。壓縮程式碼 @code{"H"} 和 @code{"I"} 分別代表兩個和四個位元組的無符號數 (unsigned number)。@code{"<"} 表示它們是標準大小，並使用小端 (little-endian) 位元組順序：

@example
import struct

with open('myfile.zip', 'rb') as f:
    data = f.read()

start = 0
for i in range(3):                      # 顯示前 3 個檔案標頭
    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     # 跳到下一個標頭
@end example

@node 多執行緒 Multi-threading,日誌記錄 Logging,二進制資料記錄編排 Binary Data Record Layouts,Python 標準函式庫概覽——第二部份
@anchor{tutorial/stdlib2 multi-threading}@anchor{1fa0}@anchor{tutorial/stdlib2 tut-multi-threading}@anchor{1fa1}
@subsection 多執行緒 (Multi-threading)


執行緒是一種用來對非順序相依 (sequentially dependent) 的多個任務進行解耦 (decoupling) 的技術。當其他任務在背景執行時，多執行緒可以用來提升應用程式在接收使用者輸入時的反應能力。一個相關的用例是，運行 I/O 的同時，在另一個執行緒中進行計算。

以下程式碼顯示了高階的 @ref{f3,,threading} 模組如何在背景運行任務，而主程式同時繼續運行：

@example
import threading, zipfile

class AsyncZip(threading.Thread):
    def __init__(self, infile, outfile):
        threading.Thread.__init__(self)
        self.infile = infile
        self.outfile = outfile

    def run(self):
        f = zipfile.ZipFile(self.outfile, 'w', zipfile.ZIP_DEFLATED)
        f.write(self.infile)
        f.close()
        print('Finished background zip of:', self.infile)

background = AsyncZip('mydata.txt', 'myarchive.zip')
background.start()
print('The main program continues to run in foreground.')

background.join()    # 等待背景任務結束
print('Main program waited until background was done.')
@end example

多執行緒應用程式的主要挑戰是，要協調多個彼此共享資料或資源的執行緒。為此，threading 模組提供了多個同步處理原始物件 (synchronization primitive)，包括鎖 (lock)、事件 (event)、條件變數 (condition variable) 和號誌 (semaphore)。

儘管這些工具很強大，但很小的設計錯誤也可能導致一些難以重現的問題。所以，任務協調的首選方法是，把所有對資源的存取集中到單一的執行緒中，然後使用 @ref{bb,,queue} 模組向該執行緒饋送來自其他執行緒的請求。應用程式若使用 @ref{158c,,Queue} 物件進行執行緒間的通信和協調，會更易於設計、更易讀、更可靠。

@node 日誌記錄 Logging,弱引用 Weak References,多執行緒 Multi-threading,Python 標準函式庫概覽——第二部份
@anchor{tutorial/stdlib2 logging}@anchor{1fa2}@anchor{tutorial/stdlib2 tut-logging}@anchor{1fa3}
@subsection 日誌記錄 (Logging)


@ref{8b,,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

在預設情況，資訊和除錯訊息不會被顯示，其輸出會被發送到標準錯誤 (standard error)。其他輸出選項包括，將訊息轉發到電子郵件、資料報 (datagram)、網路插座 (socket) 或 HTTP 伺服器。新的過濾器可以根據訊息的優先順序，選擇不同的路由 (routing) 方式：@ref{1fa4,,DEBUG}、@ref{1fa5,,INFO}、@ref{1fa6,,WARNING}、@ref{1fa7,,ERROR} 及 @ref{1fa8,,CRITICAL}。

日誌記錄系統可以直接從 Python 配置，也可以透過載入使用者可編輯的配置檔案以進行客製化的日誌記錄，而無須對應用程式做出變更。

@node 弱引用 Weak References,使用於 List 的工具,日誌記錄 Logging,Python 標準函式庫概覽——第二部份
@anchor{tutorial/stdlib2 tut-weak-references}@anchor{1fa9}@anchor{tutorial/stdlib2 weak-references}@anchor{1faa}
@subsection 弱引用 (Weak References)


Python 會自動進行記憶體管理（對大多數物件進行參照計數 (reference counting) 並使用 @ref{1765,,garbage collection} 來消除循環參照）。當一個參照從記憶體被移除後不久，該記憶體就會被釋出。

此方式對大多數應用程式來說都沒問題，但偶爾也需要在物件仍然被其他物件所使用時持續追蹤它們。可惜的是，儘管只是追蹤它們，也會建立一個使它們永久化 (permanent) 的參照。@ref{11a,,weakref} 模組提供的工具可以不必建立參照就能追蹤物件。當該物件不再被需要時，它會自動從一個弱引用表 (weakref table) 中被移除，並為弱引用物件觸發一個回呼 (callback)。典型的應用包括暫存 (cache) 那些成本較為昂貴的物件：

@example
>>> import weakref, gc
>>> class A:
...     def __init__(self, value):
...         self.value = value
...     def __repr__(self):
...         return str(self.value)
...
>>> a = A(10)                   # 建立一個參照
>>> d = weakref.WeakValueDictionary()
>>> d['primary'] = a            # 不會建立參照
>>> d['primary']                # 如果物件仍然存在則取得它
10
>>> del a                       # 移除一個參照
>>> gc.collect()                # 立即執行垃圾回收
0
>>> d['primary']                # 項目被自動移除
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
    d['primary']                # 項目被自動移除
  File "C:/python314/lib/weakref.py", line 46, in __getitem__
    o = self.data[key]()
KeyError: 'primary'
@end example

@node 使用於 List 的工具,十進制浮點數運算 Decimal Floating-Point Arithmetic,弱引用 Weak References,Python 標準函式庫概覽——第二部份
@anchor{tutorial/stdlib2 tools-for-working-with-lists}@anchor{1fab}@anchor{tutorial/stdlib2 tut-list-tools}@anchor{1fac}
@subsection 使用於 List 的工具


許多對於資料結構的需求，可以透過內建的 list（串列）型別來滿足。但是，有時也會根據效能的各種取捨，需要一些替代的實作。

@ref{8,,array} 模組提供了一個 @ref{4b9,,array} 物件，它像是 list，但只能儲存同類的資料且能緊密地儲存。下面的範例展示一個數值陣列 (array)，以兩個位元組的無符號二進數 (unsigned binary numbers) 為儲存單位（類型碼為 @code{"H"}），而在 Python 整數物件的正規 list 中，每個項目通常使用 16 個位元組：

@example
>>> from array import array
>>> a = array('H', [4000, 10, 700, 22222])
>>> sum(a)
26932
>>> a[1:3]
array('H', [10, 700])
@end example

@ref{1e,,collections} 模組提供了一個 @ref{7ed,,deque} 物件，它像是 list，但從左側加入 (append) 和彈出 (pop) 的速度較快，而在中間查找的速度則較慢。這種物件適用於實作佇列 (queue) 和廣度優先搜尋法 (breadth first tree search)：

@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

除了替代的 list 實作以外，函式庫也提供了其他工具，例如 @ref{12,,bisect} 模組，具有能夠操作 sorted list（已排序串列）的函式：

@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

@ref{6d,,heapq} 模組提供了一些函式，能基於正規 list 來實作堆積 (heap)。最小值的項目會永遠保持在位置零。對於一些需要多次存取最小元素，但不想要對整個 list 進行排序的應用程式來說，這會很有用：

@example
>>> from heapq import heapify, heappop, heappush
>>> data = [1, 3, 5, 7, 9, 2, 4, 6, 8, 0]
>>> heapify(data)                      # 將串列重新排列為堆積順序
>>> heappush(data, -5)                 # 加入新項目
>>> [heappop(data) for i in range(3)]  # 取得三個最小的項目
[-5, 0, 1]
@end example

@node 十進制浮點數運算 Decimal Floating-Point Arithmetic,,使用於 List 的工具,Python 標準函式庫概覽——第二部份
@anchor{tutorial/stdlib2 decimal-floating-point-arithmetic}@anchor{1fad}@anchor{tutorial/stdlib2 tut-decimal-fp}@anchor{1fae}
@subsection 十進制浮點數運算 (Decimal Floating-Point Arithmetic)


@ref{3a,,decimal} 模組提供了一個 @ref{1fe,,Decimal} 資料類型，用於十進制浮點數運算。相較於內建的二進制浮點數 @ref{196,,float} 實作，該 class 特別適用於下列情境


@itemize *

@item 
金融應用程式及其他需要準確十進位制表示法的應用，

@item 
對於精確度 (precision) 的控制，

@item 
控制四捨五入，以滿足法律或監管規範，

@item 
追蹤有效的小數位數 (decimal place)，或

@item 
使用者會期望計算結果與手工計算相符的應用程式。
@end itemize

例如，要計算 70 美分的手機充電加上 5% 稅金的總價，使用十進制浮點數和二進制浮點數，會算出不同的答案。如果把計算結果四捨五入到最接近的美分，兩者的差異會更顯著：

@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{1fe,,Decimal} 的運算結果會保留尾部的零，也會根據有兩個有效位數的被乘數自動推斷出有四個有效位數的乘積。Decimal 可以重現手工計算的結果，以避免產生二進制浮點數無法準確表示十進制數值時會導致的問題。

準確的表示法使得 @ref{1fe,,Decimal} class 能夠執行對於二進制浮點數不適用的模數計算和相等性檢測：

@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

@ref{3a,,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 虛擬環境與套件,現在可以來學習些什麼？,Python 標準函式庫概覽——第二部份,Python 教學
@anchor{tutorial/venv doc}@anchor{1faf}@anchor{tutorial/venv translation-repo}@anchor{1fb0}@anchor{tutorial/venv tut-venv}@anchor{1fb1}@anchor{tutorial/venv virtual-environments-and-packages}@anchor{1fb2}
@section 虛擬環境與套件


@menu
* 簡介: 簡介<4>. 
* 建立虛擬環境:: 
* 用 pip 管理套件:: 

@end menu

@node 簡介<4>,建立虛擬環境,,虛擬環境與套件
@anchor{tutorial/venv introduction}@anchor{1fb3}
@subsection 簡介


Python 應用程式通常會用到不在標準函式庫的套件和模組。應用程式有時候會需要某個特定版本的函式庫，因為這個應用程式可能需要某個特殊的臭蟲修正，或是這個應用程式是根據該函式庫特定版本的介面所撰寫。

這意味著不太可能安裝一套 Python 就可以滿足所有應用程式的要求。如果應用程式 A 需要一個特定的模組的 1.0 版，但另外一個應用程式 B 需要 2.0 版，那麼這整個需求不管安裝 1.0 或是 2.0 都會衝突，以致於應用程式無法使用。

解決方案是建立一個@ref{1fb4,,虛擬環境 (virtual environment)}，這是一個獨立的資料夾，並且裡面裝好了特定版本的 Python，以及一系列相關的套件。

不同的應用程式可以使用不同的虛擬環境。以前述中需要被解決的例子中，應用程式 A 能夠擁有它自己的虛擬環境，並且是裝好 1.0 版，然而應用程式 B 則可以是用另外一個有 2.0 版的虛擬環境。要是應用程式 B 需要某個函式庫被升級到 3.0 版，這並不會影響到應用程式 A 的環境。

@node 建立虛擬環境,用 pip 管理套件,簡介<4>,虛擬環境與套件
@anchor{tutorial/venv creating-virtual-environments}@anchor{1fb5}
@subsection 建立虛擬環境


用來建立與管理虛擬環境的模組叫做 @ref{117,,venv}。@ref{117,,venv} 將安裝執行命令的 Python 版本（如 @ref{f12,,--version} 選項所報告的）。例如使用 @code{python3.12} 執行命令將安裝 3.12 版本。

在建立虛擬環境的時候，在你決定要放該虛擬環境的資料夾之後，以腳本 (script) 執行 @ref{117,,venv} 模組並且給定資料夾路徑：

@example
python -m venv tutorial-env
@end example

如果 @code{tutorial-env} 不存在的話，這會建立 @code{tutorial-env} 資料夾，並且也會在裡面建立一個有 Python 直譯器的複本以及不同的支援檔案的資料夾。

虛擬環境的常用資料夾位置是 @code{.venv}。這個名稱通常會使該資料夾在你的 shell 中保持隱藏，因此這樣命名既可以解釋資料夾存在的原因，也不會造成任何困擾。它還能防止與某些工具所支援的 @code{.env} 環境變數定義檔案發生衝突。

一旦你建立了一個虛擬環境，你可以啟動它。

在 Windows 系統中，使用：

@example
tutorial-env\Scripts\activate
@end example

在 Unix 或 MacOS 系統，使用：

@example
source tutorial-env/bin/activate
@end example

（這段程式碼適用於 bash shell。如果你是用 @code{csh} 或者 @code{fish} shell，應當使用替代的 @code{activate.csh} 與 @code{activate.fish} 腳本。）

啟動虛擬環境會改變你的 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
deactivate
@end example

於終端機中。

@node 用 pip 管理套件,,建立虛擬環境,虛擬環境與套件
@anchor{tutorial/venv managing-packages-with-pip}@anchor{1fb6}
@subsection 用 pip 管理套件


你可以使用一個叫做 @code{pip} 的程式來安裝、升級和移除套件。@code{pip} 預設會從 Python Package Index@footnote{https://pypi.org} 安裝套件。你可以透過你的網頁瀏覽器瀏覽 Python Package Index。

@code{pip} 有好幾個子命令："install"、"uninstall"、"freeze" 等等。（可以參考@ref{10f3,,安裝 Python 模組}指南，來取得 @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{10f3,,安裝 Python 模組}指南，來取得完整的 @code{pip} 說明文件。當你撰寫了一個套件並且想要讓它在 Python Package Index 上可以取得的話，可以參考 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 現在可以來學習些什麼？,互動式輸入編輯和歷史記錄替換,虛擬環境與套件,Python 教學
@anchor{tutorial/whatnow doc}@anchor{1fb7}@anchor{tutorial/whatnow translation-repo}@anchor{1fb8}@anchor{tutorial/whatnow tut-whatnow}@anchor{1fb9}@anchor{tutorial/whatnow what-now}@anchor{1fba}
@section 現在可以來學習些什麼？


閱讀本教學可能增強你對於使用 Python 的興趣——你應該非常渴望使用 Python 來解決在現實生活中所遭遇的問題。該從哪裡學習更多呢？

本教學是 Python 文件中的一部分。這份文件集裡頭的其他文件包含：


@itemize *

@item 
@ref{149,,Python 標準函式庫 (Standard Library)}：

你該好好的瀏覽這份手冊，它提供了完整（但簡潔）的參考素材像是型別、函式與標準函式庫裡的模組。標準的 Python 發行版本會包含`大量'的附加程式碼。有些模組可以讀取 Unix 信箱、通過 HTTP 來檢索文件、產生亂數、分析命令列選項、壓縮資料、及許多其他任務。瀏覽函式庫參考手冊可以讓你了解有哪些模組可以用。

@item 
@ref{10f3,,安裝 Python 模組}：說明與解釋如何安裝其他 Python 使用者所編寫的模組。

@item 
@ref{14a,,Python 語言參考手冊}：Python 語法以及語意的詳細說明。這份文件閱讀起來會有些吃力，但作為一個語言本身的完整指南是非常有用的。
@end itemize

更多 Python 的資源：


@itemize *

@item 
@indicateurl{https://www.python.org}：Python 的主要網站。它包含程式碼、文件以及連結到 Python 相關聯的網頁。

@item 
@indicateurl{https://docs.python.org}：快速存取 Python 的文件。

@item 
@indicateurl{https://pypi.org}：Python 套件索引 (Python Package Index)，之前也被暱稱為 Cheese Shop @footnote{
「Cheese Shop（起司店）」是 Monty Python 的一個短劇：一位顧客進入一家起司店，但無論他要哪種起司，店員都說沒有貨。
}，彙總了使用者開發 Python 模組的索引，並提供模組能夠被下載。一旦開始發佈相關程式碼，你可以將開發的作品註冊到這裡並且讓其他人找到。

@item 
@indicateurl{https://code.activestate.com/recipes/langs/python/}：Python Cookbook 是一個相當大的程式碼集，包含程式碼範例、較大的模組以及有用的腳本。特別值得注意的貢獻則被收集在一本名為 Python Cookbook (O'Reilly & Associates, ISBN 0-596-00797-3.) 的書籍中。

@item 
@indicateurl{https://pyvideo.org} 從研討會與使用者群組聚會裡收集與 Python 相關的影片連結。

@item 
@indicateurl{https://scipy.org}：The Scientific Python 專案是一個包含用於高速陣列運算與操作的模組，以及用於如線性代數、傅利葉變換、非線性求解器、隨機數分佈、統計分析等一系列的套件。
@end itemize

對於 Python 相關的疑問與問題回報，你可以張貼到新聞群組@code{comp.lang.python}，或將它們寄至 @email{python-list@@python.org} 的郵寄清單 (mailing list)。新聞群組和郵寄清單是個閘道，因此張貼到其中的郵件都將自動轉發給另一個。每天會有數以百計的內容，詢問（和回答）問題、建議新功能與發佈新的模組。郵寄清單會存檔在 @indicateurl{https://mail.python.org/pipermail/}。

在張貼之前，請先確認問題是否在@ref{1fbb,,常見問題}（也被稱為 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 互動式輸入編輯和歷史記錄替換,浮點數運算：問題與限制,現在可以來學習些什麼？,Python 教學
@anchor{tutorial/interactive doc}@anchor{1fbc}@anchor{tutorial/interactive interactive-input-editing-and-history-substitution}@anchor{1fbd}@anchor{tutorial/interactive translation-repo}@anchor{1fbe}@anchor{tutorial/interactive tut-interacting}@anchor{1e92}
@section 互動式輸入編輯和歷史記錄替換


有些版本的 Python 直譯器支援目前輸入內容的編輯和歷史記錄的替換 (history substitution)，類似在 Korn shell 和 GNU Bash shell 中的功能。這個功能是用 GNU Readline@footnote{https://tiswww.case.edu/php/chet/readline/rltop.html} 函式庫來實作，它支援多種編輯的風格。這個函式庫有它自己的說明文件，在這裡我們就不重複了。

@menu
* Tab 鍵自動完成 (Tab Completion) 和歷史記錄編輯 (History Editing): Tab 鍵自動完成 Tab Completion 和歷史記錄編輯 History Editing. 
* 互動式直譯器的替代方案:: 

@end menu

@node Tab 鍵自動完成 Tab Completion 和歷史記錄編輯 History Editing,互動式直譯器的替代方案,,互動式輸入編輯和歷史記錄替換
@anchor{tutorial/interactive tab-completion-and-history-editing}@anchor{1fbf}@anchor{tutorial/interactive tut-keybindings}@anchor{1fc0}
@subsection Tab 鍵自動完成 (Tab Completion) 和歷史記錄編輯 (History Editing)


在直譯器啟動的時候，變數和模組名稱的自動完成功能會被@ref{11c4,,自動啟用}，所以可以用 @code{Tab} 鍵來叫用自動完成函式；它會查看 Python 的陳述式名稱、目前區域變數名稱和可用模組名稱。對於像是 @code{string.a} 的點分隔運算式 (dotted expression)，它會對最後一個 @code{'.'} 之前的運算式求值，然後根據求值結果物件的屬性，給予自動完成的建議。請注意，如果一個物件有 @ref{6f3,,__getattr__()} method（方法），同時又是該運算式的一部份，這樣可能會執行應用程式自定義的程式碼。預設設定也會把你的指令歷史記錄儲存在你的使用者資料夾內，一個名為 @code{.python_history} 的檔案中。在下一次啟動互動式直譯器時，這些歷史記錄依然可以被使用。

@node 互動式直譯器的替代方案,,Tab 鍵自動完成 Tab Completion 和歷史記錄編輯 History Editing,互動式輸入編輯和歷史記錄替換
@anchor{tutorial/interactive alternatives-to-the-interactive-interpreter}@anchor{1fc1}@anchor{tutorial/interactive tut-commentary}@anchor{1fc2}
@subsection 互動式直譯器的替代方案


與早期版本的直譯器相比，上述功能的出現的確是一個巨大的進步；但還是有一些願望沒有被實現：如果能在每次換行時給予適當的縮排建議（剖析器 (parser) 知道下一行是否需要縮排標記 (@ref{1fc3,,INDENT} token)），那就更棒了。自動完成機制可能會使用直譯器的符號表。若有一個命令能夠檢查（或甚至建議）括號、引號和其他符號的匹配，那也會很有用。

有一個功能增強的互動式直譯器替代方案，已經存在一段時間，稱為 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 浮點數運算：問題與限制,附錄,互動式輸入編輯和歷史記錄替換,Python 教學
@anchor{tutorial/floatingpoint doc}@anchor{1fc4}@anchor{tutorial/floatingpoint floating-point-arithmetic-issues-and-limitations}@anchor{1fc5}@anchor{tutorial/floatingpoint translation-repo}@anchor{1fc6}@anchor{tutorial/floatingpoint tut-fp-issues}@anchor{1fc7}
@section 浮點數運算：問題與限制


在計算機架構中，浮點數 (floating-point number) 是以基數為 2（二進位）的小數表示。例如說，在`十進位'小數中 @code{0.625} 可被分為 6/10 + 2/100 + 5/1000，同樣的道理，`二進位'小數 @code{0.101} 可被分為 1/2 + 0/4 + 1/8。這兩個小數有相同的數值，而唯一真正的不同在於前者以十進位表示，後者以二進位表示。

不幸的是，大多數十進位小數無法精準地以二進位小數表示。一般的結果為，你輸入的十進位浮點數只能由實際儲存在計算機中的二進位浮點數近似。

在十進位中，這個問題更容易被理解。以分數 1/3 為例，你可以將其近似為十進位小數：

@example
0.3
@end example

或者，更好的近似：

@example
0.33
@end example

或者，更好的近似：

@example
0.333
@end example

依此類推，不論你使用多少位數表示小數，最後的結果都無法精準地表示 1/3，但你還是能越來越精準地表示 1/3。

同樣的道理，不論你願意以多少位數表示二進位小數，十進位小數 0.1 都無法被二進位小數精準地表達。在二進位小數中，1/10 會是一個無限循環小數：

@example
0.0001100110011001100110011001100110011001100110011...
@end example

只要你停在任何有限的位數，你就只會得到近似值。而現在大多數的計算機中，浮點數是透過二進位分數近似的，其中分子是從最高有效位元開始，用 53 個位元表示，分母則是以二為底的指數。在 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.10000000000000001} 和 @code{0.1000000000000000055511151231257827021181583404541015625}，都由 @code{3602879701896397 / 2 ** 55} 近似。由於這三個十進位數值共用同一個近似值，任何一個數值都可以被顯示，同時保持 @code{eval(repr(x)) == x}。

歷史上，Python 的提示字元 (prompt) 與內建的 @ref{1c1,,repr()} 函式會選擇上段說明中有 17 個有效位元的數：@code{0.10000000000000001}。從 Python 3.1 版開始，Python（在大部分的系統上）現在能選擇其中最短的數並簡單地顯示為 @code{0.1}。

注意，這是二進位浮點數理所當然的特性，並不是 Python 的錯誤 (bug)，更不是你程式碼的錯誤。只要程式語言有支援硬體的浮點數運算，你將會看到同樣的事情出現在其中（雖然有些程式語言預設不會`顯示'該差異，有些甚至是在所有的輸出模式中都不會顯示。）

為求更優雅的輸出，你可能想要使用字串的格式化 (string formatting) 產生限定的有效位數：

@example
>>> format(math.pi, '.12g')  # 給出 12 個有效位數
'3.14159265359'

>>> format(math.pi, '.2f')   # 小數點後給出 2 位數字
'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{14db,,round()} 函式捨入並不會有幫助：

@example
>>> round(0.1, 1) + round(0.1, 1) + round(0.1, 1) == round(0.3, 1)
False
@end example

雖然數字不會再更接近他們的精準數值，但 @ref{fab,,math.isclose()} 函式可以用來比較不精確的值：

@example
>>> math.isclose(0.1 + 0.1 + 0.1, 0.3)
True
@end example

或者，可以使用 @ref{14db,,round()} 函式來比較粗略的近似值：

@example
>>> round(math.pi, ndigits=2) == round(22 / 7, ndigits=2)
True
@end example

二進位浮點數架構下還有很多這樣的意外。底下的「表示法誤差 (Representation Error)」章節，詳細地解釋了「0.1」的問題。Examples of Floating Point Problems（浮點數問題範例）@footnote{https://jvns.ca/blog/2023/01/13/examples-of-floating-point-problems/}一文提供了二進位浮點數的作用方式與現實中這類常見問題的摘錄。如果想要其他常見問題的更完整描述，可以參考 The Perils of Floating Point（浮點數的風險）@footnote{http://www.indowsway.com/floatingpoint.htm}。

如同上文的末段所述，「這個問題並沒有簡單的答案。」不過，也不必對浮點過度擔心！Python 的 float（浮點數）運算中的誤差，是從浮點硬體繼承而來，而在大多數的計算機上，每次運算的誤差範圍不會大於 2**53 分之 1。這對大多數的任務來說已經相當足夠，但你需要記住，它並非十進位運算，且每一次 float 運算都可能會承受新的捨入誤差。

雖然浮點運算確實存在一些問題，但在一般情況下，如果你只是把最終結果的顯示值，以十進位方式捨入至預期的位數，那麼仍會得到你預期的結果。@ref{169,,str()} 通常就能滿足要求，而若想要更細緻的控制，可參閱@ref{1593,,格式化文字語法}中關於 @ref{82c,,str.format()} method（方法）的格式規範。

對於需要精準十進位表示法的用例，可以試著用 @ref{3a,,decimal} 模組，它可實作適用於會計應用程式與高精確度應用程式的十進位運算。

另一種支援精準運算的格式為 @ref{61,,fractions} 模組，該模組基於有理數來實作運算（因此可以精確表示像 1/3 這樣的數字）。

如果你是浮點運算的重度使用者，你應該看一下 NumPy 套件，以及由 SciPy 專案提供的許多用於數學和統計學運算的其他套件。請參閱 <@indicateurl{https://scipy.org}>。

在罕見情況下，當你`真的'想知道一個 float 的精準值，Python 提供的工具可協助達成。@ref{1fc8,,float.as_integer_ratio()} method 可將一個 float 的值表示為分數：

@example
>>> x = 3.14159
>>> x.as_integer_ratio()
(3537115888337719, 1125899906842624)
@end example

由於該比率是精準的，它可無損地再現該原始值：

@example
>>> x == 3537115888337719 / 1125899906842624
True
@end example

@ref{1fc9,,float.hex()} method 以十六進位（基數為 16）表示 float，一樣可以給出你的電腦所儲存的精準值：

@example
>>> x.hex()
'0x1.921f9f01b866ep+1'
@end example

這種精確的十六進位表示法可用於精準地重建 float 值：

@example
>>> x == float.fromhex('0x1.921f9f01b866ep+1')
True
@end example

由於該表示法是精準的，因此適用於在不同版本的 Python 之間可靠地傳送數值（獨立於系統平台），並與支援相同格式的其他語言（如 JAVA 和 C99）交換資料。

另一個有用的工具是 @ref{68e,,sum()} 函式，能在計算總和時幫忙減少精確度的損失。當數值被加到運行中的總計值時，它會追蹤「失去的位數 (lost digits)」。這可以明顯改善總體準確度 (overall accuracy)，使得誤差不至於累積到影響最終總計值的程度：

@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{15cb,,math.fsum()} 更進一步將數值被加到運行總計中的總計時追蹤所有「失去的位數」，以便結果僅有一次捨入。這比 @ref{68e,,sum()} 慢，但在不常見的情況下會更準確，在這種情況下，大量輸入大多相互抵消，最終的總和會接近於零：

@example
>>> arr = [-0.10430216751806065, -266310978.67179024, 143401161448607.16,
...        -143401161400469.7, 266262841.31058735, -0.003244936839808227]
>>> float(sum(map(Fraction, arr)))   # 單次四捨五入的精確加總
8.042173697819788e-13
>>> math.fsum(arr)                   # 單次四捨五入
8.042173697819788e-13
>>> sum(arr)                         # 在擴展精度中進行多次捨入
8.042178034628478e-13
>>> total = 0.0
>>> for x in arr:
...     total += x                   # 在標準精度中進行多次捨入
...
>>> total                            # 直接相加沒有正確的數字
-0.0051575902860057365
@end example

@menu
* 表示法誤差 (Representation Error): 表示法誤差 Representation Error. 

@end menu

@node 表示法誤差 Representation Error,,,浮點數運算：問題與限制
@anchor{tutorial/floatingpoint representation-error}@anchor{1fca}@anchor{tutorial/floatingpoint tut-fp-error}@anchor{1fcb}
@subsection 表示法誤差 (Representation Error)


本節將會詳細解釋「0.1」的例子，並說明你自己要如何對類似案例執行精準的分析。 以下假設你對二進位浮點表示法已有基本程度的熟悉。

`Representation error'（表示法誤差）是指在真實情況中，有些（實際上是大多數）十進位小數並不能精準地以二進位（基數為 2）小數表示。這是 Python（或 Perl、C、C++、JAVA、Fortran 和其他許多）通常不會顯示你期望的精準十進位數字的主要原因。

為什麼呢？因為 1/10 無法精準地以一個二進位小數來表示。至少自從 2000 年以來，幾乎所有的計算機皆使用 IEEE-754 浮點數運算標準，並且幾乎所有的平台都以 IEEE 754 binary64 標準中的「雙精度 (double precision)」來作為 Python 的 float。IEEE 754 binary64 的值包含 53 位元的精度，所以在輸入時，電腦會努力把 0.1 轉換到最接近的分數，以 `J'/2**`N' 的形式表示，此處 `J' 是一個正好包含 53 位元的整數。可以將：

@example
1 / 10 ~= J / (2**N)
@end example

重寫為：

@example
J ~= 2**N / 10
@end example

而前面提到 `J' 有精準的 53 位元（即 @code{>= 2**52} 但 @code{< 2**53}），所以 `N' 的最佳數值是 56：

@example
>>> 2**52 <=  2**56 // 10  < 2**53
True
@end example

意即，要使 `J' 正好有 53 位元，則 56 會是 `N' 的唯一值。而 `J' 最有可能的數值就是經過捨入後的該商數：

@example
>>> q, r = divmod(2**56, 10)
>>> r
6
@end example

由於餘數超過 10 的一半，所以最佳的近似值是透過進位而得：

@example
>>> q+1
7205759403792794
@end example

所以，在 IEEE 754 雙精度下，1/10 的最佳近似值是：

@example
7205759403792794 / 2 ** 56
@end example

將分子和分母同除以二，會約分為：

@example
3602879701896397 / 2 ** 55
@end example

請注意，由於我們有進位，所以這實際上比 1/10 大了一點；如果我們沒有進位，商數將會有點小於 1/10。但在任何情況下都不可能是`精準的' 1/10！

所以電腦從來沒有「看到」1/10：它看到的是上述的精準分數，也就是它能得到的 IEEE 754 double 最佳近似值：

@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

@ref{61,,fractions} 與 @ref{3a,,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{1fcc}@anchor{tutorial/appendix appendix}@anchor{1fcd}@anchor{tutorial/appendix translation-repo}@anchor{1fce}@anchor{tutorial/appendix tut-appendix}@anchor{1fcf}
@section 附錄


@menu
* 互動模式: 互動模式<2>. 

@end menu

@node 互動模式<2>,,,附錄
@anchor{tutorial/appendix interactive-mode}@anchor{1fd0}@anchor{tutorial/appendix tut-interac}@anchor{48f}
@subsection 互動模式


互動式 @ref{48c,,REPL} 有兩種變體。經典的基本解釋器在所有平台上都支援，具有最低限度的行控制能力（line control capabilities）。

在 Windows 或支援 @ref{2f,,curses} 的類似 Unix 系統上，自 Python 3.13 起預設會使用新的互動式 shell。這個 shell 支援顏色、多行編輯、歷史瀏覽和貼上模式。要停用顏色，請參閱 @ref{1b7,,Controlling color} 取得詳細資訊。功能鍵提供了一些額外的功能。@code{F1} 進入互動式幫助瀏覽器 @ref{ba,,pydoc}。@code{F2} 允許瀏覽命令列歷史，既沒有輸出，也沒有 @ref{48d,,>>>} 和 @ref{48e,,...} 的提示。@code{F3} 進入 「貼上模式」，這使得貼上較大的程式碼區塊更容易。按 @code{F3} 可以返回正常提示。

使用新的互動 shell 時， 請輸入 @code{exit} 或 @code{quit} 來離開 shell。不需要在這些指令後面加上呼叫括號。

如果不需要新的互動式 shell， 可以透過 
@geindex PYTHON_BASIC_REPL
@geindex 環境變數; PYTHON_BASIC_REPL
@ref{1b6,,PYTHON_BASIC_REPL} 環境變數來停用它。

@menu
* 錯誤處理:: 
* 可執行的 Python 腳本:: 
* 互動式啟動檔案:: 
* 客製化模組:: 

@end menu

@node 錯誤處理,可執行的 Python 腳本,,互動模式<2>
@anchor{tutorial/appendix error-handling}@anchor{1fd1}@anchor{tutorial/appendix tut-error}@anchor{1fd2}
@subsubsection 錯誤處理


當一個錯誤發生時，直譯器會印出一個錯誤訊息和堆疊回溯。在互動模式下，它將返回主提示字元；當輸入來自檔案時，它在印出堆疊回溯後以非零退出狀態 (nonzero exit status) 退出。(由 @ref{1ab,,except} 子句在 @ref{8f0,,try} 陳述式中處理的例外在這種情況下不是錯誤。) 有些錯誤是無條件嚴重的，會導致非零退出狀態；這適用於內部不一致和一些記憶體耗盡的情況。所有的錯誤訊息都被寫入標準錯誤輸出；被執行指令的正常輸出被寫入標準輸出。

向主提示字元或次提示字元輸入中斷字元（通常是 @code{Control}-@code{C} 或 @code{Delete} ）會取消輸入並返回到主提示字元。@footnote{
GNU Readline 套件的一個問題可能會阻止這一點。
} 在指令執行過程中輸入一個中斷，會引發 @ref{bbc,,KeyboardInterrupt} 例外，但可以通過 @ref{8f0,,try} 陳述式來處理。

@node 可執行的 Python 腳本,互動式啟動檔案,錯誤處理,互動模式<2>
@anchor{tutorial/appendix executable-python-scripts}@anchor{1fd3}@anchor{tutorial/appendix tut-scripts}@anchor{1e9a}
@subsubsection 可執行的 Python 腳本


在類 BSD 的 Unix 系統上，Python 腳本可以直接執行，就像 shell 腳本一樣，通過放置以下這行：

@example
#!/usr/bin/env python3
@end example

（假設直譯器在用戶的 
@geindex PATH
@geindex 環境變數; PATH
@code{PATH} 上）在腳本的開頭並給檔案一個可執行模式。@code{#!} 必須是檔案的前兩個字元。在某些平台上，第一行必須以 Unix 樣式的換行 (@code{'\n'}) 結尾，而不是 Windows (@code{'\r\n'}) 換行。請注意，井號 @code{'#'} 用於在 Python 中開始註解。

可以使用 @code{chmod} 指令為腳本賦予可執行模式或權限。

@example
$ chmod +x myscript.py
@end example

在 Windows 系統上，沒有「可執行模式」的概念。Python 安裝程式會自動將 @code{.py} 檔案與 @code{python.exe} 聯繫起來，這樣雙擊 Python 檔案就會作為腳本運行。副檔名也可以是 @code{.pyw}，在這種情況下，通常會出現的控制台視窗會被隱藏。

@node 互動式啟動檔案,客製化模組,可執行的 Python 腳本,互動模式<2>
@anchor{tutorial/appendix the-interactive-startup-file}@anchor{1fd4}@anchor{tutorial/appendix tut-startup}@anchor{1fd5}
@subsubsection 互動式啟動檔案


當你互動式地使用 Python 時，每次啟動直譯器時執行一些標準指令是非常方便的。你可以通過設置一個名為 
@geindex PYTHONSTARTUP
@geindex 環境變數; PYTHONSTARTUP
@ref{1b8,,PYTHONSTARTUP} 的環境變數來實現，該變數是一個包含啟動指令的檔案名。它的功能類似 Unix shell 的 @code{.profile} 。

這個檔案只在互動模式中被讀取，當 Python 從腳本中讀取指令時，此檔案不會被讀取，當 @code{/dev/tty} 作為指令的明確來源時也不會（否則表現得像互動模式）。它在執行互動式指令的同一命名空間中執行，因此它所定義或 import 的物件可以在互動模式中不加限定地使用。你也可以在這個檔案中改變 @code{sys.ps1} 和 @code{sys.ps2} 等提示字元。

如果你想從目前目錄中讀取一個額外的啟動檔案，你可以在全域啟動檔案中使用類似 @code{if os.path.isfile('.pythonrc.py'): exec(open('.pythonrc.py').read()} 的程式碼設定這個行為。如果你想在一個腳本中使用啟動檔案，你必須在腳本中明確地這樣做：

@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 客製化模組,,互動式啟動檔案,互動模式<2>
@anchor{tutorial/appendix the-customization-modules}@anchor{1fd6}@anchor{tutorial/appendix tut-customize}@anchor{1fd7}
@subsubsection 客製化模組


Python 提供了兩個鉤子 (hook) 讓你可以將它客製化： 
@geindex sitecustomize
sitecustomize 和 
@geindex usercustomize
usercustomize 。要看它是如何運作的，你首先需要找到你的 site-packages 的位置。啟動 Python 並運行這段程式碼：

@example
>>> import site
>>> site.getusersitepackages()
'/home/user/.local/lib/python3.x/site-packages'
@end example

現在，你可以在該目錄中建立一個名為 @code{usercustomize.py} 的檔案，並將你想要的任何內容放入其中。它會影響 Python 的每次呼叫，除非它以 @ref{1586,,-s} 選項啟動以禁用自動 import 。

@geindex sitecustomize
sitecustomize 的運作方式相同，但通常是由電腦的管理員在全域 site-packages 目錄下建立，並在 
@geindex usercustomize
usercustomize 之前 import 。更多細節請參閱 @ref{cc,,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{1fd8}@anchor{using/index python-setup-and-usage}@anchor{1fd9}@anchor{using/index translation-repo}@anchor{1fda}@anchor{using/index using-index}@anchor{1fdb}
@chapter Python 的設置與使用


這部分的說明文件是關於在不同平台上設定 Python 環境的綜合資訊、直譯器的呼叫，以及讓 Python 更容易使用的一些方法。

@c ATTENTION: You probably should update Misc/python.man, too, if you modify
@c this file.

@menu
* 命令列與環境:: 
* 在 Unix 平臺上使用 Python:: 
* 配置 Python:: 
* 在 Windows 上使用 Python:: 
* 於 macOS 使用 Python:: 
* 在 Android 上使用 Python:: 
* 在 iOS 上使用 Python:: 
* 編輯器與 IDE:: 

@end menu

@node 命令列與環境,在 Unix 平臺上使用 Python,,Python 的設置與使用
@anchor{using/cmdline doc}@anchor{1fdc}@anchor{using/cmdline command-line-and-environment}@anchor{1fdd}@anchor{using/cmdline using-on-general}@anchor{1c70}
@section 命令列與環境


The CPython interpreter scans the command line and the environment for various
settings.

`CPython 實作細節：' Other implementations' command line schemes may differ.  See
@ref{1fde,,Alternate Implementations} for further resources.

@menu
* 命令列:: 
* 環境變數:: 

@end menu

@node 命令列,環境變數,,命令列與環境
@anchor{using/cmdline command-line}@anchor{1fdf}@anchor{using/cmdline using-on-cmdline}@anchor{1202}
@subsection 命令列


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
* 介面選項:: 
* Generic options:: 
* Miscellaneous options:: 
* Controlling color:: 

@end menu

@node 介面選項,Generic options,,命令列
@anchor{using/cmdline interface-options}@anchor{1fe0}@anchor{using/cmdline using-on-interface-options}@anchor{1fe1}
@subsubsection 介面選項


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{48f,,互動模式}.

@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. Leading whitespace is significant in Python statements!

@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{1465,,sys.argv} -- note that the first
element, subscript zero (@code{sys.argv[0]}), is a string reflecting the program's
source.

@geindex 命令列選項; -c
@anchor{using/cmdline cmdoption-c}@anchor{1a8}
@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{1465,,sys.argv} will be
@code{"-c"} and the current directory will be added to the start of
@ref{3e2,,sys.path} (allowing modules in that directory to be imported as top
level modules).

引發一個附帶引數 @code{command} 的@ref{1b70,,稽核事件} @code{cpython.run_command}。


在 3.14 版的變更: `command' is automatically dedented before execution.

@end deffn

@geindex 命令列選項; -m
@anchor{using/cmdline cmdoption-m}@anchor{23c}
@deffn {Option} @w{-}m <module@w{-}name>

Search @ref{3e2,,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{1465,,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{1a8,,-c} option,
the current directory will be added to the start of @ref{3e2,,sys.path}.

@ref{b4e,,-I} option can  be used to run the script in isolated mode where
@ref{3e2,,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{f5,,timeit} module:

@example
python -m timeit -s "setup here" "benchmarked code here"
python -m timeit -h # for details
@end example

引發一個附帶引數 @code{module-name} 的@ref{1b70,,稽核事件} @code{cpython.run_module}。


@subsubheading 也參考



@table @asis

@item @ref{1ac1,,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{1fe2}
@deffn {Describe} @w{-}

Read commands from standard input (@ref{758,,sys.stdin}).  If standard input is
a terminal, @ref{16cf,,-i} is implied.

If this option is given, the first element of @ref{1465,,sys.argv} will be
@code{"-"} and the current directory will be added to the start of
@ref{3e2,,sys.path}.

引發一個不附帶引數的@ref{1b70,,稽核事件} @code{cpython.run_stdin}。
@end deffn

@anchor{using/cmdline cmdarg-script}@anchor{1fe3}
@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{1465,,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{3e2,,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{3e2,,sys.path} and the @code{__main__.py} file in
that location is executed as the @ref{1,,__main__} module.

@ref{b4e,,-I} option can  be used to run the script in isolated mode where
@ref{3e2,,sys.path} contains neither the script's directory nor the user's
site-packages directory. All @code{PYTHON*} environment variables are
ignored, too.

引發一個附帶引數 @code{filename} 的@ref{1b70,,稽核事件} @code{cpython.run_file}。


@subsubheading 也參考



@table @asis

@item @ref{49f,,runpy.run_path()}

Equivalent functionality directly available to Python code
@end table

@end deffn

If no interface option is given, @ref{16cf,,-i} is implied, @code{sys.argv[0]} is
an empty string (@code{""}) and the current directory will be added to the
start of @ref{3e2,,sys.path}.  Also, tab-completion and history editing is
automatically enabled, if available on your platform (see
@ref{11c4,,Readline configuration}).


@subsubheading 也參考


@ref{1e8f,,啟動直譯器}



在 3.4 版的變更: Automatic enabling of tab-completion and history editing.


@node Generic options,Miscellaneous options,介面選項,命令列
@anchor{using/cmdline generic-options}@anchor{1fe4}@anchor{using/cmdline using-on-generic-options}@anchor{1fe5}
@subsubsection Generic options


@geindex 命令列選項; -?
@geindex 命令列選項; -h
@geindex 命令列選項; --help
@anchor{using/cmdline cmdoption-0}@anchor{161f}
@deffn {Option} @w{-}?
@anchor{using/cmdline cmdoption-h}@anchor{1fe6}
@deffnx {Option} @w{-}h
@anchor{using/cmdline cmdoption-help}@anchor{7ff}
@deffnx {Option} @w{-}@w{-}help

Print a short description of all command line options and corresponding
environment variables and exit.
@end deffn

@geindex 命令列選項; --help-env
@anchor{using/cmdline cmdoption-help-env}@anchor{801}
@deffn {Option} @w{-}@w{-}help@w{-}env

Print a short description of Python-specific environment variables
and exit.


在 3.11 版被加入.

@end deffn

@geindex 命令列選項; --help-xoptions
@anchor{using/cmdline cmdoption-help-xoptions}@anchor{802}
@deffn {Option} @w{-}@w{-}help@w{-}xoptions

Print a description of implementation-specific @ref{16f,,-X} options
and exit.


在 3.11 版被加入.

@end deffn

@geindex 命令列選項; --help-all
@anchor{using/cmdline cmdoption-help-all}@anchor{803}
@deffn {Option} @w{-}@w{-}help@w{-}all

印出完整使用資訊並離開。


在 3.11 版被加入.

@end deffn

@geindex 命令列選項; -V
@geindex 命令列選項; --version
@anchor{using/cmdline cmdoption-V}@anchor{496}
@deffn {Option} @w{-}V
@anchor{using/cmdline cmdoption-version}@anchor{f12}
@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


在 3.6 版被加入: @code{-VV} 選項

@end deffn

@node Miscellaneous options,Controlling color,Generic options,命令列
@anchor{using/cmdline miscellaneous-options}@anchor{1fe7}@anchor{using/cmdline using-on-misc-options}@anchor{1203}
@subsubsection Miscellaneous options


@geindex 命令列選項; -b
@anchor{using/cmdline cmdoption-b}@anchor{7f2}
@deffn {Option} @w{-}b

Issue a warning when converting @ref{192,,bytes} or @ref{343,,bytearray} to
@ref{169,,str} without specifying encoding or comparing @code{bytes} or
@code{bytearray} with @code{str} or @code{bytes} with @ref{19b,,int}.
Issue an error when the option is given twice (@code{-bb}).


在 3.5 版的變更: Affects also comparisons of @ref{192,,bytes} with @ref{19b,,int}.

@end deffn

@geindex 命令列選項; -B
@anchor{using/cmdline cmdoption-B}@anchor{15c4}
@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{15c5,,PYTHONDONTWRITEBYTECODE}.
@end deffn

@geindex 命令列選項; --check-hash-based-pycs
@anchor{using/cmdline cmdoption-check-hash-based-pycs}@anchor{1fe8}
@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{7fb,,Cached bytecode invalidation}. 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 命令列選項; -d
@anchor{using/cmdline cmdoption-d}@anchor{1fe9}
@deffn {Option} @w{-}d

Turn on parser debugging output (for expert only).
See also the 
@geindex PYTHONDEBUG
@geindex 環境變數; PYTHONDEBUG
@ref{1fea,,PYTHONDEBUG} environment variable.

This option requires a @ref{504,,debug build of Python}, otherwise
it's ignored.
@end deffn

@geindex 命令列選項; -E
@anchor{using/cmdline cmdoption-E}@anchor{b4d}
@deffn {Option} @w{-}E

Ignore all @code{PYTHON*} environment variables, e.g.
@geindex PYTHONPATH
@geindex 環境變數; PYTHONPATH
@ref{1218,,PYTHONPATH} and 
@geindex PYTHONHOME
@geindex 環境變數; PYTHONHOME
@ref{3ee,,PYTHONHOME}, that might be set.

另請參閱 @ref{7ba,,-P} 和 @ref{b4e,,-I} (isolated) 選項。
@end deffn

@geindex 命令列選項; -i
@anchor{using/cmdline cmdoption-i}@anchor{16cf}
@deffn {Option} @w{-}i

Enter interactive mode after execution.

Using the @ref{16cf,,-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{1a8,,-c} option is used

@item 
When the @ref{23c,,-m} option is used
@end itemize

Interactive mode will start even when @ref{758,,sys.stdin} does not appear to be a terminal. The
@geindex PYTHONSTARTUP
@geindex 環境變數; PYTHONSTARTUP
@ref{1b8,,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{16ce,,PYTHONINSPECT}.
@end deffn

@geindex 命令列選項; -I
@anchor{using/cmdline cmdoption-I}@anchor{b4e}
@deffn {Option} @w{-}I

Run Python in isolated mode. This also implies @ref{b4d,,-E}, @ref{7ba,,-P}
and @ref{1586,,-s} options.

In isolated mode @ref{3e2,,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.


在 3.4 版被加入.

@end deffn

@geindex 命令列選項; -O
@anchor{using/cmdline cmdoption-O}@anchor{18c}
@deffn {Option} @w{-}O

Remove assert statements and any code conditional on the value of
@ref{9d3,,__debug__}.  Augment the filename for compiled
(@ref{4a5,,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{1feb,,PYTHONOPTIMIZE}.


在 3.5 版的變更: 根據 
@geindex Python Enhancement Proposals; PEP 488
PEP 488@footnote{https://peps.python.org/pep-0488/} 修改 @code{.pyc} 檔案名稱。

@end deffn

@geindex 命令列選項; -OO
@anchor{using/cmdline cmdoption-OO}@anchor{fb0}
@deffn {Option} @w{-}OO

Do @ref{18c,,-O} and also discard docstrings.  Augment the filename
for compiled (@ref{4a5,,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 版的變更: 根據 
@geindex Python Enhancement Proposals; PEP 488
PEP 488@footnote{https://peps.python.org/pep-0488/} 修改 @code{.pyc} 檔案名稱。

@end deffn

@geindex 命令列選項; -P
@anchor{using/cmdline cmdoption-P}@anchor{7ba}
@deffn {Option} @w{-}P

Don't prepend a potentially unsafe path to @ref{3e2,,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{7bb,,PYTHONSAFEPATH} environment variable, and @ref{b4d,,-E}
and @ref{b4e,,-I} (isolated) options.


在 3.11 版被加入.

@end deffn

@geindex 命令列選項; -q
@anchor{using/cmdline cmdoption-q}@anchor{1fec}
@deffn {Option} @w{-}q

Don't display the copyright and version messages even in interactive mode.


在 3.2 版被加入.

@end deffn

@geindex 命令列選項; -R
@anchor{using/cmdline cmdoption-R}@anchor{1d3f}
@deffn {Option} @w{-}R

Turn on hash randomization. This option only has an effect if the
@geindex PYTHONHASHSEED
@geindex 環境變數; PYTHONHASHSEED
@ref{1278,,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{cea,,__hash__()} values of str and bytes objects
are "salted" with an unpredictable random value.  Although they remain
constant within an individual Python process, they are not predictable
between repeated invocations of Python.

Hash randomization is intended to provide protection against a
denial-of-service caused by carefully chosen inputs that exploit the worst
case performance of a dict construction, `O'(`n'@w{^2}) complexity.  See
@indicateurl{http://ocert.org/advisories/ocert-2011-003.html} for details.

@geindex PYTHONHASHSEED
@geindex 環境變數; PYTHONHASHSEED
@ref{1278,,PYTHONHASHSEED} allows you to set a fixed value for the hash
seed secret.


在 3.2.3 版被加入.



在 3.7 版的變更: The option is no longer ignored.

@end deffn

@geindex 命令列選項; -s
@anchor{using/cmdline cmdoption-s}@anchor{1586}
@deffn {Option} @w{-}s

Don't add the @ref{1fed,,user site-packages directory} to
@ref{3e2,,sys.path}.

另請參閱 
@geindex PYTHONNOUSERSITE
@geindex 環境變數; PYTHONNOUSERSITE
@ref{1587,,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 命令列選項; -S
@anchor{using/cmdline cmdoption-S}@anchor{13a9}
@deffn {Option} @w{-}S

Disable the import of the module @ref{cc,,site} and the site-dependent
manipulations of @ref{3e2,,sys.path} that it entails.  Also disable these
manipulations if @ref{cc,,site} is explicitly imported later (call
@ref{1fee,,site.main()} if you want them to be triggered).
@end deffn

@geindex 命令列選項; -u
@anchor{using/cmdline cmdoption-u}@anchor{1c56}
@deffn {Option} @w{-}u

Force the stdout and stderr streams to be unbuffered.  This option has no
effect on the stdin stream.

另請參閱 
@geindex PYTHONUNBUFFERED
@geindex 環境變數; PYTHONUNBUFFERED
@ref{1c57,,PYTHONUNBUFFERED}。


在 3.7 版的變更: The text layer of the stdout and stderr streams now is unbuffered.

@end deffn

@geindex 命令列選項; -v
@anchor{using/cmdline cmdoption-v}@anchor{161c}
@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{cc,,site} module reports the site-specific paths
and @code{.pth} files being processed.


另請參閱 
@geindex PYTHONVERBOSE
@geindex 環境變數; PYTHONVERBOSE
@ref{1fef,,PYTHONVERBOSE}。
@end deffn

@geindex 命令列選項; -W
@anchor{using/cmdline using-on-warnings}@anchor{1ff0}@anchor{using/cmdline cmdoption-W}
@deffn {Option} @w{-}W arg

Warning control. Python's warning machinery by default prints warning
messages to @ref{b2a,,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}.

完整的引數形式為：

@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 whole warning message; this match is
case-insensitive.

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.

The `lineno' field matches the line number, where zero matches all line
numbers and is thus equivalent to an omitted line number.

Multiple @ref{abc,,-W} options can be given; when a warning matches more than
one option, the action for the last matching option is performed. Invalid
@ref{abc,,-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{d9e,,PYTHONWARNINGS}
environment variable and from within a Python program using the
@ref{118,,warnings} module. For example, the @ref{169d,,warnings.filterwarnings()}
function can be used to use a regular expression on the warning message.

See @ref{1b1,,警告過濾器} and @ref{1ff1,,描述警告過濾器} for more
details.
@end deffn

@geindex 命令列選項; -x
@anchor{using/cmdline cmdoption-x}@anchor{1ff2}
@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 命令列選項; -X
@anchor{using/cmdline cmdoption-X}@anchor{16f}
@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{5c,,faulthandler}.
See also 
@geindex PYTHONFAULTHANDLER
@geindex 環境變數; PYTHONFAULTHANDLER
@ref{1280,,PYTHONFAULTHANDLER}.


在 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{504,,debug builds}.


在 3.4 版被加入.


@item 
@code{-X tracemalloc} to start tracing Python memory allocations using the
@ref{105,,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{1ff3,,tracemalloc.start()} and 
@geindex PYTHONTRACEMALLOC
@geindex 環境變數; PYTHONTRACEMALLOC
@ref{1ff4,,PYTHONTRACEMALLOC}
for more information.


在 3.4 版被加入.


@item 
@code{-X int_max_str_digits} configures the @ref{804,,integer string conversion length limitation}.  See also
@geindex PYTHONINTMAXSTRDIGITS
@geindex 環境變數; PYTHONINTMAXSTRDIGITS
@ref{1a79,,PYTHONINTMAXSTRDIGITS}.


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

另請參閱 
@geindex PYTHONPROFILEIMPORTTIME
@geindex 環境變數; PYTHONPROFILEIMPORTTIME
@ref{ce4,,PYTHONPROFILEIMPORTTIME}。


在 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{503,,Python Development Mode}, introducing
additional runtime checks that are too expensive to be enabled by
default.  See also 
@geindex PYTHONDEVMODE
@geindex 環境變數; PYTHONDEVMODE
@ref{cde,,PYTHONDEVMODE}.


在 3.7 版被加入.


@item 
@code{-X utf8} enables the @ref{85f,,Python UTF-8 Mode}.
@code{-X utf8=0} explicitly disables @ref{85f,,Python UTF-8 Mode}
(even when it would otherwise activate automatically).
See also 
@geindex PYTHONUTF8
@geindex 環境變數; PYTHONUTF8
@ref{cc6,,PYTHONUTF8}.


在 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{b92,,PYTHONPYCACHEPREFIX}.


在 3.8 版被加入.


@item 
@code{-X warn_default_encoding} issues a @ref{1ff5,,EncodingWarning} when the
locale-specific default encoding is used for opening files.
See also 
@geindex PYTHONWARNDEFAULTENCODING
@geindex 環境變數; PYTHONWARNDEFAULTENCODING
@ref{9b8,,PYTHONWARNDEFAULTENCODING}.


在 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{7cc,,PYTHONNODEBUGRANGES}.


在 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{4a8,,PYTHON_FROZEN_MODULES}.


在 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{692,,PYTHONPERFSUPPORT} and @ref{4a9,,Python 對 Linux perf 分析器的支援}.


在 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{4aa,,PYTHON_PERF_JIT_SUPPORT}
and @ref{4a9,,Python 對 Linux perf 分析器的支援}.


在 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{16e,,PYTHON_DISABLE_REMOTE_DEBUG} and 
@geindex Python Enhancement Proposals; PEP 768
PEP 768@footnote{https://peps.python.org/pep-0768/}.


在 3.14 版被加入.


@item 
@code{-X cpu_count=@var{n}} overrides @ref{4d6,,os.cpu_count()},
@ref{4d5,,os.process_cpu_count()}, and @ref{116a,,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{519,,PYTHON_CPU_COUNT}.
If `n' is @code{default}, nothing is overridden.


在 3.13 版被加入.


@item 
@code{-X presite=@var{package.module}} specifies a module that should be
imported before the @ref{cc,,site} module is executed and before the
@ref{1,,__main__} module exists.  Therefore, the imported module isn't
@ref{1,,__main__}. This can be used to execute code early during Python
initialization. Python needs to be @ref{504,,built in debug mode}
for this option to exist.  See also 
@geindex PYTHON_PRESITE
@geindex 環境變數; PYTHON_PRESITE
@ref{1ff6,,PYTHON_PRESITE}.


在 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{494,,--disable-gil}. See also 
@geindex PYTHON_GIL
@geindex 環境變數; PYTHON_GIL
@ref{495,,PYTHON_GIL} and
@ref{467,,Free-threaded CPython}.


在 3.13 版被加入.


@item 
@code{-X thread_inherit_context=@var{0,1}} causes @ref{176,,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{17e4,,PYTHON_THREAD_INHERIT_CONTEXT}.


在 3.14 版被加入.


@item 
@code{-X context_aware_warnings=@var{0,1}} causes the
@ref{179,,warnings.catch_warnings} context manager to use a
@ref{17f0,,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{17db,,PYTHON_CONTEXT_AWARE_WARNINGS}.


在 3.14 版被加入.


@item 
@code{-X tlbc=@var{0,1}} enables (1, the default) or disables (0) thread-local
bytecode in builds configured with @ref{494,,--disable-gil}.  When disabled,
this also disables the specializing interpreter.  See also
@geindex PYTHON_TLBC
@geindex 環境變數; PYTHON_TLBC
@ref{1ff7,,PYTHON_TLBC}.


在 3.14 版被加入.

@end itemize

It also allows passing arbitrary values and retrieving them through the
@ref{1ff8,,sys._xoptions} dictionary.


在 3.2 版被加入.



在 3.9 版的變更: 移除 @code{-X showalloccount} 選項。



在 3.10 版的變更: 移除 @code{-X oldparser} 選項。

@end deffn


在 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,命令列
@anchor{using/cmdline controlling-color}@anchor{1ff9}@anchor{using/cmdline using-on-controlling-color}@anchor{1b7}
@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{470,,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 環境變數,,命令列,命令列與環境
@anchor{using/cmdline environment-variables}@anchor{1ffa}@anchor{using/cmdline using-on-envvars}@anchor{800}
@subsection 環境變數


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{3ee}
@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{3ee,,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
@ref{3ee,,PYTHONHOME} to @code{`prefix':`exec_prefix'}.
@end deffn

@geindex 環境變數; PYTHONPATH
@anchor{using/cmdline envvar-PYTHONPATH}@anchor{1218}
@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{1ffb,,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{1218,,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{3ee,,PYTHONHOME} above).  It
is `always' appended to 
@geindex PYTHONPATH
@geindex 環境變數; PYTHONPATH
@ref{1218,,PYTHONPATH}.

An additional directory will be inserted in the search path in front of
@geindex PYTHONPATH
@geindex 環境變數; PYTHONPATH
@ref{1218,,PYTHONPATH} as described above under
@ref{1fe1,,介面選項}. The search path can be manipulated from
within a Python program as the variable @ref{3e2,,sys.path}.
@end deffn

@geindex 環境變數; PYTHONSAFEPATH
@anchor{using/cmdline envvar-PYTHONSAFEPATH}@anchor{7bb}
@deffn {環境變數} PYTHONSAFEPATH

If this is set to a non-empty string, don't prepend a potentially unsafe
path to @ref{3e2,,sys.path}: see the @ref{7ba,,-P} option for details.


在 3.11 版被加入.

@end deffn

@geindex 環境變數; PYTHONPLATLIBDIR
@anchor{using/cmdline envvar-PYTHONPLATLIBDIR}@anchor{1bf5}
@deffn {環境變數} PYTHONPLATLIBDIR

If this is set to a non-empty string, it overrides the @ref{b29,,sys.platlibdir}
value.


在 3.9 版被加入.

@end deffn

@geindex 環境變數; PYTHONSTARTUP
@anchor{using/cmdline envvar-PYTHONSTARTUP}@anchor{1b8}
@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{1ffc,,sys.ps1} and
@ref{1ffd,,sys.ps2} and the hook @ref{11c3,,sys.__interactivehook__} in this file.

引發一個附帶呼叫啟動時的檔案名稱為引數的@ref{1b70,,稽核事件} @code{cpython.run_startup}。
@end deffn

@geindex 環境變數; PYTHONOPTIMIZE
@anchor{using/cmdline envvar-PYTHONOPTIMIZE}@anchor{1feb}
@deffn {環境變數} PYTHONOPTIMIZE

If this is set to a non-empty string it is equivalent to specifying the
@ref{18c,,-O} option.  If set to an integer, it is equivalent to specifying
@ref{18c,,-O} multiple times.
@end deffn

@geindex 環境變數; PYTHONBREAKPOINT
@anchor{using/cmdline envvar-PYTHONBREAKPOINT}@anchor{cc9}
@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{cc8,,sys.breakpointhook()} which itself is
called by built-in @ref{271,,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 @ref{cc8,,sys.breakpointhook()}
to do nothing but return immediately.


在 3.7 版被加入.

@end deffn

@geindex 環境變數; PYTHONDEBUG
@anchor{using/cmdline envvar-PYTHONDEBUG}@anchor{1fea}
@deffn {環境變數} PYTHONDEBUG

If this is set to a non-empty string it is equivalent to specifying the
@ref{1fe9,,-d} option.  If set to an integer, it is equivalent to specifying
@ref{1fe9,,-d} multiple times.

This environment variable requires a @ref{504,,debug build of Python}, otherwise it's ignored.
@end deffn

@geindex 環境變數; PYTHONINSPECT
@anchor{using/cmdline envvar-PYTHONINSPECT}@anchor{16ce}
@deffn {環境變數} PYTHONINSPECT

If this is set to a non-empty string it is equivalent to specifying the
@ref{16cf,,-i} option.

This variable can also be modified by Python code using @ref{259,,os.environ}
to force inspect mode on program termination.

引發一個不附帶引數的@ref{1b70,,稽核事件} @code{cpython.run_stdin}。


在 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{1b8,,PYTHONSTARTUP} is
also executed. Emits audit events.

@end deffn

@geindex 環境變數; PYTHONUNBUFFERED
@anchor{using/cmdline envvar-PYTHONUNBUFFERED}@anchor{1c57}
@deffn {環境變數} PYTHONUNBUFFERED

If this is set to a non-empty string it is equivalent to specifying the
@ref{1c56,,-u} option.
@end deffn

@geindex 環境變數; PYTHONVERBOSE
@anchor{using/cmdline envvar-PYTHONVERBOSE}@anchor{1fef}
@deffn {環境變數} PYTHONVERBOSE

If this is set to a non-empty string it is equivalent to specifying the
@ref{161c,,-v} option.  If set to an integer, it is equivalent to specifying
@ref{161c,,-v} multiple times.
@end deffn

@geindex 環境變數; PYTHONCASEOK
@anchor{using/cmdline envvar-PYTHONCASEOK}@anchor{b4c}
@deffn {環境變數} PYTHONCASEOK

If this is set, Python ignores case in @ref{7f1,,import} statements.  This
only works on Windows and macOS.
@end deffn

@geindex 環境變數; PYTHONDONTWRITEBYTECODE
@anchor{using/cmdline envvar-PYTHONDONTWRITEBYTECODE}@anchor{15c5}
@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{15c4,,-B} option.
@end deffn

@geindex 環境變數; PYTHONPYCACHEPREFIX
@anchor{using/cmdline envvar-PYTHONPYCACHEPREFIX}@anchor{b92}
@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{16f,,-X}
@code{pycache_prefix=PATH} option.


在 3.8 版被加入.

@end deffn

@geindex 環境變數; PYTHONHASHSEED
@anchor{using/cmdline envvar-PYTHONHASHSEED}@anchor{1278}
@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{1278,,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.


在 3.2.3 版被加入.

@end deffn

@geindex 環境變數; PYTHONINTMAXSTRDIGITS
@anchor{using/cmdline envvar-PYTHONINTMAXSTRDIGITS}@anchor{1a79}
@deffn {環境變數} PYTHONINTMAXSTRDIGITS

If this variable is set to an integer, it is used to configure the
interpreter's global @ref{804,,integer string conversion length limitation}.


在 3.11 版被加入.

@end deffn

@geindex 環境變數; PYTHONIOENCODING
@anchor{using/cmdline envvar-PYTHONIOENCODING}@anchor{1205}
@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{ac9,,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{e50,,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{1587}
@deffn {環境變數} PYTHONNOUSERSITE

If this is set, Python won't add the @ref{1fed,,user site-packages directory} to @ref{3e2,,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{1585}
@deffn {環境變數} PYTHONUSERBASE

Defines the @ref{151d,,user base directory}, which is used to
compute the path of the @ref{1fed,,user site-packages directory}
and @ref{1ffe,,installation paths} for
@code{python -m pip install --user}.


@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{1fff}
@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{d9e}
@deffn {環境變數} PYTHONWARNINGS

This is equivalent to the @ref{abc,,-W} option. If set to a comma
separated string, it is equivalent to specifying @ref{abc,,-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{1b1,,警告過濾器} and @ref{1ff1,,描述警告過濾器} for more
details.
@end deffn

@geindex 環境變數; PYTHONFAULTHANDLER
@anchor{using/cmdline envvar-PYTHONFAULTHANDLER}@anchor{1280}
@deffn {環境變數} PYTHONFAULTHANDLER

If this environment variable is set to a non-empty string,
@ref{20f,,faulthandler.enable()} is called at startup: install a handler for
@ref{127b,,SIGSEGV}, @ref{127c,,SIGFPE},
@ref{127d,,SIGABRT}, @ref{127e,,SIGBUS} and
@ref{127f,,SIGILL} signals to dump the Python traceback.
This is equivalent to @ref{16f,,-X} @code{faulthandler} option.


在 3.3 版被加入.

@end deffn

@geindex 環境變數; PYTHONTRACEMALLOC
@anchor{using/cmdline envvar-PYTHONTRACEMALLOC}@anchor{1ff4}
@deffn {環境變數} PYTHONTRACEMALLOC

If this environment variable is set to a non-empty string, start tracing
Python memory allocations using the @ref{105,,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{1ff3,,tracemalloc.start()} function for more information.
This is equivalent to setting the @ref{16f,,-X} @code{tracemalloc} option.


在 3.4 版被加入.

@end deffn

@geindex 環境變數; PYTHONPROFILEIMPORTTIME
@anchor{using/cmdline envvar-PYTHONPROFILEIMPORTTIME}@anchor{ce4}
@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{16f,,-X} @code{importtime} option.


在 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{2000}
@deffn {環境變數} PYTHONASYNCIODEBUG

If this environment variable is set to a non-empty string, enable the
@ref{2001,,debug mode} of the @ref{b,,asyncio} module.


在 3.4 版被加入.

@end deffn

@geindex 環境變數; PYTHONMALLOC
@anchor{using/cmdline envvar-PYTHONMALLOC}@anchor{e59}
@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{2002,,default memory allocators}.

@item 
@code{malloc}: use the @code{malloc()} function of the C library
for all domains (@ref{2003,,PYMEM_DOMAIN_RAW}, @ref{e5e,,PYMEM_DOMAIN_MEM},
@ref{e5c,,PYMEM_DOMAIN_OBJ}).

@item 
@code{pymalloc}: use the @ref{f06,,pymalloc allocator} for
@ref{e5e,,PYMEM_DOMAIN_MEM} and @ref{e5c,,PYMEM_DOMAIN_OBJ} domains and use
the @code{malloc()} function for the @ref{2003,,PYMEM_DOMAIN_RAW} domain.

@item 
@code{mimalloc}: use the @ref{2004,,mimalloc allocator} for
@ref{e5e,,PYMEM_DOMAIN_MEM} and @ref{e5c,,PYMEM_DOMAIN_OBJ} domains and use
the @code{malloc()} function for the @ref{2003,,PYMEM_DOMAIN_RAW} domain.
@end itemize

Install @ref{2005,,debug hooks}:


@itemize *

@item 
@code{debug}: install debug hooks on top of the @ref{2002,,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


在 3.6 版被加入.



在 3.7 版的變更: Added the @code{"default"} allocator.

@end deffn

@geindex 環境變數; PYTHONMALLOCSTATS
@anchor{using/cmdline envvar-PYTHONMALLOCSTATS}@anchor{1dfe}
@deffn {環境變數} PYTHONMALLOCSTATS

If set to a non-empty string, Python will print statistics of the
@ref{f06,,pymalloc memory allocator} every time a new pymalloc object
arena is created, and on shutdown.

This variable is ignored if the 
@geindex PYTHONMALLOC
@geindex 環境變數; PYTHONMALLOC
@ref{e59,,PYTHONMALLOC} environment variable
is used to force the @code{malloc()} allocator of the C library, or if
Python is configured without @code{pymalloc} 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 環境變數; PYTHONLEGACYWINDOWSFSENCODING
@anchor{using/cmdline envvar-PYTHONLEGACYWINDOWSFSENCODING}@anchor{33e}
@deffn {環境變數} PYTHONLEGACYWINDOWSFSENCODING

If set to a non-empty string, the default @ref{756,,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{33d,,sys._enablelegacywindowsfsencoding()}.

@ref{2006,,可用性}: Windows.


在 3.6 版被加入: 更多細節請見 
@geindex Python Enhancement Proposals; PEP 529
PEP 529@footnote{https://peps.python.org/pep-0529/}。

@end deffn

@geindex 環境變數; PYTHONLEGACYWINDOWSSTDIO
@anchor{using/cmdline envvar-PYTHONLEGACYWINDOWSSTDIO}@anchor{e50}
@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{2006,,可用性}: Windows.


在 3.6 版被加入.

@end deffn

@geindex 環境變數; PYTHONCOERCECLOCALE
@anchor{using/cmdline envvar-PYTHONCOERCECLOCALE}@anchor{cc3}
@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{325,,locale.getdefaultlocale()}).

Configuring one of these locales (either explicitly or via the above
implicit locale coercion) automatically enables the @code{surrogateescape}
@ref{1a9e,,error handler} for @ref{758,,sys.stdin} and
@ref{cc4,,sys.stdout} (@ref{b2a,,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{1205,,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{cc6,,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{2006,,可用性}: Unix.


在 3.7 版被加入: 更多細節請見 
@geindex Python Enhancement Proposals; PEP 538
PEP 538@footnote{https://peps.python.org/pep-0538/}。

@end deffn

@geindex 環境變數; PYTHONDEVMODE
@anchor{using/cmdline envvar-PYTHONDEVMODE}@anchor{cde}
@deffn {環境變數} PYTHONDEVMODE

If this environment variable is set to a non-empty string, enable
@ref{503,,Python Development Mode}, introducing additional runtime
checks that are too expensive to be enabled by default.
This is equivalent to setting the @ref{16f,,-X} @code{dev} option.


在 3.7 版被加入.

@end deffn

@geindex 環境變數; PYTHONUTF8
@anchor{using/cmdline envvar-PYTHONUTF8}@anchor{cc6}
@deffn {環境變數} PYTHONUTF8

如果設為 @code{1}，則啟用 @ref{85f,,Python UTF-8 Mode}。

如果設為 @code{0}，則停用 @ref{85f,,Python UTF-8 Mode}。

Setting any other non-empty string causes an error during interpreter
initialisation.


在 3.7 版被加入.

@end deffn

@geindex 環境變數; PYTHONWARNDEFAULTENCODING
@anchor{using/cmdline envvar-PYTHONWARNDEFAULTENCODING}@anchor{9b8}
@deffn {環境變數} PYTHONWARNDEFAULTENCODING

If this environment variable is set to a non-empty string, issue a
@ref{1ff5,,EncodingWarning} when the locale-specific default encoding is used.

細節請見 @ref{2007,,選擇性加入的編碼警告}。


在 3.10 版被加入.

@end deffn

@geindex 環境變數; PYTHONNODEBUGRANGES
@anchor{using/cmdline envvar-PYTHONNODEBUGRANGES}@anchor{7cc}
@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.


在 3.11 版被加入.

@end deffn

@geindex 環境變數; PYTHONPERFSUPPORT
@anchor{using/cmdline envvar-PYTHONPERFSUPPORT}@anchor{692}
@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{16f,,-X perf} command-line option
and @ref{4a9,,Python 對 Linux perf 分析器的支援}.


在 3.12 版被加入.

@end deffn

@geindex 環境變數; PYTHON_PERF_JIT_SUPPORT
@anchor{using/cmdline envvar-PYTHON_PERF_JIT_SUPPORT}@anchor{4aa}
@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{16f,,-X perf_jit} command-line option
and @ref{4a9,,Python 對 Linux perf 分析器的支援}.


在 3.13 版被加入.

@end deffn

@geindex 環境變數; PYTHON_DISABLE_REMOTE_DEBUG
@anchor{using/cmdline envvar-PYTHON_DISABLE_REMOTE_DEBUG}@anchor{16e}
@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.

另請參閱 @ref{16f,,-X disable_remote_debug} 命令列選項。


在 3.14 版被加入.

@end deffn

@geindex 環境變數; PYTHON_CPU_COUNT
@anchor{using/cmdline envvar-PYTHON_CPU_COUNT}@anchor{519}
@deffn {環境變數} PYTHON_CPU_COUNT

If this variable is set to a positive integer, it overrides the return
values of @ref{4d6,,os.cpu_count()} and @ref{4d5,,os.process_cpu_count()}.

另請參閱 @ref{16f,,-X cpu_count} 命令列選項。


在 3.13 版被加入.

@end deffn

@geindex 環境變數; PYTHON_FROZEN_MODULES
@anchor{using/cmdline envvar-PYTHON_FROZEN_MODULES}@anchor{4a8}
@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}.

另請參閱 @ref{16f,,-X frozen_modules} 命令列選項。


在 3.13 版被加入.

@end deffn

@geindex 環境變數; PYTHON_COLORS
@anchor{using/cmdline envvar-PYTHON_COLORS}@anchor{470}
@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{1b7,,Controlling color}.


在 3.13 版被加入.

@end deffn

@geindex 環境變數; PYTHON_BASIC_REPL
@anchor{using/cmdline envvar-PYTHON_BASIC_REPL}@anchor{1b6}
@deffn {環境變數} PYTHON_BASIC_REPL

If this variable is set to any value, the interpreter will not attempt to
load the Python-based @ref{48c,,REPL} that requires @ref{bf,,readline}, and will
instead use the traditional parser-based @ref{48c,,REPL}.


在 3.13 版被加入.

@end deffn

@geindex 環境變數; PYTHON_HISTORY
@anchor{using/cmdline envvar-PYTHON_HISTORY}@anchor{4ab}
@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).


在 3.13 版被加入.

@end deffn

@geindex 環境變數; PYTHON_GIL
@anchor{using/cmdline envvar-PYTHON_GIL}@anchor{495}
@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{494,,--disable-gil} build option).

See also the @ref{16f,,-X gil} command-line option, which takes
precedence over this variable, and @ref{467,,Free-threaded CPython}.


在 3.13 版被加入.

@end deffn

@geindex 環境變數; PYTHON_THREAD_INHERIT_CONTEXT
@anchor{using/cmdline envvar-PYTHON_THREAD_INHERIT_CONTEXT}@anchor{17e4}
@deffn {環境變數} PYTHON_THREAD_INHERIT_CONTEXT

If this variable is set to @code{1} then @ref{176,,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{16f,,-X thread_inherit_context}.


在 3.14 版被加入.

@end deffn

@geindex 環境變數; PYTHON_CONTEXT_AWARE_WARNINGS
@anchor{using/cmdline envvar-PYTHON_CONTEXT_AWARE_WARNINGS}@anchor{17db}
@deffn {環境變數} PYTHON_CONTEXT_AWARE_WARNINGS

If set to @code{1} then the @ref{179,,warnings.catch_warnings} context
manager will use a @ref{17f0,,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{16f,,-X context_aware_warnings}.


在 3.14 版被加入.

@end deffn

@geindex 環境變數; PYTHON_JIT
@anchor{using/cmdline envvar-PYTHON_JIT}@anchor{44b}
@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.


在 3.13 版被加入.

@end deffn

@geindex 環境變數; PYTHON_TLBC
@anchor{using/cmdline envvar-PYTHON_TLBC}@anchor{1ff7}
@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{494,,--disable-gil}.

另請參閱 @ref{16f,,-X tlbc} 命令列選項。


在 3.14 版被加入.

@end deffn

@menu
* 除錯模式變數:: 

@end menu

@node 除錯模式變數,,,環境變數
@anchor{using/cmdline debug-mode-variables}@anchor{2008}
@subsubsection 除錯模式變數


@geindex 環境變數; PYTHONDUMPREFS
@anchor{using/cmdline envvar-PYTHONDUMPREFS}@anchor{b95}
@deffn {環境變數} PYTHONDUMPREFS

If set, Python will dump objects and reference counts still alive after
shutting down the interpreter.

Needs Python configured with the @ref{62e,,--with-trace-refs} build option.
@end deffn

@geindex 環境變數; PYTHONDUMPREFSFILE
@anchor{using/cmdline envvar-PYTHONDUMPREFSFILE}@anchor{1b49}
@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{62e,,--with-trace-refs} build option.


在 3.11 版被加入.

@end deffn

@geindex 環境變數; PYTHON_PRESITE
@anchor{using/cmdline envvar-PYTHON_PRESITE}@anchor{1ff6}
@deffn {環境變數} PYTHON_PRESITE

If this variable is set to a module, that module will be imported
early in the interpreter lifecycle, before the @ref{cc,,site} module is
executed, and before the @ref{1,,__main__} module is created.
Therefore, the imported module is not treated as @ref{1,,__main__}.

This can be used to execute code early during Python initialization.

To import a submodule, use @code{package.module} as the value, like in
an import statement.

See also the @ref{16f,,-X presite} command-line option,
which takes precedence over this variable.

Needs Python configured with the @ref{65e,,--with-pydebug} build option.


在 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 在 Unix 平臺上使用 Python,配置 Python,命令列與環境,Python 的設置與使用
@anchor{using/unix doc}@anchor{2009}@anchor{using/unix translation-repo}@anchor{200a}@anchor{using/unix using-on-unix}@anchor{200b}@anchor{using/unix using-python-on-unix-platforms}@anchor{200c}
@section 在 Unix 平臺上使用 Python


@menu
* 獲得並安裝 Python 的最新版本:: 
* 建置 Python:: 
* 與 Python 相關的路徑和檔案:: 
* 雜項: 雜項<2>. 
* 客製化 OpenSSL:: 

@end menu

@node 獲得並安裝 Python 的最新版本,建置 Python,,在 Unix 平臺上使用 Python
@anchor{using/unix getting-and-installing-the-latest-version-of-python}@anchor{200d}
@subsection 獲得並安裝 Python 的最新版本


@menu
* 在 Linux 上:: 
* 在 FreeBSD 和 OpenBSD 上:: 

@end menu

@node 在 Linux 上,在 FreeBSD 和 OpenBSD 上,,獲得並安裝 Python 的最新版本
@anchor{using/unix on-linux}@anchor{200e}
@subsubsection 在 Linux 上


在大多數 Linux 發行版上會預先安裝 Python，並作為一個套件提供給所有其他使用者。但是發行版提供的套件可能沒有你想要使用的某些功能，這時你可以選擇從原始碼編譯最新版本的 Python。

如果最新版的 Python 沒有預先安裝，並且不在發行版提供的儲存庫 (repository) 中，你可以輕鬆地為自己使用的發行版建立套件。參閱以下連結：


@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{200f}@anchor{using/unix installing-idle-on-linux}@anchor{2010}
@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{2011}
@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 使用者要取得 Python 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 的最新版本,在 Unix 平臺上使用 Python
@anchor{using/unix building-python}@anchor{2012}@anchor{using/unix building-python-on-unix}@anchor{10f1}
@subsection 建置 Python


如果你想自己編譯 CPython，首先要做的是取得原始碼@footnote{https://www.python.org/downloads/source/}。你可以下載最新版本的原始碼，也可以直接提取最新的 clone（克隆）@footnote{https://devguide.python.org/setup/#getting-the-source-code}。（如果你想要貢獻修補程式碼，也會需要一份 clone。）

建置過程由幾個常用命令組成：

@example
./configure
make
make install
@end example

特定 Unix 平臺的@ref{2013,,配置選項}和注意事項通常會詳細地記錄在 Python 原始碼樹 (source tree) 根目錄下的 README.rst@footnote{https://github.com/python/cpython/tree/3.14/README.rst} 檔案中。

@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 相關的路徑和檔案,雜項<2>,建置 Python,在 Unix 平臺上使用 Python
@anchor{using/unix python-related-paths-and-files}@anchor{2014}
@subsection 與 Python 相關的路徑和檔案


這取決於本地安裝慣例；@ref{2015,,prefix} 和 @ref{2016,,exec_prefix} 相依於安裝方式，應被直譯來讓 GNU 軟體使用；它們也可能相同。

例如，在大多數 Linux 系統上，兩者的預設值皆是 @code{/usr}。


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

檔案/目錄

@tab

含意

@item

@code{`exec_prefix'/bin/python3}

@tab

直譯器的推薦位置。

@item

@code{`prefix'/lib/python`version'}、@code{`exec_prefix'/lib/python`version'}

@tab

包含標準模組目錄的推薦位置。

@item

@code{`prefix'/include/python`version'}、@code{`exec_prefix'/include/python`version'}

@tab

包含開發 Python 擴充套件和嵌入直譯器所需 include 檔案之目錄的推薦位置。

@end multitable


@node 雜項<2>,客製化 OpenSSL,與 Python 相關的路徑和檔案,在 Unix 平臺上使用 Python
@anchor{using/unix miscellaneous}@anchor{2017}
@subsection 雜項


要在 Unix 上使用 Python 腳本，你需要讓他們是可執行的 (executable)，例如用

@example
$ chmod +x script
@end example

並在腳本的頂部放一個合適的 Shebang。以下通常是個好選擇：

@example
#!/usr/bin/env python3
@end example

將在整個 
@geindex PATH
@geindex 環境變數; PATH
@code{PATH} 中搜尋 Python 直譯器。然而某些 Unix 系統可能沒有 @code{env} 命令，因此你可能需要將 @code{/usr/bin/python3} 寫死 (hardcode) 成直譯器路徑。

要在 Python 腳本中使用 shell 命令，請見 @ref{dc,,subprocess} 模組。

@node 客製化 OpenSSL,,雜項<2>,在 Unix 平臺上使用 Python
@anchor{using/unix custom-openssl}@anchor{2018}@anchor{using/unix unix-custom-openssl}@anchor{2019}
@subsection 客製化 OpenSSL



@enumerate 

@item 
要使用你所選擇發行商 (vendor) 的 OpenSSL 配置和系統信任儲存區 (system trust store)，請找到包含 @code{openssl.cnf} 檔案的目錄或位於 @code{/etc} 的符號連結 (symlink)。在大多數發行版上，該檔案會是在 @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 
下載、建置並安裝 OpenSSL。請確保你使用 @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 
使用客製化 OpenSSL 建置 Python（參見配置 @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 的修補釋出版 (patch releases) 具有向後相容的 ABI。你不需要重新編譯 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 配置 Python,在 Windows 上使用 Python,在 Unix 平臺上使用 Python,Python 的設置與使用
@anchor{using/configure doc}@anchor{201a}@anchor{using/configure configure-python}@anchor{201b}@anchor{using/configure translation-repo}@anchor{201c}
@section 配置 Python


@menu
* 建置需求:: 
* 產生的檔案:: 
* 設定選項:: 
* Python 建置系統:: 
* Compiler and linker flags:: 

@end menu

@node 建置需求,產生的檔案,,配置 Python
@anchor{using/configure build-requirements}@anchor{201d}
@subsection 建置需求


建置 CPython 所需的功能與最小版本：


@itemize *

@item 
一個 C11@footnote{https://en.cppreference.com/w/c/11} 編譯器。選擇性 C11 功能@footnote{https://en.wikipedia.org/wiki/C11_(C_standard_revision)#Optional_features}並非必要。

@item 
在 Windows 上需要 Microsoft Visual Studio 2017 或更新版本。

@item 
支援 IEEE 754@footnote{https://en.wikipedia.org/wiki/IEEE_754} 浮點數與浮點數非數值 (NaN)@footnote{https://en.wikipedia.org/wiki/NaN#Floating_point}。

@item 
thread 的支援。
@end itemize

建置可選的模組：


@itemize *

@item 
libbz2@footnote{https://sourceware.org/bzip2/} for the @ref{14,,bz2} module.

@item 
libb2@footnote{https://github.com/BLAKE2/libb2} (@ref{201e,,BLAKE2}),
used by @ref{6c,,hashlib} module.

@item 
libffi@footnote{https://sourceware.org/libffi/} 3.3.0 is the recommended
minimum version for the @ref{2e,,ctypes} module.

@item 
@code{liblzma}, for the @ref{8e,,lzma} module.

@item 
libmpdec@footnote{https://www.bytereef.org/mpdecimal/doc/libmpdec/} 2.5.0
for the @ref{3a,,decimal} module.

@item 
@code{libncurses} or @code{libncursesw},
for the @ref{2f,,curses} module.

@item 
@code{libpanel} or @code{libpanelw},
for the @ref{31,,curses.panel} module.

@item 
libreadline@footnote{https://tiswww.case.edu/php/chet/readline/rltop.html} or
libedit@footnote{https://www.thrysoee.dk/editline/}
for the @ref{bf,,readline} module.

@item 
libuuid@footnote{https://linux.die.net/man/3/libuuid}, for the @ref{116,,uuid} module.

@item 
OpenSSL@footnote{https://www.openssl.org/} 1.1.1 是最低版本，OpenSSL 3.0.18 是 @ref{d5,,ssl} 與 @ref{6c,,hashlib} 擴充模組的建議最低版本。

@item 
SQLite@footnote{https://sqlite.org/} 3.15.2 for the @ref{d4,,sqlite3} extension module.

@item 
Tcl/Tk@footnote{https://www.tcl-lang.org/} 8.5.12 for the @ref{f6,,tkinter} module.

@item 
zlib@footnote{https://www.zlib.net} 1.1.4 is the reccomended minimum version for the
@ref{139,,zlib} module.

@item 
zstd@footnote{https://facebook.github.io/zstd/} 1.4.5 is the minimum version for
the @ref{23,,compression.zstd} module.
@end itemize

For a full list of dependencies required to build all modules and how to install
them, see the
devguide@footnote{https://devguide.python.org/getting-started/setup-building/#install-dependencies}.


@itemize *

@item 
Autoconf 2.72 and aclocal 1.16.5 are required to regenerate the
@code{configure} script.
@end itemize


在 3.1 版的變更: Tcl/Tk version 8.3.1 現在是必要的。



在 3.5 版的變更: 在 Windows 上，Visual Studio 2015 或更新版本與 Tcl/Tk version 8.4 現在是必要的。



在 3.6 版的變更: Selected C99 features are now required, like @code{<stdint.h>} and @code{static
inline} functions.



在 3.7 版的變更: 對執行緒與 OpenSSL 1.0.2 的支援現在是必要的。



在 3.10 版的變更: OpenSSL 1.1.1 現在是必要的。需要 SQLite 3.7.15。



在 3.11 版的變更: C11 compiler, IEEE 754 and NaN support are now required.
On Windows, Visual Studio 2017 or later is required.
Tcl/Tk version 8.5.12 is now required for the @ref{f6,,tkinter} module.



在 3.13 版的變更: Autoconf 2.71, aclocal 1.16.5 and SQLite 3.15.2 are now required.



在 3.14 版的變更: Autoconf 2.72 現在是必要的。


See also 
@geindex Python Enhancement Proposals; PEP 7
PEP 7@footnote{https://peps.python.org/pep-0007/} "Style Guide for C Code" and 
@geindex Python Enhancement Proposals; PEP 11
PEP 11@footnote{https://peps.python.org/pep-0011/} "CPython platform
support".

@node 產生的檔案,設定選項,建置需求,配置 Python
@anchor{using/configure generated-files}@anchor{201f}
@subsection 產生的檔案


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
* 設定腳本:: 

@end menu

@node 設定腳本,,,產生的檔案
@anchor{using/configure configure-script}@anchor{2020}
@subsubsection 設定腳本


The @code{make regen-configure} command regenerates the @code{aclocal.m4} file and
the @code{configure} script using the @code{Tools/build/regen-configure.sh} shell
script which uses an Ubuntu container to get the same tools versions and have a
reproducible output.

The container is optional, the following command can be run locally:

@example
autoreconf -ivf -Werror
@end example

The generated files can change depending on the exact @code{autoconf-archive},
@code{aclocal} and @code{pkg-config} versions.

@node 設定選項,Python 建置系統,產生的檔案,配置 Python
@anchor{using/configure configure-options}@anchor{2013}@anchor{using/configure id1}@anchor{2021}
@subsection 設定選項


使用以下命令列出所有 @code{configure} 腳本選項：

@example
./configure --help
@end example

請見 Python 原始碼發行版中的 @code{Misc/SpecialBuilds.txt}。

@menu
* 一般選項:: 
* C 編譯器選項。:: 
* Linker options:: 
* Options for third-party dependencies:: 
* WebAssembly 選項:: 
* 安裝選項:: 
* 效能選項:: 
* Python Debug Build:: 
* 偵錯選項:: 
* Linker options: Linker options<2>. 
* 函式庫選項:: 
* 安全性選項:: 
* macOS 選項:: 
* iOS 選項:: 
* Cross Compiling Options:: 

@end menu

@node 一般選項,C 編譯器選項。,,設定選項
@anchor{using/configure general-options}@anchor{2022}
@subsubsection 一般選項


@geindex 命令列選項; --enable-loadable-sqlite-extensions
@anchor{using/configure cmdoption-enable-loadable-sqlite-extensions}@anchor{2023}
@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{d4,,sqlite3} module.

請見 @ref{d4,,sqlite3} 模組的 @ref{a38,,sqlite3.Connection.enable_load_extension()} 方法。


在 3.6 版被加入.

@end deffn

@geindex 命令列選項; --disable-ipv6
@anchor{using/configure cmdoption-disable-ipv6}@anchor{2024}
@deffn {Option} @w{-}@w{-}disable@w{-}ipv6

停用 IPv6 支援（如果支援的話預設是啟用的），請見 @ref{d1,,socket} 模組。
@end deffn

@geindex 命令列選項; --enable-big-digits
@anchor{using/configure cmdoption-enable-big-digits}@anchor{94b}
@deffn {Option} @w{-}@w{-}enable@w{-}big@w{-}digits=[15|30]

Define the size in bits of Python @ref{19b,,int} digits: 15 or 30 bits.

By default, the digit size is 30.

將 @code{PYLONG_BITS_IN_DIGIT} 定義為 @code{15} 或 @code{30}。

參閱 @ref{1494,,sys.int_info.bits_per_digit}。
@end deffn

@geindex 命令列選項; --with-suffix
@anchor{using/configure cmdoption-with-suffix}@anchor{2025}
@deffn {Option} @w{-}@w{-}with@w{-}suffix=SUFFIX

將 Python 執行檔的後綴設定為 `SUFFIX'。

在 Windows 和 macOS 上預設的後綴是 @code{.exe} （@code{python.exe} 執行檔）、在 Emscripten node 上為 @code{.js}、在 Emscripten 瀏覽器為 @code{.html}、在 WASI 上為 @code{.wasm}，以及在其他平台為空字串（@code{python} 執行檔）。


在 3.11 版的變更: 在 WASM 平台上預設的後綴是 @code{.js}、@code{.html} 或 @code{.wasm} 中的一個。

@end deffn

@geindex 命令列選項; --with-tzpath
@anchor{using/configure cmdoption-with-tzpath}@anchor{2026}
@deffn {Option} @w{-}@w{-}with@w{-}tzpath=<list of absolute paths separated by pathsep>

Select the default time zone search path for @ref{2027,,zoneinfo.TZPATH}.
See the @ref{2028,,Compile-time configuration} of the @ref{13a,,zoneinfo} module.

預設值：@code{/usr/share/zoneinfo:/usr/lib/zoneinfo:/usr/share/lib/zoneinfo:/etc/zoneinfo}。

請見 @ref{1ffb,,os.pathsep} 路徑分隔符號。


在 3.9 版被加入.

@end deffn

@geindex 命令列選項; --without-decimal-contextvar
@anchor{using/configure cmdoption-without-decimal-contextvar}@anchor{2029}
@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{3a,,decimal} module.

請見 @ref{202a,,decimal.HAVE_CONTEXTVAR} 與 @ref{28,,contextvars} 模組。


在 3.9 版被加入.

@end deffn

@geindex 命令列選項; --with-dbmliborder
@anchor{using/configure cmdoption-with-dbmliborder}@anchor{202b}
@deffn {Option} @w{-}@w{-}with@w{-}dbmliborder=<list of backend names>

Override order to check db backends for the @ref{35,,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 命令列選項; --without-c-locale-coercion
@anchor{using/configure cmdoption-without-c-locale-coercion}@anchor{202c}
@deffn {Option} @w{-}@w{-}without@w{-}c@w{-}locale@w{-}coercion

Disable C locale coercion to a UTF-8 based locale (enabled by default).

不要定義 @code{PY_COERCE_C_LOCALE} 巨集。

請見 
@geindex PYTHONCOERCECLOCALE
@geindex 環境變數; PYTHONCOERCECLOCALE
@ref{cc3,,PYTHONCOERCECLOCALE} 與 
@geindex Python Enhancement Proposals; PEP 538
PEP 538@footnote{https://peps.python.org/pep-0538/}。
@end deffn

@geindex 命令列選項; --with-platlibdir
@anchor{using/configure cmdoption-with-platlibdir}@anchor{202d}
@deffn {Option} @w{-}@w{-}with@w{-}platlibdir=DIRNAME

Python 函式庫目錄名稱（預設為 @code{lib} ）。

Fedora 和 SuSE 在 64 位元平台上使用 @code{lib64}。

參閱 @ref{b29,,sys.platlibdir}。


在 3.9 版被加入.

@end deffn

@geindex 命令列選項; --with-wheel-pkg-dir
@anchor{using/configure cmdoption-with-wheel-pkg-dir}@anchor{a84}
@deffn {Option} @w{-}@w{-}with@w{-}wheel@w{-}pkg@w{-}dir=PATH

Directory of wheel packages used by the @ref{59,,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.


在 3.10 版被加入.

@end deffn

@geindex 命令列選項; --with-pkg-config
@anchor{using/configure cmdoption-with-pkg-config}@anchor{202e}
@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}（預設）：@code{pkg-config} 是可選的

@item 
@code{yes}：@code{pkg-config} 是必要的

@item 
@code{no}：即使存在也不使用 @code{pkg-config} 來配置
@end itemize


在 3.11 版被加入.

@end deffn

@geindex 命令列選項; --enable-pystats
@anchor{using/configure cmdoption-enable-pystats}@anchor{1a77}
@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.

效果：


@itemize *

@item 
新增 @ref{16f,,-X pystats} 命令列選項。

@item 
新增 @code{PYTHONSTATS} 環境變數。

@item 
定義 @code{Py_STATS} 巨集。

@item 
新增函式到 @ref{df,,sys} 模組。


@itemize *

@item 
@code{sys._stats_on()}：啟用統計資料收集。

@item 
@code{sys._stats_off()}：關閉統計資料收集。

@item 
@code{sys._stats_clear()}：清除統計資料。

@item 
@code{sys._stats_dump()}：將統計資料轉儲到檔案，並清除統計資料。
@end itemize
@end itemize

統計資料將被轉儲到 @code{/tmp/py_stats/} (Unix) 或 @code{C:\temp\py_stats\} (Windows) 中的任意（可能是唯一的）檔案。如果該目錄不存在，結果將被列印到 stderr。

使用 @code{Tools/scripts/summarize_stats.py} 來讀取統計資料。

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 
物件：


@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 
最佳化嘗試；

@item 
optimization traces created/executed;

@item 
uops executed.
@end itemize

@item 
垃圾回收器：


@itemize *

@item 
垃圾回收；

@item 
Objects visited;

@item 
Objects collected.
@end itemize
@end itemize


在 3.11 版被加入.

@end deffn

@geindex 命令列選項; --disable-gil
@anchor{using/configure free-threading-build}@anchor{202f}@anchor{using/configure cmdoption-disable-gil}@anchor{494}
@deffn {Option} @w{-}@w{-}disable@w{-}gil

Enables support for running Python without the @ref{46e,,global interpreter lock} (GIL): free threading build.

Defines the @code{Py_GIL_DISABLED} macro and adds @code{"t"} to
@ref{c50,,sys.abiflags}.

See @ref{467,,Free-threaded CPython} for more detail.


在 3.13 版被加入.

@end deffn

@geindex 命令列選項; --enable-experimental-jit
@anchor{using/configure cmdoption-enable-experimental-jit}@anchor{44c}
@deffn {Option} @w{-}@w{-}enable@w{-}experimental@w{-}jit=[no|yes|yes@w{-}off|interpreter]

Indicate how to integrate the @ref{159,,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{44b,,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{44b,,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{44b,,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


在 3.13 版被加入.

@end deffn

@geindex 命令列選項; PKG_CONFIG
@anchor{using/configure cmdoption-arg-PKG_CONFIG}@anchor{2030}
@deffn {Option} PKG_CONFIG

Path to @code{pkg-config} utility.
@end deffn

@geindex 命令列選項; PKG_CONFIG_LIBDIR
@anchor{using/configure cmdoption-arg-PKG_CONFIG_LIBDIR}@anchor{2031}
@deffn {Option} PKG_CONFIG_LIBDIR
@end deffn

@geindex 命令列選項; PKG_CONFIG_PATH
@anchor{using/configure cmdoption-arg-PKG_CONFIG_PATH}@anchor{2032}
@deffn {Option} PKG_CONFIG_PATH

@code{pkg-config} 選項。
@end deffn

@node C 編譯器選項。,Linker options,一般選項,設定選項
@anchor{using/configure c-compiler-options}@anchor{2033}
@subsubsection C 編譯器選項。


@geindex 命令列選項; CC
@anchor{using/configure cmdoption-arg-CC}@anchor{2034}
@deffn {Option} CC

C 編譯器指令。
@end deffn

@geindex 命令列選項; CFLAGS
@anchor{using/configure cmdoption-arg-CFLAGS}@anchor{2035}
@deffn {Option} CFLAGS

C 編譯器旗標。
@end deffn

@geindex 命令列選項; CPP
@anchor{using/configure cmdoption-arg-CPP}@anchor{2036}
@deffn {Option} CPP

C 預處理器指令。
@end deffn

@geindex 命令列選項; CPPFLAGS
@anchor{using/configure cmdoption-arg-CPPFLAGS}@anchor{2037}
@deffn {Option} CPPFLAGS

C 預處理器旗標，例如：@code{-I@var{include_dir}}。
@end deffn

@node Linker options,Options for third-party dependencies,C 編譯器選項。,設定選項
@anchor{using/configure linker-options}@anchor{2038}
@subsubsection Linker options


@geindex 命令列選項; LDFLAGS
@anchor{using/configure cmdoption-arg-LDFLAGS}@anchor{2039}
@deffn {Option} LDFLAGS

Linker flags, e.g. @code{-L@var{library_directory}}.
@end deffn

@geindex 命令列選項; LIBS
@anchor{using/configure cmdoption-arg-LIBS}@anchor{203a}
@deffn {Option} LIBS

Libraries to pass to the linker, e.g. @code{-l@var{library}}.
@end deffn

@geindex 命令列選項; MACHDEP
@anchor{using/configure cmdoption-arg-MACHDEP}@anchor{203b}
@deffn {Option} MACHDEP

Name for machine-dependent library files.
@end deffn

@node Options for third-party dependencies,WebAssembly 選項,Linker options,設定選項
@anchor{using/configure options-for-third-party-dependencies}@anchor{203c}
@subsubsection Options for third-party dependencies



在 3.11 版被加入.


@geindex 命令列選項; BZIP2_CFLAGS
@anchor{using/configure cmdoption-arg-BZIP2_CFLAGS}@anchor{203d}
@deffn {Option} BZIP2_CFLAGS
@end deffn

@geindex 命令列選項; BZIP2_LIBS
@anchor{using/configure cmdoption-arg-BZIP2_LIBS}@anchor{203e}
@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 命令列選項; CURSES_CFLAGS
@anchor{using/configure cmdoption-arg-CURSES_CFLAGS}@anchor{203f}
@deffn {Option} CURSES_CFLAGS
@end deffn

@geindex 命令列選項; CURSES_LIBS
@anchor{using/configure cmdoption-arg-CURSES_LIBS}@anchor{2040}
@deffn {Option} CURSES_LIBS

C compiler and linker flags for @code{libncurses} or @code{libncursesw}, used by
@ref{2f,,curses} module, overriding @code{pkg-config}.
@end deffn

@geindex 命令列選項; GDBM_CFLAGS
@anchor{using/configure cmdoption-arg-GDBM_CFLAGS}@anchor{2041}
@deffn {Option} GDBM_CFLAGS
@end deffn

@geindex 命令列選項; GDBM_LIBS
@anchor{using/configure cmdoption-arg-GDBM_LIBS}@anchor{2042}
@deffn {Option} GDBM_LIBS

C compiler and linker flags for @code{gdbm}.
@end deffn

@geindex 命令列選項; LIBB2_CFLAGS
@anchor{using/configure cmdoption-arg-LIBB2_CFLAGS}@anchor{2043}
@deffn {Option} LIBB2_CFLAGS
@end deffn

@geindex 命令列選項; LIBB2_LIBS
@anchor{using/configure cmdoption-arg-LIBB2_LIBS}@anchor{2044}
@deffn {Option} LIBB2_LIBS

C compiler and linker flags for @code{libb2} (@ref{201e,,BLAKE2}),
used by @ref{6c,,hashlib} module, overriding @code{pkg-config}.
@end deffn

@geindex 命令列選項; LIBEDIT_CFLAGS
@anchor{using/configure cmdoption-arg-LIBEDIT_CFLAGS}@anchor{2045}
@deffn {Option} LIBEDIT_CFLAGS
@end deffn

@geindex 命令列選項; LIBEDIT_LIBS
@anchor{using/configure cmdoption-arg-LIBEDIT_LIBS}@anchor{2046}
@deffn {Option} LIBEDIT_LIBS

C compiler and linker flags for @code{libedit}, used by @ref{bf,,readline} module,
overriding @code{pkg-config}.
@end deffn

@geindex 命令列選項; LIBFFI_CFLAGS
@anchor{using/configure cmdoption-arg-LIBFFI_CFLAGS}@anchor{2047}
@deffn {Option} LIBFFI_CFLAGS
@end deffn

@geindex 命令列選項; LIBFFI_LIBS
@anchor{using/configure cmdoption-arg-LIBFFI_LIBS}@anchor{2048}
@deffn {Option} LIBFFI_LIBS

C compiler and linker flags for @code{libffi}, used by @ref{2e,,ctypes} module,
overriding @code{pkg-config}.
@end deffn

@geindex 命令列選項; LIBMPDEC_CFLAGS
@anchor{using/configure cmdoption-arg-LIBMPDEC_CFLAGS}@anchor{2049}
@deffn {Option} LIBMPDEC_CFLAGS
@end deffn

@geindex 命令列選項; LIBMPDEC_LIBS
@anchor{using/configure cmdoption-arg-LIBMPDEC_LIBS}@anchor{204a}
@deffn {Option} LIBMPDEC_LIBS

C compiler and linker flags for @code{libmpdec}, used by @ref{3a,,decimal} module,
overriding @code{pkg-config}.

@cartouche
@quotation 備註 
These environment variables have no effect unless
@ref{64f,,--with-system-libmpdec} is specified.
@end quotation
@end cartouche
@end deffn

@geindex 命令列選項; LIBLZMA_CFLAGS
@anchor{using/configure cmdoption-arg-LIBLZMA_CFLAGS}@anchor{204b}
@deffn {Option} LIBLZMA_CFLAGS
@end deffn

@geindex 命令列選項; LIBLZMA_LIBS
@anchor{using/configure cmdoption-arg-LIBLZMA_LIBS}@anchor{204c}
@deffn {Option} LIBLZMA_LIBS

C compiler and linker flags for @code{liblzma}, used by @ref{8e,,lzma} module,
overriding @code{pkg-config}.
@end deffn

@geindex 命令列選項; LIBREADLINE_CFLAGS
@anchor{using/configure cmdoption-arg-LIBREADLINE_CFLAGS}@anchor{204d}
@deffn {Option} LIBREADLINE_CFLAGS
@end deffn

@geindex 命令列選項; LIBREADLINE_LIBS
@anchor{using/configure cmdoption-arg-LIBREADLINE_LIBS}@anchor{204e}
@deffn {Option} LIBREADLINE_LIBS

C compiler and linker flags for @code{libreadline}, used by @ref{bf,,readline}
module, overriding @code{pkg-config}.
@end deffn

@geindex 命令列選項; LIBSQLITE3_CFLAGS
@anchor{using/configure cmdoption-arg-LIBSQLITE3_CFLAGS}@anchor{204f}
@deffn {Option} LIBSQLITE3_CFLAGS
@end deffn

@geindex 命令列選項; LIBSQLITE3_LIBS
@anchor{using/configure cmdoption-arg-LIBSQLITE3_LIBS}@anchor{2050}
@deffn {Option} LIBSQLITE3_LIBS

C compiler and linker flags for @code{libsqlite3}, used by @ref{d4,,sqlite3}
module, overriding @code{pkg-config}.
@end deffn

@geindex 命令列選項; LIBUUID_CFLAGS
@anchor{using/configure cmdoption-arg-LIBUUID_CFLAGS}@anchor{2051}
@deffn {Option} LIBUUID_CFLAGS
@end deffn

@geindex 命令列選項; LIBUUID_LIBS
@anchor{using/configure cmdoption-arg-LIBUUID_LIBS}@anchor{2052}
@deffn {Option} LIBUUID_LIBS

C compiler and linker flags for @code{libuuid}, used by @ref{116,,uuid} module,
overriding @code{pkg-config}.
@end deffn

@geindex 命令列選項; LIBZSTD_CFLAGS
@anchor{using/configure cmdoption-arg-LIBZSTD_CFLAGS}@anchor{2053}
@deffn {Option} LIBZSTD_CFLAGS
@end deffn

@geindex 命令列選項; LIBZSTD_LIBS
@anchor{using/configure cmdoption-arg-LIBZSTD_LIBS}@anchor{2054}
@deffn {Option} LIBZSTD_LIBS

C compiler and linker flags for @code{libzstd}, used by @ref{23,,compression.zstd} module,
overriding @code{pkg-config}.


在 3.14 版被加入.

@end deffn

@geindex 命令列選項; PANEL_CFLAGS
@anchor{using/configure cmdoption-arg-PANEL_CFLAGS}@anchor{2055}
@deffn {Option} PANEL_CFLAGS
@end deffn

@geindex 命令列選項; PANEL_LIBS
@anchor{using/configure cmdoption-arg-PANEL_LIBS}@anchor{2056}
@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{31,,curses.panel} module, overriding @code{pkg-config}.
@end deffn

@geindex 命令列選項; TCLTK_CFLAGS
@anchor{using/configure cmdoption-arg-TCLTK_CFLAGS}@anchor{2057}
@deffn {Option} TCLTK_CFLAGS
@end deffn

@geindex 命令列選項; TCLTK_LIBS
@anchor{using/configure cmdoption-arg-TCLTK_LIBS}@anchor{2058}
@deffn {Option} TCLTK_LIBS

C compiler and linker flags for TCLTK, overriding @code{pkg-config}.
@end deffn

@geindex 命令列選項; ZLIB_CFLAGS
@anchor{using/configure cmdoption-arg-ZLIB_CFLAGS}@anchor{2059}
@deffn {Option} ZLIB_CFLAGS
@end deffn

@geindex 命令列選項; ZLIB_LIBS
@anchor{using/configure cmdoption-arg-ZLIB_LIBS}@anchor{205a}
@deffn {Option} ZLIB_LIBS

C compiler and linker flags for @code{libzlib}, used by @ref{6b,,gzip} module,
overriding @code{pkg-config}.
@end deffn

@node WebAssembly 選項,安裝選項,Options for third-party dependencies,設定選項
@anchor{using/configure webassembly-options}@anchor{205b}
@subsubsection WebAssembly 選項


@geindex 命令列選項; --enable-wasm-dynamic-linking
@anchor{using/configure cmdoption-enable-wasm-dynamic-linking}@anchor{1ae4}
@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.


在 3.11 版被加入.

@end deffn

@geindex 命令列選項; --enable-wasm-pthreads
@anchor{using/configure cmdoption-enable-wasm-pthreads}@anchor{1ab7}
@deffn {Option} @w{-}@w{-}enable@w{-}wasm@w{-}pthreads

Turn on pthreads support for WASM.


在 3.11 版被加入.

@end deffn

@node 安裝選項,效能選項,WebAssembly 選項,設定選項
@anchor{using/configure install-options}@anchor{205c}
@subsubsection 安裝選項


@geindex 命令列選項; --prefix
@anchor{using/configure cmdoption-prefix}@anchor{2015}
@deffn {Option} @w{-}@w{-}prefix=PREFIX

Install architecture-independent files in PREFIX. On Unix, it
defaults to @code{/usr/local}.

這個值可以在 runtime 使用 @ref{3e6,,sys.prefix} 取得。

As an example, one can use @code{--prefix="$HOME/.local/"} to install
a Python in its home directory.
@end deffn

@geindex 命令列選項; --exec-prefix
@anchor{using/configure cmdoption-exec-prefix}@anchor{2016}
@deffn {Option} @w{-}@w{-}exec@w{-}prefix=EPREFIX

Install architecture-dependent files in EPREFIX, defaults to @ref{2015,,--prefix}.

這個值可以在 runtime 使用 @ref{3e9,,sys.exec_prefix} 取得
@end deffn

@geindex 命令列選項; --disable-test-modules
@anchor{using/configure cmdoption-disable-test-modules}@anchor{a83}
@deffn {Option} @w{-}@w{-}disable@w{-}test@w{-}modules

Don't build nor install test modules, like the @ref{e8,,test} package or the
@code{_testcapi} extension module (built and installed by default).


在 3.10 版被加入.

@end deffn

@geindex 命令列選項; --with-ensurepip
@anchor{using/configure cmdoption-with-ensurepip}@anchor{205d}
@deffn {Option} @w{-}@w{-}with@w{-}ensurepip=[upgrade|install|no]

選擇在 Python 安裝時執行的 @ref{59,,ensurepip} 命令：


@itemize *

@item 
@code{upgrade} （預設）：執行 @code{python -m ensurepip --altinstall --upgrade} 命令。

@item 
@code{install}：執行 @code{python -m ensurepip --altinstall} 命令；

@item 
@code{no}：不要執行 ensurepip；
@end itemize


在 3.6 版被加入.

@end deffn

@node 效能選項,Python Debug Build,安裝選項,設定選項
@anchor{using/configure performance-options}@anchor{205e}
@subsubsection 效能選項


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 命令列選項; --enable-optimizations
@anchor{using/configure cmdoption-enable-optimizations}@anchor{a5b}
@deffn {Option} @w{-}@w{-}enable@w{-}optimizations

Enable Profile Guided Optimization (PGO) using 
@geindex PROFILE_TASK
@geindex 環境變數; PROFILE_TASK
@ref{19d0,,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{16ab,,CFLAGS}.
@end quotation
@end cartouche


在 3.6 版被加入.



在 3.10 版的變更: 在 GCC 上使用 @code{-fno-semantic-interposition}。

@end deffn

@geindex 環境變數; PROFILE_TASK
@anchor{using/configure envvar-PROFILE_TASK}@anchor{19d0}
@deffn {環境變數} PROFILE_TASK

Environment variable used in the Makefile: Python command line arguments for
the PGO generation task.

預設值：@code{-m test --pgo --timeout=$(TESTTIMEOUT)}。


在 3.8 版被加入.



在 3.13 版的變更: Task failure is no longer ignored silently.

@end deffn

@geindex 命令列選項; --with-lto
@anchor{using/configure cmdoption-with-lto}@anchor{94a}
@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}).


在 3.6 版被加入.



在 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 命令列選項; --enable-bolt
@anchor{using/configure cmdoption-enable-bolt}@anchor{205f}
@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.


在 3.12 版被加入.

@end deffn

@geindex 命令列選項; BOLT_APPLY_FLAGS
@anchor{using/configure cmdoption-arg-BOLT_APPLY_FLAGS}@anchor{2060}
@deffn {Option} BOLT_APPLY_FLAGS

Arguments to @code{llvm-bolt} when creating a BOLT optimized binary@footnote{https://github.com/facebookarchive/BOLT}.


在 3.12 版被加入.

@end deffn

@geindex 命令列選項; BOLT_INSTRUMENT_FLAGS
@anchor{using/configure cmdoption-arg-BOLT_INSTRUMENT_FLAGS}@anchor{2061}
@deffn {Option} BOLT_INSTRUMENT_FLAGS

Arguments to @code{llvm-bolt} when instrumenting binaries.


在 3.12 版被加入.

@end deffn

@geindex 命令列選項; --with-computed-gotos
@anchor{using/configure cmdoption-with-computed-gotos}@anchor{2062}
@deffn {Option} @w{-}@w{-}with@w{-}computed@w{-}gotos

Enable computed gotos in evaluation loop (enabled by default on supported
compilers).
@end deffn

@geindex 命令列選項; --with-tail-call-interp
@anchor{using/configure cmdoption-with-tail-call-interp}@anchor{172}
@deffn {Option} @w{-}@w{-}with@w{-}tail@w{-}call@w{-}interp

Enable interpreters using tail calls in CPython. If enabled, enabling PGO
(@ref{a5b,,--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.


在 3.14 版被加入.

@end deffn

@geindex 命令列選項; --without-mimalloc
@anchor{using/configure cmdoption-without-mimalloc}@anchor{2063}
@deffn {Option} @w{-}@w{-}without@w{-}mimalloc

Disable the fast @ref{2004,,mimalloc} allocator
(enabled by default).

另請參閱 
@geindex PYTHONMALLOC
@geindex 環境變數; PYTHONMALLOC
@ref{e59,,PYTHONMALLOC} 環境變數。
@end deffn

@geindex 命令列選項; --without-pymalloc
@anchor{using/configure cmdoption-without-pymalloc}@anchor{2064}
@deffn {Option} @w{-}@w{-}without@w{-}pymalloc

Disable the specialized Python memory allocator @ref{f06,,pymalloc}
(enabled by default).

另請參閱 
@geindex PYTHONMALLOC
@geindex 環境變數; PYTHONMALLOC
@ref{e59,,PYTHONMALLOC} 環境變數。
@end deffn

@geindex 命令列選項; --without-doc-strings
@anchor{using/configure cmdoption-without-doc-strings}@anchor{2065}
@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.

不要定義 @code{WITH_DOC_STRINGS} 巨集。

請見 @code{PyDoc_STRVAR()} 巨集。
@end deffn

@geindex 命令列選項; --enable-profiling
@anchor{using/configure cmdoption-enable-profiling}@anchor{2066}
@deffn {Option} @w{-}@w{-}enable@w{-}profiling

Enable C-level code profiling with @code{gprof} (disabled by default).
@end deffn

@geindex 命令列選項; --with-strict-overflow
@anchor{using/configure cmdoption-with-strict-overflow}@anchor{1a1e}
@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 命令列選項; --without-remote-debug
@anchor{using/configure cmdoption-without-remote-debug}@anchor{170}
@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{2067}
@deffn {C 巨集} Py_REMOTE_DEBUG

This macro is defined by default, unless Python is configured with
@ref{170,,--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


在 3.14 版被加入.

@end deffn

@node Python Debug Build,偵錯選項,效能選項,設定選項
@anchor{using/configure debug-build}@anchor{504}@anchor{using/configure python-debug-build}@anchor{2068}
@subsubsection Python Debug Build


A debug build is Python built with the @ref{65e,,--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{118,,warnings} module.

@item 
新增 @code{d} 到 @ref{c50,,sys.abiflags}。

@item 
新增 @code{sys.gettotalrefcount()} 函式。

@item 
新增 @ref{16f,,-X showrefcount} 命令列選項。

@item 
Add @ref{1fe9,,-d} command line option and 
@geindex PYTHONDEBUG
@geindex 環境變數; PYTHONDEBUG
@ref{1fea,,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{2002,,debug hooks on memory allocators}
to detect buffer overflow and other memory errors.

@item 
定義 @code{Py_DEBUG} 和 @code{Py_REF_DEBUG} 巨集。

@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{625,,--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{1b3,,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{503,,Python Development Mode} and the
@ref{62e,,--with-trace-refs} configure option.


在 3.8 版的變更: Release builds and debug builds are now ABI compatible: defining the
@code{Py_DEBUG} macro no longer implies the @code{Py_TRACE_REFS} macro (see the
@ref{62e,,--with-trace-refs} option).


@node 偵錯選項,Linker options<2>,Python Debug Build,設定選項
@anchor{using/configure debug-options}@anchor{2069}
@subsubsection 偵錯選項


@geindex 命令列選項; --with-pydebug
@anchor{using/configure cmdoption-with-pydebug}@anchor{65e}
@deffn {Option} @w{-}@w{-}with@w{-}pydebug

@ref{504,,以偵錯模式建置 Python}：定義 @code{Py_DEBUG} 巨集（預設不啟用）。
@end deffn

@geindex 命令列選項; --with-trace-refs
@anchor{using/configure cmdoption-with-trace-refs}@anchor{62e}
@deffn {Option} @w{-}@w{-}with@w{-}trace@w{-}refs

以偵錯為目的啟用參照追蹤（預設不啟用）。

效果：


@itemize *

@item 
定義 @code{Py_TRACE_REFS} 巨集。

@item 
新增 @ref{28e,,sys.getobjects()} 函式。

@item 
新增 
@geindex PYTHONDUMPREFS
@geindex 環境變數; PYTHONDUMPREFS
@ref{b95,,PYTHONDUMPREFS} 環境變數。
@end itemize

@geindex PYTHONDUMPREFS
@geindex 環境變數; PYTHONDUMPREFS
@ref{b95,,PYTHONDUMPREFS} 環境變數可以用來在 Python 結束時轉儲仍然有效的物件和參照計數。

不追蹤@ref{97b,,靜態配置的物件}。


在 3.8 版被加入.



在 3.13 版的變更: 這個建置現在與發佈版本建置和@ref{504,,偵錯建置}具有 ABI 相容性。

@end deffn

@geindex 命令列選項; --with-assertions
@anchor{using/configure cmdoption-with-assertions}@anchor{625}
@deffn {Option} @w{-}@w{-}with@w{-}assertions

啟用 C 斷言建置（預設不啟用）：@code{assert(...);} 和 @code{_PyObject_ASSERT(...);}。

如果設定，@code{NDEBUG} 巨集不會在 
@geindex OPT
@geindex 環境變數; OPT
@ref{206a,,OPT} 編譯器變數中定義。

另請參閱 @ref{65e,,--with-pydebug} 選項（@ref{504,,debug build}），它也啟用了斷言。


在 3.6 版被加入.

@end deffn

@geindex 命令列選項; --with-valgrind
@anchor{using/configure cmdoption-with-valgrind}@anchor{206b}
@deffn {Option} @w{-}@w{-}with@w{-}valgrind

啟用 Valgrind 支援（預設不啟用）。
@end deffn

@geindex 命令列選項; --with-dtrace
@anchor{using/configure cmdoption-with-dtrace}@anchor{206c}
@deffn {Option} @w{-}@w{-}with@w{-}dtrace

啟用 DTrace 支援（預設不啟用）。

請參閱@ref{e61,,使用 DTrace 和 SystemTap 檢測 CPython}。


在 3.6 版被加入.

@end deffn

@geindex 命令列選項; --with-address-sanitizer
@anchor{using/configure cmdoption-with-address-sanitizer}@anchor{206d}
@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{2064,,--without-pymalloc} to disable the specialized small-object
allocator whose allocations are not tracked by ASan.


在 3.6 版被加入.

@end deffn

@geindex 命令列選項; --with-memory-sanitizer
@anchor{using/configure cmdoption-with-memory-sanitizer}@anchor{206e}
@deffn {Option} @w{-}@w{-}with@w{-}memory@w{-}sanitizer

啟用 MemorySanitizer 分配錯誤偵測器 @code{msan}（預設不啟用）。


在 3.6 版被加入.

@end deffn

@geindex 命令列選項; --with-undefined-behavior-sanitizer
@anchor{using/configure cmdoption-with-undefined-behavior-sanitizer}@anchor{206f}
@deffn {Option} @w{-}@w{-}with@w{-}undefined@w{-}behavior@w{-}sanitizer

啟用 UndefinedBehaviorSanitizer 未定義行為偵測器 @code{ubsan}（預設不啟用）。


在 3.6 版被加入.

@end deffn

@geindex 命令列選項; --with-thread-sanitizer
@anchor{using/configure cmdoption-with-thread-sanitizer}@anchor{2070}
@deffn {Option} @w{-}@w{-}with@w{-}thread@w{-}sanitizer

啟用 ThreadSanitizer 資料競爭偵測器 @code{tsan}（預設不啟用）。


在 3.13 版被加入.

@end deffn

@node Linker options<2>,函式庫選項,偵錯選項,設定選項
@anchor{using/configure id2}@anchor{2071}
@subsubsection Linker options


@geindex 命令列選項; --enable-shared
@anchor{using/configure cmdoption-enable-shared}@anchor{a5c}
@deffn {Option} @w{-}@w{-}enable@w{-}shared

啟用建置共享 Python 函式庫：@code{libpython}（預設不啟用）。
@end deffn

@geindex 命令列選項; --without-static-libpython
@anchor{using/configure cmdoption-without-static-libpython}@anchor{a85}
@deffn {Option} @w{-}@w{-}without@w{-}static@w{-}libpython

不要建置 @code{libpythonMAJOR.MINOR.a} 並且不要安裝 @code{python.o}（預設會建置並啟用）。


在 3.10 版被加入.

@end deffn

@node 函式庫選項,安全性選項,Linker options<2>,設定選項
@anchor{using/configure libraries-options}@anchor{2072}
@subsubsection 函式庫選項


@geindex 命令列選項; --with-libs
@anchor{using/configure cmdoption-with-libs}@anchor{2073}
@deffn {Option} @w{-}@w{-}with@w{-}libs='lib1 ...'

Link against additional libraries (default is no).
@end deffn

@geindex 命令列選項; --with-system-expat
@anchor{using/configure cmdoption-with-system-expat}@anchor{1a6e}
@deffn {Option} @w{-}@w{-}with@w{-}system@w{-}expat

使用已安裝的 @code{expat} 函式庫建置 @code{pyexpat} 模組（預設不建置）。
@end deffn

@geindex 命令列選項; --with-system-libmpdec
@anchor{using/configure cmdoption-with-system-libmpdec}@anchor{64f}
@deffn {Option} @w{-}@w{-}with@w{-}system@w{-}libmpdec

使用已安裝的 @code{mpdecimal} 函式庫建置 @code{_decimal} 擴充模組，請參閱 @ref{3a,,decimal} 模組（預設建置）。


在 3.3 版被加入.



在 3.13 版的變更: 預設使用已安裝的 @code{mpdecimal} 函式庫。



Deprecated since version 3.13, will be removed in version 3.16: Python 3.16 不再隨附 @code{mpdecimal} 函式庫的原始碼副本。



@subsubheading 也參考


@ref{2049,,LIBMPDEC_CFLAGS} 和 @ref{204a,,LIBMPDEC_LIBS}。

@end deffn

@geindex 命令列選項; --with-readline
@anchor{using/configure cmdoption-with-readline}@anchor{2074}
@deffn {Option} @w{-}@w{-}with@w{-}readline=readline|editline

Designate a backend library for the @ref{bf,,readline} module.


@itemize *

@item 
readline: Use readline as the backend.

@item 
editline: Use editline as the backend.
@end itemize


在 3.10 版被加入.

@end deffn

@geindex 命令列選項; --without-readline
@anchor{using/configure cmdoption-without-readline}@anchor{2075}
@deffn {Option} @w{-}@w{-}without@w{-}readline

不要建置 @ref{bf,,readline} 模組（預設會建置）。

不要定義 @code{HAVE_LIBREADLINE} 巨集。


在 3.10 版被加入.

@end deffn

@geindex 命令列選項; --with-libm
@anchor{using/configure cmdoption-with-libm}@anchor{2076}
@deffn {Option} @w{-}@w{-}with@w{-}libm=STRING

Override @code{libm} math library to `STRING' (default is system-dependent).
@end deffn

@geindex 命令列選項; --with-libc
@anchor{using/configure cmdoption-with-libc}@anchor{2077}
@deffn {Option} @w{-}@w{-}with@w{-}libc=STRING

Override @code{libc} C library to `STRING' (default is system-dependent).
@end deffn

@geindex 命令列選項; --with-openssl
@anchor{using/configure cmdoption-with-openssl}@anchor{2078}
@deffn {Option} @w{-}@w{-}with@w{-}openssl=DIR

OpenSSL 目錄的根目錄。


在 3.7 版被加入.

@end deffn

@geindex 命令列選項; --with-openssl-rpath
@anchor{using/configure cmdoption-with-openssl-rpath}@anchor{a86}
@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{2078,,--with-openssl} and
@code{pkg-config};

@item 
`DIR': set an explicit rpath.
@end itemize


在 3.10 版被加入.

@end deffn

@node 安全性選項,macOS 選項,函式庫選項,設定選項
@anchor{using/configure security-options}@anchor{2079}
@subsubsection 安全性選項


@geindex 命令列選項; --with-hash-algorithm
@anchor{using/configure cmdoption-with-hash-algorithm}@anchor{207a}
@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}（預設）；

@item 
@code{siphash24}；

@item 
@code{fnv}。
@end itemize


在 3.4 版被加入.



在 3.11 版被加入: @code{siphash13} is added and it is the new default.

@end deffn

@geindex 命令列選項; --with-builtin-hashlib-hashes
@anchor{using/configure cmdoption-with-builtin-hashlib-hashes}@anchor{207b}
@deffn {Option} @w{-}@w{-}with@w{-}builtin@w{-}hashlib@w{-}hashes=md5,sha1,sha256,sha512,sha3,blake2

內建雜湊模組：


@itemize *

@item 
@code{md5}；

@item 
@code{sha1}；

@item 
@code{sha256}；

@item 
@code{sha512}；

@item 
@code{sha3} (with shake);

@item 
@code{blake2}。
@end itemize


在 3.9 版被加入.

@end deffn

@geindex 命令列選項; --with-ssl-default-suites
@anchor{using/configure cmdoption-with-ssl-default-suites}@anchor{207c}
@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

請見 @ref{d5,,ssl} 模組。


在 3.7 版被加入.



在 3.10 版的變更: The settings @code{python} and `STRING' also set TLS 1.2 as minimum
protocol version.

@end deffn

@geindex 命令列選項; --disable-safety
@anchor{using/configure cmdoption-disable-safety}@anchor{443}
@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


在 3.14 版被加入.

@end deffn

@geindex 命令列選項; --enable-slower-safety
@anchor{using/configure cmdoption-enable-slower-safety}@anchor{444}
@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


在 3.14 版被加入.

@end deffn

@node macOS 選項,iOS 選項,安全性選項,設定選項
@anchor{using/configure macos-options}@anchor{207d}
@subsubsection macOS 選項


參閱 Mac/README.rst@footnote{https://github.com/python/cpython/tree/3.14/Mac/README.rst}。

@geindex 命令列選項; --enable-universalsdk
@anchor{using/configure cmdoption-enable-universalsdk}@anchor{b5a}
@deffn {Option} @w{-}@w{-}enable@w{-}universalsdk
@end deffn

@geindex 命令列選項; --enable-universalsdk
@anchor{using/configure cmdoption-0}@anchor{207e}
@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 命令列選項; --enable-framework
@anchor{using/configure cmdoption-enable-framework}@anchor{207f}
@deffn {Option} @w{-}@w{-}enable@w{-}framework
@end deffn

@geindex 命令列選項; --enable-framework
@anchor{using/configure cmdoption-1}@anchor{2080}
@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 命令列選項; --with-universal-archs
@anchor{using/configure cmdoption-with-universal-archs}@anchor{2081}
@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{b5a,,--enable-universalsdk} is set.

選項：


@itemize *

@item 
@code{universal2}（x86-64 與 arm64）；

@item 
@code{32-bit}（PPC 與 i386）；

@item 
@code{64-bit}（PPC64 與 x86-64）；

@item 
@code{3-way}（i386、PPC 與 x86-64）；

@item 
@code{intel}（i386 與 x86-64）；

@item 
@code{intel-32}（i386）；

@item 
@code{intel-64}（x86-64）；

@item 
@code{all}（PPC、i386、PPC64 與 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 命令列選項; --with-framework-name
@anchor{using/configure cmdoption-with-framework-name}@anchor{2082}
@deffn {Option} @w{-}@w{-}with@w{-}framework@w{-}name=FRAMEWORK

Specify the name for the python framework on macOS only valid when
@ref{207f,,--enable-framework} is set (default: @code{Python}).
@end deffn

@geindex 命令列選項; --with-app-store-compliance
@anchor{using/configure cmdoption-with-app-store-compliance}@anchor{18f0}
@deffn {Option} @w{-}@w{-}with@w{-}app@w{-}store@w{-}compliance
@end deffn

@geindex 命令列選項; --with-app-store-compliance
@anchor{using/configure cmdoption-2}@anchor{2083}
@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.


在 3.13 版被加入.

@end deffn

@node iOS 選項,Cross Compiling Options,macOS 選項,設定選項
@anchor{using/configure ios-options}@anchor{2084}
@subsubsection iOS 選項


參閱 iOS/README.rst@footnote{https://github.com/python/cpython/tree/3.14/iOS/README.rst}。

@geindex 命令列選項; --enable-framework
@anchor{using/configure cmdoption-3}@anchor{2085}
@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 命令列選項; --with-framework-name
@anchor{using/configure cmdoption-4}@anchor{2086}
@deffn {Option} @w{-}@w{-}with@w{-}framework@w{-}name=FRAMEWORK

指定框架的名稱（預設值：@code{Python}）。
@end deffn

@node Cross Compiling Options,,iOS 選項,設定選項
@anchor{using/configure cross-compiling-options}@anchor{2087}
@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 命令列選項; --build
@anchor{using/configure cmdoption-build}@anchor{2088}
@deffn {Option} @w{-}@w{-}build=BUILD

configure for building on BUILD, usually guessed by @code{config.guess}.
@end deffn

@geindex 命令列選項; --host
@anchor{using/configure cmdoption-host}@anchor{2089}
@deffn {Option} @w{-}@w{-}host=HOST

cross-compile to build programs to run on HOST (target platform)
@end deffn

@geindex 命令列選項; --with-build-python
@anchor{using/configure cmdoption-with-build-python}@anchor{208a}
@deffn {Option} @w{-}@w{-}with@w{-}build@w{-}python=path/to/python

path to build @code{python} binary for cross compiling


在 3.11 版被加入.

@end deffn

@geindex 命令列選項; CONFIG_SITE
@anchor{using/configure cmdoption-arg-CONFIG_SITE}@anchor{208b}
@deffn {Option} CONFIG_SITE=file

An environment variable that points to a file with configure overrides.

範例 `config.site' 檔案：

@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 命令列選項; HOSTRUNNER
@anchor{using/configure cmdoption-arg-HOSTRUNNER}@anchor{208c}
@deffn {Option} HOSTRUNNER

Program to run CPython for the host platform for cross-compilation.


在 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 建置系統,Compiler and linker flags,設定選項,配置 Python
@anchor{using/configure python-build-system}@anchor{208d}
@subsection Python 建置系統


@menu
* 建置系統的主要檔案:: 
* 主要建置步驟:: 
* 主要 Makefile 目標:: 
* C 擴充模組:: 

@end menu

@node 建置系統的主要檔案,主要建置步驟,,Python 建置系統
@anchor{using/configure main-files-of-the-build-system}@anchor{208e}
@subsubsection 建置系統的主要檔案



@itemize *

@item 
@code{configure.ac} => @code{configure}；

@item 
@code{Makefile.pre.in} => @code{Makefile}（由 @code{configure} 建立）；

@item 
@code{pyconfig.h}（由 @code{configure} 建立）；

@item 
@code{Modules/Setup}: C extensions built by the Makefile using
@code{Module/makesetup} shell script;
@end itemize

@node 主要建置步驟,主要 Makefile 目標,建置系統的主要檔案,Python 建置系統
@anchor{using/configure main-build-steps}@anchor{208f}
@subsubsection 主要建置步驟



@itemize *

@item 
C 檔案（@code{.c}）被建置為目的檔（@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 主要 Makefile 目標,C 擴充模組,主要建置步驟,Python 建置系統
@anchor{using/configure main-makefile-targets}@anchor{2090}
@subsubsection 主要 Makefile 目標


@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,,主要 Makefile 目標
@anchor{using/configure make}@anchor{2091}
@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}（使用 @code{--enable-optimizations} 配置）

@item 
@code{build_wasm} (chosen if the host platform matches @code{wasm32-wasi*} or
@code{wasm32-emscripten})

@item 
@code{build_all}（未明確使用其他選項進行配置）
@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,主要 Makefile 目標
@anchor{using/configure make-platform}@anchor{2092}
@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,主要 Makefile 目標
@anchor{using/configure make-profile-opt}@anchor{2093}
@subsubsection make profile-opt


Build Python using profile-guided optimization (PGO).  You can use the
configure @ref{a5b,,--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,主要 Makefile 目標
@anchor{using/configure make-clean}@anchor{2094}
@subsubsection make clean


移除建置的檔案。

@node make distclean,make install,make clean,主要 Makefile 目標
@anchor{using/configure make-distclean}@anchor{2095}
@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,主要 Makefile 目標
@anchor{using/configure make-install}@anchor{2096}
@subsubsection make install


建置 @code{all} 目標並安裝 Python。

@node make test,make ci,make install,主要 Makefile 目標
@anchor{using/configure make-test}@anchor{2097}
@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}：額外的 regrtest 命令列選項。

@item 
@code{TESTPYTHONOPTS}：額外的 Python 命令列選項。

@item 
@code{TESTTIMEOUT}：秒數表示的超時設定（預設值：10 分鐘）。
@end itemize

@node make ci,make buildbottest,make test,主要 Makefile 目標
@anchor{using/configure make-ci}@anchor{2098}
@subsubsection make ci


This is similar to @code{make test}, but uses the @code{-ugui} to also run GUI tests.


在 3.14 版被加入.


@node make buildbottest,make regen-all,make ci,主要 Makefile 目標
@anchor{using/configure make-buildbottest}@anchor{2099}
@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,主要 Makefile 目標
@anchor{using/configure make-regen-all}@anchor{209a}
@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{201f,,generated files}.

@node C 擴充模組,,主要 Makefile 目標,Python 建置系統
@anchor{using/configure c-extensions}@anchor{209b}
@subsubsection C 擴充模組


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{16c7,,PyMODINIT_FUNC} macros of @code{Include/exports.h} are defined
differently depending if the @code{Py_BUILD_CORE_MODULE} macro is defined:


@itemize *

@item 
如果定義了 @code{Py_BUILD_CORE_MODULE}，則使用 @code{Py_EXPORTED_SYMBOL}

@item 
否則使用 @code{Py_IMPORTED_SYMBOL}。
@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{653,,ImportError} on import.

@node Compiler and linker flags,,Python 建置系統,配置 Python
@anchor{using/configure compiler-and-linker-flags}@anchor{209c}
@subsection Compiler and linker flags


Options set by the @code{./configure} script and environment variables and used by
@code{Makefile}.

@menu
* 預處理器旗標:: 
* 編譯器旗標:: 
* Linker flags:: 

@end menu

@node 預處理器旗標,編譯器旗標,,Compiler and linker flags
@anchor{using/configure preprocessor-flags}@anchor{209d}
@subsubsection 預處理器旗標


@geindex 環境變數; CONFIGURE_CPPFLAGS
@anchor{using/configure envvar-CONFIGURE_CPPFLAGS}@anchor{209e}
@deffn {環境變數} CONFIGURE_CPPFLAGS

Value of 
@geindex CPPFLAGS
@geindex 環境變數; CPPFLAGS
@ref{16ad,,CPPFLAGS} variable passed to the @code{./configure} script.


在 3.6 版被加入.

@end deffn

@geindex 環境變數; CPPFLAGS
@anchor{using/configure envvar-CPPFLAGS}@anchor{16ad}
@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{16ad,,CPPFLAGS} and 
@geindex LDFLAGS
@geindex 環境變數; LDFLAGS
@ref{16ac,,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{209f}
@deffn {環境變數} BASECPPFLAGS


在 3.4 版被加入.

@end deffn

@geindex 環境變數; PY_CPPFLAGS
@anchor{using/configure envvar-PY_CPPFLAGS}@anchor{20a0}
@deffn {環境變數} PY_CPPFLAGS

Extra preprocessor flags added for building the interpreter object files.

Default: @code{$(BASECPPFLAGS) -I. -I$(srcdir)/Include $(CONFIGURE_CPPFLAGS) $(CPPFLAGS)}.


在 3.2 版被加入.

@end deffn

@node 編譯器旗標,Linker flags,預處理器旗標,Compiler and linker flags
@anchor{using/configure compiler-flags}@anchor{20a1}
@subsubsection 編譯器旗標


@geindex 環境變數; CC
@anchor{using/configure envvar-CC}@anchor{16aa}
@deffn {環境變數} CC

C 編譯器指令。

範例：@code{gcc -pthread}。
@end deffn

@geindex 環境變數; CXX
@anchor{using/configure envvar-CXX}@anchor{20a2}
@deffn {環境變數} CXX

C++ 編譯器指令。

範例：@code{g++ -pthread}。
@end deffn

@geindex 環境變數; CFLAGS
@anchor{using/configure envvar-CFLAGS}@anchor{16ab}
@deffn {環境變數} CFLAGS

C 編譯器旗標。
@end deffn

@geindex 環境變數; CFLAGS_NODIST
@anchor{using/configure envvar-CFLAGS_NODIST}@anchor{20a3}
@deffn {環境變數} CFLAGS_NODIST

@geindex CFLAGS_NODIST
@geindex 環境變數; CFLAGS_NODIST
@ref{20a3,,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{16ab,,CFLAGS} once Python is installed (gh-65320@footnote{https://github.com/python/cpython/issues/65320}).

In particular, 
@geindex CFLAGS
@geindex 環境變數; CFLAGS
@ref{16ab,,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{16ab,,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


在 3.5 版被加入.

@end deffn

@geindex 環境變數; COMPILEALL_OPTS
@anchor{using/configure envvar-COMPILEALL_OPTS}@anchor{20a4}
@deffn {環境變數} COMPILEALL_OPTS

Options passed to the @ref{21,,compileall} command line when building PYC files
in @code{make install}. Default: @code{-j0}.


在 3.12 版被加入.

@end deffn

@geindex 環境變數; EXTRA_CFLAGS
@anchor{using/configure envvar-EXTRA_CFLAGS}@anchor{20a5}
@deffn {環境變數} EXTRA_CFLAGS

額外的 C 編譯器旗標。
@end deffn

@geindex 環境變數; CONFIGURE_CFLAGS
@anchor{using/configure envvar-CONFIGURE_CFLAGS}@anchor{20a6}
@deffn {環境變數} CONFIGURE_CFLAGS

Value of 
@geindex CFLAGS
@geindex 環境變數; CFLAGS
@ref{16ab,,CFLAGS} variable passed to the @code{./configure}
script.


在 3.2 版被加入.

@end deffn

@geindex 環境變數; CONFIGURE_CFLAGS_NODIST
@anchor{using/configure envvar-CONFIGURE_CFLAGS_NODIST}@anchor{20a7}
@deffn {環境變數} CONFIGURE_CFLAGS_NODIST

Value of 
@geindex CFLAGS_NODIST
@geindex 環境變數; CFLAGS_NODIST
@ref{20a3,,CFLAGS_NODIST} variable passed to the @code{./configure}
script.


在 3.5 版被加入.

@end deffn

@geindex 環境變數; BASECFLAGS
@anchor{using/configure envvar-BASECFLAGS}@anchor{20a8}
@deffn {環境變數} BASECFLAGS

基本編譯器旗標。
@end deffn

@geindex 環境變數; OPT
@anchor{using/configure envvar-OPT}@anchor{206a}
@deffn {環境變數} OPT

最佳化旗標。
@end deffn

@geindex 環境變數; CFLAGS_ALIASING
@anchor{using/configure envvar-CFLAGS_ALIASING}@anchor{20a9}
@deffn {環境變數} CFLAGS_ALIASING

Strict or non-strict aliasing flags used to compile @code{Python/dtoa.c}.


在 3.7 版被加入.

@end deffn

@geindex 環境變數; CCSHARED
@anchor{using/configure envvar-CCSHARED}@anchor{20aa}
@deffn {環境變數} CCSHARED

用於建置共享函式庫的編譯器旗標。

例如說 @code{-fPIC} 被使用於 Linux 與 BSD 上。
@end deffn

@geindex 環境變數; CFLAGSFORSHARED
@anchor{using/configure envvar-CFLAGSFORSHARED}@anchor{20ab}
@deffn {環境變數} CFLAGSFORSHARED

用於建置直譯器目的檔的額外 C 旗標。

預設值：當使用 @ref{a5c,,--enable-shared} 時為 @code{$(CCSHARED)}，否則為空字串。
@end deffn

@geindex 環境變數; PY_CFLAGS
@anchor{using/configure envvar-PY_CFLAGS}@anchor{20ac}
@deffn {環境變數} PY_CFLAGS

預設值：@code{$(BASECFLAGS) $(OPT) $(CONFIGURE_CFLAGS) $(CFLAGS) $(EXTRA_CFLAGS)}。
@end deffn

@geindex 環境變數; PY_CFLAGS_NODIST
@anchor{using/configure envvar-PY_CFLAGS_NODIST}@anchor{20ad}
@deffn {環境變數} PY_CFLAGS_NODIST

預設值：@code{$(CONFIGURE_CFLAGS_NODIST) $(CFLAGS_NODIST) -I$(srcdir)/Include/internal}。


在 3.5 版被加入.

@end deffn

@geindex 環境變數; PY_STDMODULE_CFLAGS
@anchor{using/configure envvar-PY_STDMODULE_CFLAGS}@anchor{20ae}
@deffn {環境變數} PY_STDMODULE_CFLAGS

用於建置直譯器目的檔的 C 旗標。

預設值：@code{$(PY_CFLAGS) $(PY_CFLAGS_NODIST) $(PY_CPPFLAGS) $(CFLAGSFORSHARED)}。


在 3.7 版被加入.

@end deffn

@geindex 環境變數; PY_CORE_CFLAGS
@anchor{using/configure envvar-PY_CORE_CFLAGS}@anchor{20af}
@deffn {環境變數} PY_CORE_CFLAGS

預設值：@code{$(PY_STDMODULE_CFLAGS) -DPy_BUILD_CORE}。


在 3.2 版被加入.

@end deffn

@geindex 環境變數; PY_BUILTIN_MODULE_CFLAGS
@anchor{using/configure envvar-PY_BUILTIN_MODULE_CFLAGS}@anchor{20b0}
@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.

預設值：@code{$(PY_STDMODULE_CFLAGS) -DPy_BUILD_CORE_BUILTIN}。


在 3.8 版被加入.

@end deffn

@geindex 環境變數; PURIFY
@anchor{using/configure envvar-PURIFY}@anchor{20b1}
@deffn {環境變數} PURIFY

Purify command. Purify is a memory debugger program.

預設值：空字串（未使用）。
@end deffn

@node Linker flags,,編譯器旗標,Compiler and linker flags
@anchor{using/configure linker-flags}@anchor{20b2}
@subsubsection Linker flags


@geindex 環境變數; LINKCC
@anchor{using/configure envvar-LINKCC}@anchor{20b3}
@deffn {環境變數} LINKCC

Linker command used to build programs like @code{python} and @code{_testembed}.

預設值：@code{$(PURIFY) $(CC)}。
@end deffn

@geindex 環境變數; CONFIGURE_LDFLAGS
@anchor{using/configure envvar-CONFIGURE_LDFLAGS}@anchor{20b4}
@deffn {環境變數} CONFIGURE_LDFLAGS

Value of 
@geindex LDFLAGS
@geindex 環境變數; LDFLAGS
@ref{16ac,,LDFLAGS} variable passed to the @code{./configure} script.

Avoid assigning 
@geindex CFLAGS
@geindex 環境變數; CFLAGS
@ref{16ab,,CFLAGS}, 
@geindex LDFLAGS
@geindex 環境變數; LDFLAGS
@ref{16ac,,LDFLAGS}, etc. so users can use
them on the command line to append to these values without stomping the
pre-set values.


在 3.2 版被加入.

@end deffn

@geindex 環境變數; LDFLAGS_NODIST
@anchor{using/configure envvar-LDFLAGS_NODIST}@anchor{20b5}
@deffn {環境變數} LDFLAGS_NODIST

@geindex LDFLAGS_NODIST
@geindex 環境變數; LDFLAGS_NODIST
@ref{20b5,,LDFLAGS_NODIST} is used in the same manner as
@geindex CFLAGS_NODIST
@geindex 環境變數; CFLAGS_NODIST
@ref{20a3,,CFLAGS_NODIST}.  Use it when a linker flag should `not' be part of
@geindex LDFLAGS
@geindex 環境變數; LDFLAGS
@ref{16ac,,LDFLAGS} once Python is installed (gh-65320@footnote{https://github.com/python/cpython/issues/65320}).

In particular, 
@geindex LDFLAGS
@geindex 環境變數; LDFLAGS
@ref{16ac,,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{16ac,,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{20b6}
@deffn {環境變數} CONFIGURE_LDFLAGS_NODIST

Value of 
@geindex LDFLAGS_NODIST
@geindex 環境變數; LDFLAGS_NODIST
@ref{20b5,,LDFLAGS_NODIST} variable passed to the @code{./configure}
script.


在 3.8 版被加入.

@end deffn

@geindex 環境變數; LDFLAGS
@anchor{using/configure envvar-LDFLAGS}@anchor{16ac}
@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{16ad,,CPPFLAGS} and 
@geindex LDFLAGS
@geindex 環境變數; LDFLAGS
@ref{16ac,,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 環境變數; LIBS
@anchor{using/configure envvar-LIBS}@anchor{20b7}
@deffn {環境變數} LIBS

Linker flags to pass libraries to the linker when linking the Python
executable.

範例：@code{-lrt}。
@end deffn

@geindex 環境變數; LDSHARED
@anchor{using/configure envvar-LDSHARED}@anchor{20b8}
@deffn {環境變數} LDSHARED

建置共享函式庫的指令。

預設值：@code{@@LDSHARED@@ $(PY_LDFLAGS)}。
@end deffn

@geindex 環境變數; BLDSHARED
@anchor{using/configure envvar-BLDSHARED}@anchor{20b9}
@deffn {環境變數} BLDSHARED

建置 @code{libpython} 共享函式庫的指令。

預設值：@code{@@BLDSHARED@@ $(PY_CORE_LDFLAGS)}。
@end deffn

@geindex 環境變數; PY_LDFLAGS
@anchor{using/configure envvar-PY_LDFLAGS}@anchor{20ba}
@deffn {環境變數} PY_LDFLAGS

預設值：@code{$(CONFIGURE_LDFLAGS) $(LDFLAGS)}。
@end deffn

@geindex 環境變數; PY_LDFLAGS_NODIST
@anchor{using/configure envvar-PY_LDFLAGS_NODIST}@anchor{20bb}
@deffn {環境變數} PY_LDFLAGS_NODIST

預設值：@code{$(CONFIGURE_LDFLAGS_NODIST) $(LDFLAGS_NODIST)}。


在 3.8 版被加入.

@end deffn

@geindex 環境變數; PY_CORE_LDFLAGS
@anchor{using/configure envvar-PY_CORE_LDFLAGS}@anchor{20bc}
@deffn {環境變數} PY_CORE_LDFLAGS

Linker flags used for building the interpreter object files.


在 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 在 Windows 上使用 Python,於 macOS 使用 Python,配置 Python,Python 的設置與使用
@anchor{using/windows doc}@anchor{20bd}@anchor{using/windows translation-repo}@anchor{20be}@anchor{using/windows using-on-windows}@anchor{c95}@anchor{using/windows using-python-on-windows}@anchor{20bf}
@section 在 Windows 上使用 Python


This document aims to give an overview of Windows-specific behaviour you should
know about when using Python on Microsoft Windows.

Unlike most Unix systems and services, Windows does not include a system
supported installation of Python. Instead, Python can be obtained from a number
of distributors, including directly from the CPython team. Each Python
distribution will have its own benefits and drawbacks, however, consistency with
other tools you are using is generally a worthwhile benefit. Before committing
to the process described here, we recommend investigating your existing tools to
see if they can provide Python directly.

To obtain Python from the CPython team, use the Python Install Manager. This
is a standalone tool that makes Python available as global commands on your
Windows machine, integrates with the system, and supports updates over time. You
can download the Python Install Manager from python.org/downloads@footnote{https://www.python.org/downloads/} or through
the Microsoft Store app@footnote{https://apps.microsoft.com/detail/9NQ7512CXL7T}.

Once you have installed the Python Install Manager, the global @code{python}
command can be used from any terminal to launch your current latest version of
Python. This version may change over time as you add or remove different
versions, and the @code{py list} command will show which is current.

In general, we recommend that you create a @ref{1fb1,,virtual environment}
for each project and run @code{<env>\Scripts\Activate} in your terminal to use it.
This provides isolation between projects, consistency over time, and ensures
that additional commands added by packages are also available in your session.
Create a virtual environment using @code{python -m venv <env path>}.

If the @code{python} or @code{py} commands do not seem to be working, please see the
@ref{20c0,,Troubleshooting} section below. There are
sometimes additional manual steps required to configure your PC.

Apart from using the Python install manager, Python can also be obtained as
NuGet packages. See @ref{20c1,,nuget.org 套件} below for more information on these
packages.

The embeddable distros are minimal packages of Python suitable for embedding
into larger applications. They can be installed using the Python install
manager. See @ref{20c2,,The embeddable package} below for more information on these
packages.
@anchor{using/windows pymanager}@anchor{20c3}@anchor{using/windows windows-store}@anchor{1e90}@anchor{using/windows setting-envvars}@anchor{1e91}@anchor{using/windows windows-path-mod}@anchor{124c}
@menu
* Python 安裝管理員:: 
* The embeddable package:: 
* nuget.org 套件: nuget org 套件. 
* Alternative bundles:: 
* Supported Windows versions:: 
* Removing the MAX_PATH limitation:: 
* UTF-8 模式:: 
* 找尋模組:: 
* 額外的模組:: 
* 編譯 Python 在 Windows:: 
* The full installer (deprecated): The full installer deprecated. 
* Python launcher for Windows (deprecated): Python launcher for Windows deprecated. 

@end menu

@node Python 安裝管理員,The embeddable package,,在 Windows 上使用 Python
@anchor{using/windows launcher}@anchor{7d3}@anchor{using/windows python-install-manager}@anchor{20c4}
@subsection Python 安裝管理員


@menu
* 安裝:: 
* 基本使用:: 
* Command help:: 
* 列出 runtimes:: 
* 安裝 runtimes:: 
* 離線安裝:: 
* 解除安裝 runtimes:: 
* 設定:: 
* Shebang lines:: 
* 進階安裝:: 
* Administrative configuration:: 
* Installing free-threaded binaries:: 
* Troubleshooting:: 

@end menu

@node 安裝,基本使用,,Python 安裝管理員
@anchor{using/windows installation}@anchor{20c5}
@subsubsection 安裝


The Python install manager can be installed from the Microsoft Store app@footnote{https://apps.microsoft.com/detail/9NQ7512CXL7T}
or downloaded and installed from python.org/downloads@footnote{https://www.python.org/downloads/}. The two versions are
identical.

To install through the Store, simply click "Install". After it has completed,
open a terminal and type @code{python} to get started.

To install the file downloaded from python.org, either double-click and select
"Install", or run @code{Add-AppxPackage <path to MSIX>} in Windows Powershell.

After installation, the @code{python}, @code{py}, and @code{pymanager} commands should be
available. If you have existing installations of Python, or you have modified
your 
@geindex PATH
@geindex 環境變數; PATH
@code{PATH} variable, you may need to remove them or undo the
modifications. See @ref{20c0,,Troubleshooting} for more help with fixing
non-working commands.

When you first install a runtime, you will likely be prompted to add a directory
to your 
@geindex PATH
@geindex 環境變數; PATH
@code{PATH}. This is optional, if you prefer to use the @code{py}
command, but is offered for those who prefer the full range of aliases (such
as @code{python3.14.exe}) to be available. The directory will be
@code{%LocalAppData%\Python\bin} by default, but may be customized by an
administrator. Click Start and search for "Edit environment variables for your
account" for the system settings page to add the path.

Each Python runtime you install will have its own directory for scripts. These
also need to be added to 
@geindex PATH
@geindex 環境變數; PATH
@code{PATH} if you want to use them.

The Python install manager will be automatically updated to new releases. This
does not affect any installs of Python runtimes. Uninstalling the Python install
manager does not uninstall any Python runtimes.

If you are not able to install an MSIX in your context, for example, you are
using automated deployment software that does not support it, or are targeting
Windows Server 2019, please see @ref{20c6,,進階安裝} below for more
information.

@node 基本使用,Command help,安裝,Python 安裝管理員
@anchor{using/windows basic-use}@anchor{20c7}
@subsubsection 基本使用


The recommended command for launching Python is @code{python}, which will either
launch the version requested by the script being launched, an active virtual
environment, or the default installed version, which will be the latest stable
release unless configured otherwise. If no version is specifically requested and
no runtimes are installed at all, the current latest release will be installed
automatically.

For all scenarios involving multiple runtime versions, the recommended command
is @code{py}. This may be used anywhere in place of @code{python} or the older
@code{py.exe} launcher. By default, @code{py} matches the behaviour of @code{python}, but
also allows command line options to select a specific version as well as
subcommands to manage installations. These are detailed below.

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 install and launch your default interpreter, while @code{pymanager}
will display help (@code{pymanager exec ...} provides equivalent behaviour to
@code{py ...}).

Each of these commands also has a windowed version that avoids creating a
console window. These are @code{pyw}, @code{pythonw} and @code{pymanagerw}. A @code{python3}
command is also included that mimics the @code{python} command. It is intended to
catch accidental uses of the typical POSIX command on Windows, but is not meant
to be widely used or recommended.

To launch your default runtime, run @code{python} or @code{py} with the arguments you
want to be passed to the runtime (such as script files or the module to launch):

@example
$> py
...
$> python my-script.py
...
$> py -m this
...
@end example

The default runtime can be overridden with the 
@geindex PYTHON_MANAGER_DEFAULT
@geindex 環境變數; PYTHON_MANAGER_DEFAULT
@ref{20c8,,PYTHON_MANAGER_DEFAULT}
environment variable, or a configuration file. See @ref{20c9,,設定} for
information about configuration settings.

To launch a specific runtime, the @code{py} command accepts a @code{-V:<TAG>} option.
This option must be specified before any others. The tag is part or all of the
identifier for the runtime; for those from the CPython team, it looks like the
version, potentially with the platform. For compatibility, the @code{V:} may be
omitted in cases where the tag refers to an official release and starts with
@code{3}.

@example
$> py -V:3.14 ...
$> py -V:3-arm64 ...
@end example

Runtimes from other distributors may require the `company' to be included as
well. This should be separated from the tag by a slash, and may be a prefix.
Specifying the company is optional when it is @code{PythonCore}, and specifying the
tag is optional (but not the slash) when you want the latest release from a
specific company.

@example
$> py -V:Distributor\1.0 ...
$> py -V:distrib/ ...
@end example

If no version is specified, but a script file is passed, the script will be
inspected for a `shebang line'. This is a special format for the first line in
a file that allows overriding the command. See @ref{20ca,,Shebang lines} for more
information. When there is no shebang line, or it cannot be resolved, the script
will be launched with the default runtime.

If you are running in an active virtual environment, have not requested a
particular version, and there is no shebang line, the default runtime will be
that virtual environment. In this scenario, the @code{python} command was likely
already overridden and none of these checks occurred. However, this behaviour
ensures that the @code{py} command can be used interchangeably.

When you launch either @code{python} or @code{py} but do not have any runtimes
installed, and the requested version is the default, it will be installed
automatically and then launched. Otherwise, the requested version will be
installed if automatic installation is configured (most likely by setting
@code{PYTHON_MANAGER_AUTOMATIC_INSTALL} to @code{true}), or if the @code{py exec} or
@code{pymanager exec} forms of the command were used.

@node Command help,列出 runtimes,基本使用,Python 安裝管理員
@anchor{using/windows command-help}@anchor{20cb}
@subsubsection Command help


The @code{py help} command will display the full list of supported commands, along
with their options. Any command may be passed the @code{-?} option to display its
help, or its name passed to @code{py help}.

@example
$> py help
$> py help install
$> py install /?
@end example

All commands support some common options, which will be shown by @code{py help}.
These options must be specified after any subcommand. Specifying @code{-v} or
@code{--verbose} will increase the amount of output shown, and @code{-vv} will
increase it further for debugging purposes. Passing @code{-q} or @code{--quiet} will
reduce output, and @code{-qq} will reduce it further.

The @code{--config=<PATH>} option allows specifying a configuration file to
override multiple settings at once. See @ref{20c9,,設定} below for more
information about these files.

@node 列出 runtimes,安裝 runtimes,Command help,Python 安裝管理員
@anchor{using/windows listing-runtimes}@anchor{20cc}
@subsubsection 列出 runtimes


@example
$> py list [-f=|--format=<FMT>] [-1|--one] [--online|-s=|--source=<URL>] [<TAG>...]
@end example

The list of installed runtimes can be seen using @code{py list}. A filter may be
added in the form of one or more tags (with or without company specifier), and
each may include a @code{<}, @code{<=}, @code{>=} or @code{>} prefix to restrict to a range.

A range of formats are supported, and can be passed as the @code{--format=<FMT>} or
@code{-f <FMT>} option. Formats include @code{table} (a user friendly table view),
@code{csv} (comma-separated table), @code{json} (a single JSON blob), @code{jsonl} (one
JSON blob per result), @code{exe} (just the executable path), @code{prefix} (just the
prefix path).

The @code{--one} or @code{-1} option only displays a single result. If the default
runtime is included, it will be the one. Otherwise, the "best" result is shown
("best" is deliberately vaguely defined, but will usually be the most recent
version). The result shown by @code{py list --one <TAG>} will match the runtime
that would be launched by @code{py -V:<TAG>}.

The @code{--only-managed} option excludes results that were not installed by the
Python install manager. This is useful when determining which runtimes may be
updated or uninstalled through the @code{py} command.

The @code{--online} option is short for passing @code{--source=<URL>} with the default
source. Passing either of these options will search the online index for
runtimes that can be installed. The result shown by @code{py list --online --one
<TAG>} will match the runtime that would be installed by @code{py install <TAG>}.

@example
$> py list --online 3.14
@end example

For compatibility with the old launcher, the @code{--list}, @code{--list-paths},
@code{-0} and @code{-0p} commands (e.g. @code{py -0p}) are retained. They do not allow
additional options, and will produce legacy formatted output.

@node 安裝 runtimes,離線安裝,列出 runtimes,Python 安裝管理員
@anchor{using/windows installing-runtimes}@anchor{20cd}
@subsubsection 安裝 runtimes


@example
$> py install [-s=|--source=<URL>] [-f|--force] [-u|--update] [--dry-run] [<TAG>...]
@end example

New runtime versions may be added using @code{py install}. One or more tags may be
specified, and the special tag @code{default} may be used to select the default.
Ranges are not supported for installation.

The @code{--source=<URL>} option allows overriding the online index that is used to
obtain runtimes. This may be used with an offline index, as shown in
@ref{20ce,,離線安裝}.

Passing @code{--force} will ignore any cached files and remove any existing install
to replace it with the specified one.

Passing @code{--update} will replace existing installs if the new version is newer.
Otherwise, they will be left. If no tags are provided with @code{--update}, all
installs managed by the Python install manager will be updated if newer versions
are available. Updates will remove any modifications made to the install,
including globally installed packages, but virtual environments will continue to
work.

Passing @code{--dry-run} will generate output and logs, but will not modify any
installs.

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.

@example
$> py install ... [-t=|--target=<PATH>] <TAG>
@end example

@node 離線安裝,解除安裝 runtimes,安裝 runtimes,Python 安裝管理員
@anchor{using/windows offline-installs}@anchor{20cf}@anchor{using/windows pymanager-offline}@anchor{20ce}
@subsubsection 離線安裝


To perform offline installs of Python, you will need to first create an offline
index on a machine that has network access.

@example
$> py install --download=<PATH> ... <TAG>...
@end example

The @code{--download=<PATH>} option will download the packages for the listed tags
and create a directory containing them and an @code{index.json} file suitable for
later installation. This entire directory can be moved to the offline machine
and used to install one or more of the bundled runtimes:

@example
$> py install --source="<PATH>\index.json" <TAG>...
@end example

The Python install manager can be installed by downloading its installer and
moving it to another machine before installing.

Alternatively, the ZIP files in an offline index directory can simply be
transferred to another machine and extracted. This will not register the install
in any way, and so it must be launched by directly referencing the executables
in the extracted directory, but it is sometimes a preferable approach in cases
where installing the Python install manager is not possible or convenient.

In this way, Python runtimes can be installed and managed on a machine without
access to the internet.

@node 解除安裝 runtimes,設定,離線安裝,Python 安裝管理員
@anchor{using/windows uninstalling-runtimes}@anchor{20d0}
@subsubsection 解除安裝 runtimes


@example
$> py uninstall [-y|--yes] <TAG>...
@end example

Runtimes may be removed using the @code{py uninstall} command. One or more tags
must be specified. Ranges are not supported here.

The @code{--yes} option bypasses the confirmation prompt before uninstalling.

Instead of passing tags individually, the @code{--purge} option may be specified.
This will remove all runtimes managed by the Python install manager, including
cleaning up the Start menu, registry, and any download caches. Runtimes that
were not installed by the Python install manager will not be impacted, and
neither will manually created configuration files.

@example
$> py uninstall [-y|--yes] --purge
@end example

The Python install manager can be uninstalled through the Windows "Installed
apps" settings page. This does not remove any runtimes, and they will still be
usable, though the global @code{python} and @code{py} commands will be removed.
Reinstalling the Python install manager will allow you to manage these runtimes
again. To completely clean up all Python runtimes, run with @code{--purge} before
uninstalling the Python install manager.

@node 設定,Shebang lines,解除安裝 runtimes,Python 安裝管理員
@anchor{using/windows configuration}@anchor{20d1}@anchor{using/windows pymanager-config}@anchor{20c9}
@subsubsection 設定


Python install manager is configured with a hierarchy of configuration files,
environment variables, command-line options, and registry settings. In general,
configuration files have the ability to configure everything, including the
location of other configuration files, while registry settings are
administrator-only and will override configuration files. Command-line options
override all other settings, but not every option is available.

This section will describe the defaults, but be aware that modified or
overridden installs may resolve settings differently.

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} (by default) 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).

The following settings are those that are considered likely to be modified in
normal use. Later sections list those that are intended for administrative
customization.

@c Sphinx bug with text writer; remove widths & caption temporarily

@c :widths: 2, 2, 4

@subsubheading Standard configuration options



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Config Key

@tab

Environment Variable

@tab

描述

@item

@code{default_tag}

@tab

@geindex 環境變數; PYTHON_MANAGER_DEFAULT
@anchor{using/windows envvar-PYTHON_MANAGER_DEFAULT}@anchor{20c8}
@deffn {環境變數} PYTHON_MANAGER_DEFAULT
@end deffn

@tab

The preferred default version to launch or install.
By default, this is interpreted as the most recent non-prerelease version
from the CPython team.

@item

@code{default_platform}

@tab

@code{PYTHON_MANAGER_DEFAULT_PLATFORM}

@tab

The preferred default platform to launch or install.
This is treated as a suffix to the specified tag, such that @code{py -V:3.14}
would prefer an install for @code{3.14-64} if it exists
(and @code{default_platform} is @code{-64}),
but will use @code{3.14} if no tagged install exists.

@item

@code{logs_dir}

@tab

@code{PYTHON_MANAGER_LOGS}

@tab

The location where log files are written.
By default, @code{%TEMP%}.

@item

@code{automatic_install}

@tab

@code{PYTHON_MANAGER_AUTOMATIC_INSTALL}

@tab

True to allow automatic installs when specifying a particular runtime
to launch.
By default, true.

@item

@code{include_unmanaged}

@tab

@code{PYTHON_MANAGER_INCLUDE_UNMANAGED}

@tab

True to allow listing and launching runtimes that were not installed
by the Python install manager, or false to exclude them.
By default, true.

@item

@code{shebang_can_run_anything}

@tab

@code{PYTHON_MANAGER_SHEBANG_CAN_RUN_ANYTHING}

@tab

True to allow shebangs in @code{.py} files to launch applications other than
Python runtimes, or false to prevent it.
By default, true.

@item

@code{log_level}

@tab

@code{PYMANAGER_VERBOSE}、@code{PYMANAGER_DEBUG}

@tab

Set the default level of output (0-50).
By default, 20.
Lower values produce more output.
The environment variables are boolean, and may produce additional
output during startup that is later suppressed by other configuration.

@item

@code{confirm}

@tab

@code{PYTHON_MANAGER_CONFIRM}

@tab

True to confirm certain actions before taking them (such as uninstall),
or false to skip the confirmation.
By default, true.

@item

@code{install.source}

@tab

@code{PYTHON_MANAGER_SOURCE_URL}

@tab

Override the index feed to obtain new installs from.

@item

@code{list.format}

@tab

@code{PYTHON_MANAGER_LIST_FORMAT}

@tab

Specify the default format used by the @code{py list} command.
By default, @code{table}.

@end multitable


Dotted names should be nested inside JSON objects, for example, @code{list.format}
would be specified as @code{@{"list": @{"format": "table"@}@}}.

@node Shebang lines,進階安裝,設定,Python 安裝管理員
@anchor{using/windows pymanager-shebang}@anchor{20ca}@anchor{using/windows shebang-lines}@anchor{20d2}
@subsubsection Shebang lines


If the first line of a script file starts with @code{#!}, it is known as a
"shebang" line.  Linux and other Unix like operating systems have native
support for such lines and they are commonly used on such systems to indicate
how a script should be executed. The @code{python} and @code{py} commands allow the
same facilities to be used with Python scripts on Windows.

To allow shebang lines in Python scripts to be portable between Unix and
Windows, a number of 'virtual' commands are supported to specify which
interpreter to use.  The supported virtual commands are:


@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

For example, if the first line of your script starts with

@example
#! /usr/bin/python
@end example

The default Python or an active virtual environment will be located and used.
As many Python scripts written to work on Unix will already have this line,
you should find these scripts can be used by the launcher without modification.
If you are writing a new script on Windows which you hope will be useful on
Unix, you should use one of the shebang lines starting with @code{/usr}.

Any of the above virtual commands can have @code{<ALIAS>} replaced by an alias from
an installed runtime. That is, any command generated in the global aliases
directory (which you may have added to your 
@geindex PATH
@geindex 環境變數; PATH
@code{PATH} environment variable)
can be used in a shebang, even if it is not on your 
@geindex PATH
@geindex 環境變數; PATH
@code{PATH}. This allows
the use of shebangs like @code{/usr/bin/python3.12} to select a particular runtime.

If no runtimes are installed, or if automatic installation is enabled, the
requested runtime will be installed if necessary. See @ref{20c9,,設定}
for information about configuration settings.

The @code{/usr/bin/env} form of shebang line will also search the 
@geindex PATH
@geindex 環境變數; PATH
@code{PATH}
environment variable for unrecognized commands. This corresponds to the
behaviour of the Unix @code{env} program, which performs the same search, but
prefers launching known Python commands. A warning may be displayed when
searching for arbitrary executables, and this search may be disabled by the
@code{shebang_can_run_anything} configuration option.

Shebang lines that do not match any of patterns are treated as `Windows'
executable paths that are absolute or relative to the directory containing the
script file. This is a convenience for Windows-only scripts, such as those
generated by an installer, since the behavior is not compatible with Unix-style
shells. These paths may be quoted, and may include multiple arguments, after
which the path to the script and any additional arguments will be appended.
This functionality may be disabled by the @code{shebang_can_run_anything}
configuration option.

@cartouche
@quotation 備註 
The behaviour of shebangs in the Python install manager is subtly different
from the previous @code{py.exe} launcher, and the old configuration options no
longer apply. If you are specifically reliant on the old behaviour or
configuration, we recommend keeping the legacy launcher. It may be
downloaded independently@footnote{https://www.python.org/ftp/python/3.13.1/win32/launcher.msi}
and installed on its own. The legacy launcher's @code{py} command will override
PyManager's one, and you will need to use @code{pymanager} commands for
installing and uninstalling.
@end quotation
@end cartouche

@node 進階安裝,Administrative configuration,Shebang lines,Python 安裝管理員
@anchor{using/windows advanced-installation}@anchor{20d3}@anchor{using/windows pymanager-advancedinstall}@anchor{20c6}
@subsubsection 進階安裝


For situations where an MSIX cannot be installed, such as some older
administrative distribution platforms, there is an MSI available from the
python.org downloads page. This MSI has no user interface, and can only perform
per-machine installs to its default location in Program Files. It will attempt
to modify the system 
@geindex PATH
@geindex 環境變數; PATH
@code{PATH} environment variable to include this install
location, but be sure to validate this on your configuration.

@cartouche
@quotation 備註 
Windows Server 2019 is the only version of Windows that CPython supports that
does not support MSIX. For Windows Server 2019, you should use the MSI.
@end quotation
@end cartouche

Be aware that the MSI package does not bundle any runtimes, and so is not
suitable for installs into offline environments without also creating an offline
install index. See @ref{20ce,,離線安裝} and @ref{20d4,,Administrative configuration}
for information on handling these scenarios.

Runtimes installed by the MSI are shared with those installed by the MSIX, and
are all per-user only. The Python install manager does not support installing
runtimes per-machine. To emulate a per-machine install, you can use @code{py install
--target=<shared location>} as administrator and add your own system-wide
modifications to 
@geindex PATH
@geindex 環境變數; PATH
@code{PATH}, the registry, or the Start menu.

When the MSIX is installed, but commands are not available in the 
@geindex PATH
@geindex 環境變數; PATH
@code{PATH}
environment variable, they can be found under
@code{%LocalAppData%\Microsoft\WindowsApps\PythonSoftwareFoundation.PythonManager_3847v3x7pw1km}
or
@code{%LocalAppData%\Microsoft\WindowsApps\PythonSoftwareFoundation.PythonManager_qbz5n2kfra8p0},
depending on whether it was installed from python.org or through the Windows
Store. Attempting to run the executable directly from Program Files is not
recommended.

To programmatically install the Python install manager, it is easiest to use
WinGet, which is included with all supported versions of 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

To download the Python install manager and install on another machine, the
following WinGet command will download the required files from the Store to your
Downloads directory (add @code{-d <location>} to customize the output location).
This also generates a YAML file that appears to be unnecessary, as the
downloaded MSIX can be installed by launching or using the commands below.

@example
$> winget download 9NQ7512CXL7T -e --skip-license --accept-package-agreements --accept-source-agreements
@end example

To programmatically install or uninstall an MSIX using only PowerShell, the
Add-AppxPackage@footnote{https://learn.microsoft.com/powershell/module/appx/add-appxpackage} and Remove-AppxPackage@footnote{https://learn.microsoft.com/powershell/module/appx/remove-appxpackage} PowerShell cmdlets are recommended:

@example
$> Add-AppxPackage C:\Downloads\python-manager-25.0.msix
...
$> Get-AppxPackage PythonSoftwareFoundation.PythonManager | Remove-AppxPackage
@end example

The latest release can be downloaded and installed by Windows by passing the
AppInstaller file to the Add-AppxPackage command. This installs using the MSIX
on python.org, and is only recommended for cases where installing via the Store
(interactively or using WinGet) is not possible.

@example
$> Add-AppxPackage -AppInstallerFile https://www.python.org/ftp/python/pymanager/pymanager.appinstaller
@end example

Other tools and APIs may also be used to provision an MSIX package for all users
on a machine, but Python does not consider this a supported scenario. We suggest
looking into the PowerShell Add-AppxProvisionedPackage@footnote{https://learn.microsoft.com/powershell/module/dism/add-appxprovisionedpackage} cmdlet, the native
Windows PackageManager@footnote{https://learn.microsoft.com/uwp/api/windows.management.deployment.packagemanager} class, or the documentation and support for your
deployment tool.

Regardless of the install method, users will still need to install their own
copies of Python itself, as there is no way to trigger those installs without
being a logged in user. When using the MSIX, the latest version of Python will
be available for all users to install without network access.

Note that the MSIX downloadable from the Store and from the Python website are
subtly different and cannot be installed at the same time. Wherever possible,
we suggest using the above WinGet commands to download the package from the
Store to reduce the risk of setting up conflicting installs. There are no
licensing restrictions on the Python install manager that would prevent using
the Store package in this way.

@node Administrative configuration,Installing free-threaded binaries,進階安裝,Python 安裝管理員
@anchor{using/windows administrative-configuration}@anchor{20d5}@anchor{using/windows pymanager-admin-config}@anchor{20d4}
@subsubsection Administrative configuration


There are a number of options that may be useful for administrators to override
configuration of the Python install manager. These can be used to provide local
caching, disable certain shortcut types, override bundled content. All of the
above configuration options may be set, as well as those below.

Configuration options may be overridden in the registry by setting values under
@code{HKEY_LOCAL_MACHINE\Software\Policies\Python\PyManager}, where the
value name matches the configuration key and the value type is @code{REG_SZ}. Note
that this key can itself be customized, but only by modifying the core config
file distributed with the Python install manager. We recommend, however, that
registry values are used only to set @code{base_config} to a JSON file containing
the full set of overrides. Registry key overrides will replace any other
configured setting, while @code{base_config} allows users to further modify
settings they may need.

Note that most settings with environment variables support those variables
because their default setting specifies the variable. If you override them, the
environment variable will no longer work, unless you override it with another
one. For example, the default value of @code{confirm} is literally
@code{%PYTHON_MANAGER_CONFIRM%}, which will resolve the variable at load time. If
you override the value to @code{yes}, then the environment variable will no longer
be used. If you override the value to @code{%CONFIRM%}, then that environment
variable will be used instead.

Configuration settings that are paths are interpreted as relative to the
directory containing the configuration file that specified them.

@c Sphinx bug with text writer; remove widths & caption temporarily

@c :widths: 1, 4

@subsubheading Administrative configuration options



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Config Key

@tab

描述

@item

@code{base_config}

@tab

The highest priority configuration file to read.
Note that only the built-in configuration file and the registry can
modify this setting.

@item

@code{user_config}

@tab

The second configuration file to read.

@item

@code{additional_config}

@tab

The third configuration file to read.

@item

@code{registry_override_key}

@tab

Registry location to check for overrides.
Note that only the built-in configuration file can modify this setting.

@item

@code{bundled_dir}

@tab

Read-only directory containing locally cached files.

@item

@code{install.fallback_source}

@tab

Path or URL to an index to consult when the main index cannot be accessed.

@item

@code{install.enable_shortcut_kinds}

@tab

Comma-separated list of shortcut kinds to allow (e.g. @code{"pep514,start"}).
Enabled shortcuts may still be disabled by @code{disable_shortcut_kinds}.

@item

@code{install.disable_shortcut_kinds}

@tab

Comma-separated list of shortcut kinds to exclude
(e.g. @code{"pep514,start"}).
Disabled shortcuts are not reactivated by @code{enable_shortcut_kinds}.

@item

@code{pep514_root}

@tab

Registry location to read and write PEP 514 entries into.
By default, @code{HKEY_CURRENT_USER\Software\Python}.

@item

@code{start_folder}

@tab

Start menu folder to write shortcuts into.
By default, @code{Python}.
This path is relative to the user's Programs folder.

@item

@code{virtual_env}

@tab

Path to the active virtual environment.
By default, this is @code{%VIRTUAL_ENV%}, but may be set empty
to disable venv detection.

@item

@code{shebang_can_run_anything_silently}

@tab

True to suppress visible warnings when a shebang launches an application
other than a Python runtime.

@end multitable


@node Installing free-threaded binaries,Troubleshooting,Administrative configuration,Python 安裝管理員
@anchor{using/windows install-freethreaded-windows}@anchor{492}@anchor{using/windows installing-free-threaded-binaries}@anchor{20d6}
@subsubsection Installing free-threaded binaries



在 3.13 版被加入.


Pre-built distributions of the free-threaded build are available
by installing tags with the @code{t} suffix.

@example
$> py install 3.14t
$> py install 3.14t-arm64
$> py install 3.14t-32
@end example

This will install and register as normal. If you have no other runtimes
installed, then @code{python} will launch this one. Otherwise, you will need to use
@code{py -V:3.14t ...} or, if you have added the global aliases directory to your
@geindex PATH
@geindex 環境變數; PATH
@code{PATH} environment variable, the @code{python3.14t.exe} commands.

@node Troubleshooting,,Installing free-threaded binaries,Python 安裝管理員
@anchor{using/windows pymanager-troubleshoot}@anchor{20c0}@anchor{using/windows troubleshooting}@anchor{20d7}
@subsubsection Troubleshooting


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/cpython/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 Troubleshooting



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Symptom

@tab

Things to try

@item

@code{python} gives me a "command not found" error or opens the Store app
when I type it in my terminal.

@tab

Did you @ref{20c3,,install the Python install manager}?

@item

@tab

Click Start, open "Manage app execution aliases", and check that the
aliases for "Python (default)" are enabled.
If they already are, try disabling and re-enabling to refresh the command.
The "Python (default windowed)" and "Python install manager" commands
may also need refreshing.

@item

@tab

Check that the @code{py} and @code{pymanager} commands work.

@item

@code{py} gives me a "command not found" error when I type it in my terminal.

@tab

Did you @ref{20c3,,install the Python install manager}?

@item

@tab

Click Start, open "Manage app execution aliases", and check that the
aliases for "Python (default)" are enabled.
If they already are, try disabling and re-enabling to refresh the command.
The "Python (default windowed)" and "Python install manager" commands
may also need refreshing.

@item

@code{py} gives me a "can't open file" error when I type commands in my
terminal.

@tab

This usually means you have the legacy launcher installed and
it has priority over the Python install manager.
To remove, click Start, open "Installed apps",
search for "Python launcher" and uninstall it.

@item

@code{python} doesn't launch the same runtime as @code{py}

@tab

Click Start, open "Installed apps", look for any existing Python runtimes,
and either remove them or Modify and disable the 
@geindex PATH
@geindex 環境變數; PATH
@code{PATH} options.

@item

@tab

Click Start, open "Manage app execution aliases", and check that your
@code{python.exe} alias is set to "Python (default)"

@item

@code{python} and @code{py} don't launch the runtime I expect

@tab

Check your 
@geindex PYTHON_MANAGER_DEFAULT
@geindex 環境變數; PYTHON_MANAGER_DEFAULT
@ref{20c8,,PYTHON_MANAGER_DEFAULT} environment variable
or @code{default_tag} configuration.
The @code{py list} command will show your default based on these settings.

@item

@tab

Installs that are managed by the Python install manager will be chosen
ahead of unmanaged installs.
Use @code{py install} to install the runtime you expect,
or configure your default tag.

@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 using @code{py install}.

@item

@code{pythonw} or @code{pyw} don't launch the same runtime as @code{python} or @code{py}

@tab

Click Start, open "Manage app execution aliases", and check that your
@code{pythonw.exe} and @code{pyw.exe} aliases are consistent with your others.

@item

@code{pip} gives me a "command not found" error when I type it in my terminal.

@tab

Have you activated a virtual environment?
Run the @code{.venv\Scripts\activate} script in your terminal to activate.

@item

@tab

The package may be available but missing the generated executable.
We recommend using the @code{python -m pip} command instead,
or alternatively the @code{python -m pip install --force pip} command
will recreate the executables and show you the path to
add to 
@geindex PATH
@geindex 環境變數; PATH
@code{PATH}.
These scripts are separated for each runtime, and so you may need to
add multiple paths.

@end multitable


@node The embeddable package,nuget org 套件,Python 安裝管理員,在 Windows 上使用 Python
@anchor{using/windows the-embeddable-package}@anchor{20d8}@anchor{using/windows windows-embeddable}@anchor{20c2}
@subsection The embeddable package



在 3.5 版被加入.


The embedded distribution is a ZIP file containing a minimal Python environment.
It is intended for acting as part of another application, rather than being
directly accessed by end-users.

To install an embedded distribution, we recommend using @code{py install} with the
@code{--target} option:

@example
$> py install 3.14-embed --target=runtime
@end example

When extracted, the embedded distribution is (almost) fully isolated from the
user's system, including environment variables, system registry settings, and
installed packages. The standard library is included as pre-compiled and
optimized @code{.pyc} files in a ZIP, and @code{python3.dll}, @code{python313.dll},
@code{python.exe} and @code{pythonw.exe} are all provided. Tcl/tk (including all
dependents, such as Idle), pip and the Python documentation are not included.

A default @code{._pth} file is included, which further restricts the default search
paths (as described below in @ref{e15,,找尋模組}). This file is
intended for embedders to modify as necessary.

Third-party packages should be installed by the application installer alongside
the embedded distribution. Using pip to manage dependencies as for a regular
Python installation is not supported with this distribution, though with some
care it may be possible to include and use pip for automatic updates. In
general, third-party packages should be treated as part of the application
("vendoring") so that the developer can ensure compatibility with newer
versions before providing updates to users.

The two recommended use cases for this distribution are described below.

@menu
* Python 應用程式:: 
* 嵌入 Python:: 

@end menu

@node Python 應用程式,嵌入 Python,,The embeddable package
@anchor{using/windows python-application}@anchor{20d9}
@subsubsection Python 應用程式


An application written in Python does not necessarily require users to be aware
of that fact. The embedded distribution may be used in this case to include a
private version of Python in an install package. Depending on how transparent it
should be (or conversely, how professional it should appear), there are two
options.

Using a specialized executable as a launcher requires some coding, but provides
the most transparent experience for users. With a customized launcher, there are
no obvious indications that the program is running on Python: icons can be
customized, company and version information can be specified, and file
associations behave properly. In most cases, a custom launcher should simply be
able to call @code{Py_Main} with a hard-coded command line.

The simpler approach is to provide a batch file or generated shortcut that
directly calls the @code{python.exe} or @code{pythonw.exe} with the required
command-line arguments. In this case, the application will appear to be Python
and not its actual name, and users may have trouble distinguishing it from other
running Python processes or file associations.

With the latter approach, packages should be installed as directories alongside
the Python executable to ensure they are available on the path. With the
specialized launcher, packages can be located in other locations as there is an
opportunity to specify the search path before launching the application.

@node 嵌入 Python,,Python 應用程式,The embeddable package
@anchor{using/windows embedding-python}@anchor{20da}
@subsubsection 嵌入 Python


Applications written in native code often require some form of scripting
language, and the embedded Python distribution can be used for this purpose. In
general, the majority of the application is in native code, and some part will
either invoke @code{python.exe} or directly use @code{python3.dll}. For either case,
extracting the embedded distribution to a subdirectory of the application
installation is sufficient to provide a loadable Python interpreter.

As with the application use, packages can be installed to any location as there
is an opportunity to specify search paths before initializing the interpreter.
Otherwise, there is no fundamental differences between using the embedded
distribution and a regular installation.

@node nuget org 套件,Alternative bundles,The embeddable package,在 Windows 上使用 Python
@anchor{using/windows the-nuget-org-packages}@anchor{20db}@anchor{using/windows windows-nuget}@anchor{20c1}
@subsection nuget.org 套件



在 3.5.2 版被加入.


The nuget.org package is a reduced size Python environment intended for use on
continuous integration and build systems that do not have a system-wide
install of Python. While nuget is "the package manager for .NET", it also works
perfectly fine for packages containing build-time tools.

Visit nuget.org@footnote{https://www.nuget.org/} for the most up-to-date information
on using nuget. What follows is a summary that is sufficient for Python
developers.

The @code{nuget.exe} command line tool may be downloaded directly from
@code{https://aka.ms/nugetclidl}, for example, using curl or PowerShell. With the
tool, the latest version of Python for 64-bit or 32-bit machines is installed
using:

@example
nuget.exe install python -ExcludeVersion -OutputDirectory .
nuget.exe install pythonx86 -ExcludeVersion -OutputDirectory .
@end example

To select a particular version, add a @code{-Version 3.x.y}. The output directory
may be changed from @code{.}, and the package will be installed into a
subdirectory. By default, the subdirectory is named the same as the package,
and without the @code{-ExcludeVersion} option this name will include the specific
version installed. Inside the subdirectory is a @code{tools} directory that
contains the Python installation:

@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

In general, nuget packages are not upgradeable, and newer versions should be
installed side-by-side and referenced using the full path. Alternatively,
delete the package directory manually and install it again. Many CI systems
will do this automatically if they do not preserve files between builds.

Alongside the @code{tools} directory is a @code{build\native} directory. This
contains a MSBuild properties file @code{python.props} that can be used in a
C++ project to reference the Python install. Including the settings will
automatically use the headers and import libraries in your build.

The package information pages on nuget.org are
www.nuget.org/packages/python@footnote{https://www.nuget.org/packages/python}
for the 64-bit version, www.nuget.org/packages/pythonx86@footnote{https://www.nuget.org/packages/pythonx86} for the 32-bit version, and
www.nuget.org/packages/pythonarm64@footnote{https://www.nuget.org/packages/pythonarm64} for the ARM64 version

@menu
* Free-threaded packages:: 

@end menu

@node Free-threaded packages,,,nuget org 套件
@anchor{using/windows free-threaded-packages}@anchor{20dc}
@subsubsection Free-threaded packages



在 3.13 版被加入.


Packages containing free-threaded binaries are named
python-freethreaded@footnote{https://www.nuget.org/packages/python-freethreaded}
for the 64-bit version, pythonx86-freethreaded@footnote{https://www.nuget.org/packages/pythonx86-freethreaded} for the 32-bit
version, and pythonarm64-freethreaded@footnote{https://www.nuget.org/packages/pythonarm64-freethreaded} for the ARM64
version. These packages contain both the @code{python3.13t.exe} and
@code{python.exe} entry points, both of which run free threaded.

@node Alternative bundles,Supported Windows versions,nuget org 套件,在 Windows 上使用 Python
@anchor{using/windows alternative-bundles}@anchor{20dd}
@subsection Alternative bundles


Besides the standard CPython distribution, there are modified packages including
additional functionality.  The following is a list of popular versions and their
key features:


@table @asis

@item ActivePython@footnote{https://www.activestate.com/products/python/}

Installer with multi-platform compatibility, documentation, PyWin32

@item Anaconda@footnote{https://www.anaconda.com/download/}

Popular scientific modules (such as numpy, scipy and pandas) and the
@code{conda} package manager.

@item Enthought Deployment Manager@footnote{https://assets.enthought.com/downloads/edm/}

"The Next Generation Python Environment and Package Manager".

Previously Enthought provided Canopy, but it reached end of life in 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-specific distribution with prebuilt scientific packages and
tools for building packages.
@end table

Note that these packages may not include the latest versions of Python or
other libraries, and are not maintained or supported by the core Python team.

@node Supported Windows versions,Removing the MAX_PATH limitation,Alternative bundles,在 Windows 上使用 Python
@anchor{using/windows supported-windows-versions}@anchor{20de}
@subsection Supported Windows versions


As specified in 
@geindex Python Enhancement Proposals; PEP 11
PEP 11@footnote{https://peps.python.org/pep-0011/}, a Python release only supports a Windows platform
while Microsoft considers the platform under extended support. This means that
Python 3.14 supports Windows 10 and newer. If you require Windows 7
support, please install Python 3.8. If you require Windows 8.1 support,
please install Python 3.12.

@node Removing the MAX_PATH limitation,UTF-8 模式,Supported Windows versions,在 Windows 上使用 Python
@anchor{using/windows max-path}@anchor{e36}@anchor{using/windows removing-the-max-path-limitation}@anchor{20df}
@subsection Removing the MAX_PATH limitation


Windows historically has limited path lengths to 260 characters. This meant that
paths longer than this would not resolve and errors would result.

In the latest versions of Windows, this limitation can be expanded to over
32,000 characters. Your administrator will need to activate the "Enable Win32
long paths" group policy, or set @code{LongPathsEnabled} to @code{1} in the registry
key @code{HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem}.

This allows the @ref{315,,open()} function, the @ref{a5,,os} module and most other
path functionality to accept and return paths longer than 260 characters.

After changing the above option and rebooting, no further configuration is
required.

@node UTF-8 模式,找尋模組,Removing the MAX_PATH limitation,在 Windows 上使用 Python
@anchor{using/windows utf-8-mode}@anchor{20e0}@anchor{using/windows win-utf8-mode}@anchor{20e1}
@subsection UTF-8 模式



在 3.7 版被加入.


Windows still uses legacy encodings for the system encoding (the ANSI Code
Page).  Python uses it for the default encoding of text files (e.g.
@ref{328,,locale.getencoding()}).

This may cause issues because UTF-8 is widely used on the internet
and most Unix systems, including WSL (Windows Subsystem for Linux).

You can use the @ref{85f,,Python UTF-8 Mode} to change the default text
encoding to UTF-8. You can enable the @ref{85f,,Python UTF-8 Mode} via
the @code{-X utf8} command line option, or the @code{PYTHONUTF8=1} environment
variable.  See 
@geindex PYTHONUTF8
@geindex 環境變數; PYTHONUTF8
@ref{cc6,,PYTHONUTF8} for enabling UTF-8 mode, and
@ref{1e91,,Python 安裝管理員} for how to modify environment variables.

When the @ref{85f,,Python UTF-8 Mode} is enabled, you can still use the
system encoding (the ANSI Code Page) via the "mbcs" codec.

Note that adding @code{PYTHONUTF8=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.

@cartouche
@quotation 備註 
Even when UTF-8 mode is disabled, Python uses UTF-8 by default
on Windows for:


@itemize *

@item 
Console I/O including standard I/O (see 
@geindex Python Enhancement Proposals; PEP 528
PEP 528@footnote{https://peps.python.org/pep-0528/} for details).

@item 
The @ref{756,,filesystem encoding}
(see 
@geindex Python Enhancement Proposals; PEP 529
PEP 529@footnote{https://peps.python.org/pep-0529/} for details).
@end itemize
@end quotation
@end cartouche

@node 找尋模組,額外的模組,UTF-8 模式,在 Windows 上使用 Python
@anchor{using/windows finding-modules}@anchor{20e2}@anchor{using/windows windows-finding-modules}@anchor{e15}
@subsection 找尋模組


These notes supplement the description at @ref{1849,,sys.path 模組搜尋路徑的初始化} with
detailed Windows notes.

When no @code{._pth} file is found, this is how @ref{3e2,,sys.path} is populated on
Windows:


@itemize *

@item 
An empty entry is added at the start, which corresponds to the current
directory.

@item 
If the environment variable 
@geindex PYTHONPATH
@geindex 環境變數; PYTHONPATH
@ref{1218,,PYTHONPATH} exists, as described in
@ref{800,,環境變數}, its entries are added next.  Note that on Windows,
paths in this variable must be separated by semicolons, to distinguish them
from the colon used in drive identifiers (@code{C:\} etc.).

@item 
Additional "application paths" can be added in the registry as subkeys of
@code{\SOFTWARE\Python\PythonCore@{version@}\PythonPath} under both the
@code{HKEY_CURRENT_USER} and @code{HKEY_LOCAL_MACHINE} hives.  Subkeys which have
semicolon-delimited path strings as their default value will cause each path
to be added to @ref{3e2,,sys.path}.  (Note that all known installers only use
HKLM, so HKCU is typically empty.)

@item 
If the environment variable 
@geindex PYTHONHOME
@geindex 環境變數; PYTHONHOME
@ref{3ee,,PYTHONHOME} is set, it is assumed as
"Python Home".  Otherwise, the path of the main Python executable is used to
locate a "landmark file" (either @code{Lib\os.py} or @code{pythonXY.zip}) to deduce
the "Python Home".  If a Python home is found, the relevant sub-directories
added to @ref{3e2,,sys.path} (@code{Lib}, @code{plat-win}, etc) are based on that
folder.  Otherwise, the core Python path is constructed from the PythonPath
stored in the registry.

@item 
If the Python Home cannot be located, no 
@geindex PYTHONPATH
@geindex 環境變數; PYTHONPATH
@ref{1218,,PYTHONPATH} is specified in
the environment, and no registry entries can be found, a default path with
relative entries is used (e.g. @code{.\Lib;.\plat-win}, etc).
@end itemize

If a @code{pyvenv.cfg} file is found alongside the main executable or in the
directory one level above the executable, the following variations apply:


@itemize *

@item 
If @code{home} is an absolute path and 
@geindex PYTHONHOME
@geindex 環境變數; PYTHONHOME
@ref{3ee,,PYTHONHOME} is not set, this
path is used instead of the path to the main executable when deducing the
home location.
@end itemize

最終這所有的結果為：


@itemize *

@item 
When running @code{python.exe}, or any other .exe in the main Python
directory (either an installed version, or directly from the PCbuild
directory), the core path is deduced, and the core paths in the registry are
ignored.  Other "application paths" in the registry are always read.

@item 
When Python is hosted in another .exe (different directory, embedded via COM,
etc), the "Python Home" will not be deduced, so the core path from the
registry is used.  Other "application paths" in the registry are always read.

@item 
If Python can't find its home and there are no registry value (frozen .exe,
some very strange installation setup) you get a path with some default, but
relative, paths.
@end itemize

For those who want to bundle Python into their application or distribution, the
following advice will prevent conflicts with other installations:


@itemize *

@item 
Include a @code{._pth} file alongside your executable containing the
directories to include. This will ignore paths listed in the registry and
environment variables, and also ignore @ref{cc,,site} unless @code{import site} is
listed.

@item 
If you are loading @code{python3.dll} or @code{python37.dll} in your own
executable, explicitly set @ref{63b,,PyConfig.module_search_paths} before
@ref{3f5,,Py_InitializeFromConfig()}.

@item 
Clear and/or overwrite 
@geindex PYTHONPATH
@geindex 環境變數; PYTHONPATH
@ref{1218,,PYTHONPATH} and set 
@geindex PYTHONHOME
@geindex 環境變數; PYTHONHOME
@ref{3ee,,PYTHONHOME}
before launching @code{python.exe} from your application.

@item 
If you cannot use the previous suggestions (for example, you are a
distribution that allows people to run @code{python.exe} directly), ensure
that the landmark file (@code{Lib\os.py}) exists in your install directory.
(Note that it will not be detected inside a ZIP file, but a correctly named
ZIP file will be detected instead.)
@end itemize

These will ensure that the files in a system-wide installation will not take
precedence over the copy of the standard library bundled with your application.
Otherwise, your users may experience problems using your application. Note that
the first suggestion is the best, as the others may still be susceptible to
non-standard paths in the registry and user site-packages.


在 3.6 版的變更: Add @code{._pth} file support and removes @code{applocal} option from
@code{pyvenv.cfg}.



在 3.6 版的變更: Add @code{python`XX'.zip} as a potential landmark when directly adjacent
to the executable.



在 3.6 版之後被棄用: Modules specified in the registry under @code{Modules} (not @code{PythonPath})
may be imported by @ref{f21,,importlib.machinery.WindowsRegistryFinder}.
This finder is enabled on Windows in 3.6.0 and earlier, but may need to
be explicitly added to @ref{f22,,sys.meta_path} in the future.


@node 額外的模組,編譯 Python 在 Windows,找尋模組,在 Windows 上使用 Python
@anchor{using/windows additional-modules}@anchor{20e3}
@subsection 額外的模組


Even though Python aims to be portable among all platforms, there are features
that are unique to Windows.  A couple of modules, both in the standard library
and external, and snippets exist to use these features.

The Windows-specific standard modules are documented in
@ref{20e4,,MS Windows 特有服務}.

@menu
* PyWin32:: 
* cx_Freeze:: 

@end menu

@node PyWin32,cx_Freeze,,額外的模組
@anchor{using/windows pywin32}@anchor{20e5}
@subsubsection PyWin32


The PyWin32@footnote{https://pypi.org/project/PyWin32/} module by Mark Hammond
is a collection of modules for advanced Windows-specific support.  This includes
utilities for:


@itemize *

@item 
Component Object Model@footnote{https://learn.microsoft.com/windows/win32/com/component-object-model--com--portal}
(COM)

@item 
Win32 API 呼叫

@item 
登錄檔（Registry）

@item 
事件日誌（Event log）

@item 
Microsoft Foundation Classes@footnote{https://learn.microsoft.com/cpp/mfc/mfc-desktop-applications}
(MFC) user interfaces
@end itemize

PythonWin@footnote{https://web.archive.org/web/20060524042422/https://www.python.org/windows/pythonwin/} is a sample MFC application
shipped with PyWin32.  It is an embeddable IDE with a built-in debugger.


@subsubheading 也參考



@table @asis

@item Win32 How Do I...?@footnote{https://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,額外的模組
@anchor{using/windows cx-freeze}@anchor{20e6}
@subsubsection cx_Freeze


cx_Freeze@footnote{https://cx-freeze.readthedocs.io/en/latest/}
wraps Python scripts into executable Windows programs
(@code{`*'.exe} files).  When you have done this, you can distribute your
application without requiring your users to install Python.

@node 編譯 Python 在 Windows,The full installer deprecated,額外的模組,在 Windows 上使用 Python
@anchor{using/windows compiling-python-on-windows}@anchor{20e7}
@subsection 編譯 Python 在 Windows


If you want to compile CPython yourself, first thing you should do is get the
source@footnote{https://www.python.org/downloads/source/}. You can download either the
latest release's source or just grab a fresh checkout@footnote{https://devguide.python.org/setup/#get-the-source-code}.

The source tree contains a build solution and project files for Microsoft
Visual Studio, which is the compiler used to build the official Python
releases. These files are in the @code{PCbuild} directory.

Check @code{PCbuild/readme.txt} for general information on the build process.

For extension modules, consult @ref{20e8,,建置 Windows 上的 C 和 C++ 擴充}.

@node The full installer deprecated,Python launcher for Windows deprecated,編譯 Python 在 Windows,在 Windows 上使用 Python
@anchor{using/windows the-full-installer-deprecated}@anchor{20e9}@anchor{using/windows windows-full}@anchor{20ea}
@subsection The full installer (deprecated)



在 3.14 版之後被棄用: This installer is deprecated since 3.14 and will not be produced for Python
3.16 or later. See @ref{20c3,,Python 安裝管理員} for the modern installer.


@menu
* 安裝步驟:: 
* Removing the MAX_PATH limitation: Removing the MAX_PATH limitation<2>. 
* 無使用者介面安裝:: 
* 無下載安裝:: 
* Modifying an install:: 
* Installing free-threaded binaries: Installing free-threaded binaries<2>. 

@end menu

@node 安裝步驟,Removing the MAX_PATH limitation<2>,,The full installer deprecated
@anchor{using/windows installation-steps}@anchor{20eb}
@subsubsection 安裝步驟


Four Python 3.14 installers are available for download - two each for the
32-bit and 64-bit versions of the interpreter. The `web installer' is a small
initial download, and it will automatically download the required components as
necessary. The `offline installer' includes the components necessary for a
default installation and only requires an internet connection for optional
features. See @ref{20ec,,無下載安裝} for other ways to avoid downloading
during installation.

After starting the installer, one of two options may be selected:

@image{python-figures/win_installer,,,,png}

如果你選擇「馬上安裝」：


@itemize *

@item 
You will `not' need to be an administrator (unless a system update for the
C Runtime Library is required or you install the @ref{7d3,,Python 安裝管理員} for all
users)

@item 
Python will be installed into your user directory

@item 
The @ref{7d3,,Python 安裝管理員} will be installed according to the option at the bottom
of the first page

@item 
The standard library, test suite, launcher and pip will be installed

@item 
如果選擇，安裝目錄將被加入到你的 
@geindex PATH
@geindex 環境變數; PATH
@code{PATH}

@item 
安裝捷徑將只能被目前使用者所看見
@end itemize

選擇「客製化安裝」將允許你選擇所需的項目進行安裝，安裝位置與其他選擇或安裝後的所需進行的動作。你將需要使用此選項「除錯特徵」或「二進位方式」進行安裝。

To perform an all-users installation, you should select "Customize
installation". In this case:


@itemize *

@item 
You may be required to provide administrative credentials or approval

@item 
Python will be installed into the Program Files directory

@item 
The @ref{7d3,,Python 安裝管理員} will be installed into the Windows directory

@item 
Optional features may be selected during installation

@item 
The standard library can be pre-compiled to bytecode

@item 
If selected, the install directory will be added to the system 
@geindex PATH
@geindex 環境變數; PATH
@code{PATH}

@item 
捷徑將被所有使用者所見
@end itemize

@node Removing the MAX_PATH limitation<2>,無使用者介面安裝,安裝步驟,The full installer deprecated
@anchor{using/windows id2}@anchor{20ed}
@subsubsection Removing the MAX_PATH limitation


Windows historically has limited path lengths to 260 characters. This meant that
paths longer than this would not resolve and errors would result.

In the latest versions of Windows, this limitation can be expanded to
approximately 32,000 characters. Your administrator will need to activate the
"Enable Win32 long paths" group policy, or set @code{LongPathsEnabled} to @code{1}
in the registry key
@code{HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem}.

This allows the @ref{315,,open()} function, the @ref{a5,,os} module and most other
path functionality to accept and return paths longer than 260 characters.

After changing the above option, no further configuration is required.


在 3.6 版的變更: Support for long paths was enabled in Python.


@node 無使用者介面安裝,無下載安裝,Removing the MAX_PATH limitation<2>,The full installer deprecated
@anchor{using/windows install-quiet-option}@anchor{7fd}@anchor{using/windows installing-without-ui}@anchor{20ee}
@subsubsection 無使用者介面安裝


All of the options available in the installer UI can also be specified from the
command line, allowing scripted installers to replicate an installation on many
machines without user interaction.  These options may also be set without
suppressing the UI in order to change some of the defaults.

The following options (found by executing the installer with @code{/?}) can be
passed into the installer:


@multitable {xxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

名稱

@tab

描述

@item

/passive

@tab

to display progress without requiring user interaction

@item

/quiet

@tab

to install/uninstall without displaying any UI

@item

/simple

@tab

to prevent user customization

@item

/uninstall

@tab

to remove Python (without confirmation)

@item

/layout [directory]

@tab

to pre-download all components

@item

/log [filename]

@tab

to specify log files location

@end multitable


All other options are passed as @code{name=value}, where the value is usually
@code{0} to disable a feature, @code{1} to enable a feature, or a path. The full list
of available options is shown below.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

名稱

@tab

描述

@tab

預設

@item

InstallAllUsers

@tab

Perform a system-wide installation.

@tab

0

@item

TargetDir

@tab

安裝目錄

@tab

Selected based on
InstallAllUsers

@item

DefaultAllUsersTargetDir

@tab

The default installation directory
for all-user installs

@tab

@code{%ProgramFiles%\Python X.Y} 或 @code{%ProgramFiles(x86)%\Python X.Y}

@item

DefaultJustForMeTargetDir

@tab

預設安裝目錄給 只有給我  安裝方式

@tab

@code{%LocalAppData%\Programs\Python\PythonXY} 或 @code{%LocalAppData%\Programs\Python\PythonXY-32} 或 @code{%LocalAppData%\Programs\Python\PythonXY-64}

@item

DefaultCustomTargetDir

@tab

The default custom install directory
displayed in the UI

@tab

(empty)

@item

AssociateFiles

@tab

當執行程序也被安裝時創造檔案關聯

@tab

1

@item

CompileAll

@tab

編譯所有 @code{.py} 檔案為 @code{.pyc}。

@tab

0

@item

PrependPath

@tab

Prepend install and Scripts
directories  to 
@geindex PATH
@geindex 環境變數; PATH
@code{PATH} and
add @code{.PY} to 
@geindex PATHEXT
@geindex 環境變數; PATHEXT
@code{PATHEXT}

@tab

0

@item

AppendPath

@tab

Append install and Scripts
directories  to 
@geindex PATH
@geindex 環境變數; PATH
@code{PATH} and
add @code{.PY} to 
@geindex PATHEXT
@geindex 環境變數; PATHEXT
@code{PATHEXT}

@tab

0

@item

Shortcuts

@tab

Create shortcuts for the interpreter,
documentation and IDLE if installed.

@tab

1

@item

Include_doc

@tab

安裝Python文件

@tab

1

@item

Include_debug

@tab

Install debug binaries

@tab

0

@item

Include_dev

@tab

Install developer headers and
libraries. Omitting this may lead to
an unusable installation.

@tab

1

@item

Include_exe

@tab

Install @code{python.exe} and
related files. Omitting this may
lead to an unusable installation.

@tab

1

@item

Include_launcher

@tab

安裝 @ref{7d3,,Python 安裝管理員}。

@tab

1

@item

InstallLauncherAllUsers

@tab

Installs the launcher for all
users. Also requires
@code{Include_launcher} to be set to 1

@tab

1

@item

Include_lib

@tab

Install standard library and
extension modules. Omitting this may
lead to an unusable installation.

@tab

1

@item

Include_pip

@tab

Install bundled pip and setuptools

@tab

1

@item

Include_symbols

@tab

Install debugging symbols (@code{*.pdb})

@tab

0

@item

Include_tcltk

@tab

Install Tcl/Tk support and IDLE

@tab

1

@item

Include_test

@tab

Install standard library test suite

@tab

1

@item

Include_tools

@tab

Install utility scripts

@tab

1

@item

LauncherOnly

@tab

Only installs the launcher. This
will override most other options.

@tab

0

@item

SimpleInstall

@tab

Disable most install UI

@tab

0

@item

SimpleInstallDescription

@tab

A custom message to display when the
simplified install UI is used.

@tab

(empty)

@end multitable


For example, to silently install a default, system-wide Python installation,
you could use the following command (from an elevated command prompt):

@example
python-3.9.0.exe /quiet InstallAllUsers=1 PrependPath=1 Include_test=0
@end example

To allow users to easily install a personal copy of Python without the test
suite, you could provide a shortcut with the following command. This will
display a simplified initial page and disallow customization:

@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

(Note that omitting the launcher also omits file associations, and is only
recommended for per-user installs when there is also a system-wide installation
that included the launcher.)

The options listed above can also be provided in a file named @code{unattend.xml}
alongside the executable. This file specifies a list of options and values.
When a value is provided as an attribute, it will be converted to a number if
possible. Values provided as element text are always left as strings. This
example file sets the same options as the previous example:

@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 無下載安裝,Modifying an install,無使用者介面安裝,The full installer deprecated
@anchor{using/windows install-layout-option}@anchor{20ec}@anchor{using/windows installing-without-downloading}@anchor{20ef}
@subsubsection 無下載安裝


As some features of Python are not included in the initial installer download,
selecting those features may require an internet connection.  To avoid this
need, all possible components may be downloaded on-demand to create a complete
`layout' that will no longer require an internet connection regardless of the
selected features. Note that this download may be bigger than required, but
where a large number of installations are going to be performed it is very
useful to have a locally cached copy.

Execute the following command from Command Prompt to download all possible
required files.  Remember to substitute @code{python-3.9.0.exe} for the actual
name of your installer, and to create layouts in their own directories to
avoid collisions between files with the same name.

@example
python-3.9.0.exe /layout [optional target directory]
@end example

You may also specify the @code{/quiet} option to hide the progress display.

@node Modifying an install,Installing free-threaded binaries<2>,無下載安裝,The full installer deprecated
@anchor{using/windows modifying-an-install}@anchor{20f0}
@subsubsection Modifying an install


Once Python has been installed, you can add or remove features through the
Programs and Features tool that is part of Windows. Select the Python entry and
choose "Uninstall/Change" to open the installer in maintenance mode.

"Modify" allows you to add or remove features by modifying the checkboxes -
unchanged checkboxes will not install or remove anything. Some options cannot be
changed in this mode, such as the install directory; to modify these, you will
need to remove and then reinstall Python completely.

"Repair" will verify all the files that should be installed using the current
settings and replace any that have been removed or modified.

"Uninstall" will remove Python entirely, with the exception of the
@ref{7d3,,Python 安裝管理員}, which has its own entry in Programs and Features.

@node Installing free-threaded binaries<2>,,Modifying an install,The full installer deprecated
@anchor{using/windows id3}@anchor{20f1}
@subsubsection Installing free-threaded binaries



在 3.13 版被加入.


To install pre-built binaries with free-threading enabled (see 
@geindex Python Enhancement Proposals; PEP 703
PEP 703@footnote{https://peps.python.org/pep-0703/}), you
should select "Customize installation". The second page of options includes the
"Download free-threaded binaries" checkbox.

@image{python-figures/win_install_freethreaded,,,,png}

Selecting this option will download and install additional binaries to the same
location as the main Python install. The main executable is called
@code{python3.13t.exe}, and other binaries either receive a @code{t} suffix or a full
ABI suffix. Python source files and bundled third-party dependencies are shared
with the main install.

The free-threaded version is registered as a regular Python install with the
tag @code{3.13t} (with a @code{-32} or @code{-arm64} suffix as normal for those
platforms). This allows tools to discover it, and for the @ref{7d3,,Python 安裝管理員} to
support @code{py.exe -3.13t}. Note that the launcher will interpret @code{py.exe -3}
(or a @code{python3} shebang) as "the latest 3.x install", which will prefer the
free-threaded binaries over the regular ones, while @code{py.exe -3.13} will not.
If you use the short style of option, you may prefer to not install the
free-threaded binaries at this time.

To specify the install option at the command line, use
@code{Include_freethreaded=1}. See @ref{20ec,,無下載安裝} for instructions on
pre-emptively downloading the additional binaries for offline install. The
options to include debug symbols and binaries also apply to the free-threaded
builds.

Free-threaded binaries are also available @ref{20c1,,on nuget.org}.

@node Python launcher for Windows deprecated,,The full installer deprecated,在 Windows 上使用 Python
@anchor{using/windows python-launcher-for-windows-deprecated}@anchor{20f2}
@subsection Python launcher for Windows (deprecated)



在 3.14 版之後被棄用: The launcher and this documentation have been superseded by the Python
Install Manager described above. This is preserved temporarily for historical
interest.



在 3.3 版被加入.


The Python launcher for Windows is a utility which aids in locating and
executing of different Python versions.  It allows scripts (or the
command-line) to indicate a preference for a specific Python version, and
will locate and execute that version.

Unlike the 
@geindex PATH
@geindex 環境變數; PATH
@code{PATH} variable, the launcher will correctly select the most
appropriate version of Python. It will prefer per-user installations over
system-wide ones, and orders by language version rather than using the most
recently installed version.

The launcher was originally specified in 
@geindex Python Enhancement Proposals; PEP 397
PEP 397@footnote{https://peps.python.org/pep-0397/}.

@menu
* 開始:: 
* Shebang lines: Shebang lines<2>. 
* Arguments in shebang lines:: 
* Customization:: 
* Diagnostics:: 
* Dry run:: 
* 安裝隨選:: 
* Return codes:: 

@end menu

@node 開始,Shebang lines<2>,,Python launcher for Windows deprecated
@anchor{using/windows getting-started}@anchor{20f3}
@subsubsection 開始


@menu
* From the command-line:: 
* 虛擬環境（Virtual environment）:: 
* From a script:: 
* 從檔案關聯:: 

@end menu

@node From the command-line,虛擬環境（Virtual environment）,,開始
@anchor{using/windows from-the-command-line}@anchor{20f4}
@subsubsection From the command-line



在 3.6 版的變更.


System-wide installations of Python 3.3 and later will put the launcher on your
@geindex PATH
@geindex 環境變數; PATH
@code{PATH}. The launcher is compatible with all available versions of
Python, so it does not matter which version is installed. To check that the
launcher is available, execute the following command in Command Prompt:

@example
py
@end example

You should find that the latest version of Python you have installed is
started - it can be exited as normal, and any additional command-line
arguments specified will be sent directly to Python.

If you have multiple versions of Python installed (e.g., 3.7 and 3.14) you
will have noticed that Python 3.14 was started - to launch Python 3.7, try
the command:

@example
py -3.7
@end example

If you want the latest version of Python 2 you have installed, try the
command:

@example
py -2
@end example

If you see the following error, you do not have the launcher installed:

@example
'py' is not recognized as an internal or external command,
operable program or batch file.
@end example

指令：

@example
py --list
@end example

displays the currently installed version(s) of Python.

The @code{-x.y} argument is the short form of the @code{-V:Company/Tag} argument,
which allows selecting a specific Python runtime, including those that may have
come from somewhere other than python.org. Any runtime registered by following
@geindex Python Enhancement Proposals; PEP 514
PEP 514@footnote{https://peps.python.org/pep-0514/} will be discoverable. The @code{--list} command lists all available
runtimes using the @code{-V:} format.

When using the @code{-V:} argument, specifying the Company will limit selection to
runtimes from that provider, while specifying only the Tag will select from all
providers. Note that omitting the slash implies a tag:

@example
# Select any '3.*' tagged runtime
py -V:3

# Select any 'PythonCore' released runtime
py -V:PythonCore/

# Select PythonCore's latest Python 3 runtime
py -V:PythonCore/3
@end example

The short form of the argument (@code{-3}) only ever selects from core Python
releases, and not other distributions. However, the longer form (@code{-V:3}) will
select from any.

The Company is matched on the full string, case-insensitive. The Tag is matched
on either the full string, or a prefix, provided the next character is a dot or a
hyphen. This allows @code{-V:3.1} to match @code{3.1-32}, but not @code{3.10}. Tags are
sorted using numerical ordering (@code{3.10} is newer than @code{3.1}), but are
compared using text (@code{-V:3.01} does not match @code{3.1}).

@node 虛擬環境（Virtual environment）,From a script,From the command-line,開始
@anchor{using/windows virtual-environments}@anchor{20f5}
@subsubsection 虛擬環境（Virtual environment）



在 3.5 版被加入.


If the launcher is run with no explicit Python version specification, and a
virtual environment (created with the standard library @ref{117,,venv} module or
the external @code{virtualenv} tool) active, the launcher will run the virtual
environment's interpreter rather than the global one.  To run the global
interpreter, either deactivate the virtual environment, or explicitly specify
the global Python version.

@node From a script,從檔案關聯,虛擬環境（Virtual environment）,開始
@anchor{using/windows from-a-script}@anchor{20f6}
@subsubsection From a script


Let's create a test Python script - create a file called @code{hello.py} with the
following contents

@example
#! python
import sys
sys.stdout.write("hello from Python %s\n" % (sys.version,))
@end example

From the directory in which hello.py lives, execute the command:

@example
py hello.py
@end example

You should notice the version number of your latest Python 2.x installation
is printed.  Now try changing the first line to be:

@example
#! python3
@end example

Re-executing the command should now print the latest Python 3.x information.
As with the above command-line examples, you can specify a more explicit
version qualifier.  Assuming you have Python 3.7 installed, try changing
the first line to @code{#! python3.7} and you should find the 3.7
version information printed.

Note that unlike interactive use, a bare "python" will use the latest
version of Python 2.x that you have installed.  This is for backward
compatibility and for compatibility with Unix, where the command @code{python}
typically refers to Python 2.

@node 從檔案關聯,,From a script,開始
@anchor{using/windows from-file-associations}@anchor{20f7}
@subsubsection 從檔案關聯


The launcher should have been associated with Python files (i.e. @code{.py},
@code{.pyw}, @code{.pyc} files) when it was installed.  This means that
when you double-click on one of these files from Windows explorer the launcher
will be used, and therefore you can use the same facilities described above to
have the script specify the version which should be used.

The key benefit of this is that a single launcher can support multiple Python
versions at the same time depending on the contents of the first line.

@node Shebang lines<2>,Arguments in shebang lines,開始,Python launcher for Windows deprecated
@anchor{using/windows id4}@anchor{20f8}
@subsubsection Shebang lines


If the first line of a script file starts with @code{#!}, it is known as a
"shebang" line.  Linux and other Unix like operating systems have native
support for such lines and they are commonly used on such systems to indicate
how a script should be executed.  This launcher allows the same facilities to
be used with Python scripts on Windows and the examples above demonstrate their
use.

To allow shebang lines in Python scripts to be portable between Unix and
Windows, this launcher supports a number of 'virtual' commands to specify
which interpreter to use.  The supported virtual commands are:


@itemize *

@item 
@code{/usr/bin/env}

@item 
@code{/usr/bin/python}

@item 
@code{/usr/local/bin/python}

@item 
@code{python}
@end itemize

For example, if the first line of your script starts with

@example
#! /usr/bin/python
@end example

The default Python or an active virtual environment will be located and used.
As many Python scripts written to work on Unix will already have this line,
you should find these scripts can be used by the launcher without modification.
If you are writing a new script on Windows which you hope will be useful on
Unix, you should use one of the shebang lines starting with @code{/usr}.

Any of the above virtual commands can be suffixed with an explicit version
(either just the major version, or the major and minor version).
Furthermore the 32-bit version can be requested by adding "-32" after the
minor version. I.e. @code{/usr/bin/python3.7-32} will request usage of the
32-bit Python 3.7. If a virtual environment is active, the version will be
ignored and the environment will be used.


在 3.7 版被加入: Beginning with python launcher 3.7 it is possible to request 64-bit version
by the "-64" suffix. Furthermore it is possible to specify a major and
architecture without minor (i.e. @code{/usr/bin/python3-64}).



在 3.11 版的變更: The "-64" suffix is deprecated, and now implies "any architecture that is
not provably i386/32-bit". To request a specific environment, use the new
@code{-V:@var{TAG}} argument with the complete tag.



在 3.13 版的變更: Virtual commands referencing @code{python} now prefer an active virtual
environment rather than searching 
@geindex PATH
@geindex 環境變數; PATH
@code{PATH}. This handles cases where
the shebang specifies @code{/usr/bin/env python3} but @code{python3.exe} is
not present in the active environment.


The @code{/usr/bin/env} form of shebang line has one further special property.
Before looking for installed Python interpreters, this form will search the
executable 
@geindex PATH
@geindex 環境變數; PATH
@code{PATH} for a Python executable matching the name provided
as the first argument. This corresponds to the behaviour of the Unix @code{env}
program, which performs a 
@geindex PATH
@geindex 環境變數; PATH
@code{PATH} search.
If an executable matching the first argument after the @code{env} command cannot
be found, but the argument starts with @code{python}, it will be handled as
described for the other virtual commands.
The environment variable @code{PYLAUNCHER_NO_SEARCH_PATH} may be set
(to any value) to skip this search of 
@geindex PATH
@geindex 環境變數; PATH
@code{PATH}.

Shebang lines that do not match any of these patterns are looked up in the
@code{[commands]} section of the launcher's @ref{20f9,,.INI file}.
This may be used to handle certain commands in a way that makes sense for your
system. The name of the command must be a single argument (no spaces in the
shebang executable), and the value substituted is the full path to the
executable (additional arguments specified in the .INI will be quoted as part
of the filename).

@example
[commands]
/bin/xpython=C:\Program Files\XPython\python.exe
@end example

Any commands not found in the .INI file are treated as `Windows' executable
paths that are absolute or relative to the directory containing the script file.
This is a convenience for Windows-only scripts, such as those generated by an
installer, since the behavior is not compatible with Unix-style shells.
These paths may be quoted, and may include multiple arguments, after which the
path to the script and any additional arguments will be appended.

@node Arguments in shebang lines,Customization,Shebang lines<2>,Python launcher for Windows deprecated
@anchor{using/windows arguments-in-shebang-lines}@anchor{20fa}
@subsubsection Arguments in shebang lines


The shebang lines can also specify additional options to be passed to the
Python interpreter.  For example, if you have a shebang line:

@example
#! /usr/bin/python -v
@end example

Then Python will be started with the @code{-v} option

@node Customization,Diagnostics,Arguments in shebang lines,Python launcher for Windows deprecated
@anchor{using/windows customization}@anchor{20fb}
@subsubsection Customization


@menu
* Customization via INI files:: 
* Customizing default Python versions:: 

@end menu

@node Customization via INI files,Customizing default Python versions,,Customization
@anchor{using/windows customization-via-ini-files}@anchor{20fc}@anchor{using/windows launcher-ini}@anchor{20f9}
@subsubsection Customization via INI files


Two .ini files will be searched by the launcher - @code{py.ini} in the current
user's application data directory (@code{%LOCALAPPDATA%} or @code{$env:LocalAppData})
and @code{py.ini} in the same directory as the launcher. The same .ini files are
used for both the 'console' version of the launcher (i.e. py.exe) and for the
'windows' version (i.e. pyw.exe).

Customization specified in the "application directory" will have precedence over
the one next to the executable, so a user, who may not have write access to the
.ini file next to the launcher, can override commands in that global .ini file.

@node Customizing default Python versions,,Customization via INI files,Customization
@anchor{using/windows customizing-default-python-versions}@anchor{20fd}
@subsubsection Customizing default Python versions


In some cases, a version qualifier can be included in a command to dictate
which version of Python will be used by the command. A version qualifier
starts with a major version number and can optionally be followed by a period
('.') and a minor version specifier. Furthermore it is possible to specify
if a 32 or 64 bit implementation shall be requested by adding "-32" or "-64".

For example, a shebang line of @code{#!python} has no version qualifier, while
@code{#!python3} has a version qualifier which specifies only a major version.

If no version qualifiers are found in a command, the environment
variable @code{PY_PYTHON} can be set to specify the default version
qualifier. If it is not set, the default is "3". The variable can
specify any value that may be passed on the command line, such as "3",
"3.7", "3.7-32" or "3.7-64". (Note that the "-64" option is only
available with the launcher included with Python 3.7 or newer.)

If no minor version qualifiers are found, the environment variable
@code{PY_PYTHON@{major@}} (where @code{@{major@}} is the current major version qualifier
as determined above) can be set to specify the full version. If no such option
is found, the launcher will enumerate the installed Python versions and use
the latest minor release found for the major version, which is likely,
although not guaranteed, to be the most recently installed version in that
family.

On 64-bit Windows with both 32-bit and 64-bit implementations of the same
(major.minor) Python version installed, the 64-bit version will always be
preferred. This will be true for both 32-bit and 64-bit implementations of the
launcher - a 32-bit launcher will prefer to execute a 64-bit Python installation
of the specified version if available. This is so the behavior of the launcher
can be predicted knowing only what versions are installed on the PC and
without regard to the order in which they were installed (i.e., without knowing
whether a 32 or 64-bit version of Python and corresponding launcher was
installed last). As noted above, an optional "-32" or "-64" suffix can be
used on a version specifier to change this behaviour.

範例：


@itemize *

@item 
If no relevant options are set, the commands @code{python} and
@code{python2} will use the latest Python 2.x version installed and
the command @code{python3} will use the latest Python 3.x installed.

@item 
The command @code{python3.7} will not consult any
options at all as the versions are fully specified.

@item 
If @code{PY_PYTHON=3}, the commands @code{python} and @code{python3} will both use
the latest installed Python 3 version.

@item 
If @code{PY_PYTHON=3.7-32}, the command @code{python} will use the 32-bit
implementation of 3.7 whereas the command @code{python3} will use the latest
installed Python (PY_PYTHON was not considered at all as a major
version was specified.)

@item 
If @code{PY_PYTHON=3} and @code{PY_PYTHON3=3.7}, the commands
@code{python} and @code{python3} will both use specifically 3.7
@end itemize

In addition to environment variables, the same settings can be configured
in the .INI file used by the launcher.  The section in the INI file is
called @code{[defaults]} and the key name will be the same as the
environment variables without the leading @code{PY_} prefix (and note that
the key names in the INI file are case insensitive.)  The contents of
an environment variable will override things specified in the INI file.

舉例來說：


@itemize *

@item 
Setting @code{PY_PYTHON=3.7} is equivalent to the INI file containing:
@end itemize

@example
[defaults]
python=3.7
@end example


@itemize *

@item 
Setting @code{PY_PYTHON=3} and @code{PY_PYTHON3=3.7} is equivalent to the INI file
containing:
@end itemize

@example
[defaults]
python=3
python3=3.7
@end example

@node Diagnostics,Dry run,Customization,Python launcher for Windows deprecated
@anchor{using/windows diagnostics}@anchor{20fe}
@subsubsection Diagnostics


If an environment variable @code{PYLAUNCHER_DEBUG} is set (to any value), the
launcher will print diagnostic information to stderr (i.e. to the console).
While this information manages to be simultaneously verbose `and' terse, it
should allow you to see what versions of Python were located, why a
particular version was chosen and the exact command-line used to execute the
target Python. It is primarily intended for testing and debugging.

@node Dry run,安裝隨選,Diagnostics,Python launcher for Windows deprecated
@anchor{using/windows dry-run}@anchor{20ff}
@subsubsection Dry run


If an environment variable @code{PYLAUNCHER_DRYRUN} is set (to any value),
the launcher will output the command it would have run, but will not actually
launch Python. This may be useful for tools that want to use the launcher to
detect and then launch Python directly. Note that the command written to
standard output is always encoded using UTF-8, and may not render correctly in
the console.

@node 安裝隨選,Return codes,Dry run,Python launcher for Windows deprecated
@anchor{using/windows install-on-demand}@anchor{2100}
@subsubsection 安裝隨選


If an environment variable @code{PYLAUNCHER_ALLOW_INSTALL} is set (to any
value), and the requested Python version is not installed but is available on
the Microsoft Store, the launcher will attempt to install it. This may require
user interaction to complete, and you may need to run the command again.

An additional @code{PYLAUNCHER_ALWAYS_INSTALL} variable causes the launcher
to always try to install Python, even if it is detected. This is mainly intended
for testing (and should be used with @code{PYLAUNCHER_DRYRUN}).

@node Return codes,,安裝隨選,Python launcher for Windows deprecated
@anchor{using/windows return-codes}@anchor{2101}
@subsubsection Return codes


The following exit codes may be returned by the Python launcher. Unfortunately,
there is no way to distinguish these from the exit code of Python itself.

The names of codes are as used in the sources, and are only for reference. There
is no way to access or resolve them apart from reading this page. Entries are
listed in alphabetical order of names.


@multitable {xxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

名稱

@tab

Value

@tab

描述

@item

RC_BAD_VENV_CFG

@tab

107

@tab

A @code{pyvenv.cfg} was found but is corrupt.

@item

RC_CREATE_PROCESS

@tab

101

@tab

Failed to launch Python.

@item

RC_INSTALLING

@tab

111

@tab

An install was started, but the command will
need to be re-run after it completes.

@item

RC_INTERNAL_ERROR

@tab

109

@tab

Unexpected error. Please report a bug.

@item

RC_NO_COMMANDLINE

@tab

108

@tab

Unable to obtain command line from the
operating system.

@item

RC_NO_PYTHON

@tab

103

@tab

Unable to locate the requested version.

@item

RC_NO_VENV_CFG

@tab

106

@tab

A @code{pyvenv.cfg} was required but not
found.

@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 於 macOS 使用 Python,在 Android 上使用 Python,在 Windows 上使用 Python,Python 的設置與使用
@anchor{using/mac doc}@anchor{2102}@anchor{using/mac translation-repo}@anchor{2103}@anchor{using/mac using-on-mac}@anchor{2104}@anchor{using/mac using-python-on-macos}@anchor{2105}
@section 於 macOS 使用 Python


This document aims to give an overview of macOS-specific behavior you should
know about to get started with Python on Mac computers.
Python on a Mac running macOS is very similar to Python on other Unix-derived platforms,
but there are some differences in installation and some features.

There are various ways to obtain and install Python for macOS.
Pre-built versions of the most recent versions of Python are available
from a number of distributors. Much of this document describes use of
the Pythons provided by the CPython release team for download from
the python.org website@footnote{https://www.python.org/downloads/}. See
@ref{2106,,Alternative Distributions} for some other options.
@anchor{using/mac getting-osx}@anchor{2107}
@menu
* Using Python for macOS from python.org: Using Python for macOS from python org. 
* Alternative Distributions:: 
* 安裝額外的 Python 套件:: 
* 開發 GUI 程式:: 
* 進階主題:: 
* 其他資源:: 

@end menu

@node Using Python for macOS from python org,Alternative Distributions,,於 macOS 使用 Python
@anchor{using/mac getting-and-installing-macpython}@anchor{2108}@anchor{using/mac using-python-for-macos-from-python-org}@anchor{2109}
@subsection Using Python for macOS from @code{python.org}


@menu
* 安裝步驟: 安裝步驟<2>. 
* 如何執行 Python 腳本:: 

@end menu

@node 安裝步驟<2>,如何執行 Python 腳本,,Using Python for macOS from python org
@anchor{using/mac installation-steps}@anchor{210a}
@subsubsection 安裝步驟


For current Python versions@footnote{https://www.python.org/downloads/}
(other than those in @code{security} status), the release team produces a
`Python for macOS' installer package for each new release.
A list of available installers
is available here@footnote{https://www.python.org/downloads/macos/}.
We recommend using the most recent supported Python version where possible.
Current installers provide a
universal2 binary@footnote{https://en.wikipedia.org/wiki/Universal_binary} build
of Python which runs natively on all Macs (Apple Silicon and Intel) that are
supported by a wide range of macOS versions,
currently typically from at least `macOS 10.15 Catalina' on.

The downloaded file is a standard macOS installer package file (@code{.pkg}).
File integrity information (checksum, size, sigstore signature, etc) for each file is included
on the release download page. Installer packages and their contents are signed and notarized
with @code{Python Software Foundation} Apple Developer ID certificates
to meet macOS Gatekeeper requirements@footnote{https://support.apple.com/en-us/102445}.

For a default installation, double-click on the downloaded installer package file.
This should launch the standard macOS Installer app and display the first of several
installer windows steps.

@image{python-figures/mac_installer_01_introduction,,,,png}

Clicking on the `Continue' button brings up the `Read Me' for this installer.
Besides other important information, the `Read Me' documents which Python version is
going to be installed and on what versions of macOS it is supported. You may need
to scroll through to read the whole file. By default, this `Read Me' will also be
installed in @code{/Applications/Python 3.14/} and available to read anytime.

@image{python-figures/mac_installer_02_readme,,,,png}

Clicking on `Continue' proceeds to display the license for Python and for
other included software. You will then need to `Agree' to the license terms
before proceeding to the next step. This license file will also be installed
and available to be read later.

@image{python-figures/mac_installer_03_license,,,,png}

After the license terms are accepted, the next step is the `Installation Type'
display. For most uses, the standard set of installation operations is appropriate.

@image{python-figures/mac_installer_04_installation_type,,,,png}

By pressing the `Customize' button, you can choose to omit or select certain package
components of the installer. Click on each package name to see a description of
what it installs.
To also install support for the optional free-threaded feature,
see @ref{493,,Installing Free-threaded Binaries}.

@image{python-figures/mac_installer_05_custom_install,,,,png}

In either case, clicking `Install' will begin the install process by asking
permission to install new software. A macOS user name with @code{Administrator} privilege
is needed as the installed Python will be available to all users of the Mac.

When the installation is complete, the `Summary' window will appear.

@image{python-figures/mac_installer_06_summary,,,,png}

Double-click on the @code{Install Certificates.command}
icon or file in the @code{/Applications/Python 3.14/} window to complete the
installation.

@image{python-figures/mac_installer_07_applications,,,,png}

This will open a temporary @code{Terminal} shell window that
will use the new Python to download and install SSL root certificates
for its use.

@image{python-figures/mac_installer_08_install_certificates,,,,png}

If @code{Successfully installed certifi} and @code{update complete} appears
in the terminal window, the installation is complete.
Close this terminal window and the installer window.

預設安裝會包含：


@itemize *

@item 
會有一個 @code{Python 3.14} 資料夾在你的 @code{Applications} 資料夾中。在這裡你可以找到 @code{IDLE}，它是作為官方 Python 發行版標準組成的開發環境；以及 @code{Python Launcher}，它負責處理在 Finder@footnote{https://support.apple.com/en-us/HT201732} 中雙擊 Python 腳本的操作。

@item 
@code{/Library/Frameworks/Python.framework} 框架，包括 Python 可執行檔案 (executable) 和函式庫 (library)。安裝程式將此位置新增到 shell 路徑。要解除安裝 Python ，你可以移除這三個東西。Python 可執行檔案的符號連結 (symlink) 則放在 @code{/usr/local/bin/} 中。
@end itemize

@cartouche
@quotation 備註 
Recent versions of macOS include a @code{python3} command in @code{/usr/bin/python3}
that links to a usually older and incomplete version of Python provided by and for use by
the Apple development tools, @code{Xcode} or the @code{Command Line Tools for Xcode}.
You should never modify or attempt to delete this installation, as it is
Apple-controlled and is used by Apple-provided or third-party software.  If
you choose to install a newer Python version from @code{python.org}, you will have
two different but functional Python installations on your computer that
can co-exist. The default installer options should ensure that its @code{python3}
will be used instead of the system @code{python3}.
@end quotation
@end cartouche

@node 如何執行 Python 腳本,,安裝步驟<2>,Using Python for macOS from python org
@anchor{using/mac how-to-run-a-python-script}@anchor{210b}
@subsubsection 如何執行 Python 腳本


There are two ways to invoke the Python interpreter.
If you are familiar with using a Unix shell in a terminal
window, you can invoke @code{python3.14} or @code{python3} optionally
followed by one or more command line options (described in @ref{1c70,,命令列與環境}).
The Python tutorial also has a useful section on
@ref{48f,,using Python interactively from a shell}.

You can also invoke the interpreter through an integrated
development environment.
@ref{1210,,IDLE --- Python 編輯器與 shell} is a basic editor and interpreter environment
which is included with the standard distribution of Python.
@code{IDLE} includes a Help menu that allows you to access Python documentation. If you
are completely new to Python, you can read the tutorial introduction
in that document.

There are many other editors and IDEs available, see @ref{210c,,編輯器與 IDE}
for more information.

To run a Python script file from the terminal window, you can
invoke the interpreter with the name of the script file:

@quotation

@code{python3.14} @code{myscript.py}
@end quotation

從 Finder 執行你的腳本時，你可以：


@itemize *

@item 
把它拖曳到 @code{Python Launcher}

@item 
透過 Finder Info 視窗選擇 @code{Python Launcher} 作為開啟腳本（或任何 @code{.py} 腳本）的預設應用程式，然後雙擊腳本。@code{Python Launcher} 有各種用來控制腳本啟動方式的選項。拖曳選項可以讓你一次更改多個選項，或使用其 @code{Preferences} 選單以全域性地更改內容。
@end itemize

Be aware that running the script directly from the macOS Finder might
produce different results than when running from a terminal window as
the script will not be run in the usual shell environment including
any setting of environment variables in shell profiles.
And, as with any other script or program,
be certain of what you are about to run.

@node Alternative Distributions,安裝額外的 Python 套件,Using Python for macOS from python org,於 macOS 使用 Python
@anchor{using/mac alternative-bundles}@anchor{2106}@anchor{using/mac alternative-distributions}@anchor{210d}
@subsection Alternative Distributions


Besides the standard @code{python.org} for macOS installer, there are third-party
distributions for macOS that may include additional functionality.
Some popular distributions and their key features:


@table @asis

@item ActivePython@footnote{https://www.activestate.com/products/python/}

Installer with multi-platform compatibility, documentation

@item Anaconda@footnote{https://www.anaconda.com/download/}

Popular scientific modules (such as numpy, scipy, and pandas) and the
@code{conda} package manager.

@item Homebrew@footnote{https://brew.sh}

Package manager for macOS including multiple versions of Python and many
third-party Python-based packages (including numpy, scipy, and pandas).

@item MacPorts@footnote{https://www.macports.org}

Another package manager for macOS including multiple versions of Python and many
third-party Python-based packages. May include pre-built versions of Python and
many packages for older versions of macOS.
@end table

Note that distributions might not include the latest versions of Python or
other libraries, and are not maintained or supported by the core Python team.

@node 安裝額外的 Python 套件,開發 GUI 程式,Alternative Distributions,於 macOS 使用 Python
@anchor{using/mac installing-additional-python-packages}@anchor{210e}@anchor{using/mac mac-package-manager}@anchor{210f}
@subsection 安裝額外的 Python 套件


更多資訊請見 Python Packaging User Guide@footnote{https://packaging.python.org/en/latest/tutorials/installing-packages/}。
@anchor{using/mac osx-gui-scripts}@anchor{2110}
@node 開發 GUI 程式,進階主題,安裝額外的 Python 套件,於 macOS 使用 Python
@anchor{using/mac gui-programming}@anchor{2111}@anchor{using/mac gui-programming-on-the-mac}@anchor{2112}
@subsection 開發 GUI 程式


於 Mac 上使用 Python 來建立 GUI 應用程式有許多選項。

標準的 Python GUI 工具套件是基於跨平臺 Tk 工具套件 (@indicateurl{https://www.tcl.tk}) 的 @ref{f6,,tkinter}。macOS 原生版本的 Tk 有包含於安裝程式中。

`PyObjC' 是一個 Apple Objective-C/Cocoa 框架的 Python 繫結 (binding)。有關 PyObjC 的資訊請見 pyobjc@footnote{https://pypi.org/project/pyobjc/}。

有許多替代 macOS GUI 工具套件可用，包含：


@itemize *

@item 
PySide@footnote{https://www.qt.io/qt-for-python}：Qt GUI 工具包@footnote{https://wiki.qt.io/Qt_for_Python}的官方 Python 繫結。

@item 
PyQt@footnote{https://riverbankcomputing.com/software/pyqt/}：Qt 的替代 Python 繫結。

@item 
Kivy@footnote{https://kivy.org}：一個支援桌面和行動平臺的跨平臺 GUI 工具包。

@item 
Toga@footnote{https://toga.readthedocs.io}：BeeWare 專案@footnote{https://beeware.org}的一部分；支援桌面、行動、網頁和控制台應用程式。

@item 
wxPython@footnote{https://wxpython.org}：一個支援桌面作業系統的跨平臺工具包。
@end itemize

@node 進階主題,其他資源,開發 GUI 程式,於 macOS 使用 Python
@anchor{using/mac advanced-topics}@anchor{2113}
@subsection 進階主題


@menu
* Installing Free-threaded Binaries:: 
* 使用命令列安裝:: 
* 發行 Python 應用程式:: 
* App Store Compliance:: 

@end menu

@node Installing Free-threaded Binaries,使用命令列安裝,,進階主題
@anchor{using/mac install-freethreaded-macos}@anchor{493}@anchor{using/mac installing-free-threaded-binaries}@anchor{2114}
@subsubsection Installing Free-threaded Binaries



在 3.13 版被加入.


The @code{python.org} @ref{2108,,Python for macOS}
installer package can optionally install an additional build of
Python 3.14 that supports 
@geindex Python Enhancement Proposals; PEP 703
PEP 703@footnote{https://peps.python.org/pep-0703/}, the free-threading feature
(running with the @ref{46e,,global interpreter lock} disabled).
Check the release page on @code{python.org} for possible updated information.

The free-threaded mode is working and continues to be improved, but
there is some additional overhead in single-threaded workloads compared
to the regular build. Additionally, third-party packages, in particular ones
with an @ref{2115,,extension module}, may not be ready for use in a
free-threaded build, and will re-enable the @ref{164,,GIL}.
Therefore, the support for free-threading
is not installed by default. It is packaged as a separate install option,
available by clicking the `Customize' button on the `Installation Type'
step of the installer as described above.

@image{python-figures/mac_installer_09_custom_install_free_threaded,,,,png}

If the box next to the `Free-threaded Python' package name is checked,
a separate @code{PythonT.framework} will also be installed
alongside the normal @code{Python.framework} in @code{/Library/Frameworks}.
This configuration allows a free-threaded Python 3.14 build to co-exist
on your system with a traditional (GIL only) Python 3.14 build with
minimal risk while installing or testing. This installation layout may
change in future releases.

Known cautions and limitations:


@itemize -

@item 
The `UNIX command-line tools' package, which is selected by default,
will install links in @code{/usr/local/bin} for @code{python3.14t},
the free-threaded interpreter, and @code{python3.14t-config},
a configuration utility which may be useful for package builders.
Since @code{/usr/local/bin} is typically included in your shell @code{PATH},
in most cases no changes to your @code{PATH} environment variables should
be needed to use @code{python3.14t}.

@item 
For this release, the `Shell profile updater' package and the
@code{Update Shell Profile.command} in @code{/Applications/Python 3.14/}
do not support the free-threaded package.

@item 
The free-threaded build and the traditional build have separate search
paths and separate @code{site-packages} directories so, by default,
if you need a package available in both builds, it may need to be installed in both.
The free-threaded package will install a separate instance of @code{pip} for use
with @code{python3.14t}.


@itemize -

@item 
To install a package using @code{pip} without a @code{venv}:

@example
python3.14t -m pip install <package_name>
@end example
@end itemize

@item 
When working with multiple Python environments, it is usually safest and easiest
to @ref{1fb1,,create and use virtual environments}.
This can avoid possible command name conflicts and confusion about which Python is in use:

@example
python3.14t -m venv <venv_name>
@end example

然後 @code{activate}。

@item 
執行 free-threaded（自由執行緒）版本的 IDLE：

@example
python3.14t -m idlelib
@end example

@item 
The interpreters in both builds respond to the same
@ref{800,,PYTHON environment variables}
which may have unexpected results, for example, if you have @code{PYTHONPATH}
set in a shell profile. If necessary, there are
@ref{1fe1,,command line options} like @code{-E}
to ignore these environment variables.

@item 
The free-threaded build links to the third-party shared libraries,
such as @code{OpenSSL} and @code{Tk}, installed in the traditional framework.
This means that both builds also share one set of trust certificates
as installed by the @code{Install Certificates.command} script,
thus it only needs to be run once.

@item 
If you cannot depend on the link in @code{/usr/local/bin} pointing to the
@code{python.org} free-threaded @code{python3.14t} (for example, if you want
to install your own version there or some other distribution does),
you can explicitly set your shell @code{PATH} environment variable to
include the @code{PythonT} framework @code{bin} directory:

@example
export PATH="/Library/Frameworks/PythonT.framework/Versions/3.14/bin":"$PATH"
@end example

The traditional framework installation by default does something similar,
except for @code{Python.framework}. Be aware that having both framework @code{bin}
directories in @code{PATH} can lead to confusion if there are duplicate names
like @code{python3.14} in both; which one is actually used depends on the order
they appear in @code{PATH}. The @code{which python3.x} or @code{which python3.xt}
commands can show which path is being used. Using virtual environments
can help avoid such ambiguities. Another option might be to create
a shell @code{alias} to the desired interpreter, like:

@example
alias py3.14="/Library/Frameworks/Python.framework/Versions/3.14/bin/python3.14"
alias py3.14t="/Library/Frameworks/PythonT.framework/Versions/3.14/bin/python3.14t"
@end example
@end itemize

@node 使用命令列安裝,發行 Python 應用程式,Installing Free-threaded Binaries,進階主題
@anchor{using/mac installing-using-the-command-line}@anchor{2116}
@subsubsection 使用命令列安裝


If you want to use automation to install the @code{python.org} installer package
(rather than by using the familiar macOS @code{Installer} GUI app),
the macOS command line @code{installer} utility lets you select non-default
options, too. If you are not familiar with @code{installer}, it can be
somewhat cryptic (see @code{man installer} for more information).
As an example, the following shell snippet shows one way to do it,
using the @code{3.14.0b2} release and selecting the free-threaded interpreter
option:

@example
RELEASE="python-3.140b2-macos11.pkg"

# download installer pkg
curl -O https://www.python.org/ftp/python/3.14.0/$@{RELEASE@}

# create installer choicechanges to customize the install:
#    enable the PythonTFramework-3.14 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.14</string>
        </dict>
</array>
</plist>
EOF

sudo installer -pkg ./$@{RELEASE@} -applyChoiceChangesXML ./choicechanges.plist -target /
@end example

You can then test that both installer builds are now available with something like:

@example
$ # test that the free-threaded interpreter was installed if the Unix Command Tools package was enabled
$ /usr/local/bin/python3.14t -VV
Python 3.14.0b2 free-threading build (v3.14.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.14 -VV
Python 3.14.0b2 (v3.14.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.14t -VV
Python 3.14.0b2 free-threading build (v3.14.0b2:3a83b172af, Jun  5 2024, 12:57:31) [Clang 15.0.0 (clang-1500.3.9.4)]
$ python3.14 -VV
Python 3.14.0b2 (v3.14.0b2:3a83b172af, Jun  5 2024, 12:50:24) [Clang 15.0.0 (clang-1500.3.9.4)]
@end example

@cartouche
@quotation 備註 
Current @code{python.org} installers only install to fixed locations like
@code{/Library/Frameworks/}, @code{/Applications}, and @code{/usr/local/bin}.
You cannot use the @code{installer} @code{-domain} option to install to
other locations.
@end quotation
@end cartouche

@node 發行 Python 應用程式,App Store Compliance,使用命令列安裝,進階主題
@anchor{using/mac distributing-python-applications}@anchor{2117}@anchor{using/mac distributing-python-applications-on-the-mac}@anchor{2118}
@subsubsection 發行 Python 應用程式


A range of tools exist for converting your Python code into a standalone
distributable application:


@itemize *

@item 
py2app@footnote{https://pypi.org/project/py2app/}：支援從 Python 專案打包成 macOS @code{.app}。

@item 
Briefcase@footnote{https://briefcase.readthedocs.io}：BeeWare 專案@footnote{https://beeware.org}的一部分；支援建立 macOS @code{.app} 的跨平台打包工具，亦為管理簽署和驗證 (notarization) 的工具。

@item 
PyInstaller@footnote{https://pyinstaller.org/}：一個跨平臺打包工具，可以將單一檔案或資料夾打包成可分發的檔案。
@end itemize

@node App Store Compliance,,發行 Python 應用程式,進階主題
@anchor{using/mac app-store-compliance}@anchor{2119}
@subsubsection App Store Compliance


Apps submitted for distribution through the macOS App Store must pass Apple's
app review process. This process includes a set of automated validation rules
that inspect the submitted application bundle for problematic code.

The Python standard library contains some code that is known to violate these
automated rules. While these violations appear to be false positives, Apple's
review rules cannot be challenged. Therefore, it is necessary to modify the
Python standard library for an app to pass App Store review.

The Python source tree contains
a patch file@footnote{https://github.com/python/cpython/tree/3.14/Mac/Resources/app-store-compliance.patch} that will remove
all code that is known to cause issues with the App Store review process. This
patch is applied automatically when CPython is configured with the
@ref{18f0,,--with-app-store-compliance} option.

This patch is not normally required to use CPython on a Mac; nor is it required
if you are distributing an app `outside' the macOS App Store. It is `only'
required if you are using the macOS App Store as a distribution channel.

@node 其他資源,,進階主題,於 macOS 使用 Python
@anchor{using/mac other-resources}@anchor{211a}
@subsection 其他資源


The python.org Help page@footnote{https://www.python.org/about/help/} has links to many useful resources.
The Pythonmac-SIG mailing list@footnote{https://www.python.org/community/sigs/current/pythonmac-sig/}
is another support resource specifically for Python users and developers on the Mac.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node 在 Android 上使用 Python,在 iOS 上使用 Python,於 macOS 使用 Python,Python 的設置與使用
@anchor{using/android doc}@anchor{211b}@anchor{using/android translation-repo}@anchor{211c}@anchor{using/android using-android}@anchor{211d}@anchor{using/android using-python-on-android}@anchor{211e}
@section 在 Android 上使用 Python


Python on Android is unlike Python on desktop platforms. On a desktop platform,
Python is generally installed as a system resource that can be used by any user
of that computer. Users then interact with Python by running a @code{python}
executable and entering commands at an interactive prompt, or by running a
Python script.

On Android, there is no concept of installing as a system resource. The only unit
of software distribution is an "app". There is also no console where you could
run a @code{python} executable, or interact with a Python REPL.

As a result, the only way you can use Python on Android is in embedded mode – that
is, by writing a native Android application, embedding a Python interpreter
using @code{libpython}, and invoking Python code using the @ref{211f,,Python embedding API}. The full Python interpreter, the standard library, and all
your Python code is then packaged into your app for its own private use.

The Python standard library has some notable omissions and restrictions on
Android. See the @ref{2120,,API availability guide} for
details.

@menu
* 將 Python 加入 Android 應用程式:: 
* 建置用於 Android 的 Python 套件:: 

@end menu

@node 將 Python 加入 Android 應用程式,建置用於 Android 的 Python 套件,,在 Android 上使用 Python
@anchor{using/android adding-python-to-an-android-app}@anchor{2121}
@subsection 將 Python 加入 Android 應用程式


Most app developers should use one of the following tools, which will provide a
much easier experience:


@itemize *

@item 
Briefcase@footnote{https://briefcase.readthedocs.io}，由 BeeWare 專案提供

@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

If you're sure you want to do all of this manually, read on. You can use the
testbed app@footnote{https://github.com/python/cpython/tree/3.14/Android/testbed} as a guide; each step below contains a
link to the relevant file.


@itemize *

@item 
First, acquire a build of Python for Android:


@itemize *

@item 
The easiest way is to download an Android release from python.org@footnote{https://www.python.org/downloads/android/}. The @code{prefix} directory
mentioned below is at the top level of the package.

@item 
Or if you want to build it yourself, follow the instructions in
Android/README.md@footnote{https://github.com/python/cpython/tree/3.14/Android/README.md}. The @code{prefix} directory will be created under
@code{cross-build/@var{HOST}}.
@end itemize

@item 
Add code to your build.gradle@footnote{https://github.com/python/cpython/tree/3.14/Android/testbed/app/build.gradle.kts}
file to copy the following items into your project. All except your own Python
code can be copied from @code{prefix/lib}:


@itemize *

@item 
In your JNI libraries:


@itemize *

@item 
@code{libpython*.*.so}

@item 
@code{lib*_python.so}（外部函式庫，例如 OpenSSL）
@end itemize

@item 
In your assets:


@itemize *

@item 
@code{python*.*}（Python 標準函式庫）

@item 
@code{python*.*/site-packages}（你自己的 Python 程式碼）
@end itemize
@end itemize

@item 
Add code to your app to extract the assets to the filesystem@footnote{https://github.com/python/cpython/tree/3.14/Android/testbed/app/src/main/java/org/python/testbed/MainActivity.kt}.

@item 
Add code to your app to start Python in embedded mode@footnote{https://github.com/python/cpython/tree/3.14/Android/testbed/app/src/main/c/main_activity.c}. This will need to be C code
called via JNI.
@end itemize

@node 建置用於 Android 的 Python 套件,,將 Python 加入 Android 應用程式,在 Android 上使用 Python
@anchor{using/android building-a-python-package-for-android}@anchor{2122}
@subsection 建置用於 Android 的 Python 套件


Python packages can be built for Android as wheels and released on PyPI. The
recommended tool for doing this is cibuildwheel@footnote{https://cibuildwheel.pypa.io/en/stable/platforms/#android}, which automates
all the details of setting up a cross-compilation environment, building the
wheel, and testing it on an emulator.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node 在 iOS 上使用 Python,編輯器與 IDE,在 Android 上使用 Python,Python 的設置與使用
@anchor{using/ios doc}@anchor{2123}@anchor{using/ios translation-repo}@anchor{2124}@anchor{using/ios using-ios}@anchor{2125}@anchor{using/ios using-python-on-ios}@anchor{2126}
@section 在 iOS 上使用 Python


@*作者: 
Russell Keith-Magee (2024-03)


Python on iOS is unlike Python on desktop platforms. On a desktop platform,
Python is generally installed as a system resource that can be used by any user
of that computer. Users then interact with Python by running a @code{python}
executable and entering commands at an interactive prompt, or by running a
Python script.

On iOS, there is no concept of installing as a system resource. The only unit
of software distribution is an "app". There is also no console where you could
run a @code{python} executable, or interact with a Python REPL.

As a result, the only way you can use Python on iOS is in embedded mode - that
is, by writing a native iOS application, and embedding a Python interpreter
using @code{libPython}, and invoking Python code using the @ref{211f,,Python embedding API}. The full Python interpreter, the standard library, and all
your Python code is then packaged as a standalone bundle that can be
distributed via the iOS App Store.

If you're looking to experiment for the first time with writing an iOS app in
Python, projects such as BeeWare@footnote{https://beeware.org} and Kivy@footnote{https://kivy.org} will provide a much more approachable user experience.
These projects manage the complexities associated with getting an iOS project
running, so you only need to deal with the Python code itself.

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

@end menu

@node Python at runtime on iOS,Installing Python on iOS,,在 iOS 上使用 Python
@anchor{using/ios python-at-runtime-on-ios}@anchor{2127}
@subsection Python at runtime on iOS


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

@end menu

@node iOS version compatibility,Platform identification,,Python at runtime on iOS
@anchor{using/ios ios-version-compatibility}@anchor{2128}
@subsubsection iOS version compatibility


The minimum supported iOS version is specified at compile time, using the
@ref{2089,,--host} option to @code{configure}. By default, when compiled for iOS,
Python will be compiled with a minimum supported iOS version of 13.0. To use a
different minimum iOS version, provide the version number as part of the
@code{--host} argument - for example,
@code{--host=arm64-apple-ios15.4-simulator} would compile an ARM64 simulator build
with a deployment target of 15.4.

@node Platform identification,Standard library availability,iOS version compatibility,Python at runtime on iOS
@anchor{using/ios platform-identification}@anchor{2129}
@subsubsection Platform identification


When executing on iOS, @code{sys.platform} will report as @code{ios}. This value will
be returned on an iPhone or iPad, regardless of whether the app is running on
the simulator or a physical device.

Information about the specific runtime environment, including the iOS version,
device model, and whether the device is a simulator, can be obtained using
@ref{212a,,platform.ios_ver()}. @ref{212b,,platform.system()} will report @code{iOS} or
@code{iPadOS}, depending on the device.

@ref{1317,,os.uname()} reports kernel-level details; it will report a name of
@code{Darwin}.

@node Standard library availability,Binary extension modules,Platform identification,Python at runtime on iOS
@anchor{using/ios standard-library-availability}@anchor{212c}
@subsubsection Standard library availability


The Python standard library has some notable omissions and restrictions on
iOS. See the @ref{2120,,API availability guide for iOS} for
details.

@node Binary extension modules,Compiler stub binaries,Standard library availability,Python at runtime on iOS
@anchor{using/ios binary-extension-modules}@anchor{212d}
@subsubsection Binary extension modules


One notable difference about iOS as a platform is that App Store distribution
imposes hard requirements on the packaging of an application. One of these
requirements governs how binary extension modules are distributed.

The iOS App Store requires that `all' binary modules in an iOS app must be
dynamic libraries, contained in a framework with appropriate metadata, stored
in the @code{Frameworks} folder of the packaged app. There can be only a single
binary per framework, and there can be no executable binary material outside
the @code{Frameworks} folder.

This conflicts with the usual Python approach for distributing binaries, which
allows a binary extension module to be loaded from any location on
@code{sys.path}. To ensure compliance with App Store policies, an iOS project must
post-process any Python packages, converting @code{.so} binary modules into
individual standalone frameworks with appropriate metadata and signing. For
details on how to perform this post-processing, see the guide for @ref{212e,,adding Python to your project}.

To help Python discover binaries in their new location, the original @code{.so}
file on @code{sys.path} is replaced with a @code{.fwork} file. This file is a text
file containing the location of the framework binary, relative to the app
bundle. To allow the framework to resolve back to the original location, the
framework must contain a @code{.origin} file that contains the location of the
@code{.fwork} file, relative to the app bundle.

For example, consider the case of an import @code{from foo.bar import _whiz},
where @code{_whiz} is implemented with the binary module
@code{sources/foo/bar/_whiz.abi3.so}, with @code{sources} being the location
registered on @code{sys.path}, relative to the application bundle. This module
`must' be distributed as @code{Frameworks/foo.bar._whiz.framework/foo.bar._whiz}
(creating the framework name from the full import path of the module), with an
@code{Info.plist} file in the @code{.framework} directory identifying the binary as a
framework. The @code{foo.bar._whiz} module would be represented in the original
location with a @code{sources/foo/bar/_whiz.abi3.fwork} marker file, containing
the path @code{Frameworks/foo.bar._whiz/foo.bar._whiz}. The framework would also
contain @code{Frameworks/foo.bar._whiz.framework/foo.bar._whiz.origin}, containing
the path to the @code{.fwork} file.

When running on iOS, the Python interpreter will install an
@ref{212f,,AppleFrameworkLoader} that is able to read and
import @code{.fwork} files. Once imported, the @code{__file__} attribute of the
binary module will report as the location of the @code{.fwork} file. However, the
@ref{2130,,ModuleSpec} for the loaded module will report the
@code{origin} as the location of the binary in the framework folder.

@node Compiler stub binaries,,Binary extension modules,Python at runtime on iOS
@anchor{using/ios compiler-stub-binaries}@anchor{2131}
@subsubsection Compiler stub binaries


Xcode doesn't expose explicit compilers for iOS; instead, it uses an @code{xcrun}
script that resolves to a full compiler path (e.g., @code{xcrun --sdk iphoneos
clang} to get the @code{clang} for an iPhone device). However, using this script
poses two problems:


@itemize *

@item 
The output of @code{xcrun} includes paths that are machine specific, resulting
in a sysconfig module that cannot be shared between users; and

@item 
It results in @code{CC}/@code{CPP}/@code{LD}/@code{AR} definitions that include spaces.
There is a lot of C ecosystem tooling that assumes that you can split a
command line at the first space to get the path to the compiler executable;
this isn't the case when using @code{xcrun}.
@end itemize

To avoid these problems, Python provided stubs for these tools. These stubs are
shell script wrappers around the underingly @code{xcrun} tools, distributed in a
@code{bin} folder distributed alongside the compiled iOS framework. These scripts
are relocatable, and will always resolve to the appropriate local system paths.
By including these scripts in the bin folder that accompanies a framework, the
contents of the @code{sysconfig} module becomes useful for end-users to compile
their own modules. When compiling third-party Python modules for iOS, you
should ensure these stub binaries are on your path.

@node Installing Python on iOS,App Store Compliance<2>,Python at runtime on iOS,在 iOS 上使用 Python
@anchor{using/ios installing-python-on-ios}@anchor{2132}
@subsection Installing Python on iOS


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

@end menu

@node Tools for building iOS apps,Adding Python to an iOS project,,Installing Python on iOS
@anchor{using/ios tools-for-building-ios-apps}@anchor{2133}
@subsubsection Tools for building iOS apps


Building for iOS requires the use of Apple's Xcode tooling. It is strongly
recommended that you use the most recent stable release of Xcode. This will
require the use of the most (or second-most) recently released macOS version,
as Apple does not maintain Xcode for older macOS versions. The Xcode Command
Line Tools are not sufficient for iOS development; you need a `full' Xcode
install.

If you want to run your code on the iOS simulator, you'll also need to install
an iOS Simulator Platform. You should be prompted to select an iOS Simulator
Platform when you first run Xcode. Alternatively, you can add an iOS Simulator
Platform by selecting from the Platforms tab of the Xcode Settings panel.

@node Adding Python to an iOS project,Testing a Python package,Tools for building iOS apps,Installing Python on iOS
@anchor{using/ios adding-ios}@anchor{212e}@anchor{using/ios adding-python-to-an-ios-project}@anchor{2134}
@subsubsection Adding Python to an iOS project


Python can be added to any iOS project, using either Swift or Objective C. The
following examples will use Objective C; if you are using Swift, you may find a
library like PythonKit@footnote{https://github.com/pvieito/PythonKit} to be
helpful.

To add Python to an iOS Xcode project:


@enumerate 

@item 
Build or obtain a Python @code{XCFramework}. See the instructions in
Apple/iOS/README.md@footnote{https://github.com/python/cpython/tree/3.14/Apple/iOS/README.md} (in the CPython source distribution) for details on
how to build a Python @code{XCFramework}. At a minimum, you will need a build
that supports @code{arm64-apple-ios}, plus one of either
@code{arm64-apple-ios-simulator} or @code{x86_64-apple-ios-simulator}.

@item 
Drag the @code{XCframework} into your iOS project. In the following
instructions, we'll assume you've dropped the @code{XCframework} into the root
of your project; however, you can use any other location that you want by
adjusting paths as needed.

@item 
Add your application code as a folder in your Xcode project. In the
following instructions, we'll assume that your user code is in a folder
named @code{app} in the root of your project; you can use any other location by
adjusting paths as needed. Ensure that this folder is associated with your
app target.

@item 
Select the app target by selecting the root node of your Xcode project, then
the target name in the sidebar that appears.

@item 
In the "General" settings, under "Frameworks, Libraries and Embedded
Content", add @code{Python.xcframework}, with "Embed & Sign" selected.

@item 
In the "Build Settings" tab, modify the following:


@itemize -

@item 
建置選項


@itemize *

@item 
User Script Sandboxing: No

@item 
Enable Testability: Yes
@end itemize

@item 
Search Paths


@itemize *

@item 
Framework Search Paths: @code{$(PROJECT_DIR)}

@item 
Header Search Paths: @code{"$(BUILT_PRODUCTS_DIR)/Python.framework/Headers"}
@end itemize

@item 
Apple Clang - Warnings - All languages


@itemize *

@item 
Quoted Include In Framework Header: No
@end itemize
@end itemize

@item 
Add a build step that processes the Python standard library, and your own
Python binary dependencies. In the "Build Phases" tab, add a new "Run
Script" build step `before' the "Embed Frameworks" step, but `after' the
"Copy Bundle Resources" step. Name the step "Process Python libraries",
disable the "Based on dependency analysis" checkbox, and set the script
content to:

@example
set -e
source $PROJECT_DIR/Python.xcframework/build/build_utils.sh
install_python Python.xcframework app
@end example

If you have placed your XCframework somewhere other than the root of your
project, modify the path to the first argument.

@item 
Add Objective C code to initialize and use a Python interpreter in embedded
mode. You should ensure that:


@itemize *

@item 
UTF-8 mode (@ref{41b,,PyPreConfig.utf8_mode}) is `enabled';

@item 
Buffered stdio (@ref{40f,,PyConfig.buffered_stdio}) is `disabled';

@item 
Writing bytecode (@ref{40b,,PyConfig.write_bytecode}) is `disabled';

@item 
Signal handlers (@ref{ab2,,PyConfig.install_signal_handlers}) are `enabled';

@item 
System logging (@ref{2135,,PyConfig.use_system_logger}) is `enabled'
(optional, but strongly recommended; this is enabled by default);

@item 
@geindex PYTHONHOME
@geindex 環境變數; PYTHONHOME
@ref{3ee,,PYTHONHOME} for the interpreter is configured to point at the
@code{python} subfolder of your app's bundle; and

@item 
The 
@geindex PYTHONPATH
@geindex 環境變數; PYTHONPATH
@ref{1218,,PYTHONPATH} for the interpreter includes:


@itemize -

@item 
the @code{python/lib/python3.X} subfolder of your app's bundle,

@item 
the @code{python/lib/python3.X/lib-dynload} subfolder of your app's bundle, and

@item 
the @code{app} subfolder of your app's bundle
@end itemize
@end itemize

Your app's bundle location can be determined using @code{[[NSBundle mainBundle]
resourcePath]}.
@end enumerate

Steps 7 and 8 of these instructions assume that you have a single folder of
pure Python application code, named @code{app}. If you have third-party binary
modules in your app, some additional steps will be required:


@itemize *

@item 
You need to ensure that any folders containing third-party binaries are
either associated with the app target, or are explicitly copied as part of
step 7. Step 7 should also purge any binaries that are not appropriate for
the platform a specific build is targeting (i.e., delete any device binaries
if you're building an app targeting the simulator).

@item 
If you're using a separate folder for third-party packages, ensure that
folder is added to the end of the call to @code{install_python} in step 7, and
as part of the 
@geindex PYTHONPATH
@geindex 環境變數; PYTHONPATH
@ref{1218,,PYTHONPATH} configuration in step 8.

@item 
If any of the folders that contain third-party packages will contain @code{.pth}
files, you should add that folder as a `site directory' (using
@ref{2136,,site.addsitedir()}), rather than adding to 
@geindex PYTHONPATH
@geindex 環境變數; PYTHONPATH
@ref{1218,,PYTHONPATH} or
@ref{3e2,,sys.path} directly.
@end itemize

@node Testing a Python package,,Adding Python to an iOS project,Installing Python on iOS
@anchor{using/ios testing-a-python-package}@anchor{2137}
@subsubsection Testing a Python package


The CPython source tree contains a testbed project@footnote{https://github.com/python/cpython/tree/3.14/Apple/iOS/testbed} that
is used to run the CPython test suite on the iOS simulator. This testbed can also
be used as a testbed project for running your Python library's test suite on iOS.

After building or obtaining an iOS XCFramework (see Apple/iOS/README.md@footnote{https://github.com/python/cpython/tree/3.14/Apple/iOS/README.md}
for details), create a clone of the Python iOS testbed project. If you used the
@code{Apple} build script to build the XCframework, you can run:

@example
$ python cross-build/iOS/testbed clone --app <path/to/module1> --app <path/to/module2> app-testbed
@end example

Or, if you've sourced your own XCframework, by running:

@example
$ python Apple/testbed clone --platform iOS --framework <path/to/Python.xcframework> --app <path/to/module1> --app <path/to/module2> app-testbed
@end example

Any folders specified with the @code{--app} flag will be copied into the cloned
testbed project. The resulting testbed will be created in the @code{app-testbed}
folder. In this example, the @code{module1} and @code{module2} would be importable
modules at runtime. If your project has additional dependencies, they can be
installed into the @code{app-testbed/Testbed/app_packages} folder (using @code{pip
install --target app-testbed/Testbed/app_packages} or similar).

You can then use the @code{app-testbed} folder to run the test suite for your app,
For example, if @code{module1.tests} was the entry point to your test suite, you
could run:

@example
$ python app-testbed run -- module1.tests
@end example

This is the equivalent of running @code{python -m module1.tests} on a desktop
Python build. Any arguments after the @code{--} will be passed to the testbed as
if they were arguments to @code{python -m} on a desktop machine.

You can also open the testbed project in Xcode by running:

@example
$ open app-testbed/iOSTestbed.xcodeproj
@end example

This will allow you to use the full Xcode suite of tools for debugging.

The arguments used to run the test suite are defined as part of the test plan.
To modify the test plan, select the test plan node of the project tree (it
should be the first child of the root node), and select the "Configurations"
tab. Modify the "Arguments Passed On Launch" value to change the testing
arguments.

The test plan also disables parallel testing, and specifies the use of the
@code{Testbed.lldbinit} file for providing configuration of the debugger. The
default debugger configuration disables automatic breakpoints on the
@code{SIGINT}, @code{SIGUSR1}, @code{SIGUSR2}, and @code{SIGXFSZ} signals.

@node App Store Compliance<2>,,Installing Python on iOS,在 iOS 上使用 Python
@anchor{using/ios app-store-compliance}@anchor{2138}
@subsection App Store Compliance


The only mechanism for distributing apps to third-party iOS devices is to
submit the app to the iOS App Store; apps submitted for distribution must pass
Apple's app review process. This process includes a set of automated validation
rules that inspect the submitted application bundle for problematic code. There
are some steps that must be taken to ensure that your app will be able to pass
these validation steps.

@menu
* Incompatible code in the standard library:: 
* Privacy manifests:: 

@end menu

@node Incompatible code in the standard library,Privacy manifests,,App Store Compliance<2>
@anchor{using/ios incompatible-code-in-the-standard-library}@anchor{2139}
@subsubsection Incompatible code in the standard library


The Python standard library contains some code that is known to violate these
automated rules. While these violations appear to be false positives, Apple's
review rules cannot be challenged; so, it is necessary to modify the Python
standard library for an app to pass App Store review.

The Python source tree contains
a patch file@footnote{https://github.com/python/cpython/tree/3.14/Mac/Resources/app-store-compliance.patch} that will remove
all code that is known to cause issues with the App Store review process. This
patch is applied automatically when building for iOS.

@node Privacy manifests,,Incompatible code in the standard library,App Store Compliance<2>
@anchor{using/ios privacy-manifests}@anchor{213a}
@subsubsection Privacy manifests


In April 2025, Apple introduced a requirement for certain third-party libraries to provide a Privacy Manifest@footnote{https://developer.apple.com/support/third-party-SDK-requirements}.
As a result, if you have a binary module that uses one of the affected
libraries, you must provide an @code{.xcprivacy} file for that library.
OpenSSL is one library affected by this requirement, but there are others.

If you produce a binary module named @code{mymodule.so}, and use you the Xcode
build script described in step 7 above, you can place a @code{mymodule.xcprivacy}
file next to @code{mymodule.so}, and the privacy manifest will be installed into
the required location when the binary module is converted into a framework.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node 編輯器與 IDE,,在 iOS 上使用 Python,Python 的設置與使用
@anchor{using/editors doc}@anchor{213b}@anchor{using/editors editors}@anchor{210c}@anchor{using/editors editors-and-ides}@anchor{213c}@anchor{using/editors translation-repo}@anchor{213d}
@section 編輯器與 IDE


There are a number of IDEs that support Python programming language.
Many editors and IDEs provide syntax highlighting, debugging tools, and 
@geindex Python Enhancement Proposals; PEP 8
PEP 8@footnote{https://peps.python.org/pep-0008/} checks.

@menu
* IDLE: IDLE --- Python 編輯器與 shell. Python 編輯器與 shell
* 其他編輯器與 IDE:: 

@end menu

@node IDLE --- Python 編輯器與 shell,其他編輯器與 IDE,,編輯器與 IDE
@anchor{using/editors idle-python-editor-and-shell}@anchor{213e}
@subsection IDLE --- Python 編輯器與 shell


IDLE is Python’s Integrated Development and Learning Environment and is generally bundled with Python installs.
If you are on Linux and do not have IDLE installed see @ref{2010,,Installing IDLE on Linux}.
For more information see the @ref{1210,,IDLE docs}.

@node 其他編輯器與 IDE,,IDLE --- Python 編輯器與 shell,編輯器與 IDE
@anchor{using/editors other-editors-and-ides}@anchor{213f}
@subsection 其他編輯器與 IDE


Python's community wiki has information submitted by the community on Editors and IDEs.
Please go to Python Editors@footnote{https://wiki.python.org/moin/PythonEditors} and
Integrated Development Environments@footnote{https://wiki.python.org/moin/IntegratedDevelopmentEnvironments}
for a comprehensive list.

@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 標準函式庫 Standard Library,Python 的設置與使用,Top
@anchor{reference/index doc}@anchor{2140}@anchor{reference/index reference-index}@anchor{14a}@anchor{reference/index the-python-language-reference}@anchor{2141}@anchor{reference/index translation-repo}@anchor{2142}
@chapter Python 語言參考手冊


這份參考手冊會描述 Python 語言的語法及「核心語意」。它雖然簡潔，但也盡量保持精確並完整。關於非必要的 (non-essential) 內建物件型別、內建函式及模組的語意，則在 @ref{149,,Python 標準函式庫 (Standard Library)} 中說明。關於此語言的非正式介紹，請參閱 @ref{1e83,,Python 教學}。對於 C 或 C++ 程式設計師，還有另外兩個手冊：@ref{1e84,,擴充和嵌入 Python 直譯器}以高階的視野說明如何編寫 Python 擴充模組，而 @ref{1e85,,Python/C API 參考手冊}則詳細說明 C/C++ 程式設計師可用的介面。

@menu
* 簡介: 簡介<5>. 
* 詞法分析:: 
* 資料模型:: 
* 執行模型:: 
* 模組引入系統:: 
* 運算式:: 
* 簡單陳述式:: 
* 複合陳述式:: 
* 最高層級元件:: 
* 完整的語法規格書:: 

@end menu

@node 簡介<5>,詞法分析,,Python 語言參考手冊
@anchor{reference/introduction doc}@anchor{2143}@anchor{reference/introduction id1}@anchor{2144}@anchor{reference/introduction introduction}@anchor{2145}
@section 簡介


This reference manual describes the Python programming language. It is not
intended as a tutorial.

While I am trying to be as precise as possible, I chose to use English rather
than formal specifications for everything except syntax and lexical analysis.
This should make the document more understandable to the average reader, but
will leave room for ambiguities. Consequently, if you were coming from Mars and
tried to re-implement Python from this document alone, you might have to guess
things and in fact you would probably end up implementing quite a different
language. On the other hand, if you are using Python and wonder what the precise
rules about a particular area of the language are, you should definitely be able
to find them here. If you would like to see a more formal definition of the
language, maybe you could volunteer your time --- or invent a cloning machine
:-).

It is dangerous to add too many implementation details to a language reference
document --- the implementation may change, and other implementations of the
same language may work differently.  On the other hand, CPython is the one
Python implementation in widespread use (although alternate implementations
continue to gain support), and its particular quirks are sometimes worth being
mentioned, especially where the implementation imposes additional limitations.
Therefore, you'll find short "implementation notes" sprinkled throughout the
text.

Every Python implementation comes with a number of built-in and standard
modules.  These are documented in @ref{149,,Python 標準函式庫 (Standard Library)}.  A few built-in modules
are mentioned when they interact in a significant way with the language
definition.

@menu
* Alternate Implementations:: 
* Notation:: 

@end menu

@node Alternate Implementations,Notation,,簡介<5>
@anchor{reference/introduction alternate-implementations}@anchor{2146}@anchor{reference/introduction implementations}@anchor{1fde}
@subsection Alternate Implementations


Though there is one Python implementation which is by far the most popular,
there are some alternate implementations which are of particular interest to
different audiences.

Known implementations include:


@table @asis

@item CPython

This is the original and most-maintained implementation of Python, written in C.
New language features generally appear here first.

@item Jython

Python implemented in Java.  This implementation can be used as a scripting
language for Java applications, or can be used to create applications using the
Java class libraries.  It is also often used to create tests for Java libraries.
More information can be found at the Jython website@footnote{https://www.jython.org/}.

@item Python for .NET

This implementation actually uses the CPython implementation, but is a managed
.NET application and makes .NET libraries available.  It was created by Brian
Lloyd.  For more information, see the Python for .NET home page@footnote{https://pythonnet.github.io/}.

@item IronPython

An alternate Python for .NET.  Unlike Python.NET, this is a complete Python
implementation that generates IL, and compiles Python code directly to .NET
assemblies.  It was created by Jim Hugunin, the original creator of Jython.  For
more information, see the IronPython website@footnote{https://ironpython.net/}.

@item PyPy

An implementation of Python written completely in Python. It supports several
advanced features not found in other implementations like stackless support
and a Just in Time compiler. One of the goals of the project is to encourage
experimentation with the language itself by making it easier to modify the
interpreter (since it is written in Python).  Additional information is
available on the PyPy project's home page@footnote{https://pypy.org/}.
@end table

Each of these implementations varies in some way from the language as documented
in this manual, or introduces specific information beyond what's covered in the
standard Python documentation.  Please refer to the implementation-specific
documentation to determine what else you need to know about the specific
implementation you're using.

@node Notation,,Alternate Implementations,簡介<5>
@anchor{reference/introduction id2}@anchor{2147}@anchor{reference/introduction notation}@anchor{2148}
@subsection Notation


@geindex BNF
@geindex grammar（文法）
@geindex syntax（語法）
@geindex notation（標記法）

The descriptions of lexical analysis and syntax use a grammar notation that
is a mixture of
EBNF@footnote{https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_form}
and PEG@footnote{https://en.wikipedia.org/wiki/Parsing_expression_grammar}.
For example:

@example
@anchor{reference/introduction grammar-token-notation-name}@anchor{2149}name:   @ref{214a,,letter} (@ref{214a,,letter} | @ref{214b,,digit} | "_")*
@anchor{reference/introduction grammar-token-notation-letter}@anchor{214a}letter: "a"..."z" | "A"..."Z"
@anchor{reference/introduction grammar-token-notation-digit}@anchor{214b}digit:  "0"..."9"
@end example

In this example, the first line says that a @code{name} is a @code{letter} followed
by a sequence of zero or more @code{letter}s, @code{digit}s, and underscores.
A @code{letter} in turn is any of the single characters @code{'a'} through
@code{'z'} and @code{A} through @code{Z}; a @code{digit} is a single character from @code{0}
to @code{9}.

Each rule begins with a name (which identifies the rule that's being defined)
followed by a colon, @code{:}.
The definition to the right of the colon uses the following syntax elements:


@itemize *

@item 
@code{name}: A name refers to another rule.
Where possible, it is a link to the rule's definition.


@itemize *

@item 
@code{TOKEN}: An uppercase name refers to a @ref{214c,,token}.
For the purposes of grammar definitions, tokens are the same as rules.
@end itemize

@item 
@code{"text"}, @code{'text'}: Text in single or double quotes must match literally
(without the quotes). The type of quote is chosen according to the meaning
of @code{text}:


@itemize *

@item 
@code{'if'}: A name in single quotes denotes a @ref{214d,,keyword}.

@item 
@code{"case"}: A name in double quotes denotes a
@ref{a06,,soft-keyword}.

@item 
@code{'@@'}: A non-letter symbol in single quotes denotes an
@ref{214e,,OP} token, that is, a @ref{214f,,delimiter} or
@ref{2150,,operator}.
@end itemize

@item 
@code{e1 e2}: Items separated only by whitespace denote a sequence.
Here, @code{e1} must be followed by @code{e2}.

@item 
@code{e1 | e2}: A vertical bar is used to separate alternatives.
It denotes PEG's "ordered choice": if @code{e1} matches, @code{e2} is
not considered.
In traditional PEG grammars, this is written as a slash, @code{/}, rather than
a vertical bar.
See 
@geindex Python Enhancement Proposals; PEP 617
PEP 617@footnote{https://peps.python.org/pep-0617/} for more background and details.

@item 
@code{e*}: A star means zero or more repetitions of the preceding item.

@item 
@code{e+}: Likewise, a plus means one or more repetitions.

@item 
@code{[e]}: A phrase enclosed in square brackets means zero or
one occurrences. In other words, the enclosed phrase is optional.

@item 
@code{e?}: A question mark has exactly the same meaning as square brackets:
the preceding item is optional.

@item 
@code{(e)}: Parentheses are used for grouping.
@end itemize

The following notation is only used in
@ref{2151,,lexical definitions}.


@itemize *

@item 
@code{"a"..."z"}: Two literal characters separated by three dots mean a choice
of any single character in the given (inclusive) range of ASCII characters.

@item 
@code{<...>}: A phrase between angular brackets gives an informal description
of the matched symbol (for example, @code{<any ASCII character except "\">}),
or an abbreviation that is defined in nearby text (for example, @code{<Lu>}).
@end itemize
@anchor{reference/introduction lexical-lookaheads}@anchor{2152}
Some definitions also use `lookaheads', which indicate that an element
must (or must not) match at a given position, but without consuming any input:


@itemize *

@item 
@code{&e}: a positive lookahead (that is, @code{e} is required to match)

@item 
@code{!e}: a negative lookahead (that is, @code{e} is required `not' to match)
@end itemize

The unary operators (@code{*}, @code{+}, @code{?}) bind as tightly as possible;
the vertical bar (@code{|}) binds most loosely.

White space is only meaningful to separate tokens.

Rules are normally contained on a single line, but rules that are too long
may be wrapped:

@example
@anchor{reference/introduction grammar-token-notation-literal}@anchor{2153}literal: stringliteral | bytesliteral
         | integer | floatnumber | imagnumber
@end example

Alternatively, rules may be formatted with the first line ending at the colon,
and each alternative beginning with a vertical bar on a new line.
For example:

@example
@anchor{reference/introduction grammar-token-notation-alt-literal}@anchor{2154}literal:
   | stringliteral
   | bytesliteral
   | integer
   | floatnumber
   | imagnumber
@end example

This does `not' mean that there is an empty first alternative.

@geindex lexical definitions（詞法定義）

@menu
* 詞法和語法定義:: 

@end menu

@node 詞法和語法定義,,,Notation
@anchor{reference/introduction lexical-and-syntactic-definitions}@anchor{2155}@anchor{reference/introduction notation-lexical-vs-syntactic}@anchor{2151}
@subsubsection 詞法和語法定義


There is some difference between `lexical' and `syntactic' analysis:
the @ref{2156,,lexical analyzer} operates on the individual characters of the
input source, while the `parser' (syntactic analyzer) operates on the stream
of @ref{214c,,tokens} generated by the lexical analysis.
However, in some cases the exact boundary between the two phases is a
CPython implementation detail.

The practical difference between the two is that in `lexical' definitions,
all whitespace is significant.
The lexical analyzer @ref{2157,,discards} all whitespace that is not
converted to tokens like @ref{1fc3,,token.INDENT} or @ref{2158,,NEWLINE}.
`Syntactic' definitions then use these tokens, rather than source characters.

This documentation uses the same BNF grammar for both styles of definitions.
All uses of BNF in the next chapter (@ref{2159,,詞法分析}) are lexical definitions;
uses in subsequent chapters are syntactic definitions.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node 詞法分析,資料模型,簡介<5>,Python 語言參考手冊
@anchor{reference/lexical_analysis doc}@anchor{215a}@anchor{reference/lexical_analysis lexical}@anchor{2159}@anchor{reference/lexical_analysis lexical-analysis}@anchor{215b}@anchor{reference/lexical_analysis translation-repo}@anchor{215c}
@section 詞法分析


@geindex lexical analysis（詞法分析）
@geindex parser（剖析器）
@geindex token

A Python program is read by a `parser'.  Input to the parser is a stream of
@ref{214c,,tokens}, generated by the `lexical analyzer' (also known as
the `tokenizer').
This chapter describes how the lexical analyzer produces these tokens.

The lexical analyzer determines the program text's @ref{215d,,encoding}
(UTF-8 by default), and decodes the text into
@ref{215e,,source characters}.
If the text cannot be decoded, a @ref{18e,,SyntaxError} is raised.

Next, the lexical analyzer uses the source characters to generate a stream of tokens.
The type of a generated token generally depends on the next source character to
be processed. Similarly, other special behavior of the analyzer depends on
the first source character that hasn't yet been processed.
The following table gives a quick summary of these source characters,
with links to sections that contain more information.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

字元

@tab

Next token (or other relevant documentation)

@item


@itemize *

@item 
space（空白）

@item 
tab（定位字元）

@item 
formfeed
@end itemize

@tab


@itemize *

@item 
@ref{2157,,Whitespace}
@end itemize

@item


@itemize *

@item 
CR, LF
@end itemize

@tab


@itemize *

@item 
@ref{215f,,New line}

@item 
@ref{2160,,Indentation}
@end itemize

@item


@itemize *

@item 
反斜線 (@code{\})
@end itemize

@tab


@itemize *

@item 
@ref{2161,,Explicit line joining}

@item 
(Also significant in @ref{680,,string escape sequences})
@end itemize

@item


@itemize *

@item 
hash (@code{#})
@end itemize

@tab


@itemize *

@item 
@ref{2162,,Comment}
@end itemize

@item


@itemize *

@item 
quote (@code{'}, @code{"})
@end itemize

@tab


@itemize *

@item 
@ref{2163,,String literal}
@end itemize

@item


@itemize *

@item 
ASCII letter (@code{a}-@code{z}, @code{A}-@code{Z})

@item 
非 ASCII 字元
@end itemize

@tab


@itemize *

@item 
@ref{2164,,Name}

@item 
Prefixed @ref{2163,,string or bytes literal}
@end itemize

@item


@itemize *

@item 
底線 (@code{_})
@end itemize

@tab


@itemize *

@item 
@ref{2164,,Name}

@item 
(Can also be part of @ref{2165,,numeric literals})
@end itemize

@item


@itemize *

@item 
number (@code{0}-@code{9})
@end itemize

@tab


@itemize *

@item 
@ref{2165,,Numeric literal}
@end itemize

@item


@itemize *

@item 
dot (@code{.})
@end itemize

@tab


@itemize *

@item 
@ref{2165,,Numeric literal}

@item 
@ref{2150,,Operator}
@end itemize

@item


@itemize *

@item 
question mark (@code{?})

@item 
dollar (@code{$})

@item 
@c (the following uses zero-width space characters to render

@c a literal backquote)

backquote (@code{​`​})

@item 
控制字元
@end itemize

@tab


@itemize *

@item 
Error (outside string literals and comments)
@end itemize

@item


@itemize *

@item 
other printing character
@end itemize

@tab


@itemize *

@item 
@ref{2150,,Operator or delimiter}
@end itemize

@item


@itemize *

@item 
end of file
@end itemize

@tab


@itemize *

@item 
@ref{2166,,End marker}
@end itemize

@end multitable


@menu
* Line structure:: 
* Other tokens:: 
* Names (identifiers and keywords): Names identifiers and keywords. 
* Literals:: 
* String and Bytes literals:: 
* Numeric literals:: 
* Operators and delimiters:: 

@end menu

@node Line structure,Other tokens,,詞法分析
@anchor{reference/lexical_analysis id1}@anchor{2167}@anchor{reference/lexical_analysis line-structure}@anchor{215f}
@subsection Line structure


@geindex line structure（列結構）

A Python program is divided into a number of `logical lines'.

@menu
* Logical lines:: 
* Physical lines:: 
* Comments:: 
* Encoding declarations:: 
* Explicit line joining:: 
* Implicit line joining:: 
* Blank lines:: 
* Indentation:: 
* Whitespace between tokens:: 
* End marker:: 

@end menu

@node Logical lines,Physical lines,,Line structure
@anchor{reference/lexical_analysis id2}@anchor{2168}@anchor{reference/lexical_analysis logical-lines}@anchor{2169}
@subsubsection Logical lines


@geindex logical line（邏輯列）
@geindex physical line（物理列）
@geindex line joining（列連接）
@geindex NEWLINE token（換行標誌）

The end of a logical line is represented by the token @ref{2158,,NEWLINE}.
Statements cannot cross logical line boundaries except where @code{NEWLINE}
is allowed by the syntax (e.g., between statements in compound statements).
A logical line is constructed from one or more `physical lines' by following
the @ref{2161,,explicit} or @ref{216a,,implicit}
`line joining' rules.

@node Physical lines,Comments,Logical lines,Line structure
@anchor{reference/lexical_analysis id3}@anchor{216b}@anchor{reference/lexical_analysis physical-lines}@anchor{216c}
@subsubsection Physical lines


A physical line is a sequence of characters terminated by one the following
end-of-line sequences:


@itemize *

@item 
the Unix form using ASCII LF (linefeed),

@item 
the Windows form using the ASCII sequence CR LF (return followed by linefeed),

@item 
the 'Classic Mac OS@footnote{https://en.wikipedia.org/wiki/Classic_Mac_OS}' form using the ASCII CR (return) character.
@end itemize

Regardless of platform, each of these sequences is replaced by a single
ASCII LF (linefeed) character.
(This is done even inside @ref{2163,,string literals}.)
Each line can use any of the sequences; they do not need to be consistent
within a file.

The end of input also serves as an implicit terminator for the final
physical line.

Formally:

@example
@anchor{reference/lexical_analysis grammar-token-python-grammar-newline}@anchor{216d}newline: <ASCII LF> | <ASCII CR> <ASCII LF> | <ASCII CR>
@end example

@node Comments,Encoding declarations,Physical lines,Line structure
@anchor{reference/lexical_analysis comments}@anchor{2162}@anchor{reference/lexical_analysis id5}@anchor{216e}
@subsubsection Comments


@geindex comment（註解）
@geindex hash character（井字號）
@geindex # （井字號）;comment（註解）

A comment starts with a hash character (@code{#}) that is not part of a string
literal, and ends at the end of the physical line.  A comment signifies the end
of the logical line unless the implicit line joining rules are invoked. Comments
are ignored by the syntax.

@node Encoding declarations,Explicit line joining,Comments,Line structure
@anchor{reference/lexical_analysis encoding-declarations}@anchor{216f}@anchor{reference/lexical_analysis encodings}@anchor{215d}
@subsubsection Encoding declarations


@geindex source character set（原始字元集合）
@geindex encoding declarations (source file)（編碼宣告（原始檔案））
@geindex # （井字號）;source encoding declaration（原始編碼宣告）

If a comment in the first or second line of the Python script matches the
regular expression @code{coding[=:]\s*([-\w.]+)}, this comment is processed as an
encoding declaration; the first group of this expression names the encoding of
the source code file. The encoding declaration must appear on a line of its
own. If it is the second line, the first line must also be a comment-only line.
The recommended forms of an encoding expression are

@example
# -*- coding: <encoding-name> -*-
@end example

which is recognized also by GNU Emacs, and

@example
# vim:fileencoding=<encoding-name>
@end example

which is recognized by Bram Moolenaar's VIM.

If no encoding declaration is found, the default encoding is UTF-8.  If the
implicit or explicit encoding of a file is UTF-8, an initial UTF-8 byte-order
mark (@code{b'\xef\xbb\xbf'}) is ignored rather than being a syntax error.

If an encoding is declared, the encoding name must be recognized by Python
(see @ref{fb3,,標準編碼}). The
encoding is used for all lexical analysis, including string literals, comments
and identifiers.
@anchor{reference/lexical_analysis lexical-source-character}@anchor{215e}
All lexical analysis, including string literals, comments
and identifiers, works on Unicode text decoded using the source encoding.
Any Unicode code point, except the NUL control character, can appear in
Python source.

@example
@anchor{reference/lexical_analysis grammar-token-python-grammar-source_character}@anchor{2170}source_character:  <any Unicode code point, except NUL>
@end example

@node Explicit line joining,Implicit line joining,Encoding declarations,Line structure
@anchor{reference/lexical_analysis explicit-joining}@anchor{2161}@anchor{reference/lexical_analysis explicit-line-joining}@anchor{2171}
@subsubsection Explicit line joining


@geindex physical line（物理列）
@geindex line joining（列連接）
@geindex line continuation（列延續）
@geindex backslash character（反斜線字元）

Two or more physical lines may be joined into logical lines using backslash
characters (@code{\}), as follows: when a physical line ends in a backslash that is
not part of a string literal or comment, it is joined with the following forming
a single logical line, deleting the backslash and the following end-of-line
character.  For example:

@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:   # 看起來像個有效日期
        return 1
@end example

A line ending in a backslash cannot carry a comment.  A backslash does not
continue a comment.  A backslash does not continue a token except for string
literals (i.e., tokens other than string literals cannot be split across
physical lines using a backslash).  A backslash is illegal elsewhere on a line
outside a string literal.

@node Implicit line joining,Blank lines,Explicit line joining,Line structure
@anchor{reference/lexical_analysis implicit-joining}@anchor{216a}@anchor{reference/lexical_analysis implicit-line-joining}@anchor{2172}
@subsubsection Implicit line joining


Expressions in parentheses, square brackets or curly braces can be split over
more than one physical line without using backslashes. For example:

@example
month_names = ['Januari', 'Februari', 'Maart',      # 這些是
               'April',   'Mei',      'Juni',       # 荷蘭文的
               'Juli',    'Augustus', 'September',  # 一年之中
               'Oktober', 'November', 'December']   # 月份名稱
@end example

Implicitly continued lines can carry comments.  The indentation of the
continuation lines is not important.  Blank continuation lines are allowed.
There is no NEWLINE token between implicit continuation lines.  Implicitly
continued lines can also occur within triple-quoted strings (see below); in that
case they cannot carry comments.

@node Blank lines,Indentation,Implicit line joining,Line structure
@anchor{reference/lexical_analysis blank-lines}@anchor{2173}@anchor{reference/lexical_analysis id6}@anchor{2174}
@subsubsection Blank lines


@geindex blank line（空白列）

A logical line that contains only spaces, tabs, formfeeds and possibly a
comment, is ignored (i.e., no @ref{2158,,NEWLINE} token is generated).
During interactive input of statements, handling of a blank line may differ
depending on the implementation of the read-eval-print loop.
In the standard interactive interpreter, an entirely blank logical line (that
is, one containing not even whitespace or a comment) terminates a multi-line
statement.

@node Indentation,Whitespace between tokens,Blank lines,Line structure
@anchor{reference/lexical_analysis id7}@anchor{2175}@anchor{reference/lexical_analysis indentation}@anchor{2160}
@subsubsection Indentation


@geindex indentation（縮排）
@geindex leading whitespace（前置空白）
@geindex space（空白）
@geindex tab（定位字元）
@geindex grouping（群組）
@geindex statement grouping（陳述式群組）

Leading whitespace (spaces and tabs) at the beginning of a logical line is used
to compute the indentation level of the line, which in turn is used to determine
the grouping of statements.

Tabs are replaced (from left to right) by one to eight spaces such that the
total number of characters up to and including the replacement is a multiple of
eight (this is intended to be the same rule as used by Unix).  The total number
of spaces preceding the first non-blank character then determines the line's
indentation.  Indentation cannot be split over multiple physical lines using
backslashes; the whitespace up to the first backslash determines the
indentation.

Indentation is rejected as inconsistent if a source file mixes tabs and spaces
in a way that makes the meaning dependent on the worth of a tab in spaces; a
@ref{75e,,TabError} is raised in that case.

`Cross-platform compatibility note:' because of the nature of text editors on
non-UNIX platforms, it is unwise to use a mixture of spaces and tabs for the
indentation in a single source file.  It should also be noted that different
platforms may explicitly limit the maximum indentation level.

A formfeed character may be present at the start of the line; it will be ignored
for the indentation calculations above.  Formfeed characters occurring elsewhere
in the leading whitespace have an undefined effect (for instance, they may reset
the space count to zero).

@geindex INDENT token（縮排標誌）
@geindex DEDENT token（縮排標誌）

The indentation levels of consecutive lines are used to generate
@ref{1fc3,,INDENT} and @ref{2176,,DEDENT} tokens, using a stack,
as follows.

Before the first line of the file is read, a single zero is pushed on the stack;
this will never be popped off again.  The numbers pushed on the stack will
always be strictly increasing from bottom to top.  At the beginning of each
logical line, the line's indentation level is compared to the top of the stack.
If it is equal, nothing happens. If it is larger, it is pushed on the stack, and
one @code{INDENT} token is generated.  If it is smaller, it `must' be one of the
numbers occurring on the stack; all numbers on the stack that are larger are
popped off, and for each number popped off a @code{DEDENT} token is generated.
At the end of the file, a @code{DEDENT} token is generated for each number
remaining on the stack that is larger than zero.

Here is an example of a correctly (though confusingly) indented piece of Python
code:

@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

The following example shows various indentation errors:

@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

(Actually, the first three errors are detected by the parser; only the last
error is found by the lexical analyzer --- the indentation of @code{return r} does
not match a level popped off the stack.)

@node Whitespace between tokens,End marker,Indentation,Line structure
@anchor{reference/lexical_analysis whitespace}@anchor{2157}@anchor{reference/lexical_analysis whitespace-between-tokens}@anchor{2177}
@subsubsection Whitespace between 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.  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 End marker,,Whitespace between tokens,Line structure
@anchor{reference/lexical_analysis end-marker}@anchor{2178}@anchor{reference/lexical_analysis endmarker-token}@anchor{2166}
@subsubsection End marker


At the end of non-interactive input, the lexical analyzer generates an
@ref{2179,,ENDMARKER} token.

@node Other tokens,Names identifiers and keywords,Line structure,詞法分析
@anchor{reference/lexical_analysis id8}@anchor{217a}@anchor{reference/lexical_analysis other-tokens}@anchor{217b}
@subsection Other tokens


Besides @ref{2158,,NEWLINE}, @ref{1fc3,,INDENT} and @ref{2176,,DEDENT},
the following categories of tokens exist:
`identifiers' and `keywords' (@ref{217c,,NAME}), `literals' (such as
@ref{217d,,NUMBER} and @ref{217e,,STRING}), and other symbols
(`operators' and `delimiters', @ref{214e,,OP}).
Whitespace characters (other than logical line terminators, discussed earlier)
are not tokens, but serve to delimit tokens.
Where ambiguity exists, a token comprises the longest possible string that
forms a legal token, when read from left to right.

@node Names identifiers and keywords,Literals,Other tokens,詞法分析
@anchor{reference/lexical_analysis identifiers}@anchor{2164}@anchor{reference/lexical_analysis names-identifiers-and-keywords}@anchor{217f}
@subsection Names (identifiers and keywords)


@geindex identifier（識別器）
@geindex name（名稱）

@ref{217c,,NAME} tokens represent `identifiers', `keywords', and
`soft keywords'.

Within the ASCII range (U+0001..U+007F), the valid characters for names
include the uppercase and lowercase letters (@code{A-Z} and @code{a-z}),
the underscore @code{_} and, except for the first character, the digits
@code{0} through @code{9}.

Names must contain at least one character, but have no upper length limit.
Case is significant.

Besides @code{A-Z}, @code{a-z}, @code{_} and @code{0-9}, names can also use "letter-like"
and "number-like" characters from outside the ASCII range, as detailed below.

All identifiers are converted into the normalization form@footnote{https://www.unicode.org/reports/tr15/#Norm_Forms} NFKC while
parsing; comparison of identifiers is based on NFKC.

Formally, the first character of a normalized identifier must belong to the
set @code{id_start}, which is the union of:


@itemize *

@item 
Unicode category @code{<Lu>} - uppercase letters (includes @code{A} to @code{Z})

@item 
Unicode category @code{<Ll>} - lowercase letters (includes @code{a} to @code{z})

@item 
Unicode category @code{<Lt>} - titlecase letters

@item 
Unicode category @code{<Lm>} - modifier letters

@item 
Unicode category @code{<Lo>} - other letters

@item 
Unicode category @code{<Nl>} - letter numbers

@item 
@{@code{"_"}@} - 底線

@item 
@code{<Other_ID_Start>} - an explicit set of characters in PropList.txt@footnote{https://www.unicode.org/Public/16.0.0/ucd/PropList.txt}
to support backwards compatibility
@end itemize

The remaining characters must belong to the set @code{id_continue}, which is the
union of:


@itemize *

@item 
all characters in @code{id_start}

@item 
Unicode category @code{<Nd>} - decimal numbers (includes @code{0} to @code{9})

@item 
Unicode category @code{<Pc>} - connector punctuations

@item 
Unicode category @code{<Mn>} - nonspacing marks

@item 
Unicode category @code{<Mc>} - spacing combining marks

@item 
@code{<Other_ID_Continue>} - another explicit set of characters in
PropList.txt@footnote{https://www.unicode.org/Public/16.0.0/ucd/PropList.txt} to support backwards compatibility
@end itemize

Unicode categories use the version of the Unicode Character Database as
included in the @ref{10b,,unicodedata} module.

These sets are based on the Unicode standard annex UAX-31@footnote{https://www.unicode.org/reports/tr31/}.
See also 
@geindex Python Enhancement Proposals; PEP 3131
PEP 3131@footnote{https://peps.python.org/pep-3131/} for further details.

Even more formally, names are described by the following lexical definitions:

@example
@anchor{reference/lexical_analysis grammar-token-python-grammar-NAME}@anchor{2180}NAME:         @ref{2181,,xid_start} @ref{2182,,xid_continue}*
@anchor{reference/lexical_analysis grammar-token-python-grammar-id_start}@anchor{2183}id_start:     <Lu> | <Ll> | <Lt> | <Lm> | <Lo> | <Nl> | "_" | <Other_ID_Start>
@anchor{reference/lexical_analysis grammar-token-python-grammar-id_continue}@anchor{2184}id_continue:  @ref{2183,,id_start} | <Nd> | <Pc> | <Mn> | <Mc> | <Other_ID_Continue>
@anchor{reference/lexical_analysis grammar-token-python-grammar-xid_start}@anchor{2181}xid_start:    <all characters in @ref{2183,,id_start} whose NFKC normalization is
               in (@ref{2183,,id_start} @ref{2182,,xid_continue}*)">
@anchor{reference/lexical_analysis grammar-token-python-grammar-xid_continue}@anchor{2182}xid_continue: <all characters in @ref{2184,,id_continue} whose NFKC normalization is
               in (@ref{2184,,id_continue}*)">
@anchor{reference/lexical_analysis grammar-token-python-grammar-identifier}@anchor{2185}identifier:   <@ref{2180,,NAME}, except keywords>
@end example

A non-normative listing of all valid identifier characters as defined by
Unicode is available in the DerivedCoreProperties.txt@footnote{https://www.unicode.org/Public/16.0.0/ucd/DerivedCoreProperties.txt} file in the Unicode
Character Database.

@menu
* 關鍵字:: 
* 軟關鍵字:: 
* Reserved classes of identifiers:: 

@end menu

@node 關鍵字,軟關鍵字,,Names identifiers and keywords
@anchor{reference/lexical_analysis id9}@anchor{2186}@anchor{reference/lexical_analysis keywords}@anchor{214d}
@subsubsection 關鍵字


@geindex keyword（關鍵字）
@geindex reserved word（保留字）

The following names are used as reserved words, or `keywords' of the
language, and cannot be used as ordinary identifiers.  They must be spelled
exactly as written here:

@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 軟關鍵字,Reserved classes of identifiers,關鍵字,Names identifiers and keywords
@anchor{reference/lexical_analysis id10}@anchor{2187}@anchor{reference/lexical_analysis soft-keywords}@anchor{a06}
@subsubsection 軟關鍵字


@geindex soft keyword（軟關鍵字）
@geindex keyword（關鍵字）


在 3.10 版被加入.


Some names are only reserved under specific contexts. These are known as
`soft keywords':


@itemize -

@item 
@code{match}, @code{case}, and @code{_}, when used in the @ref{a07,,match} statement.

@item 
@code{type}, when used in the @ref{665,,type} statement.
@end itemize

These syntactically act as keywords in their specific contexts,
but this distinction is done at the parser level, not when tokenizing.

As soft keywords, their use in the grammar is possible while still
preserving compatibility with existing code that uses these names as
identifier names.


在 3.12 版的變更: @code{type} 現在是軟關鍵字。


@geindex _@comma{} identifiers（識別器）
@geindex __@comma{} identifiers（識別器）

@node Reserved classes of identifiers,,軟關鍵字,Names identifiers and keywords
@anchor{reference/lexical_analysis id-classes}@anchor{2188}@anchor{reference/lexical_analysis reserved-classes-of-identifiers}@anchor{2189}
@subsubsection Reserved classes of identifiers


Certain classes of identifiers (besides keywords) have special meanings.  These
classes are identified by the patterns of leading and trailing underscore
characters:


@table @asis

@item @code{_*}

Not imported by @code{from module import *}.

@item @code{_}

In a @code{case} pattern within a @ref{a07,,match} statement, @code{_} is a
@ref{a06,,soft keyword} that denotes a
@ref{a08,,wildcard}.

Separately, the interactive interpreter makes the result of the last evaluation
available in the variable @code{_}.
(It is stored in the @ref{13,,builtins} module, alongside built-in
functions like @code{print}.)

Elsewhere, @code{_} is a regular identifier. It is often used to name
"special" items, but it is not special to Python itself.

@cartouche
@quotation 備註 
The name @code{_} is often used in conjunction with internationalization;
refer to the documentation for the @ref{67,,gettext} module for more
information on this convention.

It is also commonly used for unused variables.
@end quotation
@end cartouche

@item @code{__*__}

System-defined names, informally known as "dunder" names. These names are
defined by the interpreter and its implementation (including the standard library).
Current system names are discussed in the @ref{e63,,Special method names} section and elsewhere.
More will likely be defined in future versions of Python.  `Any' use of @code{__*__} names,
in any context, that does not follow explicitly documented use, is subject to
breakage without warning.

@item @code{__*}

Class-private names.  Names in this category, when used within the context of a
class definition, are re-written to use a mangled form to help avoid name
clashes between "private" attributes of base and derived classes. See section
@ref{218a,,Identifiers (Names)}.
@end table

@node Literals,String and Bytes literals,Names identifiers and keywords,詞法分析
@anchor{reference/lexical_analysis id11}@anchor{218b}@anchor{reference/lexical_analysis literals}@anchor{218c}
@subsection Literals


@geindex literal（常數）
@geindex constant（常數）

Literals are notations for constant values of some built-in types.

In terms of lexical analysis, Python has @ref{2163,,string@comma{} bytes}
and @ref{2165,,numeric} literals.

Other "literals" are lexically denoted using @ref{214d,,keywords}
(@code{None}, @code{True}, @code{False}) and the special
@ref{218d,,ellipsis token} (@code{...}).

@geindex string literal（字串常數）
@geindex bytes literal（位元組常數）
@geindex ASCII
@geindex ' （單引號）;string literal（字串常數）
@geindex " （雙引號）;string literal（字串常數）

@node String and Bytes literals,Numeric literals,Literals,詞法分析
@anchor{reference/lexical_analysis string-and-bytes-literals}@anchor{218e}@anchor{reference/lexical_analysis strings}@anchor{2163}
@subsection String and Bytes literals


String literals are text enclosed in single quotes (@code{'}) or double
quotes (@code{"}). For example:

@example
"spam"
'eggs'
@end example

The quote used to start the literal also terminates it, so a string literal
can only contain the other quote (except with escape sequences, see below).
For example:

@example
'Say "Hello", please.'
"Don't do that!"
@end example

Except for this limitation, the choice of quote character (@code{'} or @code{"})
does not affect how the literal is parsed.

Inside a string literal, the backslash (@code{\}) character introduces an
`escape sequence', which has special meaning depending on the character
after the backslash.
For example, @code{\"} denotes the double quote character, and does `not' end
the string:

@example
>>> print("Say \"Hello\" to everyone!")
Say "Hello" to everyone!
@end example

See @ref{680,,escape sequences} below for a full list of such
sequences, and more details.

@geindex triple-quoted string（三引號字串）
@geindex """;string literal（字串常數）
@geindex '@w{'}';string literal（字串常數）

@menu
* 三引號字串:: 
* String prefixes:: 
* Formal grammar:: 
* 跳脫序列:: 
* 位元組常數:: 
* 原始字串常數:: 
* f-string（f 字串）:: 
* t-string（t 字串）:: 

@end menu

@node 三引號字串,String prefixes,,String and Bytes literals
@anchor{reference/lexical_analysis triple-quoted-strings}@anchor{218f}
@subsubsection 三引號字串


Strings can also be enclosed in matching groups of three single or double
quotes.
These are generally referred to as `triple-quoted strings':

@example
"""這是一個三引號字串。"""
@end example

In triple-quoted literals, unescaped quotes are allowed (and are
retained), except that three unescaped quotes in a row terminate the literal,
if they are of the same kind (@code{'} or @code{"}) used at the start:

@example
"""這個字串裡面有 "引號"。"""
@end example

Unescaped newlines are also allowed and retained:

@example
'@w{'}'This triple-quoted string
continues on the next line.'@w{'}'
@end example

@geindex u';string literal（字串常數）
@geindex u";string literal（字串常數）

@node String prefixes,Formal grammar,三引號字串,String and Bytes literals
@anchor{reference/lexical_analysis string-prefixes}@anchor{2190}
@subsubsection String prefixes


String literals can have an optional `prefix' that influences how the
content of the literal is parsed, for example:

@example
b"data"
f'@{result=@}'
@end example

The allowed prefixes are:


@itemize *

@item 
@code{b}: @ref{2191,,Bytes literal}

@item 
@code{r}: @ref{2192,,Raw string}

@item 
@code{f}: @ref{19a,,Formatted string literal} ("f-string")

@item 
@code{t}: @ref{1780,,Template string literal} ("t-string")

@item 
@code{u}: No effect (allowed for backwards compatibility)
@end itemize

See the linked sections for details on each type.

Prefixes are case-insensitive (for example, '@code{B}' works the same as '@code{b}').
The '@code{r}' prefix can be combined with '@code{f}', '@code{t}' or '@code{b}', so '@code{fr}',
'@code{rf}', '@code{tr}', '@code{rt}', '@code{br}', and '@code{rb}' are also valid prefixes.


在 3.3 版被加入: The @code{'rb'} prefix of raw bytes literals has been added as a synonym
of @code{'br'}.

Support for the unicode legacy literal (@code{u'value'}) was reintroduced
to simplify the maintenance of dual Python 2.x and 3.x codebases.
See 
@geindex Python Enhancement Proposals; PEP 414
PEP 414@footnote{https://peps.python.org/pep-0414/} for more information.


@node Formal grammar,跳脫序列,String prefixes,String and Bytes literals
@anchor{reference/lexical_analysis formal-grammar}@anchor{2193}
@subsubsection Formal grammar


String literals, except @ref{19a,,"f-strings"} and
@ref{1780,,"t-strings"}, are described by the
following lexical definitions.

These definitions use @ref{2152,,negative lookaheads} (@code{!})
to indicate that an ending quote ends the literal.

@example
@anchor{reference/lexical_analysis grammar-token-python-grammar-STRING}@anchor{2194}STRING:          [@ref{2195,,stringprefix}] (@ref{2196,,stringcontent})
@anchor{reference/lexical_analysis grammar-token-python-grammar-stringprefix}@anchor{2195}stringprefix:    <("r" | "u" | "b" | "br" | "rb"), case-insensitive>
@anchor{reference/lexical_analysis grammar-token-python-grammar-stringcontent}@anchor{2196}stringcontent:
   | "'@w{'}'" ( !"'@w{'}'" @ref{2197,,longstringitem})* "'@w{'}'"
   | '"""' ( !'"""' @ref{2197,,longstringitem})* '"""'
   | "'" ( !"'" @ref{2198,,stringitem})* "'"
   | '"' ( !'"' @ref{2198,,stringitem})* '"'
@anchor{reference/lexical_analysis grammar-token-python-grammar-stringitem}@anchor{2198}stringitem:      @ref{2199,,stringchar} | @ref{219a,,stringescapeseq}
@anchor{reference/lexical_analysis grammar-token-python-grammar-stringchar}@anchor{2199}stringchar:      <any @ref{2170,,source_character}, except backslash and newline>
@anchor{reference/lexical_analysis grammar-token-python-grammar-longstringitem}@anchor{2197}longstringitem:  @ref{2198,,stringitem} | newline
@anchor{reference/lexical_analysis grammar-token-python-grammar-stringescapeseq}@anchor{219a}stringescapeseq: "\" <any @ref{2170,,source_character}>
@end example

Note that as in all lexical definitions, whitespace is significant.
In particular, the prefix (if any) must be immediately followed by the starting
quote.

@geindex physical line（物理列）
@geindex escape sequence（跳脫序列）
@geindex Standard C（標準 C）
@geindex C
@geindex \ （反斜線）;escape sequence（跳脫序列）
@geindex \\;escape sequence（跳脫序列）
@geindex \a;escape sequence（跳脫序列）
@geindex \b;escape sequence（跳脫序列）
@geindex \f;escape sequence（跳脫序列）
@geindex \n;escape sequence（跳脫序列）
@geindex \r;escape sequence（跳脫序列）
@geindex \t;escape sequence（跳脫序列）
@geindex \v;escape sequence（跳脫序列）
@geindex \x;escape sequence（跳脫序列）
@geindex \N;escape sequence（跳脫序列）
@geindex \u;escape sequence（跳脫序列）
@geindex \U;escape sequence（跳脫序列）

@node 跳脫序列,位元組常數,Formal grammar,String and Bytes literals
@anchor{reference/lexical_analysis escape-sequences}@anchor{680}@anchor{reference/lexical_analysis id12}@anchor{219b}
@subsubsection 跳脫序列


Unless an '@code{r}' or '@code{R}' prefix is present, escape sequences in string and
bytes literals are interpreted according to rules similar to those used by
Standard C.  The recognized escape sequences are:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Escape Sequence

@tab

含義

@item

@code{\}<newline>

@tab

@ref{219c,,Ignored end of line}

@item

@code{\\}

@tab

@ref{219d,,Backslash}

@item

@code{\'}

@tab

@ref{219d,,Single quote}

@item

@code{\"}

@tab

@ref{219d,,Double quote}

@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{219e,,八進位字元}

@item

@code{\x@var{hh}}

@tab

@ref{219f,,十六進位字元}

@item

@code{\N@{@var{name}@}}

@tab

@ref{21a0,,Named Unicode character}

@item

@code{\u@var{xxxx}}

@tab

@ref{21a1,,Hexadecimal Unicode character}

@item

@code{\U@var{xxxxxxxx}}

@tab

@ref{21a1,,Hexadecimal Unicode character}

@end multitable


@menu
* Ignored end of line:: 
* 跳脫字元:: 
* 八進位字元:: 
* 十六進位字元:: 
* Named Unicode character:: 
* 十六進位 Unicode 字元:: 
* 無法辨識的跳脫序列:: 

@end menu

@node Ignored end of line,跳脫字元,,跳脫序列
@anchor{reference/lexical_analysis ignored-end-of-line}@anchor{21a2}@anchor{reference/lexical_analysis string-escape-ignore}@anchor{219c}
@subsubsection Ignored end of line


A backslash can be added at the end of a line to ignore the newline:

@example
>>> 'This string will not include \
... backslashes or newline characters.'
'This string will not include backslashes or newline characters.'
@end example

The same result can be achieved using @ref{2163,,triple-quoted strings},
or parentheses and @ref{21a3,,string literal concatenation}.

@node 跳脫字元,八進位字元,Ignored end of line,跳脫序列
@anchor{reference/lexical_analysis escaped-characters}@anchor{21a4}@anchor{reference/lexical_analysis string-escape-escaped-char}@anchor{219d}
@subsubsection 跳脫字元


To include a backslash in a non-@ref{2192,,raw} Python string
literal, it must be doubled. The @code{\\} escape sequence denotes a single
backslash character:

@example
>>> print('C:\\Program Files')
C:\Program Files
@end example

Similarly, the @code{\'} and @code{\"} sequences denote the single and double
quote character, respectively:

@example
>>> print('\' and \"')
' and "
@end example

@node 八進位字元,十六進位字元,跳脫字元,跳脫序列
@anchor{reference/lexical_analysis octal-character}@anchor{21a5}@anchor{reference/lexical_analysis string-escape-oct}@anchor{219e}
@subsubsection 八進位字元


The sequence @code{\@var{ooo}} denotes a `character' with the octal (base 8)
value `ooo':

@example
>>> '\120'
'P'
@end example

Up to three octal digits (0 through 7) are accepted.

In a bytes literal, `character' means a `byte' with the given value.
In a string literal, it means a Unicode character with the given value.


在 3.11 版的變更: Octal escapes with value larger than @code{0o377} (255) produce a
@ref{1a3,,DeprecationWarning}.



在 3.12 版的變更: Octal escapes with value larger than @code{0o377} (255) produce a
@ref{1ae,,SyntaxWarning}.
In a future Python version they will raise a @ref{18e,,SyntaxError}.


@node 十六進位字元,Named Unicode character,八進位字元,跳脫序列
@anchor{reference/lexical_analysis hexadecimal-character}@anchor{21a6}@anchor{reference/lexical_analysis string-escape-hex}@anchor{219f}
@subsubsection 十六進位字元


The sequence @code{\x@var{hh}} denotes a `character' with the hex (base 16)
value `hh':

@example
>>> '\x50'
'P'
@end example

與標準 C 不同，這裡需要剛好兩個十六進位數字。

In a bytes literal, `character' means a `byte' with the given value.
In a string literal, it means a Unicode character with the given value.

@node Named Unicode character,十六進位 Unicode 字元,十六進位字元,跳脫序列
@anchor{reference/lexical_analysis named-unicode-character}@anchor{21a7}@anchor{reference/lexical_analysis string-escape-named}@anchor{21a0}
@subsubsection Named Unicode character


The sequence @code{\N@{@var{name}@}} denotes a Unicode character
with the given `name':

@example
>>> '\N@{LATIN CAPITAL LETTER P@}'
'P'
>>> '\N@{SNAKE@}'
'🐍'
@end example

This sequence cannot appear in @ref{2191,,bytes literals}.


在 3.3 版的變更: 已新增對名稱別名 (name alias)@footnote{https://www.unicode.org/Public/16.0.0/ucd/NameAliases.txt}的支援。


@node 十六進位 Unicode 字元,無法辨識的跳脫序列,Named Unicode character,跳脫序列
@anchor{reference/lexical_analysis hexadecimal-unicode-characters}@anchor{21a8}@anchor{reference/lexical_analysis string-escape-long-hex}@anchor{21a1}
@subsubsection 十六進位 Unicode 字元


These sequences @code{\u@var{xxxx}} and @code{\U@var{xxxxxxxx}} denote the
Unicode character with the given hex (base 16) value.
Exactly four digits are required for @code{\u}; exactly eight digits are
required for @code{\U}.
The latter can encode any Unicode character.

@example
>>> '\u1234'
'ሴ'
>>> '\U0001f40d'
'🐍'
@end example

These sequences cannot appear in @ref{2191,,bytes literals}.

@geindex unrecognized escape sequence（無法辨識的跳脫序列）

@node 無法辨識的跳脫序列,,十六進位 Unicode 字元,跳脫序列
@anchor{reference/lexical_analysis unrecognized-escape-sequences}@anchor{21a9}
@subsubsection 無法辨識的跳脫序列


Unlike in Standard C, all unrecognized escape sequences are left in the string
unchanged, that is, `the backslash is left in the result':

@example
>>> print('\q')
\q
>>> list('\q')
['\\', 'q']
@end example

Note that for bytes literals, the escape sequences only recognized in string
literals (@code{\N...}, @code{\u...}, @code{\U...}) fall into the category of
unrecognized escapes.


在 3.6 版的變更: Unrecognized escape sequences produce a @ref{1a3,,DeprecationWarning}.



在 3.12 版的變更: Unrecognized escape sequences produce a @ref{1ae,,SyntaxWarning}.
In a future Python version they will raise a @ref{18e,,SyntaxError}.


@geindex b';bytes literal（位元組常數）
@geindex b";bytes literal（位元組常數）

@node 位元組常數,原始字串常數,跳脫序列,String and Bytes literals
@anchor{reference/lexical_analysis bytes-literal}@anchor{2191}@anchor{reference/lexical_analysis bytes-literals}@anchor{21aa}
@subsubsection 位元組常數


`Bytes literals' are always prefixed with '@code{b}' or '@code{B}'; they produce an
instance of the @ref{192,,bytes} type instead of the @ref{169,,str} type.
They may only contain ASCII characters; bytes with a numeric value of 128
or greater must be expressed with escape sequences (typically
@ref{219f,,十六進位字元} or @ref{219e,,八進位字元}):

@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

Similarly, a zero byte must be expressed using an escape sequence (typically
@code{\0} or @code{\x00}).

@geindex r';raw string literal（原始字串常數）
@geindex r";raw string literal（原始字串常數）

@node 原始字串常數,f-string（f 字串）,位元組常數,String and Bytes literals
@anchor{reference/lexical_analysis raw-string-literals}@anchor{21ab}@anchor{reference/lexical_analysis raw-strings}@anchor{2192}
@subsubsection 原始字串常數


Both string and bytes literals may optionally be prefixed with a letter '@code{r}'
or '@code{R}'; such constructs are called `raw string literals'
and `raw bytes literals' respectively and treat backslashes as
literal characters.
As a result, in raw string literals, @ref{680,,escape sequences}
are not treated specially:

@example
>>> r'\d@{4@}-\d@{2@}-\d@{2@}'
'\\d@{4@}-\\d@{2@}-\\d@{2@}'
@end example

Even in a raw literal, quotes can be escaped with a backslash, but the
backslash remains in the result; for example, @code{r"\""} is a valid string
literal consisting of two characters: a backslash and a double quote; @code{r"\"}
is not a valid string literal (even a raw string cannot end in an odd number of
backslashes).  Specifically, `a raw literal cannot end in a single backslash'
(since the backslash would escape the following quote character).  Note also
that a single backslash followed by a newline is interpreted as those two
characters as part of the literal, `not' as a line continuation.

@geindex formatted string literal（格式化字串常數）
@geindex interpolated string literal（插值字串常數）
@geindex string（字串）;formatted literal（格式化常數）
@geindex string（字串）;interpolated literal（插值常數）
@geindex f-string（f 字串）
@geindex fstring（f 字串）
@geindex f';formatted string literal（格式化字串常數）
@geindex f";formatted string literal（格式化字串常數）
@geindex @{@} （花括號）;於格式化字串常數中
@geindex ! （驚嘆號）;於格式化字串常數中
@geindex ; （冒號）;於格式化字串常數中
@geindex = （等號）;for help in debugging using string literals（使用字串常數進行除錯）
@anchor{reference/lexical_analysis f-strings}@anchor{19a}
@node f-string（f 字串）,t-string（t 字串）,原始字串常數,String and Bytes literals
@anchor{reference/lexical_analysis formatted-string-literals}@anchor{21ac}@anchor{reference/lexical_analysis id13}@anchor{21ad}
@subsubsection f-string（f 字串）



在 3.6 版被加入.


A `formatted string literal' or `f-string' is a string literal
that is prefixed with '@code{f}' or '@code{F}'.  These strings may contain
replacement fields, which are expressions delimited by curly braces @code{@{@}}.
While other string literals always have a constant value, formatted strings
are really expressions evaluated at run time.

Escape sequences are decoded like in ordinary string literals (except when
a literal is also marked as a raw string).  After decoding, the grammar
for the contents of the string is:

@example
@anchor{reference/lexical_analysis grammar-token-python-grammar-f_string}@anchor{21ae}f_string:          (@ref{21af,,literal_char} | "@{@{" | "@}@}" | @ref{21b0,,replacement_field})*
@anchor{reference/lexical_analysis grammar-token-python-grammar-replacement_field}@anchor{21b0}replacement_field: "@{" @ref{21b1,,f_expression} ["="] ["!" @ref{21b2,,conversion}] [":" @ref{21b3,,format_spec}] "@}"
@anchor{reference/lexical_analysis grammar-token-python-grammar-f_expression}@anchor{21b1}f_expression:      (@ref{21b4,,conditional_expression} | "*" @ref{21b5,,or_expr})
                     ("," @ref{21b4,,conditional_expression} | "," "*" @ref{21b5,,or_expr})* [","]
                   | @ref{21b6,,yield_expression}
@anchor{reference/lexical_analysis grammar-token-python-grammar-conversion}@anchor{21b2}conversion:        "s" | "r" | "a"
@anchor{reference/lexical_analysis grammar-token-python-grammar-format_spec}@anchor{21b3}format_spec:       (@ref{21af,,literal_char} | @ref{21b0,,replacement_field})*
@anchor{reference/lexical_analysis grammar-token-python-grammar-literal_char}@anchor{21af}literal_char:      <any code point except "@{", "@}" or NULL>
@end example

The parts of the string outside curly braces are treated literally,
except that any doubled curly braces @code{'@{@{'} or @code{'@}@}'} are replaced
with the corresponding single curly brace.  A single opening curly
bracket @code{'@{'} marks a replacement field, which starts with a
Python expression. To display both the expression text and its value after
evaluation, (useful in debugging), an equal sign @code{'='} may be added after the
expression. A conversion field, introduced by an exclamation point @code{'!'} may
follow.  A format specifier may also be appended, introduced by a colon @code{':'}.
A replacement field ends with a closing curly bracket @code{'@}'}.

Expressions in formatted string literals are treated like regular
Python expressions surrounded by parentheses, with a few exceptions.
An empty expression is not allowed, and both @ref{149e,,lambda}  and
assignment expressions @code{:=} must be surrounded by explicit parentheses.
Each expression is evaluated in the context where the formatted string literal
appears, in order from left to right.  Replacement expressions can contain
newlines in both single-quoted and triple-quoted f-strings and they can contain
comments.  Everything that comes after a @code{#} inside a replacement field
is a comment (even closing braces and quotes). In that case, replacement fields
must be closed in a different line.

@example
>>> f"abc@{a # This is a comment @}"
... + 3@}"
'abc5'
@end example


在 3.7 版的變更: Prior to Python 3.7, an @ref{18d,,await} expression and comprehensions
containing an @ref{c98,,async for} clause were illegal in the expressions
in formatted string literals due to a problem with the implementation.



在 3.12 版的變更: Prior to Python 3.12, comments were not allowed inside f-string replacement
fields.


When the equal sign @code{'='} is provided, the output will have the expression
text, the @code{'='} and the evaluated value. Spaces after the opening brace
@code{'@{'}, within the expression and after the @code{'='} are all retained in the
output. By default, the @code{'='} causes the @ref{1c1,,repr()} of the expression to be
provided, unless there is a format specified. When a format is specified it
defaults to the @ref{169,,str()} of the expression unless a conversion @code{'!r'} is
declared.


在 3.8 版被加入: 等號 @code{'='}。


If a conversion is specified, the result of evaluating the expression
is converted before formatting.  Conversion @code{'!s'} calls @ref{169,,str()} on
the result, @code{'!r'} calls @ref{1c1,,repr()}, and @code{'!a'} calls @ref{15dd,,ascii()}.

The result is then formatted using the @ref{199,,format()} protocol.  The
format specifier is passed to the @ref{82a,,__format__()} method of the
expression or conversion result.  An empty string is passed when the
format specifier is omitted.  The formatted result is then included in
the final value of the whole string.

Top-level format specifiers may include nested replacement fields. These nested
fields may include their own conversion fields and @ref{4f4,,format specifiers}, but may not include more deeply nested replacement fields. The
@ref{4f4,,format specifier mini-language} is the same as that used by
the @ref{82c,,str.format()} method.

Formatted string literals may be concatenated, but replacement fields
cannot be split across literals.

Some examples of formatted string literals:

@example
>>> name = "Fred"
>>> f"He said his name is @{name!r@}."
"He said his name is 'Fred'."
>>> f"He said his name is @{repr(name)@}."  # repr() is equivalent to !r
"He said his name is 'Fred'."
>>> width = 10
>>> precision = 4
>>> value = decimal.Decimal("12.34567")
>>> f"result: @{value:@{width@}.@{precision@}@}"  # nested fields
'result:      12.35'
>>> today = datetime(year=2017, month=1, day=27)
>>> f"@{today:%B %d, %Y@}"  # using date format specifier
'January 27, 2017'
>>> f"@{today=:%B %d, %Y@}" # using date format specifier and debugging
'today=January 27, 2017'
>>> number = 1024
>>> f"@{number:#0x@}"  # using integer format specifier
'0x400'
>>> foo = "bar"
>>> f"@{ foo = @}" # preserves whitespace
" foo = 'bar'"
>>> line = "The mill's closed"
>>> f"@{line = @}"
'line = "The mill\'s closed"'
>>> f"@{line = :20@}"
"line = The mill's closed   "
>>> f"@{line = !r:20@}"
'line = "The mill\'s closed" '
@end example

Reusing the outer f-string quoting type inside a replacement field is
permitted:

@example
>>> a = dict(x=2)
>>> f"abc @{a["x"]@} def"
'abc 2 def'
@end example


在 3.12 版的變更: Prior to Python 3.12, reuse of the same quoting type of the outer f-string
inside a replacement field was not possible.


Backslashes are also allowed in replacement fields and are evaluated the same
way as in any other context:

@example
>>> a = ["a", "b", "c"]
>>> print(f"List a contains:\n@{"\n".join(a)@}")
List a contains:
a
b
c
@end example


在 3.12 版的變更: Prior to Python 3.12, backslashes were not permitted inside an f-string
replacement field.


Formatted string literals cannot be used as docstrings, even if they do not
include expressions.

@example
>>> def foo():
...     f"Not a docstring"
...
>>> foo.__doc__ is None
True
@end example

See also 
@geindex Python Enhancement Proposals; PEP 498
PEP 498@footnote{https://peps.python.org/pep-0498/} for the proposal that added formatted string literals,
and @ref{82c,,str.format()}, which uses a related format string mechanism.
@anchor{reference/lexical_analysis t-strings}@anchor{1780}
@node t-string（t 字串）,,f-string（f 字串）,String and Bytes literals
@anchor{reference/lexical_analysis id14}@anchor{21b7}@anchor{reference/lexical_analysis template-string-literals}@anchor{21b8}
@subsubsection t-string（t 字串）



在 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 and evaluation rules as
@ref{19a,,formatted string literals}, with the following differences:


@itemize *

@item 
Rather than evaluating to a @code{str} object, template string literals evaluate
to a @ref{16a,,string.templatelib.Template} object.

@item 
The @ref{199,,format()} protocol is not used.
Instead, the format specifier and conversions (if any) are passed to
a new @ref{16b,,Interpolation} object that is created
for each evaluated expression.
It is up to code that processes the resulting @ref{16a,,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{16b,,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{21b9,,conversion} will
be set to '@code{r}' (@ref{1c1,,repr()}) by default.
If an explicit conversion or format specifier are provided,
this will override the default behaviour.
@end itemize

@node Numeric literals,Operators and delimiters,String and Bytes literals,詞法分析
@anchor{reference/lexical_analysis numbers}@anchor{2165}@anchor{reference/lexical_analysis numeric-literals}@anchor{21ba}
@subsection Numeric literals


@geindex number（數字）
@geindex numeric literal（數值常數）
@geindex integer literal（整數常數）
@geindex floating-point literal（浮點數常數）
@geindex hexadecimal literal（十六進位常數）
@geindex octal literal（八進位常數）
@geindex binary literal（二進位常數）
@geindex decimal literal（十進位常數）
@geindex imaginary literal（虛數常數）
@geindex complex literal（複數常數）

@ref{217d,,NUMBER} tokens represent numeric literals, of which there are
three types: integers, floating-point numbers, and imaginary numbers.

@example
@anchor{reference/lexical_analysis grammar-token-python-grammar-NUMBER}@anchor{21bb}NUMBER: @ref{21bc,,integer} | @ref{21bd,,floatnumber} | @ref{21be,,imagnumber}
@end example

The numeric value of a numeric literal is the same as if it were passed as a
string to the @ref{19b,,int}, @ref{196,,float} or @ref{197,,complex} class
constructor, respectively.
Note that not all valid inputs for those constructors are also valid literals.

Numeric literals do not include a sign; a phrase like @code{-1} is
actually an expression composed of the unary operator '@code{-}' and the literal
@code{1}.

@geindex 0b;integer literal（整數常數）
@geindex 0o;integer literal（整數常數）
@geindex 0x;integer literal（整數常數）
@geindex _ （底線）;於數值常數中

@menu
* Integer literals:: 
* 浮點數常數 (Floating-point literals): 浮點數常數 Floating-point literals. 
* Imaginary literals:: 

@end menu

@node Integer literals,浮點數常數 Floating-point literals,,Numeric literals
@anchor{reference/lexical_analysis integer-literals}@anchor{21bf}@anchor{reference/lexical_analysis integers}@anchor{21c0}
@subsubsection Integer literals


Integer literals denote whole numbers. For example:

@example
7
3
2147483647
@end example

There is no limit for the length of integer literals apart from what can be
stored in available memory:

@example
7922816251426433759354395033679228162514264337593543950336
@end example

Underscores can be used to group digits for enhanced readability,
and are ignored for determining the numeric value of the literal.
For example, the following literals are equivalent:

@example
100_000_000_000
100000000000
1_00_00_00_00_000
@end example

Underscores can only occur between digits.
For example, @code{_123}, @code{321_}, and @code{123__321} are `not' valid literals.

Integers can be specified in binary (base 2), octal (base 8), or hexadecimal
(base 16) using the prefixes @code{0b}, @code{0o} and @code{0x}, respectively.
Hexadecimal digits 10 through 15 are represented by letters @code{A}-@code{F},
case-insensitive.  For example:

@example
0b100110111
0b_1110_0101
0o177
0o377
0xdeadbeef
0xDead_Beef
@end example

An underscore can follow the base specifier.
For example, @code{0x_1f} is a valid literal, but @code{0_x1f} and @code{0x__1f} are
not.

Leading zeros in a non-zero decimal number are not allowed.
For example, @code{0123} is not a valid literal.
This is for disambiguation with C-style octal literals, which Python used
before version 3.0.

Formally, integer literals are described by the following lexical definitions:

@example
@anchor{reference/lexical_analysis grammar-token-python-grammar-integer}@anchor{21bc}integer:      @ref{21c1,,decinteger} | @ref{21c2,,bininteger} | @ref{21c3,,octinteger} | @ref{21c4,,hexinteger} | @ref{21c5,,zerointeger}
@anchor{reference/lexical_analysis grammar-token-python-grammar-decinteger}@anchor{21c1}decinteger:   @ref{21c6,,nonzerodigit} (["_"] @ref{21c7,,digit})*
@anchor{reference/lexical_analysis grammar-token-python-grammar-bininteger}@anchor{21c2}bininteger:   "0" ("b" | "B") (["_"] @ref{21c8,,bindigit})+
@anchor{reference/lexical_analysis grammar-token-python-grammar-octinteger}@anchor{21c3}octinteger:   "0" ("o" | "O") (["_"] @ref{21c9,,octdigit})+
@anchor{reference/lexical_analysis grammar-token-python-grammar-hexinteger}@anchor{21c4}hexinteger:   "0" ("x" | "X") (["_"] @ref{21ca,,hexdigit})+
@anchor{reference/lexical_analysis grammar-token-python-grammar-zerointeger}@anchor{21c5}zerointeger:  "0"+ (["_"] "0")*
@anchor{reference/lexical_analysis grammar-token-python-grammar-nonzerodigit}@anchor{21c6}nonzerodigit: "1"..."9"
@anchor{reference/lexical_analysis grammar-token-python-grammar-digit}@anchor{21c7}digit:        "0"..."9"
@anchor{reference/lexical_analysis grammar-token-python-grammar-bindigit}@anchor{21c8}bindigit:     "0" | "1"
@anchor{reference/lexical_analysis grammar-token-python-grammar-octdigit}@anchor{21c9}octdigit:     "0"..."7"
@anchor{reference/lexical_analysis grammar-token-python-grammar-hexdigit}@anchor{21ca}hexdigit:     @ref{21c7,,digit} | "a"..."f" | "A"..."F"
@end example


在 3.6 版的變更: Underscores are now allowed for grouping purposes in literals.


@geindex . （點）;於數值常數中
@geindex e;於數值常數中
@geindex _ （底線）;於數值常數中

@node 浮點數常數 Floating-point literals,Imaginary literals,Integer literals,Numeric literals
@anchor{reference/lexical_analysis floating}@anchor{21cb}@anchor{reference/lexical_analysis floating-point-literals}@anchor{21cc}
@subsubsection 浮點數常數 (Floating-point literals)


Floating-point (float) literals, such as @code{3.14} or @code{1.5}, denote
@ref{21cd,,approximations of real numbers}.

They consist of `integer' and `fraction' parts, each composed of decimal digits.
The parts are separated by a decimal point, @code{.}:

@example
2.71828
4.0
@end example

Unlike in integer literals, leading zeros are allowed.
For example, @code{077.010} is legal, and denotes the same number as @code{77.01}.

As in integer literals, single underscores may occur between digits to help
readability:

@example
96_485.332_123
3.14_15_93
@end example

Either of these parts, but not both, can be empty. For example:

@example
10.  # （相當於 10.0）
.001  # （相當於 0.001）
@end example

Optionally, the integer and fraction may be followed by an `exponent':
the letter @code{e} or @code{E}, followed by an optional sign, @code{+} or @code{-},
and a number in the same format as the integer and fraction parts.
The @code{e} or @code{E} represents "times ten raised to the power of":

@example
1.0e3  # (represents 1.0×10³, or 1000.0)
1.166e-5  # (represents 1.166×10⁻⁵, or 0.00001166)
6.02214076e+23  # (represents 6.02214076×10²³, or 602214076000000000000000.)
@end example

In floats with only integer and exponent parts, the decimal point may be
omitted:

@example
1e3  # （相當於 1.e3 和 1.0e3）
0e0  # （相當於 0.）
@end example

Formally, floating-point literals are described by the following
lexical definitions:

@example
@anchor{reference/lexical_analysis grammar-token-python-grammar-floatnumber}@anchor{21bd}floatnumber:
   | @ref{21ce,,digitpart} "." [@ref{21ce,,digitpart}] [@ref{21cf,,exponent}]
   | "." @ref{21ce,,digitpart} [@ref{21cf,,exponent}]
   | @ref{21ce,,digitpart} @ref{21cf,,exponent}
@anchor{reference/lexical_analysis grammar-token-python-grammar-digitpart}@anchor{21ce}digitpart: @ref{21c7,,digit} (["_"] @ref{21c7,,digit})*
@anchor{reference/lexical_analysis grammar-token-python-grammar-exponent}@anchor{21cf}exponent:  ("e" | "E") ["+" | "-"] @ref{21ce,,digitpart}
@end example


在 3.6 版的變更: Underscores are now allowed for grouping purposes in literals.


@geindex j;於數值常數中

@node Imaginary literals,,浮點數常數 Floating-point literals,Numeric literals
@anchor{reference/lexical_analysis imaginary}@anchor{21d0}@anchor{reference/lexical_analysis imaginary-literals}@anchor{21d1}
@subsubsection Imaginary literals


Python has @ref{1ea3,,complex number} objects, but no complex
literals.
Instead, `imaginary literals' denote complex numbers with a zero
real part.

For example, in math, the complex number 3+4.2`i' is written
as the real number 3 added to the imaginary number 4.2`i'.
Python uses a similar syntax, except the imaginary unit is written as @code{j}
rather than `i':

@example
3+4.2j
@end example

This is an expression composed
of the @ref{21c0,,integer literal} @code{3},
the @ref{2150,,operator} '@code{+}',
and the @ref{21d0,,imaginary literal} @code{4.2j}.
Since these are three separate tokens, whitespace is allowed between them:

@example
3 + 4.2j
@end example

No whitespace is allowed `within' each token.
In particular, the @code{j} suffix, may not be separated from the number
before it.

The number before the @code{j} has the same syntax as a floating-point literal.
Thus, the following are valid imaginary literals:

@example
4.2j
3.14j
10.j
.001j
1e100j
3.14e-10j
3.14_15_93j
@end example

Unlike in a floating-point literal the decimal point can be omitted if the
imaginary number only has an integer part.
The number is still evaluated as a floating-point number, not an integer:

@example
10j
0j
1000000000000000000000000j   # 相當於 1e+24j
@end example

The @code{j} suffix is case-insensitive.
That means you can use @code{J} instead:

@example
3.14J   # equivalent to 3.14j
@end example

Formally, imaginary literals are described by the following lexical definition:

@example
@anchor{reference/lexical_analysis grammar-token-python-grammar-imagnumber}@anchor{21be}imagnumber: (@ref{21bd,,floatnumber} | @ref{21ce,,digitpart}) ("j" | "J")
@end example
@anchor{reference/lexical_analysis delimiters}@anchor{214f}@anchor{reference/lexical_analysis operators}@anchor{2150}
@node Operators and delimiters,,Numeric literals,詞法分析
@anchor{reference/lexical_analysis lexical-ellipsis}@anchor{218d}@anchor{reference/lexical_analysis operators-and-delimiters}@anchor{21d2}
@subsection Operators and delimiters


@geindex operators（運算子）
@geindex delimiters（分隔符號）

The following grammar defines `operator' and `delimiter' tokens,
that is, the generic @ref{214e,,OP} token type.
A @ref{21d3,,list of these tokens and their names}
is also available in the @code{token} module documentation.

@example
@anchor{reference/lexical_analysis grammar-token-python-grammar-OP}@anchor{21d4}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{21d5}assignment_operator:   "+=" | "-=" | "*=" | "**=" | "/="  | "//=" | "%=" |
                       "&=" | "|=" | "^=" | "<<=" | ">>=" | "@@="  | ":="
@anchor{reference/lexical_analysis grammar-token-python-grammar-bitwise_operator}@anchor{21d6}bitwise_operator:      "&"  | "|"  | "^"  | "~"   | "<<"  | ">>"
@anchor{reference/lexical_analysis grammar-token-python-grammar-comparison_operator}@anchor{21d7}comparison_operator:   "<=" | ">=" | "<"  | ">"   | "=="  | "!="
@anchor{reference/lexical_analysis grammar-token-python-grammar-enclosing_delimiter}@anchor{21d8}enclosing_delimiter:   "("  | ")"  | "["  | "]"   | "@{"   | "@}"
@anchor{reference/lexical_analysis grammar-token-python-grammar-other_delimiter}@anchor{21d9}other_delimiter:       ","  | ":"  | "!"  | ";"   | "="   | "->"
@anchor{reference/lexical_analysis grammar-token-python-grammar-arithmetic_operator}@anchor{21da}arithmetic_operator:   "+"  | "-"  | "**" | "*"   | "//"  | "/"   | "%"
@anchor{reference/lexical_analysis grammar-token-python-grammar-other_op}@anchor{21db}other_op:              "."  | "@@"
@end example

@cartouche
@quotation 備註 
Generally, `operators' are used to combine @ref{21dc,,expressions},
while `delimiters' serve other purposes.
However, there is no clear, formal distinction between the two categories.

Some tokens can serve as either operators or delimiters, depending on usage.
For example, @code{*} is both the multiplication operator and a delimiter used
for sequence unpacking, and @code{@@} is both the matrix multiplication and
a delimiter that introduces decorators.

For some tokens, the distinction is unclear.
For example, some people consider @code{.}, @code{(}, and @code{)} to be delimiters, while others
see the @ref{dc5,,getattr()} operator and the function call operator(s).

Some of Python's operators, like @code{and}, @code{or}, and @code{not in}, use
@ref{214d,,keyword} tokens rather than "symbols" (operator tokens).
@end quotation
@end cartouche

A sequence of three consecutive periods (@code{...}) has a special
meaning as an @ref{21dd,,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{21de}@anchor{reference/datamodel data-model}@anchor{21df}@anchor{reference/datamodel datamodel}@anchor{1c23}@anchor{reference/datamodel translation-repo}@anchor{21e0}
@section 資料模型


@menu
* 物件、數值和型別:: 
* 標準型別階層:: 
* Special method names:: 
* 協程:: 

@end menu

@node 物件、數值和型別,標準型別階層,,資料模型
@anchor{reference/datamodel objects}@anchor{21e1}@anchor{reference/datamodel objects-values-and-types}@anchor{21e2}
@subsection 物件、數值和型別


@geindex object（物件）
@geindex data（資料）

`物件' 是 Python 為資料的抽象表示方式。一個 Python 程式當中的所有資料皆由物件或物件之間的關係來呈現。（某種意義上，同時符合 Von Neumann 對於「儲存程式型電腦」("stored program computer") 的模型，程式碼也是以物件呈現的。）

@geindex built-in function（內建函式）;id
@geindex built-in function（內建函式）;type（型別）
@geindex identity of an object（物件的識別）
@geindex value of an object（物件的值）
@geindex type of an object（物件的型別）
@geindex mutable object（可變物件）
@geindex immutable object（不可變物件）

@c XXX it *is* now possible in some cases to change an object's
@c type, under certain controlled conditions

每個物件都有一個識別性、型別，和數值。物件的`識別性'在物件建立後永遠不會改變；你也可以把它想成是該物件在記憶體中的位址。@ref{34a,,is} 運算子會比較兩個物件的識別性是否相同；@ref{161a,,id()} 函式則會回傳代表一個該物件的識別性的整數。

在 CPython 當中，@code{id(x)} 就是 @code{x} 所儲存在的記憶體位址。

一個物件的型別決定了該物件所支援的操作（例如「它有長度嗎？」），也同時定義該型別的物件能夠擁有的數值。@ref{f3f,,type()} 函式會回傳一個物件的型別（而該型別本身也是一個物件）。如同它的識別性，一個物件的型別 (`type') 也是不可變的。@footnote{
It `is' possible in some cases to change an object's type, under certain
controlled conditions. It generally isn't a good idea though, since it can
lead to some very strange behaviour if it is handled incorrectly.
}

某些物件的`數值'可被改變，這種物件稱作「可變的」(`mutable')；建立後數值不能變更的物件則稱作「不可變的」(`immutable')。（不可變的容器物件中如果包含對於可變物件的參照，則後者的數值改變的時候前者的數值也會跟著一起改變；這種時候該容器仍會被當成是不可變的，因為它包含的物件集合仍然無法變更。因此可變或不可變嚴格說起並不等同於數值是否能被改變，它的定義有其他不明顯的細節。）一個物件是否為可變取決於它的型別；舉例來說，數字、字串和 tuple 是不可變的，而字典與串列則是可變的。

@geindex garbage collection（垃圾回收）
@geindex reference counting（參照計數）
@geindex unreachable object（不可達物件）

物件永遠不會被明示的摧毀；但當它們變得不再能夠存取的時候可能會被作為垃圾回收。每個實作都能延後垃圾回收或是乾脆忽略它 --- 垃圾回收如何進行完全取決於各個實作，只要沒有被回收的物件仍是可達的。

CPython 目前使用一種參照計數的方案，並提供可選的循環連結垃圾延遲偵測，這個方案會在大部分物件變得不可存取時馬上回收它們，但不保證能夠回收包含循環參照的垃圾。關於控制循環垃圾回收的資訊請見 @ref{64,,gc} 模組的說明文件。其他實作的行為不會相同，CPython 也有可能改變，因此請不要仰賴物件在變得不可存取時能夠馬上被最終化（亦即你應該總是明確關閉檔案）。

請注意，使用一個實作的追蹤或除錯工具可能會讓原本能夠回收的物件被維持存活。也請注意，使用 @ref{8f0,,try}...@ref{1ab,,except} 陳述式來抓捕例外也可能會讓物件維持存活。

某些物件包含對於「外部」資源的參照，像是開啟的檔案或是視窗。基本上這些資源會在物件被回收時釋放，但因為垃圾回收不保證會發生，這種物件也會提供明確釋放外部資源的方式 --- 通常是 @code{close()} method。強烈建議各個程式明確關閉這種物件。@ref{8f0,,try}...@ref{1b0,,finally} 陳述式與 @ref{186,,with} 陳述式提供進行明確關閉的方便手段。

@geindex container（容器）

某些物件包含對於其他物件的參照；這種物件被叫做「容器」。容器的範例有 tuple、串列與字典。這些參照是容器的數值的一部分。通常當我們提到容器的數值的時候，我們指的是其中包含的物件的數值，而不是它們的識別性；但當我們提到容器是否可變的時候，我們指的是直接包含在其中的物件的識別性。因此，如果一個不可變的容器（像一個 tuple）包含對於可變物件的參照，該可變物件被變更時該容器的數值也會跟著變更。

型別幾乎影響物件行為的所有面向。就連物件識別性的重要性某種程度上也受型別影響：對於不可變的型別，計算新數值的操作可能其實會回傳一個某個相同型別且相同數值的現存物件的參照；對於可變型別這則不會發生。舉例來說，在進行 @code{a = 1; b = 1} 之後，`a' 和 `b' 可能會參照同一個物件，也可能不會，取決於所使用的實作。這是因為 @ref{19b,,int} 是不可變的型別，因此 @code{1} 的參照可以重複利用。這個行為取決於所使用的實作，因此不應該依賴它，但在進行物件識別性測試的時候還是需要注意有這件事情。而在進行 @code{c = []; d = []} 之後，`c' 和 `d' 則保證會參照兩個不同、獨特、且新建立的空白串列。（請注意，@code{e = f = []} 則會將同一個物件同時指派給 `e' 和 `f'。）

@node 標準型別階層,Special method names,物件、數值和型別,資料模型
@anchor{reference/datamodel the-standard-type-hierarchy}@anchor{21e3}@anchor{reference/datamodel types}@anchor{21e4}
@subsection 標準型別階層


@geindex type（型別）
@geindex data（資料）;type（型別）
@geindex type（型別）;hierarchy（階層）
@geindex extension（擴充）;module（模組）
@geindex C;language（語言）

Below is a list of the types that are built into Python.  Extension modules
(written in C, Java, or other languages, depending on the implementation) can
define additional types.  Future versions of Python may add types to the type
hierarchy (e.g., rational numbers, efficiently stored arrays of integers, etc.),
although such additions will often be provided via the standard library instead.

@geindex attribute（屬性）
@geindex special;attribute（屬性）
@geindex generic（泛型）;special;attribute（屬性）

Some of the type descriptions below contain a paragraph listing 'special
attributes.'  These are attributes that provide access to the implementation and
are not intended for general use.  Their definition may change in the future.

@menu
* None:: 
* NotImplemented:: 
* Ellipsis:: 
* numbers.Number: numbers Number. 
* Sequences:: 
* Set（集合）型別:: 
* 對映:: 
* 可呼叫型別:: 
* 模組: 模組<2>. 
* Custom classes:: 
* 類別實例: 類別實例<2>. 
* I/O objects (also known as file objects): I/O objects also known as file objects. 
* Internal types:: 

@end menu

@node None,NotImplemented,,標準型別階層
@anchor{reference/datamodel none}@anchor{21e5}
@subsubsection None


@geindex object（物件）;None

這個型別只有一個數值。只有一個物件有這個數值。這個物件由內建名稱 @code{None} 存取。它用來在許多情況下代表數值不存在，例如沒有明確回傳任何東西的函式就會回傳這個物件。它的真值是 false。

@node NotImplemented,Ellipsis,None,標準型別階層
@anchor{reference/datamodel notimplemented}@anchor{21e6}
@subsubsection NotImplemented


@geindex object（物件）;NotImplemented

這個型別只有一個數值。只有一個物件有這個數值。這個物件由內建名稱 @ref{1a2,,NotImplemented} 存取。數字方法和 rich comparison 方法應該在沒有為所提供的運算元實作該操作的時候回傳這個數值。（直譯器接下來則會依運算子嘗試反轉的操作或是其他的後備方案。）它不應該在預期布林值的情境中被計算。

更多細節請見 @ref{21e7,,實作算術操作}。


在 3.9 版的變更: Evaluating @ref{1a2,,NotImplemented} in a boolean context was deprecated.



在 3.14 版的變更: 在預期布林值的情境中計算 @ref{1a2,,NotImplemented} 現在會引發 @ref{198,,TypeError}。它先前會計算為 @ref{e02,,True}，並自 Python 3.9 起會發出 @ref{1a3,,DeprecationWarning}。


@node Ellipsis,numbers Number,NotImplemented,標準型別階層
@anchor{reference/datamodel ellipsis}@anchor{21e8}
@subsubsection Ellipsis


@geindex object（物件）;Ellipsis
@geindex ...;ellipsis literal（刪節號字面值）

這個型別只有一個數值。只有一個物件有這個數值。這個物件由文本 @code{...} 或內建名稱 @code{Ellipsis} 存取。它的真值是 true。

@node numbers Number,Sequences,Ellipsis,標準型別階層
@anchor{reference/datamodel numbers-number}@anchor{21e9}
@subsubsection @code{numbers.Number}


@geindex object（物件）;numeric（數值）

These are created by numeric literals and returned as results by arithmetic
operators and arithmetic built-in functions.  Numeric objects are immutable;
once created their value never changes.  Python numbers are of course strongly
related to mathematical numbers, but subject to the limitations of numerical
representation in computers.

The string representations of the numeric classes, computed by
@ref{828,,__repr__()} and @ref{829,,__str__()}, have the following
properties:


@itemize *

@item 
They are valid numeric literals which, when passed to their
class constructor, produce an object having the value of the
original numeric.

@item 
The representation is in base 10, when possible.

@item 
Leading zeros, possibly excepting a single zero before a
decimal point, are not shown.

@item 
Trailing zeros, possibly excepting a single zero after a
decimal point, are not shown.

@item 
A sign is shown only when the number is negative.
@end itemize

Python distinguishes between integers, floating-point numbers, and complex
numbers:

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

@end menu

@node numbers Integral,numbers Real float,,numbers Number
@anchor{reference/datamodel numbers-integral}@anchor{21ea}
@subsubsection @code{numbers.Integral}


@geindex object（物件）;integer（整數）

These represent elements from the mathematical set of integers (positive and
negative).

@cartouche
@quotation 備註 
@geindex integer（整數）;representation（表示）

The rules for integer representation are intended to give the most meaningful
interpretation of shift and mask operations involving negative integers.
@end quotation
@end cartouche

There are two types of integers:


@table @asis

@item Integers (@ref{19b,,int})

These represent numbers in an unlimited range, subject to available (virtual)
memory only.  For the purpose of shift and mask operations, a binary
representation is assumed, and negative numbers are represented in a variant of
2's complement which gives the illusion of an infinite string of sign bits
extending to the left.

@item Booleans (@ref{3c1,,bool})

@geindex object（物件）;Boolean（布林）
@geindex False
@geindex True

These represent the truth values False and True.  The two objects representing
the values @code{False} and @code{True} are the only Boolean objects. The Boolean type is a
subtype of the integer type, and Boolean values behave like the values 0 and 1,
respectively, in almost all contexts, the exception being that when converted to
a string, the strings @code{"False"} or @code{"True"} are returned, respectively.
@end table

@node numbers Real float,numbers Complex complex,numbers Integral,numbers Number
@anchor{reference/datamodel datamodel-float}@anchor{21cd}@anchor{reference/datamodel numbers-real-float}@anchor{21eb}
@subsubsection @code{numbers.Real} (@code{float})


@geindex object（物件）;floating-point（浮點）
@geindex floating-point（浮點）;number（數字）
@geindex C;language（語言）
@geindex Java;language（語言）

These represent machine-level double precision floating-point numbers. You are
at the mercy of the underlying machine architecture (and C or Java
implementation) for the accepted range and handling of overflow. Python does not
support single-precision floating-point numbers; the savings in processor and
memory usage that are usually the reason for using these are dwarfed by the
overhead of using objects in Python, so there is no reason to complicate the
language with two kinds of floating-point numbers.

@node numbers Complex complex,,numbers Real float,numbers Number
@anchor{reference/datamodel numbers-complex-complex}@anchor{21ec}
@subsubsection @code{numbers.Complex} (@code{complex})


@geindex object（物件）;complex（複數）
@geindex complex（複數）;number（數字）

These represent complex numbers as a pair of machine-level double precision
floating-point numbers.  The same caveats apply as for floating-point numbers.
The real and imaginary parts of a complex number @code{z} can be retrieved through
the read-only attributes @code{z.real} and @code{z.imag}.

@node Sequences,Set（集合）型別,numbers Number,標準型別階層
@anchor{reference/datamodel sequences}@anchor{21ed}
@subsubsection Sequences


@geindex built-in function（內建函式）;len
@geindex object（物件）;sequence（序列）
@geindex index operation（索引操作）
@geindex item selection（項目選取）
@geindex subscription（下標）

These represent finite ordered sets indexed by non-negative numbers. The
built-in function @ref{839,,len()} returns the number of items of a sequence. When
the length of a sequence is `n', the index set contains the numbers 0, 1,
..., `n'-1.  Item `i' of sequence `a' is selected by @code{a[i]}. Some sequences,
including built-in sequences, interpret negative subscripts by adding the
sequence length. For example, @code{a[-2]} equals @code{a[n-2]}, the second to last
item of sequence a with length @code{n}.

@geindex slice（切片）

Sequences also support slicing: @code{a[i:j]} selects all items with index `k' such
that `i' @code{<=} `k' @code{<} `j'.  When used as an expression, a slice is a
sequence of the same type. The comment above about negative indexes also applies
to negative slice positions.

Some sequences also support "extended slicing" with a third "step" parameter:
@code{a[i:j:k]} selects all items of `a' with index `x' where @code{x = i + n*k}, `n'
@code{>=} @code{0} and `i' @code{<=} `x' @code{<} `j'.

Sequences are distinguished according to their mutability:

@menu
* Immutable sequences:: 
* 可變序列:: 

@end menu

@node Immutable sequences,可變序列,,Sequences
@anchor{reference/datamodel immutable-sequences}@anchor{21ee}
@subsubsection Immutable sequences


@geindex object（物件）;immutable sequence（不可變序列）
@geindex object（物件）;immutable（不可變）

An object of an immutable sequence type cannot change once it is created.  (If
the object contains references to other objects, these other objects may be
mutable and may be changed; however, the collection of objects directly
referenced by an immutable object cannot change.)

The following types are immutable sequences:

@geindex string（字串）;immutable sequences（不可變序列）


@table @asis

@item 字串 (String)

@geindex built-in function（內建函式）;chr
@geindex built-in function（內建函式）;ord
@geindex character（字元）
@geindex integer（整數）
@geindex Unicode

A string is a sequence of values that represent Unicode code points.
All the code points in the range @code{U+0000 - U+10FFFF} can be
represented in a string.  Python doesn't have a char type;
instead, every code point in the string is represented as a string
object with length @code{1}.  The built-in function @ref{21ef,,ord()}
converts a code point from its string form to an integer in the
range @code{0 - 10FFFF}; @ref{193e,,chr()} converts an integer in the range
@code{0 - 10FFFF} to the corresponding length @code{1} string object.
@ref{ac9,,str.encode()} can be used to convert a @ref{169,,str} to
@ref{192,,bytes} using the given text encoding, and
@ref{aca,,bytes.decode()} can be used to achieve the opposite.

@item Tuple（元組）

@geindex object（物件）;tuple（元組）
@geindex singleton（單例）;tuple（元組）
@geindex empty（空的）;tuple（元組）

The items of a 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 位元組

@geindex bytes（位元組）
@geindex byte（位元組）

A bytes object is an immutable array.  The items are 8-bit bytes,
represented by integers in the range 0 <= x < 256.  Bytes literals
(like @code{b'abc'}) and the built-in @ref{192,,bytes()} constructor
can be used to create bytes objects.  Also, bytes objects can be
decoded to strings via the @ref{aca,,decode()} method.
@end table

@node 可變序列,,Immutable sequences,Sequences
@anchor{reference/datamodel mutable-sequences}@anchor{21f0}
@subsubsection 可變序列


@geindex object（物件）;mutable sequence（可變序列）
@geindex object（物件）;mutable（可變的）
@geindex assignment（賦值）;statement（陳述式）
@geindex subscription（下標）
@geindex slice（切片）

Mutable sequences can be changed after they are created.  The subscription and
slicing notations can be used as the target of assignment and @ref{1a62,,del}
(delete) statements.

@cartouche
@quotation 備註 
@geindex module（模組）;array（陣列）

@geindex module（模組）;collections

The @ref{1e,,collections} and @ref{8,,array} module provide
additional examples of mutable sequence types.
@end quotation
@end cartouche

There are currently two intrinsic mutable sequence types:


@table @asis

@item List（串列）

@geindex object（物件）;list（串列）

The items of a list are arbitrary Python objects.  Lists are formed by
placing a comma-separated list of expressions in square brackets. (Note
that there are no special cases needed to form lists of length 0 or 1.)

@item 位元組陣列

@geindex bytearray（位元組陣列）

A bytearray object is a mutable array. They are created by the built-in
@ref{343,,bytearray()} constructor.  Aside from being mutable
(and hence unhashable), byte arrays otherwise provide the same interface
and functionality as immutable @ref{192,,bytes} objects.
@end table

@node Set（集合）型別,對映,Sequences,標準型別階層
@anchor{reference/datamodel set-types}@anchor{21f1}
@subsubsection Set（集合）型別


@geindex built-in function（內建函式）;len
@geindex object（物件）;set type（集合型別）

These represent unordered, finite sets of unique, immutable objects. As such,
they cannot be indexed by any subscript. However, they can be iterated over, and
the built-in function @ref{839,,len()} returns the number of items in a set. Common
uses for sets are fast membership testing, removing duplicates from a sequence,
and computing mathematical operations such as intersection, union, difference,
and symmetric difference.

For set elements, the same immutability rules apply as for dictionary keys. Note
that numeric types obey the normal rules for numeric comparison: if two numbers
compare equal (e.g., @code{1} and @code{1.0}), only one of them can be contained in a
set.

There are currently two intrinsic set types:


@table @asis

@item Set（集合）

@geindex object（物件）;set（集合）

These represent a mutable set. They are created by the built-in @ref{184,,set()}
constructor and can be modified afterwards by several methods, such as
@ref{21f2,,add}.

@item Frozen set（凍結集合）

@geindex object（物件）;frozenset（凍結集合）

These represent an immutable set.  They are created by the built-in
@ref{7eb,,frozenset()} constructor.  As a frozenset is immutable and
@ref{81d,,hashable}, it can be used again as an element of another set, or as
a dictionary key.
@end table

@node 對映,可呼叫型別,Set（集合）型別,標準型別階層
@anchor{reference/datamodel mappings}@anchor{21f3}
@subsubsection 對映


@geindex built-in function（內建函式）;len
@geindex subscription（下標）
@geindex object（物件）;mapping（對映）

These represent finite sets of objects indexed by arbitrary index sets. The
subscript notation @code{a[k]} selects the item indexed by @code{k} from the mapping
@code{a}; this can be used in expressions and as the target of assignments or
@ref{1a62,,del} statements. The built-in function @ref{839,,len()} returns the number
of items in a mapping.

There is currently a single intrinsic mapping type:

@menu
* 字典:: 

@end menu

@node 字典,,,對映
@anchor{reference/datamodel dictionaries}@anchor{21f4}
@subsubsection 字典


@geindex object（物件）;dictionary（字典）

These represent finite sets of objects indexed by nearly arbitrary values.  The
only types of values not acceptable as keys are values containing lists or
dictionaries or other mutable types that are compared by value rather than by
object identity, the reason being that the efficient implementation of
dictionaries requires a key's hash value to remain constant. Numeric types used
for keys obey the normal rules for numeric comparison: if two numbers compare
equal (e.g., @code{1} and @code{1.0}) then they can be used interchangeably to index
the same dictionary entry.

Dictionaries preserve insertion order, meaning that keys will be produced
in the same order they were added sequentially over the dictionary.
Replacing an existing key does not change the order, however removing a key
and re-inserting it will add it to the end instead of keeping its old place.

Dictionaries are mutable; they can be created by the @code{@{@}} notation (see
section @ref{f7a,,Dictionary displays}).

@geindex module（模組）;dbm.ndbm
@geindex module（模組）;dbm.gnu

The extension modules @ref{38,,dbm.ndbm} and @ref{37,,dbm.gnu} provide
additional examples of mapping types, as does the @ref{1e,,collections}
module.


在 3.7 版的變更: Dictionaries did not preserve insertion order in versions of Python before 3.6.
In CPython 3.6, insertion order was preserved, but it was considered
an implementation detail at that time rather than a language guarantee.


@node 可呼叫型別,模組<2>,對映,標準型別階層
@anchor{reference/datamodel callable-types}@anchor{21f5}
@subsubsection 可呼叫型別


@geindex object（物件）;callable（可呼叫物件）
@geindex function （函式）;call（呼叫）
@geindex invocation（呼叫）
@geindex function （函式）;argument（引數）

These are the types to which the function call operation (see section
@ref{f78,,Calls}) can be applied:

@menu
* 自訂函式:: 
* 實例方法:: 
* 產生器函式:: 
* Coroutine（協程）函式:: 
* 非同步產生器函式:: 
* 內建函式:: 
* 內建方法:: 
* Classes:: 
* 類別實例:: 

@end menu

@node 自訂函式,實例方法,,可呼叫型別
@anchor{reference/datamodel user-defined-funcs}@anchor{596}@anchor{reference/datamodel user-defined-functions}@anchor{21f6}
@subsubsection 自訂函式


@geindex user-defined（使用者定義）;function （函式）
@geindex object（物件）;function （函式）
@geindex object（物件）;user-defined function（使用者定義函式）

A user-defined function object is created by a function definition (see
section @ref{1ee1,,函式定義}).  It should be called with an argument list
containing the same number of items as the function's formal parameter
list.

@menu
* 特殊唯讀屬性:: 
* 特殊可寫屬性:: 

@end menu

@node 特殊唯讀屬性,特殊可寫屬性,,自訂函式
@anchor{reference/datamodel special-read-only-attributes}@anchor{21f7}
@subsubsection 特殊唯讀屬性


@geindex __closure__ （函式屬性）
@geindex __globals__ （函式屬性）
@geindex global（全域）;namespace（命名空間）


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

屬性

@tab

含義

@item

@geindex __globals__ (function 的屬性)
@anchor{reference/datamodel function __globals__}@anchor{14d4}
@deffn {屬性} function.__globals__
@end deffn

@tab

A reference to the @ref{183,,dictionary} that holds the function's
@ref{21f8,,global variables} -- the global namespace of the module
in which the function was defined.

@item

@geindex __closure__ (function 的屬性)
@anchor{reference/datamodel function __closure__}@anchor{14d1}
@deffn {屬性} function.__closure__
@end deffn

@tab

@code{None} or a @ref{60c,,tuple} of cells that contain bindings for the names specified
in the @ref{21f9,,co_freevars} attribute of the function's
@ref{597,,code object}.

A cell object has the attribute @code{cell_contents}.
This can be used to get the value of the cell, as well as set the value.

@end multitable


@node 特殊可寫屬性,,特殊唯讀屬性,自訂函式
@anchor{reference/datamodel special-writable-attributes}@anchor{21fa}
@subsubsection 特殊可寫屬性


@geindex __doc__ （函式屬性）
@geindex __name__ （函式屬性）
@geindex __module__ （函式屬性）
@geindex __dict__ （函式屬性）
@geindex __defaults__ （函式屬性）
@geindex __code__ （函式屬性）
@geindex __annotations__ （函式屬性）
@geindex __annotate__ （函式屬性）
@geindex __kwdefaults__ （函式屬性）
@geindex __type_params__ （函式屬性）

Most of these attributes check the type of the assigned value:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

屬性

@tab

含義

@item

@geindex __doc__ (function 的屬性)
@anchor{reference/datamodel function __doc__}@anchor{13da}
@deffn {屬性} function.__doc__
@end deffn

@tab

函式的文件字串，若不可用則為 @code{None}。

@item

@geindex __name__ (function 的屬性)
@anchor{reference/datamodel function __name__}@anchor{14d5}
@deffn {屬性} function.__name__
@end deffn

@tab

The function's name.
See also: @ref{1261,,__name__ attributes}.

@item

@geindex __qualname__ (function 的屬性)
@anchor{reference/datamodel function __qualname__}@anchor{21fb}
@deffn {屬性} function.__qualname__
@end deffn

@tab

The function's @ref{1bf6,,qualified name}.
See also: @ref{1260,,__qualname__ attributes}.


在 3.3 版被加入.


@item

@geindex __module__ (function 的屬性)
@anchor{reference/datamodel function __module__}@anchor{21fc}
@deffn {屬性} function.__module__
@end deffn

@tab

The name of the module the function was defined in,
or @code{None} if unavailable.

@item

@geindex __defaults__ (function 的屬性)
@anchor{reference/datamodel function __defaults__}@anchor{14d2}
@deffn {屬性} function.__defaults__
@end deffn

@tab

A @ref{60c,,tuple} containing default @ref{21fd,,parameter} values
for those parameters that have defaults,
or @code{None} if no parameters have a default value.

@item

@geindex __code__ (function 的屬性)
@anchor{reference/datamodel function __code__}@anchor{597}
@deffn {屬性} function.__code__
@end deffn

@tab

代表編譯函式主體的@ref{4e1,,程式碼物件}。

@item

@geindex __dict__ (function 的屬性)
@anchor{reference/datamodel function __dict__}@anchor{14d3}
@deffn {屬性} function.__dict__
@end deffn

@tab

The namespace supporting arbitrary function attributes.
See also: @ref{776,,__dict__ attributes}.

@item

@geindex __annotations__ (function 的屬性)
@anchor{reference/datamodel function __annotations__}@anchor{13d9}
@deffn {屬性} function.__annotations__
@end deffn

@tab

A @ref{183,,dictionary} containing annotations of
@ref{21fd,,parameters}.
The keys of the dictionary are the parameter names,
and @code{'return'} for the return annotation, if provided.
See also: @ref{456,,object.__annotations__}.


在 3.14 版的變更: Annotations are now @ref{67e,,lazily evaluated}.
See 
@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{21fe}
@deffn {屬性} function.__annotate__
@end deffn

@tab

The @ref{15d,,annotate function} for this function, or @code{None}
if the function has no annotations. See @ref{18df,,object.__annotate__}.


在 3.14 版被加入.


@item

@geindex __kwdefaults__ (function 的屬性)
@anchor{reference/datamodel function __kwdefaults__}@anchor{1223}
@deffn {屬性} function.__kwdefaults__
@end deffn

@tab

A @ref{183,,dictionary} containing defaults for keyword-only
@ref{21fd,,parameters}.

@item

@geindex __type_params__ (function 的屬性)
@anchor{reference/datamodel function __type_params__}@anchor{21ff}
@deffn {屬性} function.__type_params__
@end deffn

@tab

A @ref{60c,,tuple} containing the @ref{5a7,,type parameters} of
a @ref{67b,,generic function}.


在 3.12 版被加入.


@end multitable


Function objects also support getting and setting arbitrary attributes, which
can be used, for example, to attach metadata to functions.  Regular attribute
dot-notation is used to get and set such attributes.

`CPython 實作細節：' CPython's current implementation only supports function attributes
on user-defined functions. Function attributes on
@ref{2200,,built-in functions} may be supported in the
future.

Additional information about a function's definition can be retrieved from its
@ref{4e1,,code object}
(accessible via the @ref{597,,__code__} attribute).

@node 實例方法,產生器函式,自訂函式,可呼叫型別
@anchor{reference/datamodel id2}@anchor{2201}@anchor{reference/datamodel instance-methods}@anchor{1f6e}
@subsubsection 實例方法


@geindex object（物件）;method（方法）
@geindex object（物件）;user-defined method（使用者定義方法）
@geindex user-defined（使用者定義）;method（方法）

An instance method object combines a class, a class instance and any
callable object (normally a user-defined function).

@geindex __func__ （方法屬性）
@geindex __self__ （方法屬性）
@geindex __doc__ （方法屬性）
@geindex __name__ （方法屬性）
@geindex __module__ （方法屬性）

特殊唯讀屬性：


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@geindex __self__ (method 的屬性)
@anchor{reference/datamodel method __self__}@anchor{15c0}
@deffn {屬性} method.__self__
@end deffn

@tab

Refers to the class instance object to which the method is
@ref{2202,,bound}

@item

@geindex __func__ (method 的屬性)
@anchor{reference/datamodel method __func__}@anchor{14fd}
@deffn {屬性} method.__func__
@end deffn

@tab

Refers to the original @ref{596,,function object}

@item

@geindex __doc__ (method 的屬性)
@anchor{reference/datamodel method __doc__}@anchor{2203}
@deffn {屬性} method.__doc__
@end deffn

@tab

The method's documentation
(same as @ref{13da,,method.__func__.__doc__}).
A @ref{169,,string} if the original function had a docstring, else
@code{None}.

@item

@geindex __name__ (method 的屬性)
@anchor{reference/datamodel method __name__}@anchor{2204}
@deffn {屬性} method.__name__
@end deffn

@tab

The name of the method
(same as @ref{14d5,,method.__func__.__name__})

@item

@geindex __module__ (method 的屬性)
@anchor{reference/datamodel method __module__}@anchor{2205}
@deffn {屬性} method.__module__
@end deffn

@tab

The name of the module the method was defined in, or @code{None} if
unavailable.

@end multitable


Methods also support accessing (but not setting) the arbitrary function
attributes on the underlying @ref{596,,function object}.

User-defined method objects may be created when getting an attribute of a
class (perhaps via an instance of that class), if that attribute is a
user-defined @ref{596,,function object} or a
@ref{489,,classmethod} object.
@anchor{reference/datamodel method-binding}@anchor{2202}
When an instance method object is created by retrieving a user-defined
@ref{596,,function object} from a class via one of its
instances, its @ref{15c0,,__self__} attribute is the instance, and the
method object is said to be `bound'.  The new method's @ref{14fd,,__func__}
attribute is the original function object.

When an instance method object is created by retrieving a @ref{489,,classmethod}
object from a class or instance, its @ref{15c0,,__self__} attribute is the
class itself, and its @ref{14fd,,__func__} attribute is the function object
underlying the class method.

When an instance method object is called, the underlying function
(@ref{14fd,,__func__}) is called, inserting the class instance
(@ref{15c0,,__self__}) in front of the argument list.  For instance, when
@code{C} is a class which contains a definition for a function
@code{f()}, and @code{x} is an instance of @code{C}, calling @code{x.f(1)} is
equivalent to calling @code{C.f(x, 1)}.

When an instance method object is derived from a @ref{489,,classmethod} object, the
"class instance" stored in @ref{15c0,,__self__} will actually be the class
itself, so that calling either @code{x.f(1)} or @code{C.f(1)} is equivalent to
calling @code{f(C,1)} where @code{f} is the underlying function.

It is important to note that user-defined functions
which are attributes of a class instance are not converted to bound
methods; this `only' happens when the function is an attribute of the
class.

@node 產生器函式,Coroutine（協程）函式,實例方法,可呼叫型別
@anchor{reference/datamodel generator-functions}@anchor{2206}
@subsubsection 產生器函式


@geindex generator（產生器）;function （函式）
@geindex generator（產生器）;itorator（疊代器）

A function or method which uses the @ref{bb9,,yield} statement (see section
@ref{bb9,,yield 陳述式}) is called a `generator function'.  Such a function, when
called, always returns an @ref{4c3,,iterator} object which can be used to
execute the body of the function:  calling the iterator's
@ref{14ce,,iterator.__next__()} method will cause the function to execute until
it provides a value using the @code{yield} statement.  When the
function executes a @ref{1af,,return} statement or falls off the end, a
@ref{df0,,StopIteration} exception is raised and the iterator will have
reached the end of the set of values to be returned.

@node Coroutine（協程）函式,非同步產生器函式,產生器函式,可呼叫型別
@anchor{reference/datamodel coroutine-functions}@anchor{2207}
@subsubsection Coroutine（協程）函式


@geindex coroutine（協程）;function （函式）

A function or method which is defined using @ref{7e6,,async def} is called
a `coroutine function'.  Such a function, when called, returns a
@ref{6b2,,coroutine} object.  It may contain @ref{18d,,await} expressions,
as well as @ref{185,,async with} and @ref{c98,,async for} statements. See
also the @ref{2208,,協程物件} section.

@node 非同步產生器函式,內建函式,Coroutine（協程）函式,可呼叫型別
@anchor{reference/datamodel asynchronous-generator-functions}@anchor{2209}
@subsubsection 非同步產生器函式


@geindex asynchronous generator（非同步產生器）;function （函式）
@geindex asynchronous generator（非同步產生器）;asynchronous iterator（非同步疊代器）

A function or method which is defined using @ref{7e6,,async def} and
which uses the @ref{bb9,,yield} statement is called a
`asynchronous generator function'.  Such a function, when called,
returns an @ref{4c2,,asynchronous iterator} object which can be used in an
@ref{c98,,async for} statement to execute the body of the function.

Calling the asynchronous iterator's
@ref{17fd,,aiterator.__anext__} method
will return an @ref{4c4,,awaitable} which when awaited
will execute until it provides a value using the @ref{bb9,,yield}
expression.  When the function executes an empty @ref{1af,,return}
statement or falls off the end, a @ref{1cd7,,StopAsyncIteration} exception
is raised and the asynchronous iterator will have reached the end of
the set of values to be yielded.

@node 內建函式,內建方法,非同步產生器函式,可呼叫型別
@anchor{reference/datamodel built-in-functions}@anchor{220a}@anchor{reference/datamodel builtin-functions}@anchor{2200}
@subsubsection 內建函式


@geindex object（物件）;built-in function（內建函式）
@geindex object（物件）;function （函式）
@geindex C;language（語言）

一個內建函式物件是一個 C 函式的 wrapper。內建函式的範例有 @ref{839,,len()} 和 @ref{16b2,,math.sin()}（@ref{92,,math} 是一個標準的內建模組）。內建函式的引數數量與其型別由其包裝的 C 函式所決定。特殊唯讀屬性：


@itemize *

@item 
@code{__doc__} 是函式的文件字串，若不可用則為 @code{None}。請見 @ref{13da,,function.__doc__}。

@item 
@code{__name__} 是函式的名稱。請見 @ref{14d5,,function.__name__}。

@item 
@code{__self__} is set to @code{None} (but see the next item).

@item 
@code{__module__} is the name of
the module the function was defined in or @code{None} if unavailable.
See @ref{21fc,,function.__module__}.
@end itemize

@node 內建方法,Classes,內建函式,可呼叫型別
@anchor{reference/datamodel built-in-methods}@anchor{220b}@anchor{reference/datamodel builtin-methods}@anchor{220c}
@subsubsection 內建方法


@geindex object（物件）;built-in method（內建方法）
@geindex object（物件）;method（方法）
@geindex built-in（內建）;method（方法）

This is really a different disguise of a built-in function, this time containing
an object passed to the C function as an implicit extra argument.  An example of
a built-in method is @code{alist.append()}, assuming `alist' is a list object. In
this case, the special read-only attribute @code{__self__} is set to the object
denoted by `alist'. (The attribute has the same semantics as it does with
@ref{15c0,,other instance methods}.)

@node Classes,類別實例,內建方法,可呼叫型別
@anchor{reference/datamodel classes}@anchor{220d}@anchor{reference/datamodel id3}@anchor{220e}
@subsubsection Classes


Classes are callable.  These objects normally act as factories for new
instances of themselves, but variations are possible for class types that
override @ref{799,,__new__()}.  The arguments of the call are passed to
@code{__new__()} and, in the typical case, to @ref{8b7,,__init__()} to
initialize the new instance.

@node 類別實例,,Classes,可呼叫型別
@anchor{reference/datamodel class-instances}@anchor{220f}
@subsubsection 類別實例


Instances of arbitrary classes can be made callable by defining a
@ref{773,,__call__()} method in their class.

@node 模組<2>,Custom classes,可呼叫型別,標準型別階層
@anchor{reference/datamodel module-objects}@anchor{2210}@anchor{reference/datamodel modules}@anchor{2211}
@subsubsection 模組


@geindex statement（陳述式）;import（引入）
@geindex object（物件）;module（模組）

Modules are a basic organizational unit of Python code, and are created by
the @ref{2212,,import system} as invoked either by the
@ref{7f1,,import} statement, or by calling
functions such as @ref{735,,importlib.import_module()} and built-in
@ref{ac8,,__import__()}.  A module object has a namespace implemented by a
@ref{183,,dictionary} object (this is the dictionary referenced by the
@ref{14d4,,__globals__}
attribute of functions defined in the module).  Attribute references are
translated to lookups in this dictionary, e.g., @code{m.x} is equivalent to
@code{m.__dict__["x"]}. A module object does not contain the code object used
to initialize the module (since it isn't needed once the initialization is
done).

Attribute assignment updates the module's namespace dictionary, e.g.,
@code{m.x = 1} is equivalent to @code{m.__dict__["x"] = 1}.

@geindex __name__ （模組屬性）
@geindex __spec__ （模組屬性）
@geindex __package__ （模組屬性）
@geindex __loader__ （模組屬性）
@geindex __path__ （模組屬性）
@geindex __file__ （模組屬性）
@geindex __cached__ （模組屬性）
@geindex __doc__ （模組屬性）
@geindex __annotations__ （模組屬性）
@geindex __annotate__ （模組屬性）
@geindex module（模組）;namespace（命名空間）

@menu
* Import-related attributes on module objects:: 
* 模組物件的其他可寫入屬性:: 
* 模組字典:: 

@end menu

@node Import-related attributes on module objects,模組物件的其他可寫入屬性,,模組<2>
@anchor{reference/datamodel import-mod-attrs}@anchor{2213}@anchor{reference/datamodel import-related-attributes-on-module-objects}@anchor{2214}
@subsubsection Import-related attributes on module objects


Module objects have the following attributes that relate to the
@ref{2212,,import system}. When a module is created using the machinery associated
with the import system, these attributes are filled in based on the module's
@ref{2215,,spec}, before the @ref{1978,,loader} executes and loads the
module.

To create a module dynamically rather than using the import system,
it's recommended to use @ref{100e,,importlib.util.module_from_spec()},
which will set the various import-controlled attributes to appropriate values.
It's also possible to use the @ref{100f,,types.ModuleType} constructor to create
modules directly, but this technique is more error-prone, as most attributes
must be manually set on the module object after it has been created when using
this approach.

@cartouche
@quotation 警示 
With the exception of @ref{1583,,__name__}, it is `strongly'
recommended that you rely on @ref{2216,,__spec__} and its attributes
instead of any of the other individual attributes listed in this subsection.
Note that updating an attribute on @code{__spec__} will not update the
corresponding attribute on the module itself:

@example
>>> import typing
>>> typing.__name__, typing.__spec__.name
('typing', 'typing')
>>> typing.__spec__.name = 'spelling'
>>> typing.__name__, typing.__spec__.name
('typing', 'spelling')
>>> typing.__name__ = 'keyboard_smashing'
>>> typing.__name__, typing.__spec__.name
('keyboard_smashing', 'spelling')
@end example
@end quotation
@end cartouche

@geindex __name__ (module 的屬性)
@anchor{reference/datamodel module __name__}@anchor{1583}
@deffn {屬性} module.__name__

The name used to uniquely identify the module in the import system.
For a directly executed module, this will be set to @code{"__main__"}.

This attribute must be set to the fully qualified name of the module.
It is expected to match the value of
@ref{2217,,module.__spec__.name}.
@end deffn

@geindex __spec__ (module 的屬性)
@anchor{reference/datamodel module __spec__}@anchor{2216}
@deffn {屬性} module.__spec__

A record of the module's import-system-related state.

Set to the @ref{2130,,module spec} that was
used when importing the module. See @ref{2218,,模組規格} for more details.


在 3.4 版被加入.

@end deffn

@geindex __package__ (module 的屬性)
@anchor{reference/datamodel module __package__}@anchor{322}
@deffn {屬性} module.__package__

The @ref{233,,package} a module belongs to.

If the module is top-level (that is, not a part of any specific package)
then the attribute should be set to @code{'@w{'}} (the empty string). Otherwise,
it should be set to the name of the module's package (which can be equal to
@ref{1583,,module.__name__} if the module itself is a package). See 
@geindex Python Enhancement Proposals; PEP 366
PEP 366@footnote{https://peps.python.org/pep-0366/}
for further details.

This attribute is used instead of @ref{1583,,__name__} to calculate
explicit relative imports for main modules. It defaults to @code{None} for
modules created dynamically using the @ref{100f,,types.ModuleType} constructor;
use @ref{100e,,importlib.util.module_from_spec()} instead to ensure the attribute
is set to a @ref{169,,str}.

It is `strongly' recommended that you use
@ref{323,,module.__spec__.parent}
instead of @code{module.__package__}. @ref{322,,__package__} is now only used
as a fallback if @code{__spec__.parent} is not set, and this fallback
path is deprecated.


在 3.4 版的變更: This attribute now defaults to @code{None} for modules created dynamically
using the @ref{100f,,types.ModuleType} constructor.
Previously the attribute was optional.



在 3.6 版的變更: The value of @code{__package__} is expected to be the same as
@ref{323,,__spec__.parent}.
@ref{322,,__package__} is now only used as a fallback during import
resolution if @code{__spec__.parent} is not defined.



在 3.10 版的變更: @ref{717,,ImportWarning} is raised if an import resolution falls back to
@code{__package__} instead of
@ref{323,,__spec__.parent}.



在 3.12 版的變更: Raise @ref{1a3,,DeprecationWarning} instead of @ref{717,,ImportWarning} when
falling back to @code{__package__} during import resolution.



Deprecated since version 3.13, will be removed in version 3.15: @code{__package__} will cease to be set or taken into consideration
by the import system or standard library.

@end deffn

@geindex __loader__ (module 的屬性)
@anchor{reference/datamodel module __loader__}@anchor{33a}
@deffn {屬性} module.__loader__

The @ref{1978,,loader} object that the import machinery used to load the module.

This attribute is mostly useful for introspection, but can be used for
additional loader-specific functionality, for example getting data
associated with a loader.

@code{__loader__} defaults to @code{None} for modules created dynamically
using the @ref{100f,,types.ModuleType} constructor;
use @ref{100e,,importlib.util.module_from_spec()} instead to ensure the attribute
is set to a @ref{1978,,loader} object.

It is `strongly' recommended that you use
@ref{33b,,module.__spec__.loader}
instead of @code{module.__loader__}.


在 3.4 版的變更: This attribute now defaults to @code{None} for modules created dynamically
using the @ref{100f,,types.ModuleType} constructor.
Previously the attribute was optional.



Deprecated since version 3.12, will be removed in version 3.16: 在模組上設定 @code{__loader__} 而沒有設定 @code{__spec__.loader} 的做法已被棄用。在 Python 3.16 中，引入系統或標準函式庫將不再設定或考慮 @code{__loader__}。

@end deffn

@geindex __path__ (module 的屬性)
@anchor{reference/datamodel module __path__}@anchor{1f1b}
@deffn {屬性} module.__path__

A (possibly empty) @ref{70f,,sequence} of strings enumerating the locations
where the package's submodules will be found. Non-package modules should
not have a @code{__path__} attribute. See @ref{2219,,__path__ attributes on modules} for
more details.

It is `strongly' recommended that you use
@ref{221a,,module.__spec__.submodule_search_locations}
instead of @code{module.__path__}.
@end deffn

@geindex __file__ (module 的屬性)
@anchor{reference/datamodel module __file__}@anchor{221b}
@deffn {屬性} module.__file__
@end deffn

@geindex __cached__ (module 的屬性)
@anchor{reference/datamodel module __cached__}@anchor{320}
@deffn {屬性} module.__cached__

@code{__file__} and @code{__cached__} are both optional attributes that
may or may not be set. Both attributes should be a @ref{169,,str} when they
are available.

@code{__file__} indicates the pathname of the file from which the module
was loaded (if loaded from a file), or the pathname of the shared library
file for extension modules loaded dynamically from a shared library.
It might be missing for certain types of modules, such as C modules that are
statically linked into the interpreter, and the
@ref{2212,,import system} may opt to leave it unset if it
has no semantic meaning (for example, a module loaded from a database).

If @code{__file__} is set then the @code{__cached__} attribute might
also be set,  which is the path to any compiled version of
the code (for example, a byte-compiled file). The file does not need to exist
to set this attribute; the path can simply point to where the
compiled file `would' exist (see 
@geindex Python Enhancement Proposals; PEP 3147
PEP 3147@footnote{https://peps.python.org/pep-3147/}).

Note that @code{__cached__} may be set even if @code{__file__} is not
set.  However, that scenario is quite atypical.  Ultimately, the
@ref{1978,,loader} is what makes use of the module spec provided by the
@ref{221c,,finder} (from which @code{__file__} and @code{__cached__} are
derived).  So if a loader can load from a cached module but otherwise does
not load from a file, that atypical scenario may be appropriate.

It is `strongly' recommended that you use
@ref{321,,module.__spec__.cached}
instead of @code{module.__cached__}.


Deprecated since version 3.13, will be removed in version 3.15: Setting @code{__cached__} on a module while failing to set
@code{__spec__.cached} is deprecated. In Python 3.15,
@code{__cached__} will cease to be set or taken into consideration by
the import system or standard library.

@end deffn

@node 模組物件的其他可寫入屬性,模組字典,Import-related attributes on module objects,模組<2>
@anchor{reference/datamodel other-writable-attributes-on-module-objects}@anchor{221d}
@subsubsection 模組物件的其他可寫入屬性


As well as the import-related attributes listed above, module objects also have
the following writable attributes:

@geindex __doc__ (module 的屬性)
@anchor{reference/datamodel module __doc__}@anchor{1b0a}
@deffn {屬性} module.__doc__

模組的文件字串，若不可用則為 @code{None}。請見 @ref{b18,,__doc__ attributes}。
@end deffn

@geindex __annotations__ (module 的屬性)
@anchor{reference/datamodel module __annotations__}@anchor{221e}
@deffn {屬性} module.__annotations__

A dictionary containing @ref{f4c,,variable annotations}
collected during module body execution.  For best practices on working with
@code{__annotations__}, see @ref{6,,annotationlib}.


在 3.14 版的變更: Annotations are now @ref{67e,,lazily evaluated}.
See 
@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{221f}
@deffn {屬性} module.__annotate__

The @ref{15d,,annotate function} for this module, or @code{None} if the module has
no annotations. See also: @ref{18df,,__annotate__} attributes.


在 3.14 版被加入.

@end deffn

@node 模組字典,,模組物件的其他可寫入屬性,模組<2>
@anchor{reference/datamodel module-dictionaries}@anchor{2220}
@subsubsection 模組字典


Module objects also have the following special read-only attribute:

@geindex __dict__ （模組屬性）

@geindex __dict__ (module 的屬性)
@anchor{reference/datamodel module __dict__}@anchor{2221}
@deffn {屬性} module.__dict__

The module's namespace as a dictionary object. Uniquely among the attributes
listed here, @code{__dict__} cannot be accessed as a global variable from
within a module; it can only be accessed as an attribute on module objects.

`CPython 實作細節：' Because of the way CPython clears module dictionaries, the module
dictionary will be cleared when the module falls out of scope even if the
dictionary still has live references.  To avoid this, copy the dictionary
or keep the module around while using its dictionary directly.
@end deffn

@node Custom classes,類別實例<2>,模組<2>,標準型別階層
@anchor{reference/datamodel class-attrs-and-methods}@anchor{2222}@anchor{reference/datamodel custom-classes}@anchor{2223}
@subsubsection Custom classes


Custom class types are typically created by class definitions (see section
@ref{14d8,,類別定義}).  A class has a namespace implemented by a dictionary object.
Class attribute references are translated to lookups in this dictionary, e.g.,
@code{C.x} is translated to @code{C.__dict__["x"]} (although there are a number of
hooks which allow for other means of locating attributes). When the attribute
name is not found there, the attribute search continues in the base classes.
This search of the base classes uses the C3 method resolution order which
behaves correctly even in the presence of 'diamond' inheritance structures
where there are multiple inheritance paths leading back to a common ancestor.
Additional details on the C3 MRO used by Python can be found at
@ref{169e,,The Python 2.3 Method Resolution Order}.

@geindex object（物件）;class（類別）
@geindex object（物件）;class instance（類別實例）
@geindex object（物件）;instance（實例）
@geindex class object（類別物件）;call（呼叫）
@geindex container（容器）
@geindex object（物件）;dictionary（字典）
@geindex class（類別）;attribute（屬性）

When a class attribute reference (for class @code{C}, say) would yield a
class method object, it is transformed into an instance method object whose
@ref{15c0,,__self__} attribute is @code{C}.
When it would yield a @ref{451,,staticmethod} object,
it is transformed into the object wrapped by the static method
object. See section @ref{e44,,實作描述器} for another way in which attributes
retrieved from a class may differ from those actually contained in its
@ref{776,,__dict__}.

@geindex class（類別）;attribute（屬性）;assignment（賦值）

Class attribute assignments update the class's dictionary, never the dictionary
of a base class.

@geindex class object（類別物件）;call（呼叫）

A class object can be called (see above) to yield a class instance (see below).

@menu
* 特殊屬性:: 
* 特殊方法:: 

@end menu

@node 特殊屬性,特殊方法,,Custom classes
@anchor{reference/datamodel special-attributes}@anchor{2224}
@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{169f}
@deffn {屬性} type.__name__
@end deffn

@tab

The class's name.
See also: @ref{1261,,__name__ attributes}.

@item

@geindex __qualname__ (type 的屬性)
@anchor{reference/datamodel type __qualname__}@anchor{2225}
@deffn {屬性} type.__qualname__
@end deffn

@tab

The class's @ref{1bf6,,qualified name}.
See also: @ref{1260,,__qualname__ attributes}.

@item

@geindex __module__ (type 的屬性)
@anchor{reference/datamodel type __module__}@anchor{60f}
@deffn {屬性} type.__module__
@end deffn

@tab

The name of the module in which the class was defined.

@item

@geindex __dict__ (type 的屬性)
@anchor{reference/datamodel type __dict__}@anchor{e52}
@deffn {屬性} type.__dict__
@end deffn

@tab

A @ref{691,,mapping proxy}
providing a read-only view of the class's namespace.
See also: @ref{776,,__dict__ attributes}.

@item

@geindex __bases__ (type 的屬性)
@anchor{reference/datamodel type __bases__}@anchor{16a0}
@deffn {屬性} type.__bases__
@end deffn

@tab

A @ref{60c,,tuple} containing the class's bases.
In most cases, for a class defined as @code{class X(A, B, C)},
@code{X.__bases__} will be exactly equal to @code{(A, B, C)}.

@item

@geindex __base__ (type 的屬性)
@anchor{reference/datamodel type __base__}@anchor{2226}
@deffn {屬性} type.__base__
@end deffn

@tab

`CPython 實作細節：' The single base class in the inheritance chain that is responsible
for the memory layout of instances. This attribute corresponds to
@ref{2227,,tp_base} at the C level.

@item

@geindex __doc__ (type 的屬性)
@anchor{reference/datamodel type __doc__}@anchor{1f5c}
@deffn {屬性} type.__doc__
@end deffn

@tab

The class's documentation string, or @code{None} if undefined.
Not inherited by subclasses.

@item

@geindex __annotations__ (type 的屬性)
@anchor{reference/datamodel type __annotations__}@anchor{17c1}
@deffn {屬性} type.__annotations__
@end deffn

@tab

A dictionary containing
@ref{f4c,,variable annotations}
collected during class body execution. See also:
@ref{456,,__annotations__ attributes}.

For best practices on working with @ref{456,,__annotations__},
please see @ref{6,,annotationlib}. Use
@ref{457,,annotationlib.get_annotations()} instead of accessing this
attribute directly.

@cartouche
@quotation 警告 
Accessing the @code{__annotations__} attribute directly
on a class object may return annotations for the wrong class, specifically
in certain cases where the class, its base class, or a metaclass
is defined under @code{from __future__ import annotations}.
See 
@geindex Python Enhancement Proposals; PEP 749#pep749-metaclasses
749@footnote{https://peps.python.org/pep-0749/#pep749-metaclasses} for details.

This attribute does not exist on certain builtin classes. On
user-defined classes without @code{__annotations__}, it is an
empty dictionary.
@end quotation
@end cartouche


在 3.14 版的變更: Annotations are now @ref{67e,,lazily evaluated}.
See 
@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{17e3}
@deffn {方法} type.__annotate__ ()
@end deffn

@tab

The @ref{15d,,annotate function} for this class, or @code{None}
if the class has no annotations.
See also: @ref{18df,,__annotate__ attributes}.


在 3.14 版被加入.


@item

@geindex __type_params__ (type 的屬性)
@anchor{reference/datamodel type __type_params__}@anchor{2228}
@deffn {屬性} type.__type_params__
@end deffn

@tab

A @ref{60c,,tuple} containing the @ref{5a7,,type parameters} of
a @ref{67a,,generic class}.


在 3.12 版被加入.


@item

@geindex __static_attributes__ (type 的屬性)
@anchor{reference/datamodel type __static_attributes__}@anchor{471}
@deffn {屬性} type.__static_attributes__
@end deffn

@tab

A @ref{60c,,tuple} containing names of attributes of this class which are
assigned through @code{self.X} from any function in its body.


在 3.13 版被加入.


@item

@geindex __firstlineno__ (type 的屬性)
@anchor{reference/datamodel type __firstlineno__}@anchor{472}
@deffn {屬性} type.__firstlineno__
@end deffn

@tab

The line number of the first line of the class definition,
including decorators.
Setting the @ref{60f,,__module__} attribute removes the
@code{__firstlineno__} item from the type's dictionary.


在 3.13 版被加入.


@item

@geindex __mro__ (type 的屬性)
@anchor{reference/datamodel type __mro__}@anchor{2229}
@deffn {屬性} type.__mro__
@end deffn

@tab

The @ref{60c,,tuple} of classes that are considered when looking for
base classes during method resolution.

@end multitable


@node 特殊方法,,特殊屬性,Custom classes
@anchor{reference/datamodel special-methods}@anchor{222a}
@subsubsection 特殊方法


In addition to the special attributes described above, all Python classes also
have the following two methods available:

@geindex mro() (type 的方法)
@anchor{reference/datamodel type mro}@anchor{222b}
@deffn {方法} type.mro ()

This method can be overridden by a metaclass to customize the method
resolution order for its instances.  It is called at class instantiation,
and its result is stored in @ref{2229,,__mro__}.
@end deffn

@geindex __subclasses__() (type 的方法)
@anchor{reference/datamodel type __subclasses__}@anchor{78c}
@deffn {方法} type.__subclasses__ ()

Each class keeps a list of weak references to its immediate subclasses. This
method returns a list of all those references still alive. The list is in
definition order. Example:

@example
>>> class A: pass
>>> class B(A): pass
>>> A.__subclasses__()
[<class 'B'>]
@end example
@end deffn

@node 類別實例<2>,I/O objects also known as file objects,Custom classes,標準型別階層
@anchor{reference/datamodel id4}@anchor{222c}
@subsubsection 類別實例


@geindex object（物件）;class instance（類別實例）
@geindex object（物件）;instance（實例）
@geindex class（類別）;instance（實例）
@geindex class instance（類別實例）;attribute（屬性）

A class instance is created by calling a class object (see above).  A class
instance has a namespace implemented as a dictionary which is the first place
in which attribute references are searched.  When an attribute is not found
there, and the instance's class has an attribute by that name, the search
continues with the class attributes.  If a class attribute is found that is a
user-defined function object, it is transformed into an instance method
object whose @ref{15c0,,__self__} attribute is the instance.  Static method and
class method objects are also transformed; see above under "Classes".  See
section @ref{e44,,實作描述器} for another way in which attributes of a class
retrieved via its instances may differ from the objects actually stored in
the class's @ref{776,,__dict__}.  If no class attribute is found, and the
object's class has a @ref{6f3,,__getattr__()} method, that is called to satisfy
the lookup.

@geindex class instance（類別實例）;attribute（屬性）;assignment（賦值）

Attribute assignments and deletions update the instance's dictionary, never a
class's dictionary.  If the class has a @ref{222d,,__setattr__()} or
@ref{222e,,__delattr__()} method, this is called instead of updating the instance
dictionary directly.

@geindex object（物件）;numeric（數值）
@geindex object（物件）;sequence（序列）
@geindex object（物件）;mapping（對映）

Class instances can pretend to be numbers, sequences, or mappings if they have
methods with certain special names.  See section @ref{e63,,Special method names}.

@menu
* 特殊屬性: 特殊屬性<2>. 

@end menu

@node 特殊屬性<2>,,,類別實例<2>
@anchor{reference/datamodel id5}@anchor{222f}
@subsubsection 特殊屬性


@geindex __dict__ （實例屬性）
@geindex __class__ （實例屬性）

@geindex __class__ (object 的屬性)
@anchor{reference/datamodel object __class__}@anchor{16a1}
@deffn {屬性} object.__class__

The class to which a class instance belongs.
@end deffn

@geindex __dict__ (object 的屬性)
@anchor{reference/datamodel object __dict__}@anchor{776}
@deffn {屬性} object.__dict__

A dictionary or other mapping object used to store an object's (writable)
attributes. Not all instances have a @code{__dict__} attribute; see the
section on @ref{2230,,__slots__} for more details.
@end deffn

@node I/O objects also known as file objects,Internal types,類別實例<2>,標準型別階層
@anchor{reference/datamodel i-o-objects-also-known-as-file-objects}@anchor{2231}
@subsubsection I/O objects (also known as file objects)


@geindex built-in function（內建函式）;open
@geindex module（模組）;io
@geindex popen() （於 os 模組中）
@geindex makefile() （socket 方法）
@geindex sys.stdin
@geindex sys.stdout
@geindex sys.stderr
@geindex stdio
@geindex stdin （sys 模組中）
@geindex stdout （sys 模組中）
@geindex stderr （sys 模組中）

A @ref{13c4,,file object} represents an open file.  Various shortcuts are
available to create file objects: the @ref{315,,open()} built-in function, and
also @ref{319,,os.popen()}, @ref{2232,,os.fdopen()}, and the
@ref{13a0,,makefile()} method of socket objects (and perhaps by
other functions or methods provided by extension modules).

The objects @code{sys.stdin}, @code{sys.stdout} and @code{sys.stderr} are
initialized to file objects corresponding to the interpreter's standard
input, output and error streams; they are all open in text mode and
therefore follow the interface defined by the @ref{89d,,io.TextIOBase}
abstract class.

@node Internal types,,I/O objects also known as file objects,標準型別階層
@anchor{reference/datamodel internal-types}@anchor{2233}
@subsubsection Internal types


@geindex internal type（內部型別）
@geindex types（型別）@comma{} internal（內部）

A few types used internally by the interpreter are exposed to the user. Their
definitions may change with future versions of the interpreter, but they are
mentioned here for completeness.

@menu
* 程式碼物件:: 
* Frame objects:: 
* Traceback objects:: 
* Slice objects:: 
* Static method objects:: 
* Class method objects:: 

@end menu

@node 程式碼物件,Frame objects,,Internal types
@anchor{reference/datamodel code-objects}@anchor{4e1}@anchor{reference/datamodel id6}@anchor{2234}
@subsubsection 程式碼物件


@geindex bytecode（位元組碼）
@geindex object（物件）;code（程式碼）
@geindex code object（程式碼物件）

Code objects represent `byte-compiled' executable Python code, or @ref{4a5,,bytecode}.
The difference between a code object and a function object is that the function
object contains an explicit reference to the function's globals (the module in
which it was defined), while a code object contains no context; also the default
argument values are stored in the function object, not in the code object
(because they represent values calculated at run-time).  Unlike function
objects, code objects are immutable and contain no references (directly or
indirectly) to mutable objects.

@geindex co_argcount （程式碼物件屬性）
@geindex co_posonlyargcount （程式碼物件屬性）
@geindex co_kwonlyargcount （程式碼物件屬性）
@geindex co_code （程式碼物件屬性）
@geindex co_consts （程式碼物件屬性）
@geindex co_filename （程式碼物件屬性）
@geindex co_firstlineno （程式碼物件屬性）
@geindex co_flags （程式碼物件屬性）
@geindex co_lnotab （程式碼物件屬性）
@geindex co_name （程式碼物件屬性）
@geindex co_names （程式碼物件屬性）
@geindex co_nlocals （程式碼物件屬性）
@geindex co_stacksize （程式碼物件屬性）
@geindex co_varnames （程式碼物件屬性）
@geindex co_cellvars （程式碼物件屬性）
@geindex co_freevars （程式碼物件屬性）
@geindex co_qualname （程式碼物件屬性）

@menu
* 特殊唯讀屬性: 特殊唯讀屬性<2>. 
* 用於程式碼物件的方法:: 

@end menu

@node 特殊唯讀屬性<2>,用於程式碼物件的方法,,程式碼物件
@anchor{reference/datamodel id7}@anchor{2235}
@subsubsection 特殊唯讀屬性



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@geindex co_name (codeobject 的屬性)
@anchor{reference/datamodel codeobject co_name}@anchor{2236}
@deffn {屬性} codeobject.co_name
@end deffn

@tab

函式名稱

@item

@geindex co_qualname (codeobject 的屬性)
@anchor{reference/datamodel codeobject co_qualname}@anchor{2237}
@deffn {屬性} codeobject.co_qualname
@end deffn

@tab

The fully qualified function name


在 3.11 版被加入.


@item

@geindex co_argcount (codeobject 的屬性)
@anchor{reference/datamodel codeobject co_argcount}@anchor{2238}
@deffn {屬性} codeobject.co_argcount
@end deffn

@tab

The total number of positional @ref{21fd,,parameters}
(including positional-only parameters and parameters with default values)
that the function has

@item

@geindex co_posonlyargcount (codeobject 的屬性)
@anchor{reference/datamodel codeobject co_posonlyargcount}@anchor{2239}
@deffn {屬性} codeobject.co_posonlyargcount
@end deffn

@tab

The number of positional-only @ref{21fd,,parameters}
(including arguments with default values) that the function has

@item

@geindex co_kwonlyargcount (codeobject 的屬性)
@anchor{reference/datamodel codeobject co_kwonlyargcount}@anchor{223a}
@deffn {屬性} codeobject.co_kwonlyargcount
@end deffn

@tab

The number of keyword-only @ref{21fd,,parameters}
(including arguments with default values) that the function has

@item

@geindex co_nlocals (codeobject 的屬性)
@anchor{reference/datamodel codeobject co_nlocals}@anchor{223b}
@deffn {屬性} codeobject.co_nlocals
@end deffn

@tab

The number of @ref{21f8,,local variables} used by the function
(including parameters)

@item

@geindex co_varnames (codeobject 的屬性)
@anchor{reference/datamodel codeobject co_varnames}@anchor{223c}
@deffn {屬性} codeobject.co_varnames
@end deffn

@tab

A @ref{60c,,tuple} containing the names of the local variables in the
function (starting with the parameter names)

@item

@geindex co_cellvars (codeobject 的屬性)
@anchor{reference/datamodel codeobject co_cellvars}@anchor{223d}
@deffn {屬性} codeobject.co_cellvars
@end deffn

@tab

A @ref{60c,,tuple} containing the names of @ref{21f8,,local variables}
that are referenced from at least one @ref{223e,,nested scope} inside the function

@item

@geindex co_freevars (codeobject 的屬性)
@anchor{reference/datamodel codeobject co_freevars}@anchor{21f9}
@deffn {屬性} codeobject.co_freevars
@end deffn

@tab

A @ref{60c,,tuple} containing the names of
@ref{180c,,free (closure) variables} that a @ref{223e,,nested scope}
references in an outer scope. See also @ref{14d1,,function.__closure__}.

Note: references to global and builtin names are `not' included.

@item

@geindex co_code (codeobject 的屬性)
@anchor{reference/datamodel codeobject co_code}@anchor{223f}
@deffn {屬性} codeobject.co_code
@end deffn

@tab

A string representing the sequence of @ref{4a5,,bytecode} instructions in
the function

@item

@geindex co_consts (codeobject 的屬性)
@anchor{reference/datamodel codeobject co_consts}@anchor{1814}
@deffn {屬性} codeobject.co_consts
@end deffn

@tab

A @ref{60c,,tuple} containing the literals used by the @ref{4a5,,bytecode} in
the function

@item

@geindex co_names (codeobject 的屬性)
@anchor{reference/datamodel codeobject co_names}@anchor{2240}
@deffn {屬性} codeobject.co_names
@end deffn

@tab

A @ref{60c,,tuple} containing the names used by the @ref{4a5,,bytecode} in
the function

@item

@geindex co_filename (codeobject 的屬性)
@anchor{reference/datamodel codeobject co_filename}@anchor{1565}
@deffn {屬性} codeobject.co_filename
@end deffn

@tab

The name of the file from which the code was compiled

@item

@geindex co_firstlineno (codeobject 的屬性)
@anchor{reference/datamodel codeobject co_firstlineno}@anchor{2241}
@deffn {屬性} codeobject.co_firstlineno
@end deffn

@tab

The line number of the first line of the function

@item

@geindex co_lnotab (codeobject 的屬性)
@anchor{reference/datamodel codeobject co_lnotab}@anchor{32f}
@deffn {屬性} codeobject.co_lnotab
@end deffn

@tab

A string encoding the mapping from @ref{4a5,,bytecode} offsets to line
numbers. For details, see the source code of the interpreter.


在 3.12 版之後被棄用: This attribute of code objects is deprecated, and may be removed in
Python 3.15.


@item

@geindex co_stacksize (codeobject 的屬性)
@anchor{reference/datamodel codeobject co_stacksize}@anchor{2242}
@deffn {屬性} codeobject.co_stacksize
@end deffn

@tab

The required stack size of the code object

@item

@geindex co_flags (codeobject 的屬性)
@anchor{reference/datamodel codeobject co_flags}@anchor{1848}
@deffn {屬性} codeobject.co_flags
@end deffn

@tab

An @ref{19b,,integer} encoding a number of flags for the
interpreter.

@end multitable


@geindex object（物件）;generator（產生器）

The following flag bits are defined for @ref{1848,,co_flags}:
bit @code{0x04} is set if
the function uses the @code{*arguments} syntax to accept an arbitrary number of
positional arguments; bit @code{0x08} is set if the function uses the
@code{**keywords} syntax to accept arbitrary keyword arguments; bit @code{0x20} is set
if the function is a generator. See @ref{2243,,Code Objects Bit Flags} for details
on the semantics of each flags that might be present.

Future feature declarations (for example, @code{from __future__ import division}) also use bits
in @ref{1848,,co_flags} to indicate whether a code object was compiled with a
particular feature enabled. See @ref{2244,,compiler_flag}.

Other bits in @ref{1848,,co_flags} are reserved for internal use.

@geindex documentation string（文件字串）

If a code object represents a function and has a docstring,
the @ref{2245,,CO_HAS_DOCSTRING} bit is set in @ref{1848,,co_flags}
and the first item in @ref{1814,,co_consts} is
the docstring of the function.

@node 用於程式碼物件的方法,,特殊唯讀屬性<2>,程式碼物件
@anchor{reference/datamodel methods-on-code-objects}@anchor{2246}
@subsubsection 用於程式碼物件的方法


@geindex co_positions() (codeobject 的方法)
@anchor{reference/datamodel codeobject co_positions}@anchor{7c9}
@deffn {方法} codeobject.co_positions ()

Returns an iterable over the source code positions of each @ref{4a5,,bytecode}
instruction in the code object.

The iterator returns @ref{60c,,tuple}s containing the @code{(start_line, end_line,
start_column, end_column)}. The `i-th' tuple corresponds to the
position of the source code that compiled to the `i-th' code unit.
Column information is 0-indexed utf-8 byte offsets on the given source
line.

This positional information can be missing. A non-exhaustive lists of
cases where this may happen:


@itemize -

@item 
Running the interpreter with @ref{16f,,-X} @code{no_debug_ranges}.

@item 
Loading a pyc file compiled while using @ref{16f,,-X} @code{no_debug_ranges}.

@item 
Position tuples corresponding to artificial instructions.

@item 
Line and column numbers that can't be represented due to
implementation specific limitations.
@end itemize

When this occurs, some or all of the tuple elements can be
@ref{87e,,None}.


在 3.11 版被加入.


@cartouche
@quotation 備註 
This feature requires storing column positions in code objects which may
result in a small increase of disk usage of compiled Python files or
interpreter memory usage. To avoid storing the extra information and/or
deactivate printing the extra traceback information, the
@ref{16f,,-X} @code{no_debug_ranges} command line flag or the 
@geindex PYTHONNODEBUGRANGES
@geindex 環境變數; PYTHONNODEBUGRANGES
@ref{7cc,,PYTHONNODEBUGRANGES}
environment variable can be used.
@end quotation
@end cartouche
@end deffn

@geindex co_lines() (codeobject 的方法)
@anchor{reference/datamodel codeobject co_lines}@anchor{34e}
@deffn {方法} codeobject.co_lines ()

Returns an iterator that yields information about successive ranges of
@ref{4a5,,bytecode}s. Each item yielded is a @code{(start, end, lineno)}
@ref{60c,,tuple}:


@itemize *

@item 
@code{start} (an @ref{19b,,int}) represents the offset (inclusive) of the start
of the @ref{4a5,,bytecode} range

@item 
@code{end} (an @ref{19b,,int}) represents the offset (exclusive) of the end of
the @ref{4a5,,bytecode} range

@item 
@code{lineno} is an @ref{19b,,int} representing the line number of the
@ref{4a5,,bytecode} range, or @code{None} if the bytecodes in the given range
have no line number
@end itemize

The items yielded will have the following properties:


@itemize *

@item 
The first range yielded will have a @code{start} of 0.

@item 
The @code{(start, end)} ranges will be non-decreasing and consecutive. That
is, for any pair of @ref{60c,,tuple}s, the @code{start} of the second will be
equal to the @code{end} of the first.

@item 
No range will be backwards: @code{end >= start} for all triples.

@item 
The last @ref{60c,,tuple} yielded will have @code{end} equal to the size of the
@ref{4a5,,bytecode}.
@end itemize

Zero-width ranges, where @code{start == end}, are allowed. Zero-width ranges
are used for lines that are present in the source code, but have been
eliminated by the @ref{4a5,,bytecode} compiler.


在 3.10 版被加入.



@subsubheading 也參考



@table @asis

@geindex Python Enhancement Proposals; PEP 626

@item PEP 626@footnote{https://peps.python.org/pep-0626/} - Precise line numbers for debugging and other tools.

The PEP that introduced the @code{co_lines()} method.
@end table

@end deffn

@geindex replace() (codeobject 的方法)
@anchor{reference/datamodel codeobject replace}@anchor{2247}
@deffn {方法} codeobject.replace (**kwargs)

Return a copy of the code object with new values for the specified fields.

Code objects are also supported by the generic function @ref{1c0,,copy.replace()}.


在 3.8 版被加入.

@end deffn

@node Frame objects,Traceback objects,程式碼物件,Internal types
@anchor{reference/datamodel frame-objects}@anchor{8e7}@anchor{reference/datamodel id8}@anchor{2248}
@subsubsection Frame objects


@geindex object（物件）;frame

Frame objects represent execution frames.  They may occur in
@ref{ce3,,traceback objects},
and are also passed to registered trace functions.

@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>. 
* Frame object methods:: 

@end menu

@node 特殊唯讀屬性<3>,特殊可寫屬性<2>,,Frame objects
@anchor{reference/datamodel id9}@anchor{2249}
@subsubsection 特殊唯讀屬性



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@geindex f_back (frame 的屬性)
@anchor{reference/datamodel frame f_back}@anchor{987}
@deffn {屬性} frame.f_back
@end deffn

@tab

Points to the previous stack frame (towards the caller),
or @code{None} if this is the bottom stack frame

@item

@geindex f_code (frame 的屬性)
@anchor{reference/datamodel frame f_code}@anchor{224a}
@deffn {屬性} frame.f_code
@end deffn

@tab

在這個 frame 中執行的@ref{4e1,,程式碼物件 (code object)}。存取這個屬性會引發一個附帶引數 @code{obj} 與 @code{"f_code"} 的@ref{1b70,,稽核事件} @code{object.__getattr__}。

@item

@geindex f_locals (frame 的屬性)
@anchor{reference/datamodel frame f_locals}@anchor{4a0}
@deffn {屬性} frame.f_locals
@end deffn

@tab

The mapping used by the frame to look up
@ref{21f8,,local variables}.
If the frame refers to an @ref{49c,,optimized scope},
this may return a write-through proxy object.


在 3.13 版的變更: Return a proxy for optimized scopes.


@item

@geindex f_globals (frame 的屬性)
@anchor{reference/datamodel frame f_globals}@anchor{224b}
@deffn {屬性} frame.f_globals
@end deffn

@tab

The dictionary used by the frame to look up
@ref{21f8,,global variables}

@item

@geindex f_builtins (frame 的屬性)
@anchor{reference/datamodel frame f_builtins}@anchor{224c}
@deffn {屬性} frame.f_builtins
@end deffn

@tab

The dictionary used by the frame to look up
@ref{21f8,,built-in (intrinsic) names}

@item

@geindex f_lasti (frame 的屬性)
@anchor{reference/datamodel frame f_lasti}@anchor{a7f}
@deffn {屬性} frame.f_lasti
@end deffn

@tab

The "precise instruction" of the frame object
(this is an index into the @ref{4a5,,bytecode} string of the
@ref{4e1,,code object})

@item

@geindex f_generator (frame 的屬性)
@anchor{reference/datamodel frame f_generator}@anchor{224d}
@deffn {屬性} frame.f_generator
@end deffn

@tab

The @ref{125c,,generator} or @ref{6b2,,coroutine} object that owns this frame,
or @code{None} if the frame is a normal function.


在 3.14 版被加入.


@end multitable


@geindex f_trace （frame 屬性）
@geindex f_trace_lines （frame 屬性）
@geindex f_trace_opcodes （frame 屬性）
@geindex f_lineno （frame 屬性）

@node 特殊可寫屬性<2>,Frame object methods,特殊唯讀屬性<3>,Frame objects
@anchor{reference/datamodel id10}@anchor{224e}
@subsubsection 特殊可寫屬性



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@geindex f_trace (frame 的屬性)
@anchor{reference/datamodel frame f_trace}@anchor{224f}
@deffn {屬性} frame.f_trace
@end deffn

@tab

If not @code{None}, this is a function called for various events during
code execution (this is used by debuggers). Normally an event is
triggered for each new source line (see @ref{dd1,,f_trace_lines}).

@item

@geindex f_trace_lines (frame 的屬性)
@anchor{reference/datamodel frame f_trace_lines}@anchor{dd1}
@deffn {屬性} frame.f_trace_lines
@end deffn

@tab

Set this attribute to @ref{d23,,False} to disable triggering a tracing
event for each source line.

@item

@geindex f_trace_opcodes (frame 的屬性)
@anchor{reference/datamodel frame f_trace_opcodes}@anchor{dd2}
@deffn {屬性} frame.f_trace_opcodes
@end deffn

@tab

Set this attribute to @ref{e02,,True} to allow per-opcode events to be
requested. Note that this may lead to
undefined interpreter behaviour if exceptions raised by the trace
function escape to the function being traced.

@item

@geindex f_lineno (frame 的屬性)
@anchor{reference/datamodel frame f_lineno}@anchor{9a8}
@deffn {屬性} frame.f_lineno
@end deffn

@tab

The current line number of the frame -- writing to this
from within a trace function jumps to the given line (only for the bottom-most
frame).  A debugger can implement a Jump command (aka Set Next Statement)
by writing to this attribute.

@end multitable


@node Frame object methods,,特殊可寫屬性<2>,Frame objects
@anchor{reference/datamodel frame-object-methods}@anchor{2250}
@subsubsection Frame object methods


Frame objects support one method:

@geindex clear() (frame 的方法)
@anchor{reference/datamodel frame clear}@anchor{57f}
@deffn {方法} frame.clear ()

This method clears all references to @ref{21f8,,local variables} held by the
frame.  Also, if the frame belonged to a @ref{125c,,generator}, the generator
is finalized.  This helps break reference cycles involving frame
objects (for example when catching an @ref{1b3a,,exception}
and storing its @ref{ce3,,traceback} for later use).

@ref{244,,RuntimeError} is raised if the frame is currently executing
or suspended.


在 3.4 版被加入.



在 3.13 版的變更: Attempting to clear a suspended frame raises @ref{244,,RuntimeError}
(as has always been the case for executing frames).

@end deffn

@node Traceback objects,Slice objects,Frame objects,Internal types
@anchor{reference/datamodel id11}@anchor{2251}@anchor{reference/datamodel traceback-objects}@anchor{ce3}
@subsubsection Traceback objects


@geindex object（物件）;traceback
@geindex stack（堆疊）;trace（追蹤）
@geindex exception（例外）;handler（處理器）
@geindex execution（執行）;stack（堆疊）
@geindex exc_info （sys 模組中）
@geindex last_traceback （sys 模組中）
@geindex sys.exc_info
@geindex sys.exception
@geindex sys.last_traceback

Traceback objects represent the stack trace of an @ref{1f39,,exception}.
A traceback object
is implicitly created when an exception occurs, and may also be explicitly
created by calling @ref{ce1,,types.TracebackType}.


在 3.7 版的變更: Traceback objects can now be explicitly instantiated from Python code.


For implicitly created tracebacks, when the search for an exception handler
unwinds the execution stack, at each unwound level a traceback object is
inserted in front of the current traceback.  When an exception handler is
entered, the stack trace is made available to the program. (See section
@ref{8f0,,try 陳述式}.) It is accessible as the third item of the
tuple returned by @ref{893,,sys.exc_info()}, and as the
@ref{14c7,,__traceback__} attribute
of the caught exception.

When the program contains no suitable
handler, the stack trace is written (nicely formatted) to the standard error
stream; if the interpreter is interactive, it is also made available to the user
as @ref{6e1,,sys.last_traceback}.

For explicitly created tracebacks, it is up to the creator of the traceback
to determine how the @ref{ce2,,tb_next} attributes should be linked to
form a full stack trace.

@geindex tb_frame （traceback 屬性）
@geindex tb_lineno （traceback 屬性）
@geindex tb_lasti （traceback 屬性）
@geindex statement（陳述式）;try

特殊唯讀屬性：


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@geindex tb_frame (traceback 的屬性)
@anchor{reference/datamodel traceback tb_frame}@anchor{2252}
@deffn {屬性} traceback.tb_frame
@end deffn

@tab

Points to the execution @ref{8e7,,frame} of the current
level.

存取此屬性會引發一個附帶引數 @code{obj} 與 @code{"tb_frame"} 的@ref{1b70,,稽核事件} @code{object.__getattr__}。

@item

@geindex tb_lineno (traceback 的屬性)
@anchor{reference/datamodel traceback tb_lineno}@anchor{2253}
@deffn {屬性} traceback.tb_lineno
@end deffn

@tab

Gives the line number where the exception occurred

@item

@geindex tb_lasti (traceback 的屬性)
@anchor{reference/datamodel traceback tb_lasti}@anchor{2254}
@deffn {屬性} traceback.tb_lasti
@end deffn

@tab

Indicates the "precise instruction".

@end multitable


The line number and last instruction in the traceback may differ from the
line number of its @ref{8e7,,frame object} if the exception
occurred in a
@ref{8f0,,try} statement with no matching except clause or with a
@ref{1b0,,finally} clause.

@geindex tb_next （traceback 屬性）

@geindex tb_next (traceback 的屬性)
@anchor{reference/datamodel traceback tb_next}@anchor{ce2}
@deffn {屬性} traceback.tb_next

The special writable attribute @code{tb_next} is the next level in the
stack trace (towards the frame where the exception occurred), or @code{None} if
there is no next level.


在 3.7 版的變更: This attribute is now writable

@end deffn

@node Slice objects,Static method objects,Traceback objects,Internal types
@anchor{reference/datamodel slice-objects}@anchor{2255}
@subsubsection Slice objects


@geindex built-in function（內建函式）;slice（切片）

Slice objects are used to represent slices for
@ref{582,,__getitem__()}
methods.  They are also created by the built-in @ref{68d,,slice()} function.

@geindex start （slice 物件屬性）
@geindex stop （slice 物件屬性）
@geindex step （slice 物件屬性）

Special read-only attributes: @ref{2256,,start} is the lower bound;
@ref{2257,,stop} is the upper bound; @ref{2258,,step} is the step
value; each is @code{None} if omitted.  These attributes can have any type.

Slice objects support one method:

@geindex indices() (slice 的方法)
@anchor{reference/datamodel slice indices}@anchor{1222}
@deffn {方法} slice.indices (self, length)

This method takes a single integer argument `length' and computes
information about the slice that the slice object would describe if
applied to a sequence of `length' items.  It returns a tuple of three
integers; respectively these are the `start' and `stop' indices and the
`step' or stride length of the slice. Missing or out-of-bounds indices
are handled in a manner consistent with regular slices.
@end deffn

@node Static method objects,Class method objects,Slice objects,Internal types
@anchor{reference/datamodel static-method-objects}@anchor{2259}
@subsubsection Static method objects


Static method objects provide a way of defeating the transformation of function
objects to method objects described above. A static method object is a wrapper
around any other object, usually a user-defined method object. When a static
method object is retrieved from a class or a class instance, the object actually
returned is the wrapped object, which is not subject to any further
transformation. Static method objects are also callable. Static method
objects are created by the built-in @ref{451,,staticmethod()} constructor.

@node Class method objects,,Static method objects,Internal types
@anchor{reference/datamodel class-method-objects}@anchor{225a}
@subsubsection Class method objects


A class method object, like a static method object, is a wrapper around another
object that alters the way in which that object is retrieved from classes and
class instances. The behaviour of class method objects upon such retrieval is
described above, under @ref{1f6e,,"instance methods"}. Class method objects are created
by the built-in @ref{489,,classmethod()} constructor.

@node Special method names,協程,標準型別階層,資料模型
@anchor{reference/datamodel special-method-names}@anchor{225b}@anchor{reference/datamodel specialnames}@anchor{e63}
@subsection Special method names


@geindex operator（運算子）;overloading（多載）
@geindex __getitem__() （對映物件方法）

A class can implement certain operations that are invoked by special syntax
(such as arithmetic operations or subscripting and slicing) by defining methods
with special names. This is Python's approach to `operator overloading',
allowing classes to define their own behavior with respect to language
operators.  For instance, if a class defines a method named
@ref{582,,__getitem__()},
and @code{x} is an instance of this class, then @code{x[i]} is roughly equivalent
to @code{type(x).__getitem__(x, i)}.  Except where mentioned, attempts to execute an
operation raise an exception when no appropriate method is defined (typically
@ref{5e8,,AttributeError} or @ref{198,,TypeError}).

Setting a special method to @code{None} indicates that the corresponding
operation is not available.  For example, if a class sets
@ref{e64,,__iter__()} to @code{None}, the class is not iterable, so calling
@ref{9d0,,iter()} on its instances will raise a @ref{198,,TypeError} (without
falling back to @ref{582,,__getitem__()}). @footnote{
The @ref{cea,,__hash__()}, @ref{e64,,__iter__()},
@ref{e81,,__reversed__()}, @ref{15b1,,__contains__()},
@ref{93b,,__class_getitem__()} and @ref{e47,,__fspath__()}
methods have special handling for this. Others
will still raise a @ref{198,,TypeError}, but may do so by relying on
the behavior that @code{None} is not callable.
}

When implementing a class that emulates any built-in type, it is important that
the emulation only be implemented to the degree that it makes sense for the
object being modelled.  For example, some sequences may work well with retrieval
of individual elements, but extracting a slice may not make sense.
(One example of this is the @ref{225c,,NodeList} interface
in the W3C's Document Object Model.)

@menu
* Basic customization:: 
* Customizing attribute access:: 
* Customizing class creation:: 
* Customizing instance and subclass checks:: 
* Emulating generic types:: 
* Emulating callable objects:: 
* Emulating container types:: 
* Emulating numeric types:: 
* With 陳述式的情境管理器:: 
* Customizing positional arguments in class pattern matching:: 
* Emulating buffer types:: 
* Annotations:: 
* Special method lookup:: 

@end menu

@node Basic customization,Customizing attribute access,,Special method names
@anchor{reference/datamodel basic-customization}@anchor{225d}@anchor{reference/datamodel customization}@anchor{225e}
@subsubsection Basic customization


@geindex __new__() (object 的方法)
@anchor{reference/datamodel object __new__}@anchor{799}
@deffn {方法} object.__new__ (cls[, ...])

@geindex subclassing（子類別化）;immutable types（不可變型別）

Called to create a new instance of class `cls'.  @ref{799,,__new__()} is a static
method (special-cased so you need not declare it as such) that takes the class
of which an instance was requested as its first argument.  The remaining
arguments are those passed to the object constructor expression (the call to the
class).  The return value of @ref{799,,__new__()} should be the new object instance
(usually an instance of `cls').

Typical implementations create a new instance of the class by invoking the
superclass's @ref{799,,__new__()} method using @code{super().__new__(cls[, ...])}
with appropriate arguments and then modifying the newly created instance
as necessary before returning it.

If @ref{799,,__new__()} is invoked during object construction and it returns an
instance of `cls', then the new instance’s @ref{8b7,,__init__()} method
will be invoked like @code{__init__(self[, ...])}, where `self' is the new instance
and the remaining arguments are the same as were passed to the object constructor.

If @ref{799,,__new__()} does not return an instance of `cls', then the new instance's
@ref{8b7,,__init__()} method will not be invoked.

@ref{799,,__new__()} is intended mainly to allow subclasses of immutable types (like
int, str, or tuple) to customize instance creation.  It is also commonly
overridden in custom metaclasses in order to customize class creation.
@end deffn

@geindex __init__() (object 的方法)
@anchor{reference/datamodel object __init__}@anchor{8b7}
@deffn {方法} object.__init__ (self[, ...])

@geindex class（類別）;constructor（建構函式）

Called after the instance has been created (by @ref{799,,__new__()}), but before
it is returned to the caller.  The arguments are those passed to the
class constructor expression.  If a base class has an @ref{8b7,,__init__()}
method, the derived class's @ref{8b7,,__init__()} method, if any, must explicitly
call it to ensure proper initialization of the base class part of the
instance; for example: @code{super().__init__([args...])}.

Because @ref{799,,__new__()} and @ref{8b7,,__init__()} work together in constructing
objects (@ref{799,,__new__()} to create it, and @ref{8b7,,__init__()} to customize it),
no non-@code{None} value may be returned by @ref{8b7,,__init__()}; doing so will
cause a @ref{198,,TypeError} to be raised at runtime.
@end deffn

@geindex __del__() (object 的方法)
@anchor{reference/datamodel object __del__}@anchor{11f8}
@deffn {方法} object.__del__ (self)

@geindex destructor（解構函式）
@geindex finalizer（終結函式）
@geindex statement（陳述式）;del

Called when the instance is about to be destroyed.  This is also called a
finalizer or (improperly) a destructor.  If a base class has a
@ref{11f8,,__del__()} method, the derived class's @ref{11f8,,__del__()} method,
if any, must explicitly call it to ensure proper deletion of the base
class part of the instance.

It is possible (though not recommended!) for the @ref{11f8,,__del__()} method
to postpone destruction of the instance by creating a new reference to
it.  This is called object `resurrection'.  It is implementation-dependent
whether @ref{11f8,,__del__()} is called a second time when a resurrected object
is about to be destroyed; the current @ref{8fd,,CPython} implementation
only calls it once.

It is not guaranteed that @ref{11f8,,__del__()} methods are called for objects
that still exist when the interpreter exits.
@ref{c66,,weakref.finalize} provides a straightforward way to register
a cleanup function to be called when an object is garbage collected.

@cartouche
@quotation 備註 
@code{del x} doesn't directly call @code{x.__del__()} --- the former decrements
the reference count for @code{x} by one, and the latter is only called when
@code{x}'s reference count reaches zero.
@end quotation
@end cartouche

`CPython 實作細節：' It is possible for a reference cycle to prevent the reference count
of an object from going to zero.  In this case, the cycle will be
later detected and deleted by the @ref{1765,,cyclic garbage collector}.  A common cause of reference cycles is when
an exception has been caught in a local variable.  The frame's
locals then reference the exception, which references its own
traceback, which references the locals of all frames caught in the
traceback.


@subsubheading 也參考


@ref{64,,gc} 模組的文件。


@cartouche
@quotation 警告 
Due to the precarious circumstances under which @ref{11f8,,__del__()} methods are
invoked, exceptions that occur during their execution are ignored, and a warning
is printed to @code{sys.stderr} instead.  In particular:


@itemize *

@item 
@ref{11f8,,__del__()} can be invoked when arbitrary code is being executed,
including from any arbitrary thread.  If @ref{11f8,,__del__()} needs to take
a lock or invoke any other blocking resource, it may deadlock as
the resource may already be taken by the code that gets interrupted
to execute @ref{11f8,,__del__()}.

@item 
@ref{11f8,,__del__()} can be executed during interpreter shutdown.  As a
consequence, the global variables it needs to access (including other
modules) may already have been deleted or set to @code{None}. Python
guarantees that globals whose name begins with a single underscore
are deleted from their module before other globals are deleted; if
no other references to such globals exist, this may help in assuring
that imported modules are still available at the time when the
@ref{11f8,,__del__()} method is called.
@end itemize
@end quotation
@end cartouche

@geindex repr() （內建函式）;__repr__() （物件方法）
@end deffn

@geindex __repr__() (object 的方法)
@anchor{reference/datamodel object __repr__}@anchor{828}
@deffn {方法} object.__repr__ (self)

Called by the @ref{1c1,,repr()} built-in function to compute the "official" string
representation of an object.  If at all possible, this should look like a
valid Python expression that could be used to recreate an object with the
same value (given an appropriate environment).  If this is not possible, a
string of the form @code{<...some useful description...>} should be returned.
The return value must be a string object. If a class defines @ref{828,,__repr__()}
but not @ref{829,,__str__()}, then @ref{828,,__repr__()} is also used when an
"informal" string representation of instances of that class is required.

This is typically used for debugging, so it is important that the representation
is information-rich and unambiguous. A default implementation is provided by the
@ref{c75,,object} class itself.

@geindex string（字串）;__str__() （物件方法）
@geindex format() （內建函式）;__str__() （物件方法）
@geindex print() （內建函式）;__str__() （物件方法）
@end deffn

@geindex __str__() (object 的方法)
@anchor{reference/datamodel object __str__}@anchor{829}
@deffn {方法} object.__str__ (self)

Called by @ref{169,,str(object)}, the default @ref{82a,,__format__()} implementation,
and the built-in function @ref{1170,,print()}, to compute the "informal" or nicely
printable string representation of an object.  The return value must be a
@ref{1ea8,,str} object.

This method differs from @ref{828,,object.__repr__()} in that there is no
expectation that @ref{829,,__str__()} return a valid Python expression: a more
convenient or concise representation can be used.

The default implementation defined by the built-in type @ref{c75,,object}
calls @ref{828,,object.__repr__()}.

@c XXX what about subclasses of string?
@end deffn

@geindex __bytes__() (object 的方法)
@anchor{reference/datamodel object __bytes__}@anchor{7f9}
@deffn {方法} object.__bytes__ (self)

@geindex built-in function（內建函式）;bytes（位元組）

Called by @ref{1d61,,bytes} to compute a byte-string representation
of an object. This should return a @ref{192,,bytes} object. The @ref{c75,,object}
class itself does not provide this method.

@geindex string（字串）;__format__() （物件方法）
@geindex string（字串）;conversion
@geindex built-in function（內建函式）;print
@end deffn

@geindex __format__() (object 的方法)
@anchor{reference/datamodel object __format__}@anchor{82a}
@deffn {方法} object.__format__ (self, format_spec)

Called by the @ref{199,,format()} built-in function,
and by extension, evaluation of @ref{19a,,formatted string literals} and the @ref{82c,,str.format()} method, to produce a "formatted"
string representation of an object. The `format_spec' argument is
a string that contains a description of the formatting options desired.
The interpretation of the `format_spec' argument is up to the type
implementing @ref{82a,,__format__()}, however most classes will either
delegate formatting to one of the built-in types, or use a similar
formatting option syntax.

See @ref{4f4,,格式規格 (Format Specification) 迷你語言} for a description of the standard formatting syntax.

回傳值必須是個字串物件。

The default implementation by the @ref{c75,,object} class should be given
an empty `format_spec' string. It delegates to @ref{829,,__str__()}.


在 3.4 版的變更: The __format__ method of @code{object} itself raises a @ref{198,,TypeError}
if passed any non-empty string.



在 3.7 版的變更: @code{object.__format__(x, '@w{'})} is now equivalent to @code{str(x)} rather
than @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{225f}@anchor{reference/datamodel object __lt__}@anchor{14a1}
@deffn {方法} object.__lt__ (self, other)
@anchor{reference/datamodel object __le__}@anchor{150b}
@deffnx {方法} object.__le__ (self, other)
@anchor{reference/datamodel object __eq__}@anchor{ce9}
@deffnx {方法} object.__eq__ (self, other)
@anchor{reference/datamodel object __ne__}@anchor{170b}
@deffnx {方法} object.__ne__ (self, other)
@anchor{reference/datamodel object __gt__}@anchor{150c}
@deffnx {方法} object.__gt__ (self, other)
@anchor{reference/datamodel object __ge__}@anchor{150d}
@deffnx {方法} object.__ge__ (self, other)

@geindex comparison（比較）

These are the so-called "rich comparison" methods. The correspondence between
operator symbols and method names is as follows: @code{x<y} calls @code{x.__lt__(y)},
@code{x<=y} calls @code{x.__le__(y)}, @code{x==y} calls @code{x.__eq__(y)}, @code{x!=y} calls
@code{x.__ne__(y)}, @code{x>y} calls @code{x.__gt__(y)}, and @code{x>=y} calls
@code{x.__ge__(y)}.

A rich comparison method may return the singleton @ref{1a2,,NotImplemented} if it does
not implement the operation for a given pair of arguments. By convention,
@code{False} and @code{True} are returned for a successful comparison. However, these
methods can return any value, so if the comparison operator is used in a Boolean
context (e.g., in the condition of an @code{if} statement), Python will call
@ref{3c1,,bool()} on the value to determine if the result is true or false.

By default, @code{object} implements @ref{ce9,,__eq__()} by using @code{is}, returning
@ref{1a2,,NotImplemented} in the case of a false comparison:
@code{True if x is y else NotImplemented}. For @ref{170b,,__ne__()}, by default it
delegates to @ref{ce9,,__eq__()} and inverts the result unless it is
@code{NotImplemented}.  There are no other implied relationships among the
comparison operators or default implementations; for example, the truth of
@code{(x<y or x==y)} does not imply @code{x<=y}. To automatically generate ordering
operations from a single root operation, see @ref{113d,,functools.total_ordering()}.

By default, the @ref{c75,,object} class provides implementations consistent
with @ref{1b32,,Value comparisons}: equality compares according to
object identity, and order comparisons raise @ref{198,,TypeError}. Each default
method may generate these results directly, but may also return
@ref{1a2,,NotImplemented}.

See the paragraph on @ref{cea,,__hash__()} for
some important notes on creating @ref{81d,,hashable} objects which support
custom comparison operations and are usable as dictionary keys.

There are no swapped-argument versions of these methods (to be used when the
left argument does not support the operation but the right argument does);
rather, @ref{14a1,,__lt__()} and @ref{150c,,__gt__()} are each other's reflection,
@ref{150b,,__le__()} and @ref{150d,,__ge__()} are each other's reflection, and
@ref{ce9,,__eq__()} and @ref{170b,,__ne__()} are their own reflection.
If the operands are of different types, and the right operand's type is
a direct or indirect subclass of the left operand's type,
the reflected method of the right operand has priority, otherwise
the left operand's method has priority.  Virtual subclassing is
not considered.

When no appropriate method returns any value other than @ref{1a2,,NotImplemented}, the
@code{==} and @code{!=} operators will fall back to @code{is} and @code{is not}, respectively.
@end deffn

@geindex __hash__() (object 的方法)
@anchor{reference/datamodel object __hash__}@anchor{cea}
@deffn {方法} object.__hash__ (self)

@geindex object（物件）;dictionary（字典）
@geindex built-in function（內建函式）;hash（雜湊）

Called by built-in function @ref{7fa,,hash()} and for operations on members of
hashed collections including @ref{184,,set}, @ref{7eb,,frozenset}, and
@ref{183,,dict}.  The @code{__hash__()} method should return an integer. The only required
property is that objects which compare equal have the same hash value; it is
advised to mix together the hash values of the components of the object that
also play a part in comparison of objects by packing them into a tuple and
hashing the tuple. Example:

@example
def __hash__(self):
    return hash((self.name, self.nick, self.color))
@end example

@cartouche
@quotation 備註 
@ref{7fa,,hash()} truncates the value returned from an object's custom
@ref{cea,,__hash__()} method to the size of a @ref{c4c,,Py_ssize_t}.  This is
typically 8 bytes on 64-bit builds and 4 bytes on 32-bit builds.  If an
object's   @ref{cea,,__hash__()} must interoperate on builds of different bit
sizes, be sure to check the width on all supported builds.  An easy way
to do this is with
@code{python -c "import sys; print(sys.hash_info.width)"}.
@end quotation
@end cartouche

If a class does not define an @ref{ce9,,__eq__()} method it should not define a
@ref{cea,,__hash__()} operation either; if it defines @ref{ce9,,__eq__()} but not
@ref{cea,,__hash__()}, its instances will not be usable as items in hashable
collections.  If a class defines mutable objects and implements an
@ref{ce9,,__eq__()} method, it should not implement @ref{cea,,__hash__()}, since the
implementation of @ref{81d,,hashable} collections requires that a key's hash value is
immutable (if the object's hash value changes, it will be in the wrong hash
bucket).

User-defined classes have @ref{ce9,,__eq__()} and @ref{cea,,__hash__()} methods
by default (inherited from the @ref{c75,,object} class); with them, all objects compare
unequal (except with themselves) and @code{x.__hash__()} returns an appropriate
value such that @code{x == y} implies both that @code{x is y} and @code{hash(x) == hash(y)}.

A class that overrides @ref{ce9,,__eq__()} and does not define @ref{cea,,__hash__()}
will have its @ref{cea,,__hash__()} implicitly set to @code{None}.  When the
@ref{cea,,__hash__()} method of a class is @code{None}, instances of the class will
raise an appropriate @ref{198,,TypeError} when a program attempts to retrieve
their hash value, and will also be correctly identified as unhashable when
checking @code{isinstance(obj, collections.abc.Hashable)}.

If a class that overrides @ref{ce9,,__eq__()} needs to retain the implementation
of @ref{cea,,__hash__()} from a parent class, the interpreter must be told this
explicitly by setting @code{__hash__ = <ParentClass>.__hash__}.

If a class that does not override @ref{ce9,,__eq__()} wishes to suppress hash
support, it should include @code{__hash__ = None} in the class definition.
A class which defines its own @ref{cea,,__hash__()} that explicitly raises
a @ref{198,,TypeError} would be incorrectly identified as hashable by
an @code{isinstance(obj, collections.abc.Hashable)} call.

@cartouche
@quotation 備註 
By default, the @ref{cea,,__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.

This is intended to provide protection against a denial-of-service caused
by carefully chosen inputs that exploit the worst case performance of a
dict insertion, `O'(`n'@w{^2}) complexity.  See
@indicateurl{http://ocert.org/advisories/ocert-2011-003.html} for details.

Changing hash values affects the iteration order of sets.
Python has never made guarantees about this ordering
(and it typically varies between 32-bit and 64-bit builds).

另請參閱 
@geindex PYTHONHASHSEED
@geindex 環境變數; PYTHONHASHSEED
@ref{1278,,PYTHONHASHSEED}。
@end quotation
@end cartouche


在 3.3 版的變更: Hash randomization is enabled by default.

@end deffn

@geindex __bool__() (object 的方法)
@anchor{reference/datamodel object __bool__}@anchor{14d6}
@deffn {方法} object.__bool__ (self)

@geindex __len__() （對映物件方法）

Called to implement truth value testing and the built-in operation
@code{bool()}; should return @code{False} or @code{True}.  When this method is not
defined, @ref{2260,,__len__()} is called, if it is defined, and the object is
considered true if its result is nonzero.  If a class defines neither
@code{__len__()} nor @code{__bool__()} (which is true of the @ref{c75,,object}
class itself), all its instances are considered true.
@end deffn

@node Customizing attribute access,Customizing class creation,Basic customization,Special method names
@anchor{reference/datamodel attribute-access}@anchor{2261}@anchor{reference/datamodel customizing-attribute-access}@anchor{2262}
@subsubsection Customizing attribute access


The following methods can be defined to customize the meaning of attribute
access (use of, assignment to, or deletion of @code{x.name}) for class instances.

@c XXX explain how descriptors interfere here!

@geindex __getattr__() (object 的方法)
@anchor{reference/datamodel object __getattr__}@anchor{6f3}
@deffn {方法} object.__getattr__ (self, name)

Called when the default attribute access fails with an @ref{5e8,,AttributeError}
(either @ref{dc6,,__getattribute__()} raises an @ref{5e8,,AttributeError} because
`name' is not an instance attribute or an attribute in the class tree
for @code{self}; or @ref{16dc,,__get__()} of a `name' property raises
@ref{5e8,,AttributeError}).  This method should either return the (computed)
attribute value or raise an @ref{5e8,,AttributeError} exception.
The @ref{c75,,object} class itself does not provide this method.

Note that if the attribute is found through the normal mechanism,
@ref{6f3,,__getattr__()} is not called.  (This is an intentional asymmetry between
@ref{6f3,,__getattr__()} and @ref{222d,,__setattr__()}.) This is done both for efficiency
reasons and because otherwise @ref{6f3,,__getattr__()} would have no way to access
other attributes of the instance.  Note that at least for instance variables,
you can take total control by not inserting any values in the instance attribute
dictionary (but instead inserting them in another object).  See the
@ref{dc6,,__getattribute__()} method below for a way to actually get total control
over attribute access.
@end deffn

@geindex __getattribute__() (object 的方法)
@anchor{reference/datamodel object __getattribute__}@anchor{dc6}
@deffn {方法} object.__getattribute__ (self, name)

Called unconditionally to implement attribute accesses for instances of the
class. If the class also defines @ref{6f3,,__getattr__()}, the latter will not be
called unless @ref{dc6,,__getattribute__()} either calls it explicitly or raises an
@ref{5e8,,AttributeError}. This method should return the (computed) attribute value
or raise an @ref{5e8,,AttributeError} exception. In order to avoid infinite
recursion in this method, its implementation should always call the base class
method with the same name to access any attributes it needs, for example,
@code{object.__getattribute__(self, name)}.

@cartouche
@quotation 備註 
This method may still be bypassed when looking up special methods as the
result of implicit invocation via language syntax or
@ref{2200,,built-in functions}.
See @ref{2263,,Special method lookup}.
@end quotation
@end cartouche


For certain sensitive attribute accesses, raises an
@ref{1b70,,auditing event} @code{object.__getattr__} with arguments
@code{obj} and @code{name}.

@end deffn

@geindex __setattr__() (object 的方法)
@anchor{reference/datamodel object __setattr__}@anchor{222d}
@deffn {方法} object.__setattr__ (self, name, value)

Called when an attribute assignment is attempted.  This is called instead of
the normal mechanism (i.e. store the value in the instance dictionary).
`name' is the attribute name, `value' is the value to be assigned to it.

If @ref{222d,,__setattr__()} wants to assign to an instance attribute, it should
call the base class method with the same name, for example,
@code{object.__setattr__(self, name, value)}.


For certain sensitive attribute assignments, raises an
@ref{1b70,,auditing event} @code{object.__setattr__} with arguments
@code{obj}, @code{name}, @code{value}.

@end deffn

@geindex __delattr__() (object 的方法)
@anchor{reference/datamodel object __delattr__}@anchor{222e}
@deffn {方法} object.__delattr__ (self, name)

Like @ref{222d,,__setattr__()} but for attribute deletion instead of assignment.  This
should only be implemented if @code{del obj.name} is meaningful for the object.


For certain sensitive attribute deletions, raises an
@ref{1b70,,auditing event} @code{object.__delattr__} with arguments
@code{obj} and @code{name}.

@end deffn

@geindex __dir__() (object 的方法)
@anchor{reference/datamodel object __dir__}@anchor{176b}
@deffn {方法} object.__dir__ (self)

Called when @ref{83d,,dir()} is called on the object. An iterable must be
returned. @ref{83d,,dir()} converts the returned iterable to a list and sorts it.
@end deffn

@menu
* Customizing module attribute access:: 
* 實作描述器:: 
* Invoking Descriptors:: 
* __slots__: __slots__<2>. 

@end menu

@node Customizing module attribute access,實作描述器,,Customizing attribute access
@anchor{reference/datamodel customizing-module-attribute-access}@anchor{2264}
@subsubsection Customizing module attribute access


@geindex __getattr__ （模組屬性）
@geindex __dir__ （模組屬性）
@geindex __class__ （模組屬性）

@geindex __getattr__() (module 的方法)
@geindex __dir__() (module 的方法)
@anchor{reference/datamodel module __getattr__}@anchor{ccf}
@deffn {方法} module.__getattr__ ()
@anchor{reference/datamodel module __dir__}@anchor{cd0}
@deffnx {方法} module.__dir__ ()
@end deffn

Special names @code{__getattr__} and @code{__dir__} can be also used to customize
access to module attributes. The @code{__getattr__} function at the module level
should accept one argument which is the name of an attribute and return the
computed value or raise an @ref{5e8,,AttributeError}. If an attribute is
not found on a module object through the normal lookup, i.e.
@ref{dc6,,object.__getattribute__()}, then @code{__getattr__} is searched in
the module @code{__dict__} before raising an @ref{5e8,,AttributeError}. If found,
it is called with the attribute name and the result is returned.

The @code{__dir__} function should accept no arguments, and return an iterable of
strings that represents the names accessible on module. If present, this
function overrides the standard @ref{83d,,dir()} search on a module.

@geindex __class__ (module 的屬性)
@anchor{reference/datamodel module __class__}@anchor{2265}
@deffn {屬性} module.__class__
@end deffn

For a more fine grained customization of the module behavior (setting
attributes, properties, etc.), one can set the @code{__class__} attribute of
a module object to a subclass of @ref{100f,,types.ModuleType}. For example:

@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 備註 
Defining module @code{__getattr__} and setting module @code{__class__} only
affect lookups made using the attribute access syntax -- directly accessing
the module globals (whether by code within the module, or via a reference
to the module's globals dictionary) is unaffected.
@end quotation
@end cartouche


在 3.5 版的變更: @code{__class__} 模組屬性現在是可寫入的。



在 3.7 版被加入: @code{__getattr__} 和 @code{__dir__} 模組屬性。



@subsubheading 也參考



@table @asis

@geindex Python Enhancement Proposals; PEP 562

@item PEP 562@footnote{https://peps.python.org/pep-0562/} - 模組 __getattr__ 和 __dir__

Describes the @code{__getattr__} and @code{__dir__} functions on modules.
@end table


@node 實作描述器,Invoking Descriptors,Customizing module attribute access,Customizing attribute access
@anchor{reference/datamodel descriptors}@anchor{e44}@anchor{reference/datamodel implementing-descriptors}@anchor{2266}
@subsubsection 實作描述器


The following methods only apply when an instance of the class containing the
method (a so-called `descriptor' class) appears in an `owner' class (the
descriptor must be in either the owner's class dictionary or in the class
dictionary for one of its parents).  In the examples below, "the attribute"
refers to the attribute whose name is the key of the property in the owner
class' @ref{776,,__dict__}.  The @ref{c75,,object} class itself does not
implement any of these protocols.

@geindex __get__() (object 的方法)
@anchor{reference/datamodel object __get__}@anchor{16dc}
@deffn {方法} object.__get__ (self, instance, owner=None)

Called to get the attribute of the owner class (class attribute access) or
of an instance of that class (instance attribute access). The optional
`owner' argument is the owner class, while `instance' is the instance that
the attribute was accessed through, or @code{None} when the attribute is
accessed through the `owner'.

This method should return the computed attribute value or raise an
@ref{5e8,,AttributeError} exception.

@geindex Python Enhancement Proposals; PEP 252
PEP 252@footnote{https://peps.python.org/pep-0252/} specifies that @ref{16dc,,__get__()} is callable with one or two
arguments.  Python's own built-in descriptors support this specification;
however, it is likely that some third-party tools have descriptors
that require both arguments.  Python's own @ref{dc6,,__getattribute__()}
implementation always passes in both arguments whether they are required
or not.
@end deffn

@geindex __set__() (object 的方法)
@anchor{reference/datamodel object __set__}@anchor{2267}
@deffn {方法} object.__set__ (self, instance, value)

Called to set the attribute on an instance `instance' of the owner class to a
new value, `value'.

Note, adding @ref{2267,,__set__()} or @ref{18b6,,__delete__()} changes the kind of
descriptor to a "data descriptor".  See @ref{2268,,Invoking Descriptors} for
more details.
@end deffn

@geindex __delete__() (object 的方法)
@anchor{reference/datamodel object __delete__}@anchor{18b6}
@deffn {方法} object.__delete__ (self, instance)

Called to delete the attribute on an instance `instance' of the owner class.
@end deffn

Instances of descriptors may also have the @code{__objclass__} attribute
present:

@geindex __objclass__ (object 的屬性)
@anchor{reference/datamodel object __objclass__}@anchor{2269}
@deffn {屬性} object.__objclass__

The attribute @code{__objclass__} is interpreted by the @ref{82,,inspect} module
as specifying the class where this object was defined (setting this
appropriately can assist in runtime introspection of dynamic class attributes).
For callables, it may indicate that an instance of the given type (or a
subclass) is expected or required as the first positional argument (for example,
CPython sets this attribute for unbound methods that are implemented in C).
@end deffn

@node Invoking Descriptors,__slots__<2>,實作描述器,Customizing attribute access
@anchor{reference/datamodel descriptor-invocation}@anchor{2268}@anchor{reference/datamodel invoking-descriptors}@anchor{226a}
@subsubsection Invoking Descriptors


In general, a descriptor is an object attribute with "binding behavior", one
whose attribute access has been overridden by methods in the descriptor
protocol:  @ref{16dc,,__get__()}, @ref{2267,,__set__()}, and
@ref{18b6,,__delete__()}. If any of
those methods are defined for an object, it is said to be a 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 base classes of @code{type(a)} excluding metaclasses.

However, 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 and how they were called.

The starting point for descriptor invocation is a binding, @code{a.x}. How the
arguments are assembled depends on @code{a}:


@table @asis

@item 直接呼叫

The simplest and least common call is when user code directly invokes a
descriptor method:    @code{x.__get__(a)}.

@item Instance Binding

If binding to an object instance, @code{a.x} is transformed into the call:
@code{type(a).__dict__['x'].__get__(a, type(a))}.

@item Class Binding

If binding to a class, @code{A.x} is transformed into the call:
@code{A.__dict__['x'].__get__(None, A)}.

@item Super Binding

A dotted lookup such as @code{super(A, a).x} searches
@code{a.__class__.__mro__} for a base class @code{B} following @code{A} and then
returns @code{B.__dict__['x'].__get__(a, A)}.  If not a descriptor, @code{x} is
returned unchanged.
@end table

@c class Desc:
@c     def __get__(*args):
@c         return args
@c 
@c class B:
@c 
@c     x = Desc()
@c 
@c class A(B):
@c 
@c     x = 999
@c 
@c     def m(self):
@c         'Demonstrate these two descriptor invocations are equivalent'
@c         result1 = super(A, self).x
@c         result2 = B.__dict__['x'].__get__(self, A)
@c         return result1 == result2

@c >>> a = A()
@c >>> a.__class__.__mro__.index(B) > a.__class__.__mro__.index(A)
@c True
@c >>> super(A, a).x == B.__dict__['x'].__get__(a, A)
@c True
@c >>> a.m()
@c True

For instance bindings, the precedence of descriptor invocation depends on
which descriptor methods are defined.  A descriptor can define any combination
of @ref{16dc,,__get__()}, @ref{2267,,__set__()} and
@ref{18b6,,__delete__()}.  If it does not
define @code{__get__()}, then accessing the attribute will return the descriptor
object itself unless there is a value in the object's instance dictionary.  If
the descriptor defines @code{__set__()} and/or @code{__delete__()}, it is a data
descriptor; if it defines neither, it is a non-data descriptor.  Normally, data
descriptors define both @code{__get__()} and @code{__set__()}, while non-data
descriptors have just the @code{__get__()} method.  Data descriptors with
@code{__get__()} and @code{__set__()} (and/or @code{__delete__()}) defined
always override a redefinition in an
instance dictionary.  In contrast, non-data descriptors can be overridden by
instances.

Python methods (including those decorated with
@ref{451,,@@staticmethod} and @ref{489,,@@classmethod}) are
implemented as non-data descriptors.  Accordingly, instances can redefine and
override methods.  This allows individual instances to acquire behaviors that
differ from other instances of the same class.

The @ref{4ae,,property()} function is implemented as a data descriptor. Accordingly,
instances cannot override the behavior of a property.

@node __slots__<2>,,Invoking Descriptors,Customizing attribute access
@anchor{reference/datamodel id13}@anchor{226b}@anchor{reference/datamodel slots}@anchor{2230}
@subsubsection __slots__


`__slots__' allow us to explicitly declare data members (like
properties) and deny the creation of @ref{776,,__dict__} and `__weakref__'
(unless explicitly declared in `__slots__' or available in a parent.)

The space saved over using @ref{776,,__dict__} can be significant.
Attribute lookup speed can be significantly improved as well.

@geindex object.__slots__ (內建變數)
@anchor{reference/datamodel object __slots__}@anchor{16df}
@deffn {資料} object.__slots__

This class variable can be assigned a string, iterable, or sequence of
strings with variable names used by instances.  `__slots__' reserves space
for the declared variables and prevents the automatic creation of
@ref{776,,__dict__}
and `__weakref__' for each instance.
@end deffn
@anchor{reference/datamodel datamodel-note-slots}@anchor{226c}
Notes on using `__slots__':


@itemize *

@item 
When inheriting from a class without `__slots__', the
@ref{776,,__dict__} and
`__weakref__' attribute of the instances will always be accessible.

@item 
Without a @ref{776,,__dict__} variable, instances cannot be assigned new
variables not
listed in the `__slots__' definition.  Attempts to assign to an unlisted
variable name raises @ref{5e8,,AttributeError}. If dynamic assignment of new
variables is desired, then add @code{'__dict__'} to the sequence of strings in
the `__slots__' declaration.

@item 
Without a `__weakref__' variable for each instance, classes defining
`__slots__' do not support @ref{11a,,weak references} to its instances.
If weak reference
support is needed, then add @code{'__weakref__'} to the sequence of strings in the
`__slots__' declaration.

@item 
`__slots__' are implemented at the class level by creating @ref{e44,,descriptors}
for each variable name.  As a result, class attributes
cannot be used to set default values for instance variables defined by
`__slots__'; otherwise, the class attribute would overwrite the descriptor
assignment.

@item 
The action of a `__slots__' declaration is not limited to the class
where it is defined.  `__slots__' declared in parents are available in
child classes. However, instances of a child subclass will get a
@ref{776,,__dict__} and `__weakref__' unless the subclass also defines
`__slots__' (which should only contain names of any `additional' slots).

@item 
If a class defines a slot also defined in a base class, the instance variable
defined by the base class slot is inaccessible (except by retrieving its
descriptor directly from the base class). This renders the meaning of the
program undefined.  In the future, a check may be added to prevent this.

@item 
@ref{198,,TypeError} will be raised if nonempty `__slots__' are defined for a
class derived from a
@ref{226d,,"variable-length" built-in type} such as
@ref{19b,,int}, @ref{192,,bytes}, and @ref{60c,,tuple}.

@item 
Any non-string @ref{1428,,iterable} may be assigned to `__slots__'.

@item 
If a @ref{183,,dictionary} is used to assign `__slots__', the dictionary
keys will be used as the slot names. The values of the dictionary can be used
to provide per-attribute docstrings that will be recognised by
@ref{be4,,inspect.getdoc()} and displayed in the output of @ref{acb,,help()}.

@item 
@ref{16a1,,__class__} assignment works only if both classes have the
same `__slots__'.

@item 
@ref{1f68,,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{198,,TypeError}.

@item 
If an @ref{4c3,,iterator} is used for `__slots__' then a @ref{17fc,,descriptor} is
created for each
of the iterator's values. However, the `__slots__' attribute will be an empty
iterator.
@end itemize

@node Customizing class creation,Customizing instance and subclass checks,Customizing attribute access,Special method names
@anchor{reference/datamodel class-customization}@anchor{e40}@anchor{reference/datamodel customizing-class-creation}@anchor{226e}
@subsubsection Customizing class creation


Whenever a class inherits from another class, @ref{83c,,__init_subclass__()} is
called on the parent class. This way, it is possible to write classes which
change the behavior of subclasses. This is closely related to class
decorators, but where class decorators only affect the specific class they're
applied to, @code{__init_subclass__} solely applies to future subclasses of the
class defining the method.

@geindex __init_subclass__() (object 的類別方法)
@anchor{reference/datamodel object __init_subclass__}@anchor{83c}
@deffn {方法} classmethod object.__init_subclass__ (cls)

This method is called whenever the containing class is subclassed.
`cls' is then the new subclass. If defined as a normal instance method,
this method is implicitly converted to a class method.

Keyword arguments which are given to a new class are passed to
the parent class's @code{__init_subclass__}. For compatibility with
other classes using @code{__init_subclass__}, one should take out the
needed keyword arguments and pass the others over to the base
class, as in:

@example
class Philosopher:
    def __init_subclass__(cls, /, default_name, **kwargs):
        super().__init_subclass__(**kwargs)
        cls.default_name = default_name

class AustralianPhilosopher(Philosopher, default_name="Bruce"):
    pass
@end example

The default implementation @code{object.__init_subclass__} does
nothing, but raises an error if it is called with any arguments.

@cartouche
@quotation 備註 
The metaclass hint @code{metaclass} is consumed by the rest of the type
machinery, and is never passed to @code{__init_subclass__} implementations.
The actual metaclass (rather than the explicit hint) can be accessed as
@code{type(cls)}.
@end quotation
@end cartouche


在 3.6 版被加入.

@end deffn

When a class is created, @code{type.__new__()} scans the class variables
and makes callbacks to those with a @ref{e43,,__set_name__()} hook.

@geindex __set_name__() (object 的方法)
@anchor{reference/datamodel object __set_name__}@anchor{e43}
@deffn {方法} object.__set_name__ (self, owner, name)

Automatically called at the time the owning class `owner' is
created. The object has been assigned to `name' in that class:

@example
class A:
    x = C()  # 自動呼叫：x.__set_name__(A, 'x')
@end example

If the class variable is assigned after the class is created,
@ref{e43,,__set_name__()} will not be called automatically.
If needed, @ref{e43,,__set_name__()} can be called directly:

@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{e3f,,Creating the class object}。


在 3.6 版被加入.

@end deffn

@menu
* Metaclasses:: 
* Resolving MRO entries:: 
* Determining the appropriate metaclass:: 
* Preparing the class namespace:: 
* Executing the class body:: 
* Creating the class object:: 
* Uses for metaclasses:: 

@end menu

@node Metaclasses,Resolving MRO entries,,Customizing class creation
@anchor{reference/datamodel id14}@anchor{226f}@anchor{reference/datamodel metaclasses}@anchor{2270}
@subsubsection Metaclasses


@geindex metaclass（元類別）
@geindex built-in function（內建函式）;type（型別）
@geindex = （等號）;class definition（類別定義）

By default, classes are constructed using @ref{f3f,,type()}. The class body is
executed in a new namespace and the class name is bound locally to the
result of @code{type(name, bases, namespace)}.

The class creation process can be customized by passing the @code{metaclass}
keyword argument in the class definition line, or by inheriting from an
existing class that included such an argument. In the following example,
both @code{MyClass} and @code{MySubclass} are instances of @code{Meta}:

@example
class Meta(type):
    pass

class MyClass(metaclass=Meta):
    pass

class MySubclass(MyClass):
    pass
@end example

Any other keyword arguments that are specified in the class definition are
passed through to all metaclass operations described below.

When a class definition is executed, the following steps occur:


@itemize *

@item 
MRO entries are resolved;

@item 
the appropriate metaclass is determined;

@item 
the class namespace is prepared;

@item 
the class body is executed;

@item 
the class object is created.
@end itemize

@node Resolving MRO entries,Determining the appropriate metaclass,Metaclasses,Customizing class creation
@anchor{reference/datamodel resolving-mro-entries}@anchor{2271}
@subsubsection Resolving MRO entries


@geindex __mro_entries__() (object 的方法)
@anchor{reference/datamodel object __mro_entries__}@anchor{cda}
@deffn {方法} object.__mro_entries__ (self, bases)

If a base that appears in a class definition is not an instance of
@ref{f3f,,type}, then an @code{__mro_entries__()} method is searched on the base.
If an @code{__mro_entries__()} method is found, the base is substituted with the
result of a call to @code{__mro_entries__()} when creating the class.
The method is called with the original bases tuple
passed to the `bases' parameter, and must return a tuple
of classes that will be used instead of the base. The returned tuple may be
empty: in these cases, the original base is ignored.
@end deffn


@subsubheading 也參考



@table @asis

@item @ref{d90,,types.resolve_bases()}

Dynamically resolve bases that are not instances of @ref{f3f,,type}.

@item @ref{6ee,,types.get_original_bases()}

Retrieve a class's "original bases" prior to modifications by
@ref{cda,,__mro_entries__()}.

@geindex Python Enhancement Proposals; PEP 560

@item PEP 560@footnote{https://peps.python.org/pep-0560/}

Core support for typing module and generic types.
@end table


@node Determining the appropriate metaclass,Preparing the class namespace,Resolving MRO entries,Customizing class creation
@anchor{reference/datamodel determining-the-appropriate-metaclass}@anchor{2272}
@subsubsection Determining the appropriate metaclass


@geindex metaclass hint（元類別提示）

The appropriate metaclass for a class definition is determined as follows:


@itemize *

@item 
if no bases and no explicit metaclass are given, then @ref{f3f,,type()} is used;

@item 
if an explicit metaclass is given and it is `not' an instance of
@ref{f3f,,type()}, then it is used directly as the metaclass;

@item 
if an instance of @ref{f3f,,type()} is given as the explicit metaclass, or
bases are defined, then the most derived metaclass is used.
@end itemize

The most derived metaclass is selected from the explicitly specified
metaclass (if any) and the metaclasses (i.e. @code{type(cls)}) of all specified
base classes. The most derived metaclass is one which is a subtype of `all'
of these candidate metaclasses. If none of the candidate metaclasses meets
that criterion, then the class definition will fail with @code{TypeError}.

@node Preparing the class namespace,Executing the class body,Determining the appropriate metaclass,Customizing class creation
@anchor{reference/datamodel prepare}@anchor{e53}@anchor{reference/datamodel preparing-the-class-namespace}@anchor{2273}
@subsubsection Preparing the class namespace


@geindex __prepare__ （元類別方法）

Once the appropriate metaclass has been identified, then the class namespace
is prepared. If the metaclass has a @code{__prepare__} attribute, it is called
as @code{namespace = metaclass.__prepare__(name, bases, **kwds)} (where the
additional keyword arguments, if any, come from the class definition). The
@code{__prepare__} method should be implemented as a
@ref{489,,classmethod}. The
namespace returned by @code{__prepare__} is passed in to @code{__new__}, but when
the final class object is created the namespace is copied into a new @code{dict}.

If the metaclass has no @code{__prepare__} attribute, then the class namespace
is initialised as an empty ordered mapping.


@subsubheading 也參考



@table @asis

@geindex Python Enhancement Proposals; PEP 3115

@item PEP 3115@footnote{https://peps.python.org/pep-3115/} - Metaclasses in Python 3000

Introduced the @code{__prepare__} namespace hook
@end table


@node Executing the class body,Creating the class object,Preparing the class namespace,Customizing class creation
@anchor{reference/datamodel executing-the-class-body}@anchor{2274}
@subsubsection Executing the class body


@geindex class（類別）;body

The class body is executed (approximately) as
@code{exec(body, globals(), namespace)}. The key difference from a normal
call to @ref{49d,,exec()} is that lexical scoping allows the class body (including
any methods) to reference names from the current and outer scopes when the
class definition occurs inside a function.

However, even when the class definition occurs inside the function, methods
defined inside the class still cannot see names defined at the class scope.
Class variables must be accessed through the first parameter of instance or
class methods, or through the implicit lexically scoped @code{__class__} reference
described in the next section.

@node Creating the class object,Uses for metaclasses,Executing the class body,Customizing class creation
@anchor{reference/datamodel class-object-creation}@anchor{e3f}@anchor{reference/datamodel creating-the-class-object}@anchor{2275}
@subsubsection Creating the class object


@geindex __class__ （方法 cell）
@geindex __classcell__ （類別命名空間項目）

Once the class namespace has been populated by executing the class body,
the class object is created by calling
@code{metaclass(name, bases, namespace, **kwds)} (the additional keywords
passed here are the same as those passed to @code{__prepare__}).

This class object is the one that will be referenced by the zero-argument
form of @ref{1a6,,super()}. @code{__class__} is an implicit closure reference
created by the compiler if any methods in a class body refer to either
@code{__class__} or @code{super}. This allows the zero argument form of
@ref{1a6,,super()} to correctly identify the class being defined based on
lexical scoping, while the class or instance that was used to make the
current call is identified based on the first argument passed to the method.

`CPython 實作細節：' In CPython 3.6 and later, the @code{__class__} cell is passed to the metaclass
as a @code{__classcell__} entry in the class namespace. If present, this must
be propagated up to the @code{type.__new__} call in order for the class to be
initialised correctly.
Failing to do so will result in a @ref{244,,RuntimeError} in Python 3.8.

When using the default metaclass @ref{f3f,,type}, or any metaclass that ultimately
calls @code{type.__new__}, the following additional customization steps are
invoked after creating the class object:


@enumerate 

@item 
The @code{type.__new__} method collects all of the attributes in the class
namespace that define a @ref{e43,,__set_name__()} method;

@item 
Those @code{__set_name__} methods are called with the class
being defined and the assigned name of that particular attribute;

@item 
The @ref{83c,,__init_subclass__()} hook is called on the
immediate parent of the new class in its method resolution order.
@end enumerate

After the class object is created, it is passed to the class decorators
included in the class definition (if any) and the resulting object is bound
in the local namespace as the defined class.

When a new class is created by @code{type.__new__}, the object provided as the
namespace parameter is copied to a new ordered mapping and the original
object is discarded. The new copy is wrapped in a read-only proxy, which
becomes the @ref{e52,,__dict__} attribute of the class object.


@subsubheading 也參考



@table @asis

@geindex Python Enhancement Proposals; PEP 3135

@item PEP 3135@footnote{https://peps.python.org/pep-3135/} - New super

Describes the implicit @code{__class__} closure reference
@end table


@node Uses for metaclasses,,Creating the class object,Customizing class creation
@anchor{reference/datamodel uses-for-metaclasses}@anchor{2276}
@subsubsection Uses for metaclasses


The potential uses for metaclasses are boundless. Some ideas that have been
explored include enum, logging, interface checking, automatic delegation,
automatic property creation, proxies, frameworks, and automatic resource
locking/synchronization.

@node Customizing instance and subclass checks,Emulating generic types,Customizing class creation,Special method names
@anchor{reference/datamodel customizing-instance-and-subclass-checks}@anchor{2277}
@subsubsection Customizing instance and subclass checks


The following methods are used to override the default behavior of the
@ref{2ad,,isinstance()} and @ref{9bd,,issubclass()} built-in functions.

In particular, the metaclass @ref{1116,,abc.ABCMeta} implements these methods in
order to allow the addition of Abstract Base Classes (ABCs) as "virtual base
classes" to any class or type (including built-in types), including other
ABCs.

@geindex __instancecheck__() (type 的方法)
@anchor{reference/datamodel type __instancecheck__}@anchor{2278}
@deffn {方法} type.__instancecheck__ (self, instance)

Return true if `instance' should be considered a (direct or indirect)
instance of `class'. If defined, called to implement @code{isinstance(instance,
class)}.
@end deffn

@geindex __subclasscheck__() (type 的方法)
@anchor{reference/datamodel type __subclasscheck__}@anchor{2279}
@deffn {方法} type.__subclasscheck__ (self, subclass)

Return true if `subclass' should be considered a (direct or indirect)
subclass of `class'.  If defined, called to implement @code{issubclass(subclass,
class)}.
@end deffn

Note that these methods are looked up on the type (metaclass) of a class.  They
cannot be defined as class methods in the actual class.  This is consistent with
the lookup of special methods that are called on instances, only in this
case the instance is itself a class.


@subsubheading 也參考



@table @asis

@geindex Python Enhancement Proposals; PEP 3119

@item PEP 3119@footnote{https://peps.python.org/pep-3119/} - Introducing Abstract Base Classes

Includes the specification for customizing @ref{2ad,,isinstance()} and
@ref{9bd,,issubclass()} behavior through @ref{2278,,__instancecheck__()} and
@ref{2279,,__subclasscheck__()}, with motivation for this functionality
in the context of adding Abstract Base Classes (see the @ref{4,,abc}
module) to the language.
@end table


@node Emulating generic types,Emulating callable objects,Customizing instance and subclass checks,Special method names
@anchor{reference/datamodel emulating-generic-types}@anchor{227a}
@subsubsection Emulating generic types


When using @ref{15c,,type annotations}, it is often useful to
`parameterize' a @ref{1a1,,generic type} using Python's square-brackets notation.
For example, the annotation @code{list[int]} might be used to signify a
@ref{24d,,list} in which all the elements are of type @ref{19b,,int}.


@subsubheading 也參考



@table @asis

@geindex Python Enhancement Proposals; PEP 484

@item PEP 484@footnote{https://peps.python.org/pep-0484/} - 型別提示

引入 Python 的型別註釋框架

@item @ref{8b8,,泛型別名型別}

Documentation for objects representing parameterized generic classes

@item @ref{227b,,泛型}, @ref{6ef,,user-defined generics} and @ref{174e,,typing.Generic}

Documentation on how to implement generic classes that can be
parameterized at runtime and understood by static type-checkers.
@end table


A class can `generally' only be parameterized if it defines the special
class method @code{__class_getitem__()}.

@geindex __class_getitem__() (object 的類別方法)
@anchor{reference/datamodel object __class_getitem__}@anchor{93b}
@deffn {方法} classmethod object.__class_getitem__ (cls, key)

Return an object representing the specialization of a generic class
by type arguments found in `key'.

When defined on a class, @code{__class_getitem__()} is automatically a class
method. As such, there is no need for it to be decorated with
@ref{489,,@@classmethod} when it is defined.
@end deffn

@menu
* The purpose of __class_getitem__:: 
* __class_getitem__ versus __getitem__:: 

@end menu

@node The purpose of __class_getitem__,__class_getitem__ versus __getitem__,,Emulating generic types
@anchor{reference/datamodel the-purpose-of-class-getitem}@anchor{227c}
@subsubsection The purpose of `__class_getitem__'


The purpose of @ref{93b,,__class_getitem__()} is to allow runtime
parameterization of standard-library generic classes in order to more easily
apply @ref{227d,,type hints} to these classes.

To implement custom generic classes that can be parameterized at runtime and
understood by static type-checkers, users should either inherit from a standard
library class that already implements @ref{93b,,__class_getitem__()}, or
inherit from @ref{174e,,typing.Generic}, which has its own implementation of
@code{__class_getitem__()}.

Custom implementations of @ref{93b,,__class_getitem__()} on classes defined
outside of the standard library may not be understood by third-party
type-checkers such as mypy. Using @code{__class_getitem__()} on any class for
purposes other than type hinting is discouraged.

@node __class_getitem__ versus __getitem__,,The purpose of __class_getitem__,Emulating generic types
@anchor{reference/datamodel class-getitem-versus-getitem}@anchor{227e}@anchor{reference/datamodel classgetitem-versus-getitem}@anchor{227f}
@subsubsection `__class_getitem__' versus `__getitem__'


Usually, the @ref{2280,,subscription} of an object using square
brackets will call the @ref{582,,__getitem__()} instance method defined on
the object's class. However, if the object being subscribed is itself a class,
the class method @ref{93b,,__class_getitem__()} may be called instead.
@code{__class_getitem__()} should return a @ref{8b8,,GenericAlias}
object if it is properly defined.

Presented with the @ref{2281,,expression} @code{obj[x]}, the Python interpreter
follows something like the following process to decide whether
@ref{582,,__getitem__()} or @ref{93b,,__class_getitem__()} should be
called:

@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

In Python, all classes are themselves instances of other classes. The class of
a class is known as that class's @ref{2282,,metaclass}, and most classes have the
@ref{f3f,,type} class as their metaclass. @ref{f3f,,type} does not define
@ref{582,,__getitem__()}, meaning that expressions such as @code{list[int]},
@code{dict[str, float]} and @code{tuple[str, bytes]} all result in
@ref{93b,,__class_getitem__()} being called:

@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

However, if a class has a custom metaclass that defines
@ref{582,,__getitem__()}, subscribing the class may result in different
behaviour. An example of this can be found in the @ref{5a,,enum} module:

@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/} - Core Support for typing module and generic types

Introducing @ref{93b,,__class_getitem__()}, and outlining when a
@ref{2280,,subscription} results in @code{__class_getitem__()}
being called instead of @ref{582,,__getitem__()}
@end table


@node Emulating callable objects,Emulating container types,Emulating generic types,Special method names
@anchor{reference/datamodel emulating-callable-objects}@anchor{2283}@anchor{reference/datamodel id15}@anchor{2284}
@subsubsection Emulating callable objects


@geindex __call__() (object 的方法)
@anchor{reference/datamodel object __call__}@anchor{773}
@deffn {方法} object.__call__ (self[, args...])

@geindex call（呼叫）;instance（實例）

Called when the instance is "called" as a function; if this method is defined,
@code{x(arg1, arg2, ...)} roughly translates to @code{type(x).__call__(x, arg1, ...)}.
The @ref{c75,,object} class itself does not provide this method.
@end deffn

@node Emulating container types,Emulating numeric types,Emulating callable objects,Special method names
@anchor{reference/datamodel emulating-container-types}@anchor{2285}@anchor{reference/datamodel sequence-types}@anchor{2286}
@subsubsection Emulating container types


The following methods can be defined to implement container objects. None of them
are provided by the @ref{c75,,object} class itself. Containers usually are
@ref{70f,,sequences} (such as @ref{24d,,lists} or
@ref{60c,,tuples}) or @ref{13bc,,mappings} (like
@ref{2287,,dictionaries}),
but can represent other containers as well.  The first set of methods is used
either to emulate a sequence or to emulate a mapping; the difference is that for
a sequence, the allowable keys should be the integers `k' for which @code{0 <= k <
N} where `N' is the length of the sequence, or @ref{68d,,slice} objects, which define a
range of items.  It is also recommended that mappings provide the methods
@code{keys()}, @code{values()}, @code{items()}, @code{get()}, @code{clear()},
@code{setdefault()}, @code{pop()}, @code{popitem()}, @code{copy()}, and
@code{update()} behaving similar to those for Python's standard @ref{183,,dictionary}
objects.  The @ref{1f,,collections.abc} module provides a
@ref{12ad,,MutableMapping}
@ref{13b7,,abstract base class} to help create those methods from a base set of
@ref{582,,__getitem__()}, @ref{14cc,,__setitem__()},
@ref{14cd,,__delitem__()}, and @code{keys()}.

Mutable sequences should provide methods
@ref{2288,,append()}, @ref{2289,,clear()}, @ref{228a,,count()},
@ref{228b,,extend()}, @ref{18da,,index()}, @ref{228c,,insert()},
@ref{228d,,pop()}, @ref{18db,,remove()}, and @ref{228e,,reverse()},
like Python standard @ref{24d,,list} objects.
Finally, sequence types should implement addition (meaning concatenation) and
multiplication (meaning repetition) by defining the methods
@ref{228f,,__add__()}, @ref{2290,,__radd__()}, @ref{2291,,__iadd__()},
@ref{2292,,__mul__()}, @ref{2293,,__rmul__()} and @ref{2294,,__imul__()}
described below; they should not define other numerical
operators.

It is recommended that both mappings and sequences implement the
@ref{15b1,,__contains__()} method to allow efficient use of the @code{in}
operator; for
mappings, @code{in} should search the mapping's keys; for sequences, it should
search through the values.  It is further recommended that both mappings and
sequences implement the @ref{e64,,__iter__()} method to allow efficient iteration
through the container; for mappings, @code{__iter__()} should iterate
through the object's keys; for sequences, it should iterate through the values.

@geindex __len__() (object 的方法)
@anchor{reference/datamodel object __len__}@anchor{2260}
@deffn {方法} object.__len__ (self)

@geindex built-in function（內建函式）;len
@geindex __bool__() （物件方法）

Called to implement the built-in function @ref{839,,len()}.  Should return the length
of the object, an integer @code{>=} 0.  Also, an object that doesn't define a
@ref{14d6,,__bool__()} method and whose @code{__len__()} method returns zero is
considered to be false in a Boolean context.

`CPython 實作細節：' In CPython, the length is required to be at most @ref{13c6,,sys.maxsize}.
If the length is larger than @code{sys.maxsize} some features (such as
@ref{839,,len()}) may raise @ref{a78,,OverflowError}.  To prevent raising
@code{OverflowError} by truth value testing, an object must define a
@ref{14d6,,__bool__()} method.
@end deffn

@geindex __length_hint__() (object 的方法)
@anchor{reference/datamodel object __length_hint__}@anchor{1109}
@deffn {方法} object.__length_hint__ (self)

Called to implement @ref{1168,,operator.length_hint()}. Should return an estimated
length for the object (which may be greater or less than the actual length).
The length must be an integer @code{>=} 0. The return value may also be
@ref{1a2,,NotImplemented}, which is treated the same as if the
@code{__length_hint__} method didn't exist at all. This method is purely an
optimization and is never required for correctness.


在 3.4 版被加入.

@end deffn

@geindex object（物件）;slice（切片）

@cartouche
@quotation 備註 
Slicing is done exclusively with the following three methods.  A call like

@example
a[1:2] = b
@end example

is translated to

@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

@geindex __getitem__() (object 的方法)
@anchor{reference/datamodel object __getitem__}@anchor{582}
@deffn {方法} object.__getitem__ (self, key)

Called to implement evaluation of @code{self[key]}. For @ref{70f,,sequence} types,
the accepted keys should be integers. Optionally, they may support
@ref{68d,,slice} objects as well.  Negative index support is also optional.
If `key' is
of an inappropriate type, @ref{198,,TypeError} may be raised; if `key' is a value
outside the set of indexes for the sequence (after any special
interpretation of negative values), @ref{1729,,IndexError} should be raised. For
@ref{13bc,,mapping} types, if `key' is missing (not in the container),
@ref{5df,,KeyError} should be raised.

@cartouche
@quotation 備註 
@ref{348,,for} loops expect that an @ref{1729,,IndexError} will be raised for
illegal indexes to allow proper detection of the end of the sequence.
@end quotation
@end cartouche

@cartouche
@quotation 備註 
When @ref{2280,,subscripting} a `class', the special
class method @ref{93b,,__class_getitem__()} may be called instead of
@code{__getitem__()}. See @ref{227f,,__class_getitem__ versus __getitem__} for more
details.
@end quotation
@end cartouche
@end deffn

@geindex __setitem__() (object 的方法)
@anchor{reference/datamodel object __setitem__}@anchor{14cc}
@deffn {方法} object.__setitem__ (self, key, value)

Called to implement assignment to @code{self[key]}.  Same note as for
@ref{582,,__getitem__()}.  This should only be implemented for mappings if the
objects support changes to the values for keys, or if new keys can be added, or
for sequences if elements can be replaced.  The same exceptions should be raised
for improper `key' values as for the @ref{582,,__getitem__()} method.
@end deffn

@geindex __delitem__() (object 的方法)
@anchor{reference/datamodel object __delitem__}@anchor{14cd}
@deffn {方法} object.__delitem__ (self, key)

Called to implement deletion of @code{self[key]}.  Same note as for
@ref{582,,__getitem__()}.  This should only be implemented for mappings if the
objects support removal of keys, or for sequences if elements can be removed
from the sequence.  The same exceptions should be raised for improper `key'
values as for the @ref{582,,__getitem__()} method.
@end deffn

@geindex __missing__() (object 的方法)
@anchor{reference/datamodel object __missing__}@anchor{13be}
@deffn {方法} object.__missing__ (self, key)

Called by @ref{183,,dict}.@ref{582,,__getitem__()} to implement @code{self[key]} for dict subclasses
when key is not in the dictionary.
@end deffn

@geindex __iter__() (object 的方法)
@anchor{reference/datamodel object __iter__}@anchor{e64}
@deffn {方法} object.__iter__ (self)

This method is called when an @ref{4c3,,iterator} is required for a container.
This method should return a new iterator object that can iterate over all the
objects in the container.  For mappings, it should iterate over the keys of
the container.
@end deffn

@geindex __reversed__() (object 的方法)
@anchor{reference/datamodel object __reversed__}@anchor{e81}
@deffn {方法} object.__reversed__ (self)

Called (if present) by the @ref{a5e,,reversed()} built-in to implement
reverse iteration.  It should return a new iterator object that iterates
over all the objects in the container in reverse order.

If the @ref{e81,,__reversed__()} method is not provided, the @ref{a5e,,reversed()}
built-in will fall back to using the sequence protocol (@ref{2260,,__len__()} and
@ref{582,,__getitem__()}).  Objects that support the sequence protocol should
only provide @ref{e81,,__reversed__()} if they can provide an implementation
that is more efficient than the one provided by @ref{a5e,,reversed()}.
@end deffn

The membership test operators (@ref{349,,in} and @ref{83a,,not in}) are normally
implemented as an iteration through a container. However, container objects can
supply the following special method with a more efficient implementation, which
also does not require the object be iterable.

@geindex __contains__() (object 的方法)
@anchor{reference/datamodel object __contains__}@anchor{15b1}
@deffn {方法} object.__contains__ (self, item)

Called to implement membership test operators.  Should return true if `item'
is in `self', false otherwise.  For mapping objects, this should consider the
keys of the mapping rather than the values or the key-item pairs.

For objects that don't define @ref{15b1,,__contains__()}, the membership test first
tries iteration via @ref{e64,,__iter__()}, then the old sequence iteration
protocol via @ref{582,,__getitem__()}, see @ref{2295,,this section in the language reference}.
@end deffn

@node Emulating numeric types,With 陳述式的情境管理器,Emulating container types,Special method names
@anchor{reference/datamodel emulating-numeric-types}@anchor{2296}@anchor{reference/datamodel numeric-types}@anchor{2297}
@subsubsection Emulating numeric types


The following methods can be defined to emulate numeric objects. Methods
corresponding to operations that are not supported by the particular kind of
number implemented (e.g., bitwise operations for non-integral numbers) should be
left undefined.

@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{228f}
@deffn {方法} object.__add__ (self, other)
@anchor{reference/datamodel object __sub__}@anchor{2298}
@deffnx {方法} object.__sub__ (self, other)
@anchor{reference/datamodel object __mul__}@anchor{2292}
@deffnx {方法} object.__mul__ (self, other)
@anchor{reference/datamodel object __matmul__}@anchor{f74}
@deffnx {方法} object.__matmul__ (self, other)
@anchor{reference/datamodel object __truediv__}@anchor{108b}
@deffnx {方法} object.__truediv__ (self, other)
@anchor{reference/datamodel object __floordiv__}@anchor{16e8}
@deffnx {方法} object.__floordiv__ (self, other)
@anchor{reference/datamodel object __mod__}@anchor{2299}
@deffnx {方法} object.__mod__ (self, other)
@anchor{reference/datamodel object __divmod__}@anchor{108c}
@deffnx {方法} object.__divmod__ (self, other)
@anchor{reference/datamodel object __pow__}@anchor{9cd}
@deffnx {方法} object.__pow__ (self, other[, modulo])
@anchor{reference/datamodel object __lshift__}@anchor{229a}
@deffnx {方法} object.__lshift__ (self, other)
@anchor{reference/datamodel object __rshift__}@anchor{229b}
@deffnx {方法} object.__rshift__ (self, other)
@anchor{reference/datamodel object __and__}@anchor{229c}
@deffnx {方法} object.__and__ (self, other)
@anchor{reference/datamodel object __xor__}@anchor{229d}
@deffnx {方法} object.__xor__ (self, other)
@anchor{reference/datamodel object __or__}@anchor{229e}
@deffnx {方法} object.__or__ (self, other)

@geindex built-in function（內建函式）;divmod
@geindex built-in function（內建函式）;pow
@geindex built-in function（內建函式）;pow

These methods are called to implement the binary arithmetic operations
(@code{+}, @code{-}, @code{*}, @code{@@}, @code{/}, @code{//}, @code{%}, @ref{b90,,divmod()},
@ref{1a4,,pow()}, @code{**}, @code{<<}, @code{>>}, @code{&}, @code{^}, @code{|}).  For instance, to
evaluate the expression @code{x + y}, where `x' is an instance of a class that
has an @ref{228f,,__add__()} method, @code{type(x).__add__(x, y)} is called.  The
@ref{108c,,__divmod__()} method should be the equivalent to using
@ref{16e8,,__floordiv__()} and @ref{2299,,__mod__()}; it should not be related to
@ref{108b,,__truediv__()}.  Note that @ref{9cd,,__pow__()} should be defined to accept
an optional third argument if the three-argument version of the built-in @ref{1a4,,pow()}
function is to be supported.

If one of those methods does not support the operation with the supplied
arguments, it should return @ref{1a2,,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{2290}
@deffn {方法} object.__radd__ (self, other)
@anchor{reference/datamodel object __rsub__}@anchor{229f}
@deffnx {方法} object.__rsub__ (self, other)
@anchor{reference/datamodel object __rmul__}@anchor{2293}
@deffnx {方法} object.__rmul__ (self, other)
@anchor{reference/datamodel object __rmatmul__}@anchor{f75}
@deffnx {方法} object.__rmatmul__ (self, other)
@anchor{reference/datamodel object __rtruediv__}@anchor{22a0}
@deffnx {方法} object.__rtruediv__ (self, other)
@anchor{reference/datamodel object __rfloordiv__}@anchor{22a1}
@deffnx {方法} object.__rfloordiv__ (self, other)
@anchor{reference/datamodel object __rmod__}@anchor{fd0}
@deffnx {方法} object.__rmod__ (self, other)
@anchor{reference/datamodel object __rdivmod__}@anchor{22a2}
@deffnx {方法} object.__rdivmod__ (self, other)
@anchor{reference/datamodel object __rpow__}@anchor{1a5}
@deffnx {方法} object.__rpow__ (self, other[, modulo])
@anchor{reference/datamodel object __rlshift__}@anchor{22a3}
@deffnx {方法} object.__rlshift__ (self, other)
@anchor{reference/datamodel object __rrshift__}@anchor{22a4}
@deffnx {方法} object.__rrshift__ (self, other)
@anchor{reference/datamodel object __rand__}@anchor{22a5}
@deffnx {方法} object.__rand__ (self, other)
@anchor{reference/datamodel object __rxor__}@anchor{22a6}
@deffnx {方法} object.__rxor__ (self, other)
@anchor{reference/datamodel object __ror__}@anchor{22a7}
@deffnx {方法} object.__ror__ (self, other)

@geindex built-in function（內建函式）;divmod
@geindex built-in function（內建函式）;pow

These methods are called to implement the binary arithmetic operations
(@code{+}, @code{-}, @code{*}, @code{@@}, @code{/}, @code{//}, @code{%}, @ref{b90,,divmod()},
@ref{1a4,,pow()}, @code{**}, @code{<<}, @code{>>}, @code{&}, @code{^}, @code{|}) with reflected
(swapped) operands.  These functions are only called if the operands
are of different types, when the left operand does not support the corresponding
operation @footnote{
"Does not support" here means that the class has no such method, or
the method returns @ref{1a2,,NotImplemented}.  Do not set the method to
@code{None} if you want to force fallback to the right operand's reflected
method—that will instead have the opposite effect of explicitly
`blocking' such fallback.
}, or the right operand's class is derived from the left operand's
class. @footnote{
For operands of the same type, it is assumed that if the non-reflected method
(such as @ref{228f,,__add__()}) fails then the operation is not supported, which is why the
reflected method is not called.
} For instance, to evaluate the expression @code{x - y}, where `y' is
an instance of a class that has an @ref{229f,,__rsub__()} method, @code{type(y).__rsub__(y, x)}
is called if @code{type(x).__sub__(x, y)} returns @ref{1a2,,NotImplemented} or @code{type(y)}
is a subclass of @code{type(x)}. @footnote{
If the right operand's type is a subclass of the left operand's type, the
reflected method having precedence allows subclasses to override their ancestors'
operations.
}

Note that @ref{1a5,,__rpow__()} should be defined to accept an optional third
argument if the three-argument version of the built-in @ref{1a4,,pow()} function
is to be supported.


在 3.14 版的變更: Three-argument @ref{1a4,,pow()} now try calling @ref{1a5,,__rpow__()} if necessary.
Previously it was only called in two-argument @code{pow()} and the binary
power operator.


@cartouche
@quotation 備註 
If the right operand's type is a subclass of the left operand's type and
that subclass provides a different implementation of the reflected method
for the operation, this method will be called before the left operand's
non-reflected method. This behavior allows subclasses to override their
ancestors' operations.
@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{2291}
@deffn {方法} object.__iadd__ (self, other)
@anchor{reference/datamodel object __isub__}@anchor{22a8}
@deffnx {方法} object.__isub__ (self, other)
@anchor{reference/datamodel object __imul__}@anchor{2294}
@deffnx {方法} object.__imul__ (self, other)
@anchor{reference/datamodel object __imatmul__}@anchor{f76}
@deffnx {方法} object.__imatmul__ (self, other)
@anchor{reference/datamodel object __itruediv__}@anchor{22a9}
@deffnx {方法} object.__itruediv__ (self, other)
@anchor{reference/datamodel object __ifloordiv__}@anchor{22aa}
@deffnx {方法} object.__ifloordiv__ (self, other)
@anchor{reference/datamodel object __imod__}@anchor{22ab}
@deffnx {方法} object.__imod__ (self, other)
@anchor{reference/datamodel object __ipow__}@anchor{9cc}
@deffnx {方法} object.__ipow__ (self, other[, modulo])
@anchor{reference/datamodel object __ilshift__}@anchor{22ac}
@deffnx {方法} object.__ilshift__ (self, other)
@anchor{reference/datamodel object __irshift__}@anchor{22ad}
@deffnx {方法} object.__irshift__ (self, other)
@anchor{reference/datamodel object __iand__}@anchor{22ae}
@deffnx {方法} object.__iand__ (self, other)
@anchor{reference/datamodel object __ixor__}@anchor{22af}
@deffnx {方法} object.__ixor__ (self, other)
@anchor{reference/datamodel object __ior__}@anchor{22b0}
@deffnx {方法} object.__ior__ (self, other)

These methods are called to implement the augmented arithmetic assignments
(@code{+=}, @code{-=}, @code{*=}, @code{@@=}, @code{/=}, @code{//=}, @code{%=}, @code{**=}, @code{<<=},
@code{>>=}, @code{&=}, @code{^=}, @code{|=}).  These methods should attempt to do the
operation in-place (modifying `self') and return the result (which could be,
but does not have to be, `self').  If a specific method is not defined, or if
that method returns @ref{1a2,,NotImplemented}, the
augmented assignment falls back to the normal methods.  For instance, if `x'
is an instance of a class with an @ref{2291,,__iadd__()} method, @code{x += y} is
equivalent to @code{x = x.__iadd__(y)} . If @ref{2291,,__iadd__()} does not exist, or if @code{x.__iadd__(y)}
returns @code{NotImplemented}, @code{x.__add__(y)} and
@code{y.__radd__(x)} are considered, as with the evaluation of @code{x + y}. In
certain situations, augmented assignment can result in unexpected errors (see
@ref{22b1,,為什麼 a_tuple[i] += ['item'] 做加法時會引發例外？}), but this behavior is in fact
part of the data model.
@end deffn

@geindex __neg__() (object 的方法)
@geindex __pos__() (object 的方法)
@geindex __abs__() (object 的方法)
@geindex __invert__() (object 的方法)
@anchor{reference/datamodel object __neg__}@anchor{22b2}
@deffn {方法} object.__neg__ (self)
@anchor{reference/datamodel object __pos__}@anchor{22b3}
@deffnx {方法} object.__pos__ (self)
@anchor{reference/datamodel object __abs__}@anchor{22b4}
@deffnx {方法} object.__abs__ (self)
@anchor{reference/datamodel object __invert__}@anchor{22b5}
@deffnx {方法} object.__invert__ (self)

@geindex built-in function（內建函式）;abs

Called to implement the unary arithmetic operations (@code{-}, @code{+}, @ref{1f54,,abs()}
and @code{~}).
@end deffn

@geindex __complex__() (object 的方法)
@geindex __int__() (object 的方法)
@geindex __float__() (object 的方法)
@anchor{reference/datamodel object __complex__}@anchor{7f8}
@deffn {方法} object.__complex__ (self)
@anchor{reference/datamodel object __int__}@anchor{19d}
@deffnx {方法} object.__int__ (self)
@anchor{reference/datamodel object __float__}@anchor{bb8}
@deffnx {方法} object.__float__ (self)

@geindex built-in function（內建函式）;complex（複數）
@geindex built-in function（內建函式）;int
@geindex built-in function（內建函式）;float

Called to implement the built-in functions @ref{197,,complex()},
@ref{19b,,int()} and @ref{196,,float()}.  Should return a value
of the appropriate type.
@end deffn

@geindex __index__() (object 的方法)
@anchor{reference/datamodel object __index__}@anchor{19e}
@deffn {方法} object.__index__ (self)

Called to implement @ref{1bc4,,operator.index()}, and whenever Python needs to
losslessly convert the numeric object to an integer object (such as in
slicing, or in the built-in @ref{14a9,,bin()}, @ref{14d0,,hex()} and @ref{14cf,,oct()}
functions). Presence of this method indicates that the numeric object is
an integer type.  Must return an integer.

If @ref{19d,,__int__()}, @ref{bb8,,__float__()} and @ref{7f8,,__complex__()} are not
defined then corresponding built-in functions @ref{19b,,int()}, @ref{196,,float()}
and @ref{197,,complex()} fall back to @ref{19e,,__index__()}.
@end deffn

@geindex __round__() (object 的方法)
@geindex __trunc__() (object 的方法)
@geindex __floor__() (object 的方法)
@geindex __ceil__() (object 的方法)
@anchor{reference/datamodel object __round__}@anchor{22b6}
@deffn {方法} object.__round__ (self[, ndigits])
@anchor{reference/datamodel object __trunc__}@anchor{19c}
@deffnx {方法} object.__trunc__ (self)
@anchor{reference/datamodel object __floor__}@anchor{22b7}
@deffnx {方法} object.__floor__ (self)
@anchor{reference/datamodel object __ceil__}@anchor{22b8}
@deffnx {方法} object.__ceil__ (self)

@geindex built-in function（內建函式）;round

Called to implement the built-in function @ref{14db,,round()} and @ref{92,,math}
functions @ref{15b7,,trunc()}, @ref{15b5,,floor()} and @ref{15b6,,ceil()}.
Unless `ndigits' is passed to @code{__round__()} all these methods should
return the value of the object truncated to an @ref{22b9,,Integral}
(typically an @ref{19b,,int}).


在 3.14 版的變更: @ref{19b,,int()} no longer delegates to the @ref{19c,,__trunc__()} method.

@end deffn

@node With 陳述式的情境管理器,Customizing positional arguments in class pattern matching,Emulating numeric types,Special method names
@anchor{reference/datamodel context-managers}@anchor{22ba}@anchor{reference/datamodel with-statement-context-managers}@anchor{22bb}
@subsubsection With 陳述式的情境管理器


A `context manager' is an object that defines the runtime context to be
established when executing a @ref{186,,with} statement. The context manager
handles the entry into, and the exit from, the desired runtime context for the
execution of the block of code.  Context managers are normally invoked using the
@code{with} statement (described in section @ref{186,,with 陳述式}), but can also be
used by directly invoking their methods.

@geindex statement（陳述式）;with
@geindex context manager（情境管理器）

Typical uses of context managers include saving and restoring various kinds of
global state, locking and unlocking resources, closing opened files, etc.

For more information on context managers, see @ref{22bc,,情境管理器型別}.
The @ref{c75,,object} class itself does not provide the context manager methods.

@geindex __enter__() (object 的方法)
@anchor{reference/datamodel object __enter__}@anchor{7dd}
@deffn {方法} object.__enter__ (self)

Enter the runtime context related to this object. The @ref{186,,with} statement
will bind this method's return value to the target(s) specified in the
@code{as} clause of the statement, if any.
@end deffn

@geindex __exit__() (object 的方法)
@anchor{reference/datamodel object __exit__}@anchor{1501}
@deffn {方法} object.__exit__ (self, exc_type, exc_value, traceback)

Exit the runtime context related to this object. The parameters describe the
exception that caused the context to be exited. If the context was exited
without an exception, all three arguments will be @ref{87e,,None}.

If an exception is supplied, and the method wishes to suppress the exception
(i.e., prevent it from being propagated), it should return a true value.
Otherwise, the exception will be processed normally upon exit from this method.

Note that @ref{1501,,__exit__()} methods should not reraise the passed-in exception;
this is the caller's responsibility.
@end deffn


@subsubheading 也參考



@table @asis

@geindex Python Enhancement Proposals; PEP 343

@item PEP 343@footnote{https://peps.python.org/pep-0343/} - "with" 陳述式

The specification, background, and examples for the Python @ref{186,,with}
statement.
@end table


@node Customizing positional arguments in class pattern matching,Emulating buffer types,With 陳述式的情境管理器,Special method names
@anchor{reference/datamodel class-pattern-matching}@anchor{22bd}@anchor{reference/datamodel customizing-positional-arguments-in-class-pattern-matching}@anchor{22be}
@subsubsection Customizing positional arguments in class pattern matching


When using a class name in a pattern, positional arguments in the pattern are not
allowed by default, i.e. @code{case MyClass(x, y)} is typically invalid without special
support in @code{MyClass}. To be able to use that kind of pattern, the class needs to
define a `__match_args__' attribute.

@geindex object.__match_args__ (內建變數)
@anchor{reference/datamodel object __match_args__}@anchor{1b75}
@deffn {資料} object.__match_args__

This class variable can be assigned a tuple of strings. When this class is
used in a class pattern with positional arguments, each positional argument will
be converted into a keyword argument, using the corresponding value in
`__match_args__' as the keyword. The absence of this attribute is equivalent to
setting it to @code{()}.
@end deffn

For example, if @code{MyClass.__match_args__} is @code{("left", "center", "right")} that means
that @code{case MyClass(x, y)} is equivalent to @code{case MyClass(left=x, center=y)}. Note
that the number of arguments in the pattern must be smaller than or equal to the number
of elements in `__match_args__'; if it is larger, the pattern match attempt will raise
a @ref{198,,TypeError}.


在 3.10 版被加入.



@subsubheading 也參考



@table @asis

@geindex Python Enhancement Proposals; PEP 634

@item PEP 634@footnote{https://peps.python.org/pep-0634/} - Structural Pattern Matching

The specification for the Python @code{match} statement.
@end table


@node Emulating buffer types,Annotations,Customizing positional arguments in class pattern matching,Special method names
@anchor{reference/datamodel emulating-buffer-types}@anchor{22bf}@anchor{reference/datamodel python-buffer-protocol}@anchor{22c0}
@subsubsection Emulating buffer types


The @ref{260,,buffer protocol} provides a way for Python
objects to expose efficient access to a low-level memory array. This protocol
is implemented by builtin types such as @ref{192,,bytes} and @ref{165,,memoryview},
and third-party libraries may define additional buffer types.

While buffer types are usually implemented in C, it is also possible to
implement the protocol in Python.

@geindex __buffer__() (object 的方法)
@anchor{reference/datamodel object __buffer__}@anchor{685}
@deffn {方法} object.__buffer__ (self, flags)

Called when a buffer is requested from `self' (for example, by the
@ref{165,,memoryview} constructor). The `flags' argument is an integer
representing the kind of buffer requested, affecting for example whether
the returned buffer is read-only or writable. @ref{686,,inspect.BufferFlags}
provides a convenient way to interpret the flags. The method must return
a @ref{165,,memoryview} object.
@end deffn

@geindex __release_buffer__() (object 的方法)
@anchor{reference/datamodel object __release_buffer__}@anchor{19b6}
@deffn {方法} object.__release_buffer__ (self, buffer)

Called when a buffer is no longer needed. The `buffer' argument is a
@ref{165,,memoryview} object that was previously returned by
@ref{685,,__buffer__()}. The method must release any resources associated
with the buffer. This method should return @code{None}.
Buffer objects that do not need to perform any cleanup are not required
to implement this method.
@end deffn


在 3.12 版被加入.



@subsubheading 也參考



@table @asis

@geindex Python Enhancement Proposals; PEP 688

@item PEP 688@footnote{https://peps.python.org/pep-0688/} - Making the buffer protocol accessible in Python

Introduces the Python @code{__buffer__} and @code{__release_buffer__} methods.

@item @ref{342,,collections.abc.Buffer}

ABC for buffer types.
@end table


@node Annotations,Special method lookup,Emulating buffer types,Special method names
@anchor{reference/datamodel annotations}@anchor{22c1}
@subsubsection Annotations


Functions, classes, and modules may contain @ref{15c,,annotations},
which are a way to associate information (usually @ref{227d,,type hints})
with a symbol.

@geindex __annotations__ (object 的屬性)
@anchor{reference/datamodel object __annotations__}@anchor{456}
@deffn {屬性} object.__annotations__

This attribute contains the annotations for an object. It is
@ref{67e,,lazily evaluated}, so accessing the attribute may
execute arbitrary code and raise exceptions. If evaluation is successful, the
attribute is set to a dictionary mapping from variable names to annotations.


在 3.14 版的變更: Annotations are now lazily evaluated.

@end deffn

@geindex __annotate__() (object 的方法)
@anchor{reference/datamodel object __annotate__}@anchor{18df}
@deffn {方法} object.__annotate__ (format)

An @ref{15d,,annotate function}.
Returns a new dictionary object mapping attribute/parameter names to their annotation values.

Takes a format parameter specifying the format in which annotations values should be provided.
It must be a member of the @ref{230,,annotationlib.Format} enum, or an integer with
a value corresponding to a member of the enum.

If an annotate function doesn't support the requested format, it must raise
@ref{369,,NotImplementedError}. Annotate functions must always support
@ref{15e,,VALUE} format; they must not raise
@ref{369,,NotImplementedError()} when called with this format.

When called with  @ref{15e,,VALUE} format, an annotate function may raise
@ref{450,,NameError}; it must not raise @code{NameError} when called requesting any other format.

If an object does not have any annotations, @ref{18df,,__annotate__} should preferably be set
to @code{None} (it can’t be deleted), rather than set to a function that returns an empty dict.


在 3.14 版被加入.

@end deffn


@subsubheading 也參考



@table @asis

@geindex Python Enhancement Proposals; PEP 649

@item PEP 649@footnote{https://peps.python.org/pep-0649/} --- Deferred evaluation of annotation using descriptors

Introduces lazy evaluation of annotations and the @code{__annotate__} function.
@end table


@node Special method lookup,,Annotations,Special method names
@anchor{reference/datamodel special-lookup}@anchor{2263}@anchor{reference/datamodel special-method-lookup}@anchor{22c2}
@subsubsection Special method lookup


For custom classes, implicit invocations of special methods are only guaranteed
to work correctly if defined on an object's type, not in the object's instance
dictionary.  That behaviour is the reason why the following code raises an
exception:

@example
>>> class C:
...     pass
...
>>> c = C()
>>> c.__len__ = lambda: 5
>>> len(c)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: object of type 'C' has no len()
@end example

The rationale behind this behaviour lies with a number of special methods such
as @ref{cea,,__hash__()} and @ref{828,,__repr__()} that are implemented
by all objects,
including type objects. If the implicit lookup of these methods used the
conventional lookup process, they would fail when invoked on the type object
itself:

@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

Incorrectly attempting to invoke an unbound method of a class in this way is
sometimes referred to as 'metaclass confusion', and is avoided by bypassing
the instance when looking up special methods:

@example
>>> type(1).__hash__(1) == hash(1)
True
>>> type(int).__hash__(int) == hash(int)
True
@end example

In addition to bypassing any instance attributes in the interest of
correctness, implicit special method lookup generally also bypasses the
@ref{dc6,,__getattribute__()} method even of the object's metaclass:

@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

Bypassing the @ref{dc6,,__getattribute__()} machinery in this fashion
provides significant scope for speed optimisations within the
interpreter, at the cost of some flexibility in the handling of
special methods (the special method `must' be set on the class
object itself in order to be consistently invoked by the interpreter).

@geindex coroutine（協程）

@node 協程,,Special method names,資料模型
@anchor{reference/datamodel coroutines}@anchor{22c3}
@subsection 協程


@menu
* Awaitable Objects:: 
* 協程物件:: 
* Asynchronous Iterators:: 
* Asynchronous Context Managers:: 

@end menu

@node Awaitable Objects,協程物件,,協程
@anchor{reference/datamodel awaitable-objects}@anchor{22c4}
@subsubsection Awaitable Objects


An @ref{4c4,,awaitable} object generally implements an @ref{f70,,__await__()} method.
@ref{6b2,,Coroutine objects} returned from @ref{7e6,,async def} functions
are awaitable.

@cartouche
@quotation 備註 
The @ref{dd4,,generator iterator} objects returned from generators
decorated with @ref{1083,,types.coroutine()}
are also awaitable, but they do not implement @ref{f70,,__await__()}.
@end quotation
@end cartouche

@geindex __await__() (object 的方法)
@anchor{reference/datamodel object __await__}@anchor{f70}
@deffn {方法} object.__await__ (self)

Must return an @ref{4c3,,iterator}.  Should be used to implement
@ref{4c4,,awaitable} objects.  For instance, @ref{dc1,,asyncio.Future} implements
this method to be compatible with the @ref{18d,,await} expression.
The @ref{c75,,object} class itself is not awaitable and does not provide
this method.

@cartouche
@quotation 備註 
The language doesn't place any restriction on the type or value of the
objects yielded by the iterator returned by @code{__await__}, as this is
specific to the implementation of the asynchronous execution framework
(e.g. @ref{b,,asyncio}) that will be managing the @ref{4c4,,awaitable} object.
@end quotation
@end cartouche
@end deffn


在 3.5 版被加入.



@subsubheading 也參考


@geindex Python Enhancement Proposals; PEP 492
PEP 492@footnote{https://peps.python.org/pep-0492/} for additional information about awaitable objects.


@node 協程物件,Asynchronous Iterators,Awaitable Objects,協程
@anchor{reference/datamodel coroutine-objects}@anchor{2208}@anchor{reference/datamodel id19}@anchor{22c5}
@subsubsection 協程物件


@ref{6b2,,Coroutine objects} are @ref{4c4,,awaitable} objects.
A coroutine's execution can be controlled by calling @ref{f70,,__await__()} and
iterating over the result.  When the coroutine has finished executing and
returns, the iterator raises @ref{df0,,StopIteration}, and the exception's
@ref{22c6,,value} attribute holds the return value.  If the
coroutine raises an exception, it is propagated by the iterator.  Coroutines
should not directly raise unhandled @ref{df0,,StopIteration} exceptions.

Coroutines also have the methods listed below, which are analogous to
those of generators (see @ref{22c7,,Generator-iterator methods}).  However, unlike
generators, coroutines do not directly support iteration.


在 3.5.2 版的變更: It is a @ref{244,,RuntimeError} to await on a coroutine more than once.


@geindex send() (coroutine 的方法)
@anchor{reference/datamodel coroutine send}@anchor{22c8}
@deffn {方法} coroutine.send (value)

Starts or resumes execution of the coroutine.  If `value' is @code{None},
this is equivalent to advancing the iterator returned by
@ref{f70,,__await__()}.  If `value' is not @code{None}, this method delegates
to the @ref{22c9,,send()} method of the iterator that caused
the coroutine to suspend.  The result (return value,
@ref{df0,,StopIteration}, or other exception) is the same as when
iterating over the @code{__await__()} return value, described above.
@end deffn

@geindex throw() (coroutine 的方法)
@anchor{reference/datamodel coroutine throw}@anchor{714}
@deffn {方法} coroutine.throw (value)

@deffnx {方法} coroutine.throw (type[, value[, traceback]])

Raises the specified exception in the coroutine.  This method delegates
to the @ref{715,,throw()} method of the iterator that caused
the coroutine to suspend, if it has such a method.  Otherwise,
the exception is raised at the suspension point.  The result
(return value, @ref{df0,,StopIteration}, or other exception) is the same as
when iterating over the @ref{f70,,__await__()} return value, described
above.  If the exception is not caught in the coroutine, it propagates
back to the caller.


在 3.12 版的變更: The second signature (type[, value[, traceback]]) is deprecated and
may be removed in a future version of Python.

@end deffn

@geindex close() (coroutine 的方法)
@anchor{reference/datamodel coroutine close}@anchor{22ca}
@deffn {方法} coroutine.close ()

Causes the coroutine to clean itself up and exit.  If the coroutine
is suspended, this method first delegates to the @ref{19b7,,close()}
method of the iterator that caused the coroutine to suspend, if it
has such a method.  Then it raises @ref{15bf,,GeneratorExit} at the
suspension point, causing the coroutine to immediately clean itself up.
Finally, the coroutine is marked as having finished executing, even if
it was never started.

Coroutine objects are automatically closed using the above process when
they are about to be destroyed.
@end deffn

@node Asynchronous Iterators,Asynchronous Context Managers,協程物件,協程
@anchor{reference/datamodel async-iterators}@anchor{f72}@anchor{reference/datamodel asynchronous-iterators}@anchor{22cb}
@subsubsection Asynchronous Iterators


An `asynchronous iterator' can call asynchronous code in
its @code{__anext__} method.

Asynchronous iterators can be used in an @ref{c98,,async for} statement.

The @ref{c75,,object} class itself does not provide these methods.

@geindex __aiter__() (object 的方法)
@anchor{reference/datamodel object __aiter__}@anchor{df1}
@deffn {方法} object.__aiter__ (self)

Must return an `asynchronous iterator' object.
@end deffn

@geindex __anext__() (object 的方法)
@anchor{reference/datamodel object __anext__}@anchor{17fd}
@deffn {方法} object.__anext__ (self)

Must return an `awaitable' resulting in a next value of the iterator.  Should
raise a @ref{1cd7,,StopAsyncIteration} error when the iteration is over.
@end deffn

An example of an asynchronous iterable object:

@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


在 3.5 版被加入.



在 3.7 版的變更: Prior to Python 3.7, @ref{df1,,__aiter__()} could return an `awaitable'
that would resolve to an
@ref{4c2,,asynchronous iterator}.

Starting with Python 3.7, @ref{df1,,__aiter__()} must return an
asynchronous iterator object.  Returning anything else
will result in a @ref{198,,TypeError} error.


@node Asynchronous Context Managers,,Asynchronous Iterators,協程
@anchor{reference/datamodel async-context-managers}@anchor{80b}@anchor{reference/datamodel asynchronous-context-managers}@anchor{22cc}
@subsubsection Asynchronous Context Managers


An `asynchronous context manager' is a `context manager' that is able to
suspend execution in its @code{__aenter__} and @code{__aexit__} methods.

Asynchronous context managers can be used in an @ref{185,,async with} statement.

The @ref{c75,,object} class itself does not provide these methods.

@geindex __aenter__() (object 的方法)
@anchor{reference/datamodel object __aenter__}@anchor{22cd}
@deffn {方法} object.__aenter__ (self)

Semantically similar to @ref{7dd,,__enter__()}, the only
difference being that it must return an `awaitable'.
@end deffn

@geindex __aexit__() (object 的方法)
@anchor{reference/datamodel object __aexit__}@anchor{18f8}
@deffn {方法} object.__aexit__ (self, exc_type, exc_value, traceback)

Semantically similar to @ref{1501,,__exit__()}, the only
difference being that it must return an `awaitable'.
@end deffn

An example of an asynchronous context manager class:

@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


在 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{22ce}@anchor{reference/executionmodel execmodel}@anchor{22cf}@anchor{reference/executionmodel execution-model}@anchor{22d0}@anchor{reference/executionmodel translation-repo}@anchor{22d1}
@section 執行模型


@geindex execution model（執行模型）
@geindex code（程式碼）;block

@menu
* Structure of a program:: 
* Naming and binding:: 
* 例外:: 
* Runtime Components:: 

@end menu

@node Structure of a program,Naming and binding,,執行模型
@anchor{reference/executionmodel prog-structure}@anchor{22d2}@anchor{reference/executionmodel structure-of-a-program}@anchor{22d3}
@subsection Structure of a program


@geindex block

A Python program is constructed from code blocks.
A `block' is a piece of Python program text that is executed as a unit.
The following are blocks: a module, a function body, and a class definition.
Each command typed interactively is a block.  A script file (a file given as
standard input to the interpreter or specified as a command line argument to the
interpreter) is a code block.  A script command (a command specified on the
interpreter command line with the @ref{1a8,,-c} option) is a code block.
A module run as a top level script (as module @code{__main__}) from the command
line using a @ref{23c,,-m} argument is also a code block. The string
argument passed to the built-in functions @ref{49e,,eval()} and @ref{49d,,exec()} is a
code block.

@geindex execution（執行）;frame

A code block is executed in an `execution frame'.  A frame contains some
administrative information (used for debugging) and determines where and how
execution continues after the code block's execution has completed.

@node Naming and binding,例外,Structure of a program,執行模型
@anchor{reference/executionmodel naming}@anchor{21f8}@anchor{reference/executionmodel naming-and-binding}@anchor{22d4}
@subsection Naming and binding


@geindex namespace（命名空間）
@geindex scope（作用域）

@menu
* Binding of names:: 
* Resolution of names:: 
* 註釋作用域 (annotation scopes): 註釋作用域 annotation scopes. 
* Lazy evaluation:: 
* Builtins and restricted execution:: 
* Interaction with dynamic features:: 

@end menu

@node Binding of names,Resolution of names,,Naming and binding
@anchor{reference/executionmodel bind-names}@anchor{22d5}@anchor{reference/executionmodel binding-of-names}@anchor{22d6}
@subsubsection Binding of names


@geindex name（名稱）
@geindex binding（繫結）;name（名稱）

`Names' refer to objects.  Names are introduced by name binding operations.

@geindex from;import statement（引入陳述式）

The following constructs bind names:


@itemize *

@item 
formal parameters to functions,

@item 
class definitions,

@item 
function definitions,

@item 
assignment expressions,

@item 
@ref{22d7,,targets} that are identifiers if occurring in
an assignment:


@itemize +

@item 
@ref{348,,for} loop header,

@item 
after @code{as} in a @ref{186,,with} statement, @ref{1ab,,except}
clause, @ref{1ac,,except*} clause, or in the as-pattern in structural pattern matching,

@item 
in a capture pattern in structural pattern matching
@end itemize

@item 
@ref{7f1,,import} 陳述式。

@item 
@ref{665,,type} 陳述式。

@item 
@ref{5a7,,type parameter lists}.
@end itemize

The @code{import} statement of the form @code{from ... import *} binds all
names defined in the imported module, except those beginning with an underscore.
This form may only be used at the module level.

A target occurring in a @ref{1a62,,del} statement is also considered bound for
this purpose (though the actual semantics are to unbind the name).

Each assignment or import statement occurs within a block defined by a class or
function definition or at the module level (the top-level code block).

@geindex free;variable（變數）

If a name is bound in a block, it is a local variable of that block, unless
declared as @ref{14a8,,nonlocal} or @ref{4a7,,global}.  If a name is bound at
the module level, it is a global variable.  (The variables of the module code
block are local and global.)  If a variable is used in a code block but not
defined there, it is a @ref{22d8,,free variable}.

Each occurrence of a name in the program text refers to the `binding' of
that name established by the following name resolution rules.

@node Resolution of names,註釋作用域 annotation scopes,Binding of names,Naming and binding
@anchor{reference/executionmodel resolution-of-names}@anchor{22d9}@anchor{reference/executionmodel resolve-names}@anchor{22da}
@subsubsection Resolution of names


@geindex scope（作用域）

A `scope' defines the visibility of a name within a block.  If a local
variable is defined in a block, its scope includes that block.  If the
definition occurs in a function block, the scope extends to any blocks contained
within the defining one, unless a contained block introduces a different binding
for the name.

@geindex environment（環境）

When a name is used in a code block, it is resolved using the nearest enclosing
scope.  The set of all such scopes visible to a code block is called the block's
`environment'.

@geindex NameError（內建例外）
@geindex UnboundLocalError

When a name is not found at all, a @ref{450,,NameError} exception is raised.
If the current scope is a function scope, and the name refers to a local
variable that has not yet been bound to a value at the point where the name is
used, an @ref{172a,,UnboundLocalError} exception is raised.
@ref{172a,,UnboundLocalError} is a subclass of @ref{450,,NameError}.

If a name binding operation occurs anywhere within a code block, all uses of the
name within the block are treated as references to the current block.  This can
lead to errors when a name is used within a block before it is bound.  This rule
is subtle.  Python lacks declarations and allows name binding operations to
occur anywhere within a code block.  The local variables of a code block can be
determined by scanning the entire text of the block for name binding operations.
See @ref{22db,,the FAQ entry on UnboundLocalError}
for examples.

If the @ref{4a7,,global} statement occurs within a block, all uses of the names
specified in the statement refer to the bindings of those names in the top-level
namespace.  Names are resolved in the top-level namespace by searching the
global namespace, i.e. the namespace of the module containing the code block,
and the builtins namespace, the namespace of the module @ref{13,,builtins}.  The
global namespace is searched first.  If the names are not found there, the
builtins namespace is searched next. If the names are also not found in the
builtins namespace, new variables are created in the global namespace.
The global statement must precede all uses of the listed names.

The @ref{4a7,,global} statement has the same scope as a name binding operation
in the same block.  If the nearest enclosing scope for a free variable contains
a global statement, the free variable is treated as a global.

@c XXX say more about "nonlocal" semantics here

The @ref{14a8,,nonlocal} statement causes corresponding names to refer
to previously bound variables in the nearest enclosing function scope.
@ref{18e,,SyntaxError} is raised at compile time if the given name does not
exist in any enclosing function scope. @ref{5a7,,Type parameters}
cannot be rebound with the @code{nonlocal} statement.

@geindex module（模組）;__main__

The namespace for a module is automatically created the first time a module is
imported.  The main module for a script is always called @ref{1,,__main__}.

Class definition blocks and arguments to @ref{49d,,exec()} and @ref{49e,,eval()} are
special in the context of name resolution.
A class definition is an executable statement that may use and define names.
These references follow the normal rules for name resolution with an exception
that unbound local variables are looked up in the global namespace.
The namespace of the class definition becomes the attribute dictionary of
the class. The scope of names defined in a class block is limited to the
class block; it does not extend to the code blocks of methods. This includes
comprehensions and generator expressions, but it does not include
@ref{4a6,,annotation scopes},
which have access to their enclosing class scopes.
This means that the following will fail:

@example
class A:
    a = 42
    b = list(a + i for i in range(10))
@end example

However, the following will succeed:

@example
class A:
    type Alias = Nested
    class Nested: pass

print(A.Alias.__value__)  # <type 'A.Nested'>
@end example

@node 註釋作用域 annotation scopes,Lazy evaluation,Resolution of names,Naming and binding
@anchor{reference/executionmodel annotation-scopes}@anchor{4a6}@anchor{reference/executionmodel id1}@anchor{22dc}
@subsubsection 註釋作用域 (annotation scopes)


@ref{15c,,Annotations}, @ref{5a7,,type parameter lists}
and @ref{665,,type} statements
introduce `annotation scopes', which behave mostly like function scopes,
but with some exceptions discussed below.

Annotation scopes are used in the following contexts:


@itemize *

@item 
@ref{1ee2,,Function annotations}.

@item 
@ref{f4c,,Variable annotations}.

@item 
Type parameter lists for @ref{67d,,generic type aliases}.

@item 
Type parameter lists for @ref{67b,,generic functions}.
A generic function's annotations are
executed within the annotation scope, but its defaults and decorators are not.

@item 
Type parameter lists for @ref{67a,,generic classes}.
A generic class's base classes and
keyword arguments are executed within the annotation scope, but its decorators are not.

@item 
The bounds, constraints, and default values for type parameters
(@ref{67e,,lazily evaluated}).

@item 
The value of type aliases (@ref{67e,,lazily evaluated}).
@end itemize

Annotation scopes differ from function scopes in the following ways:


@itemize *

@item 
Annotation scopes have access to their enclosing class namespace.
If an annotation scope is immediately within a class scope, or within another
annotation scope that is immediately within a class scope, the code in the
annotation scope can use names defined in the class scope as if it were
executed directly within the class body. This contrasts with regular
functions defined within classes, which cannot access names defined in the class scope.

@item 
Expressions in annotation scopes cannot contain @ref{bb9,,yield}, @code{yield from},
@ref{18d,,await}, or @ref{22dd,,;=}
expressions. (These expressions are allowed in other scopes contained within the
annotation scope.)

@item 
Names defined in annotation scopes cannot be rebound with @ref{14a8,,nonlocal}
statements in inner scopes. This includes only type parameters, as no other
syntactic elements that can appear within annotation scopes can introduce new names.

@item 
While annotation scopes have an internal name, that name is not reflected in the
@ref{1bf6,,qualified name} of objects defined within the scope.
Instead, the @ref{1260,,__qualname__}
of such objects is as if the object were defined in the enclosing scope.
@end itemize


在 3.12 版被加入: Annotation scopes were introduced in Python 3.12 as part of 
@geindex Python Enhancement Proposals; PEP 695
PEP 695@footnote{https://peps.python.org/pep-0695/}.



在 3.13 版的變更: Annotation scopes are also used for type parameter defaults, as
introduced by 
@geindex Python Enhancement Proposals; PEP 696
PEP 696@footnote{https://peps.python.org/pep-0696/}.



在 3.14 版的變更: Annotation scopes are now also used for annotations, as specified in
@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 Lazy evaluation,Builtins and restricted execution,註釋作用域 annotation scopes,Naming and binding
@anchor{reference/executionmodel id2}@anchor{22de}@anchor{reference/executionmodel lazy-evaluation}@anchor{67e}
@subsubsection Lazy evaluation


Most annotation scopes are `lazily evaluated'. This includes annotations,
the values of type aliases created through the @ref{665,,type} statement, and
the bounds, constraints, and default values of type
variables created through the @ref{5a7,,type parameter syntax}.
This means that they are not evaluated when the type alias or type variable is
created, or when the object carrying annotations is created. Instead, they
are only evaluated when necessary, for example when the @code{__value__}
attribute on a type alias is accessed.

舉例來說：

@example
>>> type Alias = 1/0
>>> Alias.__value__
Traceback (most recent call last):
  ...
ZeroDivisionError: division by zero
>>> def func[T: 1/0](): pass
>>> T = func.__type_params__[0]
>>> T.__bound__
Traceback (most recent call last):
  ...
ZeroDivisionError: division by zero
@end example

Here the exception is raised only when the @code{__value__} attribute
of the type alias or the @code{__bound__} attribute of the type variable
is accessed.

This behavior is primarily useful for references to types that have not
yet been defined when the type alias or type variable is created. For example,
lazy evaluation enables creation of mutually recursive type aliases:

@example
from typing import Literal

type SimpleExpr = int | Parenthesized
type Parenthesized = tuple[Literal["("], Expr, Literal[")"]]
type Expr = SimpleExpr | tuple[SimpleExpr, Literal["+", "-"], Expr]
@end example

Lazily evaluated values are evaluated in @ref{4a6,,annotation scope},
which means that names that appear inside the lazily evaluated value are looked up
as if they were used in the immediately enclosing scope.


在 3.12 版被加入.


@node Builtins and restricted execution,Interaction with dynamic features,Lazy evaluation,Naming and binding
@anchor{reference/executionmodel builtins-and-restricted-execution}@anchor{22df}@anchor{reference/executionmodel restrict-exec}@anchor{22e0}
@subsubsection Builtins and restricted execution


@geindex restricted（受限）;execution（執行）

`CPython 實作細節：' Users should not touch @code{__builtins__}; it is strictly an implementation
detail.  Users wanting to override values in the builtins namespace should
@ref{7f1,,import} the @ref{13,,builtins} module and modify its
attributes appropriately.

The builtins namespace associated with the execution of a code block
is actually found by looking up the name @code{__builtins__} in its
global namespace; this should be a dictionary or a module (in the
latter case the module's dictionary is used).  By default, when in the
@ref{1,,__main__} module, @code{__builtins__} is the built-in module
@ref{13,,builtins}; when in any other module, @code{__builtins__} is an
alias for the dictionary of the @ref{13,,builtins} module itself.

@node Interaction with dynamic features,,Builtins and restricted execution,Naming and binding
@anchor{reference/executionmodel dynamic-features}@anchor{22e1}@anchor{reference/executionmodel interaction-with-dynamic-features}@anchor{22e2}
@subsubsection Interaction with dynamic features


Name resolution of free variables occurs at runtime, not at compile time.
This means that the following code will print 42:

@example
i = 10
def f():
    print(i)
i = 42
f()
@end example

@c XXX from * also invalid with relative imports (at least currently)

The @ref{49e,,eval()} and @ref{49d,,exec()} functions do not have access to the full
environment for resolving names.  Names may be resolved in the local and global
namespaces of the caller.  Free variables are not resolved in the nearest
enclosing namespace, but in the global namespace.  @footnote{
This limitation occurs because the code that is executed by these operations
is not available at the time the module is compiled.
} The @ref{49d,,exec()} and
@ref{49e,,eval()} functions have optional arguments to override the global and local
namespace.  If only one namespace is specified, it is used for both.

@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 例外,Runtime Components,Naming and binding,執行模型
@anchor{reference/executionmodel exceptions}@anchor{22e3}@anchor{reference/executionmodel id4}@anchor{22e4}
@subsection 例外


@geindex exception（例外）

@geindex raise an exception（引發例外）
@geindex handle an exception（處理例外）
@geindex exception handler（例外處理器）
@geindex errors（錯誤）
@geindex error handling（錯誤處理）

Exceptions are a means of breaking out of the normal flow of control of a code
block in order to handle errors or other exceptional conditions.  An exception
is `raised' at the point where the error is detected; it may be `handled' by the
surrounding code block or by any code block that directly or indirectly invoked
the code block where the error occurred.

The Python interpreter raises an exception when it detects a run-time error
(such as division by zero).  A Python program can also explicitly raise an
exception with the @ref{7fc,,raise} statement. Exception handlers are specified
with the @ref{8f0,,try} ... @ref{1ab,,except} statement.  The @ref{1b0,,finally}
clause of such a statement can be used to specify cleanup code which does not
handle the exception, but is executed whether an exception occurred or not in
the preceding code.

@geindex termination model（終止模型）

Python uses the "termination" model of error handling: an exception handler can
find out what happened and continue execution at an outer level, but it cannot
repair the cause of the error and retry the failing operation (except by
re-entering the offending piece of code from the top).

@geindex SystemExit（內建例外）

When an exception is not handled at all, the interpreter terminates execution of
the program, or returns to its interactive main loop.  In either case, it prints
a stack traceback, except when the exception is @ref{f37,,SystemExit}.

Exceptions are identified by class instances.  The @ref{1ab,,except} clause is
selected depending on the class of the instance: it must reference the class of
the instance or a @ref{13b7,,non-virtual base class} thereof.
The instance can be received by the handler and can carry additional information
about the exceptional condition.

@cartouche
@quotation 備註 
Exception messages are not part of the Python API.  Their contents may change
from one version of Python to the next without warning and should not be
relied on by code which will run under multiple versions of the interpreter.
@end quotation
@end cartouche

See also the description of the @ref{8f0,,try} statement in section @ref{8f0,,try 陳述式}
and @ref{7fc,,raise} statement in section @ref{7fc,,raise 陳述式}.

@node Runtime Components,,例外,執行模型
@anchor{reference/executionmodel execcomponents}@anchor{22e5}@anchor{reference/executionmodel runtime-components}@anchor{22e6}
@subsection Runtime Components


@menu
* General Computing Model:: 
* Python Runtime Model:: 

@end menu

@node General Computing Model,Python Runtime Model,,Runtime Components
@anchor{reference/executionmodel general-computing-model}@anchor{22e7}
@subsubsection General Computing Model


Python's execution model does not operate in a vacuum.  It runs on
a host machine and through that host's runtime environment, including
its operating system (OS), if there is one.  When a program runs,
the conceptual layers of how it runs on the host look something
like this:

@quotation


@display
`host machine'@w{ }
@display
`process' (global resources)@w{ }
@display
`thread' (runs machine code)@w{ }
@end display
@end display
@end display


@end quotation

Each process represents a program running on the host.  Think of each
process itself as the data part of its program.  Think of the process'
threads as the execution part of the program.  This distinction will
be important to understand the conceptual Python runtime.

The process, as the data part, is the execution context in which the
program runs.  It mostly consists of the set of resources assigned to
the program by the host, including memory, signals, file handles,
sockets, and environment variables.

Processes are isolated and independent from one another.  (The same
is true for hosts.)  The host manages the process' access to its
assigned resources, in addition to coordinating between processes.

Each thread represents the actual execution of the program's machine
code, running relative to the resources assigned to the program's
process.  It's strictly up to the host how and when that execution
takes place.

From the point of view of Python, a program always starts with exactly
one thread.  However, the program may grow to run in multiple
simultaneous threads.  Not all hosts support multiple threads per
process, but most do.  Unlike processes, threads in a process are not
isolated and independent from one another.  Specifically, all threads
in a process share all of the process' resources.

The fundamental point of threads is that each one does `run'
independently, at the same time as the others.  That may be only
conceptually at the same time ("concurrently") or physically
("in parallel").  Either way, the threads effectively run
at a non-synchronized rate.

@cartouche
@quotation 備註 
That non-synchronized rate means none of the process' memory is
guaranteed to stay consistent for the code running in any given
thread.  Thus multi-threaded programs must take care to coordinate
access to intentionally shared resources.  Likewise, they must take
care to be absolutely diligent about not accessing any `other'
resources in multiple threads; otherwise two threads running at the
same time might accidentally interfere with each other's use of some
shared data.  All this is true for both Python programs and the
Python runtime.

The cost of this broad, unstructured requirement is the tradeoff for
the kind of raw concurrency that threads provide.  The alternative
to the required discipline generally means dealing with
non-deterministic bugs and data corruption.
@end quotation
@end cartouche

@node Python Runtime Model,,General Computing Model,Runtime Components
@anchor{reference/executionmodel python-runtime-model}@anchor{22e8}
@subsubsection Python Runtime Model


The same conceptual layers apply to each Python program, with some
extra data layers specific to Python:

@quotation


@display
`host machine'@w{ }
@display
`process' (global resources)@w{ }
@display
Python global runtime (`state')@w{ }
@display
Python interpreter (`state')@w{ }
@display
`thread' (runs Python bytecode and "C-API")@w{ }
@display
Python thread `state'@w{ }
@end display
@end display
@end display
@end display
@end display
@end display


@end quotation

At the conceptual level: when a Python program starts, it looks exactly
like that diagram, with one of each.  The runtime may grow to include
multiple interpreters, and each interpreter may grow to include
multiple thread states.

@cartouche
@quotation 備註 
A Python implementation won't necessarily implement the runtime
layers distinctly or even concretely.  The only exception is places
where distinct layers are directly specified or exposed to users,
like through the @ref{f3,,threading} module.
@end quotation
@end cartouche

@cartouche
@quotation 備註 
The initial interpreter is typically called the "main" interpreter.
Some Python implementations, like CPython, assign special roles
to the main interpreter.

Likewise, the host thread where the runtime was initialized is known
as the "main" thread.  It may be different from the process' initial
thread, though they are often the same.  In some cases "main thread"
may be even more specific and refer to the initial thread state.
A Python runtime might assign specific responsibilities
to the main thread, such as handling signals.
@end quotation
@end cartouche

As a whole, the Python runtime consists of the global runtime state,
interpreters, and thread states.  The runtime ensures all that state
stays consistent over its lifetime, particularly when used with
multiple host threads.

The global runtime, at the conceptual level, is just a set of
interpreters.  While those interpreters are otherwise isolated and
independent from one another, they may share some data or other
resources.  The runtime is responsible for managing these global
resources safely.  The actual nature and management of these resources
is implementation-specific.  Ultimately, the external utility of the
global runtime is limited to managing interpreters.

In contrast, an "interpreter" is conceptually what we would normally
think of as the (full-featured) "Python runtime".  When machine code
executing in a host thread interacts with the Python runtime, it calls
into Python in the context of a specific interpreter.

@cartouche
@quotation 備註 
The term "interpreter" here is not the same as the "bytecode
interpreter", which is what regularly runs in threads, executing
compiled Python code.

In an ideal world, "Python runtime" would refer to what we currently
call "interpreter".  However, it's been called "interpreter" at least
since introduced in 1997 (CPython:a027efa5b@footnote{https://github.com/python/cpython/commit/a027efa5b}).
@end quotation
@end cartouche

Each interpreter completely encapsulates all of the non-process-global,
non-thread-specific state needed for the Python runtime to work.
Notably, the interpreter's state persists between uses.  It includes
fundamental data like @ref{17c0,,sys.modules}.  The runtime ensures
multiple threads using the same interpreter will safely
share it between them.

A Python implementation may support using multiple interpreters at the
same time in the same process.  They are independent and isolated from
one another.  For example, each interpreter has its own
@ref{17c0,,sys.modules}.

For thread-specific runtime state, each interpreter has a set of thread
states, which it manages, in the same way the global runtime contains
a set of interpreters.  It can have thread states for as many host
threads as it needs.  It may even have multiple thread states for
the same host thread, though that isn't as common.

Each thread state, conceptually, has all the thread-specific runtime
data an interpreter needs to operate in one host thread.  The thread
state includes the current raised exception and the thread's Python
call stack.  It may include other thread-specific resources.

@cartouche
@quotation 備註 
The term "Python thread" can sometimes refer to a thread state, but
normally it means a thread created using the @ref{f3,,threading} module.
@end quotation
@end cartouche

Each thread state, over its lifetime, is always tied to exactly one
interpreter and exactly one host thread.  It will only ever be used in
that thread and with that interpreter.

Multiple thread states may be tied to the same host thread, whether for
different interpreters or even the same interpreter.  However, for any
given host thread, only one of the thread states tied to it can be used
by the thread at a time.

Thread states are isolated and independent from one another and don't
share any data, except for possibly sharing an interpreter and objects
or other resources belonging to that interpreter.

Once a program is running, new Python threads can be created using the
@ref{f3,,threading} module (on platforms and Python implementations that
support threads).  Additional processes can be created using the
@ref{a5,,os}, @ref{dc,,subprocess}, and @ref{98,,multiprocessing} modules.
Interpreters can be created and used with the
@ref{25,,interpreters} module.  Coroutines (async) can
be run using @ref{b,,asyncio} in each interpreter, typically only
in a single thread (often the main thread).

@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/import doc}@anchor{22e9}@anchor{reference/import importsystem}@anchor{2212}@anchor{reference/import the-import-system}@anchor{22ea}@anchor{reference/import translation-repo}@anchor{22eb}
@section 模組引入系統


@geindex import machinery（引入機制）

一個 @ref{192d,,module} 中的 Python 程式碼透過 @ref{22ec,,importing} 的過程來存取另一個模組中的程式碼。@ref{7f1,,import} 陳述式是叫用 (invoke) 引入機制最常見的方法，但這不是唯一的方法。函式如 @ref{735,,importlib.import_module()} 以及內建函式 @ref{ac8,,__import__()} 也可以用來叫用引入機制。

@ref{7f1,,import} 陳述式結合了兩個操作：首先搜尋指定的模組，然後將搜尋結果繫結到本地作用域中的一個名稱。@code{import} 陳述式的搜尋操作被定義為一個對 @ref{ac8,,__import__()} 函式的呼叫，並帶有相應的引數。@ref{ac8,,__import__()} 的回傳值用於執行 @code{import} 陳述式的名稱繫結操作。有關名稱繫結操作的詳細資訊，請參見 @code{import} 陳述式。

直接呼叫 @ref{ac8,,__import__()} 只會執行模組搜尋操作，以及在找到時執行模組的建立操作。雖然某些副作用可能會發生，例如引入父套件 (parent package)，以及更新各種快取（包括 @ref{17c0,,sys.modules}），但只有 @ref{7f1,,import} 陳述式會執行名稱繫結操作。

當執行 @ref{7f1,,import} 陳述式時，會呼叫內建的 @ref{ac8,,__import__()} 函式。其他叫用引入系統的機制（如 @ref{735,,importlib.import_module()}）可以選擇略過 @ref{ac8,,__import__()}，並使用它們自己的解決方案來實作引入語意。

當模組首次被引入時，Python 會搜尋該模組，若找到則會建立一個模組物件 @footnote{
參閱 @ref{100f,,types.ModuleType}。
}，並對其進行初始化。如果找不到指定的模組，則會引發 @ref{d35,,ModuleNotFoundError}。當引入機制被叫用時，Python 會實作各種策略來搜尋指定的模組。這些策略可以透過使用以下章節描述的各種 hook（掛鉤）來修改和擴展。


在 3.3 版的變更: 引入系統已被更新，以完全實作 
@geindex Python Enhancement Proposals; PEP 302
PEP 302@footnote{https://peps.python.org/pep-0302/} 的第二階段。不再有隱式引入機制——完整的引入系統已透過 @ref{f22,,sys.meta_path} 公開。此外，原生命名空間套件支援（請參閱 
@geindex Python Enhancement Proposals; PEP 420
PEP 420@footnote{https://peps.python.org/pep-0420/}）也已被實作。


@menu
* importlib: importlib<10>. 
* 套件:: 
* 搜尋:: 
* 載入:: 
* The Path Based Finder:: 
* Replacing the standard import system:: 
* Package Relative Imports:: 
* Special considerations for __main__:: 
* References:: 

@end menu

@node importlib<10>,套件,,模組引入系統
@anchor{reference/import importlib}@anchor{22ed}
@subsection @code{importlib}


@ref{7b,,importlib} 模組提供了豐富的 API 來與引入系統互動。例如，@ref{735,,importlib.import_module()} 提供了一個比內建的 @ref{ac8,,__import__()} 更推薦且更簡單的 API 來叫用引入機制。更多詳細資訊請參閱 @ref{7b,,importlib} 函式庫文件。

@node 套件,搜尋,importlib<10>,模組引入系統
@anchor{reference/import packages}@anchor{22ee}
@subsection 套件


@geindex package（套件）

Python 只有一種類型的模組物件，且所有模組，無論其是使用 Python、C 還是其他語言實作，都是這種類型。為了幫助組織模組並提供命名階層，Python 導入了@ref{233,,套件}的概念。

你可以將套件視為檔案系統中的目錄，模組則是目錄中的檔案，但不要過於字面地理解這個比喻，因為套件和模組不一定來自檔案系統。為了方便解釋，我們將使用這個目錄和檔案的比喻。就像檔案系統目錄一樣，套件是分層組織的，套件本身可以包含子套件以及一般模組。

請記住，所有的套件都是模組，但並非所有模組都是套件。換句話說，套件只是一種特殊的模組。具體來說，任何包含 @code{__path__} 屬性的模組都被視為套件。

所有模組都有一個名稱。子套件的名稱與其父套件名稱之間用一個點來分隔，類似於 Python 的標準屬性存取語法。因此，你可能會有一個名為 @ref{3f,,email} 的套件，該套件又有一個名為 @ref{49,,email.mime} 的子套件，並且該子套件中有一個名為 @ref{51,,email.mime.text} 的模組。

@menu
* 一般套件:: 
* 命名空間套件:: 

@end menu

@node 一般套件,命名空間套件,,套件
@anchor{reference/import regular-packages}@anchor{22ef}
@subsubsection 一般套件


@geindex package（套件）;regular（一般）

Python 定義了兩種類型的套件，@ref{22f0,,一般套件}和@ref{2b2,,命名空間套件}。一般套件是 Python 3.2 及更早版本中存在的傳統套件。一般套件通常實作成一個包含 @code{__init__.py} 檔案的目錄。當引入一般套件時，該 @code{__init__.py} 檔案會被隱式執行，其定義的物件會繫結到該套件的命名空間中的名稱。@code{__init__.py} 檔案可以包含與任何其他模組相同的 Python 程式碼，並且 Python 會在引入時為該模組增加一些額外的屬性。

例如，以下檔案系統布置定義了一個頂層的 @code{parent} 套件，該套件包含三個子套件：

@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 命名空間套件,,一般套件,套件
@anchor{reference/import namespace-packages}@anchor{22f1}@anchor{reference/import reference-namespace-package}@anchor{22f2}
@subsubsection 命名空間套件


@geindex package（套件）;namespace（命名空間）
@geindex package（套件）;portion（部分）

命名空間套件是由不同的@ref{22f3,,部分} 組成的，每個部分都為父套件提供一個子套件。這些部分可以位於檔案系統上的不同位置。部分可能也存在於壓縮檔案中、網路上，或 Python 在引入時搜尋的任何其他地方。命名空間套件不一定直接對應於檔案系統中的對象；它們可能是沒有具體表示的虛擬模組。

命名空間套件的 @code{__path__} 屬性不使用普通的串列。它們使用自定義的可疊代型別，當父套件的路徑（或頂層套件的 @ref{3e2,,sys.path}）發生變化時，會在下一次引入嘗試時自動執行新一輪的套件部分搜尋。

在命名空間套件中，不存在 @code{parent/__init__.py} 檔案。實際上，在引入搜尋過程中可能會找到多個 @code{parent} 目錄，每個目錄由不同的部分提供。因此，@code{parent/one} 可能與 @code{parent/two} 不會實際位於一起。在這種情況下，每當引入頂層 @code{parent} 套件或其子套件之一時，Python 會為頂層 @code{parent} 套件建立一個命名空間套件。

有關命名空間套件的規範，請參見 
@geindex Python Enhancement Proposals; PEP 420
PEP 420@footnote{https://peps.python.org/pep-0420/}。

@node 搜尋,載入,套件,模組引入系統
@anchor{reference/import searching}@anchor{22f4}
@subsection 搜尋


在開始搜尋之前，Python 需要被引入模組（或套件，但在本討論中，兩者的區別無關緊要）的完整@ref{1bf6,,限定名稱 (qualified name)}。此名稱可能來自 @ref{7f1,,import} 陳述式的各種引數，或來自 @ref{735,,importlib.import_module()} 或 @ref{ac8,,__import__()} 函式的參數。

此名稱將在引入搜尋的各個階段中使用，並且它可能是指向子模組的點分隔路徑，例如 @code{foo.bar.baz}。在這種情況下，Python 會首先嘗試引入 @code{foo}，然後是 @code{foo.bar}，最後是 @code{foo.bar.baz}。如果任何中間引入失敗，則會引發 @ref{d35,,ModuleNotFoundError}。

@menu
* 模組快取:: 
* 尋檢器 (Finder) 與載入器 (Loader): 尋檢器 Finder 與載入器 Loader. 
* 引入掛鉤 (Import hooks): 引入掛鉤 Import hooks. 
* 元路徑:: 

@end menu

@node 模組快取,尋檢器 Finder 與載入器 Loader,,搜尋
@anchor{reference/import the-module-cache}@anchor{22f5}
@subsubsection 模組快取


@geindex sys.modules

在引入搜尋過程中首先檢查的地方是 @ref{17c0,,sys.modules}。此對映用作所有先前引入過的模組的快取，包括中間路徑。因此，如果 @code{foo.bar.baz} 之前已被引入，@ref{17c0,,sys.modules} 將包含 @code{foo}、@code{foo.bar} 和 @code{foo.bar.baz} 的條目。每個鍵的值都是相應的模組物件。

在引入過程中，會在 @ref{17c0,,sys.modules} 中查找模組名稱，如果存在，則相關的值為滿足此引入的模組，此引入過程即完成。然而，如果值是 @code{None}，則會引發 @ref{d35,,ModuleNotFoundError}。如果模組名稱不存在，Python 會繼續搜尋該模組。

@ref{17c0,,sys.modules} 是可寫入的。刪除一個鍵可能不會銷毀相關聯的模組（因為其他模組可能持有對它的參照），但會使指定的模組的快取條目失效，導致 Python 在下一次引入該模組時重新搜尋。也可以將鍵賦值為 @code{None}，這會強制下一次引入該模組時引發 @ref{d35,,ModuleNotFoundError}。

但請注意，如果你保留了對模組物件的參照，並在 @ref{17c0,,sys.modules} 中使其快取條目失效，然後重新引入指定的模組，這兩個模組物件將`不會'相同。相比之下，@ref{736,,importlib.reload()} 會重用`相同的'模組物件，並透過重新執行模組的程式碼來簡單地重新初始化模組內容。

@node 尋檢器 Finder 與載入器 Loader,引入掛鉤 Import hooks,模組快取,搜尋
@anchor{reference/import finders-and-loaders}@anchor{22f6}@anchor{reference/import id2}@anchor{22f7}
@subsubsection 尋檢器 (Finder) 與載入器 (Loader)


@geindex finder（搜尋器）
@geindex loader（載入器）
@geindex module spec

如果在 @ref{17c0,,sys.modules} 中找不到指定的模組，則會叫用 Python 的引入協定來尋找並載入該模組。這個協定由兩個概念性物件組成，@ref{221c,,尋檢器} 和@ref{1978,,載入器}。尋檢器的任務是使用其已知的策略來確定是否能找到命名模組。實作這兩個介面的物件稱為@ref{22f8,,引入器 (importer)} ——當它們發現可以載入所請求的模組時，會回傳它們自己。

Python 包含多個預設的尋檢器和引入器。第一個尋檢器知道如何定位內建模組，第二個尋檢器知道如何定位凍結模組。第三個預設尋檢器會在 @ref{22f9,,import path} 中搜尋模組。@ref{22f9,,import path} 是一個位置的列表，這些位置可能是檔案系統路徑或壓縮檔案，也可以擴展以搜尋任何可定位的資源，例如由 URL 識別的資源。

引入機制是可擴展的，因此可以增加新的尋檢器來擴展模組搜尋的範圍和作用域。

尋檢器實際上不會載入模組。如果它們能找到指定的模組，它們會回傳一個`模組規格'，這是一個模組的引入相關資訊的封裝，引入機制會在載入模組時使用這些資訊。

以下各節將更詳細地描述尋檢器和載入器的協定，包括如何建立和註冊新的尋檢器和載入器來擴展引入機制。


在 3.4 版的變更: Python 在之前的版本中，尋檢器會直接回傳@ref{1978,,載入器}，而現在它們回傳的是`包含'載入器的模組規格。載入器仍在引入過程中使用，但其責任減少了。


@node 引入掛鉤 Import hooks,元路徑,尋檢器 Finder 與載入器 Loader,搜尋
@anchor{reference/import import-hooks}@anchor{22fa}
@subsubsection 引入掛鉤 (Import hooks)


@geindex import hooks
@geindex meta hooks
@geindex path hooks
@geindex hooks;import（引入）
@geindex hooks;meta
@geindex hooks;path（路徑）

引入機制的設計是可擴展的；其主要機制是`引入掛鉤'。引入掛鉤有兩種類型：`元掛鉤 (meta hooks)' 和`引入路徑掛鉤'。

元掛鉤會在引入處理的開始階段被呼叫，除了查找 @ref{17c0,,sys.modules} 快取外，其他引入處理還未發生時就會呼叫。這允許元掛鉤覆蓋 @ref{3e2,,sys.path} 的處理、凍結模組，甚至是內建模組。元掛鉤透過將新的尋檢器物件添加到 @ref{f22,,sys.meta_path} 中來註冊，具體描述請參閱以下段落。

引入路徑掛鉤被視為 @ref{3e2,,sys.path}（或 @code{package.__path__}）處理過程的一部分來呼叫，當遇到與其相關聯的路徑項目時就會被觸發。引入路徑掛鉤透過將新的可呼叫對象增加到 @ref{121f,,sys.path_hooks} 中來註冊，具體描述請參閱以下段落。

@node 元路徑,,引入掛鉤 Import hooks,搜尋
@anchor{reference/import the-meta-path}@anchor{22fb}
@subsubsection 元路徑


@geindex sys.meta_path
@geindex finder（搜尋器）;find_spec

當在 @ref{17c0,,sys.modules} 中找不到命名模組時，Python 接下來會搜尋 @ref{f22,,sys.meta_path}，其中包含一個元路徑尋檢器物件串列。這些尋檢器會依次被查詢，看它們是否知道如何處理命名模組。元路徑尋檢器必須實作一個名為 @ref{a61,,find_spec()} 的方法，該方法接收三個引數：名稱、引入路徑和（可選的）目標模組。元路徑尋檢器可以使用任何策略來確定它是否能處理命名模組。

如果元路徑尋檢器知道如何處理命名模組，它會回傳一個規格物件。如果它無法處理命名模組，則回傳 @code{None}。如果 @ref{f22,,sys.meta_path} 的處理到達串列的末尾仍未回傳規格，則會引發 @ref{d35,,ModuleNotFoundError}。任何其他引發的例外將直接向上傳播，並中止引入過程。

元路徑尋檢器的 @ref{a61,,find_spec()} 方法會以兩個或三個引數來呼叫。第一個是被引入模組的完全限定名稱，例如 @code{foo.bar.baz}。第二個引數是用於模組搜尋的路徑條目。對於頂層模組，第二個引數是 @code{None}，但對於子模組或子套件，第二個引數是父套件的 @code{__path__} 屬性的值。如果無法存取相應的 @code{__path__} 屬性，將引發 @ref{d35,,ModuleNotFoundError}。第三個引數是一個現有的模組物件，該物件將成為後續載入的目標。引入系統只會在重新載入時傳入目標模組。

對於一個引入請求，元路徑可能會被遍歷多次。例如，假設參與的模組都沒有被快取，則引入 @code{foo.bar.baz} 將首先執行頂層引入，對每個元路徑尋檢器（@code{mpf}）呼叫 @code{mpf.find_spec("foo", None, None)}。當 @code{foo} 被引入後，將再次藉由遍歷元路徑引入 @code{foo.bar}，並呼叫 @code{mpf.find_spec("foo.bar", foo.__path__, None)}。當 @code{foo.bar} 被引入後，最後一次遍歷會呼叫 @code{mpf.find_spec("foo.bar.baz", foo.bar.__path__, None)}。

一些元路徑尋檢器僅支援頂層引入。當第二個引數傳入 @code{None} 以外的值時，這些引入器將始終回傳 @code{None}。

Python 的預設 @ref{f22,,sys.meta_path} 有三個元路徑尋檢器，一個知道如何引入內建模組，一個知道如何引入凍結模組，還有一個知道如何從 @ref{22f9,,import path} 引入模組（即 @ref{22fc,,path based finder}）。


在 3.4 版的變更: 元路徑尋檢器的 @ref{a61,,find_spec()} 方法取代了 @code{find_module()}，後者現在已被棄用。雖然它將繼續正常工作，但引入機制僅在尋檢器未實作 @ref{a61,,find_spec()} 時才會嘗試使用它。



在 3.10 版的變更: 引入系統現在使用 @code{find_module()} 時將引發 @ref{717,,ImportWarning}。



在 3.12 版的變更: @code{find_module()} 已被移除。請改用 @ref{a61,,find_spec()}。


@node 載入,The Path Based Finder,搜尋,模組引入系統
@anchor{reference/import loading}@anchor{22fd}
@subsection 載入


如果找到模組規格，引入機制會在載入模組時使用該規格（以及它包含的載入器）。以下是引入過程中載入部分的大致情況：

@example
module = None
if spec.loader is not None and hasattr(spec.loader, 'create_module'):
    # 這裡假設載入器上也會定義 'exec_module'
    module = spec.loader.create_module(spec)
if module is None:
    module = ModuleType(spec.name)
# 與引入相關的模組屬性會在此處設定：
_init_module_attrs(spec, module)

if spec.loader is None:
    # 不支援
    raise ImportError
if spec.origin is None and spec.submodule_search_locations is not None:
    # 命名空間套件
    sys.modules[spec.name] = module
elif not hasattr(spec.loader, 'exec_module'):
    module = spec.loader.load_module(spec.name)
else:
    sys.modules[spec.name] = module
    try:
        spec.loader.exec_module(module)
    except BaseException:
        try:
            del sys.modules[spec.name]
        except KeyError:
            pass
        raise
return sys.modules[spec.name]
@end example

請注意下列細節：


@itemize *

@item 
如果 @ref{17c0,,sys.modules} 中已存在具有給定名稱的模組物件，引入會已回傳該物件。

@item 
在載入器執行模組程式碼之前，模組將已存在於 @ref{17c0,,sys.modules} 中。這一點至關重要，因為模組程式碼可能會（直接或間接）引入自己；事先將其增加到 @ref{17c0,,sys.modules} 可以預防類似無限遞迴以及多次重覆載入等情形。

@item 
如果載入失敗，只有載入失敗的模組會從 @ref{17c0,,sys.modules} 中刪除。任何已存在於 @ref{17c0,,sys.modules} 快取中的模組，以及任何在載入失敗前成功載入的模組，都必須保留在快取中。此情形與重新載入不同，在重新載入時，即使載入失敗的模組也會保留在 @ref{17c0,,sys.modules} 中。

@item 
模組建立後、在執行之前，引入機制會設置與引入相關的模組屬性（在上面的偽程式碼範例中為 "_init_module_attrs"），具體內容在@ref{2213,,之後的段落}會總結。

@item 
模組執行是載入過程中的關鍵時刻，此時模組的命名空間會被新增名稱。執行過程完全交由載入器處理，由其決定如何新增以及新增什麼。

@item 
在載入過程中建立並傳遞給 exec_module() 的模組，可能不會是引入結束時回傳的模組 @footnote{
The importlib implementation avoids using the return value
directly. Instead, it gets the module object by looking the module name up
in @ref{17c0,,sys.modules}.  The indirect effect of this is that an imported
module may replace itself in @ref{17c0,,sys.modules}.  This is
implementation-specific behavior that is not guaranteed to work in other
Python implementations.
}。
@end itemize


在 3.4 版的變更: 引入系統已接管載入器的模板 (boilerplate) 責任。之前是由 @ref{a62,,importlib.abc.Loader.load_module()} 方法執行的。


@menu
* 載入器:: 
* 子模組:: 
* 模組規格:: 
* __path__ attributes on modules:: 
* Module reprs:: 
* Cached bytecode invalidation:: 

@end menu

@node 載入器,子模組,,載入
@anchor{reference/import loaders}@anchor{22fe}
@subsubsection 載入器


模組載入器提供了載入的關鍵功能：模組執行。引入機制會以單一引數（即要執行的模組物件）呼叫 @ref{a63,,importlib.abc.Loader.exec_module()} 方法。任何從 @ref{a63,,exec_module()} 回傳的值都會被忽略。

載入器必須滿足以下要求：


@itemize *

@item 
如果模組是 Python 模組（而非內建模組或動態載入的擴充），載入器應在模組的全域命名空間 (@code{module.__dict__}) 中執行該模組的程式碼。

@item 
如果載入器無法執行該模組，應引發 @ref{653,,ImportError}。不過，在 @ref{a63,,exec_module()} 中引發的任何其他例外也會被傳播。
@end itemize

在許多情況下，尋檢器和載入器可以是同一個物件；在這種情況下，@ref{a61,,find_spec()} 方法只需回傳一個載入器設為 @code{self} 的規格即可。

模組載入器可以選擇透過實作 @ref{ea7,,create_module()} 方法，在載入過程中建立模組物件。該方法接受一個引數，即模組規格，並回傳在載入過程中要使用的新的模組物件。@code{create_module()} 不需要在模組物件上設定任何屬性。如果該方法回傳 @code{None}，引入機制將自行建立新的模組。


在 3.4 版被加入: 載入器的 @ref{ea7,,create_module()} 方法。



在 3.4 版的變更: @ref{a62,,load_module()} 方法已被 @ref{a63,,exec_module()} 取代，引入機制已承擔所有載入的模板責任。

為了與現有的載入器相容，引入機制會在載入器未實作 @code{exec_module()} 且存在 @code{load_module()} 方法時使用該方法。然而，@code{load_module()} 已被棄用，載入器應改為實作 @code{exec_module()}。

@code{load_module()} 方法除了執行模組外，還必須實作上述全部的模板載入功能。所有相同的限制依然適用，並且還有一些額外的說明：


@itemize *

@item 
如果 @ref{17c0,,sys.modules} 中已存在具有給定名稱的模組物件，載入器必須使用該模組（否則 @ref{736,,importlib.reload()} 將無法正常運作）。如果命名模組不存在於 @ref{17c0,,sys.modules} 中，載入器必須建立一個新的模組物件並將其新增至 @ref{17c0,,sys.modules}。

@item 
在載入器執行模組程式碼之前，該模組`必須'已存在於 @ref{17c0,,sys.modules} 中，以防止無限遞迴或多次載入。

@item 
如果載入失敗，載入器必須移除已經插入到 @ref{17c0,,sys.modules} 中的任何模組，但`只能'移除失敗的模組（們），且僅在載入器本身明確載入這些模組時才需移除。
@end itemize



在 3.5 版的變更: 當 @code{exec_module()} 已定義但未定義 @code{create_module()} 時，將引發 @ref{1a3,,DeprecationWarning}。



在 3.6 版的變更: 當 @code{exec_module()} 已定義但未定義 @code{create_module()} 時，將引發 @ref{653,,ImportError}。



在 3.10 版的變更: 使用 @code{load_module()} 將引發 @ref{717,,ImportWarning}。


@node 子模組,模組規格,載入器,載入
@anchor{reference/import submodules}@anchor{22ff}
@subsubsection 子模組


當使用任何機制（例如 @code{importlib} APIs、@code{import} 或 @code{import-from} 陳述式，或內建的 @code{__import__()}）載入子模組時，會將子模組物件繫結到父模組的命名空間中。例如，如果套件 @code{spam} 有一個子模組 @code{foo}，則在引入 @code{spam.foo} 之後，@code{spam} 將擁有一個名為 @code{foo} 的屬性，該屬性繫結到子模組。我們假設你有以下的目錄結構：

@example
spam/
    __init__.py
    foo.py
@end example

並且 @code{spam/__init__.py} 中包含以下程式碼：

@example
from .foo import Foo
@end example

那麼執行以下程式碼會將 @code{foo} 和 @code{Foo} 的名稱繫結到 @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 模組規格,__path__ attributes on modules,子模組,載入
@anchor{reference/import id4}@anchor{2300}@anchor{reference/import module-specs}@anchor{2218}
@subsubsection 模組規格


引入機制在引入過程中使用有關每個模組的各種資訊，尤其是在載入之前。大多數資訊對所有模組來說都是通用的。模組規格的目的是以每個模組為基礎封裝這些與引入相關的資訊。

在引入過程中使用規格允許在引入系統的各個組件之間傳遞狀態，例如在建立模組規格的尋檢器和執行該規格的載入器之間傳遞。最重要的是，這允許引入機制執行載入的模板操作，而在沒有模組規格的情況下，這些操作則是載入器的責任。

模組的規格以 @ref{2216,,module.__spec__} 的形式公開。適當地設定 @code{__spec__} 同樣適用於@ref{2301,,在直譯器啟動期間初始化的模組}。唯一的例外是 @code{__main__}，其中 @code{__spec__} 會@ref{2302,,在某些情況下被設定成 None}。

有關模組規格內容的詳細資訊，請參閱 @ref{2130,,ModuleSpec}。


在 3.4 版被加入.


@node __path__ attributes on modules,Module reprs,模組規格,載入
@anchor{reference/import package-path-rules}@anchor{2219}@anchor{reference/import path-attributes-on-modules}@anchor{2303}
@subsubsection __path__ attributes on modules


The @ref{1f1b,,__path__} attribute should be a (possibly empty)
@ref{70f,,sequence} of strings enumerating the locations where the package's
submodules will be found. By definition, if a module has a @code{__path__}
attribute, it is a @ref{233,,package}.

A package's @ref{1f1b,,__path__} attribute is used during imports of its
subpackages.
Within the import machinery, it functions much the same as @ref{3e2,,sys.path},
i.e. providing a list of locations to search for modules during import.
However, @code{__path__} is typically much more constrained than
@code{sys.path}.

The same rules used for @ref{3e2,,sys.path} also apply to a package's
@code{__path__}. @ref{121f,,sys.path_hooks} (described below) are
consulted when traversing a package's @code{__path__}.

A package's @code{__init__.py} file may set or alter the package's
@ref{1f1b,,__path__}
attribute, and this was typically the way namespace packages were implemented
prior to 
@geindex Python Enhancement Proposals; PEP 420
PEP 420@footnote{https://peps.python.org/pep-0420/}.  With the adoption of 
@geindex Python Enhancement Proposals; PEP 420
PEP 420@footnote{https://peps.python.org/pep-0420/}, namespace packages no
longer need to supply @code{__init__.py} files containing only @code{__path__}
manipulation code; the import machinery automatically sets @code{__path__}
correctly for the namespace package.

@node Module reprs,Cached bytecode invalidation,__path__ attributes on modules,載入
@anchor{reference/import module-reprs}@anchor{2304}
@subsubsection Module reprs


By default, all modules have a usable repr, however depending on the
attributes set above, and in the module's spec, you can more explicitly
control the repr of module objects.

If the module has a spec (@code{__spec__}), the import machinery will try
to generate a repr from it.  If that fails or there is no spec, the import
system will craft a default repr using whatever information is available
on the module.  It will try to use the @code{module.__name__},
@code{module.__file__}, and @code{module.__loader__} as input into the repr,
with defaults for whatever information is missing.

Here are the exact rules used:


@itemize *

@item 
If the module has a @code{__spec__} attribute, the information in the spec
is used to generate the repr.  The "name", "loader", "origin", and
"has_location" attributes are consulted.

@item 
If the module has a @code{__file__} attribute, this is used as part of the
module's repr.

@item 
If the module has no @code{__file__} but does have a @code{__loader__} that is not
@code{None}, then the loader's repr is used as part of the module's repr.

@item 
Otherwise, just use the module's @code{__name__} in the repr.
@end itemize


在 3.12 版的變更: Use of @code{module_repr()}, having been deprecated since Python 3.4, was
removed in Python 3.12 and is no longer called during the resolution of a
module's repr.


@node Cached bytecode invalidation,,Module reprs,載入
@anchor{reference/import cached-bytecode-invalidation}@anchor{2305}@anchor{reference/import pyc-invalidation}@anchor{7fb}
@subsubsection Cached bytecode invalidation


Before Python loads cached bytecode from a @code{.pyc} file, it checks whether the
cache is up-to-date with the source @code{.py} file. By default, Python does this
by storing the source's last-modified timestamp and size in the cache file when
writing it. At runtime, the import system then validates the cache file by
checking the stored metadata in the cache file against the source's
metadata.

Python also supports "hash-based" cache files, which store a hash of the source
file's contents rather than its metadata. There are two variants of hash-based
@code{.pyc} files: checked and unchecked. For checked hash-based @code{.pyc} files,
Python validates the cache file by hashing the source file and comparing the
resulting hash with the hash in the cache file. If a checked hash-based cache
file is found to be invalid, Python regenerates it and writes a new checked
hash-based cache file. For unchecked hash-based @code{.pyc} files, Python simply
assumes the cache file is valid if it exists. Hash-based @code{.pyc} files
validation behavior may be overridden with the @ref{1fe8,,--check-hash-based-pycs}
flag.


在 3.7 版的變更: Added hash-based @code{.pyc} files. Previously, Python only supported
timestamp-based invalidation of bytecode caches.


@node The Path Based Finder,Replacing the standard import system,載入,模組引入系統
@anchor{reference/import the-path-based-finder}@anchor{2306}
@subsection The Path Based Finder


@geindex path based finder（基於路徑的搜尋器）

As mentioned previously, Python comes with several default meta path finders.
One of these, called the @ref{22fc,,path based finder}
(@ref{121e,,PathFinder}), searches an @ref{22f9,,import path},
which contains a list of @ref{2307,,path entries}.  Each path
entry names a location to search for modules.

The path based finder itself doesn't know how to import anything. Instead, it
traverses the individual path entries, associating each of them with a
path entry finder that knows how to handle that particular kind of path.

The default set of path entry finders implement all the semantics for finding
modules on the file system, handling special file types such as Python source
code (@code{.py} files), Python byte code (@code{.pyc} files) and
shared libraries (e.g. @code{.so} files). When supported by the @ref{138,,zipimport}
module in the standard library, the default path entry finders also handle
loading all of these file types (other than shared libraries) from zipfiles.

Path entries need not be limited to file system locations.  They can refer to
URLs, database queries, or any other location that can be specified as a
string.

The path based finder provides additional hooks and protocols so that you
can extend and customize the types of searchable path entries.  For example,
if you wanted to support path entries as network URLs, you could write a hook
that implements HTTP semantics to find modules on the web.  This hook (a
callable) would return a @ref{126c,,path entry finder} supporting the protocol
described below, which was then used to get a loader for the module from the
web.

A word of warning: this section and the previous both use the term `finder',
distinguishing between them by using the terms @ref{126b,,meta path finder} and
@ref{126c,,path entry finder}.  These two types of finders are very similar,
support similar protocols, and function in similar ways during the import
process, but it's important to keep in mind that they are subtly different.
In particular, meta path finders operate at the beginning of the import
process, as keyed off the @ref{f22,,sys.meta_path} traversal.

By contrast, path entry finders are in a sense an implementation detail
of the path based finder, and in fact, if the path based finder were to be
removed from @ref{f22,,sys.meta_path}, none of the path entry finder semantics
would be invoked.

@menu
* Path entry finders:: 
* Path entry finder protocol:: 

@end menu

@node Path entry finders,Path entry finder protocol,,The Path Based Finder
@anchor{reference/import path-entry-finders}@anchor{2308}
@subsubsection Path entry finders


@geindex sys.path
@geindex sys.path_hooks
@geindex sys.path_importer_cache
@geindex PYTHONPATH

The @ref{22fc,,path based finder} is responsible for finding and loading
Python modules and packages whose location is specified with a string
@ref{2307,,path entry}.  Most path entries name locations in the file system,
but they need not be limited to this.

As a meta path finder, the @ref{22fc,,path based finder} implements the
@ref{a61,,find_spec()} protocol previously
described, however it exposes additional hooks that can be used to
customize how modules are found and loaded from the @ref{22f9,,import path}.

Three variables are used by the @ref{22fc,,path based finder}, @ref{3e2,,sys.path},
@ref{121f,,sys.path_hooks} and @ref{7f3,,sys.path_importer_cache}.  The @code{__path__}
attributes on package objects are also used.  These provide additional ways
that the import machinery can be customized.

@ref{3e2,,sys.path} contains a list of strings providing search locations for
modules and packages.  It is initialized from the 
@geindex PYTHONPATH
@geindex 環境變數; PYTHONPATH
@ref{1218,,PYTHONPATH}
environment variable and various other installation- and
implementation-specific defaults.  Entries in @ref{3e2,,sys.path} can name
directories on the file system, zip files, and potentially other "locations"
(see the @ref{cc,,site} module) that should be searched for modules, such as
URLs, or database queries.  Only strings should be present on
@ref{3e2,,sys.path}; all other data types are ignored.

The @ref{22fc,,path based finder} is a @ref{126b,,meta path finder}, so the import
machinery begins the @ref{22f9,,import path} search by calling the path
based finder's @ref{120c,,find_spec()} method as
described previously.  When the @code{path} argument to
@ref{120c,,find_spec()} is given, it will be a
list of string paths to traverse - typically a package's @code{__path__}
attribute for an import within that package.  If the @code{path} argument is
@code{None}, this indicates a top level import and @ref{3e2,,sys.path} is used.

The path based finder iterates over every entry in the search path, and
for each of these, looks for an appropriate @ref{126c,,path entry finder}
(@ref{a68,,PathEntryFinder}) for the
path entry.  Because this can be an expensive operation (e.g. there may be
@code{stat()} call overheads for this search), the path based finder maintains
a cache mapping path entries to path entry finders.  This cache is maintained
in @ref{7f3,,sys.path_importer_cache} (despite the name, this cache actually
stores finder objects rather than being limited to @ref{22f8,,importer} objects).
In this way, the expensive search for a particular @ref{2307,,path entry}
location's @ref{126c,,path entry finder} need only be done once.  User code is
free to remove cache entries from @ref{7f3,,sys.path_importer_cache} forcing
the path based finder to perform the path entry search again.

If the path entry is not present in the cache, the path based finder iterates
over every callable in @ref{121f,,sys.path_hooks}.  Each of the @ref{2309,,path entry hooks} in this list is called with a single argument, the
path entry to be searched.  This callable may either return a @ref{126c,,path entry finder} that can handle the path entry, or it may raise
@ref{653,,ImportError}.  An @ref{653,,ImportError} is used by the path based finder to
signal that the hook cannot find a @ref{126c,,path entry finder}
for that @ref{2307,,path entry}.  The
exception is ignored and @ref{22f9,,import path} iteration continues.  The hook
should expect either a string or bytes object; the encoding of bytes objects
is up to the hook (e.g. it may be a file system encoding, UTF-8, or something
else), and if the hook cannot decode the argument, it should raise
@ref{653,,ImportError}.

If @ref{121f,,sys.path_hooks} iteration ends with no @ref{126c,,path entry finder}
being returned, then the path based finder's
@ref{120c,,find_spec()} method will store @code{None}
in @ref{7f3,,sys.path_importer_cache} (to indicate that there is no finder for
this path entry) and return @code{None}, indicating that this
@ref{126b,,meta path finder} could not find the module.

If a @ref{126c,,path entry finder} `is' returned by one of the @ref{2309,,path entry hook} callables on @ref{121f,,sys.path_hooks}, then the following protocol is used
to ask the finder for a module spec, which is then used when loading the
module.

The current working directory -- denoted by an empty string -- is handled
slightly differently from other entries on @ref{3e2,,sys.path}. First, if the
current working directory cannot be determined or is found not to exist, no
value is stored in @ref{7f3,,sys.path_importer_cache}. Second, the value for the
current working directory is looked up fresh for each module lookup. Third,
the path used for @ref{7f3,,sys.path_importer_cache} and returned by
@ref{120c,,importlib.machinery.PathFinder.find_spec()} will be the actual current
working directory and not the empty string.

@node Path entry finder protocol,,Path entry finders,The Path Based Finder
@anchor{reference/import path-entry-finder-protocol}@anchor{230a}
@subsubsection Path entry finder protocol


In order to support imports of modules and initialized packages and also to
contribute portions to namespace packages, path entry finders must implement
the @ref{a65,,find_spec()} method.

@ref{a65,,find_spec()} takes two arguments: the
fully qualified name of the module being imported, and the (optional) target
module.  @code{find_spec()} returns a fully populated spec for the module.
This spec will always have "loader" set (with one exception).

To indicate to the import machinery that the spec represents a namespace
@ref{22f3,,portion}, the path entry finder sets @code{submodule_search_locations} to
a list containing the portion.


在 3.4 版的變更: @ref{a65,,find_spec()} replaced
@code{find_loader()} and
@code{find_module()}, both of which
are now deprecated, but will be used if @code{find_spec()} is not defined.

Older path entry finders may implement one of these two deprecated methods
instead of @code{find_spec()}.  The methods are still respected for the
sake of backward compatibility.  However, if @code{find_spec()} is
implemented on the path entry finder, the legacy methods are ignored.

@code{find_loader()} takes one argument, the
fully qualified name of the module being imported.  @code{find_loader()}
returns a 2-tuple where the first item is the loader and the second item
is a namespace @ref{22f3,,portion}.

For backwards compatibility with other implementations of the import
protocol, many path entry finders also support the same,
traditional @code{find_module()} method that meta path finders support.
However path entry finder @code{find_module()} methods are never called
with a @code{path} argument (they are expected to record the appropriate
path information from the initial call to the path hook).

The @code{find_module()} method on path entry finders is deprecated,
as it does not allow the path entry finder to contribute portions to
namespace packages.  If both @code{find_loader()} and @code{find_module()}
exist on a path entry finder, the import system will always call
@code{find_loader()} in preference to @code{find_module()}.



在 3.10 版的變更: Calls to @code{find_module()} and
@code{find_loader()} by the import
system will raise @ref{717,,ImportWarning}.



在 3.12 版的變更: @code{find_module()} 和 @code{find_loader()} 已被移除。


@node Replacing the standard import system,Package Relative Imports,The Path Based Finder,模組引入系統
@anchor{reference/import replacing-the-standard-import-system}@anchor{230b}
@subsection Replacing the standard import system


The most reliable mechanism for replacing the entire import system is to
delete the default contents of @ref{f22,,sys.meta_path}, replacing them
entirely with a custom 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{ac8,,__import__()} function may be sufficient. This technique
may also be employed at the module level to only alter the behaviour of
import statements within that module.

To selectively prevent the import of some modules from a hook early on the
meta path (rather than disabling the standard import system entirely),
it is sufficient to raise @ref{d35,,ModuleNotFoundError} directly from
@ref{a61,,find_spec()} instead of returning
@code{None}. The latter indicates that the meta path search should continue,
while raising an exception terminates it immediately.

@node Package Relative Imports,Special considerations for __main__,Replacing the standard import system,模組引入系統
@anchor{reference/import package-relative-imports}@anchor{230c}@anchor{reference/import relativeimports}@anchor{230d}
@subsection Package Relative Imports


Relative imports use leading dots. A single leading dot indicates a relative
import, starting with the current package. Two or more leading dots indicate a
relative import to the parent(s) of the current package, one level per dot
after the first. For example, given the following package layout:

@example
package/
    __init__.py
    subpackage1/
        __init__.py
        moduleX.py
        moduleY.py
    subpackage2/
        __init__.py
        moduleZ.py
    moduleA.py
@end example

In either @code{subpackage1/moduleX.py} or @code{subpackage1/__init__.py},
the following are valid relative imports:

@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

Absolute imports may use either the @code{import <>} or @code{from <> import <>}
syntax, but relative imports may only use the second form; the reason
for this is that:

@example
import XXX.YYY.ZZZ
@end example

should expose @code{XXX.YYY.ZZZ} as a usable expression, but .moduleY is
not a valid expression.

@node Special considerations for __main__,References,Package Relative Imports,模組引入系統
@anchor{reference/import import-dunder-main}@anchor{230e}@anchor{reference/import special-considerations-for-main}@anchor{230f}
@subsection Special considerations for __main__


The @ref{1,,__main__} module is a special case relative to Python's import
system.  As noted @ref{2301,,elsewhere}, the @code{__main__} module
is directly initialized at interpreter startup, much like @ref{df,,sys} and
@ref{13,,builtins}.  However, unlike those two, it doesn't strictly
qualify as a built-in module.  This is because the manner in which
@code{__main__} is initialized depends on the flags and other options with
which the interpreter is invoked.

@menu
* __main__.__spec__: __main__ __spec__. 

@end menu

@node __main__ __spec__,,,Special considerations for __main__
@anchor{reference/import id5}@anchor{2310}@anchor{reference/import main-spec}@anchor{2302}
@subsubsection __main__.__spec__


Depending on how @ref{1,,__main__} is initialized, @code{__main__.__spec__}
gets set appropriately or to @code{None}.

When Python is started with the @ref{23c,,-m} option, @code{__spec__} is set
to the module spec of the corresponding module or package. @code{__spec__} is
also populated when the @code{__main__} module is loaded as part of executing a
directory, zipfile or other @ref{3e2,,sys.path} entry.

In @ref{1fe1,,the remaining cases}
@code{__main__.__spec__} is set to @code{None}, as the code used to populate the
@ref{1,,__main__} does not correspond directly with an importable module:


@itemize -

@item 
interactive prompt

@item 
@ref{1a8,,-c} 選項

@item 
running from stdin

@item 
running directly from a source or bytecode file
@end itemize

Note that @code{__main__.__spec__} is always @code{None} in the last case,
`even if' the file could technically be imported directly as a module
instead. Use the @ref{23c,,-m} switch if valid module metadata is desired
in @ref{1,,__main__}.

Note also that even when @code{__main__} corresponds with an importable module
and @code{__main__.__spec__} is set accordingly, they're still considered
`distinct' modules. This is due to the fact that blocks guarded by
@code{if __name__ == "__main__":} checks only execute when the module is used
to populate the @code{__main__} namespace, and not during normal import.

@node References,,Special considerations for __main__,模組引入系統
@anchor{reference/import references}@anchor{2311}
@subsection References


The import machinery has evolved considerably since Python's early days.  The
original specification for packages@footnote{https://www.python.org/doc/essays/packages/} is still available to read,
although some details have changed since the writing of that document.

The original specification for @ref{f22,,sys.meta_path} was 
@geindex Python Enhancement Proposals; PEP 302
PEP 302@footnote{https://peps.python.org/pep-0302/}, with
subsequent extension in 
@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/} introduced @ref{2b2,,namespace packages} for
Python 3.3.  
@geindex Python Enhancement Proposals; PEP 420
PEP 420@footnote{https://peps.python.org/pep-0420/} also introduced the @code{find_loader()} protocol as an
alternative to @code{find_module()}.

@geindex Python Enhancement Proposals; PEP 366
PEP 366@footnote{https://peps.python.org/pep-0366/} describes the addition of the @code{__package__} attribute for
explicit relative imports in main modules.

@geindex Python Enhancement Proposals; PEP 328
PEP 328@footnote{https://peps.python.org/pep-0328/} introduced absolute and explicit relative imports and initially
proposed @code{__name__} for semantics 
@geindex Python Enhancement Proposals; PEP 366
PEP 366@footnote{https://peps.python.org/pep-0366/} would eventually specify for
@code{__package__}.

@geindex Python Enhancement Proposals; PEP 338
PEP 338@footnote{https://peps.python.org/pep-0338/} defines executing modules as scripts.

@geindex Python Enhancement Proposals; PEP 451
PEP 451@footnote{https://peps.python.org/pep-0451/} adds the encapsulation of per-module import state in spec
objects.  It also off-loads most of the boilerplate responsibilities of
loaders back onto the import machinery.  These changes allow the
deprecation of several APIs in the import system and also addition of new
methods to finders and 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 運算式,簡單陳述式,模組引入系統,Python 語言參考手冊
@anchor{reference/expressions doc}@anchor{2312}@anchor{reference/expressions expressions}@anchor{21dc}@anchor{reference/expressions id1}@anchor{2313}@anchor{reference/expressions translation-repo}@anchor{2314}
@section 運算式


@geindex expression
@geindex BNF

This chapter explains the meaning of the elements of expressions in Python.

`Syntax Notes:' In this and the following chapters, extended BNF 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{2315}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,,運算式
@anchor{reference/expressions arithmetic-conversions}@anchor{2316}@anchor{reference/expressions conversions}@anchor{2317}
@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 types works as follows:


@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

Some additional rules apply for certain operators (e.g., a string as a left
argument to the '%' operator).  Extensions must define their own conversion
behavior.

@node Atoms,Primaries,Arithmetic conversions,運算式
@anchor{reference/expressions atoms}@anchor{2318}@anchor{reference/expressions id2}@anchor{2319}
@subsection Atoms


@geindex atom

Atoms are the most basic elements of expressions.  The simplest atoms are
identifiers or literals.  Forms enclosed in parentheses, brackets or braces are
also categorized syntactically as atoms.  The syntax for atoms is:

@example
@anchor{reference/expressions grammar-token-python-grammar-atom}@anchor{231a}atom:      @ref{2185,,identifier} | @ref{231b,,literal} | @ref{231c,,enclosure}
@anchor{reference/expressions grammar-token-python-grammar-enclosure}@anchor{231c}enclosure: @ref{231d,,parenth_form} | @ref{231e,,list_display} | @ref{231f,,dict_display} | @ref{2320,,set_display}
           | @ref{2321,,generator_expression} | @ref{2322,,yield_atom}
@end example

@menu
* Identifiers (Names): Identifiers Names. 
* Literals: Literals<2>. 
* 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 Identifiers Names,Literals<2>,,Atoms
@anchor{reference/expressions atom-identifiers}@anchor{218a}@anchor{reference/expressions identifiers-names}@anchor{2323}
@subsubsection Identifiers (Names)


@geindex name（名稱）
@geindex identifier

An identifier occurring as an atom is a name.  See section @ref{2164,,Names (identifiers and keywords)}
for lexical definition and section @ref{21f8,,Naming and binding} 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{450,,NameError}
exception.

@geindex name（名稱）;mangling
@geindex private;names
@anchor{reference/expressions private-name-mangling}@anchor{1f6a}
@menu
* Private name mangling:: 

@end menu

@node Private name mangling,,,Identifiers Names
@anchor{reference/expressions id3}@anchor{2324}
@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{14d8,,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{1261,,__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<2>,Parenthesized forms,Identifiers Names,Atoms
@anchor{reference/expressions atom-literals}@anchor{2325}@anchor{reference/expressions literals}@anchor{2326}
@subsubsection Literals


@geindex literal

Python supports string and bytes literals and various numeric literals:

@example
@anchor{reference/expressions grammar-token-python-grammar-literal}@anchor{231b}literal: @ref{2327,,strings} | @ref{21bb,,NUMBER}
@end example

Evaluation of a literal yields an object of the given type (string, bytes,
integer, floating-point number, complex number) with the given value.  The value
may be approximated in the case of floating-point and imaginary (complex)
literals.
See section @ref{218c,,Literals} for details.
See section @ref{21a3,,String literal concatenation} for details on @code{strings}.

@geindex immutable;data（資料）;type（型別）
@geindex immutable;object（物件）

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.

@menu
* String literal concatenation:: 

@end menu

@node String literal concatenation,,,Literals<2>
@anchor{reference/expressions string-concatenation}@anchor{21a3}@anchor{reference/expressions string-literal-concatenation}@anchor{2328}
@subsubsection String literal concatenation


Multiple adjacent string or bytes literals (delimited by whitespace), possibly
using different quoting conventions, are allowed, and their meaning is the same
as their concatenation:

@example
>>> "hello" 'world'
"helloworld"
@end example

Formally:

@example
@anchor{reference/expressions grammar-token-python-grammar-strings}@anchor{2327}strings: ( @ref{2194,,STRING} | fstring)+ | tstring+
@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)   # 不是：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

@node Parenthesized forms,Displays for lists sets and dictionaries,Literals<2>,Atoms
@anchor{reference/expressions parenthesized}@anchor{2329}@anchor{reference/expressions parenthesized-forms}@anchor{232a}
@subsubsection Parenthesized forms


@geindex parenthesized form
@geindex () （圓括號）;tuple display

A parenthesized form is an optional expression list enclosed in parentheses:

@example
@anchor{reference/expressions grammar-token-python-grammar-parenth_form}@anchor{231d}parenth_form: "(" [@ref{232b,,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{} （逗號）

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{7e5}@anchor{reference/expressions displays-for-lists-sets-and-dictionaries}@anchor{232c}
@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;於 comprehensions（綜合運算）
@geindex if;於 comprehensions（綜合運算）
@geindex async for;於 comprehensions（綜合運算）

Common syntax elements for comprehensions are:

@example
@anchor{reference/expressions grammar-token-python-grammar-comprehension}@anchor{232d}comprehension: @ref{22dd,,assignment_expression} @ref{232e,,comp_for}
@anchor{reference/expressions grammar-token-python-grammar-comp_for}@anchor{232e}comp_for:      ["async"] "for" @ref{232f,,target_list} "in" @ref{2330,,or_test} [@ref{2331,,comp_iter}]
@anchor{reference/expressions grammar-token-python-grammar-comp_iter}@anchor{2331}comp_iter:     @ref{232e,,comp_for} | @ref{2332,,comp_if}
@anchor{reference/expressions grammar-token-python-grammar-comp_if}@anchor{2332}comp_if:       "if" @ref{2330,,or_test} [@ref{2331,,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.

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;於 comprehensions（綜合運算）

Since Python 3.6, in an @ref{7e6,,async def} function, an @code{async for}
clause may be used to iterate over a @ref{4c2,,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{18d,,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/}.


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


@node List displays,Set displays,Displays for lists sets and dictionaries,Atoms
@anchor{reference/expressions list-displays}@anchor{2333}@anchor{reference/expressions lists}@anchor{2334}
@subsubsection List displays


@geindex list（串列）;display
@geindex list（串列）;comprehensions
@geindex empty;list（串列）
@geindex object（物件）;list（串列）
@geindex [] （方括號）;list expression（串列運算式）
@geindex @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{231e}list_display: "[" [@ref{2335,,flexible_expression_list} | @ref{232d,,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{2336}@anchor{reference/expressions set-displays}@anchor{2337}
@subsubsection Set displays


@geindex set（集合）;display
@geindex set（集合）;comprehensions
@geindex object（物件）;set（集合）
@geindex @{@} （花括號）;set expression（集合運算式）
@geindex @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{2320}set_display: "@{" (@ref{2335,,flexible_expression_list} | @ref{232d,,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{f7a}@anchor{reference/expressions dictionary-displays}@anchor{2338}
@subsubsection Dictionary displays


@geindex dictionary（字典）;display
@geindex dictionary（字典）;comprehensions
@geindex key（鍵）
@geindex value（值）
@geindex key/value pair（鍵/值對）
@geindex object（物件）;dictionary（字典）
@geindex @{@} （花括號）;dictionary expression（字典運算式）
@geindex ; （冒號）;於字典運算式
@geindex @comma{} （逗號）;於字典顯示

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{231f}dict_display:       "@{" [@ref{2339,,dict_item_list} | @ref{233a,,dict_comprehension}] "@}"
@anchor{reference/expressions grammar-token-python-grammar-dict_item_list}@anchor{2339}dict_item_list:     @ref{233b,,dict_item} ("," @ref{233b,,dict_item})* [","]
@anchor{reference/expressions grammar-token-python-grammar-dict_item}@anchor{233b}dict_item:          @ref{182,,expression} ":" @ref{182,,expression} | "**" @ref{21b5,,or_expr}
@anchor{reference/expressions grammar-token-python-grammar-dict_comprehension}@anchor{233a}dict_comprehension: @ref{182,,expression} ":" @ref{182,,expression} @ref{232e,,comp_for}
@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 **;於字典顯示

A double asterisk @code{**} denotes `dictionary unpacking'.
Its operand must be a @ref{13bc,,mapping}.  Each mapping item is added
to the new dictionary.  Later values replace values already set by
earlier dict items and earlier dictionary unpackings.


在 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, in contrast to list and set comprehensions, needs 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.

@geindex immutable;object（物件）
@geindex hashable（可雜湊）

Restrictions on the types of the key values are listed earlier in section
@ref{21e4,,標準型別階層}.  (To summarize, the key type should be @ref{81d,,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/}.


@node Generator expressions,Yield expressions,Dictionary displays,Atoms
@anchor{reference/expressions generator-expressions}@anchor{233c}@anchor{reference/expressions genexpr}@anchor{233d}
@subsubsection Generator expressions


@geindex generator（產生器）;expression
@geindex object（物件）;generator（產生器）
@geindex () （圓括號）;generator expression（產生器運算式）

A generator expression is a compact generator notation in parentheses:

@example
@anchor{reference/expressions grammar-token-python-grammar-generator_expression}@anchor{2321}generator_expression: "(" @ref{182,,expression} @ref{232e,,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{1f75,,__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{4c3,,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{f78,,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{18d,,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{f72,,Asynchronous Iterators}).


在 3.6 版被加入: Asynchronous generator expressions were introduced.



在 3.7 版的變更: Prior to Python 3.7, asynchronous generator expressions could
only appear in @ref{7e6,,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{233e}@anchor{reference/expressions yieldexpr}@anchor{233f}
@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{2322}yield_atom:       "(" @ref{21b6,,yield_expression} ")"
@anchor{reference/expressions grammar-token-python-grammar-yield_from}@anchor{2340}yield_from:       "yield" "from" @ref{182,,expression}
@anchor{reference/expressions grammar-token-python-grammar-yield_expression}@anchor{21b6}yield_expression: "yield" @ref{2341,,yield_list} | @ref{2340,,yield_from}
@end example

The yield expression is used when defining a @ref{125c,,generator} function
or an @ref{2342,,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{7e6,,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{2343,,非同步產生器函式}.

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{2341,,yield_list}
to the generator's caller,
or @code{None} if @ref{2341,,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{1f75,,__next__()} is used
(typically via either a @ref{348,,for} or the @ref{9d1,,next()} builtin) then the
result is @ref{87e,,None}.  Otherwise, if @ref{22c9,,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{8f0,,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{19b7,,close()} method will be called,
allowing any pending @ref{1b0,,finally} clauses to execute.

@geindex from;yield from expression（yield from 運算式）

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{22c9,,send()} and any exceptions passed in with
@ref{715,,throw()} are passed to the underlying iterator if it has the
appropriate methods.  If this is not the case, then @ref{22c9,,send()}
will raise @ref{5e8,,AttributeError} or @ref{198,,TypeError}, while
@ref{715,,throw()} will just raise the passed in exception immediately.

When the underlying iterator is complete, the @ref{22c6,,value}
attribute of the raised @ref{df0,,StopIteration} instance becomes the value of
the yield expression. It can be either set explicitly when raising
@ref{df0,,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{bb9,,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{2340,,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:: 
* 模組: 模組<3>. 
* 非同步產生器函式: 非同步產生器函式<2>. 
* Asynchronous generator-iterator methods:: 

@end menu

@node Generator-iterator methods,模組<3>,,Yield expressions
@anchor{reference/expressions generator-iterator-methods}@anchor{2344}@anchor{reference/expressions generator-methods}@anchor{22c7}
@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{2eb,,ValueError} exception.

@geindex exception;StopIteration

@geindex __next__() (generator 的方法)
@anchor{reference/expressions generator __next__}@anchor{1f75}
@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
@ref{1f75,,__next__()} method, the current yield expression always
evaluates to @ref{87e,,None}.  The execution then continues to the next yield
expression, where the generator is suspended again, and the value of the
@ref{2341,,yield_list} is returned to @ref{1f75,,__next__()}'s
caller.  If the generator exits without yielding another value, a
@ref{df0,,StopIteration} exception is raised.

This method is normally called implicitly, e.g. by a @ref{348,,for} loop, or
by the built-in @ref{9d1,,next()} function.
@end deffn

@geindex send() (generator 的方法)
@anchor{reference/expressions generator send}@anchor{22c9}
@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
@ref{22c9,,send()} method returns the next value yielded by the generator, or
raises @ref{df0,,StopIteration} if the generator exits without yielding another
value.  When @ref{22c9,,send()} is called to start the generator, it must be called
with @ref{87e,,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{715}
@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{df0,,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{7fc,,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{14c7,,__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{19b7}
@deffn {方法} generator.close ()

Raises a @ref{15bf,,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 @ref{19b7,,close()}.  If the generator function
is already closed, or raises @ref{15bf,,GeneratorExit} (by not catching the
exception), @ref{19b7,,close()} returns @ref{87e,,None}.  If the generator yields a
value, a @ref{244,,RuntimeError} is raised.  If the generator raises any other
exception, it is propagated to the caller.  If the generator has already
exited due to an exception or normal exit, @ref{19b7,,close()} returns
@ref{87e,,None} and has no other effect.


在 3.13 版的變更: If a generator returns a value upon being closed, the value is returned
by @ref{19b7,,close()}.

@end deffn

@geindex yield;範例

@node 模組<3>,非同步產生器函式<2>,Generator-iterator methods,Yield expressions
@anchor{reference/expressions examples}@anchor{2345}
@subsubsection 模組


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{1235,,PEP 380; Syntax for Delegating to a Subgenerator} in "What's New in
Python."

@node 非同步產生器函式<2>,Asynchronous generator-iterator methods,模組<3>,Yield expressions
@anchor{reference/expressions asynchronous-generator-functions}@anchor{2343}@anchor{reference/expressions id4}@anchor{2346}
@subsubsection 非同步產生器函式


The presence of a yield expression in a function or method defined using
@ref{7e6,,async def} further defines the function as an
@ref{2342,,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{c98,,async for} statement in a coroutine function analogously to
how a generator object would be used in a @ref{348,,for} statement.

Calling one of the asynchronous generator's methods returns an @ref{4c4,,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{2341,,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{2347,,__anext__()} is used then the result is @ref{87e,,None}. Otherwise, if
@ref{acd,,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{17f,,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{acc,,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{8f0,,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{1b0,,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{acc,,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{acc,,aclose()} and executes the coroutine.
This  `finalizer' may be registered by calling @ref{18f4,,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/3.14/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,,非同步產生器函式<2>,Yield expressions
@anchor{reference/expressions asynchronous-generator-iterator-methods}@anchor{2348}@anchor{reference/expressions asynchronous-generator-methods}@anchor{2349}
@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{2347}
@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 @ref{2347,,__anext__()}
method, the current yield expression always evaluates to @ref{87e,,None} in the
returned awaitable, which when run will continue to the next yield
expression. The value of the @ref{2341,,yield_list} of the
yield expression is the value of the @ref{df0,,StopIteration} exception raised by
the completing coroutine.  If the asynchronous generator exits without
yielding another value, the awaitable instead raises a
@ref{1cd7,,StopAsyncIteration} exception, signalling that the asynchronous
iteration has completed.

This method is normally called implicitly by a @ref{c98,,async for} loop.
@end deffn

@geindex asend() (agen 的方法)
@anchor{reference/expressions agen asend}@anchor{acd}
@deffn {方法} async agen.asend (value)

Returns an awaitable which when run resumes the execution of the
asynchronous generator. As with the @ref{22c9,,send()} method for a
generator, this "sends" a value into the asynchronous generator function,
and the `value' argument becomes the result of the current yield expression.
The awaitable returned by the @ref{acd,,asend()} method will return the next
value yielded by the generator as the value of the raised
@ref{df0,,StopIteration}, or raises @ref{1cd7,,StopAsyncIteration} if the
asynchronous generator exits without yielding another value.  When
@ref{acd,,asend()} is called to start the asynchronous
generator, it must be called with @ref{87e,,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{716}
@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{df0,,StopIteration} exception.  If the asynchronous generator exits
without yielding another value, a @ref{1cd7,,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{acc}
@deffn {方法} async agen.aclose ()

Returns an awaitable that when run will throw a @ref{15bf,,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 @ref{15bf,,GeneratorExit} (by not catching the exception),
then the returned awaitable will raise a @ref{df0,,StopIteration} exception.
Any further awaitables returned by subsequent calls to the asynchronous
generator will raise a @ref{1cd7,,StopAsyncIteration} exception.  If the
asynchronous generator yields a value, a @ref{244,,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 @ref{acc,,aclose()} will return an awaitable that does nothing.
@end deffn

@node Primaries,Await expression,Atoms,運算式
@anchor{reference/expressions id5}@anchor{234a}@anchor{reference/expressions primaries}@anchor{234b}
@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{234c}primary: @ref{231a,,atom} | @ref{234d,,attributeref} | @ref{234e,,subscription} | @ref{234f,,slicing} | @ref{2350,,call}
@end example

@menu
* Attribute references:: 
* Subscriptions:: 
* Slicings:: 
* Calls:: 

@end menu

@node Attribute references,Subscriptions,,Primaries
@anchor{reference/expressions attribute-references}@anchor{2351}@anchor{reference/expressions id6}@anchor{2352}
@subsubsection Attribute references


@geindex attribute（屬性）;reference（參照）
@geindex . （點）;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{234d}attributeref: @ref{234c,,primary} "." @ref{2185,,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{dc6,,__getattribute__()} method or the @ref{6f3,,__getattr__()}
method.  The @code{__getattribute__()} method is called first and either
returns a value or raises @ref{5e8,,AttributeError} if the attribute is not
available.

If an @ref{5e8,,AttributeError} is raised and the object has a @code{__getattr__()}
method, that method is called as a fallback.

@node Subscriptions,Slicings,Attribute references,Primaries
@anchor{reference/expressions id7}@anchor{2353}@anchor{reference/expressions subscriptions}@anchor{2280}
@subsubsection Subscriptions


@geindex subscription（下標）
@geindex [] （方括號）;subscription（下標）

@geindex object（物件）;sequence（序列）
@geindex object（物件）;mapping（對映）
@geindex object（物件）;string（字串）
@geindex object（物件）;tuple
@geindex object（物件）;list（串列）
@geindex object（物件）;dictionary（字典）
@geindex sequence（序列）;item（項目）

The subscription of an instance of a @ref{2286,,container class}
will generally select an element from the container. The subscription of a
@ref{1a1,,generic class} will generally return a
@ref{8b8,,GenericAlias} object.

@example
@anchor{reference/expressions grammar-token-python-grammar-subscription}@anchor{234e}subscription: @ref{234c,,primary} "[" @ref{2335,,flexible_expression_list} "]"
@end example

When an object is subscripted, the interpreter will evaluate the primary and
the expression list.

The primary must evaluate to an object that supports subscription. An object
may support subscription through defining one or both of
@ref{582,,__getitem__()} and @ref{93b,,__class_getitem__()}. When the
primary is subscripted, the evaluated result of the expression list will be
passed to one of these methods. For more details on when @code{__class_getitem__}
is called instead of @code{__getitem__}, see @ref{227f,,__class_getitem__ versus __getitem__}.

If the expression list contains at least one comma, or if any of the expressions
are starred, the expression list will evaluate to a @ref{60c,,tuple} containing
the items of the expression list. Otherwise, the expression list will evaluate
to the value of the list's sole member.


在 3.11 版的變更: Expressions in an expression list may be starred. See 
@geindex Python Enhancement Proposals; PEP 646
PEP 646@footnote{https://peps.python.org/pep-0646/}.


For built-in objects, there are two types of objects that support subscription
via @ref{582,,__getitem__()}:


@enumerate 

@item 
Mappings. If the primary is a @ref{13bc,,mapping}, the expression list must
evaluate to an object whose value is one of the keys of the mapping, and the
subscription selects the value in the mapping that corresponds to that key.
An example of a builtin mapping class is the @ref{183,,dict} class.

@item 
Sequences. If the primary is a @ref{70f,,sequence}, the expression list must
evaluate to an @ref{19b,,int} or a @ref{68d,,slice} (as discussed in the
following section). Examples of builtin sequence classes include the
@ref{169,,str}, @ref{24d,,list} and @ref{60c,,tuple} classes.
@end enumerate

The formal syntax makes no special provision for negative indices in
@ref{70f,,sequences}. However, built-in sequences all provide a @ref{582,,__getitem__()}
method that interprets negative indices by adding the length of the sequence
to the index so that, for example, @code{x[-1]} selects the last item of @code{x}. The
resulting value must be a nonnegative integer less than the number of items in
the sequence, and the subscription selects the item whose index is that value
(counting from zero). Since the support for negative indices and slicing
occurs in the object's @ref{582,,__getitem__()} method, subclasses overriding
this method will need to explicitly add that support.

@geindex character（字元）
@geindex string（字串）;item（項目）

A @ref{169,,string} is a special kind of sequence whose items are
`characters'. A character is not a separate data type but a
string of exactly one character.

@node Slicings,Calls,Subscriptions,Primaries
@anchor{reference/expressions id8}@anchor{2354}@anchor{reference/expressions slicings}@anchor{2355}
@subsubsection Slicings


@geindex slicing（切片）
@geindex slice（切片）
@geindex ; （冒號）;slicing（切片）
@geindex @comma{} （逗號）;slicing（切片）

@geindex object（物件）;sequence（序列）
@geindex object（物件）;string（字串）
@geindex object（物件）;tuple
@geindex object（物件）;list（串列）

A slicing selects a range of items in a sequence object (e.g., a string, tuple
or list).  Slicings may be used as expressions or as targets in assignment or
@ref{1a62,,del} statements.  The syntax for a slicing:

@example
@anchor{reference/expressions grammar-token-python-grammar-slicing}@anchor{234f}slicing:      @ref{234c,,primary} "[" @ref{2356,,slice_list} "]"
@anchor{reference/expressions grammar-token-python-grammar-slice_list}@anchor{2356}slice_list:   @ref{2357,,slice_item} ("," @ref{2357,,slice_item})* [","]
@anchor{reference/expressions grammar-token-python-grammar-slice_item}@anchor{2357}slice_item:   @ref{182,,expression} | @ref{2358,,proper_slice}
@anchor{reference/expressions grammar-token-python-grammar-proper_slice}@anchor{2358}proper_slice: [@ref{2359,,lower_bound}] ":" [@ref{235a,,upper_bound}] [ ":" [@ref{235b,,stride}] ]
@anchor{reference/expressions grammar-token-python-grammar-lower_bound}@anchor{2359}lower_bound:  @ref{182,,expression}
@anchor{reference/expressions grammar-token-python-grammar-upper_bound}@anchor{235a}upper_bound:  @ref{182,,expression}
@anchor{reference/expressions grammar-token-python-grammar-stride}@anchor{235b}stride:       @ref{182,,expression}
@end example

There is ambiguity in the formal syntax here: anything that looks like an
expression list also looks like a slice list, so any subscription can be
interpreted as a slicing.  Rather than further complicating the syntax, this is
disambiguated by defining that in this case the interpretation as a subscription
takes priority over the interpretation as a slicing (this is the case if the
slice list contains no proper slice).

@geindex start（切片物件屬性）
@geindex stop（切片物件屬性）
@geindex step（切片物件屬性）

The semantics for a slicing are as follows.  The primary is indexed (using the
same @ref{582,,__getitem__()} method as
normal subscription) with a key that is constructed from the slice list, as
follows.  If the slice list contains at least one comma, the key is a tuple
containing the conversion of the slice items; otherwise, the conversion of the
lone slice item is the key.  The conversion of a slice item that is an
expression is that expression.  The conversion of a proper slice is a slice
object (see section @ref{21e4,,標準型別階層}) whose @ref{2256,,start},
@ref{2257,,stop} and @ref{2258,,step} attributes are the values of the
expressions given as lower bound, upper bound and stride, respectively,
substituting @code{None} for missing expressions.

@geindex object（物件）;callable（可呼叫物件）
@geindex call（呼叫）
@geindex argument（引數）;call semantics（呼叫語意）
@geindex () （圓括號）;call（呼叫）
@geindex @comma{} （逗號）;argument list（引數列表）
@geindex = （等號）;於函式呼叫中

@node Calls,,Slicings,Primaries
@anchor{reference/expressions calls}@anchor{f78}@anchor{reference/expressions id9}@anchor{235c}
@subsubsection Calls


A call calls a callable object (e.g., a @ref{235d,,function}) with a possibly empty
series of @ref{673,,arguments}:

@example
@anchor{reference/expressions grammar-token-python-grammar-call}@anchor{2350}call:                 @ref{234c,,primary} "(" [@ref{235e,,argument_list} [","] | @ref{232d,,comprehension}] ")"
@anchor{reference/expressions grammar-token-python-grammar-argument_list}@anchor{235e}argument_list:        @ref{235f,,positional_arguments} ["," @ref{2360,,starred_and_keywords}]
                        ["," @ref{2361,,keywords_arguments}]
                      | @ref{2360,,starred_and_keywords} ["," @ref{2361,,keywords_arguments}]
                      | @ref{2361,,keywords_arguments}
@anchor{reference/expressions grammar-token-python-grammar-positional_arguments}@anchor{235f}positional_arguments: @ref{2362,,positional_item} ("," @ref{2362,,positional_item})*
@anchor{reference/expressions grammar-token-python-grammar-positional_item}@anchor{2362}positional_item:      @ref{22dd,,assignment_expression} | "*" @ref{182,,expression}
@anchor{reference/expressions grammar-token-python-grammar-starred_and_keywords}@anchor{2360}starred_and_keywords: ("*" @ref{182,,expression} | @ref{2363,,keyword_item})
                      ("," "*" @ref{182,,expression} | "," @ref{2363,,keyword_item})*
@anchor{reference/expressions grammar-token-python-grammar-keywords_arguments}@anchor{2361}keywords_arguments:   (@ref{2363,,keyword_item} | "**" @ref{182,,expression})
                      ("," @ref{2363,,keyword_item} | "," "**" @ref{182,,expression})*
@anchor{reference/expressions grammar-token-python-grammar-keyword_item}@anchor{2363}keyword_item:         @ref{2185,,identifier} "=" @ref{182,,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{773,,__call__()} method are callable).  All
argument expressions are evaluated before the call is attempted.  Please refer
to section @ref{1ee1,,函式定義} for the syntax of formal @ref{21fd,,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{198,,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 @ref{198,,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{3bf,,PyArg_ParseTuple()} to
parse their arguments.

If there are more positional arguments than there are formal parameter slots, a
@ref{198,,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{198,,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 * （星號）;於函式呼叫中
@geindex unpacking（解包）;於函式呼叫中

If the syntax @code{*expression} appears in the function call, @code{expression} must
evaluate to an @ref{1428,,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 **;於函式呼叫中

If the syntax @code{**expression} appears in the function call, @code{expression} must
evaluate to a @ref{13bc,,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{198,,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{198,,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{1ee1,,函式定義}.  When the code block
executes a @ref{1af,,return} statement, this specifies the return value of the
function call.  If execution reaches the end of the code block without
executing a @ref{1af,,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{145d,,內建函式} 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__() （物件方法）

The class must define a @ref{773,,__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,運算式
@anchor{reference/expressions await}@anchor{18d}@anchor{reference/expressions await-expression}@anchor{2364}
@subsection Await expression


Suspend the execution of @ref{6b2,,coroutine} on an @ref{4c4,,awaitable} object.
Can only be used inside a @ref{f6e,,coroutine function}.

@example
@anchor{reference/expressions grammar-token-python-grammar-await_expr}@anchor{2365}await_expr: "await" @ref{234c,,primary}
@end example


在 3.5 版被加入.


@node The power operator,Unary arithmetic and bitwise operations,Await expression,運算式
@anchor{reference/expressions power}@anchor{2366}@anchor{reference/expressions the-power-operator}@anchor{2367}
@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{2368}power: (@ref{2365,,await_expr} | @ref{234c,,primary}) ["**" @ref{2369,,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{1a4,,pow()} function,
when called with two arguments: it yields its left argument raised to the power
of its right argument.  The numeric arguments are first 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{b36,,ZeroDivisionError}.
Raising a negative number to a fractional power results in a @ref{197,,complex}
number. (In earlier versions it raised a @ref{2eb,,ValueError}.)

This operation can be customized using the special @ref{9cd,,__pow__()} and
@ref{1a5,,__rpow__()} methods.

@node Unary arithmetic and bitwise operations,Binary arithmetic operations,The power operator,運算式
@anchor{reference/expressions unary}@anchor{236a}@anchor{reference/expressions unary-arithmetic-and-bitwise-operations}@anchor{236b}
@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{2369}u_expr: @ref{2368,,power} | "-" @ref{2369,,u_expr} | "+" @ref{2369,,u_expr} | "~" @ref{2369,,u_expr}
@end example

@geindex negation（否定）
@geindex minus（減）
@geindex operator（運算子）;- （減號）
@geindex - （減號）;unary operator（一元運算子）

The unary @code{-} (minus) operator yields the negation of its numeric argument; the
operation can be overridden with the @ref{22b2,,__neg__()} special method.

@geindex plus（加）
@geindex operator（運算子）;+ （加號）
@geindex + （加號）;unary operator（一元運算子）

The unary @code{+} (plus) operator yields its numeric argument unchanged; the
operation can be overridden with the @ref{22b3,,__pos__()} special method.

@geindex inversion（反轉）
@geindex operator（運算子）;~ （波浪號）

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{22b5,,__invert__()} special method.

@geindex exception;TypeError

In all three cases, if the argument does not have the proper type, a
@ref{198,,TypeError} exception is raised.

@node Binary arithmetic operations,Shifting operations,Unary arithmetic and bitwise operations,運算式
@anchor{reference/expressions binary}@anchor{236c}@anchor{reference/expressions binary-arithmetic-operations}@anchor{236d}
@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{236e}m_expr: @ref{2369,,u_expr} | @ref{236e,,m_expr} "*" @ref{2369,,u_expr} | @ref{236e,,m_expr} "@@" @ref{236e,,m_expr} |
        @ref{236e,,m_expr} "//" @ref{2369,,u_expr} | @ref{236e,,m_expr} "/" @ref{2369,,u_expr} |
        @ref{236e,,m_expr} "%" @ref{2369,,u_expr}
@anchor{reference/expressions grammar-token-python-grammar-a_expr}@anchor{236f}a_expr: @ref{236e,,m_expr} | @ref{236f,,a_expr} "+" @ref{236e,,m_expr} | @ref{236f,,a_expr} "-" @ref{236e,,m_expr}
@end example

@geindex multiplication（乘）
@geindex operator（運算子）;* （星號）

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 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{2292,,__mul__()} and
@ref{2293,,__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（運算子）;@@ （在）

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{f74,,__matmul__()} and
@ref{f75,,__rmatmul__()} methods.


在 3.5 版被加入.


@geindex exception;ZeroDivisionError
@geindex division（除）
@geindex operator（運算子）;/ （斜線）
@geindex operator（運算子）;//

The @code{/} (division) and @code{//} (floor division) operators yield the quotient of
their arguments.  The numeric arguments are first 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{b36,,ZeroDivisionError}
exception.

The division operation can be customized using the special @ref{108b,,__truediv__()}
and @ref{22a0,,__rtruediv__()} methods.
The floor division operation can be customized using the special
@ref{16e8,,__floordiv__()} and @ref{22a1,,__rfloordiv__()} methods.

@geindex modulo（餘數）
@geindex operator（運算子）;% （百分號）

The @code{%} (modulo) operator yields the remainder from the division of the first
argument by the second.  The numeric arguments are first converted to a common
type.  A zero right argument raises the @ref{b36,,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{2370,,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{b90,,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{8d3,,printf-style String Formatting}.

The `modulo' operation can be customized using the special @ref{2299,,__mod__()}
and @ref{fd0,,__rmod__()} methods.

The floor division operator, the modulo operator, and the @ref{b90,,divmod()}
function are not defined for complex numbers.  Instead, convert to a
floating-point number using the @ref{1f54,,abs()} function if appropriate.

@geindex addition（加）
@geindex operator（運算子）;+ （加號）
@geindex + （加號）;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 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{228f,,__add__()} and
@ref{2290,,__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（運算子）;- （減號）
@geindex - （減號）;binary operator（二元運算子）

The @code{-} (subtraction) operator yields the difference of its arguments.  The
numeric arguments are first converted to a common real type.

This operation can be customized using the special @ref{2298,,__sub__()} and
@ref{229f,,__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,運算式
@anchor{reference/expressions shifting}@anchor{2371}@anchor{reference/expressions shifting-operations}@anchor{2372}
@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{2373}shift_expr: @ref{236f,,a_expr} | @ref{2373,,shift_expr} ("<<" | ">>") @ref{236f,,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{229a,,__lshift__()}
and @ref{22a3,,__rlshift__()} methods.
The right shift operation can be customized using the special @ref{229b,,__rshift__()}
and @ref{22a4,,__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,運算式
@anchor{reference/expressions binary-bitwise-operations}@anchor{2374}@anchor{reference/expressions bitwise}@anchor{2375}
@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{2376}and_expr: @ref{2373,,shift_expr} | @ref{2376,,and_expr} "&" @ref{2373,,shift_expr}
@anchor{reference/expressions grammar-token-python-grammar-xor_expr}@anchor{2377}xor_expr: @ref{2376,,and_expr} | @ref{2377,,xor_expr} "^" @ref{2376,,and_expr}
@anchor{reference/expressions grammar-token-python-grammar-or_expr}@anchor{21b5}or_expr:  @ref{2377,,xor_expr} | @ref{21b5,,or_expr} "|" @ref{2377,,xor_expr}
@end example

@geindex bitwise（位元）;and
@geindex operator（運算子）;& （和號）

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{229c,,__and__()} or
@ref{22a5,,__rand__()} special methods.

@geindex bitwise（位元）;xor
@geindex exclusive（排外）;or
@geindex operator（運算子）;^ （插入符號）

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{229d,,__xor__()} or
@ref{22a6,,__rxor__()} special methods.

@geindex bitwise（位元）;or
@geindex inclusive（包含）;or
@geindex operator（運算子）;| （垂直線）

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{229e,,__or__()} or
@ref{22a7,,__ror__()} special methods.

@node Comparisons,Boolean operations,Binary bitwise operations,運算式
@anchor{reference/expressions comparisons}@anchor{2378}@anchor{reference/expressions id12}@anchor{2379}
@subsection Comparisons


@geindex comparison（比較）
@geindex C;language（語言）
@geindex operator（運算子）;< （小於）
@geindex operator（運算子）;> （大於）
@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{237a}comparison:    @ref{21b5,,or_expr} (@ref{237b,,comp_operator} @ref{21b5,,or_expr})*
@anchor{reference/expressions grammar-token-python-grammar-comp_operator}@anchor{237b}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{3c1,,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{1b32}@anchor{reference/expressions value-comparisons}@anchor{237c}
@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{21e1,,物件、數值和型別} 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{c75,,object}, they
inherit the default comparison behavior from @ref{c75,,object}.  Types can
customize their comparison behavior by implementing
`rich comparison methods' like @ref{14a1,,__lt__()}, described in
@ref{225e,,Basic customization}.

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{198,,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{1ea3,,數值型別 --- int、float、complex}) and of the standard
library types @ref{213,,fractions.Fraction} and @ref{1fe,,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{1a2,,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{192,,bytes} or @ref{343,,bytearray}) can be
compared within and across their types.  They compare lexicographically using
the numeric values of their elements.

@item 
Strings (instances of @ref{169,,str}) compare lexicographically using the
numerical Unicode code points (the result of the built-in function
@ref{21ef,,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{8dc,,unicodedata.normalize()}.
}

Strings and binary sequences cannot be directly compared.

@item 
Sequences (instances of @ref{60c,,tuple}, @ref{24d,,list}, or @ref{b34,,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{198,,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{183,,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{198,,TypeError}.

@item 
Sets (instances of @ref{184,,set} or @ref{7eb,,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{1106,,min()}, @ref{1107,,max()}, and
@ref{dc2,,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} 和 @code{y == x}

@code{x != y} 和 @code{y != x}

@code{x < y} 和 @code{y > x}

@code{x <= y} 和 @code{y >= x}
@end quotation

@item 
Comparison should be transitive.
The following (non-exhaustive) examples illustrate that:

@quotation

@code{x > y and y > z} 暗示了 @code{x > z}

@code{x < y and y <= z} 暗示了 @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} 和 @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{113d,,total_ordering()} decorator.

@item 
The @ref{7fa,,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{349}@anchor{reference/expressions not-in}@anchor{83a}
@node Membership test operations,Identity comparisons,Value comparisons,Comparisons
@anchor{reference/expressions membership-test-details}@anchor{2295}@anchor{reference/expressions membership-test-operations}@anchor{237d}
@subsubsection Membership test operations


The operators @ref{349,,in} and @ref{83a,,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{15b1,,__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{15b1,,__contains__()} but do define
@ref{e64,,__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{349,,in} raised
that exception.

Lastly, the old-style iteration protocol is tried: if a class defines
@ref{582,,__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{1729,,IndexError} exception.  (If any other exception is raised, it is as
if @ref{349,,in} raised that exception).

@geindex operator（運算子）;in
@geindex operator（運算子）;not in
@geindex membership（成員）;test（測試）
@geindex object（物件）;sequence（序列）

The operator @ref{83a,,not in} is defined to have the inverse truth value of
@ref{349,,in}.

@geindex operator（運算子）;is
@geindex operator（運算子）;is not
@geindex identity;test（測試）
@anchor{reference/expressions is}@anchor{34a}
@node Identity comparisons,,Membership test operations,Comparisons
@anchor{reference/expressions identity-comparisons}@anchor{237e}@anchor{reference/expressions is-not}@anchor{237f}
@subsubsection Identity comparisons


The operators @ref{34a,,is} and @ref{237f,,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{161a,,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{34a,,is} operator, like those involving comparisons between instance
methods, or constants.  Check their documentation for more info.
}
@anchor{reference/expressions booleans}@anchor{2380}@anchor{reference/expressions and}@anchor{347}@anchor{reference/expressions or}@anchor{34b}
@node Boolean operations,Assignment expressions<2>,Comparisons,運算式
@anchor{reference/expressions boolean-operations}@anchor{2381}@anchor{reference/expressions not}@anchor{2382}
@subsection Boolean operations


@geindex Conditional（條件式）;expression
@geindex Boolean（布林）;operation（操作）

@example
@anchor{reference/expressions grammar-token-python-grammar-or_test}@anchor{2330}or_test:  @ref{2383,,and_test} | @ref{2330,,or_test} "or" @ref{2383,,and_test}
@anchor{reference/expressions grammar-token-python-grammar-and_test}@anchor{2383}and_test: @ref{2384,,not_test} | @ref{2383,,and_test} "and" @ref{2384,,not_test}
@anchor{reference/expressions grammar-token-python-grammar-not_test}@anchor{2384}not_test: @ref{237a,,comparison} | "not" @ref{2384,,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{14d6,,__bool__()} method.

@geindex operator（運算子）;not

The operator @ref{2382,,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{347,,and} nor @ref{34b,,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{2382,,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 ;= （冒號等於）
@geindex assignment expression（賦值運算式）
@geindex walrus operator（海象運算子）
@geindex named expression（附名運算式）
@geindex assignment（賦值）;expression

@node Assignment expressions<2>,Conditional expressions,Boolean operations,運算式
@anchor{reference/expressions assignment-expressions}@anchor{2385}@anchor{reference/expressions id15}@anchor{2386}
@subsection Assignment expressions


@example
@anchor{reference/expressions grammar-token-python-grammar-assignment_expression}@anchor{22dd}assignment_expression: [@ref{2185,,identifier} ":="] @ref{182,,expression}
@end example

An assignment expression (sometimes also called a "named expression" or
"walrus") assigns an @ref{182,,expression} to an
@ref{2185,,identifier}, while also returning the value of the
@ref{182,,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.


在 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>,運算式
@anchor{reference/expressions conditional-expressions}@anchor{2387}@anchor{reference/expressions if-expr}@anchor{17d}
@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{21b4}conditional_expression: @ref{2330,,or_test} ["if" @ref{2330,,or_test} "else" @ref{182,,expression}]
@anchor{reference/expressions grammar-token-python-grammar-expression}@anchor{182}expression:             @ref{21b4,,conditional_expression} | @ref{2388,,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{2389}
@node Lambdas,Expression lists,Conditional expressions,運算式
@anchor{reference/expressions id16}@anchor{238a}@anchor{reference/expressions lambda}@anchor{149e}
@subsection Lambdas


@geindex lambda;expression
@geindex lambda;form
@geindex anonymous（匿名）;function （函式）
@geindex ; （冒號）;lambda expression（lambda 運算式）

@example
@anchor{reference/expressions grammar-token-python-grammar-lambda_expr}@anchor{2388}lambda_expr: "lambda" [@ref{238b,,parameter_list}] ":" @ref{182,,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{1ee1,,函式定義} for the syntax of parameter lists.  Note that
functions created with lambda expressions cannot contain statements or
annotations.

@node Expression lists,Evaluation order,Lambdas,運算式
@anchor{reference/expressions expression-lists}@anchor{238c}@anchor{reference/expressions exprlists}@anchor{f79}
@subsection Expression lists


@geindex expression;list（串列）
@geindex @comma{} （逗號）;expression list（運算式串列）

@example
@anchor{reference/expressions grammar-token-python-grammar-starred_expression}@anchor{232b}starred_expression:       "*" @ref{21b5,,or_expr} | @ref{182,,expression}
@anchor{reference/expressions grammar-token-python-grammar-flexible_expression}@anchor{238d}flexible_expression:      @ref{22dd,,assignment_expression} | @ref{232b,,starred_expression}
@anchor{reference/expressions grammar-token-python-grammar-flexible_expression_list}@anchor{2335}flexible_expression_list: @ref{238d,,flexible_expression} ("," @ref{238d,,flexible_expression})* [","]
@anchor{reference/expressions grammar-token-python-grammar-starred_expression_list}@anchor{238e}starred_expression_list:  @ref{232b,,starred_expression} ("," @ref{232b,,starred_expression})* [","]
@anchor{reference/expressions grammar-token-python-grammar-expression_list}@anchor{238f}expression_list:          @ref{182,,expression} ("," @ref{182,,expression})* [","]
@anchor{reference/expressions grammar-token-python-grammar-yield_list}@anchor{2341}yield_list:               @ref{238f,,expression_list} | @ref{232b,,starred_expression} "," [@ref{238e,,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 * （星號）;於 expression list（運算式串列）

An asterisk @code{*} denotes `iterable unpacking'.  Its operand must be
an @ref{1428,,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.


在 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/}.



在 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,運算式
@anchor{reference/expressions evalorder}@anchor{2390}@anchor{reference/expressions evaluation-order}@anchor{2391}
@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,運算式
@anchor{reference/expressions operator-precedence}@anchor{2392}@anchor{reference/expressions operator-summary}@anchor{2393}
@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{2378,,Comparisons} section.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

運算子

@tab

描述

@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, slicing,
call, attribute reference

@item

@ref{18d,,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{349,,in}, @ref{83a,,not in},
@ref{34a,,is}, @ref{237f,,is not}, @code{<},
@code{<=}, @code{>}, @code{>=}, @code{!=}, @code{==}

@tab

Comparisons, including membership
tests and identity tests

@item

@ref{2382,,not x}

@tab

Boolean NOT

@item

@ref{347,,and}

@tab

Boolean AND

@item

@ref{34b,,or}

@tab

Boolean OR

@item

@ref{17d,,if} -- @code{else}

@tab

Conditional expression

@item

@ref{149e,,lambda}

@tab

Lambda expression

@item

@code{:=}

@tab

Assignment expression

@end multitable


@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/simple_stmts doc}@anchor{2394}@anchor{reference/simple_stmts simple}@anchor{2395}@anchor{reference/simple_stmts simple-statements}@anchor{2396}@anchor{reference/simple_stmts translation-repo}@anchor{2397}
@section 簡單陳述式


@geindex simple;statement（陳述式）

A simple statement is comprised within a single logical line. Several simple
statements may occur on a single line separated by semicolons.  The syntax for
simple statements is:

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-simple_stmt}@anchor{2398}simple_stmt: @ref{2399,,expression_stmt}
             | @ref{239a,,assert_stmt}
             | @ref{239b,,assignment_stmt}
             | @ref{239c,,augmented_assignment_stmt}
             | @ref{239d,,annotated_assignment_stmt}
             | @ref{239e,,pass_stmt}
             | @ref{239f,,del_stmt}
             | @ref{23a0,,return_stmt}
             | @ref{23a1,,yield_stmt}
             | @ref{23a2,,raise_stmt}
             | @ref{23a3,,break_stmt}
             | @ref{23a4,,continue_stmt}
             | @ref{23a5,,import_stmt}
             | @ref{23a6,,future_stmt}
             | @ref{23a7,,global_stmt}
             | @ref{23a8,,nonlocal_stmt}
             | @ref{23a9,,type_stmt}
@end example

@menu
* Expression statements:: 
* Assignment statements:: 
* assert 陳述式:: 
* pass 陳述式: pass 陳述式<2>. 
* del 陳述式: del 陳述式<2>. 
* return 陳述式:: 
* yield 陳述式:: 
* raise 陳述式:: 
* break 陳述式:: 
* continue 陳述式:: 
* import 陳述式:: 
* global 陳述式:: 
* nonlocal 陳述式:: 
* type 陳述式:: 

@end menu

@node Expression statements,Assignment statements,,簡單陳述式
@anchor{reference/simple_stmts expression-statements}@anchor{23aa}@anchor{reference/simple_stmts exprstmts}@anchor{23ab}
@subsection Expression statements


@geindex expression;statement（陳述式）
@geindex expression;list（串列）

@geindex expression;list（串列）

Expression statements are used (mostly interactively) to compute and write a
value, or (usually) to call a procedure (a function that returns no meaningful
result; in Python, procedures return the value @code{None}).  Other uses of
expression statements are allowed and occasionally useful.  The syntax for an
expression statement is:

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-expression_stmt}@anchor{2399}expression_stmt: @ref{232b,,starred_expression}
@end example

An expression statement evaluates the expression list (which may be a single
expression).

@geindex built-in function（內建函式）;repr
@geindex object（物件）;None
@geindex string（字串）;conversion
@geindex output
@geindex standard;output
@geindex writing;values
@geindex procedure;call

In interactive mode, if the value is not @code{None}, it is converted to a string
using the built-in @ref{1c1,,repr()} function and the resulting string is written to
standard output on a line by itself (except if the result is @code{None}, so that
procedure calls do not cause any output.)

@node Assignment statements,assert 陳述式,Expression statements,簡單陳述式
@anchor{reference/simple_stmts assignment}@anchor{22d7}@anchor{reference/simple_stmts assignment-statements}@anchor{23ac}
@subsection Assignment statements


@geindex = （等號）;assignment statement（賦值陳述式）
@geindex assignment（賦值）;statement（陳述式）
@geindex binding（繫結）;name（名稱）
@geindex rebinding（重新繫結）;name（名稱）
@geindex object（物件）;mutable（可變的）
@geindex attribute（屬性）;assignment（賦值）

Assignment statements are used to (re)bind names to values and to modify
attributes or items of mutable objects:

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-assignment_stmt}@anchor{239b}assignment_stmt: (@ref{232f,,target_list} "=")+ (@ref{232b,,starred_expression} | @ref{21b6,,yield_expression})
@anchor{reference/simple_stmts grammar-token-python-grammar-target_list}@anchor{232f}target_list:     @ref{23ad,,target} ("," @ref{23ad,,target})* [","]
@anchor{reference/simple_stmts grammar-token-python-grammar-target}@anchor{23ad}target:          @ref{2185,,identifier}
                 | "(" [@ref{232f,,target_list}] ")"
                 | "[" [@ref{232f,,target_list}] "]"
                 | @ref{234d,,attributeref}
                 | @ref{234e,,subscription}
                 | @ref{234f,,slicing}
                 | "*" @ref{23ad,,target}
@end example

(See section @ref{234b,,Primaries} for the syntax definitions for `attributeref',
`subscription', and `slicing'.)

An assignment statement evaluates the expression list (remember that this can be
a single expression or a comma-separated list, the latter yielding a tuple) and
assigns the single resulting object to each of the target lists, from left to
right.

@geindex target
@geindex target;list（串列）

Assignment is defined recursively depending on the form of the target (list).
When a target is part of a mutable object (an attribute reference, subscription
or slicing), 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{21e4,,標準型別階層}).

@geindex target;list（串列）;assignment（賦值）
@geindex @comma{} （逗號）;於目標列表中
@geindex * （星號）;於賦值目標列表中
@geindex [] （方括號）;於賦值目標列表中
@geindex () （圓括號）;於賦值目標列表中

Assignment of an object to a target list, optionally enclosed in parentheses or
square brackets, is recursively defined as follows.


@itemize *

@item 
If the target list is a single target with no trailing comma,
optionally in parentheses, the object is assigned to that target.

@item 
Else:


@itemize *

@item 
If the target list contains one target prefixed with an asterisk, called a
"starred" target: The object must be an iterable with at least as many items
as there are targets in the target list, minus one.  The first items of the
iterable are assigned, from left to right, to the targets before the starred
target.  The final items of the iterable are assigned to the targets after
the starred target.  A list of the remaining items in the iterable is then
assigned to the starred target (the list can be empty).

@item 
Else: The object must be an iterable with the same number of items as there
are targets in the target list, and the items are assigned, from left to
right, to the corresponding targets.
@end itemize
@end itemize

Assignment of an object to a single target is recursively defined as follows.


@itemize *

@item 
If the target is an identifier (name):


@itemize *

@item 
If the name does not occur in a @ref{4a7,,global} or @ref{14a8,,nonlocal}
statement in the current code block: the name is bound to the object in the
current local namespace.

@item 
Otherwise: the name is bound to the object in the global namespace or the
outer namespace determined by @ref{14a8,,nonlocal}, respectively.
@end itemize

@geindex destructor（解構函式）

The name is rebound if it was already bound.  This may cause the reference
count for the object previously bound to the name to reach zero, causing the
object to be deallocated and its destructor (if it has one) to be called.

@geindex attribute（屬性）;assignment（賦值）

@item 
If the target is an attribute reference: The primary expression in the
reference is evaluated.  It should yield an object with assignable attributes;
if this is not the case, @ref{198,,TypeError} is raised.  That object is then
asked to assign the assigned object to the given attribute; if it cannot
perform the assignment, it raises an exception (usually but not necessarily
@ref{5e8,,AttributeError}).
@anchor{reference/simple_stmts attr-target-note}@anchor{23ae}
Note: If the object is a class instance and the attribute reference occurs on
both sides of the assignment operator, the right-hand side expression, @code{a.x} can access
either an instance attribute or (if no instance attribute exists) a class
attribute.  The left-hand side target @code{a.x} is always set as an instance attribute,
creating it if necessary.  Thus, the two occurrences of @code{a.x} do not
necessarily refer to the same attribute: if the right-hand side expression refers to a
class attribute, the left-hand side creates a new instance attribute as the target of the
assignment:

@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

This description does not necessarily apply to descriptor attributes, such as
properties created with @ref{4ae,,property()}.

@geindex subscription（下標）;assignment（賦值）
@geindex object（物件）;mutable（可變的）

@item 
If the target is a subscription: The primary expression in the reference is
evaluated.  It should yield either a mutable sequence object (such as a list)
or a mapping object (such as a dictionary).  Next, the subscript expression is
evaluated.

@geindex object（物件）;sequence（序列）
@geindex object（物件）;list（串列）

If the primary is a mutable sequence object (such as a list), the subscript
must yield an integer.  If it is negative, the sequence's length is added to
it.  The resulting value must be a nonnegative integer less than the
sequence's length, and the sequence is asked to assign the assigned object to
its item with that index.  If the index is out of range, @ref{1729,,IndexError} is
raised (assignment to a subscripted sequence cannot add new items to a list).

@geindex object（物件）;mapping（對映）
@geindex object（物件）;dictionary（字典）

If the primary is a mapping object (such as a dictionary), the subscript must
have a type compatible with the mapping's key type, and the mapping is then
asked to create a key/value pair which maps the subscript to the assigned
object.  This can either replace an existing key/value pair with the same key
value, or insert a new key/value pair (if no key with the same value existed).

For user-defined objects, the @ref{14cc,,__setitem__()} method is called with
appropriate arguments.

@geindex slice（切片）;assignment（賦值）

@item 
If the target is a slicing: The primary expression in the reference is
evaluated.  It should yield a mutable sequence object (such as a list).  The
assigned object should be a sequence object of the same type.  Next, the lower
and upper bound expressions are evaluated, insofar they are present; defaults
are zero and the sequence's length.  The bounds should evaluate to integers.
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

`CPython 實作細節：' In the current implementation, the syntax for targets is taken to be the same
as for expressions, and invalid syntax is rejected during the code generation
phase, causing less detailed error messages.

Although the definition of assignment implies that overlaps between the
left-hand side and the right-hand side are 'simultaneous' (for example @code{a, b =
b, a} swaps two variables), overlaps `within' the collection of assigned-to
variables occur left-to-right, sometimes resulting in confusion.  For instance,
the following program prints @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/} - Extended Iterable Unpacking

The specification for the @code{*target} feature.
@end table


@menu
* 擴增賦值陳述式:: 
* 註釋賦值陳述式:: 

@end menu

@node 擴增賦值陳述式,註釋賦值陳述式,,Assignment statements
@anchor{reference/simple_stmts augassign}@anchor{23af}@anchor{reference/simple_stmts augmented-assignment-statements}@anchor{23b0}
@subsubsection 擴增賦值陳述式


@geindex augmented（增強）;assignment（賦值）
@geindex statement（陳述式）;assignment（賦值）、augmented（增強）
@geindex +=;augmented assignment（增強賦值）
@geindex -=;augmented assignment（增強賦值）
@geindex *=;augmented assignment（增強賦值）
@geindex /=;augmented assignment（增強賦值）
@geindex %=;augmented assignment（增強賦值）
@geindex &=;augmented assignment（增強賦值）
@geindex ^=;augmented assignment（增強賦值）
@geindex |=;augmented assignment（增強賦值）
@geindex **=;augmented assignment（增強賦值）
@geindex //=;augmented assignment（增強賦值）
@geindex >>=;augmented assignment（增強賦值）
@geindex <<=;augmented assignment（增強賦值）

Augmented assignment is the combination, in a single statement, of a binary
operation and an assignment statement:

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-augmented_assignment_stmt}@anchor{239c}augmented_assignment_stmt: @ref{23b1,,augtarget} @ref{23b2,,augop} (@ref{238f,,expression_list} | @ref{21b6,,yield_expression})
@anchor{reference/simple_stmts grammar-token-python-grammar-augtarget}@anchor{23b1}augtarget:                 @ref{2185,,identifier} | @ref{234d,,attributeref} | @ref{234e,,subscription} | @ref{234f,,slicing}
@anchor{reference/simple_stmts grammar-token-python-grammar-augop}@anchor{23b2}augop:                     "+=" | "-=" | "*=" | "@@=" | "/=" | "//=" | "%=" | "**="
                           | ">>=" | "<<=" | "&=" | "^=" | "|="
@end example

(See section @ref{234b,,Primaries} for the syntax definitions of the last three
symbols.)

An augmented assignment evaluates the target (which, unlike normal assignment
statements, cannot be an unpacking) and the expression list, performs the binary
operation specific to the type of assignment on the two operands, and assigns
the result to the original target.  The target is only evaluated once.

An augmented assignment statement like @code{x += 1} can be rewritten as @code{x = x +
1} to achieve a similar, but not exactly equal effect. In the augmented
version, @code{x} is only evaluated once. Also, when possible, the actual operation
is performed `in-place', meaning that rather than creating a new object and
assigning that to the target, the old object is modified instead.

Unlike normal assignments, augmented assignments evaluate the left-hand side
`before' evaluating the right-hand side.  For example, @code{a[i] += f(x)} first
looks-up @code{a[i]}, then it evaluates @code{f(x)} and performs the addition, and
lastly, it writes the result back to @code{a[i]}.

With the exception of assigning to tuples and multiple targets in a single
statement, the assignment done by augmented assignment statements is handled the
same way as normal assignments. Similarly, with the exception of the possible
`in-place' behavior, the binary operation performed by augmented assignment is
the same as the normal binary operations.

For targets which are attribute references, the same @ref{23ae,,caveat about class and instance attributes} applies as for regular assignments.

@node 註釋賦值陳述式,,擴增賦值陳述式,Assignment statements
@anchor{reference/simple_stmts annassign}@anchor{23b3}@anchor{reference/simple_stmts annotated-assignment-statements}@anchor{23b4}
@subsubsection 註釋賦值陳述式


@geindex annotated（註釋）;assignment（賦值）
@geindex statement（陳述式）;assignment（賦值）、annotated（註釋）
@geindex ; （冒號）;annotated variable（註釋變數）

@ref{f4c,,註釋} 賦值是將變數或屬性註釋與可選的賦值陳述式結合在一個陳述式中：

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-annotated_assignment_stmt}@anchor{239d}annotated_assignment_stmt: @ref{23b1,,augtarget} ":" @ref{182,,expression}
                           ["=" (@ref{232b,,starred_expression} | @ref{21b6,,yield_expression})]
@end example

The difference from normal @ref{22d7,,Assignment statements} is that only a single target is allowed.

The assignment target is considered "simple" if it consists of a single
name that is not enclosed in parentheses.
For simple assignment targets, if in class or module scope,
the annotations are gathered in a lazily evaluated
@ref{4a6,,annotation scope}. The annotations can be
evaluated using the @ref{456,,__annotations__} attribute of a
class or module, or using the facilities in the @ref{6,,annotationlib}
module.

If the assignment target is not simple (an attribute, subscript node, or
parenthesized name), the annotation is never evaluated.

If a name is annotated in a function scope, then this name is local for
that scope. Annotations are never evaluated and stored in function scopes.

If the right hand side is present, an annotated
assignment performs the actual assignment as if there was no annotation
present. If the right hand side is not present for an expression
target, then the interpreter evaluates the target except for the last
@ref{14cc,,__setitem__()} or @ref{222d,,__setattr__()} call.


@subsubheading 也參考



@table @asis

@geindex Python Enhancement Proposals; PEP 526

@item PEP 526@footnote{https://peps.python.org/pep-0526/} - Syntax for Variable Annotations

The proposal that added syntax for annotating the types of variables
(including class variables and instance variables), instead of expressing
them through comments.

@geindex Python Enhancement Proposals; PEP 484

@item PEP 484@footnote{https://peps.python.org/pep-0484/} - 型別提示

The proposal that added the @ref{10a,,typing} module to provide a standard
syntax for type annotations that can be used in static analysis tools and
IDEs.
@end table



在 3.8 版的變更: Now annotated assignments allow the same expressions in the right hand side as
regular assignments. Previously, some expressions (like un-parenthesized
tuple expressions) caused a syntax error.



在 3.14 版的變更: Annotations are now lazily evaluated in a separate @ref{4a6,,annotation scope}.
If the assignment target is not simple, annotations are never evaluated.


@node assert 陳述式,pass 陳述式<2>,Assignment statements,簡單陳述式
@anchor{reference/simple_stmts assert}@anchor{b57}@anchor{reference/simple_stmts the-assert-statement}@anchor{23b5}
@subsection @code{assert} 陳述式


@geindex statement（陳述式）;assert
@geindex debugging（除錯）;assertions（斷言）
@geindex @comma{} （逗號）;expression list（運算式列表）

Assert statements are a convenient way to insert debugging assertions into a
program:

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-assert_stmt}@anchor{239a}assert_stmt: "assert" @ref{182,,expression} ["," @ref{182,,expression}]
@end example

The simple form, @code{assert expression}, is equivalent to

@example
if __debug__:
    if not expression: raise AssertionError
@end example

The extended form, @code{assert expression1, expression2}, is equivalent to

@example
if __debug__:
    if not expression1: raise AssertionError(expression2)
@end example

@geindex __debug__
@geindex exception（例外）;AssertionError

These equivalences assume that @ref{9d3,,__debug__} and @ref{8b0,,AssertionError} refer to
the built-in variables with those names.  In the current implementation, the
built-in variable @code{__debug__} is @code{True} under normal circumstances,
@code{False} when optimization is requested (command line option @ref{18c,,-O}).  The current
code generator emits no code for an @ref{b57,,assert} statement when optimization is
requested at compile time.  Note that it is unnecessary to include the source
code for the expression that failed in the error message; it will be displayed
as part of the stack trace.

Assignments to @ref{9d3,,__debug__} are illegal.  The value for the built-in variable
is determined when the interpreter starts.

@node pass 陳述式<2>,del 陳述式<2>,assert 陳述式,簡單陳述式
@anchor{reference/simple_stmts pass}@anchor{17e}@anchor{reference/simple_stmts the-pass-statement}@anchor{23b6}
@subsection @code{pass} 陳述式


@geindex statement（陳述式）;pass
@geindex null;operation（操作）
@geindex null;operation（操作）

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-pass_stmt}@anchor{239e}pass_stmt: "pass"
@end example

@ref{17e,,pass} is a null operation --- when it is executed, nothing happens.
It is useful as a placeholder when a statement is required syntactically, but no
code needs to be executed, for example:

@example
def f(arg): pass    # a function that does nothing (yet)

class C: pass       # a class with no methods (yet)
@end example

@node del 陳述式<2>,return 陳述式,pass 陳述式<2>,簡單陳述式
@anchor{reference/simple_stmts del}@anchor{1a62}@anchor{reference/simple_stmts the-del-statement}@anchor{23b7}
@subsection @code{del} 陳述式


@geindex statement（陳述式）;del
@geindex deletion（刪除）;target
@geindex deletion（刪除）;target;list（串列）

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-del_stmt}@anchor{239f}del_stmt: "del" @ref{232f,,target_list}
@end example

Deletion is recursively defined very similar to the way assignment is defined.
Rather than spelling it out in full details, here are some hints.

Deletion of a target list recursively deletes each target, from left to right.

@geindex statement（陳述式）;global
@geindex unbinding（解除繫結）;name（名稱）

Deletion of a name removes the binding of that name from the local or global
namespace, depending on whether the name occurs in a @ref{4a7,,global} statement
in the same code block.  Trying to delete an unbound name raises a
@ref{450,,NameError} exception.

@geindex attribute（屬性）;deletion（刪除）

Deletion of attribute references, subscriptions and slicings 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 版的變更: Previously it was illegal to delete a name from the local namespace if it
occurs as a free variable in a nested block.


@node return 陳述式,yield 陳述式,del 陳述式<2>,簡單陳述式
@anchor{reference/simple_stmts return}@anchor{1af}@anchor{reference/simple_stmts the-return-statement}@anchor{23b8}
@subsection @code{return} 陳述式


@geindex statement（陳述式）;return （回傳）
@geindex function （函式）;definition（定義）
@geindex class（類別）;definition（定義）

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-return_stmt}@anchor{23a0}return_stmt: "return" [@ref{238f,,expression_list}]
@end example

@ref{1af,,return} may only occur syntactically nested in a function definition,
not within a nested class definition.

If an expression list is present, it is evaluated, else @code{None} is substituted.

@ref{1af,,return} leaves the current function call with the expression list (or
@code{None}) as return value.

@geindex keyword（關鍵字）;finally

When @ref{1af,,return} passes control out of a @ref{8f0,,try} statement with a
@ref{1b0,,finally} clause, that @code{finally} clause is executed before
really leaving the function.

In a generator function, the @ref{1af,,return} statement indicates that the
generator is done and will cause @ref{df0,,StopIteration} to be raised. The returned
value (if any) is used as an argument to construct @ref{df0,,StopIteration} and
becomes the @ref{22c6,,StopIteration.value} attribute.

In an asynchronous generator function, an empty @ref{1af,,return} statement
indicates that the asynchronous generator is done and will cause
@ref{1cd7,,StopAsyncIteration} to be raised.  A non-empty @code{return}
statement is a syntax error in an asynchronous generator function.

@node yield 陳述式,raise 陳述式,return 陳述式,簡單陳述式
@anchor{reference/simple_stmts the-yield-statement}@anchor{23b9}@anchor{reference/simple_stmts yield}@anchor{bb9}
@subsection @code{yield} 陳述式


@geindex statement（陳述式）;yield
@geindex generator（產生器）;function （函式）
@geindex generator（產生器）;iterator（疊代器）
@geindex function （函式）;generator（產生器）
@geindex exception（例外）;StopIteration

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-yield_stmt}@anchor{23a1}yield_stmt: @ref{21b6,,yield_expression}
@end example

A @ref{bb9,,yield} statement is semantically equivalent to a @ref{233f,,yield expression}. The @code{yield} statement can be used to omit the
parentheses that would otherwise be required in the equivalent yield expression
statement. For example, the yield statements

@example
yield <expr>
yield from <expr>
@end example

are equivalent to the yield expression statements

@example
(yield <expr>)
(yield from <expr>)
@end example

Yield expressions and statements are only used when defining a @ref{125c,,generator}
function, and are only used in the body of the generator function.  Using @ref{bb9,,yield}
in a function definition is sufficient to cause that definition to create a
generator function instead of a normal function.

For full details of @ref{bb9,,yield} semantics, refer to the
@ref{233f,,Yield expressions} section.

@node raise 陳述式,break 陳述式,yield 陳述式,簡單陳述式
@anchor{reference/simple_stmts raise}@anchor{7fc}@anchor{reference/simple_stmts the-raise-statement}@anchor{23ba}
@subsection @code{raise} 陳述式


@geindex statement（陳述式）;raise
@geindex exception（例外）
@geindex raiseing;exception（例外）
@geindex __traceback__（例外屬性）

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-raise_stmt}@anchor{23a2}raise_stmt: "raise" [@ref{182,,expression} ["from" @ref{182,,expression}]]
@end example

If no expressions are present, @ref{7fc,,raise} re-raises the
exception that is currently being handled, which is also known as the `active exception'.
If there isn't currently an active exception, a @ref{244,,RuntimeError} exception is raised
indicating that this is an error.

Otherwise, @ref{7fc,,raise} evaluates the first expression as the exception
object.  It must be either a subclass or an instance of @ref{7d0,,BaseException}.
If it is a class, the exception instance will be obtained when needed by
instantiating the class with no arguments.

The `type' of the exception is the exception instance's class, the
`value' is the instance itself.

@geindex object（物件）;traceback

A traceback object is normally created automatically when an exception is raised
and attached to it as the @ref{14c7,,__traceback__} attribute.
You can create an exception and set your own traceback in one step using the
@ref{23bb,,with_traceback()} exception method (which returns the
same exception instance, with its traceback set to its argument), like so:

@example
raise Exception("foo occurred").with_traceback(tracebackobj)
@end example

@geindex exception（例外）;chaining（鏈結）
@geindex __cause__（例外屬性）
@geindex __context__（例外屬性）

The @code{from} clause is used for exception chaining: if given, the second
`expression' must be another exception class or instance. If the second
expression is an exception instance, it will be attached to the raised
exception as the @ref{14c9,,__cause__} attribute (which is writable). If the
expression is an exception class, the class will be instantiated and the
resulting exception instance will be attached to the raised exception as the
@code{__cause__} attribute. If the raised exception is not handled, both
exceptions will be printed:

@example
>>> try:
...     print(1 / 0)
... except Exception as exc:
...     raise RuntimeError("Something bad happened") from exc
...
Traceback (most recent call last):
  File "<stdin>", line 2, in <module>
    print(1 / 0)
          ~~^~~
ZeroDivisionError: division by zero

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "<stdin>", line 4, in <module>
    raise RuntimeError("Something bad happened") from exc
RuntimeError: Something bad happened
@end example

A similar mechanism works implicitly if a new exception is raised when
an exception is already being handled.  An exception may be handled
when an @ref{1ab,,except} or @ref{1b0,,finally} clause, or a
@ref{186,,with} statement, is used.  The previous exception is then
attached as the new exception's @ref{14c8,,__context__} attribute:

@example
>>> try:
...     print(1 / 0)
... except:
...     raise RuntimeError("Something bad happened")
...
Traceback (most recent call last):
  File "<stdin>", line 2, in <module>
    print(1 / 0)
          ~~^~~
ZeroDivisionError: division by zero

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "<stdin>", line 4, in <module>
    raise RuntimeError("Something bad happened")
RuntimeError: Something bad happened
@end example

Exception chaining can be explicitly suppressed by specifying @ref{87e,,None} in
the @code{from} clause:

@example
>>> try:
...     print(1 / 0)
... except:
...     raise RuntimeError("Something bad happened") from None
...
Traceback (most recent call last):
  File "<stdin>", line 4, in <module>
RuntimeError: Something bad happened
@end example

Additional information on exceptions can be found in section @ref{22e3,,例外},
and information about handling exceptions is in section @ref{8f0,,try 陳述式}.


在 3.3 版的變更: @ref{87e,,None} is now permitted as @code{Y} in @code{raise X from Y}.

Added the @ref{23bc,,__suppress_context__} attribute to suppress
automatic display of the exception context.



在 3.11 版的變更: If the traceback of the active exception is modified in an @ref{1ab,,except}
clause, a subsequent @code{raise} statement re-raises the exception with the
modified traceback. Previously, the exception was re-raised with the
traceback it had when it was caught.


@node break 陳述式,continue 陳述式,raise 陳述式,簡單陳述式
@anchor{reference/simple_stmts break}@anchor{17f}@anchor{reference/simple_stmts the-break-statement}@anchor{23bd}
@subsection @code{break} 陳述式


@geindex statement（陳述式）;break
@geindex statement（陳述式）;for
@geindex statement（陳述式）;while
@geindex loop（迴圈）;statement（陳述式）

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-break_stmt}@anchor{23a3}break_stmt: "break"
@end example

@ref{17f,,break} may only occur syntactically nested in a @ref{348,,for} or
@ref{18d6,,while} loop, but not nested in a function or class definition within
that loop.

@geindex keyword（關鍵字）;else
@geindex loop control（迴圈控制）;target

It terminates the nearest enclosing loop, skipping the optional @code{else}
clause if the loop has one.

If a @ref{348,,for} loop is terminated by @ref{17f,,break}, the loop control
target keeps its current value.

@geindex keyword（關鍵字）;finally

When @ref{17f,,break} passes control out of a @ref{8f0,,try} statement with a
@ref{1b0,,finally} clause, that @code{finally} clause is executed before
really leaving the loop.

@node continue 陳述式,import 陳述式,break 陳述式,簡單陳述式
@anchor{reference/simple_stmts continue}@anchor{180}@anchor{reference/simple_stmts the-continue-statement}@anchor{23be}
@subsection @code{continue} 陳述式


@geindex statement（陳述式）;continue
@geindex statement（陳述式）;for
@geindex statement（陳述式）;while
@geindex loop（迴圈）;statement（陳述式）
@geindex keyword（關鍵字）;finally

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-continue_stmt}@anchor{23a4}continue_stmt: "continue"
@end example

@ref{180,,continue} may only occur syntactically nested in a @ref{348,,for} or
@ref{18d6,,while} loop, but not nested in a function or class definition within
that loop.  It continues with the next cycle of the nearest enclosing loop.

When @ref{180,,continue} passes control out of a @ref{8f0,,try} statement with a
@ref{1b0,,finally} clause, that @code{finally} clause is executed before
really starting the next loop cycle.
@anchor{reference/simple_stmts import}@anchor{7f1}
@node import 陳述式,global 陳述式,continue 陳述式,簡單陳述式
@anchor{reference/simple_stmts from}@anchor{14ac}@anchor{reference/simple_stmts the-import-statement}@anchor{23bf}
@subsection @code{import} 陳述式


@geindex statement（陳述式）;import（引入）
@geindex module（模組）;importing（引入）
@geindex name（名稱）;binding（繫結）
@geindex keyword（關鍵字）;from
@geindex keyword（關鍵字）;as
@geindex exception（例外）;ImportError
@geindex @comma{} （逗號）;import statement（引入陳述式）

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-import_stmt}@anchor{23a5}import_stmt:     "import" @ref{23c0,,module} ["as" @ref{2185,,identifier}] ("," @ref{23c0,,module} ["as" @ref{2185,,identifier}])*
                 | "from" @ref{23c1,,relative_module} "import" @ref{2185,,identifier} ["as" @ref{2185,,identifier}]
                 ("," @ref{2185,,identifier} ["as" @ref{2185,,identifier}])*
                 | "from" @ref{23c1,,relative_module} "import" "(" @ref{2185,,identifier} ["as" @ref{2185,,identifier}]
                 ("," @ref{2185,,identifier} ["as" @ref{2185,,identifier}])* [","] ")"
                 | "from" @ref{23c1,,relative_module} "import" "*"
@anchor{reference/simple_stmts grammar-token-python-grammar-module}@anchor{23c0}module:          (@ref{2185,,identifier} ".")* @ref{2185,,identifier}
@anchor{reference/simple_stmts grammar-token-python-grammar-relative_module}@anchor{23c1}relative_module: "."* @ref{23c0,,module} | "."+
@end example

The basic import statement (no @ref{14ac,,from} clause) is executed in two
steps:


@enumerate 

@item 
find a module, loading and initializing it if necessary

@item 
define a name or names in the local namespace for the scope where
the @ref{7f1,,import} statement occurs.
@end enumerate

When the statement contains multiple clauses (separated by
commas) the two steps are carried out separately for each clause, just
as though the clauses had been separated out into individual import
statements.

The details of the first step, finding and loading modules, are described in
greater detail in the section on the @ref{2212,,import system},
which also describes the various types of packages and modules that can
be imported, as well as all the hooks that can be used to customize
the import system. Note that failures in this step may indicate either
that the module could not be located, `or' that an error occurred while
initializing the module, which includes execution of the module's code.

If the requested module is retrieved successfully, it will be made
available in the local namespace in one of three ways:

@geindex as;import statement（引入陳述式）


@itemize *

@item 
If the module name is followed by @code{as}, then the name
following @code{as} is bound directly to the imported module.

@item 
If no other name is specified, and the module being imported is a top
level module, the module's name is bound in the local namespace as a
reference to the imported module

@item 
If the module being imported is `not' a top level module, then the name
of the top level package that contains the module is bound in the local
namespace as a reference to the top level package. The imported module
must be accessed using its full qualified name rather than directly
@end itemize

@geindex name（名稱）;binding（繫結）
@geindex from;import statement（引入陳述式）

The @ref{14ac,,from} form uses a slightly more complex process:


@enumerate 

@item 
find the module specified in the @ref{14ac,,from} clause, loading and
initializing it if necessary;

@item 
for each of the identifiers specified in the @ref{7f1,,import} clauses:


@enumerate 

@item 
check if the imported module has an attribute by that name

@item 
if not, attempt to import a submodule with that name and then
check the imported module again for that attribute

@item 
if the attribute is not found, @ref{653,,ImportError} is raised.

@item 
otherwise, a reference to that value is stored in the local 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 * （星號）;import statement（引入陳述式）

If the list of identifiers is replaced by a star (@code{'*'}), all public
names defined in the module are bound in the local namespace for the scope
where the @ref{7f1,,import} statement occurs.

@geindex __all__（可選模組屬性）

@geindex __all__ (module 的屬性)
@anchor{reference/simple_stmts module __all__}@anchor{f36}
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.  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).

The wild card form of import --- @code{from module import *} --- is only allowed at
the module level.  Attempting to use it in class or function definitions will
raise a @ref{18e,,SyntaxError}.

@geindex relative（相對）;import（引入）

When specifying what module to import you do not have to specify the absolute
name of the module. When a module or package is contained within another
package it is possible to make a relative import within the same top package
without having to mention the package name. By using leading dots in the
specified module or package after @ref{14ac,,from} you can specify how high to
traverse up the current package hierarchy without specifying exact names. One
leading dot means the current package where the module making the import
exists. Two dots means up one package level. Three dots is up two levels, etc.
So if you execute @code{from . import mod} from a module in the @code{pkg} package
then you will end up importing @code{pkg.mod}. If you execute @code{from ..subpkg2
import mod} from within @code{pkg.subpkg1} you will import @code{pkg.subpkg2.mod}.
The specification for relative imports is contained in
the @ref{230d,,Package Relative Imports} section.

@ref{735,,importlib.import_module()} is provided to support applications that
determine dynamically the modules to be loaded.

引發一個附帶引數 @code{module}、@code{filename}、@code{sys.path}、@code{sys.meta_path}、@code{sys.path_hooks} 的@ref{1b70,,稽核事件} @code{import}。

@menu
* Future statements:: 

@end menu

@node Future statements,,,import 陳述式
@anchor{reference/simple_stmts future}@anchor{45b}@anchor{reference/simple_stmts future-statements}@anchor{23c2}
@subsubsection Future statements


@geindex future;statement（陳述式）
@geindex __future__;future statement（future 陳述式）

A `future statement' is a directive to the compiler that a particular
module should be compiled using syntax or semantics that will be available in a
specified future release of Python where the feature becomes standard.

The future statement is intended to ease migration to future versions of Python
that introduce incompatible changes to the language.  It allows use of the new
features on a per-module basis before the release in which the feature becomes
standard.

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-future_stmt}@anchor{23a6}future_stmt: "from" "__future__" "import" @ref{23c3,,feature} ["as" @ref{2185,,identifier}]
             ("," @ref{23c3,,feature} ["as" @ref{2185,,identifier}])*
             | "from" "__future__" "import" "(" @ref{23c3,,feature} ["as" @ref{2185,,identifier}]
             ("," @ref{23c3,,feature} ["as" @ref{2185,,identifier}])* [","] ")"
@anchor{reference/simple_stmts grammar-token-python-grammar-feature}@anchor{23c3}feature:     @ref{2185,,identifier}
@end example

A future statement must appear near the top of the module.  The only lines that
can appear before a future statement are:


@itemize *

@item 
the module docstring (if any),

@item 
comments,

@item 
blank lines, and

@item 
other future statements.
@end itemize

The only feature that requires using the future statement is
@code{annotations} (see 
@geindex Python Enhancement Proposals; PEP 563
PEP 563@footnote{https://peps.python.org/pep-0563/}).

All historical features enabled by the future statement are still recognized
by Python 3.  The list includes @code{absolute_import}, @code{division},
@code{generators}, @code{generator_stop}, @code{unicode_literals},
@code{print_function}, @code{nested_scopes} and @code{with_statement}.  They are
all redundant because they are always enabled, and only kept for
backwards compatibility.

A future statement is recognized and treated specially at compile time: Changes
to the semantics of core constructs are often implemented by generating
different code.  It may even be the case that a new feature introduces new
incompatible syntax (such as a new reserved word), in which case the compiler
may need to parse the module differently.  Such decisions cannot be pushed off
until runtime.

For any given release, the compiler knows which feature names have been defined,
and raises a compile-time error if a future statement contains a feature not
known to it.

The direct runtime semantics are the same as for any import statement: there is
a standard module @ref{0,,__future__}, described later, and it will be imported in
the usual way at the time the future statement is executed.

The interesting runtime semantics depend on the specific feature enabled by the
future statement.

Note that there is nothing special about the statement:

@example
import __future__ [as name]
@end example

That is not a future statement; it's an ordinary import statement with no
special semantics or syntax restrictions.

Code compiled by calls to the built-in functions @ref{49d,,exec()} and @ref{4ac,,compile()}
that occur in a module @code{M} containing a future statement will, by default,
use the new syntax or semantics associated with the future statement.  This can
be controlled by optional arguments to @ref{4ac,,compile()} --- see the documentation
of that function for details.

A future statement typed at an interactive interpreter prompt will take effect
for the rest of the interpreter session.  If an interpreter is started with the
@ref{16cf,,-i} option, is passed a script name to execute, and the script includes
a future statement, it will be in effect in the interactive session started
after the script is executed.


@subsubheading 也參考



@table @asis

@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


@node global 陳述式,nonlocal 陳述式,import 陳述式,簡單陳述式
@anchor{reference/simple_stmts global}@anchor{4a7}@anchor{reference/simple_stmts the-global-statement}@anchor{23c4}
@subsection @code{global} 陳述式


@geindex statement（陳述式）;global
@geindex global;name（名稱）;binding（繫結）
@geindex @comma{} （逗號）;identifier list（識別符號清單）

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-global_stmt}@anchor{23a7}global_stmt: "global" @ref{2185,,identifier} ("," @ref{2185,,identifier})*
@end example

The @ref{4a7,,global} statement causes the listed identifiers to be interpreted
as globals. It would be impossible to assign to a global variable without
@code{global}, although free variables may refer to globals without being
declared global.

The @code{global} statement applies to the entire current scope
(module, function body or class definition).
A @ref{18e,,SyntaxError} is raised if a variable is used or
assigned to prior to its global declaration in the scope.

At the module level, all variables are global, so a @code{global}
statement has no effect.
However, variables must still not be used or
assigned to prior to their @code{global} declaration.
This requirement is relaxed in the interactive prompt (@ref{48c,,REPL}).

@geindex built-in function（內建函式）;exec
@geindex built-in function（內建函式）;eval
@geindex built-in function（內建函式）;compile（編譯）

`Programmer's note:' @ref{4a7,,global} is a directive to the parser.  It
applies only to code parsed at the same time as the @code{global} statement.
In particular, a @code{global} statement contained in a string or code
object supplied to the built-in @ref{49d,,exec()} function does not affect the code
block `containing' the function call, and code contained in such a string is
unaffected by @code{global} statements in the code containing the function
call.  The same applies to the @ref{49e,,eval()} and @ref{4ac,,compile()} functions.

@node nonlocal 陳述式,type 陳述式,global 陳述式,簡單陳述式
@anchor{reference/simple_stmts nonlocal}@anchor{14a8}@anchor{reference/simple_stmts the-nonlocal-statement}@anchor{23c5}
@subsection @code{nonlocal} 陳述式


@geindex statement（陳述式）;nonlocal
@geindex @comma{} （逗號）;identifier list（識別符號清單）

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-nonlocal_stmt}@anchor{23a8}nonlocal_stmt: "nonlocal" @ref{2185,,identifier} ("," @ref{2185,,identifier})*
@end example

When the definition of a function or class is nested (enclosed) within
the definitions of other functions, its nonlocal scopes are the local
scopes of the enclosing functions. The @ref{14a8,,nonlocal} statement
causes the listed identifiers to refer to names previously bound in
nonlocal scopes. It allows encapsulated code to rebind such nonlocal
identifiers.  If a name is bound in more than one nonlocal scope, the
nearest binding is used. If a name is not bound in any nonlocal scope,
or if there is no nonlocal scope, a @ref{18e,,SyntaxError} is raised.

The @ref{14a8,,nonlocal} statement applies to the entire scope of a function or
class body. A @ref{18e,,SyntaxError} is raised if a variable is used or
assigned to prior to its nonlocal declaration in the scope.


@subsubheading 也參考



@table @asis

@geindex Python Enhancement Proposals; PEP 3104

@item PEP 3104@footnote{https://peps.python.org/pep-3104/} - Access to Names in Outer Scopes

The specification for the @ref{14a8,,nonlocal} statement.
@end table


`Programmer's note:' @ref{14a8,,nonlocal} is a directive to the parser
and applies only to code parsed along with it.  See the note for the
@ref{4a7,,global} statement.

@node type 陳述式,,nonlocal 陳述式,簡單陳述式
@anchor{reference/simple_stmts the-type-statement}@anchor{23c6}@anchor{reference/simple_stmts type}@anchor{665}
@subsection @code{type} 陳述式


@geindex statement（陳述式）;type

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-type_stmt}@anchor{23a9}type_stmt: 'type' @ref{2185,,identifier} [@ref{23c7,,type_params}] "=" @ref{182,,expression}
@end example

The @code{type} statement declares a type alias, which is an instance
of @ref{2ae,,typing.TypeAliasType}.

For example, the following statement creates a type alias:

@example
type Point = tuple[float, float]
@end example

This code is roughly equivalent to:

@example
annotation-def VALUE_OF_Point():
    return tuple[float, float]
Point = typing.TypeAliasType("Point", VALUE_OF_Point())
@end example

@code{annotation-def} indicates an @ref{4a6,,annotation scope}, which behaves
mostly like a function, but with several small differences.

The value of the
type alias is evaluated in the annotation scope. It is not evaluated when the
type alias is created, but only when the value is accessed through the type alias's
@code{__value__} attribute (see @ref{67e,,Lazy evaluation}).
This allows the type alias to refer to names that are not yet defined.

Type aliases may be made generic by adding a @ref{5a7,,type parameter list}
after the name. See @ref{67d,,Generic type aliases} for more.

@code{type} is a @ref{a06,,soft keyword}.


在 3.12 版被加入.



@subsubheading 也參考



@table @asis

@geindex Python Enhancement Proposals; PEP 695

@item PEP 695@footnote{https://peps.python.org/pep-0695/} - Type Parameter Syntax

Introduced the @code{type} statement and syntax for
generic classes and functions.
@end table


@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/compound_stmts doc}@anchor{23c8}@anchor{reference/compound_stmts compound}@anchor{23c9}@anchor{reference/compound_stmts compound-statements}@anchor{23ca}@anchor{reference/compound_stmts translation-repo}@anchor{23cb}
@section 複合陳述式


@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{181,,if}, @ref{18d6,,while} and @ref{348,,for} statements implement
traditional control flow constructs.  @ref{8f0,,try} specifies exception
handlers and/or cleanup code for a group of statements, while the
@ref{186,,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 ; （分號）

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{181,,if} clause a following
@ref{17c,,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{1170,,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{23cc}compound_stmt: @ref{23cd,,if_stmt}
               | @ref{23ce,,while_stmt}
               | @ref{23cf,,for_stmt}
               | @ref{23d0,,try_stmt}
               | @ref{23d1,,with_stmt}
               | @ref{23d2,,match_stmt}
               | @ref{23d3,,funcdef}
               | @ref{23d4,,classdef}
               | @ref{23d5,,async_with_stmt}
               | @ref{23d6,,async_for_stmt}
               | @ref{23d7,,async_funcdef}
@anchor{reference/compound_stmts grammar-token-python-grammar-suite}@anchor{23d8}suite:         @ref{23d9,,stmt_list} NEWLINE | NEWLINE INDENT @ref{23da,,statement}+ DEDENT
@anchor{reference/compound_stmts grammar-token-python-grammar-statement}@anchor{23da}statement:     @ref{23d9,,stmt_list} NEWLINE | @ref{23cc,,compound_stmt}
@anchor{reference/compound_stmts grammar-token-python-grammar-stmt_list}@anchor{23d9}stmt_list:     @ref{2398,,simple_stmt} (";" @ref{2398,,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{17c,,else}' problem is solved in Python by requiring nested
@ref{181,,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{181}@anchor{reference/compound_stmts elif}@anchor{17b}
@menu
* if 陳述式: if 陳述式<2>. 
* while 陳述式:: 
* for 陳述式: for 陳述式<2>. 
* try 陳述式:: 
* with 陳述式:: 
* match 陳述式: match 陳述式<2>. 
* 函式定義:: 
* 類別定義:: 
* 協程: 協程<2>. 
* Type parameter lists:: 
* 註釋:: 

@end menu

@node if 陳述式<2>,while 陳述式,,複合陳述式
@anchor{reference/compound_stmts else}@anchor{17c}@anchor{reference/compound_stmts the-if-statement}@anchor{23db}
@subsection @code{if} 陳述式


@geindex statement（陳述式）;if
@geindex keyword（關鍵字）;elif
@geindex keyword（關鍵字）;else
@geindex ; （冒號）;compound statement（複合陳述式）

The @ref{181,,if} statement is used for conditional execution:

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-if_stmt}@anchor{23cd}if_stmt: "if" @ref{22dd,,assignment_expression} ":" @ref{23d8,,suite}
         ("elif" @ref{22dd,,assignment_expression} ":" @ref{23d8,,suite})*
         ["else" ":" @ref{23d8,,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{2380,,Boolean operations} for the definition of
true and false); then that suite is executed (and no other part of the
@ref{181,,if} statement is executed or evaluated).  If all expressions are
false, the suite of the @ref{17c,,else} clause, if present, is executed.

@node while 陳述式,for 陳述式<2>,if 陳述式<2>,複合陳述式
@anchor{reference/compound_stmts the-while-statement}@anchor{23dc}@anchor{reference/compound_stmts while}@anchor{18d6}
@subsection @code{while} 陳述式


@geindex statement（陳述式）;while
@geindex keyword（關鍵字）;else
@geindex loop（迴圈）;statement（陳述式）
@geindex ; （冒號）;compound statement（複合陳述式）

The @ref{18d6,,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{23ce}while_stmt: "while" @ref{22dd,,assignment_expression} ":" @ref{23d8,,suite}
            ["else" ":" @ref{23d8,,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{17f,,break} statement executed in the first suite terminates the loop
without executing the @code{else} clause's suite.  A @ref{180,,continue}
statement executed in the first suite skips the rest of the suite and goes back
to testing the expression.

@node for 陳述式<2>,try 陳述式,while 陳述式,複合陳述式
@anchor{reference/compound_stmts for}@anchor{348}@anchor{reference/compound_stmts the-for-statement}@anchor{23dd}
@subsection @code{for} 陳述式


@geindex statement（陳述式）;for
@geindex keyword（關鍵字）;in
@geindex keyword（關鍵字）;else
@geindex target;list（串列）
@geindex loop（迴圈）;statement（陳述式）
@geindex object（物件）;sequence（序列）
@geindex ; （冒號）;compound statement（複合陳述式）

The @ref{348,,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{23cf}for_stmt: "for" @ref{232f,,target_list} "in" @ref{238e,,starred_expression_list} ":" @ref{23d8,,suite}
          ["else" ":" @ref{23d8,,suite}]
@end example

The @ref{238e,,starred_expression_list} expression is evaluated
once; it should yield an @ref{1428,,iterable} object. An @ref{4c3,,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{22d7,,Assignment statements}), 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{17f,,break} statement executed in the first suite terminates the loop
without executing the @code{else} clause's suite.  A @ref{180,,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{b34,,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 try 陳述式,with 陳述式,for 陳述式<2>,複合陳述式
@anchor{reference/compound_stmts the-try-statement}@anchor{23de}@anchor{reference/compound_stmts try}@anchor{8f0}
@subsection @code{try} 陳述式


@geindex statement（陳述式）;try
@geindex keyword（關鍵字）;except
@geindex keyword（關鍵字）;finally
@geindex keyword（關鍵字）;else
@geindex keyword（關鍵字）;as
@geindex ; （冒號）;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{23d0}try_stmt:  @ref{23df,,try1_stmt} | @ref{23e0,,try2_stmt} | @ref{23e1,,try3_stmt}
@anchor{reference/compound_stmts grammar-token-python-grammar-try1_stmt}@anchor{23df}try1_stmt: "try" ":" @ref{23d8,,suite}
           ("except" [@ref{182,,expression} ["as" @ref{2185,,identifier}]] ":" @ref{23d8,,suite})+
           ["else" ":" @ref{23d8,,suite}]
           ["finally" ":" @ref{23d8,,suite}]
@anchor{reference/compound_stmts grammar-token-python-grammar-try2_stmt}@anchor{23e0}try2_stmt: "try" ":" @ref{23d8,,suite}
           ("except" "*" @ref{182,,expression} ["as" @ref{2185,,identifier}] ":" @ref{23d8,,suite})+
           ["else" ":" @ref{23d8,,suite}]
           ["finally" ":" @ref{23d8,,suite}]
@anchor{reference/compound_stmts grammar-token-python-grammar-try3_stmt}@anchor{23e1}try3_stmt: "try" ":" @ref{23d8,,suite}
           "finally" ":" @ref{23d8,,suite}
@end example

Additional information on exceptions can be found in section @ref{22e3,,例外},
and information on using the @ref{7fc,,raise} statement to generate exceptions
may be found in section @ref{7fc,,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 子句:: 
* except* 子句:: 
* else 子句:: 
* finally 子句:: 

@end menu

@node except 子句,except* 子句,,try 陳述式
@anchor{reference/compound_stmts except}@anchor{1ab}@anchor{reference/compound_stmts except-clause}@anchor{23e2}
@subsubsection @code{except} 子句


The @code{except} clause(s) specify one or more exception handlers. When no
exception occurs in the @ref{8f0,,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{13b7,,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{1b0,,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{8f0,,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{8f0,,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{df,,sys} module, where it can be accessed
from within the body of the @code{except} clause by calling
@ref{894,,sys.exception()}. When leaving an exception handler, the exception
stored in the @ref{df,,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* 子句,else 子句,except 子句,try 陳述式
@anchor{reference/compound_stmts except-star}@anchor{1ac}@anchor{reference/compound_stmts id2}@anchor{23e3}
@subsubsection @code{except*} 子句


The @code{except*} clause(s) specify one or more handlers for groups of
exceptions (@ref{560,,BaseExceptionGroup} instances). A @ref{8f0,,try} statement
can have either @ref{1ab,,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{198,,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{1847,,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{894,,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{8f0,,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{560,,BaseExceptionGroup}:

@example
>>> try:
...     raise BlockingIOError
... except* BlockingIOError as e:
...     print(repr(e))
...
ExceptionGroup('@w{'}, (BlockingIOError()))
@end example

@ref{17f,,break}, @ref{180,,continue} and @ref{1af,,return}
cannot appear in an @code{except*} clause.

@geindex keyword（關鍵字）;else
@geindex statement（陳述式）;return （回傳）
@geindex statement（陳述式）;break
@geindex statement（陳述式）;continue

@node else 子句,finally 子句,except* 子句,try 陳述式
@anchor{reference/compound_stmts else-clause}@anchor{23e4}@anchor{reference/compound_stmts except-else}@anchor{23e5}
@subsubsection @code{else} 子句


The optional @code{else} clause is executed if the control flow leaves the
@ref{8f0,,try} suite, no exception was raised, and no @ref{1af,,return},
@ref{180,,continue}, or @ref{17f,,break} statement was executed.  Exceptions in
the @code{else} clause are not handled by the preceding @ref{1ab,,except}
clauses.

@geindex keyword（關鍵字）;finally

@node finally 子句,,else 子句,try 陳述式
@anchor{reference/compound_stmts finally}@anchor{1b0}@anchor{reference/compound_stmts finally-clause}@anchor{23e6}
@subsubsection @code{finally} 子句


If @code{finally} is present, it specifies a 'cleanup' handler.  The
@ref{8f0,,try} clause is executed, including any @ref{1ab,,except}
and @ref{23e5,,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{1af,,return}, @ref{17f,,break}
or @ref{180,,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{1af,,return}, @ref{17f,,break} or @ref{180,,continue} statement is
executed in the @ref{8f0,,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{1af,,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{180,,continue} statement was illegal in the
@code{finally} clause due to a problem with the implementation.



在 3.14 版的變更: The compiler emits a @ref{1ae,,SyntaxWarning} when a @ref{1af,,return},
@ref{17f,,break} or @ref{180,,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{186}
@node with 陳述式,match 陳述式<2>,try 陳述式,複合陳述式
@anchor{reference/compound_stmts as}@anchor{23e7}@anchor{reference/compound_stmts the-with-statement}@anchor{23e8}
@subsection @code{with} 陳述式


@geindex statement（陳述式）;with
@geindex keyword（關鍵字）;as
@geindex as;with statement（with 陳述式）
@geindex @comma{} （逗號）;with statement（with 陳述式）
@geindex ; （冒號）;compound statement（複合陳述式）

The @ref{186,,with} statement is used to wrap the execution of a block with
methods defined by a context manager (see section @ref{22ba,,With 陳述式的情境管理器}).
This allows common @ref{8f0,,try}...@ref{1ab,,except}...@ref{1b0,,finally}
usage patterns to be encapsulated for convenient reuse.

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-with_stmt}@anchor{23d1}with_stmt:          "with" ( "(" @ref{23e9,,with_stmt_contents} ","? ")" | @ref{23e9,,with_stmt_contents} ) ":" @ref{23d8,,suite}
@anchor{reference/compound_stmts grammar-token-python-grammar-with_stmt_contents}@anchor{23e9}with_stmt_contents: @ref{23ea,,with_item} ("," @ref{23ea,,with_item})*
@anchor{reference/compound_stmts grammar-token-python-grammar-with_item}@anchor{23ea}with_item:          @ref{182,,expression} ["as" @ref{23ad,,target}]
@end example

The execution of the @ref{186,,with} statement with one "item" proceeds as follows:


@enumerate 

@item 
The context expression (the expression given in the
@ref{23ea,,with_item}) is evaluated to obtain a context manager.

@item 
The context manager's @ref{7dd,,__enter__()} is loaded for later use.

@item 
The context manager's @ref{1501,,__exit__()} is loaded for later use.

@item 
The context manager's @ref{7dd,,__enter__()} method is invoked.

@item 
If a target was included in the @ref{186,,with} statement, the return value
from @ref{7dd,,__enter__()} is assigned to it.

@cartouche
@quotation 備註 
The @ref{186,,with} statement guarantees that if the @ref{7dd,,__enter__()}
method returns without an error, then @ref{1501,,__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{1501,,__exit__()} method is invoked.  If an exception
caused the suite to be exited, its type, value, and traceback are passed as
arguments to @ref{1501,,__exit__()}. Otherwise, three @ref{87e,,None} arguments are
supplied.

If the suite was exited due to an exception, and the return value from the
@ref{1501,,__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{186,,with} statement.

If the suite was exited for any reason other than an exception, the return
value from @ref{1501,,__exit__()} is ignored, and execution proceeds at the normal
location for the kind of exit that was taken.
@end enumerate

以下程式碼：

@example
with EXPRESSION as TARGET:
    SUITE
@end example

在語義上等同於：

@example
manager = (EXPRESSION)
enter = type(manager).__enter__
exit = type(manager).__exit__
value = enter(manager)
hit_except = False

try:
    TARGET = value
    SUITE
except:
    hit_except = True
    if not exit(manager, *sys.exc_info()):
        raise
finally:
    if not hit_except:
        exit(manager, None, None, None)
@end example

With more than one item, the context managers are processed as if multiple
@ref{186,,with} statements were nested:

@example
with A() as a, B() as b:
    SUITE
@end example

在語義上等同於：

@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/} - "with" 陳述式

The specification, background, and examples for the Python @ref{186,,with}
statement.
@end table

@anchor{reference/compound_stmts match}@anchor{a07}
@node match 陳述式<2>,函式定義,with 陳述式,複合陳述式
@anchor{reference/compound_stmts case}@anchor{23eb}@anchor{reference/compound_stmts the-match-statement}@anchor{23ec}
@subsection @code{match} 陳述式


@geindex statement（陳述式）;match
@geindex keyword（關鍵字）;case
@geindex pattern matching（模式匹配）
@geindex keyword（關鍵字）;if
@geindex keyword（關鍵字）;as
@geindex match;case
@geindex as;match statement（匹配陳述式）
@geindex ; （冒號）;compound statement（複合陳述式）


在 3.10 版被加入.


The match statement is used for pattern matching.  Syntax:

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-match_stmt}@anchor{23d2}match_stmt:   'match' @ref{23ed,,subject_expr} ":" NEWLINE INDENT @ref{23ee,,case_block}+ DEDENT
@anchor{reference/compound_stmts grammar-token-python-grammar-subject_expr}@anchor{23ed}subject_expr: `!star_named_expression` "," `!star_named_expressions`?
              | `!named_expression`
@anchor{reference/compound_stmts grammar-token-python-grammar-case_block}@anchor{23ee}case_block:   'case' @ref{23ef,,patterns} [@ref{23f0,,guard}] ":" `!block`
@end example

@cartouche
@quotation 備註 
This section uses single quotes to denote
@ref{a06,,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{a06,,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,,match 陳述式<2>
@anchor{reference/compound_stmts overview}@anchor{23f1}
@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{23f2,,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,match 陳述式<2>
@anchor{reference/compound_stmts guards}@anchor{23f3}
@subsubsection Guards


@geindex guard

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-guard}@anchor{23f0}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{181,,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,match 陳述式<2>
@anchor{reference/compound_stmts irrefutable-case}@anchor{23f4}@anchor{reference/compound_stmts irrefutable-case-blocks}@anchor{23f5}
@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{23f6,,AS Patterns} whose left-hand side is irrefutable

@item 
@ref{23f7,,OR Patterns} containing at least one irrefutable pattern

@item 
@ref{23f8,,Capture Patterns}

@item 
@ref{a08,,Wildcard Patterns}

@item 
parenthesized irrefutable patterns
@end itemize

@node Patterns,,Irrefutable Case Blocks,match 陳述式<2>
@anchor{reference/compound_stmts patterns}@anchor{23f9}
@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{23ef}patterns:       @ref{23fa,,open_sequence_pattern} | @ref{23fb,,pattern}
@anchor{reference/compound_stmts grammar-token-python-grammar-pattern}@anchor{23fb}pattern:        @ref{23fc,,as_pattern} | @ref{23fd,,or_pattern}
@anchor{reference/compound_stmts grammar-token-python-grammar-closed_pattern}@anchor{23fe}closed_pattern: | @ref{23ff,,literal_pattern}
                | @ref{2400,,capture_pattern}
                | @ref{2401,,wildcard_pattern}
                | @ref{2402,,value_pattern}
                | @ref{2403,,group_pattern}
                | @ref{2404,,sequence_pattern}
                | @ref{2405,,mapping_pattern}
                | @ref{2406,,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{2407}@anchor{reference/compound_stmts or-patterns}@anchor{23f7}
@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{23fd}or_pattern: "|".@ref{23fe,,closed_pattern}+
@end example

Only the final subpattern may be @ref{23f4,,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{23f6}@anchor{reference/compound_stmts id4}@anchor{2408}
@subsubsection AS Patterns


An AS pattern matches an OR pattern on the left of the @ref{23e7,,as}
keyword against a subject.  Syntax:

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-as_pattern}@anchor{23fc}as_pattern: @ref{23fd,,or_pattern} "as" @ref{2400,,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{2409}@anchor{reference/compound_stmts literal-patterns}@anchor{240a}
@subsubsection Literal Patterns


A literal pattern corresponds to most
@ref{218c,,literals} in Python.  Syntax:

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-literal_pattern}@anchor{23ff}literal_pattern: @ref{240b,,signed_number}
                 | @ref{240b,,signed_number} "+" NUMBER
                 | @ref{240b,,signed_number} "-" NUMBER
                 | @ref{2327,,strings}
                 | "None"
                 | "True"
                 | "False"
@anchor{reference/compound_stmts grammar-token-python-grammar-signed_number}@anchor{240b}signed_number:   ["-"] NUMBER
@end example

The rule @code{strings} and the token @code{NUMBER} are defined in the
@ref{240c,,standard Python grammar}.  Triple-quoted strings are
supported.  Raw strings and byte strings are supported.  @ref{19a,,f-string（f 字串）}
and @ref{1780,,t-string（t 字串）} are not supported.

The forms @code{signed_number '+' NUMBER} and @code{signed_number '-' NUMBER} are
for expressing @ref{21d0,,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{34a,,is} operator is used.

@node Capture Patterns,Wildcard Patterns,Literal Patterns,Patterns
@anchor{reference/compound_stmts capture-patterns}@anchor{23f8}@anchor{reference/compound_stmts id6}@anchor{240d}
@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{2400}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{2401,,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{4a7,,global} or @ref{14a8,,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{240e}@anchor{reference/compound_stmts wildcard-patterns}@anchor{a08}
@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{2401}wildcard_pattern: '_'
@end example

@code{_} is a @ref{a06,,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{240f}@anchor{reference/compound_stmts value-patterns}@anchor{2410}
@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{2402}value_pattern: @ref{2411,,attr}
@anchor{reference/compound_stmts grammar-token-python-grammar-attr}@anchor{2411}attr:          @ref{2412,,name_or_attr} "." NAME
@anchor{reference/compound_stmts grammar-token-python-grammar-name_or_attr}@anchor{2412}name_or_attr:  @ref{2411,,attr} | NAME
@end example

The dotted name in the pattern is looked up using standard Python
@ref{22da,,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{2413}@anchor{reference/compound_stmts id9}@anchor{2414}
@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{2403}group_pattern: "(" @ref{23fb,,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{2415}@anchor{reference/compound_stmts sequence-patterns}@anchor{2416}
@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{2404}sequence_pattern:       "[" [@ref{2417,,maybe_sequence_pattern}] "]"
                        | "(" [@ref{23fa,,open_sequence_pattern}] ")"
@anchor{reference/compound_stmts grammar-token-python-grammar-open_sequence_pattern}@anchor{23fa}open_sequence_pattern:  @ref{2418,,maybe_star_pattern} "," [@ref{2417,,maybe_sequence_pattern}]
@anchor{reference/compound_stmts grammar-token-python-grammar-maybe_sequence_pattern}@anchor{2417}maybe_sequence_pattern: ",".@ref{2418,,maybe_star_pattern}+ ","?
@anchor{reference/compound_stmts grammar-token-python-grammar-maybe_star_pattern}@anchor{2418}maybe_star_pattern:     @ref{2419,,star_pattern} | @ref{23fb,,pattern}
@anchor{reference/compound_stmts grammar-token-python-grammar-star_pattern}@anchor{2419}star_pattern:           "*" (@ref{2400,,capture_pattern} | @ref{2401,,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{2413,,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{13c5,,collections.abc.Sequence}

@item 
a Python class that has been registered as @ref{13c5,,collections.abc.Sequence}

@item 
a builtin class that has its (CPython) @ref{1b5b,,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{4b9,,array.array}

@item 
@ref{7ed,,collections.deque}

@item 
@ref{24d,,list}

@item 
@ref{165,,memoryview}

@item 
@ref{b34,,range}

@item 
@ref{60c,,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{839,,len()} (i.e. via the @ref{2260,,__len__()} protocol).
This length may be cached by the interpreter in a similar manner as
@ref{2410,,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{241a}@anchor{reference/compound_stmts mapping-patterns}@anchor{241b}
@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{2405}mapping_pattern:     "@{" [@ref{241c,,items_pattern}] "@}"
@anchor{reference/compound_stmts grammar-token-python-grammar-items_pattern}@anchor{241c}items_pattern:       ",".@ref{241d,,key_value_pattern}+ ","?
@anchor{reference/compound_stmts grammar-token-python-grammar-key_value_pattern}@anchor{241d}key_value_pattern:   (@ref{23ff,,literal_pattern} | @ref{2402,,value_pattern}) ":" @ref{23fb,,pattern}
                     | @ref{241e,,double_star_pattern}
@anchor{reference/compound_stmts grammar-token-python-grammar-double_star_pattern}@anchor{241e}double_star_pattern: "**" @ref{2400,,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{18e,,SyntaxError}. Two keys that otherwise have the same value will
raise a @ref{2eb,,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{abe,,collections.abc.Mapping}

@item 
a Python class that has been registered as @ref{abe,,collections.abc.Mapping}

@item 
a builtin class that has its (CPython) @ref{1b5a,,Py_TPFLAGS_MAPPING} bit set

@item 
a class that inherits from any of the above
@end itemize

The standard library classes @ref{183,,dict} and @ref{691,,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{18e,,SyntaxError} is raised for duplicate literal
values; or a @ref{2eb,,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{13be,,__missing__()}
or @ref{582,,__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{241f}@anchor{reference/compound_stmts id14}@anchor{2420}
@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{2406}class_pattern:       @ref{2412,,name_or_attr} "(" [@ref{2421,,pattern_arguments} ","?] ")"
@anchor{reference/compound_stmts grammar-token-python-grammar-pattern_arguments}@anchor{2421}pattern_arguments:   @ref{2422,,positional_patterns} ["," @ref{2423,,keyword_patterns}]
                     | @ref{2423,,keyword_patterns}
@anchor{reference/compound_stmts grammar-token-python-grammar-positional_patterns}@anchor{2422}positional_patterns: ",".@ref{23fb,,pattern}+
@anchor{reference/compound_stmts grammar-token-python-grammar-keyword_patterns}@anchor{2423}keyword_patterns:    ",".@ref{2424,,keyword_pattern}+
@anchor{reference/compound_stmts grammar-token-python-grammar-keyword_pattern}@anchor{2424}keyword_pattern:     NAME "=" @ref{23fb,,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{f3f,,type} , raise
@ref{198,,TypeError}.

@item 
If the subject value is not an instance of @code{name_or_attr} (tested via
@ref{2ad,,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:

I. The keyword is looked up as an attribute on the subject.

@quotation


@itemize *

@item 
If this raises an exception other than @ref{5e8,,AttributeError}, the
exception bubbles up.

@item 
If this raises @ref{5e8,,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
@end quotation

II. If all keyword patterns succeed, the class pattern succeeds.

If any positional patterns are present, they are converted to keyword
patterns using the @ref{1b75,,__match_args__} attribute on the class
@code{name_or_attr} before matching:

I. The equivalent of @code{getattr(cls, "__match_args__", ())} is called.

@quotation


@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{198,,TypeError} is raised.

@item 
If there are more positional patterns than @code{len(cls.__match_args__)},
@ref{198,,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{198,,TypeError} is raised.

@item 
If there are duplicate keywords, @ref{198,,TypeError} is raised.
@end itemize


@subsubheading 也參考


@ref{22bd,,Customizing positional arguments in class pattern matching}

@end quotation


@table @asis

@item II. Once all positional patterns have been converted to keyword patterns,

the match proceeds as if there were only keyword patterns.
@end table

For the following built-in types the handling of positional subpatterns is
different:


@itemize *

@item 
@ref{3c1,,bool}

@item 
@ref{343,,bytearray}

@item 
@ref{192,,bytes}

@item 
@ref{183,,dict}

@item 
@ref{196,,float}

@item 
@ref{7eb,,frozenset}

@item 
@ref{19b,,int}

@item 
@ref{24d,,list}

@item 
@ref{184,,set}

@item 
@ref{169,,str}

@item 
@ref{60c,,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{1ee1}
@node 函式定義,類別定義,match 陳述式<2>,複合陳述式
@anchor{reference/compound_stmts def}@anchor{164f}@anchor{reference/compound_stmts function-definitions}@anchor{2425}
@subsection 函式定義


@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 () （圓括號）;function definition（函式定義）
@geindex @comma{} （逗號）;parameter list（參數列表）
@geindex ; （冒號）;compound statement（複合陳述式）

A function definition defines a user-defined function object (see section
@ref{21e4,,標準型別階層}):

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-funcdef}@anchor{23d3}funcdef:                   [@ref{2426,,decorators}] "def" @ref{2427,,funcname} [@ref{23c7,,type_params}] "(" [@ref{238b,,parameter_list}] ")"
                           ["->" @ref{182,,expression}] ":" @ref{23d8,,suite}
@anchor{reference/compound_stmts grammar-token-python-grammar-decorators}@anchor{2426}decorators:                @ref{2428,,decorator}+
@anchor{reference/compound_stmts grammar-token-python-grammar-decorator}@anchor{2428}decorator:                 "@@" @ref{22dd,,assignment_expression} NEWLINE
@anchor{reference/compound_stmts grammar-token-python-grammar-parameter_list}@anchor{238b}parameter_list:            @ref{2429,,defparameter} ("," @ref{2429,,defparameter})* "," "/" ["," [@ref{242a,,parameter_list_no_posonly}]]
                             | @ref{242a,,parameter_list_no_posonly}
@anchor{reference/compound_stmts grammar-token-python-grammar-parameter_list_no_posonly}@anchor{242a}parameter_list_no_posonly: @ref{2429,,defparameter} ("," @ref{2429,,defparameter})* ["," [@ref{242b,,parameter_list_starargs}]]
                           | @ref{242b,,parameter_list_starargs}
@anchor{reference/compound_stmts grammar-token-python-grammar-parameter_list_starargs}@anchor{242b}parameter_list_starargs:   "*" [@ref{242c,,star_parameter}] ("," @ref{2429,,defparameter})* ["," [@ref{242d,,parameter_star_kwargs}]]
                           | "*" ("," @ref{2429,,defparameter})+ ["," [@ref{242d,,parameter_star_kwargs}]]
                           | @ref{242d,,parameter_star_kwargs}
@anchor{reference/compound_stmts grammar-token-python-grammar-parameter_star_kwargs}@anchor{242d}parameter_star_kwargs:     "**" @ref{242e,,parameter} [","]
@anchor{reference/compound_stmts grammar-token-python-grammar-parameter}@anchor{242e}parameter:                 @ref{2185,,identifier} [":" @ref{182,,expression}]
@anchor{reference/compound_stmts grammar-token-python-grammar-star_parameter}@anchor{242c}star_parameter:            @ref{2185,,identifier} [":" ["*"] @ref{182,,expression}]
@anchor{reference/compound_stmts grammar-token-python-grammar-defparameter}@anchor{2429}defparameter:              @ref{242e,,parameter} ["=" @ref{182,,expression}]
@anchor{reference/compound_stmts grammar-token-python-grammar-funcname}@anchor{2427}funcname:                  @ref{2185,,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{13da,,__doc__} attribute and
therefore the function's @ref{242f,,docstring}.
}

@geindex @@ （在）;function definition（函式定義）

A function definition may be wrapped by one or more @ref{932,,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

大致等價於：

@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{22dd,,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{5a7,,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{21ff,,__type_params__}
attribute. See @ref{67b,,Generic functions} for more.


在 3.12 版的變更: Type parameter lists are new in Python 3.12.


@geindex default（預設）;parameter（參數）;value（值）
@geindex argument（引數）;function definition（函式定義）
@geindex = （等號）;function definition（函式定義）

When one or more @ref{21fd,,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{673,,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 / （斜線）;function definition（函式定義）
@geindex * （星號）;function definition（函式定義）
@geindex **;function definition（函式定義）

Function call semantics are described in more detail in section @ref{f78,,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 ; （冒號）;function annotations（函式註釋）

Parameters may have an @ref{1ee2,,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{2430,,註釋} 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{149e,,Lambdas}.  Note that the lambda expression is merely a shorthand for a
simplified function definition; a function defined in a "@ref{164f,,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{21f8,,Naming and binding} 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/} - 型別提示

定義註釋的標準意義：型別提示。

@geindex Python Enhancement Proposals; PEP 526

@item PEP 526@footnote{https://peps.python.org/pep-0526/} - 變數註釋的語法

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 類別定義,協程<2>,函式定義,複合陳述式
@anchor{reference/compound_stmts class}@anchor{14d8}@anchor{reference/compound_stmts class-definitions}@anchor{2431}
@subsection 類別定義


@geindex object（物件）;class（類別）
@geindex statement（陳述式）;class（類別）
@geindex class（類別）;definition（定義）
@geindex class（類別）;name（名稱）
@geindex name（名稱）;binding（綁定）
@geindex execution（執行）;frame
@geindex inheritance（繼承）
@geindex docstring（說明字串）
@geindex () （圓括號）;class definition（類別定義）
@geindex @comma{} （逗號）;expression list（運算式列表）
@geindex ; （冒號）;compound statement（複合陳述式）

A class definition defines a class object (see section @ref{21e4,,標準型別階層}):

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-classdef}@anchor{23d4}classdef:    [@ref{2426,,decorators}] "class" @ref{2432,,classname} [@ref{23c7,,type_params}] [@ref{2433,,inheritance}] ":" @ref{23d8,,suite}
@anchor{reference/compound_stmts grammar-token-python-grammar-inheritance}@anchor{2433}inheritance: "(" [@ref{235e,,argument_list}] ")"
@anchor{reference/compound_stmts grammar-token-python-grammar-classname}@anchor{2432}classname:   @ref{2185,,identifier}
@end example

A class definition is an executable statement.  The inheritance list usually
gives a list of base classes (see @ref{2270,,Metaclasses} 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{c75,,object}; hence,

@example
class Foo:
    pass
@end example

is equivalent to

@example
class Foo(object):
    pass
@end example

The class's suite is then executed in a new execution frame (see @ref{21f8,,Naming and binding}),
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{1f5c,,__doc__} item and therefore
the class's @ref{242f,,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{e52,,__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{2270,,metaclasses}.

@geindex @@ （在）;class definition（類別定義）

Classes can also be decorated: just like when decorating functions,

@example
@@f1(arg)
@@f2
class Foo: pass
@end example

大致等價於：

@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{22dd,,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{5a7,,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{2228,,__type_params__} attribute. See @ref{67a,,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{e44,,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/} - 類別裝飾器

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


@node 協程<2>,Type parameter lists,類別定義,複合陳述式
@anchor{reference/compound_stmts async}@anchor{933}@anchor{reference/compound_stmts coroutines}@anchor{2434}
@subsection 協程



在 3.5 版被加入.


@geindex statement（陳述式）;async def

@menu
* 協程函式定義:: 
* async for 陳述式:: 
* async with 陳述式:: 

@end menu

@node 協程函式定義,async for 陳述式,,協程<2>
@anchor{reference/compound_stmts async-def}@anchor{7e6}@anchor{reference/compound_stmts coroutine-function-definition}@anchor{2435}
@subsubsection 協程函式定義


@example
@anchor{reference/compound_stmts grammar-token-python-grammar-async_funcdef}@anchor{23d7}async_funcdef: [@ref{2426,,decorators}] "async" "def" @ref{2427,,funcname} "(" [@ref{238b,,parameter_list}] ")"
               ["->" @ref{182,,expression}] ":" @ref{23d8,,suite}
@end example

@geindex keyword（關鍵字）;async
@geindex keyword（關鍵字）;await

Execution of Python coroutines can be suspended and resumed at many points
(see @ref{6b2,,coroutine}). @ref{18d,,await} expressions, @ref{c98,,async for} and
@ref{185,,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{18e,,SyntaxError} to use a @code{yield from} expression inside the body
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 async for 陳述式,async with 陳述式,協程函式定義,協程<2>
@anchor{reference/compound_stmts async-for}@anchor{c98}@anchor{reference/compound_stmts the-async-for-statement}@anchor{2436}
@subsubsection @code{async for} 陳述式


@example
@anchor{reference/compound_stmts grammar-token-python-grammar-async_for_stmt}@anchor{23d6}async_for_stmt: "async" @ref{23cf,,for_stmt}
@end example

An @ref{f6f,,asynchronous iterable} provides an @code{__aiter__} method that directly
returns an @ref{4c2,,asynchronous iterator}, which can call asynchronous code in
its @code{__anext__} method.

The @code{async for} statement allows convenient iteration over asynchronous
iterables.

以下程式碼：

@example
async for TARGET in ITER:
    SUITE
else:
    SUITE2
@end example

Is semantically equivalent to:

@example
iter = (ITER)
iter = type(iter).__aiter__(iter)
running = True

while running:
    try:
        TARGET = await type(iter).__anext__(iter)
    except StopAsyncIteration:
        running = False
    else:
        SUITE
else:
    SUITE2
@end example

更多細節請見 @ref{df1,,__aiter__()} 與 @ref{17fd,,__anext__()}。

It is a @ref{18e,,SyntaxError} to use an @code{async for} statement outside the
body of a coroutine function.

@geindex statement（陳述式）;async with

@node async with 陳述式,,async for 陳述式,協程<2>
@anchor{reference/compound_stmts async-with}@anchor{185}@anchor{reference/compound_stmts the-async-with-statement}@anchor{2437}
@subsubsection @code{async with} 陳述式


@example
@anchor{reference/compound_stmts grammar-token-python-grammar-async_with_stmt}@anchor{23d5}async_with_stmt: "async" @ref{23d1,,with_stmt}
@end example

An @ref{7e8,,asynchronous context manager} is a @ref{1e1,,context manager} that is
able to suspend execution in its `enter' and `exit' methods.

以下程式碼：

@example
async with EXPRESSION as TARGET:
    SUITE
@end example

在語義上等同於：

@example
manager = (EXPRESSION)
aenter = type(manager).__aenter__
aexit = type(manager).__aexit__
value = await aenter(manager)
hit_except = False

try:
    TARGET = value
    SUITE
except:
    hit_except = True
    if not await aexit(manager, *sys.exc_info()):
        raise
finally:
    if not hit_except:
        await aexit(manager, None, None, None)
@end example

更多細節請見 @ref{22cd,,__aenter__()} 與 @ref{18f8,,__aexit__()}。

It is a @ref{18e,,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,註釋,協程<2>,複合陳述式
@anchor{reference/compound_stmts type-parameter-lists}@anchor{2438}@anchor{reference/compound_stmts type-params}@anchor{5a7}
@subsection Type parameter lists



在 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 parameter（型別參數）

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-type_params}@anchor{23c7}type_params:  "[" @ref{2439,,type_param} ("," @ref{2439,,type_param})* "]"
@anchor{reference/compound_stmts grammar-token-python-grammar-type_param}@anchor{2439}type_param:   @ref{243a,,typevar} | @ref{243b,,typevartuple} | @ref{243c,,paramspec}
@anchor{reference/compound_stmts grammar-token-python-grammar-typevar}@anchor{243a}typevar:      @ref{2185,,identifier} (":" @ref{182,,expression})? ("=" @ref{182,,expression})?
@anchor{reference/compound_stmts grammar-token-python-grammar-typevartuple}@anchor{243b}typevartuple: "*" @ref{2185,,identifier} ("=" @ref{182,,expression})?
@anchor{reference/compound_stmts grammar-token-python-grammar-paramspec}@anchor{243c}paramspec:    "**" @ref{2185,,identifier} ("=" @ref{182,,expression})?
@end example

@ref{164f,,Functions} (including @ref{7e6,,coroutines}),
@ref{14d8,,classes} and @ref{665,,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{4a6,,annotation scope}) that
wraps the creation of the generic object.

Generic functions, classes, and type aliases have a
@ref{243d,,__type_params__} attribute listing their type parameters.

Type parameters come in three kinds:


@itemize *

@item 
@ref{481,,typing.TypeVar}, introduced by a plain name (e.g., @code{T}). Semantically, this
represents a single type to a type checker.

@item 
@ref{483,,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{482,,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{481,,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{4a6,,annotation scope}.

@ref{483,,typing.TypeVarTuple}s and @ref{482,,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{4a6,,annotation scope}. If no default value is specified
for a type parameter, the @code{__default__} attribute is set to the special
sentinel object @ref{563,,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{67b}@anchor{reference/compound_stmts id17}@anchor{243e}
@subsubsection Generic functions


Generic functions are declared as follows:

@example
def func[T](arg: T): ...
@end example

語法大致等價於：

@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{4a6,,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{10a,,typing} module, but creates an instance of
@ref{481,,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{67e,,lazy evaluation} of the
@ref{481,,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{67a}@anchor{reference/compound_stmts id18}@anchor{243f}
@subsubsection Generic classes


Generic classes are declared as follows:

@example
class Bag[T]: ...
@end example

語法大致等價於：

@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{4a6,,annotation scope}, and the name
@code{TYPE_PARAMS_OF_Bag} is not actually bound at runtime.

Generic classes implicitly inherit from @ref{174e,,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

這等價於：

@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{67d}@anchor{reference/compound_stmts id19}@anchor{2440}
@subsubsection Generic type aliases


The @ref{665,,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{67e,,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{4a6,,annotation scope}. The capitalized names
like @code{TYPE_PARAMS_OF_ListOrSet} are not actually bound at runtime.

@node 註釋,,Type parameter lists,複合陳述式
@anchor{reference/compound_stmts annotations}@anchor{2430}@anchor{reference/compound_stmts id20}@anchor{2441}
@subsection 註釋



在 3.14 版的變更: Annotations are now lazily evaluated by default.


Variables and function parameters may carry @ref{15c,,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{227d,,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{33,,dataclasses} or @ref{844,,functools.singledispatch()}).

By default, annotations are lazily evaluated in an @ref{4a6,,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{45b,,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{457,,annotationlib.get_annotations()} and @ref{8b9,,typing.get_type_hints()} are
less likely to be able to resolve annotations at runtime.

@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/toplevel_components doc}@anchor{2442}@anchor{reference/toplevel_components top-level}@anchor{2443}@anchor{reference/toplevel_components top-level-components}@anchor{2444}@anchor{reference/toplevel_components translation-repo}@anchor{2445}
@section 最高層級元件


@geindex interpreter（直譯器）

Python 直譯器可以從多種來源獲得輸入：作為標準輸入或程式引數自腳本傳入、以互動式鍵入、自模組原始檔引入等等。這一章將給出在這些情況下所用的語法。

@menu
* 完整的 Python 程式:: 
* 檔案輸入:: 
* 互動式輸入:: 
* 運算式輸入:: 

@end menu

@node 完整的 Python 程式,檔案輸入,,最高層級元件
@anchor{reference/toplevel_components complete-python-programs}@anchor{2446}@anchor{reference/toplevel_components programs}@anchor{2301}
@subsection 完整的 Python 程式


@geindex program（程式）

@geindex module（模組）;sys
@geindex module（模組）;__main__
@geindex module（模組）;builtins（內建）

雖然語言規範描述不必規定語言直譯器是如何被叫用（invoke）的，但對完整的 Python 程式加以說明還是很有用的。一個完整的 Python 程式會在最小初始化環境中被執行：所有內建和標準模組均為可用，但均處於未初始化狀態，只有 @ref{df,,sys}（各種系統服務）、@ref{13,,builtins}（內建函式、例外和 @code{None}）和 @ref{1,,__main__} 除外。後者用於為完整程式的執行提供區域性和全域性命名空間 (namespace)。

用於一個完整 Python 程式的語法，即下節所描述的檔案輸入。

@geindex interactive mode（互動模式）
@geindex module（模組）;__main__

直譯器也可以透過互動模式被叫用；在此情況下，它並不讀取和執行一個完整程式，而是每讀取一條陳述式就執行一次（可能為複合陳述式）。此時的初始環境與一個完整程式的相同；每條陳述式會在 @ref{1,,__main__} 的命名空間中被執行。

@geindex UNIX
@geindex Windows
@geindex command line（命令列）
@geindex standard input（標準輸入）

一個完整程式可透過三種形式被傳遞給直譯器：使用 @ref{1a8,,-c} `字串'命令列選項、使用一個檔案作為第一個命令列引數、或者使用標準輸入。如果檔案或標準輸入是一個 tty 裝置，直譯器會進入互動模式；否則它會將檔案當作一個完整程式來執行。

@node 檔案輸入,互動式輸入,完整的 Python 程式,最高層級元件
@anchor{reference/toplevel_components file-input}@anchor{2447}@anchor{reference/toplevel_components id1}@anchor{2448}
@subsection 檔案輸入


所有從非互動式檔案讀取的輸入都具有相同的形式：

@example
@anchor{reference/toplevel_components grammar-token-python-grammar-file_input}@anchor{2449}file_input: (NEWLINE | @ref{23da,,statement})* ENDMARKER
@end example

此語法用於下列幾種情況：


@itemize *

@item 
剖析一個完整 Python 程式時（從檔案或字串）；

@item 
剖析一個模組時；

@item 
剖析一個傳遞给 @ref{49d,,exec()} 函數的字串時；
@end itemize

@node 互動式輸入,運算式輸入,檔案輸入,最高層級元件
@anchor{reference/toplevel_components interactive}@anchor{244a}@anchor{reference/toplevel_components interactive-input}@anchor{244b}
@subsection 互動式輸入


互動模式下的輸入使用以下語法進行剖析：

@example
@anchor{reference/toplevel_components grammar-token-python-grammar-interactive_input}@anchor{244c}interactive_input: [@ref{23d9,,stmt_list}] NEWLINE | @ref{23cc,,compound_stmt} NEWLINE | ENDMARKER
@end example

注意在互動模式下，一條（最高層級）複合陳述式最後必須帶有一個空行；這能夠幫助剖析器確定輸入已經結束。

@node 運算式輸入,,互動式輸入,最高層級元件
@anchor{reference/toplevel_components expression-input}@anchor{244d}@anchor{reference/toplevel_components id2}@anchor{244e}
@subsection 運算式輸入


@geindex input（輸入）

@geindex built-in function（內建函式）;eval

@ref{49e,,eval()} 被用於運算式輸入，它會忽略開頭的空白。傳遞給 @ref{49e,,eval()} 的字串引數必須具有以下形式：

@example
@anchor{reference/toplevel_components grammar-token-python-grammar-eval_input}@anchor{244f}eval_input: @ref{238f,,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{240c}@anchor{reference/grammar full-grammar-specification}@anchor{2450}@anchor{reference/grammar id1}@anchor{2451}@anchor{reference/grammar translation-repo}@anchor{2452}
@section 完整的語法規格書


This is the full Python grammar, derived directly from the grammar
used to generate the CPython parser (see Grammar/python.gram@footnote{https://github.com/python/cpython/tree/3.14/Grammar/python.gram}).
The version here omits details related to code generation and
error recovery.

The notation used here is the same as in the preceding docs,
and is described in the @ref{2148,,notation} section,
except for an extra complication:


@itemize *

@item 
@code{~} ("cut"): commit to the current alternative and fail the rule
even if this fails to parse
@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
    | e=star_expressions @{ _PyAST_Expr(e, EXTRA) @}
    | &'return' return_stmt
    | &('import' | 'from') import_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 b=['from' z=expression @{ z @}] @{ _PyAST_Raise(a, b, 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]: 'assert' a=expression b=[',' z=expression @{ z @}] @{ _PyAST_Assert(a, b, EXTRA) @}

import_stmt[stmt_ty]:
    | invalid_import
    | import_name
    | import_from

# Import statements
# -----------------

import_name[stmt_ty]: 'import' a=dotted_as_names @{ _PyAST_Import(a, EXTRA) @}
# note below: the ('.' | '...') is necessary because '...' is tokenized as ELLIPSIS
import_from[stmt_ty]:
    | 'from' a=('.' | '...')* b=dotted_name 'import' c=import_from_targets @{
        _PyPegen_checked_future_import(p, b->v.Name.id, c, _PyPegen_seq_count_dots(a), EXTRA) @}
    | 'from' a=('.' | '...')+ 'import' b=import_from_targets @{
        _PyAST_ImportFrom(NULL, b, _PyPegen_seq_count_dots(a), EXTRA) @}
import_from_targets[asdl_alias_seq*]:
    | '(' a=import_from_as_names [','] ')' @{ a @}
    | import_from_as_names !','
    | '*' @{ (asdl_alias_seq*)_PyPegen_singleton_seq(p, CHECK(alias_ty, _PyPegen_alias_for_star(p, EXTRA))) @}
    | invalid_import_from_targets
import_from_as_names[asdl_alias_seq*]:
    | a[asdl_alias_seq*]=','.import_from_as_name+ @{ a @}
import_from_as_name[alias_ty]:
    | 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 @{ _PyAST_UnaryOp(USub, number, EXTRA) @}

signed_real_number[expr_ty]:
    | real_number
    | '-' real=real_number @{ _PyAST_UnaryOp(USub, real, EXTRA) @}

real_number[expr_ty]:
    | real=NUMBER @{ _PyPegen_ensure_real(p, real) @}

imaginary_number[expr_ty]:
    | imag=NUMBER @{ _PyPegen_ensure_imaginary(p, imag) @}

capture_pattern[pattern_ty]:
    | target=pattern_capture_target @{ _PyAST_MatchAs(NULL, target->v.Name.id, EXTRA) @}

pattern_capture_target[expr_ty]:
    | !"_" name=NAME !('.' | '(' | '=') @{
        _PyPegen_set_expr_context(p, name, Store) @}

wildcard_pattern[pattern_ty]:
    | "_" @{ _PyAST_MatchAs(NULL, NULL, EXTRA) @}

value_pattern[pattern_ty]:
    | attr=attr !('.' | '(' | '=') @{ _PyAST_MatchValue(attr, EXTRA) @}

attr[expr_ty]:
    | value=name_or_attr '.' attr=NAME @{
        _PyAST_Attribute(value, attr->v.Name.id, Load, EXTRA) @}

name_or_attr[expr_ty]:
    | attr
    | NAME

group_pattern[pattern_ty]:
    | '(' pattern=pattern ')' @{ pattern @}

sequence_pattern[pattern_ty]:
    | '[' patterns=maybe_sequence_pattern? ']' @{ _PyAST_MatchSequence(patterns, EXTRA) @}
    | '(' patterns=open_sequence_pattern? ')' @{ _PyAST_MatchSequence(patterns, EXTRA) @}

open_sequence_pattern[asdl_seq*]:
    | pattern=maybe_star_pattern ',' patterns=maybe_sequence_pattern? @{
        _PyPegen_seq_insert_in_front(p, pattern, patterns) @}

maybe_sequence_pattern[asdl_seq*]:
    | patterns=','.maybe_star_pattern+ ','? @{ patterns @}

maybe_star_pattern[pattern_ty]:
    | star_pattern
    | pattern

star_pattern[pattern_ty] (memo):
    | '*' target=pattern_capture_target @{
        _PyAST_MatchStar(target->v.Name.id, EXTRA) @}
    | '*' wildcard_pattern @{
        _PyAST_MatchStar(NULL, EXTRA) @}

mapping_pattern[pattern_ty]:
    | '@{' '@}' @{
        _PyAST_MatchMapping(NULL, NULL, NULL, EXTRA) @}
    | '@{' rest=double_star_pattern ','? '@}' @{
        _PyAST_MatchMapping(NULL, NULL, rest->v.Name.id, EXTRA) @}
    | '@{' items=items_pattern ',' rest=double_star_pattern ','? '@}' @{
        _PyAST_MatchMapping(
            CHECK(asdl_expr_seq*, _PyPegen_get_pattern_keys(p, items)),
            CHECK(asdl_pattern_seq*, _PyPegen_get_patterns(p, items)),
            rest->v.Name.id,
            EXTRA) @}
    | '@{' items=items_pattern ','? '@}' @{
        _PyAST_MatchMapping(
            CHECK(asdl_expr_seq*, _PyPegen_get_pattern_keys(p, items)),
            CHECK(asdl_pattern_seq*, _PyPegen_get_patterns(p, items)),
            NULL,
            EXTRA) @}

items_pattern[asdl_seq*]:
    | ','.key_value_pattern+

key_value_pattern[KeyPatternPair*]:
    | key=(literal_expr | attr) ':' pattern=pattern @{
        _PyPegen_key_pattern_pair(p, key, pattern) @}

double_star_pattern[expr_ty]:
    | '**' target=pattern_capture_target @{ target @}

class_pattern[pattern_ty]:
    | cls=name_or_attr '(' ')' @{
        _PyAST_MatchClass(cls, NULL, NULL, NULL, EXTRA) @}
    | cls=name_or_attr '(' patterns=positional_patterns ','? ')' @{
        _PyAST_MatchClass(cls, patterns, NULL, NULL, EXTRA) @}
    | cls=name_or_attr '(' keywords=keyword_patterns ','? ')' @{
        _PyAST_MatchClass(
            cls, NULL,
            CHECK(asdl_identifier_seq*, _PyPegen_map_names_to_ids(p,
                CHECK(asdl_expr_seq*, _PyPegen_get_pattern_keys(p, keywords)))),
            CHECK(asdl_pattern_seq*, _PyPegen_get_patterns(p, keywords)),
            EXTRA) @}
    | cls=name_or_attr '(' patterns=positional_patterns ',' keywords=keyword_patterns ','? ')' @{
        _PyAST_MatchClass(
            cls,
            patterns,
            CHECK(asdl_identifier_seq*, _PyPegen_map_names_to_ids(p,
                CHECK(asdl_expr_seq*, _PyPegen_get_pattern_keys(p, keywords)))),
            CHECK(asdl_pattern_seq*, _PyPegen_get_patterns(p, keywords)),
            EXTRA) @}
    | invalid_class_pattern

positional_patterns[asdl_pattern_seq*]:
    | args[asdl_pattern_seq*]=','.pattern+ @{ args @}

keyword_patterns[asdl_seq*]:
    | ','.keyword_pattern+

keyword_pattern[KeyPatternPair*]:
    | arg=NAME '=' value=pattern @{ _PyPegen_key_pattern_pair(p, arg, value) @}

# Type statement
# ---------------

type_alias[stmt_ty]:
    | "type" n=NAME t=[type_params] '=' b=expression @{
        CHECK_VERSION(stmt_ty, 12, "Type statement is",
        _PyAST_TypeAlias(CHECK(expr_ty, _PyPegen_set_expr_context(p, n, Store)), t, b, EXTRA)) @}

# Type parameter declaration
# --------------------------

type_params[asdl_type_param_seq*]:
    | invalid_type_params
    | '[' t=type_param_seq ']' @{
        CHECK_VERSION(asdl_type_param_seq *, 12, "Type parameter lists are", t) @}

type_param_seq[asdl_type_param_seq*]: a[asdl_type_param_seq*]=','.type_param+ [','] @{ a @}

type_param[type_param_ty] (memo):
    | a=NAME b=[type_param_bound] c=[type_param_default] @{ _PyAST_TypeVar(a->v.Name.id, b, c, EXTRA) @}
    | 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_expression
    | invalid_legacy_expression
    | a=disjunction 'if' b=disjunction 'else' c=expression @{ _PyAST_IfExp(b, a, c, EXTRA) @}
    | disjunction
    | lambdef

yield_expr[expr_ty]:
    | 'yield' 'from' a=expression @{ _PyAST_YieldFrom(a, EXTRA) @}
    | 'yield' a=[star_expressions] @{ _PyAST_Yield(a, EXTRA) @}

star_expressions[expr_ty]:
    | a=star_expression b=(',' c=star_expression @{ c @})+ [','] @{
        _PyAST_Tuple(CHECK(asdl_expr_seq*, _PyPegen_seq_insert_in_front(p, a, b)), Load, EXTRA) @}
    | a=star_expression ',' @{ _PyAST_Tuple(CHECK(asdl_expr_seq*, _PyPegen_singleton_seq(p, a)), Load, EXTRA) @}
    | star_expression

star_expression[expr_ty] (memo):
    | '*' a=bitwise_or @{ _PyAST_Starred(a, Load, EXTRA) @}
    | expression

star_named_expressions[asdl_expr_seq*]: a[asdl_expr_seq*]=','.star_named_expression+ [','] @{ a @}

star_named_expression[expr_ty]:
    | '*' a=bitwise_or @{ _PyAST_Starred(a, Load, EXTRA) @}
    | named_expression

assignment_expression[expr_ty]:
    | a=NAME ':=' ~ b=expression @{
        CHECK_VERSION(expr_ty, 8, "Assignment expressions are",
        _PyAST_NamedExpr(CHECK(expr_ty, _PyPegen_set_expr_context(p, a, Store)), b, EXTRA)) @}

named_expression[expr_ty]:
    | assignment_expression
    | invalid_named_expression
    | expression !':='

disjunction[expr_ty] (memo):
    | a=conjunction b=('or' c=conjunction @{ c @})+ @{ _PyAST_BoolOp(
        Or,
        CHECK(asdl_expr_seq*, _PyPegen_seq_insert_in_front(p, a, b)),
        EXTRA) @}
    | conjunction

conjunction[expr_ty] (memo):
    | a=inversion b=('and' c=inversion @{ c @})+ @{ _PyAST_BoolOp(
        And,
        CHECK(asdl_expr_seq*, _PyPegen_seq_insert_in_front(p, a, b)),
        EXTRA) @}
    | inversion

inversion[expr_ty] (memo):
    | 'not' a=inversion @{ _PyAST_UnaryOp(Not, a, EXTRA) @}
    | comparison

# Comparison operators
# --------------------

comparison[expr_ty]:
    | a=bitwise_or b=compare_op_bitwise_or_pair+ @{
        _PyAST_Compare(
            a,
            CHECK(asdl_int_seq*, _PyPegen_get_cmpops(p, b)),
            CHECK(asdl_expr_seq*, _PyPegen_get_exprs(p, b)),
            EXTRA) @}
    | bitwise_or

compare_op_bitwise_or_pair[CmpopExprPair*]:
    | eq_bitwise_or
    | noteq_bitwise_or
    | lte_bitwise_or
    | lt_bitwise_or
    | gte_bitwise_or
    | gt_bitwise_or
    | notin_bitwise_or
    | in_bitwise_or
    | isnot_bitwise_or
    | is_bitwise_or

eq_bitwise_or[CmpopExprPair*]: '==' a=bitwise_or @{ _PyPegen_cmpop_expr_pair(p, Eq, a) @}
noteq_bitwise_or[CmpopExprPair*]:
    | (tok='!=' @{ _PyPegen_check_barry_as_flufl(p, tok) ? NULL : tok@}) a=bitwise_or @{_PyPegen_cmpop_expr_pair(p, NotEq, a) @}
lte_bitwise_or[CmpopExprPair*]: '<=' a=bitwise_or @{ _PyPegen_cmpop_expr_pair(p, LtE, a) @}
lt_bitwise_or[CmpopExprPair*]: '<' a=bitwise_or @{ _PyPegen_cmpop_expr_pair(p, Lt, a) @}
gte_bitwise_or[CmpopExprPair*]: '>=' a=bitwise_or @{ _PyPegen_cmpop_expr_pair(p, GtE, a) @}
gt_bitwise_or[CmpopExprPair*]: '>' a=bitwise_or @{ _PyPegen_cmpop_expr_pair(p, Gt, a) @}
notin_bitwise_or[CmpopExprPair*]: 'not' 'in' a=bitwise_or @{ _PyPegen_cmpop_expr_pair(p, NotIn, a) @}
in_bitwise_or[CmpopExprPair*]: 'in' a=bitwise_or @{ _PyPegen_cmpop_expr_pair(p, In, a) @}
isnot_bitwise_or[CmpopExprPair*]: 'is' 'not' a=bitwise_or @{ _PyPegen_cmpop_expr_pair(p, IsNot, a) @}
is_bitwise_or[CmpopExprPair*]: 'is' a=bitwise_or @{ _PyPegen_cmpop_expr_pair(p, Is, a) @}

# Bitwise operators
# -----------------

bitwise_or[expr_ty]:
    | a=bitwise_or '|' b=bitwise_xor @{ _PyAST_BinOp(a, BitOr, b, EXTRA) @}
    | bitwise_xor

bitwise_xor[expr_ty]:
    | a=bitwise_xor '^' b=bitwise_and @{ _PyAST_BinOp(a, BitXor, b, EXTRA) @}
    | bitwise_and

bitwise_and[expr_ty]:
    | a=bitwise_and '&' b=shift_expr @{ _PyAST_BinOp(a, BitAnd, b, EXTRA) @}
    | shift_expr

shift_expr[expr_ty]:
    | a=shift_expr '<<' b=sum @{ _PyAST_BinOp(a, LShift, b, EXTRA) @}
    | a=shift_expr '>>' b=sum @{ _PyAST_BinOp(a, RShift, b, EXTRA) @}
    | invalid_arithmetic
    | sum

# Arithmetic operators
# --------------------

sum[expr_ty]:
    | a=sum '+' b=term @{ _PyAST_BinOp(a, Add, b, EXTRA) @}
    | a=sum '-' b=term @{ _PyAST_BinOp(a, Sub, b, EXTRA) @}
    | term

term[expr_ty]:
    | a=term '*' b=factor @{ _PyAST_BinOp(a, Mult, b, EXTRA) @}
    | a=term '/' b=factor @{ _PyAST_BinOp(a, Div, b, EXTRA) @}
    | a=term '//' b=factor @{ _PyAST_BinOp(a, FloorDiv, b, EXTRA) @}
    | a=term '%' b=factor @{ _PyAST_BinOp(a, Mod, b, EXTRA) @}
    | a=term '@@' b=factor @{ CHECK_VERSION(expr_ty, 5, "The '@@' operator is", _PyAST_BinOp(a, MatMult, b, EXTRA)) @}
    | invalid_factor
    | factor

factor[expr_ty] (memo):
    | '+' a=factor @{ _PyAST_UnaryOp(UAdd, a, EXTRA) @}
    | '-' a=factor @{ _PyAST_UnaryOp(USub, a, EXTRA) @}
    | '~' a=factor @{ _PyAST_UnaryOp(Invert, a, EXTRA) @}
    | power

power[expr_ty]:
    | a=await_primary '**' b=factor @{ _PyAST_BinOp(a, Pow, b, EXTRA) @}
    | await_primary

# Primary elements
# ----------------

# Primary elements are things like "obj.something.something", "obj[something]", "obj(something)", "obj" ...

await_primary[expr_ty] (memo):
    | 'await' a=primary @{ CHECK_VERSION(expr_ty, 5, "Await expressions are", _PyAST_Await(a, EXTRA)) @}
    | primary

primary[expr_ty]:
    | a=primary '.' b=NAME @{ _PyAST_Attribute(a, b->v.Name.id, Load, EXTRA) @}
    | a=primary b=genexp @{ _PyAST_Call(a, CHECK(asdl_expr_seq*, (asdl_expr_seq*)_PyPegen_singleton_seq(p, b)), NULL, EXTRA) @}
    | a=primary '(' b=[arguments] ')' @{
        _PyAST_Call(a,
                 (b) ? ((expr_ty) b)->v.Call.args : NULL,
                 (b) ? ((expr_ty) b)->v.Call.keywords : NULL,
                 EXTRA) @}
    | a=primary '[' b=slices ']' @{ _PyAST_Subscript(a, b, Load, EXTRA) @}
    | atom

slices[expr_ty]:
    | a=slice !',' @{ a @}
    | a[asdl_expr_seq*]=','.(slice | starred_expression)+ [','] @{ _PyAST_Tuple(a, Load, EXTRA) @}

slice[expr_ty]:
    | a=[expression] ':' b=[expression] c=[':' d=[expression] @{ d @}] @{ _PyAST_Slice(a, b, c, EXTRA) @}
    | a=named_expression @{ a @}

atom[expr_ty]:
    | NAME
    | 'True' @{ _PyAST_Constant(Py_True, NULL, EXTRA) @}
    | 'False' @{ _PyAST_Constant(Py_False, NULL, EXTRA) @}
    | 'None' @{ _PyAST_Constant(Py_None, NULL, EXTRA) @}
    | &(STRING|FSTRING_START|TSTRING_START) strings
    | NUMBER
    | &'(' (tuple | group | genexp)
    | &'[' (list | listcomp)
    | &'@{' (dict | set | dictcomp | setcomp)
    | '...' @{ _PyAST_Constant(Py_Ellipsis, NULL, EXTRA) @}

group[expr_ty]:
    | '(' a=(yield_expr | named_expression) ')' @{ a @}
    | invalid_group

# Lambda functions
# ----------------

lambdef[expr_ty]:
    | 'lambda' a=[lambda_params] ':' b=expression @{
        _PyAST_Lambda((a) ? a : CHECK(arguments_ty, _PyPegen_empty_arguments(p)), b, EXTRA) @}

lambda_params[arguments_ty]:
    | invalid_lambda_parameters
    | lambda_parameters

# lambda_parameters etc. duplicates parameters but without annotations
# or type comments, and if there's no comma after a parameter, we expect
# a colon, not a close parenthesis.  (For more, see parameters above.)
#
lambda_parameters[arguments_ty]:
    | a=lambda_slash_no_default b[asdl_arg_seq*]=lambda_param_no_default* c=lambda_param_with_default* d=[lambda_star_etc] @{
        CHECK_VERSION(arguments_ty, 8, "Positional-only parameters are", _PyPegen_make_arguments(p, a, NULL, b, c, d)) @}
    | a=lambda_slash_with_default b=lambda_param_with_default* c=[lambda_star_etc] @{
        CHECK_VERSION(arguments_ty, 8, "Positional-only parameters are", _PyPegen_make_arguments(p, NULL, a, NULL, b, c)) @}
    | a[asdl_arg_seq*]=lambda_param_no_default+ b=lambda_param_with_default* c=[lambda_star_etc] @{
        _PyPegen_make_arguments(p, NULL, NULL, a, b, c) @}
    | a=lambda_param_with_default+ b=[lambda_star_etc] @{ _PyPegen_make_arguments(p, NULL, NULL, NULL, a, b)@}
    | a=lambda_star_etc @{ _PyPegen_make_arguments(p, NULL, NULL, NULL, NULL, a) @}

lambda_slash_no_default[asdl_arg_seq*]:
    | a[asdl_arg_seq*]=lambda_param_no_default+ '/' ',' @{ a @}
    | a[asdl_arg_seq*]=lambda_param_no_default+ '/' &':' @{ a @}

lambda_slash_with_default[SlashWithDefault*]:
    | a=lambda_param_no_default* b=lambda_param_with_default+ '/' ',' @{ _PyPegen_slash_with_default(p, (asdl_arg_seq *)a, b) @}
    | a=lambda_param_no_default* b=lambda_param_with_default+ '/' &':' @{ _PyPegen_slash_with_default(p, (asdl_arg_seq *)a, b) @}

lambda_star_etc[StarEtc*]:
    | invalid_lambda_star_etc
    | '*' a=lambda_param_no_default b=lambda_param_maybe_default* c=[lambda_kwds] @{
        _PyPegen_star_etc(p, a, b, c) @}
    | '*' ',' b=lambda_param_maybe_default+ c=[lambda_kwds] @{
        _PyPegen_star_etc(p, NULL, b, c) @}
    | a=lambda_kwds @{ _PyPegen_star_etc(p, NULL, NULL, a) @}

lambda_kwds[arg_ty]:
    | invalid_lambda_kwds
    | '**' a=lambda_param_no_default @{ a @}

lambda_param_no_default[arg_ty]:
    | a=lambda_param ',' @{ a @}
    | a=lambda_param &':' @{ a @}
lambda_param_with_default[NameDefaultPair*]:
    | a=lambda_param c=default ',' @{ _PyPegen_name_default_pair(p, a, c, NULL) @}
    | a=lambda_param c=default &':' @{ _PyPegen_name_default_pair(p, a, c, NULL) @}
lambda_param_maybe_default[NameDefaultPair*]:
    | a=lambda_param c=default? ',' @{ _PyPegen_name_default_pair(p, a, c, NULL) @}
    | a=lambda_param c=default? &':' @{ _PyPegen_name_default_pair(p, a, c, NULL) @}
lambda_param[arg_ty]: a=NAME @{ _PyAST_arg(a->v.Name.id, NULL, NULL, EXTRA) @}

# LITERALS
# ========

fstring_middle[expr_ty]:
    | fstring_replacement_field
    | t=FSTRING_MIDDLE @{ _PyPegen_constant_from_token(p, t) @}
fstring_replacement_field[expr_ty]:
    | '@{' a=annotated_rhs debug_expr='='? conversion=[fstring_conversion] format=[fstring_full_format_spec] rbrace='@}' @{
        _PyPegen_formatted_value(p, a, debug_expr, conversion, format, rbrace, EXTRA) @}
    | invalid_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] ']' @{ _PyAST_List(a, Load, EXTRA) @}

tuple[expr_ty]:
    | '(' a=[y=star_named_expression ',' z=[star_named_expressions] @{ _PyPegen_seq_insert_in_front(p, y, z) @} ] ')' @{
        _PyAST_Tuple(a, Load, EXTRA) @}

set[expr_ty]: '@{' a=star_named_expressions '@}' @{ _PyAST_Set(a, EXTRA) @}

# Dicts
# -----

dict[expr_ty]:
    | '@{' a=[double_starred_kvpairs] '@}' @{
        _PyAST_Dict(
            CHECK(asdl_expr_seq*, _PyPegen_get_keys(p, a)),
            CHECK(asdl_expr_seq*, _PyPegen_get_values(p, a)),
            EXTRA) @}
    | '@{' invalid_double_starred_kvpairs '@}'

double_starred_kvpairs[asdl_seq*]: a=','.double_starred_kvpair+ [','] @{ a @}

double_starred_kvpair[KeyValuePair*]:
    | '**' a=bitwise_or @{ _PyPegen_key_value_pair(p, NULL, a) @}
    | kvpair

kvpair[KeyValuePair*]: a=expression ':' b=expression @{ _PyPegen_key_value_pair(p, a, b) @}

# Comprehensions & Generators
# ---------------------------

for_if_clauses[asdl_comprehension_seq*]:
    | a[asdl_comprehension_seq*]=for_if_clause+ @{ a @}

for_if_clause[comprehension_ty]:
    | 'async' 'for' a=star_targets 'in' ~ b=disjunction c[asdl_expr_seq*]=('if' z=disjunction @{ z @})* @{
        CHECK_VERSION(comprehension_ty, 6, "Async comprehensions are", _PyAST_comprehension(a, b, c, 1, p->arena)) @}
    | 'for' a=star_targets 'in' ~ b=disjunction c[asdl_expr_seq*]=('if' z=disjunction @{ z @})* @{
        _PyAST_comprehension(a, b, c, 0, p->arena) @}
    | invalid_for_if_clause
    | invalid_for_target

listcomp[expr_ty]:
    | '[' a=named_expression b=for_if_clauses ']' @{ _PyAST_ListComp(a, b, EXTRA) @}
    | invalid_comprehension

setcomp[expr_ty]:
    | '@{' a=named_expression b=for_if_clauses '@}' @{ _PyAST_SetComp(a, b, EXTRA) @}
    | invalid_comprehension

genexp[expr_ty]:
    | '(' a=( assignment_expression | expression !':=') b=for_if_clauses ')' @{ _PyAST_GeneratorExp(a, b, EXTRA) @}
    | invalid_comprehension

dictcomp[expr_ty]:
    | '@{' a=kvpair b=for_if_clauses '@}' @{ _PyAST_DictComp(a->key, a->value, b, EXTRA) @}
    | invalid_dict_comprehension

# FUNCTION CALL ARGUMENTS
# =======================

arguments[expr_ty] (memo):
    | a=args [','] &')' @{ a @}
    | invalid_arguments

args[expr_ty]:
    | a[asdl_expr_seq*]=','.(starred_expression | ( assignment_expression | expression !':=') !'=')+ b=[',' k=kwargs @{k@}] @{
        _PyPegen_collect_call_seqs(p, a, b, EXTRA) @}
    | a=kwargs @{ _PyAST_Call(_PyPegen_dummy_name(p),
                          CHECK_NULL_ALLOWED(asdl_expr_seq*, _PyPegen_seq_extract_starred_exprs(p, a)),
                          CHECK_NULL_ALLOWED(asdl_keyword_seq*, _PyPegen_seq_delete_starred_exprs(p, a)),
                          EXTRA) @}

kwargs[asdl_seq*]:
    | a=','.kwarg_or_starred+ ',' b=','.kwarg_or_double_starred+ @{ _PyPegen_join_sequences(p, a, b) @}
    | ','.kwarg_or_starred+
    | ','.kwarg_or_double_starred+

starred_expression[expr_ty]:
    | invalid_starred_expression_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_check_legacy_stmt(p, a) ? NULL : p->tokens[p->mark-1]->level == 0 ? NULL :
        RAISE_SYNTAX_ERROR_KNOWN_RANGE(a, b, "invalid syntax. Perhaps you forgot a comma?") @}
   | a=disjunction 'if' b=disjunction !('else'|':') @{ RAISE_SYNTAX_ERROR_KNOWN_RANGE(a, b, "expected 'else' after 'if' expression") @}
   | a=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_named_expression(memo):
    | a=expression ':=' expression @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(
            a, "cannot use assignment expressions with %s", _PyPegen_get_expr_name(a)) @}
    | a=NAME '=' b=bitwise_or !('='|':=') @{
        RAISE_SYNTAX_ERROR_KNOWN_RANGE(a, b, "invalid syntax. Maybe you meant '==' or ':=' instead of '='?") @}
    | !(list|tuple|genexp|'True'|'None'|'False') a=bitwise_or b='=' bitwise_or !('='|':=') @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "cannot assign to %s here. Maybe you meant '==' instead of '='?",
                                          _PyPegen_get_expr_name(a)) @}

invalid_assignment:
    | a=invalid_ann_assign_target ':' expression @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(
            a,
            "only single target (not %s) can be annotated",
            _PyPegen_get_expr_name(a)
        )@}
    | a=star_named_expression ',' star_named_expressions* ':' expression @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "only single target (not tuple) can be annotated") @}
    | a=expression ':' expression @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "illegal target for annotation") @}
    | (star_targets '=')* a=star_expressions '=' @{
        RAISE_SYNTAX_ERROR_INVALID_TARGET(STAR_TARGETS, a) @}
    | (star_targets '=')* a=yield_expr '=' @{ RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "assignment to yield expression not possible") @}
    | a=star_expressions augassign annotated_rhs @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(
            a,
            "'%s' is an illegal expression for augmented assignment",
            _PyPegen_get_expr_name(a)
        )@}
invalid_ann_assign_target[expr_ty]:
    | list
    | tuple
    | '(' a=invalid_ann_assign_target ')' @{ a @}
invalid_del_stmt:
    | 'del' a=star_expressions @{
        RAISE_SYNTAX_ERROR_INVALID_TARGET(DEL_TARGETS, a) @}
invalid_block:
    | NEWLINE !INDENT @{ RAISE_INDENTATION_ERROR("expected an indented block") @}
invalid_comprehension:
    | ('[' | '(' | '@{') a=starred_expression for_if_clauses @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "iterable unpacking cannot be used in comprehension") @}
    | ('[' | '@{') a=star_named_expression ',' b=star_named_expressions for_if_clauses @{
        RAISE_SYNTAX_ERROR_KNOWN_RANGE(a, PyPegen_last_item(b, expr_ty),
        "did you forget parentheses around the comprehension target?") @}
    | ('[' | '@{') a=star_named_expression b=',' for_if_clauses @{
        RAISE_SYNTAX_ERROR_KNOWN_RANGE(a, b, "did you forget parentheses around the comprehension target?") @}
invalid_dict_comprehension:
    | '@{' a='**' bitwise_or for_if_clauses '@}' @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "dict unpacking cannot be used in dict comprehension") @}
invalid_parameters:
    | a="/" ',' @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "at least one argument must precede /") @}
    | (slash_no_default | slash_with_default) param_maybe_default* a='/' @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "/ may appear only once") @}
    | slash_no_default? param_no_default* invalid_parameters_helper a=param_no_default @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "parameter without a default follows parameter with a default") @}
    | param_no_default* a='(' param_no_default+ ','? b=')' @{
        RAISE_SYNTAX_ERROR_KNOWN_RANGE(a, b, "Function parameters cannot be parenthesized") @}
    | (slash_no_default | slash_with_default)? param_maybe_default* '*' (',' | param_no_default) param_maybe_default* a='/' @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "/ must be ahead of *") @}
    | param_maybe_default+ '/' a='*' @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "expected comma between / and *") @}
invalid_default:
    | a='=' &(')'|',') @{ RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "expected default value expression") @}
invalid_star_etc:
    | a='*' (')' | ',' (')' | '**')) @{ RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "named arguments must follow bare *") @}
    | '*' ',' TYPE_COMMENT @{ RAISE_SYNTAX_ERROR("bare * has associated type comment") @}
    | '*' param a='=' @{ RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "var-positional argument cannot have default value") @}
    | '*' (param_no_default | ',') param_maybe_default* a='*' (param_no_default | ',') @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "* argument may appear only once") @}
invalid_kwds:
    | '**' param a='=' @{ RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "var-keyword argument cannot have default value") @}
    | '**' param ',' a=param @{ RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "arguments cannot follow var-keyword argument") @}
    | '**' param ',' a[Token*]=('*'|'**'|'/') @{ RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "arguments cannot follow var-keyword argument") @}
invalid_parameters_helper: # This is only there to avoid type errors
    | a=slash_with_default @{ _PyPegen_singleton_seq(p, a) @}
    | param_with_default+
invalid_lambda_parameters:
    | a="/" ',' @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "at least one argument must precede /") @}
    | (lambda_slash_no_default | lambda_slash_with_default) lambda_param_maybe_default* a='/' @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "/ may appear only once") @}
    | lambda_slash_no_default? lambda_param_no_default* invalid_lambda_parameters_helper a=lambda_param_no_default @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "parameter without a default follows parameter with a default") @}
    | lambda_param_no_default* a='(' ','.lambda_param+ ','? b=')' @{
        RAISE_SYNTAX_ERROR_KNOWN_RANGE(a, b, "Lambda expression parameters cannot be parenthesized") @}
    | (lambda_slash_no_default | lambda_slash_with_default)? lambda_param_maybe_default* '*' (',' | lambda_param_no_default) lambda_param_maybe_default* a='/' @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "/ must be ahead of *") @}
    | lambda_param_maybe_default+ '/' a='*' @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "expected comma between / and *") @}
invalid_lambda_parameters_helper:
    | a=lambda_slash_with_default @{ _PyPegen_singleton_seq(p, a) @}
    | lambda_param_with_default+
invalid_lambda_star_etc:
    | '*' (':' | ',' (':' | '**')) @{ RAISE_SYNTAX_ERROR("named arguments must follow bare *") @}
    | '*' lambda_param a='=' @{ RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "var-positional argument cannot have default value") @}
    | '*' (lambda_param_no_default | ',') lambda_param_maybe_default* a='*' (lambda_param_no_default | ',') @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "* argument may appear only once") @}
invalid_lambda_kwds:
    | '**' lambda_param a='=' @{ RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "var-keyword argument cannot have default value") @}
    | '**' lambda_param ',' a=lambda_param @{ RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "arguments cannot follow var-keyword argument") @}
    | '**' lambda_param ',' a[Token*]=('*'|'**'|'/') @{ RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "arguments cannot follow var-keyword argument") @}
invalid_double_type_comments:
    | TYPE_COMMENT NEWLINE TYPE_COMMENT NEWLINE INDENT @{
        RAISE_SYNTAX_ERROR("Cannot have two type comments on def") @}
invalid_with_item:
    | expression 'as' a=expression &(',' | ')' | ':') @{
        RAISE_SYNTAX_ERROR_INVALID_TARGET(STAR_TARGETS, a) @}

invalid_for_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])+ 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) @}
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_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:
    | ','.double_starred_kvpair+ ',' invalid_kvpair
    | expression ':' a='*' bitwise_or @{ RAISE_SYNTAX_ERROR_STARTING_FROM(a, "cannot use a starred expression in a dictionary value") @}
    | expression a=':' &('@}'|',') @{ RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "expression expected after dictionary key and ':'") @}
invalid_kvpair:
    | a=expression !(':') @{
        RAISE_ERROR_KNOWN_LOCATION(p, PyExc_SyntaxError, a->lineno, a->end_col_offset - 1, a->end_lineno, -1, "':' expected after dictionary key") @}
    | expression ':' a='*' bitwise_or @{ RAISE_SYNTAX_ERROR_STARTING_FROM(a, "cannot use a starred expression in a dictionary value") @}
    | expression a=':' &('@}'|',') @{RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "expression expected after dictionary key and ':'") @}
invalid_starred_expression_unpacking:
    | a='*' expression '=' b=expression @{ RAISE_SYNTAX_ERROR_KNOWN_RANGE(a, b, "cannot assign to iterable argument 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 Python 標準函式庫 Standard Library,擴充和嵌入 Python 直譯器,Python 語言參考手冊,Top
@anchor{library/index doc}@anchor{2453}@anchor{library/index library-index}@anchor{149}@anchor{library/index the-python-standard-library}@anchor{2454}@anchor{library/index translation-repo}@anchor{2455}
@chapter Python 標準函式庫 (Standard Library)


@ref{14a,,Python 語言參考手冊}說明 Python 這門語言確切的文法及語意，而這份函式庫參考手冊則是說明隨著 Python 一起發佈的標準函式庫，除此之外，其內容也包含一些時常出現在 Python 發佈版本中的非必要套件。

Python 的標準函式庫是非常龐大的，其提供了如下所述極多且涵蓋用途極廣的許多模組。包含一些用 C 語言撰寫，可以操作像是檔案讀寫等系統相關功能的內建模組，當然也有用 Python 撰寫，並使用標準解法解決許多常見問題的模組。其中有些模組則是特別針對 Python 的可攜性去設計的，為此特地將一些平台特殊相依性的功能抽象化成可跨平台的 API。

Python 的 Windows 安裝檔基本上包含整個標準函式庫，且通常也包含許多附加的組件；而在類 Unix 作業系統方面，Python 通常是以一系列的套件被安裝，因此對於某些或全部的可選組件，可能都必須使用該作業系統提供的套件管理工具來安裝。

在標準函式庫之外，還有成千上萬且不斷增加的組件（從個別的程式、模組、套件到完整的應用程式開發框架），可以從 Python 套件索引 (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
* 簡介: 簡介<6>. 
* 內建函式: 內建函式<2>. 
* 內建常數:: 
* 內建型別:: 
* 內建的例外:: 
* 文本處理 (Text Processing) 服務: 文本處理 Text Processing 服務. 
* 二進位資料服務:: 
* 資料型別:: 
* 數值與數學模組:: 
* 函式程式設計模組:: 
* 檔案與目錄存取:: 
* 資料持久性 (Data Persistence): 資料持久性 Data Persistence. 
* 資料壓縮與保存:: 
* 檔案格式:: 
* 加密服務:: 
* 通用作業系統服務:: 
* 命令列介面函式庫:: 
* 並行執行 (Concurrent Execution): 並行執行 Concurrent Execution. 
* 網路與行程間通訊:: 
* 網際網路資料處理:: 
* 結構化標記處理工具:: 
* 網路協定 (Internet protocols) 及支援: 網路協定 Internet protocols 及支援. 
* 多媒體服務:: 
* 國際化:: 
* 以 Tk 打造圖形使用者介面 (Graphical User Interfaces): 以 Tk 打造圖形使用者介面 Graphical User Interfaces. 
* 開發工具:: 
* 除錯與效能分析:: 
* 軟體封裝與發布:: 
* Python Runtime 服務:: 
* 自訂 Python 直譯器:: 
* 引入模組:: 
* Python 語言服務:: 
* MS Windows 特有服務:: 
* Unix 特有服務:: 
* 模組命令列介面:: 
* 已被取代的模組:: 
* 已移除的模組:: 
* 安全性注意事項: 安全性注意事項<4>. 

@end menu

@node 簡介<6>,內建函式<2>,,Python 標準函式庫 Standard Library
@anchor{library/intro doc}@anchor{2456}@anchor{library/intro introduction}@anchor{2457}@anchor{library/intro library-intro}@anchor{2458}
@section 簡介


「Python 函式庫」包含了許多不同的部分。

函式庫中包括被視為程式語言「核心」部分的資料型態，像是數字 (number) 或是串列 (list)。對於這些型別，Python 核心對這些字面值 (literal) 的形式做定義，並對它們的語意制定了一些限制，但在此同時卻不把文字對應的語意完全定義。（另一方面，Python 在語法面上有確實的定義，例如拼字或是運算元次序）

Python 函式庫也囊括了內建函式與例外處理——這些物件都可以不用透過 @ref{7f1,,import} 陳述式來引入 Python 程式中就能使用。函式庫中有部份是被 Python 核心所定義的，但在這裡僅解釋最核心的語意部分。

整個函式庫中包含了許多模組，有許多方法可以從函式庫中取用這些模組。有些模組是以 C 語言撰寫並建置於 Python 編譯器之中，其他的是由 Python 撰寫並以源碼的方式 (source form) 引入。有些模組提供的功能是專屬於 Python 的，像是把 stack trace 印出來；有些則是針對特定作業系統，去試著存取特定硬體；還有些提供對特定應用的功能與操作介面，像是 World Wide Web。模組的使用情況會因機器與 Python 的版本而不同，部分模組是開放所有版本以及 Port 的 Python 來使用的，但有些會因系統支援或需求在某些版本或系統下無法使用，甚至有些僅限在特定的設定環境下才能使用。

這個手冊會「深入淺出」地介紹 Python 函式庫。它會先介紹一些內建函式、資料型態、和一些例外處理，再來一章章的主題式介紹相關模組。

這代表如果你從這個手冊的最開始讀起，並在感到無聊時跳到下一個章節，你仍然可以得到一個對 Python 函式庫所支援的模組與其合理應用的概觀。當然，你`沒有必要'像是在讀一本小說一樣讀這本手冊——你可以快速瀏覽目錄（在手冊的最前頭）、或是你可以利用最後面的索引來查詢特定的函式或模組。最後，如果你享受閱讀一些隨機的主題，你可以選擇一個隨機的數字並開始閱讀（見 @ref{bd,,random} 模組) 。不管你想要以什麼順序來閱讀這個手冊，@ref{145d,,內建函式}會是一個很好的入門，因為手冊中其他章節都預設你已經對這個章節有一定的熟悉程度。

讓我們開始吧！

@menu
* 可用性之標註:: 

@end menu

@node 可用性之標註,,,簡介<6>
@anchor{library/intro availability}@anchor{2006}@anchor{library/intro notes-on-availability}@anchor{2459}
@subsection 可用性之標註



@itemize *

@item 
如果出現「適用：Unix」標註，則代表該函式普遍存在於 Unix 系統中，但這並不保證其存在於某特定作業系統。

@item 
如果沒有分別標註的話，有標明「適用：Unix」標註的所有函式也都於 macOS、iOS 和 Android 上支援，因其建於 Unix 核心之上。

@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 平台:: 
* 行動平台:: 

@end menu

@node WebAssembly 平台,行動平台,,可用性之標註
@anchor{library/intro wasm-availability}@anchor{1a99}@anchor{library/intro webassembly-platforms}@anchor{245a}
@subsubsection WebAssembly 平台


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{8a4,,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{4b0,,fork()},
@ref{12fa,,execve()}), wait for processes (@ref{f95,,waitpid()}), send signals
(@ref{155f,,kill()}), or otherwise interact with processes. The
@ref{dc,,subprocess} is importable but does not work.

@item 
The @ref{d1,,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{2120}
@node 行動平台,,WebAssembly 平台,可用性之標註
@anchor{library/intro ios-availability}@anchor{245b}@anchor{library/intro mobile-platforms}@anchor{245c}
@subsubsection 行動平台


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{211f,,Python embedding API}. For more details, see
@ref{211d,,在 Android 上使用 Python} and @ref{2125,,在 iOS 上使用 Python}.

@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{2f,,curses} and @ref{bf,,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 內建函式<2>,內建常數,簡介<6>,Python 標準函式庫 Standard Library
@anchor{library/functions doc}@anchor{245d}@anchor{library/functions built-in-funcs}@anchor{145d}@anchor{library/functions built-in-functions}@anchor{245e}@anchor{library/functions translation-repo}@anchor{245f}
@section 內建函式


Python 直譯器有內建多個可隨時使用的函式和型別。以下按照英文字母排序列出。


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

內建函式

@tab

@tab

@tab

@item


@display
`A'@w{ }
@ref{1f54,,abs()}@w{ }
@ref{9ce,,aiter()}@w{ }
@ref{1619,,all()}@w{ }
@ref{9cf,,anext()}@w{ }
@ref{1618,,any()}@w{ }
@ref{15dd,,ascii()}@w{ }
@w{ }
`B'@w{ }
@ref{14a9,,bin()}@w{ }
@ref{3c1,,bool()}@w{ }
@ref{271,,breakpoint()}@w{ }
@ref{1d62,,bytearray()}@w{ }
@ref{1d61,,bytes()}@w{ }
@w{ }
`C'@w{ }
@ref{13c7,,callable()}@w{ }
@ref{193e,,chr()}@w{ }
@ref{489,,classmethod()}@w{ }
@ref{4ac,,compile()}@w{ }
@ref{197,,complex()}@w{ }
@w{ }
`D'@w{ }
@ref{2460,,delattr()}@w{ }
@ref{2461,,dict()}@w{ }
@ref{83d,,dir()}@w{ }
@ref{b90,,divmod()}@w{ }
@w{ }
@end display



@tab


@display
`E'@w{ }
@ref{1675,,enumerate()}@w{ }
@ref{49e,,eval()}@w{ }
@ref{49d,,exec()}@w{ }
@w{ }
`F'@w{ }
@ref{a5d,,filter()}@w{ }
@ref{196,,float()}@w{ }
@ref{199,,format()}@w{ }
@ref{2462,,frozenset()}@w{ }
@w{ }
`G'@w{ }
@ref{dc5,,getattr()}@w{ }
@ref{1b1e,,globals()}@w{ }
@w{ }
`H'@w{ }
@ref{6f2,,hasattr()}@w{ }
@ref{7fa,,hash()}@w{ }
@ref{acb,,help()}@w{ }
@ref{14d0,,hex()}@w{ }
@w{ }
`I'@w{ }
@ref{161a,,id()}@w{ }
@ref{14d9,,input()}@w{ }
@ref{19b,,int()}@w{ }
@ref{2ad,,isinstance()}@w{ }
@ref{9bd,,issubclass()}@w{ }
@ref{9d0,,iter()}@w{ }
@end display



@tab


@display
`L'@w{ }
@ref{839,,len()}@w{ }
@ref{2463,,list()}@w{ }
@ref{469,,locals()}@w{ }
@w{ }
`M'@w{ }
@ref{19f,,map()}@w{ }
@ref{1107,,max()}@w{ }
@ref{2464,,memoryview()}@w{ }
@ref{1106,,min()}@w{ }
@w{ }
`N'@w{ }
@ref{9d1,,next()}@w{ }
@w{ }
`O'@w{ }
@ref{c75,,object()}@w{ }
@ref{14cf,,oct()}@w{ }
@ref{315,,open()}@w{ }
@ref{21ef,,ord()}@w{ }
@w{ }
`P'@w{ }
@ref{1a4,,pow()}@w{ }
@ref{1170,,print()}@w{ }
@ref{4ae,,property()}@w{ }
@w{ }
@w{ }
@w{ }
@w{ }
@end display



@tab


@display
`R'@w{ }
@ref{2465,,range()}@w{ }
@ref{1c1,,repr()}@w{ }
@ref{a5e,,reversed()}@w{ }
@ref{14db,,round()}@w{ }
@w{ }
`S'@w{ }
@ref{2466,,set()}@w{ }
@ref{2467,,setattr()}@w{ }
@ref{68d,,slice()}@w{ }
@ref{dc2,,sorted()}@w{ }
@ref{451,,staticmethod()}@w{ }
@ref{2468,,str()}@w{ }
@ref{68e,,sum()}@w{ }
@ref{1a6,,super()}@w{ }
@w{ }
`T'@w{ }
@ref{2469,,tuple()}@w{ }
@ref{f3f,,type()}@w{ }
@w{ }
`V'@w{ }
@ref{1ceb,,vars()}@w{ }
@w{ }
`Z'@w{ }
@ref{1a0,,zip()}@w{ }
@w{ }
`_'@w{ }
@ref{ac8,,__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{1f54}
@deffn {函式} abs (number, /)

回傳一個數的絕對值，引數可以是整數、浮點數或有實現 @ref{22b4,,__abs__()} 的物件。如果引數是一個複數，回傳它的純量（大小）。
@end deffn

@geindex built-in function; aiter()
@anchor{library/functions aiter}@anchor{9ce}
@deffn {函式} aiter (async_iterable, /)

回傳 @ref{4c2,,非同步疊代器} 做為 @ref{f6f,,非同步可疊代物件}。相當於呼叫 x.__aiter__()。

注意：與 @ref{9d0,,iter()} 不同，@ref{9ce,,aiter()} 沒有兩個引數的變體。


在 3.10 版被加入.

@end deffn

@geindex built-in function; all()
@anchor{library/functions all}@anchor{1619}
@deffn {函式} all (iterable, /)

如果 `iterable' 的所有元素皆為真（或 iterable 為空）則回傳 @code{True}。等價於：

@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{9cf}
@deffn {函式} awaitable anext (async_iterator, /)

@deffnx {函式} awaitable anext (async_iterator, default, /)

當進入 await 時，從給定的 @ref{4c2,,asynchronous iterator} 中回傳下一個項目（item），疊代完畢則回傳 `default' 。

這是內建函式 @ref{9d1,,next()} 的非同步版本，其行為類似於：

呼叫 `async_iterator' 的 @ref{17fd,,__anext__()} 方法，回傳 @ref{4c4,,awaitable}。等待返回疊代器的下一個值。如果指定 `default'，當疊代器結束時會返回該值，否則會引發 @ref{1cd7,,StopAsyncIteration} 。


在 3.10 版被加入.

@end deffn

@geindex built-in function; any()
@anchor{library/functions any}@anchor{1618}
@deffn {函式} any (iterable, /)

如果 `iterable' 的任一元素為真，回傳 @code{True}。如果 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{15dd}
@deffn {函式} ascii (object, /)

就像函式 @ref{1c1,,repr()}，回傳一個表示物件的字串，但是 @ref{1c1,,repr()} 回傳的字串中非 ASCII 編碼的字元會被跳脫 (escape)，像是 @code{\x}、@code{\u} 和 @code{\U}。這個函式生成的字串和 Python 2 的 @ref{1c1,,repr()} 回傳的結果相似。
@end deffn

@geindex built-in function; bin()
@anchor{library/functions bin}@anchor{14a9}
@deffn {函式} bin (integer, /)

將一個整數轉變為一個前綴為 "0b" 的二進位制字串。結果是一個有效的 Python 運算式。如果 `integer' 不是 Python 的 @ref{19b,,int} 物件，那它需要定義 @ref{19e,,__index__()} method 回傳一個整數。舉例來說：

@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

可參考 @ref{199,,format()} 取得更多資訊。
@end deffn

@geindex bool (內建類別)
@anchor{library/functions bool}@anchor{3c1}
@deffn {類別} bool (object=False, /)

回傳一個布林值，即 @code{True} 或者 @code{False}。引數會使用標準的@ref{17d7,,真值測試程序}來轉換。如果引數為假或者被省略，則回傳 @code{False}；其他情況回傳 @code{True}。@ref{3c1,,bool} class（類別）是 @ref{19b,,int} 的 subclass（子類別）（參見 @ref{1ea3,,數值型別 --- int、float、complex}），其他 class 不能繼承自它。它只有 @code{False} 和 @code{True} 兩個實例（參見 @ref{246a,,Boolean 型別 - bool}）。

@geindex Boolean（布林值）;type（型別）


在 3.7 版的變更: 現在為僅限位置參數。

@end deffn

@geindex built-in function; breakpoint()
@anchor{library/functions breakpoint}@anchor{271}
@deffn {函式} breakpoint (*args, **kws)

這個函式將呼叫 @ref{cc8,,sys.breakpointhook()} 函式，並將 @code{args} 和 @code{kws} 傳遞給它。這將有效地讓你在特定的呼叫點進入除錯器。預設情況下，@code{sys.breakpointhook()} 呼叫 @ref{272,,pdb.set_trace()} 不須帶任何引數。這樣的設計是為了方便使用者，讓他們不需要額外地導入 @ref{aa,,pdb} 模組或輸入太多程式就可以進入除錯器。然而，可以將 @ref{cc8,,sys.breakpointhook()} 設置為其他函式，並且 @ref{271,,breakpoint()} 將自動呼叫該函式，讓你進入所選擇的除錯器。如果無法存取 @ref{cc8,,sys.breakpointhook()} 這個函式，則此函式將引發 @ref{244,,RuntimeError}。

預設情況下，@ref{271,,breakpoint()} 的行為可以透過 
@geindex PYTHONBREAKPOINT
@geindex 環境變數; PYTHONBREAKPOINT
@ref{cc9,,PYTHONBREAKPOINT} 環境變數來更改。有關使用詳情，請參考 @ref{cc8,,sys.breakpointhook()}。

請注意，如果 @ref{cc8,,sys.breakpointhook()} 被替換了，則無法保證此功能。

引發一個附帶引數 @code{breakpointhook} 的@ref{1b70,,稽核事件} @code{builtins.breakpoint}。


在 3.7 版被加入.

@end deffn

@anchor{library/functions func-bytearray}@anchor{1d62}
@deffn {類別} bytearray (source=b'@w{'})

@deffnx {類別} bytearray (source, encoding, errors='strict')

回傳一個新的 bytes 陣列。@ref{343,,bytearray} class 是一個可變的整數序列，包含範圍為 0 <= x < 256 的整數。它有可變序列大部分常見的 method（如在 @ref{246b,,可變序列型別} 中所述），同時也有 @ref{192,,bytes} 型別大部分的 method，參見 @ref{246c,,Bytes 和 Bytearray 的操作}。

選擇性參數 `source' 可以被用來以不同的方式初始化陣列：


@itemize *

@item 
如果是一個 `string'，你必須提供 `encoding' 參數（以及選擇性地提供 `errors' ）；@ref{343,,bytearray()} 會使用 @ref{ac9,,str.encode()} method 來將 string 轉變成 bytes。

@item 
如果是一個 `integer'，陣列則會有該數值的長度，並以 null bytes 來當作初始值。

@item 
如果是一個符合 @ref{260,,buffer 介面}的物件，該物件的唯讀 buffer 會被用來初始化 bytes 陣列。

@item 
如果是一個 `iterable'，它的元素必須是範圍為 @code{0 <= x < 256} 的整數，並且會被用作陣列的初始值。
@end itemize

如果沒有引數，則建立長度為 0 的陣列。

可參考 @ref{246d,,Binary Sequence Types --- bytes@comma{} bytearray@comma{} memoryview} 和 @ref{246e,,Bytearray 物件}。
@end deffn

@anchor{library/functions func-bytes}@anchor{1d61}
@deffn {類別} bytes (source=b'@w{'})

@deffnx {類別} bytes (source, encoding, errors='strict')

回傳一個新的 "bytes" 物件，會是一個元素是範圍為 @code{0 <= x < 256} 整數的不可變序列。@ref{192,,bytes} 是 @ref{343,,bytearray} 的不可變版本 — 它的同樣具備不改變物件的 method，也有相同的索引和切片操作。

因此，建構函式的引數和 @ref{343,,bytearray()} 相同。

Bytes 物件還可以用文字建立，參見 @ref{2163,,String and Bytes literals}。

可參考 @ref{246d,,Binary Sequence Types --- bytes@comma{} bytearray@comma{} memoryview}、@ref{246f,,Bytes Objects} 和 @ref{246c,,Bytes 和 Bytearray 的操作}。
@end deffn

@geindex built-in function; callable()
@anchor{library/functions callable}@anchor{13c7}
@deffn {函式} callable (object, /)

如果引數 `object' 是可呼叫的，回傳 @ref{e02,,True}，否則回傳 @ref{d23,,False}。如果回傳 @code{True}，呼叫仍可能會失敗；但如果回傳 @code{False}，則呼叫 `object' 肯定會失敗。注意 class 是可呼叫的（呼叫 class 會回傳一個新的實例）；如果實例的 class 有定義 @ref{773,,__call__()} method，則它是可呼叫的。


在 3.2 版被加入: 這個函式一開始在 Python 3.0 被移除，但在 Python 3.2 又被重新加入。

@end deffn

@geindex built-in function; chr()
@anchor{library/functions chr}@anchor{193e}
@deffn {函式} chr (codepoint, /)

回傳代表有特定 Unicode 編碼位置字元的字串。例如，@code{chr(97)} 回傳字串 @code{'a'}，而 @code{chr(8364)} 回傳字串 @code{'€'}。這是 @ref{21ef,,ord()} 的逆函式。

引數的有效範圍是 0 到 1,114,111（16 進制表示為 0x10FFFF）。如果它超過這個範圍，會引發 @ref{2eb,,ValueError}。
@end deffn

@geindex built-in function; classmethod()
@anchor{library/functions classmethod}@anchor{489}
@deffn {函式} @@classmethod

把一個 method 封裝成 class method（類別方法）。

一個 class method 把自己的 class 作為第一個引數，就像一個實例 method 把實例自己作為第一個引數。請用以下慣例來宣告 class method：

@example
class C:
    @@classmethod
    def f(cls, arg1, arg2): ...
@end example

@code{@@classmethod} 語法是一個函式 @ref{932,,decorator} — 參見 @ref{1ee1,,函式定義} 中關於函式定義的詳細介紹。

一個 class method 可以在 class（如 @code{C.f()}）或實例（如 @code{C().f()}）上呼叫。實例除了它的 class 資訊，其他都會被忽略。如果一個 class method 在 subclass 上呼叫，subclass 會作為第一個引數傳入。

Class method 和 C++ 與 Java 的 static method 是有區別的。如果你想瞭解 static method，請看本節的 @ref{451,,staticmethod()}。關於 class method 的更多資訊，請參考@ref{21e4,,標準型別階層}。


在 3.9 版的變更: Class methods 現在可以包裝其他@ref{17fc,,描述器}，例如 @ref{4ae,,property()}



在 3.10 版的變更: Class method 現在繼承了 method 屬性（@ref{21fc,,__module__}、@ref{14d5,,__name__}、@ref{21fb,,__qualname__}、@ref{13da,,__doc__} 和 @ref{13d9,,__annotations__}），並擁有一個新的 @code{__wrapped__} 屬性。



Deprecated since version 3.11, removed in version 3.13: Class methods 不能再包裝其他的@ref{17fc,,描述器}，例如 @ref{4ae,,property()}。

@end deffn

@geindex built-in function; compile()
@anchor{library/functions compile}@anchor{4ac}
@deffn {函式} compile (source, filename, mode, flags=0, dont_inherit=False, optimize=-1)

將 `source' 編譯成程式碼或 AST 物件。程式碼物件可以被 @ref{49d,,exec()} 或 @ref{49e,,eval()} 執行。`source' 可以是一般的字串、bytes 字串、或者 AST 物件。參見 @ref{9,,ast} module（模組）的說明文件瞭解如何使用 AST 物件。

`filename' 引數必須是程式碼的檔名；如果程式碼不是從檔案中讀取，可以傳入一些可辨識的值（經常會使用 @code{'<string>'} 來替代）。

`mode' 引數指定了編譯程式碼時必須用的模式。如果 `source' 是一系列的陳述式，可以是 @code{'exec'}；如果是單一運算式，可以是 @code{'eval'}；如果是單個互動式陳述式，可以是 @code{'single'}（在最後一種情況下，如果運算式執行結果不是 @code{None} 則會被印出來）。

可選引數 `flags' 和 `dont_inherit' 控制啟用哪個@ref{2470,,編譯器選項}以及允許哪個@ref{45b,,未來功能}。如果兩者都不存在（或兩者都為零），則會呼叫與 @ref{4ac,,compile()} 相同旗標的程式碼來編譯。如果給定 `flags' 引數而未給定 `dont_inherit*（或為零）則無論如何都會使用由 *flags' 引數所指定的編譯器選項和未來陳述式。如果 `dont_inherit' 是一個非零整數，則使用 `flags' 引數 -- 周圍程式碼中的旗標（未來功能和編譯器選項）將被忽略。

編譯器選項和 future 陳述式使用 bits 來表示，可以一起被位元操作 OR 來表示複數個選項。需要被具體定義特徵的位元域可以透過 @ref{0,,__future__} module 中 @ref{2471,,_Feature} 實例中的 @ref{2244,,compiler_flag} 屬性來獲得。@ref{2470,,編譯器旗標}可以在 @ref{9,,ast} module 中搜尋有 @code{PyCF_} 前綴的名稱。

引數 `optimize' 用來指定編譯器的最佳化級別；預設值 @code{-1} 選擇與直譯器的 @ref{18c,,-O} 選項相同的最佳化級別。其他級別為 @code{0}（沒有最佳化；@code{__debug__} 為真值）、@code{1}（assert 被刪除，@code{__debug__} 為假值）或 @code{2}（說明字串 (docstring) 也被刪除）。

如果編譯的原始碼無效，此函式會引發 @ref{18e,,SyntaxError}，如果原始碼包含 null bytes，則會引發 @ref{2eb,,ValueError}。

如果你想解析 Python 程式碼為 AST 運算式，請參閱 @ref{1c2,,ast.parse()}。

引發一個附帶引數 @code{source}、@code{filename} 的@ref{1b70,,稽核事件} @code{compile}。此事件也可能由隱式編譯 (implicit compilation) 所引發。

@cartouche
@quotation 備註 
在 @code{'single'} 或 @code{'eval'} 模式編譯多行程式碼時，輸入必須以至少一個換行符結尾。這使 @ref{1b,,code} module 更容易檢測陳述式的完整性。
@end quotation
@end cartouche

@cartouche
@quotation 警告 
如果編譯足夠大或者足夠複雜的字串成 AST 物件時，Python 直譯器會因為 Python AST 編譯器的 stack 深度限制而崩潰。
@end quotation
@end cartouche


在 3.2 版的變更: 允許使用 Windows 和 Mac 的換行符號。此外，在 @code{'exec'} 模式不需要以換行符號結尾。增加了 `optimize' 參數。



在 3.5 版的變更: 在之前的版本，`source' 中包含 null bytes 會引發 @ref{198,,TypeError}。



在 3.8 版被加入: @code{ast.PyCF_ALLOW_TOP_LEVEL_AWAIT} 現在可以傳遞旗標以啟用對頂層 @code{await}、@code{async for} 和 @code{async with} 的支援。

@end deffn

@geindex complex (內建類別)
@anchor{library/functions complex}@anchor{197}
@deffn {類別} complex (number=0, /)

@deffnx {類別} complex (string, /)

@deffnx {類別} complex (real=0, imag=0)

Convert a single string or number to a complex number, or create a
complex number from real and imaginary parts.

例如：

@example
>>> complex('+1.23')
(1.23+0j)
>>> complex('-4.5j')
-4.5j
>>> complex('-1.23+4.5j')
(-1.23+4.5j)
>>> complex('\t( -1.23+4.5J )\n')
(-1.23+4.5j)
>>> complex('-Infinity+NaNj')
(-inf+nanj)
>>> complex(1.23)
(1.23+0j)
>>> complex(imag=-4.5)
-4.5j
>>> complex(-1.23, 4.5)
(-1.23+4.5j)
@end example

If the argument is a string, it must contain either a real part (in the
same format as for @ref{196,,float()}) or an imaginary part (in the same
format but with a @code{'j'} or @code{'J'} suffix), or both real and imaginary
parts (the sign of the imaginary part is mandatory in this case).
The string can optionally be surrounded by whitespaces and the round
parentheses @code{'('} and @code{')'}, which are ignored.
The string must not contain whitespace between @code{'+'}, @code{'-'}, the
@code{'j'} or @code{'J'} suffix, and the decimal number.
For example, @code{complex('1+2j')} is fine, but @code{complex('1 + 2j')} raises
@ref{2eb,,ValueError}.
More precisely, the input must conform to the @ref{2472,,complexvalue}
production rule in the following grammar, after parentheses and leading and
trailing whitespace characters are removed:

@example
@anchor{library/functions grammar-token-float-complexvalue}@anchor{2472}complexvalue: @ref{2473,,floatvalue} |
              @ref{2473,,floatvalue} ("j" | "J") |
              @ref{2473,,floatvalue} @ref{2474,,sign} @ref{2475,,absfloatvalue} ("j" | "J")
@end example

如果引數是一個數字，則建構函式會像 @ref{19b,,int} 和 @ref{196,,float} 一樣進行數值轉換。對於一個普通的 Python 物件 @code{x}，@code{complex(x)} 會委派給 @code{x.__complex__()}。如果 @ref{7f8,,__complex__()} 未定義，則會回退 (fall back) 到 @ref{bb8,,__float__()}。如果 @code{__float__()} 未定義，則會再回退到 @ref{19e,,__index__()}。

If two arguments are provided or keyword arguments are used, each argument
may be any numeric type (including complex).
If both arguments are real numbers, return a complex number with the real
component `real' and the imaginary component `imag'.
If both arguments are complex numbers, return a complex number with the real
component @code{real.real-imag.imag} and the imaginary component
@code{real.imag+imag.real}.
If one of arguments is a real number, only its real component is used in
the above expressions.

See also @ref{195,,complex.from_number()} which only accepts a single numeric argument.

If all arguments are omitted, returns @code{0j}.

複數型別在 @ref{1ea3,,數值型別 --- int、float、complex} 中有相關描述。


在 3.6 版的變更: 可以使用底線將程式碼文字中的數字進行分組。



在 3.8 版的變更: 如果 @ref{7f8,,__complex__()} 和 @ref{bb8,,__float__()} 未定義，則會回退到 @ref{19e,,__index__()}。



在 3.14 版之後被棄用: Passing a complex number as the `real' or `imag' argument is now
deprecated; it should only be passed as a single positional argument.

@end deffn

@geindex built-in function; delattr()
@anchor{library/functions delattr}@anchor{2460}
@deffn {函式} delattr (object, name, /)

這是 @ref{2467,,setattr()} 相關的函式。引數是一個物件和一個字串，該字串必須是物件中某個屬性名稱。如果物件允許，該函式將刪除指定的屬性。例如 @code{delattr(x, 'foobar')} 等價於 @code{del x.foobar}。`name' 不必是個 Python 識別符 (identifier)（請見 @ref{2467,,setattr()}）。
@end deffn

@anchor{library/functions func-dict}@anchor{2461}
@deffn {類別} dict (**kwargs)

@deffnx {類別} dict (mapping, /, **kwargs)

@deffnx {類別} dict (iterable, /, **kwargs)

建立一個新的 dictionary（字典）。@ref{183,,dict} 物件是一個 dictionary class。參見 @ref{183,,dict} 和 @ref{cb4,,Mapping Types --- dict} 來瞭解這個 class。

其他容器型別，請參見內建的 @ref{24d,,list}、@ref{184,,set} 和 @ref{60c,,tuple} class，以及 @ref{1e,,collections} module。
@end deffn

@geindex built-in function; dir()
@anchor{library/functions dir}@anchor{83d}
@deffn {函式} dir ()

@deffnx {函式} dir (object, /)

如果沒有引數，則回傳目前區域作用域 (local scope) 中的名稱列表。如果有引數，它會嘗試回傳該物件的有效屬性列表。

如果物件有一個名為 @ref{176b,,__dir__()} 的 method，那麼該 method 將被呼叫，並且必須回傳一個屬性列表。這允許實現自定義 @ref{6f3,,__getattr__()} 或 @ref{dc6,,__getattribute__()} 函式的物件能夠自定義 @ref{83d,,dir()} 來報告它們的屬性。

如果物件不提供 @ref{176b,,__dir__()}，這個函式會嘗試從物件已定義的 @ref{776,,__dict__} 屬性和型別物件收集資訊。結果列表並不總是完整的，如果物件有自定義 @ref{6f3,,__getattr__()}，那結果可能不準確。

預設的 @ref{83d,,dir()} 機制對不同型別的物件有不同行為，它會試圖回傳最相關而非最完整的資訊：


@itemize *

@item 
如果物件是 module 物件，則列表包含 module 的屬性名稱。

@item 
如果物件是型別或 class 物件，則列表包含它們的屬性名稱，並且遞迴查詢其基礎的所有屬性。

@item 
否則，包含物件的屬性名稱列表、它的 class 屬性名稱，並且遞迴查詢它的 class 的所有基礎 class 的屬性。
@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__', '__cached__', '__doc__', '__file__',
 '__initializing__', '__loader__', '__name__', '__package__',
 '_clearcache', 'calcsize', 'error', 'pack', 'pack_into',
 'unpack', 'unpack_from']
>>> class Shape:
...     def __dir__(self):
...         return ['area', 'perimeter', 'location']
...
>>> s = Shape()
>>> dir(s)
['area', 'location', 'perimeter']
@end example

@cartouche
@quotation 備註 
因為 @ref{83d,,dir()} 主要是為了便於在互動式提示字元時使用，所以它會試圖回傳人們感興趣的名稱集合，而不是試圖保證結果的嚴格性或一致性，它具體的行為也可能在不同版本之間改變。例如，當引數是一個 class 時，metaclass 的屬性不包含在結果列表中。
@end quotation
@end cartouche
@end deffn

@geindex built-in function; divmod()
@anchor{library/functions divmod}@anchor{b90}
@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{1675}
@deffn {函式} enumerate (iterable, start=0)

回傳一個列舉 (enumerate) 物件。`iterable' 必須是一個序列、@ref{4c3,,iterator} 或其他支援疊代的物件。@ref{1675,,enumerate()} 回傳之 iterator 的 @ref{14ce,,__next__()} method 回傳一個 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{2476}@anchor{library/functions eval}@anchor{49e}
@deffn {函式} eval (source, /, globals=None, locals=None)

@*參數: 

@itemize *

@item 
@code{source} (@ref{169,,str} | @ref{4e1,,code object}) -- A Python expression.

@item 
@code{globals} (@ref{183,,dict} | @code{None}) -- The global namespace (default: @code{None}).

@item 
@code{locals} (@ref{13bc,,mapping} | @code{None}) -- The local namespace (default: @code{None}).
@end itemize


@*回傳: 
The result of the evaluated expression.


@*引發: 
Syntax errors are reported as exceptions.


@cartouche
@quotation 警告 
This function executes arbitrary code. Calling it with
user-supplied input may lead to security vulnerabilities.
@end quotation
@end cartouche

`expression' 引數會被視為一條 Python 運算式（技術上而言，是條件列表）來剖析及求值，而 `globals' 和 `locals' 對映分別用作全域和區域命名空間。如果 `globals' dictionary 存在但缺少 @code{__builtins__} 的鍵值，那 `expression' 被剖析之前，將為該鍵插入對內建 @ref{13,,builtins} module dictionary 的引用。這麼一來，在將 @code{__builtins__} dictionary 傳入 @ref{49e,,eval()} 之前，你可以透過將它插入 `globals' 來控制你需要哪些內建函式來執行程式碼。如果 `locals' 對映被省略，那它的預設值是 `globals' dictionary。如果兩個對映都被省略，則以在 @ref{49e,,eval()} 被呼叫的環境中的 `globals' 和 `locals' 執行運算式。請注意，`eval()' 在封閉 (enclosing) 環境中無法存取@ref{223e,,巢狀作用域} (non-locals)，除非呼叫 @ref{49e,,eval()} 的作用域已經有參照它們（例如透過 @ref{14a8,,nonlocal} 陳述式）。

範例：

@example
>>> x = 1
>>> eval('x+1')
2
@end example

這個函式也可以用來執行任意程式碼物件（如被 @ref{4ac,,compile()} 建立的那些）。這種情況下，傳入的引數是程式碼物件而不是字串。如果編譯該物件時的 `mode' 引數是 @code{'exec'}，那麼 @ref{49e,,eval()} 回傳值為 @code{None}。

提示：@ref{49d,,exec()} 函式支援動態執行陳述式。@ref{1b1e,,globals()} 和 @ref{469,,locals()} 函式分別回傳目前的全域性和局部性 dictionary，它們對於將引數傳遞給 @ref{49e,,eval()} 或 @ref{49d,,exec()} 可能會方便許多。

如果給定來源是一個字串，那麼其前後的空格和定位字元會被移除。

另外可以參閱 @ref{e0d,,ast.literal_eval()}，該函式可以安全執行僅包含文字的運算式字串。

引發一個附帶程式碼物件為引數的@ref{1b70,,稽核事件} @code{exec}。也可能會引發程式碼編譯事件。


在 3.13 版的變更: The `globals' and `locals' arguments can now be passed as keywords.



在 3.13 版的變更: The semantics of the default `locals' namespace have been adjusted as
described for the @ref{469,,locals()} builtin.

@end deffn

@geindex built-in function（內建函式）;exec

@geindex built-in function; exec()
@anchor{library/functions exec}@anchor{49d}
@deffn {函式} exec (source, /, globals=None, locals=None, *, closure=None)

@cartouche
@quotation 警告 
This function executes arbitrary code. Calling it with
user-supplied input may lead to security vulnerabilities.
@end quotation
@end cartouche

這個函式支援動態執行 Python 程式碼。`source' 必須是字串或者程式碼物件。如果是字串，那麼該字串將被剖析為一系列 Python 陳述式並執行（除非發生語法錯誤）。@footnote{
剖析器只接受 Unix 風格的行結束符。如果你從檔案中讀取程式碼，請確保用換行符號轉換模式轉換 Windows 或 Mac 風格的換行符號。
} 如果是程式碼物件，它將被直接執行。無論哪種情況，被執行的程式碼都需要和檔案輸入一樣是有效的（可參閱語言參考手冊中關於@ref{2447,,檔案輸入}的章節）。請注意，即使在傳遞給 @ref{49d,,exec()} 函式的程式碼的上下文中，@ref{14a8,,nonlocal}、@ref{bb9,,yield} 和 @ref{1af,,return} 陳述式也不能在函式之外使用。該函式回傳值是 @code{None}。

無論哪種情況，如果省略了選擇性的部分，程式碼將在目前作用域內執行。如果只提供了 `globals' 引數，就必須是 dictionary 型別（且不能是 dictionary 的子類別），而且會被用作全域和區域變數。如果同時提供了 `globals' 和 `locals'，它們分別被用作全域和區域變數。如果提供了 `locals'，則它可以是任何對映物件。請記住在 module 層級中全域和區域變數是相同的 dictionary。

@cartouche
@quotation 備註 
When @code{exec} gets two separate objects as `globals' and `locals', the
code will be executed as if it were embedded in a class definition. This
means functions and classes defined in the executed code will not be able
to access variables assigned at the top level (as the "top level"
variables are treated as class variables in a class definition).
@end quotation
@end cartouche

如果 `globals' dictionary 不包含 @code{__builtins__} 鍵值，則將為該鍵插入對內建 @ref{13,,builtins} module dictionary 的引用。這麼一來，在將 @code{__builtins__} dictionary 傳入 @ref{49d,,exec()} 之前，你可以透過將它插入 `globals' 來控制你需要哪些內建函式來執行程式碼。

`closure' 引數會指定一個閉包 (closure) — 它是一個 cellvar（格變數）的 tuple。只有在 `object' 是一個含有@ref{180c,,自由（閉包）變數 (free (closure) variables)} 的程式碼物件時，它才有效。Tuple 的長度必須與程式碼物件的 @ref{21f9,,co_freevars} 屬性完全匹配。

引發一個附帶程式碼物件為引數的@ref{1b70,,稽核事件} @code{exec}。也可能會引發程式碼編譯事件。

@cartouche
@quotation 備註 
內建 @ref{1b1e,,globals()} 和 @ref{469,,locals()} 函式各自回傳目前的全域和區域命名空間，因此可以將它們傳遞給 @ref{49d,,exec()} 的第二個和第三個引數以供後續使用。
@end quotation
@end cartouche

@cartouche
@quotation 備註 
預設情況下，`locals' 的行為如下面 @ref{469,,locals()} 函式描述的一樣。如果你想在 @ref{49d,,exec()} 函式回傳時知道程式碼對 `locals' 的變動，請明確地傳遞 `locals' dictionary 。
@end quotation
@end cartouche


在 3.11 版的變更: 增加了 `closure' 參數。



在 3.13 版的變更: The `globals' and `locals' arguments can now be passed as keywords.



在 3.13 版的變更: The semantics of the default `locals' namespace have been adjusted as
described for the @ref{469,,locals()} builtin.

@end deffn

@geindex built-in function; filter()
@anchor{library/functions filter}@anchor{a5d}
@deffn {函式} filter (function, iterable, /)

用 `iterable' 中函式 `function' 為 True 的那些元素，構建一個新的 iterator。`iterable' 可以是一個序列、一個支援疊代的容器、或一個 iterator。如果 `function' 是 @code{None}，則會假設它是一個識別性函式，即 `iterable' 中所有假值元素會被移除。

請注意，@code{filter(function, iterable)} 相當於一個生成器運算式，當 function 不是 @code{None} 的時候為 @code{(item for item in iterable if function(item))}；function 是 @code{None} 的時候為 @code{(item for item in iterable if item)}。

請參閱 @ref{2477,,itertools.filterfalse()}，只有 `function' 為 false 時才選取 `iterable' 中元素的互補函式。
@end deffn

@geindex float (內建類別)
@anchor{library/functions float}@anchor{196}
@deffn {類別} float (number=0.0, /)

@deffnx {類別} float (string, /)

@geindex NaN
@geindex Infinity（無窮）

回傳從數字或字串生成的浮點數。

例如：

@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

如果引數是字串，則它必須是包含十進位制數字的字串，字串前面可以有符號，之前也可以有空格。選擇性的符號有 @code{'+'} 和 @code{'-'}；@code{'+'} 對建立的值沒有影響。引數也可以是 NaN（非數字）或正負無窮大的字串。確切地說，除去首尾的空格後，輸入必須遵循以下語法中 @ref{2473,,floatvalue} 的生成規則：

@example
@anchor{library/functions grammar-token-float-sign}@anchor{2474}sign:          "+" | "-"
@anchor{library/functions grammar-token-float-infinity}@anchor{2478}infinity:      "Infinity" | "inf"
@anchor{library/functions grammar-token-float-nan}@anchor{2479}nan:           "nan"
@anchor{library/functions grammar-token-float-digit}@anchor{247a}digit:         <a Unicode decimal digit, i.e. characters in Unicode general category Nd>
@anchor{library/functions grammar-token-float-digitpart}@anchor{247b}digitpart:     @ref{247a,,digit} (["_"] @ref{247a,,digit})*
@anchor{library/functions grammar-token-float-number}@anchor{247c}number:        [@ref{247b,,digitpart}] "." @ref{247b,,digitpart} | @ref{247b,,digitpart} ["."]
@anchor{library/functions grammar-token-float-exponent}@anchor{247d}exponent:      ("e" | "E") [@ref{2474,,sign}] @ref{247b,,digitpart}
@anchor{library/functions grammar-token-float-floatnumber}@anchor{247e}floatnumber:   @ref{247c,,number} [@ref{247d,,exponent}]
@anchor{library/functions grammar-token-float-absfloatvalue}@anchor{2475}absfloatvalue: @ref{247e,,floatnumber} | @ref{2478,,infinity} | @ref{2479,,nan}
@anchor{library/functions grammar-token-float-floatvalue}@anchor{2473}floatvalue:    [@ref{2474,,sign}] @ref{2475,,absfloatvalue}
@end example

字母大小寫不影響，例如，"inf"、"Inf"、"INFINITY"、"iNfINity" 都可以表示正無窮大。

否則，如果引數是整數或浮點數，則回傳具有相同值（在 Python 浮點精度範圍內）的浮點數。如果引數在 Python 浮點精度範圍外，則會引發 @ref{a78,,OverflowError}。

對於一般的 Python 物件 @code{x}，@code{float(x)} 會委派給 @code{x.__float__()}。如果未定義 @ref{bb8,,__float__()} 則會回退到 @ref{19e,,__index__()}。

See also @ref{194,,float.from_number()} which only accepts a numeric argument.

如果沒有引數，則回傳 @code{0.0}。

@ref{1ea3,,數值型別 --- int、float、complex} 描述了浮點數型別。


在 3.6 版的變更: 可以使用底線將程式碼文字中的數字進行分組。



在 3.7 版的變更: 現在為僅限位置參數。



在 3.8 版的變更: 如果 @ref{bb8,,__float__()} 未定義，則會回退到 @ref{19e,,__index__()}。

@end deffn

@geindex __format__
@geindex string（字串）;format()（內建函式）

@geindex built-in function; format()
@anchor{library/functions format}@anchor{199}
@deffn {函式} format (value, format_spec='@w{'}, /)

將 `value' 轉換為 `format_spec' 控制的 "格式化" 表示。`format_spec' 的解釋取決於 `value' 引數的型別，但是大多數內建型別使用標準格式化語法：@ref{4f4,,格式規格 (Format Specification) 迷你語言}。

預設的 `format_spec' 是一個空字串，它通常和呼叫 @ref{169,,str(value)} 的效果相同。

呼叫 @code{format(value, format_spec)} 會轉換成 @code{type(value).__format__(value, format_spec)}，當搜尋 value 的 @ref{82a,,__format__()} method 時，會忽略實例中的字典。如果搜尋到 @ref{c75,,object} 這個 method 但 `format_spec' 不為空，或是 `format_spec' 或回傳值不是字串，則會引發 @ref{198,,TypeError}。


在 3.4 版的變更: 當 `format_spec' 不是空字串時，@code{object().__format__(format_spec)} 會引發 @ref{198,,TypeError}。

@end deffn

@anchor{library/functions func-frozenset}@anchor{2462}
@deffn {類別} frozenset (iterable=(), /)

回傳一個新的 @ref{7eb,,frozenset} 物件，它包含選擇性引數 `iterable' 中的元素。@code{frozenset} 是一個內建的 class。有關此 class 的文件，請參閱 @ref{7eb,,frozenset} 和 @ref{247f,,Set Types --- set@comma{} frozenset}。

請參閱內建的 @ref{184,,set}、@ref{24d,,list}、@ref{60c,,tuple} 和 @ref{183,,dict} class，以及 @ref{1e,,collections} module 來了解其它的容器。
@end deffn

@geindex built-in function; getattr()
@anchor{library/functions getattr}@anchor{dc5}
@deffn {函式} getattr (object, name, /)

@deffnx {函式} getattr (object, name, default, /)

回傳 `object' 之具名屬性的值。`name' 必須是字串。如果該字串是物件屬性之一的名稱，則回傳該屬性的值。例如，@code{getattr(x, 'foobar')} 等同於 @code{x.foobar}。如果指定的屬性不存在，且提供了 `default' 值，則回傳其值，否則引發 @ref{5e8,,AttributeError}。`name' 不必是個 Python 識別符 (identifier)（請見 @ref{2467,,setattr()}）。

@cartouche
@quotation 備註 
由於@ref{1f6a,,私有名稱改編 (private name mangling)} 是發生在編譯期，因此你必須手動改編私有屬性（有兩個前導底線的屬性）的名稱，才能使用 @ref{dc5,,getattr()} 來取得它。
@end quotation
@end cartouche
@end deffn

@geindex built-in function; globals()
@anchor{library/functions globals}@anchor{1b1e}
@deffn {函式} globals ()

回傳代表目前 module 命名空間的 dictionary。對於在函式中的程式碼來說，這在定義函式時設定且不論該函式是在何處呼叫都會保持相同。
@end deffn

@geindex built-in function; hasattr()
@anchor{library/functions hasattr}@anchor{6f2}
@deffn {函式} hasattr (object, name, /)

該引數是一個物件和一個字串。如果字串是物件屬性之一的名稱，則回傳 @code{True}，否則回傳 @code{False}。（此功能是透過呼叫 @code{getattr(object, name)} 並檢查是否引發 @ref{5e8,,AttributeError} 來實作的。）
@end deffn

@geindex built-in function; hash()
@anchor{library/functions hash}@anchor{7fa}
@deffn {函式} hash (object, /)

回傳該物件的雜湊值（如果它有的話）。雜湊值是整數。它們在 dictionary 查詢元素時用來快速比較 dictionary 的鍵。相同大小的數字數值有相同的雜湊值（即使它們型別不同，如 1 和 1.0）。

@cartouche
@quotation 備註 
請注意，如果物件帶有自訂的 @ref{cea,,__hash__()} 方法，@ref{7fa,,hash()} 將根據運行機器的位元長度來截斷回傳值。
@end quotation
@end cartouche
@end deffn

@geindex built-in function; help()
@anchor{library/functions help}@anchor{acb}
@deffn {函式} help ()

@deffnx {函式} help (request)

啟動內建的幫助系統（此函式主要以互動式使用）。如果沒有引數，直譯器控制台裡會啟動互動式幫助系統。如果引數是一個字串，則會在 module、函式、class、method、關鍵字或說明文件主題中搜尋該字串，並在控制台上列印幫助資訊。如果引數是其他任意物件，則會生成該物件的幫助頁。

請注意，呼叫 @ref{acb,,help()} 時，如果斜線 (/) 出現在函式的參數列表中，這表示斜線前面的參數是僅限位置 (positional-only) 參數。有關更多資訊，請參閱@ref{2480,,常見問答集中的僅限位置參數條目}。

此函式會被 @ref{cc,,site} module 加入到內建命名空間。


在 3.4 版的變更: 對於 @ref{ba,,pydoc} 和 @ref{82,,inspect} 的變更，使得可呼叫物件回報的的簽名 (signature) 更加全面和一致。

@end deffn

@geindex built-in function; hex()
@anchor{library/functions hex}@anchor{14d0}
@deffn {函式} hex (integer, /)

將整數轉換為以 "0x" 為前綴的小寫十六進位制字串。如果 `integer' 不是 Python @ref{19b,,int} 物件，則必須定義一個 @ref{19e,,__index__()} method 並且回傳一個整數。舉例來說：

@example
>>> hex(255)
'0xff'
>>> hex(-42)
'-0x2a'
@end example

如果要將整數轉換為大寫或小寫的十六進位制字串，並可選擇有無 "0x" 前綴，則可以使用如下方法：

@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{199,,format()} 取得更多資訊。

另請參閱 @ref{19b,,int()} 將十六進位制字串轉換為以 16 為基數的整數。

@cartouche
@quotation 備註 
如果要取得浮點數的十六進位制字串形式，請使用 @ref{1fc9,,float.hex()} method。
@end quotation
@end cartouche
@end deffn

@geindex built-in function; id()
@anchor{library/functions id}@anchor{161a}
@deffn {函式} id (object, /)

回傳物件的 "識別性" 。該值是一個整數，在此物件的生命週期中保證是唯一且恆定的。兩個生命期不重疊的物件可能具有相同的 @ref{161a,,id()} 值。

這是該物件在記憶體中的位址。

引發一個附帶引數 @code{id} 的@ref{1b70,,稽核事件} @code{builtins.id}。
@end deffn

@geindex built-in function; input()
@anchor{library/functions input}@anchor{14d9}
@deffn {函式} input ()

@deffnx {函式} input (prompt, /)

如果有提供 `prompt' 引數，則將其寫入標準輸出，末尾不帶換行符。接下來，該函式從輸入中讀取一行，將其轉換為字串（去除末尾的換行符）並回傳。當讀取到 EOF 時，則引發 @ref{14da,,EOFError}。例如：

@example
>>> s = input('--> ')
--> Monty Python's Flying Circus
>>> s
"Monty Python's Flying Circus"
@end example

如果載入了 @ref{bf,,readline} module，@ref{14d9,,input()} 將使用它來提供複雜的行編輯和歷史記錄功能。

引發一個附帶讀取輸入前的引數 @code{prompt} 的@ref{1b70,,稽核事件} @code{builtins.input}。

引發一個附帶成功讀取結果的@ref{1b70,,稽核事件} @code{builtins.input/result}。
@end deffn

@geindex int (內建類別)
@anchor{library/functions int}@anchor{19b}
@deffn {類別} int (number=0, /)

@deffnx {類別} int (string, /, base=10)

Return an integer object constructed from a number or a string, or return
@code{0} if no arguments are given.

例如：

@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{19d,,__int__()}，則 @code{int(x)} 會回傳 @code{x.__int__()}。如果引數定義了 @ref{19e,,__index__()} 則回傳 @code{x.__index__()}。對於浮點數，則會向零的方向無條件捨去。

如果引數不是數字或如果有給定 `base'，則它必須是個字串、@ref{192,,bytes} 或 @ref{343,,bytearray} 實例，表示基數 (radix) `base' 中的整數。可選地，字串之前可以有 @code{+} 或 @code{-}（中間沒有空格）、可有個前導的零、也可被空格包圍、或在數字間有單一底線。

一個 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{21c0,,程式碼整數字面值 (integer literal in code)} 類似的方式來直譯，最後由前綴決定的結果會是 2、8、10、16 進制中的一個，所以 @code{int('010', 0)} 是非法的，但 @code{int('010')} 和 @code{int('010', 8)} 是有效的。

整數型別定義請參閱@ref{1ea3,,數值型別 --- int、float、complex}。


在 3.4 版的變更: 如果 `base' 不是 @ref{19b,,int} 的實例，但 `base' 物件有 @ref{19e,,base.__index__} method，則會呼叫該 method 來取得此進位制所需的整數。以前的版本使用 @ref{19d,,base.__int__} 而不是 @ref{19e,,base.__index__}。



在 3.6 版的變更: 可以使用底線將程式碼文字中的數字進行分組。



在 3.7 版的變更: 第一個參數為僅限位置參數。



在 3.8 版的變更: 如果未定義 @ref{19d,,__int__()} 則會回退到 @ref{19e,,__index__()}。



在 3.11 版的變更: @ref{19b,,int} 的字串輸入和字串表示法可以被限制，以避免阻斷服務攻擊 (denial of service attack)。在字串 `x' 轉換為 @ref{19b,,int} 時已超出限制，或是在 @ref{19b,,int} 轉換為字串時將會超出限制時，會引發 @ref{2eb,,ValueError}。請參閱@ref{804,,整數字串轉換的長度限制}說明文件。



在 3.14 版的變更: @ref{19b,,int()} 不再委派給 @ref{19c,,__trunc__()} method。

@end deffn

@geindex built-in function; isinstance()
@anchor{library/functions isinstance}@anchor{2ad}
@deffn {函式} isinstance (object, classinfo, /)

如果 `object' 引數是 `classinfo' 引數的實例，或者是（直接、間接或 @ref{13b7,,virtual}）subclass 的實例，則回傳 @code{True}。如果 `object' 不是給定型別的物件，函式始終回傳 @code{False}。如果 `classinfo' 是包含物件型別的 tuple（或多個遞迴 tuple）或一個包含多種型別的 @ref{9be,,聯合型別 (Union Type)}，若 `object' 是其中的任何一個物件的實例則回傳 @code{True}。如果 `classinfo' 既不是型別，也不是型別 tuple 或型別的遞迴 tuple，那麼會引發 @ref{198,,TypeError} 異常。若是先前檢查已經成功，@ref{198,,TypeError} 可能不會再因為不合格的型別而被引發。


在 3.10 版的變更: `classinfo' 可以是一個 @ref{9be,,聯合型別 (Union Type)}。

@end deffn

@geindex built-in function; issubclass()
@anchor{library/functions issubclass}@anchor{9bd}
@deffn {函式} issubclass (class, classinfo, /)

如果 `class' 是 `classinfo' 的 subclass（直接、間接或 @ref{13b7,,virtual}），則回傳 @code{True}。`classinfo' 可以是 class 物件的 tuple（或遞迴地其他類似 tuple）或是一個 @ref{9be,,聯合型別 (Union Type)}，此時若 `class' 是 `classinfo' 中任一元素的 subclass 時則回傳 @code{True}。其他情況，會引發 @ref{198,,TypeError}。


在 3.10 版的變更: `classinfo' 可以是一個 @ref{9be,,聯合型別 (Union Type)}。

@end deffn

@geindex built-in function; iter()
@anchor{library/functions iter}@anchor{9d0}
@deffn {函式} iter (iterable, /)

@deffnx {函式} iter (callable, sentinel, /)

回傳一個 @ref{4c3,,iterator} 物件。根據是否存在第二個引數，第一個引數的意義是非常不同的。如果沒有第二個引數，該單一引數必須是支援 @ref{1428,,iterable} 協定（有 @ref{e64,,__iter__()} method）的集合物件，或必須支援序列協定（有 @ref{582,,__getitem__()} 方法，且數字引數從 @code{0} 開始）。如果它不支援這些協定，會引發 @ref{198,,TypeError}。如果有第二個引數 `sentinel'，那麼第一引數必須是可呼叫的物件，這種情況下生成的 iterator，每次疊代呼叫 @ref{14ce,,__next__()} 時會不帶引數地呼叫 `callable'；如果回傳的結果是 `sentinel' 則引發 @ref{df0,,StopIteration}，否則回傳呼叫結果。

另請參閱 @ref{2481,,疊代器型別}。

@ref{9d0,,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{839}
@deffn {函式} len (object, /)

回傳物件的長度（元素個數）。引數可以是序列（如 string、bytes、tuple、list 或 range）或集合（如 dictionary、set 或 frozen set）。

如果物件長度大於 @ref{13c6,,sys.maxsize}，像是 @ref{b34,,range(2 ** 100)}，則 @code{len} 會引發 @ref{a78,,OverflowError}。
@end deffn

@anchor{library/functions func-list}@anchor{2463}
@deffn {類別} list (iterable=(), /)

除了是函式，@ref{24d,,list} 也是可變序列型別，詳情請參閱 @ref{2482,,List（串列）} 和 @ref{1ef6,,Sequence Types --- list@comma{} tuple@comma{} range}。
@end deffn

@geindex built-in function; locals()
@anchor{library/functions locals}@anchor{469}
@deffn {函式} locals ()

Return a mapping object representing the current local symbol table, with
variable names as the keys, and their currently bound references as the
values.

At module scope, as well as when using @ref{49d,,exec()} or @ref{49e,,eval()} with
a single namespace, this function returns the same namespace as
@ref{1b1e,,globals()}.

At class scope, it returns the namespace that will be passed to the
metaclass constructor.

When using @code{exec()} or @code{eval()} with separate local and global
arguments, it returns the local namespace passed in to the function call.

In all of the above cases, each call to @code{locals()} in a given frame of
execution will return the `same' mapping object. Changes made through
the mapping object returned from @code{locals()} will be visible as assigned,
reassigned, or deleted local variables, and assigning, reassigning, or
deleting local variables will immediately affect the contents of the
returned mapping object.

In an @ref{49c,,optimized scope} (including functions, generators, and
coroutines), each call to @code{locals()} instead returns a fresh dictionary
containing the current bindings of the function's local variables and any
nonlocal cell references. In this case, name binding changes made via the
returned dict are `not' written back to the corresponding local variables
or nonlocal cell references, and assigning, reassigning, or deleting local
variables and nonlocal cell references does `not' affect the contents
of previously returned dictionaries.

Calling @code{locals()} as part of a comprehension in a function, generator, or
coroutine is equivalent to calling it in the containing scope, except that
the comprehension's initialised iteration variables will be included. In
other scopes, it behaves as if the comprehension were running as a nested
function.

Calling @code{locals()} as part of a generator expression is equivalent to
calling it in a nested generator function.


在 3.12 版的變更: The behaviour of @code{locals()} in a comprehension has been updated as
described in 
@geindex Python Enhancement Proposals; PEP 709
PEP 709@footnote{https://peps.python.org/pep-0709/}.



在 3.13 版的變更: As part of 
@geindex Python Enhancement Proposals; PEP 667
PEP 667@footnote{https://peps.python.org/pep-0667/}, the semantics of mutating the mapping objects
returned from this function are now defined. The behavior in
@ref{49c,,optimized scopes} is now as described above.
Aside from being defined, the behaviour in other scopes remains
unchanged from previous versions.

@end deffn

@geindex built-in function; map()
@anchor{library/functions map}@anchor{19f}
@deffn {函式} map (function, iterable, /, *iterables, strict=False)

產生一個將 `function' 應用於 `iterable' 中所有項目並 yield 回傳結果的疊代器。如果傳遞了額外的 `iterables' 引數，則 `function' 必須接受相同個數的引數，且 `function' 會平行地被應用於所有可疊代物件的項目。當有多個可疊代物件時，項目最少的可疊代物件耗盡時疊代器也會結束。如果 `strict' 為 @code{True} 且其中一個可疊代物件在其他可疊代物件之前耗盡，則會拋出 @ref{2eb,,ValueError}。如果函式的輸入已經被編排為引數的元組，請參閱 @ref{12e5,,itertools.starmap()}。


在 3.14 版的變更: 增加了 `strict' 參數。

@end deffn

@geindex built-in function; max()
@anchor{library/functions max}@anchor{1107}
@deffn {函式} max (iterable, /, *, key=None)

@deffnx {函式} max (iterable, /, *, default, key=None)

@deffnx {函式} max (arg1, arg2, /, *args, key=None)

回傳 iterable 中最大的元素，或者回傳兩個以上的引數中最大的。

如果只提供了一個位置引數，它必須是個 @ref{1428,,iterable}，iterable 中最大的元素會被回傳。如果提供了兩個或以上的位置引數，則回傳最大的位置引數。

這個函式有兩個選擇性的僅限關鍵字引數。`key' 引數能指定單一引數所使用的排序函式，如同 @ref{dc3,,list.sort()} 的使用方式。`default' 引數是當 iterable 為空時回傳的物件。如果 iterable 為空，並且沒有提供 `default'，則會引發 @ref{2eb,,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{2464}
@deffn {類別} memoryview (object)

回傳由給定的引數所建立之「memory view（記憶體檢視）」物件。有關詳細資訊，請參閱@ref{2483,,Memory Views}。
@end deffn

@geindex built-in function; min()
@anchor{library/functions min}@anchor{1106}
@deffn {函式} min (iterable, /, *, key=None)

@deffnx {函式} min (iterable, /, *, default, key=None)

@deffnx {函式} min (arg1, arg2, /, *args, key=None)

回傳 iterable 中最小的元素，或者回傳兩個以上的引數中最小的。

如果只提供了一個位置引數，它必須是 @ref{1428,,iterable}，iterable 中最小的元素會被回傳。如果提供了兩個以上的位置引數，則回傳最小的位置引數。

這個函式有兩個選擇性的僅限關鍵字引數。`key' 引數能指定單一引數所使用的排序函式，如同 @ref{dc3,,list.sort()} 的使用方式。`default' 引數是當 iterable 為空時回傳的物件。如果 iterable 為空，並且沒有提供 `default'，則會引發 @ref{2eb,,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{9d1}
@deffn {函式} next (iterator, /)

@deffnx {函式} next (iterator, default, /)

透過呼叫 @ref{4c3,,iterator} 的 @ref{14ce,,__next__()} method 取得下一個元素。如果 iterator 耗盡，則回傳給定的預設值 `default'，如果沒有預設值則引發 @ref{df0,,StopIteration}。
@end deffn

@geindex object (內建類別)
@anchor{library/functions object}@anchor{c75}
@deffn {類別} object

這是所有其他 class 的基礎，它具有所有 Python class 實例的通用 method。當建構函式被呼叫時，它會回傳一個新的沒有特徵 (featureless) 的物件。這個建構函式不接受任何引數。

@cartouche
@quotation 備註 
由於 @ref{c75,,object} 實例`沒有' @ref{776,,__dict__} 屬性，因此無法將任意屬性賦給 @ref{c75,,object} 的實例。
@end quotation
@end cartouche
@end deffn

@geindex built-in function; oct()
@anchor{library/functions oct}@anchor{14cf}
@deffn {函式} oct (integer, /)

將一個整數轉變為一個前綴為 "0o" 的八進位制字串。回傳結果是一個有效的 Python 運算式。如果 `integer' 不是 Python 的 @ref{19b,,int} 物件，那它需要定義 @ref{19e,,__index__()} method 回傳一個整數。舉例來說：

@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{199,,format()} 取得更多資訊。
@end deffn

@geindex file object（檔案物件）;open() 內建函式

@geindex built-in function; open()
@anchor{library/functions open}@anchor{315}
@deffn {函式} open (file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, closefd=True, opener=None)

開啟 `file' 並回傳對應的@ref{13c4,,檔案物件}。如果該檔案不能開啟，則引發 @ref{2c0,,OSError}。關於使用此函式的更多方法，請參閱@ref{1f2d,,讀寫檔案}。

`file' 是一個@ref{59b,,類路徑物件}，是將被開啟之檔案的路徑（絕對路徑或目前工作目錄的相對路徑），或是要被包裝 (wrap) 檔案的整數檔案描述器 (file descriptor)。（如果有給定檔案描述器，它會隨著回傳的 I/O 物件關閉而關閉，除非 `closefd' 被設為 @code{False}。）

`mode' 是一個選擇性字串，用於指定開啟檔案的模式。預設值是 @code{'r'}，這意味著它以文字模式開啟並讀取。其他常見模式有：寫入 @code{'w'}（會捨去已經存在的檔案）、唯一性建立 @code{'x'}、追加寫入 @code{'a'}（在`一些' Unix 系統上，無論目前的檔案指標在什麼位置，`所有' 寫入都會追加到檔案末尾）。在文字模式，如果沒有指定 `encoding'，則根據電腦平臺來決定使用的編碼：呼叫 @ref{328,,locale.getencoding()} 來取得目前的本地編碼。（要讀取和寫入原始 bytes，請使用二進位制模式且不要指定 `encoding'。）可用的模式有：

@geindex file（檔案）;modes（模式）
@anchor{library/functions filemodes}@anchor{2484}

@multitable {xxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

字元

@tab

意義

@item

@code{'r'}

@tab

讀取（預設）

@item

@code{'w'}

@tab

寫入，會先清除檔案內容

@item

@code{'x'}

@tab

唯一性建立，如果文件已存在則會失敗

@item

@code{'a'}

@tab

寫入，如果檔案存在則在其末端附加內容

@item

@code{'b'}

@tab

二進制模式

@item

@code{'t'}

@tab

文字模式（預設）

@item

@code{'+'}

@tab

更新（讀取並寫入）

@end multitable


預設的模式是 @code{'r'}（開啟並讀取文字，同 @code{'rt'}）。@code{'w+'} 和 @code{'w+b'} 模式會開啟並清除檔案。@code{'r+'} 和 @code{'r+b'} 模式會開啟且保留檔案內容。

如@ref{2485,,總覽}中所述，Python 能區分二進制和文字的 I/O。在二進制模式下開啟的檔案（`mode' 引數中含有 @code{'b'}）會將其內容以 @ref{192,,bytes} 物件回傳，而不進行任何解碼。在文字模式（預設情況，或當 `mode' 引數中含有 @code{'t'}），檔案的內容會以 @ref{169,,str} 回傳，其位元組已經先被解碼，使用的是取決於平台的編碼系統或是給定的 `encoding'。

@cartouche
@quotation 備註 
Python 不會使用底層作業系統對於文字檔案的操作概念；所有的處理都是由 Python 獨自完成的，因此能獨立於不同平台。
@end quotation
@end cartouche

`buffering' 是一個選擇性的整數，用於設定緩衝策略。傳入 0 表示關閉緩衝（僅在二進制模式下被允許），1 表示行緩衝（line buffering，僅在文字模式下可用），而 >1 的整數是指示一個大小固定的區塊緩衝區 (chunk buffer)，其位元組的數量。請注意，此類指定緩衝區大小的方式適用於二進制緩衝 I/O，但是 @code{TextIOWrapper}（以 @code{mode='r+'} 開啟的檔案）會有另一種緩衝方式。若要在 @code{TextIOWrapper} 中停用緩衝，可考慮使用 @ref{d38,,io.TextIOWrapper.reconfigure()} 的 @code{write_through} 旗標。若未給定 `buffering' 引數，則預設的緩衝策略會運作如下：


@itemize *

@item 
二進位檔案會以固定大小的區塊進行緩衝；緩衝區的大小為 @code{max(min(blocksize, 8 MiB), DEFAULT_BUFFER_SIZE)}，當裝置區塊大小可用時。在大多數系統上，緩衝區的長度通常為 128 KB。

@item 
「互動式」文字檔（@ref{1f30,,isatty()} 回傳 @code{True} 的檔案）會使用列緩衝。其他文字檔則使用上述的二進制檔案緩衝策略。
@end itemize

`encoding' 是用於解碼或編碼檔案的編碼系統之名稱。它只應該在文字模式下使用。預設的編碼系統會取決於平台（根據 @ref{328,,locale.getencoding()} 回傳的內容），但 Python 支援的任何 @ref{2486,,text encoding}（文字編碼）都是可以使用的。關於支援的編碼系統清單，請參閱 @ref{1c,,codecs} module。

`errors' 是一個選擇性的字串，用於指定要如何處理編碼和解碼的錯誤——它不能在二進制模式下使用。有許多不同的標準錯誤處理程式（error handler，在@ref{1a9e,,Error Handlers}有列出清單），不過任何已註冊到 @ref{168f,,codecs.register_error()} 的錯誤處理程式名稱也都是有效的。標準的名稱包括：


@itemize *

@item 
@code{'strict'} 如果發生編碼錯誤，則引發 @ref{2eb,,ValueError} 例外。預設值 @code{None} 也有相同的效果。

@item 
@code{'ignore'} 忽略錯誤。請注意，忽略編碼錯誤可能導致資料遺失。

@item 
@code{'replace'} 會在格式不正確的資料位置插入一個替換標誌（像是 @code{'?'}）。

@item 
@code{'surrogateescape'} 會將任何不正確的位元組表示為低位代理碼元 (low surrogate code unit)，範圍從 U+DC80 到 U+DCFF。在寫入資料時，這些代理碼元將會被還原回 @code{surrogateescape} 錯誤處理程式當時所處理的那些相同位元組。這對於處理未知編碼方式的檔案會很好用。

@item 
@code{'xmlcharrefreplace'} 僅在寫入檔案時可支援。編碼系統不支援的字元會被替換為適當的 XML 字元參考 (character reference) @code{&#nnn;}。

@item 
@code{'backslashreplace'} 會用 Python 的反斜線跳脫序列 (backslashed escape sequence) 替換格式不正確的資料。

@item 
@code{'namereplace'}（也僅在寫入時支援）會將不支援的字元替換為 @code{\N@{...@}} 跳脫序列。
@end itemize

@geindex universal newlines;open() 內建函式
@anchor{library/functions open-newline-parameter}@anchor{940}
`newline' 會決定如何剖析資料串流 (stream) 中的換行字元。它可以是 @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{2487,,os.linesep}。如果 `newline' 是 @code{'@w{'}} 或 @code{'\n'}，則不做任何轉換。如果 `newline' 是任何其他有效的值，則寫入的任何 @code{'\n'} 字元都將轉換為給定的字串。
@end itemize

如果 `closefd' 是 @code{False}，且給定的 `file' 引數是一個檔案描述器而不是檔名，則當檔案關閉時，底層的檔案描述器會保持開啟狀態。如果有給定一個檔名，則 `closefd' 必須是 @code{True}（預設值）；否則將引發錯誤。

透過以 `opener' 傳遞一個可呼叫物件，就可以自訂開啟函式。然後透過以引數 (`file', `flags') 呼叫 `opener'，就能取得檔案物件的底層檔案描述器。`opener' 必須回傳一個開啟的檔案描述器（將 @ref{f8d,,os.open} 作為 `opener' 傳入，在功能上的結果會相當於傳入 @code{None}）。

新建立的檔案是@ref{10f7,,不可繼承的}。

下面的範例使用 @ref{f8d,,os.open()} 函式回傳值當作 @ref{12eb,,dir_fd} 的參數，從給定的目錄中用相對路徑開啟檔案：

@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{315,,open()} 函式回傳的 @ref{13c4,,file object} 型別取決於模式。當 @ref{315,,open()} 是在文字模式中開啟檔案時（@code{'w'}、@code{'r'}、@code{'wt'}、@code{'rt'} 等），它會回傳 @ref{89d,,io.TextIOBase} 的一個 subclass（具體來說，就是 @ref{9b7,,io.TextIOWrapper}）。使用有緩衝的二進制模式開啟檔案時，回傳的 class 則會是 @ref{89c,,io.BufferedIOBase} 的 subclass。確切的 class 各不相同：在讀取的二進制模式，它會回傳 @ref{140f,,io.BufferedReader}；在寫入和附加的二進制模式，它會回傳 @ref{15a9,,io.BufferedWriter}，而在讀／寫模式，它會回傳 @ref{15aa,,io.BufferedRandom}。當緩衝被停用時，會回傳原始資料串流 @ref{1510,,io.FileIO}，它是 @ref{12d1,,io.RawIOBase} 的一個 subclass。

@geindex line-buffered I/O（行緩衝 I/O）
@geindex unbuffered I/O（非緩衝 I/O）
@geindex buffer size@comma{} I/O（緩衝區大小、I/O）
@geindex I/O control（I/O 控制）;buffering（緩衝）
@geindex 二進制模式
@geindex text mode（文字模式）
@geindex module（模組）;sys

另請參閱檔案操作模組，例如 @ref{5f,,fileinput}、@ref{83,,io}（定義了 @ref{315,,open()} 的 module ）、@ref{a5,,os}、@ref{a6,,os.path}、@ref{e6,,tempfile} 以及 @ref{ca,,shutil}。

引發一個附帶引數 @code{path}、@code{mode}、@code{flags} 的@ref{1b70,,稽核事件} @code{open}。

@code{mode} 和 @code{flags} 引數可能會被原始的呼叫所修改或推論 (infer)。


在 3.3 版的變更: 


@itemize *

@item 
增加了 `opener' 參數。

@item 
增加了 @code{'x'} 模式。

@item 
過去引發的 @ref{124e,,IOError}，現在是 @ref{2c0,,OSError} 的別名。

@item 
如果檔案已存在但使用了唯一性建立模式 (@code{'x'})，現在會引發 @ref{121b,,FileExistsError}。
@end itemize



在 3.4 版的變更: 


@itemize *

@item 
檔案在此版本開始是不可繼承的。
@end itemize



在 3.5 版的變更: 


@itemize *

@item 
如果系統呼叫被中斷，但訊號處理程式沒有引發例外，此函式現在會重試系統呼叫，而不是引發 @ref{f83,,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{e46,,os.PathLike} 物件的支援。

@item 
在 Windows 上，開啟一個控制臺緩衝區可能會回傳 @ref{12d1,,io.RawIOBase} 的 subclass，而不是 @ref{1510,,io.FileIO}。
@end itemize



在 3.11 版的變更: @code{'U'} 模式被移除。

@end deffn

@geindex built-in function; ord()
@anchor{library/functions ord}@anchor{21ef}
@deffn {函式} ord (character, /)

Return the ordinal value of a character.

如果引數是單字元字串，則回傳該字元的 Unicode 編碼位置。例如 @code{ord('a')} 回傳整數 @code{97}、@code{ord('€')}（歐元符號）回傳 @code{8364}。這是 @ref{193e,,chr()} 的逆函式。

If the argument is a @ref{192,,bytes} or @ref{343,,bytearray} object of
length 1, return its single byte value.
For example, @code{ord(b'a')} returns the integer @code{97}.
@end deffn

@geindex built-in function; pow()
@anchor{library/functions pow}@anchor{1a4}
@deffn {函式} pow (base, exp, mod=None)

回傳 `base' 的 `exp' 次方；如果 `mod' 存在，則回傳 `base' 的 `exp' 次方對 `mod' 取餘數（比直接呼叫 @code{pow(base, exp) % mod} 計算更高效）。兩個引數形式的 @code{pow(exp, exp)} 等價於次方運算子：@code{base**exp}。

當引數為內建數值型別且運算元型別為混合型別時，會套用二元算術運算子的強制轉型 (coercion) 規則。對於 @ref{19b,,int} 運算元，運算結果會（在強制轉型後）與運算元的型別相同，除非第二個引數是負數；在這種情況下，所有的引數都會被轉換為浮點數並得到浮點數的結果。例如，@code{pow(10, 2)} 會回傳 @code{100}，但 @code{pow(10, -2)} 會回傳 @code{0.01}。如果底數 (base) 是型別為 @ref{19b,,int} 或 @ref{196,,float} 的負數且指數 (exponent) 為非整數，則會傳回複數結果。例如 @code{pow(-9, 0.5)} 會回傳一個接近 @code{3j} 的值。然而，如果底數 (base) 是型別為 @ref{19b,,int} 或 @ref{196,,float} 的負數且指數為整數，則會傳回浮點數結果。例如 @code{pow(-9, 2.0)} 會回傳 @code{81.0}。

對於 @ref{19b,,int} 運算元 `base' 和 `exp'，如果有給定 `mod'，則 `mod' 也必須是整數型別，且 `mod' 必須不為零。如果有給定 `mod' 且 `exp' 為負，則 `base' 必須與 `mod' 互質。在這種情況下，會回傳 @code{pow(inv_base, -exp, mod)}，其中 `inv_base' 是 `base' 對 `mod' 的模倒數 (inverse modulo)。

以下是一個計算 @code{38} 對 @code{97} 取模倒數的範例：

@example
>>> pow(38, -1, mod=97)
23
>>> 23 * 38 % 97 == 1
True
@end example


在 3.8 版的變更: 對於 @ref{19b,,int} 運算元，現在 @code{pow} 的三引數形式允許第二個引數為負數，也容許模倒數的計算。



在 3.8 版的變更: 允許關鍵字引數。在此之前只支援位置引數。

@end deffn

@geindex built-in function; print()
@anchor{library/functions print}@anchor{1170}
@deffn {函式} print (*objects, sep=' ', end='\n', file=None, flush=False)

將 `objects' 列印到文字資料串流 `file'，用 `sep' 分隔並以 `end' 結尾。如果有給定 `sep'、`end'、`file' 和 `flush'，那麼它們必須是關鍵字引數的形式。

所有的非關鍵字引數都會像是 @ref{169,,str()} 操作一樣地被轉換為字串，並寫入資料串流，彼此以 `sep' 分隔，並以 `end' 結尾。`sep' 和 `end' 都必須是字串；它們也可以是 @code{None}，這表示使用預設值。如果沒有給定 `objects'，@ref{1170,,print()} 就只會寫入 `end'。

`file' 引數必須是一個有 @code{write(string)} method 的物件；如果沒有給定或被設為 @code{None}，則將使用 @ref{cc4,,sys.stdout}。因為要列印的引數會被轉換為文字字串，所以 @ref{1170,,print()} 不能用於二進位模式的檔案物件。對於此類物件，請改用 @code{file.write(...)}。

輸出緩衝通常會由 `file' 決定。但是如果 `flush' 為 true，則資料串流會被強制清除。


在 3.3 版的變更: 增加了 `flush' 關鍵字引數。

@end deffn

@geindex property (內建類別)
@anchor{library/functions property}@anchor{4ae}
@deffn {類別} property (fget=None, fset=None, fdel=None, doc=None)

回傳 property 屬性。

`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' 是 `C' 的一個實例，則 @code{c.x} 將會叫用取得器 (getter)，@code{c.x = value} 會呼叫設定器 (setter)，而 @code{del c.x} 會叫用刪除器 (deleter)。

如果有給定 `doc'，它將會是 property 屬性的說明字串。否則，property 會複製 `fget' 的說明字串（如果它存在的話）。這樣一來，就能夠輕鬆地使用 @ref{4ae,,property()} 作為@ref{932,,裝飾器}來建立唯讀屬性：

@example
class Parrot:
    def __init__(self):
        self._voltage = 100000

    @@property
    def voltage(self):
        """Get the current voltage."""
        return self._voltage
@end example

The @code{@@property} decorator turns the @code{voltage()} method into a "getter"
for a read-only attribute with the same name, and it sets the docstring for
`voltage' to "Get the current voltage."

@geindex built-in function; property.getter()
@anchor{library/functions property getter}@anchor{1928}
@deffn {函式} @@getter
@end deffn

@geindex built-in function; property.setter()
@anchor{library/functions property setter}@anchor{1929}
@deffn {函式} @@setter
@end deffn

@geindex built-in function; property.deleter()
@anchor{library/functions property deleter}@anchor{192a}
@deffn {函式} @@deleter

A property object has @code{getter}, @code{setter},
and @code{deleter} methods usable as decorators that create a
copy of the property with the corresponding accessor function set to the
decorated function.  This is best explained with an example:

@example
class C:
    def __init__(self):
        self._x = None

    @@property
    def x(self):
        """I'm the 'x' property."""
        return self._x

    @@x.setter
    def x(self, value):
        self._x = value

    @@x.deleter
    def x(self):
        del self._x
@end example

This code is exactly equivalent to the first example.  Be sure to give the
additional functions the same name as the original property (@code{x} in this
case.)

The returned property object also has the attributes @code{fget}, @code{fset}, and
@code{fdel} corresponding to the constructor arguments.
@end deffn


在 3.5 版的變更: The docstrings of property objects are now writeable.


@geindex __name__ (property 的屬性)
@anchor{library/functions property __name__}@anchor{4ad}
@deffn {屬性} __name__

Attribute holding the name of the property. The name of the property
can be changed at runtime.


在 3.13 版被加入.

@end deffn
@end deffn

@anchor{library/functions func-range}@anchor{2465}
@deffn {類別} range (stop, /)

@deffnx {類別} range (start, stop, step=1, /)

Rather than being a function, @ref{b34,,range} is actually an immutable
sequence type, as documented in @ref{2488,,Ranges} and @ref{1ef6,,Sequence Types --- list@comma{} tuple@comma{} range}.
@end deffn

@geindex built-in function; repr()
@anchor{library/functions repr}@anchor{1c1}
@deffn {函式} repr (object, /)

Return a string containing a printable representation of an object.  For many
types, this function makes an attempt to return a string that would yield an
object with the same value when passed to @ref{49e,,eval()}; otherwise, the
representation is a string enclosed in angle brackets that contains the name
of the type of the object together with additional information often
including the name and address of the object.  A class can control what this
function returns for its instances
by defining a @ref{828,,__repr__()} method.
If @ref{1713,,sys.displayhook()} is not accessible, this function will raise
@ref{244,,RuntimeError}.

This class has a custom representation that can be evaluated:

@example
class Person:
   def __init__(self, name, age):
      self.name = name
      self.age = age

   def __repr__(self):
      return f"Person('@{self.name@}', @{self.age@})"
@end example
@end deffn

@geindex built-in function; reversed()
@anchor{library/functions reversed}@anchor{a5e}
@deffn {函式} reversed (object, /)

Return a reverse @ref{4c3,,iterator}.  The argument must be an object which has
a @ref{e81,,__reversed__()} method or supports the sequence protocol (the
@ref{2260,,__len__()} method and the @ref{582,,__getitem__()} method
with integer arguments starting at @code{0}).
@end deffn

@geindex built-in function; round()
@anchor{library/functions round}@anchor{14db}
@deffn {函式} round (number, ndigits=None)

Return `number' rounded to `ndigits' precision after the decimal
point.  If `ndigits' is omitted or is @code{None}, it returns the
nearest integer to its input.

For the built-in types supporting @ref{14db,,round()}, values are rounded to the
closest multiple of 10 to the power minus `ndigits'; if two multiples are
equally close, rounding is done toward the even choice (so, for example,
both @code{round(0.5)} and @code{round(-0.5)} are @code{0}, and @code{round(1.5)} is
@code{2}).  Any integer value is valid for `ndigits' (positive, zero, or
negative).  The return value is an integer if `ndigits' is omitted or
@code{None}.
Otherwise, the return value has the same type as `number'.

For a general Python object @code{number}, @code{round} delegates to
@code{number.__round__}.

@cartouche
@quotation 備註 
The behavior of @ref{14db,,round()} for floats can be surprising: for example,
@code{round(2.675, 2)} gives @code{2.67} instead of the expected @code{2.68}.
This is not a bug: it's a result of the fact that most decimal fractions
can't be represented exactly as a float.  See @ref{1fc7,,浮點數運算：問題與限制} for
more information.
@end quotation
@end cartouche
@end deffn

@anchor{library/functions func-set}@anchor{2466}
@deffn {類別} set (iterable=(), /)

Return a new @ref{184,,set} object, optionally with elements taken from
`iterable'.  @code{set} is a built-in class.  See @ref{184,,set} and
@ref{247f,,Set Types --- set@comma{} frozenset} for documentation about this class.

For other containers see the built-in @ref{7eb,,frozenset}, @ref{24d,,list},
@ref{60c,,tuple}, and @ref{183,,dict} classes, as well as the @ref{1e,,collections}
module.
@end deffn

@geindex built-in function; setattr()
@anchor{library/functions setattr}@anchor{2467}
@deffn {函式} setattr (object, name, value, /)

This is the counterpart of @ref{dc5,,getattr()}.  The arguments are an object, a
string, and an arbitrary value.  The string may name an existing attribute or a
new attribute.  The function assigns the value to the attribute, provided the
object allows it.  For example, @code{setattr(x, 'foobar', 123)} is equivalent to
@code{x.foobar = 123}.

`name' need not be a Python identifier as defined in @ref{2164,,Names (identifiers and keywords)}
unless the object chooses to enforce that, for example in a custom
@ref{dc6,,__getattribute__()} or via @ref{16df,,__slots__}.
An attribute whose name is not an identifier will not be accessible using
the dot notation, but is accessible through @ref{dc5,,getattr()} etc..

@cartouche
@quotation 備註 
Since @ref{1f6a,,private name mangling} happens at
compilation time, one must manually mangle a private attribute's
(attributes with two leading underscores) name in order to set it with
@ref{2467,,setattr()}.
@end quotation
@end cartouche
@end deffn

@geindex slice (內建類別)
@anchor{library/functions slice}@anchor{68d}
@deffn {類別} slice (stop, /)

@deffnx {類別} slice (start, stop, step=None, /)

Return a @ref{2489,,slice} object representing the set of indices specified by
@code{range(start, stop, step)}.  The `start' and `step' arguments default to
@code{None}.

Slice objects have read-only data attributes @code{start},
@code{stop}, and @code{step} which merely return the argument
values (or their default).  They have no other explicit functionality;
however, they are used by NumPy and other third-party packages.

@geindex start (slice 的屬性)
@anchor{library/functions slice start}@anchor{2256}
@deffn {屬性} start
@end deffn

@geindex stop (slice 的屬性)
@anchor{library/functions slice stop}@anchor{2257}
@deffn {屬性} stop
@end deffn

@geindex step (slice 的屬性)
@anchor{library/functions slice step}@anchor{2258}
@deffn {屬性} step
@end deffn

Slice objects are also generated when extended indexing syntax is used.  For
example: @code{a[start:stop:step]} or @code{a[start:stop, i]}.  See
@ref{d3b,,itertools.islice()} for an alternate version that returns an
@ref{4c3,,iterator}.


在 3.12 版的變更: Slice objects are now @ref{81d,,hashable} (provided @ref{2256,,start},
@ref{2257,,stop}, and @ref{2258,,step} are hashable).

@end deffn

@geindex built-in function; sorted()
@anchor{library/functions sorted}@anchor{dc2}
@deffn {函式} sorted (iterable, /, *, key=None, reverse=False)

Return a new sorted list from the items in `iterable'.

有兩個選擇性引數，只能使用關鍵字引數來指定。

`key' 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}).  The
default value is @code{None} (compare the elements directly).

`reverse' is a boolean value.  If set to @code{True}, then the list elements are
sorted as if each comparison were reversed.

Use @ref{13db,,functools.cmp_to_key()} to convert an old-style `cmp' function to a
`key' function.

The built-in @ref{dc2,,sorted()} function is guaranteed to be stable. A sort is
stable if it guarantees not to change the relative order of elements that
compare equal --- this is helpful for sorting in multiple passes (for
example, sort by department, then by salary grade).

The sort algorithm uses only @code{<} comparisons between items.  While
defining an @ref{14a1,,__lt__()} method will suffice for sorting,
@geindex Python Enhancement Proposals; PEP 8
PEP 8@footnote{https://peps.python.org/pep-0008/} recommends that all six @ref{2378,,rich comparisons} be implemented.  This will help avoid bugs when using
the same data with other ordering tools such as @ref{1107,,max()} that rely
on a different underlying method.  Implementing all six comparisons
also helps avoid confusion for mixed type comparisons which can call
reflected the @ref{150c,,__gt__()} method.

For sorting examples and a brief sorting tutorial, see @ref{248a,,排序技法}.
@end deffn

@geindex built-in function; staticmethod()
@anchor{library/functions staticmethod}@anchor{451}
@deffn {函式} @@staticmethod

Transform a method into a static method.

A static method does not receive an implicit first argument. To declare a static
method, use this idiom:

@example
class C:
    @@staticmethod
    def f(arg1, arg2, argN): ...
@end example

@code{@@staticmethod} 語法是一個函式 @ref{932,,decorator} - 參見 @ref{1ee1,,函式定義} 中的詳細介紹。

A static method can be called either on the class (such as @code{C.f()}) or on
an instance (such as @code{C().f()}).
Moreover, the static method @ref{17fc,,descriptor} is also callable, so it can
be used in the class definition (such as @code{f()}).

Static methods in Python are similar to those found in Java or C++. Also, see
@ref{489,,classmethod()} for a variant that is useful for creating alternate class
constructors.

Like all decorators, it is also possible to call @code{staticmethod} as
a regular function and do something with its result.  This is needed
in some cases where you need a reference to a function from a class
body and you want to avoid the automatic transformation to instance
method.  For these cases, use this idiom:

@example
def regular_function():
    ...

class C:
    method = staticmethod(regular_function)
@end example

關於 static method 的更多資訊，請參考 @ref{21e4,,標準型別階層}。


在 3.10 版的變更: Static method 現在繼承了 method 屬性（@ref{21fc,,__module__}、@ref{14d5,,__name__}、@ref{21fb,,__qualname__}、@ref{13da,,__doc__} 和 @ref{13d9,,__annotations__}），並擁有一個新的 @code{__wrapped__} 屬性，且為如一般函式的可呼叫物件。

@end deffn

@geindex string（字串）;str() （內建函式）

@anchor{library/functions func-str}@anchor{2468}
@deffn {類別} str (*, encoding='utf-8', errors='strict')

@deffnx {類別} str (object)

@deffnx {類別} str (object, encoding, errors='strict')

@deffnx {類別} str (object, *, errors)

Return a @ref{169,,str} version of `object'.  See @ref{169,,str()} for details.

@code{str} is the built-in string @ref{1be7,,class}.  For general information
about strings, see @ref{1ea8,,Text Sequence Type --- str}.
@end deffn

@geindex built-in function; sum()
@anchor{library/functions sum}@anchor{68e}
@deffn {函式} sum (iterable, /, start=0)

Sums `start' and the items of an `iterable' from left to right and returns the
total.  The `iterable''s items are normally numbers, and the start value is not
allowed to be a string.

For some use cases, there are good alternatives to @ref{68e,,sum()}.
The preferred, fast way to concatenate a sequence of strings is by calling
@code{'@w{'}.join(sequence)}.  To add floating-point values with extended precision,
see @ref{15cb,,math.fsum()}.  To concatenate a series of iterables, consider using
@ref{248b,,itertools.chain()}.


在 3.8 版的變更: `start' 參數可被指定為關鍵字引數。



在 3.12 版的變更: Summation of floats switched to an algorithm
that gives higher accuracy and better commutativity on most builds.



在 3.14 版的變更: Added specialization for summation of complexes,
using same algorithm as for summation of floats.

@end deffn

@geindex super (內建類別)
@anchor{library/functions super}@anchor{1a6}
@deffn {類別} super

@deffnx {類別} super (type, object_or_type=None, /)

Return a proxy object that delegates method calls to a parent or sibling
class of `type'.  This is useful for accessing inherited methods that have
been overridden in a class.

The `object_or_type' determines the @ref{248c,,method resolution order}
to be searched.  The search starts from the class right after the
`type'.

For example, if @ref{2229,,__mro__} of `object_or_type' is
@code{D -> B -> C -> A -> object} and the value of `type' is @code{B},
then @ref{1a6,,super()} searches @code{C -> A -> object}.

The @ref{2229,,__mro__} attribute of the class corresponding to
`object_or_type' lists the method resolution search order used by both
@ref{dc5,,getattr()} and @ref{1a6,,super()}.  The attribute is dynamic and can change
whenever the inheritance hierarchy is updated.

If the second argument is omitted, the super object returned is unbound.  If
the second argument is an object, @code{isinstance(obj, type)} must be true.  If
the second argument is a type, @code{issubclass(type2, type)} must be true (this
is useful for classmethods).

When called directly within an ordinary method of a class, both arguments may
be omitted ("zero-argument @code{super()}"). In this case, `type' will be the
enclosing class, and `obj' will be the first argument of the immediately
enclosing function (typically @code{self}). (This means that zero-argument
@code{super()} will not work as expected within nested functions, including
generator expressions, which implicitly create nested functions.)

There are two typical use cases for `super'.  In a class hierarchy with
single inheritance, `super' can be used to refer to parent classes without
naming them explicitly, thus making the code more maintainable.  This use
closely parallels the use of `super' in other programming languages.

The second use case is to support cooperative multiple inheritance in a
dynamic execution environment.  This use case is unique to Python and is
not found in statically compiled languages or languages that only support
single inheritance.  This makes it possible to implement "diamond diagrams"
where multiple base classes implement the same method.  Good design dictates
that such implementations have the same calling signature in every case (because the
order of calls is determined at runtime, because that order adapts
to changes in the class hierarchy, and because that order can include
sibling classes that are unknown prior to runtime).

For both use cases, a typical superclass call looks like this:

@example
class C(B):
    def method(self, arg):
        super().method(arg)    # This does the same thing as:
                               # super(C, self).method(arg)
@end example

In addition to method lookups, @ref{1a6,,super()} also works for attribute
lookups.  One possible use case for this is calling @ref{17fc,,descriptors}
in a parent or sibling class.

Note that @ref{1a6,,super()} is implemented as part of the binding process for
explicit dotted attribute lookups such as @code{super().__getitem__(name)}.
It does so by implementing its own @ref{dc6,,__getattribute__()} method
for searching
classes in a predictable order that supports cooperative multiple inheritance.
Accordingly, @ref{1a6,,super()} is undefined for implicit lookups using statements or
operators such as @code{super()[name]}.

Also note that, aside from the zero argument form, @ref{1a6,,super()} is not
limited to use inside methods.  The two argument form specifies the
arguments exactly and makes the appropriate references.  The zero
argument form only works inside a class definition, as the compiler fills
in the necessary details to correctly retrieve the class being defined,
as well as accessing the current instance for ordinary methods.

For practical suggestions on how to design cooperative classes using
@ref{1a6,,super()}, see guide to using super()@footnote{https://rhettinger.wordpress.com/2011/05/26/super-considered-super/}.


在 3.14 版的變更: @ref{1a6,,super} objects are now @ref{ab,,pickleable} and
 @ref{29,,copyable}.

@end deffn

@anchor{library/functions func-tuple}@anchor{2469}
@deffn {類別} tuple (iterable=(), /)

Rather than being a function, @ref{60c,,tuple} is actually an immutable
sequence type, as documented in @ref{23f2,,Tuples} and @ref{1ef6,,Sequence Types --- list@comma{} tuple@comma{} range}.
@end deffn

@geindex type (內建類別)
@anchor{library/functions type}@anchor{f3f}
@deffn {類別} type (object, /)

@deffnx {類別} type (name, bases, dict, /, **kwargs)

@geindex object（物件）;type（型別）

With one argument, return the type of an `object'.  The return value is a
type object and generally the same object as returned by
@ref{16a1,,object.__class__}.

The @ref{2ad,,isinstance()} built-in function is recommended for testing the type
of an object, because it takes subclasses into account.

With three arguments, return a new type object.  This is essentially a
dynamic form of the @ref{14d8,,class} statement. The `name' string is
the class name and becomes the @ref{169f,,__name__} attribute.
The `bases' tuple contains the base classes and becomes the
@ref{16a0,,__bases__} attribute; if empty, @ref{c75,,object}, the
ultimate base of all classes, is added.  The `dict' dictionary contains
attribute and method definitions for the class body; it may be copied
or wrapped before becoming the @ref{e52,,__dict__} attribute.
The following two statements create identical @code{type} objects:

@example
>>> class X:
...     a = 1
...
>>> X = type('X', (), dict(a=1))
@end example

See also:


@itemize *

@item 
@ref{2222,,Documentation on attributes and methods on classes}.

@item 
@ref{248d,,Type Objects}
@end itemize

Keyword arguments provided to the three argument form are passed to the
appropriate metaclass machinery (usually @ref{83c,,__init_subclass__()})
in the same way that keywords in a class
definition (besides `metaclass') would.

另請參閱 @ref{e40,,Customizing class creation}。


在 3.6 版的變更: Subclasses of @code{type} which don't override @code{type.__new__} may no
longer use the one-argument form to get the type of an object.

@end deffn

@geindex built-in function; vars()
@anchor{library/functions vars}@anchor{1ceb}
@deffn {函式} vars ()

@deffnx {函式} vars (object, /)

Return the @ref{776,,__dict__} attribute for a module, class, instance,
or any other object with a @code{__dict__} attribute.

Objects such as modules and instances have an updateable @ref{776,,__dict__}
attribute; however, other objects may have write restrictions on their
@code{__dict__} attributes (for example, classes use a
@ref{691,,types.MappingProxyType} to prevent direct dictionary updates).

Without an argument, @ref{1ceb,,vars()} acts like @ref{469,,locals()}.

A @ref{198,,TypeError} exception is raised if an object is specified but
it doesn't have a @ref{776,,__dict__} attribute (for example, if
its class defines the @ref{16df,,__slots__} attribute).


在 3.13 版的變更: The result of calling this function without an argument has been
updated as described for the @ref{469,,locals()} builtin.

@end deffn

@geindex built-in function; zip()
@anchor{library/functions zip}@anchor{1a0}
@deffn {函式} zip (*iterables, strict=False)

Iterate over several iterables in parallel, producing tuples with an item
from each one.

例如：

@example
>>> for item in zip([1, 2, 3], ['sugar', 'spice', 'everything nice']):
...     print(item)
...
(1, 'sugar')
(2, 'spice')
(3, 'everything nice')
@end example

More formally: @ref{1a0,,zip()} returns an iterator of tuples, where the `i'-th
tuple contains the `i'-th element from each of the argument iterables.

Another way to think of @ref{1a0,,zip()} is that it turns rows into columns, and
columns into rows.  This is similar to transposing a matrix@footnote{https://en.wikipedia.org/wiki/Transpose}.

@ref{1a0,,zip()} is lazy: The elements won't be processed until the iterable is
iterated on, e.g. by a @code{for} loop or by wrapping in a
@ref{24d,,list}.

One thing to consider is that the iterables passed to @ref{1a0,,zip()} could have
different lengths; sometimes by design, and sometimes because of a bug in
the code that prepared these iterables.  Python offers three different
approaches to dealing with this issue:


@itemize *

@item 
By default, @ref{1a0,,zip()} stops when the shortest iterable is exhausted.
It will ignore the remaining items in the longer iterables, cutting off
the result to the length of the shortest iterable:

@example
>>> list(zip(range(3), ['fee', 'fi', 'fo', 'fum']))
[(0, 'fee'), (1, 'fi'), (2, 'fo')]
@end example

@item 
@ref{1a0,,zip()} is often used in cases where the iterables are assumed to be
of equal length.  In such cases, it's recommended to use the @code{strict=True}
option. Its output is the same as regular @ref{1a0,,zip()}:

@example
>>> list(zip(('a', 'b', 'c'), (1, 2, 3), strict=True))
[('a', 1), ('b', 2), ('c', 3)]
@end example

Unlike the default behavior, it raises a @ref{2eb,,ValueError} if one iterable
is exhausted before the others:

@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

Without the @code{strict=True} argument, any bug that results in iterables of
different lengths will be silenced, possibly manifesting as a hard-to-find
bug in another part of the program.

@item 
Shorter iterables can be padded with a constant value to make all the
iterables have the same length.  This is done by
@ref{149f,,itertools.zip_longest()}.
@end itemize

Edge cases: With a single iterable argument, @ref{1a0,,zip()} returns an
iterator of 1-tuples.  With no arguments, it returns an empty iterator.

Tips and tricks:


@itemize *

@item 
The left-to-right evaluation order of the iterables is guaranteed. This
makes possible an idiom for clustering a data series into n-length groups
using @code{zip(*[iter(s)]*n, strict=True)}.  This repeats the `same' iterator
@code{n} times so that each output tuple has the result of @code{n} calls to the
iterator. This has the effect of dividing the input into n-length chunks.

@item 
@ref{1a0,,zip()} in conjunction with the @code{*} operator can be used to unzip a
list:

@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{ac8}
@deffn {函式} __import__ (name, globals=None, locals=None, fromlist=(), level=0)

@geindex statement（陳述式）;import（引入）
@geindex module（模組）;builtins（內建）

@cartouche
@quotation 備註 
This is an advanced function that is not needed in everyday Python
programming, unlike @ref{735,,importlib.import_module()}.
@end quotation
@end cartouche

This function is invoked by the @ref{7f1,,import} statement.  It can be
replaced (by importing the @ref{13,,builtins} module and assigning to
@code{builtins.__import__}) in order to change semantics of the
@code{import} statement, but doing so is `strongly' discouraged as it
is usually simpler to use import hooks (see 
@geindex Python Enhancement Proposals; PEP 302
PEP 302@footnote{https://peps.python.org/pep-0302/}) to attain the same
goals and does not cause issues with code which assumes the default import
implementation is in use.  Direct use of @ref{ac8,,__import__()} is also
discouraged in favor of @ref{735,,importlib.import_module()}.

The function imports the module `name', potentially using the given `globals'
and `locals' to determine how to interpret the name in a package context.
The `fromlist' gives the names of objects or submodules that should be
imported from the module given by `name'.  The standard implementation does
not use its `locals' argument at all and uses its `globals' only to
determine the package context of the @ref{7f1,,import} statement.

`level' specifies whether to use absolute or relative imports. @code{0} (the
default) means only perform absolute imports.  Positive values for
`level' indicate the number of parent directories to search relative to the
directory of the module calling @ref{ac8,,__import__()} (see 
@geindex Python Enhancement Proposals; PEP 328
PEP 328@footnote{https://peps.python.org/pep-0328/} for the
details).

When the `name' variable is of the form @code{package.module}, normally, the
top-level package (the name up till the first dot) is returned, `not' the
module named by `name'.  However, when a non-empty `fromlist' argument is
given, the module named by `name' is returned.

For example, the statement @code{import spam} results in bytecode resembling the
following code:

@example
spam = __import__('spam', globals(), locals(), [], 0)
@end example

The statement @code{import spam.ham} results in this call:

@example
spam = __import__('spam.ham', globals(), locals(), [], 0)
@end example

Note how @ref{ac8,,__import__()} returns the toplevel module here because this is
the object that is bound to a name by the @ref{7f1,,import} statement.

On the other hand, the statement @code{from spam.ham import eggs, sausage as
saus} results in

@example
_temp = __import__('spam.ham', globals(), locals(), ['eggs', 'sausage'], 0)
eggs = _temp.eggs
saus = _temp.sausage
@end example

Here, the @code{spam.ham} module is returned from @ref{ac8,,__import__()}.  From this
object, the names to import are retrieved and assigned to their respective
names.

If you simply want to import a module (potentially within a package) by name,
use @ref{735,,importlib.import_module()}.


在 3.3 版的變更: Negative values for `level' are no longer supported (which also changes
the default value to 0).



在 3.9 版的變更: When the command line options @ref{b4d,,-E} or @ref{b4e,,-I} are being used,
the environment variable 
@geindex PYTHONCASEOK
@geindex 環境變數; PYTHONCASEOK
@ref{b4c,,PYTHONCASEOK} is now ignored.

@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 內建常數,內建型別,內建函式<2>,Python 標準函式庫 Standard Library
@anchor{library/constants doc}@anchor{248e}@anchor{library/constants built-in-constants}@anchor{248f}@anchor{library/constants built-in-consts}@anchor{2490}@anchor{library/constants translation-repo}@anchor{2491}
@section 內建常數


有一小部分的常數存在於內建命名空間中。他們是：

@geindex False (內建變數)
@anchor{library/constants False}@anchor{d23}
@deffn {資料} False

在 @ref{3c1,,bool} 型別中的 false 值。對於 @code{False} 的賦值是不合法的，並且會拋出 @ref{18e,,SyntaxError}。
@end deffn

@geindex True (內建變數)
@anchor{library/constants True}@anchor{e02}
@deffn {資料} True

在 @ref{3c1,,bool} 型別中的 true 值。對於 @code{True} 的賦值是不合法的，並且會拋出 @ref{18e,,SyntaxError}。
@end deffn

@geindex None (內建變數)
@anchor{library/constants None}@anchor{87e}
@deffn {資料} None

型別 @code{NoneType} 的唯一值。@code{None} 經常被使用來表達缺少值，例如未傳送預設的引數至函式時，相對應參數即會被賦予 @code{None}。對於 @code{None} 的賦值是不合法的，並且會拋出 @ref{18e,,SyntaxError}。@code{None} 是型別 @ref{a4b,,NoneType} 的唯一實例。
@end deffn

@geindex NotImplemented (內建變數)
@anchor{library/constants NotImplemented}@anchor{1a2}
@deffn {資料} NotImplemented

會被二元特殊方法 (binary special methods)（如：@ref{ce9,,__eq__()}、@ref{14a1,,__lt__()}、@ref{228f,,__add__()}、@ref{229f,,__rsub__()}  等）所回傳的特殊值，代表著該運算沒有針對其他型別的實作。同理也可以被原地二元特殊方法 (in-place binary special methods) （如：@ref{2294,,__imul__()}、@ref{22ae,,__iand__()} 等）回傳。它不應該被作為 boolean（布林）來解讀。@code{NotImplemented} 是型別 @ref{a4c,,types.NotImplementedType} 的唯一實例。

@cartouche
@quotation 備註 
當一個二元 (binary) 或原地 (in-place) 方法回傳 @code{NotImplemented}，直譯器會嘗試反映該操作到其他型別（或是其他後備 (fallback)，取決於是哪種運算子）。如果所有的常識都回傳 @code{NotImplemented}，直譯器會拋出適當的例外。不正確的回傳 @code{NotImplemented} 會造成誤導的錯誤訊息或是 @code{NotImplemented} 值被傳回到 Python 程式碼中。

請參見 @ref{21e7,,實作算術操作} 以找到更多範例。
@end quotation
@end cartouche

@cartouche
@quotation 警示 
@code{NotImplemented} 與 @code{NotImplementedError} 並不一樣且不可互換。這個常數只能用於上述的情況；欲知更多如何正確使用它們的細節，請參見 @ref{369,,NotImplementedError}。
@end quotation
@end cartouche


在 3.9 版的變更: 在 boolean（布林）上下文中對 @code{NotImplemented} 求值的操作已被棄用。



在 3.14 版的變更: 在 boolean 上下文中解讀 @code{NotImplemented} 現在會引發 @ref{198,,TypeError}。過去自 Python 3.9 以來，這會被解讀成 @ref{e02,,True}，並發出 @ref{1a3,,DeprecationWarning}

@end deffn

@geindex ...;ellipsis literal（刪節號字面值）

@geindex Ellipsis (內建變數)
@anchor{library/constants Ellipsis}@anchor{21dd}
@deffn {資料} Ellipsis

與刪節號 "@code{...}" 字面相同，是一個經常被用來表示某些東西被省略的物件。對於 @code{Ellipsis} 的賦值是可能的，但對於 @code{...} 的賦值會引發 @ref{18e,,SyntaxError}。@code{Ellipsis} 是型別 @ref{a4a,,types.EllipsisType} 的唯一實例。
@end deffn

@geindex __debug__ (內建變數)
@anchor{library/constants debug__}@anchor{9d3}
@deffn {資料} __debug__

如果 Python 沒有被以 @ref{18c,,-O} 選項啟動，則此常數為 true。請參見 @ref{b57,,assert} 陳述式。
@end deffn

@cartouche
@quotation 備註 
@ref{87e,,None}，@ref{d23,,False}，@ref{e02,,True}，以及 @ref{9d3,,__debug__} 都是不能被重新賦值的（任何對它們的賦值，即使是屬性的名稱，也會拋出 @ref{18e,,SyntaxError}）。因此，它們可以被視為”真正的”常數。
@end quotation
@end cartouche

@menu
* 由 site module（模組）所添增的常數:: 

@end menu

@node 由 site module（模組）所添增的常數,,,內建常數
@anchor{library/constants constants-added-by-the-site-module}@anchor{2492}@anchor{library/constants site-consts}@anchor{2493}
@subsection 由 @code{site} module（模組）所添增的常數


@ref{cc,,site} module（模組）（在啟動期間自動 import ，除非有給予 @ref{13a9,,-S} 指令行選項）會添增一些常數到內建命名空間 (built-in namespace) 中。它們在互動式直譯器中是很有幫助的，但不應該在程式 (programs) 中被使用。

@geindex quit (內建變數)
@geindex exit (內建變數)
@anchor{library/constants quit}@anchor{2494}
@deffn {資料} quit (code=None)
@anchor{library/constants exit}@anchor{2495}
@deffnx {資料} exit (code=None)

當印出物件時，會印出一個訊息："Use quit() or Ctrl-D (i.e. EOF) to exit"。當直接在互動式直譯器中存取或作為函式呼叫時，會引發 @ref{f37,,SystemExit} 並帶有指定的返回碼（exit code）。
@end deffn


@deffn {資料} help

當印出此物件時，會印出訊息 "Type help() for interactive help, or help(object) for help about object."，並在互動式直譯器中直接存取時，會叫用內建的幫助系統（參見 @ref{acb,,help()}）。
@end deffn

@geindex copyright (內建變數)
@geindex credits (內建變數)
@anchor{library/constants copyright}@anchor{2496}
@deffn {資料} copyright
@anchor{library/constants credits}@anchor{1752}
@deffnx {資料} credits

當印出或是呼叫此物件時，分別會印出版權與致謝的文字。
@end deffn

@geindex license (內建變數)
@anchor{library/constants license}@anchor{2497}
@deffn {資料} license

當印出此物件時，會印出訊息 "Type license() to see the full license text"，並在呼叫時以分頁形式印出完整的許可證文字（一次一整個畫面）。
@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 內建型別,內建的例外,內建常數,Python 標準函式庫 Standard Library
@anchor{library/stdtypes doc}@anchor{2498}@anchor{library/stdtypes bltin-types}@anchor{2499}@anchor{library/stdtypes built-in-types}@anchor{249a}@anchor{library/stdtypes translation-repo}@anchor{249b}
@section 內建型別


以下章節描述了直譯器中內建的標準型別。

@geindex built-in（內建）;type（型別）

主要內建型別為數字、序列、對映、class（類別）、實例和例外。

有些集合類別是 mutable（可變的）。那些用於原地 (in-place) 加入、移除或重新排列其成員且不回傳特定項的 method（方法），也只會回傳 @code{None} 而非集合實例自己。

某些操作已被多種物件型別支援；特別是實務上所有物件都已經可以做相等性比較、真值檢測及被轉換為字串（使用 @ref{1c1,,repr()} 函式或稍有差異的 @ref{169,,str()} 函式），後者為當物件傳入 @ref{1170,,print()} 函式印出時在背後被呼叫的函式。

@menu
* 真值檢測:: 
* Boolean（布林）運算: Boolean（布林）運算 --- and or not. and, or, not
* 比較運算:: 
* 數值型別: 數值型別 --- int、float、complex. int、float、complex
* Boolean 型別 - bool:: 
* 疊代器型別:: 
* Sequence Types: Sequence Types --- list tuple range. list, tuple, range
* Text and Binary Sequence Type Methods Summary:: 
* Text Sequence Type: Text Sequence Type --- str. str
* Binary Sequence Types: Binary Sequence Types --- bytes bytearray memoryview. bytes, bytearray, memoryview
* Set Types: Set Types --- set frozenset. set, frozenset
* Mapping Types: Mapping Types --- dict. dict
* 情境管理器型別:: 
* 型別註釋的型別: 型別註釋的型別 --- 泛型別名 Generic Alias 、聯合 Union. 泛型別名 (Generic Alias)、聯合 (Union)
* 其他內建型別:: 
* 特殊屬性: 特殊屬性<3>. 
* Integer string conversion length limitation:: 

@end menu

@node 真值檢測,Boolean（布林）運算 --- and or not,,內建型別
@anchor{library/stdtypes truth}@anchor{17d7}@anchor{library/stdtypes truth-value-testing}@anchor{249c}
@subsection 真值檢測


@geindex statement（陳述式）;if
@geindex statement（陳述式）;while
@geindex truth（真）;value
@geindex Boolean（布林）;operations（操作）
@geindex false

任何物件都可以進行檢測以判斷是否為真值，以便在 @ref{181,,if} 或 @ref{18d6,,while} 條件中使用，或是作為如下所述 boolean（布林）運算之運算元所用。

@geindex true

預設情況下，一個物件會被視為真值，除非它的 class 定義了會回傳 @code{False} 的 @ref{14d6,,__bool__()} method 或是定義了會回傳零的 @ref{2260,,__len__()} method。@footnote{
Additional information on these special methods may be found in the Python
Reference Manual (@ref{225e,,Basic customization}).
} 以下列出了大部分會被視為 false 的內建物件：

@geindex None（內建物件）
@geindex False（內建物件）


@itemize *

@item 
定義為 false 之常數：@code{None} 與 @code{False}

@item 
任何數值型別的零：@code{0}、@code{0.0}、@code{0j}、@code{Decimal(0)}、@code{Fraction(0, 1)}

@item 
空的序列和集合：@code{'@w{'}}、@code{()}、@code{[]}、@code{@{@}}、@code{set()}、@code{range(0)}
@end itemize

@geindex operator（運算子）;or
@geindex operator（運算子）;and
@geindex False
@geindex True

除非另有特別說明，產生 boolean 結果的操作或內建函式都會回傳 @code{0} 或 @code{False} 作為假值、@code{1} 或 @code{True} 作為真值。（重要例外： boolean 運算 @code{or} 和 @code{and} 回傳的是其中一個運算元。）

@node Boolean（布林）運算 --- and or not,比較運算,真值檢測,內建型別
@anchor{library/stdtypes boolean}@anchor{249d}@anchor{library/stdtypes boolean-operations-and-or-not}@anchor{249e}
@subsection Boolean（布林）運算 --- @code{and}, @code{or}, @code{not}


@geindex Boolean（布林）;operations（操作）

下方為 Boolean 運算，按優先順序排序：


@multitable {xxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxx} 
@headitem

運算

@tab

結果

@tab

註解

@item

@code{x or y}

@tab

假如 `x' 為真，則 `x'，否則 `y'

@tab

(1)

@item

@code{x and y}

@tab

假如 `x' 為假，則 `x'，否則 `y'

@tab

(2)

@item

@code{not x}

@tab

假如 `x' 為假，則 @code{True}，否則 @code{False}

@tab

(3)

@end multitable


@geindex operator（運算子）;and
@geindex operator（運算子）;or
@geindex operator（運算子）;not

註解：


@enumerate 

@item 
這是一個短路運算子，所以他只有在第一個引數為假時，才會對第二個引數求值。

@item 
這是一個短路運算子，所以他只有在第一個引數為真時，才會對第二個引數求值。

@item 
@code{not} 比非 Boolean 運算子有較低的優先權，因此 @code{not a == b} 可直譯為 @code{not (a == b)}，而 @code{a == not b} 會導致語法錯誤。
@end enumerate

@node 比較運算,數值型別 --- int、float、complex,Boolean（布林）運算 --- and or not,內建型別
@anchor{library/stdtypes comparisons}@anchor{249f}@anchor{library/stdtypes stdcomparisons}@anchor{24a0}
@subsection 比較運算


@geindex chaining（鏈結）;comparisons（比較）
@geindex operator（運算子）;comparison（比較）
@geindex operator（運算子）;==
@geindex operator（運算子）;< （小於）
@geindex operator（運算子）;<=
@geindex operator（運算子）;> （大於）
@geindex operator（運算子）;>=
@geindex operator（運算子）;!=
@geindex operator（運算子）;is
@geindex operator（運算子）;is not

在 Python 裡共有 8 種比較運算。他們的優先順序都相同（皆優先於 Boolean 運算）。比較運算可以任意的串連；例如，@code{x < y <= z} 等同於 @code{x < y and y <= z}，差異只在於前者的 `y' 只有被求值一次（但在這兩個例子中，當 @code{x < y} 為假時，`z' 皆不會被求值）。

這個表格統整所有比較運算：


@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 object（物件）;numeric（數值）
@geindex objects（物件）;comparing（比較）

除了不同的數值型別外，不同型別的物件不能進行相等比較。運算子 @code{==} 總有定義，但在某些物件型別（例如，class 物件）時，運算子會等同於 @ref{34a,,is}。其他運算子 @code{<}、@code{<=}、@code{>} 及 @code{>=} 皆僅在有意義的部分有所定義；例如，當其中一個引數為複數時，將引發一個 @ref{198,,TypeError} 的例外。

@geindex __eq__()（實例方法）
@geindex __ne__()（實例方法）
@geindex __lt__()（實例方法）
@geindex __le__()（實例方法）
@geindex __gt__()（實例方法）
@geindex __ge__()（實例方法）

一個 class 的非相同實例通常會比較為不相等，除非 class 有定義 @ref{ce9,,__eq__()} method。

一個 class 的實例不可以與其他相同 class 的實例或其他物件型別進行排序，除非 class 定義足夠的 method ，包含 @ref{14a1,,__lt__()}、@ref{150b,,__le__()}、@ref{150c,,__gt__()} 及 @ref{150d,,__ge__()}（一般來說，使用 @ref{14a1,,__lt__()} 及 @ref{ce9,,__eq__()} 就可以滿足常規意義上的比較運算子）。

無法自定義 @ref{34a,,is} 與 @ref{237f,,is not} 運算子的行為；這兩個運算子也可以運用在任意兩個物件且不會引發例外。

@geindex operator（運算子）;in
@geindex operator（運算子）;not in

此外，擁有相同的語法優先序的 @ref{349,,in} 及 @ref{83a,,not in} 兩種運算皆被@ref{1428,,可疊代物件}或者有實作 @ref{15b1,,__contains__()} method 的型別所支援。

@node 數值型別 --- int、float、complex,Boolean 型別 - bool,比較運算,內建型別
@anchor{library/stdtypes numeric-types-int-float-complex}@anchor{24a1}@anchor{library/stdtypes typesnumeric}@anchor{1ea3}
@subsection 數值型別 --- @code{int}、@code{float}、@code{complex}


@geindex object（物件）;numeric（數值）
@geindex object（物件）;Boolean（布林）
@geindex object（物件）;integer（整數）
@geindex object（物件）;floating-point（浮點數）
@geindex object（物件）;complex number（複數）
@geindex C;language（語言）

數值型別共有三種：`整數'、`浮點數' 及 `複數'。此外，Boolean 為整數中的一個子型別。整數有無限的精度。浮點數通常使用 C 裡面的 double 實作。關於在你程式所運作的機器上之浮點數的精度及內部表示法可以在 @ref{1c98,,sys.float_info} 進行查找。複數包含實數及虛數的部分，這兩部分各自是一個浮點數。若要從一個複數 `z' 提取這兩部分，需使用 @code{z.real} 及 @code{z.imag}。（標準函式庫包含額外的數值型別，像是 @ref{213,,fractions.Fraction} 表示有理數，而 @ref{1fe,,decimal.Decimal} 表示可由使用者制定精度的浮點數。）

@geindex numeric（數值）;literals（字面值）
@geindex integer（整數）;literals（字面值）
@geindex floating-point（浮點數）;literals（字面值）
@geindex complex number（複數）;literals（字面值）
@geindex hexadecimal（十六進位）;literals（字面值）
@geindex octal（八進位）;literals（字面值）
@geindex binary（二進位）;literals（字面值）

數字是由字面數值或內建公式及運算子的結果所產生的。未經修飾的字面數值（含十六進位、八進位及二進位數值）會 yield 整數。包含小數點或指數符號的字面數值會 yield 浮點數。在數值後面加上 @code{'j'} 或是 @code{'J'} 會 yield 一個虛數（意即一個實數為 0 的複數）。你也可以將整數與浮點數相加以得到一個有實部與虛部的複數。

建構函式： @ref{19b,,int()}、@ref{196,,float()} 及 @ref{197,,complex()} 可以用來產生特定型別的數字。

@geindex arithmetic（算術）
@geindex built-in function（內建函式）;int
@geindex built-in function（內建函式）;float
@geindex built-in function（內建函式）;complex（複數）
@geindex operator（運算子）;+ （加號）
@geindex + （加號）;unary operator（一元運算子）
@geindex + （加號）;binary operator（二元運算子）
@geindex operator（運算子）;- （減號）
@geindex - （減號）;unary operator（一元運算子）
@geindex - （減號）;binary operator（二元運算子）
@geindex operator（運算子）;* （星號）
@geindex operator（運算子）;/ （斜線）
@geindex operator（運算子）;//
@geindex operator（運算子）;% （百分號）
@geindex operator（運算子）;**

Python 完全支援混和運算：當一個二元運算子的運算元有不同數值型別時，「較窄」型別的運算元會被拓寬到另一個型別的運算元；在此處，整數窄於浮點數。複數及實數運算元的運算是由一般的數學公式所定義，例如：

@example
x + complex(u, v) = complex(x + u, v)
x * complex(u, v) = complex(x * u, x * v)
@end example

A comparison between numbers of different types behaves as though the exact
values of those numbers were being compared. @footnote{
As a consequence, the list @code{[1, 2]} is considered equal to @code{[1.0, 2.0]}, and
similarly for tuples.
}

所有數值型別（除複數外）皆支援以下的運算（有關運算的先後順序，詳見 @ref{2393,,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' 的絕對值或量 (magnitude)

@tab

@tab

@ref{1f54,,abs()}

@item

@code{int(x)}

@tab

將 `x' 轉為整數

@tab

(3)(6)

@tab

@ref{19b,,int()}

@item

@code{float(x)}

@tab

將 `x' 轉為浮點數

@tab

(4)(6)

@tab

@ref{196,,float()}

@item

@code{complex(re, im)}

@tab

一個複數，其實部為 `re'，虛部為 `im'。`im' 預設為零。

@tab

(6)

@tab

@ref{197,,complex()}

@item

@code{c.conjugate()}

@tab

為複數 `c' 的共軛複數

@tab

@tab

@item

@code{divmod(x, y)}

@tab

一對 @code{(x // y, x % y)}

@tab

(2)

@tab

@ref{b90,,divmod()}

@item

@code{pow(x, y)}

@tab

`x' 的 `y' 次方

@tab

(5)

@tab

@ref{1a4,,pow()}

@item

@code{x ** y}

@tab

`x' 的 `y' 次方

@tab

(5)

@tab

@end multitable


@geindex operations on（操作於）;numeric（數值）;type（型別）
@geindex conjugate()（複數方法）

註解：


@enumerate 

@item 
也被稱為整數除法。對於型別為 @ref{19b,,int} 的運算元來說，結果之型別會是 @ref{19b,,int}。對於型別為 @ref{196,,float} 的運算元來說，結果之型別會是 @ref{196,,float}。一般來說，結果會是一個整數，但其型別不一定會是 @ref{19b,,int}。結果總是會往負無窮大的方向取整數值： @code{1//2} 為 @code{0}、@code{(-1)//2} 為 @code{-1}、@code{1//(-2)} 為 @code{-1} 及 @code{(-1)//(-2)} 為 @code{0}。

@item 
不可用於複數。在適當情形下，可使用 @ref{1f54,,abs()} 轉換為浮點數。

@item 
@geindex 模組;math
@geindex floor()（於 math 模組）
@geindex ceil()（於 math 模組）
@geindex trunc()（於 math 模組）
@geindex numeric（數值）;conversions（轉換）

從 @ref{196,,float} 轉換為 @ref{19b,,int} 會導致截斷並排除小數部分。詳見 @ref{15b5,,math.floor()} 及 @ref{15b6,,math.ceil()} 以了解更多轉換方式。

@item 
浮點數也接受帶有可選的前綴 "+" 及 "-" 的 "nan" 及  "inf" 字串，其分別代表非數字（NaN）及正負無窮。

@item 
Python 將 @code{pow(0, 0)} 及 @code{0 ** 0} 定義為 @code{1} 這是程式語言的普遍做法。

@item 
字面數值接受包含數字 @code{0} 到 @code{9} 或任何等效的 Unicode 字元（具有 @code{Nd} 屬性的 code points（編碼位置））。

請參閱 Unicode 標準@footnote{https://unicode.org/Public/UNIDATA/extracted/DerivedNumericType.txt}以了解具有 @code{Nd} 屬性的 code points 完整列表。
@end enumerate

所有 @ref{24a2,,numbers.Real} 型別（@ref{19b,,int} 及 @ref{196,,float}）也適用下列運算：


@multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

運算

@tab

結果

@item

@ref{15b7,,math.trunc(x)}

@tab

`x' 截斷為 @ref{22b9,,Integral}

@item

@ref{14db,,round(x[@comma{} n])}

@tab

`x' 進位至小數點後第 `n' 位，使用偶數捨入法。若省略 `n' ，則預設為 0。

@item

@ref{15b5,,math.floor(x)}

@tab

小於等於 `x' 的最大 @ref{22b9,,Integral}

@item

@ref{15b6,,math.ceil(x)}

@tab

大於等於 `x' 的最小 @ref{22b9,,Integral}

@end multitable


關於其他數值運算請詳見 @ref{92,,math} 及 @ref{19,,cmath} modules（模組）。

@c XXXJH exceptions: overflow (when? what operations?) zerodivision

@menu
* 整數型別的位元運算:: 
* 整數型別的附加方法:: 
* 浮點數的附加方法:: 
* 複數的附加方法:: 
* 數值型別的雜湊:: 

@end menu

@node 整數型別的位元運算,整數型別的附加方法,,數值型別 --- int、float、complex
@anchor{library/stdtypes bitstring-ops}@anchor{24a3}@anchor{library/stdtypes bitwise-operations-on-integer-types}@anchor{24a4}
@subsubsection 整數型別的位元運算


@geindex operations on（操作於）;integer（整數）;type（型別）
@geindex bitwise（位元）;operations（操作）
@geindex shifting（移位）;operations（操作）
@geindex masking（遮罩）;operations（操作）
@geindex operator（運算子）;| （垂直線）
@geindex operator（運算子）;^ （插入符號）
@geindex operator（運算子）;& （和號）
@geindex operator（運算子）;<<
@geindex operator（運算子）;>>
@geindex operator（運算子）;~ （波浪號）

位元運算只對整數有意義。位元運算的計算結果就如同對二的補數執行無窮多個符號位元。

二元位元運算的優先順序皆低於數字運算，但高於比較運算；一元運算 @code{~} 與其他一元數值運算有一致的優先順序（@code{+} 及 @code{-}）。

這個表格列出所有位元運算並以優先順序由先至後排序。


@multitable {xxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxx} 
@headitem

運算

@tab

結果

@tab

註解

@item

@code{x | y}

@tab

`x' 及 `y' 的位元 `或'

@tab

(4)

@item

@code{x ^ y}

@tab

`x' 及 `y' 的位元 `邏輯互斥或'

@tab

(4)

@item

@code{x & y}

@tab

`x' 及 `y' 的位元 `與'

@tab

(4)

@item

@code{x << n}

@tab

`x' 往左移動 `n' 個位元

@tab

(1)(2)

@item

@code{x >> n}

@tab

`x' 往右移動 `n' 個位元

@tab

(1)(3)

@item

@code{~x}

@tab

反轉 `x' 的位元

@tab

@end multitable


註解：


@enumerate 

@item 
負數位移是不被允許並會引發 @ref{2eb,,ValueError} 的錯誤。

@item 
向左移動 `n' 個位元等同於乘以 @code{pow(2, n)}。

@item 
向右移動 `n' 個位元等同於向下除法除以 @code{pow(2, n)}。

@item 
在有限的二的補數表示法中執行這些計算（一個有效位元寬度為 @code{1 + max(x.bit_length(), y.bit_length())} 或以上）並至少有一個額外的符號擴展位元，便足以得到與無窮多個符號位元相同的結果。
@end enumerate

@node 整數型別的附加方法,浮點數的附加方法,整數型別的位元運算,數值型別 --- int、float、complex
@anchor{library/stdtypes additional-methods-on-integer-types}@anchor{24a5}
@subsubsection 整數型別的附加方法


整數型別實作了 @ref{22b9,,numbers.Integral} @ref{13b7,,抽象基底類別}。此外，它提供了一些方法：

@geindex bit_length() (int 的方法)
@anchor{library/stdtypes int bit_length}@anchor{24a6}
@deffn {方法} int.bit_length ()

回傳以二進位表示一個整數所需要的位元數，不包括符號及首位的零：

@example
>>> n = -37
>>> bin(n)
'-0b100101'
>>> n.bit_length()
6
@end example

更準確來說，若 @code{x} 非為零，則 @code{x.bit_length()} 會得出滿足 @code{2**(k-1) <= abs(x) < 2**k} 的單一正整數 @code{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


在 3.1 版被加入.

@end deffn

@geindex bit_count() (int 的方法)
@anchor{library/stdtypes int bit_count}@anchor{9c8}
@deffn {方法} int.bit_count ()

回傳在絕對值表示的二進位中 1 的個數。這也被稱作母體計數。舉例來說：

@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


在 3.10 版被加入.

@end deffn

@geindex to_bytes() (int 的方法)
@anchor{library/stdtypes int to_bytes}@anchor{1b46}
@deffn {方法} int.to_bytes (length=1, byteorder='big', *, signed=False)

回傳表示一個整數的一列位元組。

@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' 位元組表示，並且預設為 1。如果該整數無法用給定的位元組數來表示，則會引發 @ref{a78,,OverflowError}。

`byteorder' 引數決定了用來表示整數的位元組順序並且預設為 @code{"big"}。如果 byteorder 是 @code{"big"}，最重要的位元組位於位元組陣列的開頭。如果 byteorder 是 @code{"little"}，最重要的位元組位於位元組陣列的結尾。

`signed' 引數決定是否使用二的補數來表示整數。如果 `signed' 是 @code{False} 並且給定了一個負整數，則會引發 @ref{a78,,OverflowError}。`signed' 的預設值是 @code{False}。

預設值可以方便地將一個整數轉換為單一位元組物件：

@example
>>> (65).to_bytes()
b'A'
@end example

然而，使用預設引數時，不要嘗試轉換大於 255 的值，否則你將會得到一個 @ref{a78,,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


在 3.2 版被加入.



在 3.11 版的變更: 為 @code{length} 和 @code{byteorder} 添加了預設引數值。

@end deffn

@geindex from_bytes() (int 的類別方法)
@anchor{library/stdtypes int from_bytes}@anchor{1b07}
@deffn {方法} classmethod int.from_bytes (bytes, byteorder='big', *, signed=False)

回傳由給定的位元組陣列表示的整數。

@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{193,,類位元組物件}或是一個產生位元組的可疊代物件。

`byteorder' 引數決定了用來表示整數的位元組順序並且預設為 @code{"big"}。如果 `byteorder' 是 @code{"big"}，最重要的位元組位於位元組陣列的開頭。如果 `byteorder' 是 @code{"little"}，最重要的位元組位於位元組陣列的結尾。若要請求主機系統的本機位元組順序，請使用 @ref{24a7,,sys.byteorder} 作為位元組順序值。

`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


在 3.2 版被加入.



在 3.11 版的變更: 為 @code{byteorder} 添加了預設引數值。

@end deffn

@geindex as_integer_ratio() (int 的方法)
@anchor{library/stdtypes int as_integer_ratio}@anchor{bb7}
@deffn {方法} int.as_integer_ratio ()

回傳一對整數，其比率等於原始整數並且有一個正分母。整數（整個數值）的整數比率總是整數作為分子，並且 @code{1} 作為分母。


在 3.8 版被加入.

@end deffn

@geindex is_integer() (int 的方法)
@anchor{library/stdtypes int is_integer}@anchor{1a36}
@deffn {方法} int.is_integer ()

回傳 @code{True}。為了與 @ref{24a8,,float.is_integer()} 的鴨子型別相容而存在。


在 3.12 版被加入.

@end deffn

@node 浮點數的附加方法,複數的附加方法,整數型別的附加方法,數值型別 --- int、float、complex
@anchor{library/stdtypes additional-methods-on-float}@anchor{24a9}
@subsubsection 浮點數的附加方法


浮點數型別實作了 @ref{24a2,,numbers.Real} @ref{13b7,,抽象基底類別}。浮點數也有下列附加方法。

@geindex from_number() (float 的類別方法)
@anchor{library/stdtypes float from_number}@anchor{194}
@deffn {方法} classmethod float.from_number (x)

Class method to return a floating-point number constructed from a number `x'.

If the argument is an integer or a floating-point number, a
floating-point number with the same value (within Python's floating-point
precision) is returned.  If the argument is outside the range of a Python
float, an @ref{a78,,OverflowError} will be raised.

For a general Python object @code{x}, @code{float.from_number(x)} delegates to
@code{x.__float__()}.
If @ref{bb8,,__float__()} is not defined then it falls back
to @ref{19e,,__index__()}.


在 3.14 版被加入.

@end deffn

@geindex as_integer_ratio() (float 的方法)
@anchor{library/stdtypes float as_integer_ratio}@anchor{1fc8}
@deffn {方法} float.as_integer_ratio ()

回傳一對整數，其比率完全等於原始浮點數。比率是在最低條件下並且有一個正分母。在無窮大時引發 @ref{a78,,OverflowError}，在 NaN 時引發 @ref{2eb,,ValueError}。
@end deffn

@geindex is_integer() (float 的方法)
@anchor{library/stdtypes float is_integer}@anchor{24a8}
@deffn {方法} float.is_integer ()

如果浮點數實例是有限的並且具有整數值，則回傳 @code{True}，否則回傳 @code{False}：

@example
>>> (-2.0).is_integer()
True
>>> (3.2).is_integer()
False
@end example
@end deffn

兩個 methods 皆支援十六進位字串之間的轉換。由於 Python 的浮點數內部以二進位數值儲存，將浮點數轉換為或從 `十進位' 字串通常涉及一個小的四捨五入誤差。相反地，十六進位字串允許精確表示和指定浮點數。這在除錯和數值工作中可能會有用。

@geindex hex() (float 的方法)
@anchor{library/stdtypes float hex}@anchor{1fc9}
@deffn {方法} float.hex ()

回傳浮點數的十六進位字串表示。對於有限浮點數，此表示方式總是包含一個前導 @code{0x} 及一個尾部 @code{p} 和指數。
@end deffn

@geindex fromhex() (float 的類別方法)
@anchor{library/stdtypes float fromhex}@anchor{24aa}
@deffn {方法} classmethod float.fromhex (s)

Class method 回傳由十六進位字串 `s' 表示的浮點數。字串 `s' 可能有前導及尾部的空白。
@end deffn

請注意 @ref{1fc9,,float.hex()} 是一個實例 method，而 @ref{24aa,,float.fromhex()} 是一個 class method。

一個十六進位字串的形式如下：

@example
[sign] ['0x'] integer ['.' fraction] ['p' exponent]
@end example

其中可選的 @code{sign} 可以是 @code{+} 或 @code{-}，@code{integer} 和 @code{fraction} 是十六進位數字的字串，而 @code{exponent} 是一個十進位整數並且有一個可選的前導符號。大小寫不重要，並且整數或小數部分至少有一個十六進位數字。這個語法與 C99 標準的第 6.4.4.2 節指定的語法相似，也與 Java 1.5 以後的語法相似。特別是 @ref{1fc9,,float.hex()} 的輸出可用作 C 或 Java 程式碼中的十六進位浮點數文字，並且 C 的 @code{%a} 格式字元或 Java 的 @code{Double.toHexString} 產生的十六進位字串可被 @ref{24aa,,float.fromhex()} 接受。

請注意指數是以十進位而非十六進位寫入，並且它給出了乘以係數的 2 的次方。例如，十六進位字串 @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} 應用反向轉換會給出一個不同的十六進位字串，它表示相同的數字：

@example
>>> float.hex(3740.0)
'0x1.d380000000000p+11'
@end example

@node 複數的附加方法,數值型別的雜湊,浮點數的附加方法,數值型別 --- int、float、complex
@anchor{library/stdtypes additional-methods-on-complex}@anchor{24ab}
@subsubsection 複數的附加方法


@code{complex} 型別實作了 @ref{24ac,,numbers.Complex} @ref{13b7,,抽象基底類別}。@code{complex} 也有下列附加方法。

@geindex from_number() (complex 的類別方法)
@anchor{library/stdtypes complex from_number}@anchor{195}
@deffn {方法} classmethod complex.from_number (x)

將一個數字轉換為複數的類別方法。

For a general Python object @code{x}, @code{complex.from_number(x)} delegates to
@code{x.__complex__()}.  If @ref{7f8,,__complex__()} is not defined then it falls back
to @ref{bb8,,__float__()}.  If @code{__float__()} is not defined then it falls back
to @ref{19e,,__index__()}.


在 3.14 版被加入.

@end deffn

@node 數值型別的雜湊,,複數的附加方法,數值型別 --- int、float、complex
@anchor{library/stdtypes hashing-of-numeric-types}@anchor{24ad}@anchor{library/stdtypes numeric-hash}@anchor{24ae}
@subsubsection 數值型別的雜湊


對於數字 @code{x} 和 @code{y}，可能是不同型別，當 @code{x == y} 時，@code{hash(x) == hash(y)} 是一個要求（ 詳見 @ref{cea,,__hash__()} method 的文件以獲得更多細節）。為了實作的便利性和效率跨越各種數值型別（包括 @ref{19b,,int}、@ref{196,,float}、@ref{1fe,,decimal.Decimal} 和 @ref{213,,fractions.Fraction}）Python 的數值型別的雜湊是基於一個數學函式，它對於任何有理數都是定義的，因此適用於所有 @ref{19b,,int} 和 @ref{213,,fractions.Fraction} 的實例，以及所有有限的 @ref{196,,float} 和 @ref{1fe,,decimal.Decimal} 的實例。基本上，這個函式是由簡化的 modulo（模數） @code{P} 給出的一個固定的質數 @code{P}。@code{P} 的值作為 @ref{11fa,,sys.hash_info} 的 @ref{24af,,modulus} 屬性提供給 Python。

目前在具有 32 位元 C longs 的機器上所使用的質數是 @code{P = 2**31 - 1}，而在具有 64 位元 C longs 的機器上為 @code{P = 2**61 - 1} 。

以下是詳細的規則：


@itemize -

@item 
如果 @code{x = m / n} 是一個非負的有理數，並且 @code{n} 不可被 @code{P} 整除，則將 @code{hash(x)} 定義為 @code{m * invmod(n, P) % P}。其中 @code{invmod(n, P)} 為 @code{n} 對模數 @code{P} 的倒數。

@item 
如果 @code{x = m / n} 是一個非負的有理數，並且 @code{n} 可被 @code{P} 整除（但 @code{m} 不行），則 @code{n} 沒有 inverse modulo（模倒數） @code{P} ，並且不適用於上述規則；在這種情況下，將 @code{hash(x)} 定義為常數值 @code{sys.hash_info.inf}。

@item 
如果 @code{x = m / n} 是一個負的有理數，則將 @code{hash(x)} 定義為 @code{-hash(-x)}。如果結果的雜湊是 @code{-1}，則將其替換為 @code{-2}。

@item 
特定值 @code{sys.hash_info.inf} 和 @code{-sys.hash_info.inf} （分別）被用作正無窮大或負無窮大的雜湊值。

@item 
對於一個 @ref{197,,complex} 值 @code{z}，實部和虛部的雜湊值藉由 @code{hash(z.real) + sys.hash_info.imag * hash(z.imag)} 的計算進行組合，對 @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 程式碼範例，等同於內建的雜湊，用於計算有理數、@ref{196,,float} 或 @ref{197,,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{24b0}
@node Boolean 型別 - bool,疊代器型別,數值型別 --- int、float、complex,內建型別
@anchor{library/stdtypes boolean-type-bool}@anchor{24b1}@anchor{library/stdtypes typebool}@anchor{246a}
@subsection Boolean 型別 - @code{bool}


Boolean 值代表 truth values（真值）。@ref{3c1,,bool} 型別有兩個常數實例：@code{True} 和 @code{False}。

@geindex False
@geindex True
@geindex Boolean（布林）;values

內建函式 @ref{3c1,,bool()} 將任何值轉換為 boolean 值，如果該值可以被直譯為一個 truth value（真值）（見上面的@ref{17d7,,真值檢測}章節）。

對於邏輯運算，使用 @ref{249d,,boolean 運算子} @code{and}、@code{or} 和 @code{not}。當將位元運算子 @code{&}、@code{|}、@code{^} 應用於兩個 boolean 值時，它們會回傳一個等同於邏輯運算 "and"、"or"、"xor" 的 boolean 值。然而，應該優先使用邏輯運算子 @code{and}、@code{or} 和 @code{!=} 而不是 @code{&}、@code{|} 和 @code{^}。


在 3.12 版之後被棄用: 位元反轉運算子 @code{~} 的使用已被棄用並且將在 Python 3.16 中引發錯誤。


@ref{3c1,,bool} 是 @ref{19b,,int} 的子類別（見@ref{1ea3,,數值型別 --- int、float、complex}）。在許多數值情境中，@code{False} 和 @code{True} 分別像整數 0 和 1 一樣。然而，不鼓勵依賴這一點；請使用 @ref{19b,,int()} 進行顯式轉換。

@node 疊代器型別,Sequence Types --- list tuple range,Boolean 型別 - bool,內建型別
@anchor{library/stdtypes iterator-types}@anchor{24b2}@anchor{library/stdtypes typeiter}@anchor{2481}
@subsection 疊代器型別


@geindex iterator protocol（疊代器協定）
@geindex protocol（協定）;iterator（疊代器）
@geindex sequence（序列）;iteration（疊代）
@geindex container（容器）;iteration over（疊代於）

Python 支援對容器的疊代概念。這是實作兩種不同的 methods；這些方法被用於允許使用者自定義的 classes 以支援疊代。序列則總是支援這些疊代 methods，在下方有更詳細的描述。

需要為容器物件定義一個 method 來提供@ref{1428,,可疊代物件}支援：

@c XXX duplicated in reference/datamodel!

@geindex __iter__() (container 的方法)
@anchor{library/stdtypes container __iter__}@anchor{1f71}
@deffn {方法} container.__iter__ ()

回傳一個@ref{4c3,,疊代器}物件。該物件需要支援下述的疊代器協定。如果一個容器支援不同型別的疊代，則可以提供額外的 methods 來專門請求這些疊代型別的疊代器。（支援多種形式疊代的物件的一個例子是支援廣度優先和深度優先遍歷的樹結構。）此 method 對應 Python/C API 中 Python 物件的型別結構的 @ref{16e3,,tp_iter} 插槽。
@end deffn

疊代器物件本身需要支援下列兩個 methods，他們一起形成了 `疊代器協定'：

@geindex __iter__() (iterator 的方法)
@anchor{library/stdtypes iterator __iter__}@anchor{1f74}
@deffn {方法} iterator.__iter__ ()

回傳@ref{4c3,,疊代器}物件本身。這是為了允許容器和疊代器都可以與 @ref{348,,for} 和 @ref{349,,in} 在陳述式中使用。此 method 對應於 Python/C API 中 Python 物件的型別結構的 @ref{16e3,,tp_iter} 插槽。
@end deffn

@geindex __next__() (iterator 的方法)
@anchor{library/stdtypes iterator __next__}@anchor{14ce}
@deffn {方法} iterator.__next__ ()

從@ref{4c3,,疊代器}回傳下一個項目。如果沒有更多項目，則引發 @ref{df0,,StopIteration} 例外。此 method 對應於 Python/C API 中Python 物件的型別結構的 @ref{16e4,,tp_iternext} 插槽。
@end deffn

Python 定義了幾個疊代器物件來支援對一般和特定序列型別、字典和其他更專門的形式的疊代。這些特定型別除了實作疊代器協定外並不重要。

一旦疊代器的 @ref{14ce,,__next__()} method 引發 @ref{df0,,StopIteration}，則它必須在後續呼叫中繼續這樣做。不遵守此屬性的實作被認為是有問題的。

@menu
* Generator Types:: 

@end menu

@node Generator Types,,,疊代器型別
@anchor{library/stdtypes generator-types}@anchor{24b3}@anchor{library/stdtypes id3}@anchor{24b4}
@subsubsection Generator Types


Python's @ref{125c,,generator}s provide a convenient way to implement the iterator
protocol.  If a container object's @ref{e64,,__iter__()} method is implemented as a
generator, it will automatically return an iterator object (technically, a
generator object) supplying the @ref{1f74,,__iter__()} and @ref{1f75,,__next__()}
methods.
More information about generators can be found in @ref{233f,,the documentation for the yield expression}.

@node Sequence Types --- list tuple range,Text and Binary Sequence Type Methods Summary,疊代器型別,內建型別
@anchor{library/stdtypes sequence-types-list-tuple-range}@anchor{24b5}@anchor{library/stdtypes typesseq}@anchor{1ef6}
@subsection Sequence Types --- @code{list}, @code{tuple}, @code{range}


There are three basic sequence types: lists, tuples, and range objects.
Additional sequence types tailored for processing of
@ref{246d,,binary data} and @ref{1ea8,,text strings} are
described in dedicated sections.

@menu
* Common Sequence Operations:: 
* 不可變序列型別:: 
* 可變序列型別:: 
* List（串列）: List（串列）<2>. 
* Tuples:: 
* Ranges:: 

@end menu

@node Common Sequence Operations,不可變序列型別,,Sequence Types --- list tuple range
@anchor{library/stdtypes common-sequence-operations}@anchor{24b6}@anchor{library/stdtypes typesseq-common}@anchor{24b7}
@subsubsection Common Sequence Operations


@geindex object（物件）;sequence（序列）

The operations in the following table are supported by most sequence types,
both mutable and immutable. The @ref{13c5,,collections.abc.Sequence} ABC is
provided to make it easier to correctly implement these operations on
custom sequence types.

This table lists the sequence operations sorted in ascending priority.  In the
table, `s' and `t' are sequences of the same type, `n', `i', `j' and `k' are
integers and `x' is an arbitrary object that meets any type and value
restrictions imposed by `s'.

The @code{in} and @code{not in} operations have the same priorities as the
comparison operations. The @code{+} (concatenation) and @code{*} (repetition)
operations have the same priority as the corresponding numeric operations. @footnote{
They must have since the parser can't tell the type of the operands.
}

@geindex operations on（操作於）;sequence（序列）;type（型別）
@geindex built-in function（內建函式）;len
@geindex built-in function（內建函式）;min
@geindex built-in function（內建函式）;max
@geindex concatenation（串接）;operation（操作）
@geindex repetition（重複）;operation（操作）
@geindex subscript（下標）;operation（操作）
@geindex slice（切片）;operation（操作）
@geindex operator（運算子）;in
@geindex operator（運算子）;not in


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxx} 
@headitem

運算

@tab

結果

@tab

註解

@item

@code{x in s}

@tab

如果 `s' 的一個項目等於 `x' 則為 @code{True}，否則為 @code{False}

@tab

(1)

@item

@code{x not in s}

@tab

如果 `s' 的一個項目等於 `x' 則為 @code{False}，否則為 @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

`s' 的第 `i' 項，起始為 0

@tab

(3)(8)

@item

@code{s[i:j]}

@tab

slice of `s' from `i' to `j'

@tab

(3)(4)

@item

@code{s[i:j:k]}

@tab

slice of `s' from `i' to `j'
with step `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 of the same type also support comparisons.  In particular, tuples
and lists are compared lexicographically by comparing corresponding elements.
This means that to compare equal, every element must compare equal and the
two sequences must be of the same type and have the same length.  (For full
details see @ref{2378,,Comparisons} in the language reference.)

@geindex loop（迴圈）;over mutable sequence（於可變序列）
@geindex mutable sequence（可變序列）;loop over（迴圈）

Forward and reversed iterators over mutable sequences access values using an
index.  That index will continue to march forward (or backward) even if the
underlying sequence is mutated.  The iterator terminates only when an
@ref{1729,,IndexError} or a @ref{df0,,StopIteration} is encountered (or when the index
drops below zero).

註解：


@enumerate 

@item 
While the @code{in} and @code{not in} operations are used only for simple
containment testing in the general case, some specialised sequences
(such as @ref{169,,str}, @ref{192,,bytes} and @ref{343,,bytearray}) also use
them for subsequence testing:

@example
>>> "gg" in "eggs"
True
@end example

@item 
Values of `n' less than @code{0} are treated as @code{0} (which yields an empty
sequence of the same type as `s').  Note that items in the sequence `s'
are not copied; they are referenced multiple times.  This often haunts
new Python programmers; consider:

@example
>>> lists = [[]] * 3
>>> lists
[[], [], []]
>>> lists[0].append(3)
>>> lists
[[3], [3], [3]]
@end example

What has happened is that @code{[[]]} is a one-element list containing an empty
list, so all three elements of @code{[[]] * 3} are references to this single empty
list.  Modifying any of the elements of @code{lists} modifies this single list.
You can create a list of different lists this way:

@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

Further explanation is available in the FAQ entry
@ref{24b8,,如何建立多維度串列？}.

@item 
If `i' or `j' is negative, the index is relative to the end of sequence `s':
@code{len(s) + i} or @code{len(s) + j} is substituted.  But note that @code{-0} is
still @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}.  If `i' or `j' is greater than @code{len(s)}, use
@code{len(s)}.  If `i' is omitted or @code{None}, use @code{0}.  If `j' is omitted or
@code{None}, use @code{len(s)}.  If `i' is greater than or equal to `j', the slice is
empty.

@item 
The slice of `s' from `i' to `j' with step `k' is defined as the sequence of
items with index  @code{x = i + n*k} such that @code{0 <= n < (j-i)/k}.  In other words,
the indices are @code{i}, @code{i+k}, @code{i+2*k}, @code{i+3*k} and so on, stopping when
`j' is reached (but never including `j').  When `k' is positive,
`i' and `j' are reduced to @code{len(s)} if they are greater.
When `k' is negative, `i' and `j' are reduced to @code{len(s) - 1} if
they are greater.  If `i' or `j' are omitted or @code{None}, they become
"end" values (which end depends on the sign of `k').  Note, `k' cannot be zero.
If `k' is @code{None}, it is treated like @code{1}.

@item 
Concatenating immutable sequences always results in a new object.  This
means that building up a sequence by repeated concatenation will have a
quadratic runtime cost in the total sequence length.  To get a linear
runtime cost, you must switch to one of the alternatives below:


@itemize *

@item 
if concatenating @ref{169,,str} objects, you can build a list and use
@ref{24b9,,str.join()} at the end or else write to an @ref{1124,,io.StringIO}
instance and retrieve its value when complete

@item 
if concatenating @ref{192,,bytes} objects, you can similarly use
@ref{24ba,,bytes.join()} or @ref{109f,,io.BytesIO}, or you can do in-place
concatenation with a @ref{343,,bytearray} object.  @ref{343,,bytearray}
objects are mutable and have an efficient overallocation mechanism

@item 
if concatenating @ref{60c,,tuple} objects, extend a @ref{24d,,list} instead

@item 
for other types, investigate the relevant class documentation
@end itemize

@item 
Some sequence types (such as @ref{b34,,range}) only support item sequences
that follow specific patterns, and hence don't support sequence
concatenation or repetition.

@item 
An @ref{1729,,IndexError} is raised if `i' is outside the sequence range.
@end enumerate

@subsubheading 序列方法


序列型別也支援以下方法：


@geindex count() (sequence 的方法)
@anchor{library/stdtypes list count}@anchor{15bd}@anchor{library/stdtypes sequence count}@anchor{228a}
@deffn {方法} sequence.count (value, /)

回傳 `sequence' 中 `value' 出現的總次數。
@end deffn


@geindex index() (sequence 的方法)
@anchor{library/stdtypes list index}@anchor{15bc}@anchor{library/stdtypes sequence index}@anchor{18da}
@deffn {方法} sequence.index (value[, start[, stop])

回傳 `sequence' 中 `value' 首次出現的索引。

當 `value' 不在 `sequence' 中時引發 @ref{2eb,,ValueError}。

The `start' or `stop' arguments allow for efficient searching
of subsections of the sequence, beginning at `start' and ending at `stop'.
This is roughly equivalent to @code{start + sequence[start:stop].index(value)},
only without copying any data.

@cartouche
@quotation 警示 
Not all sequence types support passing the `start' and `stop' arguments.
@end quotation
@end cartouche
@end deffn

@node 不可變序列型別,可變序列型別,Common Sequence Operations,Sequence Types --- list tuple range
@anchor{library/stdtypes immutable-sequence-types}@anchor{24bb}@anchor{library/stdtypes typesseq-immutable}@anchor{24bc}
@subsubsection 不可變序列型別


@geindex immutable（不可變）;sequence（序列）;type（型別）
@geindex object（物件）;tuple（元組）
@geindex built-in function（內建函式）;hash（雜湊）

The only operation that immutable sequence types generally implement that is
not also implemented by mutable sequence types is support for the @ref{7fa,,hash()}
built-in.

This support allows immutable sequences, such as @ref{60c,,tuple} instances, to
be used as @ref{183,,dict} keys and stored in @ref{184,,set} and @ref{7eb,,frozenset}
instances.

Attempting to hash an immutable sequence that contains unhashable values will
result in @ref{198,,TypeError}.

@node 可變序列型別,List（串列）<2>,不可變序列型別,Sequence Types --- list tuple range
@anchor{library/stdtypes mutable-sequence-types}@anchor{24bd}@anchor{library/stdtypes typesseq-mutable}@anchor{246b}
@subsubsection 可變序列型別


@geindex mutable（可變）;sequence（序列）;type（型別）
@geindex object（物件）;list（串列）
@geindex object（物件）;bytearray（位元組陣列）

The operations in the following table are defined on mutable sequence types.
The @ref{4ba,,collections.abc.MutableSequence} ABC is provided to make it
easier to correctly implement these operations on custom sequence types.

In the table `s' is an instance of a mutable sequence type, `t' is any
iterable object and `x' is an arbitrary object that meets any type
and value restrictions imposed by `s' (for example, @ref{343,,bytearray} only
accepts integers that meet the value restriction @code{0 <= x <= 255}).

@geindex operations on（操作於）;sequence（序列）;type（型別）
@geindex operations on（操作於）;list（串列）;type（型別）
@geindex subscript（下標）;assignment（賦值）
@geindex slice（切片）;assignment（賦值）
@geindex statement（陳述式）;del


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

運算

@tab

結果

@tab

註解

@item

@code{s[i] = x}

@tab

item `i' of `s' is replaced by
`x'

@tab

@item

@code{del s[i]}

@tab

移除 `s' 中的項目 `i'

@tab

@item

@code{s[i:j] = t}

@tab

slice of `s' from `i' to `j'
is replaced by the contents of
the 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

extends `s' with the
contents of `t' (for the
most part the same as
@code{s[len(s):len(s)] = t})

@tab

@item

@code{s *= n}

@tab

updates `s' with its contents
repeated `n' times

@tab

(2)

@end multitable


註解：


@enumerate 

@item 
If `k' is not equal to @code{1}, `t' must have the same length as the slice it is replacing.

@item 
The value `n' is an integer, or an object implementing
@ref{19e,,__index__()}.  Zero and negative values of `n' clear
the sequence.  Items in the sequence are not copied; they are referenced
multiple times, as explained for @code{s * n} under @ref{24b7,,Common Sequence Operations}.
@end enumerate

@subsubheading 可變序列方法


可變序列型別也支援以下方法：


@geindex append() (sequence 的方法)
@anchor{library/stdtypes bytearray append}@anchor{159d}@anchor{library/stdtypes sequence append}@anchor{2288}
@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{24be}@anchor{library/stdtypes sequence clear}@anchor{2289}
@deffn {方法} sequence.clear ()


在 3.3 版被加入.


移除 `sequence' 中的所有項目，這和 @code{del sequence[:]} 相同。
@end deffn


@geindex copy() (sequence 的方法)
@anchor{library/stdtypes bytearray copy}@anchor{24bf}@anchor{library/stdtypes sequence copy}@anchor{24c0}
@deffn {方法} sequence.copy ()


在 3.3 版被加入.


建立 `sequence' 的淺層複製，這和 @code{sequence[:]} 相同。

@cartouche
@quotation 提示 
The @code{copy()} method is not part of the
@ref{4ba,,MutableSequence} @ref{1115,,ABC},
but most concrete mutable sequence types provide it.
@end quotation
@end cartouche
@end deffn


@geindex extend() (sequence 的方法)
@anchor{library/stdtypes bytearray extend}@anchor{1925}@anchor{library/stdtypes sequence extend}@anchor{228b}
@deffn {方法} sequence.extend (iterable, /)

Extend `sequence' with the contents of `iterable'.
For the most part, this is the same as writing
@code{seq[len(seq):len(seq)] = iterable}.
@end deffn


@geindex insert() (sequence 的方法)
@anchor{library/stdtypes bytearray insert}@anchor{24c1}@anchor{library/stdtypes sequence insert}@anchor{228c}
@deffn {方法} sequence.insert (index, value, /)

Insert `value' into `sequence' at the given `index'.
This is equivalent to writing @code{sequence[index:index] = [value]}.
@end deffn


@geindex pop() (sequence 的方法)
@anchor{library/stdtypes bytearray pop}@anchor{159e}@anchor{library/stdtypes sequence pop}@anchor{228d}
@deffn {方法} sequence.pop (index=-1, /)

Retrieve the item at `index' and also removes it from `sequence'.
By default, the last item in `sequence' is removed and returned.
@end deffn


@geindex remove() (sequence 的方法)
@anchor{library/stdtypes bytearray remove}@anchor{24c2}@anchor{library/stdtypes sequence remove}@anchor{18db}
@deffn {方法} sequence.remove (value, /)

Remove the first item from `sequence' where @code{sequence[i] == value}.

當 `value' 不在 `sequence' 中時引發 @ref{2eb,,ValueError}。
@end deffn


@geindex reverse() (sequence 的方法)
@anchor{library/stdtypes bytearray reverse}@anchor{159f}@anchor{library/stdtypes sequence reverse}@anchor{228e}
@deffn {方法} sequence.reverse ()

Reverse the items of `sequence' in place.
This method maintains economy of space when reversing a large sequence.
To remind users that it operates by side-effect, it returns @code{None}.
@end deffn

@node List（串列）<2>,Tuples,可變序列型別,Sequence Types --- list tuple range
@anchor{library/stdtypes lists}@anchor{24c3}@anchor{library/stdtypes typesseq-list}@anchor{2482}
@subsubsection List（串列）


@geindex object（物件）;list（串列）

Lists are mutable sequences, typically used to store collections of
homogeneous items (where the precise degree of similarity will vary by
application).

@geindex list (內建類別)
@anchor{library/stdtypes list}@anchor{24d}
@deffn {類別} list (iterable=(), /)

Lists may be constructed in several ways:


@itemize *

@item 
Using a pair of square brackets to denote the empty list: @code{[]}

@item 
Using square brackets, separating items with commas: @code{[a]}, @code{[a, b, c]}

@item 
使用串列綜合運算式：@code{[x for x in iterable]}

@item 
使用型別建構函式：@code{list()} 或 @code{list(iterable)}
@end itemize

The constructor builds a list whose items are the same and in the same
order as `iterable''s items.  `iterable' may be either a sequence, a
container that supports iteration, or an iterator object.  If `iterable'
is already a list, a copy is made and returned, similar to @code{iterable[:]}.
For example, @code{list('abc')} returns @code{['a', 'b', 'c']} and
@code{list( (1, 2, 3) )} returns @code{[1, 2, 3]}.
If no argument is given, the constructor creates a new empty list, @code{[]}.

Many other operations also produce lists, including the @ref{dc2,,sorted()}
built-in.

Lists implement all of the @ref{24b7,,common} and
@ref{246b,,mutable} sequence operations. Lists also provide the
following additional method:

@geindex sort() (list 的方法)
@anchor{library/stdtypes list sort}@anchor{dc3}
@deffn {方法} sort (*, key=None, reverse=False)

This method sorts the list in place, using only @code{<} comparisons
between items. Exceptions are not suppressed - if any comparison operations
fail, the entire sort operation will fail (and the list will likely be left
in a partially modified state).

@ref{dc3,,sort()} accepts two arguments that can only be passed by keyword
(@ref{59f,,keyword-only arguments}):

`key' specifies a function of one argument that is used to extract a
comparison key from each list element (for example, @code{key=str.lower}).
The key corresponding to each item in the list is calculated once and
then used for the entire sorting process. The default value of @code{None}
means that list items are sorted directly without calculating a separate
key value.

The @ref{13db,,functools.cmp_to_key()} utility is available to convert a 2.x
style `cmp' function to a `key' function.

`reverse' is a boolean value.  If set to @code{True}, then the list elements
are sorted as if each comparison were reversed.

This method modifies the sequence in place for economy of space when
sorting a large sequence.  To remind users that it operates by side
effect, it does not return the sorted sequence (use @ref{dc2,,sorted()} to
explicitly request a new sorted list instance).

The @ref{dc3,,sort()} method is guaranteed to be stable.  A sort is stable if it
guarantees not to change the relative order of elements that compare equal
--- this is helpful for sorting in multiple passes (for example, sort by
department, then by salary grade).

For sorting examples and a brief sorting tutorial, see @ref{248a,,排序技法}.

`CPython 實作細節：' While a list is being sorted, the effect of attempting to mutate, or even
inspect, the list is undefined.  The C implementation of Python makes the
list appear empty for the duration, and raises @ref{2eb,,ValueError} if it can
detect that the list has been mutated during a sort.
@end deffn
@end deffn

@node Tuples,Ranges,List（串列）<2>,Sequence Types --- list tuple range
@anchor{library/stdtypes tuples}@anchor{24c4}@anchor{library/stdtypes typesseq-tuple}@anchor{23f2}
@subsubsection Tuples


@geindex object（物件）;tuple（元組）

Tuples are immutable sequences, typically used to store collections of
heterogeneous data (such as the 2-tuples produced by the @ref{1675,,enumerate()}
built-in). Tuples are also used for cases where an immutable sequence of
homogeneous data is needed (such as allowing storage in a @ref{184,,set} or
@ref{183,,dict} instance).

@geindex tuple (內建類別)
@anchor{library/stdtypes tuple}@anchor{60c}
@deffn {類別} tuple (iterable=(), /)

元組可以以多種方式建構：


@itemize *

@item 
使用一對圓括號表示空元組：@code{()}

@item 
使用末尾的逗號表示單元素元組：@code{a,} 或 @code{(a,)}

@item 
使用逗號分隔項目：@code{a, b, c} 或 @code{(a, b, c)}

@item 
Using the @ref{60c,,tuple()} built-in: @code{tuple()} or @code{tuple(iterable)}
@end itemize

The constructor builds a tuple whose items are the same and in the same
order as `iterable''s items.  `iterable' may be either a sequence, a
container that supports iteration, or an iterator object.  If `iterable'
is already a tuple, it is returned unchanged. For example,
@code{tuple('abc')} returns @code{('a', 'b', 'c')} and
@code{tuple( [1, 2, 3] )} returns @code{(1, 2, 3)}.
If no argument is given, the constructor creates a new empty tuple, @code{()}.

Note that it is actually the comma which makes a tuple, not the parentheses.
The parentheses are optional, except in the empty tuple case, or
when they are needed to avoid syntactic ambiguity. For example,
@code{f(a, b, c)} is a function call with three arguments, while
@code{f((a, b, c))} is a function call with a 3-tuple as the sole argument.

Tuples implement all of the @ref{24b7,,common} sequence
operations.
@end deffn

For heterogeneous collections of data where access by name is clearer than
access by index, @ref{4db,,collections.namedtuple()} may be a more appropriate
choice than a simple tuple object.

@node Ranges,,Tuples,Sequence Types --- list tuple range
@anchor{library/stdtypes ranges}@anchor{24c5}@anchor{library/stdtypes typesseq-range}@anchor{2488}
@subsubsection Ranges


@geindex object（物件）;range

The @ref{b34,,range} type represents an immutable sequence of numbers and is
commonly used for looping a specific number of times in @ref{348,,for}
loops.

@geindex range (內建類別)
@anchor{library/stdtypes range}@anchor{b34}
@deffn {類別} range (stop, /)

@deffnx {類別} range (start, stop, step=1, /)

The arguments to the range constructor must be integers (either built-in
@ref{19b,,int} or any object that implements the @ref{19e,,__index__()} special
method).  If the `step' argument is omitted, it defaults to @code{1}.
If the `start' argument is omitted, it defaults to @code{0}.
If `step' is zero, @ref{2eb,,ValueError} is raised.

For a positive `step', the contents of a range @code{r} are determined by the
formula @code{r[i] = start + step*i} where @code{i >= 0} and
@code{r[i] < stop}.

For a negative `step', the contents of the range are still determined by
the formula @code{r[i] = start + step*i}, but the constraints are @code{i >= 0}
and @code{r[i] > stop}.

A range object will be empty if @code{r[0]} does not meet the value
constraint. Ranges do support negative indices, but these are interpreted
as indexing from the end of the sequence determined by the positive
indices.

Ranges containing absolute values larger than @ref{13c6,,sys.maxsize} are
permitted but some features (such as @ref{839,,len()}) may raise
@ref{a78,,OverflowError}.

Range examples:

@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 implement all of the @ref{24b7,,common} sequence operations
except concatenation and repetition (due to the fact that range objects can
only represent sequences that follow a strict pattern and repetition and
concatenation will usually violate that pattern).

@geindex start (range 的屬性)
@anchor{library/stdtypes range start}@anchor{24c6}
@deffn {屬性} start

The value of the `start' parameter (or @code{0} if the parameter was
not supplied)
@end deffn

@geindex stop (range 的屬性)
@anchor{library/stdtypes range stop}@anchor{24c7}
@deffn {屬性} stop

The value of the `stop' parameter
@end deffn

@geindex step (range 的屬性)
@anchor{library/stdtypes range step}@anchor{24c8}
@deffn {屬性} step

The value of the `step' parameter (or @code{1} if the parameter was
not supplied)
@end deffn
@end deffn

The advantage of the @ref{b34,,range} type over a regular @ref{24d,,list} or
@ref{60c,,tuple} is that a @ref{b34,,range} object will always take the same
(small) amount of memory, no matter the size of the range it represents (as it
only stores the @code{start}, @code{stop} and @code{step} values, calculating individual
items and subranges as needed).

Range objects implement the @ref{13c5,,collections.abc.Sequence} ABC, and provide
features such as containment tests, element index lookup, slicing and
support for negative indices (see @ref{1ef6,,Sequence Types --- 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

Testing range objects for equality with @code{==} and @code{!=} compares
them as sequences.  That is, two range objects are considered equal if
they represent the same sequence of values.  (Note that two range
objects that compare equal might have different @ref{24c6,,start},
@ref{24c7,,stop} and @ref{24c8,,step} attributes, for example
@code{range(0) == range(2, 1, 3)} or @code{range(0, 3, 2) == range(0, 4, 2)}.)


在 3.2 版的變更: Implement the Sequence ABC.
Support slicing and negative indices.
Test @ref{19b,,int} objects for membership in constant time instead of
iterating through all items.



在 3.3 版的變更: Define '==' and '!=' to compare range objects based on the
sequence of values they define (instead of comparing based on
object identity).

Added the @ref{24c6,,start}, @ref{24c7,,stop} and @ref{24c8,,step}
attributes.



@subsubheading 也參考



@itemize *

@item 
The linspace recipe@footnote{https://code.activestate.com/recipes/579000-equally-spaced-numbers-linspace/}
shows how to implement a lazy version of range suitable for floating-point
applications.
@end itemize


@geindex string（字串）;text sequence type（文字序列型別）
@geindex str（內建類別）;（亦請見 string）
@geindex object（物件）;string（字串）

@node Text and Binary Sequence Type Methods Summary,Text Sequence Type --- str,Sequence Types --- list tuple range,內建型別
@anchor{library/stdtypes text-and-binary-sequence-type-methods-summary}@anchor{24c9}@anchor{library/stdtypes text-methods-summary}@anchor{24ca}
@subsection Text and Binary Sequence Type Methods Summary


The following table summarizes the text and binary sequence types methods by
category.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxx} {xx} {xx} {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx} {xx} {xx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

分類

@tab

@ref{169,,str} 方法

@tab

@tab

@tab

@tab

@ref{192,,bytes} 和 @ref{343,,bytearray} 方法

@tab

@tab

@tab

@item

格式化

@tab

@ref{82c,,str.format()}

@tab

@tab

@tab

@tab

@tab

@tab

@tab

@item

@ref{fd2,,str.format_map()}

@tab

@tab

@tab

@tab

@tab

@tab

@tab

@item

@ref{19a,,f-string（f 字串）}

@tab

@tab

@tab

@tab

@tab

@tab

@tab

@item

@ref{8d3,,printf-style String Formatting}

@tab

@tab

@tab

@tab

@ref{f7c,,printf-style Bytes Formatting}

@tab

@tab

@tab

@item

搜尋和取代

@tab

@ref{10a3,,str.find()}

@tab

@ref{10a4,,str.rfind()}

@tab

@tab

@tab

@ref{1af4,,bytes.find()}

@tab

@ref{1af5,,bytes.rfind()}

@tab

@tab

@item

@ref{1911,,str.index()}

@tab

@ref{1458,,str.rindex()}

@tab

@tab

@tab

@ref{24cb,,bytes.index()}

@tab

@ref{24cc,,bytes.rindex()}

@tab

@tab

@item

@ref{10c6,,str.startswith()}

@tab

@tab

@tab

@tab

@ref{24cd,,bytes.startswith()}

@tab

@tab

@tab

@item

@ref{10c7,,str.endswith()}

@tab

@tab

@tab

@tab

@ref{24ce,,bytes.endswith()}

@tab

@tab

@tab

@item

@ref{18dc,,str.count()}

@tab

@tab

@tab

@tab

@ref{18dd,,bytes.count()}

@tab

@tab

@tab

@item

@ref{4b3,,str.replace()}

@tab

@tab

@tab

@tab

@ref{24cf,,bytes.replace()}

@tab

@tab

@tab

@item

分割和連接

@tab

@ref{10a5,,str.split()}

@tab

@tab

@ref{1456,,str.rsplit()}

@tab

@tab

@ref{24d0,,bytes.split()}

@tab

@tab

@ref{24d1,,bytes.rsplit()}

@tab

@item

@ref{1457,,str.splitlines()}

@tab

@tab

@tab

@tab

@ref{24d2,,bytes.splitlines()}

@tab

@tab

@tab

@item

@ref{10a6,,str.partition()}

@tab

@tab

@tab

@tab

@ref{24d3,,bytes.partition()}

@tab

@tab

@tab

@item

@ref{1459,,str.rpartition()}

@tab

@tab

@tab

@tab

@ref{24d4,,bytes.rpartition()}

@tab

@tab

@tab

@item

@ref{24b9,,str.join()}

@tab

@tab

@tab

@tab

@ref{24ba,,bytes.join()}

@tab

@tab

@tab

@item

字串分類

@tab

@ref{24d5,,str.isalpha()}

@tab

@tab

@tab

@tab

@ref{24d6,,bytes.isalpha()}

@tab

@tab

@tab

@item

@ref{24d7,,str.isdecimal()}

@tab

@tab

@tab

@tab

@tab

@tab

@tab

@item

@ref{24d8,,str.isdigit()}

@tab

@tab

@tab

@tab

@ref{24d9,,bytes.isdigit()}

@tab

@tab

@tab

@item

@ref{24da,,str.isnumeric()}

@tab

@tab

@tab

@tab

@tab

@tab

@tab

@item

@ref{24db,,str.isalnum()}

@tab

@tab

@tab

@tab

@ref{24dc,,bytes.isalnum()}

@tab

@tab

@tab

@item

@ref{1c0f,,str.isidentifier()}

@tab

@tab

@tab

@tab

@tab

@tab

@tab

@item

@ref{24dd,,str.islower()}

@tab

@tab

@tab

@tab

@ref{24de,,bytes.islower()}

@tab

@tab

@tab

@item

@ref{24df,,str.isupper()}

@tab

@tab

@tab

@tab

@ref{24e0,,bytes.isupper()}

@tab

@tab

@tab

@item

@ref{24e1,,str.istitle()}

@tab

@tab

@tab

@tab

@ref{24e2,,bytes.istitle()}

@tab

@tab

@tab

@item

@ref{24e3,,str.isspace()}

@tab

@tab

@tab

@tab

@ref{24e4,,bytes.isspace()}

@tab

@tab

@tab

@item

@ref{fd3,,str.isprintable()}

@tab

@tab

@tab

@tab

@tab

@tab

@tab

@item

大小寫操作

@tab

@ref{1aa5,,str.lower()}

@tab

@tab

@tab

@tab

@ref{24e5,,bytes.lower()}

@tab

@tab

@tab

@item

@ref{24e6,,str.upper()}

@tab

@tab

@tab

@tab

@ref{24e7,,bytes.upper()}

@tab

@tab

@tab

@item

@ref{fd1,,str.casefold()}

@tab

@tab

@tab

@tab

@tab

@tab

@tab

@item

@ref{24e8,,str.capitalize()}

@tab

@tab

@tab

@tab

@ref{24e9,,bytes.capitalize()}

@tab

@tab

@tab

@item

@ref{24ea,,str.title()}

@tab

@tab

@tab

@tab

@ref{24eb,,bytes.title()}

@tab

@tab

@tab

@item

@ref{24ec,,str.swapcase()}

@tab

@tab

@tab

@tab

@ref{24ed,,bytes.swapcase()}

@tab

@tab

@tab

@item

填充和去除空白

@tab

@ref{1f29,,str.ljust()}

@tab

@tab

@ref{1f28,,str.rjust()}

@tab

@tab

@ref{24ee,,bytes.ljust()}

@tab

@tab

@ref{24ef,,bytes.rjust()}

@tab

@item

@ref{1f2a,,str.center()}

@tab

@tab

@tab

@tab

@ref{24f0,,bytes.center()}

@tab

@tab

@tab

@item

@ref{24f1,,str.expandtabs()}

@tab

@tab

@tab

@tab

@ref{24f2,,bytes.expandtabs()}

@tab

@tab

@tab

@item

@ref{16a3,,str.strip()}

@tab

@tab

@tab

@tab

@ref{24f3,,bytes.strip()}

@tab

@tab

@tab

@item

@ref{16a4,,str.lstrip()}

@tab

@tab

@tab

@ref{16a5,,str.rstrip()}

@tab

@ref{24f4,,bytes.lstrip()}

@tab

@tab

@tab

@ref{24f5,,bytes.rstrip()}

@item

翻譯和編碼

@tab

@ref{24f6,,str.translate()}

@tab

@tab

@tab

@tab

@ref{24f7,,bytes.translate()}

@tab

@tab

@tab

@item

@ref{fd4,,str.maketrans()}

@tab

@tab

@tab

@tab

@ref{1475,,bytes.maketrans()}

@tab

@tab

@tab

@item

@ref{ac9,,str.encode()}

@tab

@tab

@tab

@tab

@tab

@tab

@tab

@item

@tab

@tab

@tab

@tab

@ref{aca,,bytes.decode()}

@tab

@tab

@tab

@end multitable


@node Text Sequence Type --- str,Binary Sequence Types --- bytes bytearray memoryview,Text and Binary Sequence Type Methods Summary,內建型別
@anchor{library/stdtypes text-sequence-type-str}@anchor{24f8}@anchor{library/stdtypes textseq}@anchor{1ea8}
@subsection Text Sequence Type --- @code{str}


Textual data in Python is handled with @ref{169,,str} objects, or `strings'.
Strings are immutable
@ref{1ef6,,sequences} of Unicode code points.  String literals are
written in a variety of ways:


@itemize *

@item 
Single quotes: @code{'allows embedded "double" quotes'}

@item 
Double quotes: @code{"allows embedded 'single' quotes"}

@item 
Triple quoted: @code{'@w{'}'Three single quotes'@w{'}'}, @code{"""Three double quotes"""}
@end itemize

Triple quoted strings may span multiple lines - all associated whitespace will
be included in the string literal.

String literals that are part of a single expression and have only whitespace
between them will be implicitly converted to a single string literal. That
is, @code{("spam " "eggs") == "spam eggs"}.

See @ref{2163,,String and Bytes literals} for more about the various forms of string literal,
including supported @ref{680,,escape sequences}, and the @code{r} ("raw") prefix that
disables most escape sequence processing.

Strings may also be created from other objects using the @ref{169,,str}
constructor.

Since there is no separate "character" type, indexing a string produces
strings of length 1. That is, for a non-empty string `s', @code{s[0] == s[0:1]}.

@geindex object（物件）;io.StringIO

There is also no mutable string type, but @ref{24b9,,str.join()} or
@ref{1124,,io.StringIO} can be used to efficiently construct strings from
multiple fragments.


在 3.3 版的變更: For backwards compatibility with the Python 2 series, the @code{u} prefix is
once again permitted on string literals. It has no effect on the meaning
of string literals and cannot be combined with the @code{r} prefix.


@geindex string（字串）;str（內建類別）

@geindex str (內建類別)
@anchor{library/stdtypes str}@anchor{169}
@deffn {類別} str (*, encoding='utf-8', errors='strict')

@deffnx {類別} str (object)

@deffnx {類別} str (object, encoding, errors='strict')

@deffnx {類別} str (object, *, errors)

Return a @ref{1ea8,,string} version of `object'.  If `object' is not
provided, returns the empty string.  Otherwise, the behavior of @code{str()}
depends on whether `encoding' or `errors' is given, as follows.

If neither `encoding' nor `errors' is given, @code{str(object)} returns
@ref{829,,type(object).__str__(object)},
which is the "informal" or nicely
printable string representation of `object'.  For string objects, this is
the string itself.  If `object' does not have a @ref{829,,__str__()}
method, then @ref{169,,str()} falls back to returning
@ref{1c1,,repr(object)}.

@geindex buffer protocol（緩衝區協定）;str（內建類別）
@geindex bytes（位元組）;str（內建類別）

If at least one of `encoding' or `errors' is given, `object' should be a
@ref{193,,bytes-like object} (e.g. @ref{192,,bytes} or @ref{343,,bytearray}).  In
this case, if `object' is a @ref{192,,bytes} (or @ref{343,,bytearray}) object,
then @code{str(bytes, encoding, errors)} is equivalent to
@ref{aca,,bytes.decode(encoding@comma{} errors)}.  Otherwise, the bytes
object underlying the buffer object is obtained before calling
@ref{aca,,bytes.decode()}.  See @ref{246d,,Binary Sequence Types --- bytes@comma{} bytearray@comma{} memoryview} and
@ref{260,,緩衝協定 (Buffer Protocol)} for information on buffer objects.

Passing a @ref{192,,bytes} object to @ref{169,,str()} without the `encoding'
or `errors' arguments falls under the first case of returning the informal
string representation (see also the @ref{7f2,,-b} command-line option to
Python).  For example:

@example
>>> str(b'Zoot!')
"b'Zoot!'"
@end example

For more information on the @code{str} class and its methods, see
@ref{1ea8,,Text Sequence Type --- str} and the @ref{1ea9,,字串方法} section below.  To output
formatted strings, see the @ref{19a,,f-string（f 字串）} and @ref{1593,,格式化文字語法}
sections.  In addition, see the @ref{24f9,,文本處理 (Text Processing) 服務} section.
@end deffn

@geindex string（字串）;methods（方法）

@menu
* 字串方法:: 
* Formatted String Literals (f-strings): Formatted String Literals f-strings. 
* printf-style String Formatting:: 

@end menu

@node 字串方法,Formatted String Literals f-strings,,Text Sequence Type --- str
@anchor{library/stdtypes id5}@anchor{24fa}@anchor{library/stdtypes string-methods}@anchor{1ea9}
@subsubsection 字串方法


@geindex 模組;re

Strings implement all of the @ref{24b7,,common} sequence
operations, along with the additional methods described below.

Strings also support two styles of string formatting, one providing a large
degree of flexibility and customization (see @ref{82c,,str.format()},
@ref{1593,,格式化文字語法} and @ref{24fb,,自訂字串格式}) and the other based on C
@code{printf} style formatting that handles a narrower range of types and is
slightly harder to use correctly, but is often faster for the cases it can
handle (@ref{8d3,,printf-style String Formatting}).

The @ref{24fc,,文本處理 (Text Processing) 服務} section of the standard library covers a number of
other modules that provide various text related utilities (including regular
expression support in the @ref{be,,re} module).

@geindex capitalize() (str 的方法)
@anchor{library/stdtypes str capitalize}@anchor{24e8}
@deffn {方法} str.capitalize ()

Return a copy of the string with its first character capitalized and the
rest lowercased.


在 3.8 版的變更: The first character is now put into titlecase rather than uppercase.
This means that characters like digraphs will only have their first
letter capitalized, instead of the full character.

@end deffn

@geindex casefold() (str 的方法)
@anchor{library/stdtypes str casefold}@anchor{fd1}
@deffn {方法} str.casefold ()

Return a casefolded copy of the string. Casefolded strings may be used for
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{1aa5,,lower()} would do nothing to @code{'ß'}; @ref{fd1,,casefold()}
converts it to @code{"ss"}.

The casefolding algorithm is
described in section 3.13 'Default Case Folding' of the Unicode Standard@footnote{https://www.unicode.org/versions/Unicode16.0.0/core-spec/chapter-3/#G33992}.


在 3.3 版被加入.

@end deffn

@geindex center() (str 的方法)
@anchor{library/stdtypes str center}@anchor{1f2a}
@deffn {方法} str.center (width, fillchar=' ', /)

Return centered in a string of length `width'. Padding is done using the
specified `fillchar' (default is an ASCII space). The original string is
returned if `width' is less than or equal to @code{len(s)}.  For example:

@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{18dc}
@deffn {方法} str.count (sub[, start[, end]])

Return the number of non-overlapping occurrences of substring `sub' in the
range [`start', `end'].  Optional arguments `start' and `end' are
interpreted as in slice notation.

If `sub' is empty, returns the number of empty strings between characters
which is the length of the string plus one. For example:

@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{ac9}
@deffn {方法} str.encode (encoding='utf-8', errors='strict')

Return the string encoded to @ref{192,,bytes}.

`encoding' defaults to @code{'utf-8'};
see @ref{fb3,,標準編碼} for possible values.

`errors' controls how encoding errors are handled.
If @code{'strict'} (the default), a @ref{460,,UnicodeError} exception is raised.
Other possible values are @code{'ignore'},
@code{'replace'}, @code{'xmlcharrefreplace'}, @code{'backslashreplace'} and any
other name registered via @ref{168f,,codecs.register_error()}.
See @ref{1a9e,,Error Handlers} for details.

For performance reasons, the value of `errors' is not checked for validity
unless an encoding error actually occurs,
@ref{503,,Python 開發模式} is enabled
or a @ref{504,,debug build} is used.
For example:

@example
>>> encoded_str_to_bytes = 'Python'.encode()
>>> type(encoded_str_to_bytes)
<class 'bytes'>
>>> encoded_str_to_bytes
b'Python'
@end example


在 3.1 版的變更: 新增關鍵字引數的支援。



在 3.9 版的變更: The value of the `errors' argument is now checked in @ref{503,,Python 開發模式} and
in @ref{504,,debug mode}.

@end deffn

@geindex endswith() (str 的方法)
@anchor{library/stdtypes str endswith}@anchor{10c7}
@deffn {方法} str.endswith (suffix[, start[, end]])

Return @code{True} if the string ends with the specified `suffix', otherwise return
@code{False}.  `suffix' can also be a tuple of suffixes to look for.  With optional
`start', test beginning at that position.  With optional `end', stop comparing
at that position. Using `start' and `end' is equivalent to
@code{str[start:end].endswith(suffix)}. For example:

@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{10c6,,startswith()} 和 @ref{ac4,,removesuffix()}。
@end deffn

@geindex expandtabs() (str 的方法)
@anchor{library/stdtypes str expandtabs}@anchor{24f1}
@deffn {方法} str.expandtabs (tabsize=8)

Return a copy of the string where all tab characters are replaced by one or
more spaces, depending on the current column and the given tab size.  Tab
positions occur every `tabsize' characters (default is 8, giving tab
positions at columns 0, 8, 16 and so on).  To expand the string, the current
column is set to zero and the string is examined character by character.  If
the character is a tab (@code{\t}), one or more space characters are inserted
in the result until the current column is equal to the next tab position.
(The tab character itself is not copied.)  If the character is a newline
(@code{\n}) or return (@code{\r}), it is copied and the current column is reset to
zero.  Any other character is copied unchanged and the current column is
incremented by one regardless of how the character is represented when
printed. For example:

@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{10a3}
@deffn {方法} str.find (sub[, start[, end]])

Return the lowest index in the string where substring `sub' is found within
the slice @code{s[start:end]}.  Optional arguments `start' and `end' are
interpreted as in slice notation.  Return @code{-1} if `sub' is not found.
For example:

@example
>>> 'spam, spam, spam'.find('sp')
0
>>> 'spam, spam, spam'.find('sp', 5)
6
@end example

另請參閱 @ref{10a4,,rfind()} 和 @ref{1911,,index()}。

@cartouche
@quotation 備註 
The @ref{10a3,,find()} method should be used only if you need to know the
position of `sub'.  To check if `sub' is a substring or not, use the
@ref{349,,in} operator:

@example
>>> 'Py' in 'Python'
True
@end example
@end quotation
@end cartouche
@end deffn

@geindex format() (str 的方法)
@anchor{library/stdtypes str format}@anchor{82c}
@deffn {方法} str.format (*args, **kwargs)

Perform a string formatting operation.  The string on which this method is
called can contain literal text or replacement fields delimited by braces
@code{@{@}}.  Each replacement field contains either the numeric index of a
positional argument, or the name of a keyword argument.  Returns a copy of
the string where each replacement field is replaced with the string value of
the corresponding argument.

@example
>>> "The sum of 1 + 2 is @{0@}".format(1+2)
'The sum of 1 + 2 is 3'
@end example

See @ref{1593,,格式化文字語法} for a description of the various formatting options
that can be specified in format strings.

@cartouche
@quotation 備註 
When formatting a number (@ref{19b,,int}, @ref{196,,float}, @ref{197,,complex},
@ref{1fe,,decimal.Decimal} and subclasses) with the @code{n} type
(ex: @code{'@{:n@}'.format(1234)}), the function temporarily sets the
@code{LC_CTYPE} locale to the @code{LC_NUMERIC} locale to decode
@code{decimal_point} and @code{thousands_sep} fields of @code{localeconv()} 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.
@end quotation
@end cartouche


在 3.7 版的變更: When formatting a number with the @code{n} type, the function sets
temporarily the @code{LC_CTYPE} locale to the @code{LC_NUMERIC} locale in some
cases.

@end deffn

@geindex format_map() (str 的方法)
@anchor{library/stdtypes str format_map}@anchor{fd2}
@deffn {方法} str.format_map (mapping, /)

Similar to @code{str.format(**mapping)}, except that @code{mapping} is
used directly and not copied to a @ref{183,,dict}.  This is useful
if for example @code{mapping} is a dict subclass:

@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


在 3.2 版被加入.

@end deffn

@geindex index() (str 的方法)
@anchor{library/stdtypes str index}@anchor{1911}
@deffn {方法} str.index (sub[, start[, end]])

Like @ref{10a3,,find()}, but raise @ref{2eb,,ValueError} when the substring is
not found.
@end deffn

@geindex isalnum() (str 的方法)
@anchor{library/stdtypes str isalnum}@anchor{24db}
@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()}.
@end deffn

@geindex isalpha() (str 的方法)
@anchor{library/stdtypes str isalpha}@anchor{24d5}
@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/Unicode16.0.0/core-spec/chapter-4/#G91002}.
@end deffn

@geindex isascii() (str 的方法)
@anchor{library/stdtypes str isascii}@anchor{ce0}
@deffn {方法} str.isascii ()

Return @code{True} if the string is empty or all characters in the string are ASCII,
@code{False} otherwise.
ASCII characters have code points in the range U+0000-U+007F.


在 3.7 版被加入.

@end deffn

@geindex isdecimal() (str 的方法)
@anchor{library/stdtypes str isdecimal}@anchor{24d7}
@deffn {方法} str.isdecimal ()

Return @code{True} if all characters in the string are decimal
characters and there is at least one character, @code{False}
otherwise. Decimal characters are those that can be used to form
numbers in base 10, e.g. U+0660, ARABIC-INDIC DIGIT
ZERO.  Formally a decimal character is a character in the Unicode
General Category "Nd".
@end deffn

@geindex isdigit() (str 的方法)
@anchor{library/stdtypes str isdigit}@anchor{24d8}
@deffn {方法} str.isdigit ()

Return @code{True} if all characters in the string are digits and there is at least one
character, @code{False} otherwise.  Digits include decimal characters and digits that need
special handling, such as the compatibility superscript digits.
This covers digits which cannot be used to form numbers in base 10,
like the Kharosthi numbers.  Formally, a digit is a character that has the
property value Numeric_Type=Digit or Numeric_Type=Decimal.
@end deffn

@geindex isidentifier() (str 的方法)
@anchor{library/stdtypes str isidentifier}@anchor{1c0f}
@deffn {方法} str.isidentifier ()

Return @code{True} if the string is a valid identifier according to the language
definition, section @ref{2164,,Names (identifiers and keywords)}.

@ref{24fd,,keyword.iskeyword()} can be used to test whether string @code{s} is a reserved
identifier, such as @ref{164f,,def} and @ref{14d8,,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{24dd}
@deffn {方法} str.islower ()

Return @code{True} if all cased characters @footnote{
Cased characters are those with general category property being one of
"Lu" (Letter, uppercase), "Ll" (Letter, lowercase), or "Lt" (Letter, titlecase).
} in the string are lowercase and
there is at least one cased character, @code{False} otherwise.
@end deffn

@geindex isnumeric() (str 的方法)
@anchor{library/stdtypes str isnumeric}@anchor{24da}
@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.
@end deffn

@geindex isprintable() (str 的方法)
@anchor{library/stdtypes str isprintable}@anchor{fd3}
@deffn {方法} str.isprintable ()

Return @code{True} if all characters in the string are printable, @code{False} if it
contains at least one non-printable character.

Here "printable" means the character is suitable for @ref{1c1,,repr()} to use in
its output; "non-printable" means that @ref{1c1,,repr()} on built-in types will
hex-escape the character.  It has no bearing on the handling of strings
written to @ref{cc4,,sys.stdout} or @ref{b2a,,sys.stderr}.

The printable characters are those which in the Unicode character database
(see @ref{10b,,unicodedata}) have a general category in group Letter, Mark,
Number, Punctuation, or Symbol (L, M, N, P, or S); plus the ASCII space 0x20.
Nonprintable characters are those in group Separator or Other (Z or C),
except the ASCII space.
@end deffn

@geindex isspace() (str 的方法)
@anchor{library/stdtypes str isspace}@anchor{24e3}
@deffn {方法} str.isspace ()

Return @code{True} if there are only whitespace characters in the string and there is
at least one character, @code{False} otherwise.

A character is `whitespace' if in the Unicode character database
(see @ref{10b,,unicodedata}), either its general category is @code{Zs}
("Separator, space"), or its bidirectional class is one of @code{WS},
@code{B}, or @code{S}.
@end deffn

@geindex istitle() (str 的方法)
@anchor{library/stdtypes str istitle}@anchor{24e1}
@deffn {方法} str.istitle ()

Return @code{True} if the string is a titlecased string and there is at least one
character, for example uppercase characters may only follow uncased characters
and lowercase characters only cased ones.  Return @code{False} otherwise.

舉例來說：

@example
>>> 'Spam, Spam, Spam'.istitle()
True
>>> 'spam, spam, spam'.istitle()
False
>>> 'SPAM, SPAM, SPAM'.istitle()
False
@end example

另請參閱 @ref{24ea,,title()}。
@end deffn

@geindex isupper() (str 的方法)
@anchor{library/stdtypes str isupper}@anchor{24df}
@deffn {方法} str.isupper ()

Return @code{True} if all cased characters @footnote{
Cased characters are those with general category property being one of
"Lu" (Letter, uppercase), "Ll" (Letter, lowercase), or "Lt" (Letter, titlecase).
} in the string are uppercase and
there is at least one cased character, @code{False} otherwise.

@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{24fe}@anchor{library/stdtypes str join}@anchor{24b9}
@deffn {方法} str.join (iterable, /)

Return a string which is the concatenation of the strings in `iterable'.
A @ref{198,,TypeError} will be raised if there are any non-string values in
`iterable', including @ref{192,,bytes} objects.  The separator between
elements is the string providing this method.
@end deffn

@geindex ljust() (str 的方法)
@anchor{library/stdtypes str ljust}@anchor{1f29}
@deffn {方法} str.ljust (width, fillchar=' ', /)

Return the string left justified in a string of length `width'. Padding is
done using the specified `fillchar' (default is an ASCII space). The
original string is returned if `width' is less than or equal to @code{len(s)}.
@end deffn

@geindex lower() (str 的方法)
@anchor{library/stdtypes str lower}@anchor{1aa5}
@deffn {方法} str.lower ()

Return a copy of the string with all the cased characters @footnote{
Cased characters are those with general category property being one of
"Lu" (Letter, uppercase), "Ll" (Letter, lowercase), or "Lt" (Letter, titlecase).
} converted to
lowercase.

The lowercasing algorithm used is
described in section 3.13 'Default Case Folding' of the Unicode Standard@footnote{https://www.unicode.org/versions/Unicode16.0.0/core-spec/chapter-3/#G33992}.
@end deffn

@geindex lstrip() (str 的方法)
@anchor{library/stdtypes str lstrip}@anchor{16a4}
@deffn {方法} str.lstrip (chars=None, /)

Return a copy of the string with leading 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; rather, all combinations of its values are stripped:

@example
>>> '   spacious   '.lstrip()
'spacious   '
>>> 'www.example.com'.lstrip('cmowz.')
'example.com'
@end example

See @ref{ac3,,str.removeprefix()} for a method that will remove a single prefix
string rather than all of a set of characters.  For example:

@example
>>> 'Arthur: three!'.lstrip('Arthur: ')
'ee!'
>>> 'Arthur: three!'.removeprefix('Arthur: ')
'three!'
@end example
@end deffn

@geindex maketrans() (str 的靜態方法)
@anchor{library/stdtypes str maketrans}@anchor{fd4}
@deffn {方法} static str.maketrans (dict, /)

@deffnx {方法} static str.maketrans (from, to, remove='@w{'}, /)

This static method returns a translation table usable for @ref{24f6,,str.translate()}.

If there is only one argument, it must be a dictionary mapping Unicode
ordinals (integers) or characters (strings of length 1) to Unicode ordinals,
strings (of arbitrary lengths) or @code{None}.  Character keys will then be
converted to ordinals.

If there are two arguments, they must be strings of equal length, and in the
resulting dictionary, each character in `from' will be mapped to the character at
the same position in `to'.  If there is a third argument, it must be a string,
whose characters will be mapped to @code{None} in the result.
@end deffn

@geindex partition() (str 的方法)
@anchor{library/stdtypes str partition}@anchor{10a6}
@deffn {方法} str.partition (sep, /)

Split the 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.
@end deffn

@geindex removeprefix() (str 的方法)
@anchor{library/stdtypes str removeprefix}@anchor{ac3}
@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


在 3.9 版被加入.

@end deffn

@geindex removesuffix() (str 的方法)
@anchor{library/stdtypes str removesuffix}@anchor{ac4}
@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


在 3.9 版被加入.

@end deffn

@geindex replace() (str 的方法)
@anchor{library/stdtypes str replace}@anchor{4b3}
@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.


在 3.13 版的變更: `count' 現在作為關鍵字引數被支援。

@end deffn

@geindex rfind() (str 的方法)
@anchor{library/stdtypes str rfind}@anchor{10a4}
@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.
@end deffn

@geindex rindex() (str 的方法)
@anchor{library/stdtypes str rindex}@anchor{1458}
@deffn {方法} str.rindex (sub[, start[, end]])

Like @ref{10a4,,rfind()} but raises @ref{2eb,,ValueError} when the substring `sub' is not
found.
@end deffn

@geindex rjust() (str 的方法)
@anchor{library/stdtypes str rjust}@anchor{1f28}
@deffn {方法} str.rjust (width, fillchar=' ', /)

Return the string right justified in a string of length `width'. Padding is
done using the specified `fillchar' (default is an ASCII space). The
original string is returned if `width' is less than or equal to @code{len(s)}.
@end deffn

@geindex rpartition() (str 的方法)
@anchor{library/stdtypes str rpartition}@anchor{1459}
@deffn {方法} str.rpartition (sep, /)

Split the string at the last 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
two empty strings, followed by the string itself.
@end deffn

@geindex rsplit() (str 的方法)
@anchor{library/stdtypes str rsplit}@anchor{1456}
@deffn {方法} str.rsplit (sep=None, maxsplit=-1)

Return a list of the words in the string, using `sep' as the delimiter string.
If `maxsplit' is given, at most `maxsplit' splits are done, the `rightmost'
ones.  If `sep' is not specified or @code{None}, any whitespace string is a
separator.  Except for splitting from the right, @ref{1456,,rsplit()} behaves like
@ref{10a5,,split()} which is described in detail below.
@end deffn

@geindex rstrip() (str 的方法)
@anchor{library/stdtypes str rstrip}@anchor{16a5}
@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:

@example
>>> '   spacious   '.rstrip()
'   spacious'
>>> 'mississippi'.rstrip('ipz')
'mississ'
@end example

See @ref{ac4,,str.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
@end deffn

@geindex split() (str 的方法)
@anchor{library/stdtypes str split}@anchor{10a5}
@deffn {方法} str.split (sep=None, maxsplit=-1)

Return a list of the words in the string, using `sep' as the delimiter
string.  If `maxsplit' is given, at most `maxsplit' splits are done (thus,
the list will have at most @code{maxsplit+1} elements).  If `maxsplit' is not
specified or @code{-1}, then there is no limit on the number of splits
(all possible splits are made).

If `sep' is given, consecutive delimiters are not grouped together and are
deemed to delimit empty strings (for example, @code{'1,,2'.split(',')} returns
@code{['1', '@w{'}, '2']}).  The `sep' argument may consist of multiple characters
as a single delimiter (to split with multiple delimiters, use
@ref{59c,,re.split()}). Splitting an empty string with a specified separator
returns @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

If `sep' is not specified or is @code{None}, a different splitting algorithm is
applied: runs of consecutive whitespace are regarded as a single separator,
and the result will contain no empty strings at the start or end if the
string has leading or trailing whitespace.  Consequently, splitting an empty
string or a string consisting of just whitespace with a @code{None} separator
returns @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

If `sep' is not specified or is @code{None} and  `maxsplit' is @code{0}, only
leading runs of consecutive whitespace are considered.

舉例來說：

@example
>>> "".split(None, 0)
[]
>>> "   ".split(None, 0)
[]
>>> "   foo   ".split(maxsplit=0)
['foo   ']
@end example
@end deffn

@geindex universal newlines;str.splitlines 方法

@geindex splitlines() (str 的方法)
@anchor{library/stdtypes str splitlines}@anchor{1457}
@deffn {方法} str.splitlines (keepends=False)

Return a list of the lines in the string, breaking at line boundaries.  Line
breaks are not included in the resulting list unless `keepends' is given and
true.

This method splits on the following line boundaries.  In particular, the
boundaries are a superset of @ref{f30,,universal newlines}.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Representation

@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} 或 @code{\x0b}

@tab

Line Tabulation

@item

@code{\f} 或 @code{\x0c}

@tab

Form Feed

@item

@code{\x1c}

@tab

File Separator

@item

@code{\x1d}

@tab

Group Separator

@item

@code{\x1e}

@tab

Record Separator

@item

@code{\x85}

@tab

Next Line (C1 Control Code)

@item

@code{\u2028}

@tab

Line Separator

@item

@code{\u2029}

@tab

Paragraph Separator

@end multitable



在 3.2 版的變更: @code{\v} and @code{\f} added to list of line boundaries.


舉例來說：

@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

Unlike @ref{10a5,,split()} when a delimiter string `sep' is given, this
method returns an empty list for the empty string, and a terminal line
break does not result in an extra line:

@example
>>> "".splitlines()
[]
>>> "One line\n".splitlines()
['One line']
@end example

For comparison, @code{split('\n')} gives:

@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{10c6}
@deffn {方法} str.startswith (prefix[, start[, end]])

Return @code{True} if string starts with the `prefix', otherwise return @code{False}.
`prefix' can also be a tuple of prefixes to look for.  With optional `start',
test string beginning at that position.  With optional `end', stop comparing
string at that position.
@end deffn

@geindex strip() (str 的方法)
@anchor{library/stdtypes str strip}@anchor{16a3}
@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.
For example:

@example
>>> comment_string = '#....... Section 3.2.1 Issue #32 .......'
>>> comment_string.strip('.#! ')
'Section 3.2.1 Issue #32'
@end example
@end deffn

@geindex swapcase() (str 的方法)
@anchor{library/stdtypes str swapcase}@anchor{24ec}
@deffn {方法} str.swapcase ()

Return a copy of the string with uppercase characters converted to lowercase and
vice versa. Note that it is not necessarily true that
@code{s.swapcase().swapcase() == s}.
@end deffn

@geindex title() (str 的方法)
@anchor{library/stdtypes str title}@anchor{24ea}
@deffn {方法} str.title ()

Return a titlecased version of the string where words start with an uppercase
character and the remaining characters are lowercase.

舉例來說：

@example
>>> 'Hello world'.title()
'Hello World'
@end example

The algorithm uses a simple language-independent definition of a word as
groups of consecutive letters.  The definition works in many contexts but
it means that apostrophes in contractions and possessives form word
boundaries, which may not be the desired result:

@example
>>> "they're bill's friends from the UK".title()
"They'Re Bill'S Friends From The Uk"
@end example

The @ref{24ff,,string.capwords()} function does not have this problem, as it
splits words on spaces only.

Alternatively, a workaround for apostrophes can be constructed using regular
expressions:

@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{24e1,,istitle()}。
@end deffn

@geindex translate() (str 的方法)
@anchor{library/stdtypes str translate}@anchor{24f6}
@deffn {方法} str.translate (table, /)

Return a copy of the string in which each character has been mapped through
the given translation table.  The table must be an object that implements
indexing via @ref{582,,__getitem__()}, typically a @ref{13bc,,mapping} or
@ref{70f,,sequence}.  When indexed by a Unicode ordinal (an integer), the
table object can do any of the following: return a Unicode ordinal or a
string, to map the character to one or more other characters; return
@code{None}, to delete the character from the return string; or raise a
@ref{2500,,LookupError} exception, to map the character to itself.

You can use @ref{fd4,,str.maketrans()} to create a translation map from
character-to-character mappings in different formats.

See also the @ref{1c,,codecs} module for a more flexible approach to custom
character mappings.
@end deffn

@geindex upper() (str 的方法)
@anchor{library/stdtypes str upper}@anchor{24e6}
@deffn {方法} str.upper ()

Return a copy of the string with all the cased characters @footnote{
Cased characters are those with general category property being one of
"Lu" (Letter, uppercase), "Ll" (Letter, lowercase), or "Lt" (Letter, titlecase).
} converted to
uppercase.  Note that @code{s.upper().isupper()} might be @code{False} if @code{s}
contains uncased characters or if the Unicode category of the resulting
character(s) is not "Lu" (Letter, uppercase), but e.g. "Lt" (Letter,
titlecase).

The uppercasing algorithm used is
described in section 3.13 'Default Case Folding' of the Unicode Standard@footnote{https://www.unicode.org/versions/Unicode16.0.0/core-spec/chapter-3/#G33992}.
@end deffn

@geindex zfill() (str 的方法)
@anchor{library/stdtypes str zfill}@anchor{16a6}
@deffn {方法} str.zfill (width, /)

Return a copy of the string left filled with ASCII @code{'0'} digits to
make a string of length `width'. A leading sign prefix (@code{'+'}/@code{'-'})
is handled by inserting the padding `after' the sign character rather
than before. The original string is returned if `width' is less than
or equal to @code{len(s)}.

舉例來說：

@example
>>> "42".zfill(5)
'00042'
>>> "-42".zfill(5)
'-0042'
@end example
@end deffn

@geindex ! formatted string literals（! 格式化字串常數）
@geindex formatted string literals（格式化字串常數）
@geindex ! f-string（! f 字串）
@geindex f-string（f 字串）
@geindex fstring（f 字串）
@geindex interpolated string literal（插值字串常數）
@geindex string（字串）;formatted literal（格式化常數）
@geindex string（字串）;interpolated literal（插值常數）
@geindex @{@} （花括號）;於格式化字串常數中
@geindex ! （驚嘆號）;於格式化字串常數中
@geindex ; （冒號）;於格式化字串常數中
@geindex = （等號）;for help in debugging using string literals

@node Formatted String Literals f-strings,printf-style String Formatting,字串方法,Text Sequence Type --- str
@anchor{library/stdtypes formatted-string-literals-f-strings}@anchor{2501}
@subsubsection Formatted String Literals (f-strings)



在 3.6 版被加入.



在 3.7 版的變更: The @ref{18d,,await} and @ref{c98,,async for} can be used in expressions
within f-strings.



在 3.8 版的變更: Added the debugging operator (@code{=})



在 3.12 版的變更: Many restrictions on expressions within f-strings have been removed.
Notably, nested strings, comments, and backslashes are now permitted.


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 arbitrary Python expressions
within `replacement fields', which are delimited by curly brackets (@code{@{@}}).
These expressions are evaluated at runtime, similarly to @ref{82c,,str.format()},
and are converted into regular @ref{169,,str} objects.
For example:

@example
>>> who = 'nobody'
>>> nationality = 'Spanish'
>>> f'@{who.title()@} expects the @{nationality@} Inquisition!'
'Nobody expects the Spanish Inquisition!'
@end example

It is also possible to use a multi line f-string:

@example
>>> f'@w{'}'This is a string
... on two lines'@w{'}'
'This is a string\non two lines'
@end example

A single opening curly bracket, @code{'@{'}, marks a `replacement field' that
can contain any Python expression:

@example
>>> nationality = 'Spanish'
>>> f'The @{nationality@} Inquisition!'
'The Spanish Inquisition!'
@end example

To include a literal @code{@{} or @code{@}}, use a double bracket:

@example
>>> x = 42
>>> f'@{@{x@}@} is @{x@}'
'@{x@} is 42'
@end example

Functions can also be used, and @ref{1593,,format specifiers}:

@example
>>> from math import sqrt
>>> f'√2 \N@{ALMOST EQUAL TO@} @{sqrt(2):.5f@}'
'√2 ≈ 1.41421'
@end example

Any non-string expression is converted using @ref{169,,str()}, by default:

@example
>>> from fractions import Fraction
>>> f'@{Fraction(1, 3)@}'
'1/3'
@end example

To use an explicit conversion, use the @code{!} (exclamation mark) operator,
followed by any of the valid formats, which are:


@multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxx} 
@headitem

Conversion

@tab

含義

@item

@code{!a}

@tab

@ref{15dd,,ascii()}

@item

@code{!r}

@tab

@ref{1c1,,repr()}

@item

@code{!s}

@tab

@ref{169,,str()}

@end multitable


舉例來說：

@example
>>> from fractions import Fraction
>>> f'@{Fraction(1, 3)!s@}'
'1/3'
>>> f'@{Fraction(1, 3)!r@}'
'Fraction(1, 3)'
>>> question = '¿Dónde está el Presidente?'
>>> print(f'@{question!a@}')
'\xbfD\xf3nde est\xe1 el Presidente?'
@end example

While debugging it may be helpful to see both the expression and its value,
by using the equals sign (@code{=}) after the expression.
This preserves spaces within the brackets, and can be used with a converter.
By default, the debugging operator uses the @ref{1c1,,repr()} (@code{!r}) conversion.
For example:

@example
>>> from fractions import Fraction
>>> calculation = Fraction(1, 3)
>>> f'@{calculation=@}'
'calculation=Fraction(1, 3)'
>>> f'@{calculation = @}'
'calculation = Fraction(1, 3)'
>>> f'@{calculation = !s@}'
'calculation = 1/3'
@end example

Once the output has been evaluated, it can be formatted using a
@ref{1593,,format specifier} following a colon (@code{':'}).
After the expression has been evaluated, and possibly converted to a string,
the @code{__format__()} method of the result is called with the format specifier,
or the empty string if no format specifier is given.
The formatted result is then used as the final value for the replacement field.
For example:

@example
>>> from fractions import Fraction
>>> f'@{Fraction(1, 7):.6f@}'
'0.142857'
>>> f'@{Fraction(1, 7):_^+10@}'
'___+1/7___'
@end example

@node printf-style String Formatting,,Formatted String Literals f-strings,Text Sequence Type --- str
@anchor{library/stdtypes old-string-formatting}@anchor{8d3}@anchor{library/stdtypes printf-style-string-formatting}@anchor{2502}
@subsubsection @code{printf}-style String Formatting


@geindex formatting（格式化）、字串 (%)
@geindex interpolation（插值）、字串 (%)
@geindex string（字串）;formatting（格式化）、printf
@geindex string（字串）;interpolation（插值）、printf
@geindex printf 風格格式化
@geindex sprintf 風格格式化
@geindex % （百分號）;printf 風格格式化

@cartouche
@quotation 備註 
The formatting operations described here exhibit a variety of quirks that
lead to a number of common errors (such as failing to display tuples and
dictionaries correctly).

Using @ref{19a,,formatted string literals}, the @ref{82c,,str.format()}
interface, or @ref{890,,string.Template} may help avoid these errors.
Each of these alternatives provides their own trade-offs and benefits of
simplicity, flexibility, and/or extensibility.
@end quotation
@end cartouche

String objects have one unique built-in operation: the @code{%} operator (modulo).
This is also known as the string `formatting' or `interpolation' operator.
Given @code{format % values} (where `format' is a string), @code{%} conversion
specifications in `format' are replaced with zero or more elements of `values'.
The effect is similar to using the @code{sprintf()} function in the C language.
For example:

@example
>>> print('%s has %d quote types.' % ('Python', 2))
Python has 2 quote types.
@end example

If `format' requires a single argument, `values' may be a single non-tuple
object. @footnote{
To format only a tuple you should therefore provide a singleton tuple whose only
element is the tuple to be formatted.
}  Otherwise, `values' must be a tuple with exactly the number of
items specified by the format string, or a single mapping object (for example, a
dictionary).

@geindex () （圓括號）;於 printf 風格格式化
@geindex * （星號）;於 printf 風格格式化
@geindex . （點）;於 printf 風格格式化

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 
Mapping key (optional), consisting of a parenthesised sequence of characters
(for example, @code{(somename)}).

@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 read from the next element of the tuple in `values', 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 read from the next
element of the tuple in `values', and the value to convert comes after the
precision.

@item 
Length modifier (optional).

@item 
Conversion type.
@end enumerate

When the right argument is a dictionary (or other mapping type), then the
formats in the string `must' include a parenthesised mapping key into that
dictionary inserted immediately after the @code{'%'} character. The mapping key
selects the value to be formatted from the mapping.  For example:

@example
>>> print('%(language)s has %(number)03d quote types.' %
...       @{'language': "Python", "number": 2@})
Python has 002 quote types.
@end example

In this case no @code{*} specifiers may occur in a format (since they require a
sequential parameter list).

The conversion flag characters are:

@geindex # （井字號）;於 printf 風格格式化
@geindex - （減號）;於 printf 風格格式化
@geindex + （加號）;於 printf 風格格式化
@geindex space（空白）;於 printf 風格格式化


@multitable {xxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Flag

@tab

含義

@item

@code{'#'}

@tab

The value conversion will use the "alternate form" (where defined
below).

@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'}
conversion if both are given).

@item

@code{' '}

@tab

(a space) A blank should be left before a positive number (or empty
string) produced by a signed conversion.

@item

@code{'+'}

@tab

A sign character (@code{'+'} or @code{'-'}) will precede the conversion
(overrides a "space" flag).

@end multitable


A length modifier (@code{h}, @code{l}, or @code{L}) may be present, but is ignored as it
is not necessary for Python -- so e.g. @code{%ld} is identical to @code{%d}.

The conversion types are:


@multitable {xxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxx} 
@headitem

Conversion

@tab

含義

@tab

註解

@item

@code{'d'}

@tab

Signed integer decimal.

@tab

@item

@code{'i'}

@tab

Signed integer decimal.

@tab

@item

@code{'o'}

@tab

Signed octal value.

@tab

(1)

@item

@code{'u'}

@tab

Obsolete type -- it is identical to @code{'d'}.

@tab

(6)

@item

@code{'x'}

@tab

Signed hexadecimal (lowercase).

@tab

(2)

@item

@code{'X'}

@tab

Signed hexadecimal (uppercase).

@tab

(2)

@item

@code{'e'}

@tab

Floating-point exponential format (lowercase).

@tab

(3)

@item

@code{'E'}

@tab

Floating-point exponential format (uppercase).

@tab

(3)

@item

@code{'f'}

@tab

Floating-point decimal format.

@tab

(3)

@item

@code{'F'}

@tab

Floating-point decimal format.

@tab

(3)

@item

@code{'g'}

@tab

Floating-point format. Uses lowercase exponential
format if exponent is less than -4 or not less than
precision, decimal format otherwise.

@tab

(4)

@item

@code{'G'}

@tab

Floating-point format. Uses uppercase exponential
format if exponent is less than -4 or not less than
precision, decimal format otherwise.

@tab

(4)

@item

@code{'c'}

@tab

Single character (accepts integer or single
character string).

@tab

@item

@code{'r'}

@tab

String (converts any Python object using
@ref{1c1,,repr()}).

@tab

(5)

@item

@code{'s'}

@tab

String (converts any Python object using
@ref{169,,str()}).

@tab

(5)

@item

@code{'a'}

@tab

String (converts any Python object using
@ref{15dd,,ascii()}).

@tab

(5)

@item

@code{'%'}

@tab

No argument is converted, results in a @code{'%'}
character in the result.

@tab

@end multitable


註解：


@enumerate 

@item 
The alternate form causes a leading octal specifier (@code{'0o'}) to be
inserted before the first digit.

@item 
The alternate form causes a leading @code{'0x'} or @code{'0X'} (depending on whether
the @code{'x'} or @code{'X'} format was used) to be inserted before the first digit.

@item 
The alternate form causes the result to always contain a decimal point, even if
no digits follow it.

The precision determines the number of digits after the decimal point and
defaults to 6.

@item 
The alternate form causes the result to always contain a decimal point, and
trailing zeroes are not removed as they would otherwise be.

The precision determines the number of significant digits before and after the
decimal point and defaults to 6.

@item 
If precision is @code{N}, the output is truncated to @code{N} characters.

@item 
參閱 
@geindex Python Enhancement Proposals; PEP 237
PEP 237@footnote{https://peps.python.org/pep-0237/}。
@end enumerate

Since Python strings have an explicit length, @code{%s} conversions do not assume
that @code{'\0'} is the end of the string.

@c XXX Examples?


在 3.1 版的變更: @code{%f} conversions for numbers whose absolute value is over 1e50 are no
longer replaced by @code{%g} conversions.


@geindex buffer protocol（緩衝區協定）;binary sequence types（二進位序列型別）

@node Binary Sequence Types --- bytes bytearray memoryview,Set Types --- set frozenset,Text Sequence Type --- str,內建型別
@anchor{library/stdtypes binary-sequence-types-bytes-bytearray-memoryview}@anchor{2503}@anchor{library/stdtypes binaryseq}@anchor{246d}
@subsection Binary Sequence Types --- @code{bytes}, @code{bytearray}, @code{memoryview}


@geindex object（物件）;bytes（位元組）
@geindex object（物件）;bytearray（位元組陣列）
@geindex object（物件）;memoryview（記憶體視圖）
@geindex 模組;array（陣列）

The core built-in types for manipulating binary data are @ref{192,,bytes} and
@ref{343,,bytearray}. They are supported by @ref{165,,memoryview} which uses
the @ref{260,,buffer protocol} to access the memory of other
binary objects without needing to make a copy.

The @ref{8,,array} module supports efficient storage of basic data types like
32-bit integers and IEEE754 double-precision floating values.

@menu
* Bytes Objects:: 
* Bytearray 物件:: 
* Bytes 和 Bytearray 的操作:: 
* printf-style Bytes Formatting:: 
* Memory Views:: 

@end menu

@node Bytes Objects,Bytearray 物件,,Binary Sequence Types --- bytes bytearray memoryview
@anchor{library/stdtypes bytes-objects}@anchor{2504}@anchor{library/stdtypes typebytes}@anchor{246f}
@subsubsection Bytes Objects


@geindex object（物件）;bytes（位元組）

Bytes objects are immutable sequences of single bytes. Since many major
binary protocols are based on the ASCII text encoding, bytes objects offer
several methods that are only valid when working with ASCII compatible
data and are closely related to string objects in a variety of other ways.

@geindex bytes (內建類別)
@anchor{library/stdtypes bytes}@anchor{192}
@deffn {類別} bytes (source=b'@w{'})

@deffnx {類別} bytes (source, encoding, errors='strict')

Firstly, the syntax for bytes literals is largely the same as that for string
literals, except that a @code{b} prefix is added:


@itemize *

@item 
Single quotes: @code{b'still allows embedded "double" quotes'}

@item 
Double quotes: @code{b"still allows embedded 'single' quotes"}

@item 
Triple quoted: @code{b'@w{'}'3 single quotes'@w{'}'}, @code{b"""3 double quotes"""}
@end itemize

Only ASCII characters are permitted in bytes literals (regardless of the
declared source code encoding). Any binary values over 127 must be entered
into bytes literals using the appropriate escape sequence.

As with string literals, bytes literals may also use a @code{r} prefix to disable
processing of escape sequences. See @ref{2163,,String and Bytes literals} for more about the various
forms of bytes literal, including supported escape sequences.

While bytes literals and representations are based on ASCII text, bytes
objects actually behave like immutable sequences of integers, with each
value in the sequence restricted such that @code{0 <= x < 256} (attempts to
violate this restriction will trigger @ref{2eb,,ValueError}). This is done
deliberately to emphasise that while many binary formats include ASCII based
elements and can be usefully manipulated with some text-oriented algorithms,
this is not generally the case for arbitrary binary data (blindly applying
text processing algorithms to binary data formats that are not ASCII
compatible will usually lead to data corruption).

In addition to the literal forms, bytes objects can be created in a number of
other ways:


@itemize *

@item 
A zero-filled bytes object of a specified length: @code{bytes(10)}

@item 
From an iterable of integers: @code{bytes(range(20))}

@item 
Copying existing binary data via the buffer protocol:  @code{bytes(obj)}
@end itemize

另見內建的 @ref{1d61,,bytes}。

Since 2 hexadecimal digits correspond precisely to a single byte, hexadecimal
numbers are a commonly used format for describing binary data. Accordingly,
the bytes type has an additional class method to read data in that format:

@geindex fromhex() (bytes 的類別方法)
@anchor{library/stdtypes bytes fromhex}@anchor{190}
@deffn {方法} classmethod fromhex (string, /)

This @ref{192,,bytes} class method returns a bytes object, decoding the
given string object.  The string must contain two hexadecimal digits per
byte, with ASCII whitespace being ignored.

@example
>>> bytes.fromhex('2Ef0 F1f2  ')
b'.\xf0\xf1\xf2'
@end example


在 3.7 版的變更: @ref{190,,bytes.fromhex()} now skips all ASCII whitespace in the string,
not just spaces.



在 3.14 版的變更: @ref{190,,bytes.fromhex()} now accepts ASCII @ref{192,,bytes} and
@ref{193,,bytes-like objects} as input.

@end deffn

A reverse conversion function exists to transform a bytes object into its
hexadecimal representation.

@geindex hex() (bytes 的方法)
@anchor{library/stdtypes bytes hex}@anchor{f60}
@deffn {方法} hex (*, bytes_per_sep=1)

@deffnx {方法} hex (sep, bytes_per_sep=1)

Return a string object containing two hexadecimal digits for each
byte in the instance.

@example
>>> b'\xf0\xf1\xf2'.hex()
'f0f1f2'
@end example

If you want to make the hex string easier to read, you can specify a
single character separator `sep' parameter to include in the output.
By default, this separator will be included between each byte.
A second optional `bytes_per_sep' parameter controls the spacing.
Positive values calculate the separator position from the right,
negative values from the left.

@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


在 3.5 版被加入.



在 3.8 版的變更: @ref{f60,,bytes.hex()} now supports optional `sep' and `bytes_per_sep'
parameters to insert separators between bytes in the hex output.

@end deffn
@end deffn

Since bytes objects are sequences of integers (akin to a tuple), for a bytes
object `b', @code{b[0]} will be an integer, while @code{b[0:1]} will be a bytes
object of length 1.  (This contrasts with text strings, where both indexing
and slicing will produce a string of length 1)

The representation of bytes objects uses the literal format (@code{b'...'})
since it is often more useful than e.g. @code{bytes([46, 46, 46])}.  You can
always convert a bytes object into a list of integers using @code{list(b)}.

@node Bytearray 物件,Bytes 和 Bytearray 的操作,Bytes Objects,Binary Sequence Types --- bytes bytearray memoryview
@anchor{library/stdtypes bytearray-objects}@anchor{2505}@anchor{library/stdtypes typebytearray}@anchor{246e}
@subsubsection Bytearray 物件


@geindex object（物件）;bytearray（位元組陣列）

@ref{343,,bytearray} objects are a mutable counterpart to @ref{192,,bytes}
objects.

@geindex bytearray (內建類別)
@anchor{library/stdtypes bytearray}@anchor{343}
@deffn {類別} bytearray (source=b'@w{'})

@deffnx {類別} bytearray (source, encoding, errors='strict')

There is no dedicated literal syntax for bytearray objects, instead
they are always created by calling the constructor:


@itemize *

@item 
建立一個空的實例：@code{bytearray()}

@item 
Creating a zero-filled instance with a given length: @code{bytearray(10)}

@item 
From an iterable of integers: @code{bytearray(range(20))}

@item 
Copying existing binary data via the buffer protocol:  @code{bytearray(b'Hi!')}
@end itemize

As bytearray objects are mutable, they support the
@ref{246b,,mutable} sequence operations in addition to the
common bytes and bytearray operations described in @ref{246c,,Bytes 和 Bytearray 的操作}.

另見內建的 @ref{1d62,,bytearray}。

Since 2 hexadecimal digits correspond precisely to a single byte, hexadecimal
numbers are a commonly used format for describing binary data. Accordingly,
the bytearray type has an additional class method to read data in that format:

@geindex fromhex() (bytearray 的類別方法)
@anchor{library/stdtypes bytearray fromhex}@anchor{191}
@deffn {方法} classmethod fromhex (string, /)

This @ref{343,,bytearray} class method returns bytearray object, decoding
the given string object.  The string must contain two hexadecimal digits
per byte, with ASCII whitespace being ignored.

@example
>>> bytearray.fromhex('2Ef0 F1f2  ')
bytearray(b'.\xf0\xf1\xf2')
@end example


在 3.7 版的變更: @ref{191,,bytearray.fromhex()} now skips all ASCII whitespace in the string,
not just spaces.



在 3.14 版的變更: @ref{191,,bytearray.fromhex()} now accepts ASCII @ref{192,,bytes} and
@ref{193,,bytes-like objects} as input.

@end deffn

A reverse conversion function exists to transform a bytearray object into its
hexadecimal representation.

@geindex hex() (bytearray 的方法)
@anchor{library/stdtypes bytearray hex}@anchor{f61}
@deffn {方法} hex (*, bytes_per_sep=1)

@deffnx {方法} hex (sep, bytes_per_sep=1)

Return a string object containing two hexadecimal digits for each
byte in the instance.

@example
>>> bytearray(b'\xf0\xf1\xf2').hex()
'f0f1f2'
@end example


在 3.5 版被加入.



在 3.8 版的變更: Similar to @ref{f60,,bytes.hex()}, @ref{f61,,bytearray.hex()} now supports
optional `sep' and `bytes_per_sep' parameters to insert separators
between bytes in the hex output.

@end deffn

@geindex resize() (bytearray 的方法)
@anchor{library/stdtypes bytearray resize}@anchor{1822}
@deffn {方法} resize (size, /)

Resize the @ref{343,,bytearray} to contain `size' bytes. `size' must be
greater than or equal to 0.

If the @ref{343,,bytearray} needs to shrink, bytes beyond `size' are truncated.

If the @ref{343,,bytearray} needs to grow, all new bytes, those beyond `size',
will be set to 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


在 3.14 版被加入.

@end deffn
@end deffn

Since bytearray objects are sequences of integers (akin to a list), for a
bytearray object `b', @code{b[0]} will be an integer, while @code{b[0:1]} will be
a bytearray object of length 1.  (This contrasts with text strings, where
both indexing and slicing will produce a string of length 1)

The representation of bytearray objects uses the bytes literal format
(@code{bytearray(b'...')}) since it is often more useful than e.g.
@code{bytearray([46, 46, 46])}.  You can always convert a bytearray object into
a list of integers using @code{list(b)}.

@node Bytes 和 Bytearray 的操作,printf-style Bytes Formatting,Bytearray 物件,Binary Sequence Types --- bytes bytearray memoryview
@anchor{library/stdtypes bytes-and-bytearray-operations}@anchor{2506}@anchor{library/stdtypes bytes-methods}@anchor{246c}
@subsubsection Bytes 和 Bytearray 的操作


@geindex bytes（位元組）;methods（方法）
@geindex bytearray（位元組陣列）;methods（方法）

Both bytes and bytearray objects support the @ref{24b7,,common}
sequence operations. They interoperate not just with operands of the same
type, but with any @ref{193,,bytes-like object}. Due to this flexibility, they can be
freely mixed in operations without causing errors. However, the return type
of the result may depend on the order of operands.

@cartouche
@quotation 備註 
The methods on bytes and bytearray objects don't accept strings as their
arguments, just as the methods on strings don't accept bytes as their
arguments.  For example, you have to write:

@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

Some bytes and bytearray operations assume the use of ASCII compatible
binary formats, and hence should be avoided when working with arbitrary
binary data. These restrictions are covered below.

@cartouche
@quotation 備註 
Using these ASCII based operations to manipulate binary data that is not
stored in an ASCII based format may lead to data corruption.
@end quotation
@end cartouche

The following methods on bytes and bytearray objects can be used with
arbitrary binary data.

@geindex count() (bytes 的方法)
@geindex count() (bytearray 的方法)
@anchor{library/stdtypes bytes count}@anchor{18dd}
@deffn {方法} bytes.count (sub[, start[, end]])
@anchor{library/stdtypes bytearray count}@anchor{18de}
@deffnx {方法} bytearray.count (sub[, start[, end]])

Return the number of non-overlapping occurrences of subsequence `sub' in
the range [`start', `end'].  Optional arguments `start' and `end' are
interpreted as in slice notation.

The subsequence to search for may be any @ref{193,,bytes-like object} or an
integer in the range 0 to 255.

If `sub' is empty, returns the number of empty slices between characters
which is the length of the bytes object plus one.


在 3.3 版的變更: Also accept an integer in the range 0 to 255 as the subsequence.

@end deffn

@geindex removeprefix() (bytes 的方法)
@geindex removeprefix() (bytearray 的方法)
@anchor{library/stdtypes bytes removeprefix}@anchor{2507}
@deffn {方法} bytes.removeprefix (prefix, /)
@anchor{library/stdtypes bytearray removeprefix}@anchor{2508}
@deffnx {方法} bytearray.removeprefix (prefix, /)

If the binary data starts with the `prefix' string, return
@code{bytes[len(prefix):]}. Otherwise, return a copy of the original
binary data:

@example
>>> b'TestHook'.removeprefix(b'Test')
b'Hook'
>>> b'BaseTestCase'.removeprefix(b'Test')
b'BaseTestCase'
@end example

`prefix' 可以是任何的 @ref{193,,bytes-like object}。

@cartouche
@quotation 備註 
The bytearray version of this method does `not' operate in place -
it always produces a new object, even if no changes were made.
@end quotation
@end cartouche


在 3.9 版被加入.

@end deffn

@geindex removesuffix() (bytes 的方法)
@geindex removesuffix() (bytearray 的方法)
@anchor{library/stdtypes bytes removesuffix}@anchor{2509}
@deffn {方法} bytes.removesuffix (suffix, /)
@anchor{library/stdtypes bytearray removesuffix}@anchor{250a}
@deffnx {方法} bytearray.removesuffix (suffix, /)

If the binary data ends with the `suffix' string and that `suffix' is
not empty, return @code{bytes[:-len(suffix)]}.  Otherwise, return a copy of
the original binary data:

@example
>>> b'MiscTests'.removesuffix(b'Tests')
b'Misc'
>>> b'TmpDirMixin'.removesuffix(b'Tests')
b'TmpDirMixin'
@end example

The `suffix' may be any @ref{193,,bytes-like object}.

@cartouche
@quotation 備註 
The bytearray version of this method does `not' operate in place -
it always produces a new object, even if no changes were made.
@end quotation
@end cartouche


在 3.9 版被加入.

@end deffn

@geindex decode() (bytes 的方法)
@geindex decode() (bytearray 的方法)
@anchor{library/stdtypes bytes decode}@anchor{aca}
@deffn {方法} bytes.decode (encoding='utf-8', errors='strict')
@anchor{library/stdtypes bytearray decode}@anchor{250b}
@deffnx {方法} bytearray.decode (encoding='utf-8', errors='strict')

Return the bytes decoded to a @ref{169,,str}.

`encoding' defaults to @code{'utf-8'};
see @ref{fb3,,標準編碼} for possible values.

`errors' controls how decoding errors are handled.
If @code{'strict'} (the default), a @ref{460,,UnicodeError} exception is raised.
Other possible values are @code{'ignore'}, @code{'replace'},
and any other name registered via @ref{168f,,codecs.register_error()}.
See @ref{1a9e,,Error Handlers} for details.

For performance reasons, the value of `errors' is not checked for validity
unless a decoding error actually occurs,
@ref{503,,Python 開發模式} is enabled or a @ref{504,,debug build} is used.

@cartouche
@quotation 備註 
Passing the `encoding' argument to @ref{169,,str} allows decoding any
@ref{193,,bytes-like object} directly, without needing to make a temporary
@code{bytes} or @code{bytearray} object.
@end quotation
@end cartouche


在 3.1 版的變更: 新增關鍵字引數的支援。



在 3.9 版的變更: The value of the `errors' argument is now checked in @ref{503,,Python 開發模式} and
in @ref{504,,debug mode}.

@end deffn

@geindex endswith() (bytes 的方法)
@geindex endswith() (bytearray 的方法)
@anchor{library/stdtypes bytes endswith}@anchor{24ce}
@deffn {方法} bytes.endswith (suffix[, start[, end]])
@anchor{library/stdtypes bytearray endswith}@anchor{159a}
@deffnx {方法} bytearray.endswith (suffix[, start[, end]])

Return @code{True} if the binary data ends with the specified `suffix',
otherwise return @code{False}.  `suffix' can also be a tuple of suffixes to
look for.  With optional `start', test beginning at that position.  With
optional `end', stop comparing at that position.

The suffix(es) to search for may be any @ref{193,,bytes-like object}.
@end deffn

@geindex find() (bytes 的方法)
@geindex find() (bytearray 的方法)
@anchor{library/stdtypes bytes find}@anchor{1af4}
@deffn {方法} bytes.find (sub[, start[, end]])
@anchor{library/stdtypes bytearray find}@anchor{159b}
@deffnx {方法} bytearray.find (sub[, start[, end]])

Return the lowest index in the data where the subsequence `sub' is found,
such that `sub' is contained in the slice @code{s[start:end]}.  Optional
arguments `start' and `end' are interpreted as in slice notation.  Return
@code{-1} if `sub' is not found.

The subsequence to search for may be any @ref{193,,bytes-like object} or an
integer in the range 0 to 255.

@cartouche
@quotation 備註 
The @ref{1af4,,find()} method should be used only if you need to know the
position of `sub'.  To check if `sub' is a substring or not, use the
@ref{349,,in} operator:

@example
>>> b'Py' in b'Python'
True
@end example
@end quotation
@end cartouche


在 3.3 版的變更: Also accept an integer in the range 0 to 255 as the subsequence.

@end deffn

@geindex index() (bytes 的方法)
@geindex index() (bytearray 的方法)
@anchor{library/stdtypes bytes index}@anchor{24cb}
@deffn {方法} bytes.index (sub[, start[, end]])
@anchor{library/stdtypes bytearray index}@anchor{250c}
@deffnx {方法} bytearray.index (sub[, start[, end]])

Like @ref{1af4,,find()}, but raise @ref{2eb,,ValueError} when the
subsequence is not found.

The subsequence to search for may be any @ref{193,,bytes-like object} or an
integer in the range 0 to 255.


在 3.3 版的變更: Also accept an integer in the range 0 to 255 as the subsequence.

@end deffn

@geindex join() (bytes 的方法)
@geindex join() (bytearray 的方法)
@anchor{library/stdtypes bytes join}@anchor{24ba}
@deffn {方法} bytes.join (iterable, /)
@anchor{library/stdtypes bytearray join}@anchor{250d}
@deffnx {方法} bytearray.join (iterable, /)

Return a bytes or bytearray object which is the concatenation of the
binary data sequences in `iterable'.  A @ref{198,,TypeError} will be raised
if there are any values in `iterable' that are not @ref{193,,bytes-like objects}, including @ref{169,,str} objects.  The
separator between elements is the contents of the bytes or
bytearray object providing this method.
@end deffn

@geindex maketrans() (bytes 的靜態方法)
@geindex maketrans() (bytearray 的靜態方法)
@anchor{library/stdtypes bytes maketrans}@anchor{1475}
@deffn {方法} static bytes.maketrans (from, to, /)
@anchor{library/stdtypes bytearray maketrans}@anchor{1476}
@deffnx {方法} static bytearray.maketrans (from, to, /)

This static method returns a translation table usable for
@ref{24f7,,bytes.translate()} that will map each character in `from' into the
character at the same position in `to'; `from' and `to' must both be
@ref{193,,bytes-like objects} and have the same length.


在 3.1 版被加入.

@end deffn

@geindex partition() (bytes 的方法)
@geindex partition() (bytearray 的方法)
@anchor{library/stdtypes bytes partition}@anchor{24d3}
@deffn {方法} bytes.partition (sep, /)
@anchor{library/stdtypes bytearray partition}@anchor{250e}
@deffnx {方法} bytearray.partition (sep, /)

Split the sequence at the first occurrence of `sep', and return a 3-tuple
containing the part before the separator, the separator itself or its
bytearray copy, and the part after the separator.
If the separator is not found, return a 3-tuple
containing a copy of the original sequence, followed by two empty bytes or
bytearray objects.

The separator to search for may be any @ref{193,,bytes-like object}.
@end deffn

@geindex replace() (bytes 的方法)
@geindex replace() (bytearray 的方法)
@anchor{library/stdtypes bytes replace}@anchor{24cf}
@deffn {方法} bytes.replace (old, new, count=-1, /)
@anchor{library/stdtypes bytearray replace}@anchor{250f}
@deffnx {方法} bytearray.replace (old, new, count=-1, /)

Return a copy of the sequence with all occurrences of subsequence `old'
replaced by `new'.  If the optional argument `count' is given, only the
first `count' occurrences are replaced.

The subsequence to search for and its replacement may be any
@ref{193,,bytes-like object}.

@cartouche
@quotation 備註 
The bytearray version of this method does `not' operate in place - it
always produces a new object, even if no changes were made.
@end quotation
@end cartouche
@end deffn

@geindex rfind() (bytes 的方法)
@geindex rfind() (bytearray 的方法)
@anchor{library/stdtypes bytes rfind}@anchor{1af5}
@deffn {方法} bytes.rfind (sub[, start[, end]])
@anchor{library/stdtypes bytearray rfind}@anchor{159c}
@deffnx {方法} bytearray.rfind (sub[, start[, end]])

Return the highest index in the sequence where the subsequence `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.

The subsequence to search for may be any @ref{193,,bytes-like object} or an
integer in the range 0 to 255.


在 3.3 版的變更: Also accept an integer in the range 0 to 255 as the subsequence.

@end deffn

@geindex rindex() (bytes 的方法)
@geindex rindex() (bytearray 的方法)
@anchor{library/stdtypes bytes rindex}@anchor{24cc}
@deffn {方法} bytes.rindex (sub[, start[, end]])
@anchor{library/stdtypes bytearray rindex}@anchor{2510}
@deffnx {方法} bytearray.rindex (sub[, start[, end]])

Like @ref{1af5,,rfind()} but raises @ref{2eb,,ValueError} when the
subsequence `sub' is not found.

The subsequence to search for may be any @ref{193,,bytes-like object} or an
integer in the range 0 to 255.


在 3.3 版的變更: Also accept an integer in the range 0 to 255 as the subsequence.

@end deffn

@geindex rpartition() (bytes 的方法)
@geindex rpartition() (bytearray 的方法)
@anchor{library/stdtypes bytes rpartition}@anchor{24d4}
@deffn {方法} bytes.rpartition (sep, /)
@anchor{library/stdtypes bytearray rpartition}@anchor{2511}
@deffnx {方法} bytearray.rpartition (sep, /)

Split the sequence at the last occurrence of `sep', and return a 3-tuple
containing the part before the separator, the separator itself or its
bytearray copy, and the part after the separator.
If the separator is not found, return a 3-tuple
containing two empty bytes or bytearray objects, followed by a copy of the
original sequence.

The separator to search for may be any @ref{193,,bytes-like object}.
@end deffn

@geindex startswith() (bytes 的方法)
@geindex startswith() (bytearray 的方法)
@anchor{library/stdtypes bytes startswith}@anchor{24cd}
@deffn {方法} bytes.startswith (prefix[, start[, end]])
@anchor{library/stdtypes bytearray startswith}@anchor{1599}
@deffnx {方法} bytearray.startswith (prefix[, start[, end]])

Return @code{True} if the binary data starts with the specified `prefix',
otherwise return @code{False}.  `prefix' can also be a tuple of prefixes to
look for.  With optional `start', test beginning at that position.  With
optional `end', stop comparing at that position.

The prefix(es) to search for may be any @ref{193,,bytes-like object}.
@end deffn

@geindex translate() (bytes 的方法)
@geindex translate() (bytearray 的方法)
@anchor{library/stdtypes bytes translate}@anchor{24f7}
@deffn {方法} bytes.translate (table, /, delete=b'@w{'})
@anchor{library/stdtypes bytearray translate}@anchor{14fc}
@deffnx {方法} bytearray.translate (table, /, delete=b'@w{'})

Return a copy of the bytes or bytearray object where all bytes occurring in
the optional argument `delete' are removed, and the remaining bytes have
been mapped through the given translation table, which must be a bytes
object of length 256.

You can use the @ref{1475,,bytes.maketrans()} method to create a translation
table.

Set the `table' argument to @code{None} for translations that only delete
characters:

@example
>>> b'read this short text'.translate(None, b'aeiou')
b'rd ths shrt txt'
@end example


在 3.6 版的變更: 支援 `delete' 關鍵字引數。

@end deffn

The following methods on bytes and bytearray objects have default behaviours
that assume the use of ASCII compatible binary formats, but can still be used
with arbitrary binary data by passing appropriate arguments. Note that all of
the bytearray methods in this section do `not' operate in place, and instead
produce new objects.

@geindex center() (bytes 的方法)
@geindex center() (bytearray 的方法)
@anchor{library/stdtypes bytes center}@anchor{24f0}
@deffn {方法} bytes.center (width, fillbyte=b' ', /)
@anchor{library/stdtypes bytearray center}@anchor{2512}
@deffnx {方法} bytearray.center (width, fillbyte=b' ', /)

Return a copy of the object centered in a sequence of length `width'.
Padding is done using the specified `fillbyte' (default is an ASCII
space). For @ref{192,,bytes} objects, the original sequence is returned if
`width' is less than or equal to @code{len(s)}.

@cartouche
@quotation 備註 
The bytearray version of this method does `not' operate in place -
it always produces a new object, even if no changes were made.
@end quotation
@end cartouche
@end deffn

@geindex ljust() (bytes 的方法)
@geindex ljust() (bytearray 的方法)
@anchor{library/stdtypes bytes ljust}@anchor{24ee}
@deffn {方法} bytes.ljust (width, fillbyte=b' ', /)
@anchor{library/stdtypes bytearray ljust}@anchor{2513}
@deffnx {方法} bytearray.ljust (width, fillbyte=b' ', /)

Return a copy of the object left justified in a sequence of length `width'.
Padding is done using the specified `fillbyte' (default is an ASCII
space). For @ref{192,,bytes} objects, the original sequence is returned if
`width' is less than or equal to @code{len(s)}.

@cartouche
@quotation 備註 
The bytearray version of this method does `not' operate in place -
it always produces a new object, even if no changes were made.
@end quotation
@end cartouche
@end deffn

@geindex lstrip() (bytes 的方法)
@geindex lstrip() (bytearray 的方法)
@anchor{library/stdtypes bytes lstrip}@anchor{24f4}
@deffn {方法} bytes.lstrip (bytes=None, /)
@anchor{library/stdtypes bytearray lstrip}@anchor{2514}
@deffnx {方法} bytearray.lstrip (bytes=None, /)

Return a copy of the sequence with specified leading bytes removed.  The
`bytes' argument is a binary sequence specifying the set of byte values to
be removed.  If omitted or @code{None}, the `bytes' argument defaults
to removing ASCII whitespace.  The `bytes' argument is not a prefix;
rather, all combinations of its values are stripped:

@example
>>> b'   spacious   '.lstrip()
b'spacious   '
>>> b'www.example.com'.lstrip(b'cmowz.')
b'example.com'
@end example

The binary sequence of byte values to remove may be any
@ref{193,,bytes-like object}. See @ref{2507,,removeprefix()} for a method
that will remove a single prefix string rather than all of a set of
characters.  For example:

@example
>>> b'Arthur: three!'.lstrip(b'Arthur: ')
b'ee!'
>>> b'Arthur: three!'.removeprefix(b'Arthur: ')
b'three!'
@end example

@cartouche
@quotation 備註 
The bytearray version of this method does `not' operate in place -
it always produces a new object, even if no changes were made.
@end quotation
@end cartouche
@end deffn

@geindex rjust() (bytes 的方法)
@geindex rjust() (bytearray 的方法)
@anchor{library/stdtypes bytes rjust}@anchor{24ef}
@deffn {方法} bytes.rjust (width, fillbyte=b' ', /)
@anchor{library/stdtypes bytearray rjust}@anchor{2515}
@deffnx {方法} bytearray.rjust (width, fillbyte=b' ', /)

Return a copy of the object right justified in a sequence of length `width'.
Padding is done using the specified `fillbyte' (default is an ASCII
space). For @ref{192,,bytes} objects, the original sequence is returned if
`width' is less than or equal to @code{len(s)}.

@cartouche
@quotation 備註 
The bytearray version of this method does `not' operate in place -
it always produces a new object, even if no changes were made.
@end quotation
@end cartouche
@end deffn

@geindex rsplit() (bytes 的方法)
@geindex rsplit() (bytearray 的方法)
@anchor{library/stdtypes bytes rsplit}@anchor{24d1}
@deffn {方法} bytes.rsplit (sep=None, maxsplit=-1)
@anchor{library/stdtypes bytearray rsplit}@anchor{2516}
@deffnx {方法} bytearray.rsplit (sep=None, maxsplit=-1)

Split the binary sequence into subsequences of the same type, using `sep'
as the delimiter string. If `maxsplit' is given, at most `maxsplit' splits
are done, the `rightmost' ones.  If `sep' is not specified or @code{None},
any subsequence consisting solely of ASCII whitespace is a separator.
Except for splitting from the right, @ref{2516,,rsplit()} behaves like
@ref{2517,,split()} which is described in detail below.
@end deffn

@geindex rstrip() (bytes 的方法)
@geindex rstrip() (bytearray 的方法)
@anchor{library/stdtypes bytes rstrip}@anchor{24f5}
@deffn {方法} bytes.rstrip (bytes=None, /)
@anchor{library/stdtypes bytearray rstrip}@anchor{2518}
@deffnx {方法} bytearray.rstrip (bytes=None, /)

Return a copy of the sequence with specified trailing bytes removed.  The
`bytes' argument is a binary sequence specifying the set of byte values to
be removed.  If omitted or @code{None}, the `bytes' argument defaults to
removing ASCII whitespace.  The `bytes' argument is not a suffix; rather,
all combinations of its values are stripped:

@example
>>> b'   spacious   '.rstrip()
b'   spacious'
>>> b'mississippi'.rstrip(b'ipz')
b'mississ'
@end example

The binary sequence of byte values to remove may be any
@ref{193,,bytes-like object}. See @ref{2509,,removesuffix()} for a method
that will remove a single suffix string rather than all of a set of
characters.  For example:

@example
>>> b'Monty Python'.rstrip(b' Python')
b'M'
>>> b'Monty Python'.removesuffix(b' Python')
b'Monty'
@end example

@cartouche
@quotation 備註 
The bytearray version of this method does `not' operate in place -
it always produces a new object, even if no changes were made.
@end quotation
@end cartouche
@end deffn

@geindex split() (bytes 的方法)
@geindex split() (bytearray 的方法)
@anchor{library/stdtypes bytes split}@anchor{24d0}
@deffn {方法} bytes.split (sep=None, maxsplit=-1)
@anchor{library/stdtypes bytearray split}@anchor{2517}
@deffnx {方法} bytearray.split (sep=None, maxsplit=-1)

Split the binary sequence into subsequences of the same type, using `sep'
as the delimiter string. If `maxsplit' is given and non-negative, at most
`maxsplit' splits are done (thus, the list will have at most @code{maxsplit+1}
elements).  If `maxsplit' is not specified or is @code{-1}, then there is no
limit on the number of splits (all possible splits are made).

If `sep' is given, consecutive delimiters are not grouped together and are
deemed to delimit empty subsequences (for example, @code{b'1,,2'.split(b',')}
returns @code{[b'1', b'@w{'}, b'2']}).  The `sep' argument may consist of a
multibyte sequence as a single delimiter. Splitting an empty sequence with
a specified separator returns @code{[b'@w{'}]} or @code{[bytearray(b'@w{'})]} depending
on the type of object being split.  The `sep' argument may be any
@ref{193,,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

If `sep' is not specified or is @code{None}, a different splitting algorithm
is applied: runs of consecutive ASCII whitespace are regarded as a single
separator, and the result will contain no empty strings at the start or
end if the sequence has leading or trailing whitespace.  Consequently,
splitting an empty sequence or a sequence consisting solely of ASCII
whitespace without a specified separator returns @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{24f3}
@deffn {方法} bytes.strip (bytes=None, /)
@anchor{library/stdtypes bytearray strip}@anchor{2519}
@deffnx {方法} bytearray.strip (bytes=None, /)

Return a copy of the sequence with specified leading and trailing bytes
removed. The `bytes' argument is a binary sequence specifying the set of
byte values to be removed.  If omitted or @code{None}, the `bytes'
argument defaults to removing ASCII whitespace. The `bytes' argument is
not a prefix or suffix; rather, all combinations of its values are
stripped:

@example
>>> b'   spacious   '.strip()
b'spacious'
>>> b'www.example.com'.strip(b'cmowz.')
b'example'
@end example

The binary sequence of byte values to remove may be any
@ref{193,,bytes-like object}.

@cartouche
@quotation 備註 
The bytearray version of this method does `not' operate in place -
it always produces a new object, even if no changes were made.
@end quotation
@end cartouche
@end deffn

The following methods on bytes and bytearray objects assume the use of ASCII
compatible binary formats and should not be applied to arbitrary binary data.
Note that all of the bytearray methods in this section do `not' operate in
place, and instead produce new objects.

@geindex capitalize() (bytes 的方法)
@geindex capitalize() (bytearray 的方法)
@anchor{library/stdtypes bytes capitalize}@anchor{24e9}
@deffn {方法} bytes.capitalize ()
@anchor{library/stdtypes bytearray capitalize}@anchor{251a}
@deffnx {方法} bytearray.capitalize ()

Return a copy of the sequence with each byte interpreted as an ASCII
character, and the first byte capitalized and the rest lowercased.
Non-ASCII byte values are passed through unchanged.

@cartouche
@quotation 備註 
The bytearray version of this method does `not' operate in place - it
always produces a new object, even if no changes were made.
@end quotation
@end cartouche
@end deffn

@geindex expandtabs() (bytes 的方法)
@geindex expandtabs() (bytearray 的方法)
@anchor{library/stdtypes bytes expandtabs}@anchor{24f2}
@deffn {方法} bytes.expandtabs (tabsize=8)
@anchor{library/stdtypes bytearray expandtabs}@anchor{251b}
@deffnx {方法} bytearray.expandtabs (tabsize=8)

Return a copy of the sequence where all ASCII tab characters are replaced
by one or more ASCII spaces, depending on the current column and the given
tab size.  Tab positions occur every `tabsize' bytes (default is 8,
giving tab positions at columns 0, 8, 16 and so on).  To expand the
sequence, the current column is set to zero and the sequence is examined
byte by byte.  If the byte is an ASCII tab character (@code{b'\t'}), one or
more space characters are inserted in the result until the current column
is equal to the next tab position. (The tab character itself is not
copied.)  If the current byte is an ASCII newline (@code{b'\n'}) or
carriage return (@code{b'\r'}), it is copied and the current column is reset
to zero.  Any other byte value is copied unchanged and the current column
is incremented by one regardless of how the byte value is represented when
printed:

@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 備註 
The bytearray version of this method does `not' operate in place - it
always produces a new object, even if no changes were made.
@end quotation
@end cartouche
@end deffn

@geindex isalnum() (bytes 的方法)
@geindex isalnum() (bytearray 的方法)
@anchor{library/stdtypes bytes isalnum}@anchor{24dc}
@deffn {方法} bytes.isalnum ()
@anchor{library/stdtypes bytearray isalnum}@anchor{251c}
@deffnx {方法} bytearray.isalnum ()

Return @code{True} if all bytes in the sequence are alphabetical ASCII characters
or ASCII decimal digits and the sequence is not empty, @code{False} otherwise.
Alphabetic ASCII characters are those byte values in the sequence
@code{b'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'}. ASCII decimal
digits are those byte values in the sequence @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{24d6}
@deffn {方法} bytes.isalpha ()
@anchor{library/stdtypes bytearray isalpha}@anchor{251d}
@deffnx {方法} bytearray.isalpha ()

Return @code{True} if all bytes in the sequence are alphabetic ASCII characters
and the sequence is not empty, @code{False} otherwise.  Alphabetic ASCII
characters are those byte values in the sequence
@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{251e}
@deffn {方法} bytes.isascii ()
@anchor{library/stdtypes bytearray isascii}@anchor{251f}
@deffnx {方法} bytearray.isascii ()

Return @code{True} if the sequence is empty or all bytes in the sequence are ASCII,
@code{False} otherwise.
ASCII bytes are in the range 0-0x7F.


在 3.7 版被加入.

@end deffn

@geindex isdigit() (bytes 的方法)
@geindex isdigit() (bytearray 的方法)
@anchor{library/stdtypes bytes isdigit}@anchor{24d9}
@deffn {方法} bytes.isdigit ()
@anchor{library/stdtypes bytearray isdigit}@anchor{2520}
@deffnx {方法} bytearray.isdigit ()

Return @code{True} if all bytes in the sequence are ASCII decimal digits
and the sequence is not empty, @code{False} otherwise. ASCII decimal digits are
those byte values in the sequence @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{24de}
@deffn {方法} bytes.islower ()
@anchor{library/stdtypes bytearray islower}@anchor{2521}
@deffnx {方法} bytearray.islower ()

Return @code{True} if there is at least one lowercase ASCII character
in the sequence and no uppercase ASCII characters, @code{False} otherwise.

舉例來說：

@example
>>> b'hello world'.islower()
True
>>> b'Hello world'.islower()
False
@end example

Lowercase ASCII characters are those byte values in the sequence
@code{b'abcdefghijklmnopqrstuvwxyz'}. Uppercase ASCII characters
are those byte values in the sequence @code{b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'}.
@end deffn

@geindex isspace() (bytes 的方法)
@geindex isspace() (bytearray 的方法)
@anchor{library/stdtypes bytes isspace}@anchor{24e4}
@deffn {方法} bytes.isspace ()
@anchor{library/stdtypes bytearray isspace}@anchor{2522}
@deffnx {方法} bytearray.isspace ()

Return @code{True} if all bytes in the sequence are ASCII whitespace and the
sequence is not empty, @code{False} otherwise.  ASCII whitespace characters are
those byte values in the sequence @code{b' \t\n\r\x0b\f'} (space, tab, newline,
carriage return, vertical tab, form feed).
@end deffn

@geindex istitle() (bytes 的方法)
@geindex istitle() (bytearray 的方法)
@anchor{library/stdtypes bytes istitle}@anchor{24e2}
@deffn {方法} bytes.istitle ()
@anchor{library/stdtypes bytearray istitle}@anchor{2523}
@deffnx {方法} bytearray.istitle ()

Return @code{True} if the sequence is ASCII titlecase and the sequence is not
empty, @code{False} otherwise. See @ref{24eb,,bytes.title()} for more details on the
definition of "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{24e0}
@deffn {方法} bytes.isupper ()
@anchor{library/stdtypes bytearray isupper}@anchor{2524}
@deffnx {方法} bytearray.isupper ()

Return @code{True} if there is at least one uppercase alphabetic ASCII character
in the sequence and no lowercase ASCII characters, @code{False} otherwise.

舉例來說：

@example
>>> b'HELLO WORLD'.isupper()
True
>>> b'Hello world'.isupper()
False
@end example

Lowercase ASCII characters are those byte values in the sequence
@code{b'abcdefghijklmnopqrstuvwxyz'}. Uppercase ASCII characters
are those byte values in the sequence @code{b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'}.
@end deffn

@geindex lower() (bytes 的方法)
@geindex lower() (bytearray 的方法)
@anchor{library/stdtypes bytes lower}@anchor{24e5}
@deffn {方法} bytes.lower ()
@anchor{library/stdtypes bytearray lower}@anchor{2525}
@deffnx {方法} bytearray.lower ()

Return a copy of the sequence with all the uppercase ASCII characters
converted to their corresponding lowercase counterpart.

舉例來說：

@example
>>> b'Hello World'.lower()
b'hello world'
@end example

Lowercase ASCII characters are those byte values in the sequence
@code{b'abcdefghijklmnopqrstuvwxyz'}. Uppercase ASCII characters
are those byte values in the sequence @code{b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'}.

@cartouche
@quotation 備註 
The bytearray version of this method does `not' operate in place - it
always produces a new object, even if no changes were made.
@end quotation
@end cartouche
@end deffn

@geindex universal newlines;bytes.splitlines 方法
@geindex universal newlines;bytearray.splitlines 方法

@geindex splitlines() (bytes 的方法)
@geindex splitlines() (bytearray 的方法)
@anchor{library/stdtypes bytes splitlines}@anchor{24d2}
@deffn {方法} bytes.splitlines (keepends=False)
@anchor{library/stdtypes bytearray splitlines}@anchor{2526}
@deffnx {方法} bytearray.splitlines (keepends=False)

Return a list of the lines in the binary sequence, breaking at ASCII
line boundaries. This method uses the @ref{f30,,universal newlines} approach
to splitting lines. Line breaks are not included in the resulting list
unless `keepends' is given and true.

舉例來說：

@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

Unlike @ref{24d0,,split()} when a delimiter string `sep' is given, this
method returns an empty list for the empty string, and a terminal line
break does not result in an extra line:

@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{24ed}
@deffn {方法} bytes.swapcase ()
@anchor{library/stdtypes bytearray swapcase}@anchor{2527}
@deffnx {方法} bytearray.swapcase ()

Return a copy of the sequence with all the lowercase ASCII characters
converted to their corresponding uppercase counterpart and vice-versa.

舉例來說：

@example
>>> b'Hello World'.swapcase()
b'hELLO wORLD'
@end example

Lowercase ASCII characters are those byte values in the sequence
@code{b'abcdefghijklmnopqrstuvwxyz'}. Uppercase ASCII characters
are those byte values in the sequence @code{b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'}.

Unlike @ref{24ec,,str.swapcase()}, it is always the case that
@code{bin.swapcase().swapcase() == bin} for the binary versions. Case
conversions are symmetrical in ASCII, even though that is not generally
true for arbitrary Unicode code points.

@cartouche
@quotation 備註 
The bytearray version of this method does `not' operate in place - it
always produces a new object, even if no changes were made.
@end quotation
@end cartouche
@end deffn

@geindex title() (bytes 的方法)
@geindex title() (bytearray 的方法)
@anchor{library/stdtypes bytes title}@anchor{24eb}
@deffn {方法} bytes.title ()
@anchor{library/stdtypes bytearray title}@anchor{2528}
@deffnx {方法} bytearray.title ()

Return a titlecased version of the binary sequence where words start with
an uppercase ASCII character and the remaining characters are lowercase.
Uncased byte values are left unmodified.

舉例來說：

@example
>>> b'Hello world'.title()
b'Hello World'
@end example

Lowercase ASCII characters are those byte values in the sequence
@code{b'abcdefghijklmnopqrstuvwxyz'}. Uppercase ASCII characters
are those byte values in the sequence @code{b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'}.
All other byte values are uncased.

The algorithm uses a simple language-independent definition of a word as
groups of consecutive letters.  The definition works in many contexts but
it means that apostrophes in contractions and possessives form word
boundaries, which may not be the desired result:

@example
>>> b"they're bill's friends from the UK".title()
b"They'Re Bill'S Friends From The Uk"
@end example

A workaround for apostrophes can be constructed using regular expressions:

@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 備註 
The bytearray version of this method does `not' operate in place - it
always produces a new object, even if no changes were made.
@end quotation
@end cartouche
@end deffn

@geindex upper() (bytes 的方法)
@geindex upper() (bytearray 的方法)
@anchor{library/stdtypes bytes upper}@anchor{24e7}
@deffn {方法} bytes.upper ()
@anchor{library/stdtypes bytearray upper}@anchor{2529}
@deffnx {方法} bytearray.upper ()

Return a copy of the sequence with all the lowercase ASCII characters
converted to their corresponding uppercase counterpart.

舉例來說：

@example
>>> b'Hello World'.upper()
b'HELLO WORLD'
@end example

Lowercase ASCII characters are those byte values in the sequence
@code{b'abcdefghijklmnopqrstuvwxyz'}. Uppercase ASCII characters
are those byte values in the sequence @code{b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'}.

@cartouche
@quotation 備註 
The bytearray version of this method does `not' operate in place - it
always produces a new object, even if no changes were made.
@end quotation
@end cartouche
@end deffn

@geindex zfill() (bytes 的方法)
@geindex zfill() (bytearray 的方法)
@anchor{library/stdtypes bytes zfill}@anchor{252a}
@deffn {方法} bytes.zfill (width, /)
@anchor{library/stdtypes bytearray zfill}@anchor{252b}
@deffnx {方法} bytearray.zfill (width, /)

Return a copy of the sequence left filled with ASCII @code{b'0'} digits to
make a sequence of length `width'. A leading sign prefix (@code{b'+'}/
@code{b'-'}) is handled by inserting the padding `after' the sign character
rather than before. For @ref{192,,bytes} objects, the original sequence is
returned if `width' is less than or equal to @code{len(seq)}.

舉例來說：

@example
>>> b"42".zfill(5)
b'00042'
>>> b"-42".zfill(5)
b'-0042'
@end example

@cartouche
@quotation 備註 
The bytearray version of this method does `not' operate in place - it
always produces a new object, even if no changes were made.
@end quotation
@end cartouche
@end deffn

@node printf-style Bytes Formatting,Memory Views,Bytes 和 Bytearray 的操作,Binary Sequence Types --- bytes bytearray memoryview
@anchor{library/stdtypes bytes-formatting}@anchor{f7c}@anchor{library/stdtypes printf-style-bytes-formatting}@anchor{252c}
@subsubsection @code{printf}-style Bytes Formatting


@geindex formatting（格式化）;bytes (%)
@geindex formatting（格式化）;bytearray (%)
@geindex interpolation（插值）;bytes (%)
@geindex interpolation（插值）;bytearray (%)
@geindex bytes（位元組）;formatting（格式化）
@geindex bytearray（位元組陣列）;formatting（格式化）
@geindex bytes（位元組）;interpolation（插值）
@geindex bytearray（位元組陣列）;interpolation（插值）
@geindex printf 風格格式化
@geindex sprintf 風格格式化
@geindex % （百分號）;printf 風格格式化

@cartouche
@quotation 備註 
The formatting operations described here exhibit a variety of quirks that
lead to a number of common errors (such as failing to display tuples and
dictionaries correctly).  If the value being printed may be a tuple or
dictionary, wrap it in a tuple.
@end quotation
@end cartouche

Bytes objects (@code{bytes}/@code{bytearray}) have one unique built-in operation:
the @code{%} operator (modulo).
This is also known as the bytes `formatting' or `interpolation' operator.
Given @code{format % values} (where `format' is a bytes object), @code{%} conversion
specifications in `format' are replaced with zero or more elements of `values'.
The effect is similar to using the @code{sprintf()} in the C language.

If `format' requires a single argument, `values' may be a single non-tuple
object. @footnote{
To format only a tuple you should therefore provide a singleton tuple whose only
element is the tuple to be formatted.
}  Otherwise, `values' must be a tuple with exactly the number of
items specified by the format bytes object, or a single mapping object (for
example, a dictionary).

@geindex () （圓括號）;於 printf 風格格式化
@geindex * （星號）;於 printf 風格格式化
@geindex . （點）;於 printf 風格格式化

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 
Mapping key (optional), consisting of a parenthesised sequence of characters
(for example, @code{(somename)}).

@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 read from the next element of the tuple in `values', 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 read from the next
element of the tuple in `values', and the value to convert comes after the
precision.

@item 
Length modifier (optional).

@item 
Conversion type.
@end enumerate

When the right argument is a dictionary (or other mapping type), then the
formats in the bytes object `must' include a parenthesised mapping key into that
dictionary inserted immediately after the @code{'%'} character. The mapping key
selects the value to be formatted from the mapping.  For example:

@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

In this case no @code{*} specifiers may occur in a format (since they require a
sequential parameter list).

The conversion flag characters are:

@geindex # （井字號）;於 printf 風格格式化
@geindex - （減號）;於 printf 風格格式化
@geindex + （加號）;於 printf 風格格式化
@geindex space（空白）;於 printf 風格格式化


@multitable {xxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Flag

@tab

含義

@item

@code{'#'}

@tab

The value conversion will use the "alternate form" (where defined
below).

@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'}
conversion if both are given).

@item

@code{' '}

@tab

(a space) A blank should be left before a positive number (or empty
string) produced by a signed conversion.

@item

@code{'+'}

@tab

A sign character (@code{'+'} or @code{'-'}) will precede the conversion
(overrides a "space" flag).

@end multitable


A length modifier (@code{h}, @code{l}, or @code{L}) may be present, but is ignored as it
is not necessary for Python -- so e.g. @code{%ld} is identical to @code{%d}.

The conversion types are:


@multitable {xxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxx} 
@headitem

Conversion

@tab

含義

@tab

註解

@item

@code{'d'}

@tab

Signed integer decimal.

@tab

@item

@code{'i'}

@tab

Signed integer decimal.

@tab

@item

@code{'o'}

@tab

Signed octal value.

@tab

(1)

@item

@code{'u'}

@tab

Obsolete type -- it is identical to @code{'d'}.

@tab

(8)

@item

@code{'x'}

@tab

Signed hexadecimal (lowercase).

@tab

(2)

@item

@code{'X'}

@tab

Signed hexadecimal (uppercase).

@tab

(2)

@item

@code{'e'}

@tab

Floating-point exponential format (lowercase).

@tab

(3)

@item

@code{'E'}

@tab

Floating-point exponential format (uppercase).

@tab

(3)

@item

@code{'f'}

@tab

Floating-point decimal format.

@tab

(3)

@item

@code{'F'}

@tab

Floating-point decimal format.

@tab

(3)

@item

@code{'g'}

@tab

Floating-point format. Uses lowercase exponential
format if exponent is less than -4 or not less than
precision, decimal format otherwise.

@tab

(4)

@item

@code{'G'}

@tab

Floating-point format. Uses uppercase exponential
format if exponent is less than -4 or not less than
precision, decimal format otherwise.

@tab

(4)

@item

@code{'c'}

@tab

Single byte (accepts integer or single
byte objects).

@tab

@item

@code{'b'}

@tab

Bytes (any object that follows the
@ref{260,,buffer protocol} or has
@ref{7f9,,__bytes__()}).

@tab

(5)

@item

@code{'s'}

@tab

@code{'s'} is an alias for @code{'b'} and should only
be used for Python2/3 code bases.

@tab

(6)

@item

@code{'a'}

@tab

Bytes (converts any Python object using
@code{repr(obj).encode('ascii', 'backslashreplace')}).

@tab

(5)

@item

@code{'r'}

@tab

@code{'r'} is an alias for @code{'a'} and should only
be used for Python2/3 code bases.

@tab

(7)

@item

@code{'%'}

@tab

No argument is converted, results in a @code{'%'}
character in the result.

@tab

@end multitable


註解：


@enumerate 

@item 
The alternate form causes a leading octal specifier (@code{'0o'}) to be
inserted before the first digit.

@item 
The alternate form causes a leading @code{'0x'} or @code{'0X'} (depending on whether
the @code{'x'} or @code{'X'} format was used) to be inserted before the first digit.

@item 
The alternate form causes the result to always contain a decimal point, even if
no digits follow it.

The precision determines the number of digits after the decimal point and
defaults to 6.

@item 
The alternate form causes the result to always contain a decimal point, and
trailing zeroes are not removed as they would otherwise be.

The precision determines the number of significant digits before and after the
decimal point and defaults to 6.

@item 
If precision is @code{N}, the output is truncated to @code{N} characters.

@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 備註 
The bytearray version of this method does `not' operate in place - it
always produces a new object, even if no changes were made.
@end quotation
@end cartouche


@subsubheading 也參考


@geindex Python Enhancement Proposals; PEP 461
PEP 461@footnote{https://peps.python.org/pep-0461/} - Adding % formatting to bytes and bytearray



在 3.5 版被加入.


@node Memory Views,,printf-style Bytes Formatting,Binary Sequence Types --- bytes bytearray memoryview
@anchor{library/stdtypes memory-views}@anchor{252d}@anchor{library/stdtypes typememoryview}@anchor{2483}
@subsubsection Memory Views


@ref{165,,memoryview} objects allow Python code to access the internal data
of an object that supports the @ref{260,,buffer protocol} without
copying.

@geindex memoryview (內建類別)
@anchor{library/stdtypes memoryview}@anchor{165}
@deffn {類別} memoryview (object)

@quotation

Create a @ref{165,,memoryview} that references `object'.  `object' must
support the buffer protocol.  Built-in objects that support the buffer
protocol include @ref{192,,bytes} and @ref{343,,bytearray}.

A @ref{165,,memoryview} has the notion of an `element', which is the
atomic memory unit handled by the originating `object'.  For many simple
types such as @ref{192,,bytes} and @ref{343,,bytearray}, an element is a single
byte, but other types such as @ref{4b9,,array.array} may have bigger elements.

@code{len(view)} is equal to the length of @ref{252e,,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 版的變更: If @code{view.ndim == 0}, @code{len(view)} now raises @ref{198,,TypeError} instead of returning 1.


The @ref{252f,,itemsize} attribute will give you the number of
bytes in a single element.

A @ref{165,,memoryview} supports slicing and indexing to expose its data.
One-dimensional slicing will result in a subview:

@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

If @ref{2530,,format} is one of the native format specifiers
from the @ref{db,,struct} module, indexing with an integer or a tuple of
integers is also supported and returns a single `element' with
the correct type.  One-dimensional memoryviews can be indexed
with an integer or a one-integer tuple.  Multi-dimensional memoryviews
can be indexed with tuples of exactly `ndim' integers where `ndim' is
the number of dimensions.  Zero-dimensional memoryviews can be indexed
with the empty tuple.

Here is an example with a non-byte format:

@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

If the underlying object is writable, the memoryview supports
one-dimensional slice assignment. Resizing is not allowed:

@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

One-dimensional memoryviews of @ref{81d,,hashable} (read-only) types with formats
'B', 'b' or 'c' are also hashable. The hash is defined as
@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 版的變更: One-dimensional memoryviews can now be sliced.
One-dimensional memoryviews with formats 'B', 'b' or 'c' are now @ref{81d,,hashable}.



在 3.4 版的變更: memoryview is now registered automatically with
@ref{13c5,,collections.abc.Sequence}



在 3.5 版的變更: memoryviews can now be indexed with tuple of integers.



在 3.14 版的變更: memoryview is now a @ref{1a1,,generic type}.


@ref{165,,memoryview} 有幾個方法：

@geindex __eq__() (memoryview 的方法)
@anchor{library/stdtypes memoryview __eq__}@anchor{2531}
@deffn {方法} __eq__ (exporter)

A memoryview and a 
@geindex Python Enhancement Proposals; PEP 3118
PEP 3118@footnote{https://peps.python.org/pep-3118/} exporter are equal if their shapes are
equivalent and if all corresponding values are equal when the operands'
respective format codes are interpreted using @ref{db,,struct} syntax.

For the subset of @ref{db,,struct} format strings currently supported by
@ref{252e,,tolist()}, @code{v} and @code{w} are equal if @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

If either format string is not supported by the @ref{db,,struct} module,
then the objects will always compare as unequal (even if the format
strings and buffer contents are identical):

@example
>>> from ctypes import BigEndianStructure, c_long
>>> class BEPoint(BigEndianStructure):
...     _fields_ = [("x", c_long), ("y", c_long)]
...
>>> point = BEPoint(100, 200)
>>> a = memoryview(point)
>>> b = memoryview(point)
>>> a == point
False
>>> a == b
False
@end example

Note that, as with floating-point numbers, @code{v is w} does `not' imply
@code{v == w} for memoryview objects.


在 3.3 版的變更: Previous versions compared the raw memory disregarding the item format
and the logical array structure.

@end deffn

@geindex tobytes() (memoryview 的方法)
@anchor{library/stdtypes memoryview tobytes}@anchor{2532}
@deffn {方法} tobytes (order='C')

Return the data in the buffer as a bytestring.  This is equivalent to
calling the @ref{192,,bytes} constructor on the memoryview.

@example
>>> m = memoryview(b"abc")
>>> m.tobytes()
b'abc'
>>> bytes(m)
b'abc'
@end example

For non-contiguous arrays the result is equal to the flattened list
representation with all elements converted to bytes. @ref{2532,,tobytes()}
supports all format strings, including those that are not in
@ref{db,,struct} module syntax.


在 3.8 版被加入: `order' can be @{'C', 'F', 'A'@}.  When `order' is 'C' or 'F', the data
of the original array is converted to C or Fortran order. For contiguous
views, 'A' returns an exact copy of the physical memory. In particular,
in-memory Fortran order is preserved. For non-contiguous views, the
data is converted to C first. `order=None' is the same as `order='C''.

@end deffn

@geindex hex() (memoryview 的方法)
@anchor{library/stdtypes memoryview hex}@anchor{f62}
@deffn {方法} hex (*, bytes_per_sep=1)

@deffnx {方法} hex (sep, bytes_per_sep=1)

Return a string object containing two hexadecimal digits for each
byte in the buffer.

@example
>>> m = memoryview(b"abc")
>>> m.hex()
'616263'
@end example


在 3.5 版被加入.



在 3.8 版的變更: Similar to @ref{f60,,bytes.hex()}, @ref{f62,,memoryview.hex()} now supports
optional `sep' and `bytes_per_sep' parameters to insert separators
between bytes in the hex output.

@end deffn

@geindex tolist() (memoryview 的方法)
@anchor{library/stdtypes memoryview tolist}@anchor{252e}
@deffn {方法} tolist ()

Return the data in the buffer as a list of elements.

@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{252e,,tolist()} now supports all single character native formats in
@ref{db,,struct} module syntax as well as multi-dimensional
representations.

@end deffn

@geindex toreadonly() (memoryview 的方法)
@anchor{library/stdtypes memoryview toreadonly}@anchor{2533}
@deffn {方法} toreadonly ()

Return a readonly version of the memoryview object.  The original
memoryview object is unchanged.

@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


在 3.8 版被加入.

@end deffn

@geindex release() (memoryview 的方法)
@anchor{library/stdtypes memoryview release}@anchor{13bf}
@deffn {方法} release ()

Release the underlying buffer exposed by the memoryview object.  Many
objects take special actions when a view is held on them (for example,
a @ref{343,,bytearray} would temporarily forbid resizing); therefore,
calling release() is handy to remove these restrictions (and free any
dangling resources) as soon as possible.

After this method has been called, any further operation on the view
raises a @ref{2eb,,ValueError} (except @ref{13bf,,release()} itself which can
be called multiple times):

@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

The context management protocol can be used for a similar effect,
using the @code{with} statement:

@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


在 3.2 版被加入.

@end deffn

@geindex cast() (memoryview 的方法)
@anchor{library/stdtypes memoryview cast}@anchor{2534}
@deffn {方法} cast (format, /)

@deffnx {方法} cast (format, shape, /)

Cast a memoryview to a new format or shape. `shape' defaults to
@code{[byte_length//new_itemsize]}, which means that the result view
will be one-dimensional. The return value is a new memoryview, but
the buffer itself is not copied. Supported casts are 1D -> C-@ref{2535,,contiguous}
and C-contiguous -> 1D.

The destination format is restricted to a single element native format in
@ref{db,,struct} syntax. One of the formats must be a byte format
('B', 'b' or 'c'). The byte length of the result must be the same
as the original length.
Note that all byte lengths may depend on the operating system.

Cast 1D/long to 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

Cast 1D/unsigned bytes to 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

Cast 1D/bytes to 3D/ints to 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

Cast 1D/unsigned long to 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


在 3.3 版被加入.



在 3.5 版的變更: The source format is no longer restricted when casting to a byte view.

@end deffn

@geindex count() (memoryview 的方法)
@anchor{library/stdtypes memoryview count}@anchor{1863}
@deffn {方法} count (value, /)

計算 `value' 的出現次數


在 3.14 版被加入.

@end deffn
@end quotation

@geindex index() (memoryview 的方法)
@anchor{library/stdtypes memoryview index}@anchor{1862}
@deffn {方法} index (value, start=0, stop=sys.maxsize, /)

@quotation

Return the index of the first occurrence of `value' (at or after
index `start' and before index `stop').

在找不到 `value' 時引發 @ref{2eb,,ValueError}。


在 3.14 版被加入.

@end quotation

There are also several readonly attributes available:

@geindex obj (memoryview 的屬性)
@anchor{library/stdtypes memoryview obj}@anchor{2536}
@deffn {屬性} obj

memoryview 的底層物件：

@example
>>> b  = bytearray(b'xyz')
>>> m = memoryview(b)
>>> m.obj is b
True
@end example


在 3.3 版被加入.

@end deffn

@geindex nbytes (memoryview 的屬性)
@anchor{library/stdtypes memoryview nbytes}@anchor{2537}
@deffn {屬性} nbytes

@code{nbytes == product(shape) * itemsize == len(m.tobytes())}. This is
the amount of space in bytes that the array would use in a contiguous
representation. It is not necessarily equal to @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

Multi-dimensional arrays:

@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


在 3.3 版被加入.

@end deffn

@geindex readonly (memoryview 的屬性)
@anchor{library/stdtypes memoryview readonly}@anchor{2538}
@deffn {屬性} readonly

A bool indicating whether the memory is read only.
@end deffn

@geindex format (memoryview 的屬性)
@anchor{library/stdtypes memoryview format}@anchor{2530}
@deffn {屬性} format

A string containing the format (in @ref{db,,struct} module style) for each
element in the view. A memoryview can be created from exporters with
arbitrary format strings, but some methods (e.g. @ref{252e,,tolist()}) are
restricted to native single element formats.


在 3.3 版的變更: format @code{'B'} is now handled according to the struct module syntax.
This means that @code{memoryview(b'abc')[0] == b'abc'[0] == 97}.

@end deffn

@geindex itemsize (memoryview 的屬性)
@anchor{library/stdtypes memoryview itemsize}@anchor{252f}
@deffn {屬性} itemsize

The size in bytes of each element of the 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{2539}
@deffn {屬性} ndim

An integer indicating how many dimensions of a multi-dimensional array the
memory represents.
@end deffn

@geindex shape (memoryview 的屬性)
@anchor{library/stdtypes memoryview shape}@anchor{253a}
@deffn {屬性} shape

A tuple of integers the length of @ref{2539,,ndim} giving the shape of the
memory as an N-dimensional array.


在 3.3 版的變更: An empty tuple instead of @code{None} when ndim = 0.

@end deffn

@geindex strides (memoryview 的屬性)
@anchor{library/stdtypes memoryview strides}@anchor{253b}
@deffn {屬性} strides

A tuple of integers the length of @ref{2539,,ndim} giving the size in bytes to
access each element for each dimension of the array.


在 3.3 版的變更: An empty tuple instead of @code{None} when ndim = 0.

@end deffn

@geindex suboffsets (memoryview 的屬性)
@anchor{library/stdtypes memoryview suboffsets}@anchor{253c}
@deffn {屬性} suboffsets

Used internally for PIL-style arrays. The value is informational only.
@end deffn

@geindex c_contiguous (memoryview 的屬性)
@anchor{library/stdtypes memoryview c_contiguous}@anchor{253d}
@deffn {屬性} c_contiguous

A bool indicating whether the memory is C-@ref{2535,,contiguous}.


在 3.3 版被加入.

@end deffn

@geindex f_contiguous (memoryview 的屬性)
@anchor{library/stdtypes memoryview f_contiguous}@anchor{253e}
@deffn {屬性} f_contiguous

A bool indicating whether the memory is Fortran @ref{2535,,contiguous}.


在 3.3 版被加入.

@end deffn

@geindex contiguous (memoryview 的屬性)
@anchor{library/stdtypes memoryview contiguous}@anchor{253f}
@deffn {屬性} contiguous

A bool indicating whether the memory is @ref{2535,,contiguous}.


在 3.3 版被加入.

@end deffn
@end deffn
@end deffn

@node Set Types --- set frozenset,Mapping Types --- dict,Binary Sequence Types --- bytes bytearray memoryview,內建型別
@anchor{library/stdtypes set-types-set-frozenset}@anchor{2540}@anchor{library/stdtypes types-set}@anchor{247f}
@subsection Set Types --- @code{set}, @code{frozenset}


@geindex object（物件）;set（集合）

A `set' object is an unordered collection of distinct @ref{81d,,hashable} objects.
Common uses include membership testing, removing duplicates from a sequence, and
computing mathematical operations such as intersection, union, difference, and
symmetric difference.
(For other containers see the built-in @ref{183,,dict}, @ref{24d,,list},
and @ref{60c,,tuple} classes, and the @ref{1e,,collections} module.)

Like other collections, sets support @code{x in set}, @code{len(set)}, and @code{for x in
set}.  Being an unordered collection, sets do not record element position or
order of insertion.  Accordingly, sets do not support indexing, slicing, or
other sequence-like behavior.

There are currently two built-in set types, @ref{184,,set} and @ref{7eb,,frozenset}.
The @ref{184,,set} type is mutable --- the contents can be changed using methods
like @code{add()} and @code{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 @ref{7eb,,frozenset} type is immutable and @ref{81d,,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.

Non-empty sets (not frozensets) can be created by placing a comma-separated list
of elements within braces, for example: @code{@{'jack', 'sjoerd'@}}, in addition to the
@ref{184,,set} constructor.

The constructors for both classes work the same:

@geindex set (內建類別)
@geindex frozenset (內建類別)
@anchor{library/stdtypes set}@anchor{184}
@deffn {類別} set (iterable=(), /)
@anchor{library/stdtypes frozenset}@anchor{7eb}
@deffnx {類別} frozenset (iterable=(), /)

Return a new set or frozenset object whose elements are taken from
`iterable'.  The elements of a set must be @ref{81d,,hashable}.  To
represent sets of sets, the inner sets must be @ref{7eb,,frozenset}
objects.  If `iterable' is not specified, a new empty set is
returned.

集合可以以多種方式建立：


@itemize *

@item 
Use a comma-separated list of elements within braces: @code{@{'jack', 'sjoerd'@}}

@item 
Use a set comprehension: @code{@{c for c in 'abracadabra' if c not in 'abc'@}}

@item 
Use the type constructor: @code{set()}, @code{set('foobar')}, @code{set(['a', 'b', 'foo'])}
@end itemize

Instances of @ref{184,,set} and @ref{7eb,,frozenset} provide the following
operations:


@deffn {Describe} len(s)

Return the number of elements in set `s' (cardinality of `s').
@end deffn


@deffn {Describe} x in s

Test `x' for membership in `s'.
@end deffn


@deffn {Describe} x not in s

Test `x' for non-membership in `s'.
@end deffn

@geindex isdisjoint() (frozenset 的方法)
@anchor{library/stdtypes frozenset isdisjoint}@anchor{2541}
@deffn {方法} isdisjoint (other, /)

Return @code{True} if the set has no elements in common with `other'.  Sets are
disjoint if and only if their intersection is the empty set.
@end deffn

@geindex issubset() (frozenset 的方法)
@anchor{library/stdtypes frozenset issubset}@anchor{2542}
@deffn {方法} issubset (other, /)

@deffnx {方法} set <= other

Test whether every element in the set is in `other'.
@end deffn


@deffn {方法} set < other

Test whether the set is a proper subset of `other', that is,
@code{set <= other and set != other}.
@end deffn

@geindex issuperset() (frozenset 的方法)
@anchor{library/stdtypes frozenset issuperset}@anchor{2543}
@deffn {方法} issuperset (other, /)

@deffnx {方法} set >= other

Test whether every element in `other' is in the set.
@end deffn


@deffn {方法} set > other

Test whether the set is a proper superset of `other', that is, @code{set >=
other and set != other}.
@end deffn

@geindex union() (frozenset 的方法)
@anchor{library/stdtypes frozenset union}@anchor{1677}
@deffn {方法} union (*others)

@deffnx {方法} set | other | ...

Return a new set with elements from the set and all others.
@end deffn

@geindex intersection() (frozenset 的方法)
@anchor{library/stdtypes frozenset intersection}@anchor{1678}
@deffn {方法} intersection (*others)

@deffnx {方法} set & other & ...

Return a new set with elements common to the set and all others.
@end deffn

@geindex difference() (frozenset 的方法)
@anchor{library/stdtypes frozenset difference}@anchor{2544}
@deffn {方法} difference (*others)

@deffnx {方法} set @w{-} other @w{-} ...

Return a new set with elements in the set that are not in the others.
@end deffn

@geindex symmetric_difference() (frozenset 的方法)
@anchor{library/stdtypes frozenset symmetric_difference}@anchor{2545}
@deffn {方法} symmetric_difference (other, /)

@deffnx {方法} set ^ other

Return a new set with elements in either the set or `other' but not both.
@end deffn

@geindex copy() (frozenset 的方法)
@anchor{library/stdtypes frozenset copy}@anchor{2546}
@deffn {方法} copy ()

Return a shallow copy of the set.
@end deffn

Note, the non-operator versions of @ref{1677,,union()}, @ref{1678,,intersection()},
@ref{2544,,difference()}, @ref{2545,,symmetric_difference()}, @ref{2542,,issubset()}, and
@ref{2543,,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')}.

Both @ref{184,,set} and @ref{7eb,,frozenset} support set to set comparisons. Two
sets are equal if and only if every element of each set is contained in the
other (each is a subset of the other). A set is less than another set if and
only if the first set is a proper subset of the second set (is a subset, but
is not equal). A set is greater than another set if and only if the first set
is a proper superset of the second set (is a superset, but is not equal).

Instances of @ref{184,,set} are compared to instances of @ref{7eb,,frozenset}
based on their members.  For example, @code{set('abc') == frozenset('abc')}
returns @code{True} and so does @code{set('abc') in set([frozenset('abc')])}.

The subset and equality comparisons do not generalize to a total ordering
function.  For example, any two nonempty disjoint sets are not equal and are not
subsets of each other, so `all' of the following return @code{False}: @code{a<b},
@code{a==b}, or @code{a>b}.

Since sets only define partial ordering (subset relationships), the output of
the @ref{dc3,,list.sort()} method is undefined for lists of sets.

Set elements, like dictionary keys, must be @ref{81d,,hashable}.

Binary operations that mix @ref{184,,set} instances with @ref{7eb,,frozenset}
return the type of the first operand.  For example: @code{frozenset('ab') |
set('bc')} returns an instance of @ref{7eb,,frozenset}.

The following table lists operations available for @ref{184,,set} that do not
apply to immutable instances of @ref{7eb,,frozenset}:

@geindex update() (frozenset 的方法)
@anchor{library/stdtypes frozenset update}@anchor{2547}
@deffn {方法} update (*others)

@deffnx {方法} set |= other | ...

Update the set, adding elements from all others.
@end deffn

@geindex intersection_update() (frozenset 的方法)
@anchor{library/stdtypes frozenset intersection_update}@anchor{1679}
@deffn {方法} intersection_update (*others)

@deffnx {方法} set &= other & ...

Update the set, keeping only elements found in it and all others.
@end deffn

@geindex difference_update() (frozenset 的方法)
@anchor{library/stdtypes frozenset difference_update}@anchor{2548}
@deffn {方法} difference_update (*others)

@deffnx {方法} set @w{-}= other | ...

Update the set, removing elements found in others.
@end deffn

@geindex symmetric_difference_update() (frozenset 的方法)
@anchor{library/stdtypes frozenset symmetric_difference_update}@anchor{167a}
@deffn {方法} symmetric_difference_update (other, /)

@deffnx {方法} set ^= other

Update the set, keeping only elements found in either set, but not in both.
@end deffn

@geindex add() (frozenset 的方法)
@anchor{library/stdtypes frozenset add}@anchor{21f2}
@deffn {方法} add (elem, /)

將元素 `elem' 加入集合。
@end deffn

@geindex remove() (frozenset 的方法)
@anchor{library/stdtypes frozenset remove}@anchor{2549}
@deffn {方法} remove (elem, /)

Remove element `elem' from the set.  Raises @ref{5df,,KeyError} if `elem' is
not contained in the set.
@end deffn

@geindex discard() (frozenset 的方法)
@anchor{library/stdtypes frozenset discard}@anchor{254a}
@deffn {方法} discard (elem, /)

如果 `elem' 存在於集合中則將其移除。
@end deffn

@geindex pop() (frozenset 的方法)
@anchor{library/stdtypes frozenset pop}@anchor{254b}
@deffn {方法} pop ()

Remove and return an arbitrary element from the set.  Raises
@ref{5df,,KeyError} if the set is empty.
@end deffn

@geindex clear() (frozenset 的方法)
@anchor{library/stdtypes frozenset clear}@anchor{254c}
@deffn {方法} clear ()

從集合中移除所有元素。
@end deffn

Note, the non-operator versions of the @ref{2547,,update()},
@ref{1679,,intersection_update()}, @ref{2548,,difference_update()}, and
@ref{167a,,symmetric_difference_update()} methods will accept any iterable as an
argument.

Note, the `elem' argument to the @ref{15b1,,__contains__()},
@ref{2549,,remove()}, and
@ref{254a,,discard()} methods may be a set.  To support searching for an equivalent
frozenset, a temporary one is created from `elem'.
@end deffn

@node Mapping Types --- dict,情境管理器型別,Set Types --- set frozenset,內建型別
@anchor{library/stdtypes mapping-types-dict}@anchor{254d}@anchor{library/stdtypes typesmapping}@anchor{cb4}
@subsection Mapping Types --- @code{dict}


@geindex object（物件）;mapping（對映）
@geindex object（物件）;dictionary（字典）
@geindex operations on（操作於）;mapping（對映）;type（型別）
@geindex operations on（操作於）;dictionary（字典）;type（型別）
@geindex statement（陳述式）;del
@geindex built-in function（內建函式）;len

A @ref{13bc,,mapping} object maps @ref{81d,,hashable} values to arbitrary objects.
Mappings are mutable objects.  There is currently only one standard mapping
type, the `dictionary'.  (For other containers see the built-in
@ref{24d,,list}, @ref{184,,set}, and @ref{60c,,tuple} classes, and the
@ref{1e,,collections} module.)

A dictionary's keys are `almost' arbitrary values.  Values that are not
@ref{81d,,hashable}, that is, values containing lists, dictionaries or other
mutable types (that are compared by value rather than by object identity) may
not be used as keys.
Values that compare equal (such as @code{1}, @code{1.0}, and @code{True})
can be used interchangeably to index the same dictionary entry.

@geindex dict (內建類別)
@anchor{library/stdtypes dict}@anchor{183}
@deffn {類別} dict (**kwargs)

@deffnx {類別} dict (mapping, /, **kwargs)

@deffnx {類別} dict (iterable, /, **kwargs)

Return a new dictionary initialized from an optional positional argument
and a possibly empty set of keyword arguments.

字典可以用數種方式建立：


@itemize *

@item 
Use a comma-separated list of @code{key: value} pairs within braces:
@code{@{'jack': 4098, 'sjoerd': 4127@}} or @code{@{4098: 'jack', 4127: 'sjoerd'@}}

@item 
Use a dict comprehension: @code{@{@}}, @code{@{x: x ** 2 for x in range(10)@}}

@item 
Use the type constructor: @code{dict()},
@code{dict([('foo', 100), ('bar', 200)])}, @code{dict(foo=100, bar=200)}
@end itemize

If no positional argument is given, an empty dictionary is created.
If a positional argument is given and it defines a @code{keys()} method, a
dictionary is created by calling @ref{582,,__getitem__()} on the argument with
each returned key from the method.  Otherwise, the positional argument must be an
@ref{1428,,iterable} object.  Each item in the iterable must itself be an iterable
with exactly two elements.  The first element of each item becomes a key in the
new dictionary, and the second element the corresponding value.  If a key occurs
more than once, the last value for that key becomes the corresponding value in
the new dictionary.

If keyword arguments are given, the keyword arguments and their values are
added to the dictionary created from the positional argument.  If a key
being added is already present, the value from the keyword argument
replaces the value from the positional argument.

Providing keyword arguments as in the first example only works for keys that
are valid Python identifiers.  Otherwise, any valid keys can be used.

Dictionaries compare equal if and only if they have the same @code{(key,
value)} pairs (regardless of ordering). Order comparisons ('<', '<=', '>=', '>') raise
@ref{198,,TypeError}.  To illustrate dictionary creation and equality,
the following examples all return a dictionary equal to
@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

Providing keyword arguments as in the first example only works for keys that
are valid Python identifiers.  Otherwise, any valid keys can be used.

Dictionaries preserve insertion order.  Note that updating a key does not
affect the order.  Keys added after deletion are inserted at the end.

@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 版的變更: Dictionary order is guaranteed to be insertion order.  This behavior was
an implementation detail of CPython from 3.6.


These are the operations that dictionaries support (and therefore, custom
mapping types should support too):


@deffn {Describe} list(d)

Return a list of all the keys used in the dictionary `d'.
@end deffn


@deffn {Describe} len(d)

Return the number of items in the dictionary `d'.
@end deffn


@deffn {Describe} d[key]

Return the item of `d' with key `key'.  Raises a @ref{5df,,KeyError} if `key' is
not in the map.

@geindex __missing__()

If a subclass of dict defines a method @ref{13be,,__missing__()} and `key'
is not present, the @code{d[key]} operation calls that method with the key `key'
as argument.  The @code{d[key]} operation then returns or raises whatever is
returned or raised by the @code{__missing__(key)} call.
No other operations or methods invoke @ref{13be,,__missing__()}. If
@ref{13be,,__missing__()} is not defined, @ref{5df,,KeyError} is raised.
@ref{13be,,__missing__()} must be a method; it cannot be an instance variable:

@example
>>> class Counter(dict):
...     def __missing__(self, key):
...         return 0
...
>>> c = Counter()
>>> c['red']
0
>>> c['red'] += 1
>>> c['red']
1
@end example

The example above shows part of the implementation of
@ref{1292,,collections.Counter}.
A different @code{__missing__()} method is used
by @ref{13bd,,collections.defaultdict}.
@end deffn


@deffn {Describe} d[key] = value

將 @code{d[key]} 設為 `value'。
@end deffn


@deffn {Describe} del d[key]

從 `d' 中移除 @code{d[key]}。若 `key' 不在對映中則引發 @ref{5df,,KeyError}。
@end deffn


@deffn {Describe} key in d

若 `d' 有鍵 `key' 則回傳 @code{True}，否則回傳 @code{False}。
@end deffn


@deffn {Describe} key not in d

等價於 @code{not key in d}。
@end deffn


@deffn {Describe} iter(d)

Return an iterator over the keys of the dictionary.  This is a shortcut
for @code{iter(d.keys())}.
@end deffn

@geindex clear() (dict 的方法)
@anchor{library/stdtypes dict clear}@anchor{1763}
@deffn {方法} clear ()

從字典中移除所有項目。
@end deffn

@geindex copy() (dict 的方法)
@anchor{library/stdtypes dict copy}@anchor{dc4}
@deffn {方法} copy ()

Return a shallow copy of the dictionary.
@end deffn

@geindex fromkeys() (dict 的類別方法)
@anchor{library/stdtypes dict fromkeys}@anchor{24e}
@deffn {方法} classmethod fromkeys (iterable, value=None, /)

Create a new dictionary with keys from `iterable' and values set to `value'.

@ref{24e,,fromkeys()} is a class method that returns a new dictionary. `value'
defaults to @code{None}.  All of the values refer to just a single instance,
so it generally doesn't make sense for `value' to be a mutable object
such as an empty list.  To get distinct values, use a @ref{f7a,,dict comprehension} instead.
@end deffn

@geindex get() (dict 的方法)
@anchor{library/stdtypes dict get}@anchor{1efb}
@deffn {方法} get (key, default=None, /)

Return the value for `key' if `key' is in the dictionary, else `default'.
If `default' is not given, it defaults to @code{None}, so that this method
never raises a @ref{5df,,KeyError}.
@end deffn

@geindex items() (dict 的方法)
@anchor{library/stdtypes dict items}@anchor{9cb}
@deffn {方法} items ()

Return a new view of the dictionary's items (@code{(key, value)} pairs).
See the @ref{254e,,documentation of view objects}.
@end deffn

@geindex keys() (dict 的方法)
@anchor{library/stdtypes dict keys}@anchor{9c9}
@deffn {方法} keys ()

Return a new view of the dictionary's keys.  See the @ref{254e,,documentation of view objects}.
@end deffn

@geindex pop() (dict 的方法)
@anchor{library/stdtypes dict pop}@anchor{5de}
@deffn {方法} pop (key, /)

@deffnx {方法} pop (key, default, /)

If `key' is in the dictionary, remove it and return its value, else return
`default'.  If `default' is not given and `key' is not in the dictionary,
a @ref{5df,,KeyError} is raised.
@end deffn

@geindex popitem() (dict 的方法)
@anchor{library/stdtypes dict popitem}@anchor{171a}
@deffn {方法} popitem ()

Remove and return a @code{(key, value)} pair from the dictionary.
Pairs are returned in @abbr{LIFO,last-in@comma{} first-out} order.

@ref{171a,,popitem()} is useful to destructively iterate over a dictionary, as
often used in set algorithms.  If the dictionary is empty, calling
@ref{171a,,popitem()} raises a @ref{5df,,KeyError}.


在 3.7 版的變更: LIFO order is now guaranteed. In prior versions, @ref{171a,,popitem()} would
return an arbitrary key/value pair.

@end deffn


@deffn {Describe} reversed(d)

Return a reverse iterator over the keys of the dictionary. This is a
shortcut for @code{reversed(d.keys())}.


在 3.8 版被加入.

@end deffn

@geindex setdefault() (dict 的方法)
@anchor{library/stdtypes dict setdefault}@anchor{1274}
@deffn {方法} setdefault (key, default=None, /)

If `key' is in the dictionary, return its value.  If not, insert `key'
with a value of `default' and return `default'.  `default' defaults to
@code{None}.
@end deffn

@geindex update() (dict 的方法)
@anchor{library/stdtypes dict update}@anchor{165a}
@deffn {方法} update (**kwargs)

@deffnx {方法} update (mapping, /, **kwargs)

@deffnx {方法} update (iterable, /, **kwargs)

Update the dictionary with the key/value pairs from `mapping' or `iterable' and `kwargs', overwriting
existing keys.  Return @code{None}.

@ref{165a,,update()} accepts either another object with a @code{keys()} method (in
which case @ref{582,,__getitem__()} is called with every key returned from
the method) or an iterable of key/value pairs (as tuples or other iterables
of length two). If keyword arguments are specified, the dictionary is then
updated with those key/value pairs: @code{d.update(red=1, blue=2)}.
@end deffn

@geindex values() (dict 的方法)
@anchor{library/stdtypes dict values}@anchor{9ca}
@deffn {方法} values ()

Return a new view of the dictionary's values.  See the
@ref{254e,,documentation of view objects}.

An equality comparison between one @code{dict.values()} view and another
will always return @code{False}. This also applies when comparing
@code{dict.values()} to itself:

@example
>>> d = @{'a': 1@}
>>> d.values() == d.values()
False
@end example
@end deffn


@deffn {Describe} d | other

Create a new dictionary with the merged keys and values of `d' and
`other', which must both be dictionaries. The values of `other' take
priority when `d' and `other' share keys.


在 3.9 版被加入.

@end deffn


@deffn {Describe} d |= other

Update the dictionary `d' with keys and values from `other', which may be
either a @ref{13bc,,mapping} or an @ref{1428,,iterable} of key/value pairs. The
values of `other' take priority when `d' and `other' share keys.


在 3.9 版被加入.

@end deffn

Dictionaries and dictionary views are reversible.

@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 版的變更: Dictionaries are now reversible.

@end deffn


@subsubheading 也參考


@ref{691,,types.MappingProxyType} can be used to create a read-only view
of a @ref{183,,dict}.


@menu
* 字典視圖物件:: 

@end menu

@node 字典視圖物件,,,Mapping Types --- dict
@anchor{library/stdtypes dict-views}@anchor{254e}@anchor{library/stdtypes dictionary-view-objects}@anchor{254f}
@subsubsection 字典視圖物件


The objects returned by @ref{9c9,,dict.keys()}, @ref{9ca,,dict.values()} and
@ref{9cb,,dict.items()} are `view objects'.  They provide a dynamic view on the
dictionary's entries, which means that when the dictionary changes, the view
reflects these changes.

Dictionary views can be iterated over to yield their respective data, and
support membership tests:


@deffn {Describe} len(dictview)

Return the number of entries in the dictionary.
@end deffn


@deffn {Describe} iter(dictview)

Return an iterator over the keys, values or items (represented as tuples of
@code{(key, value)}) in the dictionary.

Keys and values are iterated over in insertion order.
This allows the creation of @code{(value, key)} pairs
using @ref{1a0,,zip()}: @code{pairs = zip(d.values(), d.keys())}.  Another way to
create the same list is @code{pairs = [(v, k) for (k, v) in d.items()]}.

Iterating views while adding or deleting entries in the dictionary may raise
a @ref{244,,RuntimeError} or fail to iterate over all entries.


在 3.7 版的變更: Dictionary order is guaranteed to be insertion order.

@end deffn


@deffn {Describe} x in dictview

Return @code{True} if `x' is in the underlying dictionary's keys, values or
items (in the latter case, `x' should be a @code{(key, value)} tuple).
@end deffn


@deffn {Describe} reversed(dictview)

Return a reverse iterator over the keys, values or items of the dictionary.
The view will be iterated in reverse order of the insertion.


在 3.8 版的變更: Dictionary views are now reversible.

@end deffn


@deffn {Describe} dictview.mapping

Return a @ref{691,,types.MappingProxyType} that wraps the original
dictionary to which the view refers.


在 3.10 版被加入.

@end deffn

Keys views are set-like since their entries are unique and @ref{81d,,hashable}.
Items views also have set-like operations since the (key, value) pairs
are unique and the keys are hashable.
If all values in an items view are hashable as well,
then the items view can interoperate with other sets.
(Values views are not treated as set-like
since the entries are generally not unique.)  For set-like views, all of the
operations defined for the abstract base class @ref{2550,,collections.abc.Set} are
available (for example, @code{==}, @code{<}, or @code{^}).  While using set operators,
set-like views accept any iterable as the other operand,
unlike sets which only accept sets as the input.

An example of dictionary view usage:

@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 情境管理器型別,型別註釋的型別 --- 泛型別名 Generic Alias 、聯合 Union,Mapping Types --- dict,內建型別
@anchor{library/stdtypes context-manager-types}@anchor{2551}@anchor{library/stdtypes typecontextmanager}@anchor{22bc}
@subsection 情境管理器型別


@geindex context manager（情境管理器）
@geindex context management protocol（情境管理協定）
@geindex protocol（協定）;context management（情境管理）

Python 的 @ref{186,,with} 陳述式支援了由情境管理器定義之 runtime 情境的概念，要使用兩個方法來實作，該方法讓使用者定義類別能夠去定義 runtime 情境，且該情境在執行陳述式主體 (statement body) 之前進入、在陳述式結束時退出：

@geindex __enter__() (contextmanager 的方法)
@anchor{library/stdtypes contextmanager __enter__}@anchor{2552}
@deffn {方法} contextmanager.__enter__ ()

輸入 runtime 情境並回傳此物件或者與 runtime 情境相關的另一個物件。此方法回傳的值有被綁定到使用此情境管理器的 @ref{186,,with} 陳述式的 @code{as} 子句中的識別字。

一個會回傳自己的情境管理器範例是 @ref{13c4,,file object}。檔案物件從 __enter__() 回傳自己，以允許將 @ref{315,,open()} 用作 @ref{186,,with} 陳述式中的情境運算式。

一個會回傳相關物件的情境管理器範例是由 @ref{157e,,decimal.localcontext()} 回傳的管理器。這些管理器將有效的十進位情境設定為原始十進位情境的副本，然後回傳該副本。這允許對 @ref{186,,with} 陳述式主體中的目前十進位情境進行更改，而不會影響 @code{with} 陳述式外部的程式碼。
@end deffn

@geindex __exit__() (contextmanager 的方法)
@anchor{library/stdtypes contextmanager __exit__}@anchor{2553}
@deffn {方法} contextmanager.__exit__ (exc_type, exc_val, exc_tb)

退出 runtime 情境並回傳布林旗標以表示是否應抑制曾發生的任何例外。如果在執行 @ref{186,,with} 陳述式主體時發生例外，則引數包含例外型別、值和回溯 (traceback) 資訊。否則，所有三個引數都是 @code{None}。

從此方法回傳 true 值將導致 @ref{186,,with} 陳述式抑制例外並繼續執行緊接著 @code{with} 陳述式之後的陳述式。否則，該例外將在該方法執行完畢後繼續傳播 (propagate)。執行此方法期間發生的例外會取代 @code{with} 陳述式主體中發生的任何例外。

傳入的例外不應明確重新引發 - 取而代之的是，此方法應回傳 false 值以指示該方法已成功完成且不希望抑制引發的例外。這讓情境管理程式碼能輕鬆檢測 @code{__exit__()} 方法是否曾實際失敗過。
@end deffn

Python 定義了多個情境管理器來支援簡單的執行緒同步、檔案或其他物件的提示關閉以及對有效十進位算術情境的更簡單操作。除了情境管理協定的實作之外，不會對特定型別進行特殊處理。更多範例請參閱 @ref{27,,contextlib} 模組。

Python 的 @ref{125c,,generator} 和 @ref{1403,,contextlib.contextmanager} 裝飾器提供了一種便捷的方法來實作這些協定。如果產生器函式以 @ref{1403,,contextlib.contextmanager} 裝飾器裝飾，它將回傳一個有實作出需要的 @ref{2552,,__enter__()} 和 @ref{2553,,__exit__()} 方法的情境管理器，而不是由未裝飾產生器函式產生的疊代器。

請注意，Python/C API 中 Python 物件的型別結構中的任何方法都沒有特定的槽。想要定義這些方法的擴充型別必須將它們作為普通的 Python 可存取方法提供。與設定 runtime 情境的開銷相比，單一類別字典查找的開銷可以忽略不計。

@node 型別註釋的型別 --- 泛型別名 Generic Alias 、聯合 Union,其他內建型別,情境管理器型別,內建型別
@anchor{library/stdtypes type-annotation-types-generic-alias-union}@anchor{2554}
@subsection 型別註釋的型別 --- 泛型別名 (Generic Alias)、聯合 (Union)


@geindex annotation（註記）;type annotation（型別註記）；type hint（型別提示）

@ref{15c,,型別註釋} 的核心內建型別是@ref{8b8,,泛型別名}和@ref{9be,,聯合}。

@menu
* 泛型別名型別:: 
* 聯合型別 (Union Type): 聯合型別 Union Type. 

@end menu

@node 泛型別名型別,聯合型別 Union Type,,型別註釋的型別 --- 泛型別名 Generic Alias 、聯合 Union
@anchor{library/stdtypes generic-alias-type}@anchor{2555}@anchor{library/stdtypes types-genericalias}@anchor{8b8}
@subsubsection 泛型別名型別


@geindex object（物件）;GenericAlias（泛型別名）
@geindex Generic（泛型）;Alias（別名）

@code{GenericAlias} 物件通常是透過@ref{2280,,下標 (subscripting)} 一個類別來建立的。它們最常與@ref{2286,,容器類別} 一起使用，像是 @ref{24d,,list} 或 @ref{183,,dict}。例如 @code{list[int]} 是一個 @code{GenericAlias} 物件，它是透過使用引數 @ref{19b,,int} 來下標 @code{list} 類別而建立的。@code{GenericAlias} 物件主要會與@ref{15c,,型別註釋} 一起使用。

@cartouche
@quotation 備註 
通常只有當類別有實作特殊方法 @ref{93b,,__class_getitem__()} 時才可以去下標該類別。
@end quotation
@end cartouche

將一個 @code{GenericAlias} 物件用作 @ref{1a1,,generic type} 的代理，實作`參數化泛型 (parameterized generics)'。

對於一個容器類別，提供給該類別的@ref{2280,,下標}引數可以代表物件所包含元素的型別。例如 @code{set[bytes]} 可以用於型別註釋來表示一個 @ref{184,,set}，其中所有元素的型別都是 @ref{192,,bytes}。

對於定義 @ref{93b,,__class_getitem__()} 但不是容器的類別，提供給該類別的下標引數通常會指示物件上有定義的一個或多個方法的回傳型別。例如@ref{be,,正規表示式}可以用於 @ref{169,,str} 和 @ref{192,,bytes} 資料型別：


@itemize *

@item 
如果 @code{x = re.search('foo', 'foo')}，@code{x} 將會是一個 @ref{1183,,re.Match} 物件，其中 @code{x.group(0)} 和 @code{x[0]} 的回傳值都是 @ref{169,,str} 型別。我們就可以用 @code{GenericAlias} @code{re.Match[str]} 在型別註釋中表示這種物件。

@item 
如果 @code{y = re.search(b'bar', b'bar')}（注意 @ref{192,,bytes} 的 @code{b}）， @code{y} 也會是 @code{re.Match} 的實例，但 @code{y.group(0)} 和 @code{y[0]} 的回傳值的型別都是 @ref{192,,bytes}。在型別註釋中，我們將用 @code{re.Match[bytes]} 來表示各種 @ref{1183,,re.Match} 物件。
@end itemize

@code{GenericAlias} 物件是 @ref{9e5,,types.GenericAlias} 類別的實例，也可以用來直接建立 @code{GenericAlias} 物件。


@deffn {Describe} T[X, Y, ...]

建立一個 @code{GenericAlias} 來表示一個型別 @code{T}，其以型別 `X'、`Y' 等（取決於所使用的 @code{T}）來參數化。例如，一個函式需要一個包含 @ref{196,,float} 元素的 @ref{24d,,list}：

@example
def average(values: list[float]) -> float:
    return sum(values) / len(values)
@end example

@ref{13bc,,對映}物件的另一個範例，使用 @ref{183,,dict}，它是一個泛型型別，需要兩個型別參數，分別表示鍵型別和值型別。在此範例中，函式需要一個 @code{dict}，其帶有 @ref{169,,str} 型別的鍵和 @ref{19b,,int} 型別的值：

@example
def send_post_request(url: str, body: dict[str, int]) -> None:
    ...
@end example
@end deffn

內建函式 @ref{2ad,,isinstance()} 和 @ref{9bd,,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 runtime 不強制執行@ref{15c,,型別註釋}。這也擴展到泛型型別及其型別參數。當從 @code{GenericAlias} 建立容器物件時，不會檢查容器中元素的型別。例如，不鼓勵使用以下程式碼，但 runtime 不會出現錯誤：

@example
>>> t = list[str]
>>> t([1, 2, 3])
[1, 2, 3]
@end example

此外，參數化泛型在物件建立期間會擦除 (erase) 型別參數：

@example
>>> t = list[str]
>>> type(t)
<class 'types.GenericAlias'>

>>> l = t()
>>> type(l)
<class 'list'>
@end example

在泛型上呼叫 @ref{1c1,,repr()} 或 @ref{169,,str()} 會顯示參數化型別：

@example
>>> repr(list[int])
'list[int]'

>>> str(list[int])
'list[int]'
@end example

為防止像是 @code{dict[str][str]} 的錯誤出現，泛型容器的 @ref{582,,__getitem__()} 方法會在這種情況下引發例外：

@example
>>> dict[str][str]
Traceback (most recent call last):
  ...
TypeError: dict[str] is not a generic class
@end example

然而當使用@ref{227b,,型別變數 (type variable)} 時，此類運算式是有效的。索引的元素數量必須與 @code{GenericAlias} 物件的 @ref{2556,,__args__} 中的型別變數項目一樣多：

@example
>>> from typing import TypeVar
>>> Y = TypeVar('Y')
>>> dict[str, Y][int]
dict[str, int]
@end example

@menu
* 標準泛型類別:: 
* GenericAlias 物件的特殊屬性:: 

@end menu

@node 標準泛型類別,GenericAlias 物件的特殊屬性,,泛型別名型別
@anchor{library/stdtypes standard-generic-classes}@anchor{2557}
@subsubsection 標準泛型類別


以下標準函式庫類別有支援參數化泛型。此列表並非詳盡無遺。


@itemize *

@item 
@ref{60c,,tuple}

@item 
@ref{24d,,list}

@item 
@ref{183,,dict}

@item 
@ref{184,,set}

@item 
@ref{7eb,,frozenset}

@item 
@ref{f3f,,type}

@item 
@ref{dc1,,asyncio.Future}

@item 
@ref{1c7,,asyncio.Task}

@item 
@ref{7ed,,collections.deque}

@item 
@ref{13bd,,collections.defaultdict}

@item 
@ref{7ec,,collections.OrderedDict}

@item 
@ref{1292,,collections.Counter}

@item 
@ref{e11,,collections.ChainMap}

@item 
@ref{fd7,,collections.abc.Awaitable}

@item 
@ref{fd8,,collections.abc.Coroutine}

@item 
@ref{fda,,collections.abc.AsyncIterable}

@item 
@ref{fd9,,collections.abc.AsyncIterator}

@item 
@ref{e82,,collections.abc.AsyncGenerator}

@item 
@ref{2558,,collections.abc.Iterable}

@item 
@ref{2559,,collections.abc.Iterator}

@item 
@ref{fd6,,collections.abc.Generator}

@item 
@ref{e80,,collections.abc.Reversible}

@item 
@ref{255a,,collections.abc.Container}

@item 
@ref{e7f,,collections.abc.Collection}

@item 
@ref{9e4,,collections.abc.Callable}

@item 
@ref{2550,,collections.abc.Set}

@item 
@ref{255b,,collections.abc.MutableSet}

@item 
@ref{abe,,collections.abc.Mapping}

@item 
@ref{12ad,,collections.abc.MutableMapping}

@item 
@ref{13c5,,collections.abc.Sequence}

@item 
@ref{4ba,,collections.abc.MutableSequence}

@item 
@ref{341,,collections.abc.ByteString}

@item 
@ref{255c,,collections.abc.MappingView}

@item 
@ref{255d,,collections.abc.KeysView}

@item 
@ref{255e,,collections.abc.ItemsView}

@item 
@ref{255f,,collections.abc.ValuesView}

@item 
@ref{e85,,contextlib.AbstractContextManager}

@item 
@ref{d18,,contextlib.AbstractAsyncContextManager}

@item 
@ref{18c2,,dataclasses.Field}

@item 
@ref{75c,,functools.cached_property}

@item 
@ref{218,,functools.partialmethod}

@item 
@ref{e46,,os.PathLike}

@item 
@ref{2560,,queue.LifoQueue}

@item 
@ref{158c,,queue.Queue}

@item 
@ref{2561,,queue.PriorityQueue}

@item 
@ref{d59,,queue.SimpleQueue}

@item 
@ref{1182,,re.Pattern}

@item 
@ref{1183,,re.Match}

@item 
@ref{2562,,shelve.BsdDbShelf}

@item 
@ref{2563,,shelve.DbfilenameShelf}

@item 
@ref{1196,,shelve.Shelf}

@item 
@ref{691,,types.MappingProxyType}

@item 
@ref{188f,,weakref.WeakKeyDictionary}

@item 
@ref{11ea,,weakref.WeakMethod}

@item 
@ref{7ee,,weakref.WeakSet}

@item 
@ref{1890,,weakref.WeakValueDictionary}
@end itemize

@node GenericAlias 物件的特殊屬性,,標準泛型類別,泛型別名型別
@anchor{library/stdtypes special-attributes-of-genericalias-objects}@anchor{2564}
@subsubsection @code{GenericAlias} 物件的特殊屬性


所有參數化泛型都有實作特殊的唯讀屬性。

@geindex __origin__ (genericalias 的屬性)
@anchor{library/stdtypes genericalias __origin__}@anchor{2565}
@deffn {屬性} genericalias.__origin__

此屬性指向非參數化泛型類別：

@example
>>> list[int].__origin__
<class 'list'>
@end example
@end deffn

@geindex __args__ (genericalias 的屬性)
@anchor{library/stdtypes genericalias __args__}@anchor{2556}
@deffn {屬性} genericalias.__args__

此屬性是傳遞給泛型類別之原始 @ref{93b,,__class_getitem__()} 的泛型型別 @ref{60c,,tuple}（長度可以為 1）：

@example
>>> dict[str, list[int]].__args__
(<class 'str'>, list[int])
@end example
@end deffn

@geindex __parameters__ (genericalias 的屬性)
@anchor{library/stdtypes genericalias __parameters__}@anchor{2566}
@deffn {屬性} genericalias.__parameters__

此屬性是個會被延遲計算 (lazily computed) 的元組（可能為空），包含了在 @code{__args__} 中找得到的不重複型別變數：

@example
>>> from typing import TypeVar

>>> T = TypeVar('T')
>>> list[T].__parameters__
(~T,)
@end example

@cartouche
@quotation 備註 
具有 @ref{482,,typing.ParamSpec} 參數的一個 @code{GenericAlias} 物件在替換後可能沒有正確的 @code{__parameters__}，因為 @ref{482,,typing.ParamSpec} 主要用於靜態型別檢查。
@end quotation
@end cartouche
@end deffn

@geindex __unpacked__ (genericalias 的屬性)
@anchor{library/stdtypes genericalias __unpacked__}@anchor{2567}
@deffn {屬性} genericalias.__unpacked__

如果別名已使用 @code{*} 運算子解包 (unpack) 則為 true 的布林值（請參閱 @ref{483,,TypeVarTuple}）。


在 3.11 版被加入.

@end deffn


@subsubheading 也參考



@table @asis

@geindex Python Enhancement Proposals; PEP 484

@item PEP 484@footnote{https://peps.python.org/pep-0484/} - 型別提示

引入 Python 的型別註釋框架。

@geindex Python Enhancement Proposals; PEP 585

@item PEP 585@footnote{https://peps.python.org/pep-0585/} - 標準集合 (Standard Collections) 中的型別提示泛型

引入原生參數化標準函式庫類別的能力，前提是它們有實作特殊的類別方法 @ref{93b,,__class_getitem__()}。

@item @ref{227b,,泛型}、@ref{6ef,,使用者定義泛型}和 @ref{174e,,typing.Generic}

有關如何實作可以在 runtime 參數化並能被靜態型別檢查器理解的泛型類別的文件。
@end table



在 3.9 版被加入.


@node 聯合型別 Union Type,,泛型別名型別,型別註釋的型別 --- 泛型別名 Generic Alias 、聯合 Union
@anchor{library/stdtypes types-union}@anchor{9be}@anchor{library/stdtypes union-type}@anchor{2568}
@subsubsection 聯合型別 (Union Type)


@geindex object（物件）;Union（聯合）
@geindex union（聯集）;type（型別）

一個聯合物件可以保存多個@ref{248d,,型別物件 (type object)}之 @code{|}（位元 or）運算的值。這些型別主要用於@ref{15c,,型別註釋 (type annotation)}。與下標 @ref{2a8,,typing.Union} 相比，聯合型別運算式可以讓型別提示語法更清晰簡潔。


@deffn {Describe} X | Y | ...

定義一個包含 `X'、`Y' 等型別的聯合物件。@code{X | Y} 表示 X 或 Y。它相當於 @code{typing.Union[X, Y]}。舉例來說，下列函式需要一個型別為 @ref{19b,,int} 或 @ref{196,,float} 的引數：

@example
def square(number: int | float) -> int | float:
    return number ** 2
@end example

@cartouche
@quotation 備註 
不能在 runtime 使用 @code{|} 運算元 (operand) 來定義有一個以上的成員為向前參照 (forward reference) 的聯合。例如 @code{int | "Foo"}，其中 @code{"Foo"} 是對未定義類別的參照，將在 runtime 失敗。對於包含向前參照的聯合，請將整個運算式以字串呈現，例如 @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{2a7,,types.UnionType} 的實例：

@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{2ad,,isinstance()} 和 @ref{9bd,,issubclass()} 的呼叫：

@example
>>> isinstance("", int | str)
True
@end example

然而聯合物件中的@ref{8b8,,參數化泛型}則無法被檢查：

@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

構成聯合物件的對使用者公開型別 (user-exposed type) 可以透過 @ref{2a7,,types.UnionType} 存取並用於 @ref{2ad,,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__()}，則 Union 可以覆寫 (override) 它：

@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} 語法和聯合型別。



在 3.10 版被加入.



在 3.14 版的變更: Union objects are now instances of @ref{2a8,,typing.Union}. Previously, they were instances
of @ref{2a7,,types.UnionType}, which remains an alias for @ref{2a8,,typing.Union}.


@node 其他內建型別,特殊屬性<3>,型別註釋的型別 --- 泛型別名 Generic Alias 、聯合 Union,內建型別
@anchor{library/stdtypes other-built-in-types}@anchor{2569}@anchor{library/stdtypes typesother}@anchor{256a}
@subsection 其他內建型別


The interpreter supports several other kinds of objects. Most of these support
only one or two operations.

@menu
* 模組: 模組<4>. 
* 類別與類別實例:: 
* 函式:: 
* 方法:: 
* 程式碼物件: 程式碼物件<2>. 
* Type Objects:: 
* Null 物件:: 
* Ellipsis 物件:: 
* NotImplemented 物件:: 
* 內部物件:: 

@end menu

@node 模組<4>,類別與類別實例,,其他內建型別
@anchor{library/stdtypes modules}@anchor{256b}@anchor{library/stdtypes typesmodules}@anchor{256c}
@subsubsection 模組


The only special operation on a module is attribute access: @code{m.name}, where
`m' is a module and `name' accesses a name defined in `m''s symbol table.
Module attributes can be assigned to.  (Note that the @ref{7f1,,import}
statement is not, strictly speaking, an operation on a module object; @code{import
foo} does not require a module object named `foo' to exist, rather it requires
an (external) `definition' for a module named `foo' somewhere.)

A special attribute of every module is @ref{776,,__dict__}. This is the
dictionary containing the module's symbol table. Modifying this dictionary will
actually change the module's symbol table, but direct assignment to the
@ref{776,,__dict__} attribute is not possible (you can write
@code{m.__dict__['a'] = 1}, which defines @code{m.a} to be @code{1}, but you can't write
@code{m.__dict__ = @{@}}).  Modifying @ref{776,,__dict__} directly is
not recommended.

Modules built into the interpreter are written like this: @code{<module 'sys'
(built-in)>}.  If loaded from a file, they are written as @code{<module 'os' from
'/usr/local/lib/pythonX.Y/os.pyc'>}.

@node 類別與類別實例,函式,模組<4>,其他內建型別
@anchor{library/stdtypes classes-and-class-instances}@anchor{256d}@anchor{library/stdtypes typesobjects}@anchor{256e}
@subsubsection 類別與類別實例


請見 @ref{21e1,,物件、數值和型別} 和 @ref{14d8,,類別定義}。

@node 函式,方法,類別與類別實例,其他內建型別
@anchor{library/stdtypes functions}@anchor{256f}@anchor{library/stdtypes typesfunctions}@anchor{2570}
@subsubsection 函式


Function objects are created by function definitions.  The only operation on a
function object is to call it: @code{func(argument-list)}.

There are really two flavors of function objects: built-in functions and
user-defined functions.  Both support the same operation (to call the function),
but the implementation is different, hence the different object types.

更多資訊請見 @ref{1ee1,,函式定義}。

@node 方法,程式碼物件<2>,函式,其他內建型別
@anchor{library/stdtypes methods}@anchor{2571}@anchor{library/stdtypes typesmethods}@anchor{2572}
@subsubsection 方法


@geindex object（物件）;method（方法）

Methods are functions that are called using the attribute notation.
There are two flavors: @ref{220c,,built-in methods}
(such as @ref{8d4,,append()} on lists)
and @ref{1f6e,,class instance method}.
Built-in methods are described with the types that support them.

If you access a method (a function defined in a class namespace) through an
instance, you get a special object: a `bound method' (also called
@ref{1f6e,,instance method}) object. When called, it will add
the @code{self} argument
to the argument list.  Bound methods have two special read-only attributes:
@ref{15c0,,m.__self__} is the object on which the method
operates, and @ref{14fd,,m.__func__} is
the function implementing the method.  Calling @code{m(arg-1, arg-2, ..., arg-n)}
is completely equivalent to calling @code{m.__func__(m.__self__, arg-1, arg-2, ...,
arg-n)}.

Like @ref{596,,function objects}, bound method objects support
getting arbitrary
attributes.  However, since method attributes are actually stored on the
underlying function object (@ref{14fd,,method.__func__}), setting method attributes on
bound methods is disallowed.  Attempting to set an attribute on a method
results in an @ref{5e8,,AttributeError} being raised.  In order to set a method
attribute, you need to explicitly set it on the underlying function object:

@example
>>> class C:
...     def method(self):
...         pass
...
>>> c = C()
>>> c.method.whoami = 'my name is method'  # 不得設定於方法
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{1f6e,,實例方法}。

@geindex object（物件）;code（程式碼）
@geindex code object（程式碼物件）

@node 程式碼物件<2>,Type Objects,方法,其他內建型別
@anchor{library/stdtypes bltin-code-objects}@anchor{2573}@anchor{library/stdtypes code-objects}@anchor{2574}
@subsubsection 程式碼物件


@geindex built-in function（內建函式）;compile（編譯）
@geindex __code__（函式物件屬性）

Code objects are used by the implementation to represent "pseudo-compiled"
executable Python code such as a function body. They differ from function
objects because they don't contain a reference to their global execution
environment.  Code objects are returned by the built-in @ref{4ac,,compile()} function
and can be extracted from function objects through their
@ref{597,,__code__} attribute. See also the @ref{1b,,code} module.

存取 @ref{597,,__code__} 會引發一個附帶引數 @code{obj} 與 @code{"__code__"} 的@ref{1b70,,稽核事件} @code{object.__getattr__}。

@geindex built-in function（內建函式）;exec
@geindex built-in function（內建函式）;eval

A code object can be executed or evaluated by passing it (instead of a source
string) to the @ref{49d,,exec()} or @ref{49e,,eval()}  built-in functions.

更多資訊請見 @ref{21e4,,標準型別階層}。

@node Type Objects,Null 物件,程式碼物件<2>,其他內建型別
@anchor{library/stdtypes bltin-type-objects}@anchor{248d}@anchor{library/stdtypes type-objects}@anchor{2575}
@subsubsection Type Objects


@geindex built-in function（內建函式）;type（型別）
@geindex 模組;type（型別）

Type objects represent the various object types.  An object's type is accessed
by the built-in function @ref{f3f,,type()}.  There are no special operations on
types.  The standard module @ref{109,,types} defines names for all standard built-in
types.

Types are written like this: @code{<class 'int'>}.

@node Null 物件,Ellipsis 物件,Type Objects,其他內建型別
@anchor{library/stdtypes bltin-null-object}@anchor{2576}@anchor{library/stdtypes the-null-object}@anchor{2577}
@subsubsection Null 物件


This object is returned by functions that don't explicitly return a value.  It
supports no special operations.  There is exactly one null object, named
@code{None} (a built-in name).  @code{type(None)()} produces the same singleton.

它被寫為 @code{None}。

@geindex ...;ellipsis literal（刪節號字面值）

@node Ellipsis 物件,NotImplemented 物件,Null 物件,其他內建型別
@anchor{library/stdtypes bltin-ellipsis-object}@anchor{1ec5}@anchor{library/stdtypes the-ellipsis-object}@anchor{2578}
@subsubsection Ellipsis 物件


This object is commonly used to indicate that something is omitted.
It supports no special operations.  There is exactly one ellipsis object, named
@ref{21dd,,Ellipsis} (a built-in name).  @code{type(Ellipsis)()} produces the
@ref{21dd,,Ellipsis} singleton.

它被寫為 @code{Ellipsis} 或 @code{...}。

In typical use, @code{...} as the @code{Ellipsis} object appears in a few different
places, for instance:


@itemize -

@item 
In type annotations, such as @ref{2579,,callable arguments}
or @ref{257a,,tuple elements}.

@item 
As the body of a function instead of a @ref{1ec4,,pass statement}.

@item 
In third-party libraries, such as Numpy's slicing and striding@footnote{https://numpy.org/doc/stable/user/basics.indexing.html#slicing-and-striding}.
@end itemize

Python also uses three dots in ways that are not @code{Ellipsis} objects, for instance:


@itemize -

@item 
Doctest's @ref{1663,,ELLIPSIS}, as a pattern for missing content.

@item 
The default Python prompt of the @ref{1b5,,interactive} shell when partial input is incomplete.
@end itemize

Lastly, the Python documentation often uses three dots in conventional English
usage to mean omitted content, even in code examples that also use them as the
@code{Ellipsis}.

@node NotImplemented 物件,內部物件,Ellipsis 物件,其他內建型別
@anchor{library/stdtypes bltin-notimplemented-object}@anchor{257b}@anchor{library/stdtypes the-notimplemented-object}@anchor{257c}
@subsubsection NotImplemented 物件


This object is returned from comparisons and binary operations when they are
asked to operate on types they don't support. See @ref{2378,,Comparisons} for more
information.  There is exactly one @ref{1a2,,NotImplemented} object.
@code{type(NotImplemented)()} produces the singleton instance.

它被寫為 @code{NotImplemented}。

@node 內部物件,,NotImplemented 物件,其他內建型別
@anchor{library/stdtypes internal-objects}@anchor{257d}@anchor{library/stdtypes typesinternal}@anchor{257e}
@subsubsection 內部物件


See @ref{21e4,,標準型別階層} for this information.  It describes
@ref{8e7,,stack frame objects},
@ref{ce3,,traceback objects}, and slice objects.

@node 特殊屬性<3>,Integer string conversion length limitation,其他內建型別,內建型別
@anchor{library/stdtypes special-attributes}@anchor{257f}@anchor{library/stdtypes specialattrs}@anchor{2580}
@subsection 特殊屬性


The implementation adds a few special read-only attributes to several object
types, where they are relevant.  Some of these are not reported by the
@ref{83d,,dir()} built-in function.

@geindex __name__ (definition 的屬性)
@anchor{library/stdtypes definition __name__}@anchor{1261}
@deffn {屬性} definition.__name__

The name of the class, function, method, descriptor, or
generator instance.
@end deffn

@geindex __qualname__ (definition 的屬性)
@anchor{library/stdtypes definition __qualname__}@anchor{1260}
@deffn {屬性} definition.__qualname__

The @ref{1bf6,,qualified name} of the class, function, method, descriptor,
or generator instance.


在 3.3 版被加入.

@end deffn

@geindex __module__ (definition 的屬性)
@anchor{library/stdtypes definition __module__}@anchor{2581}
@deffn {屬性} definition.__module__

The name of the module in which a class or function was defined.
@end deffn

@geindex __doc__ (definition 的屬性)
@anchor{library/stdtypes definition __doc__}@anchor{b18}
@deffn {屬性} definition.__doc__

The documentation string of a class or function, or @code{None} if undefined.
@end deffn

@geindex __type_params__ (definition 的屬性)
@anchor{library/stdtypes definition __type_params__}@anchor{243d}
@deffn {屬性} definition.__type_params__

The @ref{5a7,,type parameters} of generic classes, functions,
and @ref{67c,,type aliases}. For classes and functions that
are not generic, this will be an empty tuple.


在 3.12 版被加入.

@end deffn

@node Integer string conversion length limitation,,特殊屬性<3>,內建型別
@anchor{library/stdtypes int-max-str-digits}@anchor{804}@anchor{library/stdtypes integer-string-conversion-length-limitation}@anchor{2582}
@subsection Integer string conversion length limitation


CPython has a global limit for converting between @ref{19b,,int} and @ref{169,,str}
to mitigate denial of service attacks. This limit `only' applies to decimal or
other non-power-of-two number bases. Hexadecimal, octal, and binary conversions
are unlimited. The limit can be configured.

The @ref{19b,,int} type in CPython is an arbitrary length number stored in binary
form (commonly known as a "bignum"). There exists no algorithm that can convert
a string to a binary integer or a binary integer to a string in linear time,
`unless' the base is a power of 2. Even the best known algorithms for base 10
have sub-quadratic complexity. Converting a large value such as @code{int('1' *
500_000)} can take over a second on a fast CPU.

Limiting conversion size offers a practical way to avoid 
@geindex Common Vulnerabilities and Exposures; CVE 2020-10735
CVE 2020-10735@footnote{https://www.cve.org/CVERecord?id=CVE-2020-10735}.

The limit is applied to the number of digit characters in the input or output
string when a non-linear conversion algorithm would be involved.  Underscores
and the sign are not counted towards the limit.

When an operation would exceed the limit, a @ref{2eb,,ValueError} is raised:

@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

The default limit is 4300 digits as provided in
@ref{1494,,sys.int_info.default_max_str_digits}.
The lowest limit that can be configured is 640 digits as provided in
@ref{1494,,sys.int_info.str_digits_check_threshold}.

Verification:

@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


在 3.11 版被加入.


@menu
* 受影響的 API:: 
* 設定限制:: 
* 建議的配置:: 

@end menu

@node 受影響的 API,設定限制,,Integer string conversion length limitation
@anchor{library/stdtypes affected-apis}@anchor{2583}
@subsubsection 受影響的 API


The limitation only applies to potentially slow conversions between @ref{19b,,int}
and @ref{169,,str} or @ref{192,,bytes}:


@itemize *

@item 
@code{int(string)} 以預設的 10 為底。

@item 
@code{int(string, base)} for all bases that are not a power of 2.

@item 
@code{str(integer)}。

@item 
@code{repr(integer)}。

@item 
any other string conversion to base 10, for example @code{f"@{integer@}"},
@code{"@{@}".format(integer)}, or @code{b"%d" % integer}.
@end itemize

The limitations do not apply to functions with a linear algorithm:


@itemize *

@item 
@code{int(string, base)} with base 2, 4, 8, 16, or 32.

@item 
@ref{1b07,,int.from_bytes()} 和 @ref{1b46,,int.to_bytes()}。

@item 
@ref{14d0,,hex()}、@ref{14cf,,oct()}、@ref{14a9,,bin()}。

@item 
@ref{4f4,,格式規格 (Format Specification) 迷你語言} for hex, octal, and binary numbers.

@item 
@ref{169,,str} to @ref{196,,float}.

@item 
@ref{169,,str} to @ref{1fe,,decimal.Decimal}.
@end itemize

@node 設定限制,建議的配置,受影響的 API,Integer string conversion length limitation
@anchor{library/stdtypes configuring-the-limit}@anchor{2584}
@subsubsection 設定限制


Before Python starts up you can use an environment variable or an interpreter
command line flag to configure the limit:


@itemize *

@item 
@geindex PYTHONINTMAXSTRDIGITS
@geindex 環境變數; PYTHONINTMAXSTRDIGITS
@ref{1a79,,PYTHONINTMAXSTRDIGITS}, e.g.
@code{PYTHONINTMAXSTRDIGITS=640 python3} to set the limit to 640 or
@code{PYTHONINTMAXSTRDIGITS=0 python3} to disable the limitation.

@item 
@ref{16f,,-X int_max_str_digits}，例如 @code{python3 -X int_max_str_digits=640}

@item 
@ref{2585,,sys.flags.int_max_str_digits} contains the value of
@geindex PYTHONINTMAXSTRDIGITS
@geindex 環境變數; PYTHONINTMAXSTRDIGITS
@ref{1a79,,PYTHONINTMAXSTRDIGITS} or @ref{16f,,-X int_max_str_digits}.
If both the env var and the @code{-X} option are set, the @code{-X} option takes
precedence. A value of `-1' indicates that both were unset, thus a value of
@ref{2586,,sys.int_info.default_max_str_digits} was used during initialization.
@end itemize

From code, you can inspect the current limit and set a new one using these
@ref{df,,sys} APIs:


@itemize *

@item 
@ref{179b,,sys.get_int_max_str_digits()} and @ref{185e,,sys.set_int_max_str_digits()} are
a getter and setter for the interpreter-wide limit. Subinterpreters have
their own limit.
@end itemize

Information about the default and minimum can be found in @ref{1494,,sys.int_info}:


@itemize *

@item 
@ref{1494,,sys.int_info.default_max_str_digits} is the compiled-in
default limit.

@item 
@ref{1494,,sys.int_info.str_digits_check_threshold} is the lowest
accepted value for the limit (other than 0 which disables it).
@end itemize


在 3.11 版被加入.


@cartouche
@quotation 警示 
Setting a low limit `can' lead to problems. While rare, code exists that
contains integer constants in decimal in their source that exceed the
minimum threshold. A consequence of setting the limit is that Python source
code containing decimal integer literals longer than the limit will
encounter an error during parsing, usually at startup time or import time or
even at installation time - anytime an up to date @code{.pyc} does not already
exist for the code. A workaround for source that contains such large
constants is to convert them to @code{0x} hexadecimal form as it has no limit.

Test your application thoroughly if you use a low limit. Ensure your tests
run with the limit set early via the environment or flag so that it applies
during startup and even during any installation step that may invoke Python
to precompile @code{.py} sources to @code{.pyc} files.
@end quotation
@end cartouche

@node 建議的配置,,設定限制,Integer string conversion length limitation
@anchor{library/stdtypes recommended-configuration}@anchor{2587}
@subsubsection 建議的配置


The default @ref{2586,,sys.int_info.default_max_str_digits} is expected to be
reasonable for most applications. If your application requires a different
limit, set it from your main entry point using Python version agnostic code as
these APIs were added in security patch releases in versions before 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

If you need to disable it entirely, set it to @code{0}.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node 內建的例外,文本處理 Text Processing 服務,內建型別,Python 標準函式庫 Standard Library
@anchor{library/exceptions doc}@anchor{2588}@anchor{library/exceptions bltin-exceptions}@anchor{1b3a}@anchor{library/exceptions built-in-exceptions}@anchor{2589}@anchor{library/exceptions translation-repo}@anchor{258a}
@section 內建的例外


@geindex statement（陳述式）;try
@geindex statement（陳述式）;except

在 Python 中，所有例外必須是從 @ref{7d0,,BaseException} 衍生的類別的實例。在陳述式 @ref{8f0,,try} 搭配 @ref{1ab,,except} 子句裡提到一個特定的類別時，那個子句也會處理任何從該類別衍生的例外類別（但不會處理該類別`衍生自'的例外類別）。兩個不是由子類別關係關聯起來的例外類別永遠不相等，就算它們有相同的名稱也是如此。

@geindex statement（陳述式）;raise

此章節裡列出的內建例外可以從直譯器或內建函式產生。除了特別提到的地方之外，它們會有一個`關聯值'表示錯誤發生的詳細原因。這可能是一個字串，或者是一些資訊項目組成的元組（例如一個錯誤代碼及一個解釋該代碼的字串）。這個關聯值通常當作引數傳遞給例外類別的建構函式。

使用者的程式碼可以引發內建例外。這可以用來測試例外處理器或者用來回報一個錯誤條件，`就像'直譯器會引發相同例外的情況；但需要注意的是沒有任何方式可以避免使用者的程式碼引發不適當的錯誤。

可以從內建的例外類別定義新的例外子類別；程式設計師被鼓勵從 @ref{bc4,,Exception} 類別或其子類別衍生新的例外，而不是從 @ref{7d0,,BaseException} 來衍生。更多關於定義例外的資訊可以在 Python 教學中的@ref{1f43,,使用者自定的例外}裡取得。

@menu
* 例外的情境:: 
* 繼承自內建的例外:: 
* 基底類別 (base classes): 基底類別 base classes. 
* 實體例外:: 
* 警告:: 
* 例外群組:: 
* 例外階層:: 

@end menu

@node 例外的情境,繼承自內建的例外,,內建的例外
@anchor{library/exceptions exception-context}@anchor{258b}
@subsection 例外的情境


@geindex exception（例外）;chaining
@geindex __cause__（例外屬性）
@geindex __context__（例外屬性）
@geindex __suppress_context__（例外屬性）

三個例外物件上的屬性提供關於引發此例外的情境的資訊：

@geindex __context__ (BaseException 的屬性)
@geindex __cause__ (BaseException 的屬性)
@geindex __suppress_context__ (BaseException 的屬性)
@anchor{library/exceptions BaseException __context__}@anchor{14c8}
@deffn {屬性} BaseException.__context__
@anchor{library/exceptions BaseException __cause__}@anchor{14c9}
@deffnx {屬性} BaseException.__cause__
@anchor{library/exceptions BaseException __suppress_context__}@anchor{23bc}
@deffnx {屬性} BaseException.__suppress_context__

當引發一個新的例外而同時有另一個例外已經正在被處理時，這個新例外的 @code{__context__} 屬性會自動被設成那個已處理的例外。當使用 @ref{1ab,,except} 或 @ref{1b0,,finally} 子句或 @ref{186,,with} 陳述式的時候例外會被處理。

這個隱含的例外情境可以透過使用 @code{from} 搭配 @ref{7fc,,raise} 來補充明確的原因：

@example
raise new_exc from original_exc
@end example

在 @ref{7fc,,from} 後面的運算式必須是一個例外或 @code{None}。它將會被設定成所引發例外的 @code{__cause__}。設定 @code{__cause__} 也隱含地設定 @code{__suppress_context__} 屬性為 @code{True}，因此使用 @code{raise new_exc from None} 實際上會以新的例外取代舊的例外以利於顯示（例如轉換 @ref{5df,,KeyError} 為 @ref{5e8,,AttributeError}），同時保持舊的例外可以透過 @code{__context__} 取得以方便 debug 的時候檢查。

預設的回溯 (traceback) 顯示程式碼會顯示這些連鎖的例外 (chained exception) 加上例外本身的回溯。當存在的時候，在 @code{__cause__} 中明確地連鎖的例外總是會被顯示。而在 @code{__context__} 中隱含地連鎖的例外只有當 @code{__cause__} 是 @ref{87e,,None} 且 @code{__suppress_context__} 是 false 時才會顯示。

在任一種情況下，例外本身總是會顯示在任何連鎖例外的後面，因此回溯的最後一列總是顯示最後一個被引發的例外。
@end deffn

@node 繼承自內建的例外,基底類別 base classes,例外的情境,內建的例外
@anchor{library/exceptions inheriting-from-built-in-exceptions}@anchor{258c}
@subsection 繼承自內建的例外


使用者的程式碼可以建立繼承自例外型別的子類別。建議一次只繼承一種例外型別以避免在基底類別之間如何處理 @code{args} 屬性的任何可能衝突，以及可能的記憶體佈局 (memory layout) 不相容。

為了效率，大部分的內建例外使用 C 來實作，參考 Objects/exceptions.c@footnote{https://github.com/python/cpython/tree/3.14/Objects/exceptions.c}。一些例外有客製化的記憶體佈局，使其不可能建立一個繼承多種例外型別的子類別。型別的記憶體佈局是實作細節且可能會在不同 Python 版本間改變，造成未來新的衝突。因此，總之建議避免繼承多種例外型別。

@node 基底類別 base classes,實體例外,繼承自內建的例外,內建的例外
@anchor{library/exceptions base-classes}@anchor{258d}
@subsection 基底類別 (base classes)


以下的例外大部分被用在當作其他例外的基底類別。

@geindex BaseException
@anchor{library/exceptions BaseException}@anchor{7d0}
@deffn {例外} BaseException

所有內建例外的基底類別。這不是為了讓使用者定義的類別直接繼承（可以使用 @ref{bc4,,Exception}）。如果在這個類別的實例上呼叫 @ref{169,,str()}，會回傳實例的引數的表示，或者沒有引數的時候會回傳空字串。

@geindex args (BaseException 的屬性)
@anchor{library/exceptions BaseException args}@anchor{786}
@deffn {屬性} args

提供給該例外建構函式的引數元組。一些內建的例外（像是 @ref{2c0,,OSError}）預期接受特定數量的引數並賦予該元組的每一個元素一個特別的意義，其他例外則通常用一個提供錯誤訊息的單一字串來呼叫。
@end deffn

@geindex with_traceback() (BaseException 的方法)
@anchor{library/exceptions BaseException with_traceback}@anchor{23bb}
@deffn {方法} with_traceback (tb)

此方法設定 `tb' 為該例外的新的回溯並回傳該例外物件。在 
@geindex Python Enhancement Proposals; PEP 3134
PEP 3134@footnote{https://peps.python.org/pep-3134/} 的例外連鎖功能變得可用之前，此方法曾被更普遍使用。下面的範例顯示我們如何將 @code{SomeException} 的實例轉換為 @code{OtherException} 的實例同時保留回溯。一旦被引發，目前的 frame 會被加進 @code{OtherException} 的回溯，就像原來 @code{SomeException} 的回溯會發生的一樣，我們允許它被傳遞給呼叫者：

@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{14c7}
@deffn {屬性} __traceback__

可寫入的欄位，儲存關聯到該例外的@ref{ce3,,回溯物件}。也可以參考 @ref{7fc,,raise 陳述式}。
@end deffn

@geindex add_note() (BaseException 的方法)
@anchor{library/exceptions BaseException add_note}@anchor{7cf}
@deffn {方法} add_note (note)

新增字串 @code{note} 到例外的備註，在標準的回溯裡，備註出現在例外字串的後面。如果 @code{note} 不是字串則引發 @ref{198,,TypeError}。


在 3.11 版被加入.

@end deffn

@geindex __notes__ (BaseException 的屬性)
@anchor{library/exceptions BaseException __notes__}@anchor{258e}
@deffn {屬性} __notes__

該例外的備註串列，使用 @ref{7cf,,add_note()} 來新增。此屬性在 @ref{7cf,,add_note()} 被呼叫的時候建立。


在 3.11 版被加入.

@end deffn
@end deffn

@geindex Exception
@anchor{library/exceptions Exception}@anchor{bc4}
@deffn {例外} Exception

所有內建、非系統退出 (non-system-exiting) 的例外都衍生自此類別。所有使用者定義的例外應該也要衍生自此類別。
@end deffn

@geindex ArithmeticError
@anchor{library/exceptions ArithmeticError}@anchor{258f}
@deffn {例外} ArithmeticError

各種運算錯誤所引發的那些內建例外：@ref{a78,,OverflowError}、@ref{b36,,ZeroDivisionError}、@ref{2590,,FloatingPointError} 的基底類別。
@end deffn

@geindex BufferError
@anchor{library/exceptions BufferError}@anchor{1adb}
@deffn {例外} BufferError

當@ref{260,,緩衝 (buffer)} 相關的操作無法被執行時會引發此例外。
@end deffn

@geindex LookupError
@anchor{library/exceptions LookupError}@anchor{2500}
@deffn {例外} LookupError

當使用在對映或序列上的鍵或索引是無效的時候所引發的例外：@ref{1729,,IndexError}、@ref{5df,,KeyError} 的基底類別。這可以被 @ref{b53,,codecs.lookup()} 直接引發。
@end deffn

@node 實體例外,警告,基底類別 base classes,內建的例外
@anchor{library/exceptions concrete-exceptions}@anchor{2591}
@subsection 實體例外


以下的例外是通常會被引發的例外。

@geindex AssertionError
@anchor{library/exceptions AssertionError}@anchor{8b0}
@deffn {例外} AssertionError

@geindex statement（陳述式）;assert

當 @ref{b57,,assert} 陳述式失敗的時候被引發。
@end deffn

@geindex AttributeError
@anchor{library/exceptions AttributeError}@anchor{5e8}
@deffn {例外} AttributeError

當屬性參照（參考 @ref{2351,,Attribute references}）或賦值失敗的時候被引發。（當物件根本不支援屬性參照或屬性賦值的時候，@ref{198,,TypeError} 會被引發。）

可選的僅限關鍵字引數 `name' 和 `obj' 會設定對應的屬性：

@geindex name (AttributeError 的屬性)
@anchor{library/exceptions AttributeError name}@anchor{2592}
@deffn {屬性} name

嘗試被存取的屬性名稱。
@end deffn

@geindex obj (AttributeError 的屬性)
@anchor{library/exceptions AttributeError obj}@anchor{2593}
@deffn {屬性} obj

存取指定屬性的物件。
@end deffn


在 3.10 版的變更: 新增 @ref{2592,,name} 與 @ref{2593,,obj} 屬性。

@end deffn

@geindex EOFError
@anchor{library/exceptions EOFError}@anchor{14da}
@deffn {例外} EOFError

當 @ref{14d9,,input()} 函式在沒有讀到任何資料而到達檔案結尾 (end-of-file, EOF) 條件的時候被引發。（注意：@code{io.IOBase.read()} 和 @ref{152a,,io.IOBase.readline()} 方法當達到 EOF 時會回傳空字串。）
@end deffn

@geindex FloatingPointError
@anchor{library/exceptions FloatingPointError}@anchor{2590}
@deffn {例外} FloatingPointError

目前沒有被使用。
@end deffn

@geindex GeneratorExit
@anchor{library/exceptions GeneratorExit}@anchor{15bf}
@deffn {例外} GeneratorExit

當 @ref{125c,,generator} 或 @ref{6b2,,coroutine} 被關閉的時候被引發；參考 @ref{19b7,,generator.close()} 和 @ref{22ca,,coroutine.close()}。此例外直接繼承自 @ref{7d0,,BaseException} 而不是 @ref{bc4,,Exception}，因為技術上來說這不是一個錯誤。
@end deffn

@geindex ImportError
@anchor{library/exceptions ImportError}@anchor{653}
@deffn {例外} ImportError

當 @ref{7f1,,import} 陳述式嘗試載入模組遇到問題的時候會被引發。當 @code{from ... import} 裡的 "from list" 包含找不到的名稱時也會被引發。

可選的僅限關鍵字引數 `name' 和 `path' 設定對應的屬性：

@geindex name (ImportError 的屬性)
@anchor{library/exceptions ImportError name}@anchor{2594}
@deffn {屬性} name

嘗試引入 (import) 的模組名稱。
@end deffn

@geindex path (ImportError 的屬性)
@anchor{library/exceptions ImportError path}@anchor{2595}
@deffn {屬性} path

觸發此例外的任何檔案的路徑。
@end deffn


在 3.3 版的變更: 新增 @ref{2594,,name} 與 @ref{2595,,path} 屬性。

@end deffn

@geindex ModuleNotFoundError
@anchor{library/exceptions ModuleNotFoundError}@anchor{d35}
@deffn {例外} ModuleNotFoundError

@ref{653,,ImportError} 的子類別，當模組不能被定位的時候會被 @ref{7f1,,import} 所引發。當在 @ref{17c0,,sys.modules} 裡找到 @code{None} 時也會被引發。


在 3.6 版被加入.

@end deffn

@geindex IndexError
@anchor{library/exceptions IndexError}@anchor{1729}
@deffn {例外} IndexError

當序列的索引超出範圍的時候會被引發。（切片索引 (slice indices) 會默默地被截短使其能落在允許的範圍內；如果索引不是整數，@ref{198,,TypeError} 會被引發。）

@c XXX xref to sequences
@end deffn

@geindex KeyError
@anchor{library/exceptions KeyError}@anchor{5df}
@deffn {例外} KeyError

當對映（字典）的鍵無法在已存在的鍵的集合中被找到時會被引發。

@c XXX xref to mapping objects?
@end deffn

@geindex KeyboardInterrupt
@anchor{library/exceptions KeyboardInterrupt}@anchor{bbc}
@deffn {例外} KeyboardInterrupt

當使用者輸入中斷鍵 (interrupt key)（一般來說是 @code{Control}-@code{C} 或 @code{Delete}）時會被引發。在執行過程中，會定期檢查是否產生中斷。此例外繼承自 @ref{7d0,,BaseException} 以防止意外地被捕捉 @ref{bc4,,Exception} 的程式碼所捕捉，而因此讓直譯器無法結束。

@cartouche
@quotation 備註 
捕捉 @ref{bbc,,KeyboardInterrupt} 需要特殊的考量。因為它可以在無法預期的時間點被引發，可能在某些情況下讓正在跑的程式處在一個不一致的狀態。一般來說最好讓 @ref{bbc,,KeyboardInterrupt} 越快結束程式越好，或者完全避免引發它。（參考 @ref{2596,,訊號處理程式與例外的說明}。）
@end quotation
@end cartouche
@end deffn

@geindex MemoryError
@anchor{library/exceptions MemoryError}@anchor{181e}
@deffn {例外} MemoryError

當一個操作用光了記憶體但情況還可能被修復 (rescued)（透過刪除一些物件）的時候被引發。關聯值是一個字串，表示什麼類型的（內部）操作用光了記憶體。需注意的是因為底層的記憶體管理架構（C 的 @code{malloc()} 函式），直譯器可能無法總是完整地從該情況中修復；僅管如此，它還是引發例外以讓堆疊回溯可以被印出，以防原因出在失控的程式。
@end deffn

@geindex NameError
@anchor{library/exceptions NameError}@anchor{450}
@deffn {例外} NameError

當找不到本地或全域的名稱時會被引發。這只應用在不合格的名稱 (unqualified name) 上。關聯值是一個錯誤訊息，包含那個無法被找到的名稱。

可選的僅限關鍵字引數 `name' 設定對應的屬性：

@geindex name (NameError 的屬性)
@anchor{library/exceptions NameError name}@anchor{2597}
@deffn {屬性} name

嘗試被存取的變數名稱。
@end deffn


在 3.10 版的變更: 新增 @ref{2597,,name} 屬性。

@end deffn

@geindex NotImplementedError
@anchor{library/exceptions NotImplementedError}@anchor{369}
@deffn {例外} NotImplementedError

此例外衍生自 @ref{244,,RuntimeError}。在使用者定義的基礎類別裡，當抽象方法要求衍生類別覆寫該方法時應該要引發此例外，或者當類別正在開發中，可用此例外表示還需要加入真正的實作。

@cartouche
@quotation 備註 
此例外不應該用來表示根本沒有要支援的運算子或方法 ── 在這個情況下可以讓該運算子或方法保持未定義，或者如果是子類別的話將其設成 @ref{87e,,None}。
@end quotation
@end cartouche

@cartouche
@quotation 警示 
@code{NotImplementedError} 和 @code{NotImplemented} 並不是可互換的。這個例外只能用在上面描述的情況；參考 @ref{1a2,,NotImplemented} 裡關於內建常數正確使用方法的細節。
@end quotation
@end cartouche
@end deffn

@geindex OSError
@anchor{library/exceptions OSError}@anchor{2c0}
@deffn {例外} OSError ([arg])

@deffnx {例外} OSError (errno, strerror[, filename[, winerror[, filename2]]])

@geindex module（模組）;errno

當系統函式回傳系統相關錯誤，包含像"找不到檔案"或"硬碟已滿"的 I/O 失敗會引發此例外（而非不合法的引數或其他次要的錯誤）。

建構函式的第二種形式會設定以下描述的相對應屬性。如果沒有給定則屬性預設為 @ref{87e,,None}。為了向後相容，如果傳入三個引數，@ref{786,,args} 屬性只會是包含建構函式前兩個引數的雙元素元組。

如同下面的@ref{2598,,作業系統例外}所描述，實際上建構函式通常回傳 @ref{2c0,,OSError} 的子類別。會依據最後 @ref{2599,,errno} 的值決定特定子類別。這個行為只發生在直接建構 @ref{2c0,,OSError} 或透過別名，且產生子類別的時候不會被繼承。

@geindex errno (OSError 的屬性)
@anchor{library/exceptions OSError errno}@anchor{2599}
@deffn {屬性} errno

從 C 變數 @code{errno} 而來的數值錯誤代碼。
@end deffn

@geindex winerror (OSError 的屬性)
@anchor{library/exceptions OSError winerror}@anchor{259a}
@deffn {屬性} winerror

在 Windows 下，這會提供你原生的 Windows 錯誤代碼。而 @ref{2599,,errno} 屬性是一個該原生錯誤代碼對於 POSIX 來說的近似翻譯。

在 Windows 下，如果建構函式引數 `winerror' 是整數，則 @ref{2599,,errno} 屬性會根據該 Windows 錯誤代碼來決定，且 `errno' 引數會被忽略。在其他平台上，`winerror' 引數會被忽略，而 @ref{259a,,winerror} 屬性會不存在。
@end deffn

@geindex strerror (OSError 的屬性)
@anchor{library/exceptions OSError strerror}@anchor{259b}
@deffn {屬性} strerror

作業系統提供的對應錯誤訊息。在 POSIX 下會使用 C 函式 @code{perror()} 做格式化，而在 Windows 下會使用 @code{FormatMessage()}。
@end deffn

@geindex filename (OSError 的屬性)
@geindex filename2 (OSError 的屬性)
@anchor{library/exceptions OSError filename}@anchor{259c}
@deffn {屬性} filename
@anchor{library/exceptions OSError filename2}@anchor{259d}
@deffnx {屬性} filename2

對於包含檔案系統路徑的例外（像是 @ref{315,,open()} 或 @ref{12f6,,os.unlink()}），@ref{259c,,filename} 是傳入函式的檔案名稱。對於包含兩個檔案系統路徑的函式（像是 @ref{12f2,,os.rename()}），@ref{259d,,filename2} 對應到傳入函式的第二個檔案名稱。
@end deffn


在 3.3 版的變更: @ref{124f,,EnvironmentError}、@ref{124e,,IOError}、@ref{1250,,WindowsError}、@ref{1251,,socket.error}、@ref{1252,,select.error} 及 @code{mmap.error} 已合併進 @ref{2c0,,OSError}，而建構函式可能會回傳子類別。



在 3.4 版的變更: @ref{259c,,filename} 屬性現在是傳入函式的原始檔名，而不是從@ref{756,,檔案系統編碼和錯誤處理函式}編碼或解碼過的名稱。並且新增 `filename2' 建構函式引數與屬性。

@end deffn

@geindex OverflowError
@anchor{library/exceptions OverflowError}@anchor{a78}
@deffn {例外} OverflowError

當運算操作的結果太大而無法表示的時候會引發此例外。這不會發生在整數上（會改成引發 @ref{181e,,MemoryError} 而不是放棄）。然而，因為一些歷史因素，OverflowError 有時候會因為整數在要求範圍之外而引發。因為在 C 裡面缺乏浮點數例外處理的標準化，大部分的浮點數運算都沒有被檢查。
@end deffn

@geindex PythonFinalizationError
@anchor{library/exceptions PythonFinalizationError}@anchor{473}
@deffn {例外} PythonFinalizationError

此例外衍生自 @ref{244,,RuntimeError}。當一個操作在直譯器關閉（也稱作 @ref{474,,Python 最終化 (Python finalization）}）期間被阻塞會引發此例外。

在 Python 最終化期間，能夠以 @ref{473,,PythonFinalizationError} 被阻塞的操作範例：


@itemize *

@item 
建立新的 Python 執行緒。

@item 
@ref{13e5,,Joining} a running daemon thread.

@item 
@ref{4b0,,os.fork()}。
@end itemize

也可以參閱 @ref{c77,,sys.is_finalizing()} 函式。


在 3.13 版被加入: 在之前，會引發一般的 @ref{244,,RuntimeError}。



在 3.14 版的變更: @ref{13e5,,threading.Thread.join()} can now raise this exception.

@end deffn

@geindex RecursionError
@anchor{library/exceptions RecursionError}@anchor{f63}
@deffn {例外} RecursionError

此例外衍生自 @ref{244,,RuntimeError}。當直譯器偵測到超過最大的遞迴深度（參考 @ref{6e4,,sys.getrecursionlimit()}）時會引發此例外。


在 3.5 版被加入: 在之前，會引發一般的 @ref{244,,RuntimeError}。

@end deffn

@geindex ReferenceError
@anchor{library/exceptions ReferenceError}@anchor{1701}
@deffn {例外} ReferenceError

當一個被 @ref{c3d,,weakref.proxy()} 函式建立的弱參照代理 (weak reference proxy) 被用來存取已經被垃圾回收 (garbage collected) 的參照物屬性時會引發此例外。更多關於弱參照的資訊參考 @ref{11a,,weakref} 模組。
@end deffn

@geindex RuntimeError
@anchor{library/exceptions RuntimeError}@anchor{244}
@deffn {例外} RuntimeError

當偵測到一個不屬於任何其他種類的錯誤時會引發此例外。關聯值是一個表示確切什麼地方出錯的字串。
@end deffn

@geindex StopIteration
@anchor{library/exceptions StopIteration}@anchor{df0}
@deffn {例外} StopIteration

會被內建函式 @ref{9d1,,next()} 及 @ref{4c3,,iterator} 的 @ref{14ce,,__next__()} 方法引發，用來表示疊代器沒有更多項目可以產生。

@geindex value (StopIteration 的屬性)
@anchor{library/exceptions StopIteration value}@anchor{22c6}
@deffn {屬性} value

此例外物件有單一屬性 @code{value}，當建構此例外時會以引數給定，預設為 @ref{87e,,None}。
@end deffn

當 @ref{125c,,generator} 或 @ref{6b2,,coroutine} 函式回傳時，新的 @ref{df0,,StopIteration} 實例會被引發，而該函式的回傳值會被用來當作此例外建構函式的 @ref{22c6,,value} 參數。

如果產生器程式直接或間接引發 @ref{df0,,StopIteration}，則其會被轉換成 @ref{244,,RuntimeError}（保留 @ref{df0,,StopIteration} 作為新例外的成因）。


在 3.3 版的變更: 新增 @code{value} 屬性且產生器函式可以用它來回傳值。



在 3.5 版的變更: 透過 @code{from __future__ import generator_stop} 引入 RuntimeError 的轉換，參考 
@geindex Python Enhancement Proposals; PEP 479
PEP 479@footnote{https://peps.python.org/pep-0479/}。



在 3.7 版的變更: 預設對所有程式啟用 
@geindex Python Enhancement Proposals; PEP 479
PEP 479@footnote{https://peps.python.org/pep-0479/}：在產生器引發的 @ref{df0,,StopIteration} 錯誤會轉換成 @ref{244,,RuntimeError}。

@end deffn

@geindex StopAsyncIteration
@anchor{library/exceptions StopAsyncIteration}@anchor{1cd7}
@deffn {例外} StopAsyncIteration

此例外必須被 @ref{4c2,,asynchronous iterator} 物件的 @ref{17fd,,__anext__()} 方法引發來停止疊代。


在 3.5 版被加入.

@end deffn

@geindex SyntaxError
@anchor{library/exceptions SyntaxError}@anchor{18e}
@deffn {例外} SyntaxError (message, details)

當剖析器遇到語法錯誤時會引發此例外。這可能發生在 @ref{7f1,,import} 陳述式、在呼叫內建函式 @ref{4ac,,compile()}、@ref{49d,,exec()} 或 @ref{49e,,eval()} 的時候，或者在讀取初始腳本或標準輸入（也包含互動式）的時候。

例外實例的 @ref{169,,str()} 只回傳錯誤訊息。Details 是個元組，其成員也能夠以分開的屬性取得。

@geindex filename (SyntaxError 的屬性)
@anchor{library/exceptions SyntaxError filename}@anchor{259e}
@deffn {屬性} filename

發生語法錯誤所在的檔案名稱。
@end deffn

@geindex lineno (SyntaxError 的屬性)
@anchor{library/exceptions SyntaxError lineno}@anchor{259f}
@deffn {屬性} lineno

發生錯誤所在檔案的列號。這是以 1 開始的索引：檔案第一列的 @code{lineno} 是 1。
@end deffn

@geindex offset (SyntaxError 的屬性)
@anchor{library/exceptions SyntaxError offset}@anchor{25a0}
@deffn {屬性} offset

發生錯誤所在該列的欄號 (column)。這是以 1 開始的索引：該列第一個字元的 @code{offset} 是 1。
@end deffn

@geindex text (SyntaxError 的屬性)
@anchor{library/exceptions SyntaxError text}@anchor{25a1}
@deffn {屬性} text

涉及該錯誤的原始程式碼文字。
@end deffn

@geindex end_lineno (SyntaxError 的屬性)
@anchor{library/exceptions SyntaxError end_lineno}@anchor{25a2}
@deffn {屬性} end_lineno

發生錯誤所在檔案的結束列號。這是以 1 開始的索引：檔案第一列的 @code{lineno} 是 1。
@end deffn

@geindex end_offset (SyntaxError 的屬性)
@anchor{library/exceptions SyntaxError end_offset}@anchor{25a3}
@deffn {屬性} end_offset

發生錯誤所在該結束列的欄號。這是以 1 開始的索引：該列第一個字元的 @code{offset} 是 1。
@end deffn

對於發生在 f-string 欄位的錯誤，訊息會以 "f-string: " 為前綴，而偏移量 (offset) 是從替代運算式建構的文字的偏移量。例如編譯 f'Bad @{a b@} field' 會得到這個 args 屬性：('f-string: ...', ('@w{'}, 1, 2, '(a b)n', 1, 5))。


在 3.10 版的變更: 新增 @ref{25a2,,end_lineno} 與 @ref{25a3,,end_offset} 屬性。

@end deffn

@geindex IndentationError
@anchor{library/exceptions IndentationError}@anchor{9a4}
@deffn {例外} IndentationError

與不正確的縮排有關的語法錯誤的基礎類別。這是 @ref{18e,,SyntaxError} 的子類別。
@end deffn

@geindex TabError
@anchor{library/exceptions TabError}@anchor{75e}
@deffn {例外} TabError

當縮排包含製表符號 (tab) 和空白的不一致用法時會引發此例外。這是 @ref{9a4,,IndentationError} 的子類別。
@end deffn

@geindex SystemError
@anchor{library/exceptions SystemError}@anchor{78e}
@deffn {例外} SystemError

當直譯器找到一個內部錯誤，但該情況看起來沒有嚴重到要讓它放棄所有的希望時會引發此例外。關聯值是一個表示什麼地方出錯的字串（以低階的方式表達）。在 @ref{8fd,,CPython} 中，這可能是因為錯誤地使用 Python 的 C API，例如回傳一個 @code{NULL} 值而沒有設定例外。

如果你確定這個例外不是你的或者所用套件的錯，你應該向你的 Python 直譯器作者或維護者回報此錯誤。務必要回報該 Python 直譯器的版本（@code{sys.version}；這也會在互動式 Python 會話的開頭被印出）、確切的錯誤訊息（該例外的關聯值）及如果可能的話，觸發此錯誤的程式來源。
@end deffn

@geindex SystemExit
@anchor{library/exceptions SystemExit}@anchor{f37}
@deffn {例外} SystemExit

此例外會被 @ref{277,,sys.exit()} 函式引發。它繼承自 @ref{7d0,,BaseException} 而不是 @ref{bc4,,Exception} 因此不會被捕捉 @ref{bc4,,Exception} 的程式意外地捕捉。這允許例外可以正確地向上傳遞並導致直譯器結束。當它未被處理時，Python 直譯器會結束；不會印出堆疊回溯。建構函式接受跟傳入 @ref{277,,sys.exit()} 一樣的可選引數。如果該值是整數，它會指定系統的結束狀態（傳入 C 的 @code{exit()} 函式）；如果它是 @code{None}，結束狀態會是 0；如果它是其他型別（例如字串），則物件的值會被印出而結束狀態是 1。

對 @ref{277,,sys.exit()} 的呼叫會轉譯成例外讓負責清理的處理函式（@ref{8f0,,try} 陳述式的 @ref{1b0,,finally} 子句）可以被執行，且讓除錯器可以在不冒著失去控制的風險下執行腳本。如果在絕對有必要立即結束的情況（例如在子行程呼叫完 @ref{4b0,,os.fork()} 之後 ）可以使用 @ref{25a4,,os._exit()} 函式。

@geindex code (SystemExit 的屬性)
@anchor{library/exceptions SystemExit code}@anchor{25a5}
@deffn {屬性} code

傳入建構函式的結束狀態或錯誤訊息。（預設是 @code{None}。 ）
@end deffn
@end deffn

@geindex TypeError
@anchor{library/exceptions TypeError}@anchor{198}
@deffn {例外} TypeError

當一個操作或函式被用在不適合的型別的物件時會引發此例外。關聯值是一個字串，提供關於不相符型別的細節。

此例外可能被使用者程式碼引發，以表示並不支援物件上所嘗試的操作，且本來就無意這樣做。如果一個物件有意要支援某個給定的操作但尚未提供實作，該引發的正確例外是 @ref{369,,NotImplementedError}。

傳入錯誤型別的引數（例如當預期傳入 @ref{19b,,int} 卻傳入 @ref{24d,,list}）應該要導致 @ref{198,,TypeError}，但傳入帶有錯誤值的引數（例如超出預期範圍的數值）應該要導致 @ref{2eb,,ValueError}。
@end deffn

@geindex UnboundLocalError
@anchor{library/exceptions UnboundLocalError}@anchor{172a}
@deffn {例外} UnboundLocalError

當在函式或方法裡引用某個區域變數，但該變數尚未被繫結到任何值的時候會引發此例外。這是 @ref{450,,NameError} 的子類別。
@end deffn

@geindex UnicodeError
@anchor{library/exceptions UnicodeError}@anchor{460}
@deffn {例外} UnicodeError

當 Unicode 相關的編碼或解碼錯誤發生時會引發此例外。這是 @ref{2eb,,ValueError} 的子類別。

@ref{460,,UnicodeError} 有屬性描述編碼或解碼錯誤。例如 @code{err.object[err.start:err.end]} 會提供讓編解碼器失敗的具體無效輸入。

@geindex encoding (UnicodeError 的屬性)
@anchor{library/exceptions UnicodeError encoding}@anchor{25a6}
@deffn {屬性} encoding

引發錯誤的編碼名稱。
@end deffn

@geindex reason (UnicodeError 的屬性)
@anchor{library/exceptions UnicodeError reason}@anchor{25a7}
@deffn {屬性} reason

描述特定編解碼器錯誤的字串。
@end deffn

@geindex object (UnicodeError 的屬性)
@anchor{library/exceptions UnicodeError object}@anchor{1867}
@deffn {屬性} object

編解碼器嘗試編碼或解碼的物件。
@end deffn

@geindex start (UnicodeError 的屬性)
@anchor{library/exceptions UnicodeError start}@anchor{1834}
@deffn {屬性} start

在 @ref{c75,,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{1835}
@deffn {屬性} end

在 @ref{c75,,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{880}
@deffn {例外} UnicodeEncodeError

在編碼當中發生 Unicode 相關錯誤時會引發此例外。這是 @ref{460,,UnicodeError} 的子類別。
@end deffn

@geindex UnicodeDecodeError
@anchor{library/exceptions UnicodeDecodeError}@anchor{bff}
@deffn {例外} UnicodeDecodeError

在解碼當中發生 Unicode 相關錯誤時會引發此例外。這是 @ref{460,,UnicodeError} 的子類別。
@end deffn

@geindex UnicodeTranslateError
@anchor{library/exceptions UnicodeTranslateError}@anchor{1868}
@deffn {例外} UnicodeTranslateError

在轉譯當中發生 Unicode 相關錯誤時會引發此例外。這是 @ref{460,,UnicodeError} 的子類別。
@end deffn

@geindex ValueError
@anchor{library/exceptions ValueError}@anchor{2eb}
@deffn {例外} ValueError

當一個操作或函式收到引數是正確型別但是不適合的值，且該情況無法被更精確的例外例如 @ref{1729,,IndexError} 所描述時會引發此例外。
@end deffn

@geindex ZeroDivisionError
@anchor{library/exceptions ZeroDivisionError}@anchor{b36}
@deffn {例外} ZeroDivisionError

當除法或模數運算 (modulo operation) 的第二個引數是 0 的時候會引發此例外。關聯值是一個字串，表示運算元及運算的類型。
@end deffn

以下例外是為了相容於之前版本而保留；從 Python 3.3 開始，它們是 @ref{2c0,,OSError} 的別名。

@geindex EnvironmentError
@anchor{library/exceptions EnvironmentError}@anchor{124f}
@deffn {例外} EnvironmentError
@end deffn

@geindex IOError
@anchor{library/exceptions IOError}@anchor{124e}
@deffn {例外} IOError
@end deffn

@geindex WindowsError
@anchor{library/exceptions WindowsError}@anchor{1250}
@deffn {例外} WindowsError

僅限於在 Windows 中使用。
@end deffn

@menu
* 作業系統例外:: 

@end menu

@node 作業系統例外,,,實體例外
@anchor{library/exceptions os-exceptions}@anchor{2598}
@subsubsection 作業系統例外


以下的例外是 @ref{2c0,,OSError} 的子類別，它們根據系統錯誤代碼來引發。

@geindex BlockingIOError
@anchor{library/exceptions BlockingIOError}@anchor{235}
@deffn {例外} BlockingIOError

當設置為非阻塞操作的物件（例如 socket）上的操作將要阻塞時會引發此例外。對應到 @code{errno} @ref{25a8,,EAGAIN}、@ref{25a9,,EALREADY}、@ref{25aa,,EWOULDBLOCK} 及 @ref{25ab,,EINPROGRESS}。

除了 @ref{2c0,,OSError} 的那些屬性之外，@ref{235,,BlockingIOError} 有多一個屬性：

@geindex characters_written (BlockingIOError 的屬性)
@anchor{library/exceptions BlockingIOError characters_written}@anchor{25ac}
@deffn {屬性} characters_written

一個整數，內容為在其阻塞之前，已寫進串流的字元數。當使用 @ref{83,,io} 模組裡的緩衝 I/O 類別時這個屬性是可用的。
@end deffn
@end deffn

@geindex ChildProcessError
@anchor{library/exceptions ChildProcessError}@anchor{1253}
@deffn {例外} ChildProcessError

當子行程上的操作失敗時會引發此例外。對應到 @code{errno} @ref{25ad,,ECHILD}。
@end deffn

@geindex ConnectionError
@anchor{library/exceptions ConnectionError}@anchor{1006}
@deffn {例外} ConnectionError

連線相關問題的基礎類別。

子類別有 @ref{1257,,BrokenPipeError}、@ref{1258,,ConnectionAbortedError}、@ref{1259,,ConnectionRefusedError} 及 @ref{125a,,ConnectionResetError}。
@end deffn

@geindex BrokenPipeError
@anchor{library/exceptions BrokenPipeError}@anchor{1257}
@deffn {例外} BrokenPipeError

@ref{1006,,ConnectionError} 的子類別，當嘗試寫入管道 (pipe) 同時另一端已經被關閉時會引發此例外，或者當嘗試寫入已關閉寫入的 socket 時也會引發。對應到 @code{errno} @ref{25ae,,EPIPE} 及 @ref{25af,,ESHUTDOWN}。
@end deffn

@geindex ConnectionAbortedError
@anchor{library/exceptions ConnectionAbortedError}@anchor{1258}
@deffn {例外} ConnectionAbortedError

@ref{1006,,ConnectionError} 的子類別。當一個連線的嘗試被對等端點 (peer) 中斷時會引發此例外。對應到 @code{errno} @ref{25b0,,ECONNABORTED}。
@end deffn

@geindex ConnectionRefusedError
@anchor{library/exceptions ConnectionRefusedError}@anchor{1259}
@deffn {例外} ConnectionRefusedError

@ref{1006,,ConnectionError} 的子類別。當一個連線的嘗試被對等端點拒絕時會引發此例外。對應到 @code{errno} @ref{25b1,,ECONNREFUSED}。
@end deffn

@geindex ConnectionResetError
@anchor{library/exceptions ConnectionResetError}@anchor{125a}
@deffn {例外} ConnectionResetError

@ref{1006,,ConnectionError} 的子類別。當一個連線被對等端點重置時會引發此例外。對應到 @code{errno} @ref{25b2,,ECONNRESET}。
@end deffn

@geindex FileExistsError
@anchor{library/exceptions FileExistsError}@anchor{121b}
@deffn {例外} FileExistsError

當嘗試建立已存在的檔案或目錄時會引發此例外。對應到 @code{errno} @ref{25b3,,EEXIST}。
@end deffn

@geindex FileNotFoundError
@anchor{library/exceptions FileNotFoundError}@anchor{264}
@deffn {例外} FileNotFoundError

當請求不存在的檔案或目錄時會引發此例外。對應到 @code{errno} @ref{25b4,,ENOENT}。
@end deffn

@geindex InterruptedError
@anchor{library/exceptions InterruptedError}@anchor{f83}
@deffn {例外} InterruptedError

當系統呼叫被傳入的信號中斷時會引發此例外。對應到 @code{errno} @ref{f82,,EINTR}。


在 3.5 版的變更: 現在當 syscall 被信號中斷時 Python 會重試系統呼叫而不會引發 @ref{f83,,InterruptedError}，除非信號處理器引發例外（理由可參考 
@geindex Python Enhancement Proposals; PEP 475
PEP 475@footnote{https://peps.python.org/pep-0475/}）。

@end deffn

@geindex IsADirectoryError
@anchor{library/exceptions IsADirectoryError}@anchor{1254}
@deffn {例外} IsADirectoryError

當在目錄上請求檔案操作（例如 @ref{12f1,,os.remove()}）時會引發此例外。對應到 @code{errno} @ref{25b5,,EISDIR}。
@end deffn

@geindex NotADirectoryError
@anchor{library/exceptions NotADirectoryError}@anchor{1255}
@deffn {例外} NotADirectoryError

當在某個不是目錄的東西上請求目錄操作（例如 @ref{12fb,,os.listdir()}）時會引發此例外。在大多數的 POSIX 平台上，如果嘗試操作開啟或遍歷一個當作目錄的非目錄檔案也會引發此例外。對應到 @code{errno} @ref{25b6,,ENOTDIR}。
@end deffn

@geindex PermissionError
@anchor{library/exceptions PermissionError}@anchor{f39}
@deffn {例外} PermissionError

當嘗試執行一個沒有合乎存取權限的操作時會引發此例外 — 例如檔案系統權限。對應到 @code{errno} @ref{25b7,,EACCES}、@ref{1a85,,EPERM} 及 @ref{1a7a,,ENOTCAPABLE}。


在 3.11.1 版的變更: WASI 的 @ref{1a7a,,ENOTCAPABLE} 現在對應到 @ref{f39,,PermissionError}。

@end deffn

@geindex ProcessLookupError
@anchor{library/exceptions ProcessLookupError}@anchor{1256}
@deffn {例外} ProcessLookupError

當給定的行程不存在時會引發此例外。對應到 @code{errno} @ref{25b8,,ESRCH}。
@end deffn

@geindex TimeoutError
@anchor{library/exceptions TimeoutError}@anchor{a2f}
@deffn {例外} TimeoutError

當系統函式在系統層級超時會引發此例外。對應到 @code{errno} @ref{25b9,,ETIMEDOUT}。
@end deffn


在 3.3 版被加入: 加入以上所有的 @ref{2c0,,OSError} 子類別。



@subsubheading 也參考


@geindex Python Enhancement Proposals; PEP 3151
PEP 3151@footnote{https://peps.python.org/pep-3151/} — 改寫作業系統與 IO 例外階層


@node 警告,例外群組,實體例外,內建的例外
@anchor{library/exceptions warning-categories-as-exceptions}@anchor{25ba}@anchor{library/exceptions warnings}@anchor{25bb}
@subsection 警告


以下的例外是當作警告的種類使用；更多細節參考 @ref{25bc,,警告類別} 文件。

@geindex Warning
@anchor{library/exceptions Warning}@anchor{25bd}
@deffn {例外} Warning

警告種類的基礎類別。
@end deffn

@geindex UserWarning
@anchor{library/exceptions UserWarning}@anchor{25be}
@deffn {例外} UserWarning

使用者程式碼產生的警告的基礎類別。
@end deffn

@geindex DeprecationWarning
@anchor{library/exceptions DeprecationWarning}@anchor{1a3}
@deffn {例外} DeprecationWarning

關於已棄用功能的警告的基礎類別，且當那些警告是針對其他 Python 開發者。

會被預設的警告過濾器忽略，在 @code{__main__} 模組裡除外 (
@geindex Python Enhancement Proposals; PEP 565
PEP 565@footnote{https://peps.python.org/pep-0565/})。啟用 @ref{503,,Python 開發模式}會顯示此警告。

棄用原則描述在 
@geindex Python Enhancement Proposals; PEP 387
PEP 387@footnote{https://peps.python.org/pep-0387/} 裡。
@end deffn

@geindex PendingDeprecationWarning
@anchor{library/exceptions PendingDeprecationWarning}@anchor{abd}
@deffn {例外} PendingDeprecationWarning

關於過時且預期未來要被棄用，但目前尚未被棄用的功能的警告的基礎類別。

因為發出關於可能即將被棄用的警告是不尋常的，此類別很少被使用，而對已經被棄用的情況會優先使用 @ref{1a3,,DeprecationWarning}。

會被預設的警告過濾器忽略。啟用 @ref{503,,Python 開發模式}會顯示此警告。

棄用原則描述在 
@geindex Python Enhancement Proposals; PEP 387
PEP 387@footnote{https://peps.python.org/pep-0387/} 裡。
@end deffn

@geindex SyntaxWarning
@anchor{library/exceptions SyntaxWarning}@anchor{1ae}
@deffn {例外} SyntaxWarning

關於可疑語法的警告的基礎類別。

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{4d2}
@deffn {例外} RuntimeWarning

關於可疑執行環境行為的警告的基礎類別。
@end deffn

@geindex FutureWarning
@anchor{library/exceptions FutureWarning}@anchor{651}
@deffn {例外} FutureWarning

關於已棄用功能的警告的基礎類別，且當那些警告是針對以 Python 寫的應用程式的終端使用者。
@end deffn

@geindex ImportWarning
@anchor{library/exceptions ImportWarning}@anchor{717}
@deffn {例外} ImportWarning

關於在模組引入的可能錯誤的警告的基礎類別。

會被預設的警告過濾器忽略。啟用 @ref{503,,Python 開發模式}會顯示此警告。
@end deffn

@geindex UnicodeWarning
@anchor{library/exceptions UnicodeWarning}@anchor{161b}
@deffn {例外} UnicodeWarning

Unicode 相關警告的基礎類別。
@end deffn

@geindex EncodingWarning
@anchor{library/exceptions EncodingWarning}@anchor{1ff5}
@deffn {例外} EncodingWarning

編碼相關警告的基礎類別。

細節參考@ref{2007,,選擇性加入的編碼警告}。


在 3.10 版被加入.

@end deffn

@geindex BytesWarning
@anchor{library/exceptions BytesWarning}@anchor{e17}
@deffn {例外} BytesWarning

@ref{192,,bytes} 及 @ref{343,,bytearray} 相關警告的基礎類別。
@end deffn

@geindex ResourceWarning
@anchor{library/exceptions ResourceWarning}@anchor{547}
@deffn {例外} ResourceWarning

資源用法相關警告的基礎類別。

會被預設的警告過濾器忽略。啟用 @ref{503,,Python 開發模式}會顯示此警告。


在 3.2 版被加入.

@end deffn

@node 例外群組,例外階層,警告,內建的例外
@anchor{library/exceptions exception-groups}@anchor{25bf}@anchor{library/exceptions lib-exception-groups}@anchor{25c0}
@subsection 例外群組


當需要引發多個不相關例外時會使用下列的類別。它們是例外階層的一部分所以可以像所有其他例外一樣使用 @ref{1ab,,except} 來處理。此外，它們會以包含的例外型別為基礎來比對其子群組而被 @ref{1ac,,except*} 辨認出來。

@geindex ExceptionGroup
@anchor{library/exceptions ExceptionGroup}@anchor{4cd}
@deffn {例外} ExceptionGroup (msg, excs)
@end deffn

@geindex BaseExceptionGroup
@anchor{library/exceptions BaseExceptionGroup}@anchor{560}
@deffn {例外} BaseExceptionGroup (msg, excs)

這兩個例外型別都將例外包裝在序列 @code{excs} 中。@code{msg} 參數必須是字串。這兩個類別的差異是 @ref{560,,BaseExceptionGroup} 擴充了 @ref{7d0,,BaseException} 且可以包裝任何例外，而 @ref{4cd,,ExceptionGroup} 擴充了 @ref{bc4,,Exception} 且只能包裝 @ref{bc4,,Exception} 的子類別。這個設計使得 @code{except Exception} 可以捕捉 @ref{4cd,,ExceptionGroup} 但不能捕捉 @ref{560,,BaseExceptionGroup}。

如果所有包含的例外都是 @ref{bc4,,Exception} 實例，@ref{560,,BaseExceptionGroup} 建構函式會回傳 @ref{4cd,,ExceptionGroup} 而不是 @ref{560,,BaseExceptionGroup}，因此可以被使用來讓這樣的選擇自動化。另一方面來說，如果任何包含的例外不是 @ref{bc4,,Exception} 的子類別，@ref{4cd,,ExceptionGroup} 建構函式會引發 @ref{198,,TypeError}。

@geindex message (BaseExceptionGroup 的屬性)
@anchor{library/exceptions BaseExceptionGroup message}@anchor{25c1}
@deffn {屬性} message

建構函式的 @code{msg} 引數。這是一個唯讀的屬性。
@end deffn

@geindex exceptions (BaseExceptionGroup 的屬性)
@anchor{library/exceptions BaseExceptionGroup exceptions}@anchor{25c2}
@deffn {屬性} exceptions

指定給建構函式 @code{excs} 序列中的例外組成的元組。這是一個唯讀的屬性。
@end deffn

@geindex subgroup() (BaseExceptionGroup 的方法)
@anchor{library/exceptions BaseExceptionGroup subgroup}@anchor{1989}
@deffn {方法} subgroup (condition)

回傳只包含從現有群組比對到 `condition' 的例外的例外群組，或者當結果為空時回傳 @code{None}。

條件式可以是一個例外型別或是例外型別的元組，在此情況下，每個例外都會使用與 @code{except} 子句中使用的相同檢查方法來檢查是否有匹配。條件式也可以是一個可呼叫物件（除了型別物件之外），其接受一個例外作為單一引數，而如果該例外應該在子群組中就回傳 true。

現有例外的巢狀結構會保留在結果裡，其 @ref{25c1,,message}、@ref{14c7,,__traceback__}、@ref{14c9,,__cause__}、@ref{14c8,,__context__} 及 @ref{258e,,__notes__} 欄位的值也一樣。空的巢狀群組會從結果裡排除。

條件會對巢狀例外群組裡的所有例外做檢查，包括頂層及任何巢狀的例外群組。如果條件對這樣的例外群組為 true，它會被完整包含在結果裡。


在 3.13 版被加入: @code{condition} 可以是任何不是型別物件的可呼叫物件。

@end deffn

@geindex split() (BaseExceptionGroup 的方法)
@anchor{library/exceptions BaseExceptionGroup split}@anchor{1847}
@deffn {方法} split (condition)

像 @ref{1989,,subgroup()} 一樣，但回傳一對 @code{(match, rest)}，其中 @code{match} 是 @code{subgroup(condition)} 而 @code{rest} 是剩下沒有比對到的部分。
@end deffn

@geindex derive() (BaseExceptionGroup 的方法)
@anchor{library/exceptions BaseExceptionGroup derive}@anchor{1988}
@deffn {方法} derive (excs)

回傳有相同 @ref{25c1,,message} 但將例外包裝在 @code{excs} 的例外群組。

此方法被 @ref{1989,,subgroup()} 及 @ref{1847,,split()} 使用，被用來在各種情境下拆分例外群組。子類別需要覆寫它來讓 @ref{1989,,subgroup()} 及 @ref{1847,,split()} 回傳子類別而不是 @ref{4cd,,ExceptionGroup} 的實例。

@ref{1989,,subgroup()} 及 @ref{1847,,split()} 會從原始的例外群組複製 @ref{14c7,,__traceback__}、@ref{14c9,,__cause__}、@ref{14c8,,__context__} 和 @ref{258e,,__notes__} 欄位到 @ref{1988,,derive()} 所回傳的例外群組上，因此這些欄位不需要被 @ref{1988,,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

需注意 @ref{560,,BaseExceptionGroup} 定義了 @ref{799,,__new__()}，因此需要不同建構函式簽名的子類別需要覆寫它而不是 @ref{8b7,,__init__()}。例如下面定義了一個例外群組子類別接受 exit_code 並從中建構群組的訊息。：

@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

像 @ref{4cd,,ExceptionGroup} 一樣，任何 @ref{560,,BaseExceptionGroup} 的子類別且也是 @ref{bc4,,Exception} 的子類別只能包裝 @ref{bc4,,Exception} 的實例。


在 3.11 版被加入.

@end deffn

@node 例外階層,,例外群組,內建的例外
@anchor{library/exceptions exception-hierarchy}@anchor{25c3}
@subsection 例外階層


內建例外的類別階層如下：

@example
BaseException
 ├── BaseExceptionGroup
 ├── GeneratorExit
 ├── KeyboardInterrupt
 ├── SystemExit
 └── Exception
      ├── ArithmeticError
      │    ├── FloatingPointError
      │    ├── OverflowError
      │    └── ZeroDivisionError
      ├── AssertionError
      ├── AttributeError
      ├── BufferError
      ├── EOFError
      ├── ExceptionGroup [BaseExceptionGroup]
      ├── ImportError
      │    └── ModuleNotFoundError
      ├── LookupError
      │    ├── IndexError
      │    └── KeyError
      ├── MemoryError
      ├── NameError
      │    └── UnboundLocalError
      ├── OSError
      │    ├── BlockingIOError
      │    ├── ChildProcessError
      │    ├── ConnectionError
      │    │    ├── BrokenPipeError
      │    │    ├── ConnectionAbortedError
      │    │    ├── ConnectionRefusedError
      │    │    └── ConnectionResetError
      │    ├── FileExistsError
      │    ├── FileNotFoundError
      │    ├── InterruptedError
      │    ├── IsADirectoryError
      │    ├── NotADirectoryError
      │    ├── PermissionError
      │    ├── ProcessLookupError
      │    └── TimeoutError
      ├── ReferenceError
      ├── RuntimeError
      │    ├── NotImplementedError
      │    ├── PythonFinalizationError
      │    └── RecursionError
      ├── StopAsyncIteration
      ├── StopIteration
      ├── SyntaxError
      │    └── IndentationError
      │         └── TabError
      ├── SystemError
      ├── TypeError
      ├── ValueError
      │    └── UnicodeError
      │         ├── UnicodeDecodeError
      │         ├── UnicodeEncodeError
      │         └── UnicodeTranslateError
      └── Warning
           ├── BytesWarning
           ├── DeprecationWarning
           ├── EncodingWarning
           ├── FutureWarning
           ├── ImportWarning
           ├── PendingDeprecationWarning
           ├── ResourceWarning
           ├── RuntimeWarning
           ├── SyntaxWarning
           ├── UnicodeWarning
           └── UserWarning
@end example

@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{24f9}
@node 文本處理 Text Processing 服務,二進位資料服務,內建的例外,Python 標準函式庫 Standard Library
@anchor{library/text doc}@anchor{25c4}@anchor{library/text text-processing-services}@anchor{25c5}@anchor{library/text textservices}@anchor{24fc}@anchor{library/text translation-repo}@anchor{25c6}
@section 文本處理 (Text Processing) 服務


本章節介紹的模組 (module) 提供了廣泛的字串操作與其他文本處理服務。

在 @ref{25c7,,二進位資料服務} 下所描述的 @ref{1c,,codecs} 模組也與文本處理高度相關。另外也請參閱在 @ref{1ea8,,Text Sequence Type --- str} 中所描述的 Python 內建字串型別。

@menu
* string: string --- 常見的字串操作. 常見的字串操作
* string.templatelib: string templatelib --- 對模板字串字面值的支援. 對模板字串字面值的支援
* re: re --- 正規表示式 regular expression 操作. 正規表示式 (regular expression) 操作
* difflib: difflib --- 計算差異的輔助工具. 計算差異的輔助工具
* textwrap: textwrap --- 文字包裝與填充. 文字包裝與填充
* unicodedata: unicodedata --- Unicode 資料庫. Unicode 資料庫
* stringprep: stringprep --- 網際網路字串的準備. 網際網路字串的準備
* readline: readline --- GNU readline 介面. GNU readline 介面
* rlcompleter: rlcompleter --- GNU readline 的補全函式. GNU readline 的補全函式

@end menu

@node string --- 常見的字串操作,string templatelib --- 對模板字串字面值的支援,,文本處理 Text Processing 服務
@anchor{library/string doc}@anchor{25c8}@anchor{library/string module-string}@anchor{d8}@anchor{library/string string-common-string-operations}@anchor{25c9}
@subsection @code{string} --- 常見的字串操作


@geindex module; string

`原始碼：'Lib/string.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/string.py}


__________________________________________________________________



@subsubheading 也參考


@ref{1ea8,,Text Sequence Type --- str}

@ref{1ea9,,字串方法}


@menu
* 字串常數:: 
* 自訂字串格式:: 
* 格式化文字語法:: 
* 模板字串 ($-strings): 模板字串 $-strings. 
* 輔助函式:: 

@end menu

@node 字串常數,自訂字串格式,,string --- 常見的字串操作
@anchor{library/string string-constants}@anchor{25ca}
@subsubsection 字串常數


此模組中定義的常數為：

@geindex ascii_letters (於 string 模組中)
@anchor{library/string string ascii_letters}@anchor{14c4}
@deffn {資料} string.ascii_letters

下文描述的 @ref{25cb,,ascii_lowercase} 和 @ref{25cc,,ascii_uppercase} 常數的串接，該值不依賴於區域設定。
@end deffn

@geindex ascii_lowercase (於 string 模組中)
@anchor{library/string string ascii_lowercase}@anchor{25cb}
@deffn {資料} string.ascii_lowercase

小寫字母 @code{'abcdefghijklmnopqrstuvwxyz'}。該值與地區設定無關且不會改變。
@end deffn

@geindex ascii_uppercase (於 string 模組中)
@anchor{library/string string ascii_uppercase}@anchor{25cc}
@deffn {資料} string.ascii_uppercase

大寫字母 @code{'ABCDEFGHIJKLMNOPQRSTUVWXYZ'}。此值與地區設定無關且不會改變。
@end deffn

@geindex digits (於 string 模組中)
@anchor{library/string string digits}@anchor{25cd}
@deffn {資料} string.digits

字串 @code{'0123456789'}。
@end deffn

@geindex hexdigits (於 string 模組中)
@anchor{library/string string hexdigits}@anchor{25ce}
@deffn {資料} string.hexdigits

字串 @code{'0123456789abcdefABCDEF'}。
@end deffn

@geindex octdigits (於 string 模組中)
@anchor{library/string string octdigits}@anchor{25cf}
@deffn {資料} string.octdigits

字串 @code{'01234567'}。
@end deffn

@geindex punctuation (於 string 模組中)
@anchor{library/string string punctuation}@anchor{25d0}
@deffn {資料} string.punctuation

在 @code{C} 語言中被視為標點符號的 ASCII 字元的字串：@code{!"#$%&'()*+,-./:;<=>?@@[\]^_`@{|@}~}。
@end deffn

@geindex printable (於 string 模組中)
@anchor{library/string string printable}@anchor{182d}
@deffn {資料} string.printable

ASCII 字元的字串被 Python 是為可被列印輸出的。這是 @ref{25cd,,digits}、@ref{14c4,,ascii_letters}、@ref{25d0,,punctuation} 和 @ref{25d1,,whitespace} 的組合。

@cartouche
@quotation 備註 
By design, @ref{fd3,,string.printable.isprintable()}
returns @ref{d23,,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{25d1}
@deffn {資料} string.whitespace

包含所有 ASCII 字元的字串都視為空白字元 (whitespace)。 包含空格 (space)、製表符號 (tab)、換行符號 (linefeed)、return、換頁符號 (formfeed) 和垂直製表符號 (vertical tab) 這些字元。
@end deffn

@node 自訂字串格式,格式化文字語法,字串常數,string --- 常見的字串操作
@anchor{library/string custom-string-formatting}@anchor{25d2}@anchor{library/string string-formatting}@anchor{24fb}
@subsubsection 自訂字串格式


透過 
@geindex Python Enhancement Proposals; PEP 3101
PEP 3101@footnote{https://peps.python.org/pep-3101/} 中描述的 @ref{82c,,format()} 方法，內建字串類別提供了進行複雜變數替換和數值格式化的能力。@ref{d8,,string} 模組中的 @ref{10b8,,Formatter} 類別模組可讓你使用與內建 @ref{82c,,format()} 方法相同的實作來建立和自訂你自己的字串格式化行為。

@geindex Formatter (string 中的類別)
@anchor{library/string string Formatter}@anchor{10b8}
@deffn {類別} string.Formatter

@ref{10b8,,Formatter} 類別有以下的公開方法：

@geindex format() (string.Formatter 的方法)
@anchor{library/string string Formatter format}@anchor{df5}
@deffn {方法} format (format_string, /, *args, **kwargs)

主要的 API 方法。它接收一個格式字串及一組任意的位置引數與關鍵字引數，是呼叫 @ref{25d3,,vformat()} 的包裝器 (wrapper)。


在 3.7 版的變更: 現在格式字串引數是@ref{c6f,,僅限位置參數}。

@end deffn

@geindex vformat() (string.Formatter 的方法)
@anchor{library/string string Formatter vformat}@anchor{25d3}
@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.  @ref{25d3,,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 @ref{10b8,,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{25d4}
@deffn {方法} parse (format_string)

將 format_string 放入迴圈，並回傳一個可疊代物件，其元素為 (`literal_text', `field_name', `format_spec', `conversion')。這會被 @ref{25d3,,vformat()} 用於將字串裁切為字面文本或替換欄位。

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{25d3,,vformat()}.
@end deffn

@geindex get_field() (string.Formatter 的方法)
@anchor{library/string string Formatter get_field}@anchor{25d5}
@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{25d4,,parse()} is done by
@ref{25d3,,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
@ref{25d3,,vformat()}. The return value `used_key' has the same meaning
as the `key' parameter to @ref{25d6,,get_value()}.
@end deffn

@geindex get_value() (string.Formatter 的方法)
@anchor{library/string string Formatter get_value}@anchor{25d6}
@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{25d3,,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
@ref{25d6,,get_value()} to be called with a `key' argument of 0.  The @code{name}
attribute will be looked up after @ref{25d6,,get_value()} returns by calling the
built-in @ref{dc5,,getattr()} function.

If the index or keyword refers to an item that does not exist, then an
@ref{1729,,IndexError} or @ref{5df,,KeyError} should be raised.
@end deffn

@geindex check_unused_args() (string.Formatter 的方法)
@anchor{library/string string Formatter check_unused_args}@anchor{25d7}
@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.  @ref{25d7,,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{25d8}
@deffn {方法} format_field (value, format_spec)

@ref{25d8,,format_field()} simply calls the global @ref{199,,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{25d9}
@deffn {方法} convert_field (value, conversion)

Converts the value (returned by @ref{25d5,,get_field()}) given a conversion type
(as in the tuple returned by the @ref{25d4,,parse()} method).  The default
version understands 's' (str), 'r' (repr) and 'a' (ascii) conversion
types.
@end deffn
@end deffn

@node 格式化文字語法,模板字串 $-strings,自訂字串格式,string --- 常見的字串操作
@anchor{library/string format-string-syntax}@anchor{25da}@anchor{library/string formatstrings}@anchor{1593}
@subsubsection 格式化文字語法


The @ref{82c,,str.format()} method and the @ref{10b8,,Formatter} class share the same
syntax for format strings (although in the case of @ref{10b8,,Formatter},
subclasses can define their own format string syntax).  The syntax is
related to that of @ref{19a,,formatted string literals} and
@ref{1780,,template string literals}, but it is less sophisticated
and, in particular, does not support arbitrary expressions in interpolations.

@geindex @{@} （花括號）;於字串格式化
@geindex . （點）;於字串格式化
@geindex [] （方括號）;於字串格式化
@geindex ! （驚嘆號）;於字串格式化
@geindex ; （冒號）;於字串格式化

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{25db}replacement_field: "@{" [@ref{25dc,,field_name}] ["!" @ref{25dd,,conversion}] [":" @ref{25de,,format_spec}] "@}"
@anchor{library/string grammar-token-format-string-field_name}@anchor{25dc}field_name:        @ref{25df,,arg_name} ("." @ref{25e0,,attribute_name} | "[" @ref{25e1,,element_index} "]")*
@anchor{library/string grammar-token-format-string-arg_name}@anchor{25df}arg_name:          [@ref{2185,,identifier} | @ref{21c7,,digit}+]
@anchor{library/string grammar-token-format-string-attribute_name}@anchor{25e0}attribute_name:    @ref{2185,,identifier}
@anchor{library/string grammar-token-format-string-element_index}@anchor{25e1}element_index:     @ref{21c7,,digit}+ | @ref{25e2,,index_string}
@anchor{library/string grammar-token-format-string-index_string}@anchor{25e2}index_string:      <any source character except "]"> +
@anchor{library/string grammar-token-format-string-conversion}@anchor{25dd}conversion:        "r" | "s" | "a"
@anchor{library/string grammar-token-format-string-format_spec}@anchor{25de}format_spec:       @ref{25e3,,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.

另請參閱 @ref{4f4,,格式規格 (Format Specification) 迷你語言} 部份。

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{24d7,,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{dc5,,getattr()}, while an expression of the form @code{'[index]'}
does an index lookup using @ref{582,,__getitem__()}.


在 3.1 版的變更: The positional argument specifiers can be omitted for @ref{82c,,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{10b8,,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{25e4}
The `conversion' field causes a type coercion before formatting.  Normally, the
job of formatting a value is done by the @ref{82a,,__format__()} method of the value
itself.  However, in some cases it is desirable to force a type to be formatted
as a string, overriding its own definition of formatting.  By converting the
value to a string before calling @ref{82a,,__format__()}, the normal formatting logic
is bypassed.

目前支援三種轉換旗標：@code{'!s'} 會對該值呼叫 @ref{169,,str()}，@code{'!r'} 會對該值呼叫 @ref{1c1,,repr()}，而 @code{'!a'} 則會對該值呼叫 @ref{15dd,,ascii()}。

一些範例：

@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

`format_spec' 欄位描述了值的呈現規格，例如欄位寬度、對齊、填充 (padding)、小數精度等細節資訊。每種值類型都可以定義自己的「格式化迷你語言 (formatting mini-language)」或對 `format_spec' 的解釋。

大多數內建型別都支援常見的格式化迷你語言，下一節將會詳細說明。

`format_spec' 欄位還可以在其內部包含巢狀的替換欄位。這些巢狀的替換欄位可能包含欄位名稱、轉換旗標、格式規格描述，但是不允許再更深層的巢狀結構。format_spec 內部的替換欄位會在 `format_spec' 字串被直譯前被替換。這讓數值的格式能夠被動態地指定。

範例請見 @ref{25e5,,格式範例}。

@menu
* 格式規格 (Format Specification) 迷你語言: 格式規格 Format Specification 迷你語言. 
* 格式範例:: 

@end menu

@node 格式規格 Format Specification 迷你語言,格式範例,,格式化文字語法
@anchor{library/string format-specification-mini-language}@anchor{25e6}@anchor{library/string formatspec}@anchor{4f4}
@subsubsection 格式規格 (Format Specification) 迷你語言


「格式規格」在格式字串 (format string) 中包含的替換欄位中使用，以定義各個值如何被呈現（請參考 @ref{1593,,格式化文字語法}、@ref{19a,,f-string（f 字串）} 和 @ref{1780,,t-string（t 字串）}）。它們也能夠直接傳遞給內建的 @ref{199,,format()} 函式。每個可格式化型別 (formattable type) 可以定義格式規格如何被直譯。

大部分內建型別為了格式規格實作了下列選項，不過有些選項只被數值型別支援。

一般來說，輸入空格式規格會產生和對值呼叫 @ref{169,,str()} 函式相同的結果，非空的格式規格才會修改結果。

`標準格式說明符號 (standard format specifier)' 的一般型式如下：

@example
@anchor{library/string grammar-token-format-spec-format_spec}@anchor{25e3}format_spec:             [@ref{25e7,,options}][@ref{25e8,,width_and_precision}][@ref{25e9,,type}]
@anchor{library/string grammar-token-format-spec-options}@anchor{25e7}options:                 [[@ref{25ea,,fill}]@ref{25eb,,align}][@ref{25ec,,sign}]["z"]["#"]["0"]
@anchor{library/string grammar-token-format-spec-fill}@anchor{25ea}fill:                    <any character>
@anchor{library/string grammar-token-format-spec-align}@anchor{25eb}align:                   "<" | ">" | "=" | "^"
@anchor{library/string grammar-token-format-spec-sign}@anchor{25ec}sign:                    "+" | "-" | " "
@anchor{library/string grammar-token-format-spec-width_and_precision}@anchor{25e8}width_and_precision:     [@ref{25ed,,width_with_grouping}][@ref{25ee,,precision_with_grouping}]
@anchor{library/string grammar-token-format-spec-width_with_grouping}@anchor{25ed}width_with_grouping:     [@ref{25ef,,width}][@ref{25f0,,grouping}]
@anchor{library/string grammar-token-format-spec-precision_with_grouping}@anchor{25ee}precision_with_grouping: "." [@ref{25f1,,precision}][@ref{25f0,,grouping}] | "." @ref{25f0,,grouping}
@anchor{library/string grammar-token-format-spec-width}@anchor{25ef}width:                   @ref{21c7,,digit}+
@anchor{library/string grammar-token-format-spec-precision}@anchor{25f1}precision:               @ref{21c7,,digit}+
@anchor{library/string grammar-token-format-spec-grouping}@anchor{25f0}grouping:                "," | "_"
@anchor{library/string grammar-token-format-spec-type}@anchor{25e9}type:                    "b" | "c" | "d" | "e" | "E" | "f" | "F" | "g"
                         | "G" | "n" | "o" | "s" | "x" | "X" | "%"
@end example

如果給定了一個有效的 `align' 值，則可以在它之前加一個 `fill' 字元，且該字元可為任意字元，若不加的話預設為空格。使用@ref{19a,,格式字串}或 @ref{82c,,str.format()} 時是無法在其中使用大括號（"@code{@{}" 或 "@code{@}}"）作為 `fill' 字元的，但仍可透過巢狀替換欄位的方式插入大括號。此限制不影響 @ref{199,,format()} 函式。

The meaning of the various alignment options is as follows:

@geindex < （小於）;於字串格式化
@geindex > （大於）;於字串格式化
@geindex = （等號）;於字串格式化
@geindex ^ （插入符號）;於字串格式化


@multitable {xxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

選項

@tab

含義

@item

@code{'<'}

@tab

強制欄位在可用空間內靠左對齊（這是大多數物件的預設值）。

@item

@code{'>'}

@tab

強制欄位在可用空間內靠右對齊（這是數字的預設值）。

@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{197,,complex}.
It becomes the default for numbers when '0' immediately
precedes the field width.

@item

@code{'^'}

@tab

強制欄位在可用空間內置中。

@end multitable


請注意，除非有定義了最小欄位寬度，否則欄位寬度將始終與填充它的資料大小相同，故在該情況下的對齊選項是沒有意義的。

`sign' 選項只適用於數字型別，並可為以下之一：

@geindex + （加號）;於字串格式化
@geindex - （減號）;於字串格式化
@geindex 空格;於字串格式化


@multitable {xxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

選項

@tab

含義

@item

@code{'+'}

@tab

表示正數與負數均需使用符號。

@item

@code{'-'}

@tab

表示正數應使用前導空格，負數應使用減號。

@item

空格

@tab

表示正數應使用前導空格，負數應使用減號。

@end multitable


@geindex z;於字串格式化

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 版的變更: 新增 @code{'z'} 選項（請見 
@geindex Python Enhancement Proposals; PEP 682
PEP 682@footnote{https://peps.python.org/pep-0682/}）。


@geindex # （井字號）;於字串格式化

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.

`width' 是一個十進位整數，定義了最小總欄位寬度，包括任何前綴、分隔符號和其他格式字元。如果未指定，則欄位寬度將由內容決定。

當未給予明確的對齊指示，在 `width' 欄位前面填入零 (@code{'0'}) 字元將會為 @ref{197,,complex} 以外的數值型別啟用有符號察覺的零填充 (sign-aware zero-padding)。這相當於使用 @code{'0'} 為 `fill' 字元且對齊類型為 @code{'='}。


在 3.10 版的變更: 在 `width' 欄位前面加上 @code{'0'} 不再影響字串的預設對齊方式。


`precision' 是一個十進位整數，指定表示類型 @code{'f'} 和 @code{'F'} 的小數點後應顯示多少位，或表示類型 @code{'g'} 或 @code{'G'} 的小數點前後應顯示多少位。對於字串表示類型，該欄位指定最大欄位大小 - 換言之，將使用欄位中的多少字元。整數表示類型不允許使用 `precision'。

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{} （逗號）;於字串格式化
@geindex _ （底線）;於字串格式化


@multitable {xxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

選項

@tab

含義

@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

在整數表示型別 @code{'d'} 和浮點數表示型別中，每 3 位數插入一個底線，這不包括 @code{'n'}。對於整數表示型別 @code{'b'}，@code{'o'}，@code{'x'} 和 @code{'X'}，每 4 位數字會插入底線。對於其他表示型別來說此選項並不支援。

@end multitable


For a locale aware separator, use the @code{'n'} presentation type instead.


在 3.1 版的變更: 新增 @code{','} 選項（請見 
@geindex Python Enhancement Proposals; PEP 378
PEP 378@footnote{https://peps.python.org/pep-0378/}）。



在 3.6 版的變更: 新增 @code{'_'} 選項（請見 
@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.


最終，型別決定了資料將會如何呈現

可用的字串表示型別有：

@quotation


@multitable {xxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

型別

@tab

含義

@item

@code{'s'}

@tab

String format. This is the default type for strings and
may be omitted.

@item

None

@tab

與 @code{'s'} 相同。

@end multitable

@end quotation

The available integer presentation types are:

@quotation


@multitable {xxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

型別

@tab

含義

@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

十六進位格式。輸出以 16 為基數的數字，9 以上的數字使用小寫字母。

@item

@code{'X'}

@tab

十六進位格式。輸出以 16 為基數的數字，9 以上的數字使用大寫字母。如果指定了 @code{'#'}，則前綴 @code{'0x'} 也會被轉成大寫的 @code{'0X'}。

@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

與 @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{196,,float()} is used to convert the
integer to a floating-point number before formatting.

The available presentation types for @ref{196,,float} and
@ref{1fe,,Decimal} values are:

@quotation


@multitable {xxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

型別

@tab

含義

@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{196,,float}, and shows all coefficient digits
for @ref{1fe,,Decimal}.  If @code{p=0}, the decimal
point is omitted unless the @code{#} option is used.

@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{196,,float}, and uses a
precision large enough to show all coefficient digits
for @ref{1fe,,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{1fe,,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{196,,float}. For
@ref{1fe,,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{196,,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{1fe,,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{169,,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{196,,float} matches that
of the @ref{14db,,round()} builtin.  For @ref{1fe,,Decimal}, the rounding
mode of the current @ref{25f2,,context} will be used.

The available presentation types for @ref{197,,complex} are the same as those for
@ref{196,,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{169,,str()} (complex numbers with
a non-zero real part are also surrounded by parentheses), possibly altered by
other format modifiers.

@node 格式範例,,格式規格 Format Specification 迷你語言,格式化文字語法
@anchor{library/string format-examples}@anchor{25f3}@anchor{library/string formatexamples}@anchor{25e5}
@subsubsection 格式範例


本節包含 @ref{82c,,str.format()} 語法以及與舊式 @code{%} 格式的比較。

此語法在大多情況下與舊式的 @code{%} 格式類似，只是增加了 @code{@{@}} 和 @code{:} 來取代 @code{%}。例如，@code{'%03.2f'} 可以改寫為 @code{'@{:03.2f@}'}。

新的語法還支援新的選項，將在以下的範例中說明。

按位置存取引數：

@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')      # 解包引數序列
'c, b, a'
>>> '@{0@}@{1@}@{0@}'.format('abra', 'cad')   # 引數索引可以重複
'abracadabra'
@end example

按名稱存取引數：

@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

存取引數的屬性：

@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

存取引數的內容：

@example
>>> coord = (3, 5)
>>> 'X: @{0[0]@};  Y: @{0[1]@}'.format(coord)
'X: 3;  Y: 5'
@end example

替換 @code{%s} 和 @code{%r}：

@example
>>> "repr() shows quotes: @{!r@}; str() doesn't: @{!s@}".format('test1', 'test2')
"repr() shows quotes: 'test1'; str() doesn't: test2"
@end example

對齊文字以及指定寬度：

@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

替換 @code{%+f}、@code{%-f} 和 @code{% f} 以及指定正負號：

@example
>>> '@{:+f@}; @{:+f@}'.format(3.14, -3.14)  # 總會顯示
'+3.140000; -3.140000'
>>> '@{: f@}; @{: f@}'.format(3.14, -3.14)  # 若為正數則顯示空格
' 3.140000; -3.140000'
>>> '@{:-f@}; @{:-f@}'.format(3.14, -3.14)  # 只顯示負號 -- 與 '@{:f@}; @{:f@}' 相同
'3.140000; -3.140000'
@end example

替換 @code{%x} 和 @code{%o} 並將其值轉換為不同的進位制：

@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

使用逗號或底線作為數字分組分隔符號：

@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

表示為百分比：

@example
>>> points = 19
>>> total = 22
>>> 'Correct answers: @{:.2%@}'.format(points/total)
'Correct answers: 86.36%'
@end example

作為特定型別格式：

@example
>>> import datetime
>>> d = datetime.datetime(2010, 7, 4, 12, 15, 58)
>>> '@{:%Y-%m-%d %H:%M:%S@}'.format(d)
'2010-07-04 12:15:58'
@end example

巢狀引數及更多複雜範例：

@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 模板字串 $-strings,輔助函式,格式化文字語法,string --- 常見的字串操作
@anchor{library/string template-strings-pep292}@anchor{25f4}@anchor{library/string template-strings-strings}@anchor{25f5}
@subsubsection 模板字串 ($-strings)


@cartouche
@quotation 備註 
The feature described here was introduced in Python 2.4;
a simple templating method based upon regular expressions.
It predates @ref{82c,,str.format()}, @ref{19a,,formatted string literals},
and @ref{25f6,,template string literals}.

It is unrelated to template string literals (t-strings),
which were introduced in Python 3.14.
These evaluate to  @ref{16a,,string.templatelib.Template} objects,
found in the @ref{d9,,string.templatelib} module.
@end quotation
@end cartouche

模板字串提供如 
@geindex Python Enhancement Proposals; PEP 292
PEP 292@footnote{https://peps.python.org/pep-0292/} 所述更簡單的字串替換。模板字串的主要用例是國際化 (i18n)，因為在這種情況下，更簡單的語法和功能使得它比其他 Python 內建字串格式化工具更容易翻譯。基於模板字串建構的 i18n 函式庫範例，請參閱 flufl.i18n@footnote{https://flufli18n.readthedocs.io/en/latest/} 套件。

@geindex $ （金錢符號）;於 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{2eb,,ValueError}
being raised.

The @ref{d8,,string} module provides a @ref{890,,Template} class that implements
these rules.  The methods of @ref{890,,Template} are:

@geindex Template (string 中的類別)
@anchor{library/string string Template}@anchor{890}
@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{1f9c}
@deffn {方法} substitute (mapping=@{@}, /, **kwds)

進行模板替換，並回傳一個新的字串。 `mapping' 是任何有金鑰並符合模板裡佔位符號的字典型物件。或者如果關鍵字就是佔位符號時，你也可以改提供關鍵字引數。當 `mapping' 跟 `kwds' 同時給定並存在重複時，`kwds' 的佔位符號會被優先使用。
@end deffn

@geindex safe_substitute() (string.Template 的方法)
@anchor{library/string string Template safe_substitute}@anchor{1f9d}
@deffn {方法} safe_substitute (mapping=@{@}, /, **kwds)

類似於 @ref{1f9c,,substitute()}，但如果 `mapping' 與 `kwds' 中缺少佔位符號的話，原始的佔位符號會完整地出現在結果字串裡，而不會引發 @ref{5df,,KeyError} 例外。此外，與 @ref{1f9c,,substitute()} 不同的是，任何包含 @code{$} 的字句會直接回傳 @code{$} 而非引發 @ref{2eb,,ValueError}。

雖然仍可能發生其他例外，但這個方法被認為是「安全」的，因為它總是試圖回傳一個有用的字串而不是引發例外。從另一個角度來看，@ref{1f9d,,safe_substitute()} 可能並非完全安全，因為它會默默忽略格式錯誤的模板，這些模板包含了多餘的左右定界符、不匹配的括號，或者不是有效的 Python 識別字的佔位符號。
@end deffn

@geindex is_valid() (string.Template 的方法)
@anchor{library/string string Template is_valid}@anchor{88f}
@deffn {方法} is_valid ()

如果模板有將導致 @ref{1f9c,,substitute()} 引發 @ref{2eb,,ValueError} 的無效佔位符號，就會回傳 @code{False}。


在 3.11 版被加入.

@end deffn

@geindex get_identifiers() (string.Template 的方法)
@anchor{library/string string Template get_identifiers}@anchor{88e}
@deffn {方法} get_identifiers ()

回傳模板中有效識別字的串列，按照它們首次出現的順序，並忽略任何無效的識別字。


在 3.11 版被加入.

@end deffn

@ref{890,,Template} 實例也提供一個公開的資料屬性：

@geindex template (string.Template 的屬性)
@anchor{library/string string Template template}@anchor{25f7}
@deffn {屬性} template

這是傳遞給建構函式 `template' 引數的物件。一般來說，你不應該改變它，但並沒有強制設定成唯讀。
@end deffn
@end deffn

以下是如何使用 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

進階用法：你可以衍生 @ref{890,,Template} 類別來自定義佔位符號語法、左右定界符字元，或者用於剖析模板字串的正規表示式。你可以透過覆寫這些類別屬性來達成：


@itemize *

@item 
`delimiter' -- 這是描述引入左右定界符的文字字串。預設值是 @code{$}。請注意這`不是'正規表示式，因為實作會在需要時對這個字串呼叫 @ref{dfe,,re.escape()}。也請注意你不能在建立類別後修改左右定界符。（意即在子類別的命名空間中必須設置不同的左右定界符）

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


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


在 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' -- 此群組與跳脫序列匹配，例如在預設模式下為 @code{$$}。

@item 
`named' -- 此群組與不帶大括號的佔位符號名稱匹配；它不應包含擷取群組中的左右定界符號。

@item 
`braced' -- 此群組與大括號括起來的佔位符號名稱匹配；它不應在擷取群組中包含左右定界符或大括號。

@item 
`invalid' -- 此群組與任何其他左右定界符模式（通常是單一左右定界符）匹配，且它應該出現在正規表示式的最後。
@end itemize

當此模式有匹配於模板但這些命名組中卻有任一個不匹配，此類別的方法將引發 @ref{2eb,,ValueError}。

@node 輔助函式,,模板字串 $-strings,string --- 常見的字串操作
@anchor{library/string helper-functions}@anchor{25f8}
@subsubsection 輔助函式


@geindex capwords() (於 string 模組中)
@anchor{library/string string capwords}@anchor{24ff}
@deffn {函式} string.capwords (s, sep=None)

使用 @ref{10a5,,str.split()} 將引數分割為字詞，使用 @ref{24e8,,str.capitalize()} 將每個單字大寫，並使用 @ref{24b9,,str.join()} 將大寫字詞連接起來。如果可選的第二引數 `sep' 不存在或為 @code{None}，則連續的空白字元將替換為單一空格，並且刪除前導和尾隨空白；在其他情況下則使用 `sep' 來分割和連接單字。
@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 --- 對模板字串字面值的支援,re --- 正規表示式 regular expression 操作,string --- 常見的字串操作,文本處理 Text Processing 服務
@anchor{library/string templatelib doc}@anchor{25f9}@anchor{library/string templatelib module-string templatelib}@anchor{d9}@anchor{library/string templatelib string-templatelib-support-for-template-string-literals}@anchor{25fa}@anchor{library/string templatelib translation-repo}@anchor{25fb}
@subsection @code{string.templatelib} --- 對模板字串字面值的支援


@geindex module; string.templatelib

`原始碼：'Lib/string/templatelib.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/string/templatelib.py}


__________________________________________________________________



@subsubheading 也參考



@itemize *

@item 
@ref{19a,,格式字串}

@item 
@ref{1780,,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
* 模板字串:: 
* Types:: 
* Helper functions:: 

@end menu

@node 模板字串,Types,,string templatelib --- 對模板字串字面值的支援
@anchor{library/string templatelib id1}@anchor{25fc}@anchor{library/string templatelib template-strings}@anchor{25f6}
@subsubsection 模板字串



在 3.14 版被加入.


Template strings are a mechanism for custom string processing.
They have the full flexibility of Python's @ref{19a,,f-string（f 字串）},
but return a @ref{16a,,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,模板字串,string templatelib --- 對模板字串字面值的支援
@anchor{library/string templatelib types}@anchor{25fd}
@subsubsection Types


@geindex Template (string.templatelib 中的類別)
@anchor{library/string templatelib string templatelib Template}@anchor{16a}
@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{1780,,template string literal syntax}.
This syntax is identical to that of @ref{19a,,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{25fe,,strings}
and dynamic @ref{25ff,,interpolations}.
A @ref{2600,,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{25fe}
@deffn {屬性} strings: @ref{60c,,tuple}[@ref{169,,str}, ...]

A @ref{60c,,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{25ff}
@deffn {屬性} interpolations: @ref{60c,,tuple}[@ref{16b,,Interpolation}, ...]

A @ref{60c,,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{2600}
@deffn {屬性} values: @ref{60c,,tuple}[@ref{c75,,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 方法


@geindex __new__() (string.templatelib.Template 的方法)
@anchor{library/string templatelib string templatelib Template __new__}@anchor{2601}
@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{25fe,,strings} attribute. For example,
the following code creates a @ref{16a,,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{25fe,,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{16b,,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{16b}
@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{a07,,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{2602}
@deffn {屬性} value: @ref{c75,,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{2603}
@deffn {屬性} expression: @ref{169,,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{21b9}
@deffn {屬性} conversion: @ref{a4e,,Literal}['a', 'r', 's'] | @ref{87e,,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{2604,,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{2605}
@deffn {屬性} format_spec: @ref{169,,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{199,,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 @ref{199,,format()} protocol.
@end quotation
@end cartouche
@end deffn

@subsubheading 方法


@geindex __new__() (string.templatelib.Interpolation 的方法)
@anchor{library/string templatelib string templatelib Interpolation __new__}@anchor{2606}
@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{1593,,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{4f4,,format specification} to present the value.
@end itemize

@end deffn
@end deffn

@node Helper functions,,Types,string templatelib --- 對模板字串字面值的支援
@anchor{library/string templatelib helper-functions}@anchor{2607}
@subsubsection Helper functions


@geindex convert() (於 string.templatelib 模組中)
@anchor{library/string templatelib string templatelib convert}@anchor{2604}
@deffn {函式} string.templatelib.convert (obj, /, conversion)

Applies formatted string literal @ref{25e4,,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{169,,str()} on the value (like @code{!s}),

@item 
@code{'r'} which calls @ref{1c1,,repr()} (like @code{!r}), and

@item 
@code{'a'} which calls @ref{15dd,,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 操作,difflib --- 計算差異的輔助工具,string templatelib --- 對模板字串字面值的支援,文本處理 Text Processing 服務
@anchor{library/re doc}@anchor{2608}@anchor{library/re module-re}@anchor{be}@anchor{library/re re-regular-expression-operations}@anchor{2609}@anchor{library/re translation-repo}@anchor{260a}
@subsection @code{re} --- 正規表示式 (regular expression) 操作


@geindex module; re

`原始碼：'Lib/re/@footnote{https://github.com/python/cpython/tree/3.14/Lib/re/}


__________________________________________________________________


此模組提供類似於 Perl 中正規表示式的配對操作。

被搜尋的模式 (pattern) 與字串可以是 Unicode 字串 (@ref{169,,str})，也可以是 8-bit 字串 (@ref{192,,bytes})。然而，Unicode 字串和 8-bit 字串不能混用：也就是，你不能用 byte 模式配對 Unicode 字串，反之亦然；同樣地，替換時，用來替換的字串必須與模式和搜尋字串是相同的型別 (type)。

正規表示式使用反斜線字元 (@code{'\'}) 表示特別的形式，或是使用特殊字元而不呼叫它們的特殊意義。這與 Python 在字串文本 (literal) 中，為了一樣的目的使用同一個字元的目的相衝突；舉例來說，為了配對一個反斜線文字，一個人可能需要寫 @code{'\\\\'} 當作模式字串，因為正規表示式必須是 @code{\\}，而且每個反斜線在一個普通的 Python 字串文本中必須表示為 @code{\\}。另外，請注意在 Python 的字串文本中使用反斜線的任何無效跳脫序列目前會產生一個 @ref{1ae,,SyntaxWarning}，而在未來這會變成一個 @ref{18e,,SyntaxError}。儘管它對正規表示式是一個有效的跳脫序列，這種行為也會發生。

解決方法是對正規表示式模式使用 Python 的原始字串符號；反斜線在一個以 @code{'r'} 為前綴的字串文本中不會被用任何特別的方式處理。所以 @code{r"\n"} 是一個兩個字元的字串，包含 @code{'\'} 和 @code{'n'}，同時 @code{"\n"} 是一個單個字元的字串，包含一個換行符號。通常模式在 Python 程式中會使用這個原始字串符號表示。

請務必注意到大部分的正規表示式操作是可以在模組層級的函式和 @ref{1182,,compiled regular expressions} 中的方法使用的。這些函式是個捷徑且讓你不需要先編譯一個正規表示式物件，但是會缺少一些微調參數。


@subsubheading 也參考


第三方的 regex@footnote{https://pypi.org/project/regex/} 模組，有著和標準函式庫 @ref{be,,re} 模組相容的 API，但是提供額外的功能以及更完整的 Unicode 支援。


@menu
* 正規表示式語法:: 
* 模組內容:: 
* Regular Expression Objects:: 
* Match Objects:: 
* Regular Expression Examples:: 

@end menu

@node 正規表示式語法,模組內容,,re --- 正規表示式 regular expression 操作
@anchor{library/re re-syntax}@anchor{926}@anchor{library/re regular-expression-syntax}@anchor{260b}
@subsubsection 正規表示式語法


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{260c,,[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{260d,,如何使用正規表示式}.

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 . （點）;於正規表示式中


@table @asis

@item @code{.}

(Dot.)  In the default mode, this matches any character except a newline.  If
the @ref{260e,,DOTALL} flag has been specified, this matches any character
including a newline.  @code{(?s:.)} matches any character regardless of flags.
@end table

@geindex ^ （插入符號）;於正規表示式中


@table @asis

@item @code{^}

(Caret.)  Matches the start of the string, and in @ref{260f,,MULTILINE} mode also
matches immediately after each newline.
@end table

@geindex $ （金錢符號）;於正規表示式中


@table @asis

@item @code{$}

Matches the end of the string or just before the newline at the end of the
string, and in @ref{260f,,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 @ref{260f,,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 * （星號）;於正規表示式中


@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 + （加號）;於正規表示式中


@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 ? （問號）;於正規表示式中


@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 *?;於正規表示式中
@geindex +?;於正規表示式中
@geindex ??;於正規表示式中


@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 *+;於正規表示式中
@geindex ++;於正規表示式中
@geindex ?+;於正規表示式中


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


在 3.11 版被加入.

@end table

@geindex @{@} （花括號）;於正規表示式中


@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}
attempt to match 5 @code{'a'} characters, then, requiring 2 more @code{'a'}s,
will need more characters than available and thus fail, while
@code{a@{3,5@}aa} will match with @code{a@{3,5@}} capturing 5, then 4 @code{'a'}s
by backtracking and then the final 2 @code{'a'}s are matched by the final
@code{aa} in the pattern.
@code{x@{m,n@}+} is equivalent to @code{(?>x@{m,n@})}.


在 3.11 版被加入.

@end table

@geindex \ （反斜線）;於正規表示式中


@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 [] （方括號）;於正規表示式中


@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 - （減號）;於正規表示式中


@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 \ （反斜線）;於正規表示式中


@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 ^ （插入符號）;於正規表示式中


@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{651,,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{651,,FutureWarning} is raised if a character set contains constructs
that will change semantically in the future.

@end table

@geindex | （垂直線）;於正規表示式中


@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 () （圓括號）;於正規表示式中


@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 (?;於正規表示式中


@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{2610,,re.A} (ASCII-only matching)

@item 
@ref{2611,,re.I} (ignore case)

@item 
@ref{2612,,re.L} (locale dependent)

@item 
@ref{2613,,re.M} (multi-line)

@item 
@ref{2614,,re.S} (dot matches all)

@item 
@ref{2615,,re.U} (Unicode matching)

@item 
@ref{2616,,re.X} (verbose)
@end itemize

(The flags are described in @ref{2617,,模組內容}.)
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{dc9,,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 (?;;於正規表示式中


@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{2610,,re.A} (ASCII-only matching)

@item 
@ref{2611,,re.I} (ignore case)

@item 
@ref{2612,,re.L} (locale dependent)

@item 
@ref{2613,,re.M} (multi-line)

@item 
@ref{2614,,re.S} (dot matches all)

@item 
@ref{2615,,re.U} (Unicode matching)

@item 
@ref{2616,,re.X} (verbose)
@end itemize

(The flags are described in @ref{2617,,模組內容}.)

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.


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


在 3.11 版被加入.

@end table

@geindex (?P<;於正規表示式中


@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{192,,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{192,,bytes} patterns, group `name' can only contain bytes
in the ASCII range (@code{b'\x00'}-@code{b'\x7f'}).

@end table

@geindex (?P=;於正規表示式中


@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 (?#;於正規表示式中


@table @asis

@item @code{(?#...)}

A comment; the contents of the parentheses are simply ignored.
@end table

@geindex (?=;於正規表示式中


@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 (?!;於正規表示式中


@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 (?<=;於正規表示式中


@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{142d,,search()} function rather than the @ref{142e,,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 (?<!;於正規表示式中


@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 (?(;於正規表示式中
@anchor{library/re re-conditional-expression}@anchor{1a69}

@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{192,,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{2618}
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 \ （反斜線）;於正規表示式中


@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;於正規表示式中


@table @asis

@item @code{\A}

Matches only at the start of the string.
@end table

@geindex \b;於正規表示式中


@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{838,,ASCII} flag.
Word boundaries are determined by the current locale
if the @ref{d5b,,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;於正規表示式中


@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{838,,ASCII} flag.
Word boundaries are determined by the current locale
if the @ref{d5b,,LOCALE} flag is used.


在 3.14 版的變更: @code{\B} now matches empty input string.

@end table

@geindex \d;於正規表示式中


@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{838,,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;於正規表示式中


@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{838,,ASCII} flag is used.
@end table

@geindex \s;於正規表示式中


@table @asis

@item @code{\s}


@table @asis

@item For Unicode (str) patterns:

Matches Unicode whitespace characters (as defined by @ref{24e3,,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{838,,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;於正規表示式中


@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{838,,ASCII} flag is used.
@end table

@geindex \w;於正規表示式中


@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{24db,,str.isalnum()}),
as well as the underscore (@code{_}).

Matches @code{[a-zA-Z0-9_]} if the @ref{838,,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{d5b,,LOCALE} flag is used,
matches characters considered alphanumeric in the current locale and the underscore.
@end table
@end table

@geindex \W;於正規表示式中


@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{24db,,str.isalnum()} returns @code{False}.

Matches @code{[^a-zA-Z0-9_]} if the @ref{838,,ASCII} flag is used.

If the @ref{d5b,,LOCALE} flag is used,
matches characters which are neither alphanumeric in the current locale
nor the underscore.
@end table

@geindex \z;於正規表示式中
@geindex \Z;於正規表示式中


@table @asis

@item @code{\z}

Matches only at the end of the string.


在 3.14 版被加入.


@item @code{\Z}

The same as @code{\z}.  For compatibility with old Python versions.
@end table

@geindex \a;於正規表示式中
@geindex \b;於正規表示式中
@geindex \f;於正規表示式中
@geindex \n;於正規表示式中
@geindex \N;於正規表示式中
@geindex \r;於正規表示式中
@geindex \t;於正規表示式中
@geindex \u;於正規表示式中
@geindex \U;於正規表示式中
@geindex \v;於正規表示式中
@geindex \x;於正規表示式中
@geindex \\;於正規表示式中

Most of the @ref{680,,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 模組內容,Regular Expression Objects,正規表示式語法,re --- 正規表示式 regular expression 操作
@anchor{library/re contents-of-module-re}@anchor{2617}@anchor{library/re module-contents}@anchor{2619}
@subsubsection 模組內容


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
* 旗標:: 
* 函式: 函式<2>. 
* 例外: 例外<2>. 

@end menu

@node 旗標,函式<2>,,模組內容
@anchor{library/re flags}@anchor{261a}
@subsubsection 旗標



在 3.6 版的變更: Flag constants are now instances of @ref{837,,RegexFlag}, which is a subclass of
@ref{e95,,enum.IntFlag}.


@geindex RegexFlag (re 中的類別)
@anchor{library/re re RegexFlag}@anchor{837}
@deffn {類別} re.RegexFlag

An @ref{e95,,enum.IntFlag} class containing the regex options listed below.


在 3.11 版被加入: - added to @code{__all__}

@end deffn

@geindex A (於 re 模組中)
@geindex ASCII (於 re 模組中)
@anchor{library/re re A}@anchor{2610}
@deffn {資料} re.A
@anchor{library/re re ASCII}@anchor{838}
@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{2615,,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{d5c,,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{261b}
@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{2611}
@deffn {資料} re.I
@anchor{library/re re IGNORECASE}@anchor{19e5}
@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{838,,ASCII} flag
is used to disable non-ASCII matches.
The current locale does not change the effect of this flag
unless the @ref{d5b,,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{19e5,,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{838,,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{2612}
@deffn {資料} re.L
@anchor{library/re re LOCALE}@anchor{d5b}
@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{d5b,,LOCALE} can be used only with bytes patterns
and is not compatible with @ref{838,,ASCII}.



在 3.7 版的變更: Compiled regular expression objects with the @ref{d5b,,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{2613}
@deffn {資料} re.M
@anchor{library/re re MULTILINE}@anchor{260f}
@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{261c}
@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(text, flag=re.NOFLAG):
    return re.match(text, flag)
@end example


在 3.11 版被加入.

@end deffn

@geindex S (於 re 模組中)
@geindex DOTALL (於 re 模組中)
@anchor{library/re re S}@anchor{2614}
@deffn {資料} re.S
@anchor{library/re re DOTALL}@anchor{260e}
@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{2615}
@deffn {資料} re.U
@anchor{library/re re UNICODE}@anchor{d5c}
@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{838,,ASCII} to restrict matching to ASCII characters instead.
@end deffn

@geindex X (於 re 模組中)
@geindex VERBOSE (於 re 模組中)
@anchor{library/re re X}@anchor{2616}
@deffn {資料} re.X
@anchor{library/re re VERBOSE}@anchor{261d}
@deffnx {資料} re.VERBOSE

@geindex # （井字號）;於正規表示式中

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 函式<2>,例外<2>,旗標,模組內容
@anchor{library/re functions}@anchor{261e}
@subsubsection 函式


@geindex compile() (於 re 模組中)
@anchor{library/re re compile}@anchor{dc9}
@deffn {函式} re.compile (pattern, flags=0)

將正規表示式模式編譯成@ref{1182,,正規表示式物件}，可以使用它的 @ref{261f,,match()}、@ref{2620,,search()} 等方法來匹配，如下所述。

可以透過指定 `flags' 值來修改運算式的行為，值可以是任何 @ref{261a,,flags} 變數，使用位元 OR（bitwise OR、@code{|} 運算子）組合。

順序為：

@example
prog = re.compile(pattern)
result = prog.match(string)
@end example

等價於：

@example
result = re.match(pattern, string)
@end example

但是當表示式在單一程式中多次使用時，使用 @ref{dc9,,re.compile()} 並保存產生的正規表示式物件以供重複使用會更有效率。

@cartouche
@quotation 備註 
傳遞給 @ref{dc9,,re.compile()} 之最新模式的編譯版本和模組層級匹配函式都會被快取，因此一次僅使用幾個正規表示式的程式不必去擔心編譯正規表示式。
@end quotation
@end cartouche
@end deffn

@geindex search() (於 re 模組中)
@anchor{library/re re search}@anchor{142d}
@deffn {函式} re.search (pattern, string, flags=0)

掃描 `string' 以尋找正規表示式 `pattern' 產生匹配的第一個位置，並回傳對應的 @ref{ebe,,Match}。如果字串中沒有與模式匹配的位置則回傳 @code{None}；請注意，這與在字串中的某個點查找零長度匹配不同。

可以透過指定 `flags' 值來修改運算式的行為，值可以是任何 @ref{261a,,flags} 變數，使用位元 OR（bitwise OR、@code{|} 運算子）組合。
@end deffn

@geindex match() (於 re 模組中)
@anchor{library/re re match}@anchor{142e}
@deffn {函式} re.match (pattern, string, flags=0)

如果 `string' 開頭的零個或多個字元與正規表示式 `pattern' 匹配，則回傳對應的 @ref{ebe,,Match}。如果字串與模式不匹配，則回傳 @code{None}；請注意，這與零長度匹配不同。

請注意，即使在 @ref{260f,,MULTILINE} 模式 (mode) 下，@ref{142e,,re.match()} 只會於字串的開頭匹配，而非每行的開頭。

如果你想在 `string' 中的任何位置找到匹配項，請使用 @ref{142d,,search()}（另請參閱 @ref{2621,,search() vs. match()}）。

可以透過指定 `flags' 值來修改運算式的行為，值可以是任何 @ref{261a,,flags} 變數，使用位元 OR（bitwise OR、@code{|} 運算子）組合。
@end deffn

@geindex fullmatch() (於 re 模組中)
@anchor{library/re re fullmatch}@anchor{1180}
@deffn {函式} re.fullmatch (pattern, string, flags=0)

如果整個 `string' 與正規表示式 `pattern' 匹配，則回傳對應的 @ref{ebe,,Match}。如果字串與模式不匹配，則回傳 @code{None}；請注意，這與零長度匹配不同。

可以透過指定 `flags' 值來修改運算式的行為，值可以是任何 @ref{261a,,flags} 變數，使用位元 OR（bitwise OR、@code{|} 運算子）組合。


在 3.4 版被加入.

@end deffn

@geindex split() (於 re 模組中)
@anchor{library/re re split}@anchor{59c}
@deffn {函式} re.split (pattern, string, maxsplit=0, flags=0)

依 `pattern' 的出現次數拆分 `string'。如果在 `pattern' 中使用捕獲括號，則模式中所有群組的文字也會作為結果串列的一部分回傳。如果 `maxsplit' 非零，則最多發生 `maxsplit' 次拆分，並且字串的其餘部分會作為串列的最終元素回傳。

@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

如果分隔符號中有捕獲群組並且它在字串的開頭匹配，則結果將以空字串開頭。這同樣適用於字串的結尾：

@example
>>> re.split(r'(\W+)', '...words, words...')
['@w{'}, '...', 'words', ', ', 'words', '...', '@w{'}]
@end example

如此一來，分隔符號元件始終可以在結果串列中的相同相對索引處找到。

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

可以透過指定 `flags' 值來修改運算式的行為，值可以是任何 @ref{261a,,flags} 變數，使用位元 OR（bitwise OR、@code{|} 運算子）組合。


在 3.1 版的變更: 新增可選的旗標引數。



在 3.7 版的變更: 新增了對可以匹配空字串之模式進行拆分的支援。



在 3.13 版之後被棄用: 將 `maxsplit' 和 `flags' 作為位置引數傳遞的用法已被棄用。在未來的 Python 版本中，它們將會是@ref{59f,,僅限關鍵字參數}。

@end deffn

@geindex findall() (於 re 模組中)
@anchor{library/re re findall}@anchor{1225}
@deffn {函式} re.findall (pattern, string, flags=0)

以字串或元組串列的形式回傳 `string' 中 `pattern' 的所有非重疊匹配項。從左到右掃描 `string'，並按找到的順序回傳符合項目。結果中會包含空匹配項。

結果取決於模式中捕獲群組的數量。如果沒有群組，則回傳與整個模式匹配的字串串列。如果恰好存在一個群組，則回傳與該群組匹配的字串串列。如果存在多個群組，則回傳與群組匹配的字串元組串列。非捕獲群組則不影響結果的形式。

@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

可以透過指定 `flags' 值來修改運算式的行為，值可以是任何 @ref{261a,,flags} 變數，使用位元 OR（bitwise OR、@code{|} 運算子）組合。


在 3.7 版的變更: 非空匹配現在可以剛好在前一個空匹配的後面開始。

@end deffn

@geindex finditer() (於 re 模組中)
@anchor{library/re re finditer}@anchor{16ee}
@deffn {函式} re.finditer (pattern, string, flags=0)

回傳一個 @ref{4c3,,iterator}，在 `string' 中的 RE `pattern' 的所有非重疊匹配上 yield @ref{ebe,,Match} 物件。從左到右掃描 `string'，並按找到的順序回傳匹配項目。結果中包含空匹配項。

可以透過指定 `flags' 值來修改運算式的行為，值可以是任何 @ref{261a,,flags} 變數，使用位元 OR（bitwise OR、@code{|} 運算子）組合。


在 3.7 版的變更: 非空匹配現在可以剛好在前一個空匹配的後面開始。

@end deffn

@geindex sub() (於 re 模組中)
@anchor{library/re re sub}@anchor{59d}
@deffn {函式} re.sub (pattern, repl, string, count=0, flags=0)

回傳透過以替換 `repl' 取代 `string' 中最左邊不重疊出現的 `pattern' 所獲得的字串。如果未找到該模式，則不改變 `string' 並回傳。`repl' 可以是字串或函式；如果它是字串，則處理其中的任何反斜線跳脫。也就是說 @code{\n} 會被轉換為單一換行符、@code{\r} 會被轉換為回車符 (carriage return) 等等。ASCII 字母的未知跳脫符會被保留以供將來使用並被視為錯誤。其他未知跳脫符例如 @code{\&} 會被單獨保留。例如 @code{\6} 的反向參照將被替換為模式中第 6 組匹配的子字串。例如：

@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

如果 `repl' 是一個函式，則 `pattern' 的每個不重疊出現之處都會呼叫它。此函式接收單一 @ref{ebe,,Match} 引數，並回傳替換字串。例如：

@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

此模式可以是字串或 @ref{1a96,,Pattern}。

可選引數 `count' 是要替換的模式出現的最大次數；`count' 必須是非負整數。如果省略或為零，則所有出現的內容都將被替換。

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;於正規表示式中

在字串型別 `repl' 引數中，除了上述字元跳脫和反向參照之外，@code{\g<name>} 將使用名為 @code{name} 的群組所匹配到的子字串，如 @code{(?P<name>...)} 所定義的語法。@code{\g<number>} 使用對應的群組編號；因此 @code{\g<2>} 等價於 @code{\2}，但在諸如 @code{\g<2>0} 之類的替換中並非模糊不清 (isn't ambiguous)。@code{\20} 將被直譯為對群組 20 的參照，而不是對後面跟著字面字元 @code{'0'} 的群組 2 的參照。反向參照 @code{\g<0>} 會取代以 RE 所匹配到的整個子字串。

可以透過指定 `flags' 值來修改運算式的行為，值可以是任何 @ref{261a,,flags} 變數，使用位元 OR（bitwise OR、@code{|} 運算子）組合。


在 3.1 版的變更: 新增可選的旗標引數。



在 3.5 版的變更: 不匹配的群組將被替換為空字串。



在 3.6 版的變更: 在由 @code{'\'} 和一個 ASCII 字母組成之 `pattern' 中的未知跳脫符現在為錯誤。



在 3.7 版的變更: 由 @code{'\'} 和一個 ASCII 字母組成之 `repl' 中的未知跳脫符現在為錯誤。非空匹配後可以緊接著出現空匹配。



在 3.12 版的變更: 群組 `id' 只能包含 ASCII 數字。在 @ref{192,,bytes} 替換字串中，群組 `name' 只能包含 ASCII 範圍內的位元組 (@code{b'\x00'}-@code{b'\x7f'})。



在 3.13 版之後被棄用: 將 `count' 和 `flags' 作為位置引數傳遞的用法已被棄用。在未來的 Python 版本中，它們將會是@ref{59f,,僅限關鍵字參數}。

@end deffn

@geindex subn() (於 re 模組中)
@anchor{library/re re subn}@anchor{59e}
@deffn {函式} re.subn (pattern, repl, string, count=0, flags=0)

執行與 @ref{59d,,sub()} 相同的操作，但回傳一個元組 @code{(new_string, number_of_subs_made)}。

可以透過指定 `flags' 值來修改運算式的行為，值可以是任何 @ref{261a,,flags} 變數，使用位元 OR（bitwise OR、@code{|} 運算子）組合。
@end deffn

@geindex escape() (於 re 模組中)
@anchor{library/re re escape}@anchor{dfe}
@deffn {函式} re.escape (pattern)

對 `pattern' 中的特殊字元進行跳脫。如果你想要匹配其中可能包含正規表示式元字元 (metacharacter) 的任意文本字串，這會非常有用。例如：

@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

此函式不得用於 @ref{59d,,sub()} 和 @ref{59e,,subn()} 中的替換字串，僅應跳脫反斜線。例如：

@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 版的變更: @code{'_'} 字元不再被跳脫。



在 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{2622}
@deffn {函式} re.purge ()

清除正規表示式快取。
@end deffn

@node 例外<2>,,函式<2>,模組內容
@anchor{library/re exceptions}@anchor{2623}
@subsubsection 例外


@geindex PatternError
@anchor{library/re re PatternError}@anchor{541}
@deffn {例外} re.PatternError (msg, pattern=None, pos=None)

當傳遞給此處函式之一的字串不是有效的正規表示式（例如它可能包含不匹配的括號）或在編譯或匹配期間發生某些其他錯誤時，將引發例外。如果字串不包含模式匹配項，則絕不是錯誤。@code{PatternError} 實例具有以下附加屬性：

@geindex msg (re.PatternError 的屬性)
@anchor{library/re re PatternError msg}@anchor{1046}
@deffn {屬性} msg

未格式化的錯誤訊息。
@end deffn

@geindex pattern (re.PatternError 的屬性)
@anchor{library/re re PatternError pattern}@anchor{1047}
@deffn {屬性} pattern

正規表示式模式。
@end deffn

@geindex pos (re.PatternError 的屬性)
@anchor{library/re re PatternError pos}@anchor{1048}
@deffn {屬性} pos

`pattern' 中編譯失敗的索引（可能是 @code{None}）。
@end deffn

@geindex lineno (re.PatternError 的屬性)
@anchor{library/re re PatternError lineno}@anchor{1049}
@deffn {屬性} lineno

對應 `pos' 的列（可能是 @code{None}）。
@end deffn

@geindex colno (re.PatternError 的屬性)
@anchor{library/re re PatternError colno}@anchor{104a}
@deffn {屬性} colno

對應 `pos' 的欄（可能是 @code{None}）。
@end deffn


在 3.5 版的變更: 新增額外屬性。



在 3.13 版的變更: @code{PatternError} 最初被命名為 @code{error}；後者為了向後相容性而被保留為別名。

@end deffn

@node Regular Expression Objects,Match Objects,模組內容,re --- 正規表示式 regular expression 操作
@anchor{library/re re-objects}@anchor{1182}@anchor{library/re regular-expression-objects}@anchor{2624}
@subsubsection Regular Expression Objects


@geindex Pattern (re 中的類別)
@anchor{library/re re Pattern}@anchor{1a96}
@deffn {類別} re.Pattern

Compiled regular expression object returned by @ref{dc9,,re.compile()}.


在 3.9 版的變更: @ref{1a96,,re.Pattern} supports @code{[]} to indicate a Unicode (str) or bytes pattern.
See @ref{8b8,,泛型別名型別}.

@end deffn

@geindex search() (re.Pattern 的方法)
@anchor{library/re re Pattern search}@anchor{2620}
@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{ebe,,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 match() (re.Pattern 的方法)
@anchor{library/re re Pattern match}@anchor{261f}
@deffn {方法} Pattern.match (string[, pos[, endpos]])

If zero or more characters at the `beginning' of `string' match this regular
expression, return a corresponding @ref{ebe,,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{2620,,search()} method.

@example
>>> pattern = re.compile("o")
>>> pattern.match("dog")      # No match as "o" is not at the start of "dog".
>>> pattern.match("dog", 1)   # Match as "o" is the 2nd character of "dog".
<re.Match object; span=(1, 2), match='o'>
@end example

If you want to locate a match anywhere in `string', use
@ref{2620,,search()} instead (see also @ref{2621,,search() vs. match()}).
@end deffn

@geindex fullmatch() (re.Pattern 的方法)
@anchor{library/re re Pattern fullmatch}@anchor{1181}
@deffn {方法} Pattern.fullmatch (string[, pos[, endpos]])

If the whole `string' matches this regular expression, return a corresponding
@ref{ebe,,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{2620,,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


在 3.4 版被加入.

@end deffn

@geindex split() (re.Pattern 的方法)
@anchor{library/re re Pattern split}@anchor{2625}
@deffn {方法} Pattern.split (string, maxsplit=0)

Identical to the @ref{59c,,split()} function, using the compiled pattern.
@end deffn

@geindex findall() (re.Pattern 的方法)
@anchor{library/re re Pattern findall}@anchor{2626}
@deffn {方法} Pattern.findall (string[, pos[, endpos]])

Similar to the @ref{1225,,findall()} function, using the compiled pattern, but
also accepts optional `pos' and `endpos' parameters that limit the search
region like for @ref{142d,,search()}.
@end deffn

@geindex finditer() (re.Pattern 的方法)
@anchor{library/re re Pattern finditer}@anchor{2627}
@deffn {方法} Pattern.finditer (string[, pos[, endpos]])

Similar to the @ref{16ee,,finditer()} function, using the compiled pattern, but
also accepts optional `pos' and `endpos' parameters that limit the search
region like for @ref{142d,,search()}.
@end deffn

@geindex sub() (re.Pattern 的方法)
@anchor{library/re re Pattern sub}@anchor{2628}
@deffn {方法} Pattern.sub (repl, string, count=0)

Identical to the @ref{59d,,sub()} function, using the compiled pattern.
@end deffn

@geindex subn() (re.Pattern 的方法)
@anchor{library/re re Pattern subn}@anchor{2629}
@deffn {方法} Pattern.subn (repl, string, count=0)

Identical to the @ref{59e,,subn()} function, using the compiled pattern.
@end deffn

@geindex flags (re.Pattern 的屬性)
@anchor{library/re re Pattern flags}@anchor{262a}
@deffn {屬性} Pattern.flags

The regex matching flags.  This is a combination of the flags given to
@ref{dc9,,compile()}, any @code{(?...)} inline flags in the pattern, and implicit
flags such as @ref{d5c,,UNICODE} if the pattern is a Unicode string.
@end deffn

@geindex groups (re.Pattern 的屬性)
@anchor{library/re re Pattern groups}@anchor{262b}
@deffn {屬性} Pattern.groups

The number of capturing groups in the pattern.
@end deffn

@geindex groupindex (re.Pattern 的屬性)
@anchor{library/re re Pattern groupindex}@anchor{262c}
@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{262d}
@deffn {屬性} Pattern.pattern

The pattern string from which the pattern object was compiled.
@end deffn


在 3.7 版的變更: Added support of @ref{750,,copy.copy()} and @ref{d5d,,copy.deepcopy()}.  Compiled
regular expression objects are considered atomic.


@node Match Objects,Regular Expression Examples,Regular Expression Objects,re --- 正規表示式 regular expression 操作
@anchor{library/re id3}@anchor{262e}@anchor{library/re match-objects}@anchor{1183}
@subsubsection Match Objects


Match objects always have a boolean value of @code{True}.
Since @ref{261f,,match()} and @ref{2620,,search()} return @code{None}
when there is no match, you can test whether there was a match with a simple
@code{if} statement:

@example
match = re.search(pattern, string)
if match:
    process(match)
@end example

@geindex Match (re 中的類別)
@anchor{library/re re Match}@anchor{ebe}
@deffn {類別} re.Match

Match object returned by successful @code{match}es and @code{search}es.


在 3.9 版的變更: @ref{ebe,,re.Match} supports @code{[]} to indicate a Unicode (str) or bytes match.
See @ref{8b8,,泛型別名型別}.

@end deffn

@geindex expand() (re.Match 的方法)
@anchor{library/re re Match expand}@anchor{262f}
@deffn {方法} Match.expand (template)

Return the string obtained by doing backslash substitution on the template
string `template', as done by the @ref{2628,,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 版的變更: 不匹配的群組將被替換為空字串。

@end deffn

@geindex group() (re.Match 的方法)
@anchor{library/re re Match group}@anchor{1226}
@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 in the inclusive range
[1..99], 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{1729,,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.match(r"(\w+) (\w+)", "Isaac Newton, physicist")
>>> m.group(0)       # The entire match
'Isaac Newton'
>>> m.group(1)       # The first parenthesized subgroup.
'Isaac'
>>> m.group(2)       # The second parenthesized subgroup.
'Newton'
>>> m.group(1, 2)    # Multiple arguments give us a tuple.
('Isaac', 'Newton')
@end example

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{1729,,IndexError}
exception is raised.

A moderately complicated example:

@example
>>> m = re.match(r"(?P<first_name>\w+) (?P<last_name>\w+)", "Malcolm Reynolds")
>>> m.group('first_name')
'Malcolm'
>>> m.group('last_name')
'Reynolds'
@end example

Named groups can also be referred to by their index:

@example
>>> m.group(1)
'Malcolm'
>>> m.group(2)
'Reynolds'
@end example

If a group matches multiple times, only the last match is accessible:

@example
>>> m = re.match(r"(..)+", "a1b2c3")  # Matches 3 times.
>>> m.group(1)                        # Returns only the last match.
'c3'
@end example
@end deffn

@geindex __getitem__() (re.Match 的方法)
@anchor{library/re re Match __getitem__}@anchor{2630}
@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.match(r"(\w+) (\w+)", "Isaac Newton, physicist")
>>> m[0]       # The entire match
'Isaac Newton'
>>> m[1]       # The first parenthesized subgroup.
'Isaac'
>>> m[2]       # The second parenthesized subgroup.
'Newton'
@end example

Named groups are supported as well:

@example
>>> m = re.match(r"(?P<first_name>\w+) (?P<last_name>\w+)", "Isaac Newton")
>>> m['first_name']
'Isaac'
>>> m['last_name']
'Newton'
@end example


在 3.6 版被加入.

@end deffn

@geindex groups() (re.Match 的方法)
@anchor{library/re re Match groups}@anchor{1227}
@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}.

舉例來說：

@example
>>> m = re.match(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.match(r"(\d+)\.?(\d+)?", "24")
>>> m.groups()      # Second group defaults to None.
('24', None)
>>> m.groups('0')   # Now, the second group defaults to '0'.
('24', '0')
@end example
@end deffn

@geindex groupdict() (re.Match 的方法)
@anchor{library/re re Match groupdict}@anchor{2631}
@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.match(r"(?P<first_name>\w+) (?P<last_name>\w+)", "Malcolm Reynolds")
>>> m.groupdict()
@{'first_name': 'Malcolm', 'last_name': 'Reynolds'@}
@end example
@end deffn

@geindex start() (re.Match 的方法)
@geindex end() (re.Match 的方法)
@anchor{library/re re Match start}@anchor{2632}
@deffn {方法} Match.start ([group])
@anchor{library/re re Match end}@anchor{2633}
@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{1729,,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{2634}
@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{2635}
@deffn {屬性} Match.pos

The value of `pos' which was passed to the @ref{2620,,search()} or
@ref{261f,,match()} method of a @ref{1182,,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{2636}
@deffn {屬性} Match.endpos

The value of `endpos' which was passed to the @ref{2620,,search()} or
@ref{261f,,match()} method of a @ref{1182,,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{2637}
@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{2638}
@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{2639}
@deffn {屬性} Match.re

The @ref{1182,,regular expression object} whose @ref{261f,,match()} or
@ref{2620,,search()} method produced this match instance.
@end deffn

@geindex string (re.Match 的屬性)
@anchor{library/re re Match string}@anchor{263a}
@deffn {屬性} Match.string

The string passed to @ref{261f,,match()} or @ref{2620,,search()}.
@end deffn


在 3.7 版的變更: Added support of @ref{750,,copy.copy()} and @ref{d5d,,copy.deepcopy()}.  Match objects
are considered atomic.


@node Regular Expression Examples,,Match Objects,re --- 正規表示式 regular expression 操作
@anchor{library/re re-examples}@anchor{145e}@anchor{library/re regular-expression-examples}@anchor{263b}
@subsubsection Regular Expression Examples


@menu
* Checking for a Pair:: 
* 模擬 scanf(): 模擬 scanf. 
* search() vs. match(): search 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,模擬 scanf,,Regular Expression Examples
@anchor{library/re checking-for-a-pair}@anchor{263c}
@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 = re.compile(r"^[a2-9tjqk]@{5@}$")
>>> displaymatch(valid.match("akt5q"))  # Valid.
"<Match: 'akt5q', groups=()>"
>>> displaymatch(valid.match("akt5e"))  # Invalid.
>>> displaymatch(valid.match("akt"))    # Invalid.
>>> displaymatch(valid.match("727ak"))  # Valid.
"<Match: '727ak', groups=()>"
@end example

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.compile(r".*(.).*\1")
>>> displaymatch(pair.match("717ak"))     # Pair of 7s.
"<Match: '717', groups=('7',)>"
>>> displaymatch(pair.match("718ak"))     # No pairs.
>>> displaymatch(pair.match("354aa"))     # Pair of aces.
"<Match: '354aa', groups=('a',)>"
@end example

To find out what card the pair consists of, one could use the
@ref{1226,,group()} method of the match object in the following manner:

@example
>>> pair = re.compile(r".*(.).*\1")
>>> pair.match("717ak").group(1)
'7'

# Error because re.match() returns None, which doesn't have a group() method:
>>> pair.match("718ak").group(1)
Traceback (most recent call last):
  File "<pyshell#23>", line 1, in <module>
    re.match(r".*(.).*\1", "718ak").group(1)
AttributeError: 'NoneType' object has no attribute 'group'

>>> pair.match("354aa").group(1)
'a'
@end example

@node 模擬 scanf,search vs match,Checking for a Pair,Regular Expression Examples
@anchor{library/re simulating-scanf}@anchor{263d}
@subsubsection 模擬 scanf()


@geindex scanf（C 函式）

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 match,Making a Phonebook,模擬 scanf,Regular Expression Examples
@anchor{library/re id4}@anchor{263e}@anchor{library/re search-vs-match}@anchor{2621}
@subsubsection search() vs. match()


Python offers different primitive operations based on regular expressions:


@itemize +

@item 
@ref{142e,,re.match()} checks for a match only at the beginning of the string

@item 
@ref{142d,,re.search()} checks for a match anywhere in the string
(this is what Perl does by default)

@item 
@ref{1180,,re.fullmatch()} checks for entire string to be a match
@end itemize

舉例來說：

@example
>>> re.match("c", "abcdef")    # No match
>>> re.search("c", "abcdef")   # Match
<re.Match object; span=(2, 3), match='c'>
>>> re.fullmatch("p.*n", "python") # Match
<re.Match object; span=(0, 6), match='python'>
>>> re.fullmatch("r.*n", "python") # No match
@end example

Regular expressions beginning with @code{'^'} can be used with @ref{142d,,search()} to
restrict the match at the beginning of the string:

@example
>>> re.match("c", "abcdef")    # No match
>>> re.search("^c", "abcdef")  # No match
>>> re.search("^a", "abcdef")  # Match
<re.Match object; span=(0, 1), match='a'>
@end example

Note however that in @ref{260f,,MULTILINE} mode @ref{142e,,match()} only matches at the
beginning of the string, whereas using @ref{142d,,search()} with a regular expression
beginning with @code{'^'} will match at the beginning of each line.

@example
>>> re.match("X", "A\nB\nX", re.MULTILINE)  # No match
>>> re.search("^X", "A\nB\nX", re.MULTILINE)  # Match
<re.Match object; span=(4, 5), match='X'>
@end example

@node Making a Phonebook,Text Munging,search vs match,Regular Expression Examples
@anchor{library/re making-a-phonebook}@anchor{263f}
@subsubsection Making a Phonebook


@ref{59c,,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{59c,,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{2640}
@subsubsection Text Munging


@ref{59d,,sub()} replaces every occurrence of a pattern with a string or the
result of a function.  This example demonstrates using @ref{59d,,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{2641}
@subsubsection Finding all Adverbs


@ref{1225,,findall()} matches `all' occurrences of a pattern, not just the first
one as @ref{142d,,search()} does.  For example, if a writer wanted to
find all of the adverbs in some text, they might use @ref{1225,,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{2642}
@subsubsection Finding all Adverbs and their Positions


If one wants more information about all matches of a pattern than the matched
text, @ref{16ee,,finditer()} is useful as it provides @ref{ebe,,Match} objects
instead of strings.  Continuing with the previous example, if a writer wanted
to find all of the adverbs `and their positions' in some text, they would use
@ref{16ee,,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{2643}
@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.match(r"\W(.)\1\W", " ff ")
<re.Match object; span=(0, 4), match=' ff '>
>>> re.match("\\W(.)\\1\\W", " ff ")
<re.Match object; span=(0, 4), match=' ff '>
@end example

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.match(r"\\", r"\\")
<re.Match object; span=(0, 1), match='\\'>
>>> re.match("\\\\", 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{2644}
@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: 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{260c}@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 --- 計算差異的輔助工具,textwrap --- 文字包裝與填充,re --- 正規表示式 regular expression 操作,文本處理 Text Processing 服務
@anchor{library/difflib doc}@anchor{2645}@anchor{library/difflib difflib-helpers-for-computing-deltas}@anchor{2646}@anchor{library/difflib module-difflib}@anchor{3b}@anchor{library/difflib translation-repo}@anchor{2647}
@subsection @code{difflib} --- 計算差異的輔助工具


@geindex module; difflib

@c Markup by Fred L. Drake, Jr. <fdrake@acm.org>

`原始碼：'Lib/difflib.py@footnote{https://github.com/python/cpython/tree/3.14/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{5e,,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{81d,,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{1214,,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{1214,,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 @ref{1214,,SequenceMatcher}.


在 3.2 版的變更: 新增 `autojunk' 參數。

@end deffn

@geindex Differ (difflib 中的類別)
@anchor{library/difflib difflib Differ}@anchor{2648}
@deffn {類別} difflib.Differ

This is a class for comparing sequences of lines of text, and producing
human-readable differences or deltas.  Differ uses @ref{1214,,SequenceMatcher}
both to compare sequences of lines, and to compare sequences of characters
within similar (near-matching) lines.

Each line of a @ref{2648,,Differ} delta begins with a two-letter code:


@multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

程式碼

@tab

含義

@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{201}
@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{2649}
@deffn {方法} __init__ (tabsize=8, wrapcolumn=None, linejunk=None, charjunk=IS_CHARACTER_JUNK)

Initializes instance of @ref{201,,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{264a,,ndiff()}
(used by @ref{201,,HtmlDiff} to generate the side by side HTML differences).  See
@ref{264a,,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{feb}
@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{264b}
@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{feb,,make_file()}
method.
@end deffn
@end deffn

@geindex context_diff() (於 difflib 模組中)
@anchor{library/difflib difflib context_diff}@anchor{18e1}
@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{125c,,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{264c,,io.IOBase.readlines()} result in diffs that are suitable for use with
@ref{264d,,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

一個更詳盡的範例請見 @ref{264e,,difflib 的命令列介面}。
@end deffn

@geindex get_close_matches() (於 difflib 模組中)
@anchor{library/difflib difflib get_close_matches}@anchor{264f}
@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{264a}
@deffn {函式} difflib.ndiff (a, b, linejunk=None, charjunk=IS_CHARACTER_JUNK)

Compare `a' and `b' (lists of strings); return a @ref{2648,,Differ}-style
delta (a @ref{125c,,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{2d7,,IS_LINE_JUNK()}, which filters out lines
without visible characters, except for at most one hash character (@code{'#'})
-- however the underlying @ref{1214,,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{2650,,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{2651}
@deffn {函式} difflib.restore (sequence, which)

Return one of the two sequences that generated a delta.

Given a `sequence' produced by @ref{2652,,Differ.compare()} or @ref{264a,,ndiff()}, extract
lines originating from file 1 or 2 (parameter `which'), stripping off line
prefixes.

範例：

@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{18e0}
@deffn {函式} difflib.unified_diff (a, b, fromfile='@w{'}, tofile='@w{'}, fromfiledate='@w{'}, tofiledate='@w{'}, n=3, lineterm='\n')

Compare `a' and `b' (lists of strings); return a delta (a @ref{125c,,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{264c,,io.IOBase.readlines()} result in diffs that are suitable for use with
@ref{264d,,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 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

一個更詳盡的範例請見 @ref{264e,,difflib 的命令列介面}。
@end deffn

@geindex diff_bytes() (於 difflib 模組中)
@anchor{library/difflib difflib diff_bytes}@anchor{fec}
@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{18e0,,unified_diff()} or
@ref{18e1,,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'.


在 3.5 版被加入.

@end deffn

@geindex IS_LINE_JUNK() (於 difflib 模組中)
@anchor{library/difflib difflib IS_LINE_JUNK}@anchor{2d7}
@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{264a,,ndiff()} in older versions.
@end deffn

@geindex IS_CHARACTER_JUNK() (於 difflib 模組中)
@anchor{library/difflib difflib IS_CHARACTER_JUNK}@anchor{2650}
@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{264a,,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 物件:: 
* SequenceMatcher 範例:: 
* Differ Objects:: 
* Differ Example:: 
* difflib 的命令列介面:: 
* ndiff 範例：:: 

@end menu

@node SequenceMatcher 物件,SequenceMatcher 範例,,difflib --- 計算差異的輔助工具
@anchor{library/difflib sequence-matcher}@anchor{2653}@anchor{library/difflib sequencematcher-objects}@anchor{2654}
@subsubsection SequenceMatcher 物件


The @ref{1214,,SequenceMatcher} class has this constructor:

@geindex SequenceMatcher (difflib 中的類別)
@anchor{library/difflib difflib SequenceMatcher}@anchor{1214}
@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{81d,,hashable}.

The optional argument `autojunk' can be used to disable the automatic junk
heuristic.


在 3.2 版的變更: 新增 `autojunk' 參數。


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{2655,,set_seqs()} or @ref{2656,,set_seq2()}.


在 3.2 版被加入: The `bjunk' and `bpopular' attributes.


@ref{1214,,SequenceMatcher} 物件有以下方法：

@geindex set_seqs() (difflib.SequenceMatcher 的方法)
@anchor{library/difflib difflib SequenceMatcher set_seqs}@anchor{2655}
@deffn {方法} set_seqs (a, b)

Set the two sequences to be compared.
@end deffn

@ref{1214,,SequenceMatcher} computes and caches detailed information about the
second sequence, so if you want to compare one sequence against many
sequences, use @ref{2656,,set_seq2()} to set the commonly used sequence once and
call @ref{2657,,set_seq1()} repeatedly, once for each of the other sequences.

@geindex set_seq1() (difflib.SequenceMatcher 的方法)
@anchor{library/difflib difflib SequenceMatcher set_seq1}@anchor{2657}
@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{2656}
@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{1c14}
@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}, @ref{1c14,,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{857,,named tuple} @code{Match(a, b, size)}.


在 3.9 版的變更: 新增預設引數。

@end deffn

@geindex get_matching_blocks() (difflib.SequenceMatcher 的方法)
@anchor{library/difflib difflib SequenceMatcher get_matching_blocks}@anchor{2658}
@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{2659}
@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

含義

@item

@code{'replace'}

@tab

@code{a[i1:i2]} 應該被替換為 @code{b[j1:j2]}。

@item

@code{'delete'}

@tab

@code{a[i1:i2]} 應該被刪除。請注意，在這種情況下 @code{j1 == j2}。

@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


舉例來說：

@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{265a}
@deffn {方法} get_grouped_opcodes (n=3)

Return a @ref{125c,,generator} of groups with up to `n' lines of context.

Starting with the groups returned by @ref{2659,,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{2659,,get_opcodes()}.
@end deffn

@geindex ratio() (difflib.SequenceMatcher 的方法)
@anchor{library/difflib difflib SequenceMatcher ratio}@anchor{265b}
@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{2658,,get_matching_blocks()} or
@ref{2659,,get_opcodes()} hasn't already been called, in which case you may want
to try @ref{265c,,quick_ratio()} or @ref{265d,,real_quick_ratio()} first to get an
upper bound.

@cartouche
@quotation 備註 
Caution: The result of a @ref{265b,,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{265c}
@deffn {方法} quick_ratio ()

Return an upper bound on @ref{265b,,ratio()} relatively quickly.
@end deffn

@geindex real_quick_ratio() (difflib.SequenceMatcher 的方法)
@anchor{library/difflib difflib SequenceMatcher real_quick_ratio}@anchor{265d}
@deffn {方法} real_quick_ratio ()

Return an upper bound on @ref{265b,,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{265c,,quick_ratio()} and @ref{265d,,real_quick_ratio()}
are always at least as large as @ref{265b,,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 範例,Differ Objects,SequenceMatcher 物件,difflib --- 計算差異的輔助工具
@anchor{library/difflib id1}@anchor{265e}@anchor{library/difflib sequencematcher-examples}@anchor{265f}
@subsubsection SequenceMatcher 範例


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{265b,,ratio()} returns a float in [0, 1], measuring the similarity of the
sequences.  As a rule of thumb, a @ref{265b,,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{2658,,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{2658,,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{2659,,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{264f,,get_close_matches()} function in this module which shows how
simple code building on @ref{1214,,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{1214,,SequenceMatcher}.
@end itemize


@node Differ Objects,Differ Example,SequenceMatcher 範例,difflib --- 計算差異的輔助工具
@anchor{library/difflib differ-objects}@anchor{2660}@anchor{library/difflib id2}@anchor{2661}
@subsubsection Differ Objects


Note that @ref{2648,,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.

@ref{2648,,Differ} 類別有這個建構函式：


@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{1c14,,find_longest_match()} method's `isjunk'
parameter for an explanation.

@ref{2648,,Differ} objects are used (deltas generated) via a single method:

@geindex compare() (difflib.Differ 的方法)
@anchor{library/difflib difflib Differ compare}@anchor{2652}
@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{264c,,readlines()} method of file-like objects.  The delta
generated also consists of newline-terminated strings, ready to be
printed as-is via the @ref{264d,,writelines()} method of a
file-like object.
@end deffn
@end deffn

@node Differ Example,difflib 的命令列介面,Differ Objects,difflib --- 計算差異的輔助工具
@anchor{library/difflib differ-example}@anchor{2662}@anchor{library/difflib differ-examples}@anchor{2663}
@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{264c,,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{2648,,Differ} object we may pass functions to
filter out line and character "junk."  See the @ref{2648,,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 difflib 的命令列介面,ndiff 範例：,Differ Example,difflib --- 計算差異的輔助工具
@anchor{library/difflib a-command-line-interface-to-difflib}@anchor{2664}@anchor{library/difflib difflib-interface}@anchor{264e}
@subsubsection difflib 的命令列介面


This example shows how to use difflib to create a @code{diff}-like utility.

@example
""" Command line interface to difflib.py providing diffs in four formats:

* ndiff:    lists every line and highlights interline changes.
* context:  highlights clusters of changes in a before/after format.
* unified:  highlights clusters of changes in an inline format.
* html:     generates side by side comparison with change highlights.

"""

import sys, os, difflib, argparse
from datetime import datetime, timezone

def file_mtime(path):
    t = datetime.fromtimestamp(os.stat(path).st_mtime,
                               timezone.utc)
    return t.astimezone().isoformat()

def main():

    parser = argparse.ArgumentParser()
    parser.add_argument('-c', action='store_true', default=False,
                        help='Produce a context format diff (default)')
    parser.add_argument('-u', action='store_true', default=False,
                        help='Produce a unified format diff')
    parser.add_argument('-m', action='store_true', default=False,
                        help='Produce HTML side by side diff '
                             '(can use -c and -l in conjunction)')
    parser.add_argument('-n', action='store_true', default=False,
                        help='Produce a ndiff format diff')
    parser.add_argument('-l', '--lines', type=int, default=3,
                        help='Set number of context lines (default 3)')
    parser.add_argument('fromfile')
    parser.add_argument('tofile')
    options = parser.parse_args()

    n = options.lines
    fromfile = options.fromfile
    tofile = options.tofile

    fromdate = file_mtime(fromfile)
    todate = file_mtime(tofile)
    with open(fromfile) as ff:
        fromlines = ff.readlines()
    with open(tofile) as tf:
        tolines = tf.readlines()

    if options.u:
        diff = difflib.unified_diff(fromlines, tolines, fromfile, tofile, fromdate, todate, n=n)
    elif options.n:
        diff = difflib.ndiff(fromlines, tolines)
    elif options.m:
        diff = difflib.HtmlDiff().make_file(fromlines,tolines,fromfile,tofile,context=options.c,numlines=n)
    else:
        diff = difflib.context_diff(fromlines, tolines, fromfile, tofile, fromdate, todate, n=n)

    sys.stdout.writelines(diff)

if __name__ == '__main__':
    main()
@end example

@node ndiff 範例：,,difflib 的命令列介面,difflib --- 計算差異的輔助工具
@anchor{library/difflib ndiff-example}@anchor{2665}
@subsubsection ndiff 範例：


This example shows how to use @ref{264a,,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 資料庫,difflib --- 計算差異的輔助工具,文本處理 Text Processing 服務
@anchor{library/textwrap doc}@anchor{2666}@anchor{library/textwrap module-textwrap}@anchor{f2}@anchor{library/textwrap textwrap-text-wrapping-and-filling}@anchor{2667}@anchor{library/textwrap translation-repo}@anchor{2668}
@subsection @code{textwrap} --- 文字包裝與填充


@geindex module; textwrap

`原始碼：'Lib/textwrap.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/textwrap.py}


__________________________________________________________________


The @ref{f2,,textwrap} module provides some convenience functions,
as well as @ref{11c8,,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
@ref{11c8,,TextWrapper} for efficiency.

@geindex wrap() (於 textwrap 模組中)
@anchor{library/textwrap textwrap wrap}@anchor{16bb}
@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=' [...]')

Wraps the single paragraph in `text' (a string) so every line is at most
`width' characters long.  Returns a list of output lines, without final
newlines.

Optional keyword arguments correspond to the instance attributes of
@ref{11c8,,TextWrapper}, documented below.

See the @ref{2669,,TextWrapper.wrap()} method for additional details on how
@ref{16bb,,wrap()} behaves.
@end deffn

@geindex fill() (於 textwrap 模組中)
@anchor{library/textwrap textwrap fill}@anchor{16ba}
@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=' [...]')

Wraps the single paragraph in `text', and returns a single string containing the
wrapped paragraph.  @ref{16ba,,fill()} is shorthand for

@example
"\n".join(wrap(text, ...))
@end example

In particular, @ref{16ba,,fill()} accepts exactly the same keyword arguments as
@ref{16bb,,wrap()}.
@end deffn

@geindex shorten() (於 textwrap 模組中)
@anchor{library/textwrap textwrap shorten}@anchor{11cb}
@deffn {函式} textwrap.shorten (text, width, *, fix_sentence_endings=False, break_long_words=True, break_on_hyphens=True, placeholder=' [...]')

Collapse and truncate the given `text' to fit in the given `width'.

First the whitespace in `text' is collapsed (all whitespace is replaced by
single spaces).  If the result fits in the `width', it is returned.
Otherwise, enough words are dropped from the end so that the remaining words
plus the `placeholder' fit within `width':

@example
>>> textwrap.shorten("Hello  world!", width=12)
'Hello world!'
>>> textwrap.shorten("Hello  world!", width=11)
'Hello [...]'
>>> textwrap.shorten("Hello world", width=10, placeholder="...")
'Hello...'
@end example

Optional keyword arguments correspond to the instance attributes of
@ref{11c8,,TextWrapper}, documented below.  Note that the whitespace is
collapsed before the text is passed to the @ref{11c8,,TextWrapper} @ref{16ba,,fill()}
function, so changing the value of @ref{266a,,tabsize}, @ref{266b,,expand_tabs},
@ref{266c,,drop_whitespace}, and @ref{266d,,replace_whitespace} will have no effect.


在 3.4 版被加入.

@end deffn

@geindex dedent() (於 textwrap 模組中)
@anchor{library/textwrap textwrap dedent}@anchor{1a9}
@deffn {函式} textwrap.dedent (text)

Remove any common leading whitespace from every line in `text'.

This can be used to make triple-quoted strings line up with the left edge of the
display, while still presenting them in the source code in indented form.

Note that tabs and spaces are both treated as whitespace, but they are not
equal: the lines @code{"  hello"} and @code{"\thello"} are considered to have no
common leading whitespace.

Lines containing only whitespace are ignored in the input and normalized to a
single newline character in the output.

舉例來說：

@example
def test():
    # end first line with \ to avoid the empty line!
    s = '@w{'}'\
    hello
      world
    '@w{'}'
    print(repr(s))          # prints '    hello\n      world\n    '
    print(repr(dedent(s)))  # prints 'hello\n  world\n'
@end example
@end deffn

@geindex indent() (於 textwrap 模組中)
@anchor{library/textwrap textwrap indent}@anchor{577}
@deffn {函式} textwrap.indent (text, prefix, predicate=None)

Add `prefix' to the beginning of selected lines in `text'.

Lines are separated by calling @code{text.splitlines(True)}.

By default, `prefix' is added to all lines that do not consist
solely of whitespace (including any line endings).

舉例來說：

@example
>>> s = 'hello\n\n \nworld'
>>> indent(s, '  ')
'  hello\n\n \n  world'
@end example

The optional `predicate' argument can be used to control which lines
are indented. For example, it is easy to add `prefix' to even empty
and whitespace-only lines:

@example
>>> print(indent(s, '+ ', lambda line: True))
+ hello
+
+
+ world
@end example


在 3.3 版被加入.

@end deffn

@ref{16bb,,wrap()}, @ref{16ba,,fill()} and @ref{11cb,,shorten()} work by creating a
@ref{11c8,,TextWrapper} instance and calling a single method on it.  That
instance is not reused, so for applications that process many text
strings using @ref{16bb,,wrap()} and/or @ref{16ba,,fill()}, it may be more efficient to
create your own @ref{11c8,,TextWrapper} object.

Text is preferably wrapped on whitespaces and right after the hyphens in
hyphenated words; only then will long words be broken if necessary, unless
@ref{266e,,TextWrapper.break_long_words} is set to false.

@geindex TextWrapper (textwrap 中的類別)
@anchor{library/textwrap textwrap TextWrapper}@anchor{11c8}
@deffn {類別} textwrap.TextWrapper (**kwargs)

The @ref{11c8,,TextWrapper} constructor accepts a number of optional keyword
arguments.  Each keyword argument corresponds to an instance attribute, so
for example

@example
wrapper = TextWrapper(initial_indent="* ")
@end example

is the same as

@example
wrapper = TextWrapper()
wrapper.initial_indent = "* "
@end example

You can reuse the same @ref{11c8,,TextWrapper} object many times, and you can
change any of its options through direct assignment to instance attributes
between uses.

The @ref{11c8,,TextWrapper} instance attributes (and keyword arguments to the
constructor) are as follows:

@geindex width (textwrap.TextWrapper 的屬性)
@anchor{library/textwrap textwrap TextWrapper width}@anchor{266f}
@deffn {屬性} width

(default: @code{70}) The maximum length of wrapped lines.  As long as there
are no individual words in the input text longer than @ref{266f,,width},
@ref{11c8,,TextWrapper} guarantees that no output line will be longer than
@ref{266f,,width} characters.
@end deffn

@geindex expand_tabs (textwrap.TextWrapper 的屬性)
@anchor{library/textwrap textwrap TextWrapper expand_tabs}@anchor{266b}
@deffn {屬性} expand_tabs

(default: @code{True}) If true, then all tab characters in `text' will be
expanded to spaces using the @ref{24f1,,expandtabs()} method of `text'.
@end deffn

@geindex tabsize (textwrap.TextWrapper 的屬性)
@anchor{library/textwrap textwrap TextWrapper tabsize}@anchor{266a}
@deffn {屬性} tabsize

(default: @code{8}) If @ref{266b,,expand_tabs} is true, then all tab characters
in `text' will be expanded to zero or more spaces, depending on the
current column and the given tab size.


在 3.3 版被加入.

@end deffn

@geindex replace_whitespace (textwrap.TextWrapper 的屬性)
@anchor{library/textwrap textwrap TextWrapper replace_whitespace}@anchor{266d}
@deffn {屬性} replace_whitespace

(default: @code{True}) If true, after tab expansion but before wrapping,
the @ref{16bb,,wrap()} method will replace each whitespace character
with a single space.  The whitespace characters replaced are
as follows: tab, newline, vertical tab, formfeed, and carriage
return (@code{'\t\n\v\f\r'}).

@cartouche
@quotation 備註 
If @ref{266b,,expand_tabs} is false and @ref{266d,,replace_whitespace} is true,
each tab character will be replaced by a single space, which is `not'
the same as tab expansion.
@end quotation
@end cartouche

@cartouche
@quotation 備註 
If @ref{266d,,replace_whitespace} is false, newlines may appear in the
middle of a line and cause strange output. For this reason, text should
be split into paragraphs (using @ref{1457,,str.splitlines()} or similar)
which are wrapped separately.
@end quotation
@end cartouche
@end deffn

@geindex drop_whitespace (textwrap.TextWrapper 的屬性)
@anchor{library/textwrap textwrap TextWrapper drop_whitespace}@anchor{266c}
@deffn {屬性} drop_whitespace

(default: @code{True}) If true, whitespace at the beginning and ending of
every line (after wrapping but before indenting) is dropped.
Whitespace at the beginning of the paragraph, however, is not dropped
if non-whitespace follows it.  If whitespace being dropped takes up an
entire line, the whole line is dropped.
@end deffn

@geindex initial_indent (textwrap.TextWrapper 的屬性)
@anchor{library/textwrap textwrap TextWrapper initial_indent}@anchor{2670}
@deffn {屬性} initial_indent

(default: @code{'@w{'}}) String that will be prepended to the first line of
wrapped output.  Counts towards the length of the first line.  The empty
string is not indented.
@end deffn

@geindex subsequent_indent (textwrap.TextWrapper 的屬性)
@anchor{library/textwrap textwrap TextWrapper subsequent_indent}@anchor{2671}
@deffn {屬性} subsequent_indent

(default: @code{'@w{'}}) String that will be prepended to all lines of wrapped
output except the first.  Counts towards the length of each line except
the first.
@end deffn

@geindex fix_sentence_endings (textwrap.TextWrapper 的屬性)
@anchor{library/textwrap textwrap TextWrapper fix_sentence_endings}@anchor{2672}
@deffn {屬性} fix_sentence_endings

(default: @code{False}) If true, @ref{11c8,,TextWrapper} attempts to detect
sentence endings and ensure that sentences are always separated by exactly
two spaces.  This is generally desired for text in a monospaced font.
However, the sentence detection algorithm is imperfect: it assumes that a
sentence ending consists of a lowercase letter followed by one of @code{'.'},
@code{'!'}, or @code{'?'}, possibly followed by one of @code{'"'} or @code{"'"},
followed by a space.  One problem with this algorithm is that it is
unable to detect the difference between "Dr." in

@example
[...] Dr. Frankenstein's monster [...]
@end example

and "Spot." in

@example
[...] See Spot. See Spot run [...]
@end example

@ref{2672,,fix_sentence_endings} is false by default.

Since the sentence detection algorithm relies on @code{string.lowercase} for
the definition of "lowercase letter", and a convention of using two spaces
after a period to separate sentences on the same line, it is specific to
English-language texts.
@end deffn

@geindex break_long_words (textwrap.TextWrapper 的屬性)
@anchor{library/textwrap textwrap TextWrapper break_long_words}@anchor{266e}
@deffn {屬性} break_long_words

(default: @code{True}) If true, then words longer than @ref{266f,,width} will be
broken in order to ensure that no lines are longer than @ref{266f,,width}.  If
it is false, long words will not be broken, and some lines may be longer
than @ref{266f,,width}.  (Long words will be put on a line by themselves, in
order to minimize the amount by which @ref{266f,,width} is exceeded.)
@end deffn

@geindex break_on_hyphens (textwrap.TextWrapper 的屬性)
@anchor{library/textwrap textwrap TextWrapper break_on_hyphens}@anchor{2673}
@deffn {屬性} break_on_hyphens

(default: @code{True}) If true, wrapping will occur preferably on whitespaces
and right after hyphens in compound words, as it is customary in English.
If false, only whitespaces will be considered as potentially good places
for line breaks, but you need to set @ref{266e,,break_long_words} to false if
you want truly insecable words.  Default behaviour in previous versions
was to always allow breaking hyphenated words.
@end deffn

@geindex max_lines (textwrap.TextWrapper 的屬性)
@anchor{library/textwrap textwrap TextWrapper max_lines}@anchor{11c9}
@deffn {屬性} max_lines

(default: @code{None}) If not @code{None}, then the output will contain at most
`max_lines' lines, with `placeholder' appearing at the end of the output.


在 3.4 版被加入.

@end deffn

@geindex ...;placeholder（佔位符號）

@geindex placeholder (textwrap.TextWrapper 的屬性)
@anchor{library/textwrap textwrap TextWrapper placeholder}@anchor{11ca}
@deffn {屬性} placeholder

(default: @code{' [...]'}) String that will appear at the end of the output
text if it has been truncated.


在 3.4 版被加入.

@end deffn

@ref{11c8,,TextWrapper} also provides some public methods, analogous to the
module-level convenience functions:

@geindex wrap() (textwrap.TextWrapper 的方法)
@anchor{library/textwrap textwrap TextWrapper wrap}@anchor{2669}
@deffn {方法} wrap (text)

Wraps the single paragraph in `text' (a string) so every line is at most
@ref{266f,,width} characters long.  All wrapping options are taken from
instance attributes of the @ref{11c8,,TextWrapper} instance.  Returns a list
of output lines, without final newlines.  If the wrapped output has no
content, the returned list is empty.
@end deffn

@geindex fill() (textwrap.TextWrapper 的方法)
@anchor{library/textwrap textwrap TextWrapper fill}@anchor{2674}
@deffn {方法} fill (text)

Wraps the single paragraph in `text', and returns a single string
containing the wrapped paragraph.
@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 資料庫,stringprep --- 網際網路字串的準備,textwrap --- 文字包裝與填充,文本處理 Text Processing 服務
@anchor{library/unicodedata doc}@anchor{2675}@anchor{library/unicodedata module-unicodedata}@anchor{10b}@anchor{library/unicodedata translation-repo}@anchor{2676}@anchor{library/unicodedata unicodedata-unicode-database}@anchor{2677}
@subsection @code{unicodedata} --- Unicode 資料庫


@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 16.0.0@footnote{https://www.unicode.org/Public/16.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{14a5,,Unicode HOWTO} for more information about Unicode and how to use
this module.


@geindex lookup() (於 unicodedata 模組中)
@anchor{library/unicodedata unicodedata lookup}@anchor{1273}
@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{5df,,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 版的變更: 已新增對名稱別名 @footnote{
@indicateurl{https://www.unicode.org/Public/16.0.0/ucd/NameAliases.txt}
} 和命名序列 @footnote{
@indicateurl{https://www.unicode.org/Public/16.0.0/ucd/NamedSequences.txt}
} 的支援。

@end deffn

@geindex name() (於 unicodedata 模組中)
@anchor{library/unicodedata unicodedata name}@anchor{2678}
@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{2eb,,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{2679}
@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{2eb,,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{267a}
@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{2eb,,ValueError} is raised:

@example
>>> unicodedata.digit('\N@{SUPERSCRIPT NINE@}')
9
@end example
@end deffn

@geindex numeric() (於 unicodedata 模組中)
@anchor{library/unicodedata unicodedata numeric}@anchor{1463}
@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{2eb,,ValueError} is raised:

@example
>>> unicodedata.numeric('½')
0.5
@end example
@end deffn

@geindex category() (於 unicodedata 模組中)
@anchor{library/unicodedata unicodedata category}@anchor{267b}
@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/tr44-34.html#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{267c}
@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/tr44-34.html#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{267d}
@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/tr44-34.html#Canonical_Combining_Class_Values}
for more information.
@end deffn

@geindex east_asian_width() (於 unicodedata 模組中)
@anchor{library/unicodedata unicodedata east_asian_width}@anchor{267e}
@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/tr11-43.html}.
@end deffn

@geindex mirrored() (於 unicodedata 模組中)
@anchor{library/unicodedata unicodedata mirrored}@anchor{267f}
@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 decomposition() (於 unicodedata 模組中)
@anchor{library/unicodedata unicodedata decomposition}@anchor{2680}
@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 normalize() (於 unicodedata 模組中)
@anchor{library/unicodedata unicodedata normalize}@anchor{8dc}
@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{c33}
@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'.


在 3.8 版被加入.

@end deffn

In addition, the module exposes the following constant:

@geindex unidata_version (於 unicodedata 模組中)
@anchor{library/unicodedata unicodedata unidata_version}@anchor{2681}
@deffn {資料} unicodedata.unidata_version

在此模組中使用的 Unicode 資料庫版本。
@end deffn

@geindex ucd_3_2_0 (於 unicodedata 模組中)
@anchor{library/unicodedata unicodedata ucd_3_2_0}@anchor{162b}
@deffn {資料} unicodedata.ucd_3_2_0

This is an object that has the same methods as 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 --- 網際網路字串的準備,readline --- GNU readline 介面,unicodedata --- Unicode 資料庫,文本處理 Text Processing 服務
@anchor{library/stringprep doc}@anchor{2682}@anchor{library/stringprep module-stringprep}@anchor{da}@anchor{library/stringprep stringprep-internet-string-preparation}@anchor{2683}@anchor{library/stringprep translation-repo}@anchor{2684}
@subsection @code{stringprep} --- 網際網路字串的準備


@geindex module; stringprep

`原始碼：'Lib/stringprep.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/stringprep.py}


__________________________________________________________________


在網際網路上識別事物（例如主機名稱）時，通常需要比較這些識別器的「相等性 (equality)」。比較的具體執行方式可能取決於應用程式領域，例如是否應該不區分大小寫。也可能有必要限制可能的識別器，只允許由「可列印 (printable)」字元組成的識別器。

@geindex RFC; RFC 3454
RFC 3454@footnote{https://datatracker.ietf.org/doc/html/rfc3454.html} 定義了在網際網路通訊協定中「準備」Unicode 字串的程序。在傳送字串到網路之前，先使用準備程序處理字串，之後字串就具有特定的規範化 (normalized) 形式。RFC 定義了一系列的表，這些表可以組合成設定檔 (profile)。每個設定檔必須定義它使用哪些表以及 @code{stringprep} 程序的哪些其他可選部分是設定檔的一部分。@code{stringprep} 配置文件的一個例子是 @code{nameprep}，它被用於國際化網域名稱。

@ref{da,,stringprep} 模組只開放 
@geindex RFC; RFC 3454
RFC 3454@footnote{https://datatracker.ietf.org/doc/html/rfc3454.html} 中的表。由於這些表如果以字典或串列的方式來表示的話會非常大，因此模組內部使用 Unicode 字元資料庫。模組原始碼本身是使用 @code{mkstringprep.py} 工具來產生的。

因此，這些表是以函式而非資料結構的形式呈現。RFC 中有兩種表：集合 (sets) 和對映 (mappings)。對於集合，@ref{da,,stringprep} 提供了「特徵函式 (characteristic function)」，也就是如果參數是集合的一部分就回傳 @code{True} 的函式。對於對映，它提供了對映函式：給定鍵，它會回傳相關的值。以下是模組中所有可用函式的清單。

@geindex in_table_a1() (於 stringprep 模組中)
@anchor{library/stringprep stringprep in_table_a1}@anchor{2685}
@deffn {函式} stringprep.in_table_a1 (code)

判斷 `code' 是否在 tableA.1（Unicode 3.2 中未指定的編碼位置 (code point)）中。
@end deffn

@geindex in_table_b1() (於 stringprep 模組中)
@anchor{library/stringprep stringprep in_table_b1}@anchor{2686}
@deffn {函式} stringprep.in_table_b1 (code)

判斷 `code' 是否在 tableB.1（通常沒有對映到任何東西）中。
@end deffn

@geindex map_table_b2() (於 stringprep 模組中)
@anchor{library/stringprep stringprep map_table_b2}@anchor{2687}
@deffn {函式} stringprep.map_table_b2 (code)

根據 tableB.2（使用 NFKC 形式的大小寫折疊 (case-folding) 對映）回傳 `code' 的對映值。
@end deffn

@geindex map_table_b3() (於 stringprep 模組中)
@anchor{library/stringprep stringprep map_table_b3}@anchor{2688}
@deffn {函式} stringprep.map_table_b3 (code)

根據 tableB.3（使用沒有規範化的大小寫折疊對映）回傳 `code' 的對映值。
@end deffn

@geindex in_table_c11() (於 stringprep 模組中)
@anchor{library/stringprep stringprep in_table_c11}@anchor{2689}
@deffn {函式} stringprep.in_table_c11 (code)

判斷 `code' 是否在 tableC.1.1（ASCII 空格字元）中。
@end deffn

@geindex in_table_c12() (於 stringprep 模組中)
@anchor{library/stringprep stringprep in_table_c12}@anchor{268a}
@deffn {函式} stringprep.in_table_c12 (code)

判斷 `code' 是否在 tableC.1.2（非 ASCII 空格字元）中。
@end deffn

@geindex in_table_c11_c12() (於 stringprep 模組中)
@anchor{library/stringprep stringprep in_table_c11_c12}@anchor{268b}
@deffn {函式} stringprep.in_table_c11_c12 (code)

判斷 `code' 是否在 tableC.1（空格字元，為 C.1.1 和 C.1.2 的聯集）中。
@end deffn

@geindex in_table_c21() (於 stringprep 模組中)
@anchor{library/stringprep stringprep in_table_c21}@anchor{268c}
@deffn {函式} stringprep.in_table_c21 (code)

判斷 `code' 是否在 tableC.2.1（ASCII 控制字元）中。
@end deffn

@geindex in_table_c22() (於 stringprep 模組中)
@anchor{library/stringprep stringprep in_table_c22}@anchor{268d}
@deffn {函式} stringprep.in_table_c22 (code)

判斷 `code' 是否在 tableC.2.2（非 ASCII 控制字元）中。
@end deffn

@geindex in_table_c21_c22() (於 stringprep 模組中)
@anchor{library/stringprep stringprep in_table_c21_c22}@anchor{268e}
@deffn {函式} stringprep.in_table_c21_c22 (code)

判斷 `code' 是否在 tableC.2（控制字元，為 C.2.1 和 C.2.2 的聯集）中。
@end deffn

@geindex in_table_c3() (於 stringprep 模組中)
@anchor{library/stringprep stringprep in_table_c3}@anchor{268f}
@deffn {函式} stringprep.in_table_c3 (code)

判斷 `code' 是否在 tableC.3（私有使用）中。
@end deffn

@geindex in_table_c4() (於 stringprep 模組中)
@anchor{library/stringprep stringprep in_table_c4}@anchor{2690}
@deffn {函式} stringprep.in_table_c4 (code)

判斷 `code' 是否在 tableC.4（非字元編碼位置）中。
@end deffn

@geindex in_table_c5() (於 stringprep 模組中)
@anchor{library/stringprep stringprep in_table_c5}@anchor{2691}
@deffn {函式} stringprep.in_table_c5 (code)

判斷 `code' 是否在 tableC.5（代理碼）中。
@end deffn

@geindex in_table_c6() (於 stringprep 模組中)
@anchor{library/stringprep stringprep in_table_c6}@anchor{2692}
@deffn {函式} stringprep.in_table_c6 (code)

判斷 `code' 是否在 tableC.6（不適用於純文字）中。
@end deffn

@geindex in_table_c7() (於 stringprep 模組中)
@anchor{library/stringprep stringprep in_table_c7}@anchor{2693}
@deffn {函式} stringprep.in_table_c7 (code)

判斷 `code' 是否在 tableC.7（不適用於規範表示法 (canonical representation)）中。
@end deffn

@geindex in_table_c8() (於 stringprep 模組中)
@anchor{library/stringprep stringprep in_table_c8}@anchor{2694}
@deffn {函式} stringprep.in_table_c8 (code)

判斷 `code' 是否在 tableC.8（變更顯示屬性或已棄用）中。
@end deffn

@geindex in_table_c9() (於 stringprep 模組中)
@anchor{library/stringprep stringprep in_table_c9}@anchor{2695}
@deffn {函式} stringprep.in_table_c9 (code)

判斷 `code' 是否在 tableC.9（標記字元 (tagging characters)）中。
@end deffn

@geindex in_table_d1() (於 stringprep 模組中)
@anchor{library/stringprep stringprep in_table_d1}@anchor{2696}
@deffn {函式} stringprep.in_table_d1 (code)

判斷 `code' 是否在 tableD.1（具有雙向屬性 "R" 或 "AL" 的字元）中。
@end deffn

@geindex in_table_d2() (於 stringprep 模組中)
@anchor{library/stringprep stringprep in_table_d2}@anchor{2697}
@deffn {函式} stringprep.in_table_d2 (code)

判斷 `code' 是否在 tableD.2（具有雙向屬性 "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 介面,rlcompleter --- GNU readline 的補全函式,stringprep --- 網際網路字串的準備,文本處理 Text Processing 服務
@anchor{library/readline doc}@anchor{2698}@anchor{library/readline module-readline}@anchor{bf}@anchor{library/readline readline-gnu-readline-interface}@anchor{2699}@anchor{library/readline translation-repo}@anchor{269a}
@subsection @code{readline} --- GNU readline 介面


@geindex module; readline


__________________________________________________________________


The @ref{bf,,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{c2,,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{14d9,,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{2006,,可用性}: not Android, not iOS, not WASI.

此模組在@ref{2120,,行動平台}或@ref{1a99,,WebAssembly 平台}上不支援。

@cartouche
@quotation 備註 
The underlying Readline library API may be implemented by
the @code{editline} (@code{libedit}) library instead of GNU readline.
On macOS the @ref{bf,,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{1977,,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{1977}
@deffn {資料} readline.backend

The name of the underlying Readline library being used, either
@code{"readline"} or @code{"editline"}.


在 3.13 版被加入.

@end deffn

@menu
* Init file:: 
* Line buffer:: 
* History file:: 
* History list:: 
* Startup hooks:: 
* Completion:: 
* 範例:: 

@end menu

@node Init file,Line buffer,,readline --- GNU readline 介面
@anchor{library/readline init-file}@anchor{269b}
@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{269c}
@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{1766}
@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{1b70,,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 介面
@anchor{library/readline line-buffer}@anchor{269d}
@subsubsection Line buffer


The following functions operate on the line buffer:

@geindex get_line_buffer() (於 readline 模組中)
@anchor{library/readline readline get_line_buffer}@anchor{269e}
@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{269f}
@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{16b9}
@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 介面
@anchor{library/readline history-file}@anchor{26a0}
@subsubsection History file


The following functions operate on a history file:

@geindex read_history_file() (於 readline 模組中)
@anchor{library/readline readline read_history_file}@anchor{1767}
@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{1b70,,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{1768}
@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{1b70,,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{104c}
@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{1b70,,auditing event} @code{open}
with the file name if given and @code{"~/.history"} otherwise.


在 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{26a1}
@deffn {函式} readline.get_history_length ()
@anchor{library/readline readline set_history_length}@anchor{188c}
@deffnx {函式} readline.set_history_length (length)

Set or return the desired number of lines to save in the history file.
The @ref{1768,,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 介面
@anchor{library/readline history-list}@anchor{26a2}
@subsubsection History list


The following functions operate on a global history list:

@geindex clear_history() (於 readline 模組中)
@anchor{library/readline readline clear_history}@anchor{26a3}
@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{16b8}
@deffn {函式} readline.get_current_history_length ()

Return the number of items currently in the history.  (This is different from
@ref{26a1,,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{16b7}
@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{26a4}
@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{26a5}
@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{26a6}
@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{ec0}
@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.


在 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 介面
@anchor{library/readline startup-hooks}@anchor{26a7}
@subsubsection Startup hooks


@geindex set_startup_hook() (於 readline 模組中)
@anchor{library/readline readline set_startup_hook}@anchor{26a8}
@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{26a9}
@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

@node Completion,範例,Startup hooks,readline --- GNU readline 介面
@anchor{library/readline completion}@anchor{26aa}@anchor{library/readline readline-completion}@anchor{26ab}
@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{c2,,rlcompleter} to complete Python identifiers for
the interactive interpreter.  If the @ref{bf,,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{26ac}
@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{26ad}
@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{26ae}
@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{1b9c}
@deffn {函式} readline.get_begidx ()
@anchor{library/readline readline get_endidx}@anchor{1b9d}
@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{197b}
@deffn {函式} readline.set_completer_delims (string)
@anchor{library/readline readline get_completer_delims}@anchor{26af}
@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{26b0}
@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 範例,,Completion,readline --- GNU readline 介面
@anchor{library/readline example}@anchor{26b1}@anchor{library/readline readline-example}@anchor{26b2}
@subsubsection 範例


The following example demonstrates how to use the @ref{bf,,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{1b8,,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{441,,interactive mode} (see @ref{11c4,,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{26b3,,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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node rlcompleter --- GNU readline 的補全函式,,readline --- GNU readline 介面,文本處理 Text Processing 服務
@anchor{library/rlcompleter doc}@anchor{26b4}@anchor{library/rlcompleter module-rlcompleter}@anchor{c2}@anchor{library/rlcompleter rlcompleter-completion-function-for-gnu-readline}@anchor{26b5}@anchor{library/rlcompleter translation-repo}@anchor{26b6}
@subsection @code{rlcompleter} --- GNU readline 的補全函式


@geindex module; rlcompleter

`原始碼：'Lib/rlcompleter.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/rlcompleter.py}


__________________________________________________________________


The @code{rlcompleter} module defines a completion function suitable to be
passed to @ref{26ac,,set_completer()} in the @ref{bf,,readline} module.

When this module is imported on a Unix platform with the @ref{bf,,readline} module
available, an instance of the @ref{1bf9,,Completer} class is automatically created
and its @ref{26b7,,complete()} method is set as the
@ref{26ab,,readline completer}. The method provides
completion of valid Python @ref{2164,,identifiers and keywords}.

範例：

@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{441,,interactive mode}.  Unless Python is run with the
@ref{13a9,,-S} option, the module is automatically imported and configured
(see @ref{11c4,,Readline configuration}).

On platforms without @ref{bf,,readline}, the @ref{1bf9,,Completer} class defined by
this module can still be used for custom purposes.

@geindex Completer (rlcompleter 中的類別)
@anchor{library/rlcompleter completer-objects}@anchor{26b8}@anchor{library/rlcompleter rlcompleter Completer}@anchor{1bf9}
@deffn {類別} rlcompleter.Completer

Completer objects have the following method:

@geindex complete() (rlcompleter.Completer 的方法)
@anchor{library/rlcompleter rlcompleter Completer complete}@anchor{26b7}
@deffn {方法} complete (text, state)

Return the next possible completion for `text'.

When called by the @ref{bf,,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{88,,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{6f3,,__getattr__()}) up to the last part, and find matches for the
rest via the @ref{83d,,dir()} function.  Any exception raised during the
evaluation of the expression is caught, silenced and @ref{87e,,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 二進位資料服務,資料型別,文本處理 Text Processing 服務,Python 標準函式庫 Standard Library
@anchor{library/binary doc}@anchor{26b9}@anchor{library/binary binary-data-services}@anchor{26ba}@anchor{library/binary binaryservices}@anchor{25c7}@anchor{library/binary translation-repo}@anchor{26bb}
@section 二進位資料服務


本章所描述的模組提供了一些基本的二進位資料操作服務。而針對二進位資料的其他操作──尤其是關於檔案格式和網路協定的部分──則會在相關章節中詳細描述。

一些在 @ref{24fc,,文本處理 (Text Processing) 服務} 中提及的函式庫也可處理 ASCII 相容的二進位格式（例如，@ref{be,,re}）及所有的二進位資料（例如，@ref{3b,,difflib}）。

此外，請參閱 Python 內建的二進位資料類型的文件，詳情請參考 @ref{246d,,Binary Sequence Types --- bytes@comma{} bytearray@comma{} memoryview}。

@menu
* struct: struct --- 將位元組直譯為打包起來的二進位資料. 將位元組直譯為打包起來的二進位資料
* codecs: codecs --- 編解碼器註冊表和基底類別. 編解碼器註冊表和基底類別

@end menu

@node struct --- 將位元組直譯為打包起來的二進位資料,codecs --- 編解碼器註冊表和基底類別,,二進位資料服務
@anchor{library/struct doc}@anchor{26bc}@anchor{library/struct struct-interpret-bytes-as-packed-binary-data}@anchor{26bd}
@subsection @code{struct} --- 將位元組直譯為打包起來的二進位資料


@c from struct import *

@geindex module; struct
@anchor{library/struct module-struct}@anchor{db}
`原始碼：'Lib/struct.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/struct.py}

@geindex C;structures（結構）
@geindex packing（打包）;binary（二進位）;data（資料）


__________________________________________________________________


此模組可在 Python 數值與以 Python @ref{192,,bytes} 物件表示的 C 結構之間進行轉換。簡潔的@ref{26be,,格式字串}描述了與 Python 數值之間預期的轉換。此模組的函式和物件可用於兩種截然不同的應用程式：與外部來源（檔案或網路連線）的資料交換，或是 Python 應用程式與 C 層之間的資料傳輸。

@cartouche
@quotation 備註 
當未給定前綴字元時會預設為原生模式。它會根據建構 Python 直譯器的平台和編譯器來打包或解包資料。打包給定 C 結構的結果包含填充位元組，以維持相關 C 型別的正確對齊；同樣地，解包時也會考量對齊。相反地，當在外部來源之間傳輸資料時，程式設計師需負責定義位元組順序和元素之間的填充。詳情請參見 @ref{26bf,,位元組順序、大小和對齊}。
@end quotation
@end cartouche

一些 @ref{db,,struct} 函式（和 @ref{1979,,Struct} 的方法）接受一個 `buffer' 引數。這是指實作@ref{260,,緩衝協定 (Buffer Protocol)} 並提供可讀或可讀寫緩衝區的物件。最常用於此目的的型別是 @ref{192,,bytes} 和 @ref{343,,bytearray}，但許多其他可以視為位元組陣列的型別都實作了緩衝區協定，因此它們可以從 @ref{192,,bytes} 物件讀取或填入資料而無需額外的複製。

@menu
* 函式與例外:: 
* 格式字串:: 
* 應用:: 
* 類別:: 

@end menu

@node 函式與例外,格式字串,,struct --- 將位元組直譯為打包起來的二進位資料
@anchor{library/struct functions-and-exceptions}@anchor{26c0}
@subsubsection 函式與例外


此模組定義了以下例外和函式：

@geindex error
@anchor{library/struct struct error}@anchor{1524}
@deffn {例外} struct.error

在各種情況下都可能觸發的例外；引數是一個描述錯誤內容的字串。
@end deffn

@geindex pack() (於 struct 模組中)
@anchor{library/struct struct pack}@anchor{1477}
@deffn {函式} struct.pack (format, v1, v2, ...)

回傳一個包含依照格式字串 `format' 打包的數值 `v1'、`v2'、... 的位元組物件。引數必須完全符合格式所需的數值。
@end deffn

@geindex pack_into() (於 struct 模組中)
@anchor{library/struct struct pack_into}@anchor{26c1}
@deffn {函式} struct.pack_into (format, buffer, offset, v1, v2, ...)

依照格式字串 `format' 打包數值 `v1'、`v2'、...，並將打包後的位元組寫入可寫緩衝區 `buffer' 中從位置 `offset' 開始的地方。請注意 `offset' 是必要的引數。
@end deffn

@geindex unpack() (於 struct 模組中)
@anchor{library/struct struct unpack}@anchor{17da}
@deffn {函式} struct.unpack (format, buffer)

根據格式字串 `format' 從緩衝區 `buffer'（推測是由 @code{pack(format, ...)} 打包的）解包。結果是一個元組，即使它只包含一個項目。緩衝區的位元組大小必須符合格式所需的大小，如 @ref{1c72,,calcsize()} 所示。
@end deffn

@geindex unpack_from() (於 struct 模組中)
@anchor{library/struct struct unpack_from}@anchor{26c2}
@deffn {函式} struct.unpack_from (format, /, buffer, offset=0)

根據格式字串 `format' 從 `buffer' 的 `offset' 位置開始解包。即使它只包含一個項目，結果也都是一個元組。緩衝區從位置 `offset' 開始的位元組大小，必須至少達到格式所需的大小，如 @ref{1c72,,calcsize()} 所示。
@end deffn

@geindex iter_unpack() (於 struct 模組中)
@anchor{library/struct struct iter_unpack}@anchor{11ba}
@deffn {函式} struct.iter_unpack (format, buffer)

根據格式字串 `format' 疊代地從緩衝區 `buffer' 解包。此函式回傳一個疊代器，它會從緩衝區讀取等大小的區塊，直到消耗完所有內容。緩衝區的位元組大小必須是格式所需大小的倍數，如 @ref{1c72,,calcsize()} 所示。

每次疊代都會產生 (yield) 出一個由格式字串指定的元組。


在 3.4 版被加入.

@end deffn

@geindex calcsize() (於 struct 模組中)
@anchor{library/struct struct calcsize}@anchor{1c72}
@deffn {函式} struct.calcsize (format)

回傳對應於格式字串 `format' 的結構大小（因此也是 @code{pack(format, ...)} 所產生的位元組物件的大小）。
@end deffn

@node 格式字串,應用,函式與例外,struct --- 將位元組直譯為打包起來的二進位資料
@anchor{library/struct format-strings}@anchor{26c3}@anchor{library/struct struct-format-strings}@anchor{26be}
@subsubsection 格式字串


格式字串描述了打包和解包資料時的資料配置 (layout)。它們由@ref{26c4,,格式字元}組成，這些字元指定了要打包或解包的資料型別。此外，特殊字元控制@ref{26bf,,位元組順序、大小和對齊}。每個格式字串由一個可選的前綴字元組成，描述資料的整體屬性，以及一個或多個描述實際資料值和填充的格式字元。

@menu
* 位元組順序、大小和對齊:: 
* 格式字元:: 
* 範例: 範例<2>. 

@end menu

@node 位元組順序、大小和對齊,格式字元,,格式字串
@anchor{library/struct byte-order-size-and-alignment}@anchor{26c5}@anchor{library/struct struct-alignment}@anchor{26bf}
@subsubsection 位元組順序、大小和對齊


預設情況下，C 型別以機器的原生格式和位元組順序表示，並在必要時透過跳過填充位元組來正確對齊（根據 C 編譯器所使用的規則）。選擇此行為使得打包結構的位元組完全對應於相對應 C 結構的記憶體配置。是否使用原生位元組順序和填充或標準格式取決於應用程式。

@geindex @@ （在）;於 struct format strings（結構格式字串）
@geindex = （等號）;於 struct format strings（結構格式字串）
@geindex < （小於）;於 struct format strings（結構格式字串）
@geindex > （大於）;於 struct format strings（結構格式字串）
@geindex ! （驚嘆號）;於 struct format strings（結構格式字串）

或者，格式字串的第一個字元可以用來指示打包資料的位元組順序、大小和對齊，如下表所示：


@multitable {xxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxx} {xxxxxxxxxxxxx} 
@headitem

字元

@tab

位元組順序

@tab

大小

@tab

對齊

@item

@code{@@}

@tab

原生

@tab

原生

@tab

原生

@item

@code{=}

@tab

原生

@tab

標準

@tab

無

@item

@code{<}

@tab

小端序

@tab

標準

@tab

無

@item

@code{>}

@tab

大端序

@tab

標準

@tab

無

@item

@code{!}

@tab

網路（= 大端序）

@tab

標準

@tab

無

@end multitable


如果第一個字元不是這些字元之一，則假設為 @code{'@@'}。

@cartouche
@quotation 備註 
數字 1023（十六進位為 @code{0x3ff}）具有以下位元組表示法：


@itemize *

@item 
大端序（@code{>}）為 @code{03 ff}

@item 
小端序（@code{<}）為 @code{ff 03}
@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

原生位元組順序是大端序或小端序，會取決於主機系統。例如，Intel x86、AMD64 (x86-64)和 Apple M1 是小端序；IBM z 和許多舊架構是大端序。可使用 @ref{24a7,,sys.byteorder} 來檢查你系統的位元組順序。

原生大小和對齊是使用 C 編譯器的 @code{sizeof} 運算式來決定的。這總是與原生位元組順序結合使用。

標準大小僅取決於格式字元；請參見@ref{26c4,,格式字元}區塊中的表格。

請注意 @code{'@@'} 和 @code{'='} 之間的差異：兩者都使用原生位元組順序，但後者的大小和對齊是標準化的。

@code{'!'} 形式表示網路位元組順序，根據 IETF RFC 1700@footnote{https://datatracker.ietf.org/doc/html/rfc1700} 的定義，它總是大端序。

沒有方法來指示非原生位元組順序（強制位元組交換）；請使用適當的 @code{'<'} 或 @code{'>'} 選擇。

註解：


@enumerate 

@item 
填充只會在連續的結構成員之間自動加入。編碼結構的開頭或結尾不會加入填充。

@item 
使用非原生大小和對齊時，例如使用 '<'、'>'、'=' 和 '!' 時，不會加入填充。

@item 
要將結構的結尾對齊到特定型別的對齊需求，請以該型別的碼結束格式，重複次數為零。請參見@ref{26c6,,範例}。
@end enumerate

@node 格式字元,範例<2>,位元組順序、大小和對齊,格式字串
@anchor{library/struct format-characters}@anchor{26c4}@anchor{library/struct id1}@anchor{26c7}
@subsubsection 格式字元


格式字元具有以下意義；在給定型別的情況下，C 和 Python 數值之間的轉換應該是顯而易見的。「標準大小」欄位指的是使用標準大小時（即當格式字串以 @code{'<'}、@code{'>'}、@code{'!'} 或 @code{'='} 其中之一開始時）打包數值的位元組大小。使用原生大小時，打包數值的大小取決於平台。


@multitable {xxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxx} 
@headitem

格式

@tab

C Type

@tab

Python 型別

@tab

標準大小

@tab

註解

@item

@code{x}

@tab

填充位元組

@tab

無值

@tab

@tab

(7)

@item

@code{c}

@tab

char

@tab

長度為 1 的位元組

@tab

1

@tab

@item

@code{b}

@tab

signed char

@tab

整數

@tab

1

@tab

(1), (2)

@item

@code{B}

@tab

unsigned char

@tab

整數

@tab

1

@tab

(2)

@item

@code{?}

@tab

_Bool

@tab

bool

@tab

1

@tab

(1)

@item

@code{h}

@tab

short

@tab

整數

@tab

2

@tab

(2)

@item

@code{H}

@tab

unsigned short

@tab

整數

@tab

2

@tab

(2)

@item

@code{i}

@tab

int

@tab

整數

@tab

4

@tab

(2)

@item

@code{I}

@tab

unsigned int

@tab

整數

@tab

4

@tab

(2)

@item

@code{l}

@tab

long

@tab

整數

@tab

4

@tab

(2)

@item

@code{L}

@tab

unsigned long

@tab

整數

@tab

4

@tab

(2)

@item

@code{q}

@tab

long long

@tab

整數

@tab

8

@tab

(2)

@item

@code{Q}

@tab

unsigned long long

@tab

整數

@tab

8

@tab

(2)

@item

@code{n}

@tab

@code{ssize_t}

@tab

整數

@tab

@tab

(3)

@item

@code{N}

@tab

@code{size_t}

@tab

整數

@tab

@tab

(3)

@item

@code{e}

@tab

(6)

@tab

float

@tab

2

@tab

(4)

@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

complex

@tab

8

@tab

(10)

@item

@code{D}

@tab

double complex

@tab

complex

@tab

16

@tab

(10)

@item

@code{s}

@tab

char[]

@tab

位元組

@tab

@tab

(9)

@item

@code{p}

@tab

char[]

@tab

位元組

@tab

@tab

(8)

@item

@code{P}

@tab

void*

@tab

整數

@tab

@tab

(5)

@end multitable



在 3.3 版的變更: 新增 @code{'n'} 與 @code{'N'} 格式的支援。



在 3.6 版的變更: 新增 @code{'e'} 格式的支援。



在 3.14 版的變更: 新增 @code{'F'} 與 @code{'D'} 格式的支援。


註解：


@enumerate 

@item 
@geindex ? （問號）;於 struct format strings（結構格式字串）

@code{'?'} 轉換碼對應於自 C99 以來 C 標準定義的 _Bool 型別。在標準模式下，它由一個位元組表示。

@item 
當嘗試使用任何整數轉換碼打包非整數時，如果非整數具有 @ref{19e,,__index__()} 方法，則會呼叫該方法在打包之前將引數轉換為整數。


在 3.2 版的變更: 新增對非整數使用 @ref{19e,,__index__()} 方法的支援。


@item 
@code{'n'} 和 @code{'N'} 轉換碼僅適用於原生大小（作為預設選擇或使用 @code{'@@'} 位元組順序字元）。對於標準大小，你可以使用適合你應用程式的其他整數格式。

@item 
對於 @code{'f'}、@code{'d'} 和 @code{'e'} 轉換碼，打包表示法使用 IEEE 754 binary32、binary64 或 binary16 格式（分別對應於 @code{'f'}、@code{'d'} 或 @code{'e'}），無論平台使用何種浮點數格式。

@item 
@code{'P'} 格式字元僅適用於原生位元組順序（作為預設選擇或使用 @code{'@@'} 位元組順序字元）。位元組順序字元 @code{'='} 根據主機系統選擇使用小端序或大端序。struct 模組不將其解釋為原生順序，因此 @code{'P'} 格式不可用。

@item 
IEEE 754 binary16「半精度 (half precision)」型別是在 2008 年的 IEEE 754 標準@footnote{https://en.wikipedia.org/wiki/IEEE_754-2008_revision}修訂版中引入的。它有一個符號位元 (sign bit)、5 位元指數和 11 位元精度（明確儲存 10 位元），可以全精度表示大約 @code{6.1e-05} 到 @code{6.5e+04} 之間的數字。此型別未被 C 編譯器廣泛支援：在典型機器上，unsigned short 可以用於儲存但不能用於數學運算。請參見 Wikipedia 上的半精度浮點數格式@footnote{https://en.wikipedia.org/wiki/Half-precision_floating-point_format}頁面以取得更多資訊。

@item 
打包時，@code{'x'} 插入一個 NUL 位元組。

@item 
@code{'p'} 格式字元編碼一個「Pascal 字串」，意思是儲存在`固定位元組數'中的短、長度可變字串，由計數指定。儲存的第一個位元組是字串的長度，或與 255 間取較小者。字串的位元組在其後。如果傳遞給 @ref{1477,,pack()} 的字串太長（長於計數減 1），則只儲存字串的前 @code{count-1} 個位元組。如果字串短於 @code{count-1}，則用空位元組填充，使得總共使用恰好 count 個位元組。請注意，對於 @ref{17da,,unpack()}， @code{'p'} 格式字元消耗 @code{count} 個位元組，但回傳的字串永遠不能包含超過 255 個位元組。

@item 
對於 @code{'s'} 格式字元，計數被直譯為位元組的長度，而不是像其他格式字元那樣的重複次數；例如，@code{'10s'} 表示一個 10 位元組字串，對應於單一 Python 位元組字串，而 @code{'10c'} 表示 10 個獨立的單位元組字元元素（例如 @code{cccccccccc}），對應於十個不同的 Python 位元組物件。（請參見 @ref{26c6,,範例} 以了解具體差異的示範。）如果未給定計數，則預設為 1。打包時，會適當地截斷或用空位元組填充字串以使其適合。解包時，結果位元組物件總是恰好具有指定的位元組數。作為特殊情況，@code{'0s'} 表示單一空字串（而 @code{'0c'} 表示 0 個字元）。

@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} and @code{D}) 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{'b'}、@code{'B'}、@code{'h'}、@code{'H'}、@code{'i'}、@code{'I'}、@code{'l'}、@code{'L'}、@code{'q'}、@code{'Q'}）打包數值 @code{x} 時，如果 @code{x} 超出該格式的有效範圍，則會觸發 @ref{1524,,struct.error}。


在 3.1 版的變更: 以前一些整數格式會環繞超出範圍的數值並引發 @ref{1a3,,DeprecationWarning} 而不是 @ref{1524,,struct.error}。


@geindex ? （問號）;於 struct format strings（結構格式字串）

對於 @code{'?'} 格式字元，回傳值是 @ref{e02,,True} 或 @ref{d23,,False}。打包時，使用引數物件的真值。原生或標準布林值表示法中的 0 或 1 將被打包，解包時任何非零值都將為 @code{True}。

@node 範例<2>,,格式字元,格式字串
@anchor{library/struct examples}@anchor{26c8}@anchor{library/struct struct-examples}@anchor{26c6}
@subsubsection 範例


@cartouche
@quotation 備註 
原生位元組順序範例（由 @code{'@@'} 格式前綴或缺少任何前綴字元指定）可能與讀者機器產生的結果不符，因為這取決於平台和編譯器。
@end quotation
@end cartouche

使用大端序打包和解包三種不同大小的整數：

@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

在原生模式下，格式字元的順序可能會影響大小，因為填充是隱式的。在標準模式下，使用者負責插入任何所需的填充。請注意下面第一個 @code{pack} 呼叫中，在打包的 @code{'#'} 之後加入了三個 NUL 位元組，以將後續整數對齊到四位元組邊界。在此範例中，輸出是在小端序機器上產生的：

@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

假設平台的 long 對齊到 4 位元組邊界，以下格式 @code{'llh0l'} 會在結尾加入兩個填充位元組：

@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 @ref{8,,array} 模組

同質資料的打包二進位儲存。

@item @ref{86,,json} 模組

JSON 編碼器和解碼器。

@item @ref{ab,,pickle} 模組

Python 物件序列化。
@end table


@node 應用,類別,格式字串,struct --- 將位元組直譯為打包起來的二進位資料
@anchor{library/struct applications}@anchor{26c9}@anchor{library/struct id2}@anchor{26ca}
@subsubsection 應用


@ref{db,,struct} 模組有兩種主要應用程式：在應用程式內或使用相同編譯器編譯的另一個應用程式之間進行 Python 和 C 程式碼的資料交換（@ref{26cb,,原生格式}），以及使用約定資料配置的應用程式之間的資料交換（@ref{26cc,,標準格式}）。一般來說，為這兩個領域建構的格式字串是不同的。

@menu
* 原生格式:: 
* 標準格式:: 

@end menu

@node 原生格式,標準格式,,應用
@anchor{library/struct native-formats}@anchor{26cd}@anchor{library/struct struct-native-formats}@anchor{26cb}
@subsubsection 原生格式


當構造模擬原生配置的格式字串時，編譯器和機器架構會決定位元組順序和填充。在這種情況下，應該使用 @code{@@} 格式字元來指定原生位元組順序和資料大小。內部填充位元組通常會自動插入。可能需要在格式字串的結尾使用零重複格式碼來向上舍入到正確的位元組邊界，以便正確對齊連續的資料區塊 (chunks)。

考慮這兩個簡單範例（在 64 位元小端序機器上）：

@example
>>> calcsize('@@lhl')
24
>>> calcsize('@@llh')
18
@end example

在第二個格式字串的結尾，如果不使用額外填充，資料不會填充到 8 位元組邊界。零重複格式碼解決了這個問題：

@example
>>> calcsize('@@llh0l')
24
@end example

@code{'x'} 格式碼可以用來指定重複，但對於原生格式來說最好使用像 @code{'0l'} 這樣的零重複格式。

預設使用原生位元組順序和對齊，但最好明確使用 @code{'@@'} 前綴字元。

@node 標準格式,,原生格式,應用
@anchor{library/struct standard-formats}@anchor{26ce}@anchor{library/struct struct-standard-formats}@anchor{26cc}
@subsubsection 標準格式


當與你的行程之外的網路或儲存區等交換資料時，要夠精確。指定確切的位元組順序、大小和對齊。不要假設它們與特定機器的原生順序匹配。例如，網路位元組順序是大端序，而許多流行的 CPU 是小端序。透過明確定義這一點，使用者無需關心其程式碼運行的平台細節。第一個字元通常應該是 @code{<} 或 @code{>}（或 @code{!}）。填充是程式設計師的責任。零重複格式字元不會起作用。取而代之的是使用者必須在需要的地方明確加入 @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 位元機器上執行）和在不同機器上執行時不保證會匹配。例如，下面的範例是在 32 位元機器上執行的：

@example
>>> calcsize('<qqh6x')
24
>>> calcsize('@@llh0l')
12
>>> pack('@@llh0l', 1, 2, 3) == pack('<qqh6x', 1, 2, 3)
False
@end example

@node 類別,,應用,struct --- 將位元組直譯為打包起來的二進位資料
@anchor{library/struct classes}@anchor{26cf}@anchor{library/struct struct-objects}@anchor{26d0}
@subsubsection 類別


@ref{db,,struct} 模組也定義了以下型別：

@geindex Struct (struct 中的類別)
@anchor{library/struct struct Struct}@anchor{1979}
@deffn {類別} struct.Struct (format)

回傳一個新的 Struct 物件，它會根據格式字串 `format' 寫入和讀取二進位資料。建立一次 @code{Struct} 物件並呼叫其方法比使用相同格式呼叫模組層級函式更有效率，因為格式字串只編譯一次。

@cartouche
@quotation 備註 
傳遞給模組層級函式的最近一個格式字串的編譯版本會被快取起來，因此僅使用少數格式字串的程式無需擔心重複使用單一 @ref{1979,,Struct} 實例。
@end quotation
@end cartouche

編譯過的 Struct 物件支援以下方法和屬性：

@geindex pack() (struct.Struct 的方法)
@anchor{library/struct struct Struct pack}@anchor{26d1}
@deffn {方法} pack (v1, v2, ...)

與 @ref{1477,,pack()} 函式相同，會使用編譯過的格式。（@code{len(result)} 將等於 @ref{26d2,,size}。）
@end deffn

@geindex pack_into() (struct.Struct 的方法)
@anchor{library/struct struct Struct pack_into}@anchor{26d3}
@deffn {方法} pack_into (buffer, offset, v1, v2, ...)

與 @ref{26c1,,pack_into()} 函式相同，會使用編譯過的格式。
@end deffn

@geindex unpack() (struct.Struct 的方法)
@anchor{library/struct struct Struct unpack}@anchor{26d4}
@deffn {方法} unpack (buffer)

與 @ref{17da,,unpack()} 函式相同，會使用編譯過的格式。緩衝區的位元組大小必須等於 @ref{26d2,,size}。
@end deffn

@geindex unpack_from() (struct.Struct 的方法)
@anchor{library/struct struct Struct unpack_from}@anchor{26d5}
@deffn {方法} unpack_from (buffer, offset=0)

與 @ref{26c2,,unpack_from()} 函式相同，會使用編譯過的格式。緩衝區從位置 `offset' 開始的位元組大小必須至少為 @ref{26d2,,size}。
@end deffn

@geindex iter_unpack() (struct.Struct 的方法)
@anchor{library/struct struct Struct iter_unpack}@anchor{11bb}
@deffn {方法} iter_unpack (buffer)

與 @ref{11ba,,iter_unpack()} 函式相同，會使用編譯過的格式。緩衝區的位元組大小必須是 @ref{26d2,,size} 的倍數。


在 3.4 版被加入.

@end deffn

@geindex format (struct.Struct 的屬性)
@anchor{library/struct struct Struct format}@anchor{dfb}
@deffn {屬性} format

用於建構此 Struct 物件的格式字串。


在 3.7 版的變更: 格式字串型別現在是 @ref{169,,str} 而不是 @ref{192,,bytes}。

@end deffn

@geindex size (struct.Struct 的屬性)
@anchor{library/struct struct Struct size}@anchor{26d2}
@deffn {屬性} size

對應於 @ref{199,,format} 的結構之計算出的大小（因此也是 @ref{1477,,pack()} 方法所產生的位元組物件的大小）。
@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 --- 編解碼器註冊表和基底類別,,struct --- 將位元組直譯為打包起來的二進位資料,二進位資料服務
@anchor{library/codecs doc}@anchor{26d6}@anchor{library/codecs codecs-codec-registry-and-base-classes}@anchor{26d7}@anchor{library/codecs module-codecs}@anchor{1c}@anchor{library/codecs translation-repo}@anchor{26d8}
@subsection @code{codecs} --- 編解碼器註冊表和基底類別


@geindex module; codecs

`原始碼：'Lib/codecs.py@footnote{https://github.com/python/cpython/tree/3.14/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{2486,,text encodings}, which encode text to bytes (and
decode bytes to text), but there are also codecs provided that encode text to
text, and bytes to bytes. Custom codecs may encode and decode between arbitrary
types, but some module features are restricted to be used specifically with
@ref{2486,,text encodings} or with codecs that encode to
@ref{192,,bytes}.

這個模組定義了以下函式，用於以任何編解碼器來編碼與解碼：

@geindex encode() (於 codecs 模組中)
@anchor{library/codecs codecs encode}@anchor{10ff}
@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{2eb,,ValueError} (or a more codec specific subclass, such as
@ref{880,,UnicodeEncodeError}). Refer to @ref{26d9,,Codec Base Classes} for more
information on codec error handling.
@end deffn

@geindex decode() (於 codecs 模組中)
@anchor{library/codecs codecs decode}@anchor{1100}
@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{2eb,,ValueError} (or a more codec specific subclass, such as
@ref{bff,,UnicodeDecodeError}). Refer to @ref{26d9,,Codec Base Classes} for more
information on codec error handling.
@end deffn

@geindex charmap_build() (於 codecs 模組中)
@anchor{library/codecs codecs charmap_build}@anchor{26da}
@deffn {函式} codecs.charmap_build (string)

Return a mapping suitable for encoding with a custom single-byte encoding.
Given a @ref{169,,str} `string' of up to 256 characters representing a
decoding table, returns either a compact internal mapping object
@code{EncodingMap} or a @ref{183,,dictionary} mapping character ordinals
to byte values. Raises a @ref{198,,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{b53}
@deffn {函式} codecs.lookup (encoding, /)

Looks up the codec info in the Python codec registry and returns a
@ref{19be,,CodecInfo} object as defined below.

Encodings are first looked up in the registry's cache. If not found, the list of
registered search functions is scanned. If no @ref{19be,,CodecInfo} object is
found, a @ref{2500,,LookupError} is raised. Otherwise, the @ref{19be,,CodecInfo} object
is stored in the cache and returned to the caller.
@end deffn

@geindex CodecInfo (codecs 中的類別)
@anchor{library/codecs codecs CodecInfo}@anchor{19be}
@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{26db}
@deffn {屬性} name

編碼的名稱。
@end deffn

@geindex encode (codecs.CodecInfo 的屬性)
@geindex decode (codecs.CodecInfo 的屬性)
@anchor{library/codecs codecs CodecInfo encode}@anchor{26dc}
@deffn {屬性} encode
@anchor{library/codecs codecs CodecInfo decode}@anchor{26dd}
@deffnx {屬性} decode

The stateless encoding and decoding functions. These must be
functions or methods which have the same interface as
the @ref{26de,,encode()} and @ref{26df,,decode()} methods of Codec
instances (see @ref{26e0,,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{26e1}
@deffn {屬性} incrementalencoder
@anchor{library/codecs codecs CodecInfo incrementaldecoder}@anchor{26e2}
@deffnx {屬性} incrementaldecoder

Incremental encoder and decoder classes or factory functions.
These have to provide the interface defined by the base classes
@ref{26e3,,IncrementalEncoder} and @ref{26e4,,IncrementalDecoder},
respectively. Incremental codecs can maintain state.
@end deffn

@geindex streamwriter (codecs.CodecInfo 的屬性)
@geindex streamreader (codecs.CodecInfo 的屬性)
@anchor{library/codecs codecs CodecInfo streamwriter}@anchor{26e5}
@deffn {屬性} streamwriter
@anchor{library/codecs codecs CodecInfo streamreader}@anchor{26e6}
@deffnx {屬性} streamreader

Stream writer and reader classes or factory functions. These have to
provide the interface defined by the base classes
@ref{26e7,,StreamWriter} and @ref{26e8,,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{b53,,lookup()} for the codec lookup:

@geindex getencoder() (於 codecs 模組中)
@anchor{library/codecs codecs getencoder}@anchor{26e9}
@deffn {函式} codecs.getencoder (encoding)

Look up the codec for the given encoding and return its encoder function.

Raises a @ref{2500,,LookupError} in case the encoding cannot be found.
@end deffn

@geindex getdecoder() (於 codecs 模組中)
@anchor{library/codecs codecs getdecoder}@anchor{26ea}
@deffn {函式} codecs.getdecoder (encoding)

Look up the codec for the given encoding and return its decoder function.

Raises a @ref{2500,,LookupError} in case the encoding cannot be found.
@end deffn

@geindex getincrementalencoder() (於 codecs 模組中)
@anchor{library/codecs codecs getincrementalencoder}@anchor{26eb}
@deffn {函式} codecs.getincrementalencoder (encoding)

Look up the codec for the given encoding and return its incremental encoder
class or factory function.

Raises a @ref{2500,,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{26ec}
@deffn {函式} codecs.getincrementaldecoder (encoding)

Look up the codec for the given encoding and return its incremental decoder
class or factory function.

Raises a @ref{2500,,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{26ed}
@deffn {函式} codecs.getreader (encoding)

Look up the codec for the given encoding and return its @ref{26e8,,StreamReader}
class or factory function.

Raises a @ref{2500,,LookupError} in case the encoding cannot be found.
@end deffn

@geindex getwriter() (於 codecs 模組中)
@anchor{library/codecs codecs getwriter}@anchor{26ee}
@deffn {函式} codecs.getwriter (encoding)

Look up the codec for the given encoding and return its @ref{26e7,,StreamWriter}
class or factory function.

Raises a @ref{2500,,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{26ef}
@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 hyphens
and spaces converted to underscores, and return a @ref{19be,,CodecInfo} object.
In case a search function cannot find a given encoding, it should return
@code{None}.


在 3.9 版的變更: Hyphens and spaces are converted to underscore.

@end deffn

@geindex unregister() (於 codecs 模組中)
@anchor{library/codecs codecs unregister}@anchor{9e2}
@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.


在 3.10 版被加入.

@end deffn

While the builtin @ref{315,,open()} and the associated @ref{83,,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{314}
@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{26f0,,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
@ref{315,,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{2eb,,ValueError} to be raised in case an encoding error occurs.

`buffering' has the same meaning as for the built-in @ref{315,,open()} function.
It defaults to -1 which means that the default buffer size will be used.


在 3.11 版的變更: 已移除 @code{'U'} 模式。



在 3.14 版之後被棄用: @ref{314,,codecs.open()} has been superseded by @ref{315,,open()}.

@end deffn

@geindex EncodedFile() (於 codecs 模組中)
@anchor{library/codecs codecs EncodedFile}@anchor{26f1}
@deffn {函式} codecs.EncodedFile (file, data_encoding, file_encoding=None, errors='strict')

Return a @ref{1c9d,,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{2eb,,ValueError} to be raised in case an encoding
error occurs.
@end deffn

@geindex iterencode() (於 codecs 模組中)
@anchor{library/codecs codecs iterencode}@anchor{26f2}
@deffn {函式} codecs.iterencode (iterator, encoding, errors='strict', **kwargs)

Uses an incremental encoder to iteratively encode the input provided by
`iterator'. `iterator' must yield @ref{169,,str} objects.
This function is a @ref{125c,,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{169,,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{26f3}
@deffn {函式} codecs.iterdecode (iterator, encoding, errors='strict', **kwargs)

Uses an incremental decoder to iteratively decode the input provided by
`iterator'. `iterator' must yield @ref{192,,bytes} objects.
This function is a @ref{125c,,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{192,,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{26f2,,iterencode()}.
@end deffn

@geindex readbuffer_encode() (於 codecs 模組中)
@anchor{library/codecs codecs readbuffer_encode}@anchor{26f4}
@deffn {函式} codecs.readbuffer_encode (buffer, errors=None, /)

Return a @ref{60c,,tuple} containing the raw bytes of `buffer', a
@ref{260,,buffer-compatible object} or @ref{169,,str}
(encoded to UTF-8 before processing), and their length in bytes.

忽略 `errors' 引數。

@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{26f5}
@deffn {資料} codecs.BOM
@anchor{library/codecs codecs BOM_BE}@anchor{26f6}
@deffnx {資料} codecs.BOM_BE
@anchor{library/codecs codecs BOM_LE}@anchor{26f7}
@deffnx {資料} codecs.BOM_LE
@anchor{library/codecs codecs BOM_UTF8}@anchor{26f8}
@deffnx {資料} codecs.BOM_UTF8
@anchor{library/codecs codecs BOM_UTF16}@anchor{26f9}
@deffnx {資料} codecs.BOM_UTF16
@anchor{library/codecs codecs BOM_UTF16_BE}@anchor{26fa}
@deffnx {資料} codecs.BOM_UTF16_BE
@anchor{library/codecs codecs BOM_UTF16_LE}@anchor{26fb}
@deffnx {資料} codecs.BOM_UTF16_LE
@anchor{library/codecs codecs BOM_UTF32}@anchor{26fc}
@deffnx {資料} codecs.BOM_UTF32
@anchor{library/codecs codecs BOM_UTF32_BE}@anchor{26fd}
@deffnx {資料} codecs.BOM_UTF32_BE
@anchor{library/codecs codecs BOM_UTF32_LE}@anchor{26fe}
@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{26f9,,BOM_UTF16} is either
@ref{26fa,,BOM_UTF16_BE} or @ref{26fb,,BOM_UTF16_LE} depending on the platform's
native byte order, @ref{26f5,,BOM} is an alias for @ref{26f9,,BOM_UTF16},
@ref{26f7,,BOM_LE} for @ref{26fb,,BOM_UTF16_LE} and @ref{26f6,,BOM_BE} for
@ref{26fa,,BOM_UTF16_BE}. The others represent the BOM in UTF-8 and UTF-32
encodings.
@end deffn

@menu
* Codec Base Classes:: 
* 編碼和 Unicode:: 
* 標準編碼:: 
* Python Specific Encodings:: 
* encodings: encodings --- Encodings package. Encodings package
* encodings.idna: encodings idna --- Internationalized Domain Names in Applications. Internationalized Domain Names in Applications
* encodings.mbcs: encodings mbcs --- Windows ANSI 碼頁. Windows ANSI 碼頁
* encodings.utf_8_sig: encodings utf_8_sig --- UTF-8 codec with BOM signature. UTF-8 codec with BOM signature

@end menu

@node Codec Base Classes,編碼和 Unicode,,codecs --- 編解碼器註冊表和基底類別
@anchor{library/codecs codec-base-classes}@anchor{26d9}@anchor{library/codecs id1}@anchor{26ff}
@subsubsection Codec Base Classes


The @ref{1c,,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{2700}
@menu
* Error Handlers:: 
* Stateless Encoding and Decoding:: 
* Incremental Encoding and Decoding:: 
* 串流編碼和解碼:: 

@end menu

@node Error Handlers,Stateless Encoding and Decoding,,Codec Base Classes
@anchor{library/codecs error-handlers}@anchor{1a9e}@anchor{library/codecs id2}@anchor{2701}
@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 ? （問號）;replacement character（替代字元）
@geindex \ （反斜線）;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{fb3,,標準編碼} codecs:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Value

@tab

含義

@item

@code{'strict'}

@tab

Raise @ref{460,,UnicodeError} (or a subclass),
this is the default. Implemented in
@ref{2702,,strict_errors()}.

@item

@code{'ignore'}

@tab

Ignore the malformed data and continue without
further notice. Implemented in
@ref{2703,,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{1836,,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{1837,,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{2486,,text encodings}):


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Value

@tab

含義

@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{1838,,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{2704,,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

含義

@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{169,,str} as an error.

@end multitable



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



在 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{168f}
@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{880,,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{169,,str} or
@ref{192,,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{1729,,IndexError} will be raised.

Decoding and translating works similarly, except @ref{bff,,UnicodeDecodeError} or
@ref{1868,,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{1690}
@deffn {函式} codecs.lookup_error (name, /)

Return the error handler previously registered under the name `name'.

Raises a @ref{2500,,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{2702}
@deffn {函式} codecs.strict_errors (exception)

Implements the @code{'strict'} error handling.

Each encoding or decoding error raises a @ref{460,,UnicodeError}.
@end deffn

@geindex ignore_errors() (於 codecs 模組中)
@anchor{library/codecs codecs ignore_errors}@anchor{2703}
@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{1836}
@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{1837}
@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{1838}
@deffn {函式} codecs.xmlcharrefreplace_errors (exception)

Implements the @code{'xmlcharrefreplace'} error handling (for encoding within
@ref{2486,,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{2704}
@deffn {函式} codecs.namereplace_errors (exception)

Implements the @code{'namereplace'} error handling (for encoding within
@ref{2486,,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@}} .


在 3.5 版被加入.

@end deffn

@node Stateless Encoding and Decoding,Incremental Encoding and Decoding,Error Handlers,Codec Base Classes
@anchor{library/codecs codec-objects}@anchor{26e0}@anchor{library/codecs stateless-encoding-and-decoding}@anchor{2705}
@subsubsection Stateless Encoding and Decoding


The base @ref{2706,,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{2706}
@deffn {類別} codecs.Codec

@geindex encode() (codecs.Codec 的方法)
@anchor{library/codecs codecs Codec encode}@anchor{26de}
@deffn {方法} encode (input, errors='strict')

Encodes the object `input' and returns a tuple (output object, length consumed).
For instance, @ref{2486,,text encoding} converts
a string object to a bytes object using a particular
character set encoding (e.g., @code{cp1252} or @code{iso-8859-1}).

The `errors' argument defines the error handling to apply.
It defaults to @code{'strict'} handling.

The method may not store state in the @ref{2706,,Codec} instance. Use
@ref{26e7,,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{26df}
@deffn {方法} decode (input, errors='strict')

Decodes the object `input' and returns a tuple (output object, length
consumed). For instance, for a @ref{2486,,text encoding}, decoding converts
a bytes object encoded using a particular
character set encoding to a string object.

For text encodings and bytes-to-bytes codecs,
`input' must be a bytes object or one which provides the read-only
buffer interface -- for example, buffer objects and memory mapped files.

The `errors' argument defines the error handling to apply.
It defaults to @code{'strict'} handling.

The method may not store state in the @ref{2706,,Codec} instance. Use
@ref{26e8,,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,串流編碼和解碼,Stateless Encoding and Decoding,Codec Base Classes
@anchor{library/codecs incremental-encoding-and-decoding}@anchor{2707}
@subsubsection Incremental Encoding and Decoding


The @ref{26e3,,IncrementalEncoder} and @ref{26e4,,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{2708,,encode()}/@ref{2709,,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{2708,,encode()}/@ref{2709,,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 物件:: 
* IncrementalDecoder 物件:: 

@end menu

@node IncrementalEncoder 物件,IncrementalDecoder 物件,,Incremental Encoding and Decoding
@anchor{library/codecs incremental-encoder-objects}@anchor{270a}@anchor{library/codecs incrementalencoder-objects}@anchor{270b}
@subsubsection IncrementalEncoder 物件


The @ref{26e3,,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{26e3}
@deffn {類別} codecs.IncrementalEncoder (errors='strict')

@ref{26e3,,IncrementalEncoder} 的建構函式。

All incremental encoders must provide this constructor interface. They are free
to add additional keyword arguments, but only the ones defined here are used by
the Python codec registry.

The @ref{26e3,,IncrementalEncoder} may implement different error handling schemes
by providing the `errors' keyword argument. See @ref{1a9e,,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 @ref{26e3,,IncrementalEncoder}
object.

@geindex encode() (codecs.IncrementalEncoder 的方法)
@anchor{library/codecs codecs IncrementalEncoder encode}@anchor{2708}
@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
@ref{10ff,,encode()} `final' must be true (the default is false).
@end deffn

@geindex reset() (codecs.IncrementalEncoder 的方法)
@anchor{library/codecs codecs IncrementalEncoder reset}@anchor{270c}
@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{270d}
@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{270e}
@deffn {方法} setstate (state)

Set the state of the encoder to `state'. `state' must be an encoder state
returned by @ref{270d,,getstate()}.
@end deffn
@end deffn

@node IncrementalDecoder 物件,,IncrementalEncoder 物件,Incremental Encoding and Decoding
@anchor{library/codecs incremental-decoder-objects}@anchor{270f}@anchor{library/codecs incrementaldecoder-objects}@anchor{2710}
@subsubsection IncrementalDecoder 物件


The @ref{26e4,,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{26e4}
@deffn {類別} codecs.IncrementalDecoder (errors='strict')

@ref{26e4,,IncrementalDecoder} 的建構函式。

All incremental decoders must provide this constructor interface. They are free
to add additional keyword arguments, but only the ones defined here are used by
the Python codec registry.

The @ref{26e4,,IncrementalDecoder} may implement different error handling schemes
by providing the `errors' keyword argument. See @ref{1a9e,,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 @ref{26e4,,IncrementalDecoder}
object.

@geindex decode() (codecs.IncrementalDecoder 的方法)
@anchor{library/codecs codecs IncrementalDecoder decode}@anchor{2709}
@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
@ref{1100,,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{2711}
@deffn {方法} reset ()

將解碼器重設到初始狀態。
@end deffn

@geindex getstate() (codecs.IncrementalDecoder 的方法)
@anchor{library/codecs codecs IncrementalDecoder getstate}@anchor{2712}
@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{2713}
@deffn {方法} setstate (state)

Set the state of the decoder to `state'. `state' must be a decoder state
returned by @ref{2712,,getstate()}.
@end deffn
@end deffn

@node 串流編碼和解碼,,Incremental Encoding and Decoding,Codec Base Classes
@anchor{library/codecs stream-encoding-and-decoding}@anchor{2714}
@subsubsection 串流編碼和解碼


The @ref{26e7,,StreamWriter} and @ref{26e8,,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 物件:: 
* StreamReader 物件:: 
* StreamReaderWriter 物件:: 
* StreamRecoder 物件:: 

@end menu

@node StreamWriter 物件,StreamReader 物件,,串流編碼和解碼
@anchor{library/codecs stream-writer-objects}@anchor{2715}@anchor{library/codecs streamwriter-objects}@anchor{2716}
@subsubsection StreamWriter 物件


The @ref{26e7,,StreamWriter} class is a subclass of @ref{2706,,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{26e7}
@deffn {類別} codecs.StreamWriter (stream, errors='strict')

@ref{26e7,,StreamWriter} 的建構函式。

All stream writers must provide this constructor interface. They are free to add
additional keyword arguments, but only the ones defined here are used by the
Python codec registry.

The `stream' argument must be a file-like object open for writing
text or binary data, as appropriate for the specific codec.

The @ref{26e7,,StreamWriter} may implement different error handling schemes by
providing the `errors' keyword argument. See @ref{1a9e,,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 @ref{26e7,,StreamWriter} object.

@geindex write() (codecs.StreamWriter 的方法)
@anchor{library/codecs codecs StreamWriter write}@anchor{2717}
@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{2718}
@deffn {方法} writelines (list)

Writes the concatenated iterable of strings to the stream (possibly by reusing
the @ref{2717,,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{2719}
@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{26e7,,StreamWriter} must also inherit
all other methods and attributes from the underlying stream.

@node StreamReader 物件,StreamReaderWriter 物件,StreamWriter 物件,串流編碼和解碼
@anchor{library/codecs stream-reader-objects}@anchor{271a}@anchor{library/codecs streamreader-objects}@anchor{271b}
@subsubsection StreamReader 物件


The @ref{26e8,,StreamReader} class is a subclass of @ref{2706,,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{26e8}
@deffn {類別} codecs.StreamReader (stream, errors='strict')

@ref{26e8,,StreamReader} 的建構函式。

All stream readers must provide this constructor interface. They are free to add
additional keyword arguments, but only the ones defined here are used by the
Python codec registry.

The `stream' argument must be a file-like object open for reading
text or binary data, as appropriate for the specific codec.

The @ref{26e8,,StreamReader} may implement different error handling schemes by
providing the `errors' keyword argument. See @ref{1a9e,,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 @ref{26e8,,StreamReader} object.

The set of allowed values for the `errors' argument can be extended with
@ref{168f,,register_error()}.

@geindex read() (codecs.StreamReader 的方法)
@anchor{library/codecs codecs StreamReader read}@anchor{271c}
@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{271c,,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{271d}
@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{271c,,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{271e}
@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{1100,,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{271c,,read()} method.
@end deffn

@geindex reset() (codecs.StreamReader 的方法)
@anchor{library/codecs codecs StreamReader reset}@anchor{271f}
@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{26e8,,StreamReader} must also inherit
all other methods and attributes from the underlying stream.

@node StreamReaderWriter 物件,StreamRecoder 物件,StreamReader 物件,串流編碼和解碼
@anchor{library/codecs stream-reader-writer}@anchor{2720}@anchor{library/codecs streamreaderwriter-objects}@anchor{2721}
@subsubsection StreamReaderWriter 物件


The @ref{26f0,,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{b53,,lookup()} function to construct the instance.

@geindex StreamReaderWriter (codecs 中的類別)
@anchor{library/codecs codecs StreamReaderWriter}@anchor{26f0}
@deffn {類別} codecs.StreamReaderWriter (stream, Reader, Writer, errors='strict')

Creates a @ref{26f0,,StreamReaderWriter} instance. `stream' must be a file-like
object. `Reader' and `Writer' must be factory functions or classes providing the
@ref{26e8,,StreamReader} and @ref{26e7,,StreamWriter} interface resp. Error handling
is done in the same way as defined for the stream readers and writers.
@end deffn

@ref{26f0,,StreamReaderWriter} instances define the combined interfaces of
@ref{26e8,,StreamReader} and @ref{26e7,,StreamWriter} classes. They inherit all other
methods and attributes from the underlying stream.

@node StreamRecoder 物件,,StreamReaderWriter 物件,串流編碼和解碼
@anchor{library/codecs stream-recoder-objects}@anchor{2722}@anchor{library/codecs streamrecoder-objects}@anchor{2723}
@subsubsection StreamRecoder 物件


The @ref{1c9d,,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{b53,,lookup()} function to construct the instance.

@geindex StreamRecoder (codecs 中的類別)
@anchor{library/codecs codecs StreamRecoder}@anchor{1c9d}
@deffn {類別} codecs.StreamRecoder (stream, encode, decode, Reader, Writer, errors='strict')

Creates a @ref{1c9d,,StreamRecoder} instance which implements a two-way conversion:
`encode' and `decode' work on the frontend — the data visible to
code calling @ref{271c,,read()} and @ref{2717,,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.

`stream' 引數必須是類檔案物件。

The `encode' and `decode' arguments must
adhere to the @ref{2706,,Codec} interface. `Reader' and
`Writer' must be factory functions or classes providing objects of the
@ref{26e8,,StreamReader} and @ref{26e7,,StreamWriter} interface respectively.

Error handling is done in the same way as defined for the stream readers and
writers.
@end deffn

@ref{1c9d,,StreamRecoder} instances define the combined interfaces of
@ref{26e8,,StreamReader} and @ref{26e7,,StreamWriter} classes. They inherit all other
methods and attributes from the underlying stream.

@node 編碼和 Unicode,標準編碼,Codec Base Classes,codecs --- 編解碼器註冊表和基底類別
@anchor{library/codecs encodings-and-unicode}@anchor{2724}@anchor{library/codecs encodings-overview}@anchor{2725}
@subsubsection 編碼和 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{2486,,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{880,,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 標準編碼,Python Specific Encodings,編碼和 Unicode,codecs --- 編解碼器註冊表和基底類別
@anchor{library/codecs id3}@anchor{2726}@anchor{library/codecs standard-encodings}@anchor{fb3}
@subsubsection 標準編碼


Python comes with a number of codecs built-in, either implemented as C functions
or with dictionaries as mapping tables. The following table lists the codecs by
name, together with a few common aliases, and the languages for which the
encoding is likely used. Neither the list of aliases nor the list of languages
is meant to be exhaustive. Notice that spelling alternatives that only differ in
case or use a hyphen instead of an underscore are also valid aliases
because they are equivalent when normalized by
@ref{9f6,,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/3.14/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 guarantead 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

語言

@item

ascii

@tab

646, us-ascii

@tab

英文

@item

big5

@tab

big5-tw, csbig5

@tab

繁體中文

@item

big5hkscs

@tab

big5-hkscs, hkscs

@tab

繁體中文

@item

cp037

@tab

IBM037, IBM039

@tab

英文

@item

cp273

@tab

273, IBM273, csIBM273

@tab

德文


在 3.4 版被加入.


@item

cp424

@tab

EBCDIC-CP-HE, IBM424

@tab

希伯來文

@item

cp437

@tab

437, IBM437

@tab

英文

@item

cp500

@tab

EBCDIC-CP-BE, EBCDIC-CP-CH,
IBM500

@tab

Western Europe

@item

cp720

@tab

@tab

阿拉伯文

@item

cp737

@tab

@tab

希臘文

@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

希伯來文

@item

cp857

@tab

857, IBM857

@tab

土耳其文

@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

希伯來文

@item

cp863

@tab

863, IBM863

@tab

Canadian

@item

cp864

@tab

IBM864

@tab

阿拉伯文

@item

cp865

@tab

865, IBM865

@tab

Danish, Norwegian

@item

cp866

@tab

866, IBM866

@tab

俄羅斯文

@item

cp869

@tab

869, CP-GR, IBM869

@tab

希臘文

@item

cp874

@tab

@tab

泰文

@item

cp875

@tab

@tab

希臘文

@item

cp932

@tab

932, ms932, mskanji, ms-kanji,
windows-31j

@tab

日文

@item

cp949

@tab

949, ms949, uhc

@tab

韓文

@item

cp950

@tab

950, ms950

@tab

繁體中文

@item

cp1006

@tab

@tab

Urdu

@item

cp1026

@tab

ibm1026

@tab

土耳其文

@item

cp1125

@tab

1125, ibm1125, cp866u, ruscii

@tab

烏克蘭文


在 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

希臘文

@item

cp1254

@tab

windows-1254

@tab

土耳其文

@item

cp1255

@tab

windows-1255

@tab

希伯來文

@item

cp1256

@tab

windows-1256

@tab

阿拉伯文

@item

cp1257

@tab

windows-1257

@tab

Baltic languages

@item

cp1258

@tab

windows-1258

@tab

越南文

@item

euc_jp

@tab

eucjp, ujis, u-jis

@tab

日文

@item

euc_jis_2004

@tab

jisx0213, eucjis2004

@tab

日文

@item

euc_jisx0213

@tab

eucjisx0213

@tab

日文

@item

euc_kr

@tab

euckr, korean, ksc5601,
ks_c-5601, ks_c-5601-1987,
ksx1001, ks_x-1001

@tab

韓文

@item

gb2312

@tab

chinese, csiso58gb231280,
euc-cn, euccn, eucgb2312-cn,
gb2312-1980, gb2312-80,
iso-ir-58

@tab

簡體中文

@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

簡體中文

@item

iso2022_jp

@tab

csiso2022jp, iso2022jp,
iso-2022-jp

@tab

日文

@item

iso2022_jp_1

@tab

iso2022jp-1, iso-2022-jp-1

@tab

日文

@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

日文

@item

iso2022_jp_3

@tab

iso2022jp-3, iso-2022-jp-3

@tab

日文

@item

iso2022_jp_ext

@tab

iso2022jp-ext, iso-2022-jp-ext

@tab

日文

@item

iso2022_kr

@tab

csiso2022kr, iso2022kr,
iso-2022-kr

@tab

韓文

@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

阿拉伯文

@item

iso8859_7

@tab

iso-8859-7, greek, greek8

@tab

希臘文

@item

iso8859_8

@tab

iso-8859-8, hebrew

@tab

希伯來文

@item

iso8859_9

@tab

iso-8859-9, latin5, L5

@tab

土耳其文

@item

iso8859_10

@tab

iso-8859-10, latin6, L6

@tab

Nordic languages

@item

iso8859_11

@tab

iso-8859-11, thai

@tab

泰語

@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

韓文

@item

koi8_r

@tab

@tab

俄羅斯文

@item

koi8_t

@tab

@tab

Tajik


在 3.5 版被加入.


@item

koi8_u

@tab

@tab

烏克蘭文

@item

kz1048

@tab

kz_1048, strk1048_2002, rk1048

@tab

Kazakh


在 3.5 版被加入.


@item

mac_cyrillic

@tab

maccyrillic

@tab

Belarusian, Bulgarian,
Macedonian, Russian, Serbian

@item

mac_greek

@tab

macgreek

@tab

希臘文

@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

土耳其文

@item

ptcp154

@tab

csptcp154, pt154, cp154,
cyrillic-asian

@tab

Kazakh

@item

shift_jis

@tab

csshiftjis, shiftjis, sjis,
s_jis

@tab

日文

@item

shift_jis_2004

@tab

shiftjis2004, sjis_2004,
sjis2004

@tab

日文

@item

shift_jisx0213

@tab

shiftjisx0213, sjisx0213,
s_jisx0213

@tab

日文

@item

utf_32

@tab

U32, utf32

@tab

all languages

@item

utf_32_be

@tab

UTF-32BE

@tab

all languages

@item

utf_32_le

@tab

UTF-32LE

@tab

all languages

@item

utf_16

@tab

U16, utf16

@tab

all languages

@item

utf_16_be

@tab

UTF-16BE

@tab

all languages

@item

utf_16_le

@tab

UTF-16LE

@tab

all languages

@item

utf_7

@tab

U7, unicode-1-1-utf-7

@tab

all languages

@item

utf_8

@tab

U8, UTF, utf8, cp65001

@tab

all languages

@item

utf_8_sig

@tab

@tab

all languages

@end multitable



在 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} 現在是 @code{utf_8} 的別名。



在 3.14 版的變更: On Windows, @code{cpXXX} codecs are now available for all code pages.


@node Python Specific Encodings,encodings --- Encodings package,標準編碼,codecs --- 編解碼器註冊表和基底類別
@anchor{library/codecs python-specific-encodings}@anchor{2727}
@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{2728}
@subsubsection Text Encodings


The following codecs provide @ref{169,,str} to @ref{192,,bytes} encoding and
@ref{193,,bytes-like object} to @ref{169,,str} decoding, similar to the Unicode text
encodings.


@multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Codec

@tab

Aliases

@tab

含義

@item

idna

@tab

@tab

Implement 
@geindex RFC; RFC 3490
RFC 3490@footnote{https://datatracker.ietf.org/doc/html/rfc3490.html},
see also
@ref{56,,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).


在 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{1101}@anchor{library/codecs id4}@anchor{2729}
@subsubsection Binary Transforms


The following codecs provide binary transforms: @ref{193,,bytes-like object}
to @ref{192,,bytes} mappings. They are not supported by @ref{aca,,bytes.decode()}
(which only produces @ref{169,,str} output).


@multitable {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Codec

@tab

Aliases

@tab

含義

@tab

Encoder / decoder

@item

base64_codec @footnote{
In addition to @ref{193,,bytes-like objects},
@code{'base64_codec'} also accepts ASCII-only instances of @ref{169,,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{193,,bytes-like object}
as input for encoding and
decoding


@tab

@ref{b43,,base64.encodebytes()} /
@ref{b44,,base64.decodebytes()}

@item

bz2_codec

@tab

bz2

@tab

Compress the operand using
bz2.

@tab

@ref{272a,,bz2.compress()} /
@ref{128f,,bz2.decompress()}

@item

hex_codec

@tab

hex

@tab

Convert the operand to
hexadecimal
representation, with two
digits per byte.

@tab

@ref{272b,,binascii.b2a_hex()} /
@ref{272c,,binascii.a2b_hex()}

@item

quopri_codec

@tab

quopri,
quotedprintable,
quoted_printable

@tab

Convert the operand to MIME
quoted printable.

@tab

@ref{272d,,quopri.encode()} with
@code{quotetabs=True} /
@ref{272e,,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{848,,zlib.compress()} /
@ref{f04,,zlib.decompress()}

@end multitable



在 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{272f}@anchor{library/codecs standalone-codec-functions}@anchor{2730}
@subsubsection Standalone Codec Functions


The following functions provide encoding and decoding functionality similar to codecs,
but are not available as named codecs through @ref{10ff,,codecs.encode()} or @ref{1100,,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{2731}
@deffn {函式} codecs.escape_encode (input, errors=None)

Encode `input' using escape sequences. Similar to how @ref{1c1,,repr()} on bytes
produces escaped byte values.

`input' must be a @ref{192,,bytes} object.

Returns a tuple @code{(output, length)} where `output' is a @ref{192,,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{2732}
@deffn {函式} codecs.escape_decode (input, errors=None)

Decode `input' from escape sequences back to the original bytes.

`input' 必須是個 @ref{193,,bytes-like object}。

Returns a tuple @code{(output, length)} where `output' is a @ref{192,,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{2733}@anchor{library/codecs text-transforms}@anchor{1102}
@subsubsection Text Transforms


The following codec provides a text transform: a @ref{169,,str} to @ref{169,,str}
mapping. It is not supported by @ref{ac9,,str.encode()} (which only produces
@ref{192,,bytes} output).


@multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Codec

@tab

Aliases

@tab

含義

@item

rot_13

@tab

rot13

@tab

Return the Caesar-cypher
encryption of the
operand.

@end multitable



在 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 --- 編解碼器註冊表和基底類別
@anchor{library/codecs encodings-encodings-package}@anchor{2734}@anchor{library/codecs module-encodings}@anchor{55}
@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{9f6}
@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{b53,,codecs.lookup()} should be used instead.
@end quotation
@end cartouche

@geindex search_function() (於 encodings 模組中)
@anchor{library/codecs encodings search_function}@anchor{2735}
@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{9f6,,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{19be,,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{2736}
@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{19be,,codecs.CodecInfo}
object for it.

@ref{2006,,可用性}: Windows.


在 3.14 版被加入.

@end deffn

This module implements the following exception:

@geindex CodecRegistryError
@anchor{library/codecs encodings CodecRegistryError}@anchor{2737}
@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 碼頁,encodings --- Encodings package,codecs --- 編解碼器註冊表和基底類別
@anchor{library/codecs encodings-idna-internationalized-domain-names-in-applications}@anchor{2738}@anchor{library/codecs module-encodings idna}@anchor{56}
@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{da,,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{d1,,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{73,,http.client} and @ref{62,,ftplib}, accept Unicode host
names (@ref{73,,http.client} then also transparently sends an IDNA hostname in the
@code{Host} field if it sends that field at all).

When receiving host names from the wire (such as in reverse name lookup), no
automatic conversion to Unicode is performed: applications wishing to present
such host names to the user should decode them to Unicode.

The module @ref{56,,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{2739}
@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{273a}
@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{273b}
@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 碼頁,encodings utf_8_sig --- UTF-8 codec with BOM signature,encodings idna --- Internationalized Domain Names in Applications,codecs --- 編解碼器註冊表和基底類別
@anchor{library/codecs encodings-mbcs-windows-ansi-codepage}@anchor{273c}@anchor{library/codecs module-encodings mbcs}@anchor{57}
@subsubsection @code{encodings.mbcs} --- Windows ANSI 碼頁


@geindex module; encodings.mbcs

這個模組實作了 ANSI 碼頁 (CP_ACP)。

@ref{2006,,可用性}: 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 碼頁,codecs --- 編解碼器註冊表和基底類別
@anchor{library/codecs encodings-utf-8-sig-utf-8-codec-with-bom-signature}@anchor{273d}@anchor{library/codecs module-encodings utf_8_sig}@anchor{58}
@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 資料型別,數值與數學模組,二進位資料服務,Python 標準函式庫 Standard Library
@anchor{library/datatypes doc}@anchor{273e}@anchor{library/datatypes data-types}@anchor{273f}@anchor{library/datatypes datatypes}@anchor{2740}@anchor{library/datatypes translation-repo}@anchor{2741}
@section 資料型別


本章節所描述的模組 (module) 提供了多樣的專門資料型別，例如日期與時間、固定型別陣列 (fixed-type arrays)、堆積佇列 (heap queues)、雙端佇列 (double-ended queues) 與列舉 (enumerations)。

Python 也有提供一些內建資料型別，特別是 @ref{183,,dict}、@ref{24d,,list}、@ref{184,,set} 與 @ref{7eb,,frozenset} 和 @ref{60c,,tuple}。@ref{169,,str} 類別是用來儲存 Unicode 字串，@ref{192,,bytes} 與 @ref{343,,bytearray} 類別則是用來儲存二進位制資料。

本章節包含下列模組的文件：

@menu
* datetime: datetime --- 日期與時間的基本型別. 日期與時間的基本型別
* zoneinfo: zoneinfo --- IANA 時區支援. IANA 時區支援
* calendar: calendar --- 日曆相關函式. 日曆相關函式
* collections: collections --- 容器資料型態. 容器資料型態
* collections.abc: collections abc --- 容器的抽象基底類別. 容器的抽象基底類別
* heapq: heapq --- 堆積佇列 heap queue 演算法. 堆積佇列 (heap queue) 演算法
* bisect: bisect --- 陣列二分演算法 Array bisection algorithm. 陣列二分演算法 (Array bisection algorithm)
* array: array --- 高效率的數值型陣列. 高效率的數值型陣列
* weakref: weakref --- 弱參照. 弱參照
* types: types --- 動態型別建立與內建型別名稱. 動態型別建立與內建型別名稱
* copy: copy --- 淺層 shallow 和深層 deep 複製操作. 淺層 (shallow) 和深層 (deep) 複製操作
* pprint: pprint --- 資料美化列印器. 資料美化列印器
* reprlib: reprlib --- repr 的替代實作. repr() 的替代實作
* enum: enum --- 對列舉的支援. 對列舉的支援
* graphlib —-- 使用類圖 (graph-like) 結構進行操作的功能: graphlib —-- 使用類圖 graph-like 結構進行操作的功能. 

@end menu

@node datetime --- 日期與時間的基本型別,zoneinfo --- IANA 時區支援,,資料型別
@anchor{library/datetime doc}@anchor{2742}@anchor{library/datetime datetime-basic-date-and-time-types}@anchor{2743}@anchor{library/datetime module-datetime}@anchor{34}
@subsection @code{datetime} --- 日期與時間的基本型別


@geindex module; datetime

`原始碼：'Lib/datetime.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/datetime.py}


__________________________________________________________________


@c XXX what order should the types be discussed in?

@code{datetime} 模組提供操作日期與時間的類別。

While date and time arithmetic is supported, the focus of the implementation is
on efficient attribute extraction for output formatting and manipulation.

@cartouche
@quotation 小訣竅 
跳轉至@ref{2744,,格式碼 (format codes)}。
@end quotation
@end cartouche


@subsubheading 也參考



@table @asis

@item @ref{15,,calendar} 模組

與日曆相關的一般函式。

@item @ref{f4,,time} 模組

Time access and conversions.

@item @ref{13a,,zoneinfo} 模組

Concrete time zones representing the IANA time zone database.

@item Package dateutil@footnote{https://dateutil.readthedocs.io/en/stable/}

帶有時區與剖析擴充支援的第三方函式庫。

@item DateType@footnote{https://pypi.org/project/DateType/} 套件

Third-party library that introduces distinct static types to e.g. allow
@ref{56e,,static type checkers}
to differentiate between naive and aware datetimes.
@end table


@menu
* Aware and Naive Objects:: 
* 常數:: 
* Available Types:: 
* timedelta 物件:: 
* date 物件:: 
* datetime 物件:: 
* time 物件:: 
* tzinfo 物件:: 
* timezone 物件:: 
* strftime() 與 strptime() 的行為: strftime 與 strptime 的行為. 

@end menu

@node Aware and Naive Objects,常數,,datetime --- 日期與時間的基本型別
@anchor{library/datetime aware-and-naive-objects}@anchor{2745}@anchor{library/datetime datetime-naive-aware}@anchor{2746}
@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{
也就是說，我們會忽略相對論的效應
}

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{4dd,,datetime} and @ref{1fb,,time}
objects have an optional time zone information attribute, @code{tzinfo}, that
can be set to an instance of a subclass of the abstract @ref{7ef,,tzinfo} class.
These @ref{7ef,,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{7ef,,tzinfo} class, the @ref{12c0,,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 常數,Available Types,Aware and Naive Objects,datetime --- 日期與時間的基本型別
@anchor{library/datetime constants}@anchor{2747}
@subsubsection 常數


@code{datetime} 模組匯出以下常數：

@geindex MINYEAR (於 datetime 模組中)
@anchor{library/datetime datetime MINYEAR}@anchor{2748}
@deffn {資料} datetime.MINYEAR

The smallest year number allowed in a @ref{1fa,,date} or @ref{4dd,,datetime} object.
@ref{2748,,MINYEAR} is 1.
@end deffn

@geindex MAXYEAR (於 datetime 模組中)
@anchor{library/datetime datetime MAXYEAR}@anchor{2749}
@deffn {資料} datetime.MAXYEAR

The largest year number allowed in a @ref{1fa,,date} or @ref{4dd,,datetime} object.
@ref{2749,,MAXYEAR} is 9999.
@end deffn

@geindex UTC (於 datetime 模組中)
@anchor{library/datetime datetime UTC}@anchor{70c}
@deffn {資料} datetime.UTC

Alias for the UTC time zone singleton @ref{820,,datetime.timezone.utc}.


在 3.11 版被加入.

@end deffn

@node Available Types,timedelta 物件,常數,datetime --- 日期與時間的基本型別
@anchor{library/datetime available-types}@anchor{274a}
@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{274b,,year}, @ref{274c,,month}, and
@ref{274d,,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{274e,,hour}, @ref{274f,,minute}, @ref{2750,,second}, @ref{2751,,microsecond},
and @ref{2752,,tzinfo}.
@end deffn


@deffn {類別} datetime.datetime

A combination of a date and a time. Attributes: @ref{2753,,year}, @ref{2754,,month},
@ref{2755,,day}, @ref{2756,,hour}, @ref{2757,,minute}, @ref{2758,,second}, @ref{2759,,microsecond},
and @ref{275a,,tzinfo}.
@end deffn


@deffn {類別} datetime.timedelta

表示兩個 @ref{4dd,,datetime} 或 @ref{1fa,,date} 實例之間時間的差異，以微秒為解析度。
@end deffn


@deffn {類別} datetime.tzinfo

An abstract base class for time zone information objects. These are used by the
@ref{4dd,,datetime} and @ref{1fb,,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{7ef,,tzinfo} abstract base class as a
fixed offset from the UTC.


在 3.2 版被加入.

@end deffn

Objects of these types are immutable.

Subclass relationships:

@example
object
    timedelta
    tzinfo
        timezone
    time
    date
        datetime
@end example

@menu
* 常見屬性:: 
* Determining if an Object is Aware or Naive:: 

@end menu

@node 常見屬性,Determining if an Object is Aware or Naive,,Available Types
@anchor{library/datetime common-properties}@anchor{275b}
@subsubsection 常見屬性


The @ref{1fa,,date}, @ref{4dd,,datetime}, @ref{1fb,,time}, and @ref{12c0,,timezone} types
share these common features:


@itemize -

@item 
Objects of these types are immutable.

@item 
Objects of these types are @ref{81d,,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,,常見屬性,Available Types
@anchor{library/datetime determining-if-an-object-is-aware-or-naive}@anchor{275c}
@subsubsection Determining if an Object is Aware or Naive


Objects of the @ref{1fa,,date} type are always naive.

An object of type @ref{1fb,,time} or @ref{4dd,,datetime} may be aware or naive.

A @ref{4dd,,datetime} object @code{d} is aware if both of the following hold:


@enumerate 

@item 
@code{d.tzinfo} 不是 @code{None}

@item 
@code{d.tzinfo.utcoffset(d)} 不會回傳 @code{None}
@end enumerate

否則 @code{d} 會是 naive 的。

A @ref{1fb,,time} object @code{t} is aware if both of the following hold:


@enumerate 

@item 
@code{t.tzinfo} 不是 @code{None}

@item 
@code{t.tzinfo.utcoffset(None)} 沒有回傳 @code{None}。
@end enumerate

否則 @code{t} 會是 naive 的。

The distinction between aware and naive doesn't apply to @ref{bba,,timedelta}
objects.

@node timedelta 物件,date 物件,Available Types,datetime --- 日期與時間的基本型別
@anchor{library/datetime datetime-timedelta}@anchor{275d}@anchor{library/datetime timedelta-objects}@anchor{275e}
@subsubsection @code{timedelta} 物件


一個 @ref{bba,,timedelta} 物件代表著一段持續時間，即兩個 @ref{4dd,,datetime} 或 @ref{1fa,,date} 之間的差異。

@geindex timedelta (datetime 中的類別)
@anchor{library/datetime datetime timedelta}@anchor{bba}
@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 
一毫秒會被轉換為 1000 微秒。

@item 
一分鐘會被轉換為 60 秒。

@item 
一小時會被轉換為 3600 秒。

@item 
一週會被轉換為 7 天。
@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
>>> from datetime import timedelta
>>> delta = timedelta(
...     days=50,
...     seconds=27,
...     microseconds=10,
...     milliseconds=29000,
...     minutes=5,
...     hours=8,
...     weeks=2
... )
>>> # Only days, seconds, and microseconds remain
>>> delta
datetime.timedelta(days=64, seconds=29156, microseconds=10)
@end example

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{a78,,OverflowError} is raised.

Note that normalization of negative values may be surprising at first. For
example:

@example
>>> from datetime import timedelta
>>> d = 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

類別屬性：

@geindex min (datetime.timedelta 的屬性)
@anchor{library/datetime datetime timedelta min}@anchor{275f}
@deffn {屬性} timedelta.min

The most negative @ref{bba,,timedelta} object, @code{timedelta(-999999999)}.
@end deffn

@geindex max (datetime.timedelta 的屬性)
@anchor{library/datetime datetime timedelta max}@anchor{2760}
@deffn {屬性} timedelta.max

The most positive @ref{bba,,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{2761}
@deffn {屬性} timedelta.resolution

The smallest possible difference between non-equal @ref{bba,,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{bba,,timedelta} object.

Instance attributes (read-only):

@geindex days (datetime.timedelta 的屬性)
@anchor{library/datetime datetime timedelta days}@anchor{2762}
@deffn {屬性} timedelta.days

在 -999,999,999 到 999,999,999 （含）之間
@end deffn

@geindex seconds (datetime.timedelta 的屬性)
@anchor{library/datetime datetime timedelta seconds}@anchor{2763}
@deffn {屬性} timedelta.seconds

在 0 到 86,399 （含）之間

@cartouche
@quotation 警示 
It is a somewhat common bug for code to unintentionally use this attribute
when it is actually intended to get a @ref{1506,,total_seconds()}
value instead:

@example
>>> from datetime import timedelta
>>> duration = timedelta(seconds=11235813)
>>> duration.days, duration.seconds
(130, 3813)
>>> duration.total_seconds()
11235813.0
@end example
@end quotation
@end cartouche
@end deffn

@geindex microseconds (datetime.timedelta 的屬性)
@anchor{library/datetime datetime timedelta microseconds}@anchor{2764}
@deffn {屬性} timedelta.microseconds

在 0 到 999,999 （含）之間
@end deffn

Supported operations:

@c XXX this table is too wide!


@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{196,,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{bba,,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{bba,,timedelta} object.

@item

@code{+t1}

@tab

Returns a @ref{bba,,timedelta} object with the
same value. (2)

@item

@code{-t1}

@tab

等價於 @code{timedelta(-t1.days, -t1.seconds, -t1.microseconds)}，也等價於 @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{bba,,timedelta} object as a constructor
call with canonical attribute values.

@end multitable


註解：


@enumerate 

@item 
這是精確的，但可能會溢位。

@item 
這是精確的，且不會溢位。

@item 
Division by zero raises @ref{b36,,ZeroDivisionError}.

@item 
@code{-timedelta.max} is not representable as a @ref{bba,,timedelta} object.

@item 
String representations of @ref{bba,,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{bba,,timedelta} objects support
certain additions and subtractions with @ref{1fa,,date} and @ref{4dd,,datetime}
objects (see below).


在 3.2 版的變更: Floor division and true division of a @ref{bba,,timedelta} object by another
@ref{bba,,timedelta} object are now supported, as are remainder operations and
the @ref{b90,,divmod()} function. True division and multiplication of a
@ref{bba,,timedelta} object by a @ref{196,,float} object are now supported.


@ref{bba,,timedelta} objects support equality and order comparisons.

In Boolean contexts, a @ref{bba,,timedelta} object is
considered to be true if and only if it isn't equal to @code{timedelta(0)}.

實例方法：

@geindex total_seconds() (datetime.timedelta 的方法)
@anchor{library/datetime datetime timedelta total_seconds}@anchor{1506}
@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 (e.g. @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.


在 3.2 版被加入.

@end deffn

@menu
* 用法範例：timedelta:: 

@end menu

@node 用法範例：timedelta,,,timedelta 物件
@anchor{library/datetime examples-of-usage-timedelta}@anchor{2765}
@subsubsection 用法範例：@code{timedelta}


An additional example of normalization:

@example
>>> # Components of another_year add up to exactly 365 days
>>> from datetime import timedelta
>>> year = timedelta(days=365)
>>> another_year = timedelta(weeks=40, days=84, hours=23,
...                          minutes=50, seconds=600)
>>> year == another_year
True
>>> year.total_seconds()
31536000.0
@end example

Examples of @ref{bba,,timedelta} arithmetic:

@example
>>> from datetime import timedelta
>>> year = timedelta(days=365)
>>> ten_years = 10 * year
>>> ten_years
datetime.timedelta(days=3650)
>>> ten_years.days // 365
10
>>> nine_years = ten_years - year
>>> nine_years
datetime.timedelta(days=3285)
>>> three_years = nine_years // 3
>>> three_years, three_years.days // 365
(datetime.timedelta(days=1095), 3)
@end example

@node date 物件,datetime 物件,timedelta 物件,datetime --- 日期與時間的基本型別
@anchor{library/datetime date-objects}@anchor{2766}@anchor{library/datetime datetime-date}@anchor{2767}
@subsubsection @code{date} 物件


A @ref{1fa,,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{1fa}
@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{2eb,,ValueError} is raised.
@end deffn

Other constructors, all class methods:

@geindex today() (datetime.date 的類別方法)
@anchor{library/datetime datetime date today}@anchor{16be}
@deffn {方法} classmethod date.today ()

回傳目前的本地日期。

這等同於 @code{date.fromtimestamp(time.time())}。
@end deffn

@geindex fromtimestamp() (datetime.date 的類別方法)
@anchor{library/datetime datetime date fromtimestamp}@anchor{dc8}
@deffn {方法} classmethod date.fromtimestamp (timestamp)

Return the local date corresponding to the POSIX timestamp, such as is
returned by @ref{557,,time.time()}.

This may raise @ref{a78,,OverflowError}, if the timestamp is out
of the range of values supported by the platform C @code{localtime()}
function, and @ref{2c0,,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 @ref{dc8,,fromtimestamp()}.


在 3.3 版的變更: Raise @ref{a78,,OverflowError} instead of @ref{2eb,,ValueError} if the timestamp
is out of the range of values supported by the platform C
@code{localtime()} function. Raise @ref{2c0,,OSError} instead of
@ref{2eb,,ValueError} on @code{localtime()} failure.

@end deffn

@geindex fromordinal() (datetime.date 的類別方法)
@anchor{library/datetime datetime date fromordinal}@anchor{dc7}
@deffn {方法} classmethod date.fromordinal (ordinal)

Return the date corresponding to the proleptic Gregorian ordinal, where
January 1 of year 1 has ordinal 1.

@ref{2eb,,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{821}
@deffn {方法} classmethod date.fromisoformat (date_string)

Return a @ref{1fa,,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

範例：

@example
>>> from datetime import date
>>> date.fromisoformat('2019-12-04')
datetime.date(2019, 12, 4)
>>> date.fromisoformat('20191204')
datetime.date(2019, 12, 4)
>>> date.fromisoformat('2021-W01-1')
datetime.date(2021, 1, 4)
@end example


在 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{bd6}
@deffn {方法} classmethod date.fromisocalendar (year, week, day)

Return a @ref{1fa,,date} corresponding to the ISO calendar date specified by
year, week and day. This is the inverse of the function @ref{ae8,,date.isocalendar()}.


在 3.8 版被加入.

@end deffn

@geindex strptime() (datetime.date 的類別方法)
@anchor{library/datetime datetime date strptime}@anchor{1f9}
@deffn {方法} classmethod date.strptime (date_string, format)

Return a @ref{1fa,,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{2eb,,ValueError} is raised if the date_string and format
can't be parsed by @ref{1624,,time.strptime()} or if it returns a value which isn't a
time tuple.  See also @ref{1a83,,strftime() 與 strptime() 的行為} and
@ref{821,,date.fromisoformat()}.

@cartouche
@quotation 備註 
If `format' specifies a day of month without a year a
@ref{1a3,,DeprecationWarning} is emitted.  This is to avoid a quadrennial
leap year bug in code seeking to parse only a month and day as the
default year used in absence of one in the format is not a leap year.
Such `format' values may raise an error as of Python 3.15.  The
workaround is to always include a year in your `format'.  If parsing
`date_string' values that do not have a year, explicitly add a year that
is a leap year before parsing:

@example
>>> from datetime import date
>>> date_string = "02/29"
>>> when = date.strptime(f"@{date_string@};1984", "%m/%d;%Y")  # 避免閏年錯誤。
>>> when.strftime("%B %d")
'February 29'
@end example
@end quotation
@end cartouche


在 3.14 版被加入.

@end deffn

類別屬性：

@geindex min (datetime.date 的屬性)
@anchor{library/datetime datetime date min}@anchor{2768}
@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{2769}
@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{276a}
@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{274b}
@deffn {屬性} date.year

Between @ref{2748,,MINYEAR} and @ref{2749,,MAXYEAR} inclusive.
@end deffn

@geindex month (datetime.date 的屬性)
@anchor{library/datetime datetime date month}@anchor{274c}
@deffn {屬性} date.month

在 1 到 12 （含）之間。
@end deffn

@geindex day (datetime.date 的屬性)
@anchor{library/datetime datetime date day}@anchor{274d}
@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


註解：


@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{a78,,OverflowError} is raised if @code{date2.year} would be smaller than
@ref{2748,,MINYEAR} or larger than @ref{2749,,MAXYEAR}.

@item 
@code{timedelta.seconds} 和 @code{timedelta.microseconds} 被忽略。

@item 
This is exact, and cannot overflow. @code{timedelta.seconds} and
@code{timedelta.microseconds} are 0, and @code{date2 + timedelta == date1} after.

@item 
@ref{1fa,,date} objects are equal if they represent the same date.

@code{date} objects that are not also @ref{4dd,,datetime} instances
are never equal to @code{datetime} objects, even if they represent
the same date.

@item 
`date1' is considered less than `date2' when `date1' precedes `date2' in time.
In other words, @code{date1 < date2} if and only if @code{date1.toordinal() <
date2.toordinal()}.

Order comparison between a @code{date} object that is not also a
@ref{4dd,,datetime} instance and a @code{datetime} object raises
@ref{198,,TypeError}.
@end enumerate


在 3.13 版的變更: Comparison between @ref{4dd,,datetime} object and an instance of
the @ref{1fa,,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{1fa,,date} objects are considered to be true.

實例方法：

@geindex replace() (datetime.date 的方法)
@anchor{library/datetime datetime date replace}@anchor{1948}
@deffn {方法} date.replace (year=self.year, month=self.month, day=self.day)

Return a new @ref{1fa,,date} object with the same values, but with specified
parameters updated.

範例：

@example
>>> from datetime import date
>>> d = date(2002, 12, 31)
>>> d.replace(day=26)
datetime.date(2002, 12, 26)
@end example

The generic function @ref{1c0,,copy.replace()} also supports @ref{1fa,,date}
objects.
@end deffn

@geindex timetuple() (datetime.date 的方法)
@anchor{library/datetime datetime date timetuple}@anchor{276b}
@deffn {方法} date.timetuple ()

回傳一個 @ref{ee1,,time.struct_time}，如同 @ref{16ed,,time.localtime()} 所回傳。

The hours, minutes and seconds are 0, and the DST flag is -1.

@code{d.timetuple()} 等價於：

@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{276c}
@deffn {方法} date.toordinal ()

Return the proleptic Gregorian ordinal of the date, where January 1 of year 1
has ordinal 1. For any @ref{1fa,,date} object @code{d},
@code{date.fromordinal(d.toordinal()) == d}.
@end deffn

@geindex weekday() (datetime.date 的方法)
@anchor{library/datetime datetime date weekday}@anchor{276d}
@deffn {方法} date.weekday ()

回傳一個代表星期幾的整數，星期一為 0、星期日為 6。例如 @code{date(2002, 12, 4).weekday() == 2} 為星期三。也請參考 @ref{276e,,isoweekday()}。
@end deffn

@geindex isoweekday() (datetime.date 的方法)
@anchor{library/datetime datetime date isoweekday}@anchor{276e}
@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{276d,,weekday()}, @ref{ae8,,isocalendar()}.
@end deffn

@geindex isocalendar() (datetime.date 的方法)
@anchor{library/datetime datetime date isocalendar}@anchor{ae8}
@deffn {方法} date.isocalendar ()

Return a @ref{857,,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
>>> from datetime import date
>>> date(2003, 12, 29).isocalendar()
datetime.IsoCalendarDate(year=2004, week=1, weekday=1)
>>> date(2004, 1, 4).isocalendar()
datetime.IsoCalendarDate(year=2004, week=1, weekday=7)
@end example


在 3.9 版的變更: Result changed from a tuple to a @ref{857,,named tuple}.

@end deffn

@geindex isoformat() (datetime.date 的方法)
@anchor{library/datetime datetime date isoformat}@anchor{276f}
@deffn {方法} date.isoformat ()

回傳一以 ISO 8601 格式 @code{YYYY-MM-DD} 表示的日期字串：

@example
>>> from datetime import date
>>> date(2002, 12, 4).isoformat()
'2002-12-04'
@end example
@end deffn

@geindex __str__() (datetime.date 的方法)
@anchor{library/datetime datetime date __str__}@anchor{2770}
@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{2771}
@deffn {方法} date.ctime ()

Return a string representing the date:

@example
>>> from datetime import date
>>> date(2002, 12, 4).ctime()
'Wed Dec  4 00:00:00 2002'
@end example

@code{d.ctime()} 等價於：

@example
time.ctime(time.mktime(d.timetuple()))
@end example

on platforms where the native C
@code{ctime()} function (which @ref{2772,,time.ctime()} invokes, but which
@ref{2771,,date.ctime()} does not invoke) conforms to the C standard.
@end deffn

@geindex strftime() (datetime.date 的方法)
@anchor{library/datetime datetime date strftime}@anchor{e8a}
@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{1a83,,strftime() 與 strptime() 的行為} and @ref{276f,,date.isoformat()}.
@end deffn

@geindex __format__() (datetime.date 的方法)
@anchor{library/datetime datetime date __format__}@anchor{2773}
@deffn {方法} date.__format__ (format)

Same as @ref{e8a,,date.strftime()}. This makes it possible to specify a format
string for a @ref{1fa,,date} object in @ref{19a,,formatted string literals} and when using @ref{82c,,str.format()}.
See also @ref{1a83,,strftime() 與 strptime() 的行為} and @ref{276f,,date.isoformat()}.
@end deffn

@menu
* 用法範例：date:: 

@end menu

@node 用法範例：date,,,date 物件
@anchor{library/datetime examples-of-usage-date}@anchor{2774}
@subsubsection 用法範例：@code{date}


計算一個事件的天數的範例：

@example
>>> import time
>>> from datetime import date
>>> today = date.today()
>>> today
datetime.date(2007, 12, 5)
>>> today == date.fromtimestamp(time.time())
True
>>> my_birthday = date(today.year, 6, 24)
>>> if my_birthday < today:
...     my_birthday = my_birthday.replace(year=today.year + 1)
...
>>> my_birthday
datetime.date(2008, 6, 24)
>>> time_to_birthday = abs(my_birthday - today)
>>> time_to_birthday.days
202
@end example

更多 @ref{1fa,,date} 的用法範例：

@example
>>> from datetime import date
>>> d = date.fromordinal(730920) # 730920th day after 1. 1. 0001
>>> d
datetime.date(2002, 3, 11)

>>> # Methods related to formatting string output
>>> d.isoformat()
'2002-03-11'
>>> d.strftime("%d/%m/%y")
'11/03/02'
>>> d.strftime("%A %d. %B %Y")
'Monday 11. March 2002'
>>> d.ctime()
'Mon Mar 11 00:00:00 2002'
>>> 'The @{1@} is @{0:%d@}, the @{2@} is @{0:%B@}.'.format(d, "day", "month")
'The day is 11, the month is March.'

>>> # Methods for to extracting 'components' under different calendars
>>> t = d.timetuple()
>>> for i in t:
...     print(i)
2002                # year
3                   # month
11                  # day
0
0
0
0                   # weekday (0 = Monday)
70                  # 70th day in the year
-1
>>> ic = d.isocalendar()
>>> for i in ic:
...     print(i)
2002                # ISO year
11                  # ISO week number
1                   # ISO day number ( 1 = Monday )

>>> # A date object is immutable; all operations produce a new object
>>> d.replace(year=2005)
datetime.date(2005, 3, 11)
@end example

@node datetime 物件,time 物件,date 物件,datetime --- 日期與時間的基本型別
@anchor{library/datetime datetime-datetime}@anchor{2775}@anchor{library/datetime datetime-objects}@anchor{2776}
@subsubsection @code{datetime} 物件


A @ref{4dd,,datetime} object is a single object containing all the information
from a @ref{1fa,,date} object and a @ref{1fb,,time} object.

Like a @ref{1fa,,date} object, @ref{4dd,,datetime} assumes the current Gregorian
calendar extended in both directions; like a @ref{1fb,,time} object,
@ref{4dd,,datetime} assumes there are exactly 3600*24 seconds in every day.

建構函式：

@geindex datetime (datetime 中的類別)
@anchor{library/datetime datetime datetime}@anchor{4dd}
@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{7ef,,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{2eb,,ValueError} is raised.


在 3.6 版的變更: 新增 `fold' 參數。

@end deffn

Other constructors, all class methods:

@geindex today() (datetime.datetime 的類別方法)
@anchor{library/datetime datetime datetime today}@anchor{2777}
@deffn {方法} classmethod datetime.today ()

回傳目前的本地日期與時間，且 @ref{275a,,tzinfo} 為 @code{None}。

等價於：

@example
datetime.fromtimestamp(time.time())
@end example

也請見 @ref{70a,,now()}、@ref{70b,,fromtimestamp()}。

This method is functionally equivalent to @ref{70a,,now()}, but without a
@code{tz} parameter.
@end deffn

@geindex now() (datetime.datetime 的類別方法)
@anchor{library/datetime datetime datetime now}@anchor{70a}
@deffn {方法} classmethod datetime.now (tz=None)

Return the current local date and time.

如果選用的引數 `tz' 為 @code{None} 或未指定，則會像是 @ref{2777,,today()}，但盡可能提供比透過 @ref{557,,time.time()} 取得的時間戳記更多位數的資訊（例如，這在有提供 C @code{gettimeofday()} 函式的平台上可能可行）。

If `tz' is not @code{None}, it must be an instance of a @ref{7ef,,tzinfo} subclass,
and the current date and time are converted to `tz'’s time zone.

This function is preferred over @ref{2777,,today()} and @ref{34f,,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{34f}
@deffn {方法} classmethod datetime.utcnow ()

Return the current UTC date and time, with @ref{275a,,tzinfo} @code{None}.

This is like @ref{70a,,now()}, but returns the current UTC date and time, as a naive
@ref{4dd,,datetime} object. An aware current UTC datetime can be obtained by
calling @code{datetime.now(timezone.utc)}. See also @ref{70a,,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{70a,,datetime.now()} with @ref{70c,,UTC} instead.

@end deffn

@geindex fromtimestamp() (datetime.datetime 的類別方法)
@anchor{library/datetime datetime datetime fromtimestamp}@anchor{70b}
@deffn {方法} classmethod datetime.fromtimestamp (timestamp, tz=None)

Return the local date and time corresponding to the POSIX timestamp, such as is
returned by @ref{557,,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{4dd,,datetime} object is naive.

If `tz' is not @code{None}, it must be an instance of a @ref{7ef,,tzinfo} subclass, and the
timestamp is converted to `tz'’s time zone.

@ref{70b,,fromtimestamp()} may raise @ref{a78,,OverflowError}, if the timestamp is out of
the range of values supported by the platform C @code{localtime()} or
@code{gmtime()} functions, and @ref{2c0,,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 @ref{70b,,fromtimestamp()},
and then it's possible to have two timestamps differing by a second that yield
identical @ref{4dd,,datetime} objects. This method is preferred over
@ref{350,,utcfromtimestamp()}.


在 3.3 版的變更: Raise @ref{a78,,OverflowError} instead of @ref{2eb,,ValueError} if the timestamp
is out of the range of values supported by the platform C
@code{localtime()} or @code{gmtime()} functions. Raise @ref{2c0,,OSError}
instead of @ref{2eb,,ValueError} on @code{localtime()} or @code{gmtime()}
failure.



在 3.6 版的變更: @ref{70b,,fromtimestamp()} may return instances with @ref{e4c,,fold} set to 1.

@end deffn

@geindex utcfromtimestamp() (datetime.datetime 的類別方法)
@anchor{library/datetime datetime datetime utcfromtimestamp}@anchor{350}
@deffn {方法} classmethod datetime.utcfromtimestamp (timestamp)

Return the UTC @ref{4dd,,datetime} corresponding to the POSIX timestamp, with
@ref{275a,,tzinfo} @code{None}.  (The resulting object is naive.)

This may raise @ref{a78,,OverflowError}, if the timestamp is
out of the range of values supported by the platform C @code{gmtime()} function,
and @ref{2c0,,OSError} on @code{gmtime()} failure.
It's common for this to be restricted to years in 1970 through 2038.

To get an aware @ref{4dd,,datetime} object, call @ref{70b,,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{2748,,MINYEAR} and @ref{2749,,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{a78,,OverflowError} instead of @ref{2eb,,ValueError} if the timestamp
is out of the range of values supported by the platform C
@code{gmtime()} function. Raise @ref{2c0,,OSError} instead of
@ref{2eb,,ValueError} on @code{gmtime()} failure.



在 3.12 版之後被棄用: Use @ref{70b,,datetime.fromtimestamp()} with @ref{70c,,UTC} instead.

@end deffn

@geindex fromordinal() (datetime.datetime 的類別方法)
@anchor{library/datetime datetime datetime fromordinal}@anchor{2778}
@deffn {方法} classmethod datetime.fromordinal (ordinal)

Return the @ref{4dd,,datetime} corresponding to the proleptic Gregorian ordinal,
where January 1 of year 1 has ordinal 1. @ref{2eb,,ValueError} is raised unless
@code{1 <= ordinal <= datetime.max.toordinal()}. The hour, minute, second and
microsecond of the result are all 0, and @ref{275a,,tzinfo} is @code{None}.
@end deffn

@geindex combine() (datetime.datetime 的類別方法)
@anchor{library/datetime datetime datetime combine}@anchor{e8b}
@deffn {方法} classmethod datetime.combine (date, time, tzinfo=time.tzinfo)

Return a new @ref{4dd,,datetime} object whose date components are equal to the
given @ref{1fa,,date} object's, and whose time components
are equal to the given @ref{1fb,,time} object's. If the `tzinfo'
argument is provided, its value is used to set the @ref{275a,,tzinfo} attribute
of the result, otherwise the @ref{2752,,tzinfo} attribute of the `time' argument
is used.  If the `date' argument is a @ref{4dd,,datetime} object, its time components
and @ref{275a,,tzinfo} attributes are ignored.

For any @ref{4dd,,datetime} object @code{d},
@code{d == datetime.combine(d.date(), d.time(), d.tzinfo)}.


在 3.6 版的變更: 新增 `tzinfo' 引數。

@end deffn

@geindex fromisoformat() (datetime.datetime 的類別方法)
@anchor{library/datetime datetime datetime fromisoformat}@anchor{823}
@deffn {方法} classmethod datetime.fromisoformat (date_string)

Return a @ref{4dd,,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

範例：

@example
>>> from datetime import datetime
>>> datetime.fromisoformat('2011-11-04')
datetime.datetime(2011, 11, 4, 0, 0)
>>> datetime.fromisoformat('20111104')
datetime.datetime(2011, 11, 4, 0, 0)
>>> datetime.fromisoformat('2011-11-04T00:05:23')
datetime.datetime(2011, 11, 4, 0, 5, 23)
>>> datetime.fromisoformat('2011-11-04T00:05:23Z')
datetime.datetime(2011, 11, 4, 0, 5, 23, tzinfo=datetime.timezone.utc)
>>> datetime.fromisoformat('20111104T000523')
datetime.datetime(2011, 11, 4, 0, 5, 23)
>>> datetime.fromisoformat('2011-W01-2T00:05:23.283')
datetime.datetime(2011, 1, 4, 0, 5, 23, 283000)
>>> datetime.fromisoformat('2011-11-04 00:05:23.283')
datetime.datetime(2011, 11, 4, 0, 5, 23, 283000)
>>> datetime.fromisoformat('2011-11-04 00:05:23.283+00:00')
datetime.datetime(2011, 11, 4, 0, 5, 23, 283000, tzinfo=datetime.timezone.utc)
>>> datetime.fromisoformat('2011-11-04T00:05:23+04:00')
datetime.datetime(2011, 11, 4, 0, 5, 23,
    tzinfo=datetime.timezone(datetime.timedelta(seconds=14400)))
@end example


在 3.7 版被加入.



在 3.11 版的變更: Previously, this method only supported formats that could be emitted by
@ref{276f,,date.isoformat()} or @ref{d1d,,datetime.isoformat()}.

@end deffn

@geindex fromisocalendar() (datetime.datetime 的類別方法)
@anchor{library/datetime datetime datetime fromisocalendar}@anchor{bd7}
@deffn {方法} classmethod datetime.fromisocalendar (year, week, day)

Return a @ref{4dd,,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{ae9,,datetime.isocalendar()}.


在 3.8 版被加入.

@end deffn

@geindex strptime() (datetime.datetime 的類別方法)
@anchor{library/datetime datetime datetime strptime}@anchor{18b7}
@deffn {方法} classmethod datetime.strptime (date_string, format)

Return a @ref{4dd,,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{2eb,,ValueError} is raised if the date_string and format
can't be parsed by @ref{1624,,time.strptime()} or if it returns a value which isn't a
time tuple.  See also @ref{1a83,,strftime() 與 strptime() 的行為} and
@ref{823,,datetime.fromisoformat()}.


在 3.13 版的變更: If `format' specifies a day of month without a year a
@ref{1a3,,DeprecationWarning} is now emitted.  This is to avoid a quadrennial
leap year bug in code seeking to parse only a month and day as the
default year used in absence of one in the format is not a leap year.
Such `format' values may raise an error as of Python 3.15.  The
workaround is to always include a year in your `format'.  If parsing
`date_string' values that do not have a year, explicitly add a year that
is a leap year before parsing:

@example
>>> from datetime import datetime
>>> date_string = "02/29"
>>> when = datetime.strptime(f"@{date_string@};1984", "%m/%d;%Y")  # 避免閏年錯誤。
>>> when.strftime("%B %d")
'February 29'
@end example

@end deffn

類別屬性：

@geindex min (datetime.datetime 的屬性)
@anchor{library/datetime datetime datetime min}@anchor{1a94}
@deffn {屬性} datetime.min

The earliest representable @ref{4dd,,datetime}, @code{datetime(MINYEAR, 1, 1,
tzinfo=None)}.
@end deffn

@geindex max (datetime.datetime 的屬性)
@anchor{library/datetime datetime datetime max}@anchor{2779}
@deffn {屬性} datetime.max

The latest representable @ref{4dd,,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{277a}
@deffn {屬性} datetime.resolution

The smallest possible difference between non-equal @ref{4dd,,datetime} objects,
@code{timedelta(microseconds=1)}.
@end deffn

Instance attributes (read-only):

@geindex year (datetime.datetime 的屬性)
@anchor{library/datetime datetime datetime year}@anchor{2753}
@deffn {屬性} datetime.year

Between @ref{2748,,MINYEAR} and @ref{2749,,MAXYEAR} inclusive.
@end deffn

@geindex month (datetime.datetime 的屬性)
@anchor{library/datetime datetime datetime month}@anchor{2754}
@deffn {屬性} datetime.month

在 1 到 12 （含）之間。
@end deffn

@geindex day (datetime.datetime 的屬性)
@anchor{library/datetime datetime datetime day}@anchor{2755}
@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{2756}
@deffn {屬性} datetime.hour

In @code{range(24)}.
@end deffn

@geindex minute (datetime.datetime 的屬性)
@anchor{library/datetime datetime datetime minute}@anchor{2757}
@deffn {屬性} datetime.minute

In @code{range(60)}.
@end deffn

@geindex second (datetime.datetime 的屬性)
@anchor{library/datetime datetime datetime second}@anchor{2758}
@deffn {屬性} datetime.second

In @code{range(60)}.
@end deffn

@geindex microsecond (datetime.datetime 的屬性)
@anchor{library/datetime datetime datetime microsecond}@anchor{2759}
@deffn {屬性} datetime.microsecond

In @code{range(1000000)}.
@end deffn

@geindex tzinfo (datetime.datetime 的屬性)
@anchor{library/datetime datetime datetime tzinfo}@anchor{275a}
@deffn {屬性} datetime.tzinfo

The object passed as the `tzinfo' argument to the @ref{4dd,,datetime} constructor,
or @code{None} if none was passed.
@end deffn

@geindex fold (datetime.datetime 的屬性)
@anchor{library/datetime datetime datetime fold}@anchor{e4c}
@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.


在 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{275a,,tzinfo} attribute as the input datetime, and
@code{datetime2 - datetime1 == timedelta} after. @ref{a78,,OverflowError} is raised if
@code{datetime2.year} would be smaller than @ref{2748,,MINYEAR} or larger than
@ref{2749,,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{275a,,tzinfo} attribute as the input
datetime, and no time zone adjustments are done even if the input is aware.

@item 
Subtraction of a @ref{4dd,,datetime} from a @ref{4dd,,datetime} is defined only if
both operands are naive, or if both are aware. If one is aware and the other is
naive, @ref{198,,TypeError} is raised.

If both are naive, or both are aware and have the same @ref{275a,,tzinfo} attribute,
the @ref{275a,,tzinfo} attributes are ignored, and the result is a @ref{bba,,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{275a,,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{4dd,,datetime} objects are equal if they represent the same date
and time, taking into account the time zone.

Naive and aware @code{datetime} objects are never equal.

If both comparands are aware, and have the same @code{tzinfo} attribute,
the @code{tzinfo} and @ref{e4c,,fold} attributes are ignored and
the base datetimes are compared.
If both comparands are aware and have different @ref{275a,,tzinfo}
attributes, the comparison acts as comparands were first converted to UTC
datetimes except that the implementation never overflows.
@code{datetime} instances in a repeated interval are never equal to
@code{datetime} instances in other time zone.

@item 
`datetime1' is considered less than `datetime2' when `datetime1' precedes
`datetime2' in time, taking into account the time zone.

Order comparison between naive and aware @ref{4dd,,datetime} objects
raises @ref{198,,TypeError}.

If both comparands are aware, and have the same @code{tzinfo} attribute,
the @code{tzinfo} and @ref{e4c,,fold} attributes are ignored and
the base datetimes are compared.
If both comparands are aware and have different @ref{275a,,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{4dd,,datetime}
instances don't raise @ref{198,,TypeError}.



在 3.13 版的變更: Comparison between @ref{4dd,,datetime} object and an instance of
the @ref{1fa,,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.


實例方法：

@geindex date() (datetime.datetime 的方法)
@anchor{library/datetime datetime datetime date}@anchor{277b}
@deffn {方法} datetime.date ()

Return @ref{1fa,,date} object with same year, month and day.
@end deffn

@geindex time() (datetime.datetime 的方法)
@anchor{library/datetime datetime datetime time}@anchor{277c}
@deffn {方法} datetime.time ()

Return @ref{1fb,,time} object with same hour, minute, second, microsecond and fold.
@ref{275a,,tzinfo} is @code{None}. See also method @ref{277d,,timetz()}.


在 3.6 版的變更: The fold value is copied to the returned @ref{1fb,,time} object.

@end deffn

@geindex timetz() (datetime.datetime 的方法)
@anchor{library/datetime datetime datetime timetz}@anchor{277d}
@deffn {方法} datetime.timetz ()

Return @ref{1fb,,time} object with same hour, minute, second, microsecond, fold, and
tzinfo attributes. See also method @ref{f4,,time()}.


在 3.6 版的變更: The fold value is copied to the returned @ref{1fb,,time} object.

@end deffn

@geindex replace() (datetime.datetime 的方法)
@anchor{library/datetime datetime datetime replace}@anchor{16bf}
@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{34,,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{4dd,,datetime} objects are also supported by generic function
@ref{1c0,,copy.replace()}.


在 3.6 版的變更: 新增 `fold' 參數。

@end deffn

@geindex astimezone() (datetime.datetime 的方法)
@anchor{library/datetime datetime datetime astimezone}@anchor{bbb}
@deffn {方法} datetime.astimezone (tz=None)

Return a @ref{4dd,,datetime} object with new @ref{275a,,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{7ef,,tzinfo} subclass, and its
@ref{277e,,utcoffset()} and @ref{277f,,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{12c0,,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{12c0,,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{2780,,tzinfo.fromutc()} method can be overridden in a
@ref{7ef,,tzinfo} subclass to affect the result returned by @ref{bbb,,astimezone()}.
Ignoring error cases, @ref{bbb,,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 @ref{bbb,,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{277e}
@deffn {方法} datetime.utcoffset ()

If @ref{275a,,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{bba,,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{277f}
@deffn {方法} datetime.dst ()

If @ref{275a,,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{bba,,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{2781}
@deffn {方法} datetime.tzname ()

If @ref{275a,,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{2782}
@deffn {方法} datetime.timetuple ()

回傳一個 @ref{ee1,,time.struct_time}，如同 @ref{16ed,,time.localtime()} 所回傳。

@code{d.timetuple()} 等價於：

@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{2783,,tm_isdst} flag of the result is set according to the
@ref{277f,,dst()} method: @ref{275a,,tzinfo} is @code{None} or @ref{277f,,dst()} returns
@code{None}, @code{tm_isdst} is set to @code{-1}; else if @ref{277f,,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{2784}
@deffn {方法} datetime.utctimetuple ()

If @ref{4dd,,datetime} instance @code{d} is naive, this is the same as
@code{d.timetuple()} except that @ref{2783,,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{ee1,,time.struct_time} for the
normalized time is returned. @code{tm_isdst} is forced to 0. Note
that an @ref{a78,,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 @ref{2784,,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{2782,,datetime.timetuple()}.
@end quotation
@end cartouche
@end deffn

@geindex toordinal() (datetime.datetime 的方法)
@anchor{library/datetime datetime datetime toordinal}@anchor{2785}
@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{129b}
@deffn {方法} datetime.timestamp ()

Return POSIX timestamp corresponding to the @ref{4dd,,datetime}
instance. The return value is a @ref{196,,float} similar to that
returned by @ref{557,,time.time()}.

Naive @ref{4dd,,datetime} instances are assumed to represent local
time and this method relies on the platform C @code{mktime()}
function to perform the conversion. Since @ref{4dd,,datetime}
supports wider range of values than @code{mktime()} on many
platforms, this method may raise @ref{a78,,OverflowError} or @ref{2c0,,OSError}
for times far in the past or far in the future.

For aware @ref{4dd,,datetime} instances, the return value is computed
as:

@example
(dt - datetime(1970, 1, 1, tzinfo=timezone.utc)).total_seconds()
@end example


在 3.3 版被加入.



在 3.6 版的變更: The @ref{129b,,timestamp()} method uses the @ref{e4c,,fold} attribute to
disambiguate the times during a repeated interval.


@cartouche
@quotation 備註 
There is no method to obtain the POSIX timestamp directly from a
naive @ref{4dd,,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
@end deffn

@geindex weekday() (datetime.datetime 的方法)
@anchor{library/datetime datetime datetime weekday}@anchor{2786}
@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{2787,,isoweekday()}.
@end deffn

@geindex isoweekday() (datetime.datetime 的方法)
@anchor{library/datetime datetime datetime isoweekday}@anchor{2787}
@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{2786,,weekday()},
@ref{ae9,,isocalendar()}.
@end deffn

@geindex isocalendar() (datetime.datetime 的方法)
@anchor{library/datetime datetime datetime isocalendar}@anchor{ae9}
@deffn {方法} datetime.isocalendar ()

Return a @ref{857,,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{d1d}
@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}，如果 @ref{2759,,microsecond} 不是 0

@item 
@code{YYYY-MM-DDTHH:MM:SS}，如果 @ref{2759,,microsecond} 是 0
@end itemize

如果 @ref{277e,,utcoffset()} 没有回傳 @code{None}，則會附加一个字串，給出 UTC 偏移：


@itemize -

@item 
@code{YYYY-MM-DDTHH:MM:SS.ffffff+HH:MM[:SS[.ffffff]]}，如果 @ref{2759,,microsecond} 不是 0

@item 
@code{YYYY-MM-DDTHH:MM:SS+HH:MM[:SS[.ffffff]]}，如果 @ref{2759,,microsecond} 是 0
@end itemize

範例：

@example
>>> from datetime import datetime, timezone
>>> datetime(2019, 5, 18, 15, 17, 8, 132263).isoformat()
'2019-05-18T15:17:08.132263'
>>> datetime(2019, 5, 18, 15, 17, tzinfo=timezone.utc).isoformat()
'2019-05-18T15:17:00+00:00'
@end example

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
>>> from datetime import tzinfo, timedelta, datetime
>>> class TZ(tzinfo):
...     """A time zone with an arbitrary, constant -06:39 offset."""
...     def utcoffset(self, dt):
...         return timedelta(hours=-6, minutes=-39)
...
>>> datetime(2002, 12, 25, tzinfo=TZ()).isoformat(' ')
'2002-12-25 00:00:00-06:39'
>>> datetime(2009, 11, 27, microsecond=100, tzinfo=TZ()).isoformat()
'2009-11-27T00:00:00.000100-06:39'
@end example

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{2759,,microsecond} is 0,
same as @code{'microseconds'} otherwise.

@item 
@code{'hours'}: Include the @ref{2756,,hour} in the two-digit @code{HH} format.

@item 
@code{'minutes'}: Include @ref{2756,,hour} and @ref{2757,,minute} in @code{HH:MM} format.

@item 
@code{'seconds'}: Include @ref{2756,,hour}, @ref{2757,,minute}, and @ref{2758,,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{2eb,,ValueError} will be raised on an invalid `timespec' argument:

@example
>>> from datetime import datetime
>>> datetime.now().isoformat(timespec='minutes')
'2002-12-25T00:00'
>>> dt = datetime(2015, 1, 1, 12, 30, 59, 0)
>>> dt.isoformat(timespec='microseconds')
'2015-01-01T12:30:59.000000'
@end example


在 3.6 版的變更: 新增 `timespec' 參數。

@end deffn

@geindex __str__() (datetime.datetime 的方法)
@anchor{library/datetime datetime datetime __str__}@anchor{2788}
@deffn {方法} datetime.__str__ ()

For a @ref{4dd,,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{2789}
@deffn {方法} datetime.ctime ()

Return a string representing the date and time:

@example
>>> from datetime import datetime
>>> 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()} 等價於：

@example
time.ctime(time.mktime(d.timetuple()))
@end example

on platforms where the native C @code{ctime()} function
(which @ref{2772,,time.ctime()} invokes, but which
@ref{2789,,datetime.ctime()} does not invoke) conforms to the C standard.
@end deffn

@geindex strftime() (datetime.datetime 的方法)
@anchor{library/datetime datetime datetime strftime}@anchor{e89}
@deffn {方法} datetime.strftime (format)

Return a string representing the date and time,
controlled by an explicit format string.
See also @ref{1a83,,strftime() 與 strptime() 的行為} and @ref{d1d,,datetime.isoformat()}.
@end deffn

@geindex __format__() (datetime.datetime 的方法)
@anchor{library/datetime datetime datetime __format__}@anchor{278a}
@deffn {方法} datetime.__format__ (format)

Same as @ref{e89,,datetime.strftime()}. This makes it possible to specify a format
string for a @ref{4dd,,datetime} object in @ref{19a,,formatted string literals} and when using @ref{82c,,str.format()}.
See also @ref{1a83,,strftime() 與 strptime() 的行為} and @ref{d1d,,datetime.isoformat()}.
@end deffn

@menu
* 用法範例：datetime:: 

@end menu

@node 用法範例：datetime,,,datetime 物件
@anchor{library/datetime examples-of-usage-datetime}@anchor{278b}
@subsubsection 用法範例：@code{datetime}


更多 @ref{4dd,,datetime} 的用法範例：

@example
>>> from datetime import datetime, date, time, timezone

>>> # Using datetime.combine()
>>> d = date(2005, 7, 14)
>>> t = time(12, 30)
>>> datetime.combine(d, t)
datetime.datetime(2005, 7, 14, 12, 30)

>>> # Using datetime.now()
>>> datetime.now()
datetime.datetime(2007, 12, 6, 16, 29, 43, 79043)   # GMT +1
>>> datetime.now(timezone.utc)
datetime.datetime(2007, 12, 6, 15, 29, 43, 79060, tzinfo=datetime.timezone.utc)

>>> # Using datetime.strptime()
>>> dt = datetime.strptime("21/11/06 16:30", "%d/%m/%y %H:%M")
>>> dt
datetime.datetime(2006, 11, 21, 16, 30)

>>> # Using datetime.timetuple() to get tuple of all attributes
>>> tt = dt.timetuple()
>>> for it in tt:
...     print(it)
...
2006    # year
11      # month
21      # day
16      # hour
30      # minute
0       # second
1       # weekday (0 = Monday)
325     # number of days since 1st January
-1      # dst - method tzinfo.dst() returned None

>>> # Date in ISO format
>>> ic = dt.isocalendar()
>>> for it in ic:
...     print(it)
...
2006    # ISO year
47      # ISO week
2       # ISO weekday

>>> # Formatting a datetime
>>> dt.strftime("%A, %d. %B %Y %I:%M%p")
'Tuesday, 21. November 2006 04:30PM'
>>> 'The @{1@} is @{0:%d@}, the @{2@} is @{0:%B@}, the @{3@} is @{0:%I:%M%p@}.'.format(dt, "day", "month", "time")
'The day is 21, the month is November, the time is 04:30PM.'
@end example

The example below defines a @ref{7ef,,tzinfo} subclass capturing time zone
information for Kabul, Afghanistan, which used +4 UTC until 1945
and then +4:30 UTC thereafter:

@example
from datetime import timedelta, datetime, tzinfo, timezone

class KabulTz(tzinfo):
    # Kabul used +4 until 1945, when they moved to +4:30
    UTC_MOVE_DATE = datetime(1944, 12, 31, 20, tzinfo=timezone.utc)

    def utcoffset(self, dt):
        if dt.year < 1945:
            return timedelta(hours=4)
        elif (1945, 1, 1, 0, 0) <= dt.timetuple()[:5] < (1945, 1, 1, 0, 30):
            # An ambiguous ("imaginary") half-hour range representing
            # a 'fold' in time due to the shift from +4 to +4:30.
            # If dt falls in the imaginary range, use fold to decide how
            # to resolve. See PEP495.
            return timedelta(hours=4, minutes=(30 if dt.fold else 0))
        else:
            return timedelta(hours=4, minutes=30)

    def fromutc(self, dt):
        # Follow same validations as in datetime.tzinfo
        if not isinstance(dt, datetime):
            raise TypeError("fromutc() requires a datetime argument")
        if dt.tzinfo is not self:
            raise ValueError("dt.tzinfo is not self")

        # A custom implementation is required for fromutc as
        # the input to this function is a datetime with utc values
        # but with a tzinfo set to self.
        # See datetime.astimezone or fromtimestamp.
        if dt.replace(tzinfo=timezone.utc) >= self.UTC_MOVE_DATE:
            return dt + timedelta(hours=4, minutes=30)
        else:
            return dt + timedelta(hours=4)

    def dst(self, dt):
        # Kabul does not observe daylight saving time.
        return timedelta(0)

    def tzname(self, dt):
        if dt >= self.UTC_MOVE_DATE:
            return "+04:30"
        return "+04"
@end example

Usage of @code{KabulTz} from above:

@example
>>> tz1 = KabulTz()

>>> # Datetime before the change
>>> dt1 = datetime(1900, 11, 21, 16, 30, tzinfo=tz1)
>>> print(dt1.utcoffset())
4:00:00

>>> # Datetime after the change
>>> dt2 = datetime(2006, 6, 14, 13, 0, tzinfo=tz1)
>>> print(dt2.utcoffset())
4:30:00

>>> # Convert datetime to another time zone
>>> dt3 = dt2.astimezone(timezone.utc)
>>> dt3
datetime.datetime(2006, 6, 14, 8, 30, tzinfo=datetime.timezone.utc)
>>> dt2
datetime.datetime(2006, 6, 14, 13, 0, tzinfo=KabulTz())
>>> dt2 == dt3
True
@end example

@node time 物件,tzinfo 物件,datetime 物件,datetime --- 日期與時間的基本型別
@anchor{library/datetime datetime-time}@anchor{278c}@anchor{library/datetime time-objects}@anchor{278d}
@subsubsection @code{time} 物件


A @ref{1fb,,time} object represents a (local) time of day, independent of any particular
day, and subject to adjustment via a @ref{7ef,,tzinfo} object.

@geindex time (datetime 中的類別)
@anchor{library/datetime datetime time}@anchor{1fb}
@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{7ef,,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{2eb,,ValueError} is raised. All
default to 0 except `tzinfo', which defaults to @code{None}.
@end deffn

類別屬性：

@geindex min (datetime.time 的屬性)
@anchor{library/datetime datetime time min}@anchor{278e}
@deffn {屬性} time.min

The earliest representable @ref{1fb,,time}, @code{time(0, 0, 0, 0)}.
@end deffn

@geindex max (datetime.time 的屬性)
@anchor{library/datetime datetime time max}@anchor{278f}
@deffn {屬性} time.max

The latest representable @ref{1fb,,time}, @code{time(23, 59, 59, 999999)}.
@end deffn

@geindex resolution (datetime.time 的屬性)
@anchor{library/datetime datetime time resolution}@anchor{2790}
@deffn {屬性} time.resolution

The smallest possible difference between non-equal @ref{1fb,,time} objects,
@code{timedelta(microseconds=1)}, although note that arithmetic on
@ref{1fb,,time} objects is not supported.
@end deffn

Instance attributes (read-only):

@geindex hour (datetime.time 的屬性)
@anchor{library/datetime datetime time hour}@anchor{274e}
@deffn {屬性} time.hour

In @code{range(24)}.
@end deffn

@geindex minute (datetime.time 的屬性)
@anchor{library/datetime datetime time minute}@anchor{274f}
@deffn {屬性} time.minute

In @code{range(60)}.
@end deffn

@geindex second (datetime.time 的屬性)
@anchor{library/datetime datetime time second}@anchor{2750}
@deffn {屬性} time.second

In @code{range(60)}.
@end deffn

@geindex microsecond (datetime.time 的屬性)
@anchor{library/datetime datetime time microsecond}@anchor{2751}
@deffn {屬性} time.microsecond

In @code{range(1000000)}.
@end deffn

@geindex tzinfo (datetime.time 的屬性)
@anchor{library/datetime datetime time tzinfo}@anchor{2752}
@deffn {屬性} time.tzinfo

The object passed as the tzinfo argument to the @ref{1fb,,time} constructor, or
@code{None} if none was passed.
@end deffn

@geindex fold (datetime.time 的屬性)
@anchor{library/datetime datetime time fold}@anchor{e88}
@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.


在 3.6 版被加入.

@end deffn

@ref{1fb,,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{198,,TypeError}.

If both comparands are aware, and have the same @ref{2752,,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{1fb,,time} instances
don't raise @ref{198,,TypeError}.


In Boolean contexts, a @ref{1fb,,time} object is always considered to be true.


在 3.5 版的變更: Before Python 3.5, a @ref{1fb,,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.


其他建構函式：

@geindex fromisoformat() (datetime.time 的類別方法)
@anchor{library/datetime datetime time fromisoformat}@anchor{822}
@deffn {方法} classmethod time.fromisoformat (time_string)

Return a @ref{1fb,,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

範例：

@example
>>> from datetime import time
>>> time.fromisoformat('04:23:01')
datetime.time(4, 23, 1)
>>> time.fromisoformat('T04:23:01')
datetime.time(4, 23, 1)
>>> time.fromisoformat('T042301')
datetime.time(4, 23, 1)
>>> time.fromisoformat('04:23:01.000384')
datetime.time(4, 23, 1, 384)
>>> time.fromisoformat('04:23:01,000384')
datetime.time(4, 23, 1, 384)
>>> time.fromisoformat('04:23:01+04:00')
datetime.time(4, 23, 1, tzinfo=datetime.timezone(datetime.timedelta(seconds=14400)))
>>> time.fromisoformat('04:23:01Z')
datetime.time(4, 23, 1, tzinfo=datetime.timezone.utc)
>>> time.fromisoformat('04:23:01+00:00')
datetime.time(4, 23, 1, tzinfo=datetime.timezone.utc)
@end example


在 3.7 版被加入.



在 3.11 版的變更: Previously, this method only supported formats that could be emitted by
@ref{2791,,time.isoformat()}.

@end deffn

@geindex strptime() (datetime.time 的類別方法)
@anchor{library/datetime datetime time strptime}@anchor{18b3}
@deffn {方法} classmethod time.strptime (date_string, format)

Return a @ref{1fb,,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{2eb,,ValueError} is raised if the `date_string' and `format'
cannot be parsed by @ref{1624,,time.strptime()} or if it returns a value which is not a
time tuple.  See also @ref{1a83,,strftime() 與 strptime() 的行為} and
@ref{822,,time.fromisoformat()}.


在 3.14 版被加入.

@end deffn

實例方法：

@geindex replace() (datetime.time 的方法)
@anchor{library/datetime datetime time replace}@anchor{1949}
@deffn {方法} time.replace (hour=self.hour, minute=self.minute, second=self.second, microsecond=self.microsecond, tzinfo=self.tzinfo, *, fold=0)

Return a new @ref{1fb,,time} with the same values, but with specified
parameters updated. Note that @code{tzinfo=None} can be specified to create a
naive @ref{1fb,,time} from an aware @ref{1fb,,time}, without conversion of the
time data.

@ref{1fb,,time} objects are also supported by generic function
@ref{1c0,,copy.replace()}.


在 3.6 版的變更: 新增 `fold' 參數。

@end deffn

@geindex isoformat() (datetime.time 的方法)
@anchor{library/datetime datetime time isoformat}@anchor{2791}
@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{2751,,microsecond} is not 0

@item 
@code{HH:MM:SS}, if @ref{2751,,microsecond} is 0

@item 
@code{HH:MM:SS.ffffff+HH:MM[:SS[.ffffff]]}, if @ref{2792,,utcoffset()} does not return @code{None}

@item 
@code{HH:MM:SS+HH:MM[:SS[.ffffff]]}, if @ref{2751,,microsecond} is 0 and @ref{2792,,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{2751,,microsecond} is 0,
same as @code{'microseconds'} otherwise.

@item 
@code{'hours'}: Include the @ref{274e,,hour} in the two-digit @code{HH} format.

@item 
@code{'minutes'}: Include @ref{274e,,hour} and @ref{274f,,minute} in @code{HH:MM} format.

@item 
@code{'seconds'}: Include @ref{274e,,hour}, @ref{274f,,minute}, and @ref{2750,,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{2eb,,ValueError} will be raised on an invalid `timespec' argument.

範例：

@example
>>> from datetime import time
>>> time(hour=12, minute=34, second=56, microsecond=123456).isoformat(timespec='minutes')
'12:34'
>>> dt = time(hour=12, minute=34, second=56, microsecond=0)
>>> dt.isoformat(timespec='microseconds')
'12:34:56.000000'
>>> dt.isoformat(timespec='auto')
'12:34:56'
@end example


在 3.6 版的變更: 新增 `timespec' 參數。

@end deffn

@geindex __str__() (datetime.time 的方法)
@anchor{library/datetime datetime time __str__}@anchor{2793}
@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{1a3e}
@deffn {方法} time.strftime (format)

Return a string representing the time, controlled by an explicit format
string.  See also @ref{1a83,,strftime() 與 strptime() 的行為} and @ref{2791,,time.isoformat()}.
@end deffn

@geindex __format__() (datetime.time 的方法)
@anchor{library/datetime datetime time __format__}@anchor{2794}
@deffn {方法} time.__format__ (format)

Same as @ref{1a3e,,time.strftime()}. This makes it possible to specify
a format string for a @ref{1fb,,time} object in @ref{19a,,formatted string literals} and when using @ref{82c,,str.format()}.
See also @ref{1a83,,strftime() 與 strptime() 的行為} and @ref{2791,,time.isoformat()}.
@end deffn

@geindex utcoffset() (datetime.time 的方法)
@anchor{library/datetime datetime time utcoffset}@anchor{2792}
@deffn {方法} time.utcoffset ()

If @ref{2752,,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{bba,,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{2795}
@deffn {方法} time.dst ()

If @ref{2752,,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{bba,,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{2796}
@deffn {方法} time.tzname ()

If @ref{2752,,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
* 用法範例：time:: 

@end menu

@node 用法範例：time,,,time 物件
@anchor{library/datetime examples-of-usage-time}@anchor{2797}
@subsubsection 用法範例：@code{time}


Examples of working with a @ref{1fb,,time} object:

@example
>>> from datetime import time, tzinfo, timedelta
>>> class TZ1(tzinfo):
...     def utcoffset(self, dt):
...         return timedelta(hours=1)
...     def dst(self, dt):
...         return timedelta(0)
...     def tzname(self,dt):
...         return "+01:00"
...     def  __repr__(self):
...         return f"@{self.__class__.__name__@}()"
...
>>> t = time(12, 10, 30, tzinfo=TZ1())
>>> t
datetime.time(12, 10, 30, tzinfo=TZ1())
>>> t.isoformat()
'12:10:30+01:00'
>>> t.dst()
datetime.timedelta(0)
>>> t.tzname()
'+01:00'
>>> t.strftime("%H:%M:%S %Z")
'12:10:30 +01:00'
>>> 'The @{@} is @{:%H:%M@}.'.format("time", t)
'The time is 12:10.'
@end example

@node tzinfo 物件,timezone 物件,time 物件,datetime --- 日期與時間的基本型別
@anchor{library/datetime datetime-tzinfo}@anchor{2798}@anchor{library/datetime tzinfo-objects}@anchor{2799}
@subsubsection @code{tzinfo} 物件


@geindex tzinfo (datetime 中的類別)
@anchor{library/datetime datetime tzinfo}@anchor{7ef}
@deffn {類別} datetime.tzinfo

This is an abstract base class, meaning that this class should not be
instantiated directly.  Define a subclass of @ref{7ef,,tzinfo} to capture
information about a particular time zone.

An instance of (a concrete subclass of) @ref{7ef,,tzinfo} can be passed to the
constructors for @ref{4dd,,datetime} and @ref{1fb,,time} objects. The latter objects
view their attributes as being in local time, and the @ref{7ef,,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 @ref{7ef,,tzinfo} methods needed by the
@ref{4dd,,datetime} methods you use. The @code{datetime} module provides
@ref{12c0,,timezone}, a simple concrete subclass of @ref{7ef,,tzinfo} which can
represent time zones with fixed offset from UTC such as UTC itself or North
American EST and EDT.

Special requirement for pickling:  A @ref{7ef,,tzinfo} subclass must have an
@ref{8b7,,__init__()} method that can be called with no arguments,
otherwise it can be
pickled but possibly not unpickled again. This is a technical requirement that
may be relaxed in the future.

A concrete subclass of @ref{7ef,,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{279a}
@deffn {方法} tzinfo.utcoffset (dt)

Return offset of local time from UTC, as a @ref{bba,,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{7ef,,tzinfo} object represents both time zone and DST adjustments,
@ref{279a,,utcoffset()} should return their sum. If the UTC offset isn't known,
return @code{None}. Else the value returned must be a @ref{bba,,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 @ref{279a,,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 @ref{279a,,utcoffset()} does not return @code{None}, @ref{279b,,dst()} should not return
@code{None} either.

The default implementation of @ref{279a,,utcoffset()} raises
@ref{369,,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{279b}
@deffn {方法} tzinfo.dst (dt)

Return the daylight saving time (DST) adjustment, as a @ref{bba,,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{bba,,timedelta} object
(see @ref{279a,,utcoffset()} for details). Note that DST offset, if applicable, has
already been added to the UTC offset returned by @ref{279a,,utcoffset()}, so there's
no need to consult @ref{279b,,dst()} unless you're interested in obtaining DST info
separately. For example, @ref{2782,,datetime.timetuple()} calls its @ref{275a,,tzinfo}
attribute's @ref{279b,,dst()} method to determine how the @ref{2783,,tm_isdst} flag
should be set, and @ref{2780,,tzinfo.fromutc()} calls @ref{279b,,dst()} to account for
DST changes when crossing time zones.

An instance `tz' of a @ref{7ef,,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{4dd,,datetime} `dt' with @code{dt.tzinfo ==
tz}. For sane @ref{7ef,,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{bbb,,datetime.astimezone()}
relies on this, but cannot detect violations; it's the programmer's
responsibility to ensure it. If a @ref{7ef,,tzinfo} subclass cannot guarantee
this, it may be able to override the default implementation of
@ref{2780,,tzinfo.fromutc()} to work correctly with @ref{bbb,,astimezone()} regardless.

Most implementations of @ref{279b,,dst()} will probably look like one of these two:

@example
def dst(self, dt):
    # a fixed-offset class:  doesn't account for DST
    return timedelta(0)
@end example

或是：

@example
def dst(self, dt):
    # Code to set dston and dstoff to the time zone's DST
    # transition times based on the input dt.year, and expressed
    # in standard local time.

    if dston <= dt.replace(tzinfo=None) < dstoff:
        return timedelta(hours=1)
    else:
        return timedelta(0)
@end example

The default implementation of @ref{279b,,dst()} raises @ref{369,,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{279c}
@deffn {方法} tzinfo.tzname (dt)

Return the time zone name corresponding to the @ref{4dd,,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{7ef,,tzinfo}
subclasses will wish to return different names depending on the specific value
of `dt' passed, especially if the @ref{7ef,,tzinfo} class is accounting for
daylight time.

The default implementation of @ref{279c,,tzname()} raises @ref{369,,NotImplementedError}.
@end deffn

These methods are called by a @ref{4dd,,datetime} or @ref{1fb,,time} object, in
response to their methods of the same names. A @ref{4dd,,datetime} object passes
itself as the argument, and a @ref{1fb,,time} object passes @code{None} as the
argument. A @ref{7ef,,tzinfo} subclass's methods should therefore be prepared to
accept a `dt' argument of @code{None}, or of class @ref{4dd,,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{7ef,,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{4dd,,datetime} object is passed in response to a @ref{4dd,,datetime}
method, @code{dt.tzinfo} is the same object as `self'. @ref{7ef,,tzinfo} methods can
rely on this, unless user code calls @ref{7ef,,tzinfo} methods directly. The
intent is that the @ref{7ef,,tzinfo} methods interpret `dt' as being in local
time, and not need worry about objects in other time zones.

There is one more @ref{7ef,,tzinfo} method that a subclass may wish to override:

@geindex fromutc() (datetime.tzinfo 的方法)
@anchor{library/datetime datetime tzinfo fromutc}@anchor{2780}
@deffn {方法} tzinfo.fromutc (dt)

This is called from the default @ref{bbb,,datetime.astimezone()}
implementation. When called from that, @code{dt.tzinfo} is `self', and `dt''s
date and time data are to be viewed as expressing a UTC time. The purpose
of @ref{2780,,fromutc()} is to adjust the date and time data, returning an
equivalent datetime in `self''s local time.

Most @ref{7ef,,tzinfo} subclasses should be able to inherit the default
@ref{2780,,fromutc()} implementation without problems. It's strong enough to handle
fixed-offset time zones, and time zones accounting for both standard and
daylight time, and the latter even if the DST transition times differ in
different years. An example of a time zone the default @ref{2780,,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{bbb,,astimezone()} and
@ref{2780,,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 @ref{2780,,fromutc()} implementation acts
like:

@example
def fromutc(self, dt):
    # raise ValueError error if dt.tzinfo is not self
    dtoff = dt.utcoffset()
    dtdst = dt.dst()
    # raise ValueError if dtoff is None or dtdst is None
    delta = dtoff - dtdst  # this is self's standard offset
    if delta:
        dt += delta   # convert to standard local time
        dtdst = dt.dst()
        # raise ValueError if dtdst is None
    if dtdst:
        return dt + dtdst
    else:
        return dt
@end example
@end deffn

In the following @code{tzinfo_examples.py} file there are some examples of
@ref{7ef,,tzinfo} classes:

@example
from datetime import tzinfo, timedelta, datetime

ZERO = timedelta(0)
HOUR = timedelta(hours=1)
SECOND = timedelta(seconds=1)

# A class capturing the platform's idea of local time.
# (May result in wrong values on historical times in
#  timezones where UTC offset and/or the DST rules had
#  changed in the past.)
import time as _time

STDOFFSET = timedelta(seconds = -_time.timezone)
if _time.daylight:
    DSTOFFSET = timedelta(seconds = -_time.altzone)
else:
    DSTOFFSET = STDOFFSET

DSTDIFF = DSTOFFSET - STDOFFSET

class LocalTimezone(tzinfo):

    def fromutc(self, dt):
        assert dt.tzinfo is self
        stamp = (dt - datetime(1970, 1, 1, tzinfo=self)) // SECOND
        args = _time.localtime(stamp)[:6]
        dst_diff = DSTDIFF // SECOND
        # Detect fold
        fold = (args == _time.localtime(stamp - dst_diff))
        return datetime(*args, microsecond=dt.microsecond,
                        tzinfo=self, fold=fold)

    def utcoffset(self, dt):
        if self._isdst(dt):
            return DSTOFFSET
        else:
            return STDOFFSET

    def dst(self, dt):
        if self._isdst(dt):
            return DSTDIFF
        else:
            return ZERO

    def tzname(self, dt):
        return _time.tzname[self._isdst(dt)]

    def _isdst(self, dt):
        tt = (dt.year, dt.month, dt.day,
              dt.hour, dt.minute, dt.second,
              dt.weekday(), 0, 0)
        stamp = _time.mktime(tt)
        tt = _time.localtime(stamp)
        return tt.tm_isdst > 0

Local = LocalTimezone()


# A complete implementation of current DST rules for major US time zones.

def first_sunday_on_or_after(dt):
    days_to_go = 6 - dt.weekday()
    if days_to_go:
        dt += timedelta(days_to_go)
    return dt


# US DST Rules
#
# This is a simplified (i.e., wrong for a few cases) set of rules for US
# DST start and end times. For a complete and up-to-date set of DST rules
# and timezone definitions, visit the Olson Database (or try pytz):
# http://www.twinsun.com/tz/tz-link.htm
# https://sourceforge.net/projects/pytz/ (might not be up-to-date)
#
# In the US, since 2007, DST starts at 2am (standard time) on the second
# Sunday in March, which is the first Sunday on or after Mar 8.
DSTSTART_2007 = datetime(1, 3, 8, 2)
# and ends at 2am (DST time) on the first Sunday of Nov.
DSTEND_2007 = datetime(1, 11, 1, 2)
# From 1987 to 2006, DST used to start at 2am (standard time) on the first
# Sunday in April and to end at 2am (DST time) on the last
# Sunday of October, which is the first Sunday on or after Oct 25.
DSTSTART_1987_2006 = datetime(1, 4, 1, 2)
DSTEND_1987_2006 = datetime(1, 10, 25, 2)
# From 1967 to 1986, DST used to start at 2am (standard time) on the last
# Sunday in April (the one on or after April 24) and to end at 2am (DST time)
# on the last Sunday of October, which is the first Sunday
# on or after Oct 25.
DSTSTART_1967_1986 = datetime(1, 4, 24, 2)
DSTEND_1967_1986 = DSTEND_1987_2006

def us_dst_range(year):
    # Find start and end times for US DST. For years before 1967, return
    # start = end for no DST.
    if 2006 < year:
        dststart, dstend = DSTSTART_2007, DSTEND_2007
    elif 1986 < year < 2007:
        dststart, dstend = DSTSTART_1987_2006, DSTEND_1987_2006
    elif 1966 < year < 1987:
        dststart, dstend = DSTSTART_1967_1986, DSTEND_1967_1986
    else:
        return (datetime(year, 1, 1), ) * 2

    start = first_sunday_on_or_after(dststart.replace(year=year))
    end = first_sunday_on_or_after(dstend.replace(year=year))
    return start, end


class USTimeZone(tzinfo):

    def __init__(self, hours, reprname, stdname, dstname):
        self.stdoffset = timedelta(hours=hours)
        self.reprname = reprname
        self.stdname = stdname
        self.dstname = dstname

    def __repr__(self):
        return self.reprname

    def tzname(self, dt):
        if self.dst(dt):
            return self.dstname
        else:
            return self.stdname

    def utcoffset(self, dt):
        return self.stdoffset + self.dst(dt)

    def dst(self, dt):
        if dt is None or dt.tzinfo is None:
            # An exception may be sensible here, in one or both cases.
            # It depends on how you want to treat them.  The default
            # fromutc() implementation (called by the default astimezone()
            # implementation) passes a datetime with dt.tzinfo is self.
            return ZERO
        assert dt.tzinfo is self
        start, end = us_dst_range(dt.year)
        # Can't compare naive to aware objects, so strip the timezone from
        # dt first.
        dt = dt.replace(tzinfo=None)
        if start + HOUR <= dt < end - HOUR:
            # DST is in effect.
            return HOUR
        if end - HOUR <= dt < end:
            # Fold (an ambiguous hour): use dt.fold to disambiguate.
            return ZERO if dt.fold else HOUR
        if start <= dt < start + HOUR:
            # Gap (a non-existent hour): reverse the fold rule.
            return HOUR if dt.fold else ZERO
        # DST is off.
        return ZERO

    def fromutc(self, dt):
        assert dt.tzinfo is self
        start, end = us_dst_range(dt.year)
        start = start.replace(tzinfo=self)
        end = end.replace(tzinfo=self)
        std_time = dt + self.stdoffset
        dst_time = std_time + HOUR
        if end <= dst_time < end + HOUR:
            # Repeated hour
            return std_time.replace(fold=1)
        if std_time < start or dst_time >= end:
            # Standard time
            return std_time
        if start <= std_time < end - HOUR:
            # Daylight saving time
            return dst_time


Eastern  = USTimeZone(-5, "Eastern",  "EST", "EDT")
Central  = USTimeZone(-6, "Central",  "CST", "CDT")
Mountain = USTimeZone(-7, "Mountain", "MST", "MDT")
Pacific  = USTimeZone(-8, "Pacific",  "PST", "PDT")
@end example

Note that there are unavoidable subtleties twice per year in a @ref{7ef,,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
>>> from datetime import datetime, timezone
>>> from tzinfo_examples import HOUR, Eastern
>>> u0 = datetime(2016, 3, 13, 5, tzinfo=timezone.utc)
>>> for i in range(4):
...     u = u0 + i*HOUR
...     t = u.astimezone(Eastern)
...     print(u.time(), 'UTC =', t.time(), t.tzname())
...
05:00:00 UTC = 00:00:00 EST
06:00:00 UTC = 01:00:00 EST
07:00:00 UTC = 03:00:00 EDT
08:00:00 UTC = 04:00:00 EDT
@end example

When DST ends (the "end" line), there's a potentially worse problem: there's an
hour that can't be spelled unambiguously in local wall time: the last hour of
daylight time. In Eastern, that's times of the form 5:MM UTC on the day
daylight time ends. The local wall clock leaps from 1:59 (daylight time) back
to 1:00 (standard time) again. Local times of the form 1:MM are ambiguous.
@ref{bbb,,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{e4c,,fold} attribute set to 0 and the later times have it set to 1.
For example, at the Fall back transition of 2016, we get:

@example
>>> u0 = datetime(2016, 11, 6, 4, tzinfo=timezone.utc)
>>> for i in range(4):
...     u = u0 + i*HOUR
...     t = u.astimezone(Eastern)
...     print(u.time(), 'UTC =', t.time(), t.tzname(), t.fold)
...
04:00:00 UTC = 00:00:00 EDT 0
05:00:00 UTC = 01:00:00 EDT 0
06:00:00 UTC = 01:00:00 EST 1
07:00:00 UTC = 02:00:00 EST 0
@end example

Note that the @ref{4dd,,datetime} instances that differ only by the value of the
@ref{e4c,,fold} attribute are considered equal in comparisons.

Applications that can't bear wall-time ambiguities should explicitly check the
value of the @ref{e4c,,fold} attribute or avoid using hybrid
@ref{7ef,,tzinfo} subclasses; there are no ambiguities when using @ref{12c0,,timezone},
or any other fixed-offset @ref{7ef,,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{13a,,zoneinfo}

The @code{datetime} module has a basic @ref{12c0,,timezone} class (for
handling arbitrary fixed offsets from UTC) and its @ref{820,,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 時區資料庫@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 物件,strftime 與 strptime 的行為,tzinfo 物件,datetime --- 日期與時間的基本型別
@anchor{library/datetime datetime-timezone}@anchor{279d}@anchor{library/datetime timezone-objects}@anchor{279e}
@subsubsection @code{timezone} 物件


The @ref{12c0,,timezone} class is a subclass of @ref{7ef,,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{12c0}
@deffn {類別} datetime.timezone (offset, name=None)

The `offset' argument must be specified as a @ref{bba,,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{2eb,,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{2781,,datetime.tzname()} method.


在 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{279f}
@deffn {方法} timezone.utcoffset (dt)

Return the fixed value specified when the @ref{12c0,,timezone} instance is
constructed.

The `dt' argument is ignored. The return value is a @ref{bba,,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{27a0}
@deffn {方法} timezone.tzname (dt)

Return the fixed value specified when the @ref{12c0,,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{27a1}
@deffn {方法} timezone.dst (dt)

總是回傳 @code{None}。
@end deffn

@geindex fromutc() (datetime.timezone 的方法)
@anchor{library/datetime datetime timezone fromutc}@anchor{27a2}
@deffn {方法} timezone.fromutc (dt)

Return @code{dt + offset}. The `dt' argument must be an aware
@ref{4dd,,datetime} instance, with @code{tzinfo} set to @code{self}.
@end deffn

類別屬性：

@geindex utc (datetime.timezone 的屬性)
@anchor{library/datetime datetime timezone utc}@anchor{820}
@deffn {屬性} timezone.utc

UTC 時區，@code{timezone(timedelta(0))}。
@end deffn

@geindex % （百分號）;datetime format（日期時間格式）

@node strftime 與 strptime 的行為,,timezone 物件,datetime --- 日期與時間的基本型別
@anchor{library/datetime strftime-and-strptime-behavior}@anchor{27a3}@anchor{library/datetime strftime-strptime-behavior}@anchor{1a83}
@subsubsection @code{strftime()} 與 @code{strptime()} 的行為


@ref{1fa,,date}, @ref{4dd,,datetime}, and @ref{1fb,,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{1f9,,date.strptime()}, @ref{18b7,,datetime.strptime()} and
@ref{1624,,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{e89,,strftime()}
versus @ref{18b7,,strptime()}:


@multitable {xxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

@tab

@code{strftime}

@tab

@code{strptime}

@item

用法

@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

實例方法

@tab

類別方法

@item

Signature

@tab

@code{strftime(format)}

@tab

@code{strptime(date_string, format)}

@end multitable


@quotation
@anchor{library/datetime format-codes}@anchor{2744}
@end quotation

@menu
* strftime() 與 strptime() 格式碼: strftime 與 strptime 格式碼. 
* 技術細節:: 

@end menu

@node strftime 與 strptime 格式碼,技術細節,,strftime 與 strptime 的行為
@anchor{library/datetime strftime-and-strptime-format-codes}@anchor{27a4}
@subsubsection @code{strftime()} 與 @code{strptime()} 格式碼


These methods accept format codes that can be used to parse and format dates:

@example
>>> datetime.strptime('31/01/22 23:59:59.999999',
...                   '%d/%m/%y %H:%M:%S.%f')
datetime.datetime(2022, 1, 31, 23, 59, 59, 999999)
>>> _.strftime('%a %d %b %Y, %I:%M%p')
'Mon 31 Jan 2022, 11:59PM'
@end example

The following is a list of all the format codes that the 1989 C standard
requires, and these work on all platforms with a standard C implementation.


@multitable {xxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxx} 
@headitem

Directive

@tab

含義

@tab

範例

@tab

註解

@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{%w}

@tab

Weekday as a decimal number,
where 0 is Sunday and 6 is
Saturday.

@tab

0, 1, ..., 6

@tab

@item

@code{%d}

@tab

Day of the month as a
zero-padded decimal number.

@tab

01, 02, ..., 31

@tab

(9)

@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{%m}

@tab

以零填充的並以十進位數字表示的月份。

@tab

01, 02, ..., 12

@tab

(9)

@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{%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{%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{%M}

@tab

Minute as a zero-padded
decimal number.

@tab

00, 01, ..., 59

@tab

(9)

@item

@code{%S}

@tab

Second as a zero-padded
decimal number.

@tab

00, 01, ..., 59

@tab

(4),
(9)

@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{±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{%j}

@tab

Day of the year as a
zero-padded decimal number.

@tab

001, 002, ..., 366

@tab

(9)

@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{%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{%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{%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{%%}

@tab

A literal @code{'%'} character.

@tab

%

@tab

@end multitable


Several additional directives not required by the C89 standard are included for
convenience. These parameters all correspond to ISO 8601 date values.


@multitable {xxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxx} 
@headitem

Directive

@tab

含義

@tab

範例

@tab

註解

@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{%u}

@tab

ISO 8601 weekday as a decimal
number where 1 is Monday.

@tab

1, 2, ..., 7

@tab

@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{%:z}

@tab

UTC offset in the form
@code{±HH:MM[:SS[.ffffff]]}
(empty string if the object is
naive).

@tab

(empty), +00:00,
-04:00, +10:30,
+06:34:15,
-03:07:12.345216

@tab

(6)

@end multitable


These may not be available on all platforms when used with the @ref{e89,,strftime()}
method. The ISO 8601 year and ISO 8601 week directives are not interchangeable
with the year and week number directives above. Calling @ref{18b7,,strptime()} with
incomplete or ambiguous ISO 8601 directives will raise a @ref{2eb,,ValueError}.

The full set of format codes supported varies across platforms, because Python
calls the platform C library's @code{strftime()} function, and platform
variations are common. To see the full set of format codes supported on your
platform, consult the @code{strftime(3)@footnote{https://manpages.debian.org/strftime(3)}} documentation. There are also
differences between platforms in handling of unsupported format specifiers.


在 3.6 版被加入: 新增 @code{%G}、@code{%u} 與 @code{%V}。



在 3.12 版被加入: 新增 @code{%:z}。


@node 技術細節,,strftime 與 strptime 格式碼,strftime 與 strptime 的行為
@anchor{library/datetime technical-detail}@anchor{27a5}
@subsubsection 技術細節


Broadly speaking, @code{d.strftime(fmt)} acts like the @ref{f4,,time} module's
@code{time.strftime(fmt, d.timetuple())} although not all objects support a
@ref{276b,,timetuple()} method.

For the @ref{18b7,,datetime.strptime()} class method, the default value is
@code{1900-01-01T00:00:00.000}: any components not specified in the format string
will be pulled from the default value. @footnote{
Passing @code{datetime.strptime('Feb 29', '%b %d')} will fail since 1900 is not a leap year.
}

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

對 @ref{1fb,,time} 物件來說，不應該使用年、月、日的格式碼，因為 @code{time} 物件並沒有這些值。如果使用這些格式碼，年份會以 1900 代替、月及日會以 1 代替。

對 @ref{1fa,,date} 物件來說，不應該使用時、分、秒、微秒的格式碼，因為 @ref{1fa,,date} 物件並沒有這些值。如果使用這些格式碼，這些值都會以 0 代替。

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{460,,UnicodeError} or return
an empty string instead.

註解：


@enumerate 

@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{18b7,,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{e89,,strftime()} method was restricted to
years >= 1900.



在 3.3 版的變更: In version 3.2, @ref{e89,,strftime()} method was restricted to
years >= 1000.


@item 
When used with the @ref{18b7,,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{f4,,time} module, the @code{datetime} module does not support
leap seconds.

@item 
When used with the @ref{18b7,,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{277e,,utcoffset()} is transformed into a string of the form
@code{±HHMM[SS[.ffffff]]}, where @code{HH} is a 2-digit string giving the number
of UTC offset hours, @code{MM} is a 2-digit string giving the number of UTC
offset minutes, @code{SS} is a 2-digit string giving the number of UTC offset
seconds and @code{ffffff} is a 6-digit string giving the number of UTC
offset microseconds. The @code{ffffff} part is omitted when the offset is a
whole number of seconds and both the @code{ffffff} and the @code{SS} part is
omitted when the offset is a whole number of minutes. For example, if
@ref{277e,,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{18b7,,strptime()} method,
the UTC offsets can have a colon as a separator between hours, minutes
and seconds.
For example, @code{'+01:00:00'} will be parsed as an offset of one hour.
In addition, providing @code{'Z'} is identical to @code{'+00:00'}.



@table @asis

@item @code{%:z}

Behaves exactly as @code{%z}, but has a colon separator added between
hours, minutes and seconds.

@item @code{%Z}

In @ref{e89,,strftime()}, @code{%Z} is replaced by an empty string if
@ref{2781,,tzname()} returns @code{None}; otherwise @code{%Z} is replaced by the
returned value, which must be a string.

@ref{18b7,,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{18b7,,strptime()} method, an
aware @ref{4dd,,datetime} object will be produced. The @code{tzinfo} of the
result will be set to a @ref{12c0,,timezone} instance.


@item 
When used with the @ref{18b7,,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{18b7,,strptime()} format string. Also note that @code{%G} and @code{%Y} are not
interchangeable.

@item 
When used with the @ref{18b7,,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{18b7,,strptime()}, always
include a year in the format.  If the value you need to parse lacks a year,
append an explicit dummy leap year.  Otherwise your code will raise an
exception when it encounters leap day because the default year used by the
parser is not a leap year.  Users run into this bug every four years...

@example
>>> month_day = "02/29"
>>> datetime.strptime(f"@{month_day@};1984", "%m/%d;%Y")  # 沒有閏年問題。
datetime.datetime(1984, 2, 29, 0, 0)
@end example


Deprecated since version 3.13, will be removed in version 3.15: @ref{18b7,,strptime()} calls using a format string containing
a day of month without a year now emit a
@ref{1a3,,DeprecationWarning}. In 3.15 or later we may change this into
an error or change the default year to a leap year. See gh-70647@footnote{https://github.com/python/cpython/issues/70647}.

@end enumerate

@subsubheading 註解


@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 時區支援,calendar --- 日曆相關函式,datetime --- 日期與時間的基本型別,資料型別
@anchor{library/zoneinfo doc}@anchor{27a6}@anchor{library/zoneinfo module-zoneinfo}@anchor{13a}@anchor{library/zoneinfo translation-repo}@anchor{27a7}@anchor{library/zoneinfo zoneinfo-iana-time-zone-support}@anchor{27a8}
@subsection @code{zoneinfo} --- IANA 時區支援


@geindex module; zoneinfo


在 3.9 版被加入.


`原始碼：'Lib/zoneinfo@footnote{https://github.com/python/cpython/tree/3.14/Lib/zoneinfo}


__________________________________________________________________


@ref{13a,,zoneinfo} 模組提供了一個具體的時區實作，以支援 
@geindex Python Enhancement Proposals; PEP 615
PEP 615@footnote{https://peps.python.org/pep-0615/} 中最初指定的 IANA 時區資料庫。預設情況下，如果可用，@ref{13a,,zoneinfo} 會使用系統的時區資料；如果沒有可用的系統時區資料，該函式庫將轉而使用 PyPI 上可用的第一方 tzdata@footnote{https://pypi.org/project/tzdata/} 套件。


@subsubheading 也參考



@table @asis

@item @ref{34,,datetime} 模組

提供了 @ref{1fb,,time} 與 @ref{4dd,,datetime} 型別，這些型別是設計來與 @ref{ad3,,ZoneInfo} 類別一起使用的。

@item tzdata@footnote{https://pypi.org/project/tzdata/} 套件

由 CPython 核心開發者維護的第一方套件，用於透過 PyPI 提供時區資料。
@end table


@c include for modules that don't work on WASM

@ref{2006,,可用性}: not WASI.

此模組在 WebAssembly 平台上不起作用或無法使用。更多資訊請參閱 @ref{1a99,,WebAssembly 平台}。

@menu
* 使用 ZoneInfo:: 
* 資料來源:: 
* ZoneInfo 類別:: 
* 函式: 函式<3>. 
* 全域變數:: 
* 例外與警告:: 

@end menu

@node 使用 ZoneInfo,資料來源,,zoneinfo --- IANA 時區支援
@anchor{library/zoneinfo using-zoneinfo}@anchor{27a9}
@subsubsection 使用 @code{ZoneInfo}


@ref{ad3,,ZoneInfo} 是 @ref{7ef,,datetime.tzinfo} 抽象基底類別的一個具體實作，旨在透過建構函式、@ref{16bf,,datetime.replace} 方法或 @ref{bbb,,datetime.astimezone} 方法附加到 @code{tzinfo}：

@example
>>> from zoneinfo import ZoneInfo
>>> from datetime import datetime, timedelta

>>> dt = datetime(2020, 10, 31, 12, tzinfo=ZoneInfo("America/Los_Angeles"))
>>> print(dt)
2020-10-31 12:00:00-07:00

>>> dt.tzname()
'PDT'
@end example

以此方式建構的 Datetime 物件與 datetime 運算相容，並能處理日光節約時間轉換而無需進一步干預：

@example
>>> dt_add = dt + timedelta(days=1)

>>> print(dt_add)
2020-11-01 12:00:00-08:00

>>> dt_add.tzname()
'PST'
@end example

這些時區也支援 
@geindex Python Enhancement Proposals; PEP 495
PEP 495@footnote{https://peps.python.org/pep-0495/} 中引入的 @ref{e4c,,fold} 屬性。在會引發時間模糊的時差轉換期間（例如日光節約時間到標準時間的轉換），當 @code{fold=0} 時，會使用轉換`前'的時差，而當 @code{fold=1} 時，會使用轉換`後'的時差，例如：

@example
>>> dt = datetime(2020, 11, 1, 1, tzinfo=ZoneInfo("America/Los_Angeles"))
>>> print(dt)
2020-11-01 01:00:00-07:00

>>> print(dt.replace(fold=1))
2020-11-01 01:00:00-08:00
@end example

當從另一個時區轉換時，fold 將被設定為正確的值：

@example
>>> from datetime import timezone
>>> LOS_ANGELES = ZoneInfo("America/Los_Angeles")
>>> dt_utc = datetime(2020, 11, 1, 8, tzinfo=timezone.utc)

>>> # 在 PDT 轉換為 PST 之前
>>> print(dt_utc.astimezone(LOS_ANGELES))
2020-11-01 01:00:00-07:00

>>> # 在 PDT 轉換為 PST 之後
>>> print((dt_utc + timedelta(hours=1)).astimezone(LOS_ANGELES))
2020-11-01 01:00:00-08:00
@end example

@node 資料來源,ZoneInfo 類別,使用 ZoneInfo,zoneinfo --- IANA 時區支援
@anchor{library/zoneinfo data-sources}@anchor{27aa}
@subsubsection 資料來源


@code{zoneinfo} 模組不直接提供時區資料，而是從系統時區資料庫或可用的第一方 PyPI 套件 tzdata@footnote{https://pypi.org/project/tzdata/} 中提取時區資訊。某些系統，特別是 Windows 系統，沒有可用的 IANA 資料庫，因此對於需要時區資料且目標為跨平台相容性的專案，建議宣告對 tzdata 的依賴。如果系統資料和 tzdata 都不可用，所有對 @ref{ad3,,ZoneInfo} 的呼叫都將引發 @ref{1799,,ZoneInfoNotFoundError} 例外。

@menu
* 設定資料來源:: 

@end menu

@node 設定資料來源,,,資料來源
@anchor{library/zoneinfo configuring-the-data-sources}@anchor{27ab}@anchor{library/zoneinfo zoneinfo-data-configuration}@anchor{27ac}
@subsubsection 設定資料來源


當呼叫 @code{ZoneInfo(key)} 時，建構函式會先在 @ref{2027,,TZPATH} 中指定的目錄中搜尋符合 @code{key} 的檔案，如果失敗，則在 tzdata 套件中尋找符合的項目。此行為可以透過三種方式設定：


@enumerate 

@item 
未另外指定時的預設 @ref{2027,,TZPATH} 可以在@ref{2028,,編譯時期}設定。

@item 
@ref{2027,,TZPATH} 可以使用 @ref{27ad,,環境變數} 來設定。

@item 
在 @ref{27ae,,runtime}，可以使用 @ref{1756,,reset_tzpath()} 函式來操作搜尋路徑。
@end enumerate

@menu
* 編譯時期設定:: 
* 環境設定:: 
* Runtime 設定:: 

@end menu

@node 編譯時期設定,環境設定,,設定資料來源
@anchor{library/zoneinfo compile-time-configuration}@anchor{27af}@anchor{library/zoneinfo zoneinfo-data-compile-time-config}@anchor{2028}
@subsubsection 編譯時期設定


預設的 @ref{2027,,TZPATH} 包含時區資料庫的幾個常見部署位置（Windows 除外，因為 Windows 上沒有時區資料的「眾所周知」位置）。在 POSIX 系統上，下游發行者和從原始碼建置 Python 且知道其系統時區資料部署位置的人，可以透過指定編譯時期選項 @code{TZPATH}（或更有可能的是使用 @ref{2026,,configure 旗標 --with-tzpath}）來變更預設時區路徑，它應該是一個由 @ref{1ffb,,os.pathsep} 分隔的字串。

在所有平台上，設定的值可以透過 @ref{174,,sysconfig.get_config_var()} 中的 @code{TZPATH} 鍵取得。

@node 環境設定,Runtime 設定,編譯時期設定,設定資料來源
@anchor{library/zoneinfo environment-configuration}@anchor{27b0}@anchor{library/zoneinfo zoneinfo-data-environment-var}@anchor{27ad}
@subsubsection 環境設定


在初始化 @ref{2027,,TZPATH} 時（無論是在引入時，或是在呼叫不帶引數的 @ref{1756,,reset_tzpath()} 時），如果環境變數 @code{PYTHONTZPATH} 存在，@code{zoneinfo} 模組將使用它來設定搜尋路徑。

@geindex 環境變數; PYTHONTZPATH
@anchor{library/zoneinfo envvar-PYTHONTZPATH}@anchor{27b1}
@deffn {環境變數} PYTHONTZPATH

這是一個由 @ref{1ffb,,os.pathsep} 分隔的字串，包含要使用的時區搜尋路徑。它必須只包含絕對路徑，而非相對路徑。在 @code{PYTHONTZPATH} 中指定的相對路徑元件將不會被使用，但除此之外，指定相對路徑時的行為是實作定義的；CPython 將引發 @ref{27b2,,InvalidTZPathWarning}，但其他實作可以自由地靜默忽略錯誤的元件或引發例外。
@end deffn

要讓系統忽略系統資料並改用 tzdata 套件，請設定 @code{PYTHONTZPATH=""}。

@node Runtime 設定,,環境設定,設定資料來源
@anchor{library/zoneinfo runtime-configuration}@anchor{27b3}@anchor{library/zoneinfo zoneinfo-data-runtime-config}@anchor{27ae}
@subsubsection Runtime 設定


TZ 搜尋路徑也可以在 Runtime 使用 @ref{1756,,reset_tzpath()} 函式進行設定。這通常不是一個建議的操作，儘管在需要使用特定時區路徑（或需要停用對系統時區的存取）的測試函式中使用它是合理的。

@node ZoneInfo 類別,函式<3>,資料來源,zoneinfo --- IANA 時區支援
@anchor{library/zoneinfo the-zoneinfo-class}@anchor{27b4}
@subsubsection @code{ZoneInfo} 類別


@geindex ZoneInfo (zoneinfo 中的類別)
@anchor{library/zoneinfo zoneinfo ZoneInfo}@anchor{ad3}
@deffn {類別} zoneinfo.ZoneInfo (key)

一個具體的 @ref{7ef,,datetime.tzinfo} 子類別，代表由字串 @code{key} 指定的 IANA 時區。對主要建構函式的呼叫將總是回傳比較結果相同的物件；換句話說，除非透過 @ref{27b5,,ZoneInfo.clear_cache()} 使快取失效，否則對於所有 @code{key} 的值，以下斷言將永遠為真：

@example
a = ZoneInfo(key)
b = ZoneInfo(key)
assert a is b
@end example

@code{key} 必須是相對、正規化的 POSIX 路徑形式，且不含上層參照。如果傳入不符合規範的鍵，建構函式將引發 @ref{2eb,,ValueError} 例外。

如果找不到符合 @code{key} 的檔案，建構函式將引發 @ref{1799,,ZoneInfoNotFoundError} 例外。
@end deffn

@code{ZoneInfo} 類別有兩個備用建構函式：

@geindex from_file() (zoneinfo.ZoneInfo 的類別方法)
@anchor{library/zoneinfo zoneinfo ZoneInfo from_file}@anchor{27b6}
@deffn {方法} classmethod ZoneInfo.from_file (file_obj, /, key=None)

從回傳位元組的類檔案物件（例如以二進位模式開啟的檔案或一個 @ref{109f,,io.BytesIO} 物件）建構一個 @code{ZoneInfo} 物件。與主要建構函式不同，這個建構函式總是會建構一個新物件。

@code{key} 參數設定了時區的名稱，用於 @ref{829,,__str__()} 和 @ref{828,,__repr__()}。

透過此建構函式建立的物件無法被封裝（參閱 @ref{27b7,,pickling}）。
@end deffn

@geindex no_cache() (zoneinfo.ZoneInfo 的類別方法)
@anchor{library/zoneinfo zoneinfo ZoneInfo no_cache}@anchor{27b8}
@deffn {方法} classmethod ZoneInfo.no_cache (key)

一個繞過建構函式快取的備用建構函式。它與主要建構函式相同，但每次呼叫都會回傳一個新物件。這對於測試或示範目的最可能有用，但它也可以用來建立一個具有不同快取失效策略的系統。

透過此建構函式建立的物件，在拆封時也會繞過去序列化過程的快取。

@c TODO: Add "See `cache_behavior`_" reference when that section is ready.

@cartouche
@quotation 警示 
使用此建構函式可能會以意想不到的方式改變你的 datetime 物件的語意，只有在你確定需要時才使用它。
@end quotation
@end cartouche
@end deffn

以下類別方法也可用：

@geindex clear_cache() (zoneinfo.ZoneInfo 的類別方法)
@anchor{library/zoneinfo zoneinfo ZoneInfo clear_cache}@anchor{27b5}
@deffn {方法} classmethod ZoneInfo.clear_cache (*, only_keys=None)

一個用於使 @code{ZoneInfo} 類別上的快取失效的方法。如果沒有傳入引數，所有快取都會失效，且下一次對每個鍵的主要建構函式呼叫都將回傳一個新的實例。

如果將一個包含鍵名的可疊代物件傳遞給 @code{only_keys} 參數，則只有指定的鍵會從快取中移除。傳遞給 @code{only_keys} 但在快取中找不到的鍵會被忽略。

@c TODO: Add "See `cache_behavior`_" reference when that section is ready.

@cartouche
@quotation 警告 
呼叫此函式可能會以意想不到的方式改變使用 @code{ZoneInfo} 的 datetime 物件的語意；這會修改模組狀態，因此可能產生廣泛的影響。只有在你確定需要時才使用它。
@end quotation
@end cartouche
@end deffn

該類別有一個屬性：

@geindex key (zoneinfo.ZoneInfo 的屬性)
@anchor{library/zoneinfo zoneinfo ZoneInfo key}@anchor{27b9}
@deffn {屬性} ZoneInfo.key

這是一個唯讀 @ref{27ba,,屬性}，它回傳傳遞給建構函式的 @code{key} 值，該值應為 IANA 時區資料庫中的查詢鍵（例如 @code{America/New_York}、@code{Europe/Paris} 或 @code{Asia/Tokyo}）。

對於從檔案建構且未指定 @code{key} 參數的時區，此屬性將被設定為 @code{None}。

@cartouche
@quotation 備註 
雖然將這些值暴露給終端使用者是一種相當普遍的做法，但這些值被設計為表示相關時區的主鍵，而不一定是面向使用者的元素。像 CLDR（Unicode 通用地區資料儲存庫）這樣的專案可以用來從這些鍵中取得更友善的使用者字串。
@end quotation
@end cartouche
@end deffn

@menu
* 字串表示:: 
* 封裝（Pickle）序列化:: 

@end menu

@node 字串表示,封裝（Pickle）序列化,,ZoneInfo 類別
@anchor{library/zoneinfo string-representations}@anchor{27bb}
@subsubsection 字串表示


在 @ref{ad3,,ZoneInfo} 物件上呼叫 @ref{169,,str} 時回傳的字串表示，預設使用 @ref{27b9,,ZoneInfo.key} 屬性（參閱屬性文件中的使用說明）：

@example
>>> zone = ZoneInfo("Pacific/Kwajalein")
>>> str(zone)
'Pacific/Kwajalein'

>>> dt = datetime(2020, 4, 1, 3, 15, tzinfo=zone)
>>> f"@{dt.isoformat()@} [@{dt.tzinfo@}]"
'2020-04-01T03:15:00+12:00 [Pacific/Kwajalein]'
@end example

對於從檔案建構且未指定 @code{key} 參數的物件，@code{str} 會轉而呼叫 @ref{1c1,,repr()}。@code{ZoneInfo} 的 @code{repr} 是實作定義的，且不保證在不同版本之間保持穩定，但保證它不會是一個有效的 @code{ZoneInfo} 鍵。

@node 封裝（Pickle）序列化,,字串表示,ZoneInfo 類別
@anchor{library/zoneinfo pickle-serialization}@anchor{27bc}@anchor{library/zoneinfo pickling}@anchor{27b7}
@subsubsection 封裝（Pickle）序列化


@code{ZoneInfo} 物件不是序列化所有轉換資料，而是按鍵進行序列化，而從檔案建構的 @code{ZoneInfo} 物件（即使是那些指定了 @code{key} 值的物件）也無法被封裝。

@code{ZoneInfo} 檔案的行為取決於它的建構方式：


@enumerate 

@item 
@code{ZoneInfo(key)}：當使用主要建構函式建構時，@code{ZoneInfo} 物件會按鍵序列化，而在去序列化時，去序列化過程會使用主要建構函式，因此這些物件會與指向相同時區的其他參照是同一個物件。例如，如果 @code{europe_berlin_pkl} 是一個包含從 @code{ZoneInfo("Europe/Berlin")} 建構並封裝的字串，會預期以下行為：

@example
>>> a = ZoneInfo("Europe/Berlin")
>>> b = pickle.loads(europe_berlin_pkl)
>>> a is b
True
@end example

@item 
@code{ZoneInfo.no_cache(key)}：當從繞過快取的建構函式建構時，@code{ZoneInfo} 物件也會按鍵序列化，但在去序列化時，去序列化過程會使用繞過快取的建構函式。如果 @code{europe_berlin_pkl_nc} 是一個包含從 @code{ZoneInfo.no_cache("Europe/Berlin")} 建構並封裝的字串，會預期以下行為：

@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)}：當從檔案建構時，@code{ZoneInfo} 物件在封裝時會引發例外。如果終端使用者想要封裝一個從檔案建構的 @code{ZoneInfo}，建議他們使用包裝器型別或自訂序列化函式：可以按鍵序列化，或儲存檔案物件的內容並將其序列化。
@end enumerate

這種序列化方法要求所需鍵的時區資料在序列化和去序列化兩端都可用，這與對類別和函式的參照預期存在於序列化和去序列化環境中的方式相似。這也意味著，當在具有不同版本時區資料的環境中拆封一個封裝的 @code{ZoneInfo} 時，不保證結果的一致性。

@node 函式<3>,全域變數,ZoneInfo 類別,zoneinfo --- IANA 時區支援
@anchor{library/zoneinfo functions}@anchor{27bd}
@subsubsection 函式


@geindex available_timezones() (於 zoneinfo 模組中)
@anchor{library/zoneinfo zoneinfo available_timezones}@anchor{1c11}
@deffn {函式} zoneinfo.available_timezones ()

取得一個集合，其中包含時區路徑上任何地方可用的所有 IANA 時區的有效鍵。這會在每次呼叫函式時重新計算。

此函式僅包含規範的時區名稱，不包含「特殊」時區，例如 @code{posix/} 和 @code{right/} 目錄下的時區，或 @code{posixrules} 時區。

@cartouche
@quotation 警示 
此函式可能會開啟大量檔案，因為確定時區路徑上的檔案是否為有效時區的最佳方法是讀取開頭的「魔術字串」。
@end quotation
@end cartouche

@cartouche
@quotation 備註 
這些值並非設計來暴露給終端使用者；對於面向使用者的元素，應用程式應使用像 CLDR（Unicode 通用地區資料儲存庫）這樣的工具來取得更友善的使用者字串。另請參閱關於 @ref{27b9,,ZoneInfo.key} 的警示說明。
@end quotation
@end cartouche
@end deffn

@geindex reset_tzpath() (於 zoneinfo 模組中)
@anchor{library/zoneinfo zoneinfo reset_tzpath}@anchor{1756}
@deffn {函式} zoneinfo.reset_tzpath (to=None)

為模組設定或重設時區搜尋路徑（@ref{2027,,TZPATH}）。當不帶引數呼叫時，@ref{2027,,TZPATH} 會被設定為預設值。

呼叫 @code{reset_tzpath} 不會使 @ref{ad3,,ZoneInfo} 快取失效，因此對主要 @code{ZoneInfo} 建構函式的呼叫只會在快取未命中時才使用新的 @code{TZPATH}。

@code{to} 參數必須是一個由字串或 @ref{e46,,os.PathLike} 組成的 @ref{70f,,序列}，而不是一個字串，其中所有元素都必須是絕對路徑。如果傳入的不是絕對路徑，將會引發 @ref{2eb,,ValueError} 例外。
@end deffn

@node 全域變數,例外與警告,函式<3>,zoneinfo --- IANA 時區支援
@anchor{library/zoneinfo globals}@anchor{27be}
@subsubsection 全域變數


@geindex TZPATH (於 zoneinfo 模組中)
@anchor{library/zoneinfo zoneinfo TZPATH}@anchor{2027}
@deffn {資料} zoneinfo.TZPATH

一個表示時區搜尋路徑的唯讀序列 —— 當從一個鍵建構 @code{ZoneInfo} 時，該鍵會與 @code{TZPATH} 中的每個條目結合，並使用找到的第一個檔案。

@code{TZPATH} 只能包含絕對路徑，絕不能包含相對路徑，無論如何設定。

@code{zoneinfo.TZPATH} 指向的物件可能會因應對 @ref{1756,,reset_tzpath()} 的呼叫而改變，因此建議使用 @code{zoneinfo.TZPATH}，而不是從 @code{zoneinfo} 引入 @code{TZPATH} 或將一個長生命週期的變數賦值給 @code{zoneinfo.TZPATH}。

有關設定時區搜尋路徑的更多資訊，請參閱 @ref{27ac,,設定資料來源}。
@end deffn

@node 例外與警告,,全域變數,zoneinfo --- IANA 時區支援
@anchor{library/zoneinfo exceptions-and-warnings}@anchor{27bf}
@subsubsection 例外與警告


@geindex ZoneInfoNotFoundError
@anchor{library/zoneinfo zoneinfo ZoneInfoNotFoundError}@anchor{1799}
@deffn {例外} zoneinfo.ZoneInfoNotFoundError

當建構 @ref{ad3,,ZoneInfo} 物件因在系統上找不到指定的鍵而失敗時引發。這是 @ref{5df,,KeyError} 的一個子類別。
@end deffn

@geindex InvalidTZPathWarning
@anchor{library/zoneinfo zoneinfo InvalidTZPathWarning}@anchor{27b2}
@deffn {例外} zoneinfo.InvalidTZPathWarning

當 
@geindex PYTHONTZPATH
@geindex 環境變數; PYTHONTZPATH
@ref{27b1,,PYTHONTZPATH} 包含將被過濾掉的無效元件（例如相對路徑）時引發。
@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 --- 日曆相關函式,collections --- 容器資料型態,zoneinfo --- IANA 時區支援,資料型別
@anchor{library/calendar doc}@anchor{27c0}@anchor{library/calendar calendar-general-calendar-related-functions}@anchor{27c1}@anchor{library/calendar module-calendar}@anchor{15}@anchor{library/calendar translation-repo}@anchor{27c2}
@subsection @code{calendar} --- 日曆相關函式


@geindex module; calendar

`原始碼：'Lib/calendar.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/calendar.py}


__________________________________________________________________


這個模組讓你可以像 Unix 的 @code{cal} 程式一樣輸出日曆，並額外提供有用的日曆相關函式。這些日曆預設把週一當作一週的第一天，而週日當作最後一天（歐洲的慣例）。可以使用 @ref{27c3,,setfirstweekday()} 設定一週的第一天為週日 (6) 或一週的其它任一天，其中指定日期的參數是整數。相關功能參考 @ref{34,,datetime} 和 @ref{f4,,time} 模組。

這個模組定義的函式和類別使用理想化的日曆，也就是公曆 (Gregorian calendar) 無限往前後兩個方向延伸。這符合 Dershowitz 和 Reingold 在「Calendrical Calculations」這本書定義的「逆推公曆」(proleptic Gregorian)，是做所有計算的基礎日曆。0 及負數年份的解讀跟 ISO 8601 標準裡規定的一樣，0 年是公元前 1 年，-1 年是公元前 2 年依此類推。

@geindex Calendar (calendar 中的類別)
@anchor{library/calendar calendar Calendar}@anchor{27c4}
@deffn {類別} calendar.Calendar (firstweekday=0)

建立 @ref{27c4,,Calendar} 物件。`firstweekday' 是一個指定一週第一天的整數，@ref{27c5,,MONDAY} 是 @code{0}（預設值），@ref{27c6,,SUNDAY} 是 @code{6}。

@ref{27c4,,Calendar} 物件提供一些方法來為日曆資料的格式化做準備。這個類別本身不做任何格式化，這是子類別的工作。

@ref{27c4,,Calendar} 實例有以下方法與屬性：

@geindex firstweekday (calendar.Calendar 的屬性)
@anchor{library/calendar calendar Calendar firstweekday}@anchor{27c7}
@deffn {屬性} firstweekday

The first weekday as an integer (0--6).

This property can also be set and read using
@ref{27c8,,setfirstweekday()} and
@ref{27c9,,getfirstweekday()} respectively.
@end deffn

@geindex getfirstweekday() (calendar.Calendar 的方法)
@anchor{library/calendar calendar Calendar getfirstweekday}@anchor{27c9}
@deffn {方法} getfirstweekday ()

Return an @ref{19b,,int} for the current first weekday (0--6).

Identical to reading the @ref{27c7,,firstweekday} property.
@end deffn

@geindex setfirstweekday() (calendar.Calendar 的方法)
@anchor{library/calendar calendar Calendar setfirstweekday}@anchor{27c8}
@deffn {方法} setfirstweekday (firstweekday)

Set the first weekday to `firstweekday', passed as an @ref{19b,,int} (0--6)

Identical to setting the @ref{27c7,,firstweekday} property.
@end deffn

@geindex iterweekdays() (calendar.Calendar 的方法)
@anchor{library/calendar calendar Calendar iterweekdays}@anchor{27ca}
@deffn {方法} iterweekdays ()

回傳一個以數字代表一週的每一天的疊代器 (iterator)。疊代器的第一個值和 @ref{27c7,,firstweekday} 屬性的值一樣。
@end deffn

@geindex itermonthdates() (calendar.Calendar 的方法)
@anchor{library/calendar calendar Calendar itermonthdates}@anchor{e0e}
@deffn {方法} itermonthdates (year, month)

回傳一個在 `year' 年 `month' (1--12) 月的疊代器。這個疊代器會回傳該月的所有日期（@ref{1fa,,datetime.date} 物件）以及在該月之前及之後用來組成完整一週的日期。
@end deffn

@geindex itermonthdays() (calendar.Calendar 的方法)
@anchor{library/calendar calendar Calendar itermonthdays}@anchor{27cb}
@deffn {方法} itermonthdays (year, month)

類似 @ref{e0e,,itermonthdates()}，回傳一個在 `year' 年 `month' 月的疊代器，但不受限於 @ref{1fa,,datetime.date} 的範圍。回傳的日期單純是該月當日的數字，對於該月之外的日期數字會是 @code{0}。
@end deffn

@geindex itermonthdays2() (calendar.Calendar 的方法)
@anchor{library/calendar calendar Calendar itermonthdays2}@anchor{27cc}
@deffn {方法} itermonthdays2 (year, month)

類似 @ref{e0e,,itermonthdates()}，回傳一個在 `year' 年 `month' 月的疊代器，但不受限於 @ref{1fa,,datetime.date} 的範圍。回傳的日期是一個由該月當日的數字及代表週幾的數字組成的元組。
@end deffn

@geindex itermonthdays3() (calendar.Calendar 的方法)
@anchor{library/calendar calendar Calendar itermonthdays3}@anchor{e0f}
@deffn {方法} itermonthdays3 (year, month)

類似 @ref{e0e,,itermonthdates()}，回傳一個在 `year' 年 `month' 月的疊代器，但不受限於 @ref{1fa,,datetime.date} 的範圍。回傳的日期是一個由年、月、日的數字組成的元組。


在 3.7 版被加入.

@end deffn

@geindex itermonthdays4() (calendar.Calendar 的方法)
@anchor{library/calendar calendar Calendar itermonthdays4}@anchor{e10}
@deffn {方法} itermonthdays4 (year, month)

類似 @ref{e0e,,itermonthdates()}，回傳一個在 `year' 年 `month' 月的疊代器，但不受限於 @ref{1fa,,datetime.date} 的範圍。回傳的日期是一個由年、月、日及代表週幾的數字組成的元組。


在 3.7 版被加入.

@end deffn

@geindex monthdatescalendar() (calendar.Calendar 的方法)
@anchor{library/calendar calendar Calendar monthdatescalendar}@anchor{27cd}
@deffn {方法} monthdatescalendar (year, month)

回傳一個在 `year' 年 `month' 月每一週組成的串列。每一週是一個串列，包含七個 @ref{1fa,,datetime.date} 物件。
@end deffn

@geindex monthdays2calendar() (calendar.Calendar 的方法)
@anchor{library/calendar calendar Calendar monthdays2calendar}@anchor{27ce}
@deffn {方法} monthdays2calendar (year, month)

回傳一個在 `year' 年 `month' 月每一週組成的串列。每一週是一個串列，包含七個該月當日的數字及代表週幾的數字組成的元組。
@end deffn

@geindex monthdayscalendar() (calendar.Calendar 的方法)
@anchor{library/calendar calendar Calendar monthdayscalendar}@anchor{27cf}
@deffn {方法} monthdayscalendar (year, month)

回傳一個在 `year' 年 `month' 月每一週組成的串列。每一週是一個串列，包含七個該月當日的數字。
@end deffn

@geindex yeardatescalendar() (calendar.Calendar 的方法)
@anchor{library/calendar calendar Calendar yeardatescalendar}@anchor{27d0}
@deffn {方法} yeardatescalendar (year, width=3)

回傳用來格式化的指定年份的資料。回傳值是月份列的串列，每個月份列最多由 `width' 個月份組成（預設為 3）。每個月份包含四到六週，每一週包含一到七天，每一天則是一個 @ref{1fa,,datetime.date} 物件。
@end deffn

@geindex yeardays2calendar() (calendar.Calendar 的方法)
@anchor{library/calendar calendar Calendar yeardays2calendar}@anchor{27d1}
@deffn {方法} yeardays2calendar (year, width=3)

回傳用來格式化的指定年份的資料（類似 @ref{27d0,,yeardatescalendar()}）。每一天是一個該月當日的數字及代表週幾的數字組成的元組，該月外的日期的該月當日數字為 0。
@end deffn

@geindex yeardayscalendar() (calendar.Calendar 的方法)
@anchor{library/calendar calendar Calendar yeardayscalendar}@anchor{27d2}
@deffn {方法} yeardayscalendar (year, width=3)

回傳用來格式化的指定年份的資料（類似 @ref{27d0,,yeardatescalendar()}）。每一天是一個該月當日的數字，該月外的日期的該月當日數字為 0。
@end deffn
@end deffn

@geindex TextCalendar (calendar 中的類別)
@anchor{library/calendar calendar TextCalendar}@anchor{1820}
@deffn {類別} calendar.TextCalendar (firstweekday=0)

這個類別用來產生純文字的日曆。

@ref{1820,,TextCalendar} 實例有以下方法：

@geindex formatday() (calendar.TextCalendar 的方法)
@anchor{library/calendar calendar TextCalendar formatday}@anchor{27d3}
@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{27d4}
@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{27c3,,setfirstweekday()} method.
@end deffn

@geindex formatweekday() (calendar.TextCalendar 的方法)
@anchor{library/calendar calendar TextCalendar formatweekday}@anchor{27d5}
@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{27d6}
@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{27d7}
@deffn {方法} formatmonth (theyear, themonth, w=0, l=0)

以多行字串的形式回傳一個月份的日曆。如果給定 `w'，它會指定置中的日期欄的寬度。如果給定 `l'，它會指定每一週使用的行數。這個日曆會依據在建構函式中指定或者透過 @ref{27c3,,setfirstweekday()} 方法設定的一週的第一天來輸出。
@end deffn

@geindex formatmonthname() (calendar.TextCalendar 的方法)
@anchor{library/calendar calendar TextCalendar formatmonthname}@anchor{27d8}
@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{27d9}
@deffn {方法} prmonth (theyear, themonth, w=0, l=0)

印出一個月份的日曆，內容和 @ref{27d7,,formatmonth()} 回傳的一樣。
@end deffn

@geindex formatyear() (calendar.TextCalendar 的方法)
@anchor{library/calendar calendar TextCalendar formatyear}@anchor{27da}
@deffn {方法} formatyear (theyear, w=2, l=1, c=6, m=3)

以多行字串的形式回傳有 `m' 欄的一整年的日曆。可選的參數 `w'、`l' 及 `c' 分別是日期欄寬度、每週行數及月份欄中間的空白數。這個日曆會依據在建構函式中指定或者透過 @ref{27c3,,setfirstweekday()} 方法設定的一週的第一天來輸出。最早可以產生日曆的年份會依據平台而不同。
@end deffn

@geindex pryear() (calendar.TextCalendar 的方法)
@anchor{library/calendar calendar TextCalendar pryear}@anchor{27db}
@deffn {方法} pryear (theyear, w=2, l=1, c=6, m=3)

印出一整年的日曆，內容和 @ref{27da,,formatyear()} 回傳的一樣。
@end deffn
@end deffn

@geindex HTMLCalendar (calendar 中的類別)
@anchor{library/calendar calendar HTMLCalendar}@anchor{d10}
@deffn {類別} calendar.HTMLCalendar (firstweekday=0)

這個類別用來產生 HTML 日曆。

@code{HTMLCalendar} 實例有以下方法：

@geindex formatmonth() (calendar.HTMLCalendar 的方法)
@anchor{library/calendar calendar HTMLCalendar formatmonth}@anchor{27dc}
@deffn {方法} formatmonth (theyear, themonth, withyear=True)

以 HTML 表格的形式回傳一個月份的日曆。如果 `withyear' 是 true 則標題會包含年份，否則只會有月份名稱。
@end deffn

@geindex formatyear() (calendar.HTMLCalendar 的方法)
@anchor{library/calendar calendar HTMLCalendar formatyear}@anchor{27dd}
@deffn {方法} formatyear (theyear, width=3)

以 HTML 表格的形式回傳一整年的日曆。`width'（預設為 3）指定一列有幾個月。
@end deffn

@geindex formatyearpage() (calendar.HTMLCalendar 的方法)
@anchor{library/calendar calendar HTMLCalendar formatyearpage}@anchor{27de}
@deffn {方法} formatyearpage (theyear, width=3, css='calendar.css', encoding=None)

以完整 HTML 頁面的形式回傳一整年的日曆。`width'（預設為 3）指定一列有幾個月。`css' 是要使用的 CSS (cascading style sheet) 名稱，可以給 @ref{87e,,None} 表示不使用任何 CSS。`encoding' 指定輸出使用的編碼（預設使用系統預設編碼）。
@end deffn

@geindex formatmonthname() (calendar.HTMLCalendar 的方法)
@anchor{library/calendar calendar HTMLCalendar formatmonthname}@anchor{27df}
@deffn {方法} formatmonthname (theyear, themonth, withyear=True)

以 HTML 表列的形式回傳一個月份的名稱。如果 `withyear' 是 true 則該列會包含年份，否則只會有月份名稱。
@end deffn

@code{HTMLCalendar} 可以覆寫以下屬性來客製日曆所使用的 CSS 類別：

@geindex cssclasses (calendar.HTMLCalendar 的屬性)
@anchor{library/calendar calendar HTMLCalendar cssclasses}@anchor{27e0}
@deffn {屬性} cssclasses

對應一週每一天 CSS 類別的串列。預設的串列內容為：

@example
cssclasses = ["mon", "tue", "wed", "thu", "fri", "sat", "sun"]
@end example

可以針對每一天增加更多樣式：

@example
cssclasses = ["mon text-bold", "tue", "wed", "thu", "fri", "sat", "sun red"]
@end example

注意這個串列的長度必須是七個項目。
@end deffn

@geindex cssclass_noday (calendar.HTMLCalendar 的屬性)
@anchor{library/calendar calendar HTMLCalendar cssclass_noday}@anchor{27e1}
@deffn {屬性} cssclass_noday

跟當月為同一週且屬於前一個或下一個月份的日期使用的 CSS 類別。


在 3.7 版被加入.

@end deffn

@geindex cssclasses_weekday_head (calendar.HTMLCalendar 的屬性)
@anchor{library/calendar calendar HTMLCalendar cssclasses_weekday_head}@anchor{27e2}
@deffn {屬性} cssclasses_weekday_head

在標題列中一週每一天名稱的 CSS 類別的串列。預設內容和 @ref{27e0,,cssclasses} 相同。


在 3.7 版被加入.

@end deffn

@geindex cssclass_month_head (calendar.HTMLCalendar 的屬性)
@anchor{library/calendar calendar HTMLCalendar cssclass_month_head}@anchor{27e3}
@deffn {屬性} cssclass_month_head

月份標題的 CSS 類別（由 @ref{27df,,formatmonthname()} 所使用），預設值是 @code{"month"}。


在 3.7 版被加入.

@end deffn

@geindex cssclass_month (calendar.HTMLCalendar 的屬性)
@anchor{library/calendar calendar HTMLCalendar cssclass_month}@anchor{27e4}
@deffn {屬性} cssclass_month

整個月份表格的 CSS 類別（由 @ref{27dc,,formatmonth()} 所使用），預設值是 @code{"month"}。


在 3.7 版被加入.

@end deffn

@geindex cssclass_year (calendar.HTMLCalendar 的屬性)
@anchor{library/calendar calendar HTMLCalendar cssclass_year}@anchor{27e5}
@deffn {屬性} cssclass_year

整年表格的 CSS 類別（由 @ref{27dd,,formatyear()} 所使用），預設值是 @code{"year"}。


在 3.7 版被加入.

@end deffn

@geindex cssclass_year_head (calendar.HTMLCalendar 的屬性)
@anchor{library/calendar calendar HTMLCalendar cssclass_year_head}@anchor{27e6}
@deffn {屬性} cssclass_year_head

整年表格標題的 CSS 類別（由 @ref{27dd,,formatyear()} 所使用），預設值是 @code{"year"}。


在 3.7 版被加入.

@end deffn

注意雖然上面提到的 CSS 屬性名稱是單數（例如 @code{cssclass_month}、@code{cssclass_noday}），你可以使用多個以空格隔開的 CSS 類別取代單一 CSS 類別，例如：

@example
"text-bold text-red"
@end example

以下是客製化 @code{HTMLCalendar} 的範例：

@example
class CustomHTMLCal(calendar.HTMLCalendar):
    cssclasses = [style + " text-nowrap" for style in
                  calendar.HTMLCalendar.cssclasses]
    cssclass_month_head = "text-center month-head"
    cssclass_month = "text-center month"
    cssclass_year = "text-italic lead"
@end example
@end deffn

@geindex LocaleTextCalendar (calendar 中的類別)
@anchor{library/calendar calendar LocaleTextCalendar}@anchor{943}
@deffn {類別} calendar.LocaleTextCalendar (firstweekday=0, locale=None)

@ref{1820,,TextCalendar} 的子類別，可以在建構函式傳入語系名稱，它會回傳指定語系的月份及一週每一天的名稱。
@end deffn

@geindex LocaleHTMLCalendar (calendar 中的類別)
@anchor{library/calendar calendar LocaleHTMLCalendar}@anchor{944}
@deffn {類別} calendar.LocaleHTMLCalendar (firstweekday=0, locale=None)

@ref{d10,,HTMLCalendar} 的子類別，可以在建構函式傳入語系名稱，它會回傳指定語系的月份及一週每一天的名稱。
@end deffn

@cartouche
@quotation 備註 
這兩個類別的建構函式、@code{formatweekday()} 及 @code{formatmonthname()} 方法會把 @code{LC_TIME} 語系暫時改成給定的 `locale'。因為目前的語系是屬於整個行程 (process-wide) 的設定，它們不是執行緒安全的。
@end quotation
@end cartouche

這個模組提供以下函式給單純的文字日曆使用。

@geindex setfirstweekday() (於 calendar 模組中)
@anchor{library/calendar calendar setfirstweekday}@anchor{27c3}
@deffn {函式} calendar.setfirstweekday (weekday)

設定一週的第一天（@code{0} 是週一、@code{6} 是週日）。提供 @ref{27c5,,MONDAY}、@ref{27e7,,TUESDAY}、@ref{27e8,,WEDNESDAY}、@ref{27e9,,THURSDAY}、@ref{27ea,,FRIDAY}、@ref{27eb,,SATURDAY} 及 @ref{27c6,,SUNDAY} 可以方便設定。例如設定一週的第一天為週日：

@example
import calendar
calendar.setfirstweekday(calendar.SUNDAY)
@end example
@end deffn

@geindex firstweekday() (於 calendar 模組中)
@anchor{library/calendar calendar firstweekday}@anchor{27ec}
@deffn {函式} calendar.firstweekday ()

回傳目前設定的一週的第一天。
@end deffn

@geindex isleap() (於 calendar 模組中)
@anchor{library/calendar calendar isleap}@anchor{27ed}
@deffn {函式} calendar.isleap (year)

如果 `year' 是閏年回傳 @ref{e02,,True}，否則回傳 @ref{d23,,False}。
@end deffn

@geindex leapdays() (於 calendar 模組中)
@anchor{library/calendar calendar leapdays}@anchor{27ee}
@deffn {函式} calendar.leapdays (y1, y2)

回傳從 `y1' 到 `y2'（不包含）間有幾個閏年，其中 `y1' 和 `y2' 是年份。

這個函式也適用在跨越世紀的時間範圍。
@end deffn

@geindex weekday() (於 calendar 模組中)
@anchor{library/calendar calendar weekday}@anchor{27ef}
@deffn {函式} calendar.weekday (year, month, day)

回傳 `year' 年 (@code{1970}--...) `month' 月 (@code{1}--@code{12}) `day' 日 (@code{1}--@code{31}) 是週幾（@code{0} 是星期一）。
@end deffn

@geindex weekheader() (於 calendar 模組中)
@anchor{library/calendar calendar weekheader}@anchor{27f0}
@deffn {函式} calendar.weekheader (n)

回傳包含一週每一天的名稱縮寫的標題。`n' 指定每一天的字元寬度。
@end deffn

@geindex monthrange() (於 calendar 模組中)
@anchor{library/calendar calendar monthrange}@anchor{27f1}
@deffn {函式} calendar.monthrange (year, month)

回傳指定 `year' 年 `month' 月該月第一天代表週幾的數字及該月有多少天。
@end deffn

@geindex monthcalendar() (於 calendar 模組中)
@anchor{library/calendar calendar monthcalendar}@anchor{27f2}
@deffn {函式} calendar.monthcalendar (year, month)

回傳代表一個月份日曆的矩陣。每一列為一週；該月以外的日期以 0 表示。每一週以週一開始，除非有使用 @ref{27c3,,setfirstweekday()} 改變設定。
@end deffn

@geindex prmonth() (於 calendar 模組中)
@anchor{library/calendar calendar prmonth}@anchor{27f3}
@deffn {函式} calendar.prmonth (theyear, themonth, w=0, l=0)

印出一個月份的日曆，跟 @ref{1876,,month()} 回傳的內容一樣。
@end deffn

@geindex month() (於 calendar 模組中)
@anchor{library/calendar calendar month}@anchor{1876}
@deffn {函式} calendar.month (theyear, themonth, w=0, l=0)

以多行字串的形式回傳一個月的日曆，使用 @ref{1820,,TextCalendar} 類別的 @ref{27d7,,formatmonth()}。
@end deffn

@geindex prcal() (於 calendar 模組中)
@anchor{library/calendar calendar prcal}@anchor{27f4}
@deffn {函式} calendar.prcal (year, w=0, l=0, c=6, m=3)

印出一整年的日曆，跟 @ref{15,,calendar()} 回傳的內容一樣。
@end deffn

@geindex calendar() (於 calendar 模組中)
@anchor{library/calendar calendar calendar}@anchor{27f5}
@deffn {函式} calendar.calendar (year, w=2, l=1, c=6, m=3)

以多行字串回傳三欄形式的一整年日曆，使用 @ref{1820,,TextCalendar} 類別的 @ref{27da,,formatyear()}。
@end deffn

@geindex timegm() (於 calendar 模組中)
@anchor{library/calendar calendar timegm}@anchor{27f6}
@deffn {函式} calendar.timegm (tuple)

一個跟日曆無關但方便的函式，它接受一個像 @ref{f4,,time} 模組裡的 @ref{13c1,,gmtime()} 函式回傳的元組，並回傳對應的 Unix 時間戳，假設從 1970 開始及 POSIX 編碼。事實上，@ref{13c1,,time.gmtime()} 和 @ref{27f6,,timegm()} 是彼此相反的。
@end deffn

@ref{15,,calendar} 模組匯出以下資料屬性：

@geindex day_name (於 calendar 模組中)
@anchor{library/calendar calendar day_name}@anchor{27f7}
@deffn {資料} calendar.day_name

以目前語系來表示的一週每一天名稱的序列，其中週一是第 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{27f8}
@deffn {資料} calendar.day_abbr

以目前語系來表示的一週每一天縮寫名稱的序列，其中 Mon 是第 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{27c5}
@deffn {資料} calendar.MONDAY
@anchor{library/calendar calendar TUESDAY}@anchor{27e7}
@deffnx {資料} calendar.TUESDAY
@anchor{library/calendar calendar WEDNESDAY}@anchor{27e8}
@deffnx {資料} calendar.WEDNESDAY
@anchor{library/calendar calendar THURSDAY}@anchor{27e9}
@deffnx {資料} calendar.THURSDAY
@anchor{library/calendar calendar FRIDAY}@anchor{27ea}
@deffnx {資料} calendar.FRIDAY
@anchor{library/calendar calendar SATURDAY}@anchor{27eb}
@deffnx {資料} calendar.SATURDAY
@anchor{library/calendar calendar SUNDAY}@anchor{27c6}
@deffnx {資料} calendar.SUNDAY

一週每一天的別名，其中 @code{MONDAY} 是 @code{0} 而 @code{SUNDAY} 是 @code{6}。


在 3.12 版被加入.

@end deffn

@geindex Day (calendar 中的類別)
@anchor{library/calendar calendar Day}@anchor{6a3}
@deffn {類別} calendar.Day

將一週中的幾天定義為整數常數的列舉。此列舉的成員將作為 @ref{27c5,,MONDAY} 到 @ref{27c6,,SUNDAY} 匯出到模組作用域。


在 3.12 版被加入.

@end deffn

@geindex month_name (於 calendar 模組中)
@anchor{library/calendar calendar month_name}@anchor{27f9}
@deffn {資料} calendar.month_name

以目前語系來表示的一年每個月份名稱的序列。它按照一般慣例以數字 1 代表一月，因此它的長度為 13，而 @code{month_name[0]} 是空字串。

@example
>>> import calendar
>>> list(calendar.month_name)
['@w{'}, 'January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December']
@end example
@end deffn

@geindex month_abbr (於 calendar 模組中)
@anchor{library/calendar calendar month_abbr}@anchor{27fa}
@deffn {資料} calendar.month_abbr

以目前語系來表示的一年每個月份縮寫名稱的序列。它按照一般慣例以數字 1 代表一月，因此它的長度為 13，而 @code{month_abbr[0]} 是空字串。

@example
>>> import calendar
>>> list(calendar.month_abbr)
['@w{'}, 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
@end example
@end deffn

@geindex JANUARY (於 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{34c}
@deffn {資料} calendar.JANUARY
@anchor{library/calendar calendar FEBRUARY}@anchor{34d}
@deffnx {資料} calendar.FEBRUARY
@anchor{library/calendar calendar MARCH}@anchor{27fb}
@deffnx {資料} calendar.MARCH
@anchor{library/calendar calendar APRIL}@anchor{27fc}
@deffnx {資料} calendar.APRIL
@anchor{library/calendar calendar MAY}@anchor{27fd}
@deffnx {資料} calendar.MAY
@anchor{library/calendar calendar JUNE}@anchor{27fe}
@deffnx {資料} calendar.JUNE
@anchor{library/calendar calendar JULY}@anchor{27ff}
@deffnx {資料} calendar.JULY
@anchor{library/calendar calendar AUGUST}@anchor{2800}
@deffnx {資料} calendar.AUGUST
@anchor{library/calendar calendar SEPTEMBER}@anchor{2801}
@deffnx {資料} calendar.SEPTEMBER
@anchor{library/calendar calendar OCTOBER}@anchor{2802}
@deffnx {資料} calendar.OCTOBER
@anchor{library/calendar calendar NOVEMBER}@anchor{2803}
@deffnx {資料} calendar.NOVEMBER
@anchor{library/calendar calendar DECEMBER}@anchor{2804}
@deffnx {資料} calendar.DECEMBER

一年內每個月的別名，其中 @code{JANUARY} 是 @code{1} 而 @code{DECEMBER} 是 @code{12}。


在 3.12 版被加入.

@end deffn

@geindex Month (calendar 中的類別)
@anchor{library/calendar calendar Month}@anchor{6a2}
@deffn {類別} calendar.Month

將一年中的月份定義為整數常數的列舉。此列舉的成員將作為 @ref{34c,,JANUARY} 到 @ref{2804,,DECEMBER} 匯出到模組作用域。


在 3.12 版被加入.

@end deffn

@ref{15,,calendar} 模組定義了以下例外：

@geindex IllegalMonthError
@anchor{library/calendar calendar IllegalMonthError}@anchor{1875}
@deffn {例外} calendar.IllegalMonthError (month)

@ref{2eb,,ValueError} 的子類別，當給定的月份數字超出 1-12 範圍（含）時引發。

@geindex month (calendar.IllegalMonthError 的屬性)
@anchor{library/calendar calendar IllegalMonthError month}@anchor{2805}
@deffn {屬性} month

無效的月份號。
@end deffn
@end deffn

@geindex IllegalWeekdayError
@anchor{library/calendar calendar IllegalWeekdayError}@anchor{2806}
@deffn {例外} calendar.IllegalWeekdayError (weekday)

@ref{2eb,,ValueError} 的子類別，當給定的週幾的數字超出 0-6（含）範圍時引發。

@geindex weekday (calendar.IllegalWeekdayError 的屬性)
@anchor{library/calendar calendar IllegalWeekdayError weekday}@anchor{2807}
@deffn {屬性} weekday

無效的週幾編號。
@end deffn
@end deffn


@subsubheading 也參考



@table @asis

@item @ref{34,,datetime} 模組

日期與時間的物件導向介面，和 @ref{f4,,time} 模組有相似的功能。

@item @ref{f4,,time} 模組

底層的時間相關函式。
@end table


@menu
* 命令列用法:: 

@end menu

@node 命令列用法,,,calendar --- 日曆相關函式
@anchor{library/calendar calendar-cli}@anchor{1d0}@anchor{library/calendar command-line-usage}@anchor{2808}
@subsubsection 命令列用法



在 2.5 版被加入.


@ref{15,,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

例如，要列印 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

接受以下選項：

@geindex calendar 命令列選項; --help
@geindex calendar 命令列選項; -h
@anchor{library/calendar cmdoption-calendar-help}@anchor{2809}@anchor{library/calendar cmdoption-calendar-h}@anchor{280a}
@deffn {Option} @w{-}@w{-}help, @w{-}h

顯示幫助訊息並退出。
@end deffn

@geindex calendar 命令列選項; --locale
@geindex calendar 命令列選項; -L
@anchor{library/calendar cmdoption-calendar-locale}@anchor{280b}@anchor{library/calendar cmdoption-calendar-L}@anchor{280c}
@deffn {Option} @w{-}@w{-}locale LOCALE, @w{-}L LOCALE

用於月份和週幾名稱的語系。預設為英語。
@end deffn

@geindex calendar 命令列選項; --encoding
@geindex calendar 命令列選項; -e
@anchor{library/calendar cmdoption-calendar-encoding}@anchor{280d}@anchor{library/calendar cmdoption-calendar-e}@anchor{280e}
@deffn {Option} @w{-}@w{-}encoding ENCODING, @w{-}e ENCODING

用於輸出的編碼。如有設定 @ref{280b,,--locale} 則必須給定 @ref{280d,,--encoding}。
@end deffn

@geindex calendar 命令列選項; --type
@geindex calendar 命令列選項; -t
@anchor{library/calendar cmdoption-calendar-type}@anchor{280f}@anchor{library/calendar cmdoption-calendar-t}@anchor{2810}
@deffn {Option} @w{-}@w{-}type @{text,html@}, @w{-}t @{text,html@}

將日曆以文字或 HTML 文件的形式印出到終端機。
@end deffn

@geindex calendar 命令列選項; --first-weekday
@geindex calendar 命令列選項; -f
@anchor{library/calendar cmdoption-calendar-first-weekday}@anchor{2811}@anchor{library/calendar cmdoption-calendar-f}@anchor{2812}
@deffn {Option} @w{-}@w{-}first@w{-}weekday FIRST_WEEKDAY, @w{-}f FIRST_WEEKDAY

一週起始的日子。必須是 0（週一）到 6（週日）之間的數字。預設為 0。


在 3.13 版被加入.

@end deffn

@geindex calendar 命令列選項; year
@anchor{library/calendar cmdoption-calendar-arg-year}@anchor{2813}
@deffn {Option} year

印出日曆的年份。預設為目前年份。
@end deffn

@geindex calendar 命令列選項; month
@anchor{library/calendar cmdoption-calendar-arg-month}@anchor{2814}
@deffn {Option} month

要列印日曆的指定 @ref{2813,,year} 的月份。必須是 1 到 12 之間的數字，並且只能在文字模式下使用。預設列印全年日曆。
@end deffn

`文字模式選項：'

@geindex calendar 命令列選項; --width
@geindex calendar 命令列選項; -w
@anchor{library/calendar cmdoption-calendar-width}@anchor{2815}@anchor{library/calendar cmdoption-calendar-w}@anchor{2816}
@deffn {Option} @w{-}@w{-}width WIDTH, @w{-}w WIDTH

終端機行中日期行的寬度。日期印出在行的中央。任何小於 2 的值都會被忽略。預設為 2。
@end deffn

@geindex calendar 命令列選項; --lines
@geindex calendar 命令列選項; -l
@anchor{library/calendar cmdoption-calendar-lines}@anchor{2817}@anchor{library/calendar cmdoption-calendar-l}@anchor{2818}
@deffn {Option} @w{-}@w{-}lines LINES, @w{-}l LINES

終端機列中每週的列數。日期印出時頂部會對齊。任何小於 1 的值都會被忽略。預設為 1。
@end deffn

@geindex calendar 命令列選項; --spacing
@geindex calendar 命令列選項; -s
@anchor{library/calendar cmdoption-calendar-spacing}@anchor{2819}@anchor{library/calendar cmdoption-calendar-s}@anchor{281a}
@deffn {Option} @w{-}@w{-}spacing SPACING, @w{-}s SPACING

行中月份之間的間距。任何小於 2 的值都會被忽略。預設為 6。
@end deffn

@geindex calendar 命令列選項; --months
@geindex calendar 命令列選項; -m
@anchor{library/calendar cmdoption-calendar-months}@anchor{281b}@anchor{library/calendar cmdoption-calendar-m}@anchor{281c}
@deffn {Option} @w{-}@w{-}months MONTHS, @w{-}m MONTHS

每列印出的月份數量。預設為 3。
@end deffn


在 3.14 版的變更: By default, today's date is highlighted in color and can be
@ref{1b7,,controlled using environment variables}.


`HTML 模式選項：'

@geindex calendar 命令列選項; --css
@geindex calendar 命令列選項; -c
@anchor{library/calendar cmdoption-calendar-css}@anchor{281d}@anchor{library/calendar cmdoption-calendar-c}@anchor{281e}
@deffn {Option} @w{-}@w{-}css CSS, @w{-}c CSS

用於日曆的 CSS 樣式表路徑。這必須是相對於產生之 HTML 的，或者為絕對的 HTTP 或 @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 --- 容器資料型態,collections abc --- 容器的抽象基底類別,calendar --- 日曆相關函式,資料型別
@anchor{library/collections doc}@anchor{281f}@anchor{library/collections collections-container-datatypes}@anchor{2820}@anchor{library/collections module-collections}@anchor{1e}@anchor{library/collections translation-repo}@anchor{2821}
@subsection @code{collections} --- 容器資料型態


@geindex module; collections

`原始碼：'Lib/collections/__init__.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/collections/__init__.py}

@c from collections import *
@c import itertools
@c __name__ = '<doctest>'


__________________________________________________________________


這個模組實作了一些特別的容器資料型態，用來替代 Python 一般內建的容器，例如 @ref{183,,dict}（字典）、@ref{24d,,list}（串列）、@ref{184,,set}（集合）和 @ref{60c,,tuple}（元組）。


@multitable {xxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{4db,,namedtuple()}

@tab

用來建立具名欄位的 tuple 子類別的工廠函式

@item

@ref{7ed,,deque}

@tab

一個類似 list 的容器，可以快速的在頭尾加入 (append) 元素與移除 (pop) 元素

@item

@ref{e11,,ChainMap}

@tab

一個類似 dict 的類別，用來為多個對映 (mapping) 建立單一的視圖 (view)

@item

@ref{1292,,Counter}

@tab

dict 的子類別，用來計算@ref{81d,,可雜湊}物件的數量

@item

@ref{7ec,,OrderedDict}

@tab

dict 的子類別，會記錄物件被加入的順序

@item

@ref{13bd,,defaultdict}

@tab

dict 的子類別，當值不存在 dict 中時會呼叫一個提供預設值的工廠函式

@item

@ref{1c46,,UserDict}

@tab

dict 物件的包裝器 (wrapper)，簡化了 dict 的子類別化過程

@item

@ref{16d8,,UserList}

@tab

list 物件的包裝器，簡化了 list 的子類別化過程

@item

@ref{fce,,UserString}

@tab

字串物件的包裝器，簡化了字串的子類別化過程

@end multitable


@menu
* ChainMap 物件:: 
* Counter 物件:: 
* deque 物件:: 
* defaultdict 物件:: 
* namedtuple() 擁有具名欄位之 tuple 的工廠函式: namedtuple 擁有具名欄位之 tuple 的工廠函式. 
* OrderedDict 物件:: 
* UserDict 物件:: 
* UserList 物件:: 
* UserString 物件:: 

@end menu

@node ChainMap 物件,Counter 物件,,collections --- 容器資料型態
@anchor{library/collections chainmap-objects}@anchor{2822}
@subsubsection @code{ChainMap} 物件



在 3.3 版被加入.


@ref{e11,,ChainMap}（對映鏈結）類別的目的是快速將數個對映連結在一起，讓它們可以被當作一個單元來處理。它通常會比建立一個新的字典並多次呼叫 @ref{165a,,update()} 來得更快。

這個類別可用於模擬巢狀作用域 (nested scopes)，且在模板化 (templating) 時能派上用場。

@geindex ChainMap (collections 中的類別)
@anchor{library/collections collections ChainMap}@anchor{e11}
@deffn {類別} collections.ChainMap (*maps)

一個 @ref{e11,,ChainMap} 將多個 dict 或其他對映組合在一起，建立一個獨立、可更新的視圖。如果沒有指定 `maps'，預設會提供一個空字典讓每個新鏈結都至少有一個對映。

底層的對映儲存於一個 list 中，這個 list 是公開的且可透過 `maps' 屬性存取或更新，沒有其他狀態 (state)。

檢索 (lookup) 陸續查詢底層對映，直到鍵被找到，然而讀取、更新和刪除就只會對第一個對映操作。

@ref{e11,,ChainMap} 透過參照將底層對映合併，所以當一個底層對映被更新，這些改變也會反映到 @ref{e11,,ChainMap}。

所有常見的字典方法都有支援。此外，還有一個 `maps' 屬性 (attribute)、一個建立子上下文 (subcontext) 的方法、和一個能夠存取除了第一個以外其他所有對映的特性 (property)：

@geindex maps (collections.ChainMap 的屬性)
@anchor{library/collections collections ChainMap maps}@anchor{2823}
@deffn {屬性} maps

一個可被更新的對映列表，這個列表是按照被搜尋的順序來排列，在 ChainMap 中它是唯一被儲存的狀態，可被修改來變換搜尋順序。回傳的列表都至少包含一個對映。
@end deffn

@geindex new_child() (collections.ChainMap 的方法)
@anchor{library/collections collections ChainMap new_child}@anchor{1120}
@deffn {方法} new_child (m=None, **kwargs)

回傳包含一個新對映的 @ref{e11,,ChainMap}， 新對映後面接著目前實例的所有現存對映。如果有給定 @code{m}，@code{m} 會成為那個最前面的新對映；若沒有指定，則會加上一個空 dict，如此一來呼叫 @code{d.new_child()} 就等同於 @code{ChainMap(@{@}, *d.maps)}。這個方法用於建立子上下文，而保持父對映的不變。


在 3.4 版的變更: 加入可選參數 @code{m}。



在 3.10 版的變更: 增加了對關鍵字引數的支援。

@end deffn

@geindex parents (collections.ChainMap 的屬性)
@anchor{library/collections collections ChainMap parents}@anchor{2824}
@deffn {屬性} parents

回傳一個包含除了第一個以外所有其他對映的新 @ref{e11,,ChainMap} 的特性，可用於需要跳過第一個對映的搜尋。使用情境類似於在@ref{223e,,巢狀作用域}當中使用 @ref{14a8,,nonlocal} 關鍵字，也可與內建函式 @ref{1a6,,super()} 做類比。引用 @code{d.parents} 等同於 @code{ChainMap(*d.maps[1:])}。
@end deffn

注意，一個 @ref{e11,,ChainMap} 的疊代順序是透過由後往前掃描對映而定：

@example
>>> baseline = @{'music': 'bach', 'art': 'rembrandt'@}
>>> adjustments = @{'art': 'van gogh', 'opera': 'carmen'@}
>>> list(ChainMap(adjustments, baseline))
['music', 'art', 'opera']
@end example

這和呼叫 @ref{165a,,dict.update()} 結果的順序一樣是從最後一個對映開始：

@example
>>> combined = baseline.copy()
>>> combined.update(adjustments)
>>> list(combined)
['music', 'art', 'opera']
@end example


在 3.9 版的變更: 支援 @code{|} 和 @code{|=} 運算子，詳見 
@geindex Python Enhancement Proposals; PEP 584
PEP 584@footnote{https://peps.python.org/pep-0584/}。

@end deffn


@subsubheading 也參考



@itemize *

@item 
Enthought CodeTools package@footnote{https://github.com/enthought/codetools} 中的 MultiContext class@footnote{https://github.com/enthought/codetools/blob/4.0.0/codetools/contexts/multi_context.py} 支援在鏈中選定任意對映寫入。

@item 
Django 中用於模板的 Context class@footnote{https://github.com/django/django/blob/main/django/template/context.py}  是唯讀的對映鏈，也具有加入 (push) 和移除 (pop) 上下文的功能，與 @ref{1120,,new_child()} 方法和 @ref{2824,,parents} 特性類似。

@item 
Nested Contexts recipe@footnote{https://code.activestate.com/recipes/577434-nested-contexts-a-chain-of-mapping-objects/} 提供了控制是否只對鏈中第一個或其他對映做寫入或其他操作的選項。

@item 
一個極度簡化、維讀版本的 Chainmap@footnote{https://code.activestate.com/recipes/305268/}。
@end itemize


@menu
* ChainMap 範例和用法:: 

@end menu

@node ChainMap 範例和用法,,,ChainMap 物件
@anchor{library/collections chainmap-examples-and-recipes}@anchor{2825}
@subsubsection @code{ChainMap} 範例和用法


此章節提供了多種操作 ChainMap 的案例。

模擬 Python 內部檢索鏈結的例子：

@example
import builtins
pylookup = ChainMap(locals(), globals(), vars(builtins))
@end example

讓使用者指定的命令列引數優先於環境變數、再優先於預設值的範例：

@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

用 @ref{e11,,ChainMap} 類別模擬巢狀上下文的範例模式：

@example
c = ChainMap()        # Create root context
d = c.new_child()     # Create nested child context
e = c.new_child()     # Child of c, independent from d
e.maps[0]             # Current context dictionary -- like Python's locals()
e.maps[-1]            # Root context -- like Python's globals()
e.parents             # Enclosing context chain -- like Python's nonlocals

d['x'] = 1            # Set value in current context
d['x']                # Get first key in the chain of contexts
del d['x']            # Delete from current context
list(d)               # All nested values
k in d                # Check all nested values
len(d)                # Number of nested values
d.items()             # All nested items
dict(d)               # Flatten into a regular dictionary
@end example

@ref{e11,,ChainMap} 類別只對鏈結中第一個對映來做寫入或刪除，但檢索則會掃過整個鏈結。但如果需要對更深層的鍵寫入或刪除，透過定義一個子類別來實作也不困難：

@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 物件,deque 物件,ChainMap 物件,collections --- 容器資料型態
@anchor{library/collections counter-objects}@anchor{2826}
@subsubsection @code{Counter} 物件


提供一個支援方便且快速計數的計數器工具，例如：

@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{1292}
@deffn {類別} collections.Counter ([iterable-or-mapping])

@ref{1292,,Counter} 是 @ref{183,,dict} 的子類別，用來計算@ref{81d,,可雜湊}物件的數量。它是將物件與其計數作為字典的鍵值對儲存的集合容器。計數可以是包含 0 與負數的任何整數值。@ref{1292,,Counter} 類別類似其他程式語言中的 bags 或 multisets。

被計數的元素來自一個 `iterable' 或是被其他的 `mapping'（或 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 物件擁有一個字典的使用介面，除了遇到 Counter 中沒有的值時會回傳計數 0 取代 @ref{5df,,KeyError} 這點不同：

@example
>>> c = Counter(['eggs', 'ham'])
>>> c['bacon']                              # count of a missing element is zero
0
@end example

將一個值的計數設為 0 並不會真的從 Counter 中刪除這個元素，要使用 @code{del} 來將其刪除：

@example
>>> c['sausage'] = 0                        # counter entry with a zero count
>>> del c['sausage']                        # del actually removes the entry
@end example


在 3.1 版被加入.



在 3.7 版的變更: 作為 @ref{183,,dict} 的子類別，@ref{1292,,Counter} 繼承了記憶插入順序的功能。對 `Counter' 做數學運算後同樣保留順序性，其結果是依照各個元素在運算元左邊出現的時間先後、再按照運算元右邊出現的時間先後來排列。


除了字典原本就有的方法外，Counter 物件額外支援數個新方法：

@geindex elements() (collections.Counter 的方法)
@anchor{library/collections collections Counter elements}@anchor{1504}
@deffn {方法} elements ()

回傳每個元素都重複出現計算次數的 iterator（疊代器）物件，其中元素的回傳順序是依照各元素首次出現的時間先後。如果元素的出現次數小於 1，@ref{1504,,elements()} 方法會忽略這些元素。

@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{1503}
@deffn {方法} most_common ([n])

回傳一個 list，包含出現最多次的 `n' 個元素及其出現次數，並按照出現次數排序。如果 `n' 被省略或者為 @code{None}，@ref{1503,,most_common()} 會回傳`所有' counter 中的元素。出現次數相同的元素會按照首次出現的時間先後來排列：

@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{13df}
@deffn {方法} subtract ([iterable-or-mapping])

減去自一個 `iterable' 或另一個`對映'（或 Counter）中的計數元素，行為類似 @ref{165a,,dict.update()} 但是是為了減去計數而非取代其值。輸入和輸出都可以是 0 或是負數。

@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


在 3.2 版被加入.

@end deffn

@geindex total() (collections.Counter 的方法)
@anchor{library/collections collections Counter total}@anchor{2827}
@deffn {方法} total ()

計算總計數值。

@example
>>> c = Counter(a=10, b=5, c=0)
>>> c.total()
15
@end example


在 3.10 版被加入.

@end deffn

通常來說字典方法也可以用於 @ref{1292,,Counter} 物件，除了以下兩個作用方式與計數器不同。

@geindex fromkeys() (collections.Counter 的方法)
@anchor{library/collections collections Counter fromkeys}@anchor{2828}
@deffn {方法} fromkeys (iterable)

此類別方法沒有被實作於 @ref{1292,,Counter} 物件中。
@end deffn

@geindex update() (collections.Counter 的方法)
@anchor{library/collections collections Counter update}@anchor{2829}
@deffn {方法} update ([iterable-or-mapping])

加上自一個 `iterable' 計算出的計數或加上另一個 `mapping'（或 Counter）中的計數，行為類似 @ref{165a,,dict.update()} 但是是為了加上計數而非取代其值。另外，`iterable' 需要是一串將被計算個數元素的序列，而非元素為 @code{(key, value)} 形式的序列。
@end deffn
@end deffn

Counter 支援相等性、子集和超集關係的 rich comparison 運算子：@code{==}、@code{!=}、@code{<}、@code{<=}、@code{>}、@code{>=}。這些檢測會將不存在的元素之計數值當作零，因此 @code{Counter(a=1) == Counter(a=1, b=0)} 將回傳真值。


在 3.10 版的變更: 增加了 rich comparison 運算。



在 3.10 版的變更: 在相等性運算中，不存在的元素之計數值會被當作零。在此之前，@code{Counter(a=3)} 和 @code{Counter(a=3, b=0)} 被視為不同。


使用 @ref{1292,,Counter} 物件的常見使用模式：

@example
c.total()                       # total of all counts
c.clear()                       # reset all counts
list(c)                         # list unique elements
set(c)                          # convert to a set
dict(c)                         # convert to a regular dictionary
c.items()                       # access the (elem, cnt) pairs
Counter(dict(list_of_pairs))    # convert from a list of (elem, cnt) pairs
c.most_common()[:-n-1:-1]       # n least common elements
+c                              # remove zero and negative counts
@end example

為結合多個 @ref{1292,,Counter} 物件以產生 multiset（多重集合，擁有大於 0 計數元素的計數器），有提供了幾種數學操作。加法和減法是根據各個對應元素分別將 Counter 加上和減去計數，交集和聯集分別回傳各個元素最小和最大計數，相等性與包含性運算則會比較對應的計數。每一個操作都可以接受輸入帶有正負號的計數，但輸出的 Counter 則會將擁有小於或等於 0 計數的元素剔除。

@example
>>> c = Counter(a=3, b=1)
>>> d = Counter(a=1, b=2)
>>> c + d                       # add two counters together:  c[x] + d[x]
Counter(@{'a': 4, 'b': 3@})
>>> c - d                       # subtract (keeping only positive counts)
Counter(@{'a': 2@})
>>> c & d                       # intersection:  min(c[x], d[x])
Counter(@{'a': 1, 'b': 1@})
>>> c | d                       # union:  max(c[x], d[x])
Counter(@{'a': 3, 'b': 2@})
>>> c == d                      # equality:  c[x] == d[x]
False
>>> c <= d                      # inclusion:  c[x] <= d[x]
False
@end example

加減法的一元運算子分別是加上空的 Counter 和從空 Counter 減去的簡寫。

@example
>>> c = Counter(a=2, b=-4)
>>> +c
Counter(@{'a': 2@})
>>> -c
Counter(@{'b': 4@})
@end example


在 3.3 版被加入: 開始支援加減一元運算子和 multiset 的原地 (in-place) 操作。


@cartouche
@quotation 備註 
Counter 主要是被設計來操作正整數以當作使用中的計數，但為了某些會用到計數之值為負數或為其他型別的案例中，Counter 也小心地被設計成不會預先排除這些特殊元素。為了輔助使用於上述案例，這一小節記錄了最小範圍和型別限制。


@itemize *

@item 
@ref{1292,,Counter} 類別本身是字典的子類別，且不限制其鍵與值。值被用來表示計數，但實際上你`可以'儲存任何值。

@item 
使用 @ref{1503,,most_common()} 方法的唯一條件是其值要是可被排序的。

@item 
像是 @code{c[key] += 1} 的原地操作中，其值之型別只必須支援加減，所以分數、浮點數、十進位數與其負值都可以使用。同理，@ref{2829,,update()} 和 @ref{13df,,subtract()} 也都允許 0 或負值為輸入或輸出。

@item 
Multiset 相關方法只為了處理正值而設計，其輸入允許是 0 或負值但只有正值會被輸出。並無型別限制，但其值的型別須支援加、減及比較運算。

@item 
@ref{1504,,elements()} 方法需要其計數為正值，如為 0 或負值則忽略。
@end itemize
@end quotation
@end cartouche


@subsubheading 也參考



@itemize *

@item 
Smalltalk 中的 Bag class@footnote{https://www.gnu.org/software/smalltalk/manual-base/html_node/Bag.html}。

@item 
維基百科上的多重集合@footnote{https://en.wikipedia.org/wiki/Multiset}條目。

@item 
C++ multisets@footnote{http://www.java2s.com/Tutorial/Cpp/0380__set-multiset/Catalog0380__set-multiset.htm} 教學與範例。

@item 
Multiset 的數學運算及其使用時機，參考 `Knuth, Donald. The Art of Computer Programming Volume II, Section 4.6.3, Exercise 19'。

@item 
若要根據給定的元素集合來列舉出所有不重複且擁有指定元素數量的 multiset，請見 @ref{1482,,itertools.combinations_with_replacement()}：

@example
map(Counter, combinations_with_replacement('ABC', 2)) # --> AA AB AC BB BC CC
@end example
@end itemize


@node deque 物件,defaultdict 物件,Counter 物件,collections --- 容器資料型態
@anchor{library/collections deque-objects}@anchor{282a}
@subsubsection @code{deque} 物件


@geindex deque (collections 中的類別)
@anchor{library/collections collections deque}@anchor{7ed}
@deffn {類別} collections.deque ([iterable[, maxlen]])

回傳一個新的 deque（雙端佇列）物件，將 `iterable' 中的資料由左至右（使用 @ref{282b,,append()}）加入來做初始化。如果 `iterable' 並未給定，回傳的則是一個空的 deque。

Deque（發音為 "deck"，為 "double-ended queue" 的簡稱）為 stack 和 queue 的一般化。deque 支援執行緒安全 (thread-safe)，且能夠有效率地節省記憶體在頭和尾加入和移除元素，兩個方向的表現都大致為 `O'(1) 複雜度。

雖然 @ref{24d,,list} 物件也支援類似操作，但 list 優化了長度固定時的操作，而會改變底層資料的長度及位置的 @code{pop(0)} 和 @code{insert(0, v)} 操作，記憶體移動則為 `O'(`n') 複雜度。

如果 `maxlen' 沒有給定或者為 @code{None}，deque 可以增長到任意長度；但若有給定的話，deque 的最大長度就會被限制。一個被限制長度的 deque 一但滿了，若在一端加入數個新元素，則同時會在另一端移除相同數量的元素。限定長度的 deque 提供了和 Unix @code{tail} filter 類似的功能，可用於追蹤使用者在意的那些最新執行事項或數據源。

Deque 物件支援以下方法：

@geindex append() (collections.deque 的方法)
@anchor{library/collections collections deque append}@anchor{282b}
@deffn {方法} append (x)

將 `x' 自 deque 的右側加入。
@end deffn

@geindex appendleft() (collections.deque 的方法)
@anchor{library/collections collections deque appendleft}@anchor{282c}
@deffn {方法} appendleft (x)

將 `x' 自 deque 的左側加入。
@end deffn

@geindex clear() (collections.deque 的方法)
@anchor{library/collections collections deque clear}@anchor{282d}
@deffn {方法} clear ()

將所有元素從 deque 中移除，使其長度為 0。
@end deffn

@geindex copy() (collections.deque 的方法)
@anchor{library/collections collections deque copy}@anchor{fcd}
@deffn {方法} copy ()

建立一個 deque 的淺複製 (shallow copy)。


在 3.5 版被加入.

@end deffn

@geindex count() (collections.deque 的方法)
@anchor{library/collections collections deque count}@anchor{13e1}
@deffn {方法} count (x)

計算 deque 內元素為 `x' 的個數。


在 3.2 版被加入.

@end deffn

@geindex extend() (collections.deque 的方法)
@anchor{library/collections collections deque extend}@anchor{282e}
@deffn {方法} extend (iterable)

將 iterable 引數加入 deque 的右側。
@end deffn

@geindex extendleft() (collections.deque 的方法)
@anchor{library/collections collections deque extendleft}@anchor{282f}
@deffn {方法} extendleft (iterable)

將 iterable 引數加入 deque 的左側。要注意的是，加入後的元素順序和 iterable 參數是相反的。
@end deffn

@geindex index() (collections.deque 的方法)
@anchor{library/collections collections deque index}@anchor{fcb}
@deffn {方法} index (x[, start[, stop]])

回傳 deque 中 `x' 的位置（或在索引 `start' 之後、索引 `stop' 之前的位置）。回傳第一個匹配的位置，如果沒找到就引發 @ref{2eb,,ValueError}。


在 3.5 版被加入.

@end deffn

@geindex insert() (collections.deque 的方法)
@anchor{library/collections collections deque insert}@anchor{fcc}
@deffn {方法} insert (i, x)

在 deque 位置 `i' 中插入 `x'。

如果此插入操作導致 deque 超過其長度上限 `maxlen' 的話，會引發 @ref{1729,,IndexError} 例外。


在 3.5 版被加入.

@end deffn

@geindex pop() (collections.deque 的方法)
@anchor{library/collections collections deque pop}@anchor{2830}
@deffn {方法} pop ()

移除並回傳 deque 的最右側元素，若本來就沒有任何元素，則會引發 @ref{1729,,IndexError}。
@end deffn

@geindex popleft() (collections.deque 的方法)
@anchor{library/collections collections deque popleft}@anchor{2831}
@deffn {方法} popleft ()

移除並回傳 deque 的最左側元素，若本來就沒有任何元素，則會引發 @ref{1729,,IndexError}。
@end deffn

@geindex remove() (collections.deque 的方法)
@anchor{library/collections collections deque remove}@anchor{1bc1}
@deffn {方法} remove (value)

移除第一個出現的 `value'，如果沒找到的話就引發一個 @ref{2eb,,ValueError}。
@end deffn

@geindex reverse() (collections.deque 的方法)
@anchor{library/collections collections deque reverse}@anchor{13e2}
@deffn {方法} reverse ()

將 deque 中的元素原地 (in-place) 倒序排列並回傳 @code{None}。


在 3.2 版被加入.

@end deffn

@geindex rotate() (collections.deque 的方法)
@anchor{library/collections collections deque rotate}@anchor{1b8c}
@deffn {方法} rotate (n=1)

將 deque 向右輪轉 `n' 步。若 `n' 為負值則向左輪轉。

當 deque 不是空的，向右輪轉一步和 @code{d.appendleft(d.pop())} 有相同意義，而向左輪轉亦等價於 @code{d.append(d.popleft())}。
@end deffn

Deque 物件也提供了一個唯讀屬性：

@geindex maxlen (collections.deque 的屬性)
@anchor{library/collections collections deque maxlen}@anchor{1505}
@deffn {屬性} maxlen

Deque 的最大長度，如果不限制長度的話則為 @code{None}。


在 3.1 版被加入.

@end deffn
@end deffn

除了以上使用方式，deque 亦支援了疊代、pickle、@code{len(d)}、@code{reversed(d)}、@code{copy.copy(d)}、@code{copy.deepcopy(d)}、用 @ref{349,,in} 運算子來作隸屬資格檢測以及像是 @code{d[0]} 的標號引用來取得第一個元素。在兩端做索引存取的複雜度為 `O'(1) 但越靠近中間則減慢至 `O'(`n')。若想要隨機而快速的存取，使用 list 會較為合適。

自從 3.5 版本起，deque 開始支援 @code{__add__()}、@code{__mul__()} 和 @code{__imul__()}。

範例：

@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 用法:: 

@end menu

@node deque 用法,,,deque 物件
@anchor{library/collections deque-recipes}@anchor{2832}
@subsubsection @code{deque} 用法


這一章節提供了多種操作 deque 的案例。

被限制長度的 deque 功能類似 Unix 中的 @code{tail} filter：

@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

另一用法是透過從右邊加入、從左邊移除來維護最近加入元素的 list：

@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

一個輪詢調度器@footnote{https://en.wikipedia.org/wiki/Round-robin_scheduling}可以透過在 @ref{7ed,,deque} 中放入 iterator 來實現，值自目前 iterator 的位置 0 取出，如果 iterator 已經消耗完畢就用 @ref{2831,,popleft()} 將其從佇列中移除，否則利用 @ref{1b8c,,rotate()} 來將其移至佇列尾端：

@example
def roundrobin(*iterables):
    "roundrobin('ABC', 'D', 'EF') --> A D E B F C"
    iterators = deque(map(iter, iterables))
    while iterators:
        try:
            while True:
                yield next(iterators[0])
                iterators.rotate(-1)
        except StopIteration:
            # Remove an exhausted iterator.
            iterators.popleft()
@end example

@ref{1b8c,,rotate()} 提供了可以用來實作 @ref{7ed,,deque} 切片和刪除的方法。舉例來說，用純 Python 實作 @code{del d[n]} 需要用 @code{rotate()} 來定位要被移除的元素：

@example
def delete_nth(d, n):
    d.rotate(-n)
    d.popleft()
    d.rotate(n)
@end example

要實現 @ref{7ed,,deque} 切片，可使用近似以下方法：使用 @ref{1b8c,,rotate()} 來將目標元素移動到 deque 最左側，用 @ref{2831,,popleft()} 移除舊元素並用 @ref{282e,,extend()} 加入新元素，最後再反向 rotate。在這個方法上做小小的更動就能簡單地實現 Forth 風格的 stack 操作，例如 @code{dup}、@code{drop}、@code{swap}、@code{over}、@code{pick}、@code{rot} 和 @code{roll}。

@node defaultdict 物件,namedtuple 擁有具名欄位之 tuple 的工廠函式,deque 物件,collections --- 容器資料型態
@anchor{library/collections defaultdict-objects}@anchor{2833}
@subsubsection @code{defaultdict} 物件


@geindex defaultdict (collections 中的類別)
@anchor{library/collections collections defaultdict}@anchor{13bd}
@deffn {類別} collections.defaultdict (default_factory=None, /[, ...])

回傳一個新的類似字典的物件。@ref{13bd,,defaultdict} 是內建類別 @ref{183,,dict} 的子類別。它覆蓋掉了一個方法並添加了一個可寫入的實例變數。其餘功能與 @ref{183,,dict} 相同，此文件不再複述。

第一個引數為 @ref{2834,,default_factory} 屬性提供了初始值，他被預設為 @code{None}，所有其他的引數（包括關鍵字引數）都會被傳遞給 @ref{183,,dict} 的建構函式 (constructor)。

@ref{13bd,,defaultdict} 物件支援以下 @ref{183,,dict} 所沒有的方法：

@geindex __missing__() (collections.defaultdict 的方法)
@anchor{library/collections collections defaultdict __missing__}@anchor{2835}
@deffn {方法} __missing__ (key)

如果 @ref{2834,,default_factory} 屬性為 @code{None}，呼叫此方法會引發一個附帶引數 `key' 的 @ref{5df,,KeyError} 例外。

如果 @ref{2834,,default_factory} 不為 @code{None}，它會不帶引數地被呼叫來為給定的 `key' 提供一個預設值，這個值和 `key' 被作為鍵值對來插入到字典中，並且被此方法所回傳。

如果呼叫 @ref{2834,,default_factory} 時發生例外，則該例外將會保持不變地向外傳遞。

在無法找到所要求的鍵時，此方法會被 @ref{183,,dict} 類別的 @ref{582,,__getitem__()} 方法呼叫。無論此方法回傳了值還是引發了例外，都會被 @ref{582,,__getitem__()} 所傳遞。

注意，@ref{2835,,__missing__()} `不會'被 @ref{582,,__getitem__()} 以外的其他方法呼叫，這意味著 @ref{1efb,,get()} 會像一般的 dict 那樣回傳 @code{None} 做為預設值，而非使用 @ref{2834,,default_factory}。
@end deffn

@ref{13bd,,defaultdict} 物件支援以下實例變數：

@geindex default_factory (collections.defaultdict 的屬性)
@anchor{library/collections collections defaultdict default_factory}@anchor{2834}
@deffn {屬性} default_factory

此屬性為 @ref{2835,,__missing__()} 方法所使用。如果有引數被傳入建構函式，則此屬性會被初始化成第一個引數，如未提供引數則被初始化為 @code{None}。
@end deffn


在 3.9 版的變更: 新增合併 (@code{|}) 和更新 (@code{|=}) 運算子，請見 
@geindex Python Enhancement Proposals; PEP 584
PEP 584@footnote{https://peps.python.org/pep-0584/}。

@end deffn

@menu
* defaultdict 範例:: 

@end menu

@node defaultdict 範例,,,defaultdict 物件
@anchor{library/collections defaultdict-examples}@anchor{2836}
@subsubsection @code{defaultdict} 範例


使用 @ref{24d,,list} 作為 @ref{2834,,default_factory} 可以很輕鬆地將鍵值對序列轉換為包含 list 之字典：

@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

當每個鍵第一次被存取時，它還沒有存在於對映中，所以會自動呼叫 @ref{2834,,default_factory} 方法來回傳一個空的 @ref{24d,,list} 以建立一個條目，@ref{8d4,,list.append()} 操作後續會再新增值到這個新的列表裡。當再次存取該鍵時，就如普通字典般操作（回傳該鍵所對應到的 list），@ref{8d4,,list.append()} 也會新增另一個值到 list 中。和使用與其等價的 @ref{1274,,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

設定 @ref{2834,,default_factory} 為 @ref{19b,,int} 使得 @ref{13bd,,defaultdict} 可被用於計數（類似其他語言中的 bag 或 multiset）：

@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

當一個字母首次被存取時，它並不存在於對映中，則 @ref{2834,,default_factory} 函式會呼叫 @ref{19b,,int()} 來提供一個整數 0 作為預設值。後續的增加操作繼續對每個字母做計數。

函式 @ref{19b,,int()} 總是回傳 0，這是常數函式的特殊情況。一個更快、更有彈性的方法是使用 lambda 函式來提供任何常數值（不用一定要是 0）：

@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

將 @ref{2834,,default_factory} 設為 @ref{184,,set} 使 @ref{13bd,,defaultdict} 可用於構建一個值為 set 的字典：

@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 擁有具名欄位之 tuple 的工廠函式,OrderedDict 物件,defaultdict 物件,collections --- 容器資料型態
@anchor{library/collections namedtuple-factory-function-for-tuples-with-named-fields}@anchor{2837}
@subsubsection @code{namedtuple()} 擁有具名欄位之 tuple 的工廠函式


Named tuple（具名元組）賦予 tuple 中各個位置意義，使程式碼更有可讀性與自我文件性。它們可以用於任何普通 tuple 可使用的場合，賦予其透過名稱（而非位置索引）來存取欄位的能力。

@geindex namedtuple() (於 collections 模組中)
@anchor{library/collections collections namedtuple}@anchor{4db}
@deffn {函式} collections.namedtuple (typename, field_names, *, rename=False, defaults=None, module=None)

回傳一個名為 `typename' 的新 tuple 子類別。這個新的子類別被用於建立類似 tuple 的物件，可以透過屬性名稱來存取欄位，它同時也是可索引 (indexable) 和可疊代的 (iterable)。子類別實例同樣有文件字串 (docstring)（有類別名稱 `typename' 和欄位名 `field_names'）和一個好用的 @ref{828,,__repr__()} 方法，可將 tuple 內容以 @code{name=value} 格式列出。

`field_names' 是一個像 @code{['x', 'y']} 一樣的字串序列。`field_names' 也可以是一個用空白或逗號分隔各個欄位名稱的字串，比如 @code{'x y'} 或者 @code{'x, y'}。

除了底線開頭以外的其他任何有效 Python 識別字 (identifier) 都可以作為欄位名稱，有效識別字由字母、數字、底線所組成，但不能是數字或底線開頭，也不能是關鍵詞 @ref{88,,keyword}，例如 `class'、`for'、`return'、`global'、`pass' 或 `raise'。

如果 `rename' 為真值，無效的欄位名稱會自動被位置名稱取代。比如 @code{['abc', 'def', 'ghi', 'abc']} 會被轉換成 @code{['abc', '_1', 'ghi', '_3']}，移除了關鍵字 @code{def} 和重複欄位名 @code{abc}。

`defaults' 可以為 @code{None} 或者是一個預設值的 @ref{1428,,iterable}。因為有預設值的欄位必須出現在那些沒有預設值的欄位之後，`defaults' 是被應用在右側的引數。例如 fieldnames 為 @code{['x', 'y', 'z']} 且 defaults 為 @code{(1, 2)}，那麼 @code{x} 就必須被給定一個引數，@code{y} 被預設為 @code{1}，@code{z} 則被預設為 @code{2}。

如果 `module' 值有被定義，named tuple 的 @ref{60f,,__module__} 屬性就被設定為該值。

Named tuple 實例中沒有字典，所以它們更加輕量，且和一般 tuple 相比佔用更少記憶體。

要支援 pickle，應將 named tuple 類別賦值給一個符合 `typename' 的變數。


在 3.1 版的變更: 新增對於 `rename' 的支援。



在 3.6 版的變更: `verbose' 和 `rename' 參數成為@ref{59f,,僅限關鍵字引數}。



在 3.6 版的變更: 新增 `module' 參數。



在 3.7 版的變更: 移除 `verbose' 參數和 @code{_source} 屬性。



在 3.7 版的變更: 新增 `defaults' 參數和 @ref{2838,,_field_defaults} 屬性。

@end deffn

@example
>>> # Basic example
>>> Point = namedtuple('Point', ['x', 'y'])
>>> p = Point(11, y=22)     # instantiate with positional or keyword arguments
>>> p[0] + p[1]             # indexable like the plain tuple (11, 22)
33
>>> x, y = p                # unpack like a regular tuple
>>> x, y
(11, 22)
>>> p.x + p.y               # fields also accessible by name
33
>>> p                       # readable __repr__ with a name=value style
Point(x=11, y=22)
@end example

Named tuple 在賦予欄位名稱於 @ref{2d,,csv} 或 @ref{d4,,sqlite3} 模組回傳之 tuple 時相當有用：

@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

除了繼承自 tuple 的方法，named tuple 還支援三個額外的方法和兩個屬性。為了防止欄位名稱有衝突，方法和屬性的名稱以底線開頭。

@geindex _make() (collections.somenamedtuple 的類別方法)
@anchor{library/collections collections somenamedtuple _make}@anchor{2839}
@deffn {方法} classmethod somenamedtuple._make (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{bcb}
@deffn {方法} somenamedtuple._asdict ()

回傳一個將欄位名稱對映至對應值的 @ref{183,,dict}：

@example
>>> p = Point(x=11, y=22)
>>> p._asdict()
@{'x': 11, 'y': 22@}
@end example


在 3.1 版的變更: 回傳一個 @ref{7ec,,OrderedDict} 而非 @ref{183,,dict}。



在 3.8 版的變更: 回傳一個常規 @ref{183,,dict} 而非 @ref{7ec,,OrderedDict}，自從 Python 3.7 開始，dict 已經保證有順序性，如果需要 @ref{7ec,,OrderedDict} 所專屬的特性，推薦的解法是將結果專換成所需的類型：@code{OrderedDict(nt._asdict())}。

@end deffn

@geindex _replace() (collections.somenamedtuple 的方法)
@anchor{library/collections collections somenamedtuple _replace}@anchor{283a}
@deffn {方法} somenamedtuple._replace (**kwargs)

回傳一個新的 named tuple 實例，並將指定欄位替換為新的值：

@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{1c0,,copy.replace()}.


在 3.13 版的變更: Raise @ref{198,,TypeError} instead of @ref{2eb,,ValueError} for invalid
keyword arguments.

@end deffn

@geindex _fields (collections.somenamedtuple 的屬性)
@anchor{library/collections collections somenamedtuple _fields}@anchor{283b}
@deffn {屬性} somenamedtuple._fields

列出 tuple 欄位名稱的字串，用於自我檢查或是從現有 named tuple 建立一個新的 named tuple 型別。

@example
>>> p._fields            # 查看欄位名稱
('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{2838}
@deffn {屬性} somenamedtuple._field_defaults

將欄位名稱對映至預設值的字典。

@example
>>> Account = namedtuple('Account', ['type', 'balance'], defaults=[0])
>>> Account._field_defaults
@{'balance': 0@}
>>> Account('premium')
Account(type='premium', balance=0)
@end example
@end deffn

要取得這個名稱存於字串的欄位，要使用 @ref{dc5,,getattr()} 函式：

@example
>>> getattr(p, 'x')
11
@end example

（如@ref{1eda,,拆解引數列表（Unpacking Argument Lists）}所述）將一個字典轉換成 named tuple，要使用 ** 雙星號運算子：

@example
>>> d = @{'x': 11, 'y': 22@}
>>> Point(**d)
Point(x=11, y=22)
@end example

因為一個 named tuple 是一個常規的 Python 類別，我們可以很容易的透過子類別來新增或更改功能，以下是如何新增一個計算得到的欄位和固定寬度的輸出列印格式：

@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

上面的子類別將 @code{__slots__} 設定為空 tuple，這樣一來就防止了字典實例被建立，因而保持了較低的記憶體用量。

子類別化無法用於增加新的、已被儲存的欄位，應當透過 @ref{283b,,_fields} 屬性以建立一個新的 named tuple 來實現：

@example
>>> Point3D = namedtuple('Point3D', Point._fields + ('z',))
@end example

透過直接賦值給 @code{__doc__}，可以自訂說明文件字串：

@example
>>> Book = namedtuple('Book', ['id', 'title', 'authors'])
>>> Book.__doc__ += ': Hardcover book in active collection'
>>> Book.id.__doc__ = '13-digit ISBN'
>>> Book.title.__doc__ = 'Title of first printing'
>>> Book.authors.__doc__ = 'List of authors sorted by last name'
@end example


在 3.5 版的變更: 文件字串屬性變成可寫入。



@subsubheading 也參考



@itemize *

@item 
關於為 named tuple 新增型別提示的方法，請參閱 @ref{330,,typing.NamedTuple}，它運用 @ref{14d8,,class} 關鍵字以提供了一個簡潔的表示法：

@example
class Component(NamedTuple):
    part_number: int
    weight: float
    description: Optional[str] = None
@end example

@item 
關於以 dict 而非 tuple 為底層的可變命名空間，請參考 @ref{4e0,,types.SimpleNamespace()}。

@item 
@ref{33,,dataclasses} 模組提供了一個裝飾器和一些函式，用於自動將被生成的特殊方法新增到使用者定義的類別中。
@end itemize


@node OrderedDict 物件,UserDict 物件,namedtuple 擁有具名欄位之 tuple 的工廠函式,collections --- 容器資料型態
@anchor{library/collections ordereddict-objects}@anchor{283c}
@subsubsection @code{OrderedDict} 物件


Ordered dictionary（有序字典）就像常規字典一樣，但有一些與排序操作相關的額外功能，但由於內建的 @ref{183,,dict} 類別現在已經有記憶插入順序的能力（Python 3.7 中確保了這種新行為），它們變得不那麼重要了。

仍存在一些與 @ref{183,,dict} 的不同之處：


@itemize *

@item 
常規的 @ref{183,,dict} 被設計成非常擅長於對映相關操作，追蹤插入的順序為次要目標。

@item 
@ref{7ec,,OrderedDict} 則被設計成擅長於重新排序相關的操作，空間效率、疊代速度和更新操作的效能則為次要設計目標。

@item 
@ref{7ec,,OrderedDict} 比起 @ref{183,,dict} 更適合處理頻繁的重新排序操作，如在下方用法中所示，這讓它適合用於多種 LRU cache 的實作中。

@item 
@ref{7ec,,OrderedDict} 之相等性運算會檢查順序是否相同。

一個一般的 @ref{183,,dict} 可以用 @code{p == q and all(k1 == k2 for k1, k2 in zip(p, q))} 來效仿有檢查順序的相等性運算。

@item 
@ref{7ec,,OrderedDict} 類別的 @ref{14ee,,popitem()} 方法有不同的函式簽名 (signature)，它接受傳入一個選擇性引數來指定要移除哪個元素。

一個一般的 @ref{183,,dict} 可以用 @code{d.popitem()} 來效仿 OrderedDict 的 @code{od.popitem(last=True)}，這保證會移除最右邊（最後一個）的元素。

一個一般的 @ref{183,,dict} 可以用 @code{(k := next(iter(d)), d.pop(k))} 來效仿 OrderedDict 的 @code{od.popitem(last=False)}，若最左邊（第一個）的元素存在，則將其回傳並移除。

@item 
@ref{7ec,,OrderedDict} 有個 @ref{13e0,,move_to_end()} 方法可有效率地將一個元素重新排列到任一端。

一個一般的 @ref{183,,dict} 可以用 @code{d[k] = d.pop(k)} 來效仿 OrderedDict 的 @code{od.move_to_end(k, last=True)}，這會將該鍵與其對應到的值移動至最右（最後面）的位置。

一個一般的 @ref{183,,dict} 沒有和 OrderedDict 的 @code{od.move_to_end(k, last=False)} 等價的有效方式，這是將鍵與其對應到的值移動至最左（最前面）位置的方法。

@item 
在 Python 3.8 之前，@ref{183,,dict} 並沒有 @ref{e81,,__reversed__()} 方法。
@end itemize

@geindex OrderedDict (collections 中的類別)
@anchor{library/collections collections OrderedDict}@anchor{7ec}
@deffn {類別} collections.OrderedDict ([items])

回傳一個 @ref{183,,dict} 子類別的實例，它具有專門用於重新排列字典順序的方法。


在 3.1 版被加入.


@geindex popitem() (collections.OrderedDict 的方法)
@anchor{library/collections collections OrderedDict popitem}@anchor{14ee}
@deffn {方法} popitem (last=True)

Ordered dictionary 的 @ref{14ee,,popitem()} 方法移除並回傳一個鍵值 (key, value) 對。如果 `last' 為真值，則按 @abbr{LIFO} 後進先出的順序回傳鍵值對，否則就按 @abbr{FIFO,first-in@comma{} first-out} 先進先出的順序回傳鍵值對。
@end deffn

@geindex move_to_end() (collections.OrderedDict 的方法)
@anchor{library/collections collections OrderedDict move_to_end}@anchor{13e0}
@deffn {方法} move_to_end (key, last=True)

將現有的 `key' 移動到 ordered dictionary 的任一端。如果 `last' 為真值（此為預設值）則將元素移至右端；如果 `last' 為假值則將元素移至左端。如果 `key' 不存在則會引發 @ref{5df,,KeyError}：

@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


在 3.2 版被加入.

@end deffn
@end deffn

除了普通的對映方法，ordered dictionary 還支援了透過 @ref{a5e,,reversed()} 來做倒序疊代。
@anchor{library/collections collections-ordereddict-eq}@anchor{18b0}
@ref{7ec,,OrderedDict} 物件之間的相等性運算是會檢查順序是否相同的，大致等價於 @code{list(od1.items())==list(od2.items())}。

@ref{7ec,,OrderedDict} 物件和其他 @ref{abe,,Mapping} 物件間的相等性運算則像普通字典一樣不考慮順序性，這使得 @ref{7ec,,OrderedDict} 可於任何字典可使用的時機中被替換掉。


在 3.5 版的變更: @ref{7ec,,OrderedDict} 的項 (item)、鍵與值之@ref{283d,,視圖}現在可透過 @ref{a5e,,reversed()} 來倒序疊代。



在 3.6 版的變更: 隨著 
@geindex Python Enhancement Proposals; PEP 468
PEP 468@footnote{https://peps.python.org/pep-0468/} 被核可，被傳入給 @ref{7ec,,OrderedDict} 建構函式與其 @ref{165a,,update()} 方法的關鍵字引數之順序被保留了下來。



在 3.9 版的變更: 新增合併 (@code{|}) 和更新 (@code{|=}) 運算子，請見 
@geindex Python Enhancement Proposals; PEP 584
PEP 584@footnote{https://peps.python.org/pep-0584/}。


@menu
* OrderedDict 範例與用法:: 

@end menu

@node OrderedDict 範例與用法,,,OrderedDict 物件
@anchor{library/collections ordereddict-examples-and-recipes}@anchor{283e}
@subsubsection @code{OrderedDict} 範例與用法


建立一個能夠記住鍵`最後'插入順序的 ordered dictionary 變體很簡單。如果新條目覆蓋了現有條目，則原本插入位置會被更改並移動至末端：

@example
class LastUpdatedOrderedDict(OrderedDict):
    'Store items in the order the keys were last added'

    def __setitem__(self, key, value):
        super().__setitem__(key, value)
        self.move_to_end(key)
@end example

@ref{7ec,,OrderedDict} 在實現一個 @ref{bd9,,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 物件,UserList 物件,OrderedDict 物件,collections --- 容器資料型態
@anchor{library/collections userdict-objects}@anchor{283f}
@subsubsection @code{UserDict} 物件


@ref{1c46,,UserDict} 類別是作為 dict 物件的包裝器。因為已經可以直接自 @ref{183,,dict} 建立子類別，這個類別的需求已部分被滿足，不過這個類別使用起來更方便，因為被包裝的字典可以作為其屬性來存取。

@geindex UserDict (collections 中的類別)
@anchor{library/collections collections UserDict}@anchor{1c46}
@deffn {類別} collections.UserDict ([initialdata])

模擬字典的類別。實例的內容被存於一個字典，可透過 @ref{1c46,,UserDict} 的 @ref{2840,,data} 屬性來做存取。如果有提供 `initialdata'，@ref{2840,,data} 屬性會被初始化為其值；要注意指到 `initialdata' 的參照不會被保留，使其可被用於其他目的。

除了支援作為對映所需的方法與操作，@ref{1c46,,UserDict} 實例提供了以下屬性：

@geindex data (collections.UserDict 的屬性)
@anchor{library/collections collections UserDict data}@anchor{2840}
@deffn {屬性} data

一個真實的字典，用於儲存 @ref{1c46,,UserDict} 類別的資料內容。
@end deffn
@end deffn

@node UserList 物件,UserString 物件,UserDict 物件,collections --- 容器資料型態
@anchor{library/collections userlist-objects}@anchor{2841}
@subsubsection @code{UserList} 物件


此類別是 list 物件的包裝器。它是個方便的基礎類別，可繼承它並覆寫現有方法或加入新方法來定義你所需的一個類似於 list 的類別。如此一來，我們可以為 list 加入新的特性。

因為已經可以直接自 @ref{24d,,list} 建立子類別，這個類別的需求已部分被滿足，不過這個類別使用起來更方便，因為被包裝的 list 可以作為其屬性來存取。

@geindex UserList (collections 中的類別)
@anchor{library/collections collections UserList}@anchor{16d8}
@deffn {類別} collections.UserList ([list])

模擬 list 的類別。實例的內容被存於一個 list，可透過 @ref{16d8,,UserList} 的 @ref{2842,,data} 屬性來做存取。實例內容被初始化為 `list' 的複製，預設為一個空的 list @code{[]}。`list' 可以是任何 iterable，例如一個真實的 Python list 或是一個 @ref{16d8,,UserList} 物件。

除了支援可變序列的方法與操作，@ref{16d8,,UserList} 實例提供了以下屬性：

@geindex data (collections.UserList 的屬性)
@anchor{library/collections collections UserList data}@anchor{2842}
@deffn {屬性} data

一個真實的 @ref{24d,,list} 物件，用於儲存 @ref{16d8,,UserList} 類別的資料內容。
@end deffn
@end deffn

`子類別化的條件：'@ref{16d8,,UserList} 的子類別應該要提供一個不需要引數或一個引數的建構函式。回傳一個新序列的 list 操作會從那些實作出來的類別建立一個實例，為了達成上述目的，它假設建構函式可傳入單一參數來呼叫，該參數即是做為數據來源的一個序列物件。

如果希望一個自此獲得的子類別不遵從上述要求，那所有該類別支援的特殊方法則必須被覆寫；請參考原始碼來理解在這情況下哪些方法是必須提供的。

@node UserString 物件,,UserList 物件,collections --- 容器資料型態
@anchor{library/collections userstring-objects}@anchor{2843}
@subsubsection @code{UserString} 物件


@ref{fce,,UserString} 類別是字串物件的包裝器，因為已經可以從 @ref{169,,str} 直接建立子類別，這個類別的需求已經部分被滿足，不過這個類別使用起來更方便，因為被包裝的字串可以作為其屬性來存取。

@geindex UserString (collections 中的類別)
@anchor{library/collections collections UserString}@anchor{fce}
@deffn {類別} collections.UserString (seq)

模擬字串物件的類別。實例的內容被存於一個字串物件，可透過 @ref{fce,,UserString} 的 @ref{2844,,data} 屬性來做存取。實例內容被初始化為 `seq' 的複製，`seq' 引數可以是任何可被內建函式 @ref{169,,str()} 轉換成字串的物件。

除了支援字串的方法和操作以外，@ref{fce,,UserString} 實例也提供了以下屬性：

@geindex data (collections.UserString 的屬性)
@anchor{library/collections collections UserString data}@anchor{2844}
@deffn {屬性} data

一個真實的 @ref{169,,str} 物件，用來儲存 @ref{fce,,UserString} 類別的資料內容。
@end deffn


在 3.5 版的變更: 新增方法 @code{__getnewargs__}、@code{__rmod__}、@code{casefold}、@code{format_map}、@code{isprintable} 以及 @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 --- 容器的抽象基底類別,heapq --- 堆積佇列 heap queue 演算法,collections --- 容器資料型態,資料型別
@anchor{library/collections abc doc}@anchor{2845}@anchor{library/collections abc collections-abc-abstract-base-classes-for-containers}@anchor{2846}@anchor{library/collections abc module-collections abc}@anchor{1f}@anchor{library/collections abc translation-repo}@anchor{2847}
@subsection @code{collections.abc} --- 容器的抽象基底類別


@geindex module; collections.abc


在 3.3 版被加入: 過去此模組是 @ref{1e,,collections} 模組的一部分。


`原始碼：'Lib/_collections_abc.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/_collections_abc.py}

@c from collections.abc import *
@c import itertools
@c __name__ = '<doctest>'


__________________________________________________________________


This module provides @ref{13b7,,abstract base classes} that
can be used to test whether a class provides a particular interface; for
example, whether it is @ref{81d,,hashable} or whether it is a @ref{13bc,,mapping}.

An @ref{9bd,,issubclass()} or @ref{2ad,,isinstance()} test for an interface works in one
of three ways.


@enumerate 

@item 
A newly written class can inherit directly from one of the
abstract base classes.  The class must supply the required abstract
methods.  The remaining mixin methods come from inheritance and can be
overridden if desired.  Other methods may be added as needed:

@example
class C(Sequence):                      # Direct inheritance
    def __init__(self): ...             # Extra method not required by the ABC
    def __getitem__(self, index):  ...  # Required abstract method
    def __len__(self):  ...             # Required abstract method
    def count(self, value): ...         # Optionally override a mixin method
@end example

@example
>>> issubclass(C, Sequence)
True
>>> isinstance(C(), Sequence)
True
@end example

@item 
Existing classes and built-in classes can be registered as "virtual
subclasses" of the ABCs.  Those classes should define the full API
including all of the abstract methods and all of the mixin methods.
This lets users rely on @ref{9bd,,issubclass()} or @ref{2ad,,isinstance()} tests
to determine whether the full interface is supported.  The exception to
this rule is for methods that are automatically inferred from the rest
of the API:

@example
class D:                                 # No inheritance
    def __init__(self): ...              # Extra method not required by the ABC
    def __getitem__(self, index):  ...   # Abstract method
    def __len__(self):  ...              # Abstract method
    def count(self, value): ...          # Mixin method
    def index(self, value): ...          # Mixin method

Sequence.register(D)                     # Register instead of inherit
@end example

@example
>>> issubclass(D, Sequence)
True
>>> isinstance(D(), Sequence)
True
@end example

In this example, class @code{D} does not need to define
@code{__contains__}, @code{__iter__}, and @code{__reversed__} because the
@ref{2378,,in-operator}, the @ref{1428,,iteration}
logic, and the @ref{a5e,,reversed()} function automatically fall back to
using @code{__getitem__} and @code{__len__}.

@item 
Some simple interfaces are directly recognizable by the presence of
the required methods (unless those methods have been set to @ref{87e,,None}):

@example
class E:
    def __iter__(self): ...
    def __next__(self): ...
@end example

@example
>>> issubclass(E, Iterable)
True
>>> isinstance(E(), Iterable)
True
@end example

Complex interfaces do not support this last technique because an
interface is more than just the presence of method names.  Interfaces
specify semantics and relationships between methods that cannot be
inferred solely from the presence of specific method names.  For
example, knowing that a class supplies @code{__getitem__}, @code{__len__}, and
@code{__iter__} is insufficient for distinguishing a @ref{13c5,,Sequence} from
a @ref{abe,,Mapping}.
@end enumerate


在 3.9 版被加入: These abstract classes now support @code{[]}. See @ref{8b8,,泛型別名型別}
and 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/}.


@menu
* Collections Abstract Base Classes:: 
* 集合抽象基底類別的詳細描述:: 
* Examples and Recipes:: 

@end menu

@node Collections Abstract Base Classes,集合抽象基底類別的詳細描述,,collections abc --- 容器的抽象基底類別
@anchor{library/collections abc collections-abstract-base-classes}@anchor{a6f}@anchor{library/collections abc id1}@anchor{2848}
@subsubsection Collections Abstract Base Classes


The collections module offers the following @ref{13b7,,ABCs}:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

ABC

@tab

Inherits from

@tab

抽象方法

@tab

Mixin Methods

@item

@ref{255a,,Container} @footnote{
These ABCs override @ref{2849,,__subclasshook__()} to support
testing an interface by verifying the required methods are present
and have not been set to @ref{87e,,None}.  This only works for simple
interfaces.  More complex interfaces require registration or direct
subclassing.
}

@tab

@tab

@code{__contains__}

@tab

@item

@ref{712,,Hashable} @footnote{
These ABCs override @ref{2849,,__subclasshook__()} to support
testing an interface by verifying the required methods are present
and have not been set to @ref{87e,,None}.  This only works for simple
interfaces.  More complex interfaces require registration or direct
subclassing.
}

@tab

@tab

@code{__hash__}

@tab

@item

@ref{2558,,Iterable} @footnote{
These ABCs override @ref{2849,,__subclasshook__()} to support
testing an interface by verifying the required methods are present
and have not been set to @ref{87e,,None}.  This only works for simple
interfaces.  More complex interfaces require registration or direct
subclassing.
} @footnote{
Checking @code{isinstance(obj, Iterable)} detects classes that are
registered as @ref{2558,,Iterable} or that have an @ref{1f71,,__iter__()}
method, but it does not detect classes that iterate with the
@ref{582,,__getitem__()} method.  The only reliable way to determine
whether an object is @ref{1428,,iterable} is to call @code{iter(obj)}.
}

@tab

@tab

@code{__iter__}

@tab

@item

@ref{2559,,Iterator} @footnote{
These ABCs override @ref{2849,,__subclasshook__()} to support
testing an interface by verifying the required methods are present
and have not been set to @ref{87e,,None}.  This only works for simple
interfaces.  More complex interfaces require registration or direct
subclassing.
}

@tab

@ref{2558,,Iterable}

@tab

@code{__next__}

@tab

@code{__iter__}

@item

@ref{e80,,Reversible} @footnote{
These ABCs override @ref{2849,,__subclasshook__()} to support
testing an interface by verifying the required methods are present
and have not been set to @ref{87e,,None}.  This only works for simple
interfaces.  More complex interfaces require registration or direct
subclassing.
}

@tab

@ref{2558,,Iterable}

@tab

@code{__reversed__}

@tab

@item

@ref{fd6,,Generator}  @footnote{
These ABCs override @ref{2849,,__subclasshook__()} to support
testing an interface by verifying the required methods are present
and have not been set to @ref{87e,,None}.  This only works for simple
interfaces.  More complex interfaces require registration or direct
subclassing.
}

@tab

@ref{2559,,Iterator}

@tab

@code{send}、@code{throw}

@tab

@code{close}、@code{__iter__}、@code{__next__}

@item

@ref{713,,Sized}  @footnote{
These ABCs override @ref{2849,,__subclasshook__()} to support
testing an interface by verifying the required methods are present
and have not been set to @ref{87e,,None}.  This only works for simple
interfaces.  More complex interfaces require registration or direct
subclassing.
}

@tab

@tab

@code{__len__}

@tab

@item

@ref{9e4,,Callable}  @footnote{
These ABCs override @ref{2849,,__subclasshook__()} to support
testing an interface by verifying the required methods are present
and have not been set to @ref{87e,,None}.  This only works for simple
interfaces.  More complex interfaces require registration or direct
subclassing.
}

@tab

@tab

@code{__call__}

@tab

@item

@ref{e7f,,Collection}  @footnote{
These ABCs override @ref{2849,,__subclasshook__()} to support
testing an interface by verifying the required methods are present
and have not been set to @ref{87e,,None}.  This only works for simple
interfaces.  More complex interfaces require registration or direct
subclassing.
}

@tab

@ref{713,,Sized}、@ref{2558,,Iterable}、@ref{255a,,Container}

@tab

@code{__contains__}、@code{__iter__}、@code{__len__}

@tab

@item

@ref{13c5,,Sequence}

@tab

@ref{e80,,Reversible},
@ref{e7f,,Collection}

@tab

@code{__getitem__}、@code{__len__}

@tab

@code{__contains__}、@code{__iter__}、@code{__reversed__}、@code{index} 和 @code{count}

@item

@ref{4ba,,MutableSequence}

@tab

@ref{13c5,,Sequence}

@tab

@code{__getitem__}、@code{__setitem__}、@code{__delitem__}、@code{__len__}、@code{insert}

@tab

繼承 @ref{13c5,,Sequence} 方法和 @code{append}、@code{clear}、@code{reverse}、@code{extend}、@code{pop}、@code{remove} 和 @code{__iadd__}

@item

@ref{341,,ByteString}

@tab

@ref{13c5,,Sequence}

@tab

@code{__getitem__}、@code{__len__}

@tab

@ref{13c5,,Sequence} 的繼承方法

@item

@ref{2550,,Set}

@tab

@ref{e7f,,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{255b,,MutableSet}

@tab

@ref{2550,,Set}

@tab

@code{__contains__}、@code{__iter__}、@code{__len__}、@code{add}、@code{discard}

@tab

Inherited @ref{2550,,Set} methods and
@code{clear}, @code{pop}, @code{remove}, @code{__ior__},
@code{__iand__}, @code{__ixor__}, and @code{__isub__}

@item

@ref{abe,,Mapping}

@tab

@ref{e7f,,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{12ad,,MutableMapping}

@tab

@ref{abe,,Mapping}

@tab

@code{__getitem__}、@code{__setitem__}、@code{__delitem__}、@code{__iter__}、@code{__len__}

@tab

Inherited @ref{abe,,Mapping} methods and
@code{pop}, @code{popitem}, @code{clear}, @code{update},
and @code{setdefault}

@item

@ref{255c,,MappingView}

@tab

@ref{713,,Sized}

@tab

@tab

@code{__init__}、@code{__len__} 和 @code{__repr__}

@item

@ref{255e,,ItemsView}

@tab

@ref{255c,,MappingView}、@ref{2550,,Set}

@tab

@tab

@code{__contains__}、@code{__iter__}

@item

@ref{255d,,KeysView}

@tab

@ref{255c,,MappingView}、@ref{2550,,Set}

@tab

@tab

@code{__contains__}、@code{__iter__}

@item

@ref{255f,,ValuesView}

@tab

@ref{255c,,MappingView}、@ref{e7f,,Collection}

@tab

@tab

@code{__contains__}、@code{__iter__}

@item

@ref{fd7,,Awaitable} @footnote{
These ABCs override @ref{2849,,__subclasshook__()} to support
testing an interface by verifying the required methods are present
and have not been set to @ref{87e,,None}.  This only works for simple
interfaces.  More complex interfaces require registration or direct
subclassing.
}

@tab

@tab

@code{__await__}

@tab

@item

@ref{fd8,,Coroutine} @footnote{
These ABCs override @ref{2849,,__subclasshook__()} to support
testing an interface by verifying the required methods are present
and have not been set to @ref{87e,,None}.  This only works for simple
interfaces.  More complex interfaces require registration or direct
subclassing.
}

@tab

@ref{fd7,,Awaitable}

@tab

@code{send}、@code{throw}

@tab

@code{close}

@item

@ref{fda,,AsyncIterable} @footnote{
These ABCs override @ref{2849,,__subclasshook__()} to support
testing an interface by verifying the required methods are present
and have not been set to @ref{87e,,None}.  This only works for simple
interfaces.  More complex interfaces require registration or direct
subclassing.
}

@tab

@tab

@code{__aiter__}

@tab

@item

@ref{fd9,,AsyncIterator} @footnote{
These ABCs override @ref{2849,,__subclasshook__()} to support
testing an interface by verifying the required methods are present
and have not been set to @ref{87e,,None}.  This only works for simple
interfaces.  More complex interfaces require registration or direct
subclassing.
}

@tab

@ref{fda,,AsyncIterable}

@tab

@code{__anext__}

@tab

@code{__aiter__}

@item

@ref{e82,,AsyncGenerator} @footnote{
These ABCs override @ref{2849,,__subclasshook__()} to support
testing an interface by verifying the required methods are present
and have not been set to @ref{87e,,None}.  This only works for simple
interfaces.  More complex interfaces require registration or direct
subclassing.
}

@tab

@ref{fd9,,AsyncIterator}

@tab

@code{asend}、@code{athrow}

@tab

@code{aclose}、@code{__aiter__}、@code{__anext__}

@item

@ref{342,,Buffer} @footnote{
These ABCs override @ref{2849,,__subclasshook__()} to support
testing an interface by verifying the required methods are present
and have not been set to @ref{87e,,None}.  This only works for simple
interfaces.  More complex interfaces require registration or direct
subclassing.
}

@tab

@tab

@code{__buffer__}

@tab

@end multitable


@node 集合抽象基底類別的詳細描述,Examples and Recipes,Collections Abstract Base Classes,collections abc --- 容器的抽象基底類別
@anchor{library/collections abc collections-abstract-base-classes-detailed-descriptions}@anchor{284a}
@subsubsection 集合抽象基底類別的詳細描述


@geindex Container (collections.abc 中的類別)
@anchor{library/collections abc collections abc Container}@anchor{255a}
@deffn {類別} collections.abc.Container

有提供 @ref{15b1,,__contains__()} 方法之類別的 ABC。
@end deffn

@geindex Hashable (collections.abc 中的類別)
@anchor{library/collections abc collections abc Hashable}@anchor{712}
@deffn {類別} collections.abc.Hashable

有提供 @ref{cea,,__hash__()} 方法之類別的 ABC。
@end deffn

@geindex Sized (collections.abc 中的類別)
@anchor{library/collections abc collections abc Sized}@anchor{713}
@deffn {類別} collections.abc.Sized

有提供 @ref{2260,,__len__()} 方法之類別的 ABC。
@end deffn

@geindex Callable (collections.abc 中的類別)
@anchor{library/collections abc collections abc Callable}@anchor{9e4}
@deffn {類別} collections.abc.Callable

有提供 @ref{773,,__call__()} 方法之類別的 ABC。

See @ref{2579,,註釋 callable 物件} for details on how to use
@code{Callable} in type annotations.
@end deffn

@geindex Iterable (collections.abc 中的類別)
@anchor{library/collections abc collections abc Iterable}@anchor{2558}
@deffn {類別} collections.abc.Iterable

有提供 @ref{1f71,,__iter__()} 方法之類別的 ABC。

Checking @code{isinstance(obj, Iterable)} detects classes that are registered
as @ref{2558,,Iterable} or that have an @ref{1f71,,__iter__()} method,
but it does
not detect classes that iterate with the @ref{582,,__getitem__()} method.
The only reliable way to determine whether an object is @ref{1428,,iterable}
is to call @code{iter(obj)}.
@end deffn

@geindex Collection (collections.abc 中的類別)
@anchor{library/collections abc collections abc Collection}@anchor{e7f}
@deffn {類別} collections.abc.Collection

ABC for sized iterable container classes.


在 3.6 版被加入.

@end deffn

@geindex Iterator (collections.abc 中的類別)
@anchor{library/collections abc collections abc Iterator}@anchor{2559}
@deffn {類別} collections.abc.Iterator

有提供 @ref{1f74,,__iter__()} 和 @ref{14ce,,__next__()} 方法之類別的 ABC。另請參閱 @ref{4c3,,iterator} 的定義。
@end deffn

@geindex Reversible (collections.abc 中的類別)
@anchor{library/collections abc collections abc Reversible}@anchor{e80}
@deffn {類別} collections.abc.Reversible

亦有提供 @ref{e81,,__reversed__()} 方法之可疊代類別的 ABC。


在 3.6 版被加入.

@end deffn

@geindex Generator (collections.abc 中的類別)
@anchor{library/collections abc collections abc Generator}@anchor{fd6}
@deffn {類別} collections.abc.Generator

ABC for @ref{125c,,generator} classes that implement the protocol defined in
@geindex Python Enhancement Proposals; PEP 342
PEP 342@footnote{https://peps.python.org/pep-0342/} that extends @ref{4c3,,iterators} with the
@ref{22c9,,send()},
@ref{715,,throw()} and @ref{19b7,,close()} methods.

See @ref{284b,,Annotating generators and coroutines}
for details on using @code{Generator} in type annotations.


在 3.5 版被加入.

@end deffn

@geindex Sequence (collections.abc 中的類別)
@geindex MutableSequence (collections.abc 中的類別)
@geindex ByteString (collections.abc 中的類別)
@anchor{library/collections abc collections abc Sequence}@anchor{13c5}
@deffn {類別} collections.abc.Sequence
@anchor{library/collections abc collections abc MutableSequence}@anchor{4ba}
@deffnx {類別} collections.abc.MutableSequence
@anchor{library/collections abc collections abc ByteString}@anchor{341}
@deffnx {類別} collections.abc.ByteString

唯讀且可變@ref{70f,,序列}的 ABC。

Implementation note: Some of the mixin methods, such as
@ref{1f71,,__iter__()}, @ref{e81,,__reversed__()},
and @ref{18da,,index()} make repeated calls to the underlying
@ref{582,,__getitem__()} method.
Consequently, if @ref{582,,__getitem__()} is implemented with constant
access speed, the mixin methods will have linear performance;
however, if the underlying method is linear (as it would be with a
linked list), the mixins will have quadratic performance and will
likely need to be overridden.

@geindex index() (collections.abc.ByteString 的方法)
@anchor{library/collections abc collections abc ByteString index}@anchor{284c}
@deffn {方法} index (value, start=0, stop=None)

回傳 `value' 的第一個索引。

如果找不到該值，則引發 @ref{2eb,,ValueError}。

建議要支援 `start' 和 `stop' 引數，但並非必要。


在 3.5 版的變更: The @ref{18da,,index()} method gained support for
the `stop' and `start' arguments.

@end deffn


Deprecated since version 3.12, will be removed in version 3.17: @ref{341,,ByteString} ABC 已被棄用。

Use @code{isinstance(obj, collections.abc.Buffer)} to test if @code{obj}
implements the @ref{260,,buffer protocol} at runtime. For use
in type annotations, either use @ref{342,,Buffer} or a union that
explicitly specifies the types your code supports (e.g.,
@code{bytes | bytearray | memoryview}).

@code{ByteString} 最初被設計為一個抽象類別，以作為 @ref{192,,bytes} 和 @ref{343,,bytearray} 的超型別 (supertype)。然而由於 ABC 從未擁有任何方法，知道一個物件是 @code{ByteString} 的實例從未真正告訴你任何關於該物件的有用資訊。其他常見的緩衝區型別如 @ref{165,,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{2550}
@deffn {類別} collections.abc.Set
@anchor{library/collections abc collections abc MutableSet}@anchor{255b}
@deffnx {類別} collections.abc.MutableSet

唯讀且可變@ref{247f,,集合}的 ABC。
@end deffn

@geindex Mapping (collections.abc 中的類別)
@geindex MutableMapping (collections.abc 中的類別)
@anchor{library/collections abc collections abc Mapping}@anchor{abe}
@deffn {類別} collections.abc.Mapping
@anchor{library/collections abc collections abc MutableMapping}@anchor{12ad}
@deffnx {類別} collections.abc.MutableMapping

唯讀且可變@ref{13bc,,對映}的 ABC。
@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{255c}
@deffn {類別} collections.abc.MappingView
@anchor{library/collections abc collections abc ItemsView}@anchor{255e}
@deffnx {類別} collections.abc.ItemsView
@anchor{library/collections abc collections abc KeysView}@anchor{255d}
@deffnx {類別} collections.abc.KeysView
@anchor{library/collections abc collections abc ValuesView}@anchor{255f}
@deffnx {類別} collections.abc.ValuesView

ABCs for mapping, items, keys, and values @ref{283d,,views}.
@end deffn

@geindex Awaitable (collections.abc 中的類別)
@anchor{library/collections abc collections abc Awaitable}@anchor{fd7}
@deffn {類別} collections.abc.Awaitable

ABC for @ref{4c4,,awaitable} objects, which can be used in @ref{18d,,await}
expressions.  Custom implementations must provide the
@ref{f70,,__await__()} method.

@ref{6b2,,Coroutine} objects and instances of the
@ref{fd8,,Coroutine} ABC are all instances of this ABC.

@cartouche
@quotation 備註 
In CPython, generator-based coroutines (@ref{125c,,generators}
decorated with @ref{1083,,@@types.coroutine}) are
`awaitables', even though they do not have an @ref{f70,,__await__()} method.
Using @code{isinstance(gencoro, Awaitable)} for them will return @code{False}.
Use @ref{1013,,inspect.isawaitable()} to detect them.
@end quotation
@end cartouche


在 3.5 版被加入.

@end deffn

@geindex Coroutine (collections.abc 中的類別)
@anchor{library/collections abc collections abc Coroutine}@anchor{fd8}
@deffn {類別} collections.abc.Coroutine

ABC for @ref{6b2,,coroutine} compatible classes.  These implement the
following methods, defined in @ref{2208,,協程物件}:
@ref{22c8,,send()}, @ref{714,,throw()}, and
@ref{22ca,,close()}.  Custom implementations must also implement
@ref{f70,,__await__()}.  All @ref{fd8,,Coroutine} instances are also
instances of @ref{fd7,,Awaitable}.

@cartouche
@quotation 備註 
In CPython, generator-based coroutines (@ref{125c,,generators}
decorated with @ref{1083,,@@types.coroutine}) are
`awaitables', even though they do not have an @ref{f70,,__await__()} method.
Using @code{isinstance(gencoro, Coroutine)} for them will return @code{False}.
Use @ref{1013,,inspect.isawaitable()} to detect them.
@end quotation
@end cartouche

See @ref{284b,,Annotating generators and coroutines}
for details on using @code{Coroutine} in type annotations.
The variance and order of type parameters correspond to those of
@ref{fd6,,Generator}.


在 3.5 版被加入.

@end deffn

@geindex AsyncIterable (collections.abc 中的類別)
@anchor{library/collections abc collections abc AsyncIterable}@anchor{fda}
@deffn {類別} collections.abc.AsyncIterable

ABC for classes that provide an @code{__aiter__} method.  See also the
definition of @ref{f6f,,asynchronous iterable}.


在 3.5 版被加入.

@end deffn

@geindex AsyncIterator (collections.abc 中的類別)
@anchor{library/collections abc collections abc AsyncIterator}@anchor{fd9}
@deffn {類別} collections.abc.AsyncIterator

ABC for classes that provide @code{__aiter__} and @code{__anext__}
methods.  See also the definition of @ref{4c2,,asynchronous iterator}.


在 3.5 版被加入.

@end deffn

@geindex AsyncGenerator (collections.abc 中的類別)
@anchor{library/collections abc collections abc AsyncGenerator}@anchor{e82}
@deffn {類別} collections.abc.AsyncGenerator

ABC for @ref{2342,,asynchronous generator} classes that implement the protocol
defined in 
@geindex Python Enhancement Proposals; PEP 525
PEP 525@footnote{https://peps.python.org/pep-0525/} and 
@geindex Python Enhancement Proposals; PEP 492
PEP 492@footnote{https://peps.python.org/pep-0492/}.

See @ref{284b,,Annotating generators and coroutines}
for details on using @code{AsyncGenerator} in type annotations.


在 3.6 版被加入.

@end deffn

@geindex Buffer (collections.abc 中的類別)
@anchor{library/collections abc collections abc Buffer}@anchor{342}
@deffn {類別} collections.abc.Buffer

ABC for classes that provide the @ref{685,,__buffer__()} method,
implementing the @ref{260,,buffer protocol}. See 
@geindex Python Enhancement Proposals; PEP 688
PEP 688@footnote{https://peps.python.org/pep-0688/}.


在 3.12 版被加入.

@end deffn

@node Examples and Recipes,,集合抽象基底類別的詳細描述,collections abc --- 容器的抽象基底類別
@anchor{library/collections abc examples-and-recipes}@anchor{284d}
@subsubsection Examples and Recipes


ABCs allow us to ask classes or instances if they provide
particular functionality, for example:

@example
size = None
if isinstance(myvar, collections.abc.Sized):
    size = len(myvar)
@end example

Several of the ABCs are also useful as mixins that make it easier to develop
classes supporting container APIs.  For example, to write a class supporting
the full @ref{2550,,Set} API, it is only necessary to supply the three underlying
abstract methods: @ref{15b1,,__contains__()}, @ref{1f71,,__iter__()}, and
@ref{2260,,__len__()}. The ABC supplies the remaining methods such as
@code{__and__()} and @ref{2541,,isdisjoint()}:

@example
class ListBasedSet(collections.abc.Set):
    '@w{'}' Alternate set implementation favoring space over speed
        and not requiring the set elements to be hashable. '@w{'}'
    def __init__(self, iterable):
        self.elements = lst = []
        for value in iterable:
            if value not in lst:
                lst.append(value)

    def __iter__(self):
        return iter(self.elements)

    def __contains__(self, value):
        return value in self.elements

    def __len__(self):
        return len(self.elements)

s1 = ListBasedSet('abcdef')
s2 = ListBasedSet('defghi')
overlap = s1 & s2            # The __and__() method is supported automatically
@end example

Notes on using @ref{2550,,Set} and @ref{255b,,MutableSet} as a mixin:


@enumerate 

@item 
Since some set operations create new sets, the default mixin methods need
a way to create new instances from an @ref{1428,,iterable}. The class constructor is
assumed to have a signature in the form @code{ClassName(iterable)}.
That assumption is factored-out to an internal @ref{489,,classmethod} called
@code{_from_iterable()} which calls @code{cls(iterable)} to produce a new set.
If the @ref{2550,,Set} mixin is being used in a class with a different
constructor signature, you will need to override @code{_from_iterable()}
with a classmethod or regular method that can construct new instances from
an iterable argument.

@item 
To override the comparisons (presumably for speed, as the
semantics are fixed), redefine @ref{150b,,__le__()} and
@ref{150d,,__ge__()},
then the other operations will automatically follow suit.

@item 
The @ref{2550,,Set} mixin provides a @code{_hash()} method to compute a hash value
for the set; however, @ref{cea,,__hash__()} is not defined because not all sets
are @ref{81d,,hashable} or immutable.  To add set hashability using mixins,
inherit from both @ref{2550,,Set()} and @ref{712,,Hashable()}, then define
@code{__hash__ = Set._hash}.
@end enumerate


@subsubheading 也參考



@itemize *

@item 
OrderedSet recipe@footnote{https://code.activestate.com/recipes/576694/} for an
example built on @ref{255b,,MutableSet}.

@item 
關於 ABC 的更多資訊請見 @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 演算法,bisect --- 陣列二分演算法 Array bisection algorithm,collections abc --- 容器的抽象基底類別,資料型別
@anchor{library/heapq doc}@anchor{284e}@anchor{library/heapq heapq-heap-queue-algorithm}@anchor{284f}@anchor{library/heapq module-heapq}@anchor{6d}@anchor{library/heapq translation-repo}@anchor{2850}
@subsection @code{heapq} --- 堆積佇列 (heap queue) 演算法


@geindex module; heapq

`原始碼：'Lib/heapq.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/heapq.py}


__________________________________________________________________


這個模組實作了堆積佇列 (heap queue) 演算法，亦被稱為優先佇列 (priority queue) 演算法。

最小堆積 (min-heap) 是一顆二元樹，樹上每個父節點的值都小於或等於其子節點的值。我們將這種情況稱為堆積性質不變 (heap invariant)。

對於最小堆積，此實作使用串列，對於所有存在的被比較元素，`k' 都滿足 @code{heap[k] <= heap[2*k+1]} 和 @code{heap[k] <= heap[2*k+2]}。元素是從零開始計數。最小堆積有一個有趣的性質：最小的元素永遠在根節點 @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.

@code{heapq} API 與教科書上的堆積演算法在兩個方面不同：(a) 我們使用從零開始的索引。這使得節點索引和其子節點索引之間的關係變得不那麼明顯，但由於 Python 使用從零開始的索引，所以這樣更適合。(b) 教科書通常專注於最大堆積，因為它們適合原地排序。我們的實作偏向於最小堆積，因為它們更符合 Python @ref{24d,,串列}。

這兩個特性使得可以將堆積視為一個普通的 Python 串列而不會有意外：@code{heap[0]} 是最小的元素，而 @code{heap.sort()} 維持堆積性質不變！

Like @ref{dc3,,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.

要建立一個堆積，使用初始化為 @code{[]} 的串列，或者分別使用 @ref{2851,,heapify()} 或 @ref{221,,heapify_max()} 函式將現有的串列轉換為最小堆積或最大堆積。

提供了以下針對最小堆積的函式：

@geindex heappush() (於 heapq 模組中)
@anchor{library/heapq heapq heappush}@anchor{16b0}
@deffn {函式} heapq.heappush (heap, item)

將值 `item' 推入 `heap'，並維持最小堆積性質不變。
@end deffn

@geindex heappop() (於 heapq 模組中)
@anchor{library/heapq heapq heappop}@anchor{16b1}
@deffn {函式} heapq.heappop (heap)

從 `heap' 取出並回傳最小的元素，維持最小堆積性質不變。如果堆積為空，會引發 @ref{1729,,IndexError}。若要在不取出的情況下存取最小元素，請使用 @code{heap[0]}。
@end deffn

@geindex heappushpop() (於 heapq 模組中)
@anchor{library/heapq heapq heappushpop}@anchor{2852}
@deffn {函式} heapq.heappushpop (heap, item)

將 `item' 放入 heap ，接著從 `heap' 取出並回傳最小的元素。這個組合函式比呼叫 @ref{16b0,,heappush()} 之後呼叫 @ref{16b1,,heappop()} 更有效率。
@end deffn

@geindex heapify() (於 heapq 模組中)
@anchor{library/heapq heapq heapify}@anchor{2851}
@deffn {函式} heapq.heapify (x)

在線性時間內將串列 `x' 原地轉換為最小堆積。
@end deffn

@geindex heapreplace() (於 heapq 模組中)
@anchor{library/heapq heapq heapreplace}@anchor{2853}
@deffn {函式} heapq.heapreplace (heap, item)

從 `heap' 取出並回傳最小的元素，接著將新的 `item' 放進heap。heap 的大小不會改變。如果 heap 是空的會產生 @ref{1729,,IndexError} 錯誤。

這個一次完成的操作會比呼叫 @ref{16b1,,heappop()} 之後呼叫 @ref{16b0,,heappush()} 更有效率，並在維護 heap 的大小不變時更為適當，取出/放入的組合函式一定會從 heap 回傳一個元素並用 `item' 取代他。

函式的回傳值可能會大於被加入的 `item' 。如果這不是你期望發生的，可以考慮使用 @ref{2852,,heappushpop()} 替代，他會回傳 heap 的最小值和 `item' 兩個當中比較小的那個，並將大的留在 heap 內。
@end deffn

提供以下針對最大堆積的函式：

@geindex heapify_max() (於 heapq 模組中)
@anchor{library/heapq heapq heapify_max}@anchor{221}
@deffn {函式} heapq.heapify_max (x)

在線性時間內將串列 `x' 原地轉換為最大堆積。


在 3.14 版被加入.

@end deffn

@geindex heappush_max() (於 heapq 模組中)
@anchor{library/heapq heapq heappush_max}@anchor{222}
@deffn {函式} heapq.heappush_max (heap, item)

將值 `item' 推入最大堆積 `heap'，維持最大堆積性質不變。


在 3.14 版被加入.

@end deffn

@geindex heappop_max() (於 heapq 模組中)
@anchor{library/heapq heapq heappop_max}@anchor{223}
@deffn {函式} heapq.heappop_max (heap)

從最大堆積 `heap' 取出並回傳最大的元素，維持最大堆積性質不變。如果最大堆積為空，會引發 @ref{1729,,IndexError}。若要在不取出的情況下存取最大元素，請使用 @code{maxheap[0]}。


在 3.14 版被加入.

@end deffn

@geindex heappushpop_max() (於 heapq 模組中)
@anchor{library/heapq heapq heappushpop_max}@anchor{225}
@deffn {函式} heapq.heappushpop_max (heap, item)

將 `item' 推入 max-heap `heap'，然後取出並回傳 `heap' 中最大的元素。這個組合動作比先呼叫 @ref{222,,heappush_max()} 再單獨呼叫 @ref{223,,heappop_max()} 更有效率。


在 3.14 版被加入.

@end deffn

@geindex heapreplace_max() (於 heapq 模組中)
@anchor{library/heapq heapq heapreplace_max}@anchor{224}
@deffn {函式} heapq.heapreplace_max (heap, item)

從最大堆積 `heap' 取出並回傳最大的元素，同時推入新的 `item'。最大堆積的大小不會改變。如果最大堆積為空，會引發 @ref{1729,,IndexError}。

The value returned may be smaller than the `item' added.  Refer to the
analogous function @ref{2853,,heapreplace()} for detailed usage notes.


在 3.14 版被加入.

@end deffn

這個模組也提供三個利用 heap 實作的一般用途函式

@geindex merge() (於 heapq 模組中)
@anchor{library/heapq heapq merge}@anchor{1000}
@deffn {函式} heapq.merge (*iterables, key=None, reverse=False)

合併多個已排序的輸入並產生單一且已排序的輸出（舉例：合併來自多個 log 檔中有時間戳記的項目）。回傳一個 @ref{4c3,,iterator} 包含已經排序的值。

和 @code{sorted(itertools.chain(*iterables))} 類似但回傳值是一個 iterable ，不會一次把所有資料都放進記憶體中，並且假設每一個輸入都已經（由小到大）排序過了。

有兩個選用參數，指定時必須被當作關鍵字參數指定。

`key' 參數指定了一個 @ref{1001,,key function}  引數，用來從每一個輸入的元素中決定一個比較的依據。預設的值是 @code{None} （直接比較元素）。

`reverse' 是一個布林值，如果設定為 @code{True} ，則輸入的元素將以相反的比較順序進行合併。為了達成類似 @code{sorted(itertools.chain(*iterables), reverse=True)} 的行為，所有 iterables 必須由大到小排序。


在 3.5 版的變更: 加入選用參數 `key' 和 `reverse' 。

@end deffn

@geindex nlargest() (於 heapq 模組中)
@anchor{library/heapq heapq nlargest}@anchor{2854}
@deffn {函式} heapq.nlargest (n, iterable, key=None)

回傳一個包含資料 `iterable' 中前 `n' 大元素的 list 。如果有指定 `key' 引數，`key' 會是只有一個引數的函式，用來從每一個在 `iterable' 中的元素提取一個比較的依據（例如 @code{key=str.lower} ）。效果相當於 @code{sorted(iterable, key=key, reverse=True)[:n]} 。
@end deffn

@geindex nsmallest() (於 heapq 模組中)
@anchor{library/heapq heapq nsmallest}@anchor{2855}
@deffn {函式} heapq.nsmallest (n, iterable, key=None)

回傳一個包含資料 `iterable' 中前 `n' 小元素的 list 。如果有指定 `key' 引數，`key' 會是只有一個引數的函式，用來從每一個在 `iterable' 中的元素提取一個比較的依據（例如 @code{key=str.lower} ）。效果相當於 @code{sorted(iterable, key=key)[:n]} 。
@end deffn

後兩個函式在 `n' 值比較小時有最好的表現。對於較大的 `n' 值，只用 @ref{dc2,,sorted()} 函式會更有效率。同樣地，當 @code{n==1} 時，使用內建函式 @ref{1106,,min()} 和 @ref{1107,,max()} 會有更好的效率。如果需要重複使用這些函式，可以考慮將 iterable 轉成真正的 heap 。

@menu
* 基礎範例:: 
* 優先佇列實作細節:: 
* 原理:: 

@end menu

@node 基礎範例,優先佇列實作細節,,heapq --- 堆積佇列 heap queue 演算法
@anchor{library/heapq basic-examples}@anchor{2856}
@subsubsection 基礎範例


堆積排序 (heapsort)@footnote{https://en.wikipedia.org/wiki/Heapsort} 可以透過將所有的值推入一個 heap，並且從 heap 中一個接一個彈出最小元素來實作：

@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

雖然類似 @code{sorted(iterable)} ，但跟 @ref{dc2,,sorted()} 不同的是，這個實作不是 stable 的排序。

Heap 中的元素可以是 tuple 。這有利於將要比較的值（例如一個 task 的優先度）和主要資料放在一起排序：

@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 優先佇列實作細節,原理,基礎範例,heapq --- 堆積佇列 heap queue 演算法
@anchor{library/heapq priority-queue-implementation-notes}@anchor{2857}
@subsubsection 優先佇列實作細節


優先佇列 (priority queue)@footnote{https://en.wikipedia.org/wiki/Priority_queue} 是 heap 的常見用途之一，實作優先佇列伴隨著下列挑戰：


@itemize *

@item 
排序的穩定性：如何將兩個擁有相同優先次序 (priority) 的 task 按照他們被加入的順序回傳?

@item 
Tuple的排序在某些情況下會壞掉，例如當 Tuple (priority, task) 的 priorities 相等且 tasks 沒有一個預設的排序時。

@item 
當一個 heap 中 task 的 priority 改變時，如何將它移到 heap 正確的位置上?

@item 
或者一個還沒被解決的 task 需要被刪除時，要如何從佇列中找到並刪除指定的 task?
@end itemize

一個針對前兩個問題的解法是：儲存一個包含 priority、entry count 和 task 三個元素的 tuple 。兩個 task 有相同 priority 時，entry count 會讓兩個 task 能根據加入的順序排序。因為沒有任何兩個 task 擁有相同的 entry count，所以永遠不會直接使用 task 做比較。

task 無法比較的另一個解決方案是建立一個包裝器類別，該類別忽略 task 項目，只比較優先等級：

@example
from dataclasses import dataclass, field
from typing import Any

@@dataclass(order=True)
class PrioritizedItem:
    priority: int
    item: Any=field(compare=False)
@end example

剩下的問題可以藉由找到要刪除的 task 並更改它的 priority 或者直接將它移除。尋找一個 task 可以使用一個 dictionary 指向佇列當中的 entry 。

移除 entry 或更改它的 priority 更為困難，因為這會破壞 heap 的性質。所以一個可行的方案是將原本的 entry 做一個標記表示它已經被刪除，並新增一個擁有新的 priority 的 entry：

@example
pq = []                         # 在 heap 中的 entry 串列
entry_finder = @{@}               # task 對應到 entry 的對映
REMOVED = '<removed-task>'      # 被刪除的 task 的佔位器
counter = itertools.count()     # 唯一的序列計數

def add_task(task, priority=0):
    '新增一個 task 或更新一個已存在 task 的 priority'
    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):
    '將一個已存在的 task 標記為 REMOVED。如果找不到會引發 KeyError。'
    entry = entry_finder.pop(task)
    entry[-1] = REMOVED

def pop_task():
    '移除並回傳最低 priority 的 task。如果 heap 是空的會引發 KeyError。'
    while pq:
        priority, count, task = heappop(pq)
        if task is not REMOVED:
            del entry_finder[task]
            return task
    raise KeyError('從空的優先佇列中 pop 出元素')
@end example

@node 原理,,優先佇列實作細節,heapq --- 堆積佇列 heap queue 演算法
@anchor{library/heapq theory}@anchor{2858}
@subsubsection 原理


Heap 是一個陣列對於所有從0開始的 index `k' 都存在性質 @code{a[k] <= a[2*k+1]} 和 @code{a[k] <= a[2*k+2]} 。為了方便比較，不存在的元素被視為無限大。Heap 的一個有趣的性質是：@code{a[0]} 永遠是最小的元素。

上述乍看之下有些奇怪的不變式，是為了實作一個對記憶體來說有效率的方法，其表示方式如同錦標賽一般。下列的數字為 `k'，而不是 @code{a[k]}：

@example
                               0

              1                                 2

      3               4                5               6

  7       8       9       10      11      12      13      14

15 16   17 18   19 20   21 22   23 24   25 26   27 28   29 30
@end example

在上面的樹當中，每個單元 `k' 都會位在 @code{2*k+1} 與 @code{2*k+2} 上方。如同體育賽事常見的錦標賽般，每個單元可視為其下方兩個單元當中的贏家，我們可以透過追溯整棵樹來找到該贏家曾經對戰過的所有對手。然而，在許多電腦應用中，我們不需要追溯贏家的完整對戰歷史。為了能更有效率地使用記憶體，當一個贏家晉級勝出時，我們用下方較低層級的另一個項目來取代它，至此規則變為一個單元以及它下方兩個單元，包含三個不同項目，但是最上方的單元「勝過」下方兩個單元。

如果能確保滿足這個 heap 的不變式，那麼索引 0 顯然是最終的贏家。移除並找到「下一個」贏家最簡單的演算法為：將一個輸家（例如上圖中的單元 30）移動到位置 0，然後從新的位置 0 不斷與下方的位置交換值來向下傳遞，直到滿足不變式為止。這個過程的複雜度顯然是樹的節點數目的對數級別。透過對所有項目疊代，可以得到一個複雜度為 `O'(`n' log `n') 的排序。

這種排序有個好處，只要插入的項目沒有「贏過」你最後提取、索引為 0 的元素，你就可以在排序進行的同時有效率地插入新項目。這在模擬情境當中特別有用，其中樹能夠保存所有輸入事件，而「贏」意味著最小排程時間。當一個事件排程其它事件的執行時，因這些事件仍在等待進行，所以很容易將它們插入 heap 當中。因此， heap 是一個實現排程器的優秀資料結構（這就是我用以實作 MIDI 編曲器的方法 :-）。

多種用於實作排程器的結構現今已被廣泛研究，heap 對此非常有用，因為它們速度相當快，且速度幾乎不受其他因素影響，最壞情況與平均狀況差異無幾。也有其它整體說來更有效率的方法，然而它們的最壞情況可能會非常糟糕。

Heap 在為儲存於硬碟上的大量資料進行排序也非常有用。你可能已經知道，大量資料排序涉及 "runs" 的產生（也就是預先排序的序列，其大小通常與 CPU 記憶體的大小有關），之後再對這些 run 合併，而這些合併的過程通常相當巧妙 @footnote{
現今的磁碟平衡演算法因為硬碟查找能力而更加複雜難解。在沒有查找功能的裝置如大型磁帶機，狀況又不一樣了，人們必須機智地確保（遠遠提前）每次於磁帶上移動都盡可能是最有效率的（也就是盡可能更好地「推進」合併的過程）。有些磁帶甚至能夠向後讀取，這也被用來避免倒轉的時間。相信我，真正優秀的磁帶排序看起來相當壯觀！排序一直以來都是一門偉大的藝術！:-)
}。很重要的一點是，初始排序產生的 run 越長越好。錦標賽是達成這一點的好方法，若你用所有可用記憶體來舉行一場錦標賽，並透過替換與向下交換來處理所有適配目前 run 的值，那麼對於隨機產生的輸入，將可以產生長度兩倍於記憶體大小的 run。對於已模糊排序過的輸入，效果更好。

此外，若你將索引為 0 的項目輸出至磁碟，並取得一個無法適配目前錦標賽的輸入（因為該值「勝過」最後的輸出值），則該輸入值就無法插入至 heap 當中，因此 heap 的大小會減小。釋放出來的記憶體可以巧妙地立即再被運用，逐步建構出第二個 heap，其大小增加的速度會與第一個 heap 減少的速度一致。當第一個 heap 完全消失時，你可以切換至第二個 heap 開啟一個新 run 。這真是個聰明且相當有效率的做法！

總結來說，heap 是值得了解的有用記憶體結構。我在一些應用中使用它們，我認為能有一個 'heap' 模組是很棒的。:-)

@subsubheading 註解


@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 --- 高效率的數值型陣列,heapq --- 堆積佇列 heap queue 演算法,資料型別
@anchor{library/bisect doc}@anchor{2859}@anchor{library/bisect bisect-array-bisection-algorithm}@anchor{285a}@anchor{library/bisect module-bisect}@anchor{12}@anchor{library/bisect translation-repo}@anchor{285b}
@subsection @code{bisect} --- 陣列二分演算法 (Array bisection algorithm)


@geindex module; bisect

@c example based on the PyModules FAQ entry by Aaron Watters <arw@pythonpros.com>

`原始碼：'Lib/bisect.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/bisect.py}


__________________________________________________________________


這個模組維護一個已經排序過的 list ，當我們每次做完插入後不需要再次排序整個 list 。一個很長的 list 的比較操作很花費時間，可以透過線性搜尋或頻繁地詢問來改善。

這個模組被稱為 @ref{12,,bisect} 是因為它使用基本二分演算法來完成其工作。不像其它搜尋特定值的二分法工具，本模組中的函式旨在定位插入點。因此，這些函式永遠不會呼叫 @ref{ce9,,__eq__()} 方法來確認是否找到一個值。相反地，這些函式只呼叫 @ref{14a1,,__lt__()} 方法，並在陣列中的值回傳一個插入點。

@cartouche
@quotation 備註 
The functions in this module are not thread-safe. If multiple threads
concurrently use @ref{12,,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 @ref{12,,bisect} function
is operating on it, the result is undefined. For example, using
@ref{285c,,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{285d}
此模組提供下面的函式：

@geindex bisect_left() (於 bisect 模組中)
@anchor{library/bisect bisect bisect_left}@anchor{285e}
@deffn {函式} bisect.bisect_left (a, x, lo=0, hi=len(a), *, key=None)

在 `a' 當中找到一個位置，讓 `x' 插入後 `a' 仍然是排序好的。參數 `lo' 和 `hi' 用來指定 list 中應該被考慮的子區間，預設是考慮整個 list 。如果 `a' 裡面已經有 `x' 出現，插入的位置會在所有 `x' 的前面（左邊）。回傳值可以被當作 @code{list.insert()} 的第一個參數，但列表 `a' 必須先排序過。

回傳的插入點 `ip' 將陣列 `a' 劃分為左右兩個切片，使得對於左切片而言 @code{all(elem < x for elem in a[lo : ip])} 為真，對於右切片而言 @code{all(elem >= x for elem in a[ip : hi])} 為真。

`key' 可指定一個單一參數的 @ref{1001,,key function}。函式將套用此 function 在陣列所有元素以得到比較值來計算順位。注意此 function 只會套用在陣列中的元素，不會套用在 `x'。

若 `key' 為 @code{None}，元素將直接進行比較，不會呼叫任何鍵函式。


在 3.10 版的變更: 新增 `key' 參數。

@end deffn

@geindex bisect_right() (於 bisect 模組中)
@geindex bisect() (於 bisect 模組中)
@anchor{library/bisect bisect bisect_right}@anchor{285f}
@deffn {函式} bisect.bisect_right (a, x, lo=0, hi=len(a), *, key=None)
@anchor{library/bisect bisect bisect}@anchor{2860}
@deffnx {函式} bisect.bisect (a, x, lo=0, hi=len(a), *, key=None)

類似 @ref{285e,,bisect_left()}，但回傳的插入位置會在所有 `a' 當中的 `x' 的後面（右邊）。

回傳的插入點 `ip' 將陣列 `a' 劃分為左右兩個切片，使得對於左切片而言 @code{all(elem <= x for elem in a[lo : ip])} 為真，對於右切片而言 @code{all(elem > x for elem in a[ip : hi])} 為真。


在 3.10 版的變更: 新增 `key' 參數。

@end deffn

@geindex insort_left() (於 bisect 模組中)
@anchor{library/bisect bisect insort_left}@anchor{285c}
@deffn {函式} bisect.insort_left (a, x, lo=0, hi=len(a), *, key=None)

將元素 `x' 插入 list `a'，並維持順序。

此函式先使用 @ref{285e,,bisect_left()} 搜尋插入位置，接著用 @ref{228c,,insert()} 於 `a' 以將 `x' 插入，並維持添加元素後的順序。

此函式只有在搜尋時會使用 `key' 函式，插入時不會。

注意雖然搜尋是 `O'(log `n')，但插入是 `O'(`n')，因此此函式整體時間複雜度是 `O'(`n')。


在 3.10 版的變更: 新增 `key' 參數。

@end deffn

@geindex insort_right() (於 bisect 模組中)
@geindex insort() (於 bisect 模組中)
@anchor{library/bisect bisect insort_right}@anchor{2861}
@deffn {函式} bisect.insort_right (a, x, lo=0, hi=len(a), *, key=None)
@anchor{library/bisect bisect insort}@anchor{2862}
@deffnx {函式} bisect.insort (a, x, lo=0, hi=len(a), *, key=None)

類似 @ref{285c,,insort_left()}，但插入的位置會在所有 `a' 當中的 `x' 的後面（右邊）。

此函式先使用 @ref{285f,,bisect_right()} 搜尋插入位置，接著用 @ref{228c,,insert()} 於 `a' 以將 `x' 插入，並維持添加元素後的順序。

此函式只有在搜尋時會使用 `key' 函式，插入時不會。

注意雖然搜尋是 `O'(log `n')，但插入是 `O'(`n')，因此此函式整體時間複雜度是 `O'(`n')。


在 3.10 版的變更: 新增 `key' 參數。

@end deffn

@menu
* 效能考量:: 
* 搜尋一個已排序的 list:: 
* 範例: 範例<3>. 

@end menu

@node 效能考量,搜尋一個已排序的 list,,bisect --- 陣列二分演算法 Array bisection algorithm
@anchor{library/bisect performance-notes}@anchor{2863}
@subsubsection 效能考量


若在需要關注寫入時間的程式當中使用 `bisect()' 和 `insort()'，請特別注意幾個事項：


@itemize *

@item 
二分法在一段範圍的數值中做搜尋的效率較佳，但若是要存取特定數值，使用字典的表現還是比較好。

@item 
`insort()' 函式的複雜度為 `O'(`n')，因為對數搜尋是以線性時間的插入步驟所主導 (dominate)。

@item 
搜尋函式為無狀態的 (stateless)，且鍵函式會在使用過後被丟棄。因此，如果搜尋函式被使用於迴圈當中，鍵函式會不斷被重複呼叫於相同的 list 元素。如果鍵函式執行速度不快，請考慮將其以 @ref{175e,,functools.cache()} 包裝起來以減少重複的計算。另外，也可以透過搜尋預先計算好的鍵列表 (array of precomputed keys) 來定位插入點（如下方範例所示）。
@end itemize


@subsubheading 也參考



@itemize *

@item 
有序容器 (Sorted Collections)@footnote{https://grantjenks.com/docs/sortedcollections/} 是一個使用 `bisect' 來管理資料之有序集合的高效能模組。

@item 
SortedCollection recipe@footnote{https://code.activestate.com/recipes/577197-sortedcollection/} 使用二分法來建立一個功能完整的集合類別 (collection class) 並帶有符合直覺的搜尋方法 (search methods) 與支援鍵函式。鍵會預先被計算好，以減少搜尋過程中多餘的鍵函式呼叫。
@end itemize


@node 搜尋一個已排序的 list,範例<3>,效能考量,bisect --- 陣列二分演算法 Array bisection algorithm
@anchor{library/bisect searching-sorted-lists}@anchor{2864}
@subsubsection 搜尋一個已排序的 list


上面的 @ref{285d,,bisect functions} 在找到數值插入點上很有用，但一般的數值搜尋任務上就不是那麼的方便。以下的五個函式展示了如何將其轉換成標準的有序列表查找函式：

@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 範例<3>,,搜尋一個已排序的 list,bisect --- 陣列二分演算法 Array bisection algorithm
@anchor{library/bisect examples}@anchor{2865}
@subsubsection 範例

@anchor{library/bisect bisect-example}@anchor{2866}
@ref{2860,,bisect()} 函式可用於數值表中的查找 (numeric table lookup)，這個範例使用 @ref{2860,,bisect()} 以基於一組有序的數值分界點來為一個考試成績找到相對應的字母等級：90 以上是 'A'、80 到 89 為 'B'，依此類推：

@example
>>> def grade(score, breakpoints=[60, 70, 80, 90], grades='FDCBA'):
...     i = bisect(breakpoints, score)
...     return grades[i]
...
>>> [grade(score) for score in [33, 99, 77, 70, 89, 90, 100]]
['F', 'A', 'C', 'C', 'B', 'A', 'A']
@end example

@ref{2860,,bisect()} 與 @ref{2862,,insort()} 函式也適用於內容為 tuples（元組）的 lists，`key' 引數可被用以取出在數值表中作為排序依據的欄位：

@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')
... ]

>>> # 找到 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')

>>> # 插入一部電影並保持排序
>>> 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

如果鍵函式會消耗較多運算資源，那可以在預先計算好的鍵列表中搜尋該紀錄的索引值，以減少重複的函式呼叫：

@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 --- 高效率的數值型陣列,weakref --- 弱參照,bisect --- 陣列二分演算法 Array bisection algorithm,資料型別
@anchor{library/array doc}@anchor{2867}@anchor{library/array array-efficient-arrays-of-numeric-values}@anchor{2868}@anchor{library/array module-array}@anchor{8}@anchor{library/array translation-repo}@anchor{2869}
@subsection @code{array} --- 高效率的數值型陣列


@geindex module; array

@geindex arrays（陣列）


__________________________________________________________________


這個模組定義了一個物件型別，可以簡潔的表達一個包含基本數值的陣列：字元、整數、浮點數。陣列是一個非常類似 list（串列）的序列型別，除了陣列會限制儲存的物件型別。在建立陣列時可以使用一個字元的 `type code' 來指定儲存的資料型別。以下為有被定義的 type codes：


@multitable {xxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxx} 
@headitem

Type code

@tab

C Type

@tab

Python Type

@tab

所需的最小位元組 (bytes)

@tab

註解

@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{'f'}

@tab

float

@tab

float

@tab

4

@tab

@item

@code{'d'}

@tab

double

@tab

float

@tab

8

@tab

@end multitable


註解：


@enumerate 

@item 
根據平台的不同，它有可能是 16 位元或者 32 位元。


在 3.9 版的變更: 目前 @code{array('u')} 使用 @code{wchar_t} 取代已棄用的 @code{Py_UNICODE} 作為 C type。這個異動並沒有影響到它的作用，因為自從 Python 3.3 開始 @code{Py_UNICODE} 即為 @code{wchar_t} 的別名。



Deprecated since version 3.3, will be removed in version 3.16: 請改用 @code{'w'} typecode。


@item 

在 3.13 版被加入.

@end enumerate

實際上數值的表示方法是被機器的架構所決定（更精準地說，被 C 的實作方法決定）。實際的大小可以透過 @ref{286a,,array.itemsize} 屬性存取。

這個模組定義了以下項目：

@geindex typecodes (於 array 模組中)
@anchor{library/array array typecodes}@anchor{286b}
@deffn {資料} array.typecodes

一個包含所有可用的 type codes 的字串。
@end deffn

這個模組定義了下方的型別：

@geindex array (array 中的類別)
@anchor{library/array array array}@anchor{4b9}
@deffn {類別} array.array (typecode[, initializer])

一個新的陣列中的元素被 `typecode' 限制，並由選用的 `initializer' 參數初始化，`initializer' 必須是一個 @ref{192,,bytes} 或 @ref{343,,bytearray} 物件、一個 Unicode 字串或包含適當型別元素的可疊代物件 (iterable)。

如果給定的是一個 @ref{192,,bytes} 或 @ref{343,,bytearray} 物件，新的陣列初始化時會傳入 @ref{1472,,frombytes()} 方法；如為 Unicode 字串則會傳入 @ref{286c,,fromunicode()} 方法；其他情況時， 一個 initializer 的可疊代物件將被傳入 @ref{286d,,extend()} 方法之中來將初始項目新增至陣列。

陣列支援常見的序列操作，包含索引 (indexing)、切片 (slicing)、串接 (concatenation)、相乘 (multiplication) 等。當使用切片進行賦值時，賦值的陣列必須具備相同的 type code，其他型別的數值將導致 @ref{198,,TypeError}。陣列同時也實作了緩衝區介面，可以在任何支援 @ref{193,,bytes-like objects} 的地方使用。

引發@ref{1b70,,稽核事件 (auditing event)} @code{array.__new__} 並附帶引數 @code{typecode}、@code{initializer}。

@geindex typecode (array.array 的屬性)
@anchor{library/array array array typecode}@anchor{286e}
@deffn {屬性} typecode

typecode 字元被用在建立陣列時。
@end deffn

@geindex itemsize (array.array 的屬性)
@anchor{library/array array array itemsize}@anchor{286a}
@deffn {屬性} itemsize

陣列當中的一個元素在內部需要的位元組長度。
@end deffn

@geindex append() (array.array 的方法)
@anchor{library/array array array append}@anchor{286f}
@deffn {方法} append (x)

新增一個元素 `x' 到陣列的最尾端。
@end deffn

@geindex buffer_info() (array.array 的方法)
@anchor{library/array array array buffer_info}@anchor{2870}
@deffn {方法} buffer_info ()

回傳一個 tuple @code{(address, length)} 表示目前的記憶體位置和陣列儲存元素的緩衝區記憶體長度。緩衝區的長度單位是位元組，並可以用 @code{array.buffer_info()[1] * array.itemsize} 計算得到。這偶爾會在底層操作需要記憶體位置的輸出輸入時很有用，例如 @code{ioctl()} 指令。只要陣列存在且沒有使用任何更改長度的操作時，回傳的數值就有效。

@cartouche
@quotation 備註 
當使用來自 C 或 C++ 程式碼（這是唯一使得這個資訊有效的途徑）的陣列物件時，更適當的做法是使用陣列物件支援的緩衝區介面。這個方法維護了向後兼容性，並應該在新的程式碼中避免。關於緩衝區介面的文件在@ref{260,,緩衝協定 (Buffer Protocol)}。
@end quotation
@end cartouche
@end deffn

@geindex byteswap() (array.array 的方法)
@anchor{library/array array array byteswap}@anchor{2871}
@deffn {方法} byteswap ()

"Byteswap" 所有陣列中的物件。這只有支援物件長度為 1、2、4 或 8 位元組的陣列，其他型別的值會導致 @ref{244,,RuntimeError}。這在從機器讀取位元順序不同的檔案時很有用。
@end deffn

@geindex count() (array.array 的方法)
@anchor{library/array array array count}@anchor{2872}
@deffn {方法} count (x)

回傳 `x' 在陣列中出現了幾次。
@end deffn

@geindex extend() (array.array 的方法)
@anchor{library/array array array extend}@anchor{286d}
@deffn {方法} extend (iterable)

從 `iterable' 中新增元素到陣列的尾端，如果 `iterable' 是另一個陣列，它必須有完全相同的 type code，如果不同會導致 @ref{198,,TypeError}。如果 `iterable' 不是一個陣列，它必須可以被疊代 (iterable) 且其中的元素必須是可以被加入陣列中的正確型別。
@end deffn

@geindex frombytes() (array.array 的方法)
@anchor{library/array array array frombytes}@anchor{1472}
@deffn {方法} frombytes (buffer)

從 @ref{193,,bytes-like object} 中新增元素。讀取時會將其內容當作一個機器數值組成的陣列（就像從檔案中使用 @ref{14c1,,fromfile()} 方法讀出的資料）。


在 3.2 版被加入: 將 @code{fromstring()} 更名為 @ref{1472,,frombytes()}，使其更加清晰易懂。

@end deffn

@geindex fromfile() (array.array 的方法)
@anchor{library/array array array fromfile}@anchor{14c1}
@deffn {方法} fromfile (f, n)

從 @ref{13c4,,file object} `f' 讀取 `n' 個元素（作為機器數值），接著將這些元素加入陣列的最尾端。如果只有少於 `n' 個有效的元素會導致 @ref{14da,,EOFError}，但有效的元素仍然會被加入陣列中。
@end deffn

@geindex fromlist() (array.array 的方法)
@anchor{library/array array array fromlist}@anchor{2873}
@deffn {方法} fromlist (list)

從 list 中新增元素。這等價於 @code{for x in list: a.append(x)}，除了有型別錯誤產生時，陣列會保持原狀不會被更改。
@end deffn

@geindex fromunicode() (array.array 的方法)
@anchor{library/array array array fromunicode}@anchor{286c}
@deffn {方法} fromunicode (s)

用給定的 Unicode 字串擴展這個陣列。陣列的 type code 必須是 @code{u} 或 @code{'w'}；其他的型別會導致 @ref{2eb,,ValueError} 被引發。使用 @code{array.frombytes(unicodestring.encode(enc))} 來新增 Unicode 資料到一個其他型別的陣列。
@end deffn

@geindex index() (array.array 的方法)
@anchor{library/array array array index}@anchor{9da}
@deffn {方法} index (x[, start[, stop]])

回傳 `i' 的最小數值，使得 `i' 成為陣列之中第一次出現 `x' 的索引。選擇性的引數 `start' 及 `stop' 則可以被用來在指定的陣列空間中搜尋 `x'。如果 `x' 不存在將導致 @ref{2eb,,ValueError}。


在 3.10 版的變更: 新增選擇性的參數 `start' 及 `stop'。

@end deffn

@geindex insert() (array.array 的方法)
@anchor{library/array array array insert}@anchor{2874}
@deffn {方法} insert (i, x)

在位置 `i' 之前插入一個元素 `x'。負數的索引值會從陣列尾端開始數。
@end deffn

@geindex pop() (array.array 的方法)
@anchor{library/array array array pop}@anchor{2875}
@deffn {方法} pop ([i])

移除並回傳陣列索引值 `i' 的元素。選擇性的引數 `i' 預設為 @code{-1}，所以預設會刪除並回傳最後一個元素。
@end deffn

@geindex remove() (array.array 的方法)
@anchor{library/array array array remove}@anchor{2876}
@deffn {方法} remove (x)

從陣列中刪除第一個出現的 `x'。
@end deffn

@geindex clear() (array.array 的方法)
@anchor{library/array array array clear}@anchor{4bb}
@deffn {方法} clear ()

從陣列中刪除所有元素。


在 3.13 版被加入.

@end deffn

@geindex reverse() (array.array 的方法)
@anchor{library/array array array reverse}@anchor{2877}
@deffn {方法} reverse ()

反轉陣列中元素的順序。
@end deffn

@geindex tobytes() (array.array 的方法)
@anchor{library/array array array tobytes}@anchor{1471}
@deffn {方法} tobytes ()

將陣列轉為另一個機器數值組成的陣列並回傳它的位元組表示（跟用 @ref{14c2,,tofile()} 方法寫入檔案時的位元序列相同）。


在 3.2 版被加入: 為了明確性，過去的 @code{tostring()} 已更名為 @ref{1471,,tobytes()}。

@end deffn

@geindex tofile() (array.array 的方法)
@anchor{library/array array array tofile}@anchor{14c2}
@deffn {方法} tofile (f)

將所有元素（作為機器數值）寫入 @ref{13c4,,file object} `f'。
@end deffn

@geindex tolist() (array.array 的方法)
@anchor{library/array array array tolist}@anchor{2878}
@deffn {方法} tolist ()

不更改元素，將陣列轉為一般的 list。
@end deffn

@geindex tounicode() (array.array 的方法)
@anchor{library/array array array tounicode}@anchor{2879}
@deffn {方法} tounicode ()

將陣列轉為一個 Unicode 字串。陣列的型別必須為 @code{u} 或 @code{'w'}；其他型別的陣列會引發 @ref{2eb,,ValueError}。請使用 @code{array.tobytes().decode(enc)} 來為其他型別的陣列轉為 Unicode 字串。
@end deffn
@end deffn

陣列物件的字串表示形式為 @code{array(typecode, initializer)}。若為空陣列則參數 `initializer' 被省略，若 `typecode' 是 @code{'u'} 或 @code{'w'} 將被表示為 Unicode 字串，其他情況則被表示為由數字組成的 list。只要 @ref{4b9,,array} class（類別）透過 @code{from array import array} 的方式引入，便能確保該字串表示能透過 @ref{49e,,eval()} 轉換回一個擁有相同型別及數值的陣列。如果它包含相應的浮點值，@code{inf} 和 @code{nan} 也必須被定義。範例：

@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 @ref{db,,struct} 模組

將包含不同資料類型的二進位資料包裝與解開包裝。

@item NumPy@footnote{https://numpy.org/}

NumPy 套件定義了另一個陣列型別
@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 --- 弱參照,types --- 動態型別建立與內建型別名稱,array --- 高效率的數值型陣列,資料型別
@anchor{library/weakref doc}@anchor{287a}@anchor{library/weakref mod-weakref}@anchor{1108}@anchor{library/weakref module-weakref}@anchor{11a}@anchor{library/weakref translation-repo}@anchor{287b}@anchor{library/weakref weakref-weak-references}@anchor{287c}
@subsection @code{weakref} --- 弱參照


@geindex module; weakref

`原始碼：'Lib/weakref.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/weakref.py}


__________________________________________________________________


@ref{11a,,weakref} 模組允許 Python 程式設計師建立對物件的 `弱參照'。

@c When making changes to the examples in this file, be sure to update
@c Lib/test/test_weakref.py::libreftest too!

在以下文章中，術語 `參照目標 (referent)' 表示被弱參照所參考的物件。

對物件的弱參照不足以使物件保持存在：當對參照目標的唯一剩下的參照是弱參照時，@ref{1765,,garbage collection} 可以自由地銷毀參照目標並將其記憶體重新用於其他用途。然而，在物件被確實銷毀之前，即使沒有對該物件的強參照 (strong reference)，弱參照也可能會回傳該物件。

弱參照的主要用途是實作保存大型物件的快取或對映，其不希望大型物件僅僅因為它出現在快取或對映中而保持存在。

例如，如果你有許多大型的二進位影像物件，你可能會想要為每個物件關聯 (associate) 一個名稱。如果你使用 Python 字典將名稱對映到影像，或將影像對映到名稱，則影像物件將保持存活，僅因為它們在字典中作為值 (value) 或鍵 (key) 出現。@ref{11a,,weakref} 模組提供的 @ref{188f,,WeakKeyDictionary} 和 @ref{1890,,WeakValueDictionary} 類別是另一種選擇，它們使用弱參照來建構對映，這些對映不會僅因為物件出現在對映物件中而使物件保持存活。例如，如果一個影像物件是 @ref{1890,,WeakValueDictionary} 中的一個值，那麼當對該影像物件最後的參照是弱對映 (weak mapping) 所持有的弱參照時，垃圾回收 (garbage collection) 可以回收該物件，且其對應的條目在弱對映中會被完全地刪除。

@ref{188f,,WeakKeyDictionary} 和 @ref{1890,,WeakValueDictionary} 在其實作中使用弱參照，在弱參照上設定回呼函式，此弱參照在垃圾回收取回鍵或值時通知弱字典。@ref{7ee,,WeakSet} 實作了 @ref{184,,set} 介面，但保留對其元素的弱參照，就像 @ref{188f,,WeakKeyDictionary} 一樣。

@ref{c66,,finalize} 提供了一種直接的方法來註冊在物件被垃圾回收時呼叫的清理函式。這比在原始弱參照上設定回呼函式更容易使用，因為模組在物件被回收前會自動確保最終化器 (finalizer) 保持存活。

大多數程式應該發現使用這些弱容器種類之一或 @ref{c66,,finalize} 就足夠了—通常不需要直接建立自己的弱參照。低層級的機制由 @ref{11a,,weakref} 模組公開，以利於進階用途。

並非所有物件都可以被弱參照。支援弱參照的物件包括類別實例、用 Python （但不是C）編寫的函式、實例方法、集合、凍結集合 (frozenset)、一些@ref{13c4,,檔案物件}、@ref{125c,,產生器}、類型物件、socket、陣列、雙向佇列、正規表示式模式物件和程式碼物件。


在 3.2 版的變更: 新增了對 thread.lock、threading.Lock 和程式碼物件的支援。


一些內建型別，例如 @ref{24d,,list} 和 @ref{183,,dict} 不直接支援弱參照，但可以透過子類別化來支援：

@example
class Dict(dict):
    pass

obj = Dict(red=1, green=2, blue=3)   # 這個物件是可被弱參照的
@end example

其他內建型別，例如 @ref{60c,,tuple} 和 @ref{19b,,int} 即使在子類別化時也不支援弱參照。

擴充型別 (extension type) 可以輕易地支援弱參照；請參閱 @ref{287d,,Weak Reference Support}。

當為給定的型別定義 @code{__slots__} 時，弱參照支援將被停用，除非 @code{'__weakref__'} 字串也存在於 @code{__slots__} 宣告的字串序列中。詳情請參閱 @ref{2230,,__slots__ 文件}。

@geindex ref (weakref 中的類別)
@anchor{library/weakref weakref ref}@anchor{11eb}
@deffn {類別} weakref.ref (object[, callback])

回傳對 `object' 的弱參照。如果參照目標仍存活，則可以透過呼叫參照物件來取回原始物件；如果參照目標已不存活，呼叫參照物件將導致 @ref{87e,,None} 被回傳。如果 `callback' 被提供而非 @ref{87e,,None}，且回傳的弱參照物件仍存活，那麼當物件即將被最終化 (finalize) 時，回呼將被呼叫；弱參照物件將作為唯一的參數傳遞給回呼；參照物件將不再可用。

為同一個物件建構多個弱參照是可行的。為每個弱參照註冊的回呼將按照最新到最舊註冊的回呼順序來被呼叫。

回呼引發的例外將在標準錯誤輸出中被註明，但無法被傳播；它們的處理方式與物件的 @ref{11f8,,__del__()} 方法引發的例外完全相同。

如果 `object' 是@ref{81d,,可雜湊的}，那麼弱參照就是可雜湊的。即使在 `object' 被刪除後，它們仍將保留其雜湊值。如果僅在 `object' 刪除後才第一次呼叫 @ref{7fa,,hash()}，則該呼叫將引發 @ref{198,,TypeError}。

弱參照支援相等性的測試，但不支援排序。如果參照目標仍存活，則兩個參照與其參照目標具有相同的相等關係（無論 `callback' 如何）。如果任一參照目標已被刪除，則僅當參照物件是同一物件時，參照才相等。

這是一個可子類別化的型別，而不是一個工廠函式。

@geindex __callback__ (weakref.ref 的屬性)
@anchor{library/weakref weakref ref __callback__}@anchor{11ec}
@deffn {屬性} __callback__

此唯讀屬性回傳目前與弱參照關聯的回呼。如果沒有回呼或弱參照的參照目標已不存活，那麼該屬性的值為 @code{None}。
@end deffn


在 3.4 版的變更: 新增 @ref{11ec,,__callback__} 屬性。

@end deffn

@geindex proxy() (於 weakref 模組中)
@anchor{library/weakref weakref proxy}@anchor{c3d}
@deffn {函式} weakref.proxy (object[, callback])

回傳一個使用弱參照的 `object' 的代理 (proxy)。這支援在大多數情境中使用代理，而不需要對弱參照物件明確地取消參照。回傳的物件將具有 @code{ProxyType} 或 @code{CallableProxyType} 型別，具體取決於 `object' 是否為可呼叫物件。無論參照目標如何，代理物件都不是 @ref{81d,,hashable}；這避免了與其基本可變物件本質相關的許多問題，並阻止它們作為字典的鍵被使用。`callback' 與 @ref{11eb,,ref()} 函式的同名參數是相同的。

在參照目標被垃圾回收後存取代理物件的屬性會引發 @ref{1701,,ReferenceError}。


在 3.8 版的變更: 提供對代理物件的運算子支援，以包括矩陣乘法運算子 @code{@@} 和 @code{@@=}。

@end deffn

@geindex getweakrefcount() (於 weakref 模組中)
@anchor{library/weakref weakref getweakrefcount}@anchor{287e}
@deffn {函式} weakref.getweakrefcount (object)

回傳參照 `object' 的弱參照和代理的數量。
@end deffn

@geindex getweakrefs() (於 weakref 模組中)
@anchor{library/weakref weakref getweakrefs}@anchor{287f}
@deffn {函式} weakref.getweakrefs (object)

回傳參照 `object' 的所有弱參照和代理物件的一個串列。
@end deffn

@geindex WeakKeyDictionary (weakref 中的類別)
@anchor{library/weakref weakref WeakKeyDictionary}@anchor{188f}
@deffn {類別} weakref.WeakKeyDictionary ([dict])

弱參照鍵的對映類別。當不再有對鍵的強參照時，字典中的條目將被丟棄。這可用於將附加資料與應用程式其他部分擁有的物件相關聯，而無需向這些物件新增屬性。這對於覆蓋屬性存取的物件特別有用。

請注意，當將與現有鍵具有相同值的鍵（但識別性不相等）插入字典時，它會替換該值，但不會替換現有鍵。因此，當刪除對原始鍵的參照時，它也會刪除字典中的條目：

@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

一個變通的解法是在重新賦值 (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 版的變更: 新增對 @code{|} 和 @code{|=} 運算子的支持，如 
@geindex Python Enhancement Proposals; PEP 584
PEP 584@footnote{https://peps.python.org/pep-0584/} 中所說明。

@end deffn

@ref{188f,,WeakKeyDictionary} 物件有一個直接公開內部參照的附加方法。參照在被使用時不保證是 "存活的"，因此在使用之前需要檢查呼叫參照的結果。這可以用來防止建立會導致垃圾回收器保留鍵的時間超過其所需時間的參照。

@geindex keyrefs() (weakref.WeakKeyDictionary 的方法)
@anchor{library/weakref weakref WeakKeyDictionary keyrefs}@anchor{2880}
@deffn {方法} WeakKeyDictionary.keyrefs ()

回傳對鍵的弱參照的可疊代物件。
@end deffn

@geindex WeakValueDictionary (weakref 中的類別)
@anchor{library/weakref weakref WeakValueDictionary}@anchor{1890}
@deffn {類別} weakref.WeakValueDictionary ([dict])

弱參照值的對映類別。當不再存在對值的強參照時，字典中的條目將被丟棄。


在 3.9 版的變更: 新增對 @code{|} 和 @code{|=} 運算子的支持，如 
@geindex Python Enhancement Proposals; PEP 584
PEP 584@footnote{https://peps.python.org/pep-0584/} 中所說明。

@end deffn

@ref{1890,,WeakValueDictionary} 物件有一個附加方法，它與 @ref{2880,,WeakKeyDictionary.keyrefs()} 方法有相同的問題。

@geindex valuerefs() (weakref.WeakValueDictionary 的方法)
@anchor{library/weakref weakref WeakValueDictionary valuerefs}@anchor{2881}
@deffn {方法} WeakValueDictionary.valuerefs ()

回傳對值的弱參照的可疊代物件。
@end deffn

@geindex WeakSet (weakref 中的類別)
@anchor{library/weakref weakref WeakSet}@anchor{7ee}
@deffn {類別} weakref.WeakSet ([elements])

保留對其元素的弱參照的集合類別。當不再存在對某個元素的強參照時，該元素將被丟棄。
@end deffn

@geindex WeakMethod (weakref 中的類別)
@anchor{library/weakref weakref WeakMethod}@anchor{11ea}
@deffn {類別} weakref.WeakMethod (method[, callback])

一個特製的 @ref{11eb,,ref} 子類別，其模擬對繫結方法 (bound method) （即在類別上定義並在實例上查找的方法）的弱參照。由於繫結方法是短暫存在的，因此標準弱參照無法保留它。@ref{11ea,,WeakMethod} 有特殊的程式碼來重新建立繫結方法，直到物件或原始函式死亡：

@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' 與 @ref{11eb,,ref()} 函式的同名參數是相同的。


在 3.4 版被加入.

@end deffn

@geindex finalize (weakref 中的類別)
@anchor{library/weakref weakref finalize}@anchor{c66}
@deffn {類別} weakref.finalize (obj, func, /, *args, **kwargs)

回傳可呼叫的最終化器物件，此物件在 `obj' 被垃圾回收時會被呼叫。與一般的弱參照不同，最終化器將始終存在，直到參照物件被回收為止，從而大大簡化了生命週期管理。

最終化器在被呼叫（明確呼叫或在垃圾回收時）之前被視為`存活'，之後它就會`死亡'。呼叫存活的最終化器會回傳 @code{func(*arg, **kwargs)} 的計算結果，而呼叫死亡的最終化器會回傳 @ref{87e,,None}。

垃圾回收期間最終化器回呼引發的例外會在標準錯誤輸出中顯示，但無法傳播。它們的處理方式與從物件的 @ref{11f8,,__del__()} 方法或弱參照的回呼引發的例外相同。

當程式結束時，除非該最終化器的 @ref{d,,atexit} 屬性已被設定為 false，否則每個存活的最終化器會被呼叫。它們以與建立相反的順序被呼叫。

當模組的 globals 可能被 @ref{87e,,None} 取代時，最終化器永遠不會在 @ref{474,,interpreter shutdown} 的後期叫用（invoke）其回呼。

@geindex __call__() (weakref.finalize 的方法)
@anchor{library/weakref weakref finalize __call__}@anchor{2882}
@deffn {方法} __call__ ()

如果 `self' 仍存活，則將其標記為死亡並回傳呼叫 @code{func(*args, **kwargs)} 的結果。如果 `self' 已死亡，則回傳 @ref{87e,,None}。
@end deffn

@geindex detach() (weakref.finalize 的方法)
@anchor{library/weakref weakref finalize detach}@anchor{2883}
@deffn {方法} detach ()

如果 `self' 仍存活，則將其標記為死亡並回傳元組 @code{(obj, func, args, kwargs)}。如果 `self' 已死亡，則回傳 @ref{87e,,None}。
@end deffn

@geindex peek() (weakref.finalize 的方法)
@anchor{library/weakref weakref finalize peek}@anchor{2884}
@deffn {方法} peek ()

如果 `self' 仍存活，則回傳元組 @code{(obj, func, args, kwargs)}。如果 `self' 已死亡，則回傳 @ref{87e,,None}。
@end deffn

@geindex alive (weakref.finalize 的屬性)
@anchor{library/weakref weakref finalize alive}@anchor{2885}
@deffn {屬性} alive

如果最終化器仍存活，則屬性為 true，否則為 false。
@end deffn

@geindex atexit (weakref.finalize 的屬性)
@anchor{library/weakref weakref finalize atexit}@anchor{2886}
@deffn {屬性} atexit

一個可寫的布林屬性，預設為 true。當程式結束時，它會呼叫 @ref{2886,,atexit} 為 true 的所有剩餘且仍存活的最終化器。它們以與建立相反的順序被呼叫。
@end deffn

@cartouche
@quotation 備註 
確保 `func'、`args' 和 `kwargs' 不直接或間接擁有對 `obj' 的任何參照非常重要，否則 `obj' 將永遠不會被垃圾回收。尤其 `func' 不應該是 `obj' 的繫結方法。
@end quotation
@end cartouche


在 3.4 版被加入.

@end deffn

@geindex ReferenceType (於 weakref 模組中)
@anchor{library/weakref weakref ReferenceType}@anchor{1a8c}
@deffn {資料} weakref.ReferenceType

弱參照物件的型別物件。
@end deffn

@geindex ProxyType (於 weakref 模組中)
@anchor{library/weakref weakref ProxyType}@anchor{1a8d}
@deffn {資料} weakref.ProxyType

非可呼叫物件的代理的型別物件。
@end deffn

@geindex CallableProxyType (於 weakref 模組中)
@anchor{library/weakref weakref CallableProxyType}@anchor{1a8e}
@deffn {資料} weakref.CallableProxyType

可呼叫物件的代理的型別物件。
@end deffn

@geindex ProxyTypes (於 weakref 模組中)
@anchor{library/weakref weakref ProxyTypes}@anchor{2887}
@deffn {資料} weakref.ProxyTypes

包含代理的所有型別物件的序列。這可以讓測試物件是否為代理變得更簡單，而無需依賴命名兩種代理型別。
@end deffn


@subsubheading 也參考



@table @asis

@geindex Python Enhancement Proposals; PEP 205

@item PEP 205@footnote{https://peps.python.org/pep-0205/} - 弱參照

此功能的提案和理由，包括早期實作的連結以及其他語言中類似功能的資訊。
@end table


@menu
* 弱參照物件:: 
* 範例: 範例<4>. 
* 最終化器物件:: 
* 最終化器與 __del__() 方法的比較: 最終化器與 __del__ 方法的比較. 

@end menu

@node 弱參照物件,範例<4>,,weakref --- 弱參照
@anchor{library/weakref weak-reference-objects}@anchor{2888}@anchor{library/weakref weakref-objects}@anchor{2889}
@subsubsection 弱參照物件


弱參照物件除了 @ref{11ec,,ref.__callback__} 之外沒有任何方法和屬性。弱參照物件允許透過呼叫來取得參照目標（如果它仍然存在）：

@example
>>> import weakref
>>> class Object:
...     pass
...
>>> o = Object()
>>> r = weakref.ref(o)
>>> o2 = r()
>>> o is o2
True
@end example

如果參照目標不再存活，則呼叫參照物件將回傳 @ref{87e,,None}：

@example
>>> del o, o2
>>> print(r())
None
@end example

應該使用運算式 @code{ref() is not None} 來測試弱參照物件是否仍然存活。需要使用參照物件的應用程式程式碼通常應遵循以下模式：

@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

使用對「活性 (liveness)」的單獨測試會在執行緒應用程式中建立競爭條件 (race condition)；另一個執行緒可能在弱參照被呼叫之前讓該弱參照失效；上方顯示的慣用作法在執行緒應用程式和單執行緒應用程式中都是安全的。

可以透過子類別化來建立 @ref{11eb,,ref} 物件的特殊版本。這在 @ref{1890,,WeakValueDictionary} 的實作中被使用，以減少對映中每個條目的記憶體開銷。這對於將附加資訊與參照相關聯最有用，但也可用於在呼叫上插入附加處理以檢索參照目標。

這個範例展示如何使用 @ref{11eb,,ref} 的子類別來儲存有關物件的附加資訊並影響存取參照目標時回傳的值：

@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 範例<4>,最終化器物件,弱參照物件,weakref --- 弱參照
@anchor{library/weakref example}@anchor{288a}@anchor{library/weakref weakref-example}@anchor{288b}
@subsubsection 範例


這個簡單的範例展示了應用程式如何使用物件 ID 來檢索它以前見過​​的物件。物件的 ID 之後可以在其他資料結構中使用，而不必強制物件保持存活，但如果這樣做，仍然可以透過 ID 檢索物件。

@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 最終化器物件,最終化器與 __del__ 方法的比較,範例<4>,weakref --- 弱參照
@anchor{library/weakref finalize-examples}@anchor{288c}@anchor{library/weakref finalizer-objects}@anchor{288d}
@subsubsection 最終化器物件


使用 @ref{c66,,finalize} 的最大優點是可以輕鬆註冊回呼，而無需保留回傳的最終化器物件。例如

@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

最終化器也可以直接被呼叫。然而，最終化器最多會叫用回呼一次。

@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

你可以使用最終化器的 @ref{2883,,detach()} 方法來取消註冊最終化器。這會殺死最終化器並回傳建立建構函式時傳遞給建構函式的引數。

@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

除非你將 @ref{2886,,atexit} 屬性設為 @ref{d23,,False}，否則當程式結束時，最終化器將會被呼叫如果其仍然存在。例如

@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 最終化器與 __del__ 方法的比較,,最終化器物件,weakref --- 弱參照
@anchor{library/weakref comparing-finalizers-with-del-methods}@anchor{288e}
@subsubsection 最終化器與 @code{__del__()} 方法的比較


假設我們要建立一個類別，其實例代表臨時目錄。當以下任一事件發生時，應刪除目錄及其內容：


@itemize *

@item 
該物件被垃圾回收，

@item 
該物件的 @code{remove()} 方法被呼叫，或者

@item 
程式結束。
@end itemize

我們可以用以下的方式來嘗試使用 @ref{11f8,,__del__()} 方法實作該類別：

@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

從 Python 3.4 開始，@ref{11f8,,__del__()} 方法不再阻止參照循環 (reference cycle) 被垃圾回收，並且在 @ref{474,,interpreter shutdown} 期間不再強制將模組的 globals 設為 @ref{87e,,None}。所以這段程式碼在 CPython 上應該可以正常運作。

然而，眾所周知，對 @ref{11f8,,__del__()} 方法的處理是特地實作的，因為它依賴於直譯器的垃圾回收器實作的內部細節。

更耐用的替代方案可以是定義一個最終化器，其僅參照需要的特定函式和物件，而不是存取物件的完整狀態：

@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

定義如下，我們的最終化器僅接收對適當清理目錄所需的詳細資訊的參照。如果物件從未被垃圾回收，則最終化器仍將在結束時被呼叫。

基於 weakref 的最終化器的另一個優點是它們可用於為定義由第三方控制的類別註冊最終化器，例如在卸載模組時執行程式碼：

@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 備註 
如果在程式結束時在常駐的 (daemonic) 執行緒中建立最終化器物件，則最終化器有可能在結束時不會被呼叫。然而，在常駐的執行緒中 @ref{a75,,atexit.register()}、@code{try: ... finally: ...} 和 @code{with: ...} 也不保證清理會發生。
@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 和深層 deep 複製操作,weakref --- 弱參照,資料型別
@anchor{library/types doc}@anchor{288f}@anchor{library/types module-types}@anchor{109}@anchor{library/types translation-repo}@anchor{2890}@anchor{library/types types-dynamic-type-creation-and-names-for-built-in-types}@anchor{2891}
@subsection @code{types} --- 動態型別建立與內建型別名稱


@geindex module; types

`原始碼：'Lib/types.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/types.py}


__________________________________________________________________


This module defines utility functions to assist in dynamic creation of
new types.

It also defines names for some object types that are used by the standard
Python interpreter, but not exposed as builtins like @ref{19b,,int} or
@ref{169,,str} are.

Finally, it provides some additional type-related utility classes and functions
that are not fundamental enough to be builtins.

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

@end menu

@node Dynamic Type Creation,Standard Interpreter Types,,types --- 動態型別建立與內建型別名稱
@anchor{library/types dynamic-type-creation}@anchor{2892}
@subsubsection Dynamic Type Creation


@geindex new_class() (於 types 模組中)
@anchor{library/types types new_class}@anchor{1362}
@deffn {函式} types.new_class (name, bases=(), kwds=None, exec_body=None)

Creates a class object dynamically using the appropriate metaclass.

The first three arguments are the components that make up a class
definition header: the class name, the base classes (in order), the
keyword arguments (such as @code{metaclass}).

The `exec_body' argument is a callback that is used to populate the
freshly created class namespace. It should accept the class namespace
as its sole argument and update the namespace directly with the class
contents. If no callback is provided, it has the same effect as passing
in @code{lambda ns: None}.


在 3.3 版被加入.

@end deffn

@geindex prepare_class() (於 types 模組中)
@anchor{library/types types prepare_class}@anchor{1363}
@deffn {函式} types.prepare_class (name, bases=(), kwds=None)

Calculates the appropriate metaclass and creates the class namespace.

The arguments are the components that make up a class definition header:
the class name, the base classes (in order) and the keyword arguments
(such as @code{metaclass}).

The return value is a 3-tuple: @code{metaclass, namespace, kwds}

`metaclass' is the appropriate metaclass, `namespace' is the
prepared class namespace and `kwds' is an updated copy of the passed
in `kwds' argument with any @code{'metaclass'} entry removed. If no `kwds'
argument is passed in, this will be an empty dict.


在 3.3 版被加入.



在 3.6 版的變更: The default value for the @code{namespace} element of the returned
tuple has changed.  Now an insertion-order-preserving mapping is
used when the metaclass does not have a @code{__prepare__} method.

@end deffn


@subsubheading 也參考



@table @asis

@item @ref{2270,,Metaclasses}

Full details of the class creation process supported by these functions

@geindex Python Enhancement Proposals; PEP 3115

@item PEP 3115@footnote{https://peps.python.org/pep-3115/} - Metaclasses in Python 3000

Introduced the @code{__prepare__} namespace hook
@end table


@geindex resolve_bases() (於 types 模組中)
@anchor{library/types types resolve_bases}@anchor{d90}
@deffn {函式} types.resolve_bases (bases)

Resolve MRO entries dynamically as specified by 
@geindex Python Enhancement Proposals; PEP 560
PEP 560@footnote{https://peps.python.org/pep-0560/}.

This function looks for items in `bases' that are not instances of
@ref{f3f,,type}, and returns a tuple where each such object that has
an @ref{cda,,__mro_entries__()} method is replaced with an unpacked result of
calling this method.  If a `bases' item is an instance of @ref{f3f,,type},
or it doesn't have an @code{__mro_entries__()} method, then it is included in
the return tuple unchanged.


在 3.7 版被加入.

@end deffn

@geindex get_original_bases() (於 types 模組中)
@anchor{library/types types get_original_bases}@anchor{6ee}
@deffn {函式} types.get_original_bases (cls, /)

Return the tuple of objects originally given as the bases of `cls' before
the @ref{cda,,__mro_entries__()} method has been called on any bases
(following the mechanisms laid out in 
@geindex Python Enhancement Proposals; PEP 560
PEP 560@footnote{https://peps.python.org/pep-0560/}). This is useful for
introspecting @ref{6ef,,Generics}.

For classes that have an @code{__orig_bases__} attribute, this
function returns the value of @code{cls.__orig_bases__}.
For classes without the @code{__orig_bases__} attribute,
@ref{16a0,,cls.__bases__} is returned.

舉例來說：

@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


在 3.12 版被加入.

@end deffn


@subsubheading 也參考


@geindex Python Enhancement Proposals; PEP 560
PEP 560@footnote{https://peps.python.org/pep-0560/} - Core support for typing module and generic types


@node Standard Interpreter Types,Additional Utility Classes and Functions,Dynamic Type Creation,types --- 動態型別建立與內建型別名稱
@anchor{library/types standard-interpreter-types}@anchor{2893}
@subsubsection Standard Interpreter Types


This module provides names for many of the types that are required to
implement a Python interpreter. It deliberately avoids including some of
the types that arise only incidentally during processing such as the
@code{listiterator} type.

Typical use of these names is for @ref{2ad,,isinstance()} or
@ref{9bd,,issubclass()} checks.

If you instantiate any of these types, note that signatures may vary between Python versions.

Standard names are defined for the following types:

@geindex NoneType (於 types 模組中)
@anchor{library/types types NoneType}@anchor{a4b}
@deffn {資料} types.NoneType

The type of @ref{87e,,None}.


在 3.10 版被加入.

@end deffn

@geindex FunctionType (於 types 模組中)
@geindex LambdaType (於 types 模組中)
@anchor{library/types types FunctionType}@anchor{a7a}
@deffn {資料} types.FunctionType
@anchor{library/types types LambdaType}@anchor{2894}
@deffnx {資料} types.LambdaType

The type of user-defined functions and functions created by
@ref{149e,,lambda}  expressions.

引發一個附帶引數 @code{code} 的@ref{1b70,,稽核事件} @code{function.__new__}。

The audit event only occurs for direct instantiation of function objects,
and is not raised for normal compilation.
@end deffn

@geindex GeneratorType (於 types 模組中)
@anchor{library/types types GeneratorType}@anchor{1902}
@deffn {資料} types.GeneratorType

The type of @ref{125c,,generator}-iterator objects, created by
generator functions.
@end deffn

@geindex CoroutineType (於 types 模組中)
@anchor{library/types types CoroutineType}@anchor{1084}
@deffn {資料} types.CoroutineType

The type of @ref{6b2,,coroutine} objects, created by
@ref{7e6,,async def} functions.


在 3.5 版被加入.

@end deffn

@geindex AsyncGeneratorType (於 types 模組中)
@anchor{library/types types AsyncGeneratorType}@anchor{2895}
@deffn {資料} types.AsyncGeneratorType

The type of @ref{2342,,asynchronous generator}-iterator objects, created by
asynchronous generator functions.


在 3.6 版被加入.

@end deffn

@geindex CodeType (types 中的類別)
@anchor{library/types types CodeType}@anchor{32e}
@deffn {類別} types.CodeType (**kwargs)

@geindex built-in function（內建函式）;compile（編譯）

The type of @ref{4e1,,code objects} such as returned by @ref{4ac,,compile()}.

引發一個附帶引數 @code{code}、@code{filename}、@code{name}、@code{argcount}、@code{posonlyargcount}、@code{kwonlyargcount}、@code{nlocals}、@code{stacksize}、@code{flags} 的@ref{1b70,,稽核事件} @code{code.__new__}。

Note that the audited arguments may not match the names or positions
required by the initializer.  The audit event only occurs for direct
instantiation of code objects, and is not raised for normal compilation.
@end deffn

@geindex CellType (於 types 模組中)
@anchor{library/types types CellType}@anchor{2896}
@deffn {資料} types.CellType

The type for cell objects: such objects are used as containers for
a function's @ref{180c,,closure variables}.


在 3.8 版被加入.

@end deffn

@geindex MethodType (於 types 模組中)
@anchor{library/types types MethodType}@anchor{1ab1}
@deffn {資料} types.MethodType

The type of methods of user-defined class instances.
@end deffn

@geindex BuiltinFunctionType (於 types 模組中)
@geindex BuiltinMethodType (於 types 模組中)
@anchor{library/types types BuiltinFunctionType}@anchor{2897}
@deffn {資料} types.BuiltinFunctionType
@anchor{library/types types BuiltinMethodType}@anchor{2898}
@deffnx {資料} types.BuiltinMethodType

The type of built-in functions like @ref{839,,len()} or @ref{277,,sys.exit()}, and
methods of built-in classes.  (Here, the term "built-in" means "written in
C".)
@end deffn

@geindex WrapperDescriptorType (於 types 模組中)
@anchor{library/types types WrapperDescriptorType}@anchor{d8d}
@deffn {資料} types.WrapperDescriptorType

The type of methods of some built-in data types and base classes such as
@ref{8b7,,object.__init__()} or @ref{14a1,,object.__lt__()}.


在 3.7 版被加入.

@end deffn

@geindex MethodWrapperType (於 types 模組中)
@anchor{library/types types MethodWrapperType}@anchor{854}
@deffn {資料} types.MethodWrapperType

The type of `bound' methods of some built-in data types and base classes.
For example it is the type of @code{object().__str__}.


在 3.7 版被加入.

@end deffn

@geindex NotImplementedType (於 types 模組中)
@anchor{library/types types NotImplementedType}@anchor{a4c}
@deffn {資料} types.NotImplementedType

The type of @ref{1a2,,NotImplemented}.


在 3.10 版被加入.

@end deffn

@geindex MethodDescriptorType (於 types 模組中)
@anchor{library/types types MethodDescriptorType}@anchor{d8e}
@deffn {資料} types.MethodDescriptorType

The type of methods of some built-in data types such as @ref{24b9,,str.join()}.


在 3.7 版被加入.

@end deffn

@geindex ClassMethodDescriptorType (於 types 模組中)
@anchor{library/types types ClassMethodDescriptorType}@anchor{d8f}
@deffn {資料} types.ClassMethodDescriptorType

The type of `unbound' class methods of some built-in data types such as
@code{dict.__dict__['fromkeys']}.


在 3.7 版被加入.

@end deffn

@geindex ModuleType (types 中的類別)
@anchor{library/types types ModuleType}@anchor{100f}
@deffn {類別} types.ModuleType (name, doc=None)

The type of @ref{192d,,modules}. The constructor takes the name of the
module to be created and optionally its @ref{242f,,docstring}.


@subsubheading 也參考



@table @asis

@item @ref{2210,,Documentation on module objects}

Provides details on the special attributes that can be found on
instances of @code{ModuleType}.

@item @ref{100e,,importlib.util.module_from_spec()}

Modules created using the @code{ModuleType} constructor are
created with many of their special attributes unset or set to default
values. @code{module_from_spec()} provides a more robust way of
creating @code{ModuleType} instances which ensures the various
attributes are set appropriately.
@end table

@end deffn

@geindex EllipsisType (於 types 模組中)
@anchor{library/types types EllipsisType}@anchor{a4a}
@deffn {資料} types.EllipsisType

The type of @ref{21dd,,Ellipsis}.


在 3.10 版被加入.

@end deffn

@geindex GenericAlias (types 中的類別)
@anchor{library/types types GenericAlias}@anchor{9e5}
@deffn {類別} types.GenericAlias (t_origin, t_args)

The type of @ref{8b8,,parameterized generics} such as
@code{list[int]}.

@code{t_origin} should be a non-parameterized generic class, such as @code{list},
@code{tuple} or @code{dict}.  @code{t_args} should be a @ref{60c,,tuple} (possibly of
length 1) of types which parameterize @code{t_origin}:

@example
>>> from types import GenericAlias

>>> list[int] == GenericAlias(list, (int,))
True
>>> dict[str, int] == GenericAlias(dict, (str, int))
True
@end example


在 3.9 版被加入.



在 3.9.2 版的變更: This type can now be subclassed.



@subsubheading 也參考



@table @asis

@item @ref{8b8,,Generic Alias Types}

In-depth documentation on instances of @code{types.GenericAlias}

@geindex Python Enhancement Proposals; PEP 585

@item PEP 585@footnote{https://peps.python.org/pep-0585/} - Type Hinting Generics In Standard Collections

Introducing the @code{types.GenericAlias} class
@end table

@end deffn

@geindex UnionType (types 中的類別)
@anchor{library/types types UnionType}@anchor{2a7}
@deffn {類別} types.UnionType

The type of @ref{9be,,union type expressions}.


在 3.10 版被加入.



在 3.14 版的變更: This is now an alias for @ref{2a8,,typing.Union}.

@end deffn

@geindex TracebackType (types 中的類別)
@anchor{library/types types TracebackType}@anchor{ce1}
@deffn {類別} types.TracebackType (tb_next, tb_frame, tb_lasti, tb_lineno)

The type of traceback objects such as found in @code{sys.exception().__traceback__}.

See @ref{ce3,,the language reference} for details of the
available attributes and operations, and guidance on creating tracebacks
dynamically.
@end deffn

@geindex FrameType (於 types 模組中)
@anchor{library/types types FrameType}@anchor{1b09}
@deffn {資料} types.FrameType

The type of @ref{8e7,,frame objects} such as found in
@ref{2252,,tb.tb_frame} if @code{tb} is a traceback object.
@end deffn

@geindex GetSetDescriptorType (於 types 模組中)
@anchor{library/types types GetSetDescriptorType}@anchor{2899}
@deffn {資料} types.GetSetDescriptorType

The type of objects defined in extension modules with @code{PyGetSetDef}, such
as @ref{4a0,,FrameType.f_locals} or @code{array.array.typecode}.
This type is used as
descriptor for object attributes; it has the same purpose as the
@ref{4ae,,property} type, but for classes defined in extension modules.
@end deffn

@geindex MemberDescriptorType (於 types 模組中)
@anchor{library/types types MemberDescriptorType}@anchor{289a}
@deffn {資料} types.MemberDescriptorType

The type of objects defined in extension modules with @code{PyMemberDef}, such
as @code{datetime.timedelta.days}.  This type is used as descriptor for simple C
data members which use standard conversion functions; it has the same purpose
as the @ref{4ae,,property} type, but for classes defined in extension modules.

In addition, when a class is defined with a @ref{16df,,__slots__} attribute, then for
each slot, an instance of @code{MemberDescriptorType} will be added as an attribute
on the class. This allows the slot to appear in the class's @ref{e52,,__dict__}.

`CPython 實作細節：' In other implementations of Python, this type may be identical to
@code{GetSetDescriptorType}.
@end deffn

@geindex MappingProxyType (types 中的類別)
@anchor{library/types types MappingProxyType}@anchor{691}
@deffn {類別} types.MappingProxyType (mapping)

Read-only proxy of a mapping. It provides a dynamic view on the mapping's
entries, which means that when the mapping changes, the view reflects these
changes.


在 3.3 版被加入.



在 3.9 版的變更: Updated to support the new union (@code{|}) operator from 
@geindex Python Enhancement Proposals; PEP 584
PEP 584@footnote{https://peps.python.org/pep-0584/}, which
simply delegates to the underlying mapping.



@deffn {Describe} key in proxy

Return @code{True} if the underlying mapping has a key `key', else
@code{False}.
@end deffn


@deffn {Describe} proxy[key]

Return the item of the underlying mapping with key `key'.  Raises a
@ref{5df,,KeyError} if `key' is not in the underlying mapping.
@end deffn


@deffn {Describe} iter(proxy)

Return an iterator over the keys of the underlying mapping.  This is a
shortcut for @code{iter(proxy.keys())}.
@end deffn


@deffn {Describe} len(proxy)

Return the number of items in the underlying mapping.
@end deffn

@geindex copy() (types.MappingProxyType 的方法)
@anchor{library/types types MappingProxyType copy}@anchor{289b}
@deffn {方法} copy ()

Return a shallow copy of the underlying mapping.
@end deffn

@geindex get() (types.MappingProxyType 的方法)
@anchor{library/types types MappingProxyType get}@anchor{289c}
@deffn {方法} get (key[, default])

Return the value for `key' if `key' is in the underlying mapping, else
`default'.  If `default' is not given, it defaults to @code{None}, so that
this method never raises a @ref{5df,,KeyError}.
@end deffn

@geindex items() (types.MappingProxyType 的方法)
@anchor{library/types types MappingProxyType items}@anchor{289d}
@deffn {方法} items ()

Return a new view of the underlying mapping's items (@code{(key, value)}
pairs).
@end deffn

@geindex keys() (types.MappingProxyType 的方法)
@anchor{library/types types MappingProxyType keys}@anchor{289e}
@deffn {方法} keys ()

Return a new view of the underlying mapping's keys.
@end deffn

@geindex values() (types.MappingProxyType 的方法)
@anchor{library/types types MappingProxyType values}@anchor{289f}
@deffn {方法} values ()

Return a new view of the underlying mapping's values.
@end deffn


@deffn {Describe} reversed(proxy)

Return a reverse iterator over the keys of the underlying mapping.


在 3.9 版被加入.

@end deffn


@deffn {Describe} hash(proxy)

Return a hash of the underlying mapping.


在 3.12 版被加入.

@end deffn
@end deffn

@geindex CapsuleType (types 中的類別)
@anchor{library/types types CapsuleType}@anchor{28a0}
@deffn {類別} types.CapsuleType

The type of @ref{28a1,,capsule objects}.


在 3.13 版被加入.

@end deffn

@node Additional Utility Classes and Functions,Coroutine Utility Functions,Standard Interpreter Types,types --- 動態型別建立與內建型別名稱
@anchor{library/types additional-utility-classes-and-functions}@anchor{28a2}
@subsubsection Additional Utility Classes and Functions


@geindex SimpleNamespace (types 中的類別)
@anchor{library/types types SimpleNamespace}@anchor{4e0}
@deffn {類別} types.SimpleNamespace

A simple @ref{c75,,object} subclass that provides attribute access to its
namespace, as well as a meaningful repr.

Unlike @ref{c75,,object}, with @code{SimpleNamespace} you can add and remove
attributes.

@ref{4e0,,SimpleNamespace} objects may be initialized
in the same way as @ref{183,,dict}: either with keyword arguments,
with a single positional argument, or with both.
When initialized with keyword arguments,
those are directly added to the underlying namespace.
Alternatively, when initialized with a positional argument,
the underlying namespace will be updated with key-value pairs
from that argument (either a mapping object or
an @ref{1428,,iterable} object producing key-value pairs).
All such keys must be strings.

The type is roughly equivalent to the following code:

@example
class SimpleNamespace:
    def __init__(self, mapping_or_iterable=(), /, **kwargs):
        self.__dict__.update(mapping_or_iterable)
        self.__dict__.update(kwargs)

    def __repr__(self):
        items = (f"@{k@}=@{v!r@}" for k, v in self.__dict__.items())
        return "@{@}(@{@})".format(type(self).__name__, ", ".join(items))

    def __eq__(self, other):
        if isinstance(self, SimpleNamespace) and isinstance(other, SimpleNamespace):
           return self.__dict__ == other.__dict__
        return NotImplemented
@end example

@code{SimpleNamespace} may be useful as a replacement for @code{class NS: pass}.
However, for a structured record type use @ref{4db,,namedtuple()}
instead.

@code{SimpleNamespace} objects are supported by @ref{1c0,,copy.replace()}.


在 3.3 版被加入.



在 3.9 版的變更: Attribute order in the repr changed from alphabetical to insertion (like
@code{dict}).



在 3.13 版的變更: Added support for an optional positional argument.

@end deffn

@geindex DynamicClassAttribute() (於 types 模組中)
@anchor{library/types types DynamicClassAttribute}@anchor{835}
@deffn {函式} types.DynamicClassAttribute (fget=None, fset=None, fdel=None, doc=None)

Route attribute access on a class to __getattr__.

This is a descriptor, used to define attributes that act differently when
accessed through an instance and through a class.  Instance access remains
normal, but access to an attribute through a class will be routed to the
class's __getattr__ method; this is done by raising AttributeError.

This allows one to have properties active on an instance, and have virtual
attributes on the class with the same name (see @ref{83b,,enum.Enum} for an example).


在 3.4 版被加入.

@end deffn

@node Coroutine Utility Functions,,Additional Utility Classes and Functions,types --- 動態型別建立與內建型別名稱
@anchor{library/types coroutine-utility-functions}@anchor{28a3}
@subsubsection Coroutine Utility Functions


@geindex coroutine() (於 types 模組中)
@anchor{library/types types coroutine}@anchor{1083}
@deffn {函式} types.coroutine (gen_func)

This function transforms a @ref{125c,,generator} function into a
@ref{f6e,,coroutine function} which returns a generator-based coroutine.
The generator-based coroutine is still a @ref{dd4,,generator iterator},
but is also considered to be a @ref{6b2,,coroutine} object and is
@ref{4c4,,awaitable}.  However, it may not necessarily implement
the @ref{f70,,__await__()} method.

If `gen_func' is a generator function, it will be modified in-place.

If `gen_func' is not a generator function, it will be wrapped. If it
returns an instance of @ref{fd6,,collections.abc.Generator}, the instance
will be wrapped in an `awaitable' proxy object.  All other types
of objects will be returned as is.


在 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 和深層 deep 複製操作,pprint --- 資料美化列印器,types --- 動態型別建立與內建型別名稱,資料型別
@anchor{library/copy doc}@anchor{28a4}@anchor{library/copy copy-shallow-and-deep-copy-operations}@anchor{28a5}@anchor{library/copy module-copy}@anchor{29}@anchor{library/copy translation-repo}@anchor{28a6}
@subsection @code{copy} --- 淺層 (shallow) 和深層 (deep) 複製操作


@geindex module; copy

`原始碼：'Lib/copy.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/copy.py}


__________________________________________________________________


Python 的賦值陳述式不複製物件，而是建立目標和物件的繫結 (binding) 關係。對於可變 (mutable) 或包含可變項目 (mutable item) 的集合，有時會需要一份副本來改變特定副本，而不必改變其他副本。本模組提供了通用的淺層複製和深層複製操作（如下所述）。

介面摘要：

@geindex copy() (於 copy 模組中)
@anchor{library/copy copy copy}@anchor{750}
@deffn {函式} copy.copy (obj)

回傳 `obj' 的淺層複製。
@end deffn

@geindex deepcopy() (於 copy 模組中)
@anchor{library/copy copy deepcopy}@anchor{d5d}
@deffn {函式} copy.deepcopy (obj[, memo])

回傳 `obj' 的深層複製。
@end deffn

@geindex replace() (於 copy 模組中)
@anchor{library/copy copy replace}@anchor{1c0}
@deffn {函式} copy.replace (obj, /, **changes)

Creates a new object of the same type as `obj', replacing fields with values
from `changes'.


在 3.13 版被加入.

@end deffn

@geindex Error
@anchor{library/copy copy Error}@anchor{28a7}
@deffn {例外} copy.Error

引發針對特定模組的錯誤。
@end deffn
@anchor{library/copy shallow-vs-deep-copy}@anchor{1ead}
淺層與深層複製的區別僅與複合物件（即包含 list 或類別的實例等其他物件的物件）相關：


@itemize *

@item 
`淺層複製'建構一個新的複合物件，然後（在儘可能的範圍內）將原始物件中找到的物件的`參照'插入其中。

@item 
`深層複製'建構一個新的複合物件，然後遞迴地將在原始物件裡找到的物件的`副本'插入其中。
@end itemize

深層複製操作通常存在兩個問題，而淺層複製操作並不存在這些問題：


@itemize *

@item 
遞迴物件（直接或間接包含對自身參照的複合物件）可能會導致遞迴迴圈。

@item 
由於深層複製會複製所有內容，因此可能會有過多複製（例如應該在副本之間共享的資料）。
@end itemize

@ref{d5d,,deepcopy()} 函式用以下方式避免了這些問題：


@itemize *

@item 
保留在目前複製過程中已複製的物件的 @code{memo} 字典；以及

@item 
允許使用者定義的類別複寫 (override) 複製操作或複製的元件集合。
@end itemize

該模組不複製模組、方法、堆疊追蹤（stack trace）、堆疊框（stack frame）、檔案、socket、視窗、陣列以及任何類似的型別。它透過不變更原始物件並將其回傳來（淺層或深層地）"複製"函式和類別；這與 @ref{ab,,pickle} 模組處理這類問題的方式是相似的。

字典的淺層複製可以使用 @ref{dc4,,dict.copy()}，而 list 的淺層複製可以透過賦值整個 list 的切片 (slice) 完成，例如，@code{copied_list = original_list[:]}。

@geindex module（模組）;pickle

類別可以使用與操作 pickle 相同的介面來控制複製操作，關於這些方法的描述資訊請參考 @ref{ab,,pickle} 模組。實際上，@ref{29,,copy} 模組使用的正是從 @ref{2a,,copyreg} 模組中註冊的 pickle 函式。

@geindex __copy__() （複製協定）
@geindex __deepcopy__() （複製協定）

In order for a class to define its own copy implementation, it can define
special methods @ref{1769,,__copy__()} and @ref{176a,,__deepcopy__()}.

@anchor{library/copy object __copy__}@anchor{1769}
@deffn {方法} object.__copy__ (self)

Called to implement the shallow copy operation;
no additional arguments are passed.
@end deffn

@anchor{library/copy object __deepcopy__}@anchor{176a}
@deffn {方法} object.__deepcopy__ (self, memo)

用來實作深層複製操作；它會傳遞一個引數，即 `memo' 字典。如果 @code{__deepcopy__} 實現需要建立一個元件的深層複製，它應當呼叫 @ref{d5d,,deepcopy()} 函式並以該元件作為第一個引數、以該 `memo' 字典作為第二個引數。`memo' 字典應當被當作不透明物件 (opaque object) 來處理
@end deffn

@geindex __replace__() （取代協定）

Function @code{copy.replace()} is more limited
than @ref{750,,copy()} and @ref{d5d,,deepcopy()},
and only supports named tuples created by @ref{4db,,namedtuple()},
@ref{33,,dataclasses}, and other classes which define method @ref{477,,__replace__()}.

@anchor{library/copy object __replace__}@anchor{477}
@deffn {方法} object.__replace__ (self, /, **changes)

This method should create a new object of the same type,
replacing fields with values from `changes'.


在 3.13 版被加入.

@end deffn


@subsubheading 也參考



@table @asis

@item @ref{ab,,pickle} 模組

支援物件之狀態檢索 (state retrieval) 和恢復 (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 --- 資料美化列印器,reprlib --- repr 的替代實作,copy --- 淺層 shallow 和深層 deep 複製操作,資料型別
@anchor{library/pprint doc}@anchor{28a8}@anchor{library/pprint module-pprint}@anchor{b3}@anchor{library/pprint pprint-data-pretty-printer}@anchor{28a9}@anchor{library/pprint translation-repo}@anchor{28aa}
@subsection @code{pprint} --- 資料美化列印器


@geindex module; pprint

`原始碼：'Lib/pprint.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/pprint.py}


__________________________________________________________________


The @ref{b3,,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 80 characters.


在 3.9 版的變更: Added support for pretty-printing @ref{4e0,,types.SimpleNamespace}.



在 3.10 版的變更: Added support for pretty-printing @ref{4dc,,dataclasses.dataclass}.


@menu
* 函式: 函式<4>. 
* PrettyPrinter 物件:: 
* 範例: 範例<5>. 

@end menu

@node 函式<4>,PrettyPrinter 物件,,pprint --- 資料美化列印器
@anchor{library/pprint functions}@anchor{28ab}@anchor{library/pprint pprint-functions}@anchor{28ac}
@subsubsection 函式


@geindex pp() (於 pprint 模組中)
@anchor{library/pprint pprint pp}@anchor{c0f}
@deffn {函式} pprint.pp (object, stream=None, indent=1, width=80, 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{1170,,print()} function for inspecting values.
Tip: you can reassign @code{print = pprint.pp} for use within a scope.

@*參數: 

@itemize *

@item 
@code{object} -- 將被印出的物件。

@item 
@code{stream} (@ref{28ad,,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{cc4,,sys.stdout} is used.

@item 
@code{indent} (@ref{19b,,int}) -- The amount of indentation added for each nesting level.

@item 
@code{width} (@ref{19b,,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{19b,,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{3c1,,bool}) -- Control the way long @ref{70f,,sequences} are formatted.
If @code{False} (the default),
each item of a sequence will be formatted on a separate line,
otherwise as many items as will fit within the `width'
will be formatted on each output line.

@item 
@code{sort_dicts} (@ref{3c1,,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{3c1,,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)
[<Recursion on list with id=...>,
 'spam',
 'eggs',
 'lumberjack',
 'knights',
 'ni']
@end example


在 3.8 版被加入.

@end deffn

@geindex pprint() (於 pprint 模組中)
@anchor{library/pprint pprint pprint}@anchor{a22}
@deffn {函式} pprint.pprint (object, stream=None, indent=1, width=80, depth=None, *, compact=False, sort_dicts=True, underscore_numbers=False)

Alias for @ref{c0f,,pp()} with `sort_dicts' set to @code{True} by default,
which would automatically sort the dictionaries' keys,
you might want to use @ref{c0f,,pp()} instead where it is @code{False} by default.
@end deffn

@geindex pformat() (於 pprint 模組中)
@anchor{library/pprint pprint pformat}@anchor{117b}
@deffn {函式} pprint.pformat (object, indent=1, width=80, 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{117a,,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{28ae}
@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{49e,,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{28af}
@deffn {函式} pprint.isrecursive (object)

Determine if `object' requires a recursive representation.  This function is
subject to the same limitations as noted in @ref{28b0,,saferepr()} below and may raise an
@ref{f63,,RecursionError} if it fails to detect a recursive object.
@end deffn

@geindex saferepr() (於 pprint 模組中)
@anchor{library/pprint pprint saferepr}@anchor{28b0}
@deffn {函式} pprint.saferepr (object)

Return a string representation of `object', protected against recursion in
some common data structures, namely instances of @ref{183,,dict}, @ref{24d,,list}
and @ref{60c,,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 物件,範例<5>,函式<4>,pprint --- 資料美化列印器
@anchor{library/pprint id1}@anchor{28b1}@anchor{library/pprint prettyprinter-objects}@anchor{28b2}
@subsubsection PrettyPrinter 物件


@geindex ...;placeholder（佔位符號）

@geindex PrettyPrinter (pprint 中的類別)
@anchor{library/pprint pprint PrettyPrinter}@anchor{117a}
@deffn {類別} pprint.PrettyPrinter (indent=1, width=80, depth=None, stream=None, *, compact=False, sort_dicts=True, underscore_numbers=False)

建立一個 @ref{117a,,PrettyPrinter} 實例。

Arguments have the same meaning as for @ref{c0f,,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(indent=4)
>>> pp.pprint(stuff)
[   ['spam', 'eggs', 'lumberjack', 'knights', 'ni'],
    'spam',
    'eggs',
    'lumberjack',
    'knights',
    'ni']
>>> pp = pprint.PrettyPrinter(width=41, compact=True)
>>> pp.pprint(stuff)
[['spam', 'eggs', 'lumberjack',
  'knights', 'ni'],
 'spam', 'eggs', 'lumberjack', 'knights',
 'ni']
>>> tup = ('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead',
... ('parrot', ('fresh fruit',))))))))
>>> pp = pprint.PrettyPrinter(depth=6)
>>> pp.pprint(tup)
('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead', (...)))))))
@end example


在 3.4 版的變更: 新增 `compact' 參數。



在 3.8 版的變更: 新增 `sort_dicts' 參數。



在 3.10 版的變更: 新增 `underscore_numbers' 參數。



在 3.11 版的變更: No longer attempts to write to @code{sys.stdout} if it is @code{None}.

@end deffn

@ref{117a,,PrettyPrinter} 實例有以下方法：

@geindex pformat() (pprint.PrettyPrinter 的方法)
@anchor{library/pprint pprint PrettyPrinter pformat}@anchor{28b3}
@deffn {方法} PrettyPrinter.pformat (object)

Return the formatted representation of `object'.  This takes into account the
options passed to the @ref{117a,,PrettyPrinter} constructor.
@end deffn

@geindex pprint() (pprint.PrettyPrinter 的方法)
@anchor{library/pprint pprint PrettyPrinter pprint}@anchor{28b4}
@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{117a,,PrettyPrinter} objects don't need to be
created.

@geindex isreadable() (pprint.PrettyPrinter 的方法)
@anchor{library/pprint pprint PrettyPrinter isreadable}@anchor{28b5}
@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{49e,,eval()}.  Note that this returns
@code{False} for recursive objects.  If the `depth' parameter of the
@ref{117a,,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{28b6}
@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{28b0,,saferepr()} implementation.

@geindex format() (pprint.PrettyPrinter 的方法)
@anchor{library/pprint pprint PrettyPrinter format}@anchor{1bd3}
@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{161a,,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 @ref{1bd3,,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 範例<5>,,PrettyPrinter 物件,pprint --- 資料美化列印器
@anchor{library/pprint example}@anchor{28b7}@anchor{library/pprint pprint-example}@anchor{28b8}
@subsubsection 範例


To demonstrate several uses of the @ref{c0f,,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{c0f,,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 --- repr 的替代實作,enum --- 對列舉的支援,pprint --- 資料美化列印器,資料型別
@anchor{library/reprlib doc}@anchor{28b9}@anchor{library/reprlib module-reprlib}@anchor{c0}@anchor{library/reprlib reprlib-alternate-repr-implementation}@anchor{28ba}@anchor{library/reprlib translation-repo}@anchor{28bb}
@subsection @code{reprlib} --- @code{repr()} 的替代實作


@geindex module; reprlib

`原始碼：'Lib/reprlib.py@footnote{https://github.com/python/cpython/tree/3.14/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{28bc}
@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{1c1,,repr()}; size limits for  different object types
are added to avoid the generation of representations which are excessively long.

The keyword arguments of the constructor can be used as a shortcut to set the
attributes of the @ref{28bc,,Repr} instance. Which means that the following
initialization:

@example
aRepr = reprlib.Repr(maxlevel=3)
@end example

等價於：

@example
aRepr = reprlib.Repr()
aRepr.maxlevel = 3
@end example

See section @ref{28bd,,Repr Objects} for more information about @ref{28bc,,Repr}
attributes.


在 3.12 版的變更: Allow attributes to be set via keyword arguments.

@end deffn

@geindex aRepr (於 reprlib 模組中)
@anchor{library/reprlib reprlib aRepr}@anchor{28be}
@deffn {資料} reprlib.aRepr

This is an instance of @ref{28bc,,Repr} which is used to provide the
@ref{28bf,,repr()} function described below.  Changing the attributes of this
object will affect the size limits used by @ref{28bf,,repr()} and the Python
debugger.
@end deffn

@geindex repr() (於 reprlib 模組中)
@anchor{library/reprlib reprlib repr}@anchor{28bf}
@deffn {函式} reprlib.repr (obj)

This is the @ref{28c0,,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{828,,__repr__()} and substituting a
placeholder string instead.

@geindex ...;placeholder（佔位符號）

@geindex recursive_repr() (於 reprlib 模組中)
@anchor{library/reprlib reprlib recursive_repr}@anchor{13f4}
@deffn {函式} @@reprlib.recursive_repr (fillvalue='...')

Decorator for @ref{828,,__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


在 3.2 版被加入.

@end deffn

@menu
* Repr 物件:: 
* Subclassing Repr Objects:: 

@end menu

@node Repr 物件,Subclassing Repr Objects,,reprlib --- repr 的替代實作
@anchor{library/reprlib id1}@anchor{28bd}@anchor{library/reprlib repr-objects}@anchor{28c1}
@subsubsection Repr 物件


@ref{28bc,,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{28c2}
@deffn {屬性} Repr.fillvalue

This string is displayed for recursive references. It defaults to
@code{...}.


在 3.11 版被加入.

@end deffn

@geindex maxlevel (reprlib.Repr 的屬性)
@anchor{library/reprlib reprlib Repr maxlevel}@anchor{28c3}
@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{28c4}
@deffn {屬性} Repr.maxdict
@anchor{library/reprlib reprlib Repr maxlist}@anchor{28c5}
@deffnx {屬性} Repr.maxlist
@anchor{library/reprlib reprlib Repr maxtuple}@anchor{28c6}
@deffnx {屬性} Repr.maxtuple
@anchor{library/reprlib reprlib Repr maxset}@anchor{28c7}
@deffnx {屬性} Repr.maxset
@anchor{library/reprlib reprlib Repr maxfrozenset}@anchor{28c8}
@deffnx {屬性} Repr.maxfrozenset
@anchor{library/reprlib reprlib Repr maxdeque}@anchor{28c9}
@deffnx {屬性} Repr.maxdeque
@anchor{library/reprlib reprlib Repr maxarray}@anchor{28ca}
@deffnx {屬性} Repr.maxarray

Limits on the number of entries represented for the named object type.  The
default is @code{4} for @ref{28c4,,maxdict}, @code{5} for @ref{28ca,,maxarray}, and  @code{6} for
the others.
@end deffn

@geindex maxlong (reprlib.Repr 的屬性)
@anchor{library/reprlib reprlib Repr maxlong}@anchor{28cb}
@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{28cc}
@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{28cd}
@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{28bc,,Repr} object. It is applied in a
similar manner as @ref{28cc,,maxstring}.  The default is @code{20}.
@end deffn

@geindex indent (reprlib.Repr 的屬性)
@anchor{library/reprlib reprlib Repr indent}@anchor{28ce}
@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{1c1,,repr()}.
For example:

@example
>>> example = [
...     1, 'spam', @{'a': 2, 'b': 'spam eggs', 'c': @{3: 4.5, 6: []@}@}, 'ham']
>>> import reprlib
>>> aRepr = reprlib.Repr()
>>> print(aRepr.repr(example))
[1, 'spam', @{'a': 2, 'b': 'spam eggs', 'c': @{3: 4.5, 6: []@}@}, 'ham']
@end example

If @ref{28ce,,indent} is set to a string, each recursion level
is placed on its own line, indented by that string:

@example
>>> aRepr.indent = '-->'
>>> print(aRepr.repr(example))
[
-->1,
-->'spam',
-->@{
-->-->'a': 2,
-->-->'b': 'spam eggs',
-->-->'c': @{
-->-->-->3: 4.5,
-->-->-->6: [],
-->-->@},
-->@},
-->'ham',
]
@end example

Setting @ref{28ce,,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


在 3.12 版被加入.

@end deffn

@geindex repr() (reprlib.Repr 的方法)
@anchor{library/reprlib reprlib Repr repr}@anchor{28c0}
@deffn {方法} Repr.repr (obj)

The equivalent to the built-in @ref{1c1,,repr()} that uses the formatting imposed by
the instance.
@end deffn

@geindex repr1() (reprlib.Repr 的方法)
@anchor{library/reprlib reprlib Repr repr1}@anchor{28cf}
@deffn {方法} Repr.repr1 (obj, level)

Recursive implementation used by @ref{28c0,,repr()}.  This uses the type of `obj' to
determine which formatting method to call, passing it `obj' and `level'.  The
type-specific methods should call @ref{28cf,,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{28cf,,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 物件,reprlib --- repr 的替代實作
@anchor{library/reprlib subclassing-repr-objects}@anchor{28d0}@anchor{library/reprlib subclassing-reprs}@anchor{28d1}
@subsubsection Subclassing Repr Objects


The use of dynamic dispatching by @ref{28cf,,Repr.repr1()} allows subclasses of
@ref{28bc,,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))         # 印出 '<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 --- 對列舉的支援,graphlib —-- 使用類圖 graph-like 結構進行操作的功能,reprlib --- repr 的替代實作,資料型別
@anchor{library/enum doc}@anchor{28d2}@anchor{library/enum enum-support-for-enumerations}@anchor{28d3}@anchor{library/enum module-enum}@anchor{5a}@anchor{library/enum translation-repo}@anchor{28d4}
@subsection @code{enum} --- 對列舉的支援


@geindex module; enum


在 3.4 版被加入.


`原始碼：'Lib/enum.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/enum.py}

@subsubheading Important



本頁包含 API 的參考資訊。關於教學資訊及更多進階主題的討論請參考


@itemize *

@item 
@ref{28d5,,基本教學}

@item 
@ref{28d6,,進階教學}

@item 
@ref{28d7,,列舉指南}
@end itemize


__________________________________________________________________


列舉：


@itemize *

@item 
是一組綁定唯一值的代表名稱（成員）

@item 
可以用疊代的方式以定義的順序回傳其正式 (canonical)（即非別名）成員

@item 
使用 `call' 語法來透過值回傳成員

@item 
使用 `index' 語法來透過名稱回傳成員
@end itemize

列舉透過 @ref{14d8,,class} 語法或函式呼叫的語法來建立：

@example
>>> from enum import Enum

>>> # class 語法
>>> class Color(Enum):
...     RED = 1
...     GREEN = 2
...     BLUE = 3

>>> # 函式語法
>>> Color = Enum('Color', [('RED', 1), ('GREEN', 2), ('BLUE', 3)])
@end example

雖然我們可以用 @ref{14d8,,class} 語法來建立列舉，列舉並不是標準的 Python 類別。參考@ref{28d8,,列舉有何差異}以取得更多細節。

@cartouche
@quotation 備註 
命名方式


@itemize -

@item 
@code{Color} 類別是一個`列舉'（或 `enum'）

@item 
@code{Color.RED}、@code{Color.GREEN} 等屬性是`列舉成員'（或`成員'），並且使用上可以看作常數。

@item 
列舉成員有`名稱'和`值'（@code{Color.RED} 的名稱是 @code{RED}，@code{Color.BLUE} 的值是 @code{3} 諸如此類）
@end itemize
@end quotation
@end cartouche


__________________________________________________________________


@menu
* 模組內容: 模組內容<2>. 
* 資料型別: 資料型別<2>. 
* 通用項目與裝飾器:: 
* 備註:: 

@end menu

@node 模組內容<2>,資料型別<2>,,enum --- 對列舉的支援
@anchor{library/enum module-contents}@anchor{28d9}
@subsubsection 模組內容


@quotation

@ref{4f2,,EnumType}

@quotation

Enum 及其子類別的 @code{type}。
@end quotation

@ref{83b,,Enum}

@quotation

用來建立列舉常數的基礎類別。
@end quotation

@ref{ed6,,IntEnum}

@quotation

用來建立列舉常數的基礎類別，同時也是 @ref{19b,,int} 的子類別。（@ref{28da,,備註}）
@end quotation

@ref{826,,StrEnum}

@quotation

用來建立列舉常數的基礎類別，同時也是 @ref{169,,str} 的子類別。（@ref{28da,,備註}）
@end quotation

@ref{82e,,Flag}

@quotation

用來建立列舉常數的基礎類別，可以使用位元操作來結合成員且其結果不失去 @ref{82e,,Flag} 的成員資格。
@end quotation

@ref{e95,,IntFlag}

@quotation

用來建立列舉常數的基礎類別，可以使用位元操作來結合成員且其結果不失去 @ref{e95,,IntFlag} 的成員資格。@ref{e95,,IntFlag} 的成員也是 @ref{19b,,int} 的子類別。（@ref{28da,,備註}）
@end quotation

@ref{827,,ReprEnum}

@quotation

由 @ref{ed6,,IntEnum}、@ref{826,,StrEnum} 及 @ref{e95,,IntFlag} 所使用來保留這些混合型別的 @ref{169,,str()}。
@end quotation

@ref{831,,EnumCheck}

@quotation

一個有 @code{CONTINUOUS}、@code{NAMED_FLAGS} 及 @code{UNIQUE} 這些值的列舉，和 @ref{830,,verify()} 一起使用來確保給定的列舉符合多種限制。
@end quotation

@ref{82f,,FlagBoundary}

@quotation

一個有 @code{STRICT}、@code{CONFORM}、@code{EJECT} 及 @code{KEEP} 這些值的列舉，允許列舉對如何處理非法值做更細微的控制。
@end quotation

@ref{4f1,,EnumDict}

@quotation

@ref{183,,dict} 的子類別，用於當作 @ref{4f2,,EnumType} 的子類別時使用。
@end quotation

@ref{e96,,auto}

@quotation

列舉成員的實例會被取代成合適的值。@ref{826,,StrEnum} 預設是小寫版本的成員名稱，其它列舉則預設是 1 且往後遞增。
@end quotation

@ref{834,,property()}

@quotation

允許 @ref{83b,,Enum} 成員擁有屬性且不會與成員名稱有衝突。@code{value} 及 @code{name} 屬性是用這個方式來實作。
@end quotation

@ref{28db,,unique()}

@quotation

Enum 類別的裝飾器，用來確保任何值只有綁定到一個名稱上。
@end quotation

@ref{830,,verify()}

@quotation

Enum 類別的裝飾器，用來檢查列舉上使用者所選的限制。
@end quotation

@ref{832,,member()}

@quotation

讓 @code{obj} 變成成員。可以當作裝飾器使用。
@end quotation

@ref{833,,nonmember()}

@quotation

不讓 @code{obj} 變成成員。可以當作裝飾器使用。
@end quotation

@ref{836,,global_enum()}

@quotation

修改列舉上的 @ref{169,,str()} 及 @ref{1c1,,repr()} ，讓成員顯示為屬於模組而不是類別，並將該列舉成員匯出到全域命名空間。
@end quotation

@ref{28dc,,show_flag_values()}

@quotation

回傳旗標 (flag) 裡包含的所有 2 的次方的整數串列。
@end quotation
@end quotation


在 3.6 版被加入: @code{Flag}, @code{IntFlag}, @code{auto}



在 3.11 版被加入: @code{StrEnum}, @code{EnumCheck}, @code{ReprEnum}, @code{FlagBoundary}, @code{property}, @code{member}, @code{nonmember}, @code{global_enum}, @code{show_flag_values}



在 3.13 版被加入: @code{EnumDict}



__________________________________________________________________


@node 資料型別<2>,通用項目與裝飾器,模組內容<2>,enum --- 對列舉的支援
@anchor{library/enum data-types}@anchor{28dd}
@subsubsection 資料型別


@geindex EnumType (enum 中的類別)
@anchor{library/enum enum EnumType}@anchor{4f2}
@deffn {類別} enum.EnumType

`EnumType' 是 `enum' 列舉的 @ref{2282,,metaclass}。`EnumType' 可以有子類別 -- 細節請參考 @ref{28de,,建立 EnumType 的子類別}。

@code{EnumType} 負責在最後的`列舉'上面設定正確的 @code{__repr__()}、@code{__str__()}、@code{__format__()} 及 @code{__reduce__()} 方法，以及建立列舉成員、正確處理重複、提供列舉類別的疊代等等。


在 3.11 版被加入: 在 3.11 之前，@code{EnumType} 稱作 @code{EnumMeta}，其目前仍可作為別名使用。


@geindex __call__() (enum.EnumType 的方法)
@anchor{library/enum enum EnumType __call__}@anchor{28df}
@deffn {方法} __call__ (cls, value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

這個方法可以用兩種不同的方式呼叫：


@itemize *

@item 
查詢已存在的成員：

@quotation

@*cls: 
所呼叫的列舉類別。


@*value: 
要查詢的值。

@end quotation

@item 
使用 @code{cls} 列舉來建立新列舉（只有在現有列舉沒有任何成員時）

@quotation

@*cls: 
所呼叫的列舉類別。


@*value: 
要建立的新列舉的名稱。


@*names: 
新列舉的成員的名稱/值。


@*module: 
新列舉要建立在哪個模組名稱下。


@*qualname: 
這個列舉在模組裡實際上的位置。


@*type: 
新列舉的混合型別。


@*start: 
列舉的第一個整數值（由 @ref{e96,,auto} 所使用）


@*boundary: 
在位元操作時怎麼處理範圍外的值（只有 @ref{82e,,Flag} 會用到）

@end quotation
@end itemize
@end deffn

@geindex __contains__() (enum.EnumType 的方法)
@anchor{library/enum enum EnumType __contains__}@anchor{28e0}
@deffn {方法} __contains__ (cls, member)

如果 member 屬於 @code{cls} 則回傳 @code{True}：

@example
>>> some_var = Color.RED
>>> some_var in Color
True
>>> Color.RED.value in Color
True
@end example


在 3.12 版的變更: 在 Python 3.12 之前，如果用非列舉成員做屬於檢查 (containment check) 會引發 @code{TypeError}。

@end deffn

@geindex __dir__() (enum.EnumType 的方法)
@anchor{library/enum enum EnumType __dir__}@anchor{28e1}
@deffn {方法} __dir__ (cls)

回傳 @code{['__class__', '__doc__', '__members__', '__module__']} 及 `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{28e2}
@deffn {方法} __getitem__ (cls, name)

回傳 `cls' 中符合 `name' 的列舉成員，或引發 @ref{5df,,KeyError}：

@example
>>> Color['BLUE']
<Color.BLUE: 3>
@end example
@end deffn

@geindex __iter__() (enum.EnumType 的方法)
@anchor{library/enum enum EnumType __iter__}@anchor{28e3}
@deffn {方法} __iter__ (cls)

以定義的順序回傳在 `cls' 中的每個成員：

@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{28e4}
@deffn {方法} __len__ (cls)

回傳 `cls' 的成員數量：

@example
>>> len(Color)
3
@end example
@end deffn

@geindex __members__ (enum.EnumType 的屬性)
@anchor{library/enum enum EnumType __members__}@anchor{28e5}
@deffn {屬性} __members__

回傳每個列舉名稱到其成員的對映，包括別名
@end deffn

@geindex __reversed__() (enum.EnumType 的方法)
@anchor{library/enum enum EnumType __reversed__}@anchor{28e6}
@deffn {方法} __reversed__ (cls)

以跟定義相反的順序回傳 `cls' 的每個成員：

@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{83b}
@deffn {類別} enum.Enum

`Enum' 是所有 `enum' 列舉的基礎類別。

@geindex name (enum.Enum 的屬性)
@anchor{library/enum enum Enum name}@anchor{28e7}
@deffn {屬性} name

用來定義 @code{Enum} 成員的名稱：

@example
>>> Color.BLUE.name
'BLUE'
@end example
@end deffn

@geindex value (enum.Enum 的屬性)
@anchor{library/enum enum Enum value}@anchor{28e8}
@deffn {屬性} value

@code{Enum} 成員給定的值：

@example
>>> Color.RED.value
1
@end example

成員的值，可以在 @ref{28e9,,__new__()} 設定。

@cartouche
@quotation 備註 
列舉成員的值

成員的值可以是任何值：@ref{19b,,int}、@ref{169,,str} 等等。如果實際使用什麼值並不重要，你可以使用 @ref{e96,,auto} 實例，它會為你選擇合適的值。更多細節請參考 @ref{e96,,auto}。

雖然可以使用可變的 (mutable) / 不可雜湊的 (unhashable) 值，例如 @ref{183,,dict}、@ref{24d,,list} 或可變的 @ref{4dc,,dataclass}，它們在建立期間會對效能產生相對於列舉中可變的 / 不可雜湊的值總數量的二次方影響。
@end quotation
@end cartouche
@end deffn

@geindex _name_ (enum.Enum 的屬性)
@anchor{library/enum enum Enum _name_}@anchor{28ea}
@deffn {屬性} _name_

成員名稱。
@end deffn

@geindex _value_ (enum.Enum 的屬性)
@anchor{library/enum enum Enum _value_}@anchor{28eb}
@deffn {屬性} _value_

成員的值，可以在 @ref{28e9,,__new__()} 設定。
@end deffn

@geindex _order_ (enum.Enum 的屬性)
@anchor{library/enum enum Enum _order_}@anchor{28ec}
@deffn {屬性} _order_

已不再使用，只為了向後相容而保留（類別屬性，在類別建立時移除）
@end deffn

@geindex _ignore_ (enum.Enum 的屬性)
@anchor{library/enum enum Enum _ignore_}@anchor{28ed}
@deffn {屬性} _ignore_

@code{_ignore_} 只有在建立的時候用到，在列舉建立完成後會被移除。

@code{_ignore_} 是一個不會變成成員的名稱串列，在列舉建立完成後其名稱會被移除。範例請參考 @ref{28ee,,TimePeriod}。
@end deffn

@geindex __dir__() (enum.Enum 的方法)
@anchor{library/enum enum Enum __dir__}@anchor{1b18}
@deffn {方法} __dir__ (self)

回傳 @code{['__class__', '__doc__', '__module__', 'name', 'value']} 及任何 `self.__class__' 上定義的公開方法：

@example
>>> from enum import Enum
>>> from datetime import date
>>> class Weekday(Enum):
...     MONDAY = 1
...     TUESDAY = 2
...     WEDNESDAY = 3
...     THURSDAY = 4
...     FRIDAY = 5
...     SATURDAY = 6
...     SUNDAY = 7
...     @@classmethod
...     def today(cls):
...         print('today is %s' % cls(date.today().isoweekday()).name)
...
>>> dir(Weekday.SATURDAY)
['__class__', '__doc__', '__eq__', '__hash__', '__module__', 'name', 'today', 'value']
@end example
@end deffn

@geindex _generate_next_value_() (enum.Enum 的方法)
@anchor{library/enum enum Enum _generate_next_value_}@anchor{28ef}
@deffn {方法} _generate_next_value_ (name, start, count, last_values)

@quotation

@*name: 
定義的成員名稱（例如 'RED'）。


@*start: 
列舉的開始值，預設為 1。


@*count: 
已定義的成員數量，不包含目前這一個。


@*last_values: 
一個之前值的串列。

@end quotation

一個 `staticmethod'，用來決定 @ref{e96,,auto} 下一個要回傳的值的：

@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
@end deffn

@geindex __init__() (enum.Enum 的方法)
@anchor{library/enum enum Enum __init__}@anchor{28f0}
@deffn {方法} __init__ (self, *args, **kwds)

預設情況下，不執行任何操作。如果在成員賦值中給出多個值，這些值將成為與 @code{__init__} 分別的引數；例如

@example
>>> from enum import Enum
>>> class Weekday(Enum):
...     MONDAY = 1, 'Mon'
@end example

@code{Weekday.__init__()} 將被稱為 @code{Weekday.__init__(self, 1, 'Mon')}
@end deffn

@geindex __init_subclass__() (enum.Enum 的方法)
@anchor{library/enum enum Enum __init_subclass__}@anchor{28f1}
@deffn {方法} __init_subclass__ (cls, **kwds)

一個 `classmethod'，用來進一步設定後續的子類別，預設不做任何事。
@end deffn

@geindex _missing_() (enum.Enum 的方法)
@anchor{library/enum enum Enum _missing_}@anchor{28f2}
@deffn {方法} _missing_ (cls, value)

一個 `classmethod'，用來查詢在 `cls' 裡找不到的值。預設不做任何事，但可以被覆寫以實作客製化的搜尋行為：

@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
@end deffn

@geindex __new__() (enum.Enum 的方法)
@anchor{library/enum enum Enum __new__}@anchor{28e9}
@deffn {方法} __new__ (cls, *args, **kwds)

預設情況下不存在。如果有指定，無論是在列舉類別定義中還是在 mixin 類別中（例如 @code{int}），都將傳遞成員賦值中給出的所有值；例如

@example
>>> from enum import Enum
>>> class MyIntEnum(int, Enum):
...     TWENTYSIX = '1a', 16
@end example

會產生呼叫 @code{int('1a', 16)} 而該成員的值為 @code{26}。

@cartouche
@quotation 備註 
當寫自訂的 @code{__new__} 時，不要使用 @code{super().__new__}，而是要呼叫適當的 @code{__new__}。
@end quotation
@end cartouche
@end deffn

@geindex __repr__() (enum.Enum 的方法)
@anchor{library/enum enum Enum __repr__}@anchor{1a40}
@deffn {方法} __repr__ (self)

回傳呼叫 `repr()' 時使用的字串。預設回傳 `Enum' 名稱、成員名稱及值，但可以被覆寫：

@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{82d}
@deffn {方法} __str__ (self)

回傳呼叫 `str()' 時使用的字串。預設回傳 `Enum' 名稱及成員名稱，但可以被覆寫：

@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{82b}
@deffn {方法} __format__ (self)

回傳呼叫 `format()' 及 `f-string' 時使用的字串。預設回傳 @ref{82d,,__str__()} 的回傳值，但可以被覆寫：

@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 備註 
@ref{83b,,Enum} 使用 @ref{e96,,auto} 會產生從 @code{1} 開始遞增的整數。
@end quotation
@end cartouche


在 3.12 版的變更: 新增 @ref{1a3f,,Dataclass support}


@geindex _add_alias_() (enum.Enum 的方法)
@anchor{library/enum enum Enum _add_alias_}@anchor{28f3}
@deffn {方法} _add_alias_ ()

新增一個名稱作為現有成員的別名：

@example
>>> Color.RED._add_alias_("ERROR")
>>> Color.ERROR
<Color.RED: 1>
@end example

如果該名稱已經被指派給不同的成員，則會引發 @ref{450,,NameError}。


在 3.13 版被加入.

@end deffn

@geindex _add_value_alias_() (enum.Enum 的方法)
@anchor{library/enum enum Enum _add_value_alias_}@anchor{28f4}
@deffn {方法} _add_value_alias_ ()

新增一個值作為現有成員的別名：

@example
>>> Color.RED._add_value_alias_(42)
>>> Color(42)
<Color.RED: 1>
@end example

如果該值已經被連結到不同的成員，則會引發 @ref{2eb,,ValueError}。


在 3.13 版被加入.

@end deffn
@end deffn

@geindex IntEnum (enum 中的類別)
@anchor{library/enum enum IntEnum}@anchor{ed6}
@deffn {類別} enum.IntEnum

`IntEnum' 和 @ref{83b,,Enum} 一樣，但其成員同時也是整數而可以被用在任何使用整數的地方。如果 `IntEnum' 成員經過任何整數運算，結果值會失去其列舉狀態。

@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 備註 
@ref{ed6,,IntEnum} 使用 @ref{e96,,auto} 會產生從 @code{1} 開始遞增的整數。
@end quotation
@end cartouche


在 3.11 版的變更: 為了更好地支援`現存常數取代 (replacement of existing constants)' 的使用情境，@ref{829,,__str__()} 現在會是 @code{int.__str__()}。為了同樣的理由，@ref{82a,,__format__()} 已經是 @code{int.__format__()}。

@end deffn

@geindex StrEnum (enum 中的類別)
@anchor{library/enum enum StrEnum}@anchor{826}
@deffn {類別} enum.StrEnum

`StrEnum' 和 @ref{83b,,Enum} 一樣，但其成員同時也是字串而可以被用在幾乎所有使用字串的地方。`StrEnum' 成員經過任何字串操作的結果會不再是列舉的一部份。

@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 備註 
stdlib 裡有些地方會檢查只能是 @ref{169,,str} 而不是 @ref{169,,str} 的子類別（也就是 @code{type(unknown) == str} 而不是 @code{isinstance(unknown, str)}），在這些地方你需要使用 @code{str(MyStrEnum.MY_MEMBER)}。
@end quotation
@end cartouche

@cartouche
@quotation 備註 
@ref{826,,StrEnum} 使用 @ref{e96,,auto} 會產生小寫的成員名稱當作值。
@end quotation
@end cartouche

@cartouche
@quotation 備註 
為了更好地支援`現存常數取代 (replacement of existing constants)' 的使用情境，@ref{829,,__str__()} 現在會是 @code{str.__str__()}。為了同樣的理由，@ref{82a,,__format__()} 也會是 @code{str.__format__()}。
@end quotation
@end cartouche


在 3.11 版被加入.

@end deffn

@geindex Flag (enum 中的類別)
@anchor{library/enum enum Flag}@anchor{82e}
@deffn {類別} enum.Flag

@code{Flag} 與 @ref{83b,,Enum} 相同，但其成員支援位元運算子 @code{&} (`AND')、@code{|} (`OR')、@code{^} (`XOR') 和 @code{~} (`INVERT')；這些操作的結果是列舉的成員（的別名）。

@geindex __contains__() (enum.Flag 的方法)
@anchor{library/enum enum Flag __contains__}@anchor{28f5}
@deffn {方法} __contains__ (self, value)

如果 value 在 self 裡則回傳 `True'：

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

回傳所有包含的非別名成員：

@example
>>> list(Color.RED)
[<Color.RED: 1>]
>>> list(purple)
[<Color.RED: 1>, <Color.BLUE: 4>]
@end example


在 3.11 版被加入.

@end deffn


@deffn {方法} __len__(self):

回傳旗標裡的成員數量：

@example
>>> len(Color.GREEN)
1
>>> len(white)
3
@end example


在 3.11 版被加入.

@end deffn


@deffn {方法} __bool__(self):

如果成員在旗標裡則回傳 `True'，否則回傳 `False'：

@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{28f6}
@deffn {方法} __or__ (self, other)

回傳和 other 做 OR 過後的二進位旗標：

@example
>>> Color.RED | Color.GREEN
<Color.RED|GREEN: 3>
@end example
@end deffn

@geindex __and__() (enum.Flag 的方法)
@anchor{library/enum enum Flag __and__}@anchor{28f7}
@deffn {方法} __and__ (self, other)

回傳和 other 做 AND 過後的二進位旗標：

@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{28f8}
@deffn {方法} __xor__ (self, other)

回傳和 other 做 XOR 過後的二進位旗標：

@example
>>> purple ^ white
<Color.GREEN: 2>
>>> purple ^ Color.GREEN
<Color.RED|GREEN|BLUE: 7>
@end example
@end deffn


@deffn {方法} __invert__(self):

回傳所有在 `type(self)' 但不在 `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{28f9}
@deffn {方法} _numeric_repr_ ()

用來格式化任何剩下未命名數值的函式。預設是值的 repr，常見選擇是 @ref{14d0,,hex()} 和 @ref{14cf,,oct()}。
@end deffn

@cartouche
@quotation 備註 
@ref{82e,,Flag} 使用 @ref{e96,,auto} 會產生從 @code{1} 開始 2 的次方的整數。
@end quotation
@end cartouche


在 3.11 版的變更: 值為 0 的旗標的 `repr()' 已改變。現在是：

@example
>>> Color(0)
<Color: 0>
@end example

@end deffn

@geindex IntFlag (enum 中的類別)
@anchor{library/enum enum IntFlag}@anchor{e95}
@deffn {類別} enum.IntFlag

@code{IntFlag} 和 @ref{82e,,Flag} 一樣，但其成員同時也是整數而可以被用在任何使用整數的地方。

@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

如果 `IntFlag' 成員經過任何整數運算，其結果不是 `IntFlag'：

@example
>>> Color.RED + 2
3
@end example

如果 `IntFlag' 成員經過 @ref{82e,,Flag} 操作且：


@itemize *

@item 
結果是合法的 `IntFlag'：回傳 `IntFlag'

@item 
結果不是合法的 `IntFlag'：結果會根據 @ref{82f,,FlagBoundary} 的設定
@end itemize

未命名且值為 0 的旗標的 @ref{1c1,,repr()} 已改變。現在是：

@example
>>> Color(0)
<Color: 0>
@end example

@cartouche
@quotation 備註 
@ref{e95,,IntFlag} 使用 @ref{e96,,auto} 會產生從 @code{1} 開始 2 的次方的整數。
@end quotation
@end cartouche


在 3.11 版的變更: 為了更好地支援`現存常數取代 (replacement of existing constants)' 的使用情境，@ref{829,,__str__()} 現在會是 @code{int.__str__()}。為了同樣的理由，@ref{82a,,__format__()} 已經是 @code{int.__format__()}。

@code{IntFlag} 的反轉 (inversion) 現在會回傳正值，該值是不在給定旗標的所有旗標聯集，而不是一個負值。這符合現有 @ref{82e,,Flag} 的行為。

@end deffn

@geindex ReprEnum (enum 中的類別)
@anchor{library/enum enum ReprEnum}@anchor{827}
@deffn {類別} enum.ReprEnum

@code{ReprEnum} 使用 @ref{83b,,Enum} 的 @ref{1a40,,repr()}，但使用混合資料型別的 @ref{169,,str()}：


@itemize *

@item 
對 @ref{ed6,,IntEnum} 和 @ref{e95,,IntFlag} 是 @code{int.__str__()}

@item 
對 @ref{826,,StrEnum} 是 @code{str.__str__()}
@end itemize

繼承 @code{ReprEnum} 來保留混合資料型別的 @ref{169,,str()} / @ref{199,,format()}，而不是使用 @ref{83b,,Enum} 預設的 @ref{82d,,str()}。


在 3.11 版被加入.

@end deffn

@geindex EnumCheck (enum 中的類別)
@anchor{library/enum enum EnumCheck}@anchor{831}
@deffn {類別} enum.EnumCheck

`EnumCheck' 包含 @ref{830,,verify()} 裝飾器使用的選項，以確保多樣的限制，不符合限制會產生 @ref{2eb,,ValueError}。

@geindex UNIQUE (enum.EnumCheck 的屬性)
@anchor{library/enum enum EnumCheck UNIQUE}@anchor{28fa}
@deffn {屬性} UNIQUE

確保每個值只有一個名稱：

@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{28fb}
@deffn {屬性} CONTINUOUS

確保在最小值成員跟最大值成員間沒有缺少值：

@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{28fc}
@deffn {屬性} NAMED_FLAGS

確保任何旗標群組 / 遮罩只包含命名旗標 -- 當值是用指定而不是透過 @ref{e96,,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 和 NAMED_FLAGS 是設計用來運作在整數值的成員上。
@end quotation
@end cartouche


在 3.11 版被加入.

@end deffn

@geindex FlagBoundary (enum 中的類別)
@anchor{library/enum enum FlagBoundary}@anchor{82f}
@deffn {類別} enum.FlagBoundary

@code{FlagBoundary} 控制在 @ref{82e,,Flag} 及其子類別中如何處理範圍外的值。

@geindex STRICT (enum.FlagBoundary 的屬性)
@anchor{library/enum enum FlagBoundary STRICT}@anchor{28fd}
@deffn {屬性} STRICT

範圍外的值會引發 @ref{2eb,,ValueError}。這是 @ref{82e,,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{28fe}
@deffn {屬性} CONFORM

會移除範圍外的值中的非法值，留下合法的 @ref{82e,,Flag} 值：

@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{28ff}
@deffn {屬性} EJECT

範圍外的值會失去它們的 @ref{82e,,Flag} 成員資格且恢復成 @ref{19b,,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{2900}
@deffn {屬性} KEEP

範圍外的值會被保留，@ref{82e,,Flag} 成員資格也會被保留。這是 @ref{e95,,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


在 3.11 版被加入.

@end deffn

@geindex EnumDict (enum 中的類別)
@anchor{library/enum enum EnumDict}@anchor{4f1}
@deffn {類別} enum.EnumDict

`EnumDict' 是 @ref{183,,dict} 的子類別，用來作為定義列舉類別的命名空間（參見 @ref{e53,,Preparing the class namespace}）。它被公開來使得 @ref{4f2,,EnumType} 的子類別能具有進階行為，例如讓每個成員有多個值。它應該在被呼叫時帶上正在建立的列舉類別名稱，否則私有名稱和內部類別將無法被正確處理。

注意只有 @ref{12ad,,MutableMapping} 介面（@ref{14cc,,__setitem__()} 和 @ref{165a,,update()}）被覆寫。可能可以使用其他 @code{dict} 操作來繞過檢查，例如 @ref{22b0,,|=}。

@geindex member_names (enum.EnumDict 的屬性)
@anchor{library/enum enum EnumDict member_names}@anchor{2901}
@deffn {屬性} member_names

一個成員名稱的串列。
@end deffn


在 3.13 版被加入.

@end deffn


__________________________________________________________________


@menu
* 支援的 __dunder__ 名稱:: 
* 支援的 _sunder_ 名稱:: 

@end menu

@node 支援的 __dunder__ 名稱,支援的 _sunder_ 名稱,,資料型別<2>
@anchor{library/enum supported-dunder-names}@anchor{2902}
@subsubsection 支援的 @code{__dunder__} 名稱


@ref{28e5,,__members__} 是一個唯讀有序的@code{成員名稱}：@code{成員}項目的對映。只有在類別上可用。

@ref{28e9,,__new__()}，如果有指定，它必須建立並回傳列舉成員；適當地設定成員的 @code{_value_} 也是一個很好的主意。一旦所有成員都建立之後就不會再被用到。

@node 支援的 _sunder_ 名稱,,支援的 __dunder__ 名稱,資料型別<2>
@anchor{library/enum supported-sunder-names}@anchor{2903}
@subsubsection 支援的 @code{_sunder_} 名稱



@itemize -

@item 
@ref{28ea,,_name_} -- 成員名稱

@item 
@ref{28eb,,_value_} -- 成員的值；可以在 @code{__new__} 設定

@item 
@ref{28f2,,_missing_()} -- 當值沒有被找到時會使用的查詢函式；可以被覆寫

@item 
@ref{28ed,,_ignore_} -- 一個名稱的串列，可以是 @ref{24d,,list} 或 @ref{169,,str}，它不會被轉換成成員，且在最後的類別上會被移除

@item 
@ref{28ec,,_order_} -- 不再被使用，僅為了向後相容而保留（類別屬性，在類別建立時移除）

@item 
@ref{28ef,,_generate_next_value_()} -- 用來為列舉成員取得合適的值；可以被覆寫

@cartouche
@quotation 備註 
對標準的 @ref{83b,,Enum} 類別來說，下一個被選擇的值是所看過的最大值加一。

對 @ref{82e,,Flag} 類別來說，下一個被選擇的值是下一個最大的 2 的次方的數字。
@end quotation
@end cartouche

@item 
@ref{28f3,,_add_alias_()} -- 新增一個名稱作為現有成員的別名。

@item 
@ref{28f4,,_add_value_alias_()} -- 新增一個值作為現有成員的別名。

@item 
雖然 @code{_sunder_} 名稱通常保留用於 @ref{83b,,Enum} 類別的進一步開發而不能被使用，但有些是明確允許的：


@itemize -

@item 
@code{_repr_*}（例如 @code{_repr_html_}），例如用於 IPython 的豐富顯示@footnote{https://ipython.readthedocs.io/en/stable/config/integrating.html#rich-display}
@end itemize
@end itemize


在 3.6 版被加入: @code{_missing_}、@code{_order_}、@code{_generate_next_value_}



在 3.7 版被加入: @code{_ignore_}



在 3.13 版被加入: @code{_add_alias_}、@code{_add_value_alias_}、@code{_repr_*}



__________________________________________________________________


@node 通用項目與裝飾器,備註,資料型別<2>,enum --- 對列舉的支援
@anchor{library/enum ipython-s-rich-display}@anchor{2904}@anchor{library/enum utilities-and-decorators}@anchor{2905}
@subsubsection 通用項目與裝飾器


@geindex auto (enum 中的類別)
@anchor{library/enum enum auto}@anchor{e96}
@deffn {類別} enum.auto

`auto' 可以用來取代給值。如果使用的話，`Enum' 系統會呼叫 @ref{83b,,Enum} 的 @ref{28ef,,_generate_next_value_()} 來取得合適的值。對 @ref{83b,,Enum} 和 @ref{ed6,,IntEnum} 來說，合適的值是最後一個值加一；對 @ref{82e,,Flag} 和 @ref{e95,,IntFlag} 來說，是第一個比最大值還大的 2 的次方的數字；對 @ref{826,,StrEnum} 來說，是成員名稱的小寫版本。如果混用 `auto()' 和手動指定值的話要特別注意。

`auto' 實例只有在最上層的賦值時才會被解析：


@itemize *

@item 
@code{FIRST = auto()} 可以運作（auto() 會被取代成 @code{1}）

@item 
@code{SECOND = auto(), -2} 可以運作（auto 會被取代成 @code{2}, 因此 @code{2, -2} 會被用來建立列舉成員 @code{SECOND}；

@item 
@code{THREE = [auto(), -3]} `無法'運作（@code{<auto 實例>, -3} 會被用來建立列舉成員 @code{THREE}）
@end itemize


在 3.11.1 版的變更: 在之前的版本中，@code{auto()} 必須是賦值行裡的唯一內容才能運作正確。


可以覆寫 @code{_generate_next_value_} 來客製 `auto' 使用的值。

@cartouche
@quotation 備註 
在 3.13 預設 @code{_generate_next_value_} 總是回傳最大的成員值加一，如果任何成員是不相容的型別就會失敗。
@end quotation
@end cartouche
@end deffn

@geindex property() (於 enum 模組中)
@anchor{library/enum enum property}@anchor{834}
@deffn {函式} @@enum.property

和內建的 `property' 相似的裝飾器，但只專門針對列舉。它允許成員屬性和成員本身有相同名稱。

@cartouche
@quotation 備註 
`屬性'和成員必須定義在分開的類別裡；例如 `value' 和 `name' 屬性定義在 `Enum' 類別而 `Enum' 子類別可以定義成員名稱為 @code{value} 和 @code{name}。
@end quotation
@end cartouche


在 3.11 版被加入.

@end deffn

@geindex unique() (於 enum 模組中)
@anchor{library/enum enum unique}@anchor{28db}
@deffn {函式} @@enum.unique

專門針對列舉的 @ref{14d8,,class} 裝飾器。它搜尋列舉的 @ref{28e5,,__members__}，蒐集任何它找到的別名；如果有找到任何別名則引發 @ref{2eb,,ValueError} 並附上細節：

@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{830}
@deffn {函式} @@enum.verify

專門針對列舉的 @ref{14d8,,class} 裝飾器。使用 @ref{831,,EnumCheck} 裡的成員來指定在裝飾的列舉上應該檢查什麼限制。


在 3.11 版被加入.

@end deffn

@geindex member() (於 enum 模組中)
@anchor{library/enum enum member}@anchor{832}
@deffn {函式} @@enum.member

列舉所使用的裝飾器：其目標會變成成員。


在 3.11 版被加入.

@end deffn

@geindex nonmember() (於 enum 模組中)
@anchor{library/enum enum nonmember}@anchor{833}
@deffn {函式} @@enum.nonmember

列舉所使用的裝飾器：其目標不會變成成員。


在 3.11 版被加入.

@end deffn

@geindex global_enum() (於 enum 模組中)
@anchor{library/enum enum global_enum}@anchor{836}
@deffn {函式} @@enum.global_enum

修改列舉的 @ref{169,,str()} 及 @ref{1c1,,repr()} 的裝飾器，讓成員顯示為屬於模組而不是其類別。應該只有當列舉成員被匯出到模組的全域命名空間才使用（範例請參考 @ref{837,,re.RegexFlag}）。


在 3.11 版被加入.

@end deffn

@geindex show_flag_values() (於 enum 模組中)
@anchor{library/enum enum show_flag_values}@anchor{28dc}
@deffn {函式} enum.show_flag_values (value)

回傳在旗標`值'中包含的所有 2 的次方的整數串列。


在 3.11 版被加入.

@end deffn


__________________________________________________________________


@node 備註,,通用項目與裝飾器,enum --- 對列舉的支援
@anchor{library/enum notes}@anchor{28da}
@subsubsection 備註


@ref{ed6,,IntEnum}、@ref{826,,StrEnum} 及 @ref{e95,,IntFlag}

@quotation

這三種列舉型別是設計來直接取代現有以整數及字串為基底的值；因此它們有額外的限制：


@itemize -

@item 
@code{__str__} 使用值而不是列舉成員的名稱

@item 
@code{__format__} 因為使用 @code{__str__}，也會使用值而不是列舉成員的名稱
@end itemize

如果你不需要或不想要這些限制，你可以透過混合 @code{int} 或 @code{str} 型別來建立自己的基礎類別：

@example
>>> from enum import Enum
>>> class MyIntEnum(int, Enum):
...     pass
@end example

或者你也可以在你的列舉重新給定合適的 @ref{169,,str()}：

@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 —-- 使用類圖 graph-like 結構進行操作的功能,,enum --- 對列舉的支援,資料型別
@anchor{library/graphlib doc}@anchor{2906}@anchor{library/graphlib graphlib-functionality-to-operate-with-graph-like-structures}@anchor{2907}@anchor{library/graphlib module-graphlib}@anchor{69}@anchor{library/graphlib translation-repo}@anchor{2908}
@subsection @code{graphlib} —-- 使用類圖 (graph-like) 結構進行操作的功能


@geindex module; graphlib

`原始碼：'Lib/graphlib.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/graphlib.py}

@c import graphlib
@c from graphlib import *


__________________________________________________________________


@geindex TopologicalSorter (graphlib 中的類別)
@anchor{library/graphlib graphlib TopologicalSorter}@anchor{ad5}
@deffn {類別} graphlib.TopologicalSorter (graph=None)

提供對包含@ref{81d,,可雜湊 (hashable)} 節點之圖 (graph) 進行拓撲排序 (topologically sort) 的功能。

拓撲排序是圖中頂點 (vertex) 的線性排序，使得對於從頂點 u 到頂點 v 的每條有向邊 (directed edge) u -> v，頂點 u 在排序中會位於頂點 v 之前。例如，圖的頂點可能代表要執行的任務，而邊可能代表一個任務必須在另一個任務之前執行的限制；在此範例中，拓撲排序只是任務的一種有效序列。若且唯若 (if and only if) 圖沒有有向環 (directed cycle) 時，即如果它是個有向無環圖 (directed acyclic graph)，則完整的拓撲排序才是可行的。

如果提供了可選的 `graph' 引數，它必須是表示有向無環圖的字典，其中鍵是節點，值是圖中該節點的包含所有前驅節點 (predecessor) 之可疊代物件（這些前驅節點具有指向以鍵表示之節點的邊）。可以使用 @ref{2909,,add()} 方法將其他節點新增到圖中。

在一般情況下，對給定的圖執行排序所需的步驟如下：


@itemize *

@item 
以選用的初始圖建立 @ref{ad5,,TopologicalSorter} 的實例。

@item 
在圖中新增其他節點。

@item 
呼叫圖的 @ref{21f,,prepare()}。

@item 
當 @ref{290a,,is_active()} 為 @code{True} 時，疊代 @ref{290b,,get_ready()} 回傳的節點並處理它們。在每個節點完成處理時呼叫 @ref{290c,,done()}。
@end itemize

如果只需要立即對圖中的節點進行排序且不涉及平行性 (parallelism)，則可以直接使用便捷方法 @ref{290d,,TopologicalSorter.static_order()}：

@example
>>> graph = @{"D": @{"B", "C"@}, "C": @{"A"@}, "B": @{"A"@}@}
>>> ts = TopologicalSorter(graph)
>>> tuple(ts.static_order())
('A', 'C', 'B', 'D')
@end example

該類別設計為在節點準備就緒時，簡單支援節點的平行處理。例如：

@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{2909}
@deffn {方法} add (node, *predecessors)

向圖中新增新節點及其前驅節點。`node' 和 `predecessors' 中的所有元素都必須是@ref{81d,,可雜湊}的。

如果以相同節點引數多次呼叫，則依賴項的集合將會是傳入的所有依賴項的聯集。

可以新增一個沒有依賴關係的節點（`predecessors' 未提供）或提供兩次依賴關係。如果有之前未曾提供的節點被包含在 `predecessors' 中，它將自動新增到沒有前驅節點的圖中。

如果在 @ref{21f,,prepare()} 之後呼叫，則引發 @ref{2eb,,ValueError}。
@end deffn

@geindex prepare() (graphlib.TopologicalSorter 的方法)
@anchor{library/graphlib graphlib TopologicalSorter prepare}@anchor{21f}
@deffn {方法} prepare ()

將圖標記為已完成並檢查圖中的循環。如果檢測到任何循環，將引發 @ref{290e,,CycleError}，但 @ref{290b,,get_ready()} 仍可用於盡可能獲得更多的節點，直到循環阻塞了進度。呼叫此函式後就無法修改圖，因此無法使用 @ref{2909,,add()} 來新增更多節點。

A @ref{2eb,,ValueError} will be raised if the sort has been started by
@ref{290d,,static_order()} or @ref{290b,,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{2eb,,ValueError}.

@end deffn

@geindex is_active() (graphlib.TopologicalSorter 的方法)
@anchor{library/graphlib graphlib TopologicalSorter is_active}@anchor{290a}
@deffn {方法} is_active ()

如果可以有更多進度則回傳 @code{True}，否則回傳 @code{False}。如果循環不阻塞解析 (resolution) 並且仍有節點準備就緒但尚未由 @ref{290b,,TopologicalSorter.get_ready()} 回傳或標記為 @ref{290c,,TopologicalSorter.done()} 的節點數量較 @ref{290b,,TopologicalSorter.get_ready()} 所回傳的少，則可以繼續取得進度。

此類別的 @ref{14d6,,__bool__()} 方法遵循此函式，因此以下做法：

@example
if ts.is_active():
    ...
@end example

可以簡單地用以下方式替換：

@example
if ts:
    ...
@end example

如果呼叫之前沒有先呼叫 @ref{21f,,prepare()} 則引發 @ref{2eb,,ValueError}。
@end deffn

@geindex done() (graphlib.TopologicalSorter 的方法)
@anchor{library/graphlib graphlib TopologicalSorter done}@anchor{290c}
@deffn {方法} done (*nodes)

將 @ref{290b,,TopologicalSorter.get_ready()} 回傳的一組節點標記為已處理，停止阻塞 `nodes' 中每個節點的任何後繼節點 (successor)，以便將來通過呼叫 @ref{290b,,TopologicalSorter.get_ready()} 回傳。

若沒有和該呼叫一起呼叫 @ref{21f,,prepare()} 或節點還沒有被 @ref{290b,,get_ready()} 回傳，且如果 `nodes' 中有任何節點已被先前對此方法的呼叫標記為已處理、或者未使用 @ref{2909,,TopologicalSorter.add()} 將節點新增到圖中，則引發 @ref{2eb,,ValueError}。
@end deffn

@geindex get_ready() (graphlib.TopologicalSorter 的方法)
@anchor{library/graphlib graphlib TopologicalSorter get_ready}@anchor{290b}
@deffn {方法} get_ready ()

回傳一個包含所有準備就緒節點的 @code{tuple}。最初它回傳沒有前驅節點的所有節點，一旦通過呼叫 @ref{290c,,TopologicalSorter.done()} 來將這些節點標記為已處理後，進一步的呼叫將回傳所有其全部前驅節點都已被處理的新節點。若無法取得更多進度，將回傳空 tuple。

如果呼叫之前沒有先呼叫 @ref{21f,,prepare()} 則引發 @ref{2eb,,ValueError}。
@end deffn

@geindex static_order() (graphlib.TopologicalSorter 的方法)
@anchor{library/graphlib graphlib TopologicalSorter static_order}@anchor{290d}
@deffn {方法} static_order ()

回傳一個可疊代物件，它將按拓撲排序疊代節點。使用此方法時，不應呼叫 @ref{21f,,prepare()} 和 @ref{290c,,done()}。此方法等效於：

@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

回傳的特定順序可能取決於將項目插入圖中的特定順序。例如：

@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

這是因為 "0" 和 "2" 在圖中處於同一級別（它們將在對 @ref{290b,,get_ready()} 的同一呼叫中回傳）並且它們之間的順序取決於插入順序。

如果檢測到任何循環，則引發 @ref{290e,,CycleError}。
@end deffn


在 3.9 版被加入.

@end deffn

@menu
* 例外: 例外<3>. 

@end menu

@node 例外<3>,,,graphlib —-- 使用類圖 graph-like 結構進行操作的功能
@anchor{library/graphlib exceptions}@anchor{290f}
@subsubsection 例外


@ref{69,,graphlib} 模組定義了以下例外類別：

@geindex CycleError
@anchor{library/graphlib graphlib CycleError}@anchor{290e}
@deffn {例外} graphlib.CycleError

@ref{2eb,,ValueError} 的子類別，如果作用的圖中存在循環則由 @ref{21f,,TopologicalSorter.prepare()} 引發。如果存在多個循環，則只會報告未定義的其中一個並包含在例外中。

檢測到的循環可以通過例外實例的 @ref{786,,args} 屬性中第二個元素來存取，其為一個節點列表，每個節點在圖中都是列表中下一個節點的直接前驅節點（immediate predecessor，即父節點）。在報告列表中，第一個和最後一個節點將會是相同的，用以明確表示它是循環的。
@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 數值與數學模組,函式程式設計模組,資料型別,Python 標準函式庫 Standard Library
@anchor{library/numeric doc}@anchor{2910}@anchor{library/numeric numeric}@anchor{2911}@anchor{library/numeric numeric-and-mathematical-modules}@anchor{2912}@anchor{library/numeric translation-repo}@anchor{2913}
@section 數值與數學模組


本章所描述的模組提供了數值和與數學相關的函式和資料型別。@ref{a2,,numbers} 模組定義了數值型別的抽象階層結構。@ref{92,,math} 和 @ref{19,,cmath} 模組包含了用於浮點數和複數的各種數學函式。@ref{3a,,decimal} 模組支援對十進位數字的精確表示以及任意精度的算術運算。

本章節包含下列的模組：

@menu
* numbers: numbers --- 數值的抽象基底類別. 數值的抽象基底類別
* math: math --- 數學函式. 數學函式
* cmath: cmath --- 複數的數學函式. 複數的數學函式
* decimal: decimal --- 十進位固定點和浮點運算. 十進位固定點和浮點運算
* fractions: fractions --- 有理數. 有理數
* random: random --- 產生偽隨機數. 產生偽隨機數
* statistics: statistics --- 數學統計函式. 數學統計函式

@end menu

@node numbers --- 數值的抽象基底類別,math --- 數學函式,,數值與數學模組
@anchor{library/numbers doc}@anchor{2914}@anchor{library/numbers module-numbers}@anchor{a2}@anchor{library/numbers numbers-numeric-abstract-base-classes}@anchor{2915}
@subsection @code{numbers} --- 數值的抽象基底類別


@geindex module; numbers

`原始碼：'Lib/numbers.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/numbers.py}


__________________________________________________________________


@code{numbers} 模組 (
@geindex Python Enhancement Proposals; PEP 3141
PEP 3141@footnote{https://peps.python.org/pep-3141/}) 定義了數值@ref{13b7,,抽象基底類別} 的階層結構，其中逐一定義了更多操作。此模組中定義的型別都不可被實例化。

@geindex Number (numbers 中的類別)
@anchor{library/numbers numbers Number}@anchor{2916}
@deffn {類別} numbers.Number

數值階層結構的基礎。如果你只想確認引數 `x' 是不是數值、並不關心其型別，請使用 @code{isinstance(x, Number)}。
@end deffn

@menu
* 數值的階層:: 
* 給型別實作者的註記:: 

@end menu

@node 數值的階層,給型別實作者的註記,,numbers --- 數值的抽象基底類別
@anchor{library/numbers the-numeric-tower}@anchor{2917}
@subsubsection 數值的階層


@geindex Complex (numbers 中的類別)
@anchor{library/numbers numbers Complex}@anchor{24ac}
@deffn {類別} numbers.Complex

這個型別的子類別描述了複數並包含適用於內建 @ref{197,,complex} 型別的操作。這些操作有：@ref{197,,complex} 和 @ref{3c1,,bool} 的轉換、@ref{2918,,real}、@ref{2919,,imag}、@code{+}、@code{-}、@code{*}、@code{/}、@code{**}、@ref{1f54,,abs()}、@ref{291a,,conjugate()}、@code{==} 以及 @code{!=}。除 @code{-} 和 @code{!=} 之外所有操作都是抽象的。

@geindex real (numbers.Complex 的屬性)
@anchor{library/numbers numbers Complex real}@anchor{2918}
@deffn {屬性} real

為抽象的。取得該數值的實數部分。
@end deffn

@geindex imag (numbers.Complex 的屬性)
@anchor{library/numbers numbers Complex imag}@anchor{2919}
@deffn {屬性} imag

為抽象的。取得該數值的虛數部分。
@end deffn

@geindex conjugate() (numbers.Complex 的方法)
@anchor{library/numbers numbers Complex conjugate}@anchor{291a}
@deffn {方法} abstractmethod conjugate ()

為抽象的。回傳共軛複數，例如 @code{(1+3j).conjugate() == (1-3j)}。
@end deffn
@end deffn

@geindex Real (numbers 中的類別)
@anchor{library/numbers numbers Real}@anchor{24a2}
@deffn {類別} numbers.Real

相對於 @ref{24ac,,Complex}，@code{Real} 加入了只有實數才能進行的操作。

簡單的說，有 @ref{196,,float} 的轉換、@ref{15b7,,math.trunc()}、@ref{14db,,round()}、@ref{15b5,,math.floor()}、@ref{15b6,,math.ceil()}、@ref{b90,,divmod()}、@code{//}、@code{%}、 @code{<}、@code{<=}、@code{>}、和 @code{>=}。

實數同樣提供 @ref{197,,complex()}、@ref{2918,,real}、@ref{2919,,imag} 和 @ref{291a,,conjugate()} 的預設值。
@end deffn

@geindex Rational (numbers 中的類別)
@anchor{library/numbers numbers Rational}@anchor{14bf}
@deffn {類別} numbers.Rational

@ref{24a2,,Real} 的子型別，並增加了 @ref{291b,,numerator} 和 @ref{291c,,denominator} 這兩種特性。它也會提供 @ref{196,,float()} 的預設值。

@ref{291b,,numerator} 和 @ref{291c,,denominator} 的值必須是 @ref{22b9,,Integral} 的實例且 @ref{291c,,denominator} 要是正數。

@geindex numerator (numbers.Rational 的屬性)
@anchor{library/numbers numbers Rational numerator}@anchor{291b}
@deffn {屬性} numerator

為抽象的。該有理數的分子。
@end deffn

@geindex denominator (numbers.Rational 的屬性)
@anchor{library/numbers numbers Rational denominator}@anchor{291c}
@deffn {屬性} denominator

為抽象的。該有理數的分母。
@end deffn
@end deffn

@geindex Integral (numbers 中的類別)
@anchor{library/numbers numbers Integral}@anchor{22b9}
@deffn {類別} numbers.Integral

@ref{14bf,,Rational} 的子型別，並增加了 @ref{19b,,int} 的轉換操作。為 @ref{196,,float()}、@ref{291b,,numerator} 和 @ref{291c,,denominator} 提供了預設值。為 @ref{1a4,,pow()} 方法增加了求餘 (modulus) 和位元字串運算 (bit-string operations) 的抽象方法：@code{<<}、@code{>>}、@code{&}、@code{^}、@code{|}、@code{~}。
@end deffn

@node 給型別實作者的註記,,數值的階層,numbers --- 數值的抽象基底類別
@anchor{library/numbers notes-for-type-implementers}@anchor{291d}
@subsubsection 給型別實作者的註記


實作者需注意，相等的數值除了大小相等外，還必須擁有同樣的雜湊值。當使用兩個不同的實數擴充時，這可能是很微妙的。例如，@ref{213,,fractions.Fraction} 底下的 @ref{7fa,,hash()} 實作如下：

@example
def __hash__(self):
    if self.denominator == 1:
        # 正確處理整數。
        return hash(self.numerator)
    # 檢查費時，但絕對正確。
    if self == float(self):
        return hash(float(self))
    else:
        # 使用 tuple 的雜湊值以避免簡單分數上的高碰撞率。
        return hash((self.numerator, self.denominator))
@end example

@menu
* 加入更多數值 ABC:: 
* 實作算術操作:: 

@end menu

@node 加入更多數值 ABC,實作算術操作,,給型別實作者的註記
@anchor{library/numbers adding-more-numeric-abcs}@anchor{291e}
@subsubsection 加入更多數值 ABC


當然，還有更多用於數值的 ABC，如果不加入它們就不會有健全的階層。你可以在 @ref{24ac,,Complex} 和 @ref{24a2,,Real} 中加入 @code{MyFoo}，像是：

@example
class MyFoo(Complex): ...
MyFoo.register(Real)
@end example

@node 實作算術操作,,加入更多數值 ABC,給型別實作者的註記
@anchor{library/numbers id1}@anchor{291f}@anchor{library/numbers implementing-the-arithmetic-operations}@anchor{21e7}
@subsubsection 實作算術操作


我們想要實作算術操作，來使得混合模式操作要麼呼叫一個作者知道兩個引數之型別的實作，要麼將其轉換成最接近的內建型別並執行這個操作。對於 @ref{22b9,,Integral} 的子型別，這意味著 @ref{228f,,__add__()} 和 @ref{2290,,__radd__()} 必須用如下方式定義：

@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

@ref{24ac,,Complex} 的子類別有 5 種不同的混合型別操作。我將上面提到所有不涉及 @code{MyIntegral} 和 @code{OtherTypeIKnowAbout} 的程式碼稱作「模板 (boilerplate)」。@code{a} 是 @ref{24ac,,Complex} 之子型別 @code{A} 的實例 (@code{a : A <: Complex})，同時 @code{b : B <: Complex}。我將要計算 @code{a + b}：


@enumerate 

@item 
如果 @code{A} 有定義成一個接受 @code{b} 的 @ref{228f,,__add__()}，不會發生問題。

@item 
如果 @code{A} 回退成模板程式碼，它將回傳一個來自 @ref{228f,,__add__()} 的值，並喪失讓 @code{B} 定義一個更完善的 @ref{2290,,__radd__()} 的機會，因此模板需要回傳一個來自 @code{__add__()} 的 @ref{1a2,,NotImplemented}。（或者 @code{A} 可能完全不實作 @code{__add__()}。）

@item 
接著看 @code{B} 的 @ref{2290,,__radd__()}。如果它接受 @code{a} ，不會發生問題。

@item 
如果沒有成功回退到模板，就沒有更多的方法可以去嘗試，因此這裡將使用預設的實作。

@item 
如果 @code{B <: A}，Python 會在 @code{A.__add__} 之前嘗試 @code{B.__radd__}。這是可行的，因為它是透過對 @code{A} 的理解而實作的，所以這可以在交給 @ref{24ac,,Complex} 之前處理好這些實例。
@end enumerate

如果 @code{A <: Complex} 和 @code{B <: Real} 且沒有共享任何其他型別上的理解，那麼適當的共享操作會涉及內建的 @ref{197,,complex}，並且分別用到 @ref{2290,,__radd__()}，因此 @code{a+b == b+a}。

由於大部分對任意給定類型的操作都十分相似的，定義一個為任意給定運算子生成向前 (forward) 與向後 (reverse) 實例的輔助函式可能會非常有用。例如，@ref{213,,fractions.Fraction} 使用了：

@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):
            # 包含整數。
            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 --- 數學函式,cmath --- 複數的數學函式,numbers --- 數值的抽象基底類別,數值與數學模組
@anchor{library/math doc}@anchor{2920}@anchor{library/math math-mathematical-functions}@anchor{2921}@anchor{library/math module-math}@anchor{92}@anchor{library/math translation-repo}@anchor{2922}
@subsection @code{math} --- 數學函式


@geindex module; math

@c from math import fsum


__________________________________________________________________


此模組提供對常見數學函式與常數的存取，包括於 C 標準中定義的那些。

這些函式不支援複數；若你需要計算複數，請使用 @ref{19,,cmath} 模組的同名函式。這是因為大多數的使用者並不想學習那麼多理解複數所需的數學概念，所以根據支援複數與否分為兩種函式。收到一個例外而非複數回傳值，有助於程式設計師提早察覺參數中包含非預期的複數，進而從源頭查出導致此情況的原因。

此模組提供下列函式。除非特意註明，否則回傳值皆為浮點數。


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

`數論函式'

@tab

@item

@ref{8d7,,comb(n@comma{} k)}

@tab

從 `n' 個物品中不重複且不考慮排序地取出 `k' 個物品的方法數。

@item

@ref{b38,,factorial(n)}

@tab

`n' factorial

@item

@ref{b03,,gcd(*integers)}

@tab

Greatest common divisor of the integer arguments

@item

@ref{bef,,isqrt(n)}

@tab

Integer square root of a nonnegative integer `n'

@item

@ref{b04,,lcm(*integers)}

@tab

Least common multiple of the integer arguments

@item

@ref{8d8,,perm(n@comma{} k)}

@tab

從 `n' 個物品中不重複但考慮排序地取出 `k' 個物品的方法數。

@item

`Floating point arithmetic'

@tab

@item

@ref{15b6,,ceil(x)}

@tab

Ceiling of `x', the smallest integer greater than or equal to `x'

@item

@ref{2923,,fabs(x)}

@tab

`x' 的絕對值。

@item

@ref{15b5,,floor(x)}

@tab

Floor of `x', the largest integer less than or equal to `x'

@item

@ref{50f,,fma(x@comma{} y@comma{} z)}

@tab

Fused multiply-add operation: @code{(x * y) + z}

@item

@ref{2370,,fmod(x@comma{} y)}

@tab

Remainder of division @code{x / y}

@item

@ref{2924,,modf(x)}

@tab

Fractional and integer parts of `x'

@item

@ref{d42,,remainder(x@comma{} y)}

@tab

Remainder of `x' with respect to `y'

@item

@ref{15b7,,trunc(x)}

@tab

Integer part of `x'

@item

`浮點數操作函式'

@tab

@item

@ref{15ca,,copysign(x@comma{} y)}

@tab

Magnitude (absolute value) of `x' with the sign of `y'

@item

@ref{2925,,frexp(x)}

@tab

Mantissa and exponent of `x'

@item

@ref{fab,,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{13ec,,isfinite(x)}

@tab

Check if `x' is neither an infinity nor a NaN

@item

@ref{15c8,,isinf(x)}

@tab

Check if `x' is a positive or negative infinity

@item

@ref{15c9,,isnan(x)}

@tab

Check if `x' is a NaN  (not a number)

@item

@ref{17bd,,ldexp(x@comma{} i)}

@tab

@code{x * (2**i)}, inverse of function @ref{2925,,frexp()}

@item

@ref{6b9,,nextafter(x@comma{} y@comma{} steps)}

@tab

Floating-point value `steps' steps after `x' towards `y'

@item

@ref{b05,,ulp(x)}

@tab

Value of the least significant bit of `x'

@item

`Power, exponential and logarithmic functions'

@tab

@item

@ref{86a,,cbrt(x)}

@tab

Cube root of `x'

@item

@ref{1514,,exp(x)}

@tab

`e' raised to the power `x'

@item

@ref{869,,exp2(x)}

@tab

`2' raised to the power `x'

@item

@ref{13ed,,expm1(x)}

@tab

`e' raised to the power `x', minus 1

@item

@ref{16b4,,log(x@comma{} base)}

@tab

Logarithm of `x' to the given base (`e' by default)

@item

@ref{15cf,,log1p(x)}

@tab

Natural logarithm of `1+x' (base `e')

@item

@ref{12dc,,log2(x)}

@tab

Base-2 logarithm of `x'

@item

@ref{18af,,log10(x)}

@tab

Base-10 logarithm of `x'

@item

@ref{86b,,pow(x@comma{} y)}

@tab

`x' raised to the power `y'

@item

@ref{bf0,,sqrt(x)}

@tab

`x' 的平方根

@item

`Summation and product functions'

@tab

@item

@ref{bec,,dist(p@comma{} q)}

@tab

Euclidean distance between two points `p' and `q' given as an iterable of coordinates

@item

@ref{15cb,,fsum(iterable)}

@tab

Sum of values in the input `iterable'

@item

@ref{bed,,hypot(*coordinates)}

@tab

Euclidean norm of an iterable of coordinates

@item

@ref{bee,,prod(iterable@comma{} start)}

@tab

Product of elements in the input `iterable' with a `start' value

@item

@ref{6b8,,sumprod(p@comma{} q)}

@tab

Sum of products from two iterables `p' and `q'

@item

`Angular conversion'

@tab

@item

@ref{2926,,degrees(x)}

@tab

Convert angle `x' from radians to degrees

@item

@ref{2927,,radians(x)}

@tab

Convert angle `x' from degrees to radians

@item

`Trigonometric functions'

@tab

@item

@ref{2928,,acos(x)}

@tab

Arc cosine of `x'

@item

@ref{2929,,asin(x)}

@tab

Arc sine of `x'

@item

@ref{292a,,atan(x)}

@tab

Arc tangent of `x'

@item

@ref{292b,,atan2(y@comma{} x)}

@tab

@code{atan(y / x)}

@item

@ref{16b3,,cos(x)}

@tab

Cosine of `x'

@item

@ref{16b2,,sin(x)}

@tab

Sine of `x'

@item

@ref{292c,,tan(x)}

@tab

Tangent of `x'

@item

`Hyperbolic functions'

@tab

@item

@ref{15cc,,acosh(x)}

@tab

Inverse hyperbolic cosine of `x'

@item

@ref{15cd,,asinh(x)}

@tab

Inverse hyperbolic sine of `x'

@item

@ref{15ce,,atanh(x)}

@tab

Inverse hyperbolic tangent of `x'

@item

@ref{292d,,cosh(x)}

@tab

Hyperbolic cosine of `x'

@item

@ref{292e,,sinh(x)}

@tab

Hyperbolic sine of `x'

@item

@ref{292f,,tanh(x)}

@tab

Hyperbolic tangent of `x'

@item

`Special functions'

@tab

@item

@ref{dce,,erf(x)}

@tab

Error function@footnote{https://en.wikipedia.org/wiki/Error_function} at `x'

@item

@ref{dcf,,erfc(x)}

@tab

Complementary error function@footnote{https://en.wikipedia.org/wiki/Error_function} at `x'

@item

@ref{13ee,,gamma(x)}

@tab

Gamma function@footnote{https://en.wikipedia.org/wiki/Gamma_function} at `x'

@item

@ref{13ef,,lgamma(x)}

@tab

Natural logarithm of the absolute value of the Gamma function@footnote{https://en.wikipedia.org/wiki/Gamma_function} at `x'

@item

`常數'

@tab

@item

@ref{2930,,pi}

@tab

`π' = 3.141592...

@item

@ref{2931,,e}

@tab

`e' = 2.718281...

@item

@ref{2932,,tau}

@tab

`τ' = 2`π' = 6.283185...

@item

@ref{e7b,,inf}

@tab

正無限大

@item

@ref{86c,,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:: 
* 特殊函式:: 
* 常數: 常數<2>. 

@end menu

@node 數論函式,Floating point arithmetic,,math --- 數學函式
@anchor{library/math number-theoretic-functions}@anchor{2933}
@subsubsection 數論函式


@geindex comb() (於 math 模組中)
@anchor{library/math math comb}@anchor{8d7}
@deffn {函式} math.comb (n, k)

回傳從 `n' 個物品中不重複且不考慮排序地取出 `k' 個物品的方法數。

當 @code{k <= n} 時其值為 @code{n! / (k! * (n - k)!)}，否則其值為 @code{0}。

因為此值等同於 @code{(1 + x)ⁿ} 進行多項式展開後第 k 項的係數，所以又稱為二項式係數。

當任一參數非整數型別時會引發 @ref{198,,TypeError}。當任一參數為負數時會引發 @ref{2eb,,ValueError}。


在 3.8 版被加入.

@end deffn

@geindex factorial() (於 math 模組中)
@anchor{library/math math factorial}@anchor{b38}
@deffn {函式} math.factorial (n)

Return factorial of the nonnegative integer `n'.


在 3.10 版的變更: 其值為整數的浮點數（如：@code{5.0}）已不再被接受。

@end deffn

@geindex gcd() (於 math 模組中)
@anchor{library/math math gcd}@anchor{b03}
@deffn {函式} math.gcd (*integers)

回傳指定整數引數的最大公因數。若存在任一非零引數，回傳值為所有引數共有因數中最大的正整數。若所有引數皆為零，則回傳值為 @code{0}。@code{gcd()} 若未傳入任何引數也將回傳 @code{0}。


在 3.5 版被加入.



在 3.9 版的變更: 新增支援任意數量的引數。先前僅支援兩個引數。

@end deffn

@geindex isqrt() (於 math 模組中)
@anchor{library/math math isqrt}@anchor{bef}
@deffn {函式} math.isqrt (n)

回傳非負整數 `n' 的整數平方根。此值為 `n' 精確平方根經下取整的值，亦等同於滿足 `a'² ≤ `n' 的最大整數值 `a'。

於有些應用程式中，取得滿足 `n' ≤ `a'² 的最小整數值 `a' ── 或者說 `n' 精確平方根經上取整的值 ── 會更加方便。對正數 `n'，此值可使用 @code{a = 1 + isqrt(n - 1)} 計算。


在 3.8 版被加入.

@end deffn

@geindex lcm() (於 math 模組中)
@anchor{library/math math lcm}@anchor{b04}
@deffn {函式} math.lcm (*integers)

回傳指定整數引數的最小公倍數。若所有引數值皆非零，回傳值為所有引數共有倍數中最小的正整數。若存在任一引數值為零，則回傳值為 @code{0}。@code{lcm()} 若未傳入任何引數將回傳 @code{1}。


在 3.9 版被加入.

@end deffn

@geindex perm() (於 math 模組中)
@anchor{library/math math perm}@anchor{8d8}
@deffn {函式} math.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!}.

當任一參數非整數型別時會引發 @ref{198,,TypeError}。當任一參數為負數時會引發 @ref{2eb,,ValueError}。


在 3.8 版被加入.

@end deffn

@node Floating point arithmetic,Floating point manipulation functions,數論函式,math --- 數學函式
@anchor{library/math floating-point-arithmetic}@anchor{2934}
@subsubsection Floating point arithmetic


@geindex ceil() (於 math 模組中)
@anchor{library/math math ceil}@anchor{15b6}
@deffn {函式} math.ceil (x)

回傳 `x' 經上取整的值，即大於或等於 `x' 的最小整數。若 `x' 並非浮點數，此函式將委派給 @ref{22b8,,x.__ceil__}，並回傳 @ref{22b9,,Integral} 型別的值。
@end deffn

@geindex fabs() (於 math 模組中)
@anchor{library/math math fabs}@anchor{2923}
@deffn {函式} math.fabs (x)

回傳 `x' 的絕對值。
@end deffn

@geindex floor() (於 math 模組中)
@anchor{library/math math floor}@anchor{15b5}
@deffn {函式} math.floor (x)

回傳 `x' 經下取整的值，即小於或等於 `x' 的最大整數。若 `x' 並非浮點數，此函式將委派給 @ref{22b7,,x.__floor__}，並回傳 @ref{22b9,,Integral} 型別的值。
@end deffn

@geindex fma() (於 math 模組中)
@anchor{library/math math fma}@anchor{50f}
@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.


在 3.13 版被加入.

@end deffn

@geindex fmod() (於 math 模組中)
@anchor{library/math math fmod}@anchor{2370}
@deffn {函式} math.fmod (x, y)

回傳 @code{x / y} 的浮點數餘數，其以平臺上的 C 函式庫 @code{fmod(x, y)} 函式定義。請注意此函式與 Python 運算式 @code{x % y} 可能不會回傳相同結果。C 標準要求 @code{fmod(x, y)} 的回傳值完全等同（數學定義上，即無限精度）於 @code{x - n*y}，`n' 為可使回傳值與 `x' 同號且長度小於 @code{abs(y)} 的整數。Python 運算式 @code{x % y} 的回傳值則與 `y' 同號，且可能無法精確地計算浮點數引數。例如：@code{fmod(-1e-100, 1e100)} 的值為 @code{-1e-100}，但 Python 運算式 @code{-1e-100 % 1e100} 的結果為 @code{1e100-1e-100}，此值無法準確地表示成浮點數，並會四捨五入為出乎意料的 @code{1e100}。因此，處理浮點數時通常會選擇函式 @ref{2370,,fmod()}，而處理整數時會選擇 Python 運算式 @code{x % y}。
@end deffn

@geindex modf() (於 math 模組中)
@anchor{library/math math modf}@anchor{2924}
@deffn {函式} math.modf (x)

Return the fractional and integer parts of `x'.  Both results carry the sign
of `x' and are floats.

Note that @ref{2924,,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{d42}
@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{2eb,,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.


在 3.7 版被加入.

@end deffn

@geindex trunc() (於 math 模組中)
@anchor{library/math math trunc}@anchor{15b7}
@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{15b5,,floor()} for positive `x', and equivalent to @ref{15b6,,ceil()}
for negative `x'. If `x' is not a float, delegates to @ref{19c,,x.__trunc__}, which should return an @ref{22b9,,Integral} value.
@end deffn

For the @ref{15b6,,ceil()}, @ref{15b5,,floor()}, and @ref{2924,,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 --- 數學函式
@anchor{library/math floating-point-manipulation-functions}@anchor{2935}
@subsubsection Floating point manipulation functions


@geindex copysign() (於 math 模組中)
@anchor{library/math math copysign}@anchor{15ca}
@deffn {函式} math.copysign (x, y)

回傳與 `x' 相同長度（絕對值）且與 `y' 同號的浮點數。在支援帶符號零的平臺上，@code{copysign(1.0, -0.0)} 回傳 `-1.0'。
@end deffn

@geindex frexp() (於 math 模組中)
@anchor{library/math math frexp}@anchor{2925}
@deffn {函式} math.frexp (x)

以 @code{(m, e)} 對的格式回傳 `x' 的尾數 `m' 及指數 `e'。`m' 是浮點數而 `e' 是整數，且兩者精確地使 @code{x == m * 2**e}。若 `x' 為零，回傳 @code{(0.0, 0)}，否則令 @code{0.5 <= abs(m) < 1}。此函式用於以可攜的方式「分割」浮點數內部表示法。

Note that @ref{2925,,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{fab}
@deffn {函式} math.isclose (a, b, *, rel_tol=1e-09, abs_tol=0.0)

若 `a' 及 `b' 兩值足夠接近便回傳 @code{True}，否則回傳 @code{False}。

兩數是否足夠接近取決於給定的絕對及相對容許偏差 (tolerance)。如果沒有錯誤發生，結果將為：@code{abs(a-b) <= max(rel_tol * max(abs(a), abs(b)), abs_tol)}。

`rel_tol' 為相對容許偏差 ── `a' 與 `b' 兩數差的最大容許值，與 `a' 及 `b' 兩數的絕對值中較大者相關。例如欲設置 5% 的容許偏差，則傳入 @code{rel_tol=0.05}。其預設值為 @code{1e-09}，該值可確保兩數於大約 9 個十進數位內相同。`rel_tol' 須不為負且小於 @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.

定義於 IEEE 754 浮點標準中的特殊值 @code{NaN}、@code{inf} 和 @code{-inf} 會根據該標準處理。更明確地說，@code{NaN} 不會與包含自身在內的任何數字足夠接近，而 @code{inf} 及 @code{-inf} 皆只與自身接近。


在 3.5 版被加入.



@subsubheading 也參考


@geindex Python Enhancement Proposals; PEP 485
PEP 485@footnote{https://peps.python.org/pep-0485/} ── 用於測試近似相等的函式

@end deffn

@geindex isfinite() (於 math 模組中)
@anchor{library/math math isfinite}@anchor{13ec}
@deffn {函式} math.isfinite (x)

若 `x' 不是無限值或 @code{NaN} 便回傳 @code{True}，否則回傳 @code{False}。（注意 @code{0.0} 被視為有限數。）


在 3.2 版被加入.

@end deffn

@geindex isinf() (於 math 模組中)
@anchor{library/math math isinf}@anchor{15c8}
@deffn {函式} math.isinf (x)

若 `x' 是正無限值或負無限值便回傳 @code{True}，否則回傳 @code{False}。
@end deffn

@geindex isnan() (於 math 模組中)
@anchor{library/math math isnan}@anchor{15c9}
@deffn {函式} math.isnan (x)

若 `x' 是 @code{NaN} ── 即非數字（NaN, not a number）── 便回傳 @code{True}，否則回傳 @code{False}。
@end deffn

@geindex ldexp() (於 math 模組中)
@anchor{library/math math ldexp}@anchor{17bd}
@deffn {函式} math.ldexp (x, i)

回傳 @code{x * (2**i)}。此函式本質上為 @ref{2925,,frexp()} 的反函式。
@end deffn

@geindex nextafter() (於 math 模組中)
@anchor{library/math math nextafter}@anchor{6b9}
@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.

範例：


@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

另請參閱 @ref{b05,,math.ulp()}。


在 3.9 版被加入.



在 3.12 版的變更: 新增 `steps' 引數。

@end deffn

@geindex ulp() (於 math 模組中)
@anchor{library/math math ulp}@anchor{b05}
@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 
若 `x' 為負值，回傳 @code{ulp(-x)}。

@item 
若 `x' 為正無限值，回傳 `x'。

@item 
If `x' is equal to zero, return the smallest positive
`denormalized' representable float (smaller than the minimum positive
`normalized' float, @ref{1c98,,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{6b9,,math.nextafter()} and @ref{1c98,,sys.float_info.epsilon}.


在 3.9 版被加入.

@end deffn

@node Power exponential and logarithmic functions,Summation and product functions,Floating point manipulation functions,math --- 數學函式
@anchor{library/math power-exponential-and-logarithmic-functions}@anchor{2936}
@subsubsection Power, exponential and logarithmic functions


@geindex cbrt() (於 math 模組中)
@anchor{library/math math cbrt}@anchor{86a}
@deffn {函式} math.cbrt (x)

Return the cube root of `x'.


在 3.11 版被加入.

@end deffn

@geindex exp() (於 math 模組中)
@anchor{library/math math exp}@anchor{1514}
@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{869}
@deffn {函式} math.exp2 (x)

Return `2' raised to the power `x'.


在 3.11 版被加入.

@end deffn

@geindex expm1() (於 math 模組中)
@anchor{library/math math expm1}@anchor{13ed}
@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 @ref{13ed,,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


在 3.2 版被加入.

@end deffn

@geindex log() (於 math 模組中)
@anchor{library/math math log}@anchor{16b4}
@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{15cf}
@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{12dc}
@deffn {函式} math.log2 (x)

Return the base-2 logarithm of `x'. This is usually more accurate than
@code{log(x, 2)}.


在 3.3 版被加入.



@subsubheading 也參考


@ref{24a6,,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{18af}
@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{86b}
@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{2eb,,ValueError}.

Unlike the built-in @code{**} operator, @ref{86b,,math.pow()} converts both
its arguments to type @ref{196,,float}.  Use @code{**} or the built-in
@ref{1a4,,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{2eb,,ValueError},
for consistency with IEEE 754.

@end deffn

@geindex sqrt() (於 math 模組中)
@anchor{library/math math sqrt}@anchor{bf0}
@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 --- 數學函式
@anchor{library/math summation-and-product-functions}@anchor{2937}
@subsubsection Summation and product functions


@geindex dist() (於 math 模組中)
@anchor{library/math math dist}@anchor{bec}
@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)))
@end example


在 3.8 版被加入.

@end deffn

@geindex fsum() (於 math 模組中)
@anchor{library/math math fsum}@anchor{15cb}
@deffn {函式} math.fsum (iterable)

回傳可疊代物件（iterable）中所有值的精確浮點數和。透過追蹤過程中多個部分和（partial sum）以避免精確度損失。

此演算法準確性奠基於保證 IEEE-754 浮點標準及典型奇進偶捨（half-even）模式。於有些非 Windows 平台建置時，底層 C 函式庫使用延伸精度加法運算，而可能導致對過程中同一部分和重複捨入，並使其最低有效位不如預期。

更深入的討論及兩種替代做法請參閱 ASPN cookbook recipes 精準的浮點數總和@footnote{https://code.activestate.com/recipes/393090/}。
@end deffn

@geindex hypot() (於 math 模組中)
@anchor{library/math math hypot}@anchor{bed}
@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{bee}
@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.


在 3.8 版被加入.

@end deffn

@geindex sumprod() (於 math 模組中)
@anchor{library/math math sumprod}@anchor{6b8}
@deffn {函式} math.sumprod (p, q)

Return the sum of products of values from two iterables `p' and `q'.

Raises @ref{2eb,,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.


在 3.12 版被加入.

@end deffn

@node Angular conversion,Trigonometric functions,Summation and product functions,math --- 數學函式
@anchor{library/math angular-conversion}@anchor{2938}
@subsubsection Angular conversion


@geindex degrees() (於 math 模組中)
@anchor{library/math math degrees}@anchor{2926}
@deffn {函式} math.degrees (x)

Convert angle `x' from radians to degrees.
@end deffn

@geindex radians() (於 math 模組中)
@anchor{library/math math radians}@anchor{2927}
@deffn {函式} math.radians (x)

Convert angle `x' from degrees to radians.
@end deffn

@node Trigonometric functions,Hyperbolic functions,Angular conversion,math --- 數學函式
@anchor{library/math trigonometric-functions}@anchor{2939}
@subsubsection Trigonometric functions


@geindex acos() (於 math 模組中)
@anchor{library/math math acos}@anchor{2928}
@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{2929}
@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{292a}
@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{292b}
@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 @ref{292b,,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{16b3}
@deffn {函式} math.cos (x)

Return the cosine of `x' radians.
@end deffn

@geindex sin() (於 math 模組中)
@anchor{library/math math sin}@anchor{16b2}
@deffn {函式} math.sin (x)

Return the sine of `x' radians.
@end deffn

@geindex tan() (於 math 模組中)
@anchor{library/math math tan}@anchor{292c}
@deffn {函式} math.tan (x)

Return the tangent of `x' radians.
@end deffn

@node Hyperbolic functions,特殊函式,Trigonometric functions,math --- 數學函式
@anchor{library/math hyperbolic-functions}@anchor{293a}
@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{15cc}
@deffn {函式} math.acosh (x)

Return the inverse hyperbolic cosine of `x'.
@end deffn

@geindex asinh() (於 math 模組中)
@anchor{library/math math asinh}@anchor{15cd}
@deffn {函式} math.asinh (x)

Return the inverse hyperbolic sine of `x'.
@end deffn

@geindex atanh() (於 math 模組中)
@anchor{library/math math atanh}@anchor{15ce}
@deffn {函式} math.atanh (x)

Return the inverse hyperbolic tangent of `x'.
@end deffn

@geindex cosh() (於 math 模組中)
@anchor{library/math math cosh}@anchor{292d}
@deffn {函式} math.cosh (x)

Return the hyperbolic cosine of `x'.
@end deffn

@geindex sinh() (於 math 模組中)
@anchor{library/math math sinh}@anchor{292e}
@deffn {函式} math.sinh (x)

Return the hyperbolic sine of `x'.
@end deffn

@geindex tanh() (於 math 模組中)
@anchor{library/math math tanh}@anchor{292f}
@deffn {函式} math.tanh (x)

Return the hyperbolic tangent of `x'.
@end deffn

@node 特殊函式,常數<2>,Hyperbolic functions,math --- 數學函式
@anchor{library/math special-functions}@anchor{293b}
@subsubsection 特殊函式


@geindex erf() (於 math 模組中)
@anchor{library/math math erf}@anchor{dce}
@deffn {函式} math.erf (x)

Return the error function@footnote{https://en.wikipedia.org/wiki/Error_function} at
`x'.

The @ref{dce,,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


在 3.2 版被加入.

@end deffn

@geindex erfc() (於 math 模組中)
@anchor{library/math math erfc}@anchor{dcf}
@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}.


在 3.2 版被加入.

@end deffn

@geindex gamma() (於 math 模組中)
@anchor{library/math math gamma}@anchor{13ee}
@deffn {函式} math.gamma (x)

Return the Gamma function@footnote{https://en.wikipedia.org/wiki/Gamma_function} at
`x'.


在 3.2 版被加入.

@end deffn

@geindex lgamma() (於 math 模組中)
@anchor{library/math math lgamma}@anchor{13ef}
@deffn {函式} math.lgamma (x)

Return the natural logarithm of the absolute value of the Gamma
function at `x'.


在 3.2 版被加入.

@end deffn

@node 常數<2>,,特殊函式,math --- 數學函式
@anchor{library/math constants}@anchor{293c}
@subsubsection 常數


@geindex pi (於 math 模組中)
@anchor{library/math math pi}@anchor{2930}
@deffn {資料} math.pi

The mathematical constant `π' = 3.141592..., to available precision.
@end deffn

@geindex e (於 math 模組中)
@anchor{library/math math e}@anchor{2931}
@deffn {資料} math.e

The mathematical constant `e' = 2.718281..., to available precision.
@end deffn

@geindex tau (於 math 模組中)
@anchor{library/math math tau}@anchor{2932}
@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!


在 3.6 版被加入.

@end deffn

@geindex inf (於 math 模組中)
@anchor{library/math math inf}@anchor{e7b}
@deffn {資料} math.inf

A floating-point positive infinity.  (For negative infinity, use
@code{-math.inf}.)  Equivalent to the output of @code{float('inf')}.


在 3.5 版被加入.

@end deffn

@geindex nan (於 math 模組中)
@anchor{library/math math nan}@anchor{86c}
@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{15c9,,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


在 3.5 版被加入.



在 3.11 版的變更: It is now always available.

@end deffn

`CPython 實作細節：' The @ref{92,,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{2eb,,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{a78,,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 @ref{19,,cmath} 模組

Complex number versions of many of these 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 cmath --- 複數的數學函式,decimal --- 十進位固定點和浮點運算,math --- 數學函式,數值與數學模組
@anchor{library/cmath doc}@anchor{293d}@anchor{library/cmath cmath-mathematical-functions-for-complex-numbers}@anchor{293e}@anchor{library/cmath module-cmath}@anchor{19}@anchor{library/cmath translation-repo}@anchor{293f}
@subsection @code{cmath} --- 複數的數學函式


@geindex module; cmath


__________________________________________________________________


本模組提供一些適用於複數的數學函式。本模組中的函式接受整數、浮點數或複數作為引數。它們也接受任何具有 @ref{7f8,,__complex__()} 或 @ref{bb8,,__float__()} 方法的 Python 物件：這些方法分別用於將物件轉換為複數或浮點數，然後再將函式應用於轉換後的結果。

@cartouche
@quotation 備註 
對於涉及分枝切割 (branch cut) 的函式，我們面臨的問題是決定如何定義在切割本身上的這些函式。遵循 Kahan 的論文 "Branch cuts for complex elementary functions"，以及 C99 的附錄 G 和後來的 C 標準，我們使用零符號來區分分枝切割的兩側：對於沿著（一部分）實數軸的分枝切割，我們查看虛部的符號，而對於沿虛軸的分枝切割，我們則查看實部的符號。

例如 @ref{2940,,cmath.sqrt()} 函式具有一條沿負實軸的分枝切割。 引數 @code{-2-0j} 被視為位於分枝切割 `下方' 處理，因此給出的結果在負虛軸上：

@example
>>> cmath.sqrt(-2-0j)
-1.4142135623730951j
@end example

但是引數 @code{-2+0j} 會被當成位於分枝切割上方處理：

@example
>>> cmath.sqrt(-2+0j)
1.4142135623730951j
@end example
@end quotation
@end cartouche


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

`轉換到極座標和從極座標做轉換'

@tab

@item

@ref{2941,,phase(z)}

@tab

回傳 `z' 的相位角。

@item

@ref{2942,,polar(z)}

@tab

回傳 `z' 在極座標中的表達方式。

@item

@ref{2943,,rect(r@comma{} phi)}

@tab

透過極座標 `r' 和 `phi' 回傳複數 `z'。

@item

`冪函數和對數函數'

@tab

@item

@ref{2944,,exp(z)}

@tab

回傳 `e' 的 `z' 次方。

@item

@ref{2945,,log(z[@comma{} base])}

@tab

回傳 `z' 以給定 `base' 為底（預設為 `e'）的對數。

@item

@ref{2946,,log10(z)}

@tab

回傳 `z' 以 10 為底的對數。

@item

@ref{2940,,sqrt(z)}

@tab

回傳 `z' 的平方根。

@item

`三角函數'

@tab

@item

@ref{2947,,acos(z)}

@tab

回傳 `z' 的反餘弦值。

@item

@ref{2948,,asin(z)}

@tab

回傳 `z' 的反正弦值。

@item

@ref{2949,,atan(z)}

@tab

回傳 `z' 的反正切值。

@item

@ref{294a,,cos(z)}

@tab

回傳 `z' 的餘弦值。

@item

@ref{294b,,sin(z)}

@tab

回傳 `z' 的正弦值。

@item

@ref{294c,,tan(z)}

@tab

回傳 `z' 的正切值。

@item

`雙曲函數'

@tab

@item

@ref{294d,,acosh(z)}

@tab

回傳 `z' 的反雙曲餘弦值。

@item

@ref{294e,,asinh(z)}

@tab

回傳 `z' 的反雙曲正弦值。

@item

@ref{294f,,atanh(z)}

@tab

回傳 `z' 的反雙曲正切值。

@item

@ref{2950,,cosh(z)}

@tab

回傳 `z' 的雙曲餘弦值。

@item

@ref{2951,,sinh(z)}

@tab

回傳 `z' 的雙曲正弦值。

@item

@ref{2952,,tanh(z)}

@tab

回傳 `z' 的雙曲正切值。

@item

`分類函數'

@tab

@item

@ref{2953,,isfinite(z)}

@tab

Check if all components of `z' are finite

@item

@ref{2954,,isinf(z)}

@tab

Check if any component of `z' is infinite

@item

@ref{2955,,isnan(z)}

@tab

Check if any component of `z' is a NaN

@item

@ref{fac,,isclose(a@comma{} b@comma{} *@comma{} rel_tol@comma{} abs_tol)}

@tab

檢查 `a' 和 `b' 的值是否接近

@item

`常數'

@tab

@item

@ref{2956,,pi}

@tab

`π' = 3.141592...

@item

@ref{2957,,e}

@tab

`e' = 2.718281...

@item

@ref{e78,,tau}

@tab

`τ' = 2`π' = 6.283185...

@item

@ref{e79,,inf}

@tab

Positive infinity

@item

@ref{e7c,,infj}

@tab

Pure imaginary infinity

@item

@ref{e7a,,nan}

@tab

"Not a number" (NaN)

@item

@ref{e7d,,nanj}

@tab

Pure imaginary NaN

@end multitable


@menu
* 轉換到極座標和從極座標做轉換:: 
* 冪函數和對數函數:: 
* 三角函數:: 
* 雙曲函數:: 
* 分類函式:: 
* 常數: 常數<3>. 

@end menu

@node 轉換到極座標和從極座標做轉換,冪函數和對數函數,,cmath --- 複數的數學函式
@anchor{library/cmath conversions-to-and-from-polar-coordinates}@anchor{2958}
@subsubsection 轉換到極座標和從極座標做轉換


Python 複數 @code{z} 是用 `直角坐標' 或 `笛卡爾坐標' 儲存在內部的。它完全是由其 `實部' @code{z.real} 和 `虛部' @code{z.imag} 所決定。

`極座標' 提供了另一種表示複數的方法。在極座標中，複數 `z' 由絕對值 (modulus) `r' 和相位角 (phase) `phi' 定義。絕對值 `r' 是從 `z' 到原點的距離，而相位角 `phi' 是從正 x 軸到連接原點到 `z' 的線段的逆時針角度（以弧度為單位）。

以下的函式可用於原始直角座標與極座標之間的相互轉換。

@geindex phase() (於 cmath 模組中)
@anchor{library/cmath cmath phase}@anchor{2941}
@deffn {函式} cmath.phase (z)

以浮點數的形式回傳 `z' 的相位角（也稱為 `z' 的 `引數' ）。@code{phase(z)} 等價於 @code{math.atan2(z.imag, z.real)}。結果將位於 [-`π', `π'] 的範圍內，且此操作的分枝切割將位於負實軸上。結果的符號會與 @code{z.imag} 的符號相同，即使 @code{z.imag} 為零：

@example
>>> phase(-1+0j)
3.141592653589793
>>> phase(-1-0j)
-3.141592653589793
@end example
@end deffn

@cartouche
@quotation 備註 
複數 `z' 的絕對值可以使用內建的 @ref{1f54,,abs()} 函式計算。沒有單獨的 @ref{19,,cmath} 模組函式適用於此操作。
@end quotation
@end cartouche

@geindex polar() (於 cmath 模組中)
@anchor{library/cmath cmath polar}@anchor{2942}
@deffn {函式} cmath.polar (z)

回傳 `z' 在極座標中的表達方式。回傳一組數對 @code{(r, phi)}， `r' 是 `z' 的絕對值， `phi' 是 `z' 的相位角。 @code{polar(z)} 相當於 @code{(abs(z), phase(z))}。
@end deffn

@geindex rect() (於 cmath 模組中)
@anchor{library/cmath cmath rect}@anchor{2943}
@deffn {函式} cmath.rect (r, phi)

透過極座標 `r' 和 `phi' 回傳複數 `z'。相當於 @code{complex(r * math.cos(phi), r * math.sin(phi))}。
@end deffn

@node 冪函數和對數函數,三角函數,轉換到極座標和從極座標做轉換,cmath --- 複數的數學函式
@anchor{library/cmath power-and-logarithmic-functions}@anchor{2959}
@subsubsection 冪函數和對數函數


@geindex exp() (於 cmath 模組中)
@anchor{library/cmath cmath exp}@anchor{2944}
@deffn {函式} cmath.exp (z)

回傳 `e' 的 `z' 次方，其中 `e' 是自然對數的底數。
@end deffn

@geindex log() (於 cmath 模組中)
@anchor{library/cmath cmath log}@anchor{2945}
@deffn {函式} cmath.log (z[, base])

回傳 `z' 給定 `base' 的對數。如果未指定 `base'，則傳回 `z' 的自然對數。存在一條分枝切割，從 0 沿負實數軸到 -∞。
@end deffn

@geindex log10() (於 cmath 模組中)
@anchor{library/cmath cmath log10}@anchor{2946}
@deffn {函式} cmath.log10 (z)

回傳 `z' 以 10 為底的對數。它與 @ref{2945,,log()} 具有相同的分枝切割。
@end deffn

@geindex sqrt() (於 cmath 模組中)
@anchor{library/cmath cmath sqrt}@anchor{2940}
@deffn {函式} cmath.sqrt (z)

回傳 `z' 的平方根。它與 @ref{2945,,log()} 具有相同的分枝切割。
@end deffn

@node 三角函數,雙曲函數,冪函數和對數函數,cmath --- 複數的數學函式
@anchor{library/cmath trigonometric-functions}@anchor{295a}
@subsubsection 三角函數


@geindex acos() (於 cmath 模組中)
@anchor{library/cmath cmath acos}@anchor{2947}
@deffn {函式} cmath.acos (z)

回傳 `z' 的反餘弦值。存在兩條分枝切割：一條是從 1 沿著實數軸向右延伸到 ∞。另一條從 -1 沿實數軸向左延伸到 -∞。
@end deffn

@geindex asin() (於 cmath 模組中)
@anchor{library/cmath cmath asin}@anchor{2948}
@deffn {函式} cmath.asin (z)

回傳 `z' 的反正弦值。它與 @ref{2947,,acos()} 具有相同的分枝切割。
@end deffn

@geindex atan() (於 cmath 模組中)
@anchor{library/cmath cmath atan}@anchor{2949}
@deffn {函式} cmath.atan (z)

回傳 `z' 的反正切值。有兩條分枝切割：一條是從 @code{1j} 沿著虛軸延伸到 @code{∞j}。另一條從 @code{-1j} 沿著虛軸延伸到 @code{-∞j}。
@end deffn

@geindex cos() (於 cmath 模組中)
@anchor{library/cmath cmath cos}@anchor{294a}
@deffn {函式} cmath.cos (z)

回傳 `z' 的餘弦值。
@end deffn

@geindex sin() (於 cmath 模組中)
@anchor{library/cmath cmath sin}@anchor{294b}
@deffn {函式} cmath.sin (z)

回傳 `z' 的正弦值。
@end deffn

@geindex tan() (於 cmath 模組中)
@anchor{library/cmath cmath tan}@anchor{294c}
@deffn {函式} cmath.tan (z)

回傳 `z' 的正切值。
@end deffn

@node 雙曲函數,分類函式,三角函數,cmath --- 複數的數學函式
@anchor{library/cmath hyperbolic-functions}@anchor{295b}
@subsubsection 雙曲函數


@geindex acosh() (於 cmath 模組中)
@anchor{library/cmath cmath acosh}@anchor{294d}
@deffn {函式} cmath.acosh (z)

回傳 `z' 的反雙曲餘弦值。存在一條分枝切割，從 1 沿實數軸向左延伸到 -∞。
@end deffn

@geindex asinh() (於 cmath 模組中)
@anchor{library/cmath cmath asinh}@anchor{294e}
@deffn {函式} cmath.asinh (z)

回傳 `z' 的反雙曲正弦值。存在兩條分枝切割：一條是從 @code{1j} 沿著虛軸延伸到 @code{∞j}。另一條從 @code{-1j} 沿著虛軸延伸到 @code{-∞j}。
@end deffn

@geindex atanh() (於 cmath 模組中)
@anchor{library/cmath cmath atanh}@anchor{294f}
@deffn {函式} cmath.atanh (z)

回傳 `z' 的反雙曲正切值。存在兩條分枝切割：一條是從 @code{1} 沿著實數軸延伸到 @code{∞}。另一條從 @code{-1} 沿著實數軸延伸到 @code{-∞}。
@end deffn

@geindex cosh() (於 cmath 模組中)
@anchor{library/cmath cmath cosh}@anchor{2950}
@deffn {函式} cmath.cosh (z)

回傳 `z' 的反雙曲餘弦值。
@end deffn

@geindex sinh() (於 cmath 模組中)
@anchor{library/cmath cmath sinh}@anchor{2951}
@deffn {函式} cmath.sinh (z)

回傳 `z' 的反雙曲正弦值。
@end deffn

@geindex tanh() (於 cmath 模組中)
@anchor{library/cmath cmath tanh}@anchor{2952}
@deffn {函式} cmath.tanh (z)

回傳 `z' 的反雙曲正切值。
@end deffn

@node 分類函式,常數<3>,雙曲函數,cmath --- 複數的數學函式
@anchor{library/cmath classification-functions}@anchor{295c}
@subsubsection 分類函式


@geindex isfinite() (於 cmath 模組中)
@anchor{library/cmath cmath isfinite}@anchor{2953}
@deffn {函式} cmath.isfinite (z)

如果 `z' 的實部和虛部都是有限的，則回傳 @code{True}，否則回傳 @code{False}。


在 3.2 版被加入.

@end deffn

@geindex isinf() (於 cmath 模組中)
@anchor{library/cmath cmath isinf}@anchor{2954}
@deffn {函式} cmath.isinf (z)

如果 `z' 的實部或虛部是無窮大，則回傳 @code{True}，否則回傳 @code{False}。
@end deffn

@geindex isnan() (於 cmath 模組中)
@anchor{library/cmath cmath isnan}@anchor{2955}
@deffn {函式} cmath.isnan (z)

如果 `z' 的實部或虛部為 NaN，則回傳 @code{True}，否則回傳 @code{False}。
@end deffn

@geindex isclose() (於 cmath 模組中)
@anchor{library/cmath cmath isclose}@anchor{fac}
@deffn {函式} cmath.isclose (a, b, *, rel_tol=1e-09, abs_tol=0.0)

如果 `a' 和 `b' 的值相互接近，則回傳 @code{True}，否則回傳 @code{False}。

兩數是否足夠接近取決於給定的絕對及相對容許偏差 (tolerance)。如果沒有錯誤發生，結果將為：@code{abs(a-b) <= max(rel_tol * max(abs(a), abs(b)), abs_tol)}。

`rel_tol' 為相對容許偏差 ── `a' 與 `b' 兩數差的最大容許值，與 `a' 及 `b' 兩數的絕對值中較大者相關。例如欲設置 5% 的容許偏差，則傳入 @code{rel_tol=0.05}。其預設值為 @code{1e-09}，該值可確保兩數於大約 9 個十進數位內相同。`rel_tol' 須不為負且小於 @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.

定義於 IEEE 754 浮點標準中的特殊值 @code{NaN}、@code{inf} 和 @code{-inf} 會根據該標準處理。更明確地說，@code{NaN} 不會與包含自身在內的任何數字足夠接近，而 @code{inf} 及 @code{-inf} 皆只與自身接近。


在 3.5 版被加入.



@subsubheading 也參考


@geindex Python Enhancement Proposals; PEP 485
PEP 485@footnote{https://peps.python.org/pep-0485/} ── 用於測試近似相等的函式

@end deffn

@node 常數<3>,,分類函式,cmath --- 複數的數學函式
@anchor{library/cmath constants}@anchor{295d}
@subsubsection 常數


@geindex pi (於 cmath 模組中)
@anchor{library/cmath cmath pi}@anchor{2956}
@deffn {資料} cmath.pi

數學常數 `π'，作為一個浮點數。
@end deffn

@geindex e (於 cmath 模組中)
@anchor{library/cmath cmath e}@anchor{2957}
@deffn {資料} cmath.e

數學常數 `e'，作為一個浮點數。
@end deffn

@geindex tau (於 cmath 模組中)
@anchor{library/cmath cmath tau}@anchor{e78}
@deffn {資料} cmath.tau

數學常數 `τ'，作為一個浮點數。


在 3.6 版被加入.

@end deffn

@geindex inf (於 cmath 模組中)
@anchor{library/cmath cmath inf}@anchor{e79}
@deffn {資料} cmath.inf

正無窮大的浮點數。相當於 @code{float('inf')}。


在 3.6 版被加入.

@end deffn

@geindex infj (於 cmath 模組中)
@anchor{library/cmath cmath infj}@anchor{e7c}
@deffn {資料} cmath.infj

實部為零和虛部為正無窮的複數。相當於 @code{complex(0.0, float('inf'))}。


在 3.6 版被加入.

@end deffn

@geindex nan (於 cmath 模組中)
@anchor{library/cmath cmath nan}@anchor{e7a}
@deffn {資料} cmath.nan

浮點「非數字」 (NaN) 值。相當於 @code{float('nan')}。另請參閱 @ref{86c,,math.nan}。


在 3.6 版被加入.

@end deffn

@geindex nanj (於 cmath 模組中)
@anchor{library/cmath cmath nanj}@anchor{e7d}
@deffn {資料} cmath.nanj

實部為零和虛部為 NaN 的複數。相當於 @code{complex(0.0, float('nan'))}。


在 3.6 版被加入.

@end deffn

@geindex module（模組）;math（數學）

請注意，函式的選擇與模組 @ref{92,,math} 的類似，但並不完全相同。擁有兩個模組的原因是有些用戶對複數不感興趣，甚至根本就不知道它們是什麼。他們寧願讓 @code{math.sqrt(-1)} 引發異常，也不願它回傳複數。另請注意， @ref{19,,cmath} 中所定義的函式始終都會回傳複數，即使答案可以表示為實數（在這種情況下，複數的虛部為零）。

關於分枝切割的註釋：它們是沿著給定的不連續函式的曲線。它們是許多複變函數的必要特徵。假設你需要使用複變函數進行計算，你將會了解分枝切割的概念。請參閱幾乎所有關於複變函數的（不是太初級的）書籍以獲得啟發。對於如何正確地基於數值目的選擇分枝切割的相關訊息，以下內容應該是一個很好的參考：


@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 --- 十進位固定點和浮點運算,fractions --- 有理數,cmath --- 複數的數學函式,數值與數學模組
@anchor{library/decimal doc}@anchor{295e}@anchor{library/decimal decimal-decimal-fixed-point-and-floating-point-arithmetic}@anchor{295f}@anchor{library/decimal module-decimal}@anchor{3a}@anchor{library/decimal translation-repo}@anchor{2960}
@subsection @code{decimal} --- 十進位固定點和浮點運算


@geindex module; decimal

`原始碼：'Lib/decimal.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/decimal.py}

@c import modules for testing inline doctests with the Sphinx doctest builder

@c import decimal
@c import math
@c from decimal import *
@c # make sure each group gets a fresh context
@c setcontext(Context())

@c # make sure other tests (outside this file) get a fresh context
@c setcontext(Context())


__________________________________________________________________


The @ref{3a,,decimal} module provides support for fast correctly rounded
decimal floating-point arithmetic. It offers several advantages over the
@ref{196,,float} datatype:


@itemize *

@item 
Decimal "is based on a floating-point model 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{2961,,ROUND_CEILING}, @ref{2962,,ROUND_DOWN},
@ref{2963,,ROUND_FLOOR}, @ref{2964,,ROUND_HALF_DOWN}, @ref{2965,,ROUND_HALF_EVEN},
@ref{2966,,ROUND_HALF_UP}, @ref{2967,,ROUND_UP}, and @ref{2968,,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{2969,,Clamped}, @ref{12a9,,InvalidOperation},
@ref{296a,,DivisionByZero}, @ref{296b,,Inexact}, @ref{296c,,Rounded}, @ref{296d,,Subnormal},
@ref{296e,,Overflow}, @ref{296f,,Underflow} and @ref{129e,,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:: 
* 常數: 常數<4>. 
* Rounding modes:: 
* Signals:: 
* Floating-point notes:: 
* Working with threads:: 
* Recipes:: 
* Decimal FAQ:: 

@end menu

@node Quick-start tutorial,Decimal objects,,decimal --- 十進位固定點和浮點運算
@anchor{library/decimal decimal-tutorial}@anchor{2970}@anchor{library/decimal quick-start-tutorial}@anchor{2971}
@subsubsection Quick-start tutorial


The usual start to using decimals is importing the module, viewing the current
context with @ref{189d,,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{129e,,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


在 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{12a9,,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

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{12b1,,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{189d,,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
Context() constructor.  To make an alternate active, use the @ref{2972,,setcontext()}
function.

In accordance with the standard, the @ref{3a,,decimal} module provides two ready to
use standard contexts, @ref{12a5,,BasicContext} and @ref{12a6,,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{2973,,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{12af,,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{1fe,,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 --- 十進位固定點和浮點運算
@anchor{library/decimal decimal-decimal}@anchor{2974}@anchor{library/decimal decimal-objects}@anchor{2975}
@subsubsection Decimal objects


@geindex Decimal (decimal 中的類別)
@anchor{library/decimal decimal Decimal}@anchor{1fe}
@deffn {類別} decimal.Decimal (value='0', context=None)

Construct a new @ref{1fe,,Decimal} object based from `value'.

`value' can be an integer, string, tuple, @ref{196,,float}, or another @ref{1fe,,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{60c,,tuple}, it should have three components, a sign
(@code{0} for positive or @code{1} for negative), a @ref{60c,,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{196,,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{12a9,,InvalidOperation}, an exception
is raised; otherwise, the constructor returns a new Decimal with the value of
@code{NaN}.

Once constructed, @ref{1fe,,Decimal} objects are immutable.


在 3.2 版的變更: The argument to the constructor is now permitted to be a @ref{196,,float}
instance.



在 3.3 版的變更: @ref{196,,float} arguments raise an exception if the @ref{129e,,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{196,,float} and @ref{19b,,int}.  All of the usual math
operations and special methods apply.  Likewise, decimal objects can be
copied, pickled, printed, used as dictionary keys, used as set elements,
compared, sorted, and coerced to another type (such as @ref{196,,float} or
@ref{19b,,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{213,,fractions.Fraction} in arithmetic operations:
an attempt to add a @ref{1fe,,Decimal} to a @ref{196,,float}, for
example, will raise a @ref{198,,TypeError}.  However, it is possible to
use Python's comparison operators to compare a @ref{1fe,,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 @ref{1fe,,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{2976}
@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{e8d}
@deffn {方法} as_integer_ratio ()

Return a pair @code{(n, d)} of integers that represent the given
@ref{1fe,,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


在 3.6 版被加入.


@geindex as_tuple() (decimal.Decimal 的方法)
@anchor{library/decimal decimal Decimal as_tuple}@anchor{2977}
@deffn {方法} as_tuple ()

Return a @ref{857,,named tuple} representation of the number:
@code{DecimalTuple(sign, digits, exponent)}.
@end deffn

@geindex canonical() (decimal.Decimal 的方法)
@anchor{library/decimal decimal Decimal canonical}@anchor{2978}
@deffn {方法} canonical ()

Return the canonical encoding of the argument.  Currently, the encoding of
a @ref{1fe,,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{2979}
@deffn {方法} compare (other, context=None)

Compare the values of two Decimal instances.  @ref{2979,,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{297a}
@deffn {方法} compare_signal (other, context=None)

This operation is identical to the @ref{2979,,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{297b}
@deffn {方法} compare_total (other, context=None)

Compare two operands using their abstract representation rather than their
numerical value.  Similar to the @ref{2979,,compare()} method, but the result
gives a total ordering on @ref{1fe,,Decimal} instances.  Two
@ref{1fe,,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{297c}
@deffn {方法} compare_total_mag (other, context=None)

Compare two operands using their abstract representation rather than their
value as in @ref{297b,,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{297d}
@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{297e}
@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{297f}
@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{2980}
@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{12ab}
@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{2965,,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{1405}
@deffn {方法} classmethod from_float (f, /)

Alternative constructor that only accepts instances of @ref{196,,float} or
@ref{19b,,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 @ref{1fe,,Decimal} instance
can also be constructed directly from a @ref{196,,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


在 3.1 版被加入.

@end deffn

@geindex from_number() (decimal.Decimal 的類別方法)
@anchor{library/decimal decimal Decimal from_number}@anchor{1fd}
@deffn {方法} classmethod from_number (number, /)

Alternative constructor that only accepts instances of
@ref{196,,float}, @ref{19b,,int} or @ref{1fe,,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


在 3.14 版被加入.

@end deffn

@geindex fma() (decimal.Decimal 的方法)
@anchor{library/decimal decimal Decimal fma}@anchor{2981}
@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{2982}
@deffn {方法} is_canonical ()

Return @ref{e02,,True} if the argument is canonical and @ref{d23,,False}
otherwise.  Currently, a @ref{1fe,,Decimal} instance is always canonical, so
this operation always returns @ref{e02,,True}.
@end deffn

@geindex is_finite() (decimal.Decimal 的方法)
@anchor{library/decimal decimal Decimal is_finite}@anchor{2983}
@deffn {方法} is_finite ()

Return @ref{e02,,True} if the argument is a finite number, and
@ref{d23,,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{2984}
@deffn {方法} is_infinite ()

Return @ref{e02,,True} if the argument is either positive or negative
infinity and @ref{d23,,False} otherwise.
@end deffn

@geindex is_nan() (decimal.Decimal 的方法)
@anchor{library/decimal decimal Decimal is_nan}@anchor{2985}
@deffn {方法} is_nan ()

Return @ref{e02,,True} if the argument is a (quiet or signaling) NaN and
@ref{d23,,False} otherwise.
@end deffn

@geindex is_normal() (decimal.Decimal 的方法)
@anchor{library/decimal decimal Decimal is_normal}@anchor{2986}
@deffn {方法} is_normal (context=None)

Return @ref{e02,,True} if the argument is a `normal' finite number.  Return
@ref{d23,,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{2987}
@deffn {方法} is_qnan ()

Return @ref{e02,,True} if the argument is a quiet NaN, and
@ref{d23,,False} otherwise.
@end deffn

@geindex is_signed() (decimal.Decimal 的方法)
@anchor{library/decimal decimal Decimal is_signed}@anchor{2988}
@deffn {方法} is_signed ()

Return @ref{e02,,True} if the argument has a negative sign and
@ref{d23,,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{2989}
@deffn {方法} is_snan ()

Return @ref{e02,,True} if the argument is a signaling NaN and @ref{d23,,False}
otherwise.
@end deffn

@geindex is_subnormal() (decimal.Decimal 的方法)
@anchor{library/decimal decimal Decimal is_subnormal}@anchor{298a}
@deffn {方法} is_subnormal (context=None)

Return @ref{e02,,True} if the argument is subnormal, and @ref{d23,,False}
otherwise.
@end deffn

@geindex is_zero() (decimal.Decimal 的方法)
@anchor{library/decimal decimal Decimal is_zero}@anchor{298b}
@deffn {方法} is_zero ()

Return @ref{e02,,True} if the argument is a (positive or negative) zero and
@ref{d23,,False} otherwise.
@end deffn

@geindex ln() (decimal.Decimal 的方法)
@anchor{library/decimal decimal Decimal ln}@anchor{12ac}
@deffn {方法} ln (context=None)

Return the natural (base e) logarithm of the operand.  The result is
correctly rounded using the @ref{2965,,ROUND_HALF_EVEN} rounding mode.
@end deffn

@geindex log10() (decimal.Decimal 的方法)
@anchor{library/decimal decimal Decimal log10}@anchor{298c}
@deffn {方法} log10 (context=None)

Return the base ten logarithm of the operand.  The result is correctly
rounded using the @ref{2965,,ROUND_HALF_EVEN} rounding mode.
@end deffn

@geindex logb() (decimal.Decimal 的方法)
@anchor{library/decimal decimal Decimal logb}@anchor{298d}
@deffn {方法} logb (context=None)

For a nonzero number, return the adjusted exponent of its operand as a
@ref{1fe,,Decimal} instance.  If the operand is a zero then
@code{Decimal('-Infinity')} is returned and the @ref{296a,,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{298e}
@deffn {方法} logical_and (other, context=None)

@ref{298e,,logical_and()} is a logical operation which takes two `logical
operands' (see @ref{298f,,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{2990}
@deffn {方法} logical_invert (context=None)

@ref{2990,,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{2991}
@deffn {方法} logical_or (other, context=None)

@ref{2991,,logical_or()} is a logical operation which takes two `logical
operands' (see @ref{298f,,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{2992}
@deffn {方法} logical_xor (other, context=None)

@ref{2992,,logical_xor()} is a logical operation which takes two `logical
operands' (see @ref{298f,,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{2993}
@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{2994}
@deffn {方法} max_mag (other, context=None)

Similar to the @ref{2993,,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{2995}
@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{2996}
@deffn {方法} min_mag (other, context=None)

Similar to the @ref{2995,,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{2997}
@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{2998}
@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{2999}
@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{299a}
@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{299b}
@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{12b1}
@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{12a9,,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{12a7,,Emax} or less than @ref{299c,,Etiny()}.
@end deffn

@geindex radix() (decimal.Decimal 的方法)
@anchor{library/decimal decimal Decimal radix}@anchor{299d}
@deffn {方法} radix ()

Return @code{Decimal(10)}, the radix (base) in which the @ref{1fe,,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{299e}
@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{299f}
@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{29a0}
@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{29a1}
@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{29a2}
@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{29a3}
@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{29a4}
@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{29a5}
@deffn {方法} to_integral (rounding=None, context=None)

Identical to the @ref{29a6,,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{29a7}
@deffn {方法} to_integral_exact (rounding=None, context=None)

Round to the nearest integer, signaling @ref{296b,,Inexact} or
@ref{296c,,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{29a6}
@deffn {方法} to_integral_value (rounding=None, context=None)

Round to the nearest integer without signaling @ref{296b,,Inexact} or
@ref{296c,,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{14db,,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{19b,,int} to `number',
rounding ties to even, and ignoring the rounding mode of the
@ref{1fe,,Decimal} context.  Raises @ref{a78,,OverflowError} if `number' is an
infinity or @ref{2eb,,ValueError} if it is a (quiet or signaling) NaN.

If `ndigits' is an @ref{19b,,int}, the context's rounding mode is respected
and a @ref{1fe,,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{12a9,,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

舉例來說：

@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{29a8}@anchor{library/decimal logical-operands-label}@anchor{298f}
@subsubsection Logical operands


The @ref{298e,,logical_and()}, @ref{2990,,logical_invert()}, @ref{2991,,logical_or()},
and @ref{2992,,logical_xor()} methods expect their arguments to be `logical
operands'.  A `logical operand' is a @ref{1fe,,Decimal} instance whose
exponent and sign are both zero, and whose digits are all either
@code{0} or @code{1}.

@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

@node Context objects,常數<4>,Decimal objects,decimal --- 十進位固定點和浮點運算
@anchor{library/decimal context-objects}@anchor{29a9}@anchor{library/decimal decimal-context}@anchor{25f2}
@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{189d,,getcontext()} and @ref{2972,,setcontext()} functions:

@geindex getcontext() (於 decimal 模組中)
@anchor{library/decimal decimal getcontext}@anchor{189d}
@deffn {函式} decimal.getcontext ()

Return the current context for the active thread.
@end deffn

@geindex setcontext() (於 decimal 模組中)
@anchor{library/decimal decimal setcontext}@anchor{2972}
@deffn {函式} decimal.setcontext (c, /)

Set the current context for the active thread to `c'.
@end deffn

You can also use the @ref{186,,with} statement and the @ref{157e,,localcontext()}
function to temporarily change the active context.

@geindex localcontext() (於 decimal 模組中)
@anchor{library/decimal decimal localcontext}@anchor{157e}
@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{198,,TypeError} if `kwargs' supplies an attribute that @ref{12b0,,Context} doesn't
support.  Raises either @ref{198,,TypeError} or @ref{2eb,,ValueError} if `kwargs' supplies an
invalid value for an attribute.


在 3.11 版的變更: @ref{157e,,localcontext()} now supports setting context attributes through the use of keyword arguments.

@end deffn

@geindex IEEEContext() (於 decimal 模組中)
@anchor{library/decimal decimal IEEEContext}@anchor{1ff}
@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{29aa,,IEEE_CONTEXT_MAX_BITS}.


在 3.14 版被加入.

@end deffn

New contexts can also be created using the @ref{12b0,,Context} constructor
described below. In addition, the module provides three pre-made contexts:

@geindex BasicContext (於 decimal 模組中)
@anchor{library/decimal decimal BasicContext}@anchor{12a5}
@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{2966,,ROUND_HALF_UP}.  All flags are cleared.  All traps are enabled (treated
as exceptions) except @ref{296b,,Inexact}, @ref{296c,,Rounded}, and
@ref{296d,,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{12a6}
@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{2965,,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{12a4}
@deffn {資料} decimal.DefaultContext

This context is used by the @ref{12b0,,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 @ref{12b0,,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{29ab,,Context.prec}=@code{28},
@ref{29ac,,Context.rounding}=@ref{2965,,ROUND_HALF_EVEN},
and enabled traps for @ref{296e,,Overflow}, @ref{12a9,,InvalidOperation}, and
@ref{296a,,DivisionByZero}.
@end deffn

In addition to the three supplied contexts, new contexts can be created with the
@ref{12b0,,Context} constructor.

@geindex Context (decimal 中的類別)
@anchor{library/decimal decimal Context}@anchor{12b0}
@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{87e,,None}, the
default values are copied from the @ref{12a4,,DefaultContext}.  If the `flags'
field is not specified or is @ref{87e,,None}, all flags are cleared.

@geindex prec (decimal.Context 的屬性)
@anchor{library/decimal decimal Context prec}@anchor{29ab}
@deffn {屬性} prec

An integer in the range [@code{1}, @ref{12a1,,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{29ac}
@deffn {屬性} rounding

One of the constants listed in the section @ref{29ad,,Rounding Modes}.
@end deffn

@geindex traps (decimal.Context 的屬性)
@geindex flags (decimal.Context 的屬性)
@anchor{library/decimal decimal Context traps}@anchor{12af}
@deffn {屬性} traps
@anchor{library/decimal decimal Context flags}@anchor{12ae}
@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{12a8}
@deffn {屬性} Emin
@anchor{library/decimal decimal Context Emax}@anchor{12a7}
@deffnx {屬性} Emax

Integers specifying the outer limits allowable for exponents. `Emin' must
be in the range [@ref{12a3,,MIN_EMIN}, @code{0}], `Emax' in the range
[@code{0}, @ref{12a2,,MAX_EMAX}].
@end deffn

@geindex capitals (decimal.Context 的屬性)
@anchor{library/decimal decimal Context capitals}@anchor{29ae}
@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{139f}
@deffn {屬性} clamp

Either @code{0} (the default) or @code{1}.  If set to @code{1}, the exponent @code{e}
of a @ref{1fe,,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 @ref{1fe,,Decimal} instance is at most @ref{12a7,,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 @ref{12b0,,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{1fe,,Decimal} methods described above (with
the exception of the @ref{2976,,adjusted()} and @ref{2977,,as_tuple()} methods) there is
a corresponding @ref{12b0,,Context} method.  For example, for a @ref{12b0,,Context}
instance @code{C} and @ref{1fe,,Decimal} instance @code{x}, @code{C.exp(x)} is
equivalent to @code{x.exp(context=C)}.  Each @ref{12b0,,Context} method accepts a
Python integer (an instance of @ref{19b,,int}) anywhere that a
Decimal instance is accepted.

@geindex clear_flags() (decimal.Context 的方法)
@anchor{library/decimal decimal Context clear_flags}@anchor{2973}
@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{29af}
@deffn {方法} clear_traps ()

Resets all of the traps to @code{0}.


在 3.3 版被加入.

@end deffn

@geindex copy() (decimal.Context 的方法)
@anchor{library/decimal decimal Context copy}@anchor{29b0}
@deffn {方法} copy ()

Return a duplicate of the context.
@end deffn

@geindex copy_decimal() (decimal.Context 的方法)
@anchor{library/decimal decimal Context copy_decimal}@anchor{29b1}
@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{12aa}
@deffn {方法} create_decimal (num='0', /)

Creates a new Decimal instance from `num' but using `self' as
context. Unlike the @ref{1fe,,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{29b2}
@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{1405,,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


在 3.1 版被加入.

@end deffn

@geindex Etiny() (decimal.Context 的方法)
@anchor{library/decimal decimal Context Etiny}@anchor{299c}
@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{299c,,Etiny}.
@end deffn

@geindex Etop() (decimal.Context 的方法)
@anchor{library/decimal decimal Context Etop}@anchor{29b3}
@deffn {方法} Etop ()

Returns a value equal to @code{Emax - prec + 1}.
@end deffn

The usual approach to working with decimals is to create @ref{1fe,,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 @ref{1fe,,Decimal} class and are only briefly
recounted here.

@geindex abs() (decimal.Context 的方法)
@anchor{library/decimal decimal Context abs}@anchor{29b4}
@deffn {方法} abs (x, /)

Returns the absolute value of `x'.
@end deffn

@geindex add() (decimal.Context 的方法)
@anchor{library/decimal decimal Context add}@anchor{29b5}
@deffn {方法} add (x, y, /)

Return the sum of `x' and `y'.
@end deffn

@geindex canonical() (decimal.Context 的方法)
@anchor{library/decimal decimal Context canonical}@anchor{1507}
@deffn {方法} canonical (x, /)

Returns the same Decimal object `x'.
@end deffn

@geindex compare() (decimal.Context 的方法)
@anchor{library/decimal decimal Context compare}@anchor{29b6}
@deffn {方法} compare (x, y, /)

Compares `x' and `y' numerically.
@end deffn

@geindex compare_signal() (decimal.Context 的方法)
@anchor{library/decimal decimal Context compare_signal}@anchor{29b7}
@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{29b8}
@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{29b9}
@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{29ba}
@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{29bb}
@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{29bc}
@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{29bd}
@deffn {方法} divide (x, y, /)

Return `x' divided by `y'.
@end deffn

@geindex divide_int() (decimal.Context 的方法)
@anchor{library/decimal decimal Context divide_int}@anchor{29be}
@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{29bf}
@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{29c0}
@deffn {方法} exp (x, /)

Returns @code{e ** x}.
@end deffn

@geindex fma() (decimal.Context 的方法)
@anchor{library/decimal decimal Context fma}@anchor{29c1}
@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{1508}
@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{29c2}
@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{29c3}
@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{29c4}
@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{29c5}
@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{29c6}
@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{29c7}
@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{29c8}
@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{29c9}
@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{29ca}
@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{29cb}
@deffn {方法} ln (x, /)

Returns the natural (base e) logarithm of `x'.
@end deffn

@geindex log10() (decimal.Context 的方法)
@anchor{library/decimal decimal Context log10}@anchor{29cc}
@deffn {方法} log10 (x, /)

Returns the base 10 logarithm of `x'.
@end deffn

@geindex logb() (decimal.Context 的方法)
@anchor{library/decimal decimal Context logb}@anchor{29cd}
@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{29ce}
@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{29cf}
@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{29d0}
@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{29d1}
@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{29d2}
@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{29d3}
@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{29d4}
@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{29d5}
@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{29d6}
@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{29d7}
@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{29d8}
@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{29d9}
@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{29da}
@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{29db}
@deffn {方法} normalize (x, /)

Reduces `x' to its simplest form.
@end deffn

@geindex number_class() (decimal.Context 的方法)
@anchor{library/decimal decimal Context number_class}@anchor{29dc}
@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{29dd}
@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{29de}
@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 @ref{29de,,power()} in terms of the correctly rounded
@ref{29c0,,exp()} and @ref{29cb,,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{29df}
@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{29e0}
@deffn {方法} radix ()

Just returns 10, as this is Decimal, :)
@end deffn

@geindex remainder() (decimal.Context 的方法)
@anchor{library/decimal decimal Context remainder}@anchor{29e1}
@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{29e2}
@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{29e3}
@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{29e4}
@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{29e5}
@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{29e6}
@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{29e7}
@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{29e8}
@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{29e9}
@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{29ea}
@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{29eb}
@deffn {方法} to_sci_string (x, /)

Converts a number to a string using scientific notation.
@end deffn
@end deffn

@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

@node 常數<4>,Rounding modes,Context objects,decimal --- 十進位固定點和浮點運算
@anchor{library/decimal constants}@anchor{29ec}@anchor{library/decimal decimal-rounding-modes}@anchor{29ed}
@subsubsection 常數


The constants in this section 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 位元

@tab

64 位元

@item

@geindex MAX_PREC (於 decimal 模組中)
@anchor{library/decimal decimal MAX_PREC}@anchor{12a1}
@deffn {資料} decimal.MAX_PREC
@end deffn

@tab

@code{425000000}

@tab

@code{999999999999999999}

@item

@geindex MAX_EMAX (於 decimal 模組中)
@anchor{library/decimal decimal MAX_EMAX}@anchor{12a2}
@deffn {資料} decimal.MAX_EMAX
@end deffn

@tab

@code{425000000}

@tab

@code{999999999999999999}

@item

@geindex MIN_EMIN (於 decimal 模組中)
@anchor{library/decimal decimal MIN_EMIN}@anchor{12a3}
@deffn {資料} decimal.MIN_EMIN
@end deffn

@tab

@code{-425000000}

@tab

@code{-999999999999999999}

@item

@geindex MIN_ETINY (於 decimal 模組中)
@anchor{library/decimal decimal MIN_ETINY}@anchor{29ee}
@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{29aa}
@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{129f}
@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{202a}
@deffn {資料} decimal.HAVE_CONTEXTVAR

The default value is @code{True}. If Python is @ref{2029,,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.


在 3.8.3 版被加入.

@end deffn

@node Rounding modes,Signals,常數<4>,decimal --- 十進位固定點和浮點運算
@anchor{library/decimal rounding-modes}@anchor{29ad}
@subsubsection Rounding modes


@geindex ROUND_CEILING (於 decimal 模組中)
@anchor{library/decimal decimal ROUND_CEILING}@anchor{2961}
@deffn {資料} decimal.ROUND_CEILING

Round towards @code{Infinity}.
@end deffn

@geindex ROUND_DOWN (於 decimal 模組中)
@anchor{library/decimal decimal ROUND_DOWN}@anchor{2962}
@deffn {資料} decimal.ROUND_DOWN

Round towards zero.
@end deffn

@geindex ROUND_FLOOR (於 decimal 模組中)
@anchor{library/decimal decimal ROUND_FLOOR}@anchor{2963}
@deffn {資料} decimal.ROUND_FLOOR

Round towards @code{-Infinity}.
@end deffn

@geindex ROUND_HALF_DOWN (於 decimal 模組中)
@anchor{library/decimal decimal ROUND_HALF_DOWN}@anchor{2964}
@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{2965}
@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{2966}
@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{2967}
@deffn {資料} decimal.ROUND_UP

Round away from zero.
@end deffn

@geindex ROUND_05UP (於 decimal 模組中)
@anchor{library/decimal decimal ROUND_05UP}@anchor{2968}
@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 --- 十進位固定點和浮點運算
@anchor{library/decimal decimal-signals}@anchor{29ef}@anchor{library/decimal signals}@anchor{29f0}
@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{296a,,DivisionByZero} trap
is set, then a @ref{296a,,DivisionByZero} exception is raised upon encountering the
condition.

@geindex Clamped (decimal 中的類別)
@anchor{library/decimal decimal Clamped}@anchor{2969}
@deffn {類別} decimal.Clamped

Altered an exponent to fit representation constraints.

Typically, clamping occurs when an exponent falls outside the context's
@ref{12a8,,Emin} and @ref{12a7,,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{29f1}
@deffn {類別} decimal.DecimalException

Base class for other signals and a subclass of @ref{258f,,ArithmeticError}.
@end deffn

@geindex DivisionByZero (decimal 中的類別)
@anchor{library/decimal decimal DivisionByZero}@anchor{296a}
@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{296b}
@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{12a9}
@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{296e}
@deffn {類別} decimal.Overflow

Numerical overflow.

Indicates the exponent is larger than @ref{12a7,,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{296b,,Inexact} and @ref{296c,,Rounded}
are also signaled.
@end deffn

@geindex Rounded (decimal 中的類別)
@anchor{library/decimal decimal Rounded}@anchor{296c}
@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{296d}
@deffn {類別} decimal.Subnormal

Exponent was lower than @ref{12a8,,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{296f}
@deffn {類別} decimal.Underflow

Numerical underflow with result rounded to zero.

Occurs when a subnormal result is pushed to zero by rounding. @ref{296b,,Inexact}
and @ref{296d,,Subnormal} are also signaled.
@end deffn

@geindex FloatOperation (decimal 中的類別)
@anchor{library/decimal decimal FloatOperation}@anchor{129e}
@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{1fe,,Decimal} constructor,
@ref{12aa,,create_decimal()} and all comparison operators.
Both conversion and comparisons are exact. Any occurrence of a mixed
operation is silently recorded by setting @ref{129e,,FloatOperation} in the
context flags. Explicit conversions with @ref{1405,,from_float()}
or @ref{29b2,,create_decimal_from_float()} do not set the flag.

Otherwise (the signal is trapped), only equality comparisons and explicit
conversions are silent. All other mixed operations raise @ref{129e,,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 --- 十進位固定點和浮點運算
@anchor{library/decimal decimal-notes}@anchor{29f2}@anchor{library/decimal floating-point-notes}@anchor{29f3}
@subsubsection Floating-point notes


@menu
* Mitigating round-off error with increased precision:: 
* 特殊值:: 

@end menu

@node Mitigating round-off error with increased precision,特殊值,,Floating-point notes
@anchor{library/decimal mitigating-round-off-error-with-increased-precision}@anchor{29f4}
@subsubsection Mitigating round-off error with increased precision


The use of decimal floating point eliminates decimal representation error
(making it possible to represent @code{0.1} exactly); however, some operations
can still incur round-off error when non-zero digits exceed the fixed precision.

The effects of round-off error can be amplified by the addition or subtraction
of nearly offsetting quantities resulting in loss of significance.  Knuth
provides two instructive examples where rounded floating-point arithmetic with
insufficient precision causes the breakdown of the associative and distributive
properties of addition:

@example
# Examples from Seminumerical Algorithms, Section 4.2.2.
>>> from decimal import Decimal, getcontext
>>> getcontext().prec = 8

>>> u, v, w = Decimal(11111113), Decimal(-11111111), Decimal('7.51111111')
>>> (u + v) + w
Decimal('9.5111111')
>>> u + (v + w)
Decimal('10')

>>> u, v, w = Decimal(20000), Decimal(-6), Decimal('6.0000003')
>>> (u*v) + (u*w)
Decimal('0.01')
>>> u * (v+w)
Decimal('0.0060000')
@end example

The @ref{3a,,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 特殊值,,Mitigating round-off error with increased precision,Floating-point notes
@anchor{library/decimal special-values}@anchor{29f5}
@subsubsection 特殊值


The number system for the @ref{3a,,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{296a,,DivisionByZero} signal is
not trapped.  Likewise, when the @ref{296e,,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{12a9,,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{d23,,False} (even when doing
@code{Decimal('NaN')==Decimal('NaN')}), while a test for inequality always returns
@ref{e02,,True}.  An attempt to compare two Decimals using any of the @code{<},
@code{<=}, @code{>} or @code{>=} operators will raise the @ref{12a9,,InvalidOperation} signal
if either operand is a @code{NaN}, and return @ref{d23,,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{2979,,compare()}
and @ref{297a,,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 --- 十進位固定點和浮點運算
@anchor{library/decimal decimal-threads}@anchor{29f6}@anchor{library/decimal working-with-threads}@anchor{29f7}
@subsubsection Working with threads


The @ref{189d,,getcontext()} function accesses a different @ref{12b0,,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{2972,,setcontext()} function automatically assigns its target to
the current thread.

If @ref{2972,,setcontext()} has not been called before @ref{189d,,getcontext()}, then
@ref{189d,,getcontext()} will automatically create a new context for use in the
current thread.  New context objects have default values set from the
@ref{12a4,,decimal.DefaultContext} object.

The @ref{175,,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{189d,,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{178,,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{189d,,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 --- 十進位固定點和浮點運算
@anchor{library/decimal decimal-recipes}@anchor{29f8}@anchor{library/decimal recipes}@anchor{29f9}
@subsubsection Recipes


Here are a few recipes that serve as utility functions and that demonstrate ways
to work with the @ref{1fe,,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 --- 十進位固定點和浮點運算
@anchor{library/decimal decimal-faq}@anchor{29fa}@anchor{library/decimal id1}@anchor{29fb}
@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{12b1,,quantize()} method rounds to a fixed number of decimal places. If
the @ref{296b,,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{12b1,,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{12b1,,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{299a,,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{1fe,,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{12aa,,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{

在 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{12a8,,Emin}
and @ref{12a7,,Emax} should always be set to the maximum values, @ref{139f,,clamp}
should always be 0 (the default).  Setting @ref{29ab,,prec} requires some care.

The easiest approach for trying out bignum arithmetic is to use the maximum
value for @ref{29ab,,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{12a1,,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{29ab,,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{296b,,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 --- 有理數,random --- 產生偽隨機數,decimal --- 十進位固定點和浮點運算,數值與數學模組
@anchor{library/fractions doc}@anchor{29fc}@anchor{library/fractions fractions-rational-numbers}@anchor{29fd}@anchor{library/fractions module-fractions}@anchor{61}@anchor{library/fractions translation-repo}@anchor{29fe}
@subsection @code{fractions} --- 有理數


@geindex module; fractions

`原始碼：'Lib/fractions.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/fractions.py}


__________________________________________________________________


The @ref{61,,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{213}
@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{14bf,,numbers.Rational} and returns a new @ref{213,,Fraction} instance
with a value equal to @code{numerator/denominator}.
If `denominator' is zero, it raises a @ref{b36,,ZeroDivisionError}.

The second version requires that `number' is an instance of
@ref{14bf,,numbers.Rational} or has the @code{as_integer_ratio()} method
(this includes @ref{196,,float} and @ref{1fe,,decimal.Decimal}).
It returns a @ref{213,,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{1fc7,,浮點數運算：問題與限制}), 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{29ff,,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{196,,float} constructor is also
accepted by the @ref{213,,Fraction} constructor.  In either form the
input string may also have leading and/or trailing whitespace.
Here are some examples:

@example
>>> from fractions import Fraction
>>> Fraction(16, -10)
Fraction(-8, 5)
>>> Fraction(123)
Fraction(123, 1)
>>> Fraction()
Fraction(0, 1)
>>> Fraction('3/7')
Fraction(3, 7)
>>> Fraction(' -3/7 ')
Fraction(-3, 7)
>>> Fraction('1.414213 \t\n')
Fraction(1414213, 1000000)
>>> Fraction('-.125')
Fraction(-1, 8)
>>> Fraction('7e-6')
Fraction(7, 1000000)
>>> Fraction(2.25)
Fraction(9, 4)
>>> Fraction(1.1)
Fraction(2476979795053773, 2251799813685248)
>>> from decimal import Decimal
>>> Fraction(Decimal('1.1'))
Fraction(11, 10)
@end example

The @ref{213,,Fraction} class inherits from the abstract base class
@ref{14bf,,numbers.Rational}, and implements all of the methods and
operations from that class.  @ref{213,,Fraction} instances are @ref{81d,,hashable},
and should be treated as immutable.  In addition,
@ref{213,,Fraction} has the following properties and methods:


在 3.2 版的變更: @ref{213,,Fraction} 建構函式現在可接受 @ref{196,,float} 和 @ref{1fe,,decimal.Decimal} 實例。



在 3.9 版的變更: The @ref{b03,,math.gcd()} function is now used to normalize the `numerator'
and `denominator'. @ref{b03,,math.gcd()} always returns an @ref{19b,,int} type.
Previously, the GCD type depended on `numerator' and `denominator'.



在 3.11 版的變更: Underscores are now permitted when creating a @ref{213,,Fraction} instance
from a string, following 
@geindex Python Enhancement Proposals; PEP 515
PEP 515@footnote{https://peps.python.org/pep-0515/} rules.



在 3.11 版的變更: @ref{213,,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 版的變更: @ref{213,,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 @ref{213,,Fraction} instances without a presentation type
now supports fill, alignment, sign handling, minimum width and grouping.



在 3.14 版的變更: @ref{213,,Fraction} 建構函式現在可接受任何具有 @code{as_integer_ratio()} 方法的物件。


@geindex numerator (fractions.Fraction 的屬性)
@anchor{library/fractions fractions Fraction numerator}@anchor{2a00}
@deffn {屬性} numerator

Numerator of the Fraction in lowest term.
@end deffn

@geindex denominator (fractions.Fraction 的屬性)
@anchor{library/fractions fractions Fraction denominator}@anchor{2a01}
@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{2a02}
@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.


在 3.8 版被加入.

@end deffn

@geindex is_integer() (fractions.Fraction 的方法)
@anchor{library/fractions fractions Fraction is_integer}@anchor{2a03}
@deffn {方法} is_integer ()

Return @code{True} if the Fraction is an integer.


在 3.12 版被加入.

@end deffn

@geindex from_float() (fractions.Fraction 的類別方法)
@anchor{library/fractions fractions Fraction from_float}@anchor{1406}
@deffn {方法} classmethod from_float (f)

Alternative constructor which only accepts instances of
@ref{196,,float} or @ref{22b9,,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
@ref{213,,Fraction} instance directly from a @ref{196,,float}.
@end quotation
@end cartouche
@end deffn

@geindex from_decimal() (fractions.Fraction 的類別方法)
@anchor{library/fractions fractions Fraction from_decimal}@anchor{1407}
@deffn {方法} classmethod from_decimal (dec)

Alternative constructor which only accepts instances of
@ref{1fe,,decimal.Decimal} or @ref{22b9,,numbers.Integral}.

@cartouche
@quotation 備註 
From Python 3.2 onwards, you can also construct a
@ref{213,,Fraction} instance directly from a @ref{1fe,,decimal.Decimal}
instance.
@end quotation
@end cartouche
@end deffn

@geindex from_number() (fractions.Fraction 的類別方法)
@anchor{library/fractions fractions Fraction from_number}@anchor{214}
@deffn {方法} classmethod from_number (number)

Alternative constructor which only accepts instances of
@ref{22b9,,numbers.Integral}, @ref{14bf,,numbers.Rational},
@ref{196,,float} or @ref{1fe,,decimal.Decimal}, and objects with
the @code{as_integer_ratio()} method, but not strings.


在 3.14 版被加入.

@end deffn

@geindex limit_denominator() (fractions.Fraction 的方法)
@anchor{library/fractions fractions Fraction limit_denominator}@anchor{29ff}
@deffn {方法} limit_denominator (max_denominator=1000000)

Finds and returns the closest @ref{213,,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{1a3d}
@deffn {方法} __floor__ ()

Returns the greatest @ref{19b,,int} @code{<= self}.  This method can
also be accessed through the @ref{15b5,,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{1a3c}
@deffn {方法} __ceil__ ()

Returns the least @ref{19b,,int} @code{>= self}.  This method can
also be accessed through the @ref{15b6,,math.ceil()} function.
@end deffn

@geindex __round__() (fractions.Fraction 的方法)
@anchor{library/fractions fractions Fraction __round__}@anchor{1a3b}
@deffn {方法} __round__ ()

@deffnx {方法} __round__ (ndigits)

The first version returns the nearest @ref{19b,,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{14db,,round()} function.
@end deffn

@geindex __format__() (fractions.Fraction 的方法)
@anchor{library/fractions fractions Fraction __format__}@anchor{2a04}
@deffn {方法} __format__ (format_spec, /)

Provides support for formatting of @ref{213,,Fraction} instances via the
@ref{82c,,str.format()} method, the @ref{199,,format()} built-in function, or
@ref{19a,,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{4f4,,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{196,,float} type in the @ref{4f4,,格式規格 (Format Specification) 迷你語言} 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 @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 --- 數學統計函式,fractions --- 有理數,數值與數學模組
@anchor{library/random doc}@anchor{2a05}@anchor{library/random module-random}@anchor{bd}@anchor{library/random random-generate-pseudo-random-numbers}@anchor{2a06}@anchor{library/random translation-repo}@anchor{2a07}
@subsection @code{random} --- 產生偽隨機數


@geindex module; random

`原始碼：'Lib/random.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/random.py}


__________________________________________________________________


本章中所提及的 module（模組）用來實現各種分佈的虛擬隨機數產生器。

對於整數，可以從範圍中進行均勻選擇。對於序列，有一個隨機元素的均勻選擇，一個用來原地 (in-place) 產生隨機排列清單的函式，以及一個用來隨機取樣不重置的函式。

在實數線上，有一些函式用於處理均勻分佈、常態分佈（高斯分佈）、對數常態分佈、負指數分佈、gamma 分佈和 Beta 分佈。對於產生角度分佈，可以使用馮·米塞斯分佈 (von Mises distribution)。

幾乎所有 module 函式都相依於基本函式 @ref{947,,random()}，此函式在半開放範圍 @code{0.0 <= X < 1.0} 內均勻地產生一個隨機 float（浮點數）。Python 使用 Mersenne Twister（梅森旋轉演算法）作為核心的產生器，它產生 53 位元精度 float，其週期為 2**19937-1，透過 C 語言進行底層的實作既快速又支援執行緒安全 (threadsafe)。Mersenne Twister 是現存最廣泛被驗證的隨機數產生器之一，但是基於完全確定性，它並不適合所有目的，並且完全不適合加密目的。

該 module 提供的函式實際上是 @ref{1b5e,,random.Random} class（類別）中一個隱藏實例的綁定方法 (bound method)。你可以實例化自己的 @ref{1b5e,,Random} 實例，以得到不共享狀態的產生器。

如果你想使用你自己設計的基本產生器，@ref{1b5e,,Random} 也可以進行子類別化 (subclass)。有關詳細資訊，請參考該類別的文件。

@ref{bd,,random} module 也提供了 @ref{2a08,,SystemRandom} class，使用系統函式 @ref{73f,,os.urandom()} 從作業系統提供的來源產生隨機數。

@cartouche
@quotation 警告 
本章所提及的虛擬隨機數產生器不應該使用於安全目的。有關安全性或加密用途，請參考 @ref{c5,,secrets} module。
@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) 用法@footnote{https://code.activestate.com/recipes/576707-long-period-random-number-generator/}，可作為隨機數產生器的一個可相容替代方案，具有較長的週期和相對簡單的更新操作。


@cartouche
@quotation 備註 
全域隨機數產生器和 @ref{1b5e,,Random} 的實例是執行緒安全的。然而，在自由執行緒構建中，對全域產生器或同一 @ref{1b5e,,Random} 實例的並行呼叫可能會遇到爭用和性能不佳。請考慮改為每個執行緒使用單獨的 @ref{1b5e,,Random} 實例。
@end quotation
@end cartouche

@menu
* 簿記函式 (bookkeeping functions): 簿記函式 bookkeeping functions. 
* 回傳位元組的函式:: 
* 回傳整數的函式:: 
* 回傳序列的函式:: 
* 離散分布:: 
* 實數分布:: 
* 替代產生器:: 
* 關於 Reproducibility（復現性）的注意事項:: 
* 範例: 範例<6>. 
* 使用方案:: 
* 命令列用法: 命令列用法<2>. 
* 命令列範例:: 

@end menu

@node 簿記函式 bookkeeping functions,回傳位元組的函式,,random --- 產生偽隨機數
@anchor{library/random bookkeeping-functions}@anchor{2a09}
@subsubsection 簿記函式 (bookkeeping functions)


@geindex seed() (於 random 模組中)
@anchor{library/random random seed}@anchor{1474}
@deffn {函式} random.seed (a=None, version=2)

初始化隨機數產生器。

如果 `a' 被省略或為 @code{None}，則使用目前系統時間。如果隨機來源由作業系統提供，則使用它們而不是系統時間（有關可用性的詳細資訊，請參考 @ref{73f,,os.urandom()} 函式）。

如果 `a' 為 int（整數），則直接使用它。

如使用版本 2（預設值），@ref{169,,str}、@ref{192,,bytes} 或 @ref{343,,bytearray} 物件將轉換為 @ref{19b,,int}，並使用其所有位元。

若使用版本 1（為復現於舊版本 Python 中產生隨機序列而提供），@ref{169,,str} 和 @ref{192,,bytes} 的演算法會產生範圍更窄的種子 (seed)。


在 3.2 版的變更: 移至版本 2 方案，該方案使用字串種子中的所有位元。



在 3.11 版的變更: `seed' 必須是以下型別之一：@code{None}、@ref{19b,,int}、@ref{196,,float}、@ref{169,,str}、@ref{192,,bytes}、@ref{343,,bytearray}。

@end deffn

@geindex getstate() (於 random 模組中)
@anchor{library/random random getstate}@anchor{2a0a}
@deffn {函式} random.getstate ()

回傳一個物件，捕獲產生器的目前內部狀態。此物件可以傳遞給 @ref{2a0b,,setstate()} 以恢復狀態。
@end deffn

@geindex setstate() (於 random 模組中)
@anchor{library/random random setstate}@anchor{2a0b}
@deffn {函式} random.setstate (state)

`state' 應該要從之前對 @ref{2a0a,,getstate()} 的呼叫中獲得，並且以 @ref{2a0b,,setstate()} 將產生器的內部狀態恢復到呼叫 @ref{2a0a,,getstate()} 時的狀態。
@end deffn

@node 回傳位元組的函式,回傳整數的函式,簿記函式 bookkeeping functions,random --- 產生偽隨機數
@anchor{library/random functions-for-bytes}@anchor{2a0c}
@subsubsection 回傳位元組的函式


@geindex randbytes() (於 random 模組中)
@anchor{library/random random randbytes}@anchor{17a9}
@deffn {函式} random.randbytes (n)

產生 `n' 個隨機位元組。

此方法不應使用於產生安全性權杖 (Token)。請改用 @ref{2a0d,,secrets.token_bytes()}。


在 3.9 版被加入.

@end deffn

@node 回傳整數的函式,回傳序列的函式,回傳位元組的函式,random --- 產生偽隨機數
@anchor{library/random functions-for-integers}@anchor{2a0e}
@subsubsection 回傳整數的函式


@geindex randrange() (於 random 模組中)
@anchor{library/random random randrange}@anchor{a64}
@deffn {函式} random.randrange (stop)

@deffnx {函式} random.randrange (start, stop[, step])

傳回從 @code{range(start, stop, step)} 中隨機選擇的元素。

這大致相當於 @code{choice(range(start, stop, step))}，但支援任意大的範圍，並針對常見情況進行了最佳化。

位置引數模式與 @ref{b34,,range()} 函式相符。

不應使用關鍵字引數，因為它們可能會以意想不到的方式被直譯。例如 @code{randrange(start=100)} 會被直譯為 @code{randrange(0, 100, 1)}。


在 3.2 版的變更: @ref{a64,,randrange()} 在產生均勻分佈的值方面更為複雜。以前，它使用像 @code{int(random()*n)} 這樣的樣式，這可能會產生稍微不均勻的分佈。



在 3.12 版的變更: 已經不再支援非整數類型到等效整數的自動轉換。像是 @code{randrange(10.0)} 和 @code{randrange(Fraction(10, 1))} 的呼叫將會引發 @ref{198,,TypeError}。

@end deffn

@geindex randint() (於 random 模組中)
@anchor{library/random random randint}@anchor{1430}
@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{1208}
@deffn {函式} random.getrandbits (k)

回傳一個具有 `k' 個隨機位元的非負 Python 整數。此方法會隨 Mersenne Twister 產生器一起提供，一些其他的產生器也可能將其作為 API 的可選部分。如果可用，@ref{1208,,getrandbits()} 使 @ref{a64,,randrange()} 能夠處理任意大的範圍。


在 3.9 版的變更: 此方法現在接受 `k' 為零。

@end deffn

@node 回傳序列的函式,離散分布,回傳整數的函式,random --- 產生偽隨機數
@anchor{library/random functions-for-sequences}@anchor{2a0f}
@subsubsection 回傳序列的函式


@geindex choice() (於 random 模組中)
@anchor{library/random random choice}@anchor{1431}
@deffn {函式} random.choice (seq)

從非空序列 `seq' 回傳一個隨機元素。如果 `seq' 為空，則引發 @ref{1729,,IndexError}。
@end deffn

@geindex choices() (於 random 模組中)
@anchor{library/random random choices}@anchor{ebc}
@deffn {函式} random.choices (population, weights=None, *, cum_weights=None, k=1)

回傳從 `population' 中重置取樣出的一個大小為 `k' 的元素 list。如果 `population' 為空，則引發 @ref{1729,,IndexError}。

如果指定了 `weights' 序列，則根據相對權重進行選擇。另外，如果給定 `cum_weights' 序列，則根據累積權重進行選擇（可能使用 @ref{be7,,itertools.accumulate()} 計算）。例如，相對權重 @code{[10, 5, 30, 5]} 等同於累積權重 @code{[10, 15, 45, 50]}。在內部，相對權重在進行選擇之前會轉換為累積權重，因此提供累積權重可以節省工作。

如果既未指定 `weights' 也未指定 `cum_weights'，則以相等的機率進行選擇。如果提供了加權序列，則該序列的長度必須與 `population' 序列的長度相同。它是一個 @ref{198,,TypeError} 來指定 `weights' 和 `cum_weights'。

`weights' 或 `cum_weights' 可以使用任何與 @ref{bd,,random()} 所回傳的 @ref{196,,float} 值（包括整數、float 和分數，但不包括小數）交互操作 (interoperates) 的數值類型。權重假定為非負數和有限的。如果所有權重均為零，則引發 @ref{2eb,,ValueError}。

對於給定的種子，具有相等權重的 @ref{ebc,,choices()} 函式通常產生與重複呼叫 @ref{1431,,choice()} 不同的序列。@ref{ebc,,choices()} 使用的演算法使用浮點運算來實現內部一致性和速度。@ref{1431,,choice()} 使用的演算法預設為整數運算和重複選擇，以避免捨入誤差產生的小偏差。


在 3.6 版被加入.



在 3.9 版的變更: 如果所有權重均為零，則引發 @ref{2eb,,ValueError}。

@end deffn

@geindex shuffle() (於 random 模組中)
@anchor{library/random random shuffle}@anchor{946}
@deffn {函式} random.shuffle (x)

將序列 `x' 原地 (in place) 隨機打亂位置。

要打亂一個不可變的序列並回傳一個新的被打亂的 list（串列），請使用 @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{945}
@deffn {函式} random.sample (population, k, *, counts=None)

回傳從母體序列中選擇出的一個包含獨特元素、長度為 `k' 的 list。用於不重置的隨機取樣。

回傳包含母體元素的新清單，同時保持原始母體不變。產生的清單按選擇順序排列，因此所有子切片也會是有效的隨機樣本。這允許抽獎獲獎者（樣本）分為大獎和第二名獲獎者（子切片）。

母體成員不必是 @ref{81d,,hashable} 或唯一的。如果母體包含重複項，則每次出現都是樣本中可能出現的一個選擇。

可以一次指定一個重複元素，也可以使用可選的僅關鍵字 `counts' 參數指定重複元素。例如 @code{sample(['red', 'blue'], counts=[4, 2], k=5)} 等同於 @code{sample(['red', 'red', 'red', 'red', 'blue', 'blue'], k=5)}。

若要從整數範圍中選擇範例，請使用 @ref{b34,,range()} 物件作為引數。這對於從大型母體中取樣特別快速且節省空間：@code{sample(range(10000000), k=60)}。

如果樣本大小大於母體大小，@ref{2eb,,ValueError} 會被引發。


在 3.9 版的變更: 新增 `counts' 參數。



在 3.11 版的變更: `population' 必須是一個序列。不再支援將 set 自動轉換為 list。

@end deffn

@node 離散分布,實數分布,回傳序列的函式,random --- 產生偽隨機數
@anchor{library/random discrete-distributions}@anchor{2a10}
@subsubsection 離散分布


以下函式產生離散分佈。

@geindex binomialvariate() (於 random 模組中)
@anchor{library/random random binomialvariate}@anchor{6d0}
@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} 範圍內的整數。


在 3.12 版被加入.

@end deffn

@node 實數分布,替代產生器,離散分布,random --- 產生偽隨機數
@anchor{library/random id1}@anchor{2a11}@anchor{library/random real-valued-distributions}@anchor{2a12}
@subsubsection 實數分布


以下函式產生特定的實數分佈。函式參數以分佈方程中的對應變數命名，如常見的數學實踐所示；這些方程式中的大多數都可以在任意統計文本中找到。

@geindex random() (於 random 模組中)
@anchor{library/random random random}@anchor{947}
@deffn {函式} random.random ()

回傳範圍 @code{0.0 <= X < 1.0} 中的下一個隨機浮點數
@end deffn

@geindex uniform() (於 random 模組中)
@anchor{library/random random uniform}@anchor{2a13}
@deffn {函式} random.uniform (a, b)

回傳一個隨機浮點數 `N'，當 @code{a <= b} 時確保 N 為 @code{a <= N <= b} 、@code{b < a} 時確保 N 為 @code{b <= N <= a}。

終點值 @code{b} 可能包含在範圍內，也可能不包含在範圍內，取決於運算式 @code{a + (b-a) * random()} 中的浮點捨入。
@end deffn

@geindex triangular() (於 random 模組中)
@anchor{library/random random triangular}@anchor{2a14}
@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{2a15}
@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{6d1}
@deffn {函式} random.expovariate (lambd=1.0)

指數分佈。`lambd' 為 1.0 除以所需的平均數。它應該不為零。（該參數將被稱為 "lambda"，但這是 Python 中的保留字）如果 `lambd' 為正，則回傳值的範圍從 0 到正無窮大；如果 `lambd' 為負，則回傳值的範圍從負無窮大到 0。


在 3.12 版的變更: 新增 @code{lambd} 的預設值。

@end deffn

@geindex gammavariate() (於 random 模組中)
@anchor{library/random random gammavariate}@anchor{2a16}
@deffn {函式} random.gammavariate (alpha, beta)

Gamma（伽瑪）分佈。（`不是' Gamma 函式！）。形狀 (shape) 和比例 (scale) 參數 `alpha' 和 `beta' 必須具有正值。（根據呼叫習慣不同，部分來源會將 'beta' 定義為比例的倒數）。

Probability distribution function（機率密度函式）是：

@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{1af8}
@deffn {函式} random.gauss (mu=0.0, sigma=1.0)

常態分佈，也稱為高斯分佈。`mu' 是平均數，`sigma' 是標準差。這比下面定義的 @ref{1af9,,normalvariate()} 函式快一點。

多執行緒須注意：當兩個執行緒同時呼叫此函式時，它們可能會收到相同的傳回值。這可以透過三種方式避免。1）讓每個執行緒使用隨機數產生器的不同實例。2）在所有呼叫周圍加鎖。3）使用較慢但執行緒安全的 @ref{1af9,,normalvariate()} 函式代替。


在 3.11 版的變更: `mu' 和 `sigma' 現在有預設引數。

@end deffn

@geindex lognormvariate() (於 random 模組中)
@anchor{library/random random lognormvariate}@anchor{2a17}
@deffn {函式} random.lognormvariate (mu, sigma)

對數常態分佈。如果你取此分佈的自然對數，你將獲得一個具有平均數 `mu' 和標準差 `sigma' 的常態分佈。`mu' 可以為任何值，並且 `sigma' 必須大於零。
@end deffn

@geindex normalvariate() (於 random 模組中)
@anchor{library/random random normalvariate}@anchor{1af9}
@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{2a18}
@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{2a19}
@deffn {函式} random.paretovariate (alpha)

Pareto distribution（柏拉圖分佈）。`alpha' 是形狀參數。
@end deffn

@geindex weibullvariate() (於 random 模組中)
@anchor{library/random random weibullvariate}@anchor{2a1a}
@deffn {函式} random.weibullvariate (alpha, beta)

Weibull distribution（韋伯分佈）。`alpha' 是比例參數，`beta' 是形狀參數。
@end deffn

@node 替代產生器,關於 Reproducibility（復現性）的注意事項,實數分布,random --- 產生偽隨機數
@anchor{library/random alternative-generator}@anchor{2a1b}
@subsubsection 替代產生器


@geindex Random (random 中的類別)
@anchor{library/random random Random}@anchor{1b5e}
@deffn {類別} random.Random ([seed])

實現 @ref{bd,,random} 模組使用的預設偽隨機數產生器的 class。


在 3.11 版的變更: 過去 `seed' 可以是任何可雜湊物件，但現在必須是以下類型之一：@code{None}、@ref{19b,,int}、@ref{196,,float}、@ref{169,,str}、@ref{192,,bytes}、@ref{343,,bytearray}。


如果 @code{Random} 的子類別希望使用不同的基礎產生器，則應該覆寫以下方法：

@geindex seed() (random.Random 的方法)
@anchor{library/random random Random seed}@anchor{1c33}
@deffn {方法} seed (a=None, version=2)

在子類別中覆寫此方法以自訂 @code{Random} 實例的 @ref{1474,,seed()} 行為。
@end deffn

@geindex getstate() (random.Random 的方法)
@anchor{library/random random Random getstate}@anchor{2a1c}
@deffn {方法} getstate ()

在子類別中覆寫此方法以自訂 @code{Random} 實例的 @ref{2a0a,,getstate()} 行為。
@end deffn

@geindex setstate() (random.Random 的方法)
@anchor{library/random random Random setstate}@anchor{2a1d}
@deffn {方法} setstate (state)

在子類別中覆寫此方法以自訂 @code{Random} 實例的 @ref{2a0b,,setstate()} 行為。
@end deffn

@geindex random() (random.Random 的方法)
@anchor{library/random random Random random}@anchor{2a1e}
@deffn {方法} random ()

在子類別中覆寫此方法以自訂 @code{Random} 實例的 @ref{947,,random()} 行為。
@end deffn

或者，自訂產生器子類別還可以提供以下方法：

@geindex getrandbits() (random.Random 的方法)
@anchor{library/random random Random getrandbits}@anchor{2a1f}
@deffn {方法} getrandbits (k)

在子類別中覆寫此方法以自訂 @code{Random} 實例的 @ref{1208,,getrandbits()} 行為。
@end deffn

@geindex randbytes() (random.Random 的方法)
@anchor{library/random random Random randbytes}@anchor{b1a}
@deffn {方法} randbytes (n)

在子類別中覆寫此方法以自訂 @code{Random} 實例的 @ref{17a9,,randbytes()} 行為。
@end deffn
@end deffn

@geindex SystemRandom (random 中的類別)
@anchor{library/random random SystemRandom}@anchor{2a08}
@deffn {類別} random.SystemRandom ([seed])

使用 @ref{73f,,os.urandom()} 函式從作業系統提供的來源產生隨機數的 Class。並非在所有系統上都可用。不依賴於軟體狀態，並且序列不可復現。因此 @ref{1474,,seed()} 方法沒有效果且被忽略。如果呼叫 @ref{2a0a,,getstate()} 和 @ref{2a0b,,setstate()} 方法會引發 @ref{369,,NotImplementedError}。
@end deffn

@node 關於 Reproducibility（復現性）的注意事項,範例<6>,替代產生器,random --- 產生偽隨機數
@anchor{library/random notes-on-reproducibility}@anchor{2a20}
@subsubsection 關於 Reproducibility（復現性）的注意事項


有時，能夠重現偽隨機數產生器給出的序列很有用。只要多執行緒未運行，透過重複使用種子值，同一序列就應該可以被復現。

大多數隨機 module 的演算法和 seed 設定函式在 Python 版本中可能會發生變化，但可以保證兩個方面不會改變：


@itemize *

@item 
如果增加了新的 seed 設定函式，則將提供向後相容的播種器 (seeder)。

@item 
當相容的播種器被賦予相同的種子時，產生器的 @ref{2a1e,,random()} 方法將持續產生相同的序列。
@end itemize

@node 範例<6>,使用方案,關於 Reproducibility（復現性）的注意事項,random --- 產生偽隨機數
@anchor{library/random examples}@anchor{2a21}@anchor{library/random random-examples}@anchor{13dd}
@subsubsection 範例


基礎範例：

@example
>>> random()                          # 隨機浮點數：0.0 <= x < 1.0
0.37444887175646646

>>> uniform(2.5, 10.0)                # 隨機浮點數：2.5 <= x <= 10.0
3.1800146073117523

>>> expovariate(1 / 5)                # 到達間隔平均為 5 秒
5.148957571865031

>>> randrange(10)                     # 0 到 9（含）的整數
7\n

>>> randrange(0, 101, 2)              # 0 到 100（含）的偶數整數
26\n

>>> choice(['win', 'lose', 'draw'])   # 從序列中隨機選取單一元素
'draw'

>>> deck = 'ace two three four'.split()
>>> shuffle(deck)                     # 打亂串列
>>> deck
['four', 'two', 'ace', 'three']

>>> sample([10, 20, 30, 40, 50], k=4) # 四個無重置的樣本
[40, 10, 50, 30]
@end example

模擬：

@example
>>> # 六次輪盤旋轉（有重置的加權抽樣）
>>> choices(['red', 'black', 'green'], [18, 18, 2], k=6)
['red', 'green', 'black', 'black', 'red', 'black']

>>> # 從一副 52 張撲克牌中無重置發 20 張牌
>>> # 並確定具有十點值的牌的比例：十、傑克、王后或國王
>>> deal = sample(['tens', 'low cards'], counts=[16, 36], k=20)
>>> deal.count('tens') / 20
0.15

>>> # 估計從 7 次旋轉中得到 5 次或更多正面的概率
>>> # 使用一枚 60% 概率為正面的偏幣
>>> sum(binomialvariate(n=7, p=0.6) >= 5 for i in range(10_000)) / 10_000
0.4169

>>> # 計算 5 個樣本的中位數位於中間兩個四分位數的概率
>>> 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

統計 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

重新取樣排列測試@footnote{https://en.wikipedia.org/wiki/Resampling_(statistics)#Permutation_tests}的範例，來確定觀察到的藥物與安慰劑之間差異的統計學意義或 p 值@footnote{https://en.wikipedia.org/wiki/P-value}：

@example
# 範例來自 Dennis Shasha 和 Manda Wilson 的 "Statistics is Easy"
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@} 次標籤重新洗牌僅產生 @{count@} 個差異實例')
print(f'至少與觀察到的差異 @{observed_diff:.1f@} 一樣極端。')
print(f'單邊 p 值 @{count / n:.4f@} 使我們拒絕無效假設')
print(f'即藥物與安慰劑之間沒有差異。')
@end example

模擬多伺服器佇列 (queue) 的到達時間與服務交付：

@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  # 每個伺服器可用的時間
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(waits):.1f@}   最大等待時間：@{max(waits):.1f@}')
print('四分位數：', [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} 對市場進行的模擬，顯示了該模組提供的許多工具和分佈（高斯、均勻、樣本、 beta 變數、選擇，三角形、隨機數）的有效使用。

機率的具體介紹（使用Python）@footnote{https://nbviewer.org/url/norvig.com/ipython/Probability.ipynb}為 Peter Norvig@footnote{https://norvig.com/bio.html} 的教學課程，涵蓋了機率理論的基礎知識與如何模擬以及使用 Python 執行數據分析。


@node 使用方案,命令列用法<2>,範例<6>,random --- 產生偽隨機數
@anchor{library/random recipes}@anchor{2a22}
@subsubsection 使用方案


這些使用方案展示了如何有效地從 @ref{85,,itertools} 模組的組合疊代器 (combinatoric iterators) 中進行隨機選擇：

@example
def random_product(*args, repeat=1):
    "從 itertools.product(*args, **kwds) 中隨機選擇"
    pools = [tuple(pool) for pool in args] * repeat
    return tuple(map(random.choice, pools))

def random_permutation(iterable, r=None):
    "從 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):
    "從 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):
    "有重置地選擇 r 個元素。結果按可疊代物件排序。"
    # 結果將在 set(itertools.combinations_with_replacement(iterable, r)) 中
    pool = tuple(iterable)
    n = len(pool)
    indices = sorted(random.choices(range(n), k=r))
    return tuple(pool[i] for i in indices)
@end example

預設的 @ref{947,,random()} 回傳 `0.0 ≤ x < 1.0' 範圍內 2⁻⁵³ 的倍數。所有數字都是均勻分佈的，並且可以完全表示為 Python float。但是，該間隔中的許多其他可表示的 float 不是可能的選擇。 例如 @code{0.05954861408025609} 不是 2⁻⁵³ 的整數倍。

以下範例採用不同的方法。間隔中的所有 float 都是可能的選擇。尾數來自 `2⁵² ≤ 尾數 < 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

Class 中的所有@ref{2a12,,實數分佈}都將使用新方法：

@example
>>> fr = FullRandom()
>>> fr.random()
0.05954861408025609
>>> fr.expovariate(0.25)
8.87925541791544
@end example

該範例在概念上等效於一種演算法，該演算法從 `0.0 ≤ x < 1.0' 範圍內 2⁻¹⁰⁷⁴ 的所有倍數中進行選擇。這些數字都是均勻分佈的，但大多數必須向下捨入到最接近的可表示的 Python float。（2⁻¹⁰⁷⁴ 是最小為正的非正規化 float，等於 @code{math.ulp(0.0)}）


@subsubheading 也參考


產生偽隨機浮點值@footnote{https://allendowney.com/research/rand/downey07randfloat.pdf}  Allen B. Downey 的一篇論文描述了產生比通常由 @ref{947,,random()} 產生的 float 更 fine-grained（細粒的）的方法。


@node 命令列用法<2>,命令列範例,使用方案,random --- 產生偽隨機數
@anchor{library/random command-line-usage}@anchor{2a23}@anchor{library/random random-cli}@anchor{479}
@subsubsection 命令列用法



在 3.13 版被加入.


@code{random} 模組可以從命令列執行。

@example
python -m random [-h] [-c CHOICE [CHOICE ...] | -i N | -f N] [input ...]
@end example

接受以下選項：

@geindex random 命令列選項; -h
@geindex random 命令列選項; --help
@anchor{library/random cmdoption-random-h}@anchor{2a24}@anchor{library/random cmdoption-random-help}@anchor{2a25}
@deffn {Option} @w{-}h, @w{-}@w{-}help

顯示幫助訊息並退出。
@end deffn

@geindex random 命令列選項; -c
@geindex random 命令列選項; --choice
@anchor{library/random cmdoption-random-c}@anchor{2a26}
@deffn {Option} @w{-}c CHOICE [CHOICE ...]
@anchor{library/random cmdoption-random-choice}@anchor{2a27}
@deffnx {Option} @w{-}@w{-}choice CHOICE [CHOICE ...]

列印一個隨機選擇，使用 @ref{1431,,choice()}。
@end deffn

@geindex random 命令列選項; -i
@geindex random 命令列選項; --integer
@anchor{library/random cmdoption-random-i}@anchor{2a28}
@deffn {Option} @w{-}i <N>
@anchor{library/random cmdoption-random-integer}@anchor{2a29}
@deffnx {Option} @w{-}@w{-}integer <N>

列印 1 到 N（含）之間的隨機整數，使用 @ref{1430,,randint()}。
@end deffn

@geindex random 命令列選項; -f
@geindex random 命令列選項; --float
@anchor{library/random cmdoption-random-f}@anchor{2a2a}
@deffn {Option} @w{-}f <N>
@anchor{library/random cmdoption-random-float}@anchor{2a2b}
@deffnx {Option} @w{-}@w{-}float <N>

列印 0 到 N（含）之間的隨機浮點數，使用 @ref{2a13,,uniform()}。
@end deffn

如果未給定選項，則輸出取決於輸入：


@itemize *

@item 
字串或多個：與 @ref{2a27,,--choice} 相同。

@item 
整數：與 @ref{2a29,,--integer} 相同。

@item 
浮點數：與 @ref{2a2b,,--float} 相同。
@end itemize

@node 命令列範例,,命令列用法<2>,random --- 產生偽隨機數
@anchor{library/random command-line-example}@anchor{2a2c}@anchor{library/random random-cli-example}@anchor{2a2d}
@subsubsection 命令列範例


以下是 @code{random} 命令列介面的一些範例：

@example
$ # 隨機選擇一個
$ python -m random egg bacon sausage spam "Lobster Thermidor aux crevettes with a Mornay sauce"
Lobster Thermidor aux crevettes with a Mornay sauce

$ # 隨機整數
$ python -m random 6
6

$ # 隨機浮點數
$ python -m random 1.8
1.7080016272295635

$ # 使用明確的引數
$ 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 --- 數學統計函式,,random --- 產生偽隨機數,數值與數學模組
@anchor{library/statistics doc}@anchor{2a2e}@anchor{library/statistics module-statistics}@anchor{d7}@anchor{library/statistics statistics-mathematical-statistics-functions}@anchor{2a2f}@anchor{library/statistics translation-repo}@anchor{2a30}
@subsection @code{statistics} --- 數學統計函式


@geindex module; statistics


在 3.4 版被加入.


`原始碼：'Lib/statistics.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/statistics.py}

@c from statistics import *
@c import math
@c __name__ = '<doctest>'


__________________________________________________________________


這個模組提供計算數值 (@code{Real}-valued) 資料的數學統計函式。

這個模組並非旨在與 NumPy@footnote{https://numpy.org}、SciPy@footnote{https://scipy.org/} 等第三方函式庫，或者像 Minitab、SAS 和 Matlab 等專門設計給專業統計學家的高階統計軟體互相競爭。此模組的目標在於繪圖和科學計算。

除非特別註明，這些函數支援 @ref{19b,,int}、@ref{196,,float}、@ref{1fe,,Decimal} 以及 @ref{213,,Fraction}。目前不支援其他型別（無論是否為數值型別）。含有混合型別的資料的集合亦是尚未定義，且取決於該型別的實作。若你的輸入資料含有混合型別，你可以考慮使用 @ref{19f,,map()} 來確保結果是一致的，例如：@code{map(float, input_data)}。

有些資料集使用 @code{NaN} （非數）來表示缺漏的資料。由於 NaN 具有特殊的比較語義，在排序資料或是統計出現次數的統計函數中，會引發意料之外或是未定義的行為。受影響的函數包含 @code{median()}、@code{median_low()}、 @code{median_high()}、 @code{median_grouped()}、 @code{mode()}、 @code{multimode()} 以及 @code{quantiles()}。在呼叫這些函數之前，應該先移除 NaN 值：

@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
* 平均值與中央位置量數:: 
* 離度 (spread) 的測量: 離度 spread 的測量. 
* 兩個輸入之間的關係統計:: 
* 函式細節:: 
* 例外: 例外<4>. 
* NormalDist 物件:: 
* 範例與錦囊妙計:: 

@end menu

@node 平均值與中央位置量數,離度 spread 的測量,,statistics --- 數學統計函式
@anchor{library/statistics averages-and-measures-of-central-location}@anchor{2a31}
@subsubsection 平均值與中央位置量數


這些函式計算來自一個母體或樣本的平均值或代表值。


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{8d9,,mean()}

@tab

資料的算術平均數（平均值）。

@item

@ref{c20,,fmean()}

@tab

快速浮點數算數平均數，可調整權重。

@item

@ref{c21,,geometric_mean()}

@tab

資料的幾何平均數。

@item

@ref{ed8,,harmonic_mean()}

@tab

資料的調和平均數。

@item

@ref{54d,,kde()}

@tab

Estimate the probability density distribution of the data.

@item

@ref{54e,,kde_random()}

@tab

Random sampling from the PDF generated by kde().

@item

@ref{2a32,,median()}

@tab

資料的中位數（中間值）。

@item

@ref{2a33,,median_low()}

@tab

資料中較小的中位數。

@item

@ref{2a34,,median_high()}

@tab

資料中較大的中位數。

@item

@ref{2a35,,median_grouped()}

@tab

分組資料的中位數（第 50 百分位數）。

@item

@ref{c7c,,mode()}

@tab

離散 (discrete) 或名目 (nomial) 資料中的眾數（出現次數最多次的值），只回傳一個。

@item

@ref{c22,,multimode()}

@tab

離散或名目資料中的眾數（出現次數最多次的值）組成的 list。

@item

@ref{c23,,quantiles()}

@tab

將資料分成數個具有相等機率的區間，即分位數 (quantile)。

@end multitable


@node 離度 spread 的測量,兩個輸入之間的關係統計,平均值與中央位置量數,statistics --- 數學統計函式
@anchor{library/statistics measures-of-spread}@anchor{2a36}
@subsubsection 離度 (spread) 的測量


這些函式計算母體或樣本偏離平均值的程度。


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{2a37,,pstdev()}

@tab

資料的母體標準差。

@item

@ref{2a38,,pvariance()}

@tab

資料的母體變異數。

@item

@ref{8db,,stdev()}

@tab

資料的樣本標準差。

@item

@ref{8da,,variance()}

@tab

資料的樣本變異數。

@end multitable


@node 兩個輸入之間的關係統計,函式細節,離度 spread 的測量,statistics --- 數學統計函式
@anchor{library/statistics statistics-for-relations-between-two-inputs}@anchor{2a39}
@subsubsection 兩個輸入之間的關係統計


這些函式計算兩個輸入之間的關係統計數據。


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{a2a,,covariance()}

@tab

兩變數的樣本共變異數。

@item

@ref{6dc,,correlation()}

@tab

Pearson 與 Spearman 相關係數 (correlation coefficient)。

@item

@ref{a2b,,linear_regression()}

@tab

簡單線性迴歸的斜率和截距。

@end multitable


@node 函式細節,例外<4>,兩個輸入之間的關係統計,statistics --- 數學統計函式
@anchor{library/statistics function-details}@anchor{2a3a}
@subsubsection 函式細節


註：這些函數並不要求輸入的資料必須排序過。為了閱讀方便，大部份的範例仍已排序過。

@geindex mean() (於 statistics 模組中)
@anchor{library/statistics statistics mean}@anchor{8d9}
@deffn {函式} statistics.mean (data)

回傳 `data' 的樣本算數平均數，輸入可為一個 sequence 或者 iterable。

算數平均數為資料總和除以資料點的數目。他通常被稱為「平均值」，儘管它只是眾多不同的數學平均值之一。它是衡量資料集中位置的一種指標。

若 `data' 為空，則會引發 @ref{2a3b,,StatisticsError}。

使用範例：

@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 備註 
平均值強烈受到離群值 (outliers)@footnote{https://en.wikipedia.org/wiki/Outlier} 的影響，且不一定能當作這些資料點的典型範例。若要使用更穩健但效率較低的集中趨勢 (central tendency)@footnote{https://en.wikipedia.org/wiki/Central_tendency} 度量，請參考 @ref{2a32,,median()}。

樣本平均數提供了對真實母體平均數的不偏估計 (unbiased estimate)，所以從所有可能的樣本中取平均值時，@code{mean(sample)} 會收斂至整個母體的真實平均值。若 `data' 為整個母體而非單一樣本，則 @code{mean(data)} 等同於計算真實的母體平均數 μ。
@end quotation
@end cartouche
@end deffn

@geindex fmean() (於 statistics 模組中)
@anchor{library/statistics statistics fmean}@anchor{c20}
@deffn {函式} statistics.fmean (data, weights=None)

將 `data' 轉換為浮點數並計算其算數平均數。

這個函式運算比 @ref{8d9,,mean()} 更快，並且它總是回傳一個 @ref{196,,float}。`data' 可以是一個 sequence 或者 iterable。如果輸入的資料為空，則引發 @ref{2a3b,,StatisticsError}。

@example
>>> fmean([3.5, 4.0, 5.25])
4.25
@end example

支援選擇性的加權。例如，一位教授以 20% 的比重計算小考分數，20% 的比重計算作業分數，30% 的比重計算期中考試分數，以及 30% 的比重計算期末考試分數：

@example
>>> grades = [85, 92, 83, 91]
>>> weights = [0.20, 0.20, 0.30, 0.30]
>>> fmean(grades, weights)
87.6
@end example

如果有提供 `weights'，它必須與 `data' 長度相同，否則將引發 @ref{2eb,,ValueError}。


在 3.8 版被加入.



在 3.11 版的變更: 新增 `weights' 的支援。

@end deffn

@geindex geometric_mean() (於 statistics 模組中)
@anchor{library/statistics statistics geometric_mean}@anchor{c21}
@deffn {函式} statistics.geometric_mean (data)

將 `data' 轉換成浮點數並計算其幾何平均數。

幾何平均數使用數值的乘積（與之對照，算數平均數使用的是數值的和）來表示 `data' 的集中趨勢或典型值。

若輸入的資料集為空、包含零、包含負值，則引發 @ref{2a3b,,StatisticsError}。`data' 可為 sequence 或者 iterable。

目前沒有特別為了精確結果而特別多下什麼工夫。（然而，未來或許會有。）

@example
>>> round(geometric_mean([54, 24, 36]), 1)
36.0
@end example


在 3.8 版被加入.

@end deffn

@geindex harmonic_mean() (於 statistics 模組中)
@anchor{library/statistics statistics harmonic_mean}@anchor{ed8}
@deffn {函式} statistics.harmonic_mean (data, weights=None)

回傳 `data' 的調和平均數。`data' 可為實數 (real-valued) sequence 或者 iterable。如果省略 `weights' 或者 `weights' 為 @code{None}，則假設各權重相等。

調和平均數是資料的倒數 (reciprocal) 經過 @ref{8d9,,mean()} 運算過後的倒數。例如，三個數 `a'，`b' 與 `c' 的調和平均數等於 @code{3/(1/a + 1/b + 1/c)}。若其中一個值為零，結果將為零。

調和平均數是一種平均數，是衡量資料中心位置的一種方法。它通常用於計算比率 (ratio) 或率 (rate) 的平均，例如速率（speed）。

假設一輛汽車以時速 40 公里的速率行駛 10 公里，然後再以時速 60 公里的速率行駛 10 公里，求汽車的平均速率？

@example
>>> harmonic_mean([40, 60])
48.0
@end example

假設一輛汽車以時速 40 公里的速率行駛 5 公里，然後在交通順暢時，加速到時速 60 公里，以此速度行駛剩下的 30 公里。求汽車的平均速率？

@example
>>> harmonic_mean([40, 60], weights=[5, 30])
56.0
@end example

若 `data' 為空、含有任何小於零的元素、或者加權總和不為正數，則引發 @ref{2a3b,,StatisticsError}。

目前的演算法設計為，若在輸入當中遇到零，則會提前退出。這意味著後續的輸入並未進行有效性檢查。（這種行為在未來可能會改變。）


在 3.6 版被加入.



在 3.10 版的變更: 新增 `weights' 的支援。

@end deffn

@geindex kde() (於 statistics 模組中)
@anchor{library/statistics statistics kde}@anchor{54d}
@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.

若 `data' 為空，則引發 @ref{2a3b,,StatisticsError}。

維基百科有一個範例@footnote{https://en.wikipedia.org/wiki/Kernel_density_estimation#Example}，我們可以使用 @ref{54d,,kde()} 來從一個小樣本生成並繪製估計的機率密度函數：

@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

@code{xarr} 和 @code{yarr} 中的點可用於繪製 PDF 圖：

@image{python-figures/kde_example,,,估計機率密度函式的散點圖 (scatter plot)。,png}


在 3.13 版被加入.

@end deffn

@geindex kde_random() (於 statistics 模組中)
@anchor{library/statistics statistics kde_random}@anchor{54e}
@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.

若 `data' 為空，則引發 @ref{2a3b,,StatisticsError}。

Continuing the example for @ref{54d,,kde()}, we can use
@ref{54e,,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


在 3.13 版被加入.

@end deffn

@geindex median() (於 statistics 模組中)
@anchor{library/statistics statistics median}@anchor{2a32}
@deffn {函式} statistics.median (data)

使用常見的「中間兩數取平均」方法回傳數值資料的中位數 （中間值）。若 `data' 為空，則會引發 @ref{2a3b,,StatisticsError}。`data' 可為一個 sequence 或者 iterable。

中位數是一種穩健的衡量資料中心位置的方法，較不易被離群值影響。當資料點數量為奇數時，會回傳中間的資料點：

@example
>>> median([1, 3, 5])
3
@end example

當資料點數量為偶數時，中位數透過中間兩個值的平均數來插值計算：

@example
>>> median([1, 3, 5, 7])
4.0
@end example

若你的資料為離散資料，並且你不介意中位數可能並非真實的資料點，那這函式適合你。

若你的資料為順序 (ordinal) 資料（支援排序操作）但並非數值型（不支援加法），可以考慮改用 @ref{2a33,,median_low()} 或是 @ref{2a34,,median_high()} 代替。
@end deffn

@geindex median_low() (於 statistics 模組中)
@anchor{library/statistics statistics median_low}@anchor{2a33}
@deffn {函式} statistics.median_low (data)

回傳數值型資料的低中位數 (low median)。若 `data' 為空，則引發 @ref{2a3b,,StatisticsError}。`data' 可為 sequence 或者 iterable。

低中位數一定會在原本的資料集當中。當資料點數量為奇數時，回傳中間值。當數量為偶數時，回傳兩個中間值當中較小的值。

@example
>>> median_low([1, 3, 5])
3
>>> median_low([1, 3, 5, 7])
3
@end example

當你的資料為離散資料，且你希望中位數是實際的資料點而不是插值時，可以用低中位數。
@end deffn

@geindex median_high() (於 statistics 模組中)
@anchor{library/statistics statistics median_high}@anchor{2a34}
@deffn {函式} statistics.median_high (data)

回傳數值型資料的高中位數 (high median)。若 `data' 為空，則引發 @ref{2a3b,,StatisticsError}。`data' 可為 sequence 或者 iterable。

高中位數一定會在原本的資料集當中。當資料點數量為奇數時，回傳中間值。當數量為偶數時，回傳兩個中間值當中較大的值。

@example
>>> median_high([1, 3, 5])
3
>>> median_high([1, 3, 5, 7])
5
@end example

當你的資料為離散資料，且你希望中位數是實際的資料點而不是插值時，可以用高中位數。
@end deffn

@geindex median_grouped() (於 statistics 模組中)
@anchor{library/statistics statistics median_grouped}@anchor{2a35}
@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{2a32,,median()} function would assume that everyone in the
tricenarian age group was exactly 35 years old.  A more tenable
assumption is that the 484 members of that age group are evenly
distributed between 30 and 40.  For that, we use
@ref{2a35,,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{c7c}
@deffn {函式} statistics.mode (data)

回傳離散或名目 `data' 中出現次數最多次的值，只回傳一個。眾數（如果存在）是最典型的值，並用來衡量資料的中心位置。

若有多個出現次數相同的眾數，則回傳在 `data' 中最先出現的眾數。如果希望回傳其中最小或最大的眾數，可以使用 @code{min(multimode(data))} 或 @code{max(multimode(data))}。如果輸入的 `data' 為空，則會引發 @ref{2a3b,,StatisticsError}。

@code{mode} 假定為離散資料，並回傳單一的值。這也是一般學校教授的標準眾數定義：

@example
>>> mode([1, 1, 2, 3, 3, 3, 3, 4])
3
@end example

眾數特別之處在於它是此套件中唯一也適用於名目（非數值型）資料的統計量：

@example
>>> mode(["red", "blue", "blue", "red", "green", "red", "red"])
'red'
@end example

Only hashable inputs are supported.  To handle type @ref{184,,set},
consider casting to @ref{7eb,,frozenset}.  To handle type @ref{24d,,list},
consider casting to @ref{60c,,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 版的變更: 現在，遇到資料中有多個眾數時，會回傳第一個遇到的眾數。在以前，當找到大於一個眾數時，會引發 @ref{2a3b,,StatisticsError}。

@end deffn

@geindex multimode() (於 statistics 模組中)
@anchor{library/statistics statistics multimode}@anchor{c22}
@deffn {函式} statistics.multimode (data)

回傳一個 list，其組成為 `data' 中出現次數最多次的值，並按照它們在 `data' 中首次出現的順序排列。如果有多個眾數，將會回傳所有結果。若 `data' 為空，則回傳空的 list：

@example
>>> multimode('aabbbbccddddeeffffgg')
['b', 'd', 'f']
>>> multimode('@w{'})
[]
@end example


在 3.8 版被加入.

@end deffn

@geindex pstdev() (於 statistics 模組中)
@anchor{library/statistics statistics pstdev}@anchor{2a37}
@deffn {函式} statistics.pstdev (data, mu=None)

回傳母體標準差（即母體變異數的平方根）。有關引數以及其他細節，請參見 @ref{2a38,,pvariance()}。

@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{2a38}
@deffn {函式} statistics.pvariance (data, mu=None)

回傳 `data' 的母體變異數。`data' 可為非空實數 sequence 或者 iterable。變異數，或者以平均數為中心的二階動差，用於衡量資料的變異性（離度或分散程度）。變異數大表示資料分散，變異數小表示資料集中在平均數附近。

若有傳入選擇性的第二個引數 `mu'，該引數應該要是 `data' 的`母體'平均值 (population mean)。它也可以用於計算非以平均值為中心的第二動差。如果沒有傳入此引數或者引數為 @code{None} （預設值），則自動計算資料的算數平均數。

使用此函式來計算整個母體的變異數。如果要從樣本估算變異數，@ref{8da,,variance()} 通常是較好的選擇。

若 `data' 為空，則引發 @ref{2a3b,,StatisticsError}。

範例：

@example
>>> data = [0.0, 0.25, 0.25, 1.25, 1.5, 1.75, 2.75, 3.25]
>>> pvariance(data)
1.25
@end example

如果已經計算出資料的平均值，你可以將其作為選擇性的第二個引數 `mu' 傳遞以避免重新計算：

@example
>>> mu = mean(data)
>>> pvariance(data, mu)
1.25
@end example

支援小數 (decimal) 與分數 (fraction)：

@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 備註 
當在整個母體上呼叫此函式時，會回傳母體變異數 σ²。當在樣本上呼叫此函式時，會回傳有偏差的樣本變異數 s²，也就是具有 N 個自由度的變異數。

若你以某種方式知道真正的母體平均數 μ，你可以將一個已知的母體平均數作為第二個引數提供給此函式，用以計算樣本的變異數。只要資料點是母體的隨機樣本，結果將是母體變異數的不偏估計。
@end quotation
@end cartouche
@end deffn

@geindex stdev() (於 statistics 模組中)
@anchor{library/statistics statistics stdev}@anchor{8db}
@deffn {函式} statistics.stdev (data, xbar=None)

回傳樣本標準差（即樣本變異數的平方根）。有關引數以及其他細節，請參見 @ref{8da,,variance()}。

@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{8da}
@deffn {函式} statistics.variance (data, xbar=None)

回傳 `data' 的樣本變異數。`data' 為兩個值以上的實數 iterable。變異數，或者以平均數為中心的二階動差，用於衡量資料的變異性（離度或分散程度）。變異數大表示資料分散，變異數小表示資料集中在平均數附近。

若有傳入選擇性的第二個引數 `xbar'，它應該是 `data' 的`樣本'平均值 (sample mean)。如果沒有傳入或者為 @code{None} （預設值），則自動計算資料的平均值。

當你的資料是來自母體的樣本時，請使用此函式。若要從整個母體計算變異數，請參見 @ref{2a38,,pvariance()}。

若 `data' 內少於兩個值，則引發 @ref{2a3b,,StatisticsError}。

範例：

@example
>>> data = [2.75, 1.75, 1.25, 0.25, 0.5, 1.25, 3.5]
>>> variance(data)
1.3720238095238095
@end example

如果已經計算出資料的樣本平均值，你可以將其作為選擇性的第二個引數 `mu' 傳遞以避免重新計算：

@example
>>> m = mean(data)
>>> variance(data, m)
1.3720238095238095
@end example

此函式不會驗證你傳入的 `xbar' 是否為實際的平均數。傳入任意的 `xbar' 會導致無效或不可能的結果。

支援小數 (decimal) 與分數 (fraction)：

@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 備註 
這是經過 Bessel 校正 (Bessel's correction) 後的樣本變異數 s² ，又稱為自由度為 N-1 的變異數。只要資料點具有代表性（例如：獨立且具有相同分布），結果應該會是對真實母體變異數的不偏估計。

若你剛好知道真正的母體平均數 μ，你應該將其作為 `mu' 參數傳入 @ref{2a38,,pvariance()} 函式來計算樣本變異數。
@end quotation
@end cartouche
@end deffn

@geindex quantiles() (於 statistics 模組中)
@anchor{library/statistics statistics quantiles}@anchor{c23}
@deffn {函式} statistics.quantiles (data, *, n=4, method='exclusive')

將 `data' 分成 `n' 個具有相等機率的連續區間。回傳一個包含 @code{n - 1} 個用於切分各區間的分隔點的 list。

將 `n' 設為 4 以表示四分位數 (quartile) （預設值）。將 `n' 設置為 100 表示百分位數 (percentile)，這將給出 99 個分隔點將 `data' 分成 100 個大小相等的組。如果 `n' 不是至少為 1，則引發 @ref{2a3b,,StatisticsError}。

`data' 可以是包含樣本資料的任何 iterable。為了取得有意義的結果，`data' 中的資料點數量應大於 `n'。如果連一個資料點都沒有，則引發 @ref{2a3b,,StatisticsError}。

分隔點是從兩個最近的資料點線性內插值計算出來的。舉例來說，如果分隔點落在兩個樣本值 @code{100} 與 @code{112} 之間的距離三分之一處，則分隔點的值將為 @code{104}。

計算分位數的 `method' 可以根據 `data' 是否包含或排除來自母體的最小與最大可能的值而改變。

預設的 `method' 是 "exclusive"，用於從可能找到比樣本更極端的值的母體中抽樣的樣本資料。對於 `m' 個已排序的資料點，計算出低於 `i-th' 的部分為 @code{i / (m + 1)}。給定九個樣本資料，此方法將對資料排序且計算下列百分位數：10%、20%、30%、40%、50%、60%、70%、80%、90%。

若將 `method' 設為 "inclusive"，則用於描述母體或者已知包含母體中最極端值的樣本資料。在 `data' 中的最小值被視為第 0 百分位數，最大值為第 100 百分位數。對於 `m' 個已排序的資料點，計算出低於 `i-th' 的部分為 @code{(i - 1) / (m - 1)}。給定十一個個樣本資料，此方法將對資料排序且計算下列百分位數：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


在 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{a2a}
@deffn {函式} statistics.covariance (x, y, /)

回傳兩輸入 `x' 與 `y' 的樣本共變異數 (sample covariance)。共變異數是衡量兩輸入的聯合變異性 (joint variability) 的指標。

兩輸入必須具有相同長度（至少兩個），否則會引發 @ref{2a3b,,StatisticsError}。

範例：

@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


在 3.10 版被加入.

@end deffn

@geindex correlation() (於 statistics 模組中)
@anchor{library/statistics statistics correlation}@anchor{6dc}
@deffn {函式} statistics.correlation (x, y, /, *, method='linear')

回傳兩輸入的 Pearson 相關係數 (Pearson’s correlation coefficient)@footnote{https://en.wikipedia.org/wiki/Pearson_correlation_coefficient}。Pearson 相關係數 `r' 的值介於 -1 與 +1 之間。它衡量線性關係的強度與方向。

如果 `method' 為 "ranked"，則計算兩輸入的 Spearman 等級相關係數 (Spearman’s rank correlation coefficient)@footnote{https://en.wikipedia.org/wiki/Spearman%27s_rank_correlation_coefficient}。資料將被取代為等級。平手的情況則取平均，令相同的值排名也相同。所得係數衡量單調關係 (monotonic relationship) 的強度。

Spearman 相關係數適用於順序型資料，或者不符合 Pearson 相關係數要求的線性比例關係的連續型 (continuous) 資料。

兩輸入必須具有相同長度（至少兩個），且不須為常數，否則會引發 @ref{2a3b,,StatisticsError}。

以 Kepler 行星運動定律@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


在 3.10 版被加入.



在 3.12 版的變更: 新增了對 Spearman 等級相關係數的支援。

@end deffn

@geindex linear_regression() (於 statistics 模組中)
@anchor{library/statistics statistics linear_regression}@anchor{a2b}
@deffn {函式} statistics.linear_regression (x, y, /, *, proportional=False)

回傳使用普通最小平方法 (ordinary least square) 估計出的簡單線性迴歸 (simple linear regression)@footnote{https://en.wikipedia.org/wiki/Simple_linear_regression} 參數中的斜率 (slope) 與截距 (intercept)。簡單線性迴歸描述自變數 (independent variable) `x' 與應變數 (dependent variable) `y' 之間的關係，用以下的線性函式表示：

@quotation

`y = slope * x + intercept + noise'
@end quotation

其中 @code{slope} 和 @code{intercept} 是被估計的迴歸參數，而 @code{noise} 表示由線性迴歸未解釋的資料變異性（它等於應變數的預測值與實際值之差）。

兩輸入必須具有相同長度（至少兩個），且自變數 `x' 不得為常數，否則會引發 @ref{2a3b,,StatisticsError}。

舉例來說，我們可以使用 Monty Python 系列電影的上映日期@footnote{https://en.wikipedia.org/wiki/Monty_Python#Films}來預測至 2019 年為止，假設他們保持固定的製作速度，應該會產生的 Monty Python 電影的累計數量。

@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

若將 `proportional' 設為 True，則假設自變數 `x' 與應變數 `y' 是直接成比例的，資料座落在通過原點的一直線上。由於 `intercept' 始終為 0.0，因此線性函式可簡化如下：

@quotation

`y = slope * x + noise'
@end quotation

繼續 @ref{6dc,,correlation()} 中的範例，我們看看基於主要行星的模型可以如何很好地預測矮行星的軌道距離：

@example
>>> model = linear_regression(period_squared, dist_cubed, proportional=True)
>>> slope = model.slope

>>> # 矮行星：          冥王星、  鬩神星、  鳥神星、  妊神星、  穀神星
>>> orbital_periods = [90_560, 204_199, 111_845, 103_410, 1_680]  # 天數
>>> 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]  # 以百萬公里為單位的實際距離
[5906, 10152, 6796, 6450, 414]
@end example


在 3.10 版被加入.



在 3.11 版的變更: 新增 `proportional' 的支援。

@end deffn

@node 例外<4>,NormalDist 物件,函式細節,statistics --- 數學統計函式
@anchor{library/statistics exceptions}@anchor{2a3c}
@subsubsection 例外


定義了一個單一的例外：

@geindex StatisticsError
@anchor{library/statistics statistics StatisticsError}@anchor{2a3b}
@deffn {例外} statistics.StatisticsError

@ref{2eb,,ValueError} 的子類別，用於和統計相關的例外。
@end deffn

@node NormalDist 物件,範例與錦囊妙計,例外<4>,statistics --- 數學統計函式
@anchor{library/statistics normaldist-objects}@anchor{2a3d}
@subsubsection @code{NormalDist} 物件


@ref{c24,,NormalDist} 是一種用於建立與操作隨機變數 (random variable)@footnote{http://www.stat.yale.edu/Courses/1997-98/101/ranvar.htm} 的常態分布的工具。它是一個將量測資料的平均數與標準差視為單一實體的類別。

常態分布源自於中央極限定理 (Central Limit Theorem)@footnote{https://en.wikipedia.org/wiki/Central_limit_theorem}，在統計學中有著廣泛的應用。

@geindex NormalDist (statistics 中的類別)
@anchor{library/statistics statistics NormalDist}@anchor{c24}
@deffn {類別} statistics.NormalDist (mu=0.0, sigma=1.0)

此方法會回傳一個新 `NormalDist' 物件，其中 `mu' 代表算數平均數@footnote{https://en.wikipedia.org/wiki/Arithmetic_mean}而 `sigma' 代表標準差@footnote{https://en.wikipedia.org/wiki/Standard_deviation}。

若 `sigma' 為負值，則引發 @ref{2a3b,,StatisticsError}。

@geindex mean (statistics.NormalDist 的屬性)
@anchor{library/statistics statistics NormalDist mean}@anchor{2a3e}
@deffn {屬性} mean

常態分布中的算數平均數@footnote{https://en.wikipedia.org/wiki/Arithmetic_mean}唯讀屬性。
@end deffn

@geindex median (statistics.NormalDist 的屬性)
@anchor{library/statistics statistics NormalDist median}@anchor{2a3f}
@deffn {屬性} median

常態分布中的中位數@footnote{https://en.wikipedia.org/wiki/Median}唯讀屬性。
@end deffn

@geindex mode (statistics.NormalDist 的屬性)
@anchor{library/statistics statistics NormalDist mode}@anchor{2a40}
@deffn {屬性} mode

常態分布中的眾數@footnote{https://en.wikipedia.org/wiki/Mode_(statistics)}唯讀屬性。
@end deffn

@geindex stdev (statistics.NormalDist 的屬性)
@anchor{library/statistics statistics NormalDist stdev}@anchor{2a41}
@deffn {屬性} stdev

常態分布中的標準差@footnote{https://en.wikipedia.org/wiki/Standard_deviation}唯讀屬性。
@end deffn

@geindex variance (statistics.NormalDist 的屬性)
@anchor{library/statistics statistics NormalDist variance}@anchor{2a42}
@deffn {屬性} variance

常態分布中的變異數@footnote{https://en.wikipedia.org/wiki/Variance}唯讀屬性。
@end deffn

@geindex from_samples() (statistics.NormalDist 的類別方法)
@anchor{library/statistics statistics NormalDist from_samples}@anchor{2a43}
@deffn {方法} classmethod from_samples (data)

利用 @ref{c20,,fmean()} 與 @ref{8db,,stdev()} 函式，估計 `data' 的 `mu' 與 `sigma' 參數，建立一個常態分布的實例。

`data' 可以是任何 @ref{1428,,iterable}，並應包含可以轉換為 @ref{196,,float} 的值。若 `data' 沒有包含至少兩個以上的元素在內，則引發 @ref{2a3b,,StatisticsError}，因為至少需要一個點來估計中央值且至少需要兩個點來估計分散情形。
@end deffn

@geindex samples() (statistics.NormalDist 的方法)
@anchor{library/statistics statistics NormalDist samples}@anchor{2a44}
@deffn {方法} samples (n, *, seed=None)

給定平均值與標準差，產生 `n' 個隨機樣本。回傳一個由 @ref{196,,float} 組成的 @ref{24d,,list}。

若有給定 `seed'，則會建立一個以此為基礎的亂數產生器實例。這對於建立可重現的結果很有幫助，即使在多執行緒情境下也是如此。


在 3.13 版的變更.


Switched to a faster algorithm.  To reproduce samples from previous
versions, use @ref{1474,,random.seed()} and @ref{1af8,,random.gauss()}.
@end deffn

@geindex pdf() (statistics.NormalDist 的方法)
@anchor{library/statistics statistics NormalDist pdf}@anchor{2a45}
@deffn {方法} pdf (x)

利用機率密度函數 (probability density function@comma{} pdf)@footnote{https://en.wikipedia.org/wiki/Probability_density_function} 計算隨機變數 `X' 接近給定值 `x' 的相對概度 (relative likelihood)。數學上，它是比率 @code{P(x <= X < x+dx) / dx} 在 `dx' 趨近於零時的極限值。

相對概度是樣本出現在狹窄範圍的機率，除以該範圍的寬度（故稱為「密度」）計算而得。由於概度是相對於其它點，故其值可大於 @code{1.0}。
@end deffn

@geindex cdf() (statistics.NormalDist 的方法)
@anchor{library/statistics statistics NormalDist cdf}@anchor{17d1}
@deffn {方法} cdf (x)

利用累積分布函式 (cumulative distribution function@comma{} cdf)@footnote{https://en.wikipedia.org/wiki/Cumulative_distribution_function} 計算隨機變數 `X' 小於或等於 `x' 的機率。數學上，它記為 @code{P(X <= x)}。
@end deffn

@geindex inv_cdf() (statistics.NormalDist 的方法)
@anchor{library/statistics statistics NormalDist inv_cdf}@anchor{2a46}
@deffn {方法} inv_cdf (p)

計算反累計分布函式 (inverse cumulative distribution function)，也稱為分位數函式 (quantile function)@footnote{https://en.wikipedia.org/wiki/Quantile_function} 或者百分率點 (percent-point)@footnote{https://web.archive.org/web/20190203145224/https://www.statisticshowto.datasciencecentral.com/inverse-distribution-function/} 函式。數學上記為 @code{x : P(X <= x) = p}。

找出一個值 `x'，使得隨機變數 `X' 小於或等於該值的機率等於給定的機率 `p'。
@end deffn

@geindex overlap() (statistics.NormalDist 的方法)
@anchor{library/statistics statistics NormalDist overlap}@anchor{2a47}
@deffn {方法} overlap (other)

衡量兩常態分布之間的一致性。回傳一個介於 0.0 與 1.0 之間的值，表示兩機率密度函式的重疊區域@footnote{https://www.rasch.org/rmt/rmt101r.htm}。
@end deffn

@geindex quantiles() (statistics.NormalDist 的方法)
@anchor{library/statistics statistics NormalDist quantiles}@anchor{2a48}
@deffn {方法} quantiles (n=4)

將常態分布分割成 `n' 個具有相等機率的連續區間。回傳一個 list，包含 (n-1) 個切割區間的分隔點。

將 `n' 設定為 4 表示四分位數（預設值）。將 `n' 設定為 10 表示十分位數。將 `n' 設定為 100 表示百分位數，這會產生 99 個分隔點，將常態分布切割成大小相等的群組。
@end deffn

@geindex zscore() (statistics.NormalDist 的方法)
@anchor{library/statistics statistics NormalDist zscore}@anchor{2a49}
@deffn {方法} zscore (x)

計算標準分數 (Standard Score)@footnote{https://www.statisticshowto.com/probability-and-statistics/z-score/}，用以描述在常態分布中，`x' 高出或低於平均數幾個標準差：@code{(x - mean) / stdev}。


在 3.9 版被加入.

@end deffn

@ref{c24,,NormalDist} 的實例支援對常數的加法、減法、乘法與除法。這些操作用於平移與縮放。例如：

@example
>>> temperature_february = NormalDist(5, 2.5)             # 攝氏
>>> temperature_february * (9/5) + 32                     # 華氏
NormalDist(mu=41.0, sigma=4.5)
@end example

不支援將常數除以 @ref{c24,,NormalDist} 的實例，因為結果將不符合常態分布。

由於常態分布源自於自變數的加法效應 (additive effects)，因此可以將兩個獨立的常態分布隨機變數相加與相減@footnote{https://en.wikipedia.org/wiki/Sum_of_normally_distributed_random_variables}，並且表示為 @ref{c24,,NormalDist} 的實例。例如：

@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


在 3.8 版被加入.

@end deffn

@node 範例與錦囊妙計,,NormalDist 物件,statistics --- 數學統計函式
@anchor{library/statistics examples-and-recipes}@anchor{2a4a}
@subsubsection 範例與錦囊妙計


@menu
* 經典機率問題:: 
* 用於模擬的蒙地卡羅 (Monte Carlo) 輸入: 用於模擬的蒙地卡羅 Monte Carlo 輸入. 
* 近似二項分布:: 
* 單純貝氏分類器 (Naive bayesian classifier): 單純貝氏分類器 Naive bayesian classifier. 

@end menu

@node 經典機率問題,用於模擬的蒙地卡羅 Monte Carlo 輸入,,範例與錦囊妙計
@anchor{library/statistics classic-probability-problems}@anchor{2a4b}
@subsubsection 經典機率問題


@ref{c24,,NormalDist} 可以輕易地解決經典的機率問題。

例如，給定 SAT 測驗的歷史資料@footnote{https://nces.ed.gov/programs/digest/d17/tables/dt17_226.40.asp}，顯示成績為平均 1060、標準差 195 的常態分布。我們要求出分數在 1100 與 1200 之間（四捨五入至最接近的整數）的學生的百分比：

@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

找出 SAT 分數的四分位數@footnote{https://en.wikipedia.org/wiki/Quartile}以及十分位數@footnote{https://en.wikipedia.org/wiki/Decile}：

@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 輸入,近似二項分布,經典機率問題,範例與錦囊妙計
@anchor{library/statistics monte-carlo-inputs-for-simulations}@anchor{2a4c}
@subsubsection 用於模擬的蒙地卡羅 (Monte Carlo) 輸入


欲估計一個不易透過解析方法求解的模型的分布，@ref{c24,,NormalDist} 可以產生輸入樣本以進行蒙地卡羅模擬@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 近似二項分布,單純貝氏分類器 Naive bayesian classifier,用於模擬的蒙地卡羅 Monte Carlo 輸入,範例與錦囊妙計
@anchor{library/statistics approximating-binomial-distributions}@anchor{2a4d}
@subsubsection 近似二項分布


當樣本數量夠大，且試驗成功的機率接近 50%，可以使用常態分布來近似二項分布 (Binomial distributions)@footnote{https://mathworld.wolfram.com/BinomialDistribution.html}。

例如，一場有 750 位參加者的開源研討會中，有兩間可容納 500 人的會議室。一場是關於 Python 的講座，另一場則是關於 Ruby 的。在過去的會議中，有 65% 的參加者傾向參與 Python 講座。假設參與者的偏好沒有改變，那麼 Python 會議室未超過自身容量限制的機率是？

@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,,近似二項分布,範例與錦囊妙計
@anchor{library/statistics naive-bayesian-classifier}@anchor{2a4e}
@subsubsection 單純貝氏分類器 (Naive bayesian classifier)


常態分布常在機器學習問題中出現。

維基百科有個 Naive Bayesian Classifier 的優良範例@footnote{https://en.wikipedia.org/wiki/Naive_Bayes_classifier#Person_classification}。課題為從身高、體重與鞋子尺寸等符合常態分布的特徵量測值中判斷一個人的性別。

給定一組包含八個人的量測值的訓練資料集。假設這些量測值服從常態分布，我們可以利用 @ref{c24,,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

接著，我們遇到一個新的人，他的特徵量測值已知，但性別未知：

@example
>>> ht = 6.0        # height
>>> wt = 130        # weight
>>> fs = 8          # foot size
@end example

從可能為男性或女性的 50% 先驗機率 (prior probability)@footnote{https://en.wikipedia.org/wiki/Prior_probability} 為開端，我們將後驗機率 (posterior probability) 計算為先驗機率乘以給定性別下，各特徵量測值的概度乘積：

@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

最終的預測結果將取決於最大的後驗機率。這被稱為最大後驗機率 (maximum a posteriori)@footnote{https://en.wikipedia.org/wiki/Maximum_a_posteriori_estimation} 或者 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 函式程式設計模組,檔案與目錄存取,數值與數學模組,Python 標準函式庫 Standard Library
@anchor{library/functional doc}@anchor{2a4f}@anchor{library/functional functional-programming-modules}@anchor{2a50}@anchor{library/functional translation-repo}@anchor{2a51}
@section 函式程式設計模組


本章節所描述的模組提供了支援函式程式設計風格的函式和類別，以及對可呼叫物件的一般操作。

本章包含下列的模組：

@menu
* itertools: itertools --- 建立產生高效率迴圈之疊代器的函式. 建立產生高效率迴圈之疊代器的函式
* functools: functools --- 可呼叫物件上的高階函式與操作. 可呼叫物件上的高階函式與操作
* operator: operator --- 標準運算子替代函式. 標準運算子替代函式

@end menu

@node itertools --- 建立產生高效率迴圈之疊代器的函式,functools --- 可呼叫物件上的高階函式與操作,,函式程式設計模組
@anchor{library/itertools doc}@anchor{2a52}@anchor{library/itertools itertools-functions-creating-iterators-for-efficient-looping}@anchor{2a53}@anchor{library/itertools module-itertools}@anchor{85}
@subsection @code{itertools} --- 建立產生高效率迴圈之疊代器的函式


@geindex module; itertools

@c from itertools import *
@c import collections
@c import math
@c import operator
@c import random


__________________________________________________________________


這個模組實作了許多 @ref{4c3,,疊代器 (iterator)} 構建塊 (building block)，其靈感來自 APL、Haskell 和 SML 的結構。每個構建塊都以適合 Python 的形式來重新設計。

這個模組標準化了快速且高效率利用記憶體的核心工具集，這些工具本身或組合使用都很有用。它們共同構成了一個「疊代器代數 (iterator algebra)」，使得在純 Python 中簡潔且高效地建構專用工具成為可能。

例如，SML 提供了一個造表工具：@code{tabulate(f)}，它產生一個序列 @code{f(0), f(1), ...}。在 Python 中，可以透過結合 @ref{19f,,map()} 和 @ref{1484,,count()} 組成 @code{map(f, count())} 以達到同樣的效果。

`無限疊代器：'


@multitable {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

疊代器

@tab

引數

@tab

結果

@tab

範例

@item

@ref{1484,,count()}

@tab

[start[, step]]

@tab

start, start+step, start+2*step, ...

@tab

@code{count(10) → 10 11 12 13 14 ...}

@item

@ref{2a54,,cycle()}

@tab

p

@tab

p0, p1, ... plast, p0, p1, ...

@tab

@code{cycle('ABCD') → A B C D A B C D ...}

@item

@ref{17d9,,repeat()}

@tab

elem [,n]

@tab

elem, elem, elem，... 重複無限次或 n 次

@tab

@code{repeat(10, 3) → 10 10 10}

@end multitable


`在最短輸入序列 (shortest input sequence) 處終止的疊代器：'


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

疊代器

@tab

引數

@tab

結果

@tab

範例

@item

@ref{be7,,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{50c,,batched()}

@tab

p, n

@tab

(p0, p1, ..., p_n-1), ...

@tab

@code{batched('ABCDEFG', n=2) → AB CD EF G}

@item

@ref{248b,,chain()}

@tab

p, q, ...

@tab

p0, p1, ... plast, q0, q1, ...

@tab

@code{chain('ABC', 'DEF') → A B C D E F}

@item

@ref{2a55,,chain.from_iterable()}

@tab

可疊代物件

@tab

p0, p1, ... plast, q0, q1, ...

@tab

@code{chain.from_iterable(['ABC', 'DEF']) → A B C D E F}

@item

@ref{1483,,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{2a56,,dropwhile()}

@tab

predicate, seq

@tab

seq[n], seq[n+1]，當 predicate 失敗時開始

@tab

@code{dropwhile(lambda x: x<5, [1,4,6,3,8]) → 6 3 8}

@item

@ref{2477,,filterfalse()}

@tab

predicate, seq

@tab

當 predicate(elem) 失敗時 seq 的元素

@tab

@code{filterfalse(lambda x: x<5, [1,4,6,3,8]) → 6 8}

@item

@ref{2a57,,groupby()}

@tab

iterable[, key]

@tab

根據 key(v) 的值分組的子疊代器

@tab

@code{groupby(['A','B','DEF'], len) → (1, A B) (3, DEF)}

@item

@ref{d3b,,islice()}

@tab

seq, [start,] stop [, step]

@tab

seq[start:stop:step] 的元素

@tab

@code{islice('ABCDEFG', 2, None) → C D E F G}

@item

@ref{a0f,,pairwise()}

@tab

可疊代物件

@tab

(p[0], p[1]), (p[1], p[2])

@tab

@code{pairwise('ABCDEFG') → AB BC CD DE EF FG}

@item

@ref{12e5,,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{2a58,,takewhile()}

@tab

predicate, seq

@tab

seq[0], seq[1]，直到 predicate 失敗

@tab

@code{takewhile(lambda x: x<5, [1,4,6,3,8]) → 1 4}

@item

@ref{2a59,,tee()}

@tab

it, n

@tab

it1, it2, ... itn，將一個疊代器分成 n 個

@tab

@code{tee('ABC', 2) → A B C, A B C}

@item

@ref{149f,,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


`組合疊代器：'


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

疊代器

@tab

引數

@tab

結果

@item

@ref{1513,,product()}

@tab

p, q, ... [repeat=1]

@tab

笛卡爾乘積 (cartesian product)，相當於巢狀的 for 迴圈

@item

@ref{1bcf,,permutations()}

@tab

p[, r]

@tab

長度為 r 的元組，所有可能的定序，無重複元素

@item

@ref{1512,,combinations()}

@tab

p, r

@tab

長度為 r 的元組，按照排序過後的定序，無重複元素

@item

@ref{1482,,combinations_with_replacement()}

@tab

p, r

@tab

長度為 r 的元組，按照排序過後的定序，有重複元素

@end multitable



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

範例

@tab

結果

@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 函式:: 
* Itertools 應用技巧:: 

@end menu

@node Itertool 函式,Itertools 應用技巧,,itertools --- 建立產生高效率迴圈之疊代器的函式
@anchor{library/itertools itertool-functions}@anchor{2a5a}@anchor{library/itertools itertools-functions}@anchor{2a5b}
@subsubsection Itertool 函式


以下的函式都會建構並回傳疊代器。一些函式提供無限長度的串流 (stream)，因此應僅由截斷串流的函式或迴圈來存取它們。

@geindex accumulate() (於 itertools 模組中)
@anchor{library/itertools itertools accumulate}@anchor{be7}
@deffn {函式} itertools.accumulate (iterable[, function, *, initial=None])

建立一個回傳累積和的疊代器，或其他二進位函式的累積結果。

`function' 預設為加法。`function' 應接受兩個引數，即累積總和和來自 `iterable' 的值。

如果提供了 `initial' 值，則累積將從該值開始，並且輸出的元素數將比輸入的可疊代物件多一個。

大致等價於：

@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

`function' 引數可以被設定為 @ref{1106,,min()} 以得到連續的最小值，設定為 @ref{1107,,max()} 以得到連續的最大值，或者設定為 @ref{2a5c,,operator.mul()} 以得到連續的乘積。也可以透過累積利息和付款來建立攤銷表 (Amortization tables)@footnote{https://www.ramseysolutions.com/real-estate/amortization-schedule} ：

@example
>>> data = [3, 4, 6, 2, 1, 9, 0, 7, 5, 8]
>>> list(accumulate(data, max))              # 運行最大值
[3, 4, 6, 6, 6, 9, 9, 9, 9, 9]
>>> list(accumulate(data, operator.mul))     # 運行乘積
[3, 12, 72, 144, 144, 1296, 0, 0, 0, 0]

# 攤銷一筆 1000 的 5% 貸款，分 10 年、每年支付 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

可參見 @ref{21a,,functools.reduce()}，其是個類似的函式，但僅回傳最終的累積值。


在 3.2 版被加入.



在 3.3 版的變更: 新增可選的 `function' 參數。



在 3.8 版的變更: 新增可選的 `initial' 參數。

@end deffn

@geindex batched() (於 itertools 模組中)
@anchor{library/itertools itertools batched}@anchor{50c}
@deffn {函式} itertools.batched (iterable, n, *, strict=False)

將來自 `iterable' 的資料分批為長度為 `n' 的元組。最後一個批次可能比 `n' 短。

如果 `strict' 為真，則當最後一個批次比 `n' 短時，會引發 @ref{2eb,,ValueError}。

對輸入的可疊代物件進行迴圈，並將資料累積到大小為 `n' 的元組中。輸入是惰性地被消耗 (consumed lazily) 的，會剛好足夠填充一批的資料。一旦批次填滿或輸入的可疊代物件耗盡，就會 yield 出結果：

@example
>>> flattened_data = ['roses', 'red', 'violets', 'blue', 'sugar', 'sweet']
>>> unflattened = list(batched(flattened_data, 2))
>>> unflattened
[('roses', 'red'), ('violets', 'blue'), ('sugar', 'sweet')]
@end example

大致等價於：

@example
def batched(iterable, n, *, strict=False):
    # batched('ABCDEFG', 2) → AB CD EF 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


在 3.12 版被加入.



在 3.13 版的變更: 新增 `strict' 選項。

@end deffn

@geindex chain() (於 itertools 模組中)
@anchor{library/itertools itertools chain}@anchor{248b}
@deffn {函式} itertools.chain (*iterables)

建立一個疊代器，從第一個可疊代物件回傳元素直到其耗盡，然後繼續處理下一個可疊代物件，直到所有可疊代物件都耗盡。這將多個資料來源結合為單一個疊代器。大致等價於：

@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{2a55}
@deffn {方法} classmethod chain.from_iterable (iterable)

@ref{248b,,chain()} 的另一個建構函式。從單個可疊代的引數中得到鏈接的輸入，該引數是惰性計算的。大致等價於：

@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{1512}
@deffn {函式} itertools.combinations (iterable, r)

從輸入 `iterable' 中回傳長度為 `r' 的元素的子序列。

輸出是 @ref{1513,,product()} 的子序列，僅保留作為 `iterable' 子序列的條目。輸出的長度由 @ref{8d7,,math.comb()} 給定，當 @code{0 ≤ r ≤ n} 時，長度為 @code{n! / r! / (n - r)!}，當 @code{r > n} 時為零。

根據輸入值 `iterable' 的順序，組合的元組會按照字典順序輸出。如果輸入的 `iterable' 已經排序，則輸出的元組也將按排序的順序產生。

元素是根據它們的位置（而非值）來決定其唯一性。如果輸入的元素都是獨特的，則每個組合內將不會有重複的值。

大致等價於：

@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{1482}
@deffn {函式} itertools.combinations_with_replacement (iterable, r)

回傳來自輸入 `iterable' 的長度為 `r' 的子序列，且允許個別元素重複多次。

其輸出是一個 @ref{1513,,product()} 的子序列，僅保留作為 `iterable' 子序列（可能有重複元素）的條目。當 @code{n > 0} 時，回傳的子序列數量為 @code{(n + r - 1)! / r! / (n - 1)!}。

根據輸入值 `iterable' 的順序，組合的元組會按照字典順序輸出。如果輸入的 `iterable' 已經排序，則輸出的元組也將按排序的順序產生。

元素是根據它們的位置（而非值）來決定其唯一性。如果輸入的元素都是獨特的，生成的組合也將是獨特的。

大致等價於：

@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


在 3.1 版被加入.

@end deffn

@geindex compress() (於 itertools 模組中)
@anchor{library/itertools itertools compress}@anchor{1483}
@deffn {函式} itertools.compress (data, selectors)

建立一個疊代器，回傳 `data' 中對應 `selectors' 的元素為 true 的元素。當 `data' 或 `selectors' 可疊代物件耗盡時停止。大致等價於：

@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


在 3.1 版被加入.

@end deffn

@geindex count() (於 itertools 模組中)
@anchor{library/itertools itertools count}@anchor{1484}
@deffn {函式} itertools.count (start=0, step=1)

建立一個疊代器，回傳從 `start' 開始的等差的值。可以與 @ref{19f,,map()} 一起使用來產生連續的資料點，或與 @ref{1a0,,zip()} 一起使用來增加序列號。大致等價於：

@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

當用浮點數計數時，將上述程式碼替換為乘法有時可以獲得更好的精確度，例如：@code{(start + step * i for i in count())}。


在 3.1 版的變更: 新增 `step' 引數並允許非整數引數。

@end deffn

@geindex cycle() (於 itertools 模組中)
@anchor{library/itertools itertools cycle}@anchor{2a54}
@deffn {函式} itertools.cycle (iterable)

建立一個疊代器，回傳 `iterable' 中的元素並保存每個元素的副本。當可疊代物件耗盡時，從保存的副本中回傳元素。會無限次的重複。大致等價於：

@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

此 itertool 可能需要大量的輔助儲存空間（取決於可疊代物件的長度）。
@end deffn

@geindex dropwhile() (於 itertools 模組中)
@anchor{library/itertools itertools dropwhile}@anchor{2a56}
@deffn {函式} itertools.dropwhile (predicate, iterable)

建立一個疊代器，在 `predicate' 為 true 時丟棄 `iterable' 中的元素，之後回傳每個元素。大致等價於：

@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

注意，在 predicate 首次變為 False 之前，這不會產生`任何'輸出，所以此 itertool 可能會有較長的啟動時間。
@end deffn

@geindex filterfalse() (於 itertools 模組中)
@anchor{library/itertools itertools filterfalse}@anchor{2477}
@deffn {函式} itertools.filterfalse (predicate, iterable)

建立一個疊代器，過濾 `iterable' 中的元素，僅回傳 `predicate' 為 False 值的元素。如果 `predicate' 是 @code{None}，則回傳為 False 的項目。大致等價於：

@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{2a57}
@deffn {函式} itertools.groupby (iterable, key=None)

建立一個疊代器，回傳 `iterable' 中連續的鍵和群組。`key' 是一個為每個元素計算鍵值的函式。如果其未指定或為 @code{None}，則 `key' 預設為一個識別性函式 (identity function)，並回傳未被更改的元素。一般來說，可疊代物件需要已經用相同的鍵函式進行排序。

@ref{2a57,,groupby()} 的操作類似於 Unix 中的 @code{uniq} 過濾器。每當鍵函式的值發生變化時，它會產生一個 break 或新的群組（這就是為什麼通常需要使用相同的鍵函式對資料進行排序）。這種行為不同於 SQL 的 GROUP BY，其無論輸入順序如何都會聚合相同的元素。

回傳的群組本身是一個與 @ref{2a57,,groupby()} 共享底層可疊代物件的疊代器。由於來源是共享的，當 @ref{2a57,,groupby()} 物件前進時，前一個群組將不再可見。因此，如果之後需要該資料，應將其儲存為串列：

@example
groups = []
uniquekeys = []
data = sorted(data, key=keyfunc)
for k, g in groupby(data, keyfunc):
    groups.append(list(g))      # 將群組疊代器儲存為串列
    uniquekeys.append(k)
@end example

@ref{2a57,,groupby()} 大致等價於：

@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{d3b}
@deffn {函式} itertools.islice (iterable, stop)

@deffnx {函式} itertools.islice (iterable, start, stop[, step])

建立一個疊代器，回傳從 iterable 中選取的元素。其作用類似於序列切片 (sequence slicing)，但不支援負數的 `start'、`stop' 或 `step' 的值。

如果 `start' 為零或 @code{None}，則從零開始疊代。否則在達到 `start' 之前，會跳過 iterable 中的元素。

如果 `stop' 為 @code{None}，則疊代將繼續前進直到輸入耗盡。如果指定了 `stop'，則在達到指定位置時停止。

如果 `step' 為 @code{None}，則步長 (step) 預設為一。元素會連續回傳，除非將 `step' 設定為大於一，這會導致一些項目被跳過。

大致等價於：

@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

若輸入為疊代器，則完整耗盡 `islice' 會使輸入的疊代器向前移動 @code{max(start, stop)} 步，與 `step' 的值無關。
@end deffn

@geindex pairwise() (於 itertools 模組中)
@anchor{library/itertools itertools pairwise}@anchor{a0f}
@deffn {函式} itertools.pairwise (iterable)

回傳從輸入的 `iterable' 中提取的連續重疊對。

輸出疊代器中的 2 元組數量將比輸入少一個。如果輸入的可疊代物件中的值少於兩個，則輸出將為空值。

大致等價於：

@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


在 3.10 版被加入.

@end deffn

@geindex permutations() (於 itertools 模組中)
@anchor{library/itertools itertools permutations}@anchor{1bcf}
@deffn {函式} itertools.permutations (iterable, r=None)

回傳 `iterable' 中連續且長度為 `r' 的元素排列@footnote{https://www.britannica.com/science/permutation} 。

如果未指定 `r' 或其值為 @code{None}，則 `r' 預設為 `iterable' 的長度，並產生所有可能的完整長度的排列。

輸出是 @ref{1513,,product()} 的子序列，其中重複元素的條目已被濾除。輸出的長度由 @ref{8d8,,math.perm()} 給定，當 @code{0 ≤ r ≤ n} 時，長度為 @code{n! / (n - r)!}，當 @code{r > n} 時為零。

根據輸入值 `iterable' 的順序，排列的元組會按照字典順序輸出。如果輸入的 `iterable' 已排序，則輸出的元組也將按排序的順序產生。

元素是根據它們的位置（而非值）來決定其唯一性。如果輸入的元素都是獨特的，則排列中將不會有重複的值。

大致等價於：

@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{1513}
@deffn {函式} itertools.product (*iterables, repeat=1)

輸入可疊代物的 笛卡爾乘積@footnote{https://en.wikipedia.org/wiki/Cartesian_product}

大致等價於產生器運算式中的巢狀 for 迴圈。例如，@code{product(A, B)} 的回傳結果與 @code{((x,y) for x in A for y in B)} 相同。

巢狀迴圈的循環類似於里程表，最右邊的元素在每次疊代時前進。這種模式會建立字典順序，因此如果輸入的 iterables 已排序，則輸出的乘積元組也將按排序的順序產生。

要計算可疊代物件自身的乘積，可以使用可選的 `repeat' 關鍵字引數來指定重複次數。例如，@code{product(A, repeat=4)} 與 @code{product(A, A, A, A)} 相同。

此函式大致等價於以下的程式碼，不同之處在於真正的實作不會在記憶體中建立中間結果：

@example
def product(*iterables, repeat=1):
    # product('ABCD', 'xy') → Ax Ay Bx By Cx Cy Dx Dy
    # product(range(2), repeat=3) → 000 001 010 011 100 101 110 111

    if repeat < 0:
        raise ValueError('repeat argument cannot be negative')
    pools = [tuple(pool) for pool in iterables] * repeat

    result = [[]]
    for pool in pools:
        result = [x+[y] for x in result for y in pool]

    for prod in result:
        yield tuple(prod)
@end example

在 @ref{1513,,product()} 執行之前，它會完全消耗輸入的 iterables，並將值的池 (pools of values) 保存在記憶體中以產生乘積。因此，它僅對有限的輸入有用。
@end deffn

@geindex repeat() (於 itertools 模組中)
@anchor{library/itertools itertools repeat}@anchor{17d9}
@deffn {函式} itertools.repeat (object[, times])

建立一個疊代器，反覆回傳 `object'。除非指定了 `times' 引數，否則會執行無限次。

大致等價於：

@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

`repeat' 的常見用途是為 `map' 或 `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{12e5}
@deffn {函式} itertools.starmap (function, iterable)

建立一個疊代器，使用從 `iterable' 取得的引數計算 `function' 。當引數參數已經被「預先壓縮 (pre-zipped)」成元組時，使用此方法代替 @ref{19f,,map()}。

@ref{19f,,map()} 和 @ref{12e5,,starmap()} 之間的區別類似於 @code{function(a,b)} 和 @code{function(*c)} 之間的區別。大致等價於：

@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{2a58}
@deffn {函式} itertools.takewhile (predicate, iterable)

建立一個疊代器，只在 `predicate' 為 true 時回傳 `iterable' 中的元素。大致等價於：

@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

注意，第一個不符合條件判斷的元素將從輸入疊代器中被消耗，且無法再存取它。如果應用程式希望在 `takewhile' 耗盡後進一步消耗輸入疊代器，這可能會是個問題。為了解決這個問題，可以考慮使用 more-itertools 中的 before_and_after()@footnote{https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.before_and_after} 作為替代。
@end deffn

@geindex tee() (於 itertools 模組中)
@anchor{library/itertools itertools tee}@anchor{2a59}
@deffn {函式} itertools.tee (iterable, n=2)

從一個 iterable 中回傳 `n' 個獨立的疊代器。

大致等價於：

@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

當輸入的 `iterable' 已經是一個 tee 疊代物件時，回傳的 tuple（元組）中所有成員都會被建立，就如同它們是由上游的 @ref{2a59,,tee()} 呼叫所產生的一樣。這個「展平步驟 (flattening step)」讓巢狀的 @ref{2a59,,tee()} 呼叫能共享相同的底層資料鏈，並以單一的更新步驟取代一連串的呼叫。

展平特性讓 tee 疊代器具備高效的預覽能力：

@example
def lookahead(tee_iterator):
     "回傳下一個值，但不推進輸入"
     [forked_iterator] = tee(tee_iterator, 1)
     return next(forked_iterator)
@end example

@example
>>> iterator = iter('abcdef')
>>> [iterator] = tee(iterator, 1)   # 使得輸入可預覽
>>> next(iterator)                  # 往前移動疊代器
'a'
>>> lookahead(iterator)             # 檢查下一個值
'b'
>>> next(iterator)                  # 繼續往前移動
'b'
@end example

@code{tee} 疊代器不是執行緒安全 (threadsafe) 的。當同時使用由同一個 @ref{2a59,,tee()} 呼叫所回傳的疊代器時，即使原始的 `iterable' 是執行緒安全的，也可能引發 @ref{244,,RuntimeError}。

此 itertool 可能需要大量的輔助儲存空間（取決於需要儲存多少臨時資料）。通常如果一個疊代器在另一個疊代器開始之前使用了大部分或全部的資料，使用 @ref{24d,,list()} 會比 @ref{2a59,,tee()} 更快。
@end deffn

@geindex zip_longest() (於 itertools 模組中)
@anchor{library/itertools itertools zip_longest}@anchor{149f}
@deffn {函式} itertools.zip_longest (*iterables, fillvalue=None)

建立一個疊代器，聚合來自每個 `iterables' 中的元素。

如果 iterables 的長度不一，則使用 `fillvalue' 填充缺少的值。如果未指定，`fillvalue' 會預設為 @code{None}。

疊代將持續直到最長的可疊代物件耗盡為止。

大致等價於：

@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

如果其中一個 iterables 可能是無限的，那麼應該用別的可以限制呼叫次數的方法來包裝 @ref{149f,,zip_longest()} 函式（例如 @ref{d3b,,islice()} 或 @ref{2a58,,takewhile()}）。
@end deffn

@node Itertools 應用技巧,,Itertool 函式,itertools --- 建立產生高效率迴圈之疊代器的函式
@anchor{library/itertools id1}@anchor{2a5d}@anchor{library/itertools itertools-recipes}@anchor{145f}
@subsubsection Itertools 應用技巧


此段落展示了使用現有的 itertools 作為構建塊來建立擴展工具集的應用技巧。

itertools 應用技巧的主要目的是教學。這些應用技巧展示了對單個工具進行思考的各種方式 —— 例如，@code{chain.from_iterable} 與攤平 (flattening) 的概念相關。這些應用技巧還提供了組合使用工具的想法 —— 例如，@code{starmap()} 和 @code{repeat()} 如何一起工作。另外還展示了將 itertools 與 @ref{a3,,operator} 和 @ref{1e,,collections} 模組一同使用以及與內建 itertools（如 @code{map()}、@code{filter()}、@code{reversed()} 和 @code{enumerate()}）一同使用的模式。

應用技巧的次要目的是作為 itertools 的孵化器。@code{accumulate()}, @code{compress()} 和 @code{pairwise()} itertools 最初都是作為應用技巧出現的。目前，@code{sliding_window()}、@code{iter_index()} 和 @code{sieve()} 的應用技巧正在被測試，以確定它們是否有價值被收錄到內建的 itertools 中。

幾乎所有這些應用技巧以及許多其他應用技巧都可以從 Python Package Index 上的 more-itertools@footnote{https://pypi.org/project/more-itertools/} 專案中安裝：

@example
python -m pip install more-itertools
@end example

許多應用技巧提供了與底層工具集相同的高性能。透過一次處理一個元素而不是將整個可疊代物件一次性引入記憶體，能保持優異的記憶體性能。以函式風格 (functional style)@footnote{https://www.cs.kent.ac.uk/people/staff/dat/miranda/whyfp90.pdf} 將工具連接在一起，能將程式碼的數量維持在較少的情況。透過優先使用「向量化 (vectorized)」的構建塊而不是使用會造成直譯器負擔的 for 迴圈和@ref{125c,,產生器}，則能保持高速度。

@example
from collections import Counter, deque
from contextlib import suppress
from functools import reduce
from math import comb, prod, sumprod, isqrt
from operator import itemgetter, getitem, mul, neg

def take(n, iterable):
    "回傳可疊代物件的前 n 個元素為串列。"
    return list(islice(iterable, n))

def prepend(value, iterable):
    "在可疊代物件開頭插入單一值。"
    # prepend(1, [2, 3, 4]) → 1 2 3 4
    return chain([value], iterable)

def tabulate(function, start=0):
    "回傳 function(0), function(1), ..."
    return map(function, count(start))

def repeatfunc(function, times=None, *args):
    "重複呼叫一個帶指定引數的函式。"
    if times is None:
        return starmap(function, repeat(args))
    return starmap(function, repeat(args, times))

def flatten(list_of_lists):
    "將巢狀結構攤平一層。"
    return chain.from_iterable(list_of_lists)

def ncycles(iterable, n):
    "回傳序列的元素重複 n 次。"
    return chain.from_iterable(repeat(tuple(iterable), n))

def loops(n):
    "執行 n 次的迴圈。類似 range(n) 但不建立整數序列。"
    # for _ in loops(100): ...
    return repeat(None, n)

def tail(n, iterable):
    "回傳一個疊代器，疊代最後 n 個元素。"
    # tail(3, 'ABCDEFG') → E F G
    return iter(deque(iterable, maxlen=n))

def consume(iterator, n=None):
    "將疊代器往前推進 n 步。如果 n 為 None，則完全消耗。"
    # 使用以 C 語言的速度消耗疊代器的函式。
    if n is None:
        deque(iterator, maxlen=0)
    else:
        next(islice(iterator, n, n), None)

def nth(iterable, n, default=None):
    "回傳第 n 個元素或預設值。"
    return next(islice(iterable, n, None), default)

def quantify(iterable, predicate=bool):
    "給定一個回傳 True 或 False 的判斷函式，計算為 True 的結果。"
    return sum(map(predicate, iterable))

def first_true(iterable, default=False, predicate=None):
    "回傳第一個為 true 的值，若無則回傳*預設值*。"
    # 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):
    "回傳 True，如果所有元素兩兩相等。"
    # all_equal('4٤௪౪໔', key=int) → True
    return len(take(2, groupby(iterable, key))) <= 1

def unique_justseen(iterable, key=None):
    "產生唯一的元素，並保留原始順序。只記住剛看見的元素。"
    # 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):
    "產生唯一的元素，並保留原始順序。記住所有曾見過的元素。"
    # 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):
   "產生排序後的不重複元素。支援不可雜湊的輸入。"
   # 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):
    "將資料收集成重疊的固定長度區段或區塊。"
    # sliding_window('ABCDEFG', 4) → ABCD BCDE CDEF DEFG
    iterator = iter(iterable)
    window = deque(islice(iterator, n - 1), maxlen=n)
    for x in iterator:
        window.append(x)
        yield tuple(window)

def grouper(iterable, n, *, incomplete='fill', fillvalue=None):
    "將資料收集成不重疊的固定長度區段或區塊。"
    # 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):
    "以循環方式依序輸入可疊代物件，直到全部耗盡。"
    # roundrobin('ABC', 'D', 'EF') → A D E B F C
    # 演算法出自 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):
    "回傳序列的所有連續非空子切片。"
    # subslices('ABCD') → A AB ABC ABCD B BC BCD C CD D
    slices = starmap(slice, combinations(range(len(seq) + 1), 2))
    return map(getitem, repeat(seq), slices)

def iter_index(iterable, value, start=0, stop=None):
    "回傳在序列或可疊代物件中某值出現的索引位置。"
    # 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):
    "將一個 call-until-exception 轉換為疊代器介面。"
    # iter_except(d.popitem, KeyError) → 非阻塞的字典疊代器
    with suppress(exception):
        if first is not None:
            yield first()
        while True:
            yield function()
@end example

以下的應用技巧具有更多的數學風格：

@example
def multinomial(*counts):
    "多重集合的不同排列數。"
    # 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):
    "來自可疊代物件的子序列，從最短到最長。"
    # 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):
    "將輸入值的平方加總。"
    # sum_of_squares([10, 20, 30]) → 1400
    return sumprod(*tee(iterable))

def reshape(matrix, columns):
    "將 2 維矩陣重新塑形為指定的行數。"
    # 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):
    "交換 2 維矩陣的列和行。"
    # transpose([(1, 2, 3), (11, 22, 33)]) → (1, 11) (2, 22) (3, 33)
    return zip(*matrix, strict=True)

def matmul(m1, m2):
    "矩陣相乘。"
    # matmul([(7, 5), (3, 5)], [(2, 5), (7, 9)]) → (49, 80), (41, 60)
    n = len(m2[0])
    return batched(starmap(sumprod, product(m1, transpose(m2))), n)

def convolve(signal, kernel):
    """兩個可疊代物件的離散線性捲積。
    等同於多項式相乘。

    在數學上捲積是可交換的；但輸入的處理方式不同。
    訊號以惰性方式被讀取，且可以是無限；核心會在計算開始前被全部讀取。

    文章：https://betterexplained.com/articles/intuitive-convolution/
    影片：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]) → 移動平均（模糊）
    # convolve(data, [1/2, 0, -1/2]) → 一階導數估計
    # convolve(data, [1, -2, 1]) → 二階導數估計
    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):
    """由多項式的根計算其係數。

       (x - 5) (x + 4) (x - 3)  展開為:   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):
    """在指定值計算多項式的值。

    此方法在數值穩定性上比 Horner 方法更好。
    """
    # 計算 x³ -4x² -17x + 60 在 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):
    """計算多項式的一階導數。

       f(x)  =  x³ -4x² -17x + 60
       f'(x) = 3x² -8x  -17
    """
    # polynomial_derivative([1, -4, -17, 60]) → [3, -8, -17]
    n = len(coefficients)
    powers = reversed(range(1, n))
    return list(map(mul, coefficients, powers))

def sieve(n):
    "小於 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):
    "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):
    "回傳 True，若 n 為質數。"
    # is_prime(1_000_000_000_000_403) → True
    return n > 1 and next(factor(n)) == n

def totient(n):
    "計算不大於 n 且與 n 互質的自然數個數。"
    # https://mathworld.wolfram.com/TotientFunction.html
    # totient(12) → 4 因爲 len([1, 5, 7, 11]) == 4
    for prime in set(factor(n)):
        n -= n // prime
    return n
@end example

@c These examples no longer appear in the docs but are guaranteed
@c to keep working.
@c 
@c >>> amounts = [120.15, 764.05, 823.14]
@c >>> for checknum, amount in zip(count(1200), amounts):
@c ...     print('Check %d is for $%.2f' % (checknum, amount))
@c ...
@c Check 1200 is for $120.15
@c Check 1201 is for $764.05
@c Check 1202 is for $823.14
@c 
@c >>> import operator
@c >>> for cube in map(operator.pow, range(1,4), repeat(3)):
@c ...    print(cube)
@c ...
@c 1
@c 8
@c 27
@c 
@c >>> reportlines = ['EuroPython', 'Roster', '', 'alex', '', 'laura', '', 'martin', '', 'walter', '', 'samuele']
@c >>> for name in islice(reportlines, 3, None, 2):
@c ...    print(name.title())
@c ...
@c Alex
@c Laura
@c Martin
@c Walter
@c Samuele
@c 
@c >>> from operator import itemgetter
@c >>> d = dict(a=1, b=2, c=1, d=2, e=1, f=2, g=3)
@c >>> di = sorted(sorted(d.items()), key=itemgetter(1))
@c >>> for k, g in groupby(di, itemgetter(1)):
@c ...     print(k, list(map(itemgetter(0), g)))
@c ...
@c 1 ['a', 'c', 'e']
@c 2 ['b', 'd', 'f']
@c 3 ['g']
@c 
@c # Find runs of consecutive numbers using groupby.  The key to the solution
@c # is differencing with a range so that consecutive numbers all appear in
@c # same group.
@c >>> data = [ 1,  4,5,6, 10, 15,16,17,18, 22, 25,26,27,28]
@c >>> for k, g in groupby(enumerate(data), lambda t:t[0]-t[1]):
@c ...     print(list(map(operator.itemgetter(1), g)))
@c ...
@c [1]
@c [4, 5, 6]
@c [10]
@c [15, 16, 17, 18]
@c [22]
@c [25, 26, 27, 28]
@c 
@c Now, we test all of the itertool recipes
@c 
@c >>> take(10, count())
@c [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
@c >>> # Verify that the input is consumed lazily
@c >>> it = iter('abcdef')
@c >>> take(3, it)
@c ['a', 'b', 'c']
@c >>> list(it)
@c ['d', 'e', 'f']
@c 
@c 
@c >>> list(prepend(1, [2, 3, 4]))
@c [1, 2, 3, 4]
@c 
@c 
@c >>> list(enumerate('abc'))
@c [(0, 'a'), (1, 'b'), (2, 'c')]
@c 
@c 
@c >>> list(islice(tabulate(lambda x: 2*x), 4))
@c [0, 2, 4, 6]
@c 
@c 
@c >>> for _ in loops(5):
@c ...     print('hi')
@c ...
@c hi
@c hi
@c hi
@c hi
@c hi
@c 
@c 
@c >>> list(tail(3, 'ABCDEFG'))
@c ['E', 'F', 'G']
@c >>> # Verify the input is consumed greedily
@c >>> input_iterator = iter('ABCDEFG')
@c >>> output_iterator = tail(3, input_iterator)
@c >>> list(input_iterator)
@c []
@c 
@c 
@c >>> it = iter(range(10))
@c >>> consume(it, 3)
@c >>> # Verify the input is consumed lazily
@c >>> next(it)
@c 3
@c >>> # Verify the input is consumed completely
@c >>> consume(it)
@c >>> next(it, 'Done')
@c 'Done'
@c 
@c 
@c >>> nth('abcde', 3)
@c 'd'
@c >>> nth('abcde', 9) is None
@c True
@c >>> # Verify that the input is consumed lazily
@c >>> it = iter('abcde')
@c >>> nth(it, 2)
@c 'c'
@c >>> list(it)
@c ['d', 'e']
@c 
@c 
@c >>> [all_equal(s) for s in ('', 'A', 'AAAA', 'AAAB', 'AAABA')]
@c [True, True, True, False, False]
@c >>> [all_equal(s, key=str.casefold) for s in ('', 'A', 'AaAa', 'AAAB', 'AAABA')]
@c [True, True, True, False, False]
@c >>> # Verify that the input is consumed lazily and that only
@c >>> # one element of a second equivalence class is used to disprove
@c >>> # the assertion that all elements are equal.
@c >>> it = iter('aaabbbccc')
@c >>> all_equal(it)
@c False
@c >>> ''.join(it)
@c 'bbccc'
@c 
@c 
@c >>> quantify(range(99), lambda x: x%2==0)
@c 50
@c >>> quantify([True, False, False, True, True])
@c 3
@c >>> quantify(range(12), predicate=lambda x: x%2==1)
@c 6
@c 
@c 
@c >>> a = [[1, 2, 3], [4, 5, 6]]
@c >>> list(flatten(a))
@c [1, 2, 3, 4, 5, 6]
@c 
@c 
@c >>> list(ncycles('abc', 3))
@c ['a', 'b', 'c', 'a', 'b', 'c', 'a', 'b', 'c']
@c >>> # Verify greedy consumption of input iterator
@c >>> input_iterator = iter('abc')
@c >>> output_iterator = ncycles(input_iterator, 3)
@c >>> list(input_iterator)
@c []
@c 
@c 
@c >>> sum_of_squares([10, 20, 30])
@c 1400
@c 
@c 
@c >>> list(reshape([(0, 1), (2, 3), (4, 5)], 3))
@c [(0, 1, 2), (3, 4, 5)]
@c >>> M = [(0, 1, 2, 3), (4, 5, 6, 7), (8, 9, 10, 11)]
@c >>> list(reshape(M, 1))
@c [(0,), (1,), (2,), (3,), (4,), (5,), (6,), (7,), (8,), (9,), (10,), (11,)]
@c >>> list(reshape(M, 2))
@c [(0, 1), (2, 3), (4, 5), (6, 7), (8, 9), (10, 11)]
@c >>> list(reshape(M, 3))
@c [(0, 1, 2), (3, 4, 5), (6, 7, 8), (9, 10, 11)]
@c >>> list(reshape(M, 4))
@c [(0, 1, 2, 3), (4, 5, 6, 7), (8, 9, 10, 11)]
@c >>> list(reshape(M, 5))
@c Traceback (most recent call last):
@c ...
@c ValueError: batched(): incomplete batch
@c >>> list(reshape(M, 6))
@c [(0, 1, 2, 3, 4, 5), (6, 7, 8, 9, 10, 11)]
@c >>> list(reshape(M, 12))
@c [(0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11)]
@c 
@c 
@c >>> list(transpose([(1, 2, 3), (11, 22, 33)]))
@c [(1, 11), (2, 22), (3, 33)]
@c >>> # Verify that the inputs are consumed lazily
@c >>> input1 = iter([1, 2, 3])
@c >>> input2 = iter([11, 22, 33])
@c >>> output_iterator = transpose([input1, input2])
@c >>> next(output_iterator)
@c (1, 11)
@c >>> list(zip(input1, input2))
@c [(2, 22), (3, 33)]
@c 
@c 
@c >>> list(matmul([(7, 5), (3, 5)], [[2, 5], [7, 9]]))
@c [(49, 80), (41, 60)]
@c >>> list(matmul([[2, 5], [7, 9], [3, 4]], [[7, 11, 5, 4, 9], [3, 5, 2, 6, 3]]))
@c [(29, 47, 20, 38, 33), (76, 122, 53, 82, 90), (33, 53, 23, 36, 39)]
@c 
@c 
@c >>> list(convolve([1, -1, -20], [1, -3])) == [1, -4, -17, 60]
@c True
@c >>> data = [20, 40, 24, 32, 20, 28, 16]
@c >>> list(convolve(data, [0.25, 0.25, 0.25, 0.25]))
@c [5.0, 15.0, 21.0, 29.0, 29.0, 26.0, 24.0, 16.0, 11.0, 4.0]
@c >>> list(convolve(data, [1, -1]))
@c [20, 20, -16, 8, -12, 8, -12, -16]
@c >>> list(convolve(data, [1, -2, 1]))
@c [20, 0, -36, 24, -20, 20, -20, -4, 16]
@c >>> # Verify signal is consumed lazily and the kernel greedily
@c >>> signal_iterator = iter([10, 20, 30, 40, 50])
@c >>> kernel_iterator = iter([1, 2, 3])
@c >>> output_iterator = convolve(signal_iterator, kernel_iterator)
@c >>> list(kernel_iterator)
@c []
@c >>> next(output_iterator)
@c 10
@c >>> next(output_iterator)
@c 40
@c >>> list(signal_iterator)
@c [30, 40, 50]
@c 
@c 
@c >>> from fractions import Fraction
@c >>> from decimal import Decimal
@c >>> polynomial_eval([1, -4, -17, 60], x=5)
@c 0
@c >>> x = 5; x**3 - 4*x**2 -17*x + 60
@c 0
@c >>> polynomial_eval([1, -4, -17, 60], x=2.5)
@c 8.125
@c >>> x = 2.5; x**3 - 4*x**2 -17*x + 60
@c 8.125
@c >>> polynomial_eval([1, -4, -17, 60], x=Fraction(2, 3))
@c Fraction(1274, 27)
@c >>> x = Fraction(2, 3); x**3 - 4*x**2 -17*x + 60
@c Fraction(1274, 27)
@c >>> polynomial_eval([1, -4, -17, 60], x=Decimal('1.75'))
@c Decimal('23.359375')
@c >>> x = Decimal('1.75'); x**3 - 4*x**2 -17*x + 60
@c Decimal('23.359375')
@c >>> polynomial_eval([], 2)
@c 0
@c >>> polynomial_eval([], 2.5)
@c 0.0
@c >>> polynomial_eval([], Fraction(2, 3))
@c Fraction(0, 1)
@c >>> polynomial_eval([], Decimal('1.75'))
@c Decimal('0')
@c >>> polynomial_eval([11], 7) == 11
@c True
@c >>> polynomial_eval([11, 2], 7) == 11 * 7 + 2
@c True
@c 
@c 
@c >>> polynomial_from_roots([5, -4, 3])
@c [1, -4, -17, 60]
@c >>> factored = lambda x: (x - 5) * (x + 4) * (x - 3)
@c >>> expanded = lambda x: x**3 -4*x**2 -17*x + 60
@c >>> all(factored(x) == expanded(x) for x in range(-10, 11))
@c True
@c 
@c 
@c >>> polynomial_derivative([1, -4, -17, 60])
@c [3, -8, -17]
@c 
@c 
@c >>> list(iter_index('AABCADEAF', 'A'))
@c [0, 1, 4, 7]
@c >>> list(iter_index('AABCADEAF', 'B'))
@c [2]
@c >>> list(iter_index('AABCADEAF', 'X'))
@c []
@c >>> list(iter_index('', 'X'))
@c []
@c >>> list(iter_index('AABCADEAF', 'A', 1))
@c [1, 4, 7]
@c >>> list(iter_index(iter('AABCADEAF'), 'A', 1))
@c [1, 4, 7]
@c >>> list(iter_index('AABCADEAF', 'A', 2))
@c [4, 7]
@c >>> list(iter_index(iter('AABCADEAF'), 'A', 2))
@c [4, 7]
@c >>> list(iter_index('AABCADEAF', 'A', 10))
@c []
@c >>> list(iter_index(iter('AABCADEAF'), 'A', 10))
@c []
@c >>> list(iter_index('AABCADEAF', 'A', 1, 7))
@c [1, 4]
@c >>> list(iter_index(iter('AABCADEAF'), 'A', 1, 7))
@c [1, 4]
@c >>> # Verify that ValueErrors not swallowed (gh-107208)
@c >>> def assert_no_value(iterable, forbidden_value):
@c ...     for item in iterable:
@c ...         if item == forbidden_value:
@c ...             raise ValueError
@c ...         yield item
@c ...
@c >>> list(iter_index(assert_no_value('AABCADEAF', 'B'), 'A'))
@c Traceback (most recent call last):
@c ...
@c ValueError
@c >>> # Verify that both paths can find identical NaN values
@c >>> x = float('NaN')
@c >>> y = float('NaN')
@c >>> list(iter_index([0, x, x, y, 0], x))
@c [1, 2]
@c >>> list(iter_index(iter([0, x, x, y, 0]), x))
@c [1, 2]
@c >>> # Test list input. Lists do not support None for the stop argument
@c >>> list(iter_index(list('AABCADEAF'), 'A'))
@c [0, 1, 4, 7]
@c >>> # Verify that input is consumed lazily
@c >>> input_iterator = iter('AABCADEAF')
@c >>> output_iterator = iter_index(input_iterator, 'A')
@c >>> next(output_iterator)
@c 0
@c >>> next(output_iterator)
@c 1
@c >>> next(output_iterator)
@c 4
@c >>> ''.join(input_iterator)
@c 'DEAF'
@c 
@c 
@c >>> # Verify that the target value can be a sequence.
@c >>> seq = [[10, 20], [30, 40], 30, 40, [30, 40], 50]
@c >>> target = [30, 40]
@c >>> list(iter_index(seq, target))
@c [1, 4]
@c 
@c 
@c >>> # Verify faithfulness to type specific index() method behaviors.
@c >>> # For example, bytes and str perform continuous-subsequence searches
@c >>> # that do not match the general behavior specified
@c >>> # in collections.abc.Sequence.index().
@c >>> seq = 'abracadabra'
@c >>> target = 'ab'
@c >>> list(iter_index(seq, target))
@c [0, 7]
@c 
@c 
@c >>> list(sieve(30))
@c [2, 3, 5, 7, 11, 13, 17, 19, 23, 29]
@c >>> small_primes = [2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47, 53, 59, 61, 67, 71, 73, 79, 83, 89, 97]
@c >>> all(list(sieve(n)) == [p for p in small_primes if p < n] for n in range(101))
@c True
@c >>> len(list(sieve(100)))
@c 25
@c >>> len(list(sieve(1_000)))
@c 168
@c >>> len(list(sieve(10_000)))
@c 1229
@c >>> len(list(sieve(100_000)))
@c 9592
@c >>> len(list(sieve(1_000_000)))
@c 78498
@c >>> carmichael = {561, 1105, 1729, 2465, 2821, 6601, 8911}  # https://oeis.org/A002997
@c >>> set(sieve(10_000)).isdisjoint(carmichael)
@c True
@c 
@c 
@c >>> small_primes = [2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47, 53, 59, 61, 67, 71, 73, 79, 83, 89, 97]
@c >>> list(filter(is_prime, range(-100, 100))) == small_primes
@c True
@c >>> carmichael = {561, 1105, 1729, 2465, 2821, 6601, 8911}  # https://oeis.org/A002997
@c >>> any(map(is_prime, carmichael))
@c False
@c >>> # https://www.wolframalpha.com/input?i=is+128884753939+prime
@c >>> is_prime(128_884_753_939)           # large prime
@c True
@c >>> is_prime(999953 * 999983)           # large semiprime
@c False
@c >>> is_prime(1_000_000_000_000_007)     # factor() example
@c False
@c >>> is_prime(1_000_000_000_000_403)     # factor() example
@c True
@c 
@c 
@c >>> list(factor(99))                    # Code example 1
@c [3, 3, 11]
@c >>> list(factor(1_000_000_000_000_007)) # Code example 2
@c [47, 59, 360620266859]
@c >>> list(factor(1_000_000_000_000_403)) # Code example 3
@c [1000000000000403]
@c >>> list(factor(0))
@c []
@c >>> list(factor(1))
@c []
@c >>> list(factor(2))
@c [2]
@c >>> list(factor(3))
@c [3]
@c >>> list(factor(4))
@c [2, 2]
@c >>> list(factor(5))
@c [5]
@c >>> list(factor(6))
@c [2, 3]
@c >>> list(factor(7))
@c [7]
@c >>> list(factor(8))
@c [2, 2, 2]
@c >>> list(factor(9))
@c [3, 3]
@c >>> list(factor(10))
@c [2, 5]
@c >>> list(factor(128_884_753_939))       # large prime
@c [128884753939]
@c >>> list(factor(999953 * 999983))       # large semiprime
@c [999953, 999983]
@c >>> list(factor(6 ** 20)) == [2] * 20 + [3] * 20   # large power
@c True
@c >>> list(factor(909_909_090_909))       # large multiterm composite
@c [3, 3, 7, 13, 13, 751, 113797]
@c >>> math.prod([3, 3, 7, 13, 13, 751, 113797])
@c 909909090909
@c >>> all(math.prod(factor(n)) == n for n in range(1, 2_000))
@c True
@c >>> all(set(factor(n)) <= set(sieve(n+1)) for n in range(2_000))
@c True
@c >>> all(list(factor(n)) == sorted(factor(n)) for n in range(2_000))
@c True
@c 
@c 
@c >>> totient(0)  # https://www.wolframalpha.com/input?i=totient+0
@c 0
@c >>> first_totients = [1, 1, 2, 2, 4, 2, 6, 4, 6, 4, 10, 4, 12, 6, 8, 8, 16, 6,
@c ... 18, 8, 12, 10, 22, 8, 20, 12, 18, 12, 28, 8, 30, 16, 20, 16, 24, 12, 36, 18,
@c ... 24, 16, 40, 12, 42, 20, 24, 22, 46, 16, 42, 20, 32, 24, 52, 18, 40, 24, 36,
@c ... 28, 58, 16, 60, 30, 36, 32, 48, 20, 66, 32, 44]  # https://oeis.org/A000010
@c ...
@c >>> list(map(totient, range(1, 70))) == first_totients
@c True
@c >>> reference_totient = lambda n: sum(math.gcd(t, n) == 1 for t in range(1, n+1))
@c >>> all(totient(n) == reference_totient(n) for n in range(1000))
@c True
@c >>> totient(128_884_753_939) == 128_884_753_938  # large prime
@c True
@c >>> totient(999953 * 999983) == 999952 * 999982  # large semiprime
@c True
@c >>> totient(6 ** 20) == 1 * 2**19 * 2 * 3**19    # repeated primes
@c True
@c 
@c 
@c >>> list(flatten([('a', 'b'), (), ('c', 'd', 'e'), ('f',), ('g', 'h', 'i')]))
@c ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i']
@c 
@c 
@c >>> list(repeatfunc(pow, 5, 2, 3))
@c [8, 8, 8, 8, 8]
@c >>> take(5, map(int, repeatfunc(random.random)))
@c [0, 0, 0, 0, 0]
@c >>> random.seed(85753098575309)
@c >>> list(repeatfunc(random.random, 3))
@c [0.16370491282496968, 0.45889608687313455, 0.3747076837820118]
@c >>> list(repeatfunc(chr, 3, 65))
@c ['A', 'A', 'A']
@c >>> list(repeatfunc(pow, 3, 2, 5))
@c [32, 32, 32]
@c 
@c 
@c >>> list(grouper('abcdefg', 3, fillvalue='x'))
@c [('a', 'b', 'c'), ('d', 'e', 'f'), ('g', 'x', 'x')]
@c 
@c 
@c >>> it = grouper('abcdefg', 3, incomplete='strict')
@c >>> next(it)
@c ('a', 'b', 'c')
@c >>> next(it)
@c ('d', 'e', 'f')
@c >>> next(it)
@c Traceback (most recent call last):
@c   ...
@c ValueError: zip() argument 2 is shorter than argument 1
@c 
@c >>> list(grouper('abcdefg', n=3, incomplete='ignore'))
@c [('a', 'b', 'c'), ('d', 'e', 'f')]
@c 
@c 
@c >>> list(sliding_window('ABCDEFG', 1))
@c [('A',), ('B',), ('C',), ('D',), ('E',), ('F',), ('G',)]
@c >>> list(sliding_window('ABCDEFG', 2))
@c [('A', 'B'), ('B', 'C'), ('C', 'D'), ('D', 'E'), ('E', 'F'), ('F', 'G')]
@c >>> list(sliding_window('ABCDEFG', 3))
@c [('A', 'B', 'C'), ('B', 'C', 'D'), ('C', 'D', 'E'), ('D', 'E', 'F'), ('E', 'F', 'G')]
@c >>> list(sliding_window('ABCDEFG', 4))
@c [('A', 'B', 'C', 'D'), ('B', 'C', 'D', 'E'), ('C', 'D', 'E', 'F'), ('D', 'E', 'F', 'G')]
@c >>> list(sliding_window('ABCDEFG', 5))
@c [('A', 'B', 'C', 'D', 'E'), ('B', 'C', 'D', 'E', 'F'), ('C', 'D', 'E', 'F', 'G')]
@c >>> list(sliding_window('ABCDEFG', 6))
@c [('A', 'B', 'C', 'D', 'E', 'F'), ('B', 'C', 'D', 'E', 'F', 'G')]
@c >>> list(sliding_window('ABCDEFG', 7))
@c [('A', 'B', 'C', 'D', 'E', 'F', 'G')]
@c >>> list(sliding_window('ABCDEFG', 8))
@c []
@c >>> try:
@c ...     list(sliding_window('ABCDEFG', -1))
@c ... except ValueError:
@c ...     'zero or negative n not supported'
@c ...
@c 'zero or negative n not supported'
@c >>> try:
@c ...     list(sliding_window('ABCDEFG', 0))
@c ... except ValueError:
@c ...     'zero or negative n not supported'
@c ...
@c 'zero or negative n not supported'
@c 
@c 
@c >>> list(roundrobin('abc', 'd', 'ef'))
@c ['a', 'd', 'e', 'b', 'f', 'c']
@c >>> ranges = [range(5, 1000), range(4, 3000), range(0), range(3, 2000), range(2, 5000), range(1, 3500)]
@c >>> collections.Counter(roundrobin(*ranges)) == collections.Counter(chain(*ranges))
@c True
@c >>> # Verify that the inputs are consumed lazily
@c >>> input_iterators = list(map(iter, ['abcd', 'ef', '', 'ghijk', 'l', 'mnopqr']))
@c >>> output_iterator = roundrobin(*input_iterators)
@c >>> ''.join(islice(output_iterator, 10))
@c 'aeglmbfhnc'
@c >>> ''.join(chain(*input_iterators))
@c 'dijkopqr'
@c 
@c 
@c >>> list(subslices('ABCD'))
@c ['A', 'AB', 'ABC', 'ABCD', 'B', 'BC', 'BCD', 'C', 'CD', 'D']
@c 
@c 
@c >>> list(powerset([1,2,3]))
@c [(), (1,), (2,), (3,), (1, 2), (1, 3), (2, 3), (1, 2, 3)]
@c >>> all(len(list(powerset(range(n)))) == 2**n for n in range(18))
@c True
@c >>> list(powerset('abcde')) == sorted(sorted(set(powerset('abcde'))), key=len)
@c True
@c 
@c 
@c >>> list(unique_everseen('AAAABBBCCDAABBB'))
@c ['A', 'B', 'C', 'D']
@c >>> list(unique_everseen('ABBCcAD', str.casefold))
@c ['A', 'B', 'C', 'D']
@c >>> list(unique_everseen('ABBcCAD', str.casefold))
@c ['A', 'B', 'c', 'D']
@c >>> # Verify that the input is consumed lazily
@c >>> input_iterator = iter('AAAABBBCCDAABBB')
@c >>> output_iterator = unique_everseen(input_iterator)
@c >>> next(output_iterator)
@c 'A'
@c >>> ''.join(input_iterator)
@c 'AAABBBCCDAABBB'
@c 
@c 
@c >>> list(unique_justseen('AAAABBBCCDAABBB'))
@c ['A', 'B', 'C', 'D', 'A', 'B']
@c >>> list(unique_justseen('ABBCcAD', str.casefold))
@c ['A', 'B', 'C', 'A', 'D']
@c >>> list(unique_justseen('ABBcCAD', str.casefold))
@c ['A', 'B', 'c', 'A', 'D']
@c >>> # Verify that the input is consumed lazily
@c >>> input_iterator = iter('AAAABBBCCDAABBB')
@c >>> output_iterator = unique_justseen(input_iterator)
@c >>> next(output_iterator)
@c 'A'
@c >>> ''.join(input_iterator)
@c 'AAABBBCCDAABBB'
@c 
@c 
@c >>> list(unique([[1, 2], [3, 4], [1, 2]]))
@c [[1, 2], [3, 4]]
@c >>> list(unique('ABBcCAD', str.casefold))
@c ['A', 'B', 'c', 'D']
@c >>> list(unique('ABBcCAD', str.casefold, reverse=True))
@c ['D', 'c', 'B', 'A']
@c 
@c 
@c >>> d = dict(a=1, b=2, c=3)
@c >>> it = iter_except(d.popitem, KeyError)
@c >>> d['d'] = 4
@c >>> next(it)
@c ('d', 4)
@c >>> next(it)
@c ('c', 3)
@c >>> next(it)
@c ('b', 2)
@c >>> d['e'] = 5
@c >>> next(it)
@c ('e', 5)
@c >>> next(it)
@c ('a', 1)
@c >>> next(it, 'empty')
@c 'empty'
@c 
@c 
@c >>> first_true('ABC0DEF1', '9', str.isdigit)
@c '0'
@c >>> # Verify that inputs are consumed lazily
@c >>> it = iter('ABC0DEF1')
@c >>> first_true(it, predicate=str.isdigit)
@c '0'
@c >>> ''.join(it)
@c 'DEF1'
@c 
@c >>> multinomial(5, 2, 2, 1, 1)
@c 83160
@c >>> word = 'coffee'
@c >>> multinomial(*Counter(word).values()) == len(set(permutations(word)))
@c True

@c # Old recipes and their tests which are guaranteed to continue to work.
@c 
@c def old_sumprod_recipe(vec1, vec2):
@c     "Compute a sum of products."
@c     return sum(starmap(operator.mul, zip(vec1, vec2, strict=True)))
@c 
@c def dotproduct(vec1, vec2):
@c     return sum(map(operator.mul, vec1, vec2))
@c 
@c def pad_none(iterable):
@c     """Returns the sequence elements and then returns None indefinitely.
@c 
@c     Useful for emulating the behavior of the built-in map() function.
@c     """
@c     return chain(iterable, repeat(None))
@c 
@c def triplewise(iterable):
@c     "Return overlapping triplets from an iterable"
@c     # triplewise('ABCDEFG') → ABC BCD CDE DEF EFG
@c     for (a, _), (b, c) in pairwise(pairwise(iterable)):
@c         yield a, b, c
@c 
@c def nth_combination(iterable, r, index):
@c     "Equivalent to list(combinations(iterable, r))[index]"
@c     pool = tuple(iterable)
@c     n = len(pool)
@c     c = math.comb(n, r)
@c     if index < 0:
@c         index += c
@c     if index < 0 or index >= c:
@c         raise IndexError
@c     result = []
@c     while r:
@c         c, n, r = c*r//n, n-1, r-1
@c         while index >= c:
@c             index -= c
@c             c, n = c*(n-r)//n, n-1
@c         result.append(pool[-1-n])
@c     return tuple(result)
@c 
@c def before_and_after(predicate, it):
@c    """ Variant of takewhile() that allows complete
@c        access to the remainder of the iterator.
@c 
@c        >>> it = iter('ABCdEfGhI')
@c        >>> all_upper, remainder = before_and_after(str.isupper, it)
@c        >>> ''.join(all_upper)
@c        'ABC'
@c        >>> ''.join(remainder)     # takewhile() would lose the 'd'
@c        'dEfGhI'
@c 
@c        Note that the true iterator must be fully consumed
@c        before the remainder iterator can generate valid results.
@c    """
@c    it = iter(it)
@c    transition = []
@c 
@c    def true_iterator():
@c        for elem in it:
@c            if predicate(elem):
@c                yield elem
@c            else:
@c                transition.append(elem)
@c                return
@c 
@c    return true_iterator(), chain(transition, it)
@c 
@c def partition(predicate, iterable):
@c     """Partition entries into false entries and true entries.
@c 
@c     If *predicate* is slow, consider wrapping it with functools.lru_cache().
@c     """
@c     # partition(is_odd, range(10)) → 0 2 4 6 8   and  1 3 5 7 9
@c     t1, t2 = tee(iterable)
@c     return filterfalse(predicate, t1), filter(predicate, t2)

@c >>> dotproduct([1,2,3], [4,5,6])
@c 32
@c 
@c 
@c >>> old_sumprod_recipe([1,2,3], [4,5,6])
@c 32
@c 
@c 
@c >>> list(islice(pad_none('abc'), 0, 6))
@c ['a', 'b', 'c', None, None, None]
@c 
@c 
@c >>> list(triplewise('ABCDEFG'))
@c [('A', 'B', 'C'), ('B', 'C', 'D'), ('C', 'D', 'E'), ('D', 'E', 'F'), ('E', 'F', 'G')]
@c 
@c 
@c >>> population = 'ABCDEFGH'
@c >>> for r in range(len(population) + 1):
@c ...     seq = list(combinations(population, r))
@c ...     for i in range(len(seq)):
@c ...         assert nth_combination(population, r, i) == seq[i]
@c ...     for i in range(-len(seq), 0):
@c ...         assert nth_combination(population, r, i) == seq[i]
@c ...
@c >>> iterable = 'abcde'
@c >>> r = 3
@c >>> combos = list(combinations(iterable, r))
@c >>> all(nth_combination(iterable, r, i) == comb for i, comb in enumerate(combos))
@c True
@c 
@c 
@c >>> it = iter('ABCdEfGhI')
@c >>> all_upper, remainder = before_and_after(str.isupper, it)
@c >>> ''.join(all_upper)
@c 'ABC'
@c >>> ''.join(remainder)
@c 'dEfGhI'
@c 
@c 
@c >>> def is_odd(x):
@c ...     return x % 2 == 1
@c ...
@c >>> evens, odds = partition(is_odd, range(10))
@c >>> list(evens)
@c [0, 2, 4, 6, 8]
@c >>> list(odds)
@c [1, 3, 5, 7, 9]
@c >>> # Verify that the input is consumed lazily
@c >>> input_iterator = iter(range(10))
@c >>> evens, odds = partition(is_odd, input_iterator)
@c >>> next(odds)
@c 1
@c >>> next(odds)
@c 3
@c >>> next(evens)
@c 0
@c >>> list(input_iterator)
@c [4, 5, 6, 7, 8, 9]

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node functools --- 可呼叫物件上的高階函式與操作,operator --- 標準運算子替代函式,itertools --- 建立產生高效率迴圈之疊代器的函式,函式程式設計模組
@anchor{library/functools doc}@anchor{2a5e}@anchor{library/functools functools-higher-order-functions-and-operations-on-callable-objects}@anchor{2a5f}@anchor{library/functools module-functools}@anchor{63}@anchor{library/functools translation-repo}@anchor{2a60}
@subsection @code{functools} --- 可呼叫物件上的高階函式與操作


@geindex module; functools

`原始碼：'Lib/functools.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/functools.py}

@c import functools
@c from functools import *


__________________________________________________________________


@ref{63,,functools} 模組用於高階函式：作用於或回傳其他函式的函式。一般來說，任何可呼叫物件都可以被視為用於此模組的函式。

@ref{63,,functools} 模組定義了以下函式：

@geindex cache() (於 functools 模組中)
@anchor{library/functools functools cache}@anchor{175e}
@deffn {函式} @@functools.cache (user_function)

簡單的輕量級無繫結函式快取 (Simple lightweight unbounded function cache)。有時稱之為 "memoize"（記憶化）@footnote{https://en.wikipedia.org/wiki/Memoization}。

和 @code{lru_cache(maxsize=None)} 回傳相同的值，為函式引數建立一個字典查找的薄包裝器。因為它永遠不需要丟棄舊值，所以這比有大小限制的 @ref{bd9,,lru_cache()} 更小、更快。

舉例來說：

@example
@@cache
def factorial(n):
    return n * factorial(n-1) if n else 1

>>> factorial(10)      # 沒有先前的快取結果，會進行 11 次遞迴呼叫
3628800
>>> factorial(5)       # 只查詢快取的結果
120
>>> factorial(12)      # 進行兩次新的遞迴呼叫，其他 10 次是快取的
479001600
@end example

該快取是執行緒安全的 (threadsafe)，因此包裝的函式可以在多個執行緒中使用。這意味著底層資料結構在並行更新期間將保持連貫 (coherent)。

如果另一個執行緒在初始呼叫完成並快取之前進行額外的呼叫，則包裝的函式可能會被多次呼叫。


在 3.9 版被加入.

@end deffn

@geindex cached_property() (於 functools 模組中)
@anchor{library/functools functools cached_property}@anchor{75c}
@deffn {函式} @@functools.cached_property (func)

將類別的一個方法轉換為屬性 (property)，其值會計算一次，然後在實例的生命週期內快取為普通屬性。類似 @ref{4ae,,property()}，但增加了快取機制。對於除使用該裝飾器的屬性外實質上幾乎是不可變 (immutable) 的實例，針對其所需要繁重計算會很有用。

範例：

@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

@ref{75c,,cached_property()} 的機制與 @ref{4ae,,property()} 有所不同。除非定義了 setter，否則常規屬性會阻止屬性的寫入。相反地，`cached_property' 則允許寫入。

`cached_property' 裝飾器僅在查找時且僅在同名屬性不存在時運行。當它運行時，`cached_property' 會寫入同名的屬性。後續屬性讀取和寫入優先於 `cached_property' 方法，並且它的工作方式與普通屬性類似。

可以透過刪除屬性來清除快取的值，這使得 `cached_property' 方法可以再次運行。

`cached_property' 無法防止多執行緒使用中可能出現的競爭條件 (race condition)。getter 函式可以在同一個實例上運行多次，最後一次運行會設定快取的值。所以快取的屬性最好是冪等的 (idempotent)，或者在一個實例上運行多次不會有害，就不會有問題。如果同步是必要的，請在裝飾的 getter 函式內部或在快取的屬性存取周圍實作必要的鎖。

請注意，此裝飾器會干擾 
@geindex Python Enhancement Proposals; PEP 412
PEP 412@footnote{https://peps.python.org/pep-0412/} 金鑰共用字典的操作。這意味著實例字典可能比平常佔用更多的空間。

此外，此裝飾器要求每個實例上的 @code{__dict__} 屬性是可變對映 (mutable mapping)。這意味著它不適用於某些型別，例如元類別 (metaclass)（因為型別實例上的 @code{__dict__} 屬性是類別命名空間的唯讀代理），以及那些指定 @code{__slots__} 而不包含 @code{__dict__} 的型別作為有定義的插槽之一（因為此種類別根本不提供 @code{__dict__} 屬性）。

如果可變對映不可用或需要金鑰共享以節省空間，則也可以透過在 @ref{bd9,,lru_cache()} 之上堆疊 @ref{4ae,,property()} 來實作類似於 @ref{75c,,cached_property()} 的效果。請參閱@ref{2a61,,如何快取方法呼叫？}以了解有關這與 @ref{75c,,cached_property()} 間不同之處的更多詳細資訊。


在 3.8 版被加入.



在 3.12 版的變更: 在 Python 3.12 之前，@code{cached_property} 包含一個未以文件記錄的鎖，以確保在多執行緒使用中能保證 getter 函式對於每個實例只會執行一次。然而，鎖是針對每個屬性，而不是針對每個實例，這可能會導致無法被接受的嚴重鎖爭用 (lock contention)。在 Python 3.12+ 中，此鎖已被刪除。

@end deffn

@geindex cmp_to_key() (於 functools 模組中)
@anchor{library/functools functools cmp_to_key}@anchor{13db}
@deffn {函式} functools.cmp_to_key (func)

將舊式比較函式轉換為@ref{1001,,鍵函式}，能與接受鍵函式的工具一起使用（例如 @ref{dc2,,sorted()}、@ref{1106,,min()}、@ref{1107,,max()}、@ref{2854,,heapq.nlargest()}、@ref{2855,,heapq.nsmallest()}、@ref{2a57,,itertools.groupby()}）。此函式主要作為轉換工具，用於從有支援使用比較函式的 Python 2 轉換成的程式。

比較函式是任何能接受兩個引數、對它們進行比較，並回傳負數（小於）、零（相等）或正數（大於）的可呼叫物件。鍵函式是接受一個引數並回傳另一個用作排序鍵之值的可呼叫物件。

範例：

@example
sorted(iterable, key=cmp_to_key(locale.strcoll))  # locale-aware sort order
@end example

有關排序範例和簡短的排序教學，請參閱@ref{248a,,排序技法}。


在 3.2 版被加入.

@end deffn

@geindex lru_cache() (於 functools 模組中)
@anchor{library/functools functools lru_cache}@anchor{bd9}
@deffn {函式} @@functools.lru_cache (user_function)

@deffnx {函式} @@functools.lru_cache (maxsize=128, typed=False)

以記憶化可呼叫物件來包裝函式的裝飾器，最多可省去 `maxsize' 個最近的呼叫。當使用相同引數定期呼叫繁重的或 I/O 密集的函式時，它可以節省時間。

該快取是執行緒安全的 (threadsafe)，因此包裝的函式可以在多個執行緒中使用。這意味著底層資料結構在並行更新期間將保持連貫 (coherent)。

如果另一個執行緒在初始呼叫完成並快取之前進行額外的呼叫，則包裝的函式可能會被多次呼叫。

由於字典用於快取結果，因此函式的位置引數和關鍵字引數必須是@ref{81d,,可雜湊的}。

不同的引數模式可以被認為是具有不同快取條目的不同呼叫。例如，@code{f(a=1, b=2)} 和 @code{f(b=2, a=1)} 的關鍵字引數順序不同，並且可能有兩個不同的快取條目。

如果指定了 `user_function'，則它必須是個可呼叫物件。這使得 `lru_cache' 裝飾器能夠直接應用於使用者函式，將 `maxsize' 保留為其預設值 128：

@example
@@lru_cache
def count_vowels(sentence):
    return sum(sentence.count(vowel) for vowel in 'AEIOUaeiou')
@end example

如果 `maxsize' 設定為 @code{None}，則 LRU 功能將被停用，且快取可以無限制地成長。

如果 `typed' 設定為 true，不同型別的函式引數將會被單獨快取起來。如果 `typed' 為 false，則實作通常會將它們視為等效呼叫，並且僅快取單一結果。（某些型別，例如 `str' 和 `int' 可能會被單獨快取起來，即使 `typed' 為 false。）

請注意，型別特異性 (type specificity) 僅適用於函式的直接引數而不是其內容。純量 (scalar) 引數 @code{Decimal(42)} 和 @code{Fraction(42)} 被視為具有不同結果的不同呼叫。相反地，元組引數 @code{('answer', Decimal(42))} 和 @code{('answer', Fraction(42))} 被視為等效。

包裝的函式使用一個 @code{cache_parameters()} 函式來進行偵測，該函式回傳一個新的 @ref{183,,dict} 以顯示 `maxsize' 和 `typed' 的值。這僅能顯示資訊，改變其值不會有任何效果。

@geindex cache_info() (functools.lru_cache 的方法)
@anchor{library/functools functools lru_cache cache_info}@anchor{2a62}
為了輔助測量快取的有效性並調整 `maxsize' 參數，包裝的函式使用了一個 @code{cache_info()} 函式來做檢測，該函式會回傳一個@ref{857,,附名元組}來顯示 `hits'、`misses'、`maxsize' 和 `currsize'。

@geindex cache_clear() (functools.lru_cache 的方法)
@anchor{library/functools functools lru_cache cache_clear}@anchor{2a63}
裝飾器還提供了一個 @code{cache_clear()} 函式來清除或使快取失效。

原本的底層函式可以透過 @code{__wrapped__} 屬性存取。這對於要自我檢查 (introspection)、繞過快取或使用不同的快取重新包裝函式時非常有用。

快取會保留對引數和回傳值的參照，直到快取過時 (age out) 或快取被清除為止。

如果方法被快取起來，則 @code{self} 實例引數將包含在快取中。請參閱@ref{2a61,,如何快取方法呼叫？}

當最近的呼叫是即將發生之呼叫的最佳預測因子時（例如新聞伺服器上最受歡迎的文章往往每天都會發生變化），LRU (least recently used) 快取@footnote{https://en.wikipedia.org/wiki/Cache_replacement_policies#Least_Recently_Used_(LRU)}能發揮最好的效果。快取的大小限制可確保快取不會在長時間運行的行程（例如 Web 伺服器）上無限制地成長。

一般來說，僅當你想要重複使用先前計算的值時才應使用 LRU 快取。因此，快取具有 side-effects 的函式、需要在每次呼叫時建立不同可變物件的函式（例如產生器和非同步函式）或不純函式（impure function，例如 time() 或 random()）是沒有意義的。

靜態網頁內容的 LRU 快取範例：

@example
@@lru_cache(maxsize=32)
def get_pep(num):
    '取得 Python 改進提案的文字'
    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

使用快取來實作動態規劃 (dynamic programming)@footnote{https://en.wikipedia.org/wiki/Dynamic_programming} 技法以有效率地計算費波那契數 (Fibonacci numbers)@footnote{https://en.wikipedia.org/wiki/Fibonacci_number} 的範例：

@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


在 3.2 版被加入.



在 3.3 版的變更: 新增 `typed' 選項。



在 3.8 版的變更: 新增 `user_function' 選項。



在 3.9 版的變更: 新增 @code{cache_parameters()} 函式。

@end deffn

@geindex total_ordering() (於 functools 模組中)
@anchor{library/functools functools total_ordering}@anchor{113d}
@deffn {函式} @@functools.total_ordering

給定一個定義一個或多個 rich comparison 排序方法的類別，該類別裝飾器會提供其餘部分。這簡化了指定所有可能的 rich comparison 操作所涉及的工作：

類別必須定義 @ref{14a1,,__lt__()}、@ref{150b,,__le__()}、@ref{150c,,__gt__()} 或 @ref{150d,,__ge__()} 其中之一。此外，該類別應該提供 @ref{ce9,,__eq__()} 方法。

舉例來說：

@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 備註 
雖然此裝飾器可以輕鬆建立能好好運作的完全有序型別 (totally ordered types)，但它`的確'以衍生比較方法的執行速度較慢和堆疊追蹤 (stack trace) 較複雜做為其代價。如果效能基準測試顯示這是給定應用程式的效能瓶頸，那麼實作全部六種 rich comparison 方法通常能輕鬆地提升速度。
@end quotation
@end cartouche

@cartouche
@quotation 備註 
此裝飾器不會嘗試覆寫類別`或其超類別 (superclass)'中宣告的方法。這意味著如果超類別定義了比較運算子，`total_ordering' 將不會再次實作它，即使原始方法是抽象的。
@end quotation
@end cartouche


在 3.2 版被加入.



在 3.4 版的變更: 現在支援從底層對於未識別型別的比較函式回傳 @code{NotImplemented}。

@end deffn

@geindex Placeholder (於 functools 模組中)
@anchor{library/functools functools Placeholder}@anchor{216}
@deffn {資料} functools.Placeholder

A singleton object used as a sentinel to reserve a place
for positional arguments when calling @ref{217,,partial()}
and @ref{218,,partialmethod()}.


在 3.14 版被加入.

@end deffn

@geindex partial() (於 functools 模組中)
@anchor{library/functools functools partial}@anchor{217}
@deffn {函式} functools.partial (func, /, *args, **keywords)

回傳一個新的 @ref{219,,partial 物件}，它在被呼叫時的行為類似於使用位置引數 `args' 和關鍵字引數 `keywords' 呼叫的 `func'。如果向呼叫提供更多引數，它們將被附加到 `args'。如果提供了額外的關鍵字引數，它們會擴充並覆寫 `keywords'。大致相當於：

@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

@code{partial()} 用於部分函式應用程序，它「凍結」函式引數和/或關鍵字的某些部分，從而產生具有簡化簽名的新物件。例如，@ref{217,,partial()} 可用來建立可呼叫函式，其行為類似於 @ref{19b,,int()} 函式，其中 `base' 引數預設為 2：

@example
>>> basetwo = partial(int, base=2)
>>> basetwo.__doc__ = 'Convert base 2 string to an int.'
>>> basetwo('10010')
18
@end example

If @ref{216,,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{198,,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{216,,Placeholder} in positional arguments.

@end deffn

@geindex partialmethod (functools 中的類別)
@anchor{library/functools functools partialmethod}@anchor{218}
@deffn {類別} functools.partialmethod (func, /, *args, **keywords)

回傳一個新的 @ref{218,,partialmethod} 描述器 (descriptor)，其行為類似於 @ref{217,,partial}，只不過它被設計為用於方法定義而不能直接呼叫。

`func' 必須是一個 @ref{17fc,,descriptor} 或可呼叫物件（兩者兼具的物件，就像普通函式一樣，會被當作描述器處理）。

當 `func' 是描述器時（例如普通的 Python 函式、@ref{489,,classmethod()}、@ref{451,,staticmethod()}、@ref{1286,,abstractmethod()} 或 @ref{218,,partialmethod} 的另一個實例），對 @code{__get__} 的呼叫將被委託 (delegated) 給底層描述器，且一個適當的 @ref{219,,partial 物件}會被作為結果回傳。

當 `func' 是非描述器可呼叫物件 (non-descriptor callable) 時，會動態建立適當的繫結方法 (bound method)。當被作為方法使用時，其行為類似於普通的 Python 函式：`self' 引數將作為第一個位置引數插入，甚至會在提供給 @ref{218,,partialmethod} 建構函式的 `args' 和 `keywords' 的前面。

範例：

@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


在 3.4 版被加入.

@end deffn

@geindex reduce() (於 functools 模組中)
@anchor{library/functools functools reduce}@anchor{21a}
@deffn {函式} functools.reduce (function, iterable, /[, initial])

從左到右，將兩個引數的 `function' 累加運用到 `iterable' 的項目上，從而將可疊代物件減少為單一值。例如，@code{reduce(lambda x, y: x+y, [1, 2, 3, 4, 5])} 會計算出 @code{((((1+2)+3)+4)+5)}。左邊的引數 `x' 是累積值，右邊的引數 `y' 是來自 `iterable' 的更新值。如果可選的 `initial' 存在，則在計算中會將其放置在可疊代物件的項目之前，並在可疊代物件為空時作為預設值。如果未給定 `initial' 且 `iterable' 僅包含一個項目，則回傳第一個項目。

大致相當於：

@example
initial_missing = object()

def reduce(function, iterable, /, initial=initial_missing):
    it = iter(iterable)
    if initial is initial_missing:
        value = next(it)
    else:
        value = initial
    for element in it:
        value = function(value, element)
    return value
@end example

請參閱 @ref{be7,,itertools.accumulate()} 以了解產生 (yield) 所有中間值 (intermediate value) 的疊代器。


在 3.14 版的變更: `initial' is now supported as a keyword argument.

@end deffn

@geindex singledispatch() (於 functools 模組中)
@anchor{library/functools functools singledispatch}@anchor{844}
@deffn {函式} @@functools.singledispatch

將函式轉換為@ref{bdc,,單一調度}@ref{bdb,,泛型函式}。

若要定義泛型函式，請使用 @code{@@singledispatch} 裝飾器對其裝飾。請注意，使用 @code{@@singledispatch} 定義函式時，分派調度 (dispatch) 是發生在第一個引數的型別上：

@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{2a64}
若要為函式新增過載實作，請使用泛型函式的 @code{register()} 屬性，該屬性可用作裝飾器。對於以型別來註釋的函式，裝飾器將自動推斷第一個引數的型別：

@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{2a8,,typing.Union}：

@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

對於不使用型別註釋的程式碼，可以將適當的型別引數明確傳遞給裝飾器本身：

@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

若要啟用註冊 @ref{2a65,,lambdas} 和預先存在的函式，@ref{2a64,,register()} 屬性也能以函式形式使用：

@example
>>> def nothing(arg, verbose=False):
...     print("Nothing.")
...
>>> fun.register(type(None), nothing)
@end example

@ref{2a64,,register()} 屬性回傳未加裝飾器的函式。這讓使得裝飾器堆疊 (decorator stacking)、@ref{ab,,pickling} 以及為每個變體獨立建立單元測試成為可能：

@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

呼叫時，泛型函式會分派第一個引數的型別：

@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

如果沒有為特定型別註冊實作，則使用其方法解析順序 (method resolution order) 來尋找更通用的實作。用 @code{@@singledispatch} 裝飾的原始函式是為基底 @ref{c75,,object} 型別註冊的，這意味著如果沒有找到更好的實作就會使用它。

如果一個實作有被註冊到一個@ref{13b7,,抽象基底類別}，則基底類別的虛擬子類別將被分派到該實作：

@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

若要檢查泛型函式將為給定型別選擇哪種實作，請使用 @code{dispatch()} 屬性：

@example
>>> fun.dispatch(float)
<function fun_num at 0x1035a2840>
>>> fun.dispatch(dict)    # note: default implementation
<function fun at 0x103fe0000>
@end example

若要存取所有已註冊的實作，請使用唯讀 @code{registry} 屬性：

@example
>>> fun.registry.keys()
dict_keys([<class 'NoneType'>, <class 'int'>, <class 'object'>,
          <class 'decimal.Decimal'>, <class 'list'>,
          <class 'float'>])
>>> fun.registry[float]
<function fun_num at 0x1035a2840>
>>> fun.registry[object]
<function fun at 0x103fe0000>
@end example


在 3.4 版被加入.



在 3.7 版的變更: @ref{2a64,,register()} 屬性現在支援使用型別註釋。



在 3.11 版的變更: @ref{2a64,,register()} 屬性現在支援使用 @ref{2a8,,typing.Union} 型別註釋。

@end deffn

@geindex singledispatchmethod (functools 中的類別)
@anchor{library/functools functools singledispatchmethod}@anchor{bda}
@deffn {類別} functools.singledispatchmethod (func)

將方法轉換為@ref{bdc,,單一調度}@ref{bdb,,泛型函式}。

若要定義泛型方法，請使用 @code{@@singledispatchmethod} 裝飾器對其裝飾。請注意，使用 @code{@@singledispatchmethod} 定義函式時，分派調度是發生在第一個非 `self' 或非 `cls' 引數的型別上：

@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} 支援與其他裝飾器巢狀使用 (nesting)，例如 @ref{489,,@@classmethod}。請注意，為了使 @code{dispatcher.register} 可用，@code{singledispatchmethod} 必須是`最外面的'裝飾器。以下範例是 @code{Negator} 類別，其 @code{neg} 方法繫結到該類別，而不是該類別的實例：

@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

相同的模式可用於其他類似的裝飾器：@ref{451,,@@staticmethod}、@ref{1286,,@@~abc.abstractmethod} 等。


在 3.8 版被加入.

@end deffn

@geindex update_wrapper() (於 functools 模組中)
@anchor{library/functools functools update_wrapper}@anchor{121d}
@deffn {函式} functools.update_wrapper (wrapper, wrapped, assigned=WRAPPER_ASSIGNMENTS, updated=WRAPPER_UPDATES)

更新 `wrapper' 函式，使其看起來像 `wrapped' 函式。可選引數是元組，用於指定原始函式的哪些屬性直接賦值給包裝函式上的匹配屬性，以及包裝函式的哪些屬性使用原始函式中的對應屬性進行更新。這些引數的預設值是模組層級的常數 @code{WRAPPER_ASSIGNMENTS}（它賦值給包裝函式的 @ref{21fc,,__module__}、@ref{14d5,,__name__}、@ref{21fb,,__qualname__}、@ref{13d9,,__annotations__}、@ref{21ff,,__type_params__} 和 @ref{13da,,__doc__} 文件字串 (docstring））和 @code{WRAPPER_UPDATES}（更新包裝器函式的 @ref{14d3,,__dict__}，即實例字典）。

為了允許出於內省 (introspection) 和其他目的所對原始函式的存取（例如繞過快取裝飾器，如 @ref{bd9,,lru_cache()}），此函式會自動向包裝器新增 @code{__wrapped__} 屬性，該包裝器參照被包裝的函式。

此函式的主要用途是在 @ref{932,,decorator} 函式中，它包裝函式並回傳包裝器。如果包裝器函式未更新，則回傳函式的元資料 (metadata) 將反映包裝器定義而非原始函式定義，這通常不太會有幫助。

@ref{121d,,update_wrapper()} 可以與函式以外的可呼叫物件一起使用。被包裝的物件中缺少的 `assigned' 或 `updated' 中指定的任何屬性都將被忽略（即此函式不會嘗試在包裝器函式上設定它們）。如果包裝函式本身缺少 `updated' 中指定的任何屬性，仍然會引發 @ref{5e8,,AttributeError}。


在 3.2 版的變更: 現在會自動新增 @code{__wrapped__} 屬性。現在預設會複製 @ref{13d9,,__annotations__} 屬性。缺少的屬性不再觸發 @ref{5e8,,AttributeError}。



在 3.4 版的變更: @code{__wrapped__} 屬性現在都會參照包裝函式，即便函式有定義 @code{__wrapped__} 屬性。（參見 bpo-17482@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17482}）



在 3.12 版的變更: 現在預設會複製 @ref{21ff,,__type_params__} 屬性。

@end deffn

@geindex wraps() (於 functools 模組中)
@anchor{library/functools functools wraps}@anchor{1158}
@deffn {函式} @@functools.wraps (wrapped, assigned=WRAPPER_ASSIGNMENTS, updated=WRAPPER_UPDATES)

這是一個方便的函式，用於在定義包裝器函式時呼叫 @ref{121d,,update_wrapper()} 作為函式裝飾器。它相當於 @code{partial(update_wrapper, wrapped=wrapped, assigned=assigned, updated=updated)}。例如：

@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

如果不使用這個裝飾器工廠 (decorator factory)，範例函式的名稱將會是 @code{'wrapper'}，並且原始 @code{example()} 的文件字串將會遺失。
@end deffn

@menu
* partial 物件:: 

@end menu

@node partial 物件,,,functools --- 可呼叫物件上的高階函式與操作
@anchor{library/functools id1}@anchor{2a66}@anchor{library/functools partial-objects}@anchor{219}
@subsubsection @code{partial} 物件


@ref{217,,partial} 物件是由 @ref{217,,partial()} 所建立的可呼叫物件。它們有三個唯讀屬性：

@geindex func (functools.partial 的屬性)
@anchor{library/functools functools partial func}@anchor{2a67}
@deffn {屬性} partial.func

一個可呼叫的物件或函式。對 @ref{217,,partial} 物件的呼叫將被轉送到帶有新引數和關鍵字的 @ref{2a67,,func}。
@end deffn

@geindex args (functools.partial 的屬性)
@anchor{library/functools functools partial args}@anchor{2a68}
@deffn {屬性} partial.args

最左邊的位置引數將會被加入到提供給 @ref{217,,partial} 物件呼叫的位置引數的前面。
@end deffn

@geindex keywords (functools.partial 的屬性)
@anchor{library/functools functools partial keywords}@anchor{2a69}
@deffn {屬性} partial.keywords

呼叫 @ref{217,,partial} 物件時將提供的關鍵字引數。
@end deffn

@ref{217,,partial} 物件與@ref{596,,函式物件}類似，因為它們是可呼叫的、可弱參照的 (weak referencable) 且可以具有屬性的。但有一些重要的區別，例如，@ref{1261,,__name__} 和 @ref{b18,,__doc__} 屬性不會自動建立。

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node operator --- 標準運算子替代函式,,functools --- 可呼叫物件上的高階函式與操作,函式程式設計模組
@anchor{library/operator doc}@anchor{2a6a}@anchor{library/operator module-operator}@anchor{a3}@anchor{library/operator operator-standard-operators-as-functions}@anchor{2a6b}@anchor{library/operator translation-repo}@anchor{2a6c}
@subsection @code{operator} --- 標準運算子替代函式


@geindex module; operator

`原始碼：'Lib/operator.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/operator.py}

@c import operator
@c from operator import itemgetter, iadd


__________________________________________________________________


@ref{a3,,operator} module（模組）提供了一套與 Python 原生運算子對應的高效率函式。例如，@code{operator.add(x, y)} 與表示式 @code{x+y} 相同。許多函式名與特殊方法名相同，只是沒有雙底線。為了向後相容，許多包含雙底線的函式被保留了下來，但為了易於表達，建議使用沒有雙底線的函式。

函式種類有物件的比較運算、邏輯運算、數學運算以及序列運算。

物件比較函式適用於所有物件，函式根據它們對應的 rich comparison 運算子命名：

@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{2a6d}
@deffn {函式} operator.lt (a, b)
@anchor{library/operator operator le}@anchor{2a6e}
@deffnx {函式} operator.le (a, b)
@anchor{library/operator operator eq}@anchor{2a6f}
@deffnx {函式} operator.eq (a, b)
@anchor{library/operator operator ne}@anchor{2a70}
@deffnx {函式} operator.ne (a, b)
@anchor{library/operator operator ge}@anchor{2a71}
@deffnx {函式} operator.ge (a, b)
@anchor{library/operator operator gt}@anchor{2a72}
@deffnx {函式} operator.gt (a, b)
@anchor{library/operator operator __lt__}@anchor{2a73}
@deffnx {函式} operator.__lt__ (a, b)
@anchor{library/operator operator __le__}@anchor{2a74}
@deffnx {函式} operator.__le__ (a, b)
@anchor{library/operator operator __eq__}@anchor{2a75}
@deffnx {函式} operator.__eq__ (a, b)
@anchor{library/operator operator __ne__}@anchor{2a76}
@deffnx {函式} operator.__ne__ (a, b)
@anchor{library/operator operator __ge__}@anchor{2a77}
@deffnx {函式} operator.__ge__ (a, b)
@anchor{library/operator operator __gt__}@anchor{2a78}
@deffnx {函式} operator.__gt__ (a, b)

在 `a' 和 `b' 之間進行 "rich comparison"。具體來說，@code{lt(a, b)} 與 @code{a < b} 相同，@code{le(a, b)} 與 @code{a <= b} 相同，@code{eq(a, b)} 與 @code{a == b} 相同，@code{ne(a, b)} 與 @code{a != b} 相同，@code{gt(a, b)} 與 @code{a > b} 相同，@code{ge(a, b)} 與 @code{a >= b} 相同。注意這些函式可以回傳任何值，無論它是否可當作 boolean（布林）值。關於 rich comparison 的更多資訊請參考 @ref{2378,,Comparisons}。
@end deffn

邏輯運算通常也適用於所有物件，並且支援真值檢測、識別性測試和 boolean 運算：

@geindex not_() (於 operator 模組中)
@geindex __not__() (於 operator 模組中)
@anchor{library/operator operator not_}@anchor{2a79}
@deffn {函式} operator.not_ (obj)
@anchor{library/operator operator __not__}@anchor{2a7a}
@deffnx {函式} operator.__not__ (obj)

回傳 @ref{2382,,not} `obj' 的結果。（請注意物件實例並沒有 @code{__not__()} method（方法）；只有直譯器核心定義此操作。結果會受 @ref{14d6,,__bool__()} 和 @ref{2260,,__len__()} method 影響。）
@end deffn

@geindex truth() (於 operator 模組中)
@anchor{library/operator operator truth}@anchor{2a7b}
@deffn {函式} operator.truth (obj)

如果 `obj' 為真值則回傳 @ref{e02,,True}，否則回傳 @ref{d23,,False}。這等價於使用 @ref{3c1,,bool} 建構函式。
@end deffn

@geindex is_() (於 operator 模組中)
@anchor{library/operator operator is_}@anchor{2a7c}
@deffn {函式} operator.is_ (a, b)

回傳 @code{a is b}。測試物件識別性。
@end deffn

@geindex is_not() (於 operator 模組中)
@anchor{library/operator operator is_not}@anchor{2a7d}
@deffn {函式} operator.is_not (a, b)

回傳 @code{a is not b}。測試物件識別性。
@end deffn

@geindex is_none() (於 operator 模組中)
@anchor{library/operator operator is_none}@anchor{255}
@deffn {函式} operator.is_none (a)

回傳 @code{a is None}。測試物件識別性。


在 3.14 版被加入.

@end deffn

@geindex is_not_none() (於 operator 模組中)
@anchor{library/operator operator is_not_none}@anchor{256}
@deffn {函式} operator.is_not_none (a)

回傳 @code{a is not None}。測試物件識別性。


在 3.14 版被加入.

@end deffn

數學和位元運算的種類是最多的：

@geindex abs() (於 operator 模組中)
@geindex __abs__() (於 operator 模組中)
@anchor{library/operator operator abs}@anchor{2a7e}
@deffn {函式} operator.abs (obj)
@anchor{library/operator operator __abs__}@anchor{2a7f}
@deffnx {函式} operator.__abs__ (obj)

回傳 `obj' 的絕對值。
@end deffn

@geindex add() (於 operator 模組中)
@geindex __add__() (於 operator 模組中)
@anchor{library/operator operator add}@anchor{2a80}
@deffn {函式} operator.add (a, b)
@anchor{library/operator operator __add__}@anchor{2a81}
@deffnx {函式} operator.__add__ (a, b)

對於數字 `a' 和 `b'，回傳 @code{a + b}。
@end deffn

@geindex and_() (於 operator 模組中)
@geindex __and__() (於 operator 模組中)
@anchor{library/operator operator and_}@anchor{2a82}
@deffn {函式} operator.and_ (a, b)
@anchor{library/operator operator __and__}@anchor{2a83}
@deffnx {函式} operator.__and__ (a, b)

回傳 `x' 和 `y' 位元運算與 (and) 的結果。
@end deffn

@geindex floordiv() (於 operator 模組中)
@geindex __floordiv__() (於 operator 模組中)
@anchor{library/operator operator floordiv}@anchor{2a84}
@deffn {函式} operator.floordiv (a, b)
@anchor{library/operator operator __floordiv__}@anchor{2a85}
@deffnx {函式} operator.__floordiv__ (a, b)

回傳 @code{a // b}。
@end deffn

@geindex index() (於 operator 模組中)
@geindex __index__() (於 operator 模組中)
@anchor{library/operator operator index}@anchor{1bc4}
@deffn {函式} operator.index (a)
@anchor{library/operator operator __index__}@anchor{2a86}
@deffnx {函式} operator.__index__ (a)

回傳 `a' 轉換為整數的結果。等價於 @code{a.__index__()}。


在 3.10 版的變更: 結果總是 @ref{19b,,int} 型別。在過去的版本中，結果可能為 @code{int} 子類別的實例。

@end deffn

@geindex inv() (於 operator 模組中)
@geindex invert() (於 operator 模組中)
@geindex __inv__() (於 operator 模組中)
@geindex __invert__() (於 operator 模組中)
@anchor{library/operator operator inv}@anchor{2a87}
@deffn {函式} operator.inv (obj)
@anchor{library/operator operator invert}@anchor{2a88}
@deffnx {函式} operator.invert (obj)
@anchor{library/operator operator __inv__}@anchor{2a89}
@deffnx {函式} operator.__inv__ (obj)
@anchor{library/operator operator __invert__}@anchor{2a8a}
@deffnx {函式} operator.__invert__ (obj)

回傳數字 `obj' 按位元取反 (inverse) 的結果。這等價於 @code{~obj}。
@end deffn

@geindex lshift() (於 operator 模組中)
@geindex __lshift__() (於 operator 模組中)
@anchor{library/operator operator lshift}@anchor{2a8b}
@deffn {函式} operator.lshift (a, b)
@anchor{library/operator operator __lshift__}@anchor{2a8c}
@deffnx {函式} operator.__lshift__ (a, b)

回傳 `a' 左移 `b' 位的結果。
@end deffn

@geindex mod() (於 operator 模組中)
@geindex __mod__() (於 operator 模組中)
@anchor{library/operator operator mod}@anchor{2a8d}
@deffn {函式} operator.mod (a, b)
@anchor{library/operator operator __mod__}@anchor{2a8e}
@deffnx {函式} operator.__mod__ (a, b)

回傳 @code{a % b}。
@end deffn

@geindex mul() (於 operator 模組中)
@geindex __mul__() (於 operator 模組中)
@anchor{library/operator operator mul}@anchor{2a5c}
@deffn {函式} operator.mul (a, b)
@anchor{library/operator operator __mul__}@anchor{2a8f}
@deffnx {函式} operator.__mul__ (a, b)

對於數字 `a' 和 `b'，回傳 @code{a * b}。
@end deffn

@geindex matmul() (於 operator 模組中)
@geindex __matmul__() (於 operator 模組中)
@anchor{library/operator operator matmul}@anchor{1030}
@deffn {函式} operator.matmul (a, b)
@anchor{library/operator operator __matmul__}@anchor{2a90}
@deffnx {函式} operator.__matmul__ (a, b)

回傳 @code{a @@ b}。


在 3.5 版被加入.

@end deffn

@geindex neg() (於 operator 模組中)
@geindex __neg__() (於 operator 模組中)
@anchor{library/operator operator neg}@anchor{2a91}
@deffn {函式} operator.neg (obj)
@anchor{library/operator operator __neg__}@anchor{2a92}
@deffnx {函式} operator.__neg__ (obj)

回傳 `obj' 取負值的結果 (@code{-obj})。
@end deffn

@geindex or_() (於 operator 模組中)
@geindex __or__() (於 operator 模組中)
@anchor{library/operator operator or_}@anchor{2a93}
@deffn {函式} operator.or_ (a, b)
@anchor{library/operator operator __or__}@anchor{2a94}
@deffnx {函式} operator.__or__ (a, b)

回傳 `a' 和 `b' 按位元或 (or) 的結果。
@end deffn

@geindex pos() (於 operator 模組中)
@geindex __pos__() (於 operator 模組中)
@anchor{library/operator operator pos}@anchor{2a95}
@deffn {函式} operator.pos (obj)
@anchor{library/operator operator __pos__}@anchor{2a96}
@deffnx {函式} operator.__pos__ (obj)

回傳 `obj' 取正的結果 (@code{+obj})。
@end deffn

@geindex pow() (於 operator 模組中)
@geindex __pow__() (於 operator 模組中)
@anchor{library/operator operator pow}@anchor{2a97}
@deffn {函式} operator.pow (a, b)
@anchor{library/operator operator __pow__}@anchor{2a98}
@deffnx {函式} operator.__pow__ (a, b)

對於數字 `a' 和 `b'，回傳 @code{a ** b}。
@end deffn

@geindex rshift() (於 operator 模組中)
@geindex __rshift__() (於 operator 模組中)
@anchor{library/operator operator rshift}@anchor{2a99}
@deffn {函式} operator.rshift (a, b)
@anchor{library/operator operator __rshift__}@anchor{2a9a}
@deffnx {函式} operator.__rshift__ (a, b)

回傳 `a' 右移 `b' 位的結果。
@end deffn

@geindex sub() (於 operator 模組中)
@geindex __sub__() (於 operator 模組中)
@anchor{library/operator operator sub}@anchor{2a9b}
@deffn {函式} operator.sub (a, b)
@anchor{library/operator operator __sub__}@anchor{2a9c}
@deffnx {函式} operator.__sub__ (a, b)

回傳 @code{a - b}。
@end deffn

@geindex truediv() (於 operator 模組中)
@geindex __truediv__() (於 operator 模組中)
@anchor{library/operator operator truediv}@anchor{2a9d}
@deffn {函式} operator.truediv (a, b)
@anchor{library/operator operator __truediv__}@anchor{2a9e}
@deffnx {函式} operator.__truediv__ (a, b)

回傳 @code{a / b}，例如 2/3 將等於 .66 而不是 0。這也被稱為「真」除法。
@end deffn

@geindex xor() (於 operator 模組中)
@geindex __xor__() (於 operator 模組中)
@anchor{library/operator operator xor}@anchor{2a9f}
@deffn {函式} operator.xor (a, b)
@anchor{library/operator operator __xor__}@anchor{2aa0}
@deffnx {函式} operator.__xor__ (a, b)

回傳 `a' 和 `b' 按位元異或 (exclusive or) 的結果。
@end deffn

適用於序列的操作（其中一些也適用於對映 (mapping)），包括：

@geindex concat() (於 operator 模組中)
@geindex __concat__() (於 operator 模組中)
@anchor{library/operator operator concat}@anchor{2aa1}
@deffn {函式} operator.concat (a, b)
@anchor{library/operator operator __concat__}@anchor{2aa2}
@deffnx {函式} operator.__concat__ (a, b)

對於序列 `a' 和 `b'，回傳 @code{a + b}。
@end deffn

@geindex contains() (於 operator 模組中)
@geindex __contains__() (於 operator 模組中)
@anchor{library/operator operator contains}@anchor{ace}
@deffn {函式} operator.contains (a, b)
@anchor{library/operator operator __contains__}@anchor{2aa3}
@deffnx {函式} operator.__contains__ (a, b)

回傳 @code{b in a} 檢測的結果。請注意運算元是反序的。
@end deffn

@geindex countOf() (於 operator 模組中)
@anchor{library/operator operator countOf}@anchor{ad0}
@deffn {函式} operator.countOf (a, b)

回傳 `b' 在 `a' 中的出現次數。
@end deffn

@geindex delitem() (於 operator 模組中)
@geindex __delitem__() (於 operator 模組中)
@anchor{library/operator operator delitem}@anchor{2aa4}
@deffn {函式} operator.delitem (a, b)
@anchor{library/operator operator __delitem__}@anchor{2aa5}
@deffnx {函式} operator.__delitem__ (a, b)

移除 `a' 中索引為 `b' 的值。
@end deffn

@geindex getitem() (於 operator 模組中)
@geindex __getitem__() (於 operator 模組中)
@anchor{library/operator operator getitem}@anchor{2aa6}
@deffn {函式} operator.getitem (a, b)
@anchor{library/operator operator __getitem__}@anchor{2aa7}
@deffnx {函式} operator.__getitem__ (a, b)

回傳 `a' 中索引為 `b' 的值。
@end deffn

@geindex indexOf() (於 operator 模組中)
@anchor{library/operator operator indexOf}@anchor{acf}
@deffn {函式} operator.indexOf (a, b)

回傳 `b' 在 `a' 中首次出現所在的索引。
@end deffn

@geindex setitem() (於 operator 模組中)
@geindex __setitem__() (於 operator 模組中)
@anchor{library/operator operator setitem}@anchor{2aa8}
@deffn {函式} operator.setitem (a, b, c)
@anchor{library/operator operator __setitem__}@anchor{2aa9}
@deffnx {函式} operator.__setitem__ (a, b, c)

將 `a' 中索引為 `b' 的值設為 `c'。
@end deffn

@geindex length_hint() (於 operator 模組中)
@anchor{library/operator operator length_hint}@anchor{1168}
@deffn {函式} operator.length_hint (obj, default=0)

回傳物件 `obj' 的估計長度。首先嘗試回傳其實際長度，再使用 @ref{1109,,object.__length_hint__()} 得出估計值，最後才是回傳預設值。


在 3.4 版被加入.

@end deffn

以下操作適用於可呼叫物件：

@geindex call() (於 operator 模組中)
@geindex __call__() (於 operator 模組中)
@anchor{library/operator operator call}@anchor{1b34}
@deffn {函式} operator.call (obj, /, *args, **kwargs)
@anchor{library/operator operator __call__}@anchor{2aaa}
@deffnx {函式} operator.__call__ (obj, /, *args, **kwargs)

回傳 @code{obj(*args, **kwargs)}。


在 3.11 版被加入.

@end deffn

@ref{a3,,operator} module 還定義了一些用於常規屬性和條目查詢的工具。這些工具適合用來編寫快速欄位提取器以作為 @ref{19f,,map()}、@ref{dc2,,sorted()}、@ref{2a57,,itertools.groupby()} 或其他需要函式引數的函式之引數。

@geindex attrgetter() (於 operator 模組中)
@anchor{library/operator operator attrgetter}@anchor{102e}
@deffn {函式} operator.attrgetter (attr)

@deffnx {函式} operator.attrgetter (*attrs)

回傳一個可從運算元中取得 `attr' 的可呼叫 (callable) 物件。如果請求了一個以上的屬性，則回傳一個包含屬性的 tupple（元組）。屬性名稱還可包含點號。例如：


@itemize *

@item 
在 @code{f = attrgetter('name')} 之後，呼叫 @code{f(b)} 將回傳 @code{b.name}。

@item 
在 @code{f = attrgetter('name', 'date')} 之後，呼叫 @code{f(b)} 將回傳 @code{(b.name, b.date)}。

@item 
在 @code{f = attrgetter('name.first', 'name.last')} 之後，呼叫 @code{f(b)} 將回傳 @code{(b.name.first, b.name.last)}。
@end itemize

等價於：

@example
def attrgetter(*items):
    if any(not isinstance(item, str) for item in items):
        raise TypeError('屬性名稱必須是一個字串')
    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{c4e}
@deffn {函式} operator.itemgetter (item)

@deffnx {函式} operator.itemgetter (*items)

回傳一個使用運算元的 @ref{582,,__getitem__()} 方法從運算元中取得 `item' 的可呼叫物件。如果指定了多個條目，則回傳一個查詢值的 tupple。例如：


@itemize *

@item 
在 @code{f = itemgetter(2)} 之後，呼叫 @code{f(r)} 將回傳 @code{r[2]}。

@item 
在 @code{g = itemgetter(2, 5, 3)} 之後，呼叫 @code{g(r)} 將回傳 @code{(r[2], r[5], r[3])}。
@end itemize

等價於：

@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

傳入的條目可以為運算元的 @ref{582,,__getitem__()} 所接受的任何型別。dictionary（字典）接受任意@ref{81d,,可雜湊}的值。list、tupple 和字串接受索引或切片：

@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

使用 @ref{c4e,,itemgetter()} 從 tuple 中提取特定欄位的例子：

@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{102f}
@deffn {函式} operator.methodcaller (name, /, *args, **kwargs)

回傳一個在運算元上呼叫 `name' method 的可呼叫物件。如果給定額外的引數和/或關鍵字引數，它們也將被傳給該 method。例如：


@itemize *

@item 
在 @code{f = methodcaller('name')} 之後，呼叫 @code{f(b)} 將回傳 @code{b.name()}。

@item 
在 @code{f = methodcaller('name', 'foo', bar=1)} 之後，呼叫 @code{f(b)} 將回傳 @code{b.name('foo', bar=1)}。
@end itemize

等價於：

@example
def methodcaller(name, /, *args, **kwargs):
    def caller(obj):
        return getattr(obj, name)(*args, **kwargs)
    return caller
@end example
@end deffn

@menu
* 運算子與函式間的對映:: 
* 原地 (in-place) 運算子: 原地 in-place 運算子. 

@end menu

@node 運算子與函式間的對映,原地 in-place 運算子,,operator --- 標準運算子替代函式
@anchor{library/operator mapping-operators-to-functions}@anchor{2aab}@anchor{library/operator operator-map}@anchor{2aac}
@subsubsection 運算子與函式間的對映


以下表格表示了抽象運算是如何對應於 Python 語法中的運算子和 @ref{a3,,operator} module中的函式。


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

運算

@tab

語法

@tab

函式

@item

加法

@tab

@code{a + b}

@tab

@code{add(a, b)}

@item

字串串接

@tab

@code{seq1 + seq2}

@tab

@code{concat(seq1, seq2)}

@item

包含性檢測

@tab

@code{obj in seq}

@tab

@code{contains(seq, obj)}

@item

除法

@tab

@code{a / b}

@tab

@code{truediv(a, b)}

@item

除法

@tab

@code{a // b}

@tab

@code{floordiv(a, b)}

@item

按位元與 (And)

@tab

@code{a & b}

@tab

@code{and_(a, b)}

@item

按位元互斥或 (Exclusive Or)

@tab

@code{a ^ b}

@tab

@code{xor(a, b)}

@item

按位元取反 (Inversion)

@tab

@code{~ a}

@tab

@code{invert(a)}

@item

按位元或 (Or)

@tab

@code{a | b}

@tab

@code{or_(a, b)}

@item

取冪

@tab

@code{a ** b}

@tab

@code{pow(a, b)}

@item

識別性

@tab

@code{a is b}

@tab

@code{is_(a, b)}

@item

識別性

@tab

@code{a is not b}

@tab

@code{is_not(a, b)}

@item

識別性

@tab

@code{a is None}

@tab

@code{is_none(a)}

@item

識別性

@tab

@code{a is not None}

@tab

@code{is_not_none(a)}

@item

索引賦值

@tab

@code{obj[k] = v}

@tab

@code{setitem(obj, k, v)}

@item

索引刪除

@tab

@code{del obj[k]}

@tab

@code{delitem(obj, k)}

@item

索引取值

@tab

@code{obj[k]}

@tab

@code{getitem(obj, k)}

@item

左移

@tab

@code{a << b}

@tab

@code{lshift(a, b)}

@item

模除 (Modulo)

@tab

@code{a % b}

@tab

@code{mod(a, b)}

@item

乘法

@tab

@code{a * b}

@tab

@code{mul(a, b)}

@item

矩陣乘法

@tab

@code{a @@ b}

@tab

@code{matmul(a, b)}

@item

反相（算術）

@tab

@code{- a}

@tab

@code{neg(a)}

@item

反相（邏輯）

@tab

@code{not a}

@tab

@code{not_(a)}

@item

正數

@tab

@code{+ a}

@tab

@code{pos(a)}

@item

右移

@tab

@code{a >> b}

@tab

@code{rshift(a, b)}

@item

切片賦值

@tab

@code{seq[i:j] = values}

@tab

@code{setitem(seq, slice(i, j), values)}

@item

切片刪除

@tab

@code{del seq[i:j]}

@tab

@code{delitem(seq, slice(i, j))}

@item

切片取值

@tab

@code{seq[i:j]}

@tab

@code{getitem(seq, slice(i, j))}

@item

字串格式化

@tab

@code{s % obj}

@tab

@code{mod(s, obj)}

@item

減法

@tab

@code{a - b}

@tab

@code{sub(a, b)}

@item

真值檢測

@tab

@code{obj}

@tab

@code{truth(obj)}

@item

比較大小

@tab

@code{a < b}

@tab

@code{lt(a, b)}

@item

比較大小

@tab

@code{a <= b}

@tab

@code{le(a, b)}

@item

相等性

@tab

@code{a == b}

@tab

@code{eq(a, b)}

@item

不等性

@tab

@code{a != b}

@tab

@code{ne(a, b)}

@item

比較大小

@tab

@code{a >= b}

@tab

@code{ge(a, b)}

@item

比較大小

@tab

@code{a > b}

@tab

@code{gt(a, b)}

@end multitable


@node 原地 in-place 運算子,,運算子與函式間的對映,operator --- 標準運算子替代函式
@anchor{library/operator in-place-operators}@anchor{2aad}
@subsubsection 原地 (in-place) 運算子


許多運算都有「原地」版本。以下列出的是提供對原地運算子（與一般語法相比）更底層存取的函式，例如 @ref{2aae,,statement} @code{x += y} 相當於 @code{x = operator.iadd(x, y)}。換一種方式來講就是 @code{z = operator.iadd(x, y)} 等價於複合陳述式 @code{z = x; z += y}。

在這些例子中，請注意當呼叫一個原地方法時，運算和賦值是分成兩個步驟來執行的。下面列出的原地函式只執行第一步，即呼叫原地方法，第二步賦值則不加處理。

對於不可變 (immutable) 的目標例如字串、數字和 tupple，更新的值會被計算，但不會被再被賦值給輸入變數：

@example
>>> a = 'hello'
>>> iadd(a, ' world')
'hello world'
>>> a
'hello'
@end example

對於可變 (mutable) 的目標例如 list 和 dictionary，原地方法將執行更新，因此不需要後續賦值操作：

@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{2aaf}
@deffn {函式} operator.iadd (a, b)
@anchor{library/operator operator __iadd__}@anchor{2ab0}
@deffnx {函式} operator.__iadd__ (a, b)

@code{a = iadd(a, b)} 等價於 @code{a += b}。
@end deffn

@geindex iand() (於 operator 模組中)
@geindex __iand__() (於 operator 模組中)
@anchor{library/operator operator iand}@anchor{2ab1}
@deffn {函式} operator.iand (a, b)
@anchor{library/operator operator __iand__}@anchor{2ab2}
@deffnx {函式} operator.__iand__ (a, b)

@code{a = iand(a, b)} 等價於 @code{a &= b}。
@end deffn

@geindex iconcat() (於 operator 模組中)
@geindex __iconcat__() (於 operator 模組中)
@anchor{library/operator operator iconcat}@anchor{2ab3}
@deffn {函式} operator.iconcat (a, b)
@anchor{library/operator operator __iconcat__}@anchor{2ab4}
@deffnx {函式} operator.__iconcat__ (a, b)

@code{a = iconcat(a, b)} 等價於 @code{a += b}，其中 `a' 和 `b' 為序列。
@end deffn

@geindex ifloordiv() (於 operator 模組中)
@geindex __ifloordiv__() (於 operator 模組中)
@anchor{library/operator operator ifloordiv}@anchor{2ab5}
@deffn {函式} operator.ifloordiv (a, b)
@anchor{library/operator operator __ifloordiv__}@anchor{2ab6}
@deffnx {函式} operator.__ifloordiv__ (a, b)

@code{a = ifloordiv(a, b)} 等價於 @code{a //= b}。
@end deffn

@geindex ilshift() (於 operator 模組中)
@geindex __ilshift__() (於 operator 模組中)
@anchor{library/operator operator ilshift}@anchor{2ab7}
@deffn {函式} operator.ilshift (a, b)
@anchor{library/operator operator __ilshift__}@anchor{2ab8}
@deffnx {函式} operator.__ilshift__ (a, b)

@code{a = ilshift(a, b)} 等價於 @code{a <<= b}。
@end deffn

@geindex imod() (於 operator 模組中)
@geindex __imod__() (於 operator 模組中)
@anchor{library/operator operator imod}@anchor{2ab9}
@deffn {函式} operator.imod (a, b)
@anchor{library/operator operator __imod__}@anchor{2aba}
@deffnx {函式} operator.__imod__ (a, b)

@code{a = imod(a, b)} 等價於 @code{a %= b}。
@end deffn

@geindex imul() (於 operator 模組中)
@geindex __imul__() (於 operator 模組中)
@anchor{library/operator operator imul}@anchor{2abb}
@deffn {函式} operator.imul (a, b)
@anchor{library/operator operator __imul__}@anchor{2abc}
@deffnx {函式} operator.__imul__ (a, b)

@code{a = imul(a, b)} 等價於 @code{a *= b}。
@end deffn

@geindex imatmul() (於 operator 模組中)
@geindex __imatmul__() (於 operator 模組中)
@anchor{library/operator operator imatmul}@anchor{1031}
@deffn {函式} operator.imatmul (a, b)
@anchor{library/operator operator __imatmul__}@anchor{2abd}
@deffnx {函式} operator.__imatmul__ (a, b)

@code{a = imatmul(a, b)} 等價於 @code{a @@= b}。


在 3.5 版被加入.

@end deffn

@geindex ior() (於 operator 模組中)
@geindex __ior__() (於 operator 模組中)
@anchor{library/operator operator ior}@anchor{2abe}
@deffn {函式} operator.ior (a, b)
@anchor{library/operator operator __ior__}@anchor{2abf}
@deffnx {函式} operator.__ior__ (a, b)

@code{a = ior(a, b)} 等價於 @code{a |= b}。
@end deffn

@geindex ipow() (於 operator 模組中)
@geindex __ipow__() (於 operator 模組中)
@anchor{library/operator operator ipow}@anchor{2ac0}
@deffn {函式} operator.ipow (a, b)
@anchor{library/operator operator __ipow__}@anchor{2ac1}
@deffnx {函式} operator.__ipow__ (a, b)

@code{a = ipow(a, b)} 等價於 @code{a **= b}。
@end deffn

@geindex irshift() (於 operator 模組中)
@geindex __irshift__() (於 operator 模組中)
@anchor{library/operator operator irshift}@anchor{2ac2}
@deffn {函式} operator.irshift (a, b)
@anchor{library/operator operator __irshift__}@anchor{2ac3}
@deffnx {函式} operator.__irshift__ (a, b)

@code{a = irshift(a, b)} 等價於 @code{a >>= b}。
@end deffn

@geindex isub() (於 operator 模組中)
@geindex __isub__() (於 operator 模組中)
@anchor{library/operator operator isub}@anchor{2ac4}
@deffn {函式} operator.isub (a, b)
@anchor{library/operator operator __isub__}@anchor{2ac5}
@deffnx {函式} operator.__isub__ (a, b)

@code{a = isub(a, b)} 等價於 @code{a -= b}。
@end deffn

@geindex itruediv() (於 operator 模組中)
@geindex __itruediv__() (於 operator 模組中)
@anchor{library/operator operator itruediv}@anchor{2ac6}
@deffn {函式} operator.itruediv (a, b)
@anchor{library/operator operator __itruediv__}@anchor{2ac7}
@deffnx {函式} operator.__itruediv__ (a, b)

@code{a = itruediv(a, b)} 等價於 @code{a /= b}。
@end deffn

@geindex ixor() (於 operator 模組中)
@geindex __ixor__() (於 operator 模組中)
@anchor{library/operator operator ixor}@anchor{2ac8}
@deffn {函式} operator.ixor (a, b)
@anchor{library/operator operator __ixor__}@anchor{2ac9}
@deffnx {函式} operator.__ixor__ (a, b)

@code{a = ixor(a, b)} 等價於 @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 檔案與目錄存取,資料持久性 Data Persistence,函式程式設計模組,Python 標準函式庫 Standard Library
@anchor{library/filesys doc}@anchor{2aca}@anchor{library/filesys file-and-directory-access}@anchor{2acb}@anchor{library/filesys filesys}@anchor{2acc}@anchor{library/filesys translation-repo}@anchor{2acd}
@section 檔案與目錄存取


本章中描述的 module（模組）用於處理硬碟檔案和目錄。例如，有一些 module 用於讀取檔案的屬性、以可攜 (portable) 方式操作路徑以及建立暫存檔。本章中的完整 module 清單是：

@menu
* pathlib: pathlib --- 物件導向檔案系統路徑. 物件導向檔案系統路徑
* os.path: os path --- 常見的路徑名操作. 常見的路徑名操作
* stat: stat --- 直譯 stat 的結果. 直譯 stat() 的結果
* filecmp: filecmp --- 檔案與目錄比較. 檔案與目錄比較
* tempfile: tempfile --- 生成臨時檔案和目錄. 生成臨時檔案和目錄
* glob: glob --- Unix 風格的路徑名稱模式擴展. Unix 風格的路徑名稱模式擴展
* fnmatch: fnmatch --- Unix 檔案名稱模式比對. Unix 檔案名稱模式比對
* linecache: linecache --- 隨機存取文字列. 隨機存取文字列
* shutil — 高階檔案操作:: 

@end menu

@node pathlib --- 物件導向檔案系統路徑,os path --- 常見的路徑名操作,,檔案與目錄存取
@anchor{library/pathlib doc}@anchor{2ace}@anchor{library/pathlib module-pathlib}@anchor{a8}@anchor{library/pathlib pathlib-object-oriented-filesystem-paths}@anchor{2acf}
@subsection @code{pathlib} --- 物件導向檔案系統路徑


@geindex module; pathlib


在 3.4 版被加入.


`原始碼：'Lib/pathlib/@footnote{https://github.com/python/cpython/tree/3.14/Lib/pathlib/}

@geindex path（路徑）;operations（操作）


__________________________________________________________________


此模組提供代表檔案系統路徑的類別，能適用不同作業系統的語意。路徑類別分成兩種，一種是@ref{2ad0,,純路徑 (pure paths)}，提供沒有 I/O 的單純計算操作，另一種是@ref{2ad1,,實體路徑 (concrete paths)}，繼承自純路徑但也提供 IO 操作。

@image{python-figures/pathlib-inheritance,,,顯示 pathlib 中可用類別的繼承圖。 最基礎的類別是 PurePath，它有三個直接子類別： PurePosixPath、PureWindowsPath 和 Path。除了這四個類別之外， 還有兩個類別使用多重繼承： PosixPath 繼承自 PurePosixPath 和 Path，而 WindowsPath 繼承自 PureWindowsPath 和 Path。,png}

如果你之前從未使用過此模組或不確定哪個類別適合你的任務，那你需要的最有可能是 @ref{266,,Path}。它針對程式執行所在的平台實例化一個@ref{2ad1,,實體路徑}。

純路徑在某些特殊情境下是有用的，例如：


@enumerate 

@item 
如果你想在 Unix 機器上處理 Windows 路徑（或反過來），你無法在 Unix 上實例化 @ref{2ad2,,WindowsPath}，但你可以實例化 @ref{19c7,,PureWindowsPath}。

@item 
你想確保你的程式在操作路徑的時候不會真的存取到 OS。在這個情況下，實例化其中一種純路徑類別可能是有用的，因為它們不會有任何存取 OS 的操作。
@end enumerate


@subsubheading 也參考


@geindex Python Enhancement Proposals; PEP 428
PEP 428@footnote{https://peps.python.org/pep-0428/}：pathlib 模組 -- 物件導向檔案系統路徑。



@subsubheading 也參考


針對字串上的底層路徑操作，你也可以使用 @ref{a6,,os.path} 模組。


@menu
* 基本用法:: 
* 例外: 例外<5>. 
* 純路徑:: 
* 實體路徑:: 
* 模式語言 (pattern language): 模式語言 pattern language. 
* 與 glob 模組的比較:: 
* 與 os 和 os.path 模組的比較: 與 os 和 os path 模組的比較. 
* Protocols:: 

@end menu

@node 基本用法,例外<5>,,pathlib --- 物件導向檔案系統路徑
@anchor{library/pathlib basic-use}@anchor{2ad3}
@subsubsection 基本用法


匯入主要類別：

@example
>>> from pathlib import Path
@end example

列出子目錄：

@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

在目前目錄樹下列出 Python 原始碼檔案：

@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

瀏覽目錄樹內部：

@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

查詢路徑屬性：

@example
>>> q.exists()
True
>>> q.is_dir()
False
@end example

開啟檔案：

@example
>>> with q.open() as f: f.readline()
...
'#!/bin/bash\n'
@end example

@node 例外<5>,純路徑,基本用法,pathlib --- 物件導向檔案系統路徑
@anchor{library/pathlib exceptions}@anchor{2ad4}
@subsubsection 例外


@geindex UnsupportedOperation
@anchor{library/pathlib pathlib UnsupportedOperation}@anchor{52e}
@deffn {例外} pathlib.UnsupportedOperation

繼承自 @ref{369,,NotImplementedError} 的例外，當在路徑物件上呼叫不支援的操作時會被引發。


在 3.13 版被加入.

@end deffn

@node 純路徑,實體路徑,例外<5>,pathlib --- 物件導向檔案系統路徑
@anchor{library/pathlib id1}@anchor{2ad5}@anchor{library/pathlib pure-paths}@anchor{2ad0}
@subsubsection 純路徑


純路徑物件提供處理路徑的操作，實際上不會存取檔案系統。有三種方式可以存取這些類別，我們也稱之為`類型 (flavours)'：

@geindex PurePath (pathlib 中的類別)
@anchor{library/pathlib pathlib PurePath}@anchor{6c6}
@deffn {類別} pathlib.PurePath (*pathsegments)

一個通用的類別，表示系統的路徑類型（實例化時會建立一個 @ref{2ad6,,PurePosixPath} 或 @ref{19c7,,PureWindowsPath})：

@example
>>> PurePath('setup.py')      # 執行在 Unix 機器上
PurePosixPath('setup.py')
@end example

`pathsegments' 中的每個元素可以是以下的其中一種：一個表示路徑片段的字串，或一個物件，它實作了 @ref{e46,,os.PathLike} 介面且其中的 @ref{e47,,__fspath__()} 方法會回傳字串，就像是另一個路徑物件：

@example
>>> PurePath('foo', 'some/path', 'bar')
PurePosixPath('foo/some/path/bar')
>>> PurePath(Path('foo'), Path('bar'))
PurePosixPath('foo/bar')
@end example

當沒有給 `pathsegments' 的時候，會假設是目前的目錄：

@example
>>> PurePath()
PurePosixPath('.')
@end example

如果一個片段是絕對路徑，則所有之前的片段會被忽略（類似 @ref{1900,,os.path.join()})：

@example
>>> PurePath('/etc', '/usr', 'lib64')
PurePosixPath('/usr/lib64')
>>> PureWindowsPath('c:/Windows', 'd:bar')
PureWindowsPath('d:bar')
@end example

在 Windows 系統上，當遇到具有根目錄的相對路徑片段（例如 @code{r'\foo'}）時，磁碟機 (drive) 部分不會被重置：

@example
>>> PureWindowsPath('c:/Windows', '/Program Files')
PureWindowsPath('c:/Program Files')
@end example

不必要的斜線和單點會被合併，但雙點 (@code{'..'}) 和前置的雙斜線 (@code{'//'}) 不會被合併，因為這樣會因為各種原因改變路徑的意義（例如符號連結 (symbolic links)、UNC 路徑）：

@example
>>> PurePath('foo//bar')
PurePosixPath('foo/bar')
>>> PurePath('//foo/bar')
PurePosixPath('//foo/bar')
>>> PurePath('foo/./bar')
PurePosixPath('foo/bar')
>>> PurePath('foo/../bar')
PurePosixPath('foo/../bar')
@end example

（一個使得 @code{PurePosixPath('foo/../bar')} 等同於 @code{PurePosixPath('bar')} 的單純方法，但如果 @code{foo} 是指到另一個目錄的符號連結，就會是錯誤的。）

純路徑物件實作了 @ref{e46,,os.PathLike} 介面，使得它們可以在任何接受該介面的地方使用。


在 3.6 版的變更: 新增了對於 @ref{e46,,os.PathLike} 介面的支援。

@end deffn

@geindex PurePosixPath (pathlib 中的類別)
@anchor{library/pathlib pathlib PurePosixPath}@anchor{2ad6}
@deffn {類別} pathlib.PurePosixPath (*pathsegments)

@ref{6c6,,PurePath} 的一個子類別，該路徑類型表示非 Windows 檔案系統的路徑：

@example
>>> PurePosixPath('/etc/hosts')
PurePosixPath('/etc/hosts')
@end example

`pathsegments' 的指定方式與 @ref{6c6,,PurePath} 類似。
@end deffn

@geindex PureWindowsPath (pathlib 中的類別)
@anchor{library/pathlib pathlib PureWindowsPath}@anchor{19c7}
@deffn {類別} pathlib.PureWindowsPath (*pathsegments)

@ref{6c6,,PurePath} 的一個子類別，該路徑類型表示 Windows 檔案系統的路徑，包括  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' 的指定方式與 @ref{6c6,,PurePath} 類似。
@end deffn

不論你使用的是什麼系統，你都可以實例化這些類別，因為它們不提供任何涉及系統呼叫的操作。

@menu
* 通用屬性:: 
* 運算子:: 
* 對個別組成的存取:: 
* 方法與屬性:: 

@end menu

@node 通用屬性,運算子,,純路徑
@anchor{library/pathlib general-properties}@anchor{2ad7}
@subsubsection 通用屬性


路徑物件是不可變 (immutable) 且可雜湊 (@ref{81d,,hashable}) 的。相同類型的路徑物件可以被比較和排序。這些屬性遵守該類型的大小寫語意規則：

@example
>>> PurePosixPath('foo') == PurePosixPath('FOO')
False
>>> PureWindowsPath('foo') == PureWindowsPath('FOO')
True
>>> PureWindowsPath('FOO') in @{ PureWindowsPath('foo') @}
True
>>> PureWindowsPath('C:') < PureWindowsPath('d:')
True
@end example

不同類型的路徑物件在比較時視為不相等且無法被排序：

@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 運算子,對個別組成的存取,通用屬性,純路徑
@anchor{library/pathlib operators}@anchor{2ad8}
@subsubsection 運算子


斜線運算子 (slash operator) 用於建立子路徑，就像是 @ref{1900,,os.path.join()} 函式一樣。如果引數是絕對路徑，則忽略前一個路徑。在 Windows 系統上，當引數是具有根目錄的相對路徑（例如，@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

路徑物件可以被用在任何可以接受實作 @ref{e46,,os.PathLike} 的物件的地方：

@example
>>> import os
>>> p = PurePath('/etc')
>>> os.fspath(p)
'/etc'
@end example

路徑的字串表示是原始的檔案系統路徑本身（以原生的形式，例如在 Windows 下是反斜線），你可以將其傳入任何將檔案路徑當作字串傳入的函式：

@example
>>> p = PurePath('/etc')
>>> str(p)
'/etc'
>>> p = PureWindowsPath('c:/Program Files')
>>> str(p)
'c:\\Program Files'
@end example

類似地，對路徑呼叫 @ref{192,,bytes} 會得到原始檔案系統路徑的 bytes 物件，就像使用 @ref{e4a,,os.fsencode()} 編碼過的一樣：

@example
>>> bytes(p)
b'/etc'
@end example

@cartouche
@quotation 備註 
只建議在 Unix 下呼叫 @ref{192,,bytes}。在 Windows 裡，unicode 形式是檔案系統路徑的權威表示方式。
@end quotation
@end cartouche

@node 對個別組成的存取,方法與屬性,運算子,純路徑
@anchor{library/pathlib accessing-individual-parts}@anchor{2ad9}
@subsubsection 對個別組成的存取


可以使用下列屬性來存取路徑的個別「組成」(parts, components)：

@geindex parts (pathlib.PurePath 的屬性)
@anchor{library/pathlib pathlib PurePath parts}@anchor{2ada}
@deffn {屬性} PurePath.parts

一個可存取路徑的各組成的元組：

@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

（特別注意磁碟機跟本地根目錄是如何被重新組合成一個單一組成）
@end deffn

@node 方法與屬性,,對個別組成的存取,純路徑
@anchor{library/pathlib methods-and-properties}@anchor{2adb}
@subsubsection 方法與屬性


@c from pathlib import PurePath, PurePosixPath, PureWindowsPath

純路徑提供以下方法與屬性：

@geindex parser (pathlib.PurePath 的屬性)
@anchor{library/pathlib pathlib PurePath parser}@anchor{531}
@deffn {屬性} PurePath.parser

用於底層路徑剖析和結合的 @ref{a6,,os.path} 模組的實作：可能是 @code{posixpath} 或 @code{ntpath}。


在 3.13 版被加入.

@end deffn

@geindex drive (pathlib.PurePath 的屬性)
@anchor{library/pathlib pathlib PurePath drive}@anchor{2adc}
@deffn {屬性} PurePath.drive

若存在則為一個表示磁碟機字母 (drive letter) 或磁碟機名稱 (drive name) 的字串：

@example
>>> PureWindowsPath('c:/Program Files/').drive
'c:'
>>> PureWindowsPath('/Program Files/').drive
'@w{'}
>>> PurePosixPath('/etc').drive
'@w{'}
@end example

UNC shares 也被視為磁碟機：

@example
>>> PureWindowsPath('//host/share/foo.txt').drive
'\\\\host\\share'
@end example
@end deffn

@geindex root (pathlib.PurePath 的屬性)
@anchor{library/pathlib pathlib PurePath root}@anchor{2add}
@deffn {屬性} PurePath.root

若存在則為一個表示（本地或全域）根目錄的字串：

@example
>>> PureWindowsPath('c:/Program Files/').root
'\\'
>>> PureWindowsPath('c:Program Files/').root
'@w{'}
>>> PurePosixPath('/etc').root
'/'
@end example

UNC shares 都會有一個根目錄：

@example
>>> PureWindowsPath('//host/share').root
'\\'
@end example

如果路徑以超過兩個連續的斜線開頭，@ref{2ad6,,PurePosixPath} 會合併它們：

@example
>>> PurePosixPath('//etc').root
'//'
>>> PurePosixPath('///etc').root
'/'
>>> PurePosixPath('////etc').root
'/'
@end example

@cartouche
@quotation 備註 
此行為符合 `The Open Group Base Specifications Issue 6'，章節 4.11 路徑名稱解析@footnote{https://pubs.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap04.html#tag_04_11}：

`「以兩個連續斜線開頭的路徑名稱可以根據實作定義的方式來解讀，儘管如此，開頭超過兩個斜線應該視為單一斜線。」'
@end quotation
@end cartouche
@end deffn

@geindex anchor (pathlib.PurePath 的屬性)
@anchor{library/pathlib pathlib PurePath anchor}@anchor{2ade}
@deffn {屬性} PurePath.anchor

磁碟機與根目錄的結合：

@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{a1a}
@deffn {屬性} PurePath.parents

一個不可變的序列，為路徑邏輯上的祖先 (logical ancestors) 提供存取：

@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 版的變更: 父序列現在支援 @ref{2489,,slices} 及負的索引值。

@end deffn

@geindex parent (pathlib.PurePath 的屬性)
@anchor{library/pathlib pathlib PurePath parent}@anchor{19ec}
@deffn {屬性} PurePath.parent

邏輯上的父路徑：

@example
>>> p = PurePosixPath('/a/b/c/d')
>>> p.parent
PurePosixPath('/a/b/c')
@end example

你不能越過一個 anchor 或空路徑：

@example
>>> p = PurePosixPath('/')
>>> p.parent
PurePosixPath('/')
>>> p = PurePosixPath('.')
>>> p.parent
PurePosixPath('.')
@end example

@cartouche
@quotation 備註 
這是一個純粹字句上的 (lexical) 運算，因此會有以下行為：

@example
>>> p = PurePosixPath('foo/..')
>>> p.parent
PurePosixPath('foo')
@end example

如果你想要沿任意的檔案系統路徑往上走，建議要先呼叫 @ref{19bf,,Path.resolve()} 來解析符號連結 (symlink) 及去除其中的 @code{”..”}。
@end quotation
@end cartouche
@end deffn

@geindex name (pathlib.PurePath 的屬性)
@anchor{library/pathlib pathlib PurePath name}@anchor{2adf}
@deffn {屬性} PurePath.name

最後的路徑組成 (final path component) 的字串表示，不包含任何磁碟機或根目錄：

@example
>>> PurePosixPath('my/library/setup.py').name
'setup.py'
@end example

UNC 磁碟機名稱並沒有算在內：

@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{18be}
@deffn {屬性} PurePath.suffix

以點分隔路徑的最後一個部分（如存在）：

@example
>>> PurePosixPath('my/library/setup.py').suffix
'.py'
>>> PurePosixPath('my/library.tar.gz').suffix
'.gz'
>>> PurePosixPath('my/library').suffix
'@w{'}
@end example

這通常被稱為檔案副檔名。


在 3.14 版的變更: A single dot ("@code{.}") is considered a valid suffix.

@end deffn

@geindex suffixes (pathlib.PurePath 的屬性)
@anchor{library/pathlib pathlib PurePath suffixes}@anchor{18bf}
@deffn {屬性} PurePath.suffixes

一個路徑後綴 (suffix) 的串列，通常被稱為檔案副檔名：

@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{2ae0}
@deffn {屬性} PurePath.stem

最後的路徑組成，不包括後綴：

@example
>>> PurePosixPath('my/library.tar.gz').stem
'library.tar'
>>> PurePosixPath('my/library.tar').stem
'library'
>>> PurePosixPath('my/library').stem
'library'
@end example
@end deffn

@geindex as_posix() (pathlib.PurePath 的方法)
@anchor{library/pathlib pathlib PurePath as_posix}@anchor{2ae1}
@deffn {方法} PurePath.as_posix ()

回傳一個使用正斜線 (@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{19eb}
@deffn {方法} PurePath.is_absolute ()

回傳一個路徑是否是絕對路徑。一個路徑被視為絕對路徑的條件是它同時有根目錄及（如果該系統類型允許的話）磁碟機：

@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{2fd}
@deffn {方法} PurePath.is_relative_to (other)

回傳此路徑是否為 `other' 路徑的相對路徑。

@example
>>> p = PurePath('/etc/passwd')
>>> p.is_relative_to('/etc')
True
>>> p.is_relative_to('/usr')
False
@end example

該方法是基於字串的；它既不存取檔案系統，也不特別處理 "@code{..}" 片段。以下程式碼是等效的：

@example
>>> u = PurePath('/usr')
>>> u == p or u in p.parents
False
@end example


在 3.9 版被加入.



Deprecated since version 3.12, removed in version 3.14: 額外引數的傳入已棄用；如果有的話，它們會與 `other' 連接在一起。

@end deffn

@geindex is_reserved() (pathlib.PurePath 的方法)
@anchor{library/pathlib pathlib PurePath is_reserved}@anchor{329}
@deffn {方法} PurePath.is_reserved ()

對 @ref{19c7,,PureWindowsPath} 來說，當路徑在 Windows 下被視為保留的話會回傳 @code{True}，否則回傳 @code{False}。對 @ref{2ad6,,PurePosixPath} 來說，總是回傳 @code{False}。


在 3.13 版的變更: Windows 路徑名稱中包含冒號或結尾為點或空格會被視為保留。UNC 路徑可能被視為保留。



Deprecated since version 3.13, will be removed in version 3.15: 此方法已被棄用；請使用 @ref{32a,,os.path.isreserved()} 來檢測 Windows 上的保留路徑。

@end deffn

@geindex joinpath() (pathlib.PurePath 的方法)
@anchor{library/pathlib pathlib PurePath joinpath}@anchor{2ae2}
@deffn {方法} PurePath.joinpath (*pathsegments)

呼叫此方法會依序結合每個所給定的 `pathsegments' 到路徑上：

@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{530}
@deffn {方法} PurePath.full_match (pattern, *, case_sensitive=None)

將路徑與 glob 形式的模式 (glob-style pattern) 做比對。如果比對成功則回傳 @code{True}，否則回傳 @code{False}，例如：

@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{2ae3,,模式語言 (pattern language)} 文件。


像其它方法一樣，是否區分大小寫會遵循平台的預設行為：

@example
>>> PurePosixPath('b.py').full_match('*.PY')
False
>>> PureWindowsPath('b.py').full_match('*.PY')
True
@end example

將 `case_sensitive' 設定成 @code{True} 或 @code{False} 會覆蓋這個行為。


在 3.13 版被加入.

@end deffn

@geindex match() (pathlib.PurePath 的方法)
@anchor{library/pathlib pathlib PurePath match}@anchor{6cc}
@deffn {方法} PurePath.match (pattern, *, case_sensitive=None)

將路徑與非遞迴 glob 形式的模式 (glob-style pattern) 做比對。如果比對成功則回傳 @code{True}，否則回傳 @code{False}。

此方法類似於 @ref{530,,full_match()}，但不允許空白模式（會引發 @ref{2eb,,ValueError}）、不支援遞迴萬用字元 "@code{**}"（它會像非遞迴的 "@code{*}" 一樣），且如果提供相對模式，則會從右邊進行比對：

@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 版的變更: `pattern' 參數接受@ref{59b,,類路徑物件}。



在 3.12 版的變更: 新增 `case_sensitive' 參數。

@end deffn

@geindex relative_to() (pathlib.PurePath 的方法)
@anchor{library/pathlib pathlib PurePath relative_to}@anchor{2fc}
@deffn {方法} PurePath.relative_to (other, walk_up=False)

計算這個路徑相對於 `other' 所表示路徑的版本。如果做不到會引發 @ref{2eb,,ValueError}：

@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

當 `walk_up' 是 False（預設值），路徑必須以 `other' 為開始。當此引數是 True，可能會加入 @code{..} 以組成相對路徑。在其他情況下，例如路徑參考到不同的磁碟機，則會引發 @ref{2eb,,ValueError}：

@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 警告 
這個函式是 @ref{6c6,,PurePath} 的一部分且可以在字串上運作。它不會檢查或存取實際的檔案架構。這會影響到 `walk_up' 選項，因為它假設路徑中沒有符號連結；如果需要解析符號連結的話可以先呼叫 @ref{19bf,,resolve()}。
@end quotation
@end cartouche


在 3.12 版的變更: 加入 `walk_up' 參數（舊的行為和 @code{walk_up=False} 相同）。



Deprecated since version 3.12, removed in version 3.14: 額外位置引數的傳入已棄用；如果有的話，它們會與 `other' 連接在一起。

@end deffn

@geindex with_name() (pathlib.PurePath 的方法)
@anchor{library/pathlib pathlib PurePath with_name}@anchor{19ba}
@deffn {方法} PurePath.with_name (name)

回傳一個修改 @ref{2adf,,name} 後的新路徑。如果原始路徑沒有名稱則引發 ValueError：

@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{192b}
@deffn {方法} PurePath.with_stem (stem)

回傳一個修改 @ref{2ae0,,stem} 後的新路徑。如果原始路徑沒有名稱則引發 ValueError：

@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


在 3.9 版被加入.

@end deffn

@geindex with_suffix() (pathlib.PurePath 的方法)
@anchor{library/pathlib pathlib PurePath with_suffix}@anchor{18bd}
@deffn {方法} PurePath.with_suffix (suffix)

回傳一個修改 @ref{18be,,suffix} 後的新路徑。如果原始路徑沒有後綴，新的 `suffix' 會附加在後面。如果 `suffix' 是一個空字串，原來的後綴會被移除：

@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{2eb,,ValueError} is raised if a single dot is supplied.

@end deffn

@geindex with_segments() (pathlib.PurePath 的方法)
@anchor{library/pathlib pathlib PurePath with_segments}@anchor{6c7}
@deffn {方法} PurePath.with_segments (*pathsegments)

透過結合給定的 `pathsegments' 建立一個相同型別的新路徑物件，當一個衍生路徑被建立的時候會呼叫這個方法，例如從 @ref{19ec,,parent} 和 @ref{2fc,,relative_to()} 建立衍生路徑。子類別可以覆寫此方法來傳遞資訊給衍生路徑，例如：

@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


在 3.12 版被加入.

@end deffn

@node 實體路徑,模式語言 pattern language,純路徑,pathlib --- 物件導向檔案系統路徑
@anchor{library/pathlib concrete-paths}@anchor{2ad1}@anchor{library/pathlib id2}@anchor{2ae4}
@subsubsection 實體路徑


實體路徑是純路徑類別的子類別。除了後者本來就有提供的操作，它們也提供方法可以對路徑物件做系統呼叫。有三種方式可以實例化實體路徑：

@geindex Path (pathlib 中的類別)
@anchor{library/pathlib pathlib Path}@anchor{266}
@deffn {類別} pathlib.Path (*pathsegments)

@ref{6c6,,PurePath} 的子類別，此類別表示系統的路徑類型的實體路徑（實例化時會建立一個 @ref{2ae5,,PosixPath} 或 @ref{2ad2,,WindowsPath}）：

@example
>>> Path('setup.py')
PosixPath('setup.py')
@end example

`pathsegments' 的指定方式與 @ref{6c6,,PurePath} 類似。
@end deffn

@geindex PosixPath (pathlib 中的類別)
@anchor{library/pathlib pathlib PosixPath}@anchor{2ae5}
@deffn {類別} pathlib.PosixPath (*pathsegments)

@ref{266,,Path} 和 @ref{2ad6,,PurePosixPath} 的子類別，此類別表示實體非 Windows 檔案系統路徑：

@example
>>> PosixPath('/etc/hosts')
PosixPath('/etc/hosts')
@end example

`pathsegments' 的指定方式與 @ref{6c6,,PurePath} 類似。


在 3.13 版的變更: 在 Windows 上會引發 @ref{52e,,UnsupportedOperation}。在先前版本中，則是引發 @ref{369,,NotImplementedError}。

@end deffn

@geindex WindowsPath (pathlib 中的類別)
@anchor{library/pathlib pathlib WindowsPath}@anchor{2ad2}
@deffn {類別} pathlib.WindowsPath (*pathsegments)

@ref{266,,Path} 和 @ref{19c7,,PureWindowsPath} 的子類別，此類別表示實體 Windows 檔案系統路徑：

@example
>>> WindowsPath('c:/', 'Users', 'Ximénez')
WindowsPath('c:/Users/Ximénez')
@end example

`pathsegments' 的指定方式與 @ref{6c6,,PurePath} 類似。


在 3.13 版的變更: 在非 Windows 平台上會引發 @ref{52e,,UnsupportedOperation}。在先前版本中，則是引發 @ref{369,,NotImplementedError}。

@end deffn

你只能實例化對應你的系統的類別類型（允許在不相容的路徑類型上做系統呼叫可能在你的應用程式導致漏洞或故障）：

@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

有些實體路徑方法會在系統呼叫失敗（例如因為路徑不存在）時引發 @ref{2c0,,OSError}。

@menu
* 剖析和產生 URI:: 
* 擴展和解析路徑:: 
* 查詢檔案類型和狀態:: 
* 讀取和寫入檔案:: 
* 讀取目錄:: 
* 建立檔案和目錄:: 
* 複製、移動和刪除:: 
* 權限和所有權:: 

@end menu

@node 剖析和產生 URI,擴展和解析路徑,,實體路徑
@anchor{library/pathlib parsing-and-generating-uris}@anchor{2ae6}
@subsubsection 剖析和產生 URI


實體路徑物件可以從符合 
@geindex RFC; RFC 8089
RFC 8089@footnote{https://datatracker.ietf.org/doc/html/rfc8089.html} 中的 'file' URI 建立，也可以以該形式來表示。

@cartouche
@quotation 備註 
檔案 URI 在跨不同@ref{2ae7,,檔案系統編碼}的機器上是無法移植的。
@end quotation
@end cartouche

@geindex from_uri() (pathlib.Path 的類別方法)
@anchor{library/pathlib pathlib Path from_uri}@anchor{52f}
@deffn {方法} classmethod Path.from_uri (uri)

從剖析 'file' URI 回傳新的路徑物件。例如：

@example
>>> p = Path.from_uri('file:///etc/hosts')
PosixPath('/etc/hosts')
@end example

在 Windows 上，從 URI 可以剖析 DOS 裝置和 UNC 路徑：

@example
>>> p = Path.from_uri('file:///c:/windows')
WindowsPath('c:/windows')
>>> p = Path.from_uri('file://server/share')
WindowsPath('//server/share')
@end example

支援多種變形：

@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

如果 URI 不是 @code{file:} 開頭，或是剖析後的路徑不是絕對路徑，則會引發 @ref{2eb,,ValueError}。


在 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{2eb,,ValueError} is raised.

@end deffn

@geindex as_uri() (pathlib.Path 的方法)
@anchor{library/pathlib pathlib Path as_uri}@anchor{31b}
@deffn {方法} Path.as_uri ()

以 'file' URI 來表示路徑。如果路徑不是絕對的則會引發 @ref{2eb,,ValueError}。

@example
>>> p = PosixPath('/etc/passwd')
>>> p.as_uri()
'file:///etc/passwd'
>>> p = WindowsPath('c:/Windows')
>>> p.as_uri()
'file:///c:/Windows'
@end example


Deprecated since version 3.14, will be removed in version 3.19: Calling this method from @ref{6c6,,PurePath} rather than @ref{266,,Path} is
possible but deprecated. The method's use of @ref{e4a,,os.fsencode()} makes
it strictly impure.

@end deffn

@node 擴展和解析路徑,查詢檔案類型和狀態,剖析和產生 URI,實體路徑
@anchor{library/pathlib expanding-and-resolving-paths}@anchor{2ae8}
@subsubsection 擴展和解析路徑


@geindex home() (pathlib.Path 的類別方法)
@anchor{library/pathlib pathlib Path home}@anchor{103e}
@deffn {方法} classmethod Path.home ()

回傳一個代表使用者家目錄的新的路徑物件（像以 @code{~} 構成的 @ref{c00,,os.path.expanduser()} 的回傳一樣）。如果無法解析家目錄，會引發 @ref{244,,RuntimeError}。

@example
>>> Path.home()
PosixPath('/home/antoine')
@end example


在 3.5 版被加入.

@end deffn

@geindex expanduser() (pathlib.Path 的方法)
@anchor{library/pathlib pathlib Path expanduser}@anchor{103d}
@deffn {方法} Path.expanduser ()

回傳一個展開 @code{~} 和 @code{~user} 構成的新路徑，像 @ref{c00,,os.path.expanduser()} 回傳的一樣。如果無法解析家目錄，會引發 @ref{244,,RuntimeError}。

@example
>>> p = PosixPath('~/films/Monty Python')
>>> p.expanduser()
PosixPath('/home/eric/films/Monty Python')
@end example


在 3.5 版被加入.

@end deffn

@geindex cwd() (pathlib.Path 的類別方法)
@anchor{library/pathlib pathlib Path cwd}@anchor{19ea}
@deffn {方法} classmethod Path.cwd ()

回傳一個代表目前目錄的新的路徑物件（像 @ref{1874,,os.getcwd()} 回傳的一樣）：

@example
>>> Path.cwd()
PosixPath('/home/antoine/pathlib')
@end example
@end deffn

@geindex absolute() (pathlib.Path 的方法)
@anchor{library/pathlib pathlib Path absolute}@anchor{1976}
@deffn {方法} Path.absolute ()

將路徑轉換為絕對路徑，不進行標準化或解析符號連結。回傳一個新的路徑物件：

@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{19bf}
@deffn {方法} Path.resolve (strict=False)

將路徑轉換為絕對路徑，解析所有符號連結。回傳一個新的路徑物件：

@example
>>> p = Path()
>>> p
PosixPath('.')
>>> p.resolve()
PosixPath('/home/antoine/pathlib')
@end example

同時也會消除 "@code{..}" 的路徑組成（只有此方法這樣做）：

@example
>>> p = Path('docs/../setup.py')
>>> p.resolve()
PosixPath('/home/antoine/pathlib/setup.py')
@end example

如果路徑不存在或遇到符號連結迴圈，且 `strict' 為 @code{True}，則引發 @ref{2c0,,OSError}。如果 `strict' 為 @code{False}，則將盡可能解析該路徑，並將任何剩餘部分追加到路徑中，而不檢查其是否存在。


在 3.6 版的變更: 新增 `strict' 參數（在 3.6 版本之前的行為是嚴格的）。



在 3.13 版的變更: 在嚴格模式下，符號連結迴圈會像其他錯誤一樣來處理：@ref{2c0,,OSError} 會被引發，而在非嚴格模式下，不會引發任何例外。在先前版本中，不管 `strict' 的值是什麼，都會引發 @ref{244,,RuntimeError}。

@end deffn

@geindex readlink() (pathlib.Path 的方法)
@anchor{library/pathlib pathlib Path readlink}@anchor{b10}
@deffn {方法} Path.readlink ()

回傳符號連結指向的路徑（如 @ref{b11,,os.readlink()} 的回傳值）：

@example
>>> p = Path('mylink')
>>> p.symlink_to('setup.py')
>>> p.readlink()
PosixPath('setup.py')
@end example


在 3.9 版被加入.



在 3.13 版的變更: 如果 @ref{b11,,os.readlink()} 不可用，會引發 @ref{52e,,UnsupportedOperation}。在先前版本中，則是引發 @ref{369,,NotImplementedError}。

@end deffn

@node 查詢檔案類型和狀態,讀取和寫入檔案,擴展和解析路徑,實體路徑
@anchor{library/pathlib querying-file-type-and-status}@anchor{2ae9}
@subsubsection 查詢檔案類型和狀態



在 3.8 版的變更: @ref{c02,,exists()}、@ref{535,,is_dir()}、@ref{534,,is_file()}、@ref{c03,,is_mount()}、@ref{c04,,is_symlink()}、@ref{c05,,is_block_device()}、@ref{c06,,is_char_device()}、@ref{c07,,is_fifo()}、@ref{c08,,is_socket()} 遇到路徑包含 OS 層無法表示的字元時現在會回傳 @code{False} 而不是引發例外。



在 3.14 版的變更: The methods given above now return @code{False} instead of raising any
@ref{2c0,,OSError} exception from the operating system. In previous versions,
some kinds of @ref{2c0,,OSError} exception are raised, and others suppressed.
The new behaviour is consistent with @ref{bfa,,os.path.exists()},
@ref{bfc,,os.path.isdir()}, etc. Use @ref{a1d,,stat()} to retrieve the file
status without suppressing exceptions.


@geindex stat() (pathlib.Path 的方法)
@anchor{library/pathlib pathlib Path stat}@anchor{a1d}
@deffn {方法} Path.stat (*, follow_symlinks=True)

回傳一個包含該路徑資訊的 @ref{16b5,,os.stat_result} 物件，像 @ref{26d,,os.stat()} 一樣。每次呼叫此方法都會重新查詢結果。

此方法通常會跟隨 (follow) 符號連結；想要取得符號連結的資訊，可以加上引數 @code{follow_symlinks=False} 或使用 @ref{2aea,,lstat()}。

@example
>>> p = Path('setup.py')
>>> p.stat().st_size
956
>>> p.stat().st_mtime
1327883547.852554
@end example


在 3.10 版的變更: 新增 `follow_symlinks' 參數。

@end deffn

@geindex lstat() (pathlib.Path 的方法)
@anchor{library/pathlib pathlib Path lstat}@anchor{2aea}
@deffn {方法} Path.lstat ()

類似 @ref{a1d,,Path.stat()}，但如果該路徑指向一個符號連結，則回傳符號連結的資訊而不是其指向的目標。
@end deffn

@geindex exists() (pathlib.Path 的方法)
@anchor{library/pathlib pathlib Path exists}@anchor{c02}
@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{a1d,,Path.stat()} to distinguish between these cases.

此方法通常會跟隨符號連結；如果想檢查符號連結是否存在，可以加上引數 @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 版的變更: 新增 `follow_symlinks' 參數。

@end deffn

@geindex is_file() (pathlib.Path 的方法)
@anchor{library/pathlib pathlib Path is_file}@anchor{534}
@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{a1d,,Path.stat()} to
distinguish between these cases.

此方法通常會跟隨符號連結；如果想將符號連結除外，可以加上引數 @code{follow_symlinks=False}。


在 3.13 版的變更: 新增 `follow_symlinks' 參數。

@end deffn

@geindex is_dir() (pathlib.Path 的方法)
@anchor{library/pathlib pathlib Path is_dir}@anchor{535}
@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{a1d,,Path.stat()} to distinguish
between these cases.

此方法通常會跟隨符號連結；如果想將對目錄的符號連結除外，可以加上引數 @code{follow_symlinks=False}。


在 3.13 版的變更: 新增 `follow_symlinks' 參數。

@end deffn

@geindex is_symlink() (pathlib.Path 的方法)
@anchor{library/pathlib pathlib Path is_symlink}@anchor{c04}
@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{a1d,,Path.stat()} to distinguish between these cases.
@end deffn

@geindex is_junction() (pathlib.Path 的方法)
@anchor{library/pathlib pathlib Path is_junction}@anchor{6cb}
@deffn {方法} Path.is_junction ()

如果該路徑指向一個連接點 (junction) 則回傳 @code{True}，對其他類型的檔案則回傳 @code{False}。目前只有 Windows 支援連接點。


在 3.12 版被加入.

@end deffn

@geindex is_mount() (pathlib.Path 的方法)
@anchor{library/pathlib pathlib Path is_mount}@anchor{c03}
@deffn {方法} Path.is_mount ()

如果路徑是一個 `mount point'（一個檔案系統裡掛載不同檔案系統的存取點）則回傳 @code{True}。在 POSIX 上，此函式檢查 `path' 的父路徑 @code{path/..} 是否和 `path' 在不同的裝置上，或者 @code{path/..} 和 `path' 是否指向相同裝置的相同 i-node ── 這對於所有 Unix 和 POSIX 變體來說應該會偵測出掛載點。在 Windows 上，一個掛載點被視為一個根磁碟機字母（例如 @code{c:\}）、一個 UNC share（例如 @code{\\server\share}）或是掛載的檔案系統目錄。


在 3.7 版被加入.



在 3.12 版的變更: 加入對 Windows 的支援。

@end deffn

@geindex is_socket() (pathlib.Path 的方法)
@anchor{library/pathlib pathlib Path is_socket}@anchor{c08}
@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{a1d,,Path.stat()} to
distinguish between these cases.
@end deffn

@geindex is_fifo() (pathlib.Path 的方法)
@anchor{library/pathlib pathlib Path is_fifo}@anchor{c07}
@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{a1d,,Path.stat()} to distinguish between these
cases.
@end deffn

@geindex is_block_device() (pathlib.Path 的方法)
@anchor{library/pathlib pathlib Path is_block_device}@anchor{c05}
@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{a1d,,Path.stat()} to
distinguish between these cases.
@end deffn

@geindex is_char_device() (pathlib.Path 的方法)
@anchor{library/pathlib pathlib Path is_char_device}@anchor{c06}
@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{a1d,,Path.stat()} to
distinguish between these cases.
@end deffn

@geindex samefile() (pathlib.Path 的方法)
@anchor{library/pathlib pathlib Path samefile}@anchor{103b}
@deffn {方法} Path.samefile (other_path)

回傳此路徑是否指向與 `other_path' 相同的檔案，`other_path' 可以是路徑 (Path) 物件或字串。其語義類似於 @ref{116c,,os.path.samefile()} 和 @ref{116b,,os.path.samestat()}。

若任何一個檔案因為某些原因無法存取，則引發 @ref{2c0,,OSError}。

@example
>>> p = Path('spam')
>>> q = Path('eggs')
>>> p.samefile(q)
False
>>> p.samefile('spam')
True
@end example


在 3.5 版被加入.

@end deffn

@geindex info (pathlib.Path 的屬性)
@anchor{library/pathlib pathlib Path info}@anchor{26b}
@deffn {屬性} Path.info

A @ref{26c,,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{26e,,Path.iterdir()} then this attribute is
initialized with some information about the file type gleaned from scanning
the parent directory. Merely accessing @ref{26b,,Path.info} does not perform
any filesystem queries.

To fetch up-to-date information, it's best to call @ref{535,,Path.is_dir()},
@ref{534,,is_file()} and @ref{c04,,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)}.


在 3.14 版被加入.

@end deffn

@node 讀取和寫入檔案,讀取目錄,查詢檔案類型和狀態,實體路徑
@anchor{library/pathlib reading-and-writing-files}@anchor{2aeb}
@subsubsection 讀取和寫入檔案


@geindex open() (pathlib.Path 的方法)
@anchor{library/pathlib pathlib Path open}@anchor{2aec}
@deffn {方法} Path.open (mode='r', buffering=-1, encoding=None, errors=None, newline=None)

開啟該路徑指向的檔案，像內建的 @ref{315,,open()} 函式做的一樣：

@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{1040}
@deffn {方法} Path.read_text (encoding=None, errors=None, newline=None)

將路徑指向的檔案的解碼內容以字串形式回傳：

@example
>>> p = Path('my_text_file')
>>> p.write_text('Text file contents')
18
>>> p.read_text()
'Text file contents'
@end example

該檔案被打開並且隨後關閉。可選參數的含義與 @ref{315,,open()} 中的相同。


在 3.5 版被加入.



在 3.13 版的變更: 新增 `newline' 參數。

@end deffn

@geindex read_bytes() (pathlib.Path 的方法)
@anchor{library/pathlib pathlib Path read_bytes}@anchor{2df}
@deffn {方法} Path.read_bytes ()

將路徑指向的檔案的二進位內容以一個位元組物件回傳：

@example
>>> p = Path('my_binary_file')
>>> p.write_bytes(b'Binary file contents')
20
>>> p.read_bytes()
b'Binary file contents'
@end example


在 3.5 版被加入.

@end deffn

@geindex write_text() (pathlib.Path 的方法)
@anchor{library/pathlib pathlib Path write_text}@anchor{103f}
@deffn {方法} Path.write_text (data, encoding=None, errors=None, newline=None)

以文字模式開啟指向的檔案，將 `data' 寫到檔案，並關閉檔案:: ：

@example
>>> p = Path('my_text_file')
>>> p.write_text('Text file contents')
18
>>> p.read_text()
'Text file contents'
@end example

一個名稱相同的已存在檔案會被覆寫。可選參數和 @ref{315,,open()} 的參數有相同意義。


在 3.5 版被加入.



在 3.10 版的變更: 新增 `newline' 參數。

@end deffn

@geindex write_bytes() (pathlib.Path 的方法)
@anchor{library/pathlib pathlib Path write_bytes}@anchor{1041}
@deffn {方法} Path.write_bytes (data)

以位元組模式開啟指向的檔案，將 `data' 寫到檔案，並關閉檔案:: ：

@example
>>> p = Path('my_binary_file')
>>> p.write_bytes(b'Binary file contents')
20
>>> p.read_bytes()
b'Binary file contents'
@end example

一個名稱相同的已存在檔案會被覆寫。


在 3.5 版被加入.

@end deffn

@node 讀取目錄,建立檔案和目錄,讀取和寫入檔案,實體路徑
@anchor{library/pathlib reading-directories}@anchor{2aed}
@subsubsection 讀取目錄


@geindex iterdir() (pathlib.Path 的方法)
@anchor{library/pathlib pathlib Path iterdir}@anchor{26e}
@deffn {方法} Path.iterdir ()

當該路徑指向一個目錄，會 yield 目錄裡面的路徑物件：

@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

子路徑會以任意順序被 yield，且不會包含特殊項目 @code{'.'} 和 @code{'..'}。如果一個檔案在建立這個疊代器之後加到該目錄或從目錄刪除，這個檔案的路徑物件是否會被包含是沒有明定的。

如果路徑不是目錄或無法存取，則會引發 @ref{2c0,,OSError}。
@end deffn

@geindex glob() (pathlib.Path 的方法)
@anchor{library/pathlib pathlib Path glob}@anchor{532}
@deffn {方法} Path.glob (pattern, *, case_sensitive=None, recurse_symlinks=False)

在該路徑表示的目錄裡，以 glob 方式比對所給定的相對 `pattern'，並 yield 所有比對到的檔案（任意類型）：

@example
>>> sorted(Path('.').glob('*.py'))
[PosixPath('pathlib.py'), PosixPath('setup.py'), PosixPath('test_pathlib.py')]
>>> sorted(Path('.').glob('*/*.py'))
[PosixPath('docs/conf.py')]
>>> sorted(Path('.').glob('**/*.py'))
[PosixPath('build/lib/pathlib.py'),
 PosixPath('docs/conf.py'),
 PosixPath('pathlib.py'),
 PosixPath('setup.py'),
 PosixPath('test_pathlib.py')]
@end example


@subsubheading 也參考


@ref{2ae3,,模式語言 (pattern language)} 文件。


預設情況下，或者當 `case_sensitive' 僅限關鍵字引數被設定為 @code{None} 的時候，此方法會使用平台特定的大小寫規則來比對路徑；通常在 POSIX 上會區分大小寫，而在 Windows 上不區分大小寫。將 `case_sensitive' 設成 @code{True} 或 @code{False} 會覆寫這個行為。

預設情況下，或者當 `recurse_symlinks' 僅限關鍵字引數被設定為 @code{False} 的時候，此方法會跟隨符號連結，除非在擴展 "@code{**}" 萬用字元時。將 `recurse_symlinks' 設成 @code{True} 以總是跟隨符號連結。

引發一個附帶引數 @code{self}、@code{pattern} 的@ref{1b70,,稽核事件} @code{pathlib.Path.glob}。


在 3.12 版的變更: 新增 `case_sensitive' 參數。



在 3.13 版的變更: 新增 `recurse_symlinks' 參數。



在 3.13 版的變更: `pattern' 參數接受@ref{59b,,類路徑物件}。



在 3.13 版的變更: 從掃描檔案系統引發的任何 @ref{2c0,,OSError} 例外都會被抑制。在先前版本中，在許多情況下這種例外都會被抑制，但不是所有情況。

@end deffn

@geindex rglob() (pathlib.Path 的方法)
@anchor{library/pathlib pathlib Path rglob}@anchor{533}
@deffn {方法} Path.rglob (pattern, *, case_sensitive=None, recurse_symlinks=False)

遞迴地 glob 給定的相對 `pattern'。這相當於在給定的相對 `pattern' 前面加上 "@code{**/}" 並呼叫 @ref{532,,Path.glob()}。


@subsubheading 也參考


@ref{2ae3,,模式語言 (pattern language)} 和 @ref{532,,Path.glob()} 文件。


引發一個附帶引數 @code{self}、@code{pattern} 的@ref{1b70,,稽核事件} @code{pathlib.Path.rglob}。


在 3.12 版的變更: 新增 `case_sensitive' 參數。



在 3.13 版的變更: 新增 `recurse_symlinks' 參數。



在 3.13 版的變更: `pattern' 參數接受@ref{59b,,類路徑物件}。

@end deffn

@geindex walk() (pathlib.Path 的方法)
@anchor{library/pathlib pathlib Path walk}@anchor{6c8}
@deffn {方法} Path.walk (top_down=True, on_error=None, follow_symlinks=False)

透過由上而下或由下而上地走訪目錄樹產生目錄樹裡的檔案名稱。

對每個以 `self' 為根且在目錄樹裡的目錄（包含 `self' 但不包含 '.' 和 '..' ），此方法會 yield 一個 @code{(dirpath, dirnames, filenames)} 的三元素元組。

`dirpath' 是一個目前走訪到的目錄的 @ref{266,,Path}，`dirnames' 是一個 `dirpath' 裡的子目錄名稱的字串串列（不包含 @code{'.'} 和 @code{'..'} ），而 `filenames' 是一個 `dirpath' 裡非目錄檔案名稱的字串串列。要取得在 `dirpath' 裡檔案或目錄的完整路徑（以 `self' 開頭），可以使用 @code{dirpath / name}。會根據檔案系統來決定串列是否有排序。

如果可選引數 `top_down' 是 true（預設值），一個目錄的三元素元組會在其任何子目錄的三元素元組之前產生（目錄是由上而下走訪）。如果 `top_down' 是 false，一個目錄的三元素元組會在其所有子目錄的三元素元組之後產生（目錄是由下而上走訪）。不論 `top_down' 的值是什麼，子目錄的串列會在走訪該目錄及其子目錄的三元素元組之前取得。

當 `top_down' 是 true，呼叫者可以原地 (in-place) 修改 `dirnames' 串列（例如使用 @ref{1a62,,del} 或切片賦值 (slice assignment)），且 @ref{6c8,,Path.walk()} 只會遞迴進名稱依然留在 `dirnames' 裡的子目錄。這可以用來修剪搜尋，或者強加特定順序的瀏覽，或者甚至在繼續 @ref{6c8,,Path.walk()} 之前，用來告訴 @ref{6c8,,Path.walk()} 關於呼叫者建立或重新命名的目錄。當 `top_down' 是 false 的時候，修改 `dirnames' 對 @ref{6c8,,Path.walk()} 的行為沒有影響，因為 `dirnames' 裡的目錄已經在 `dirnames' yield 給呼叫者之前被產生。

預設來自 @ref{c4b,,os.scandir()} 的錯誤會被忽略。如果指定了可選引數 `on_error'（它應該要是一個可呼叫物件），它會被以一個 @ref{2c0,,OSError} 實例為引數來呼叫。這個可呼叫物件可以處理錯誤以繼續走訪，或者再次引發錯誤來停止走訪。注意，檔案名稱可以從例外物件的 @code{filename} 屬性來取得。

預設 @ref{6c8,,Path.walk()} 不會跟隨符號連結，而是會把它們加到 `filenames' 串列。將 `follow_symlinks' 設定為 true 會解析符號連結，並將它們根據其指向的目標放在適當的 `dirnames' 和 `filenames'，而因此瀏覽到符號連結指向的目錄（在有支援符號連結的地方）。

@cartouche
@quotation 備註 
需要注意的是如果符號連結指向一個其本身的父目錄，則將 `follow_symlinks' 設定為 true 會導致無窮的遞迴。@ref{6c8,,Path.walk()} 不會紀錄其已經瀏覽過的目錄。
@end quotation
@end cartouche

@cartouche
@quotation 備註 
@ref{6c8,,Path.walk()} 假設其走訪的目錄在執行過程中不會被修改。舉例來說，如果在 `dirnames' 裡的目錄已經被一個符號連結取代，且 `follow_symlinks' 是 false，@ref{6c8,,Path.walk()} 依然會試著往下進入它。為了防止這樣的行為，可以從 `dirnames' 適當地移除目錄。
@end quotation
@end cartouche

@cartouche
@quotation 備註 
如果 `follow_symlinks' 是 false，和 @ref{6c9,,os.walk()} 行為不同的是 @ref{6c8,,Path.walk()} 會將指向目錄的符號連結放在 `filenames' 串列。
@end quotation
@end cartouche

這個範例會顯示在每個目錄裡所有檔案使用的位元組數量，同時間忽略 @code{__pycache__} 目錄：

@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

下一個範例是 @ref{354,,shutil.rmtree()} 的一個簡單的實作方式。由下而上走訪目錄樹是必要的，因為 @ref{2aee,,rmdir()} 不允許在目錄為空之前刪除它：

@example
# 刪除可從 "top" 目錄到達的所有東西。
# 注意：這是危險的！例如，如果 top == Path('/')，
# 它可能會刪除你所有的檔案。
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


在 3.12 版被加入.

@end deffn

@node 建立檔案和目錄,複製、移動和刪除,讀取目錄,實體路徑
@anchor{library/pathlib creating-files-and-directories}@anchor{2aef}
@subsubsection 建立檔案和目錄


@geindex touch() (pathlib.Path 的方法)
@anchor{library/pathlib pathlib Path touch}@anchor{2af0}
@deffn {方法} Path.touch (mode=0o666, exist_ok=True)

根據給定路徑來建立一個檔案。如果 `mode' 有給定，它會與行程的 @code{umask} 值結合，以確定檔案模式和存取旗標。當檔案已經存在時，若 `exist_ok' 為 true 則函式不會失敗（其變更時間會被更新為當下時間），否則會引發 @ref{121b,,FileExistsError}。


@subsubheading 也參考


@ref{2aec,,open()}、@ref{103f,,write_text()} 和 @ref{1041,,write_bytes()} 方法通常用於建立檔案。

@end deffn

@geindex mkdir() (pathlib.Path 的方法)
@anchor{library/pathlib pathlib Path mkdir}@anchor{103c}
@deffn {方法} Path.mkdir (mode=0o777, parents=False, exist_ok=False)

在給定路徑下建立一個新的目錄。如果有給 `mode' 則會結合行程 (process) 的 @code{umask} 值來決定檔案模式與存取旗標 (access flag)。如果路徑已經存在，會引發 @ref{121b,,FileExistsError}。

如果 `parents' 是 true，則任何缺少的父路徑都會依需要被建立；它們不考慮 `mode' 而會以預設的權限來建立（模仿 POSIX 的 @code{mkdir -p} 指令）。

如果 `parents' 是 false（預設值），缺少的父路徑會引發 @ref{264,,FileNotFoundError}。

如果 `exist_ok' 是 false（預設值），則當目標目錄已經存在的話會引發 @ref{121b,,FileExistsError}。

如果 `exist_ok' 是 true，只有當最後的路徑組成不是一個已存在的非目錄檔案，@ref{121b,,FileExistsError} 例外會被忽略（與 POSIX 的 @code{mkdir -p} 指令行為相同）。


在 3.5 版的變更: 新增 `exist_ok' 參數。

@end deffn

@geindex symlink_to() (pathlib.Path 的方法)
@anchor{library/pathlib pathlib Path symlink_to}@anchor{a1c}
@deffn {方法} Path.symlink_to (target, target_is_directory=False)

使這個路徑成為一個指向 `target' 的符號連結。

在 Windows 上，符號連結代表一個檔案或目錄，且不會隨著目標 (target) 動態改變。如果目標存在，則符號連結的類型會被建立來符合其目標。否則如果 `target_is_directory' 是 true，該符號連結會被建立成目錄，如果不是則建立成檔案（預設值）。在非 Windows 平台上，`target_is_directory' 會被忽略。

@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 備註 
引數的順序 (link, target) 和 @ref{12f5,,os.symlink()} 相反。
@end quotation
@end cartouche


在 3.13 版的變更: 如果 @ref{12f5,,os.symlink()} 不可用，會引發 @ref{52e,,UnsupportedOperation}。在先前版本中，則是引發 @ref{369,,NotImplementedError}。

@end deffn

@geindex hardlink_to() (pathlib.Path 的方法)
@anchor{library/pathlib pathlib Path hardlink_to}@anchor{a1b}
@deffn {方法} Path.hardlink_to (target)

使這個路徑成為與 `target' 相同檔案的一個硬連結 (hard link)。

@cartouche
@quotation 備註 
引數的順序 (link, target) 和 @ref{12f0,,os.link()} 相反。
@end quotation
@end cartouche


在 3.10 版被加入.



在 3.13 版的變更: 如果 @ref{12f0,,os.link()} 不可用，會引發 @ref{52e,,UnsupportedOperation}。在先前版本中，則是引發 @ref{369,,NotImplementedError}。

@end deffn

@node 複製、移動和刪除,權限和所有權,建立檔案和目錄,實體路徑
@anchor{library/pathlib copying-moving-and-deleting}@anchor{2af1}
@subsubsection 複製、移動和刪除


@geindex copy() (pathlib.Path 的方法)
@anchor{library/pathlib pathlib Path copy}@anchor{267}
@deffn {方法} Path.copy (target, *, follow_symlinks=True, preserve_metadata=False)

將此檔案或目錄樹複製到給定的 `target'，並回傳一個指向 `target' 的新 @code{Path} 實例。

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


在 3.14 版被加入.

@end deffn

@geindex copy_into() (pathlib.Path 的方法)
@anchor{library/pathlib pathlib Path copy_into}@anchor{268}
@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{267,,Path.copy()}. Returns a new @code{Path} instance pointing to the
copy.


在 3.14 版被加入.

@end deffn

@geindex rename() (pathlib.Path 的方法)
@anchor{library/pathlib pathlib Path rename}@anchor{180a}
@deffn {方法} Path.rename (target)

將此檔案或目錄重新命名為給定的 `target' ，並回傳一個新的 @code{Path} 實例指向該 `target'。在 Unix 系統上，若 `target' 存在且為一個檔案，若使用者有權限，則會在不顯示訊息的情況下進行取代。在 Windows 系統上，若 `target' 存在，則會引發 @ref{121b,,FileExistsError} 錯誤。`target' 可以是字串或另一個路徑物件：

@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

目標路徑可以是絕對路徑或相對路徑。相對路徑會相對於目前的工作目錄進行解釋，`而不是'相對於 @code{Path} 物件所在的目錄。

此功能是使用 @ref{12f2,,os.rename()} 實現的，並提供相同的保證。


在 3.8 版的變更: 新增了回傳值，回傳新的 @code{Path} 實例。

@end deffn

@geindex replace() (pathlib.Path 的方法)
@anchor{library/pathlib pathlib Path replace}@anchor{2af2}
@deffn {方法} Path.replace (target)

將此檔案或目錄重新命名為給定的 `target'，並回傳一個指向 `target' 的新 @code{Path} 實例。如果 `target' 指向一個現有的檔案或空目錄，它將被無條件地取代。

目標路徑可以是絕對路徑或相對路徑。相對路徑會相對於目前的工作目錄進行解釋，`而不是'相對於 @code{Path} 物件所在的目錄。


在 3.8 版的變更: 新增了回傳值，回傳新的 @code{Path} 實例。

@end deffn

@geindex move() (pathlib.Path 的方法)
@anchor{library/pathlib pathlib Path move}@anchor{269}
@deffn {方法} Path.move (target)

將此檔案或目錄樹移動到給定的 `target'，並回傳一個指向 `target' 的新 @code{Path} 實例。

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{2c0,,OSError} is raised.

If both paths are on the same filesystem, the move is performed with
@ref{12f3,,os.replace()}. Otherwise, this path is copied (preserving metadata and
symlinks) and then deleted.


在 3.14 版被加入.

@end deffn

@geindex move_into() (pathlib.Path 的方法)
@anchor{library/pathlib pathlib Path move_into}@anchor{26a}
@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.


在 3.14 版被加入.

@end deffn

@geindex unlink() (pathlib.Path 的方法)
@anchor{library/pathlib pathlib Path unlink}@anchor{1c9e}
@deffn {方法} Path.unlink (missing_ok=False)

移除這個檔案或符號連結。如果路徑指向目錄，請改用 @ref{2aee,,Path.rmdir()}。

如果 `missing_ok' 是 false（預設值），@ref{264,,FileNotFoundError} 會在路徑不存在時被引發。

如果 `missing_ok' 是 true，@ref{264,,FileNotFoundError} 例外會被忽略（行為與 POSIX @code{rm -f} 指令相同）。


在 3.8 版的變更: 新增 `missing_ok' 參數。

@end deffn

@geindex rmdir() (pathlib.Path 的方法)
@anchor{library/pathlib pathlib Path rmdir}@anchor{2aee}
@deffn {方法} Path.rmdir ()

移除此目錄。該目錄必須為空。
@end deffn

@node 權限和所有權,,複製、移動和刪除,實體路徑
@anchor{library/pathlib permissions-and-ownership}@anchor{2af3}
@subsubsection 權限和所有權


@geindex owner() (pathlib.Path 的方法)
@anchor{library/pathlib pathlib Path owner}@anchor{536}
@deffn {方法} Path.owner (*, follow_symlinks=True)

回傳擁有該檔案的用戶名稱。如果在系統資料庫中找不到該檔案的使用者識別字 (UID)，則會引發 @ref{5df,,KeyError}。

此方法通常會跟隨符號連結；如果想取得符號連結的擁有者，可以加上引數 @code{follow_symlinks=False}。


在 3.13 版的變更: 如果 @ref{b7,,pwd} 模組不可用，會引發 @ref{52e,,UnsupportedOperation}。在先前版本中，則是引發 @ref{369,,NotImplementedError}。



在 3.13 版的變更: 新增 `follow_symlinks' 參數。

@end deffn

@geindex group() (pathlib.Path 的方法)
@anchor{library/pathlib pathlib Path group}@anchor{537}
@deffn {方法} Path.group (*, follow_symlinks=True)

回傳擁有該檔案的群組名稱。如果在系統資料庫裡找不到檔案的群組識別字 (GID) 會引發 @ref{5df,,KeyError}。

此方法通常會跟隨符號連結；如果想取得符號連結的群組，可以加上引數 @code{follow_symlinks=False}。


在 3.13 版的變更: 如果 @ref{6a,,grp} 模組不可用，會引發 @ref{52e,,UnsupportedOperation}。在先前版本中，則是引發 @ref{369,,NotImplementedError}。



在 3.13 版的變更: 新增 `follow_symlinks' 參數。

@end deffn

@geindex chmod() (pathlib.Path 的方法)
@anchor{library/pathlib pathlib Path chmod}@anchor{a1e}
@deffn {方法} Path.chmod (mode, *, follow_symlinks=True)

修改檔案模式 (file mode) 與權限，像 @ref{524,,os.chmod()} 一樣。

此方法通常會跟隨符號連結。一些 Unix 類型支援修改符號連結本身的權限；在這些平台上你可以加上引數 @code{follow_symlinks=False} 或使用 @ref{2af4,,lchmod()}。

@example
>>> p = Path('setup.py')
>>> p.stat().st_mode
33277
>>> p.chmod(0o444)
>>> p.stat().st_mode
33060
@end example


在 3.10 版的變更: 新增 `follow_symlinks' 參數。

@end deffn

@geindex lchmod() (pathlib.Path 的方法)
@anchor{library/pathlib pathlib Path lchmod}@anchor{2af4}
@deffn {方法} Path.lchmod (mode)

類似 @ref{a1e,,Path.chmod()}，但如果該路徑指向一個符號連結，則符號連結的模式 (mode) 會被改變而不是其指向的目標。
@end deffn

@node 模式語言 pattern language,與 glob 模組的比較,實體路徑,pathlib --- 物件導向檔案系統路徑
@anchor{library/pathlib pathlib-pattern-language}@anchor{2ae3}@anchor{library/pathlib pattern-language}@anchor{2af5}
@subsubsection 模式語言 (pattern language)


以下的萬用字元在 @ref{530,,full_match()}、@ref{532,,glob()} 和 @ref{533,,rglob()} 的模式中被支援：


@table @asis

@item @code{**}（整個片段）

匹配任何數量的檔案或目錄片段，包括零個。

@item @code{*}（整個片段）

匹配一個檔案或目錄的片段。

@item @code{*}（片段的一部分）

匹配任意數量的非分隔字元，包括零個。

@item @code{?}

匹配一個非分隔字元。

@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]}

匹配一個不在 `seq' 中的字元，其中 `seq' 遵循上述相同的規則。
@end table

對於文本 (literal) 匹配，可以用方括號包裝元字元 (meta-characters)。例如，@code{"[?]"} 會匹配字元 @code{"?"}。

"@code{**}" 萬用字元讓它可以做遞迴 glob。例如：


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

模式

@tab

意涵

@item

"@code{**/*}"

@tab

至少有一個片段的路徑。

@item

"@code{**/*.py}"

@tab

最後一個片段以 "@code{.py}" 結尾的任何路徑。

@item

"@code{assets/**}"

@tab

任何以 "@code{assets/}" 開頭的路徑。

@item

"@code{assets/**/*}"

@tab

任何以 "@code{assets/}" 開頭的路徑，不包括 "@code{assets/}" 本身。

@end multitable


@cartouche
@quotation 備註 
Glob 使用 @code{**} 萬用字元會訪問目錄樹中的每個目錄。對於大型的目錄樹，搜尋可能需要花費很長的時間。
@end quotation
@end cartouche


在 3.13 版的變更: Glob 使用結尾為 @code{**} 的模式會同時回傳檔案和目錄。在先前版本中，只會回傳目錄。


在 @ref{532,,Path.glob()} 和 @ref{533,,rglob()} 中，可以在模式後面加上斜線以只匹配目錄。


在 3.11 版的變更: Glob 使用以路徑名稱組成的分隔符號（@ref{873,,sep} 或 @ref{874,,altsep}）作結尾的模式則只會回傳目錄。


@node 與 glob 模組的比較,與 os 和 os path 模組的比較,模式語言 pattern language,pathlib --- 物件導向檔案系統路徑
@anchor{library/pathlib comparison-to-the-glob-module}@anchor{2af6}
@subsubsection 與 @code{glob} 模組的比較


@ref{532,,Path.glob()} 和 @ref{533,,Path.rglob()} 接受的模式和產生的結果與 @ref{68,,glob} 模組略有不同：


@enumerate 

@item 
pathlib 中以點開頭的檔案並不特別。這和將 @code{include_hidden=True} 傳遞給 @ref{59a,,glob.glob()} 相同。

@item 
@code{**} 模式組成在 pathlib 中總是遞迴的。這與將 @code{recursive=True} 傳遞給 @ref{59a,,glob.glob()} 相同。

@item 
在 pathlib 中，@code{**} 模式組成預設不跟隨符號連結。這在 @ref{59a,,glob.glob()} 中沒有等效的行為，但你可以將 @code{recurse_symlinks=True} 傳遞給 @ref{532,,Path.glob()} 以獲得相容的行為。

@item 
與所有 @ref{6c6,,PurePath} 和 @ref{266,,Path} 物件一樣，從 @ref{532,,Path.glob()} 和 @ref{533,,Path.rglob()} 回傳的值不包含結尾斜線。

@item 
pathlib 的 @code{path.glob()} 和 @code{path.rglob()} 回傳的值包含了 `path' 作為前綴，而 @code{glob.glob(root_dir=path)} 的結果則不會如此。

@item 
pathlib 的 @code{path.glob()} 和 @code{path.rglob()} 回傳的值可能包含 `path' 本身，例如當使用 "@code{**}" 做 glob 的時候，然而 @code{glob.glob(root_dir=path)} 的結果則永遠不會包含一個對應到 `path' 的空字串。
@end enumerate

@node 與 os 和 os path 模組的比較,Protocols,與 glob 模組的比較,pathlib --- 物件導向檔案系統路徑
@anchor{library/pathlib comparison-to-the-os-and-os-path-modules}@anchor{2af7}
@subsubsection 與 @code{os} 和 @code{os.path} 模組的比較


pathlib 使用 @ref{6c6,,PurePath} 和 @ref{266,,Path} 物件來實作路徑操作，因此它被稱為是`物件導向'的。另一方面，@ref{a5,,os} 和 @ref{a6,,os.path} 模組提供能夠與底層 @code{str} 和 @code{bytes} 物件互動的函式，這是一種更`程序式'的方法。有些使用者認為物件導向的風格更易讀。

@ref{a5,,os} 和 @ref{a6,,os.path} 中的許多函式支援 @code{bytes} 路徑和@ref{12eb,,相對路徑的目錄描述器 (paths relative to directory descriptors)}。這些功能在 pathlib 中不可用。

Python 的 @code{str} 和 @code{bytes} 型別，以及 @ref{a5,,os} 和 @ref{a6,,os.path} 模組的一些部分，是用 C 寫的且非常快速。pathlib 是用純 Python 寫的且通常比較慢，但很少會慢到足以產生影響。

pathlib 的路徑正規化略比 @ref{a6,,os.path} 更武斷和一致。例如，儘管 @ref{151b,,os.path.abspath()} 會從路徑中移除 "@code{..}" 片段，如果包含符號連結的話這可能會改變其意義，而 @ref{1976,,Path.absolute()} 則會保留這些片段以增加安全性。

pathlib 的路徑正規化可能會使它不適合某些應用程式：


@enumerate 

@item 
pathlib 將 @code{Path("my_folder/")} 正規化為 @code{Path("my_folder")}，這會在提供給各種操作系統 API 和命令列工具時改變路徑的意義。具體來說，缺少結尾分隔符號可能會允許該路徑被解析為檔案或目錄，而不只是目錄。

@item 
pathlib 將 @code{Path("./my_program")} 正規化為 @code{Path("my_program")}，這會在作為執行檔搜尋路徑使用時改變路徑的意義，例如在 shell 或在衍生 (spawn) 子行程時。具體來說，在路徑中缺少分隔符號可能會使其強制在 
@geindex PATH
@geindex 環境變數; PATH
@code{PATH} 中尋找，而不是目前目錄。
@end enumerate

因為這些差異，pathlib 不是 @ref{a6,,os.path} 的直接替代品。

@menu
* 對應工具:: 

@end menu

@node 對應工具,,,與 os 和 os path 模組的比較
@anchor{library/pathlib corresponding-tools}@anchor{2af8}
@subsubsection 對應工具


以下是一張表格，對應許多 @ref{a5,,os} 函式及其相符於 @ref{6c6,,PurePath}/@ref{266,,Path} 的項目。


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

@ref{a5,,os} 和 @ref{a6,,os.path}

@tab

@ref{a8,,pathlib}

@item

@ref{2af9,,os.path.dirname()}

@tab

@ref{19ec,,PurePath.parent}

@item

@ref{2afa,,os.path.basename()}

@tab

@ref{2adf,,PurePath.name}

@item

@ref{18c0,,os.path.splitext()}

@tab

@ref{2ae0,,PurePath.stem} 和 @ref{18be,,PurePath.suffix}

@item

@ref{1900,,os.path.join()}

@tab

@ref{2ae2,,PurePath.joinpath()}

@item

@ref{52c,,os.path.isabs()}

@tab

@ref{19eb,,PurePath.is_absolute()}

@item

@ref{6ca,,os.path.relpath()}

@tab

@ref{2fc,,PurePath.relative_to()} @footnote{
@ref{6ca,,os.path.relpath()} 會呼叫 @ref{151b,,abspath()} 來將路徑變成絕對路徑並移除 "@code{..}" 部分，而 @ref{2fc,,PurePath.relative_to()} 是一個文本上的操作，當它輸入的錨點不同時（例如一個是絕對路徑，另一個則是相對路徑）會引發 @ref{2eb,,ValueError}。
}

@item

@ref{c00,,os.path.expanduser()}

@tab

@ref{103d,,Path.expanduser()} @footnote{
@ref{c00,,os.path.expanduser()} 會在無法解析家目錄時回傳原始路徑，而 @ref{103d,,Path.expanduser()} 則會引發 @ref{244,,RuntimeError}。
}

@item

@ref{262,,os.path.realpath()}

@tab

@ref{19bf,,Path.resolve()}

@item

@ref{151b,,os.path.abspath()}

@tab

@ref{1976,,Path.absolute()} @footnote{
@ref{151b,,os.path.abspath()} 將 "@code{..}" 組成移除而不解析符號連結，這可能會改變路徑的意義，而 @ref{1976,,Path.absolute()} 則會保留路徑中任何 "@code{..}" 組成。
}

@item

@ref{bfa,,os.path.exists()}

@tab

@ref{c02,,Path.exists()}

@item

@ref{bfd,,os.path.isfile()}

@tab

@ref{534,,Path.is_file()}

@item

@ref{bfc,,os.path.isdir()}

@tab

@ref{535,,Path.is_dir()}

@item

@ref{bf8,,os.path.islink()}

@tab

@ref{c04,,Path.is_symlink()}

@item

@ref{6c3,,os.path.isjunction()}

@tab

@ref{6cb,,Path.is_junction()}

@item

@ref{bfe,,os.path.ismount()}

@tab

@ref{c03,,Path.is_mount()}

@item

@ref{116c,,os.path.samefile()}

@tab

@ref{103b,,Path.samefile()}

@item

@ref{1874,,os.getcwd()}

@tab

@ref{19ea,,Path.cwd()}

@item

@ref{26d,,os.stat()}

@tab

@ref{a1d,,Path.stat()}

@item

@ref{6c1,,os.lstat()}

@tab

@ref{2aea,,Path.lstat()}

@item

@ref{12fb,,os.listdir()}

@tab

@ref{26e,,Path.iterdir()}

@item

@ref{6c9,,os.walk()}

@tab

@ref{6c8,,Path.walk()} @footnote{
當分類路徑成 `dirnames' 和 `filenames' 時 @ref{6c9,,os.walk()} 總是跟隨符號連結，而 @ref{6c8,,Path.walk()} 在 `follow_symlinks' 為 false（預設值）時，會將所有符號連結都分類為 `filenames'。
}

@item

@ref{526,,os.mkdir()}、@ref{527,,os.makedirs()}

@tab

@ref{103c,,Path.mkdir()}

@item

@ref{12f0,,os.link()}

@tab

@ref{a1b,,Path.hardlink_to()}

@item

@ref{12f5,,os.symlink()}

@tab

@ref{a1c,,Path.symlink_to()}

@item

@ref{b11,,os.readlink()}

@tab

@ref{b10,,Path.readlink()}

@item

@ref{12f2,,os.rename()}

@tab

@ref{180a,,Path.rename()}

@item

@ref{12f3,,os.replace()}

@tab

@ref{2af2,,Path.replace()}

@item

@ref{12f1,,os.remove()}、@ref{12f6,,os.unlink()}

@tab

@ref{1c9e,,Path.unlink()}

@item

@ref{12f4,,os.rmdir()}

@tab

@ref{2aee,,Path.rmdir()}

@item

@ref{524,,os.chmod()}

@tab

@ref{a1e,,Path.chmod()}

@item

@ref{523,,os.lchmod()}

@tab

@ref{2af4,,Path.lchmod()}

@end multitable


@node Protocols,,與 os 和 os path 模組的比較,pathlib --- 物件導向檔案系統路徑
@anchor{library/pathlib module-pathlib types}@anchor{a9}@anchor{library/pathlib protocols}@anchor{2afb}
@subsubsection Protocols


@geindex module; pathlib.types

The @ref{a9,,pathlib.types} module provides types for static type checking.


在 3.14 版被加入.


@geindex PathInfo (pathlib.types 中的類別)
@anchor{library/pathlib pathlib types PathInfo}@anchor{26c}
@deffn {類別} pathlib.types.PathInfo

A @ref{565,,typing.Protocol} describing the
@ref{26b,,Path.info} attribute. Implementations may
return cached results from their methods.

@geindex exists() (pathlib.types.PathInfo 的方法)
@anchor{library/pathlib pathlib types PathInfo exists}@anchor{2afc}
@deffn {方法} exists (*, follow_symlinks=True)

如果路徑是個存在的檔案、目錄或任何其他類型的檔案則回傳 @code{True}，如果路徑不存在則回傳 @code{False}。

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{2afd}
@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{2afe}
@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{2aff}
@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 --- 常見的路徑名操作,stat --- 直譯 stat 的結果,pathlib --- 物件導向檔案系統路徑,檔案與目錄存取
@anchor{library/os path doc}@anchor{2b00}@anchor{library/os path module-os path}@anchor{a6}@anchor{library/os path os-path-common-pathname-manipulations}@anchor{2b01}@anchor{library/os path translation-repo}@anchor{2b02}
@subsection @code{os.path} --- 常見的路徑名操作


@geindex module; os.path

`原始碼：' Lib/genericpath.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/genericpath.py}、Lib/posixpath.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/posixpath.py} (用於 POSIX 系統) 和 Lib/ntpath.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/ntpath.py} (用於 Windows).

@geindex path（路徑）;operations（操作）


__________________________________________________________________


該模組實現了一些有用的路徑名操作函式。若要讀取或寫入檔案，請參閱 @ref{315,,open()} 函式，要存取檔案系統，請參閱 @ref{a5,,os} 模組。路徑參數可以以字串、位元組或任何依照 @ref{e46,,os.PathLike} 協定實作的物件傳遞。

與 Unix shell 不同，Python 不會`自動'進行路徑展開 (path expansions)。當應用程式需要進行類似 shell 的路徑展開時，可以明確地叫用 @ref{c00,,expanduser()} 和 @ref{15d0,,expandvars()} 等函式。（另請參閱 @ref{68,,glob} 模組。）


@subsubheading 也參考


@ref{a8,,pathlib} 模組提供了高階的路徑物件。


@cartouche
@quotation 備註 
所有這些函式都只接受位元組或字串物件作為參數。如果回傳的是路徑或檔案名稱，結果將是相同型別的物件。
@end quotation
@end cartouche

@cartouche
@quotation 備註 
由於不同的作業系統具有不同的路徑命名慣例，在標準函式庫中的路徑模組有數個版本可供使用，而 @ref{a6,,os.path} 模組都會是運行 Python 之作業系統所適用本地路徑。然而，如果你想要操作`始終'以某個不同於本機格式表示的路徑，你也可以引入並使用對應的模組。它們都具有相同的介面：


@itemize *

@item 
@code{posixpath} 用於 UNIX 形式的路徑

@item 
@code{ntpath} 用於 Windows 的路徑
@end itemize
@end quotation
@end cartouche


在 3.8 版的變更: 對於包含有作業系統層級無法表示之字元或位元組的路徑，@ref{bfa,,exists()}、@ref{bfb,,lexists()}、@ref{bfc,,isdir()}、@ref{bfd,,isfile()}、@ref{bf8,,islink()} 和 @ref{bfe,,ismount()} 函式現在會回傳 @code{False}，而不是引發例外。


@geindex abspath() (於 os.path 模組中)
@anchor{library/os path os path abspath}@anchor{151b}
@deffn {函式} os.path.abspath (path)

回傳經正規化的絕對路徑名 `path' 。在大多數平台上，這等效於按照以下方式呼叫 @ref{151a,,normpath()} 函式：@code{normpath(join(os.getcwd(), path))}。


在 3.6 版的變更: 接受一個 @ref{59b,,path-like object}。

@end deffn

@geindex basename() (於 os.path 模組中)
@anchor{library/os path os path basename}@anchor{2afa}
@deffn {函式} os.path.basename (path, /)

回傳路徑名 `path' 的基底名稱。這是將 `path' 傳遞給函式 @ref{2b03,,split()} 後回傳結果中的第二個元素。請注意，此函式的結果與 Unix 的 @code{basename} 程式不同；對於 @code{'/foo/bar/'}，@code{basename} 回傳 @code{'bar'}，而 @ref{2afa,,basename()} 函式回傳空字串（@code{'@w{'}}）。


在 3.6 版的變更: 接受一個 @ref{59b,,path-like object}。

@end deffn

@geindex commonpath() (於 os.path 模組中)
@anchor{library/os path os path commonpath}@anchor{1038}
@deffn {函式} os.path.commonpath (paths)

回傳可疊代物件 `paths' 中每個路徑名稱的最長共同子路徑。如果 `paths' 同時包含絕對路徑名稱和相對路徑名稱、`paths' 位於不同的驅動機或 `paths' 為空，則引發 @ref{2eb,,ValueError}。與 @ref{1039,,commonprefix()} 不同，此函式回傳的是有效路徑。


在 3.5 版被加入.



在 3.6 版的變更: 接受一個@ref{59b,,類路徑物件}的序列。



在 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{1039}
@deffn {函式} os.path.commonprefix (list, /)

回傳 `list' 中所有路徑的最長路徑前綴（逐字元比較）。如果 `list' 為空，則回傳空字串（@code{'@w{'}}）。

@cartouche
@quotation 備註 
由於此函式是逐字元比較，因此可能會回傳無效的路徑。若要獲得有效的路徑，請參考 @ref{1038,,commonpath()} 函式。

@example
>>> os.path.commonprefix(['/usr/lib', '/usr/local/lib'])
'/usr/l'

>>> os.path.commonpath(['/usr/lib', '/usr/local/lib'])
'/usr'
@end example
@end quotation
@end cartouche


在 3.6 版的變更: 接受一個 @ref{59b,,path-like object}。

@end deffn

@geindex dirname() (於 os.path 模組中)
@anchor{library/os path os path dirname}@anchor{2af9}
@deffn {函式} os.path.dirname (path, /)

回傳路徑名 `path' 的目錄名稱。這是將 `path' 傳遞給函式 @ref{2b03,,split()} 後回傳之成對結果中的第一個元素。


在 3.6 版的變更: 接受一個 @ref{59b,,path-like object}。

@end deffn

@geindex exists() (於 os.path 模組中)
@anchor{library/os path os path exists}@anchor{bfa}
@deffn {函式} os.path.exists (path)

如果 `path' 是一個存在的路徑或一個開啟的檔案描述器則回傳 @code{True}。對於已損壞的符號連結則回傳 @code{False}。在某些平台上，即使 `path' 實際存在，如果未被授予執行 @ref{26d,,os.stat()} 的權限，此函式仍可能回傳 @code{False}。


在 3.3 版的變更: 現在 `path' 可以是一個整數：如果它是一個開啟的檔案描述器，則回傳 @code{True}；否則回傳 @code{False}。



在 3.6 版的變更: 接受一個 @ref{59b,,path-like object}。

@end deffn

@geindex lexists() (於 os.path 模組中)
@anchor{library/os path os path lexists}@anchor{bfb}
@deffn {函式} os.path.lexists (path)

如果 `path' 是一個存在的路徑則回傳 @code{True}，對已損壞的符號連結也是。在缺乏 @ref{6c1,,os.lstat()} 的平台上，與 @ref{bfa,,exists()} 函式等效。


在 3.6 版的變更: 接受一個 @ref{59b,,path-like object}。

@end deffn

@geindex ~ （波浪號）;home directory expansion（家目錄展開）

@geindex expanduser() (於 os.path 模組中)
@anchor{library/os path os path expanduser}@anchor{c00}
@deffn {函式} os.path.expanduser (path)

在 Unix 和 Windows 上，將引數中以 @code{~} 或 @code{~user} 開頭的部分替換為該 `user' 的家目錄。

@geindex module（模組）;pwd

在 Unix 上，如果環境變數 
@geindex HOME
@geindex 環境變數; HOME
@code{HOME} 有被設置，則將初始的 @code{~} 替換為該變數的值；否則將使用內建模組 @ref{b7,,pwd} 在密碼目錄中查找目前使用者的家目錄。對於初始的 @code{~user}，直接在密碼目錄中查找該使用者的家目錄。

在 Windows 上，如果 
@geindex USERPROFILE
@geindex 環境變數; USERPROFILE
@code{USERPROFILE} 有被設置，則使用該變數的值；否則將結合 
@geindex HOMEPATH
@geindex 環境變數; HOMEPATH
@code{HOMEPATH} 和 
@geindex HOMEDRIVE
@geindex 環境變數; HOMEDRIVE
@code{HOMEDRIVE}。對於初始的 @code{~user}，會檢查目前使用者的家目錄的最後一個目錄元件是否與 
@geindex USERNAME
@geindex 環境變數; USERNAME
@code{USERNAME} 相符，如果相符則替換它。

如果展開失敗或路徑不以波浪符號 (tilde) 開頭，則回傳原始路徑，不做任何變更。


在 3.6 版的變更: 接受一個 @ref{59b,,path-like object}。



在 3.8 版的變更: 在 Windows 上不再使用 
@geindex HOME
@geindex 環境變數; HOME
@code{HOME} 變數。

@end deffn

@geindex $ （金錢符號）;environment variables expansion（環境變數展開）
@geindex % （百分號）;environment variables expansion (Windows)（環境變數展開 (Windows)）

@geindex expandvars() (於 os.path 模組中)
@anchor{library/os path os path expandvars}@anchor{15d0}
@deffn {函式} os.path.expandvars (path)

回傳已展開環境變數的引數。形如 @code{$name} 或 @code{$@{name@}} 的子字串會被替換為環境變數 `name' 的值。無效的變數名稱和對不存在變數的引用保持不變。

在 Windows 上，除了支援 @code{$name} 和 @code{$@{name@}} 形式的展開外，還支援 @code{%name%} 形式的展開。


在 3.6 版的變更: 接受一個 @ref{59b,,path-like object}。

@end deffn

@geindex getatime() (於 os.path 模組中)
@anchor{library/os path os path getatime}@anchor{2b04}
@deffn {函式} os.path.getatime (path, /)

回傳 `path' 的最後存取時間。回傳值是一個浮點數，表示自紀元（參見 @ref{f4,,time} 模組）以來的秒數。如果檔案不存在或無法存取，則引發 @ref{2c0,,OSError}。
@end deffn

@geindex getmtime() (於 os.path 模組中)
@anchor{library/os path os path getmtime}@anchor{2b05}
@deffn {函式} os.path.getmtime (path, /)

回傳 `path' 的最後修改時間。回傳值是一個浮點數，表示自紀元（參見 @ref{f4,,time} 模組）以來的秒數。如果檔案不存在或無法存取，則引發 @ref{2c0,,OSError}。


在 3.6 版的變更: 接受一個 @ref{59b,,path-like object}。

@end deffn

@geindex getctime() (於 os.path 模組中)
@anchor{library/os path os path getctime}@anchor{2b06}
@deffn {函式} os.path.getctime (path, /)

回傳系統的 ctime。在某些系統（如 Unix）上，這是最後一次元數據 (metadata) 更改的時間，在其他系統（如 Windows）上則是 `path' 的建立時間。回傳值是一個浮點數，表示自紀元（參見 @ref{f4,,time} 模組）以來的秒數。如果檔案不存在或無法存取），則引發 @ref{2c0,,OSError}。


在 3.6 版的變更: 接受一個 @ref{59b,,path-like object}。

@end deffn

@geindex getsize() (於 os.path 模組中)
@anchor{library/os path os path getsize}@anchor{2b07}
@deffn {函式} os.path.getsize (path, /)

回傳 `path' 的大小（以位元組為單位）。如果檔案不存在或無法存取，則引發 @ref{2c0,,OSError}。


在 3.6 版的變更: 接受一個 @ref{59b,,path-like object}。

@end deffn

@geindex isabs() (於 os.path 模組中)
@anchor{library/os path os path isabs}@anchor{52c}
@deffn {函式} os.path.isabs (path, /)

如果 `path' 是絕對路徑名，則回傳 @code{True}。在 Unix 上，這表示它以斜線開頭；在 Windows 上，表示這是以兩個（反）斜線開頭或者以一個驅動機字母、冒號和（反）斜線開頭。


在 3.6 版的變更: 接受一個 @ref{59b,,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{bfd}
@deffn {函式} os.path.isfile (path)

如果 `path' 是一個@ref{bfa,,已存在的}常規檔案，則回傳 @code{True}。這將跟隨符號連結，因此同一個路徑可以同時回傳 @ref{bf8,,islink()} 和 @ref{bfd,,isfile()} 的結果為真。


在 3.6 版的變更: 接受一個 @ref{59b,,path-like object}。

@end deffn

@geindex isdir() (於 os.path 模組中)
@anchor{library/os path os path isdir}@anchor{bfc}
@deffn {函式} os.path.isdir (path, /)

如果 `path' 是一個@ref{bfa,,已存在的}目錄，則回傳 @code{True}。這將跟隨符號連結，因此同一個路徑可以同時回傳 @ref{bf8,,islink()} 和 @ref{bfd,,isfile()} 的結果為真。


在 3.6 版的變更: 接受一個 @ref{59b,,path-like object}。

@end deffn

@geindex isjunction() (於 os.path 模組中)
@anchor{library/os path os path isjunction}@anchor{6c3}
@deffn {函式} os.path.isjunction (path)

如果 `path' 是指向@ref{bfb,,已存在的}目錄條目且為聯接點 (junction)，則回傳 @code{True}。如果目前平台不支援聯接點，則始終返回 @code{False}。


在 3.12 版被加入.

@end deffn

@geindex islink() (於 os.path 模組中)
@anchor{library/os path os path islink}@anchor{bf8}
@deffn {函式} os.path.islink (path)

如果 `path' 是指向@ref{bfa,,已存在的}目錄項目且為符號連結，則回傳 @code{True}。如果 Python 執行時不支援符號連結，則始終回傳 @code{False}。


在 3.6 版的變更: 接受一個 @ref{59b,,path-like object}。

@end deffn

@geindex ismount() (於 os.path 模組中)
@anchor{library/os path os path ismount}@anchor{bfe}
@deffn {函式} os.path.ismount (path)

如果路徑名 `path' 是一個掛載點 (`mount point')，則回傳 @code{True}：即在檔案系統中掛載了不同的檔案系統。在 POSIX 系統上，該函式檢查 `path' 的父目錄 @code{`path'/..} 是否位於不同的設備上，或者 @code{`path'/..} 和 `path' 是否指向同一設備上的相同 i-node --- 這應該能夠檢測出所有 Unix 和 POSIX 變體的掛載點。但無法可靠地檢測出相同檔案系統上的綁定掛載點 (bind mount)。在 Linux 系統上，即使它們不是掛載點，也會始終回傳 @code{True} 給 btrfs 子卷（subvolumes）。在 Windows 上，以驅動機字母開頭的根目錄和 UNC 共享路徑始終是掛載點，對於任何其他路徑，會呼叫 @code{GetVolumePathName} 函式來檢查它是否與輸入路徑不同。


在 3.4 版的變更: 新增在 Windows 上檢測非根目錄掛載點的支援。



在 3.6 版的變更: 接受一個 @ref{59b,,path-like object}。

@end deffn

@geindex isdevdrive() (於 os.path 模組中)
@anchor{library/os path os path isdevdrive}@anchor{1915}
@deffn {函式} os.path.isdevdrive (path)

如果路徑名 `path' 位於 Windows Dev 驅動機上，則回傳 @code{True}。Dev 驅動機針對開發人員場景進行了優化，提供更快的讀寫檔案性能。建議將其用於原始程式碼、臨時建置目錄、封包快取和其他 I/O 密集型操作。

可能會對無效的路徑引發錯誤，例如，沒有可識別的驅動機的路徑，但在不支援 Dev 磁碟機的平台上返回 @code{False}。請參閱 Windows 文件@footnote{https://learn.microsoft.com/windows/dev-drive/}以了解有關啟用和建立 Dev 驅動機的資訊。


在 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{32a}
@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{2006,,可用性}: Windows.


在 3.13 版被加入.

@end deffn

@geindex join() (於 os.path 模組中)
@anchor{library/os path os path join}@anchor{1900}
@deffn {函式} os.path.join (path, /, *paths)

聰明地連接一個或多個路徑段。回傳值是 `path' 和 `*paths' 的所有成員的串聯，每個非空部分後面都有一個目錄分隔符號，除了最後一個部分。換句話說，如果最後一個部分為空或以分隔符號結尾，結果只會以分隔符號結尾。如果一個段是絕對路徑（在 Windows 上需要驅動機和根），則忽略所有之前的段，並從絕對路徑段繼續連接。

在 Windows 上，當遇到根路徑段（例如，@code{r'\foo'}）時，驅動機不會被重置。如果一個段位於不同的驅動機上，或者是絕對路徑，則將忽略所有之前的段並重置驅動機。請注意，由於每個驅動機都有目前目錄，@code{os.path.join("c:", "foo")} 表示相對於驅動機 @code{C:} 的目前目錄的路徑（即 @code{c:foo}），而不是 @code{c:\foo}。


在 3.6 版的變更: `path' 和 `paths' 接受 @ref{59b,,path-like object} 作為參數。

@end deffn

@geindex normcase() (於 os.path 模組中)
@anchor{library/os path os path normcase}@anchor{2b08}
@deffn {函式} os.path.normcase (path, /)

將路徑名的大小寫規範化。在 Windows 上，將路徑名中的所有字元轉換為小寫，並將正斜線轉換為反斜線。在其他作業系統上，回傳原始路徑。


在 3.6 版的變更: 接受一個 @ref{59b,,path-like object}。

@end deffn

@geindex normpath() (於 os.path 模組中)
@anchor{library/os path os path normpath}@anchor{151a}
@deffn {函式} os.path.normpath (path)

通過合併多餘的分隔符號和上層引用來標準化路徑名，使得 @code{A//B}、@code{A/B/}、@code{A/./B} 和 @code{A/foo/../B} 都變成 @code{A/B}。這種字串操作可能會改變包含符號連結的路徑的含義。在 Windows 上，它將正斜線轉換為反斜線。要標準化大小寫，請使用 @ref{2b08,,normcase()}。

@cartouche
@quotation 備註 
在 POSIX 系統中，根據 IEEE Std 1003.1 2013 版; 4.13 Pathname Resolution@footnote{https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_13} 標準，如果一個路徑名恰好以兩個斜線開頭，則在前導字元後的第一個部分可能會以由實作品自行定義的方式解釋，雖然多於兩個前導字元應該被視為單個字元。
@end quotation
@end cartouche


在 3.6 版的變更: 接受一個 @ref{59b,,path-like object}。

@end deffn

@geindex realpath() (於 os.path 模組中)
@anchor{library/os path os path realpath}@anchor{262}
@deffn {函式} os.path.realpath (path, /, *, strict=False)

回傳指定檔案名稱的規範路徑，會消除路徑中遇到的所有符號連結（如果作業系統支援）。在 Windows 上，此函式還會解析 MS-DOS（也稱為 8.3）樣式的名稱，例如 @code{C:\\PROGRA~1} 會被解析為 @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{2c0,,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{264,,FileNotFoundError} is raised if `path' does not exist,
or another @ref{2c0,,OSError} if it is otherwise inaccessible.

If `strict' is @ref{263,,os.path.ALLOW_MISSING}, errors other than
@ref{264,,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 備註 
此函式模擬作業系統使路徑成為規範的過程，Windows 和 UNIX 之間在鏈接和後續路徑部份交互方式方面略有不同。

作業系統的 API 會根據需要自動使路徑正則，因此通常不需要呼叫此函式。
@end quotation
@end cartouche


在 3.6 版的變更: 接受一個 @ref{59b,,path-like object}。



在 3.8 版的變更: 在 Windows 上，現在會解析符號連結和連接點。



在 3.10 版的變更: 新增 `strict' 參數。



在 3.14 版的變更: The @ref{263,,ALLOW_MISSING} value for the `strict' parameter
was added.

@end deffn

@geindex ALLOW_MISSING (於 os.path 模組中)
@anchor{library/os path os path ALLOW_MISSING}@anchor{263}
@deffn {資料} os.path.ALLOW_MISSING

Special value used for the `strict' argument in @ref{262,,realpath()}.


在 3.14 版被加入.

@end deffn

@geindex relpath() (於 os.path 模組中)
@anchor{library/os path os path relpath}@anchor{6ca}
@deffn {函式} os.path.relpath (path, start=os.curdir)

從目前目錄或可選的 `start' 目錄回傳到 `path' 的相對檔案路徑。這是一個路徑計算：不會存取檔案系統來確認 `path' 或 `start' 的存在或屬性。在 Windows 上，當 `path' 和 `start' 在不同的驅動機上時，會引發 @ref{2eb,,ValueError}。

`start' 的預設值為 @ref{2b09,,os.curdir}。


在 3.6 版的變更: 接受一個 @ref{59b,,path-like object}。

@end deffn

@geindex samefile() (於 os.path 模組中)
@anchor{library/os path os path samefile}@anchor{116c}
@deffn {函式} os.path.samefile (path1, path2, /)

如果兩個路徑名引數指向同一個檔案或目錄，則回傳 @code{True}。這是通過設備編號和 i-node 編號來確定的，如果對任一路徑名的 @ref{26d,,os.stat()} 呼叫失敗，則會引發異常。


在 3.2 版的變更: 新增對 Windows 的支援。



在 3.4 版的變更: 現在在 Windows 上使用與其他所有平台相同的實作方式。



在 3.6 版的變更: 接受一個 @ref{59b,,path-like object}。

@end deffn

@geindex sameopenfile() (於 os.path 模組中)
@anchor{library/os path os path sameopenfile}@anchor{2b0a}
@deffn {函式} os.path.sameopenfile (fp1, fp2)

如果文件描述符 `fp1' 和 `fp2' 指向同一個檔案，則回傳 @code{True}。


在 3.2 版的變更: 新增對 Windows 的支援。



在 3.6 版的變更: 接受一個 @ref{59b,,path-like object}。

@end deffn

@geindex samestat() (於 os.path 模組中)
@anchor{library/os path os path samestat}@anchor{116b}
@deffn {函式} os.path.samestat (stat1, stat2, /)

如果 stat 值組 `stat1' 和 `stat2' 指向同一個檔案，則回傳 @code{True}。這些結構可能由 @ref{f87,,os.fstat()}、@ref{6c1,,os.lstat()} 或 @ref{26d,,os.stat()} 回傳。此函式使用 @ref{116c,,samefile()} 和 @ref{2b0a,,sameopenfile()} 實現了底層比較。


在 3.4 版的變更: 新增對 Windows 的支援。

@end deffn

@geindex split() (於 os.path 模組中)
@anchor{library/os path os path split}@anchor{2b03}
@deffn {函式} os.path.split (path, /)

將路徑名 `path' 拆分為 @code{(head, tail)} 一對，其中 `tail' 是最後一個路徑名部份，`head' 是在它之前的所有部分。`tail' 部分不會包含斜線；如果 `path' 以斜線結尾，則 `tail' 將為空。如果 `path' 中沒有斜線，則 `head' 將為空。如果 `path' 為空，則 `head' 和 `tail' 都為空。除非 `head' 是根目錄（僅有一個或多個斜線），否則從 `head' 中刪除尾部的斜線。在所有情況下，@code{join(head, tail)} 回傳指向與 `path' 相同位置的路徑（但字串可能不同）。還可以參考函式 @ref{2af9,,dirname()} 和 @ref{2afa,,basename()}。


在 3.6 版的變更: 接受一個 @ref{59b,,path-like object}。

@end deffn

@geindex splitdrive() (於 os.path 模組中)
@anchor{library/os path os path splitdrive}@anchor{dea}
@deffn {函式} os.path.splitdrive (path, /)

將路徑名 `path' 拆分為 @code{(drive, tail)} 一對，其中 `drive' 是掛載點或空字串。在不使用驅動機規範的系統上，`drive' 將始終為空字串。在所有情況下，@code{drive + tail} 將與 `path' 相同。

在 Windows 上，將路徑名拆分為驅動機或 UNC 共享點以及相對路徑。

如果路徑包含驅動機字母，則 `drive' 將包含從頭到冒號（包括冒號）的所有內容：

@example
>>> splitdrive("c:/dir")
("c:", "/dir")
@end example

如果路徑包含 UNC 路徑，則驅動機將包含主機名和共享名：

@example
>>> splitdrive("//host/computer/dir")
("//host/computer", "/dir")
@end example


在 3.6 版的變更: 接受一個 @ref{59b,,path-like object}。

@end deffn

@geindex splitroot() (於 os.path 模組中)
@anchor{library/os path os path splitroot}@anchor{6c4}
@deffn {函式} os.path.splitroot (path, /)

將路徑名 `path' 拆分為一個 3 項值組 @code{(drive, root, tail)}，其中 `drive' 是設備名稱或掛載點，`root' 是驅動機後的分隔符字串，`tail' 是在根後的所有內容。這些項目中的任何一個都可能是空字串。在所有情況下，@code{drive + root + tail} 將與 `path' 相同。

在 POSIX 系統上，`drive' 始終為空。`root' 可能為空（如果 `path' 是相對路徑），一個斜線（如果 `path' 是絕對路徑），或者兩個斜線（根據 IEEE Std 1003.1-2017; 4.13 Pathname Resolution@footnote{https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_13} 的實作定義）。例如：

@example
>>> splitroot('/home/sam')
('@w{'}, '/', 'home/sam')
>>> splitroot('//home/sam')
('@w{'}, '//', 'home/sam')
>>> splitroot('///home/sam')
('@w{'}, '/', '//home/sam')
@end example

在 Windows 上，`drive' 可能為空、驅動機名稱、UNC 共享或設備名稱。`root' 可能為空，斜線或反斜線。例如：

@example
>>> splitroot('C:/Users/Sam')
('C:', '/', 'Users/Sam')
>>> splitroot('//Server/Share/Users/Sam')
('//Server/Share', '/', 'Users/Sam')
@end example


在 3.12 版被加入.

@end deffn

@geindex splitext() (於 os.path 模組中)
@anchor{library/os path os path splitext}@anchor{18c0}
@deffn {函式} os.path.splitext (path, /)

將路徑名 `path' 拆分為一對 @code{(root, ext)}，使得 @code{root + ext == path}，且副檔名 `ext' 為空或以點開頭且最多包含一個點 (period)。

如果路徑不包含副檔名，則 `ext' 將為 @code{'@w{'}}：

@example
>>> splitext('bar')
('bar', '@w{'})
@end example

如果路徑包含副檔名，則 `ext' 將設置為該副檔名，包括前導的點。請注意，前面的點將被忽略：

@example
>>> splitext('foo.bar.exe')
('foo.bar', '.exe')
>>> splitext('/foo/bar.exe')
('/foo/bar', '.exe')
@end example

路徑的最後一個部份的前導點被認為是根的一部分：

@example
>>> splitext('.cshrc')
('.cshrc', '@w{'})
>>> splitext('/foo/....jpg')
('/foo/....jpg', '@w{'})
@end example


在 3.6 版的變更: 接受一個 @ref{59b,,path-like object}。

@end deffn

@geindex supports_unicode_filenames (於 os.path 模組中)
@anchor{library/os path os path supports_unicode_filenames}@anchor{1682}
@deffn {資料} os.path.supports_unicode_filenames

如果可以使用任意的 Unicode 字串作為檔案名（在檔案系統所施加的限制範圍內），則回傳 @code{True}。
@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 --- 直譯 stat 的結果,filecmp --- 檔案與目錄比較,os path --- 常見的路徑名操作,檔案與目錄存取
@anchor{library/stat doc}@anchor{2b0b}@anchor{library/stat module-stat}@anchor{d6}@anchor{library/stat stat-interpreting-stat-results}@anchor{2b0c}@anchor{library/stat translation-repo}@anchor{2b0d}
@subsection @code{stat} --- 直譯 @code{stat()} 的結果


@geindex module; stat

`原始碼：'Lib/stat.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/stat.py}


__________________________________________________________________


The @ref{d6,,stat} module defines constants and functions for interpreting the
results of @ref{26d,,os.stat()}, @ref{f87,,os.fstat()} and @ref{6c1,,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.


@ref{d6,,stat} 模組定義了以下函式，用於測試特定檔案類型：

@geindex S_ISDIR() (於 stat 模組中)
@anchor{library/stat stat S_ISDIR}@anchor{2b0e}
@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{2b0f}
@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{2b10}
@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{2b11}
@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{2b12}
@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{2b13}
@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{2b14}
@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{1c74}
@deffn {函式} stat.S_ISDOOR (mode)

Return non-zero if the mode is from a door.


在 3.4 版被加入.

@end deffn

@geindex S_ISPORT() (於 stat 模組中)
@anchor{library/stat stat S_ISPORT}@anchor{1c75}
@deffn {函式} stat.S_ISPORT (mode)

Return non-zero if the mode is from an event port.


在 3.4 版被加入.

@end deffn

@geindex S_ISWHT() (於 stat 模組中)
@anchor{library/stat stat S_ISWHT}@anchor{1c76}
@deffn {函式} stat.S_ISWHT (mode)

Return non-zero if the mode is from a whiteout.


在 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{2b15}
@deffn {函式} stat.S_IMODE (mode)

Return the portion of the file's mode that can be set by
@ref{524,,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{2b16}
@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
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{134c}
@deffn {函式} stat.filemode (mode)

Convert a file's mode to a string of the form '-rwxrwxrwx'.


在 3.3 版被加入.



在 3.4 版的變更: The function supports @ref{11b6,,S_IFDOOR}, @ref{11b7,,S_IFPORT} and
@ref{11b8,,S_IFWHT}.

@end deffn

All the variables below are simply symbolic indexes into the 10-tuple returned
by @ref{26d,,os.stat()}, @ref{f87,,os.fstat()} or @ref{6c1,,os.lstat()}.

@geindex ST_MODE (於 stat 模組中)
@anchor{library/stat stat ST_MODE}@anchor{11b5}
@deffn {資料} stat.ST_MODE

Inode protection mode.
@end deffn

@geindex ST_INO (於 stat 模組中)
@anchor{library/stat stat ST_INO}@anchor{2b17}
@deffn {資料} stat.ST_INO

Inode number.
@end deffn

@geindex ST_DEV (於 stat 模組中)
@anchor{library/stat stat ST_DEV}@anchor{2b18}
@deffn {資料} stat.ST_DEV

Device inode resides on.
@end deffn

@geindex ST_NLINK (於 stat 模組中)
@anchor{library/stat stat ST_NLINK}@anchor{2b19}
@deffn {資料} stat.ST_NLINK

Number of links to the inode.
@end deffn

@geindex ST_UID (於 stat 模組中)
@anchor{library/stat stat ST_UID}@anchor{2b1a}
@deffn {資料} stat.ST_UID

User id of the owner.
@end deffn

@geindex ST_GID (於 stat 模組中)
@anchor{library/stat stat ST_GID}@anchor{2b1b}
@deffn {資料} stat.ST_GID

Group id of the owner.
@end deffn

@geindex ST_SIZE (於 stat 模組中)
@anchor{library/stat stat ST_SIZE}@anchor{2b1c}
@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{2b1d}
@deffn {資料} stat.ST_ATIME

Time of last access.
@end deffn

@geindex ST_MTIME (於 stat 模組中)
@anchor{library/stat stat ST_MTIME}@anchor{2b1e}
@deffn {資料} stat.ST_MTIME

Time of last modification.
@end deffn

@geindex ST_CTIME (於 stat 模組中)
@anchor{library/stat stat ST_CTIME}@anchor{2b1f}
@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{26d,,os.stat()},
@ref{f87,,os.fstat()}, or @ref{6c1,,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{11b5,,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{2b20}
@deffn {資料} stat.S_IFSOCK

Socket.
@end deffn

@geindex S_IFLNK (於 stat 模組中)
@anchor{library/stat stat S_IFLNK}@anchor{2b21}
@deffn {資料} stat.S_IFLNK

Symbolic link.
@end deffn

@geindex S_IFREG (於 stat 模組中)
@anchor{library/stat stat S_IFREG}@anchor{2b22}
@deffn {資料} stat.S_IFREG

Regular file.
@end deffn

@geindex S_IFBLK (於 stat 模組中)
@anchor{library/stat stat S_IFBLK}@anchor{2b23}
@deffn {資料} stat.S_IFBLK

Block device.
@end deffn

@geindex S_IFDIR (於 stat 模組中)
@anchor{library/stat stat S_IFDIR}@anchor{2b24}
@deffn {資料} stat.S_IFDIR

Directory.
@end deffn

@geindex S_IFCHR (於 stat 模組中)
@anchor{library/stat stat S_IFCHR}@anchor{2b25}
@deffn {資料} stat.S_IFCHR

Character device.
@end deffn

@geindex S_IFIFO (於 stat 模組中)
@anchor{library/stat stat S_IFIFO}@anchor{2b26}
@deffn {資料} stat.S_IFIFO

FIFO.
@end deffn

@geindex S_IFDOOR (於 stat 模組中)
@anchor{library/stat stat S_IFDOOR}@anchor{11b6}
@deffn {資料} stat.S_IFDOOR

Door.


在 3.4 版被加入.

@end deffn

@geindex S_IFPORT (於 stat 模組中)
@anchor{library/stat stat S_IFPORT}@anchor{11b7}
@deffn {資料} stat.S_IFPORT

Event port.


在 3.4 版被加入.

@end deffn

@geindex S_IFWHT (於 stat 模組中)
@anchor{library/stat stat S_IFWHT}@anchor{11b8}
@deffn {資料} stat.S_IFWHT

Whiteout.


在 3.4 版被加入.

@end deffn

@cartouche
@quotation 備註 
@ref{11b6,,S_IFDOOR}, @ref{11b7,,S_IFPORT} or @ref{11b8,,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{524,,os.chmod()}:

@geindex S_ISUID (於 stat 模組中)
@anchor{library/stat stat S_ISUID}@anchor{2b27}
@deffn {資料} stat.S_ISUID

Set UID bit.
@end deffn

@geindex S_ISGID (於 stat 模組中)
@anchor{library/stat stat S_ISGID}@anchor{2b28}
@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 @ref{2b28,,S_ISGID} bit set.  For a
file that does not have the group execution bit (@ref{2b29,,S_IXGRP})
set, the set-group-ID bit indicates mandatory file/record locking
(see also @ref{2b2a,,S_ENFMT}).
@end deffn

@geindex S_ISVTX (於 stat 模組中)
@anchor{library/stat stat S_ISVTX}@anchor{2b2b}
@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{2b2c}
@deffn {資料} stat.S_IRWXU

Mask for file owner permissions.
@end deffn

@geindex S_IRUSR (於 stat 模組中)
@anchor{library/stat stat S_IRUSR}@anchor{2b2d}
@deffn {資料} stat.S_IRUSR

Owner has read permission.
@end deffn

@geindex S_IWUSR (於 stat 模組中)
@anchor{library/stat stat S_IWUSR}@anchor{2b2e}
@deffn {資料} stat.S_IWUSR

Owner has write permission.
@end deffn

@geindex S_IXUSR (於 stat 模組中)
@anchor{library/stat stat S_IXUSR}@anchor{2b2f}
@deffn {資料} stat.S_IXUSR

Owner has execute permission.
@end deffn

@geindex S_IRWXG (於 stat 模組中)
@anchor{library/stat stat S_IRWXG}@anchor{2b30}
@deffn {資料} stat.S_IRWXG

Mask for group permissions.
@end deffn

@geindex S_IRGRP (於 stat 模組中)
@anchor{library/stat stat S_IRGRP}@anchor{2b31}
@deffn {資料} stat.S_IRGRP

Group has read permission.
@end deffn

@geindex S_IWGRP (於 stat 模組中)
@anchor{library/stat stat S_IWGRP}@anchor{2b32}
@deffn {資料} stat.S_IWGRP

Group has write permission.
@end deffn

@geindex S_IXGRP (於 stat 模組中)
@anchor{library/stat stat S_IXGRP}@anchor{2b29}
@deffn {資料} stat.S_IXGRP

Group has execute permission.
@end deffn

@geindex S_IRWXO (於 stat 模組中)
@anchor{library/stat stat S_IRWXO}@anchor{2b33}
@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{2b34}
@deffn {資料} stat.S_IROTH

Others have read permission.
@end deffn

@geindex S_IWOTH (於 stat 模組中)
@anchor{library/stat stat S_IWOTH}@anchor{2b35}
@deffn {資料} stat.S_IWOTH

Others have write permission.
@end deffn

@geindex S_IXOTH (於 stat 模組中)
@anchor{library/stat stat S_IXOTH}@anchor{2b36}
@deffn {資料} stat.S_IXOTH

Others have execute permission.
@end deffn

@geindex S_ENFMT (於 stat 模組中)
@anchor{library/stat stat S_ENFMT}@anchor{2b2a}
@deffn {資料} stat.S_ENFMT

System V file locking enforcement.  This flag is shared with @ref{2b28,,S_ISGID}:
file/record locking is enforced on files that do not have the group
execution bit (@ref{2b29,,S_IXGRP}) set.
@end deffn

@geindex S_IREAD (於 stat 模組中)
@anchor{library/stat stat S_IREAD}@anchor{2b37}
@deffn {資料} stat.S_IREAD

Unix V7 synonym for @ref{2b2d,,S_IRUSR}.
@end deffn

@geindex S_IWRITE (於 stat 模組中)
@anchor{library/stat stat S_IWRITE}@anchor{2b38}
@deffn {資料} stat.S_IWRITE

Unix V7 synonym for @ref{2b2e,,S_IWUSR}.
@end deffn

@geindex S_IEXEC (於 stat 模組中)
@anchor{library/stat stat S_IEXEC}@anchor{2b39}
@deffn {資料} stat.S_IEXEC

Unix V7 synonym for @ref{2b2f,,S_IXUSR}.
@end deffn

The following flags can be used in the `flags' argument of @ref{12ee,,os.chflags()}:

@geindex UF_SETTABLE (於 stat 模組中)
@anchor{library/stat stat UF_SETTABLE}@anchor{2b3a}
@deffn {資料} stat.UF_SETTABLE

All user settable flags.


在 3.13 版被加入.

@end deffn

@geindex UF_NODUMP (於 stat 模組中)
@anchor{library/stat stat UF_NODUMP}@anchor{2b3b}
@deffn {資料} stat.UF_NODUMP

Do not dump the file.
@end deffn

@geindex UF_IMMUTABLE (於 stat 模組中)
@anchor{library/stat stat UF_IMMUTABLE}@anchor{2b3c}
@deffn {資料} stat.UF_IMMUTABLE

The file may not be changed.
@end deffn

@geindex UF_APPEND (於 stat 模組中)
@anchor{library/stat stat UF_APPEND}@anchor{2b3d}
@deffn {資料} stat.UF_APPEND

The file may only be appended to.
@end deffn

@geindex UF_OPAQUE (於 stat 模組中)
@anchor{library/stat stat UF_OPAQUE}@anchor{2b3e}
@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{2b3f}
@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{2b40}
@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{2b41}
@deffn {資料} stat.UF_TRACKED

Used for handling document IDs (macOS)


在 3.13 版被加入.

@end deffn

@geindex UF_DATAVAULT (於 stat 模組中)
@anchor{library/stat stat UF_DATAVAULT}@anchor{2b42}
@deffn {資料} stat.UF_DATAVAULT

The file needs an entitlement for reading or writing (macOS 10.13+)


在 3.13 版被加入.

@end deffn

@geindex UF_HIDDEN (於 stat 模組中)
@anchor{library/stat stat UF_HIDDEN}@anchor{2b43}
@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{2b44}
@deffn {資料} stat.SF_SETTABLE

All super-user changeable flags


在 3.13 版被加入.

@end deffn

@geindex SF_SUPPORTED (於 stat 模組中)
@anchor{library/stat stat SF_SUPPORTED}@anchor{2b45}
@deffn {資料} stat.SF_SUPPORTED

All super-user supported flags

@ref{2006,,可用性}: macOS


在 3.13 版被加入.

@end deffn

@geindex SF_SYNTHETIC (於 stat 模組中)
@anchor{library/stat stat SF_SYNTHETIC}@anchor{2b46}
@deffn {資料} stat.SF_SYNTHETIC

All super-user read-only synthetic flags

@ref{2006,,可用性}: macOS


在 3.13 版被加入.

@end deffn

@geindex SF_ARCHIVED (於 stat 模組中)
@anchor{library/stat stat SF_ARCHIVED}@anchor{2b47}
@deffn {資料} stat.SF_ARCHIVED

The file may be archived.
@end deffn

@geindex SF_IMMUTABLE (於 stat 模組中)
@anchor{library/stat stat SF_IMMUTABLE}@anchor{2b48}
@deffn {資料} stat.SF_IMMUTABLE

The file may not be changed.
@end deffn

@geindex SF_APPEND (於 stat 模組中)
@anchor{library/stat stat SF_APPEND}@anchor{2b49}
@deffn {資料} stat.SF_APPEND

The file may only be appended to.
@end deffn

@geindex SF_RESTRICTED (於 stat 模組中)
@anchor{library/stat stat SF_RESTRICTED}@anchor{2b4a}
@deffn {資料} stat.SF_RESTRICTED

The file needs an entitlement to write to (macOS 10.13+)


在 3.13 版被加入.

@end deffn

@geindex SF_NOUNLINK (於 stat 模組中)
@anchor{library/stat stat SF_NOUNLINK}@anchor{2b4b}
@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{2b4c}
@deffn {資料} stat.SF_SNAPSHOT

The file is a snapshot file.
@end deffn

@geindex SF_FIRMLINK (於 stat 模組中)
@anchor{library/stat stat SF_FIRMLINK}@anchor{2b4d}
@deffn {資料} stat.SF_FIRMLINK

The file is a firmlink (macOS 10.15+)


在 3.13 版被加入.

@end deffn

@geindex SF_DATALESS (於 stat 模組中)
@anchor{library/stat stat SF_DATALESS}@anchor{2b4e}
@deffn {資料} stat.SF_DATALESS

The file is a dataless object (macOS 10.15+)


在 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{26d,,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{2b4f}
@deffn {資料} stat.FILE_ATTRIBUTE_ARCHIVE
@anchor{library/stat stat FILE_ATTRIBUTE_COMPRESSED}@anchor{2b50}
@deffnx {資料} stat.FILE_ATTRIBUTE_COMPRESSED
@anchor{library/stat stat FILE_ATTRIBUTE_DEVICE}@anchor{2b51}
@deffnx {資料} stat.FILE_ATTRIBUTE_DEVICE
@anchor{library/stat stat FILE_ATTRIBUTE_DIRECTORY}@anchor{2b52}
@deffnx {資料} stat.FILE_ATTRIBUTE_DIRECTORY
@anchor{library/stat stat FILE_ATTRIBUTE_ENCRYPTED}@anchor{2b53}
@deffnx {資料} stat.FILE_ATTRIBUTE_ENCRYPTED
@anchor{library/stat stat FILE_ATTRIBUTE_HIDDEN}@anchor{2b54}
@deffnx {資料} stat.FILE_ATTRIBUTE_HIDDEN
@anchor{library/stat stat FILE_ATTRIBUTE_INTEGRITY_STREAM}@anchor{2b55}
@deffnx {資料} stat.FILE_ATTRIBUTE_INTEGRITY_STREAM
@anchor{library/stat stat FILE_ATTRIBUTE_NORMAL}@anchor{2b56}
@deffnx {資料} stat.FILE_ATTRIBUTE_NORMAL
@anchor{library/stat stat FILE_ATTRIBUTE_NOT_CONTENT_INDEXED}@anchor{2b57}
@deffnx {資料} stat.FILE_ATTRIBUTE_NOT_CONTENT_INDEXED
@anchor{library/stat stat FILE_ATTRIBUTE_NO_SCRUB_DATA}@anchor{2b58}
@deffnx {資料} stat.FILE_ATTRIBUTE_NO_SCRUB_DATA
@anchor{library/stat stat FILE_ATTRIBUTE_OFFLINE}@anchor{2b59}
@deffnx {資料} stat.FILE_ATTRIBUTE_OFFLINE
@anchor{library/stat stat FILE_ATTRIBUTE_READONLY}@anchor{2b5a}
@deffnx {資料} stat.FILE_ATTRIBUTE_READONLY
@anchor{library/stat stat FILE_ATTRIBUTE_REPARSE_POINT}@anchor{2b5b}
@deffnx {資料} stat.FILE_ATTRIBUTE_REPARSE_POINT
@anchor{library/stat stat FILE_ATTRIBUTE_SPARSE_FILE}@anchor{2b5c}
@deffnx {資料} stat.FILE_ATTRIBUTE_SPARSE_FILE
@anchor{library/stat stat FILE_ATTRIBUTE_SYSTEM}@anchor{2b5d}
@deffnx {資料} stat.FILE_ATTRIBUTE_SYSTEM
@anchor{library/stat stat FILE_ATTRIBUTE_TEMPORARY}@anchor{2b5e}
@deffnx {資料} stat.FILE_ATTRIBUTE_TEMPORARY
@anchor{library/stat stat FILE_ATTRIBUTE_VIRTUAL}@anchor{2b5f}
@deffnx {資料} stat.FILE_ATTRIBUTE_VIRTUAL


在 3.5 版被加入.

@end deffn

On Windows, the following constants are available for comparing against the
@code{st_reparse_tag} member returned by @ref{6c1,,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{2b60}
@deffn {資料} stat.IO_REPARSE_TAG_SYMLINK
@anchor{library/stat stat IO_REPARSE_TAG_MOUNT_POINT}@anchor{2b61}
@deffnx {資料} stat.IO_REPARSE_TAG_MOUNT_POINT
@anchor{library/stat stat IO_REPARSE_TAG_APPEXECLINK}@anchor{2b62}
@deffnx {資料} stat.IO_REPARSE_TAG_APPEXECLINK


在 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 filecmp --- 檔案與目錄比較,tempfile --- 生成臨時檔案和目錄,stat --- 直譯 stat 的結果,檔案與目錄存取
@anchor{library/filecmp doc}@anchor{2b63}@anchor{library/filecmp filecmp-file-and-directory-comparisons}@anchor{2b64}@anchor{library/filecmp module-filecmp}@anchor{5e}@anchor{library/filecmp translation-repo}@anchor{2b65}
@subsection @code{filecmp} --- 檔案與目錄比較


@geindex module; filecmp

`原始碼：'Lib/filecmp.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/filecmp.py}


__________________________________________________________________


The @ref{5e,,filecmp} module defines functions to compare files and directories,
with various optional time/correctness trade-offs. For comparing files,
see also the @ref{3b,,difflib} module.

@ref{5e,,filecmp} 模組定義了以下函式：

@geindex cmp() (於 filecmp 模組中)
@anchor{library/filecmp filecmp cmp}@anchor{192c}
@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{26d,,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{26d,,os.stat()} information for the
file changes.  The entire cache may be cleared using @ref{1139,,clear_cache()}.
@end deffn

@geindex cmpfiles() (於 filecmp 模組中)
@anchor{library/filecmp filecmp cmpfiles}@anchor{18ac}
@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{192c,,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{1139}
@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.


在 3.4 版被加入.

@end deffn

@menu
* The dircmp class:: 

@end menu

@node The dircmp class,,,filecmp --- 檔案與目錄比較
@anchor{library/filecmp dircmp-objects}@anchor{2b66}@anchor{library/filecmp the-dircmp-class}@anchor{2b67}
@subsubsection The @code{dircmp} class


@geindex dircmp (filecmp 中的類別)
@anchor{library/filecmp filecmp dircmp}@anchor{113b}
@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{113a,,filecmp.DEFAULT_IGNORES}.  `hide' is a list of names to hide, and
defaults to @code{[os.curdir, os.pardir]}.

The @ref{113b,,dircmp} class compares files by doing `shallow' comparisons
as described for @ref{192c,,filecmp.cmp()} by default using the `shallow'
parameter.


在 3.13 版的變更: Added the `shallow' parameter.


The @ref{113b,,dircmp} class provides the following methods:

@geindex report() (filecmp.dircmp 的方法)
@anchor{library/filecmp filecmp dircmp report}@anchor{2b68}
@deffn {方法} report ()

Print (to @ref{cc4,,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{2b69}
@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{2b6a}
@deffn {方法} report_full_closure ()

Print a comparison between `a' and `b' and common subdirectories
(recursively).
@end deffn

The @ref{113b,,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{6f3,,__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{2b6b}
@deffn {屬性} left

The directory `a'.
@end deffn

@geindex right (filecmp.dircmp 的屬性)
@anchor{library/filecmp filecmp dircmp right}@anchor{2b6c}
@deffn {屬性} right

The directory `b'.
@end deffn

@geindex left_list (filecmp.dircmp 的屬性)
@anchor{library/filecmp filecmp dircmp left_list}@anchor{2b6d}
@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{2b6e}
@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{2b6f}
@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{2b70}
@deffn {屬性} left_only

Files and subdirectories only in `a'.
@end deffn

@geindex right_only (filecmp.dircmp 的屬性)
@anchor{library/filecmp filecmp dircmp right_only}@anchor{2b71}
@deffn {屬性} right_only

Files and subdirectories only in `b'.
@end deffn

@geindex common_dirs (filecmp.dircmp 的屬性)
@anchor{library/filecmp filecmp dircmp common_dirs}@anchor{2b72}
@deffn {屬性} common_dirs

Subdirectories in both `a' and `b'.
@end deffn

@geindex common_files (filecmp.dircmp 的屬性)
@anchor{library/filecmp filecmp dircmp common_files}@anchor{2b73}
@deffn {屬性} common_files

Files in both `a' and `b'.
@end deffn

@geindex common_funny (filecmp.dircmp 的屬性)
@anchor{library/filecmp filecmp dircmp common_funny}@anchor{2b74}
@deffn {屬性} common_funny

Names in both `a' and `b', such that the type differs between the
directories, or names for which @ref{26d,,os.stat()} reports an error.
@end deffn

@geindex same_files (filecmp.dircmp 的屬性)
@anchor{library/filecmp filecmp dircmp same_files}@anchor{2b75}
@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{2b76}
@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{2b77}
@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{1bd1}
@deffn {屬性} subdirs

A dictionary mapping names in @ref{2b72,,common_dirs} to @ref{113b,,dircmp}
instances (or MyDirCmp instances if this instance is of type MyDirCmp, a
subclass of @ref{113b,,dircmp}).


在 3.10 版的變更: Previously entries were always @ref{113b,,dircmp} instances. Now entries
are the same type as `self', if `self' is a subclass of
@ref{113b,,dircmp}.

@end deffn
@end deffn

@geindex DEFAULT_IGNORES (於 filecmp 模組中)
@anchor{library/filecmp filecmp DEFAULT_IGNORES}@anchor{113a}
@deffn {資料} filecmp.DEFAULT_IGNORES


在 3.4 版被加入.


List of directories ignored by @ref{113b,,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 --- 生成臨時檔案和目錄,glob --- Unix 風格的路徑名稱模式擴展,filecmp --- 檔案與目錄比較,檔案與目錄存取
@anchor{library/tempfile doc}@anchor{2b78}@anchor{library/tempfile module-tempfile}@anchor{e6}@anchor{library/tempfile tempfile-generate-temporary-files-and-directories}@anchor{2b79}@anchor{library/tempfile translation-repo}@anchor{2b7a}
@subsection @code{tempfile} --- 生成臨時檔案和目錄


@geindex module; tempfile

`原始碼：'Lib/tempfile.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/tempfile.py}

@geindex temporary（臨時）;file name（檔案名稱）
@geindex temporary（臨時）;file（檔案）


__________________________________________________________________


該 module（模組）用於建立臨時檔案和目錄，它可以在所有有支援的平臺上使用。@ref{2b7b,,TemporaryFile}、@ref{6e6,,NamedTemporaryFile}、@ref{1435,,TemporaryDirectory} 和 @ref{89b,,SpooledTemporaryFile} 是有自動清除功能的高階介面，可作為@ref{1e1,,情境管理器 (context manager)} 使用。@ref{2b7c,,mkstemp()} 和 @ref{528,,mkdtemp()} 是低階函式，使用完畢後需手動清理。

所有可被使用者呼叫的函式和建構函式都帶有可以設定臨時檔案和臨時目錄的路徑和名稱的引數。此 module 所使用的檔名為一個隨機字元組成的字串，這讓檔案可以更安全地在共享的臨時目錄中被建立。為了維持向後相容性，引數的順序會稍微奇怪，所以為了讓程式更容易被理解，建議使用關鍵字引數。

這個 module 定義了以下可供使用者呼叫的項目：

@geindex TemporaryFile() (於 tempfile 模組中)
@anchor{library/tempfile tempfile TemporaryFile}@anchor{2b7b}
@deffn {函式} tempfile.TemporaryFile (mode='w+b', buffering=-1, encoding=None, newline=None, suffix=None, prefix=None, dir=None, *, errors=None)

回傳一個可當作臨時儲存區域的@ref{28ad,,類檔案物件}。建立該檔案使用了與 @ref{2b7c,,mkstemp()} 相同的安全規則。它將在關閉（包括當物件被垃圾回收 (garbage collect) 時的隱式關閉）後立即銷毀。在 Unix 下，該檔案所在的目錄可能根本不被建立、或者在建立檔案後立即就被刪除，其他平臺不支援此功能；你的程式不應依賴使用此功能建立的臨時檔案名稱，因為它在檔案系統中的名稱有可能是不可見的。

生成的物件可以作為@ref{1e1,,情境管理器}使用（參見 @ref{2b7d,,範例}）。完成情境或銷毀臨時檔案物件後，臨時檔案將從檔案系統中刪除。

`mode' 參數預設為 @code{'w+b'}，所以建立的檔案不用關閉就可以讀取或寫入。因為用的是二進位制模式，所以無論存的是什麼資料，它在所有平臺上的行為都一致。`buffering'、`encoding'、`errors' 和 `newline' 的含義與 @ref{315,,open()} 中的相同。

參數 `dir'、`prefix' 和 `suffix' 的含義和預設值都與它們在 @ref{2b7c,,mkstemp()} 中的相同。

在 POSIX 平臺上，回傳物件是真實的檔案物件。在其他平臺上，它是一個 file-like object，它的 @code{file} 屬性為底層的真實檔案物件。

如果可用且可運作，則使用 @ref{116e,,os.O_TMPFILE} 旗標（僅限於 Linux，需要 3.11 版本以上的核心）。

在不是 Posix 或 Cygwin 的平臺上，TemporaryFile 是 NamedTemporaryFile 的別名。

引發一個附帶引數 @code{fullpath} 的 @code{tempfile.mkstemp} @ref{1b70,,稽核事件}。


在 3.5 版的變更: 如果可用，自此開始使用 @ref{116e,,os.O_TMPFILE} 旗標。



在 3.8 版的變更: 新增 `errors' 參數。

@end deffn

@geindex NamedTemporaryFile() (於 tempfile 模組中)
@anchor{library/tempfile tempfile NamedTemporaryFile}@anchor{6e6}
@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)

此函式的操作與 @ref{2b7b,,TemporaryFile()} 完全相同，但存在以下差異：


@itemize *

@item 
此函式回傳一個保證在檔案系統中具有可見名稱的檔案。

@item 
為了管理指定檔案，它使用 `delete' 和 `delete_on_close' 參數擴充 @ref{2b7b,,TemporaryFile()} 來指定是否以及如何自動刪除指定檔案。
@end itemize

回傳的物件始終是一個@ref{28ad,,類檔案物件}，其 @code{file} 屬性是底層的真實檔案物件。這個類檔案物件可以在 @ref{186,,with} 陳述式中使用，就像普通檔案一樣。臨時檔案的名稱可以從回傳的類檔案物件的 @code{name} 屬性中取得。在 Unix 上則與 @ref{2b7b,,TemporaryFile()} 不同，目錄條目不會在檔案建立後立即被取消鏈接 (unlink)。

如果 `delete' 為 true（預設值）並且 `delete_on_close' 為 true（預設值），則檔案在關閉後會立即被刪除。如果 `delete' 為 true 並且 `delete_on_close' 為 false，則僅在情境管理器退出時刪除檔案，或者在@ref{28ad,,類檔案物件}完結時刪除檔案。在這種情況下，並不總是保證能成功刪除（請參閱 @ref{11f8,,object.__del__()}）。如果 `delete' 為 false，則會忽略 `delete_on_close' 的值。

因此，要在關閉檔案後使用臨時檔案的名稱重新打開檔案，請確保在關閉時不刪除檔案（將 `delete' 參數設定為 false），或者如果臨時檔案是以 @ref{186,,with} 陳述式建立，要將 `delete_on_close' 參數設定為 false。建議使用後者，因為它有助於在情境管理器退出時自動清理臨時檔案。

在臨時檔案仍處於打開狀態時再次按其名稱打開它，其作用方式如下：


@itemize *

@item 
在 POSIX 上，檔案始終可以再次打開。

@item 
在 Windows 上，確保至少滿足以下條件之一：


@itemize *

@item 
`delete' 為 false

@item 
額外的 open 會共享刪除存取權限（例如，通過使用旗標 @code{O_TEMPORARY} 來呼叫 @ref{f8d,,os.open()}）

@item 
`delete' 為 true 但 `delete_on_close' 為 false。請注意，在這種情況下不共享刪除存取權限的其他 open（例如透過內建的 @ref{315,,open()} 建立）必須在退出情境管理器之前關閉，否則情境管理器上的 @ref{12f6,,os.unlink()} 呼叫退出將失敗並出現 @ref{f39,,PermissionError}。
@end itemize
@end itemize

在 Windows 上，如果 `delete_on_close' 為 false，並且檔案是在使用者缺乏刪除存取權限的目錄中建立的，則情境管理器退出時的 @ref{12f6,,os.unlink()} 呼叫將失敗，並引發 @ref{f39,,PermissionError}。當 `delete_on_close' 為 true 時，不會發生這種情況，因為刪除存取權限是由 open 來要求的，如果未授予存取權限則會立即失敗。

（僅）在 POSIX 上，因使用 SIGKILL 而被終止的行程無法自動刪除它建立的任何 NamedTemporaryFiles。

引發一個附帶引數 @code{fullpath} 的 @code{tempfile.mkstemp} @ref{1b70,,稽核事件}。


在 3.8 版的變更: 新增 `errors' 參數。



在 3.12 版的變更: 新增 `delete_on_close' 參數。

@end deffn

@geindex SpooledTemporaryFile (tempfile 中的類別)
@anchor{library/tempfile tempfile SpooledTemporaryFile}@anchor{89b}
@deffn {類別} tempfile.SpooledTemporaryFile (max_size=0, mode='w+b', buffering=-1, encoding=None, newline=None, suffix=None, prefix=None, dir=None, *, errors=None)

此類別執行的操作與 @ref{2b7b,,TemporaryFile()} 完全相同，但會將資料排存 (spool) 於在記憶體中，直到檔案大小超過 `max_size'，或檔案的 @ref{2b7e,,fileno()} 方法被呼叫為止，此時資料會被寫入磁碟，並且之後的操作與 @ref{2b7b,,TemporaryFile()} 相同。

@geindex rollover() (tempfile.SpooledTemporaryFile 的方法)
@anchor{library/tempfile tempfile SpooledTemporaryFile rollover}@anchor{2b7f}
@deffn {方法} rollover ()

生成的檔案物件有一個額外的方法 @code{rollover()}，忽略檔案大小並立即將其寫入磁碟。
@end deffn

回傳的物件是 file-like object，它的 @code{_file} 屬性是 @ref{109f,,io.BytesIO} 或 @ref{9b7,,io.TextIOWrapper} 物件（取決於指定的是二進位制模式還是文字模式）或真實的檔案物件（取決於是否已呼叫 @ref{2b7f,,rollover()}）。file-like object 可以像普通檔案一樣在 @ref{186,,with} 陳述式中使用。


在 3.3 版的變更: 現在，檔案的截斷方法 (truncate method) 可接受一個 `size' 引數。



在 3.8 版的變更: 新增 `errors' 參數。



在 3.11 版的變更: 完全實作 @ref{89c,,io.BufferedIOBase} 和 @ref{89d,,io.TextIOBase} 抽象基底類別（取決於指定的是二進位還是文本 `mode'）。

@end deffn

@geindex TemporaryDirectory (tempfile 中的類別)
@anchor{library/tempfile tempfile TemporaryDirectory}@anchor{1435}
@deffn {類別} tempfile.TemporaryDirectory (suffix=None, prefix=None, dir=None, ignore_cleanup_errors=False, *, delete=True)

此類別會使用與 @ref{528,,mkdtemp()} 相同安全規則來建立一個臨時目錄。回傳物件可當作@ref{1e1,,情境管理器}使用（參見@ref{2b7d,,範例}）。在完成情境或銷毀臨時目錄物件時，新建立的臨時目錄及其所有內容會從檔案系統中被移除。

@geindex name (tempfile.TemporaryDirectory 的屬性)
@anchor{library/tempfile tempfile TemporaryDirectory name}@anchor{2b80}
@deffn {屬性} name

可以從回傳物件的 @code{name} 屬性中找到的臨時目錄名稱。當回傳的物件用作@ref{1e1,,情境管理器}時，這個 @code{name} 會作為 @ref{186,,with} 陳述句中 @code{as} 子句的目標（如果有 as 的話）。
@end deffn

@geindex cleanup() (tempfile.TemporaryDirectory 的方法)
@anchor{library/tempfile tempfile TemporaryDirectory cleanup}@anchor{2b81}
@deffn {方法} cleanup ()

此目錄可透過呼叫 @code{cleanup()} 方法來顯式地清理。如果 `ignore_cleanup_errors' 為 true，則在顯式或隱式清理期間出現的未處理例外（例如在 Windows 上移除開啟的檔案而引發的 @ref{f39,,PermissionError}）將被忽略，並且剩餘的可移除條目會「儘可能」地被刪除。在其他情況下，錯誤將在任何情境清理發生時被引發（@code{cleanup()} 呼叫、退出情境管理器、物件被作為垃圾回收或直譯器關閉等）。
@end deffn

`delete' 參數可以停用在退出情境時對目錄樹的清理，雖然停用情境管理器在退出情境時所採取的操作似乎不常見，但它在除錯期間或當你需要基於其他邏輯的清理行為時會非常有用。

引發一個附帶引數 @code{fullpath} 的 @code{tempfile.mkdtemp} @ref{1b70,,稽核事件}。


在 3.2 版被加入.



在 3.10 版的變更: 新增 `ignore_cleanup_errors' 參數。



在 3.12 版的變更: 新增 `delete' 參數。

@end deffn

@geindex mkstemp() (於 tempfile 模組中)
@anchor{library/tempfile tempfile mkstemp}@anchor{2b7c}
@deffn {函式} tempfile.mkstemp (suffix=None, prefix=None, dir=None, text=False)

盡可能以最安全的方式建立一個臨時檔案。假設所在平臺正確實作了 @ref{f8d,,os.open()} 的 @ref{2b82,,os.O_EXCL} 旗標，則建立檔案時不會有 race condition（競爭條件）的情況。該檔案只能由建立者讀寫，如果所在平臺用 permission bit（許可權位元）來表示檔案是否可執行，則沒有人有執行權。檔案描述器不會被子行程繼承。

與 @ref{2b7b,,TemporaryFile()} 不同，@ref{2b7c,,mkstemp()} 使用者用完臨時檔案後需要自行將其刪除。

如果 `suffix' 不是 @code{None} 則檔名將以該後綴結尾，若為 @code{None} 則沒有後綴。@ref{2b7c,,mkstemp()} 不會在檔名和後綴之間加點 (dot)，如果需要加一個點號，請將其放在 `suffix' 的開頭。

如果 `prefix' 不是 @code{None} 則檔名將以該字首開頭，若為 @code{None} 則使用預設前綴。預設前綴是 @ref{2b83,,gettempprefix()} 或 @ref{2b84,,gettempprefixb()} 函式的回傳值（自動呼叫合適的函式）。

如果 `dir' 不為 @code{None} 則在指定的目錄建立檔案，若為 @code{None} 則使用預設目錄。預設目錄是從一個相依於平臺的列表中選擇出來的，但是使用者可以設定 `TMPDIR'、`TEMP' 或 `TMP' 環境變數來設定目錄的位置。因此，不能保證生成的臨時檔案路徑是使用者友善的，比如透過 @code{os.popen()} 將路徑傳遞給外部命令時仍需要加引號 (quoting)。

如果 `suffix'、`prefix' 和 `dir' 中的任何一個不是 @code{None}，就要保證它們資料型別相同。如果它們是位元組串，則回傳名稱的型別就是位元組串而非字串。如果不想遵循預設行為但又想要回傳值是位元組串型別，請傳入 @code{suffix=b'@w{'}}。

如果指定了 `text' 且為真值，檔案會以文字模式開啟。否則，檔案（預設）以二進位制模式開啟。

@ref{2b7c,,mkstemp()} 回傳一個 tuple，tuple 中，第一個元素是一個作業系統層級 (OS-level) 控制代碼，指向一個開啟的檔案（如同 @ref{f8d,,os.open()} 的回傳值），第二元素是該檔案的絕對路徑。

引發一個附帶引數 @code{fullpath} 的 @code{tempfile.mkstemp} @ref{1b70,,稽核事件}。


在 3.5 版的變更: 現在，`suffix'、`prefix' 和 `dir' 可以以位元組串型別按順序提供，以獲得位元組串型別的回傳值。在之前只允許使用字串。`suffix' 和 `prefix' 現在可以接受 @code{None}，並且預設為 @code{None} 以使用合適的預設值。



在 3.6 版的變更: `dir' 參數現在可接受一個類路徑物件 (@ref{59b,,path-like object})。

@end deffn

@geindex mkdtemp() (於 tempfile 模組中)
@anchor{library/tempfile tempfile mkdtemp}@anchor{528}
@deffn {函式} tempfile.mkdtemp (suffix=None, prefix=None, dir=None)

盡可能以最安全的方式建立一個臨時目錄，建立該目錄時不會有 race condition 的情況，該目錄只能由建立者讀取、寫入和搜尋。

@ref{528,,mkdtemp()} 的使用者用完臨時目錄後需要自行將其刪除。

引數 `prefix'、`suffix' 和 `dir' 的含義與它們在 @ref{2b7c,,mkstemp()} 中相同。

@ref{528,,mkdtemp()} 回傳新目錄的絕對路徑名稱。

引發一個附帶引數 @code{fullpath} 的 @code{tempfile.mkdtemp} @ref{1b70,,稽核事件}。


在 3.5 版的變更: 現在，`suffix'、`prefix' 和 `dir' 可以以位元組串型別按順序提供，以獲得位元組串型別的回傳值。在之前只允許使用字串。`suffix' 和 `prefix' 現在可以接受 @code{None}，並且預設為 @code{None} 以使用合適的預設值。



在 3.6 版的變更: `dir' 參數現在可接受一個類路徑物件 (@ref{59b,,path-like object})。



在 3.12 版的變更: @ref{528,,mkdtemp()} 現在都會回傳絕對路徑，即使 `dir' 是相對路徑。

@end deffn

@geindex gettempdir() (於 tempfile 模組中)
@anchor{library/tempfile tempfile gettempdir}@anchor{1b8f}
@deffn {函式} tempfile.gettempdir ()

回傳儲存臨時檔案的目錄名稱。這設定了此 module 所有函式 `dir' 引數的預設值。

Python 搜尋標準目錄列表來找到呼叫者可以在其中建立檔案的目錄。這個列表是：


@enumerate 

@item 
@geindex TMPDIR
@geindex 環境變數; TMPDIR
@code{TMPDIR} 環境變數指向的目錄。

@item 
@geindex TEMP
@geindex 環境變數; TEMP
@code{TEMP} 環境變數指向的目錄。

@item 
@geindex TMP
@geindex 環境變數; TMP
@code{TMP} 環境變數指向的目錄。

@item 
與平臺相關的位置：


@itemize *

@item 
在 Windows 上，目錄依次為 @code{C:\TEMP}、@code{C:\TMP}、@code{\TEMP} 和 @code{\TMP}。

@item 
在所有其他平臺上，目錄依次為 @code{/tmp}、@code{/var/tmp} 和 @code{/usr/tmp}。
@end itemize

@item 
不得已時，使用目前工作目錄。
@end enumerate

搜尋的結果會被 cache（快取）起來，請見下面 @ref{1b8e,,tempdir} 的描述。


在 3.10 版的變更: 回傳一個字串。在之前的版本中它會回傳任意 @ref{1b8e,,tempdir} 的值而不考慮它的型別，只要它不為 @code{None}。

@end deffn

@geindex gettempdirb() (於 tempfile 模組中)
@anchor{library/tempfile tempfile gettempdirb}@anchor{1b90}
@deffn {函式} tempfile.gettempdirb ()

與 @ref{1b8f,,gettempdir()} 相同，但回傳值為位元組串型別。


在 3.5 版被加入.

@end deffn

@geindex gettempprefix() (於 tempfile 模組中)
@anchor{library/tempfile tempfile gettempprefix}@anchor{2b83}
@deffn {函式} tempfile.gettempprefix ()

回傳用於建立臨時檔案的檔名前綴，它不包含目錄部分。
@end deffn

@geindex gettempprefixb() (於 tempfile 模組中)
@anchor{library/tempfile tempfile gettempprefixb}@anchor{2b84}
@deffn {函式} tempfile.gettempprefixb ()

與 @ref{2b83,,gettempprefix()} 相同，但回傳值為位元組串型別。


在 3.5 版被加入.

@end deffn

此 module 使用一個全域性變數來儲存由 @ref{1b8f,,gettempdir()} 回傳的臨時檔案使用的目錄路徑。它可被直接設定以覆蓋選擇過程，但不建議這樣做。此 module 中的所有函式都接受一個 `dir' 引數，它可被用於指定目錄。這是個推薦的做法，它不會透過改變全域性 API 行為而對其他不預期此行為的程式造成影響。

@geindex tempdir (於 tempfile 模組中)
@anchor{library/tempfile tempfile tempdir}@anchor{1b8e}
@deffn {資料} tempfile.tempdir

當被設為 @code{None} 以外的值時，此變數會為此 module 所定義函式的引數 `dir' 定義預設值，包括確定其型別為位元組串還是字串。它不可以為 @ref{59b,,path-like object}。

如果在呼叫除 @ref{2b83,,gettempprefix()} 外的上述任何函式時 @code{tempdir} 為 @code{None} (預設值) 則它會按照 @ref{1b8f,,gettempdir()} 中所描述的演算法來初始化。

@cartouche
@quotation 備註 
請注意如果你將 @code{tempdir} 設為位元組串值，會有一個麻煩的副作用：@ref{2b7c,,mkstemp()} 和 @ref{528,,mkdtemp()} 的全域性預設回傳型別會在沒有提供明顯字串型別的 @code{prefix}、@code{suffix} 或 @code{dir} 時被改為位元組串。請不要編寫預期此行為或依賴於此行為的程式。這個奇怪的行為是為了維持與以往實作版本的相容性。
@end quotation
@end cartouche
@end deffn

@menu
* 範例: 範例<7>. 
* 已棄用的函式和變數:: 

@end menu

@node 範例<7>,已棄用的函式和變數,,tempfile --- 生成臨時檔案和目錄
@anchor{library/tempfile examples}@anchor{2b85}@anchor{library/tempfile tempfile-examples}@anchor{2b7d}
@subsubsection 範例


以下是 @ref{e6,,tempfile} module 的一些常見用法範例：

@example
>>> import tempfile

# 建立一個臨時檔案並寫入一些資料
>>> fp = tempfile.TemporaryFile()
>>> fp.write(b'Hello world!')
# read data from file
>>> fp.seek(0)
>>> fp.read()
b'Hello world!'
# 關閉檔案，檔案會被刪除
>>> fp.close()

# 使用情境管理器建立臨時檔案
>>> with tempfile.TemporaryFile() as fp:
...     fp.write(b'Hello world!')
...     fp.seek(0)
...     fp.read()
b'Hello world!'
>>>
# 檔案現在已關閉並刪除

# 使用情境管理器建立臨時檔案
# 關閉檔案，使用名稱再次開啟檔案
>>> with tempfile.NamedTemporaryFile(delete_on_close=False) as fp:
...     fp.write(b'Hello world!')
...     fp.close()
... # 檔案已被關閉，但未被刪除
... # 透過其名稱再次開啟檔案
...     with open(fp.name, mode='rb') as f:
...         f.read()
b'Hello world!'
>>>
# 現在檔案已被刪除

# 使用情境管理器建立臨時目錄
>>> with tempfile.TemporaryDirectory() as tmpdirname:
...     print('created temporary directory', tmpdirname)
>>>
# 目錄及其內容已被刪除
@end example

@node 已棄用的函式和變數,,範例<7>,tempfile --- 生成臨時檔案和目錄
@anchor{library/tempfile deprecated-functions-and-variables}@anchor{2b86}@anchor{library/tempfile tempfile-mktemp-deprecated}@anchor{2b87}
@subsubsection 已棄用的函式和變數


在過去，建立臨時檔案首先使用 @ref{1b44,,mktemp()} 函式生成一個檔名，然後使用該檔名建立檔案。不幸的是這並不安全的，因為在呼叫 @ref{1b44,,mktemp()} 與隨後嘗試建立檔案之間的時間裡，其他程式可能會使用該名稱建立檔案。解決方案是將兩個步驟結合起來，並立即建立檔案。這個方案目前被 @ref{2b7c,,mkstemp()} 和上述其他函式所採用。

@geindex mktemp() (於 tempfile 模組中)
@anchor{library/tempfile tempfile mktemp}@anchor{1b44}
@deffn {函式} tempfile.mktemp (suffix='@w{'}, prefix='tmp', dir=None)


在 2.3 版之後被棄用: 使用 @ref{2b7c,,mkstemp()} 代替。


回傳一個在呼叫本方法時不存在檔案的絕對路徑。引數 `prefix'、`suffix' 和 `dir' 與 @ref{2b7c,,mkstemp()} 中所用的類似，除了在於不支援位元組串型別的檔名且不支援 @code{suffix=None} 和 @code{prefix=None}。

@cartouche
@quotation 警告 
使用此功能可能會在程式中引入安全漏洞。當你開始使用本方法回傳的檔案執行任何操作時，可能有人已經捷足先登了。@ref{1b44,,mktemp()} 的功能可以很輕鬆地用帶有 @code{delete=False} 參數的 @ref{6e6,,NamedTemporaryFile()} 代替：

@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 風格的路徑名稱模式擴展,fnmatch --- Unix 檔案名稱模式比對,tempfile --- 生成臨時檔案和目錄,檔案與目錄存取
@anchor{library/glob doc}@anchor{2b88}@anchor{library/glob glob-unix-style-pathname-pattern-expansion}@anchor{2b89}@anchor{library/glob module-glob}@anchor{68}@anchor{library/glob translation-repo}@anchor{2b8a}
@subsection @code{glob} --- Unix 風格的路徑名稱模式擴展


@geindex module; glob

`原始碼：'Lib/glob.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/glob.py}

@geindex filenames（檔案名稱）;pathname expansion（路徑名稱展開）


__________________________________________________________________


@geindex * （星號）;於 glob 風格的萬用字元中
@geindex ? （問號）;於 glob 風格的萬用字元中
@geindex [] （方括號）;於 glob 風格的萬用字元中
@geindex ! （驚嘆號）;於 glob 風格的萬用字元中
@geindex - （減號）;於 glob 風格的萬用字元中
@geindex . （點）;於 glob 風格的萬用字元中

@code{glob} 模組使用類似於 Unix shell 的模式匹配規則來尋找路徑名稱。不會進行波浪號擴展 (tilde expansion) ，但 @code{*}、@code{?} 和使用 @code{[]} 表達的字元範圍將會被正確匹配。這是透過結合使用 @ref{c4b,,os.scandir()} 和 @ref{1b56,,fnmatch.fnmatch()} 函式來完成的，而沒有實際呼叫 subshell。

@cartouche
@quotation 備註 
路徑名稱不會以特定順序回傳。如果你需要特定的順序，請對結果進行排序。
@end quotation
@end cartouche

以點 (@code{.}) 開頭的檔案只能與同樣以點開頭的模式匹配，這與 @ref{1b56,,fnmatch.fnmatch()} 或 @ref{532,,pathlib.Path.glob()} 不同。對於波浪號和 shell 變數擴展，請使用 @ref{c00,,os.path.expanduser()} 和 @ref{15d0,,os.path.expandvars()}。

對於文本 (literal) 匹配，將元字元 (meta-character) 括在方括號中。例如，@code{'[?]'} 會匹配 @code{'?'} 字元。

@code{glob} 模組定義了以下函式：

@geindex glob() (於 glob 模組中)
@anchor{library/glob glob glob}@anchor{59a}
@deffn {函式} glob.glob (pathname, *, root_dir=None, dir_fd=None, recursive=False, include_hidden=False)

回傳與 `pathname' 匹配、可能為空的路徑名稱 list，它必須是包含路徑規範的字串。 `pathname' 可以是絕對的（如 @code{/usr/src/Python-1.5/Makefile}）或相對的（如 @code{../../Tools/*/*.gif}），並且可以包含 shell 樣式的通用字元 (wildcard)。已損壞的符號連接也會（如同在 shell）被包含在結果中。結果是否排序取決於檔案系統 (file system)。如果在呼叫此函式期間刪除或新增滿足條件的檔案，則結果不一定會包含該檔案的路徑名稱。

如果 `root_dir' 不是 @code{None}，它應該是一個指定搜尋根目錄的 @ref{59b,,path-like object}。它在呼叫它之前更改目前目錄的影響與 @code{glob()} 相同。如果 `pathname' 是相對的，結果將包含相對於 `root_dir' 的路徑。

此函式可以支援以 `dir_fd' 參數使用@ref{12eb,,相對目錄描述器的路徑}。

@geindex **;於 glob 風格的萬用字元中

如果 `recursive' 為真，模式 "@code{**}" 將匹配任何檔案、零個或多個目錄、子目錄和目錄的符號連結。如果模式後面有 @ref{873,,os.sep} 或 @ref{874,,os.altsep} 那麼檔案將不會被匹配。

如果 `include_hidden' 為真，"@code{**}" 模式將匹配被隱藏的目錄。

引發一個附帶引數 @code{pathname}、@code{recursive} 的@ref{1b70,,稽核事件} @code{glob.glob}。

引發一個附帶引數 @code{pathname}、@code{recursive}、@code{root_dir}、@code{dir_fd} 的@ref{1b70,,稽核事件} @code{glob.glob/2}。

@cartouche
@quotation 備註 
在大型目錄樹中使用 "@code{**}" 模式可能會消耗過多的時間。
@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


在 3.5 版的變更: 支援以 "@code{**}" 使用遞迴 glob。



在 3.10 版的變更: 新增 `root_dir' 與 `dir_fd' 參數。



在 3.11 版的變更: 新增 `include_hidden' 參數。

@end deffn

@geindex iglob() (於 glob 模組中)
@anchor{library/glob glob iglob}@anchor{a01}
@deffn {函式} glob.iglob (pathname, *, root_dir=None, dir_fd=None, recursive=False, include_hidden=False)

回傳一個會產生與 @ref{68,,glob()} 相同的值的 @ref{4c3,,iterator} ，而不是同時儲存全部的值。

引發一個附帶引數 @code{pathname}、@code{recursive} 的@ref{1b70,,稽核事件} @code{glob.glob}。

引發一個附帶引數 @code{pathname}、@code{recursive}、@code{root_dir}、@code{dir_fd} 的@ref{1b70,,稽核事件} @code{glob.glob/2}。

@cartouche
@quotation 備註 
This function may return duplicate path names if `pathname'
contains multiple "@code{**}" patterns and `recursive' is true.
@end quotation
@end cartouche


在 3.5 版的變更: 支援以 "@code{**}" 使用遞迴 glob。



在 3.10 版的變更: 新增 `root_dir' 與 `dir_fd' 參數。



在 3.11 版的變更: 新增 `include_hidden' 參數。

@end deffn

@geindex escape() (於 glob 模組中)
@anchor{library/glob glob escape}@anchor{1140}
@deffn {函式} glob.escape (pathname)

跳脫 (escape) 所有特殊字元（@code{'?'}、@code{'*'} 和 @code{'['}）。如果你想匹配其中可能包含特殊字元的任意文本字串，這將會很有用。驅動器 (drive)/UNC 共享點 (sharepoints) 中的特殊字元不會被跳脫，例如在 Windows 上，@code{escape('//?/c:/Quo vadis?.txt')} 會回傳 @code{'//?/c:/Quo vadis[?].txt'}。


在 3.4 版被加入.

@end deffn

@geindex translate() (於 glob 模組中)
@anchor{library/glob glob translate}@anchor{4f6}
@deffn {函式} glob.translate (pathname, *, recursive=False, include_hidden=False, seps=None)

Convert the given path specification to a regular expression for use with
@ref{142e,,re.match()}. The path specification can contain shell-style wildcards.

舉例來說：

@example
>>> import glob, re
>>>
>>> regex = glob.translate('**/*.txt', recursive=True, include_hidden=True)
>>> regex
'(?s:(?:.+/)?[^/]*\\.txt)\\z'
>>> reobj = re.compile(regex)
>>> reobj.match('foo/bar/baz.txt')
<re.Match object; span=(0, 15), match='foo/bar/baz.txt'>
@end example

Path separators and segments are meaningful to this function, unlike
@ref{17cd,,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{873,,os.sep} and @ref{874,,altsep} (if available) are used.


@subsubheading 也參考


@ref{530,,pathlib.PurePath.full_match()} and @ref{532,,pathlib.Path.glob()}
methods, which call this function to implement pattern matching and
globbing.



在 3.13 版被加入.

@end deffn

@menu
* 範例: 範例<8>. 

@end menu

@node 範例<8>,,,glob --- Unix 風格的路徑名稱模式擴展
@anchor{library/glob examples}@anchor{2b8b}
@subsubsection 範例


例如，在一個包含以下檔案的目錄：@code{1.gif}、@code{2.txt}、@code{card.gif}，和一個僅包含 @code{3.txt} 檔案的子目錄 @code{sub}，@ref{68,,glob()} 將產生以下結果。請注意路徑的任何前導部分是如何保留的。

@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

如果目錄包含以 @code{.} 開頭的檔案，則預設情況下不會去匹配到它們。例如，一個包含 @code{card.gif} 和 @code{.card.gif} 的目錄：

@example
>>> import glob
>>> glob.glob('*.gif')
['card.gif']
>>> glob.glob('.c*')
['.card.gif']
@end example


@subsubheading 也參考


@ref{60,,fnmatch} 模組提供了 shell 風格檔案名（不是路徑）的擴展



@subsubheading 也參考


@ref{a8,,pathlib} 模組提供高階路徑物件。


@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 檔案名稱模式比對,linecache --- 隨機存取文字列,glob --- Unix 風格的路徑名稱模式擴展,檔案與目錄存取
@anchor{library/fnmatch doc}@anchor{2b8c}@anchor{library/fnmatch fnmatch-unix-filename-pattern-matching}@anchor{2b8d}@anchor{library/fnmatch module-fnmatch}@anchor{60}@anchor{library/fnmatch translation-repo}@anchor{2b8e}
@subsection @code{fnmatch} --- Unix 檔案名稱模式比對


@geindex module; fnmatch

`原始碼：'Lib/fnmatch.py@footnote{https://github.com/python/cpython/tree/3.14/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{be,,re} module).  The
special characters used in shell-style wildcards are:

@geindex * （星號）;於 glob 風格的萬用字元中
@geindex ? （問號）;於 glob 風格的萬用字元中
@geindex [] （方括號）;於 glob 風格的萬用字元中
@geindex ! （驚嘆號）;於 glob 風格的萬用字元中
@geindex - （減號）;於 glob 風格的萬用字元中


@multitable {xxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Pattern

@tab

含義

@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{68,,glob} for pathname expansion (@ref{68,,glob} uses
@ref{1b58,,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{169,,str} or @code{ISO-8859-1} encoded @ref{192,,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{bd9,,functools.lru_cache()} with a `maxsize' of 32768
is used to cache the (typed) compiled regex patterns in the following
functions: @ref{60,,fnmatch()}, @ref{1b57,,fnmatchcase()}, @ref{1b58,,filter()}, @ref{211,,filterfalse()}.

@geindex fnmatch() (於 fnmatch 模組中)
@anchor{library/fnmatch fnmatch fnmatch}@anchor{1b56}
@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{2b08,,os.path.normcase()}. @ref{1b57,,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{1b57}
@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{2b08,,os.path.normcase()}.
@end deffn

@geindex filter() (於 fnmatch 模組中)
@anchor{library/fnmatch fnmatch filter}@anchor{1b58}
@deffn {函式} fnmatch.filter (names, pat)

Construct a list from those elements of the @ref{1428,,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{211}
@deffn {函式} fnmatch.filterfalse (names, pat)

Construct a list from those elements of the @ref{1428,,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.


在 3.14 版被加入.

@end deffn

@geindex translate() (於 fnmatch 模組中)
@anchor{library/fnmatch fnmatch translate}@anchor{17cd}
@deffn {函式} fnmatch.translate (pat)

Return the shell-style pattern `pat' converted to a regular expression for
using with @ref{142e,,re.match()}. The pattern is expected to be a @ref{169,,str}.

範例：

@example
>>> import fnmatch, re
>>>
>>> regex = fnmatch.translate('*.txt')
>>> regex
'(?s:.*\\.txt)\\z'
>>> reobj = re.compile(regex)
>>> reobj.match('foobar.txt')
<re.Match object; span=(0, 10), match='foobar.txt'>
@end example
@end deffn


@subsubheading 也參考



@table @asis

@item @ref{68,,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 --- 隨機存取文字列,shutil — 高階檔案操作,fnmatch --- Unix 檔案名稱模式比對,檔案與目錄存取
@anchor{library/linecache doc}@anchor{2b8f}@anchor{library/linecache linecache-random-access-to-text-lines}@anchor{2b90}@anchor{library/linecache module-linecache}@anchor{89}@anchor{library/linecache translation-repo}@anchor{2b91}
@subsection @code{linecache} --- 隨機存取文字列


@geindex module; linecache

`原始碼：'Lib/linecache.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/linecache.py}


__________________________________________________________________


@ref{89,,linecache} 模組允許從 Python 原始碼檔案中取得任何一行。當嘗試在程式內部進行最佳化，會使用快取，這是從單一檔案讀取許多行的常見情況。 這被 @ref{104,,traceback} 模組用來擷取來自原始碼檔案的行，以包含在格式化的 traceback 中。

@ref{2b92,,tokenize.open()} 函式用來開啟檔案。這個函式使用 @ref{1750,,tokenize.detect_encoding()} 來取得檔案的編碼；在沒有編碼標記的情況下，檔案編碼預設為 UTF-8。

@ref{89,,linecache} 模組定義了下列函式：

@geindex getline() (於 linecache 模組中)
@anchor{library/linecache linecache getline}@anchor{240}
@deffn {函式} linecache.getline (filename, lineno, module_globals=None)

從名為 `filename' 的檔案中取得 `lineno' 行。這個函式不會產生例外 --- 它會在出錯時回傳 @code{'@w{'}} （找到的行會包含終止換行字元）。

@geindex module（模組）;search（搜尋）;path（路徑）

If `filename' indicates a frozen module (starting with @code{'<frozen '}), the function
will attepmt to get the real file name from @code{module_globals['__file__']} if
`module_globals' is not @code{None}.

如果找不到名為 `filename' 的檔案，函式會先檢查 `module_globals' 中是否有 
@geindex Python Enhancement Proposals; PEP 302
PEP 302@footnote{https://peps.python.org/pep-0302/} @cite{__loader__} 載入器。如果有這樣一個載入器，而且它定義了一個 @code{get_source} 方法，這之後它就會決定原始碼行（如果 @code{get_source()} 回傳 @code{None}，那麼就會回傳 @code{'@w{'}}）。最後，如果 `filename' 是相對的檔案名稱，則會相對於模組搜尋路徑 @code{sys.path} 中的項目進行搜尋。


在 3.14 版的變更: Support `filename' of frozen modules.

@end deffn

@geindex clearcache() (於 linecache 模組中)
@anchor{library/linecache linecache clearcache}@anchor{2b93}
@deffn {函式} linecache.clearcache ()

清除快取。如果你不再需要先前使用 @ref{240,,getline()} 讀取的檔案行數，請使用此函式。
@end deffn

@geindex checkcache() (於 linecache 模組中)
@anchor{library/linecache linecache checkcache}@anchor{1858}
@deffn {函式} linecache.checkcache (filename=None)

檢查快取是否有效。如果快取中的檔案可能已在磁碟上變更，而你需要更新的版本，請使用此功能。 如果省略 `filename'，則會檢查快取中的所有項目。
@end deffn

@geindex lazycache() (於 linecache 模組中)
@anchor{library/linecache linecache lazycache}@anchor{101f}
@deffn {函式} linecache.lazycache (filename, module_globals)

即使 `module_globals' 在稍後的呼叫中是 @code{None} ，也可以擷取非檔案型模組的足夠細節，以允許稍後透過 @ref{240,,getline()} 取得其行。這可以避免在真正需要某一行之前進行 I/O 操作，而不必無限期地帶著模組的全域變數。


在 3.5 版被加入.

@end deffn

範例：

@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 — 高階檔案操作,,linecache --- 隨機存取文字列,檔案與目錄存取
@anchor{library/shutil doc}@anchor{2b94}@anchor{library/shutil module-shutil}@anchor{ca}@anchor{library/shutil shutil-high-level-file-operations}@anchor{2b95}@anchor{library/shutil translation-repo}@anchor{2b96}
@subsection @code{shutil} — 高階檔案操作


@geindex module; shutil

@c partly based on the docstrings

`原始碼：'Lib/shutil.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/shutil.py}

@geindex file（檔案）;copying（複製）
@geindex copying files（複製檔案）


__________________________________________________________________


The @ref{ca,,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{c46,,shutil.copy()},
@ref{c47,,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
* 目錄和檔案操作:: 
* Archiving operations:: 
* Querying the size of the output terminal:: 

@end menu

@node 目錄和檔案操作,Archiving operations,,shutil — 高階檔案操作
@anchor{library/shutil directory-and-files-operations}@anchor{2b97}@anchor{library/shutil file-operations}@anchor{2b98}
@subsubsection 目錄和檔案操作


@geindex copyfileobj() (於 shutil 模組中)
@anchor{library/shutil shutil copyfileobj}@anchor{c49}
@deffn {函式} shutil.copyfileobj (fsrc, fdst[, length])

Copy the contents of the @ref{13c4,,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.

@ref{c49,,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{2b99,,flush()} or
@ref{501,,close()} on the file-like object before attempting to read
the destination file.
@end deffn

@geindex copyfile() (於 shutil 模組中)
@anchor{library/shutil shutil copyfile}@anchor{c45}
@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{59b,,path-like objects} or path names given as strings.

`dst' must be the complete target file name; look at @ref{c46,,copy()}
for a copy that accepts a target directory path.  If `src' and `dst'
specify the same file, @ref{1199,,SameFileError} is raised.

The destination location must be writable; otherwise, an @ref{2c0,,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.

引發一個附帶引數 @code{src}、@code{dst} 的@ref{1b70,,稽核事件} @code{shutil.copyfile}。


在 3.3 版的變更: @ref{124e,,IOError} used to be raised instead of @ref{2c0,,OSError}.
Added `follow_symlinks' argument.
Now returns `dst'.



在 3.4 版的變更: Raise @ref{1199,,SameFileError} instead of @ref{1198,,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{c4a,,Platform-dependent efficient copy operations} section.

@end deffn

@geindex SpecialFileError
@anchor{library/shutil shutil SpecialFileError}@anchor{151c}
@deffn {例外} shutil.SpecialFileError

This exception is raised when @ref{c45,,copyfile()} or @ref{c15,,copytree()} attempt
to copy a named pipe.


在 2.7 版被加入.

@end deffn

@geindex SameFileError
@anchor{library/shutil shutil SameFileError}@anchor{1199}
@deffn {例外} shutil.SameFileError

This exception is raised if source and destination in @ref{c45,,copyfile()}
are the same file.


在 3.4 版被加入.

@end deffn

@geindex copymode() (於 shutil 模組中)
@anchor{library/shutil shutil copymode}@anchor{1974}
@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{59b,,path-like objects} or path names
given as strings.
If `follow_symlinks' is false, and both `src' and `dst' are symbolic links,
@ref{1974,,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{132f,,copystat()} for more information.  If
@ref{1974,,copymode()} cannot modify symbolic links on the local platform, and it
is asked to do so, it will do nothing and return.

引發一個附帶引數 @code{src}、@code{dst} 的@ref{1b70,,稽核事件} @code{shutil.copymode}。


在 3.3 版的變更: 新增 `follow_symlinks' 引數。

@end deffn

@geindex copystat() (於 shutil 模組中)
@anchor{library/shutil shutil copystat}@anchor{132f}
@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, @ref{132f,,copystat()} also copies the
"extended attributes" where possible.  The file contents, owner, and
group are unaffected.  `src' and `dst' are @ref{59b,,path-like objects} or path
names given as strings.

If `follow_symlinks' is false, and `src' and `dst' both
refer to symbolic links, @ref{132f,,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}, @ref{132f,,copystat()} can modify the permission
bits of a symbolic link.

@item 
If @code{os.utime in os.supports_follow_symlinks} is
@code{True}, @ref{132f,,copystat()} can modify the last access
and modification times of a symbolic link.

@item 
If @code{os.chflags in os.supports_follow_symlinks} is
@code{True}, @ref{132f,,copystat()} can modify the flags of
a symbolic link.  (@code{os.chflags} is not available on
all platforms.)
@end itemize

On platforms where some or all of this functionality
is unavailable, when asked to modify a symbolic link,
@ref{132f,,copystat()} will copy everything it can.
@ref{132f,,copystat()} never returns failure.

更多資訊請見 @ref{12f9,,os.supports_follow_symlinks}。
@end quotation
@end cartouche

引發一個附帶引數 @code{src}、@code{dst} 的@ref{1b70,,稽核事件} @code{shutil.copystat}。


在 3.3 版的變更: Added `follow_symlinks' argument and support for Linux extended attributes.

@end deffn

@geindex copy() (於 shutil 模組中)
@anchor{library/shutil shutil copy}@anchor{c46}
@deffn {函式} shutil.copy (src, dst, *, follow_symlinks=True)

Copies the file `src' to the file or directory `dst'.  `src' and `dst'
should be @ref{59b,,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{c46,,copy()} copies the file data and the file's permission
mode (see @ref{524,,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{c47,,copy2()} instead.

引發一個附帶引數 @code{src}、@code{dst} 的@ref{1b70,,稽核事件} @code{shutil.copyfile}。

引發一個附帶引數 @code{src}、@code{dst} 的@ref{1b70,,稽核事件} @code{shutil.copymode}。


在 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{c4a,,Platform-dependent efficient copy operations} section.

@end deffn

@geindex copy2() (於 shutil 模組中)
@anchor{library/shutil shutil copy2}@anchor{c47}
@deffn {函式} shutil.copy2 (src, dst, *, follow_symlinks=True)

Identical to @ref{c46,,copy()} except that @ref{c47,,copy2()}
also attempts to preserve file metadata.

When `follow_symlinks' is false, and `src' is a symbolic
link, @ref{c47,,copy2()} attempts to copy all metadata from the
`src' symbolic link to the newly created `dst' symbolic link.
However, this functionality is not available on all platforms.
On platforms where some or all of this functionality is
unavailable, @ref{c47,,copy2()} will preserve all the metadata
it can; @ref{c47,,copy2()} never raises an exception because it
cannot preserve file metadata.

@ref{c47,,copy2()} uses @ref{132f,,copystat()} to copy the file metadata.
Please see @ref{132f,,copystat()} for more information
about platform support for modifying symbolic link metadata.

引發一個附帶引數 @code{src}、@code{dst} 的@ref{1b70,,稽核事件} @code{shutil.copyfile}。

引發一個附帶引數 @code{src}、@code{dst} 的@ref{1b70,,稽核事件} @code{shutil.copystat}。


在 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{c4a,,Platform-dependent efficient copy operations} section.

@end deffn

@geindex ignore_patterns() (於 shutil 模組中)
@anchor{library/shutil shutil ignore_patterns}@anchor{2b9a}
@deffn {函式} shutil.ignore_patterns (*patterns)

This factory function creates a function that can be used as a callable for
@ref{c15,,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{c15}
@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{132f,,copystat()},
individual files are copied using @ref{c47,,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{1198,,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{12f5,,os.symlink()}.

If `ignore' is given, it must be a callable that will receive as its
arguments the directory being visited by @ref{c15,,copytree()}, and a list of its
contents, as returned by @ref{12fb,,os.listdir()}.  Since @ref{c15,,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{2b9a,,ignore_patterns()} can be used to create such a callable that
ignores names based on glob-style patterns.

If exception(s) occur, an @ref{1198,,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{c47,,copy2()} is used, but any function
that supports the same signature (like @ref{c46,,copy()}) can be used.

If `dirs_exist_ok' is false (the default) and `dst' already exists, a
@ref{121b,,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.

引發一個附帶引數 @code{src}、@code{dst} 的@ref{1b70,,稽核事件} @code{shutil.copytree}。


在 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{c4a,,Platform-dependent efficient copy operations} section.



在 3.8 版的變更: 新增 `dirs_exist_ok' 參數。

@end deffn

@geindex rmtree() (於 shutil 模組中)
@anchor{library/shutil shutil rmtree}@anchor{354}
@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{12eb,,paths relative to directory descriptors}.

@cartouche
@quotation 備註 
On platforms that support the necessary fd-based functions a symlink
attack resistant version of @ref{354,,rmtree()} is used by default.  On other
platforms, the @ref{354,,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{2b9b,,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{893,,sys.exc_info()}.


@subsubheading 也參考


@ref{2b9c,,rmtree 範例} for an example of handling the removal
of a directory tree that contains read-only files.


引發一個附帶引數 @code{path}、@code{dir_fd} 的@ref{1b70,,稽核事件} @code{shutil.rmtree}。


在 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 版的變更: 新增 `dir_fd' 參數。



在 3.12 版的變更: 新增 `onexc' 參數並棄用 `onerror'。



在 3.13 版的變更: @code{rmtree()} now ignores @ref{264,,FileNotFoundError} exceptions for all
but the top-level path.
Exceptions other than @ref{2c0,,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{2b9b}
@deffn {屬性} rmtree.avoids_symlink_attacks

Indicates whether the current platform and implementation provides a
symlink attack resistant version of @ref{354,,rmtree()}.  Currently this is
only true for platforms supporting fd-based directory access functions.


在 3.3 版被加入.

@end deffn
@end deffn

@geindex move() (於 shutil 模組中)
@anchor{library/shutil shutil move}@anchor{c48}
@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{12f2,,os.rename()} semantics.

If the destination is on the current filesystem, then @ref{12f2,,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{12f2,,os.rename()} cannot be used.  If the source is a directory,
@ref{c15,,copytree()} is called, passing it the `copy_function'. The
default `copy_function' is @ref{c47,,copy2()}.  Using @ref{c46,,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.

引發一個附帶引數 @code{src}、@code{dst} 的@ref{1b70,,稽核事件} @code{shutil.move}。


在 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 版的變更: 新增 `copy_function' 關鍵字引數。



在 3.8 版的變更: Platform-specific fast-copy syscalls may be used internally in order to
copy the file more efficiently. See
@ref{c4a,,Platform-dependent efficient copy operations} section.



在 3.9 版的變更: Accepts a @ref{59b,,path-like object} for both `src' and `dst'.

@end deffn

@geindex disk_usage() (於 shutil 模組中)
@anchor{library/shutil shutil disk_usage}@anchor{132e}
@deffn {函式} shutil.disk_usage (path)

Return disk usage statistics about the given path as a @ref{857,,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


在 3.3 版被加入.



在 3.8 版的變更: On Windows, `path' can now be a file or directory.


@ref{2006,,可用性}: Unix, Windows.
@end deffn

@geindex chown() (於 shutil 模組中)
@anchor{library/shutil shutil chown}@anchor{543}
@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{12ef,,os.chown()}, the underlying function.

引發一個附帶引數 @code{path}、@code{user}、@code{group} 的@ref{1b70,,稽核事件} @code{shutil.chown}。

@ref{2006,,可用性}: Unix.


在 3.3 版被加入.



在 3.13 版的變更: 新增 `dir_fd' 和 `follow_symlinks' 參數。

@end deffn

@geindex which() (於 shutil 模組中)
@anchor{library/shutil shutil which}@anchor{6d4}
@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{12ed,,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{1ffb,,os.pathsep}. When no `path' is specified, the
@geindex PATH
@geindex 環境變數; PATH
@code{PATH} environment variable is read from @ref{259,,os.environ},
falling back to @ref{1cad,,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")}, @ref{6d4,,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


在 3.3 版被加入.



在 3.8 版的變更: The @ref{192,,bytes} type is now accepted.  If `cmd' type is
@ref{192,,bytes}, the result type is also @ref{192,,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{1198}
@deffn {例外} shutil.Error

This exception collects exceptions that are raised during a multi-file
operation. For @ref{c15,,copytree()}, the exception argument is a list of 3-tuples
(`srcname', `dstname', `exception').
@end deffn

@menu
* Platform-dependent efficient copy operations:: 
* copytree 範例:: 
* rmtree 範例:: 

@end menu

@node Platform-dependent efficient copy operations,copytree 範例,,目錄和檔案操作
@anchor{library/shutil platform-dependent-efficient-copy-operations}@anchor{2b9d}@anchor{library/shutil shutil-platform-dependent-efficient-copy-operations}@anchor{c4a}
@subsubsection Platform-dependent efficient copy operations


Starting from Python 3.8, all functions involving a file copy
(@ref{c45,,copyfile()}, @ref{c46,,copy()}, @ref{c47,,copy2()},
@ref{c15,,copytree()}, and @ref{c48,,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).

Linux 上會使用 @ref{182a,,os.copy_file_range()} 或 @ref{cfd,,os.sendfile()}。

Solaris 上會使用 @ref{cfd,,os.sendfile()}。

On Windows @ref{c45,,shutil.copyfile()} uses a bigger default buffer size (1 MiB
instead of 64 KiB) and a @ref{165,,memoryview()}-based variant of
@ref{c49,,shutil.copyfileobj()} is used.

If the fast-copy operation fails and no data was written in the destination
file then shutil will silently fallback on using less efficient
@ref{c49,,copyfileobj()} function internally.


在 3.8 版的變更.



在 3.14 版的變更: Solaris now uses @ref{cfd,,os.sendfile()}.



在 3.14 版的變更: Copy-on-write or server-side copy may be used internally via
@ref{182a,,os.copy_file_range()} on supported Linux filesystems.


@node copytree 範例,rmtree 範例,Platform-dependent efficient copy operations,目錄和檔案操作
@anchor{library/shutil copytree-example}@anchor{2b9e}@anchor{library/shutil shutil-copytree-example}@anchor{2b9f}
@subsubsection copytree 範例


An example that uses the @ref{2b9a,,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 []   # 沒有東西被忽略

copytree(source, destination, ignore=_logpath)
@end example

@node rmtree 範例,,copytree 範例,目錄和檔案操作
@anchor{library/shutil rmtree-example}@anchor{2ba0}@anchor{library/shutil shutil-rmtree-example}@anchor{2b9c}
@subsubsection rmtree 範例


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,目錄和檔案操作,shutil — 高階檔案操作
@anchor{library/shutil archiving-operations}@anchor{1419}@anchor{library/shutil id1}@anchor{2ba1}
@subsubsection Archiving operations



在 3.2 版被加入.



在 3.5 版的變更: 新增 `xztar' 格式的支援。


High-level utilities to create and read compressed and archived files are also
provided.  They rely on the @ref{137,,zipfile} and @ref{e4,,tarfile} modules.

@geindex make_archive() (於 shutil 模組中)
@anchor{library/shutil shutil make_archive}@anchor{6d3}
@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 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{139,,zlib} module is available), "tar", "gztar" (if the
@ref{139,,zlib} module is available), "bztar" (if the @ref{14,,bz2} module is
available), "xztar" (if the @ref{8e,,lzma} module is available), or "zstdtar"
(if the @ref{23,,compression.zstd} module is available).

`root_dir' is a directory that will be the root directory of the
archive, all paths in the archive will be relative to it; for example,
we typically chdir into `root_dir' before creating the archive.

`base_dir' is the directory where we start archiving from;
i.e. `base_dir' will be the common prefix of all files and
directories in the archive.  `base_dir' must be given relative
to `root_dir'.  See @ref{2ba2,,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' 必須是與 
@geindex Python Enhancement Proposals; PEP 282
PEP 282@footnote{https://peps.python.org/pep-0282/} 相容的物件，通常是 @ref{d3e,,logging.Logger} 的實例。

`verbose' 引數未被使用且已棄用。

引發一個附帶引數 @code{base_name}、@code{format}、@code{root_dir}、@code{base_dir} 的@ref{1b70,,稽核事件} @code{shutil.make_archive}。

@cartouche
@quotation 備註 
This function is not thread-safe when custom archivers registered
with @ref{2ba3,,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.

@end deffn

@geindex get_archive_formats() (於 shutil 模組中)
@anchor{library/shutil shutil get_archive_formats}@anchor{2ba4}
@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)}.

預設情況下 @ref{ca,,shutil} 提供這些格式：


@itemize -

@item 
`zip': ZIP file (if the @ref{139,,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{139,,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{8e,,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{2ba3,,register_archive_format()}.
@end deffn

@geindex register_archive_format() (於 shutil 模組中)
@anchor{library/shutil shutil register_archive_format}@anchor{2ba3}
@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{2b09,,os.curdir}) to start archiving from.
Further arguments are passed as keyword arguments: `owner', `group',
`dry_run' and `logger' (as passed in @ref{6d3,,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{6d3,,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{2ba4,,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{2ba5}
@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{68f}
@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{2ba6,,register_unpack_format()}.  If not provided, @ref{68f,,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{2eb,,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{690,,Extraction filters} for details.)

引發一個附帶引數 @code{filename}、@code{extract_dir}、@code{format} 的@ref{1b70,,稽核事件} @code{shutil.unpack_archive}。

@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{2ba7,,Hints for further verification}
section for tar-specific details.
@end quotation
@end cartouche


在 3.7 版的變更: Accepts a @ref{59b,,path-like object} for `filename' and `extract_dir'.



在 3.12 版的變更: 新增 `filter' 引數。

@end deffn

@geindex register_unpack_format() (於 shutil 模組中)
@anchor{library/shutil shutil register_unpack_format}@anchor{2ba6}
@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{68f,,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{2ba8,,get_unpack_formats()} function.
@end deffn

@geindex unregister_unpack_format() (於 shutil 模組中)
@anchor{library/shutil shutil unregister_unpack_format}@anchor{2ba9}
@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{2ba8}
@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)}.

預設情況下 @ref{ca,,shutil} 提供這些格式：


@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{139,,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{8e,,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{2ba6,,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{2baa}@anchor{library/shutil shutil-archiving-example}@anchor{2bab}
@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{2bac}@anchor{library/shutil shutil-archiving-example-with-basedir}@anchor{2ba2}
@subsubsection Archiving example with `base_dir'


In this example, similar to the @ref{2bab,,one above},
we show how to use @ref{6d3,,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 — 高階檔案操作
@anchor{library/shutil querying-the-size-of-the-output-terminal}@anchor{2bad}
@subsubsection Querying the size of the output terminal


@geindex get_terminal_size() (於 shutil 模組中)
@anchor{library/shutil shutil get_terminal_size}@anchor{1304}
@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{2bae,,sys.__stdout__} is queried
by invoking @ref{1303,,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{2baf,,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}.


在 3.3 版被加入.



在 3.11 版的變更: The @code{fallback} values are also used if @ref{1303,,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}

作業系統介面，包括處理比 Python @ref{13c4,,檔案物件}更低階檔案的函式。

@item Module @ref{83,,io}

Python 的內建 I/O 函式庫，包含抽象類別和一些具體類別 (concrete class)，如檔案 I/O。

@item 內建函式 @ref{315,,open()}

使用 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,資料壓縮與保存,檔案與目錄存取,Python 標準函式庫 Standard Library
@anchor{library/persistence doc}@anchor{2bb0}@anchor{library/persistence data-persistence}@anchor{2bb1}@anchor{library/persistence persistence}@anchor{2bb2}@anchor{library/persistence translation-repo}@anchor{2bb3}
@section 資料持久性 (Data Persistence)


本章節所描述的模組支援將 Python 資料以持久形式儲存在磁碟上。@ref{ab,,pickle} 和 @ref{91,,marshal} 模組可以將許多 Python 資料型別轉換為位元串流，然後再從位元串流重建物件。各種與 DBM 有關的模組支援一系列基於雜湊的檔案格式，用來儲存字串對字串的對映。

本章節所描述的模組列表為：

@menu
* pickle: pickle --- Python 物件序列化. Python 物件序列化
* copyreg: copyreg --- 註冊 pickle 支援函式. 註冊 pickle 支援函式
* shelve: shelve --- Python object persistence. Python object persistence
* marshal: marshal --- 內部 Python 物件序列化. 內部 Python 物件序列化
* dbm: dbm --- Unix "databases" 的介面. Unix "databases" 的介面
* sqlite3: sqlite3 --- SQLite 資料庫的 DB-API 2 0 介面. SQLite 資料庫的 DB-API 2.0 介面

@end menu

@node pickle --- Python 物件序列化,copyreg --- 註冊 pickle 支援函式,,資料持久性 Data Persistence
@anchor{library/pickle doc}@anchor{2bb4}@anchor{library/pickle module-pickle}@anchor{ab}@anchor{library/pickle pickle-python-object-serialization}@anchor{2bb5}
@subsection @code{pickle} --- Python 物件序列化


@geindex module; pickle

`原始碼：'Lib/pickle.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/pickle.py}

@geindex persistence（持續性）
@geindex persistent（持續）;objects（物件）
@geindex serializing（序列化）;objects（物件）
@geindex marshalling;objects（物件）
@geindex flattening（攤平）;objects（物件）
@geindex pickling;objects（物件）


__________________________________________________________________


@ref{ab,,pickle} 模組實作的是一個在二進位層級上對 Python 物件進行序列化（serialize）或去序列化（de-serialize）。`"Pickling"' 用於專門指摘將一個 Python 物件轉換為一個二進位串流的過程，`"unpickling"' 則相反，指的是將一個（來自 @ref{1f35,,binary file} 或 @ref{193,,bytes-like object} 的）二進位串流轉換回 Python 物件的過程。Pickling（和 unpickling）的過程也可能被稱作 "serialization", "marshalling," @footnote{
不要將此模組與 @ref{91,,marshal} 模組混淆
} 或 "flattening"。不過，為了避免混淆，本文件將統一稱作封裝（pickling）、拆封（unpickling）。

@cartouche
@quotation 警告 
@code{pickle} 模組`並不安全'，切記只拆封你信任的資料。

pickle 封包是有可能被建立來在拆封的時候`執行任意惡意程式碼'的。絕對不要拆封任何你無法信任其來源、或可能被修改過的 pickle 封包。

建議你可以使用 @ref{6e,,hmac} 模組來簽署這個封包，以確保其未被修改過。

如果你在處理不受信任的資料，其他比較安全的序列化格式（例如 @ref{86,,json}）可能會更適合。請參照 See @ref{2bb6,,和 json 的比較} 的說明。
@end quotation
@end cartouche

@menu
* 和其他 Python 模組的關係:: 
* 資料串流格式:: 
* 模組介面:: 
* 哪些物件能或不能被封裝、拆封？:: 
* Pickling 類別實例:: 
* 針對型別、函式或特定物件定製縮減函式:: 
* 帶外（Out-of-band）資料緩衝區:: 
* 限制全域物件:: 
* 效能: 效能<2>. 
* 範例: 範例<10>. 
* 命令列介面:: 

@end menu

@node 和其他 Python 模組的關係,資料串流格式,,pickle --- Python 物件序列化
@anchor{library/pickle relationship-to-other-python-modules}@anchor{2bb7}
@subsubsection 和其他 Python 模組的關係


@menu
* 和 marshal 的比較:: 
* 和 json 的比較:: 

@end menu

@node 和 marshal 的比較,和 json 的比較,,和其他 Python 模組的關係
@anchor{library/pickle comparison-with-marshal}@anchor{2bb8}
@subsubsection 和 @code{marshal} 的比較


Python 有另一個比較原始的序列化模組叫 @ref{91,,marshal}，不過其設計目的是為了支援 Python 的預編譯功能 @code{.pyc} 的運作。總地來說，請盡可能地使用 @ref{ab,,pickle}，沒事不要用 @ref{91,,marshal}。

@ref{ab,,pickle} 和 @ref{91,,marshal} 有幾個明顯不同的地方：


@itemize *

@item 
@ref{ab,,pickle} 會記住哪些物件已經被序列化過了，稍後再次參照到這個物件的時候才不會進行重複的序列化。@ref{91,,marshal} 沒有這個功能。

這對遞迴物件和物件共用都有影響。遞迴物件是指包含自我參照的物件。這些情況在 marshal 模組中不會被處理，若嘗試使用 marshal 處理遞迴物件會導致 Python 直譯器崩潰。物件共用發生在序列化的物件階層中、不同位置對同一物件有多個參照時。@ref{ab,,pickle} 只會儲存這個被參照的物件一次，並確保所有其他參照指向這個主要的版本。共用的物件會保持共用，這對於可變（mutable）物件來說非常重要。

@item 
@ref{91,,marshal} 無法序列化使用者自訂的類別和的實例。@ref{ab,,pickle} 則可以讓使用者儲存並還原自訂的類別實例，前提是儲存時該類別的定義存在於與要被儲存的物件所在的模組中、且可以被引入（import）。

@item 
@ref{91,,marshal} 序列化格式無法保證能在不同版本的 Python 之間移植。因為其主要的作用是支援 @code{.pyc} 檔案的運作，Python 的實作人員會在需要時實作無法前向相容的序列化方式。但只要選擇了相容的 pickle 協定，且處理了 Python 2 和 Python 3 之間的資料類型差異，@ref{ab,,pickle} 序列化協定能保證在不同 Python 版本間的相容性。
@end itemize

@node 和 json 的比較,,和 marshal 的比較,和其他 Python 模組的關係
@anchor{library/pickle comparison-with-json}@anchor{2bb6}@anchor{library/pickle id2}@anchor{2bb9}
@subsubsection 和 @code{json} 的比較


pickle 協定和 JSON (JavaScript Object Notation)@footnote{https://json.org} 有一些根本上的不同：


@itemize *

@item 
JSON 以文字形式作為序列化的輸出（輸出 unicode 文字，但大多數又會被編碼為 @code{UTF-8}），而 pickle 則是以二進位形式作為序列化的輸出；

@item 
JSON 是人類可讀的，而 pickle 則無法；

@item 
JSON 具有高互通性（interoperability）且在 Python 以外的環境也被大量利用，但 pickle 只能在 Python 內使用。

@item 
預設狀態下的 JSON 只能紀錄一小部份的 Python 內建型別，且無法紀錄自訂類別；但透過 Python 的自省措施，pickle 可以紀錄絕大多數的 Python 型別（其他比較複雜的狀況也可以透過實作 @ref{2bba,,specific object APIs} 來解決）；

@item 
去序列化不安全的 JSON 不會產生任意程式執行的風險，但去序列化不安全的 pickle 會。
@end itemize


@subsubheading 也參考


@ref{86,,json} module: 是標準函式庫的一部分，可讓使用者進行 JSON 的序列化與去序列化。


@node 資料串流格式,模組介面,和其他 Python 模組的關係,pickle --- Python 物件序列化
@anchor{library/pickle data-stream-format}@anchor{2bbb}@anchor{library/pickle pickle-protocols}@anchor{27b}
@subsubsection 資料串流格式


@geindex External Data Representation（外部資料表現）

@ref{ab,,pickle} 使用的資料格式是針對 Python 而設計的。好處是他不會受到外部標準（像是 JSON，無法紀錄指標共用）的限制；不過這也代表其他不是 Python 的程式可能無法重建 pickle 封裝的 Python 物件。

以預設設定來說，@ref{ab,,pickle} 使用相對緊湊的二進位形式來儲存資料。如果你需要盡可能地縮小檔案大小，你可以@ref{2bbc,,壓縮}封裝的資料。

@ref{ac,,pickletools} 含有工具可分析 @ref{ab,,pickle} 所產生的資料流。@ref{ac,,pickletools} 的源始碼詳細地記載了所有 pickle 協定的操作碼（opcode）。

截至目前為止，共有六種不同版本的協定可用於封裝 pickle。數字越大版本代表你需要使用越新的 Python 版本來拆封相應的 pickle 封裝。


@itemize *

@item 
版本 0 的協定是最初「人類可讀」的版本，且可以向前支援早期版本的 Python。

@item 
版本 1 的協定使用舊的二進位格式，一樣能向前支援早期版本的 Python。

@item 
版本 2 的協定在 Python 2.3 中初次被引入。其可提供更高效率的 @ref{2bbd,,new-style classes} 封裝過程。請參閱 
@geindex Python Enhancement Proposals; PEP 307
PEP 307@footnote{https://peps.python.org/pep-0307/} 以了解版本 2 帶來的改進。

@item 
版本 3 的協定在 Python 3.0 被新增。現在能支援封裝 @ref{192,,bytes} 的物件且無法被 2.x 版本的 Python 拆封。在 3.0～3.7 的 Python 預設使用 3 版協定。

@item 
版本 4 的協定在 Python 3.4 被新增。現在能支援超大物件的封裝、更多種型別的物件以及針對部份資料格式的儲存進行最佳化。從 Python 3.8 到 3.13，預設使用第 4 版協定。請參閱 
@geindex Python Enhancement Proposals; PEP 3154
PEP 3154@footnote{https://peps.python.org/pep-3154/} 以了解第 4 版協定改進的細節。

@item 
版本 5 的協定在 Python 3.8 被新增。現在能支援帶外資料（Out-of-band data）並加速帶內資料的處理速度。自 3.14 起這是預設使用的協定。請參閱 
@geindex Python Enhancement Proposals; PEP 574
PEP 574@footnote{https://peps.python.org/pep-0574/} 以了解第 5 版協定改進的細節。
@end itemize

@cartouche
@quotation 備註 
資料序列化是一個比資料持久化更早出現的概念；雖然 @ref{ab,,pickle} 可以讀寫檔案物件，但它並不處理命名持久物件的問題，也不處理對持久物件的並行存取、一個更棘手的問題。@ref{ab,,pickle} 模組可以將複雜物件轉換成位元組串流，也可以將位元組串流轉換回具有相同原始內部結構的物件。對這些位元組串流最常見的處理方式是將它們寫入檔案中，但也可以將它們透過網路傳送或儲存在一個資料庫中。@ref{c8,,shelve} 模組提供了一個簡單的介面來讓使用者在 DBM 風格的資料庫檔案中對物件進行封裝和拆封的操作。
@end quotation
@end cartouche

@node 模組介面,哪些物件能或不能被封裝、拆封？,資料串流格式,pickle --- Python 物件序列化
@anchor{library/pickle module-interface}@anchor{2bbe}
@subsubsection 模組介面


想要序列化一個物件，你只需要呼叫 @ref{1698,,dumps()} 函式。而當你想要去序列化一個資料流時，你只需要呼叫 @ref{f08,,loads()} 即可。不過，若你希望能各自對序列化和去序列化的過程中有更多的掌控度，你可以自訂一個 @ref{c0a,,Pickler} 或 @ref{1971,,Unpickler} 物件。

@ref{ab,,pickle} 模組提供以下常數：

@geindex HIGHEST_PROTOCOL (於 pickle 模組中)
@anchor{library/pickle pickle HIGHEST_PROTOCOL}@anchor{1699}
@deffn {資料} pickle.HIGHEST_PROTOCOL

一個整數，表示可使用的最高@ref{27b,,協定版本}。這個值可作為 `protocol' 的數值傳給 @ref{2bbf,,dump()} 和 @ref{1698,,dumps()} 函式以及 @ref{c0a,,Pickler} 建構式。
@end deffn

@geindex DEFAULT_PROTOCOL (於 pickle 模組中)
@anchor{library/pickle pickle DEFAULT_PROTOCOL}@anchor{a28}
@deffn {資料} pickle.DEFAULT_PROTOCOL

一個整數，用於 pickle 的預設 @ref{27b,,協定版本}。可能小於 @ref{1699,,HIGHEST_PROTOCOL}。目前預設協定是 5，在 Python 3.8 中引入，與之前的版本不相容。此版本引入了對 out-of-band buffer 的支援，其中 
@geindex Python Enhancement Proposals; PEP 3118
PEP 3118@footnote{https://peps.python.org/pep-3118/} 相容的資料可以與主要 pickle 串流分開傳輸。


在 3.0 版的變更: 預設協定版本為 3。



在 3.8 版的變更: 預設協定版本為 4。



在 3.14 版的變更: 預設協定是 5。

@end deffn

@ref{ab,,pickle} 模組提供下列函式來簡化封裝的過程：

@geindex dump() (於 pickle 模組中)
@anchor{library/pickle pickle dump}@anchor{2bbf}
@deffn {函式} pickle.dump (obj, file, protocol=None, *, fix_imports=True, buffer_callback=None)

將被封裝成 pickle 形式的物件 `obj' 寫入到已開啟的@ref{13c4,,file object} `file'。這等效於@code{Pickler(file, protocol).dump(obj)}。

引數 `file'、`protocol'、`fix_imports' 和 `buffer_callback' 的意義與 @ref{c0a,,Pickler} 建構式中的相同。


在 3.8 版的變更: 新增 `buffer_callback' 引數。

@end deffn

@geindex dumps() (於 pickle 模組中)
@anchor{library/pickle pickle dumps}@anchor{1698}
@deffn {函式} pickle.dumps (obj, protocol=None, *, fix_imports=True, buffer_callback=None)

將被封裝為 pickle 形式的物件 `obj' 以 @ref{192,,bytes} 類別回傳，而非寫入進檔案。

引數 `protocol'、`fix_imports' 和 `buffer_callback' 的意義和 @ref{c0a,,Pickler} 建構式中的相同。


在 3.8 版的變更: 新增 `buffer_callback' 引數。

@end deffn

@geindex load() (於 pickle 模組中)
@anchor{library/pickle pickle load}@anchor{f07}
@deffn {函式} pickle.load (file, *, fix_imports=True, encoding='ASCII', errors='strict', buffers=None)

從已開啟的 @ref{13c4,,檔案物件} `file' 中讀取已序列化的物件，並傳回其重建後的物件階層。這相當於呼叫 @code{Unpickler(file).load()}。

模組會自動偵測 pickle 封包所使用的協定版本，所以無須另外指定。超出 pickle 封包表示範圍的位元組將被忽略。

引數 `file'、`fix_imports'、`encoding'、`errors'、`strict' 和 `buffers' 的意義和 @ref{1971,,Unpickler} 建構式中的相同。


在 3.8 版的變更: 新增 `buffer' 引數。

@end deffn

@geindex loads() (於 pickle 模組中)
@anchor{library/pickle pickle loads}@anchor{f08}
@deffn {函式} pickle.loads (data, /, *, fix_imports=True, encoding='ASCII', errors='strict', buffers=None)

回傳從 `data' 的 pickle 封包重建後的物件階層。`data' 必須是一個 @ref{193,,bytes-like object}。

模組會自動偵測 pickle 封包所使用的協定版本，所以無須另外指定。超出 pickle 封包表示範圍的位元組將被忽略。

引數 `fix_imports'、`encoding'、`errors'、`strict' 和 `buffers' 的意義與 @ref{1971,,Unpickler} 建構式所用的相同。


在 3.8 版的變更: 新增 `buffer' 引數。

@end deffn

@ref{ab,,pickle} 模組定義了以下三種例外：

@geindex PickleError
@anchor{library/pickle pickle PickleError}@anchor{2bc0}
@deffn {例外} pickle.PickleError

繼承 @ref{bc4,,Exception} 類別。一個在封裝或拆封時遭遇其他例外時通用的基底類別。
@end deffn

@geindex PicklingError
@anchor{library/pickle pickle PicklingError}@anchor{18a9}
@deffn {例外} pickle.PicklingError

當 @ref{c0a,,Pickler} 遭遇無法封裝物件時會引發的例外。繼承 @ref{2bc0,,PickleError} 類別。

請參閱 @ref{2bc1,,哪些物件能或不能被封裝、拆封？} 以了解哪些物件是可以被封裝的。
@end deffn

@geindex UnpicklingError
@anchor{library/pickle pickle UnpicklingError}@anchor{2bc2}
@deffn {例外} pickle.UnpicklingError

拆封物件時遇到問題（如資料毀損或違反安全性原則等）所引發的意外。繼承自 @ref{2bc0,,PickleError} 類別。

拆封的時候還是可能會遭遇其他不在此列的例外（例如：AttributeError、EOFError、ImportError、或 IndexError），請注意。
@end deffn

引入模組 @ref{ab,,pickle} 時會帶來三個類別：@ref{c0a,,Pickler}、@ref{1971,,Unpickler} 和 @ref{1ab0,,PickleBuffer}：

@geindex Pickler (pickle 中的類別)
@anchor{library/pickle pickle Pickler}@anchor{c0a}
@deffn {類別} pickle.Pickler (file, protocol=None, *, fix_imports=True, buffer_callback=None)

接受一個用以寫入 pickle 資料流的二進位檔案。

可選引數 `protocol' 接受整數，用來要求封裝器（pickler）使用指定的協定；支援從 0 版起到 @ref{1699,,HIGHEST_PROTOCOL} 版的協定。如未指定，則預設為 @ref{a28,,DEFAULT_PROTOCOL}。若指定了負數，則視為選擇 @ref{1699,,HIGHEST_PROTOCOL}。

引數 `file' 必須支援可寫入單一位元組引數的 write() 方法。只要滿足此條件，傳入的物件可以是一個硬碟上二進位檔案、一個 @ref{109f,,io.BytesIO} 實例或任何其他滿足這個介面要求的物件。

若 `fix_imports' 設為 true 且 `protocol' 版本小於 3，本模組會嘗試將 Python 3 的新模組名稱轉換為 Python 2 所支援的舊名，以讓 Python 2 能正確地讀取此資料流。

如果 `buffer_callback' 是 @code{None}（預設值），緩衝區的視圖會作為 pickle 封裝串流的一部分被序列化進 `file' 中。

如果 `buffer_callback' 不是 @code{None}，則它可以被多次呼叫並回傳一個緩衝區的視圖。如果回呼函式回傳一個假值（例如 @code{None}），則所給的緩衝區將被視為 @ref{2bc3,,帶外資料}；否則，該緩衝區將被視為 pickle 串流的帶內資料被序列化。

如果 `buffer_callback' 不是 @code{None} 且 `protocol' 是 @code{None} 或小於 5 則會報錯。


在 3.8 版的變更: 新增 `buffer_callback' 引數。


@geindex dump() (pickle.Pickler 的方法)
@anchor{library/pickle pickle Pickler dump}@anchor{1cee}
@deffn {方法} dump (obj)

將已封裝（pickled）的 `obj' 寫入已在建構式中開啟的對應檔案。
@end deffn

@geindex persistent_id() (pickle.Pickler 的方法)
@anchor{library/pickle pickle Pickler persistent_id}@anchor{1877}
@deffn {方法} persistent_id (obj)

預設不進行任何動作。這是一種抽象方法，用於讓後續繼承這個類別的物件可以覆寫本方法函式。

如果 @ref{1877,,persistent_id()} 回傳 @code{None}，則 `obj' 會照一般的方式進行封裝（pickling）。若回傳其他值，則 @ref{c0a,,Pickler} 會將該值作為 `obj' 的永久識別碼回傳。此永久識別碼的意義應由 @ref{187f,,Unpickler.persistent_load()} 定義。請注意 @ref{1877,,persistent_id()} 回傳的值本身不能擁有自己的永久識別碼。

關於細節與用法範例請見 @ref{2bc4,,外部物件持久化}。


在 3.13 版的變更: 在 C 的 @code{Pickler} 實作中的增加了這個方法的預設實作。

@end deffn

@geindex dispatch_table (pickle.Pickler 的屬性)
@anchor{library/pickle pickle Pickler dispatch_table}@anchor{1323}
@deffn {屬性} dispatch_table

封裝器（pickler）物件含有的的調度表是一個`縮減函式'（reduction function）的註冊表，可以使用 @ref{2bc5,,copyreg.pickle()} 來宣告這類縮減函式。它是一個以類別為鍵、還原函式為值的映射表。縮減函式應準備接收一個對應類別的引數，並應遵循與 @ref{bbd,,__reduce__()} 方法相同的介面。

預設情況下，封裝器（pickler）物件不會有 @ref{1323,,dispatch_table} 屬性，而是會使用由 @ref{2a,,copyreg} 模組管理的全域調度表。不過，若要自訂某個封裝器（pickler）物件的序列化行為，可以將 @ref{1323,,dispatch_table} 屬性設置為類字典物件。另外，如果 @ref{c0a,,Pickler} 的子類別具有 @ref{1323,,dispatch_table} 屬性，那麼這個屬性將作為該子類別實例的預設調度表。

關於用法範例請見 @ref{2bc6,,調度表}。


在 3.3 版被加入.

@end deffn

@geindex reducer_override() (pickle.Pickler 的方法)
@anchor{library/pickle pickle Pickler reducer_override}@anchor{c0b}
@deffn {方法} reducer_override (obj)

一個可以在 @ref{c0a,,Pickler} 子類別中被定義的縮減器（reducer）。這個方法的優先度高於任何其他 @ref{1323,,分派表} 中的縮減器。他應該要有和 @ref{bbd,,__reduce__()} 方法相同的函式介面，且可以可選地回傳 @ref{1a2,,NotImplemented} 以後備（fallback）使用 @ref{1323,,分派表} 中登錄的縮減方法來封裝 @code{obj}。

請查閱 @ref{2bc7,,針對型別、函式或特定物件定製縮減函式} 來參考其他較詳細的範例。


在 3.8 版被加入.

@end deffn

@geindex fast (pickle.Pickler 的屬性)
@anchor{library/pickle pickle Pickler fast}@anchor{2bc8}
@deffn {屬性} fast

已棄用。如果設置為 true，將啟用快速模式。快速模式會停用備忘（memo），因此能透過不產生多餘的 PUT 操作碼（OpCode）來加速封裝過程。它不應被用於自我參照物件，否則將導致 @ref{c0a,,Pickler} 陷入無限遞迴。

使用 @ref{2bc9,,pickletools.optimize()} 以獲得更緊湊的 pickle 輸出。
@end deffn

@geindex clear_memo() (pickle.Pickler 的方法)
@anchor{library/pickle pickle Pickler clear_memo}@anchor{2bca}
@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{1971}
@deffn {類別} pickle.Unpickler (file, *, fix_imports=True, encoding='ASCII', errors='strict', buffers=None)

這個物件接受一個二進位檔案 `file' 來從中讀取 pickle 資料流。

協定版本號會被自動偵測，所以不需要在這邊手動輸入。

參數 `file' 必須擁有三個方法，分別是接受整數作為引數的 read() 方法、接受緩衝區作為引數的 readinto() 方法以及不需要引數的 readline() 方法，如同在 @ref{89c,,io.BufferedIOBase} 的介面一樣。因此，`file' 可以是一個以二進位讀取模式開啟的檔案、一個 @ref{109f,,io.BytesIO} 物件、或任何符合此介面的自訂物件。

可選引數 `fix_imports'、`encoding' 和 `errors' 用來控制 Python 2 pickle 資料的相容性支援。如果 `fix_imports' 為 true，則 pickle 模組會嘗試將舊的 Python 2 模組名稱映射到 Python 3 中使用的新名稱。`encoding' 和 `errors' 告訴 pickle 模組如何解碼由 Python 2 pickle 封裝的 8 位元字串實例；`encoding' 和 `errors' 預設分別為 'ASCII' 和 'strict'。`encoding' 可以設定為 'bytes' 以將這些 8 位元字串實例讀為位元組物件。而由 Python 2 封裝的 NumPy 陣列、@ref{4dd,,datetime}、@ref{1fa,,date} 和 @ref{1fb,,time} 的實例則必須使用 @code{encoding='latin1'} 來拆封。

如果 `buffers' 是 @code{None}（預設值），那麼去序列化所需的所有資料都必須已經包含在 pickle 串流中。這意味著當初在建立對應的 @ref{c0a,,Pickler} 時（或在呼叫 @ref{2bbf,,dump()} 或 @ref{1698,,dumps()} 時）*buffer_callback* 引數必須為 @code{None}。

如果 `buffers' 不是 @code{None}，則其應該是一個可疊代物件，內含數個支援緩衝區的物件，並且每當 pickle 串流引用一個@ref{2bc3,,帶外}緩衝區視圖時將會被照順序消耗。這些緩衝資料當初建立時應已按照順序給定於 Pickler 物件中的 `buffer_callback'。


在 3.8 版的變更: 新增 `buffer' 引數。


@geindex load() (pickle.Unpickler 的方法)
@anchor{library/pickle pickle Unpickler load}@anchor{2bcb}
@deffn {方法} load ()

開啟先前被傳入建構子的檔案，從中讀取一個被 pickle 封裝的物件，並回傳重建完成的物件階層。超過 pickle 表示範圍的位元組會被忽略。
@end deffn

@geindex persistent_load() (pickle.Unpickler 的方法)
@anchor{library/pickle pickle Unpickler persistent_load}@anchor{187f}
@deffn {方法} persistent_load (pid)

預設會引發 @ref{2bc2,,UnpicklingError} 例外。

若有定義，則 @ref{187f,,persistent_load()} 將回傳符合持久化識別碼 `pid' 的物件。如果遭遇了無效的持久化識別碼，則會引發 @ref{2bc2,,UnpicklingError}。

關於細節與用法範例請見 @ref{2bc4,,外部物件持久化}。


在 3.13 版的變更: 在 C 的 @code{Unpickler} 實作中的增加了這個方法的預設實作。

@end deffn

@geindex find_class() (pickle.Unpickler 的方法)
@anchor{library/pickle pickle Unpickler find_class}@anchor{2bcc}
@deffn {方法} find_class (module, name)

如有需要將引入 `module'，並從中回傳名為 `name' 的物件，這裡的 `module' 和 `name' 引數接受的輸入是 @ref{169,,str} 物件。注意，雖然名稱上看起來不像，但 @ref{2bcc,,find_class()} 亦可被用於尋找其他函式。

子類別可以覆寫此方法以控制可以載入哪些類型的物件、以及如何載入它們，從而潛在地降低安全性風險。詳情請參考@ref{2bcd,,限制全域物件}。

引發一個附帶引數 @code{module}、@code{name} 的@ref{1b70,,稽核事件} @code{pickle.find_class}。
@end deffn
@end deffn

@geindex PickleBuffer (pickle 中的類別)
@anchor{library/pickle pickle PickleBuffer}@anchor{1ab0}
@deffn {類別} pickle.PickleBuffer (buffer)

一個表示了含有可封裝資料緩衝區的包裝函式（wrapper function）。`buffer' 必須是一個 @ref{260,,提供緩衝區} 的物件，例如一個 @ref{193,,類位元組物件} 或 N 維陣列。

@ref{1ab0,,PickleBuffer} 本身就是一個提供緩衝區的物件，所以是能夠將其提供給其它「預期收到含有緩衝物件的 API」的，比如 @ref{165,,memoryview}。

@ref{1ab0,,PickleBuffer} 物件僅能由 5 版或以上的 pickle 協定進行封裝。該物件亦能被作為帶外資料來進行@ref{2bc3,,帶外資料序列化}


在 3.8 版被加入.


@geindex raw() (pickle.PickleBuffer 的方法)
@anchor{library/pickle pickle PickleBuffer raw}@anchor{2bce}
@deffn {方法} raw ()

回傳此緩衝區底層記憶體區域的 @ref{165,,memoryview}。被回傳的物件是一個（在 C 語言的 formatter 格式中）以 @code{B} (unsigned bytes) 二進位格式儲存、一維且列連續（C-contiguous）的 memoryview。如果緩衝區既不是列連續（C-contiguous）也不是行連續（Fortran-contiguous）的，則會引發 @ref{1adb,,BufferError}。
@end deffn

@geindex release() (pickle.PickleBuffer 的方法)
@anchor{library/pickle pickle PickleBuffer release}@anchor{2bcf}
@deffn {方法} release ()

釋放 PickleBuffer 物件現正曝光中的緩衝區。
@end deffn
@end deffn

@node 哪些物件能或不能被封裝、拆封？,Pickling 類別實例,模組介面,pickle --- Python 物件序列化
@anchor{library/pickle pickle-picklable}@anchor{2bc1}@anchor{library/pickle what-can-be-pickled-and-unpickled}@anchor{2bd0}
@subsubsection 哪些物件能或不能被封裝、拆封？


下列型別可以被封裝：


@itemize *

@item 
內建常數（@code{None}、@code{True}、@code{False}、@code{Ellipsis} 和 @ref{1a2,,NotImplemented}）；

@item 
整數、浮點數和複數；

@item 
字串、位元組物件、位元組陣列；

@item 
元組（tuple）、串列（list）、集合（set）和僅含有可封裝物件的字典；

@item 
在模組最表面的層級就能被存取的函式（內建或自訂的皆可，不過僅限使用 @ref{164f,,def} 定義的函式，@ref{149e,,lambda} 函式不適用）；

@item 
在模組最表面的層級就能被存取的類別；

@item 
實例，只要在呼叫了 @ref{7ea,,__getstate__()} 後其回傳值全都是可封裝物件。（詳情請參閱 @ref{2bba,,Pickling 類別實例}）。
@end itemize

嘗試封裝無法封裝的物件會引發 @ref{18a9,,PicklingError} 例外；注意當這種情況發生時，可能已經有未知數量的位元組已被寫入到檔案。嘗試封裝深度遞迴的資料結構可能會導致其超出最大遞迴深度，在這種情況下會引發 @ref{f63,,RecursionError} 例外。你可以（小心地）使用 @ref{6e3,,sys.setrecursionlimit()} 來提高此上限。

請注意，函式（內建及自訂兩者皆是）是依據完整的 @ref{1bf6,,限定名稱} 來封裝，而非依其值。@footnote{
這就是為什麼 @ref{149e,,lambda} 函式無法被封裝：所有 @code{lambda} 函式共享相同的名稱：@code{<lambda>}。
} 這意味著封裝時只有函式名稱、所屬的模組和所屬的類別名稱會被封裝。函式本身的程式碼及其附帶的任何屬性均不會被封裝。因此，在拆封該物件的環境中，定義此函式的模組必須可被引入，且該模組必須包含具此命名之物件，否則將引發例外。 @footnote{
引發的例外應該是 @ref{653,,ImportError} 或 @ref{5e8,,AttributeError}，但也可能是其他例外。
}

同樣情況，類別是依照其完整限定名稱來進行封裝，因此在進行拆封的環境中會具有同上的限制。類別中的程式碼或資料皆不會被封裝，因此在以下範例中，注意到類別屬性 @code{attr} 在拆封的環境中不會被還原:

@example
class Foo:
    attr = 'A class attribute'

picklestring = pickle.dumps(Foo)
@end example

這些限制就是可封裝的函式和類別必須被定義在模組頂層的原因。

同樣地，當類別實例被封裝時，它所屬類別具有的程式碼和資料不會被一起封裝。只有實例資料本身會被封裝。這是有意而為的，因為如此你才可以在類別中修正錯誤或新增其他方法，且於此同時仍能夠載入使用較早期版本的類別所建立的物件實例。如果你預計將有長期存在的物件、且該物件將經歷許多版本的更替，你可以在物件中存放一個版本號，以便未來能透過 @ref{bbe,,__setstate__()} 方法來進行適當的版本轉換。

@node Pickling 類別實例,針對型別、函式或特定物件定製縮減函式,哪些物件能或不能被封裝、拆封？,pickle --- Python 物件序列化
@anchor{library/pickle pickle-inst}@anchor{2bba}@anchor{library/pickle pickling-class-instances}@anchor{2bd1}
@subsubsection Pickling 類別實例


在這一個章節，我們會講述如何封裝或拆封一個物件實例的相關機制，以方便你進行自訂。

大部分的實例不需要額外的程式碼就已經是可封裝的了。在這樣的預設狀況中，pickle 模組透過自省機制來取得類別及其實例的屬性。當類別實例被拆封時，其 @ref{8b7,,__init__()} 方法通常`不會'被呼叫。預設行為首先會建立一個未初始化的實例，然後還原紀錄中的屬性。以下程式碼的實作展示了前述行為：

@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

被封裝的目標類別可以提供一個或數個下列特殊方法來改變 pickle 的預設行為：

@geindex __getnewargs_ex__() (object 的方法)
@anchor{library/pickle object __getnewargs_ex__}@anchor{2bd2}
@deffn {方法} object.__getnewargs_ex__ ()

在第 2 版協定或更新的版本中，有實作 @ref{2bd2,,__getnewargs_ex__()} 方法的類別，可以決定在拆封時要傳遞給 @ref{799,,__new__()} 方法的值。該方法必須回傳一個 @code{(args, kwargs)} 的組合，其中 `args' 是一個位置引數的元組（tuple），`kwargs' 是一個用於建構物件的命名引數字典。這些資訊將在拆封時傳遞給 @ref{799,,__new__()} 方法。

如果目標類別的方法 @ref{799,,__new__()} 需要僅限關鍵字的參數時，你應該實作此方法。否則，為了提高相容性，建議你改為實作 @ref{fcf,,__getnewargs__()}。


在 3.6 版的變更: 在第 2、3 版的協定中現在改為使用 @ref{2bd2,,__getnewargs_ex__()}。

@end deffn

@geindex __getnewargs__() (object 的方法)
@anchor{library/pickle object __getnewargs__}@anchor{fcf}
@deffn {方法} object.__getnewargs__ ()

此方法與 @ref{2bd2,,__getnewargs_ex__()} 的目的一樣，但僅支援位置參數。它必須回傳一個由傳入引數所組成的元組（tuple）@code{args}，這些引數會在拆封時傳遞給 @ref{799,,__new__()} 方法。

當有定義 @ref{2bd2,,__getnewargs_ex__()} 的時候便不會呼叫 @ref{fcf,,__getnewargs__()}。


在 3.6 版的變更: 在 Python 3.6 之前、版本 2 和版本 3 的協定中，會呼叫 @ref{fcf,,__getnewargs__()} 而非 @ref{2bd2,,__getnewargs_ex__()}。

@end deffn

@geindex __getstate__() (object 的方法)
@anchor{library/pickle object __getstate__}@anchor{7ea}
@deffn {方法} object.__getstate__ ()

目標類別可以透過覆寫方法 @ref{7ea,,__getstate__()} 進一步影響其實例被封裝的方式。封裝時，呼叫該方法所回傳的物件將作為該實例的內容被封裝、而非一個預設狀態。以下列出幾種預設狀態：


@itemize *

@item 
沒有 @ref{776,,__dict__} 和 @ref{16df,,__slots__} 實例的類別，其預設狀態為 @code{None}。

@item 
有 @ref{776,,__dict__} 實例、但沒有 @ref{16df,,__slots__} 實例的類別，其預設狀態為 @code{self.__dict__}。

@item 
有 @ref{776,,__dict__} 和 @ref{16df,,__slots__} 實例的類別，其預設狀態是一個含有兩個字典的元組（tuple），該二字典分別為 @code{self.__dict__} 本身，和紀錄欄位（slot）名稱和值對應關係的字典（只有含有值的欄位（slot）會被紀錄其中）。

@item 
沒有 @ref{776,,__dict__} 但有 @ref{16df,,__slots__} 實例的類別，其預設狀態是一個二元組（tuple），元組中的第一個值是 @code{None}，第二個值則是紀錄欄位（slot）名稱和值對應關係的字典（與前一項提到的字典是同一個）。
@end itemize


在 3.11 版的變更: 在 @ref{c75,,object} 類別中增加預設的 @code{__getstate__()} 實作。

@end deffn

@geindex __setstate__() (object 的方法)
@anchor{library/pickle object __setstate__}@anchor{bbe}
@deffn {方法} object.__setstate__ (state)

在拆封時，如果類別定義了 @ref{bbe,,__setstate__()}，則會使用拆封後的狀態呼叫它。在這種情況下，紀錄狀態的物件不需要是字典（dictionary）。否則，封裝時的狀態紀錄必須是一個字典，其紀錄的項目將被賦值給新實例的字典。

@cartouche
@quotation 備註 
如果 @ref{bbd,,__reduce__()} 在封裝時回傳了 @code{None} 狀態，則拆封時就不會去呼叫 @ref{bbe,,__setstate__()}。
@end quotation
@end cartouche
@end deffn

參閱 @ref{2bd3,,處裡紀錄大量狀態的物件} 以了解 @ref{7ea,,__getstate__()} 和 @ref{bbe,,__setstate__()} 的使用方法。

@cartouche
@quotation 備註 
在拆封時，某些方法如 @ref{6f3,,__getattr__()}、@ref{dc6,,__getattribute__()} 或 @ref{222d,,__setattr__()} 可能會在建立實例時被呼叫。如果這些方法依賴了某些實例內部的不變性，則應實作 @ref{799,,__new__()} 以建立此不變性，因為在拆封實例時不會呼叫 @ref{8b7,,__init__()}。
@end quotation
@end cartouche

@geindex copy（複製）;protocol（協定）

如稍後所演示，pickle 並不直接使用上述方法。這些方法實際上是實作了 @ref{bbd,,__reduce__()} 特殊方法的拷貝協定（copy protocol）。拷貝協定提供了統一的介面，以檢索進行封裝及複製物件時所需的資料。 @footnote{
@ref{29,,copy} 模組使用此協定進行淺層及深層複製操作。
}

直接在類別中實作 @ref{bbd,,__reduce__()} 雖然功能強大但卻容易導致出錯。因此，設計類別者應盡可能使用高階介面（例如，@ref{2bd2,,__getnewargs_ex__()}、@ref{7ea,,__getstate__()} 和 @ref{bbe,,__setstate__()}）。不過，我們也將展示一些特例狀況，在這些狀況中，使用 @code{__reduce__()} 可能是唯一的選擇、是更有效率的封裝方法或二者兼備。

@geindex __reduce__() (object 的方法)
@anchor{library/pickle object __reduce__}@anchor{bbd}
@deffn {方法} object.__reduce__ ()

目前的介面定義如下。 @ref{bbd,,__reduce__()} 方法不接受引數，且應回傳一個字串或一個元組（元組一般而言是較佳的選擇；所回傳的物件通常稱為「縮減值」）。

如果回傳的是字串，該字串應被解讀為一個全域變數的名稱。它應是該物件相對其所在模組的本地名稱；pickle 模組會在模組命名空間中尋找，以確定該物件所在的模組。這種行為通常對於單例物件特別有用。

當回傳一個元組時，其長度必須介於兩至六項元素之間。可選項可以被省略，或者其值可以被設為 @code{None}。各項物件的語意依序為：

@c XXX Mention __newobj__ special-case?


@itemize *

@item 
一個將會被呼叫來建立初始版本物件的可呼叫物件。

@item 
一個用於傳遞引數給前述物件的元組。如果前述物件不接受引數輸入，則你仍應在這裡給定一個空元組。

@item 
可選項。物件狀態。如前所述，會被傳遞給該物件的 @ref{bbe,,__setstate__()} 方法。如果該物件沒有實作此方法，則本值必須是一個字典，且其將會被新增到物件的 @ref{776,,__dict__} 屬性中。

@item 
可選項。一個用來提供連續項目的疊代器（而非序列）。這些項目將個別透過 @code{obj.append(item)} 方法或成批次地透過 @code{obj.extend(list_of_items)} 方法被附加到物件中。主要用於串列（list）子類別，但只要其他類別具有相應的 @ref{2288,,append()} 和 @ref{228b,,extend()} 方法以及相同的函式簽章（signature）就也可以使用。 （是否會呼叫 @code{append()} 或 @code{extend()} 方法將取決於所選用的 pickle 協定版本以及要附加的項目數量，因此必須同時支援這兩種方法。）

@item 
可選項。一個產生連續鍵值對的疊代器（不是序列）。這些項目將以 @code{obj[key] = value} 方式被儲存到物件中。主要用於字典（dictionary）子類別，但只要有實現了 @ref{14cc,,__setitem__()} 的其他類別也可以使用。

@item 
可選項。一個具有 @code{(obj, state)} 函式簽章（signature）的可呼叫物件。該物件允許使用者以可編寫的邏輯，而不是物件 @code{obj} 預設的 @ref{bbe,,__setstate__()} 靜態方法去控制特定物件的狀態更新方式。如果這個物件不是 @code{None}，這個物件的呼叫優先權將優於物件 @code{obj} 的 @ref{bbe,,__setstate__()}。


在 3.8 版被加入: 加入第六個可選項（一個 @code{(obj, state)} 元組）。

@end itemize
@end deffn

@geindex __reduce_ex__() (object 的方法)
@anchor{library/pickle object __reduce_ex__}@anchor{18d2}
@deffn {方法} object.__reduce_ex__ (protocol)

另外，你也可以定義一個 @ref{18d2,,__reduce_ex__()} 方法。唯一的不同的地方是此方法只接受協定版本（整數）作為參數。當有定義本方法時，pickle 會優先呼叫它而不是 @ref{bbd,,__reduce__()} 。此外，呼叫 @ref{bbd,,__reduce__()} 時也會自動變成呼叫這個變體版本。此方法主要是為了向後相容的舊的 Python 版本而存在。
@end deffn

@menu
* 外部物件持久化:: 
* 調度表:: 
* 處裡紀錄大量狀態的物件:: 

@end menu

@node 外部物件持久化,調度表,,Pickling 類別實例
@anchor{library/pickle persistence-of-external-objects}@anchor{2bd4}@anchor{library/pickle pickle-persistent}@anchor{2bc4}
@subsubsection 外部物件持久化


@geindex persistent_id（pickle 協定）
@geindex persistent_load（pickle 協定）

為了方便物件持久化，@ref{ab,,pickle} 模組支援對被封裝資料串流以外的物件參照。被參照的物件是透過一個持久化 ID 來參照的，這個 ID 應該要是字母數字字元（alphanumeric）組成的字串（協定 0） @footnote{
協定 0 中限制僅能使用英文字母或數字字元來分配持久化 ID 是因為持久化 ID 是由換行符號所分隔的。因此，如果持久化 ID 中出現任何形式的換行字元，將導致封裝資料變得無法讀取。
} 或者是任意的物件（任何較新的協定）。

@ref{ab,,pickle} 沒有定義要如何解決或分派這個持久化 ID 的問題；故其處理方式有賴使用者自行定義在封裝器（pickler）以及拆封器（unpickler）中。方法的名稱各自為 @ref{1877,,persistent_id()} 和 @ref{187f,,persistent_load()}。

要封裝具有外部持久化 ID 的物件，封裝器（pickler）必須擁有一個自訂的方法 @ref{1877,,persistent_id()}，這個方法將接收一個物件作為參數，並回傳 @code{None} 或該物件的持久化 ID。當回傳 @code{None} 時，封裝器會正常地封裝該物件。當回傳一個持久化 ID 字串時，封裝器會封裝該物件並加上一個標記，讓拆封器（unpickler）能識別它是一個持久化 ID。

要拆封外部物件，拆封器（unpickler）必須有一個自訂的 @ref{187f,,persistent_load()} 方法，該方法應接受一個持久化 ID 物件，並回傳相對應的物件。

以下是一個完整的範例，用以說明如何使用持久化 ID 來封裝具外部參照的物件。

@example
# 展示如何使用持久化 ID 來封裝外部物件的簡單範例

import pickle
import sqlite3
from collections import namedtuple

# 代表資料庫中紀錄的一個簡易類別
MemoRecord = namedtuple("MemoRecord", "key, task")

class DBPickler(pickle.Pickler):

    def persistent_id(self, obj):
        # 我們派發出一個持久 ID，而不是像一般類別實例那樣封裝 MemoRecord。
        if isinstance(obj, MemoRecord):
            # 我們的持久 ID 就是一個元組，裡面包含一個標籤和一個鍵，指向資料庫中的特定紀錄。
            return ("MemoRecord", obj.key)
        else:
            # 如果 obj 沒有持久 ID，則回傳 None。這表示 obj 像平常那樣封裝即可。
            return None


class DBUnpickler(pickle.Unpickler):

    def __init__(self, file, connection):
        super().__init__(file)
        self.connection = connection

    def persistent_load(self, pid):
        # 每當遇到持久 ID 時，此方法都會被呼叫。
        # pid 是 DBPickler 所回傳的元組。
        cursor = self.connection.cursor()
        type_tag, key_id = pid
        if type_tag == "MemoRecord":
            # 從資料庫中抓取所引用的紀錄並回傳。
            cursor.execute("SELECT * FROM memos WHERE key=?", (str(key_id),))
            key, task = cursor.fetchone()
            return MemoRecord(key, task)
        else:
            # 如果無法回傳正確的物件，則必須引發錯誤。
            # 否則 unpickler 會誤認為 None 是持久 ID 所引用的物件。
            raise pickle.UnpicklingError("unsupported persistent object")


def main():
    import io
    import pprint

    # 初始化資料庫。
    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,))

    # 抓取要封裝的紀錄。
    cursor.execute("SELECT * FROM memos")
    memos = [MemoRecord(key, task) for key, task in cursor]
    # 使用我們自訂的 DBPickler 來保存紀錄。
    file = io.BytesIO()
    DBPickler(file).dump(memos)

    print("被封裝的紀錄:")
    pprint.pprint(memos)

    # 更新一筆紀錄（測試用）。
    cursor.execute("UPDATE memos SET task='learn italian' WHERE key=1")

    # 從 pickle 資料流中載入紀錄。
    file.seek(0)
    memos = DBUnpickler(file, conn).load()

    print("已拆封的紀錄:")
    pprint.pprint(memos)


if __name__ == '__main__':
    main()
@end example

@node 調度表,處裡紀錄大量狀態的物件,外部物件持久化,Pickling 類別實例
@anchor{library/pickle dispatch-tables}@anchor{2bd5}@anchor{library/pickle pickle-dispatch}@anchor{2bc6}
@subsubsection 調度表


如果你希望在不干擾其他物件正常封裝的前提下建立一個針對特定物件的封裝器，你可建立一個有私密調度表的封裝器。

由 @ref{2a,,copyreg} 模組管理的全域調度表可以 @code{copyreg.dispatch_table} 呼叫。你可以透過這個方式來基於原始 @code{copyreg.dispatch_table} 建立一個修改過的版本，作為你的專屬用途的調度表。

舉例來說：

@example
f = io.BytesIO()
p = pickle.Pickler(f)
p.dispatch_table = copyreg.dispatch_table.copy()
p.dispatch_table[SomeClass] = reduce_SomeClass
@end example

建立了一個 @ref{c0a,,pickle.Pickler}，其中含有專門處裡 @code{SomeClass} 類別的專屬調度表。此外，你也可以寫作：:

@example
class MyPickler(pickle.Pickler):
    dispatch_table = copyreg.dispatch_table.copy()
    dispatch_table[SomeClass] = reduce_SomeClass
f = io.BytesIO()
p = MyPickler(f)
@end example

這樣可產生相似的結果，唯一不同的是往後所有 @code{MyPickler} 預設都會使用這個專屬調度表。最後，如果將程式寫為：:

@example
copyreg.pickle(SomeClass, reduce_SomeClass)
f = io.BytesIO()
p = pickle.Pickler(f)
@end example

則會改變 @ref{2a,,copyreg} 模組內建、所有使用者共通的調度表。

@node 處裡紀錄大量狀態的物件,,調度表,Pickling 類別實例
@anchor{library/pickle handling-stateful-objects}@anchor{2bd6}@anchor{library/pickle pickle-state}@anchor{2bd3}
@subsubsection 處裡紀錄大量狀態的物件


@geindex __getstate__()（copy 協定）
@geindex __setstate__()（copy 協定）

以下的範例展示了如何修改針對特定類別封裝時的行為。下面的 @code{TextReader} 類別會開啟一個文字檔案，並在每次呼叫其 @code{readline()} 方法時返回目前行編號與該行內容。如果 @code{TextReader} 實例被封裝，所有`除了檔案物件之外'的屬性成員都會被保存。在該實例被拆封時，檔案將被重新開啟，並從上次的位置繼續讀取。這個行為的達成是透過 @code{__setstate__()} 和 @code{__getstate__()} 方法來實作的。:

@example
class TextReader:
    """列出文字檔案中的行並對其進行編號。"""

    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):
        # 從 self.__dict__ 中複製物件的狀態。包含了所有的實例屬性。
        # 使用 dict.copy() 方法以避免修改原始狀態。
        state = self.__dict__.copy()
        # 移除不可封裝的項目。
        del state['file']
        return state

    def __setstate__(self, state):
        # 恢復實例屬性（即 filename 和 lineno）。
        self.__dict__.update(state)
        # 恢復到先前開啟了檔案的狀態。為此，我們需要重新開啟它並一直讀取到行數編號相同。
        file = open(self.filename)
        for _ in range(self.lineno):
            file.readline()
        # 存檔。
        self.file = file
@end example

可以這樣實際使用：:

@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 針對型別、函式或特定物件定製縮減函式,帶外（Out-of-band）資料緩衝區,Pickling 類別實例,pickle --- Python 物件序列化
@anchor{library/pickle custom-reduction-for-types-functions-and-other-objects}@anchor{2bd7}@anchor{library/pickle reducer-override}@anchor{2bc7}
@subsubsection 針對型別、函式或特定物件定製縮減函式



在 3.8 版被加入.


有時候，@ref{1323,,dispatch_table} 的彈性空間可能不夠。尤其當我們想要使用型別以外的方式來判斷如何使用自訂封裝、或者我們想要自訂特定函式和類別的封裝方法時。

如果是這樣的話，可以繼承 @ref{c0a,,Pickler} 類別並實作一個 @ref{c0b,,reducer_override()} 方法。此方法可以回傳任意的縮減元組（參閱 @ref{bbd,,__reduce__()}）、也可以回傳 @ref{1a2,,NotImplemented} 以使用後備的原始行為方案。

如果 @ref{1323,,dispatch_table} 和 @ref{c0b,,reducer_override()} 都被定義了的話，@ref{c0b,,reducer_override()} 的優先度較高。

@cartouche
@quotation 備註 
出於效能考量，處裡以下物件可能不會呼叫 @ref{c0b,,reducer_override()}：@code{None}、@code{True}、@code{False}，以及 @ref{19b,,int}、@ref{196,,float}、@ref{192,,bytes}、@ref{169,,str}、@ref{183,,dict}、@ref{184,,set}、@ref{7eb,,frozenset}、@ref{24d,,list} 和 @ref{60c,,tuple} 的實例。
@end quotation
@end cartouche

以下是一個簡單的例子，我們示範如何允許封裝和重建給定的類別：:

@example
import io
import pickle

class MyClass:
    my_attribute = 1

class MyPickler(pickle.Pickler):
    def reducer_override(self, obj):
        """MyClass 的自訂縮減函式。"""
        if getattr(obj, "__name__", None) == "MyClass":
            return type, (obj.__name__, obj.__bases__,
                          @{'my_attribute': obj.my_attribute@})
        else:
            # 遭遇其他物件，則使用一般的縮減方式
            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）資料緩衝區,限制全域物件,針對型別、函式或特定物件定製縮減函式,pickle --- Python 物件序列化
@anchor{library/pickle out-of-band-buffers}@anchor{2bd8}@anchor{library/pickle pickle-oob}@anchor{2bc3}
@subsubsection 帶外（Out-of-band）資料緩衝區



在 3.8 版被加入.


@ref{ab,,pickle} 模組會被用於用於傳輸龐大的資料。此時，將複製記憶體的次數降到最低以保持效能變得很重要。然而，@ref{ab,,pickle} 模組的正常操作過程中，當它將物件的圖狀結構（graph-like structure）轉換為連續的位元組串流時，本質上就涉及將資料複製到封裝流以及從封裝流複製資料。

如果`供給者'（被傳遞物件的型別的實作）與`消費者'（資訊交換系統的實作）都支援由 pickle 協定 5 或更高版本提供的帶外傳輸功能，則可以避免此一先天限制。

@menu
* 供給者 API:: 
* 消費者 API:: 
* 範例: 範例<9>. 

@end menu

@node 供給者 API,消費者 API,,帶外（Out-of-band）資料緩衝區
@anchor{library/pickle provider-api}@anchor{2bd9}
@subsubsection 供給者 API


要封裝的大型資料物件，則必須實作一個針對 5 版協定及以上的 @ref{18d2,,__reduce_ex__()} 方法，該方法應回傳一個 @ref{1ab0,,PickleBuffer} 實例來處理任何大型資料（而非回傳如 @ref{192,,bytes} 物件）。

一個 @ref{1ab0,,PickleBuffer} 物件`指示'了當下底層的緩衝區狀態適合進行帶外資料傳輸。這些物件仍然相容 @ref{ab,,pickle} 模組的一般使用方式。消費者程式也可以選擇介入，指示 @ref{ab,,pickle} 他們將自行處理這些緩衝區。

@node 消費者 API,範例<9>,供給者 API,帶外（Out-of-band）資料緩衝區
@anchor{library/pickle consumer-api}@anchor{2bda}
@subsubsection 消費者 API


一個資訊交換系統可以決定要自行處裡序列化物件圖時產生的 @ref{1ab0,,PickleBuffer} 物件。

傳送端需要傳遞一個呼叫緩衝區的回呼函式給 @ref{c0a,,Pickler}（或 @ref{2bbf,,dump()} 或 @ref{1698,,dumps()} 函式）的 `buffer_callback' 引數，使每次生成 @ref{1ab0,,PickleBuffer} 時，該物件在處理物件圖時能被呼叫。除了一個簡易標記以外，由 `buffer_callback' 累積的緩衝區資料不會被複製到 pickle 串流中。

接收端需要傳遞一個緩衝區物件給 @ref{1971,,Unpickler}（或 @ref{f07,,load()} 或 @ref{f08,,loads()} 函式）的 `buffers' 引數。該物件須是一個可疊代的（iterable）緩衝區（buffer）物件，其中包含傳遞給 `buffer_callback' 的緩衝區物件。這個可疊代物件的緩衝區順序應該與它們當初被封裝時傳遞給 `buffer_callback' 的順序相同。這些緩衝區將提供物件重建所需的資料，以使重建器能還原出那個當時產生了 @ref{1ab0,,PickleBuffer} 的物件。

在傳送與接收端之間，通訊系統可以自由實作轉移帶外緩衝區資料的機制。該機制可能可以利用共用記憶體機制或根據資料類型特定的壓縮方式來最佳化執行速度。

@node 範例<9>,,消費者 API,帶外（Out-of-band）資料緩衝區
@anchor{library/pickle example}@anchor{2bdb}
@subsubsection 範例


這一個簡單的範例展示了如何實作一個可以參與帶外緩衝區封裝的 @ref{343,,bytearray} 子類別：:

@example
class ZeroCopyByteArray(bytearray):

    def __reduce_ex__(self, protocol):
        if protocol >= 5:
            return type(self)._reconstruct, (PickleBuffer(self),), None
        else:
            # PickleBuffer 在 pickle 協定 <= 4 時禁止使用。
            return type(self)._reconstruct, (bytearray(self),)

    @@classmethod
    def _reconstruct(cls, obj):
        with memoryview(obj) as m:
            # 取得對原始緩衝區物件的控制
            obj = m.obj
            if type(obj) is cls:
                # 若原本的緩衝區物件是 ZeroCopyByteArray，則直接回傳。
                return obj
            else:
                return cls(obj)
@end example

如果型別正確，重建器（@code{_reconstruct} 類別方法）會回傳當時提供緩衝區的物件。這個簡易實作可以模擬一個無複製行為的重建器。

在使用端，我們可以用一般的方式封裝這些物件，當我們拆封時會得到一個原始物件的副本：:

@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: 曾進行過複製運算
@end example

但如果我們傳一個 `buffer_callback' 並在去序列化時正確回傳積累的緩衝資料，我們就能拿回原始的物件：:

@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: 沒有進行過複製
@end example

此範例是因為受限於 @ref{343,,bytearray} 會自行分配記憶體：你無法建立以其他物件的記憶體為基礎的 @ref{343,,bytearray} 實例。不過第三方資料型態（如 NumPy 陣列）則可能沒有這個限制，而允許在不同程序或系統之間傳輸資料時使用零拷貝封裝（或儘可能地減少拷貝次數）。


@subsubheading 也參考


@geindex Python Enhancement Proposals; PEP 574
PEP 574@footnote{https://peps.python.org/pep-0574/} -- 第 5 版 Pickle 協定的帶外資料（out-of-band data）處裡


@node 限制全域物件,效能<2>,帶外（Out-of-band）資料緩衝區,pickle --- Python 物件序列化
@anchor{library/pickle pickle-restrict}@anchor{2bcd}@anchor{library/pickle restricting-globals}@anchor{2bdc}
@subsubsection 限制全域物件


@geindex find_class()（pickle 協定）

預設情況下，拆封過程將會引入任何在 pickle 資料中找到的類別或函式。對於許多應用程式來說，這種行為是不可接受的，因為它讓拆封器能夠引入並執行任意程式碼。請參見以下 pickle 資料流在載入時的行為：:

@example
>>> import pickle
>>> pickle.loads(b"cos\nsystem\n(S'echo hello world'\ntR.")
hello world
0
@end example

在這個例子中，拆封器會引入 @ref{1652,,os.system()} 函式，然後執行命令「echo hello world」。雖然這個例子是無害的，但不難想像可以這個方式輕易執行任意可能對系統造成損害的命令。

基於以上原因，你可能會希望透過自訂 @ref{2bcc,,Unpickler.find_class()} 來控制哪些是能夠被拆封的內容。與其名稱字面意義暗示的不同，實際上每當你請求一個全域物件（例如，類別或函式）時，就會呼叫 @ref{2bcc,,Unpickler.find_class()}。因此，可以透過這個方法完全禁止全域物件或將其限制在安全的子集合。

以下是一個僅允許從 @ref{13,,builtins} 模組中載入少數安全類別的拆封器（unpickler）的例子：:

@example
import builtins
import io
import pickle

safe_builtins = @{
    'range',
    'complex',
    'set',
    'frozenset',
    'slice',
@}

class RestrictedUnpickler(pickle.Unpickler):

    def find_class(self, module, name):
        # 只允許幾個內建的安全類別
        if module == "builtins" and name in safe_builtins:
            return getattr(builtins, name)
        # 完全禁止任何其他類別
        raise pickle.UnpicklingError("global '%s.%s' is forbidden" %
                                     (module, name))

def restricted_loads(s):
    """一個模擬 pickle.loads() 的輔助函式"""
    return RestrictedUnpickler(io.BytesIO(s)).load()
@end example

我們剛才實作的的拆封器範例正常運作的樣子：:

@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()).

正如我們的範例所示，必須謹慎審視能被拆封的內容。因此，如果你的應用場景非常關心安全性，你可能需要考慮其他選擇，例如 @ref{134,,xmlrpc.client} 中的 marshalling API 或其他第三方解決方案。

@node 效能<2>,範例<10>,限制全域物件,pickle --- Python 物件序列化
@anchor{library/pickle performance}@anchor{2bdd}
@subsubsection 效能


較近期的 pickle 協定版本（從 2 版協定開始）為多種常見功能和內建型別提供了高效率的二進位編碼。此外，@ref{ab,,pickle} 模組還具備一個透明化的、以 C 語言編寫的最佳化工具。

@node 範例<10>,命令列介面,效能<2>,pickle --- Python 物件序列化
@anchor{library/pickle examples}@anchor{2bde}@anchor{library/pickle pickle-example}@anchor{2bdf}
@subsubsection 範例


最簡單的使用方式，呼叫 @ref{2bbf,,dump()} 和 @ref{f07,,load()} 函式。:

@example
import pickle

# 任意 pickle 支援的物件。
data = @{
    'a': [1, 2.0, 3+4j],
    'b': ("string", b"byte string"),
    'c': @{None, True, False@}
@}

with open('data.pickle', 'wb') as f:
    # 使用可用的最高協定來封裝 'data' 字典。
    pickle.dump(data, f, pickle.HIGHEST_PROTOCOL)
@end example

以下範例可以讀取前述程式所封裝的 pickle 資料。:

@example
import pickle

with open('data.pickle', 'rb') as f:
    # 會自動檢測資料使用的協定版本，因此我們不需要手動指定。
    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 命令列介面,,範例<10>,pickle --- Python 物件序列化
@anchor{library/pickle command-line-interface}@anchor{2be0}@anchor{library/pickle pickle-cli}@anchor{2be1}
@subsubsection 命令列介面


The @ref{ab,,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{2be2,,pickletools CLI usage}.

@example
python -m pickle pickle_file [pickle_file ...]
@end example

接受以下選項：

@geindex pickle 命令列選項; pickle_file
@anchor{library/pickle cmdoption-pickle-arg-pickle_file}@anchor{2be3}
@deffn {Option} pickle_file

A pickle file to read, or @code{-} to indicate reading from standard input.
@end deffn


@subsubheading 也參考



@table @asis

@item @ref{2a,,copyreg} 模組

註冊擴充型別的 Pickle 介面建構子。

@item @ref{ac,,pickletools} 模組

用於分析或處裡被封裝資料的工具。

@item @ref{c8,,shelve} 模組

索引式資料庫；使用 @ref{ab,,pickle} 實作。

@item @ref{29,,copy} 模組

物件的淺層或深度拷貝。

@item @ref{91,,marshal} 模組

內建型別的高效能序列化。
@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 copyreg --- 註冊 pickle 支援函式,shelve --- Python object persistence,pickle --- Python 物件序列化,資料持久性 Data Persistence
@anchor{library/copyreg doc}@anchor{2be4}@anchor{library/copyreg copyreg-register-pickle-support-functions}@anchor{2be5}@anchor{library/copyreg module-copyreg}@anchor{2a}@anchor{library/copyreg translation-repo}@anchor{2be6}
@subsection @code{copyreg} --- 註冊 @code{pickle} 支援函式


@geindex module; copyreg

`原始碼：'Lib/copyreg.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/copyreg.py}

@geindex module（模組）;pickle
@geindex module（模組）;copy（複製）


__________________________________________________________________


@ref{2a,,copyreg} 模組提供了一種用以定義在 pickle 特定物件時使用之函式的方式。@ref{ab,,pickle} 和 @ref{29,,copy} 模組在 pickle/copy 這些物件時使用這些函式。此模組提供有關非類別物件之建構函式的配置資訊。此類建構函式可以是工廠函式 (factory function) 或類別實例。

@geindex constructor() (於 copyreg 模組中)
@anchor{library/copyreg copyreg constructor}@anchor{2be7}
@deffn {函式} copyreg.constructor (object)

宣告 `object' 是一個有效的建構函式。如果 `object' 不可呼叫（因此不可作為有效的建構函式），則會引發 @ref{198,,TypeError}。
@end deffn

@geindex pickle() (於 copyreg 模組中)
@anchor{library/copyreg copyreg pickle}@anchor{2bc5}
@deffn {函式} copyreg.pickle (type, function, constructor_ob=None)

宣告 `function' 應該用作 `type' 型別之物件的「歸約 ("reduction")」函式。`function' 必須回傳字串或包含 2 到 6 個元素的元組。有關 `function' 介面的更多詳細資訊，請參閱 @ref{1323,,dispatch_table}。

`constructor_ob' 參數是一個遺留功能，現在已被忽略，但如果要傳遞它的話則必須是個可呼叫物件。

請注意，pickler 物件或 @ref{c0a,,pickle.Pickler} 子類別的 @ref{1323,,dispatch_table} 屬性也可用於宣告歸約函式。
@end deffn

@menu
* 範例: 範例<11>. 

@end menu

@node 範例<11>,,,copyreg --- 註冊 pickle 支援函式
@anchor{library/copyreg example}@anchor{2be8}
@subsubsection 範例


下面範例展示如何註冊一個 pickle 函式以及如何使用它：

@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 --- 內部 Python 物件序列化,copyreg --- 註冊 pickle 支援函式,資料持久性 Data Persistence
@anchor{library/shelve doc}@anchor{2be9}@anchor{library/shelve module-shelve}@anchor{c8}@anchor{library/shelve shelve-python-object-persistence}@anchor{2bea}@anchor{library/shelve translation-repo}@anchor{2beb}
@subsection @code{shelve} --- Python object persistence


@geindex module; shelve

`原始碼：'Lib/shelve.py@footnote{https://github.com/python/cpython/tree/3.14/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{19c3}
@deffn {函式} shelve.open (filename, flag='c', protocol=None, writeback=False)

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{1127,,dbm.open()}.

By default, pickles created with @ref{a28,,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{2bec,,範例}).  If the
optional `writeback' parameter is set to @code{True}, all entries accessed are also
cached in memory, and written back on @ref{2bed,,sync()} and
@ref{2bee,,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).


在 3.10 版的變更: @ref{a28,,pickle.DEFAULT_PROTOCOL} is now used as the default pickle
protocol.



在 3.11 版的變更: Accepts @ref{59b,,path-like object} for filename.


@cartouche
@quotation 備註 
Do not rely on the shelf being closed automatically; always call
@ref{2bee,,close()} explicitly when you don't need it any more, or
use @ref{19c3,,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{2bef}
@cartouche
@quotation 警告 
Because the @ref{c8,,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 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{2bed}
@deffn {方法} Shelf.sync ()

Write back all entries in the cache if the shelf was opened with `writeback'
set to @ref{e02,,True}.  Also empty the cache and synchronize the persistent
dictionary on disk, if feasible.  This is called automatically when the shelf
is closed with @ref{2bee,,close()}.
@end deffn

@geindex close() (shelve.Shelf 的方法)
@anchor{library/shelve shelve Shelf close}@anchor{2bee}
@deffn {方法} Shelf.close ()

Synchronize and close the persistent `dict' object.  Operations on a closed
shelf will fail with a @ref{2eb,,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:: 
* 範例: 範例<12>. 

@end menu

@node Restrictions,範例<12>,,shelve --- Python object persistence
@anchor{library/shelve restrictions}@anchor{2bf0}
@subsubsection Restrictions


@geindex module（模組）;dbm.ndbm
@geindex module（模組）;dbm.gnu


@itemize *

@item 
The choice of which database package will be used (such as @ref{38,,dbm.ndbm} or
@ref{37,,dbm.gnu}) depends on which interface is available.  Therefore it is not
safe to open the database directly using @ref{35,,dbm}.  The database is also
(unfortunately) subject to the limitations of @ref{35,,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 @ref{c8,,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{38,,dbm.ndbm} can silently corrupt the database file on updates,
which can cause hard crashes when trying to read from the database.
@end itemize

@geindex Shelf (shelve 中的類別)
@anchor{library/shelve shelve Shelf}@anchor{1196}
@deffn {類別} shelve.Shelf (dict, protocol=None, writeback=False, keyencoding='utf-8')

A subclass of @ref{12ad,,collections.abc.MutableMapping} which stores pickled
values in the `dict' object.

By default, pickles created with @ref{a28,,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.

A @ref{1196,,Shelf} object can also be used as a context manager, in which
case it will be automatically closed when the @ref{186,,with} block ends.


在 3.2 版的變更: Added the `keyencoding' parameter; previously, keys were always encoded in
UTF-8.



在 3.4 版的變更: 新增情境管理器的支援。



在 3.10 版的變更: @ref{a28,,pickle.DEFAULT_PROTOCOL} is now used as the default pickle
protocol.

@end deffn

@geindex BsdDbShelf (shelve 中的類別)
@anchor{library/shelve shelve BsdDbShelf}@anchor{2562}
@deffn {類別} shelve.BsdDbShelf (dict, protocol=None, writeback=False, keyencoding='utf-8')

A subclass of @ref{1196,,Shelf} which exposes @code{first()}, @code{next()},
@code{previous()}, @code{last()} and @code{set_location()} methods.
These are available
in the third-party @code{bsddb} module from pybsddb@footnote{https://www.jcea.es/programacion/pybsddb.htm} but not in other database
modules.  The `dict' object passed to the constructor must support those
methods.  This is generally accomplished by calling one of
@code{bsddb.hashopen()}, @code{bsddb.btopen()} or @code{bsddb.rnopen()}.  The
optional `protocol', `writeback', and `keyencoding' parameters have the same
interpretation as for the @ref{1196,,Shelf} class.
@end deffn

@geindex DbfilenameShelf (shelve 中的類別)
@anchor{library/shelve shelve DbfilenameShelf}@anchor{2563}
@deffn {類別} shelve.DbfilenameShelf (filename, flag='c', protocol=None, writeback=False)

A subclass of @ref{1196,,Shelf} which accepts a `filename' instead of a dict-like
object.  The underlying file will be opened using @ref{1127,,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{19c3,,open()}
function.  The optional `protocol' and `writeback' parameters have the same
interpretation as for the @ref{1196,,Shelf} class.
@end deffn

@node 範例<12>,,Restrictions,shelve --- Python object persistence
@anchor{library/shelve example}@anchor{2bf1}@anchor{library/shelve shelve-example}@anchor{2bec}
@subsubsection 範例


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


@subsubheading 也參考



@table @asis

@item @ref{35,,dbm} 模組

Generic interface to @code{dbm}-style databases.

@item @ref{ab,,pickle} 模組

Object serialization used by @ref{c8,,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 --- 內部 Python 物件序列化,dbm --- Unix "databases" 的介面,shelve --- Python object persistence,資料持久性 Data Persistence
@anchor{library/marshal doc}@anchor{2bf2}@anchor{library/marshal marshal-internal-python-object-serialization}@anchor{2bf3}@anchor{library/marshal module-marshal}@anchor{91}@anchor{library/marshal translation-repo}@anchor{2bf4}
@subsection @code{marshal} --- 內部 Python 物件序列化


@geindex module; marshal


__________________________________________________________________


此模組包含一個能以二進位制格式來讀寫 Python 值的函式。這種格式是 Python 專屬但獨立於機器架構的（例如，你可以在一臺 PC 上寫入某個 Python 值，再將檔案傳到一臺 Mac 上並在那裡讀取它）。這種格式的細節是有意地不在文件上說明的；它可能在不同 Python 版本中被改變（雖然這種情況極少發生）。@footnote{
此模組的名稱來源於 Modula-3 (及其他語言) 的設計者所使用的術語，他們使用 "marshal" 來表示自包含 (self-contained) 形式資料的傳輸。嚴格來說，將資料從內部形式轉換為外部形式 (例如用於 RPC 緩衝區) 稱為 "marshal"，而其反向過程則稱為 "unmarshal"。
}

@geindex module（模組）;pickle
@geindex module（模組）;shelve

這不是一個通用「持久性 (persistence)」模組。關於通用持久性以及透過 RPC 呼叫傳遞 Python 物件，請參閱 @ref{ab,,pickle} 和 @ref{c8,,shelve} 等模組。@ref{91,,marshal} 模組主要是為了支援用來讀寫 @code{.pyc} 檔案之 Python 模組的「偽編譯 (pseudo-compiled)」程式碼。因此，Python 維護者保留了在必要時以不向後相容的方式修改 marshal 格式的權利。程式碼物件的格式在不同 Python 版本間是不相容的，即使格式版本相同。在不正確的 Python 版本中反序列化程式碼物件會有未定義的行為。如果你要序列化和反序列化 Python 物件，請改用 @ref{ab,,pickle} 模組 -- 其執行效率相當、有保證版本獨立性，且實質上 pickle 還支援比 marshal 更多樣的物件。

@cartouche
@quotation 警告 
@ref{91,,marshal} 模組對於錯誤或惡意構建的資料來說是不安全的。永遠不要 unmarshal 來自不受信任的或來源未經驗證的資料。
@end quotation
@end cartouche

有些函式可以讀/寫檔案，還有些函式可以操作類位元組串物件 (bytes-like object)。

@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{19b,,int}, @ref{3c1,,bool}, @ref{196,,float}, @ref{197,,complex}.

@item 
Strings (@ref{169,,str}) and @ref{192,,bytes}.
@ref{193,,Bytes-like objects} like @ref{343,,bytearray} are
marshalled as @code{bytes}.

@item 
Containers: @ref{60c,,tuple}, @ref{24d,,list}, @ref{184,,set}, @ref{7eb,,frozenset},
and (since @ref{2bf5,,version} 5), @ref{68d,,slice}.
It should be understood that these are supported only if the values contained
therein are themselves supported.
Recursive containers are supported since @ref{2bf5,,version} 3.

@item 
The singletons @ref{87e,,None}, @ref{21dd,,Ellipsis} and @ref{df0,,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.


這個模組定義了以下函式：

@geindex dump() (於 marshal 模組中)
@anchor{library/marshal marshal dump}@anchor{2bf6}
@deffn {函式} marshal.dump (value, file, version=version, /, *, allow_code=True)

將值寫入被開啟的檔案。值必須為受支援的型別，檔案必須為可寫入的 @ref{1f35,,binary file}。

如果值具有（或其所包含的物件具有）不支援的型別，則會引發 @ref{2eb,,ValueError} 例外 --- 但是垃圾資料 (garbage data) 也將寫入檔案，物件也無法正確地透過 @ref{1cbe,,load()} 重新讀取。@ref{4e1,,程式碼物件}只有在 `allow_code' 為 true 時才會支援。

`version' 引數指明 @code{dump} 應該使用的資料格式（見下文）。

引發一個附帶引數 @code{value} 與 @code{version} 的@ref{1b70,,稽核事件 (auditing event)} @code{marshal.dumps}。


在 3.13 版的變更: 新增 `allow_code' 參數。

@end deffn

@geindex load() (於 marshal 模組中)
@anchor{library/marshal marshal load}@anchor{1cbe}
@deffn {函式} marshal.load (file, /, *, allow_code=True)

從開啟的檔案讀取一個值並回傳。如果讀不到有效的值（例如，由於資料為不同 Python 版本的不相容 marshal 格式），則會引發 @ref{14da,,EOFError}、@ref{2eb,,ValueError} 或 @ref{198,,TypeError}。@ref{4e1,,程式碼物件}只有在 `allow_code' 為 true 時才會支援。檔案必須為可讀取的 @ref{1f35,,binary file}。

引發一個沒有附帶引數的@ref{1b70,,稽核事件} @code{marshal.load}。

@cartouche
@quotation 備註 
如果透過 @ref{2bf6,,dump()} marshal 了一個包含不支援型別的物件，@ref{1cbe,,load()} 會將不可 marshal 的型別替換為 @code{None}。
@end quotation
@end cartouche


在 3.10 版的變更: 使用此呼叫為每個程式碼物件引發一個 @code{code.__new__} 稽核事件。現在它會為整個載入操作引發單個 @code{marshal.load} 事件。



在 3.13 版的變更: 新增 `allow_code' 參數。

@end deffn

@geindex dumps() (於 marshal 模組中)
@anchor{library/marshal marshal dumps}@anchor{10a0}
@deffn {函式} marshal.dumps (value, version=version, /, *, allow_code=True)

回傳將透過 @code{dump(value, file)} 來被寫入一個檔案的位元組串物件，其值必須是有支援的型別，如果值（或其包含的任一物件）為不支援的型別則會引發 @ref{2eb,,ValueError}。@ref{4e1,,程式碼物件}只有在 `allow_code' 為 true 時才會支援。

`version' 引數指明 @code{dumps} 應當使用的資料型別（見下文）。

引發一個附帶引數 @code{value} 與 @code{version} 的@ref{1b70,,稽核事件 (auditing event)} @code{marshal.dumps}。


在 3.13 版的變更: 新增 `allow_code' 參數。

@end deffn

@geindex loads() (於 marshal 模組中)
@anchor{library/marshal marshal loads}@anchor{2bf7}
@deffn {函式} marshal.loads (bytes, /, *, allow_code=True)

將 @ref{193,,bytes-like object} 轉換為一個值。如果找不到有效的值，則會引發 @ref{14da,,EOFError}、@ref{2eb,,ValueError} 或 @ref{198,,TypeError}。@ref{4e1,,程式碼物件}只有在 `allow_code' 為 true 時才會支援。輸入中額外的位元組串會被忽略。

引發一個附帶引數 @code{bytes} 的@ref{1b70,,稽核事件} @code{marshal.loads}。


在 3.10 版的變更: 使用此呼叫為每個程式碼物件引發一個 @code{code.__new__} 稽核事件。現在它會為整個載入操作引發單個 @code{marshal.loads} 事件。



在 3.13 版的變更: 新增 `allow_code' 參數。

@end deffn

此外，還定義了以下常數：

@geindex version (於 marshal 模組中)
@anchor{library/marshal marshal version}@anchor{2bf5}
@deffn {資料} marshal.version

表示模組所使用的格式。第 0 版為歷史上第一版本；後續版本會新增功能。當引入新版本時，它通常會成為預設版本。


@multitable {xxxxxxxxx} {xxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

版本

@tab

Available since

@tab

New features

@item

1

@tab

Python 2.4

@tab

共享駐留字串

@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{68d,,slice} objects

@end multitable

@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 dbm --- Unix "databases" 的介面,sqlite3 --- SQLite 資料庫的 DB-API 2 0 介面,marshal --- 內部 Python 物件序列化,資料持久性 Data Persistence
@anchor{library/dbm doc}@anchor{2bf8}@anchor{library/dbm dbm-interfaces-to-unix-databases}@anchor{2bf9}@anchor{library/dbm module-dbm}@anchor{35}@anchor{library/dbm translation-repo}@anchor{2bfa}
@subsection @code{dbm} --- Unix "databases" 的介面


@geindex module; dbm

`原始碼：'Lib/dbm/__init__.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/dbm/__init__.py}


__________________________________________________________________


@ref{35,,dbm} is a generic interface to variants of the DBM database:


@itemize *

@item 
@ref{39,,dbm.sqlite3}

@item 
@ref{37,,dbm.gnu}

@item 
@ref{38,,dbm.ndbm}
@end itemize

If none of these modules are installed, the
slow-but-simple implementation in module @ref{36,,dbm.dumb} will be used.  There
is a third party interface@footnote{https://www.jcea.es/programacion/pybsddb.htm} to
the Oracle Berkeley DB.

@geindex error
@anchor{library/dbm dbm error}@anchor{2bfb}
@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{2bfb,,dbm.error} as the first
item --- the latter is used when @ref{2bfb,,dbm.error} is raised.
@end deffn

@geindex whichdb() (於 dbm 模組中)
@anchor{library/dbm dbm whichdb}@anchor{2bfc}
@deffn {函式} dbm.whichdb (filename)

This function attempts to guess which of the several simple database modules
available --- @ref{39,,dbm.sqlite3}, @ref{37,,dbm.gnu}, @ref{38,,dbm.ndbm},
or @ref{36,,dbm.dumb} --- should be used to open a given file.

回傳以下其中一個值：


@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{59b,,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{1127}
@deffn {函式} dbm.open (file, flag='r', mode=0o666)

Open a database and return the corresponding database object.

@*參數: 

@itemize *

@item 
@code{file} (@ref{59b,,path-like object}) -- 
要打開的資料庫檔案

If the database file already exists, the @ref{2bfc,,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{169,,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{19b,,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' 接受一個@ref{59b,,類路徑物件}。

@end deffn

The object returned by @ref{1127,,open()} supports the basic
functionality of mutable @ref{13bc,,mappings};
keys and their corresponding values can be stored, retrieved, and
deleted, and iteration, the @ref{349,,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{192,,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{186,,with} statement, which
will automatically close them when done.


在 3.2 版的變更: @code{get()} and @code{setdefault()} methods are now available for all
@ref{35,,dbm} backends.



在 3.4 版的變更: Added native support for the context management protocol to the objects
returned by @ref{1127,,open()}.



在 3.8 版的變更: Deleting a key from a read-only database raises a database module specific exception
instead of @ref{5df,,KeyError}.



在 3.13 版的變更: @code{clear()} 方法現在可用於所有 @ref{35,,dbm} 後端。


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 @ref{c8,,shelve} 模組

Persistence module which stores non-string data.
@end table


The individual submodules are described in the following sections.

@menu
* dbm.sqlite3: dbm sqlite3 --- dbm 的 SQLite 後端. dbm 的 SQLite 後端
* dbm.gnu: dbm gnu --- GNU 資料庫管理器. GNU 資料庫管理器
* dbm.ndbm: dbm ndbm --- 新資料庫管理器. 新資料庫管理器
* dbm.dumb: dbm dumb --- 可攜式 DBM 實作. 可攜式 DBM 實作

@end menu

@node dbm sqlite3 --- dbm 的 SQLite 後端,dbm gnu --- GNU 資料庫管理器,,dbm --- Unix "databases" 的介面
@anchor{library/dbm dbm-sqlite3-sqlite-backend-for-dbm}@anchor{2bfd}@anchor{library/dbm module-dbm sqlite3}@anchor{39}
@subsubsection @code{dbm.sqlite3} --- dbm 的 SQLite 後端


@geindex module; dbm.sqlite3


在 3.13 版被加入.


`原始碼：'Lib/dbm/sqlite3.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/dbm/sqlite3.py}


__________________________________________________________________


This module uses the standard library @ref{d4,,sqlite3} module to provide an
SQLite backend for the @ref{35,,dbm} module.
The files created by @ref{39,,dbm.sqlite3} can thus be opened by @ref{d4,,sqlite3},
or any other SQLite browser, including the SQLite CLI.

@c include for modules that don't work on WASM

@ref{2006,,可用性}: not WASI.

此模組在 WebAssembly 平台上不起作用或無法使用。更多資訊請參閱 @ref{1a99,,WebAssembly 平台}。

@geindex open() (於 dbm.sqlite3 模組中)
@anchor{library/dbm dbm sqlite3 open}@anchor{2bfe}
@deffn {函式} dbm.sqlite3.open (filename, /, flag='r', mode=0o666)

打開一個 SQLite 資料庫。

@*參數: 

@itemize *

@item 
@code{filename} (@ref{59b,,path-like object}) -- 要打開的資料庫路徑

@item 
@code{flag} (@ref{169,,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{13bc,,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{186,,with} keyword.

也提供了以下方法：

@geindex close() (dbm.sqlite3.sqlite3 的方法)
@anchor{library/dbm dbm sqlite3 sqlite3 close}@anchor{2bff}
@deffn {方法} sqlite3.close ()

關閉 SQLite 資料庫。
@end deffn
@end deffn

@node dbm gnu --- GNU 資料庫管理器,dbm ndbm --- 新資料庫管理器,dbm sqlite3 --- dbm 的 SQLite 後端,dbm --- Unix "databases" 的介面
@anchor{library/dbm dbm-gnu-gnu-database-manager}@anchor{2c00}@anchor{library/dbm module-dbm gnu}@anchor{37}
@subsubsection @code{dbm.gnu} --- GNU 資料庫管理器


@geindex module; dbm.gnu

`原始碼：'Lib/dbm/gnu.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/dbm/gnu.py}


__________________________________________________________________


The @ref{37,,dbm.gnu} module provides an interface to the @abbr{GDBM,GNU dbm}
library, similar to the @ref{38,,dbm.ndbm} module, but with additional
functionality like crash tolerance.

@cartouche
@quotation 備註 
The file formats created by @ref{37,,dbm.gnu} and @ref{38,,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{2006,,可用性}: not Android, not iOS, not WASI.

此模組在@ref{2120,,行動平台}或@ref{1a99,,WebAssembly 平台}上不支援。

@geindex error
@anchor{library/dbm dbm gnu error}@anchor{c88}
@deffn {例外} dbm.gnu.error

Raised on @ref{37,,dbm.gnu}-specific errors, such as I/O errors. @ref{5df,,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{2c01}
@deffn {資料} dbm.gnu.open_flags

A string of characters the `flag' parameter of @ref{1ce8,,open()} supports.
@end deffn

@geindex open() (於 dbm.gnu 模組中)
@anchor{library/dbm dbm gnu open}@anchor{1ce8}
@deffn {函式} dbm.gnu.open (filename, flag='r', mode=0o666, /)

打開一個 GDBM 資料庫，並回傳一個 @code{gdbm} 物件。

@*參數: 

@itemize *

@item 
@code{filename} (@ref{59b,,path-like object}) -- 要打開的資料庫檔案

@item 
@code{flag} (@ref{169,,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'}: 不要鎖住資料庫。
@end itemize

Not all flags are valid for all versions of GDBM.
See the @ref{2c01,,open_flags} member for a list of supported flag characters.


@item 
@code{mode} (@ref{19b,,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{c88,,error} -- 如果一個無效的 `flag' 引數被傳入。



在 3.11 版的變更: `filename' accepts a @ref{59b,,path-like object}.


@code{gdbm} objects behave similar to mutable @ref{13bc,,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{186,,with} keyword.


在 3.2 版的變更: 新增了 @code{get()} 和 @code{setdefault()} 方法。



在 3.13 版的變更: 新增了 @code{clear()} 方法。


也提供了以下方法：

@geindex close() (dbm.gnu.gdbm 的方法)
@anchor{library/dbm dbm gnu gdbm close}@anchor{2c02}
@deffn {方法} gdbm.close ()

關閉 GDBM 資料庫。
@end deffn

@geindex firstkey() (dbm.gnu.gdbm 的方法)
@anchor{library/dbm dbm gnu gdbm firstkey}@anchor{2c03}
@deffn {方法} gdbm.firstkey ()

It's possible to loop over every key in the database using this method  and the
@ref{2c04,,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{2c04}
@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{2c05}
@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.
@end deffn

@geindex sync() (dbm.gnu.gdbm 的方法)
@anchor{library/dbm dbm gnu gdbm sync}@anchor{2c06}
@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 --- 新資料庫管理器,dbm dumb --- 可攜式 DBM 實作,dbm gnu --- GNU 資料庫管理器,dbm --- Unix "databases" 的介面
@anchor{library/dbm dbm-ndbm-new-database-manager}@anchor{2c07}@anchor{library/dbm module-dbm ndbm}@anchor{38}
@subsubsection @code{dbm.ndbm} --- 新資料庫管理器


@geindex module; dbm.ndbm

`原始碼：'Lib/dbm/ndbm.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/dbm/ndbm.py}


__________________________________________________________________


The @ref{38,,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{37,,dbm.gnu} and @ref{38,,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{2006,,可用性}: not Android, not iOS, not WASI.

此模組在@ref{2120,,行動平台}或@ref{1a99,,WebAssembly 平台}上不支援。

@geindex error
@anchor{library/dbm dbm ndbm error}@anchor{c89}
@deffn {例外} dbm.ndbm.error

Raised on @ref{38,,dbm.ndbm}-specific errors, such as I/O errors. @ref{5df,,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{2c08}
@deffn {資料} dbm.ndbm.library

Name of the NDBM implementation library used.
@end deffn

@geindex open() (於 dbm.ndbm 模組中)
@anchor{library/dbm dbm ndbm open}@anchor{1ce9}
@deffn {函式} dbm.ndbm.open (filename, flag='r', mode=0o666, /)

Open an NDBM database and return an @code{ndbm} object.

@*參數: 

@itemize *

@item 
@code{filename} (@ref{59b,,path-like object}) -- The basename of the database file
(without the @code{.dir} or @code{.pag} extensions).

@item 
@code{flag} (@ref{169,,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{19b,,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{59b,,path-like object} for filename.


@code{ndbm} objects behave similar to mutable @ref{13bc,,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{186,,with} keyword.


在 3.2 版的變更: 新增了 @code{get()} 和 @code{setdefault()} 方法。



在 3.13 版的變更: 新增了 @code{clear()} 方法。


也提供了以下方法：

@geindex close() (dbm.ndbm.ndbm 的方法)
@anchor{library/dbm dbm ndbm ndbm close}@anchor{2c09}
@deffn {方法} ndbm.close ()

關閉 NDBM 資料庫。
@end deffn
@end deffn

@node dbm dumb --- 可攜式 DBM 實作,,dbm ndbm --- 新資料庫管理器,dbm --- Unix "databases" 的介面
@anchor{library/dbm dbm-dumb-portable-dbm-implementation}@anchor{2c0a}@anchor{library/dbm module-dbm dumb}@anchor{36}
@subsubsection @code{dbm.dumb} --- 可攜式 DBM 實作


@geindex module; dbm.dumb

`原始碼：'Lib/dbm/dumb.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/dbm/dumb.py}

@geindex databases（資料庫）

@cartouche
@quotation 備註 
The @ref{36,,dbm.dumb} module is intended as a last resort fallback for the
@ref{35,,dbm} module when a more robust module is not available. The @ref{36,,dbm.dumb}
module is not written for speed and is not nearly as heavily used as the other
database modules.
@end quotation
@end cartouche


__________________________________________________________________


The @ref{36,,dbm.dumb} module provides a persistent @ref{183,,dict}-like
interface which is written entirely in Python.
Unlike other @ref{35,,dbm} backends, such as @ref{37,,dbm.gnu}, no
external library is required.

@code{dbm.dumb} 模組定義了以下項目：

@geindex error
@anchor{library/dbm dbm dumb error}@anchor{c87}
@deffn {例外} dbm.dumb.error

Raised on @ref{36,,dbm.dumb}-specific errors, such as I/O errors.  @ref{5df,,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{c84}
@deffn {函式} dbm.dumb.open (filename, flag='c', mode=0o666)

開啟一個 @code{dbm.dumb} 資料庫。

@*參數: 

@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{169,,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{19b,,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


在 3.5 版的變更: @ref{c84,,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{59b,,path-like object}.


The returned database object behaves similar to a mutable @ref{13bc,,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{186,,with} keyword.

也提供了以下方法：

@geindex close() (dbm.dumb.dumbdbm 的方法)
@anchor{library/dbm dbm dumb dumbdbm close}@anchor{2c0b}
@deffn {方法} dumbdbm.close ()

關閉資料庫。
@end deffn

@geindex sync() (dbm.dumb.dumbdbm 的方法)
@anchor{library/dbm dbm dumb dumbdbm sync}@anchor{2c0c}
@deffn {方法} dumbdbm.sync ()

Synchronize the on-disk directory and data files.  This method is called
by the @ref{2bed,,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 --- SQLite 資料庫的 DB-API 2 0 介面,,dbm --- Unix "databases" 的介面,資料持久性 Data Persistence
@anchor{library/sqlite3 doc}@anchor{2c0d}@anchor{library/sqlite3 module-sqlite3}@anchor{d4}@anchor{library/sqlite3 sqlite3-db-api-2-0-interface-for-sqlite-databases}@anchor{2c0e}@anchor{library/sqlite3 translation-repo}@anchor{2c0f}
@subsection @code{sqlite3} --- SQLite 資料庫的 DB-API 2.0 介面


@geindex module; sqlite3

`原始碼：'Lib/sqlite3/@footnote{https://github.com/python/cpython/tree/3.14/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{2c10}
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 SQLite 3.15.2 or newer.

此文件包含四個主要章節：


@itemize *

@item 
@ref{2c11,,教學} 教導如何使用 @code{sqlite3} 模組。

@item 
@ref{2c12,,Reference} 描述此模組定義的類別與函式。

@item 
@ref{2c13,,How-to guides} 詳細說明如何處理特定工作。

@item 
@ref{2c14,,解釋} 深入提供交易 (transaction) 控制的背景。
@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/} - 資料庫 API 規格 2.0

PEP 由 Marc-André Lemburg 撰寫。
@end table


@c We use the following practises for SQL code:
@c - UPPERCASE for keywords
@c - snake_case for schema
@c - single quotes for string literals
@c - singular for table names
@c - if needed, use double quotes for table and column names

@menu
* 教學:: 
* Reference:: 
* How-to guides:: 
* 解釋:: 

@end menu

@node 教學,Reference,,sqlite3 --- SQLite 資料庫的 DB-API 2 0 介面
@anchor{library/sqlite3 sqlite3-tutorial}@anchor{2c11}@anchor{library/sqlite3 tutorial}@anchor{2c15}
@subsubsection 教學


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{5a0,,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{548,,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{2c16,,con.cursor()} to create the @ref{2c17,,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{5aa,,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{5aa,,cur.execute(...)},
assign the result to @code{res},
and call @ref{2c18,,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{60c,,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{5aa,,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{2c19,,Transaction control} for details).
Call @ref{2c1a,,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{5aa,,cur.execute(...)} to
assign the result to @code{res},
and call @ref{2c1b,,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{24d,,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{5ab,,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{1f21,,string formatting}
to bind Python values to SQL statements,
to avoid SQL injection attacks@footnote{https://en.wikipedia.org/wiki/SQL_injection}
(see @ref{5ac,,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{60c,,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{549,,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{2c13,,How-to guides}：


@itemize *

@item 
@ref{5ac,,How to use placeholders to bind values in SQL queries}

@item 
@ref{2c1c,,How to adapt custom Python types to SQLite values}

@item 
@ref{2c1d,,How to convert SQLite values to custom Python types}

@item 
@ref{1a9b,,How to use the connection context manager}

@item 
@ref{2c1e,,How to create and use row factories}
@end itemize

@item 
@ref{2c14,,解釋} for in-depth background on transaction control.
@end itemize


@node Reference,How-to guides,教學,sqlite3 --- SQLite 資料庫的 DB-API 2 0 介面
@anchor{library/sqlite3 reference}@anchor{2c1f}@anchor{library/sqlite3 sqlite3-reference}@anchor{2c12}
@subsubsection Reference


@c We keep the old sqlite3-module-contents ref to prevent breaking links.
@anchor{library/sqlite3 sqlite3-module-contents}@anchor{2c20}
@menu
* Module functions:: 
* Module constants:: 
* Connection 物件:: 
* Cursor 物件:: 
* Row 物件:: 
* Blob 物件:: 
* PrepareProtocol 物件:: 
* 例外: 例外<6>. 
* SQLite and Python types:: 
* Default adapters and converters (deprecated): Default adapters and converters deprecated. 
* 命令列介面: 命令列介面<2>. 

@end menu

@node Module functions,Module constants,,Reference
@anchor{library/sqlite3 module-functions}@anchor{2c21}@anchor{library/sqlite3 sqlite3-module-functions}@anchor{2c22}
@subsubsection Module functions


@geindex connect() (於 sqlite3 模組中)
@anchor{library/sqlite3 sqlite3 connect}@anchor{5a0}
@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{59b,,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{196,,float}) -- How many seconds the connection should wait before raising
an @ref{1b54,,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{19b,,int}) -- Control whether and how data types not
@ref{2c23,,natively supported by SQLite}
are looked up to be converted to Python types,
using the converters registered with @ref{2c24,,register_converter()}.
Set it to any combination (using @code{|}, bitwise or) of
@ref{2c25,,PARSE_DECLTYPES} and @ref{2c26,,PARSE_COLNAMES}
to enable this.
Column names takes precedence over declared types if both flags are set.
By default (@code{0}), type detection is disabled.

@item 
@code{isolation_level} (@ref{169,,str}@code{ | }@code{None}) -- Control legacy transaction handling behaviour.
See @ref{2c27,,Connection.isolation_level} and
@ref{2c28,,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{6d6,,Connection.autocommit} is set to
@ref{2c29,,LEGACY_TRANSACTION_CONTROL} (the default).

@item 
@code{check_same_thread} (@ref{3c1,,bool}) -- If @code{True} (default), @ref{304,,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{885,,threadsafety} for more information.

@item 
@code{factory} (@ref{548,,Connection}) -- A custom subclass of @ref{548,,Connection} to create the connection with,
if not the default @ref{548,,Connection} class.

@item 
@code{cached_statements} (@ref{19b,,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{3c1,,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{2c2a,,How to work with SQLite URIs}.

@item 
@code{autocommit} (@ref{3c1,,bool}) -- Control 
@geindex Python Enhancement Proposals; PEP 249
PEP 249@footnote{https://peps.python.org/pep-0249/} transaction handling behaviour.
See @ref{6d6,,Connection.autocommit} and
@ref{6d7,,Transaction control via the autocommit attribute} for more information.
`autocommit' currently defaults to
@ref{2c29,,LEGACY_TRANSACTION_CONTROL}.
The default will change to @code{False} in a future Python release.
@end itemize


@*回傳型別: 
@ref{548,,Connection}


引發一個附帶引數 @code{database} 的@ref{1b70,,稽核事件} @code{sqlite3.connect}。

引發一個附帶引數 @code{connection_handle} 的@ref{1b70,,稽核事件} @code{sqlite3.connect/handle}。


在 3.4 版的變更: 新增 `uri' 參數。



在 3.7 版的變更: `database' can now also be a @ref{59b,,path-like object}, not only a string.



在 3.10 版的變更: 新增 @code{sqlite3.connect/handle} 稽核事件。



在 3.12 版的變更: 新增 `autocommit' 參數。



在 3.13 版的變更: Positional use of the parameters `timeout', `detect_types',
`isolation_level', `check_same_thread', `factory', `cached_statements',
and `uri' is deprecated.
They will become keyword-only parameters in Python 3.15.

@end deffn

@geindex complete_statement() (於 sqlite3 模組中)
@anchor{library/sqlite3 sqlite3 complete_statement}@anchor{2c2b}
@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.

範例：

@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{5aa,,execute()}.

See @code{runsource()} in Lib/sqlite3/__main__.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/sqlite3/__main__.py}
for real-world use.
@end deffn

@geindex enable_callback_tracebacks() (於 sqlite3 模組中)
@anchor{library/sqlite3 sqlite3 enable_callback_tracebacks}@anchor{2c2c}
@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{b2a,,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{502,,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{2c2d}
@deffn {函式} sqlite3.register_adapter (type, adapter, /)

Register an `adapter' @ref{2c2e,,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{2c23,,type that SQLite natively understands}.
@end deffn

@geindex register_converter() (於 sqlite3 模組中)
@anchor{library/sqlite3 sqlite3 register_converter}@anchor{2c24}
@deffn {函式} sqlite3.register_converter (typename, converter, /)

Register the `converter' @ref{2c2e,,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{192,,bytes} object and should return an object of the
desired Python type.
Consult the parameter `detect_types' of
@ref{5a0,,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 物件,Module functions,Reference
@anchor{library/sqlite3 module-constants}@anchor{2c2f}@anchor{library/sqlite3 sqlite3-module-constants}@anchor{2c30}
@subsubsection Module constants


@geindex LEGACY_TRANSACTION_CONTROL (於 sqlite3 模組中)
@anchor{library/sqlite3 sqlite3 LEGACY_TRANSACTION_CONTROL}@anchor{2c29}
@deffn {資料} sqlite3.LEGACY_TRANSACTION_CONTROL

Set @ref{6d6,,autocommit} to this constant to select
old style (pre-Python 3.12) transaction control behaviour.
See @ref{2c28,,Transaction control via the isolation_level attribute} for more information.
@end deffn

@geindex PARSE_DECLTYPES (於 sqlite3 模組中)
@anchor{library/sqlite3 sqlite3 PARSE_DECLTYPES}@anchor{2c25}
@deffn {資料} sqlite3.PARSE_DECLTYPES

Pass this flag value to the `detect_types' parameter of
@ref{5a0,,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{2c26,,PARSE_COLNAMES} using the @code{|}
(bitwise or) operator.

@cartouche
@quotation 備註 
Generated fields (for example @code{MAX(p)}) are returned as @ref{169,,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{2c26}
@deffn {資料} sqlite3.PARSE_COLNAMES

Pass this flag value to the `detect_types' parameter of
@ref{5a0,,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{2c25,,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{2c31}
@deffn {資料} sqlite3.SQLITE_OK
@anchor{library/sqlite3 sqlite3 SQLITE_DENY}@anchor{2c32}
@deffnx {資料} sqlite3.SQLITE_DENY
@anchor{library/sqlite3 sqlite3 SQLITE_IGNORE}@anchor{2c33}
@deffnx {資料} sqlite3.SQLITE_IGNORE

Flags that should be returned by the `authorizer_callback' @ref{2c2e,,callable}
passed to @ref{5a3,,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{2c34}
@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{2c35}
@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{302}
@deffn {資料} sqlite3.sqlite_version

Version number of the runtime SQLite library as a @ref{169,,string}.
@end deffn

@geindex sqlite_version_info (於 sqlite3 模組中)
@anchor{library/sqlite3 sqlite3 sqlite_version_info}@anchor{303}
@deffn {資料} sqlite3.sqlite_version_info

Version number of the runtime SQLite library as a @ref{60c,,tuple} of
@ref{19b,,integers}.
@end deffn

@geindex threadsafety (於 sqlite3 模組中)
@anchor{library/sqlite3 sqlite3 threadsafety}@anchor{885}
@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 執行緒模式

@tab

@geindex Python Enhancement Proposals; PEP 0249#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{2c36}@anchor{library/sqlite3 sqlite3 SQLITE_DBCONFIG_DEFENSIVE}@anchor{2c37}
@deffn {資料} sqlite3.SQLITE_DBCONFIG_DEFENSIVE
@anchor{library/sqlite3 sqlite3 SQLITE_DBCONFIG_DQS_DDL}@anchor{2c38}
@deffnx {資料} sqlite3.SQLITE_DBCONFIG_DQS_DDL
@anchor{library/sqlite3 sqlite3 SQLITE_DBCONFIG_DQS_DML}@anchor{2c39}
@deffnx {資料} sqlite3.SQLITE_DBCONFIG_DQS_DML
@anchor{library/sqlite3 sqlite3 SQLITE_DBCONFIG_ENABLE_FKEY}@anchor{2c3a}
@deffnx {資料} sqlite3.SQLITE_DBCONFIG_ENABLE_FKEY
@anchor{library/sqlite3 sqlite3 SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER}@anchor{2c3b}
@deffnx {資料} sqlite3.SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER
@anchor{library/sqlite3 sqlite3 SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION}@anchor{2c3c}
@deffnx {資料} sqlite3.SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION
@anchor{library/sqlite3 sqlite3 SQLITE_DBCONFIG_ENABLE_QPSG}@anchor{2c3d}
@deffnx {資料} sqlite3.SQLITE_DBCONFIG_ENABLE_QPSG
@anchor{library/sqlite3 sqlite3 SQLITE_DBCONFIG_ENABLE_TRIGGER}@anchor{2c3e}
@deffnx {資料} sqlite3.SQLITE_DBCONFIG_ENABLE_TRIGGER
@anchor{library/sqlite3 sqlite3 SQLITE_DBCONFIG_ENABLE_VIEW}@anchor{2c3f}
@deffnx {資料} sqlite3.SQLITE_DBCONFIG_ENABLE_VIEW
@anchor{library/sqlite3 sqlite3 SQLITE_DBCONFIG_LEGACY_ALTER_TABLE}@anchor{2c40}
@deffnx {資料} sqlite3.SQLITE_DBCONFIG_LEGACY_ALTER_TABLE
@anchor{library/sqlite3 sqlite3 SQLITE_DBCONFIG_LEGACY_FILE_FORMAT}@anchor{2c41}
@deffnx {資料} sqlite3.SQLITE_DBCONFIG_LEGACY_FILE_FORMAT
@anchor{library/sqlite3 sqlite3 SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE}@anchor{2c42}
@deffnx {資料} sqlite3.SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE
@anchor{library/sqlite3 sqlite3 SQLITE_DBCONFIG_RESET_DATABASE}@anchor{2c43}
@deffnx {資料} sqlite3.SQLITE_DBCONFIG_RESET_DATABASE
@anchor{library/sqlite3 sqlite3 SQLITE_DBCONFIG_TRIGGER_EQP}@anchor{2c44}
@deffnx {資料} sqlite3.SQLITE_DBCONFIG_TRIGGER_EQP
@anchor{library/sqlite3 sqlite3 SQLITE_DBCONFIG_TRUSTED_SCHEMA}@anchor{2c45}
@deffnx {資料} sqlite3.SQLITE_DBCONFIG_TRUSTED_SCHEMA
@anchor{library/sqlite3 sqlite3 SQLITE_DBCONFIG_WRITABLE_SCHEMA}@anchor{2c46}
@deffnx {資料} sqlite3.SQLITE_DBCONFIG_WRITABLE_SCHEMA

These constants are used for the @ref{6da,,Connection.setconfig()}
and @ref{6d9,,getconfig()} methods.

The availability of these constants varies depending on the version of SQLite
Python was compiled with.


在 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


Deprecated since version 3.12, removed in version 3.14: The @code{version} and @code{version_info} constants.


@node Connection 物件,Cursor 物件,Module constants,Reference
@anchor{library/sqlite3 connection-objects}@anchor{2c47}@anchor{library/sqlite3 sqlite3-connection-objects}@anchor{2c48}
@subsubsection Connection 物件


@geindex Connection (sqlite3 中的類別)
@anchor{library/sqlite3 sqlite3 Connection}@anchor{548}
@deffn {類別} sqlite3.Connection

Each open SQLite database is represented by a @code{Connection} object,
which is created using @ref{5a0,,sqlite3.connect()}.
Their main purpose is creating @ref{2c17,,Cursor} objects,
and @ref{2c19,,Transaction control}.


@subsubheading 也參考



@itemize *

@item 
@ref{2c49,,How to use connection shortcut methods}

@item 
@ref{1a9b,,How to use the connection context manager}
@end itemize



在 3.13 版的變更: A @ref{547,,ResourceWarning} is emitted if @ref{549,,close()} is not called before
a @code{Connection} object is deleted.


一個 SQLite 資料庫連線具有以下屬性和方法：

@geindex cursor() (sqlite3.Connection 的方法)
@anchor{library/sqlite3 sqlite3 Connection cursor}@anchor{2c16}
@deffn {方法} cursor (factory=Cursor)

Create and return a @ref{2c17,,Cursor} object.
The cursor method accepts a single optional parameter `factory'. If
supplied, this must be a @ref{2c2e,,callable} returning
an instance of @ref{2c17,,Cursor} or its subclasses.
@end deffn

@geindex blobopen() (sqlite3.Connection 的方法)
@anchor{library/sqlite3 sqlite3 Connection blobopen}@anchor{88a}
@deffn {方法} blobopen (table, column, rowid, /, *, readonly=False, name='main')

Open a @ref{88b,,Blob} handle to an existing
@abbr{BLOB,Binary Large OBject}.

@*參數: 

@itemize *

@item 
@code{table} (@ref{169,,str}) -- The name of the table where the blob is located.

@item 
@code{column} (@ref{169,,str}) -- The name of the column where the blob is located.

@item 
@code{rowid} (@ref{19b,,int}) -- The row id where the blob is located.

@item 
@code{readonly} (@ref{3c1,,bool}) -- Set to @code{True} if the blob should be opened without write
permissions.
Defaults to @code{False}.

@item 
@code{name} (@ref{169,,str}) -- The name of the database where the blob is located.
Defaults to @code{"main"}.
@end itemize


@*引發: 
@ref{1b54,,OperationalError} -- When trying to open a blob in a @code{WITHOUT ROWID} table.


@*回傳型別: 
@ref{88b,,Blob}


@cartouche
@quotation 備註 
The blob size cannot be changed using the @ref{88b,,Blob} class.
Use the SQL function @code{zeroblob} to create a blob with a fixed size.
@end quotation
@end cartouche


在 3.11 版被加入.

@end deffn

@geindex commit() (sqlite3.Connection 的方法)
@anchor{library/sqlite3 sqlite3 Connection commit}@anchor{2c1a}
@deffn {方法} commit ()

Commit any pending transaction to the database.
If @ref{6d6,,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{2c4a}
@deffn {方法} rollback ()

Roll back to the start of any pending transaction.
If @ref{6d6,,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{549}
@deffn {方法} close ()

Close the database connection.
If @ref{6d6,,autocommit} is @code{False},
any pending transaction is implicitly rolled back.
If @code{autocommit} is @code{True} or @ref{2c29,,LEGACY_TRANSACTION_CONTROL},
no implicit transaction control is executed.
Make sure to @ref{2c1a,,commit()} before closing
to avoid losing pending changes.
@end deffn

@geindex execute() (sqlite3.Connection 的方法)
@anchor{library/sqlite3 sqlite3 Connection execute}@anchor{2c4b}
@deffn {方法} execute (sql, parameters=(), /)

Create a new @ref{2c17,,Cursor} object and call
@ref{5aa,,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{2c4c}
@deffn {方法} executemany (sql, parameters, /)

Create a new @ref{2c17,,Cursor} object and call
@ref{5ab,,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{2c4d}
@deffn {方法} executescript (sql_script, /)

Create a new @ref{2c17,,Cursor} object and call
@ref{2c4e,,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{5a1}
@deffn {方法} create_function (name, narg, func, *, deterministic=False)

Create or remove a user-defined SQL function.

@*參數: 

@itemize *

@item 
@code{name} (@ref{169,,str}) -- The name of the SQL function.

@item 
@code{narg} (@ref{19b,,int}) -- The number of arguments the SQL function can accept.
If @code{-1}, it may take any number of arguments.

@item 
@code{func} (@ref{2c4f,,callback} | None) -- A @ref{2c2e,,callable} that is called when the SQL function is invoked.
The callable must return @ref{2c23,,a type natively supported by SQLite}.
Set to @code{None} to remove an existing SQL function.

@item 
@code{deterministic} (@ref{3c1,,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 版的變更: 新增 `deterministic' 參數。


範例：

@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


在 3.13 版的變更: Passing `name', `narg', and `func' as keyword arguments is deprecated.
These parameters will become positional-only in Python 3.15.

@end deffn

@geindex create_aggregate() (sqlite3.Connection 的方法)
@anchor{library/sqlite3 sqlite3 Connection create_aggregate}@anchor{5a2}
@deffn {方法} create_aggregate (name, n_arg, aggregate_class)

Create or remove a user-defined SQL aggregate function.

@*參數: 

@itemize *

@item 
@code{name} (@ref{169,,str}) -- The name of the SQL aggregate function.

@item 
@code{n_arg} (@ref{19b,,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{1be7,,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{2c23,,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


範例：

@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


在 3.13 版的變更: Passing `name', `n_arg', and `aggregate_class' as keyword arguments is deprecated.
These parameters will become positional-only in Python 3.15.

@end deffn

@geindex create_window_function() (sqlite3.Connection 的方法)
@anchor{library/sqlite3 sqlite3 Connection create_window_function}@anchor{889}
@deffn {方法} create_window_function (name, num_params, aggregate_class, /)

Create or remove a user-defined aggregate window function.

@*參數: 

@itemize *

@item 
@code{name} (@ref{169,,str}) -- The name of the SQL aggregate window function to create or remove.

@item 
@code{num_params} (@ref{19b,,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{1be7,,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{2c23,,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{2c50,,NotSupportedError} -- If used with a version of SQLite older than 3.25.0,
which does not support aggregate window functions.



在 3.11 版被加入.


範例：

@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{87f}
@deffn {方法} create_collation (name, callable, /)

Create a collation named `name' using the collating function `callable'.
`callable' is passed two @ref{169,,string} arguments,
and it should return an @ref{19b,,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{2c51}
@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{1b54,,OperationalError}.
@end deffn

@geindex set_authorizer() (sqlite3.Connection 的方法)
@anchor{library/sqlite3 sqlite3 Connection set_authorizer}@anchor{5a3}
@deffn {方法} set_authorizer (authorizer_callback)

Register @ref{2c2e,,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{2c31,,SQLITE_OK},
@ref{2c32,,SQLITE_DENY}, or @ref{2c33,,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.13 版的變更: Passing `authorizer_callback' as a keyword argument is deprecated.
The parameter will become positional-only in Python 3.15.

@end deffn

@geindex set_progress_handler() (sqlite3.Connection 的方法)
@anchor{library/sqlite3 sqlite3 Connection set_progress_handler}@anchor{5a4}
@deffn {方法} set_progress_handler (progress_handler, n)

Register @ref{2c2e,,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{2c52,,DatabaseError}
exception.


在 3.13 版的變更: Passing `progress_handler' as a keyword argument is deprecated.
The parameter will become positional-only in Python 3.15.

@end deffn

@geindex set_trace_callback() (sqlite3.Connection 的方法)
@anchor{library/sqlite3 sqlite3 Connection set_trace_callback}@anchor{5a5}
@deffn {方法} set_trace_callback (trace_callback)

Register @ref{2c2e,,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{169,,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{5aa,,Cursor.execute()} methods.  Other sources include the
@ref{2c19,,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{2c2c,,enable_callback_tracebacks()} to enable printing
tracebacks from exceptions raised in the trace callback.
@end quotation
@end cartouche


在 3.3 版被加入.



在 3.13 版的變更: Passing `trace_callback' as a keyword argument is deprecated.
The parameter will become positional-only in Python 3.15.

@end deffn

@geindex enable_load_extension() (sqlite3.Connection 的方法)
@anchor{library/sqlite3 sqlite3 Connection enable_load_extension}@anchor{a38}
@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{2023,,--enable-loadable-sqlite-extensions} option
to @code{configure}.
@end quotation
@end cartouche

引發一個附帶引數 @code{connection}、@code{enabled} 的@ref{1b70,,稽核事件} @code{sqlite3.enable_load_extension}。


在 3.2 版被加入.



在 3.10 版的變更: 加入 @code{sqlite3.enable_load_extension} 稽核事件。


@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{6d8}
@deffn {方法} load_extension (path, /, *, entrypoint=None)

Load an SQLite extension from a shared library.
Enable extension loading with @ref{a38,,enable_load_extension()} before
calling this method.

@*參數: 

@itemize *

@item 
@code{path} (@ref{169,,str}) -- The path to the SQLite extension.

@item 
@code{entrypoint} (@ref{169,,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


引發一個附帶引數 @code{connection}、@code{path} 的@ref{1b70,,稽核事件} @code{sqlite3.load_extension}。


在 3.2 版被加入.



在 3.10 版的變更: 加入 @code{sqlite3.load_extension} 稽核事件。



在 3.12 版的變更: 新增 `entrypoint' 參數。

@end deffn

@geindex iterdump() (sqlite3.Connection 的方法)
@anchor{library/sqlite3 sqlite3 Connection iterdump}@anchor{54a}
@deffn {方法} iterdump (*, filter=None)

Return an @ref{4c3,,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{169,,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
# 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{2c53,,如何處理非 UTF-8 的文字編碼}



在 3.13 版的變更: 新增 `filter' 參數。

@end deffn

@geindex backup() (sqlite3.Connection 的方法)
@anchor{library/sqlite3 sqlite3 Connection backup}@anchor{d6b}
@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{548,,Connection}) -- The database connection to save the backup to.

@item 
@code{pages} (@ref{19b,,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{2c4f,,callback} | None) -- If set to a @ref{2c2e,,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{169,,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{196,,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


在 3.7 版被加入.



@subsubheading 也參考


@ref{2c53,,如何處理非 UTF-8 的文字編碼}

@end deffn

@geindex getlimit() (sqlite3.Connection 的方法)
@anchor{library/sqlite3 sqlite3 Connection getlimit}@anchor{884}
@deffn {方法} getlimit (category, /)

Get a connection runtime limit.

@*參數: 
@code{category} (@ref{19b,,int}) -- The SQLite limit category@footnote{https://www.sqlite.org/c3ref/c_limit_attached.html} to be queried.


@*回傳型別: 
@ref{19b,,int}


@*引發: 
@ref{304,,ProgrammingError} -- If `category' is not recognised by the underlying SQLite library.


Example, query the maximum length of an SQL statement
for @ref{548,,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


在 3.11 版被加入.

@end deffn

@geindex setlimit() (sqlite3.Connection 的方法)
@anchor{library/sqlite3 sqlite3 Connection setlimit}@anchor{883}
@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{19b,,int}) -- The SQLite limit category@footnote{https://www.sqlite.org/c3ref/c_limit_attached.html} to be set.

@item 
@code{limit} (@ref{19b,,int}) -- The value of the new limit.
If negative, the current limit is unchanged.
@end itemize


@*回傳型別: 
@ref{19b,,int}


@*引發: 
@ref{304,,ProgrammingError} -- If `category' is not recognised by the underlying SQLite library.


Example, limit the number of attached databases to 1
for @ref{548,,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()


在 3.11 版被加入.

@end deffn

@geindex getconfig() (sqlite3.Connection 的方法)
@anchor{library/sqlite3 sqlite3 Connection getconfig}@anchor{6d9}
@deffn {方法} getconfig (op, /)

Query a boolean connection configuration option.

@*參數: 
@code{op} (@ref{19b,,int}) -- A @ref{2c36,,SQLITE_DBCONFIG code}.


@*回傳型別: 
@ref{3c1,,bool}



在 3.12 版被加入.

@end deffn

@geindex setconfig() (sqlite3.Connection 的方法)
@anchor{library/sqlite3 sqlite3 Connection setconfig}@anchor{6da}
@deffn {方法} setconfig (op, enable=True, /)

Set a boolean connection configuration option.

@*參數: 

@itemize *

@item 
@code{op} (@ref{19b,,int}) -- A @ref{2c36,,SQLITE_DBCONFIG code}.

@item 
@code{enable} (@ref{3c1,,bool}) -- @code{True} if the configuration option should be enabled (default);
@code{False} if it should be disabled.
@end itemize



在 3.12 版被加入.

@end deffn

@geindex serialize() (sqlite3.Connection 的方法)
@anchor{library/sqlite3 sqlite3 Connection serialize}@anchor{887}
@deffn {方法} serialize (*, name='main')

Serialize a database into a @ref{192,,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{169,,str}) -- The database name to be serialized.
Defaults to @code{"main"}.


@*回傳型別: 
@ref{192,,bytes}


@cartouche
@quotation 備註 
This method is only available if the underlying SQLite library has the
serialize API.
@end quotation
@end cartouche


在 3.11 版被加入.

@end deffn

@geindex deserialize() (sqlite3.Connection 的方法)
@anchor{library/sqlite3 sqlite3 Connection deserialize}@anchor{888}
@deffn {方法} deserialize (data, /, *, name='main')

Deserialize a @ref{887,,serialized} database into a
@ref{548,,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{192,,bytes}) -- A serialized database.

@item 
@code{name} (@ref{169,,str}) -- The database name to deserialize into.
Defaults to @code{"main"}.
@end itemize


@*引發: 

@itemize *

@item 
@ref{1b54,,OperationalError} -- If the database connection is currently involved in a read
transaction or a backup operation.

@item 
@ref{2c52,,DatabaseError} -- If `data' does not contain a valid SQLite database.

@item 
@ref{a78,,OverflowError} -- If @ref{839,,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


在 3.11 版被加入.

@end deffn

@geindex autocommit (sqlite3.Connection 的屬性)
@anchor{library/sqlite3 sqlite3 Connection autocommit}@anchor{6d6}
@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{2c1a,,commit()} and @ref{2c4a,,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{2c1a,,commit()} and @ref{2c4a,,rollback()} have no effect in this mode.

@item 
@ref{2c29,,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{2c27,,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.

更多詳情請見 @ref{6d7,,Transaction control via the autocommit attribute}。

@cartouche
@quotation 備註 
The @ref{2c27,,isolation_level} attribute has no effect unless
@ref{6d6,,autocommit} is @ref{2c29,,LEGACY_TRANSACTION_CONTROL}.
@end quotation
@end cartouche


在 3.12 版被加入.

@end deffn

@geindex in_transaction (sqlite3.Connection 的屬性)
@anchor{library/sqlite3 sqlite3 Connection in_transaction}@anchor{2c54}
@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.


在 3.2 版被加入.

@end deffn

@geindex isolation_level (sqlite3.Connection 的屬性)
@anchor{library/sqlite3 sqlite3 Connection isolation_level}@anchor{2c27}
@deffn {屬性} isolation_level

Controls the @ref{2c28,,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{2c28,,implicit transaction management} is performed.

If not overridden by the `isolation_level' parameter of @ref{5a0,,connect()},
the default is @code{""}, which is an alias for @code{"DEFERRED"}.

@cartouche
@quotation 備註 
Using @ref{6d6,,autocommit} to control transaction handling is
recommended over using @code{isolation_level}.
@code{isolation_level} has no effect unless @ref{6d6,,autocommit} is
set to @ref{2c29,,LEGACY_TRANSACTION_CONTROL} (the default).
@end quotation
@end cartouche
@end deffn

@geindex row_factory (sqlite3.Connection 的屬性)
@anchor{library/sqlite3 sqlite3 Connection row_factory}@anchor{18fc}
@deffn {屬性} row_factory

The initial @ref{2c55,,row_factory}
for @ref{2c17,,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{60c,,tuple}.

更多詳情請見 @ref{2c1e,,How to create and use row factories}。
@end deffn

@geindex text_factory (sqlite3.Connection 的屬性)
@anchor{library/sqlite3 sqlite3 Connection text_factory}@anchor{2c56}
@deffn {屬性} text_factory

A @ref{2c2e,,callable} that accepts a @ref{192,,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{169,,str}.

更多詳情請見 @ref{2c53,,如何處理非 UTF-8 的文字編碼}。
@end deffn

@geindex total_changes (sqlite3.Connection 的屬性)
@anchor{library/sqlite3 sqlite3 Connection total_changes}@anchor{2c57}
@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 物件,Row 物件,Connection 物件,Reference
@anchor{library/sqlite3 cursor-objects}@anchor{2c58}@anchor{library/sqlite3 sqlite3-cursor-objects}@anchor{2c59}
@subsubsection Cursor 物件


@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{2c16,,Connection.cursor()},
or by using any of the @ref{2c49,,connection shortcut methods}.

Cursor objects are @ref{4c3,,iterators},
meaning that if you @ref{5aa,,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{2c17}
@deffn {類別} sqlite3.Cursor

@ref{2c17,,Cursor} 實例具有以下屬性和方法。

@geindex ? （問號）;於 SQL 陳述式中

@geindex ; （冒號）;於 SQL 陳述式中

@geindex execute() (sqlite3.Cursor 的方法)
@anchor{library/sqlite3 sqlite3 Cursor execute}@anchor{5aa}
@deffn {方法} execute (sql, parameters=(), /)

Execute a single SQL statement,
optionally binding Python values using
@ref{5ac,,placeholders}.

@*參數: 

@itemize *

@item 
@code{sql} (@ref{169,,str}) -- 單一個 SQL 陳述式。

@item 
@code{parameters} (@ref{183,,dict} | @ref{70f,,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{5ac,,How to use placeholders to bind values in SQL queries}.
@end itemize


@*引發: 
@ref{304,,ProgrammingError} -- When `sql' contains more than one SQL statement.
When @ref{5ac,,named placeholders} are used
and `parameters' is a sequence instead of a @ref{183,,dict}.


If @ref{6d6,,autocommit} is
@ref{2c29,,LEGACY_TRANSACTION_CONTROL},
@ref{2c27,,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{304,,ProgrammingError} is emitted if
@ref{5ac,,named placeholders} are used
and `parameters' is a sequence instead of a @ref{183,,dict}.


Use @ref{2c4e,,executescript()} to execute multiple SQL statements.
@end deffn

@geindex executemany() (sqlite3.Cursor 的方法)
@anchor{library/sqlite3 sqlite3 Cursor executemany}@anchor{5ab}
@deffn {方法} executemany (sql, parameters, /)

For every item in `parameters',
repeatedly execute the @ref{5ac,,parameterized}
@abbr{DML,Data Manipulation Language} SQL statement `sql'.

Uses the same implicit transaction handling as @ref{5aa,,execute()}.

@*參數: 

@itemize *

@item 
@code{sql} (@ref{169,,str}) -- A single SQL DML statement.

@item 
@code{parameters} (@ref{1428,,iterable}) -- An iterable of parameters to bind with
the placeholders in `sql'.
See @ref{5ac,,How to use placeholders to bind values in SQL queries}.
@end itemize


@*引發: 
@ref{304,,ProgrammingError} -- When `sql' contains more than one SQL statement
or is not a DML statement,
When @ref{5ac,,named placeholders} are used
and the items in `parameters' are sequences instead of @ref{183,,dict}s.


範例：

@example
rows = [
    ("row1",),
    ("row2",),
]
# cur 是一個 sqlite3.Cursor 物件
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{304,,ProgrammingError} is emitted if
@ref{5ac,,named placeholders} are used
and the items in `parameters' are sequences
instead of @ref{183,,dict}s.

@end deffn

@geindex executescript() (sqlite3.Cursor 的方法)
@anchor{library/sqlite3 sqlite3 Cursor executescript}@anchor{2c4e}
@deffn {方法} executescript (sql_script, /)

Execute the SQL statements in `sql_script'.
If the @ref{6d6,,autocommit} is
@ref{2c29,,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' 必須是一個 @ref{169,,string}。

範例：

@example
# cur 是一個 sqlite3.Cursor 物件
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{2c18}
@deffn {方法} fetchone ()

If @ref{2c55,,row_factory} is @code{None},
return the next row query result set as a @ref{60c,,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{1749}
@deffn {方法} fetchmany (size=cursor.arraysize)

Return the next set of rows of a query result as a @ref{24d,,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{174a,,arraysize} determines the number of rows
to be fetched.
If fewer than `size' rows are available,
as many rows as are available are returned.

Note there are performance considerations involved with the `size' parameter.
For optimal performance, it is usually best to use the arraysize attribute.
If the `size' parameter is used, then it is best for it to retain the same
value from one @ref{1749,,fetchmany()} call to the next.


在 3.14.0 (unreleased) 版的變更: Negative `size' values are rejected by raising @ref{2eb,,ValueError}.

@end deffn

@geindex fetchall() (sqlite3.Cursor 的方法)
@anchor{library/sqlite3 sqlite3 Cursor fetchall}@anchor{2c1b}
@deffn {方法} fetchall ()

Return all (remaining) rows of a query result as a @ref{24d,,list}.
Return an empty list if no rows are available.
Note that the @ref{174a,,arraysize} attribute can affect the performance of
this operation.
@end deffn

@geindex close() (sqlite3.Cursor 的方法)
@anchor{library/sqlite3 sqlite3 Cursor close}@anchor{2c5a}
@deffn {方法} close ()

Close the cursor now (rather than whenever @code{__del__} is called).

The cursor will be unusable from this point forward; a @ref{304,,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{2c5b}
@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{2c5c}
@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{174a}
@deffn {屬性} arraysize

Read/write attribute that controls the number of rows returned by @ref{1749,,fetchmany()}.
The default value is 1 which means a single row would be fetched per call.


在 3.14.0 (unreleased) 版的變更: Negative values are rejected by raising @ref{2eb,,ValueError}.

@end deffn

@geindex connection (sqlite3.Cursor 的屬性)
@anchor{library/sqlite3 sqlite3 Cursor connection}@anchor{2c5d}
@deffn {屬性} connection

Read-only attribute that provides the SQLite database @ref{548,,Connection}
belonging to the cursor.  A @ref{2c17,,Cursor} object created by
calling @ref{2c16,,con.cursor()} will have a
@ref{2c5d,,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{1821}
@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{ec7}
@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{5aa,,execute()} method.  For other statements, after
@ref{5ab,,executemany()} or @ref{2c4e,,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 版的變更: 新增 @code{REPLACE} 陳述式的支援。

@end deffn

@geindex rowcount (sqlite3.Cursor 的屬性)
@anchor{library/sqlite3 sqlite3 Cursor rowcount}@anchor{1a8f}
@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{5aa,,execute()} and @ref{5ab,,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{2c55}
@deffn {屬性} row_factory

Control how a row fetched from this @code{Cursor} is represented.
If @code{None}, a row is represented as a @ref{60c,,tuple}.
Can be set to the included @ref{106c,,sqlite3.Row};
or a @ref{2c2e,,callable} that accepts two arguments,
a @ref{2c17,,Cursor} object and the @code{tuple} of row values,
and returns a custom object representing an SQLite row.

Defaults to what @ref{18fc,,Connection.row_factory} was set to
when the @code{Cursor} was created.
Assigning to this attribute does not affect
@ref{18fc,,Connection.row_factory} of the parent connection.

更多詳情請見 @ref{2c1e,,How to create and use row factories}。
@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{2c5e}
@node Row 物件,Blob 物件,Cursor 物件,Reference
@anchor{library/sqlite3 row-objects}@anchor{2c5f}@anchor{library/sqlite3 sqlite3-row-objects}@anchor{2c60}
@subsubsection Row 物件


@geindex Row (sqlite3 中的類別)
@anchor{library/sqlite3 sqlite3 Row}@anchor{106c}
@deffn {類別} sqlite3.Row

A @code{Row} instance serves as a highly optimized
@ref{18fc,,row_factory} for @ref{548,,Connection} objects.
It supports iteration, equality testing, @ref{839,,len()},
and @ref{13bc,,mapping} access by column name and index.

Two @code{Row} objects compare equal
if they have identical column names and values.

更多詳情請見 @ref{2c1e,,How to create and use row factories}。

@geindex keys() (sqlite3.Row 的方法)
@anchor{library/sqlite3 sqlite3 Row keys}@anchor{2c61}
@deffn {方法} keys ()

Return a @ref{24d,,list} of column names as @ref{169,,strings}.
Immediately after a query,
it is the first member of each tuple in @ref{1821,,Cursor.description}.
@end deffn


在 3.5 版的變更: 新增對切片的支援。

@end deffn

@node Blob 物件,PrepareProtocol 物件,Row 物件,Reference
@anchor{library/sqlite3 blob-objects}@anchor{2c62}@anchor{library/sqlite3 sqlite3-blob-objects}@anchor{2c63}
@subsubsection Blob 物件


@geindex Blob (sqlite3 中的類別)
@anchor{library/sqlite3 sqlite3 Blob}@anchor{88b}
@deffn {類別} sqlite3.Blob


在 3.11 版被加入.


A @ref{88b,,Blob} instance is a @ref{28ad,,file-like object}
that can read and write data in an SQLite @abbr{BLOB}.
Call @ref{839,,len(blob)} to get the size (number of bytes) of the blob.
Use indices and @ref{2489,,slices} for direct access to the blob data.

Use the @ref{88b,,Blob} as a @ref{1e1,,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{2c64}
@deffn {方法} close ()

Close the blob.

The blob will be unusable from this point onward.  An
@ref{1b37,,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{2c65}
@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, @ref{2c65,,read()} will read until the end of
the blob.
@end deffn

@geindex write() (sqlite3.Blob 的方法)
@anchor{library/sqlite3 sqlite3 Blob write}@anchor{2c66}
@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{2eb,,ValueError}.
@end deffn

@geindex tell() (sqlite3.Blob 的方法)
@anchor{library/sqlite3 sqlite3 Blob tell}@anchor{2c67}
@deffn {方法} tell ()

Return the current access position of the blob.
@end deffn

@geindex seek() (sqlite3.Blob 的方法)
@anchor{library/sqlite3 sqlite3 Blob seek}@anchor{2c68}
@deffn {方法} seek (offset, origin=os.SEEK_SET, /)

Set the current access position of the blob to `offset'.  The `origin'
argument defaults to @ref{148e,,os.SEEK_SET} (absolute blob positioning).
Other values for `origin' are @ref{148f,,os.SEEK_CUR} (seek relative to the
current position) and @ref{1490,,os.SEEK_END} (seek relative to the blob’s
end).
@end deffn
@end deffn

@node PrepareProtocol 物件,例外<6>,Blob 物件,Reference
@anchor{library/sqlite3 prepareprotocol-objects}@anchor{2c69}
@subsubsection PrepareProtocol 物件


@geindex PrepareProtocol (sqlite3 中的類別)
@anchor{library/sqlite3 sqlite3 PrepareProtocol}@anchor{1a9a}
@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{2c6a,,adapt themselves} to @ref{2c23,,native SQLite types}.
@end deffn

@node 例外<6>,SQLite and Python types,PrepareProtocol 物件,Reference
@anchor{library/sqlite3 exceptions}@anchor{2c6b}@anchor{library/sqlite3 sqlite3-exceptions}@anchor{2c6c}
@subsubsection 例外


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{1adc}
@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{bc4,,Exception}.
@end deffn

@geindex Error
@anchor{library/sqlite3 sqlite3 Error}@anchor{1b37}
@deffn {例外} sqlite3.Error

The base class of the other exceptions in this module.
Use this to catch all errors with one single @ref{1ab,,except} statement.
@code{Error} is a subclass of @ref{bc4,,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{881}
@deffn {屬性} sqlite_errorcode

The numeric error code from the
SQLite API@footnote{https://sqlite.org/rescode.html}


在 3.11 版被加入.

@end deffn

@geindex sqlite_errorname (sqlite3.Error 的屬性)
@anchor{library/sqlite3 sqlite3 Error sqlite_errorname}@anchor{882}
@deffn {屬性} sqlite_errorname

The symbolic name of the numeric error code
from the SQLite API@footnote{https://sqlite.org/rescode.html}


在 3.11 版被加入.

@end deffn
@end deffn

@geindex InterfaceError
@anchor{library/sqlite3 sqlite3 InterfaceError}@anchor{886}
@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{1b37,,Error}.
@end deffn

@geindex DatabaseError
@anchor{library/sqlite3 sqlite3 DatabaseError}@anchor{2c52}
@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{1b37,,Error}.
@end deffn

@geindex DataError
@anchor{library/sqlite3 sqlite3 DataError}@anchor{1b53}
@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{2c52,,DatabaseError}.
@end deffn

@geindex OperationalError
@anchor{library/sqlite3 sqlite3 OperationalError}@anchor{1b54}
@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{2c52,,DatabaseError}.
@end deffn

@geindex IntegrityError
@anchor{library/sqlite3 sqlite3 IntegrityError}@anchor{2c6d}
@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{2c52,,DatabaseError}.
@end deffn

@geindex InternalError
@anchor{library/sqlite3 sqlite3 InternalError}@anchor{2c6e}
@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{2c52,,DatabaseError}.
@end deffn

@geindex ProgrammingError
@anchor{library/sqlite3 sqlite3 ProgrammingError}@anchor{304}
@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{548,,Connection}.
@code{ProgrammingError} is a subclass of @ref{2c52,,DatabaseError}.
@end deffn

@geindex NotSupportedError
@anchor{library/sqlite3 sqlite3 NotSupportedError}@anchor{2c50}
@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{5a1,,create_function()}, if the underlying SQLite library
does not support deterministic functions.
@code{NotSupportedError} is a subclass of @ref{2c52,,DatabaseError}.
@end deffn

@node SQLite and Python types,Default adapters and converters deprecated,例外<6>,Reference
@anchor{library/sqlite3 sqlite-and-python-types}@anchor{2c6f}@anchor{library/sqlite3 sqlite3-types}@anchor{2c23}
@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{19b,,int}

@tab

@code{INTEGER}

@item

@ref{196,,float}

@tab

@code{REAL}

@item

@ref{169,,str}

@tab

@code{TEXT}

@item

@ref{192,,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{19b,,int}

@item

@code{REAL}

@tab

@ref{196,,float}

@item

@code{TEXT}

@tab

depends on @ref{2c56,,text_factory},
@ref{169,,str} by default

@item

@code{BLOB}

@tab

@ref{192,,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{2c1c,,object adapters},
and you can let the @code{sqlite3} module convert SQLite types to
Python types via @ref{2c1d,,converters}.

@node Default adapters and converters deprecated,命令列介面<2>,SQLite and Python types,Reference
@anchor{library/sqlite3 default-adapters-and-converters-deprecated}@anchor{2c70}@anchor{library/sqlite3 sqlite3-default-converters}@anchor{70d}
@subsubsection Default adapters and converters (deprecated)


@cartouche
@quotation 備註 
The default adapters and converters are deprecated as of Python 3.12.
Instead, use the @ref{70e,,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{1fa,,datetime.date} objects to @ref{169,,strings} in
ISO 8601@footnote{https://en.wikipedia.org/wiki/ISO_8601} format.

@item 
An adapter for @ref{4dd,,datetime.datetime} objects to strings in
ISO 8601 format.

@item 
A converter for @ref{2c1d,,declared} "date" types to
@ref{1fa,,datetime.date} objects.

@item 
A converter for declared "timestamp" types to
@ref{4dd,,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{4dd,,datetime.datetime} object. To preserve UTC
offsets in timestamps, either leave converters disabled, or register an
offset-aware converter with @ref{2c24,,register_converter()}.
@end quotation
@end cartouche


在 3.12 版之後被棄用.


@node 命令列介面<2>,,Default adapters and converters deprecated,Reference
@anchor{library/sqlite3 command-line-interface}@anchor{2c71}@anchor{library/sqlite3 sqlite3-cli}@anchor{66c}
@subsubsection 命令列介面


The @code{sqlite3} module can be invoked as a script,
using the interpreter's @ref{23c,,-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] 命令列選項; -h
@geindex python--m-sqlite3-[-h]-[-v]-[filename]-[sql] 命令列選項; --help
@anchor{library/sqlite3 cmdoption-python-m-sqlite3-h-v-filename-sql-h}@anchor{2c72}@anchor{library/sqlite3 cmdoption-python-m-sqlite3-h-v-filename-sql-help}@anchor{2c73}
@deffn {Option} @w{-}h, @w{-}@w{-}help

Print CLI help.
@end deffn

@geindex python--m-sqlite3-[-h]-[-v]-[filename]-[sql] 命令列選項; -v
@geindex python--m-sqlite3-[-h]-[-v]-[filename]-[sql] 命令列選項; --version
@anchor{library/sqlite3 cmdoption-python-m-sqlite3-h-v-filename-sql-v}@anchor{2c74}@anchor{library/sqlite3 cmdoption-python-m-sqlite3-h-v-filename-sql-version}@anchor{2c75}
@deffn {Option} @w{-}v, @w{-}@w{-}version

Print underlying SQLite library version.
@end deffn


在 3.12 版被加入.


@node How-to guides,解釋,Reference,sqlite3 --- SQLite 資料庫的 DB-API 2 0 介面
@anchor{library/sqlite3 how-to-guides}@anchor{2c76}@anchor{library/sqlite3 sqlite3-howtos}@anchor{2c13}
@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:: 
* 如何處理非 UTF-8 的文字編碼:: 

@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{2c77}@anchor{library/sqlite3 sqlite3-placeholders}@anchor{5ac}
@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
>>> # 千萬不要這樣做，這不安全！
>>> 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{60c,,tuple} of values to the second
argument of the cursor's @ref{5aa,,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{70f,,sequence} whose length must match the number of placeholders,
or a @ref{304,,ProgrammingError} is raised.
For the named style, `parameters' must be
an instance of a @ref{183,,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{2c78}@anchor{library/sqlite3 sqlite3-adapters}@anchor{2c1c}
@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{2c23,,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{2c79}@anchor{library/sqlite3 sqlite3-conform}@anchor{2c6a}
@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{1a9a,,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{2c7a}
@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{2c2d,,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{2c7b}@anchor{library/sqlite3 sqlite3-converters}@anchor{2c1d}
@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{192,,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{5a0,,connect()}. There are three options:


@itemize *

@item 
Implicit: set `detect_types' to @ref{2c25,,PARSE_DECLTYPES}

@item 
Explicit: set `detect_types' to @ref{2c26,,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{2c7c}@anchor{library/sqlite3 sqlite3-adapter-converter-recipes}@anchor{70e}
@subsubsection Adapter and converter recipes


This section shows recipes for common adapters and converters.

@example
import datetime
import sqlite3

def adapt_date_iso(val):
    """Adapt datetime.date to ISO 8601 date."""
    return val.isoformat()

def adapt_datetime_iso(val):
    """Adapt datetime.datetime to timezone-naive ISO 8601 date."""
    return val.replace(tzinfo=None).isoformat()

def adapt_datetime_epoch(val):
    """Adapt datetime.datetime to Unix timestamp."""
    return int(val.timestamp())

sqlite3.register_adapter(datetime.date, adapt_date_iso)
sqlite3.register_adapter(datetime.datetime, adapt_datetime_iso)
sqlite3.register_adapter(datetime.datetime, adapt_datetime_epoch)

def convert_date(val):
    """Convert ISO 8601 date to datetime.date object."""
    return datetime.date.fromisoformat(val.decode())

def convert_datetime(val):
    """Convert ISO 8601 datetime to datetime.datetime object."""
    return datetime.datetime.fromisoformat(val.decode())

def convert_timestamp(val):
    """Convert Unix epoch timestamp to datetime.datetime object."""
    return datetime.datetime.fromtimestamp(int(val))

sqlite3.register_converter("date", convert_date)
sqlite3.register_converter("datetime", convert_datetime)
sqlite3.register_converter("timestamp", convert_timestamp)
@end example

@c dt = datetime.datetime(2019, 5, 18, 15, 17, 8, 123456)
@c 
@c assert adapt_date_iso(dt.date()) == "2019-05-18"
@c assert convert_date(b"2019-05-18") == dt.date()
@c 
@c assert adapt_datetime_iso(dt) == "2019-05-18T15:17:08.123456"
@c assert convert_datetime(b"2019-05-18T15:17:08.123456") == dt
@c 
@c # Using current time as fromtimestamp() returns local date/time.
@c # Dropping microseconds as adapt_datetime_epoch truncates fractional second part.
@c now = datetime.datetime.now().replace(microsecond=0)
@c current_timestamp = int(now.timestamp())
@c 
@c assert adapt_datetime_epoch(now) == current_timestamp
@c assert convert_timestamp(str(current_timestamp).encode()) == now

@node How to use connection shortcut methods,How to use the connection context manager,Adapter and converter recipes,How-to guides
@anchor{library/sqlite3 how-to-use-connection-shortcut-methods}@anchor{2c7d}@anchor{library/sqlite3 sqlite3-connection-shortcuts}@anchor{2c49}
@subsubsection How to use connection shortcut methods


Using the @ref{2c4b,,execute()},
@ref{2c4c,,executemany()}, and @ref{2c4d,,executescript()}
methods of the @ref{548,,Connection} class, your code can
be written more concisely because you don't have to create the (often
superfluous) @ref{2c17,,Cursor} objects explicitly. Instead, the @ref{2c17,,Cursor}
objects are created implicitly and these shortcut methods return the cursor
objects. This way, you can execute a @code{SELECT} statement and iterate over it
directly using only a single call on the @ref{548,,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{2c7e}@anchor{library/sqlite3 sqlite3-connection-context-manager}@anchor{1a9b}
@subsubsection How to use the connection context manager


A @ref{548,,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{186,,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{6d6,,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{6d6,,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{1581,,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{2c7f}@anchor{library/sqlite3 sqlite3-uri-tricks}@anchor{2c2a}
@subsubsection How to work with SQLite URIs


Some useful URI tricks include:


@itemize *

@item 
以唯讀模式開啟資料庫：
@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{1b54,,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,如何處理非 UTF-8 的文字編碼,How to work with SQLite URIs,How-to guides
@anchor{library/sqlite3 how-to-create-and-use-row-factories}@anchor{2c80}@anchor{library/sqlite3 sqlite3-howto-row-factory}@anchor{2c1e}
@subsubsection How to create and use row factories


By default, @code{sqlite3} represents each row as a @ref{60c,,tuple}.
If a @code{tuple} does not suit your needs,
you can use the @ref{106c,,sqlite3.Row} class
or a custom @ref{2c55,,row_factory}.

While @code{row_factory} exists as an attribute both on the
@ref{2c17,,Cursor} and the @ref{548,,Connection},
it is recommended to set @ref{18fc,,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{2c55,,row_factory}
that returns each row as a @ref{183,,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{857,,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{4dc,,dataclass}, or any other custom class,
instead of a @ref{4db,,namedtuple}.

@node 如何處理非 UTF-8 的文字編碼,,How to create and use row factories,How-to guides
@anchor{library/sqlite3 how-to-handle-non-utf-8-text-encodings}@anchor{2c81}@anchor{library/sqlite3 sqlite3-howto-encoding}@anchor{2c53}
@subsubsection 如何處理非 UTF-8 的文字編碼


By default, @code{sqlite3} uses @ref{169,,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{2c56,,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{548,,Connection} instance @code{con}
connected to this database,
we can decode the Latin-2 encoded text using this @ref{2c56,,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{14a5,,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{14a5,,Unicode HOWTO}


@node 解釋,,How-to guides,sqlite3 --- SQLite 資料庫的 DB-API 2 0 介面
@anchor{library/sqlite3 explanation}@anchor{2c82}@anchor{library/sqlite3 sqlite3-explanation}@anchor{2c14}
@subsubsection 解釋

@anchor{library/sqlite3 sqlite3-transaction-control}@anchor{2c83}
@menu
* Transaction control:: 

@end menu

@node Transaction control,,,解釋
@anchor{library/sqlite3 sqlite3-controlling-transactions}@anchor{2c19}@anchor{library/sqlite3 transaction-control}@anchor{2c84}
@subsubsection Transaction control


@code{sqlite3} offers multiple methods of controlling whether,
when and how database transactions are opened and closed.
@ref{6d7,,Transaction control via the autocommit attribute} is recommended,
while @ref{2c28,,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{6d7}@anchor{library/sqlite3 transaction-control-via-the-autocommit-attribute}@anchor{2c85}
@subsubsection Transaction control via the @code{autocommit} attribute


The recommended way of controlling transaction behaviour is through
the @ref{6d6,,Connection.autocommit} attribute,
which should preferably be set using the `autocommit' parameter
of @ref{5a0,,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{5a0,,connect()}, @ref{2c1a,,Connection.commit()}, and @ref{2c4a,,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{549,,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{2c1a,,Connection.commit()} and @ref{2c4a,,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{6d6,,Connection.autocommit} attribute;
use @ref{2c54,,Connection.in_transaction} to query
the low-level SQLite autocommit mode.

Set `autocommit' to @ref{2c29,,LEGACY_TRANSACTION_CONTROL}
to leave transaction control behaviour to the
@ref{2c27,,Connection.isolation_level} attribute.
See @ref{2c28,,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{2c28}@anchor{library/sqlite3 transaction-control-via-the-isolation-level-attribute}@anchor{2c86}
@subsubsection Transaction control via the @code{isolation_level} attribute


@cartouche
@quotation 備註 
The recommended way of controlling transactions is via the
@ref{6d6,,autocommit} attribute.
See @ref{6d7,,Transaction control via the autocommit attribute}.
@end quotation
@end cartouche

If @ref{6d6,,Connection.autocommit} is set to
@ref{2c29,,LEGACY_TRANSACTION_CONTROL} (the default),
transaction behaviour is controlled using
the @ref{2c27,,Connection.isolation_level} attribute.
Otherwise, @code{isolation_level} has no effect.

If the connection attribute @ref{2c27,,isolation_level}
is not @code{None},
new transactions are implicitly opened before
@ref{5aa,,execute()} and @ref{5ab,,executemany()} executes
@code{INSERT}, @code{UPDATE}, @code{DELETE}, or @code{REPLACE} statements;
for other statements, no implicit transaction handling is performed.
Use the @ref{2c1a,,commit()} and @ref{2c4a,,rollback()} methods
to respectively commit and roll back pending transactions.
You can choose the underlying SQLite transaction behaviour@footnote{https://www.sqlite.org/lang_transaction.html#deferred_immediate_and_exclusive_transactions} —
that is, whether and what type of @code{BEGIN} statements @code{sqlite3}
implicitly executes –
via the @ref{2c27,,isolation_level} attribute.

If @ref{2c27,,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{2c54,,in_transaction} attribute.

The @ref{2c4e,,executescript()} method implicitly commits
any pending transaction before execution of the given SQL script,
regardless of the value of @ref{2c27,,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{6d6,,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 Persistence,Python 標準函式庫 Standard Library
@anchor{library/archiving doc}@anchor{2bbc}@anchor{library/archiving archiving}@anchor{2c87}@anchor{library/archiving data-compression-and-archiving}@anchor{2c88}@anchor{library/archiving translation-repo}@anchor{2c89}
@section 資料壓縮與保存


本章中描述的模組支援使用 zlib、gzip、bzip2、lzma 和 zstd 演算法進行資料壓縮，以及建立 ZIP 和 tar 格式的存檔。另請參閱 @ref{ca,,shutil} 模組提供的 @ref{1419,,Archiving operations}。

@menu
* compression 套件:: 
* compression.zstd: compression zstd --- 與 Zstandard 格式相容的壓縮. 與 Zstandard 格式相容的壓縮
* zlib: zlib --- 相容於 gzip 的壓縮. 相容於 gzip 的壓縮
* gzip: gzip --- gzip 檔案的支援. gzip 檔案的支援
* bz2: bz2 --- bzip2 壓縮的支援. bzip2 壓縮的支援
* lzma: lzma --- 使用 LZMA 演算法進行壓縮. 使用 LZMA 演算法進行壓縮
* zipfile: zipfile --- 處理 ZIP 封存檔案. 處理 ZIP 封存檔案
* tarfile: tarfile --- 讀取與寫入 tar 封存檔案. 讀取與寫入 tar 封存檔案

@end menu

@node compression 套件,compression zstd --- 與 Zstandard 格式相容的壓縮,,資料壓縮與保存
@anchor{library/compression doc}@anchor{2c8a}@anchor{library/compression module-compression}@anchor{22}@anchor{library/compression the-compression-package}@anchor{2c8b}
@subsection @code{compression} 套件


@geindex module; compression


在 3.14 版被加入.


@code{compression} 套件包含了有多種不同壓縮演算法介面的標準壓縮模組。其中一些模組過去是以獨立模組的形式提供；為了相容性考量，這些模組將繼續以其原始名稱提供，並且不會在沒有經過棄用週期的情況下被移除。建議在可行的情況下盡量先使用 @code{compression} 中的模組。


@itemize *

@item 
@code{compression.bz2} -- 重新匯出 @ref{14,,bz2}

@item 
@code{compression.gzip} -- 重新匯出 @ref{6b,,gzip}

@item 
@code{compression.lzma} -- 重新匯出 @ref{8e,,lzma}

@item 
@code{compression.zlib} -- 重新匯出 @ref{139,,zlib}

@item 
@ref{23,,compression.zstd} -- Zstandard 壓縮函式庫的包裝器
@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 --- 與 Zstandard 格式相容的壓縮,zlib --- 相容於 gzip 的壓縮,compression 套件,資料壓縮與保存
@anchor{library/compression zstd doc}@anchor{2c8c}@anchor{library/compression zstd compression-zstd-compression-compatible-with-the-zstandard-format}@anchor{2c8d}@anchor{library/compression zstd module-compression zstd}@anchor{23}@anchor{library/compression zstd translation-repo}@anchor{2c8e}
@subsection @code{compression.zstd} --- 與 Zstandard 格式相容的壓縮


@geindex module; compression.zstd


在 3.14 版被加入.


`原始碼：'Lib/compression/zstd/__init__.py@footnote{https://github.com/python/cpython/tree/3.14/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.

@code{compression.zstd} 模組包含：


@itemize *

@item 
The @ref{2c8f,,open()} function and @ref{2c90,,ZstdFile} class for reading and
writing compressed files.

@item 
The @ref{2c91,,ZstdCompressor} and @ref{2c92,,ZstdDecompressor} classes for
incremental (de)compression.

@item 
The @ref{2c93,,compress()} and @ref{2c94,,decompress()} functions for one-shot
(de)compression.

@item 
The @ref{2c95,,train_dict()} and @ref{2c96,,finalize_dict()} functions and the
@ref{2c97,,ZstdDict} class to train and manage Zstandard dictionaries.

@item 
The @ref{2c98,,CompressionParameter}, @ref{2c99,,DecompressionParameter}, and
@ref{2c9a,,Strategy} classes for setting advanced (de)compression parameters.
@end itemize

@menu
* 例外: 例外<7>. 
* Reading and writing compressed files:: 
* Compressing and decompressing data in memory:: 
* Zstandard 字典:: 
* Advanced parameter control:: 
* Miscellaneous:: 
* 範例: 範例<13>. 

@end menu

@node 例外<7>,Reading and writing compressed files,,compression zstd --- 與 Zstandard 格式相容的壓縮
@anchor{library/compression zstd exceptions}@anchor{2c9b}
@subsubsection 例外


@geindex ZstdError
@anchor{library/compression zstd compression zstd ZstdError}@anchor{2c9c}
@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,例外<7>,compression zstd --- 與 Zstandard 格式相容的壓縮
@anchor{library/compression zstd reading-and-writing-compressed-files}@anchor{2c9d}
@subsubsection Reading and writing compressed files


@geindex open() (於 compression.zstd 模組中)
@anchor{library/compression zstd compression zstd open}@anchor{2c8f}
@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{13c4,,file object}.

The `file' argument can be either a file name (given as a
@ref{169,,str}, @ref{192,,bytes} or @ref{59b,,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{2c99,,DecompressionParameter} for detailed
information about supported
parameters. The `zstd_dict' argument is a @ref{2c97,,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 decompression parameters; see
@ref{2c98,,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{2c97,,ZstdDict} instance to be used during
compression.

In binary mode, this function is equivalent to the @ref{2c90,,ZstdFile}
constructor: @code{ZstdFile(file, mode, ...)}. In this case, the
`encoding', `errors', and `newline' parameters must not be provided.

In text mode, a @ref{2c90,,ZstdFile} object is created, and wrapped in an
@ref{9b7,,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{2c90}
@deffn {類別} compression.zstd.ZstdFile (file, /, mode='rb', *, level=None, options=None, zstd_dict=None)

Open a Zstandard-compressed file in binary mode.

A @ref{2c90,,ZstdFile} can wrap an already-open @ref{13c4,,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{169,,str},
@ref{192,,bytes} or @ref{59b,,path-like} object). If
wrapping an existing file object, the wrapped file will not be closed when
the @ref{2c90,,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{2c99,,DecompressionParameter} for detailed information about supported
parameters. The `zstd_dict' argument is a @ref{2c97,,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 decompression parameters; see
@ref{2c98,,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{2c97,,ZstdDict} instance to be used during
compression.

@code{ZstdFile} supports all the members specified by
@ref{89c,,io.BufferedIOBase}, except for @ref{2c9e,,detach()}
and @ref{1511,,truncate()}.
Iteration and the @ref{186,,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{2c9f}
@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 @ref{2c9f,,peek()} does not change the file position of
the @ref{2c90,,ZstdFile}, it may change the position of the underlying
file object (for example, if the @ref{2c90,,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{2ca0}
@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{2ca1}
@deffn {屬性} name

The name of the Zstandard file. Equivalent to the @ref{2ca2,,name}
attribute of the underlying @ref{13c4,,file object}.
@end deffn
@end deffn

@node Compressing and decompressing data in memory,Zstandard 字典,Reading and writing compressed files,compression zstd --- 與 Zstandard 格式相容的壓縮
@anchor{library/compression zstd compressing-and-decompressing-data-in-memory}@anchor{2ca3}
@subsubsection Compressing and decompressing data in memory


@geindex compress() (於 compression.zstd 模組中)
@anchor{library/compression zstd compression zstd compress}@anchor{2c93}
@deffn {函式} compression.zstd.compress (data, level=None, options=None, zstd_dict=None)

Compress `data' (a @ref{193,,bytes-like object}), returning the compressed
data as a @ref{192,,bytes} object.

The `level' argument is an integer controlling the level of
compression. `level' is an alternative to setting
@ref{2ca4,,CompressionParameter.compression_level} in `options'. Use
@ref{2ca5,,bounds()} on
@ref{2ca4,,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{2c98,,CompressionParameter} documentation.

The `zstd_dict' argument is an instance of @ref{2c97,,ZstdDict}
containing trained data to improve compression efficiency. The
function @ref{2c95,,train_dict()} can be used to generate a Zstandard dictionary.
@end deffn

@geindex decompress() (於 compression.zstd 模組中)
@anchor{library/compression zstd compression zstd decompress}@anchor{2c94}
@deffn {函式} compression.zstd.decompress (data, zstd_dict=None, options=None)

Decompress `data' (a @ref{193,,bytes-like object}), returning the uncompressed
data as a @ref{192,,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{2c99,,DecompressionParameter}
documentation.

The `zstd_dict' argument is an instance of @ref{2c97,,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{2c91}
@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{2c93,,compress()}.

The `level' argument is an integer controlling the level of
compression. `level' is an alternative to setting
@ref{2ca4,,CompressionParameter.compression_level} in `options'. Use
@ref{2ca5,,bounds()} on
@ref{2ca4,,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{2c98,,CompressionParameter} documentation.

The `zstd_dict' argument is an optional instance of @ref{2c97,,ZstdDict}
containing trained data to improve compression efficiency. The
function @ref{2c95,,train_dict()} can be used to generate a Zstandard dictionary.

@geindex compress() (compression.zstd.ZstdCompressor 的方法)
@anchor{library/compression zstd compression zstd ZstdCompressor compress}@anchor{2ca6}
@deffn {方法} compress (data, mode=ZstdCompressor.CONTINUE)

Compress `data' (a @ref{193,,bytes-like object}), returning a @ref{192,,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{2ca7,,flush()}. The returned
data should be concatenated with the output of any previous calls to
@ref{2ca6,,compress()}.

The `mode' argument is a @ref{2c91,,ZstdCompressor} attribute, either
@ref{2ca8,,CONTINUE}, @ref{2ca9,,FLUSH_BLOCK},
or @ref{2caa,,FLUSH_FRAME}.

When all data has been provided to the compressor, call the
@ref{2ca7,,flush()} method to finish the compression process. If
@ref{2ca6,,compress()} is called with `mode' set to @ref{2caa,,FLUSH_FRAME},
@ref{2ca7,,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{2ca7}
@deffn {方法} flush (mode=ZstdCompressor.FLUSH_FRAME)

Finish the compression process, returning a @ref{192,,bytes} object
containing any data stored in the compressor's internal buffers.

The `mode' argument is a @ref{2c91,,ZstdCompressor} attribute, either
@ref{2ca9,,FLUSH_BLOCK}, or @ref{2caa,,FLUSH_FRAME}.
@end deffn

@geindex set_pledged_input_size() (compression.zstd.ZstdCompressor 的方法)
@anchor{library/compression zstd compression zstd ZstdCompressor set_pledged_input_size}@anchor{2cab}
@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{2cac,,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{2cad,,last_mode} is not @ref{2caa,,FLUSH_FRAME}, a
@ref{2eb,,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{2ca6,,compress()}, future calls to @code{compress()} or
@ref{2ca7,,flush()} may raise @ref{2c9c,,ZstdError} and the last chunk of data may
be lost.

After @ref{2ca7,,flush()} or @ref{2ca6,,compress()} are called with mode
@ref{2caa,,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{2ca8}
@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{2ca9}
@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{2ca6,,compress()},
improving compression.
@end deffn

@geindex FLUSH_FRAME (compression.zstd.ZstdCompressor 的屬性)
@anchor{library/compression zstd compression zstd ZstdCompressor FLUSH_FRAME}@anchor{2caa}
@deffn {屬性} FLUSH_FRAME

Complete and write out a frame. Future data provided to
@ref{2ca6,,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{2cad}
@deffn {屬性} last_mode

The last mode passed to either @ref{2ca6,,compress()} or @ref{2ca7,,flush()}.
The value can be one of @ref{2ca8,,CONTINUE}, @ref{2ca9,,FLUSH_BLOCK}, or
@ref{2caa,,FLUSH_FRAME}. The initial value is @ref{2caa,,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{2c92}
@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{2c94,,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{2c99,,DecompressionParameter}
documentation.

The `zstd_dict' argument is an instance of @ref{2c97,,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{2c94,,decompress()} function and
@ref{2c90,,ZstdFile} class. To decompress a multi-frame input, you should
use @ref{2c94,,decompress()}, @ref{2c90,,ZstdFile} if working with a
@ref{13c4,,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{2cae}
@deffn {方法} decompress (data, max_length=-1)

Decompress `data' (a @ref{193,,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, the @ref{2caf,,needs_input} attribute will
be set to @code{False}. In this case, the next call to
@ref{2cae,,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{2caf,,needs_input} attribute
will be set to @code{True}.

Attempting to decompress data after the end of a frame will raise a
@ref{2c9c,,ZstdError}. Any data found after the end of the frame is ignored
and saved in the @ref{2cb0,,unused_data} attribute.
@end deffn

@geindex eof (compression.zstd.ZstdDecompressor 的屬性)
@anchor{library/compression zstd compression zstd ZstdDecompressor eof}@anchor{2cb1}
@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{2cb0}
@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{2caf}
@deffn {屬性} needs_input

@code{False} if the @ref{2cae,,decompress()} method can provide more
decompressed data before requiring new compressed input.
@end deffn
@end deffn

@node Zstandard 字典,Advanced parameter control,Compressing and decompressing data in memory,compression zstd --- 與 Zstandard 格式相容的壓縮
@anchor{library/compression zstd zstandard-dictionaries}@anchor{2cb2}
@subsubsection Zstandard 字典


@geindex train_dict() (於 compression.zstd 模組中)
@anchor{library/compression zstd compression zstd train_dict}@anchor{2c95}
@deffn {函式} compression.zstd.train_dict (samples, dict_size)

Train a Zstandard dictionary, returning a @ref{2c97,,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{192,,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{2c96}
@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{2c97,,ZstdDict} instance with
the @ref{2cb3,,dict_content} containing the raw dictionary contents.

The `samples' argument (an iterable of @ref{192,,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{2c95,,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{2c97}
@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{2c95,,train_dict()} if you
need to train a new dictionary from sample data.

The `dict_content' argument (a @ref{193,,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{2c95,,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{2cb3}
@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{2cb4}
@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{2cb5,,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{2cb6}
@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{2cb7}
@deffn {屬性} as_undigested_dict

Load as an undigested dictionary.
@end deffn
@end quotation
@end deffn

@node Advanced parameter control,Miscellaneous,Zstandard 字典,compression zstd --- 與 Zstandard 格式相容的壓縮
@anchor{library/compression zstd advanced-parameter-control}@anchor{2cb8}
@subsubsection Advanced parameter control


@geindex CompressionParameter (compression.zstd 中的類別)
@anchor{library/compression zstd compression zstd CompressionParameter}@anchor{2c98}
@deffn {類別} compression.zstd.CompressionParameter

An @ref{ed6,,IntEnum} containing the advanced compression parameter
keys that can be used when compressing data.

The @ref{2ca5,,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{2ca4,,compression_level}:

@example
lower, upper = CompressionParameter.compression_level.bounds()
@end example

Example setting the @ref{2cb9,,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{2ca5}
@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{2ca4,,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{2ca4}
@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{2cba,,COMPRESSION_LEVEL_DEFAULT}.
@end deffn

@geindex window_log (compression.zstd.CompressionParameter 的屬性)
@anchor{library/compression zstd compression zstd CompressionParameter window_log}@anchor{2cb9}
@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{2cbb}
@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{2cbc,,dfast}, and improve compression
speed of strategies > @ref{2cbc,,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{2cbd}
@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{2cbe,,fast} strategy. It's still useful when using
@ref{2cbc,,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{2cbf}
@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{2cbe,,fast} and @ref{2cbc,,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{2cc0}
@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{2cc1,,btopt},
the effective minimum is @code{4}; for all strategies
> @ref{2cbe,,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{2cc2}
@deffn {屬性} target_length

The impact of this field depends on the selected @ref{2c9a,,Strategy}.

For strategies @ref{2cc1,,btopt}, @ref{2cc3,,btultra} and
@ref{2cc4,,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{2cbe,,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{2cc5}
@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{2c9a,,Strategy}

@end deffn

@geindex enable_long_distance_matching (compression.zstd.CompressionParameter 的屬性)
@anchor{library/compression zstd compression zstd CompressionParameter enable_long_distance_matching}@anchor{2cc6}
@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{2cb9,,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{2cc1,,btopt} (compression level 16+).
@end deffn

@geindex ldm_hash_log (compression.zstd.CompressionParameter 的屬性)
@anchor{library/compression zstd compression zstd CompressionParameter ldm_hash_log}@anchor{2cc7}
@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{2cc8}
@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{2cc9}
@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{2cca}
@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{2cac}
@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{2c93,,compress()} for one-shot compression

@item 
Providing all of the data to be compressed in the frame in a single
@ref{2ca6,,ZstdCompressor.compress()} call, with the
@ref{2caa,,ZstdCompressor.FLUSH_FRAME} mode.

@item 
Calling @ref{2cab,,ZstdCompressor.set_pledged_input_size()} with the exact
amount of data that will be provided to the compressor prior to any
calls to @ref{2ca6,,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{2ccb}
@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{2c9c,,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{2ccc}
@deffn {屬性} dict_id_flag

When compressing with a @ref{2c97,,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{2ccd}
@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{2cce}
@deffn {屬性} job_size

Size of a compression job, in bytes. This value is enforced only when
@ref{2ccd,,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{2ccf}
@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{2ccd,,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{2c99}
@deffn {類別} compression.zstd.DecompressionParameter

An @ref{ed6,,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{2cd0,,bounds()} method can be used on any attribute to get the valid
values for that parameter.

Example setting the @ref{2cd1,,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{2cd0}
@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{2cd1}
@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{2c9a}
@deffn {類別} compression.zstd.Strategy

An @ref{ed6,,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{2cbe}
@deffn {屬性} fast
@end deffn

@geindex dfast (compression.zstd.Strategy 的屬性)
@anchor{library/compression zstd compression zstd Strategy dfast}@anchor{2cbc}
@deffn {屬性} dfast
@end deffn

@geindex greedy (compression.zstd.Strategy 的屬性)
@anchor{library/compression zstd compression zstd Strategy greedy}@anchor{2cd2}
@deffn {屬性} greedy
@end deffn

@geindex lazy (compression.zstd.Strategy 的屬性)
@anchor{library/compression zstd compression zstd Strategy lazy}@anchor{2cd3}
@deffn {屬性} lazy
@end deffn

@geindex lazy2 (compression.zstd.Strategy 的屬性)
@anchor{library/compression zstd compression zstd Strategy lazy2}@anchor{2cd4}
@deffn {屬性} lazy2
@end deffn

@geindex btlazy2 (compression.zstd.Strategy 的屬性)
@anchor{library/compression zstd compression zstd Strategy btlazy2}@anchor{2cd5}
@deffn {屬性} btlazy2
@end deffn

@geindex btopt (compression.zstd.Strategy 的屬性)
@anchor{library/compression zstd compression zstd Strategy btopt}@anchor{2cc1}
@deffn {屬性} btopt
@end deffn

@geindex btultra (compression.zstd.Strategy 的屬性)
@anchor{library/compression zstd compression zstd Strategy btultra}@anchor{2cc3}
@deffn {屬性} btultra
@end deffn

@geindex btultra2 (compression.zstd.Strategy 的屬性)
@anchor{library/compression zstd compression zstd Strategy btultra2}@anchor{2cc4}
@deffn {屬性} btultra2
@end deffn
@end deffn

@node Miscellaneous,範例<13>,Advanced parameter control,compression zstd --- 與 Zstandard 格式相容的壓縮
@anchor{library/compression zstd miscellaneous}@anchor{2cd6}
@subsubsection Miscellaneous


@geindex get_frame_info() (於 compression.zstd 模組中)
@anchor{library/compression zstd compression zstd get_frame_info}@anchor{2cb5}
@deffn {函式} compression.zstd.get_frame_info (frame_buffer)

Retrieve a @ref{2cd7,,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{2cd7}
@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{2cd8}
@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{2cd9}
@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{2cba}
@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{2cda}
@deffn {屬性} compression.zstd.zstd_version_info

Version number of the runtime zstd library as a tuple of integers
(major, minor, release).
@end deffn

@node 範例<13>,,Miscellaneous,compression zstd --- 與 Zstandard 格式相容的壓縮
@anchor{library/compression zstd examples}@anchor{2cdb}
@subsubsection 範例


讀取壓縮檔案：

@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 --- 相容於 gzip 的壓縮,gzip --- gzip 檔案的支援,compression zstd --- 與 Zstandard 格式相容的壓縮,資料壓縮與保存
@anchor{library/zlib doc}@anchor{2cdc}@anchor{library/zlib module-zlib}@anchor{139}@anchor{library/zlib translation-repo}@anchor{2cdd}@anchor{library/zlib zlib-compression-compatible-with-gzip}@anchor{2cde}
@subsection @code{zlib} --- 相容於 @code{gzip} 的壓縮


@geindex module; zlib


__________________________________________________________________


對於需要資料壓縮的應用程式，此模組提供了能夠使用 zlib 函式庫進行壓縮和解壓縮的函式。zlib 函式庫有自己的主頁 @indicateurl{https://www.zlib.net}。已知 Python 模組與早於 1.1.3 的 zlib 函式庫版本之間並不相容；1.1.3 存在安全漏洞@footnote{https://zlib.net/zlib_faq.html#faq33}，因此我們建議使用 1.1.4 或更新的版本。

zlib 的函式有很多選項，且通常需要按特定順序使用。本文件並不打算解說所有選項排列組合的效果；相關官方資訊，請參閱 zlib 手冊@footnote{https://www.zlib.net/manual.html}。

若要讀寫 @code{.gz} 文件，請參閱 @ref{6b,,gzip} 模組。

該模組中可用的例外和函式是：

@geindex error
@anchor{library/zlib zlib error}@anchor{2cdf}
@deffn {例外} zlib.error

當壓縮和解壓縮發生錯誤時引發的例外。
@end deffn

@geindex adler32() (於 zlib 模組中)
@anchor{library/zlib zlib adler32}@anchor{1ae0}
@deffn {函式} zlib.adler32 (data[, value])

計算 `data' 的 Adler-32 核對和 (checksum)。（Adler-32 核對和幾乎與 CRC32 一樣可靠，但計算速度更快。）結果是一個 unsigned（無符號的）32-bit 整數。如果有提供 `value'，則將其用作核對和的起始值，否則使用預設值 1。傳入 `value' 允許了於多個輸入的串聯 (concatenation) 上計算核對和。該演算法的加密強度不夠高，不該用於身份驗證 (authentication) 或數位簽章 (digital signature)。由於該演算法是為核對和演算法而設計的，它並不適合作為通用的雜湊演算法。


在 3.0 版的變更: 結果總是為 unsigned。

@end deffn

@geindex compress() (於 zlib 模組中)
@anchor{library/zlib zlib compress}@anchor{848}
@deffn {函式} zlib.compress (data, /, level=Z_DEFAULT_COMPRESSION, wbits=MAX_WBITS)

壓縮 `data' 中的位元組，回傳一個包含壓縮資料的位元組物件。 `level' 是從 @code{0} 到 @code{9} 或 @code{-1} 的整數，控制了壓縮的級別；請見 @ref{2ce0,,Z_BEST_SPEED} (@code{1})、@ref{2ce1,,Z_BEST_COMPRESSION} (@code{9})、@ref{2ce2,,Z_NO_COMPRESSION} (@code{0})，以及預設值 @ref{2ce3,,Z_DEFAULT_COMPRESSION} (@code{-1}) 以得到更多關於這些值的資訊。
@anchor{library/zlib compress-wbits}@anchor{2ce4}
`wbits' 引數控制了壓縮資料時所使用的歷史紀錄緩衝區 (history buffer) 大小（或「視窗大小」），以及輸出中是否包含標題和尾末 (trailer)。它可以採用多個值的範圍，預設為 @code{15} (@ref{2ce5,,MAX_WBITS})：


@itemize *

@item 
+9 到 +15：視窗大小的以二為底的對數，因此範圍在 512 到 32768 之間。較大的值會產生更佳的壓縮，但會佔用更多的記憶體。生成輸出將包含特定於 zlib 的標頭和尾末。

@item 
−9 到 −15：使用 `wbits' 的絕對值作為視窗大小的對數，同時生成沒有標頭或尾末核對和的原始輸出串流。

@item 
+25 到 +31 = 16 +（9 到 15）：使用數值的最低 4 位元作為視窗大小的對數，同時在輸出中包含基本的 gzip 標頭和尾末核對和。
@end itemize

如果發生任何錯誤，則引發 @ref{2cdf,,error} 例外。


在 3.6 版的變更: `level' 現在可以用作關鍵字參數。



在 3.11 版的變更: `wbits' 參數現在可用於設定視窗位元和壓縮型別。

@end deffn

@geindex compressobj() (於 zlib 模組中)
@anchor{library/zlib zlib compressobj}@anchor{2ce6}
@deffn {函式} zlib.compressobj (level=Z_DEFAULT_COMPRESSION, method=DEFLATED, wbits=MAX_WBITS, memLevel=DEF_MEM_LEVEL, strategy=Z_DEFAULT_STRATEGY[, zdict])

回傳一個壓縮物件，用於壓縮不能一次全部放入記憶體中的資料串流。

`level' is the compression level -- an integer from @code{0} to @code{9} or @code{-1}.
See @ref{2ce0,,Z_BEST_SPEED} (@code{1}), @ref{2ce1,,Z_BEST_COMPRESSION} (@code{9}),
@ref{2ce2,,Z_NO_COMPRESSION} (@code{0}), and the default,
@ref{2ce3,,Z_DEFAULT_COMPRESSION} (@code{-1}) for more information about these values.

`method' 代表壓縮演算法。目前唯一支援的值是 @ref{2ce7,,DEFLATED}。

`wbits' 參數控制歷史紀錄緩衝區的大小（或「視窗大小」），以及將使用的標頭和尾末格式。它與@ref{2ce4,,前面敘述的 compress()} 具有相同的含義。

`memLevel' 引數控制用於內部壓縮狀態的記憶體大小。有效值範圍為 @code{1} 到 @code{9}。較高的值會使用更多的記憶體，但速度更快並產生更小的輸出。

`strategy' 被用於調整壓縮演算法。可用的值為 @ref{2ce8,,Z_DEFAULT_STRATEGY}、@ref{2ce9,,Z_FILTERED}、@ref{2cea,,Z_HUFFMAN_ONLY}、@ref{2ceb,,Z_RLE} 和 @ref{2cec,,Z_FIXED}。

`zdict' 是事先定義好的的壓縮字典。這是一個位元組序列（例如一個 @ref{192,,bytes} 物件），其中包含預期在要壓縮的資料中頻繁出現的子序列。那些預期會最常見的子序列應該出現在字典的尾末。


在 3.3 版的變更: 新增 `zdict' 參數與支援關鍵字引數。

@end deffn

@geindex crc32() (於 zlib 模組中)
@anchor{library/zlib zlib crc32}@anchor{195f}
@deffn {函式} zlib.crc32 (data[, value])

@geindex Cyclic Redundancy Check（循環冗餘核對）
@geindex checksum（核對和）;Cyclic Redundancy Check（循環冗餘核對）

計算 `data' 的 CRC（Cyclic Redundancy Check，循環冗餘核對）核對和，結果會是一個 unsigned 32-bit 整數。如果 `value' 存在，則將其用作核對和的起始值，否則使用預設值 0。傳入 `value' 允許在多個輸入的串聯上計算核對和。該演算法的加密強度不夠高，不該用於身份驗證或數位簽章。由於該演算法是為核對和演算法而設計的，它並不適合作為通用的雜湊演算法。


在 3.0 版的變更: 結果總是為 unsigned。

@end deffn

@geindex decompress() (於 zlib 模組中)
@anchor{library/zlib zlib decompress}@anchor{f04}
@deffn {函式} zlib.decompress (data, /, wbits=MAX_WBITS, bufsize=DEF_BUF_SIZE)

解壓縮 `data' 中的位元組，回傳包含未壓縮資料的位元組物件。 `wbits' 參數依賴於 `data' 的格式，下面將進一步討論。如果有給定 `bufsize'，它會被用作輸出緩衝區的初始大小。如果發生任何錯誤，則引發 @ref{2cdf,,error} 例外。
@anchor{library/zlib decompress-wbits}@anchor{2ced}
`wbits' 參數控制歷史紀錄緩衝區的大小（或「視窗大小」），以及期望的標頭和尾末格式。它類似於 @ref{2ce6,,compressobj()} 的參數，但接受更多範圍的值：


@itemize *

@item 
+8 到 +15：視窗大小的以二為底的對數。輸入必須包括一個 zlib 標頭和尾末。

@item 
0：根據 zlib 標頭檔自動決定視窗大小。僅有在 zlib 1.2.3.5 或更新的版本支援。

@item 
−8 to −15：使用 `wbits' 的絕對值作為視窗大小的對數，輸入必須是沒有標頭或尾末的原始串流。

@item 
+24 到 +31 = 16 + （8 到 15）：取值的最低4位元作為視窗大小的對數，輸入必須包含 gzip 標頭和尾末。

@item 
+40 到 +47 = 32 + （8 到 15）：使用值的最低 4 位元作為視窗大小的對數，並自動接受 zlib 或 gzip 格式。
@end itemize

當解壓縮一個串流時，視窗大小不得小於最初用於壓縮串流的大小；使用太小的值可能會導致 @ref{2cdf,,error} 例外。預設的 `wbits' 值對應於最大的視窗大小，並且需要包含 zlib 標頭和尾末。

`bufsize' 是用於保存解壓縮資料的緩衝區的初始大小。如果需要更多空間，緩衝區大小將根據需求來增加，因此你不需要讓該值完全剛好；調整它只會節省幾次對 @code{malloc()} 的呼叫。


在 3.6 版的變更: `wbits' 和 `bufsize' 可以用作關鍵字引數。

@end deffn

@geindex decompressobj() (於 zlib 模組中)
@anchor{library/zlib zlib decompressobj}@anchor{2cee}
@deffn {函式} zlib.decompressobj (wbits=MAX_WBITS[, zdict])

回傳一個解壓縮物件，用於解壓縮不能一次全部放入記憶體的資料串流。

`wbits' 引數控制歷史紀錄緩衝區的大小（或「視窗大小」），以及期望的標頭和尾末格式。它與@ref{2ced,,前面敘述的 decompress()} 具有相同的含義。

`zdict' 參數指定是先定義好的壓縮字典。如果有提供，這必須與生成要解壓縮資料的壓縮器所使用的字典相同。

@cartouche
@quotation 備註 
如果 `zdict' 是一個可變物件 (mutable object)（例如一個 @ref{343,,bytearray}），你不能在呼叫 @ref{2cee,,decompressobj()} 和第一次呼叫解壓縮器的 @code{decompress()} 方法之間修改它的內容。
@end quotation
@end cartouche


在 3.3 版的變更: 新增 `zdict' 參數。

@end deffn

壓縮物件支援以下方法：

@geindex compress() (zlib.Compress 的方法)
@anchor{library/zlib zlib Compress compress}@anchor{2cef}
@deffn {方法} Compress.compress (data)

壓縮 `data'，回傳一個位元組物件，其中至少包含 `data' 中部分資料的壓縮資料。此資料應串聯到任何先前呼叫 @ref{848,,compress()} 方法所產生的輸出。一些輸入可能會保存在內部緩衝區中以供後續處理。
@end deffn

@geindex flush() (zlib.Compress 的方法)
@anchor{library/zlib zlib Compress flush}@anchor{2cf0}
@deffn {方法} Compress.flush ([mode])

處理所有待處理的輸入，並回傳包含剩餘壓縮輸出的位元組物件。`mode' 可以從以下常數中選擇：@ref{2cf1,,Z_NO_FLUSH}、@ref{2cf2,,Z_PARTIAL_FLUSH}、@ref{2cf3,,Z_SYNC_FLUSH}、@ref{2cf4,,Z_FULL_FLUSH}、@ref{2cf5,,Z_BLOCK} 或 @ref{2cf6,,Z_FINISH}，預設為 @ref{2cf6,,Z_FINISH}。除了 @ref{2cf6,,Z_FINISH} 之外，所有常數都允許壓縮更多的資料位元組字串，而 @ref{2cf6,,Z_FINISH} 會完成壓縮串流並同時防止壓縮更多資料。在 `mode' 設定為 @ref{2cf6,,Z_FINISH} 的情況下呼叫 @ref{2cf0,,flush()} 後，無法再次呼叫 @ref{848,,compress()} 方法；唯一可行的作法是刪除物件。
@end deffn

@geindex copy() (zlib.Compress 的方法)
@anchor{library/zlib zlib Compress copy}@anchor{2cf7}
@deffn {方法} Compress.copy ()

回傳壓縮物件的副本，這可用於有效壓縮一組共用初始前綴的資料。
@end deffn


在 3.8 版的變更: 於壓縮物件新增對 @ref{750,,copy.copy()} 和 @ref{d5d,,copy.deepcopy()} 的支援。


解壓縮物件支援以下方法和屬性：

@geindex unused_data (zlib.Decompress 的屬性)
@anchor{library/zlib zlib Decompress unused_data}@anchor{2cf8}
@deffn {屬性} Decompress.unused_data

一個位元組物件，它包含壓縮資料結束之後的任何位元組。也就是說，在包含壓縮資料的最後一個位元組可用之前，它會一直保持為 @code{b""}。如果整個位元組字串 (bytestring) 有包含壓縮資料，這會是 @code{b""}，也就是一個空位元組物件。
@end deffn

@geindex unconsumed_tail (zlib.Decompress 的屬性)
@anchor{library/zlib zlib Decompress unconsumed_tail}@anchor{2cf9}
@deffn {屬性} Decompress.unconsumed_tail

一個位元組物件，包含前一次 @ref{f04,,decompress()} 的呼叫因超出了未壓縮資料緩衝區的限制而沒消耗掉的任何資料。 zlib 機制尚未看到此資料，因此你必須將其（和可能有和它串聯的其他資料）反饋給後續的 @ref{f04,,decompress()} 方法呼叫以獲得正確的輸出。
@end deffn

@geindex eof (zlib.Decompress 的屬性)
@anchor{library/zlib zlib Decompress eof}@anchor{136e}
@deffn {屬性} Decompress.eof

一個布林值，代表是否已到達壓縮資料串流的尾末。

這使其能夠區分有正確建構的壓縮串流和不完整或被截斷的串流。


在 3.3 版被加入.

@end deffn

@geindex decompress() (zlib.Decompress 的方法)
@anchor{library/zlib zlib Decompress decompress}@anchor{2cfa}
@deffn {方法} Decompress.decompress (data, max_length=0)

解壓縮 `data' 並回傳一個位元組物件，其包含與 `string' 中至少與部分資料相對應的未壓縮資料。此資料應串聯到任何先前呼叫 @ref{f04,,decompress()} 方法所產生的輸出。一些輸入資料可能會保存在內部緩衝區中以供後續處理。

如果可選參數 `max_length' 不是零，則回傳值長度將不超過 `max_length'。這代表著並不是所有的已壓縮輸入都可以被處理；未使用的資料將被儲存在屬性 @ref{2cf9,,unconsumed_tail} 中。如果要繼續解壓縮，則必須將此位元組字串傳遞給後續對 @ref{f04,,decompress()} 的呼叫。如果 `max_length' 為零，則整個輸入會被解壓縮，並且 @ref{2cf9,,unconsumed_tail} 為空。


在 3.6 版的變更: `max_length' 可以用作關鍵字引數。

@end deffn

@geindex flush() (zlib.Decompress 的方法)
@anchor{library/zlib zlib Decompress flush}@anchor{2cfb}
@deffn {方法} Decompress.flush ([length])

處理所有待處理的輸入，並回傳包含剩餘未壓縮輸出的位元組物件。呼叫 @ref{2cfb,,flush()} 後，無法再次呼叫 @ref{f04,,decompress()} 方法；唯一可行的方法是刪除該物件。

可選參數 `length' 設定了輸出緩衝區的初始大小。
@end deffn

@geindex copy() (zlib.Decompress 的方法)
@anchor{library/zlib zlib Decompress copy}@anchor{2cfc}
@deffn {方法} Decompress.copy ()

回傳解壓物件的副本，這可用於在資料串流中途保存解壓縮器的狀態，以便在未來某個時間點加速對串流的隨機搜尋 (random seek)。
@end deffn


在 3.8 版的變更: 於解壓縮物件新增對 @ref{750,,copy.copy()} 和 @ref{d5d,,copy.deepcopy()} 支援。


The following constants are available to configure compression and decompression
behavior:

@geindex DEFLATED (於 zlib 模組中)
@anchor{library/zlib zlib DEFLATED}@anchor{2ce7}
@deffn {資料} zlib.DEFLATED

The deflate compression method.
@end deffn

@geindex MAX_WBITS (於 zlib 模組中)
@anchor{library/zlib zlib MAX_WBITS}@anchor{2ce5}
@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{2cfd}
@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{2cfe}
@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{2ce2}
@deffn {資料} zlib.Z_NO_COMPRESSION

Compression level @code{0}; no compression.


在 3.6 版被加入.

@end deffn

@geindex Z_BEST_SPEED (於 zlib 模組中)
@anchor{library/zlib zlib Z_BEST_SPEED}@anchor{2ce0}
@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{2ce1}
@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{2ce3}
@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{2ce8}
@deffn {資料} zlib.Z_DEFAULT_STRATEGY

Default compression strategy, for normal data.
@end deffn

@geindex Z_FILTERED (於 zlib 模組中)
@anchor{library/zlib zlib Z_FILTERED}@anchor{2ce9}
@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{2cea}
@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{2ceb}
@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.


在 3.6 版被加入.

@end deffn

@geindex Z_FIXED (於 zlib 模組中)
@anchor{library/zlib zlib Z_FIXED}@anchor{2cec}
@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.


在 3.6 版被加入.

@end deffn

@geindex Z_NO_FLUSH (於 zlib 模組中)
@anchor{library/zlib zlib Z_NO_FLUSH}@anchor{2cf1}
@deffn {資料} zlib.Z_NO_FLUSH

Flush mode @code{0}. No special flushing behavior.


在 3.6 版被加入.

@end deffn

@geindex Z_PARTIAL_FLUSH (於 zlib 模組中)
@anchor{library/zlib zlib Z_PARTIAL_FLUSH}@anchor{2cf2}
@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{2cf3}
@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{2cf4}
@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{2cf6}
@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{2cf5}
@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.


在 3.6 版被加入.

@end deffn

@geindex Z_TREES (於 zlib 模組中)
@anchor{library/zlib zlib Z_TREES}@anchor{2cff}
@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.


在 3.6 版被加入.

@end deffn

有關正在使用的 zlib 函式庫版本資訊可通過以下常數獲得：

@geindex ZLIB_VERSION (於 zlib 模組中)
@anchor{library/zlib zlib ZLIB_VERSION}@anchor{2d00}
@deffn {資料} zlib.ZLIB_VERSION

用於建置模組的 zlib 函式庫版本字串。這可能與實際在執行環境 (runtime) 使用的 zlib 函式庫不同，後者以 @ref{136f,,ZLIB_RUNTIME_VERSION} 提供。
@end deffn

@geindex ZLIB_RUNTIME_VERSION (於 zlib 模組中)
@anchor{library/zlib zlib ZLIB_RUNTIME_VERSION}@anchor{136f}
@deffn {資料} zlib.ZLIB_RUNTIME_VERSION

直譯器實際載入的 zlib 函式庫版本字串。


在 3.3 版被加入.

@end deffn

@geindex ZLIBNG_VERSION (於 zlib 模組中)
@anchor{library/zlib zlib ZLIBNG_VERSION}@anchor{2d01}
@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{2d00,,ZLIB_VERSION} and
@ref{136f,,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.


在 3.14 版被加入.

@end deffn


@subsubheading 也參考



@table @asis

@item @ref{6b,,gzip} 模組

讀寫 @code{gzip} 格式的檔案。

@item @indicateurl{https://www.zlib.net}

zlib 函式庫首頁。

@item @indicateurl{https://www.zlib.net/manual.html}

zlib 手冊解釋了函式庫中許多函式的語義和用法。
@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 --- bzip2 壓縮的支援,zlib --- 相容於 gzip 的壓縮,資料壓縮與保存
@anchor{library/gzip doc}@anchor{2d02}@anchor{library/gzip gzip-support-for-gzip-files}@anchor{2d03}@anchor{library/gzip module-gzip}@anchor{6b}@anchor{library/gzip translation-repo}@anchor{2d04}
@subsection @code{gzip} --- @code{gzip} 檔案的支援


@geindex module; gzip

`原始碼：'Lib/gzip.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/gzip.py}


__________________________________________________________________


This module provides a simple interface to compress and decompress files just
like the GNU programs @code{gzip} and @code{gunzip} would.

The data compression is provided by the @ref{139,,zlib} module.

The @ref{6b,,gzip} module provides the @ref{654,,GzipFile} class, as well as the
@ref{2d05,,open()}, @ref{847,,compress()} and @ref{140e,,decompress()} convenience functions.
The @ref{654,,GzipFile} class reads and writes @code{gzip}-format files,
automatically compressing or decompressing the data so that it looks like an
ordinary @ref{13c4,,file object}.

Note that additional file formats which can be decompressed by the
@code{gzip} and @code{gunzip} programs, such  as those produced by
@code{compress} and @code{pack}, are not supported by this module.

此模組定義了以下項目：

@geindex open() (於 gzip 模組中)
@anchor{library/gzip gzip open}@anchor{2d05}
@deffn {函式} gzip.open (filename, mode='rb', compresslevel=9, encoding=None, errors=None, newline=None)

Open a gzip-compressed file in binary or text mode, returning a @ref{13c4,,file object}.

The `filename' argument can be an actual filename (a @ref{169,,str} or
@ref{192,,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{'a'}, @code{'ab'},
@code{'w'}, @code{'wb'}, @code{'x'} or @code{'xb'} for binary mode, or @code{'rt'},
@code{'at'}, @code{'wt'}, or @code{'xt'} for text mode. The default is @code{'rb'}.

The `compresslevel' argument is an integer from 0 to 9, as for the
@ref{654,,GzipFile} constructor.

For binary mode, this function is equivalent to the @ref{654,,GzipFile}
constructor: @code{GzipFile(filename, mode, compresslevel)}. In this case, the
`encoding', `errors' and `newline' arguments must not be provided.

For text mode, a @ref{654,,GzipFile} object is created, and wrapped in an
@ref{9b7,,io.TextIOWrapper} instance with the specified encoding, error
handling behavior, and line ending(s).


在 3.3 版的變更: Added support for `filename' being a file object, support for text mode,
and the `encoding', `errors' and `newline' arguments.



在 3.4 版的變更: 新增 @code{'x'}、@code{'xb'} 和 @code{'xt'} 模式的支援。



在 3.6 版的變更: 接受@ref{59b,,類路徑物件}。

@end deffn

@geindex BadGzipFile
@anchor{library/gzip gzip BadGzipFile}@anchor{be1}
@deffn {例外} gzip.BadGzipFile

An exception raised for invalid gzip files.  It inherits from @ref{2c0,,OSError}.
@ref{14da,,EOFError} and @ref{2cdf,,zlib.error} can also be raised for invalid gzip
files.


在 3.8 版被加入.

@end deffn

@geindex GzipFile (gzip 中的類別)
@anchor{library/gzip gzip GzipFile}@anchor{654}
@deffn {類別} gzip.GzipFile (filename=None, mode=None, compresslevel=9, fileobj=None, mtime=None)

Constructor for the @ref{654,,GzipFile} class, which simulates most of the
methods of a @ref{13c4,,file object}, with the exception of the @ref{1511,,truncate()}
method.  At least one of `fileobj' and `filename' must be given a non-trivial
value.

The new class instance is based on `fileobj', which can be a regular file, an
@ref{109f,,io.BytesIO} object, or any other object which simulates a file.  It
defaults to @code{None}, in which case `filename' is opened to provide a file
object.

When `fileobj' is not @code{None}, the `filename' argument is only used to be
included in the @code{gzip} file header, which may include the original
filename of the uncompressed file.  It defaults to the filename of `fileobj', if
discernible; otherwise, it defaults to the empty string, and in this case the
original filename is not included in the header.

The `mode' argument can be any of @code{'r'}, @code{'rb'}, @code{'a'}, @code{'ab'}, @code{'w'},
@code{'wb'}, @code{'x'}, or @code{'xb'}, depending on whether the file will be read or
written.  The default is the mode of `fileobj' if discernible; otherwise, the
default is @code{'rb'}.  In future Python releases the mode of `fileobj' will
not be used.  It is better to always specify `mode' for writing.

Note that the file is always opened in binary mode. To open a compressed file
in text mode, use @ref{2d05,,open()} (or wrap your @ref{654,,GzipFile} with an
@ref{9b7,,io.TextIOWrapper}).

The `compresslevel' argument is an integer from @code{0} to @code{9} controlling
the level of compression; @code{1} is fastest and produces the least
compression, and @code{9} is slowest and produces the most compression. @code{0}
is no compression. The default is @code{9}.

The optional `mtime' argument is the timestamp requested by gzip. The time
is in Unix format, i.e., seconds since 00:00:00 UTC, January 1, 1970.
If `mtime' is omitted or @code{None}, the current time is used. Use `mtime' = 0
to generate a compressed stream that does not depend on creation time.

See below for the @ref{2d06,,mtime} attribute that is set when decompressing.

Calling a @ref{654,,GzipFile} object's @code{close()} method does not close
`fileobj', since you might wish to append more material after the compressed
data.  This also allows you to pass an @ref{109f,,io.BytesIO} object opened for
writing as `fileobj', and retrieve the resulting memory buffer using the
@ref{109f,,io.BytesIO} object's @ref{2d07,,getvalue()} method.

@ref{654,,GzipFile} supports the @ref{89c,,io.BufferedIOBase} interface,
including iteration and the @ref{186,,with} statement.  Only the
@ref{1511,,truncate()} method isn't implemented.

@ref{654,,GzipFile} 也提供了以下的方法和屬性：

@geindex peek() (gzip.GzipFile 的方法)
@anchor{library/gzip gzip GzipFile peek}@anchor{140d}
@deffn {方法} peek (n)

Read `n' uncompressed bytes without advancing the file position.
The number of bytes returned may be more or less than requested.

@cartouche
@quotation 備註 
While calling @ref{140d,,peek()} does not change the file position of
the @ref{654,,GzipFile}, it may change the position of the underlying
file object (e.g. if the @ref{654,,GzipFile} was constructed with the
`fileobj' parameter).
@end quotation
@end cartouche


在 3.2 版被加入.

@end deffn

@geindex mode (gzip.GzipFile 的屬性)
@anchor{library/gzip gzip GzipFile mode}@anchor{2d08}
@deffn {屬性} mode

@code{'rb'} for reading and @code{'wb'} for writing.


在 3.13 版的變更: In previous versions it was an integer @code{1} or @code{2}.

@end deffn

@geindex mtime (gzip.GzipFile 的屬性)
@anchor{library/gzip gzip GzipFile mtime}@anchor{2d06}
@deffn {屬性} mtime

When decompressing, this attribute is set to the last timestamp in the most
recently read header.  It is an integer, holding the number of seconds
since the Unix epoch (00:00:00 UTC, January 1, 1970).
The initial value before reading any headers is @code{None}.
@end deffn

@geindex name (gzip.GzipFile 的屬性)
@anchor{library/gzip gzip GzipFile name}@anchor{72a}
@deffn {屬性} name

The path to the gzip file on disk, as a @ref{169,,str} or @ref{192,,bytes}.
Equivalent to the output of @ref{e48,,os.fspath()} on the original input path,
with no other normalization, resolution or expansion.
@end deffn


在 3.1 版的變更: Support for the @ref{186,,with} statement was added, along with the
`mtime' constructor argument and @ref{2d06,,mtime} attribute.



在 3.2 版的變更: Support for zero-padded and unseekable files was added.



在 3.3 版的變更: @ref{2d09,,io.BufferedIOBase.read1()} 方法現在已有實作。



在 3.4 版的變更: 新增 @code{'x'} 和 @code{'xb'} 模式的支援。



在 3.5 版的變更: Added support for writing arbitrary
@ref{193,,bytes-like objects}.
The @ref{1529,,read()} method now accepts an argument of
@code{None}.



在 3.6 版的變更: 接受@ref{59b,,類路徑物件}。



在 3.9 版之後被棄用: Opening @ref{654,,GzipFile} for writing without specifying the `mode'
argument is deprecated.



在 3.12 版的變更: Remove the @code{filename} attribute, use the @ref{72a,,name}
attribute instead.

@end deffn

@geindex compress() (於 gzip 模組中)
@anchor{library/gzip gzip compress}@anchor{847}
@deffn {函式} gzip.compress (data, compresslevel=9, *, mtime=0)

Compress the `data', returning a @ref{192,,bytes} object containing
the compressed data.  `compresslevel' and `mtime' have the same meaning as in
the @ref{654,,GzipFile} constructor above,
but `mtime' defaults to 0 for reproducible output.


在 3.2 版被加入.



在 3.8 版的變更: Added the `mtime' parameter for reproducible output.



在 3.11 版的變更: Speed is improved by compressing all data at once instead of in a
streamed fashion. Calls with `mtime' set to @code{0} are delegated to
@ref{848,,zlib.compress()} for better speed. In this situation the
output may contain a gzip header "OS" byte value other than 255
"unknown" as supplied by the underlying zlib implementation.



在 3.13 版的變更: The gzip header OS byte is guaranteed to be set to 255 when this function
is used as was the case in 3.10 and earlier.



在 3.14 版的變更: The `mtime' parameter now defaults to 0 for reproducible output.
For the previous behaviour of using the current time,
pass @code{None} to `mtime'.

@end deffn

@geindex decompress() (於 gzip 模組中)
@anchor{library/gzip gzip decompress}@anchor{140e}
@deffn {函式} gzip.decompress (data)

Decompress the `data', returning a @ref{192,,bytes} object containing the
uncompressed data. This function is capable of decompressing multi-member
gzip data (multiple gzip blocks concatenated together). When the data is
certain to contain only one member the @ref{f04,,zlib.decompress()} function with
`wbits' set to 31 is faster.


在 3.2 版被加入.



在 3.11 版的變更: Speed is improved by decompressing members at once in memory instead of in
a streamed fashion.

@end deffn

@menu
* 用法範例:: 
* 命令列介面: 命令列介面<3>. 

@end menu

@node 用法範例,命令列介面<3>,,gzip --- gzip 檔案的支援
@anchor{library/gzip examples-of-usage}@anchor{2d0a}@anchor{library/gzip gzip-usage-examples}@anchor{2d0b}
@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

如何壓縮一個已存在的檔案的範例：

@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

如何壓縮一個二進位字串的範例：

@example
import gzip
s_in = b"Lots of content here"
s_out = gzip.compress(s_in)
@end example


@subsubheading 也參考



@table @asis

@item @ref{139,,zlib} 模組

The basic data compression module needed to support the @code{gzip} file
format.
@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.


@node 命令列介面<3>,,用法範例,gzip --- gzip 檔案的支援
@anchor{library/gzip command-line-interface}@anchor{2d0c}@anchor{library/gzip gzip-cli}@anchor{2d0d}
@subsubsection 命令列介面


The @ref{6b,,gzip} module provides a simple command line interface to compress or
decompress files.

Once executed the @ref{6b,,gzip} module keeps the input file(s).


在 3.8 版的變更: Add a new command line interface with a usage.
By default, when you will execute the CLI, the default compression level is 6.


@menu
* 命令列選項:: 

@end menu

@node 命令列選項,,,命令列介面<3>
@anchor{library/gzip command-line-options}@anchor{2d0e}
@subsubsection 命令列選項


@geindex gzip 命令列選項; file
@anchor{library/gzip cmdoption-gzip-arg-file}@anchor{2d0f}
@deffn {Option} file

如果未指定 `file'，則從 @ref{758,,sys.stdin} 讀取。
@end deffn

@geindex gzip 命令列選項; --fast
@anchor{library/gzip cmdoption-gzip-fast}@anchor{2d10}
@deffn {Option} @w{-}@w{-}fast

Indicates the fastest compression method (less compression).
@end deffn

@geindex gzip 命令列選項; --best
@anchor{library/gzip cmdoption-gzip-best}@anchor{2d11}
@deffn {Option} @w{-}@w{-}best

Indicates the slowest compression method (best compression).
@end deffn

@geindex gzip 命令列選項; -d
@geindex gzip 命令列選項; --decompress
@anchor{library/gzip cmdoption-gzip-d}@anchor{2d12}@anchor{library/gzip cmdoption-gzip-decompress}@anchor{2d13}
@deffn {Option} @w{-}d, @w{-}@w{-}decompress

解壓縮指定的檔案。
@end deffn

@geindex gzip 命令列選項; -h
@geindex gzip 命令列選項; --help
@anchor{library/gzip cmdoption-gzip-h}@anchor{2d14}@anchor{library/gzip cmdoption-gzip-help}@anchor{2d15}
@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 --- bzip2 壓縮的支援,lzma --- 使用 LZMA 演算法進行壓縮,gzip --- gzip 檔案的支援,資料壓縮與保存
@anchor{library/bz2 doc}@anchor{2d16}@anchor{library/bz2 bz2-support-for-bzip2-compression}@anchor{2d17}@anchor{library/bz2 module-bz2}@anchor{14}@anchor{library/bz2 translation-repo}@anchor{2d18}
@subsection @code{bz2} --- @code{bzip2} 壓縮的支援


@geindex module; bz2

`原始碼：'Lib/bz2.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/bz2.py}


__________________________________________________________________


This module provides a comprehensive interface for compressing and
decompressing data using the bzip2 compression algorithm.

The @ref{14,,bz2} module contains:


@itemize *

@item 
The @ref{128e,,open()} function and @ref{a5f,,BZ2File} class for reading and
writing compressed files.

@item 
The @ref{1a19,,BZ2Compressor} and @ref{1a17,,BZ2Decompressor} classes for
incremental (de)compression.

@item 
The @ref{272a,,compress()} and @ref{128f,,decompress()} functions for one-shot
(de)compression.
@end itemize

@menu
* (De)compression of files: De compression of files. 
* Incremental (de)compression: Incremental de compression. 
* One-shot (de)compression: One-shot de compression. 
* 用法範例: 用法範例<2>. 

@end menu

@node De compression of files,Incremental de compression,,bz2 --- bzip2 壓縮的支援
@anchor{library/bz2 de-compression-of-files}@anchor{2d19}
@subsubsection (De)compression of files


@geindex open() (於 bz2 模組中)
@anchor{library/bz2 bz2 open}@anchor{128e}
@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{13c4,,file object}.

As with the constructor for @ref{a5f,,BZ2File}, the `filename' argument can be
an actual filename (a @ref{169,,str} or @ref{192,,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{a5f,,BZ2File} constructor.

For binary mode, this function is equivalent to the @ref{a5f,,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{a5f,,BZ2File} object is created, and wrapped in an
@ref{9b7,,io.TextIOWrapper} instance with the specified encoding, error
handling behavior, and line ending(s).


在 3.3 版被加入.



在 3.4 版的變更: The @code{'x'} (exclusive creation) mode was added.



在 3.6 版的變更: Accepts a @ref{59b,,path-like object}.

@end deffn

@geindex BZ2File (bz2 中的類別)
@anchor{library/bz2 bz2 BZ2File}@anchor{a5f}
@deffn {類別} bz2.BZ2File (filename, mode='r', *, compresslevel=9)

Open a bzip2-compressed file in binary mode.

If `filename' is a @ref{169,,str} or @ref{192,,bytes} object, open the named file
directly. Otherwise, `filename' should be a @ref{13c4,,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.

@ref{a5f,,BZ2File} provides all of the members specified by the
@ref{89c,,io.BufferedIOBase}, except for @ref{2c9e,,detach()}
and @ref{1511,,truncate()}.
Iteration and the @ref{186,,with} statement are supported.

@ref{a5f,,BZ2File} 也提供了以下方法和屬性：

@geindex peek() (bz2.BZ2File 的方法)
@anchor{library/bz2 bz2 BZ2File peek}@anchor{2d1a}
@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 @ref{2d1a,,peek()} does not change the file position of
the @ref{a5f,,BZ2File}, it may change the position of the underlying file
object (e.g. if the @ref{a5f,,BZ2File} was constructed by passing a file
object for `filename').
@end quotation
@end cartouche


在 3.3 版被加入.

@end deffn

@geindex fileno() (bz2.BZ2File 的方法)
@anchor{library/bz2 bz2 BZ2File fileno}@anchor{2d1b}
@deffn {方法} fileno ()

Return the file descriptor for the underlying file.


在 3.3 版被加入.

@end deffn

@geindex readable() (bz2.BZ2File 的方法)
@anchor{library/bz2 bz2 BZ2File readable}@anchor{2d1c}
@deffn {方法} readable ()

Return whether the file was opened for reading.


在 3.3 版被加入.

@end deffn

@geindex seekable() (bz2.BZ2File 的方法)
@anchor{library/bz2 bz2 BZ2File seekable}@anchor{2d1d}
@deffn {方法} seekable ()

Return whether the file supports seeking.


在 3.3 版被加入.

@end deffn

@geindex writable() (bz2.BZ2File 的方法)
@anchor{library/bz2 bz2 BZ2File writable}@anchor{2d1e}
@deffn {方法} writable ()

Return whether the file was opened for writing.


在 3.3 版被加入.

@end deffn

@geindex read1() (bz2.BZ2File 的方法)
@anchor{library/bz2 bz2 BZ2File read1}@anchor{2d1f}
@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.


在 3.3 版被加入.

@end deffn

@geindex readinto() (bz2.BZ2File 的方法)
@anchor{library/bz2 bz2 BZ2File readinto}@anchor{2d20}
@deffn {方法} readinto (b)

Read bytes into `b'.

Returns the number of bytes read (0 for EOF).


在 3.3 版被加入.

@end deffn

@geindex mode (bz2.BZ2File 的屬性)
@anchor{library/bz2 bz2 BZ2File mode}@anchor{2d21}
@deffn {屬性} mode

@code{'rb'} for reading and @code{'wb'} for writing.


在 3.13 版被加入.

@end deffn

@geindex name (bz2.BZ2File 的屬性)
@anchor{library/bz2 bz2 BZ2File name}@anchor{2d22}
@deffn {屬性} name

The bzip2 file name.  Equivalent to the @ref{2ca2,,name}
attribute of the underlying @ref{13c4,,file object}.


在 3.13 版被加入.

@end deffn


在 3.1 版的變更: Support for the @ref{186,,with} statement was added.



在 3.3 版的變更: Support was added for `filename' being a @ref{13c4,,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{1529,,read()} method now accepts an argument of
@code{None}.



在 3.6 版的變更: Accepts a @ref{59b,,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{6b,,gzip} and
@ref{8e,,lzma} have always been.

@end deffn

@node Incremental de compression,One-shot de compression,De compression of files,bz2 --- bzip2 壓縮的支援
@anchor{library/bz2 incremental-de-compression}@anchor{2d23}
@subsubsection Incremental (de)compression


@geindex BZ2Compressor (bz2 中的類別)
@anchor{library/bz2 bz2 BZ2Compressor}@anchor{1a19}
@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{272a,,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{2d24}
@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{2d25,,flush()} method to finish the compression process.
@end deffn

@geindex flush() (bz2.BZ2Compressor 的方法)
@anchor{library/bz2 bz2 BZ2Compressor flush}@anchor{2d25}
@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{1a17}
@deffn {類別} bz2.BZ2Decompressor

Create a new decompressor object. This object may be used to decompress data
incrementally. For one-shot compression, use the @ref{128f,,decompress()} function
instead.

@cartouche
@quotation 備註 
This class does not transparently handle inputs containing multiple
compressed streams, unlike @ref{128f,,decompress()} and @ref{a5f,,BZ2File}. If
you need to decompress a multi-stream input with @ref{1a17,,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{fc5}
@deffn {方法} decompress (data, max_length=-1)

Decompress `data' (a @ref{193,,bytes-like object}), returning
uncompressed data as bytes. Some of `data' may be buffered
internally, for use in later calls to @ref{128f,,decompress()}. The
returned data should be concatenated with the output of any
previous calls to @ref{128f,,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{2d26,,needs_input} attribute will
be set to @code{False}. In this case, the next call to
@ref{fc5,,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{2d26,,needs_input} attribute
will be set to @code{True}.

Attempting to decompress data after the end of stream is reached
raises an @ref{14da,,EOFError}.  Any data found after the end of the
stream is ignored and saved in the @ref{2d27,,unused_data} attribute.


在 3.5 版的變更: 新增 `max_length' 參數。

@end deffn

@geindex eof (bz2.BZ2Decompressor 的屬性)
@anchor{library/bz2 bz2 BZ2Decompressor eof}@anchor{2d28}
@deffn {屬性} eof

@code{True} if the end-of-stream marker has been reached.


在 3.3 版被加入.

@end deffn

@geindex unused_data (bz2.BZ2Decompressor 的屬性)
@anchor{library/bz2 bz2 BZ2Decompressor unused_data}@anchor{2d27}
@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{2d26}
@deffn {屬性} needs_input

@code{False} if the @ref{fc5,,decompress()} method can provide more
decompressed data before requiring new uncompressed input.


在 3.5 版被加入.

@end deffn
@end deffn

@node One-shot de compression,用法範例<2>,Incremental de compression,bz2 --- bzip2 壓縮的支援
@anchor{library/bz2 one-shot-de-compression}@anchor{2d29}
@subsubsection One-shot (de)compression


@geindex compress() (於 bz2 模組中)
@anchor{library/bz2 bz2 compress}@anchor{272a}
@deffn {函式} bz2.compress (data, compresslevel=9)

Compress `data', a @ref{193,,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{1a19,,BZ2Compressor} instead.
@end deffn

@geindex decompress() (於 bz2 模組中)
@anchor{library/bz2 bz2 decompress}@anchor{128f}
@deffn {函式} bz2.decompress (data)

Decompress `data', a @ref{193,,bytes-like object}.

If `data' is the concatenation of multiple compressed streams, decompress
all of the streams.

For incremental decompression, use a @ref{1a17,,BZ2Decompressor} instead.


在 3.3 版的變更: Support for multi-stream inputs was added.

@end deffn

@node 用法範例<2>,,One-shot de compression,bz2 --- bzip2 壓縮的支援
@anchor{library/bz2 bz2-usage-examples}@anchor{2d2a}@anchor{library/bz2 examples-of-usage}@anchor{2d2b}
@subsubsection 用法範例


Below are some examples of typical usage of the @ref{14,,bz2} module.

Using @ref{272a,,compress()} and @ref{128f,,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{1a19,,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 --- 使用 LZMA 演算法進行壓縮,zipfile --- 處理 ZIP 封存檔案,bz2 --- bzip2 壓縮的支援,資料壓縮與保存
@anchor{library/lzma doc}@anchor{2d2c}@anchor{library/lzma lzma-compression-using-the-lzma-algorithm}@anchor{2d2d}@anchor{library/lzma module-lzma}@anchor{8e}@anchor{library/lzma translation-repo}@anchor{2d2e}
@subsection @code{lzma} --- 使用 LZMA 演算法進行壓縮


@geindex module; lzma


在 3.3 版被加入.


`原始碼：'Lib/lzma.py@footnote{https://github.com/python/cpython/tree/3.14/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{1207,,LZMAFile} and @ref{a5f,,bz2.BZ2File} are `not'
thread-safe, so if you need to use a single @ref{1207,,LZMAFile} instance
from multiple threads, it is necessary to protect it with a lock.

@geindex LZMAError
@anchor{library/lzma lzma LZMAError}@anchor{2d2f}
@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:: 
* 範例: 範例<14>. 

@end menu

@node Reading and writing compressed files<2>,Compressing and decompressing data in memory<2>,,lzma --- 使用 LZMA 演算法進行壓縮
@anchor{library/lzma reading-and-writing-compressed-files}@anchor{2d30}
@subsubsection Reading and writing compressed files


@geindex open() (於 lzma 模組中)
@anchor{library/lzma lzma open}@anchor{2d31}
@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{13c4,,file object}.

The `filename' argument can be either an actual file name (given as a
@ref{169,,str}, @ref{192,,bytes} or @ref{59b,,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{1a16,,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{1a18,,LZMACompressor}.

For binary mode, this function is equivalent to the @ref{1207,,LZMAFile}
constructor: @code{LZMAFile(filename, mode, ...)}. In this case, the `encoding',
`errors' and `newline' arguments must not be provided.

For text mode, a @ref{1207,,LZMAFile} object is created, and wrapped in an
@ref{9b7,,io.TextIOWrapper} instance with the specified encoding, error
handling behavior, and line ending(s).


在 3.4 版的變更: 新增 @code{"x"}、@code{"xb"} 和 @code{"xt"} 模式的支援。



在 3.6 版的變更: Accepts a @ref{59b,,path-like object}.

@end deffn

@geindex LZMAFile (lzma 中的類別)
@anchor{library/lzma lzma LZMAFile}@anchor{1207}
@deffn {類別} lzma.LZMAFile (filename=None, mode='r', *, format=None, check=-1, preset=None, filters=None)

Open an LZMA-compressed file in binary mode.

An @ref{1207,,LZMAFile} can wrap an already-open @ref{13c4,,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{169,,str},
@ref{192,,bytes} or @ref{59b,,path-like} object). When wrapping an
existing file object, the wrapped file will not be closed when the
@ref{1207,,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{1a16,,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{1a18,,LZMACompressor}.

@ref{1207,,LZMAFile} supports all the members specified by
@ref{89c,,io.BufferedIOBase}, except for @ref{2c9e,,detach()}
and @ref{1511,,truncate()}.
Iteration and the @ref{186,,with} statement are supported.

The following method and attributes are also provided:

@geindex peek() (lzma.LZMAFile 的方法)
@anchor{library/lzma lzma LZMAFile peek}@anchor{2d32}
@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 @ref{2d32,,peek()} does not change the file position of
the @ref{1207,,LZMAFile}, it may change the position of the underlying
file object (e.g. if the @ref{1207,,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{2d33}
@deffn {屬性} mode

@code{'rb'} for reading and @code{'wb'} for writing.


在 3.13 版被加入.

@end deffn

@geindex name (lzma.LZMAFile 的屬性)
@anchor{library/lzma lzma LZMAFile name}@anchor{2d34}
@deffn {屬性} name

The lzma file name.  Equivalent to the @ref{2ca2,,name}
attribute of the underlying @ref{13c4,,file object}.


在 3.13 版被加入.

@end deffn


在 3.4 版的變更: 新增 @code{"x"} 和 @code{"xb"} 模式的支援。



在 3.5 版的變更: The @ref{1529,,read()} method now accepts an argument of
@code{None}.



在 3.6 版的變更: Accepts a @ref{59b,,path-like object}.

@end deffn

@node Compressing and decompressing data in memory<2>,Miscellaneous<2>,Reading and writing compressed files<2>,lzma --- 使用 LZMA 演算法進行壓縮
@anchor{library/lzma compressing-and-decompressing-data-in-memory}@anchor{2d35}
@subsubsection Compressing and decompressing data in memory


@geindex LZMACompressor (lzma 中的類別)
@anchor{library/lzma lzma LZMACompressor}@anchor{1a18}
@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{2d36,,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{1a16,,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{2d2f,,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
@ref{1a18,,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{2d37,,Specifying custom filter chains} for details.

@geindex compress() (lzma.LZMACompressor 的方法)
@anchor{library/lzma lzma LZMACompressor compress}@anchor{2d38}
@deffn {方法} compress (data)

Compress `data' (a @ref{192,,bytes} object), returning a @ref{192,,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
@ref{2d36,,compress()} and @ref{2d39,,flush()}. The returned data should be
concatenated with the output of any previous calls to @ref{2d36,,compress()}.
@end deffn

@geindex flush() (lzma.LZMACompressor 的方法)
@anchor{library/lzma lzma LZMACompressor flush}@anchor{2d39}
@deffn {方法} flush ()

Finish the compression process, returning a @ref{192,,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{1a16}
@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{2d3a,,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{2d2f,,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{2d37,,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{2d3a,,decompress()} and @ref{1207,,LZMAFile}. To
decompress a multi-stream input with @ref{1a16,,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{1029}
@deffn {方法} decompress (data, max_length=-1)

Decompress `data' (a @ref{193,,bytes-like object}), returning
uncompressed data as bytes. Some of `data' may be buffered
internally, for use in later calls to @ref{2d3a,,decompress()}. The
returned data should be concatenated with the output of any
previous calls to @ref{2d3a,,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{2d3b,,needs_input} attribute will
be set to @code{False}. In this case, the next call to
@ref{1029,,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{2d3b,,needs_input} attribute
will be set to @code{True}.

Attempting to decompress data after the end of stream is reached
raises an @ref{14da,,EOFError}.  Any data found after the end of the
stream is ignored and saved in the @ref{2d3c,,unused_data} attribute.


在 3.5 版的變更: 新增 `max_length' 參數。

@end deffn

@geindex check (lzma.LZMADecompressor 的屬性)
@anchor{library/lzma lzma LZMADecompressor check}@anchor{2d3d}
@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{2d3e}
@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{2d3c}
@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{2d3b}
@deffn {屬性} needs_input

@code{False} if the @ref{1029,,decompress()} method can provide more
decompressed data before requiring new uncompressed input.


在 3.5 版被加入.

@end deffn
@end deffn

@geindex compress() (於 lzma 模組中)
@anchor{library/lzma lzma compress}@anchor{2d36}
@deffn {函式} lzma.compress (data, format=FORMAT_XZ, check=-1, preset=None, filters=None)

Compress `data' (a @ref{192,,bytes} object), returning the compressed data as a
@ref{192,,bytes} object.

See @ref{1a18,,LZMACompressor} above for a description of the `format', `check',
`preset' and `filters' arguments.
@end deffn

@geindex decompress() (於 lzma 模組中)
@anchor{library/lzma lzma decompress}@anchor{2d3a}
@deffn {函式} lzma.decompress (data, format=FORMAT_AUTO, memlimit=None, filters=None)

Decompress `data' (a @ref{192,,bytes} object), returning the uncompressed data
as a @ref{192,,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{1a16,,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 --- 使用 LZMA 演算法進行壓縮
@anchor{library/lzma miscellaneous}@anchor{2d3f}
@subsubsection Miscellaneous


@geindex is_check_supported() (於 lzma 模組中)
@anchor{library/lzma lzma is_check_supported}@anchor{2d40}
@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,範例<14>,Miscellaneous<2>,lzma --- 使用 LZMA 演算法進行壓縮
@anchor{library/lzma filter-chain-specs}@anchor{2d37}@anchor{library/lzma specifying-custom-filter-chains}@anchor{2d41}
@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 範例<14>,,Specifying custom filter chains,lzma --- 使用 LZMA 演算法進行壓縮
@anchor{library/lzma examples}@anchor{2d42}
@subsubsection 範例


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 --- 處理 ZIP 封存檔案,tarfile --- 讀取與寫入 tar 封存檔案,lzma --- 使用 LZMA 演算法進行壓縮,資料壓縮與保存
@anchor{library/zipfile doc}@anchor{2d43}@anchor{library/zipfile module-zipfile}@anchor{137}@anchor{library/zipfile translation-repo}@anchor{2d44}@anchor{library/zipfile zipfile-work-with-zip-archives}@anchor{2d45}
@subsection @code{zipfile} --- 處理 ZIP 封存檔案


@geindex module; zipfile

`原始碼：'Lib/zipfile/@footnote{https://github.com/python/cpython/tree/3.14/Lib/zipfile/}


__________________________________________________________________


ZIP 檔案格式是一種常見的封存 (archive) 與壓縮標準。本模組提供了建立、讀取、寫入、附加與列出 ZIP 檔案的工具。任何對本模組的進階使用都將需要對 PKZIP Application Note@footnote{https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT} 中定義的格式有所理解。

本模組目前不處理多磁碟 ZIP 檔案。它可以處理使用 ZIP64 擴充（即大於 4 GiB 的 ZIP 檔案）的 ZIP 檔案。它支援解密 ZIP 封存檔案中的加密檔案，但目前無法建立加密檔案。解密速度極慢，因為它是在原生 Python 中實作，而不是 C。

本模組定義了以下項目：

@geindex BadZipFile
@anchor{library/zipfile zipfile BadZipFile}@anchor{1a97}
@deffn {例外} zipfile.BadZipFile

對於損壞的 ZIP 檔案所引發的錯誤。


在 3.2 版被加入.

@end deffn

@geindex BadZipfile
@anchor{library/zipfile zipfile BadZipfile}@anchor{2d46}
@deffn {例外} zipfile.BadZipfile

@ref{1a97,,BadZipFile} 的別名，為了與舊版 Python 相容。


在 3.2 版之後被棄用.

@end deffn

@geindex LargeZipFile
@anchor{library/zipfile zipfile LargeZipFile}@anchor{2d47}
@deffn {例外} zipfile.LargeZipFile

當 ZIP 檔案需要 ZIP64 功能但該功能未被啟用時所引發的錯誤。
@end deffn


@deffn {類別} zipfile.ZipFile

用於讀取和寫入 ZIP 檔案的類別。有關建構函式的詳細資訊，請參閱 @ref{2d48,,ZipFile 物件} 章節。
@end deffn


@deffn {類別} zipfile.Path

實作了 @ref{266,,pathlib.Path} 所提供介面子集的類別，包括完整的 @ref{2f9,,importlib.resources.abc.Traversable} 介面。


在 3.8 版被加入.

@end deffn


@deffn {類別} zipfile.PyZipFile

用於建立包含 Python 函式庫的 ZIP 封存檔案的類別。
@end deffn

@geindex ZipInfo (zipfile 中的類別)
@anchor{library/zipfile zipfile ZipInfo}@anchor{2cb}
@deffn {類別} zipfile.ZipInfo (filename='NoName', date_time=(1980, 1, 1, 0, 0, 0))

用於表示封存檔案中成員資訊的類別。此類別的實例由 @ref{8cb,,ZipFile} 物件的 @ref{2d49,,getinfo()} 和 @ref{2d4a,,infolist()} 方法回傳。大多數 @ref{137,,zipfile} 模組的使用者不需要建立這些實例，而只需使用本模組所建立的。`filename' 應為封存成員的完整名稱，而 `date_time' 應為一個包含六個欄位的元組，用以描述檔案的最後修改時間；這些欄位在 @ref{2d4b,,ZipInfo 物件} 章節中有所描述。


在 3.13 版的變更: 新增了一個公開的 @code{compress_level} 屬性，以公開先前受保護的 @code{_compresslevel}。為了向後相容，舊的受保護名稱仍可作為一個特性繼續運作。


@geindex _for_archive() (zipfile.ZipInfo 的方法)
@anchor{library/zipfile zipfile ZipInfo _for_archive}@anchor{2ca}
@deffn {方法} _for_archive (archive)

Resolve the date_time, compression attributes, and external attributes
to suitable defaults as used by @ref{2cc,,ZipFile.writestr()}.

Returns self for chaining.


在 3.14 版被加入.

@end deffn
@end deffn

@geindex is_zipfile() (於 zipfile 模組中)
@anchor{library/zipfile zipfile is_zipfile}@anchor{152b}
@deffn {函式} zipfile.is_zipfile (filename)

如果 `filename' 根據其魔術數字（magic number）是一個有效的 ZIP 檔案，則回傳 @code{True}，否則回傳 @code{False}。`filename' 也可以是一個檔案或類檔案物件。


在 3.1 版的變更: 支援檔案和類檔案物件。

@end deffn

@geindex ZIP_STORED (於 zipfile 模組中)
@anchor{library/zipfile zipfile ZIP_STORED}@anchor{2d4c}
@deffn {資料} zipfile.ZIP_STORED

用於未壓縮封存成員的數值常數。
@end deffn

@geindex ZIP_DEFLATED (於 zipfile 模組中)
@anchor{library/zipfile zipfile ZIP_DEFLATED}@anchor{2d4d}
@deffn {資料} zipfile.ZIP_DEFLATED

用於常用的 ZIP 壓縮方法的數值常數。這需要 @ref{139,,zlib} 模組。
@end deffn

@geindex ZIP_BZIP2 (於 zipfile 模組中)
@anchor{library/zipfile zipfile ZIP_BZIP2}@anchor{2d4e}
@deffn {資料} zipfile.ZIP_BZIP2

用於 BZIP2 壓縮方法的數值常數。這需要 @ref{14,,bz2} 模組。


在 3.3 版被加入.

@end deffn

@geindex ZIP_LZMA (於 zipfile 模組中)
@anchor{library/zipfile zipfile ZIP_LZMA}@anchor{2d4f}
@deffn {資料} zipfile.ZIP_LZMA

用於 LZMA 壓縮方法的數值常數。這需要 @ref{8e,,lzma} 模組。


在 3.3 版被加入.

@end deffn

@geindex ZIP_ZSTANDARD (於 zipfile 模組中)
@anchor{library/zipfile zipfile ZIP_ZSTANDARD}@anchor{2d50}
@deffn {資料} zipfile.ZIP_ZSTANDARD

用於 Zstandard 壓縮方法的數值常數。這需要 @ref{23,,compression.zstd} 模組。

@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


在 3.14 版被加入.

@end deffn

@cartouche
@quotation 備註 
ZIP 檔案格式規範自 2001 年起已包含對 bzip2 壓縮的支援、自 2006 年起支援 LZMA 壓縮、自 2020 年起支援 Zstandard 壓縮。然而某些工具（包括舊版的 Python）不支援這些壓縮方法，可能會完全拒絕處理該 ZIP 檔案，或無法解壓縮個別檔案。
@end quotation
@end cartouche


@subsubheading 也參考



@table @asis

@item PKZIP Application Note@footnote{https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT}

由 Phil Katz（該格式與所用演算法的創造者）所撰寫的關於 ZIP 檔案格式的文件。

@item Info-ZIP 首頁@footnote{https://infozip.sourceforge.net/}

關於 Info-ZIP 專案的 ZIP 封存程式和開發函式庫的資訊。
@end table


@menu
* ZipFile 物件:: 
* Path 物件:: 
* PyZipFile 物件:: 
* ZipInfo 物件:: 
* 命令列介面: 命令列介面<4>. 
* 解壓縮的陷阱:: 

@end menu

@node ZipFile 物件,Path 物件,,zipfile --- 處理 ZIP 封存檔案
@anchor{library/zipfile id1}@anchor{2d51}@anchor{library/zipfile zipfile-objects}@anchor{2d48}
@subsubsection ZipFile 物件


@geindex ZipFile (zipfile 中的類別)
@anchor{library/zipfile zipfile ZipFile}@anchor{8cb}
@deffn {類別} zipfile.ZipFile (file, mode='r', compression=ZIP_STORED, allowZip64=True, compresslevel=None, *, strict_timestamps=True, metadata_encoding=None)

開啟一個 ZIP 檔案，其中 `file' 可以是一個檔案的路徑（一個字串）、一個類檔案物件或一個 @ref{59b,,path-like object}。

`mode' 參數應為 @code{'r'} 來讀取一個現有檔案、@code{'w'} 來清空並寫入一個新檔案、@code{'a'} 來附加到一個現有檔案，或 @code{'x'} 來獨佔性地建立並寫入一個新檔案。如果 `mode' 為 @code{'x'} 且 `file' 指向一個現有檔案，將會引發 @ref{121b,,FileExistsError}。如果 `mode' 為 @code{'a'} 且 `file' 指向一個現有的 ZIP 檔案，則會將額外的檔案加入其中。如果 `file' 並非指向一個 ZIP 檔案，則一個新的 ZIP 封存檔案會被附加到該檔案之後。這適用於將一個 ZIP 封存檔案附加到另一個檔案（例如 @code{python.exe}）。如果 `mode' 為 @code{'a'} 且檔案完全不存在，它會被建立。如果 `mode' 為 @code{'r'} 或 @code{'a'}，該檔案應為可定位的 (seekable)。

`compression' 是寫入封存檔案時要使用的 ZIP 壓縮方法，應為 @ref{2d4c,,ZIP_STORED}、@ref{2d4d,,ZIP_DEFLATED}、@ref{2d4e,,ZIP_BZIP2}、@ref{2d4f,,ZIP_LZMA} 或 @ref{2d50,,ZIP_ZSTANDARD}；無法識別的值將導致引發 @ref{369,,NotImplementedError}。如果指定了 @ref{2d4d,,ZIP_DEFLATED}、@ref{2d4e,,ZIP_BZIP2}、@ref{2d4f,,ZIP_LZMA} 或 @ref{2d50,,ZIP_ZSTANDARD}，但對應的模組（@ref{139,,zlib}、@ref{14,,bz2}、@ref{8e,,lzma} 或 @ref{23,,compression.zstd}）不可用，則會引發 @ref{244,,RuntimeError}。預設為 @ref{2d4c,,ZIP_STORED}。

如果 `allowZip64' 為 @code{True}（預設值），當 zipfile 大於 4 GiB 時，zipfile 將會建立使用 ZIP64 擴充的 ZIP 檔案。如果為 @code{false}，當 ZIP 檔案需要 ZIP64 擴充時，@ref{137,,zipfile} 將會引發一個例外。

`compresslevel' 參數控制寫入檔案到封存時使用的壓縮層級。當使用 @ref{2d4c,,ZIP_STORED} 或 @ref{2d4f,,ZIP_LZMA} 時，它沒有效果。當使用 @ref{2d4d,,ZIP_DEFLATED} 時，接受整數 @code{0} 到 @code{9}（更多資訊請參閱 @ref{2ce6,,zlib}）。當使用 @ref{2d4e,,ZIP_BZIP2} 時，接受整數 @code{1} 到 @code{9}（更多資訊請參閱 @ref{a5f,,bz2}）。當使用 @ref{2d50,,ZIP_ZSTANDARD} 時，通常接受整數 @code{-131072} 到 @code{22}（更多關於檢索有效值及其含義，請參閱 @ref{2ca4,,CompressionParameter.compression_level}）。

`strict_timestamps' 引數，當設為 @code{False} 時，允許壓縮早於 1980-01-01 的檔案，代價是將時間戳記設為 1980-01-01。對於晚於 2107-12-31 的檔案，也會有類似的行為，時間戳記同樣會被設為極限值。

當 mode 為 @code{'r'} 時，`metadata_encoding' 可以設為一個編解碼器的名稱，該編解碼器將被用來解碼元資料，例如成員名稱和 ZIP 註解。

如果檔案以 @code{'w'}、@code{'x'} 或 @code{'a'} 模式建立，然後在沒有向封存檔案中加入任何檔案的情況下 @ref{2d52,,關閉}，則適用於空封存檔案的 ZIP 結構將被寫入檔案中。

ZipFile 也是一個情境管理器，因此支援 @ref{186,,with} 陳述式。在範例中，`myzip' 在 @code{with} 陳述式的程式碼區塊執行完畢後會被關閉 --- 即使發生例外也是如此：

@example
with ZipFile('spam.zip', 'w') as myzip:
    myzip.write('eggs.txt')
@end example

@cartouche
@quotation 備註 
`metadata_encoding' 是 ZipFile 的一個實例範圍設定。目前無法以每個成員為基礎來設定此項。

此屬性是針對舊版實作的變通方法，這些實作會以當前區域編碼或頁碼（主要在 Windows 上）產生帶有名稱的封存檔案。根據 .ZIP 標準，元資料的編碼可以透過封存檔案標頭中的一個旗標指定為 IBM 頁碼（預設）或 UTF-8。該旗標的優先級高於 `metadata_encoding'，後者是 Python 特有的擴充。
@end quotation
@end cartouche


在 3.2 版的變更: 新增 @ref{8cb,,ZipFile} 作為情境管理器使用的能力。



在 3.3 版的變更: 新增對於 @ref{14,,bzip2} 和 @ref{8e,,lzma} 壓縮的支援。



在 3.4 版的變更: ZIP64 擴充預設為啟用。



在 3.5 版的變更: 新增了對寫入不可定位的 (unseekable) 串流的支援。新增了對 @code{'x'} 模式的支援。



在 3.6 版的變更: 先前，對於無法識別的壓縮值，會引發一個單純的 @ref{244,,RuntimeError}。



在 3.6.2 版的變更: `file' 參數接受一個 @ref{59b,,path-like object}。



在 3.7 版的變更: 新增 `compresslevel' 參數。



在 3.8 版的變更: `strict_timestamps' 僅限關鍵字參數。



在 3.11 版的變更: 新增了在讀取 zipfile 目錄和檔案標頭中的元資料時，可指定成員名稱編碼的支援。

@end deffn

@geindex close() (zipfile.ZipFile 的方法)
@anchor{library/zipfile zipfile ZipFile close}@anchor{2d52}
@deffn {方法} ZipFile.close ()

關閉封存檔案。你必須在結束程式前呼叫 @ref{2d52,,close()}，否則必要的記錄將不會被寫入。
@end deffn

@geindex getinfo() (zipfile.ZipFile 的方法)
@anchor{library/zipfile zipfile ZipFile getinfo}@anchor{2d49}
@deffn {方法} ZipFile.getinfo (name)

回傳一個帶有關於封存成員 `name' 資訊的 @ref{2cb,,ZipInfo} 物件。對一個目前不包含在封存檔案中的名稱呼叫 @ref{2d49,,getinfo()} 將會引發 @ref{5df,,KeyError}。
@end deffn

@geindex infolist() (zipfile.ZipFile 的方法)
@anchor{library/zipfile zipfile ZipFile infolist}@anchor{2d4a}
@deffn {方法} ZipFile.infolist ()

回傳一個串列，其中為每個封存成員包含一個 @ref{2cb,,ZipInfo} 物件。如果開啟的是一個現有的封存檔案，這些物件的順序與它們在磁碟上實際 ZIP 檔案中的條目順序相同。
@end deffn

@geindex namelist() (zipfile.ZipFile 的方法)
@anchor{library/zipfile zipfile ZipFile namelist}@anchor{2d53}
@deffn {方法} ZipFile.namelist ()

依名稱回傳封存成員的串列。
@end deffn

@geindex open() (zipfile.ZipFile 的方法)
@anchor{library/zipfile zipfile ZipFile open}@anchor{655}
@deffn {方法} ZipFile.open (name, mode='r', pwd=None, *, force_zip64=False)

以二進位類檔案物件的形式存取封存檔案中的一個成員。`name' 可以是封存檔案內的檔案名稱，或是一個 @ref{2cb,,ZipInfo} 物件。`mode' 參數如果包含，則必須是 @code{'r'}（預設值）或 @code{'w'}。`pwd' 是用於解密加密 ZIP 檔案的密碼，為一個 @ref{192,,bytes} 物件。

@ref{655,,open()} 也是一個情境管理器，因此支援 @ref{186,,with} 陳述式：

@example
with ZipFile('spam.zip') as myzip:
    with myzip.open('eggs.txt') as myfile:
        print(myfile.read())
@end example

在 `mode' 為 @code{'r'} 時，該類檔案物件（@code{ZipExtFile}）是唯讀的，並提供以下方法：@ref{1529,,read()}、@ref{152a,,readline()}、@ref{264c,,readlines()}、@ref{148d,,seek()}、@ref{15a4,,tell()}、@ref{1f71,,__iter__()}、@ref{14ce,,__next__()}。這些物件可以獨立於 ZipFile 運作。

在 @code{mode='w'} 時，會回傳一個可寫的檔案控點 (file handle)，它支援 @ref{ed2,,write()} 方法。當一個可寫的檔案控點開啟時，嘗試讀取或寫入 ZIP 檔案中的其他檔案將會引發 @ref{2eb,,ValueError}。

在這兩種情況下，該類檔案物件也具有 @code{name} 屬性，它相當於封存檔案內的檔案名稱，以及 @code{mode} 屬性，其值為 @code{'rb'} 或 @code{'wb'}，取決於輸入的模式。

寫入檔案時，如果檔案大小預先未知但可能超過 2 GiB，請傳入 @code{force_zip64=True} 以確保標頭格式能夠支援大檔案。如果檔案大小預先已知，請建構一個設定了 @ref{2d54,,file_size} 的 @ref{2cb,,ZipInfo} 物件，並將其用作 `name' 參數。

@cartouche
@quotation 備註 
@ref{655,,open()}、@ref{2d55,,read()} 和 @ref{2d56,,extract()} 方法可以接受一個檔名或一個 @ref{2cb,,ZipInfo} 物件。當你嘗試讀取一個包含重複名稱成員的 ZIP 檔案時，你會發現這很有用。
@end quotation
@end cartouche


在 3.6 版的變更: 移除了對 @code{mode='U'} 的支援。請使用 @ref{9b7,,io.TextIOWrapper} 以 @ref{f30,,universal newlines} 模式讀取壓縮的文字檔。



在 3.6 版的變更: @ref{655,,ZipFile.open()} 現在可以用於以 @code{mode='w'} 選項將檔案寫入封存檔案。



在 3.6 版的變更: 在一個已關閉的 ZipFile 上呼叫 @ref{655,,open()} 將會引發 @ref{2eb,,ValueError}。先前，會引發一個 @ref{244,,RuntimeError}。



在 3.13 版的變更: 為可寫的類檔案物件新增了 @code{name} 和 @code{mode} 屬性。可讀的類檔案物件的 @code{mode} 屬性值從 @code{'r'} 變更為 @code{'rb'}。

@end deffn

@geindex extract() (zipfile.ZipFile 的方法)
@anchor{library/zipfile zipfile ZipFile extract}@anchor{2d56}
@deffn {方法} ZipFile.extract (member, path=None, pwd=None)

從封存檔案中解壓縮一個成員到目前工作目錄；`member' 必須是其完整名稱或一個 @ref{2cb,,ZipInfo} 物件。其檔案資訊會被盡可能精確地解壓縮。`path' 指定一個不同的目錄來解壓縮。`member' 可以是一個檔名或一個 @ref{2cb,,ZipInfo} 物件。`pwd' 是用於加密檔案的密碼，為一個 @ref{192,,bytes} 物件。

回傳建立的正規化路徑（一個目錄或新檔案）。

@cartouche
@quotation 備註 
如果成員檔名是絕對路徑，磁碟機/UNC 共享點和開頭的（反）斜線將被移除，例如：在 Unix 上 @code{///foo/bar} 變成 @code{foo/bar}，在 Windows 上 @code{C:\foo\bar} 變成 @code{foo\bar}。並且成員檔名中所有的 @code{".."} 元件將被移除，例如：@code{../../foo../../ba..r} 變成 @code{foo../ba..r}。在 Windows 上，非法字元（@code{:}、@code{<}、@code{>}、@code{|}、@code{"}、@code{?} 和 @code{*}）會被底線（@code{_}）取代。
@end quotation
@end cartouche


在 3.6 版的變更: 在一個已關閉的 ZipFile 上呼叫 @ref{2d56,,extract()} 將會引發 @ref{2eb,,ValueError}。先前，會引發一個 @ref{244,,RuntimeError}。



在 3.6.2 版的變更: `path' 參數接受一個 @ref{59b,,path-like object}。

@end deffn

@geindex extractall() (zipfile.ZipFile 的方法)
@anchor{library/zipfile zipfile ZipFile extractall}@anchor{2d57}
@deffn {方法} ZipFile.extractall (path=None, members=None, pwd=None)

從封存檔案中解壓縮所有成員到目前工作目錄。`path' 指定一個不同的目錄來解壓縮。`members' 是可選的，且必須是 @ref{2d53,,namelist()} 回傳的串列的子集。`pwd' 是用於加密檔案的密碼，為一個 @ref{192,,bytes} 物件。

@cartouche
@quotation 警告 
絕不要在未經事先檢查的情況下，從不受信任的來源解壓縮封存檔案。檔案有可能被建立在 `path' 之外，例如，成員具有以 @code{"/"} 開頭的絕對檔名或帶有兩個點 @code{".."} 的檔名。本模組會試圖防止這種情況。請參閱 @ref{2d56,,extract()} 的註解。
@end quotation
@end cartouche


在 3.6 版的變更: 在一個已關閉的 ZipFile 上呼叫 @ref{2d57,,extractall()} 將會引發 @ref{2eb,,ValueError}。先前，會引發一個 @ref{244,,RuntimeError}。



在 3.6.2 版的變更: `path' 參數接受一個 @ref{59b,,path-like object}。

@end deffn

@geindex printdir() (zipfile.ZipFile 的方法)
@anchor{library/zipfile zipfile ZipFile printdir}@anchor{2d58}
@deffn {方法} ZipFile.printdir ()

將封存檔案的內容目錄印出到 @code{sys.stdout}。
@end deffn

@geindex setpassword() (zipfile.ZipFile 的方法)
@anchor{library/zipfile zipfile ZipFile setpassword}@anchor{2d59}
@deffn {方法} ZipFile.setpassword (pwd)

設定 `pwd'（一個 @ref{192,,bytes} 物件）為解壓縮加密檔案的預設密碼。
@end deffn

@geindex read() (zipfile.ZipFile 的方法)
@anchor{library/zipfile zipfile ZipFile read}@anchor{2d55}
@deffn {方法} ZipFile.read (name, pwd=None)

回傳封存檔案中 `name' 檔案的位元組。`name' 是封存檔案中檔案的名稱，或是一個 @ref{2cb,,ZipInfo} 物件。封存檔案必須以讀取或附加模式開啟。`pwd' 是用於加密檔案的密碼，為一個 @ref{192,,bytes} 物件，如果指定，將會覆寫用 @ref{2d59,,setpassword()} 設定的預設密碼。在一個使用 @ref{2d4c,,ZIP_STORED}、@ref{2d4d,,ZIP_DEFLATED}、@ref{2d4e,,ZIP_BZIP2}、@ref{2d4f,,ZIP_LZMA} 或 @ref{2d50,,ZIP_ZSTANDARD} 以外壓縮方法的 ZipFile 上呼叫 @ref{2d55,,read()} 將會引發 @ref{369,,NotImplementedError}。如果對應的壓縮模組不可用，也會引發一個錯誤。


在 3.6 版的變更: 在一個已關閉的 ZipFile 上呼叫 @ref{2d55,,read()} 將會引發 @ref{2eb,,ValueError}。先前，會引發一個 @ref{244,,RuntimeError}。

@end deffn

@geindex testzip() (zipfile.ZipFile 的方法)
@anchor{library/zipfile zipfile ZipFile testzip}@anchor{2d5a}
@deffn {方法} ZipFile.testzip ()

讀取封存檔案中的所有檔案，並檢查它們的 CRC 和檔案標頭。回傳第一個損壞檔案的名稱，否則回傳 @code{None}。


在 3.6 版的變更: 在一個已關閉的 ZipFile 上呼叫 @ref{2d5a,,testzip()} 將會引發 @ref{2eb,,ValueError}。先前，會引發一個 @ref{244,,RuntimeError}。

@end deffn

@geindex write() (zipfile.ZipFile 的方法)
@anchor{library/zipfile zipfile ZipFile write}@anchor{f44}
@deffn {方法} ZipFile.write (filename, arcname=None, compress_type=None, compresslevel=None)

將名為 `filename' 的檔案寫入封存檔案，並給予它封存名稱 `arcname*（預設情況下，這將與 *filename' 相同，但不含磁碟機代號且移除了開頭的路徑分隔符）。如果給定，`compress_type' 將覆寫為建構函式中 `compression' 參數為新條目指定的值。同樣地，如果給定 `compresslevel'，它將覆寫建構函式。封存檔案必須以 @code{'w'}、@code{'x'} 或 @code{'a'} 模式開啟。

@cartouche
@quotation 備註 
ZIP 檔案標準在歷史上並未指定元資料編碼，但為了互通性 (interoperability) 強烈建議使用 CP437（原始的 IBM PC 編碼）。近期的版本允許（僅）使用 UTF-8。在本模組中，如果成員名稱包含任何非 ASCII 字元，將會自動使用 UTF-8 來寫入。無法以 ASCII 或 UTF-8 以外的任何編碼寫入成員名稱。
@end quotation
@end cartouche

@cartouche
@quotation 備註 
封存名稱應相對於封存檔案的根目錄，也就是說，它們不應以路徑分隔符開頭。
@end quotation
@end cartouche

@cartouche
@quotation 備註 
如果 @code{arcname}（或在未給定 @code{arcname} 時的 @code{filename}）包含一個空位元組，封存檔案中該檔案的名稱將在空位元組處被截斷。
@end quotation
@end cartouche

@cartouche
@quotation 備註 
檔名中開頭的斜線可能導致在 Windows 系統上的某些 zip 程式中無法開啟該封存檔案。
@end quotation
@end cartouche


在 3.6 版的變更: 在以 @code{'r'} 模式建立的 ZipFile 或一個已關閉的 ZipFile 上呼叫 @ref{f44,,write()} 將會引發 @ref{2eb,,ValueError}。先前，會引發一個 @ref{244,,RuntimeError}。

@end deffn

@geindex writestr() (zipfile.ZipFile 的方法)
@anchor{library/zipfile zipfile ZipFile writestr}@anchor{2cc}
@deffn {方法} ZipFile.writestr (zinfo_or_arcname, data, compress_type=None, compresslevel=None)

將一個檔案寫入封存檔案。內容為 `data'，它可以是一個 @ref{169,,str} 或一個 @ref{192,,bytes} 實例；如果它是一個 @ref{169,,str}，它會先被編碼為 UTF-8。`zinfo_or_arcname' 是它在封存檔案中將被賦予的檔案名稱，或是一個 @ref{2cb,,ZipInfo} 實例。如果它是一個實例，則至少必須給定檔名、日期和時間。如果它是一個名稱，則日期和時間被設為目前的日期和時間。封存檔案必須以 @code{'w'}、@code{'x'} 或 @code{'a'} 模式開啟。

如果給定，`compress_type' 將覆寫為建構函式中 `compression' 參數為新條目指定的值，或覆寫 `zinfo_or_arcname'（如果它是一個 @ref{2cb,,ZipInfo} 實例）中的值。同樣地，如果給定 `compresslevel'，它將覆寫建構函式。

@cartouche
@quotation 備註 
當傳遞一個 @ref{2cb,,ZipInfo} 實例作為 `zinfo_or_arcname' 參數時，所使用的壓縮方法將是給定的 @ref{2cb,,ZipInfo} 實例的 `compress_type' 成員中指定的方法。預設情況下，@ref{2cb,,ZipInfo} 建構函式將此成員設為 @ref{2d4c,,ZIP_STORED}。
@end quotation
@end cartouche


在 3.2 版的變更: `compress_type' 引數。



在 3.6 版的變更: 在以 @code{'r'} 模式建立的 ZipFile 或一個已關閉的 ZipFile 上呼叫 @ref{2cc,,writestr()} 將會引發 @ref{2eb,,ValueError}。先前，會引發一個 @ref{244,,RuntimeError}。

@end deffn

@geindex mkdir() (zipfile.ZipFile 的方法)
@anchor{library/zipfile zipfile ZipFile mkdir}@anchor{8cc}
@deffn {方法} ZipFile.mkdir (zinfo_or_directory, mode=511)

在封存檔案內建立一個目錄。如果 `zinfo_or_directory' 是一個字串，則會在封存檔案內以 `mode' 引數中指定的模式建立一個目錄。然而，如果 `zinfo_or_directory' 是一個 @ref{2cb,,ZipInfo} 實例，則 `mode' 引數會被忽略。

封存檔案必須以 @code{'w'}、@code{'x'} 或 @code{'a'} 模式開啟。


在 3.11 版被加入.

@end deffn

以下資料屬性也可用：

@geindex filename (zipfile.ZipFile 的屬性)
@anchor{library/zipfile zipfile ZipFile filename}@anchor{2d5b}
@deffn {屬性} ZipFile.filename

ZIP 檔案的名稱。
@end deffn

@geindex debug (zipfile.ZipFile 的屬性)
@anchor{library/zipfile zipfile ZipFile debug}@anchor{2d5c}
@deffn {屬性} ZipFile.debug

要使用的偵錯輸出層級。可以從 @code{0}（預設，無輸出）設定到 @code{3}（最多輸出）。偵錯資訊會被寫入到 @code{sys.stdout}。
@end deffn

@geindex comment (zipfile.ZipFile 的屬性)
@anchor{library/zipfile zipfile ZipFile comment}@anchor{2d5d}
@deffn {屬性} ZipFile.comment

與 ZIP 檔案關聯的註解，為一個 @ref{192,,bytes} 物件。如果為一個以 @code{'w'}、@code{'x'} 或 @code{'a'} 模式建立的 @ref{8cb,,ZipFile} 實例指派註解，其長度不應超過 65535 位元組。超過此長度的註解將被截斷。
@end deffn

@node Path 物件,PyZipFile 物件,ZipFile 物件,zipfile --- 處理 ZIP 封存檔案
@anchor{library/zipfile id2}@anchor{2d5e}@anchor{library/zipfile path-objects}@anchor{2d5f}
@subsubsection Path 物件


@geindex Path (zipfile 中的類別)
@anchor{library/zipfile zipfile Path}@anchor{8cd}
@deffn {類別} zipfile.Path (root, at='@w{'})

從一個 @code{root} zipfile（它可以是一個 @ref{8cb,,ZipFile} 實例或一個適合傳遞給 @ref{8cb,,ZipFile} 建構函式的 @code{file}）建構一個 Path 物件。

@code{at} 指定此 Path 在 zipfile 中的位置，例如 'dir/file.txt'、'dir/' 或 '@w{'}。預設為空字串，表示根目錄。

@cartouche
@quotation 備註 
@ref{8cd,,Path} 類別不會清理 ZIP 封存檔案內的檔名。與 @ref{2d56,,ZipFile.extract()} 和 @ref{2d57,,ZipFile.extractall()} 方法不同，呼叫者有責任驗證或清理檔名，以防止路徑遍歷漏洞（例如，包含 ".." 或絕對路徑的檔名）。在處理不受信任的封存檔案時，請考慮使用 @ref{151b,,os.path.abspath()} 解析檔名，並使用 @ref{1038,,os.path.commonpath()} 與目標目錄進行核對。
@end quotation
@end cartouche
@end deffn

Path 物件公開了 @ref{266,,pathlib.Path} 物件的以下特性：

Path 物件可以使用 @code{/} 運算子或 @code{joinpath} 來遍歷。

@geindex name (zipfile.Path 的屬性)
@anchor{library/zipfile zipfile Path name}@anchor{2d60}
@deffn {屬性} Path.name

最後的路徑元件。
@end deffn

@geindex open() (zipfile.Path 的方法)
@anchor{library/zipfile zipfile Path open}@anchor{1872}
@deffn {方法} Path.open (mode='r', *, pwd, **)

在目前路徑上呼叫 @ref{655,,ZipFile.open()}。允許透過支援的模式 'r'、'w'、'rb'、'wb' 以讀取或寫入、文字或二進位模式開啟。當以文字模式開啟時，位置引數和關鍵字引數會被傳遞給 @ref{9b7,,io.TextIOWrapper}，否則會被忽略。@code{pwd} 是傳遞給 @ref{655,,ZipFile.open()} 的 @code{pwd} 參數。


在 3.9 版的變更: 新增了對 open 的文字和二進位模式的支援。預設模式現在是文字模式。



在 3.11.2 版的變更: @code{encoding} 參數可以作為位置引數提供，而不會導致 @ref{198,,TypeError}，就像在 3.9 中一樣。需要與未修補的 3.10 和 3.11 版本相容的程式碼，必須將所有 @ref{9b7,,io.TextIOWrapper} 引數，包括 @code{encoding}，作為關鍵字傳遞。

@end deffn

@geindex iterdir() (zipfile.Path 的方法)
@anchor{library/zipfile zipfile Path iterdir}@anchor{2d61}
@deffn {方法} Path.iterdir ()

列舉目前目錄的子項目。
@end deffn

@geindex is_dir() (zipfile.Path 的方法)
@anchor{library/zipfile zipfile Path is_dir}@anchor{2d62}
@deffn {方法} Path.is_dir ()

如果目前情境參照到一個目錄，則回傳 @code{True}。
@end deffn

@geindex is_file() (zipfile.Path 的方法)
@anchor{library/zipfile zipfile Path is_file}@anchor{2d63}
@deffn {方法} Path.is_file ()

如果目前情境參照到一個檔案，則回傳 @code{True}。
@end deffn

@geindex is_symlink() (zipfile.Path 的方法)
@anchor{library/zipfile zipfile Path is_symlink}@anchor{2d64}
@deffn {方法} Path.is_symlink ()

如果目前情境參照到一個符號連結，則回傳 @code{True}。


在 3.12 版被加入.



在 3.13 版的變更: 先前，@code{is_symlink} 會無條件地回傳 @code{False}。

@end deffn

@geindex exists() (zipfile.Path 的方法)
@anchor{library/zipfile zipfile Path exists}@anchor{2d65}
@deffn {方法} Path.exists ()

如果目前情境參照到 zip 檔案中的一個檔案或目錄，則回傳 @code{True}。
@end deffn

@geindex Path.suffix (於 zipfile 模組中)
@anchor{library/zipfile zipfile Path suffix}@anchor{8cf}
@deffn {資料} Path.suffix

最後一個元件中以點分隔的最後一部分（如果有的話）。這通常被稱為副檔名。


在 3.11 版被加入: 新增 @ref{8cf,,Path.suffix} 特性。

@end deffn

@geindex Path.stem (於 zipfile 模組中)
@anchor{library/zipfile zipfile Path stem}@anchor{8ce}
@deffn {資料} Path.stem

最後的路徑元件，不含其後綴。


在 3.11 版被加入: 新增 @ref{8ce,,Path.stem} 特性。

@end deffn

@geindex Path.suffixes (於 zipfile 模組中)
@anchor{library/zipfile zipfile Path suffixes}@anchor{8d0}
@deffn {資料} Path.suffixes

路徑的後綴串列，通常稱為副檔名。


在 3.11 版被加入: 新增 @ref{8d0,,Path.suffixes} 特性。

@end deffn

@geindex read_text() (zipfile.Path 的方法)
@anchor{library/zipfile zipfile Path read_text}@anchor{1a29}
@deffn {方法} Path.read_text (*, **)

將目前檔案讀取為 unicode 文字。位置引數和關鍵字引數會被傳遞給 @ref{9b7,,io.TextIOWrapper}（但 @code{buffer} 會根據情境隱式處理）。


在 3.11.2 版的變更: @code{encoding} 參數可以作為位置引數提供，而不會導致 @ref{198,,TypeError}，就像在 3.9 中一樣。需要與未修補的 3.10 和 3.11 版本相容的程式碼，必須將所有 @ref{9b7,,io.TextIOWrapper} 引數，包括 @code{encoding}，作為關鍵字傳遞。

@end deffn

@geindex read_bytes() (zipfile.Path 的方法)
@anchor{library/zipfile zipfile Path read_bytes}@anchor{2d66}
@deffn {方法} Path.read_bytes ()

將目前檔案讀取為位元組。
@end deffn

@geindex joinpath() (zipfile.Path 的方法)
@anchor{library/zipfile zipfile Path joinpath}@anchor{2d67}
@deffn {方法} Path.joinpath (*other)

回傳一個新的 Path 物件，並將每個 `other' 引數加入。以下是等效的：

@example
>>> Path(...).joinpath('child').joinpath('grandchild')
>>> Path(...).joinpath('child', 'grandchild')
>>> Path(...) / 'child' / 'grandchild'
@end example


在 3.10 版的變更: 在 3.10 之前，@code{joinpath} 沒有文件記載，且只接受一個參數。

@end deffn

zipp@footnote{https://pypi.org/project/zipp/} 專案為舊版 Python 提供了最新的 path 物件功能的向後移植版本。使用 @code{zipp.Path} 來取代 @code{zipfile.Path} 以提早使用變更。

@node PyZipFile 物件,ZipInfo 物件,Path 物件,zipfile --- 處理 ZIP 封存檔案
@anchor{library/zipfile id3}@anchor{2d68}@anchor{library/zipfile pyzipfile-objects}@anchor{2d69}
@subsubsection PyZipFile 物件


@ref{11f4,,PyZipFile} 建構函式接受與 @ref{8cb,,ZipFile} 建構函式相同的參數，以及一個額外的參數 `optimize'。

@geindex PyZipFile (zipfile 中的類別)
@anchor{library/zipfile zipfile PyZipFile}@anchor{11f4}
@deffn {類別} zipfile.PyZipFile (file, mode='r', compression=ZIP_STORED, allowZip64=True, optimize=-1)


在 3.2 版的變更: 新增 `optimize' 參數。



在 3.4 版的變更: ZIP64 擴充預設為啟用。


實例除了 @ref{8cb,,ZipFile} 物件的方法之外，還有一個額外的方法：

@geindex writepy() (zipfile.PyZipFile 的方法)
@anchor{library/zipfile zipfile PyZipFile writepy}@anchor{11f3}
@deffn {方法} writepy (pathname, basename='@w{'}, filterfunc=None)

搜尋 @code{*.py} 檔案，並將對應的檔案加入封存檔案。

如果傳給 @ref{11f4,,PyZipFile} 的 `optimize' 參數未被給定或為 @code{-1}，則對應的檔案是一個 @code{*.pyc} 檔案，如有必要則進行編譯。

如果傳給 @ref{11f4,,PyZipFile} 的 `optimize' 參數為 @code{0}、@code{1} 或 @code{2}，則只有具有該最佳化層級（參閱 @ref{4ac,,compile()}）的檔案會被加入封存檔案，如有必要則進行編譯。

如果 `pathname' 是一個檔案，檔名必須以 @code{.py} 結尾，且只有（對應的 @code{*.pyc}）檔案會被加到頂層（沒有路徑資訊）。如果 `pathname' 是一個不以 @code{.py} 結尾的檔案，將會引發 @ref{244,,RuntimeError}。如果它是一個目錄，且該目錄不是一個套件目錄，則所有 @code{*.pyc} 檔案都會被加到頂層。如果該目錄是一個套件目錄，則所有 @code{*.pyc} 都會以檔案路徑的形式被加到套件名稱下，且如果任何子目錄是套件目錄，所有這些都會以排序後的順序遞迴地加入。

`basename' 僅供內部使用。

`filterfunc'，如果給定，必須是一個接受單一字串引數的函式。每個路徑（包括每個單獨的完整檔案路徑）在被加入封存檔案之前都會被傳遞給它。如果 `filterfunc' 回傳一個假值，該路徑將不會被加入，且如果它是一個目錄，其內容將被忽略。例如，如果我們的測試檔案要嘛在 @code{test} 目錄中，要嘛以字串 @code{test_} 開頭，我們可以使用一個 `filterfunc' 來排除它們：

@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

@ref{11f3,,writepy()} 方法會建立帶有如下檔名的封存檔案：

@example
string.pyc                   # 頂層名稱
test/__init__.pyc            # 套件目錄
test/testall.pyc             # 模組 test.testall
test/bogus/__init__.pyc      # 子套件目錄
test/bogus/myfile.pyc        # 子模組 test.bogus.myfile
@end example


在 3.4 版的變更: 新增 `filterfunc' 參數。



在 3.6.2 版的變更: `pathname' 參數接受一個 @ref{59b,,path-like object}。



在 3.7 版的變更: 遞迴會對目錄條目進行排序。

@end deffn
@end deffn

@node ZipInfo 物件,命令列介面<4>,PyZipFile 物件,zipfile --- 處理 ZIP 封存檔案
@anchor{library/zipfile id4}@anchor{2d6a}@anchor{library/zipfile zipinfo-objects}@anchor{2d4b}
@subsubsection ZipInfo 物件


@ref{2cb,,ZipInfo} 類別的實例由 @ref{8cb,,ZipFile} 物件的 @ref{2d49,,getinfo()} 和 @ref{2d4a,,infolist()} 方法回傳。每個物件儲存關於 ZIP 封存檔案單一成員的資訊。

有一個類別方法可以為檔案系統中的檔案建立一個 @ref{2cb,,ZipInfo} 實例：

@geindex from_file() (zipfile.ZipInfo 的類別方法)
@anchor{library/zipfile zipfile ZipInfo from_file}@anchor{f01}
@deffn {方法} classmethod ZipInfo.from_file (filename, arcname=None, *, strict_timestamps=True)

為檔案系統上的一個檔案建構一個 @ref{2cb,,ZipInfo} 實例，為將其加入 zip 檔案做準備。

`filename' 應為檔案系統上一個檔案或目錄的路徑。

如果指定了 `arcname'，它將被用作封存檔案內的名稱。如果未指定 `arcname'，名稱將與 `filename' 相同，但會移除任何磁碟機代號和開頭的路徑分隔符。

`strict_timestamps' 引數，當設為 @code{False} 時，允許壓縮早於 1980-01-01 的檔案，代價是將時間戳記設為 1980-01-01。對於晚於 2107-12-31 的檔案，也會有類似的行為，時間戳記同樣會被設為極限值。


在 3.6 版被加入.



在 3.6.2 版的變更: `filename' 參數接受一個 @ref{59b,,path-like object}。



在 3.8 版的變更: 新增了 `strict_timestamps' 僅限關鍵字參數。

@end deffn

實例具有以下方法和屬性：

@geindex is_dir() (zipfile.ZipInfo 的方法)
@anchor{library/zipfile zipfile ZipInfo is_dir}@anchor{f02}
@deffn {方法} ZipInfo.is_dir ()

如果此封存成員是一個目錄，則回傳 @code{True}。

這會使用條目的名稱：目錄應總是以 @code{/} 結尾。


在 3.6 版被加入.

@end deffn

@geindex filename (zipfile.ZipInfo 的屬性)
@anchor{library/zipfile zipfile ZipInfo filename}@anchor{2d6b}
@deffn {屬性} ZipInfo.filename

封存檔案中檔案的名稱。
@end deffn

@geindex date_time (zipfile.ZipInfo 的屬性)
@anchor{library/zipfile zipfile ZipInfo date_time}@anchor{2d6c}
@deffn {屬性} ZipInfo.date_time

封存成員的最後修改時間和日期。這是一個包含六個值的元組，代表 ZIP 檔案中中央目錄的「最後 [修改] 檔案時間」和「最後 [修改] 檔案日期」欄位。

該元組包含：


@multitable {xxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

索引

@tab

值

@item

@code{0}

@tab

年（>= 1980）

@item

@code{1}

@tab

月（從 1 開始）

@item

@code{2}

@tab

日（從 1 開始）

@item

@code{3}

@tab

時（從 0 開始）

@item

@code{4}

@tab

分（從 0 開始）

@item

@code{5}

@tab

秒（從 0 開始）

@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{2d6d}
@deffn {屬性} ZipInfo.compress_type

封存成員的壓縮型別。
@end deffn

@geindex comment (zipfile.ZipInfo 的屬性)
@anchor{library/zipfile zipfile ZipInfo comment}@anchor{2d6e}
@deffn {屬性} ZipInfo.comment

個別封存成員的註解，為一個 @ref{192,,bytes} 物件。
@end deffn

@geindex extra (zipfile.ZipInfo 的屬性)
@anchor{library/zipfile zipfile ZipInfo extra}@anchor{2d6f}
@deffn {屬性} ZipInfo.extra

擴充欄位資料。PKZIP Application Note@footnote{https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT} 包含一些關於此 @ref{192,,bytes} 物件中所含資料內部結構的註解。
@end deffn

@geindex create_system (zipfile.ZipInfo 的屬性)
@anchor{library/zipfile zipfile ZipInfo create_system}@anchor{2d70}
@deffn {屬性} ZipInfo.create_system

建立 ZIP 封存檔案的系統。
@end deffn

@geindex create_version (zipfile.ZipInfo 的屬性)
@anchor{library/zipfile zipfile ZipInfo create_version}@anchor{2d71}
@deffn {屬性} ZipInfo.create_version

建立 ZIP 封存檔案的 PKZIP 版本。
@end deffn

@geindex extract_version (zipfile.ZipInfo 的屬性)
@anchor{library/zipfile zipfile ZipInfo extract_version}@anchor{2d72}
@deffn {屬性} ZipInfo.extract_version

解壓縮封存檔案所需的 PKZIP 版本。
@end deffn

@geindex reserved (zipfile.ZipInfo 的屬性)
@anchor{library/zipfile zipfile ZipInfo reserved}@anchor{2d73}
@deffn {屬性} ZipInfo.reserved

必須為零。
@end deffn

@geindex flag_bits (zipfile.ZipInfo 的屬性)
@anchor{library/zipfile zipfile ZipInfo flag_bits}@anchor{2d74}
@deffn {屬性} ZipInfo.flag_bits

ZIP 旗標位元。
@end deffn

@geindex volume (zipfile.ZipInfo 的屬性)
@anchor{library/zipfile zipfile ZipInfo volume}@anchor{2d75}
@deffn {屬性} ZipInfo.volume

檔案標頭的磁碟空間編號。
@end deffn

@geindex internal_attr (zipfile.ZipInfo 的屬性)
@anchor{library/zipfile zipfile ZipInfo internal_attr}@anchor{2d76}
@deffn {屬性} ZipInfo.internal_attr

內部屬性。
@end deffn

@geindex external_attr (zipfile.ZipInfo 的屬性)
@anchor{library/zipfile zipfile ZipInfo external_attr}@anchor{2d77}
@deffn {屬性} ZipInfo.external_attr

外部檔案屬性。
@end deffn

@geindex header_offset (zipfile.ZipInfo 的屬性)
@anchor{library/zipfile zipfile ZipInfo header_offset}@anchor{2d78}
@deffn {屬性} ZipInfo.header_offset

到檔案標頭的位元組偏移量。
@end deffn

@geindex CRC (zipfile.ZipInfo 的屬性)
@anchor{library/zipfile zipfile ZipInfo CRC}@anchor{2d79}
@deffn {屬性} ZipInfo.CRC

未壓縮檔案的 CRC-32。
@end deffn

@geindex compress_size (zipfile.ZipInfo 的屬性)
@anchor{library/zipfile zipfile ZipInfo compress_size}@anchor{2d7a}
@deffn {屬性} ZipInfo.compress_size

壓縮資料的大小。
@end deffn

@geindex file_size (zipfile.ZipInfo 的屬性)
@anchor{library/zipfile zipfile ZipInfo file_size}@anchor{2d54}
@deffn {屬性} ZipInfo.file_size

未壓縮檔案的大小。
@end deffn

@node 命令列介面<4>,解壓縮的陷阱,ZipInfo 物件,zipfile --- 處理 ZIP 封存檔案
@anchor{library/zipfile command-line-interface}@anchor{2d7b}@anchor{library/zipfile zipfile-commandline}@anchor{2d7c}
@subsubsection 命令列介面


@ref{137,,zipfile} 模組提供了一個簡單的命令列介面，用以與 ZIP 封存檔案互動。

如果你想建立一個新的 ZIP 封存檔案，請在 @ref{2d7d,,-c} 選項後指定其名稱，然後列出應包含的檔名：

@example
$ python -m zipfile -c monty.zip spam.txt eggs.txt
@end example

傳遞一個目錄也是可以的：

@example
$ python -m zipfile -c monty.zip life-of-brian_1979/
@end example

如果你想將一個 ZIP 封存檔案解壓縮到指定的目錄，請使用 @ref{2d7e,,-e} 選項：

@example
$ python -m zipfile -e monty.zip target-dir/
@end example

要列出 ZIP 封存檔案中的檔案，請使用 @ref{2d7f,,-l} 選項：

@example
$ python -m zipfile -l monty.zip
@end example

@menu
* 命令列選項: 命令列選項<2>. 

@end menu

@node 命令列選項<2>,,,命令列介面<4>
@anchor{library/zipfile command-line-options}@anchor{2d80}
@subsubsection 命令列選項


@geindex zipfile 命令列選項; -l
@geindex zipfile 命令列選項; --list
@anchor{library/zipfile cmdoption-zipfile-l}@anchor{2d7f}
@deffn {Option} @w{-}l <zipfile>
@anchor{library/zipfile cmdoption-zipfile-list}@anchor{2d81}
@deffnx {Option} @w{-}@w{-}list <zipfile>

列出 zipfile 中的檔案。
@end deffn

@geindex zipfile 命令列選項; -c
@geindex zipfile 命令列選項; --create
@anchor{library/zipfile cmdoption-zipfile-c}@anchor{2d7d}
@deffn {Option} @w{-}c <zipfile> <source1> ... <sourceN>
@anchor{library/zipfile cmdoption-zipfile-create}@anchor{2d82}
@deffnx {Option} @w{-}@w{-}create <zipfile> <source1> ... <sourceN>

從來源檔案建立 zipfile。
@end deffn

@geindex zipfile 命令列選項; -e
@geindex zipfile 命令列選項; --extract
@anchor{library/zipfile cmdoption-zipfile-e}@anchor{2d7e}
@deffn {Option} @w{-}e <zipfile> <output_dir>
@anchor{library/zipfile cmdoption-zipfile-extract}@anchor{2d83}
@deffnx {Option} @w{-}@w{-}extract <zipfile> <output_dir>

將 zipfile 解壓縮到目標目錄。
@end deffn

@geindex zipfile 命令列選項; -t
@geindex zipfile 命令列選項; --test
@anchor{library/zipfile cmdoption-zipfile-t}@anchor{2d84}
@deffn {Option} @w{-}t <zipfile>
@anchor{library/zipfile cmdoption-zipfile-test}@anchor{2d85}
@deffnx {Option} @w{-}@w{-}test <zipfile>

測試 zipfile 是否有效。
@end deffn

@geindex zipfile 命令列選項; --metadata-encoding
@anchor{library/zipfile cmdoption-zipfile-metadata-encoding}@anchor{2d86}
@deffn {Option} @w{-}@w{-}metadata@w{-}encoding <encoding>

為 @ref{2d7f,,-l}、@ref{2d7e,,-e} 和 @ref{2d84,,-t} 指定成員名稱的編碼。


在 3.11 版被加入.

@end deffn

@node 解壓縮的陷阱,,命令列介面<4>,zipfile --- 處理 ZIP 封存檔案
@anchor{library/zipfile decompression-pitfalls}@anchor{2d87}
@subsubsection 解壓縮的陷阱


zipfile 模組中的解壓縮可能會由於下面列出的一些陷阱而失敗。

@menu
* 來自檔案本身:: 
* 檔案系統限制:: 
* 資源限制:: 
* 中斷:: 
* 解壓縮的預設行為:: 

@end menu

@node 來自檔案本身,檔案系統限制,,解壓縮的陷阱
@anchor{library/zipfile from-file-itself}@anchor{2d88}
@subsubsection 來自檔案本身


解壓縮可能由於不正確的密碼 / CRC 校驗和 / ZIP 格式或不支援的壓縮方法 / 解密而失敗。

@node 檔案系統限制,資源限制,來自檔案本身,解壓縮的陷阱
@anchor{library/zipfile file-system-limitations}@anchor{2d89}
@subsubsection 檔案系統限制


超出不同檔案系統的限制可能導致解壓縮失敗。例如目錄條目中允許的字元、檔名長度、路徑名長度、單一檔案的大小以及檔案數量等。

@node 資源限制,中斷,檔案系統限制,解壓縮的陷阱
@anchor{library/zipfile resources-limitations}@anchor{2d8a}@anchor{library/zipfile zipfile-resources-limitations}@anchor{2d8b}
@subsubsection 資源限制


記憶體或磁碟空間不足會導致解壓縮失敗。例如，解壓縮炸彈（又稱 ZIP bomb@footnote{https://en.wikipedia.org/wiki/Zip_bomb}）適用於 zipfile 函式庫，可能導致磁碟空間耗盡。

@node 中斷,解壓縮的預設行為,資源限制,解壓縮的陷阱
@anchor{library/zipfile interruption}@anchor{2d8c}
@subsubsection 中斷


在解壓縮過程中斷，例如按下 control-C 或終止解壓縮過程，可能導致封存檔案解壓縮不完整。

@node 解壓縮的預設行為,,中斷,解壓縮的陷阱
@anchor{library/zipfile default-behaviors-of-extraction}@anchor{2d8d}
@subsubsection 解壓縮的預設行為


不了解預設的解壓縮行為可能導致非預期的解壓縮結果。例如，當兩次解壓縮同一個封存檔案時，它會不經詢問就覆寫檔案。

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node tarfile --- 讀取與寫入 tar 封存檔案,,zipfile --- 處理 ZIP 封存檔案,資料壓縮與保存
@anchor{library/tarfile doc}@anchor{2d8e}@anchor{library/tarfile module-tarfile}@anchor{e4}@anchor{library/tarfile tarfile-read-and-write-tar-archive-files}@anchor{2d8f}@anchor{library/tarfile translation-repo}@anchor{2d90}
@subsection @code{tarfile} --- 讀取與寫入 tar 封存檔案


@geindex module; tarfile

`原始碼：'Lib/tarfile.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/tarfile.py}


__________________________________________________________________


The @ref{e4,,tarfile} module makes it possible to read and write tar
archives, including those using gzip, bz2 and lzma compression.
Use the @ref{137,,zipfile} module to read or write @code{.zip} files, or the
higher-level functions in @ref{1419,,shutil}.

Some facts and figures:


@itemize *

@item 
reads and writes @ref{6b,,gzip}, @ref{14,,bz2}, @ref{23,,compression.zstd}, and
@ref{8e,,lzma} compressed archives if the respective modules are available.

@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 版的變更: 新增對 @ref{8e,,lzma} 壓縮的支援。



在 3.12 版的變更: Archives are extracted using a @ref{690,,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{29a,,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{2d91,,fully_trusted}.



在 3.14 版的變更: 新增對 Zstandard 壓縮的支援（使用 @ref{23,,compression.zstd}）。


@geindex open() (於 tarfile 模組中)
@anchor{library/tarfile tarfile open}@anchor{1072}
@deffn {函式} tarfile.open (name=None, mode='r', fileobj=None, bufsize=10240, **kwargs)

Return a @ref{1411,,TarFile} object for the pathname `name'. For detailed
information on @ref{1411,,TarFile} objects and the keyword arguments that are
allowed, see @ref{2d92,,TarFile 物件}.

`mode' 必須是 @code{'filemode[:compression]'} 形式的字串，預設為 @code{'r'}。以下是所有可能的模式組合：


@multitable {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

模式

@tab

操作

@item

@code{'r'} 或 @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

開啟以讀取 gzip 壓縮。

@item

@code{'r:bz2'}

@tab

開啟以讀取 bzip2 壓縮。

@item

@code{'r:xz'}

@tab

開啟以讀取 lzma 壓縮。

@item

@code{'r:zst'}

@tab

開啟以讀取 Zstandard 壓縮。

@item

@code{'x'} 或 @code{'x:'}

@tab

Create a tarfile exclusively without
compression.
Raise a @ref{121b,,FileExistsError} exception
if it already exists.

@item

@code{'x:gz'}

@tab

Create a tarfile with gzip compression.
Raise a @ref{121b,,FileExistsError} exception
if it already exists.

@item

@code{'x:bz2'}

@tab

Create a tarfile with bzip2 compression.
Raise a @ref{121b,,FileExistsError} exception
if it already exists.

@item

@code{'x:xz'}

@tab

Create a tarfile with lzma compression.
Raise a @ref{121b,,FileExistsError} exception
if it already exists.

@item

@code{'x:zst'}

@tab

Create a tarfile with Zstandard compression.
Raise a @ref{121b,,FileExistsError} exception
if it already exists.

@item

@code{'a'} 或 @code{'a:'}

@tab

Open for appending with no compression. The
file is created if it does not exist.

@item

@code{'w'} 或 @code{'w:'}

@tab

Open for uncompressed writing.

@item

@code{'w:gz'}

@tab

開啟以用於 gzip 壓縮寫入。

@item

@code{'w:bz2'}

@tab

開啟以用於 bzip2 壓縮寫入。

@item

@code{'w:xz'}

@tab

開啟以用於 lzma 壓縮寫入。

@item

@code{'w:zst'}

@tab

開啟以用於 Zstandard 壓縮寫入。

@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{1b51,,ReadError} is raised. Use `mode' @code{'r'} to avoid this.  If a
compression method is not supported, @ref{2d93,,CompressionError} is raised.

If `fileobj' is specified, it is used as an alternative to a @ref{13c4,,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{1072,,tarfile.open()} accepts the keyword argument
`compresslevel' (default @code{9}) to specify the compression level of the file.

For modes @code{'w:xz'}, @code{'x:xz'} and @code{'w|xz'}, @ref{1072,,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{1072,,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{2c98,,CompressionParameter}. The keyword argument
`zstd_dict' can be passed to provide a @ref{2c97,,ZstdDict},
a Zstandard dictionary used to improve compression of smaller amounts of
data.

For special purposes, there is a second format for `mode':
@code{'filemode|[compression]'}.  @ref{1072,,tarfile.open()} will return a @ref{1411,,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{1018,,read()} or @ref{15a3,,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{13c4,,file object} or a tape device.
However, such a @ref{1411,,TarFile} object is limited in that it does
not allow random access, see @ref{2d94,,範例}.  The currently
possible modes:


@multitable {xxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

模式

@tab

操作

@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

開啟以用於 Zstandard 壓縮寫入。

@end multitable



在 3.5 版的變更: The @code{'x'} (exclusive creation) mode was added.



在 3.6 版的變更: The `name' parameter accepts a @ref{59b,,path-like object}.



在 3.12 版的變更: The `compresslevel' keyword argument also works for streams.



在 3.14 版的變更: The `preset' keyword argument also works for streams.

@end deffn


@deffn {類別} tarfile.TarFile

Class for reading and writing tar archives. Do not use this class directly:
use @ref{1072,,tarfile.open()} instead. See @ref{2d92,,TarFile 物件}.
@end deffn

@geindex is_tarfile() (於 tarfile 模組中)
@anchor{library/tarfile tarfile is_tarfile}@anchor{1afb}
@deffn {函式} tarfile.is_tarfile (name)

Return @ref{e02,,True} if `name' is a tar archive file, that the @ref{e4,,tarfile}
module can read. `name' may be a @ref{169,,str}, file, or file-like object.


在 3.9 版的變更: 對檔案和類檔案物件的支援。

@end deffn

@ref{e4,,tarfile} 模組定義了以下例外：

@geindex TarError
@anchor{library/tarfile tarfile TarError}@anchor{2d95}
@deffn {例外} tarfile.TarError

所有 @ref{e4,,tarfile} 例外的基底類別。
@end deffn

@geindex ReadError
@anchor{library/tarfile tarfile ReadError}@anchor{1b51}
@deffn {例外} tarfile.ReadError

Is raised when a tar archive is opened, that either cannot be handled by the
@ref{e4,,tarfile} module or is somehow invalid.
@end deffn

@geindex CompressionError
@anchor{library/tarfile tarfile CompressionError}@anchor{2d93}
@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{2d96}
@deffn {例外} tarfile.StreamError

Is raised for the limitations that are typical for stream-like @ref{1411,,TarFile}
objects.
@end deffn

@geindex ExtractError
@anchor{library/tarfile tarfile ExtractError}@anchor{2d97}
@deffn {例外} tarfile.ExtractError

Is raised for `non-fatal' errors when using @ref{29c,,TarFile.extract()}, but only if
@ref{29e,,TarFile.errorlevel}@code{== 2}.
@end deffn

@geindex HeaderError
@anchor{library/tarfile tarfile HeaderError}@anchor{2d98}
@deffn {例外} tarfile.HeaderError

Is raised by @ref{2d99,,TarInfo.frombuf()} if the buffer it gets is invalid.
@end deffn

@geindex FilterError
@anchor{library/tarfile tarfile FilterError}@anchor{2d9a}
@deffn {例外} tarfile.FilterError

Base class for members @ref{2d9b,,refused} by
filters.

@geindex tarinfo (tarfile.FilterError 的屬性)
@anchor{library/tarfile tarfile FilterError tarinfo}@anchor{2d9c}
@deffn {屬性} tarinfo

Information about the member that the filter refused to extract,
as @ref{2d9d,,TarInfo}.
@end deffn
@end deffn

@geindex AbsolutePathError
@anchor{library/tarfile tarfile AbsolutePathError}@anchor{2d9e}
@deffn {例外} tarfile.AbsolutePathError

Raised to refuse extracting a member with an absolute path.
@end deffn

@geindex OutsideDestinationError
@anchor{library/tarfile tarfile OutsideDestinationError}@anchor{2d9f}
@deffn {例外} tarfile.OutsideDestinationError

Raised to refuse extracting a member outside the destination directory.
@end deffn

@geindex SpecialFileError
@anchor{library/tarfile tarfile SpecialFileError}@anchor{2da0}
@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{2da1}
@deffn {例外} tarfile.AbsoluteLinkError

Raised to refuse extracting a symbolic link with an absolute path.
@end deffn

@geindex LinkOutsideDestinationError
@anchor{library/tarfile tarfile LinkOutsideDestinationError}@anchor{2da2}
@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{29d}
@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__}.


在 3.14 版被加入.

@end deffn

The following constants are available at the module level:

@geindex ENCODING (於 tarfile 模組中)
@anchor{library/tarfile tarfile ENCODING}@anchor{2da3}
@deffn {資料} tarfile.ENCODING

The default character encoding: @code{'utf-8'} on Windows, the value returned by
@ref{e4e,,sys.getfilesystemencoding()} otherwise.
@end deffn

@geindex REGTYPE (於 tarfile 模組中)
@geindex AREGTYPE (於 tarfile 模組中)
@anchor{library/tarfile tarfile REGTYPE}@anchor{2da4}
@deffn {資料} tarfile.REGTYPE
@anchor{library/tarfile tarfile AREGTYPE}@anchor{2da5}
@deffnx {資料} tarfile.AREGTYPE

一個普通檔案 @ref{2da6,,type}。
@end deffn

@geindex LNKTYPE (於 tarfile 模組中)
@anchor{library/tarfile tarfile LNKTYPE}@anchor{2da7}
@deffn {資料} tarfile.LNKTYPE

A link (inside tarfile) @ref{2da6,,type}.
@end deffn

@geindex SYMTYPE (於 tarfile 模組中)
@anchor{library/tarfile tarfile SYMTYPE}@anchor{2da8}
@deffn {資料} tarfile.SYMTYPE

A symbolic link @ref{2da6,,type}.
@end deffn

@geindex CHRTYPE (於 tarfile 模組中)
@anchor{library/tarfile tarfile CHRTYPE}@anchor{2da9}
@deffn {資料} tarfile.CHRTYPE

A character special device @ref{2da6,,type}.
@end deffn

@geindex BLKTYPE (於 tarfile 模組中)
@anchor{library/tarfile tarfile BLKTYPE}@anchor{2daa}
@deffn {資料} tarfile.BLKTYPE

A block special device @ref{2da6,,type}.
@end deffn

@geindex DIRTYPE (於 tarfile 模組中)
@anchor{library/tarfile tarfile DIRTYPE}@anchor{2dab}
@deffn {資料} tarfile.DIRTYPE

A directory @ref{2da6,,type}.
@end deffn

@geindex FIFOTYPE (於 tarfile 模組中)
@anchor{library/tarfile tarfile FIFOTYPE}@anchor{2dac}
@deffn {資料} tarfile.FIFOTYPE

A FIFO special device @ref{2da6,,type}.
@end deffn

@geindex CONTTYPE (於 tarfile 模組中)
@anchor{library/tarfile tarfile CONTTYPE}@anchor{2dad}
@deffn {資料} tarfile.CONTTYPE

A contiguous file @ref{2da6,,type}.
@end deffn

@geindex GNUTYPE_LONGNAME (於 tarfile 模組中)
@anchor{library/tarfile tarfile GNUTYPE_LONGNAME}@anchor{2dae}
@deffn {資料} tarfile.GNUTYPE_LONGNAME

A GNU tar longname @ref{2da6,,type}.
@end deffn

@geindex GNUTYPE_LONGLINK (於 tarfile 模組中)
@anchor{library/tarfile tarfile GNUTYPE_LONGLINK}@anchor{2daf}
@deffn {資料} tarfile.GNUTYPE_LONGLINK

A GNU tar longlink @ref{2da6,,type}.
@end deffn

@geindex GNUTYPE_SPARSE (於 tarfile 模組中)
@anchor{library/tarfile tarfile GNUTYPE_SPARSE}@anchor{2db0}
@deffn {資料} tarfile.GNUTYPE_SPARSE

A GNU tar sparse file @ref{2da6,,type}.
@end deffn

Each of the following constants defines a tar archive format that the
@ref{e4,,tarfile} module is able to create. See section @ref{2db1,,支援的 tar 格式} for
details.

@geindex USTAR_FORMAT (於 tarfile 模組中)
@anchor{library/tarfile tarfile USTAR_FORMAT}@anchor{2db2}
@deffn {資料} tarfile.USTAR_FORMAT

POSIX.1-1988 (ustar) 格式。
@end deffn

@geindex GNU_FORMAT (於 tarfile 模組中)
@anchor{library/tarfile tarfile GNU_FORMAT}@anchor{2db3}
@deffn {資料} tarfile.GNU_FORMAT

GNU tar 格式。
@end deffn

@geindex PAX_FORMAT (於 tarfile 模組中)
@anchor{library/tarfile tarfile PAX_FORMAT}@anchor{2db4}
@deffn {資料} tarfile.PAX_FORMAT

POSIX.1-2001 (pax) 格式。
@end deffn

@geindex DEFAULT_FORMAT (於 tarfile 模組中)
@anchor{library/tarfile tarfile DEFAULT_FORMAT}@anchor{2db5}
@deffn {資料} tarfile.DEFAULT_FORMAT

The default format for creating archives. This is currently @ref{2db4,,PAX_FORMAT}.


在 3.8 版的變更: The default format for new archives was changed to
@ref{2db4,,PAX_FORMAT} from @ref{2db3,,GNU_FORMAT}.

@end deffn


@subsubheading 也參考



@table @asis

@item @ref{137,,zipfile} 模組

@ref{137,,zipfile} 標準模組的文件。

@item @ref{1419,,Archiving operations}

Documentation of the higher-level archiving facilities provided by the
standard @ref{ca,,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 物件:: 
* TarInfo 物件:: 
* Extraction filters:: 
* 命令列介面: 命令列介面<5>. 
* 範例: 範例<15>. 
* 支援的 tar 格式:: 
* Unicode issues:: 

@end menu

@node TarFile 物件,TarInfo 物件,,tarfile --- 讀取與寫入 tar 封存檔案
@anchor{library/tarfile id1}@anchor{2db6}@anchor{library/tarfile tarfile-objects}@anchor{2d92}
@subsubsection TarFile 物件


The @ref{1411,,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{1412,,TarInfo}
object, see @ref{2d9d,,TarInfo 物件} for details.

A @ref{1411,,TarFile} object can be used as a context manager in a @ref{186,,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{2d94,,範例} section for a use case.


在 3.2 版被加入: 新增對情境管理協定的支援。


@geindex TarFile (tarfile 中的類別)
@anchor{library/tarfile tarfile TarFile}@anchor{1411}
@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{59b,,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 @ref{1411,,TarFile} is closed.
@end quotation
@end cartouche

`format' controls the archive format for writing. It must be one of the constants
@ref{2db2,,USTAR_FORMAT}, @ref{2db3,,GNU_FORMAT} or @ref{2db4,,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{1412,,TarInfo} class
with a different one.

If `dereference' is @ref{d23,,False}, add symbolic and hard links to the archive. If it
is @ref{e02,,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{d23,,False}, treat an empty block as the end of the archive.
If it is @ref{e02,,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{29e,,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{2db7,,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{2db4,,PAX_FORMAT}.

If `stream' is set to @ref{e02,,True} then while reading the archive info about files
in the archive are not cached, saving memory.


在 3.2 版的變更: 使用 @code{'surrogateescape'} 作為 `errors' 引數的預設值。



在 3.5 版的變更: The @code{'x'} (exclusive creation) mode was added.



在 3.6 版的變更: The `name' parameter accepts a @ref{59b,,path-like object}.



在 3.13 版的變更: 新增 `stream' 參數。

@end deffn

@geindex open() (tarfile.TarFile 的類別方法)
@anchor{library/tarfile tarfile TarFile open}@anchor{1afc}
@deffn {方法} classmethod TarFile.open (...)

Alternative constructor. The @ref{1072,,tarfile.open()} function is actually a
shortcut to this classmethod.
@end deffn

@geindex getmember() (tarfile.TarFile 的方法)
@anchor{library/tarfile tarfile TarFile getmember}@anchor{1b0b}
@deffn {方法} TarFile.getmember (name)

Return a @ref{1412,,TarInfo} object for member `name'. If `name' can not be found
in the archive, @ref{5df,,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{1074}
@deffn {方法} TarFile.getmembers ()

Return the members of the archive as a list of @ref{1412,,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{2db8}
@deffn {方法} TarFile.getnames ()

Return the members as a list of their names. It has the same order as the list
returned by @ref{1074,,getmembers()}.
@end deffn

@geindex list() (tarfile.TarFile 的方法)
@anchor{library/tarfile tarfile TarFile list}@anchor{1073}
@deffn {方法} TarFile.list (verbose=True, *, members=None)

Print a table of contents to @code{sys.stdout}. If `verbose' is @ref{d23,,False},
only the names of the members are printed. If it is @ref{e02,,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{1074,,getmembers()}.


在 3.5 版的變更: 新增 `members' 參數。

@end deffn

@geindex next() (tarfile.TarFile 的方法)
@anchor{library/tarfile tarfile TarFile next}@anchor{2db9}
@deffn {方法} TarFile.next ()

Return the next member of the archive as a @ref{1412,,TarInfo} object, when
@ref{1411,,TarFile} is opened for reading. Return @ref{87e,,None} if there is no more
available.
@end deffn

@geindex extractall() (tarfile.TarFile 的方法)
@anchor{library/tarfile tarfile TarFile extractall}@anchor{29b}
@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{1074,,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{e02,,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{690,,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{29a,,data}) will prevent
the most dangerous security issues.
However, it will not prevent `all' unintended or insecure behavior.
Read the @ref{690,,Extraction filters} section for details.
@end quotation
@end cartouche


在 3.5 版的變更: 新增 `numeric_owner' 參數。



在 3.6 版的變更: The `path' parameter accepts a @ref{59b,,path-like object}.



在 3.12 版的變更: 新增 `filter' 參數。



在 3.14 版的變更: The `filter' parameter now defaults to @code{'data'}.

@end deffn

@geindex extract() (tarfile.TarFile 的方法)
@anchor{library/tarfile tarfile TarFile extract}@anchor{29c}
@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{1412,,TarInfo} object. You can specify a different
directory using `path'. `path' may be a @ref{59b,,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{29b,,extractall()}.

@cartouche
@quotation 備註 
The @ref{29c,,extract()} method does not take care of several extraction issues.
In most cases you should consider using the @ref{29b,,extractall()} method.
@end quotation
@end cartouche

@cartouche
@quotation 警告 
Never extract archives from untrusted sources without prior inspection.
See the warning for @ref{29b,,extractall()} for details.
@end quotation
@end cartouche


在 3.2 版的變更: 增加 `set_attrs' 參數。



在 3.5 版的變更: 新增 `numeric_owner' 參數。



在 3.6 版的變更: The `path' parameter accepts a @ref{59b,,path-like object}.



在 3.12 版的變更: 新增 `filter' 參數。

@end deffn

@geindex extractfile() (tarfile.TarFile 的方法)
@anchor{library/tarfile tarfile TarFile extractfile}@anchor{2dba}
@deffn {方法} TarFile.extractfile (member)

Extract a member from the archive as a file object. `member' may be
a filename or a @ref{1412,,TarInfo} object. If `member' is a regular file or
a link, an @ref{140f,,io.BufferedReader} object is returned. For all other
existing members, @ref{87e,,None} is returned. If `member' does not appear
in the archive, @ref{5df,,KeyError} is raised.


在 3.3 版的變更: Return an @ref{140f,,io.BufferedReader} object.



在 3.13 版的變更: The returned @ref{140f,,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{29e}
@deffn {屬性} TarFile.errorlevel: @ref{19b,,int}

If `errorlevel' is @code{0}, errors are ignored when using @ref{29c,,TarFile.extract()}
and @ref{29b,,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{2c0,,OSError} or
@ref{2d9a,,FilterError} exceptions. If @code{2}, all `non-fatal' errors are raised
as @ref{2d95,,TarError} exceptions as well.

Some exceptions, e.g. ones caused by wrong argument types or data
corruption, are always raised.

Custom @ref{690,,extraction filters}
should raise @ref{2d9a,,FilterError} for `fatal' errors
and @ref{2d97,,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{2dbb}
@deffn {屬性} TarFile.extraction_filter


在 3.12 版被加入.


The @ref{690,,extraction filter} used
as a default for the `filter' argument of @ref{29c,,extract()}
and @ref{29b,,extractall()}.

The attribute may be @code{None} or a callable.
String names are not allowed for this attribute, unlike the `filter'
argument to @ref{29c,,extract()}.

If @code{extraction_filter} is @code{None} (the default), extraction methods
will use the @ref{29a,,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{cc,,site configuration}.
To set a global default this way, a filter function needs to be wrapped in
@ref{451,,staticmethod()} to prevent injection of a @code{self} argument.


在 3.14 版的變更: The default filter is set to @ref{29a,,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{2d91,,fully_trusted}.

@end deffn

@geindex add() (tarfile.TarFile 的方法)
@anchor{library/tarfile tarfile TarFile add}@anchor{de9}
@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{d23,,False}. Recursion adds entries in sorted order.
If `filter' is given, it
should be a function that takes a @ref{1412,,TarInfo} object argument and
returns the changed @ref{1412,,TarInfo} object. If it instead returns
@ref{87e,,None} the @ref{1412,,TarInfo} object will be excluded from the
archive. See @ref{2d94,,範例} for an example.


在 3.2 版的變更: 新增 `filter' 參數。



在 3.7 版的變更: Recursion adds entries in sorted order.

@end deffn

@geindex addfile() (tarfile.TarFile 的方法)
@anchor{library/tarfile tarfile TarFile addfile}@anchor{18fe}
@deffn {方法} TarFile.addfile (tarinfo, fileobj=None)

Add the @ref{1412,,TarInfo} object `tarinfo' to the archive. If `tarinfo' represents
a non zero-size regular file, the `fileobj' argument should be a @ref{1f35,,binary file},
and @code{tarinfo.size} bytes are read from it and added to the archive.  You can
create @ref{1412,,TarInfo} objects directly, or by using @ref{2dbc,,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{2dbc}
@deffn {方法} TarFile.gettarinfo (name=None, arcname=None, fileobj=None)

Create a @ref{1412,,TarInfo} object from the result of @ref{26d,,os.stat()} or
equivalent on an existing file.  The file is either named by `name', or
specified as a @ref{13c4,,file object} `fileobj' with a file descriptor.
`name' may be a @ref{59b,,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{2ca2,,name} attribute, or the `name' argument.  The name
should be a text string.

You can modify
some of the @ref{1412,,TarInfo}’s attributes before you add it using @ref{18fe,,addfile()}.
If the file object is not an ordinary file object positioned at the
beginning of the file, attributes such as @ref{2dbd,,size} may need
modifying.  This is the case for objects such as @ref{654,,GzipFile}.
The @ref{2dbe,,name} may also be modified, in which case `arcname'
could be a dummy string.


在 3.6 版的變更: The `name' parameter accepts a @ref{59b,,path-like object}.

@end deffn

@geindex close() (tarfile.TarFile 的方法)
@anchor{library/tarfile tarfile TarFile close}@anchor{2dbf}
@deffn {方法} TarFile.close ()

Close the @ref{1411,,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{2dc0}
@deffn {屬性} TarFile.pax_headers: @ref{183,,dict}

A dictionary containing key-value pairs of pax global headers.
@end deffn

@node TarInfo 物件,Extraction filters,TarFile 物件,tarfile --- 讀取與寫入 tar 封存檔案
@anchor{library/tarfile id2}@anchor{2dc1}@anchor{library/tarfile tarinfo-objects}@anchor{2d9d}
@subsubsection TarInfo 物件


A @ref{1412,,TarInfo} object represents one member in a @ref{1411,,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{1412,,TarInfo} objects are returned by @ref{1411,,TarFile}'s methods
@ref{1b0b,,getmember()}, @ref{1074,,getmembers()} and
@ref{2dbc,,gettarinfo()}.

Modifying the objects returned by @ref{1b0b,,getmember()} or
@ref{1074,,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{2dc2,,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{1412,,TarInfo} methods handle @code{None} differently:


@itemize -

@item 
The @ref{29c,,extract()} or @ref{29b,,extractall()} methods will
ignore the corresponding metadata, leaving it set to a default.

@item 
@ref{18fe,,addfile()} will fail.

@item 
@ref{1073,,list()} will print a placeholder string.
@end itemize

@geindex TarInfo (tarfile 中的類別)
@anchor{library/tarfile tarfile TarInfo}@anchor{1412}
@deffn {類別} tarfile.TarInfo (name='@w{'})

Create a @ref{1412,,TarInfo} object.
@end deffn

@geindex frombuf() (tarfile.TarInfo 的類別方法)
@anchor{library/tarfile tarfile TarInfo frombuf}@anchor{2d99}
@deffn {方法} classmethod TarInfo.frombuf (buf, encoding, errors)

Create and return a @ref{1412,,TarInfo} object from string buffer `buf'.

Raises @ref{2d98,,HeaderError} if the buffer is invalid.
@end deffn

@geindex fromtarfile() (tarfile.TarInfo 的類別方法)
@anchor{library/tarfile tarfile TarInfo fromtarfile}@anchor{2dc3}
@deffn {方法} classmethod TarInfo.fromtarfile (tarfile)

Read the next member from the @ref{1411,,TarFile} object `tarfile' and return it as
a @ref{1412,,TarInfo} object.
@end deffn

@geindex tobuf() (tarfile.TarInfo 的方法)
@anchor{library/tarfile tarfile TarInfo tobuf}@anchor{2dc4}
@deffn {方法} TarInfo.tobuf (format=DEFAULT_FORMAT, encoding=ENCODING, errors='surrogateescape')

Create a string buffer from a @ref{1412,,TarInfo} object. For information on the
arguments see the constructor of the @ref{1411,,TarFile} class.


在 3.2 版的變更: 使用 @code{'surrogateescape'} 作為 `errors' 引數的預設值。

@end deffn

一個 @code{TarInfo} 物件具有以下公開資料屬性：

@geindex name (tarfile.TarInfo 的屬性)
@anchor{library/tarfile tarfile TarInfo name}@anchor{2dbe}
@deffn {屬性} TarInfo.name: @ref{169,,str}

Name of the archive member.
@end deffn

@geindex size (tarfile.TarInfo 的屬性)
@anchor{library/tarfile tarfile TarInfo size}@anchor{2dbd}
@deffn {屬性} TarInfo.size: @ref{19b,,int}

Size in bytes.
@end deffn

@geindex mtime (tarfile.TarInfo 的屬性)
@anchor{library/tarfile tarfile TarInfo mtime}@anchor{2dc5}
@deffn {屬性} TarInfo.mtime: @ref{19b,,int} | @ref{196,,float}

Time of last modification in seconds since the @ref{2dc6,,epoch},
as in @ref{2dc7,,os.stat_result.st_mtime}.


在 3.12 版的變更: Can be set to @code{None} for @ref{29c,,extract()} and
@ref{29b,,extractall()}, causing extraction to skip applying this
attribute.

@end deffn

@geindex mode (tarfile.TarInfo 的屬性)
@anchor{library/tarfile tarfile TarInfo mode}@anchor{2dc8}
@deffn {屬性} TarInfo.mode: @ref{19b,,int}

Permission bits, as for @ref{524,,os.chmod()}.


在 3.12 版的變更: Can be set to @code{None} for @ref{29c,,extract()} and
@ref{29b,,extractall()}, causing extraction to skip applying this
attribute.

@end deffn

@geindex type (tarfile.TarInfo 的屬性)
@anchor{library/tarfile tarfile TarInfo type}@anchor{2da6}
@deffn {屬性} TarInfo.type

File type.  `type' is usually one of these constants: @ref{2da4,,REGTYPE},
@ref{2da5,,AREGTYPE}, @ref{2da7,,LNKTYPE}, @ref{2da8,,SYMTYPE}, @ref{2dab,,DIRTYPE},
@ref{2dac,,FIFOTYPE}, @ref{2dad,,CONTTYPE}, @ref{2da9,,CHRTYPE}, @ref{2daa,,BLKTYPE},
@ref{2db0,,GNUTYPE_SPARSE}.  To determine the type of a @ref{1412,,TarInfo} object
more conveniently, use the @code{is*()} methods below.
@end deffn

@geindex linkname (tarfile.TarInfo 的屬性)
@anchor{library/tarfile tarfile TarInfo linkname}@anchor{2dc9}
@deffn {屬性} TarInfo.linkname: @ref{169,,str}

Name of the target file name, which is only present in @ref{1412,,TarInfo} objects
of type @ref{2da7,,LNKTYPE} and @ref{2da8,,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{2dca}
@deffn {屬性} TarInfo.uid: @ref{19b,,int}

User ID of the user who originally stored this member.


在 3.12 版的變更: Can be set to @code{None} for @ref{29c,,extract()} and
@ref{29b,,extractall()}, causing extraction to skip applying this
attribute.

@end deffn

@geindex gid (tarfile.TarInfo 的屬性)
@anchor{library/tarfile tarfile TarInfo gid}@anchor{2dcb}
@deffn {屬性} TarInfo.gid: @ref{19b,,int}

Group ID of the user who originally stored this member.


在 3.12 版的變更: Can be set to @code{None} for @ref{29c,,extract()} and
@ref{29b,,extractall()}, causing extraction to skip applying this
attribute.

@end deffn

@geindex uname (tarfile.TarInfo 的屬性)
@anchor{library/tarfile tarfile TarInfo uname}@anchor{2dcc}
@deffn {屬性} TarInfo.uname: @ref{169,,str}

User name.


在 3.12 版的變更: Can be set to @code{None} for @ref{29c,,extract()} and
@ref{29b,,extractall()}, causing extraction to skip applying this
attribute.

@end deffn

@geindex gname (tarfile.TarInfo 的屬性)
@anchor{library/tarfile tarfile TarInfo gname}@anchor{2dcd}
@deffn {屬性} TarInfo.gname: @ref{169,,str}

Group name.


在 3.12 版的變更: Can be set to @code{None} for @ref{29c,,extract()} and
@ref{29b,,extractall()}, causing extraction to skip applying this
attribute.

@end deffn

@geindex chksum (tarfile.TarInfo 的屬性)
@anchor{library/tarfile tarfile TarInfo chksum}@anchor{2dce}
@deffn {屬性} TarInfo.chksum: @ref{19b,,int}

Header checksum.
@end deffn

@geindex devmajor (tarfile.TarInfo 的屬性)
@anchor{library/tarfile tarfile TarInfo devmajor}@anchor{2dcf}
@deffn {屬性} TarInfo.devmajor: @ref{19b,,int}

Device major number.
@end deffn

@geindex devminor (tarfile.TarInfo 的屬性)
@anchor{library/tarfile tarfile TarInfo devminor}@anchor{2dd0}
@deffn {屬性} TarInfo.devminor: @ref{19b,,int}

Device minor number.
@end deffn

@geindex offset (tarfile.TarInfo 的屬性)
@anchor{library/tarfile tarfile TarInfo offset}@anchor{2dd1}
@deffn {屬性} TarInfo.offset: @ref{19b,,int}

The tar header starts here.
@end deffn

@geindex offset_data (tarfile.TarInfo 的屬性)
@anchor{library/tarfile tarfile TarInfo offset_data}@anchor{2dd2}
@deffn {屬性} TarInfo.offset_data: @ref{19b,,int}

The file's data starts here.
@end deffn

@geindex sparse (tarfile.TarInfo 的屬性)
@anchor{library/tarfile tarfile TarInfo sparse}@anchor{2dd3}
@deffn {屬性} TarInfo.sparse

Sparse member information.
@end deffn

@geindex pax_headers (tarfile.TarInfo 的屬性)
@anchor{library/tarfile tarfile TarInfo pax_headers}@anchor{2dd4}
@deffn {屬性} TarInfo.pax_headers: @ref{183,,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{2dc2}
@deffn {方法} TarInfo.replace (name=..., mtime=..., mode=..., linkname=..., uid=..., gid=..., uname=..., gname=..., deep=True)


在 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{1412,,TarInfo} object also provides some convenient query methods:

@geindex isfile() (tarfile.TarInfo 的方法)
@anchor{library/tarfile tarfile TarInfo isfile}@anchor{2dd5}
@deffn {方法} TarInfo.isfile ()

Return @ref{e02,,True} if the @ref{1412,,TarInfo} object is a regular file.
@end deffn

@geindex isreg() (tarfile.TarInfo 的方法)
@anchor{library/tarfile tarfile TarInfo isreg}@anchor{2dd6}
@deffn {方法} TarInfo.isreg ()

Same as @ref{2dd5,,isfile()}.
@end deffn

@geindex isdir() (tarfile.TarInfo 的方法)
@anchor{library/tarfile tarfile TarInfo isdir}@anchor{2dd7}
@deffn {方法} TarInfo.isdir ()

如果它是一個目錄，則回傳 @ref{e02,,True}。
@end deffn

@geindex issym() (tarfile.TarInfo 的方法)
@anchor{library/tarfile tarfile TarInfo issym}@anchor{2dd8}
@deffn {方法} TarInfo.issym ()

如果它是一個符號連結，則回傳 @ref{e02,,True}。
@end deffn

@geindex islnk() (tarfile.TarInfo 的方法)
@anchor{library/tarfile tarfile TarInfo islnk}@anchor{2dd9}
@deffn {方法} TarInfo.islnk ()

Return @ref{e02,,True} if it is a hard link.
@end deffn

@geindex ischr() (tarfile.TarInfo 的方法)
@anchor{library/tarfile tarfile TarInfo ischr}@anchor{2dda}
@deffn {方法} TarInfo.ischr ()

如果它是一個字元裝置，則回傳 @ref{e02,,True}。
@end deffn

@geindex isblk() (tarfile.TarInfo 的方法)
@anchor{library/tarfile tarfile TarInfo isblk}@anchor{2ddb}
@deffn {方法} TarInfo.isblk ()

如果它是一個區塊裝置，則回傳 @ref{e02,,True}。
@end deffn

@geindex isfifo() (tarfile.TarInfo 的方法)
@anchor{library/tarfile tarfile TarInfo isfifo}@anchor{2ddc}
@deffn {方法} TarInfo.isfifo ()

如果它是一個 FIFO，則回傳 @ref{e02,,True}。
@end deffn

@geindex isdev() (tarfile.TarInfo 的方法)
@anchor{library/tarfile tarfile TarInfo isdev}@anchor{2ddd}
@deffn {方法} TarInfo.isdev ()

如果它是一個字元裝置、區塊裝置或 FIFO，則回傳 @ref{e02,,True}。
@end deffn

@node Extraction filters,命令列介面<5>,TarInfo 物件,tarfile --- 讀取與寫入 tar 封存檔案
@anchor{library/tarfile extraction-filters}@anchor{2dde}@anchor{library/tarfile tarfile-extraction-filter}@anchor{690}
@subsubsection Extraction filters



在 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{2ba7,,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{29c,,TarFile.extract()} or @ref{29b,,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{2ddf,,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{29a,,data_filter()} for details.

@item 
@code{None} (default): Use @ref{2dbb,,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{29a,,data}.
Previously, the default was equivalent to
@ref{2d91,,fully_trusted}.

@end quotation

@item 
A callable which will be called for each extracted member with a
@ref{2d9d,,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{1412,,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{29e,,errorlevel}.
Note that when extraction is aborted, @ref{29b,,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{2de0}
@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{2d91}
@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{2ddf}
@deffn {函式} tarfile.tar_filter (member, path)

Implements the @code{'tar'} filter.


@itemize -

@item 
Strip leading slashes (@code{/} and @ref{873,,os.sep}) from filenames.

@item 
@ref{2d9b,,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{2d9e,,AbsolutePathError}.

@item 
@ref{2d9b,,Refuse} to extract files whose absolute
path (after following symlinks) would end up outside the destination.
This raises @ref{2d9f,,OutsideDestinationError}.

@item 
Clear high mode bits (setuid, setgid, sticky) and group/other write bits
(@ref{2b32,,S_IWGRP} | @ref{2b35,,S_IWOTH}).
@end itemize

Return the modified @code{TarInfo} member.
@end deffn

@geindex data_filter() (於 tarfile 模組中)
@anchor{library/tarfile tarfile data_filter}@anchor{29a}
@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{2dc9,,TarInfo.linkname}) using
@ref{151a,,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{2d9b,,Refuse} to extract links (hard or soft)
that link to absolute paths, or ones that link outside the destination.

This raises @ref{2da1,,AbsoluteLinkError} or
@ref{2da2,,LinkOutsideDestinationError}.

Note that such files are refused even on platforms that do not support
symbolic links.

@item 
@ref{2d9b,,Refuse} to extract device files
(including pipes).
This raises @ref{2da0,,SpecialFileError}.

@item 
For regular files, including hard links:


@itemize -

@item 
Set the owner read and write permissions
(@ref{2b2d,,S_IRUSR} | @ref{2b2e,,S_IWUSR}).

@item 
Remove the group & other executable permission
(@ref{2b29,,S_IXGRP} | @ref{2b36,,S_IXOTH})
if the owner doesn’t have it (@ref{2b2f,,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{2ba7,,Hints for further verification}  for details.


在 3.14 版的變更: 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{2de1}@anchor{library/tarfile tarfile-extraction-refuse}@anchor{2d9b}
@subsubsection Filter errors


When a filter refuses to extract a file, it will raise an appropriate exception,
a subclass of @ref{2d9a,,FilterError}.
This will abort the extraction if @ref{29e,,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{2de2}@anchor{library/tarfile tarfile-further-verification}@anchor{2ba7}
@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{528,,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{2de3}
@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

或：

@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:
    # 當不再需要時移除它
    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{2de4}
@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 命令列介面<5>,範例<15>,Extraction filters,tarfile --- 讀取與寫入 tar 封存檔案
@anchor{library/tarfile command-line-interface}@anchor{2de5}@anchor{library/tarfile tarfile-commandline}@anchor{11c6}
@subsubsection 命令列介面



在 3.4 版被加入.


The @ref{e4,,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{2de6,,-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{2de7,,-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{2de8,,-l} option:

@example
$ python -m tarfile -l monty.tar
@end example

@menu
* 命令列選項: 命令列選項<3>. 

@end menu

@node 命令列選項<3>,,,命令列介面<5>
@anchor{library/tarfile command-line-options}@anchor{2de9}
@subsubsection 命令列選項


@geindex tarfile 命令列選項; -l
@geindex tarfile 命令列選項; --list
@anchor{library/tarfile cmdoption-tarfile-l}@anchor{2de8}
@deffn {Option} @w{-}l <tarfile>
@anchor{library/tarfile cmdoption-tarfile-list}@anchor{2dea}
@deffnx {Option} @w{-}@w{-}list <tarfile>

List files in a tarfile.
@end deffn

@geindex tarfile 命令列選項; -c
@geindex tarfile 命令列選項; --create
@anchor{library/tarfile cmdoption-tarfile-c}@anchor{2de6}
@deffn {Option} @w{-}c <tarfile> <source1> ... <sourceN>
@anchor{library/tarfile cmdoption-tarfile-create}@anchor{2deb}
@deffnx {Option} @w{-}@w{-}create <tarfile> <source1> ... <sourceN>

Create tarfile from source files.
@end deffn

@geindex tarfile 命令列選項; -e
@geindex tarfile 命令列選項; --extract
@anchor{library/tarfile cmdoption-tarfile-e}@anchor{2de7}
@deffn {Option} @w{-}e <tarfile> [<output_dir>]
@anchor{library/tarfile cmdoption-tarfile-extract}@anchor{2dec}
@deffnx {Option} @w{-}@w{-}extract <tarfile> [<output_dir>]

Extract tarfile into the current directory if `output_dir' is not specified.
@end deffn

@geindex tarfile 命令列選項; -t
@geindex tarfile 命令列選項; --test
@anchor{library/tarfile cmdoption-tarfile-t}@anchor{2ded}
@deffn {Option} @w{-}t <tarfile>
@anchor{library/tarfile cmdoption-tarfile-test}@anchor{2dee}
@deffnx {Option} @w{-}@w{-}test <tarfile>

Test whether the tarfile is valid or not.
@end deffn

@geindex tarfile 命令列選項; -v
@geindex tarfile 命令列選項; --verbose
@anchor{library/tarfile cmdoption-tarfile-v}@anchor{2def}@anchor{library/tarfile cmdoption-tarfile-verbose}@anchor{2df0}
@deffn {Option} @w{-}v, @w{-}@w{-}verbose

Verbose output.
@end deffn

@geindex tarfile 命令列選項; --filter
@anchor{library/tarfile cmdoption-tarfile-filter}@anchor{2df1}
@deffn {Option} @w{-}@w{-}filter <filtername>

Specifies the `filter' for @code{--extract}.
See @ref{690,,Extraction filters} for details.
Only string names are accepted (that is, @code{fully_trusted}, @code{tar},
and @code{data}).
@end deffn

@node 範例<15>,支援的 tar 格式,命令列介面<5>,tarfile --- 讀取與寫入 tar 封存檔案
@anchor{library/tarfile examples}@anchor{2df2}@anchor{library/tarfile tar-examples}@anchor{2d94}
@subsubsection 範例


@menu
* Reading examples:: 
* Writing examples:: 

@end menu

@node Reading examples,Writing examples,,範例<15>
@anchor{library/tarfile reading-examples}@anchor{2df3}
@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{29b,,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,範例<15>
@anchor{library/tarfile writing-examples}@anchor{2df4}
@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{186,,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{cc4,,sys.stdout.buffer} in the `fileobj' parameter
in @ref{de9,,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{de9,,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 支援的 tar 格式,Unicode issues,範例<15>,tarfile --- 讀取與寫入 tar 封存檔案
@anchor{library/tarfile supported-tar-formats}@anchor{2df5}@anchor{library/tarfile tar-formats}@anchor{2db1}
@subsubsection 支援的 tar 格式


There are three tar formats that can be created with the @ref{e4,,tarfile} module:


@itemize *

@item 
The POSIX.1-1988 ustar format (@ref{2db2,,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{2db3,,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. @ref{e4,,tarfile} fully supports the GNU tar
extensions for long names, sparse file support is read-only.

@item 
The POSIX.1-2001 pax format (@ref{2db4,,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,,支援的 tar 格式,tarfile --- 讀取與寫入 tar 封存檔案
@anchor{library/tarfile tar-unicode}@anchor{2db7}@anchor{library/tarfile unicode-issues}@anchor{2df6}
@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 @ref{e4,,tarfile} are controlled by the
`encoding' and `errors' keyword arguments of the @ref{1411,,TarFile} class.

`encoding' defines the character encoding to use for the metadata in the
archive. The default value is @ref{e4e,,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{1a9e,,Error Handlers}.
The default scheme is @code{'surrogateescape'} which Python also uses for its
file system calls, see @ref{2df7,,File Names@comma{} Command Line Arguments@comma{} and Environment Variables}.

For @ref{2db4,,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 檔案格式,加密服務,資料壓縮與保存,Python 標準函式庫 Standard Library
@anchor{library/fileformats doc}@anchor{2df8}@anchor{library/fileformats file-formats}@anchor{2df9}@anchor{library/fileformats fileformats}@anchor{2dfa}@anchor{library/fileformats translation-repo}@anchor{2dfb}
@section 檔案格式


本章所描述的模組會剖析各種非標記類型語言且與電子郵件無關的雜項檔案格式。

@menu
* csv: csv --- CSV 檔案讀取及寫入. CSV 檔案讀取及寫入
* configparser: configparser --- 設定檔剖析器. 設定檔剖析器
* tomllib: tomllib --- 剖析 TOML 檔案. 剖析 TOML 檔案
* netrc: netrc --- netrc 檔案處理. netrc 檔案處理
* plistlib: plistlib --- 產生和剖析 Apple plist 檔案. 產生和剖析 Apple .plist 檔案

@end menu

@node csv --- CSV 檔案讀取及寫入,configparser --- 設定檔剖析器,,檔案格式
@anchor{library/csv doc}@anchor{2dfc}@anchor{library/csv csv-csv-file-reading-and-writing}@anchor{2dfd}@anchor{library/csv module-csv}@anchor{2d}
@subsection @code{csv} --- CSV 檔案讀取及寫入


@geindex module; csv

`原始碼：'Lib/csv.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/csv.py}

@geindex csv
@geindex data（資料）;tabular（表格）


__________________________________________________________________


所謂的 CSV (Comma Separated Values) 檔案格式是試算表及資料庫中最常見的匯入、匯出檔案格式。在嘗試以 
@geindex RFC; RFC 4180
RFC 4180@footnote{https://datatracker.ietf.org/doc/html/rfc4180.html} 中的標準化方式來描述格式之前，CSV 格式已經使用了許多年。由於缺少一個完善定義的標準，意味著各個不同的應用程式會在資料產生及銷毀時有微妙的差別。這些不同之處使得從不同資料來源處理 CSV 檔案時會非常擾人。儘管如此，雖然分隔符號和引號字元有所不同，整體的格式非常相似，可以寫個單一模組來高效率的操作這樣的資料，讓程式設計師可以隱藏讀取及寫入資料的細節。

@ref{2d,,csv} 模組實作透過 class 去讀取、寫入 CSV 格式的表格資料。它讓程式設計師可以說出：「以 Excel 為首選並寫入該種格式的資料」或是「從 Excel 產生的檔案來讀取資料」，且無需知道這是 Excel 所使用的 CSV 格式等精確的細節。程式設計師也可以描述其他應用程式所理解的 CSV 格式或他們自行定義具有特殊意義的 CSV 格式。

@ref{2d,,csv} 模組的 @ref{6a7,,reader} 及 @ref{6a8,,writer} 物件可以讀取及寫入序列。程式設計師也可以透過 @ref{bcf,,DictReader} 及 @ref{13ff,,DictWriter} class（類別）使用 dictionary （字典）讀取及寫入資料。


@subsubheading 也參考



@table @asis

@geindex Python Enhancement Proposals; PEP 305

@item PEP 305@footnote{https://peps.python.org/pep-0305/} - CSV 檔案 API

Python Enhancement Proposal (PEP) 所提出的 Python 附加功能。
@end table


@menu
* 模組內容: 模組內容<3>. 
* Dialect 與格式參數:: 
* 讀取器物件:: 
* 寫入器物件:: 
* 範例: 範例<16>. 

@end menu

@node 模組內容<3>,Dialect 與格式參數,,csv --- CSV 檔案讀取及寫入
@anchor{library/csv csv-contents}@anchor{2dfe}@anchor{library/csv module-contents}@anchor{2dff}
@subsubsection 模組內容


@ref{2d,,csv} 模組定義了以下函式：

@geindex universal newlines;csv.reader 函式

@geindex reader() (於 csv 模組中)
@anchor{library/csv csv reader}@anchor{6a7}
@deffn {函式} csv.reader (csvfile, /, dialect='excel', **fmtparams)

回傳一個@ref{2e00,,讀取器物件 (reader object)} 並處理在指定的 `csvfile' 中的每一行，csvfile 必須是字串的可疊代物件 (iterable of strings)，其中每個字串都要是讀取器所定義的 csv 格式，csvfile 通常是個類檔案物件或者 list。如果 `csvfile' 是個檔案物件，則需開啟時使用 @code{newline='@w{'}}。 @footnote{
如果 @code{newline='@w{'}} 沒有被指定，則嵌入引號中的換行符號不會被正確直譯，使用 @code{\r\n} 行尾 (line ending) 的平台會寫入額外的 @code{\r}。自從 csv 模組有自己 (@ref{f30,,統一的}) 換行處理方式，因此指定 @code{newline='@w{'}} 會永遠是安全的。
} `dialect' 為一個可選填的參數，可以用為特定的 CSV dialect（方言） 定義一組參數。它可能為 @ref{17aa,,Dialect} 的一個子類別 (subclass) 的實例或是由 @ref{1abe,,list_dialects()} 函式回傳的多個字串中的其中之一。另一個可選填的關鍵字引數 `fmtparams' 可以在這個 dialect 中覆寫 (override) 個別的格式化參數 (formatting parameter)。關於 dialect 及格式化參數的完整說明，請見段落 @ref{2e01,,Dialect 與格式參數}。

從 CSV 檔案讀取的每一列會回傳為一個字串列表。除非格式選項 @ref{18ae,,QUOTE_NONNUMERIC} 有被指定（在這個情況之下，沒有引號的欄位都會被轉換成浮點數），否則不會進行自動資料型別轉換。

一個簡短的用法範例：

@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{6a8}
@deffn {函式} csv.writer (csvfile, /, dialect='excel', **fmtparams)

回傳一個寫入器物件 (writer object)，其負責在給定的類檔案物件 (file-like object) 上將使用者的資料轉換為分隔字串 (delimited string)。`csvfile' 可以為具有 @ref{1f22,,write()} method 的任何物件。若 `csvfile' 為一個檔案物件，它應該使用 @code{newline='@w{'}} 開啟 @footnote{
如果 @code{newline='@w{'}} 沒有被指定，則嵌入引號中的換行符號不會被正確直譯，使用 @code{\r\n} 行尾 (line ending) 的平台會寫入額外的 @code{\r}。自從 csv 模組有自己 (@ref{f30,,統一的}) 換行處理方式，因此指定 @code{newline='@w{'}} 會永遠是安全的。
} 。`dialect' 為一個可選填的參數，可以用為特定的 CSV dialect 定義一組參數。它可能為 @ref{17aa,,Dialect} 的一個子類別的實例或是由 @ref{1abe,,list_dialects()} 函式回傳的多個字串中的其中之一。另一個可選填的關鍵字引數 `fmtparams' 可以在這個 dialect 中覆寫個別的格式化參數。關於 dialect 及格式化參數的完整說明，請見段落 @ref{2e01,,Dialect 與格式參數}。為了更容易與有實作 DB API 的模組互相接合，@ref{87e,,None} 值會被寫成空字串。雖然這不是一個可逆的變換，這使得dump （傾印） SQL NULL 資料值到 CSV 檔案上就無需讓 @code{cursor.fetch*} 呼叫回傳的資料進行預處理 (preprocessing)。其餘非字串的資料則會在寫入之前用 @ref{169,,str()} 函式進行字串化 (stringify)。

一個簡短的用法範例：

@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{189f}
@deffn {函式} csv.register_dialect (name, /, dialect='excel', **fmtparams)

將 `dialect' 與 `name' 進行關聯 (associate)。`name' 必須為字串。這個 dialect 可以透過傳遞 @ref{17aa,,Dialect} 的子類別進行指定；或是關鍵字引數 `fmtparams'；或是以上兩者皆是，並透過關鍵字引數來覆寫 dialect 的參數。關於 dialect 及格式化參數的完整說明，請見段落 @ref{2e01,,Dialect 與格式參數}。
@end deffn

@geindex unregister_dialect() (於 csv 模組中)
@anchor{library/csv csv unregister_dialect}@anchor{1abd}
@deffn {函式} csv.unregister_dialect (name)

從 dialect 註冊表 (registry) 中，刪除與 `name' 關聯的 dialect。若 `name' 如果不是註冊的 dialect 名稱，則會產生一個 @ref{2e02,,Error}。
@end deffn

@geindex get_dialect() (於 csv 模組中)
@anchor{library/csv csv get_dialect}@anchor{1abc}
@deffn {函式} csv.get_dialect (name)

回傳一個與 `name' 關聯的 dialect。若 `name' 如果不是註冊的 dialect 名稱，則會產生一個 @ref{2e02,,Error}。這個函式會回傳一個 immutable （不可變物件） @ref{17aa,,Dialect}。
@end deffn

@geindex list_dialects() (於 csv 模組中)
@anchor{library/csv csv list_dialects}@anchor{1abe}
@deffn {函式} csv.list_dialects ()

回傳所有已註冊的 dialect 名稱。
@end deffn

@geindex field_size_limit() (於 csv 模組中)
@anchor{library/csv csv field_size_limit}@anchor{1abb}
@deffn {函式} csv.field_size_limit ()

@deffnx {函式} csv.field_size_limit (new_limit)

回傳目前的剖析器 (parser) 允許的最大字串大小。如果 `new_limit' 被給定，則會變成新的最大字串大小。
@end deffn

@ref{2d,,csv} 模組定義了下列的類別：

@geindex DictReader (csv 中的類別)
@anchor{library/csv csv DictReader}@anchor{bcf}
@deffn {類別} csv.DictReader (f, fieldnames=None, restkey=None, restval=None, dialect='excel', *args, **kwds)

建立一個物件，其運作上就像一般的讀取器，但可以將每一列資訊 map （對映） 到 @ref{183,,dict} 中，可以透過選填的參數 `fieldnames' 設定 key。

參數 `fieldnames' 是一個 @ref{70f,,sequence}。如果 `fieldnames' 被省略了，檔案 `f' 中第一列的值會被當作欄位標題，且於結果中會被省略。如果 `fieldname' 有提供，它們就會被使用，且第一列會被包含在結果中。不管欄位標題是如何決定的，dictionary 都會保留原始的排序。

如果一列資料中的欄位比欄位標題還多，其餘的資料及以 `restkey' （預設為 @code{None}）特指的欄位標題會放入列表當中並儲存。如果一個非空的 (non-blank) 列中的欄位比欄位標題還少，缺少的值則會填入 `restval' （預設為 @code{None}）的值。

所有其他選填的引數或關鍵字引數皆會傳遞至下層的 @ref{6a7,,reader} 實例。

如果傳遞至 `fieldnames' 的引數是個疊代器，則會被迫成為一個 @ref{24d,,list}。


在 3.6 版的變更: 回傳的列已成為型別 @code{OrderedDict}。



在 3.8 版的變更: 回傳的列已成為型別 @ref{183,,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{13ff}
@deffn {類別} csv.DictWriter (f, fieldnames, restval='@w{'}, extrasaction='raise', dialect='excel', *args, **kwds)

建立一個物件，其運作上就像一般的寫入器，但可以將 dictionary map 到輸出的列上。參數 `fieldnames' 是一個鍵值的 @ref{1f,,sequence} 且可以辨識 dictionary 中傳遞至 @ref{fe4,,writerow()} method 寫入至檔案 `f' 中的值。如果 dictionary 中缺少了 `fieldnames' 的鍵值，則會寫入選填的參數 `restval' 的值。如果傳遞至 @ref{fe4,,writerow()} method 的 dictionary 包含了一個 `fieldnames' 中不存在的鍵值，選填的參數 `extrasaction' 可以指出該執行的動作。如果它被設定為 @code{'raise'}，預設會觸發 @ref{2eb,,ValueError}。如果它被設定為 @code{'ignore'}，dictionary 中額外的值會被忽略。其他選填的引數或關鍵字引數皆會傳遞至下層的 @ref{6a8,,writer} 實例。

請記得這不像類別 @ref{bcf,,DictReader}，在類別 @ref{13ff,,DictWriter} 中，參數 `fieldnames' 並不是選填的。

如果傳遞至 `fieldnames' 的引數是個疊代器，則會被迫成為一個 @ref{24d,,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{17aa}
@deffn {類別} csv.Dialect

類別 @ref{17aa,,Dialect} 是一個容器類別，其屬性 (attribute) 包含如何處理雙引號、空白、分隔符號等資訊。由於缺少一個嚴謹的 CSV 技術規範，不同的應用程式會產出有巧妙不同的 CSV 資料。@ref{17aa,,Dialect} 實例定義了 @ref{6a7,,reader} 以及 @ref{6a8,,writer} 的實例該如何表示。

所有可用的 @ref{17aa,,Dialect} 名稱會透過 @ref{1abe,,list_dialects()} 回傳，且它們可以透過特定 @ref{6a7,,reader} 及 @ref{6a8,,writer} 類別的初始器 (initializer, @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{2e03}
@deffn {類別} csv.excel

類別 @ref{2e03,,excel} 定義了透過 Excel 產生的 CSV 檔案的慣用屬性。它被註冊的 dialect 名稱為 @code{'excel'}。
@end deffn

@geindex excel_tab (csv 中的類別)
@anchor{library/csv csv excel_tab}@anchor{2e04}
@deffn {類別} csv.excel_tab

類別 @ref{2e04,,excel_tab} 定義了透過 Excel 產生並以 Tab 作為分隔的 CSV 檔案的慣用屬性。它被註冊的 dialect 名稱為 @code{'excel-tab'}。
@end deffn

@geindex unix_dialect (csv 中的類別)
@anchor{library/csv csv unix_dialect}@anchor{13fe}
@deffn {類別} csv.unix_dialect

類別 @ref{13fe,,unix_dialect} 定義了透過 UNIX 系統產生的 CSV 檔案的慣用屬性，換句話說，使用 @code{'\n'} 作為換行符號且所有欄位都被引號包覆起來。它被註冊的 dialect 名稱為 @code{'unix'}。


在 3.2 版被加入.

@end deffn

@geindex Sniffer (csv 中的類別)
@anchor{library/csv csv Sniffer}@anchor{2e05}
@deffn {類別} csv.Sniffer

類別 @ref{2e05,,Sniffer} 被用來推斷 CSV 檔案的格式。

類別 @ref{2e05,,Sniffer} 提供了兩個 method：

@geindex sniff() (csv.Sniffer 的方法)
@anchor{library/csv csv Sniffer sniff}@anchor{2e06}
@deffn {方法} sniff (sample, delimiters=None)

分析給定的 `sample' 且回傳一個 @ref{17aa,,Dialect} 子類別，反應出找到的格式參數。如果給定選填的參數 `delimiters'，它會被解釋為一個字串且含有可能、有效的分隔字元。
@end deffn

@geindex has_header() (csv.Sniffer 的方法)
@anchor{library/csv csv Sniffer has_header}@anchor{1b59}
@deffn {方法} has_header (sample)

如果第一列的文字顯示將作為一系列的欄位標題，會分析 sample 文字（假定他是 CSV 格式）並回傳 @ref{e02,,True}。檢查每一欄時，會考慮是否滿足兩個關鍵標準其中之一，判斷 sample 是否包含標題：


@itemize -

@item 
第二列至第 n 列包含數字

@item 
第二列到第 n 列包含的字串中至少有一個值的長度與該行的假定標題的長度不同。
@end itemize

對第一列之後的二十個列進行取樣；如果超過一半的行及列滿足條件，則返回 @ref{e02,,True}。
@end deffn

@cartouche
@quotation 備註 
此方法是一個粗略的啟發，可能會產生偽陽性及偽陰性 (false positives and negatives)。
@end quotation
@end cartouche
@end deffn

一個 @ref{2e05,,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)
    # ... 在這邊處理 CSV 檔案 ...
@end example
@anchor{library/csv csv-constants}@anchor{2e07}
@ref{2d,,csv} 模組定義了以下常數：

@geindex QUOTE_ALL (於 csv 模組中)
@anchor{library/csv csv QUOTE_ALL}@anchor{2e08}
@deffn {資料} csv.QUOTE_ALL

引導 @ref{6a8,,writer} 物件引用所有欄位。
@end deffn

@geindex QUOTE_MINIMAL (於 csv 模組中)
@anchor{library/csv csv QUOTE_MINIMAL}@anchor{2e09}
@deffn {資料} csv.QUOTE_MINIMAL

引導 @ref{6a8,,writer} 物件只引用包含特殊字元的欄位，例如：`delimiter'、`quotechar'、@code{'\r'}、@code{'\n'} 或是 `lineterminator' 的其他字元。
@end deffn

@geindex QUOTE_NONNUMERIC (於 csv 模組中)
@anchor{library/csv csv QUOTE_NONNUMERIC}@anchor{18ae}
@deffn {資料} csv.QUOTE_NONNUMERIC

引導 @ref{6a8,,writer} 物件引用所有非數字的欄位。

引導 @ref{6a7,,reader} 物件轉換所有非引用的欄位為 @ref{196,,float}。

@cartouche
@quotation 備註 
Some numeric types, such as @ref{3c1,,bool}, @ref{213,,Fraction},
or @ref{ed6,,IntEnum}, have a string representation that cannot be
converted to @ref{196,,float}.
They cannot be read in the @ref{18ae,,QUOTE_NONNUMERIC} and
@ref{6a6,,QUOTE_STRINGS} modes.
@end quotation
@end cartouche
@end deffn

@geindex QUOTE_NONE (於 csv 模組中)
@anchor{library/csv csv QUOTE_NONE}@anchor{2e0a}
@deffn {資料} csv.QUOTE_NONE

引導 @ref{6a8,,writer} 物件不得引用欄位。當目前的 `delimiter'、`quotechar'、@code{'\r'}、@code{'\n'} 或是 `lineterminator' 的其他字元出現在輸出資料時，在他之前的字元是目前的 `escapechar'。如果沒有設定 `escapechar'，若遇到任何字元需要逸出，寫入器則會引發 @ref{2e02,,Error}。設定 `quotechar' 為 @code{None} 以防止逸出。

引導 @ref{6a7,,reader} 物件不對引號進行特別處理。
@end deffn

@geindex QUOTE_NOTNULL (於 csv 模組中)
@anchor{library/csv csv QUOTE_NOTNULL}@anchor{6a5}
@deffn {資料} csv.QUOTE_NOTNULL

引導 @ref{6a8,,writer} 物件引用所有非 @code{None} 的欄位。這與 @ref{2e08,,QUOTE_ALL} 相似，除非如果欄位值為 @code{None}，該欄位則被寫成空（沒有引號）字串。

引導 @ref{6a7,,reader} 物件將空（沒有引號）欄位直譯 (interpret) 為 @code{None}，否則會和 @ref{2e08,,QUOTE_ALL} 有相同的表現方式。


在 3.12 版被加入.

@end deffn

@geindex QUOTE_STRINGS (於 csv 模組中)
@anchor{library/csv csv QUOTE_STRINGS}@anchor{6a6}
@deffn {資料} csv.QUOTE_STRINGS

引導 @ref{6a8,,writer} 物件永遠在字串的欄位前後放置引號。這與 @ref{18ae,,QUOTE_NONNUMERIC} 相似，除非如果欄位值為 @code{None}，該欄位則被寫成空（沒有引號）字串。

引導 @ref{6a7,,reader} 物件將空（沒有引號）字串直譯為 @code{None}，否則會和 @ref{2e08,,QUOTE_ALL} 有相同的表現方式。


在 3.12 版被加入.

@end deffn

@ref{2d,,csv} 模組定義下列例外：

@geindex Error
@anchor{library/csv csv Error}@anchor{2e02}
@deffn {例外} csv.Error

當偵測到錯誤時，任何函式都可以引發。
@end deffn

@node Dialect 與格式參數,讀取器物件,模組內容<3>,csv --- CSV 檔案讀取及寫入
@anchor{library/csv csv-fmt-params}@anchor{2e01}@anchor{library/csv dialects-and-formatting-parameters}@anchor{2e0b}
@subsubsection Dialect 與格式參數


為了讓指定輸入及輸出紀錄的格式更方便，特定的格式化參數會被組成 dialect。一個 dialect 是 @ref{17aa,,Dialect} class 的子類別，其包含多個描述 CSV 檔案格式的多個屬性。當建立 @ref{6a7,,reader} 或 @ref{6a8,,writer} 物件時，程式設計師可以指定一個字串或是一個 @ref{17aa,,Dialect} 的子類別作為 dialect 參數。此外，或是作為替代，在`dialect'參數中，程式設計師可以指定個別的格式化參數，其與 @ref{17aa,,Dialect} 類別定義的屬性具有相同的名字。

Dialect 支援下列屬性：

@geindex delimiter (csv.Dialect 的屬性)
@anchor{library/csv csv Dialect delimiter}@anchor{2e0c}
@deffn {屬性} Dialect.delimiter

一個單一字元 (one-character) 的字串可已用來分割欄位。預設為 @code{','}。
@end deffn

@geindex doublequote (csv.Dialect 的屬性)
@anchor{library/csv csv Dialect doublequote}@anchor{2e0d}
@deffn {屬性} Dialect.doublequote

控制 `quotechar' 的實例何時出現在欄位之中，並讓它們自己被放在引號之內。當屬性為 @ref{e02,,True}，字元會是雙引號。若為 @ref{d23,,False}，在 `quotechar' 之前會先使用 `escapechar' 作為前綴字。預設為 @ref{e02,,True}。

在輸出時，若 `doublequote' 是 @ref{d23,,False} 且`逸出字元'沒有被設定，當一個`引號'在欄位中被發現時，@ref{2e02,,Error} 會被引發。
@end deffn

@geindex escapechar (csv.Dialect 的屬性)
@anchor{library/csv csv Dialect escapechar}@anchor{2e0e}
@deffn {屬性} Dialect.escapechar

一個單一字元的字串，會被寫入器用來逸出需要逸出的字元：

@quotation


@itemize *

@item 
the `delimiter', the `quotechar', @code{'\r'}, @code{'\n'} and any of the
characters in `lineterminator' are escaped if `quoting' is set to
@ref{2e0a,,QUOTE_NONE};

@item 
the `quotechar' is escaped if `doublequote' is @ref{d23,,False};

@item 
`escapechar' 本身。
@end itemize
@end quotation

在讀取時，`escapechar' 會移除後面字元的任何特殊意義。預設為 @ref{87e,,None}，表示禁止逸出。


在 3.11 版的變更: `escapechar' 為空是不被接受的。

@end deffn

@geindex lineterminator (csv.Dialect 的屬性)
@anchor{library/csv csv Dialect lineterminator}@anchor{2e0f}
@deffn {屬性} Dialect.lineterminator

由 @ref{6a8,,writer} 產生被用來分行的字串。預設為 @code{'\r\n'}。

@cartouche
@quotation 備註 
@ref{6a7,,reader} 是 hard-coded 辨別 @code{'\r'} or @code{'\n'} 作為行尾 (end-of-line)，並忽略`lineterminator'。未來可能會改變這個行為。
@end quotation
@end cartouche
@end deffn

@geindex quotechar (csv.Dialect 的屬性)
@anchor{library/csv csv Dialect quotechar}@anchor{2e10}
@deffn {屬性} Dialect.quotechar

一個單一字元的字串被用於引用包含特殊字元的欄位，像是 `delimiter'、`quotechar' 或是換行字元（@code{'\r'}、@code{'\n'} 或是 `lineterminator' 的任一字元）。預設為 @code{'"'}。如果 `quoting' 設定為 @ref{2e0a,,QUOTE_NONE}，可以設定為 @code{None} 以防止逸出 @code{'"'}。


在 3.11 版的變更: `quotechar' 為空是不被允許的。

@end deffn

@geindex quoting (csv.Dialect 的屬性)
@anchor{library/csv csv Dialect quoting}@anchor{2e11}
@deffn {屬性} Dialect.quoting

控制 writer 何時產生引號，以及 reader 如何辨識引號。如 `quotechar' 不為 @code{None}，則可以使用任何 @ref{2e07,,QUOTE_* 常數}且預設為 @ref{2e09,,QUOTE_MINIMAL}。否則預設為 @ref{2e0a,,QUOTE_NONE}。
@end deffn

@geindex skipinitialspace (csv.Dialect 的屬性)
@anchor{library/csv csv Dialect skipinitialspace}@anchor{2e12}
@deffn {屬性} Dialect.skipinitialspace

若為 @ref{e02,,True}，在緊接著`delimiter'後的空格會被忽略。預設為 @ref{d23,,False}。當結合 @code{delimiter=' '} 與 @code{skipinitialspace=True} 時，不允許沒有引號的空欄位。
@end deffn

@geindex strict (csv.Dialect 的屬性)
@anchor{library/csv csv Dialect strict}@anchor{2e13}
@deffn {屬性} Dialect.strict

若為 @code{True}，若有錯誤的 CSV 輸入則會引發 @ref{2e02,,Error}。預設為 @code{False}。
@end deffn

@node 讀取器物件,寫入器物件,Dialect 與格式參數,csv --- CSV 檔案讀取及寫入
@anchor{library/csv id3}@anchor{2e14}@anchor{library/csv reader-objects}@anchor{2e00}
@subsubsection 讀取器物件


讀取器物件（@ref{6a7,,reader()} 函式回傳的 @ref{bcf,,DictReader} 實例與物件）有下列公開方法 (public method)：

@geindex __next__() (csv.csvreader 的方法)
@anchor{library/csv csv csvreader __next__}@anchor{2e15}
@deffn {方法} csvreader.__next__ ()

回傳一個列表為讀入器的可疊代物件的下一列內容（若該物件是由 @ref{6a7,,reader()} 回傳）或是一個 dict（若為 @ref{bcf,,DictReader} 實例），會依據目前的 @ref{17aa,,Dialect} 進行剖析。通常會用 @code{next(reader)} 來進行呼叫。
@end deffn

讀取器物件有下列公開屬性 (public attributes)：

@geindex dialect (csv.csvreader 的屬性)
@anchor{library/csv csv csvreader dialect}@anchor{2e16}
@deffn {屬性} csvreader.dialect

dialect 的唯讀敘述，會被剖析器使用。
@end deffn

@geindex line_num (csv.csvreader 的屬性)
@anchor{library/csv csv csvreader line_num}@anchor{2e17}
@deffn {屬性} csvreader.line_num

來源疊代器所讀取的行數。這與回傳的紀錄數不同，因為可以進行跨行紀錄。
@end deffn

DictReader 物件有下列公開屬性：

@geindex fieldnames (csv.DictReader 的屬性)
@anchor{library/csv csv DictReader fieldnames}@anchor{2e18}
@deffn {屬性} DictReader.fieldnames

若在建立物件時沒有作為參數傳遞，這個屬性會在第一次存取之前或是第一筆資料被讀取之前進行初始化 (initialize)。
@end deffn

@node 寫入器物件,範例<16>,讀取器物件,csv --- CSV 檔案讀取及寫入
@anchor{library/csv writer-objects}@anchor{2e19}
@subsubsection 寫入器物件


@ref{6a8,,writer} 物件（@ref{6a8,,writer()} 函式回傳的 @ref{13ff,,DictWriter} 實例與物件）有下列公開方法。對於 @ref{6a8,,writer} 物件而言，一個`列'中必須為一個可疊代的字串或是數字；對於 @ref{13ff,,DictWriter} 物件而言，則必須為一個 dictionary ，且可以對應欄位標題至字串或數字（會先透過 @ref{169,,str()} 進行傳遞）。請注意，在寫入複數 (complex number) 時會用小括號 (parens) 包起來。這可能在其他程式讀取 CSV 檔案時導致某些問題（假設他們完全支援複雜數字）。

@geindex writerow() (csv.csvwriter 的方法)
@anchor{library/csv csv csvwriter writerow}@anchor{fe4}
@deffn {方法} csvwriter.writerow (row, /)

將參數 `row' 寫入至寫入器的檔案物件中，並依照目前的 @ref{17aa,,Dialect} 進行格式化。回傳下層檔案物件 `write' 方法的回傳值。


在 3.5 版的變更: 新增對任意可疊代物件 (arbitrary iterables) 的支援。

@end deffn

@geindex writerows() (csv.csvwriter 的方法)
@anchor{library/csv csv csvwriter writerows}@anchor{2e1a}
@deffn {方法} csvwriter.writerows (rows, /)

將 `rows' 中所有元素（為上述的一個可疊代的 `row' 物件）寫入至寫入器的檔案物件中，並依照目前的 dialect 進行格式化。
@end deffn

寫入器物件有下列公開屬性：

@geindex dialect (csv.csvwriter 的屬性)
@anchor{library/csv csv csvwriter dialect}@anchor{2e1b}
@deffn {屬性} csvwriter.dialect

dialect 的唯讀敘述，會被寫入器使用。
@end deffn

DictWriter 物件有下列公開方法：

@geindex writeheader() (csv.DictWriter 的方法)
@anchor{library/csv csv DictWriter writeheader}@anchor{1400}
@deffn {方法} DictWriter.writeheader ()

將具欄位標題的一列（於建構函式 (constructor) 中指定的）寫入至寫入器的檔案物件中，並依照目前的 dialect 進行格式化。回傳內部呼叫 @ref{fe4,,csvwriter.writerow()} 的回傳值。


在 3.2 版被加入.



在 3.8 版的變更: @ref{1400,,writeheader()} 現在也會回傳內部呼叫 @ref{fe4,,csvwriter.writerow()} 的回傳值。

@end deffn

@node 範例<16>,,寫入器物件,csv --- CSV 檔案讀取及寫入
@anchor{library/csv csv-examples}@anchor{2e1c}@anchor{library/csv examples}@anchor{2e1d}
@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{315,,open()} 被使用於開啟並讀取一個 CSV 檔案，該檔案會預設使用系統預設的編碼格式（請見 @ref{328,,locale.getencoding()}），並解碼為 unicode。若要使用不同編碼格式進行檔案解碼，請使用 open 函式的 @code{encoding} 引數：

@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

同理可以應用到使用不同編碼格式進行寫入：當開啟輸出檔案時，指定 @code{encoding} 引數。

註冊一個新的 dialect ：

@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

而當模組無法直接支援剖析字串時，仍可以輕鬆的解決：

@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 --- 設定檔剖析器,tomllib --- 剖析 TOML 檔案,csv --- CSV 檔案讀取及寫入,檔案格式
@anchor{library/configparser doc}@anchor{2e1e}@anchor{library/configparser configparser-configuration-file-parser}@anchor{2e1f}@anchor{library/configparser module-configparser}@anchor{26}@anchor{library/configparser translation-repo}@anchor{2e20}
@subsection @code{configparser} --- 設定檔剖析器


@geindex module; configparser

`原始碼：'Lib/configparser.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/configparser.py}

@geindex .ini;file（檔案）
@geindex configuration（設定）;file（檔案）
@geindex ini file（ini 檔案）
@geindex Windows ini file（Windows ini 檔案）


__________________________________________________________________


This module provides the @ref{4d9,,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


@subsubheading 也參考



@table @asis

@item @ref{102,,tomllib} 模組

TOML is a well-specified format for application configuration files.
It is specifically designed to be an improved version of INI.

@item @ref{c9,,shlex} 模組

Support for creating Unix shell-like mini-languages which can also
be used for application configuration files.

@item @ref{86,,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:: 
* 支援的 INI 檔案結構:: 
* Unnamed Sections:: 
* Interpolation of values:: 
* Mapping Protocol Access:: 
* Customizing Parser Behaviour:: 
* Legacy API Examples:: 
* ConfigParser 物件:: 
* RawConfigParser 物件:: 
* 例外: 例外<8>. 

@end menu

@node Quick Start,Supported Datatypes,,configparser --- 設定檔剖析器
@anchor{library/configparser quick-start}@anchor{2e21}
@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{2e22,,in the following section}.  Essentially, the file
consists of sections, each of which contains keys with values.
@ref{26,,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{2e23,,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{2e24,,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{2e24,,Customizing Parser Behaviour} section.
}.

It is possible to read several configurations into a single
@ref{4d9,,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{165d,,ConfigParser.read()} call with several
files passed to the `filenames' parameter.

@node Supported Datatypes,Fallback Values,Quick Start,configparser --- 設定檔剖析器
@anchor{library/configparser supported-datatypes}@anchor{2e25}
@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{2e26,,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{2e24,,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{2e26,,getboolean()}, config parsers also
provide equivalent @ref{2e27,,getint()} and
@ref{2e28,,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{2e24,,Customizing Parser Behaviour} section.
}

@node Fallback Values,支援的 INI 檔案結構,Supported Datatypes,configparser --- 設定檔剖析器
@anchor{library/configparser fallback-values}@anchor{2e29}
@subsubsection Fallback Values


As with a dictionary, you can use a section's @ref{146c,,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{146c,,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{2e27,,getint()}, @ref{2e28,,getfloat()} and
@ref{2e26,,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 支援的 INI 檔案結構,Unnamed Sections,Fallback Values,configparser --- 設定檔剖析器
@anchor{library/configparser supported-ini-file-structure}@anchor{2e22}
@subsubsection 支援的 INI 檔案結構


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{2e24,,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{2e24,,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{2e24,,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{2e2a,,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{18a7,,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{2e24,,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{2e24,,Customizing Parser Behaviour} section.
}

舉例來說：

@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,支援的 INI 檔案結構,configparser --- 設定檔剖析器
@anchor{library/configparser id10}@anchor{2e2b}@anchor{library/configparser unnamed-sections}@anchor{2e2c}
@subsubsection Unnamed Sections


The name of the first section (or unique) may be omitted and values
retrieved by the @ref{18a7,,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 --- 設定檔剖析器
@anchor{library/configparser interpolation-of-values}@anchor{2e2d}
@subsubsection Interpolation of values


On top of the core functionality, @ref{4d9,,ConfigParser} supports
interpolation.  This means values can be preprocessed before returning them
from @code{get()} calls.

@geindex % （百分號）;interpolation in configuration files（設定檔中的插值）

@geindex BasicInterpolation (configparser 中的類別)
@anchor{library/configparser configparser BasicInterpolation}@anchor{924}
@deffn {類別} configparser.BasicInterpolation

The default implementation used by @ref{4d9,,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{2e24,,Customizing Parser Behaviour} section.
}.  Additional default
values can be provided on initialization.

舉例來說：

@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{4d9,,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 $ （金錢符號）;interpolation in configuration files（設定檔中的插值）

@geindex ExtendedInterpolation (configparser 中的類別)
@anchor{library/configparser configparser ExtendedInterpolation}@anchor{925}
@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 --- 設定檔剖析器
@anchor{library/configparser mapping-protocol-access}@anchor{2e23}
@subsubsection Mapping Protocol Access



在 3.2 版被加入.


Mapping protocol access is a generic name for functionality that enables using
custom objects as if they were dictionaries.  In case of @ref{26,,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.

@ref{26,,configparser} objects behave as close to actual dictionaries as possible.
The mapping interface is complete and adheres to the
@ref{12ad,,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{2e24,,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{5df,,KeyError}.

@item 
@code{DEFAULTSECT} 不能從剖析器中移除：


@itemize *

@item 
嘗試刪除它會引發 @ref{2eb,,ValueError}，

@item 
@code{parser.clear()} 會保持它不變，

@item 
@code{parser.popitem()} 永遠不會回傳它。
@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 --- 設定檔剖析器
@anchor{library/configparser customizing-parser-behaviour}@anchor{2e24}
@subsubsection Customizing Parser Behaviour


There are nearly as many INI format variants as there are applications using it.
@ref{26,,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{2e2e,,read_dict()} before you read the actual file.

@item 
`dict_type', default value: @ref{183,,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 @ref{26,,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{1de,,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 @ref{26,,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{723,,read_file()},
@ref{2e2f,,read_string()} or @ref{2e2e,,read_dict()}).  It is recommended to use strict
parsers in new applications.


在 3.2 版的變更: In previous versions of @ref{26,,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{2e2d,,dedicated documentation section}.
@ref{115f,,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{2e27,,getint()}, @ref{2e28,,getfloat()}, and
@ref{2e26,,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{2e30}
@deffn {屬性} ConfigParser.BOOLEAN_STATES

By default when using @ref{2e26,,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{2e2a}
@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 物件,Customizing Parser Behaviour,configparser --- 設定檔剖析器
@anchor{library/configparser legacy-api-examples}@anchor{2e31}
@subsubsection Legacy API Examples


Mainly because of backwards compatibility concerns, @ref{26,,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{4d9,,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 物件,RawConfigParser 物件,Legacy API Examples,configparser --- 設定檔剖析器
@anchor{library/configparser configparser-objects}@anchor{2e32}@anchor{library/configparser id13}@anchor{2e33}
@subsubsection ConfigParser 物件


@geindex ConfigParser (configparser 中的類別)
@anchor{library/configparser configparser ConfigParser}@anchor{4d9}
@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{146f,,DuplicateSectionError} or
@ref{1470,,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{2e2d,,dedicated documentation section}.

All option names used in interpolation will be passed through the
@ref{2e34,,optionxform()} method just like any other option name reference.  For
example, using the default implementation of @ref{2e34,,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{2e2c,,"Unnamed Sections" section}.

It is possible to read several configurations into a single
@ref{4d9,,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 版的變更: 預設的 `dict_type' 是 @ref{7ec,,collections.OrderedDict}。



在 3.2 版的變更: `allow_no_value', `delimiters', `comment_prefixes', `strict',
`empty_lines_in_values', `default_section' and `interpolation' were
added.



在 3.5 版的變更: 新增 `converters' 引數。



在 3.7 版的變更: The `defaults' argument is read with @ref{2e2e,,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{183,,dict}, since it now preserves
insertion order.



在 3.13 版的變更: Raise a @ref{2e35,,MultilineContinuationError} when `allow_no_value' is
@code{True}, and a key without a value is continued with an indented line.



在 3.13 版的變更: 新增 `allow_unnamed_section' 引數。


@geindex defaults() (configparser.ConfigParser 的方法)
@anchor{library/configparser configparser ConfigParser defaults}@anchor{2e36}
@deffn {方法} defaults ()

Return a dictionary containing the instance-wide defaults.
@end deffn

@geindex sections() (configparser.ConfigParser 的方法)
@anchor{library/configparser configparser ConfigParser sections}@anchor{2e37}
@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{146e}
@deffn {方法} add_section (section)

Add a section named `section' to the instance.  If a section by the given
name already exists, @ref{146f,,DuplicateSectionError} is raised.  If the
`default section' name is passed, @ref{2eb,,ValueError} is raised.  The name
of the section must be a string; if not, @ref{198,,TypeError} is raised.


在 3.2 版的變更: Non-string section names raise @ref{198,,TypeError}.

@end deffn

@geindex has_section() (configparser.ConfigParser 的方法)
@anchor{library/configparser configparser ConfigParser has_section}@anchor{2e38}
@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{2e39}
@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{2e3a}
@deffn {方法} has_option (section, option)

If the given `section' exists, and contains the given `option', return
@ref{e02,,True}; otherwise return @ref{d23,,False}.  If the specified
`section' is @ref{87e,,None} or an empty string, DEFAULT is assumed.
@end deffn

@geindex read() (configparser.ConfigParser 的方法)
@anchor{library/configparser configparser ConfigParser read}@anchor{165d}
@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{192,,bytes} object or a
@ref{59b,,path-like object}, it is treated as
a single filename.  If a file named in `filenames' cannot be opened, that
file will be ignored.  This is designed so that you can specify an
iterable of potential configuration file locations (for example, the
current directory, the user's home directory, and some system-wide
directory), and all existing configuration files in the iterable will be
read.

If none of the named files exist, the @ref{4d9,,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{723,,read_file()} before calling @ref{165d,,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{315,,open()}.



在 3.6.1 版的變更: The `filenames' parameter accepts a @ref{59b,,path-like object}.



在 3.7 版的變更: The `filenames' parameter accepts a @ref{192,,bytes} object.

@end deffn

@geindex read_file() (configparser.ConfigParser 的方法)
@anchor{library/configparser configparser ConfigParser read_file}@anchor{723}
@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{'<???>'}.


在 3.2 版被加入: 取代 @code{readfp()}。

@end deffn

@geindex read_string() (configparser.ConfigParser 的方法)
@anchor{library/configparser configparser ConfigParser read_string}@anchor{2e2f}
@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.


在 3.2 版被加入.

@end deffn

@geindex read_dict() (configparser.ConfigParser 的方法)
@anchor{library/configparser configparser ConfigParser read_dict}@anchor{2e2e}
@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.


在 3.2 版被加入.

@end deffn

@geindex get() (configparser.ConfigParser 的方法)
@anchor{library/configparser configparser ConfigParser get}@anchor{146c}
@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{2e27}
@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{146c,,get()} for explanation of `raw', `vars' and
`fallback'.
@end deffn

@geindex getfloat() (configparser.ConfigParser 的方法)
@anchor{library/configparser configparser ConfigParser getfloat}@anchor{2e28}
@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{146c,,get()} for explanation of `raw',
`vars' and `fallback'.
@end deffn

@geindex getboolean() (configparser.ConfigParser 的方法)
@anchor{library/configparser configparser ConfigParser getboolean}@anchor{2e26}
@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{2eb,,ValueError}.  See @ref{146c,,get()} for explanation of `raw', `vars' and
`fallback'.
@end deffn

@geindex items() (configparser.ConfigParser 的方法)
@anchor{library/configparser configparser ConfigParser items}@anchor{2e3b}
@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{146c,,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{146d}
@deffn {方法} set (section, option, value)

If the given section exists, set the given option to the specified value;
otherwise raise @ref{2e3c,,NoSectionError}.  `option' and `value' must be
strings; if not, @ref{198,,TypeError} is raised.
@end deffn

@geindex write() (configparser.ConfigParser 的方法)
@anchor{library/configparser configparser ConfigParser write}@anchor{1de}
@deffn {方法} write (fileobject, space_around_delimiters=True)

Write a representation of the configuration to the specified @ref{13c4,,file object}, which must be opened in text mode (accepting strings).  This
representation can be parsed by a future @ref{165d,,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{165d,,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{2e3d}
@deffn {方法} remove_option (section, option)

Remove the specified `option' from the specified `section'.  If the
section does not exist, raise @ref{2e3c,,NoSectionError}.  If the option
existed to be removed, return @ref{e02,,True}; otherwise return
@ref{d23,,False}.
@end deffn

@geindex remove_section() (configparser.ConfigParser 的方法)
@anchor{library/configparser configparser ConfigParser remove_section}@anchor{2e3e}
@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{2e34}
@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 @ref{2e34,,optionxform()} is called.
@end deffn
@end deffn

@geindex UNNAMED_SECTION (於 configparser 模組中)
@anchor{library/configparser configparser UNNAMED_SECTION}@anchor{18a7}
@deffn {資料} configparser.UNNAMED_SECTION

A special object representing a section name used to reference the unnamed section (see @ref{2e2c,,Unnamed Sections}).
@end deffn

@geindex MAX_INTERPOLATION_DEPTH (於 configparser 模組中)
@anchor{library/configparser configparser MAX_INTERPOLATION_DEPTH}@anchor{2e3f}
@deffn {資料} configparser.MAX_INTERPOLATION_DEPTH

The maximum depth for recursive interpolation for @ref{146c,,get()} when the `raw'
parameter is false.  This is relevant only when the default `interpolation'
is used.
@end deffn

@node RawConfigParser 物件,例外<8>,ConfigParser 物件,configparser --- 設定檔剖析器
@anchor{library/configparser id15}@anchor{2e40}@anchor{library/configparser rawconfigparser-objects}@anchor{2e41}
@subsubsection RawConfigParser 物件


@geindex RawConfigParser (configparser 中的類別)
@anchor{library/configparser configparser RawConfigParser}@anchor{115f}
@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{4d9,,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 版的變更: 新增 `converters' 引數。



在 3.8 版的變更: The default `dict_type' is @ref{183,,dict}, since it now preserves
insertion order.



在 3.13 版的變更: 新增 `allow_unnamed_section' 引數。


@cartouche
@quotation 備註 
Consider using @ref{4d9,,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{2e42}
@deffn {方法} add_section (section)

Add a section named `section' or @ref{18a7,,UNNAMED_SECTION} to the instance.

If the given section already exists, @ref{146f,,DuplicateSectionError} is
raised. If the `default section' name is passed, @ref{2eb,,ValueError} is
raised. If @ref{18a7,,UNNAMED_SECTION} is passed and support is disabled,
@ref{2e43,,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 版的變更: 新增對 @ref{18a7,,UNNAMED_SECTION} 的支援。


@geindex set() (configparser.RawConfigParser 的方法)
@anchor{library/configparser configparser RawConfigParser set}@anchor{2e44}
@deffn {方法} set (section, option, value)

If the given section exists, set the given option to the specified value;
otherwise raise @ref{2e3c,,NoSectionError}.  While it is possible to use
@ref{115f,,RawConfigParser} (or @ref{4d9,,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 例外<8>,,RawConfigParser 物件,configparser --- 設定檔剖析器
@anchor{library/configparser exceptions}@anchor{2e45}
@subsubsection 例外


@geindex Error
@anchor{library/configparser configparser Error}@anchor{2e46}
@deffn {例外} configparser.Error

Base class for all other @ref{26,,configparser} exceptions.
@end deffn

@geindex NoSectionError
@anchor{library/configparser configparser NoSectionError}@anchor{2e3c}
@deffn {例外} configparser.NoSectionError

Exception raised when a specified section is not found.
@end deffn

@geindex DuplicateSectionError
@anchor{library/configparser configparser DuplicateSectionError}@anchor{146f}
@deffn {例外} configparser.DuplicateSectionError

Exception raised if @ref{146e,,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{1470}
@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{2e47}
@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{2e48}
@deffn {例外} configparser.InterpolationError

Base class for exceptions raised when problems occur performing string
interpolation.
@end deffn

@geindex InterpolationDepthError
@anchor{library/configparser configparser InterpolationDepthError}@anchor{2e49}
@deffn {例外} configparser.InterpolationDepthError

Exception raised when string interpolation cannot be completed because the
number of iterations exceeds @ref{2e3f,,MAX_INTERPOLATION_DEPTH}.  Subclass of
@ref{2e48,,InterpolationError}.
@end deffn

@geindex InterpolationMissingOptionError
@anchor{library/configparser configparser InterpolationMissingOptionError}@anchor{2e4a}
@deffn {例外} configparser.InterpolationMissingOptionError

Exception raised when an option referenced from a value does not exist.
Subclass of @ref{2e48,,InterpolationError}.
@end deffn

@geindex InterpolationSyntaxError
@anchor{library/configparser configparser InterpolationSyntaxError}@anchor{2e4b}
@deffn {例外} configparser.InterpolationSyntaxError

Exception raised when the source text into which substitutions are made does
not conform to the required syntax.  Subclass of @ref{2e48,,InterpolationError}.
@end deffn

@geindex MissingSectionHeaderError
@anchor{library/configparser configparser MissingSectionHeaderError}@anchor{2e4c}
@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{722}
@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{2e35}
@deffn {例外} configparser.MultilineContinuationError

Exception raised when a key without a corresponding value is continued with
an indented line.


在 3.13 版被加入.

@end deffn

@geindex UnnamedSectionDisabledError
@anchor{library/configparser configparser UnnamedSectionDisabledError}@anchor{2e43}
@deffn {例外} configparser.UnnamedSectionDisabledError

Exception raised when attempting to use the
@ref{18a7,,UNNAMED_SECTION} without enabling it.

@quotation


在 3.14 版被加入.

@end quotation
@end deffn

@geindex InvalidWriteError
@anchor{library/configparser configparser InvalidWriteError}@anchor{1df}
@deffn {例外} configparser.InvalidWriteError

Exception raised when an attempted @ref{1de,,ConfigParser.write()} would not be parsed
accurately with a future @ref{165d,,ConfigParser.read()} call.

Ex: Writing a key beginning with the @ref{2e2a,,ConfigParser.SECTCRE} pattern
would parse as a section header when read. Attempting to write this will raise
this exception.


在 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 --- 剖析 TOML 檔案,netrc --- netrc 檔案處理,configparser --- 設定檔剖析器,檔案格式
@anchor{library/tomllib doc}@anchor{2e4d}@anchor{library/tomllib module-tomllib}@anchor{102}@anchor{library/tomllib tomllib-parse-toml-files}@anchor{2e4e}@anchor{library/tomllib translation-repo}@anchor{2e4f}
@subsection @code{tomllib} --- 剖析 TOML 檔案


@geindex module; tomllib


在 3.11 版被加入.


`原始碼：'Lib/tomllib@footnote{https://github.com/python/cpython/tree/3.14/Lib/tomllib}


__________________________________________________________________


此模組提供了剖析 TOML 1.0.0 (Tom's Obvious Minimal Language, https://toml.io@footnote{https://toml.io/en/}) 的一個介面，此模組並不支援寫入 TOML。


@subsubheading 也參考


Tomli-W 套件@footnote{https://pypi.org/project/tomli-w/}是一個 TOML 編寫器，可以與此模組結合使用，以提供標準函式庫中 @ref{91,,marshal} 和 @ref{ab,,pickle} 模組之使用者所熟悉的寫入 API。



@subsubheading 也參考


TOML 工具套件@footnote{https://pypi.org/project/tomlkit/}是一個保留風格且具有讀寫能力的 TOML 函式庫。若要編輯已存在的 TOML 文件，建議用它來替換此模組。


此模組定義了以下函式：

@geindex load() (於 tomllib 模組中)
@anchor{library/tomllib tomllib load}@anchor{2e50}
@deffn {函式} tomllib.load (fp, /, *, parse_float=float)

讀取一個 TOML 檔案。第一個引數應為一個可讀取的二進位檔案物件。回傳一個 @ref{183,,dict}。用這個@ref{2e51,,轉換表}將 TOML 型別轉換成 Python 的。

`parse_float' 會被呼叫於要解碼的每個 TOML 浮點數字串。預設情況下，這相當於 @code{float(num_str)}。若有使用另一種資料型別或剖析器的 TOML 浮點數（例如 @ref{1fe,,decimal.Decimal}），這就派得上用場。可呼叫物件不得回傳 @ref{183,,dict} 或 @ref{24d,,list}，否則會引發 @ref{2eb,,ValueError}。

不合格的 TOML 文件會使得 @ref{1878,,TOMLDecodeError} 被引發。
@end deffn

@geindex loads() (於 tomllib 模組中)
@anchor{library/tomllib tomllib loads}@anchor{1892}
@deffn {函式} tomllib.loads (s, /, *, parse_float=float)

自一個 @ref{169,,str} 物件載入成 TOML。回傳一個 @ref{183,,dict}。用這個@ref{2e51,,轉換表}轉換 TOML 型別成 Python 的。`parse_float' 引數和 @ref{2e50,,load()} 中的相同。

不合格的 TOML 文件會使得 @ref{1878,,TOMLDecodeError} 被引發。
@end deffn

以下為可用的例外：

@geindex TOMLDecodeError
@anchor{library/tomllib tomllib TOMLDecodeError}@anchor{1878}
@deffn {例外} tomllib.TOMLDecodeError (msg, doc, pos)

Subclass of @ref{2eb,,ValueError} with the following additional attributes:

@geindex msg (tomllib.TOMLDecodeError 的屬性)
@anchor{library/tomllib tomllib TOMLDecodeError msg}@anchor{2e52}
@deffn {屬性} msg

The unformatted error message.
@end deffn

@geindex doc (tomllib.TOMLDecodeError 的屬性)
@anchor{library/tomllib tomllib TOMLDecodeError doc}@anchor{2e53}
@deffn {屬性} doc

The TOML document being parsed.
@end deffn

@geindex pos (tomllib.TOMLDecodeError 的屬性)
@anchor{library/tomllib tomllib TOMLDecodeError pos}@anchor{2e54}
@deffn {屬性} pos

The index of `doc' where parsing failed.
@end deffn

@geindex lineno (tomllib.TOMLDecodeError 的屬性)
@anchor{library/tomllib tomllib TOMLDecodeError lineno}@anchor{2e55}
@deffn {屬性} lineno

The line corresponding to `pos'.
@end deffn

@geindex colno (tomllib.TOMLDecodeError 的屬性)
@anchor{library/tomllib tomllib TOMLDecodeError colno}@anchor{2e56}
@deffn {屬性} colno

The column corresponding to `pos'.
@end deffn


在 3.14 版的變更: Added the `msg', `doc' and `pos' parameters.
Added the @ref{2e52,,msg}, @ref{2e53,,doc}, @ref{2e54,,pos}, @ref{2e55,,lineno} and @ref{2e56,,colno} attributes.



在 3.14 版之後被棄用: Passing free-form positional arguments is deprecated.

@end deffn

@menu
* 範例: 範例<17>. 
* 轉換表:: 

@end menu

@node 範例<17>,轉換表,,tomllib --- 剖析 TOML 檔案
@anchor{library/tomllib examples}@anchor{2e57}
@subsubsection 範例


剖析一個 TOML 檔案：

@example
import tomllib

with open("pyproject.toml", "rb") as f:
    data = tomllib.load(f)
@end example

剖析一個 TOML 字串：

@example
import tomllib

toml_str = """
python-version = "3.11.0"
python-implementation = "CPython"
"""

data = tomllib.loads(toml_str)
@end example

@node 轉換表,,範例<17>,tomllib --- 剖析 TOML 檔案
@anchor{library/tomllib conversion-table}@anchor{2e58}
@subsubsection 轉換表

@anchor{library/tomllib toml-to-py-table}@anchor{2e51}

@multitable {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

TOML

@tab

Python

@item

TOML 文件

@tab

dict

@item

string

@tab

str

@item

integer

@tab

int

@item

float

@tab

float（可透過 `parse_float' 調整）

@item

boolean

@tab

bool

@item

偏移日期時間 (offset date-time)

@tab

datetime.datetime（設定 @code{tzinfo} 屬性為 @code{datetime.timezone} 的實例）

@item

本地日期時間 (local date-time)

@tab

datetime.datetime（設定 @code{tzinfo} 為 @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

dict 串列 (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 檔案處理,plistlib --- 產生和剖析 Apple plist 檔案,tomllib --- 剖析 TOML 檔案,檔案格式
@anchor{library/netrc doc}@anchor{2e59}@anchor{library/netrc module-netrc}@anchor{9f}@anchor{library/netrc netrc-netrc-file-processing}@anchor{2e5a}@anchor{library/netrc translation-repo}@anchor{2e5b}
@subsection @code{netrc} --- netrc 檔案處理


@geindex module; netrc

`原始碼：'Lib/netrc.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/netrc.py}


__________________________________________________________________


@ref{1b77,,netrc} 類別能夠剖析 (parse) 並封裝 (encapsulate) netrc 檔案格式，以供 Unix @code{ftp} 程式和其他 FTP 用戶端使用。

@geindex netrc (netrc 中的類別)
@anchor{library/netrc netrc netrc}@anchor{1b77}
@deffn {類別} netrc.netrc ([file])

@ref{1b77,,netrc} 實例或其子類別實例能夠封裝來自 netrc 檔案的資料。可用初始化引數（如有給定）指定要剖析的檔案，如果未給定引數，則將讀取（由 @ref{c00,,os.path.expanduser()} 指定的）使用者主目錄中的 @code{.netrc} 檔案，否則將引發 @ref{264,,FileNotFoundError} 例外。剖析錯誤會引發 @ref{2e5c,,NetrcParseError}，其帶有包括檔案名稱、列號和終止 token 的診斷資訊。

如果在 POSIX 系統上未指定引數，且若檔案所有權或權限不安全（擁有者與運行該行程的使用者不同，或者可供任何其他使用者讀取或寫入），存有密碼的 @code{.netrc} 檔案將會引發 @ref{2e5c,,NetrcParseError}。這實作了與 ftp 和其他使用 @code{.netrc} 程式等效的安全行為。這種安全檢查在不支援 @ref{179a,,os.getuid()} 的平台上不可用。


在 3.4 版的變更: 新增了 POSIX 權限檢查。



在 3.7 版的變更: 當未傳遞 `file' 引數時，@ref{c00,,os.path.expanduser()} 可用於查找 @code{.netrc} 檔案的位置。



在 3.10 版的變更: @ref{9f,,netrc} 在使用特定語言環境編碼前會先嘗試 UTF-8 編碼。netrc 檔案中的條目就不再需要包含所有 token，缺少的 token 值被預設為空字串。現在所有 token 及其值都可以包含任意字元，例如空格和非 ASCII 字元。如果登入名稱為匿名，就不會觸發安全檢查。

@end deffn

@geindex NetrcParseError
@anchor{library/netrc netrc NetrcParseError}@anchor{2e5c}
@deffn {例外} netrc.NetrcParseError

當原始文本中遇到語法錯誤時，@ref{1b77,,netrc} 類別會引發例外。此例外的實例提供了三個有趣的屬性：

@geindex msg (netrc.NetrcParseError 的屬性)
@anchor{library/netrc netrc NetrcParseError msg}@anchor{2e5d}
@deffn {屬性} msg

錯誤的文字解釋。
@end deffn

@geindex filename (netrc.NetrcParseError 的屬性)
@anchor{library/netrc netrc NetrcParseError filename}@anchor{2e5e}
@deffn {屬性} filename

原始檔案的名稱。
@end deffn

@geindex lineno (netrc.NetrcParseError 的屬性)
@anchor{library/netrc netrc NetrcParseError lineno}@anchor{2e5f}
@deffn {屬性} lineno

發現錯誤的列號。
@end deffn
@end deffn

@menu
* netrc 物件:: 

@end menu

@node netrc 物件,,,netrc --- netrc 檔案處理
@anchor{library/netrc id1}@anchor{2e60}@anchor{library/netrc netrc-objects}@anchor{2e61}
@subsubsection netrc 物件


@ref{1b77,,netrc} 實例具有以下方法：

@geindex authenticators() (netrc.netrc 的方法)
@anchor{library/netrc netrc netrc authenticators}@anchor{2e62}
@deffn {方法} netrc.authenticators (host)

回傳 `host' 身份驗證器的三元素 tuple @code{(login, account, password)}。如果 netrc 檔案不包含給定主機的條目，則回傳與 'default' 條目關聯的 tuple。如果並無匹配主機且預設條目也不可用則回傳 @code{None}。
@end deffn

@geindex __repr__() (netrc.netrc 的方法)
@anchor{library/netrc netrc netrc __repr__}@anchor{2e63}
@deffn {方法} netrc.__repr__ ()

將類別資料傾印 (dump) 為 netrc 檔案格式的字串。（這會將註解移除，並可能會對條目重新排序。）
@end deffn

@ref{1b77,,netrc} 的實例具有公開實例變數：

@geindex hosts (netrc.netrc 的屬性)
@anchor{library/netrc netrc netrc hosts}@anchor{2e64}
@deffn {屬性} netrc.hosts

將主機名稱對映到 @code{(login, account, password)} tuple 的字典。'default' 條目（如存在）表示為該名稱對應到的偽主機 (pseudo-host)。
@end deffn

@geindex macros (netrc.netrc 的屬性)
@anchor{library/netrc netrc netrc macros}@anchor{2e65}
@deffn {屬性} netrc.macros

巨集 (macro) 名稱與字串 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 plistlib --- 產生和剖析 Apple plist 檔案,,netrc --- netrc 檔案處理,檔案格式
@anchor{library/plistlib doc}@anchor{2e66}@anchor{library/plistlib module-plistlib}@anchor{b0}@anchor{library/plistlib plistlib-generate-and-parse-apple-plist-files}@anchor{2e67}@anchor{library/plistlib translation-repo}@anchor{2e68}
@subsection @code{plistlib} --- 產生和剖析 Apple @code{.plist} 檔案


@geindex module; plistlib

@c (harvested from docstrings in the original file)

`原始碼：'Lib/plistlib.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/plistlib.py}

@geindex plist;file（檔案）
@geindex property list（屬性清單）


__________________________________________________________________


This module provides an interface for reading and writing the "property list"
files used by Apple, primarily on macOS and iOS. This module supports both binary
and XML plist files.

The property list (@code{.plist}) file format is a simple serialization supporting
basic object types, like dictionaries, lists, numbers and strings.  Usually the
top level object is a dictionary.

To write out and to parse a plist file, use the @ref{b41,,dump()} and
@ref{b3f,,load()} functions.

To work with plist data in bytes or string objects, use @ref{b42,,dumps()}
and @ref{b40,,loads()}.

Values can be strings, integers, floats, booleans, tuples, lists, dictionaries
(but only with string keys), @ref{192,,bytes}, @ref{343,,bytearray}
or @ref{4dd,,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{c0d,,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


此模組定義了以下函式：

@geindex load() (於 plistlib 模組中)
@anchor{library/plistlib plistlib load}@anchor{b3f}
@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{87e,,None}：自動偵測檔案格式

@item 
@ref{1174,,FMT_XML}：XML 檔案格式

@item 
@ref{1175,,FMT_BINARY}：二進位 plist 格式
@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{2746,,aware object}, with
@code{tzinfo} as @ref{70c,,datetime.UTC}.

XML data for the @ref{1174,,FMT_XML} format is parsed using the Expat parser
from @ref{12c,,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{1be4,,InvalidFileException} when the file cannot be parsed.


在 3.4 版被加入.



在 3.13 版的變更: 新增僅限關鍵字參數 `aware_datetime'。

@end deffn

@geindex loads() (於 plistlib 模組中)
@anchor{library/plistlib plistlib loads}@anchor{b40}
@deffn {函式} plistlib.loads (data, *, fmt=None, dict_type=dict, aware_datetime=False)

Load a plist from a bytes or string object. See @ref{b3f,,load()} for an
explanation of the keyword arguments.


在 3.4 版被加入.



在 3.13 版的變更: `data' 在 `fmt' 等於 @ref{1174,,FMT_XML} 時可以是一個字串。

@end deffn

@geindex dump() (於 plistlib 模組中)
@anchor{library/plistlib plistlib dump}@anchor{b41}
@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{1174,,FMT_XML}: XML formatted plist file

@item 
@ref{1175,,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{198,,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{2746,,aware object}, it will convert to
UTC timezone before writing it.

A @ref{198,,TypeError} will be raised if the object is of an unsupported type or
a container that contains objects of unsupported types.

An @ref{a78,,OverflowError} will be raised for integer values that cannot
be represented in (binary) plist files.


在 3.4 版被加入.



在 3.13 版的變更: 新增僅限關鍵字參數 `aware_datetime'。

@end deffn

@geindex dumps() (於 plistlib 模組中)
@anchor{library/plistlib plistlib dumps}@anchor{b42}
@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{b41,,dump()} for an explanation of the keyword
arguments of this function.


在 3.4 版被加入.

@end deffn

The following classes are available:

@geindex UID (plistlib 中的類別)
@anchor{library/plistlib plistlib UID}@anchor{c0d}
@deffn {類別} plistlib.UID (data)

Wraps an @ref{19b,,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{2e69}
@deffn {屬性} data

Int value of the UID.  It must be in the range @code{0 <= data < 2**64}.
@end deffn


在 3.8 版被加入.

@end deffn

以下常數可供使用：

@geindex FMT_XML (於 plistlib 模組中)
@anchor{library/plistlib plistlib FMT_XML}@anchor{1174}
@deffn {資料} plistlib.FMT_XML

The XML format for plist files.


在 3.4 版被加入.

@end deffn

@geindex FMT_BINARY (於 plistlib 模組中)
@anchor{library/plistlib plistlib FMT_BINARY}@anchor{1175}
@deffn {資料} plistlib.FMT_BINARY

The binary format for plist files


在 3.4 版被加入.

@end deffn

這個模組定義了以下例外：

@geindex InvalidFileException
@anchor{library/plistlib plistlib InvalidFileException}@anchor{1be4}
@deffn {例外} plistlib.InvalidFileException

當檔案無法被剖析時引發。


在 3.4 版被加入.

@end deffn

@menu
* 範例: 範例<18>. 

@end menu

@node 範例<18>,,,plistlib --- 產生和剖析 Apple plist 檔案
@anchor{library/plistlib examples}@anchor{2e6a}
@subsubsection 範例


Generating a plist:

@example
import datetime
import plistlib

pl = dict(
    aString = "Doodah",
    aList = ["A", "B", 12, 32.1, [1, 2, 3]],
    aFloat = 0.1,
    anInt = 728,
    aDict = dict(
        anotherString = "<hello & hi there!>",
        aThirdString = "M\xe4ssig, Ma\xdf",
        aTrueValue = True,
        aFalseValue = False,
    ),
    someData = b"<binary gunk>",
    someMoreData = b"<lots of binary gunk>" * 10,
    aDate = datetime.datetime.now()
)
print(plistlib.dumps(pl).decode())
@end example

Parsing a plist:

@example
import plistlib

plist = b"""<plist version="1.0">
<dict>
    <key>foo</key>
    <string>bar</string>
</dict>
</plist>"""
pl = plistlib.loads(plist)
print(pl["foo"])
@end example

@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 標準函式庫 Standard Library
@anchor{library/crypto doc}@anchor{2e6b}@anchor{library/crypto crypto}@anchor{2e6c}@anchor{library/crypto cryptographic-services}@anchor{2e6d}@anchor{library/crypto translation-repo}@anchor{2e6e}
@section 加密服務


@geindex cryptography（密碼學）

本章所描述的模組實作了多種加密演算法。它們可以在安裝時選擇是否一同安裝。以下為概述：

@menu
* hashlib: hashlib --- 安全雜湊與訊息摘要. 安全雜湊與訊息摘要
* hmac: hmac --- 基於金鑰雜湊的訊息驗證. 基於金鑰雜湊的訊息驗證
* secrets: secrets --- 產生用於管理機密的安全亂數. 產生用於管理機密的安全亂數

@end menu

@node hashlib --- 安全雜湊與訊息摘要,hmac --- 基於金鑰雜湊的訊息驗證,,加密服務
@anchor{library/hashlib doc}@anchor{2e6f}@anchor{library/hashlib hashlib-secure-hashes-and-message-digests}@anchor{2e70}@anchor{library/hashlib module-hashlib}@anchor{6c}
@subsection @code{hashlib} --- 安全雜湊與訊息摘要


@geindex module; hashlib

`原始碼：'Lib/hashlib.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/hashlib.py}

@geindex message digest（訊息摘要）、MD5
@geindex 安全雜湊演算法、SHA1、SHA2、SHA224、SHA256、SHA384、SHA512、SHA3、Shake、Blake2

@c import hashlib


__________________________________________________________________


該模組實作了許多不同雜湊演算法的通用介面，其中包括 FIPS 安全雜湊演算法 SHA1、SHA224、SHA256、SHA384、SHA512（定義於 FIPS 180-4 標準@footnote{https://csrc.nist.gov/pubs/fips/180-4/upd1/final}）、SHA-3 系列（定義於 FIPS 202 標準@footnote{https://csrc.nist.gov/pubs/fips/202/final}）以及遺留的 SHA1 演算法（先前為 FIPS 的一部分@footnote{https://csrc.nist.gov/news/2023/decision-to-revise-fips-180-4}）和 MD5 演算法（定義於網際網路 
@geindex RFC; RFC 1321
RFC 1321@footnote{https://datatracker.ietf.org/doc/html/rfc1321.html}）。

@cartouche
@quotation 備註 
如果你需要 adler32 或 crc32 雜湊函式，可以在 @ref{139,,zlib} 模組中找到它們。
@end quotation
@end cartouche

@menu
* 雜湊演算法:: 
* 用法:: 
* 建構函式:: 
* 屬性:: 
* 雜湊物件:: 
* SHAKE 可變長度摘要:: 
* 檔案雜湊:: 
* 密鑰的生成:: 
* BLAKE2:: 

@end menu

@node 雜湊演算法,用法,,hashlib --- 安全雜湊與訊息摘要
@anchor{library/hashlib hash-algorithms}@anchor{2e71}@anchor{library/hashlib id1}@anchor{2e72}
@subsubsection 雜湊演算法


每種種類的 `hash' 都有一個以其命名的建構函式方法。全部都會回傳具有相同簡單介面的雜湊物件。例如：可使用 @ref{1824,,sha256()} 來建立 SHA-256 雜湊物件。現在你可以使用 @ref{2e73,,update} 方法向此物件提供@ref{193,,類位元組物件 (bytes-like objects)}（通常是 @ref{192,,bytes}）。在任何時候，你都可以使用 @ref{2e74,,digest()} 或 @ref{2e75,,hexdigest()} 方法來要求它提供迄今為止傳遞給它的資料串聯的`摘要 (digest)'。

為了允許多執行緒 (multithreading)，Python @ref{164,,GIL} 被釋放，同時在其建構函式或 @ref{2e73,,.update} 方法中計算一次提供超過 2047 位元組資料的雜湊值。

@geindex OpenSSL;（使用於 hashlib 模組中）

此模組中始終存在的雜湊演算法之建構函式有 @ref{2e76,,sha1()}、@ref{2e77,,sha224()}、@ref{1824,,sha256()}、@ref{2e78,,sha384()}、@ref{2e79,,sha512()}、@ref{e9b,,sha3_224()}、@ref{e9c,,sha3_256()}、@ref{e9d,,sha3_384()}、@ref{e9e,,sha3_512()}、@ref{e9f,,shake_128()}、@ref{ea0,,shake_256()}、@ref{84b,,blake2b()} 和 @ref{84c,,blake2s()}。@ref{17a6,,md5()} 通常也可用，但如果你使用罕見的「符合 FIPS (FIPS compliant)」的 Python 建置版本，它可能不存在或者不被允許使用。以上會對應到 @ref{156b,,algorithms_guaranteed}。

如果你的 Python 發行版的 @ref{6c,,hashlib} 與提供其他演算法的 OpenSSL 版本鏈結，也可能有其他演算法可用。其他則`不保證可用'於在所有安裝上，並且只能以名稱來透過 @ref{1bfc,,new()} 存取。請參閱 @ref{156c,,algorithms_available}。

@cartouche
@quotation 警告 
某些演算法具有已知的雜湊碰撞 (hash collision) 弱點（包括 MD5 和 SHA1）。請參閱 Attacks on cryptographic hash algorithms@footnote{https://en.wikipedia.org/wiki/Cryptographic_hash_function#Attacks_on_cryptographic_hash_algorithms} 和本文件後面的@ref{2e7a,,也參考}部分。
@end quotation
@end cartouche


在 3.6 版被加入: 新增了 SHA3 (Keccak) 和 SHAKE 建構函式 @ref{e9b,,sha3_224()}、@ref{e9c,,sha3_256()}、@ref{e9d,,sha3_384()}、@ref{e9e,,sha3_512()}、@ref{e9f,,shake_128()}、@ref{ea0,,shake_256()}。也新增了 @ref{84b,,blake2b()} 和 @ref{84c,,blake2s()}。

@anchor{library/hashlib hashlib-usedforsecurity}@anchor{2e7b}

在 3.9 版的變更: 所有 hashlib 建構函式都採用一個僅限關鍵字引數 (keyword-only argument) `usedforsecurity'，其預設值為 @code{True}。False 值則會允許在受限環境中使用不安全 (insecure) 和阻塞的 (blocked) 雜湊演算法。@code{False} 表示雜湊演算法未在安全情境中使用，例如作為一種非加密用途的單向壓縮函式。



在 3.9 版的變更: Hashlib 現在使用 OpenSSL 中的 SHA3 和 SHAKE（如果有提供的話）。



在 3.12 版的變更: 對於鏈結之 OpenSSL 未提供的任何 MD5、SHA1、SHA2 或 SHA3 演算法，我們會回退使用 HACL* 專案@footnote{https://github.com/hacl-star/hacl-star}中經過驗證的實作。


@node 用法,建構函式,雜湊演算法,hashlib --- 安全雜湊與訊息摘要
@anchor{library/hashlib usage}@anchor{2e7c}
@subsubsection 用法


取得位元組字串 @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

更濃縮：

@example
>>> hashlib.sha256(b"Nobody inspects the spammish repetition").hexdigest()
'031edd7d41651593c5fe5c006fa5752b37fddff7bc4e843aa6af0c950f4b9406'
@end example

@node 建構函式,屬性,用法,hashlib --- 安全雜湊與訊息摘要
@anchor{library/hashlib constructors}@anchor{2e7d}
@subsubsection 建構函式


@geindex new() (於 hashlib 模組中)
@anchor{library/hashlib hashlib new}@anchor{1bfc}
@deffn {函式} hashlib.new (name[, data], *, usedforsecurity=True)

是一個通用建構函式，它將目標演算法的字串 `name' 作為其第一個參數。它還允許使用者取得上面列出的雜湊值以及 OpenSSL 函式庫可能提供的任何其他演算法。
@end deffn

使用 @ref{1bfc,,new()} 和演算法名稱：

@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{17a6}
@deffn {函式} hashlib.md5 ([data], *, usedforsecurity=True)
@end deffn

@geindex sha1() (於 hashlib 模組中)
@anchor{library/hashlib hashlib sha1}@anchor{2e76}
@deffn {函式} hashlib.sha1 ([data], *, usedforsecurity=True)
@end deffn

@geindex sha224() (於 hashlib 模組中)
@anchor{library/hashlib hashlib sha224}@anchor{2e77}
@deffn {函式} hashlib.sha224 ([data], *, usedforsecurity=True)
@end deffn

@geindex sha256() (於 hashlib 模組中)
@anchor{library/hashlib hashlib sha256}@anchor{1824}
@deffn {函式} hashlib.sha256 ([data], *, usedforsecurity=True)
@end deffn

@geindex sha384() (於 hashlib 模組中)
@anchor{library/hashlib hashlib sha384}@anchor{2e78}
@deffn {函式} hashlib.sha384 ([data], *, usedforsecurity=True)
@end deffn

@geindex sha512() (於 hashlib 模組中)
@anchor{library/hashlib hashlib sha512}@anchor{2e79}
@deffn {函式} hashlib.sha512 ([data], *, usedforsecurity=True)
@end deffn

@geindex sha3_224() (於 hashlib 模組中)
@anchor{library/hashlib hashlib sha3_224}@anchor{e9b}
@deffn {函式} hashlib.sha3_224 ([data], *, usedforsecurity=True)
@end deffn

@geindex sha3_256() (於 hashlib 模組中)
@anchor{library/hashlib hashlib sha3_256}@anchor{e9c}
@deffn {函式} hashlib.sha3_256 ([data], *, usedforsecurity=True)
@end deffn

@geindex sha3_384() (於 hashlib 模組中)
@anchor{library/hashlib hashlib sha3_384}@anchor{e9d}
@deffn {函式} hashlib.sha3_384 ([data], *, usedforsecurity=True)
@end deffn

@geindex sha3_512() (於 hashlib 模組中)
@anchor{library/hashlib hashlib sha3_512}@anchor{e9e}
@deffn {函式} hashlib.sha3_512 ([data], *, usedforsecurity=True)
@end deffn

諸如此類的附名建構函式比將演算法名稱傳遞給 @ref{1bfc,,new()} 更快。

@node 屬性,雜湊物件,建構函式,hashlib --- 安全雜湊與訊息摘要
@anchor{library/hashlib attributes}@anchor{2e7e}
@subsubsection 屬性


Hashlib 提供以下常數模組屬性：

@geindex algorithms_guaranteed (於 hashlib 模組中)
@anchor{library/hashlib hashlib algorithms_guaranteed}@anchor{156b}
@deffn {資料} hashlib.algorithms_guaranteed

包含所有平台上該模組保證支援的雜湊演算法名稱的集合。請注意，'md5' 有出現在此列表中，儘管有一些上游供應商提供了奇怪的「符合 FIPS (FIPS compliant)」的 Python 建置，並將其排除在外。


在 3.2 版被加入.

@end deffn

@geindex algorithms_available (於 hashlib 模組中)
@anchor{library/hashlib hashlib algorithms_available}@anchor{156c}
@deffn {資料} hashlib.algorithms_available

包含正在運行的 Python 直譯器中可用的雜湊演算法名稱的集合。這些名稱在傳遞給 @ref{1bfc,,new()} 時將被識別。@ref{156b,,algorithms_guaranteed} 都會是它的一個子集。相同的演算法可能會以不同的名稱多次出現在該集合中（多虧了 OpenSSL）。


在 3.2 版被加入.

@end deffn

@node 雜湊物件,SHAKE 可變長度摘要,屬性,hashlib --- 安全雜湊與訊息摘要
@anchor{library/hashlib hash-objects}@anchor{2e7f}
@subsubsection 雜湊物件


以下的值皆為建構函式回傳之雜湊物件的常數屬性：

@geindex hash.digest_size (於 hashlib 模組中)
@anchor{library/hashlib hashlib hash digest_size}@anchor{2e80}
@deffn {資料} hash.digest_size

生成雜湊的大小（以位元組為單位）。
@end deffn

@geindex hash.block_size (於 hashlib 模組中)
@anchor{library/hashlib hashlib hash block_size}@anchor{2e81}
@deffn {資料} hash.block_size

雜湊演算法的內部區塊大小（以位元組為單位）。
@end deffn

雜湊物件具有以下屬性：

@geindex name (hashlib.hash 的屬性)
@anchor{library/hashlib hashlib hash name}@anchor{1142}
@deffn {屬性} hash.name

該雜湊的規範名稱，都會是小寫，且都會適合作為 @ref{1bfc,,new()} 的參數以建立此型別的另一個雜湊。


在 3.4 版的變更: name 屬性自 CPython 誕生以來就存在於其中，但直到 Python 3.4 才正式確立，因此在某些平台上可能不存在。

@end deffn

雜湊物件具有以下方法：

@geindex update() (hashlib.hash 的方法)
@anchor{library/hashlib hashlib hash update}@anchor{2e73}
@deffn {方法} hash.update (data)

使用@ref{193,,類位元組物件}來更新雜湊物件。重複呼叫相當於連接所有引數的單一呼叫：@code{m.update(a); m.update(b)} 等價於 @code{m.update(a+b)}。
@end deffn

@geindex digest() (hashlib.hash 的方法)
@anchor{library/hashlib hashlib hash digest}@anchor{2e74}
@deffn {方法} hash.digest ()

回傳目前有傳遞給 @ref{2e73,,update()} 方法的資料之摘要。這是一個大小為 @ref{2e80,,digest_size} 的位元組物件，它可能包含從 0 到 255 的整個範圍內的位元組。
@end deffn

@geindex hexdigest() (hashlib.hash 的方法)
@anchor{library/hashlib hashlib hash hexdigest}@anchor{2e75}
@deffn {方法} hash.hexdigest ()

與 @ref{2e74,,digest()} 類似，只不過摘要會是作為雙倍長度的字串物件回傳，僅包含十六進位數字。這可用於在電子郵件或其他非二進位環境中安全地交換值。
@end deffn

@geindex copy() (hashlib.hash 的方法)
@anchor{library/hashlib hashlib hash copy}@anchor{2e82}
@deffn {方法} hash.copy ()

回傳雜湊物件的副本（「複製 (clone)」），這可用於高效率地計算出共享同一初始子字串的資料之摘要。
@end deffn

@node SHAKE 可變長度摘要,檔案雜湊,雜湊物件,hashlib --- 安全雜湊與訊息摘要
@anchor{library/hashlib shake-variable-length-digests}@anchor{2e83}
@subsubsection SHAKE 可變長度摘要


@geindex shake_128() (於 hashlib 模組中)
@anchor{library/hashlib hashlib shake_128}@anchor{e9f}
@deffn {函式} hashlib.shake_128 ([data], *, usedforsecurity=True)
@end deffn

@geindex shake_256() (於 hashlib 模組中)
@anchor{library/hashlib hashlib shake_256}@anchor{ea0}
@deffn {函式} hashlib.shake_256 ([data], *, usedforsecurity=True)
@end deffn

@ref{e9f,,shake_128()} 和 @ref{ea0,,shake_256()} 演算法提供了可變長度摘要，其 length_in_bits//2 最高為 128 或 256 位元安全性。因此，他們的摘要方法會需要長度。最大長度不受 SHAKE 演算法限制。

@geindex digest() (hashlib.shake 的方法)
@anchor{library/hashlib hashlib shake digest}@anchor{1ce2}
@deffn {方法} shake.digest (length)

回傳目前有傳遞給 @ref{2e73,,update()} 方法的資料之摘要。這是一個大小為 `length' 的位元組物件，可能包含從 0 到 255 的整個範圍內的位元組。
@end deffn

@geindex hexdigest() (hashlib.shake 的方法)
@anchor{library/hashlib hashlib shake hexdigest}@anchor{1ce3}
@deffn {方法} shake.hexdigest (length)

與 @ref{1ce2,,digest()} 類似，只不過摘要作為雙倍長度的字串物件回傳，僅包含十六進位數字。這可用於交換電子郵件或其他非二進位環境中的值。
@end deffn

範例：

@example
>>> h = hashlib.shake_256(b'Nobody inspects the spammish repetition')
>>> h.hexdigest(20)
'44709d6fcb83d92a76dcb0b668c98e1b1d3dafe7'
@end example

@node 檔案雜湊,密鑰的生成,SHAKE 可變長度摘要,hashlib --- 安全雜湊與訊息摘要
@anchor{library/hashlib file-hashing}@anchor{2e84}
@subsubsection 檔案雜湊


hashlib 模組提供了一個輔助函式，用於對檔案或類檔案物件 (file-like object) 進行有效率的雜湊。

@geindex file_digest() (於 hashlib 模組中)
@anchor{library/hashlib hashlib file_digest}@anchor{84d}
@deffn {函式} hashlib.file_digest (fileobj, digest, /)

回傳已用檔案物件內容更新的摘要物件。

`fileobj' 必須是以二進位模式讀取的類檔案物件。它接受來自內建 @ref{315,,open()} 的檔案物件、@ref{109f,,BytesIO} 實例、來自 @ref{13a0,,socket.socket.makefile()} 的 SocketIO 物件等。`fileobj' 必須以阻塞模式開啟，否則可能會引發 @ref{235,,BlockingIOError}。

該函式可以繞過 Python 的 I/O 並直接使用 @ref{2b7e,,fileno()} 中的檔案描述器 (file descriptor)。在此函式回傳或引發後，必須假定 `fileobj' 處於未知狀態 (unknown state)。由呼叫者決定是否關閉 `fileobj'。

`digest' 必須是名稱作為 `str' 的雜湊演算法、雜湊建構函式或會回傳雜湊物件的可呼叫函式。

範例：

@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


在 3.11 版被加入.



在 3.14 版的變更: Now raises a @ref{235,,BlockingIOError} if the file is opened in non-blocking
mode. Previously, spurious null bytes were added to the digest.

@end deffn

@node 密鑰的生成,BLAKE2,檔案雜湊,hashlib --- 安全雜湊與訊息摘要
@anchor{library/hashlib key-derivation}@anchor{2e85}
@subsubsection 密鑰的生成


密鑰生成 (key derivation) 和密鑰延伸 (key stretching) 演算法專為安全密碼雜湊而設計。像是 @code{sha1(password)} 這樣過於單純的演算法無法抵抗暴力攻擊。一個好的密碼雜湊函式必須是可調校的 (tunable)、緩慢的，並且有包含 salt（鹽）@footnote{https://zh.wikipedia.org/zh-tw/%E7%9B%90_(%E5%AF%86%E7%A0%81%E5%AD%A6)}。

@geindex pbkdf2_hmac() (於 hashlib 模組中)
@anchor{library/hashlib hashlib pbkdf2_hmac}@anchor{72c}
@deffn {函式} hashlib.pbkdf2_hmac (hash_name, password, salt, iterations, dklen=None)

該函式提供基於密碼的 PKCS#5 密鑰生成函式 2。它使用 HMAC 作為偽隨機函式 (pseudorandom function)。

字串 `hash_name' 是 HMAC 的雜湊摘要演算法所需的名稱，例如 @code{sha1} 或 @code{sha256}。`password' 和 `salt' 被直譯為位元組緩衝區。應用程式和函式庫應為 `password' 設下合理的長度限制（例如 1024）。`salt' 應該是來自適當來源（例如 @ref{73f,,os.urandom()}）且大約 16 或更多位元組。

應根據雜湊演算法和計算能力選擇 `iterations' 次數。截至 2022 年，建議進行數十萬次 SHA-256 疊代。有關為什麼以及如何選擇最適合你的應用程式的基本原理，請閱讀 NIST-SP-800-132@footnote{https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-132.pdf} 的 `Appendix A.2.2'。stackexchange pbkdf2 疊代問題@footnote{https://security.stackexchange.com/questions/3959/recommended-of-iterations-when-using-pbkdf2-sha256/}上的答案有詳細解釋。

`dklen' 是生成的密鑰長度。如果 `dklen' 為 @code{None}，則會使用雜湊演算法 `hash_name' 的摘要大小，例如 SHA-512 為 64。

@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

僅當有使用 OpenSSL 編譯 Python 時該函式才可用。


在 3.4 版被加入.



在 3.12 版的變更: 該函式現在僅在有使用 OpenSSL 建置 Python 時可用。緩慢的純 Python 實作已被刪除。

@end deffn

@geindex scrypt() (於 hashlib 模組中)
@anchor{library/hashlib hashlib scrypt}@anchor{e33}
@deffn {函式} hashlib.scrypt (password, *, salt, n, r, p, maxmem=0, dklen=64)

該函式提供（如 
@geindex RFC; RFC 7914
RFC 7914@footnote{https://datatracker.ietf.org/doc/html/rfc7914.html} 中所定義的）scrypt 基於密碼的密鑰衍生函式。

`password' 和 `salt' 必須是@ref{193,,類位元組物件}。應用程式和函式庫應為 `password' 設下合理的長度限制（例如 1024）。`salt' 應該是來自適當來源（例如 @ref{73f,,os.urandom()}）且大約 16 或更多位元組。

`n' 是 CPU/記憶體開銷係數、`r' 是區塊大小、`p' 為平行化係數、`maxmem' 為記憶體限制（OpenSSL 1.1.0 預設為 32 MiB）。`dklen' 是生成密鑰的長度。


在 3.6 版被加入.

@end deffn

@node BLAKE2,,密鑰的生成,hashlib --- 安全雜湊與訊息摘要
@anchor{library/hashlib blake2}@anchor{2e86}@anchor{library/hashlib hashlib-blake2}@anchor{201e}
@subsubsection BLAKE2


@geindex blake2b@comma{} blake2s

BLAKE2@footnote{https://www.blake2.net} 是在 
@geindex RFC; RFC 7693
RFC 7693@footnote{https://datatracker.ietf.org/doc/html/rfc7693.html} 中定義的加密雜湊函式，有兩種類型：


@itemize *

@item 
`BLAKE2b'，針對 64 位元平台進行了最佳化，可生成 1 到 64 位元組之間任意大小的摘要，

@item 
`BLAKE2s'，針對 8 至 32 位元平台進行了最佳化，可生成 1 至 32 位元組之間任意大小的摘要。
@end itemize

BLAKE2 支援`密鑰模式 (keyed mode)' （更快、更簡單的 HMAC@footnote{https://en.wikipedia.org/wiki/Hash-based_message_authentication_code} 替代品）、`加鹽雜湊 (salted hashing)'、`個人化'和`樹狀雜湊'。

該模組中的雜湊物件遵循標準函式庫的 @ref{6c,,hashlib} 物件 API。

@menu
* 建立雜湊物件:: 
* 常數: 常數<5>. 
* 範例: 範例<19>. 
* 製作人員:: 

@end menu

@node 建立雜湊物件,常數<5>,,BLAKE2
@anchor{library/hashlib creating-hash-objects}@anchor{2e87}
@subsubsection 建立雜湊物件


新的雜湊物件是透過呼叫建構函式建立的：

@geindex blake2b() (於 hashlib 模組中)
@anchor{library/hashlib hashlib blake2b}@anchor{84b}
@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{84c}
@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

這些函式回傳相應的雜湊物件以計算 BLAKE2b 或 BLAKE2s。他們可以選擇採用這些通用參數：


@itemize *

@item 
`data'：要雜湊的初始資料塊 (data chunk)，它必須是@ref{193,,類位元組物件}。它只能作為位置引數傳遞。

@item 
`digest_size'：輸出摘要的大小（以位元組為單位）。

@item 
`key'：用於密鑰雜湊的密鑰（BLAKE2b 最多 64 位元組、BLAKE2s 最多 32 位元組）。

@item 
`salt'：用於隨機雜湊的鹽（BLAKE2b 最多 16 個位元組、BLAKE2s 最多 8 個位元組）。

@item 
`person'：個人化字串（BLAKE2b 最多 16 個位元組、BLAKE2s 最多 8 個位元組）。
@end itemize

下表顯示了一般參數的限制（以位元組為單位）：


@multitable {xxxxxxxxx} {xxxxxxxxxxxxx} {xxxxxxxxxx} {xxxxxxxxxxx} {xxxxxxxxxxxxx} 
@headitem

雜湊

@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 規範定義了鹽和個人化參數的恆定長度，但為了方便起見，此實作接受任意大小的位元組字串，最多可達指定長度。如果參數的長度小於指定的長度，則用零補滿，所以像是 @code{b'salt} 和 @code{b'salt\x00} 是相同的值。（但 `key' 的情況並非如此。）
@end quotation
@end cartouche

這些大小可作為模組@ref{2e88,,常數}使用，如下所述。

建構函式還接受以下樹狀雜湊參數：


@itemize *

@item 
`fanout'：扇出（0 到 255，如果無限制則為 0、順序模式為 1）。

@item 
`depth'：樹的最大深度（1 到 255，如果無限制則為 255、順序模式為 1）。

@item 
`leaf_size'：葉的最大位元組長度（0 到 @code{2**32-1}，如果無限制或處於順序模式則為 0）。

@item 
`node_offset'：節點偏移量（BLAKE2b 為 0 到 @code{2**64-1}，BLAKE2s 為 0 到 @code{2**48-1}，0 表示第一個、最左邊、葉子或在順序模式下）。

@item 
`node_depth'：節點深度（0 到 255，葉為 0，或在順序模式下）。

@item 
`inner_size'：內部摘要大小（BLAKE2b 為 0 到 64，BLAKE2s 為 0 到 32，順序模式為 0）。

@item 
`last_node'：布林值，代表處理的節點是否為最後一個（@code{False} 代表順序模式）。
@end itemize


@float Figure

@image{python-figures/hashlib-blake2-tree,,,樹狀模式參數說明。,png}

@end float


關於樹狀雜湊的綜合回顧，請參閱 BLAKE2 規範@footnote{https://www.blake2.net/blake2_20130129.pdf}中的第 2.10 節。

@node 常數<5>,範例<19>,建立雜湊物件,BLAKE2
@anchor{library/hashlib constants}@anchor{2e88}
@subsubsection 常數


@geindex blake2b.SALT_SIZE (於 hashlib 模組中)
@anchor{library/hashlib hashlib blake2b SALT_SIZE}@anchor{2e89}
@deffn {資料} blake2b.SALT_SIZE
@end deffn

@geindex blake2s.SALT_SIZE (於 hashlib 模組中)
@anchor{library/hashlib hashlib blake2s SALT_SIZE}@anchor{2e8a}
@deffn {資料} blake2s.SALT_SIZE
@end deffn

鹽長度（建構函式接受的最大長度）。

@geindex blake2b.PERSON_SIZE (於 hashlib 模組中)
@anchor{library/hashlib hashlib blake2b PERSON_SIZE}@anchor{2e8b}
@deffn {資料} blake2b.PERSON_SIZE
@end deffn

@geindex blake2s.PERSON_SIZE (於 hashlib 模組中)
@anchor{library/hashlib hashlib blake2s PERSON_SIZE}@anchor{2e8c}
@deffn {資料} blake2s.PERSON_SIZE
@end deffn

個人化字串長度（建構函式接受的最大長度）。

@geindex blake2b.MAX_KEY_SIZE (於 hashlib 模組中)
@anchor{library/hashlib hashlib blake2b MAX_KEY_SIZE}@anchor{2e8d}
@deffn {資料} blake2b.MAX_KEY_SIZE
@end deffn

@geindex blake2s.MAX_KEY_SIZE (於 hashlib 模組中)
@anchor{library/hashlib hashlib blake2s MAX_KEY_SIZE}@anchor{2e8e}
@deffn {資料} blake2s.MAX_KEY_SIZE
@end deffn

最大密鑰大小。

@geindex blake2b.MAX_DIGEST_SIZE (於 hashlib 模組中)
@anchor{library/hashlib hashlib blake2b MAX_DIGEST_SIZE}@anchor{2e8f}
@deffn {資料} blake2b.MAX_DIGEST_SIZE
@end deffn

@geindex blake2s.MAX_DIGEST_SIZE (於 hashlib 模組中)
@anchor{library/hashlib hashlib blake2s MAX_DIGEST_SIZE}@anchor{2e90}
@deffn {資料} blake2s.MAX_DIGEST_SIZE
@end deffn

雜湊函式可以輸出的最大摘要大小。

@node 範例<19>,製作人員,常數<5>,BLAKE2
@anchor{library/hashlib examples}@anchor{2e91}
@subsubsection 範例


@menu
* 簡單雜湊:: 
* 使用不同的摘要大小:: 
* 密鑰雜湊 (Keyed hashing): 密鑰雜湊 Keyed hashing. 
* 隨機雜湊 (Randomized hashing): 隨機雜湊 Randomized hashing. 
* 個人化:: 
* 樹狀模式:: 

@end menu

@node 簡單雜湊,使用不同的摘要大小,,範例<19>
@anchor{library/hashlib simple-hashing}@anchor{2e92}
@subsubsection 簡單雜湊


要計算某些資料的雜湊值，你應該首先透過呼叫適當的建構函式（@ref{84b,,blake2b()} 或 @ref{84c,,blake2s()}）以建構一個雜湊物件，然後透過於物件呼叫 @ref{2e73,,update()} 來以資料對它更新，最後透過呼叫 @ref{2e74,,digest()}（或對於十六進位編碼字串則為 @ref{2e75,,hexdigest()}）從物件中獲得摘要。

@example
>>> from hashlib import blake2b
>>> h = blake2b()
>>> h.update(b'Hello world')
>>> h.hexdigest()
'6ff843ba685842aa82031d3f53c48b66326df7639a63d128974c5c14f31a0f33343a8c65551134ed1ae0f2b0dd2bb495dc81039e3eeb0aa1bb0388bbeac29183'
@end example

作為一個快捷方式，你可以將要更新的第一個資料塊作為位置引數直接傳遞給建構函式：

@example
>>> from hashlib import blake2b
>>> blake2b(b'Hello world').hexdigest()
'6ff843ba685842aa82031d3f53c48b66326df7639a63d128974c5c14f31a0f33343a8c65551134ed1ae0f2b0dd2bb495dc81039e3eeb0aa1bb0388bbeac29183'
@end example

你可以根據需求來多次呼叫 @ref{2e73,,hash.update()} 以疊代更新雜湊：

@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 使用不同的摘要大小,密鑰雜湊 Keyed hashing,簡單雜湊,範例<19>
@anchor{library/hashlib using-different-digest-sizes}@anchor{2e93}
@subsubsection 使用不同的摘要大小


BLAKE2 有可調整的摘要大小，BLAKE2b 最多為 64 位元組，BLAKE2s 最多為 32 位元組。例如，要在不改變輸出大小的情況下用 BLAKE2b 替換 SHA-1，我們可以指定 BLAKE2b 生成 20 位元組的摘要：

@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

具有不同摘要大小的雜湊物件具有完全不同的輸出（較短的雜湊值`不是'較長雜湊值的前綴）；即使輸出長度相同，BLAKE2b 和 BLAKE2s 也會產生不同的輸出：

@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,使用不同的摘要大小,範例<19>
@anchor{library/hashlib keyed-hashing}@anchor{2e94}
@subsubsection 密鑰雜湊 (Keyed hashing)


密鑰雜湊可用於身份驗證，作為基於雜湊的訊息驗證碼 (Hash-based message authentication code)@footnote{https://zh.wikipedia.org/zh-tw/HMAC} (HMAC) 的更快、更簡單的替代方案。由於繼承自 BLAKE 的不可微特性 (indifferentiability property)，BLAKE2 可以安全地用於 prefix-MAC 模式。

此範例示範了如何使用密鑰 @code{b'pseudorandom key'} 取得訊息 @code{b'message data'} 的（十六進位編碼）128 位元驗證碼：

@example
>>> from hashlib import blake2b
>>> h = blake2b(key=b'pseudorandom key', digest_size=16)
>>> h.update(b'message data')
>>> h.hexdigest()
'3d363ff7401e02026f4a4687d4863ced'
@end example

舉一個實際的例子，網頁應用程式可以對發送給使用者的 cookie 進行對稱簽名 (symmetrically sign)，然後驗證它們以確保它們沒有被篡改：

@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

儘管有原生密鑰雜湊模式，BLAKE2 還是可以透過 @ref{6e,,hmac} 模組用於建構 HMAC：

@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,個人化,密鑰雜湊 Keyed hashing,範例<19>
@anchor{library/hashlib randomized-hashing}@anchor{2e95}
@subsubsection 隨機雜湊 (Randomized hashing)


透過設定 `salt' 參數，使用者可以向雜湊函式引入隨機化。隨機雜湊在防止針對數位簽章中雜湊函式的碰撞攻擊 (collision attacks) 非常有用。

@quotation

隨機雜湊是為這樣的情況而設計的：一方（訊息準備者）生成全部或部分訊息並由另一方（訊息簽名者）簽名。如果訊息準備者能夠發現加密雜湊函式發生碰撞（collision，即兩條訊息產生相同的雜湊值），那麼他們可能會準備有意義的訊息版本，該版本將產生相同的雜湊值和數位簽章，但結果不同（例如，將 $1,000,000 轉入賬戶，而不是 $10）。加密雜湊函式的設計以抗碰撞性為主要目標，但目前對加密雜湊函式攻擊的關注可能會導致給定的加密雜湊函式所提供的抗碰撞性低於預期。隨機雜湊透過降低準備者在數位簽章生成過程中生成最終產生相同雜湊值的兩個或多個訊息的可能性，為簽名者提供額外的保護 —— 即便嘗試去找到雜湊函式碰撞的發生是實際可行的。然而，若訊息的所有部分都是由簽名者所準備好的，使用隨機雜湊可能會降低數位簽章提供的安全性。

（NIST SP-800-106 「數位簽章的隨機雜湊 (Randomized Hashing for Digital Signatures)」@footnote{https://csrc.nist.gov/pubs/sp/800/106/final}）
@end quotation

在 BLAKE2 中，鹽在初始化期間作為雜湊函式的一次性輸入被處理，而不是作為每個壓縮函式的輸入。

@cartouche
@quotation 警告 
使用 BLAKE2 或任何其他通用加密雜湊函式（例如 SHA-256）的`加鹽雜湊' （或單純雜湊）不適合對密碼進行雜湊處理。有關更多資訊，請參閱 BLAKE2 FAQ@footnote{https://www.blake2.net/#qa} 。
@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 個人化,樹狀模式,隨機雜湊 Randomized hashing,範例<19>
@anchor{library/hashlib personalization}@anchor{2e96}
@subsubsection 個人化


有時候強制雜湊函式為不同目的的相同輸入生成不同的摘要是很有用的。引用 Skein 雜湊函式的作者的話：

@quotation

我們建議所有應用程式設計者認真考慮這樣做；我們已經看到許多協定，其中在協定的一個部分中計算的雜湊可以在完全不同的部分中使用，因為兩次雜湊計算是在相似或相關的資料上完成的，並且攻擊者可以強制應用程式將雜湊輸入設為相同的。對協定中使用的每個雜湊函式進行個人化可以立即阻止此類攻擊。

（Skein 雜湊函式系列@footnote{https://www.schneier.com/wp-content/uploads/2016/02/skein.pdf}，第 21 頁）
@end quotation

BLAKE2 可以透過將位元組傳遞給 `person' 引數來做個人化：

@example
>>> from hashlib import blake2b
>>> FILES_HASH_PERSON = b'MyApp Files Hash'
>>> BLOCK_HASH_PERSON = b'MyApp Block Hash'
>>> h = blake2b(digest_size=32, person=FILES_HASH_PERSON)
>>> h.update(b'the same content')
>>> h.hexdigest()
'20d9cd024d4fb086aae819a1432dd2466de12947831b75c5a30cf2676095d3b4'
>>> h = blake2b(digest_size=32, person=BLOCK_HASH_PERSON)
>>> h.update(b'the same content')
>>> h.hexdigest()
'cf68fb5761b9c44e7878bfb2c4c9aea52264a80b75005e65619778de59f383a3'
@end example

個人化與密鑰模式還可以一起用於從單個密鑰得出不同的密鑰。

@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 樹狀模式,,個人化,範例<19>
@anchor{library/hashlib tree-mode}@anchor{2e97}
@subsubsection 樹狀模式


下面是對具有兩個葉節點的最小樹進行雜湊處理的範例：

@example
  10
 /  \
00  01
@end example

此範例使用 64-byte 內部摘要，並回傳 32-byte 最終摘要：

@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 製作人員,,範例<19>,BLAKE2
@anchor{library/hashlib credits}@anchor{2e98}
@subsubsection 製作人員


BLAKE2@footnote{https://www.blake2.net} 由 `Jean-Philippe Aumasson'、`Samuel Neves'、`Zooko Wilcox-O'Hearn' 和 `Christian Winnerlein' 設計，基於由 `Jean-Philippe Aumasson'、`Luca Henzen'、`Willi Meier' 和 `Raphael C.-W. Phan' 所建立的 SHA-3@footnote{https://en.wikipedia.org/wiki/Secure_Hash_Algorithms} 最終版本 BLAKE@footnote{https://web.archive.org/web/20200918190133/https://131002.net/blake/}。

它使用 `Daniel J. Bernstein' 設計的 ChaCha@footnote{https://cr.yp.to/chacha.html} 密碼的核心演算法。

標準函式庫實作是基於 pyblake2@footnote{https://pythonhosted.org/pyblake2/} 模組。它是由 `Dmitry Chestnykh' 在 `Samuel Neves' 的 C 版本實作為基礎所編寫的。該文件是由 `Dmitry Chestnykh' 編寫並從 pyblake2@footnote{https://pythonhosted.org/pyblake2/} 複製過來的。

`Christian Heimes' 為 Python 重寫了部分 C 程式碼。

以下公開領域貢獻適用於 C 雜湊函式實作、擴充程式碼和此文件：

@quotation

在法律允許的範圍內，作者已將該軟體的所有版權以及相關和鄰接權利奉獻給全球的公開領域。該軟體的發布沒有任何授權 (warranty)。

你應會隨本軟體一起收到一份 CC0 公眾領域貢獻宣告 (CC0 Public Domain Dedication) 的副本。如果沒有，請參閱 @indicateurl{https://creativecommons.org/publicdomain/zero/1.0/} 。
@end quotation

以下人員根據創用 CC 通用公眾領域貢獻宣告 1.0 (Creative Commons Public Domain Dedication 1.0 Universal) 於專案和公開領域做出了開發或貢獻：


@itemize *

@item 
`Alexandr Sokolovskiy'
@end itemize
@anchor{library/hashlib hashlib-seealso}@anchor{2e7a}

@subsubheading 也參考



@table @asis

@item @ref{6e,,hmac} 模組

使用雜湊生成訊息驗證程式碼的模組。

@item @ref{f,,base64} 模組

另一種在非二進位環境中編碼二進位雜湊的方法。

@item @indicateurl{https://nvlpubs.nist.gov/nistpubs/fips/nist.fips.180-4.pdf}

有關安全雜湊演算法的 FIPS 180-4 出版物。

@item @indicateurl{https://csrc.nist.gov/pubs/fips/202/final}

有關 SHA-3 標準的 FIPS 202 出版物。

@item @indicateurl{https://www.blake2.net/}

BLAKE2 官方網站。

@item @indicateurl{https://en.wikipedia.org/wiki/Cryptographic_hash_function}

包含有關哪些演算法存在已知問題以及這些問題對其使用意味著什麼資訊的維基百科文章。

@item @indicateurl{https://www.ietf.org/rfc/rfc8018.txt}

PKCS #5：基於密碼的加密規範版本 2.1

@item @indicateurl{https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-132.pdf}

NIST（美國國家標準技術研究院）針對基於密碼的密鑰衍生的建議。
@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 --- 基於金鑰雜湊的訊息驗證,secrets --- 產生用於管理機密的安全亂數,hashlib --- 安全雜湊與訊息摘要,加密服務
@anchor{library/hmac doc}@anchor{2e99}@anchor{library/hmac hmac-keyed-hashing-for-message-authentication}@anchor{2e9a}@anchor{library/hmac module-hmac}@anchor{6e}@anchor{library/hmac translation-repo}@anchor{2e9b}
@subsection @code{hmac} --- 基於金鑰雜湊的訊息驗證


@geindex module; hmac

`原始碼：'Lib/hmac.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/hmac.py}


__________________________________________________________________


此模組實作了 
@geindex RFC; RFC 2014
RFC 2014@footnote{https://datatracker.ietf.org/doc/html/rfc2014.html} 所描述的 HMAC 演算法。此介面允許使用具有`固定'摘要 (digest) 長度的任意雜湊函式。要特別注意的是擴充輸出函式（如 SHAKE-128 或 SHAKE-256）不能與 HMAC 一起使用。

@geindex new() (於 hmac 模組中)
@anchor{library/hmac hmac new}@anchor{c8d}
@deffn {函式} hmac.new (key, msg=None, digestmod)

回傳一個新的 hmac 物件。`key' 是一個指定密鑰的 bytes（位元組）或 bytearray 物件。如果提供了 `msg'，將會呼叫 @code{update(msg)} 方法。`digestmod' 為 HMAC 物件所用的摘要名稱、摘要建構函式 (constructor) 或模組。它可以是適用於 @ref{1bfc,,hashlib.new()} 的任何名稱。儘管該引數的位置在後，但它卻是必須的。


在 3.4 版的變更: 參數 `key' 可以為 bytes 或 bytearray 物件。參數 `msg' 可以為 @ref{6c,,hashlib} 所支援的任意型別。參數 `digestmod' 可以為雜湊演算法的名稱。



在 3.8 版的變更: `digestmod' 引數現在是必須的。請將其作為關鍵字引數傳入以避免當你沒有初始 `msg' 時導致的麻煩。

@end deffn

@geindex digest() (於 hmac 模組中)
@anchor{library/hmac hmac digest}@anchor{d2a}
@deffn {函式} hmac.digest (key, msg, digest)

基於給定密鑰 `key' 和 `digest' 回傳 `msg' 的摘要。此函式等價於 @code{HMAC(key, msg, digest).digest()}，但使用了優化的 C 或 行內實作（inline implementation），對放入記憶體的訊息能處理得更快。參數 `key'、`msg' 和 `digest' 在 @ref{c8d,,new()} 中具有相同含義。

作為 CPython 的實現細節，C 的優化實作只有當 `digest' 為字串並且是一個 OpenSSL 所支持的摘要演算法的名稱時才會被使用。


在 3.7 版被加入.

@end deffn

@geindex HMAC (hmac 中的類別)
@anchor{library/hmac hmac HMAC}@anchor{d2b}
@deffn {類別} hmac.HMAC

HMAC 物件具有下列方法 (method)：
@end deffn

@geindex update() (hmac.HMAC 的方法)
@anchor{library/hmac hmac HMAC update}@anchor{1144}
@deffn {方法} HMAC.update (msg)

用 `msg' 來更新 hmac 物件。重複呼叫相當於單次呼叫並傳入所有引數的拼接結果：@code{m.update(a); m.update(b)} 等價於 @code{m.update(a + b)}。


在 3.4 版的變更: 參數 `msg' 可以是 @ref{6c,,hashlib} 所支援的任何型別。

@end deffn

@geindex digest() (hmac.HMAC 的方法)
@anchor{library/hmac hmac HMAC digest}@anchor{2e9c}
@deffn {方法} HMAC.digest ()

回傳目前已傳給 @ref{1144,,update()} 方法的 bytes 摘要。這個 bytes 物件的長度會與傳給建構函式的摘要 `digest_size' 的長度相同。它可以包含 NUL bytes 以及 non-ASCII bytes。

@cartouche
@quotation 警告 
在一個例行的驗證事務運行期間，將 @ref{d2a,,digest()} 的輸出與外部提供的摘要進行比較時，建議使用 @ref{12ca,,compare_digest()} 函式而不是 @code{==} 運算子以減少被定時攻擊時的漏洞。
@end quotation
@end cartouche
@end deffn

@geindex hexdigest() (hmac.HMAC 的方法)
@anchor{library/hmac hmac HMAC hexdigest}@anchor{2e9d}
@deffn {方法} HMAC.hexdigest ()

像是 @ref{d2a,,digest()} 但摘要的回傳形式為兩倍長度的字串，且此字串只包含十六進位數位。這可以被用於在電子郵件或其他非二進位制環境中安全地交換數據。

@cartouche
@quotation 警告 
在一個例行的驗證事務運行期間，將 @ref{2e9d,,hexdigest()} 的輸出與外部提供的摘要進行比較時，建議使用 @ref{12ca,,compare_digest()} 函式而不是 @code{==} 運算子以減少被定時攻擊時的漏洞。
@end quotation
@end cartouche
@end deffn

@geindex copy() (hmac.HMAC 的方法)
@anchor{library/hmac hmac HMAC copy}@anchor{2e9e}
@deffn {方法} HMAC.copy ()

回傳 hmac 物件的拷貝 ("clone")。這可以被用來有效率地計算那些共享相同初始子字串的字串的摘要。
@end deffn

一個 hash 物件具有以下屬性：

@geindex digest_size (hmac.HMAC 的屬性)
@anchor{library/hmac hmac HMAC digest_size}@anchor{1147}
@deffn {屬性} HMAC.digest_size

以 bytes 表示最終 HMAC 摘要的大小。
@end deffn

@geindex block_size (hmac.HMAC 的屬性)
@anchor{library/hmac hmac HMAC block_size}@anchor{1145}
@deffn {屬性} HMAC.block_size

以 bytes 表示雜湊演算法的內部區塊大小。


在 3.4 版被加入.

@end deffn

@geindex name (hmac.HMAC 的屬性)
@anchor{library/hmac hmac HMAC name}@anchor{1146}
@deffn {屬性} HMAC.name

HMAC 的正準名稱總是為小寫形式，例如 @code{hmac-md5}。


在 3.4 版被加入.

@end deffn


在 3.10 版的變更: 未寫入文件的屬性 @code{HMAC.digest_cons}，@code{HMAC.inner} 和 @code{HMAC.outer} 已被移除。


這個模組還提供了下列輔助函式：

@geindex compare_digest() (於 hmac 模組中)
@anchor{library/hmac hmac compare_digest}@anchor{12ca}
@deffn {函式} hmac.compare_digest (a, b)

回傳 @code{a == b}。此函式使用一種經專門設計的方式通過避免基於內容的短路行為來防止定時分析，使得它適合處理密碼學。`a' 和 `b' 必須為相同的型別：可以是 @ref{169,,str}（僅限 ASCII，如 @ref{2e9d,,HMAC.hexdigest()} 的回傳值），或者是 @ref{193,,bytes-like object}。

@cartouche
@quotation 備註 
如果 `a' 和 `b' 具有不同的長度，或者如果發生了錯誤，定時攻擊在理論上可以取得有關 `a' 和 `b' 的型別和長度的訊息 — 但不能取得他們的值。
@end quotation
@end cartouche


在 3.3 版被加入.



在 3.10 版的變更: 此函式在可能的情況下會在內部使用 OpenSSL 的 @code{CRYPTO_memcmp()}。

@end deffn


@subsubheading 也參考



@table @asis

@item @ref{6c,,hashlib} 模組

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 secrets --- 產生用於管理機密的安全亂數,,hmac --- 基於金鑰雜湊的訊息驗證,加密服務
@anchor{library/secrets doc}@anchor{2e9f}@anchor{library/secrets module-secrets}@anchor{c5}@anchor{library/secrets secrets-generate-secure-random-numbers-for-managing-secrets}@anchor{2ea0}@anchor{library/secrets translation-repo}@anchor{2ea1}
@subsection @code{secrets} --- 產生用於管理機密的安全亂數


@geindex module; secrets


在 3.6 版被加入.


@c from secrets import *
@c __name__ = '<doctest>'

`原始碼：'Lib/secrets.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/secrets.py}


__________________________________________________________________


@ref{c5,,secrets} 模組可用於產生高加密強度的亂數，適合用來管理諸如密碼、帳號認證、安全性權杖（security tokens）這類資料，以及管理其他相關的機密資料。

尤其應優先使用 @ref{c5,,secrets} 作為預設來替代 @ref{bd,,random} 模組中的預設偽亂數產生器（pseudo-random number generator），該模組被設計用於建模和模擬，而非用於安全性和加密。


@subsubheading 也參考


@geindex Python Enhancement Proposals; PEP 506
PEP 506@footnote{https://peps.python.org/pep-0506/}


@menu
* 亂數:: 
* 產生權杖（token）:: 
* 其他函式:: 
* 應用技巧和典範實務（best practices）:: 

@end menu

@node 亂數,產生權杖（token）,,secrets --- 產生用於管理機密的安全亂數
@anchor{library/secrets random-numbers}@anchor{2ea2}
@subsubsection 亂數


@ref{c5,,secrets} 模組使你得以存取作業系統所提供安全性最高的亂數產生器。

@geindex SystemRandom (secrets 中的類別)
@anchor{library/secrets secrets SystemRandom}@anchor{2ea3}
@deffn {類別} secrets.SystemRandom

一個用來產生亂數的類別，用的是作業系統提供的最高品質來源。 請參閱 @ref{2a08,,random.SystemRandom} 以取得更多細節。
@end deffn

@geindex choice() (於 secrets 模組中)
@anchor{library/secrets secrets choice}@anchor{2ea4}
@deffn {函式} secrets.choice (seq)

從一非空序列中，回傳一個隨機選取的元素。
@end deffn

@geindex randbelow() (於 secrets 模組中)
@anchor{library/secrets secrets randbelow}@anchor{2ea5}
@deffn {函式} secrets.randbelow (exclusive_upper_bound)

回傳一個 [0, `exclusive_upper_bound') 範圍之內的隨機整數。
@end deffn

@geindex randbits() (於 secrets 模組中)
@anchor{library/secrets secrets randbits}@anchor{2ea6}
@deffn {函式} secrets.randbits (k)

回傳一個具 `k' 個隨機位元的非負整數。
@end deffn

@node 產生權杖（token）,其他函式,亂數,secrets --- 產生用於管理機密的安全亂數
@anchor{library/secrets generating-tokens}@anchor{2ea7}
@subsubsection 產生權杖（token）


@ref{c5,,secrets} 模組提供了一些產生安全性權杖的函式，適合用於諸如重設密碼、難以猜測的 URL，或類似的應用。

@geindex token_bytes() (於 secrets 模組中)
@anchor{library/secrets secrets token_bytes}@anchor{2a0d}
@deffn {函式} secrets.token_bytes ([nbytes=None])

回傳一個隨機位元組字串，其中含有 `nbytes' 位元組的數字。 如果 `nbytes' 為 @code{None} 或未提供，則會使用一合理預設值。

@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{1a67}
@deffn {函式} secrets.token_hex ([nbytes=None])

回傳一以十六進位表示的隨機字串。 字串具有 `nbytes' 個隨機位元組，每個位元組會轉成兩個十六進位的數字。 如果 `nbytes' 為 @code{None} 或未提供，則會使用一個合理的預設值。

@example
>>> token_hex(16)
'f9bf78b9a18ce6d46a0cd2b0b86df9da'
@end example
@end deffn

@geindex token_urlsafe() (於 secrets 模組中)
@anchor{library/secrets secrets token_urlsafe}@anchor{2ea8}
@deffn {函式} secrets.token_urlsafe ([nbytes=None])

回傳一個 URL 安全的隨機文本字串，包含 `nbytes' 個隨機位元組。 文本將使用 Base64 編碼，因此平均來說每個位元組會對應到約 1.3 個字元。 如果 `nbytes' 為 @code{None} 或未提供，則會使用一個合理的預設值。

@example
>>> token_urlsafe(16)
'Drmhze6EPcv0fN_81Bj-nA'
@end example
@end deffn

@menu
* 權杖應當使用多少個位元組？:: 

@end menu

@node 權杖應當使用多少個位元組？,,,產生權杖（token）
@anchor{library/secrets how-many-bytes-should-tokens-use}@anchor{2ea9}
@subsubsection 權杖應當使用多少個位元組？


為了在面對暴力攻擊@footnote{https://en.wikipedia.org/wiki/Brute-force_attack}時能保證安全，權杖必須具有足夠的隨機性。 不幸的是，對隨機性是否足夠的標準，會隨著電腦越來越強大並能夠在更短時間內進行更多猜測而不斷提高。 在 2015 年時，人們認為 32 位元組（256 位元）的隨機性對於 @ref{c5,,secrets} 模組所預期的一般使用場景來說是足夠的。

對於想自行管理權杖長度的使用者，你可以對各種 @code{token_*} 函式明白地指定 @ref{19b,,int} 引數（argument）來指定權杖要使用的隨機性程度。 該引數以位元組數來表示要使用的隨機性程度。

否則，如未提供引數，或者如果引數為 @code{None}，則 @code{token_*} 函式則會使用一個合理的預設值。

@cartouche
@quotation 備註 
該預設值可能在任何時候被改變，包括在維護版本更新的時候。
@end quotation
@end cartouche

@node 其他函式,應用技巧和典範實務（best practices）,產生權杖（token）,secrets --- 產生用於管理機密的安全亂數
@anchor{library/secrets other-functions}@anchor{2eaa}
@subsubsection 其他函式


@geindex compare_digest() (於 secrets 模組中)
@anchor{library/secrets secrets compare_digest}@anchor{2eab}
@deffn {函式} secrets.compare_digest (a, b)

如果字串或@ref{193,,類位元組串物件} `a' 與 `b' 相等則回傳 @code{True}，否則回傳 @code{False}，以"恆定時間比較 (constant-time compare) "的處理方式可降低時序攻擊@footnote{https://codahale.com/a-lesson-in-timing-attacks/}的風險。 請參閱 @ref{12ca,,hmac.compare_digest()} 以了解更多細節。
@end deffn

@node 應用技巧和典範實務（best practices）,,其他函式,secrets --- 產生用於管理機密的安全亂數
@anchor{library/secrets recipes-and-best-practices}@anchor{2eac}
@subsubsection 應用技巧和典範實務（best practices）


本節展示了一些使用 @ref{c5,,secrets} 來管理基本安全等級的應用技巧和典範實務。

產生八個字元長的字母數字密碼：

@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 備註 
應用程式不能
@geindex Common Weakness Enumeration; CWE 257
以可復原的格式儲存密碼@footnote{https://cwe.mitre.org/data/definitions/257.html}，無論是用純文本還是經過加密。 它們應當先加鹽（salt），再使用高加密強度的單向（不可逆）雜湊函式來產生雜湊值。
@end quotation
@end cartouche

產生十個字元長的字母數字密碼，其中包含至少一個小寫字母，至少一個大寫字母以及至少三個數字:

@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

產生 XKCD 風格的 passphrase@footnote{https://xkcd.com/936/}:

@example
import secrets
# 在標準 Linux 系統上，使用一個方便的字典檔案。
# 其他平台可能需要提供自己的字詞列表。
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

產生難以猜測的暫時性 URL，內含回復密碼時所用的一個安全性權杖：

@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 通用作業系統服務,命令列介面函式庫,加密服務,Python 標準函式庫 Standard Library
@anchor{library/allos doc}@anchor{2ead}@anchor{library/allos allos}@anchor{2eae}@anchor{library/allos generic-operating-system-services}@anchor{2eaf}@anchor{library/allos translation-repo}@anchor{2eb0}
@section 通用作業系統服務


此章節所描述的模組 (module) 提供了作業系統特性的使用介面，例如檔案與時鐘，（幾乎）在所有作業系統上皆能使用。這些介面通常是參考 Unix 或 C 的介面來實作，不過在其他大多數系統上也能使用。以下為概述：

@menu
* os: os --- 各種作業系統介面. 各種作業系統介面
* io — 處理資料串流的核心工具:: 
* time: time --- 時間存取與轉換. 時間存取與轉換
* logging: logging --- Python 的日誌記錄工具. Python 的日誌記錄工具
* logging.config: logging config --- 日誌記錄配置. 日誌記錄配置
* logging.handlers: logging handlers --- 日誌紀錄處理器. 日誌紀錄處理器
* platform: platform --- 對底層平臺識別資料的存取. 對底層平臺識別資料的存取
* errno: errno --- 標準 errno 系統符號. 標準 errno 系統符號
* ctypes: ctypes --- 用於 Python 的外部函式庫. 用於 Python 的外部函式庫

@end menu

@node os --- 各種作業系統介面,io — 處理資料串流的核心工具,,通用作業系統服務
@anchor{library/os doc}@anchor{2eb1}@anchor{library/os module-os}@anchor{a5}@anchor{library/os os-miscellaneous-operating-system-interfaces}@anchor{2eb2}
@subsection @code{os} --- 各種作業系統介面


@geindex module; os

`原始碼：'Lib/os.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/os.py}


__________________________________________________________________


該模組提供了一種便利的方式來操作與作業系統相關的功能。如果你想讀取或寫入檔案，請參閱 @ref{315,,open()} ，如果你想操作檔案路徑，請參閱 @ref{a6,,os.path} 模組，如果你想透過命令列查看所有檔案中的所有內容，請查看 @ref{5f,,fileinput} 模組。要建立臨時檔案和目錄，請參閱 @ref{e6,,tempfile} 模組，要操作高級檔案和目錄，請參閱 @ref{ca,,shutil} 模組。

關於這些功能的可用性說明：


@itemize *

@item 
Python 所有內建作業系統相關的模組設計是這樣：只要有相同的函式可使用，就會使用相同的介面 （interface）。舉例來說，@code{os.stat(path)} 函式會以相同格式回傳關於 `path' 的統計資訊（這剛好來自於 POSIX 的介面。）。

@item 
對於特定的作業系統獨有的擴充功能也可以透過 @ref{a5,,os} 取得，但使用它們的時候對於可移植性無疑會是個問題。

@item 
所有接受檔案路徑和檔案名稱的函式皆接受位元組 (bytes) 和字串物件 (string objects)，且如果回傳檔案路徑或檔案名稱，則會產出相同型別的物件。

@item 
在 VxWorks, 不支援 os.popen、os.fork、os.execv 和 os.spawn*p*。

@item 
在 WebAssembly 平台和 Android 與 iOS 上，大部分 @ref{a5,,os} 模組無法使用或行為不同。與行程 (process)（例如 @ref{4b0,,fork()}、@ref{12fa,,execve()}）與資源（例如 @ref{1302,,nice()}）相關的 API 不可使用。其他諸如 @ref{179a,,getuid()} 和 @ref{2eb3,,getpid()} 的相關 API 是 emulated 或 stubs。WebAssembly 平台也缺少訊號相關支援（例如 @ref{155f,,kill()}、@ref{f93,,wait()}）。
@end itemize

@cartouche
@quotation 備註 
在檔案名稱和路徑找不到或無效的時候，或引數型別正確但作業系統不接受的時候，在此模組中的所有的函式都會引發 @ref{2c0,,OSError}（或其子類別）。
@end quotation
@end cartouche

@geindex error
@anchor{library/os os error}@anchor{2eb4}
@deffn {例外} os.error

內建例外 @ref{2c0,,OSError} 的別名。
@end deffn

@geindex name (於 os 模組中)
@anchor{library/os os name}@anchor{2eb5}
@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{291,,sys.platform} has a finer granularity.  @ref{1317,,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{2df7}
@menu
* File Names@comma{} Command Line Arguments@comma{} and Environment Variables: File Names Command Line Arguments and Environment Variables. 
* Python UTF-8 模式:: 
* 行程參數:: 
* File Object Creation:: 
* File Descriptor Operations:: 
* Files and Directories:: 
* 行程管理:: 
* 排程器介面:: 
* Miscellaneous System Information:: 
* Random numbers:: 

@end menu

@node File Names Command Line Arguments and Environment Variables,Python UTF-8 模式,,os --- 各種作業系統介面
@anchor{library/os file-names-command-line-arguments-and-environment-variables}@anchor{2eb6}@anchor{library/os filesystem-encoding}@anchor{2ae7}
@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{756,,filesystem encoding and error handler} to perform this
conversion (see @ref{e4e,,sys.getfilesystemencoding()}).

The @ref{756,,filesystem encoding and error handler} are configured at Python
startup by the @ref{98b,,PyConfig_Read()} function: see
@ref{419,,filesystem_encoding} and
@ref{41a,,filesystem_errors} members of @ref{3f4,,PyConfig}.


在 3.1 版的變更: On some systems, conversion using the file system encoding may fail. In this
case, Python uses the @ref{2700,,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{756,,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{460,,UnicodeError}.

另請參閱 @ref{545,,locale encoding}。

@node Python UTF-8 模式,行程參數,File Names Command Line Arguments and Environment Variables,os --- 各種作業系統介面
@anchor{library/os python-utf-8-mode}@anchor{2eb7}@anchor{library/os utf8-mode}@anchor{85f}
@subsubsection Python UTF-8 模式



在 3.7 版被加入: 更多資訊請見 
@geindex Python Enhancement Proposals; PEP 540
PEP 540@footnote{https://peps.python.org/pep-0540/}。


Python 在 UTF-8 模式下會忽略 @ref{545,,locale encoding} 並且強制使用 UTF-8 去編碼：


@itemize *

@item 
Use UTF-8 as the @ref{756,,filesystem encoding}.

@item 
@ref{e4e,,sys.getfilesystemencoding()} 回傳 @code{'utf-8'}。

@item 
@ref{755,,locale.getpreferredencoding()} 回傳 @code{'utf-8'}（`do_setlocale' 引數並無任何效果）。

@item 
@ref{758,,sys.stdin}, @ref{cc4,,sys.stdout}, and @ref{b2a,,sys.stderr} all use
UTF-8 as their text encoding, with the @code{surrogateescape}
@ref{1a9e,,error handler} being enabled for @ref{758,,sys.stdin}
and @ref{cc4,,sys.stdout} (@ref{b2a,,sys.stderr} continues to use
@code{backslashreplace} as it does in the default locale-aware mode)

@item 
在 Unix 中，@ref{1b48,,os.device_encoding()} 回傳 @code{'utf-8'} 而非裝置編碼。
@end itemize

請注意，在 UTF-8 模式中，標準的串流設定會被 
@geindex PYTHONIOENCODING
@geindex 環境變數; PYTHONIOENCODING
@ref{1205,,PYTHONIOENCODING} 覆蓋（如同在預設在地化覺察 模式一樣）。

As a consequence of the changes in those lower level APIs, other higher
level APIs also exhibit different default behaviours:


@itemize *

@item 
命令列引數、環境變數及檔案名稱會以 UTF-8 編碼形式來被解碼成文字。

@item 
@ref{e49,,os.fsdecode()} 和 @ref{e4a,,os.fsencode()} 使用 UTF-8 編碼。

@item 
@ref{315,,open()}, @ref{739,,io.open()}, and @ref{314,,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{85f,,Python UTF-8 Mode} is enabled if the LC_CTYPE locale is
@code{C} or @code{POSIX} at Python startup (see the @ref{98b,,PyConfig_Read()}
function).

It can be enabled or disabled using the @ref{16f,,-X utf8} command line
option and the 
@geindex PYTHONUTF8
@geindex 環境變數; PYTHONUTF8
@ref{cc6,,PYTHONUTF8} environment variable.

If the 
@geindex PYTHONUTF8
@geindex 環境變數; PYTHONUTF8
@ref{cc6,,PYTHONUTF8} environment variable is not set at all, then the
interpreter defaults to using the current locale settings, `unless' the current
locale is identified as a legacy ASCII-based locale (as described for
@geindex PYTHONCOERCECLOCALE
@geindex 環境變數; PYTHONCOERCECLOCALE
@ref{cc3,,PYTHONCOERCECLOCALE}), and locale coercion is either disabled or
fails. In such legacy locales, the interpreter will default to enabling UTF-8
mode unless explicitly instructed not to do so.

The Python UTF-8 Mode can only be enabled at the Python startup. Its value
can be read from @ref{895,,sys.flags.utf8_mode}.

See also the @ref{20e1,,UTF-8 mode on Windows}
and the @ref{756,,filesystem encoding and error handler}.


@subsubheading 也參考



@table @asis

@geindex Python Enhancement Proposals; PEP 686

@item PEP 686@footnote{https://peps.python.org/pep-0686/}

Python 3.15 預設使用 @ref{85f,,Python UTF-8 模式}
@end table


@node 行程參數,File Object Creation,Python UTF-8 模式,os --- 各種作業系統介面
@anchor{library/os os-procinfo}@anchor{2eb8}@anchor{library/os process-parameters}@anchor{2eb9}
@subsubsection 行程參數


These functions and data items provide information and operate on the current
process and user.

@geindex ctermid() (於 os 模組中)
@anchor{library/os os ctermid}@anchor{2eba}
@deffn {函式} os.ctermid ()

Return the filename corresponding to the controlling terminal of the process.

@ref{2006,,可用性}: Unix, not WASI.
@end deffn

@geindex environ (於 os 模組中)
@anchor{library/os os environ}@anchor{259}
@deffn {資料} os.environ

A @ref{13bc,,mapping} object where keys and values are strings that represent
the process environment.  For example, @code{environ['HOME']} is the pathname
of your home directory (on some platforms), and is equivalent to
@code{getenv("HOME")} in C.

This mapping is captured the first time the @ref{a5,,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{259,,os.environ},
except for changes made by modifying @ref{259,,os.environ} directly.

This mapping may be used to modify the environment as well as query the
environment.  @ref{25b,,putenv()} will be called automatically when the mapping
is modified.

On Unix, keys and values use @ref{e4e,,sys.getfilesystemencoding()} and
@code{'surrogateescape'} error handler. Use @ref{25a,,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 備註 
呼叫 @ref{25b,,putenv()} 並不會改變 @ref{259,,os.environ}，所以建議直接修改 @ref{259,,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{25c,,unsetenv()} will be called automatically when an item is deleted from
@ref{259,,os.environ}, and when one of the @code{pop()} or @code{clear()} methods is
called.


@subsubheading 也參考


@ref{258,,os.reload_environ()} 函式。



在 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{25a}
@deffn {資料} os.environb

Bytes version of @ref{259,,environ}: a @ref{13bc,,mapping} object where both keys
and values are @ref{192,,bytes} objects representing the process environment.
@ref{259,,environ} and @ref{25a,,environb} are synchronized (modifying
@ref{25a,,environb} updates @ref{259,,environ}, and vice versa).

@ref{25a,,environb} is only available if @ref{1416,,supports_bytes_environ} is
@code{True}.


在 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{258}
@deffn {函式} os.reload_environ ()

The @ref{259,,os.environ} and @ref{25a,,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{25b,,os.putenv()} or @ref{25c,,os.unsetenv()}.
Use @code{os.reload_environ()} to update @ref{259,,os.environ} and @ref{25a,,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 an other thread is an undefined behavior. Reading from
@ref{259,,os.environ} or @ref{25a,,os.environb}, or calling @ref{2ebb,,os.getenv()}
while reloading, may return an empty result.
@end quotation
@end cartouche


在 3.14 版被加入.

@end deffn


@deffn {函式} os.chdir (path)

@deffnx {函式} os.fchdir (fd)

@deffnx {函式} os.getcwd ()

These functions are described in @ref{2ebc,,Files and Directories}.
@end deffn

@geindex fsencode() (於 os 模組中)
@anchor{library/os os fsencode}@anchor{e4a}
@deffn {函式} os.fsencode (filename)

Encode @ref{59b,,path-like} `filename' to the
@ref{756,,filesystem encoding and error handler}; return @ref{192,,bytes}
unchanged.

@ref{e49,,fsdecode()} 是反函式。


在 3.2 版被加入.



在 3.6 版的變更: Support added to accept objects implementing the @ref{e46,,os.PathLike}
interface.

@end deffn

@geindex fsdecode() (於 os 模組中)
@anchor{library/os os fsdecode}@anchor{e49}
@deffn {函式} os.fsdecode (filename)

Decode the @ref{59b,,path-like} `filename' from the
@ref{756,,filesystem encoding and error handler}; return @ref{169,,str}
unchanged.

@ref{e4a,,fsencode()} 是反函式。


在 3.2 版被加入.



在 3.6 版的變更: Support added to accept objects implementing the @ref{e46,,os.PathLike}
interface.

@end deffn

@geindex fspath() (於 os 模組中)
@anchor{library/os os fspath}@anchor{e48}
@deffn {函式} os.fspath (path)

Return the file system representation of the path.

If @ref{169,,str} or @ref{192,,bytes} is passed in, it is returned unchanged.
Otherwise @ref{e47,,__fspath__()} is called and its value is
returned as long as it is a @ref{169,,str} or @ref{192,,bytes} object.
In all other cases, @ref{198,,TypeError} is raised.


在 3.6 版被加入.

@end deffn

@geindex PathLike (os 中的類別)
@anchor{library/os os PathLike}@anchor{e46}
@deffn {類別} os.PathLike

An @ref{13b7,,abstract base class} for objects representing a file system path,
e.g. @ref{6c6,,pathlib.PurePath}.


在 3.6 版被加入.


@geindex __fspath__() (os.PathLike 的方法)
@anchor{library/os os PathLike __fspath__}@anchor{e47}
@deffn {方法} abstractmethod __fspath__ ()

Return the file system path representation of the object.

The method should only return a @ref{169,,str} or @ref{192,,bytes} object,
with the preference being for @ref{169,,str}.
@end deffn
@end deffn

@geindex getenv() (於 os 模組中)
@anchor{library/os os getenv}@anchor{2ebb}
@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 @ref{2ebb,,getenv()} uses @ref{259,,os.environ}, the mapping of @ref{2ebb,,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{e4e,,sys.getfilesystemencoding()}
and @code{'surrogateescape'} error handler. Use @ref{1417,,os.getenvb()} if you
would like to use a different encoding.

@ref{2006,,可用性}: Unix, Windows.
@end deffn

@geindex getenvb() (於 os 模組中)
@anchor{library/os os getenvb}@anchor{1417}
@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 @ref{1417,,getenvb()} uses @ref{25a,,os.environb}, the mapping of @ref{1417,,getenvb()} is
similarly also captured on import, and the function may not reflect
future environment changes.

@ref{1417,,getenvb()} is only available if @ref{1416,,supports_bytes_environ}
is @code{True}.

@ref{2006,,可用性}: Unix.


在 3.2 版被加入.

@end deffn

@geindex get_exec_path() (於 os 模組中)
@anchor{library/os os get_exec_path}@anchor{2ebd}
@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{259,,environ} is used.


在 3.2 版被加入.

@end deffn

@geindex getegid() (於 os 模組中)
@anchor{library/os os getegid}@anchor{2ebe}
@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{2006,,可用性}: Unix, not WASI.
@end deffn

@geindex geteuid() (於 os 模組中)
@anchor{library/os os geteuid}@anchor{1aa1}
@deffn {函式} os.geteuid ()

@geindex user（使用者）;effective id

Return the current process's effective user id.

@ref{2006,,可用性}: Unix, not WASI.
@end deffn

@geindex getgid() (於 os 模組中)
@anchor{library/os os getgid}@anchor{2ebf}
@deffn {函式} os.getgid ()

@geindex process;group（群組）

Return the real group id of the current process.

@ref{2006,,可用性}: Unix.

The function is a stub on WASI, see @ref{1a99,,WebAssembly 平台} for more
information.
@end deffn

@geindex getgrouplist() (於 os 模組中)
@anchor{library/os os getgrouplist}@anchor{1315}
@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{2006,,可用性}: Unix, not WASI.


在 3.3 版被加入.

@end deffn

@geindex getgroups() (於 os 模組中)
@anchor{library/os os getgroups}@anchor{2ec0}
@deffn {函式} os.getgroups ()

Return list of supplemental group ids associated with the current process.

@ref{2006,,可用性}: Unix, not WASI.

@cartouche
@quotation 備註 
On macOS, @ref{2ec0,,getgroups()} behavior differs somewhat from
other Unix platforms. If the Python interpreter was built with a
deployment target of @code{10.5} or earlier, @ref{2ec0,,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{2ec1,,setgroups()} if suitably privileged.
If built with a deployment target greater than @code{10.5},
@ref{2ec0,,getgroups()} returns the current group access list for the user
associated with the effective user id of the process; the group access
list may change over the lifetime of the process, it is not affected by
calls to @ref{2ec1,,setgroups()}, and its length is not limited to 16.  The
deployment target value, @code{MACOSX_DEPLOYMENT_TARGET}, can be
obtained with @ref{174,,sysconfig.get_config_var()}.
@end quotation
@end cartouche
@end deffn

@geindex getlogin() (於 os 模組中)
@anchor{library/os os getlogin}@anchor{17a5}
@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{652,,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{2006,,可用性}: Unix, Windows, not WASI.
@end deffn

@geindex getpgid() (於 os 模組中)
@anchor{library/os os getpgid}@anchor{2ec2}
@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{2006,,可用性}: Unix, not WASI.
@end deffn

@geindex getpgrp() (於 os 模組中)
@anchor{library/os os getpgrp}@anchor{2ec3}
@deffn {函式} os.getpgrp ()

@geindex process;group（群組）

Return the id of the current process group.

@ref{2006,,可用性}: Unix, not WASI.
@end deffn

@geindex getpid() (於 os 模組中)
@anchor{library/os os getpid}@anchor{2eb3}
@deffn {函式} os.getpid ()

@geindex process;id

Return the current process id.

The function is a stub on WASI, see @ref{1a99,,WebAssembly 平台} for more
information.
@end deffn

@geindex getppid() (於 os 模組中)
@anchor{library/os os getppid}@anchor{191f}
@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{2006,,可用性}: Unix, Windows, not WASI.


在 3.2 版的變更: 新增對 Windows 的支援。

@end deffn

@geindex getpriority() (於 os 模組中)
@anchor{library/os os getpriority}@anchor{1300}
@deffn {函式} os.getpriority (which, who)

@geindex process;scheduling priority（排程優先權）

Get program scheduling priority.  The value `which' is one of
@ref{2ec4,,PRIO_PROCESS}, @ref{2ec5,,PRIO_PGRP}, or @ref{2ec6,,PRIO_USER}, and `who'
is interpreted relative to `which' (a process identifier for
@ref{2ec4,,PRIO_PROCESS}, process group identifier for @ref{2ec5,,PRIO_PGRP}, and a
user ID for @ref{2ec6,,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{2006,,可用性}: Unix, not WASI.


在 3.3 版被加入.

@end deffn

@geindex PRIO_PROCESS (於 os 模組中)
@geindex PRIO_PGRP (於 os 模組中)
@geindex PRIO_USER (於 os 模組中)
@anchor{library/os os PRIO_PROCESS}@anchor{2ec4}
@deffn {資料} os.PRIO_PROCESS
@anchor{library/os os PRIO_PGRP}@anchor{2ec5}
@deffnx {資料} os.PRIO_PGRP
@anchor{library/os os PRIO_USER}@anchor{2ec6}
@deffnx {資料} os.PRIO_USER

Parameters for the @ref{1300,,getpriority()} and @ref{1301,,setpriority()} functions.

@ref{2006,,可用性}: Unix, not WASI.


在 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{2ec7}
@deffn {資料} os.PRIO_DARWIN_THREAD
@anchor{library/os os PRIO_DARWIN_PROCESS}@anchor{2ec8}
@deffnx {資料} os.PRIO_DARWIN_PROCESS
@anchor{library/os os PRIO_DARWIN_BG}@anchor{2ec9}
@deffnx {資料} os.PRIO_DARWIN_BG
@anchor{library/os os PRIO_DARWIN_NONUI}@anchor{2eca}
@deffnx {資料} os.PRIO_DARWIN_NONUI

Parameters for the @ref{1300,,getpriority()} and @ref{1301,,setpriority()} functions.

@ref{2006,,可用性}: macOS


在 3.12 版被加入.

@end deffn

@geindex getresuid() (於 os 模組中)
@anchor{library/os os getresuid}@anchor{1516}
@deffn {函式} os.getresuid ()

Return a tuple (ruid, euid, suid) denoting the current process's
real, effective, and saved user ids.

@ref{2006,,可用性}: Unix, not WASI.


在 3.2 版被加入.

@end deffn

@geindex getresgid() (於 os 模組中)
@anchor{library/os os getresgid}@anchor{1515}
@deffn {函式} os.getresgid ()

Return a tuple (rgid, egid, sgid) denoting the current process's
real, effective, and saved group ids.

@ref{2006,,可用性}: Unix, not WASI.


在 3.2 版被加入.

@end deffn

@geindex getuid() (於 os 模組中)
@anchor{library/os os getuid}@anchor{179a}
@deffn {函式} os.getuid ()

@geindex user（使用者）;id

Return the current process's real user id.

@ref{2006,,可用性}: Unix.

The function is a stub on WASI, see @ref{1a99,,WebAssembly 平台} for more
information.
@end deffn

@geindex initgroups() (於 os 模組中)
@anchor{library/os os initgroups}@anchor{1519}
@deffn {函式} os.initgroups (username, gid, /)

Call the system 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{2006,,可用性}: Unix, not WASI, not Android.


在 3.2 版被加入.

@end deffn

@geindex putenv() (於 os 模組中)
@anchor{library/os os putenv}@anchor{25b}
@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{1652,,os.system()},
@ref{319,,popen()} or @ref{4b0,,fork()} and @ref{2ecb,,execv()}.

Assignments to items in @ref{259,,os.environ} are automatically translated into
corresponding calls to @ref{25b,,putenv()}; however, calls to @ref{25b,,putenv()}
don't update @ref{259,,os.environ}, so it is actually preferable to assign to items
of @ref{259,,os.environ}. This also applies to @ref{2ebb,,getenv()} and @ref{1417,,getenvb()}, which
respectively use @ref{259,,os.environ} and @ref{25a,,os.environb} in their implementations.

也請見 @ref{258,,os.reload_environ()} 函式。

@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

引發一個附帶引數 @code{key}、@code{value} 的@ref{1b70,,稽核事件} @code{os.putenv}。


在 3.9 版的變更: 此函式現在都會是可用的。

@end deffn

@geindex setegid() (於 os 模組中)
@anchor{library/os os setegid}@anchor{2ecc}
@deffn {函式} os.setegid (egid, /)

Set the current process's effective group id.

@ref{2006,,可用性}: Unix, not WASI, not Android.
@end deffn

@geindex seteuid() (於 os 模組中)
@anchor{library/os os seteuid}@anchor{2ecd}
@deffn {函式} os.seteuid (euid, /)

Set the current process's effective user id.

@ref{2006,,可用性}: Unix, not WASI, not Android.
@end deffn

@geindex setgid() (於 os 模組中)
@anchor{library/os os setgid}@anchor{2ece}
@deffn {函式} os.setgid (gid, /)

Set the current process' group id.

@ref{2006,,可用性}: Unix, not WASI, not Android.
@end deffn

@geindex setgroups() (於 os 模組中)
@anchor{library/os os setgroups}@anchor{2ec1}
@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{2006,,可用性}: 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{2ec0,,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{1a7b}
@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{2ecf,,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{69d,,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{2ecf,,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{2b7e,,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{2006,,可用性}: Linux >= 3.0 with glibc >= 2.14.


在 3.12 版被加入.



@subsubheading 也參考


@ref{1a7c,,unshare()} 函式。

@end deffn

@geindex setpgrp() (於 os 模組中)
@anchor{library/os os setpgrp}@anchor{2ed0}
@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{2006,,可用性}: Unix, not WASI.
@end deffn

@geindex setpgid() (於 os 模組中)
@anchor{library/os os setpgid}@anchor{2ed1}
@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{2006,,可用性}: Unix, not WASI.
@end deffn

@geindex setpriority() (於 os 模組中)
@anchor{library/os os setpriority}@anchor{1301}
@deffn {函式} os.setpriority (which, who, priority)

@geindex process;scheduling priority（排程優先權）

Set program scheduling priority. The value `which' is one of
@ref{2ec4,,PRIO_PROCESS}, @ref{2ec5,,PRIO_PGRP}, or @ref{2ec6,,PRIO_USER}, and `who'
is interpreted relative to `which' (a process identifier for
@ref{2ec4,,PRIO_PROCESS}, process group identifier for @ref{2ec5,,PRIO_PGRP}, and a
user ID for @ref{2ec6,,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{2006,,可用性}: Unix, not WASI.


在 3.3 版被加入.

@end deffn

@geindex setregid() (於 os 模組中)
@anchor{library/os os setregid}@anchor{2ed2}
@deffn {函式} os.setregid (rgid, egid, /)

Set the current process's real and effective group ids.

@ref{2006,,可用性}: Unix, not WASI, not Android.
@end deffn

@geindex setresgid() (於 os 模組中)
@anchor{library/os os setresgid}@anchor{1517}
@deffn {函式} os.setresgid (rgid, egid, sgid, /)

Set the current process's real, effective, and saved group ids.

@ref{2006,,可用性}: Unix, not WASI, not Android.


在 3.2 版被加入.

@end deffn

@geindex setresuid() (於 os 模組中)
@anchor{library/os os setresuid}@anchor{1518}
@deffn {函式} os.setresuid (ruid, euid, suid, /)

Set the current process's real, effective, and saved user ids.

@ref{2006,,可用性}: Unix, not WASI, not Android.


在 3.2 版被加入.

@end deffn

@geindex setreuid() (於 os 模組中)
@anchor{library/os os setreuid}@anchor{2ed3}
@deffn {函式} os.setreuid (ruid, euid, /)

Set the current process's real and effective user ids.

@ref{2006,,可用性}: Unix, not WASI, not Android.
@end deffn

@geindex getsid() (於 os 模組中)
@anchor{library/os os getsid}@anchor{2ed4}
@deffn {函式} os.getsid (pid, /)

Call the system call @code{getsid()}.  See the Unix manual for the semantics.

@ref{2006,,可用性}: Unix, not WASI.
@end deffn

@geindex setsid() (於 os 模組中)
@anchor{library/os os setsid}@anchor{1c83}
@deffn {函式} os.setsid ()

Call the system call @code{setsid()}.  See the Unix manual for the semantics.

@ref{2006,,可用性}: Unix, not WASI.
@end deffn

@geindex setuid() (於 os 模組中)
@anchor{library/os os setuid}@anchor{2ed5}
@deffn {函式} os.setuid (uid, /)

@geindex user（使用者）;id@comma{} setting（設定）

Set the current process's user id.

@ref{2006,,可用性}: 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{2ed6}
@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{2eb,,ValueError} is raised.
@end deffn

@geindex supports_bytes_environ (於 os 模組中)
@anchor{library/os os supports_bytes_environ}@anchor{1416}
@deffn {資料} os.supports_bytes_environ

@code{True} if the native OS type of the environment is bytes (eg. @code{False} on
Windows).


在 3.2 版被加入.

@end deffn

@geindex umask() (於 os 模組中)
@anchor{library/os os umask}@anchor{2ed7}
@deffn {函式} os.umask (mask, /)

Set the current numeric umask and return the previous umask.

The function is a stub on WASI, see @ref{1a99,,WebAssembly 平台} for more
information.
@end deffn

@geindex uname() (於 os 模組中)
@anchor{library/os os uname}@anchor{1317}
@deffn {函式} os.uname ()

@geindex gethostname()（於 socket 模組）
@geindex gethostbyaddr()（於 socket 模組）

Returns information identifying the current operating system.
The return value is an object with five attributes:


@itemize *

@item 
@code{sysname} - 作業系統名稱

@item 
@code{nodename} - name of machine on network (implementation-defined)

@item 
@code{release} - operating system release

@item 
@code{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{2ed8,,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{1cdb,,platform.uname()}
can be used to get the user-facing operating system name and version on iOS and
Android.

@ref{2006,,可用性}: 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{25c}
@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{1652,,os.system()}, @ref{319,,popen()} or
@ref{4b0,,fork()} and @ref{2ecb,,execv()}.

Deletion of items in @ref{259,,os.environ} is automatically translated into a
corresponding call to @ref{25c,,unsetenv()}; however, calls to @ref{25c,,unsetenv()}
don't update @ref{259,,os.environ}, so it is actually preferable to delete items of
@ref{259,,os.environ}.

也請見 @ref{258,,os.reload_environ()} 函式。

引發一個附帶引數 @code{key} 的@ref{1b70,,稽核事件} @code{os.unsetenv}。


在 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{1a7c}
@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{2ecf,,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{2006,,可用性}: Linux >= 2.6.16.


在 3.12 版被加入.



@subsubheading 也參考


@ref{1a7b,,setns()} 函式。

@end deffn
@anchor{library/os os-unshare-clone-flags}@anchor{2ecf}
Flags to the @ref{1a7c,,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{2ed9}
@deffn {資料} os.CLONE_FILES
@anchor{library/os os CLONE_FS}@anchor{2eda}
@deffnx {資料} os.CLONE_FS
@anchor{library/os os CLONE_NEWCGROUP}@anchor{2edb}
@deffnx {資料} os.CLONE_NEWCGROUP
@anchor{library/os os CLONE_NEWIPC}@anchor{2edc}
@deffnx {資料} os.CLONE_NEWIPC
@anchor{library/os os CLONE_NEWNET}@anchor{2edd}
@deffnx {資料} os.CLONE_NEWNET
@anchor{library/os os CLONE_NEWNS}@anchor{2ede}
@deffnx {資料} os.CLONE_NEWNS
@anchor{library/os os CLONE_NEWPID}@anchor{2edf}
@deffnx {資料} os.CLONE_NEWPID
@anchor{library/os os CLONE_NEWTIME}@anchor{2ee0}
@deffnx {資料} os.CLONE_NEWTIME
@anchor{library/os os CLONE_NEWUSER}@anchor{2ee1}
@deffnx {資料} os.CLONE_NEWUSER
@anchor{library/os os CLONE_NEWUTS}@anchor{2ee2}
@deffnx {資料} os.CLONE_NEWUTS
@anchor{library/os os CLONE_SIGHAND}@anchor{2ee3}
@deffnx {資料} os.CLONE_SIGHAND
@anchor{library/os os CLONE_SYSVSEM}@anchor{2ee4}
@deffnx {資料} os.CLONE_SYSVSEM
@anchor{library/os os CLONE_THREAD}@anchor{2ee5}
@deffnx {資料} os.CLONE_THREAD
@anchor{library/os os CLONE_VM}@anchor{2ee6}
@deffnx {資料} os.CLONE_VM
@end deffn

@node File Object Creation,File Descriptor Operations,行程參數,os --- 各種作業系統介面
@anchor{library/os file-object-creation}@anchor{2ee7}@anchor{library/os os-newstreams}@anchor{2ee8}
@subsubsection File Object Creation


These functions create new @ref{13c4,,file objects}.  (See also
@ref{f8d,,open()} for opening file descriptors.)

@geindex fdopen() (於 os 模組中)
@anchor{library/os os fdopen}@anchor{2232}
@deffn {函式} os.fdopen (fd, *args, **kwargs)

Return an open file object connected to the file descriptor `fd'.  This is an
alias of the @ref{315,,open()} built-in function and accepts the same arguments.
The only difference is that the first argument of @ref{2232,,fdopen()} must always
be an integer.
@end deffn

@node File Descriptor Operations,Files and Directories,File Object Creation,os --- 各種作業系統介面
@anchor{library/os file-descriptor-operations}@anchor{2ee9}@anchor{library/os os-fd-ops}@anchor{2eea}
@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{2b7e,,fileno()} method can be used to obtain the file descriptor
associated with a @ref{13c4,,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{d63}
@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{f8d,,os.open()} or @ref{1a93,,pipe()}.  To close a "file
object" returned by the built-in function @ref{315,,open()} or by @ref{319,,popen()} or
@ref{2232,,fdopen()}, use its @ref{501,,close()} method.
@end quotation
@end cartouche
@end deffn

@geindex closerange() (於 os 模組中)
@anchor{library/os os closerange}@anchor{2eeb}
@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{182a}
@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{2c0,,OSError} is
raised with @ref{2599,,errno} set to @ref{2eec,,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{182a,,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{2006,,可用性}: Linux >= 4.5 with glibc >= 2.27.


在 3.8 版被加入.

@end deffn

@geindex device_encoding() (於 os 模組中)
@anchor{library/os os device_encoding}@anchor{1b48}
@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{87e,,None}.

On Unix, if the @ref{85f,,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{1c8b}
@deffn {函式} os.dup (fd, /)

Return a duplicate of file descriptor `fd'. The new file descriptor is
@ref{10f7,,non-inheritable}.

On Windows, when duplicating a standard stream (0: stdin, 1: stdout,
2: stderr), the new file descriptor is @ref{10f7,,inheritable}.

@ref{2006,,可用性}: not WASI.


在 3.4 版的變更: The new file descriptor is now non-inheritable.

@end deffn

@geindex dup2() (於 os 模組中)
@anchor{library/os os dup2}@anchor{d52}
@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{10f7,,inheritable} by default or non-inheritable if `inheritable'
is @code{False}.

@ref{2006,,可用性}: not WASI.


在 3.4 版的變更: 新增可選用的參數 `inheritable'。



在 3.7 版的變更: Return `fd2' on success. Previously, @code{None} was always returned.

@end deffn

@geindex fchmod() (於 os 模組中)
@anchor{library/os os fchmod}@anchor{525}
@deffn {函式} os.fchmod (fd, mode)

Change the mode of the file given by `fd' to the numeric `mode'.  See the
docs for @ref{524,,chmod()} for possible values of `mode'.  As of Python 3.3, this
is equivalent to @code{os.chmod(fd, mode)}.

引發一個附帶引數 @code{path}、@code{mode}、@code{dir_fd} 的@ref{1b70,,稽核事件} @code{os.chmod}。

@ref{2006,,可用性}: Unix, Windows.

The function is limited on WASI, see @ref{1a99,,WebAssembly 平台} for more
information.


在 3.13 版的變更: 新增對 Windows 的支援。

@end deffn

@geindex fchown() (於 os 模組中)
@anchor{library/os os fchown}@anchor{f85}
@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{12ef,,chown()}.  As of Python 3.3, this is equivalent to @code{os.chown(fd, uid,
gid)}.

引發一個附帶引數 @code{path}、@code{uid}、@code{gid}、@code{dir_fd} 的@ref{1b70,,稽核事件} @code{os.chown}。

@ref{2006,,可用性}: Unix.

The function is limited on WASI, see @ref{1a99,,WebAssembly 平台} for more
information.
@end deffn

@geindex fdatasync() (於 os 模組中)
@anchor{library/os os fdatasync}@anchor{f86}
@deffn {函式} os.fdatasync (fd)

Force write of file with filedescriptor `fd' to disk. Does not force update of
metadata.

@ref{2006,,可用性}: 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{2eed}
@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{2eb,,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{2c0,,OSError} is raised with
@ref{1c9b,,errno.EINVAL} for the error number.

As of Python 3.3, this is equivalent to @code{os.pathconf(fd, name)}.

@ref{2006,,可用性}: Unix.
@end deffn

@geindex fstat() (於 os 模組中)
@anchor{library/os os fstat}@anchor{f87}
@deffn {函式} os.fstat (fd)

Get the status of the file descriptor `fd'. Return a @ref{16b5,,stat_result}
object.

As of Python 3.3, this is equivalent to @code{os.stat(fd)}.


@subsubheading 也參考


The @ref{26d,,stat()} function.

@end deffn

@geindex fstatvfs() (於 os 模組中)
@anchor{library/os os fstatvfs}@anchor{f88}
@deffn {函式} os.fstatvfs (fd, /)

Return information about the filesystem containing the file associated with
file descriptor `fd', like @ref{12fd,,statvfs()}.  As of Python 3.3, this is
equivalent to @code{os.statvfs(fd)}.

@ref{2006,,可用性}: Unix.
@end deffn

@geindex fsync() (於 os 模組中)
@anchor{library/os os fsync}@anchor{f89}
@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{13c4,,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{2006,,可用性}: Unix, Windows.
@end deffn

@geindex ftruncate() (於 os 模組中)
@anchor{library/os os ftruncate}@anchor{f8a}
@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)}.

引發一個附帶引數 @code{fd}、@code{length} 的@ref{1b70,,稽核事件} @code{os.truncate}。

@ref{2006,,可用性}: Unix, Windows.


在 3.5 版的變更: 新增對 Windows 的支援

@end deffn

@geindex get_blocking() (於 os 模組中)
@anchor{library/os os get_blocking}@anchor{1034}
@deffn {函式} os.get_blocking (fd, /)

Get the blocking mode of the file descriptor: @code{False} if the
@ref{1036,,O_NONBLOCK} flag is set, @code{True} if the flag is cleared.

另請參閱 @ref{1035,,set_blocking()} 與 @ref{2eee,,socket.socket.setblocking()}。

@ref{2006,,可用性}: Unix, Windows.

The function is limited on WASI, see @ref{1a99,,WebAssembly 平台} for more
information.

On Windows, this function is limited to pipes.


在 3.5 版被加入.



在 3.12 版的變更: 新增對 Windows 上的 pipe 支援。

@end deffn

@geindex grantpt() (於 os 模組中)
@anchor{library/os os grantpt}@anchor{194d}
@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{2006,,可用性}: Unix, not WASI.


在 3.13 版被加入.

@end deffn

@geindex isatty() (於 os 模組中)
@anchor{library/os os isatty}@anchor{1b47}
@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{1314}
@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{2eef,,F_LOCK}, @ref{2ef0,,F_TLOCK},
@ref{2ef1,,F_ULOCK} or @ref{2ef2,,F_TEST}.
`len' specifies the section of the file to lock.

引發一個附帶引數 @code{fd}、@code{cmd}、@code{len} 的@ref{1b70,,稽核事件} @code{os.lockf}。

@ref{2006,,可用性}: Unix.


在 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{2eef}
@deffn {資料} os.F_LOCK
@anchor{library/os os F_TLOCK}@anchor{2ef0}
@deffnx {資料} os.F_TLOCK
@anchor{library/os os F_ULOCK}@anchor{2ef1}
@deffnx {資料} os.F_ULOCK
@anchor{library/os os F_TEST}@anchor{2ef2}
@deffnx {資料} os.F_TEST

Flags that specify what action @ref{1314,,lockf()} will take.

@ref{2006,,可用性}: Unix.


在 3.3 版被加入.

@end deffn

@geindex login_tty() (於 os 模組中)
@anchor{library/os os login_tty}@anchor{1a15}
@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{2006,,可用性}: Unix, not WASI.


在 3.11 版被加入.

@end deffn

@geindex lseek() (於 os 模組中)
@anchor{library/os os lseek}@anchor{1318}
@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{148e,,SEEK_SET} or @code{0} -- set `pos' relative to the beginning of the file

@item 
@ref{148f,,SEEK_CUR} or @code{1} -- set `pos' relative to the current file position

@item 
@ref{1490,,SEEK_END} or @code{2} -- set `pos' relative to the end of the file

@item 
@ref{2ef3,,SEEK_HOLE} -- set `pos' to the next data location, relative to `pos'

@item 
@ref{2ef4,,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{148e}
@deffn {資料} os.SEEK_SET
@anchor{library/os os SEEK_CUR}@anchor{148f}
@deffnx {資料} os.SEEK_CUR
@anchor{library/os os SEEK_END}@anchor{1490}
@deffnx {資料} os.SEEK_END

Parameters to the @ref{1318,,lseek()} function and the @ref{148d,,seek()}
method on @ref{13c4,,file-like objects},
for whence to adjust the file position indicator.


@table @asis

@item @ref{148e,,SEEK_SET}

Adjust the file position relative to the beginning of the file.

@item @ref{148f,,SEEK_CUR}

Adjust the file position relative to the current file position.

@item @ref{1490,,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{2ef3}
@deffn {資料} os.SEEK_HOLE
@anchor{library/os os SEEK_DATA}@anchor{2ef4}
@deffnx {資料} os.SEEK_DATA

Parameters to the @ref{1318,,lseek()} function and the @ref{148d,,seek()}
method on @ref{13c4,,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{2006,,可用性}: Linux >= 3.1, macOS, Unix


在 3.3 版被加入.

@end deffn

@geindex open() (於 os 模組中)
@anchor{library/os os open}@anchor{f8d}
@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{10f7,,non-inheritable}.

For a description of the flag and mode values, see the C run-time documentation;
flag constants (like @ref{2ef5,,O_RDONLY} and @ref{2ef6,,O_WRONLY}) are defined in
the @ref{a5,,os} module.  In particular, on Windows adding
@ref{2ef7,,O_BINARY} is needed to open files in binary mode.

This function can support @ref{12eb,,paths relative to directory descriptors} with the `dir_fd' parameter.

引發一個附帶引數 @code{path}、@code{mode}、@code{flags} 的@ref{1b70,,稽核事件} @code{open}。


在 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 @ref{315,,open()}, which returns a @ref{13c4,,file object} with
@code{read()} and @code{write()} methods (and many more).  To
wrap a file descriptor in a file object, use @ref{2232,,fdopen()}.
@end quotation
@end cartouche


在 3.3 版的變更: 新增 `dir_fd' 參數。



在 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{f83,,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{59b,,path-like object}.

@end deffn

The following constants are options for the `flags' parameter to the
@ref{f8d,,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{2ef5}
@deffn {資料} os.O_RDONLY
@anchor{library/os os O_WRONLY}@anchor{2ef6}
@deffnx {資料} os.O_WRONLY
@anchor{library/os os O_RDWR}@anchor{2ef8}
@deffnx {資料} os.O_RDWR
@anchor{library/os os O_APPEND}@anchor{2ef9}
@deffnx {資料} os.O_APPEND
@anchor{library/os os O_CREAT}@anchor{2efa}
@deffnx {資料} os.O_CREAT
@anchor{library/os os O_EXCL}@anchor{2b82}
@deffnx {資料} os.O_EXCL
@anchor{library/os os O_TRUNC}@anchor{2efb}
@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{2efc}
@deffn {資料} os.O_DSYNC
@anchor{library/os os O_RSYNC}@anchor{2efd}
@deffnx {資料} os.O_RSYNC
@anchor{library/os os O_SYNC}@anchor{2efe}
@deffnx {資料} os.O_SYNC
@anchor{library/os os O_NDELAY}@anchor{2eff}
@deffnx {資料} os.O_NDELAY
@anchor{library/os os O_NONBLOCK}@anchor{1036}
@deffnx {資料} os.O_NONBLOCK
@anchor{library/os os O_NOCTTY}@anchor{2f00}
@deffnx {資料} os.O_NOCTTY
@anchor{library/os os O_CLOEXEC}@anchor{1277}
@deffnx {資料} os.O_CLOEXEC

The above constants are only available on Unix.


在 3.3 版的變更: Add @ref{1277,,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{2ef7}
@deffn {資料} os.O_BINARY
@anchor{library/os os O_NOINHERIT}@anchor{2f01}
@deffnx {資料} os.O_NOINHERIT
@anchor{library/os os O_SHORT_LIVED}@anchor{2f02}
@deffnx {資料} os.O_SHORT_LIVED
@anchor{library/os os O_TEMPORARY}@anchor{2f03}
@deffnx {資料} os.O_TEMPORARY
@anchor{library/os os O_RANDOM}@anchor{2f04}
@deffnx {資料} os.O_RANDOM
@anchor{library/os os O_SEQUENTIAL}@anchor{2f05}
@deffnx {資料} os.O_SEQUENTIAL
@anchor{library/os os O_TEXT}@anchor{2f06}
@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{a14}
@deffn {資料} os.O_EVTONLY
@anchor{library/os os O_FSYNC}@anchor{a15}
@deffnx {資料} os.O_FSYNC
@anchor{library/os os O_SYMLINK}@anchor{a16}
@deffnx {資料} os.O_SYMLINK
@anchor{library/os os O_NOFOLLOW_ANY}@anchor{a17}
@deffnx {資料} os.O_NOFOLLOW_ANY

The above constants are only available on macOS.


在 3.10 版的變更: Add @ref{a14,,O_EVTONLY}, @ref{a15,,O_FSYNC}, @ref{a16,,O_SYMLINK}
and @ref{a17,,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{2f07}
@deffn {資料} os.O_ASYNC
@anchor{library/os os O_DIRECT}@anchor{2f08}
@deffnx {資料} os.O_DIRECT
@anchor{library/os os O_DIRECTORY}@anchor{2f09}
@deffnx {資料} os.O_DIRECTORY
@anchor{library/os os O_NOFOLLOW}@anchor{2f0a}
@deffnx {資料} os.O_NOFOLLOW
@anchor{library/os os O_NOATIME}@anchor{2f0b}
@deffnx {資料} os.O_NOATIME
@anchor{library/os os O_PATH}@anchor{116d}
@deffnx {資料} os.O_PATH
@anchor{library/os os O_TMPFILE}@anchor{116e}
@deffnx {資料} os.O_TMPFILE
@anchor{library/os os O_SHLOCK}@anchor{1626}
@deffnx {資料} os.O_SHLOCK
@anchor{library/os os O_EXLOCK}@anchor{1627}
@deffnx {資料} os.O_EXLOCK

The above constants are extensions and not present if they are not defined by
the C library.


在 3.4 版的變更: Add @ref{116d,,O_PATH} on systems that support it.
Add @ref{116e,,O_TMPFILE}, only available on Linux Kernel 3.11
  or newer.

@end deffn

@geindex openpty() (於 os 模組中)
@anchor{library/os os openpty}@anchor{2f0c}
@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{10f7,,non-inheritable}. For a (slightly) more
portable approach, use the @ref{b6,,pty} module.

@ref{2006,,可用性}: Unix, not WASI.


在 3.4 版的變更: The new file descriptors are now non-inheritable.

@end deffn

@geindex pipe() (於 os 模組中)
@anchor{library/os os pipe}@anchor{1a93}
@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{10f7,,non-inheritable}.

@ref{2006,,可用性}: Unix, Windows.


在 3.4 版的變更: The new file descriptors are now non-inheritable.

@end deffn

@geindex pipe2() (於 os 模組中)
@anchor{library/os os pipe2}@anchor{12ea}
@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{1036,,O_NONBLOCK}, @ref{1277,,O_CLOEXEC}.
Return a pair of file descriptors @code{(r, w)} usable for reading and writing,
respectively.

@ref{2006,,可用性}: Unix, not WASI.


在 3.3 版被加入.

@end deffn

@geindex posix_fallocate() (於 os 模組中)
@anchor{library/os os posix_fallocate}@anchor{f8f}
@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{2006,,可用性}: Unix.


在 3.3 版被加入.

@end deffn

@geindex posix_fadvise() (於 os 模組中)
@anchor{library/os os posix_fadvise}@anchor{f8e}
@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{2f0d,,POSIX_FADV_NORMAL}, @ref{2f0e,,POSIX_FADV_SEQUENTIAL},
@ref{2f0f,,POSIX_FADV_RANDOM}, @ref{2f10,,POSIX_FADV_NOREUSE},
@ref{2f11,,POSIX_FADV_WILLNEED} or @ref{2f12,,POSIX_FADV_DONTNEED}.

@ref{2006,,可用性}: Unix.


在 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{2f0d}
@deffn {資料} os.POSIX_FADV_NORMAL
@anchor{library/os os POSIX_FADV_SEQUENTIAL}@anchor{2f0e}
@deffnx {資料} os.POSIX_FADV_SEQUENTIAL
@anchor{library/os os POSIX_FADV_RANDOM}@anchor{2f0f}
@deffnx {資料} os.POSIX_FADV_RANDOM
@anchor{library/os os POSIX_FADV_NOREUSE}@anchor{2f10}
@deffnx {資料} os.POSIX_FADV_NOREUSE
@anchor{library/os os POSIX_FADV_WILLNEED}@anchor{2f11}
@deffnx {資料} os.POSIX_FADV_WILLNEED
@anchor{library/os os POSIX_FADV_DONTNEED}@anchor{2f12}
@deffnx {資料} os.POSIX_FADV_DONTNEED

Flags that can be used in `advice' in @ref{f8e,,posix_fadvise()} that specify
the access pattern that is likely to be used.

@ref{2006,,可用性}: Unix.


在 3.3 版被加入.

@end deffn

@geindex pread() (於 os 模組中)
@anchor{library/os os pread}@anchor{d4e}
@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{2006,,可用性}: Unix.


在 3.3 版被加入.

@end deffn

@geindex posix_openpt() (於 os 模組中)
@anchor{library/os os posix_openpt}@anchor{194c}
@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{10f7,,non-inheritable}.
If the value @ref{1277,,O_CLOEXEC} is available on the system, it is added to
`oflag'.

@ref{2006,,可用性}: Unix, not WASI.


在 3.13 版被加入.

@end deffn

@geindex preadv() (於 os 模組中)
@anchor{library/os os preadv}@anchor{d4c}
@deffn {函式} os.preadv (fd, buffers, offset, flags=0, /)

Read from a file descriptor `fd' at a position of `offset' into mutable
@ref{193,,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{2f13,,RWF_HIPRI}

@item 
@ref{2f14,,RWF_NOWAIT}
@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{185a,,sysconf()} value
@code{'SC_IOV_MAX'}) on the number of buffers that can be used.

Combine the functionality of @ref{d4d,,os.readv()} and @ref{d4e,,os.pread()}.

@ref{2006,,可用性}: Linux >= 2.6.30, FreeBSD >= 6.0, OpenBSD >= 2.7, AIX >= 7.1.

Using flags requires Linux >= 4.6.


在 3.7 版被加入.

@end deffn

@geindex RWF_NOWAIT (於 os 模組中)
@anchor{library/os os RWF_NOWAIT}@anchor{2f14}
@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{25a8,,errno.EAGAIN}.

@ref{2006,,可用性}: Linux >= 4.14.


在 3.7 版被加入.

@end deffn

@geindex RWF_HIPRI (於 os 模組中)
@anchor{library/os os RWF_HIPRI}@anchor{2f13}
@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{2f08,,O_DIRECT} flag.

@ref{2006,,可用性}: Linux >= 4.6.


在 3.7 版被加入.

@end deffn

@geindex ptsname() (於 os 模組中)
@anchor{library/os os ptsname}@anchor{194f}
@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{2006,,可用性}: Unix, not WASI.


在 3.13 版被加入.

@end deffn

@geindex pwrite() (於 os 模組中)
@anchor{library/os os pwrite}@anchor{d51}
@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{2006,,可用性}: Unix.


在 3.3 版被加入.

@end deffn

@geindex pwritev() (於 os 模組中)
@anchor{library/os os pwritev}@anchor{d4f}
@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{193,,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{2f15,,RWF_DSYNC}

@item 
@ref{2f16,,RWF_SYNC}

@item 
@ref{1bfb,,RWF_APPEND}
@end itemize

Return the total number of bytes actually written.

The operating system may set a limit (@ref{185a,,sysconf()} value
@code{'SC_IOV_MAX'}) on the number of buffers that can be used.

Combine the functionality of @ref{d50,,os.writev()} and @ref{d51,,os.pwrite()}.

@ref{2006,,可用性}: Linux >= 2.6.30, FreeBSD >= 6.0, OpenBSD >= 2.7, AIX >= 7.1.

Using flags requires Linux >= 4.6.


在 3.7 版被加入.

@end deffn

@geindex RWF_DSYNC (於 os 模組中)
@anchor{library/os os RWF_DSYNC}@anchor{2f15}
@deffn {資料} os.RWF_DSYNC

Provide a per-write equivalent of the @ref{2efc,,O_DSYNC} @ref{f8d,,os.open()} flag.
This flag effect applies only to the data range written by the system call.

@ref{2006,,可用性}: Linux >= 4.7.


在 3.7 版被加入.

@end deffn

@geindex RWF_SYNC (於 os 模組中)
@anchor{library/os os RWF_SYNC}@anchor{2f16}
@deffn {資料} os.RWF_SYNC

Provide a per-write equivalent of the @ref{2efe,,O_SYNC} @ref{f8d,,os.open()} flag.
This flag effect applies only to the data range written by the system call.

@ref{2006,,可用性}: Linux >= 4.7.


在 3.7 版被加入.

@end deffn

@geindex RWF_APPEND (於 os 模組中)
@anchor{library/os os RWF_APPEND}@anchor{1bfb}
@deffn {資料} os.RWF_APPEND

Provide a per-write equivalent of the @ref{2ef9,,O_APPEND} @ref{f8d,,os.open()}
flag. This flag is meaningful only for @ref{d4f,,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{2006,,可用性}: Linux >= 4.16.


在 3.10 版被加入.

@end deffn

@geindex read() (於 os 模組中)
@anchor{library/os os read}@anchor{f90}
@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{f8d,,os.open()} or @ref{1a93,,pipe()}.  To read a
"file object" returned by the built-in function @ref{315,,open()} or by
@ref{319,,popen()} or @ref{2232,,fdopen()}, or @ref{758,,sys.stdin}, use its
@code{read()} or @code{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{f83,,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{25f}
@deffn {函式} os.readinto (fd, buffer, /)

Read from a file descriptor `fd' into a mutable
@ref{260,,buffer object} `buffer'.

The `buffer' should be mutable and @ref{193,,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{f8d,,os.open()} or @ref{1a93,,os.pipe()}.  To read a
"file object" returned by the built-in function @ref{315,,open()}, or
@ref{758,,sys.stdin}, use its member functions, for example
@ref{180e,,io.BufferedIOBase.readinto()}, @ref{1529,,io.BufferedIOBase.read()}, or
@ref{1f33,,io.TextIOBase.read()}
@end quotation
@end cartouche


在 3.14 版被加入.

@end deffn

@geindex sendfile() (於 os 模組中)
@anchor{library/os os sendfile}@anchor{cfd}
@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
@ref{cfd,,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{2006,,可用性}: Unix, not WASI.

@cartouche
@quotation 備註 
For a higher-level wrapper of @ref{cfd,,sendfile()}, see
@ref{1058,,socket.socket.sendfile()}.
@end quotation
@end cartouche


在 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{2f17}
@deffn {資料} os.SF_NODISKIO
@anchor{library/os os SF_MNOWAIT}@anchor{2f18}
@deffnx {資料} os.SF_MNOWAIT
@anchor{library/os os SF_SYNC}@anchor{2f19}
@deffnx {資料} os.SF_SYNC

Parameters to the @ref{cfd,,sendfile()} function, if the implementation supports
them.

@ref{2006,,可用性}: Unix, not WASI.


在 3.3 版被加入.

@end deffn

@geindex SF_NOCACHE (於 os 模組中)
@anchor{library/os os SF_NOCACHE}@anchor{2f1a}
@deffn {資料} os.SF_NOCACHE

Parameter to the @ref{cfd,,sendfile()} function, if the implementation supports
it. The data won't be cached in the virtual memory and will be freed afterwards.

@ref{2006,,可用性}: Unix, not WASI.


在 3.11 版被加入.

@end deffn

@geindex set_blocking() (於 os 模組中)
@anchor{library/os os set_blocking}@anchor{1035}
@deffn {函式} os.set_blocking (fd, blocking, /)

Set the blocking mode of the specified file descriptor. Set the
@ref{1036,,O_NONBLOCK} flag if blocking is @code{False}, clear the flag otherwise.

另請參閱 @ref{1034,,get_blocking()} 與 @ref{2eee,,socket.socket.setblocking()}。

@ref{2006,,可用性}: Unix, Windows.

The function is limited on WASI, see @ref{1a99,,WebAssembly 平台} for more
information.

On Windows, this function is limited to pipes.


在 3.5 版被加入.



在 3.12 版的變更: 新增對 Windows 上的 pipe 支援。

@end deffn

@geindex splice() (於 os 模組中)
@anchor{library/os os splice}@anchor{a13}
@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{2f1b,,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{2f1c,,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{2f1d,,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{2c0,,OSError} is raised with
@ref{2599,,errno} set to @ref{2eec,,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 也參考


@code{splice(2)@footnote{https://manpages.debian.org/splice(2)}} 使用手冊。


@ref{2006,,可用性}: Linux >= 2.6.17 with glibc >= 2.5


在 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{2f1b}
@deffn {資料} os.SPLICE_F_MOVE
@anchor{library/os os SPLICE_F_NONBLOCK}@anchor{2f1c}
@deffnx {資料} os.SPLICE_F_NONBLOCK
@anchor{library/os os SPLICE_F_MORE}@anchor{2f1d}
@deffnx {資料} os.SPLICE_F_MORE


在 3.10 版被加入.

@end deffn

@geindex readv() (於 os 模組中)
@anchor{library/os os readv}@anchor{d4d}
@deffn {函式} os.readv (fd, buffers, /)

Read from a file descriptor `fd' into a number of mutable @ref{193,,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{185a,,sysconf()} value
@code{'SC_IOV_MAX'}) on the number of buffers that can be used.

@ref{2006,,可用性}: Unix.


在 3.3 版被加入.

@end deffn

@geindex tcgetpgrp() (於 os 模組中)
@anchor{library/os os tcgetpgrp}@anchor{2f1e}
@deffn {函式} os.tcgetpgrp (fd, /)

Return the process group associated with the terminal given by `fd' (an open
file descriptor as returned by @ref{f8d,,os.open()}).

@ref{2006,,可用性}: Unix, not WASI.
@end deffn

@geindex tcsetpgrp() (於 os 模組中)
@anchor{library/os os tcsetpgrp}@anchor{2f1f}
@deffn {函式} os.tcsetpgrp (fd, pg, /)

Set the process group associated with the terminal given by `fd' (an open file
descriptor as returned by @ref{f8d,,os.open()}) to `pg'.

@ref{2006,,可用性}: Unix, not WASI.
@end deffn

@geindex ttyname() (於 os 模組中)
@anchor{library/os os ttyname}@anchor{2f20}
@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{2006,,可用性}: Unix.
@end deffn

@geindex unlockpt() (於 os 模組中)
@anchor{library/os os unlockpt}@anchor{194e}
@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{2006,,可用性}: Unix, not WASI.


在 3.13 版被加入.

@end deffn

@geindex write() (於 os 模組中)
@anchor{library/os os write}@anchor{f96}
@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{f8d,,os.open()} or @ref{1a93,,pipe()}.  To write a "file
object" returned by the built-in function @ref{315,,open()} or by @ref{319,,popen()} or
@ref{2232,,fdopen()}, or @ref{cc4,,sys.stdout} or @ref{b2a,,sys.stderr}, use its
@code{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{f83,,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{d50}
@deffn {函式} os.writev (fd, buffers, /)

Write the contents of `buffers' to file descriptor `fd'. `buffers' must be
a sequence of @ref{193,,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{185a,,sysconf()} value
@code{'SC_IOV_MAX'}) on the number of buffers that can be used.

@ref{2006,,可用性}: Unix.


在 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{2f21}@anchor{library/os terminal-size}@anchor{2f22}
@subsubsection Querying the size of a terminal



在 3.3 版被加入.


@geindex get_terminal_size() (於 os 模組中)
@anchor{library/os os get_terminal_size}@anchor{1303}
@deffn {函式} os.get_terminal_size (fd=STDOUT_FILENO, /)

Return the size of the terminal window as @code{(columns, lines)},
tuple of type @ref{2baf,,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{2c0,,OSError}
is raised.

@ref{1304,,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{2006,,可用性}: Unix, Windows.
@end deffn

@geindex terminal_size (os 中的類別)
@anchor{library/os os terminal_size}@anchor{2baf}
@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{2f23}
@deffn {屬性} columns

Width of the terminal window in characters.
@end deffn

@geindex lines (os.terminal_size 的屬性)
@anchor{library/os os terminal_size lines}@anchor{2f24}
@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{10f7}@anchor{library/os inheritance-of-file-descriptors}@anchor{2f25}
@subsubsection Inheritance of File Descriptors



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

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{31a,,spawn*} functions,
all inheritable handles and all inheritable file descriptors are inherited.
Using the @ref{dc,,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{10f8}
@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{10f9}
@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{10fa}
@deffn {函式} os.get_handle_inheritable (handle, /)

Get the "inheritable" flag of the specified handle (a boolean).

@ref{2006,,可用性}: Windows.
@end deffn

@geindex set_handle_inheritable() (於 os 模組中)
@anchor{library/os os set_handle_inheritable}@anchor{10fb}
@deffn {函式} os.set_handle_inheritable (handle, inheritable, /)

Set the "inheritable" flag of the specified handle.

@ref{2006,,可用性}: Windows.
@end deffn

@node Files and Directories,行程管理,File Descriptor Operations,os --- 各種作業系統介面
@anchor{library/os files-and-directories}@anchor{2f26}@anchor{library/os os-file-dir}@anchor{2ebc}
@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{d4b}

@itemize *

@item 
`specifying a file descriptor:'
Normally the `path' argument provided to functions in the @ref{a5,,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{12fe,,os.supports_fd}.
If this functionality is unavailable, using it will raise a
@ref{369,,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{12eb}

@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{12f8,,os.supports_dir_fd}.  If it's unavailable,
using it will raise a @ref{369,,NotImplementedError}.
@end itemize
@anchor{library/os follow-symlinks}@anchor{12ec}

@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{12f9,,os.supports_follow_symlinks}.
If it's unavailable, using it will raise a @ref{369,,NotImplementedError}.
@end itemize

@geindex access() (於 os 模組中)
@anchor{library/os os access}@anchor{12ed}
@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{2f27,,F_OK} to test the existence of `path', or it
can be the inclusive OR of one or more of @ref{2f28,,R_OK}, @ref{2f29,,W_OK}, and
@ref{2f2a,,X_OK} to test permissions.  Return @ref{e02,,True} if access is allowed,
@ref{d23,,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{12eb,,paths relative to directory descriptors} and @ref{12ec,,not following symlinks}.

If `effective_ids' is @code{True}, @ref{12ed,,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{12ff,,os.supports_effective_ids}.  If it is
unavailable, using it will raise a @ref{369,,NotImplementedError}.

@cartouche
@quotation 備註 
Using @ref{12ed,,access()} to check if a user is authorized to e.g. open a file
before actually doing so using @ref{315,,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{2f2b,,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 @ref{12ed,,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 版的變更: 新增 `dir_fd'、`effective_ids' 與 `follow_symlinks' 參數。



在 3.6 版的變更: Accepts a @ref{59b,,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{2f27}
@deffn {資料} os.F_OK
@anchor{library/os os R_OK}@anchor{2f28}
@deffnx {資料} os.R_OK
@anchor{library/os os W_OK}@anchor{2f29}
@deffnx {資料} os.W_OK
@anchor{library/os os X_OK}@anchor{2f2a}
@deffnx {資料} os.X_OK

Values to pass as the `mode' parameter of @ref{12ed,,access()} to test the
existence, readability, writability and executability of `path',
respectively.
@end deffn

@geindex chdir() (於 os 模組中)
@anchor{library/os os chdir}@anchor{81a}
@deffn {函式} os.chdir (path)

@geindex directory（目錄）;changing（改變）

Change the current working directory to `path'.

This function can support @ref{d4b,,specifying a file descriptor}.  The
descriptor must refer to an opened directory, not an open file.

This function can raise @ref{2c0,,OSError} and subclasses such as
@ref{264,,FileNotFoundError}, @ref{f39,,PermissionError}, and @ref{1255,,NotADirectoryError}.

引發一個附帶引數 @code{path} 的@ref{1b70,,稽核事件} @code{os.chdir}。


在 3.3 版的變更: Added support for specifying `path' as a file descriptor
on some platforms.



在 3.6 版的變更: Accepts a @ref{59b,,path-like object}.

@end deffn

@geindex chflags() (於 os 模組中)
@anchor{library/os os chflags}@anchor{12ee}
@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{d6,,stat} module):


@itemize *

@item 
@ref{2b3b,,stat.UF_NODUMP}

@item 
@ref{2b3c,,stat.UF_IMMUTABLE}

@item 
@ref{2b3d,,stat.UF_APPEND}

@item 
@ref{2b3e,,stat.UF_OPAQUE}

@item 
@ref{2b3f,,stat.UF_NOUNLINK}

@item 
@ref{2b40,,stat.UF_COMPRESSED}

@item 
@ref{2b43,,stat.UF_HIDDEN}

@item 
@ref{2b47,,stat.SF_ARCHIVED}

@item 
@ref{2b48,,stat.SF_IMMUTABLE}

@item 
@ref{2b49,,stat.SF_APPEND}

@item 
@ref{2b4b,,stat.SF_NOUNLINK}

@item 
@ref{2b4c,,stat.SF_SNAPSHOT}
@end itemize

This function can support @ref{12ec,,not following symlinks}.

引發一個附帶引數 @code{path}、@code{flags} 的@ref{1b70,,稽核事件} @code{os.chflags}。

@ref{2006,,可用性}: Unix, not WASI.


在 3.3 版的變更: 新增 `follow_symlinks' 參數。



在 3.6 版的變更: Accepts a @ref{59b,,path-like object}.

@end deffn

@geindex chmod() (於 os 模組中)
@anchor{library/os os chmod}@anchor{524}
@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{d6,,stat} module) or bitwise ORed
combinations of them:


@itemize *

@item 
@ref{2b27,,stat.S_ISUID}

@item 
@ref{2b28,,stat.S_ISGID}

@item 
@ref{2b2a,,stat.S_ENFMT}

@item 
@ref{2b2b,,stat.S_ISVTX}

@item 
@ref{2b37,,stat.S_IREAD}

@item 
@ref{2b38,,stat.S_IWRITE}

@item 
@ref{2b39,,stat.S_IEXEC}

@item 
@ref{2b2c,,stat.S_IRWXU}

@item 
@ref{2b2d,,stat.S_IRUSR}

@item 
@ref{2b2e,,stat.S_IWUSR}

@item 
@ref{2b2f,,stat.S_IXUSR}

@item 
@ref{2b30,,stat.S_IRWXG}

@item 
@ref{2b31,,stat.S_IRGRP}

@item 
@ref{2b32,,stat.S_IWGRP}

@item 
@ref{2b29,,stat.S_IXGRP}

@item 
@ref{2b33,,stat.S_IRWXO}

@item 
@ref{2b34,,stat.S_IROTH}

@item 
@ref{2b35,,stat.S_IWOTH}

@item 
@ref{2b36,,stat.S_IXOTH}
@end itemize

This function can support @ref{d4b,,specifying a file descriptor},
@ref{12eb,,paths relative to directory descriptors} and @ref{12ec,,not following symlinks}.

@cartouche
@quotation 備註 
Although Windows supports @ref{524,,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{1a99,,WebAssembly 平台} for more
information.
@end quotation
@end cartouche

引發一個附帶引數 @code{path}、@code{mode}、@code{dir_fd} 的@ref{1b70,,稽核事件} @code{os.chmod}。


在 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{59b,,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{12ef}
@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{d4b,,specifying a file descriptor},
@ref{12eb,,paths relative to directory descriptors} and @ref{12ec,,not following symlinks}.

See @ref{543,,shutil.chown()} for a higher-level function that accepts names in
addition to numeric ids.

引發一個附帶引數 @code{path}、@code{uid}、@code{gid}、@code{dir_fd} 的@ref{1b70,,稽核事件} @code{os.chown}。

@ref{2006,,可用性}: Unix.

The function is limited on WASI, see @ref{1a99,,WebAssembly 平台} 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{59b,,path-like object}.

@end deffn

@geindex chroot() (於 os 模組中)
@anchor{library/os os chroot}@anchor{1c45}
@deffn {函式} os.chroot (path)

Change the root directory of the current process to `path'.

@ref{2006,,可用性}: Unix, not WASI, not Android.


在 3.6 版的變更: Accepts a @ref{59b,,path-like object}.

@end deffn

@geindex fchdir() (於 os 模組中)
@anchor{library/os os fchdir}@anchor{f84}
@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)}.

引發一個附帶引數 @code{path} 的@ref{1b70,,稽核事件} @code{os.chdir}。

@ref{2006,,可用性}: Unix.
@end deffn

@geindex getcwd() (於 os 模組中)
@anchor{library/os os getcwd}@anchor{1874}
@deffn {函式} os.getcwd ()

Return a string representing the current working directory.
@end deffn

@geindex getcwdb() (於 os 模組中)
@anchor{library/os os getcwdb}@anchor{c79}
@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{2f2c}
@deffn {函式} os.lchflags (path, flags)

Set the flags of `path' to the numeric `flags', like @ref{12ee,,chflags()}, but do
not follow symbolic links.  As of Python 3.3, this is equivalent to
@code{os.chflags(path, flags, follow_symlinks=False)}.

引發一個附帶引數 @code{path}、@code{flags} 的@ref{1b70,,稽核事件} @code{os.chflags}。

@ref{2006,,可用性}: Unix, not WASI.


在 3.6 版的變更: Accepts a @ref{59b,,path-like object}.

@end deffn

@geindex lchmod() (於 os 模組中)
@anchor{library/os os lchmod}@anchor{523}
@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{524,,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.

引發一個附帶引數 @code{path}、@code{mode}、@code{dir_fd} 的@ref{1b70,,稽核事件} @code{os.chmod}。

@ref{2006,,可用性}: Unix, Windows, not Linux, FreeBSD >= 1.3, NetBSD >= 1.3, not OpenBSD


在 3.6 版的變更: Accepts a @ref{59b,,path-like object}.



在 3.13 版的變更: 新增對 Windows 的支援。

@end deffn

@geindex lchown() (於 os 模組中)
@anchor{library/os os lchown}@anchor{2f2d}
@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)}.

引發一個附帶引數 @code{path}、@code{uid}、@code{gid}、@code{dir_fd} 的@ref{1b70,,稽核事件} @code{os.chown}。

@ref{2006,,可用性}: Unix.


在 3.6 版的變更: Accepts a @ref{59b,,path-like object}.

@end deffn

@geindex link() (於 os 模組中)
@anchor{library/os os link}@anchor{12f0}
@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{12eb,,paths relative to directory descriptors}, and @ref{12ec,,not following symlinks}.
The default value of `follow_symlinks' is @code{False} on Windows.

引發一個附帶引數 @code{src}、@code{dst}、@code{src_dir_fd}、@code{dst_dir_fd} 的@ref{1b70,,稽核事件} @code{os.link}。

@ref{2006,,可用性}: Unix, Windows.


在 3.2 版的變更: 新支援 Windows。



在 3.3 版的變更: 新增 `src_dir_fd'、`dst_dir_fd' 與 `follow_symlinks' 參數。



在 3.6 版的變更: Accepts a @ref{59b,,path-like object} for `src' and `dst'.

@end deffn

@geindex listdir() (於 os 模組中)
@anchor{library/os os listdir}@anchor{12fb}
@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{59b,,path-like object}.  If `path' is of type @code{bytes}
(directly or indirectly through the @ref{e46,,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{d4b,,specifying a file descriptor}; the file descriptor must refer to a directory.

引發一個附帶引數 @code{path} 的@ref{1b70,,稽核事件} @code{os.listdir}。

@cartouche
@quotation 備註 
To encode @code{str} filenames to @code{bytes}, use @ref{e4a,,fsencode()}.
@end quotation
@end cartouche


@subsubheading 也參考


The @ref{c4b,,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{59b,,path-like object}.

@end deffn

@geindex listdrives() (於 os 模組中)
@anchor{library/os os listdrives}@anchor{6be}
@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{2c0,,OSError} if an error occurs collecting the drive
names.

引發一個不附帶引數的@ref{1b70,,稽核事件} @code{os.listdrives}。

@ref{2006,,可用性}: Windows


在 3.12 版被加入.

@end deffn

@geindex listmounts() (於 os 模組中)
@anchor{library/os os listmounts}@anchor{6c0}
@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{6bf,,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{2c0,,OSError} if the volume is not recognized or if an error
occurs collecting the paths.

引發一個附帶引數 @code{volume} 的@ref{1b70,,稽核事件} @code{os.listmounts}。

@ref{2006,,可用性}: Windows


在 3.12 版被加入.

@end deffn

@geindex listvolumes() (於 os 模組中)
@anchor{library/os os listvolumes}@anchor{6bf}
@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{6c0,,os.listmounts()}.

May raise @ref{2c0,,OSError} if an error occurs collecting the volumes.

引發一個不附帶引數的@ref{1b70,,稽核事件} @code{os.listvolumes}。

@ref{2006,,可用性}: Windows


在 3.12 版被加入.

@end deffn

@geindex lstat() (於 os 模組中)
@anchor{library/os os lstat}@anchor{6c1}
@deffn {函式} os.lstat (path, *, dir_fd=None)

Perform the equivalent of an @code{lstat()} system call on the given path.
Similar to @ref{26d,,stat()}, but does not follow symbolic links. Return a
@ref{16b5,,stat_result} object.

On platforms that do not support symbolic links, this is an alias for
@ref{26d,,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{12eb,,paths relative to directory descriptors}.


@subsubheading 也參考


The @ref{26d,,stat()} function.



在 3.2 版的變更: Added support for Windows 6.0 (Vista) symbolic links.



在 3.3 版的變更: 新增 `dir_fd' 參數。



在 3.6 版的變更: Accepts a @ref{59b,,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{26d,,stat()}.

@end deffn

@geindex mkdir() (於 os 模組中)
@anchor{library/os os mkdir}@anchor{526}
@deffn {函式} os.mkdir (path, mode=0o777, *, dir_fd=None)

Create a directory named `path' with numeric mode `mode'.

If the directory already exists, @ref{121b,,FileExistsError} is raised. If a parent
directory in the path does not exist, @ref{264,,FileNotFoundError} is raised.
@anchor{library/os mkdir-modebits}@anchor{2f2e}
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{524,,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{12eb,,paths relative to directory descriptors}.

It is also possible to create temporary directories; see the
@ref{e6,,tempfile} module's @ref{528,,tempfile.mkdtemp()} function.

引發一個附帶引數 @code{path}、@code{mode}、@code{dir_fd} 的@ref{1b70,,稽核事件} @code{os.mkdir}。


在 3.3 版的變更: 新增 `dir_fd' 參數。



在 3.6 版的變更: Accepts a @ref{59b,,path-like object}.



在 3.13 版的變更: Windows now handles a `mode' of @code{0o700}.

@end deffn

@geindex makedirs() (於 os 模組中)
@anchor{library/os os makedirs}@anchor{527}
@deffn {函式} os.makedirs (name, mode=0o777, exist_ok=False)

@geindex directory（目錄）;creating（建立）
@geindex UNC paths（UNC 路徑）;以及 os.makedirs()

Recursive directory creation function.  Like @ref{526,,mkdir()}, but makes all
intermediate-level directories needed to contain the leaf directory.

The `mode' parameter is passed to @ref{526,,mkdir()} for creating the leaf
directory; see @ref{2f2e,,the mkdir() description} for how it
is interpreted.  To set the file permission bits of any newly created parent
directories you can set the umask before invoking @ref{527,,makedirs()}.  The
file permission bits of existing parent directories are not changed.

If `exist_ok' is @code{False} (the default), a @ref{121b,,FileExistsError} is
raised if the target directory already exists.

@cartouche
@quotation 備註 
@ref{527,,makedirs()} will become confused if the path elements to create
include @ref{2f2f,,pardir} (eg. ".." on UNIX systems).
@end quotation
@end cartouche

This function handles UNC paths correctly.

引發一個附帶引數 @code{path}、@code{mode}、@code{dir_fd} 的@ref{1b70,,稽核事件} @code{os.mkdir}。


在 3.2 版的變更: 新增 `exist_ok' 參數。



在 3.4.1 版的變更: Before Python 3.4.1, if `exist_ok' was @code{True} and the directory existed,
@ref{527,,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{59b,,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{f8b}
@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{12eb,,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{12f6,,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 @ref{f8b,,mkfifo()}
doesn't open the FIFO --- it just creates the rendezvous point.

@ref{2006,,可用性}: Unix, not WASI.


在 3.3 版的變更: 新增 `dir_fd' 參數。



在 3.6 版的變更: Accepts a @ref{59b,,path-like object}.

@end deffn

@geindex mknod() (於 os 模組中)
@anchor{library/os os mknod}@anchor{f8c}
@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 @code{stat.S_IFREG},
@code{stat.S_IFCHR}, @code{stat.S_IFBLK}, and @code{stat.S_IFIFO} (those constants are
available in @ref{d6,,stat}).  For @code{stat.S_IFCHR} and @code{stat.S_IFBLK},
`device' defines the newly created device special file (probably using
@ref{18c7,,os.makedev()}), otherwise it is ignored.

This function can also support @ref{12eb,,paths relative to directory descriptors}.

@ref{2006,,可用性}: Unix, not WASI.


在 3.3 版的變更: 新增 `dir_fd' 參數。



在 3.6 版的變更: Accepts a @ref{59b,,path-like object}.

@end deffn

@geindex major() (於 os 模組中)
@anchor{library/os os major}@anchor{18c5}
@deffn {函式} os.major (device, /)

Extract the device major number from a raw device number (usually the
@code{st_dev} or @code{st_rdev} field from @code{stat}).
@end deffn

@geindex minor() (於 os 模組中)
@anchor{library/os os minor}@anchor{18c6}
@deffn {函式} os.minor (device, /)

Extract the device minor number from a raw device number (usually the
@code{st_dev} or @code{st_rdev} field from @code{stat}).
@end deffn

@geindex makedev() (於 os 模組中)
@anchor{library/os os makedev}@anchor{18c7}
@deffn {函式} os.makedev (major, minor, /)

Compose a raw device number from the major and minor device numbers.
@end deffn

@geindex pathconf() (於 os 模組中)
@anchor{library/os os pathconf}@anchor{12fc}
@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{2eb,,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{2c0,,OSError} is raised with
@ref{1c9b,,errno.EINVAL} for the error number.

This function can support @ref{d4b,,specifying a file descriptor}.

@ref{2006,,可用性}: Unix.


在 3.6 版的變更: Accepts a @ref{59b,,path-like object}.

@end deffn

@geindex pathconf_names (於 os 模組中)
@anchor{library/os os pathconf_names}@anchor{2f30}
@deffn {資料} os.pathconf_names

Dictionary mapping names accepted by @ref{12fc,,pathconf()} and @ref{2eed,,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{2006,,可用性}: Unix.
@end deffn

@geindex readlink() (於 os 模組中)
@anchor{library/os os readlink}@anchor{b11}
@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{e46,,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{12eb,,paths relative to directory descriptors}.

When trying to resolve a path that may contain links, use
@ref{262,,realpath()} to properly handle recursion and platform
differences.

@ref{2006,,可用性}: Unix, Windows.


在 3.2 版的變更: Added support for Windows 6.0 (Vista) symbolic links.



在 3.3 版的變更: 新增 `dir_fd' 參數。



在 3.6 版的變更: Accepts a @ref{59b,,path-like object} on Unix.



在 3.8 版的變更: Accepts a @ref{59b,,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{12f1}
@deffn {函式} os.remove (path, *, dir_fd=None)

Remove (delete) the file `path'.  If `path' is a directory, an
@ref{2c0,,OSError} is raised.  Use @ref{12f4,,rmdir()} to remove directories.
If the file does not exist, a @ref{264,,FileNotFoundError} is raised.

This function can support @ref{12eb,,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{12f6,,unlink()}.

引發一個附帶引數 @code{path}、@code{dir_fd} 的@ref{1b70,,稽核事件} @code{os.remove}。


在 3.3 版的變更: 新增 `dir_fd' 參數。



在 3.6 版的變更: Accepts a @ref{59b,,path-like object}.

@end deffn

@geindex removedirs() (於 os 模組中)
@anchor{library/os os removedirs}@anchor{2f31}
@deffn {函式} os.removedirs (name)

@geindex directory（目錄）;deleting（刪除）

Remove directories recursively.  Works like @ref{12f4,,rmdir()} except that, if the
leaf directory is successfully removed, @ref{2f31,,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{2c0,,OSError} if the leaf directory could not be
successfully removed.

引發一個附帶引數 @code{path}、@code{dir_fd} 的@ref{1b70,,稽核事件} @code{os.remove}。


在 3.6 版的變更: Accepts a @ref{59b,,path-like object}.

@end deffn

@geindex rename() (於 os 模組中)
@anchor{library/os os rename}@anchor{12f2}
@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{2c0,,OSError} subclass in a number of cases:

On Windows, if `dst' exists a @ref{121b,,FileExistsError} is always raised.
The operation may fail if `src' and `dst' are on different filesystems. Use
@ref{c48,,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{1254,,IsADirectoryError} or a @ref{1255,,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{2c0,,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{12eb,,paths relative to directory descriptors}.

If you want cross-platform overwriting of the destination, use @ref{12f3,,replace()}.

引發一個附帶引數 @code{src}、@code{dst}、@code{src_dir_fd}、@code{dst_dir_fd} 的@ref{1b70,,稽核事件} @code{os.rename}。


在 3.3 版的變更: 新增 `src_dir_fd' 與 `dst_dir_fd' 參數。



在 3.6 版的變更: Accepts a @ref{59b,,path-like object} for `src' and `dst'.

@end deffn

@geindex renames() (於 os 模組中)
@anchor{library/os os renames}@anchor{2f32}
@deffn {函式} os.renames (old, new)

Recursive directory or file renaming function. Works like @ref{12f2,,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{2f31,,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

引發一個附帶引數 @code{src}、@code{dst}、@code{src_dir_fd}、@code{dst_dir_fd} 的@ref{1b70,,稽核事件} @code{os.rename}。


在 3.6 版的變更: Accepts a @ref{59b,,path-like object} for `old' and `new'.

@end deffn

@geindex replace() (於 os 模組中)
@anchor{library/os os replace}@anchor{12f3}
@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{2c0,,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{12eb,,paths relative to directory descriptors}.

引發一個附帶引數 @code{src}、@code{dst}、@code{src_dir_fd}、@code{dst_dir_fd} 的@ref{1b70,,稽核事件} @code{os.rename}。


在 3.3 版被加入.



在 3.6 版的變更: Accepts a @ref{59b,,path-like object} for `src' and `dst'.

@end deffn

@geindex rmdir() (於 os 模組中)
@anchor{library/os os rmdir}@anchor{12f4}
@deffn {函式} os.rmdir (path, *, dir_fd=None)

Remove (delete) the directory `path'.  If the directory does not exist or is
not empty, a @ref{264,,FileNotFoundError} or an @ref{2c0,,OSError} is raised
respectively.  In order to remove whole directory trees,
@ref{354,,shutil.rmtree()} can be used.

This function can support @ref{12eb,,paths relative to directory descriptors}.

引發一個附帶引數 @code{path}、@code{dir_fd} 的@ref{1b70,,稽核事件} @code{os.rmdir}。


在 3.3 版的變更: 新增 `dir_fd' 參數。



在 3.6 版的變更: Accepts a @ref{59b,,path-like object}.

@end deffn

@geindex scandir() (於 os 模組中)
@anchor{library/os os scandir}@anchor{c4b}
@deffn {函式} os.scandir (path='.')

Return an iterator of @ref{6bc,,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 @ref{c4b,,scandir()} instead of @ref{12fb,,listdir()} can significantly
increase the performance of code that also needs file type or file
attribute information, because @ref{6bc,,os.DirEntry} objects expose this
information if the operating system provides it when scanning a directory.
All @ref{6bc,,os.DirEntry} methods may perform a system call, but
@ref{2f33,,is_dir()} and @ref{f7f,,is_file()} usually only
require a system call for symbolic links; @ref{19bd,,os.DirEntry.stat()}
always requires a system call on Unix but only requires one for
symbolic links on Windows.

`path' may be a @ref{59b,,path-like object}.  If `path' is of type @code{bytes}
(directly or indirectly through the @ref{e46,,PathLike} interface),
the type of the @ref{2f34,,name} and @ref{1947,,path}
attributes of each @ref{6bc,,os.DirEntry} will be @code{bytes}; in all other
circumstances, they will be of type @code{str}.

This function can also support @ref{d4b,,specifying a file descriptor}; the file descriptor must refer to a directory.

引發一個附帶引數 @code{path} 的@ref{1b70,,稽核事件} @code{os.scandir}。

@ref{c4b,,scandir()} 疊代器支援 @ref{1e1,,context manager} 協定，並具有以下方法：

@geindex close() (os.scandir 的方法)
@anchor{library/os os scandir close}@anchor{eb3}
@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{186,,with}
statement.


在 3.6 版被加入.

@end deffn

The following example shows a simple use of @ref{c4b,,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, @ref{c4b,,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


在 3.5 版被加入.



在 3.6 版的變更: Added support for the @ref{1e1,,context manager} protocol and the
@ref{eb3,,close()} method.  If a @ref{c4b,,scandir()} iterator is neither
exhausted nor explicitly closed a @ref{547,,ResourceWarning} will be emitted
in its destructor.

The function accepts a @ref{59b,,path-like object}.



在 3.7 版的變更: 新增對 Unix 上的@ref{d4b,,檔案描述器}的支援。

@end deffn

@geindex DirEntry (os 中的類別)
@anchor{library/os os DirEntry}@anchor{6bc}
@deffn {類別} os.DirEntry

Object yielded by @ref{c4b,,scandir()} to expose the file path and other file
attributes of a directory entry.

@ref{c4b,,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{c4b,,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{2c0,,OSError}. If you need very fine-grained
control over errors, you can catch @ref{2c0,,OSError} when calling one of the
@code{os.DirEntry} methods and handle as appropriate.

To be directly usable as a @ref{59b,,path-like object}, @code{os.DirEntry}
implements the @ref{e46,,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{2f34}
@deffn {屬性} name

The entry's base filename, relative to the @ref{c4b,,scandir()} `path'
argument.

The @ref{2eb5,,name} attribute will be @code{bytes} if the @ref{c4b,,scandir()}
`path' argument is of type @code{bytes} and @code{str} otherwise.  Use
@ref{e49,,fsdecode()} to decode byte filenames.
@end deffn

@geindex path (os.DirEntry 的屬性)
@anchor{library/os os DirEntry path}@anchor{1947}
@deffn {屬性} path

The entry's full path name: equivalent to @code{os.path.join(scandir_path,
entry.name)} where `scandir_path' is the @ref{c4b,,scandir()} `path'
argument.  The path is only absolute if the @ref{c4b,,scandir()} `path'
argument was absolute.  If the @ref{c4b,,scandir()} `path'
argument was a @ref{d4b,,file descriptor}, the @ref{a6,,path}
attribute is the same as the @ref{2eb5,,name} attribute.

The @ref{a6,,path} attribute will be @code{bytes} if the @ref{c4b,,scandir()}
`path' argument is of type @code{bytes} and @code{str} otherwise.  Use
@ref{e49,,fsdecode()} to decode byte filenames.
@end deffn

@geindex inode() (os.DirEntry 的方法)
@anchor{library/os os DirEntry inode}@anchor{199e}
@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{2f33}
@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{26d,,os.stat()} along
with @ref{2b0e,,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{2c0,,OSError}, such as @ref{f39,,PermissionError},
but @ref{264,,FileNotFoundError} is caught and not raised.
@end deffn

@geindex is_file() (os.DirEntry 的方法)
@anchor{library/os os DirEntry is_file}@anchor{f7f}
@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{2f33,,is_dir()}.
@end deffn

@geindex is_symlink() (os.DirEntry 的方法)
@anchor{library/os os DirEntry is_symlink}@anchor{2f35}
@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{bf8,,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{2c0,,OSError}, such as @ref{f39,,PermissionError},
but @ref{264,,FileNotFoundError} is caught and not raised.
@end deffn

@geindex is_junction() (os.DirEntry 的方法)
@anchor{library/os os DirEntry is_junction}@anchor{6bd}
@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{6c3,,os.path.isjunction()} to fetch up-to-date information.


在 3.12 版被加入.

@end deffn

@geindex stat() (os.DirEntry 的方法)
@anchor{library/os os DirEntry stat}@anchor{19bd}
@deffn {方法} stat (*, follow_symlinks=True)

Return a @ref{16b5,,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{16b5,,stat_result} are always set to zero. Call @ref{26d,,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{26d,,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{266,,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.


在 3.5 版被加入.



在 3.6 版的變更: Added support for the @ref{e46,,PathLike} interface.  Added support
for @ref{192,,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{26d}
@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{e46,,PathLike}
interface -- or as an open file descriptor. Return a @ref{16b5,,stat_result}
object.

This function normally follows symlinks; to stat a symlink add the argument
@code{follow_symlinks=False}, or use @ref{6c1,,lstat()}.

This function can support @ref{d4b,,specifying a file descriptor} and
@ref{12ec,,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{262,,os.path.realpath()} function to resolve the path name as far as
possible and call @ref{6c1,,lstat()} on the result. This does not apply to
dangling symlinks or junction points, which will raise the usual exceptions.

@geindex module（模組）;stat

範例：

@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{f87,,fstat()} 和 @ref{6c1,,lstat()} 函式。



在 3.3 版的變更: 新增 `dir_fd' 與 `follow_symlinks' 參數，指定一個檔案描述器而非路徑。



在 3.6 版的變更: Accepts a @ref{59b,,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{16b5}
@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{26d,,os.stat()},
@ref{f87,,os.fstat()} and @ref{6c1,,os.lstat()}.

屬性：

@geindex st_mode (os.stat_result 的屬性)
@anchor{library/os os stat_result st_mode}@anchor{bf6}
@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{2f36}
@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{2f37}
@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{2f38}
@deffn {屬性} st_nlink

Number of hard links.
@end deffn

@geindex st_uid (os.stat_result 的屬性)
@anchor{library/os os stat_result st_uid}@anchor{2f39}
@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{2f3a}
@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{2f3b}
@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{2f3c}
@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{2dc7}
@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{2f3d}
@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{2f3e}
@deffn {屬性} st_atime_ns

Time of most recent access expressed in nanoseconds as an integer.


在 3.3 版被加入.

@end deffn

@geindex st_mtime_ns (os.stat_result 的屬性)
@anchor{library/os os stat_result st_mtime_ns}@anchor{2f3f}
@deffn {屬性} st_mtime_ns

Time of most recent content modification expressed in nanoseconds as an
integer.


在 3.3 版被加入.

@end deffn

@geindex st_ctime_ns (os.stat_result 的屬性)
@anchor{library/os os stat_result st_ctime_ns}@anchor{2f40}
@deffn {屬性} st_ctime_ns

Time of most recent metadata change expressed in nanoseconds as an
integer.


在 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{2f41}
@deffn {屬性} st_birthtime

Time of file creation expressed in seconds. This attribute is not
always available, and may raise @ref{5e8,,AttributeError}.


在 3.12 版的變更: @code{st_birthtime} 現在在 Windows 上可用。

@end deffn

@geindex st_birthtime_ns (os.stat_result 的屬性)
@anchor{library/os os stat_result st_birthtime_ns}@anchor{2f42}
@deffn {屬性} st_birthtime_ns

Time of file creation expressed in nanoseconds as an integer.
This attribute is not always available, and may raise
@ref{5e8,,AttributeError}.


在 3.12 版被加入.

@end deffn

@cartouche
@quotation 備註 
The exact meaning and resolution of the @ref{2f3c,,st_atime},
@ref{2dc7,,st_mtime}, @ref{2f3d,,st_ctime} and @ref{2f41,,st_birthtime} attributes
depend on the operating system and the file system. For example, on
Windows systems using the FAT32 file systems, @ref{2dc7,,st_mtime} has
2-second resolution, and @ref{2f3c,,st_atime} has only 1-day resolution.
See your operating system documentation for details.

Similarly, although @ref{2f3e,,st_atime_ns}, @ref{2f3f,,st_mtime_ns},
@ref{2f40,,st_ctime_ns} and @ref{2f42,,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{2f3c,,st_atime}, @ref{2dc7,,st_mtime}, @ref{2f3d,,st_ctime} and
@ref{2f41,,st_birthtime} cannot preserve all of it, and as such will be
slightly inexact. If you need the exact timestamps you should always use
@ref{2f3e,,st_atime_ns}, @ref{2f3f,,st_mtime_ns}, @ref{2f40,,st_ctime_ns} and
@ref{2f42,,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{2f43}
@deffn {屬性} st_blocks

Number of 512-byte blocks allocated for file.
This may be smaller than @ref{2f3b,,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{2f44}
@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{1755}
@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{2f45}
@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{2f46}
@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{d53}
@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{2f47}
@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{2f48}
@deffn {屬性} st_creator

Creator of the file.
@end deffn

@geindex st_type (os.stat_result 的屬性)
@anchor{library/os os stat_result st_type}@anchor{2f49}
@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{1033}
@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{d6,,stat} module.


在 3.5 版被加入.

@end deffn

@geindex st_reparse_tag (os.stat_result 的屬性)
@anchor{library/os os stat_result st_reparse_tag}@anchor{bf7}
@deffn {屬性} st_reparse_tag

When @ref{1033,,st_file_attributes} has the @ref{2b5b,,FILE_ATTRIBUTE_REPARSE_POINT}
set, this field contains the tag identifying the type of reparse point.
See the @ref{2b60,,IO_REPARSE_TAG_*}
constants in the @ref{d6,,stat} module.
@end deffn

The standard module @ref{d6,,stat} defines functions and constants that are
useful for extracting information from a @code{stat} structure. (On
Windows, some items are filled with dummy values.)

For backward compatibility, a @ref{16b5,,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{bf6,,st_mode}, @ref{2f36,,st_ino}, @ref{2f37,,st_dev}, @ref{2f38,,st_nlink},
@ref{2f39,,st_uid}, @ref{2f3a,,st_gid}, @ref{2f3b,,st_size}, @ref{2f3c,,st_atime},
@ref{2dc7,,st_mtime}, @ref{2f3d,,st_ctime}. More items may be added at the end by
some implementations. For compatibility with older Python versions,
accessing @ref{16b5,,stat_result} as a tuple always returns integers.


在 3.5 版的變更: Windows now returns the file index as @ref{2f36,,st_ino} when
available.



在 3.7 版的變更: Added the @ref{d53,,st_fstype} member to Solaris/derivatives.



在 3.8 版的變更: 在 Windows 上新增 @ref{bf7,,st_reparse_tag} 成員。



在 3.8 版的變更: On Windows, the @ref{bf6,,st_mode} member now identifies special
files as @code{S_IFCHR}, @code{S_IFIFO} or @code{S_IFBLK}
as appropriate.



在 3.12 版的變更: On Windows, @ref{2f3d,,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{2f41,,st_birthtime} for the creation time.

On Windows, @ref{2f36,,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{1755,,st_rdev} no longer returns a value. Previously
it would contain the same as @ref{2f37,,st_dev}, which was incorrect.

在 Windows 上新增 @ref{2f41,,st_birthtime} 成員。

@end deffn

@geindex statvfs() (於 os 模組中)
@anchor{library/os os statvfs}@anchor{12fd}
@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{d4b,,specifying a file descriptor}.

@ref{2006,,可用性}: Unix.


在 3.2 版的變更: 新增 @code{ST_RDONLY} 與 @code{ST_NOSUID} 常數。



在 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{59b,,path-like object}.



在 3.7 版的變更: 新增 @code{f_fsid} 屬性。

@end deffn

@geindex supports_dir_fd (於 os 模組中)
@anchor{library/os os supports_dir_fd}@anchor{12f8}
@deffn {資料} os.supports_dir_fd

A @ref{184,,set} object indicating which functions in the @ref{a5,,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{26d,,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.


在 3.3 版被加入.

@end deffn

@geindex supports_effective_ids (於 os 模組中)
@anchor{library/os os supports_effective_ids}@anchor{12ff}
@deffn {資料} os.supports_effective_ids

A @ref{184,,set} object indicating whether @ref{12ed,,os.access()} permits
specifying @code{True} for its `effective_ids' parameter on the local platform.
(Specifying @code{False} for `effective_ids' is always supported on all
platforms.)  If the local platform supports it, the collection will contain
@ref{12ed,,os.access()}; otherwise it will be empty.

This expression evaluates to @code{True} if @ref{12ed,,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.


在 3.3 版被加入.

@end deffn

@geindex supports_fd (於 os 模組中)
@anchor{library/os os supports_fd}@anchor{12fe}
@deffn {資料} os.supports_fd

A @ref{184,,set} object indicating which functions in the
@ref{a5,,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{81a,,os.chdir()} accepts open file descriptors for `path' on your local
platform:

@example
os.chdir in os.supports_fd
@end example


在 3.3 版被加入.

@end deffn

@geindex supports_follow_symlinks (於 os 模組中)
@anchor{library/os os supports_follow_symlinks}@anchor{12f9}
@deffn {資料} os.supports_follow_symlinks

A @ref{184,,set} object indicating which functions in the @ref{a5,,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{26d,,os.stat()} on the local platform:

@example
os.stat in os.supports_follow_symlinks
@end example


在 3.3 版被加入.

@end deffn

@geindex symlink() (於 os 模組中)
@anchor{library/os os symlink}@anchor{12f5}
@deffn {函式} os.symlink (src, dst, target_is_directory=False, *, dir_fd=None)

Create a symbolic link pointing to `src' named `dst'.

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{12eb,,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{2c0,,OSError} is raised when the function is called by an unprivileged
user.
@end quotation
@end cartouche

引發一個附帶引數 @code{src}、@code{dst}、@code{dir_fd} 的@ref{1b70,,稽核事件} @code{os.symlink}。

@ref{2006,,可用性}: Unix, Windows.

The function is limited on WASI, see @ref{1a99,,WebAssembly 平台} 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{59b,,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{1313}
@deffn {函式} os.sync ()

Force write of everything to disk.

@ref{2006,,可用性}: Unix.


在 3.3 版被加入.

@end deffn

@geindex truncate() (於 os 模組中)
@anchor{library/os os truncate}@anchor{1037}
@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{d4b,,specifying a file descriptor}.

引發一個附帶引數 @code{path}、@code{length} 的@ref{1b70,,稽核事件} @code{os.truncate}。

@ref{2006,,可用性}: Unix, Windows.


在 3.3 版被加入.



在 3.5 版的變更: 新增對 Windows 的支援



在 3.6 版的變更: Accepts a @ref{59b,,path-like object}.

@end deffn

@geindex unlink() (於 os 模組中)
@anchor{library/os os unlink}@anchor{12f6}
@deffn {函式} os.unlink (path, *, dir_fd=None)

Remove (delete) the file `path'.  This function is semantically
identical to @ref{12f1,,remove()}; the @code{unlink} name is its
traditional Unix name.  Please see the documentation for
@ref{12f1,,remove()} for further information.

引發一個附帶引數 @code{path}、@code{dir_fd} 的@ref{1b70,,稽核事件} @code{os.remove}。


在 3.3 版的變更: 新增 `dir_fd' 參數。



在 3.6 版的變更: Accepts a @ref{59b,,path-like object}.

@end deffn

@geindex utime() (於 os 模組中)
@anchor{library/os os utime}@anchor{12f7}
@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'.

@ref{12f7,,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 an int or float expressing seconds.

@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{26d,,stat()} call, depending on the resolution with which your operating
system records access and modification times; see @ref{26d,,stat()}. The best
way to preserve exact times is to use the `st_atime_ns' and `st_mtime_ns'
fields from the @ref{26d,,os.stat()} result object with the `ns' parameter to
@ref{12f7,,utime()}.

This function can support @ref{d4b,,specifying a file descriptor},
@ref{12eb,,paths relative to directory descriptors} and @ref{12ec,,not following symlinks}.

引發一個附帶引數 @code{path}、@code{times}、@code{ns}、@code{dir_fd} 的@ref{1b70,,稽核事件} @code{os.utime}。


在 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{59b,,path-like object}.

@end deffn

@geindex walk() (於 os 模組中)
@anchor{library/os os walk}@anchor{6c9}
@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{1a62,,del} or slice assignment), and @ref{6c9,,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
@ref{6c9,,walk()} about directories the caller creates or renames before it resumes
@ref{6c9,,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{c4b,,scandir()} call are ignored.  If optional
argument `onerror' is specified, it should be a function; it will be called with
one argument, an @ref{2c0,,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, @ref{6c9,,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. @ref{6c9,,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 @ref{6c9,,walk()}.  @ref{6c9,,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{354,,shutil.rmtree()}),
walking the tree bottom-up is essential, @ref{12f4,,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

引發一個附帶引數 @code{top}、@code{topdown}、@code{onerror}、@code{followlinks} 的@ref{1b70,,稽核事件} @code{os.walk}。


在 3.5 版的變更: This function now calls @ref{c4b,,os.scandir()} instead of @ref{12fb,,os.listdir()},
making it faster by reducing the number of calls to @ref{26d,,os.stat()}.



在 3.6 版的變更: Accepts a @ref{59b,,path-like object}.

@end deffn

@geindex fwalk() (於 os 模組中)
@anchor{library/os os fwalk}@anchor{d4a}
@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{6c9,,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{6c9,,walk()} output,
and `dirfd' is a file descriptor referring to the directory `dirpath'.

This function always supports @ref{12eb,,paths relative to directory descriptors} and @ref{12ec,,not following symlinks}.  Note however
that, unlike other functions, the @ref{d4a,,fwalk()} default value for
`follow_symlinks' is @code{False}.

@cartouche
@quotation 備註 
Since @ref{d4a,,fwalk()} yields file descriptors, those are only valid until
the next iteration step, so you should duplicate them (e.g. with
@ref{1c8b,,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{12f4,,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

引發一個附帶引數 @code{top}、@code{topdown}、@code{onerror}、@code{follow_symlinks}、@code{dir_fd} 的@ref{1b70,,稽核事件} @code{os.fwalk}。

@ref{2006,,可用性}: Unix.


在 3.3 版被加入.



在 3.6 版的變更: Accepts a @ref{59b,,path-like object}.



在 3.7 版的變更: 新增對 @ref{192,,bytes} 路徑的支援。

@end deffn

@geindex memfd_create() (於 os 模組中)
@anchor{library/os os memfd_create}@anchor{bf5}
@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{10f7,,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{2006,,可用性}: Linux >= 3.17 with glibc >= 2.27.


在 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{2f4a}
@deffn {資料} os.MFD_CLOEXEC
@anchor{library/os os MFD_ALLOW_SEALING}@anchor{2f4b}
@deffnx {資料} os.MFD_ALLOW_SEALING
@anchor{library/os os MFD_HUGETLB}@anchor{2f4c}
@deffnx {資料} os.MFD_HUGETLB
@anchor{library/os os MFD_HUGE_SHIFT}@anchor{2f4d}
@deffnx {資料} os.MFD_HUGE_SHIFT
@anchor{library/os os MFD_HUGE_MASK}@anchor{2f4e}
@deffnx {資料} os.MFD_HUGE_MASK
@anchor{library/os os MFD_HUGE_64KB}@anchor{2f4f}
@deffnx {資料} os.MFD_HUGE_64KB
@anchor{library/os os MFD_HUGE_512KB}@anchor{2f50}
@deffnx {資料} os.MFD_HUGE_512KB
@anchor{library/os os MFD_HUGE_1MB}@anchor{2f51}
@deffnx {資料} os.MFD_HUGE_1MB
@anchor{library/os os MFD_HUGE_2MB}@anchor{2f52}
@deffnx {資料} os.MFD_HUGE_2MB
@anchor{library/os os MFD_HUGE_8MB}@anchor{2f53}
@deffnx {資料} os.MFD_HUGE_8MB
@anchor{library/os os MFD_HUGE_16MB}@anchor{2f54}
@deffnx {資料} os.MFD_HUGE_16MB
@anchor{library/os os MFD_HUGE_32MB}@anchor{2f55}
@deffnx {資料} os.MFD_HUGE_32MB
@anchor{library/os os MFD_HUGE_256MB}@anchor{2f56}
@deffnx {資料} os.MFD_HUGE_256MB
@anchor{library/os os MFD_HUGE_512MB}@anchor{2f57}
@deffnx {資料} os.MFD_HUGE_512MB
@anchor{library/os os MFD_HUGE_1GB}@anchor{2f58}
@deffnx {資料} os.MFD_HUGE_1GB
@anchor{library/os os MFD_HUGE_2GB}@anchor{2f59}
@deffnx {資料} os.MFD_HUGE_2GB
@anchor{library/os os MFD_HUGE_16GB}@anchor{2f5a}
@deffnx {資料} os.MFD_HUGE_16GB

這些旗標可以傳給 @ref{bf5,,memfd_create()}。

@ref{2006,,可用性}: Linux >= 3.17 with glibc >= 2.27

@code{MFD_HUGE*} 旗標僅在 Linux 4.14 以上可用。


在 3.8 版被加入.

@end deffn

@geindex eventfd() (於 os 模組中)
@anchor{library/os os eventfd}@anchor{a12}
@deffn {函式} os.eventfd (initval[, flags=os.EFD_CLOEXEC])

Create and return an event file descriptor. The file descriptors supports
raw @ref{f90,,read()} and @ref{f96,,write()} with a buffer size of 8,
@ref{f9b,,select()}, @ref{2f5b,,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{10f7,,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{1a87,,EFD_CLOEXEC},
@ref{1a88,,EFD_NONBLOCK}, and @ref{1a89,,EFD_SEMAPHORE}.

If @ref{1a89,,EFD_SEMAPHORE} is specified and the event counter is non-zero,
@ref{2f5c,,eventfd_read()} returns 1 and decrements the counter by one.

If @ref{1a89,,EFD_SEMAPHORE} is not specified and the event counter is
non-zero, @ref{2f5c,,eventfd_read()} returns the current event counter value and
resets the counter to zero.

If the event counter is zero and @ref{1a88,,EFD_NONBLOCK} is not
specified, @ref{2f5c,,eventfd_read()} blocks.

@ref{2f5d,,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
import os

# semaphore with start value '1'
fd = os.eventfd(1, os.EFD_SEMAPHORE | os.EFC_CLOEXEC)
try:
    # acquire semaphore
    v = os.eventfd_read(fd)
    try:
        do_work()
    finally:
        # release semaphore
        os.eventfd_write(fd, v)
finally:
    os.close(fd)
@end example

@ref{2006,,可用性}: Linux >= 2.6.27 with glibc >= 2.8


在 3.10 版被加入.

@end deffn

@geindex eventfd_read() (於 os 模組中)
@anchor{library/os os eventfd_read}@anchor{2f5c}
@deffn {函式} os.eventfd_read (fd)

Read value from an @ref{a12,,eventfd()} file descriptor and return a 64 bit
unsigned int. The function does not verify that `fd' is an @ref{a12,,eventfd()}.

@ref{2006,,可用性}: Linux >= 2.6.27


在 3.10 版被加入.

@end deffn

@geindex eventfd_write() (於 os 模組中)
@anchor{library/os os eventfd_write}@anchor{2f5d}
@deffn {函式} os.eventfd_write (fd, value)

Add value to an @ref{a12,,eventfd()} file descriptor. `value' must be a 64 bit
unsigned int. The function does not verify that `fd' is an @ref{a12,,eventfd()}.

@ref{2006,,可用性}: Linux >= 2.6.27


在 3.10 版被加入.

@end deffn

@geindex EFD_CLOEXEC (於 os 模組中)
@anchor{library/os os EFD_CLOEXEC}@anchor{1a87}
@deffn {資料} os.EFD_CLOEXEC

Set close-on-exec flag for new @ref{a12,,eventfd()} file descriptor.

@ref{2006,,可用性}: Linux >= 2.6.27


在 3.10 版被加入.

@end deffn

@geindex EFD_NONBLOCK (於 os 模組中)
@anchor{library/os os EFD_NONBLOCK}@anchor{1a88}
@deffn {資料} os.EFD_NONBLOCK

設定新的 @ref{a12,,eventfd()} 檔案描述器的 @ref{1036,,O_NONBLOCK} 狀態旗標。

@ref{2006,,可用性}: Linux >= 2.6.27


在 3.10 版被加入.

@end deffn

@geindex EFD_SEMAPHORE (於 os 模組中)
@anchor{library/os os EFD_SEMAPHORE}@anchor{1a89}
@deffn {資料} os.EFD_SEMAPHORE

Provide semaphore-like semantics for reads from an @ref{a12,,eventfd()} file
descriptor. On read the internal counter is decremented by one.

@ref{2006,,可用性}: Linux >= 2.6.30


在 3.10 版被加入.

@end deffn

@menu
* 計時器檔案描述器:: 
* Linux extended attributes:: 

@end menu

@node 計時器檔案描述器,Linux extended attributes,,Files and Directories
@anchor{library/os os-timerfd}@anchor{478}@anchor{library/os timer-file-descriptors}@anchor{2f5e}
@subsubsection 計時器檔案描述器



在 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{51a}
@deffn {函式} os.timerfd_create (clockid, /, *, flags=0)

Create and return a timer file descriptor (`timerfd').

The file descriptor returned by @ref{51a,,timerfd_create()} supports:


@itemize -

@item 
@ref{f90,,read()}

@item 
@ref{f9b,,select()}

@item 
@ref{2f5b,,poll()}
@end itemize

The file descriptor's @ref{f90,,read()} method can be called with a buffer size
of 8. If the timer has already expired one or more times, @ref{f90,,read()}
returns the number of expirations with the host's endianness, which may be
converted to an @ref{19b,,int} by @code{int.from_bytes(x, byteorder=sys.byteorder)}.

@ref{f9b,,select()} and @ref{2f5b,,poll()} can be used to wait until
timer expires and the file descriptor is readable.

`clockid' must be a valid @ref{2f5f,,clock ID},
as defined in the @ref{f4,,time} module:


@itemize -

@item 
@ref{8a1,,time.CLOCK_REALTIME}

@item 
@ref{d82,,time.CLOCK_MONOTONIC}

@item 
@ref{d81,,time.CLOCK_BOOTTIME} (Since Linux 3.15 for timerfd_create)
@end itemize

If `clockid' is @ref{8a1,,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{522,,TFD_TIMER_CANCEL_ON_SET}.

If `clockid' is @ref{d82,,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{d81,,time.CLOCK_BOOTTIME}, same as @ref{d82,,time.CLOCK_MONOTONIC}
except it includes any time that the system is suspended.

The file descriptor's behaviour can be modified by specifying a `flags' value.
Any of the following variables may used, combined using bitwise OR
(the @code{|} operator):


@itemize -

@item 
@ref{51f,,TFD_NONBLOCK}

@item 
@ref{520,,TFD_CLOEXEC}
@end itemize

If @ref{51f,,TFD_NONBLOCK} is not set as a flag, @ref{f90,,read()} blocks until
the timer expires. If it is set as a flag, @ref{f90,,read()} doesn't block, but
If there hasn't been an expiration since the last call to read,
@ref{f90,,read()} raises @ref{2c0,,OSError} with @code{errno} is set to
@ref{25a8,,errno.EAGAIN}.

@ref{520,,TFD_CLOEXEC} 總是由 Python 自動設定。

The file descriptor must be closed with @ref{d63,,os.close()} when it is no
longer needed, or else the file descriptor will be leaked.


@subsubheading 也參考


@code{timerfd_create(2)@footnote{https://manpages.debian.org/timerfd_create(2)}} 使用手冊。


@ref{2006,,可用性}: Linux >= 2.6.27 with glibc >= 2.8


在 3.13 版被加入.

@end deffn

@geindex timerfd_settime() (於 os 模組中)
@anchor{library/os os timerfd_settime}@anchor{51b}
@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{51c,,timerfd_settime_ns()}.

`fd' 必須是有效的計時器檔案描述器。

The timer's behaviour can be modified by specifying a `flags' value.
Any of the following variables may used, combined using bitwise OR
(the @code{|} operator):


@itemize -

@item 
@ref{521,,TFD_TIMER_ABSTIME}

@item 
@ref{522,,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{2c0,,OSError} exception
with @code{errno} set to @ref{1c9b,,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{521,,TFD_TIMER_ABSTIME} flag is set,
the timer will fire when the timer's clock
(set by `clockid' in @ref{51a,,timerfd_create()}) reaches `initial' seconds.

The timer's interval is set by the `interval' @ref{196,,float}.
If `interval' is zero, the timer only fires once, on the initial expiration.
If `interval' is greater than zero, the timer fires every time `interval'
seconds have elapsed since the previous expiration.
If `interval' is less than zero, it raises @ref{2c0,,OSError} with @code{errno}
set to @ref{1c9b,,errno.EINVAL}

If the @ref{522,,TFD_TIMER_CANCEL_ON_SET} flag is set along with
@ref{521,,TFD_TIMER_ABSTIME} and the clock for this timer is
@ref{8a1,,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{2006,,可用性}: Linux >= 2.6.27 with glibc >= 2.8


在 3.13 版被加入.

@end deffn

@geindex timerfd_settime_ns() (於 os 模組中)
@anchor{library/os os timerfd_settime_ns}@anchor{51c}
@deffn {函式} os.timerfd_settime_ns (fd, /, *, flags=0, initial=0, interval=0)

Similar to @ref{51b,,timerfd_settime()}, but use time as nanoseconds.
This function operates the same interval timer as @ref{51b,,timerfd_settime()}.

@ref{2006,,可用性}: Linux >= 2.6.27 with glibc >= 2.8


在 3.13 版被加入.

@end deffn

@geindex timerfd_gettime() (於 os 模組中)
@anchor{library/os os timerfd_gettime}@anchor{51d}
@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 next the timer next fires,
regardless of if the @ref{521,,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{2006,,可用性}: Linux >= 2.6.27 with glibc >= 2.8


在 3.13 版被加入.

@end deffn

@geindex timerfd_gettime_ns() (於 os 模組中)
@anchor{library/os os timerfd_gettime_ns}@anchor{51e}
@deffn {函式} os.timerfd_gettime_ns (fd, /)

Similar to @ref{51d,,timerfd_gettime()}, but return time as nanoseconds.

@ref{2006,,可用性}: Linux >= 2.6.27 with glibc >= 2.8


在 3.13 版被加入.

@end deffn

@geindex TFD_NONBLOCK (於 os 模組中)
@anchor{library/os os TFD_NONBLOCK}@anchor{51f}
@deffn {資料} os.TFD_NONBLOCK

A flag for the @ref{51a,,timerfd_create()} function,
which sets the @ref{1036,,O_NONBLOCK} status flag for the new timer file
descriptor. If @ref{51f,,TFD_NONBLOCK} is not set as a flag, @ref{f90,,read()} blocks.

@ref{2006,,可用性}: Linux >= 2.6.27 with glibc >= 2.8


在 3.13 版被加入.

@end deffn

@geindex TFD_CLOEXEC (於 os 模組中)
@anchor{library/os os TFD_CLOEXEC}@anchor{520}
@deffn {資料} os.TFD_CLOEXEC

A flag for the @ref{51a,,timerfd_create()} function,
If @ref{520,,TFD_CLOEXEC} is set as a flag, set close-on-exec flag for new file
descriptor.

@ref{2006,,可用性}: Linux >= 2.6.27 with glibc >= 2.8


在 3.13 版被加入.

@end deffn

@geindex TFD_TIMER_ABSTIME (於 os 模組中)
@anchor{library/os os TFD_TIMER_ABSTIME}@anchor{521}
@deffn {資料} os.TFD_TIMER_ABSTIME

A flag for the @ref{51b,,timerfd_settime()} and @ref{51c,,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{2006,,可用性}: Linux >= 2.6.27 with glibc >= 2.8


在 3.13 版被加入.

@end deffn

@geindex TFD_TIMER_CANCEL_ON_SET (於 os 模組中)
@anchor{library/os os TFD_TIMER_CANCEL_ON_SET}@anchor{522}
@deffn {資料} os.TFD_TIMER_CANCEL_ON_SET

A flag for the @ref{51b,,timerfd_settime()} and @ref{51c,,timerfd_settime_ns()}
functions along with @ref{521,,TFD_TIMER_ABSTIME}.
The timer is cancelled when the time of the underlying clock changes
discontinuously.

@ref{2006,,可用性}: Linux >= 2.6.27 with glibc >= 2.8


在 3.13 版被加入.

@end deffn

@node Linux extended attributes,,計時器檔案描述器,Files and Directories
@anchor{library/os linux-extended-attributes}@anchor{2f60}
@subsubsection Linux extended attributes



在 3.3 版被加入.


These functions are all available on Linux only.

@geindex getxattr() (於 os 模組中)
@anchor{library/os os getxattr}@anchor{1305}
@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{e46,,PathLike} interface). If it is str, it is encoded with the filesystem
encoding.

This function can support @ref{d4b,,specifying a file descriptor} and
@ref{12ec,,not following symlinks}.

引發一個附帶引數 @code{path}、@code{attribute} 的@ref{1b70,,稽核事件} @code{os.getxattr}。


在 3.6 版的變更: Accepts a @ref{59b,,path-like object} for `path' and `attribute'.

@end deffn

@geindex listxattr() (於 os 模組中)
@anchor{library/os os listxattr}@anchor{1306}
@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}, @ref{1306,,listxattr()} will examine the current
directory.

This function can support @ref{d4b,,specifying a file descriptor} and
@ref{12ec,,not following symlinks}.

引發一個附帶引數 @code{path} 的@ref{1b70,,稽核事件} @code{os.listxattr}。


在 3.6 版的變更: Accepts a @ref{59b,,path-like object}.

@end deffn

@geindex removexattr() (於 os 模組中)
@anchor{library/os os removexattr}@anchor{1307}
@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{e46,,PathLike} interface). If it is a string, it is encoded
with the @ref{756,,filesystem encoding and error handler}.

This function can support @ref{d4b,,specifying a file descriptor} and
@ref{12ec,,not following symlinks}.

引發一個附帶引數 @code{path}、@code{attribute} 的@ref{1b70,,稽核事件} @code{os.removexattr}。


在 3.6 版的變更: Accepts a @ref{59b,,path-like object} for `path' and `attribute'.

@end deffn

@geindex setxattr() (於 os 模組中)
@anchor{library/os os setxattr}@anchor{1308}
@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{e46,,PathLike} interface). If it is a str,
it is encoded with the @ref{756,,filesystem encoding and error handler}.  `flags' may be
@ref{2f61,,XATTR_REPLACE} or @ref{2f62,,XATTR_CREATE}. If @ref{2f61,,XATTR_REPLACE} is
given and the attribute does not exist, @code{ENODATA} will be raised.
If @ref{2f62,,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{d4b,,specifying a file descriptor} and
@ref{12ec,,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

引發一個附帶引數 @code{path}、@code{attribute}、@code{value}、@code{flags} 的@ref{1b70,,稽核事件} @code{os.setxattr}。


在 3.6 版的變更: Accepts a @ref{59b,,path-like object} for `path' and `attribute'.

@end deffn

@geindex XATTR_SIZE_MAX (於 os 模組中)
@anchor{library/os os XATTR_SIZE_MAX}@anchor{2f63}
@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{2f62}
@deffn {資料} os.XATTR_CREATE

This is a possible value for the flags argument in @ref{1308,,setxattr()}. It
indicates the operation must create an attribute.
@end deffn

@geindex XATTR_REPLACE (於 os 模組中)
@anchor{library/os os XATTR_REPLACE}@anchor{2f61}
@deffn {資料} os.XATTR_REPLACE

This is a possible value for the flags argument in @ref{1308,,setxattr()}. It
indicates the operation must replace an existing attribute.
@end deffn

@node 行程管理,排程器介面,Files and Directories,os --- 各種作業系統介面
@anchor{library/os os-process}@anchor{2f64}@anchor{library/os process-management}@anchor{2f65}
@subsubsection 行程管理


These functions may be used to create and manage processes.

The various @ref{2f66,,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{2f67}
@deffn {函式} os.abort ()

Generate a @code{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{1335,,signal.signal()}.
@end deffn

@geindex add_dll_directory() (於 os 模組中)
@anchor{library/os os add_dll_directory}@anchor{bd4}
@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{3e2,,sys.path}), and also by @ref{2e,,ctypes}.

Remove the directory by calling `close()' on the returned object
or using it in a @ref{186,,with} statement.

See the Microsoft documentation@footnote{https://msdn.microsoft.com/44228cf2-6306-466c-8f16-f513cd3ba8b5}
for more information about how DLLs are loaded.

引發一個附帶引數 @code{path} 的@ref{1b70,,稽核事件} @code{os.add_dll_directory}。

@ref{2006,,可用性}: Windows.


在 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{c8c,,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{2f66}
@deffn {函式} os.execl (path, arg0, arg1, ...)
@anchor{library/os os execle}@anchor{2f68}
@deffnx {函式} os.execle (path, arg0, arg1, ..., env)
@anchor{library/os os execlp}@anchor{2f69}
@deffnx {函式} os.execlp (file, arg0, arg1, ...)
@anchor{library/os os execlpe}@anchor{2f6a}
@deffnx {函式} os.execlpe (file, arg0, arg1, ..., env)
@anchor{library/os os execv}@anchor{2ecb}
@deffnx {函式} os.execv (path, args)
@anchor{library/os os execve}@anchor{12fa}
@deffnx {函式} os.execve (path, args, env)
@anchor{library/os os execvp}@anchor{2f6b}
@deffnx {函式} os.execvp (file, args)
@anchor{library/os os execvpe}@anchor{2f6c}
@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{2c0,,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
@code{sys.stdout.flush()} or @ref{f89,,os.fsync()} before calling an
@ref{2f66,,exec*} function.

The "l" and "v" variants of the @ref{2f66,,exec*} functions differ in how
command-line arguments are passed.  The "l" variants are perhaps the easiest
to work with if the number of parameters is fixed when the code is written; the
individual parameters simply become additional parameters to the @code{execl*()}
functions.  The "v" variants are good when the number of parameters is
variable, with the arguments being passed in a list or tuple as the `args'
parameter.  In either case, the arguments to the child process should start with
the name of the command being run, but this is not enforced.

The variants which include a "p" near the end (@ref{2f69,,execlp()},
@ref{2f6a,,execlpe()}, @ref{2f6b,,execvp()}, and @ref{2f6c,,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 @ref{2f66,,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, @ref{2f66,,execl()}, @ref{2f68,,execle()},
@ref{2ecb,,execv()}, and @ref{12fa,,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 @ref{2f68,,execle()}, @ref{2f6a,,execlpe()}, @ref{12fa,,execve()}, and @ref{2f6c,,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 @ref{2f66,,execl()},
@ref{2f69,,execlp()}, @ref{2ecb,,execv()}, and @ref{2f6b,,execvp()} all cause the new process to
inherit the environment of the current process.

For @ref{12fa,,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{12fe,,os.supports_fd}.
If it is unavailable, using it will raise a @ref{369,,NotImplementedError}.

引發一個附帶引數 @code{path}、@code{args}、@code{env} 的@ref{1b70,,稽核事件} @code{os.exec}。

@ref{2006,,可用性}: Unix, Windows, not WASI, not Android, not iOS.


在 3.3 版的變更: Added support for specifying `path' as an open file descriptor
for @ref{12fa,,execve()}.



在 3.6 版的變更: Accepts a @ref{59b,,path-like object}.

@end deffn

@geindex _exit() (於 os 模組中)
@anchor{library/os os _exit}@anchor{25a4}
@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{277,,sys.exit(n)}.  @code{_exit()} should
normally only be used in the child process after a @ref{4b0,,fork()}.
@end quotation
@end cartouche
@end deffn

The following exit codes are defined and can be used with @ref{25a4,,_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{2f6d}
@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{2006,,可用性}: Unix, Windows.
@end deffn

@geindex EX_USAGE (於 os 模組中)
@anchor{library/os os EX_USAGE}@anchor{2f6e}
@deffn {資料} os.EX_USAGE

Exit code that means the command was used incorrectly, such as when the wrong
number of arguments are given.

@ref{2006,,可用性}: Unix, not WASI.
@end deffn

@geindex EX_DATAERR (於 os 模組中)
@anchor{library/os os EX_DATAERR}@anchor{2f6f}
@deffn {資料} os.EX_DATAERR

Exit code that means the input data was incorrect.

@ref{2006,,可用性}: Unix, not WASI.
@end deffn

@geindex EX_NOINPUT (於 os 模組中)
@anchor{library/os os EX_NOINPUT}@anchor{2f70}
@deffn {資料} os.EX_NOINPUT

Exit code that means an input file did not exist or was not readable.

@ref{2006,,可用性}: Unix, not WASI.
@end deffn

@geindex EX_NOUSER (於 os 模組中)
@anchor{library/os os EX_NOUSER}@anchor{2f71}
@deffn {資料} os.EX_NOUSER

Exit code that means a specified user did not exist.

@ref{2006,,可用性}: Unix, not WASI.
@end deffn

@geindex EX_NOHOST (於 os 模組中)
@anchor{library/os os EX_NOHOST}@anchor{2f72}
@deffn {資料} os.EX_NOHOST

Exit code that means a specified host did not exist.

@ref{2006,,可用性}: Unix, not WASI.
@end deffn

@geindex EX_UNAVAILABLE (於 os 模組中)
@anchor{library/os os EX_UNAVAILABLE}@anchor{2f73}
@deffn {資料} os.EX_UNAVAILABLE

Exit code that means that a required service is unavailable.

@ref{2006,,可用性}: Unix, not WASI.
@end deffn

@geindex EX_SOFTWARE (於 os 模組中)
@anchor{library/os os EX_SOFTWARE}@anchor{2f74}
@deffn {資料} os.EX_SOFTWARE

Exit code that means an internal software error was detected.

@ref{2006,,可用性}: Unix, not WASI.
@end deffn

@geindex EX_OSERR (於 os 模組中)
@anchor{library/os os EX_OSERR}@anchor{2f75}
@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{2006,,可用性}: Unix, not WASI.
@end deffn

@geindex EX_OSFILE (於 os 模組中)
@anchor{library/os os EX_OSFILE}@anchor{2f76}
@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{2006,,可用性}: Unix, not WASI.
@end deffn

@geindex EX_CANTCREAT (於 os 模組中)
@anchor{library/os os EX_CANTCREAT}@anchor{2f77}
@deffn {資料} os.EX_CANTCREAT

Exit code that means a user specified output file could not be created.

@ref{2006,,可用性}: Unix, not WASI.
@end deffn

@geindex EX_IOERR (於 os 模組中)
@anchor{library/os os EX_IOERR}@anchor{2f78}
@deffn {資料} os.EX_IOERR

Exit code that means that an error occurred while doing I/O on some file.

@ref{2006,,可用性}: Unix, not WASI.
@end deffn

@geindex EX_TEMPFAIL (於 os 模組中)
@anchor{library/os os EX_TEMPFAIL}@anchor{2f79}
@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{2006,,可用性}: Unix, not WASI.
@end deffn

@geindex EX_PROTOCOL (於 os 模組中)
@anchor{library/os os EX_PROTOCOL}@anchor{2f7a}
@deffn {資料} os.EX_PROTOCOL

Exit code that means that a protocol exchange was illegal, invalid, or not
understood.

@ref{2006,,可用性}: Unix, not WASI.
@end deffn

@geindex EX_NOPERM (於 os 模組中)
@anchor{library/os os EX_NOPERM}@anchor{2f7b}
@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{2006,,可用性}: Unix, not WASI.
@end deffn

@geindex EX_CONFIG (於 os 模組中)
@anchor{library/os os EX_CONFIG}@anchor{2f7c}
@deffn {資料} os.EX_CONFIG

Exit code that means that some kind of configuration error occurred.

@ref{2006,,可用性}: Unix, not WASI.
@end deffn

@geindex EX_NOTFOUND (於 os 模組中)
@anchor{library/os os EX_NOTFOUND}@anchor{2f7d}
@deffn {資料} os.EX_NOTFOUND

Exit code that means something like "an entry was not found".

@ref{2006,,可用性}: Unix, not WASI.
@end deffn

@geindex fork() (於 os 模組中)
@anchor{library/os os fork}@anchor{4b0}
@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{2c0,,OSError} is raised.

Note that some platforms including FreeBSD <= 6.3 and Cygwin have
known issues when using @code{fork()} from a thread.

引發一個不附帶引數的@ref{1b70,,稽核事件} @code{os.fork}。

@cartouche
@quotation 警告 
If you use TLS sockets in an application calling @code{fork()}, see
the warning in the @ref{d5,,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{111,,urllib.request}.
@end quotation
@end cartouche


在 3.8 版的變更: Calling @code{fork()} in a subinterpreter is no longer supported
(@ref{244,,RuntimeError} is raised).



在 3.12 版的變更: If Python is able to detect that your process has multiple
threads, @ref{4b0,,os.fork()} now raises a @ref{1a3,,DeprecationWarning}.

We chose to surface this as a warning, when detectable, to better
inform developers of a design problem that the POSIX platform
specifically notes as not supported. Even in code that
`appears' to work, it has never been safe to mix threading with
@ref{4b0,,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{2006,,可用性}: POSIX, not WASI, not Android, not iOS.
@end deffn

@geindex forkpty() (於 os 模組中)
@anchor{library/os os forkpty}@anchor{4b1}
@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{b6,,pty} module.  If an error occurs @ref{2c0,,OSError} is raised.

引發一個不附帶引數的@ref{1b70,,稽核事件} @code{os.forkpty}。

@cartouche
@quotation 警告 
On macOS the use of this function is unsafe when mixed with using
higher-level system APIs, and that includes using @ref{111,,urllib.request}.
@end quotation
@end cartouche


在 3.8 版的變更: Calling @code{forkpty()} in a subinterpreter is no longer supported
(@ref{244,,RuntimeError} is raised).



在 3.12 版的變更: If Python is able to detect that your process has multiple
threads, this now raises a @ref{1a3,,DeprecationWarning}. See the
longer explanation on @ref{4b0,,os.fork()}.


@ref{2006,,可用性}: Unix, not WASI, not Android, not iOS.
@end deffn

@geindex kill() (於 os 模組中)
@anchor{library/os os kill}@anchor{155f}
@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{cb,,signal} module.

Windows: The @ref{1560,,signal.CTRL_C_EVENT} and
@ref{1561,,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'.

另請參閱 @ref{1332,,signal.pthread_kill()}。

引發一個附帶引數 @code{pid}、@code{sig} 的@ref{1b70,,稽核事件} @code{os.kill}。

@ref{2006,,可用性}: Unix, Windows, not WASI, not iOS.


在 3.2 版的變更: 新支援 Windows。

@end deffn

@geindex killpg() (於 os 模組中)
@anchor{library/os os killpg}@anchor{1c84}
@deffn {函式} os.killpg (pgid, sig, /)

@geindex process;killing
@geindex process;signalling（信號）

Send the signal `sig' to the process group `pgid'.

引發一個附帶引數 @code{pgid}、@code{sig} 的@ref{1b70,,稽核事件} @code{os.killpg}。

@ref{2006,,可用性}: Unix, not WASI, not iOS.
@end deffn

@geindex nice() (於 os 模組中)
@anchor{library/os os nice}@anchor{1302}
@deffn {函式} os.nice (increment, /)

Add `increment' to the process's "niceness".  Return the new niceness.

@ref{2006,,可用性}: Unix, not WASI.
@end deffn

@geindex pidfd_open() (於 os 模組中)
@anchor{library/os os pidfd_open}@anchor{69d}
@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.

更多細節請見 @code{pidfd_open(2)@footnote{https://manpages.debian.org/pidfd_open(2)}} 使用手冊。

@ref{2006,,可用性}: Linux >= 5.3, Android >= @ref{d7d,,build-time} API level 31


在 3.9 版被加入.


@geindex PIDFD_NONBLOCK (於 os 模組中)
@anchor{library/os os PIDFD_NONBLOCK}@anchor{6bb}
@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{25a8,,EAGAIN} rather than blocking.
@end deffn

@ref{2006,,可用性}: Linux >= 5.10


在 3.12 版被加入.

@end deffn

@geindex plock() (於 os 模組中)
@anchor{library/os os plock}@anchor{2f7e}
@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{2006,,可用性}: Unix, not WASI, not iOS.
@end deffn

@geindex popen() (於 os 模組中)
@anchor{library/os os popen}@anchor{319}
@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{315,,open()} function. The
returned file object reads or writes text strings rather than bytes.

The @code{close} method returns @ref{87e,,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{b0e,,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{4b2,,subprocess.Popen}; see that class's
documentation for more powerful ways to manage and communicate with
subprocesses.

@ref{2006,,可用性}: not WASI, not Android, not iOS.

@cartouche
@quotation 備註 
The @ref{85f,,Python UTF-8 Mode} affects encodings used
for `cmd' and pipe contents.

@ref{319,,popen()} is a simple wrapper around @ref{4b2,,subprocess.Popen}.
Use @ref{4b2,,subprocess.Popen} or @ref{d79,,subprocess.run()} to
control options like encodings.
@end quotation
@end cartouche


在 3.14 版之後被棄用: The function is @ref{23d,,soft deprecated} and should no longer be used to
write new code. The @ref{dc,,subprocess} module is recommended instead.

@end deffn

@geindex posix_spawn() (於 os 模組中)
@anchor{library/os os posix_spawn}@anchor{529}
@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{d79,,subprocess.run()} instead of @ref{529,,posix_spawn()}.

The positional-only arguments `path', `args', and `env' are similar to
@ref{12fa,,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{1cd9,,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{2f7f}
@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{2f80}
@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{2f81}
@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{52a}
@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{369,,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{187b,,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.

引發一個附帶引數 @code{path}、@code{argv}、@code{env} 的@ref{1b70,,稽核事件} @code{os.posix_spawn}。


在 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{2006,,可用性}: Unix, not WASI, not Android, not iOS.
@end deffn

@geindex posix_spawnp() (於 os 模組中)
@anchor{library/os os posix_spawnp}@anchor{1cd9}
@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{529,,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)}).

引發一個附帶引數 @code{path}、@code{argv}、@code{env} 的@ref{1b70,,稽核事件} @code{os.posix_spawn}。


在 3.8 版被加入.


@ref{2006,,可用性}: POSIX, not WASI, not Android, not iOS.

見 @ref{529,,posix_spawn()} 文件。
@end deffn

@geindex register_at_fork() (於 os 模組中)
@anchor{library/os os register_at_fork}@anchor{353}
@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{4b0,,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{dc,,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{db3,,PyOS_BeforeFork()},
@ref{db4,,PyOS_AfterFork_Parent()} and @ref{42e,,PyOS_AfterFork_Child()}.

There is no way to unregister a function.

@ref{2006,,可用性}: Unix, not WASI, not Android, not iOS.


在 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{31a}
@deffn {函式} os.spawnl (mode, path, ...)
@anchor{library/os os spawnle}@anchor{2f82}
@deffnx {函式} os.spawnle (mode, path, ..., env)
@anchor{library/os os spawnlp}@anchor{2f83}
@deffnx {函式} os.spawnlp (mode, file, ...)
@anchor{library/os os spawnlpe}@anchor{2f84}
@deffnx {函式} os.spawnlpe (mode, file, ..., env)
@anchor{library/os os spawnv}@anchor{2f85}
@deffnx {函式} os.spawnv (mode, path, args)
@anchor{library/os os spawnve}@anchor{2f86}
@deffnx {函式} os.spawnve (mode, path, args, env)
@anchor{library/os os spawnvp}@anchor{2f87}
@deffnx {函式} os.spawnvp (mode, file, args)
@anchor{library/os os spawnvpe}@anchor{2f88}
@deffnx {函式} os.spawnvpe (mode, file, args, env)

Execute the program `path' in a new process.

(Note that the @ref{dc,,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{1389,,Replacing Older Functions with the subprocess Module} section.)

If `mode' is @ref{2f89,,P_NOWAIT}, this function returns the process id of the new
process; if `mode' is @ref{2f8a,,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{f95,,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 @ref{31a,,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 (@ref{2f83,,spawnlp()},
@ref{2f84,,spawnlpe()}, @ref{2f87,,spawnvp()}, and @ref{2f88,,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 @ref{31a,,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, @ref{31a,,spawnl()},
@ref{2f82,,spawnle()}, @ref{2f85,,spawnv()}, and @ref{2f86,,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 @ref{2f82,,spawnle()}, @ref{2f84,,spawnlpe()}, @ref{2f86,,spawnve()}, and @ref{2f88,,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
@ref{31a,,spawnl()}, @ref{2f83,,spawnlp()}, @ref{2f85,,spawnv()}, and @ref{2f87,,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 @ref{2f83,,spawnlp()} and @ref{2f88,,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

引發一個附帶引數 @code{mode}、@code{path}、@code{args}、@code{env} 的@ref{1b70,,稽核事件} @code{os.spawn}。

@ref{2006,,可用性}: Unix, Windows, not WASI, not Android, not iOS.

@ref{2f83,,spawnlp()}, @ref{2f84,,spawnlpe()}, @ref{2f87,,spawnvp()}
and @ref{2f88,,spawnvpe()} are not available on Windows.  @ref{2f82,,spawnle()} and
@ref{2f86,,spawnve()} are not thread-safe on Windows; we advise you to use the
@ref{dc,,subprocess} module instead.


在 3.6 版的變更: Accepts a @ref{59b,,path-like object}.



在 3.14 版之後被棄用: These functions are @ref{23d,,soft deprecated} and should no longer be used
to write new code. The @ref{dc,,subprocess} module is recommended instead.

@end deffn

@geindex P_NOWAIT (於 os 模組中)
@geindex P_NOWAITO (於 os 模組中)
@anchor{library/os os P_NOWAIT}@anchor{2f89}
@deffn {資料} os.P_NOWAIT
@anchor{library/os os P_NOWAITO}@anchor{2f8b}
@deffnx {資料} os.P_NOWAITO

Possible values for the `mode' parameter to the @ref{31a,,spawn*} family of
functions.  If either of these values is given, the @ref{31a,,spawn*} functions
will return as soon as the new process has been created, with the process id as
the return value.

@ref{2006,,可用性}: Unix, Windows.
@end deffn

@geindex P_WAIT (於 os 模組中)
@anchor{library/os os P_WAIT}@anchor{2f8a}
@deffn {資料} os.P_WAIT

Possible value for the `mode' parameter to the @ref{31a,,spawn*} family of
functions.  If this is given as `mode', the @ref{31a,,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{2006,,可用性}: Unix, Windows.
@end deffn

@geindex P_DETACH (於 os 模組中)
@geindex P_OVERLAY (於 os 模組中)
@anchor{library/os os P_DETACH}@anchor{2f8c}
@deffn {資料} os.P_DETACH
@anchor{library/os os P_OVERLAY}@anchor{2f8d}
@deffnx {資料} os.P_OVERLAY

Possible values for the `mode' parameter to the @ref{31a,,spawn*} family of
functions.  These are less portable than those listed above. @ref{2f8c,,P_DETACH}
is similar to @ref{2f89,,P_NOWAIT}, but the new process is detached from the
console of the calling process. If @ref{2f8d,,P_OVERLAY} is used, the current
process will be replaced; the @ref{31a,,spawn*} function will not return.

@ref{2006,,可用性}: Windows.
@end deffn

@geindex startfile() (於 os 模組中)
@anchor{library/os os startfile}@anchor{1b81}
@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.

@ref{1b81,,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{151a,,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{369,,NotImplementedError} will be raised.

引發一個附帶引數 @code{path}、@code{operation} 的@ref{1b70,,稽核事件} @code{os.startfile}。

引發一個附帶引數 @code{path}、@code{operation}、@code{arguments}、@code{cwd}、@code{show_cmd} 的@ref{1b70,,稽核事件} @code{os.startfile/2}。

@ref{2006,,可用性}: 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{1652}
@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{758,,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{f93,,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{dc,,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{1389,,Replacing Older Functions with the subprocess Module} section in
the @ref{dc,,subprocess} documentation for some helpful recipes.

On Unix, @ref{b0e,,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.

引發一個附帶引數 @code{command} 的@ref{1b70,,稽核事件} @code{os.system}。

@ref{2006,,可用性}: Unix, Windows, not WASI, not Android, not iOS.
@end deffn

@geindex times() (於 os 模組中)
@anchor{library/os os times}@anchor{1316}
@deffn {函式} os.times ()

Returns the current global process times.
The return value is an object with five attributes:


@itemize *

@item 
@code{user} - 使用者時間

@item 
@code{system} - 系統時間

@item 
@code{children_user} - 所有子行程的使用者時間

@item 
@code{children_system} - 所有子行程的系統時間

@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{2006,,可用性}: 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{f93}
@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{1253,,ChildProcessError}
is raised.

@ref{b0e,,waitstatus_to_exitcode()} can be used to convert the exit status into an
exit code.

@ref{2006,,可用性}: 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{f95,,waitpid()} is the only one also available on Windows.

@end deffn

@geindex waitid() (於 os 模組中)
@anchor{library/os os waitid}@anchor{f94}
@deffn {函式} os.waitid (idtype, id, options, /)

Wait for the completion of a child process.

`idtype' can be @ref{2f8e,,P_PID}, @ref{2f8f,,P_PGID}, @ref{2f90,,P_ALL}, or (on Linux) @ref{b0d,,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{2f91,,WEXITED},
@ref{2f92,,WSTOPPED} or @ref{2f93,,WCONTINUED} is required;
@ref{2f94,,WNOHANG} and @ref{2f95,,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{2f96,,SIGCHLD})

@item 
@code{si_status} (the exit status or signal number, depending on @code{si_code})

@item 
@code{si_code} (see @ref{2f97,,CLD_EXITED} for possible values)
@end itemize

If @ref{2f94,,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{1253,,ChildProcessError} is raised.

@ref{2006,,可用性}: Unix, not WASI, not Android, not iOS.


在 3.3 版被加入.



在 3.13 版的變更: This function is now available on macOS as well.

@end deffn

@geindex waitpid() (於 os 模組中)
@anchor{library/os os waitpid}@anchor{f95}
@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{f93,,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}, @ref{f95,,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{2f94,,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{1253,,ChildProcessError} is raised.  Other options that can be used are
@ref{2f98,,WUNTRACED} and @ref{2f93,,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{31a,,spawn*}
functions called with @ref{2f89,,P_NOWAIT} return suitable process handles.

@ref{b0e,,waitstatus_to_exitcode()} can be used to convert the exit status into an
exit code.

@ref{2006,,可用性}: 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{f83,,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{f91}
@deffn {函式} os.wait3 (options)

Similar to @ref{f95,,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{1628,,resource.getrusage()} for details on resource usage information.  The
`options' argument is the same as that provided to @ref{f95,,waitpid()} and
@ref{f92,,wait4()}.

@ref{b0e,,waitstatus_to_exitcode()} can be used to convert the exit status into an
exitcode.

@ref{2006,,可用性}: Unix, not WASI, not Android, not iOS.
@end deffn

@geindex wait4() (於 os 模組中)
@anchor{library/os os wait4}@anchor{f92}
@deffn {函式} os.wait4 (pid, options)

Similar to @ref{f95,,waitpid()}, except a 3-element tuple, containing the child's
process id, exit status indication, and resource usage information is
returned.  Refer to @ref{1628,,resource.getrusage()} for details on resource usage
information.  The arguments to @ref{f92,,wait4()} are the same as those provided
to @ref{f95,,waitpid()}.

@ref{b0e,,waitstatus_to_exitcode()} can be used to convert the exit status into an
exitcode.

@ref{2006,,可用性}: 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{2f8e}
@deffn {資料} os.P_PID
@anchor{library/os os P_PGID}@anchor{2f8f}
@deffnx {資料} os.P_PGID
@anchor{library/os os P_ALL}@anchor{2f90}
@deffnx {資料} os.P_ALL
@anchor{library/os os P_PIDFD}@anchor{b0d}
@deffnx {資料} os.P_PIDFD

These are the possible values for `idtype' in @ref{f94,,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{69d,,pidfd_open()}).
@end itemize

@ref{2006,,可用性}: Unix, not WASI, not Android, not iOS.

@cartouche
@quotation 備註 
@code{P_PIDFD} is only available on Linux >= 5.4.
@end quotation
@end cartouche


在 3.3 版被加入.



在 3.9 版被加入: The @code{P_PIDFD} constant.

@end deffn

@geindex WCONTINUED (於 os 模組中)
@anchor{library/os os WCONTINUED}@anchor{2f93}
@deffn {資料} os.WCONTINUED

This `options' flag for @ref{f95,,waitpid()}, @ref{f91,,wait3()}, @ref{f92,,wait4()}, and
@ref{f94,,waitid()} causes child processes to be reported if they have been
continued from a job control stop since they were last reported.

@ref{2006,,可用性}: Unix, not WASI, not Android, not iOS.
@end deffn

@geindex WEXITED (於 os 模組中)
@anchor{library/os os WEXITED}@anchor{2f91}
@deffn {資料} os.WEXITED

This `options' flag for @ref{f94,,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{2006,,可用性}: Unix, not WASI, not Android, not iOS.


在 3.3 版被加入.

@end deffn

@geindex WSTOPPED (於 os 模組中)
@anchor{library/os os WSTOPPED}@anchor{2f92}
@deffn {資料} os.WSTOPPED

This `options' flag for @ref{f94,,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{2006,,可用性}: Unix, not WASI, not Android, not iOS.


在 3.3 版被加入.

@end deffn

@geindex WUNTRACED (於 os 模組中)
@anchor{library/os os WUNTRACED}@anchor{2f98}
@deffn {資料} os.WUNTRACED

This `options' flag for @ref{f95,,waitpid()}, @ref{f91,,wait3()}, and @ref{f92,,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{f94,,waitid()}.

@ref{2006,,可用性}: Unix, not WASI, not Android, not iOS.
@end deffn

@geindex WNOHANG (於 os 模組中)
@anchor{library/os os WNOHANG}@anchor{2f94}
@deffn {資料} os.WNOHANG

This `options' flag causes @ref{f95,,waitpid()}, @ref{f91,,wait3()}, @ref{f92,,wait4()}, and
@ref{f94,,waitid()} to return right away if no child process status is available
immediately.

@ref{2006,,可用性}: Unix, not WASI, not Android, not iOS.
@end deffn

@geindex WNOWAIT (於 os 模組中)
@anchor{library/os os WNOWAIT}@anchor{2f95}
@deffn {資料} os.WNOWAIT

This `options' flag causes @ref{f94,,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{2006,,可用性}: 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{2f97}
@deffn {資料} os.CLD_EXITED
@anchor{library/os os CLD_KILLED}@anchor{b0b}
@deffnx {資料} os.CLD_KILLED
@anchor{library/os os CLD_DUMPED}@anchor{2f99}
@deffnx {資料} os.CLD_DUMPED
@anchor{library/os os CLD_TRAPPED}@anchor{2f9a}
@deffnx {資料} os.CLD_TRAPPED
@anchor{library/os os CLD_STOPPED}@anchor{b0c}
@deffnx {資料} os.CLD_STOPPED
@anchor{library/os os CLD_CONTINUED}@anchor{2f9b}
@deffnx {資料} os.CLD_CONTINUED

These are the possible values for @code{si_code} in the result returned by
@ref{f94,,waitid()}.

@ref{2006,,可用性}: Unix, not WASI, not Android, not iOS.


在 3.3 版被加入.



在 3.9 版的變更: 新增 @ref{b0b,,CLD_KILLED} 和 @ref{b0c,,CLD_STOPPED} 值。

@end deffn

@geindex waitstatus_to_exitcode() (於 os 模組中)
@anchor{library/os os waitstatus_to_exitcode}@anchor{b0e}
@deffn {函式} os.waitstatus_to_exitcode (status)

Convert a wait status to an exit code.

在 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 
否則，引發 @ref{2eb,,ValueError}。
@end itemize

On Windows, return `status' shifted right by 8 bits.

On Unix, if the process is being traced or if @ref{f95,,waitpid()} was called
with @ref{2f98,,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{2f9c,,WIFEXITED()}, @ref{2f9d,,WEXITSTATUS()}, @ref{2f9e,,WIFSIGNALED()},
@ref{2f9f,,WTERMSIG()}, @ref{2fa0,,WIFSTOPPED()}, @ref{2fa1,,WSTOPSIG()} functions.


@ref{2006,,可用性}: Unix, Windows, not WASI, not Android, not iOS.


在 3.9 版被加入.

@end deffn

The following functions take a process status code as returned by
@ref{1652,,system()}, @ref{f93,,wait()}, or @ref{f95,,waitpid()} as a parameter.  They may be
used to determine the disposition of a process.

@geindex WCOREDUMP() (於 os 模組中)
@anchor{library/os os WCOREDUMP}@anchor{2fa2}
@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{2f9e,,WIFSIGNALED()} is true.

@ref{2006,,可用性}: Unix, not WASI, not Android, not iOS.
@end deffn

@geindex WIFCONTINUED() (於 os 模組中)
@anchor{library/os os WIFCONTINUED}@anchor{2fa3}
@deffn {函式} os.WIFCONTINUED (status)

Return @code{True} if a stopped child has been resumed by delivery of
@ref{2fa4,,SIGCONT} (if the process has been continued from a job
control stop), otherwise return @code{False}.

參閱 @ref{2f93,,WCONTINUED} 選項。

@ref{2006,,可用性}: Unix, not WASI, not Android, not iOS.
@end deffn

@geindex WIFSTOPPED() (於 os 模組中)
@anchor{library/os os WIFSTOPPED}@anchor{2fa0}
@deffn {函式} os.WIFSTOPPED (status)

Return @code{True} if the process was stopped by delivery of a signal,
otherwise return @code{False}.

@ref{2fa0,,WIFSTOPPED()} only returns @code{True} if the @ref{f95,,waitpid()} call was
done using @ref{2f98,,WUNTRACED} option or when the process is being traced (see
@code{ptrace(2)@footnote{https://manpages.debian.org/ptrace(2)}}).

@ref{2006,,可用性}: Unix, not WASI, not Android, not iOS.
@end deffn

@geindex WIFSIGNALED() (於 os 模組中)
@anchor{library/os os WIFSIGNALED}@anchor{2f9e}
@deffn {函式} os.WIFSIGNALED (status)

Return @code{True} if the process was terminated by a signal, otherwise return
@code{False}.

@ref{2006,,可用性}: Unix, not WASI, not Android, not iOS.
@end deffn

@geindex WIFEXITED() (於 os 模組中)
@anchor{library/os os WIFEXITED}@anchor{2f9c}
@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{2006,,可用性}: Unix, not WASI, not Android, not iOS.
@end deffn

@geindex WEXITSTATUS() (於 os 模組中)
@anchor{library/os os WEXITSTATUS}@anchor{2f9d}
@deffn {函式} os.WEXITSTATUS (status)

Return the process exit status.

This function should be employed only if @ref{2f9c,,WIFEXITED()} is true.

@ref{2006,,可用性}: Unix, not WASI, not Android, not iOS.
@end deffn

@geindex WSTOPSIG() (於 os 模組中)
@anchor{library/os os WSTOPSIG}@anchor{2fa1}
@deffn {函式} os.WSTOPSIG (status)

Return the signal which caused the process to stop.

This function should be employed only if @ref{2fa0,,WIFSTOPPED()} is true.

@ref{2006,,可用性}: Unix, not WASI, not Android, not iOS.
@end deffn

@geindex WTERMSIG() (於 os 模組中)
@anchor{library/os os WTERMSIG}@anchor{2f9f}
@deffn {函式} os.WTERMSIG (status)

Return the number of the signal that caused the process to terminate.

This function should be employed only if @ref{2f9e,,WIFSIGNALED()} is true.

@ref{2006,,可用性}: Unix, not WASI, not Android, not iOS.
@end deffn

@node 排程器介面,Miscellaneous System Information,行程管理,os --- 各種作業系統介面
@anchor{library/os interface-to-the-scheduler}@anchor{2fa5}
@subsubsection 排程器介面


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.


在 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{2fa6}@anchor{library/os os SCHED_OTHER}@anchor{2fa7}
@deffn {資料} os.SCHED_OTHER

The default scheduling policy.
@end deffn

@geindex SCHED_BATCH (於 os 模組中)
@anchor{library/os os SCHED_BATCH}@anchor{2fa8}
@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{25d}
@deffn {資料} os.SCHED_DEADLINE

Scheduling policy for tasks with deadline constraints.


在 3.14 版被加入.

@end deffn

@geindex SCHED_IDLE (於 os 模組中)
@anchor{library/os os SCHED_IDLE}@anchor{2fa9}
@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{25e}
@deffn {資料} os.SCHED_NORMAL

Alias for @ref{2fa7,,SCHED_OTHER}.


在 3.14 版被加入.

@end deffn

@geindex SCHED_SPORADIC (於 os 模組中)
@anchor{library/os os SCHED_SPORADIC}@anchor{2faa}
@deffn {資料} os.SCHED_SPORADIC

Scheduling policy for sporadic server programs.
@end deffn

@geindex SCHED_FIFO (於 os 模組中)
@anchor{library/os os SCHED_FIFO}@anchor{2fab}
@deffn {資料} os.SCHED_FIFO

先進先出排程策略。
@end deffn

@geindex SCHED_RR (於 os 模組中)
@anchor{library/os os SCHED_RR}@anchor{2fac}
@deffn {資料} os.SCHED_RR

輪轉排程策略。
@end deffn

@geindex SCHED_RESET_ON_FORK (於 os 模組中)
@anchor{library/os os SCHED_RESET_ON_FORK}@anchor{2fad}
@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{187b}
@deffn {類別} os.sched_param (sched_priority)

This class represents tunable scheduling parameters used in
@ref{1310,,sched_setparam()}, @ref{1311,,sched_setscheduler()}, and
@ref{130c,,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{2fae}
@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{130a}
@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{1309}
@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{1311}
@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{187b,,sched_param} instance.
@end deffn

@geindex sched_getscheduler() (於 os 模組中)
@anchor{library/os os sched_getscheduler}@anchor{130d}
@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{1310}
@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{187b,,sched_param} instance.
@end deffn

@geindex sched_getparam() (於 os 模組中)
@anchor{library/os os sched_getparam}@anchor{130c}
@deffn {函式} os.sched_getparam (pid, /)

Return the scheduling parameters as a @ref{187b,,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{130e}
@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{1312}
@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{130f}
@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{130b}
@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.

也請見 @ref{4d5,,process_cpu_count()} 函式。
@end deffn

@node Miscellaneous System Information,Random numbers,排程器介面,os --- 各種作業系統介面
@anchor{library/os miscellaneous-system-information}@anchor{2faf}@anchor{library/os os-path}@anchor{2fb0}
@subsubsection Miscellaneous System Information


@geindex confstr() (於 os 模組中)
@anchor{library/os os confstr}@anchor{1859}
@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{2eb,,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{2c0,,OSError} is raised with
@ref{1c9b,,errno.EINVAL} for the error number.

@ref{2006,,可用性}: Unix.
@end deffn

@geindex confstr_names (於 os 模組中)
@anchor{library/os os confstr_names}@anchor{2fb1}
@deffn {資料} os.confstr_names

Dictionary mapping names accepted by @ref{1859,,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{2006,,可用性}: Unix.
@end deffn

@geindex cpu_count() (於 os 模組中)
@anchor{library/os os cpu_count}@anchor{4d6}
@deffn {函式} os.cpu_count ()

Return the number of logical CPUs in the `system'. Returns @code{None} if
undetermined.

The @ref{4d5,,process_cpu_count()} function can be used to get the number of
logical CPUs usable by the calling thread of the `current process'.


在 3.4 版被加入.



在 3.13 版的變更: If @ref{16f,,-X cpu_count} is given or 
@geindex PYTHON_CPU_COUNT
@geindex 環境變數; PYTHON_CPU_COUNT
@ref{519,,PYTHON_CPU_COUNT} is set,
@ref{4d6,,cpu_count()} returns the overridden value `n'.

@end deffn

@geindex getloadavg() (於 os 模組中)
@anchor{library/os os getloadavg}@anchor{188b}
@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{2c0,,OSError} if the load average was
unobtainable.

@ref{2006,,可用性}: Unix.
@end deffn

@geindex process_cpu_count() (於 os 模組中)
@anchor{library/os os process_cpu_count}@anchor{4d5}
@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{4d6,,cpu_count()} depending on the CPU affinity.

The @ref{4d6,,cpu_count()} function can be used to get the number of logical CPUs
in the `system'.

If @ref{16f,,-X cpu_count} is given or 
@geindex PYTHON_CPU_COUNT
@geindex 環境變數; PYTHON_CPU_COUNT
@ref{519,,PYTHON_CPU_COUNT} is set,
@ref{4d5,,process_cpu_count()} returns the overridden value `n'.

也請見 @ref{130b,,sched_getaffinity()} 函式。


在 3.13 版被加入.

@end deffn

@geindex sysconf() (於 os 模組中)
@anchor{library/os os sysconf}@anchor{185a}
@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{1859,,confstr()} apply here as well; the dictionary that
provides information on the known names is given by @code{sysconf_names}.

@ref{2006,,可用性}: Unix.
@end deffn

@geindex sysconf_names (於 os 模組中)
@anchor{library/os os sysconf_names}@anchor{2fb2}
@deffn {資料} os.sysconf_names

Dictionary mapping names accepted by @ref{185a,,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{2006,,可用性}: 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 . （點）;於 pathnames（路徑名稱）中

@geindex curdir (於 os 模組中)
@anchor{library/os os curdir}@anchor{2b09}
@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 ..;於 pathnames（路徑名稱）中

@geindex pardir (於 os 模組中)
@anchor{library/os os pardir}@anchor{2f2f}
@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 / （斜線）;於 pathnames（路徑名稱）中

@geindex \ （反斜線）;in pathnames (Windows)（在路徑名稱中 (Windows)）

@geindex sep (於 os 模組中)
@anchor{library/os os sep}@anchor{873}
@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{2b03,,os.path.split()} and @ref{1900,,os.path.join()} --- but it is occasionally
useful. Also available via @ref{a6,,os.path}.
@end deffn

@geindex / （斜線）;於 pathnames（路徑名稱）中

@geindex altsep (於 os 模組中)
@anchor{library/os os altsep}@anchor{874}
@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 . （點）;於 pathnames（路徑名稱）中

@geindex extsep (於 os 模組中)
@anchor{library/os os extsep}@anchor{2fb3}
@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 ; （冒號）;path separator (POSIX)（路徑分隔器 (POSIX)）
@geindex ; （分號）

@geindex pathsep (於 os 模組中)
@anchor{library/os os pathsep}@anchor{1ffb}
@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{1cad}
@deffn {資料} os.defpath

The default search path used by @ref{2f66,,exec*p*} and
@ref{31a,,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{2487}
@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{1cdc}
@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{1319}
@deffn {資料} os.RTLD_LAZY
@anchor{library/os os RTLD_NOW}@anchor{131a}
@deffnx {資料} os.RTLD_NOW
@anchor{library/os os RTLD_GLOBAL}@anchor{131b}
@deffnx {資料} os.RTLD_GLOBAL
@anchor{library/os os RTLD_LOCAL}@anchor{131c}
@deffnx {資料} os.RTLD_LOCAL
@anchor{library/os os RTLD_NODELETE}@anchor{131d}
@deffnx {資料} os.RTLD_NODELETE
@anchor{library/os os RTLD_NOLOAD}@anchor{131e}
@deffnx {資料} os.RTLD_NOLOAD
@anchor{library/os os RTLD_DEEPBIND}@anchor{131f}
@deffnx {資料} os.RTLD_DEEPBIND

Flags for use with the @ref{1320,,setdlopenflags()} and
@ref{1702,,getdlopenflags()} functions.  See the Unix manual page
@code{dlopen(3)@footnote{https://manpages.debian.org/dlopen(3)}} for what the different flags mean.


在 3.3 版被加入.

@end deffn

@node Random numbers,,Miscellaneous System Information,os --- 各種作業系統介面
@anchor{library/os random-numbers}@anchor{2fb4}
@subsubsection Random numbers


@geindex getrandom() (於 os 模組中)
@anchor{library/os os getrandom}@anchor{eb4}
@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{2fb5,,os.GRND_RANDOM} and
@ref{2fb6,,GRND_NONBLOCK}.

See also the Linux getrandom() manual page@footnote{https://man7.org/linux/man-pages/man2/getrandom.2.html}.

@ref{2006,,可用性}: Linux >= 3.17.


在 3.6 版被加入.

@end deffn

@geindex urandom() (於 os 模組中)
@anchor{library/os os urandom}@anchor{73f}
@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{eb4,,getrandom()} function can be used to get
random bytes in non-blocking mode (using the @ref{2fb6,,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{369,,NotImplementedError} exception is raised.

On Windows, it will use @code{BCryptGenRandom()}.


@subsubheading 也參考


The @ref{c5,,secrets} module provides higher level functions. For an
easy-to-use interface to the random number generator provided by your
platform, please see @ref{2a08,,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{2fb6}
@deffn {資料} os.GRND_NONBLOCK

By  default, when reading from @code{/dev/random}, @ref{eb4,,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 @ref{2fb6,,GRND_NONBLOCK} flag is set, then @ref{eb4,,getrandom()} does not
block in these cases, but instead immediately raises @ref{235,,BlockingIOError}.


在 3.6 版被加入.

@end deffn

@geindex GRND_RANDOM (於 os 模組中)
@anchor{library/os os GRND_RANDOM}@anchor{2fb5}
@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.


在 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 — 處理資料串流的核心工具,time --- 時間存取與轉換,os --- 各種作業系統介面,通用作業系統服務
@anchor{library/io doc}@anchor{2fb7}@anchor{library/io io-core-tools-for-working-with-streams}@anchor{2fb8}@anchor{library/io module-io}@anchor{83}@anchor{library/io translation-repo}@anchor{2fb9}
@subsection @code{io} — 處理資料串流的核心工具


@geindex module; io

`原始碼：'Lib/io.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/io.py}


__________________________________________________________________


@menu
* 總覽:: 
* 文字編碼:: 
* 高階模組介面:: 
* 類別階層:: 
* Static Typing:: 
* Performance:: 

@end menu

@node 總覽,文字編碼,,io — 處理資料串流的核心工具
@anchor{library/io io-overview}@anchor{2485}@anchor{library/io overview}@anchor{2fba}
@subsubsection 總覽


@geindex file object（檔案物件）;io 模組

@ref{83,,io} 模組替 Python 提供處理各種類型 IO 的主要工具。有三種主要的 IO 類型： `文字 I/O (text I/O)'、`二進位 I/O (binary I/O)' 以及`原始 I/O (raw I/O)'。這些均為泛用 (generic) 類型，且每種類型都可以使用各式後端儲存 (backing store)。任一種屬於這些類型的具體物件稱為 @ref{13c4,,file object}。其它常見的名詞還有`資料串流 (stream)' 以及`類檔案物件 (file-like objects)'。

無論其類型為何，每個具體的資料串流物件也將具有各種能力：唯讀的、只接受寫入的、或者讀寫兼具的。它還允許任意的隨機存取（向前或向後尋找至任意位置），或者只能依順序存取（例如 socket 或 pipe 的情形下）。

所有的資料串流都會謹慎處理你所提供的資料的型別。舉例來說，提供一個 @ref{169,,str} 物件給二進位資料串流的 @code{write()} 方法將會引發 @ref{198,,TypeError}。同樣地，若提供一個 @ref{192,,bytes} 物件給文字資料串流的 @code{write()} 方法，也會引發同樣的錯誤。


在 3.3 版的變更: 原本會引發 @ref{124e,,IOError} 的操作，現在將改成引發 @ref{2c0,,OSError}。因為 @ref{124e,,IOError} 現在是 @ref{2c0,,OSError} 的別名。


@menu
* 文字 I/O:: 
* 二進位 (Binary) I/O: 二進位 Binary I/O. 
* 原始 (Raw) I/O: 原始 Raw I/O. 

@end menu

@node 文字 I/O,二進位 Binary I/O,,總覽
@anchor{library/io text-i-o}@anchor{2fbb}
@subsubsection 文字 I/O


文字 I/O 要求和產出 @ref{169,,str} 物件。這意味著每當後端儲存為原生 bytes 時（例如在檔案的情形下），資料的編碼與解碼會以清楚易懂的方式進行，也可選擇同時轉換特定於平台的換行字元。

建立文字資料串流最簡單的方法是使用 @ref{315,,open()}，可選擇性地指定編碼：

@example
f = open("myfile.txt", "r", encoding="utf-8")
@end example

記憶體內的文字資料串流也可以使用 @ref{1124,,StringIO} 物件建立：

@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{235,,BlockingIOError} if the stream cannot perform the operation
immediately.
@end quotation
@end cartouche

文字資料串流 API 的詳細說明在 @ref{89d,,TextIOBase} 文件當中。

@node 二進位 Binary I/O,原始 Raw I/O,文字 I/O,總覽
@anchor{library/io binary-i-o}@anchor{2fbc}
@subsubsection 二進位 (Binary) I/O


二進位 I/O（也稱為`緩衝 I/O (buffered I/O)'）要求的是@ref{193,,類位元組物件 (bytes-like objects)} 且產生 @ref{192,,bytes} 物件。不進行編碼、解碼或者換行字元轉換。這種類型的資料串流可用於各種非文字資料，以及需要手動控制對文字資料的處理時。

建立二進位資料串流最簡單的方法是使用 @ref{315,,open()}，並在 mode 字串中加入 @code{'b'}：

@example
f = open("myfile.jpg", "rb")
@end example

記憶體內的二進位資料串流也可以透過 @ref{109f,,BytesIO} 物件來建立：

@example
f = io.BytesIO(b"some initial binary data: \x00\x01")
@end example

二進位資料串流 API 的詳細說明在 @ref{89c,,BufferedIOBase} 文件當中。

其它函式庫模組可能提供額外的方法來建立文字或二進位資料串流。例如 @ref{13a0,,socket.socket.makefile()}。

@node 原始 Raw I/O,,二進位 Binary I/O,總覽
@anchor{library/io raw-i-o}@anchor{2fbd}
@subsubsection 原始 (Raw) I/O


原始 I/O（也稱為`無緩衝 I/O (unbuffered I/O)'）通常作為二進位以及文字資料串流的低階 building-block 使用；在使用者程式碼中直接操作原始資料串流很少有用。然而，你可以透過以無緩衝的二進位模式開啟一個檔案來建立一個原始資料串流：

@example
f = open("myfile.jpg", "rb", buffering=0)
@end example

原始串流 API 在 @ref{12d1,,RawIOBase} 文件中有詳細描述。

@node 文字編碼,高階模組介面,總覽,io — 處理資料串流的核心工具
@anchor{library/io io-text-encoding}@anchor{9b9}@anchor{library/io text-encoding}@anchor{2fbe}
@subsubsection 文字編碼


@ref{9b7,,TextIOWrapper} 和 @ref{315,,open()} 預設編碼是根據區域設定的 (locale-specific) (@ref{328,,locale.getencoding()})。

然而，許多開發人員在開啟以 UTF-8 編碼的文字檔案（例如：JSON、TOML、Markdown等）時忘記指定編碼，因為多數 Unix 平台預設使用 UTF-8 區域設定。這會導致錯誤，因為對於大多數 Windows 使用者來說，預設地區編碼並非 UTF-8。舉例來說：

@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

因此，強烈建議在開啟文字檔案時，明確指定編碼。若你想使用 UTF-8 編碼，請傳入 @code{encoding="utf-8"}。若想使用目前的地區編碼，Python 3.10 以後的版本支援使用 @code{encoding="locale"}。


@subsubheading 也參考



@table @asis

@item @ref{85f,,Python UTF-8 模式}

在 Python UTF-8 模式下，可以將預設編碼從特定地區編碼改為 UTF-8。

@geindex Python Enhancement Proposals; PEP 686

@item PEP 686@footnote{https://peps.python.org/pep-0686/}

Python 3.15 將預設使用 @ref{85f,,Python UTF-8 模式}。
@end table


@menu
* 選擇性加入的編碼警告:: 

@end menu

@node 選擇性加入的編碼警告,,,文字編碼
@anchor{library/io io-encoding-warning}@anchor{2007}@anchor{library/io opt-in-encodingwarning}@anchor{2fbf}
@subsubsection 選擇性加入的編碼警告



在 3.10 版被加入: 更多資訊請見 
@geindex Python Enhancement Proposals; PEP 597
PEP 597@footnote{https://peps.python.org/pep-0597/}。


要找出哪些地方使用到預設的地區編碼，你可以啟用 @ref{16f,,-X warn_default_encoding} 命令列選項，或者設定環境變數 
@geindex PYTHONWARNDEFAULTENCODING
@geindex 環境變數; PYTHONWARNDEFAULTENCODING
@ref{9b8,,PYTHONWARNDEFAULTENCODING}。當使用到預設編碼時，會引發 @ref{1ff5,,EncodingWarning}。

如果你正在提供一個使用 @ref{315,,open()} 或 @ref{9b7,,TextIOWrapper} 且傳遞 @code{encoding=None} 作為參數的 API，你可以使用 @ref{198d,,text_encoding()}。如此一來如果 API 的呼叫方沒有傳遞 @code{encoding}，呼叫方就會發出一個 @ref{1ff5,,EncodingWarning}。然而，對於新的 API，請考慮預設使用 UTF-8（即 @code{encoding="utf-8"}）。

@node 高階模組介面,類別階層,文字編碼,io — 處理資料串流的核心工具
@anchor{library/io high-level-module-interface}@anchor{2fc0}
@subsubsection 高階模組介面


@geindex DEFAULT_BUFFER_SIZE (於 io 模組中)
@anchor{library/io io DEFAULT_BUFFER_SIZE}@anchor{198e}
@deffn {資料} io.DEFAULT_BUFFER_SIZE

一個包含模組中緩衝 I/O 類別所使用的預設緩衝區大小的整數。若可能的話，@ref{315,,open()} 會使用檔案的 blksize （透過 @ref{26d,,os.stat()} 取得）。
@end deffn

@geindex open() (於 io 模組中)
@anchor{library/io io open}@anchor{739}
@deffn {函式} io.open (file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, closefd=True, opener=None)

這是內建函式 @ref{315,,open()} 的別名。

此函式會引發一個帶有引數 `path'、`mode' 以及 `flags' 的@ref{1b70,,稽核事件 (auditing event)} @code{open}。`mode' 與 `flags' 引數可能已經被修改或者從原始呼叫中被推斷出來。
@end deffn

@geindex open_code() (於 io 模組中)
@anchor{library/io io open_code}@anchor{19e7}
@deffn {函式} io.open_code (path)

以 @code{'rb'} 模式開啟提供的檔案。此函式應用於意圖將內容視為可執行的程式碼的情況下。

`path' 應該要屬於 @ref{169,,str} 類別，且是個絕對路徑。

這個函式的行為可能會被之前對 @ref{19e9,,PyFile_SetOpenCodeHook()} 的呼叫覆寫。然而，假設 `path' 是個 @ref{169,,str} 且為絕對路徑，則 @code{open_code(path)} 總是與 @code{open(path, 'rb')} 有相同行為。覆寫這個行為是為了對檔案進行額外驗證或預處理。


在 3.8 版被加入.

@end deffn

@geindex text_encoding() (於 io 模組中)
@anchor{library/io io text_encoding}@anchor{198d}
@deffn {函式} io.text_encoding (encoding, stacklevel=2, /)

這是個輔助函式，適用於使用 @ref{315,,open()} 或 @ref{9b7,,TextIOWrapper} 且具有 @code{encoding=None} 參數的可呼叫物件。

若 `encoding' 不為 @code{None}，此函式將回傳 `encoding'。否則，將根據 @ref{85f,,UTF-8 Mode} 回傳 @code{"locale"} 或 @code{"utf-8"}。

若 @ref{895,,sys.flags.warn_default_encoding} 為真，且 `encoding' 為 @code{None}，此函式會發出一個 @ref{1ff5,,EncodingWarning}。`stacklevel' 指定警告在哪層發出。範例：

@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

在此範例中，對於 @code{read_text()} 的呼叫方會引發一個 @ref{1ff5,,EncodingWarning}。

更多資訊請見 @ref{9b9,,文字編碼}。


在 3.10 版被加入.



在 3.11 版的變更: 當 UTF-8 模式啟用且 `encoding' 為 @code{None} 時，@ref{198d,,text_encoding()} 會回傳 "utf-8"。

@end deffn

@geindex BlockingIOError
@anchor{library/io io BlockingIOError}@anchor{2fc1}
@deffn {例外} io.BlockingIOError

這是內建的 @ref{235,,BlockingIOError} 例外的相容性別名。
@end deffn

@geindex UnsupportedOperation
@anchor{library/io io UnsupportedOperation}@anchor{1c48}
@deffn {例外} io.UnsupportedOperation

當在資料串流上呼叫不支援的操作時，會引發繼承自 @ref{2c0,,OSError} 與 @ref{2eb,,ValueError} 的例外。
@end deffn


@subsubheading 也參考



@table @asis

@item @ref{df,,sys}

包含標準的 IO 資料串流：@ref{758,,sys.stdin}、@ref{cc4,,sys.stdout} 以及 @ref{b2a,,sys.stderr}。
@end table


@node 類別階層,Static Typing,高階模組介面,io — 處理資料串流的核心工具
@anchor{library/io class-hierarchy}@anchor{2fc2}
@subsubsection 類別階層


I/O 串流的實作是由多個類別組合成的階層結構所構成。首先是 @ref{13b7,,abstract base classes} （抽象基底類別，ABCs），它們被用來規範各種不同類型的串流，接著具體類別會提供標準串流的實作。

@cartouche
@quotation 備註 
為了協助具體串流類別的實作，抽象基底類別提供了某些方法的預設實作。舉例來說，@ref{89c,,BufferedIOBase} 提供未經最佳化的 @code{readinto()} 與 @code{readline()} 實作。
@end quotation
@end cartouche

I/O 階層結構的最上層是抽象基底類別 @ref{500,,IOBase}。它定義了串流的基礎的介面。然而，請注意，讀取串流與寫入串流之間並沒有分離；若不支援給定的操作，實作是允許引發 @ref{1c48,,UnsupportedOperation} 例外的。

抽象基底類別 @ref{12d1,,RawIOBase} 繼承 @ref{500,,IOBase}。此類別處理對串流的位元組讀寫。@ref{1510,,FileIO} 則繼承 @ref{12d1,,RawIOBase} 來提供一個介面以存取機器檔案系統內的檔案。

抽象基底類別 @ref{89c,,BufferedIOBase} 繼承 @ref{500,,IOBase}。此類別緩衝原始二進位串流 (@ref{12d1,,RawIOBase})。它的子類別 @ref{15a9,,BufferedWriter}、@ref{140f,,BufferedReader} 與 @ref{15ab,,BufferedRWPair} 分別緩衝可寫、可讀、可讀也可寫的的原始二進位串流。類別 @ref{15aa,,BufferedRandom} 則提供一個對可搜尋串流 (seekable stream) 的緩衝介面。另一個類別 @ref{89c,,BufferedIOBase} 的子類別 @ref{109f,,BytesIO}，是一個記憶體內位元組串流。

抽象基底類別 @ref{89d,,TextIOBase} 繼承 @ref{500,,IOBase}。此類別處理文本位元組串流，並處理字串的編碼和解碼。類別 @ref{9b7,,TextIOWrapper} 繼承自 @ref{89d,,TextIOBase}，這是個對緩衝原始串流 (@ref{89c,,BufferedIOBase}) 的緩衝文本介面。最後，@ref{1124,,StringIO} 是個文字記憶體內串流。

引數名稱不是規範的一部份，只有 @ref{315,,open()} 的引數將作為關鍵字引數。

以下表格總結了 @ref{83,,io} 模組提供的抽象基底類別 (ABC)：


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

抽象基底類別 (ABC)

@tab

繼承

@tab

Stub 方法

@tab

Mixin 方法與屬性

@item

@ref{500,,IOBase}

@tab

@tab

@code{fileno}、@code{seek} 和 @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} 與 @code{writelines}

@item

@ref{12d1,,RawIOBase}

@tab

@ref{500,,IOBase}

@tab

@code{readinto} 和 @code{write}

@tab

繼承自 @ref{500,,IOBase} 的方法，@code{read} 與 @code{readall}

@item

@ref{89c,,BufferedIOBase}

@tab

@ref{500,,IOBase}

@tab

@code{detach}、@code{read}、@code{read1} 和 @code{write}

@tab

繼承自 @ref{500,,IOBase} 的方法，@code{readinto} 與 @code{readinto1}

@item

@ref{89d,,TextIOBase}

@tab

@ref{500,,IOBase}

@tab

@code{detach}、@code{read}、@code{readline} 和 @code{write}

@tab

繼承自 @ref{500,,IOBase} 的方法，@code{encoding}、@code{errors} 與 @code{newlines}

@end multitable


@menu
* I/O 基礎類別:: 
* 原始檔案 I/O:: 
* Buffered Streams:: 
* 文字 I/O: 文字 I/O<2>. 

@end menu

@node I/O 基礎類別,原始檔案 I/O,,類別階層
@anchor{library/io i-o-base-classes}@anchor{2fc3}
@subsubsection I/O 基礎類別


@geindex IOBase (io 中的類別)
@anchor{library/io io IOBase}@anchor{500}
@deffn {類別} io.IOBase

所有 I/O 類別的抽象基礎類別。

為許多方法提供了空的抽象實作，衍生類別可以選擇性地覆寫這些方法；預設的實作代表一個無法讀取、寫入或搜尋的檔案。

即使 @ref{500,,IOBase} 因為實作的簽名差異巨大而沒有宣告 @code{read()} 或 @code{write()} 方法，實作與用戶端應把這些方法視為介面的一部份。此外，當呼叫不被它們支援的操作時，可能會引發 @ref{2eb,,ValueError} （或 @ref{1c48,,UnsupportedOperation}）例外。

The basic type used for binary data read from or written to a file is
@ref{192,,bytes}.  Other @ref{193,,bytes-like objects} are
accepted as method arguments too.  Text I/O classes work with @ref{169,,str} data.

請注意，在一個已經關閉的串流上呼叫任何方法（即使只是查詢）都是未定義的。在這種情況下，實作可能會引發 @ref{2eb,,ValueError} 例外。

@ref{500,,IOBase} (and its subclasses) supports the iterator protocol, meaning
that an @ref{500,,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{152a,,readline()} below.

@ref{500,,IOBase} 也是個情境管理器，因此支援 @ref{186,,with} 陳述式。在這個例子中，`file' 會在 @code{with} 陳述式執行完畢後關閉——即使發生了異常。

@example
with open('spam.txt', 'w') as file:
    file.write('Spam and eggs!')
@end example

@ref{500,,IOBase} 提供這些資料屬性與方法：

@geindex close() (io.IOBase 的方法)
@anchor{library/io io IOBase close}@anchor{501}
@deffn {方法} close ()

清除並關閉這個串流。若檔案已經關閉，則此方法沒有作用。一旦檔案被關閉，任何對檔案的操作（例如讀取或寫入）將引發 @ref{2eb,,ValueError} 異常。

為了方便起見，允許多次呼叫這個方法；然而，只有第一次呼叫會有效果。
@end deffn

@geindex closed (io.IOBase 的屬性)
@anchor{library/io io IOBase closed}@anchor{1cd6}
@deffn {屬性} closed

如果串流已關閉，則為 @code{True}。
@end deffn

@geindex fileno() (io.IOBase 的方法)
@anchor{library/io io IOBase fileno}@anchor{2b7e}
@deffn {方法} fileno ()

如果串流存在，則回傳其底層的檔案描述器（一個整數）。如果 IO 物件不使用檔案描述器，則會引發一個 @ref{2c0,,OSError} 例外。
@end deffn

@geindex flush() (io.IOBase 的方法)
@anchor{library/io io IOBase flush}@anchor{2b99}
@deffn {方法} flush ()

如果適用，清空串流的寫入緩衝區。對於唯讀和非阻塞串流，此操作不會執行任何操作。
@end deffn

@geindex isatty() (io.IOBase 的方法)
@anchor{library/io io IOBase isatty}@anchor{1f30}
@deffn {方法} isatty ()

如果串流是互動式的（即連接到終端機/tty 設備），則回傳 @code{True}。
@end deffn

@geindex readable() (io.IOBase 的方法)
@anchor{library/io io IOBase readable}@anchor{15a5}
@deffn {方法} readable ()

如果串流可以被讀取，則回傳 @code{True}。如果是 @code{False}，@code{read()} 將會引發 @ref{2c0,,OSError} 例外。
@end deffn

@geindex readline() (io.IOBase 的方法)
@anchor{library/io io IOBase readline}@anchor{152a}
@deffn {方法} readline (size=-1, /)

從串流讀取並回傳一行。如果指定了 `size'，則最多讀取 `size' 個位元組。

對於二進位檔案，行結束符總是 @code{b'\n'}；對於文字檔案，可以使用 @ref{315,,open()} 函式的 `newline' 引數來選擇識別的行結束符號。
@end deffn

@geindex readlines() (io.IOBase 的方法)
@anchor{library/io io IOBase readlines}@anchor{264c}
@deffn {方法} readlines (hint=-1, /)

從串流讀取並回傳一個含有一或多行的 list。可以指定 `hint' 來控制讀取的行數：如果到目前為止所有行的總大小（以位元組/字元計）超過 `hint'，則不會再讀取更多行。

`hint' 值為 @code{0} 或更小，以及 @code{None}，都被視為沒有提供 hint。

請注意，已經可以使用 @code{for line in file: ...} 在檔案物件上進行疊代，而不一定需要呼叫 @code{file.readlines()}。
@end deffn

@geindex seek() (io.IOBase 的方法)
@anchor{library/io io IOBase seek}@anchor{148d}
@deffn {方法} seek (offset, whence=os.SEEK_SET, /)

將串流位置改變到給定的位元組 `offset'，此位置是相對於由 `whence' 指示的位置解釋的，並回傳新的絕對位置。`whence' 的值可為：


@itemize *

@item 
@ref{148e,,os.SEEK_SET} 或 @code{0} -- 串流的起點（預設值）；`offset' 應為零或正數

@item 
@ref{148f,,os.SEEK_CUR} 或 @code{1} -- 目前串流位置；`offset' 可以是負數

@item 
@ref{1490,,os.SEEK_END} 或 @code{2} -- 串流的結尾；`offset' 通常是負數
@end itemize


在 3.1 版被加入: @code{SEEK_*} 常數。



在 3.3 版被加入: 某些作業系統可以支援額外的值，例如 @ref{2ef3,,os.SEEK_HOLE} 或 @ref{2ef4,,os.SEEK_DATA}。檔案的合法值取決於它是以文字模式還是二進位模式開啟。

@end deffn

@geindex seekable() (io.IOBase 的方法)
@anchor{library/io io IOBase seekable}@anchor{15a7}
@deffn {方法} seekable ()

如果串流支援隨機存取，則回傳 @code{True}。如果是 @code{False}，則 @ref{148d,,seek()}、@ref{15a4,,tell()} 和 @ref{1511,,truncate()} 會引發 @ref{2c0,,OSError}。
@end deffn

@geindex tell() (io.IOBase 的方法)
@anchor{library/io io IOBase tell}@anchor{15a4}
@deffn {方法} tell ()

回傳目前串流的位置。
@end deffn

@geindex truncate() (io.IOBase 的方法)
@anchor{library/io io IOBase truncate}@anchor{1511}
@deffn {方法} truncate (size=None, /)

將串流的大小調整為指定的 `size' 位元組（如果沒有指定 `size'，則調整為目前位置）。目前串流位置不會改變。這種調整可以擴展或縮減目前檔案大小。在擴展的情況下，新檔案區域的內容取決於平台（在大多數系統上，額外的位元組會被填充為零）。回傳新的檔案大小。


在 3.5 版的變更: Windows 現在在擴展時會對檔案進行零填充 (zero-fill)。

@end deffn

@geindex writable() (io.IOBase 的方法)
@anchor{library/io io IOBase writable}@anchor{15a6}
@deffn {方法} writable ()

如果串流支援寫入，則回傳 @code{True}。如果是 @code{False}，@code{write()} 和 @ref{1511,,truncate()} 將會引發 @ref{2c0,,OSError}。
@end deffn

@geindex writelines() (io.IOBase 的方法)
@anchor{library/io io IOBase writelines}@anchor{264d}
@deffn {方法} writelines (lines, /)

將一個包含每一行的 list 寫入串流。這不會新增行分隔符號，因此通常提供的每一行末尾都有一個行分隔符號。
@end deffn

@geindex __del__() (io.IOBase 的方法)
@anchor{library/io io IOBase __del__}@anchor{2fc4}
@deffn {方法} __del__ ()

為物件銷毀做準備。@ref{500,,IOBase} 提供了這個方法的預設實作，該實作會呼叫實例的 @ref{501,,close()} 方法。
@end deffn
@end deffn

@geindex RawIOBase (io 中的類別)
@anchor{library/io io RawIOBase}@anchor{12d1}
@deffn {類別} io.RawIOBase

原始二進位串流的基底類別。它繼承自 @ref{500,,IOBase}。

原始二進位串流通常提供對底層作業系統設備或 API 的低階存取，並不嘗試將其封裝在高階基元 (primitive) 中（這項功能在緩衝二進位串流和文字串流中的更高階層級完成，後面的頁面會有描述）。

@ref{12d1,,RawIOBase} 除了 @ref{500,,IOBase} 的方法外，還提供以下這些方法：

@geindex read() (io.RawIOBase 的方法)
@anchor{library/io io RawIOBase read}@anchor{1018}
@deffn {方法} read (size=-1, /)

從物件中讀取最多 `size' 個位元組並回傳。方便起見，如果 `size' 未指定或為 -1，則回傳直到檔案結尾 (EOF) 的所有位元組。否則，只會進行一次系統呼叫。如果作業系統呼叫回傳的位元組少於 `size'，則可能回傳少於 `size' 的位元組。

如果回傳了 0 位元組，且 `size' 不是 0，這表示檔案結尾 (end of file)。如果物件處於非阻塞模式且沒有可用的位元組，則回傳 @code{None}。

預設的實作會遵守 @ref{2fc5,,readall()} 和 @ref{1019,,readinto()} 的實作。
@end deffn

@geindex readall() (io.RawIOBase 的方法)
@anchor{library/io io RawIOBase readall}@anchor{2fc5}
@deffn {方法} readall ()

讀取並回傳串流中直到檔案結尾的所有位元組，必要時使用多次對串流的呼叫。
@end deffn

@geindex readinto() (io.RawIOBase 的方法)
@anchor{library/io io RawIOBase readinto}@anchor{1019}
@deffn {方法} readinto (b, /)

將位元組讀入一個預先分配的、可寫的 @ref{193,,bytes-like object} （類位元組物件） `b' 中，並回傳讀取的位元組數量。例如，`b' 可能是一個 @ref{343,,bytearray}。如果物件處於非阻塞模式且沒有可用的位元組，則回傳 @code{None}。
@end deffn

@geindex write() (io.RawIOBase 的方法)
@anchor{library/io io RawIOBase write}@anchor{15a3}
@deffn {方法} write (b, /)

將給定的 @ref{193,,bytes-like object} （類位元組物件），`b'，寫入底層的原始串流，並回傳寫入的位元組大小。根據底層原始串流的具體情況，這可能少於 `b' 的位元組長度，尤其是當它處於非阻塞模式時。如果原始串流設置為非阻塞且無法立即寫入任何單一位元組，則回傳 @code{None}。呼叫者在此方法回傳後可以釋放或變更 `b'，因此實作應該只在方法呼叫期間存取 `b'。
@end deffn
@end deffn

@geindex BufferedIOBase (io 中的類別)
@anchor{library/io io BufferedIOBase}@anchor{89c}
@deffn {類別} io.BufferedIOBase

支援某種緩衝的二進位串流的基底類別。它繼承自 @ref{500,,IOBase}。

與 @ref{12d1,,RawIOBase} 的主要差異在於，@ref{1529,,read()}、@ref{180e,,readinto()} 及 @ref{ed2,,write()} 方法將分別嘗試讀取所請求的盡可能多的輸入，或發出所有提供的資料。

In addition, if the underlying raw stream is in non-blocking mode, when the
system returns would block @ref{ed2,,write()} will raise @ref{235,,BlockingIOError}
with @ref{25ac,,BlockingIOError.characters_written} and @ref{1529,,read()} will return
data read so far or @code{None} if no data is available.

此外，@ref{1529,,read()} 方法不存在一個遵從 @ref{180e,,readinto()} 的預設實作。

一個典型的 @ref{89c,,BufferedIOBase} 實作不應該繼承自一個 @ref{12d1,,RawIOBase} 的實作，而是應該改用包裝的方式，像 @ref{15a9,,BufferedWriter} 和 @ref{140f,,BufferedReader} 那樣的作法。

@ref{89c,,BufferedIOBase} 除了提供或覆寫來自 @ref{500,,IOBase} 的資料屬性和方法以外，還包含了這些：

@geindex raw (io.BufferedIOBase 的屬性)
@anchor{library/io io BufferedIOBase raw}@anchor{15a8}
@deffn {屬性} raw

底層的原始串流（一個 @ref{12d1,,RawIOBase} 實例），@ref{89c,,BufferedIOBase} 處理的對象。這不是 @ref{89c,,BufferedIOBase} API 的一部分，且在某些實作可能不存在。
@end deffn

@geindex detach() (io.BufferedIOBase 的方法)
@anchor{library/io io BufferedIOBase detach}@anchor{2c9e}
@deffn {方法} detach ()

將底層的原始串流從緩衝區中分離出來，並回傳它。

在原始串流被分離後，緩衝區處於一個不可用的狀態。

某些緩衝區，如 @ref{109f,,BytesIO}，沒有單一原始串流的概念可從此方法回傳。它們會引發 @ref{1c48,,UnsupportedOperation}。


在 3.1 版被加入.

@end deffn

@geindex read() (io.BufferedIOBase 的方法)
@anchor{library/io io BufferedIOBase read}@anchor{1529}
@deffn {方法} read (size=-1, /)

讀取並回傳最多 `size' 個位元組。如果引數被省略、為 @code{None} 或為負值，將讀取盡可能最多的位元組。

Fewer bytes may be returned than requested. An empty @ref{192,,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{f90,,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{2fc5,,RawIOBase.readall()}), otherwise will read in a loop until read
returns @code{None}, an empty @ref{192,,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{235,,BlockingIOError} or return @code{None} if no data is
available. @ref{83,,io} implementations return @code{None}.
@end quotation
@end cartouche
@end deffn

@geindex read1() (io.BufferedIOBase 的方法)
@anchor{library/io io BufferedIOBase read1}@anchor{2d09}
@deffn {方法} read1 (size=-1, /)

Read and return up to `size' bytes, calling @ref{1019,,readinto()}
which may retry if @ref{f82,,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{235,,BlockingIOError} or return @code{None} if no data is
available. @ref{83,,io} implementations return @code{None}.
@end quotation
@end cartouche
@end deffn

@geindex readinto() (io.BufferedIOBase 的方法)
@anchor{library/io io BufferedIOBase readinto}@anchor{180e}
@deffn {方法} readinto (b, /)

讀取位元組到一個預先分配的、可寫的 @ref{193,,bytes-like object} `b' 當中，並回傳讀取的位元組數量。例如，`b' 可能是一個 @ref{343,,bytearray}。

類似於 @ref{1529,,read()}，除非後者是互動式的，否則可能會對底層原始串流發出多次讀取。

如果底層原始串流處於非阻塞模式，且目前沒有可用資料，則會引發 @ref{235,,BlockingIOError}。
@end deffn

@geindex readinto1() (io.BufferedIOBase 的方法)
@anchor{library/io io BufferedIOBase readinto1}@anchor{1017}
@deffn {方法} readinto1 (b, /)

讀取位元組到一個預先分配的、可寫的 @ref{193,,bytes-like object} `b' 中，最多呼叫一次底層原始串流的 @ref{1018,,read()} （或 @ref{1019,,readinto()}）方法。此方法回傳讀取的位元組數量。

如果底層原始串流處於非阻塞模式，且目前沒有可用資料，則會引發 @ref{235,,BlockingIOError}。


在 3.5 版被加入.

@end deffn

@geindex write() (io.BufferedIOBase 的方法)
@anchor{library/io io BufferedIOBase write}@anchor{ed2}
@deffn {方法} write (b, /)

寫入給定的 @ref{193,,bytes-like object}，`b'，並回傳寫入的位元組數量（總是等於 `b' 的長度，以位元組計，因為如果寫入失敗將會引發 @ref{2c0,,OSError}）。根據實際的實作，這些位元組可能會立即寫入底層串流，或出於性能和延遲的緣故而被留在緩衝區當中。

當處於非阻塞模式時，如果需要將資料寫入原始串流，但它無法接受所有資料而不阻塞，則會引發 @ref{235,,BlockingIOError}。

呼叫者可以在此方法回傳後釋放或變更 `b'，因此實作應該僅在方法呼叫期間存取 `b'。
@end deffn
@end deffn

@node 原始檔案 I/O,Buffered Streams,I/O 基礎類別,類別階層
@anchor{library/io raw-file-i-o}@anchor{2fc6}
@subsubsection 原始檔案 I/O


@geindex FileIO (io 中的類別)
@anchor{library/io io FileIO}@anchor{1510}
@deffn {類別} io.FileIO (name, mode='r', closefd=True, opener=None)

一個代表包含位元組資料的 OS 層級檔案的原始二進制串流。它繼承自 @ref{12d1,,RawIOBase}。

`name' 可以是兩種事物之一：


@itemize *

@item 
代表將要打開的檔案路徑的一個字元串或 @ref{192,,bytes} 物件。在這種情況下，closefd 必須是 @code{True} （預設值），否則將引發錯誤。

@item 
an integer representing the number of an existing OS-level file descriptor
to which the resulting @ref{1510,,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{121b,,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{1018,,read()} (when called with a positive argument),
@ref{1019,,readinto()} and @ref{15a3,,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{f8d,,os.open} as `opener' results in functionality similar to passing
@code{None}).

The newly created file is @ref{10f7,,non-inheritable}.

See the @ref{315,,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.


@ref{1510,,FileIO} provides these data attributes in addition to those from
@ref{12d1,,RawIOBase} and @ref{500,,IOBase}:

@geindex mode (io.FileIO 的屬性)
@anchor{library/io io FileIO mode}@anchor{2fc7}
@deffn {屬性} mode

The mode as given in the constructor.
@end deffn

@geindex name (io.FileIO 的屬性)
@anchor{library/io io FileIO name}@anchor{2ca2}
@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,文字 I/O<2>,原始檔案 I/O,類別階層
@anchor{library/io buffered-streams}@anchor{2fc8}
@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{109f}
@deffn {類別} io.BytesIO (initial_bytes=b'@w{'})

A binary stream using an in-memory bytes buffer.  It inherits from
@ref{89c,,BufferedIOBase}.  The buffer is discarded when the
@ref{501,,close()} method is called.

The optional argument `initial_bytes' is a @ref{193,,bytes-like object} that
contains initial data.

@ref{109f,,BytesIO} provides or overrides these methods in addition to those
from @ref{89c,,BufferedIOBase} and @ref{500,,IOBase}:

@geindex getbuffer() (io.BytesIO 的方法)
@anchor{library/io io BytesIO getbuffer}@anchor{13f2}
@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 @ref{109f,,BytesIO} object cannot be
resized or closed.
@end quotation
@end cartouche


在 3.2 版被加入.

@end deffn

@geindex getvalue() (io.BytesIO 的方法)
@anchor{library/io io BytesIO getvalue}@anchor{2d07}
@deffn {方法} getvalue ()

Return @ref{192,,bytes} containing the entire contents of the buffer.
@end deffn

@geindex read1() (io.BytesIO 的方法)
@anchor{library/io io BytesIO read1}@anchor{2fc9}
@deffn {方法} read1 (size=-1, /)

In @ref{109f,,BytesIO}, this is the same as @ref{1529,,read()}.


在 3.7 版的變更: The `size' argument is now optional.

@end deffn

@geindex readinto1() (io.BytesIO 的方法)
@anchor{library/io io BytesIO readinto1}@anchor{2fca}
@deffn {方法} readinto1 (b, /)

In @ref{109f,,BytesIO}, this is the same as @ref{180e,,readinto()}.


在 3.5 版被加入.

@end deffn
@end deffn

@geindex BufferedReader (io 中的類別)
@anchor{library/io io BufferedReader}@anchor{140f}
@deffn {類別} io.BufferedReader (raw, buffer_size=DEFAULT_BUFFER_SIZE)

A buffered binary stream providing higher-level access to a readable, non
seekable @ref{12d1,,RawIOBase} raw binary stream.  It inherits from
@ref{89c,,BufferedIOBase}.

When reading data from this object, a larger amount of data may be
requested from the underlying raw stream, and kept in an internal buffer.
The buffered data can then be returned directly on subsequent reads.

The constructor creates a @ref{140f,,BufferedReader} for the given readable
`raw' stream and `buffer_size'.  If `buffer_size' is omitted,
@ref{198e,,DEFAULT_BUFFER_SIZE} is used.

@ref{140f,,BufferedReader} provides or overrides these methods in addition to
those from @ref{89c,,BufferedIOBase} and @ref{500,,IOBase}:

@geindex peek() (io.BufferedReader 的方法)
@anchor{library/io io BufferedReader peek}@anchor{2fcb}
@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{2fcc}
@deffn {方法} read (size=-1, /)

In @ref{140f,,BufferedReader} this is the same as @ref{1529,,io.BufferedIOBase.read()}
@end deffn

@geindex read1() (io.BufferedReader 的方法)
@anchor{library/io io BufferedReader read1}@anchor{2fcd}
@deffn {方法} read1 (size=-1, /)

In @ref{140f,,BufferedReader} this is the same as @ref{2d09,,io.BufferedIOBase.read1()}


在 3.7 版的變更: The `size' argument is now optional.

@end deffn
@end deffn

@geindex BufferedWriter (io 中的類別)
@anchor{library/io io BufferedWriter}@anchor{15a9}
@deffn {類別} io.BufferedWriter (raw, buffer_size=DEFAULT_BUFFER_SIZE)

A buffered binary stream providing higher-level access to a writeable, non
seekable @ref{12d1,,RawIOBase} raw binary stream.  It inherits from
@ref{89c,,BufferedIOBase}.

When writing to this object, data is normally placed into an internal
buffer.  The buffer will be written out to the underlying @ref{12d1,,RawIOBase}
object under various conditions, including:


@itemize *

@item 
when the buffer gets too small for all pending data;

@item 
when @ref{2fce,,flush()} is called;

@item 
when a @ref{148d,,seek()} is requested (for @ref{15aa,,BufferedRandom} objects);

@item 
when the @ref{15a9,,BufferedWriter} object is closed or destroyed.
@end itemize

The constructor creates a @ref{15a9,,BufferedWriter} for the given writeable
`raw' stream.  If the `buffer_size' is not given, it defaults to
@ref{198e,,DEFAULT_BUFFER_SIZE}.

@ref{15a9,,BufferedWriter} provides or overrides these methods in addition to
those from @ref{89c,,BufferedIOBase} and @ref{500,,IOBase}:

@geindex flush() (io.BufferedWriter 的方法)
@anchor{library/io io BufferedWriter flush}@anchor{2fce}
@deffn {方法} flush ()

Force bytes held in the buffer into the raw stream.  A
@ref{235,,BlockingIOError} should be raised if the raw stream blocks.
@end deffn

@geindex write() (io.BufferedWriter 的方法)
@anchor{library/io io BufferedWriter write}@anchor{2fcf}
@deffn {方法} write (b, /)

Write the @ref{193,,bytes-like object}, `b', and return the
number of bytes written.  When in non-blocking mode, a
@ref{235,,BlockingIOError} with @ref{25ac,,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{15aa}
@deffn {類別} io.BufferedRandom (raw, buffer_size=DEFAULT_BUFFER_SIZE)

A buffered binary stream providing higher-level access to a seekable
@ref{12d1,,RawIOBase} raw binary stream.  It inherits from @ref{140f,,BufferedReader}
and @ref{15a9,,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{198e,,DEFAULT_BUFFER_SIZE}.

@ref{15aa,,BufferedRandom} is capable of anything @ref{140f,,BufferedReader} or
@ref{15a9,,BufferedWriter} can do.  In addition, @ref{148d,,seek()} and
@ref{15a4,,tell()} are guaranteed to be implemented.
@end deffn

@geindex BufferedRWPair (io 中的類別)
@anchor{library/io io BufferedRWPair}@anchor{15ab}
@deffn {類別} io.BufferedRWPair (reader, writer, buffer_size=DEFAULT_BUFFER_SIZE, /)

A buffered binary stream providing higher-level access to two non seekable
@ref{12d1,,RawIOBase} raw binary streams---one readable, the other writeable.
It inherits from @ref{89c,,BufferedIOBase}.

`reader' and `writer' are @ref{12d1,,RawIOBase} objects that are readable and
writeable respectively.  If the `buffer_size' is omitted it defaults to
@ref{198e,,DEFAULT_BUFFER_SIZE}.

@ref{15ab,,BufferedRWPair} implements all of @ref{89c,,BufferedIOBase}'s methods
except for @ref{2c9e,,detach()}, which raises
@ref{1c48,,UnsupportedOperation}.

@cartouche
@quotation 警告 
@ref{15ab,,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{15aa,,BufferedRandom} instead.
@end quotation
@end cartouche
@end deffn

@node 文字 I/O<2>,,Buffered Streams,類別階層
@anchor{library/io id1}@anchor{2fd0}
@subsubsection 文字 I/O


@geindex TextIOBase (io 中的類別)
@anchor{library/io io TextIOBase}@anchor{89d}
@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{500,,IOBase}.

@ref{89d,,TextIOBase} provides or overrides these data attributes and
methods in addition to those from @ref{500,,IOBase}:

@geindex encoding (io.TextIOBase 的屬性)
@anchor{library/io io TextIOBase encoding}@anchor{2fd1}
@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{150f}
@deffn {屬性} errors

The error setting of the decoder or encoder.
@end deffn

@geindex newlines (io.TextIOBase 的屬性)
@anchor{library/io io TextIOBase newlines}@anchor{2fd2}
@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{14a4}
@deffn {屬性} buffer

底層的二進位緩衝（一個 @ref{89c,,BufferedIOBase} 或 @ref{12d1,,RawIOBase} 實例），為 @ref{89d,,TextIOBase} 處理的對象。這不是 @ref{89d,,TextIOBase} API 的一部分，且在某些實作可能不存在。
@end deffn

@geindex detach() (io.TextIOBase 的方法)
@anchor{library/io io TextIOBase detach}@anchor{2fd3}
@deffn {方法} detach ()

Separate the underlying binary buffer from the @ref{89d,,TextIOBase} and
return it.

After the underlying buffer has been detached, the @ref{89d,,TextIOBase} is
in an unusable state.

Some @ref{89d,,TextIOBase} implementations, like @ref{1124,,StringIO}, may not
have the concept of an underlying buffer and calling this method will
raise @ref{1c48,,UnsupportedOperation}.


在 3.1 版被加入.

@end deffn

@geindex read() (io.TextIOBase 的方法)
@anchor{library/io io TextIOBase read}@anchor{1f33}
@deffn {方法} read (size=-1, /)

Read and return at most `size' characters from the stream as a single
@ref{169,,str}.  If `size' is negative or @code{None}, reads until EOF.
@end deffn

@geindex readline() (io.TextIOBase 的方法)
@anchor{library/io io TextIOBase readline}@anchor{1f6d}
@deffn {方法} readline (size=-1, /)

Read until newline or EOF and return a single @ref{169,,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{2fd4}
@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{2fd5,,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.


在 3.1 版被加入: @code{SEEK_*} 常數。

@end deffn

@geindex tell() (io.TextIOBase 的方法)
@anchor{library/io io TextIOBase tell}@anchor{2fd5}
@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{1f22}
@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{9b7}
@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{89c,,BufferedIOBase} buffered binary stream.  It inherits from
@ref{89d,,TextIOBase}.

`encoding' gives the name of the encoding that the stream will be decoded or
encoded with.  In @ref{85f,,UTF-8 Mode}, this defaults to UTF-8.
Otherwise, it defaults to @ref{328,,locale.getencoding()}.
@code{encoding="locale"} can be used to specify the current locale's encoding
explicitly. See @ref{9b9,,文字編碼} 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{2eb,,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{168f,,codecs.register_error()} is also valid.

@geindex universal newlines;io.TextIOWrapper 類別

`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{f30,,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{2487,,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{2b99,,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{ed2,,write()} are guaranteed
not to be buffered: any data written on the @ref{9b7,,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{327,,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{235,,BlockingIOError}
may be raised if a read operation cannot be completed immediately.
@end quotation
@end cartouche

@ref{9b7,,TextIOWrapper} provides these data attributes and methods in
addition to those from @ref{89d,,TextIOBase} and @ref{500,,IOBase}:

@geindex line_buffering (io.TextIOWrapper 的屬性)
@anchor{library/io io TextIOWrapper line_buffering}@anchor{2fd6}
@deffn {屬性} line_buffering

Whether line buffering is enabled.
@end deffn

@geindex write_through (io.TextIOWrapper 的屬性)
@anchor{library/io io TextIOWrapper write_through}@anchor{2fd7}
@deffn {屬性} write_through

Whether writes are passed immediately to the underlying binary
buffer.


在 3.7 版被加入.

@end deffn

@geindex reconfigure() (io.TextIOWrapper 的方法)
@anchor{library/io io TextIOWrapper reconfigure}@anchor{d38}
@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.


在 3.7 版被加入.



在 3.11 版的變更: The method supports @code{encoding="locale"} option.

@end deffn

@geindex seek() (io.TextIOWrapper 的方法)
@anchor{library/io io TextIOWrapper seek}@anchor{2fd8}
@deffn {方法} seek (cookie, whence=os.SEEK_SET, /)

Set the stream position.
Return the new stream position as an @ref{19b,,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{2fd9,,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{148e,,os.SEEK_SET}, @ref{148f,,os.SEEK_CUR}, and @ref{1490,,os.SEEK_END}.

@end deffn

@geindex tell() (io.TextIOWrapper 的方法)
@anchor{library/io io TextIOWrapper tell}@anchor{2fd9}
@deffn {方法} tell ()

Return the stream position as an opaque number.
The return value of @code{tell()} can be given as input to @ref{2fd8,,seek()},
to restore a previous stream position.
@end deffn
@end deffn

@geindex StringIO (io 中的類別)
@anchor{library/io io StringIO}@anchor{1124}
@deffn {類別} io.StringIO (initial_value='@w{'}, newline='\n')

A text stream using an in-memory text buffer.  It inherits from
@ref{89d,,TextIOBase}.

The text buffer is discarded when the @ref{501,,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{1f22,,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{9b7,,TextIOWrapper},
except that when writing output to the stream, if `newline' is @code{None},
newlines are written as @code{\n} on all platforms.

@ref{1124,,StringIO} provides this method in addition to those from
@ref{89d,,TextIOBase} and @ref{500,,IOBase}:

@geindex getvalue() (io.StringIO 的方法)
@anchor{library/io io StringIO getvalue}@anchor{2fda}
@deffn {方法} getvalue ()

Return a @ref{169,,str} containing the entire contents of the buffer.
Newlines are decoded as if by @ref{1f33,,read()}, although
the stream position is not changed.
@end deffn

使用範例：

@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 類別

@geindex IncrementalNewlineDecoder (io 中的類別)
@anchor{library/io io IncrementalNewlineDecoder}@anchor{198f}
@deffn {類別} io.IncrementalNewlineDecoder

A helper codec that decodes newlines for @ref{f30,,universal newlines} mode.
It inherits from @ref{26e4,,codecs.IncrementalDecoder}.
@end deffn

@node Static Typing,Performance,類別階層,io — 處理資料串流的核心工具
@anchor{library/io static-typing}@anchor{2fdb}
@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{66d,,@@typing.runtime_checkable}.

@geindex Reader (io 中的類別)
@anchor{library/io io Reader}@anchor{236}
@deffn {類別} io.Reader [T]

Generic protocol for reading from a file or other input stream. @code{T} will
usually be @ref{169,,str} or @ref{192,,bytes}, but can be any type that is
read from the stream.


在 3.14 版被加入.


@geindex read() (io.Reader 的方法)
@anchor{library/io io Reader read}@anchor{2fdc}
@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

例如：

@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{237}
@deffn {類別} io.Writer [T]

Generic protocol for writing to a file or other output stream. @code{T} will
usually be @ref{169,,str} or @ref{192,,bytes}, but can be any type that can be
written to the stream.


在 3.14 版被加入.


@geindex write() (io.Writer 的方法)
@anchor{library/io io Writer write}@anchor{2fdd}
@deffn {方法} write (data, /)

Write `data' to the output stream and return the number of items
(bytes/characters) written.
@end deffn

例如：

@example
def write_binary(writer: Writer[bytes]):
    writer.write(b"Hello world!\n")
@end example
@end deffn

See @ref{2fde,,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,,Static Typing,io — 處理資料串流的核心工具
@anchor{library/io performance}@anchor{2fdf}
@subsubsection Performance


This section discusses the performance of the provided concrete I/O
implementations.

@menu
* 二進位 (Binary) I/O: 二進位 Binary I/O<2>. 
* 文字 I/O: 文字 I/O<3>. 
* Multi-threading: Multi-threading<2>. 
* Reentrancy:: 

@end menu

@node 二進位 Binary I/O<2>,文字 I/O<3>,,Performance
@anchor{library/io id2}@anchor{2fe0}
@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 文字 I/O<3>,Multi-threading<2>,二進位 Binary I/O<2>,Performance
@anchor{library/io id3}@anchor{2fe1}
@subsubsection 文字 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{2fd5,,tell()} and @ref{2fd4,,seek()} are both quite slow
due to the reconstruction algorithm used.

@ref{1124,,StringIO}, however, is a native in-memory unicode container and will
exhibit similar speed to @ref{109f,,BytesIO}.

@node Multi-threading<2>,Reentrancy,文字 I/O<3>,Performance
@anchor{library/io multi-threading}@anchor{2fe2}
@subsubsection Multi-threading


@ref{1510,,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{140f,,BufferedReader},
@ref{15a9,,BufferedWriter}, @ref{15aa,,BufferedRandom} and @ref{15ab,,BufferedRWPair})
protect their internal structures using a lock; it is therefore safe to call
them from multiple threads at once.

@ref{9b7,,TextIOWrapper} objects are not thread-safe.

@node Reentrancy,,Multi-threading<2>,Performance
@anchor{library/io reentrancy}@anchor{2fe3}
@subsubsection Reentrancy


Binary buffered objects (instances of @ref{140f,,BufferedReader},
@ref{15a9,,BufferedWriter}, @ref{15aa,,BufferedRandom} and @ref{15ab,,BufferedRWPair})
are not reentrant.  While reentrant calls will not happen in normal situations,
they can arise from doing I/O in a @ref{cb,,signal} handler.  If a thread tries to
re-enter a buffered object which it is already accessing, a @ref{244,,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{315,,open()} function
will wrap a buffered object inside a @ref{9b7,,TextIOWrapper}.  This includes
standard streams and therefore affects the built-in @ref{1170,,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 --- Python 的日誌記錄工具,io — 處理資料串流的核心工具,通用作業系統服務
@anchor{library/time doc}@anchor{2fe4}@anchor{library/time module-time}@anchor{f4}@anchor{library/time time-time-access-and-conversions}@anchor{2fe5}@anchor{library/time translation-repo}@anchor{2fe6}
@subsection @code{time} --- 時間存取與轉換


@geindex module; time


__________________________________________________________________


這個模組提供了各種與時間相關的函式。若要查看相關功能，請參閱 @ref{34,,datetime} 和 @ref{15,,calendar} 模組。

雖然這個模組隨時可用，但並非所有函式在所有平台上都可用。這個模組中定義的大多數函式都會呼叫 C 語言平台的函式庫中具有相同名稱的函式。由於這些函式的語義因平台而異，所以偶爾查閱平台文件可能會有所幫助。

以下是對一些術語和慣例的說明。

@geindex epoch（紀元）
@anchor{library/time epoch}@anchor{2dc6}

@itemize *

@item 
`epoch' 是起始的時間點，即 @code{time.gmtime(0)} 的回傳值。在所有平台上，它是 1970 年 1 月 1 日，00:00:00（UTC）。
@end itemize

@geindex 紀元秒數


@itemize *

@item 
術語 `seconds since the epoch（紀元秒數）' 是指從 epoch（紀元）開始經過的總秒數，通常不包括 leap seconds@footnote{https://en.wikipedia.org/wiki/Leap_second}。在所有符合 POSIX 標準的平台上，leap seconds （閏秒）都不計入這個總數。
@end itemize

@geindex Year 2038（2038 年問題）


@itemize *

@item 
這個模組中的函式可能無法處理 @ref{2dc6,,epoch} 之前或遙遠未來的日期和時間。未來的臨界點由 C 函式庫決定；對於 32 位元系統來說通常是在 2038 年。
@end itemize

@geindex 2-digit years（2 位數年份）


@itemize *

@item 
函式 @ref{1624,,strptime()} 在給定 @code{%y} 格式碼時可以剖析 (parse) 兩位數的年份。當剖析兩位數的年份時，它們會根據 POSIX 和 ISO C 標準進行轉換：69--99 的值對映到 1969--1999，0--68 的值對映到 2000--2068。
@end itemize

@geindex UTC
@geindex Coordinated Universal Time（世界協調時間）
@geindex Greenwich Mean Time（格林威治標準時間）


@itemize *

@item 
UTC is Coordinated Universal Time@footnote{https://en.wikipedia.org/wiki/Coordinated_Universal_Time} and superseded Greenwich Mean Time@footnote{https://en.wikipedia.org/wiki/Greenwich_Mean_Time} or
GMT as the basis of international timekeeping. The acronym UTC is not a
mistake but conforms to an earlier, language-agnostic naming scheme for time
standards such as UT0, UT1, and UT2.
@end itemize

@geindex Daylight Saving Time（日光節約時間）


@itemize *

@item 
DST 是 Daylight Saving Time（日光節約時間），一年中的某些時段（通常）將會時區調整一小時。DST 的規則是根據當地法律決定的，且可能每年不同。C 函式庫有一個包含當地規則的表（通常會為了靈活性而從系統文件中讀取），在這方面是唯一的真正依據。

@item 
各種即時 (real-time) 函式的精確度可能低於其值或引數所表示的單位所建議的精確度。例如，在大多數 Unix 系統上，時鐘每秒只「跳」50 次或 100 次。

@item 
另一方面，@ref{557,,time()} 和 @ref{8a4,,sleep()} 的精確度比它們的在 Unix 的等效函式更高：時間以浮點數表示，@ref{557,,time()} 回傳最精確的可用時間（如果可以會使用 Unix 的 @code{gettimeofday()}），而 @ref{8a4,,sleep()} 可以接受帶有非零分數的時間（如果可以會使用 Unix 的 @code{select()} 來實作）。

@item 
由 @ref{13c1,,gmtime()}、@ref{16ed,,localtime()} 和 @ref{1624,,strptime()} 回傳，並由 @ref{13e8,,asctime()}、@ref{13e9,,mktime()} 和 @ref{13ea,,strftime()} 接受的時間值，是一個 9 個整數的序列。@ref{13c1,,gmtime()}、@ref{16ed,,localtime()} 和 @ref{1624,,strptime()} 的回傳值也為各個欄位提供屬性名稱。

關於這些物件的敘述請見 @ref{ee1,,struct_time}。


在 3.3 版的變更: 當平台支援對應的 @code{struct tm} 成員時，@ref{ee1,,struct_time} 型別被擴展以提供 @ref{2fe7,,tm_gmtoff} 和 @ref{2fe8,,tm_zone} 屬性。



在 3.6 版的變更: @ref{ee1,,struct_time} 的屬性 @ref{2fe7,,tm_gmtoff} 和 @ref{2fe8,,tm_zone} 現在在所有平台上都可用。


@item 
使用以下函式在時間表示之間進行轉換：


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

轉換來源

@tab

轉換目標

@tab

使用

@item

紀元秒數

@tab

世界協調時間的 @ref{ee1,,struct_time}

@tab

@ref{13c1,,gmtime()}

@item

紀元秒數

@tab

本地時間的 @ref{ee1,,struct_time}

@tab

@ref{16ed,,localtime()}

@item

世界協調時間的 @ref{ee1,,struct_time}

@tab

紀元秒數

@tab

@ref{27f6,,calendar.timegm()}

@item

本地時間的 @ref{ee1,,struct_time}

@tab

紀元秒數

@tab

@ref{13e9,,mktime()}

@end multitable

@end itemize

@menu
* 函式: 函式<5>. 
* 時鐘 ID 常數:: 
* 時區常數:: 

@end menu

@node 函式<5>,時鐘 ID 常數,,time --- 時間存取與轉換
@anchor{library/time functions}@anchor{2fe9}@anchor{library/time time-functions}@anchor{2fea}
@subsubsection 函式


@geindex asctime() (於 time 模組中)
@anchor{library/time time asctime}@anchor{13e8}
@deffn {函式} time.asctime ([t])

將由 @ref{13c1,,gmtime()} 或 @ref{16ed,,localtime()} 回傳的元組或 @ref{ee1,,struct_time} 表示的時間轉換為以下格式的字串：@code{'Sun Jun 20 23:21:05 1993'}。日期欄位為兩個字元長，如果日期是個位數，則用空格填充，例如：@code{'Wed Jun  9 04:26:40 1993'}。

如果沒有提供 `t'，則使用由 @ref{16ed,,localtime()} 回傳的目前時間。@ref{13e8,,asctime()} 不使用區域資訊。

@cartouche
@quotation 備註 
與同名的 C 函式不同，@ref{13e8,,asctime()} 不會添加結尾的換行字元。
@end quotation
@end cartouche
@end deffn

@geindex pthread_getcpuclockid() (於 time 模組中)
@anchor{library/time time pthread_getcpuclockid}@anchor{d86}
@deffn {函式} time.pthread_getcpuclockid (thread_id)

為指定的 `thread_id' 回傳執行緒專用 CPU-time 時鐘的 `clk_id'。

使用 @ref{135b,,threading.get_ident()} 或 @ref{176,,threading.Thread} 物件的 @ref{2feb,,ident} 屬性來取得適用於 `thread_id' 的值。

@cartouche
@quotation 警告 
傳遞無效或過期的 `thread_id' 可能會導致未定義的行為，例如分段錯誤 (segmentation fault)。
@end quotation
@end cartouche

@ref{2006,,可用性}: Unix

若需更多資訊，請參閱 @code{pthread_getcpuclockid(3)@footnote{https://manpages.debian.org/pthread_getcpuclockid(3)}} 的說明文件。


在 3.7 版被加入.

@end deffn

@geindex clock_getres() (於 time 模組中)
@anchor{library/time time clock_getres}@anchor{135e}
@deffn {函式} time.clock_getres (clk_id)

回傳指定時鐘 `clk_id' 的解析度（精確度）。有關 `clk_id' 可接受的值的串列，請參閱 @ref{2f5f,,時鐘 ID 常數}。

@ref{2006,,可用性}: Unix.


在 3.3 版被加入.

@end deffn

@geindex clock_gettime() (於 time 模組中)
@anchor{library/time time clock_gettime}@anchor{135f}
@deffn {函式} time.clock_gettime (clk_id) -> float

回傳指定時鐘 `clk_id' 的時間。有關 `clk_id' 可接受的值的串列，請參閱 @ref{2f5f,,時鐘 ID 常數}。

使用 @ref{cd2,,clock_gettime_ns()} 以避免 @ref{196,,float} 型別造成的精確度損失。

@ref{2006,,可用性}: Unix.


在 3.3 版被加入.

@end deffn

@geindex clock_gettime_ns() (於 time 模組中)
@anchor{library/time time clock_gettime_ns}@anchor{cd2}
@deffn {函式} time.clock_gettime_ns (clk_id) -> int

類似於 @ref{135f,,clock_gettime()}，但回傳以奈秒 (nanoseconds) 為單位的時間。

@ref{2006,,可用性}: Unix.


在 3.7 版被加入.

@end deffn

@geindex clock_settime() (於 time 模組中)
@anchor{library/time time clock_settime}@anchor{1360}
@deffn {函式} time.clock_settime (clk_id, time: float)

設定指定時鐘 `clk_id' 的時間。目前，@ref{8a1,,CLOCK_REALTIME} 是 `clk_id' 唯一可以接受的值。

使用 @ref{cd3,,clock_settime_ns()} 以避免 @ref{196,,float} 型別造成的精確度損失。

@ref{2006,,可用性}: Unix, not Android, not iOS.


在 3.3 版被加入.

@end deffn

@geindex clock_settime_ns() (於 time 模組中)
@anchor{library/time time clock_settime_ns}@anchor{cd3}
@deffn {函式} time.clock_settime_ns (clk_id, time: int)

類似於 @ref{1360,,clock_settime()}，但設定以奈秒為單位的時間。

@ref{2006,,可用性}: Unix, not Android, not iOS.


在 3.7 版被加入.

@end deffn

@geindex ctime() (於 time 模組中)
@anchor{library/time time ctime}@anchor{2772}
@deffn {函式} time.ctime ([secs])

將自 @ref{2dc6,,epoch} 起以秒表示的時間轉換為表示當地時間且符合以下格式的字串：@code{'Sun Jun 20 23:21:05 1993'}。日期欄位為兩個字元長，如果日期是個位數，則用空格填充，例如：@code{'Wed Jun  9 04:26:40 1993'}。

如果未提供 `secs' 或其為 @ref{87e,,None}，則使用由 @ref{557,,time()} 回傳的目前時間。@code{ctime(secs)} 等同於 @code{asctime(localtime(secs))}。@ref{2772,,ctime()} 不使用區域資訊。
@end deffn

@geindex get_clock_info() (於 time 模組中)
@anchor{library/time time get_clock_info}@anchor{135d}
@deffn {函式} time.get_clock_info (name)

取得指定時鐘的資訊作為命名空間物件。支援的時鐘名稱及讀取他們的值的對應函式如下：


@itemize *

@item 
@code{'monotonic'}：@ref{556,,time.monotonic()}

@item 
@code{'perf_counter'}：@ref{c71,,time.perf_counter()}

@item 
@code{'process_time'}：@ref{c72,,time.process_time()}

@item 
@code{'thread_time'}：@ref{b27,,time.thread_time()}

@item 
@code{'time'}：@ref{557,,time.time()}
@end itemize

其結果具有以下屬性：


@itemize -

@item 
`adjustable': 如果時鐘可以設定為向前或向後跳轉時間則為 @code{True}，否則為 @code{False}。不指漸進式的 NTP 速率調整。

@item 
`implementation': 用於取得時鐘的值的底層 C 函式名稱。有關可能的值，請參閱 @ref{2f5f,,時鐘 ID 常數}。

@item 
`monotonic': 如果時鐘不能倒轉，則為 @code{True}，否則為 @code{False}

@item 
`resolution': 以秒 (@ref{196,,float}) 為單位的時鐘的解析度
@end itemize


在 3.3 版被加入.

@end deffn

@geindex gmtime() (於 time 模組中)
@anchor{library/time time gmtime}@anchor{13c1}
@deffn {函式} time.gmtime ([secs])

將自 @ref{2dc6,,epoch} 起以秒表示的時間轉換為 UTC 中的 @ref{ee1,,struct_time}，其中 dst 旗標始終為零。如果未提供 `secs' 或其為 @ref{87e,,None}，則使用由 @ref{557,,time()} 回傳的目前時間。忽略秒的分數部分。關於 @ref{ee1,,struct_time} 物件的描述，請參閱上文。此函式的反運算請參閱 @ref{27f6,,calendar.timegm()}。
@end deffn

@geindex localtime() (於 time 模組中)
@anchor{library/time time localtime}@anchor{16ed}
@deffn {函式} time.localtime ([secs])

類似於 @ref{13c1,,gmtime()}，但轉換為當地時間。如果未提供 `secs' 或其為 @ref{87e,,None}，則使用由 @ref{557,,time()} 回傳的目前時間。當 DST 適用於給定時間時，dst 旗標會被設定為 @code{1}。

如果時間戳超出 C 平台的 @code{localtime()} 或 @code{gmtime()} 函式支援的範圍，@ref{16ed,,localtime()} 可能會引發 @ref{a78,,OverflowError}；在 @code{localtime()} 或 @code{gmtime()} 失敗時，會引發 @ref{2c0,,OSError}。通常會把年份限制在 1970 年到 2038 年之間。
@end deffn

@geindex mktime() (於 time 模組中)
@anchor{library/time time mktime}@anchor{13e9}
@deffn {函式} time.mktime (t)

這是 @ref{16ed,,localtime()} 的反函式。其引數是表示`當地'時間（不是 UTC）的 @ref{ee1,,struct_time} 或完整的 9 元組（因為需要 dst 旗標；如果 dst 為未知，則使用 @code{-1} 作為 dst 旗標）。它回傳一個浮點數，以與 @ref{557,,time()} 相容。如果輸入值不能表示為有效時間，將引發 @ref{a78,,OverflowError} 或 @ref{2eb,,ValueError}（取決於無效值是被 Python 還是底層 C 函式庫捕獲）。它能生成時間的最早日期根據平台而有所不同。
@end deffn

@geindex monotonic() (於 time 模組中)
@anchor{library/time time monotonic}@anchor{556}
@deffn {函式} time.monotonic () -> float

回傳單調時鐘（monotonic clock，即不能倒轉的時鐘）的值（以帶有小數的秒數表示）。該時鐘不受系統時鐘更新的影響。回傳值的參考點沒有定義，因此只有兩次呼叫結果之間的差異才是有效的。

時鐘：


@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{cd4,,monotonic_ns()} 以避免 @ref{196,,float} 型別造成的精確度損失。


在 3.3 版被加入.



在 3.5 版的變更: 此函式現在始終可用且時鐘對於所有行程都會是相同。



在 3.10 版的變更: 在 macOS 上，時鐘對於所有行程都會是相同。

@end deffn

@geindex monotonic_ns() (於 time 模組中)
@anchor{library/time time monotonic_ns}@anchor{cd4}
@deffn {函式} time.monotonic_ns () -> int

類似於 @ref{556,,monotonic()}，但回傳以奈秒為單位的時間。


在 3.7 版被加入.

@end deffn

@geindex perf_counter() (於 time 模組中)
@anchor{library/time time perf_counter}@anchor{c71}
@deffn {函式} time.perf_counter () -> float

@geindex benchmarking（基準測試）

回傳性能計數器的值（以帶有小數的秒數表示），即具有最高可用解析度來測量短時間間隔的時鐘。它包括睡眠時經過的時間，且時鐘對於所有行程都會是相同。回傳值的參考點沒有定義，因此只有兩次呼叫結果之間的差異才是有效的。

在 CPython 上，使用與 @ref{556,,time.monotonic()} 相同的時鐘，且其為單調時鐘（即不能倒轉的時鐘）。

使用 @ref{cd5,,perf_counter_ns()} 以避免 @ref{196,,float} 型別造成的精確度損失。


在 3.3 版被加入.



在 3.10 版的變更: 在 Windows 上，時鐘對於所有行程都會是相同。



在 3.13 版的變更: 使用與 @ref{556,,time.monotonic()} 相同的時鐘。

@end deffn

@geindex perf_counter_ns() (於 time 模組中)
@anchor{library/time time perf_counter_ns}@anchor{cd5}
@deffn {函式} time.perf_counter_ns () -> int

類似於 @ref{c71,,perf_counter()}，但回傳以奈秒為單位的時間。


在 3.7 版被加入.

@end deffn

@geindex process_time() (於 time 模組中)
@anchor{library/time time process_time}@anchor{c72}
@deffn {函式} time.process_time () -> float

@geindex CPU time（CPU 時間）
@geindex processor time（處理器時間）
@geindex benchmarking（基準測試）

回傳目前行程的系統和用戶 CPU 時間之和（以帶有小數的秒數表示）。它不包括睡眠時經過的時間。根據定義，它涵蓋整個行程。回傳值的參考點沒有定義，因此只有兩次呼叫結果之間的差異才是有效的。

使用 @ref{cd6,,process_time_ns()} 以避免 @ref{196,,float} 型別造成的精確度損失。


在 3.3 版被加入.

@end deffn

@geindex process_time_ns() (於 time 模組中)
@anchor{library/time time process_time_ns}@anchor{cd6}
@deffn {函式} time.process_time_ns () -> int

類似於 @ref{c72,,process_time()}，但回傳以奈秒為單位的時間。


在 3.7 版被加入.

@end deffn

@geindex sleep() (於 time 模組中)
@anchor{library/time time sleep}@anchor{8a4}
@deffn {函式} time.sleep (secs)

在一個給定的秒數內暫停呼叫執行緒 (calling thread) 的執行。引數可以是浮點數，以表示更精確的睡眠時間。

如果睡眠被訊號中斷且訊號處理器未引發例外，則睡眠將以重新計算過的逾時 (timeout) 重新開始。

由於系統中其他活動的調度，暫停時間可能會比請求的時間長任意的量。

@subsubheading Windows 實作


在 Windows 上，如果 `secs' 為零，則執行緒將其剩餘的時間片段讓給任何準備運行的其他執行緒。如果沒有其他執行緒準備運行，該函式將立即回傳，而執行緒會繼續執行。在 Windows 8.1 及更新的版本中，此實作使用高解析度計時器@footnote{https://learn.microsoft.com/windows-hardware/drivers/kernel/high-resolution-timers}，其解析度為 100 奈秒。如果 `secs' 為零，則使用 @code{Sleep(0)}。

@subsubheading Unix 實作



@itemize *

@item 
如果可以，使用 @code{clock_nanosleep()}（解析度：1 奈秒）；

@item 
或者使用 @code{nanosleep()}（解析度：1 奈秒）；

@item 
或使用 @code{select()}（解析度：1 微秒）。
@end itemize

@cartouche
@quotation 備註 
要模擬「無動作 (no-op)」，請使用 @ref{17e,,pass} 而不是 @code{time.sleep(0)}。

To voluntarily relinquish the CPU, specify a real-time @ref{2fa6,,scheduling policy} and use @ref{1312,,os.sched_yield()} instead.
@end quotation
@end cartouche

引發一個帶有引數 @code{secs} 的@ref{1b70,,稽核事件 (auditing event)} @code{time.sleep}。


在 3.5 版的變更: 即使睡眠被訊號中斷，此函式現在至少還是會睡眠 `secs'，除非訊號處理器引發例外（理由請參閱 
@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 版的變更: 引發一個稽核事件。

@end deffn

@geindex % （百分號）;datetime format（日期時間格式）

@geindex strftime() (於 time 模組中)
@anchor{library/time time strftime}@anchor{13ea}
@deffn {函式} time.strftime (format[, t])

將由 @ref{13c1,,gmtime()} 或 @ref{16ed,,localtime()} 回傳代表時間的一個元組或 @ref{ee1,,struct_time} 轉換為由 `format' 引數指定的字串。如果未提供 `t'，則使用由 @ref{16ed,,localtime()} 回傳的目前時間。`format' 必須是一個字串。如果 `t' 中的任何欄位超出允許範圍，將會引發 @ref{2eb,,ValueError}。

0 在時間元組中的任何位置都是合法引數；如果元組中出現常見的錯誤，該值將被強制更改為正確的值。

以下指令可以嵌入在 `format' 字串中。它們顯示時不帶可選的欄位寬度和精度規範，並在 @ref{13ea,,strftime()} 的結果中被標示的字元替換：


@multitable {xxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxx} 
@headitem

指令

@tab

意義

@tab

註解

@item

@code{%a}

@tab

區域設定的週間日 (weekday) 縮寫名稱。

@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 代表十進位的小時數碼 (digits)，M 代表十進位的分鐘數碼 [-23:59, +23:59]。 @footnote{
現在 @code{%Z} 已被棄用，@code{%z} 藉由擴展為偏好的小時/分鐘偏移而逃離了被棄用的命運，但其並不是被所有 ANSI C 函式庫支援。此外，嚴格按照 1982 年的 
@geindex RFC; RFC 822
@uref{https://datatracker.ietf.org/doc/html/rfc822.html,RFC 822} 標準，應該使用兩位數年份（@code{%y} 而不是 @code{%Y}），但實作中在 2000 年之前就已經轉向使用四位數年份。之後，
@geindex RFC; RFC 822
@uref{https://datatracker.ietf.org/doc/html/rfc822.html,RFC 822} 被淘汰，四位數年份首先由 
@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} 正式批准。
}

@tab

@item

@code{%Z}

@tab

時區名稱（如果不存在時區，則無字元）。已被棄用。 @footnote{
現在 @code{%Z} 已被棄用，@code{%z} 藉由擴展為偏好的小時/分鐘偏移而逃離了被棄用的命運，但其並不是被所有 ANSI C 函式庫支援。此外，嚴格按照 1982 年的 
@geindex RFC; RFC 822
@uref{https://datatracker.ietf.org/doc/html/rfc822.html,RFC 822} 標準，應該使用兩位數年份（@code{%y} 而不是 @code{%Y}），但實作中在 2000 年之前就已經轉向使用四位數年份。之後，
@geindex RFC; RFC 822
@uref{https://datatracker.ietf.org/doc/html/rfc822.html,RFC 822} 被淘汰，四位數年份首先由 
@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} 正式批准。
}

@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{1624,,strptime()}，不適用於 @ref{13ea,,strftime()}。然而，在 @ref{18b7,,datetime.datetime.strptime()} 和 @ref{e89,,datetime.datetime.strftime()} 其中的 @code{%f} 格式的指令@ref{2744,,適用於微秒}。

@item 
當與 @ref{1624,,strptime()} 函式一起使用時，@code{%p} 指令僅在使用 @code{%I} 指令剖析小時時影響輸出小時的欄位。
@end enumerate
@anchor{library/time leap-second}@anchor{2fec}

@enumerate 3

@item 
範圍確實是從 @code{0} 到 @code{61}；數值 @code{60} 在表示 leap seconds@footnote{https://en.wikipedia.org/wiki/Leap_second} 的時間戳中是有效的，而數值 @code{61} 是出於歷史因素而被支援。

@item 
當與 @ref{1624,,strptime()} 函式一起使用時，@code{%U} 和 @code{%W} 僅在指定週間的某天和年份時用於計算中。
@end enumerate

以下是一個範例，其為一種與 
@geindex RFC; RFC 2822
RFC 2822@footnote{https://datatracker.ietf.org/doc/html/rfc2822.html} 網際網路電子郵件標準中指定的日期格式兼容的格式。 @footnote{
現在 @code{%Z} 已被棄用，@code{%z} 藉由擴展為偏好的小時/分鐘偏移而逃離了被棄用的命運，但其並不是被所有 ANSI C 函式庫支援。此外，嚴格按照 1982 年的 
@geindex RFC; RFC 822
@uref{https://datatracker.ietf.org/doc/html/rfc822.html,RFC 822} 標準，應該使用兩位數年份（@code{%y} 而不是 @code{%Y}），但實作中在 2000 年之前就已經轉向使用四位數年份。之後，
@geindex RFC; RFC 822
@uref{https://datatracker.ietf.org/doc/html/rfc822.html,RFC 822} 被淘汰，四位數年份首先由 
@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} 正式批准。
}：

@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{'%'} 之後；這也是不可攜 (portable) 的。欄位寬度通常為 2，除了 @code{%j} 為 3。
@end deffn

@geindex % （百分號）;datetime format（日期時間格式）

@geindex strptime() (於 time 模組中)
@anchor{library/time time strptime}@anchor{1624}
@deffn {函式} time.strptime (string[, format])

根據格式剖析表示時間的字串。回傳值是 @ref{ee1,,struct_time}，如同由 @ref{13c1,,gmtime()} 或 @ref{16ed,,localtime()} 回傳的一樣。

`format' 參數使用與 @ref{13ea,,strftime()} 相同的指令；預設為 @code{"%a %b %d %H:%M:%S %Y"}，與 @ref{2772,,ctime()} 回傳的格式匹配。如果 `string' 無法根據 `format' 解析，或剖析後有多餘的資料，將引發 @ref{2eb,,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} 是否為 true。因此，除了識別始終已知的 UTC 和 GMT（且被考慮為非日光節約時區）外，這是特定於平台的。

僅支援文件中指定的指令。由於 @code{strftime()} 是根據每個平台實作的，有時它可以提供比列出的還要更多的指令。但是 @code{strptime()} 與任何平台無關，因此不一定支援所有未記載為支援的指令。
@end deffn

@geindex struct_time (time 中的類別)
@anchor{library/time time struct_time}@anchor{ee1}
@deffn {類別} time.struct_time

由 @ref{13c1,,gmtime()}、@ref{16ed,,localtime()} 和 @ref{1624,,strptime()} 回傳的時間值序列的型別。它是一個具有 @ref{857,,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{16ec}
@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{2fed}
@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{2fee}
@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{2fef}
@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{2ff0}
@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{2ff1}
@deffn {屬性} tm_sec
@end deffn

@tab

範圍 [0, 61]；參見 @ref{13ea,,strftime()} 中的@ref{2fec,,註釋 (2)}

@item

6

@tab

@geindex tm_wday (time.struct_time 的屬性)
@anchor{library/time time struct_time tm_wday}@anchor{2ff2}
@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{2ff3}
@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{2783}
@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{2fe8}
@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{2fe7}
@deffn {屬性} tm_gmtoff
@end deffn

@tab

UTC 向東的偏移量（以秒為單位）

@end multitable


請注意，與 C 結構不同，月份值的範圍是 [1, 12]，而不是 [0, 11]。

在呼叫 @ref{13e9,,mktime()} 時，當日光節約時間生效的時候，@ref{2783,,tm_isdst} 可以設定為 1，不生效時設定為 0。值 -1 表示未知是否生效，通常結果會填入正確的狀態。

當一個長度不正確的元組被傳遞給預期得到 @ref{ee1,,struct_time} 的函式時，或者其中有元素型別錯誤時，將引發 @ref{198,,TypeError}。
@end deffn

@geindex time() (於 time 模組中)
@anchor{library/time time time}@anchor{557}
@deffn {函式} time.time () -> float

回傳自 @ref{2dc6,,epoch} 起的時間（秒）至今的浮點數。對 leap seconds@footnote{https://en.wikipedia.org/wiki/Leap_second} 的處理是與平台有關的。在 Windows 和大多數 Unix 系統上，閏秒不計入自 @ref{2dc6,,epoch} 起的秒數中。這通常被稱為 Unix 時間@footnote{https://en.wikipedia.org/wiki/Unix_time}。

請注意，即使時間始終作為浮點數回傳，但並非所有系統都提供比 1 秒還更精確的時間。雖然此函式通常回傳非遞減的值，但如果在兩次呼叫之間系統時鐘被回調，則它可能回傳比之前呼叫更小的值。

由 @ref{557,,time()} 回傳的數字可以通過傳遞給 @ref{13c1,,gmtime()} 函式轉換為 UTC 內更常見的時間格式（即年、月、日、小時等）或通過傳遞給 @ref{16ed,,localtime()} 函式轉換為當地時間。在這兩種情況下都會回傳一個 @ref{ee1,,struct_time} 物件，從中可以作為屬性存取日曆日期的組成部分。

時鐘：


@itemize *

@item 
在 Windows 上，呼叫 @code{GetSystemTimePreciseAsFileTime()}。

@item 
如果可以的話，呼叫 @code{clock_gettime(CLOCK_REALTIME)}。

@item 
否則，呼叫 @code{gettimeofday()}。
@end itemize

使用 @ref{cd7,,time_ns()} 以避免 @ref{196,,float} 型別造成的精確度損失。
@end deffn


在 3.13 版的變更: 在 Windows 上，呼叫 @code{GetSystemTimePreciseAsFileTime()} 而不是 @code{GetSystemTimeAsFileTime()}。


@geindex time_ns() (於 time 模組中)
@anchor{library/time time time_ns}@anchor{cd7}
@deffn {函式} time.time_ns () -> int

類似於 @ref{557,,time()}，但回傳自 @ref{2dc6,,epoch} 起的以奈秒為單位的整數。


在 3.7 版被加入.

@end deffn

@geindex thread_time() (於 time 模組中)
@anchor{library/time time thread_time}@anchor{b27}
@deffn {函式} time.thread_time () -> float

@geindex CPU time（CPU 時間）
@geindex processor time（處理器時間）
@geindex benchmarking（基準測試）

回傳目前執行緒的系統和用戶 CPU 時間之和（以帶有小數的秒數表示）。它不包括睡眠期間經過的時間。根據定義，這是執行緒特定 (thread-specific) 的。回傳值的參照點未定義，因此只有同一執行緒中兩次呼叫結果之間的差異才是有效的。

使用 @ref{d85,,thread_time_ns()} 以避免 @ref{196,,float} 型別造成的精確度損失。

@ref{2006,,可用性}: Linux, Unix, Windows.

有支援 @code{CLOCK_THREAD_CPUTIME_ID} 的 Unix 系統。


在 3.7 版被加入.

@end deffn

@geindex thread_time_ns() (於 time 模組中)
@anchor{library/time time thread_time_ns}@anchor{d85}
@deffn {函式} time.thread_time_ns () -> int

類似於 @ref{b27,,thread_time()}，但回傳以奈秒為單位的時間。


在 3.7 版被加入.

@end deffn

@geindex tzset() (於 time 模組中)
@anchor{library/time time tzset}@anchor{2ff4}
@deffn {函式} time.tzset ()

重置函式庫常式 (routine) 使用的時間轉換規則。環境變數 
@geindex TZ
@geindex 環境變數; TZ
@code{TZ} 指定了這一過程的實施方式。它還會設定變數 @code{tzname}（來自 
@geindex TZ
@geindex 環境變數; TZ
@code{TZ} 環境變數）、@code{timezone}（非日光節約時間的 UTC 以西的時間偏移，單位為秒）、@code{altzone}（日光節約時間的 UTC 以西的時間偏移，單位為秒）和 @code{daylight}（如果該時區沒有日光節約時間規則，則設定為 0；如果在過去、現在或未來的某個時間有日光節約時間規則，則設置為非零的值）。

@ref{2006,,可用性}: Unix.

@cartouche
@quotation 備註 
雖然在許多情況下，更改 
@geindex TZ
@geindex 環境變數; TZ
@code{TZ} 環境變數可能會在沒有呼叫 @ref{2ff4,,tzset()} 的情況下影響 @ref{16ed,,localtime()} 等函式的輸出，但是這種行為是不該被依賴的。

@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}

三個或更多字母與數字 (alphanumerics) 組成的時區縮寫。這些縮寫會被傳播到 time.tzname 中。

@item @code{offset}

偏移量的格式為：@code{± hh[:mm[:ss]]}。這表示為達到 UTC 而增加到當地時間的值。如果以 '-' 開頭，則表示該時區位於本初子午線以東；否則，位於其西。如果 dst 之後沒有偏移量，則假定日光時間比標準時間快一小時。

@item @code{start[/time], end[/time]}

表示何時切換至日光節約時間及何時切換回來。開始和結束日期的格式如以下其一：


@table @asis

@item @code{J@var{n}}

儒略日 (Julian day) `n*（1 <= *n' <= 365）。閏日不計算，因此在所有年份中，2 月 28 日是第 59 天，3 月 1 日是第 60 天。

@item @code{@var{n}}

從 0 開始的儒略日 (0 <= `n' <= 365)。閏日會計算，因此可以適用至 2 月 29 日。

@item @code{M@var{m}.@var{n}.@var{d}}

一年中第 `m' 月的第 `n' 週的第 `d' 天（0 <= `d' <= 6，1 <= `n' <= 5，1 <= `m' <= 12，其中 `n' 為 5 表示「該月的最後一個第 `d' 天」，這可能出現在第四或第五週）。第 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 時鐘 ID 常數,時區常數,函式<5>,time --- 時間存取與轉換
@anchor{library/time clock-id-constants}@anchor{2ff5}@anchor{library/time time-clock-id-constants}@anchor{2f5f}
@subsubsection 時鐘 ID 常數


這些常數用作 @ref{135e,,clock_getres()} 和 @ref{135f,,clock_gettime()} 的參數。

@geindex CLOCK_BOOTTIME (於 time 模組中)
@anchor{library/time time CLOCK_BOOTTIME}@anchor{d81}
@deffn {資料} time.CLOCK_BOOTTIME

與 @ref{d82,,CLOCK_MONOTONIC} 基本相同，不同之處在於它還包括系統暫停的任何時間。

這允許應用程式取得一個能夠感知暫停的單調時鐘，而無需處理 @ref{8a1,,CLOCK_REALTIME} 的複雜情況，後者在使用 @code{settimeofday()} 或類似函式更改時間時可能會出現不連續的情況。

@ref{2006,,可用性}: Linux >= 2.6.39.


在 3.7 版被加入.

@end deffn

@geindex CLOCK_HIGHRES (於 time 模組中)
@anchor{library/time time CLOCK_HIGHRES}@anchor{2ff6}
@deffn {資料} time.CLOCK_HIGHRES

Solaris 作業系統具有 @code{CLOCK_HIGHRES} 計時器，它嘗試使用最佳的硬體資源，並可能提供接近奈秒的解析度。@code{CLOCK_HIGHRES} 是不可調整且高解析度的時鐘。

@ref{2006,,可用性}: Solaris.


在 3.3 版被加入.

@end deffn

@geindex CLOCK_MONOTONIC (於 time 模組中)
@anchor{library/time time CLOCK_MONOTONIC}@anchor{d82}
@deffn {資料} time.CLOCK_MONOTONIC

該時鐘無法被設定，其表示自某個未指定起點以來的單調時間。

@ref{2006,,可用性}: Unix.


在 3.3 版被加入.

@end deffn

@geindex CLOCK_MONOTONIC_RAW (於 time 模組中)
@anchor{library/time time CLOCK_MONOTONIC_RAW}@anchor{2ff7}
@deffn {資料} time.CLOCK_MONOTONIC_RAW

類似於 @ref{d82,,CLOCK_MONOTONIC}，但提供對基於硬體的原始時間的存取，此時間不受 NTP 調整的影響。

@ref{2006,,可用性}: Linux >= 2.6.28, macOS >= 10.12.


在 3.3 版被加入.

@end deffn

@geindex CLOCK_MONOTONIC_RAW_APPROX (於 time 模組中)
@anchor{library/time time CLOCK_MONOTONIC_RAW_APPROX}@anchor{2ff8}
@deffn {資料} time.CLOCK_MONOTONIC_RAW_APPROX

類似於 @ref{2ff7,,CLOCK_MONOTONIC_RAW}，但讀取的是系統在情境切換時快取的值，因此精準度較低。

@ref{2006,,可用性}: macOS >= 10.12.


在 3.13 版被加入.

@end deffn

@geindex CLOCK_PROCESS_CPUTIME_ID (於 time 模組中)
@anchor{library/time time CLOCK_PROCESS_CPUTIME_ID}@anchor{2ff9}
@deffn {資料} time.CLOCK_PROCESS_CPUTIME_ID

來自 CPU 的高解析度每個行程的計時器。

@ref{2006,,可用性}: Unix.


在 3.3 版被加入.

@end deffn

@geindex CLOCK_PROF (於 time 模組中)
@anchor{library/time time CLOCK_PROF}@anchor{d83}
@deffn {資料} time.CLOCK_PROF

來自 CPU 的高解析度每個行程的計時器。

@ref{2006,,可用性}: FreeBSD, NetBSD >= 7, OpenBSD.


在 3.7 版被加入.

@end deffn

@geindex CLOCK_TAI (於 time 模組中)
@anchor{library/time time CLOCK_TAI}@anchor{1c20}
@deffn {資料} time.CLOCK_TAI

國際原子時間@footnote{https://www.nist.gov/pml/time-and-frequency-division/how-utcnist-related-coordinated-universal-time-utc-international}

系統必須擁有目前的閏秒表才能給出正確答案。PTP 或 NTP 軟體可以維護閏秒表。

@ref{2006,,可用性}: Linux.


在 3.9 版被加入.

@end deffn

@geindex CLOCK_THREAD_CPUTIME_ID (於 time 模組中)
@anchor{library/time time CLOCK_THREAD_CPUTIME_ID}@anchor{2ffa}
@deffn {資料} time.CLOCK_THREAD_CPUTIME_ID

執行緒相關的 CPU 時間時鐘。

@ref{2006,,可用性}: Unix.


在 3.3 版被加入.

@end deffn

@geindex CLOCK_UPTIME (於 time 模組中)
@anchor{library/time time CLOCK_UPTIME}@anchor{d84}
@deffn {資料} time.CLOCK_UPTIME

表示系統運作且無暫停的絕對時間，提供包括絕對時間 (absolute) 和時間區間 (interval) 的精確的正常上線時間 (uptime) 測量。

@ref{2006,,可用性}: FreeBSD, OpenBSD >= 5.5.


在 3.7 版被加入.

@end deffn

@geindex CLOCK_UPTIME_RAW (於 time 模組中)
@anchor{library/time time CLOCK_UPTIME_RAW}@anchor{c2e}
@deffn {資料} time.CLOCK_UPTIME_RAW

單調增量的時鐘，從某個任意點開始計時，不受頻率或時間調整影響，並且在系統休眠時不增量。

@ref{2006,,可用性}: macOS >= 10.12.


在 3.8 版被加入.

@end deffn

@geindex CLOCK_UPTIME_RAW_APPROX (於 time 模組中)
@anchor{library/time time CLOCK_UPTIME_RAW_APPROX}@anchor{2ffb}
@deffn {資料} time.CLOCK_UPTIME_RAW_APPROX

類似於 @ref{c2e,,CLOCK_UPTIME_RAW}，但該值在情境切換時由系統快取，因此精準度較低。

@ref{2006,,可用性}: macOS >= 10.12.


在 3.13 版被加入.

@end deffn

以下常數是唯一可以傳遞給 @ref{1360,,clock_settime()} 的參數。

@geindex CLOCK_REALTIME (於 time 模組中)
@anchor{library/time time CLOCK_REALTIME}@anchor{8a1}
@deffn {資料} time.CLOCK_REALTIME

即時時鐘。設定此時鐘需要適當的權限。時鐘對於所有行程都會是相同。

@ref{2006,,可用性}: Unix.


在 3.3 版被加入.

@end deffn

@node 時區常數,,時鐘 ID 常數,time --- 時間存取與轉換
@anchor{library/time time-timezone-constants}@anchor{2ffc}@anchor{library/time timezone-constants}@anchor{2ffd}
@subsubsection 時區常數


@geindex altzone (於 time 模組中)
@anchor{library/time time altzone}@anchor{2ffe}
@deffn {資料} time.altzone

如果本地 DST 時區有被定義，則此值為本地 DST 時區相對於 UTC 以西的偏移量（以秒為單位）。若本地 DST 時區位於 UTC 以東（例如包括英國在內的西歐），則此值為負值。僅在 @code{daylight} 為非零時使用此值。詳情請參見下方註釋。
@end deffn

@geindex daylight (於 time 模組中)
@anchor{library/time time daylight}@anchor{2fff}
@deffn {資料} time.daylight

如果定義了 DST 時區，則為非零值。詳情請參見下方註釋。
@end deffn

@geindex timezone (於 time 模組中)
@anchor{library/time time timezone}@anchor{3000}
@deffn {資料} time.timezone

本地（非 DST）時區相對於 UTC 以西的偏移量（以秒為單位），西歐大多數地區為負，美國為正，英國為零。詳情請參見下方註釋。
@end deffn

@geindex tzname (於 time 模組中)
@anchor{library/time time tzname}@anchor{3001}
@deffn {資料} time.tzname

一個包含兩個字串的元組：第一個是本地非 DST 時區的名稱，第二個是本地 DST 時區的名稱。如果沒有定義 DST 時區，則不應使用第二個字串。詳情請參見下方註釋。
@end deffn

@cartouche
@quotation 備註 
對於上述時區常數（@ref{2ffe,,altzone}、@ref{2fff,,daylight}、@ref{3000,,timezone} 和 @ref{3001,,tzname}），其值由模組載入時或 @ref{2ff4,,tzset()} 最後一次被呼叫時的時區規則決定，且過去的時間可能會不準確。建議使用 @ref{16ed,,localtime()} 回傳的 @ref{2fe7,,tm_gmtoff} 和 @ref{2fe8,,tm_zone} 來取得時區資訊。
@end quotation
@end cartouche


@subsubheading 也參考



@table @asis

@item @ref{34,,datetime} 模組

更多物件導向的日期和時間介面。

@item @ref{8a,,locale} 模組

國際化服務。區域設定會影響 @ref{13ea,,strftime()} 和 @ref{1624,,strptime()} 中許多格式指定符號 (format specifiers) 的解譯。

@item @ref{15,,calendar} 模組

通用的日曆相關函式。@ref{27f6,,timegm()} 是本模組中 @ref{13c1,,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 --- Python 的日誌記錄工具,logging config --- 日誌記錄配置,time --- 時間存取與轉換,通用作業系統服務
@anchor{library/logging doc}@anchor{3002}@anchor{library/logging logging-logging-facility-for-python}@anchor{3003}@anchor{library/logging module-logging}@anchor{8b}@anchor{library/logging translation-repo}@anchor{3004}
@subsection @code{logging} --- Python 的日誌記錄工具


@geindex module; logging

`原始碼：'Lib/logging/__init__.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/logging/__init__.py}

@geindex Errors（錯誤）;logging（日誌）

@subsubheading Important



此頁面包含 API 參考訊息。有關教學流程和更進階的主題討論，請參閱


@itemize *

@item 
@ref{13f6,,基礎教學}

@item 
@ref{13f7,,進階教學}

@item 
@ref{13f8,,日誌記錄手冊}
@end itemize


__________________________________________________________________


這個模組定義了函式與類別 (class)，為應用程式和函式庫實作彈性的日誌管理系統。

由標準函式庫模組提供的日誌記錄 API 的主要好處是，所有的 Python 模組都能參與日誌記錄，因此你的應用程式日誌可以包含你自己的訊息，並與來自第三方模組的訊息整合在一起。

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{bea,,basicConfig()} provides a quick way to configure
the root logger that handles many use cases.

這個模組提供了很多的功能性以及彈性。如果你對於 logging 不熟悉，熟悉它最好的方法就是去看教學（`請看右上方的連結'）。

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 
格式器指定日誌記錄在最終輸出中的佈局。
@end itemize

@menu
* Logger 物件:: 
* Logging Levels:: 
* Handler Objects:: 
* Formatter Objects:: 
* Filter Objects:: 
* LogRecord 物件:: 
* LogRecord 屬性:: 
* LoggerAdapter 物件:: 
* 執行緒安全:: 
* 模組層級函式:: 
* 模組層級屬性:: 
* Integration with the warnings module:: 

@end menu

@node Logger 物件,Logging Levels,,logging --- Python 的日誌記錄工具
@anchor{library/logging logger}@anchor{3005}@anchor{library/logging logger-objects}@anchor{3006}
@subsubsection Logger 物件


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{b50,,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{d3e}
@deffn {類別} logging.Logger

@geindex name (logging.Logger 的屬性)
@anchor{library/logging logging Logger name}@anchor{3007}
@deffn {屬性} name

This is the logger's name, and is the value that was passed to @ref{b50,,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{3008}
@deffn {屬性} level

The threshold of this logger, as set by the @ref{1687,,setLevel()} method.

@cartouche
@quotation 備註 
Do not set this attribute directly - always use @ref{1687,,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{3009}
@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{1689}
@deffn {屬性} propagate

如果此屬性評估為 true，則在此日誌紀錄器被記錄的事件會被傳到更高階（上代）日誌記錄器 的處理函式和所有附加在此日誌記錄器的任何處理器。訊息會直接傳到上代 loggers 的處理器 - 在問題中上代日誌記錄器的層級或是篩選器都不會被考慮。

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.

此建構函式將該屬性設為 @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{300a}
@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{300b,,addHandler()} and @ref{300c,,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{300d}
@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{1687}
@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'.

當一個日誌記錄器被建立時，記錄層級會被設定成 @ref{300e,,NOTSET} （當此日誌記錄器是根日誌記錄器，或是代表父日誌記錄器的非根日誌記錄器時，會使所有訊息被處理）。請注意根日誌記錄器會以記錄等級 @ref{1fa6,,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.

層級清單請見 @ref{863,,Logging 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{1fa5,,INFO}. Note, however, that levels are internally stored
as integers, and methods such as e.g. @ref{300f,,getEffectiveLevel()} and
@ref{14f7,,isEnabledFor()} will return/expect to be passed integers.

@end deffn

@geindex isEnabledFor() (logging.Logger 的方法)
@anchor{library/logging logging Logger isEnabledFor}@anchor{14f7}
@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{300f,,getEffectiveLevel()}.
@end deffn

@geindex getEffectiveLevel() (logging.Logger 的方法)
@anchor{library/logging logging Logger getEffectiveLevel}@anchor{300f}
@deffn {方法} getEffectiveLevel ()

Indicates the effective level for this logger. If a value other than
@ref{300e,,NOTSET} has been set using @ref{1687,,setLevel()}, it is returned. Otherwise,
the hierarchy is traversed towards the root until a value other than
@ref{300e,,NOTSET} is found, and that value is returned. The value returned is
an integer, typically one of @ref{1fa4,,logging.DEBUG}, @ref{1fa5,,logging.INFO}
etc.
@end deffn

@geindex getChild() (logging.Logger 的方法)
@anchor{library/logging logging Logger getChild}@anchor{14f5}
@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.


在 3.2 版被加入.

@end deffn

@geindex getChildren() (logging.Logger 的方法)
@anchor{library/logging logging Logger getChildren}@anchor{1a81}
@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}.


在 3.12 版被加入.

@end deffn

@geindex debug() (logging.Logger 的方法)
@anchor{library/logging logging Logger debug}@anchor{1026}
@deffn {方法} debug (msg, *args, **kwargs)

Logs a message with level @ref{1fa4,,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{893,,sys.exc_info()}) or an exception instance is provided, it is used;
otherwise, @ref{893,,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{11e1,,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{118,,warnings} module.

The fourth keyword argument is `extra' which can be used to pass a
dictionary which is used to populate the @ref{776,,__dict__} of the
@ref{11e1,,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{3010,,LogRecord 屬性} 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{168b,,Formatter} has been
set up with a format string which expects 'clientip' and 'user' in the attribute
dictionary of the @ref{11e1,,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{168b,,Formatter}s would be used with particular @ref{168a,,Handler}s.

If no handler is attached to this logger (or any of its ancestors,
taking into account the relevant @ref{1689,,Logger.propagate} attributes),
the message will be sent to the handler set on @ref{13fb,,lastResort}.


在 3.2 版的變更: 新增 `stack_info' 參數。



在 3.5 版的變更: The `exc_info' parameter can now accept exception instances.



在 3.8 版的變更: 新增 `stacklevel' 參數。

@end deffn

@geindex info() (logging.Logger 的方法)
@anchor{library/logging logging Logger info}@anchor{3011}
@deffn {方法} info (msg, *args, **kwargs)

Logs a message with level @ref{1fa5,,INFO} on this logger. The arguments are
interpreted as for @ref{3012,,debug()}.
@end deffn

@geindex warning() (logging.Logger 的方法)
@anchor{library/logging logging Logger warning}@anchor{19c6}
@deffn {方法} warning (msg, *args, **kwargs)

在此記錄器上記錄一條層級為 @ref{1fa6,,WARNING} 的訊息。這些引數被直譯的方式與 @ref{3012,,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{3013}
@deffn {方法} error (msg, *args, **kwargs)

Logs a message with level @ref{1fa7,,ERROR} on this logger. The arguments are
interpreted as for @ref{3012,,debug()}.
@end deffn

@geindex critical() (logging.Logger 的方法)
@anchor{library/logging logging Logger critical}@anchor{1025}
@deffn {方法} critical (msg, *args, **kwargs)

Logs a message with level @ref{1fa8,,CRITICAL} on this logger. The arguments are
interpreted as for @ref{3012,,debug()}.
@end deffn

@geindex log() (logging.Logger 的方法)
@anchor{library/logging logging Logger log}@anchor{1023}
@deffn {方法} log (level, msg, *args, **kwargs)

Logs a message with integer level `level' on this logger. The other arguments are
interpreted as for @ref{3012,,debug()}.
@end deffn

@geindex exception() (logging.Logger 的方法)
@anchor{library/logging logging Logger exception}@anchor{1024}
@deffn {方法} exception (msg, *args, **kwargs)

Logs a message with level @ref{1fa7,,ERROR} on this logger. The arguments are
interpreted as for @ref{3012,,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{3014}
@deffn {方法} addFilter (filter)

在該 logger 內增加指定的 filter `filter'。
@end deffn

@geindex removeFilter() (logging.Logger 的方法)
@anchor{library/logging logging Logger removeFilter}@anchor{3015}
@deffn {方法} removeFilter (filter)

在該 logger 內移除指定的 filter `filter'。
@end deffn

@geindex filter() (logging.Logger 的方法)
@anchor{library/logging logging Logger filter}@anchor{3016}
@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{300b}
@deffn {方法} addHandler (hdlr)

Adds the specified handler `hdlr' to this logger.
@end deffn

@geindex removeHandler() (logging.Logger 的方法)
@anchor{library/logging logging Logger removeHandler}@anchor{300c}
@deffn {方法} removeHandler (hdlr)

Removes the specified handler `hdlr' from this logger.
@end deffn

@geindex findCaller() (logging.Logger 的方法)
@anchor{library/logging logging Logger findCaller}@anchor{3017}
@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{3012,,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{3018}
@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{3016,,filter()}.
@end deffn

@geindex makeRecord() (logging.Logger 的方法)
@anchor{library/logging logging Logger makeRecord}@anchor{3019}
@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{11e1,,LogRecord} instances.
@end deffn

@geindex hasHandlers() (logging.Logger 的方法)
@anchor{library/logging logging Logger hasHandlers}@anchor{301a}
@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.


在 3.2 版被加入.

@end deffn


在 3.7 版的變更: Loggers can now be pickled and unpickled.

@end deffn

@node Logging Levels,Handler Objects,Logger 物件,logging --- Python 的日誌記錄工具
@anchor{library/logging levels}@anchor{863}@anchor{library/logging logging-levels}@anchor{301b}
@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{300e}
@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{1fa4}
@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{1fa5}
@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{1fa6}
@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{1fa7}
@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{1fa8}
@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 --- Python 的日誌記錄工具
@anchor{library/logging handler}@anchor{301c}@anchor{library/logging handler-objects}@anchor{301d}
@subsubsection Handler Objects


Handlers have the following attributes and methods. Note that @ref{168a,,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{301e,,Handler.__init__()}.

@geindex Handler (logging 中的類別)
@anchor{library/logging logging Handler}@anchor{168a}
@deffn {類別} logging.Handler

@geindex __init__() (logging.Handler 的方法)
@anchor{library/logging logging Handler __init__}@anchor{301e}
@deffn {方法} __init__ (level=NOTSET)

Initializes the @ref{168a,,Handler} instance by setting its level, setting the list
of filters to the empty list and creating a lock (using @ref{301f,,createLock()}) for
serializing access to an I/O mechanism.
@end deffn

@geindex createLock() (logging.Handler 的方法)
@anchor{library/logging logging Handler createLock}@anchor{301f}
@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{3020}
@deffn {方法} acquire ()

Acquires the thread lock created with @ref{301f,,createLock()}.
@end deffn

@geindex release() (logging.Handler 的方法)
@anchor{library/logging logging Handler release}@anchor{3021}
@deffn {方法} release ()

Releases the thread lock acquired with @ref{3020,,acquire()}.
@end deffn

@geindex setLevel() (logging.Handler 的方法)
@anchor{library/logging logging Handler setLevel}@anchor{3022}
@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{300e,,NOTSET} (which causes all messages to be
processed).

層級清單請見 @ref{863,,Logging 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{1fa5,,INFO}.

@end deffn

@geindex setFormatter() (logging.Handler 的方法)
@anchor{library/logging logging Handler setFormatter}@anchor{3023}
@deffn {方法} setFormatter (fmt)

Sets the formatter for this handler to `fmt'.
The `fmt' argument must be a @ref{168b,,Formatter} instance or @code{None}.
@end deffn

@geindex addFilter() (logging.Handler 的方法)
@anchor{library/logging logging Handler addFilter}@anchor{3024}
@deffn {方法} addFilter (filter)

Adds the specified filter `filter' to this handler.
@end deffn

@geindex removeFilter() (logging.Handler 的方法)
@anchor{library/logging logging Handler removeFilter}@anchor{3025}
@deffn {方法} removeFilter (filter)

Removes the specified filter `filter' from this handler.
@end deffn

@geindex filter() (logging.Handler 的方法)
@anchor{library/logging logging Handler filter}@anchor{3026}
@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{3027}
@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{3028}
@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 @ref{3028,,close()}
methods.
@end deffn

@geindex handle() (logging.Handler 的方法)
@anchor{library/logging logging Handler handle}@anchor{3029}
@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{302a}
@deffn {方法} handleError (record)

This method should be called from handlers when an exception is encountered
during an @ref{302b,,emit()} call. If the module-level attribute
@ref{13fa,,raiseExceptions} is @code{False}, exceptions get silently ignored. This is
what is mostly wanted for a logging system - most users will not care about
errors in the logging system, they are more interested in application
errors. You could, however, replace this with a custom handler if you wish.
The specified record is the one which was being processed when the exception
occurred. (The default value of @ref{13fa,,raiseExceptions} is @code{True}, as that is
more useful during development).
@end deffn

@geindex format() (logging.Handler 的方法)
@anchor{library/logging logging Handler format}@anchor{302c}
@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{302b}
@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{369,,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{8d,,logging.handlers}.

@node Formatter Objects,Filter Objects,Handler Objects,logging --- Python 的日誌記錄工具
@anchor{library/logging formatter-objects}@anchor{302d}@anchor{library/logging id1}@anchor{302e}
@subsubsection Formatter Objects


@geindex Formatter (logging 中的類別)
@anchor{library/logging logging Formatter}@anchor{168b}
@deffn {類別} logging.Formatter (fmt=None, datefmt=None, style='%', validate=True, *, defaults=None)

Responsible for converting a @ref{11e1,,LogRecord} to an output string
to be interpreted by a human or external system.

@*參數: 

@itemize *

@item 
@code{fmt} (@ref{169,,str}) -- A format string in the given `style' for
the logged output as a whole.
The possible mapping keys are drawn from the @ref{11e1,,LogRecord} object's
@ref{3010,,LogRecord 屬性}.
If not specified, @code{'%(message)s'} is used,
which is just the logged message.

@item 
@code{datefmt} (@ref{169,,str}) -- A format string for the date/time portion of the logged output.
If not specified, the default described in @ref{302f,,formatTime()} is used.

@item 
@code{style} (@ref{169,,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{8d3,,printf-style String Formatting} (@code{%}), @ref{82c,,str.format()} (@code{@{})
or @ref{890,,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{3030,,other ways}
to use @code{@{}- and @code{$}-formatting for log messages.

@item 
@code{validate} (@ref{3c1,,bool}) -- If @code{True} (the default), incorrect or mismatched
`fmt' and `style' will raise a @ref{2eb,,ValueError}; for example,
@code{logging.Formatter('%(asctime)s - %(message)s', style='@{')}.

@item 
@code{defaults} (@ref{183,,dict}@code{[}@ref{169,,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 版的變更: 新增 `style' 參數。



在 3.8 版的變更: 新增 `validate' 參數。



在 3.10 版的變更: 新增 `defaults' 參數。


@geindex format() (logging.Formatter 的方法)
@anchor{library/logging logging Formatter format}@anchor{3031}
@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{302f,,formatTime()} is called
to format the event time. If there is exception information, it is
formatted using @ref{3032,,formatException()} and appended to the message. Note
that the formatted exception information is cached in attribute
`exc_text'. This is useful because the exception information can be
pickled and sent across the wire, but you should be careful if you have
more than one @ref{168b,,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{3033,,formatStack()} to transform it if necessary.
@end deffn

@geindex formatTime() (logging.Formatter 的方法)
@anchor{library/logging logging Formatter formatTime}@anchor{302f}
@deffn {方法} formatTime (record, datefmt=None)

This method should be called from @ref{199,,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{13ea,,time.strftime()} to format the creation time of the
record. Otherwise, the format '%Y-%m-%d %H:%M:%S,uuu' is used, where the
uuu part is a millisecond value and the other letters are as per the
@ref{13ea,,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{16ed,,time.localtime()} is used; to change
this for a particular formatter instance, set the @code{converter} attribute
to a function with the same signature as @ref{16ed,,time.localtime()} or
@ref{13c1,,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{3032}
@deffn {方法} formatException (exc_info)

Formats the specified exception information (a standard exception tuple as
returned by @ref{893,,sys.exc_info()}) as a string. This default implementation
just uses @ref{a48,,traceback.print_exception()}. The resulting string is
returned.
@end deffn

@geindex formatStack() (logging.Formatter 的方法)
@anchor{library/logging logging Formatter formatStack}@anchor{3033}
@deffn {方法} formatStack (stack_info)

Formats the specified stack information (a string as returned by
@ref{1081,,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{3034}
@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{168b,,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{3035}
@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{3036}
@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{3037}
@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 物件,Formatter Objects,logging --- Python 的日誌記錄工具
@anchor{library/logging filter}@anchor{3038}@anchor{library/logging filter-objects}@anchor{3039}
@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{13fc}
@deffn {類別} logging.Filter (name='@w{'})

Returns an instance of the @ref{13fc,,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{303a}
@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{3012,,debug()}, @ref{303b,,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{303a,,filter()} method is called. Otherwise, it's
assumed to be a callable and called with the record as the single
parameter. The returned value should conform to that returned by
@ref{303a,,filter()}.



在 3.12 版的變更: You can now return a @ref{11e1,,LogRecord} instance from filters to replace
the log record rather than modifying it in place. This allows filters attached to
a @ref{168a,,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{11e1,,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{303c,,Using Filters to impart contextual information}).

@node LogRecord 物件,LogRecord 屬性,Filter Objects,logging --- Python 的日誌記錄工具
@anchor{library/logging log-record}@anchor{303d}@anchor{library/logging logrecord-objects}@anchor{303e}
@subsubsection LogRecord 物件


@ref{11e1,,LogRecord} instances are created automatically by the @ref{d3e,,Logger}
every time something is logged, and can be created manually via
@ref{303f,,makeLogRecord()} (for example, from a pickled event received over the
wire).

@geindex LogRecord (logging 中的類別)
@anchor{library/logging logging LogRecord}@anchor{11e1}
@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{169,,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{19b,,int}) -- The @ref{863,,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{169,,str}) -- The full string path of the source file
where the logging call was made.

@item 
@code{lineno} (@ref{19b,,int}) -- The line number in the source file
where the logging call was made.

@item 
@code{msg} (@ref{8b3,,Any}) -- The event description message,
which can be a %-format string with placeholders for variable data,
or an arbitrary object (see @ref{3040,,Using arbitrary objects as messages}).

@item 
@code{args} (@ref{60c,,tuple}@code{ | }@ref{183,,dict}@code{[}@ref{169,,str}@code{, }@ref{8b3,,Any}@code{]}) -- Variable data to merge into the `msg' argument
to obtain the event description.

@item 
@code{exc_info} (@ref{60c,,tuple}@code{[}@ref{f3f,,type}@code{[}@ref{7d0,,BaseException}@code{]}@code{, }@ref{7d0,,BaseException}@code{, }@ref{ce1,,types.TracebackType}@code{] }@code{| }@code{None}) -- An exception tuple with the current exception information,
as returned by @ref{893,,sys.exc_info()},
or @code{None} if no exception information is available.

@item 
@code{func} (@ref{169,,str}@code{ | }@code{None}) -- The name of the function or method
from which the logging call was invoked.

@item 
@code{sinfo} (@ref{169,,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{3041}
@deffn {方法} getMessage ()

Returns the message for this @ref{11e1,,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{169,,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 @ref{11e1,,LogRecord} has been made more configurable by
providing a factory which is used to create the record. The factory can be
set using @ref{3042,,getLogRecordFactory()} and @ref{3043,,setLogRecordFactory()}
(see this for the factory's signature).


This functionality can be used to inject your own values into a
@ref{11e1,,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 屬性,LoggerAdapter 物件,LogRecord 物件,logging --- Python 的日誌記錄工具
@anchor{library/logging id2}@anchor{3044}@anchor{library/logging logrecord-attributes}@anchor{3010}
@subsubsection LogRecord 屬性


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{82c,,str.format()}), you can use
@code{@{attrname@}} as the placeholder in the format string. If you are using
$-formatting (@ref{890,,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{82c,,str.format()} documentation for full details on
the options available to you.


@multitable {xxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

屬性名稱

@tab

格式

@tab

描述

@item

args

@tab

你不應該需要自己格式化它。

@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{11e1,,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{11e1,,LogRecord} was created
(as returned by @ref{cd7,,time.time_ns()} / 1e9).

@item

exc_info

@tab

你不應該需要自己格式化它。

@tab

Exception tuple (à la @code{sys.exc_info}) or,
if no exception has occurred, @code{None}.

@item

filename

@tab

@code{%(filename)s}

@tab

@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{1fa4,,DEBUG}, @ref{1fa5,,INFO},
@ref{1fa6,,WARNING}, @ref{1fa7,,ERROR},
@ref{1fa8,,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{3031,,Formatter.format()} is invoked.

@item

模組

@tab

@code{%(module)s}

@tab

模組（@code{filename} 的名稱部分）。

@item

msecs

@tab

@code{%(msecs)d}

@tab

Millisecond portion of the time when the
@ref{11e1,,LogRecord} was created.

@item

msg

@tab

你不應該需要自己格式化它。

@tab

The format string passed in the original
logging call. Merged with @code{args} to
produce @code{message}, or an arbitrary object
(see @ref{3040,,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

行程 ID（如果可用）。

@item

processName

@tab

@code{%(processName)s}

@tab

行程名稱（如果可用）。

@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

你不應該需要自己格式化它。

@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

執行緒 ID（如果可用）。

@item

threadName

@tab

@code{%(threadName)s}

@tab

Thread name (if available).

@item

taskName

@tab

@code{%(taskName)s}

@tab

@ref{1c7,,asyncio.Task} name (if available).

@end multitable



在 3.1 版的變更: 新增 `processName'。



在 3.12 版的變更: 新增 `taskName'。


@node LoggerAdapter 物件,執行緒安全,LogRecord 屬性,logging --- Python 的日誌記錄工具
@anchor{library/logging logger-adapter}@anchor{3045}@anchor{library/logging loggeradapter-objects}@anchor{3046}
@subsubsection LoggerAdapter 物件


@ref{14f6,,LoggerAdapter} instances are used to conveniently pass contextual
information into logging calls. For a usage example, see the section on
@ref{3047,,adding contextual information to your logging output}.

@geindex LoggerAdapter (logging 中的類別)
@anchor{library/logging logging LoggerAdapter}@anchor{14f6}
@deffn {類別} logging.LoggerAdapter (logger, extra=None, merge_extra=False)

Returns an instance of @ref{14f6,,LoggerAdapter} initialized with an
underlying @ref{d3e,,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 @ref{14f6,,LoggerAdapter} extra.
The default behavior is to ignore the `extra' argument of individual log
calls and only use the one of the @ref{14f6,,LoggerAdapter} instance

@geindex process() (logging.LoggerAdapter 的方法)
@anchor{library/logging logging LoggerAdapter process}@anchor{3048}
@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{3049}
@deffn {屬性} manager

Delegates to the underlying @code{manager} on `logger'.
@end deffn

@geindex _log (logging.LoggerAdapter 的屬性)
@anchor{library/logging logging LoggerAdapter _log}@anchor{304a}
@deffn {屬性} _log

Delegates to the underlying @code{_log()} method on `logger'.
@end deffn

In addition to the above, @ref{14f6,,LoggerAdapter} supports the following
methods of @ref{d3e,,Logger}: @ref{1026,,debug()}, @ref{3011,,info()},
@ref{19c6,,warning()}, @ref{3013,,error()}, @ref{1024,,exception()},
@ref{1025,,critical()}, @ref{1023,,log()}, @ref{14f7,,isEnabledFor()},
@ref{300f,,getEffectiveLevel()}, @ref{1687,,setLevel()} and
@ref{301a,,hasHandlers()}. These methods have the same signatures as their
counterparts in @ref{d3e,,Logger}, so you can use the two types of instances
interchangeably.


在 3.2 版的變更: The @ref{14f7,,isEnabledFor()}, @ref{300f,,getEffectiveLevel()},
@ref{1687,,setLevel()} and @ref{301a,,hasHandlers()} methods were added
to @ref{14f6,,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 執行緒安全,模組層級函式,LoggerAdapter 物件,logging --- Python 的日誌記錄工具
@anchor{library/logging thread-safety}@anchor{304b}
@subsubsection 執行緒安全


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{cb,,signal}
module, you may not be able to use logging from within such handlers. This is
because lock implementations in the @ref{f3,,threading} module are not always
re-entrant, and so cannot be invoked from such signal handlers.

@node 模組層級函式,模組層級屬性,執行緒安全,logging --- Python 的日誌記錄工具
@anchor{library/logging module-level-functions}@anchor{304c}
@subsubsection 模組層級函式


In addition to the classes described above, there are a number of module-level
functions.

@geindex getLogger() (於 logging 模組中)
@anchor{library/logging logging getLogger}@anchor{b50}
@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{3005,,Logger 物件}.

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{304d}
@deffn {函式} logging.getLoggerClass ()

Return either the standard @ref{d3e,,Logger} class, or the last class passed to
@ref{304e,,setLoggerClass()}. This function may be called from within a new class
definition, to ensure that installing a customized @ref{d3e,,Logger} class will
not undo customizations already applied by other code. For example:

@example
class MyLogger(logging.getLoggerClass()):
    # ... 在這裡覆蓋其行為
@end example
@end deffn

@geindex getLogRecordFactory() (於 logging 模組中)
@anchor{library/logging logging getLogRecordFactory}@anchor{3042}
@deffn {函式} logging.getLogRecordFactory ()

Return a callable which is used to create a @ref{11e1,,LogRecord}.


在 3.2 版被加入: This function has been provided, along with @ref{3043,,setLogRecordFactory()},
to allow developers more control over how the @ref{11e1,,LogRecord}
representing a logging event is constructed.


See @ref{3043,,setLogRecordFactory()} for more information about the how the
factory is called.
@end deffn

@geindex debug() (於 logging 模組中)
@anchor{library/logging logging debug}@anchor{3012}
@deffn {函式} logging.debug (msg, *args, **kwargs)

This is a convenience function that calls @ref{1026,,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{bea,,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{1026,,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{303b}
@deffn {函式} logging.info (msg, *args, **kwargs)

Logs a message with level @ref{1fa5,,INFO} on the root logger. The arguments and behavior
are otherwise the same as for @ref{3012,,debug()}.
@end deffn

@geindex warning() (於 logging 模組中)
@anchor{library/logging logging warning}@anchor{352}
@deffn {函式} logging.warning (msg, *args, **kwargs)

Logs a message with level @ref{1fa6,,WARNING} on the root logger. The arguments and behavior
are otherwise the same as for @ref{3012,,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{304f}
@deffn {函式} logging.error (msg, *args, **kwargs)

Logs a message with level @ref{1fa7,,ERROR} on the root logger. The arguments and behavior
are otherwise the same as for @ref{3012,,debug()}.
@end deffn

@geindex critical() (於 logging 模組中)
@anchor{library/logging logging critical}@anchor{3050}
@deffn {函式} logging.critical (msg, *args, **kwargs)

Logs a message with level @ref{1fa8,,CRITICAL} on the root logger. The arguments and behavior
are otherwise the same as for @ref{3012,,debug()}.
@end deffn

@geindex exception() (於 logging 模組中)
@anchor{library/logging logging exception}@anchor{1688}
@deffn {函式} logging.exception (msg, *args, **kwargs)

Logs a message with level @ref{1fa7,,ERROR} on the root logger. The arguments and behavior
are otherwise the same as for @ref{3012,,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{3051}
@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{3012,,debug()}.
@end deffn

@geindex disable() (於 logging 模組中)
@anchor{library/logging logging disable}@anchor{3052}
@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{3053}
@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{168b,,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{3054,,Custom Levels}.
@end quotation
@end cartouche
@end deffn

@geindex getLevelNamesMapping() (於 logging 模組中)
@anchor{library/logging logging getLevelNamesMapping}@anchor{862}
@deffn {函式} logging.getLevelNamesMapping ()

Returns a mapping from level names to their corresponding logging levels. For example, the
string "CRITICAL" maps to @ref{1fa8,,CRITICAL}. The returned mapping is copied from an internal
mapping on each call to this function.


在 3.11 版被加入.

@end deffn

@geindex getLevelName() (於 logging 模組中)
@anchor{library/logging logging getLevelName}@anchor{3055}
@deffn {函式} logging.getLevelName (level)

Returns the textual or numeric representation of logging level `level'.

If `level' is one of the predefined levels @ref{1fa8,,CRITICAL}, @ref{1fa7,,ERROR},
@ref{1fa6,,WARNING}, @ref{1fa5,,INFO} or @ref{1fa4,,DEBUG} then you get the
corresponding string. If you have associated levels with names using
@ref{3053,,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{3010,,LogRecord 屬性}), 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 due to retain backward compatibility.

@end deffn

@geindex getHandlerByName() (於 logging 模組中)
@anchor{library/logging logging getHandlerByName}@anchor{1a91}
@deffn {函式} logging.getHandlerByName (name)

Returns a handler with the specified `name', or @code{None} if there is no handler
with that name.


在 3.12 版被加入.

@end deffn

@geindex getHandlerNames() (於 logging 模組中)
@anchor{library/logging logging getHandlerNames}@anchor{19c0}
@deffn {函式} logging.getHandlerNames ()

Returns an immutable set of all known handler names.


在 3.12 版被加入.

@end deffn

@geindex makeLogRecord() (於 logging 模組中)
@anchor{library/logging logging makeLogRecord}@anchor{303f}
@deffn {函式} logging.makeLogRecord (attrdict)

Creates and returns a new @ref{11e1,,LogRecord} instance whose attributes are
defined by `attrdict'. This function is useful for taking a pickled
@ref{11e1,,LogRecord} attribute dictionary, sent over a socket, and reconstituting
it as a @ref{11e1,,LogRecord} instance at the receiving end.
@end deffn

@geindex basicConfig() (於 logging 模組中)
@anchor{library/logging logging basicConfig}@anchor{bea}
@deffn {函式} logging.basicConfig (**kwargs)

Does basic configuration for the logging system by creating a
@ref{13f9,,StreamHandler} with a default @ref{168b,,Formatter} and adding it to the
root logger. The functions @ref{3012,,debug()}, @ref{303b,,info()}, @ref{352,,warning()},
@ref{304f,,error()} and @ref{3050,,critical()} will call @ref{bea,,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

支援以下的關鍵字引數。


@multitable {xxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

格式

@tab

描述

@item

`filename'

@tab

Specifies that a @ref{1b55,,FileHandler} be
created, using the specified filename,
rather than a @ref{13f9,,StreamHandler}.

@item

`filemode'

@tab

If `filename' is specified, open the file
in this @ref{2484,,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{13ea,,time.strftime()}.

@item

`style'

@tab

If `format' is specified, use this style
for the format string. One of @code{'%'},
@code{'@{'} or @code{'$'} for @ref{8d3,,printf-style},
@ref{82c,,str.format()} or
@ref{890,,string.Template} respectively.
Defaults to @code{'%'}.

@item

`level'

@tab

Set the root logger level to the specified
@ref{863,,level}.

@item

`stream'

@tab

Use the specified stream to initialize the
@ref{13f9,,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{1b55,,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{1b55,,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{315,,open()},
which means that it will be treated the
same as passing 'errors'.

@end multitable



在 3.2 版的變更: 新增 `style' 引數。



在 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 版的變更: 新增 `force' 引數。



在 3.9 版的變更: 新增 `encoding' 與 `errors' 引數。

@end deffn

@geindex shutdown() (於 logging 模組中)
@anchor{library/logging logging shutdown}@anchor{3056}
@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{304e}
@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{b50,,logging.getLogger()} API to get your loggers.
@end deffn

@geindex setLogRecordFactory() (於 logging 模組中)
@anchor{library/logging logging setLogRecordFactory}@anchor{3043}
@deffn {函式} logging.setLogRecordFactory (factory)

Set a callable which is used to create a @ref{11e1,,LogRecord}.

@*參數: 
@code{factory} -- The factory callable to be used to instantiate a log record.



在 3.2 版被加入: This function has been provided, along with @ref{3042,,getLogRecordFactory()}, to
allow developers more control over how the @ref{11e1,,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{1081,,traceback.print_stack()}, showing the call hierarchy.


@*kwargs: 
額外的關鍵字引數。

@end quotation
@end deffn

@node 模組層級屬性,Integration with the warnings module,模組層級函式,logging --- Python 的日誌記錄工具
@anchor{library/logging module-level-attributes}@anchor{3057}
@subsubsection 模組層級屬性


@geindex lastResort (於 logging 模組中)
@anchor{library/logging logging lastResort}@anchor{13fb}
@deffn {資料} logging.lastResort

A "handler of last resort" is available through this attribute. This
is a @ref{13f9,,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}.


在 3.2 版被加入.

@end deffn

@geindex raiseExceptions (於 logging 模組中)
@anchor{library/logging logging raiseExceptions}@anchor{13fa}
@deffn {資料} logging.raiseExceptions

Used to see if exceptions during handling should be propagated.

Default: @code{True}.

If @ref{13fa,,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,,模組層級屬性,logging --- Python 的日誌記錄工具
@anchor{library/logging integration-with-the-warnings-module}@anchor{3058}
@subsubsection Integration with the warnings module


The @ref{3059,,captureWarnings()} function can be used to integrate @ref{8b,,logging}
with the @ref{118,,warnings} module.

@geindex captureWarnings() (於 logging 模組中)
@anchor{library/logging logging captureWarnings}@anchor{3059}
@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{118,,warnings} module will
be redirected to the logging system. Specifically, a warning will be
formatted using @ref{1cc0,,warnings.formatwarning()} and the resulting string
logged to a logger named @code{'py.warnings'} with a severity of @ref{1fa6,,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 @ref{8c,,logging.config} 模組

Configuration API for the logging module.

@item @ref{8d,,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 @ref{8b,,logging} package.  The version of the
package available from this site is suitable for use with Python 1.5.2, 2.1.x
and 2.2.x, which do not include the @ref{8b,,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 handlers --- 日誌紀錄處理器,logging --- Python 的日誌記錄工具,通用作業系統服務
@anchor{library/logging config doc}@anchor{305a}@anchor{library/logging config logging-config-logging-configuration}@anchor{305b}@anchor{library/logging config module-logging config}@anchor{8c}@anchor{library/logging config translation-repo}@anchor{305c}
@subsection @code{logging.config} --- 日誌記錄配置


@geindex module; logging.config

`原始碼：'Lib/logging/config.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/logging/config.py}

@subsubheading Important



This page contains only reference information. For tutorials,
please see


@itemize *

@item 
@ref{13f6,,基礎教學}

@item 
@ref{13f7,,進階教學}

@item 
@ref{13f8,,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 --- 日誌記錄配置
@anchor{library/logging config configuration-functions}@anchor{305d}@anchor{library/logging config logging-config-api}@anchor{14f2}
@subsubsection Configuration functions


The following functions configure the logging module. They are located in the
@ref{8c,,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{8b,,logging} itself) and defining handlers which are declared either in
@ref{8b,,logging} or @ref{8d,,logging.handlers}.

@geindex dictConfig() (於 logging.config 模組中)
@anchor{library/logging config logging config dictConfig}@anchor{13b1}
@deffn {函式} logging.config.dictConfig (config)

Takes the logging configuration from a dictionary.  The contents of
this dictionary are described in @ref{305e,,Configuration dictionary schema}
below.

If an error is encountered during configuration, this function will
raise a @ref{2eb,,ValueError}, @ref{198,,TypeError}, @ref{5e8,,AttributeError}
or @ref{653,,ImportError} with a suitably descriptive message.  The
following is a (possibly incomplete) list of conditions which will
raise an error:


@itemize *

@item 
A @code{level} which is not a string or which is a string not
corresponding to an actual logging level.

@item 
A @code{propagate} value which is not a boolean.

@item 
An id which does not have a corresponding destination.

@item 
A non-existent handler id found during an incremental call.

@item 
An invalid logger name.

@item 
Inability to resolve to an internal or external object.
@end itemize

Parsing is performed by the @code{DictConfigurator} class, whose
constructor is passed the dictionary used for configuration, and
has a @code{configure()} method.  The @ref{8c,,logging.config} module
has a callable attribute @code{dictConfigClass}
which is initially set to @code{DictConfigurator}.
You can replace the value of @code{dictConfigClass} with a
suitable implementation of your own.

@ref{13b1,,dictConfig()} calls @code{dictConfigClass} passing
the specified dictionary, and then calls the @code{configure()} method on
the returned object to put the configuration into effect:

@example
def dictConfig(config):
    dictConfigClass(config).configure()
@end example

For example, a subclass of @code{DictConfigurator} could call
@code{DictConfigurator.__init__()} in its own @code{__init__()}, then
set up custom prefixes which would be usable in the subsequent
@code{configure()} call. @code{dictConfigClass} would be bound to
this new subclass, and then @ref{13b1,,dictConfig()} could be called exactly as
in the default, uncustomized state.


在 3.2 版被加入.

@end deffn

@geindex fileConfig() (於 logging.config 模組中)
@anchor{library/logging config logging config fileConfig}@anchor{d40}
@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{305f,,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{264,,FileNotFoundError} if the file
doesn't exist and @ref{244,,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{115f,,RawConfigParser}. If a
@code{RawConfigParser}-derived instance is passed, it is used as
is. Otherwise, a @ref{4d9,,ConfigParser} is
instantiated, and the configuration read by it from the
object passed in @code{fname}. If that has a @ref{bf,,readline()}
method, it is assumed to be a file-like object and read using
@ref{723,,read_file()}; otherwise,
it is assumed to be a filename and passed to
@ref{165d,,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{115f,,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{1160}
@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{13b1,,dictConfig()} or
@ref{d40,,fileConfig()}. Returns a @ref{176,,Thread} instance on which
you can call @ref{178,,start()} to start the server, and which
you can @ref{13e5,,join()} when appropriate. To stop the server,
call @ref{3060,,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{3061}
@cartouche
@quotation 備註 
Because portions of the configuration are passed through
@ref{49e,,eval()}, use of this function may open its users to a security risk.
While the function only binds to a socket on @code{localhost}, and so does
not accept connections from remote machines, there are scenarios where
untrusted code could be run under the account of the process which calls
@ref{1160,,listen()}. Specifically, if the process calling @ref{1160,,listen()} runs
on a multi-user machine where users cannot trust each other, then a
malicious user could arrange to run essentially arbitrary code in a
victim user's process, simply by connecting to the victim's
@ref{1160,,listen()} socket and sending a configuration which runs whatever
code the attacker wants to have executed in the victim's process. This is
especially easy to do if the default port is used, but not hard even if a
different port is used. To avoid the risk of this happening, use the
@code{verify} argument to @ref{1160,,listen()} to prevent unrecognised
configurations from being applied.
@end quotation
@end cartouche


在 3.4 版的變更: 新增 @code{verify} 引數。


@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{13b1,,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{3060}
@deffn {函式} logging.config.stopListening ()

Stops the listening server which was created with a call to @ref{1160,,listen()}.
This is typically called before calling @code{join()} on the return value from
@ref{1160,,listen()}.
@end deffn

@node Security considerations,Configuration dictionary schema,Configuration functions,logging config --- 日誌記錄配置
@anchor{library/logging config security-considerations}@anchor{3062}
@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{3063,,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 --- 日誌記錄配置
@anchor{library/logging config configuration-dictionary-schema}@anchor{3064}@anchor{library/logging config logging-config-dictschema}@anchor{305e}
@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{8b,,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{3065,,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{3066}
@subsubsection Dictionary Schema Details


The dictionary passed to @ref{13b1,,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{3063,,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{3067}

@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{168b,,Formatter} instance.

The configuring dict is searched for the following optional keys
which correspond to the arguments passed to create a
@ref{168b,,Formatter} object:


@itemize *

@item 
@code{format}

@item 
@code{datefmt}

@item 
@code{style}

@item 
@code{validate} (自 3.8 版起)

@item 
@code{defaults} (自 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{168b,,Formatter}, thus this key is
most useful for instantiating a customised subclass of
@ref{168b,,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{3063,,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{13fc,,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{13f9,,logging.StreamHandler}, using @code{sys.stdout} as the underlying
stream.  The handler with id @code{file} is instantiated as a
@ref{18a8,,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{d40,,fileConfig()} API.

If the specified value is @code{True}, the configuration is processed
as described in the section on @ref{3068,,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{d40,,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{3069}@anchor{library/logging config logging-config-dict-incremental}@anchor{3068}
@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{3065}@anchor{library/logging config object-connections}@anchor{306a}
@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{3063}@anchor{library/logging config user-defined-objects}@anchor{306b}
@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{168b,,logging.Formatter} instance with the
specified format string.  The second, with id @code{default}, has a
longer format and also defines the time format explicitly, and will
result in a @ref{168b,,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

和：

@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{168b,,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{306c}@anchor{library/logging config handler-configuration-order}@anchor{306d}
@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{306e}@anchor{library/logging config logging-config-dict-externalobj}@anchor{306f}
@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{3070}@anchor{library/logging config logging-config-dict-internalobj}@anchor{3071}
@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{8b,,logging} module.  For
example, consider @ref{3072,,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{3073}@anchor{library/logging config logging-import-resolution}@anchor{3074}
@subsubsection Import resolution and custom importers


Import resolution, by default, uses the builtin @ref{ac8,,__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{451,,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{451,,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{18ad}@anchor{library/logging config configuring-queuehandler-and-queuelistener}@anchor{3075}
@subsubsection Configuring QueueHandler and QueueListener


If you want to configure a @ref{1a90,,QueueHandler}, noting that this
is normally used in conjunction with a @ref{242,,QueueListener}, you
can configure both together. After the configuration, the @code{QueueListener} instance
will be available as the @ref{3076,,listener} attribute of
the created handler, and that in turn will be available to you using
@ref{1a91,,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{3077,,Queue.put_nowait}
and @ref{3078,,Queue.get} public API. For instance, this may be
an actual instance of @ref{158c,,queue.Queue} or a subclass thereof, or a proxy
obtained by @ref{3079,,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{158c,,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{3063,,User-defined objects}. The result of this construction should be a
@ref{158c,,queue.Queue} instance.
@end itemize

If the  @code{queue} key is absent, a standard unbounded @ref{158c,,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{242,,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{3063,,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{242,,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{1a90,,QueueHandler} and
@ref{242,,QueueListener}.


在 3.12 版被加入.


@node Configuration file format,,Configuration dictionary schema,logging config --- 日誌記錄配置
@anchor{library/logging config configuration-file-format}@anchor{307a}@anchor{library/logging config logging-config-fileformat}@anchor{305f}
@subsubsection Configuration file format


The configuration file format understood by @ref{d40,,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{d40,,fileConfig()} API is older than the @ref{13b1,,dictConfig()} API and does
not provide functionality to cover certain aspects of logging. For example,
you cannot configure @ref{13fc,,Filter} objects, which provide for
filtering of messages beyond simple integer levels, using @ref{d40,,fileConfig()}.
If you need to have instances of @ref{13fc,,Filter} in your logging
configuration, you will need to use @ref{13b1,,dictConfig()}. Note that future
enhancements to configuration functionality will be added to
@ref{13b1,,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{2476,,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{49e,,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{2476,,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{2476,,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{3067,,formatters section}.

The @code{defaults} entry, when @ref{2476,,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{49e,,eval()} as described above, there are
potential security risks which result from using the @ref{1160,,listen()} to send
and receive configurations via sockets. The risks are limited to where
multiple users with no mutual trust run code on the same machine; see the
@ref{1160,,listen()} documentation for more information.
@end quotation
@end cartouche


@subsubheading 也參考



@table @asis

@item @ref{8b,,logging} 模組

API reference for the logging module.

@item @ref{8d,,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 --- 日誌紀錄處理器,platform --- 對底層平臺識別資料的存取,logging config --- 日誌記錄配置,通用作業系統服務
@anchor{library/logging handlers doc}@anchor{307b}@anchor{library/logging handlers logging-handlers-logging-handlers}@anchor{307c}@anchor{library/logging handlers module-logging handlers}@anchor{8d}@anchor{library/logging handlers translation-repo}@anchor{307d}
@subsection @code{logging.handlers} --- 日誌紀錄處理器


@geindex module; logging.handlers

`原始碼：'Lib/logging/handlers.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/logging/handlers.py}

@subsubheading Important



This page contains only reference information. For tutorials,
please see


@itemize *

@item 
@ref{13f6,,基礎教學}

@item 
@ref{13f7,,進階教學}

@item 
@ref{13f8,,Logging Cookbook}
@end itemize


__________________________________________________________________


The following useful handlers are provided in the package. Note that three of
the handlers (@ref{13f9,,StreamHandler}, @ref{1b55,,FileHandler} and
@ref{1485,,NullHandler}) are actually defined in the @ref{8b,,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 --- 日誌紀錄處理器
@anchor{library/logging handlers stream-handler}@anchor{307e}@anchor{library/logging handlers streamhandler}@anchor{307f}
@subsubsection StreamHandler


The @ref{13f9,,StreamHandler} class, located in the core @ref{8b,,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{13f9}
@deffn {類別} logging.StreamHandler (stream=None)

Returns a new instance of the @ref{13f9,,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{3080}
@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{3081,,terminator}. If exception information
is present, it is formatted using @ref{a48,,traceback.print_exception()} and
appended to the stream.
@end deffn

@geindex flush() (logging.StreamHandler 的方法)
@anchor{library/logging handlers logging StreamHandler flush}@anchor{3082}
@deffn {方法} flush ()

Flushes the stream by calling its @ref{3082,,flush()} method. Note that the
@code{close()} method is inherited from @ref{168a,,Handler} and so
does no output, so an explicit @ref{3082,,flush()} call may be needed at times.
@end deffn

@geindex setStream() (logging.StreamHandler 的方法)
@anchor{library/logging handlers logging StreamHandler setStream}@anchor{d3f}
@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.



在 3.7 版被加入.

@end deffn

@geindex terminator (logging.StreamHandler 的屬性)
@anchor{library/logging handlers logging StreamHandler terminator}@anchor{3081}
@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'}.


在 3.2 版被加入.

@end deffn
@end deffn

@node FileHandler,NullHandler,StreamHandler,logging handlers --- 日誌紀錄處理器
@anchor{library/logging handlers file-handler}@anchor{3083}@anchor{library/logging handlers filehandler}@anchor{3084}
@subsubsection FileHandler


The @ref{1b55,,FileHandler} class, located in the core @ref{8b,,logging} package,
sends logging output to a disk file.  It inherits the output functionality from
@ref{13f9,,StreamHandler}.

@geindex FileHandler (logging 中的類別)
@anchor{library/logging handlers logging FileHandler}@anchor{1b55}
@deffn {類別} logging.FileHandler (filename, mode='a', encoding=None, delay=False, errors=None)

Returns a new instance of the @ref{1b55,,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{3085,,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{266,,Path} objects are also accepted
for the `filename' argument.



在 3.9 版的變更: 新增 `errors' 參數。


@geindex close() (logging.FileHandler 的方法)
@anchor{library/logging handlers logging FileHandler close}@anchor{3086}
@deffn {方法} close ()

Closes the file.
@end deffn

@geindex emit() (logging.FileHandler 的方法)
@anchor{library/logging handlers logging FileHandler emit}@anchor{3085}
@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 --- 日誌紀錄處理器
@anchor{library/logging handlers null-handler}@anchor{3087}@anchor{library/logging handlers nullhandler}@anchor{3088}
@subsubsection NullHandler



在 3.1 版被加入.


The @ref{1485,,NullHandler} class, located in the core @ref{8b,,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{1485}
@deffn {類別} logging.NullHandler

Returns a new instance of the @ref{1485,,NullHandler} class.

@geindex emit() (logging.NullHandler 的方法)
@anchor{library/logging handlers logging NullHandler emit}@anchor{3089}
@deffn {方法} emit (record)

This method does nothing.
@end deffn

@geindex handle() (logging.NullHandler 的方法)
@anchor{library/logging handlers logging NullHandler handle}@anchor{308a}
@deffn {方法} handle (record)

This method does nothing.
@end deffn

@geindex createLock() (logging.NullHandler 的方法)
@anchor{library/logging handlers logging NullHandler createLock}@anchor{308b}
@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{308c,,Configuring Logging for a Library} for more information on how to use
@ref{1485,,NullHandler}.

@node WatchedFileHandler,BaseRotatingHandler,NullHandler,logging handlers --- 日誌紀錄處理器
@anchor{library/logging handlers watched-file-handler}@anchor{308d}@anchor{library/logging handlers watchedfilehandler}@anchor{308e}
@subsubsection WatchedFileHandler


The @ref{308f,,WatchedFileHandler} class, located in the @ref{8d,,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{26d,,stat()} always returns zero
for this value.

@geindex WatchedFileHandler (logging.handlers 中的類別)
@anchor{library/logging handlers logging handlers WatchedFileHandler}@anchor{308f}
@deffn {類別} logging.handlers.WatchedFileHandler (filename, mode='a', encoding=None, delay=False, errors=None)

Returns a new instance of the @ref{308f,,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{3090,,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{266,,Path} objects are also accepted
for the `filename' argument.



在 3.9 版的變更: 新增 `errors' 參數。


@geindex reopenIfNeeded() (logging.handlers.WatchedFileHandler 的方法)
@anchor{library/logging handlers logging handlers WatchedFileHandler reopenIfNeeded}@anchor{eaf}
@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.


在 3.6 版被加入.

@end deffn

@geindex emit() (logging.handlers.WatchedFileHandler 的方法)
@anchor{library/logging handlers logging handlers WatchedFileHandler emit}@anchor{3090}
@deffn {方法} emit (record)

Outputs the record to the file, but first calls @ref{eaf,,reopenIfNeeded()} to
reopen the file if it has changed.
@end deffn
@end deffn

@node BaseRotatingHandler,RotatingFileHandler,WatchedFileHandler,logging handlers --- 日誌紀錄處理器
@anchor{library/logging handlers base-rotating-handler}@anchor{3091}@anchor{library/logging handlers baserotatinghandler}@anchor{3092}
@subsubsection BaseRotatingHandler


The @ref{3093,,BaseRotatingHandler} class, located in the @ref{8d,,logging.handlers}
module, is the base class for the rotating file handlers,
@ref{18a8,,RotatingFileHandler} and @ref{115c,,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{3093}
@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{3094}
@deffn {屬性} namer

If this attribute is set to a callable, the @ref{3095,,rotation_filename()}
method delegates to this callable. The parameters passed to the callable
are those passed to @ref{3095,,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{18a8,,RotatingFileHandler} expects to have a set of log files
whose names contain successive integers, so that rotation works as expected,
and @ref{115c,,TimedRotatingFileHandler} deletes old log files (based on the
@code{backupCount} parameter passed to the handler's initializer) by determining
the oldest files to delete. For this to happen, the filenames should be
sortable using the date/time portion of the filename, and a namer needs to
respect this. (If a namer is wanted that doesn't respect this scheme, it will
need to be used in a subclass of @ref{115c,,TimedRotatingFileHandler} which
overrides the @ref{3096,,getFilesToDelete()} method to
fit in with the custom naming scheme.)
@end quotation
@end cartouche


在 3.3 版被加入.

@end deffn

@geindex rotator (logging.handlers.BaseRotatingHandler 的屬性)
@anchor{library/logging handlers logging handlers BaseRotatingHandler rotator}@anchor{3097}
@deffn {屬性} rotator

If this attribute is set to a callable, the @ref{3098,,rotate()} method
delegates to this callable.  The parameters passed to the callable are
those passed to @ref{3098,,rotate()}.


在 3.3 版被加入.

@end deffn

@geindex rotation_filename() (logging.handlers.BaseRotatingHandler 的方法)
@anchor{library/logging handlers logging handlers BaseRotatingHandler rotation_filename}@anchor{3095}
@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.



在 3.3 版被加入.

@end deffn

@geindex rotate() (logging.handlers.BaseRotatingHandler 的方法)
@anchor{library/logging handlers logging handlers BaseRotatingHandler rotate}@anchor{3098}
@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



在 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{18a8,,RotatingFileHandler} and
@ref{115c,,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{3099,,Using a rotator and namer to customize log rotation processing}.

@node RotatingFileHandler,TimedRotatingFileHandler,BaseRotatingHandler,logging handlers --- 日誌紀錄處理器
@anchor{library/logging handlers rotating-file-handler}@anchor{309a}@anchor{library/logging handlers rotatingfilehandler}@anchor{309b}
@subsubsection RotatingFileHandler


The @ref{18a8,,RotatingFileHandler} class, located in the @ref{8d,,logging.handlers}
module, supports rotation of disk log files.

@geindex RotatingFileHandler (logging.handlers 中的類別)
@anchor{library/logging handlers logging handlers RotatingFileHandler}@anchor{18a8}
@deffn {類別} logging.handlers.RotatingFileHandler (filename, mode='a', maxBytes=0, backupCount=0, encoding=None, delay=False, errors=None)

Returns a new instance of the @ref{18a8,,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{309c,,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{266,,Path} objects are also accepted
for the `filename' argument.



在 3.9 版的變更: 新增 `errors' 參數。


@geindex doRollover() (logging.handlers.RotatingFileHandler 的方法)
@anchor{library/logging handlers logging handlers RotatingFileHandler doRollover}@anchor{309d}
@deffn {方法} doRollover ()

Does a rollover, as described above.
@end deffn

@geindex emit() (logging.handlers.RotatingFileHandler 的方法)
@anchor{library/logging handlers logging handlers RotatingFileHandler emit}@anchor{309c}
@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{309e}
@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 --- 日誌紀錄處理器
@anchor{library/logging handlers timed-rotating-file-handler}@anchor{309f}@anchor{library/logging handlers timedrotatingfilehandler}@anchor{30a0}
@subsubsection TimedRotatingFileHandler


The @ref{115c,,TimedRotatingFileHandler} class, located in the
@ref{8d,,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{115c}
@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 @ref{115c,,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{30a1,,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' 參數。



在 3.6 版的變更: As well as string values, @ref{266,,Path} objects are also accepted
for the `filename' argument.



在 3.9 版的變更: 新增 `errors' 參數。


@geindex doRollover() (logging.handlers.TimedRotatingFileHandler 的方法)
@anchor{library/logging handlers logging handlers TimedRotatingFileHandler doRollover}@anchor{30a2}
@deffn {方法} doRollover ()

Does a rollover, as described above.
@end deffn

@geindex emit() (logging.handlers.TimedRotatingFileHandler 的方法)
@anchor{library/logging handlers logging handlers TimedRotatingFileHandler emit}@anchor{30a1}
@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{3096}
@deffn {方法} getFilesToDelete ()

Returns a list of filenames which should be deleted as part of rollover. These
@end deffn

@geindex shouldRollover() (logging.handlers.TimedRotatingFileHandler 的方法)
@anchor{library/logging handlers logging handlers TimedRotatingFileHandler shouldRollover}@anchor{30a3}
@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 --- 日誌紀錄處理器
@anchor{library/logging handlers socket-handler}@anchor{30a4}@anchor{library/logging handlers sockethandler}@anchor{30a5}
@subsubsection SocketHandler


The @ref{115d,,SocketHandler} class, located in the @ref{8d,,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{115d}
@deffn {類別} logging.handlers.SocketHandler (host, port)

Returns a new instance of the @ref{115d,,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{30a6}
@deffn {方法} close ()

Closes the socket.
@end deffn

@geindex emit() (logging.handlers.SocketHandler 的方法)
@anchor{library/logging handlers logging handlers SocketHandler emit}@anchor{30a7}
@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{11e1,,LogRecord}, use the @ref{303f,,makeLogRecord()}
function.
@end deffn

@geindex handleError() (logging.handlers.SocketHandler 的方法)
@anchor{library/logging handlers logging handlers SocketHandler handleError}@anchor{30a8}
@deffn {方法} handleError ()

Handles an error which has occurred during @ref{30a7,,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{30a9}
@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{14f4,,socket.SOCK_STREAM}).
@end deffn

@geindex makePickle() (logging.handlers.SocketHandler 的方法)
@anchor{library/logging handlers logging handlers SocketHandler makePickle}@anchor{30aa}
@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{30ab}
@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{30aa,,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{866}
@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 --- 日誌紀錄處理器
@anchor{library/logging handlers datagram-handler}@anchor{30ac}@anchor{library/logging handlers datagramhandler}@anchor{30ad}
@subsubsection DatagramHandler


The @ref{115e,,DatagramHandler} class, located in the @ref{8d,,logging.handlers}
module, inherits from @ref{115d,,SocketHandler} to support sending logging messages
over UDP sockets.

@geindex DatagramHandler (logging.handlers 中的類別)
@anchor{library/logging handlers logging handlers DatagramHandler}@anchor{115e}
@deffn {類別} logging.handlers.DatagramHandler (host, port)

Returns a new instance of the @ref{115e,,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{30ae}
@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{11e1,,LogRecord}, use the @ref{303f,,makeLogRecord()}
function.
@end deffn

@geindex makeSocket() (logging.handlers.DatagramHandler 的方法)
@anchor{library/logging handlers logging handlers DatagramHandler makeSocket}@anchor{30af}
@deffn {方法} makeSocket ()

The factory method of @ref{115d,,SocketHandler} is here overridden to create
a UDP socket (@ref{14f3,,socket.SOCK_DGRAM}).
@end deffn

@geindex send() (logging.handlers.DatagramHandler 的方法)
@anchor{library/logging handlers logging handlers DatagramHandler send}@anchor{30b0}
@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{30aa,,SocketHandler.makePickle()}.
@end deffn
@end deffn

@node SysLogHandler,NTEventLogHandler,DatagramHandler,logging handlers --- 日誌紀錄處理器
@anchor{library/logging handlers syslog-handler}@anchor{30b1}@anchor{library/logging handlers sysloghandler}@anchor{30b2}
@subsubsection SysLogHandler


The @ref{865,,SysLogHandler} class, located in the @ref{8d,,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{865}
@deffn {類別} logging.handlers.SysLogHandler (address=('localhost', SYSLOG_UDP_PORT), facility=LOG_USER, socktype=socket.SOCK_DGRAM, timeout=None)

Returns a new instance of the @ref{865,,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{14f3,,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{14f4,,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,
@ref{865,,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 @ref{865,,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'。



在 3.14 版的變更: 新增 `timeout'。


@geindex close() (logging.handlers.SysLogHandler 的方法)
@anchor{library/logging handlers logging handlers SysLogHandler close}@anchor{30b3}
@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{864}
@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.


在 3.11 版被加入.

@end deffn

@geindex emit() (logging.handlers.SysLogHandler 的方法)
@anchor{library/logging handlers logging handlers SysLogHandler emit}@anchor{30b4}
@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{30b5}
@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 @ref{865,,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} 或 @code{critical}

@tab

LOG_CRIT

@item

@code{debug}

@tab

LOG_DEBUG

@item

@code{emerg} 或 @code{panic}

@tab

LOG_EMERG

@item

@code{err} 或 @code{error}

@tab

LOG_ERR

@item

@code{info}

@tab

LOG_INFO

@item

@code{notice}

@tab

LOG_NOTICE

@item

@code{warn} 或 @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{30b6}
@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 --- 日誌紀錄處理器
@anchor{library/logging handlers nt-eventlog-handler}@anchor{30b7}@anchor{library/logging handlers nteventloghandler}@anchor{30b8}
@subsubsection NTEventLogHandler


The @ref{30b9,,NTEventLogHandler} class, located in the @ref{8d,,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{30b9}
@deffn {類別} logging.handlers.NTEventLogHandler (appname, dllname=None, logtype='Application')

Returns a new instance of the @ref{30b9,,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{30ba}
@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{30bb}
@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{30bc}
@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{30bd}
@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{30be}
@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 --- 日誌紀錄處理器
@anchor{library/logging handlers smtp-handler}@anchor{30bf}@anchor{library/logging handlers smtphandler}@anchor{30c0}
@subsubsection SMTPHandler


The @ref{1828,,SMTPHandler} class, located in the @ref{8d,,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{1828}
@deffn {類別} logging.handlers.SMTPHandler (mailhost, fromaddr, toaddrs, subject, credentials=None, secure=None, timeout=1.0)

Returns a new instance of the @ref{1828,,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{1339,,smtplib.SMTP.starttls()} method.)

A timeout can be specified for communication with the SMTP server using the
`timeout' argument.


在 3.3 版的變更: 新增 `timeout' 參數。


@geindex emit() (logging.handlers.SMTPHandler 的方法)
@anchor{library/logging handlers logging handlers SMTPHandler emit}@anchor{30c1}
@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{30c2}
@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 --- 日誌紀錄處理器
@anchor{library/logging handlers memory-handler}@anchor{30c3}@anchor{library/logging handlers memoryhandler}@anchor{30c4}
@subsubsection MemoryHandler


The @ref{3072,,MemoryHandler} class, located in the @ref{8d,,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{3072,,MemoryHandler} is a subclass of the more general
@ref{30c5,,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{30c5}
@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{30c6}
@deffn {方法} emit (record)

Append the record to the buffer. If @ref{30c7,,shouldFlush()} returns true,
call @ref{30c8,,flush()} to process the buffer.
@end deffn

@geindex flush() (logging.handlers.BufferingHandler 的方法)
@anchor{library/logging handlers logging handlers BufferingHandler flush}@anchor{30c8}
@deffn {方法} flush ()

For a @ref{30c5,,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{30c7}
@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{3072}
@deffn {類別} logging.handlers.MemoryHandler (capacity, flushLevel=ERROR, target=None, flushOnClose=True)

Returns a new instance of the @ref{3072,,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{30c9,,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 版的變更: 新增 `flushOnClose' 參數。


@geindex close() (logging.handlers.MemoryHandler 的方法)
@anchor{library/logging handlers logging handlers MemoryHandler close}@anchor{30ca}
@deffn {方法} close ()

Calls @ref{30cb,,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{30cb}
@deffn {方法} flush ()

For a @ref{3072,,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{30c9}
@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{30cc}
@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 --- 日誌紀錄處理器
@anchor{library/logging handlers http-handler}@anchor{30cd}@anchor{library/logging handlers httphandler}@anchor{30ce}
@subsubsection HTTPHandler


The @ref{1027,,HTTPHandler} class, located in the @ref{8d,,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{1027}
@deffn {類別} logging.handlers.HTTPHandler (host, url, method='GET', secure=False, credentials=None, context=None)

Returns a new instance of the @ref{1027,,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{355,,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 版的變更: 新增 `context' 參數。


@geindex mapLogRecord() (logging.handlers.HTTPHandler 的方法)
@anchor{library/logging handlers logging handlers HTTPHandler mapLogRecord}@anchor{30cf}
@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{11e1,,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{30d0}
@deffn {方法} emit (record)

Sends the record to the web server as a URL-encoded dictionary. The
@ref{30cf,,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{3023,,setFormatter()} to specify a
@ref{168b,,Formatter} for a @ref{1027,,HTTPHandler} has no effect.
Instead of calling @ref{302c,,format()}, this handler calls
@ref{30cf,,mapLogRecord()} and then @ref{1090,,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 --- 日誌紀錄處理器
@anchor{library/logging handlers queue-handler}@anchor{30d1}@anchor{library/logging handlers queuehandler}@anchor{30d2}
@subsubsection QueueHandler



在 3.2 版被加入.


The @ref{1a90,,QueueHandler} class, located in the @ref{8d,,logging.handlers} module,
supports sending logging messages to a queue, such as those implemented in the
@ref{bb,,queue} or @ref{98,,multiprocessing} modules.

Along with the @ref{242,,QueueListener} class, @ref{1a90,,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{1828,,SMTPHandler}) are done on a separate thread.

@geindex QueueHandler (logging.handlers 中的類別)
@anchor{library/logging handlers logging handlers QueueHandler}@anchor{1a90}
@deffn {類別} logging.handlers.QueueHandler (queue)

Returns a new instance of the @ref{1a90,,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{30d3,,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{d59,,SimpleQueue} instances for `queue'.

@cartouche
@quotation 備註 
If you are using @ref{98,,multiprocessing}, you should avoid using
@ref{d59,,SimpleQueue} and instead use @ref{1ab3,,multiprocessing.Queue}.
@end quotation
@end cartouche

@cartouche
@quotation 警告 
The @ref{98,,multiprocessing} module uses an internal logger created and
accessed via @ref{30d4,,get_logger()}.
@ref{1ab3,,multiprocessing.Queue} will log @code{DEBUG} level messages upon
items being queued. If those log messages are processed by a
@ref{1a90,,QueueHandler} using the same @ref{1ab3,,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{30d5}
@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{302a,,handleError()} method is called to handle the
error. This can result in the record silently being dropped (if
@ref{13fa,,logging.raiseExceptions} is @code{False}) or a message printed to
@code{sys.stderr} (if @ref{13fa,,logging.raiseExceptions} is @code{True}).
@end deffn

@geindex prepare() (logging.handlers.QueueHandler 的方法)
@anchor{library/logging handlers logging handlers QueueHandler prepare}@anchor{30d6}
@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{199,,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{242,,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{30d3}
@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{3076}
@deffn {屬性} listener

When created via configuration using @ref{13b1,,dictConfig()}, this
attribute will contain a @ref{242,,QueueListener} instance for use with this
handler. Otherwise, it will be @code{None}.


在 3.12 版被加入.

@end deffn
@end deffn

@node QueueListener,,QueueHandler,logging handlers --- 日誌紀錄處理器
@anchor{library/logging handlers queue-listener}@anchor{30d7}@anchor{library/logging handlers queuelistener}@anchor{30d8}
@subsubsection QueueListener



在 3.2 版被加入.


The @ref{242,,QueueListener} class, located in the @ref{8d,,logging.handlers}
module, supports receiving logging messages from a queue, such as those
implemented in the @ref{bb,,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
@ref{242,,QueueListener} is not itself a handler, it is documented here
because it works hand-in-hand with @ref{1a90,,QueueHandler}.

Along with the @ref{1a90,,QueueHandler} class, @ref{242,,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{1828,,SMTPHandler}) are done on a separate thread.

@geindex QueueListener (logging.handlers 中的類別)
@anchor{library/logging handlers logging handlers QueueListener}@anchor{242}
@deffn {類別} logging.handlers.QueueListener (queue, *handlers, respect_handler_level=False)

Returns a new instance of the @ref{242,,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{30d9,,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{d59,,SimpleQueue} instances for `queue'.

@cartouche
@quotation 備註 
If you are using @ref{98,,multiprocessing}, you should avoid using
@ref{d59,,SimpleQueue} and instead use @ref{1ab3,,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 版的變更: 新增 @code{respect_handler_level} 引數。



在 3.14 版的變更: @ref{242,,QueueListener} can now be used as a context manager via
@ref{186,,with}. When entering the context, the listener is started. When
exiting the context, the listener is stopped.
@ref{2552,,__enter__()} returns the
@ref{242,,QueueListener} object.


@geindex dequeue() (logging.handlers.QueueListener 的方法)
@anchor{library/logging handlers logging handlers QueueListener dequeue}@anchor{30d9}
@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{30da}
@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{30db}
@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{30da,,prepare()}.
@end deffn

@geindex start() (logging.handlers.QueueListener 的方法)
@anchor{library/logging handlers logging handlers QueueListener start}@anchor{243}
@deffn {方法} start ()

Starts the listener.

This starts up a background thread to monitor the queue for
LogRecords to process.


在 3.14 版的變更: Raises @ref{244,,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{30dc}
@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{30dd}
@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.


在 3.3 版被加入.

@end deffn
@end deffn


@subsubheading 也參考



@table @asis

@item @ref{8b,,logging} 模組

API reference for the logging module.

@item @ref{8c,,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 --- 標準 errno 系統符號,logging handlers --- 日誌紀錄處理器,通用作業系統服務
@anchor{library/platform doc}@anchor{30de}@anchor{library/platform module-platform}@anchor{af}@anchor{library/platform platform-access-to-underlying-platform-s-identifying-data}@anchor{30df}@anchor{library/platform translation-repo}@anchor{30e0}
@subsection @code{platform} ---  對底層平臺識別資料的存取


@geindex module; platform

`原始碼：'Lib/platform.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/platform.py}


__________________________________________________________________


@cartouche
@quotation 備註 
特定平臺清單為按字母順序排列，Linux 包括在 Unix 小節之中。
@end quotation
@end cartouche

@menu
* 跨平台:: 
* Java 平台:: 
* Windows 平台:: 
* macOS 平台:: 
* iOS 平台:: 
* Unix 平台:: 
* Linux 平台:: 
* Android 平台:: 
* 命令列用法: 命令列用法<3>. 

@end menu

@node 跨平台,Java 平台,,platform --- 對底層平臺識別資料的存取
@anchor{library/platform cross-platform}@anchor{30e1}
@subsubsection 跨平台


@geindex architecture() (於 platform 模組中)
@anchor{library/platform platform architecture}@anchor{1955}
@deffn {函式} platform.architecture (executable=sys.executable, bits='@w{'}, linkage='@w{'})

查詢給定的可執行檔案（預設為 Python 直譯器二進位制檔案）來取得各種架構資訊。

回傳一個 tuple（元組） @code{(bits, linkage)}，其中包含可執行檔案所使用的位元架構和連結格式資訊。這兩個值均以字串形式回傳。

無法確定的值將回傳參數所給定之預先設置值。如果給定的位元為 @code{'@w{'}}，則會使用 @code{sizeof(pointer)}（或者當 Python 版本 < 1.5.2 時為 @code{sizeof(long)}）作為所支援指標大小的指示器 (indicator)。

此函式依賴於系統的 @code{file} 命令來執行實際的操作。這在幾乎所有 Unix 平臺和某些非 Unix 平臺上，只有當可執行檔案指向 Python 直譯器時才可使用。當以上要求不滿足時將會使用合理的預設值。

@cartouche
@quotation 備註 
在 macOS（也許還有其他平臺）上，可執行檔案可能是包含多種架構的通用檔案。

要取得目前直譯器的 "64 位元性 (64-bitness)"，更可靠的做法是查詢 @ref{13c6,,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{30e2}
@deffn {函式} platform.machine ()

回傳機器種類，例如 @code{'AMD64'}。如果該值無法確定則會回傳一個空字串。

The output is platform-dependent and may differ in casing and naming conventions.
@end deffn

@geindex node() (於 platform 模組中)
@anchor{library/platform platform node}@anchor{30e3}
@deffn {函式} platform.node ()

回傳電腦的網路名稱（可能不是完整名稱！）。如果該值無法確定則會回傳一個空字串。
@end deffn

@geindex platform() (於 platform 模組中)
@anchor{library/platform platform platform}@anchor{1a11}
@deffn {函式} platform.platform (aliased=False, terse=False)

會儘可能附帶有用資訊地回傳一個標識底層平臺的字串。

輸出應為`人類易讀的 (human readable)'，而非機器易剖析的 (machine parseable)。它在不同平臺上看起來可能不一致，這是有意為之的。

如果 `aliased' 為真值，此函式將使用各種不同於平臺通用名稱的別名來回報系統名稱，例如 SunOS 將被回報為 Solaris。@ref{30e4,,system_alias()} 函式被用於實作此功能。

將 `terse' 設為真值將導致此函式只回傳標識平臺所需的最小量資訊。


在 3.8 版的變更: 在 macOS 上，如果 @ref{1cdd,,mac_ver()} 回傳的釋出版字串非空字串，此函式現在會使用它以取得 macOS 版本而非 darwin 版本。

@end deffn

@geindex processor() (於 platform 模組中)
@anchor{library/platform platform processor}@anchor{30e5}
@deffn {函式} platform.processor ()

回傳（真實的）處理器名稱，例如 @code{'amdk6'}。

如果該值無法確定則將回傳空字串。請注意，許多平臺都不提供此資訊或是簡單地回傳與 @ref{30e2,,machine()} 相同的值。NetBSD 則會提供此資訊。
@end deffn

@geindex python_build() (於 platform 模組中)
@anchor{library/platform platform python_build}@anchor{30e6}
@deffn {函式} platform.python_build ()

回傳一個 tuple @code{(buildno, builddate)}，表示字串形式的 Python 建置編號和日期。
@end deffn

@geindex python_compiler() (於 platform 模組中)
@anchor{library/platform platform python_compiler}@anchor{30e7}
@deffn {函式} platform.python_compiler ()

回傳一個標識用於編譯 Python 的編譯器的字串。
@end deffn

@geindex python_branch() (於 platform 模組中)
@anchor{library/platform platform python_branch}@anchor{30e8}
@deffn {函式} platform.python_branch ()

回傳一個標識 Python 實作 SCM 分支的字串。
@end deffn

@geindex python_implementation() (於 platform 模組中)
@anchor{library/platform platform python_implementation}@anchor{30e9}
@deffn {函式} platform.python_implementation ()

回傳一個標識 Python 實作的字串。可能的回傳值有：'CPython'、'IronPython'、'Jython'、'PyPy'。
@end deffn

@geindex python_revision() (於 platform 模組中)
@anchor{library/platform platform python_revision}@anchor{30ea}
@deffn {函式} platform.python_revision ()

回傳一個標識 Python 實作 SCM 修訂版的字串。
@end deffn

@geindex python_version() (於 platform 模組中)
@anchor{library/platform platform python_version}@anchor{30eb}
@deffn {函式} platform.python_version ()

將 Python 版本以字串 @code{'major.minor.patchlevel'} 形式回傳。

請注意此回傳值不同於 Python @code{sys.version}，它總是會包括 patchlevel（預設為 @code{'0'}）。
@end deffn

@geindex python_version_tuple() (於 platform 模組中)
@anchor{library/platform platform python_version_tuple}@anchor{30ec}
@deffn {函式} platform.python_version_tuple ()

將 Python 版本以字串 tuple @code{(major, minor, patchlevel)} 形式回傳。

請注意此回傳值不同於 Python @code{sys.version}，它總是會包括 patchlevel（預設為 @code{'0'}）。
@end deffn

@geindex release() (於 platform 模組中)
@anchor{library/platform platform release}@anchor{30ed}
@deffn {函式} platform.release ()

回傳系統的釋出版本，例如 @code{'2.2.0'} 或 @code{'NT'}，如果該值無法確定則將回傳一個空字串。
@end deffn

@geindex system() (於 platform 模組中)
@anchor{library/platform platform system}@anchor{212b}
@deffn {函式} platform.system ()

回傳系統/OS 的名稱，例如 @code{'Linux'}、@code{'Darwin'}、@code{'Java'}、@code{'Windows'}。如果該值無法確定則回傳一個空字串。

On iOS and Android, this returns the user-facing OS name (i.e, @code{'iOS},
@code{'iPadOS'} or @code{'Android'}). To obtain the kernel name (@code{'Darwin'} or
@code{'Linux'}), use @ref{1317,,os.uname()}.
@end deffn

@geindex system_alias() (於 platform 模組中)
@anchor{library/platform platform system_alias}@anchor{30e4}
@deffn {函式} platform.system_alias (system, release, version)

回傳做為某些系統所使用的常見行銷名稱之別名的 @code{(system, release, version)}。它還會在可能導致混淆的情況下對資訊進行一些重新排序。
@end deffn

@geindex version() (於 platform 模組中)
@anchor{library/platform platform version}@anchor{30ee}
@deffn {函式} platform.version ()

回傳系統的釋出版本資訊，例如 @code{'#3 on degas'}。如果該值無法確定則將回傳一個空字串。

On iOS and Android, this is the user-facing OS version. To obtain the
Darwin or Linux kernel version, use @ref{1317,,os.uname()}.
@end deffn

@geindex uname() (於 platform 模組中)
@anchor{library/platform platform uname}@anchor{1cdb}
@deffn {函式} platform.uname ()

具有高可攜性 (portable) 的 uname 介面。回傳包含六個屬性的 @ref{4db,,namedtuple()}：@ref{212b,,system}、@ref{30e3,,node}、@ref{30ed,,release}、@ref{30ee,,version}、@ref{30e2,,machine} 和 @ref{30e5,,processor}。

@ref{30e5,,processor} 會延遲解析，有需求時才會解析

注意：前兩個屬性名稱與 @ref{1317,,os.uname()} 提供的名稱不同，它們分別命名為 @code{sysname} 和 @code{nodename}。

無法確定的條目會被設為 @code{'@w{'}}。


在 3.3 版的變更: 將結果從 tuple 改為 @ref{4db,,namedtuple()}。



在 3.9 版的變更: @ref{30e5,,processor} 會延遲解析，並非立即解析。

@end deffn

@geindex invalidate_caches() (於 platform 模組中)
@anchor{library/platform platform invalidate_caches}@anchor{27d}
@deffn {函式} platform.invalidate_caches ()

Clear out the internal cache of information, such as the @ref{1cdb,,uname()}.
This is typically useful when the platform's @ref{30e3,,node()} is changed
by an external process and one needs to retrieve the updated value.


在 3.14 版被加入.

@end deffn

@node Java 平台,Windows 平台,跨平台,platform --- 對底層平臺識別資料的存取
@anchor{library/platform java-platform}@anchor{30ef}
@subsubsection Java 平台


@geindex java_ver() (於 platform 模組中)
@anchor{library/platform platform java_ver}@anchor{32b}
@deffn {函式} platform.java_ver (release='@w{'}, vendor='@w{'}, vminfo=('@w{'}, '@w{'}, '@w{'}), osinfo=('@w{'}, '@w{'}, '@w{'}))

Jython 的版本介面。

回傳一個 tuple @code{(release, vendor, vminfo, osinfo)}，其中 `vminfo' 為 tuple @code{(vm_name, vm_release, vm_vendor)} 而 `osinfo' 為 tuple @code{(os_name, os_version, os_arch)}。無法確定的值將被設為由參數所給定的預設值（預設均為 @code{'@w{'}}）。


Deprecated since version 3.13, will be removed in version 3.15: It was largely untested, had a confusing API,
and was only useful for Jython support.

@end deffn

@node Windows 平台,macOS 平台,Java 平台,platform --- 對底層平臺識別資料的存取
@anchor{library/platform windows-platform}@anchor{30f0}
@subsubsection Windows 平台


@geindex win32_ver() (於 platform 模組中)
@anchor{library/platform platform win32_ver}@anchor{1c13}
@deffn {函式} platform.win32_ver (release='@w{'}, version='@w{'}, csd='@w{'}, ptype='@w{'})

從 Windows 登錄檔 (Window Registry) 取得額外的版本資訊並回傳一個 tuple @code{(release, version, csd, ptype)}，它代表 OS 發行版、版本號、CSD 級別 (service pack) 和 OS 類型（多個/單個處理器）。

一點提示：`ptype' 在單個處理器的 NT 機器上為 @code{'Uniprocessor Free'}，而在多個處理器的機器上為 @code{'Multiprocessor Free'}。@code{'Free'} 是指該 OS 版本沒有除錯程式。它也可能以 @code{'Checked'} 表示，代表該 OS 版本使用了除錯程式，即檢查引數、範圍等的程式。
@end deffn

@geindex win32_edition() (於 platform 模組中)
@anchor{library/platform platform win32_edition}@anchor{30f1}
@deffn {函式} platform.win32_edition ()

回傳一個代表目前 Windows 版本的字串。可能的值包括但不限於 @code{'Enterprise'}、@code{'IoTUAP'}、@code{'ServerStandard'} 和 @code{'nanoserver'}。


在 3.8 版被加入.

@end deffn

@geindex win32_is_iot() (於 platform 模組中)
@anchor{library/platform platform win32_is_iot}@anchor{30f2}
@deffn {函式} platform.win32_is_iot ()

如果 @ref{30f1,,win32_edition()} 回傳的 Windows 版本被識別為 IoT 版則回傳 @code{True}。


在 3.8 版被加入.

@end deffn

@node macOS 平台,iOS 平台,Windows 平台,platform --- 對底層平臺識別資料的存取
@anchor{library/platform macos-platform}@anchor{30f3}
@subsubsection macOS 平台


@geindex mac_ver() (於 platform 模組中)
@anchor{library/platform platform mac_ver}@anchor{1cdd}
@deffn {函式} platform.mac_ver (release='@w{'}, versioninfo=('@w{'}, '@w{'}, '@w{'}), machine='@w{'})

取得 Mac OS 版本資訊並將其回傳為 tuple @code{(release, versioninfo, machine)}，其中 `versioninfo' 是一個 tuple @code{(version, dev_stage, non_release_version)}。

無法確定的條目會被設為 @code{'@w{'}}。所有 tuple 條目均為字串。
@end deffn

@node iOS 平台,Unix 平台,macOS 平台,platform --- 對底層平臺識別資料的存取
@anchor{library/platform ios-platform}@anchor{30f4}
@subsubsection iOS 平台


@geindex ios_ver() (於 platform 模組中)
@anchor{library/platform platform ios_ver}@anchor{212a}
@deffn {函式} platform.ios_ver (system='@w{'}, release='@w{'}, model='@w{'}, is_simulator=False)

Get iOS version information and return it as a
@ref{4db,,namedtuple()} with the following attributes:


@itemize *

@item 
@code{system} 是 OS 名稱；可能是 @code{'iOS'} 或 @code{'iPadOS'}。

@item 
@code{release} is the iOS version number as a string (e.g., @code{'17.2'}).

@item 
@code{model} is the device model identifier; this will be a string like
@code{'iPhone13,2'} for a physical device, or @code{'iPhone'} on a simulator.

@item 
@code{is_simulator} is a boolean describing if the app is running on a
simulator or a physical device.
@end itemize

無法確定的條目會被設定為以參數給定的預設值。
@end deffn

@node Unix 平台,Linux 平台,iOS 平台,platform --- 對底層平臺識別資料的存取
@anchor{library/platform unix-platforms}@anchor{30f5}
@subsubsection Unix 平台


@geindex libc_ver() (於 platform 模組中)
@anchor{library/platform platform libc_ver}@anchor{177b}
@deffn {函式} platform.libc_ver (executable=sys.executable, lib='@w{'}, version='@w{'}, chunksize=16384)

嘗試確認可執行檔案（預設為 Python 直譯器）所連結到的 libc 版本。回傳一個字串 tuple @code{(lib, version)}，當查詢失敗時其預設值將被設為給定的參數值。

請注意，此函式對於不同 libc 版本如何為可執行檔案新增符號的方式有深層的關聯，可能僅適用於以 @code{gcc} 編譯出來的可執行檔案。

檔案會以 `chunksize' 位元組大小的分塊 (chunk) 來讀取和掃描。
@end deffn

@node Linux 平台,Android 平台,Unix 平台,platform --- 對底層平臺識別資料的存取
@anchor{library/platform linux-platforms}@anchor{30f6}
@subsubsection Linux 平台


@geindex freedesktop_os_release() (於 platform 模組中)
@anchor{library/platform platform freedesktop_os_release}@anchor{a20}
@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 的發行版。

當 @code{/etc/os-release} 與 @code{/usr/lib/os-release} 均無法被讀取時將引發 @ref{2c0,,OSError} 或其子類別。

成功時，該函式將回傳一個字典，其中鍵和值均為字串。值當中的特殊字元例如 @code{"} 和 @code{$} 會被移除引號 (unquoted)。欄位 @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


在 3.10 版被加入.

@end deffn

@node Android 平台,命令列用法<3>,Linux 平台,platform --- 對底層平臺識別資料的存取
@anchor{library/platform android-platform}@anchor{30f7}
@subsubsection Android 平台


@geindex android_ver() (於 platform 模組中)
@anchor{library/platform platform android_ver}@anchor{1919}
@deffn {函式} platform.android_ver (release='@w{'}, api_level=0, manufacturer='@w{'}, model='@w{'}, device='@w{'}, is_emulator=False)

Get Android device information. Returns a @ref{4db,,namedtuple()}
with the following attributes. Values which cannot be determined are set to
the defaults given as parameters.


@itemize *

@item 
@code{release} - Android version, as a string (e.g. @code{"14"}).

@item 
@code{api_level} - API level of the running device, as an integer (e.g. @code{34}
for Android 14). To get the API level which Python was built against, see
@ref{d7d,,sys.getandroidapilevel()}.

@item 
@code{manufacturer} - Manufacturer name@footnote{https://developer.android.com/reference/android/os/Build#MANUFACTURER}.

@item 
@code{model} - Model name@footnote{https://developer.android.com/reference/android/os/Build#MODEL} –
typically the marketing name or model number.

@item 
@code{device} - Device name@footnote{https://developer.android.com/reference/android/os/Build#DEVICE} –
typically the model number or a codename.

@item 
@code{is_emulator} - @code{True} if the device is an emulator; @code{False} if it's
a physical device.
@end itemize

Google maintains a list of known model and device names@footnote{https://storage.googleapis.com/play_public/supported_devices.html}.


在 3.13 版被加入.

@end deffn

@node 命令列用法<3>,,Android 平台,platform --- 對底層平臺識別資料的存取
@anchor{library/platform command-line-usage}@anchor{30f8}@anchor{library/platform platform-cli}@anchor{30f9}
@subsubsection 命令列用法


@ref{af,,platform} can also be invoked directly using the @ref{23c,,-m}
switch of the interpreter:

@example
python -m platform [--terse] [--nonaliased] [@{nonaliased,terse@} ...]
@end example

可接受以下選項：

@geindex platform 命令列選項; --terse
@anchor{library/platform cmdoption-platform-terse}@anchor{30fa}
@deffn {Option} @w{-}@w{-}terse

Print terse information about the platform. This is equivalent to
calling @ref{1a11,,platform.platform()} with the `terse' argument set to @code{True}.
@end deffn

@geindex platform 命令列選項; --nonaliased
@anchor{library/platform cmdoption-platform-nonaliased}@anchor{30fb}
@deffn {Option} @w{-}@w{-}nonaliased

Print platform information without system/OS name aliasing. This is
equivalent to calling @ref{1a11,,platform.platform()} with the `aliased' argument
set to @code{True}.
@end deffn

You can also pass one or more positional arguments (@code{terse}, @code{nonaliased})
to explicitly control the output format. These behave similarly to their
corresponding options.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node errno --- 標準 errno 系統符號,ctypes --- 用於 Python 的外部函式庫,platform --- 對底層平臺識別資料的存取,通用作業系統服務
@anchor{library/errno doc}@anchor{30fc}@anchor{library/errno errno-standard-errno-system-symbols}@anchor{30fd}@anchor{library/errno module-errno}@anchor{5b}@anchor{library/errno translation-repo}@anchor{30fe}
@subsection @code{errno} --- 標準 errno 系統符號


@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{30ff}
@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{2ed6,,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{1a85}
@deffn {資料} errno.EPERM

Operation not permitted. This error is mapped to the exception
@ref{f39,,PermissionError}.
@end deffn

@geindex ENOENT (於 errno 模組中)
@anchor{library/errno errno ENOENT}@anchor{25b4}
@deffn {資料} errno.ENOENT

No such file or directory. This error is mapped to the exception
@ref{264,,FileNotFoundError}.
@end deffn

@geindex ESRCH (於 errno 模組中)
@anchor{library/errno errno ESRCH}@anchor{25b8}
@deffn {資料} errno.ESRCH

No such process. This error is mapped to the exception
@ref{1256,,ProcessLookupError}.
@end deffn

@geindex EINTR (於 errno 模組中)
@anchor{library/errno errno EINTR}@anchor{f82}
@deffn {資料} errno.EINTR

Interrupted system call. This error is mapped to the exception
@ref{f83,,InterruptedError}.
@end deffn

@geindex EIO (於 errno 模組中)
@anchor{library/errno errno EIO}@anchor{3100}
@deffn {資料} errno.EIO

I/O error
@end deffn

@geindex ENXIO (於 errno 模組中)
@anchor{library/errno errno ENXIO}@anchor{3101}
@deffn {資料} errno.ENXIO

No such device or address
@end deffn

@geindex E2BIG (於 errno 模組中)
@anchor{library/errno errno E2BIG}@anchor{3102}
@deffn {資料} errno.E2BIG

Arg list too long
@end deffn

@geindex ENOEXEC (於 errno 模組中)
@anchor{library/errno errno ENOEXEC}@anchor{3103}
@deffn {資料} errno.ENOEXEC

Exec format error
@end deffn

@geindex EBADF (於 errno 模組中)
@anchor{library/errno errno EBADF}@anchor{b4b}
@deffn {資料} errno.EBADF

Bad file number
@end deffn

@geindex ECHILD (於 errno 模組中)
@anchor{library/errno errno ECHILD}@anchor{25ad}
@deffn {資料} errno.ECHILD

No child processes. This error is mapped to the exception
@ref{1253,,ChildProcessError}.
@end deffn

@geindex EAGAIN (於 errno 模組中)
@anchor{library/errno errno EAGAIN}@anchor{25a8}
@deffn {資料} errno.EAGAIN

Try again. This error is mapped to the exception @ref{235,,BlockingIOError}.
@end deffn

@geindex ENOMEM (於 errno 模組中)
@anchor{library/errno errno ENOMEM}@anchor{3104}
@deffn {資料} errno.ENOMEM

Out of memory
@end deffn

@geindex EACCES (於 errno 模組中)
@anchor{library/errno errno EACCES}@anchor{25b7}
@deffn {資料} errno.EACCES

Permission denied.  This error is mapped to the exception
@ref{f39,,PermissionError}.
@end deffn

@geindex EFAULT (於 errno 模組中)
@anchor{library/errno errno EFAULT}@anchor{3105}
@deffn {資料} errno.EFAULT

Bad address
@end deffn

@geindex ENOTBLK (於 errno 模組中)
@anchor{library/errno errno ENOTBLK}@anchor{3106}
@deffn {資料} errno.ENOTBLK

Block device required
@end deffn

@geindex EBUSY (於 errno 模組中)
@anchor{library/errno errno EBUSY}@anchor{3107}
@deffn {資料} errno.EBUSY

Device or resource busy
@end deffn

@geindex EEXIST (於 errno 模組中)
@anchor{library/errno errno EEXIST}@anchor{25b3}
@deffn {資料} errno.EEXIST

File exists. This error is mapped to the exception
@ref{121b,,FileExistsError}.
@end deffn

@geindex EXDEV (於 errno 模組中)
@anchor{library/errno errno EXDEV}@anchor{2eec}
@deffn {資料} errno.EXDEV

Cross-device link
@end deffn

@geindex ENODEV (於 errno 模組中)
@anchor{library/errno errno ENODEV}@anchor{3108}
@deffn {資料} errno.ENODEV

No such device
@end deffn

@geindex ENOTDIR (於 errno 模組中)
@anchor{library/errno errno ENOTDIR}@anchor{25b6}
@deffn {資料} errno.ENOTDIR

Not a directory. This error is mapped to the exception
@ref{1255,,NotADirectoryError}.
@end deffn

@geindex EISDIR (於 errno 模組中)
@anchor{library/errno errno EISDIR}@anchor{25b5}
@deffn {資料} errno.EISDIR

Is a directory. This error is mapped to the exception
@ref{1254,,IsADirectoryError}.
@end deffn

@geindex EINVAL (於 errno 模組中)
@anchor{library/errno errno EINVAL}@anchor{1c9b}
@deffn {資料} errno.EINVAL

Invalid argument
@end deffn

@geindex ENFILE (於 errno 模組中)
@anchor{library/errno errno ENFILE}@anchor{3109}
@deffn {資料} errno.ENFILE

File table overflow
@end deffn

@geindex EMFILE (於 errno 模組中)
@anchor{library/errno errno EMFILE}@anchor{310a}
@deffn {資料} errno.EMFILE

Too many open files
@end deffn

@geindex ENOTTY (於 errno 模組中)
@anchor{library/errno errno ENOTTY}@anchor{310b}
@deffn {資料} errno.ENOTTY

Not a typewriter
@end deffn

@geindex ETXTBSY (於 errno 模組中)
@anchor{library/errno errno ETXTBSY}@anchor{310c}
@deffn {資料} errno.ETXTBSY

Text file busy
@end deffn

@geindex EFBIG (於 errno 模組中)
@anchor{library/errno errno EFBIG}@anchor{310d}
@deffn {資料} errno.EFBIG

File too large
@end deffn

@geindex ENOSPC (於 errno 模組中)
@anchor{library/errno errno ENOSPC}@anchor{310e}
@deffn {資料} errno.ENOSPC

No space left on device
@end deffn

@geindex ESPIPE (於 errno 模組中)
@anchor{library/errno errno ESPIPE}@anchor{310f}
@deffn {資料} errno.ESPIPE

Illegal seek
@end deffn

@geindex EROFS (於 errno 模組中)
@anchor{library/errno errno EROFS}@anchor{3110}
@deffn {資料} errno.EROFS

Read-only file system
@end deffn

@geindex EMLINK (於 errno 模組中)
@anchor{library/errno errno EMLINK}@anchor{3111}
@deffn {資料} errno.EMLINK

Too many links
@end deffn

@geindex EPIPE (於 errno 模組中)
@anchor{library/errno errno EPIPE}@anchor{25ae}
@deffn {資料} errno.EPIPE

Broken pipe. This error is mapped to the exception
@ref{1257,,BrokenPipeError}.
@end deffn

@geindex EDOM (於 errno 模組中)
@anchor{library/errno errno EDOM}@anchor{3112}
@deffn {資料} errno.EDOM

Math argument out of domain of func
@end deffn

@geindex ERANGE (於 errno 模組中)
@anchor{library/errno errno ERANGE}@anchor{3113}
@deffn {資料} errno.ERANGE

Math result not representable
@end deffn

@geindex EDEADLK (於 errno 模組中)
@anchor{library/errno errno EDEADLK}@anchor{3114}
@deffn {資料} errno.EDEADLK

Resource deadlock would occur
@end deffn

@geindex ENAMETOOLONG (於 errno 模組中)
@anchor{library/errno errno ENAMETOOLONG}@anchor{3115}
@deffn {資料} errno.ENAMETOOLONG

File name too long
@end deffn

@geindex ENOLCK (於 errno 模組中)
@anchor{library/errno errno ENOLCK}@anchor{3116}
@deffn {資料} errno.ENOLCK

No record locks available
@end deffn

@geindex ENOSYS (於 errno 模組中)
@anchor{library/errno errno ENOSYS}@anchor{1a86}
@deffn {資料} errno.ENOSYS

Function not implemented
@end deffn

@geindex ENOTEMPTY (於 errno 模組中)
@anchor{library/errno errno ENOTEMPTY}@anchor{3117}
@deffn {資料} errno.ENOTEMPTY

Directory not empty
@end deffn

@geindex ELOOP (於 errno 模組中)
@anchor{library/errno errno ELOOP}@anchor{3118}
@deffn {資料} errno.ELOOP

Too many symbolic links encountered
@end deffn

@geindex EWOULDBLOCK (於 errno 模組中)
@anchor{library/errno errno EWOULDBLOCK}@anchor{25aa}
@deffn {資料} errno.EWOULDBLOCK

Operation would block. This error is mapped to the exception
@ref{235,,BlockingIOError}.
@end deffn

@geindex ENOMSG (於 errno 模組中)
@anchor{library/errno errno ENOMSG}@anchor{3119}
@deffn {資料} errno.ENOMSG

No message of desired type
@end deffn

@geindex EIDRM (於 errno 模組中)
@anchor{library/errno errno EIDRM}@anchor{311a}
@deffn {資料} errno.EIDRM

Identifier removed
@end deffn

@geindex ECHRNG (於 errno 模組中)
@anchor{library/errno errno ECHRNG}@anchor{311b}
@deffn {資料} errno.ECHRNG

Channel number out of range
@end deffn

@geindex EL2NSYNC (於 errno 模組中)
@anchor{library/errno errno EL2NSYNC}@anchor{311c}
@deffn {資料} errno.EL2NSYNC

Level 2 not synchronized
@end deffn

@geindex EL3HLT (於 errno 模組中)
@anchor{library/errno errno EL3HLT}@anchor{311d}
@deffn {資料} errno.EL3HLT

Level 3 halted
@end deffn

@geindex EL3RST (於 errno 模組中)
@anchor{library/errno errno EL3RST}@anchor{311e}
@deffn {資料} errno.EL3RST

Level 3 reset
@end deffn

@geindex ELNRNG (於 errno 模組中)
@anchor{library/errno errno ELNRNG}@anchor{311f}
@deffn {資料} errno.ELNRNG

Link number out of range
@end deffn

@geindex EUNATCH (於 errno 模組中)
@anchor{library/errno errno EUNATCH}@anchor{3120}
@deffn {資料} errno.EUNATCH

Protocol driver not attached
@end deffn

@geindex ENOCSI (於 errno 模組中)
@anchor{library/errno errno ENOCSI}@anchor{3121}
@deffn {資料} errno.ENOCSI

No CSI structure available
@end deffn

@geindex EL2HLT (於 errno 模組中)
@anchor{library/errno errno EL2HLT}@anchor{3122}
@deffn {資料} errno.EL2HLT

Level 2 halted
@end deffn

@geindex EBADE (於 errno 模組中)
@anchor{library/errno errno EBADE}@anchor{3123}
@deffn {資料} errno.EBADE

Invalid exchange
@end deffn

@geindex EBADR (於 errno 模組中)
@anchor{library/errno errno EBADR}@anchor{3124}
@deffn {資料} errno.EBADR

Invalid request descriptor
@end deffn

@geindex EXFULL (於 errno 模組中)
@anchor{library/errno errno EXFULL}@anchor{3125}
@deffn {資料} errno.EXFULL

Exchange full
@end deffn

@geindex ENOANO (於 errno 模組中)
@anchor{library/errno errno ENOANO}@anchor{3126}
@deffn {資料} errno.ENOANO

No anode
@end deffn

@geindex EBADRQC (於 errno 模組中)
@anchor{library/errno errno EBADRQC}@anchor{3127}
@deffn {資料} errno.EBADRQC

Invalid request code
@end deffn

@geindex EBADSLT (於 errno 模組中)
@anchor{library/errno errno EBADSLT}@anchor{3128}
@deffn {資料} errno.EBADSLT

Invalid slot
@end deffn

@geindex EDEADLOCK (於 errno 模組中)
@anchor{library/errno errno EDEADLOCK}@anchor{3129}
@deffn {資料} errno.EDEADLOCK

File locking deadlock error
@end deffn

@geindex EBFONT (於 errno 模組中)
@anchor{library/errno errno EBFONT}@anchor{312a}
@deffn {資料} errno.EBFONT

Bad font file format
@end deffn

@geindex ENOSTR (於 errno 模組中)
@anchor{library/errno errno ENOSTR}@anchor{312b}
@deffn {資料} errno.ENOSTR

Device not a stream
@end deffn

@geindex ENODATA (於 errno 模組中)
@anchor{library/errno errno ENODATA}@anchor{312c}
@deffn {資料} errno.ENODATA

No data available
@end deffn

@geindex ETIME (於 errno 模組中)
@anchor{library/errno errno ETIME}@anchor{312d}
@deffn {資料} errno.ETIME

Timer expired
@end deffn

@geindex ENOSR (於 errno 模組中)
@anchor{library/errno errno ENOSR}@anchor{312e}
@deffn {資料} errno.ENOSR

Out of streams resources
@end deffn

@geindex ENONET (於 errno 模組中)
@anchor{library/errno errno ENONET}@anchor{312f}
@deffn {資料} errno.ENONET

Machine is not on the network
@end deffn

@geindex ENOPKG (於 errno 模組中)
@anchor{library/errno errno ENOPKG}@anchor{3130}
@deffn {資料} errno.ENOPKG

Package not installed
@end deffn

@geindex EREMOTE (於 errno 模組中)
@anchor{library/errno errno EREMOTE}@anchor{3131}
@deffn {資料} errno.EREMOTE

Object is remote
@end deffn

@geindex ENOLINK (於 errno 模組中)
@anchor{library/errno errno ENOLINK}@anchor{3132}
@deffn {資料} errno.ENOLINK

Link has been severed
@end deffn

@geindex EADV (於 errno 模組中)
@anchor{library/errno errno EADV}@anchor{3133}
@deffn {資料} errno.EADV

Advertise error
@end deffn

@geindex ESRMNT (於 errno 模組中)
@anchor{library/errno errno ESRMNT}@anchor{3134}
@deffn {資料} errno.ESRMNT

Srmount error
@end deffn

@geindex ECOMM (於 errno 模組中)
@anchor{library/errno errno ECOMM}@anchor{3135}
@deffn {資料} errno.ECOMM

Communication error on send
@end deffn

@geindex EPROTO (於 errno 模組中)
@anchor{library/errno errno EPROTO}@anchor{3136}
@deffn {資料} errno.EPROTO

Protocol error
@end deffn

@geindex EMULTIHOP (於 errno 模組中)
@anchor{library/errno errno EMULTIHOP}@anchor{3137}
@deffn {資料} errno.EMULTIHOP

Multihop attempted
@end deffn

@geindex EDOTDOT (於 errno 模組中)
@anchor{library/errno errno EDOTDOT}@anchor{3138}
@deffn {資料} errno.EDOTDOT

RFS specific error
@end deffn

@geindex EBADMSG (於 errno 模組中)
@anchor{library/errno errno EBADMSG}@anchor{3139}
@deffn {資料} errno.EBADMSG

Not a data message
@end deffn

@geindex EOVERFLOW (於 errno 模組中)
@anchor{library/errno errno EOVERFLOW}@anchor{313a}
@deffn {資料} errno.EOVERFLOW

Value too large for defined data type
@end deffn

@geindex ENOTUNIQ (於 errno 模組中)
@anchor{library/errno errno ENOTUNIQ}@anchor{313b}
@deffn {資料} errno.ENOTUNIQ

Name not unique on network
@end deffn

@geindex EBADFD (於 errno 模組中)
@anchor{library/errno errno EBADFD}@anchor{313c}
@deffn {資料} errno.EBADFD

File descriptor in bad state
@end deffn

@geindex EREMCHG (於 errno 模組中)
@anchor{library/errno errno EREMCHG}@anchor{313d}
@deffn {資料} errno.EREMCHG

Remote address changed
@end deffn

@geindex ELIBACC (於 errno 模組中)
@anchor{library/errno errno ELIBACC}@anchor{313e}
@deffn {資料} errno.ELIBACC

Can not access a needed shared library
@end deffn

@geindex ELIBBAD (於 errno 模組中)
@anchor{library/errno errno ELIBBAD}@anchor{313f}
@deffn {資料} errno.ELIBBAD

Accessing a corrupted shared library
@end deffn

@geindex ELIBSCN (於 errno 模組中)
@anchor{library/errno errno ELIBSCN}@anchor{3140}
@deffn {資料} errno.ELIBSCN

.lib section in a.out corrupted
@end deffn

@geindex ELIBMAX (於 errno 模組中)
@anchor{library/errno errno ELIBMAX}@anchor{3141}
@deffn {資料} errno.ELIBMAX

Attempting to link in too many shared libraries
@end deffn

@geindex ELIBEXEC (於 errno 模組中)
@anchor{library/errno errno ELIBEXEC}@anchor{3142}
@deffn {資料} errno.ELIBEXEC

Cannot exec a shared library directly
@end deffn

@geindex EILSEQ (於 errno 模組中)
@anchor{library/errno errno EILSEQ}@anchor{3143}
@deffn {資料} errno.EILSEQ

Illegal byte sequence
@end deffn

@geindex ERESTART (於 errno 模組中)
@anchor{library/errno errno ERESTART}@anchor{3144}
@deffn {資料} errno.ERESTART

Interrupted system call should be restarted
@end deffn

@geindex ESTRPIPE (於 errno 模組中)
@anchor{library/errno errno ESTRPIPE}@anchor{3145}
@deffn {資料} errno.ESTRPIPE

Streams pipe error
@end deffn

@geindex EUSERS (於 errno 模組中)
@anchor{library/errno errno EUSERS}@anchor{3146}
@deffn {資料} errno.EUSERS

使用者數量過多
@end deffn

@geindex ENOTSOCK (於 errno 模組中)
@anchor{library/errno errno ENOTSOCK}@anchor{3147}
@deffn {資料} errno.ENOTSOCK

Socket operation on non-socket
@end deffn

@geindex EDESTADDRREQ (於 errno 模組中)
@anchor{library/errno errno EDESTADDRREQ}@anchor{3148}
@deffn {資料} errno.EDESTADDRREQ

Destination address required
@end deffn

@geindex EMSGSIZE (於 errno 模組中)
@anchor{library/errno errno EMSGSIZE}@anchor{3149}
@deffn {資料} errno.EMSGSIZE

Message too long
@end deffn

@geindex EPROTOTYPE (於 errno 模組中)
@anchor{library/errno errno EPROTOTYPE}@anchor{314a}
@deffn {資料} errno.EPROTOTYPE

Protocol wrong type for socket
@end deffn

@geindex ENOPROTOOPT (於 errno 模組中)
@anchor{library/errno errno ENOPROTOOPT}@anchor{314b}
@deffn {資料} errno.ENOPROTOOPT

Protocol not available
@end deffn

@geindex EPROTONOSUPPORT (於 errno 模組中)
@anchor{library/errno errno EPROTONOSUPPORT}@anchor{314c}
@deffn {資料} errno.EPROTONOSUPPORT

Protocol not supported
@end deffn

@geindex ESOCKTNOSUPPORT (於 errno 模組中)
@anchor{library/errno errno ESOCKTNOSUPPORT}@anchor{314d}
@deffn {資料} errno.ESOCKTNOSUPPORT

Socket type not supported
@end deffn

@geindex EOPNOTSUPP (於 errno 模組中)
@anchor{library/errno errno EOPNOTSUPP}@anchor{314e}
@deffn {資料} errno.EOPNOTSUPP

Operation not supported on transport endpoint
@end deffn

@geindex ENOTSUP (於 errno 模組中)
@anchor{library/errno errno ENOTSUP}@anchor{314f}
@deffn {資料} errno.ENOTSUP

Operation not supported


在 3.2 版被加入.

@end deffn

@geindex EPFNOSUPPORT (於 errno 模組中)
@anchor{library/errno errno EPFNOSUPPORT}@anchor{3150}
@deffn {資料} errno.EPFNOSUPPORT

Protocol family not supported
@end deffn

@geindex EAFNOSUPPORT (於 errno 模組中)
@anchor{library/errno errno EAFNOSUPPORT}@anchor{3151}
@deffn {資料} errno.EAFNOSUPPORT

Address family not supported by protocol
@end deffn

@geindex EADDRINUSE (於 errno 模組中)
@anchor{library/errno errno EADDRINUSE}@anchor{3152}
@deffn {資料} errno.EADDRINUSE

Address already in use
@end deffn

@geindex EADDRNOTAVAIL (於 errno 模組中)
@anchor{library/errno errno EADDRNOTAVAIL}@anchor{3153}
@deffn {資料} errno.EADDRNOTAVAIL

Cannot assign requested address
@end deffn

@geindex ENETDOWN (於 errno 模組中)
@anchor{library/errno errno ENETDOWN}@anchor{3154}
@deffn {資料} errno.ENETDOWN

Network is down
@end deffn

@geindex ENETUNREACH (於 errno 模組中)
@anchor{library/errno errno ENETUNREACH}@anchor{1cb2}
@deffn {資料} errno.ENETUNREACH

Network is unreachable
@end deffn

@geindex ENETRESET (於 errno 模組中)
@anchor{library/errno errno ENETRESET}@anchor{3155}
@deffn {資料} errno.ENETRESET

Network dropped connection because of reset
@end deffn

@geindex ECONNABORTED (於 errno 模組中)
@anchor{library/errno errno ECONNABORTED}@anchor{25b0}
@deffn {資料} errno.ECONNABORTED

Software caused connection abort. This error is mapped to the
exception @ref{1258,,ConnectionAbortedError}.
@end deffn

@geindex ECONNRESET (於 errno 模組中)
@anchor{library/errno errno ECONNRESET}@anchor{25b2}
@deffn {資料} errno.ECONNRESET

Connection reset by peer. This error is mapped to the exception
@ref{125a,,ConnectionResetError}.
@end deffn

@geindex ENOBUFS (於 errno 模組中)
@anchor{library/errno errno ENOBUFS}@anchor{1aa0}
@deffn {資料} errno.ENOBUFS

No buffer space available
@end deffn

@geindex EISCONN (於 errno 模組中)
@anchor{library/errno errno EISCONN}@anchor{3156}
@deffn {資料} errno.EISCONN

Transport endpoint is already connected
@end deffn

@geindex ENOTCONN (於 errno 模組中)
@anchor{library/errno errno ENOTCONN}@anchor{3157}
@deffn {資料} errno.ENOTCONN

Transport endpoint is not connected
@end deffn

@geindex ESHUTDOWN (於 errno 模組中)
@anchor{library/errno errno ESHUTDOWN}@anchor{25af}
@deffn {資料} errno.ESHUTDOWN

Cannot send after transport endpoint shutdown. This error is mapped
to the exception @ref{1257,,BrokenPipeError}.
@end deffn

@geindex ETOOMANYREFS (於 errno 模組中)
@anchor{library/errno errno ETOOMANYREFS}@anchor{3158}
@deffn {資料} errno.ETOOMANYREFS

Too many references: cannot splice
@end deffn

@geindex ETIMEDOUT (於 errno 模組中)
@anchor{library/errno errno ETIMEDOUT}@anchor{25b9}
@deffn {資料} errno.ETIMEDOUT

Connection timed out. This error is mapped to the exception
@ref{a2f,,TimeoutError}.
@end deffn

@geindex ECONNREFUSED (於 errno 模組中)
@anchor{library/errno errno ECONNREFUSED}@anchor{25b1}
@deffn {資料} errno.ECONNREFUSED

Connection refused. This error is mapped to the exception
@ref{1259,,ConnectionRefusedError}.
@end deffn

@geindex EHOSTDOWN (於 errno 模組中)
@anchor{library/errno errno EHOSTDOWN}@anchor{3159}
@deffn {資料} errno.EHOSTDOWN

Host is down
@end deffn

@geindex EHOSTUNREACH (於 errno 模組中)
@anchor{library/errno errno EHOSTUNREACH}@anchor{315a}
@deffn {資料} errno.EHOSTUNREACH

No route to host
@end deffn

@geindex EHWPOISON (於 errno 模組中)
@anchor{library/errno errno EHWPOISON}@anchor{20b}
@deffn {資料} errno.EHWPOISON

Memory page has hardware error.


在 3.14 版被加入.

@end deffn

@geindex EALREADY (於 errno 模組中)
@anchor{library/errno errno EALREADY}@anchor{25a9}
@deffn {資料} errno.EALREADY

Operation already in progress. This error is mapped to the
exception @ref{235,,BlockingIOError}.
@end deffn

@geindex EINPROGRESS (於 errno 模組中)
@anchor{library/errno errno EINPROGRESS}@anchor{25ab}
@deffn {資料} errno.EINPROGRESS

Operation now in progress. This error is mapped to the exception
@ref{235,,BlockingIOError}.
@end deffn

@geindex ESTALE (於 errno 模組中)
@anchor{library/errno errno ESTALE}@anchor{315b}
@deffn {資料} errno.ESTALE

Stale NFS file handle
@end deffn

@geindex EUCLEAN (於 errno 模組中)
@anchor{library/errno errno EUCLEAN}@anchor{315c}
@deffn {資料} errno.EUCLEAN

Structure needs cleaning
@end deffn

@geindex ENOTNAM (於 errno 模組中)
@anchor{library/errno errno ENOTNAM}@anchor{315d}
@deffn {資料} errno.ENOTNAM

Not a XENIX named type file
@end deffn

@geindex ENAVAIL (於 errno 模組中)
@anchor{library/errno errno ENAVAIL}@anchor{315e}
@deffn {資料} errno.ENAVAIL

No XENIX semaphores available
@end deffn

@geindex EISNAM (於 errno 模組中)
@anchor{library/errno errno EISNAM}@anchor{315f}
@deffn {資料} errno.EISNAM

Is a named type file
@end deffn

@geindex EREMOTEIO (於 errno 模組中)
@anchor{library/errno errno EREMOTEIO}@anchor{3160}
@deffn {資料} errno.EREMOTEIO

Remote I/O error
@end deffn

@geindex EDQUOT (於 errno 模組中)
@anchor{library/errno errno EDQUOT}@anchor{3161}
@deffn {資料} errno.EDQUOT

Quota exceeded
@end deffn

@geindex EQFULL (於 errno 模組中)
@anchor{library/errno errno EQFULL}@anchor{3162}
@deffn {資料} errno.EQFULL

Interface output queue is full


在 3.11 版被加入.

@end deffn

@geindex ENOMEDIUM (於 errno 模組中)
@anchor{library/errno errno ENOMEDIUM}@anchor{3163}
@deffn {資料} errno.ENOMEDIUM

No medium found
@end deffn

@geindex EMEDIUMTYPE (於 errno 模組中)
@anchor{library/errno errno EMEDIUMTYPE}@anchor{3164}
@deffn {資料} errno.EMEDIUMTYPE

Wrong medium type
@end deffn

@geindex ENOKEY (於 errno 模組中)
@anchor{library/errno errno ENOKEY}@anchor{3165}
@deffn {資料} errno.ENOKEY

Required key not available
@end deffn

@geindex EKEYEXPIRED (於 errno 模組中)
@anchor{library/errno errno EKEYEXPIRED}@anchor{3166}
@deffn {資料} errno.EKEYEXPIRED

Key has expired
@end deffn

@geindex EKEYREVOKED (於 errno 模組中)
@anchor{library/errno errno EKEYREVOKED}@anchor{3167}
@deffn {資料} errno.EKEYREVOKED

Key has been revoked
@end deffn

@geindex EKEYREJECTED (於 errno 模組中)
@anchor{library/errno errno EKEYREJECTED}@anchor{3168}
@deffn {資料} errno.EKEYREJECTED

Key was rejected by service
@end deffn

@geindex ERFKILL (於 errno 模組中)
@anchor{library/errno errno ERFKILL}@anchor{3169}
@deffn {資料} errno.ERFKILL

Operation not possible due to RF-kill
@end deffn

@geindex ELOCKUNMAPPED (於 errno 模組中)
@anchor{library/errno errno ELOCKUNMAPPED}@anchor{316a}
@deffn {資料} errno.ELOCKUNMAPPED

Locked lock was unmapped
@end deffn

@geindex ENOTACTIVE (於 errno 模組中)
@anchor{library/errno errno ENOTACTIVE}@anchor{316b}
@deffn {資料} errno.ENOTACTIVE

Facility is not active
@end deffn

@geindex EAUTH (於 errno 模組中)
@anchor{library/errno errno EAUTH}@anchor{316c}
@deffn {資料} errno.EAUTH

Authentication error


在 3.2 版被加入.

@end deffn

@geindex EBADARCH (於 errno 模組中)
@anchor{library/errno errno EBADARCH}@anchor{316d}
@deffn {資料} errno.EBADARCH

Bad CPU type in executable


在 3.2 版被加入.

@end deffn

@geindex EBADEXEC (於 errno 模組中)
@anchor{library/errno errno EBADEXEC}@anchor{316e}
@deffn {資料} errno.EBADEXEC

Bad executable (or shared library)


在 3.2 版被加入.

@end deffn

@geindex EBADMACHO (於 errno 模組中)
@anchor{library/errno errno EBADMACHO}@anchor{316f}
@deffn {資料} errno.EBADMACHO

Malformed Mach-o file


在 3.2 版被加入.

@end deffn

@geindex EDEVERR (於 errno 模組中)
@anchor{library/errno errno EDEVERR}@anchor{3170}
@deffn {資料} errno.EDEVERR

裝置錯誤


在 3.2 版被加入.

@end deffn

@geindex EFTYPE (於 errno 模組中)
@anchor{library/errno errno EFTYPE}@anchor{3171}
@deffn {資料} errno.EFTYPE

不適當的檔案類型或格式


在 3.2 版被加入.

@end deffn

@geindex ENEEDAUTH (於 errno 模組中)
@anchor{library/errno errno ENEEDAUTH}@anchor{3172}
@deffn {資料} errno.ENEEDAUTH

需要驗證器


在 3.2 版被加入.

@end deffn

@geindex ENOATTR (於 errno 模組中)
@anchor{library/errno errno ENOATTR}@anchor{3173}
@deffn {資料} errno.ENOATTR

找不到屬性


在 3.2 版被加入.

@end deffn

@geindex ENOPOLICY (於 errno 模組中)
@anchor{library/errno errno ENOPOLICY}@anchor{3174}
@deffn {資料} errno.ENOPOLICY

Policy not found


在 3.2 版被加入.

@end deffn

@geindex EPROCLIM (於 errno 模組中)
@anchor{library/errno errno EPROCLIM}@anchor{3175}
@deffn {資料} errno.EPROCLIM

行程數量過多


在 3.2 版被加入.

@end deffn

@geindex EPROCUNAVAIL (於 errno 模組中)
@anchor{library/errno errno EPROCUNAVAIL}@anchor{3176}
@deffn {資料} errno.EPROCUNAVAIL

Bad procedure for program


在 3.2 版被加入.

@end deffn

@geindex EPROGMISMATCH (於 errno 模組中)
@anchor{library/errno errno EPROGMISMATCH}@anchor{3177}
@deffn {資料} errno.EPROGMISMATCH

Program version wrong


在 3.2 版被加入.

@end deffn

@geindex EPROGUNAVAIL (於 errno 模組中)
@anchor{library/errno errno EPROGUNAVAIL}@anchor{3178}
@deffn {資料} errno.EPROGUNAVAIL

RPC prog. not avail


在 3.2 版被加入.

@end deffn

@geindex EPWROFF (於 errno 模組中)
@anchor{library/errno errno EPWROFF}@anchor{3179}
@deffn {資料} errno.EPWROFF

裝置電源關閉


在 3.2 版被加入.

@end deffn

@geindex EBADRPC (於 errno 模組中)
@anchor{library/errno errno EBADRPC}@anchor{317a}
@deffn {資料} errno.EBADRPC

RPC 結構不正確


在 3.2 版被加入.

@end deffn

@geindex ERPCMISMATCH (於 errno 模組中)
@anchor{library/errno errno ERPCMISMATCH}@anchor{317b}
@deffn {資料} errno.ERPCMISMATCH

RPC 版本錯誤


在 3.2 版被加入.

@end deffn

@geindex ESHLIBVERS (於 errno 模組中)
@anchor{library/errno errno ESHLIBVERS}@anchor{317c}
@deffn {資料} errno.ESHLIBVERS

共享函式庫版本不匹配


在 3.2 版被加入.

@end deffn

@geindex ENOTCAPABLE (於 errno 模組中)
@anchor{library/errno errno ENOTCAPABLE}@anchor{1a7a}
@deffn {資料} errno.ENOTCAPABLE

Capabilities insufficient. This error is mapped to the exception
@ref{f39,,PermissionError}.

@ref{2006,,可用性}: WASI, FreeBSD


在 3.11.1 版被加入.

@end deffn

@geindex ECANCELED (於 errno 模組中)
@anchor{library/errno errno ECANCELED}@anchor{1758}
@deffn {資料} errno.ECANCELED

操作已取消


在 3.2 版被加入.

@end deffn

@geindex EOWNERDEAD (於 errno 模組中)
@anchor{library/errno errno EOWNERDEAD}@anchor{317d}
@deffn {資料} errno.EOWNERDEAD

擁有者過世


在 3.2 版被加入.

@end deffn

@geindex ENOTRECOVERABLE (於 errno 模組中)
@anchor{library/errno errno ENOTRECOVERABLE}@anchor{317e}
@deffn {資料} errno.ENOTRECOVERABLE

狀態無法恢復


在 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 --- 用於 Python 的外部函式庫,,errno --- 標準 errno 系統符號,通用作業系統服務
@anchor{library/ctypes doc}@anchor{317f}@anchor{library/ctypes ctypes-a-foreign-function-library-for-python}@anchor{3180}@anchor{library/ctypes module-ctypes}@anchor{2e}@anchor{library/ctypes translation-repo}@anchor{3181}
@subsection @code{ctypes} --- 用於 Python 的外部函式庫


@geindex module; ctypes

`原始碼：'Lib/ctypes@footnote{https://github.com/python/cpython/tree/3.14/Lib/ctypes}


__________________________________________________________________


@ref{2e,,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.

@menu
* ctypes 教學:: 
* ctypes reference:: 

@end menu

@node ctypes 教學,ctypes reference,,ctypes --- 用於 Python 的外部函式庫
@anchor{library/ctypes ctypes-ctypes-tutorial}@anchor{3182}@anchor{library/ctypes ctypes-tutorial}@anchor{3183}
@subsubsection ctypes 教學


Note: The code samples in this tutorial use @ref{3e,,doctest} to make sure that
they actually work.  Since some code samples behave differently under Linux,
Windows, or macOS, they contain doctest directives in comments.

Note: Some code samples reference the ctypes @ref{3184,,c_int} type.  On platforms
where @code{sizeof(long) == sizeof(int)} it is an alias to @ref{3185,,c_long}.
So, you should not be confused if @ref{3185,,c_long} is printed if you would expect
@ref{3184,,c_int} --- they are actually the same type.

@menu
* Loading dynamic link libraries:: 
* Accessing functions from loaded dlls:: 
* 呼叫函式:: 
* 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:: 
* 指標:: 
* Thread safety without the GIL:: 
* Type conversions:: 
* Incomplete Types:: 
* 回呼函式:: 
* Accessing values exported from dlls:: 
* Surprises:: 
* Variable-sized data types:: 

@end menu

@node Loading dynamic link libraries,Accessing functions from loaded dlls,,ctypes 教學
@anchor{library/ctypes ctypes-loading-dynamic-link-libraries}@anchor{3186}@anchor{library/ctypes loading-dynamic-link-libraries}@anchor{3187}
@subsubsection Loading dynamic link libraries


@ref{2e,,ctypes} exports the `cdll', and on Windows `windll' and `oledll'
objects, for loading dynamic link libraries.

You load libraries by accessing them as attributes of these objects. `cdll'
loads libraries which export functions using the standard @code{cdecl} calling
convention, while `windll' libraries call functions using the @code{stdcall}
calling convention. `oledll' also uses the @code{stdcall} calling convention, and
assumes the functions return a Windows @code{HRESULT} error code. The error
code is used to automatically raise an @ref{2c0,,OSError} exception when the
function call fails.


在 3.3 版的變更: Windows errors used to raise @ref{1250,,WindowsError}, which is now an alias
of @ref{2c0,,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

On Linux, it is required to specify the filename `including' the extension to
load a library, so attribute access can not be used to load libraries. Either the
@ref{3188,,LoadLibrary()} method of the dll loaders should be used,
or you should load the library by creating an instance of CDLL by calling
the constructor:

@example
>>> cdll.LoadLibrary("libc.so.6")
<CDLL 'libc.so.6', handle ... at ...>
>>> libc = CDLL("libc.so.6")
>>> libc
<CDLL 'libc.so.6', handle ... at ...>
>>>
@end example

@c XXX Add section for macOS.

@node Accessing functions from loaded dlls,呼叫函式,Loading dynamic link libraries,ctypes 教學
@anchor{library/ctypes accessing-functions-from-loaded-dlls}@anchor{3189}@anchor{library/ctypes ctypes-accessing-functions-from-loaded-dlls}@anchor{318a}
@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 版本 */
HMODULE GetModuleHandleA(LPCSTR lpModuleName);
/* UNICODE 版本 */
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{dc5,,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 呼叫函式,Fundamental data types,Accessing functions from loaded dlls,ctypes 教學
@anchor{library/ctypes calling-functions}@anchor{318b}@anchor{library/ctypes ctypes-calling-functions}@anchor{318c}
@subsubsection 呼叫函式


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{2eb,,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, @ref{2e,,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 @ref{2e,,ctypes}, so you
should be careful anyway.  The @ref{5c,,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 @ref{2e,,ctypes} data types.

@node Fundamental data types,Calling functions continued,呼叫函式,ctypes 教學
@anchor{library/ctypes ctypes-fundamental-data-types}@anchor{318d}@anchor{library/ctypes fundamental-data-types}@anchor{318e}
@subsubsection Fundamental data types


@ref{2e,,ctypes} defines a number of primitive C compatible data types:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

ctypes 型別

@tab

C 型別

@tab

Python 型別

@item

@ref{318f,,c_bool}

@tab

_Bool

@tab

bool (1)

@item

@ref{3190,,c_char}

@tab

char

@tab

1-character bytes object

@item

@ref{3191,,c_wchar}

@tab

@code{wchar_t}

@tab

1-character string

@item

@ref{1a2b,,c_byte}

@tab

char

@tab

int

@item

@ref{1a2c,,c_ubyte}

@tab

unsigned char

@tab

int

@item

@ref{3192,,c_short}

@tab

short

@tab

int

@item

@ref{3193,,c_ushort}

@tab

unsigned short

@tab

int

@item

@ref{3184,,c_int}

@tab

int

@tab

int

@item

@ref{3194,,c_int8}

@tab

@code{int8_t}

@tab

int

@item

@ref{3195,,c_int16}

@tab

@code{int16_t}

@tab

int

@item

@ref{3196,,c_int32}

@tab

@code{int32_t}

@tab

int

@item

@ref{3197,,c_int64}

@tab

@code{int64_t}

@tab

int

@item

@ref{3198,,c_uint}

@tab

unsigned int

@tab

int

@item

@ref{3199,,c_uint8}

@tab

@code{uint8_t}

@tab

int

@item

@ref{319a,,c_uint16}

@tab

@code{uint16_t}

@tab

int

@item

@ref{319b,,c_uint32}

@tab

@code{uint32_t}

@tab

int

@item

@ref{319c,,c_uint64}

@tab

@code{uint64_t}

@tab

int

@item

@ref{3185,,c_long}

@tab

long

@tab

int

@item

@ref{319d,,c_ulong}

@tab

unsigned long

@tab

int

@item

@ref{319e,,c_longlong}

@tab

__int64 或 long long

@tab

int

@item

@ref{319f,,c_ulonglong}

@tab

unsigned __int64 或 unsigned long long

@tab

int

@item

@ref{31a0,,c_size_t}

@tab

@code{size_t}

@tab

int

@item

@ref{143d,,c_ssize_t}

@tab

@code{ssize_t} 或 @ref{c4c,,Py_ssize_t}

@tab

int

@item

@ref{1a92,,c_time_t}

@tab

@code{time_t}

@tab

int

@item

@ref{31a1,,c_float}

@tab

float

@tab

float

@item

@ref{1bb0,,c_double}

@tab

double

@tab

float

@item

@ref{1bb1,,c_longdouble}

@tab

long double

@tab

float

@item

@ref{19a8,,c_char_p}

@tab

char* (NUL terminated)

@tab

位元組物件或 @code{None}

@item

@ref{19a9,,c_wchar_p}

@tab

wchar_t* (NUL terminated)

@tab

字串或 @code{None}

@item

@ref{19aa,,c_void_p}

@tab

void*

@tab

int or @code{None}

@end multitable



@enumerate 

@item 
The constructor accepts any object with a truth value.
@end enumerate

Additionally, if IEC 60559 compatible complex arithmetic (Annex G) is supported
in both C and @code{libffi}, the following complex types are available:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxx} 
@headitem

ctypes 型別

@tab

C 型別

@tab

Python 型別

@item

@ref{1ed,,c_float_complex}

@tab

float complex

@tab

complex

@item

@ref{1ee,,c_double_complex}

@tab

double complex

@tab

complex

@item

@ref{1ef,,c_longdouble_complex}

@tab

long double complex

@tab

complex

@end multitable


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

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{19a8,,c_char_p},
@ref{19a9,,c_wchar_p}, and @ref{19aa,,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)              # 記憶體位置已改變
c_wchar_p(139966783348904)
>>> print(c_s.value)
Hi, there
>>> print(s)                # 第一個物件未改變
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{31a2,,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{31a2,,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{1c7d,,create_unicode_buffer()} function.

@node Calling functions continued,Calling variadic functions,Fundamental data types,ctypes 教學
@anchor{library/ctypes calling-functions-continued}@anchor{31a3}@anchor{library/ctypes ctypes-calling-functions-continued}@anchor{31a4}
@subsubsection Calling functions, continued


Note that printf prints to the real standard output channel, `not' to
@ref{cc4,,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 @ref{2e,,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 教學
@anchor{library/ctypes calling-variadic-functions}@anchor{31a5}@anchor{library/ctypes ctypes-calling-variadic-functions}@anchor{31a6}
@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{1757,,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{1757,,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 教學
@anchor{library/ctypes calling-functions-with-your-own-custom-data-types}@anchor{31a7}@anchor{library/ctypes ctypes-calling-functions-with-own-custom-data-types}@anchor{31a8}
@subsubsection Calling functions with your own custom data types


You can also customize @ref{2e,,ctypes} argument conversion to allow instances of
your own classes be used as function arguments. @ref{2e,,ctypes} looks for an
@code{_as_parameter_} attribute and uses this as the function argument. The
attribute must be an integer, string, bytes, a @ref{2e,,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{4ae,,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 教學
@anchor{library/ctypes ctypes-specifying-required-argument-types}@anchor{31a9}@anchor{library/ctypes specifying-the-required-argument-types-function-prototypes}@anchor{31aa}
@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{1757,,argtypes} attribute.

@ref{1757,,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{31ab,,from_param()} class method for them to be able to use them
in the @ref{1757,,argtypes} sequence. The @ref{31ab,,from_param()} class method receives
the Python object passed to the function call, it should do a typecheck or
whatever is needed to make sure this object is acceptable, and then return the
object itself, its @code{_as_parameter_} attribute, or whatever you want to
pass as the C function argument in this case. Again, the result should be an
integer, string, bytes, a @ref{2e,,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 教學
@anchor{library/ctypes ctypes-return-types}@anchor{31ac}@anchor{library/ctypes return-types}@anchor{31ad}
@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{31ae,,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{1757,,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{21ef,,ord("x")} calls above, you can set the
@ref{1757,,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{31ae,,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{31af,,GetLastError()} to retrieve it.

Please note that a much more powerful error checking mechanism is available
through the @ref{31b0,,errcheck} attribute;
see the reference manual for details.

@node Passing pointers or passing parameters by reference,Structures and unions,Return types,ctypes 教學
@anchor{library/ctypes ctypes-passing-pointers}@anchor{31b1}@anchor{library/ctypes passing-pointers-or-passing-parameters-by-reference}@anchor{31b2}
@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'.

@ref{2e,,ctypes} exports the @ref{31b3,,byref()} function which is used to pass parameters
by reference.  The same effect can be achieved with the @ref{19a7,,pointer()} function,
although @ref{19a7,,pointer()} does a lot more work since it constructs a real pointer
object, so it is faster to use @ref{31b3,,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 教學
@anchor{library/ctypes ctypes-structures-unions}@anchor{31b4}@anchor{library/ctypes structures-and-unions}@anchor{31b5}
@subsubsection Structures and unions


Structures and unions must derive from the @ref{1e5,,Structure} and @ref{1e6,,Union}
base classes which are defined in the @ref{2e,,ctypes} module. Each subclass must
define a @ref{189c,,_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 @ref{2e,,ctypes} type like @ref{3184,,c_int}, or any other
derived @ref{2e,,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{17fc,,descriptor}s can be retrieved from the `class', they are useful
for debugging because they can provide useful information.
See @ref{1e8,,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{31b6}
@cartouche
@quotation 警告 
@ref{2e,,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 教學
@anchor{library/ctypes structure-union-layout-alignment-and-byte-order}@anchor{31b7}
@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{1e7,,_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{316,,_pack_}
and/or @ref{4e3,,_align_}, respectively.
See the attribute documentation for details.

@ref{2e,,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{31b8,,BigEndianStructure}, @ref{31b9,,LittleEndianStructure},
@ref{1add,,BigEndianUnion}, and @ref{1ade,,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 教學
@anchor{library/ctypes bit-fields-in-structures-and-unions}@anchor{31ba}@anchor{library/ctypes ctypes-bit-fields-in-structures-unions}@anchor{1e4}
@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{189c,,_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{1e7,,_layout_} attribute for details on the default
behavior and how to change it.

@node Arrays,指標,Bit fields in structures and unions,ctypes 教學
@anchor{library/ctypes arrays}@anchor{31bb}@anchor{library/ctypes ctypes-arrays}@anchor{31bc}
@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 指標,Thread safety without the GIL,Arrays,ctypes 教學
@anchor{library/ctypes ctypes-pointers}@anchor{31bd}@anchor{library/ctypes pointers}@anchor{31be}
@subsubsection 指標


Pointer instances are created by calling the @ref{19a7,,pointer()} function on a
@ref{2e,,ctypes} type:

@example
>>> from ctypes import *
>>> i = c_int(42)
>>> pi = pointer(i)
>>>
@end example

Pointer instances have a @ref{31bf,,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 @ref{2e,,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{3184,,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{19a7,,pointer()} function does more than simply create
pointer instances, it has to create pointer `types' first. This is done with the
@ref{1f1,,POINTER()} function, which accepts any @ref{2e,,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

@ref{2e,,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,指標,ctypes 教學
@anchor{library/ctypes ctypes-thread-safety}@anchor{31c0}@anchor{library/ctypes thread-safety-without-the-gil}@anchor{31c1}
@subsubsection Thread safety without the GIL


From Python 3.13 onward, the @ref{164,,GIL} can be disabled on @ref{1f4,,free threaded} builds.
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{1943,,threading.Lock}
to synchronize access to memory:

@quotation

@example
>>> import threading
>>> lock = threading.Lock()
>>> # 執行緒 1
>>> with lock:
...    pointer_a.contents = 24
>>> # 執行緒 2
>>> with lock:
...    pointer_b.contents = 42
@end example
@end quotation

@node Type conversions,Incomplete Types,Thread safety without the GIL,ctypes 教學
@anchor{library/ctypes ctypes-type-conversions}@anchor{31c2}@anchor{library/ctypes type-conversions}@anchor{31c3}
@subsubsection Type conversions


Usually, ctypes does strict type checking.  This means, if you have
@code{POINTER(c_int)} in the @ref{1757,,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{1757,,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{31b3,,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.  @ref{2e,,ctypes} provides a @ref{31c4,,cast()} function which can be
used in the same way.  The @code{Bar} structure defined above accepts
@code{POINTER(c_int)} pointers or @ref{3184,,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{31c4,,cast()} function is handy.

The @ref{31c4,,cast()} function can be used to cast a ctypes instance into a pointer
to a different ctypes data type.  @ref{31c4,,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{31c4,,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,回呼函式,Type conversions,ctypes 教學
@anchor{library/ctypes ctypes-incomplete-types}@anchor{317}@anchor{library/ctypes incomplete-types}@anchor{31c5}
@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 @ref{2e,,ctypes}, we can define the @code{cell} class and set the
@ref{189c,,_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 回呼函式,Accessing values exported from dlls,Incomplete Types,ctypes 教學
@anchor{library/ctypes callback-functions}@anchor{31c6}@anchor{library/ctypes ctypes-callback-functions}@anchor{31c7}
@subsubsection 回呼函式


@ref{2e,,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{31c8,,CFUNCTYPE()} factory function creates types for callback functions
using the @code{cdecl} calling convention. On Windows, the @ref{31c9,,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

結果為：

@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{31c8,,CFUNCTYPE()} objects as long as they
are used from C code. @ref{2e,,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{17df,,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,回呼函式,ctypes 教學
@anchor{library/ctypes accessing-values-exported-from-dlls}@anchor{31ca}@anchor{library/ctypes ctypes-accessing-values-exported-from-dlls}@anchor{31cb}
@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{37f,,Py_Version}, Python
runtime version number encoded in a single constant integer.

@ref{2e,,ctypes} can access values like this with the @ref{31cc,,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{31cd,,PyImport_FrozenModules} pointer exported by Python.

Quoting the docs for that value:

@quotation

This pointer is initialized to point to an array of @ref{971,,_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 @ref{2e,,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)),  # 函式指標
...                ]
...
>>>
@end example

We have defined the @ref{971,,_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 教學
@anchor{library/ctypes ctypes-surprises}@anchor{31ce}@anchor{library/ctypes surprises}@anchor{31cf}
@subsubsection Surprises


There are some edges in @ref{2e,,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{19a8,,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{17fc,,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 教學
@anchor{library/ctypes ctypes-variable-sized-data-types}@anchor{31d0}@anchor{library/ctypes variable-sized-data-types}@anchor{31d1}
@subsubsection Variable-sized data types


@ref{2e,,ctypes} provides some support for variable-sized arrays and structures.

The @ref{31d2,,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{2eb,,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 @ref{2e,,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 教學,ctypes --- 用於 Python 的外部函式庫
@anchor{library/ctypes ctypes-ctypes-reference}@anchor{31d3}@anchor{library/ctypes ctypes-reference}@anchor{31d4}
@subsubsection ctypes reference


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

@end menu

@node Finding shared libraries,Listing loaded shared libraries,,ctypes reference
@anchor{library/ctypes ctypes-finding-shared-libraries}@anchor{31d5}@anchor{library/ctypes finding-shared-libraries}@anchor{31d6}
@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 purpose of the @ref{f40,,find_library()} function is to locate a library in a way
similar to what the compiler or runtime loader does (on platforms with several
versions of a shared library the most recent should be loaded), while the ctypes
library loaders act like when a program is run, and call the runtime loader
directly.

The @code{ctypes.util} module provides a function which can help to determine
the library to load.


@deffn {資料} ctypes.util.find_library (name)

Try to find a library and return a pathname.  `name' is the library name without
any prefix like `lib', suffix like @code{.so}, @code{.dylib} or version number (this
is the form used for the posix linker option @code{-l}).  If no library can
be found, returns @code{None}.
@end deffn

The exact functionality is system dependent.

On Linux, @ref{f40,,find_library()} tries to run external programs
(@code{/sbin/ldconfig}, @code{gcc}, @code{objdump} and @code{ld}) to find the library file.
It returns the filename of the library file.


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


以下是一些範例：

@example
>>> from ctypes.util import find_library
>>> find_library("m")
'libm.so.6'
>>> find_library("c")
'libc.so.6'
>>> find_library("bz2")
'libbz2.so.1.0'
>>>
@end example

On macOS and Android, @ref{f40,,find_library()} uses the system's
standard naming schemes and paths to locate the library, and returns a full
pathname if successful:

@example
>>> from ctypes.util import find_library
>>> find_library("c")
'/usr/lib/libc.dylib'
>>> find_library("m")
'/usr/lib/libm.dylib'
>>> find_library("bz2")
'/usr/lib/libbz2.dylib'
>>> find_library("AGL")
'/System/Library/Frameworks/AGL.framework/AGL'
>>>
@end example

On Windows, @ref{f40,,find_library()} searches along the system search path, and
returns the full pathname, but since there is no predefined naming scheme a call
like @code{find_library("c")} will fail and return @code{None}.

If wrapping a shared library with @ref{2e,,ctypes}, it `may' be better to determine
the shared library name at development time, and hardcode that into the wrapper
module instead of using @ref{f40,,find_library()} to locate the library at runtime.

@node Listing loaded shared libraries,Loading shared libraries,Finding shared libraries,ctypes reference
@anchor{library/ctypes ctypes-listing-loaded-shared-libraries}@anchor{31d7}@anchor{library/ctypes listing-loaded-shared-libraries}@anchor{31d8}
@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{1f0,,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 Loading shared libraries,Foreign functions,Listing loaded shared libraries,ctypes reference
@anchor{library/ctypes ctypes-loading-shared-libraries}@anchor{31d9}@anchor{library/ctypes loading-shared-libraries}@anchor{31da}
@subsubsection Loading shared libraries


There are several ways to load shared libraries into the Python process.  One
way is to instantiate one of the following classes:

@geindex CDLL (ctypes 中的類別)
@anchor{library/ctypes ctypes CDLL}@anchor{bd3}
@deffn {類別} ctypes.CDLL (name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False, winmode=None)

Instances of this class represent loaded shared libraries. Functions in these
libraries use the standard C calling convention, and are assumed to return
int.

On Windows creating a @ref{bd3,,CDLL} instance may fail even if the DLL name
exists. When a dependent DLL of the loaded DLL is not found, a
@ref{2c0,,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.


在 3.12 版的變更: The `name' parameter can now be a @ref{59b,,path-like object}.

@end deffn


@subsubheading 也參考


Microsoft DUMPBIN tool@footnote{https://docs.microsoft.com/cpp/build/reference/dependents}
-- A tool to find DLL dependents.


@geindex OleDLL (ctypes 中的類別)
@anchor{library/ctypes ctypes OleDLL}@anchor{1a2d}
@deffn {類別} ctypes.OleDLL (name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False, winmode=None)

Instances of this class represent loaded shared libraries,
functions in these libraries use the @code{stdcall} calling convention, and are
assumed to return the windows specific @ref{31db,,HRESULT} code.  @ref{31db,,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{2c0,,OSError} is automatically raised.

@ref{2006,,可用性}: Windows


在 3.3 版的變更: @ref{1250,,WindowsError} used to be raised,
which is now an alias of @ref{2c0,,OSError}.



在 3.12 版的變更: The `name' parameter can now be a @ref{59b,,path-like object}.

@end deffn

@geindex WinDLL (ctypes 中的類別)
@anchor{library/ctypes ctypes WinDLL}@anchor{1a2e}
@deffn {類別} ctypes.WinDLL (name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False, winmode=None)

Instances of this class represent loaded shared libraries,
functions in these libraries use the @code{stdcall} calling convention, and are
assumed to return int by default.

@ref{2006,,可用性}: Windows


在 3.12 版的變更: The `name' parameter can now be a @ref{59b,,path-like object}.

@end deffn

The Python @ref{46e,,global interpreter lock} is released before calling any
function exported by these libraries, and reacquired afterwards.

@geindex PyDLL (ctypes 中的類別)
@anchor{library/ctypes ctypes PyDLL}@anchor{1a2f}
@deffn {類別} ctypes.PyDLL (name, mode=DEFAULT_MODE, handle=None)

Instances of this class behave like @ref{bd3,,CDLL} instances, except that 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.


在 3.12 版的變更: The `name' parameter can now be a @ref{59b,,path-like object}.

@end deffn

All these classes can be instantiated by calling them with at least one
argument, the pathname of the shared library.  If you have an existing handle to
an already loaded shared library, it can be passed as the @code{handle} named
parameter, otherwise the underlying platform's @code{dlopen()} or
@code{LoadLibrary()} function is used to load the library into
the process, and to get a handle to it.

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{5b,,errno} error number in a safe way.
@ref{2e,,ctypes} maintains a thread-local copy of the system's @ref{5b,,errno}
variable; if you call foreign functions created with @code{use_errno=True} then the
@ref{5b,,errno} value before the function call is swapped with the ctypes private
copy, the same happens immediately after the function call.

The function @ref{31dc,,ctypes.get_errno()} returns the value of the ctypes private
copy, and the function @ref{31dd,,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{31af,,GetLastError()} and
@code{SetLastError()} Windows API functions; @ref{31de,,ctypes.get_last_error()} and
@ref{31df,,ctypes.set_last_error()} are used to request and change the ctypes private
copy of the windows error code.

The `winmode' parameter is used on Windows to specify how the library is loaded
(since `mode' is ignored). It takes any value that is valid for the Win32 API
@code{LoadLibraryEx} flags parameter. When omitted, the default is to use the
flags that result in the most secure DLL load, which avoids issues such as DLL
hijacking. Passing the full path to the DLL is the safest way to ensure the
correct library and dependencies are loaded.


在 3.8 版的變更: 新增 `winmode' 參數。



@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


@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


@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

Instances of these classes 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")  # 於 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.PyDLL 的屬性)
@anchor{library/ctypes ctypes PyDLL _handle}@anchor{31e0}
@deffn {屬性} PyDLL._handle

The system handle used to access the library.
@end deffn

@geindex _name (ctypes.PyDLL 的屬性)
@anchor{library/ctypes ctypes PyDLL _name}@anchor{31e1}
@deffn {屬性} PyDLL._name

The name of the library passed in the constructor.
@end deffn

Shared libraries can also be loaded by using one of the prefabricated objects,
which are instances of the @ref{31e2,,LibraryLoader} class, either by calling the
@ref{3188,,LoadLibrary()} method, or by retrieving the library as
attribute of the loader instance.

@geindex LibraryLoader (ctypes 中的類別)
@anchor{library/ctypes ctypes LibraryLoader}@anchor{31e2}
@deffn {類別} ctypes.LibraryLoader (dlltype)

Class which loads shared libraries.  `dlltype' should be one of the
@ref{bd3,,CDLL}, @ref{1a2f,,PyDLL}, @ref{1a2e,,WinDLL}, or @ref{1a2d,,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{3188}
@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:


@deffn {資料} ctypes.cdll

Creates @ref{bd3,,CDLL} instances.
@end deffn


@deffn {資料} ctypes.windll

Creates @ref{1a2e,,WinDLL} instances.

@ref{2006,,可用性}: Windows
@end deffn


@deffn {資料} ctypes.oledll

Creates @ref{1a2d,,OleDLL} instances.

@ref{2006,,可用性}: Windows
@end deffn


@deffn {資料} ctypes.pydll

Creates @ref{1a2f,,PyDLL} instances.
@end deffn

For accessing the C Python api directly, a ready-to-use Python shared library
object is available:


@deffn {資料} ctypes.pythonapi

An instance of @ref{1a2f,,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


Loading a library through any of these objects raises an
@ref{1b70,,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 Foreign functions,Function prototypes,Loading shared libraries,ctypes reference
@anchor{library/ctypes ctypes-foreign-functions}@anchor{31e3}@anchor{library/ctypes foreign-functions}@anchor{31e4}
@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{1843,,_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{1843}
@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{31ae}
@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{31b0,,errcheck} attribute.
@end deffn

@geindex argtypes (ctypes._CFuncPtr 的屬性)
@anchor{library/ctypes ctypes _CFuncPtr argtypes}@anchor{1757}
@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{31ab,,from_param()} class method of the items in the @ref{1757,,argtypes}
tuple, this method allows adapting the actual argument to an object that
the foreign function accepts.  For example, a @ref{19a8,,c_char_p} item in
the @ref{1757,,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{31ab,,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{31b0}
@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{31e5}@anchor{library/ctypes function-prototypes}@anchor{31e6}
@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{31c7,,回呼函式} for examples.

@geindex CFUNCTYPE() (於 ctypes 模組中)
@anchor{library/ctypes ctypes CFUNCTYPE}@anchor{31c8}
@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{5b,,errno} variable is exchanged with the real @ref{5b,,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{31c9}
@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{2006,,可用性}: Windows
@end deffn

@geindex PYFUNCTYPE() (於 ctypes 模組中)
@anchor{library/ctypes ctypes PYFUNCTYPE}@anchor{31e7}
@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{2c0,,OSError} is raised if the COM method
call fails. If `iid' is specified, a @ref{1e9,,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{2006,,可用性}: 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{1757,,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 @ref{2e,,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 @ref{2e,,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{31b0,,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{31b0,,errcheck} function returns the argument tuple it receives
unchanged, @ref{2e,,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,Function prototypes,ctypes reference
@anchor{library/ctypes ctypes-utility-functions}@anchor{31e8}@anchor{library/ctypes utility-functions}@anchor{31e9}
@subsubsection Utility functions


@geindex addressof() (於 ctypes 模組中)
@anchor{library/ctypes ctypes addressof}@anchor{31ea}
@deffn {函式} ctypes.addressof (obj)

Returns the address of the memory buffer as integer.  `obj' must be an
instance of a ctypes type.

引發一個附帶引數 @code{obj} 的@ref{1b70,,稽核事件} @code{ctypes.addressof}。
@end deffn

@geindex alignment() (於 ctypes 模組中)
@anchor{library/ctypes ctypes alignment}@anchor{31eb}
@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{31b3}
@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{1ea}
@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{2006,,可用性}: Windows


在 3.14 版被加入.

@end deffn

@geindex cast() (於 ctypes 模組中)
@anchor{library/ctypes ctypes cast}@anchor{31c4}
@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{31a2}
@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{3190,,c_char}.

If `size' is given (and not @code{None}), it must be an @ref{19b,,int}.
It specifies the size of the returned array.

If the `init' argument is given, it must be @ref{192,,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.

如果兩個引數皆有提供，`size' 不得小於 @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

舉例來說：

@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

引發一個附帶引數 @code{init} 與 @code{size} 的@ref{1b70,,稽核事件} @code{ctypes.create_string_buffer}。
@end deffn

@geindex create_unicode_buffer() (於 ctypes 模組中)
@anchor{library/ctypes ctypes create_unicode_buffer}@anchor{1c7d}
@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{3191,,c_wchar}.

The function takes the same arguments as @ref{31a2,,create_string_buffer()} except
`init' must be a string and `size' counts @ref{3191,,c_wchar}.

引發一個附帶引數 @code{init} 與 @code{size} 的@ref{1b70,,稽核事件} @code{ctypes.create_unicode_buffer}。
@end deffn

@geindex DllCanUnloadNow() (於 ctypes 模組中)
@anchor{library/ctypes ctypes DllCanUnloadNow}@anchor{31ec}
@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{2006,,可用性}: Windows
@end deffn

@geindex DllGetClassObject() (於 ctypes 模組中)
@anchor{library/ctypes ctypes DllGetClassObject}@anchor{31ed}
@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{2006,,可用性}: Windows
@end deffn

@geindex find_library() (於 ctypes.util 模組中)
@anchor{library/ctypes ctypes util find_library}@anchor{f40}
@deffn {函式} ctypes.util.find_library (name)

Try to find a library and return a pathname.  `name' is the library name
without any prefix like @code{lib}, suffix like @code{.so}, @code{.dylib} or version
number (this is the form used for the posix linker option @code{-l}).  If
no library can be found, returns @code{None}.

The exact functionality is system dependent.
@end deffn

@geindex find_msvcrt() (於 ctypes.util 模組中)
@anchor{library/ctypes ctypes util find_msvcrt}@anchor{31ee}
@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.

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{2006,,可用性}: Windows
@end deffn

@geindex dllist() (於 ctypes.util 模組中)
@anchor{library/ctypes ctypes util dllist}@anchor{1f0}
@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{2c0,,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{2006,,可用性}: Windows, macOS, iOS, glibc, BSD libc, musl


在 3.14 版被加入.

@end deffn

@geindex FormatError() (於 ctypes 模組中)
@anchor{library/ctypes ctypes FormatError}@anchor{31ef}
@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{31af,,GetLastError()}.

@ref{2006,,可用性}: Windows
@end deffn

@geindex GetLastError() (於 ctypes 模組中)
@anchor{library/ctypes ctypes GetLastError}@anchor{31af}
@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{2006,,可用性}: Windows
@end deffn

@geindex get_errno() (於 ctypes 模組中)
@anchor{library/ctypes ctypes get_errno}@anchor{31dc}
@deffn {函式} ctypes.get_errno ()

Returns the current value of the ctypes-private copy of the system
@ref{5b,,errno} variable in the calling thread.

引發一個不附帶引數的@ref{1b70,,稽核事件} @code{ctypes.get_errno}。
@end deffn

@geindex get_last_error() (於 ctypes 模組中)
@anchor{library/ctypes ctypes get_last_error}@anchor{31de}
@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{2006,,可用性}: Windows

引發一個不附帶引數的@ref{1b70,,稽核事件} @code{ctypes.get_last_error}。
@end deffn

@geindex memmove() (於 ctypes 模組中)
@anchor{library/ctypes ctypes memmove}@anchor{31f0}
@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{31f1}
@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{1f1}
@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{19a7}
@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{31d2}
@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{31dd}
@deffn {函式} ctypes.set_errno (value)

Set the current value of the ctypes-private copy of the system @ref{5b,,errno}
variable in the calling thread to `value' and return the previous value.

引發一個附帶引數 @code{errno} 的@ref{1b70,,稽核事件} @code{ctypes.set_errno}。
@end deffn

@geindex set_last_error() (於 ctypes 模組中)
@anchor{library/ctypes ctypes set_last_error}@anchor{31df}
@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{2006,,可用性}: Windows

引發一個附帶引數 @code{error} 的@ref{1b70,,稽核事件} @code{ctypes.set_last_error}。
@end deffn

@geindex sizeof() (於 ctypes 模組中)
@anchor{library/ctypes ctypes sizeof}@anchor{31f2}
@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{1ec}
@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.

引發一個附帶引數 @code{ptr}、@code{size} 的@ref{1b70,,稽核事件} @code{ctypes.string_at}。
@end deffn

@geindex WinError() (於 ctypes 模組中)
@anchor{library/ctypes ctypes WinError}@anchor{31f3}
@deffn {函式} ctypes.WinError (code=None, descr=None)

Creates an instance of @ref{2c0,,OSError}.  If `code' is not specified,
@ref{31af,,GetLastError()} is called to determine the error code. If `descr' is not
specified, @ref{31ef,,FormatError()} is called to get a textual description of the
error.

@ref{2006,,可用性}: Windows


在 3.3 版的變更: An instance of @ref{1250,,WindowsError} used to be created, which is now an
alias of @ref{2c0,,OSError}.

@end deffn

@geindex wstring_at() (於 ctypes 模組中)
@anchor{library/ctypes ctypes wstring_at}@anchor{31f4}
@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.

引發一個附帶引數 @code{ptr}、@code{size} 的@ref{1b70,,稽核事件} @code{ctypes.wstring_at}。
@end deffn

@geindex memoryview_at() (於 ctypes 模組中)
@anchor{library/ctypes ctypes memoryview_at}@anchor{1eb}
@deffn {函式} ctypes.memoryview_at (ptr, size, readonly=False)

Return a @ref{165,,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{1ec,,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{31f5,,from_address()} only takes integers, `ptr' can also
be given as a @ref{1f1,,ctypes.POINTER} or a @ref{31b3,,byref()} object.)

引發一個附帶引數 @code{address}、@code{size} 與 @code{readonly} 的@ref{1b70,,稽核事件} @code{ctypes.memoryview_at}。


在 3.14 版被加入.

@end deffn

@node Data types,Fundamental data types<2>,Utility functions,ctypes reference
@anchor{library/ctypes ctypes-data-types}@anchor{31f6}@anchor{library/ctypes data-types}@anchor{31f7}
@subsubsection Data types


@geindex _CData (ctypes 中的類別)
@anchor{library/ctypes ctypes _CData}@anchor{31f8}
@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{31ea,,addressof()} helper function. Another instance variable is exposed as
@ref{31f9,,_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{2282,,metaclass}):

@geindex from_buffer() (ctypes._CData 的方法)
@anchor{library/ctypes ctypes _CData from_buffer}@anchor{31fa}
@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{2eb,,ValueError} is raised.

引發一個附帶引數 @code{pointer}、@code{size}、@code{offset} 的@ref{1b70,,稽核事件} @code{ctypes.cdata/buffer}。
@end deffn

@geindex from_buffer_copy() (ctypes._CData 的方法)
@anchor{library/ctypes ctypes _CData from_buffer_copy}@anchor{31fb}
@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{2eb,,ValueError} is
raised.

引發一個附帶引數 @code{pointer}、@code{size}、@code{offset} 的@ref{1b70,,稽核事件} @code{ctypes.cdata/buffer}。
@end deffn

@geindex from_address() (ctypes._CData 的方法)
@anchor{library/ctypes ctypes _CData from_address}@anchor{31f5}
@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{1b70,,auditing event} @code{ctypes.cdata} with argument
@code{address}.

@end deffn

@geindex from_param() (ctypes._CData 的方法)
@anchor{library/ctypes ctypes _CData from_param}@anchor{31ab}
@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{1757,,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{31cc}
@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{1f2}
@deffn {屬性} __pointer_type__

The pointer type that was created by calling
@ref{1f1,,POINTER()} for corresponding ctypes data type. If a pointer type
was not yet created, the attribute is missing.


在 3.14 版被加入.

@end deffn

Common instance variables of ctypes data types:

@geindex _b_base_ (ctypes._CData 的屬性)
@anchor{library/ctypes ctypes _CData _b_base_}@anchor{31fc}
@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{31fc,,_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{31fd}
@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{31f9}
@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,ctypes reference
@anchor{library/ctypes ctypes-fundamental-data-types-2}@anchor{31fe}@anchor{library/ctypes id1}@anchor{31ff}
@subsubsection Fundamental data types


@geindex _SimpleCData (ctypes 中的類別)
@anchor{library/ctypes ctypes _SimpleCData}@anchor{3200}
@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.  @ref{3200,,_SimpleCData} is a subclass of
@ref{31f8,,_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{3201}
@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.  @ref{2e,,ctypes} does `not' implement
original object return, always a new object is constructed.  The same is
true for all other ctypes object instances.
@end deffn
@end deffn

Fundamental data types, when returned as foreign function call results, or, for
example, by retrieving structure field members or array items, are transparently
converted to native Python types.  In other words, if a foreign function has a
@ref{31ae,,restype} of @ref{19a8,,c_char_p}, you will always receive a Python bytes
object, `not' a @ref{19a8,,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{19aa,,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{1a2b}
@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{3190}
@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{19a8}
@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{1bb0}
@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{1bb1}
@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{1bb0,,c_double}.
@end deffn

@geindex c_float (ctypes 中的類別)
@anchor{library/ctypes ctypes c_float}@anchor{31a1}
@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{1ee}
@deffn {類別} ctypes.c_double_complex

Represents the C double complex datatype, if available.  The
constructor accepts an optional @ref{197,,complex} initializer.


在 3.14 版被加入.

@end deffn

@geindex c_float_complex (ctypes 中的類別)
@anchor{library/ctypes ctypes c_float_complex}@anchor{1ed}
@deffn {類別} ctypes.c_float_complex

Represents the C float complex datatype, if available.  The
constructor accepts an optional @ref{197,,complex} initializer.


在 3.14 版被加入.

@end deffn

@geindex c_longdouble_complex (ctypes 中的類別)
@anchor{library/ctypes ctypes c_longdouble_complex}@anchor{1ef}
@deffn {類別} ctypes.c_longdouble_complex

Represents the C long double complex datatype, if available.  The
constructor accepts an optional @ref{197,,complex} initializer.


在 3.14 版被加入.

@end deffn

@geindex c_int (ctypes 中的類別)
@anchor{library/ctypes ctypes c_int}@anchor{3184}
@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{3185,,c_long}.
@end deffn

@geindex c_int8 (ctypes 中的類別)
@anchor{library/ctypes ctypes c_int8}@anchor{3194}
@deffn {類別} ctypes.c_int8

Represents the C 8-bit signed int datatype.  It is an alias for
@ref{1a2b,,c_byte}.
@end deffn

@geindex c_int16 (ctypes 中的類別)
@anchor{library/ctypes ctypes c_int16}@anchor{3195}
@deffn {類別} ctypes.c_int16

Represents the C 16-bit signed int datatype.  Usually an alias for
@ref{3192,,c_short}.
@end deffn

@geindex c_int32 (ctypes 中的類別)
@anchor{library/ctypes ctypes c_int32}@anchor{3196}
@deffn {類別} ctypes.c_int32

Represents the C 32-bit signed int datatype.  Usually an alias for
@ref{3184,,c_int}.
@end deffn

@geindex c_int64 (ctypes 中的類別)
@anchor{library/ctypes ctypes c_int64}@anchor{3197}
@deffn {類別} ctypes.c_int64

Represents the C 64-bit signed int datatype.  Usually an alias for
@ref{319e,,c_longlong}.
@end deffn

@geindex c_long (ctypes 中的類別)
@anchor{library/ctypes ctypes c_long}@anchor{3185}
@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{319e}
@deffn {類別} ctypes.c_longlong

Represents the C signed long long datatype.  The constructor accepts
an optional integer initializer; no overflow checking is done.
@end deffn

@geindex c_short (ctypes 中的類別)
@anchor{library/ctypes ctypes c_short}@anchor{3192}
@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{31a0}
@deffn {類別} ctypes.c_size_t

Represents the C @code{size_t} datatype.
@end deffn

@geindex c_ssize_t (ctypes 中的類別)
@anchor{library/ctypes ctypes c_ssize_t}@anchor{143d}
@deffn {類別} ctypes.c_ssize_t

Represents the C @code{ssize_t} datatype.


在 3.2 版被加入.

@end deffn

@geindex c_time_t (ctypes 中的類別)
@anchor{library/ctypes ctypes c_time_t}@anchor{1a92}
@deffn {類別} ctypes.c_time_t

Represents the C @code{time_t} datatype.


在 3.12 版被加入.

@end deffn

@geindex c_ubyte (ctypes 中的類別)
@anchor{library/ctypes ctypes c_ubyte}@anchor{1a2c}
@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{3198}
@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{319d,,c_ulong}.
@end deffn

@geindex c_uint8 (ctypes 中的類別)
@anchor{library/ctypes ctypes c_uint8}@anchor{3199}
@deffn {類別} ctypes.c_uint8

Represents the C 8-bit unsigned int datatype.  It is an alias for
@ref{1a2c,,c_ubyte}.
@end deffn

@geindex c_uint16 (ctypes 中的類別)
@anchor{library/ctypes ctypes c_uint16}@anchor{319a}
@deffn {類別} ctypes.c_uint16

Represents the C 16-bit unsigned int datatype.  Usually an alias for
@ref{3193,,c_ushort}.
@end deffn

@geindex c_uint32 (ctypes 中的類別)
@anchor{library/ctypes ctypes c_uint32}@anchor{319b}
@deffn {類別} ctypes.c_uint32

Represents the C 32-bit unsigned int datatype.  Usually an alias for
@ref{3198,,c_uint}.
@end deffn

@geindex c_uint64 (ctypes 中的類別)
@anchor{library/ctypes ctypes c_uint64}@anchor{319c}
@deffn {類別} ctypes.c_uint64

Represents the C 64-bit unsigned int datatype.  Usually an alias for
@ref{319f,,c_ulonglong}.
@end deffn

@geindex c_ulong (ctypes 中的類別)
@anchor{library/ctypes ctypes c_ulong}@anchor{319d}
@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{319f}
@deffn {類別} ctypes.c_ulonglong

Represents the C unsigned long long datatype.  The constructor
accepts an optional integer initializer; no overflow checking is done.
@end deffn

@geindex c_ushort (ctypes 中的類別)
@anchor{library/ctypes ctypes c_ushort}@anchor{3193}
@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{19aa}
@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{3191}
@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{19a9}
@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{318f}
@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{31db}
@deffn {類別} ctypes.HRESULT

Represents a @code{HRESULT} value, which contains success or
error information for a function or method call.

@ref{2006,,可用性}: Windows
@end deffn

@geindex py_object (ctypes 中的類別)
@anchor{library/ctypes ctypes py_object}@anchor{1f3}
@deffn {類別} ctypes.py_object

Represents the C @ref{5d7,,PyObject}* datatype.  Calling this without an
argument creates a @code{NULL} @ref{5d7,,PyObject}* pointer.


在 3.14 版的變更: @code{py_object} is now a @ref{1a1,,generic type}.

@end deffn

The @code{ctypes.wintypes} module provides quite some other Windows specific
data types, for example @code{HWND}, @code{WPARAM}, or @code{DWORD}.
Some useful structures like @code{MSG} or @code{RECT} are also defined.

@node Structured data types,Arrays and pointers,Fundamental data types<2>,ctypes reference
@anchor{library/ctypes ctypes-structured-data-types}@anchor{3202}@anchor{library/ctypes structured-data-types}@anchor{3203}
@subsubsection Structured data types


@geindex Union (ctypes 中的類別)
@anchor{library/ctypes ctypes Union}@anchor{1e6}
@deffn {類別} ctypes.Union (*args, **kw)

Abstract base class for unions in native byte order.

Unions share common attributes and behavior with structures;
see @ref{1e5,,Structure} documentation for details.
@end deffn

@geindex BigEndianUnion (ctypes 中的類別)
@anchor{library/ctypes ctypes BigEndianUnion}@anchor{1add}
@deffn {類別} ctypes.BigEndianUnion (*args, **kw)

Abstract base class for unions in `big endian' byte order.


在 3.11 版被加入.

@end deffn

@geindex LittleEndianUnion (ctypes 中的類別)
@anchor{library/ctypes ctypes LittleEndianUnion}@anchor{1ade}
@deffn {類別} ctypes.LittleEndianUnion (*args, **kw)

Abstract base class for unions in `little endian' byte order.


在 3.11 版被加入.

@end deffn

@geindex BigEndianStructure (ctypes 中的類別)
@anchor{library/ctypes ctypes BigEndianStructure}@anchor{31b8}
@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{31b9}
@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{1e5}
@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{189c,,_fields_} class variable. @ref{2e,,ctypes} will
create @ref{17fc,,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{189c}
@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{3184,,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{189c,,_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{5e8,,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{31f2,,sizeof()} is called on it, and so on.
Later assignments to @code{_fields_} will raise an @ref{5e8,,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{189c,,_fields_} defined in the sub-subclass, if any.
@end deffn

@geindex _pack_ (ctypes.Structure 的屬性)
@anchor{library/ctypes ctypes Structure _pack_}@anchor{316}
@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{1e7,,_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
@ref{2e,,ctypes} may allow larger `n' than what the compiler accepts.

@code{_pack_} must already be defined
when @ref{189c,,_fields_} is assigned, otherwise it will have no effect.


Deprecated since version 3.14, will be removed in version 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{1e7,,_layout_} to @code{'ms'}
explicitly.

@end deffn

@geindex _align_ (ctypes.Structure 的屬性)
@anchor{library/ctypes ctypes Structure _align_}@anchor{4e3}
@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 @ref{2e,,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{189c,,_fields_} is assigned, otherwise it will have no effect.


在 3.13 版被加入.

@end deffn

@geindex _layout_ (ctypes.Structure 的屬性)
@anchor{library/ctypes ctypes Structure _layout_}@anchor{1e7}
@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{316,,_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{316,,_pack_} is specified: @code{"ms"}.
(This is deprecated; see @ref{316,,_pack_} documentation.)

@item 
Otherwise: @code{"gcc-sysv"}
@end itemize

@code{_layout_} must already be defined when
@ref{189c,,_fields_} is assigned, otherwise it will have no effect.


在 3.14 版被加入.

@end deffn

@geindex _anonymous_ (ctypes.Structure 的屬性)
@anchor{library/ctypes ctypes Structure _anonymous_}@anchor{3204}
@deffn {屬性} _anonymous_

An optional sequence that lists the names of unnamed (anonymous) fields.
@ref{3204,,_anonymous_} must be already defined when @ref{189c,,_fields_} is
assigned, otherwise it will have no effect.

The fields listed in this variable must be structure or union type fields.
@ref{2e,,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{189c,,_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{189c,,_fields_}.  Keyword arguments in the
constructor are interpreted as attribute assignments, so they will initialize
@ref{189c,,_fields_} with the same name, or create new attributes for names not
present in @ref{189c,,_fields_}.
@end deffn

@geindex CField (ctypes 中的類別)
@anchor{library/ctypes ctypes CField}@anchor{1e8}
@deffn {類別} ctypes.CField (*args, **kw)

Descriptor for fields of a @ref{1e5,,Structure} and @ref{1e6,,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{189c,,_fields_};
do not instantiate the class directly.


在 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{3205}
@deffn {屬性} name

Name of the field, as a string.
@end deffn

@geindex type (ctypes.CField 的屬性)
@anchor{library/ctypes ctypes CField type}@anchor{3206}
@deffn {屬性} type

Type of the field, as a @ref{31f6,,ctypes class}.
@end deffn

@geindex offset (ctypes.CField 的屬性)
@geindex byte_offset (ctypes.CField 的屬性)
@anchor{library/ctypes ctypes CField offset}@anchor{3207}
@deffn {屬性} offset
@anchor{library/ctypes ctypes CField byte_offset}@anchor{3208}
@deffnx {屬性} byte_offset

Offset of the field, in bytes.

For bitfields, this is the offset of the underlying byte-aligned
`storage unit'; see @ref{3209,,bit_offset}.
@end deffn

@geindex byte_size (ctypes.CField 的屬性)
@anchor{library/ctypes ctypes CField byte_size}@anchor{320a}
@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{320b}
@deffn {屬性} size

For non-bitfields, equivalent to @ref{320a,,byte_size}.

For bitfields, this contains a backwards-compatible bit-packed
value that combines @ref{320c,,bit_size} and
@ref{3209,,bit_offset}.
Prefer using the explicit attributes instead.
@end deffn

@geindex is_bitfield (ctypes.CField 的屬性)
@anchor{library/ctypes ctypes CField is_bitfield}@anchor{320d}
@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{3209}
@deffn {屬性} bit_offset
@anchor{library/ctypes ctypes CField bit_size}@anchor{320c}
@deffnx {屬性} bit_size

The location of a bitfield within its `storage unit', that is, within
@ref{320a,,byte_size} bytes of memory starting at
@ref{3208,,byte_offset}.

To get the field's value, read the storage unit as an integer,
@ref{2371,,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{320e}
@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,Structured data types,ctypes reference
@anchor{library/ctypes arrays-and-pointers}@anchor{320f}@anchor{library/ctypes ctypes-arrays-pointers}@anchor{3210}
@subsubsection Arrays and pointers


@geindex Array (ctypes 中的類別)
@anchor{library/ctypes ctypes Array}@anchor{1cd4}
@deffn {類別} ctypes.Array (*args)

Abstract base class for arrays.

The recommended way to create concrete array types is by multiplying any
@ref{2e,,ctypes} data type with a non-negative integer.  Alternatively, you can subclass
this type and define @ref{3211,,_length_} and @ref{3212,,_type_} class variables.
Array elements can be read and written using standard
subscript and slice accesses; for slice reads, the resulting object is
`not' itself an @ref{1cd4,,Array}.

@geindex _length_ (ctypes.Array 的屬性)
@anchor{library/ctypes ctypes Array _length_}@anchor{3211}
@deffn {屬性} _length_

A positive integer specifying the number of elements in the array.
Out-of-range subscripts result in an @ref{1729,,IndexError}. Will be
returned by @ref{839,,len()}.
@end deffn

@geindex _type_ (ctypes.Array 的屬性)
@anchor{library/ctypes ctypes Array _type_}@anchor{3212}
@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{598}
@deffn {函式} ctypes.ARRAY (type, length)

Create an array.
Equivalent to @code{type * length}, where `type' is a
@ref{2e,,ctypes} data type and `length' an integer.

This function is @ref{23d,,soft deprecated} in favor of multiplication.
There are no plans to remove it.
@end deffn

@geindex _Pointer (ctypes 中的類別)
@anchor{library/ctypes ctypes _Pointer}@anchor{3213}
@deffn {類別} ctypes._Pointer

Private, abstract base class for pointers.

Concrete pointer types are created by calling @ref{1f1,,POINTER()} with the
type that will be pointed to; this is done automatically by
@ref{19a7,,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{839,,len()} will raise @ref{198,,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{17ce}
@deffn {屬性} _type_

Specifies the type pointed to.
@end deffn

@geindex contents (ctypes._Pointer 的屬性)
@anchor{library/ctypes ctypes _Pointer contents}@anchor{31bf}
@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,,Arrays and pointers,ctypes reference
@anchor{library/ctypes ctypes-exceptions}@anchor{3214}@anchor{library/ctypes exceptions}@anchor{3215}
@subsubsection Exceptions


@geindex ArgumentError
@anchor{library/ctypes ctypes ArgumentError}@anchor{3216}
@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{1e9}
@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{3217}
@deffn {屬性} hresult

The integer value representing the error code.
@end deffn

@geindex text (ctypes.COMError 的屬性)
@anchor{library/ctypes ctypes COMError text}@anchor{3218}
@deffn {屬性} text

The error message.
@end deffn

@geindex details (ctypes.COMError 的屬性)
@anchor{library/ctypes ctypes COMError details}@anchor{3219}
@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{2006,,可用性}: Windows


在 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 命令列介面函式庫,並行執行 Concurrent Execution,通用作業系統服務,Python 標準函式庫 Standard Library
@anchor{library/cmdlinelibs doc}@anchor{321a}@anchor{library/cmdlinelibs cmdlinelibs}@anchor{321b}@anchor{library/cmdlinelibs command-line-interface-libraries}@anchor{321c}@anchor{library/cmdlinelibs translation-repo}@anchor{321d}
@section 命令列介面函式庫


本章節所描述的模組協助實作應用程式的命令列與終端介面。

以下為概覽：

@menu
* argparse: argparse --- 命令列選項、引數和子命令的剖析器. 命令列選項、引數和子命令的剖析器
* optparse: optparse --- 命令列選項剖析器. 命令列選項剖析器
* getpass: getpass --- 可攜式密碼輸入工具. 可攜式密碼輸入工具
* fileinput: fileinput --- 逐列疊代多個輸入串流. 逐列疊代多個輸入串流
* curses: curses --- 字元儲存格顯示的終端處理. 字元儲存格顯示的終端處理
* curses.textpad: curses textpad --- Text input widget for curses programs. Text input widget for curses programs
* curses.ascii: curses ascii --- ASCII 字元的工具程式. ASCII 字元的工具程式
* curses.panel: curses panel --- curses 的面板堆疊擴充. curses 的面板堆疊擴充
* cmd: cmd --- 以列為導向的命令直譯器支援. 以列為導向的命令直譯器支援

@end menu

@node argparse --- 命令列選項、引數和子命令的剖析器,optparse --- 命令列選項剖析器,,命令列介面函式庫
@anchor{library/argparse doc}@anchor{321e}@anchor{library/argparse argparse-parser-for-command-line-options-arguments-and-subcommands}@anchor{321f}@anchor{library/argparse module-argparse}@anchor{7}
@subsection @code{argparse} --- 命令列選項、引數和子命令的剖析器


@geindex module; argparse


在 3.2 版被加入.


`原始碼：'Lib/argparse.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/argparse.py}

@cartouche
@quotation 備註 
While @ref{7,,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{3220,,選擇一個命令列參數剖析函式庫} 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 教學



This page contains the API reference information. For a more gentle
introduction to Python command-line parsing, have a look at the
@ref{3221,,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{1465,,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{1bd,,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{4b7,,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')           # 位置引數
parser.add_argument('-c', '--count')      # 接收一個值的選項
parser.add_argument('-v', '--verbose',
                    action='store_true')  # 開關旗標
@end example

The @ref{3222,,ArgumentParser.parse_args()} method runs the parser and places
the extracted data in a @ref{3223,,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{13af,,Upgrading Optparse Code}.
@end quotation
@end cartouche

@menu
* ArgumentParser 物件:: 
* add_argument() 方法: add_argument 方法. 
* parse_args() 方法: parse_args 方法. 
* Other utilities:: 
* 例外: 例外<9>. 

@end menu

@node ArgumentParser 物件,add_argument 方法,,argparse --- 命令列選項、引數和子命令的剖析器
@anchor{library/argparse argumentparser-objects}@anchor{3224}
@subsubsection ArgumentParser 物件


@geindex ArgumentParser (argparse 中的類別)
@anchor{library/argparse argparse ArgumentParser}@anchor{1bd}
@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=False, color=True)

Create a new @ref{1bd,,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{1bc,,prog} - 程式的名稱（預設值：從 @code{__main__} 模組屬性和 @code{sys.argv[0]} 產生）

@item 
@ref{3225,,usage} - 描述程式用法的字串（預設值：從新增到剖析器的引數產生）

@item 
@ref{3226,,description} - 引數說明之前要顯示的文字（預設值：無文字）

@item 
@ref{3227,,epilog} - 引數說明之後要顯示的文字（預設值：無文字）

@item 
@ref{3228,,parents} - 一個 @ref{1bd,,ArgumentParser} 物件的串列，其引數也應該被包含

@item 
@ref{3229,,formatter_class} - 用於自訂說明輸出的類別

@item 
@ref{322a,,prefix_chars} - 前綴可選引數的字元集合（預設值：'-'）

@item 
@ref{322b,,fromfile_prefix_chars} - The set of characters that prefix files from
which additional arguments should be read (default: @code{None})

@item 
@ref{322c,,argument_default} - The global default value for arguments
(default: @code{None})

@item 
@ref{322d,,conflict_handler} - The strategy for resolving conflicting optionals
(usually unnecessary)

@item 
@ref{322e,,add_help} - Add a @code{-h/--help} option to the parser (default: @code{True})

@item 
@ref{fba,,allow_abbrev} - Allows long options to be abbreviated if the
abbreviation is unambiguous (default: @code{True})

@item 
@ref{322f,,exit_on_error} - Determines whether or not @code{ArgumentParser} exits with
error info when an error occurs. (default: @code{True})

@item 
@ref{3230,,suggest_on_error} - Enables suggestions for mistyped argument choices
and subparser names (default: @code{False})

@item 
@ref{3231,,color} - Allow color output (default: @code{True})
@end itemize


在 3.5 版的變更: 新增 `allow_abbrev' 參數。



在 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' 參數。



在 3.14 版的變更: 新增 `suggest_on_error' 和 `color' 參數。

@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 物件
@anchor{library/argparse id1}@anchor{3232}@anchor{library/argparse prog}@anchor{1bc}
@subsubsection prog


By default, @ref{1bd,,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{2afa,,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{23c,,-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{1bd,,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 物件
@anchor{library/argparse usage}@anchor{3225}
@subsubsection usage


By default, @ref{1bd,,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{e0c,,add_subparsers()}
or the @code{prog} and the @code{usage} arguments to
@code{add_parser()}, to ensure consistent command prefixes and
usage information across subparsers.

@node description,epilog,usage,ArgumentParser 物件
@anchor{library/argparse description}@anchor{3226}@anchor{library/argparse id2}@anchor{3233}
@subsubsection description


Most calls to the @ref{1bd,,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{3229,,formatter_class} argument.

@node epilog,parents,description,ArgumentParser 物件
@anchor{library/argparse epilog}@anchor{3227}
@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{1bd,,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{3226,,description} argument, the @code{epilog=} text is by default
line-wrapped, but this behavior can be adjusted with the @ref{3229,,formatter_class}
argument to @ref{1bd,,ArgumentParser}.

@node parents,formatter_class,epilog,ArgumentParser 物件
@anchor{library/argparse parents}@anchor{3228}
@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{1bd,,ArgumentParser}
can be used.  The @code{parents=} argument takes a list of @ref{1bd,,ArgumentParser}
objects, collects all the positional and optional actions from them, and adds
these actions to the @ref{1bd,,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{1bd,,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 物件
@anchor{library/argparse formatter-class}@anchor{3229}@anchor{library/argparse id3}@anchor{3234}
@subsubsection formatter_class


@ref{1bd,,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{3235}
@deffn {類別} argparse.RawDescriptionHelpFormatter
@anchor{library/argparse argparse RawTextHelpFormatter}@anchor{3236}
@deffnx {類別} argparse.RawTextHelpFormatter
@anchor{library/argparse argparse ArgumentDefaultsHelpFormatter}@anchor{1b52}
@deffnx {類別} argparse.ArgumentDefaultsHelpFormatter
@anchor{library/argparse argparse MetavarTypeHelpFormatter}@anchor{3237}
@deffnx {類別} argparse.MetavarTypeHelpFormatter
@end deffn

@ref{3235,,RawDescriptionHelpFormatter} and @ref{3236,,RawTextHelpFormatter} give
more control over how textual descriptions are displayed.
By default, @ref{1bd,,ArgumentParser} objects line-wrap the @ref{3226,,description} and
@ref{3227,,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{3235,,RawDescriptionHelpFormatter} as @code{formatter_class=}
indicates that @ref{3226,,description} and @ref{3227,,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{3236,,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{1b52,,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{3237,,MetavarTypeHelpFormatter} uses the name of the @ref{3238,,type} argument for each
argument as the display name for its values (rather than using the @ref{3239,,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 物件
@anchor{library/argparse prefix-chars}@anchor{322a}
@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{1bd,,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 物件
@anchor{library/argparse fromfile-prefix-chars}@anchor{322b}
@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{1bd,,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{323a,,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{1bd,,ArgumentParser} uses @ref{756,,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{1bd,,ArgumentParser} changed encoding and errors to read arguments files
from default (e.g. @ref{755,,locale.getpreferredencoding(False)}
and @code{"strict"}) to the @ref{756,,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 物件
@anchor{library/argparse argument-default}@anchor{322c}
@subsubsection argument_default


Generally, argument defaults are specified either by passing a default to
@ref{4b7,,add_argument()} or by calling the
@ref{323b,,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{1bd,,ArgumentParser}.  For example,
to globally suppress attribute creation on @ref{3222,,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 物件
@anchor{library/argparse allow-abbrev}@anchor{fba}@anchor{library/argparse id4}@anchor{323c}
@subsubsection allow_abbrev


Normally, when you pass an argument list to the
@ref{3222,,parse_args()} method of an @ref{1bd,,ArgumentParser},
it @ref{fb9,,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


在 3.5 版被加入.


@node conflict_handler,add_help,allow_abbrev,ArgumentParser 物件
@anchor{library/argparse conflict-handler}@anchor{322d}
@subsubsection conflict_handler


@ref{1bd,,ArgumentParser} objects do not allow two actions with the same option
string.  By default, @ref{1bd,,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{3228,,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{1bd,,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{1bd,,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 物件
@anchor{library/argparse add-help}@anchor{322e}
@subsubsection add_help


By default, @ref{1bd,,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{1bd,,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 物件
@anchor{library/argparse exit-on-error}@anchor{322f}
@subsubsection exit_on_error


Normally, when you pass an invalid argument list to the @ref{3222,,parse_args()}
method of an @ref{1bd,,ArgumentParser}, it will print a `message' to @ref{b2a,,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


在 3.9 版被加入.


@node suggest_on_error,color,exit_on_error,ArgumentParser 物件
@anchor{library/argparse suggest-on-error}@anchor{3230}
@subsubsection suggest_on_error


By default, when a user passes an invalid argument choice or subparser name,
@ref{1bd,,ArgumentParser} will exit with error info and list the permissible
argument choices (if specified) or subparser names as part of the error message.

If the user would like to enable suggestions for mistyped argument choices and
subparser names, the feature can be enabled by setting @code{suggest_on_error} to
@code{True}. Note that this only applies for arguments when the choices specified
are strings:

@example
>>> parser = argparse.ArgumentParser(description='Process some integers.',
                                     suggest_on_error=True)
>>> 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(['--action', 'sumn', 1, 2, 3])
tester.py: error: argument --action: invalid choice: 'sumn', maybe you meant 'sum'? (choose from 'sum', 'max')
@end example

If you're writing code that needs to be compatible with older Python versions
and want to opportunistically use @code{suggest_on_error} when it's available, you
can set it as an attribute after initializing the parser instead of using the
keyword argument:

@example
>>> parser = argparse.ArgumentParser(description='Process some integers.')
>>> parser.suggest_on_error = True
@end example


在 3.14 版被加入.


@node color,,suggest_on_error,ArgumentParser 物件
@anchor{library/argparse color}@anchor{3231}
@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{1b7,,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


在 3.14 版被加入.


@node add_argument 方法,parse_args 方法,ArgumentParser 物件,argparse --- 命令列選項、引數和子命令的剖析器
@anchor{library/argparse the-add-argument-method}@anchor{323d}
@subsubsection add_argument() 方法


@geindex add_argument() (argparse.ArgumentParser 的方法)
@anchor{library/argparse argparse ArgumentParser add_argument}@anchor{4b7}
@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{323e,,name or flags} - Either a name or a list of option strings, e.g. @code{'foo'}
or @code{'-f', '--foo'}.

@item 
@ref{1891,,action} - The basic type of action to be taken when this argument is
encountered at the command line.

@item 
@ref{1897,,nargs} - The number of command-line arguments that should be consumed.

@item 
@ref{1899,,const} - A constant value required by some @ref{1891,,action} and @ref{1897,,nargs} selections.

@item 
@ref{1898,,default} - The value produced if the argument is absent from the
command line and if it is absent from the namespace object.

@item 
@ref{3238,,type} - The type to which the command-line argument should be converted.

@item 
@ref{1893,,choices} - A sequence of the allowable values for the argument.

@item 
@ref{323f,,required} - Whether or not the command-line option may be omitted
(optionals only).

@item 
@ref{3240,,help} - A brief description of what the argument does.

@item 
@ref{3241,,metavar} - A name for the argument in usage messages.

@item 
@ref{3239,,dest} - The name of the attribute to be added to the object returned by
@ref{3222,,parse_args()}.

@item 
@ref{3242,,deprecated} - Whether or not use of the argument is deprecated.
@end itemize
@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 類別:: 

@end menu

@node name or flags,action,,add_argument 方法
@anchor{library/argparse id5}@anchor{3243}@anchor{library/argparse name-or-flags}@anchor{323e}
@subsubsection name or flags


The @ref{4b7,,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
@ref{4b7,,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{3222,,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{3239,,dest} and @ref{3241,,metavar} parameters.
The @ref{3239,,dest} parameter defaults to the argument name with underscores @code{_}
replacing hyphens @code{-} . The @ref{3241,,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,add_argument 方法
@anchor{library/argparse action}@anchor{1891}@anchor{library/argparse id6}@anchor{3244}
@subsubsection action


@ref{1bd,,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{3222,,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{1899,,const} keyword
argument; note that the @ref{1899,,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'} used for storing the values @code{True} and @code{False}
respectively.  In addition, they create default values of @code{False} and
@code{True} respectively:

@example
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='store_true')
>>> parser.add_argument('--bar', action='store_false')
>>> parser.add_argument('--baz', action='store_false')
>>> parser.parse_args('--foo --bar'.split())
Namespace(foo=True, bar=False, baz=True)
@end example

@item 
@code{'append'} - 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 stores a list, and appends the value specified by
the @ref{1899,,const} keyword argument to the list; note that the @ref{1899,,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 stores a list and appends each item from the multi-value
argument list to it.
The @code{'extend'} action is typically used with the @ref{1897,,nargs} keyword argument
value @code{'+'} or @code{'*'}.
Note that when @ref{1897,,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


在 3.8 版被加入.


@item 
@code{'count'} - This counts the number of times a keyword 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{1bd,,ArgumentParser} for details of how the
output is created.

@item 
@code{'version'} - This expects a @code{version=} keyword argument in the
@ref{4b7,,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

你也可以傳遞一個 @ref{1ab6,,Action} 子類別（例如 @ref{1b0d,,BooleanOptionalAction}）或實作相同介面的其他物件。只有會消耗命令列引數的 action（例如 @code{'store'}、@code{'append'}、@code{'extend'} 或 @code{nargs} 不為零的自定義 action）可以被用於位置引數。

The recommended way to create a custom action is to extend @ref{1ab6,,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{3245,,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

更多詳情請見 @ref{1ab6,,Action}。

@node nargs,const,action,add_argument 方法
@anchor{library/argparse id7}@anchor{3246}@anchor{library/argparse nargs}@anchor{1897}
@subsubsection nargs


@ref{1bd,,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{3247,,指定不明確的引數}. 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 ? （問號）;於 argparse 模組中


@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{1898,,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{1899,,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 * （星號）;於 argparse 模組中


@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 + （加號）;於 argparse 模組中


@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{1891,,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,add_argument 方法
@anchor{library/argparse const}@anchor{1899}@anchor{library/argparse id8}@anchor{3248}
@subsubsection const


The @code{const} argument of @ref{4b7,,add_argument()} is used to hold
constant values that are not read from the command line but are required for
the various @ref{1bd,,ArgumentParser} actions.  The two most common uses of it are:


@itemize *

@item 
When @ref{4b7,,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{3222,,parse_args()}. See the @ref{1891,,action} description for examples.
If @code{const} is not provided to @ref{4b7,,add_argument()}, it will
receive a default value of @code{None}.

@item 
When @ref{4b7,,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{1897,,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,add_argument 方法
@anchor{library/argparse default}@anchor{1898}@anchor{library/argparse id9}@anchor{3249}
@subsubsection default


All optional arguments and some positional arguments may be omitted at the
command line.  The @code{default} keyword argument of
@ref{4b7,,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{3238,,type}
conversion argument, if provided, before setting the attribute on the
@ref{3223,,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{1897,,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{323f,,required} arguments, the @code{default} value is ignored. For example, this
applies to positional arguments with @ref{1897,,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,add_argument 方法
@anchor{library/argparse argparse-type}@anchor{324a}@anchor{library/argparse type}@anchor{3238}
@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{196,,float} or @ref{19b,,int}.  The
@code{type} keyword for @ref{4b7,,add_argument()} allows any
necessary type-checking and type conversions to be performed.

If the @ref{3238,,type} keyword is used with the @ref{1898,,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{3245,,register()})
If the function raises @ref{324b,,ArgumentTypeError}, @ref{198,,TypeError}, or
@ref{2eb,,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{3c1,,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.

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{101d,,JSONDecodeError} would not be well formatted and a
@ref{264,,FileNotFoundError} exception would not be handled at all.

Even @ref{30b,,FileType} has its limitations for use with the @code{type}
keyword.  If one argument uses @ref{30b,,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{186,,with}-statement to manage the
files.

For type checkers that simply check against a fixed set of values, consider
using the @ref{1893,,choices} keyword instead.

@node choices,required,type,add_argument 方法
@anchor{library/argparse choices}@anchor{1893}@anchor{library/argparse id10}@anchor{324c}
@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{4b7,,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{24d,,list} objects,
@ref{60c,,tuple} objects, and custom sequences are all supported.

Use of @ref{83b,,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{3238,,type}
conversions have been performed, so objects in `choices'
should match the @ref{3238,,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{3238,,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{3241,,metavar}.

@node required,help,choices,add_argument 方法
@anchor{library/argparse id11}@anchor{324d}@anchor{library/argparse required}@anchor{323f}
@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{4b7,,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{3222,,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,add_argument 方法
@anchor{library/argparse help}@anchor{3240}@anchor{library/argparse id12}@anchor{324e}
@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{1898,,default}.  The available
specifiers include the program name, @code{%(prog)s} and most keyword arguments to
@ref{4b7,,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,add_argument 方法
@anchor{library/argparse id13}@anchor{324f}@anchor{library/argparse metavar}@anchor{3241}
@subsubsection metavar


When @ref{1bd,,ArgumentParser} generates help messages, it needs some way to refer
to each expected argument.  By default, @code{ArgumentParser} objects use the @ref{3239,,dest}
value as the "name" of each object.  By default, for positional argument
actions, the @ref{3239,,dest} value is used directly, and for optional argument actions,
the @ref{3239,,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{3222,,parse_args()} object is still determined
by the @ref{3239,,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,add_argument 方法
@anchor{library/argparse dest}@anchor{3239}@anchor{library/argparse id14}@anchor{3250}
@subsubsection dest


Most @ref{1bd,,ArgumentParser} actions add some value as an attribute of the
object returned by @ref{3222,,parse_args()}.  The name of this
attribute is determined by the @code{dest} keyword argument of
@ref{4b7,,add_argument()}.  For positional argument actions,
@code{dest} is normally supplied as the first argument to
@ref{4b7,,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{1bd,,ArgumentParser} generates the value of @code{dest} by
taking the first long option string and stripping away the initial @code{--}
string.  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('-x', '-y')
>>> parser.parse_args('-f 1 -x 2'.split())
Namespace(foo_bar='1', x='2')
>>> parser.parse_args('--foo 1 -y 2'.split())
Namespace(foo_bar='1', x='2')
@end example

@code{dest} 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

@node deprecated,Action 類別,dest,add_argument 方法
@anchor{library/argparse deprecated}@anchor{3242}@anchor{library/argparse id15}@anchor{3251}
@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{4b7,,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{b2a,,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


在 3.13 版被加入.


@node Action 類別,,deprecated,add_argument 方法
@anchor{library/argparse action-classes}@anchor{3252}
@subsubsection Action 類別


@code{Action} classes implement the Action API, a callable which returns a callable
which processes arguments from the command-line. Any object which follows
this API may be passed as the @code{action} parameter to
@ref{4b7,,add_argument()}.

@geindex Action (argparse 中的類別)
@anchor{library/argparse argparse Action}@anchor{1ab6}
@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{1bd,,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{4b7,,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{3253}
@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{1bd,,ArgumentParser} object which contains this action.

@item 
`namespace' - The @ref{3223,,Namespace} object that will be returned by
@ref{3222,,parse_args()}.  Most actions add an attribute to this
object using @ref{2467,,setattr()}.

@item 
`values' - The associated command-line arguments, with any type conversions
applied.  Type conversions are specified with the @ref{3238,,type} keyword argument to
@ref{4b7,,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{3254}
@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{1b0d}
@deffn {類別} argparse.BooleanOptionalAction

A subclass of @ref{1ab6,,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


在 3.9 版被加入.

@end deffn

@node parse_args 方法,Other utilities,add_argument 方法,argparse --- 命令列選項、引數和子命令的剖析器
@anchor{library/argparse the-parse-args-method}@anchor{3255}
@subsubsection parse_args() 方法


@geindex parse_args() (argparse.ArgumentParser 的方法)
@anchor{library/argparse argparse ArgumentParser parse_args}@anchor{3222}
@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{4b7,,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{3256,,args} - List of strings to parse.  The default is taken from
@ref{1465,,sys.argv}.

@item 
@ref{3257,,namespace} - An object to take the attributes.  The default is a new empty
@ref{3223,,Namespace} object.
@end itemize
@end deffn

@menu
* Option value syntax:: 
* 無效引數:: 
* 包含 - 的引數:: 
* 引數縮寫 (前綴匹配): 引數縮寫 前綴匹配. 
* sys.argv 之外: sys argv 之外. 
* 命名空間物件:: 

@end menu

@node Option value syntax,無效引數,,parse_args 方法
@anchor{library/argparse option-value-syntax}@anchor{3258}
@subsubsection Option value syntax


The @ref{3222,,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 無效引數,包含 - 的引數,Option value syntax,parse_args 方法
@anchor{library/argparse invalid-arguments}@anchor{3259}
@subsubsection 無效引數


While parsing the command line, @ref{3222,,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='?')

>>> # 無效型別
>>> parser.parse_args(['--foo', 'spam'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: argument --foo: invalid int value: 'spam'

>>> # 無效選項
>>> parser.parse_args(['--bar'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: no such option: --bar

>>> # 錯誤引數數量
>>> parser.parse_args(['spam', 'badger'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: extra arguments found: badger
@end example

@node 包含 - 的引數,引數縮寫 前綴匹配,無效引數,parse_args 方法
@anchor{library/argparse arguments-containing}@anchor{325a}
@subsubsection 包含 @code{-} 的引數


The @ref{3222,,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 @ref{3222,,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{3222,,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{3247,,the argparse howto on ambiguous arguments}
for more details.

@node 引數縮寫 前綴匹配,sys argv 之外,包含 - 的引數,parse_args 方法
@anchor{library/argparse argument-abbreviations-prefix-matching}@anchor{325b}@anchor{library/argparse prefix-matching}@anchor{fb9}
@subsubsection 引數縮寫 (前綴匹配)


The @ref{3222,,parse_args()} method @ref{fba,,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{fba,,allow_abbrev} to @code{False}.

@node sys argv 之外,命名空間物件,引數縮寫 前綴匹配,parse_args 方法
@anchor{library/argparse args}@anchor{3256}@anchor{library/argparse beyond-sys-argv}@anchor{325c}
@subsubsection @code{sys.argv} 之外


Sometimes it may be useful to have an @ref{1bd,,ArgumentParser} parse arguments other than those
of @ref{1465,,sys.argv}.  This can be accomplished by passing a list of strings to
@ref{3222,,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 命名空間物件,,sys argv 之外,parse_args 方法
@anchor{library/argparse namespace}@anchor{3257}@anchor{library/argparse the-namespace-object}@anchor{325d}
@subsubsection 命名空間物件


@geindex Namespace (argparse 中的類別)
@anchor{library/argparse argparse Namespace}@anchor{3223}
@deffn {類別} argparse.Namespace

Simple class used by default by @ref{3222,,parse_args()} to create
an object holding attributes and return it.

This class is deliberately simple, just an @ref{c75,,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{1ceb,,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{1bd,,ArgumentParser} assign attributes to an
already existing object, rather than a new @ref{3223,,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,例外<9>,parse_args 方法,argparse --- 命令列選項、引數和子命令的剖析器
@anchor{library/argparse other-utilities}@anchor{325e}
@subsubsection Other utilities


@menu
* 子命令:: 
* FileType 物件:: 
* Argument groups:: 
* Mutual exclusion:: 
* Parser defaults:: 
* 印出幫助訊息:: 
* Partial parsing:: 
* Customizing file parsing:: 
* Exiting methods:: 
* Intermixed parsing:: 
* Registering custom types or actions:: 

@end menu

@node 子命令,FileType 物件,,Other utilities
@anchor{library/argparse sub-commands}@anchor{325f}
@subsubsection 子命令


@geindex add_subparsers() (argparse.ArgumentParser 的方法)
@anchor{library/argparse argparse ArgumentParser add_subparsers}@anchor{e0c}
@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{1bd,,ArgumentParser} supports the creation of such subcommands with the
@code{add_subparsers()} method.  The @code{add_subparsers()} method is normally
called with no arguments and returns a special action object.  This object
has a single method, @code{add_parser()}, which takes a
command name and any @code{ArgumentParser} constructor arguments, and
returns an @code{ArgumentParser} object that can be modified as usual.

參數的解釋：


@itemize *

@item 
`title' - title for the sub-parser group in help output; by default
"subcommands" if description is provided, otherwise uses title for
positional arguments

@item 
`description' - description for the sub-parser group in help output, by
default @code{None}

@item 
`prog' - usage information that will be displayed with sub-command help,
by default the name of the program and any positional arguments before the
subparser argument

@item 
`parser_class' - class which will be used to create sub-parser instances, by
default the class of the current parser (e.g. @ref{1bd,,ArgumentParser})

@item 
@ref{1891,,action} - the basic type of action to be taken when this argument is
encountered at the command line

@item 
@ref{3239,,dest} - name of the attribute under which sub-command name will be
stored; by default @code{None} and no value is stored

@item 
@ref{323f,,required} - Whether or not a subcommand must be provided, by default
@code{False} (added in 3.7)

@item 
@ref{3240,,help} - help for sub-parser group in help output, by default @code{None}

@item 
@ref{3241,,metavar} - string presenting available subcommands in help; by default it
is @code{None} and presents subcommands in form @{cmd1, cmd2, ..@}
@end itemize

一些使用範例：

@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{3222,,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 @code{add_parser()} as above.)

@example
>>> parser.parse_args(['--help'])
usage: PROG [-h] [--foo] @{a,b@} ...

positional arguments:
  @{a,b@}   subcommand help
    a     a help
    b     b help

options:
  -h, --help  show this help message and exit
  --foo   foo help

>>> parser.parse_args(['a', '--help'])
usage: PROG a [-h] bar

positional arguments:
  bar     bar help

options:
  -h, --help  show this help message and exit

>>> parser.parse_args(['b', '--help'])
usage: PROG b [-h] [--baz @{X,Y,Z@}]

options:
  -h, --help     show this help message and exit
  --baz @{X,Y,Z@}  baz help
@end example

The @ref{e0c,,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

Furthermore, @code{add_parser()} supports an additional
`aliases' argument,
which allows multiple strings to refer to the same subparser. This example,
like @code{svn}, aliases @code{co} as a shorthand for @code{checkout}:

@example
>>> parser = argparse.ArgumentParser()
>>> subparsers = parser.add_subparsers()
>>> checkout = subparsers.add_parser('checkout', aliases=['co'])
>>> checkout.add_argument('foo')
>>> parser.parse_args(['co', 'bar'])
Namespace(foo='bar')
@end example

@code{add_parser()} supports also an additional
`deprecated' argument, which allows to deprecate the subparser.

@example
>>> import argparse
>>> parser = argparse.ArgumentParser(prog='chicken.py')
>>> subparsers = parser.add_subparsers()
>>> run = subparsers.add_parser('run')
>>> fly = subparsers.add_parser('fly', deprecated=True)
>>> parser.parse_args(['fly'])
chicken.py: warning: command 'fly' is deprecated
Namespace()
@end example


在 3.13 版被加入.


One particularly effective way of handling subcommands is to combine the use
of the @ref{e0c,,add_subparsers()} method with calls to @ref{323b,,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{3222,,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 @ref{e0c,,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

@node FileType 物件,Argument groups,子命令,Other utilities
@anchor{library/argparse filetype-objects}@anchor{3260}
@subsubsection FileType 物件


@geindex FileType (argparse 中的類別)
@anchor{library/argparse argparse FileType}@anchor{30b}
@deffn {類別} argparse.FileType (mode='r', bufsize=-1, encoding=None, errors=None)

The @ref{30b,,FileType} factory creates objects that can be passed to the type
argument of @ref{4b7,,ArgumentParser.add_argument()}.  Arguments that have
@ref{30b,,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{315,,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{758,,sys.stdin} for readable @ref{30b,,FileType} objects and
@ref{cc4,,sys.stdout} for writable @ref{30b,,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{186,,with}-statement to manage the files.
@end quotation
@end cartouche


在 3.4 版的變更: Added the `encodings' and `errors' parameters.



在 3.14 版之後被棄用.

@end deffn

@node Argument groups,Mutual exclusion,FileType 物件,Other utilities
@anchor{library/argparse argument-groups}@anchor{3261}
@subsubsection Argument groups


@geindex add_argument_group() (argparse.ArgumentParser 的方法)
@anchor{library/argparse argparse ArgumentParser add_argument_group}@anchor{2ea}
@deffn {方法} ArgumentParser.add_argument_group (title=None, description=None, *[, argument_default][, conflict_handler])

By default, @ref{1bd,,ArgumentParser} groups command-line arguments into
"positional arguments" and "options" when displaying help
messages. When there is a better conceptual grouping of arguments than this
default one, appropriate groups can be created using the
@code{add_argument_group()} method:

@example
>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
>>> group = parser.add_argument_group('group')
>>> group.add_argument('--foo', help='foo help')
>>> group.add_argument('bar', help='bar help')
>>> parser.print_help()
usage: PROG [--foo FOO] bar

group:
  bar    bar help
  --foo FOO  foo help
@end example

The @ref{2ea,,add_argument_group()} method returns an argument group object which
has an @ref{4b7,,add_argument()} method just like a regular
@ref{1bd,,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{322c,,argument_default} and @ref{322d,,conflict_handler}
allow for finer-grained control of the behavior of the argument group. These
parameters have the same meaning as in the @ref{1bd,,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.


Deprecated since version 3.11, removed in version 3.14: Calling @ref{2ea,,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{322a,,prefix_chars} to @ref{2ea,,add_argument_group()}
is now deprecated.

@end deffn

@node Mutual exclusion,Parser defaults,Argument groups,Other utilities
@anchor{library/argparse mutual-exclusion}@anchor{3262}
@subsubsection Mutual exclusion


@geindex add_mutually_exclusive_group() (argparse.ArgumentParser 的方法)
@anchor{library/argparse argparse ArgumentParser add_mutually_exclusive_group}@anchor{2ec}
@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 @ref{2ec,,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{2ea,,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


Deprecated since version 3.11, removed in version 3.14: Calling @ref{2ea,,add_argument_group()} or @ref{2ec,,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,印出幫助訊息,Mutual exclusion,Other utilities
@anchor{library/argparse parser-defaults}@anchor{3263}
@subsubsection Parser defaults


@geindex set_defaults() (argparse.ArgumentParser 的方法)
@anchor{library/argparse argparse ArgumentParser set_defaults}@anchor{323b}
@deffn {方法} ArgumentParser.set_defaults (**kwargs)

Most of the time, the attributes of the object returned by @ref{3222,,parse_args()}
will be fully determined by inspecting the command-line arguments and the argument
actions.  @ref{323b,,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 parser-level defaults always override argument-level defaults:

@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{e0c,,add_subparsers()} method for an
example of this type.
@end deffn

@geindex get_default() (argparse.ArgumentParser 的方法)
@anchor{library/argparse argparse ArgumentParser get_default}@anchor{3264}
@deffn {方法} ArgumentParser.get_default (dest)

Get the default value for a namespace attribute, as set by either
@ref{4b7,,add_argument()} or by
@ref{323b,,set_defaults()}:

@example
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default='badger')
>>> parser.get_default('foo')
'badger'
@end example
@end deffn

@node 印出幫助訊息,Partial parsing,Parser defaults,Other utilities
@anchor{library/argparse printing-help}@anchor{3265}
@subsubsection 印出幫助訊息


In most typical applications, @ref{3222,,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{3266}
@deffn {方法} ArgumentParser.print_usage (file=None)

Print a brief description of how the @ref{1bd,,ArgumentParser} should be
invoked on the command line.  If `file' is @code{None}, @ref{cc4,,sys.stdout} is
assumed.
@end deffn

@geindex print_help() (argparse.ArgumentParser 的方法)
@anchor{library/argparse argparse ArgumentParser print_help}@anchor{3267}
@deffn {方法} ArgumentParser.print_help (file=None)

Print a help message, including the program usage and information about the
arguments registered with the @ref{1bd,,ArgumentParser}.  If `file' is
@code{None}, @ref{cc4,,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{1c79}
@deffn {方法} ArgumentParser.format_usage ()

Return a string containing a brief description of how the
@ref{1bd,,ArgumentParser} should be invoked on the command line.
@end deffn

@geindex format_help() (argparse.ArgumentParser 的方法)
@anchor{library/argparse argparse ArgumentParser format_help}@anchor{3268}
@deffn {方法} ArgumentParser.format_help ()

Return a string containing a help message, including the program usage and
information about the arguments registered with the @ref{1bd,,ArgumentParser}.
@end deffn

@node Partial parsing,Customizing file parsing,印出幫助訊息,Other utilities
@anchor{library/argparse partial-parsing}@anchor{3269}
@subsubsection Partial parsing


@geindex parse_known_args() (argparse.ArgumentParser 的方法)
@anchor{library/argparse argparse ArgumentParser parse_known_args}@anchor{326a}
@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 @ref{326a,,parse_known_args()} method can be
useful.

This method works similarly to @ref{3222,,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{fb9,,Prefix matching} rules apply to
@ref{326a,,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{326b}
@subsubsection Customizing file parsing


@geindex convert_arg_line_to_args() (argparse.ArgumentParser 的方法)
@anchor{library/argparse argparse ArgumentParser convert_arg_line_to_args}@anchor{323a}
@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{1bd,,ArgumentParser} constructor) are read one
argument per line. @ref{323a,,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{326c}
@subsubsection Exiting methods


@geindex exit() (argparse.ArgumentParser 的方法)
@anchor{library/argparse argparse ArgumentParser exit}@anchor{326d}
@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{b2a,,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{326e}
@deffn {方法} ArgumentParser.error (message)

This method prints a usage message, including the `message', to
@ref{b2a,,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{326f}
@subsubsection Intermixed parsing


@geindex parse_intermixed_args() (argparse.ArgumentParser 的方法)
@anchor{library/argparse argparse ArgumentParser parse_intermixed_args}@anchor{cef}
@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{3270}
@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{cef,,parse_intermixed_args()}
and @ref{3270,,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{326a,,parse_known_args()} and
@ref{cef,,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

@ref{3270,,parse_known_intermixed_args()} returns a two item tuple
containing the populated namespace and the list of remaining argument strings.
@ref{cef,,parse_intermixed_args()} raises an error if there are any
remaining unparsed argument strings.


在 3.7 版被加入.

@end deffn

@node Registering custom types or actions,,Intermixed parsing,Other utilities
@anchor{library/argparse registering-custom-types-or-actions}@anchor{3271}
@subsubsection Registering custom types or actions


@geindex register() (argparse.ArgumentParser 的方法)
@anchor{library/argparse argparse ArgumentParser register}@anchor{3245}
@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 例外<9>,,Other utilities,argparse --- 命令列選項、引數和子命令的剖析器
@anchor{library/argparse exceptions}@anchor{3272}
@subsubsection 例外


@geindex ArgumentError
@anchor{library/argparse argparse ArgumentError}@anchor{3273}
@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{324b}
@deffn {例外} argparse.ArgumentTypeError

Raised when something goes wrong converting a command line string to a type.
@end deffn

@subsubheading Guides and Tutorials


@menu
* Argparse 教學:: 
* 將 optparse 程式碼遷移到 argparse:: 

@end menu

@node Argparse 教學,將 optparse 程式碼遷移到 argparse,,例外<9>
@anchor{howto/argparse doc}@anchor{3274}@anchor{howto/argparse argparse-tutorial}@anchor{3221}@anchor{howto/argparse id1}@anchor{3275}
@subsubsection Argparse 教學


@*作者: 
Tshepang Mbambo


本教學旨在簡要介紹 @ref{7,,argparse} 這個 Python 標準函式庫中推薦的命令列剖析模組。

@cartouche
@quotation 備註 
標準函式庫包含另外兩個與命令列參數處理直接相關的函式庫：較低階的 @ref{a4,,optparse} 模組（可能需要更多程式碼來為給定應用程式設定，但也允許應用程式要求 @code{argparse} 不支援的行為），以及非常低階的 @ref{65,,getopt}（專門用作 C 程式設計師可用的 @code{getopt()} 函式系列的等價）。雖然這個指南並未直接涵蓋這些模組，但 @code{argparse} 的許多核心概念最初來自於 @code{optparse}，因此本教學的某些部分也適用於 @code{optparse} 使用者。
@end quotation
@end cartouche

@menu
* 概念:: 
* 基本用法: 基本用法<2>. 
* 位置引數的介紹:: 
* 可選引數的介紹:: 
* 組合位置引數和可選引數:: 
* 更進階一點:: 
* 如何翻譯 argparse 輸出:: 
* 自定義型別轉換器:: 
* 結論:: 

@end menu

@node 概念,基本用法<2>,,Argparse 教學
@anchor{howto/argparse concepts}@anchor{3276}
@subsubsection 概念


讓我們透過使用 @code{ls} 指令來展示我們將在本介紹教學中探索的功能類型：

@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

我們可以從這四個命令中學到一些概念：


@itemize *

@item 
@code{ls} 命令即便在沒有任何選項的情況下執行仍非常有用。它預設顯示目前目錄的內容。

@item 
如果我們想要看到比它預設提供更多的內容，我們也需要多告訴它一點。在本例中，我們希望它顯示不同的目錄 @code{pypy}，我們做的是指定所謂的位置引數。之所以如此命名是因為程式應該只根據該值在命令列中出現的位置來知道如何處理該值。這個概念與 @code{cp} 這樣的指令更相關，其最基本的用法是 @code{cp SRC DEST}。第一個是`你想要複製的位置'，第二個是`你想要複製過去的位置'。

@item 
現在假設我們想要改變程式的行為。在我們的範例中，我們顯示每個檔案的更多資訊，而不僅是顯示檔案名稱。在這種情況下，@code{-l} 被稱為可選引數。

@item 
這是幫助文字的片段。它非常有用，因為當你遇到以前從未使用過的程式時，只需閱讀其幫助文字即可了解它的工作原理。
@end itemize

@node 基本用法<2>,位置引數的介紹,概念,Argparse 教學
@anchor{howto/argparse the-basics}@anchor{3277}
@subsubsection 基本用法


讓我們從一個非常簡單的例子開始，它（幾乎）什麼都不做：

@example
import argparse
parser = argparse.ArgumentParser()
parser.parse_args()
@end example

程式碼執行結果如下：

@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

這是發生的事情：


@itemize *

@item 
執行不帶任何選項的腳本不會在標準輸出中顯示任何內容。不太有用。

@item 
第二個開始能夠顯現 @ref{7,,argparse} 模組的有用之處。我們幾乎什麼也沒做，但我們已經收到了一個很好的幫助訊息。

@item 
@code{--help} 選項也可以縮寫為 @code{-h}，是我們能隨意獲得的唯一選項（即無需指定它）。指定任何其他內容都會導致錯誤。但即便如此，我們也還是輕鬆地獲得了有用的使用資訊。
@end itemize

@node 位置引數的介紹,可選引數的介紹,基本用法<2>,Argparse 教學
@anchor{howto/argparse introducing-positional-arguments}@anchor{3278}
@subsubsection 位置引數的介紹


例如：

@example
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("echo")
args = parser.parse_args()
print(args.echo)
@end example

執行這段程式碼：

@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

這是會發生的事情：


@itemize *

@item 
我們新增了 @ref{4b7,,add_argument()} 方法，我們用它來指定程式願意接受哪些命令列選項。在本例中，我將其命名為 @code{echo}，以便與其功能一致。

@item 
現在呼叫我們的程式時需要指定一個選項。

@item 
@ref{3222,,parse_args()} 方法實際上從指定的選項中回傳一些資料，在本例中為 @code{echo}。

@item 
該變數是某種形式的「魔法」，@ref{7,,argparse} 可以自由執行（即無需指定該值儲存在哪個變數中）。你還會注意到，它的名稱與提供給方法 @code{echo} 的字串引數相符。
@end itemize

但請注意，儘管幫助顯示看起來不錯，但它目前還沒有發揮出應有的用處。例如，我們看到 @code{echo} 作為位置引數，但除了猜測或閱讀原始程式碼之外，我們不知道它的作用。那麼，我們來讓它變得更有用一點：

@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

然後我們得到：

@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

現在來做一些更有用處的事情：

@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

程式碼執行結果如下：

@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

進展不太順利。這是因為，除非我們另有說明，@ref{7,,argparse} 會將我們給它的選項視為字串。因此，讓我們告訴 @ref{7,,argparse} 將該輸入視為整數：

@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

程式碼執行結果如下：

@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

順利進展。現在該程式甚至可以在繼續操作之前因錯誤的非法輸入而退出。

@node 可選引數的介紹,組合位置引數和可選引數,位置引數的介紹,Argparse 教學
@anchor{howto/argparse introducing-optional-arguments}@anchor{3279}
@subsubsection 可選引數的介紹


到目前為止，我們一直在討論位置引數。我們來看看如何新增可選引數：

@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

接者是結果：

@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

這是發生的事情：


@itemize *

@item 
程式被編寫為在指定 @code{--verbosity} 時顯示一些內容，並在未指定時不顯示任何內容。

@item 
為了表示該選項實際上是可選的，沒使用它來執行程式並不會出現錯誤。請注意，預設情況下，如果未使用可選引數，則相關變數（在本例中為 @code{args.verbosity}）將被賦予 @code{None} 作為值，這就是它未能通過 @ref{181,,if} 陳述式真值測試的原因。

@item 
幫助訊息有點不同。

@item 
當使用 @code{--verbosity} 選項時必須要指定一些值，任何值都可以。
@end itemize

在上面的例子中，@code{--verbosity} 接受任意的整數，但對我們的程式來說只接受兩個輸入值， @code{True} 或 @code{False}。所以我們來修改一下程式碼使其符合：

@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

接者是結果：

@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

這是發生的事情：


@itemize *

@item 
這個選項現在更像是一個旗標，而不是需要值的東西。我們甚至更改了選項的名稱以符合這個想法。請注意，我們現在指定一個新的關鍵字 @code{action}，並為其指定值 @code{"store_true"}。這意味著，如果指定了該選項，則將值 @code{True} 指派給 @code{args.verbose}。不指定它代表為 @code{False}。

@item 
當你指定一個值時，它會本著旗標的實際精神來抱怨。

@item 
請注意不同的幫助文字。
@end itemize

@menu
* 短選項:: 

@end menu

@node 短選項,,,可選引數的介紹
@anchor{howto/argparse short-options}@anchor{327a}
@subsubsection 短選項


如果你熟悉命令列用法，你會注意到我尚未提及選項的簡短版本。這很簡單：

@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

而這為：

@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

請注意，新功能也反映在幫助文字中。

@node 組合位置引數和可選引數,更進階一點,可選引數的介紹,Argparse 教學
@anchor{howto/argparse combining-positional-and-optional-arguments}@anchor{327b}
@subsubsection 組合位置引數和可選引數


我們的程式的複雜性不斷增加：

@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

然後現在的輸出結果：

@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 
我們帶回了位置引數，因而被抱怨。

@item 
請注意，順序並不重要。
@end itemize

我們讓這個程式擁有多個訊息詳細級別 (verbosity) 之值的能力，並實際使用它們：

@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

接者是結果：

@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

除了最後一個外都看起來正常，它透露了我們程式中的一個錯誤。我們可透過限制 @code{--verbosity} 選項可以接受的值來修復它：

@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

接者是結果：

@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

請注意，更改也會反映在錯誤訊息和幫助字串中。

現在，讓我們使用另一種常見方法來玩玩訊息詳細級別。它也與 CPython 執行檔處理其自身訊息詳細級別引數的方式相符（請見 @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

我們已經介紹過另一個操作 "count" 用來計算指定的選項出現的次數。

@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 
是的，現在它更像是我們上一版腳本中的旗標（類似於 @code{action="store_true"}），這應該可以解釋抱怨的原因。

@item 
它的行為也類似 "store_true" 操作。

@item 
現在這裡示範了 "count" 動作的作用。你可能以前見過這種用法。

@item 
如果你不指定 @code{-v} 旗標，則該旗標被視為具有 @code{None} 值。

@item 
正如預期的那樣，指定長形式旗標，我們應該得到相同的輸出。

@item 
遺憾的是，我們的幫助輸出對於我們腳本獲得的新功能並沒有提供太多資訊，但我們都可以透過改進腳本的文件來解決這個問題（例如：透過 @code{help} 關鍵字引數）。

@item 
最後的輸出透露了我們程式中的一個錯誤。
@end itemize

讓我們來解決問題：

@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

這就是它給出的：

@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 
第一次輸出順利進行，並修復了我們之前遇到的錯誤。也就是說，我們希望任何 >= 2 的值都盡可能詳細。

@item 
第三個輸出不太好。
@end itemize

我們來修復這個錯誤：

@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

我們剛剛引入了另一個關鍵字 @code{default}。我們將其設為 @code{0}，以便使其與其他 int 值進行比較。請記住，預設情況下，如果未指定可選引數，它將獲得 @code{None} 值，並且不能與 int 值進行比較（因此會出現 @ref{198,,TypeError} 例外）。

而且：

@example
$ python prog.py 4
16
@end example

僅憑我們迄今為止所學到的知識就可以做到很多事情了，不過其實這樣只有學到一點皮毛而已。@ref{7,,argparse} 模組非常強大，在結束本教學之前我們會對它進行更多探索。

@node 更進階一點,如何翻譯 argparse 輸出,組合位置引數和可選引數,Argparse 教學
@anchor{howto/argparse getting-a-little-more-advanced}@anchor{327c}
@subsubsection 更進階一點


如果我們想擴充我們的小程式來執行其他次方的運算，而不僅是平方：

@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

結果：

@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

請注意，到目前為止，我們一直在使用詳細級別來`更改'顯示的文字。以下範例使用詳細級別來顯示`更多'文字：

@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

結果：

@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
* 指定不明確的引數:: 
* 相互衝突的選項:: 

@end menu

@node 指定不明確的引數,相互衝突的選項,,更進階一點
@anchor{howto/argparse id2}@anchor{327d}@anchor{howto/argparse specifying-ambiguous-arguments}@anchor{3247}
@subsubsection 指定不明確的引數


當決定一個引數是位置引數還是引數會有歧義，可以使用 @code{--} 來告訴 @ref{3222,,parse_args()} 之後的所有內容都是位置引數：

@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 相互衝突的選項,,指定不明確的引數,更進階一點
@anchor{howto/argparse conflicting-options}@anchor{327e}
@subsubsection 相互衝突的選項


到目前為止，我們一直在使用 @ref{1bd,,argparse.ArgumentParser} 實例的兩種方法。讓我們介紹第三個，@ref{2ec,,add_mutually_exclusive_group()}，它允許我們指定彼此衝突的選項。我們還可以更改程式的其餘部分，以使得新功能更有意義：我們將引入 @code{--quiet} 選項，該選項與 @code{--verbose} 選項相反：

@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

我們的程式現在更簡單了，我們因為功能展示失去了一些功能，但無論如何，以下這是輸出：

@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

這應該很容易理解。我新增了最後一個輸出，以便看到所獲得的靈活性，即可以混合長形式與短形式選項。

在我們結束之前，你可能想告訴使用者你的程式的主要目的，以防他們不知道：

@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

請注意用法文字中的細微差別。注意 @code{[-v | -q]}，它告訴我們可以使用 @code{-v} 或 @code{-q}，但不能同時使用：

@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 如何翻譯 argparse 輸出,自定義型別轉換器,更進階一點,Argparse 教學
@anchor{howto/argparse how-to-translate-the-argparse-output}@anchor{327f}
@subsubsection 如何翻譯 argparse 輸出


@ref{7,,argparse} 模組的輸出，例如幫助文字和錯誤訊息，都可以透過使用 @ref{67,,gettext} 模組進行翻譯。這允許應用程式能輕鬆本地化 @ref{7,,argparse} 生成的訊息。另請參閱 @ref{3280,,Internationalizing your programs and modules}。

例如，在此 @ref{7,,argparse} 輸出中：

@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

字串 @code{usage:}、@code{positional arguments:}、@code{options:} 和 @code{show this help message and exit} 都是可被翻譯的。

為了翻譯這些字串，必須先將它們提取到 @code{.po} 檔案中。例如，使用 Babel@footnote{https://babel.pocoo.org/} 並執行下列命令：

@example
$ pybabel extract -o messages.po /usr/lib/python3.12/argparse.py
@end example

此命令將從 @ref{7,,argparse} 模組中提取出所有可翻譯的字串，並將它們輸出到名為 @code{messages.po} 的檔案中。這個指令假設你的 Python 是安裝在 @code{/usr/lib} 中。

你可以使用以下腳本找到 @ref{7,,argparse} 模組在系統上的位置：

@example
import argparse
print(argparse.__file__)
@end example

一旦翻譯了 @code{.po} 檔案中的訊息並使用 @ref{67,,gettext} 安裝了翻譯，@ref{7,,argparse} 將能夠顯示翻譯後的訊息。

若要在 @ref{7,,argparse} 輸出中翻譯你自己的字串，請使用 @ref{67,,gettext}。

@node 自定義型別轉換器,結論,如何翻譯 argparse 輸出,Argparse 教學
@anchor{howto/argparse custom-type-converters}@anchor{3281}
@subsubsection 自定義型別轉換器


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{3223,,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

結果：

@example
$ python prog.py -a value1 +a value2
Namespace(a=[('-', 'value1'), ('+', 'value2')])
@end example

在這個範例當中，我們：


@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 結論,,自定義型別轉換器,Argparse 教學
@anchor{howto/argparse conclusion}@anchor{3282}
@subsubsection 結論


@ref{7,,argparse} 模組提供的功能比此篇內容的要多得多。它的文件非常詳細與透徹並有很多範例。讀完本教學後，你應該可以輕鬆消化它們，而不會感到不知所措。

@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{13af}
@node 將 optparse 程式碼遷移到 argparse,,Argparse 教學,例外<9>
@anchor{howto/argparse-optparse doc}@anchor{3283}@anchor{howto/argparse-optparse migrating-optparse-code}@anchor{3284}@anchor{howto/argparse-optparse migrating-optparse-code-to-argparse}@anchor{3285}@anchor{howto/argparse-optparse translation-repo}@anchor{3286}
@subsubsection 將 @code{optparse} 程式碼遷移到 @code{argparse}


@ref{7,,argparse} 模組提供了一些高階功能，這些功能在 @ref{a4,,optparse} 模組中並未原生提供，包括：


@itemize *

@item 
處理位置引數。

@item 
支援子命令。

@item 
允許替代選項前綴，如 @code{+} 和 @code{/}。

@item 
處理零或多個 (zero-or-more) 和一個或多個 (and one-or-more) 樣式的引數。

@item 
產生更多資訊的使用訊息。

@item 
為自訂 @code{type} 和 @code{action} 提供了一個更簡單的介面。
@end itemize

最初 @ref{7,,argparse} 模組試圖保持與 @ref{a4,,optparse} 的相容性，但在基礎設計上的存在差異 -- 支援宣告式 (declarative) 命令列選項處理 (同時將位置引數處理留給應用程式的程式碼) 和在宣告式介面中支援命名選項 (named options) 和位置引數 -- 代表 API 隨著時間的推移已經與 @code{optparse} API 分歧。

如 @ref{3220,,選擇一個命令列參數剖析函式庫} 中所述，目前使用 @ref{a4,,optparse} 並對其運作方式滿意的應用程式可以繼續使用 @code{optparse}。

在決定是否遷移之前，應用程式開發人員應該先檢閱該段落中描述的內在行為差異清單，來決定是否值得遷移。

對於選擇從 @ref{a4,,optparse} 遷移到 @ref{7,,argparse} 的應用程式，以下建議應會有所幫助：


@itemize *

@item 
將所有 @ref{3287,,optparse.OptionParser.add_option()} 呼叫替換為 @ref{4b7,,ArgumentParser.add_argument()} 呼叫。

@item 
將 @code{(options, args) = parser.parse_args()} 替換為 @code{args = parser.parse_args()}，並為位置引數新增額外的 @ref{4b7,,ArgumentParser.add_argument()} 呼叫。請記住，以前稱為 @code{options} 的東西，在 @ref{7,,argparse} 情境中現在稱為 @code{args}。

@item 
使用 @ref{cef,,parse_intermixed_args()} 來替換掉 @ref{3288,,optparse.OptionParser.disable_interspersed_args()}，而不是使用 @ref{3222,,parse_args()}。

@item 
將回呼動作和 @code{callback_*} 關鍵字引數替換為 @code{type} 或 @code{action} 引數。

@item 
將 @code{type} 關鍵字引數的字串名稱替換為相應的類型物件 (例如 int、float、complex 等)。

@item 
將 @ref{3289,,optparse.Values} 替換為 @ref{3223,,Namespace}，並將 @ref{328a,,optparse.OptionError} 和 @ref{328b,,optparse.OptionValueError} 替換為 @ref{3273,,ArgumentError}。

@item 
將隱式引數的字串，如 @code{%default} 或 @code{%prog} 替換為使用字典來格式化字串的標準 Python 語法，即 @code{%(default)s} 和 @code{%(prog)s}。

@item 
將 OptionParser 建構函式的 @code{version} 引數替換為呼叫 @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 --- 命令列選項剖析器,getpass --- 可攜式密碼輸入工具,argparse --- 命令列選項、引數和子命令的剖析器,命令列介面函式庫
@anchor{library/optparse doc}@anchor{328c}@anchor{library/optparse module-optparse}@anchor{a4}@anchor{library/optparse optparse-parser-for-command-line-options}@anchor{328d}@anchor{library/optparse translation-repo}@anchor{328e}
@subsection @code{optparse} --- 命令列選項剖析器


@geindex module; optparse

`原始碼：'Lib/optparse.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/optparse.py}


__________________________________________________________________


@menu
* 選擇一個命令列參數剖析函式庫:: 
* Introduction:: 
* 背景:: 
* 教學: 教學<2>. 
* Reference Guide:: 
* Option Callbacks:: 
* Extending optparse:: 
* 例外: 例外<10>. 

@end menu

@node 選擇一個命令列參數剖析函式庫,Introduction,,optparse --- 命令列選項剖析器
@anchor{library/optparse choosing-an-argument-parser}@anchor{3220}@anchor{library/optparse choosing-an-argument-parsing-library}@anchor{328f}
@subsubsection 選擇一個命令列參數剖析函式庫


標準函式庫包含三個命令列引數剖析函式庫：


@itemize *

@item 
@ref{65,,getopt}: a module that closely mirrors the procedural C @code{getopt} API.
Included in the standard library since before the initial Python 1.0 release.

@item 
@ref{a4,,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{65,,getopt} is retained almost entirely for backwards compatibility reasons.
However, it also serves a niche use case as a tool for prototyping and testing
command line argument handling in @code{getopt}-based C applications.

@ref{a4,,optparse} should be considered as an alternative to @ref{7,,argparse} in the
following cases:


@itemize *

@item 
an application is already using @ref{a4,,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 @ref{a4,,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,背景,選擇一個命令列參數剖析函式庫,optparse --- 命令列選項剖析器
@anchor{library/optparse introduction}@anchor{3290}
@subsubsection Introduction


@ref{a4,,optparse} is a more convenient, flexible, and powerful library for parsing
command-line options than the minimalist @ref{65,,getopt} module.
@ref{a4,,optparse} uses a more declarative style of command-line parsing:
you create an instance of @ref{16c1,,OptionParser},
populate it with options, and parse the command line.
@ref{a4,,optparse} allows users to specify options in the conventional
GNU/POSIX syntax, and additionally generates usage and help messages for you.

Here's an example of using @ref{a4,,optparse} in a simple script:

@example
from optparse import OptionParser
...
parser = OptionParser()
parser.add_option("-f", "--file", dest="filename",
                  help="write report to FILE", metavar="FILE")
parser.add_option("-q", "--quiet",
                  action="store_false", dest="verbose", default=True,
                  help="don't print status messages to stdout")

(options, args) = parser.parse_args()
@end example

With these few lines of code, users of your script can now do the "usual thing"
on the command-line, for example:

@example
<yourscript> --file=outfile -q
@end example

As it parses the command line, @ref{a4,,optparse} sets attributes of the
@code{options} object returned by @ref{16c2,,parse_args()} based on user-supplied
command-line values.  When @ref{16c2,,parse_args()} returns from parsing this command
line, @code{options.filename} will be @code{"outfile"} and @code{options.verbose} will be
@code{False}.  @ref{a4,,optparse} supports both long and short options, allows short
options to be merged together, and allows options to be associated with their
arguments in a variety of ways.  Thus, the following command lines are all
equivalent to the above example:

@example
<yourscript> -f outfile --quiet
<yourscript> --quiet --file outfile
<yourscript> -q -foutfile
<yourscript> -qfoutfile
@end example

Additionally, users can run one of the following

@example
<yourscript> -h
<yourscript> --help
@end example

and @ref{a4,,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 背景,教學<2>,Introduction,optparse --- 命令列選項剖析器
@anchor{library/optparse background}@anchor{3291}@anchor{library/optparse optparse-background}@anchor{3292}
@subsubsection 背景


@ref{a4,,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
* 術語:: 
* What are options for?:: 
* What are positional arguments for?:: 

@end menu

@node 術語,What are options for?,,背景
@anchor{library/optparse optparse-terminology}@anchor{3293}@anchor{library/optparse terminology}@anchor{3294}
@subsubsection 術語



@table @asis

@item 引數

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 選項

an argument used to supply extra information to guide or customize the
execution of a program.  There are many different syntaxes for options; the
traditional Unix syntax is a hyphen ("-") followed by a single letter,
e.g. @code{-x} or @code{-F}.  Also, traditional Unix syntax allows multiple
options to be merged into a single argument, e.g. @code{-x -F} is equivalent
to @code{-xF}.  The GNU project introduced @code{--} followed by a series of
hyphen-separated words, e.g. @code{--file} or @code{--dry-run}.  These are the
only two option syntaxes provided by @ref{a4,,optparse}.

Some other option syntaxes that the world has seen include:


@itemize *

@item 
a hyphen followed by a few letters, e.g. @code{-pf} (this is `not' the same
as multiple options merged into a single argument)

@item 
a hyphen followed by a whole word, e.g. @code{-file} (this is technically
equivalent to the previous syntax, but they aren't usually seen in the same
program)

@item 
a plus sign followed by a single letter, or a few letters, or a word, e.g.
@code{+f}, @code{+rgb}

@item 
a slash followed by a letter, or a few letters, or a word, e.g. @code{/f},
@code{/file}
@end itemize

These option syntaxes are not supported by @ref{a4,,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 選項引數

an argument that follows an option, is closely associated with that option,
and is consumed from the argument list when that option is. With
@ref{a4,,optparse}, option arguments may either be in a separate argument from
their option:

@example
-f foo
--file foo
@end example

or included in the same argument:

@example
-ffoo
--file=foo
@end example

Typically, a given option either takes an argument or it doesn't. Lots of
people want an "optional option arguments" feature, meaning that some options
will take an argument if they see it, and won't if they don't.  This is
somewhat controversial, because it makes parsing ambiguous: if @code{-a} takes
an optional argument and @code{-b} is another option entirely, how do we
interpret @code{-ab}?  Because of this ambiguity, @ref{a4,,optparse} does not
support this feature.

@item 位置引數

something leftover in the argument list after options have been parsed, i.e.
after options and their arguments have been parsed and removed from the
argument list.

@item required option

an option that must be supplied on the command-line; note that the phrase
"required option" is self-contradictory in English.  @ref{a4,,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?,術語,背景
@anchor{library/optparse optparse-what-options-for}@anchor{3295}@anchor{library/optparse what-are-options-for}@anchor{3296}
@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?,背景
@anchor{library/optparse optparse-what-positional-arguments-for}@anchor{3297}@anchor{library/optparse what-are-positional-arguments-for}@anchor{3298}
@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 教學<2>,Reference Guide,背景,optparse --- 命令列選項剖析器
@anchor{library/optparse optparse-tutorial}@anchor{3299}@anchor{library/optparse tutorial}@anchor{329a}
@subsubsection 教學


While @ref{a4,,optparse} is quite flexible and powerful, it's also straightforward
to use in most cases.  This section covers the code patterns that are common to
any @ref{a4,,optparse}-based program.

First, you need to import the OptionParser class; then, early in the main
program, create an OptionParser instance:

@example
from optparse import OptionParser
...
parser = OptionParser()
@end example

Then you can start defining options.  The basic syntax is:

@example
parser.add_option(opt_str, ...,
                  attr=value, ...)
@end example

Each option has one or more option strings, such as @code{-f} or @code{--file},
and several option attributes that tell @ref{a4,,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{3287,,OptionParser.add_option()} are effectively
labels for the
option defined by that call.  For brevity, we will frequently refer to
`encountering an option' on the command line; in reality, @ref{a4,,optparse}
encounters `option strings' and looks up options from them.

Once all of your options are defined, instruct @ref{a4,,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{16c2,,parse_args()}, but
that's rarely necessary: by default it uses @code{sys.argv[1:]}.)

@ref{16c2,,parse_args()} 回傳兩個值：


@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{329b,,action}, @ref{329c,,type}, @ref{329d,,dest}
(destination), and @ref{329e,,help}. Of these, @ref{329b,,action} is the
most fundamental.

@menu
* Understanding option actions:: 
* The store action:: 
* Handling boolean (flag) options: Handling boolean flag options. 
* Other actions:: 
* 預設值:: 
* Generating help:: 
* Printing a version string:: 
* How optparse handles errors:: 
* Putting it all together:: 

@end menu

@node Understanding option actions,The store action,,教學<2>
@anchor{library/optparse optparse-understanding-option-actions}@anchor{329f}@anchor{library/optparse understanding-option-actions}@anchor{32a0}
@subsubsection Understanding option actions


Actions tell @ref{a4,,optparse} what to do when it encounters an option on the
command line.  There is a fixed set of actions hard-coded into @ref{a4,,optparse};
adding new actions is an advanced topic covered in section
@ref{32a1,,Extending optparse}.  Most actions tell @ref{a4,,optparse} to store
a value in some variable---for example, take a string from the command line and
store it in an attribute of @code{options}.

If you don't specify an option action, @ref{a4,,optparse} defaults to @code{store}.

@node The store action,Handling boolean flag options,Understanding option actions,教學<2>
@anchor{library/optparse optparse-store-action}@anchor{32a2}@anchor{library/optparse the-store-action}@anchor{32a3}
@subsubsection The store action


The most common option action is @code{store}, which tells @ref{a4,,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.

舉例來說：

@example
parser.add_option("-f", "--file",
                  action="store", type="string", dest="filename")
@end example

Now let's make up a fake command line and ask @ref{a4,,optparse} to parse it:

@example
args = ["-f", "foo.txt"]
(options, args) = parser.parse_args(args)
@end example

When @ref{a4,,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{16c2,,parse_args()}, @code{options.filename} is @code{"foo.txt"}.

Some other option types supported by @ref{a4,,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

會印出 @code{42}。

If you don't specify a type, @ref{a4,,optparse} assumes @code{string}.  Combined with
the fact that the default action is @code{store}, that means our first example can
be a lot shorter:

@example
parser.add_option("-f", "--file", dest="filename")
@end example

If you don't supply a destination, @ref{a4,,optparse} figures out a sensible
default from the option strings: if the first long option string is
@code{--foo-bar}, then the default destination is @code{foo_bar}.  If there are no
long option strings, @ref{a4,,optparse} looks at the first short option string: the
default destination for @code{-f} is @code{f}.

@ref{a4,,optparse} also includes the built-in @code{complex} type.  Adding
types is covered in section @ref{32a1,,Extending optparse}.

@node Handling boolean flag options,Other actions,The store action,教學<2>
@anchor{library/optparse handling-boolean-flag-options}@anchor{32a4}@anchor{library/optparse optparse-handling-boolean-options}@anchor{32a5}
@subsubsection Handling boolean (flag) options


Flag options---set a variable to true or false when a particular option is
seen---are quite common.  @ref{a4,,optparse} supports them with two separate actions,
@code{store_true} and @code{store_false}.  For example, you might have a @code{verbose}
flag that is turned on with @code{-v} and off with @code{-q}:

@example
parser.add_option("-v", action="store_true", dest="verbose")
parser.add_option("-q", action="store_false", dest="verbose")
@end example

Here we have two different options with the same destination, which is perfectly
OK.  (It just means you have to be a bit careful when setting default
values---see below.)

When @ref{a4,,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,預設值,Handling boolean flag options,教學<2>
@anchor{library/optparse optparse-other-actions}@anchor{32a6}@anchor{library/optparse other-actions}@anchor{32a7}
@subsubsection Other actions


Some other actions supported by @ref{a4,,optparse} are:


@table @asis

@item @code{"store_const"}

store a constant value, pre-set via @ref{32a8,,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{32a9,,Reference Guide},
and section @ref{32aa,,Option Callbacks}.

@node 預設值,Generating help,Other actions,教學<2>
@anchor{library/optparse default-values}@anchor{32ab}@anchor{library/optparse optparse-default-values}@anchor{32ac}
@subsubsection 預設值


All of the above examples involve setting some variable (the "destination") when
certain command-line options are seen.  What happens if those options are never
seen?  Since we didn't supply any defaults, they are all set to @code{None}.  This
is usually fine, but sometimes you want more control.  @ref{a4,,optparse} lets you
supply a default value for each destination, which is assigned before the
command line is parsed.

First, consider the verbose/quiet example.  If we want @ref{a4,,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{16c2,,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,預設值,教學<2>
@anchor{library/optparse generating-help}@anchor{32ad}@anchor{library/optparse optparse-generating-help}@anchor{32ae}
@subsubsection Generating help


@ref{a4,,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{329e,,help} value for each option, and optionally a short
usage message for your whole program.  Here's an OptionParser populated with
user-friendly (documented) options:

@example
usage = "usage: %prog [options] arg1 arg2"
parser = OptionParser(usage=usage)
parser.add_option("-v", "--verbose",
                  action="store_true", dest="verbose", default=True,
                  help="make lots of noise [default]")
parser.add_option("-q", "--quiet",
                  action="store_false", dest="verbose",
                  help="be vewwy quiet (I'm hunting wabbits)")
parser.add_option("-f", "--filename",
                  metavar="FILE", help="write output to FILE")
parser.add_option("-m", "--mode",
                  default="intermediate",
                  help="interaction mode: novice, intermediate, "
                       "or expert [default: %default]")
@end example

If @ref{a4,,optparse} encounters either @code{-h} or @code{--help} on the
command-line, or if you just call @code{parser.print_help()}, it prints the
following to standard output:

@example
Usage: <yourscript> [options] arg1 arg2

Options:
  -h, --help            show this help message and exit
  -v, --verbose         make lots of noise [default]
  -q, --quiet           be vewwy quiet (I'm hunting wabbits)
  -f FILE, --filename=FILE
                        write output to FILE
  -m MODE, --mode=MODE  interaction mode: novice, intermediate, or
                        expert [default: intermediate]
@end example

(If the help output is triggered by a help option, @ref{a4,,optparse} exits after
printing the help text.)

There's a lot going on here to help @ref{a4,,optparse} generate the best possible
help message:


@itemize *

@item 
the script defines its own usage message:

@example
usage = "usage: %prog [options] arg1 arg2"
@end example

@ref{a4,,optparse} expands @code{%prog} in the usage string to the name of the
current program, i.e. @code{os.path.basename(sys.argv[0])}.  The expanded string
is then printed before the detailed option help.

If you don't supply a usage string, @ref{a4,,optparse} uses a bland but sensible
default: @code{"Usage: %prog [options]"}, which is fine if your script doesn't
take any positional arguments.

@item 
every option defines a help string, and doesn't worry about
line-wrapping---@ref{a4,,optparse} takes care of wrapping lines and making
the help output look good.

@item 
options that take a value indicate this fact in their automatically generated
help message, e.g. for the "mode" option:

@example
-m MODE, --mode=MODE
@end example

Here, "MODE" is called the meta-variable: it stands for the argument that the
user is expected to supply to @code{-m}/@code{--mode}.  By default,
@ref{a4,,optparse} converts the destination variable name to uppercase and uses
that for the meta-variable.  Sometimes, that's not what you want---for
example, the @code{--filename} option explicitly sets @code{metavar="FILE"},
resulting in this automatically generated option description:

@example
-f FILE, --filename=FILE
@end example

This is important for more than just saving space, though: the manually
written help text uses the meta-variable @code{FILE} to clue the user in that
there's a connection between the semi-formal syntax @code{-f FILE} and the informal
semantic description "write output to FILE". This is a simple but effective
way to make your help text a lot clearer and more useful for end users.

@item 
options that have a default value can include @code{%default} in the help
string---@ref{a4,,optparse} will replace it with @ref{169,,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{32af}
@subsubsection Grouping Options


When dealing with many options, it is convenient to group these options for
better help output.  An @ref{16c1,,OptionParser} can contain several option groups,
each of which can contain several options.

An option group is obtained using the class @ref{32b0,,OptionGroup}:

@geindex OptionGroup (optparse 中的類別)
@anchor{library/optparse optparse OptionGroup}@anchor{32b0}
@deffn {類別} optparse.OptionGroup (parser, title, description=None)

where


@itemize *

@item 
parser is the @ref{16c1,,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{32b0,,OptionGroup} inherits from @code{OptionContainer} (like
@ref{16c1,,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{16c1,,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{32b0,,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{32b1}
@deffn {方法} OptionParser.get_option_group (opt_str)

Return the @ref{32b0,,OptionGroup} to which the short or long option
string `opt_str' (e.g. @code{'-o'} or @code{'--option'}) belongs. If
there's no such @ref{32b0,,OptionGroup}, return @code{None}.
@end deffn

@node Printing a version string,How optparse handles errors,Generating help,教學<2>
@anchor{library/optparse optparse-printing-version-string}@anchor{32b2}@anchor{library/optparse printing-a-version-string}@anchor{32b3}
@subsubsection Printing a version string


Similar to the brief usage string, @ref{a4,,optparse} can also print a version
string for your program.  You have to supply the string as the @code{version}
argument to OptionParser:

@example
parser = OptionParser(usage="%prog [-f] [-q]", version="%prog 1.0")
@end example

@code{%prog} is expanded just like it is in @code{usage}.  Apart from that,
@code{version} can contain anything you like.  When you supply it, @ref{a4,,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{32b4}
@deffn {方法} OptionParser.print_version (file=None)

Print the version message for the current program (@code{self.version}) to
`file' (default stdout).  As with @ref{32b5,,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{32b6}
@deffn {方法} OptionParser.get_version ()

Same as @ref{32b4,,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,教學<2>
@anchor{library/optparse how-optparse-handles-errors}@anchor{32b7}@anchor{library/optparse optparse-how-optparse-handles-errors}@anchor{32b8}
@subsubsection How @code{optparse} handles errors


There are two broad classes of errors that @ref{a4,,optparse} has to worry about:
programmer errors and user errors.  Programmer errors are usually erroneous
calls to @ref{3287,,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{328a,,optparse.OptionError} or
@ref{198,,TypeError}) and let the program crash.

Handling user errors is much more important, since they are guaranteed to happen
no matter how stable your code is.  @ref{a4,,optparse} can automatically detect
some user errors, such as bad option arguments (passing @code{-n 4x} where
@code{-n} takes an integer argument), missing arguments (@code{-n} at the end
of the command line, where @code{-n} takes an argument of any type).  Also,
you can call @code{OptionParser.error()} to signal an application-defined error
condition:

@example
(options, args) = parser.parse_args()
...
if options.a and options.b:
    parser.error("options -a and -b are mutually exclusive")
@end example

In either case, @ref{a4,,optparse} handles the error the same way: it prints the
program's usage message and an error message to standard error and exits with
error status 2.

Consider the first example above, where the user passes @code{4x} to an option
that takes an integer:

@example
$ /usr/bin/foo -n 4x
Usage: foo [options]

foo: error: option -n: invalid integer value: '4x'
@end example

Or, where the user fails to pass a value at all:

@example
$ /usr/bin/foo -n
Usage: foo [options]

foo: error: -n option requires an argument
@end example

@ref{a4,,optparse}-generated error messages take care always to mention the
option involved in the error; be sure to do the same when calling
@code{OptionParser.error()} from your application code.

If @ref{a4,,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,教學<2>
@anchor{library/optparse optparse-putting-it-all-together}@anchor{32b9}@anchor{library/optparse putting-it-all-together}@anchor{32ba}
@subsubsection Putting it all together


Here's what @ref{a4,,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,教學<2>,optparse --- 命令列選項剖析器
@anchor{library/optparse optparse-reference-guide}@anchor{32a9}@anchor{library/optparse reference-guide}@anchor{32bb}
@subsubsection Reference Guide


@menu
* 建立剖析器:: 
* Populating the parser:: 
* 定義選項:: 
* 選項屬性:: 
* 標準選項動作:: 
* Standard option types:: 
* 剖析引數:: 
* Querying and manipulating your option parser:: 
* Conflicts between options:: 
* Cleanup:: 
* 其他方法:: 

@end menu

@node 建立剖析器,Populating the parser,,Reference Guide
@anchor{library/optparse creating-the-parser}@anchor{32bc}@anchor{library/optparse optparse-creating-parser}@anchor{32bd}
@subsubsection 建立剖析器


The first step in using @ref{a4,,optparse} is to create an OptionParser instance.

@geindex OptionParser (optparse 中的類別)
@anchor{library/optparse optparse OptionParser}@anchor{16c1}
@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}（預設值：@code{"%prog [options]"}）

The usage summary to print when your program is run incorrectly or with a
help option.  When @ref{a4,,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}（預設值：@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{3287,,add_option()} after
creating the parser instead.

@item @code{option_class}（預設值：optparse.Option）

在 @ref{3287,,add_option()} 中新增選項時要使用的類別。

@item @code{version}（預設值：@code{None}）

A version string to print when the user supplies a version option. If you
supply a true value for @code{version}, @ref{a4,,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}（預設值：@code{"error"}）

Specifies what to do when options with conflicting option strings are
added to the parser; see section
@ref{32be,,Conflicts between options}.

@item @code{description}（預設值：@code{None}）

A paragraph of text giving a brief overview of your program.
@ref{a4,,optparse} reformats this paragraph to fit the current terminal width
and prints it when the user requests help (after @code{usage}, but before the
list of options).

@item @code{formatter} (default: a new @code{IndentedHelpFormatter})

An instance of optparse.HelpFormatter that will be used for printing help
text.  @ref{a4,,optparse} provides two concrete classes for this purpose:
IndentedHelpFormatter and TitledHelpFormatter.

@item @code{add_help_option}（預設值：@code{True}）

If true, @ref{a4,,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}（預設值：@code{None}）

A paragraph of help text to print after the option help.
@end table
@end deffn

@node Populating the parser,定義選項,建立剖析器,Reference Guide
@anchor{library/optparse optparse-populating-parser}@anchor{32bf}@anchor{library/optparse populating-the-parser}@anchor{32c0}
@subsubsection Populating the parser


There are several ways to populate the parser with options.  The preferred way
is by using @ref{3287,,OptionParser.add_option()}, as shown in section
@ref{3299,,教學}.  @code{add_option()} can be called in one of two ways:


@itemize *

@item 
pass it an Option instance (as returned by @code{make_option()})

@item 
pass it any combination of positional and keyword arguments that are
acceptable to @code{make_option()} (i.e., to the Option constructor), and it
will create the Option instance for you
@end itemize

The other alternative is to pass a list of pre-constructed Option instances to
the OptionParser constructor, as in:

@example
option_list = [
    make_option("-f", "--filename",
                action="store", type="string", dest="filename"),
    make_option("-q", "--quiet",
                action="store_false", dest="verbose"),
    ]
parser = OptionParser(option_list=option_list)
@end example

(@code{make_option()} is a factory function for creating Option instances;
currently it is an alias for the Option constructor.  A future version of
@ref{a4,,optparse} may split Option into several classes, and @code{make_option()}
will pick the right class to instantiate.  Do not instantiate Option directly.)

@node 定義選項,選項屬性,Populating the parser,Reference Guide
@anchor{library/optparse defining-options}@anchor{32c1}@anchor{library/optparse optparse-defining-options}@anchor{32c2}
@subsubsection 定義選項


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{32c3,,Option} instance is with the
@code{add_option()} method of @ref{16c1,,OptionParser}.

@geindex add_option() (optparse.OptionParser 的方法)
@anchor{library/optparse optparse OptionParser add_option}@anchor{3287}
@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{329b,,action}, and it largely
determines which other attributes are relevant or required.  If you pass
irrelevant option attributes, or fail to pass required ones, @ref{a4,,optparse}
raises an @ref{328a,,OptionError} exception explaining your mistake.

An option's `action' determines what @ref{a4,,optparse} does when it encounters
this option on the command-line.  The standard option actions hard-coded into
@ref{a4,,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{32a8,,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{32a8,,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{329c,,type} and @ref{329d,,dest} option
attributes; see @ref{32c4,,標準選項動作}.)
@end deffn

As you can see, most actions involve storing or updating a value somewhere.
@ref{a4,,optparse} always creates a special object for this, conventionally called
@code{options}, which is an instance of @ref{3289,,optparse.Values}.

@geindex Values (optparse 中的類別)
@anchor{library/optparse optparse Values}@anchor{3289}
@deffn {類別} optparse.Values

An object holding parsed argument names and values as attributes.
Normally created by calling when calling @ref{16c2,,OptionParser.parse_args()},
and can be overridden by a custom subclass passed to the `values' argument of
@ref{16c2,,OptionParser.parse_args()} (as described in @ref{32c5,,剖析引數}).
@end deffn

Option
arguments (and various other values) are stored as attributes of this object,
according to the @ref{329d,,dest} (destination) option attribute.

例如說，當你呼叫：

@example
parser.parse_args()
@end example

one of the first things @ref{a4,,optparse} does is create the @code{options} object:

@example
options = Values()
@end example

If one of the options in this parser is defined with

@example
parser.add_option("-f", "--file", action="store", type="string", dest="filename")
@end example

and the command-line being parsed includes any of the following:

@example
-ffoo
-f foo
--file=foo
--file foo
@end example

then @ref{a4,,optparse}, on seeing this option, will do the equivalent of

@example
options.filename = "foo"
@end example

The @ref{329c,,type} and @ref{329d,,dest} option attributes are almost
as important as @ref{329b,,action}, but @ref{329b,,action} is the only
one that makes sense for `all' options.

@node 選項屬性,標準選項動作,定義選項,Reference Guide
@anchor{library/optparse option-attributes}@anchor{32c6}@anchor{library/optparse optparse-option-attributes}@anchor{32c7}
@subsubsection 選項屬性


@geindex Option (optparse 中的類別)
@anchor{library/optparse optparse Option}@anchor{32c3}
@deffn {類別} optparse.Option

A single command line argument,
with various attributes passed by keyword to the constructor.
Normally created with @ref{3287,,OptionParser.add_option()} rather than directly,
and can be overridden by a custom class via the `option_class' argument
to @ref{16c1,,OptionParser}.
@end deffn

The following option attributes may be passed as keyword arguments to
@ref{3287,,OptionParser.add_option()}.  If you pass an option attribute that is not
relevant to a particular option, or fail to pass a required option attribute,
@ref{a4,,optparse} raises @ref{328a,,OptionError}.

@geindex action (optparse.Option 的屬性)
@anchor{library/optparse optparse Option action}@anchor{329b}
@deffn {屬性} Option.action

（預設值： @code{"store"} ）

Determines @ref{a4,,optparse}'s behaviour when this option is seen on the
command line; the available options are documented @ref{32c4,,here}.
@end deffn

@geindex type (optparse.Option 的屬性)
@anchor{library/optparse optparse Option type}@anchor{329c}
@deffn {屬性} Option.type

（預設值： @code{"string"} ）

The argument type expected by this option (e.g., @code{"string"} or @code{"int"});
the available option types are documented @ref{32c8,,here}.
@end deffn

@geindex dest (optparse.Option 的屬性)
@anchor{library/optparse optparse Option dest}@anchor{329d}
@deffn {屬性} Option.dest

(default: derived from option strings)

If the option's action implies writing or modifying a value somewhere, this
tells @ref{a4,,optparse} where to write it: @ref{329d,,dest} names an
attribute of the @code{options} object that @ref{a4,,optparse} builds as it parses
the command line.
@end deffn

@geindex default (optparse.Option 的屬性)
@anchor{library/optparse optparse Option default}@anchor{32c9}
@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{32ca,,OptionParser.set_defaults()}.
@end deffn

@geindex nargs (optparse.Option 的屬性)
@anchor{library/optparse optparse Option nargs}@anchor{32cb}
@deffn {屬性} Option.nargs

（預設值：1）

How many arguments of type @ref{329c,,type} should be consumed when this
option is seen.  If > 1, @ref{a4,,optparse} will store a tuple of values to
@ref{329d,,dest}.
@end deffn

@geindex const (optparse.Option 的屬性)
@anchor{library/optparse optparse Option const}@anchor{32a8}
@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{32cc}
@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{32cd}
@deffn {屬性} Option.callback

For options with action @code{"callback"}, the callable to call when this option
is seen.  See section @ref{32aa,,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{32ce}
@deffn {屬性} Option.callback_args
@anchor{library/optparse optparse Option callback_kwargs}@anchor{32cf}
@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{329e}
@deffn {屬性} Option.help

Help text to print for this option when listing all available options after
the user supplies a @ref{329e,,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{32d0}
@deffn {屬性} Option.metavar

(default: derived from option strings)

Stand-in for the option argument(s) to use when printing help text.  See
section @ref{3299,,教學} for an example.
@end deffn

@node 標準選項動作,Standard option types,選項屬性,Reference Guide
@anchor{library/optparse optparse-standard-option-actions}@anchor{32c4}@anchor{library/optparse standard-option-actions}@anchor{32d1}
@subsubsection 標準選項動作


The various option actions all have slightly different requirements and effects.
Most actions have several relevant option attributes which you may specify to
guide @ref{a4,,optparse}'s behaviour; a few have required attributes, which you
must specify for any option using that action.


@itemize *

@item 
@code{"store"} [relevant: @ref{329c,,type}, @ref{329d,,dest},
@ref{32cb,,nargs}, @ref{32cc,,choices}]

The option must be followed by an argument, which is converted to a value
according to @ref{329c,,type} and stored in @ref{329d,,dest}.  If
@ref{32cb,,nargs} > 1, multiple arguments will be consumed from the
command line; all will be converted according to @ref{329c,,type} and
stored to @ref{329d,,dest} as a tuple.  See the
@ref{32c8,,Standard option types} section.

If @ref{32cc,,choices} is supplied (a list or tuple of strings), the type
defaults to @code{"choice"}.

如果沒有提供 @ref{329c,,type}，它的預設值是 @code{"string"}。

If @ref{329d,,dest} is not supplied, @ref{a4,,optparse} derives a destination
from the first long option string (e.g., @code{--foo-bar} implies
@code{foo_bar}). If there are no long option strings, @ref{a4,,optparse} derives a
destination from the first short option string (e.g., @code{-f} implies @code{f}).

範例：

@example
parser.add_option("-f")
parser.add_option("-p", type="float", nargs=3, dest="point")
@end example

As it parses the command line

@example
-f foo.txt -p 1 -3.5 4 -fbar.txt
@end example

@ref{a4,,optparse} 將會設定：

@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{32a8,,const}; relevant:
@ref{329d,,dest}]

The value @ref{32a8,,const} is stored in @ref{329d,,dest}.

範例：

@example
parser.add_option("-q", "--quiet",
                  action="store_const", const=0, dest="verbose")
parser.add_option("-v", "--verbose",
                  action="store_const", const=1, dest="verbose")
parser.add_option("--noisy",
                  action="store_const", const=2, dest="verbose")
@end example

If @code{--noisy} is seen, @ref{a4,,optparse} will set

@example
options.verbose = 2
@end example

@item 
@code{"store_true"} [relevant: @ref{329d,,dest}]

A special case of @code{"store_const"} that stores @code{True} to
@ref{329d,,dest}.

@item 
@code{"store_false"} [relevant: @ref{329d,,dest}]

Like @code{"store_true"}, but stores @code{False}.

範例：

@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{329c,,type}, @ref{329d,,dest},
@ref{32cb,,nargs}, @ref{32cc,,choices}]

The option must be followed by an argument, which is appended to the list in
@ref{329d,,dest}.  If no default value for @ref{329d,,dest} is
supplied, an empty list is automatically created when @ref{a4,,optparse} first
encounters this option on the command-line.  If @ref{32cb,,nargs} > 1,
multiple arguments are consumed, and a tuple of length @ref{32cb,,nargs}
is appended to @ref{329d,,dest}.

The defaults for @ref{329c,,type} and @ref{329d,,dest} are the same as
for the @code{"store"} action.

範例：

@example
parser.add_option("-t", "--tracks", action="append", type="int")
@end example

If @code{-t3} is seen on the command-line, @ref{a4,,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{32a8,,const}; relevant:
@ref{329d,,dest}]

Like @code{"store_const"}, but the value @ref{32a8,,const} is appended to
@ref{329d,,dest}; as with @code{"append"}, @ref{329d,,dest} defaults to
@code{None}, and an empty list is automatically created the first time the option
is encountered.

@item 
@code{"count"} [relevant: @ref{329d,,dest}]

Increment the integer stored at @ref{329d,,dest}.  If no default value is
supplied, @ref{329d,,dest} is set to zero before being incremented the
first time.

範例：

@example
parser.add_option("-v", action="count", dest="verbosity")
@end example

The first time @code{-v} is seen on the command line, @ref{a4,,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{32cd,,callback}; relevant:
@ref{329c,,type}, @ref{32cb,,nargs}, @ref{32ce,,callback_args},
@ref{32cf,,callback_kwargs}]

Call the function specified by @ref{32cd,,callback}, which is called as

@example
func(option, opt_str, value, parser, *args, **kwargs)
@end example

更多細節請見 @ref{32aa,,Option Callbacks}。

@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{329e,,help} string passed to every
option.

If no @ref{329e,,help} string is supplied for an option, it will still be
listed in the help message.  To omit an option entirely, use the special value
@code{optparse.SUPPRESS_HELP}.

@ref{a4,,optparse} automatically adds a @ref{329e,,help} option to all
OptionParsers, so you do not normally need to create one.

範例：

@example
from optparse import OptionParser, SUPPRESS_HELP

# usually, a help option is added automatically, but that can
# be suppressed using the add_help_option argument
parser = OptionParser(add_help_option=False)

parser.add_option("-h", "--help", action="help")
parser.add_option("-v", action="store_true", dest="verbose",
                  help="Be moderately verbose")
parser.add_option("--file", dest="filename",
                  help="Input file to read data from")
parser.add_option("--secret", help=SUPPRESS_HELP)
@end example

If @ref{a4,,optparse} sees either @code{-h} or @code{--help} on the command line,
it will print something like the following help message to stdout (assuming
@code{sys.argv[0]} is @code{"foo.py"}):

@example
Usage: foo.py [options]

Options:
  -h, --help        Show this help message and exit
  -v                Be moderately verbose
  --file=FILENAME   Input file to read data from
@end example

After printing the help message, @ref{a4,,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{329e,,help} options, you will rarely create @code{version} options,
since @ref{a4,,optparse} automatically adds them when needed.
@end itemize

@node Standard option types,剖析引數,標準選項動作,Reference Guide
@anchor{library/optparse optparse-standard-option-types}@anchor{32c8}@anchor{library/optparse standard-option-types}@anchor{32d2}
@subsubsection Standard option types


@ref{a4,,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{32a1,,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{19b,,int()} with the appropriate base (2, 8,
10, or 16).  If this fails, so will @ref{a4,,optparse}, although with a more useful
error message.

@code{"float"} and @code{"complex"} option arguments are converted directly with
@ref{196,,float()} and @ref{197,,complex()}, with similar error-handling.

@code{"choice"} options are a subtype of @code{"string"} options.  The
@ref{32cc,,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{328b,,OptionValueError} if an invalid string is given.

@node 剖析引數,Querying and manipulating your option parser,Standard option types,Reference Guide
@anchor{library/optparse optparse-parsing-arguments}@anchor{32c5}@anchor{library/optparse parsing-arguments}@anchor{32d3}
@subsubsection 剖析引數


The whole point of creating and populating an OptionParser is to call its
@ref{16c2,,parse_args()} method.

@geindex parse_args() (optparse.OptionParser 的方法)
@anchor{library/optparse optparse OptionParser parse_args}@anchor{16c2}
@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{3289,,Values} object to store option arguments in (default: a
new instance of @ref{3289,,Values}) -- if you give an existing object, the
option defaults will not be initialized on it
@end table

and the return value is a pair @code{(options, args)} where


@table @asis

@item @code{options}

the same object that was passed in as `values', or the @code{optparse.Values}
instance created by @ref{a4,,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{2467,,setattr()} calls (roughly one
for every option argument stored to an option destination) and returned by
@ref{16c2,,parse_args()}.

If @ref{16c2,,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,剖析引數,Reference Guide
@anchor{library/optparse optparse-querying-manipulating-option-parser}@anchor{32d4}@anchor{library/optparse querying-and-manipulating-your-option-parser}@anchor{32d5}
@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{3288}
@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, @ref{a4,,optparse}
normally accepts this syntax:

@example
prog -a arg1 -b arg2
@end example

and treats it as equivalent to

@example
prog -a -b arg1 arg2
@end example

To disable this feature, call @ref{3288,,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{32d6}
@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{32d7}
@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{32d8}
@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{32d9}
@deffn {方法} OptionParser.remove_option (opt_str)

If the @ref{16c1,,OptionParser} has an option corresponding to `opt_str', that
option is removed.  If that option provided any other option strings, all of
those option strings become invalid. If `opt_str' does not occur in any
option belonging to this @ref{16c1,,OptionParser}, raises @ref{2eb,,ValueError}.
@end deffn

@node Conflicts between options,Cleanup,Querying and manipulating your option parser,Reference Guide
@anchor{library/optparse conflicts-between-options}@anchor{32da}@anchor{library/optparse optparse-conflicts-between-options}@anchor{32be}
@subsubsection Conflicts between options


If you're not careful, it's easy to define options with conflicting option
strings:

@example
parser.add_option("-n", "--dry-run", ...)
...
parser.add_option("-n", "--noisy", ...)
@end example

(This is particularly true if you've defined your own OptionParser subclass with
some standard options.)

Every time you add an option, @ref{a4,,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"} (預設值)

assume option conflicts are a programming error and raise
@ref{32db,,OptionConflictError}

@item @code{"resolve"}

resolve option conflicts intelligently (see below)
@end table
@end quotation

As an example, let's define an @ref{16c1,,OptionParser} that resolves conflicts
intelligently and add conflicting options to it:

@example
parser = OptionParser(conflict_handler="resolve")
parser.add_option("-n", "--dry-run", ..., help="do no harm")
parser.add_option("-n", "--noisy", ..., help="be noisy")
@end example

At this point, @ref{a4,,optparse} detects that a previously added option is already
using the @code{-n} option string.  Since @code{conflict_handler} is @code{"resolve"},
it resolves the situation by removing @code{-n} from the earlier option's list of
option strings.  Now @code{--dry-run} is the only way for the user to activate
that option.  If the user asks for help, the help message will reflect that:

@example
Options:
  --dry-run     do no harm
  ...
  -n, --noisy   be noisy
@end example

It's possible to whittle away the option strings for a previously added option
until there are none left, and the user has no way of invoking that option from
the command-line.  In that case, @ref{a4,,optparse} removes that option completely,
so it doesn't show up in help text or anywhere else. Carrying on with our
existing OptionParser:

@example
parser.add_option("--dry-run", ..., help="new dry-run option")
@end example

At this point, the original @code{-n}/@code{--dry-run} option is no longer
accessible, so @ref{a4,,optparse} removes it, leaving this help text:

@example
Options:
  ...
  -n, --noisy   be noisy
  --dry-run     new dry-run option
@end example

@node Cleanup,其他方法,Conflicts between options,Reference Guide
@anchor{library/optparse cleanup}@anchor{32dc}@anchor{library/optparse optparse-cleanup}@anchor{32dd}
@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 其他方法,,Cleanup,Reference Guide
@anchor{library/optparse optparse-other-methods}@anchor{32de}@anchor{library/optparse other-methods}@anchor{32df}
@subsubsection 其他方法


OptionParser supports several other public methods:

@geindex set_usage() (optparse.OptionParser 的方法)
@anchor{library/optparse optparse OptionParser set_usage}@anchor{32e0}
@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{32b5}
@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{32e1}
@deffn {方法} OptionParser.get_usage ()

Same as @ref{32b5,,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{32ca}
@deffn {方法} OptionParser.set_defaults (dest=value, ...)

Set default values for several option destinations at once.  Using
@ref{32ca,,set_defaults()} is the preferred way to set default values for options,
since multiple options can share the same destination.  For example, if
several "mode" options all set the same destination, any one of them can set
the default, and the last one wins:

@example
parser.add_option("--advanced", action="store_const",
                  dest="mode", const="advanced",
                  default="novice")    # overridden below
parser.add_option("--novice", action="store_const",
                  dest="mode", const="novice",
                  default="advanced")  # overrides above setting
@end example

To avoid this confusion, use @ref{32ca,,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 --- 命令列選項剖析器
@anchor{library/optparse option-callbacks}@anchor{32e2}@anchor{library/optparse optparse-option-callbacks}@anchor{32aa}
@subsubsection Option Callbacks


When @ref{a4,,optparse}'s built-in actions and types aren't quite enough for your
needs, you have two choices: extend @ref{a4,,optparse} or define a callback option.
Extending @ref{a4,,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{32e3}@anchor{library/optparse optparse-defining-callback-option}@anchor{32e4}
@subsubsection Defining a callback option


As always, the easiest way to define a callback option is by using the
@ref{3287,,OptionParser.add_option()} method.  Apart from @ref{329b,,action}, the
only option attribute you must specify is @code{callback}, the function to call:

@example
parser.add_option("-c", action="callback", callback=my_callback)
@end example

@code{callback} is a function (or other callable object), so you must have already
defined @code{my_callback()} when you create this callback option. In this simple
case, @ref{a4,,optparse} doesn't even know if @code{-c} takes any arguments,
which usually means that the option takes no arguments---the mere presence of
@code{-c} on the command-line is all it needs to know.  In some
circumstances, though, you might want your callback to consume an arbitrary
number of command-line arguments.  This is where writing callbacks gets tricky;
it's covered later in this section.

@ref{a4,,optparse} always passes four particular arguments to your callback, and it
will only pass additional arguments if you specify them via
@ref{32ce,,callback_args} and @ref{32cf,,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{329c,,type}

has its usual meaning: as with the @code{"store"} or @code{"append"} actions, it
instructs @ref{a4,,optparse} to consume one argument and convert it to
@ref{329c,,type}.  Rather than storing the converted value(s) anywhere,
though, @ref{a4,,optparse} passes it to your callback function.

@item @ref{32cb,,nargs}

also has its usual meaning: if it is supplied and > 1, @ref{a4,,optparse} will
consume @ref{32cb,,nargs} arguments, each of which must be convertible to
@ref{329c,,type}.  It then passes a tuple of converted values to your
callback.

@item @ref{32ce,,callback_args}

a tuple of extra positional arguments to pass to the callback

@item @ref{32cf,,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{32e5}@anchor{library/optparse optparse-how-callbacks-called}@anchor{32e6}
@subsubsection How callbacks are called


All callbacks are called as follows:

@example
func(option, opt_str, value, parser, *args, **kwargs)
@end example

where


@table @asis

@item @code{option}

is the Option instance that's calling the callback

@item @code{opt_str}

is the option string seen on the command-line that's triggering the callback.
(If an abbreviated long option was used, @code{opt_str} will be the full,
canonical option string---e.g. if the user puts @code{--foo} on the
command-line as an abbreviation for @code{--foobar}, then @code{opt_str} will be
@code{"--foobar"}.)

@item @code{value}

is the argument to this option seen on the command-line.  @ref{a4,,optparse} will
only expect an argument if @ref{329c,,type} is set; the type of @code{value} will be
the type implied by the option's type.  If @ref{329c,,type} for this option is
@code{None} (no argument expected), then @code{value} will be @code{None}.  If @ref{32cb,,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{16c2,,parse_args()}.)

@item @code{parser.rargs}

the current list of remaining arguments, ie. with @code{opt_str} and
@code{value} (if applicable) removed, and only the arguments following them
still there.  Feel free to modify @code{parser.rargs}, e.g. by consuming more
arguments.

@item @code{parser.values}

the object where option values are by default stored (an instance of
optparse.OptionValues).  This lets callbacks use the same mechanism as the
rest of @ref{a4,,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{32ce,,callback_args} option attribute.

@item @code{kwargs}

is a dictionary of arbitrary keyword arguments supplied via
@ref{32cf,,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{32e7}@anchor{library/optparse raising-errors-in-a-callback}@anchor{32e8}
@subsubsection Raising errors in a callback


The callback function should raise @ref{328b,,OptionValueError} if there are any
problems with the option or its argument(s).  @ref{a4,,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{32e9}@anchor{library/optparse optparse-callback-example-1}@anchor{32ea}
@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{32eb}@anchor{library/optparse optparse-callback-example-2}@anchor{32ec}
@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{32ed}@anchor{library/optparse optparse-callback-example-3}@anchor{32ee}
@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{32ef}@anchor{library/optparse optparse-callback-example-4}@anchor{32f0}
@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{32f1}@anchor{library/optparse optparse-callback-example-5}@anchor{32f2}
@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{329c,,type}, then the option takes one argument that must be
convertible to that type; if you further define @ref{32cb,,nargs}, then the
option takes @ref{32cb,,nargs} arguments.

Here's an example that just emulates the standard @code{"store"} action:

@example
def store_value(option, opt_str, value, parser):
    setattr(parser.values, option.dest, value)
...
parser.add_option("--foo",
                  action="callback", callback=store_value,
                  type="int", nargs=3, dest="foo")
@end example

Note that @ref{a4,,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{32f3}@anchor{library/optparse optparse-callback-example-6}@anchor{32f4}
@subsubsection Callback example 6: variable arguments


Things get hairy when you want an option to take a variable number of arguments.
For this case, you must write a callback, as @ref{a4,,optparse} doesn't provide any
built-in capabilities for it.  And you have to deal with certain intricacies of
conventional Unix command-line parsing that @ref{a4,,optparse} normally handles for
you.  In particular, callbacks should implement the conventional rules for bare
@code{--} and @code{-} arguments:


@itemize *

@item 
either @code{--} or @code{-} can be option arguments

@item 
bare @code{--} (if not the argument to some option): halt command-line
processing and discard the @code{--}

@item 
bare @code{-} (if not the argument to some option): halt command-line
processing but keep the @code{-} (append it to @code{parser.largs})
@end itemize

If you want an option that takes a variable number of arguments, there are
several subtle, tricky issues to worry about.  The exact implementation you
choose will be based on which trade-offs you're willing to make for your
application (which is why @ref{a4,,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,例外<10>,Option Callbacks,optparse --- 命令列選項剖析器
@anchor{library/optparse extending-optparse}@anchor{32f5}@anchor{library/optparse optparse-extending-optparse}@anchor{32a1}
@subsubsection Extending @code{optparse}


Since the two major controlling factors in how @ref{a4,,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{32f6}@anchor{library/optparse optparse-adding-new-types}@anchor{32f7}
@subsubsection Adding new types


To add new types, you need to define your own subclass of @ref{a4,,optparse}'s
@ref{32c3,,Option} class.  This class has a couple of attributes that define
@ref{a4,,optparse}'s types: @ref{32f8,,TYPES} and @ref{32f9,,TYPE_CHECKER}.

@geindex TYPES (optparse.Option 的屬性)
@anchor{library/optparse optparse Option TYPES}@anchor{32f8}
@deffn {屬性} Option.TYPES

A tuple of type names; in your subclass, simply define a new tuple
@ref{32f8,,TYPES} that builds on the standard one.
@end deffn

@geindex TYPE_CHECKER (optparse.Option 的屬性)
@anchor{library/optparse optparse Option TYPE_CHECKER}@anchor{32f9}
@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{32c3,,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{16c2,,OptionParser.parse_args()}, or be passed to a callback as the
@code{value} parameter.

Your type-checking function should raise @ref{328b,,OptionValueError} if it
encounters any problems.  @ref{328b,,OptionValueError} takes a single string
argument, which is passed as-is to @ref{16c1,,OptionParser}'s @code{error()}
method, which in turn prepends the program name and the string @code{"error:"}
and prints everything to stderr before terminating the process.
@end deffn

Here's a silly example that demonstrates adding a @code{"complex"} option type to
parse Python-style complex numbers on the command line.  (This is even sillier
than it used to be, because @ref{a4,,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{32f9,,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{32f9,,Option.TYPE_CHECKER}, we would end
up modifying the @ref{32f9,,TYPE_CHECKER} attribute of @ref{a4,,optparse}'s
Option class.  This being Python, nothing stops you from doing that except good
manners and common sense.)

That's it!  Now you can write a script that uses the new option type just like
any other @ref{a4,,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{32fa}@anchor{library/optparse optparse-adding-new-actions}@anchor{32fb}
@subsubsection Adding new actions


Adding new actions is a bit trickier, because you have to understand that
@ref{a4,,optparse} has a couple of classifications for actions:


@table @asis

@item "store" actions

actions that result in @ref{a4,,optparse} storing a value to an attribute of the
current OptionValues instance; these options require a @ref{329d,,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{329c,,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{32fc}
@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{32fd}
@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{32fe}
@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{32ff}
@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 @ref{a4,,optparse}
assigns the default type, @code{"string"}, to options with no explicit type
whose action is listed in @ref{32ff,,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{32fd,,STORE_ACTIONS} and
@ref{32fe,,TYPED_ACTIONS}.

@item 
to ensure that @ref{a4,,optparse} assigns the default type of @code{"string"} to
@code{"extend"} actions, we put the @code{"extend"} action in
@ref{32ff,,ALWAYS_TYPED_ACTIONS} as well.

@item 
@code{MyOption.take_action()} implements just this one new action, and passes
control back to @code{Option.take_action()} for the standard @ref{a4,,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{dc5,,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 例外<10>,,Extending optparse,optparse --- 命令列選項剖析器
@anchor{library/optparse exceptions}@anchor{3300}
@subsubsection 例外


@geindex OptionError
@anchor{library/optparse optparse OptionError}@anchor{328a}
@deffn {例外} optparse.OptionError

Raised if an @ref{32c3,,Option} instance is created with invalid or
inconsistent arguments.
@end deffn

@geindex OptionConflictError
@anchor{library/optparse optparse OptionConflictError}@anchor{32db}
@deffn {例外} optparse.OptionConflictError

Raised if conflicting options are added to an @ref{16c1,,OptionParser}.
@end deffn

@geindex OptionValueError
@anchor{library/optparse optparse OptionValueError}@anchor{328b}
@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{3301}
@deffn {例外} optparse.BadOptionError

Raised if an invalid option is passed on the command line.
@end deffn

@geindex AmbiguousOptionError
@anchor{library/optparse optparse AmbiguousOptionError}@anchor{3302}
@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 --- 可攜式密碼輸入工具,fileinput --- 逐列疊代多個輸入串流,optparse --- 命令列選項剖析器,命令列介面函式庫
@anchor{library/getpass doc}@anchor{3303}@anchor{library/getpass getpass-portable-password-input}@anchor{3304}@anchor{library/getpass module-getpass}@anchor{66}@anchor{library/getpass translation-repo}@anchor{3305}
@subsection @code{getpass} --- 可攜式密碼輸入工具


@geindex module; getpass

@c Windows (& Mac?) support by Guido van Rossum.

`原始碼：'Lib/getpass.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/getpass.py}


__________________________________________________________________


@c include for modules that don't work on WASM

@ref{2006,,可用性}: not WASI.

此模組在 WebAssembly 平台上不起作用或無法使用。更多資訊請參閱 @ref{1a99,,WebAssembly 平台}。

@ref{66,,getpass} 模組 (module) 提供了兩個函式：

@geindex getpass() (於 getpass 模組中)
@anchor{library/getpass getpass getpass}@anchor{21d}
@deffn {函式} getpass.getpass (prompt='Password: ', stream=None, *, echo_char=None)

提示使用者輸入一個密碼且不會有回音 (echo)。使用者會看到字串 `prompt' 作為提示，其預設值為 @code{'Password: '}。在 Unix 上，如有必要的話會使用替換錯誤處理函式 (replace error handler) 寫入到類檔案物件 (file-like object) `stream'中。`stream' 預設為主控終端機 (controlling terminal) (@code{/dev/tty})，如果不可用則為 @code{sys.stderr} (此引數在 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.

如果無回音輸入 (echo-free input) 無法使用則 getpass() 將回退為印出一條警告訊息到 `stream'，並從 @code{sys.stdin} 讀取且同時發出 @ref{3306,,GetPassWarning}。

@cartouche
@quotation 備註 
如果你從 IDLE 內部呼叫 getpass，輸入可能會在你啟動 IDLE 的終端機中完成，而非在 IDLE 視窗中。
@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}}.
In particular, this means that line editing shortcuts such as
@code{Ctrl}+@code{U} will not work and may insert unexpected characters into
the input.
@end quotation
@end cartouche


在 3.14 版的變更: Added the `echo_char' parameter for keyboard feedback.

@end deffn

@geindex GetPassWarning
@anchor{library/getpass getpass GetPassWarning}@anchor{3306}
@deffn {例外} getpass.GetPassWarning

當密碼輸入可能被回音時會發出的 @ref{25be,,UserWarning} 子類別。
@end deffn

@geindex getuser() (於 getpass 模組中)
@anchor{library/getpass getpass getuser}@anchor{652}
@deffn {函式} getpass.getuser ()

回傳使用者的"登入名稱"。

此函式會按順序檢查環境變數 
@geindex LOGNAME
@geindex 環境變數; LOGNAME
@code{LOGNAME}、
@geindex USER
@geindex 環境變數; USER
@code{USER}、@code{LNAME} 和 
@geindex USERNAME
@geindex 環境變數; USERNAME
@code{USERNAME}，並回傳其中第一個被設定成非空字串的值。如果均未設定，則在支援 @ref{b7,,pwd} 模組的系統上將會回傳來自密碼資料庫的登入名稱，否則將引發一個 @ref{2c0,,OSError} 例外。

大部分情況下，此函式應該要比 @ref{17a5,,os.getlogin()} 優先使用。


在 3.13 版的變更: 在過去，除了 @ref{2c0,,OSError} 外還會引發各種例外。

@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 --- 逐列疊代多個輸入串流,curses --- 字元儲存格顯示的終端處理,getpass --- 可攜式密碼輸入工具,命令列介面函式庫
@anchor{library/fileinput doc}@anchor{3307}@anchor{library/fileinput fileinput-iterate-over-lines-from-multiple-input-streams}@anchor{3308}@anchor{library/fileinput module-fileinput}@anchor{5f}@anchor{library/fileinput translation-repo}@anchor{3309}
@subsection @code{fileinput} --- 逐列疊代多個輸入串流


@geindex module; fileinput

`原始碼：'Lib/fileinput.py@footnote{https://github.com/python/cpython/tree/3.14/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{315,,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{9f9,,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{9f9,,input()} or
@ref{938,,FileInput}.  If an I/O error occurs during opening or reading a file,
@ref{2c0,,OSError} is raised.


在 3.3 版的變更: @ref{124e,,IOError} 曾經被引發；現在它是一個 @ref{2c0,,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{9f9,,fileinput.input()} or @ref{938,,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{9fa,,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{9f9}
@deffn {函式} fileinput.input (files=None, inplace=False, backup='@w{'}, *, mode='r', openhook=None, encoding=None, errors=None)

Create an instance of the @ref{938,,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 @ref{938,,FileInput} class.

The @ref{938,,FileInput} instance can be used as a context manager in the
@ref{186,,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{9f9,,fileinput.input()};
if there is no active state, @ref{244,,RuntimeError} is raised.

@geindex filename() (於 fileinput 模組中)
@anchor{library/fileinput fileinput filename}@anchor{330a}
@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{1625}
@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{330b}
@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{330c}
@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{330d}
@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{330e}
@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{330f}
@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{3310}
@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{938}
@deffn {類別} fileinput.FileInput (files=None, inplace=False, backup='@w{'}, *, mode='r', openhook=None, encoding=None, errors=None)

Class @ref{938,,FileInput} is the implementation; its methods @ref{330a,,filename()},
@ref{1625,,fileno()}, @ref{330b,,lineno()}, @ref{330c,,filelineno()}, @ref{330d,,isfirstline()},
@ref{330e,,isstdin()}, @ref{330f,,nextfile()} and @ref{3310,,close()} correspond to the
functions of the same name in the module. In addition it is @ref{1428,,iterable}
and has a @ref{1f6d,,readline()} method which returns the next
input line. The sequence must be accessed in strictly sequential order;
random access and @ref{1f6d,,readline()} cannot be mixed.

With `mode' you can specify which file mode will be passed to @ref{315,,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{315,,open()} or `openhook'.

A @ref{938,,FileInput} instance can be used as a context manager in the
@ref{186,,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{9f9,,fileinput.input()} or to the @ref{938,,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{9fa}
@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{6b,,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{315,,open()} without any decompression).

The `encoding' and `errors' values are passed to @ref{9b7,,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{e99}
@deffn {函式} fileinput.hook_encoded (encoding, errors=None)

Returns a hook which opens each file with @ref{315,,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 版的變更: 新增可選參數 `errors'。



在 3.10 版之後被棄用: This function is deprecated since @ref{9f9,,fileinput.input()} and @ref{938,,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 --- 字元儲存格顯示的終端處理,curses textpad --- Text input widget for curses programs,fileinput --- 逐列疊代多個輸入串流,命令列介面函式庫
@anchor{library/curses doc}@anchor{3311}@anchor{library/curses curses-terminal-handling-for-character-cell-displays}@anchor{3312}@anchor{library/curses module-curses}@anchor{2f}@anchor{library/curses translation-repo}@anchor{3313}
@subsection @code{curses} --- 字元儲存格顯示的終端處理


@geindex module; curses

`原始碼：'Lib/curses@footnote{https://github.com/python/cpython/tree/3.14/Lib/curses}


__________________________________________________________________


The @ref{2f,,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{2006,,可用性}: not Android, not iOS, not WASI.

此模組在@ref{2120,,行動平台}或@ref{1a99,,WebAssembly 平台}上不支援。

@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 @ref{30,,curses.ascii} 模組

Utilities for working with ASCII characters, regardless of your locale settings.

@item @ref{31,,curses.panel} 模組

A panel stack extension that adds depth to  curses windows.

@item @ref{32,,curses.textpad} 模組

Editable text widget for curses supporting  @code{Emacs}-like bindings.

@item @ref{3314,,Curses Programming with Python}

Tutorial material on using curses with Python, by Andrew Kuchling and Eric
Raymond.
@end table


@menu
* 函式: 函式<6>. 
* Window Objects:: 
* Constants:: 

@end menu

@node 函式<6>,Window Objects,,curses --- 字元儲存格顯示的終端處理
@anchor{library/curses curses-functions}@anchor{3315}@anchor{library/curses functions}@anchor{3316}
@subsubsection 函式


@ref{2f,,curses} 模組定義了以下例外：

@geindex error
@anchor{library/curses curses error}@anchor{3317}
@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{3318,,A_NORMAL}.
@end quotation
@end cartouche

@ref{2f,,curses} 模組定義了以下函式：

@geindex assume_default_colors() (於 curses 模組中)
@anchor{library/curses curses assume_default_colors}@anchor{1f6}
@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


在 3.14 版被加入.

@end deffn

@geindex baudrate() (於 curses 模組中)
@anchor{library/curses curses baudrate}@anchor{3319}
@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{331a}
@deffn {函式} curses.beep ()

Emit a short attention sound.
@end deffn

@geindex can_change_color() (於 curses 模組中)
@anchor{library/curses curses can_change_color}@anchor{331b}
@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{331c}
@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{331d,,raw()} then @ref{331c,,cbreak()} leaves the terminal in cbreak mode.
@end deffn

@geindex color_content() (於 curses 模組中)
@anchor{library/curses curses color_content}@anchor{9eb}
@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{331e}
@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{331f,,A_STANDOUT}, @ref{3320,,A_REVERSE},
and the other @code{A_*} attributes.  @ref{3321,,pair_number()} is the counterpart
to this function.
@end deffn

@geindex curs_set() (於 curses 模組中)
@anchor{library/curses curses curs_set}@anchor{3322}
@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{3323}
@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{3324,,reset_prog_mode()} will
restore this mode.
@end deffn

@geindex def_shell_mode() (於 curses 模組中)
@anchor{library/curses curses def_shell_mode}@anchor{3325}
@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{3326,,reset_shell_mode()} will restore this mode.
@end deffn

@geindex delay_output() (於 curses 模組中)
@anchor{library/curses curses delay_output}@anchor{3327}
@deffn {函式} curses.delay_output (ms)

Insert an `ms' millisecond pause in output.
@end deffn

@geindex doupdate() (於 curses 模組中)
@anchor{library/curses curses doupdate}@anchor{3328}
@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 @ref{3328,,doupdate()} ground updates the
physical screen to match the virtual screen.

The virtual screen may be updated by a @ref{3329,,noutrefresh()} call after write
operations such as @ref{332a,,addstr()} have been performed on a window.  The normal
@ref{332b,,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{332c}
@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{332d}
@deffn {函式} curses.endwin ()

De-initialize the library, and return terminal to normal status.
@end deffn

@geindex erasechar() (於 curses 模組中)
@anchor{library/curses curses erasechar}@anchor{332e}
@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{332f}
@deffn {函式} curses.filter ()

The @ref{332f,,filter()} routine, if used, must be called before @ref{187a,,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{3330}
@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{331a,,beep()}.
@end deffn

@geindex flushinp() (於 curses 模組中)
@anchor{library/curses curses flushinp}@anchor{3331}
@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{3332}
@deffn {函式} curses.getmouse ()

After @ref{17a8,,getch()} returns @ref{3333,,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{3334,,BUTTONn_PRESSED}, @ref{3335,,BUTTONn_RELEASED}, @ref{3336,,BUTTONn_CLICKED},
@ref{3337,,BUTTONn_DOUBLE_CLICKED}, @ref{3338,,BUTTONn_TRIPLE_CLICKED},
@ref{3339,,BUTTON_SHIFT}, @ref{333a,,BUTTON_CTRL}, @ref{333b,,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{333c}
@deffn {函式} curses.getsyx ()

Return the current coordinates of the virtual screen cursor as a tuple
@code{(y, x)}.  If @ref{333d,,leaveok} is currently @code{True}, then return @code{(-1, -1)}.
@end deffn

@geindex getwin() (於 curses 模組中)
@anchor{library/curses curses getwin}@anchor{333e}
@deffn {函式} curses.getwin (file)

Read window related data stored in the file by an earlier @ref{333f,,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{3340}
@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{9ef}
@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.


在 3.10 版被加入.

@end deffn

@geindex has_ic() (於 curses 模組中)
@anchor{library/curses curses has_ic}@anchor{3341}
@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{3342}
@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{3343}
@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{3344}
@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{3345,,nocbreak()} to leave half-delay mode.
@end deffn

@geindex init_color() (於 curses 模組中)
@anchor{library/curses curses init_color}@anchor{9ec}
@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 @ref{9ec,,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{331b,,can_change_color()} returns @code{True}.
@end deffn

@geindex init_pair() (於 curses 模組中)
@anchor{library/curses curses init_pair}@anchor{9ed}
@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{1f7,,use_default_colors()} and @ref{1f6,,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{187a}
@deffn {函式} curses.initscr ()

Initialize the library. Return a @ref{18e3,,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{3346}
@deffn {函式} curses.is_term_resized (nlines, ncols)

Return @code{True} if @ref{1896,,resize_term()} would modify the window structure,
@code{False} otherwise.
@end deffn

@geindex isendwin() (於 curses 模組中)
@anchor{library/curses curses isendwin}@anchor{3347}
@deffn {函式} curses.isendwin ()

Return @code{True} if @ref{332d,,endwin()} has been called (that is, the  curses library has
been deinitialized).
@end deffn

@geindex keyname() (於 curses 模組中)
@anchor{library/curses curses keyname}@anchor{3348}
@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{3349}
@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{334a}
@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{187a,,initscr()}.
@end deffn

@geindex meta() (於 curses 模組中)
@anchor{library/curses curses meta}@anchor{334b}
@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{334c}
@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{334d}
@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{1879}
@deffn {函式} curses.napms (ms)

Sleep for `ms' milliseconds.
@end deffn

@geindex newpad() (於 curses 模組中)
@anchor{library/curses curses newpad}@anchor{334e}
@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{332b,,refresh()} and @ref{3329,,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{334f}
@deffn {函式} curses.newwin (nlines, ncols)

@deffnx {函式} curses.newwin (nlines, ncols, begin_y, begin_x)

Return a new @ref{18e3,,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{3350}
@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{3345}
@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{3351}
@deffn {函式} curses.noecho ()

Leave echo mode.  Echoing of input characters is turned off.
@end deffn

@geindex nonl() (於 curses 模組中)
@anchor{library/curses curses nonl}@anchor{3352}
@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{3353}
@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{3354}
@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{9ee}
@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{3321}
@deffn {函式} curses.pair_number (attr)

Return the number of the color-pair set by the attribute value `attr'.
@ref{331e,,color_pair()} is the counterpart to this function.
@end deffn

@geindex putp() (於 curses 模組中)
@anchor{library/curses curses putp}@anchor{3355}
@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 @ref{3355,,putp()}
always goes to standard output.
@end deffn

@geindex qiflush() (於 curses 模組中)
@anchor{library/curses curses qiflush}@anchor{3356}
@deffn {函式} curses.qiflush ([flag])

If `flag' is @code{False}, the effect is the same as calling @ref{3353,,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{331d}
@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{3324}
@deffn {函式} curses.reset_prog_mode ()

Restore the  terminal  to "program" mode, as previously saved  by
@ref{3323,,def_prog_mode()}.
@end deffn

@geindex reset_shell_mode() (於 curses 模組中)
@anchor{library/curses curses reset_shell_mode}@anchor{3326}
@deffn {函式} curses.reset_shell_mode ()

Restore the  terminal  to "shell" mode, as previously saved  by
@ref{3325,,def_shell_mode()}.
@end deffn

@geindex resetty() (於 curses 模組中)
@anchor{library/curses curses resetty}@anchor{3357}
@deffn {函式} curses.resetty ()

Restore the state of the terminal modes to what it was at the last call to
@ref{3358,,savetty()}.
@end deffn

@geindex resize_term() (於 curses 模組中)
@anchor{library/curses curses resize_term}@anchor{1896}
@deffn {函式} curses.resize_term (nlines, ncols)

Backend function used by @ref{1895,,resizeterm()}, performing most of the work;
when resizing the windows, @ref{1896,,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{1895}
@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{3358}
@deffn {函式} curses.savetty ()

Save the current state of the terminal modes in a buffer, usable by
@ref{3357,,resetty()}.
@end deffn

@geindex get_escdelay() (於 curses 模組中)
@anchor{library/curses curses get_escdelay}@anchor{ae3}
@deffn {函式} curses.get_escdelay ()

Retrieves the value set by @ref{ae4,,set_escdelay()}.


在 3.9 版被加入.

@end deffn

@geindex set_escdelay() (於 curses 模組中)
@anchor{library/curses curses set_escdelay}@anchor{ae4}
@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.


在 3.9 版被加入.

@end deffn

@geindex get_tabsize() (於 curses 模組中)
@anchor{library/curses curses get_tabsize}@anchor{ae5}
@deffn {函式} curses.get_tabsize ()

Retrieves the value set by @ref{ae6,,set_tabsize()}.


在 3.9 版被加入.

@end deffn

@geindex set_tabsize() (於 curses 模組中)
@anchor{library/curses curses set_tabsize}@anchor{ae6}
@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.


在 3.9 版被加入.

@end deffn

@geindex setsyx() (於 curses 模組中)
@anchor{library/curses curses setsyx}@anchor{3359}
@deffn {函式} curses.setsyx (y, x)

Set the virtual screen cursor to `y', `x'. If `y' and `x' are both @code{-1}, then
@ref{333d,,leaveok} is set @code{True}.
@end deffn

@geindex setupterm() (於 curses 模組中)
@anchor{library/curses curses setupterm}@anchor{335a}
@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{335b}
@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{187a,,initscr()}.

@ref{335b,,start_color()} initializes eight basic colors (black, red,  green, yellow,
blue, magenta, cyan, and white), and two global variables in the @ref{2f,,curses}
module, @ref{335c,,COLORS} and @ref{335d,,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{335e}
@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{335f}
@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{3360}
@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{3361}
@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{3362}
@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{3363}
@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{3364}
@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{3365}
@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{3366}
@deffn {函式} curses.ungetch (ch)

Push `ch' so the next @ref{17a8,,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{fe6}
@deffn {函式} curses.update_lines_cols ()

Update the @ref{fe7,,LINES} and @ref{fe8,,COLS} module variables.
Useful for detecting manual screen resize.


在 3.5 版被加入.

@end deffn

@geindex unget_wch() (於 curses 模組中)
@anchor{library/curses curses unget_wch}@anchor{1299}
@deffn {函式} curses.unget_wch (ch)

Push `ch' so the next @ref{1298,,get_wch()} will return it.

@cartouche
@quotation 備註 
Only one `ch' can be pushed before @code{get_wch()} is called.
@end quotation
@end cartouche


在 3.3 版被加入.

@end deffn

@geindex ungetmouse() (於 curses 模組中)
@anchor{library/curses curses ungetmouse}@anchor{3367}
@deffn {函式} curses.ungetmouse (id, x, y, z, bstate)

Push a @ref{3333,,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{3368}
@deffn {函式} curses.use_env (flag)

If used, this function should be called before @ref{187a,,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{1f7}
@deffn {函式} curses.use_default_colors ()

Equivalent to @code{assume_default_colors(-1, -1)}.
@end deffn

@geindex wrapper() (於 curses 模組中)
@anchor{library/curses curses wrapper}@anchor{c6a}
@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>,curses --- 字元儲存格顯示的終端處理
@anchor{library/curses curses-window-objects}@anchor{18e3}@anchor{library/curses window-objects}@anchor{3369}
@subsubsection Window Objects


@geindex window (curses 中的類別)
@anchor{library/curses curses window}@anchor{1296}
@deffn {類別} curses.window

Window objects, as returned by @ref{187a,,initscr()} and @ref{334f,,newwin()} above, have
the following methods and attributes:
@end deffn

@geindex addch() (curses.window 的方法)
@anchor{library/curses curses window addch}@anchor{336a}
@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{3317,,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{336b}
@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{332a}
@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{3317,,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{332a,,addstr()}
with a `str' that has embedded newlines.  Instead, call @ref{332a,,addstr()}
separately for each line.
@end itemize
@end quotation
@end cartouche
@end deffn

@geindex attroff() (curses.window 的方法)
@anchor{library/curses curses window attroff}@anchor{336c}
@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{336d}
@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{336e}
@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{336f}
@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{3370}
@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{3371}
@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

參數

@tab

描述

@tab

Default value

@item

`ls'

@tab

Left side

@tab

@ref{3372,,ACS_VLINE}

@item

`rs'

@tab

Right side

@tab

@ref{3372,,ACS_VLINE}

@item

`ts'

@tab

Top

@tab

@ref{3373,,ACS_HLINE}

@item

`bs'

@tab

Bottom

@tab

@ref{3373,,ACS_HLINE}

@item

`tl'

@tab

Upper-left corner

@tab

@ref{3374,,ACS_ULCORNER}

@item

`tr'

@tab

Upper-right corner

@tab

@ref{3375,,ACS_URCORNER}

@item

`bl'

@tab

Bottom-left corner

@tab

@ref{3376,,ACS_LLCORNER}

@item

`br'

@tab

Bottom-right corner

@tab

@ref{3377,,ACS_LRCORNER}

@end multitable

@end deffn

@geindex box() (curses.window 的方法)
@anchor{library/curses curses window box}@anchor{3378}
@deffn {方法} window.box ([vertch, horch])

Similar to @ref{3371,,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{3379}
@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{337a,,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{337b}
@deffn {方法} window.clear ()

Like @ref{337c,,erase()}, but also cause the whole window to be repainted upon next
call to @ref{332b,,refresh()}.
@end deffn

@geindex clearok() (curses.window 的方法)
@anchor{library/curses curses window clearok}@anchor{337d}
@deffn {方法} window.clearok (flag)

If `flag' is @code{True}, the next call to @ref{332b,,refresh()} will clear the window
completely.
@end deffn

@geindex clrtobot() (curses.window 的方法)
@anchor{library/curses curses window clrtobot}@anchor{337e}
@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{337f,,clrtoeol()} is performed.
@end deffn

@geindex clrtoeol() (curses.window 的方法)
@anchor{library/curses curses window clrtoeol}@anchor{337f}
@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{3380}
@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{3381}
@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{3382}
@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{3383}
@deffn {方法} window.derwin (begin_y, begin_x)

@deffnx {方法} window.derwin (nlines, ncols, begin_y, begin_x)

An abbreviation for "derive window", @ref{3383,,derwin()} is the same as calling
@ref{3384,,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{3385}
@deffn {方法} window.echochar (ch[, attr])

Add character `ch' with attribute `attr', and immediately  call @ref{332b,,refresh()}
on the window.
@end deffn

@geindex enclose() (curses.window 的方法)
@anchor{library/curses curses window enclose}@anchor{1b8d}
@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{1297}
@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{3384,,window.subwin()}.
By default, current locale encoding is used (see @ref{328,,locale.getencoding()}).


在 3.3 版被加入.

@end deffn

@geindex erase() (curses.window 的方法)
@anchor{library/curses curses window erase}@anchor{337c}
@deffn {方法} window.erase ()

Clear the window.
@end deffn

@geindex getbegyx() (curses.window 的方法)
@anchor{library/curses curses window getbegyx}@anchor{3386}
@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{3387}
@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{17a8}
@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{1298}
@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.


在 3.3 版被加入.

@end deffn

@geindex getkey() (curses.window 的方法)
@anchor{library/curses curses window getkey}@anchor{3388}
@deffn {方法} window.getkey ([y, x])

Get a character, returning a string instead of an integer, as @ref{17a8,,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{3389}
@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{338a}
@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{17bb}
@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{338b}
@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{338c}
@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{338d}
@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{338e}
@deffn {方法} window.idlok (flag)

If `flag' is @code{True}, @ref{2f,,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{338f}
@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{332b,,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{3390}
@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{3391}
@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{3392}
@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{3393}
@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{3394}
@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{3395}
@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{17ba}
@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, @ref{17ba,,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{3396}
@deffn {方法} window.is_linetouched (line)

Return @code{True} if the specified line was modified since the last call to
@ref{332b,,refresh()}; otherwise return @code{False}.  Raise a @ref{3317,,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{3397}
@deffn {方法} window.is_wintouched ()

Return @code{True} if the specified window was modified since the last call to
@ref{332b,,refresh()}; otherwise return @code{False}.
@end deffn

@geindex keypad() (curses.window 的方法)
@anchor{library/curses curses window keypad}@anchor{3398}
@deffn {方法} window.keypad (flag)

If `flag' is @code{True}, escape sequences generated by some keys (keypad,  function keys)
will be interpreted by @ref{2f,,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{333d}
@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{3399}
@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{339a}
@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{339b}
@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{339c}
@deffn {方法} window.nodelay (flag)

If `flag' is @code{True}, @ref{17a8,,getch()} will be non-blocking.
@end deffn

@geindex notimeout() (curses.window 的方法)
@anchor{library/curses curses window notimeout}@anchor{339d}
@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{3329}
@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{3328,,doupdate()}.
@end deffn

@geindex overlay() (curses.window 的方法)
@anchor{library/curses curses window overlay}@anchor{339e}
@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
@ref{339e,,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{339f}
@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
@ref{339f,,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{333f}
@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{333e,,getwin()} function.
@end deffn

@geindex redrawln() (curses.window 的方法)
@anchor{library/curses curses window redrawln}@anchor{33a0}
@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{332b,,refresh()} call.
@end deffn

@geindex redrawwin() (curses.window 的方法)
@anchor{library/curses curses window redrawwin}@anchor{33a1}
@deffn {方法} window.redrawwin ()

Touch the entire window, causing it to be completely redrawn on the next
@ref{332b,,refresh()} call.
@end deffn

@geindex refresh() (curses.window 的方法)
@anchor{library/curses curses window refresh}@anchor{332b}
@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{334e,,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{33a2}
@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{3370,,bkgdset()}) merged into them.
@end deffn

@geindex scroll() (curses.window 的方法)
@anchor{library/curses curses window scroll}@anchor{33a3}
@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{33a4}
@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{338e,,idlok()}.
@end deffn

@geindex setscrreg() (curses.window 的方法)
@anchor{library/curses curses window setscrreg}@anchor{33a5}
@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{33a6}
@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{33a7}
@deffn {方法} window.standout ()

Turn on attribute `A_STANDOUT'.
@end deffn

@geindex subpad() (curses.window 的方法)
@anchor{library/curses curses window subpad}@anchor{33a8}
@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{3384}
@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{33a9}
@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{332b,,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{33aa}
@deffn {方法} window.syncok (flag)

If `flag' is @code{True}, then @ref{33ab,,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{33ab}
@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{33ac}
@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{17a8,,getch()} will
return @code{-1} if no input is waiting.  If `delay' is positive, then
@ref{17a8,,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{337a}
@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{33ad}
@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{33ae}
@deffn {方法} window.untouchwin ()

Mark all lines in  the  window  as unchanged since the last call to
@ref{332b,,refresh()}.
@end deffn

@geindex vline() (curses.window 的方法)
@anchor{library/curses curses window vline}@anchor{1a44}
@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,,Window Objects,curses --- 字元儲存格顯示的終端處理
@anchor{library/curses constants}@anchor{33af}
@subsubsection Constants


@ref{2f,,curses} 模組定義了以下資料成員：

@geindex ERR (於 curses 模組中)
@anchor{library/curses curses ERR}@anchor{33b0}
@deffn {資料} curses.ERR

Some curses routines  that  return  an integer, such as @ref{17a8,,getch()}, return
@ref{33b0,,ERR} upon failure.
@end deffn

@geindex OK (於 curses 模組中)
@anchor{library/curses curses OK}@anchor{33b1}
@deffn {資料} curses.OK

Some curses routines  that  return  an integer, such as  @ref{1879,,napms()}, return
@ref{33b1,,OK} upon success.
@end deffn

@geindex version (於 curses 模組中)
@anchor{library/curses curses version}@anchor{33b2}
@deffn {資料} curses.version
@end deffn

@geindex __version__ (於 curses 模組中)
@anchor{library/curses curses __version__}@anchor{33b3}
@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{bd1}
@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.


在 3.8 版被加入.

@end deffn

@geindex COLORS (於 curses 模組中)
@anchor{library/curses curses COLORS}@anchor{335c}
@deffn {資料} curses.COLORS

The maximum number of colors the terminal can support.
It is defined only after the call to @ref{335b,,start_color()}.
@end deffn

@geindex COLOR_PAIRS (於 curses 模組中)
@anchor{library/curses curses COLOR_PAIRS}@anchor{335d}
@deffn {資料} curses.COLOR_PAIRS

The maximum number of color pairs the terminal can support.
It is defined only after the call to @ref{335b,,start_color()}.
@end deffn

@geindex COLS (於 curses 模組中)
@anchor{library/curses curses COLS}@anchor{fe8}
@deffn {資料} curses.COLS

The width of the screen, i.e., the number of columns.
It is defined only after the call to @ref{187a,,initscr()}.
Updated by @ref{fe6,,update_lines_cols()}, @ref{1895,,resizeterm()} and
@ref{1896,,resize_term()}.
@end deffn

@geindex LINES (於 curses 模組中)
@anchor{library/curses curses LINES}@anchor{fe7}
@deffn {資料} curses.LINES

The height of the screen, i.e., the number of lines.
It is defined only after the call to @ref{187a,,initscr()}.
Updated by @ref{fe6,,update_lines_cols()}, @ref{1895,,resizeterm()} and
@ref{1896,,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

含義

@item

@geindex A_ALTCHARSET (於 curses 模組中)
@anchor{library/curses curses A_ALTCHARSET}@anchor{33b4}
@deffn {資料} curses.A_ALTCHARSET
@end deffn

@tab

Alternate character set mode

@item

@geindex A_BLINK (於 curses 模組中)
@anchor{library/curses curses A_BLINK}@anchor{33b5}
@deffn {資料} curses.A_BLINK
@end deffn

@tab

Blink mode

@item

@geindex A_BOLD (於 curses 模組中)
@anchor{library/curses curses A_BOLD}@anchor{33b6}
@deffn {資料} curses.A_BOLD
@end deffn

@tab

Bold mode

@item

@geindex A_DIM (於 curses 模組中)
@anchor{library/curses curses A_DIM}@anchor{33b7}
@deffn {資料} curses.A_DIM
@end deffn

@tab

Dim mode

@item

@geindex A_INVIS (於 curses 模組中)
@anchor{library/curses curses A_INVIS}@anchor{33b8}
@deffn {資料} curses.A_INVIS
@end deffn

@tab

Invisible or blank mode

@item

@geindex A_ITALIC (於 curses 模組中)
@anchor{library/curses curses A_ITALIC}@anchor{33b9}
@deffn {資料} curses.A_ITALIC
@end deffn

@tab

Italic mode

@item

@geindex A_NORMAL (於 curses 模組中)
@anchor{library/curses curses A_NORMAL}@anchor{3318}
@deffn {資料} curses.A_NORMAL
@end deffn

@tab

Normal attribute

@item

@geindex A_PROTECT (於 curses 模組中)
@anchor{library/curses curses A_PROTECT}@anchor{33ba}
@deffn {資料} curses.A_PROTECT
@end deffn

@tab

Protected mode

@item

@geindex A_REVERSE (於 curses 模組中)
@anchor{library/curses curses A_REVERSE}@anchor{3320}
@deffn {資料} curses.A_REVERSE
@end deffn

@tab

Reverse background and
foreground colors

@item

@geindex A_STANDOUT (於 curses 模組中)
@anchor{library/curses curses A_STANDOUT}@anchor{331f}
@deffn {資料} curses.A_STANDOUT
@end deffn

@tab

Standout mode

@item

@geindex A_UNDERLINE (於 curses 模組中)
@anchor{library/curses curses A_UNDERLINE}@anchor{33bb}
@deffn {資料} curses.A_UNDERLINE
@end deffn

@tab

Underline mode

@item

@geindex A_HORIZONTAL (於 curses 模組中)
@anchor{library/curses curses A_HORIZONTAL}@anchor{33bc}
@deffn {資料} curses.A_HORIZONTAL
@end deffn

@tab

Horizontal highlight

@item

@geindex A_LEFT (於 curses 模組中)
@anchor{library/curses curses A_LEFT}@anchor{33bd}
@deffn {資料} curses.A_LEFT
@end deffn

@tab

Left highlight

@item

@geindex A_LOW (於 curses 模組中)
@anchor{library/curses curses A_LOW}@anchor{33be}
@deffn {資料} curses.A_LOW
@end deffn

@tab

Low highlight

@item

@geindex A_RIGHT (於 curses 模組中)
@anchor{library/curses curses A_RIGHT}@anchor{33bf}
@deffn {資料} curses.A_RIGHT
@end deffn

@tab

Right highlight

@item

@geindex A_TOP (於 curses 模組中)
@anchor{library/curses curses A_TOP}@anchor{33c0}
@deffn {資料} curses.A_TOP
@end deffn

@tab

Top highlight

@item

@geindex A_VERTICAL (於 curses 模組中)
@anchor{library/curses curses A_VERTICAL}@anchor{33c1}
@deffn {資料} curses.A_VERTICAL
@end deffn

@tab

Vertical highlight

@end multitable



在 3.7 版被加入: 新增 @code{A_ITALIC}。


Several constants are available to extract corresponding attributes returned
by some methods.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Bit-mask

@tab

含義

@item

@geindex A_ATTRIBUTES (於 curses 模組中)
@anchor{library/curses curses A_ATTRIBUTES}@anchor{33c2}
@deffn {資料} curses.A_ATTRIBUTES
@end deffn

@tab

Bit-mask to extract
attributes

@item

@geindex A_CHARTEXT (於 curses 模組中)
@anchor{library/curses curses A_CHARTEXT}@anchor{33c3}
@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{33c4}
@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{33c5}
@deffn {資料} curses.KEY_MIN
@end deffn

@tab

Minimum key value

@item

@geindex KEY_BREAK (於 curses 模組中)
@anchor{library/curses curses KEY_BREAK}@anchor{33c6}
@deffn {資料} curses.KEY_BREAK
@end deffn

@tab

Break key (unreliable)

@item

@geindex KEY_DOWN (於 curses 模組中)
@anchor{library/curses curses KEY_DOWN}@anchor{33c7}
@deffn {資料} curses.KEY_DOWN
@end deffn

@tab

Down-arrow

@item

@geindex KEY_UP (於 curses 模組中)
@anchor{library/curses curses KEY_UP}@anchor{33c8}
@deffn {資料} curses.KEY_UP
@end deffn

@tab

Up-arrow

@item

@geindex KEY_LEFT (於 curses 模組中)
@anchor{library/curses curses KEY_LEFT}@anchor{33c9}
@deffn {資料} curses.KEY_LEFT
@end deffn

@tab

Left-arrow

@item

@geindex KEY_RIGHT (於 curses 模組中)
@anchor{library/curses curses KEY_RIGHT}@anchor{33ca}
@deffn {資料} curses.KEY_RIGHT
@end deffn

@tab

Right-arrow

@item

@geindex KEY_HOME (於 curses 模組中)
@anchor{library/curses curses KEY_HOME}@anchor{33cb}
@deffn {資料} curses.KEY_HOME
@end deffn

@tab

Home key (upward+left arrow)

@item

@geindex KEY_BACKSPACE (於 curses 模組中)
@anchor{library/curses curses KEY_BACKSPACE}@anchor{33cc}
@deffn {資料} curses.KEY_BACKSPACE
@end deffn

@tab

Backspace (unreliable)

@item

@geindex KEY_F0 (於 curses 模組中)
@anchor{library/curses curses KEY_F0}@anchor{33cd}
@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{33ce}
@deffn {資料} curses.KEY_Fn
@end deffn

@tab

Value of function key `n'

@item

@geindex KEY_DL (於 curses 模組中)
@anchor{library/curses curses KEY_DL}@anchor{33cf}
@deffn {資料} curses.KEY_DL
@end deffn

@tab

Delete line

@item

@geindex KEY_IL (於 curses 模組中)
@anchor{library/curses curses KEY_IL}@anchor{33d0}
@deffn {資料} curses.KEY_IL
@end deffn

@tab

Insert line

@item

@geindex KEY_DC (於 curses 模組中)
@anchor{library/curses curses KEY_DC}@anchor{33d1}
@deffn {資料} curses.KEY_DC
@end deffn

@tab

Delete character

@item

@geindex KEY_IC (於 curses 模組中)
@anchor{library/curses curses KEY_IC}@anchor{33d2}
@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{33d3}
@deffn {資料} curses.KEY_EIC
@end deffn

@tab

Exit insert char mode

@item

@geindex KEY_CLEAR (於 curses 模組中)
@anchor{library/curses curses KEY_CLEAR}@anchor{33d4}
@deffn {資料} curses.KEY_CLEAR
@end deffn

@tab

Clear screen

@item

@geindex KEY_EOS (於 curses 模組中)
@anchor{library/curses curses KEY_EOS}@anchor{33d5}
@deffn {資料} curses.KEY_EOS
@end deffn

@tab

Clear to end of screen

@item

@geindex KEY_EOL (於 curses 模組中)
@anchor{library/curses curses KEY_EOL}@anchor{33d6}
@deffn {資料} curses.KEY_EOL
@end deffn

@tab

Clear to end of line

@item

@geindex KEY_SF (於 curses 模組中)
@anchor{library/curses curses KEY_SF}@anchor{33d7}
@deffn {資料} curses.KEY_SF
@end deffn

@tab

Scroll 1 line forward

@item

@geindex KEY_SR (於 curses 模組中)
@anchor{library/curses curses KEY_SR}@anchor{33d8}
@deffn {資料} curses.KEY_SR
@end deffn

@tab

Scroll 1 line backward (reverse)

@item

@geindex KEY_NPAGE (於 curses 模組中)
@anchor{library/curses curses KEY_NPAGE}@anchor{33d9}
@deffn {資料} curses.KEY_NPAGE
@end deffn

@tab

Next page

@item

@geindex KEY_PPAGE (於 curses 模組中)
@anchor{library/curses curses KEY_PPAGE}@anchor{33da}
@deffn {資料} curses.KEY_PPAGE
@end deffn

@tab

Previous page

@item

@geindex KEY_STAB (於 curses 模組中)
@anchor{library/curses curses KEY_STAB}@anchor{33db}
@deffn {資料} curses.KEY_STAB
@end deffn

@tab

Set tab

@item

@geindex KEY_CTAB (於 curses 模組中)
@anchor{library/curses curses KEY_CTAB}@anchor{33dc}
@deffn {資料} curses.KEY_CTAB
@end deffn

@tab

Clear tab

@item

@geindex KEY_CATAB (於 curses 模組中)
@anchor{library/curses curses KEY_CATAB}@anchor{33dd}
@deffn {資料} curses.KEY_CATAB
@end deffn

@tab

Clear all tabs

@item

@geindex KEY_ENTER (於 curses 模組中)
@anchor{library/curses curses KEY_ENTER}@anchor{33de}
@deffn {資料} curses.KEY_ENTER
@end deffn

@tab

Enter or send (unreliable)

@item

@geindex KEY_SRESET (於 curses 模組中)
@anchor{library/curses curses KEY_SRESET}@anchor{33df}
@deffn {資料} curses.KEY_SRESET
@end deffn

@tab

Soft (partial) reset (unreliable)

@item

@geindex KEY_RESET (於 curses 模組中)
@anchor{library/curses curses KEY_RESET}@anchor{33e0}
@deffn {資料} curses.KEY_RESET
@end deffn

@tab

Reset or hard reset (unreliable)

@item

@geindex KEY_PRINT (於 curses 模組中)
@anchor{library/curses curses KEY_PRINT}@anchor{33e1}
@deffn {資料} curses.KEY_PRINT
@end deffn

@tab

Print

@item

@geindex KEY_LL (於 curses 模組中)
@anchor{library/curses curses KEY_LL}@anchor{33e2}
@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{33e3}
@deffn {資料} curses.KEY_A1
@end deffn

@tab

Upper left of keypad

@item

@geindex KEY_A3 (於 curses 模組中)
@anchor{library/curses curses KEY_A3}@anchor{33e4}
@deffn {資料} curses.KEY_A3
@end deffn

@tab

Upper right of keypad

@item

@geindex KEY_B2 (於 curses 模組中)
@anchor{library/curses curses KEY_B2}@anchor{33e5}
@deffn {資料} curses.KEY_B2
@end deffn

@tab

Center of keypad

@item

@geindex KEY_C1 (於 curses 模組中)
@anchor{library/curses curses KEY_C1}@anchor{33e6}
@deffn {資料} curses.KEY_C1
@end deffn

@tab

Lower left of keypad

@item

@geindex KEY_C3 (於 curses 模組中)
@anchor{library/curses curses KEY_C3}@anchor{33e7}
@deffn {資料} curses.KEY_C3
@end deffn

@tab

Lower right of keypad

@item

@geindex KEY_BTAB (於 curses 模組中)
@anchor{library/curses curses KEY_BTAB}@anchor{33e8}
@deffn {資料} curses.KEY_BTAB
@end deffn

@tab

Back tab

@item

@geindex KEY_BEG (於 curses 模組中)
@anchor{library/curses curses KEY_BEG}@anchor{33e9}
@deffn {資料} curses.KEY_BEG
@end deffn

@tab

Beg (beginning)

@item

@geindex KEY_CANCEL (於 curses 模組中)
@anchor{library/curses curses KEY_CANCEL}@anchor{33ea}
@deffn {資料} curses.KEY_CANCEL
@end deffn

@tab

Cancel

@item

@geindex KEY_CLOSE (於 curses 模組中)
@anchor{library/curses curses KEY_CLOSE}@anchor{33eb}
@deffn {資料} curses.KEY_CLOSE
@end deffn

@tab

Close

@item

@geindex KEY_COMMAND (於 curses 模組中)
@anchor{library/curses curses KEY_COMMAND}@anchor{33ec}
@deffn {資料} curses.KEY_COMMAND
@end deffn

@tab

Cmd (command)

@item

@geindex KEY_COPY (於 curses 模組中)
@anchor{library/curses curses KEY_COPY}@anchor{33ed}
@deffn {資料} curses.KEY_COPY
@end deffn

@tab

Copy

@item

@geindex KEY_CREATE (於 curses 模組中)
@anchor{library/curses curses KEY_CREATE}@anchor{33ee}
@deffn {資料} curses.KEY_CREATE
@end deffn

@tab

Create

@item

@geindex KEY_END (於 curses 模組中)
@anchor{library/curses curses KEY_END}@anchor{33ef}
@deffn {資料} curses.KEY_END
@end deffn

@tab

End

@item

@geindex KEY_EXIT (於 curses 模組中)
@anchor{library/curses curses KEY_EXIT}@anchor{33f0}
@deffn {資料} curses.KEY_EXIT
@end deffn

@tab

Exit

@item

@geindex KEY_FIND (於 curses 模組中)
@anchor{library/curses curses KEY_FIND}@anchor{33f1}
@deffn {資料} curses.KEY_FIND
@end deffn

@tab

Find

@item

@geindex KEY_HELP (於 curses 模組中)
@anchor{library/curses curses KEY_HELP}@anchor{33f2}
@deffn {資料} curses.KEY_HELP
@end deffn

@tab

Help

@item

@geindex KEY_MARK (於 curses 模組中)
@anchor{library/curses curses KEY_MARK}@anchor{33f3}
@deffn {資料} curses.KEY_MARK
@end deffn

@tab

Mark

@item

@geindex KEY_MESSAGE (於 curses 模組中)
@anchor{library/curses curses KEY_MESSAGE}@anchor{33f4}
@deffn {資料} curses.KEY_MESSAGE
@end deffn

@tab

Message

@item

@geindex KEY_MOVE (於 curses 模組中)
@anchor{library/curses curses KEY_MOVE}@anchor{33f5}
@deffn {資料} curses.KEY_MOVE
@end deffn

@tab

Move

@item

@geindex KEY_NEXT (於 curses 模組中)
@anchor{library/curses curses KEY_NEXT}@anchor{33f6}
@deffn {資料} curses.KEY_NEXT
@end deffn

@tab

Next

@item

@geindex KEY_OPEN (於 curses 模組中)
@anchor{library/curses curses KEY_OPEN}@anchor{33f7}
@deffn {資料} curses.KEY_OPEN
@end deffn

@tab

Open

@item

@geindex KEY_OPTIONS (於 curses 模組中)
@anchor{library/curses curses KEY_OPTIONS}@anchor{33f8}
@deffn {資料} curses.KEY_OPTIONS
@end deffn

@tab

Options

@item

@geindex KEY_PREVIOUS (於 curses 模組中)
@anchor{library/curses curses KEY_PREVIOUS}@anchor{33f9}
@deffn {資料} curses.KEY_PREVIOUS
@end deffn

@tab

Prev (previous)

@item

@geindex KEY_REDO (於 curses 模組中)
@anchor{library/curses curses KEY_REDO}@anchor{33fa}
@deffn {資料} curses.KEY_REDO
@end deffn

@tab

Redo

@item

@geindex KEY_REFERENCE (於 curses 模組中)
@anchor{library/curses curses KEY_REFERENCE}@anchor{33fb}
@deffn {資料} curses.KEY_REFERENCE
@end deffn

@tab

Ref (reference)

@item

@geindex KEY_REFRESH (於 curses 模組中)
@anchor{library/curses curses KEY_REFRESH}@anchor{33fc}
@deffn {資料} curses.KEY_REFRESH
@end deffn

@tab

Refresh

@item

@geindex KEY_REPLACE (於 curses 模組中)
@anchor{library/curses curses KEY_REPLACE}@anchor{33fd}
@deffn {資料} curses.KEY_REPLACE
@end deffn

@tab

Replace

@item

@geindex KEY_RESTART (於 curses 模組中)
@anchor{library/curses curses KEY_RESTART}@anchor{33fe}
@deffn {資料} curses.KEY_RESTART
@end deffn

@tab

Restart

@item

@geindex KEY_RESUME (於 curses 模組中)
@anchor{library/curses curses KEY_RESUME}@anchor{33ff}
@deffn {資料} curses.KEY_RESUME
@end deffn

@tab

Resume

@item

@geindex KEY_SAVE (於 curses 模組中)
@anchor{library/curses curses KEY_SAVE}@anchor{3400}
@deffn {資料} curses.KEY_SAVE
@end deffn

@tab

Save

@item

@geindex KEY_SBEG (於 curses 模組中)
@anchor{library/curses curses KEY_SBEG}@anchor{3401}
@deffn {資料} curses.KEY_SBEG
@end deffn

@tab

Shifted Beg (beginning)

@item

@geindex KEY_SCANCEL (於 curses 模組中)
@anchor{library/curses curses KEY_SCANCEL}@anchor{3402}
@deffn {資料} curses.KEY_SCANCEL
@end deffn

@tab

Shifted Cancel

@item

@geindex KEY_SCOMMAND (於 curses 模組中)
@anchor{library/curses curses KEY_SCOMMAND}@anchor{3403}
@deffn {資料} curses.KEY_SCOMMAND
@end deffn

@tab

Shifted Command

@item

@geindex KEY_SCOPY (於 curses 模組中)
@anchor{library/curses curses KEY_SCOPY}@anchor{3404}
@deffn {資料} curses.KEY_SCOPY
@end deffn

@tab

Shifted Copy

@item

@geindex KEY_SCREATE (於 curses 模組中)
@anchor{library/curses curses KEY_SCREATE}@anchor{3405}
@deffn {資料} curses.KEY_SCREATE
@end deffn

@tab

Shifted Create

@item

@geindex KEY_SDC (於 curses 模組中)
@anchor{library/curses curses KEY_SDC}@anchor{3406}
@deffn {資料} curses.KEY_SDC
@end deffn

@tab

Shifted Delete char

@item

@geindex KEY_SDL (於 curses 模組中)
@anchor{library/curses curses KEY_SDL}@anchor{3407}
@deffn {資料} curses.KEY_SDL
@end deffn

@tab

Shifted Delete line

@item

@geindex KEY_SELECT (於 curses 模組中)
@anchor{library/curses curses KEY_SELECT}@anchor{3408}
@deffn {資料} curses.KEY_SELECT
@end deffn

@tab

Select

@item

@geindex KEY_SEND (於 curses 模組中)
@anchor{library/curses curses KEY_SEND}@anchor{3409}
@deffn {資料} curses.KEY_SEND
@end deffn

@tab

Shifted End

@item

@geindex KEY_SEOL (於 curses 模組中)
@anchor{library/curses curses KEY_SEOL}@anchor{340a}
@deffn {資料} curses.KEY_SEOL
@end deffn

@tab

Shifted Clear line

@item

@geindex KEY_SEXIT (於 curses 模組中)
@anchor{library/curses curses KEY_SEXIT}@anchor{340b}
@deffn {資料} curses.KEY_SEXIT
@end deffn

@tab

Shifted Exit

@item

@geindex KEY_SFIND (於 curses 模組中)
@anchor{library/curses curses KEY_SFIND}@anchor{340c}
@deffn {資料} curses.KEY_SFIND
@end deffn

@tab

Shifted Find

@item

@geindex KEY_SHELP (於 curses 模組中)
@anchor{library/curses curses KEY_SHELP}@anchor{340d}
@deffn {資料} curses.KEY_SHELP
@end deffn

@tab

Shifted Help

@item

@geindex KEY_SHOME (於 curses 模組中)
@anchor{library/curses curses KEY_SHOME}@anchor{340e}
@deffn {資料} curses.KEY_SHOME
@end deffn

@tab

Shifted Home

@item

@geindex KEY_SIC (於 curses 模組中)
@anchor{library/curses curses KEY_SIC}@anchor{340f}
@deffn {資料} curses.KEY_SIC
@end deffn

@tab

Shifted Input

@item

@geindex KEY_SLEFT (於 curses 模組中)
@anchor{library/curses curses KEY_SLEFT}@anchor{3410}
@deffn {資料} curses.KEY_SLEFT
@end deffn

@tab

Shifted Left arrow

@item

@geindex KEY_SMESSAGE (於 curses 模組中)
@anchor{library/curses curses KEY_SMESSAGE}@anchor{3411}
@deffn {資料} curses.KEY_SMESSAGE
@end deffn

@tab

Shifted Message

@item

@geindex KEY_SMOVE (於 curses 模組中)
@anchor{library/curses curses KEY_SMOVE}@anchor{3412}
@deffn {資料} curses.KEY_SMOVE
@end deffn

@tab

Shifted Move

@item

@geindex KEY_SNEXT (於 curses 模組中)
@anchor{library/curses curses KEY_SNEXT}@anchor{3413}
@deffn {資料} curses.KEY_SNEXT
@end deffn

@tab

Shifted Next

@item

@geindex KEY_SOPTIONS (於 curses 模組中)
@anchor{library/curses curses KEY_SOPTIONS}@anchor{3414}
@deffn {資料} curses.KEY_SOPTIONS
@end deffn

@tab

Shifted Options

@item

@geindex KEY_SPREVIOUS (於 curses 模組中)
@anchor{library/curses curses KEY_SPREVIOUS}@anchor{3415}
@deffn {資料} curses.KEY_SPREVIOUS
@end deffn

@tab

Shifted Prev

@item

@geindex KEY_SPRINT (於 curses 模組中)
@anchor{library/curses curses KEY_SPRINT}@anchor{3416}
@deffn {資料} curses.KEY_SPRINT
@end deffn

@tab

Shifted Print

@item

@geindex KEY_SREDO (於 curses 模組中)
@anchor{library/curses curses KEY_SREDO}@anchor{3417}
@deffn {資料} curses.KEY_SREDO
@end deffn

@tab

Shifted Redo

@item

@geindex KEY_SREPLACE (於 curses 模組中)
@anchor{library/curses curses KEY_SREPLACE}@anchor{3418}
@deffn {資料} curses.KEY_SREPLACE
@end deffn

@tab

Shifted Replace

@item

@geindex KEY_SRIGHT (於 curses 模組中)
@anchor{library/curses curses KEY_SRIGHT}@anchor{3419}
@deffn {資料} curses.KEY_SRIGHT
@end deffn

@tab

Shifted Right arrow

@item

@geindex KEY_SRSUME (於 curses 模組中)
@anchor{library/curses curses KEY_SRSUME}@anchor{341a}
@deffn {資料} curses.KEY_SRSUME
@end deffn

@tab

Shifted Resume

@item

@geindex KEY_SSAVE (於 curses 模組中)
@anchor{library/curses curses KEY_SSAVE}@anchor{341b}
@deffn {資料} curses.KEY_SSAVE
@end deffn

@tab

Shifted Save

@item

@geindex KEY_SSUSPEND (於 curses 模組中)
@anchor{library/curses curses KEY_SSUSPEND}@anchor{341c}
@deffn {資料} curses.KEY_SSUSPEND
@end deffn

@tab

Shifted Suspend

@item

@geindex KEY_SUNDO (於 curses 模組中)
@anchor{library/curses curses KEY_SUNDO}@anchor{341d}
@deffn {資料} curses.KEY_SUNDO
@end deffn

@tab

Shifted Undo

@item

@geindex KEY_SUSPEND (於 curses 模組中)
@anchor{library/curses curses KEY_SUSPEND}@anchor{341e}
@deffn {資料} curses.KEY_SUSPEND
@end deffn

@tab

Suspend

@item

@geindex KEY_UNDO (於 curses 模組中)
@anchor{library/curses curses KEY_UNDO}@anchor{341f}
@deffn {資料} curses.KEY_UNDO
@end deffn

@tab

Undo

@item

@geindex KEY_MOUSE (於 curses 模組中)
@anchor{library/curses curses KEY_MOUSE}@anchor{3333}
@deffn {資料} curses.KEY_MOUSE
@end deffn

@tab

Mouse event has occurred

@item

@geindex KEY_RESIZE (於 curses 模組中)
@anchor{library/curses curses KEY_RESIZE}@anchor{3420}
@deffn {資料} curses.KEY_RESIZE
@end deffn

@tab

Terminal resize event

@item

@geindex KEY_MAX (於 curses 模組中)
@anchor{library/curses curses KEY_MAX}@anchor{3421}
@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{33ce,,KEY_F1}, @ref{33ce,,KEY_F2},
@ref{33ce,,KEY_F3}, @ref{33ce,,KEY_F4}) available, and the arrow keys mapped to
@ref{33c8,,KEY_UP}, @ref{33c7,,KEY_DOWN}, @ref{33c9,,KEY_LEFT} and @ref{33ca,,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{3422}
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{187a,,initscr()} has  been called.
@end quotation
@end cartouche


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

ACS code

@tab

含義

@item

@geindex ACS_BBSS (於 curses 模組中)
@anchor{library/curses curses ACS_BBSS}@anchor{3423}
@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{3424}
@deffn {資料} curses.ACS_BLOCK
@end deffn

@tab

solid square block

@item

@geindex ACS_BOARD (於 curses 模組中)
@anchor{library/curses curses ACS_BOARD}@anchor{3425}
@deffn {資料} curses.ACS_BOARD
@end deffn

@tab

board of squares

@item

@geindex ACS_BSBS (於 curses 模組中)
@anchor{library/curses curses ACS_BSBS}@anchor{3426}
@deffn {資料} curses.ACS_BSBS
@end deffn

@tab

alternate name for horizontal line

@item

@geindex ACS_BSSB (於 curses 模組中)
@anchor{library/curses curses ACS_BSSB}@anchor{3427}
@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{3428}
@deffn {資料} curses.ACS_BSSS
@end deffn

@tab

alternate name for top tee

@item

@geindex ACS_BTEE (於 curses 模組中)
@anchor{library/curses curses ACS_BTEE}@anchor{3429}
@deffn {資料} curses.ACS_BTEE
@end deffn

@tab

bottom tee

@item

@geindex ACS_BULLET (於 curses 模組中)
@anchor{library/curses curses ACS_BULLET}@anchor{342a}
@deffn {資料} curses.ACS_BULLET
@end deffn

@tab

bullet

@item

@geindex ACS_CKBOARD (於 curses 模組中)
@anchor{library/curses curses ACS_CKBOARD}@anchor{342b}
@deffn {資料} curses.ACS_CKBOARD
@end deffn

@tab

checker board (stipple)

@item

@geindex ACS_DARROW (於 curses 模組中)
@anchor{library/curses curses ACS_DARROW}@anchor{342c}
@deffn {資料} curses.ACS_DARROW
@end deffn

@tab

arrow pointing down

@item

@geindex ACS_DEGREE (於 curses 模組中)
@anchor{library/curses curses ACS_DEGREE}@anchor{342d}
@deffn {資料} curses.ACS_DEGREE
@end deffn

@tab

degree symbol

@item

@geindex ACS_DIAMOND (於 curses 模組中)
@anchor{library/curses curses ACS_DIAMOND}@anchor{342e}
@deffn {資料} curses.ACS_DIAMOND
@end deffn

@tab

diamond

@item

@geindex ACS_GEQUAL (於 curses 模組中)
@anchor{library/curses curses ACS_GEQUAL}@anchor{342f}
@deffn {資料} curses.ACS_GEQUAL
@end deffn

@tab

greater-than-or-equal-to

@item

@geindex ACS_HLINE (於 curses 模組中)
@anchor{library/curses curses ACS_HLINE}@anchor{3373}
@deffn {資料} curses.ACS_HLINE
@end deffn

@tab

horizontal line

@item

@geindex ACS_LANTERN (於 curses 模組中)
@anchor{library/curses curses ACS_LANTERN}@anchor{3430}
@deffn {資料} curses.ACS_LANTERN
@end deffn

@tab

lantern symbol

@item

@geindex ACS_LARROW (於 curses 模組中)
@anchor{library/curses curses ACS_LARROW}@anchor{3431}
@deffn {資料} curses.ACS_LARROW
@end deffn

@tab

left arrow

@item

@geindex ACS_LEQUAL (於 curses 模組中)
@anchor{library/curses curses ACS_LEQUAL}@anchor{3432}
@deffn {資料} curses.ACS_LEQUAL
@end deffn

@tab

less-than-or-equal-to

@item

@geindex ACS_LLCORNER (於 curses 模組中)
@anchor{library/curses curses ACS_LLCORNER}@anchor{3376}
@deffn {資料} curses.ACS_LLCORNER
@end deffn

@tab

lower left-hand corner

@item

@geindex ACS_LRCORNER (於 curses 模組中)
@anchor{library/curses curses ACS_LRCORNER}@anchor{3377}
@deffn {資料} curses.ACS_LRCORNER
@end deffn

@tab

lower right-hand corner

@item

@geindex ACS_LTEE (於 curses 模組中)
@anchor{library/curses curses ACS_LTEE}@anchor{3433}
@deffn {資料} curses.ACS_LTEE
@end deffn

@tab

left tee

@item

@geindex ACS_NEQUAL (於 curses 模組中)
@anchor{library/curses curses ACS_NEQUAL}@anchor{3434}
@deffn {資料} curses.ACS_NEQUAL
@end deffn

@tab

not-equal sign

@item

@geindex ACS_PI (於 curses 模組中)
@anchor{library/curses curses ACS_PI}@anchor{3435}
@deffn {資料} curses.ACS_PI
@end deffn

@tab

letter pi

@item

@geindex ACS_PLMINUS (於 curses 模組中)
@anchor{library/curses curses ACS_PLMINUS}@anchor{3436}
@deffn {資料} curses.ACS_PLMINUS
@end deffn

@tab

plus-or-minus sign

@item

@geindex ACS_PLUS (於 curses 模組中)
@anchor{library/curses curses ACS_PLUS}@anchor{3437}
@deffn {資料} curses.ACS_PLUS
@end deffn

@tab

big plus sign

@item

@geindex ACS_RARROW (於 curses 模組中)
@anchor{library/curses curses ACS_RARROW}@anchor{3438}
@deffn {資料} curses.ACS_RARROW
@end deffn

@tab

right arrow

@item

@geindex ACS_RTEE (於 curses 模組中)
@anchor{library/curses curses ACS_RTEE}@anchor{3439}
@deffn {資料} curses.ACS_RTEE
@end deffn

@tab

right tee

@item

@geindex ACS_S1 (於 curses 模組中)
@anchor{library/curses curses ACS_S1}@anchor{343a}
@deffn {資料} curses.ACS_S1
@end deffn

@tab

scan line 1

@item

@geindex ACS_S3 (於 curses 模組中)
@anchor{library/curses curses ACS_S3}@anchor{343b}
@deffn {資料} curses.ACS_S3
@end deffn

@tab

scan line 3

@item

@geindex ACS_S7 (於 curses 模組中)
@anchor{library/curses curses ACS_S7}@anchor{343c}
@deffn {資料} curses.ACS_S7
@end deffn

@tab

scan line 7

@item

@geindex ACS_S9 (於 curses 模組中)
@anchor{library/curses curses ACS_S9}@anchor{343d}
@deffn {資料} curses.ACS_S9
@end deffn

@tab

scan line 9

@item

@geindex ACS_SBBS (於 curses 模組中)
@anchor{library/curses curses ACS_SBBS}@anchor{343e}
@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{343f}
@deffn {資料} curses.ACS_SBSB
@end deffn

@tab

alternate name for vertical line

@item

@geindex ACS_SBSS (於 curses 模組中)
@anchor{library/curses curses ACS_SBSS}@anchor{3440}
@deffn {資料} curses.ACS_SBSS
@end deffn

@tab

alternate name for right tee

@item

@geindex ACS_SSBB (於 curses 模組中)
@anchor{library/curses curses ACS_SSBB}@anchor{3441}
@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{3442}
@deffn {資料} curses.ACS_SSBS
@end deffn

@tab

alternate name for bottom tee

@item

@geindex ACS_SSSB (於 curses 模組中)
@anchor{library/curses curses ACS_SSSB}@anchor{3443}
@deffn {資料} curses.ACS_SSSB
@end deffn

@tab

alternate name for left tee

@item

@geindex ACS_SSSS (於 curses 模組中)
@anchor{library/curses curses ACS_SSSS}@anchor{3444}
@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{3445}
@deffn {資料} curses.ACS_STERLING
@end deffn

@tab

pound sterling

@item

@geindex ACS_TTEE (於 curses 模組中)
@anchor{library/curses curses ACS_TTEE}@anchor{3446}
@deffn {資料} curses.ACS_TTEE
@end deffn

@tab

top tee

@item

@geindex ACS_UARROW (於 curses 模組中)
@anchor{library/curses curses ACS_UARROW}@anchor{3447}
@deffn {資料} curses.ACS_UARROW
@end deffn

@tab

up arrow

@item

@geindex ACS_ULCORNER (於 curses 模組中)
@anchor{library/curses curses ACS_ULCORNER}@anchor{3374}
@deffn {資料} curses.ACS_ULCORNER
@end deffn

@tab

upper left corner

@item

@geindex ACS_URCORNER (於 curses 模組中)
@anchor{library/curses curses ACS_URCORNER}@anchor{3375}
@deffn {資料} curses.ACS_URCORNER
@end deffn

@tab

upper right corner

@item

@geindex ACS_VLINE (於 curses 模組中)
@anchor{library/curses curses ACS_VLINE}@anchor{3372}
@deffn {資料} curses.ACS_VLINE
@end deffn

@tab

vertical line

@end multitable


The following table lists mouse button constants used by @ref{3332,,getmouse()}:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Mouse button constant

@tab

含義

@item

@geindex BUTTONn_PRESSED (於 curses 模組中)
@anchor{library/curses curses BUTTONn_PRESSED}@anchor{3334}
@deffn {資料} curses.BUTTONn_PRESSED
@end deffn

@tab

Mouse button `n' pressed

@item

@geindex BUTTONn_RELEASED (於 curses 模組中)
@anchor{library/curses curses BUTTONn_RELEASED}@anchor{3335}
@deffn {資料} curses.BUTTONn_RELEASED
@end deffn

@tab

Mouse button `n' released

@item

@geindex BUTTONn_CLICKED (於 curses 模組中)
@anchor{library/curses curses BUTTONn_CLICKED}@anchor{3336}
@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{3337}
@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{3338}
@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{3339}
@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{333a}
@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{333b}
@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

顏色

@item

@geindex COLOR_BLACK (於 curses 模組中)
@anchor{library/curses curses COLOR_BLACK}@anchor{3448}
@deffn {資料} curses.COLOR_BLACK
@end deffn

@tab

黑

@item

@geindex COLOR_BLUE (於 curses 模組中)
@anchor{library/curses curses COLOR_BLUE}@anchor{3449}
@deffn {資料} curses.COLOR_BLUE
@end deffn

@tab

藍

@item

@geindex COLOR_CYAN (於 curses 模組中)
@anchor{library/curses curses COLOR_CYAN}@anchor{344a}
@deffn {資料} curses.COLOR_CYAN
@end deffn

@tab

Cyan (light greenish blue)

@item

@geindex COLOR_GREEN (於 curses 模組中)
@anchor{library/curses curses COLOR_GREEN}@anchor{344b}
@deffn {資料} curses.COLOR_GREEN
@end deffn

@tab

綠

@item

@geindex COLOR_MAGENTA (於 curses 模組中)
@anchor{library/curses curses COLOR_MAGENTA}@anchor{344c}
@deffn {資料} curses.COLOR_MAGENTA
@end deffn

@tab

Magenta (purplish red)

@item

@geindex COLOR_RED (於 curses 模組中)
@anchor{library/curses curses COLOR_RED}@anchor{344d}
@deffn {資料} curses.COLOR_RED
@end deffn

@tab

紅

@item

@geindex COLOR_WHITE (於 curses 模組中)
@anchor{library/curses curses COLOR_WHITE}@anchor{344e}
@deffn {資料} curses.COLOR_WHITE
@end deffn

@tab

白

@item

@geindex COLOR_YELLOW (於 curses 模組中)
@anchor{library/curses curses COLOR_YELLOW}@anchor{344f}
@deffn {資料} curses.COLOR_YELLOW
@end deffn

@tab

Yellow

@end multitable


@node curses textpad --- Text input widget for curses programs,curses ascii --- ASCII 字元的工具程式,curses --- 字元儲存格顯示的終端處理,命令列介面函式庫
@anchor{library/curses curses-textpad-text-input-widget-for-curses-programs}@anchor{3450}@anchor{library/curses module-curses textpad}@anchor{32}
@subsection @code{curses.textpad} --- Text input widget for curses programs


@geindex module; curses.textpad

The @ref{32,,curses.textpad} module provides a @ref{3451,,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.

@ref{32,,curses.textpad} 模組定義了以下函式：

@geindex rectangle() (於 curses.textpad 模組中)
@anchor{library/curses curses textpad rectangle}@anchor{3452}
@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{3453}@anchor{library/curses textbox-objects}@anchor{3454}
@subsubsection Textbox objects


You can instantiate a @ref{3451,,Textbox} object as follows:

@geindex Textbox (curses.textpad 中的類別)
@anchor{library/curses curses textpad Textbox}@anchor{3451}
@deffn {類別} curses.textpad.Textbox (win)

Return a textbox widget object.  The `win' argument should be a curses
@ref{18e3,,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{3455,,stripspaces} flag is initially on.

@ref{3451,,Textbox} objects have the following methods:

@geindex edit() (curses.textpad.Textbox 的方法)
@anchor{library/curses curses textpad Textbox edit}@anchor{3456}
@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{3455,,stripspaces} attribute.
@end deffn

@geindex do_command() (curses.textpad.Textbox 的方法)
@anchor{library/curses curses textpad Textbox do_command}@anchor{3457}
@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{33c9,,KEY_LEFT}

@tab

@code{Control}-@code{B}

@item

@ref{33ca,,KEY_RIGHT}

@tab

@code{Control}-@code{F}

@item

@ref{33c8,,KEY_UP}

@tab

@code{Control}-@code{P}

@item

@ref{33c7,,KEY_DOWN}

@tab

@code{Control}-@code{N}

@item

@ref{33cc,,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{3458}
@deffn {方法} gather ()

Return the window contents as a string; whether blanks in the
window are included is affected by the @ref{3455,,stripspaces} member.
@end deffn

@geindex stripspaces (curses.textpad.Textbox 的屬性)
@anchor{library/curses curses textpad Textbox stripspaces}@anchor{3455}
@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 --- ASCII 字元的工具程式,curses panel --- curses 的面板堆疊擴充,curses textpad --- Text input widget for curses programs,命令列介面函式庫
@anchor{library/curses ascii doc}@anchor{3459}@anchor{library/curses ascii curses-ascii-utilities-for-ascii-characters}@anchor{345a}@anchor{library/curses ascii module-curses ascii}@anchor{30}@anchor{library/curses ascii translation-repo}@anchor{345b}
@subsection @code{curses.ascii} --- ASCII 字元的工具程式


@geindex module; curses.ascii

`原始碼：'Lib/curses/ascii.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/curses/ascii.py}


__________________________________________________________________


The @ref{30,,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

名稱

@tab

含義

@item

@geindex NUL (於 curses.ascii 模組中)
@anchor{library/curses ascii curses ascii NUL}@anchor{345c}
@deffn {資料} curses.ascii.NUL
@end deffn

@tab

@item

@geindex SOH (於 curses.ascii 模組中)
@anchor{library/curses ascii curses ascii SOH}@anchor{345d}
@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{345e}
@deffn {資料} curses.ascii.STX
@end deffn

@tab

Start of text

@item

@geindex ETX (於 curses.ascii 模組中)
@anchor{library/curses ascii curses ascii ETX}@anchor{345f}
@deffn {資料} curses.ascii.ETX
@end deffn

@tab

End of text

@item

@geindex EOT (於 curses.ascii 模組中)
@anchor{library/curses ascii curses ascii EOT}@anchor{3460}
@deffn {資料} curses.ascii.EOT
@end deffn

@tab

End of transmission

@item

@geindex ENQ (於 curses.ascii 模組中)
@anchor{library/curses ascii curses ascii ENQ}@anchor{3461}
@deffn {資料} curses.ascii.ENQ
@end deffn

@tab

Enquiry, goes with @ref{3462,,ACK} flow control

@item

@geindex ACK (於 curses.ascii 模組中)
@anchor{library/curses ascii curses ascii ACK}@anchor{3462}
@deffn {資料} curses.ascii.ACK
@end deffn

@tab

Acknowledgement

@item

@geindex BEL (於 curses.ascii 模組中)
@anchor{library/curses ascii curses ascii BEL}@anchor{3463}
@deffn {資料} curses.ascii.BEL
@end deffn

@tab

Bell

@item

@geindex BS (於 curses.ascii 模組中)
@anchor{library/curses ascii curses ascii BS}@anchor{3464}
@deffn {資料} curses.ascii.BS
@end deffn

@tab

Backspace

@item

@geindex TAB (於 curses.ascii 模組中)
@anchor{library/curses ascii curses ascii TAB}@anchor{3465}
@deffn {資料} curses.ascii.TAB
@end deffn

@tab

Tab

@item

@geindex HT (於 curses.ascii 模組中)
@anchor{library/curses ascii curses ascii HT}@anchor{3466}
@deffn {資料} curses.ascii.HT
@end deffn

@tab

Alias for @ref{3465,,TAB}: "Horizontal tab"

@item

@geindex LF (於 curses.ascii 模組中)
@anchor{library/curses ascii curses ascii LF}@anchor{3467}
@deffn {資料} curses.ascii.LF
@end deffn

@tab

Line feed

@item

@geindex NL (於 curses.ascii 模組中)
@anchor{library/curses ascii curses ascii NL}@anchor{3468}
@deffn {資料} curses.ascii.NL
@end deffn

@tab

Alias for @ref{3467,,LF}: "New line"

@item

@geindex VT (於 curses.ascii 模組中)
@anchor{library/curses ascii curses ascii VT}@anchor{3469}
@deffn {資料} curses.ascii.VT
@end deffn

@tab

Vertical tab

@item

@geindex FF (於 curses.ascii 模組中)
@anchor{library/curses ascii curses ascii FF}@anchor{346a}
@deffn {資料} curses.ascii.FF
@end deffn

@tab

Form feed

@item

@geindex CR (於 curses.ascii 模組中)
@anchor{library/curses ascii curses ascii CR}@anchor{346b}
@deffn {資料} curses.ascii.CR
@end deffn

@tab

Carriage return

@item

@geindex SO (於 curses.ascii 模組中)
@anchor{library/curses ascii curses ascii SO}@anchor{346c}
@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{346d}
@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{346e}
@deffn {資料} curses.ascii.DLE
@end deffn

@tab

Data-link escape

@item

@geindex DC1 (於 curses.ascii 模組中)
@anchor{library/curses ascii curses ascii DC1}@anchor{346f}
@deffn {資料} curses.ascii.DC1
@end deffn

@tab

XON, for flow control

@item

@geindex DC2 (於 curses.ascii 模組中)
@anchor{library/curses ascii curses ascii DC2}@anchor{3470}
@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{3471}
@deffn {資料} curses.ascii.DC3
@end deffn

@tab

XOFF, for flow control

@item

@geindex DC4 (於 curses.ascii 模組中)
@anchor{library/curses ascii curses ascii DC4}@anchor{3472}
@deffn {資料} curses.ascii.DC4
@end deffn

@tab

Device control 4

@item

@geindex NAK (於 curses.ascii 模組中)
@anchor{library/curses ascii curses ascii NAK}@anchor{3473}
@deffn {資料} curses.ascii.NAK
@end deffn

@tab

Negative acknowledgement

@item

@geindex SYN (於 curses.ascii 模組中)
@anchor{library/curses ascii curses ascii SYN}@anchor{3474}
@deffn {資料} curses.ascii.SYN
@end deffn

@tab

Synchronous idle

@item

@geindex ETB (於 curses.ascii 模組中)
@anchor{library/curses ascii curses ascii ETB}@anchor{3475}
@deffn {資料} curses.ascii.ETB
@end deffn

@tab

End transmission block

@item

@geindex CAN (於 curses.ascii 模組中)
@anchor{library/curses ascii curses ascii CAN}@anchor{3476}
@deffn {資料} curses.ascii.CAN
@end deffn

@tab

Cancel

@item

@geindex EM (於 curses.ascii 模組中)
@anchor{library/curses ascii curses ascii EM}@anchor{3477}
@deffn {資料} curses.ascii.EM
@end deffn

@tab

End of medium

@item

@geindex SUB (於 curses.ascii 模組中)
@anchor{library/curses ascii curses ascii SUB}@anchor{3478}
@deffn {資料} curses.ascii.SUB
@end deffn

@tab

Substitute

@item

@geindex ESC (於 curses.ascii 模組中)
@anchor{library/curses ascii curses ascii ESC}@anchor{3479}
@deffn {資料} curses.ascii.ESC
@end deffn

@tab

Escape

@item

@geindex FS (於 curses.ascii 模組中)
@anchor{library/curses ascii curses ascii FS}@anchor{347a}
@deffn {資料} curses.ascii.FS
@end deffn

@tab

File separator

@item

@geindex GS (於 curses.ascii 模組中)
@anchor{library/curses ascii curses ascii GS}@anchor{347b}
@deffn {資料} curses.ascii.GS
@end deffn

@tab

Group separator

@item

@geindex RS (於 curses.ascii 模組中)
@anchor{library/curses ascii curses ascii RS}@anchor{347c}
@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{347d}
@deffn {資料} curses.ascii.US
@end deffn

@tab

Unit separator

@item

@geindex SP (於 curses.ascii 模組中)
@anchor{library/curses ascii curses ascii SP}@anchor{347e}
@deffn {資料} curses.ascii.SP
@end deffn

@tab

Space

@item

@geindex DEL (於 curses.ascii 模組中)
@anchor{library/curses ascii curses ascii DEL}@anchor{347f}
@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{3480}
@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{3481}
@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{3482}
@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{3483}
@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{3484}
@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{3485}
@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{3486}
@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{3487}
@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{3488}
@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{3489}
@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{348a}
@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{348b}
@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{348c}
@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{348d}
@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{348e}
@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{21ef,,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{348f}
@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{3490}
@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{3491}
@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 ^ （插入符號）;於 curses 模組中
@geindex ! （驚嘆號）;於 curses 模組中

@geindex unctrl() (於 curses.ascii 模組中)
@anchor{library/curses ascii curses ascii unctrl}@anchor{3492}
@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{3493}
@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 --- curses 的面板堆疊擴充,cmd --- 以列為導向的命令直譯器支援,curses ascii --- ASCII 字元的工具程式,命令列介面函式庫
@anchor{library/curses panel doc}@anchor{3494}@anchor{library/curses panel curses-panel-a-panel-stack-extension-for-curses}@anchor{3495}@anchor{library/curses panel module-curses panel}@anchor{31}@anchor{library/curses panel translation-repo}@anchor{3496}
@subsection @code{curses.panel} --- 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
* 函式: 函式<7>. 
* Panel Objects:: 

@end menu

@node 函式<7>,Panel Objects,,curses panel --- curses 的面板堆疊擴充
@anchor{library/curses panel cursespanel-functions}@anchor{3497}@anchor{library/curses panel functions}@anchor{3498}
@subsubsection 函式


@ref{31,,curses.panel} 模組定義了以下函式：

@geindex bottom_panel() (於 curses.panel 模組中)
@anchor{library/curses panel curses panel bottom_panel}@anchor{3499}
@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{349a}
@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{349b}
@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{349c}
@deffn {函式} curses.panel.update_panels ()

Updates the virtual screen after changes in the panel stack. This does not call
@ref{3328,,curses.doupdate()}, so you'll have to do this yourself.
@end deffn

@node Panel Objects,,函式<7>,curses panel --- curses 的面板堆疊擴充
@anchor{library/curses panel curses-panel-objects}@anchor{349d}@anchor{library/curses panel panel-objects}@anchor{349e}
@subsubsection Panel Objects


Panel objects, as returned by @ref{349a,,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{349f}
@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{34a0}
@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{34a1}
@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{34a2}
@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{34a3}
@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{34a4}
@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{34a5}
@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{34a6}
@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{34a7}
@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{34a8}
@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{34a9}
@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{34aa}
@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 --- 以列為導向的命令直譯器支援,,curses panel --- curses 的面板堆疊擴充,命令列介面函式庫
@anchor{library/cmd doc}@anchor{34ab}@anchor{library/cmd cmd-support-for-line-oriented-command-interpreters}@anchor{34ac}@anchor{library/cmd module-cmd}@anchor{1a}@anchor{library/cmd translation-repo}@anchor{34ad}
@subsection @code{cmd} --- 以列為導向的命令直譯器支援


@geindex module; cmd

`原始碼：'Lib/cmd.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/cmd.py}


__________________________________________________________________


@ref{17cc,,Cmd} 類別提供了一個簡單的架構，用於撰寫列導向的命令直譯器。這類直譯器常用於測試控制工具、管理工具以及日後將包裝於更高階介面的原型中。

@geindex Cmd (cmd 中的類別)
@anchor{library/cmd cmd Cmd}@anchor{17cc}
@deffn {類別} cmd.Cmd (completekey='tab', stdin=None, stdout=None)

@ref{17cc,,Cmd} 實例或其子類別實例是一種列導向的直譯器架構。通常沒有必要直接實例化 @ref{17cc,,Cmd} 本身；它更適合作為你自定義的直譯器類別的父類別，讓你能繼承 @ref{17cc,,Cmd} 的方法，並封裝動作方法。

可選引數 `completekey' 是 @ref{bf,,readline} 模組中用於自動完成的按鍵名稱；預設為 @code{Tab}。若 `completekey' 不為 @ref{87e,,None} 且 @ref{bf,,readline} 可用，則會自動啟用命令自動完成功能。

預設值 @code{'tab'} 會被特殊處理，使其在所有的 @ref{1977,,readline.backend} 中皆代表 @code{Tab} 鍵。具體來說，若 @ref{1977,,readline.backend} 為 @code{editline}，則 @code{Cmd} 會改用 @code{'^I'} 取代 @code{'tab'}。請注意，其他值不會有此處理方式，且可能僅能在特定的後端中適用。

可選引數 `stdin' 與 `stdout' 用來指定 Cmd 實例或其子類別實例所使用的輸入與輸出檔案物件。若未指定，預設為 @ref{758,,sys.stdin} 與 @ref{cc4,,sys.stdout}。

若你希望使用指定的 `stdin'，請務必將該實例的 @ref{34ae,,use_rawinput} 屬性設為 @code{False}，否則 `stdin' 會被忽略。


在 3.13 版的變更: 對於 @code{editline}，@code{completekey='tab'} 會被替換為 @code{'^I'}。

@end deffn

@menu
* Cmd 物件:: 
* Cmd 範例:: 

@end menu

@node Cmd 物件,Cmd 範例,,cmd --- 以列為導向的命令直譯器支援
@anchor{library/cmd cmd-objects}@anchor{34af}@anchor{library/cmd id1}@anchor{34b0}
@subsubsection Cmd 物件


@ref{17cc,,Cmd} 實例具有以下方法：

@geindex cmdloop() (cmd.Cmd 的方法)
@anchor{library/cmd cmd Cmd cmdloop}@anchor{34b1}
@deffn {方法} Cmd.cmdloop (intro=None)

重複顯示提示字元、接收輸入、剖析接收到的輸入字串前綴，並派發給動作方法，將其餘部分作為引數傳遞給它們

此可選引數為橫幅或導言字串，會在首次顯示提示字元前輸出（此值會覆寫 @ref{34b2,,intro} 類別屬性）。

如果已載入 @ref{bf,,readline} 模組，輸入將自動繼承類似 @code{bash} 的歷史紀錄編輯功能（例如 @code{Control}-@code{P} 可向上捲動至上一個命令，@code{Control}-@code{N} 向下捲動至下一個命令，@code{Control}-@code{F} 非破壞性地將游標向右移動，@code{Control}-@code{B} 非破壞性地將游標向左移動等）。

當輸入為檔案結尾（EOF）時，會傳回字串 @code{'EOF'}。

@geindex ? （問號）;於 command interpreter（命令直譯器）中
@geindex ! （驚嘆號）;於 command interpreter（命令直譯器）中

直譯器實例僅當存在 @code{do_foo()} 方法時，才會識別命令名稱 @code{foo}。作為特殊情況，以字元 @code{'?'} 開頭的列會被派發至 @ref{197c,,do_help()} 方法；另一個特殊情況是，以字元 @code{'!'} 開頭的列會被派發至 @code{do_shell()} 方法（若該方法已定義）。

當 @ref{34b3,,postcmd()} 方法回傳真值時，此方法將會結束。傳遞給 @ref{34b3,,postcmd()} 的 `stop' 引數是該命令對應的 @code{do_*()} 方法的回傳值。

如果啟用了自動完成，命令的自動完成將會自動執行，而命令引數的自動完成則是透過呼叫 @code{complete_foo()} 方法並傳入 `text'、`line'、`begidx' 和 `endidx' 引數來處理。`text' 是要比對的字串前綴：所有回傳的符合項都必須以此字串開頭。`line' 是目前的輸入列（前置空白會被移除），`begidx' 和 `endidx' 則分別是前綴字串的起始與結束索引，可用來根據引數所在的位置提供不同的自動完成結果。
@end deffn

@geindex do_help() (cmd.Cmd 的方法)
@anchor{library/cmd cmd Cmd do_help}@anchor{197c}
@deffn {方法} Cmd.do_help (arg)

所有 @ref{17cc,,Cmd} 的子類別都會繼承預先定義的 @code{do_help()} 方法。當此方法接收到引數 @code{'bar'} 時，會呼叫對應的 @code{help_bar()} 方法；若該方法不存在，則會列印 @code{do_bar()} 的說明字串（若有的話）。若未提供任何引數，@code{do_help()} 會列出所有可用的說明主題（也就是所有具有對應 @code{help_*()} 方法或有說明字串的命令），並且也會列出所有尚未記錄的命令。
@end deffn

@geindex onecmd() (cmd.Cmd 的方法)
@anchor{library/cmd cmd Cmd onecmd}@anchor{34b4}
@deffn {方法} Cmd.onecmd (str)

將引數視為在回應提示字元時所輸入的內容來直譯。這個方法可以被覆寫，但通常不需要這麼做；參見 @ref{34b5,,precmd()} 與 @ref{34b3,,postcmd()} 方法，它們提供實用的執行勾點（hook）。此方法的回傳值是一個旗標，用來指出是否應該停止直譯器對命令的直譯。若有對應 `str' 命令的 @code{do_*()} 方法，則會回傳該方法的回傳值；否則，回傳值將來自 @ref{34b6,,default()} 方法。
@end deffn

@geindex emptyline() (cmd.Cmd 的方法)
@anchor{library/cmd cmd Cmd emptyline}@anchor{34b7}
@deffn {方法} Cmd.emptyline ()

在回應提示字元時輸入空白列，會呼叫此方法。若此方法未被覆寫，則會重復上一次輸入的非空命令。
@end deffn

@geindex default() (cmd.Cmd 的方法)
@anchor{library/cmd cmd Cmd default}@anchor{34b6}
@deffn {方法} Cmd.default (line)

當輸入列中的命令前綴無法辨識時，會呼叫此方法。若此方法未被覆寫，則會輸出並回傳錯誤訊息。
@end deffn

@geindex completedefault() (cmd.Cmd 的方法)
@anchor{library/cmd cmd Cmd completedefault}@anchor{34b8}
@deffn {方法} Cmd.completedefault (text, line, begidx, endidx)

當沒有對應特定命令的 @code{complete_*()} 方法時，會呼叫此方法以完成輸入列。預設會回傳空串列。
@end deffn

@geindex columnize() (cmd.Cmd 的方法)
@anchor{library/cmd cmd Cmd columnize}@anchor{1b1d}
@deffn {方法} Cmd.columnize (list, displaywidth=80)

此方法用來將字串串列顯示為緊湊的欄集合。每一欄的寬度僅足以容納其內容，各欄之間以兩個空格分隔，以提高可讀性。
@end deffn

@geindex precmd() (cmd.Cmd 的方法)
@anchor{library/cmd cmd Cmd precmd}@anchor{34b5}
@deffn {方法} Cmd.precmd (line)

勾點方法會在直譯命令列 `line' 前執行，但會在提示字元產生並顯示後才觸發。這個方法在 @ref{17cc,,Cmd} 類別中為 stub，預期由子類別覆寫。回傳值會作為 @ref{34b4,,onecmd()} 方法所執行的命令；@ref{34b5,,precmd()} 的實作可以重寫該命令，或直接回傳未變更的 `line'。
@end deffn

@geindex postcmd() (cmd.Cmd 的方法)
@anchor{library/cmd cmd Cmd postcmd}@anchor{34b3}
@deffn {方法} Cmd.postcmd (stop, line)

勾點方法會在命令派發完成後執行。這個方法在 @ref{17cc,,Cmd} 類別中為 stub，預期由子類別覆寫。`line' 是剛剛執行的命令列，而 `stop' 是一個旗標，用來指出在呼叫 @ref{34b3,,postcmd()} 後是否應終止執行；該值即為 @ref{34b4,,onecmd()} 方法的回傳值。本方法的回傳值將會更新內部的 `stop' 旗標；若回傳 false，則會繼續進行直譯。
@end deffn

@geindex preloop() (cmd.Cmd 的方法)
@anchor{library/cmd cmd Cmd preloop}@anchor{34b9}
@deffn {方法} Cmd.preloop ()

當 @ref{34b1,,cmdloop()} 被呼叫時，此勾點方法會執行一次。這個方法在 @ref{17cc,,Cmd} 類別中為 stub，預期由子類別覆寫。
@end deffn

@geindex postloop() (cmd.Cmd 的方法)
@anchor{library/cmd cmd Cmd postloop}@anchor{34ba}
@deffn {方法} Cmd.postloop ()

當 @ref{34b1,,cmdloop()} 即將回傳時，此勾點方法會執行一次。這個方法在 @ref{17cc,,Cmd} 類別中為 stub，預期由子類別覆寫。
@end deffn

@ref{17cc,,Cmd} 子類別的實例包含一些公開的實例變數：

@geindex prompt (cmd.Cmd 的屬性)
@anchor{library/cmd cmd Cmd prompt}@anchor{34bb}
@deffn {屬性} Cmd.prompt

用來請求輸入的提示字元。
@end deffn

@geindex identchars (cmd.Cmd 的屬性)
@anchor{library/cmd cmd Cmd identchars}@anchor{34bc}
@deffn {屬性} Cmd.identchars

可作為命令前綴的字元字串
@end deffn

@geindex lastcmd (cmd.Cmd 的屬性)
@anchor{library/cmd cmd Cmd lastcmd}@anchor{34bd}
@deffn {屬性} Cmd.lastcmd

最後一個遇到的非空命令前綴
@end deffn

@geindex cmdqueue (cmd.Cmd 的屬性)
@anchor{library/cmd cmd Cmd cmdqueue}@anchor{34be}
@deffn {屬性} Cmd.cmdqueue

排入佇列的輸入列串列。當 @ref{34b1,,cmdloop()} 需要新輸入時，會檢查 cmdqueue 串列；若不為空，其元素將依序處理，就如同它們是在提示字元中輸入的一樣。
@end deffn

@geindex intro (cmd.Cmd 的屬性)
@anchor{library/cmd cmd Cmd intro}@anchor{34b2}
@deffn {屬性} Cmd.intro

作為簡介或橫幅的字串。可透過為 @ref{34b1,,cmdloop()} 方法提供引數來覆寫此內容。
@end deffn

@geindex doc_header (cmd.Cmd 的屬性)
@anchor{library/cmd cmd Cmd doc_header}@anchor{34bf}
@deffn {屬性} Cmd.doc_header

若說明輸出包含已記錄命令的區段，則會顯示的標頭字串。
@end deffn

@geindex misc_header (cmd.Cmd 的屬性)
@anchor{library/cmd cmd Cmd misc_header}@anchor{34c0}
@deffn {屬性} Cmd.misc_header

若說明輸出包含雜項說明主題的區段（也就是存在 @code{help_*()} 方法但沒有對應的 @code{do_*()} 方法），則會顯示的標頭字串。
@end deffn

@geindex undoc_header (cmd.Cmd 的屬性)
@anchor{library/cmd cmd Cmd undoc_header}@anchor{34c1}
@deffn {屬性} Cmd.undoc_header

若說明輸出包含未記錄命令的區段（也就是存在 @code{do_*()} 方法但沒有對應的 @code{help_*()} 方法），則會顯示的標頭字串。
@end deffn

@geindex ruler (cmd.Cmd 的屬性)
@anchor{library/cmd cmd Cmd ruler}@anchor{34c2}
@deffn {屬性} Cmd.ruler

用於在說明訊息的標頭下方繪製分隔線的字元。若為空，則不會繪製分隔線。預設為 @code{'='}。
@end deffn

@geindex use_rawinput (cmd.Cmd 的屬性)
@anchor{library/cmd cmd Cmd use_rawinput}@anchor{34ae}
@deffn {屬性} Cmd.use_rawinput

一個旗標，預設為 true。若為 true，@ref{34b1,,cmdloop()} 會使用 @ref{14d9,,input()} 來顯示提示字元並讀取下一個命令；若為 false，則會改用 @ref{cc4,,sys.stdout.write()} 和 @ref{758,,sys.stdin.readline()}。（這表示在支援的系統中，透過 import  @ref{bf,,readline} module，直譯器將自動支援類似 @code{Emacs} 的列編輯與命令歷史快捷鍵。）
@end deffn

@node Cmd 範例,,Cmd 物件,cmd --- 以列為導向的命令直譯器支援
@anchor{library/cmd cmd-example}@anchor{34c3}@anchor{library/cmd id2}@anchor{34c4}
@subsubsection Cmd 範例


@ref{1a,,cmd} module 主要用於建構自訂 shell，讓使用者能以互動方式操作程式。

本節將示範如何以 @ref{107,,turtle} module 中的幾個命令為基礎，建立一個簡單的 shell。

像是 @ref{34c5,,forward()} 這樣的基本 turtle 命令，可透過新增名為 @code{do_forward()} 的方法加入至 @ref{17cc,,Cmd} 子類別中。傳入的引數會轉換為數值，並傳送給 turtle 模組。該方法的說明字串會用於 shell 所提供的說明功能中。

此範例同時包含一個簡單的錄製與重播功能，其實作方式是透過 @ref{34b5,,precmd()} 方法，負責將輸入轉為小寫並寫入檔案。@code{do_playback()} 方法則會讀取該檔案，並將錄製的命令加入 @ref{34be,,cmdqueue} 中以供立即重播:

@example
import cmd, sys
from turtle import *

class TurtleShell(cmd.Cmd):
    intro = '歡迎來到 turtle shell。輸入 help 或 ? 來列出命令。\n'
    prompt = '(turtle) '
    file = None

    # ----- 基本烏龜命令 -----
    def do_forward(self, arg):
        '將烏龜向前移動指定的距離： FORWARD 10'
        forward(*parse(arg))
    def do_right(self, arg):
        '將烏龜右轉指定的角度： RIGHT 20'
        right(*parse(arg))
    def do_left(self, arg):
        '將烏龜左轉指定的角度： LEFT 90'
        left(*parse(arg))
    def do_goto(self, arg):
        '將烏龜移動到指定的絕對位置並改變方向。 GOTO 100 200'
        goto(*parse(arg))
    def do_home(self, arg):
        '將烏龜返回起始位置： HOME'
        home()
    def do_circle(self, arg):
        '畫出指定半徑、範圍和步數的圓： CIRCLE 50'
        circle(*parse(arg))
    def do_position(self, arg):
        '顯示當前烏龜位置： POSITION'
        print('當前位置是 %d %d\n' % position())
    def do_heading(self, arg):
        '顯示當前烏龜方向角度： HEADING'
        print('當前方向是 %d\n' % (heading(),))
    def do_color(self, arg):
        '設定顏色： COLOR BLUE'
        color(arg.lower())
    def do_undo(self, arg):
        '撤銷（重複）最後一次烏龜動作： UNDO'
    def do_reset(self, arg):
        '清除畫面並將烏龜返回到中心： RESET'
        reset()
    def do_bye(self, arg):
        '停止錄製、關閉烏龜視窗並退出： BYE'
        print('感謝使用 Turtle')
        self.close()
        bye()
        return True

    # ----- 錄製與回放 -----
    def do_record(self, arg):
        '將未來命令儲存至檔案： RECORD rose.cmd'
        self.file = open(arg, 'w')
    def do_playback(self, arg):
        '從檔案回放命令： 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):
    '將一串零個或多個數字轉換為引數 tuple'
    return tuple(map(int, arg.split()))

if __name__ == '__main__':
    TurtleShell().cmdloop()
@end example

以下是與 turtle shell 的一段範例互動，展示了說明功能、使用空白列重複執行命令，以及簡單的錄製與重播功能：

@example
歡迎來到 turtle shell。輸入 help 或 ? 來列出命令。

(turtle) ?

已記錄的命令（輸入 help <主題>）：
========================================
bye     color    goto     home  playback  record  right
circle  forward  heading  left  position  reset   undo

(turtle) help forward
將烏龜向前移動指定的距離： FORWARD 10
(turtle) record spiral.cmd
(turtle) position
當前位置是 0 0

(turtle) heading
當前方向是 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
當前方向是 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
當前位置是 0 0

當前方向是 0

當前方向是 180

(turtle) bye
感謝使用 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,網路與行程間通訊,命令列介面函式庫,Python 標準函式庫 Standard Library
@anchor{library/concurrency doc}@anchor{34c6}@anchor{library/concurrency concurrency}@anchor{34c7}@anchor{library/concurrency concurrent-execution}@anchor{34c8}@anchor{library/concurrency translation-repo}@anchor{34c9}
@section 並行執行 (Concurrent Execution)


本章節描述的模組在程式的並行執行上提供支援。選擇要使用哪一個工具則取決於是執行什麼樣的任務（CPU 密集或 IO 密集）與偏好的開發風格（事件驅動協作式多工處理或搶占式多工處理）。以下為此章節總覽：

@menu
* threading: threading --- 基於執行緒的平行性. 基於執行緒的平行性
* multiprocessing: multiprocessing --- 以行程為基礎的平行性. 以行程為基礎的平行性
* multiprocessing.shared_memory: multiprocessing shared_memory --- 對於共享記憶體的跨行程直接存取. 對於共享記憶體的跨行程直接存取
* concurrent 套件:: 
* concurrent.futures: concurrent futures --- 啟動平行任務. 啟動平行任務
* concurrent.interpreters: concurrent interpreters --- 在同一個行程中使用多個直譯器. 在同一個行程中使用多個直譯器
* subprocess: subprocess --- 子行程管理. 子行程管理
* sched: sched --- 事件排程器. 事件排程器
* queue: queue --- 同步佇列 synchronized queue 類別. 同步佇列 (synchronized queue) 類別
* contextvars: contextvars --- 情境變數. 情境變數
* _thread: _thread --- 低階執行緒 API. 低階執行緒 API

@end menu

@node threading --- 基於執行緒的平行性,multiprocessing --- 以行程為基礎的平行性,,並行執行 Concurrent Execution
@anchor{library/threading doc}@anchor{34ca}@anchor{library/threading module-threading}@anchor{f3}@anchor{library/threading threading-thread-based-parallelism}@anchor{34cb}
@subsection @code{threading} --- 基於執行緒的平行性


@geindex module; threading

`原始碼：'Lib/threading.py@footnote{https://github.com/python/cpython/tree/3.14/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{2006,,可用性}: not WASI.

此模組在 WebAssembly 平台上不起作用或無法使用。更多資訊請參閱 @ref{1a99,,WebAssembly 平台}。

@menu
* Introduction: Introduction<2>. 
* 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. 

@end menu

@node Introduction<2>,GIL and performance considerations,,threading --- 基於執行緒的平行性
@anchor{library/threading introduction}@anchor{34cc}
@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{176,,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{941,,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{bb,,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{46e,,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{1d6,,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<2>,threading --- 基於執行緒的平行性
@anchor{library/threading gil-and-performance-considerations}@anchor{34cd}
@subsubsection GIL and performance considerations


Unlike the @ref{98,,multiprocessing} module, which uses separate processes to
bypass the @ref{46e,,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{1f4,,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 --- 基於執行緒的平行性
@anchor{library/threading reference}@anchor{34ce}
@subsubsection Reference


此模組定義了以下函式：

@geindex active_count() (於 threading 模組中)
@anchor{library/threading threading active_count}@anchor{35d}
@deffn {函式} threading.active_count ()

Return the number of @ref{176,,Thread} objects currently alive.  The returned
count is equal to the length of the list returned by @ref{1b5c,,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{35c}
@deffn {函式} threading.current_thread ()

Return the current @ref{176,,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.

@code{currentThread} 函式是此函式的已棄用別名。
@end deffn

@geindex excepthook() (於 threading 模組中)
@anchor{library/threading threading excepthook}@anchor{a44}
@deffn {函式} threading.excepthook (args, /)

處理由 @ref{c28,,Thread.run()} 引發且未被捕捉到的例外。

`args' 引數有下列屬性：


@itemize *

@item 
`exc_type'：例外型別。

@item 
`exc_value': Exception value, can be @code{None}.

@item 
`exc_traceback': Exception traceback, can be @code{None}.

@item 
`thread'：引發例外的執行緒，可以是 @code{None}。
@end itemize

If `exc_type' is @ref{f37,,SystemExit}, the exception is silently ignored.
Otherwise, the exception is printed out on @ref{b2a,,sys.stderr}.

如果這個函式引發例外，則會呼叫 @ref{a05,,sys.excepthook()} 來處理它。

@ref{a44,,threading.excepthook()} can be overridden to control how uncaught
exceptions raised by @ref{c28,,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{a05,,sys.excepthook()} 處理未被捕捉到的例外。



在 3.8 版被加入.

@end deffn

@geindex __excepthook__ (於 threading 模組中)
@anchor{library/threading threading __excepthook__}@anchor{a43}
@deffn {資料} threading.__excepthook__

Holds the original value of @ref{a44,,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.


在 3.10 版被加入.

@end deffn

@geindex get_ident() (於 threading 模組中)
@anchor{library/threading threading get_ident}@anchor{135b}
@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.


在 3.3 版被加入.

@end deffn

@geindex get_native_id() (於 threading 模組中)
@anchor{library/threading threading get_native_id}@anchor{c29}
@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{2006,,可用性}: Windows, FreeBSD, Linux, macOS, OpenBSD, NetBSD, AIX, DragonFlyBSD, GNU/kFreeBSD.


在 3.8 版被加入.



在 3.13 版的變更: 新增對 GNU/kFreeBSD 的支援。

@end deffn

@geindex enumerate() (於 threading 模組中)
@anchor{library/threading threading enumerate}@anchor{1b5c}
@deffn {函式} threading.enumerate ()

Return a list of all @ref{176,,Thread} objects currently active.  The list
includes daemonic threads and dummy thread objects created by
@ref{35c,,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{11cd}
@deffn {函式} threading.main_thread ()

Return the main @ref{176,,Thread} object.  In normal conditions, the
main thread is the thread from which the Python interpreter was
started.


在 3.4 版被加入.

@end deffn

@geindex settrace() (於 threading 模組中)
@anchor{library/threading threading settrace}@anchor{a41}
@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{2e1,,sys.settrace()} for each thread, before its
@ref{c28,,run()} method is called.
@end deffn

@geindex settrace_all_threads() (於 threading 模組中)
@anchor{library/threading threading settrace_all_threads}@anchor{6e8}
@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{2e1,,sys.settrace()} for each thread, before its
@ref{c28,,run()} method is called.


在 3.12 版被加入.

@end deffn

@geindex gettrace() (於 threading 模組中)
@anchor{library/threading threading gettrace}@anchor{a3f}
@deffn {函式} threading.gettrace ()

@geindex trace function
@geindex debugger（除錯器）

Get the trace function as set by @ref{a41,,settrace()}.


在 3.10 版被加入.

@end deffn

@geindex setprofile() (於 threading 模組中)
@anchor{library/threading threading setprofile}@anchor{a42}
@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{16f2,,sys.setprofile()} for each thread, before its
@ref{c28,,run()} method is called.
@end deffn

@geindex setprofile_all_threads() (於 threading 模組中)
@anchor{library/threading threading setprofile_all_threads}@anchor{6e9}
@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{16f2,,sys.setprofile()} for each thread, before its
@ref{c28,,run()} method is called.


在 3.12 版被加入.

@end deffn

@geindex getprofile() (於 threading 模組中)
@anchor{library/threading threading getprofile}@anchor{a40}
@deffn {函式} threading.getprofile ()

@geindex profile function

Get the profiler function as set by @ref{a42,,setprofile()}.


在 3.10 版被加入.

@end deffn

@geindex stack_size() (於 threading 模組中)
@anchor{library/threading threading stack_size}@anchor{34cf}
@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{244,,RuntimeError} is raised.  If the specified stack size is
invalid, a @ref{2eb,,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{2006,,可用性}: Windows, pthreads.

Unix platforms with POSIX threads support.
@end deffn

此模組也定義了以下常數：

@geindex TIMEOUT_MAX (於 threading 模組中)
@anchor{library/threading threading TIMEOUT_MAX}@anchor{34d0}
@deffn {資料} threading.TIMEOUT_MAX

The maximum value allowed for the `timeout' parameter of blocking functions
(@ref{8a0,,Lock.acquire()}, @ref{1076,,RLock.acquire()}, @ref{1b68,,Condition.wait()}, etc.).
Specifying a timeout greater than this value will raise an
@ref{a78,,OverflowError}.


在 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{176,,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 物件:: 
* Lock 物件:: 
* RLock 物件:: 
* Condition objects:: 
* Semaphore 物件:: 
* Semaphore 範例:: 
* Event objects:: 
* Timer 物件:: 
* Barrier 物件:: 

@end menu

@node Thread-local data,Thread 物件,,Reference<2>
@anchor{library/threading thread-local-data}@anchor{34d1}
@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{17df,,local} object and use its attributes:

@example
>>> mydata = local()
>>> mydata.number = 42
>>> mydata.number
42
@end example

You can also access the @ref{17df,,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{17df,,local} object, including their
@ref{776,,__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{17df,,local} objects by subclassing the
@ref{17df,,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{8b7,,__init__()}
method, it will be called each time the @ref{17df,,local} object is used
in a separate thread.  This is necessary to initialize each thread's
dictionary.

現在如果我們建立一個 @ref{17df,,local} 物件：

@example
>>> mydata = MyLocal(color='red')
@end example

會有一個預設的數字：

@example
>>> mydata.number
2
@end example

和一個初始顏色：

@example
>>> mydata.color
'red'
>>> del mydata.color
@end example

和一個操作資料的方法：

@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{7f0,,__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{17df}
@deffn {類別} threading.local

A class that represents thread-local data.
@end deffn

@node Thread 物件,Lock 物件,Thread-local data,Reference<2>
@anchor{library/threading id1}@anchor{34d2}@anchor{library/threading thread-objects}@anchor{34d3}
@subsubsection Thread 物件


The @ref{176,,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{c28,,run()}
method in a subclass.  No other methods (except for the constructor) should be
overridden in a subclass.  In other words, `only'  override the
@code{__init__()} and @ref{c28,,run()} methods of this class.

Once a thread object is created, its activity must be started by calling the
thread's @ref{178,,start()} method.  This invokes the @ref{c28,,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{c28,,run()} method terminates -- either
normally, or by raising an unhandled exception.  The @ref{b3d,,is_alive()}
method tests whether the thread is alive.

Other threads can call a thread's @ref{13e5,,join()} method.  This blocks
the calling thread until the thread whose @ref{13e5,,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{2a0,,name} attribute.

If the @ref{c28,,run()} method raises an exception,
@ref{a44,,threading.excepthook()} is called to handle it. By default,
@ref{a44,,threading.excepthook()} ignores silently @ref{f37,,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{35a,,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{1359,,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{34d4,,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{176}
@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{c28,,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{177,,Context} value to use when starting
the thread.  The default value is @code{None} which indicates that the
@ref{175,,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{178,,start()}.  If false, they will start with an empty
context.  To explicitly start with an empty context, pass a new instance of
@ref{177,,Context()}.  To explicitly start with a copy of the
current context, pass the value from @ref{34d5,,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 版的變更: 新增 `daemon' 參數。



在 3.10 版的變更: Use the `target' name if `name' argument is omitted.



在 3.14 版的變更: 新增 `context' 參數。


@geindex start() (threading.Thread 的方法)
@anchor{library/threading threading Thread start}@anchor{178}
@deffn {方法} start ()

Start the thread's activity.

It must be called at most once per thread object.  It arranges for the
object's @ref{c28,,run()} method to be invoked in a separate thread
of control.

This method will raise a @ref{244,,RuntimeError} if called more than once
on the same thread object.

If supported, set the operating system thread name to
@ref{2a0,,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{c28}
@deffn {方法} run ()

Method representing the thread's activity.

You may override this method in a subclass.  The standard @ref{c28,,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 @ref{176,,Thread}
could achieve the same effect.

舉例來說：

@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{34d4}@anchor{library/threading threading Thread join}@anchor{13e5}
@deffn {方法} join (timeout=None)

Wait until the thread terminates. This blocks the calling thread until
the thread whose @ref{13e5,,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
floating-point number specifying a timeout for the operation in seconds
(or fractions thereof). As @ref{13e5,,join()} always returns @code{None},
you must call @ref{b3d,,is_alive()} after @ref{13e5,,join()} to
decide whether a timeout happened -- if the thread is still alive, the
@ref{13e5,,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.

@ref{13e5,,join()} raises a @ref{244,,RuntimeError} if an attempt is made
to join the current thread as that would cause a deadlock. It is also
an error to @ref{13e5,,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{474,,Python finalization} @code{join()}
raises a @ref{473,,PythonFinalizationError}.


在 3.14 版的變更: May raise @ref{473,,PythonFinalizationError}.

@end deffn

@geindex name (threading.Thread 的屬性)
@anchor{library/threading threading Thread name}@anchor{2a0}
@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{34d6}
@deffn {方法} getName ()
@anchor{library/threading threading Thread setName}@anchor{35b}
@deffnx {方法} setName ()

Deprecated getter/setter API for @ref{2a0,,name}; use it directly as a
property instead.


在 3.10 版之後被棄用.

@end deffn

@geindex ident (threading.Thread 的屬性)
@anchor{library/threading threading Thread ident}@anchor{2feb}
@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{135b,,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{c2a}
@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{c29,,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{2006,,可用性}: Windows, FreeBSD, Linux, macOS, OpenBSD, NetBSD, AIX, DragonFlyBSD.


在 3.8 版被加入.

@end deffn

@geindex is_alive() (threading.Thread 的方法)
@anchor{library/threading threading Thread is_alive}@anchor{b3d}
@deffn {方法} is_alive ()

Return whether the thread is alive.

This method returns @code{True} just before the @ref{c28,,run()} method
starts until just after the @ref{c28,,run()} method terminates.  The
module function @ref{1b5c,,enumerate()} returns a list of all alive threads.
@end deffn

@geindex daemon (threading.Thread 的屬性)
@anchor{library/threading threading Thread daemon}@anchor{35a}
@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{178,,start()} is called,
otherwise @ref{244,,RuntimeError} is raised.  Its initial value is inherited
from the creating thread; the main thread is not a daemon thread and
therefore all threads created in the main thread default to
@ref{35a,,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{34d7}
@deffn {方法} isDaemon ()
@anchor{library/threading threading Thread setDaemon}@anchor{359}
@deffnx {方法} setDaemon ()

Deprecated getter/setter API for @ref{35a,,daemon}; use it directly as a
property instead.


在 3.10 版之後被棄用.

@end deffn
@end deffn

@node Lock 物件,RLock 物件,Thread 物件,Reference<2>
@anchor{library/threading id2}@anchor{34d8}@anchor{library/threading lock-objects}@anchor{34d9}
@subsubsection Lock 物件


原始鎖 (primitive lock) 是一種同步原語 (synchronization primitive)，在鎖定時不屬於特定執行緒。在 Python 中，它是目前可用的最低階同步原語，直接由 @ref{2,,_thread} 擴充模組實作。

原始鎖會處於兩種狀態之一：「鎖定 (locked)」或「未鎖定 (unclocked)」，建立時會處於未鎖定狀態。它有兩個基本方法 @ref{8a0,,acquire()} 和 @ref{14c3,,release()}。當狀態為未鎖定時，@ref{8a0,,acquire()} 會將狀態變更為鎖定並立即回傳。當狀態被鎖定時，@ref{8a0,,acquire()} 會阻塞 (block)，直到另一個執行緒中對 @ref{14c3,,release()} 的呼叫將其更改為未鎖定狀態，然後 @ref{8a0,,acquire()} 呼叫會將其重置為鎖定並回傳。@ref{14c3,,release()} 方法只能在鎖定狀態下呼叫；它將狀態更改為未鎖定並立即回傳。如果嘗試釋放未鎖定的鎖，則會引發 @ref{244,,RuntimeError}。

鎖也支援@ref{34da,,情境管理協定}。

當多個執行緒阻塞在 @ref{8a0,,acquire()} 中等待狀態轉變為未鎖定，此時若呼叫 @ref{14c3,,release()} 將狀態重置為未鎖定，則只會有一個執行緒繼續進行；哪一個等待執行緒會繼續進行是未定義的，並且可能因實作而異。

所有方法均以最小不可分割的操作方式 (atomically) 執行。

@geindex Lock (threading 中的類別)
@anchor{library/threading threading Lock}@anchor{1943}
@deffn {類別} threading.Lock

實作原始鎖物件的類別。一旦執行緒獲得了鎖，後續再嘗試獲得它就會被阻塞，直到鎖被釋放；任何執行緒都可以去釋放它。


在 3.13 版的變更: @code{Lock} 現在是一個類別。在早期的 Python 中，@code{Lock} 是一個會回傳底層私有鎖型別實例的工廠函式。


@geindex acquire() (threading.Lock 的方法)
@anchor{library/threading threading Lock acquire}@anchor{8a0}
@deffn {方法} acquire (blocking=True, timeout=-1)

阻塞或非阻塞地取得鎖。

當以 `blocking' 引數設為 @code{True}（預設值）來叫用，將會阻塞直到鎖被解鎖，然後將其設為鎖定並回傳 @code{True}。

當以 `blocking' 引數設為 @code{False} 叫用則不會阻塞。如果 `blocking' 設定為 @code{True} 的呼叫會阻塞，則立即回傳 @code{False}；否則將鎖設為鎖定並回傳 @code{True}。

當使用設定為正值的浮點 `timeout' 引數進行叫用，只要持續無法取得鎖，最多會阻塞 `timeout' 指定的秒數。@code{-1} 的 `timeout' 引數代表指定為不會停止的等待。當 `blocking' 為 @code{False} 時禁止指定 `timeout'。

如果成功取得鎖，則回傳值為 @code{True}，否則回傳值為 @code{False}（例如像是 `timeout' 已逾期）。


在 3.2 版的變更: 新的 `timeout' 參數。



在 3.2 版的變更: 如果底層執行緒實作支援的話，鎖的取得現在可以被 POSIX 上的訊號中斷。



在 3.14 版的變更: Lock acquisition can now be interrupted by signals on Windows.

@end deffn

@geindex release() (threading.Lock 的方法)
@anchor{library/threading threading Lock release}@anchor{14c3}
@deffn {方法} release ()

釋放鎖。這可以從任何執行緒呼叫，而不是只有獲得鎖的執行緒。

當鎖被鎖定時，將其重置為未鎖定然後回傳。如果任何其他執行緒在等待鎖被解鎖時被阻塞，只允許其中一個執行緒繼續進行。

當在未鎖定的鎖上叫用時，會引發 @ref{244,,RuntimeError}

沒有回傳值。
@end deffn

@geindex locked() (threading.Lock 的方法)
@anchor{library/threading threading Lock locked}@anchor{34db}
@deffn {方法} locked ()

如果有取得了鎖，則回傳 @code{True}。
@end deffn
@end deffn

@node RLock 物件,Condition objects,Lock 物件,Reference<2>
@anchor{library/threading id3}@anchor{34dc}@anchor{library/threading rlock-objects}@anchor{34dd}
@subsubsection RLock 物件


可重入鎖 (reentrant lock) 是一種同步原語，同一執行緒可以多次取得它。在內部，除了原始鎖使用的鎖定/未鎖定狀態之外，它還使用「所屬執行緒 (owning thread)」和「遞迴等級 (recursion level)」的概念。在鎖定狀態下，某個執行緒會擁有鎖；在未鎖定狀態下則沒有執行緒擁有它。

執行緒呼叫鎖的 @ref{1076,,acquire()} 方法來鎖定它，並呼叫它的 @ref{14c3,,release()} 方法來解鎖它。

@cartouche
@quotation 備註 
可重入鎖支援@ref{34da,,情境管理協定}，因此建議使用 @ref{186,,with} 而不是手動呼叫 @ref{1076,,acquire()} 和 @ref{34de,,release()} 來對程式碼區塊處理鎖的獲得和釋放。
@end quotation
@end cartouche

RLock 的 @ref{1076,,acquire()}/@ref{34de,,release()} 呼叫成對組合可以嵌套使用，這與 Lock 的 @ref{8a0,,acquire()}/@ref{14c3,,release()} 不同。只有最後一個 @ref{34de,,release()}（最外面一對的 @ref{14c3,,release()}）會將鎖重置為未鎖定狀態，並允許在 @ref{1076,,acquire()} 中阻塞的另一個執行緒繼續進行。

@ref{1076,,acquire()}/@ref{34de,,release()} 必須成對使用：每次獲得都必須在已獲得鎖的執行緒中有一個釋放。如果鎖釋放的次數不能和取得的次數一樣的話，可能會導致死鎖 (deadlock)。

@geindex RLock (threading 中的類別)
@anchor{library/threading threading RLock}@anchor{32d}
@deffn {類別} threading.RLock

此類別實作了可重入鎖物件。可重入鎖必須由獲得它的執行緒釋放。一旦一個執行緒獲得了可重入鎖，同一個執行緒可以再次獲得它而不會阻塞；執行緒每次獲得它也都必須釋放它一次。

請注意，@code{RLock} 實際上是一個工廠函式，它會回傳平台有支援的特定 RLock 類別的最高效率版本的實例。

@geindex acquire() (threading.RLock 的方法)
@anchor{library/threading threading RLock acquire}@anchor{1076}
@deffn {方法} acquire (blocking=True, timeout=-1)

阻塞或非阻塞地取得鎖。


@subsubheading 也參考



@table @asis

@item @ref{34da,,將 RLock 用作為情境管理器}

若是使用場景合理，和手動呼叫 @code{acquire()} 和 @ref{34de,,release()} 相比，會是更為推薦的使用方式。
@end table


當以 `blocking' 引數設為 @code{True}（預設值）來呼叫：

@quotation


@itemize *

@item 
如果沒有執行緒擁有鎖，則獲得鎖並立即回傳。

@item 
如果另一個執行緒擁有鎖，則阻塞直到能夠取得鎖，或者達到 `timeout'（如果設定為正浮點值）。

@item 
如果同一個執行緒擁有鎖，則再次取得鎖，並立即回傳。這就是 @ref{1943,,Lock} 和 @code{RLock} 之間的差別；@ref{1943,,Lock} 處理方式與上一種情況相同，會阻塞直到能夠取得鎖。
@end itemize
@end quotation

當以 `blocking' 引數設為 @code{False} 來呼叫：

@quotation


@itemize *

@item 
如果沒有執行緒擁有鎖，則獲得鎖並立即回傳。

@item 
如果另一個執行緒擁有該鎖，則立即回傳。

@item 
如果同一個執行緒擁有鎖，則再次取得鎖並立即回傳。
@end itemize
@end quotation

在所有情況下，如果執行緒能夠取得鎖則回傳 @code{True}。如果執行緒無法取得鎖（即沒有阻塞或已達超時限制）則回傳 @code{False}。

如果多次呼叫，又未能呼叫相同次數的 @ref{34de,,release()}，則可能會導致死鎖。考慮將 @code{RLock} 作為情境管理器使用，而不是直接呼叫 acquire/release。


在 3.2 版的變更: 新的 `timeout' 參數。

@end deffn

@geindex release() (threading.RLock 的方法)
@anchor{library/threading threading RLock release}@anchor{34de}
@deffn {方法} release ()

釋放鎖並減少遞迴等級。如果被減至零，則將鎖重置為未鎖定（不屬於任何執行緒），並且如果任何其他執行緒被阻塞以等待鎖變成未鎖定狀態，則僅允許其中一個執行緒繼續進行。如果遞減後遞迴等級仍然非零，則鎖會保持鎖定並由呼叫它的執行緒所擁有。

僅當呼叫的執行緒擁有鎖時才能呼叫此方法。如果在未取得鎖時呼叫此方法則會引發 @ref{244,,RuntimeError}。

沒有回傳值。
@end deffn

@geindex locked() (threading.RLock 的方法)
@anchor{library/threading threading RLock locked}@anchor{17b9}
@deffn {方法} locked ()

Return a boolean indicating whether this object is locked right now.


在 3.14 版被加入.

@end deffn
@end deffn

@node Condition objects,Semaphore 物件,RLock 物件,Reference<2>
@anchor{library/threading condition-objects}@anchor{34df}@anchor{library/threading id4}@anchor{34e0}
@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{34da,,context management protocol}:
using the @code{with} statement acquires the associated lock for the duration of
the enclosed block.  The @ref{34e1,,acquire()} and
@ref{34e2,,release()} methods also call the corresponding methods of
the associated lock.

Other methods must be called with the associated lock held.  The
@ref{1b68,,wait()} method releases the lock, and then blocks until
another thread awakens it by calling @ref{1a95,,notify()} or
@ref{357,,notify_all()}.  Once awakened, @ref{1b68,,wait()}
re-acquires the lock and returns.  It is also possible to specify a timeout.

The @ref{1a95,,notify()} method wakes up one of the threads waiting for
the condition variable, if any are waiting.  The @ref{357,,notify_all()}
method wakes up all threads waiting for the condition variable.

Note: the @ref{1a95,,notify()} and @ref{357,,notify_all()} methods
don't release the lock; this means that the thread or threads awakened will
not return from their @ref{1b68,,wait()} call immediately, but only when
the thread that called @ref{1a95,,notify()} or @ref{357,,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{1b68,,wait()} repeatedly until they
see the desired state, while threads that modify the state call
@ref{1a95,,notify()} or @ref{357,,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{1b68,,wait()} can return after an arbitrary long time,
and the condition which prompted the @ref{1a95,,notify()} call may
no longer hold true.  This is inherent to multi-threaded programming.  The
@ref{34e3,,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{1a95,,notify()} and @ref{357,,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{1356}
@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{1943,,Lock}
or @ref{32d,,RLock} object, and it is used as the underlying lock.  Otherwise,
a new @ref{32d,,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{34e1}
@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{34e2}
@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{34e4}
@deffn {方法} locked ()

Return a boolean indicating whether this object is locked right now.


在 3.14 版被加入.

@end deffn

@geindex wait() (threading.Condition 的方法)
@anchor{library/threading threading Condition wait}@anchor{1b68}
@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{244,,RuntimeError} is
raised.

This method releases the underlying lock, and then blocks until it is
awakened by a @ref{1a95,,notify()} or @ref{357,,notify_all()} call for the same
condition variable in another thread, or until the optional timeout
occurs.  Once awakened or timed out, it re-acquires the lock and returns.

When the `timeout' argument is present and not @code{None}, it should be a
floating-point number specifying a timeout for the operation in seconds
(or fractions thereof).

When the underlying lock is an @ref{32d,,RLock}, it is not released using
its @ref{34e2,,release()} method, since this may not actually unlock the lock
when it was acquired multiple times recursively.  Instead, an internal
interface of the @ref{32d,,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{34e3}
@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{1b68,,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{1b68,,wait()}: The lock must be
held when called and is re-acquired on return.  The predicate is evaluated
with the lock held.


在 3.2 版被加入.

@end deffn

@geindex notify() (threading.Condition 的方法)
@anchor{library/threading threading Condition notify}@anchor{1a95}
@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{244,,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{1b68,,wait()}
call until it can reacquire the lock.  Since @ref{1a95,,notify()} does not
release the lock, its caller should.
@end deffn

@geindex notify_all() (threading.Condition 的方法)
@anchor{library/threading threading Condition notify_all}@anchor{357}
@deffn {方法} notify_all ()

Wake up all threads waiting on this condition.  This method acts like
@ref{1a95,,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{244,,RuntimeError} is raised.

The method @code{notifyAll} is a deprecated alias for this method.
@end deffn
@end deffn

@node Semaphore 物件,Semaphore 範例,Condition objects,Reference<2>
@anchor{library/threading id5}@anchor{34e5}@anchor{library/threading semaphore-objects}@anchor{34e6}
@subsubsection Semaphore 物件


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{1454,,acquire()} and
@ref{34e7,,release()}).

A semaphore manages an internal counter which is decremented by each
@ref{1454,,acquire()} call and incremented by each @ref{34e7,,release()}
call.  The counter can never go below zero; when @ref{1454,,acquire()}
finds that it is zero, it blocks, waiting until some other thread calls
@ref{34e7,,release()}.

Semaphores also support the @ref{34da,,context management protocol}.

@geindex Semaphore (threading 中的類別)
@anchor{library/threading threading Semaphore}@anchor{1357}
@deffn {類別} threading.Semaphore (value=1)

This class implements semaphore objects.  A semaphore manages an atomic
counter representing the number of @ref{34e7,,release()} calls minus the number of
@ref{1454,,acquire()} calls, plus an initial value.  The @ref{1454,,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{2eb,,ValueError} is
raised.


在 3.3 版的變更: changed from a factory function to a class.


@geindex acquire() (threading.Semaphore 的方法)
@anchor{library/threading threading Semaphore acquire}@anchor{1454}
@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{34e7,,release()}.  Once awoken (and the counter is greater
than 0), decrement the counter by 1 and return @code{True}.  Exactly one
thread will be awoken by each call to @ref{34e7,,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 版的變更: 新的 `timeout' 參數。

@end deffn

@geindex release() (threading.Semaphore 的方法)
@anchor{library/threading threading Semaphore release}@anchor{34e7}
@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{1358}
@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{2eb,,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 範例,Event objects,Semaphore 物件,Reference<2>
@anchor{library/threading semaphore-example}@anchor{34e8}@anchor{library/threading semaphore-examples}@anchor{34e9}
@subsubsection @code{Semaphore} 範例


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:
        # ... 使用該連線 ...
    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 物件,Semaphore 範例,Reference<2>
@anchor{library/threading event-objects}@anchor{34ea}@anchor{library/threading id6}@anchor{34eb}
@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{34ec,,set()} method and reset to false with the @ref{34ed,,clear()}
method.  The @ref{1527,,wait()} method blocks until the flag is true.

@geindex Event (threading 中的類別)
@anchor{library/threading threading Event}@anchor{1359}
@deffn {類別} threading.Event

Class implementing event objects.  An event manages a flag that can be set to
true with the @ref{34ec,,set()} method and reset to false with the
@ref{34ed,,clear()} method.  The @ref{1527,,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{358}
@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{34ec}
@deffn {方法} set ()

Set the internal flag to true. All threads waiting for it to become true
are awakened. Threads that call @ref{1527,,wait()} once the flag is true will
not block at all.
@end deffn

@geindex clear() (threading.Event 的方法)
@anchor{library/threading threading Event clear}@anchor{34ed}
@deffn {方法} clear ()

Reset the internal flag to false. Subsequently, threads calling
@ref{1527,,wait()} will block until @ref{34ec,,set()} is called to set the internal
flag to true again.
@end deffn

@geindex wait() (threading.Event 的方法)
@anchor{library/threading threading Event wait}@anchor{1527}
@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
floating-point 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 物件,Barrier 物件,Event objects,Reference<2>
@anchor{library/threading id7}@anchor{34ee}@anchor{library/threading timer-objects}@anchor{34ef}
@subsubsection Timer 物件


This class represents an action that should be run only after a certain amount
of time has passed --- a timer.  @ref{135a,,Timer} is a subclass of @ref{176,,Thread}
and as such also functions as an example of creating custom threads.

Timers are started, as with threads, by calling their @ref{178,,Timer.start}
method.  The timer can be stopped (before its action has begun) by calling the
@ref{34f0,,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.

舉例來說：

@example
def hello():
    print("hello, world")

t = Timer(30.0, hello)
t.start()  # 30 秒後會印出 "hello, world"
@end example

@geindex Timer (threading 中的類別)
@anchor{library/threading threading Timer}@anchor{135a}
@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{34f0}
@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 物件,,Timer 物件,Reference<2>
@anchor{library/threading barrier-objects}@anchor{34f1}
@subsubsection Barrier 物件



在 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{34f2,,wait()} method and will block until
all of the threads have made their @ref{34f2,,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{13e4}
@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{34f2,,wait()} method.

@geindex wait() (threading.Barrier 的方法)
@anchor{library/threading threading Barrier wait}@anchor{34f2}
@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:
    # 只會有一個執行緒會印出這個
    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{13e6,,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{34f3}
@deffn {方法} reset ()

Return the barrier to the default, empty state.  Any threads waiting on it
will receive the @ref{13e6,,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{34f4}
@deffn {方法} abort ()

Put the barrier into a broken state.  This causes any active or future
calls to @ref{34f2,,wait()} to fail with the @ref{13e6,,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{34f5}
@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{34f6}
@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{34f7}
@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{13e6}
@deffn {例外} threading.BrokenBarrierError

This exception, a subclass of @ref{244,,RuntimeError}, is raised when the
@ref{13e4,,Barrier} object is reset or broken.
@end deffn

@node Using locks conditions and semaphores in the with statement,,Reference<2>,threading --- 基於執行緒的平行性
@anchor{library/threading using-locks-conditions-and-semaphores-in-the-with-statement}@anchor{34f8}@anchor{library/threading with-locks}@anchor{34da}
@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{186,,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:
    # 做某些事情...
@end example

is equivalent to:

@example
some_lock.acquire()
try:
    # 做某些事情...
finally:
    some_lock.release()
@end example

Currently, @ref{1943,,Lock}, @ref{32d,,RLock}, @ref{1356,,Condition},
@ref{1357,,Semaphore}, and @ref{1358,,BoundedSemaphore} objects may be used as
@ref{186,,with} statement context managers.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node multiprocessing --- 以行程為基礎的平行性,multiprocessing shared_memory --- 對於共享記憶體的跨行程直接存取,threading --- 基於執行緒的平行性,並行執行 Concurrent Execution
@anchor{library/multiprocessing doc}@anchor{34f9}@anchor{library/multiprocessing module-multiprocessing}@anchor{98}@anchor{library/multiprocessing multiprocessing-process-based-parallelism}@anchor{34fa}@anchor{library/multiprocessing translation-repo}@anchor{34fb}
@subsection @code{multiprocessing} --- 以行程為基礎的平行性


@geindex module; multiprocessing

`原始碼：'Lib/multiprocessing/@footnote{https://github.com/python/cpython/tree/3.14/Lib/multiprocessing/}


__________________________________________________________________


@c include for modules that don't work on WASM or mobile platforms

@ref{2006,,可用性}: not Android, not iOS, not WASI.

此模組在@ref{2120,,行動平台}或@ref{1a99,,WebAssembly 平台}上不支援。

@menu
* 簡介: 簡介<7>. 
* Reference: Reference<3>. 
* Programming guidelines:: 
* 範例: 範例<20>. 

@end menu

@node 簡介<7>,Reference<3>,,multiprocessing --- 以行程為基礎的平行性
@anchor{library/multiprocessing introduction}@anchor{34fc}
@subsubsection 簡介


@ref{98,,multiprocessing} is a package that supports spawning processes using an
API similar to the @ref{f3,,threading} module.  The @ref{98,,multiprocessing} package
offers both local and remote concurrency, effectively side-stepping the
@ref{46e,,Global Interpreter Lock} by using
subprocesses instead of threads.  Due
to this, the @ref{98,,multiprocessing} module allows the programmer to fully
leverage multiple processors on a given machine.  It runs on both POSIX and
Windows.

The @ref{98,,multiprocessing} module also introduces APIs which do not have
analogs in the @ref{f3,,threading} module.  A prime example of this is the
@ref{1166,,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 @ref{1166,,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


@subsubheading 也參考


@ref{1d6,,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{1166,,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
* Process 類別:: 
* Contexts and start methods:: 
* Exchanging objects between processes:: 
* Synchronization between processes:: 
* Sharing state between processes:: 
* Using a pool of workers:: 

@end menu

@node Process 類別,Contexts and start methods,,簡介<7>
@anchor{library/multiprocessing the-process-class}@anchor{34fd}
@subsubsection @code{Process} 類別


In @ref{98,,multiprocessing}, processes are spawned by creating a @ref{252,,Process}
object and then calling its @ref{1589,,start()} method.  @ref{252,,Process}
follows the API of @ref{176,,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{34fe,,Programming guidelines}.

The arguments to @ref{252,,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{5e8,,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,Process 類別,簡介<7>
@anchor{library/multiprocessing contexts-and-start-methods}@anchor{34ff}@anchor{library/multiprocessing multiprocessing-start-methods}@anchor{1d5}
@subsubsection Contexts and start methods


Depending on the platform, @ref{98,,multiprocessing} supports three ways
to start a process.  These `start methods' are

@quotation
@anchor{library/multiprocessing multiprocessing-start-method-spawn}@anchor{1d8}

@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{3500,,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{1d7}

@table @asis

@item `fork'

The parent process uses @ref{4b0,,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{24a,,get_context()} or @ref{24b,,set_start_method()}.



在 3.12 版的變更: If Python is able to detect that your process has multiple threads, the
@ref{4b0,,os.fork()} function that this start method calls internally will
raise a @ref{1a3,,DeprecationWarning}. Use a different start method.
See the @ref{4b0,,os.fork()} documentation for further explanation.

@end table
@anchor{library/multiprocessing multiprocessing-start-method-forkserver}@anchor{1d4}

@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{4b0,,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{1927,,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{24b,,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{24b,,set_start_method()} should not be used more than once in the
program.

Alternatively, you can use @ref{24a,,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 @ref{98,,multiprocessing} or
@ref{1d6,,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,簡介<7>
@anchor{library/multiprocessing exchanging-objects-between-processes}@anchor{3501}
@subsubsection Exchanging objects between processes


@ref{98,,multiprocessing} supports two types of communication channel between
processes:

`Queues'

@quotation

The @ref{1ab3,,Queue} class is a near clone of @ref{158c,,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())    # 印出 "[42, None, 'hello']"
    p.join()
@end example

Queues are thread and process safe.
Any object put into a @ref{98,,multiprocessing} queue will be serialized.
@end quotation

`Pipes'

@quotation

The @ref{3502,,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())   # 印出 "[42, None, 'hello']"
    p.join()
@end example

The two connection objects returned by @ref{3502,,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,簡介<7>
@anchor{library/multiprocessing synchronization-between-processes}@anchor{3503}
@subsubsection Synchronization between processes


@ref{98,,multiprocessing} contains equivalents of all the synchronization
primitives from @ref{f3,,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,簡介<7>
@anchor{library/multiprocessing sharing-state-between-processes}@anchor{3504}
@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
@ref{98,,multiprocessing} provides a couple of ways of doing so.

`Shared memory'

@quotation

Data can be stored in a shared memory map using @ref{3505,,Value} or
@ref{3506,,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{250,,Manager()} controls a server process which
holds Python objects and allows other processes to manipulate them using
proxies.

A manager returned by @ref{250,,Manager()} will support types
@ref{24d,,list}, @ref{183,,dict}, @ref{184,,set}, @ref{3507,,Namespace}, @ref{17d2,,Lock},
@ref{17d3,,RLock}, @ref{3508,,Semaphore}, @ref{3509,,BoundedSemaphore},
@ref{350a,,Condition}, @ref{1b1a,,Event}, @ref{350b,,Barrier},
@ref{1ab3,,Queue}, @ref{3505,,Value} and @ref{3506,,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,簡介<7>
@anchor{library/multiprocessing using-a-pool-of-workers}@anchor{350c}
@subsubsection Using a pool of workers


The @ref{1166,,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.

舉例來說：

@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{34fe,,Programming guidelines}
however it is worth pointing out here. This means that some examples, such
as the @ref{1166,,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,簡介<7>,multiprocessing --- 以行程為基礎的平行性
@anchor{library/multiprocessing reference}@anchor{350d}
@subsubsection Reference


The @ref{98,,multiprocessing} package mostly replicates the API of the
@ref{f3,,threading} module.

@menu
* Process 與例外:: 
* Pipes and Queues:: 
* Miscellaneous: Miscellaneous<3>. 
* Connection Objects:: 
* Synchronization primitives:: 
* 共享的 ctypes 物件:: 
* Managers:: 
* Proxy Objects:: 
* Process Pools:: 
* Listeners and Clients:: 
* Authentication keys:: 
* Logging:: 
* multiprocessing.dummy 模組: multiprocessing dummy 模組. 

@end menu

@node Process 與例外,Pipes and Queues,,Reference<3>
@anchor{library/multiprocessing process-and-exceptions}@anchor{350e}
@subsubsection @code{Process} 與例外


@geindex Process (multiprocessing 中的類別)
@anchor{library/multiprocessing multiprocessing Process}@anchor{252}
@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
@ref{252,,Process} class has equivalents of all the methods of
@ref{176,,threading.Thread}.

The constructor should always be called with keyword arguments. `group'
should always be @code{None}; it exists solely for compatibility with
@ref{176,,threading.Thread}.  `target' is the callable object to be invoked by
the @ref{3500,,run()} method.  It defaults to @code{None}, meaning nothing is
called. `name' is the process name (see @ref{350f,,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{3510,,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 @ref{252,,Process} must be picklable.  This is
frequently observed when trying to create a @ref{252,,Process} or use a
@ref{1d6,,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{5e8,,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{3511,,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{1d5,,Contexts and start methods}.
See also gh-132898@footnote{https://github.com/python/cpython/issues/132898}.
@end quotation
@end cartouche


在 3.3 版的變更: 新增 `daemon' 參數。


@geindex run() (multiprocessing.Process 的方法)
@anchor{library/multiprocessing multiprocessing Process run}@anchor{3500}
@deffn {方法} run ()

Method representing the process's activity.

You may override this method in a subclass.  The standard @ref{3500,,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 @ref{252,,Process}
achieves the same effect.

範例：

@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{1589}
@deffn {方法} start ()

Start the process's activity.

This must be called at most once per process object.  It arranges for the
object's @ref{3500,,run()} method to be invoked in a separate process.
@end deffn

@geindex join() (multiprocessing.Process 的方法)
@anchor{library/multiprocessing multiprocessing Process join}@anchor{158b}
@deffn {方法} join ([timeout])

If the optional argument `timeout' is @code{None} (the default), the method
blocks until the process whose @ref{158b,,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{3512,,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{350f}
@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{158a}
@deffn {方法} is_alive ()

Return whether the process is alive.

Roughly, a process object is alive from the moment the @ref{1589,,start()}
method returns until the child process terminates.
@end deffn

@geindex daemon (multiprocessing.Process 的屬性)
@anchor{library/multiprocessing multiprocessing Process daemon}@anchor{3510}
@deffn {屬性} daemon

The process's daemon flag, a Boolean value.  This must be set before
@ref{1589,,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{176,,threading.Thread} API, @ref{252,,Process} objects
also support the following attributes and methods:

@geindex pid (multiprocessing.Process 的屬性)
@anchor{library/multiprocessing multiprocessing Process pid}@anchor{3513}
@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{3512}
@deffn {屬性} exitcode

The child's exit code.  This will be @code{None} if the process has not yet
terminated.

If the child's @ref{3500,,run()} method returned normally, the exit code
will be 0.  If it terminated via @ref{277,,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{3500,,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{3514}
@deffn {屬性} authkey

The process's authentication key (a byte string).

When @ref{98,,multiprocessing} is initialized the main process is assigned a
random string using @ref{73f,,os.urandom()}.

When a @ref{252,,Process} object is created, it will inherit the
authentication key of its parent process, although this may be changed by
setting @ref{3514,,authkey} to another byte string.

參閱 @ref{3515,,Authentication keys}。
@end deffn

@geindex sentinel (multiprocessing.Process 的屬性)
@anchor{library/multiprocessing multiprocessing Process sentinel}@anchor{12e2}
@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{12e0,,multiprocessing.connection.wait()}.  Otherwise
calling @ref{158b,,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{c6,,select} module.


在 3.3 版被加入.

@end deffn

@geindex interrupt() (multiprocessing.Process 的方法)
@anchor{library/multiprocessing multiprocessing Process interrupt}@anchor{251}
@deffn {方法} interrupt ()

Terminate the process. Works on POSIX using the @ref{253,,SIGINT} signal.
Behavior on Windows is undefined.

By default, this terminates the child process by raising @ref{bbc,,KeyboardInterrupt}.
This behavior can be altered by setting the respective signal handler in the child
process @ref{1335,,signal.signal()} for @ref{253,,SIGINT}.

Note: if the child process catches and discards @ref{bbc,,KeyboardInterrupt}, the
process will not be terminated.

Note: the default behavior will also set @ref{3512,,exitcode} to @code{1} as if an
uncaught exception was raised in the child process. To have a different
@ref{3512,,exitcode} you may simply catch @ref{bbc,,KeyboardInterrupt} and call
@code{exit(your_code)}.


在 3.14 版被加入.

@end deffn

@geindex terminate() (multiprocessing.Process 的方法)
@anchor{library/multiprocessing multiprocessing Process terminate}@anchor{17d6}
@deffn {方法} terminate ()

Terminate the process.  On POSIX this is done using the @ref{15d6,,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{d47}
@deffn {方法} kill ()

Same as @ref{17d6,,terminate()} but using the @code{SIGKILL} signal on POSIX.


在 3.7 版被加入.

@end deffn

@geindex close() (multiprocessing.Process 的方法)
@anchor{library/multiprocessing multiprocessing Process close}@anchor{d46}
@deffn {方法} close ()

Close the @ref{252,,Process} object, releasing all resources associated
with it.  @ref{2eb,,ValueError} is raised if the underlying process
is still running.  Once @ref{d46,,close()} returns successfully, most
other methods and attributes of the @ref{252,,Process} object will
raise @ref{2eb,,ValueError}.


在 3.7 版被加入.

@end deffn

Note that the @ref{1589,,start()}, @ref{158b,,join()}, @ref{158a,,is_alive()},
@ref{17d6,,terminate()} and @ref{3512,,exitcode} methods should only be called by
the process that created the process object.

Example usage of some of the methods of @ref{252,,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{3516}
@deffn {例外} multiprocessing.ProcessError

The base class of all @ref{98,,multiprocessing} exceptions.
@end deffn

@geindex BufferTooShort
@anchor{library/multiprocessing multiprocessing BufferTooShort}@anchor{3517}
@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 @ref{3517,,BufferTooShort} then @code{e.args[0]} will give
the message as a byte string.
@end deffn

@geindex AuthenticationError
@anchor{library/multiprocessing multiprocessing AuthenticationError}@anchor{3518}
@deffn {例外} multiprocessing.AuthenticationError

Raised when there is an authentication error.
@end deffn

@geindex TimeoutError
@anchor{library/multiprocessing multiprocessing TimeoutError}@anchor{3519}
@deffn {例外} multiprocessing.TimeoutError

Raised by methods with a timeout when the timeout expires.
@end deffn

@node Pipes and Queues,Miscellaneous<3>,Process 與例外,Reference<3>
@anchor{library/multiprocessing pipes-and-queues}@anchor{351a}
@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{3502,,Pipe()} (for a connection between two
processes) or a queue (which allows multiple producers and consumers).

The @ref{1ab3,,Queue}, @ref{b07,,SimpleQueue} and @ref{351b,,JoinableQueue} types
are multi-producer, multi-consumer @abbr{FIFO}
queues modelled on the @ref{158c,,queue.Queue} class in the
standard library.  They differ in that @ref{1ab3,,Queue} lacks the
@ref{351c,,task_done()} and @ref{351d,,join()} methods introduced
into Python 2.5's @ref{158c,,queue.Queue} class.

If you use @ref{351b,,JoinableQueue} then you `must' call
@ref{351e,,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 @ref{98,,multiprocessing}
queues serializes all objects that are put into them using @ref{ab,,pickle}.
The object return 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{351f,,Managers}.

@cartouche
@quotation 備註 
@ref{98,,multiprocessing} uses the usual @ref{3520,,queue.Empty} and
@ref{3521,,queue.Full} exceptions to signal a timeout.  They are not available in
the @ref{98,,multiprocessing} namespace so you need to import them from
@ref{bb,,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{351f,,manager}.


@enumerate 

@item 
After putting an object on an empty queue there may be an
infinitesimal delay before the queue's @ref{18cf,,empty()}
method returns @ref{d23,,False} and @ref{3522,,get_nowait()} can
return without raising @ref{3520,,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{17d6,,Process.terminate()} or @ref{155f,,os.kill()}
while it is trying to use a @ref{1ab3,,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{3523,,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{34fe,,Programming guidelines}.
@end quotation
@end cartouche

For an example of the usage of queues for interprocess communication see
@ref{3524,,範例}.

@geindex Pipe() (於 multiprocessing 模組中)
@anchor{library/multiprocessing multiprocessing Pipe}@anchor{3502}
@deffn {函式} multiprocessing.Pipe ([duplex])

Returns a pair @code{(conn1, conn2)} of
@ref{12e1,,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{1ab3}
@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.

The usual @ref{3520,,queue.Empty} and @ref{3521,,queue.Full} exceptions from the
standard library's @ref{bb,,queue} module are raised to signal timeouts.

@ref{1ab3,,Queue} implements all the methods of @ref{158c,,queue.Queue} except for
@ref{351c,,task_done()} and @ref{351d,,join()}.

@geindex qsize() (multiprocessing.Queue 的方法)
@anchor{library/multiprocessing multiprocessing Queue qsize}@anchor{3525}
@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{369,,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{18cf}
@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{2c0,,OSError} on closed queues. (not guaranteed)
@end deffn

@geindex full() (multiprocessing.Queue 的方法)
@anchor{library/multiprocessing multiprocessing Queue full}@anchor{3526}
@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{1ce5}
@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{3521,,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 @ref{3521,,queue.Full} exception (`timeout' is
ignored in that case).


在 3.8 版的變更: If the queue is closed, @ref{2eb,,ValueError} is raised instead of
@ref{8b0,,AssertionError}.

@end deffn

@geindex put_nowait() (multiprocessing.Queue 的方法)
@anchor{library/multiprocessing multiprocessing Queue put_nowait}@anchor{3527}
@deffn {方法} put_nowait (obj)

Equivalent to @code{put(obj, False)}.
@end deffn

@geindex get() (multiprocessing.Queue 的方法)
@anchor{library/multiprocessing multiprocessing Queue get}@anchor{1ce6}
@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{3520,,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
@ref{3520,,queue.Empty} exception (`timeout' is ignored in that case).


在 3.8 版的變更: If the queue is closed, @ref{2eb,,ValueError} is raised instead of
@ref{2c0,,OSError}.

@end deffn

@geindex get_nowait() (multiprocessing.Queue 的方法)
@anchor{library/multiprocessing multiprocessing Queue get_nowait}@anchor{3522}
@deffn {方法} get_nowait ()

Equivalent to @code{get(False)}.
@end deffn

@ref{1ab3,,multiprocessing.Queue} has a few additional methods not found in
@ref{158c,,queue.Queue}.  These methods are usually unnecessary for most
code:

@geindex close() (multiprocessing.Queue 的方法)
@anchor{library/multiprocessing multiprocessing Queue close}@anchor{1ab4}
@deffn {方法} close ()

Close the queue: release internal resources.

A queue must not be used anymore after it is closed. For example,
@ref{1ce6,,get()}, @ref{1ce5,,put()} and @ref{18cf,,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{3528}
@deffn {方法} join_thread ()

Join the background thread.  This can only be used after @ref{1ab4,,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{3523,,cancel_join_thread()} to make @ref{3528,,join_thread()} do nothing.
@end deffn

@geindex cancel_join_thread() (multiprocessing.Queue 的方法)
@anchor{library/multiprocessing multiprocessing Queue cancel_join_thread}@anchor{3523}
@deffn {方法} cancel_join_thread ()

Prevent @ref{3528,,join_thread()} from blocking.  In particular, this prevents
the background thread from being joined automatically when the process
exits -- see @ref{3528,,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 @ref{1ab3,,Queue} will result in an @ref{653,,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{b07}
@deffn {類別} multiprocessing.SimpleQueue

It is a simplified @ref{1ab3,,Queue} type, very close to a locked @ref{3502,,Pipe}.

@geindex close() (multiprocessing.SimpleQueue 的方法)
@anchor{library/multiprocessing multiprocessing SimpleQueue close}@anchor{b08}
@deffn {方法} close ()

Close the queue: release internal resources.

A queue must not be used anymore after it is closed. For example,
@ref{3529,,get()}, @ref{352a,,put()} and @ref{18d0,,empty()} methods must no longer be
called.


在 3.9 版被加入.

@end deffn

@geindex empty() (multiprocessing.SimpleQueue 的方法)
@anchor{library/multiprocessing multiprocessing SimpleQueue empty}@anchor{18d0}
@deffn {方法} empty ()

Return @code{True} if the queue is empty, @code{False} otherwise.

Always raises an @ref{2c0,,OSError} if the SimpleQueue is closed.
@end deffn

@geindex get() (multiprocessing.SimpleQueue 的方法)
@anchor{library/multiprocessing multiprocessing SimpleQueue get}@anchor{3529}
@deffn {方法} get ()

Remove and return an item from the queue.
@end deffn

@geindex put() (multiprocessing.SimpleQueue 的方法)
@anchor{library/multiprocessing multiprocessing SimpleQueue put}@anchor{352a}
@deffn {方法} put (item)

Put `item' into the queue.
@end deffn
@end deffn

@geindex JoinableQueue (multiprocessing 中的類別)
@anchor{library/multiprocessing multiprocessing JoinableQueue}@anchor{351b}
@deffn {類別} multiprocessing.JoinableQueue ([maxsize])

@ref{351b,,JoinableQueue}, a @ref{1ab3,,Queue} subclass, is a queue which
additionally has @ref{351e,,task_done()} and @ref{352b,,join()} methods.

@geindex task_done() (multiprocessing.JoinableQueue 的方法)
@anchor{library/multiprocessing multiprocessing JoinableQueue task_done}@anchor{351e}
@deffn {方法} task_done ()

Indicate that a formerly enqueued task is complete. Used by queue
consumers.  For each @ref{1ce6,,get()} used to fetch a task, a subsequent
call to @ref{351e,,task_done()} tells the queue that the processing on the task
is complete.

If a @ref{351d,,join()} is currently blocking, it will resume when all
items have been processed (meaning that a @ref{351e,,task_done()} call was
received for every item that had been @ref{1ce5,,put()} into the queue).

Raises a @ref{2eb,,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{352b}
@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{351e,,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{351d,,join()} unblocks.
@end deffn
@end deffn

@node Miscellaneous<3>,Connection Objects,Pipes and Queues,Reference<3>
@anchor{library/multiprocessing miscellaneous}@anchor{352c}
@subsubsection Miscellaneous


@geindex active_children() (於 multiprocessing 模組中)
@anchor{library/multiprocessing multiprocessing active_children}@anchor{352d}
@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{116a}
@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{4d5,,os.process_cpu_count()} (or @code{len(os.sched_getaffinity(0))}).

When the number of CPUs cannot be determined a @ref{369,,NotImplementedError}
is raised.


@subsubheading 也參考


@ref{4d6,,os.cpu_count()}
@ref{4d5,,os.process_cpu_count()}



在 3.13 版的變更: The return value can also be overridden using the
@ref{16f,,-X cpu_count} flag or 
@geindex PYTHON_CPU_COUNT
@geindex 環境變數; PYTHON_CPU_COUNT
@ref{519,,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{352e}
@deffn {函式} multiprocessing.current_process ()

Return the @ref{252,,Process} object corresponding to the current process.

An analogue of @ref{35c,,threading.current_thread()}.
@end deffn

@geindex parent_process() (於 multiprocessing 模組中)
@anchor{library/multiprocessing multiprocessing parent_process}@anchor{352f}
@deffn {函式} multiprocessing.parent_process ()

Return the @ref{252,,Process} object corresponding to the parent process of
the @ref{352e,,current_process()}. For the main process, @code{parent_process} will
be @code{None}.


在 3.8 版被加入.

@end deffn

@geindex freeze_support() (於 multiprocessing 模組中)
@anchor{library/multiprocessing multiprocessing freeze_support}@anchor{17b8}
@deffn {函式} multiprocessing.freeze_support ()

Add support for when a program which uses @ref{98,,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{244,,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{1164}
@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{1d5,,Contexts and start methods}.


在 3.4 版被加入.

@end deffn

@geindex get_context() (於 multiprocessing 模組中)
@anchor{library/multiprocessing multiprocessing get_context}@anchor{24a}
@deffn {函式} multiprocessing.get_context (method=None)

Return a context object which has the same attributes as the
@ref{98,,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
default method.
Otherwise `method' should be @code{'fork'}, @code{'spawn'},
@code{'forkserver'}.  @ref{2eb,,ValueError} is raised if the specified
start method is not available.  See @ref{1d5,,Contexts and start methods}.


在 3.4 版被加入.

@end deffn

@geindex get_start_method() (於 multiprocessing 模組中)
@anchor{library/multiprocessing multiprocessing get_start_method}@anchor{1165}
@deffn {函式} multiprocessing.get_start_method (allow_none=False)

Return the name of start method used for starting processes.

If the global start method has not been set and `allow_none' is
@code{False}, then the start method is set to the default and the name
is returned. If the start method has not been set and `allow_none' is
@code{True} then @code{None} is returned.

The return value can be @code{'fork'}, @code{'spawn'}, @code{'forkserver'}
or @code{None}.  See @ref{1d5,,Contexts and start methods}.


在 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{1aba}
@deffn {函式} multiprocessing.set_executable (executable)

Set the path of the Python interpreter to use when starting a child process.
(By default @ref{3eb,,sys.executable} is used).  Embedders will probably need to
do some thing like

@example
set_executable(os.path.join(sys.exec_prefix, 'pythonw.exe'))
@end example

before they can create child processes.


在 3.4 版的變更: Now supported on POSIX when the @code{'spawn'} start method is used.



在 3.11 版的變更: 接受一個@ref{59b,,類路徑物件}。

@end deffn

@geindex set_forkserver_preload() (於 multiprocessing 模組中)
@anchor{library/multiprocessing multiprocessing set_forkserver_preload}@anchor{1873}
@deffn {函式} multiprocessing.set_forkserver_preload (module_names)

Set a list of module names for the forkserver main process to attempt to
import so that their already imported state is inherited by forked
processes. Any @ref{653,,ImportError} when doing so is silently ignored.
This can be used as a performance enhancement to avoid repeated work
in every process.

For this to work, it must be called before the forkserver process has been
launched (before creating a @code{Pool} or starting a @ref{252,,Process}).

Only meaningful when using the @code{'forkserver'} start method.
See @ref{1d5,,Contexts and start methods}.


在 3.4 版被加入.

@end deffn

@geindex set_start_method() (於 multiprocessing 模組中)
@anchor{library/multiprocessing multiprocessing set_start_method}@anchor{24b}
@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{244,,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.

參閱 @ref{1d5,,Contexts and start methods}。


在 3.4 版被加入.

@end deffn

@cartouche
@quotation 備註 
@ref{98,,multiprocessing} contains no analogues of
@ref{35d,,threading.active_count()}, @ref{1b5c,,threading.enumerate()},
@ref{a41,,threading.settrace()}, @ref{a42,,threading.setprofile()},
@ref{135a,,threading.Timer}, or @ref{17df,,threading.local}.
@end quotation
@end cartouche

@node Connection Objects,Synchronization primitives,Miscellaneous<3>,Reference<3>
@anchor{library/multiprocessing connection-objects}@anchor{3530}
@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{3502,,Pipe} -- see also
@ref{3531,,Listeners and Clients}.

@geindex Connection (multiprocessing.connection 中的類別)
@anchor{library/multiprocessing multiprocessing connection Connection}@anchor{12e1}
@deffn {類別} multiprocessing.connection.Connection

@geindex send() (multiprocessing.connection.Connection 的方法)
@anchor{library/multiprocessing multiprocessing connection Connection send}@anchor{3532}
@deffn {方法} send (obj)

Send an object to the other end of the connection which should be read
using @ref{3533,,recv()}.

The object must be picklable.  Very large pickles (approximately 32 MiB+,
though it depends on the OS) may raise a @ref{2eb,,ValueError} exception.
@end deffn

@geindex recv() (multiprocessing.connection.Connection 的方法)
@anchor{library/multiprocessing multiprocessing connection Connection recv}@anchor{3533}
@deffn {方法} recv ()

Return an object sent from the other end of the connection using
@ref{3532,,send()}.  Blocks until there is something to receive.  Raises
@ref{14da,,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{3534}
@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{3535}
@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{3536}
@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{12e0,,multiprocessing.connection.wait()}.
@end deffn

@geindex send_bytes() (multiprocessing.connection.Connection 的方法)
@anchor{library/multiprocessing multiprocessing connection Connection send_bytes}@anchor{3537}
@deffn {方法} send_bytes (buffer[, offset[, size]])

Send byte data from a @ref{193,,bytes-like object} as a complete message.

If `offset' is given then data is read from that position in `buffer'.  If
`size' is given then that many bytes will be read from buffer.  Very large
buffers (approximately 32 MiB+, though it depends on the OS) may raise a
@ref{2eb,,ValueError} exception
@end deffn

@geindex recv_bytes() (multiprocessing.connection.Connection 的方法)
@anchor{library/multiprocessing multiprocessing connection Connection recv_bytes}@anchor{3538}
@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{14da,,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{2c0,,OSError} is raised and the connection will no longer be
readable.


在 3.3 版的變更: This function used to raise @ref{124e,,IOError}, which is now an
alias of @ref{2c0,,OSError}.

@end deffn

@geindex recv_bytes_into() (multiprocessing.connection.Connection 的方法)
@anchor{library/multiprocessing multiprocessing connection Connection recv_bytes_into}@anchor{3539}
@deffn {方法} recv_bytes_into (buffer[, offset])

Read into `buffer' 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{14da,,EOFError} if there is nothing left to receive and the other end was
closed.

`buffer' must be a writable @ref{193,,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 `buffer' (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{3532,,Connection.send()} and @ref{3533,,Connection.recv()}.

Connection objects also now support the context management protocol -- see
@ref{22bc,,情境管理器型別}.  @ref{2552,,__enter__()} returns the
connection object, and @ref{2553,,__exit__()} calls @ref{3535,,close()}.

@end deffn

舉例來說：

@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{353a}
@cartouche
@quotation 警告 
The @ref{3533,,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{3533,,recv()} and @ref{3532,,send()}
methods after performing some sort of authentication.  See
@ref{3515,,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,共享的 ctypes 物件,Connection Objects,Reference<3>
@anchor{library/multiprocessing synchronization-primitives}@anchor{353b}
@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{f3,,threading} module.

Note that one can also create synchronization primitives by using a manager
object -- see @ref{351f,,Managers}.

@geindex Barrier (multiprocessing 中的類別)
@anchor{library/multiprocessing multiprocessing Barrier}@anchor{350b}
@deffn {類別} multiprocessing.Barrier (parties[, action[, timeout]])

A barrier object: a clone of @ref{13e4,,threading.Barrier}.


在 3.3 版被加入.

@end deffn

@geindex BoundedSemaphore (multiprocessing 中的類別)
@anchor{library/multiprocessing multiprocessing BoundedSemaphore}@anchor{3509}
@deffn {類別} multiprocessing.BoundedSemaphore ([value])

A bounded semaphore object: a close analog of
@ref{1358,,threading.BoundedSemaphore}.

A solitary difference from its close analog exists: its @code{acquire} method's
first argument is named `block', as is consistent with @ref{353c,,Lock.acquire()}.

@cartouche
@quotation 備註 
On macOS, this is indistinguishable from @ref{3508,,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{350a}
@deffn {類別} multiprocessing.Condition ([lock])

A condition variable: an alias for @ref{1356,,threading.Condition}.

If `lock' is specified then it should be a @ref{17d2,,Lock} or @ref{17d3,,RLock}
object from @ref{98,,multiprocessing}.


在 3.3 版的變更: The @ref{34e3,,wait_for()} method was added.

@end deffn

@geindex Event (multiprocessing 中的類別)
@anchor{library/multiprocessing multiprocessing Event}@anchor{1b1a}
@deffn {類別} multiprocessing.Event

A clone of @ref{1359,,threading.Event}.
@end deffn

@geindex Lock (multiprocessing 中的類別)
@anchor{library/multiprocessing multiprocessing Lock}@anchor{17d2}
@deffn {類別} multiprocessing.Lock

A non-recursive lock object: a close analog of @ref{1943,,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
@ref{1943,,threading.Lock} as it applies to threads are replicated here in
@ref{17d2,,multiprocessing.Lock} as it applies to either processes or threads,
except as noted.

Note that @ref{17d2,,Lock} is actually a factory function which returns an
instance of @code{multiprocessing.synchronize.Lock} initialized with a
default context.

@ref{17d2,,Lock} supports the @ref{1e1,,context manager} protocol and thus may be
used in @ref{186,,with} statements.

@geindex acquire() (multiprocessing.Lock 的方法)
@anchor{library/multiprocessing multiprocessing Lock acquire}@anchor{353c}
@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{8a0,,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{8a0,,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{353d}
@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{14c3,,threading.Lock.release()} except that
when invoked on an unlocked lock, a @ref{2eb,,ValueError} is raised.
@end deffn

@geindex locked() (multiprocessing.Lock 的方法)
@anchor{library/multiprocessing multiprocessing Lock locked}@anchor{17f2}
@deffn {方法} locked ()

Return a boolean indicating whether this object is locked right now.


在 3.14 版被加入.

@end deffn
@end deffn

@geindex RLock (multiprocessing 中的類別)
@anchor{library/multiprocessing multiprocessing RLock}@anchor{17d3}
@deffn {類別} multiprocessing.RLock

A recursive lock object: a close analog of @ref{32d,,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 @ref{17d3,,RLock} is actually a factory function which returns an
instance of @code{multiprocessing.synchronize.RLock} initialized with a
default context.

@ref{17d3,,RLock} supports the @ref{1e1,,context manager} protocol and thus may be
used in @ref{186,,with} statements.

@geindex acquire() (multiprocessing.RLock 的方法)
@anchor{library/multiprocessing multiprocessing RLock acquire}@anchor{353e}
@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{1076,,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{353c,,Lock.acquire()}.  Note that some of these behaviors of `timeout'
differ from the implemented behaviors in @ref{1076,,threading.RLock.acquire()}.
@end deffn

@geindex release() (multiprocessing.RLock 的方法)
@anchor{library/multiprocessing multiprocessing RLock release}@anchor{353f}
@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{8b0,,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{34de,,threading.RLock.release()}.
@end deffn

@geindex locked() (multiprocessing.RLock 的方法)
@anchor{library/multiprocessing multiprocessing RLock locked}@anchor{17f3}
@deffn {方法} locked ()

Return a boolean indicating whether this object is locked right now.


在 3.14 版被加入.

@end deffn
@end deffn

@geindex Semaphore (multiprocessing 中的類別)
@anchor{library/multiprocessing multiprocessing Semaphore}@anchor{3508}
@deffn {類別} multiprocessing.Semaphore ([value])

A semaphore object: a close analog of @ref{1357,,threading.Semaphore}.

A solitary difference from its close analog exists: its @code{acquire} method's
first argument is named `block', as is consistent with @ref{353c,,Lock.acquire()}.
@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{653,,ImportError}. See
bpo-3770@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3770} for additional information.
@end quotation
@end cartouche

@node 共享的 ctypes 物件,Managers,Synchronization primitives,Reference<3>
@anchor{library/multiprocessing shared-ctypes-objects}@anchor{3540}
@subsubsection 共享的 @code{ctypes} 物件


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{3505}
@deffn {函式} multiprocessing.Value (typecode_or_type, *args, lock=True)

Return a @ref{2e,,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{3505,,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{17d2,,Lock} or @ref{17d3,,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{3506}
@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 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.

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{17d2,,Lock} or
@ref{17d3,,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{3190,,ctypes.c_char} has `value' and `raw'
attributes which allow one to use it to store and retrieve strings.
@end deffn

@menu
* multiprocessing.sharedctypes 模組: multiprocessing sharedctypes 模組. 

@end menu

@node multiprocessing sharedctypes 模組,,,共享的 ctypes 物件
@anchor{library/multiprocessing module-multiprocessing sharedctypes}@anchor{9e}@anchor{library/multiprocessing the-multiprocessing-sharedctypes-module}@anchor{3541}
@subsubsection @code{multiprocessing.sharedctypes} 模組


@geindex module; multiprocessing.sharedctypes

The @ref{9e,,multiprocessing.sharedctypes} module provides functions for allocating
@ref{2e,,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{3542}
@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{3543,,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{3544}
@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{3545,,Value()} instead to make sure that access is automatically synchronized
using a lock.

Note that an array of @ref{3190,,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{2e,,ctypes}.
@end deffn

@geindex Array() (於 multiprocessing.sharedctypes 模組中)
@anchor{library/multiprocessing multiprocessing sharedctypes Array}@anchor{3543}
@deffn {函式} multiprocessing.sharedctypes.Array (typecode_or_type, size_or_initializer, *, lock=True)

The same as @ref{3542,,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{17d2,,Lock} or @ref{17d3,,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.
@end deffn

@geindex Value() (於 multiprocessing.sharedctypes 模組中)
@anchor{library/multiprocessing multiprocessing sharedctypes Value}@anchor{3545}
@deffn {函式} multiprocessing.sharedctypes.Value (typecode_or_type, *args, lock=True)

The same as @ref{3544,,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{17d2,,Lock} or
@ref{17d3,,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.
@end deffn

@geindex copy() (於 multiprocessing.sharedctypes 模組中)
@anchor{library/multiprocessing multiprocessing sharedctypes copy}@anchor{3546}
@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{102c}
@deffn {函式} multiprocessing.sharedctypes.synchronized (obj[, lock])

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{17d3,,multiprocessing.RLock} object is created automatically.

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{1e1,,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{1e5,,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,共享的 ctypes 物件,Reference<3>
@anchor{library/multiprocessing managers}@anchor{3547}@anchor{library/multiprocessing multiprocessing-managers}@anchor{351f}
@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{250}
@deffn {函式} multiprocessing.Manager ()

Returns a started @ref{180d,,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{3548}
@deffn {類別} multiprocessing.managers.BaseManager (address=None, authkey=None, serializer='pickle', ctx=None, *, shutdown_timeout=1.0)

建立一個 BaseManager 物件。

Once created one should call @ref{3549,,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{134,,xmlrpc.client} serialization).

`ctx' is a context object, or @code{None} (use the current context). See the
@code{get_context()} function.

`shutdown_timeout' is a timeout in seconds used to wait until the process
used by the manager completes in the @ref{354a,,shutdown()} method. If the
shutdown times out, the process is terminated. If terminating the process
also times out, the process is killed.


在 3.11 版的變更: 新增 `shutdown_timeout' 參數。


@geindex start() (multiprocessing.managers.BaseManager 的方法)
@anchor{library/multiprocessing multiprocessing managers BaseManager start}@anchor{3549}
@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{354b}
@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{354c,,address} attribute.
@end deffn

@geindex connect() (multiprocessing.managers.BaseManager 的方法)
@anchor{library/multiprocessing multiprocessing managers BaseManager connect}@anchor{354d}
@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{354a}
@deffn {方法} shutdown ()

Stop the process used by the manager.  This is only available if
@ref{3549,,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{354e}
@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{354d,,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{354f,,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{3550,,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{773,,__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

@ref{3548,,BaseManager} instances also have one read-only property:

@geindex address (multiprocessing.managers.BaseManager 的屬性)
@anchor{library/multiprocessing multiprocessing managers BaseManager address}@anchor{354c}
@deffn {屬性} address

The address used by the manager.
@end deffn


在 3.3 版的變更: Manager objects support the context management protocol -- see
@ref{22bc,,情境管理器型別}.  @ref{2552,,__enter__()} starts the
server process (if it has not already started) and then returns the
manager object.  @ref{2553,,__exit__()} calls @ref{354a,,shutdown()}.

In previous versions @ref{2552,,__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{180d}
@deffn {類別} multiprocessing.managers.SyncManager

A subclass of @ref{3548,,BaseManager} which can be used for the synchronization
of processes.  Objects of this type are returned by
@ref{250,,multiprocessing.Manager()}.

Its methods create and return @ref{24c,,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{3551}
@deffn {方法} Barrier (parties[, action[, timeout]])

Create a shared @ref{13e4,,threading.Barrier} object and return a
proxy for it.


在 3.3 版被加入.

@end deffn

@geindex BoundedSemaphore() (multiprocessing.managers.SyncManager 的方法)
@anchor{library/multiprocessing multiprocessing managers SyncManager BoundedSemaphore}@anchor{3552}
@deffn {方法} BoundedSemaphore ([value])

Create a shared @ref{1358,,threading.BoundedSemaphore} object and return a
proxy for it.
@end deffn

@geindex Condition() (multiprocessing.managers.SyncManager 的方法)
@anchor{library/multiprocessing multiprocessing managers SyncManager Condition}@anchor{3553}
@deffn {方法} Condition ([lock])

Create a shared @ref{1356,,threading.Condition} object and return a proxy for
it.

If `lock' is supplied then it should be a proxy for a
@ref{1943,,threading.Lock} or @ref{32d,,threading.RLock} object.


在 3.3 版的變更: The @ref{34e3,,wait_for()} method was added.

@end deffn

@geindex Event() (multiprocessing.managers.SyncManager 的方法)
@anchor{library/multiprocessing multiprocessing managers SyncManager Event}@anchor{3554}
@deffn {方法} Event ()

Create a shared @ref{1359,,threading.Event} object and return a proxy for it.
@end deffn

@geindex Lock() (multiprocessing.managers.SyncManager 的方法)
@anchor{library/multiprocessing multiprocessing managers SyncManager Lock}@anchor{158f}
@deffn {方法} Lock ()

Create a shared @ref{1943,,threading.Lock} object and return a proxy for it.
@end deffn

@geindex Namespace() (multiprocessing.managers.SyncManager 的方法)
@anchor{library/multiprocessing multiprocessing managers SyncManager Namespace}@anchor{3555}
@deffn {方法} Namespace ()

Create a shared @ref{3507,,Namespace} object and return a proxy for it.
@end deffn

@geindex Queue() (multiprocessing.managers.SyncManager 的方法)
@anchor{library/multiprocessing multiprocessing managers SyncManager Queue}@anchor{3079}
@deffn {方法} Queue ([maxsize])

Create a shared @ref{158c,,queue.Queue} object and return a proxy for it.
@end deffn

@geindex RLock() (multiprocessing.managers.SyncManager 的方法)
@anchor{library/multiprocessing multiprocessing managers SyncManager RLock}@anchor{1590}
@deffn {方法} RLock ()

Create a shared @ref{32d,,threading.RLock} object and return a proxy for it.
@end deffn

@geindex Semaphore() (multiprocessing.managers.SyncManager 的方法)
@anchor{library/multiprocessing multiprocessing managers SyncManager Semaphore}@anchor{1591}
@deffn {方法} Semaphore ([value])

Create a shared @ref{1357,,threading.Semaphore} object and return a proxy for
it.
@end deffn

@geindex Array() (multiprocessing.managers.SyncManager 的方法)
@anchor{library/multiprocessing multiprocessing managers SyncManager Array}@anchor{3556}
@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{3557}
@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{3558}
@deffn {方法} dict ()

@deffnx {方法} dict (mapping)

@deffnx {方法} dict (sequence)

Create a shared @ref{183,,dict} object and return a proxy for it.
@end deffn

@geindex list() (multiprocessing.managers.SyncManager 的方法)
@anchor{library/multiprocessing multiprocessing managers SyncManager list}@anchor{3559}
@deffn {方法} list ()

@deffnx {方法} list (sequence)

Create a shared @ref{24d,,list} object and return a proxy for it.
@end deffn

@geindex set() (multiprocessing.managers.SyncManager 的方法)
@anchor{library/multiprocessing multiprocessing managers SyncManager set}@anchor{24f}
@deffn {方法} set ()

@deffnx {方法} set (sequence)

@deffnx {方法} set (mapping)

Create a shared @ref{184,,set} object and return a proxy for it.


在 3.14 版被加入: 已新增對 @ref{184,,set} 的支援。

@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 @ref{180d,,SyncManager}.

@end deffn

@geindex Namespace (multiprocessing.managers 中的類別)
@anchor{library/multiprocessing multiprocessing managers Namespace}@anchor{3507}
@deffn {類別} multiprocessing.managers.Namespace

A type that can register with @ref{180d,,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{355a}
@subsubsection Customized managers


To create one's own manager, one creates a subclass of @ref{3548,,BaseManager} and
uses the @ref{354e,,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))         # 印出 7
        print(maths.mul(7, 8))         # 印出 56
@end example

@node Using a remote manager,,Customized managers,Managers
@anchor{library/multiprocessing using-a-remote-manager}@anchor{355b}
@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{24c}@anchor{library/multiprocessing proxy-objects}@anchor{355c}
@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{169,,str()} to a proxy will return the representation of
the referent, whereas applying @ref{1c1,,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{24c,,Proxy Objects}.  This permits nesting of these managed
lists, dicts, and other @ref{24c,,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{24d,,list} or @ref{183,,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{24c,,Proxy Objects} for most use cases but also
demonstrates a level of control over the synchronization.

@cartouche
@quotation 備註 
The proxy types in @ref{98,,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{354f}
@deffn {類別} multiprocessing.managers.BaseProxy

Proxy objects are instances of subclasses of @ref{354f,,BaseProxy}.

@geindex _callmethod() (multiprocessing.managers.BaseProxy 的方法)
@anchor{library/multiprocessing multiprocessing managers BaseProxy _callmethod}@anchor{3550}
@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{354e,,BaseManager.register()}.

If an exception is raised by the call, then is re-raised by
@ref{3550,,_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 @ref{3550,,_callmethod()}.

Note in particular that an exception will be raised if `methodname' has
not been `exposed'.

An example of the usage of @ref{3550,,_callmethod()}:

@example
>>> l = manager.list(range(10))
>>> l._callmethod('__len__')
10
>>> l._callmethod('__getitem__', (slice(2, 7),)) # 等價於 l[2:7]
[2, 3, 4, 5, 6]
>>> l._callmethod('__getitem__', (20,))          # 等價於 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{355d}
@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{355e}
@deffn {方法} __repr__ ()

Return a representation of the proxy object.
@end deffn

@geindex __str__() (multiprocessing.managers.BaseProxy 的方法)
@anchor{library/multiprocessing multiprocessing managers BaseProxy __str__}@anchor{355f}
@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{3560}
@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{3561}
@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{1166,,Pool} class.

@geindex Pool (multiprocessing.pool 中的類別)
@anchor{library/multiprocessing multiprocessing pool Pool}@anchor{1166}
@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{4d5,,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{1166,,Pool()} method
of a context object.  In both cases `context' is set
appropriately.

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{3562,,close()} and @ref{3563,,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{11f8,,object.__del__()} for more information).
@end quotation
@end cartouche


在 3.2 版的變更: 新增 `maxtasksperchild'  參數。



在 3.4 版的變更: 新增 `context' 參數。



在 3.13 版的變更: `processes' uses @ref{4d5,,os.process_cpu_count()} by default, instead of
@ref{4d6,,os.cpu_count()}.


@cartouche
@quotation 備註 
Worker processes within a @ref{1166,,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 being exiting, being cleaned up and a new
process spawned to replace the old one. The `maxtasksperchild'
argument to the @ref{1166,,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{158d}
@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{158e,,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{158e}
@deffn {方法} apply_async (func[, args[, kwds[, callback[, error_callback]]]])

A variant of the @ref{158d,,apply()} method which returns a
@ref{3564,,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{12e6}
@deffn {方法} map (func, iterable[, chunksize])

A parallel equivalent of the @ref{19f,,map()} built-in function (it supports only
one `iterable' argument though, for multiple iterables see @ref{12e3,,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{3565,,imap()} or @ref{3566,,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{12e7}
@deffn {方法} map_async (func, iterable[, chunksize[, callback[, error_callback]]])

A variant of the @ref{12e6,,map()} method which returns a
@ref{3564,,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{3565}
@deffn {方法} imap (func, iterable[, chunksize])

A lazier version of @ref{12e6,,map()}.

The `chunksize' argument is the same as the one used by the @ref{12e6,,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 @ref{3565,,imap()} method has an optional `timeout' parameter:
@code{next(timeout)} will raise @ref{3519,,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{3566}
@deffn {方法} imap_unordered (func, iterable[, chunksize])

The same as @ref{3565,,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{12e3}
@deffn {方法} starmap (func, iterable[, chunksize])

Like @ref{12e6,,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)]}.


在 3.3 版被加入.

@end deffn

@geindex starmap_async() (multiprocessing.pool.Pool 的方法)
@anchor{library/multiprocessing multiprocessing pool Pool starmap_async}@anchor{12e4}
@deffn {方法} starmap_async (func, iterable[, chunksize[, callback[, error_callback]]])

A combination of @ref{12e3,,starmap()} and @ref{12e7,,map_async()} that iterates over
`iterable' of iterables and calls `func' with the iterables unpacked.
Returns a result object.


在 3.3 版被加入.

@end deffn

@geindex close() (multiprocessing.pool.Pool 的方法)
@anchor{library/multiprocessing multiprocessing pool Pool close}@anchor{3562}
@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{3563}
@deffn {方法} terminate ()

Stops the worker processes immediately without completing outstanding
work.  When the pool object is garbage collected @ref{3563,,terminate()} will be
called immediately.
@end deffn

@geindex join() (multiprocessing.pool.Pool 的方法)
@anchor{library/multiprocessing multiprocessing pool Pool join}@anchor{3567}
@deffn {方法} join ()

Wait for the worker processes to exit.  One must call @ref{3562,,close()} or
@ref{3563,,terminate()} before using @ref{3567,,join()}.
@end deffn


在 3.3 版的變更: Pool objects now support the context management protocol -- see
@ref{22bc,,情境管理器型別}.  @ref{2552,,__enter__()} returns the
pool object, and @ref{2553,,__exit__()} calls @ref{3563,,terminate()}.

@end deffn

@geindex AsyncResult (multiprocessing.pool 中的類別)
@anchor{library/multiprocessing multiprocessing pool AsyncResult}@anchor{3564}
@deffn {類別} multiprocessing.pool.AsyncResult

The class of the result returned by @ref{158e,,Pool.apply_async()} and
@ref{12e7,,Pool.map_async()}.

@geindex get() (multiprocessing.pool.AsyncResult 的方法)
@anchor{library/multiprocessing multiprocessing pool AsyncResult get}@anchor{3568}
@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{3519,,multiprocessing.TimeoutError} is raised.  If the remote call raised
an exception then that exception will be reraised by @ref{3568,,get()}.
@end deffn

@geindex wait() (multiprocessing.pool.AsyncResult 的方法)
@anchor{library/multiprocessing multiprocessing pool AsyncResult wait}@anchor{3569}
@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{356a}
@deffn {方法} ready ()

Return whether the call has completed.
@end deffn

@geindex successful() (multiprocessing.pool.AsyncResult 的方法)
@anchor{library/multiprocessing multiprocessing pool AsyncResult successful}@anchor{356b}
@deffn {方法} successful ()

Return whether the call completed without raising an exception.  Will
raise @ref{2eb,,ValueError} if the result is not ready.


在 3.7 版的變更: If the result is not ready, @ref{2eb,,ValueError} is raised instead of
@ref{8b0,,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{356c}@anchor{library/multiprocessing module-multiprocessing connection}@anchor{99}@anchor{library/multiprocessing multiprocessing-listeners-clients}@anchor{3531}
@subsubsection Listeners and Clients


@geindex module; multiprocessing.connection

Usually message passing between processes is done using queues or by using
@ref{12e1,,Connection} objects returned by
@ref{3502,,Pipe()}.

However, the @ref{99,,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{6e,,hmac} module, and for polling
multiple connections at the same time.

@geindex deliver_challenge() (於 multiprocessing.connection 模組中)
@anchor{library/multiprocessing multiprocessing connection deliver_challenge}@anchor{356d}
@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{3518,,AuthenticationError} is raised.
@end deffn

@geindex answer_challenge() (於 multiprocessing.connection 模組中)
@anchor{library/multiprocessing multiprocessing connection answer_challenge}@anchor{356e}
@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{3518,,AuthenticationError} is raised.
@end deffn

@geindex Client() (於 multiprocessing.connection 模組中)
@anchor{library/multiprocessing multiprocessing connection Client}@anchor{356f}
@deffn {函式} multiprocessing.connection.Client (address[, family[, authkey]])

Attempt to set up a connection to the listener which is using address
`address', returning a @ref{12e1,,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{3570,,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{3518,,AuthenticationError} is raised if authentication fails.
See @ref{3515,,Authentication keys}.
@end deffn

@geindex Listener (multiprocessing.connection 中的類別)
@anchor{library/multiprocessing multiprocessing connection Listener}@anchor{1973}
@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{3570,,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{2b7c,,tempfile.mkstemp()}.

If the listener object uses a socket then `backlog' (1 by default) is passed
to the @ref{1059,,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{3518,,AuthenticationError} is raised if authentication fails.
See @ref{3515,,Authentication keys}.

@geindex accept() (multiprocessing.connection.Listener 的方法)
@anchor{library/multiprocessing multiprocessing connection Listener accept}@anchor{192e}
@deffn {方法} accept ()

Accept a connection on the bound socket or named pipe of the listener
object and return a @ref{12e1,,Connection} object.
If authentication is attempted and fails, then
@ref{3518,,AuthenticationError} is raised.
@end deffn

@geindex close() (multiprocessing.connection.Listener 的方法)
@anchor{library/multiprocessing multiprocessing connection Listener close}@anchor{3571}
@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{3572}
@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{3573}
@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{22bc,,情境管理器型別}.  @ref{2552,,__enter__()} returns the
listener object, and @ref{2553,,__exit__()} calls @ref{3571,,close()}.

@end deffn

@geindex wait() (於 multiprocessing.connection 模組中)
@anchor{library/multiprocessing multiprocessing connection wait}@anchor{12e0}
@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{12e1,,Connection} object;

@item 
a connected and readable @ref{f9c,,socket.socket} object; or

@item 
the @ref{12e2,,sentinel} attribute of a
@ref{252,,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{f9b,,select.select()} is interrupted by a signal, it can
raise @ref{2c0,,OSError} with an error number of @code{EINTR}, whereas
@ref{12e0,,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{2b7e,,fileno()} method which returns a
socket handle or pipe handle.  (Note that pipe handles and socket
handles are `not' waitable handles.)


在 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{12e0,,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{3574}@anchor{library/multiprocessing multiprocessing-address-formats}@anchor{3570}
@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{356f,,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,Listeners and Clients,Reference<3>
@anchor{library/multiprocessing authentication-keys}@anchor{3575}@anchor{library/multiprocessing multiprocessing-auth-keys}@anchor{3515}
@subsubsection Authentication keys


When one uses @ref{3533,,Connection.recv}, the
data received is automatically
unpickled. Unfortunately unpickling data from an untrusted source is a security
risk. Therefore @ref{1973,,Listener} and @ref{356f,,Client()} use the @ref{6e,,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{252,,Process}).  This value will be automatically inherited by
any @ref{252,,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{73f,,os.urandom()}.

@node Logging,multiprocessing dummy 模組,Authentication keys,Reference<3>
@anchor{library/multiprocessing logging}@anchor{3576}
@subsubsection Logging


Some support for logging is available.  Note, however, that the @ref{8b,,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{30d4}
@deffn {函式} multiprocessing.get_logger ()

Returns the logger used by @ref{98,,multiprocessing}.  If necessary, a new one
will be created.

When first created the logger has level @ref{300e,,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{3577}
@deffn {函式} multiprocessing.log_to_stderr (level=None)

This function performs a call to @ref{30d4,,get_logger()} but in addition to
returning the logger created by get_logger, it adds a handler which sends
output to @ref{b2a,,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{8b,,logging} module.

@node multiprocessing dummy 模組,,Logging,Reference<3>
@anchor{library/multiprocessing module-multiprocessing dummy}@anchor{9a}@anchor{library/multiprocessing the-multiprocessing-dummy-module}@anchor{3578}
@subsubsection @code{multiprocessing.dummy} 模組


@geindex module; multiprocessing.dummy

@ref{9a,,multiprocessing.dummy} replicates the API of @ref{98,,multiprocessing} but is
no more than a wrapper around the @ref{f3,,threading} module.

In particular, the @code{Pool} function provided by @ref{9a,,multiprocessing.dummy}
returns an instance of @ref{1bc6,,ThreadPool}, which is a subclass of
@ref{1166,,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{1bc6}
@deffn {類別} multiprocessing.pool.ThreadPool ([processes[, initializer[, initargs]]])

A thread pool object which controls a pool of worker threads to which jobs
can be submitted.  @ref{1bc6,,ThreadPool} instances are fully interface
compatible with @ref{1166,,Pool} instances, and their resources must also be
properly managed, either by using the pool as a context manager or by
calling @ref{3562,,close()} and
@ref{3563,,terminate()} manually.

`processes' is the number of worker threads to use.  If `processes' is
@code{None} then the number returned by @ref{4d5,,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{1166,,Pool}, `maxtasksperchild' and `context' cannot be provided.

@cartouche
@quotation 備註 
A @ref{1bc6,,ThreadPool} shares the same interface as @ref{1166,,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{3564,,AsyncResult}, that is not understood by any other libraries.

Users should generally prefer to use
@ref{941,,concurrent.futures.ThreadPoolExecutor}, which has a simpler
interface that was designed around threads from the start, and which
returns @ref{13b3,,concurrent.futures.Future} instances that are
compatible with many other libraries, including @ref{b,,asyncio}.
@end quotation
@end cartouche
@end deffn

@node Programming guidelines,範例<20>,Reference<3>,multiprocessing --- 以行程為基礎的平行性
@anchor{library/multiprocessing multiprocessing-programming}@anchor{34fe}@anchor{library/multiprocessing programming-guidelines}@anchor{3579}
@subsubsection Programming guidelines


There are certain guidelines and idioms which should be adhered to when using
@ref{98,,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{357a}
@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{352d,,active_children()} is called) all completed processes
which have not yet been joined will be joined.  Also calling a finished
process's @ref{158a,,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 @ref{98,,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{17d6,,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{17d6,,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{3523,,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{758,,sys.stdin} with a "file like object"

@quotation

@ref{98,,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{758,,sys.stdin()} with a "file-like object"
with output buffering.  This danger is that if multiple processes call
@ref{501,,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{3511}
@node The spawn and forkserver start methods,,All start methods,Programming guidelines
@anchor{library/multiprocessing multiprocessing-programming-forkserver}@anchor{1d9}@anchor{library/multiprocessing the-spawn-and-forkserver-start-methods}@anchor{357b}
@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{252,,Process} are
picklable.  Also, if you subclass @code{Process.__init__}, you must make sure
that instances will be picklable when the
@ref{1589,,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{1589,,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{357c}
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{244,,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 範例<20>,,Programming guidelines,multiprocessing --- 以行程為基礎的平行性
@anchor{library/multiprocessing examples}@anchor{357d}@anchor{library/multiprocessing multiprocessing-examples}@anchor{3524}
@subsubsection 範例


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

使用 @ref{1166,,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 --- 對於共享記憶體的跨行程直接存取,concurrent 套件,multiprocessing --- 以行程為基礎的平行性,並行執行 Concurrent Execution
@anchor{library/multiprocessing shared_memory doc}@anchor{357e}@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{357f}@anchor{library/multiprocessing shared_memory translation-repo}@anchor{3580}
@subsection @code{multiprocessing.shared_memory} --- 對於共享記憶體的跨行程直接存取


@geindex module; multiprocessing.shared_memory

`原始碼：'Lib/multiprocessing/shared_memory.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/multiprocessing/shared_memory.py}


在 3.8 版被加入.


@geindex Shared Memory（共享記憶體）
@geindex POSIX Shared Memory（POSIX 共享記憶體）
@geindex Named Shared Memory（附名共享記憶體）


__________________________________________________________________


該模組提供了一個 @ref{1927,,SharedMemory} 類別，用於分配和管理被多核心或對稱多處理器 (symmetric multiprocessor, SMP) 機器上的一個或多個行程存取的共享記憶體。為了協助共享記憶體的生命週期管理，特別是跨不同行程的管理，@ref{9b,,multiprocessing.managers} 模組中還提供了一個 @ref{3548,,BaseManager} 子類別 @ref{3581,,SharedMemoryManager}。

在此模組中，共享記憶體是指「POSIX 風格」的共享記憶體區塊（儘管不一定如此明確實作），而不是指「分散式共享記憶體 (distributed shared memory)」。這種型別的共享記憶體允許不同的行程潛在地讀取和寫入揮發性記憶體 (volatile memory) 的公開（或共享）區域。通常行程只能存取自己的行程記憶體空間，但共享記憶體允許在行程之間共享資料，從而避免需要跨行程傳遞資料的情境。與透過硬碟或 socket 或其他需要序列化/還原序列化 (serialization/deserialization) 和複製資料的通訊方式以共享資料相比，直接透過記憶體共享資料可以提供顯著的性能優勢。

@geindex SharedMemory (multiprocessing.shared_memory 中的類別)
@anchor{library/multiprocessing shared_memory multiprocessing shared_memory SharedMemory}@anchor{1927}
@deffn {類別} multiprocessing.shared_memory.SharedMemory (name=None, create=False, size=0, *, track=True)

建立 @code{SharedMemory} 類別的實例，用於建立新的共享記憶體區塊或附加到現有的共享記憶體區塊。每個共享記憶體區塊都被分配了一個唯一的名稱。透過這種方式，一個行程可以建立具有特定名稱的共享記憶體區塊，而不同的行程可以使用該相同名稱附加到同一共享記憶體塊。

作為跨行程共享資料的資源，共享記憶體區塊的壽命可能比建立它們的原始行程還要長。當一個行程不再需要存取但其他行程可能仍需要的共享記憶體區塊時，應該呼叫 @ref{3582,,close()} 方法。當任何行程不再需要共享記憶體區塊時，應呼叫 @ref{3583,,unlink()} 方法以確保正確清理。

@*參數: 

@itemize *

@item 
@code{name} (@ref{169,,str}@code{ | }@code{None}) -- 所請求的共享記憶體的唯一名稱，指定為字串。建立新的共享記憶體區塊時，如果名稱提供為 @code{None}（預設值），則會生成一個新的名稱。

@item 
@code{create} (@ref{3c1,,bool}) -- 控制是否建立新的共享記憶體區塊 (@code{True}) 或附加現有的共享記憶體區塊 (@code{False})。

@item 
@code{size} (@ref{19b,,int}) -- 指定建立新共享記憶體區塊時請求的位元組數。由於某些平台會根據該平台的記憶體頁 (memory page) 大小來選擇分配記憶體區塊，因此共享記憶體區塊的確切大小可能大於或等於請求的大小。當附加到現有共享記憶體區塊時，@code{size} 參數將被忽略。

@item 
@code{track} (@ref{3c1,,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{dc,,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 版的變更: 新增 `track' 參數。


@geindex close() (multiprocessing.shared_memory.SharedMemory 的方法)
@anchor{library/multiprocessing shared_memory multiprocessing shared_memory SharedMemory close}@anchor{3582}
@deffn {方法} close ()

Close the file descriptor/handle to the shared memory from this
instance.  @ref{3582,,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{3583,,unlink()} method.
@end deffn

@geindex unlink() (multiprocessing.shared_memory.SharedMemory 的方法)
@anchor{library/multiprocessing shared_memory multiprocessing shared_memory SharedMemory unlink}@anchor{3583}
@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.
@ref{3583,,unlink()} and @ref{3582,,close()} can be called in any order, but
trying to access data inside a shared memory block after @ref{3583,,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{3584}
@deffn {屬性} buf

共享記憶體區塊內容的記憶體視圖 (memoryview)。
@end deffn

@geindex name (multiprocessing.shared_memory.SharedMemory 的屬性)
@anchor{library/multiprocessing shared_memory multiprocessing shared_memory SharedMemory name}@anchor{3585}
@deffn {屬性} name

對共享記憶體區塊之唯一名稱的唯讀存取。
@end deffn

@geindex size (multiprocessing.shared_memory.SharedMemory 的屬性)
@anchor{library/multiprocessing shared_memory multiprocessing shared_memory SharedMemory size}@anchor{3586}
@deffn {屬性} size

對共享記憶體區塊大小（以位元組為單位）的唯讀存取。
@end deffn
@end deffn

以下範例示範了 @ref{1927,,SharedMemory} 實例的低階使用方式：

@example
>>> from multiprocessing import shared_memory
>>> shm_a = shared_memory.SharedMemory(create=True, size=10)
>>> type(shm_a.buf)
<class 'memoryview'>
>>> buffer = shm_a.buf
>>> len(buffer)
10
>>> buffer[:4] = bytearray([22, 33, 44, 55])  # Modify multiple at once
>>> buffer[4] = 100                           # Modify single byte at a time
>>> # Attach to an existing shared memory block
>>> shm_b = shared_memory.SharedMemory(shm_a.name)
>>> import array
>>> array.array('b', shm_b.buf[:5])  # Copy the data into a new array.array
array('b', [22, 33, 44, 55, 100])
>>> shm_b.buf[:5] = b'howdy'  # Modify via shm_b using bytes
>>> bytes(shm_a.buf[:5])      # Access via shm_a
b'howdy'
>>> shm_b.close()   # Close each SharedMemory instance
>>> shm_a.close()
>>> shm_a.unlink()  # Call unlink only once to release the shared memory
@end example

以下範例示範了 @ref{1927,,SharedMemory} 類別與 NumPy 陣列@footnote{https://numpy.org/}的實際用法：從兩個不同的 Python shell 存取相同的 @code{numpy.ndarray}：

@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{3581}
@deffn {類別} multiprocessing.managers.SharedMemoryManager ([address[, authkey]])

@ref{3548,,multiprocessing.managers.BaseManager} 的子類別，可用於跨行程管理共享記憶體區塊。

在 @code{SharedMemoryManager} 實例上呼叫 @ref{3549,,start()} 會啟動一個新行程。這個新行程的唯一目的是管理那些透過它建立出的所有共享記憶體區塊的生命週期。要觸發釋放該行程管理的所有共享記憶體區塊，請在實例上呼叫 @ref{354a,,shutdown()}，這會觸發對該行程管理的所有 @ref{3587,,SharedMemory} 物件的 @ref{3583,,unlink()} 呼叫，然後再停止這個行程。透過 @code{SharedMemoryManager} 建立  @code{SharedMemory} 實例，我們無需手動追蹤和觸發共享記憶體資源的釋放。

此類別提供了用於建立和回傳 @ref{3587,,SharedMemory} 實例以及建立由共享記憶體支援的類串列物件 (@ref{3588,,ShareableList}) 的方法。

請參閱 @ref{3548,,BaseManager} 了解繼承的 `address' 和 `authkey' 可選輸入引數的描述以及如何使用它們從其他行程連接到現有的 @code{SharedMemoryManager} 服務。

@geindex SharedMemory() (multiprocessing.managers.SharedMemoryManager 的方法)
@anchor{library/multiprocessing shared_memory multiprocessing managers SharedMemoryManager SharedMemory}@anchor{3587}
@deffn {方法} SharedMemory (size)

建立並回傳一個新的 @ref{3587,,SharedMemory} 物件，該物件具有指定的 `size'（以位元組為單位）。
@end deffn

@geindex ShareableList() (multiprocessing.managers.SharedMemoryManager 的方法)
@anchor{library/multiprocessing shared_memory multiprocessing managers SharedMemoryManager ShareableList}@anchor{3588}
@deffn {方法} ShareableList (sequence)

建立並回傳一個新的 @ref{3588,,ShareableList} 物件，該物件由輸入 `sequence' 中的值初始化。
@end deffn
@end deffn

以下範例示範了 @ref{3581,,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

以下範例描述了一種可能更方便的模式，即透過 @ref{186,,with} 陳述式使用 @ref{3581,,SharedMemoryManager} 物件，以確保所有共享記憶體區塊不再被需要後都被釋放：

@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

在 @ref{186,,with} 陳述式中使用 @ref{3581,,SharedMemoryManager} 時，當 @code{with} 陳述式的程式碼區塊執行完畢時，使用該管理器建立的共享記憶體區塊都會被釋放。

@geindex ShareableList (multiprocessing.shared_memory 中的類別)
@anchor{library/multiprocessing shared_memory multiprocessing shared_memory ShareableList}@anchor{1c21}
@deffn {類別} multiprocessing.shared_memory.ShareableList (sequence=None, *, name=None)

提供一個類似 list 的可變物件，其中儲存的所有值都儲存在共享記憶體區塊中。這將可儲存值限制為以下內建資料型別：


@itemize *

@item 
@ref{19b,,int} （有符號 64 位元）

@item 
@ref{196,,float}

@item 
@ref{3c1,,bool}

@item 
@ref{169,,str} （編碼為 UTF-8 時每個小於 10M 位元組）

@item 
@ref{192,,bytes} （每個小於 10M 位元組）

@item 
@code{None}
@end itemize

它也與內建 @ref{24d,,list} 型別明顯不同，因為這些 list 不能更改其總長度（即沒有 @code{append()}、@code{insert()} 等）並且不支援通過切片動態建立新的 @code{ShareableList} 實例。

`sequence' 用於填充 (populate) 一個充滿值的新 @code{ShareableList}。設定為 @code{None} 以透過其唯一的共享記憶體名稱來附加到已經存在的 @code{ShareableList}。

如 @ref{1927,,SharedMemory} 的定義中所述，`name' 是被請求之共享記憶體的唯一名稱。當附加到現有的 @code{ShareableList} 時，指定其共享記憶體區塊的唯一名稱，同時將 `sequence' 設定為 @code{None}。

@cartouche
@quotation 備註 
@ref{192,,bytes} 和 @ref{169,,str} 值存在一個已知問題。如果它們以 @code{\x00} nul 位元組或字元結尾，那麼當透過索引從 @code{ShareableList} 中取得它們時，這些位元組或字元可能會被`默默地剝離 (silently stripped)'。這種 @code{.rstrip(b'\x00')} 行為被認為是一個錯誤，將來可能會消失。請參閱 gh-106939@footnote{https://github.com/python/cpython/issues/106939}。
@end quotation
@end cartouche

對於去除尾隨空值 (rstripping of trailing nulls) 會出問題的應用程式，變通解法 (workaround) 是始終無條件地在儲存時於此類值的末尾追加一個額外非 0 位元組，並在取得時也無條件地刪除它：

@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{3589}
@deffn {方法} count (value)

回傳 `value' 出現的次數。
@end deffn

@geindex index() (multiprocessing.shared_memory.ShareableList 的方法)
@anchor{library/multiprocessing shared_memory multiprocessing shared_memory ShareableList index}@anchor{358a}
@deffn {方法} index (value)

回傳 `value' 的第一個索引位置。如果 `value' 不存在，則引發 @ref{2eb,,ValueError}。
@end deffn

@geindex format (multiprocessing.shared_memory.ShareableList 的屬性)
@anchor{library/multiprocessing shared_memory multiprocessing shared_memory ShareableList format}@anchor{358b}
@deffn {屬性} format

唯讀屬性，包含所有目前有儲存的值所使用的 @ref{db,,struct} 打包格式。
@end deffn

@geindex shm (multiprocessing.shared_memory.ShareableList 的屬性)
@anchor{library/multiprocessing shared_memory multiprocessing shared_memory ShareableList shm}@anchor{358c}
@deffn {屬性} shm

儲存值的 @ref{1927,,SharedMemory} 實例。
@end deffn
@end deffn

以下範例示範了 @ref{1c21,,ShareableList} 實例的基本用法：

@example
>>> from multiprocessing import shared_memory
>>> a = shared_memory.ShareableList(['howdy', b'HoWdY', -273.154, 100, None, True, 42])
>>> [ type(entry) for entry in a ]
[<class 'str'>, <class 'bytes'>, <class 'float'>, <class 'int'>, <class 'NoneType'>, <class 'bool'>, <class 'int'>]
>>> a[2]
-273.154
>>> a[2] = -78.5
>>> a[2]
-78.5
>>> a[2] = 'dry ice'  # Changing data types is supported as well
>>> a[2]
'dry ice'
>>> a[2] = 'larger than previously allocated storage space'
Traceback (most recent call last):
  ...
ValueError: exceeds available storage for existing str
>>> a[2]
'dry ice'
>>> len(a)
7
>>> a.index(42)
6
>>> a.count(b'howdy')
0
>>> a.count(b'HoWdY')
1
>>> a.shm.close()
>>> a.shm.unlink()
>>> del a  # Use of a ShareableList after call to unlink() is unsupported
@end example

以下範例描述了一個、兩個或多個行程如何透過提供後面的共享記憶體區塊名稱來存取同一個 @ref{1c21,,ShareableList}：

@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

以下範例示範了如果需要，可以對 @ref{1c21,,ShareableList}（和底層 @ref{1927,,SharedMemory}）物件進行 pickle 和 unpickle。請注意，它仍然是相同的共享物件。發生這種情況是因為反序列化的物件具有相同的唯一名稱，並且只是附加到具有相同名稱的現有物件（如果該物件仍然存在）：

@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 concurrent 套件,concurrent futures --- 啟動平行任務,multiprocessing shared_memory --- 對於共享記憶體的跨行程直接存取,並行執行 Concurrent Execution
@anchor{library/concurrent doc}@anchor{358d}@anchor{library/concurrent the-concurrent-package}@anchor{358e}@anchor{library/concurrent translation-repo}@anchor{358f}
@subsection @code{concurrent} 套件


此套件包含下列模組：


@itemize *

@item 
@ref{24,,concurrent.futures} -- 啟動平行任務

@item 
@ref{25,,concurrent.interpreters} -- 在同一行程中使用多個直譯器
@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 --- 啟動平行任務,concurrent interpreters --- 在同一個行程中使用多個直譯器,concurrent 套件,並行執行 Concurrent Execution
@anchor{library/concurrent futures doc}@anchor{3590}@anchor{library/concurrent futures concurrent-futures-launching-parallel-tasks}@anchor{3591}@anchor{library/concurrent futures module-concurrent futures}@anchor{24}@anchor{library/concurrent futures translation-repo}@anchor{3592}
@subsection @code{concurrent.futures} --- 啟動平行任務


@geindex module; concurrent.futures


在 3.2 版被加入.


`原始碼：'Lib/concurrent/futures/thread.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/concurrent/futures/thread.py}、Lib/concurrent/futures/process.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/concurrent/futures/process.py} 與 Lib/concurrent/futures/interpreter.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/concurrent/futures/interpreter.py}


__________________________________________________________________


@ref{24,,concurrent.futures} 模組提供了一個高階介面來非同步地 (asynchronously) 執行可呼叫物件 (callable) 。

非同步執行可以透過 @ref{941,,ThreadPoolExecutor} 或 @ref{1d2,,InterpreterPoolExecutor} 來使用執行緒 (thread) 執行，或透過 @ref{1d6,,ProcessPoolExecutor} 來使用單獨行程 (process) 執行。兩者都實作了相同的介面，該介面由抽象的 @ref{3593,,Executor} 類別定義。

@c include for modules that don't work on WASM

@ref{2006,,可用性}: not WASI.

此模組在 WebAssembly 平台上不起作用或無法使用。更多資訊請參閱 @ref{1a99,,WebAssembly 平台}。

@menu
* Executor 物件:: 
* ThreadPoolExecutor:: 
* InterpreterPoolExecutor:: 
* ProcessPoolExecutor:: 
* Future 物件:: 
* 模組函式:: 
* 例外類別:: 

@end menu

@node Executor 物件,ThreadPoolExecutor,,concurrent futures --- 啟動平行任務
@anchor{library/concurrent futures executor-objects}@anchor{3594}
@subsubsection Executor 物件


@geindex Executor (concurrent.futures 中的類別)
@anchor{library/concurrent futures concurrent futures Executor}@anchor{3593}
@deffn {類別} concurrent.futures.Executor

提供非同步執行呼叫方法的抽象類別。不應直接使用它，而應透過其具體子類別來使用。

@geindex submit() (concurrent.futures.Executor 的方法)
@anchor{library/concurrent futures concurrent futures Executor submit}@anchor{c6c}
@deffn {方法} submit (fn, /, *args, **kwargs)

為可呼叫物件 `fn' 排程來以 @code{fn(*args, **kwargs)} 的形式執行並回傳一個表示可呼叫的執行的 @ref{13b3,,Future} 物件。

@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{1dc}
@deffn {方法} map (fn, *iterables, timeout=None, chunksize=1, buffersize=None)

類似於 @ref{19f,,map(fn@comma{} *iterables)}，除了：


@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' 是非同步執行的，並且對 `fn' 的多次呼叫可以並行處理。
@end itemize

如果 @ref{14ce,,__next__()} 被呼叫，且在原先呼叫 @ref{1dc,,Executor.map()} 的 `timeout' 秒後結果仍不可用，回傳的疊代器就會引發 @ref{a2f,,TimeoutError}。`timeout' 可以是整數或浮點數。如果未指定 `timeout' 或為 @code{None}，則等待時間就不會有限制。

如果 `fn' 呼叫引發例外，則當從疊代器中檢索到它的值時將引發該例外。

使用 @ref{1d6,,ProcessPoolExecutor} 時，此方法將 `iterables' 分成許多分塊 (chunks)，並將其作為獨立的任務來提交給池 (pool)。可以透過將 `chunksize' 設定為正整數來指定這些分塊的（約略）大小。對於非常長的可疊代物件，`chunksize' 使用較大的值（與預設大小 1 相比）可以顯著提高性能。對於 @ref{941,,ThreadPoolExecutor} 和 @ref{1d2,,InterpreterPoolExecutor}，`chunksize' 無效。


在 3.5 版的變更: 新增 `chunksize' 參數。



在 3.14 版的變更: 新增 `buffersize' 參數。

@end deffn

@geindex shutdown() (concurrent.futures.Executor 的方法)
@anchor{library/concurrent futures concurrent futures Executor shutdown}@anchor{ae1}
@deffn {方法} shutdown (wait=True, *, cancel_futures=False)

向 executor 發出訊號 (signal)，表明它應該在目前未定 (pending) 的 future 完成執行時釋放它正在使用的任何資源。在關閉後呼叫 @ref{c6c,,Executor.submit()} 和 @ref{1dc,,Executor.map()} 將引發 @ref{244,,RuntimeError}。

如果 `wait' 為 @code{True} 則此方法將不會回傳，直到所有未定的 futures 完成執行並且與 executor 關聯的資源都被釋放。如果 `wait' 為 @code{False} 則此方法將立即回傳，並且當所有未定的 future 執行完畢時，與 executor 關聯的資源將被釋放。不管 `wait' 的值如何，整個 Python 程式都不會退出，直到所有未定的 futures 執行完畢。

如果 `cancel_futures' 為 @code{True}，此方法將取消 executor 尚未開始運行的所有未定 future。無論 `cancel_futures' 的值如何，任何已完成或正在運行的 future 都不會被取消。

如果 `cancel_futures' 和 `wait' 都為 @code{True}，則 executor 已開始運行的所有 future 將在此方法回傳之前完成。剩餘的 future 被取消。

如果使用 @ref{186,,with} 陳述式來將 executor 用作 @ref{1e1,,context manager}，那你就可以不用明確地呼叫此方法，這將會自己關閉 @ref{3593,,Executor}（如同呼叫 @ref{ae1,,Executor.shutdown()} 時 `wait' 被設定為 @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 版的變更: 新增 `cancel_futures'。

@end deffn
@end deffn

@node ThreadPoolExecutor,InterpreterPoolExecutor,Executor 物件,concurrent futures --- 啟動平行任務
@anchor{library/concurrent futures threadpoolexecutor}@anchor{3595}
@subsubsection ThreadPoolExecutor


@ref{941,,ThreadPoolExecutor} 是一個 @ref{3593,,Executor} 子類別，它使用執行緒池來非同步地執行呼叫。

當與 @ref{13b3,,Future} 關聯的可呼叫物件等待另一個 @ref{13b3,,Future} 的結果時，可能會發生死鎖 (deadlock)。例如：

@example
import time
def wait_on_b():
    time.sleep(5)
    print(b.result())  # b 永遠不會完成，因為它正在等待 a。
    return 5

def wait_on_a():
    time.sleep(5)
    print(a.result())  # a 永遠不會完成，因為它正在等待 b。
    return 6


executor = ThreadPoolExecutor(max_workers=2)
a = executor.submit(wait_on_b)
b = executor.submit(wait_on_a)
@end example

和：

@example
def wait_on_future():
    f = executor.submit(pow, 5, 2)
    # 這將永遠不會完成，因為只有一個工作執行緒且
    # 它正在執行這個函式。
    print(f.result())

executor = ThreadPoolExecutor(max_workers=1)
executor.submit(wait_on_future)
@end example

@geindex ThreadPoolExecutor (concurrent.futures 中的類別)
@anchor{library/concurrent futures concurrent futures ThreadPoolExecutor}@anchor{941}
@deffn {類別} concurrent.futures.ThreadPoolExecutor (max_workers=None, thread_name_prefix='@w{'}, initializer=None, initargs=())

一個 @ref{3593,,Executor} 子類別，它使用最多有 `max_workers' 個執行緒的池來非同步地執行呼叫。

所有排隊到 @code{ThreadPoolExecutor} 的執行緒都將在直譯器退出之前加入。請注意，執行此操作的退出處理程式會在任何使用 @code{atexit} 新增的退出處理程式`之前'執行。這意味著必須捕獲並處理主執行緒中的例外，以便向執行緒發出訊號來正常退出 (gracefully exit)。因此，建議不要將 @code{ThreadPoolExecutor} 用於長時間運行的任務。

`initializer' 是一個可選的可呼叫物件，在每個工作執行緒開始時呼叫； `initargs' 是傳遞給 initializer 的引數元組 (tuple)。如果 `initializer' 引發例外，所有目前未定的作業以及任何向池中提交 (submit) 更多作業的嘗試都將引發 @ref{3596,,BrokenThreadPool}。


在 3.5 版的變更: 如果 `max_workers' 為 @code{None} 或未給定，它將預設為機器上的處理器數量乘以 @code{5}，這假定了 @ref{941,,ThreadPoolExecutor} 通常用於 I/O 重疊而非 CPU 密集的作業，並且 worker 的數量應該高於 @ref{1d6,,ProcessPoolExecutor} 的 worker 數量。



在 3.6 版的變更: 新增 `thread_name_prefix' 參數以允許使用者控制由池所建立的工作執行緒 (worker thread) 的 @ref{176,,threading.Thread} 名稱，以便於除錯。



在 3.7 版的變更: 新增 `initializer' 與 `initargs' 引數。



在 3.8 版的變更: `max_workers' 的預設值改為 @code{min(32, os.cpu_count() + 4)}。此預設值為 I/O 密集任務至少保留了 5 個 worker。它最多使用 32 個 CPU 核心來執行CPU 密集任務，以釋放 GIL。並且它避免了在多核機器上隱晦地使用非常大量的資源。

ThreadPoolExecutor 現在在啟動 `max_workers' 工作執行緒之前會重用 (reuse) 空閒的工作執行緒。



在 3.13 版的變更: `max_workers' 的預設值被改為 @code{min(32, (os.process_cpu_count() or 1) + 4)}。

@end deffn

@menu
* ThreadPoolExecutor 範例:: 

@end menu

@node ThreadPoolExecutor 範例,,,ThreadPoolExecutor
@anchor{library/concurrent futures id1}@anchor{3597}@anchor{library/concurrent futures threadpoolexecutor-example}@anchor{13b4}
@subsubsection ThreadPoolExecutor 範例


@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 --- 啟動平行任務
@anchor{library/concurrent futures interpreterpoolexecutor}@anchor{3598}
@subsubsection InterpreterPoolExecutor



在 3.14 版被加入.


The @ref{1d2,,InterpreterPoolExecutor} class uses a pool of interpreters
to execute calls asynchronously.  It is a @ref{941,,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{46e,,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{cc4,,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{df,,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{d1,,socket} or
@ref{1a93,,pipe}.

@geindex InterpreterPoolExecutor (concurrent.futures 中的類別)
@anchor{library/concurrent futures concurrent futures InterpreterPoolExecutor}@anchor{1d2}
@deffn {類別} concurrent.futures.InterpreterPoolExecutor (max_workers=None, thread_name_prefix='@w{'}, initializer=None, initargs=())

A @ref{941,,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{46e,,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{3599,,ExecutionFailed}.
@end quotation
@end cartouche

Other caveats from parent @ref{941,,ThreadPoolExecutor} apply here.
@end deffn

@ref{c6c,,submit()} and @ref{1dc,,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{3599,,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
@ref{3599,,ExecutionFailed}
instance instead.

@node ProcessPoolExecutor,Future 物件,InterpreterPoolExecutor,concurrent futures --- 啟動平行任務
@anchor{library/concurrent futures processpoolexecutor}@anchor{359a}
@subsubsection ProcessPoolExecutor


@ref{1d6,,ProcessPoolExecutor} 類別是一個 @ref{3593,,Executor} 的子類別，它使用行程池來非同步地執行呼叫。@ref{1d6,,ProcessPoolExecutor} 使用了 @ref{98,,multiprocessing} 模組，這允許它避開@ref{46e,,全域直譯器鎖 (Global Interpreter Lock)}，但也意味著只能執行和回傳可被 pickle 的 (picklable) 物件。

@code{__main__} 模組必須可以被工作子行程 (worker subprocess) 引入。這意味著 @ref{1d6,,ProcessPoolExecutor} 將無法在交互式直譯器 (interactive interpreter) 中工作。

從提交給 @ref{1d6,,ProcessPoolExecutor} 的可呼叫物件中呼叫 @ref{3593,,Executor} 或 @ref{13b3,,Future} 方法將導致死鎖。

Note that the restrictions on functions and arguments needing to picklable as
per @ref{252,,multiprocessing.Process} apply when using @ref{c6c,,submit()}
and @ref{1dc,,map()} on a @ref{1d6,,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{1d6}
@deffn {類別} concurrent.futures.ProcessPoolExecutor (max_workers=None, mp_context=None, initializer=None, initargs=(), max_tasks_per_child=None)

一個 @ref{3593,,Executor} 子類別，它使用了最多有 `max_workers' 個行程的池來非同步地執行呼叫。如果 `max_workers' 為 @code{None} 或未給定，它將被預設為 @ref{4d5,,os.process_cpu_count()}。如果 `max_workers' 小於或等於 @code{0}，則會引發 @ref{2eb,,ValueError}。在 Windows 上，`max_workers' 必須小於或等於 @code{61}。如果不是，則會引發 @ref{2eb,,ValueError}。如果 `max_workers' 為 @code{None}，則預設選擇最多為 @code{61}，即便有更多處理器可用。`mp_context' 可以是 @ref{98,,multiprocessing} 情境 (context) 或 @code{None}。它將用於啟動 worker。如果 `mp_context' 為 @code{None} 或未給定，則使用預設的 @ref{98,,multiprocessing} 情境。請見 @ref{1d5,,Contexts and start methods}。

`initializer' 是一個可選的可呼叫物件，在每個工作行程 (worker process) 開始時呼叫；`initargs' 是傳遞給 initializer 的引數元組。如果 `initializer' 引發例外，所有目前未定的作業以及任何向池中提交更多作業的嘗試都將引發 @ref{359b,,BrokenProcessPool}。

`max_tasks_per_child' 是一個可選引數，它指定單個行程在退出並被新的工作行程替換之前可以執行的最大任務數。預設情況下 `max_tasks_per_child' 是 @code{None}，這意味著工作行程的生命週期將與池一樣長。當指定最大值時，在沒有 `mp_context' 參數的情況下，將預設使用 "spawn" 做為 multiprocessing 啟動方法。此功能與 "fork" 啟動方法不相容。


在 3.3 版的變更: 當其中一個工作行程突然終止時，現在會引發 @ref{359b,,BrokenProcessPool} 錯誤。在過去，此行為是未定義的 (undefined)，但對 executor 或其 future 的操作經常會發生凍結或死鎖。



在 3.7 版的變更: 新增了 `mp_context' 引數以允許使用者控制由池所建立的工作行程的 start_method。

新增 `initializer' 與 `initargs' 引數。



在 3.11 版的變更: 新增了 `max_tasks_per_child' 引數以允許使用者控制池中 worker 的生命週期。



在 3.12 版的變更: 在 POSIX 系統上，如果你的應用程式有多個執行緒並且 @ref{98,,multiprocessing} 情境使用了 @code{"fork"} 啟動方法：內部呼叫以產生 worker 的 @ref{4b0,,os.fork()} 函式可能會引發 @ref{1a3,,DeprecationWarning}。傳遞一個 `mp_context' 以配置為使用不同的啟動方法。更多說明請參閱 @ref{4b0,,os.fork()} 文件。



在 3.13 版的變更: `max_workers' uses @ref{4d5,,os.process_cpu_count()} by default, instead of
@ref{4d6,,os.cpu_count()}.



在 3.14 版的變更: The default process start method (see
@ref{1d5,,Contexts and start methods}) changed away from `fork'. If you
require the `fork' start method for @ref{1d6,,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{1da}
@deffn {方法} terminate_workers ()

Attempt to terminate all living worker processes immediately by calling
@ref{17d6,,Process.terminate} on each of them.
Internally, it will also call @ref{ae1,,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.


在 3.14 版被加入.

@end deffn

@geindex kill_workers() (concurrent.futures.ProcessPoolExecutor 的方法)
@anchor{library/concurrent futures concurrent futures ProcessPoolExecutor kill_workers}@anchor{1db}
@deffn {方法} kill_workers ()

Attempt to kill all living worker processes immediately by calling
@ref{d47,,Process.kill} on each of them.
Internally, it will also call @ref{ae1,,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.


在 3.14 版被加入.

@end deffn
@end deffn

@menu
* ProcessPoolExecutor 範例:: 

@end menu

@node ProcessPoolExecutor 範例,,,ProcessPoolExecutor
@anchor{library/concurrent futures id2}@anchor{359c}@anchor{library/concurrent futures processpoolexecutor-example}@anchor{13b5}
@subsubsection ProcessPoolExecutor 範例


@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 物件,模組函式,ProcessPoolExecutor,concurrent futures --- 啟動平行任務
@anchor{library/concurrent futures future-objects}@anchor{359d}
@subsubsection Future 物件


@ref{13b3,,Future} 類別封裝了可呼叫物件的非同步執行。@ref{13b3,,Future} 實例由 @ref{c6c,,Executor.submit()} 建立。

@geindex Future (concurrent.futures 中的類別)
@anchor{library/concurrent futures concurrent futures Future}@anchor{13b3}
@deffn {類別} concurrent.futures.Future

封裝可呼叫物件的非同步執行。@ref{13b3,,Future} 實例由 @ref{c6c,,Executor.submit()} 建立，且除測試外不應直接建立。

@geindex cancel() (concurrent.futures.Future 的方法)
@anchor{library/concurrent futures concurrent futures Future cancel}@anchor{359e}
@deffn {方法} cancel ()

嘗試取消呼叫。如果呼叫目前正在執行或已完成運行且無法取消，則該方法將回傳 @code{False}，否則呼叫將被取消並且該方法將回傳 @code{True}。
@end deffn

@geindex cancelled() (concurrent.futures.Future 的方法)
@anchor{library/concurrent futures concurrent futures Future cancelled}@anchor{359f}
@deffn {方法} cancelled ()

如果該呼叫成功被取消，則回傳 @code{True}。
@end deffn

@geindex running() (concurrent.futures.Future 的方法)
@anchor{library/concurrent futures concurrent futures Future running}@anchor{35a0}
@deffn {方法} running ()

如果呼叫正在執行且無法取消，則回傳 @code{True}。
@end deffn

@geindex done() (concurrent.futures.Future 的方法)
@anchor{library/concurrent futures concurrent futures Future done}@anchor{35a1}
@deffn {方法} done ()

如果呼叫成功被取消或結束運行，則回傳 @code{True}。
@end deffn

@geindex result() (concurrent.futures.Future 的方法)
@anchor{library/concurrent futures concurrent futures Future result}@anchor{35a2}
@deffn {方法} result (timeout=None)

回傳該呼叫回傳的值。如果呼叫尚未完成，則此方法將等待至多 `timeout' 秒。如果呼叫在 `timeout' 秒內未完成，則會引發 @ref{a2f,,TimeoutError}。`timeout' 可以是整數或浮點數。如果未指定 `timeout' 或為 @code{None}，則等待時間就不會有限制。

如果 future 在完成之前被取消，那麼 @ref{bc5,,CancelledError} 將被引發。

如果該呼叫引發了例外，此方法將引發相同的例外。
@end deffn

@geindex exception() (concurrent.futures.Future 的方法)
@anchor{library/concurrent futures concurrent futures Future exception}@anchor{35a3}
@deffn {方法} exception (timeout=None)

回傳該呼叫引發的例外。如果呼叫尚未完成，則此方法將等待至多 `timeout' 秒。如果呼叫在 `timeout' 秒內未完成，則會引發 @ref{a2f,,TimeoutError}。 `timeout' 可以是整數或浮點數。如果未指定 `timeout' 或為 @code{None}，則等待時間就不會有限制。

如果 future 在完成之前被取消，那麼 @ref{bc5,,CancelledError} 將被引發。

如果呼叫在沒有引發的情況下完成，則回傳 @code{None}。
@end deffn

@geindex add_done_callback() (concurrent.futures.Future 的方法)
@anchor{library/concurrent futures concurrent futures Future add_done_callback}@anchor{35a4}
@deffn {方法} add_done_callback (fn)

將可呼叫的 `fn' 附加到 future 上。當 future 被取消或完成運行時，`fn' 將被以 future 作為其唯一引數來呼叫。

新增的可呼叫物件按新增順序呼叫，並且始終在屬於新增它們的行程的執行緒中呼叫。如果可呼叫物件引發 @ref{bc4,,Exception} 子類別，它將被記錄 (log) 並忽略。如果可呼叫物件引發 @ref{7d0,,BaseException} 子類別，該行為未定義。

如果 future 已經完成或被取消，`fn' 將立即被呼叫。
@end deffn

以下 @ref{13b3,,Future} 方法旨在用於單元測試和 @ref{3593,,Executor} 實作。

@geindex set_running_or_notify_cancel() (concurrent.futures.Future 的方法)
@anchor{library/concurrent futures concurrent futures Future set_running_or_notify_cancel}@anchor{35a5}
@deffn {方法} set_running_or_notify_cancel ()

此方法只能在與 @ref{13b3,,Future} 關聯的工作被執行之前於 @ref{3593,,Executor} 實作中呼叫，或者在單元測試中呼叫。

如果該方法回傳 @code{False} 則 @ref{13b3,,Future} 已被取消，即 @ref{359e,,Future.cancel()} 被呼叫並回傳 @code{True}。任何等待 @ref{13b3,,Future} 完成的執行緒（即透過 @ref{191a,,as_completed()} 或 @ref{1b19,,wait()}）將被喚醒。

如果該方法回傳 @code{True} 則代表 @ref{13b3,,Future} 未被取消並已進入運行狀態，意即呼叫 @ref{35a0,,Future.running()} 將回傳 @code{True}。

此方法只能呼叫一次，且不能在呼叫 @ref{35a6,,Future.set_result()} 或 @ref{35a7,,Future.set_exception()} 之後呼叫。
@end deffn

@geindex set_result() (concurrent.futures.Future 的方法)
@anchor{library/concurrent futures concurrent futures Future set_result}@anchor{35a6}
@deffn {方法} set_result (result)

將與 @ref{13b3,,Future} 關聯的工作結果設定為 `result'。

此方法只能在 @ref{3593,,Executor} 實作中和單元測試中使用。


在 3.8 版的變更: 如果 @ref{13b3,,Future} 已經完成，此方法會引發 @ref{18b8,,concurrent.futures.InvalidStateError}。

@end deffn

@geindex set_exception() (concurrent.futures.Future 的方法)
@anchor{library/concurrent futures concurrent futures Future set_exception}@anchor{35a7}
@deffn {方法} set_exception (exception)

將與 @ref{13b3,,Future} 關聯的工作結果設定為 @ref{bc4,,Exception} `exception'。

此方法只能在 @ref{3593,,Executor} 實作中和單元測試中使用。


在 3.8 版的變更: 如果 @ref{13b3,,Future} 已經完成，此方法會引發 @ref{18b8,,concurrent.futures.InvalidStateError}。

@end deffn
@end deffn

@node 模組函式,例外類別,Future 物件,concurrent futures --- 啟動平行任務
@anchor{library/concurrent futures module-functions}@anchor{35a8}
@subsubsection 模組函式


@geindex wait() (於 concurrent.futures 模組中)
@anchor{library/concurrent futures concurrent futures wait}@anchor{1b19}
@deffn {函式} concurrent.futures.wait (fs, timeout=None, return_when=ALL_COMPLETED)

等待 `fs' 給定的 @ref{13b3,,Future} 實例（可能由不同的 @ref{3593,,Executor} 實例建立）完成。提供給 `fs' 的重複 future 將被刪除，並且只會回傳一次。回傳一個集合的附名二元組 (named 2-tuple of sets)。第一組名為 @code{done}，包含在等待完成之前完成的 future（已完成或被取消的 future）。第二組名為 @code{not_done}，包含未完成的 future（未定或運行中的 future）。

`timeout' 可用於控制回傳前等待的最大秒數。`timeout' 可以是整數或浮點數。如果未指定 `timeout' 或為 @code{None}，則等待時間就沒有限制。

`return_when' 表示此函式應回傳的時間。它必須是以下常數之一：


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

常數

@tab

描述

@item

@geindex FIRST_COMPLETED (於 concurrent.futures 模組中)
@anchor{library/concurrent futures concurrent futures FIRST_COMPLETED}@anchor{35a9}
@deffn {資料} concurrent.futures.FIRST_COMPLETED
@end deffn

@tab

當任何 future 完成或被取消時，該函式就會回傳。

@item

@geindex FIRST_EXCEPTION (於 concurrent.futures 模組中)
@anchor{library/concurrent futures concurrent futures FIRST_EXCEPTION}@anchor{35aa}
@deffn {資料} concurrent.futures.FIRST_EXCEPTION
@end deffn

@tab

該函式會在任何 future 透過引發例外而完結時回傳。如果 future 沒有引發例外，那麼它等同於 @ref{35ab,,ALL_COMPLETED}。

@item

@geindex ALL_COMPLETED (於 concurrent.futures 模組中)
@anchor{library/concurrent futures concurrent futures ALL_COMPLETED}@anchor{35ab}
@deffn {資料} concurrent.futures.ALL_COMPLETED
@end deffn

@tab

當所有 future 都完成或被取消時，該函式才會回傳。

@end multitable

@end deffn

@geindex as_completed() (於 concurrent.futures 模組中)
@anchor{library/concurrent futures concurrent futures as_completed}@anchor{191a}
@deffn {函式} concurrent.futures.as_completed (fs, timeout=None)

回傳由 `fs' 給定的 @ref{13b3,,Future} 實例（可能由不同的 @ref{3593,,Executor} 實例建立）的疊代器，它在完成時產生 future（已完成或被取消的 future）。`fs' 給定的任何重複的 future 將只被回傳一次。呼叫 @ref{191a,,as_completed()} 之前完成的任何 future 將首先產生。如果 @ref{14ce,,__next__()} 被呼叫，並且在原先呼叫 @ref{191a,,as_completed()} 的 `timeout' 秒後結果仍不可用，則回傳的疊代器會引發 @ref{a2f,,TimeoutError}。`timeout' 可以是整數或浮點數。如果未指定 `timeout' 或為 @code{None}，則等待時間就沒有限制。
@end deffn


@subsubheading 也參考



@table @asis

@geindex Python Enhancement Proposals; PEP 3148

@item PEP 3148@footnote{https://peps.python.org/pep-3148/} -- futures - 非同步地執行運算

描述此功能並提出被包含於 Python 標準函式庫中的提案。
@end table


@node 例外類別,,模組函式,concurrent futures --- 啟動平行任務
@anchor{library/concurrent futures exception-classes}@anchor{35ac}
@subsubsection 例外類別


@geindex CancelledError
@anchor{library/concurrent futures concurrent futures CancelledError}@anchor{bc5}
@deffn {例外} concurrent.futures.CancelledError

當 future 被取消時引發。
@end deffn

@geindex TimeoutError
@anchor{library/concurrent futures concurrent futures TimeoutError}@anchor{35ad}
@deffn {例外} concurrent.futures.TimeoutError

@ref{a2f,,TimeoutError} 的棄用別名，在 future 操作超過給定超時 (timeout) 時引發。


在 3.11 版的變更: 這個類別是 @ref{a2f,,TimeoutError} 的別名。

@end deffn

@geindex BrokenExecutor
@anchor{library/concurrent futures concurrent futures BrokenExecutor}@anchor{35ae}
@deffn {例外} concurrent.futures.BrokenExecutor

衍生自 @ref{244,,RuntimeError}，當執行器因某種原因損壞時會引發此例外類別，並且不能用於提交或執行新任務。


在 3.7 版被加入.

@end deffn

@geindex InvalidStateError
@anchor{library/concurrent futures concurrent futures InvalidStateError}@anchor{18b8}
@deffn {例外} concurrent.futures.InvalidStateError

目前狀態下不允許的 future 操作被執行時而引發。


在 3.8 版被加入.

@end deffn

@geindex BrokenThreadPool
@anchor{library/concurrent futures concurrent futures thread BrokenThreadPool}@anchor{3596}
@deffn {例外} concurrent.futures.thread.BrokenThreadPool

衍生自 @ref{35ae,,BrokenExecutor}，當 @ref{941,,ThreadPoolExecutor} 的其中一個 worker 初始化失敗時會引發此例外類別。


在 3.7 版被加入.

@end deffn

@geindex BrokenInterpreterPool
@anchor{library/concurrent futures concurrent futures interpreter BrokenInterpreterPool}@anchor{35af}
@deffn {例外} concurrent.futures.interpreter.BrokenInterpreterPool

衍生自 @ref{3596,,BrokenThreadPool}，當 @ref{1d2,,InterpreterPoolExecutor} 的其中一個 worker 初始化失敗時會引發此例外類別。


在 3.14 版被加入.

@end deffn

@geindex ExecutionFailed
@anchor{library/concurrent futures concurrent futures interpreter ExecutionFailed}@anchor{3599}
@deffn {例外} concurrent.futures.interpreter.ExecutionFailed

Raised from @ref{1d2,,InterpreterPoolExecutor} when
the given initializer fails or from
@ref{c6c,,submit()} when there's an uncaught
exception from the submitted task.


在 3.14 版被加入.

@end deffn

@geindex BrokenProcessPool
@anchor{library/concurrent futures concurrent futures process BrokenProcessPool}@anchor{359b}
@deffn {例外} concurrent.futures.process.BrokenProcessPool

衍生自 @ref{35ae,,BrokenExecutor}（以前為 @ref{244,,RuntimeError}），當 @ref{1d6,,ProcessPoolExecutor} 的其中一個 worker 以不乾淨的方式終止時將引發此例外類別（例如它是從外面被 kill 掉的）。


在 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 --- 在同一個行程中使用多個直譯器,subprocess --- 子行程管理,concurrent futures --- 啟動平行任務,並行執行 Concurrent Execution
@anchor{library/concurrent interpreters doc}@anchor{35b0}@anchor{library/concurrent interpreters concurrent-interpreters-multiple-interpreters-in-the-same-process}@anchor{35b1}@anchor{library/concurrent interpreters module-concurrent interpreters}@anchor{25}@anchor{library/concurrent interpreters translation-repo}@anchor{35b2}
@subsection @code{concurrent.interpreters} --- 在同一個行程中使用多個直譯器


@geindex module; concurrent.interpreters


在 3.14 版被加入.


`原始碼：'Lib/concurrent/interpreters@footnote{https://github.com/python/cpython/tree/3.14/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{f3,,threads}  See @ref{35b3,,below}@anchor{library/concurrent interpreters interp-concurrency}@anchor{35b3}


@subsubheading 也參考



@table @asis

@item @ref{1d2,,InterpreterPoolExecutor}

@quotation

combines threads with interpreters in a familiar interface.
@end quotation

@c XXX Add references to the upcoming HOWTO docs in the seealso block.

@item @ref{166,,隔離擴充模組}

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{2006,,可用性}: not WASI.

This module does not work or is not available on WebAssembly. See
@ref{1a99,,WebAssembly 平台} for more information.

@menu
* Key details:: 
* Introduction: Introduction<3>. 
* Reference: Reference<4>. 
* 基本用法: 基本用法<3>. 

@end menu

@node Key details,Introduction<3>,,concurrent interpreters --- 在同一個行程中使用多個直譯器
@anchor{library/concurrent interpreters key-details}@anchor{35b4}
@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{35b5,,isolated}@anchor{library/concurrent interpreters interp-isolation}@anchor{35b5}, 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<3>,Reference<4>,Key details,concurrent interpreters --- 在同一個行程中使用多個直譯器
@anchor{library/concurrent interpreters interpreters-intro}@anchor{35b6}@anchor{library/concurrent interpreters introduction}@anchor{35b7}
@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{35b5,,isolation}
was relatively incomplete until version 3.12.

@menu
* Multiple Interpreters and Isolation:: 
* Running in an Interpreter:: 
* Concurrency and Parallelism:: 
* 直譯器之間的溝通:: 
* "Sharing" Objects:: 

@end menu

@node Multiple Interpreters and Isolation,Running in an Interpreter,,Introduction<3>
@anchor{library/concurrent interpreters multiple-interpreters-and-isolation}@anchor{35b8}
@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<3>
@anchor{library/concurrent interpreters running-in-an-interpreter}@anchor{35b9}
@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{35ba,,a helper}@anchor{library/concurrent interpreters interp-call-in-thread}@anchor{35ba} for that though.
There is another dedicated helper for calling the builtin
@ref{49d,,exec()} in an interpreter.

When @ref{49d,,exec()} (or @ref{49e,,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,直譯器之間的溝通,Running in an Interpreter,Introduction<3>
@anchor{library/concurrent interpreters concurrency-and-parallelism}@anchor{35bb}
@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{164,,GIL}, which means combining threads with
multiple interpreters enables full multi-core parallelism.
(This has been the case since Python 3.12.)

@node 直譯器之間的溝通,"Sharing" Objects,Concurrency and Parallelism,Introduction<3>
@anchor{library/concurrent interpreters communication-between-interpreters}@anchor{35bc}
@subsubsection 直譯器之間的溝通


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{158c,,queue.Queue} implementation, available through
@ref{35bd,,create_queue()}.

@node "Sharing" Objects,,直譯器之間的溝通,Introduction<3>
@anchor{library/concurrent interpreters interp-object-sharing}@anchor{35be}@anchor{library/concurrent interpreters sharing-objects}@anchor{35bf}
@subsubsection "Sharing" Objects


Any data actually shared between interpreters loses the thread-safety
provided by the @ref{164,,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{87e,,None}

@item 
@ref{3c1,,bool}（@ref{e02,,True} 和 @ref{d23,,False}）

@item 
@ref{192,,bytes}

@item 
@ref{169,,str}

@item 
@ref{19b,,int}

@item 
@ref{196,,float}

@item 
@ref{60c,,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{165,,memoryview}

@item 
@ref{35c0,,Queue}
@end itemize

@node Reference<4>,基本用法<3>,Introduction<3>,concurrent interpreters --- 在同一個行程中使用多個直譯器
@anchor{library/concurrent interpreters reference}@anchor{35c1}
@subsubsection Reference


This module defines the following functions:

@geindex list_all() (於 concurrent.interpreters 模組中)
@anchor{library/concurrent interpreters concurrent interpreters list_all}@anchor{35c2}
@deffn {函式} concurrent.interpreters.list_all ()

Return a @ref{24d,,list} of @ref{35c3,,Interpreter} objects,
one for each existing interpreter.
@end deffn

@geindex get_current() (於 concurrent.interpreters 模組中)
@anchor{library/concurrent interpreters concurrent interpreters get_current}@anchor{35c4}
@deffn {函式} concurrent.interpreters.get_current ()

Return an @ref{35c3,,Interpreter} object for the currently running
interpreter.
@end deffn

@geindex get_main() (於 concurrent.interpreters 模組中)
@anchor{library/concurrent interpreters concurrent interpreters get_main}@anchor{35c5}
@deffn {函式} concurrent.interpreters.get_main ()

Return an @ref{35c3,,Interpreter} object for the main interpreter.
This is the interpreter the runtime created to run the @ref{48c,,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{1751}
@deffn {函式} concurrent.interpreters.create ()

Initialize a new (idle) Python interpreter
and return a @ref{35c3,,Interpreter} object for it.
@end deffn

@geindex create_queue() (於 concurrent.interpreters 模組中)
@anchor{library/concurrent interpreters concurrent interpreters create_queue}@anchor{35bd}
@deffn {函式} concurrent.interpreters.create_queue ()

Initialize a new cross-interpreter queue and return a @ref{35c0,,Queue}
object for it.
@end deffn

@menu
* Interpreter objects:: 
* 例外: 例外<11>. 
* 在直譯器之間溝通:: 

@end menu

@node Interpreter objects,例外<11>,,Reference<4>
@anchor{library/concurrent interpreters interpreter-objects}@anchor{35c6}
@subsubsection Interpreter objects


@geindex Interpreter (concurrent.interpreters 中的類別)
@anchor{library/concurrent interpreters concurrent interpreters Interpreter}@anchor{35c3}
@deffn {類別} concurrent.interpreters.Interpreter (id)

A single interpreter in the current process.

Generally, @ref{35c3,,Interpreter} shouldn't be called directly.
Instead, use @ref{1751,,create()} or one of the other module functions.

@geindex id (concurrent.interpreters.Interpreter 的屬性)
@anchor{library/concurrent interpreters concurrent interpreters Interpreter id}@anchor{35c7}
@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{35c8}
@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{35c9}
@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{35ca}
@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{35cb}
@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{35be,,"Sharing" Objects}.
@end deffn

@geindex exec() (concurrent.interpreters.Interpreter 的方法)
@anchor{library/concurrent interpreters concurrent interpreters Interpreter exec}@anchor{35cc}
@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{35cd}
@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{35ce}
@deffn {方法} call_in_thread (callable, /, *args, **kwargs)

Run the given function in the interpreter (in a new thread).
@end deffn
@end deffn

@node 例外<11>,在直譯器之間溝通,Interpreter objects,Reference<4>
@anchor{library/concurrent interpreters exceptions}@anchor{35cf}
@subsubsection 例外


@geindex InterpreterError
@anchor{library/concurrent interpreters concurrent interpreters InterpreterError}@anchor{35d0}
@deffn {例外} concurrent.interpreters.InterpreterError

This exception, a subclass of @ref{bc4,,Exception}, is raised when
an interpreter-related error happens.
@end deffn

@geindex InterpreterNotFoundError
@anchor{library/concurrent interpreters concurrent interpreters InterpreterNotFoundError}@anchor{35d1}
@deffn {例外} concurrent.interpreters.InterpreterNotFoundError

This exception, a subclass of @ref{35d0,,InterpreterError}, is raised when
the targeted interpreter no longer exists.
@end deffn

@geindex ExecutionFailed
@anchor{library/concurrent interpreters concurrent interpreters ExecutionFailed}@anchor{35d2}
@deffn {例外} concurrent.interpreters.ExecutionFailed

This exception, a subclass of @ref{35d0,,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{35d3}
@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{35d4}
@deffn {例外} concurrent.interpreters.NotShareableError

This exception, a subclass of @ref{198,,TypeError}, is raised when
an object cannot be sent to another interpreter.
@end deffn

@node 在直譯器之間溝通,,例外<11>,Reference<4>
@anchor{library/concurrent interpreters communicating-between-interpreters}@anchor{35d5}
@subsubsection 在直譯器之間溝通


@geindex Queue (concurrent.interpreters 中的類別)
@anchor{library/concurrent interpreters concurrent interpreters Queue}@anchor{35c0}
@deffn {類別} concurrent.interpreters.Queue (id)

A wrapper around a low-level, cross-interpreter queue, which
implements the @ref{158c,,queue.Queue} interface.  The underlying queue
can only be created through @ref{35bd,,create_queue()}.

Some objects are actually shared and some are copied efficiently,
but most are copied via @ref{ab,,pickle}.  See @ref{35be,,"Sharing" Objects}.

@geindex id (concurrent.interpreters.Queue 的屬性)
@anchor{library/concurrent interpreters concurrent interpreters Queue id}@anchor{35d6}
@deffn {屬性} id

(read-only)

The queue's ID.
@end deffn
@end deffn

@geindex QueueEmptyError
@anchor{library/concurrent interpreters concurrent interpreters QueueEmptyError}@anchor{35d7}
@deffn {例外} concurrent.interpreters.QueueEmptyError

This exception, a subclass of @ref{3520,,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{35d8}
@deffn {例外} concurrent.interpreters.QueueFullError

This exception, a subclass of @ref{3521,,queue.Full}, is raised from
@code{Queue.put()} and @code{Queue.put_nowait()} when the queue
is full.
@end deffn

@node 基本用法<3>,,Reference<4>,concurrent interpreters --- 在同一個行程中使用多個直譯器
@anchor{library/concurrent interpreters basic-usage}@anchor{35d9}
@subsubsection 基本用法


建立一個直譯器並在其中運行程式碼：

@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 --- 子行程管理,sched --- 事件排程器,concurrent interpreters --- 在同一個行程中使用多個直譯器,並行執行 Concurrent Execution
@anchor{library/subprocess doc}@anchor{35da}@anchor{library/subprocess module-subprocess}@anchor{dc}@anchor{library/subprocess subprocess-subprocess-management}@anchor{35db}@anchor{library/subprocess translation-repo}@anchor{35dc}
@subsection @code{subprocess} --- 子行程管理


@geindex module; subprocess

`原始碼：'Lib/subprocess.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/subprocess.py}


__________________________________________________________________


The @ref{dc,,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 @ref{dc,,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/} -- 提議 subprocess 模組的 PEP


@c include for modules that don't work on WASM or mobile platforms

@ref{2006,,可用性}: not Android, not iOS, not WASI.

此模組在@ref{2120,,行動平台}或@ref{1a99,,WebAssembly 平台}上不支援。

@menu
* Using the subprocess Module:: 
* 安全性注意事項:: 
* Popen Objects:: 
* Windows Popen Helpers:: 
* Older high-level API:: 
* Replacing Older Functions with the subprocess Module:: 
* Legacy Shell Invocation Functions:: 
* 註解:: 

@end menu

@node Using the subprocess Module,安全性注意事項,,subprocess --- 子行程管理
@anchor{library/subprocess using-the-subprocess-module}@anchor{35dd}
@subsubsection Using the @code{subprocess} Module


The recommended approach to invoking subprocesses is to use the @ref{d79,,run()}
function for all use cases it can handle. For more advanced use cases, the
underlying @ref{4b2,,Popen} interface can be used directly.

@geindex run() (於 subprocess 模組中)
@anchor{library/subprocess subprocess run}@anchor{d79}
@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{106e,,CompletedProcess} instance.

The arguments shown above are merely the most common ones, described below
in @ref{35de,,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{4b2,,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{4b2,,Popen} object is automatically created with
`stdout' and `stderr' both set to @ref{d7a,,PIPE}.
The `stdout' and `stderr' arguments may not be supplied at the same time as `capture_output'.
If you wish to capture and combine both streams into one,
set `stdout' to @ref{d7a,,PIPE}
and `stderr' to @ref{35df,,STDOUT},
instead of using `capture_output'.

A `timeout' may be specified in seconds, it is internally passed on to
@ref{35e0,,Popen.communicate()}. If the timeout expires, the child process will be
killed and waited for. The @ref{17cf,,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{35e0,,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{4b2,,Popen} object is automatically created with
`stdin' set to @ref{d7a,,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{1525,,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{9b7,,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{4b2,,Popen}. This mapping can be str to str on any platform
or bytes to bytes on POSIX platforms much like @ref{259,,os.environ} or
@ref{25a,,os.environb}.

範例：

@example
>>> subprocess.run(["ls", "-l"])  # 不捕捉輸出
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


在 3.5 版被加入.



在 3.6 版的變更: 新增 `encoding' 與 `errors' 參數。



在 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{106e}
@deffn {類別} subprocess.CompletedProcess

The return value from @ref{d79,,run()}, representing a process that has finished.

@geindex args (subprocess.CompletedProcess 的屬性)
@anchor{library/subprocess subprocess CompletedProcess args}@anchor{35e1}
@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{35e2}
@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{35e3}
@deffn {屬性} stdout

Captured stdout from the child process. A bytes sequence, or a string if
@ref{d79,,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{35e4,,stderr} will be
@code{None}.
@end deffn

@geindex stderr (subprocess.CompletedProcess 的屬性)
@anchor{library/subprocess subprocess CompletedProcess stderr}@anchor{35e4}
@deffn {屬性} stderr

Captured stderr from the child process. A bytes sequence, or a string if
@ref{d79,,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{35e5}
@deffn {方法} check_returncode ()

If @ref{35e2,,returncode} is non-zero, raise a @ref{1525,,CalledProcessError}.
@end deffn


在 3.5 版被加入.

@end deffn

@geindex DEVNULL (於 subprocess 模組中)
@anchor{library/subprocess subprocess DEVNULL}@anchor{134f}
@deffn {資料} subprocess.DEVNULL

Special value that can be used as the `stdin', `stdout' or `stderr' argument
to @ref{4b2,,Popen} and indicates that the special file @ref{1cdc,,os.devnull}
will be used.


在 3.3 版被加入.

@end deffn

@geindex PIPE (於 subprocess 模組中)
@anchor{library/subprocess subprocess PIPE}@anchor{d7a}
@deffn {資料} subprocess.PIPE

Special value that can be used as the `stdin', `stdout' or `stderr' argument
to @ref{4b2,,Popen} and indicates that a pipe to the standard stream should be
opened.  Most useful with @ref{35e0,,Popen.communicate()}.
@end deffn

@geindex STDOUT (於 subprocess 模組中)
@anchor{library/subprocess subprocess STDOUT}@anchor{35df}
@deffn {資料} subprocess.STDOUT

Special value that can be used as the `stderr' argument to @ref{4b2,,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{35e6}
@deffn {例外} subprocess.SubprocessError

Base class for all other exceptions from this module.


在 3.3 版被加入.

@end deffn

@geindex TimeoutExpired
@anchor{library/subprocess subprocess TimeoutExpired}@anchor{17cf}
@deffn {例外} subprocess.TimeoutExpired

Subclass of @ref{35e6,,SubprocessError}, raised when a timeout expires
while waiting for a child process.

@geindex cmd (subprocess.TimeoutExpired 的屬性)
@anchor{library/subprocess subprocess TimeoutExpired cmd}@anchor{35e7}
@deffn {屬性} cmd

Command that was used to spawn the child process.
@end deffn

@geindex timeout (subprocess.TimeoutExpired 的屬性)
@anchor{library/subprocess subprocess TimeoutExpired timeout}@anchor{35e8}
@deffn {屬性} timeout

Timeout in seconds.
@end deffn

@geindex output (subprocess.TimeoutExpired 的屬性)
@anchor{library/subprocess subprocess TimeoutExpired output}@anchor{35e9}
@deffn {屬性} output

Output of the child process if it was captured by @ref{d79,,run()} or
@ref{11bd,,check_output()}.  Otherwise, @code{None}.  This is always
@ref{192,,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{35ea}
@deffn {屬性} stdout

Alias for output, for symmetry with @ref{35eb,,stderr}.
@end deffn

@geindex stderr (subprocess.TimeoutExpired 的屬性)
@anchor{library/subprocess subprocess TimeoutExpired stderr}@anchor{35eb}
@deffn {屬性} stderr

Stderr output of the child process if it was captured by @ref{d79,,run()}.
Otherwise, @code{None}.  This is always @ref{192,,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


在 3.3 版被加入.



在 3.5 版的變更: `stdout' and `stderr' attributes added

@end deffn

@geindex CalledProcessError
@anchor{library/subprocess subprocess CalledProcessError}@anchor{1525}
@deffn {例外} subprocess.CalledProcessError

Subclass of @ref{35e6,,SubprocessError}, raised when a process run by
@ref{35ec,,check_call()}, @ref{11bd,,check_output()}, or @ref{d79,,run()} (with @code{check=True})
returns a non-zero exit status.

@geindex returncode (subprocess.CalledProcessError 的屬性)
@anchor{library/subprocess subprocess CalledProcessError returncode}@anchor{35ed}
@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{35ee}
@deffn {屬性} cmd

Command that was used to spawn the child process.
@end deffn

@geindex output (subprocess.CalledProcessError 的屬性)
@anchor{library/subprocess subprocess CalledProcessError output}@anchor{35ef}
@deffn {屬性} output

Output of the child process if it was captured by @ref{d79,,run()} or
@ref{11bd,,check_output()}.  Otherwise, @code{None}.
@end deffn

@geindex stdout (subprocess.CalledProcessError 的屬性)
@anchor{library/subprocess subprocess CalledProcessError stdout}@anchor{35f0}
@deffn {屬性} stdout

Alias for output, for symmetry with @ref{35f1,,stderr}.
@end deffn

@geindex stderr (subprocess.CalledProcessError 的屬性)
@anchor{library/subprocess subprocess CalledProcessError stderr}@anchor{35f1}
@deffn {屬性} stderr

Stderr output of the child process if it was captured by @ref{d79,,run()}.
Otherwise, @code{None}.
@end deffn


在 3.5 版的變更: `stdout' and `stderr' attributes added

@end deffn

@menu
* Frequently Used Arguments:: 
* Popen Constructor:: 
* 例外: 例外<12>. 

@end menu

@node Frequently Used Arguments,Popen Constructor,,Using the subprocess Module
@anchor{library/subprocess frequently-used-arguments}@anchor{35de}@anchor{library/subprocess id1}@anchor{35f2}
@subsubsection Frequently Used Arguments


To support a wide variety of use cases, the @ref{4b2,,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{e02,,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{d7a,,PIPE}, @ref{134f,,DEVNULL}, an existing file descriptor (a
positive integer), and an existing @ref{13c4,,file object} with a valid file
descriptor.  With the default settings of @code{None}, no redirection will
occur.  @ref{d7a,,PIPE} indicates that a new pipe to the child should be
created.  @ref{134f,,DEVNULL} indicates that the special file @ref{1cdc,,os.devnull}
will be used.  Additionally, `stderr' can be @ref{35df,,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 模組

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{9b7,,io.TextIOWrapper}.

For `stdin', line ending characters @code{'\n'} in the input will be converted
to the default line separator @ref{2487,,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{9b7,,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 版的變更: 新增 `encoding' 與 `errors' 參數。



在 3.7 版的變更: Added the `text' parameter as an alias for `universal_newlines'.


@cartouche
@quotation 備註 
The newlines attribute of the file objects @ref{35f3,,Popen.stdin},
@ref{35f4,,Popen.stdout} and @ref{35f5,,Popen.stderr} are not updated by
the @ref{35e0,,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{68,,glob},
@ref{60,,fnmatch}, @ref{6c9,,os.walk()}, @ref{15d0,,os.path.expandvars()},
@ref{c00,,os.path.expanduser()}, and @ref{ca,,shutil}).


在 3.3 版的變更: When `universal_newlines' is @code{True}, the class uses the encoding
@ref{755,,locale.getpreferredencoding(False)}
instead of @code{locale.getpreferredencoding()}.  See the
@ref{9b7,,io.TextIOWrapper} class for more information on this change.


@cartouche
@quotation 備註 
Read the @ref{35f6,,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{4b2,,Popen} constructor documentation.

@node Popen Constructor,例外<12>,Frequently Used Arguments,Using the subprocess Module
@anchor{library/subprocess popen-constructor}@anchor{35f7}
@subsubsection Popen Constructor


The underlying process creation and management in this module is handled by
the @ref{4b2,,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{4b2}
@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{2f6c,,os.execvpe()}-like behavior to execute the child program.  On Windows,
the class uses the Windows @code{CreateProcess()} function.  The arguments to
@ref{4b2,,Popen} are as follows.

`args' should be a sequence of program arguments or else a single string
or @ref{59b,,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{6d4,,shutil.which()}. On all platforms, passing @ref{3eb,,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{2f6c,,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{757,,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) # 成功！
@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{35f8,,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{59b,,path-like object} if `shell' is
@code{False} and a sequence containing path-like objects on POSIX.



在 3.8 版的變更: `args' parameter accepts a @ref{59b,,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, @ref{4b2,,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{35f6,,Security Considerations} section before using @code{shell=True}.
@end quotation
@end cartouche

`bufsize' will be supplied as the corresponding argument to the
@ref{315,,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{59b,,path-like object} on POSIX.



在 3.8 版的變更: `executable' parameter accepts a bytes and @ref{59b,,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{d7a,,PIPE}, @ref{134f,,DEVNULL}, an existing file descriptor (a
positive integer), and an existing @ref{13c4,,file object} with a valid file
descriptor.  With the default settings of @code{None}, no redirection will
occur.  @ref{d7a,,PIPE} indicates that a new pipe to the child should be
created.  @ref{134f,,DEVNULL} indicates that the special file @ref{1cdc,,os.devnull}
will be used.  Additionally, `stderr' can be @ref{35df,,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{1c83,,os.setsid()} or @ref{2ed1,,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{244,,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{10f7,,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{e03,,STARTUPINFO.lpAttributeList}, or by standard handle redirection.


在 3.2 版的變更: The default for `close_fds' was changed from @ref{d23,,False} to
what is described above.



在 3.7 版的變更: On Windows the default for `close_fds' was changed from @ref{d23,,False} to
@ref{e02,,True} when redirecting the standard handles. It's now possible to
set `close_fds' to @ref{e02,,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{e02,,True}.  (POSIX only)


在 3.2 版的變更: 新增 `pass_fds' 參數。


If `cwd' is not @code{None}, the function changes the working directory to
`cwd' before executing the child.  `cwd' can be a string, bytes or
@ref{59b,,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{59b,,path-like object} on POSIX.



在 3.7 版的變更: `cwd' parameter accepts a @ref{59b,,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'。


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{2006,,可用性}: POSIX


在 3.2 版的變更: 新增 `start_new_session'。


If `process_group' is a non-negative integer, the @code{setpgid(0, value)} system call will
be made in the child process prior to the execution of the subprocess.

@ref{2006,,可用性}: POSIX


在 3.11 版的變更: 新增 `process_group'。


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{35f9,,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{2006,,可用性}: POSIX


在 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{35f9,,grp.getgrnam()} and the values in @code{gr_gid} will be used.
Integer values will be passed verbatim. (POSIX only)

@ref{2006,,可用性}: POSIX


在 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{35fa,,pwd.getpwnam()} and
the value in @code{pw_uid} will be used. If the value is an integer, it will
be passed verbatim. (POSIX only)

@ref{2006,,可用性}: POSIX


在 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{2006,,可用性}: POSIX


在 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{259,,os.environ} or @ref{25a,,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{35de,,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.


在 3.6 版被加入: 新增 `encoding' 與 `errors'。



在 3.7 版被加入: `text' was added as a more readable alias for `universal_newlines'.


If given, `startupinfo' will be a @ref{35fb,,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{35fc,,CREATE_NEW_CONSOLE}

@item 
@ref{35fd,,CREATE_NEW_PROCESS_GROUP}

@item 
@ref{35fe,,ABOVE_NORMAL_PRIORITY_CLASS}

@item 
@ref{35ff,,BELOW_NORMAL_PRIORITY_CLASS}

@item 
@ref{3600,,HIGH_PRIORITY_CLASS}

@item 
@ref{3601,,IDLE_PRIORITY_CLASS}

@item 
@ref{3602,,NORMAL_PRIORITY_CLASS}

@item 
@ref{3603,,REALTIME_PRIORITY_CLASS}

@item 
@ref{3604,,CREATE_NO_WINDOW}

@item 
@ref{3605,,DETACHED_PROCESS}

@item 
@ref{3606,,CREATE_DEFAULT_ERROR_MODE}

@item 
@ref{3607,,CREATE_BREAKAWAY_FROM_JOB}
@end itemize

`pipesize' can be used to change the size of the pipe when
@ref{d7a,,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 版的變更: 新增 @code{pipesize} 參數。


Popen objects are supported as context managers via the @ref{186,,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{1b70,,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 版的變更: 新增情境管理器的支援。



在 3.6 版的變更: Popen destructor now emits a @ref{547,,ResourceWarning} warning if the child
process is still running.



在 3.8 版的變更: Popen can use @ref{529,,os.posix_spawn()} in some cases for better
performance. On Windows Subsystem for Linux and QEMU User Emulation,
Popen constructor using @ref{529,,os.posix_spawn()} no longer raise an
exception on errors like missing program, but the child process fails
with a non-zero @ref{c7a,,returncode}.

@end deffn

@node 例外<12>,,Popen Constructor,Using the subprocess Module
@anchor{library/subprocess exceptions}@anchor{3608}
@subsubsection 例外


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{2c0,,OSError}.  This occurs, for example,
when trying to execute a non-existent file.  Applications should prepare for
@ref{2c0,,OSError} exceptions. Note that, when @code{shell=True}, @ref{2c0,,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{2eb,,ValueError} will be raised if @ref{4b2,,Popen} is called with invalid
arguments.

@ref{35ec,,check_call()} and @ref{11bd,,check_output()} will raise
@ref{1525,,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{d79,,run()} and @ref{35e0,,Popen.communicate()} will raise @ref{17cf,,TimeoutExpired} if
the timeout expires before the process exits.

Exceptions defined in this module all inherit from @ref{35e6,,SubprocessError}.


在 3.3 版被加入: The @ref{35e6,,SubprocessError} base class was added.


@node 安全性注意事項,Popen Objects,Using the subprocess Module,subprocess --- 子行程管理
@anchor{library/subprocess security-considerations}@anchor{35f6}@anchor{library/subprocess subprocess-security}@anchor{3609}
@subsubsection 安全性注意事項


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{360a,,some platforms}, it is possible
to use @ref{57c,,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,安全性注意事項,subprocess --- 子行程管理
@anchor{library/subprocess popen-objects}@anchor{360b}
@subsubsection Popen Objects


Instances of the @ref{4b2,,Popen} class have the following methods:

@geindex poll() (subprocess.Popen 的方法)
@anchor{library/subprocess subprocess Popen poll}@anchor{360c}
@deffn {方法} Popen.poll ()

Check if child process has terminated.  Set and return
@ref{c7a,,returncode} attribute. Otherwise, returns @code{None}.
@end deffn

@geindex wait() (subprocess.Popen 的方法)
@anchor{library/subprocess subprocess Popen wait}@anchor{edb}
@deffn {方法} Popen.wait (timeout=None)

Wait for child process to terminate.  Set and return
@ref{c7a,,returncode} attribute.

If the process does not terminate after `timeout' seconds, raise a
@ref{17cf,,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{35e0,,Popen.communicate()} when using pipes to avoid that.
@end quotation
@end cartouche

@cartouche
@quotation 備註 
When the @code{timeout} parameter is not @code{None}, then (on POSIX) the
function is implemented using a busy loop (non-blocking call and short
sleeps). Use the @ref{b,,asyncio} module for an asynchronous wait: see
@ref{c62,,asyncio.create_subprocess_exec}.
@end quotation
@end cartouche


在 3.3 版的變更: 新增 `timeout'。

@end deffn

@geindex communicate() (subprocess.Popen 的方法)
@anchor{library/subprocess subprocess Popen communicate}@anchor{35e0}
@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{c7a,,returncode} attribute.  The optional `input' argument should be
data to be sent to the child process, or @code{None}, if no data should be sent
to the child.  If streams were opened in text mode, `input' must be a string.
Otherwise, it must be bytes.

@ref{35e0,,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{17cf,,TimeoutExpired} exception will be raised.  Catching this exception and
retrying communication will not lose any output.

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

@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'。

@end deffn

@geindex send_signal() (subprocess.Popen 的方法)
@anchor{library/subprocess subprocess Popen send_signal}@anchor{15d5}
@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{15d3,,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{15d3}
@deffn {方法} Popen.terminate ()

Stop the child. On POSIX OSs the method sends @ref{15d6,,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{15d4}
@deffn {方法} Popen.kill ()

Kills the child. On POSIX OSs the function sends SIGKILL to the child.
On Windows @ref{15d4,,kill()} is an alias for @ref{15d3,,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{360d}
@deffn {屬性} Popen.args

The `args' argument as it was passed to @ref{4b2,,Popen} -- a
sequence of program arguments or else a single string.


在 3.3 版被加入.

@end deffn

@geindex stdin (subprocess.Popen 的屬性)
@anchor{library/subprocess subprocess Popen stdin}@anchor{35f3}
@deffn {屬性} Popen.stdin

If the `stdin' argument was @ref{d7a,,PIPE}, this attribute is a writeable
stream object as returned by @ref{315,,open()}. If the `encoding' or `errors'
arguments were specified or the `text' or `universal_newlines' argument
was @code{True}, the stream is a text stream, otherwise it is a byte stream.
If the `stdin' argument was not @ref{d7a,,PIPE}, this attribute is @code{None}.
@end deffn

@geindex stdout (subprocess.Popen 的屬性)
@anchor{library/subprocess subprocess Popen stdout}@anchor{35f4}
@deffn {屬性} Popen.stdout

If the `stdout' argument was @ref{d7a,,PIPE}, this attribute is a readable
stream object as returned by @ref{315,,open()}. Reading from the stream provides
output from the child process. If the `encoding' or `errors' arguments were
specified or the `text' or `universal_newlines' argument was @code{True}, the
stream is a text stream, otherwise it is a byte stream. If the `stdout'
argument was not @ref{d7a,,PIPE}, this attribute is @code{None}.
@end deffn

@geindex stderr (subprocess.Popen 的屬性)
@anchor{library/subprocess subprocess Popen stderr}@anchor{35f5}
@deffn {屬性} Popen.stderr

If the `stderr' argument was @ref{d7a,,PIPE}, this attribute is a readable
stream object as returned by @ref{315,,open()}. Reading from the stream provides
error output from the child process. If the `encoding' or `errors' arguments
were specified or the `text' or `universal_newlines' argument was @code{True}, the
stream is a text stream, otherwise it is a byte stream. If the `stderr' argument
was not @ref{d7a,,PIPE}, this attribute is @code{None}.
@end deffn

@cartouche
@quotation 警告 
Use @ref{35e0,,communicate()} rather than @ref{35f3,,.stdin.write},
@ref{35f4,,.stdout.read} or @ref{35f5,,.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{360e}
@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{c7a}
@deffn {屬性} Popen.returncode

The child return code. Initially @code{None}, @ref{c7a,,returncode} is set by
a call to the @ref{360c,,poll()}, @ref{edb,,wait()}, or @ref{35e0,,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).
@end deffn

@node Windows Popen Helpers,Older high-level API,Popen Objects,subprocess --- 子行程管理
@anchor{library/subprocess windows-popen-helpers}@anchor{360f}
@subsubsection Windows Popen Helpers


The @ref{35fb,,STARTUPINFO} class and following constants are only available
on Windows.

@geindex STARTUPINFO (subprocess 中的類別)
@anchor{library/subprocess subprocess STARTUPINFO}@anchor{35fb}
@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{4b2,,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{3610}
@deffn {屬性} dwFlags

A bit field that determines whether certain @ref{35fb,,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{3611}
@deffn {屬性} hStdInput

If @ref{3610,,dwFlags} specifies @ref{3612,,STARTF_USESTDHANDLES}, this attribute
is the standard input handle for the process. If
@ref{3612,,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{3613}
@deffn {屬性} hStdOutput

If @ref{3610,,dwFlags} specifies @ref{3612,,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{3614}
@deffn {屬性} hStdError

If @ref{3610,,dwFlags} specifies @ref{3612,,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{3615}
@deffn {屬性} wShowWindow

If @ref{3610,,dwFlags} specifies @ref{3616,,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{3617,,SW_HIDE} is provided for this attribute. It is used when
@ref{4b2,,Popen} is called with @code{shell=True}.
@end deffn

@geindex lpAttributeList (subprocess.STARTUPINFO 的屬性)
@anchor{library/subprocess subprocess STARTUPINFO lpAttributeList}@anchor{e03}
@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{10fb,,os.set_handle_inheritable()} when passed to the @ref{4b2,,Popen}
constructor, else @ref{2c0,,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{1652,,os.system()}.  This also applies to
standard handle redirection, which temporarily creates inheritable
handles.
@end quotation
@end cartouche
@end table


在 3.7 版被加入.

@end deffn
@end deffn

@menu
* Windows Constants:: 

@end menu

@node Windows Constants,,,Windows Popen Helpers
@anchor{library/subprocess windows-constants}@anchor{3618}
@subsubsection Windows Constants


The @ref{dc,,subprocess} module exposes the following constants.

@geindex STD_INPUT_HANDLE (於 subprocess 模組中)
@anchor{library/subprocess subprocess STD_INPUT_HANDLE}@anchor{3619}
@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{361a}
@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{361b}
@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{3617}
@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{3612}
@deffn {資料} subprocess.STARTF_USESTDHANDLES

Specifies that the @ref{3611,,STARTUPINFO.hStdInput},
@ref{3613,,STARTUPINFO.hStdOutput}, and @ref{3614,,STARTUPINFO.hStdError} attributes
contain additional information.
@end deffn

@geindex STARTF_USESHOWWINDOW (於 subprocess 模組中)
@anchor{library/subprocess subprocess STARTF_USESHOWWINDOW}@anchor{3616}
@deffn {資料} subprocess.STARTF_USESHOWWINDOW

Specifies that the @ref{3615,,STARTUPINFO.wShowWindow} attribute contains
additional information.
@end deffn

@geindex STARTF_FORCEONFEEDBACK (於 subprocess 模組中)
@anchor{library/subprocess subprocess STARTF_FORCEONFEEDBACK}@anchor{361c}
@deffn {資料} subprocess.STARTF_FORCEONFEEDBACK

A @ref{3610,,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.


在 3.13 版被加入.

@end deffn

@geindex STARTF_FORCEOFFFEEDBACK (於 subprocess 模組中)
@anchor{library/subprocess subprocess STARTF_FORCEOFFFEEDBACK}@anchor{361d}
@deffn {資料} subprocess.STARTF_FORCEOFFFEEDBACK

A @ref{3610,,STARTUPINFO.dwFlags} parameter to specify that the mouse
cursor will not be changed when launching a process.


在 3.13 版被加入.

@end deffn

@geindex CREATE_NEW_CONSOLE (於 subprocess 模組中)
@anchor{library/subprocess subprocess CREATE_NEW_CONSOLE}@anchor{35fc}
@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{35fd}
@deffn {資料} subprocess.CREATE_NEW_PROCESS_GROUP

A @ref{4b2,,Popen} @code{creationflags} parameter to specify that a new process
group will be created. This flag is necessary for using @ref{155f,,os.kill()}
on the subprocess.

This flag is ignored if @ref{35fc,,CREATE_NEW_CONSOLE} is specified.
@end deffn

@geindex ABOVE_NORMAL_PRIORITY_CLASS (於 subprocess 模組中)
@anchor{library/subprocess subprocess ABOVE_NORMAL_PRIORITY_CLASS}@anchor{35fe}
@deffn {資料} subprocess.ABOVE_NORMAL_PRIORITY_CLASS

A @ref{4b2,,Popen} @code{creationflags} parameter to specify that a new process
will have an above average priority.


在 3.7 版被加入.

@end deffn

@geindex BELOW_NORMAL_PRIORITY_CLASS (於 subprocess 模組中)
@anchor{library/subprocess subprocess BELOW_NORMAL_PRIORITY_CLASS}@anchor{35ff}
@deffn {資料} subprocess.BELOW_NORMAL_PRIORITY_CLASS

A @ref{4b2,,Popen} @code{creationflags} parameter to specify that a new process
will have a below average priority.


在 3.7 版被加入.

@end deffn

@geindex HIGH_PRIORITY_CLASS (於 subprocess 模組中)
@anchor{library/subprocess subprocess HIGH_PRIORITY_CLASS}@anchor{3600}
@deffn {資料} subprocess.HIGH_PRIORITY_CLASS

A @ref{4b2,,Popen} @code{creationflags} parameter to specify that a new process
will have a high priority.


在 3.7 版被加入.

@end deffn

@geindex IDLE_PRIORITY_CLASS (於 subprocess 模組中)
@anchor{library/subprocess subprocess IDLE_PRIORITY_CLASS}@anchor{3601}
@deffn {資料} subprocess.IDLE_PRIORITY_CLASS

A @ref{4b2,,Popen} @code{creationflags} parameter to specify that a new process
will have an idle (lowest) priority.


在 3.7 版被加入.

@end deffn

@geindex NORMAL_PRIORITY_CLASS (於 subprocess 模組中)
@anchor{library/subprocess subprocess NORMAL_PRIORITY_CLASS}@anchor{3602}
@deffn {資料} subprocess.NORMAL_PRIORITY_CLASS

A @ref{4b2,,Popen} @code{creationflags} parameter to specify that a new process
will have a normal priority. (default)


在 3.7 版被加入.

@end deffn

@geindex REALTIME_PRIORITY_CLASS (於 subprocess 模組中)
@anchor{library/subprocess subprocess REALTIME_PRIORITY_CLASS}@anchor{3603}
@deffn {資料} subprocess.REALTIME_PRIORITY_CLASS

A @ref{4b2,,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.


在 3.7 版被加入.

@end deffn

@geindex CREATE_NO_WINDOW (於 subprocess 模組中)
@anchor{library/subprocess subprocess CREATE_NO_WINDOW}@anchor{3604}
@deffn {資料} subprocess.CREATE_NO_WINDOW

A @ref{4b2,,Popen} @code{creationflags} parameter to specify that a new process
will not create a window.


在 3.7 版被加入.

@end deffn

@geindex DETACHED_PROCESS (於 subprocess 模組中)
@anchor{library/subprocess subprocess DETACHED_PROCESS}@anchor{3605}
@deffn {資料} subprocess.DETACHED_PROCESS

A @ref{4b2,,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.


在 3.7 版被加入.

@end deffn

@geindex CREATE_DEFAULT_ERROR_MODE (於 subprocess 模組中)
@anchor{library/subprocess subprocess CREATE_DEFAULT_ERROR_MODE}@anchor{3606}
@deffn {資料} subprocess.CREATE_DEFAULT_ERROR_MODE

A @ref{4b2,,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.


在 3.7 版被加入.

@end deffn

@geindex CREATE_BREAKAWAY_FROM_JOB (於 subprocess 模組中)
@anchor{library/subprocess subprocess CREATE_BREAKAWAY_FROM_JOB}@anchor{3607}
@deffn {資料} subprocess.CREATE_BREAKAWAY_FROM_JOB

A @ref{4b2,,Popen} @code{creationflags} parameter to specify that a new process
is not associated with the job.


在 3.7 版被加入.

@end deffn

@node Older high-level API,Replacing Older Functions with the subprocess Module,Windows Popen Helpers,subprocess --- 子行程管理
@anchor{library/subprocess call-function-trio}@anchor{361e}@anchor{library/subprocess older-high-level-api}@anchor{361f}
@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{d79,,run()} in many cases, but lots of existing code
calls these functions.

@geindex call() (於 subprocess 模組中)
@anchor{library/subprocess subprocess call}@anchor{d7b}
@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{c7a,,returncode} attribute.

Code needing to capture stdout or stderr should use @ref{d79,,run()} instead:

@example
run(...).returncode
@end example

To suppress stdout or stderr, supply a value of @ref{134f,,DEVNULL}.

The arguments shown above are merely some common ones.
The full function signature is the
same as that of the @ref{4b2,,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'。



在 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{35ec}
@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{1525,,CalledProcessError}. The
@ref{1525,,CalledProcessError} object will have the return code in the
@ref{35ed,,returncode} attribute.
If @ref{35ec,,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{d79,,run()} instead:

@example
run(..., check=True)
@end example

To suppress stdout or stderr, supply a value of @ref{134f,,DEVNULL}.

The arguments shown above are merely some common ones.
The full function signature is the
same as that of the @ref{4b2,,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'。



在 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{11bd}
@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{1525,,CalledProcessError}. The
@ref{1525,,CalledProcessError} object will have the return code in the
@ref{35ed,,returncode} attribute and any output in the
@ref{35ef,,output} attribute.

這等同於：

@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{d79,,run()} -
most arguments are passed directly through to that interface.
One API deviation from @ref{d79,,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{35de,,Frequently Used Arguments} and @ref{d79,,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


在 3.1 版被加入.



在 3.3 版的變更: 新增 `timeout'。



在 3.4 版的變更: 新增 `input' 關鍵字引數的支援。



在 3.6 版的變更: 新增 `encoding' 與 `errors'。細節請見 @ref{d79,,run()}。



在 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 --- 子行程管理
@anchor{library/subprocess replacing-older-functions-with-the-subprocess-module}@anchor{3620}@anchor{library/subprocess subprocess-replacements}@anchor{1389}
@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{2c0,,OSError}
instead.

In addition, the replacements using @ref{11bd,,check_output()} will fail with a
@ref{1525,,CalledProcessError} if the requested operation produces a non-zero
return code. The output is still available as the
@ref{35ef,,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 @ref{dc,,subprocess} module.

@menu
* Replacing /bin/sh shell command substitution:: 
* Replacing shell pipeline:: 
* 取代 os.system(): 取代 os system. 
* Replacing the os.spawn family: Replacing the os spawn family. 
* 取代 os.popen(): 取代 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{3621}
@subsubsection Replacing @code{/bin/sh} shell command substitution


@example
output=$(mycmd myarg)
@end example

變成：

@example
output = check_output(["mycmd", "myarg"])
@end example

@node Replacing shell pipeline,取代 os system,Replacing /bin/sh shell command substitution,Replacing Older Functions with the subprocess Module
@anchor{library/subprocess replacing-shell-pipeline}@anchor{3622}
@subsubsection Replacing shell pipeline


@example
output=$(dmesg | grep hda)
@end example

變成：

@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

變成：

@example
output = check_output("dmesg | grep hda", shell=True)
@end example

@node 取代 os system,Replacing the os spawn family,Replacing shell pipeline,Replacing Older Functions with the subprocess Module
@anchor{library/subprocess replacing-os-system}@anchor{3623}
@subsubsection 取代 @code{os.system()}


@example
sts = os.system("mycmd" + " myarg")
# 變成
retcode = call("mycmd" + " myarg", shell=True)
@end example

註解：


@itemize *

@item 
Calling the program through the shell is usually not required.

@item 
The @ref{d7b,,call()} return value is encoded differently to that of
@ref{1652,,os.system()}.

@item 
The @ref{1652,,os.system()} function ignores SIGINT and SIGQUIT signals while
the command is running, but the caller must do this separately when
using the @ref{dc,,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,取代 os popen,取代 os system,Replacing Older Functions with the subprocess Module
@anchor{library/subprocess replacing-the-os-spawn-family}@anchor{3624}
@subsubsection Replacing the @code{os.spawn} family


P_NOWAIT 範例：

@example
pid = os.spawnlp(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg")
==>
pid = Popen(["/bin/mycmd", "myarg"]).pid
@end example

P_WAIT 範例：

@example
retcode = os.spawnlp(os.P_WAIT, "/bin/mycmd", "mycmd", "myarg")
==>
retcode = call(["/bin/mycmd", "myarg"])
@end example

向量範例：

@example
os.spawnvp(os.P_NOWAIT, path, args)
==>
Popen([path] + args[1:])
@end example

環境範例：

@example
os.spawnlpe(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg", env)
==>
Popen(["/bin/mycmd", "myarg"], env=@{"PATH": "/usr/bin"@})
@end example

@node 取代 os popen,,Replacing the os spawn family,Replacing Older Functions with the subprocess Module
@anchor{library/subprocess replacing-os-popen}@anchor{3625}
@subsubsection 取代 @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,註解,Replacing Older Functions with the subprocess Module,subprocess --- 子行程管理
@anchor{library/subprocess legacy-shell-invocation-functions}@anchor{3626}
@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{11bf}
@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{11bd,,check_output()} and
return a 2-tuple @code{(exitcode, output)}.
`encoding' and `errors' are used to decode output;
see the notes on @ref{35de,,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{2006,,可用性}: Unix, Windows.


在 3.3.4 版的變更: 新增對 Windows 的支援。

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{c7a,,returncode}.



在 3.11 版的變更: 新增 `encoding' 與 `errors' 參數。

@end deffn

@geindex getoutput() (於 subprocess 模組中)
@anchor{library/subprocess subprocess getoutput}@anchor{11be}
@deffn {函式} subprocess.getoutput (cmd, *, encoding=None, errors=None)

Return output (stdout and stderr) of executing `cmd' in a shell.

Like @ref{11bf,,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{2006,,可用性}: Unix, Windows.


在 3.3.4 版的變更: 新增對 Windows 的支援



在 3.11 版的變更: 新增 `encoding' 與 `errors' 參數。

@end deffn

@node 註解,,Legacy Shell Invocation Functions,subprocess --- 子行程管理
@anchor{library/subprocess notes}@anchor{3627}
@subsubsection 註解


@menu
* Timeout Behavior:: 
* Converting an argument sequence to a string on Windows:: 
* 停用 posix_spawn(): 停用 posix_spawn. 

@end menu

@node Timeout Behavior,Converting an argument sequence to a string on Windows,,註解
@anchor{library/subprocess subprocess-timeout-behavior}@anchor{3628}@anchor{library/subprocess timeout-behavior}@anchor{3629}
@subsubsection Timeout Behavior


When using the @code{timeout} parameter in functions like @ref{d79,,run()},
@ref{edb,,Popen.wait()}, or @ref{35e0,,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{17cf,,TimeoutExpired} exceptions because
process creation and system scheduling inherently require time.
@end enumerate

@node Converting an argument sequence to a string on Windows,停用 posix_spawn,Timeout Behavior,註解
@anchor{library/subprocess converting-an-argument-sequence-to-a-string-on-windows}@anchor{362a}@anchor{library/subprocess converting-argument-sequence}@anchor{35f8}
@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{c9,,shlex}

Module which provides function to parse and escape command lines.
@end table


@node 停用 posix_spawn,,Converting an argument sequence to a string on Windows,註解
@anchor{library/subprocess disable-posix-spawn}@anchor{362b}@anchor{library/subprocess disable-use-of-posix-spawn}@anchor{362c}
@subsubsection 停用 @code{posix_spawn()}


在 Linux 上，@ref{dc,,subprocess} 在安全的情況下預設會在內部使用 @code{vfork()} 系統呼叫，而不是 @code{fork()}，這顯著地提高了性能。

@example
subprocess._USE_POSIX_SPAWN = False  # 見 CPython 問題 gh-NNNNNN。
@end example

在任何 Python 版本上將這個設定為 false 都是安全的。當不受支援時，它對舊版本或沒有支援的新版本沒有影響。不要假設屬性可供讀取。儘管它的名稱是這樣，真實值並不表示將使用相應的函式，而只是表示可能會使用。

每當你需要使用這些私有開關以重現你所看到的問題時，請隨時提出問題 (file issues)。從程式碼中的註解連結到該問題。


在 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 --- 事件排程器,queue --- 同步佇列 synchronized queue 類別,subprocess --- 子行程管理,並行執行 Concurrent Execution
@anchor{library/sched doc}@anchor{362d}@anchor{library/sched module-sched}@anchor{c4}@anchor{library/sched sched-event-scheduler}@anchor{362e}@anchor{library/sched translation-repo}@anchor{362f}
@subsection @code{sched} --- 事件排程器


@geindex module; sched

`原始碼：'Lib/sched.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/sched.py}

@geindex event scheduling（事件排程）


__________________________________________________________________


@ref{c4,,sched} 模組定義了一個有實作通用事件排程器的類別：

@geindex scheduler (sched 中的類別)
@anchor{library/sched sched scheduler}@anchor{1328}
@deffn {類別} sched.scheduler (timefunc=time.monotonic, delayfunc=time.sleep)

@ref{1328,,scheduler} 類別定義了事件排程的泛用介面。它需要兩個函式來和「外部世界」作用 —— `timefunc' 應不帶引數地被呼叫，並回傳一個數字（為「時間」，可為任何單位）。`delayfunc' 函式應以一個引數呼叫，並與 `timefunc' 的輸出相容，且應延遲其指定的時間單位。每個事件運行後，也會以引數 @code{0} 呼叫 `delayfunc'，來使得其他執行緒有機會在多執行緒應用程式中運行。


在 3.3 版的變更: `timefunc' 和 `delayfunc' 參數是可選的。



在 3.3 版的變更: @ref{1328,,scheduler} 類別可以安全地在多執行緒環境中使用。

@end deffn

範例：

@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',))
...     # 儘管優先順序較高，但由於 enter() 是相對的，'keyword' 在 'positional' 之後運行
...     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
* 排程器物件:: 

@end menu

@node 排程器物件,,,sched --- 事件排程器
@anchor{library/sched id1}@anchor{3630}@anchor{library/sched scheduler-objects}@anchor{3631}
@subsubsection 排程器物件


@ref{1328,,scheduler} 實例具有以下方法和屬性：

@geindex enterabs() (sched.scheduler 的方法)
@anchor{library/sched sched scheduler enterabs}@anchor{132a}
@deffn {方法} scheduler.enterabs (time, priority, action, argument=(), kwargs=@{@})

為一個新事件排程。`time' 引數應該是與傳遞給建構函式的 `timefunc' 函式回傳值相容的數字型別。安排在相同 `time' 的事件將按照其 `priority' 的順序執行。數字越小代表優先順序越高。

執行事件意味著執行 @code{action(*argument, **kwargs)}。`argument' 是一個包含 `action' 之位置引數的序列。`kwargs' 是一個字典，帶有 `action' 的關鍵字引數。

回傳值是一個事件，可用於後續取消該事件（請見 @ref{1be5,,cancel()}）。


在 3.3 版的變更: `argument' 參數是可選的。



在 3.3 版的變更: 新增 `kwargs' 參數。

@end deffn

@geindex enter() (sched.scheduler 的方法)
@anchor{library/sched sched scheduler enter}@anchor{1329}
@deffn {方法} scheduler.enter (delay, priority, action, argument=(), kwargs=@{@})

為一個排程事件延期 `delay' 個時間單位。除了相對時間之外，其他引數、效果和回傳值皆與 @ref{132a,,enterabs()} 的相同。


在 3.3 版的變更: `argument' 參數是可選的。



在 3.3 版的變更: 新增 `kwargs' 參數。

@end deffn

@geindex cancel() (sched.scheduler 的方法)
@anchor{library/sched sched scheduler cancel}@anchor{1be5}
@deffn {方法} scheduler.cancel (event)

從佇列中刪除該事件。如果 `event' 不是目前佇列中的事件，此方法將引發 @ref{2eb,,ValueError}。
@end deffn

@geindex empty() (sched.scheduler 的方法)
@anchor{library/sched sched scheduler empty}@anchor{3632}
@deffn {方法} scheduler.empty ()

如果事件佇列為空，則回傳 @code{True}。
@end deffn

@geindex run() (sched.scheduler 的方法)
@anchor{library/sched sched scheduler run}@anchor{1327}
@deffn {方法} scheduler.run (blocking=True)

運行所有已排程的事件。此方法將會等待（使用傳遞給建構函式的 `delayfunc' 函式）下一個事件，然後執行它，並依此類推，直到不再有排程好的事件。

如果 `blocking' 為 false，則執行最快到期的已排程事件（如存在），然後回傳排程器中下一個排程呼叫（如存在）的截止時間。

`action' 或 `delayfunc' 都可能引發例外。無論哪種情況，排程器都將保持一致的狀態並傳遞例外。如果是由 `action' 引發例外，則後續呼叫 @ref{1327,,run()} 時將不會嘗試運行該事件。

如果一系列事件的運行時長比執行下一個事件前的可用時長 (available time) 更長，那麼排程器就單純會落後。不會有事件被丟棄；呼叫程式碼也要負責取消不再相關的事件。


在 3.3 版的變更: 新增 `blocking' 參數。

@end deffn

@geindex queue (sched.scheduler 的屬性)
@anchor{library/sched sched scheduler queue}@anchor{3633}
@deffn {屬性} scheduler.queue

會按事件運行順序回傳即將發生的事件串列的唯讀屬性。每個事件都以@ref{857,,附名元組 (named tuple)} 表示，並包含以下欄位：時間、優先順序、動作 (action)、引數、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 --- 同步佇列 synchronized queue 類別,contextvars --- 情境變數,sched --- 事件排程器,並行執行 Concurrent Execution
@anchor{library/queue doc}@anchor{3634}@anchor{library/queue module-queue}@anchor{bb}@anchor{library/queue queue-a-synchronized-queue-class}@anchor{3635}@anchor{library/queue translation-repo}@anchor{3636}
@subsection @code{queue} --- 同步佇列 (synchronized queue) 類別


@geindex module; queue

`原始碼：'Lib/queue.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/queue.py}


__________________________________________________________________


@ref{bb,,queue} module（模組）實作多生產者、多消費者佇列。在執行緒程式設計中，必須在多執行緒之間安全地交換資訊時，特別有用。此 module 中的 @ref{158c,,Queue} class 實作所有必需的鎖定語義 (locking semantics)。

此 module 實作三種型別的佇列，它們僅在取出條目的順序上有所不同。在 @abbr{FIFO} 佇列中，先加入的任務是第一個被取出的。在 @abbr{LIFO} 佇列中，最近被加入的條目是第一個被取出的（像堆疊 (stack) 一樣操作）。使用優先佇列 (priority queue) 時，條目將保持排序狀態（使用 @ref{6d,,heapq} module），並先取出最低值條目。

在內部，這三種型別的佇列使用鎖 (lock) 來暫時阻塞競爭執行緒；但是，它們並不是被設計來處理執行緒內的 reentrancy（可重入）。

此外，此 module 實作一個「簡單」的 @abbr{FIFO} 佇列型別 @ref{d59,,SimpleQueue}，其特定的實作是以較少的功能為代價，來提供額外的保證。

@ref{bb,,queue} module 定義了以下的 class 和例外：

@geindex Queue (queue 中的類別)
@anchor{library/queue queue Queue}@anchor{158c}
@deffn {類別} queue.Queue (maxsize=0)

@abbr{FIFO} 佇列的建構子 (constructor)。`maxsize' 是一個整數，用於設置佇列中可放置的項目數的上限。一旦達到此大小，插入將會阻塞，直到佇列中的項目被消耗。如果 `maxsize' 小於或等於零，則佇列大小為無限。
@end deffn

@geindex LifoQueue (queue 中的類別)
@anchor{library/queue queue LifoQueue}@anchor{2560}
@deffn {類別} queue.LifoQueue (maxsize=0)

@abbr{LIFO} 佇列的建構子。`maxsize' 是一個整數，用於設置佇列中可放置的項目數的上限。一旦達到此大小，插入將被鎖定，到佇列中的項目被消耗。如果 `maxsize' 小於或等於零，則佇列大小為無限。
@end deffn

@geindex PriorityQueue (queue 中的類別)
@anchor{library/queue queue PriorityQueue}@anchor{2561}
@deffn {類別} queue.PriorityQueue (maxsize=0)

優先佇列的建構子。`maxsize' 是一個整數，用於設置佇列中可放置的項目數的上限。一旦達到此大小，插入將被阻塞，直到佇列中的項目被消耗。如果 `maxsize' 小於或等於零，則佇列大小為無限。

最低值的條目會最先被取出（最低值的條目是被會 @code{min(entries)} 回傳的那一個）。條目的典型模式是格式為 @code{(priority_number, data)} 的 tuple（元組）。

如果 `data' 元素為不可比較的，則可以將資料包裝在一個 class 中，該 class 忽略資料項目並僅比較優先數：

@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{d59}
@deffn {類別} queue.SimpleQueue

無界的 @abbr{FIFO} 佇列的建構子。簡單佇列缺少任務追蹤等進階功能。


在 3.7 版被加入.

@end deffn

@geindex Empty
@anchor{library/queue queue Empty}@anchor{3520}
@deffn {例外} queue.Empty

當對一個空的 @ref{158c,,Queue} 物件呼叫非阻塞的 (non-blocking) @ref{3078,,get()}（或 @ref{3637,,get_nowait()}）將引發此例外。
@end deffn

@geindex Full
@anchor{library/queue queue Full}@anchor{3521}
@deffn {例外} queue.Full

當對一個已滿的 @ref{158c,,Queue} 物件呼叫非阻塞的 @ref{3638,,put()}（或 @ref{3077,,put_nowait()}）將引發此例外。
@end deffn

@geindex ShutDown
@anchor{library/queue queue ShutDown}@anchor{53e}
@deffn {例外} queue.ShutDown

當對一個已關閉的 @ref{158c,,Queue} 物件呼叫 @ref{3638,,put()} 或 @ref{3078,,get()} 時將引發此例外。


在 3.13 版被加入.

@end deffn

@menu
* 佇列物件:: 
* SimpleQueue 物件:: 

@end menu

@node 佇列物件,SimpleQueue 物件,,queue --- 同步佇列 synchronized queue 類別
@anchor{library/queue queue-objects}@anchor{3639}@anchor{library/queue queueobjects}@anchor{363a}
@subsubsection 佇列物件


佇列物件（@ref{158c,,Queue}、@ref{2560,,LifoQueue}、@ref{2561,,PriorityQueue}）提供下面描述的公用 method。

@geindex qsize() (queue.Queue 的方法)
@anchor{library/queue queue Queue qsize}@anchor{363b}
@deffn {方法} Queue.qsize ()

回傳佇列的近似大小。注意，qsize() > 0 並不能保證後續的 get() 不會阻塞，qsize() < maxsize 也不會保證 put() 不會阻塞。
@end deffn

@geindex empty() (queue.Queue 的方法)
@anchor{library/queue queue Queue empty}@anchor{363c}
@deffn {方法} Queue.empty ()

如果佇列為空，則回傳 @code{True}，否則回傳 @code{False}。如果 empty() 回傳 @code{True}，則不保證後續呼叫 put() 不會阻塞。同樣，如果 empty() 回傳 @code{False}，則不保證後續呼叫 get() 不會阻塞。
@end deffn

@geindex full() (queue.Queue 的方法)
@anchor{library/queue queue Queue full}@anchor{363d}
@deffn {方法} Queue.full ()

如果佇列已滿，則回傳 @code{True} ，否則回傳 @code{False}。如果 full() 回傳 @code{True}，則不保證後續呼叫 get() 不會阻塞。同樣，如果 full() 回傳 @code{False}，則不保證後續呼叫 put() 不會阻塞。
@end deffn

@geindex put() (queue.Queue 的方法)
@anchor{library/queue queue Queue put}@anchor{3638}
@deffn {方法} Queue.put (item, block=True, timeout=None)

將 `item' 放入佇列中。如果可選的 args `block' 為 true、`timeout' 為 @code{None}（預設值），則在必要時阻塞，直到自由槽 (free slot) 可用。如果 `timeout' 為正數，則最多阻塞 `timeout' 秒，如果該時間內沒有可用的自由槽，則會引發 @ref{3521,,Full} 例外。否則（`block' 為 false），如果自由槽立即可用，則將項目放在佇列中，否則引發 @ref{3521,,Full} 例外（在這種情況下，`timeout' 將被忽略）。

如果佇列已被關閉，則引發 @ref{53e,,ShutDown}。
@end deffn

@geindex put_nowait() (queue.Queue 的方法)
@anchor{library/queue queue Queue put_nowait}@anchor{3077}
@deffn {方法} Queue.put_nowait (item)

等效於 @code{put(item, block=False)}。
@end deffn

@geindex get() (queue.Queue 的方法)
@anchor{library/queue queue Queue get}@anchor{3078}
@deffn {方法} Queue.get (block=True, timeout=None)

從佇列中移除並回傳一個項目。如果可選的 args `block' 為 true，且 `timeout' 為 @code{None}（預設值），則在必要時阻塞，直到有可用的項目。如果 `timeout' 是正數，則最多會阻塞 `timeout' 秒，如果該時間內沒有可用的項目，則會引發 @ref{3520,,Empty} 例外。否則（`block' 為 false），如果立即可用，則回傳一個項目，否則引發 @ref{3520,,Empty} 例外（在這種情況下，`timeout' 將被忽略）。

在 POSIX 系統的 3.0 版之前，以及 Windows 的所有版本，如果 `block' 為 true 且 `timeout' 為 @code{None}，則此操作將在底層鎖上進入不間斷等待。這意味著不會發生例外，特別是 SIGINT（中斷訊號）不會觸發 @ref{bbc,,KeyboardInterrupt}。

如果佇列已被關閉且為空，或佇列已立即關閉，則引發 @ref{53e,,ShutDown}。
@end deffn

@geindex get_nowait() (queue.Queue 的方法)
@anchor{library/queue queue Queue get_nowait}@anchor{3637}
@deffn {方法} Queue.get_nowait ()

等效於 @code{get(False)}。
@end deffn

有兩個 method 可以支援追蹤放入佇列的任務是否已由常駐消費者執行緒 (daemon consumer threads) 完全處理。

@geindex task_done() (queue.Queue 的方法)
@anchor{library/queue queue Queue task_done}@anchor{351c}
@deffn {方法} Queue.task_done ()

表示先前放入佇列的任務已完成。由佇列消費者執行緒使用。對於用來提取任務的每個 @ref{3078,,get()}，隨後呼叫 @ref{351c,,task_done()} 告訴佇列任務的處理已完成。

如果目前 @ref{351d,,join()} 阻塞，它將會在所有項目都已處理完畢後恢復（代表對於以 @ref{3638,,put()} 放進佇列的每個項目，都要收到 @ref{351c,,task_done()} 的呼叫）。

如果呼叫次數超過佇列中放置的項目數量，則引發 @ref{2eb,,ValueError}。
@end deffn

@geindex join() (queue.Queue 的方法)
@anchor{library/queue queue Queue join}@anchor{351d}
@deffn {方法} Queue.join ()

持續阻塞直到佇列中的所有項目都已被取得並處理完畢。

每當項目被加到佇列中時，未完成任務的計數都會增加。每當消費者執行緒呼叫 @ref{351c,,task_done()} 以指示該項目已被取出並且對其的所有工作都已完成時，計數就會下降。當未完成任務的計數降至零時，@ref{351d,,join()} 將停止阻塞。
@end deffn

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

@end menu

@node Waiting for task completion,Terminating queues,,佇列物件
@anchor{library/queue waiting-for-task-completion}@anchor{363e}
@subsubsection Waiting for task completion


如何等待放入佇列的任務完成的範例：

@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,佇列物件
@anchor{library/queue terminating-queues}@anchor{363f}
@subsubsection Terminating queues


When no longer needed, @ref{158c,,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{53d}
@deffn {方法} Queue.shutdown (immediate=False)

Put a @ref{158c,,Queue} instance into a shutdown mode.

The queue can no longer grow.
Future calls to @ref{3638,,put()} raise @ref{53e,,ShutDown}.
Currently blocked callers of @ref{3638,,put()} will be unblocked
and will raise @ref{53e,,ShutDown} in the formerly blocked thread.

If `immediate' is false (the default), the queue can be wound
down normally with @ref{3078,,get()} calls to extract tasks
that have already been loaded.

And if @ref{351c,,task_done()} is called for each remaining task, a
pending @ref{351d,,join()} will be unblocked normally.

Once the queue is empty, future calls to @ref{3078,,get()} will
raise @ref{53e,,ShutDown}.

If `immediate' is true, the queue is terminated immediately.
The queue is drained to be completely empty.  All callers of
@ref{351d,,join()} are unblocked regardless of the number
of unfinished tasks.  Blocked callers of @ref{3078,,get()}
are unblocked and will raise @ref{53e,,ShutDown} because the
queue is empty.

Use caution when using @ref{351d,,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.


在 3.13 版被加入.

@end deffn

@node SimpleQueue 物件,,佇列物件,queue --- 同步佇列 synchronized queue 類別
@anchor{library/queue simplequeue-objects}@anchor{3640}
@subsubsection SimpleQueue 物件


@ref{d59,,SimpleQueue} 物件提供下面描述的公用 method。

@geindex qsize() (queue.SimpleQueue 的方法)
@anchor{library/queue queue SimpleQueue qsize}@anchor{3641}
@deffn {方法} SimpleQueue.qsize ()

傳回佇列的近似大小。注意，qsize() > 0 並不能保證後續的 get() 不會阻塞。
@end deffn

@geindex empty() (queue.SimpleQueue 的方法)
@anchor{library/queue queue SimpleQueue empty}@anchor{3642}
@deffn {方法} SimpleQueue.empty ()

如果佇列為空，則回傳 @code{True}，否則回傳 @code{False}。如果 empty() 回傳 @code{False}，則不保證後續呼叫 get() 不會阻塞。
@end deffn

@geindex put() (queue.SimpleQueue 的方法)
@anchor{library/queue queue SimpleQueue put}@anchor{3643}
@deffn {方法} SimpleQueue.put (item, block=True, timeout=None)

將 `item' 放入佇列中。此 method 從不阻塞，並且都會成功（除了潛在的低階錯誤，像是分配記憶體失敗）。可選的 args `block' 和 `timeout' 會被忽略，它們僅是為了與 @ref{3638,,Queue.put()} 相容才存在。

此 method 有一個可重入 (reentrant) 的 C 實作。意思就是，一個 @code{put()} 或 @code{get()} 呼叫，可以被同一執行緒中的另一個 @code{put()} 呼叫中斷，而不會造成死鎖 (deadlock) 或損壞佇列中的內部狀態。這使得它適合在解構子 (destructor) 中使用，像是 @code{__del__} method 或 @ref{11a,,weakref} 回呼函式 (callback)。
@end deffn

@geindex put_nowait() (queue.SimpleQueue 的方法)
@anchor{library/queue queue SimpleQueue put_nowait}@anchor{3644}
@deffn {方法} SimpleQueue.put_nowait (item)

等效於 @code{put(item, block=False)}，用於與 @ref{3077,,Queue.put_nowait()} 相容。
@end deffn

@geindex get() (queue.SimpleQueue 的方法)
@anchor{library/queue queue SimpleQueue get}@anchor{3645}
@deffn {方法} SimpleQueue.get (block=True, timeout=None)

從佇列中移除並回傳一個項目。如果可選的 args `block' 為 true，且 `timeout' 為 @code{None}（預設值），則在必要時阻塞，直到有可用的項目。如果 `timeout' 是正數，則最多會阻塞 `timeout' 秒，如果該時間內沒有可用的項目，則會引發 @ref{3520,,Empty} 例外。否則（`block' 為 false），如果立即可用，則回傳一個項目，否則引發 @ref{3520,,Empty} 例外（在這種情況下，`timeout' 將被忽略）。
@end deffn

@geindex get_nowait() (queue.SimpleQueue 的方法)
@anchor{library/queue queue SimpleQueue get_nowait}@anchor{3646}
@deffn {方法} SimpleQueue.get_nowait ()

等效於 @code{get(False)}。
@end deffn


@subsubheading 也參考



@table @asis

@item Class @ref{1ab3,,multiprocessing.Queue}

用於多行程處理 (multi-processing)（而非多執行緒）情境 (context) 的佇列 class。
@end table

@ref{7ed,,collections.deque} 是無界佇列的替代實作，有快速且具原子性 (atomic) 的 @ref{282b,,append()} 和 @ref{2831,,popleft()} 操作，這些操作不需要鎖定，並且還支持索引。


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node contextvars --- 情境變數,_thread --- 低階執行緒 API,queue --- 同步佇列 synchronized queue 類別,並行執行 Concurrent Execution
@anchor{library/contextvars doc}@anchor{3647}@anchor{library/contextvars contextvars-context-variables}@anchor{3648}@anchor{library/contextvars module-contextvars}@anchor{28}@anchor{library/contextvars translation-repo}@anchor{3649}
@subsection @code{contextvars} --- 情境變數


@geindex module; contextvars


__________________________________________________________________


本模組供 API 來管理、儲存及存取單一情境各自的狀態（context-local state）。 用 @ref{17f0,,ContextVar} 類別宣告和處理`情境變數'。 @ref{34d5,,copy_context()} 函式和 @ref{177,,Context} 類別應在非同步框架中管理目前的情境。

帶有狀態的 Context Manager 應該使用情境變數，而不是 @ref{17df,,threading.local()}，才能防止它們的狀態在並行（concurrent）程式碼中使用時意外外溢並干擾到其他程式碼。

其他詳細資訊，請參閱 
@geindex Python Enhancement Proposals; PEP 567
PEP 567@footnote{https://peps.python.org/pep-0567/}。


在 3.7 版被加入.


@menu
* 情境變數:: 
* 手動情境管理:: 
* 對 asyncio 的支援:: 

@end menu

@node 情境變數,手動情境管理,,contextvars --- 情境變數
@anchor{library/contextvars context-variables}@anchor{364a}
@subsubsection 情境變數


@geindex ContextVar (contextvars 中的類別)
@anchor{library/contextvars contextvars ContextVar}@anchor{17f0}
@deffn {類別} contextvars.ContextVar (name[, *, default])

此類別用在宣告新的情境變數，例如：

@example
var: ContextVar[int] = ContextVar('var', default=42)
@end example

必要參數 `name' 用於自我檢查（introspection）和除錯。

當在目前的情境中找不到變數的值時，@ref{364b,,ContextVar.get()} 會回傳可選的僅限關鍵字參數 `default'。

`重要：'情境變數應該在最頂端的模組層級建立，絕對不要在閉包（closure）中建立。 @ref{177,,Context} 物件持有情境變數的強參照，這會阻止情境變數被正確地垃圾回收（garbage collected）。

@geindex name (contextvars.ContextVar 的屬性)
@anchor{library/contextvars contextvars ContextVar name}@anchor{364c}
@deffn {屬性} name

這個變數的名稱。這是一個唯讀屬性。


在 3.7.1 版被加入.

@end deffn

@geindex get() (contextvars.ContextVar 的方法)
@anchor{library/contextvars contextvars ContextVar get}@anchor{364b}
@deffn {方法} get ([default])

回傳當前情境的情境變數值。

如果在當前情境中沒有變數的值，此方法將：


@itemize *

@item 
回傳方法的 `default' 引數值（如果有的話）；否則

@item 
回傳情境變數的預設值（如果建立情境變數時有指定預設值的話）；否則

@item 
會引發一個 @ref{2500,,LookupError}。
@end itemize
@end deffn

@geindex set() (contextvars.ContextVar 的方法)
@anchor{library/contextvars contextvars ContextVar set}@anchor{364d}
@deffn {方法} set (value)

在目前的情境中，呼叫以設定情境變數的新值。

`value' 屬必要引數，是情境變數的新值。

回傳一個 @ref{1e2,,Token} 物件，該物件可透過 @ref{364e,,ContextVar.reset()} 方法，用來將變數還原到之前的值。
@end deffn

@geindex reset() (contextvars.ContextVar 的方法)
@anchor{library/contextvars contextvars ContextVar reset}@anchor{364e}
@deffn {方法} reset (token)

將情境變數重設為使用 @ref{364d,,ContextVar.set()} 建立 `token' 前的值。

舉例來說：

@example
var = ContextVar('var')

token = var.set('new value')
# 使用 'var' 的程式碼；var.get() 回傳 'new value'。
var.reset(token)

# 在重設呼叫之後，var 又沒有值了，所以
# var.get() 會引發 LookupError。
@end example
@end deffn
@end deffn

@geindex Token (contextvars 中的類別)
@anchor{library/contextvars contextvars Token}@anchor{1e2}
@deffn {類別} contextvars.Token

`Token' 物件由 @ref{364d,,ContextVar.set()} 方法回傳，可以傳遞給 @ref{364e,,ContextVar.reset()} 方法，用以將變數的值還原為相對應的 `set' 之前的值。

The token supports @ref{22ba,,context manager protocol}
to restore the corresponding context variable value at the exit from
@ref{186,,with} block:

@example
var = ContextVar('var', default='default value')

with var.set('new value'):
    assert var.get() == 'new value'

assert var.get() == 'default value'
@end example


在 3.14 版被加入: 新增對用作情境管理器的支援。


@geindex var (contextvars.Token 的屬性)
@anchor{library/contextvars contextvars Token var}@anchor{364f}
@deffn {屬性} var

唯讀屬性。 指向建立 token 的 @ref{17f0,,ContextVar} 物件。
@end deffn

@geindex old_value (contextvars.Token 的屬性)
@anchor{library/contextvars contextvars Token old_value}@anchor{3650}
@deffn {屬性} old_value

唯讀屬性。 值為變數在呼叫 @ref{364d,,ContextVar.set()} 方法之前的值。如果變數在呼叫前沒有設定，則指向 @ref{177f,,Token.MISSING}。
@end deffn

@geindex MISSING (contextvars.Token 的屬性)
@anchor{library/contextvars contextvars Token MISSING}@anchor{177f}
@deffn {屬性} MISSING

由 @ref{3650,,Token.old_value} 使用的標記物件。
@end deffn
@end deffn

@node 手動情境管理,對 asyncio 的支援,情境變數,contextvars --- 情境變數
@anchor{library/contextvars manual-context-management}@anchor{3651}
@subsubsection 手動情境管理


@geindex copy_context() (於 contextvars 模組中)
@anchor{library/contextvars contextvars copy_context}@anchor{34d5}
@deffn {函式} contextvars.copy_context ()

回傳目前 @ref{177,,Context} 物件的複本（copy）。

以下程式碼片段會取得目前情境的複本，並顯示在其中設定的所有變數及其值：:

@example
ctx: Context = copy_context()
print(list(ctx.items()))
@end example

這個函式具有 `O'(1) 的複雜度，也就是說，對於只有少許情境變數的情境和有大量情境變數的情境，速度都一樣快。
@end deffn

@geindex Context (contextvars 中的類別)
@anchor{library/contextvars contextvars Context}@anchor{177}
@deffn {類別} contextvars.Context

@ref{17f0,,ContextVars} 到其值的映射。

@code{Context()} 會建立一個沒有值的空情境。要取得目前情境的複本，請使用 @ref{34d5,,copy_context()} 函式。

每個執行緒都有自己的 @code{Context} 物件中目前主控中的堆疊（stack）。@ref{18cb,,current context} 是目前執行緒堆疊頂端的 @code{Context} 物件。  堆疊中的所有 @code{Context} 物件都被視為`已進入'。

`進入'一個情境，可以藉由呼叫其 @ref{18b2,,run()} 方法來完成，此`進入'的動作會將一情境推到目前執行緒的情境堆疊的頂端，使該情境成為目前的情境。

如果你傳遞給 @ref{18b2,,run()} 方法的回呼函式（callback functions），該函式回傳之後，就會自動`退出'目前的情境，這會將目前的情境還原到進入情境之前的狀態，方法是將情境從情境堆疊的頂端彈出。

因為每個執行緒都有自己的情境堆疊，當值在不同的執行緒中被指定時， @ref{17f0,,ContextVar} 物件的行為與 @ref{17df,,threading.local()} 相似。

嘗試進入已進入的情境，包括在其他執行緒中進入的情境，會引發 @ref{244,,RuntimeError}。

退出情境後，之後可以重新進入（從任何執行緒）。

任何透過 @ref{364d,,ContextVar.set()} 方法對 @ref{17f0,,ContextVar} 值的改變都會記錄在目前的情境中。  @ref{364b,,ContextVar.get()} 方法回傳與當前情境相關的值。  退出情境實際造成的效果會像是將其在進入情境時對情境變數所做的任何變一一彈出並還原（如果需要，可以透過重新進入情境來還原值）。

情境（Context）實作了 @ref{abe,,collections.abc.Mapping} 介面。

@geindex run() (contextvars.Context 的方法)
@anchor{library/contextvars contextvars Context run}@anchor{18b2}
@deffn {方法} run (callable, *args, **kwargs)

進入 Context，執行 @code{callable(*args, **kwargs)}，然後退出 Context。 回傳 `callable' 的回傳值，如果發生例外（exception），則傳播例外。

例如：

@example
import contextvars

var = contextvars.ContextVar('var')
var.set('spam')
print(var.get())  # 'spam'

ctx = contextvars.copy_context()

def main():
    # 'var' 之前被設成 'spam'
    # 呼叫 'copy_context()' 和 'ctx.run(main)'，所以：
    print(var.get())  # 'spam'
    print(ctx[var])  # 'spam'

    var.set('ham')

    # 現在, 在把 'var' 的值設成 'ham' 後:
    print(var.get())  # 'ham'
    print(ctx[var])  # 'ham'

# 'main' 函式對 'var' 所做的任何變更都會
# 包含在 'ctx 裡：.
ctx.run(main)

# 'main()' 函式是在 'ctx' 情境中執行，
# 所以對 'var' 的變更會保存在 'ctx' 中：
print(ctx[var])  # 'ham'

# 但是，在 'ctx' 外, 'var' 的值仍然是 '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{3652}
@deffn {方法} copy ()

回傳情境物件的淺層複本（shallow copy）。
@end deffn


@deffn {Describe} var in context

如果`情境'裡面有 `var' 的值，則回傳 @code{True}，否則回傳 @code{False}。
@end deffn


@deffn {Describe} context[var]

回傳 `var' @ref{17f0,,ContextVar} 變數的值。如果該變數並沒有在情境物件中設定，則會引發 @ref{5df,,KeyError} 錯誤。
@end deffn

@geindex get() (contextvars.Context 的方法)
@anchor{library/contextvars contextvars Context get}@anchor{3653}
@deffn {方法} get (var[, default])

如果 `var' 的值在情境物件中，則回傳 `var' 的值。否則回傳 `default'。如果沒有 `default' 值，則回傳 @code{None}。
@end deffn


@deffn {Describe} iter(context)

回傳儲存於情境物件中變數的疊代器。
@end deffn


@deffn {Describe} len(proxy)

回傳情境物件中的變數個數。
@end deffn

@geindex keys() (contextvars.Context 的方法)
@anchor{library/contextvars contextvars Context keys}@anchor{3654}
@deffn {方法} keys ()

回傳情境物件中所有變數的串列。
@end deffn

@geindex values() (contextvars.Context 的方法)
@anchor{library/contextvars contextvars Context values}@anchor{3655}
@deffn {方法} values ()

回傳情境物件中所有變數的值的串列。
@end deffn

@geindex items() (contextvars.Context 的方法)
@anchor{library/contextvars contextvars Context items}@anchor{3656}
@deffn {方法} items ()

回傳情境物件中所有變數與其值的 2-元組（2-tuples）的串列。
@end deffn
@end deffn

@node 對 asyncio 的支援,,手動情境管理,contextvars --- 情境變數
@anchor{library/contextvars asyncio-support}@anchor{3657}
@subsubsection 對 asyncio 的支援


@ref{b,,asyncio} 原生支援情境變數，不需任何額外設定。 舉例來說，以下是一個簡單的 echo 伺服器，使用情境變數讓遠端用戶端的位址在處理該用戶端的任務中可用：

@example
import asyncio
import contextvars

client_addr_var = contextvars.ContextVar('client_addr')

def render_goodbye():
    # 即使不把目前處理中的用戶端（client）傳入此函式
    # 仍可取得其位址

    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)

    # 在任何我們呼叫的程式碼中，都可以
    # 呼叫 '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())

# 你可以使用 telnet 或 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)

以下是支援部份上述服務的模組：

@node _thread --- 低階執行緒 API,,contextvars --- 情境變數,並行執行 Concurrent Execution
@anchor{library/_thread doc}@anchor{3658}@anchor{library/_thread module-_thread}@anchor{2}@anchor{library/_thread thread-low-level-threading-api}@anchor{3659}@anchor{library/_thread translation-repo}@anchor{365a}
@subsection @code{_thread} --- 低階執行緒 API


@geindex module; _thread

@geindex light-weight processes（輕量級行程）
@geindex processes@comma{} light-weight（行程，輕量級）
@geindex binary semaphores（二進位號誌）
@geindex semaphores@comma{} binary（號誌，二進位）


__________________________________________________________________


這個模組提供了與多個執行緒（也稱為:dfn:@cite{輕量級行程} 或 :dfn: @cite{任務}）一起工作的低階原始物件 --- 多個控制執行緒分享其全域資料空間。為了處理同步問題，也提供了簡單的鎖 (lock) 機制（也稱為:dfn:@cite{互斥鎖} 或 `二進位號誌'）。 @ref{f3,,threading} 模組提供了一個建立在這個模組之上的更易於使用和高階的執行緒 API。

@geindex pthreads
@geindex threads（執行緒）;POSIX


在 3.7 版的變更: 這個模組之前是可選擇性的，但現在已經是可用的。


這個模組定義了以下的常數和函式：

@geindex error
@anchor{library/_thread thread error}@anchor{365b}
@deffn {例外} _thread.error

在執行緒相關的錯誤發生時引發。


在 3.3 版的變更: 現在是內建例外 @ref{244,,RuntimeError} 的別名。

@end deffn

@geindex LockType (於 _thread 模組中)
@anchor{library/_thread thread LockType}@anchor{365c}
@deffn {資料} _thread.LockType

這是鎖物件的型別。
@end deffn

@geindex start_new_thread() (於 _thread 模組中)
@anchor{library/_thread thread start_new_thread}@anchor{4af}
@deffn {函式} _thread.start_new_thread (function, args[, kwargs])

開始一個新的執行緒並回傳其識別字 (identifier) 。該執行緒執行帶有引數列表 `args*（必須是一個 tuple（元組））的函式 *function'。可選的 `kwargs' 引數指定一個關鍵字引數的字典。

當函式回傳時，執行緒會靜默退出。

當函式因未處理的例外終止時，將呼叫 @ref{502,,sys.unraisablehook()} 來處理該例外。鉤子引數的 `object' 屬性是 `function'。預設情況下，會列印堆疊跟蹤，然後執行緒退出（但其他執行緒會繼續運行）。

當函式引發 @ref{f37,,SystemExit} 例外時，它會被靜默忽略。

引發一個 @ref{1b70,,稽核事件} @code{_thread.start_new_thread}，帶有引數 @code{function}、@code{args} 和 @code{kwargs}。


在 3.8 版的變更: 現在使用 @ref{502,,sys.unraisablehook()} 來處理未處理的例外。

@end deffn

@geindex interrupt_main() (於 _thread 模組中)
@anchor{library/_thread thread interrupt_main}@anchor{a3d}
@deffn {函式} _thread.interrupt_main (signum=signal.SIGINT, /)

模擬一個訊號到達主執行緒的效果。執行緒可以使用此函式來中斷主執行緒，但無法保證中斷會立即發生。

如果提供了 `signum'，則模擬指定的訊號編號。如果未提供 `signum'，則模擬 @ref{253,,signal.SIGINT} 訊號。

如果給定的訊號在 Python 中未被處理（即設置為 @ref{1ad7,,signal.SIG_DFL} 或 @ref{1ad6,,signal.SIG_IGN}），此函式不做任何操作。


在 3.10 版的變更: 新增了 `signum' 引數以自定義訊號編號。


@cartouche
@quotation 備註 
這並不會發出對應的訊號，而是安排呼叫相應的處理器（如果存在的話）。如果你想真正發出訊號，請使用 @ref{1ab9,,signal.raise_signal()}。
@end quotation
@end cartouche
@end deffn

@geindex exit() (於 _thread 模組中)
@anchor{library/_thread thread exit}@anchor{365d}
@deffn {函式} _thread.exit ()

引發 @ref{f37,,SystemExit} 例外。當未捕獲時，將導致執行緒靜默退出。
@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{365e}
@deffn {函式} _thread.allocate_lock ()

回傳一個新的鎖物件。鎖物件的方法如下所述。初始狀況下鎖是解鎖狀態。
@end deffn

@geindex get_ident() (於 _thread 模組中)
@anchor{library/_thread thread get_ident}@anchor{365f}
@deffn {函式} _thread.get_ident ()

回傳目前執行緒的「執行緒識別字」。這是一個非零的整數。它的值沒有直接的含義；它被用作一個 magic cookie，例如用於索引特定於執行緒的資料的字典。當執行緒退出並建立另一個執行緒時，執行緒識別字可能會被重複使用。
@end deffn

@geindex get_native_id() (於 _thread 模組中)
@anchor{library/_thread thread get_native_id}@anchor{3660}
@deffn {函式} _thread.get_native_id ()

回傳由核心 (kernel) 分配的目前執行緒的原生整數執行緒 ID。這是一個非負整數。它的值可用於在整個系統中唯一標識此特定執行緒（直到執行緒終止後，該值可能被操作系統重新使用）。

@ref{2006,,可用性}: Windows, FreeBSD, Linux, macOS, OpenBSD, NetBSD, AIX, DragonFlyBSD, GNU/kFreeBSD.


在 3.8 版被加入.



在 3.13 版的變更: 新增了對 GNU/kFreeBSD 的支援。

@end deffn

@geindex stack_size() (於 _thread 模組中)
@anchor{library/_thread thread stack_size}@anchor{3661}
@deffn {函式} _thread.stack_size ([size])

回傳在建立新執行緒時使用的執行緒堆疊大小。可選的 `size' 引數指定了隨後建立的執行緒要使用的堆疊大小，必須是 0（使用平台或配置的預設值）或至少 32,768（32 KiB）的正整數值。如果未指定 `size'，則使用 0。如果不支持更改執行緒堆疊大小，則會引發 @ref{244,,RuntimeError} 錯誤。如果指定的堆疊大小無效，則會引發 @ref{2eb,,ValueError} 錯誤，並且堆疊大小不會被修改。目前，32 KiB 是保證直譯器本身具有足夠堆疊空間所支持的最小堆疊大小值。請注意，某些平台對於堆疊大小的值可能有特定的限制，例如要求最小堆疊大小 > 32 KiB，或要求按系統記憶體頁面大小的倍數進行分配。應參考平台文件以取得更多訊息（4 KiB 頁面是比較普遍的；在缺乏更具體訊息的情況下，建議使用 4096 的倍數作為堆疊大小）。

@ref{2006,,可用性}: Windows, pthreads.

Unix 平台上支援 POSIX 執行緒。
@end deffn

@geindex TIMEOUT_MAX (於 _thread 模組中)
@anchor{library/_thread thread TIMEOUT_MAX}@anchor{3662}
@deffn {資料} _thread.TIMEOUT_MAX

@ref{8a0,,Lock.acquire} 的 `timeout' 參數所允許的最大值。指定超過此值的 timeout 將引發 @ref{a78,,OverflowError} 錯誤。


在 3.2 版被加入.

@end deffn

鎖物件具有以下方法：

@geindex acquire() (_thread.lock 的方法)
@anchor{library/_thread thread lock acquire}@anchor{3663}
@deffn {方法} lock.acquire (blocking=True, timeout=-1)

沒有任何可選引數時，此方法無條件地取得鎖，必要時會等待直到被另一個執行緒釋放（一次只能有一個執行緒取得鎖 --- 這正是鎖存在的原因）。

如果存在 `blocking' 引數，則根據其值執行操作：如果為 False，只有在可以立即獲取鎖而無需等待的情況下才取得鎖，而如果為 True，則像上面一樣無條件地取得鎖。

如果存在浮點數的 `timeout' 引數且為正值，則它指定了在回傳之前的最大等待時間（以秒為單位）。如果 `timeout' 引數為負值，則表示等待時間會無限期地等待。如果 `blocking' 為 False，則你無法指定 `timeout'。

如果成功取得鎖，回傳值為 @code{True}，否則為 @code{False}。


在 3.2 版的變更: 新增的 `timeout' 參數。



在 3.2 版的變更: 現在取得鎖的操作可以被 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{3664}
@deffn {方法} lock.release ()

釋放鎖。鎖必須先前被取得，但不一定是由同一個執行緒取得的。
@end deffn

@geindex locked() (_thread.lock 的方法)
@anchor{library/_thread thread lock locked}@anchor{3665}
@deffn {方法} lock.locked ()

回傳鎖的狀態：如果鎖已被某個執行緒取得，則回傳 @code{True}，否則回傳 @code{False}。
@end deffn

除了這些方法之外，鎖物件還可以透過 @ref{186,,with} 語句來使用，例如：

@example
import _thread

a_lock = _thread.allocate_lock()

with a_lock:
    print("a_lock 在執行這裡時被鎖定")
@end example

`注意事項：'

@geindex module（模組）;signal（訊號）


@itemize *

@item 
中斷總會跳到主執行緒（該執行緒將接收 @ref{bbc,,KeyboardInterrupt} 例外。）

@item 
呼叫 @ref{277,,sys.exit()} 函式或引發 @ref{f37,,SystemExit} 例外等同於呼叫 @ref{365d,,_thread.exit()} 函式。

@item 
當主執行緒退出時，其他執行緒是否保留是由系統決定的。在大多數系統上，它們將被終止，而不會執行 @ref{8f0,,try} ... @ref{1b0,,finally} 子句或執行物件的解構函式。
@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 網路與行程間通訊,網際網路資料處理,並行執行 Concurrent Execution,Python 標準函式庫 Standard Library
@anchor{library/ipc doc}@anchor{3666}@anchor{library/ipc ipc}@anchor{3667}@anchor{library/ipc networking-and-interprocess-communication}@anchor{3668}@anchor{library/ipc translation-repo}@anchor{3669}
@section 網路與行程間通訊


本章所描述的模組提供了網路和行程間通訊的機制。

某些模組僅適用於同一台機器上的兩個行程，例如 @ref{cb,,signal} 和 @ref{94,,mmap}。其他模組則支援網路通訊協定，可供兩個或多個行程跨機器進行通訊。

本章所述的模組列表如下：

@menu
* asyncio: asyncio --- 非同步 I/O. 非同步 I/O
* socket — 低階網路介面:: 
* ssl: ssl --- socket 物件的 TLS/SSL 包裝器. socket 物件的 TLS/SSL 包裝器
* select: select --- 等待 I/O 完成. 等待 I/O 完成
* selectors: selectors --- 高階 I/O 多工. 高階 I/O 多工
* signal: signal --- 設定非同步事件的處理函式. 設定非同步事件的處理函式
* mmap: mmap --- 記憶體對映檔案的支援. 記憶體對映檔案的支援

@end menu

@node asyncio --- 非同步 I/O,socket — 低階網路介面,,網路與行程間通訊
@anchor{library/asyncio doc}@anchor{366a}@anchor{library/asyncio asyncio-asynchronous-i-o}@anchor{366b}@anchor{library/asyncio module-asyncio}@anchor{b}
@subsection @code{asyncio} --- 非同步 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 是讓使用者以 `async/await' 語法來編寫`並行 (concurrent)' 程式碼的函式庫 (library)。

asyncio 作為多個 Python 非同步框架的基礎，在高效能網路與網頁伺服器、資料庫連線函式庫、分散式任務佇列等服務都可以看得到它。

asyncio 往往是個建構 IO 密集型與高階層`結構化'網路程式碼的完美選擇。


@subsubheading 也參考



@table @asis

@item @ref{366c,,asyncio 的概念性總覽}

asyncio 的基本原理說明。
@end table


asyncio 提供了一系列`高階' API：


@itemize *

@item 
並行地@ref{366d,,運行 Python 協程 (coroutine)} 並擁有完整控制權；

@item 
執行@ref{366e,,網路 IO 與 IPC}；

@item 
控制@ref{366f,,子行程 (subprocess)}；

@item 
透過@ref{3670,,佇列 (queue)} 分配任務；

@item 
@ref{3671,,同步}並行程式碼；
@end itemize

此外，還有一些給`函式庫與框架 (framework) 開發者'的`低階' API：


@itemize *

@item 
建立與管理 @ref{f71,,event loops（事件迴圈）}，它提供了能被用於@ref{3672,,網路}、執行@ref{3673,,子行程}、處理@ref{3674,,作業系統訊號}等任務的非同步 API；

@item 
使用 @ref{3675,,transports（asyncio 底層傳輸相關類別）}來實作高效能協定；

@item 
透過 async/await 語法來@ref{3676,,橋接}基於回呼 (callback-based) 的函式庫與程式碼。
@end itemize

@c include for modules that don't work on WASM

@ref{2006,,可用性}: not WASI.

此模組在 WebAssembly 平台上不起作用或無法使用。更多資訊請參閱 @ref{1a99,,WebAssembly 平台}。
@anchor{library/asyncio asyncio-cli}@anchor{3677}
@subsubheading asyncio REPL


你能在 @ref{48c,,REPL} 中對一個 @code{asyncio} 的並行情境 (context) 進行實驗：

@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

產生一個 @ref{1b70,,稽核事件} @code{cpython.run_stdin} 且沒有引數。


在 3.12.5 版的變更: (也包括 3.11.10、3.10.15、3.9.20 及 3.8.20）發出稽核事件。



在 3.13 版的變更: 可能的話使用 PyREPL，在這種情況下 
@geindex PYTHONSTARTUP
@geindex 環境變數; PYTHONSTARTUP
@ref{1b8,,PYTHONSTARTUP} 也會被執行。發出稽核事件。


@c We use the "rubric" directive here to avoid creating
@c the "Reference" subsection in the TOC.

@subsubheading 參閱


@menu
* Runners (執行器): Runners 執行器. 
* 協程與任務:: 
* 串流:: 
* 同步化原始物件 (Synchronization Primitives): 同步化原始物件 Synchronization Primitives. 
* 子行程:: 
* 佇列 (Queues): 佇列 Queues. 
* 例外: 例外<14>. 
* Call Graph Introspection:: 
* 事件迴圈:: 
* Futures:: 
* 傳輸與協定:: 
* Policies:: 
* 平臺支援:: 
* 擴充:: 
* 高階 API 索引:: 
* 低階 API 索引:: 
* 使用 asyncio 開發:: 

@end menu

@node Runners 執行器,協程與任務,,asyncio --- 非同步 I/O
@anchor{library/asyncio-runner doc}@anchor{3678}@anchor{library/asyncio-runner runners}@anchor{3679}
@subsubsection Runners (執行器)


`原始碼：'Lib/asyncio/runners.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/asyncio/runners.py}

這個章節概述用於執行 asyncio 程式碼的高階 asyncio 原始物件。

他們是基於一個@ref{f71,,事件迴圈}，目的是為了簡化常見且廣泛運用場景的非同步程式碼。

@menu
* 運行一個 asyncio 程式:: 
* Runner context manager:: 
* Handling Keyboard Interruption:: 

@end menu

@node 運行一個 asyncio 程式,Runner context manager,,Runners 執行器
@anchor{library/asyncio-runner running-an-asyncio-program}@anchor{367a}
@subsubsection 運行一個 asyncio 程式


@geindex run() (於 asyncio 模組中)
@anchor{library/asyncio-runner asyncio run}@anchor{2f2}
@deffn {函式} asyncio.run (coro, *, debug=None, loop_factory=None)

在 asyncio 事件迴圈中執行 `coro' 並回傳結果。

該引數可以是任何可等待物件 (awaitable object)。

這個函式負責運行被傳入的可等待物件、管理 asyncio 的事件迴圈、`終結非同步產生器'以及關閉執行器。

當另一個非同步事件迴圈在同一執行緒中執行時，無法呼叫此函式。

如果 `debug' 為 @code{True}，事件迴圈會以除錯模式執行。@code{False} 則會關閉除錯模式。@code{None} 則會優先使用@ref{2001,,除錯模式}的全域設定。

如果 `loop_factory' 不為 @code{None}，它會被用於建立一個新的事件迴圈；否則會改用 @ref{367b,,asyncio.new_event_loop()}。迴圈會在最後關閉。這個函式應該要作為asyncio 程式的主要進入點，且理想上僅會被呼叫一次。推薦使用 `loop_factory' 來設定事件迴圈時而不是使用 policies（政策）。傳遞 @ref{19b9,,asyncio.EventLoop} 可以讓 asyncio 在沒有政策系統的情況下運行。

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
async def main():
    await asyncio.sleep(1)
    print('hello')

asyncio.run(main())
@end example


在 3.7 版被加入.



在 3.9 版的變更: Updated to use @ref{adb,,loop.shutdown_default_executor()}.



在 3.10 版的變更: `debug' is @code{None} by default to respect the global debug mode settings.



在 3.12 版的變更: 新增 `loop_factory' 參數。



在 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,運行一個 asyncio 程式,Runners 執行器
@anchor{library/asyncio-runner runner-context-manager}@anchor{367c}
@subsubsection Runner context manager


@geindex Runner (asyncio 中的類別)
@anchor{library/asyncio-runner asyncio Runner}@anchor{2f4}
@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{f71,,event loop} and @ref{177,,contextvars.Context}.

如果 `debug' 為 @code{True}，事件迴圈會以除錯模式執行。@code{False} 則會關閉除錯模式。@code{None} 則會優先使用@ref{2001,,除錯模式}的全域設定。

`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{367b,,asyncio.new_event_loop()} is used and set as
current event loop with @ref{1a84,,asyncio.set_event_loop()} if `loop_factory' is @code{None}.

Basically, @ref{2f2,,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


在 3.11 版被加入.


@geindex run() (asyncio.Runner 的方法)
@anchor{library/asyncio-runner asyncio Runner run}@anchor{18b4}
@deffn {方法} run (coro, *, context=None)

Execute `coro' in the embedded event loop.

該引數可以是任何可等待物件 (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{177,,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.

當另一個非同步事件迴圈在同一執行緒中執行時，無法呼叫此函式。


在 3.14 版的變更: `coro' can be any awaitable object.

@end deffn

@geindex close() (asyncio.Runner 的方法)
@anchor{library/asyncio-runner asyncio Runner close}@anchor{367d}
@deffn {方法} close ()

Close the runner.

Finalize asynchronous generators, shutdown default executor, close the event loop
and release embedded @ref{177,,contextvars.Context}.
@end deffn

@geindex get_loop() (asyncio.Runner 的方法)
@anchor{library/asyncio-runner asyncio Runner get_loop}@anchor{367e}
@deffn {方法} get_loop ()

Return the event loop associated with the runner instance.
@end deffn

@cartouche
@quotation 備註 
@ref{2f4,,Runner} uses the lazy initialization strategy, its constructor doesn't
initialize underlying low-level structures.

Embedded `loop' and `context' are created at the @ref{186,,with} body entering
or the first call of @ref{2f2,,run()} or @ref{367e,,get_loop()}.
@end quotation
@end cartouche
@end deffn

@node Handling Keyboard Interruption,,Runner context manager,Runners 執行器
@anchor{library/asyncio-runner handling-keyboard-interruption}@anchor{367f}
@subsubsection Handling Keyboard Interruption



在 3.11 版被加入.


When @ref{253,,signal.SIGINT} is raised by @code{Ctrl}-@code{C}, @ref{bbc,,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{253,,signal.SIGINT} as follows:


@enumerate 

@item 
@ref{18b4,,asyncio.Runner.run()} installs a custom @ref{253,,signal.SIGINT} handler before
any user code is executed and removes it when exiting from the function.

@item 
The @ref{2f4,,Runner} creates the main task for the passed coroutine for its
execution.

@item 
When @ref{253,,signal.SIGINT} is raised by @code{Ctrl}-@code{C}, the custom signal handler
cancels the main task by calling @ref{4ce,,asyncio.Task.cancel()} which raises
@ref{4cf,,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{18b4,,asyncio.Runner.run()} raises
@ref{bbc,,KeyboardInterrupt}.

@item 
A user could write a tight loop which cannot be interrupted by
@ref{4ce,,asyncio.Task.cancel()}, in which case the second following @code{Ctrl}-@code{C}
immediately raises the @ref{bbc,,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 協程與任務,串流,Runners 執行器,asyncio --- 非同步 I/O
@anchor{library/asyncio-task doc}@anchor{3680}@anchor{library/asyncio-task coroutines-and-tasks}@anchor{3681}@anchor{library/asyncio-task translation-repo}@anchor{3682}
@subsubsection 協程與任務


This section outlines high-level asyncio APIs to work with coroutines
and Tasks.

@menu
* 協程: 協程<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 物件:: 

@end menu

@node 協程<3>,Awaitables,,協程與任務
@anchor{library/asyncio-task coroutine}@anchor{366d}@anchor{library/asyncio-task coroutines}@anchor{3683}
@subsubsection 協程


`原始碼：'Lib/asyncio/coroutines.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/asyncio/coroutines.py}


__________________________________________________________________


@ref{6b2,,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{2f2,,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

預期的輸出：

@example
started at 17:13:52
hello
world
finished at 17:13:55
@end example

@item 
The @ref{1c9,,asyncio.create_task()} function to run coroutines
concurrently as asyncio @ref{1c7,,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{4cc,,asyncio.TaskGroup} class provides a more modern
alternative to @ref{1c9,,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.


在 3.11 版被加入: @ref{4cc,,asyncio.TaskGroup}。

@end itemize

@node Awaitables,Creating Tasks,協程<3>,協程與任務
@anchor{library/asyncio-task asyncio-awaitables}@anchor{3684}@anchor{library/asyncio-task awaitables}@anchor{3685}
@subsubsection Awaitables


We say that an object is an `awaitable' object if it can be used
in an @ref{18d,,await} expression.  Many asyncio APIs are designed to
accept awaitables.

There are three main types of `awaitable' objects:
`coroutines', `Tasks', and `Futures'.

@subsubheading 協程


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{7e6,,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{1c9,,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{dc1,,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{add,,loop.run_in_executor()}.

@node Creating Tasks,Task Cancellation,Awaitables,協程與任務
@anchor{library/asyncio-task creating-tasks}@anchor{3686}
@subsubsection Creating Tasks


`原始碼：'Lib/asyncio/tasks.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/asyncio/tasks.py}


__________________________________________________________________


@geindex create_task() (於 asyncio 模組中)
@anchor{library/asyncio-task asyncio create_task}@anchor{1c9}
@deffn {函式} asyncio.create_task (coro, *, name=None, context=None, eager_start=None, **kwargs)

Wrap the `coro' @ref{366d,,coroutine} into a @ref{1c7,,Task}
and schedule its execution.  Return the Task object.

The full function signature is largely the same as that of the
@ref{1c7,,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{177,,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{1c8,,loop.set_task_factory()} will be used.

The task is executed in the loop returned by @ref{cf9,,get_running_loop()},
@ref{244,,RuntimeError} is raised if there is no running loop in
current thread.

@cartouche
@quotation 備註 
@ref{1cb,,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


在 3.7 版被加入.



在 3.8 版的變更: 新增 `name' 參數。



在 3.11 版的變更: 新增 `context' 參數。



在 3.14 版的變更: Added the `eager_start' parameter by passing on all `kwargs'.

@end deffn

@node Task Cancellation,Task Groups,Creating Tasks,協程與任務
@anchor{library/asyncio-task task-cancellation}@anchor{3687}
@subsubsection Task Cancellation


Tasks can easily and safely be cancelled.
When a task is cancelled, @ref{4cf,,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{4cf,,asyncio.CancelledError}
is explicitly caught, it should generally be propagated when
clean-up is complete. @ref{4cf,,asyncio.CancelledError} directly subclasses
@ref{7d0,,BaseException} so most code will not need to be aware of it.

The asyncio components that enable structured concurrency, like
@ref{4cc,,asyncio.TaskGroup} and @ref{80d,,asyncio.timeout()},
are implemented using cancellation internally and might misbehave if
a coroutine swallows @ref{4cf,,asyncio.CancelledError}. Similarly, user code
should not generally call @ref{4d1,,uncancel}.
However, in cases when suppressing @ref{4cf,,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,協程與任務
@anchor{library/asyncio-task task-groups}@anchor{3688}@anchor{library/asyncio-task taskgroups}@anchor{3689}
@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{4cc}
@deffn {類別} asyncio.TaskGroup

An @ref{80b,,asynchronous context manager}
holding a group of tasks.
Tasks can be added to the group using @ref{1c9,,create_task()}.
All tasks are awaited when the context manager exits.


在 3.11 版被加入.


@geindex create_task() (asyncio.TaskGroup 的方法)
@anchor{library/asyncio-task asyncio TaskGroup create_task}@anchor{1cb}
@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{1c9,,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{1ca,,loop.create_task()}

@end deffn
@end deffn

範例：

@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).
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{4cf,,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{18f8,,__aexit__()} hasn't been called yet),
the task directly containing the @code{async with} statement is also cancelled.
The resulting @ref{4cf,,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{4cf,,asyncio.CancelledError},
those exceptions are combined in an
@ref{4cd,,ExceptionGroup} or @ref{560,,BaseExceptionGroup}
(as appropriate; see their documentation)
which is then raised.

Two base exceptions are treated specially:
If any task fails with @ref{bbc,,KeyboardInterrupt} or @ref{f37,,SystemExit},
the task group still cancels the remaining tasks and waits for them,
but then the initial @ref{bbc,,KeyboardInterrupt} or @ref{f37,,SystemExit}
is re-raised instead of @ref{4cd,,ExceptionGroup} or @ref{560,,BaseExceptionGroup}.

If the body of the @code{async with} statement exits with an exception
(so @ref{18f8,,__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 @ref{18f8,,__aexit__()},
unless it is @ref{4cf,,asyncio.CancelledError},
is also included in the exception group.
The same special case is made for
@ref{bbc,,KeyboardInterrupt} and @ref{f37,,SystemExit} as in the previous paragraph.

Task groups are careful not to mix up the internal cancellation used to
"wake up" their @ref{18f8,,__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{4cd,,ExceptionGroup}, it will call the parent task's
@ref{4ce,,cancel()} method. This ensures that a
@ref{4cf,,asyncio.CancelledError} will be raised at the next
@ref{18d,,await}, so the cancellation is not lost.

Task groups preserve the cancellation count
reported by @ref{4d0,,asyncio.Task.cancelling()}.


在 3.13 版的變更: Improved handling of simultaneous internal and external cancellations
and correct preservation of cancellation counts.


@menu
* Terminating a Task Group:: 

@end menu

@node Terminating a Task Group,,,Task Groups
@anchor{library/asyncio-task terminating-a-task-group}@anchor{368a}
@subsubsection Terminating a Task Group


While terminating a task group is not natively supported by the standard
library, termination can be achieved by adding an exception-raising task
to the task group and ignoring the raised exception:

@example
import asyncio
from asyncio import TaskGroup

class TerminateTaskGroup(Exception):
    """Exception raised to terminate a task group."""

async def force_terminate_task_group():
    """Used to force termination of a task group."""
    raise TerminateTaskGroup()

async def job(task_id, sleep_time):
    print(f'Task @{task_id@}: start')
    await asyncio.sleep(sleep_time)
    print(f'Task @{task_id@}: done')

async def main():
    try:
        async with TaskGroup() as group:
            # spawn some tasks
            group.create_task(job(1, 0.5))
            group.create_task(job(2, 1.5))
            # sleep for 1 second
            await asyncio.sleep(1)
            # add an exception-raising task to force the group to terminate
            group.create_task(force_terminate_task_group())
    except* TerminateTaskGroup:
        pass

asyncio.run(main())
@end example

預期的輸出：

@example
Task 1: start
Task 2: start
Task 1: done
@end example

@node Sleeping,Running Tasks Concurrently,Task Groups,協程與任務
@anchor{library/asyncio-task sleeping}@anchor{368b}
@subsubsection Sleeping


@geindex sleep() (於 asyncio 模組中)
@anchor{library/asyncio-task asyncio sleep}@anchor{c5b}
@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{368c}
Example of coroutine displaying the current date every second
for 5 seconds:

@example
import asyncio
import datetime

async def display_date():
    loop = asyncio.get_running_loop()
    end_time = loop.time() + 5.0
    while True:
        print(datetime.datetime.now())
        if (loop.time() + 1.0) >= end_time:
            break
        await asyncio.sleep(1)

asyncio.run(display_date())
@end example


在 3.10 版的變更: 移除 `loop' 參數。



在 3.13 版的變更: 如果 `delay' 是 @ref{86c,,nan}，則引發 @ref{2eb,,ValueError}。

@end deffn

@node Running Tasks Concurrently,Eager Task Factory,Sleeping,協程與任務
@anchor{library/asyncio-task running-tasks-concurrently}@anchor{368d}
@subsubsection Running Tasks Concurrently


@geindex gather() (於 asyncio 模組中)
@anchor{library/asyncio-task asyncio gather}@anchor{80c}
@deffn {函式} awaitable asyncio.gather (*aws, return_exceptions=False)

Run @ref{3684,,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{4cf,,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{4cc,,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{368e}
範例：

@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 版的變更: 移除 `loop' 參數。



在 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,協程與任務
@anchor{library/asyncio-task eager-task-factory}@anchor{368f}@anchor{library/asyncio-task id2}@anchor{3690}
@subsubsection Eager Task Factory


@geindex eager_task_factory() (於 asyncio 模組中)
@anchor{library/asyncio-task asyncio eager_task_factory}@anchor{69b}
@deffn {函式} asyncio.eager_task_factory (loop, coro, *, name=None, context=None)

A task factory for eager task execution.

When using this factory (via @ref{1c8,,loop.set_task_factory(asyncio.eager_task_factory)}),
coroutines begin execution synchronously during @ref{1c7,,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


在 3.12 版被加入.

@end deffn

@geindex create_eager_task_factory() (於 asyncio 模組中)
@anchor{library/asyncio-task asyncio create_eager_task_factory}@anchor{69c}
@deffn {函式} asyncio.create_eager_task_factory (custom_task_constructor)

Create an eager task factory, similar to @ref{69b,,eager_task_factory()},
using the provided `custom_task_constructor' when creating a new task instead
of the default @ref{1c7,,Task}.

`custom_task_constructor' must be a `callable' with the signature matching
the signature of @ref{1c7,,Task.__init__}.
The callable must return a @ref{1c7,,asyncio.Task}-compatible object.

This function returns a `callable' intended to be used as a task factory of an
event loop via @ref{1c8,,loop.set_task_factory(factory)}).


在 3.12 版被加入.

@end deffn

@node Shielding From Cancellation,Timeouts,Eager Task Factory,協程與任務
@anchor{library/asyncio-task shielding-from-cancellation}@anchor{3691}
@subsubsection Shielding From Cancellation


@geindex shield() (於 asyncio 模組中)
@anchor{library/asyncio-task asyncio shield}@anchor{c5c}
@deffn {函式} awaitable asyncio.shield (aw)

Protect an @ref{3684,,awaitable object}
from being @ref{4ce,,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{4cf,,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 版的變更: 移除 `loop' 參數。



在 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,協程與任務
@anchor{library/asyncio-task timeouts}@anchor{3692}
@subsubsection Timeouts


@geindex timeout() (於 asyncio 模組中)
@anchor{library/asyncio-task asyncio timeout}@anchor{80d}
@deffn {函式} asyncio.timeout (delay)

Return an @ref{80b,,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{3693,,Timeout.reschedule()}.

範例：

@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{4cf,,asyncio.CancelledError} internally, transforming it
into a @ref{a2f,,TimeoutError} which can be caught and handled.

@cartouche
@quotation 備註 
The @ref{80d,,asyncio.timeout()} context manager is what transforms
the @ref{4cf,,asyncio.CancelledError} into a @ref{a2f,,TimeoutError},
which means the @ref{a2f,,TimeoutError} can only be caught
`outside' of the context manager.
@end quotation
@end cartouche

Example of catching @ref{a2f,,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{80d,,asyncio.timeout()} can be
rescheduled to a different deadline and inspected.

@geindex Timeout (asyncio 中的類別)
@anchor{library/asyncio-task asyncio Timeout}@anchor{1991}
@deffn {類別} asyncio.Timeout (when)

An @ref{80b,,asynchronous context manager}
for cancelling overdue coroutines.

@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{3694}
@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{3693}
@deffn {方法} reschedule (when: float | None)

Reschedule the timeout.
@end deffn

@geindex expired() (asyncio.Timeout 的方法)
@anchor{library/asyncio-task asyncio Timeout expired}@anchor{3695}
@deffn {方法} expired () -> bool

Return whether the context manager has exceeded its deadline
(expired).
@end deffn
@end quotation
@end deffn

範例：

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


在 3.11 版被加入.

@end deffn

@geindex timeout_at() (於 asyncio 模組中)
@anchor{library/asyncio-task asyncio timeout_at}@anchor{1ad8}
@deffn {函式} asyncio.timeout_at (when)

Similar to @ref{80d,,asyncio.timeout()}, except `when' is the absolute time
to stop waiting, or @code{None}.

範例：

@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


在 3.11 版被加入.

@end deffn

@geindex wait_for() (於 asyncio 模組中)
@anchor{library/asyncio-task asyncio wait_for}@anchor{80e}
@deffn {函式} async asyncio.wait_for (aw, timeout)

Wait for the `aw' @ref{3684,,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{a2f,,TimeoutError}.

To avoid the task @ref{4ce,,cancellation},
wrap it in @ref{c5c,,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{3696}
範例：

@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{a2f,,TimeoutError} immediately.



在 3.10 版的變更: 移除 `loop' 參數。



在 3.11 版的變更: 引發 @ref{a2f,,TimeoutError} 而不是 @ref{1a00,,asyncio.TimeoutError}。

@end deffn

@node Waiting Primitives,Running in Threads,Timeouts,協程與任務
@anchor{library/asyncio-task waiting-primitives}@anchor{3697}
@subsubsection Waiting Primitives


@geindex wait() (於 asyncio 模組中)
@anchor{library/asyncio-task asyncio wait}@anchor{6a0}
@deffn {函式} async asyncio.wait (aws, *, timeout=None, return_when=ALL_COMPLETED)

Run @ref{dc1,,Future} and @ref{1c7,,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)}.

用法：

@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{a2f,,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

常數

@tab

描述

@item

@geindex FIRST_COMPLETED (於 asyncio 模組中)
@anchor{library/asyncio-task asyncio FIRST_COMPLETED}@anchor{3698}
@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{3699}
@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{369a,,ALL_COMPLETED}.

@item

@geindex ALL_COMPLETED (於 asyncio 模組中)
@anchor{library/asyncio-task asyncio ALL_COMPLETED}@anchor{369a}
@deffn {資料} asyncio.ALL_COMPLETED
@end deffn

@tab

The function will return when all futures finish or are cancelled.

@end multitable


Unlike @ref{80e,,wait_for()}, @code{wait()} does not cancel the
futures when a timeout occurs.


在 3.10 版的變更: 移除 `loop' 參數。



在 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{4c1}
@deffn {函式} asyncio.as_completed (aws, *, timeout=None)

Run @ref{3684,,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{4c2,,asynchronous iterator} or a plain @ref{4c3,,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{a2f,,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 版的變更: 移除 `loop' 參數。



在 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{4c2,,asynchronous iterator}
or as a plain @ref{4c3,,iterator} (previously it was only a plain iterator).

@end deffn

@node Running in Threads,Scheduling From Other Threads,Waiting Primitives,協程與任務
@anchor{library/asyncio-task running-in-threads}@anchor{369b}
@subsubsection Running in Threads


@geindex to_thread() (於 asyncio 模組中)
@anchor{library/asyncio-task asyncio to_thread}@anchor{adc}
@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{177,,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{164,,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


在 3.9 版被加入.

@end deffn

@node Scheduling From Other Threads,Introspection,Running in Threads,協程與任務
@anchor{library/asyncio-task scheduling-from-other-threads}@anchor{369c}
@subsubsection Scheduling From Other Threads


@geindex run_coroutine_threadsafe() (於 asyncio 模組中)
@anchor{library/asyncio-task asyncio run_coroutine_threadsafe}@anchor{a79}
@deffn {函式} asyncio.run_coroutine_threadsafe (coro, loop)

Submit a coroutine to the given event loop.  Thread-safe.

Return a @ref{13b3,,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{369d,,concurrency and multithreading}
section of the documentation.

Unlike other asyncio functions this function requires the `loop'
argument to be passed explicitly.


在 3.5.1 版被加入.

@end deffn

@node Introspection,Task 物件,Scheduling From Other Threads,協程與任務
@anchor{library/asyncio-task introspection}@anchor{369e}
@subsubsection Introspection


@geindex current_task() (於 asyncio 模組中)
@anchor{library/asyncio-task asyncio current_task}@anchor{69e}
@deffn {函式} asyncio.current_task (loop=None)

Return the currently running @ref{1c7,,Task} instance, or @code{None} if
no task is running.

If `loop' is @code{None} @ref{cf9,,get_running_loop()} is used to get
the current loop.


在 3.7 版被加入.

@end deffn

@geindex all_tasks() (於 asyncio 模組中)
@anchor{library/asyncio-task asyncio all_tasks}@anchor{b46}
@deffn {函式} asyncio.all_tasks (loop=None)

Return a set of not yet finished @ref{1c7,,Task} objects run by
the loop.

If `loop' is @code{None}, @ref{cf9,,get_running_loop()} is used for getting
current loop.


在 3.7 版被加入.

@end deffn

@geindex iscoroutine() (於 asyncio 模組中)
@anchor{library/asyncio-task asyncio iscoroutine}@anchor{69f}
@deffn {函式} asyncio.iscoroutine (obj)

Return @code{True} if `obj' is a coroutine object.


在 3.4 版被加入.

@end deffn

@node Task 物件,,Introspection,協程與任務
@anchor{library/asyncio-task asyncio-task-obj}@anchor{369f}@anchor{library/asyncio-task task-object}@anchor{36a0}
@subsubsection Task 物件


@geindex Task (asyncio 中的類別)
@anchor{library/asyncio-task asyncio Task}@anchor{1c7}
@deffn {類別} asyncio.Task (coro, *, loop=None, name=None, context=None, eager_start=False)

A @ref{dc1,,Future-like} object that runs a Python
@ref{366d,,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{1c9,,asyncio.create_task()} function to create
Tasks, or the low-level @ref{1ca,,loop.create_task()} or
@ref{e6c,,ensure_future()} functions.  Manual instantiation of Tasks
is discouraged.

To cancel a running Task use the @ref{4ce,,cancel()} method.  Calling it
will cause the Task to throw a @ref{4cf,,CancelledError} exception into
the wrapped coroutine.  If a coroutine is awaiting on a Future
object during cancellation, the Future object will be cancelled.

@ref{36a1,,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{4cf,,CancelledError} exception and was actually
cancelled.

@ref{1c7,,asyncio.Task} inherits from @ref{dc1,,Future} all of its
APIs except @ref{36a2,,Future.set_result()} and
@ref{e73,,Future.set_exception()}.

An optional keyword-only `context' argument allows specifying a
custom @ref{177,,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{1c7,,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 版的變更: 新增對 @ref{28,,contextvars} 模組的支援。



在 3.8 版的變更: 新增 `name' 參數。



在 3.10 版之後被棄用: Deprecation warning is emitted if `loop' is not specified
and there is no running event loop.



在 3.11 版的變更: 新增 `context' 參數。



在 3.12 版的變更: 新增 `eager_start' 參數。


@geindex done() (asyncio.Task 的方法)
@anchor{library/asyncio-task asyncio Task done}@anchor{36a3}
@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{36a4}
@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{4cf,,CancelledError} exception.

If the Task's result isn't yet available, this method raises
an @ref{36a5,,InvalidStateError} exception.
@end deffn

@geindex exception() (asyncio.Task 的方法)
@anchor{library/asyncio-task asyncio Task exception}@anchor{36a6}
@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{4cf,,CancelledError} exception.

If the Task isn't `done' yet, this method raises an
@ref{36a5,,InvalidStateError} exception.
@end deffn

@geindex add_done_callback() (asyncio.Task 的方法)
@anchor{library/asyncio-task asyncio Task add_done_callback}@anchor{36a7}
@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{cf6,,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{36a8}
@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{187c,,Future.remove_done_callback()}
for more details.
@end deffn

@geindex get_stack() (asyncio.Task 的方法)
@anchor{library/asyncio-task asyncio Task get_stack}@anchor{36a9}
@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{1a1b}
@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{36a9,,get_stack()}.

The `limit' argument is passed to @ref{36a9,,get_stack()} directly.

The `file' argument is an I/O stream to which the output
is written; by default output is written to @ref{cc4,,sys.stdout}.
@end deffn

@geindex get_coro() (asyncio.Task 的方法)
@anchor{library/asyncio-task asyncio Task get_coro}@anchor{bc6}
@deffn {方法} get_coro ()

Return the coroutine object wrapped by the @ref{1c7,,Task}.

@cartouche
@quotation 備註 
This will return @code{None} for Tasks which have already
completed eagerly. See the @ref{368f,,Eager Task Factory}.
@end quotation
@end cartouche


在 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{36aa}
@deffn {方法} get_context ()

Return the @ref{177,,contextvars.Context} object
associated with the task.


在 3.12 版被加入.

@end deffn

@geindex get_name() (asyncio.Task 的方法)
@anchor{library/asyncio-task asyncio Task get_name}@anchor{bc8}
@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.


在 3.8 版被加入.

@end deffn

@geindex set_name() (asyncio.Task 的方法)
@anchor{library/asyncio-task asyncio Task set_name}@anchor{bc7}
@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{1c1,,repr()} output of a task object.


在 3.8 版被加入.

@end deffn

@geindex cancel() (asyncio.Task 的方法)
@anchor{library/asyncio-task asyncio Task cancel}@anchor{4ce}
@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{4cf,,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{8f0,,try} ...
... @code{except CancelledError} ... @ref{1b0,,finally} block.
Therefore, unlike @ref{1acf,,Future.cancel()}, @ref{4ce,,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{4d1,,Task.uncancel()} in addition
to catching the exception.


在 3.9 版的變更: 新增 `msg' 參數。



在 3.11 版的變更: The @code{msg} parameter is propagated from cancelled task to its awaiter.

@anchor{library/asyncio-task asyncio-example-task-cancel}@anchor{36ab}
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{36a1}
@deffn {方法} cancelled ()

Return @code{True} if the Task is `cancelled'.

The Task is `cancelled' when the cancellation was requested with
@ref{4ce,,cancel()} and the wrapped coroutine propagated the
@ref{4cf,,CancelledError} exception thrown into it.
@end deffn

@geindex uncancel() (asyncio.Task 的方法)
@anchor{library/asyncio-task asyncio Task uncancel}@anchor{4d1}
@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 @ref{4d1,,uncancel()} are ineffective.


在 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{3689,,Task Groups} and @ref{80d,,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 @ref{4d1,,uncancel()}.  @ref{4cc,,TaskGroup} context managers use
@ref{4d1,,uncancel()} in a similar fashion.

If end-user code is, for some reason, suppressing cancellation by
catching @ref{4cf,,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{4ce,,cancel()} call had arranged
for @ref{4cf,,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{4d0}
@deffn {方法} cancelling ()

Return the number of pending cancellation requests to this Task, i.e.,
the number of calls to @ref{4ce,,cancel()} less the number of
@ref{4d1,,uncancel()} calls.

Note that if this number is greater than zero but the Task is
still executing, @ref{36a1,,cancelled()} will still return @code{False}.
This is because this number can be lowered by calling @ref{4d1,,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{4d1,,uncancel()} for more details.


在 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 串流,同步化原始物件 Synchronization Primitives,協程與任務,asyncio --- 非同步 I/O
@anchor{library/asyncio-stream doc}@anchor{36ac}@anchor{library/asyncio-stream asyncio-streams}@anchor{366e}@anchor{library/asyncio-stream streams}@anchor{36ad}@anchor{library/asyncio-stream translation-repo}@anchor{36ae}
@subsubsection 串流


`原始碼：'Lib/asyncio/streams.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/asyncio/streams.py}


__________________________________________________________________


串流是支援 async/await (async/await-ready) 的高階原始物件 (high-level primitive)，用於處理網路連線。串流不需要使用回呼 (callback) 或低階協定和傳輸 (transport) 就能夠傳送和接收資料。
@anchor{library/asyncio-stream asyncio-example-stream}@anchor{36af}
這是一個使用 asyncio 串流編寫的 TCP echo 用戶端範例：

@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

另請參閱下方 @ref{36b0,,Examples} 段落。

@subsubheading 串流函式


下面的高階 asyncio 函式可以用來建立和處理串流：

@geindex open_connection() (於 asyncio 模組中)
@anchor{library/asyncio-stream asyncio open_connection}@anchor{d06}
@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)

建立網路連線並回傳一對 @code{(reader, writer)} 物件。

回傳的 `reader' 和 `writer' 物件是 @ref{1b7b,,StreamReader} 和 @ref{19c2,,StreamWriter} 類別的實例。

`limit' 指定了回傳的 @ref{1b7b,,StreamReader} 實例所使用的緩衝區 (buffer) 大小限制。`limit' 預設為 64 KiB。

其餘的引數會直接傳遞到 @ref{811,,loop.create_connection()}。

@cartouche
@quotation 備註 
The `sock' argument transfers ownership of the socket to the
@ref{19c2,,StreamWriter} created. To close the socket, call its
@ref{36b1,,close()} method.
@end quotation
@end cartouche


在 3.7 版的變更: 新增 `ssl_handshake_timeout' 參數。



在 3.8 版的變更: 新增 `happy_eyeballs_delay' 和 `interleave' 參數。



在 3.10 版的變更: 移除 `loop' 參數。



在 3.11 版的變更: 新增 `ssl_shutdown_timeout' 參數。

@end deffn

@geindex start_server() (於 asyncio 模組中)
@anchor{library/asyncio-stream asyncio start_server}@anchor{d07}
@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)

啟動 socket 伺服器。

當一個新的用戶端連線被建立時，回呼函式 `client_connected_cb' 就會被呼叫。該函式會接收到一對引數 @code{(reader, writer)}，分別為 @ref{1b7b,,StreamReader} 和 @ref{19c2,,StreamWriter} 的實例。

`client_connected_cb' 既可以是普通的可呼叫物件 (callable)，也可以是一個@ref{366d,,協程函式}；如果它是一個協程函式，它將自動作為 @ref{1c7,,Task} 來被排程。

`limit' 指定了回傳的 @ref{1b7b,,StreamReader} 實例所使用的緩衝區 (buffer) 大小限制。`limit' 預設為 64 KiB。

剩下的引數將會直接傳遞給 @ref{d01,,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{36b2,,close()} method.
@end quotation
@end cartouche


在 3.7 版的變更: 新增 `ssl_handshake_timeout' 與 `start_serving' 參數。



在 3.10 版的變更: 移除 `loop' 參數。



在 3.11 版的變更: 新增 `ssl_shutdown_timeout' 參數。



在 3.13 版的變更: 新增 `keep_alive' 參數。

@end deffn

@subsubheading Unix Sockets


@geindex open_unix_connection() (於 asyncio 模組中)
@anchor{library/asyncio-stream asyncio open_unix_connection}@anchor{36b3}
@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)

建立一個 Unix socket 連線並回傳一對 @code{(reader, writer)}。

與 @ref{d06,,open_connection()} 相似，但是是操作 Unix sockets。

另請參閱 @ref{36b4,,loop.create_unix_connection()} 文件。

@cartouche
@quotation 備註 
The `sock' argument transfers ownership of the socket to the
@ref{19c2,,StreamWriter} created. To close the socket, call its
@ref{36b1,,close()} method.
@end quotation
@end cartouche

@ref{2006,,可用性}: Unix.


在 3.7 版的變更: 新增 `ssl_handshake_timeout' 參數。`path' 參數現在可以是個 @ref{59b,,path-like object}



在 3.10 版的變更: 移除 `loop' 參數。



在 3.11 版的變更: 新增 `ssl_shutdown_timeout' 參數。

@end deffn

@geindex start_unix_server() (於 asyncio 模組中)
@anchor{library/asyncio-stream asyncio start_unix_server}@anchor{36b5}
@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)

啟動一個 Unix socket 伺服器。

與 @ref{d07,,start_server()} 相似，但會是操作 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.

另請參閱 @ref{4c5,,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{36b2,,close()} method.
@end quotation
@end cartouche

@ref{2006,,可用性}: Unix.


在 3.7 版的變更: 新增 `ssl_handshake_timeout' 與 `start_serving' 參數。`path' 參數現在可以是個 @ref{59b,,path-like object}。



在 3.10 版的變更: 移除 `loop' 參數。



在 3.11 版的變更: 新增 `ssl_shutdown_timeout' 參數。



在 3.13 版的變更: 新增 `cleanup_socket' 參數。

@end deffn

@menu
* StreamReader:: 
* StreamWriter:: 
* 範例: 範例<21>. 

@end menu

@node StreamReader,StreamWriter,,串流
@anchor{library/asyncio-stream streamreader}@anchor{36b6}
@subsubsection StreamReader


@geindex StreamReader (asyncio 中的類別)
@anchor{library/asyncio-stream asyncio StreamReader}@anchor{1b7b}
@deffn {類別} asyncio.StreamReader

表示一個有提供 API 來從 IO 串流中讀取資料的 reader 物件。作為一個 @ref{f6f,,asynchronous iterable}，此物件支援 @ref{c98,,async for} 陳述式。

不建議直接實例化 `StreamReader' 物件；使用 @ref{d06,,open_connection()} 和 @ref{d07,,start_server()} 會是較好的做法。

@geindex feed_eof() (asyncio.StreamReader 的方法)
@anchor{library/asyncio-stream asyncio StreamReader feed_eof}@anchor{36b7}
@deffn {方法} feed_eof ()

Acknowledge the EOF.
@end deffn

@geindex read() (asyncio.StreamReader 的方法)
@anchor{library/asyncio-stream asyncio StreamReader read}@anchor{36b8}
@deffn {方法} async read (n=-1)

從串流中讀取至多 `n' 個位元組的資料。

如果沒有設定 `n' 或是被設為 @code{-1}，則會持續讀取直到 EOF，然後回傳所有讀取到的 @ref{192,,bytes}。讀取到 EOF 且內部緩衝區是空的，則回傳一個空的 @code{bytes} 物件。

如果 `n' 為 @code{0}，則立即回傳一個空的 @code{bytes} 物件。

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{36b9}
@deffn {方法} async readline ()

讀取一行，其中"行"指的是以 @code{\n} 結尾的位元組序列。

如果讀取到 EOF 而沒有找到 @code{\n}，該方法會回傳部分的已讀取資料。

如果讀取到 EOF 且內部緩衝區是空的，則回傳一個空的 @code{bytes} 物件。
@end deffn

@geindex readexactly() (asyncio.StreamReader 的方法)
@anchor{library/asyncio-stream asyncio StreamReader readexactly}@anchor{e71}
@deffn {方法} async readexactly (n)

讀取剛好 `n' 個位元組。

如果在讀取完 `n' 個位元組之前讀取到 EOF，則會引發 @ref{1bd4,,IncompleteReadError}。使用 @ref{36ba,,IncompleteReadError.partial} 屬性來取得串流結束前已讀取的部分資料。
@end deffn

@geindex readuntil() (asyncio.StreamReader 的方法)
@anchor{library/asyncio-stream asyncio StreamReader readuntil}@anchor{4cb}
@deffn {方法} async readuntil (separator=b'\n')

從串流中持續讀取資料直到出現 `separator'。

成功後，資料和 separator（分隔符號）會從內部緩衝區中刪除（或者說是被消費掉 (consumed)）。回傳的資料在末尾會有一個 separator。

如果讀取的資料量超過了設定的串流限制，將會引發 @ref{36bb,,LimitOverrunError} 例外，資料將被留在內部緩衝區中，並可以再次被讀取。

如果在完整的 separator 被找到之前就讀取到 EOF，則會引發 @ref{1bd4,,IncompleteReadError} 例外，且內部緩衝區會被重置。@ref{36ba,,IncompleteReadError.partial} 屬性可能包含一部分的 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{36bb,,LimitOverrunError},
the shortest possible separator is considered to be the one that
matched.


在 3.5.2 版被加入.



在 3.13 版的變更: 現在 `separator' 參數可以是一個分隔符號的 @ref{60c,,tuple}。

@end deffn

@geindex at_eof() (asyncio.StreamReader 的方法)
@anchor{library/asyncio-stream asyncio StreamReader at_eof}@anchor{36bc}
@deffn {方法} at_eof ()

如果緩衝區是空的且 @ref{36b7,,feed_eof()} 曾被呼叫則回傳 @code{True}。
@end deffn
@end deffn

@node StreamWriter,範例<21>,StreamReader,串流
@anchor{library/asyncio-stream streamwriter}@anchor{36bd}
@subsubsection StreamWriter


@geindex StreamWriter (asyncio 中的類別)
@anchor{library/asyncio-stream asyncio StreamWriter}@anchor{19c2}
@deffn {類別} asyncio.StreamWriter

表示一個有提供 API 來將資料寫入 IO 串流的 writer 物件。

不建議直接實例化 `StreamWriter' 物件；使用 @ref{d06,,open_connection()} 和 @ref{d07,,start_server()} 會是較好的做法。

@geindex write() (asyncio.StreamWriter 的方法)
@anchor{library/asyncio-stream asyncio StreamWriter write}@anchor{36be}
@deffn {方法} write (data)

此方法會嘗試立即將 `data' 寫入到底層的 socket。如果失敗，資料會被放到內部寫入緩衝中排隊等待 (queue)，直到它可被發送。

The `data' buffer should be a bytes, bytearray, or C-contiguous one-dimensional
memoryview object.

此方法應當與 @code{drain()} 方法一起使用：

@example
stream.write(data)
await stream.drain()
@end example
@end deffn

@geindex writelines() (asyncio.StreamWriter 的方法)
@anchor{library/asyncio-stream asyncio StreamWriter writelines}@anchor{36bf}
@deffn {方法} writelines (data)

此方法會立即嘗試將一個位元組 list（或任何可疊代物件 (iterable)）寫入到底層的 socket。如果失敗，資料會被放到內部寫入緩衝中排隊等待，直到它可被發送。

此方法應當與 @code{drain()} 方法一起使用：

@example
stream.writelines(lines)
await stream.drain()
@end example
@end deffn

@geindex close() (asyncio.StreamWriter 的方法)
@anchor{library/asyncio-stream asyncio StreamWriter close}@anchor{36b1}
@deffn {方法} close ()

此方法會關閉串流以及底層的 socket。

此方法應與 @code{wait_closed()} 方法一起使用，但並非強制：

@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{36c0}
@deffn {方法} can_write_eof ()

如果底層的傳輸支援 @ref{36c1,,write_eof()} 方法就回傳 @code{True}，否則回傳 @code{False}。
@end deffn

@geindex write_eof() (asyncio.StreamWriter 的方法)
@anchor{library/asyncio-stream asyncio StreamWriter write_eof}@anchor{36c1}
@deffn {方法} write_eof ()

在已緩衝的寫入資料被清理 (flush) 後關閉串流的寫入端。
@end deffn

@geindex transport (asyncio.StreamWriter 的屬性)
@anchor{library/asyncio-stream asyncio StreamWriter transport}@anchor{36c2}
@deffn {屬性} transport

回傳底層的 asyncio 傳輸。
@end deffn

@geindex get_extra_info() (asyncio.StreamWriter 的方法)
@anchor{library/asyncio-stream asyncio StreamWriter get_extra_info}@anchor{36c3}
@deffn {方法} get_extra_info (name, default=None)

存取可選的傳輸資訊；詳情請見 @ref{c8a,,BaseTransport.get_extra_info()}。
@end deffn

@geindex drain() (asyncio.StreamWriter 的方法)
@anchor{library/asyncio-stream asyncio StreamWriter drain}@anchor{1a6a}
@deffn {方法} async drain ()

等待直到可以繼續寫入到串流。範例：

@example
writer.write(data)
await writer.drain()
@end example

這是一個與底層 IO 寫入緩衝區互動的流程控制方法。當緩衝區大小達到最高標記位 (high watermark) 時，`drain()' 會阻塞直到緩衝區大小減少至最低標記位 (low watermark) 以便繼續寫入。當沒有要等待的資料時，@ref{1a6a,,drain()} 會立即回傳。
@end deffn

@geindex start_tls() (asyncio.StreamWriter 的方法)
@anchor{library/asyncio-stream asyncio StreamWriter start_tls}@anchor{812}
@deffn {方法} async start_tls (sslcontext, *, server_hostname=None, ssl_handshake_timeout=None, ssl_shutdown_timeout=None)

將現有的基於串流的連線升級到 TLS。

參數：


@itemize *

@item 
`sslcontext'：一個 @ref{355,,SSLContext} 的已配置實例。

@item 
`server_hostname'：設定或覆寫將會被目標伺服器憑證比對的主機名稱。

@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


在 3.11 版被加入.



在 3.12 版的變更: 新增 `ssl_shutdown_timeout' 參數。

@end deffn

@geindex is_closing() (asyncio.StreamWriter 的方法)
@anchor{library/asyncio-stream asyncio StreamWriter is_closing}@anchor{cfb}
@deffn {方法} is_closing ()

如果串流已被關閉或正在被關閉則回傳 @code{True}。


在 3.7 版被加入.

@end deffn

@geindex wait_closed() (asyncio.StreamWriter 的方法)
@anchor{library/asyncio-stream asyncio StreamWriter wait_closed}@anchor{cfa}
@deffn {方法} async wait_closed ()

等待直到串流被關閉。

應當在 @ref{36b1,,close()} 之後才被呼叫，這會持續等待直到底層的連線被關閉，以確保在這之前（例如在程式退出前）所有資料都已經被清空


在 3.7 版被加入.

@end deffn
@end deffn

@node 範例<21>,,StreamWriter,串流
@anchor{library/asyncio-stream examples}@anchor{36b0}
@subsubsection 範例


@menu
* 使用串流的 TCP echo 用戶端:: 
* 使用串流的 TCP echo 伺服器:: 
* 取得 HTTP 標頭:: 
* 註冊一個使用串流來等待資料的開放 socket:: 

@end menu

@node 使用串流的 TCP echo 用戶端,使用串流的 TCP echo 伺服器,,範例<21>
@anchor{library/asyncio-stream asyncio-tcp-echo-client-streams}@anchor{36c4}@anchor{library/asyncio-stream tcp-echo-client-using-streams}@anchor{36c5}
@subsubsection 使用串流的 TCP echo 用戶端


使用 @ref{d06,,asyncio.open_connection()} 函式的 TCP echo 用戶端：

@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 也參考


使用低階 @ref{811,,loop.create_connection()} 方法的 @ref{36c6,,TCP echo 用戶端協定}範例。


@node 使用串流的 TCP echo 伺服器,取得 HTTP 標頭,使用串流的 TCP echo 用戶端,範例<21>
@anchor{library/asyncio-stream asyncio-tcp-echo-server-streams}@anchor{36c7}@anchor{library/asyncio-stream tcp-echo-server-using-streams}@anchor{36c8}
@subsubsection 使用串流的 TCP echo 伺服器


TCP echo 伺服器使用 @ref{d07,,asyncio.start_server()} 函式：

@example
import asyncio

async def handle_echo(reader, writer):
    data = await reader.read(100)
    message = data.decode()
    addr = writer.get_extra_info('peername')

    print(f"Received @{message!r@} from @{addr!r@}")

    print(f"Send: @{message!r@}")
    writer.write(data)
    await writer.drain()

    print("Close the connection")
    writer.close()
    await writer.wait_closed()

async def main():
    server = await asyncio.start_server(
        handle_echo, '127.0.0.1', 8888)

    addrs = ', '.join(str(sock.getsockname()) for sock in server.sockets)
    print(f'Serving on @{addrs@}')

    async with server:
        await server.serve_forever()

asyncio.run(main())
@end example


@subsubheading 也參考


使用 @ref{d01,,loop.create_server()} 方法的 @ref{36c9,,TCP echo 伺服器協定} 範例。


@node 取得 HTTP 標頭,註冊一個使用串流來等待資料的開放 socket,使用串流的 TCP echo 伺服器,範例<21>
@anchor{library/asyncio-stream get-http-headers}@anchor{36ca}
@subsubsection 取得 HTTP 標頭


查詢自命令列傳入之 URL 所帶有 HTTP 標頭的簡單範例：

@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

用法：

@example
python example.py http://example.com/path/page.html
@end example

或使用 HTTPS：

@example
python example.py https://example.com/path/page.html
@end example

@node 註冊一個使用串流來等待資料的開放 socket,,取得 HTTP 標頭,範例<21>
@anchor{library/asyncio-stream asyncio-example-create-connection-streams}@anchor{36cb}@anchor{library/asyncio-stream register-an-open-socket-to-wait-for-data-using-streams}@anchor{36cc}
@subsubsection 註冊一個使用串流來等待資料的開放 socket


等待直到 socket 透過使用 @ref{d06,,open_connection()} 函式接收到資料的協程：

@example
import asyncio
import socket

async def wait_for_data():
    # Get a reference to the current event loop because
    # we want to access low-level APIs.
    loop = asyncio.get_running_loop()

    # Create a pair of connected sockets.
    rsock, wsock = socket.socketpair()

    # Register the open socket to wait for data.
    reader, writer = await asyncio.open_connection(sock=rsock)

    # Simulate the reception of data from the network
    loop.call_soon(wsock.send, 'abc'.encode())

    # Wait for data
    data = await reader.read(100)

    # Got data, we are done: close the socket
    print("Received:", data.decode())
    writer.close()
    await writer.wait_closed()

    # Close the second socket
    wsock.close()

asyncio.run(wait_for_data())
@end example


@subsubheading 也參考


在@ref{36cd,,註冊一個開啟的 socket 以等待有使用協定的資料}範例中，有使用了低階協定以及 @ref{811,,loop.create_connection()} 方法。

在@ref{36ce,,監視檔案描述器以讀取事件}範例中，有使用低階的 @ref{36cf,,loop.add_reader()} 方法來監視檔案描述器。


@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,子行程,串流,asyncio --- 非同步 I/O
@anchor{library/asyncio-sync doc}@anchor{36d0}@anchor{library/asyncio-sync asyncio-sync}@anchor{3671}@anchor{library/asyncio-sync synchronization-primitives}@anchor{36d1}@anchor{library/asyncio-sync translation-repo}@anchor{36d2}
@subsubsection 同步化原始物件 (Synchronization Primitives)


`原始碼：'Lib/asyncio/locks.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/asyncio/locks.py}


__________________________________________________________________


asyncio 的同步化原始物件被設計成和那些 @ref{f3,,threading} 模組 (module) 中的同名物件相似，但有兩個重要的限制條件：


@itemize *

@item 
asyncio 原始物件並不支援執行緒安全 (thread-safe)，因此他們不可被用於 OS 執行緒同步化（請改用 @ref{f3,,threading}）；

@item 
這些同步化原始物件的方法 (method) 並不接受 `timeout' 引數；要達成有超時 (timeout) 設定的操作請改用 @ref{80e,,asyncio.wait_for()} 函式。
@end itemize

asyncio 有以下基礎同步化原始物件：


@itemize *

@item 
@ref{c5d,,Lock}

@item 
@ref{2f3,,Event}

@item 
@ref{c5e,,Condition}

@item 
@ref{c5f,,Semaphore}

@item 
@ref{c60,,BoundedSemaphore}

@item 
@ref{80f,,Barrier}
@end itemize


__________________________________________________________________


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

@end menu

@node Lock,Event,,同步化原始物件 Synchronization Primitives
@anchor{library/asyncio-sync lock}@anchor{36d3}
@subsubsection Lock


@geindex Lock (asyncio 中的類別)
@anchor{library/asyncio-sync asyncio Lock}@anchor{c5d}
@deffn {類別} asyncio.Lock

實作了一個給 asyncio 任務 (task) 用的互斥鎖 (mutex lock)。不支援執行緒安全。

一個 asyncio 的鎖可以用來確保一個共享資源的存取權被獨佔。

使用 Lock 的推薦方式是透過 @ref{185,,async with} 陳述式：

@example
lock = asyncio.Lock()

# ... later
async with lock:
    # access shared state
@end example

這等價於：

@example
lock = asyncio.Lock()

# ... later
await lock.acquire()
try:
    # access shared state
finally:
    lock.release()
@end example


在 3.10 版的變更: 移除 @code{loop} 參數。


@geindex acquire() (asyncio.Lock 的方法)
@anchor{library/asyncio-sync asyncio Lock acquire}@anchor{36d4}
@deffn {方法} async acquire ()

獲得鎖。

此方法會持續等待直到鎖的狀態成為 `unlocked'，並將其設置為 `locked' 和回傳 @code{True}。

當多於一個的協程 (coroutine) 在 @ref{36d4,,acquire()} 中等待解鎖而被阻塞，最終只會有其中的一個被處理。

鎖的取得方式是`公平'的：被處理的協程會是最早開始等待解鎖的那一個。
@end deffn

@geindex release() (asyncio.Lock 的方法)
@anchor{library/asyncio-sync asyncio Lock release}@anchor{36d5}
@deffn {方法} release ()

釋放鎖。

如果鎖的狀態為 `locked' 則將其重置為 `unlocked' 並回傳。

如果鎖的狀態為 `unlocked' 則 @ref{244,,RuntimeError} 會被引發。
@end deffn

@geindex locked() (asyncio.Lock 的方法)
@anchor{library/asyncio-sync asyncio Lock locked}@anchor{36d6}
@deffn {方法} locked ()

如果鎖的狀態為 `locked' 則回傳 @code{True}。
@end deffn
@end deffn

@node Event,Condition,Lock,同步化原始物件 Synchronization Primitives
@anchor{library/asyncio-sync event}@anchor{36d7}
@subsubsection Event


@geindex Event (asyncio 中的類別)
@anchor{library/asyncio-sync asyncio Event}@anchor{2f3}
@deffn {類別} asyncio.Event

一個事件 (event) 物件。不支援執行緒安全。

一個 asyncio 事件可以被用於通知多個有發生某些事件於其中的 asyncio 任務。

一個 Event 物件會管理一個內部旗標 (flag)，它可以透過 @ref{36d8,,set()} 方法來被設為 `true' 並透過 @ref{36d9,,clear()} 方法來重置為 `false'。@ref{36da,,wait()} 方法會被阻塞 (block) 直到該旗標被設為 `true'。該旗標初始設置為 `false'。


在 3.10 版的變更: 移除 @code{loop} 參數。

@anchor{library/asyncio-sync asyncio-example-sync-event}@anchor{36db}
範例：

@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{36da}
@deffn {方法} async wait ()

持續等待直到事件被設置。

如果事件有被設置則立刻回傳 @code{True}。否則持續阻塞直到另一個任務呼叫 @ref{36d8,,set()}。
@end deffn

@geindex set() (asyncio.Event 的方法)
@anchor{library/asyncio-sync asyncio Event set}@anchor{36d8}
@deffn {方法} set ()

設置事件。

所有正在等待事件被設置的任務會立即被喚醒。
@end deffn

@geindex clear() (asyncio.Event 的方法)
@anchor{library/asyncio-sync asyncio Event clear}@anchor{36d9}
@deffn {方法} clear ()

清除（還原）事件。

正透過 @ref{36da,,wait()} 等待的後續 Tasks 現在會持續阻塞直到 @ref{36d8,,set()} 方法再次被呼叫。
@end deffn

@geindex is_set() (asyncio.Event 的方法)
@anchor{library/asyncio-sync asyncio Event is_set}@anchor{36dc}
@deffn {方法} is_set ()

如果事件有被設置則回傳 @code{True}。
@end deffn
@end deffn

@node Condition,Semaphore,Event,同步化原始物件 Synchronization Primitives
@anchor{library/asyncio-sync condition}@anchor{36dd}
@subsubsection Condition


@geindex Condition (asyncio 中的類別)
@anchor{library/asyncio-sync asyncio Condition}@anchor{c5e}
@deffn {類別} asyncio.Condition (lock=None)

一個條件 (codition) 物件。不支援執行緒安全。

一個 asyncio 條件原始物件可以被任務用來等待某事件發生，並獲得一個共享資源的獨佔存取權。

本質上，一個 Condition 物件會結合 @ref{2f3,,Event} 和 @ref{c5d,,Lock} 的功能。多個 Condition 物件共享一個 Lock 是有可能發生的，這能夠協調關注同一共享資源的不同狀態以取得其獨佔存取權的多個任務。

可選的 `lock' 引數必須是一個 @ref{c5d,,Lock} 物件或者為 @code{None}。如為後者則一個新的 Lock 物件會被自動建立。


在 3.10 版的變更: 移除 @code{loop} 參數。


使用 Condition 的推薦方式是透過 @ref{185,,async with} 陳述式：

@example
cond = asyncio.Condition()

# ... later
async with cond:
    await cond.wait()
@end example

這等價於：

@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{36de}
@deffn {方法} async acquire ()

取得底層的鎖。

此方法會持續等待直到底層的鎖為 `unlocked'，並將其設為 `locked' 並回傳 @code{True}。
@end deffn

@geindex notify() (asyncio.Condition 的方法)
@anchor{library/asyncio-sync asyncio Condition notify}@anchor{1946}
@deffn {方法} notify (n=1)

喚醒至多 `n' 個正在等待此條件的任務（預設為 1），如果少於 `n' 個任務則全部被喚醒。

在此方法被呼叫前必須先獲得鎖，並在之後立刻將其釋放。如果呼叫於一個 `unlocked' 的鎖則 @ref{244,,RuntimeError} 錯誤會被引發。
@end deffn

@geindex locked() (asyncio.Condition 的方法)
@anchor{library/asyncio-sync asyncio Condition locked}@anchor{36df}
@deffn {方法} locked ()

如果已取得底層的鎖則回傳 @code{True}。
@end deffn

@geindex notify_all() (asyncio.Condition 的方法)
@anchor{library/asyncio-sync asyncio Condition notify_all}@anchor{36e0}
@deffn {方法} notify_all ()

喚醒所有正在等待此條件的任務。

這個方法的行為就像 @ref{1946,,notify()}，但會喚醒所有正在等待的任務。

在此方法被呼叫前必須先獲得鎖，並在之後立刻將其釋放。如果呼叫於一個 `unlocked' 的鎖則 @ref{244,,RuntimeError} 錯誤會被引發。
@end deffn

@geindex release() (asyncio.Condition 的方法)
@anchor{library/asyncio-sync asyncio Condition release}@anchor{36e1}
@deffn {方法} release ()

釋放底層的鎖。

當叫用於一個未被解開的鎖之上時，會引發一個 @ref{244,,RuntimeError}。
@end deffn

@geindex wait() (asyncio.Condition 的方法)
@anchor{library/asyncio-sync asyncio Condition wait}@anchor{196f}
@deffn {方法} async wait ()

持續等待直到被通知 (notify)。

當此方法被呼叫時，如果呼叫它的任務還沒有取得鎖的話，@ref{244,,RuntimeError} 會被引發。

此方法會釋放底層的鎖，然後持續阻塞直到被 @ref{1946,,notify()} 或 @ref{36e0,,notify_all()} 的呼叫所喚醒。一但被喚醒，Condition 會重新取得該鎖且此方法會回傳 @code{True}。

Note that a task `may' return from this call spuriously,
which is why the caller should always re-check the state
and be prepared to @ref{196f,,wait()} again. For this reason, you may
prefer to use @ref{36e2,,wait_for()} instead.
@end deffn

@geindex wait_for() (asyncio.Condition 的方法)
@anchor{library/asyncio-sync asyncio Condition wait_for}@anchor{36e2}
@deffn {方法} async wait_for (predicate)

持續等待直到謂語 (predicate) 成為 `true'。

謂語必須是一個結果可被直譯為一個 boolean 值的可呼叫物件 (callable)。此方法會重複地 @ref{196f,,wait()} 直到謂語求值結果為 `true'。最終的值即為回傳值。
@end deffn
@end deffn

@node Semaphore,BoundedSemaphore,Condition,同步化原始物件 Synchronization Primitives
@anchor{library/asyncio-sync semaphore}@anchor{36e3}
@subsubsection Semaphore


@geindex Semaphore (asyncio 中的類別)
@anchor{library/asyncio-sync asyncio Semaphore}@anchor{c5f}
@deffn {類別} asyncio.Semaphore (value=1)

一個旗號 (semaphore) 物件。不支援執行緒安全。

一個旗號物件會管理一個內部計數器，會在每次呼叫 @ref{1970,,acquire()} 時減少一、每次呼叫 @ref{36e4,,release()} 時增加一。此計數器永遠不會少於零；當 @ref{1970,,acquire()} 發現它是零時，它會持續阻塞並等待某任務呼叫 @ref{36e4,,release()}。

可選的 `value' 引數給定了內部計數器的初始值（預設為 @code{1}）。如給定的值少於 @code{0} 則 @ref{2eb,,ValueError} 會被引發。


在 3.10 版的變更: 移除 @code{loop} 參數。


使用 Semaphore 的推薦方式是透過 @ref{185,,async with} 陳述式：

@example
sem = asyncio.Semaphore(10)

# ... later
async with sem:
    # work with shared resource
@end example

這等價於：

@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{1970}
@deffn {方法} async acquire ()

取得一個旗號。

如果內部計數器大於零，將其減一並立刻回傳 @code{True}。如果為零，則持續等待直到 @ref{36e4,,release()} 被呼叫，並回傳 @code{True}。
@end deffn

@geindex locked() (asyncio.Semaphore 的方法)
@anchor{library/asyncio-sync asyncio Semaphore locked}@anchor{36e5}
@deffn {方法} locked ()

如果旗號無法立即被取得則回傳 @code{True}。
@end deffn

@geindex release() (asyncio.Semaphore 的方法)
@anchor{library/asyncio-sync asyncio Semaphore release}@anchor{36e4}
@deffn {方法} release ()

釋放一個旗號，並為其內部的計數器數值增加一。可以把一個正在等待取得旗號的任務叫醒。

和 @ref{c60,,BoundedSemaphore} 不同，@ref{c5f,,Semaphore} 允許 @code{release()} 的呼叫次數多於 @code{acquire()}。
@end deffn
@end deffn

@node BoundedSemaphore,Barrier,Semaphore,同步化原始物件 Synchronization Primitives
@anchor{library/asyncio-sync boundedsemaphore}@anchor{36e6}
@subsubsection BoundedSemaphore


@geindex BoundedSemaphore (asyncio 中的類別)
@anchor{library/asyncio-sync asyncio BoundedSemaphore}@anchor{c60}
@deffn {類別} asyncio.BoundedSemaphore (value=1)

一個有界的旗號物件。不支援執行緒安全。

Bounded Semaphore 是 @ref{c5f,,Semaphore} 的另一版本，如果其內部的計數器數值增加至大於初始 `value' 值的話，@ref{2eb,,ValueError} 會在 @ref{36e4,,release()} 時被引發。


在 3.10 版的變更: 移除 @code{loop} 參數。

@end deffn

@node Barrier,,BoundedSemaphore,同步化原始物件 Synchronization Primitives
@anchor{library/asyncio-sync barrier}@anchor{36e7}
@subsubsection Barrier


@geindex Barrier (asyncio 中的類別)
@anchor{library/asyncio-sync asyncio Barrier}@anchor{80f}
@deffn {類別} asyncio.Barrier (parties)

一個屏障 (barrier) 物件。不支援執行緒安全。

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{36e8,,wait()} method and would be blocked until
the specified number of tasks end up waiting on @ref{36e8,,wait()}.
At that point all of the waiting tasks would unblock simultaneously.

@ref{185,,async with} can be used as an alternative to awaiting on
@ref{36e8,,wait()}.

The barrier can be reused any number of times.
@anchor{library/asyncio-sync asyncio-example-barrier}@anchor{36e9}
範例：

@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


在 3.11 版被加入.


@geindex wait() (asyncio.Barrier 的方法)
@anchor{library/asyncio-sync asyncio Barrier wait}@anchor{36e8}
@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{810,,BrokenBarrierError} exception if the
barrier is broken or reset while a task is waiting.
It could raise a @ref{4cf,,CancelledError} if a task is cancelled.
@end deffn

@geindex reset() (asyncio.Barrier 的方法)
@anchor{library/asyncio-sync asyncio Barrier reset}@anchor{36ea}
@deffn {方法} async reset ()

Return the barrier to the default, empty state.  Any tasks waiting on it
will receive the @ref{810,,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{36eb}
@deffn {方法} async abort ()

Put the barrier into a broken state.  This causes any active or future
calls to @ref{36e8,,wait()} to fail with the @ref{810,,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{36ec}
@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{36ed}
@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{36ee}
@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{810}
@deffn {例外} asyncio.BrokenBarrierError

This exception, a subclass of @ref{244,,RuntimeError}, is raised when the
@ref{80f,,Barrier} object is reset or broken.
@end deffn


__________________________________________________________________



在 3.9 版的變更: 透過 @code{await lock} 或 @code{yield from lock} 和/或 @ref{186,,with} 陳述式 (@code{with await lock}, @code{with (yield from lock)}) 來取得鎖的方式已被移除。請改用 @code{async with lock}。


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node 子行程,佇列 Queues,同步化原始物件 Synchronization Primitives,asyncio --- 非同步 I/O
@anchor{library/asyncio-subprocess doc}@anchor{36ef}@anchor{library/asyncio-subprocess asyncio-subprocess}@anchor{366f}@anchor{library/asyncio-subprocess subprocesses}@anchor{36f0}@anchor{library/asyncio-subprocess translation-repo}@anchor{36f1}
@subsubsection 子行程


`原始碼：'Lib/asyncio/subprocess.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/asyncio/subprocess.py}、Lib/asyncio/base_subprocess.py@footnote{https://github.com/python/cpython/tree/3.14/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{36f2}
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

會印出：

@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

另請參閱@ref{36f3,,Examples}。

@menu
* 建立子行程:: 
* 常數: 常數<6>. 
* 與子行程互動:: 

@end menu

@node 建立子行程,常數<6>,,子行程
@anchor{library/asyncio-subprocess creating-subprocesses}@anchor{36f4}
@subsubsection 建立子行程


@geindex create_subprocess_exec() (於 asyncio 模組中)
@anchor{library/asyncio-subprocess asyncio create_subprocess_exec}@anchor{c62}
@deffn {函式} async asyncio.create_subprocess_exec (program, *args, stdin=None, stdout=None, stderr=None, limit=None, **kwds)

建立一個子行程。

The `limit' argument sets the buffer limit for @ref{1b7b,,StreamReader}
wrappers for @ref{36f5,,stdout} and @ref{36f6,,stderr}
(if @ref{d7a,,subprocess.PIPE} is passed to `stdout' and `stderr' arguments).

回傳一個 @ref{36f7,,Process} 實例。

See the documentation of @ref{36f8,,loop.subprocess_exec()} for other
parameters.


在 3.10 版的變更: 移除了 `loop' 參數。

@end deffn

@geindex create_subprocess_shell() (於 asyncio 模組中)
@anchor{library/asyncio-subprocess asyncio create_subprocess_shell}@anchor{c63}
@deffn {函式} async asyncio.create_subprocess_shell (cmd, stdin=None, stdout=None, stderr=None, limit=None, **kwds)

執行 `cmd' shell 命令。

The `limit' argument sets the buffer limit for @ref{1b7b,,StreamReader}
wrappers for @ref{36f5,,stdout} and @ref{36f6,,stderr}
(if @ref{d7a,,subprocess.PIPE} is passed to `stdout' and `stderr' arguments).

回傳一個 @ref{36f7,,Process} 實例。

See the documentation of @ref{36f9,,loop.subprocess_shell()} for other
parameters.

@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{57c,,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 版的變更: 移除了 `loop' 參數。

@end deffn

@cartouche
@quotation 備註 
Subprocesses are available for Windows if a @ref{816,,ProactorEventLoop} is
used. See @ref{36fa,,Subprocess Support on Windows}
for details.
@end quotation
@end cartouche


@subsubheading 也參考


asyncio also has the following `low-level' APIs to work with subprocesses:
@ref{36f8,,loop.subprocess_exec()}, @ref{36f9,,loop.subprocess_shell()},
@ref{36fb,,loop.connect_read_pipe()}, @ref{36fc,,loop.connect_write_pipe()},
as well as the @ref{36fd,,Subprocess Transports}
and @ref{36fe,,Subprocess Protocols}.


@node 常數<6>,與子行程互動,建立子行程,子行程
@anchor{library/asyncio-subprocess constants}@anchor{36ff}
@subsubsection 常數


@geindex asyncio.subprocess.PIPE (內建變數)
@anchor{library/asyncio-subprocess asyncio subprocess PIPE}@anchor{3700}
@deffn {資料} asyncio.subprocess.PIPE

Can be passed to the `stdin', `stdout' or `stderr' parameters.

If `PIPE' is passed to `stdin' argument, the
@ref{3701,,Process.stdin} attribute
will point to a @ref{19c2,,StreamWriter} instance.

If `PIPE' is passed to `stdout' or `stderr' arguments, the
@ref{36f5,,Process.stdout} and
@ref{36f6,,Process.stderr}
attributes will point to @ref{1b7b,,StreamReader} instances.
@end deffn

@geindex asyncio.subprocess.STDOUT (內建變數)
@anchor{library/asyncio-subprocess asyncio subprocess STDOUT}@anchor{3702}
@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{3703}
@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{1cdc,,os.devnull} will be used for the corresponding subprocess stream.
@end deffn

@node 與子行程互動,,常數<6>,子行程
@anchor{library/asyncio-subprocess interacting-with-subprocesses}@anchor{3704}
@subsubsection 與子行程互動


Both @ref{c62,,create_subprocess_exec()} and @ref{c63,,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{36f7}
@deffn {類別} asyncio.subprocess.Process

An object that wraps OS processes created by the
@ref{c62,,create_subprocess_exec()} and @ref{c63,,create_subprocess_shell()}
functions.

This class is designed to have a similar API to the
@ref{4b2,,subprocess.Popen} class, but there are some
notable differences:


@itemize *

@item 
unlike Popen, Process instances do not have an equivalent to
the @ref{360c,,poll()} method;

@item 
the @ref{19ee,,communicate()} and
@ref{3705,,wait()} methods don't have a
`timeout' parameter: use the @ref{80e,,wait_for()} function;

@item 
the @ref{3705,,Process.wait()} method
is asynchronous, whereas @ref{edb,,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{369d,,not thread safe}.

See also the @ref{3706,,Subprocess and Threads}
section.

@geindex wait() (asyncio.subprocess.Process 的方法)
@anchor{library/asyncio-subprocess asyncio subprocess Process wait}@anchor{3705}
@deffn {方法} async wait ()

Wait for the child process to terminate.

Set and return the @ref{3707,,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{19ee,,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{19ee}
@deffn {方法} async communicate (input=None)

Interact with process:


@enumerate 

@item 
send data to `stdin' (if `input' is not @code{None});

@item 
關閉 `stdin'；

@item 
從 `stdout' 和 `stderr' 讀取資料，直到 EOF；

@item 
等待行程終止。
@end enumerate

The optional `input' argument is the data (@ref{192,,bytes} object)
that will be sent to the child process.

回傳一個 @code{(stdout_data, stderr_data)} 元組。

If either @ref{1257,,BrokenPipeError} or @ref{125a,,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{18b1}
@deffn {方法} send_signal (signal)

Sends the signal `signal' to the child process.

@cartouche
@quotation 備註 
On Windows, @ref{15d6,,SIGTERM} is an alias for @ref{3708,,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{3708}
@deffn {方法} terminate ()

Stop the child process.

On POSIX systems this method sends @ref{15d6,,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{3709}
@deffn {方法} kill ()

Kill the child process.

On POSIX systems this method sends @ref{d48,,SIGKILL} to the child
process.

On Windows this method is an alias for @ref{3708,,terminate()}.
@end deffn

@geindex stdin (asyncio.subprocess.Process 的屬性)
@anchor{library/asyncio-subprocess asyncio subprocess Process stdin}@anchor{3701}
@deffn {屬性} stdin

Standard input stream (@ref{19c2,,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{36f5}
@deffn {屬性} stdout

Standard output stream (@ref{1b7b,,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{36f6}
@deffn {屬性} stderr

Standard error stream (@ref{1b7b,,StreamReader}) or @code{None}
if the process was created with @code{stderr=None}.
@end deffn

@cartouche
@quotation 警告 
Use the @ref{19ee,,communicate()} method rather than
@ref{3701,,process.stdin.write()},
@ref{36f5,,await process.stdout.read()} or
@ref{36f6,,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{370a}
@deffn {屬性} pid

Process identification number (PID).

Note that for processes created by the @ref{c63,,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{3707}
@deffn {屬性} returncode

Return code of the process when it exits.

A @code{None} value indicates that the process has not terminated yet.

A negative value @code{-N} indicates that the child was terminated
by signal @code{N} (POSIX only).
@end deffn
@end deffn

@menu
* 子行程與執行緒:: 
* 範例: 範例<22>. 

@end menu

@node 子行程與執行緒,範例<22>,,與子行程互動
@anchor{library/asyncio-subprocess asyncio-subprocess-threads}@anchor{3706}@anchor{library/asyncio-subprocess subprocess-and-threads}@anchor{370b}
@subsubsection 子行程與執行緒


Standard asyncio event loop supports running subprocesses from different threads by
default.

On Windows subprocesses are provided by @ref{816,,ProactorEventLoop} only (default),
@ref{313,,SelectorEventLoop} has no subprocess support.

Note that alternative event loop implementations might have own limitations;
please refer to their documentation.


@subsubheading 也參考


The @ref{369d,,Concurrency and multithreading in asyncio} section.


@node 範例<22>,,子行程與執行緒,與子行程互動
@anchor{library/asyncio-subprocess examples}@anchor{36f3}
@subsubsection 範例


An example using the @ref{36f7,,Process} class to
control a subprocess and the @ref{1b7b,,StreamReader} class to read from
its standard output.
@anchor{library/asyncio-subprocess asyncio-example-create-subprocess-exec}@anchor{370c}
The subprocess is created by the @ref{c62,,create_subprocess_exec()}
function:

@example
import asyncio
import sys

async def get_date():
    code = 'import datetime; print(datetime.datetime.now())'

    # Create the subprocess; redirect the standard output
    # into a pipe.
    proc = await asyncio.create_subprocess_exec(
        sys.executable, '-c', code,
        stdout=asyncio.subprocess.PIPE)

    # Read one line of output.
    data = await proc.stdout.readline()
    line = data.decode('ascii').rstrip()

    # Wait for the subprocess exit.
    await proc.wait()
    return line

date = asyncio.run(get_date())
print(f"Current date: @{date@}")
@end example

See also the @ref{370d,,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 佇列 Queues,例外<14>,子行程,asyncio --- 非同步 I/O
@anchor{library/asyncio-queue doc}@anchor{370e}@anchor{library/asyncio-queue asyncio-queues}@anchor{3670}@anchor{library/asyncio-queue queues}@anchor{370f}@anchor{library/asyncio-queue translation-repo}@anchor{3710}
@subsubsection 佇列 (Queues)


`原始碼：'Lib/asyncio/queues.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/asyncio/queues.py}


__________________________________________________________________


asyncio 佇列被設計成與 @ref{bb,,queue} 模組類似。儘管 asyncio 佇列不支援執行緒安全 (thread-safe)，但他們是被設計來專用於 async/await 程式。

注意 asyncio 的佇列沒有 `timeout' 參數；請使用 @ref{80e,,asyncio.wait_for()} 函式來為佇列新增具有超時 (timeout) 設定的操作。

另請參閱下方 @ref{3711,,Examples}。

@menu
* Queue:: 
* Priority Queue（優先佇列）:: 
* LIFO Queue:: 
* 例外: 例外<13>. 
* 範例: 範例<23>. 

@end menu

@node Queue,Priority Queue（優先佇列）,,佇列 Queues
@anchor{library/asyncio-queue queue}@anchor{3712}
@subsubsection Queue


@geindex Queue (asyncio 中的類別)
@anchor{library/asyncio-queue asyncio Queue}@anchor{c61}
@deffn {類別} asyncio.Queue (maxsize=0)

先進先出 (FIFO) 佇列。

如果 `maxsize' 小於或等於零，則佇列大小是無限制的。如果是大於 @code{0} 的整數，則當佇列達到 `maxsize' 時，@code{await put()} 將會阻塞 (block)，直到某個元素被 @ref{3713,,get()} 取出。

不像標準函式庫中執行緒類型的 @ref{bb,,queue}，佇列的大小一直是已知的，可以透過呼叫 @ref{3714,,qsize()} 方法回傳。


在 3.10 版的變更: 移除 `loop' 參數。


這個類別是@ref{369d,,不支援執行緒安全的}。

@geindex maxsize (asyncio.Queue 的屬性)
@anchor{library/asyncio-queue asyncio Queue maxsize}@anchor{3715}
@deffn {屬性} maxsize

佇列中可存放的元素數量。
@end deffn

@geindex empty() (asyncio.Queue 的方法)
@anchor{library/asyncio-queue asyncio Queue empty}@anchor{3716}
@deffn {方法} empty ()

如果佇列為空則回傳 @code{True}，否則回傳 @code{False}。
@end deffn

@geindex full() (asyncio.Queue 的方法)
@anchor{library/asyncio-queue asyncio Queue full}@anchor{3717}
@deffn {方法} full ()

如果有 @ref{3715,,maxsize} 個條目在佇列中，則回傳 @code{True}。

如果佇列用 @code{maxsize=0} （預設）初始化，則 @ref{3717,,full()} 永遠不會回傳 @code{True}。
@end deffn

@geindex get() (asyncio.Queue 的方法)
@anchor{library/asyncio-queue asyncio Queue get}@anchor{3713}
@deffn {方法} async get ()

從佇列中刪除並回傳一個元素。如果佇列為空，則持續等待直到佇列中有元素。

Raises @ref{4c8,,QueueShutDown} if the queue has been shut down and
is empty, or if the queue has been shut down immediately.
@end deffn

@geindex get_nowait() (asyncio.Queue 的方法)
@anchor{library/asyncio-queue asyncio Queue get_nowait}@anchor{3718}
@deffn {方法} get_nowait ()

如果佇列內有值則立即回傳佇列中的元素，否則引發 @ref{3719,,QueueEmpty}。
@end deffn

@geindex join() (asyncio.Queue 的方法)
@anchor{library/asyncio-queue asyncio Queue join}@anchor{fc1}
@deffn {方法} async join ()

持續阻塞直到佇列中所有的元素都被接收和處理完畢。

當條目新增到佇列的時候，未完成任務的計數就會增加。每當一個消耗者 (consumer) 協程呼叫 @ref{fc2,,task_done()}，表示這個條目已經被取回且被它包含的所有工作都已完成，未完成任務計數就會減少。當未完成計數降到零的時候，@ref{fc1,,join()} 阻塞會被解除 (unblock)。
@end deffn

@geindex put() (asyncio.Queue 的方法)
@anchor{library/asyncio-queue asyncio Queue put}@anchor{371a}
@deffn {方法} async put (item)

將一個元素放進佇列。如果佇列滿了，在新增元素之前，會持續等待直到有空閒插槽 (free slot) 能被使用。

如果佇列已經被關閉，則引發 @ref{4c8,,QueueShutDown}。
@end deffn

@geindex put_nowait() (asyncio.Queue 的方法)
@anchor{library/asyncio-queue asyncio Queue put_nowait}@anchor{371b}
@deffn {方法} put_nowait (item)

不阻塞地將一個元素放入佇列。

如果沒有立即可用的空閒插槽，引發 @ref{371c,,QueueFull}。
@end deffn

@geindex qsize() (asyncio.Queue 的方法)
@anchor{library/asyncio-queue asyncio Queue qsize}@anchor{3714}
@deffn {方法} qsize ()

回傳佇列中的元素數量。
@end deffn

@geindex shutdown() (asyncio.Queue 的方法)
@anchor{library/asyncio-queue asyncio Queue shutdown}@anchor{4c7}
@deffn {方法} shutdown (immediate=False)

Put a @ref{c61,,Queue} instance into a shutdown mode.

The queue can no longer grow.
Future calls to @ref{371a,,put()} raise @ref{4c8,,QueueShutDown}.
Currently blocked callers of @ref{371a,,put()} will be unblocked
and will raise @ref{4c8,,QueueShutDown} in the formerly blocked thread.

If `immediate' is false (the default), the queue can be wound
down normally with @ref{3713,,get()} calls to extract tasks
that have already been loaded.

And if @ref{fc2,,task_done()} is called for each remaining task, a
pending @ref{fc1,,join()} will be unblocked normally.

Once the queue is empty, future calls to @ref{3713,,get()} will
raise @ref{4c8,,QueueShutDown}.

If `immediate' is true, the queue is terminated immediately.
The queue is drained to be completely empty.  All callers of
@ref{fc1,,join()} are unblocked regardless of the number
of unfinished tasks.  Blocked callers of @ref{3713,,get()}
are unblocked and will raise @ref{4c8,,QueueShutDown} because the
queue is empty.

Use caution when using @ref{fc1,,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.


在 3.13 版被加入.

@end deffn

@geindex task_done() (asyncio.Queue 的方法)
@anchor{library/asyncio-queue asyncio Queue task_done}@anchor{fc2}
@deffn {方法} task_done ()

表示前面一個排隊的工作項目已經完成。

由佇列消耗者使用。對於每個用於取得一個工作項目的 @ref{3713,,get()}，接續的 @ref{fc2,,task_done()} 呼叫會告訴佇列這個工作項目的處理已經完成。

如果 @ref{fc1,,join()} 目前正在阻塞，在所有項目都被處理後會解除阻塞（意味著每個以 @ref{371a,,put()} 放進佇列的條目都會收到一個 @ref{fc2,,task_done()}）。

如果被呼叫的次數多於放入佇列中的項目數量，將引發 @ref{2eb,,ValueError}。
@end deffn
@end deffn

@node Priority Queue（優先佇列）,LIFO Queue,Queue,佇列 Queues
@anchor{library/asyncio-queue priority-queue}@anchor{371d}
@subsubsection Priority Queue（優先佇列）


@geindex PriorityQueue (asyncio 中的類別)
@anchor{library/asyncio-queue asyncio PriorityQueue}@anchor{371e}
@deffn {類別} asyncio.PriorityQueue

@ref{c61,,Queue} 的變形；按優先順序取出條目 (最小的先取出)。

條目通常是 @code{(priority_number, data)} 形式的 tuple（元組）。
@end deffn

@node LIFO Queue,例外<13>,Priority Queue（優先佇列）,佇列 Queues
@anchor{library/asyncio-queue lifo-queue}@anchor{371f}
@subsubsection LIFO Queue


@geindex LifoQueue (asyncio 中的類別)
@anchor{library/asyncio-queue asyncio LifoQueue}@anchor{3720}
@deffn {類別} asyncio.LifoQueue

@ref{c61,,Queue} 的變形，先取出最近新增的條目（後進先出）。
@end deffn

@node 例外<13>,範例<23>,LIFO Queue,佇列 Queues
@anchor{library/asyncio-queue exceptions}@anchor{3721}
@subsubsection 例外


@geindex QueueEmpty
@anchor{library/asyncio-queue asyncio QueueEmpty}@anchor{3719}
@deffn {例外} asyncio.QueueEmpty

當佇列為空的時候，呼叫 @ref{3718,,get_nowait()} 方法會引發這個例外。
@end deffn

@geindex QueueFull
@anchor{library/asyncio-queue asyncio QueueFull}@anchor{371c}
@deffn {例外} asyncio.QueueFull

當佇列中條目數量已經達到它的 `maxsize' 時，呼叫 @ref{371b,,put_nowait()} 方法會引發這個例外。
@end deffn

@geindex QueueShutDown
@anchor{library/asyncio-queue asyncio QueueShutDown}@anchor{4c8}
@deffn {例外} asyncio.QueueShutDown

Exception raised when @ref{371a,,put()} or @ref{3713,,get()} is
called on a queue which has been shut down.


在 3.13 版被加入.

@end deffn

@node 範例<23>,,例外<13>,佇列 Queues
@anchor{library/asyncio-queue examples}@anchor{3711}
@subsubsection 範例

@anchor{library/asyncio-queue asyncio-example-queue-dist}@anchor{3722}
佇列能被用於多個並行任務的工作分配：

@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 例外<14>,Call Graph Introspection,佇列 Queues,asyncio --- 非同步 I/O
@anchor{library/asyncio-exceptions doc}@anchor{3723}@anchor{library/asyncio-exceptions asyncio-exceptions}@anchor{3724}@anchor{library/asyncio-exceptions exceptions}@anchor{3725}@anchor{library/asyncio-exceptions translation-repo}@anchor{3726}
@subsubsection 例外


`原始碼：'Lib/asyncio/exceptions.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/asyncio/exceptions.py}


__________________________________________________________________


@geindex TimeoutError
@anchor{library/asyncio-exceptions asyncio TimeoutError}@anchor{1a00}
@deffn {例外} asyncio.TimeoutError

@ref{a2f,,TimeoutError} 的一個已被棄用的別名，當操作已超過規定的截止時間時被引發。


在 3.11 版的變更: 此 class 是 @ref{a2f,,TimeoutError} 的一個別名。

@end deffn

@geindex CancelledError
@anchor{library/asyncio-exceptions asyncio CancelledError}@anchor{4cf}
@deffn {例外} asyncio.CancelledError

該操作已被取消。

當 asyncio Task 被取消時，可以捕獲此例外以執行客製化操作。在幾乎所有情況下，該例外必須重新被引發。


在 3.8 版的變更: @ref{4cf,,CancelledError} 現在是 @ref{7d0,,BaseException} 而非 @ref{bc4,,Exception} 的子類別。

@end deffn

@geindex InvalidStateError
@anchor{library/asyncio-exceptions asyncio InvalidStateError}@anchor{36a5}
@deffn {例外} asyncio.InvalidStateError

@ref{1c7,,Task} 或 @ref{dc1,,Future} 的無效內部狀態。

可以在像是為已設定結果值的 `Future' 物件設定結果值的情況下引發。
@end deffn

@geindex SendfileNotAvailableError
@anchor{library/asyncio-exceptions asyncio SendfileNotAvailableError}@anchor{3727}
@deffn {例外} asyncio.SendfileNotAvailableError

"sendfile" 系統呼叫不適用於給定的 socket 或檔案型別。

一個 @ref{244,,RuntimeError} 的子類別。
@end deffn

@geindex IncompleteReadError
@anchor{library/asyncio-exceptions asyncio IncompleteReadError}@anchor{1bd4}
@deffn {例外} asyncio.IncompleteReadError

請求的讀取操作未全部完成。

由 @ref{366e,,asyncio 串流 APIs} 引發。

此例外是 @ref{14da,,EOFError} 的子類別。

@geindex expected (asyncio.IncompleteReadError 的屬性)
@anchor{library/asyncio-exceptions asyncio IncompleteReadError expected}@anchor{3728}
@deffn {屬性} expected

預期的位元組總數 (@ref{19b,,int})。
@end deffn

@geindex partial (asyncio.IncompleteReadError 的屬性)
@anchor{library/asyncio-exceptions asyncio IncompleteReadError partial}@anchor{36ba}
@deffn {屬性} partial

串流結束之前讀取的 @ref{192,,bytes} 字串。
@end deffn
@end deffn

@geindex LimitOverrunError
@anchor{library/asyncio-exceptions asyncio LimitOverrunError}@anchor{36bb}
@deffn {例外} asyncio.LimitOverrunError

在查詢分隔符號 (separator) 時達到緩衝區 (buffer) 大小限制。

由 @ref{366e,,asyncio 串流 APIs} 引發。

@geindex consumed (asyncio.LimitOverrunError 的屬性)
@anchor{library/asyncio-exceptions asyncio LimitOverrunError consumed}@anchor{3729}
@deffn {屬性} consumed

要消耗的位元組總數。
@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,事件迴圈,例外<14>,asyncio --- 非同步 I/O
@anchor{library/asyncio-graph doc}@anchor{372a}@anchor{library/asyncio-graph asyncio-graph}@anchor{372b}@anchor{library/asyncio-graph call-graph-introspection}@anchor{372c}@anchor{library/asyncio-graph translation-repo}@anchor{372d}
@subsubsection Call Graph Introspection


`原始碼：'Lib/asyncio/graph.py@footnote{https://github.com/python/cpython/tree/3.14/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.


在 3.14 版被加入.


@geindex print_call_graph() (於 asyncio 模組中)
@anchor{library/asyncio-graph asyncio print_call_graph}@anchor{1cd}
@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{1c7,,Task} or @ref{dc1,,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{cc4,,sys.stdout}.

`範例：'

以下 Python 程式碼：

@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

會印出：

@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{372e}
@deffn {函式} asyncio.format_call_graph (future=None, /, *, depth=1, limit=None)

Like @ref{1cd,,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{1cc}
@deffn {函式} asyncio.capture_call_graph (future=None, /, *, depth=1, limit=None)

Capture the async call graph for the current task or the provided
@ref{1c7,,Task} or @ref{dc1,,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.

會回傳一個 @code{FutureCallGraph} 資料類別物件：


@itemize *

@item 
@code{FutureCallGraph(future, call_stack, awaited_by)}

@quotation

Where `future' is a reference to a @ref{dc1,,Future} or
a @ref{1c7,,Task} (or their subclasses.)

@code{call_stack} 是一個由 @code{FrameCallGraphEntry} 物件組成的元組。

@code{awaited_by} 是一個由 @code{FutureCallGraph} 物件組成的元組。
@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
* 低階工具函式:: 

@end menu

@node 低階工具函式,,,Call Graph Introspection
@anchor{library/asyncio-graph low-level-utility-functions}@anchor{372f}
@subsubsection 低階工具函式


To introspect an async call graph asyncio requires cooperation from
control flow structures, such as @ref{c5c,,shield()} or @ref{4cc,,TaskGroup}.
Any time an intermediate @ref{dc1,,Future} object with low-level APIs like
@ref{cf6,,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{3730}
@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{dc1,,Future} or @ref{1c7,,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{3731,,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{3731}
@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{dc1,,Future} or @ref{1c7,,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 事件迴圈,Futures,Call Graph Introspection,asyncio --- 非同步 I/O
@anchor{library/asyncio-eventloop doc}@anchor{3732}@anchor{library/asyncio-eventloop asyncio-event-loop}@anchor{f71}@anchor{library/asyncio-eventloop event-loop}@anchor{3733}@anchor{library/asyncio-eventloop translation-repo}@anchor{3734}
@subsubsection 事件迴圈


`原始碼：' Lib/asyncio/events.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/asyncio/events.py}、Lib/asyncio/base_events.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/asyncio/base_events.py}


__________________________________________________________________


@subsubheading 前言


事件迴圈是每個 asyncio 應用程式的核心。事件迴圈執行非同步任務和回呼、執行網路 IO 操作並啟動子行程。

應用程式開發人員通常應使用高階的 asyncio 函式，例如 @ref{2f2,,asyncio.run()}，並且很少需要參照事件迴圈物件或呼叫其方法。本節主要針對那些需要更細粒度控制事件迴圈行為的低階程式碼、函式庫和框架的作者。

@subsubheading 取得事件迴圈


以下的低階函式可用於取得、設置或建立事件迴圈：

@geindex get_running_loop() (於 asyncio 模組中)
@anchor{library/asyncio-eventloop asyncio get_running_loop}@anchor{cf9}
@deffn {函式} asyncio.get_running_loop ()

在目前作業系統執行緒中回傳正在運行的事件迴圈。

如果沒有運行的事件迴圈，則引發 @ref{244,,RuntimeError}。

此函式只能從協程或回呼函式中呼叫。


在 3.7 版被加入.

@end deffn

@geindex get_event_loop() (於 asyncio 模組中)
@anchor{library/asyncio-eventloop asyncio get_event_loop}@anchor{2f1}
@deffn {函式} asyncio.get_event_loop ()

取得目前的事件迴圈。

當從協程或回呼函式呼叫此函式（例如，使用 call_soon 或類似的 API 於排程呼叫），此函式將永遠回傳正在運行的事件迴圈。

如果沒有設定正在運行的事件迴圈，該函式將回傳 @code{get_event_loop_policy().get_event_loop()} 呼叫的結果。

由於此函式具有相當複雜的行為（尤其是在使用自訂事件迴圈策略時），在協程和回呼函式中，建議使用 @ref{cf9,,get_running_loop()} 函式，而不是 @ref{2f1,,get_event_loop()}。

如上所述，可以考慮使用高階的 @ref{2f2,,asyncio.run()} 函式，而不是使用這些較低階的函式手動建立和關閉事件迴圈。


在 3.14 版的變更: 如果沒有目前的事件迴圈，則引發 @ref{244,,RuntimeError}。


@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{1a84,,set_event_loop()}.
@end quotation
@end cartouche
@end deffn

@geindex set_event_loop() (於 asyncio 模組中)
@anchor{library/asyncio-eventloop asyncio set_event_loop}@anchor{1a84}
@deffn {函式} asyncio.set_event_loop (loop)

將 `loop' 設置為目前 OS 執行緒的目前事件迴圈。
@end deffn

@geindex new_event_loop() (於 asyncio 模組中)
@anchor{library/asyncio-eventloop asyncio new_event_loop}@anchor{367b}
@deffn {函式} asyncio.new_event_loop ()

建立並回傳新的事件迴圈物件。
@end deffn

請注意 @ref{2f1,,get_event_loop()}、@ref{1a84,,set_event_loop()} 和 @ref{367b,,new_event_loop()} 函式的行為可以透過@ref{3735,,設定自訂事件迴圈策略}進行調整。

@subsubheading 目錄


本頁文件包含以下章節：


@itemize *

@item 
@ref{3736,,事件迴圈方法}章節是事件迴圈 API 們的參照文件；

@item 
@ref{3737,,回呼處理}章節記錄了從排程方法（如 @ref{cf2,,loop.call_soon()} 和 @ref{cf4,,loop.call_later()}）回傳的 @ref{1d4b,,Handle} 和 @ref{1a28,,TimerHandle} 實例；

@item 
@ref{3738,,Server 物件}章節記錄了從事件迴圈方法（如 @ref{d01,,loop.create_server()}）回傳的資料型別；

@item 
@ref{3739,,事件迴圈實作}章節記錄了 @ref{313,,SelectorEventLoop} 和 @ref{816,,ProactorEventLoop} 類別；

@item 
@ref{373a,,範例}章節展示了如何使用一些事件迴圈 API。
@end itemize

@menu
* 事件迴圈方法:: 
* 回呼處理:: 
* Server 物件:: 
* 事件迴圈實作:: 
* 範例: 範例<24>. 

@end menu

@node 事件迴圈方法,回呼處理,,事件迴圈
@anchor{library/asyncio-eventloop asyncio-event-loop-methods}@anchor{373b}@anchor{library/asyncio-eventloop event-loop-methods}@anchor{3736}
@subsubsection 事件迴圈方法


事件迴圈提供以下`低階' API：

@menu
* 啟動和停止迴圈:: 
* 排程回呼函式:: 
* 排程延遲的回呼函式:: 
* 建立 Futures 和 Tasks:: 
* 打開網路連線:: 
* 建立網路伺服器:: 
* 傳輸檔案:: 
* TLS 升級:: 
* 監視檔案描述器:: 
* 直接使用 socket 物件:: 
* DNS:: 
* 使用管道:: 
* Unix 訊號:: 
* 在執行緒池或行程池中執行程式碼:: 
* 錯誤處理 API:: 
* 啟用除錯模式:: 
* 運行子行程:: 

@end menu

@node 啟動和停止迴圈,排程回呼函式,,事件迴圈方法
@anchor{library/asyncio-eventloop running-and-stopping-the-loop}@anchor{373c}
@subsubsection 啟動和停止迴圈


@geindex run_until_complete() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop asyncio loop run_until_complete}@anchor{e6d}
@deffn {方法} loop.run_until_complete (future)

運行直到 `future' （一個 @ref{dc1,,Future} 實例）完成。

如果引數是@ref{366d,,協程物件}，則它將被隱式排程為 @ref{1c7,,asyncio.Task} 運行。

回傳 Future 的結果或引發其例外。
@end deffn

@geindex run_forever() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop asyncio loop run_forever}@anchor{373d}
@deffn {方法} loop.run_forever ()

運行事件迴圈直到 @ref{e72,,stop()} 被呼叫。

如果在呼叫 @ref{373d,,run_forever()} 之前呼叫 @ref{e72,,stop()}，則迴圈將使用超時為零的方式輪詢 I/O 選擇器，運行所有回應 I/O 事件（以及已經排程的事件）的回呼，然後退出。

如果在 @ref{373d,,run_forever()} 運行時呼叫 @ref{e72,,stop()}，則迴圈將運行目前批次的回呼函式，然後退出。請注意，由回呼函式排程的新回呼在此情況下不會運行；而是在下次呼叫 @ref{373d,,run_forever()} 或 @ref{e6d,,run_until_complete()} 時運行。
@end deffn

@geindex stop() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop asyncio loop stop}@anchor{e72}
@deffn {方法} loop.stop ()

停止事件迴圈。
@end deffn

@geindex is_running() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop asyncio loop is_running}@anchor{373e}
@deffn {方法} loop.is_running ()

如果事件迴圈目前正在運行，則回傳 @code{True}。
@end deffn

@geindex is_closed() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop asyncio loop is_closed}@anchor{fbe}
@deffn {方法} loop.is_closed ()

如果事件迴圈已關閉，則回傳 @code{True}。
@end deffn

@geindex close() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop asyncio loop close}@anchor{373f}
@deffn {方法} loop.close ()

關閉事件迴圈。

不得於迴圈運行中呼叫此函式。將丟棄任何待處理的回呼。

此方法清除所有佇列並關閉執行器，但不等待執行器完成。

此方法是冪等且不可逆的。在事件迴圈關閉後不應呼叫其他方法。
@end deffn

@geindex shutdown_asyncgens() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop asyncio loop shutdown_asyncgens}@anchor{e74}
@deffn {方法} async loop.shutdown_asyncgens ()

排程所有目前打開的@ref{2342,,非同步產生器}物件使用 @ref{acc,,aclose()} 呼叫來關閉。呼叫此方法後，如果疊代新的非同步產生器，事件迴圈將發出警告。應該使用此方法可靠地完成所有已排程的非同步產生器。

請注意，使用 @ref{2f2,,asyncio.run()} 時不需要呼叫此函式。

範例：

@example
try:
    loop.run_forever()
finally:
    loop.run_until_complete(loop.shutdown_asyncgens())
    loop.close()
@end example


在 3.6 版被加入.

@end deffn

@geindex shutdown_default_executor() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop asyncio loop shutdown_default_executor}@anchor{adb}
@deffn {方法} async loop.shutdown_default_executor (timeout=None)

排程預設執行器的關閉，並等待它加入 @ref{941,,ThreadPoolExecutor} 中的所有執行緒。一旦呼叫了此方法，使用預設執行器與 @ref{add,,loop.run_in_executor()} 將引發 @ref{244,,RuntimeError}。

`timeout' 參數指定執行器完成加入所需的時間（以 @ref{196,,float} 秒為單位）。預設情況下為 @code{None}，不會限制執行器所花費的時間。

如果達到 `timeout'，將發出 @ref{4d2,,RuntimeWarning} 警告，預設執行器將立即終止，不等待其執行緒完成加入。

@cartouche
@quotation 備註 
使用 @ref{2f2,,asyncio.run()} 時請勿呼叫此方法，因為後者會自動處理預設執行器的關閉。
@end quotation
@end cartouche


在 3.9 版被加入.



在 3.12 版的變更: 加入 `timeout' 參數。

@end deffn

@node 排程回呼函式,排程延遲的回呼函式,啟動和停止迴圈,事件迴圈方法
@anchor{library/asyncio-eventloop scheduling-callbacks}@anchor{3740}
@subsubsection 排程回呼函式


@geindex call_soon() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop asyncio loop call_soon}@anchor{cf2}
@deffn {方法} loop.call_soon (callback, *args, context=None)

在事件迴圈的下一次疊代中排程以 `args' 引數呼叫 `callback' @ref{2c4f,,callback}。

回傳 @ref{1d4b,,asyncio.Handle} 的實例，稍後可以用於取消回呼函式。

回呼函式按照其註冊的順序呼叫。每個回呼函式將被呼叫恰好一次。

選用的僅限關鍵字引數 `context' 指定了要給 `callback' 執行的自定義 @ref{177,,contextvars.Context}。當未提供 `context' 時，回呼函式使用目前情境。

與 @ref{cf3,,call_soon_threadsafe()} 不同，此方法不是執行緒安全的。
@end deffn

@geindex call_soon_threadsafe() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop asyncio loop call_soon_threadsafe}@anchor{cf3}
@deffn {方法} loop.call_soon_threadsafe (callback, *args, context=None)

這是 @ref{cf2,,call_soon()} 的執行緒安全變體。當從另一個執行緒排程回呼函式時，`必須'使用此函式，因為 @ref{cf2,,call_soon()} 不是執行緒安全的。

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.

如果在已關閉的迴圈上呼叫，則引發 @ref{244,,RuntimeError}。在主應用程式關閉時，這可能發生在次要執行緒上。

請參閱文件的@ref{369d,,並行和多執行緒}部分。


在 3.7 版的變更: 新增了 `context' 僅限關鍵字參數。詳細資訊請參閱 
@geindex Python Enhancement Proposals; PEP 567
PEP 567@footnote{https://peps.python.org/pep-0567/}。

@end deffn
@anchor{library/asyncio-eventloop asyncio-pass-keywords}@anchor{3741}
@cartouche
@quotation 備註 
大多數 @ref{b,,asyncio} 排程函式不允許傳遞關鍵字引數。要傳遞關鍵字引數，請使用 @ref{217,,functools.partial()}：

@example
# 將會排程 "print("Hello", flush=True)"
loop.call_soon(
    functools.partial(print, "Hello", flush=True))
@end example

通常使用 partial 物件比使用 lambda 更方便，因為 asyncio 可以在除錯和錯誤訊息中更好地呈現 partial 物件。
@end quotation
@end cartouche

@node 排程延遲的回呼函式,建立 Futures 和 Tasks,排程回呼函式,事件迴圈方法
@anchor{library/asyncio-eventloop asyncio-delayed-calls}@anchor{3742}@anchor{library/asyncio-eventloop scheduling-delayed-callbacks}@anchor{3743}
@subsubsection 排程延遲的回呼函式


事件迴圈提供為回呼函式排程在將來某個時間點才呼叫的機制。事件迴圈使用了單調時鐘來追蹤時間。

@geindex call_later() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop asyncio loop call_later}@anchor{cf4}
@deffn {方法} loop.call_later (delay, callback, *args, context=None)

排程 `callback' 在給定的 `delay' 秒數後呼叫（可以是整數或浮點數）。

回傳 @ref{1a28,,asyncio.TimerHandle} 的實例，可用於取消回呼函式。

`callback' 將只被呼叫恰好一次。如果有兩個回呼函式被排程在完全相同的時間，則其呼叫順序是不定的。

可選的位置引數 `args' 將在呼叫回呼函式時傳遞。如果要使用關鍵字引數呼叫回呼函數，請使用 @ref{217,,functools.partial()}。

可選的僅限關鍵字 `context' 引數允許為 `callback' 指定自定義的 @ref{177,,contextvars.Context} 以提供運行。當未提供 `context' 時，將使用目前情境。

@cartouche
@quotation 備註 
For performance, callbacks scheduled with @ref{cf4,,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 版的變更: 新增了 `context' 僅限關鍵字參數。詳細資訊請參閱 
@geindex Python Enhancement Proposals; PEP 567
PEP 567@footnote{https://peps.python.org/pep-0567/}。



在 3.8 版的變更: 在 Python 3.7 及更早版本中，使用預設事件迴圈實作時，`delay' 不能超過一天。這在 Python 3.8 中已經修復。

@end deffn

@geindex call_at() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop asyncio loop call_at}@anchor{cf5}
@deffn {方法} loop.call_at (when, callback, *args, context=None)

排程 `callback' 在給定的絕對時間戳 `when' （整數或浮點數）處呼叫，使用與 @ref{3744,,loop.time()} 相同的時間參照。

此方法的行為與 @ref{cf4,,call_later()} 相同。

回傳 @ref{1a28,,asyncio.TimerHandle} 的實例，可用於取消回呼函式。

@cartouche
@quotation 備註 
For performance, callbacks scheduled with @ref{cf5,,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 版的變更: 新增了 `context' 僅限關鍵字參數。詳細資訊請參閱 
@geindex Python Enhancement Proposals; PEP 567
PEP 567@footnote{https://peps.python.org/pep-0567/}。



在 3.8 版的變更: 在 Python 3.7 及更早版本中，使用預設事件迴圈實作時，`when' 和目前時間之間的差值不能超過一天。這在 Python 3.8 中已經修復。

@end deffn

@geindex time() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop asyncio loop time}@anchor{3744}
@deffn {方法} loop.time ()

根據事件迴圈的內部單調時鐘，回傳目前時間，以 @ref{196,,float} 值表示。
@end deffn

@cartouche
@quotation 備註 

在 3.8 版的變更: 在 Python 3.7 及更早版本中，超時（相對 `delay' 或絕對 `when'）不應超過一天。這在 Python 3.8 中已經修復。

@end quotation
@end cartouche


@subsubheading 也參考


函式 @ref{c5b,,asyncio.sleep()}。


@node 建立 Futures 和 Tasks,打開網路連線,排程延遲的回呼函式,事件迴圈方法
@anchor{library/asyncio-eventloop creating-futures-and-tasks}@anchor{3745}
@subsubsection 建立 Futures 和 Tasks


@geindex create_future() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop asyncio loop create_future}@anchor{e6f}
@deffn {方法} loop.create_future ()

建立附加到事件迴圈的 @ref{dc1,,asyncio.Future} 物件。

這是在 asyncio 中建立 Futures 的首選方式。這允許第三方事件迴圈提供 Future 物件的替代實作（具有更好的性能或儀器計測表現）。


在 3.5.2 版被加入.

@end deffn

@geindex create_task() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop asyncio loop create_task}@anchor{1ca}
@deffn {方法} loop.create_task (coro, *, name=None, context=None, eager_start=None, **kwargs)

排程執行@ref{366d,,協程} `coro'。回傳 @ref{1c7,,Task} 物件。

第三方事件迴圈可以使用其自己的 @ref{1c7,,Task} 子類別以實現互操作性（interoperability）。在這種情況下，結果類型是 @ref{1c7,,Task} 的子類別。

The full function signature is largely the same as that of the
@ref{1c7,,Task} constructor (or factory) - all of the keyword arguments to
this function are passed through to that interface.

如果提供了 `name' 引數且不為 @code{None}，則將其設置為任務的名稱，使用 @ref{bc7,,Task.set_name()}。

可選的僅限關鍵字 `context' 引數允許為 `coro' 指定自定義的 @ref{177,,contextvars.Context} 以提供運行。當未提供 `context' 時，將建立目前情境的副本。

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{1c8,,loop.set_task_factory()} will be used.


在 3.8 版的變更: 加入 `name' 參數。



在 3.11 版的變更: 加入 `context' 參數。



在 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{1c8}
@deffn {方法} loop.set_task_factory (factory)

設置將由 @ref{1ca,,loop.create_task()} 使用的任務工廠。

如果 `factory' 為 @code{None}，將設置預設的任務工廠。否則，`factory' 必須是一個具有匹配簽名 @code{(loop, coro, **kwargs)} 的 `callable'，其中 `loop' 是有效事件迴圈的參照、`coro' 是一個協程物件。該可呼叫物件必須傳遞所有 `kwargs' 並回傳一個與 @ref{1c7,,asyncio.Task} 相容的物件。


在 3.13.3 版的變更: Required that all `kwargs' are passed on to @ref{1c7,,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{fc0}
@deffn {方法} loop.get_task_factory ()

回傳任務工廠，如果使用預設任務工廠則回傳 @code{None}。
@end deffn

@node 打開網路連線,建立網路伺服器,建立 Futures 和 Tasks,事件迴圈方法
@anchor{library/asyncio-eventloop opening-network-connections}@anchor{3746}
@subsubsection 打開網路連線


@geindex create_connection() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop asyncio loop create_connection}@anchor{811}
@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)

打開以 `host' 和 `port' 指定之給定地址的串流傳輸連線。

根據 `host*（或提供的 *family' 引數）的情況，socket 家族可以是 @ref{1ad2,,AF_INET} 或 @ref{1ad3,,AF_INET6}。

Socket 類型將為 @ref{14f4,,SOCK_STREAM}。

`protocol_factory' 必須是一個回傳 @ref{3747,,asyncio protocol} 實作的可呼叫函式。

此方法將嘗試在背景建立連線。成功時，它將回傳一對 @code{(transport, protocol)}。

底層操作的時間軸簡介如下：


@enumerate 

@item 
建立連線並為其建立@ref{3748,,傳輸}。

@item 
`protocol_factory' 在無引數的情況下被呼叫，並且預計回傳一個 @ref{3747,,協定} 實例。

@item 
通過呼叫其 @ref{3749,,connection_made()} 方法，將協定實例與傳輸連線在一起。

@item 
成功時回傳一個 @code{(transport, protocol)} 元組。
@end enumerate

建立的傳輸是一個依賴實作的雙向串流。

其他引數：


@itemize *

@item 
若有給定 `ssl' 且非 false，將建立 SSL/TLS 傳輸（預設建立普通 TCP 傳輸）。如果 `ssl' 為 @ref{355,,ssl.SSLContext} 物件，則使用該情境來建立傳輸；如果 `ssl' 為 @ref{e02,,True}，則使用 @ref{47a,,ssl.create_default_context()} 回傳的預設情境。


@subsubheading 也參考


@ref{374a,,SSL/TLS 安全考量}


@item 
`server_hostname' 設置或覆蓋目標伺服器憑證將匹配的主機名稱。僅在 `ssl' 不為 @code{None} 時傳遞。預設情況下，將使用 `host' 引數的值。如果 `host' 為空，則沒有預設值，必須傳遞 `server_hostname' 的值。若 `server_hostname' 為空字串，將停用主機名稱匹配（這是一個嚴重的安全風險，可能導致中間人攻擊）。

@item 
`family'、`proto'、`flags' 是可選的位址家族、協定和旗標，用於傳遞至 getaddrinfo() 進行 `host' 解析。若有給定這些應該都是相應 @ref{d1,,socket} 模組常數的整數。

@item 
若有給定，`happy_eyeballs_delay' 會啟用此連線的 Happy Eyeballs。它應該是一個浮點數，表示等待連線嘗試完成的秒數，然後在並行啟動下一次嘗試。這是 
@geindex RFC; RFC 8305
RFC 8305@footnote{https://datatracker.ietf.org/doc/html/rfc8305.html} 中定義的「連線嘗試延遲」。RFC 建議的合理預設值為 @code{0.25} 秒（250 毫秒）。

@item 
`interleave' 控制主機名稱解析為多個 IP 位址時的地址重新排序。若為 @code{0} 或未指定，將不執行重排序，並按 @ref{e09,,getaddrinfo()} 回傳的順序嘗試位址。如果指定正整數，則按地址家族交錯排列，給定的整數直譯為 
@geindex RFC; RFC 8305
RFC 8305@footnote{https://datatracker.ietf.org/doc/html/rfc8305.html} 中定義的「首個地址家族計數」。如果未指定 `happy_eyeballs_delay'，則預設值為 @code{0}，如果指定則為 @code{1}。

@item 
若有給定 `sock' 則其應為已存在且已連線的 @ref{f9c,,socket.socket} 物件，可供傳輸使用。如果提供了 `sock'，則不應指定 `host'、`port'、`family'、`proto'、`flags'、`happy_eyeballs_delay'、`interleave' 和 `local_addr' 中的任何一項。

@cartouche
@quotation 備註 
引數 `sock' 將 socket 所有權轉移給所建立的傳輸 socket，請呼叫傳輸的 @ref{374b,,close()} 方法。
@end quotation
@end cartouche

@item 
若有給定 `local_addr' 則其為一個 @code{(local_host, local_port)} 元組，用於在本地綁定 socket。將使用 @code{getaddrinfo()} 查找 `local_host' 和 `local_port'，方式類似於 `host' 和 `port'。

@item 
`ssl_handshake_timeout' （對於 TLS 連線）是等待 TLS 交握的時間，以秒為單位，在那之前若未完成則會中斷連線。如果為 @code{None} （預設值），則會等待 @code{60.0} 秒。

@item 
`ssl_shutdown_timeout' 是等待 SSL 關閉完成以前中斷連線的時間，以秒為單位。如果為 @code{None} （預設值），則會等待 @code{30.0} 秒。

@item 
`all_errors' 決定在無法建立連線時會引發哪些例外。預設情況下，只會引發單一 @code{Exception}：如果只有一個例外或所有錯誤訊息相同，則引發第一個例外，否則引發包含所有錯誤訊息的單一 @code{OSError}。當 @code{all_errors} 為 @code{True} 時，將引發包含所有例外的 @code{ExceptionGroup} （即使只有一個例外）。
@end itemize


在 3.5 版的變更: 新增 @ref{816,,ProactorEventLoop} 中的 SSL/TLS 支援。



在 3.6 版的變更: 所有 TCP 連線都預設有 @ref{d64,,socket.TCP_NODELAY} socket 選項。



在 3.7 版的變更: 增加 `ssl_handshake_timeout' 參數。



在 3.8 版的變更: 加入 `happy_eyeballs_delay' 和 `interleave' 參數。

Happy Eyeballs 演算法：雙協定堆疊主機 (Dual-Stack Hosts) 的成功。當伺服器的 IPv4 路徑和協定運作正常，但伺服器的 IPv6 路徑和協定不運作時，雙棧用戶端應用程式會比僅具 IPv4 的用戶端體驗到顯著的連線延遲。這是不希望的，因為這會導致雙棧用戶端的使用者體驗變差。本文件具體說明了減少此用戶可見延遲的演算法要求並提供了一種演算法。

更多資訊請見： @indicateurl{https://datatracker.ietf.org/doc/html/rfc6555}



在 3.11 版的變更: 增加 `ssl_shutdown_timeout' 參數。



在 3.12 版的變更: 已新增 `all_errors'。



@subsubheading 也參考


函式 @ref{d06,,open_connection()} 是高階的替代 API。它回傳一對 (@ref{1b7b,,StreamReader}, @ref{19c2,,StreamWriter}) 可直接在 async/await 程式碼中使用。

@end deffn

@geindex create_datagram_endpoint() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop asyncio loop create_datagram_endpoint}@anchor{934}
@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)

建立一個資料報連線。

Socket 家族可以是 @ref{1ad2,,AF_INET}、@ref{1ad3,,AF_INET6} 或 @ref{1ad5,,AF_UNIX}，視乎 `host'（或提供的 `family' 引數）而定。

Socket 類型將為 @ref{14f3,,SOCK_DGRAM}。

`protocol_factory' 必須是可呼叫的函式，回傳 @ref{3747,,protocol} 實作。

成功時回傳 @code{(transport, protocol)} 元組。

其他引數：


@itemize *

@item 
`local_addr'，如果提供，是一個 @code{(local_host, local_port)} 元組，用於在本地綁定 socket。`local_host' 和 `local_port' 使用 @ref{e09,,getaddrinfo()} 來查找。

@cartouche
@quotation 備註 
On Windows, when using the proactor event loop with @code{local_addr=None},
an @ref{2c0,,OSError} with @code{errno.WSAEINVAL} will be raised
when running it.
@end quotation
@end cartouche

@item 
`remote_addr'，如果提供，是一個 @code{(remote_host, remote_port)} 元組，用於將 socket 連線到遠端位址。 `remote_host' 和 `remote_port' 使用 @ref{e09,,getaddrinfo()} 來查找。

@item 
`family'、`proto' 和 `flags' 是用於傳遞給 @ref{e09,,getaddrinfo()} 以解析 `host' 的可選地址家族、協定和旗標。如果提供，這些應該都是來自相應的 @ref{d1,,socket} 模組常數的整數。

@item 
`reuse_port' 告訴核心允許將此端點綁定到與其他現有端點相同的埠，只要它們在建立時都設定了此旗標。此選項不受 Windows 和某些 Unix 系統支援。如果未定義 @code{SO_REUSEPORT} 常數，則不支援此功能。

@item 
`allow_broadcast' 告訴核心允許此端點向廣播位址發送訊息。

@item 
`sock' 可以選擇性地指定，以使用預先存在且已連線的 @ref{f9c,,socket.socket} 物件供傳輸使用。如果指定，`local_addr' 和 `remote_addr' 應省略（必須是 @ref{87e,,None}）。

@cartouche
@quotation 備註 
引數 `sock' 將 socket 所有權轉移給所建立的傳輸 socket，請呼叫傳輸的 @ref{374b,,close()} 方法。
@end quotation
@end cartouche
@end itemize

請參閱 @ref{374c,,UDP 回應用戶端協定} 和 @ref{374d,,UDP 回應伺服器協定} 範例。


在 3.4.4 版的變更: 新增 `family'、`proto'、`flags'、`reuse_address'、`reuse_port'、`allow_broadcast' 和 `sock' 參數。



在 3.8 版的變更: 新增對於 Windows 的支援。



在 3.8.1 版的變更: 不再支援 `reuse_address' 參數，因為使用 @code{SO_REUSEADDR} 對於 UDP 存有重大的安全疑慮。明確傳遞 @code{reuse_address=True} 將引發例外。

當具有不同 UID 的多個行程使用 @code{SO_REUSEADDR} 將 socket 分配給相同的 UDP socket 地址時，傳入的封包可能會在 socket 之間隨機分佈。

對於有支援的平台，`reuse_port' 可以用作類似功能的替代方案。使用 `reuse_port'，將改為使用 @code{SO_REUSEPORT}，該選項明確禁止具有不同 UID 的行程將 socket 分配給相同的 socket 地址。



在 3.11 版的變更: 自 Python 3.9.0、3.8.1、3.7.6 和 3.6.10 起，已完全移除 `reuse_address' 參數。

@end deffn

@geindex create_unix_connection() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop asyncio loop create_unix_connection}@anchor{36b4}
@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)

建立一個 Unix 連線。

Socket 家族將為 @ref{1ad5,,AF_UNIX}；socket 類型將為 @ref{14f4,,SOCK_STREAM}。

成功時回傳 @code{(transport, protocol)} 元組。

`path' 是 Unix 域 socket 的名稱，除非指定 `sock' 參數，否則為必填。支援抽象 Unix sockets、@ref{169,,str}、@ref{192,,bytes} 和 @ref{266,,Path} 路徑。

有關此方法的引數資訊，請參閱 @ref{811,,loop.create_connection()} 方法的文件。

@ref{2006,,可用性}: Unix.


在 3.7 版的變更: 新增 `ssl_handshake_timeout' 參數。`path' 參數現在可以是 @ref{59b,,path-like object}。



在 3.11 版的變更: 增加 `ssl_shutdown_timeout' 參數。

@end deffn

@node 建立網路伺服器,傳輸檔案,打開網路連線,事件迴圈方法
@anchor{library/asyncio-eventloop creating-network-servers}@anchor{374e}
@subsubsection 建立網路伺服器


@geindex create_server() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop loop-create-server}@anchor{3672}@anchor{library/asyncio-eventloop asyncio loop create_server}@anchor{d01}
@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)

建立一個 TCP 伺服器（socket 類型 @ref{14f4,,SOCK_STREAM}），監聽 `host' 位址的 `port'。

回傳一個 @ref{d00,,Server} 物件。

引數：


@itemize *

@item 
`protocol_factory' 必須是可呼叫的函式，回傳 @ref{3747,,protocol} 實作。

@item 
可以將 `host' 參數設為幾種類型，以確定伺服器將監聽的位置：


@itemize -

@item 
如果 `host' 是字串，則 TCP 伺服器綁定到由 `host' 指定的單個網路介面。

@item 
如果 `host' 是字串序列，則 TCP 伺服器綁定到序列指定的所有網路介面。

@item 
若 `host' 是空字串或 @code{None}，則所有介面都被假定並回傳多個 socket 的清單（可能一個用於 IPv4，另一個用於 IPv6）。
@end itemize

@item 
可以設定 `port' 參數以指定伺服器應該監聽的埠。如果是 @code{0} 或 @code{None}（預設值），將隨機選擇一個未使用的埠（請注意，如果 `host' 解析為多個網路介面，將為每個介面隨機選擇不同的隨機埠）。

@item 
`family' 可以設定為 @ref{1ad2,,socket.AF_INET} 或 @ref{1ad3,,AF_INET6} 以強制使用 IPv4 或 IPv6。如果未設定，`family' 將從主機名稱決定（預設為 @ref{374f,,AF_UNSPEC}）。

@item 
`flags' 是 @ref{e09,,getaddrinfo()} 的位元遮罩。

@item 
可以可選地指定 `sock' 以使用現有的 socket 物件。如果指定了，`host' 和 `port' 不能指定。

@cartouche
@quotation 備註 
`sock' 引數將 socket 的所有權轉移給建立的伺服器。要關閉 socket，請呼叫伺服器的 @ref{36b2,,close()} 方法。
@end quotation
@end cartouche

@item 
`backlog' 是傳遞給 @ref{1059,,listen()} 的最大佇列連線數（預設為 100）。

@item 
`ssl' 可以設定為 @ref{355,,SSLContext} 實例以在接受的連線上啟用 TLS。

@item 
`reuse_address' 告訴內核重用 @code{TIME_WAIT} 狀態下的本地 socket，而不等待其自然超時過期。如果未指定，在 Unix 上將自動設置為 @code{True}。

@item 
`reuse_port' 告訴內核允許此端點繫結到與其他現有端點繫結的相同埠，只要它們在建立時都設置了此旗標。此選項在旗標 Windows 上不受支援。

@item 
將 `keep_alive' 設為 @code{True} 透過啟用定期的訊息傳輸來保持連線活躍。
@end itemize


在 3.13 版的變更: 加入 `keep_alive' 參數。



@itemize *

@item 
（對於 TLS 伺服器）`ssl_handshake_timeout' 是在中斷連線之前等待 TLS 握手完成的時間（以秒為單位）。如果為 @code{None}（預設），則為 @code{60.0} 秒。

@item 
`ssl_shutdown_timeout' 是等待 SSL 關閉完成以前中斷連線的時間，以秒為單位。如果為 @code{None} （預設值），則會等待 @code{30.0} 秒。

@item 
將 `start_serving' 設置為 @code{True}（預設）將使建立的伺服器立即開始接受連接。當設置為 @code{False} 時，用戶應該等待 @ref{d02,,Server.start_serving()} 或 @ref{d03,,Server.serve_forever()} 來使伺服器開始接受連線。
@end itemize


在 3.5 版的變更: 新增 @ref{816,,ProactorEventLoop} 中的 SSL/TLS 支援。



在 3.5.1 版的變更: `host' 參數可以是字串序列。



在 3.6 版的變更: 新增 `ssl_handshake_timeout' 與 `start_serving' 參數。所有 TCP 連線都預設有 @ref{d64,,socket.TCP_NODELAY} socket 選項。



在 3.11 版的變更: 增加 `ssl_shutdown_timeout' 參數。



@subsubheading 也參考


@ref{d07,,start_server()} 函式是一個更高階的替代 API，它回傳一對 @ref{1b7b,,StreamReader} 和 @ref{19c2,,StreamWriter}，可以在 async/await 程式碼中使用。

@end deffn

@geindex create_unix_server() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop asyncio loop create_unix_server}@anchor{4c5}
@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)

類似 @ref{d01,,loop.create_server()}，但適用於 @ref{1ad5,,AF_UNIX} socket 家族。

`path' 是 Unix 域 socket 的名稱，除非提供了 `sock' 引數，否則必須給定。支援抽象 Unix sockets、@ref{169,,str}、@ref{192,,bytes} 和 @ref{266,,Path} 路徑。

如果 `cleanup_socket' 為真，則 Unix socket 將在伺服器關閉時自動從檔案系統中刪除，除非在建立伺服器後替換了 socket。

有關此方法的引數資訊，請參閱 @ref{d01,,loop.create_server()} 方法的文件。

@ref{2006,,可用性}: Unix.


在 3.7 版的變更: 新增 `ssl_handshake_timeout' 與 `start_serving' 參數。`path' 參數現在可為一個 @ref{266,,Path} 物件。



在 3.11 版的變更: 增加 `ssl_shutdown_timeout' 參數。



在 3.13 版的變更: 加入 `cleanup_socket' 參數。

@end deffn

@geindex connect_accepted_socket() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop asyncio loop connect_accepted_socket}@anchor{9d7}
@deffn {方法} async loop.connect_accepted_socket (protocol_factory, sock, *, ssl=None, ssl_handshake_timeout=None, ssl_shutdown_timeout=None)

將已接受的連線包裝成傳輸層/協定對。

此方法可以由在 asyncio 外接受連線但使用 asyncio 處理連線的伺服器使用。

參數：


@itemize *

@item 
`protocol_factory' 必須是可呼叫的函式，回傳 @ref{3747,,protocol} 實作。

@item 
`sock' 是從 @ref{f9d,,socket.accept} 回傳的預先存在的 socket 物件。

@cartouche
@quotation 備註 
引數 `sock' 將 socket 所有權轉移給所建立的傳輸 socket，請呼叫傳輸的 @ref{374b,,close()} 方法。
@end quotation
@end cartouche

@item 
`ssl' 可以設置為 @ref{355,,SSLContext} 以在已接受的連線上啟用 SSL。

@item 
（對於 SSL 連線）`ssl_handshake_timeout' 是在中斷連線之前等待 SSL 握手完成的時間（以秒為單位）。如果為 @code{None}（預設），則為 @code{60.0} 秒。

@item 
`ssl_shutdown_timeout' 是等待 SSL 關閉完成以前中斷連線的時間，以秒為單位。如果為 @code{None} （預設值），則會等待 @code{30.0} 秒。
@end itemize

回傳 @code{(transport, protocol)} 對。


在 3.5.3 版被加入.



在 3.7 版的變更: 增加 `ssl_handshake_timeout' 參數。



在 3.11 版的變更: 增加 `ssl_shutdown_timeout' 參數。

@end deffn

@node 傳輸檔案,TLS 升級,建立網路伺服器,事件迴圈方法
@anchor{library/asyncio-eventloop transferring-files}@anchor{3750}
@subsubsection 傳輸檔案


@geindex sendfile() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop asyncio loop sendfile}@anchor{3751}
@deffn {方法} async loop.sendfile (transport, file, offset=0, count=None, *, fallback=True)

通過 `transport' 發送 `file'。回傳發送的總位元組數。

如果可用，該方法使用高性能 @ref{cfd,,os.sendfile()}。

`file' 必須是以二進位模式打開的常規檔案物件。

`offset' 告訴從哪裡開始讀取檔案。如果指定了，`count' 是要傳輸的總位元組數，而不是發送檔案直到達到 EOF。即使此方法引發錯誤時，檔案位置也始終更新，可以使用 @ref{15a4,,file.tell()} 取得實際發送的位元組數。

將 `fallback' 設置為 @code{True} 會使 asyncio 在平台不支援 sendfile 系統呼叫時（例如 Windows 或 Unix 上的 SSL socket）手動讀取和發送檔案。

如果系統不支援 `sendfile' 系統呼叫且 `fallback' 為 @code{False}，則引發 @ref{3727,,SendfileNotAvailableError}。


在 3.7 版被加入.

@end deffn

@node TLS 升級,監視檔案描述器,傳輸檔案,事件迴圈方法
@anchor{library/asyncio-eventloop tls-upgrade}@anchor{3752}
@subsubsection TLS 升級


@geindex start_tls() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop asyncio loop start_tls}@anchor{cf7}
@deffn {方法} async loop.start_tls (transport, protocol, sslcontext, *, server_side=False, server_hostname=None, ssl_handshake_timeout=None, ssl_shutdown_timeout=None)

將基於傳輸的現有連線升級到 TLS。

建立 TLS 編解碼器實例並在 `transport' 和 `protocol' 之間插入它。編解碼器既實作了對於 `transport' 的協定，也實作了對於 `protocol' 的傳輸。

回傳建立的雙介面實例。在 `await' 後，`protocol' 必須停止使用原始的 `transport'，僅與回傳的物件通信，因為編碼器快取了 `protocol' 端的資料，並且與 `transport' 間歇性地交換額外的 TLS session 封包。

在某些情況下（例如傳入的傳輸已經關閉），此函式可能回傳 @code{None}。

參數：


@itemize *

@item 
`transport' 和 `protocol' 實例，由像 @ref{d01,,create_server()} 和 @ref{811,,create_connection()} 等方法回傳。

@item 
`sslcontext'：配置好的 @ref{355,,SSLContext} 實例。

@item 
當升級伺服器端連線時（像由 @ref{d01,,create_server()} 建立的那樣）傳遞 @code{True}。

@item 
`server_hostname'：設置或覆蓋將用於匹配目標伺服器憑證的主機名。

@item 
`ssl_handshake_timeout' （對於 TLS 連線）是等待 TLS 交握的時間，以秒為單位，在那之前若未完成則會中斷連線。如果為 @code{None} （預設值），則會等待 @code{60.0} 秒。

@item 
`ssl_shutdown_timeout' 是等待 SSL 關閉完成以前中斷連線的時間，以秒為單位。如果為 @code{None} （預設值），則會等待 @code{30.0} 秒。
@end itemize


在 3.7 版被加入.



在 3.11 版的變更: 增加 `ssl_shutdown_timeout' 參數。

@end deffn

@node 監視檔案描述器,直接使用 socket 物件,TLS 升級,事件迴圈方法
@anchor{library/asyncio-eventloop watching-file-descriptors}@anchor{3753}
@subsubsection 監視檔案描述器


@geindex add_reader() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop asyncio loop add_reader}@anchor{36cf}
@deffn {方法} loop.add_reader (fd, callback, *args)

開始監視 `fd' 檔案描述器的讀取可用性，一但 `fd' 可讀取，使用指定引數叫用 `callback'。

任何預先存在、為 `fd' 註冊的回呼函式將被取消並替換為 `callback'。
@end deffn

@geindex remove_reader() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop asyncio loop remove_reader}@anchor{3754}
@deffn {方法} loop.remove_reader (fd)

停止監視 `fd' 檔案描述器的讀取可用性。如果 `fd' 之前正在監視讀取，則回傳 @code{True}。
@end deffn

@geindex add_writer() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop asyncio loop add_writer}@anchor{3755}
@deffn {方法} loop.add_writer (fd, callback, *args)

開始監視 `fd' 檔案描述器的寫入可用性，一旦 `fd' 可寫入，使用指定引數叫用 `callback'。

任何預先存在、為 `fd' 註冊的回呼函式將被取消並替換為 `callback'。

使用 @ref{217,,functools.partial()} 向 `callback' @ref{3741,,傳送關鍵字引數}。
@end deffn

@geindex remove_writer() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop asyncio loop remove_writer}@anchor{3756}
@deffn {方法} loop.remove_writer (fd)

停止監視 `fd' 檔案描述器的寫入可用性。如果 `fd' 之前正在監視寫入，則回傳 @code{True}。
@end deffn

另請參閱@ref{3757,,平台支援}部分以了解這些方法的一些限制。

@node 直接使用 socket 物件,DNS,監視檔案描述器,事件迴圈方法
@anchor{library/asyncio-eventloop working-with-socket-objects-directly}@anchor{3758}
@subsubsection 直接使用 socket 物件


一般情況下，使用基於傳輸的 API（如 @ref{811,,loop.create_connection()} 和 @ref{d01,,loop.create_server()}）的協定實作比直接使用 socket 的實作更快。然而在某些情況下性能不是關鍵，直接使用 @ref{f9c,,socket} 物件更方便。

@geindex sock_recv() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop asyncio loop sock_recv}@anchor{e06}
@deffn {方法} async loop.sock_recv (sock, nbytes)

從 `sock' 接收最多 `nbytes'。@ref{f9f,,socket.recv()} 的非同步版本。

將接收到的資料作為 bytes 物件回傳。

`sock' 必須是非阻塞 socket。


在 3.7 版的變更: 儘管此方法一直記錄為協程方法，但 Python 3.7 之前的版本回傳 @ref{dc1,,Future}。自 Python 3.7 起，這是 @code{async def} 方法。

@end deffn

@geindex sock_recv_into() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop asyncio loop sock_recv_into}@anchor{cf8}
@deffn {方法} async loop.sock_recv_into (sock, buf)

從 `sock' 接收資料到 `buf' 緩衝區。仿照阻塞 @ref{151e,,socket.recv_into()} 方法。

回傳寫入緩衝區位元組的數目。

`sock' 必須是非阻塞 socket。


在 3.7 版被加入.

@end deffn

@geindex sock_recvfrom() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop asyncio loop sock_recvfrom}@anchor{814}
@deffn {方法} async loop.sock_recvfrom (sock, bufsize)

從 `sock' 接收最多 `bufsize' 大小的資料單元。@ref{fa0,,socket.recvfrom()} 的非同步版本。

回傳一個元組 (received data, remote address)。

`sock' 必須是非阻塞 socket。


在 3.11 版被加入.

@end deffn

@geindex sock_recvfrom_into() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop asyncio loop sock_recvfrom_into}@anchor{815}
@deffn {方法} async loop.sock_recvfrom_into (sock, buf, nbytes=0)

從 `sock' 接收最多 `nbytes' 大小的資料單元到 `buf'。@ref{151f,,socket.recvfrom_into()} 的非同步版本。

回傳一個元組 (number of bytes received, remote address)。

`sock' 必須是非阻塞 socket。


在 3.11 版被加入.

@end deffn

@geindex sock_sendall() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop asyncio loop sock_sendall}@anchor{e07}
@deffn {方法} async loop.sock_sendall (sock, data)

將 `data' 發送到 `sock' socket。@ref{fa3,,socket.sendall()} 的非同步版本。

此方法將繼續發送到 socket，直到 `data' 中的所有資料都已發送或發生錯誤。成功時回傳 @code{None}。錯誤時引發例外。此外，沒有辦法確定接收端成功處理了多少資料（如果有的話）。

`sock' 必須是非阻塞 socket。


在 3.7 版的變更: 儘管該方法一直被記錄為協程方法，但在 Python 3.7 之前它回傳 @ref{dc1,,Future}。從 Python 3.7 開始，這是一個 @code{async def} 方法。

@end deffn

@geindex sock_sendto() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop asyncio loop sock_sendto}@anchor{813}
@deffn {方法} async loop.sock_sendto (sock, data, address)

從 `sock' 向 `address' 發送一個資料單元。@ref{fa4,,socket.sendto()} 的非同步版本。

回傳發送的位元組數。

`sock' 必須是非阻塞 socket。


在 3.11 版被加入.

@end deffn

@geindex sock_connect() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop asyncio loop sock_connect}@anchor{fc3}
@deffn {方法} async loop.sock_connect (sock, address)

將 `sock' 連線到位於 `address' 的遠端 socket。

@ref{f9e,,socket.connect()} 的非同步版本。

`sock' 必須是非阻塞 socket。


在 3.5.2 版的變更: 不再需要解析 @code{address}。@code{sock_connect} 將嘗試透過呼叫 @ref{b52,,socket.inet_pton()} 檢查 `address' 是否已解析。如果沒有，將使用 @ref{e09,,loop.getaddrinfo()} 解析 `address'。



@subsubheading 也參考


@ref{811,,loop.create_connection()} 和 @ref{d06,,asyncio.open_connection()}。

@end deffn

@geindex sock_accept() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop asyncio loop sock_accept}@anchor{e08}
@deffn {方法} async loop.sock_accept (sock)

接受一個連線。模擬阻塞的 @ref{f9d,,socket.accept()} 方法。

Socket 必須繫結到一個地址並偵聽連線。回傳值是一個 @code{(conn, address)} 對，其中 `conn' 是一個 `新' socket 物件，可在連線上發送和接收資料，`address' 是連接另一端對應的 socket 地址。

`sock' 必須是非阻塞 socket。


在 3.7 版的變更: 儘管該方法一直被記錄為協程方法，但在 Python 3.7 之前它回傳 @ref{dc1,,Future}。從 Python 3.7 開始，這是一個 @code{async def} 方法。



@subsubheading 也參考


@ref{d01,,loop.create_server()} 和 @ref{d07,,start_server()}。

@end deffn

@geindex sock_sendfile() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop asyncio loop sock_sendfile}@anchor{cfc}
@deffn {方法} async loop.sock_sendfile (sock, file, offset=0, count=None, *, fallback=True)

如果可行，使用高性能 @ref{cfd,,os.sendfile} 發送檔案。回傳發送的總位元組數。

@ref{1058,,socket.sendfile()} 的非同步版本。

`sock' 必須是非阻塞的 @ref{14f4,,socket.SOCK_STREAM} @ref{f9c,,socket}。

`file' 必須是以二進位模式打開的常規檔案物件。

`offset' 告訴從哪裡開始讀取檔案。如果指定了，`count' 是要傳輸的總位元組數，而不是發送檔案直到達到 EOF。即使此方法引發錯誤時，檔案位置也始終更新，可以使用 @ref{15a4,,file.tell()} 取得實際發送的位元組數。

當設置為 @code{True} 時，`fallback' 使 asyncio 在平台不支援 sendfile 系統呼叫時（例如 Windows 或 Unix 上的 SSL socket）手動讀取和發送檔案。

如果系統不支援 `sendfile' 系統呼叫且 `fallback' 為 @code{False}，引發 @ref{3727,,SendfileNotAvailableError}。

`sock' 必須是非阻塞 socket。


在 3.7 版被加入.

@end deffn

@node DNS,使用管道,直接使用 socket 物件,事件迴圈方法
@anchor{library/asyncio-eventloop dns}@anchor{3759}
@subsubsection DNS


@geindex getaddrinfo() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop asyncio loop getaddrinfo}@anchor{e09}
@deffn {方法} async loop.getaddrinfo (host, port, *, family=0, type=0, proto=0, flags=0)

@ref{1a0e,,socket.getaddrinfo()} 的非同步版本。
@end deffn

@geindex getnameinfo() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop asyncio loop getnameinfo}@anchor{e0a}
@deffn {方法} async loop.getnameinfo (sockaddr, flags=0)

@ref{198b,,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 版的變更: `getaddrinfo' 和 `getnameinfo' 方法一直被記錄為回傳協程，但在 Python 3.7 之前它們實際上回傳 @ref{dc1,,asyncio.Future} 物件。從 Python 3.7 開始，兩個方法都是協程。


@node 使用管道,Unix 訊號,DNS,事件迴圈方法
@anchor{library/asyncio-eventloop working-with-pipes}@anchor{375a}
@subsubsection 使用管道


@geindex connect_read_pipe() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop asyncio loop connect_read_pipe}@anchor{36fb}
@deffn {方法} async loop.connect_read_pipe (protocol_factory, pipe)

在事件迴圈中註冊 `pipe' 的讀取端。

`protocol_factory' 必須是一個回傳 @ref{3747,,asyncio protocol} 實作的可呼叫函式。

`pipe' 是 @ref{13c4,,類檔案物件}。

回傳 @code{(transport, protocol)} 對，其中 `transport' 支援 @ref{375b,,ReadTransport} 介面，`protocol' 是由 `protocol_factory' 實例化的物件。

使用 @ref{313,,SelectorEventLoop} 事件迴圈時，`pipe' 設置為非阻塞模式。
@end deffn

@geindex connect_write_pipe() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop asyncio loop connect_write_pipe}@anchor{36fc}
@deffn {方法} async loop.connect_write_pipe (protocol_factory, pipe)

在事件迴圈中註冊 `pipe' 的寫入端。

`protocol_factory' 必須是一個回傳 @ref{3747,,asyncio protocol} 實作的可呼叫函式。

`pipe' 是 @ref{13c4,,file-like object}。

回傳 @code{(transport, protocol)} 對，其中 `transport' 支援 @ref{375c,,WriteTransport} 介面，`protocol' 是由 `protocol_factory' 實例化的物件。

使用 @ref{313,,SelectorEventLoop} 事件迴圈時，`pipe' 設置為非阻塞模式。
@end deffn

@cartouche
@quotation 備註 
@ref{313,,SelectorEventLoop} 在 Windows 上不支援上述方法。對於 Windows 請使用 @ref{816,,ProactorEventLoop}。
@end quotation
@end cartouche


@subsubheading 也參考


@ref{36f8,,loop.subprocess_exec()} 和 @ref{36f9,,loop.subprocess_shell()} 方法。


@node Unix 訊號,在執行緒池或行程池中執行程式碼,使用管道,事件迴圈方法
@anchor{library/asyncio-eventloop unix-signals}@anchor{375d}
@subsubsection Unix 訊號


@geindex add_signal_handler() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop loop-add-signal-handler}@anchor{3674}@anchor{library/asyncio-eventloop asyncio loop add_signal_handler}@anchor{375e}
@deffn {方法} loop.add_signal_handler (signum, callback, *args)

將 `callback' 設置為 `signum' 訊號的處理程式。

該回呼將由 `loop' 叫用，與該事件迴圈的其他排隊回呼和可運行的協程一起。與使用 @ref{1335,,signal.signal()} 註冊的訊號處理程式不同，使用此函式註冊的回呼允許與事件迴圈進行互動。

如果訊號號無效或不可捕獲，引發 @ref{2eb,,ValueError}。如果設定處理程序有問題，拋出 @ref{244,,RuntimeError}。

使用 @ref{217,,functools.partial()} 向 `callback' @ref{3741,,傳送關鍵字引數}。

像 @ref{1335,,signal.signal()} 一樣，此函式必須在主執行緒中叫用。
@end deffn

@geindex remove_signal_handler() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop asyncio loop remove_signal_handler}@anchor{375f}
@deffn {方法} loop.remove_signal_handler (sig)

移除 `sig' 訊號的處理程式。

如果訊號處理程式被移除，回傳 @code{True}；如果給定訊號沒有設置處理程式，回傳 @code{False}。

@ref{2006,,可用性}: Unix.
@end deffn


@subsubheading 也參考


@ref{cb,,signal} 模組。


@node 在執行緒池或行程池中執行程式碼,錯誤處理 API,Unix 訊號,事件迴圈方法
@anchor{library/asyncio-eventloop executing-code-in-thread-or-process-pools}@anchor{3760}
@subsubsection 在執行緒池或行程池中執行程式碼


@geindex run_in_executor() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop asyncio loop run_in_executor}@anchor{add}
@deffn {方法} awaitable loop.run_in_executor (executor, func, *args)

安排在指定的執行器中呼叫 `func'。

The `executor' argument should be an @ref{3593,,concurrent.futures.Executor}
instance. The default executor is used if `executor' is @code{None}.
The default executor can be set by @ref{942,,loop.set_default_executor()},
otherwise, a @ref{941,,concurrent.futures.ThreadPoolExecutor} will be
lazy-initialized and used by @ref{add,,run_in_executor()} if needed.

範例：

@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

請注意，由於 @ref{98,,multiprocessing}（由 @ref{1d6,,ProcessPoolExecutor} 使用）的特殊性，選項 3 需要進入點保護（@code{if __name__ == '__main__'}）。請參閱@ref{357c,,主模組的安全引入}。

此方法回傳 @ref{dc1,,asyncio.Future} 物件。

使用 @ref{217,,functools.partial()} 將來@ref{3741,,關鍵字引數傳遞}給 `func'。


在 3.5.3 版的變更: @ref{add,,loop.run_in_executor()} 不再配置它建立的執行緒池執行器的 @code{max_workers}，而是讓執行緒池執行器（@ref{941,,ThreadPoolExecutor}）設定預設值。

@end deffn

@geindex set_default_executor() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop asyncio loop set_default_executor}@anchor{942}
@deffn {方法} loop.set_default_executor (executor)

將 `executor' 設置為 @ref{add,,run_in_executor()} 使用的預設執行器。`executor' 必須是 @ref{941,,ThreadPoolExecutor}（也包含 @ref{1d2,,InterpreterPoolExecutor}）的實例。


在 3.11 版的變更: `executor' 必須是 @ref{941,,ThreadPoolExecutor} 的實例。

@end deffn

@node 錯誤處理 API,啟用除錯模式,在執行緒池或行程池中執行程式碼,事件迴圈方法
@anchor{library/asyncio-eventloop error-handling-api}@anchor{3761}
@subsubsection 錯誤處理 API


允許自定義事件迴圈中的例外處理方式。

@geindex set_exception_handler() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop asyncio loop set_exception_handler}@anchor{3762}
@deffn {方法} loop.set_exception_handler (handler)

將 `handler' 設定為新的事件迴圈例外處理程式。

如果 `handler' 是 @code{None}，則將設置預設例外處理程式。否則，`handler' 必須是一個可呼叫物件，簽名匹配 @code{(loop, context)}，其中 @code{loop} 是參照活躍事件迴圈的，@code{context} 是包含例外詳細資訊的 @code{dict} 物件（有關情境的詳細資訊，請參閱 @ref{3763,,call_exception_handler()} 文件）。

如果代表 @ref{1c7,,Task} 或 @ref{1d4b,,Handle} 呼叫處理程式，它將在該任務或回呼處理程式的 @ref{177,,contextvars.Context} 中運行。


在 3.12 版的變更: 處理程式可能在引發例外的任務或處理程式的 @ref{177,,Context} 中被呼叫。

@end deffn

@geindex get_exception_handler() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop asyncio loop get_exception_handler}@anchor{e70}
@deffn {方法} loop.get_exception_handler ()

回傳目前的例外處理程式，如果未設置自定義例外處理程式，則回傳 @code{None}。


在 3.5.2 版被加入.

@end deffn

@geindex default_exception_handler() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop asyncio loop default_exception_handler}@anchor{3764}
@deffn {方法} loop.default_exception_handler (context)

預設例外處理程式。

當發生例外且未設置例外處理程式時呼叫此函式。自定義例外處理程式可以呼叫此函式以轉由預設處理程式處理。

`context' 參數與 @ref{3763,,call_exception_handler()} 中的意思相同。
@end deffn

@geindex call_exception_handler() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop asyncio loop call_exception_handler}@anchor{3763}
@deffn {方法} loop.call_exception_handler (context)

呼叫目前事件迴圈例外處理程式。

`context' 是一個包含以下鍵的 @code{dict} 物件（未來的 Python 版本中可能會引入新的鍵）:


@itemize *

@item 
'message'：錯誤訊息；

@item 
'exception'（可選）：例外物件；

@item 
'future'（可選）： @ref{dc1,,asyncio.Future} 實例；

@item 
'task'（可選）： @ref{1c7,,asyncio.Task} 實例；

@item 
'handle'（可選）： @ref{1d4b,,asyncio.Handle} 實例；

@item 
'protocol'（可選）： @ref{3747,,Protocol} 實例；

@item 
'transport'（可選）： @ref{3748,,Transport} 實例；

@item 
'socket'（可選）： @ref{f9c,,socket.socket} 實例；

@item 
'source_traceback' (optional): Traceback of the source;

@item 
'handle_traceback' (optional): Traceback of the handle;

@item 

@table @asis

@item 'asyncgen'(可選)： 非同步產生器引發

例外。
@end table
@end itemize

@cartouche
@quotation 備註 
此方法不應在子類別事件迴圈中被覆寫。為了自定義例外處理，請使用 @ref{3762,,set_exception_handler()} 方法。
@end quotation
@end cartouche
@end deffn

@node 啟用除錯模式,運行子行程,錯誤處理 API,事件迴圈方法
@anchor{library/asyncio-eventloop enabling-debug-mode}@anchor{3765}
@subsubsection 啟用除錯模式


@geindex get_debug() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop asyncio loop get_debug}@anchor{fbd}
@deffn {方法} loop.get_debug ()

取得事件迴圈的除錯模式（@ref{3c1,,bool}）。

如果環境變數 
@geindex PYTHONASYNCIODEBUG
@geindex 環境變數; PYTHONASYNCIODEBUG
@ref{2000,,PYTHONASYNCIODEBUG} 被設定為非空字串，則預設值為 @code{True}，否則為 @code{False}。
@end deffn

@geindex set_debug() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop asyncio loop set_debug}@anchor{fbc}
@deffn {方法} loop.set_debug (enabled: bool)

設定事件迴圈的除錯模式。


在 3.7 版的變更: 現在也可以使用新的 @ref{503,,Python 開發模式} 啟用除錯模式。

@end deffn

@geindex slow_callback_duration (asyncio.loop 的屬性)
@anchor{library/asyncio-eventloop asyncio loop slow_callback_duration}@anchor{3766}
@deffn {屬性} loop.slow_callback_duration

此屬性可用於設定被視為"慢"的最短執行時間（以秒為單位）。啟用偵錯模式後，"慢"回呼將被記錄。

預設值為 100 毫秒
@end deffn


@subsubheading 也參考


@ref{2001,,asyncio 的除錯模式}。


@node 運行子行程,,啟用除錯模式,事件迴圈方法
@anchor{library/asyncio-eventloop running-subprocesses}@anchor{3767}
@subsubsection 運行子行程


本小節描述的方法是低階的。在常規的 async/await 程式碼中，請考慮使用高階 @ref{c63,,asyncio.create_subprocess_shell()} 和 @ref{c62,,asyncio.create_subprocess_exec()} 輔助功能而不是。

@cartouche
@quotation 備註 
在 Windows 上，預設事件迴圈 @ref{816,,ProactorEventLoop} 支援子行程，而 @ref{313,,SelectorEventLoop} 不支援。詳細資訊請參見 @ref{36fa,,Windows 上對於子行程的支援}。
@end quotation
@end cartouche

@geindex subprocess_exec() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop loop-subprocess-exec}@anchor{3673}@anchor{library/asyncio-eventloop asyncio loop subprocess_exec}@anchor{36f8}
@deffn {方法} async loop.subprocess_exec (protocol_factory, *args, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, **kwargs)

從 `args' 指定的一個或多個字串引數建立子行程。

`args' 必須是由以下項表示的字串串列：


@itemize *

@item 
@ref{169,,str}；

@item 
或 @ref{192,,bytes}，編碼為 @ref{2ae7,,檔案系統編碼}。
@end itemize

第一個字串指定程序可執行檔案，其餘字串指定引數。字串引數一起組成程序的 @code{argv}。

這與標準函式庫 @ref{4b2,,subprocess.Popen} 類似，使用 @code{shell=False} 呼叫並將字串串列作為第一個引數傳遞；然而，@ref{4b2,,Popen} 接受單個字串串列引數，`subprocess_exec' 接受多個字串引數。

`protocol_factory' 必須是回傳 @ref{3768,,asyncio.SubprocessProtocol} 子類別的可呼叫物件。

其他參數：


@itemize *

@item 
`stdin' 可以是以下任意一個：


@itemize *

@item 
類檔案物件

@item 
現有的檔案描述器（正整數），例如用 @ref{1a93,,os.pipe()} 建立的

@item 
@ref{d7a,,subprocess.PIPE} 常數（預設），它將建立一個新的管道並連線，

@item 
值 @code{None} 將使子行程從此行程繼承檔案描述器

@item 
@ref{134f,,subprocess.DEVNULL} 常數，表示將使用特殊的 @ref{1cdc,,os.devnull} 檔案
@end itemize

@item 
`stdout' 可以是以下任意一個：


@itemize *

@item 
類檔案物件

@item 
@ref{d7a,,subprocess.PIPE} 常數（預設），它將建立一個新的管道並連線，

@item 
值 @code{None} 將使子行程從此行程繼承檔案描述器

@item 
@ref{134f,,subprocess.DEVNULL} 常數，表示將使用特殊的 @ref{1cdc,,os.devnull} 檔案
@end itemize

@item 
`stderr' 可以是以下任意一個：


@itemize *

@item 
類檔案物件

@item 
@ref{d7a,,subprocess.PIPE} 常數（預設），它將建立一個新的管道並連線，

@item 
值 @code{None} 將使子行程從此行程繼承檔案描述器

@item 
@ref{134f,,subprocess.DEVNULL} 常數，表示將使用特殊的 @ref{1cdc,,os.devnull} 檔案

@item 
@ref{35df,,subprocess.STDOUT} 常數，它將標準錯誤串流連線到行程的標準輸出串流
@end itemize

@item 
所有其他關鍵字引數都會傳遞給 @ref{4b2,,subprocess.Popen} 而不進行直譯，但 `bufsize'、`universal_newlines'、`shell'、`text'、`encoding' 和 `errors' 除外，這些不應該指定。

@code{asyncio} 子行程 API 不支援將串流解碼為文本。可以使用 @ref{aca,,bytes.decode()} 將從串流回傳的位元組轉換為文本。
@end itemize

如果傳遞給 `stdin'、`stdout' 或 `stderr' 的類檔案物件表示管道，則該管道的另一端應該使用 @ref{36fc,,connect_write_pipe()} 或 @ref{36fb,,connect_read_pipe()} 註冊到事件迴圈中。

有關其他引數的文件，請參閱 @ref{4b2,,subprocess.Popen} 類別的建構函式。

回傳 @code{(transport, protocol)} 對，其中 `transport' 符合 @ref{3769,,asyncio.SubprocessTransport} 基底類別，`protocol' 是由 `protocol_factory' 實例化的物件。
@end deffn

@geindex subprocess_shell() (asyncio.loop 的方法)
@anchor{library/asyncio-eventloop asyncio loop subprocess_shell}@anchor{36f9}
@deffn {方法} async loop.subprocess_shell (protocol_factory, cmd, *, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, **kwargs)

使用平台的 "shell" 語法從 `cmd' 建立子行程，`cmd' 可以是 @ref{169,,str} 或編碼為 @ref{2ae7,,檔案系統編碼} 的 @ref{192,,bytes} 字串。

這類似於標準函式庫中的 @ref{4b2,,subprocess.Popen} 類別，使用 @code{shell=True} 呼叫。

`protocol_factory' 必須是回傳 @ref{3768,,SubprocessProtocol} 子類別的可呼叫物件。

有關其餘引數的更多詳細資訊，請參閱 @ref{36f8,,subprocess_exec()}。

回傳一對 @code{(transport, protocol)}，其中 `transport' 符合 @ref{3769,,SubprocessTransport} 基底類別，而 `protocol' 是由 `protocol_factory' 實例化的物件。
@end deffn

@cartouche
@quotation 備註 
由應用程式負責確保適當引用所有空白和特殊字元，以避免 shell 注入@footnote{https://en.wikipedia.org/wiki/Shell_injection#Shell_injection}風險。可以使用 @ref{57c,,shlex.quote()} 函式來正確跳脫用於構建 shell 命令的字串中的空白和特殊字元。
@end quotation
@end cartouche

@node 回呼處理,Server 物件,事件迴圈方法,事件迴圈
@anchor{library/asyncio-eventloop callback-handles}@anchor{3737}
@subsubsection 回呼處理


@geindex Handle (asyncio 中的類別)
@anchor{library/asyncio-eventloop asyncio Handle}@anchor{1d4b}
@deffn {類別} asyncio.Handle

由 @ref{cf2,,loop.call_soon()} 和 @ref{cf3,,loop.call_soon_threadsafe()} 回傳的回呼包裝器。

@geindex get_context() (asyncio.Handle 的方法)
@anchor{library/asyncio-eventloop asyncio Handle get_context}@anchor{376a}
@deffn {方法} get_context ()

回傳與處理相關聯的 @ref{177,,contextvars.Context} 物件。


在 3.12 版被加入.

@end deffn

@geindex cancel() (asyncio.Handle 的方法)
@anchor{library/asyncio-eventloop asyncio Handle cancel}@anchor{376b}
@deffn {方法} cancel ()

取消回呼。如果回呼已被取消或執行，此方法將不起作用。
@end deffn

@geindex cancelled() (asyncio.Handle 的方法)
@anchor{library/asyncio-eventloop asyncio Handle cancelled}@anchor{d08}
@deffn {方法} cancelled ()

如果回呼已被取消，回傳 @code{True}。


在 3.7 版被加入.

@end deffn
@end deffn

@geindex TimerHandle (asyncio 中的類別)
@anchor{library/asyncio-eventloop asyncio TimerHandle}@anchor{1a28}
@deffn {類別} asyncio.TimerHandle

由 @ref{cf4,,loop.call_later()} 和 @ref{cf5,,loop.call_at()} 回傳的回呼包裝器。

這個類別是 @ref{1d4b,,Handle} 的子類別。

@geindex when() (asyncio.TimerHandle 的方法)
@anchor{library/asyncio-eventloop asyncio TimerHandle when}@anchor{d05}
@deffn {方法} when ()

回傳預定的回呼時間，以 @ref{196,,float} 秒為單位。

時間是一個絕對的時間戳，使用與 @ref{3744,,loop.time()} 相同的時間參照。


在 3.7 版被加入.

@end deffn
@end deffn

@node Server 物件,事件迴圈實作,回呼處理,事件迴圈
@anchor{library/asyncio-eventloop server-objects}@anchor{3738}
@subsubsection Server 物件


Server 物件是由 @ref{d01,,loop.create_server()}、@ref{4c5,,loop.create_unix_server()}、@ref{d07,,start_server()} 和 @ref{36b5,,start_unix_server()} 函式所建立。

請勿直接實例化 @ref{d00,,Server} 類別。

@geindex Server (asyncio 中的類別)
@anchor{library/asyncio-eventloop asyncio Server}@anchor{d00}
@deffn {類別} asyncio.Server

`Server' 物件是非同步情境管理器。當在 @code{async with} 陳述中使用時，可以保證在完成 @code{async with} 陳述時，Server 物件將會關閉並停止接受新的連線：

@example
srv = await loop.create_server(...)

async with srv:
    # 一些程式碼

# 此時 srv 已關閉，不再接受新的連線。
@end example


在 3.7 版的變更: 自 Python 3.7 起，Server 物件是非同步情境管理器。



在 3.11 版的變更: 此類別在 Python 3.9.11、3.10.3 和 3.11 中以 @code{asyncio.Server} 的形式被公開。


@geindex close() (asyncio.Server 的方法)
@anchor{library/asyncio-eventloop asyncio Server close}@anchor{36b2}
@deffn {方法} close ()

停止服務：關閉監聽的 sockets 並將 @ref{e0b,,sockets} 屬性設為 @code{None}。

代表現有傳入用戶端連線的 sockets 仍然保持開啟。

伺服器以非同步方式關閉；使用 @code{wait_close()} 協程等待伺服器關閉（不再有活躍連線）。
@end deffn

@geindex close_clients() (asyncio.Server 的方法)
@anchor{library/asyncio-eventloop asyncio Server close_clients}@anchor{4c9}
@deffn {方法} close_clients ()

關閉所有現有的傳入用戶端連線。

在所有關聯的傳輸上呼叫 @ref{374b,,close()}。

@ref{36b2,,close()} should be called before @ref{4c9,,close_clients()} when
closing the server to avoid races with new clients connecting.


在 3.13 版被加入.

@end deffn

@geindex abort_clients() (asyncio.Server 的方法)
@anchor{library/asyncio-eventloop asyncio Server abort_clients}@anchor{4ca}
@deffn {方法} abort_clients ()

立即關閉所有現有的傳入用戶端連線，而不等待待定操作完成。

在所有關聯的傳輸上呼叫 @ref{374b,,close()}。

@ref{36b2,,close()} should be called before @ref{4ca,,abort_clients()} when
closing the server to avoid races with new clients connecting.


在 3.13 版被加入.

@end deffn

@geindex get_loop() (asyncio.Server 的方法)
@anchor{library/asyncio-eventloop asyncio Server get_loop}@anchor{cff}
@deffn {方法} get_loop ()

回傳與伺服器物件關聯的事件迴圈。


在 3.7 版被加入.

@end deffn

@geindex start_serving() (asyncio.Server 的方法)
@anchor{library/asyncio-eventloop asyncio Server start_serving}@anchor{d02}
@deffn {方法} async start_serving ()

開始接受連線。

此方法是幂等的，因此可以在伺服器已經運行時呼叫。

`start_serving' 僅限關鍵字參數只能在 @ref{d01,,loop.create_server()} 和 @ref{d07,,asyncio.start_server()} 中使用，允許建立一個最初不接受連線的 Server 物件。在這種情況下，可以使用 @code{Server.start_serving()} 或 @ref{d03,,Server.serve_forever()} 來使 Server 開始接受連線。


在 3.7 版被加入.

@end deffn

@geindex serve_forever() (asyncio.Server 的方法)
@anchor{library/asyncio-eventloop asyncio Server serve_forever}@anchor{d03}
@deffn {方法} async serve_forever ()

開始接受連線，直到協程被取消。取消 @code{serve_forever} 任務會導致伺服器關閉。

如果伺服器已經接受連線，則可以呼叫此方法。每個 `Server' 物件只能存在一個 @code{serve_forever} 任務。

範例：

@example
async def client_connected(reader, writer):
    # 透過讀取器/寫入器串流
    # 與用戶端溝通。例如：
    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


在 3.7 版被加入.

@end deffn

@geindex is_serving() (asyncio.Server 的方法)
@anchor{library/asyncio-eventloop asyncio Server is_serving}@anchor{d04}
@deffn {方法} is_serving ()

如果伺服器正在接受新連線，則回傳 @code{True}。


在 3.7 版被加入.

@end deffn

@geindex wait_closed() (asyncio.Server 的方法)
@anchor{library/asyncio-eventloop asyncio Server wait_closed}@anchor{1990}
@deffn {方法} async wait_closed ()

等待 @ref{36b2,,close()} 方法完成且所有活動連線都已結束。
@end deffn

@geindex sockets (asyncio.Server 的屬性)
@anchor{library/asyncio-eventloop asyncio Server sockets}@anchor{e0b}
@deffn {屬性} sockets

伺服器正在監聽的類似 socket 的物件串列，@code{asyncio.trsock.TransportSocket}。


在 3.7 版的變更: 在 Python 3.7 之前，@code{Server.sockets} 曾經直接回傳內部伺服器 sockets 的串列。在 3.7 中回傳了該串列的副本。

@end deffn
@end deffn
@anchor{library/asyncio-eventloop asyncio-event-loops}@anchor{376c}
@node 事件迴圈實作,範例<24>,Server 物件,事件迴圈
@anchor{library/asyncio-eventloop asyncio-event-loop-implementations}@anchor{376d}@anchor{library/asyncio-eventloop event-loop-implementations}@anchor{3739}
@subsubsection 事件迴圈實作


asyncio 內附兩個不同的事件迴圈實作：@ref{313,,SelectorEventLoop} 和 @ref{816,,ProactorEventLoop}。

預設情況下，asyncio 被配置為要使用 @ref{19b9,,EventLoop}。

@geindex SelectorEventLoop (asyncio 中的類別)
@anchor{library/asyncio-eventloop asyncio SelectorEventLoop}@anchor{313}
@deffn {類別} asyncio.SelectorEventLoop

基於 @ref{c7,,selectors} 模組的一個 @ref{b4f,,AbstractEventLoop} 子類別。

使用特定平台上最有效的 `selector'。也可以手動配置要使用的確切 selector 實作：

@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{2006,,可用性}: Unix, Windows.
@end deffn

@geindex ProactorEventLoop (asyncio 中的類別)
@anchor{library/asyncio-eventloop asyncio ProactorEventLoop}@anchor{816}
@deffn {類別} asyncio.ProactorEventLoop

用於 Windows 的 @ref{b4f,,AbstractEventLoop} 子類別，使用「I/O 完成埠 (IOCP, I/O Completion Ports)」。

@ref{2006,,可用性}: Windows.


@subsubheading 也參考


I/O 完成埠的 MSDN 文件@footnote{https://learn.microsoft.com/windows/win32/fileio/i-o-completion-ports}。

@end deffn

@geindex EventLoop (asyncio 中的類別)
@anchor{library/asyncio-eventloop asyncio EventLoop}@anchor{19b9}
@deffn {類別} asyncio.EventLoop

@quotation

An alias to the most efficient available subclass of @ref{b4f,,AbstractEventLoop} for the given
platform.

在 Unix 上是 @ref{313,,SelectorEventLoop} 的別名，在 Windows 上是 @ref{816,,ProactorEventLoop} 的別名。
@end quotation


在 3.13 版被加入.

@end deffn

@geindex AbstractEventLoop (asyncio 中的類別)
@anchor{library/asyncio-eventloop asyncio AbstractEventLoop}@anchor{b4f}
@deffn {類別} asyncio.AbstractEventLoop

為符合 asyncio 標準的事件迴圈的抽象基礎類別。

@ref{373b,,事件迴圈方法} 部分列出了替代 @code{AbstractEventLoop} 實作應該定義的所有方法。
@end deffn

@node 範例<24>,,事件迴圈實作,事件迴圈
@anchor{library/asyncio-eventloop examples}@anchor{373a}
@subsubsection 範例


請注意，本節中的所有範例都 `故意' 展示如何使用低階事件迴圈 API，如 @ref{373d,,loop.run_forever()} 和 @ref{cf2,,loop.call_soon()}。現代 asyncio 應用程式很少需要這種方式撰寫；請考慮使用高階的函式，如 @ref{2f2,,asyncio.run()}。

@menu
* 使用 call_soon() 的 Hello World 範例: 使用 call_soon 的 Hello World 範例. 
* 使用 call_later() 顯示目前日期: 使用 call_later 顯示目前日期. 
* 監聽檔案描述器以進行讀取事件:: 
* 設定 SIGINT 和 SIGTERM 的訊號處理程式:: 

@end menu

@node 使用 call_soon 的 Hello World 範例,使用 call_later 顯示目前日期,,範例<24>
@anchor{library/asyncio-eventloop asyncio-example-lowlevel-helloworld}@anchor{376e}@anchor{library/asyncio-eventloop hello-world-with-call-soon}@anchor{376f}
@subsubsection 使用 call_soon() 的 Hello World 範例


使用 @ref{cf2,,loop.call_soon()} 方法排程回呼的範例。回呼會顯示 @code{"Hello World"}，然後停止事件迴圈：

@example
import asyncio

def hello_world(loop):
    """列印 'Hello World' 並停止事件迴圈的回呼"""
    print('Hello World')
    loop.stop()

loop = asyncio.new_event_loop()

# 排程對 hello_world() 的呼叫
loop.call_soon(hello_world, loop)

# 阻塞呼叫被 loop.stop() 中斷
try:
    loop.run_forever()
finally:
    loop.close()
@end example


@subsubheading 也參考


使用協程和 @ref{2f2,,run()} 函式建立的類似 @ref{366d,,Hello World} 範例。


@node 使用 call_later 顯示目前日期,監聽檔案描述器以進行讀取事件,使用 call_soon 的 Hello World 範例,範例<24>
@anchor{library/asyncio-eventloop asyncio-example-call-later}@anchor{3770}@anchor{library/asyncio-eventloop display-the-current-date-with-call-later}@anchor{3771}
@subsubsection 使用 call_later() 顯示目前日期


一個回呼的範例，每秒顯示目前日期。回呼使用 @ref{cf4,,loop.call_later()} 方法在 5 秒後重新排程自己，然後停止事件迴圈：

@example
import asyncio
import datetime

def display_date(end_time, loop):
    print(datetime.datetime.now())
    if (loop.time() + 1.0) < end_time:
        loop.call_later(1, display_date, end_time, loop)
    else:
        loop.stop()

loop = asyncio.new_event_loop()

# 排程 display_date() 的第一次呼叫
end_time = loop.time() + 5.0
loop.call_soon(display_date, end_time, loop)

# 阻塞呼叫被 loop.stop() 中斷
try:
    loop.run_forever()
finally:
    loop.close()
@end example


@subsubheading 也參考


使用協程和 @ref{2f2,,run()} 函式建立的類似 @ref{368c,,current date} 範例。


@node 監聽檔案描述器以進行讀取事件,設定 SIGINT 和 SIGTERM 的訊號處理程式,使用 call_later 顯示目前日期,範例<24>
@anchor{library/asyncio-eventloop asyncio-example-watch-fd}@anchor{36ce}@anchor{library/asyncio-eventloop watch-a-file-descriptor-for-read-events}@anchor{3772}
@subsubsection 監聽檔案描述器以進行讀取事件


使用 @ref{36cf,,loop.add_reader()} 方法等待檔案描述器接收到某些資料，然後關閉事件迴圈：

@example
import asyncio
from socket import socketpair

# 建立一對連接的檔案描述器
rsock, wsock = socketpair()

loop = asyncio.new_event_loop()

def reader():
    data = rsock.recv(100)
    print("Received:", data.decode())

    # 我們完成了：註銷檔案描述器
    loop.remove_reader(rsock)

    # 停止事件迴圈
    loop.stop()

# 為讀取事件註冊檔案描述器
loop.add_reader(rsock, reader)

# 模擬從網路接收資料
loop.call_soon(wsock.send, 'abc'.encode())

try:
    # 運行事件迴圈
    loop.run_forever()
finally:
    # 我們完成了。關閉 socket 和事件迴圈。
    rsock.close()
    wsock.close()
    loop.close()
@end example


@subsubheading 也參考



@itemize *

@item 
使用傳輸、協定和 @ref{811,,loop.create_connection()} 方法的類似 @ref{36cd,,範例}。

@item 
另一個使用高階 @ref{d06,,asyncio.open_connection()} 函式和串流的類似 @ref{36cb,,範例}。
@end itemize


@node 設定 SIGINT 和 SIGTERM 的訊號處理程式,,監聽檔案描述器以進行讀取事件,範例<24>
@anchor{library/asyncio-eventloop asyncio-example-unix-signals}@anchor{3773}@anchor{library/asyncio-eventloop set-signal-handlers-for-sigint-and-sigterm}@anchor{3774}
@subsubsection 設定 SIGINT 和 SIGTERM 的訊號處理程式


（此 @code{signals} 範例僅在 Unix 上運作。）

使用 @ref{375e,,loop.add_signal_handler()} 方法註冊訊號 @code{SIGINT} 和 @code{SIGTERM} 的處理程式：

@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,傳輸與協定,事件迴圈,asyncio --- 非同步 I/O
@anchor{library/asyncio-future doc}@anchor{3775}@anchor{library/asyncio-future asyncio-futures}@anchor{3676}@anchor{library/asyncio-future futures}@anchor{3776}@anchor{library/asyncio-future translation-repo}@anchor{3777}
@subsubsection Futures


`原始碼：'Lib/asyncio/futures.py、source:`Lib/asyncio/base_futures.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/asyncio/futures.py、source:`Lib/asyncio/base_futures.py}


__________________________________________________________________


`Future' 物件被用來連結`低階回呼式程式'和高階 async/await 程式。

@menu
* Future 函式:: 
* Future 物件: Future 物件<2>. 

@end menu

@node Future 函式,Future 物件<2>,,Futures
@anchor{library/asyncio-future future-functions}@anchor{3778}
@subsubsection Future 函式


@geindex isfuture() (於 asyncio 模組中)
@anchor{library/asyncio-future asyncio isfuture}@anchor{3779}
@deffn {函式} asyncio.isfuture (obj)

如果 `obj' 為下面任意物件，回傳 @code{True}：


@itemize *

@item 
一個 @ref{dc1,,asyncio.Future} 的實例、

@item 
一個 @ref{1c7,,asyncio.Task} 的實例、

@item 
帶有 @code{_asyncio_future_blocking} 屬性的類 Future 物件 (Future-like object)。
@end itemize


在 3.5 版被加入.

@end deffn

@geindex ensure_future() (於 asyncio 模組中)
@anchor{library/asyncio-future asyncio ensure_future}@anchor{e6c}
@deffn {函式} asyncio.ensure_future (obj, *, loop=None)

回傳：


@itemize *

@item 
`obj' 引數會保持原樣，`obj' 須為 @ref{dc1,,Future}、@ref{1c7,,Task} 或類 Future 物件（可以用 @ref{3779,,isfuture()} 來進行檢查。）

@item 
包裝 (wrap) 了 `obj' 的 @ref{1c7,,Task} 物件，如果 `obj' 是一個協程 (coroutine) (可以用 @ref{69f,,iscoroutine()} 來進行檢查)；在此情況下該協程將透過 @code{ensure_future()} 來排程。

@item 
一個會等待 `obj' 的 @ref{1c7,,Task} 物件，`obj' 須為一個可等待物件（@ref{1013,,inspect.isawaitable()} 用於測試。)
@end itemize

如果 `obj' 不是上述物件的話會引發一個 @ref{198,,TypeError} 例外。

@cartouche
@quotation 重要 
將參照 (reference) 儲存至此函式的結果，用以防止任務在執行中消失。

請見 @ref{1c9,,create_task()} 函式，它是建立新 Task 的推薦方法。或者使用 @ref{4cc,,asyncio.TaskGroup}，它會在內部保留對 Task 的參照。
@end quotation
@end cartouche


在 3.5.1 版的變更: 這個函式接受任意 @ref{4c4,,awaitable} 物件。



在 3.10 版之後被棄用: 如果 `obj' 不是類 Future 物件且 `loop' 並未被指定，同時沒有正在執行的事件迴圈 (event loop)，則會發出棄用警告。

@end deffn

@geindex wrap_future() (於 asyncio 模組中)
@anchor{library/asyncio-future asyncio wrap_future}@anchor{1b7a}
@deffn {函式} asyncio.wrap_future (future, *, loop=None)

將一個 @ref{13b3,,concurrent.futures.Future} 物件包裝到 @ref{dc1,,asyncio.Future} 物件中。


在 3.10 版之後被棄用: 如果 `future' 不是類 Future 物件且 `loop' 未被指定，同時沒有正在執行的事件迴圈，則會發出棄用警告。

@end deffn

@node Future 物件<2>,,Future 函式,Futures
@anchor{library/asyncio-future asyncio-future-obj}@anchor{377a}@anchor{library/asyncio-future future-object}@anchor{377b}
@subsubsection Future 物件


@geindex Future (asyncio 中的類別)
@anchor{library/asyncio-future asyncio Future}@anchor{dc1}
@deffn {類別} asyncio.Future (*, loop=None)

一個 Future 代表一個非同步運算的最終結果。並不支援執行緒安全 (thread-safe)。

Future 是一個 @ref{4c4,,awaitable} 物件。協程可以等待 Future 物件直到它們有結果或例外被設置、或者被取消。一個 Future 可被多次等待而結果都會是相同的。

Future 通常用於讓低階基於回呼的程式（例如在協定實作中使用 asyncio @ref{3675,,transports}）能夠與高階 async/await 程式互動。

經驗法則為永遠不要在提供給使用者的 API 中公開 Future 物件，同時建議使用 @ref{e6f,,loop.create_future()} 來建立 Future 物件。如此一來，不同實作的事件迴圈可以注入自己最佳化實作的 Future 物件。


在 3.7 版的變更: 加入對 @ref{28,,contextvars} 模組的支援。



在 3.10 版之後被棄用: 如果未指定 `loop' 並且沒有正在執行的事件迴圈則會發出棄用警告。


@geindex result() (asyncio.Future 的方法)
@anchor{library/asyncio-future asyncio Future result}@anchor{377c}
@deffn {方法} result ()

回傳 Future 的結果。

如果 Future 狀態為 `done'（完成），並擁有 @ref{36a2,,set_result()} 方法設定的一個結果，則回傳該結果之值。

如果 Future 狀態為 `done'，並擁有 @ref{e73,,set_exception()} 方法設定的一個例外，那麼這個方法會引發該例外。

如果 Future 已被 `cancelled'（取消），此方法會引發一個 @ref{4cf,,CancelledError} 例外。

如果 Future 的結果還不可用，此方法會引發一個 @ref{36a5,,InvalidStateError} 例外。
@end deffn

@geindex set_result() (asyncio.Future 的方法)
@anchor{library/asyncio-future asyncio Future set_result}@anchor{36a2}
@deffn {方法} set_result (result)

將 Future 標記為 `done' 並設定其結果。

如果 Future 已經 `done' 則引發一個 @ref{36a5,,InvalidStateError} 錯誤。
@end deffn

@geindex set_exception() (asyncio.Future 的方法)
@anchor{library/asyncio-future asyncio Future set_exception}@anchor{e73}
@deffn {方法} set_exception (exception)

將 Future 標記為 `done' 並設定一個例外。

如果 Future 已經 `done' 則引發一個 @ref{36a5,,InvalidStateError} 錯誤。
@end deffn

@geindex done() (asyncio.Future 的方法)
@anchor{library/asyncio-future asyncio Future done}@anchor{377d}
@deffn {方法} done ()

如果 Future 已為 `done' 則回傳 @code{True}。

如果 Future 有被 `cancelled'、@ref{36a2,,set_result()} 有被呼叫來為其設定結果、或 @ref{e73,,set_exception()} 有被呼叫為其設定例外，那麼它就是 `done'。
@end deffn

@geindex cancelled() (asyncio.Future 的方法)
@anchor{library/asyncio-future asyncio Future cancelled}@anchor{377e}
@deffn {方法} cancelled ()

如果 Future 已經被 `cancelled' 則回傳 @code{True}。

這個方法通常在為 Future 設定結果或例外前用來確認它還沒被 `cancelled'：

@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{cf6}
@deffn {方法} add_done_callback (callback, *, context=None)

新增一個在 Future 為 `done' 時執行的回呼函式。

呼叫 `callback' 並附帶做為唯一引數的 Future 物件。

如果呼叫這個方法時 Future 已經為 `done'，回呼函式會被 @ref{cf2,,loop.call_soon()} 排程。

可選僅限關鍵字引數 `context' 用來指定一個讓 `callback' 執行於其中的客製化 @ref{177,,contextvars.Context} 物件。如果沒有提供 `context'，則使用目前情境。

可以用 @ref{217,,functools.partial()} 傳遞引數給回呼函式，例如：

@example
# Call 'print("Future:", fut)' when "fut" is done.
fut.add_done_callback(
    functools.partial(print, "Future:"))
@end example


在 3.7 版的變更: 加入僅限關鍵字參數 `context'。更多細節請參閱 
@geindex Python Enhancement Proposals; PEP 567
PEP 567@footnote{https://peps.python.org/pep-0567/}。

@end deffn

@geindex remove_done_callback() (asyncio.Future 的方法)
@anchor{library/asyncio-future asyncio Future remove_done_callback}@anchor{187c}
@deffn {方法} remove_done_callback (callback)

從回呼列表中移除 `callback'。

回傳被移除的回呼函式數量，通常為 1，除非一個回呼函式被多次加入。
@end deffn

@geindex cancel() (asyncio.Future 的方法)
@anchor{library/asyncio-future asyncio Future cancel}@anchor{1acf}
@deffn {方法} cancel (msg=None)

取消 Future 並為回呼函式排程。

如果 Future 已經是 `done' 或 `cancelled'，回傳 @code{False}。否則將 Future 狀態改為 `cancelled' 並在為回呼函式排程後回傳 @code{True}。


在 3.9 版的變更: 新增 `msg' 參數。

@end deffn

@geindex exception() (asyncio.Future 的方法)
@anchor{library/asyncio-future asyncio Future exception}@anchor{377f}
@deffn {方法} exception ()

回傳被設定於此 Future 的例外。

只有 Future 在 `done' 時才回傳例外（如果沒有設定例外則回傳 @code{None}）。

如果 Future 已被 `cancelled'（取消），此方法會引發一個 @ref{4cf,,CancelledError} 例外。

如果 Future 還不為 `done'，此方法會引發一個 @ref{36a5,,InvalidStateError} 例外。
@end deffn

@geindex get_loop() (asyncio.Future 的方法)
@anchor{library/asyncio-future asyncio Future get_loop}@anchor{cfe}
@deffn {方法} get_loop ()

回傳已被 Future 物件繫結 (bind) 的事件迴圈。


在 3.7 版被加入.

@end deffn
@end deffn
@anchor{library/asyncio-future asyncio-example-future}@anchor{3780}
這個例子建立一個 Future 物件，建立一個非同步 Task 並為其排程以設定 Future 結果，然後等待 Future 結果出現：

@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 重要 
該 Future 物件是為了模仿 @ref{13b3,,concurrent.futures.Future} 而設計。主要差異包含：


@itemize -

@item 
與 asyncio 的 Future 不同，@ref{13b3,,concurrent.futures.Future} 實例不可被等待。

@item 
@ref{377c,,asyncio.Future.result()} 和 @ref{377f,,asyncio.Future.exception()} 不接受 `timeout' 引數。

@item 
Future 不為 `done' 時 @ref{377c,,asyncio.Future.result()} 和 @ref{377f,,asyncio.Future.exception()} 會引發一個 @ref{36a5,,InvalidStateError} 例外。

@item 
使用 @ref{cf6,,asyncio.Future.add_done_callback()} 註冊的回呼函式不會立即呼叫，而是被 @ref{cf2,,loop.call_soon()} 排程。

@item 
asyncio Future 不能與 @ref{1b19,,concurrent.futures.wait()} 和 @ref{191a,,concurrent.futures.as_completed()} 函式相容。

@item 
@ref{1acf,,asyncio.Future.cancel()} 接受一個可選的 @code{msg} 引數，但 @ref{359e,,concurrent.futures.Future.cancel()} 無此引數。
@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 傳輸與協定,Policies,Futures,asyncio --- 非同步 I/O
@anchor{library/asyncio-protocol doc}@anchor{3781}@anchor{library/asyncio-protocol asyncio-transports-protocols}@anchor{3675}@anchor{library/asyncio-protocol translation-repo}@anchor{3782}@anchor{library/asyncio-protocol transports-and-protocols}@anchor{3783}
@subsubsection 傳輸與協定


@subsubheading 前言


Transports and Protocols are used by the `low-level' event loop
APIs such as @ref{811,,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{3784,,Transports} and @ref{3785,,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{811,,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 目錄


This documentation page contains the following sections:


@itemize *

@item 
The @ref{3784,,Transports} section documents asyncio @ref{3786,,BaseTransport},
@ref{375b,,ReadTransport}, @ref{375c,,WriteTransport}, @ref{3787,,Transport},
@ref{1a68,,DatagramTransport}, and @ref{3769,,SubprocessTransport}
classes.

@item 
The @ref{3785,,Protocols} section documents asyncio @ref{3788,,BaseProtocol},
@ref{3789,,Protocol}, @ref{c8b,,BufferedProtocol},
@ref{8d6,,DatagramProtocol}, and @ref{3768,,SubprocessProtocol} classes.

@item 
The @ref{378a,,Examples} section showcases how to work with transports,
protocols, and low-level event loop APIs.
@end itemize

@menu
* Transports:: 
* Protocols: Protocols<2>. 
* 範例: 範例<25>. 

@end menu

@node Transports,Protocols<2>,,傳輸與協定
@anchor{library/asyncio-protocol asyncio-transport}@anchor{3748}@anchor{library/asyncio-protocol transports}@anchor{3784}
@subsubsection Transports


`原始碼：'Lib/asyncio/transports.py@footnote{https://github.com/python/cpython/tree/3.14/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{f71,,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{369d,,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{378b}
@subsubsection Transports Hierarchy


@geindex BaseTransport (asyncio 中的類別)
@anchor{library/asyncio-protocol asyncio BaseTransport}@anchor{3786}
@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{375c}
@deffn {類別} asyncio.WriteTransport (BaseTransport)

A base transport for write-only connections.

Instances of the `WriteTransport' class are returned from
the @ref{36fc,,loop.connect_write_pipe()} event loop method and
are also used by subprocess-related methods like
@ref{36f8,,loop.subprocess_exec()}.
@end deffn

@geindex ReadTransport (asyncio 中的類別)
@anchor{library/asyncio-protocol asyncio ReadTransport}@anchor{375b}
@deffn {類別} asyncio.ReadTransport (BaseTransport)

A base transport for read-only connections.

Instances of the `ReadTransport' class are returned from
the @ref{36fb,,loop.connect_read_pipe()} event loop method and
are also used by subprocess-related methods like
@ref{36f8,,loop.subprocess_exec()}.
@end deffn

@geindex Transport (asyncio 中的類別)
@anchor{library/asyncio-protocol asyncio Transport}@anchor{3787}
@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{811,,loop.create_connection()},
@ref{36b4,,loop.create_unix_connection()},
@ref{d01,,loop.create_server()}, @ref{3751,,loop.sendfile()}, etc.
@end deffn

@geindex DatagramTransport (asyncio 中的類別)
@anchor{library/asyncio-protocol asyncio DatagramTransport}@anchor{1a68}
@deffn {類別} asyncio.DatagramTransport (BaseTransport)

A transport for datagram (UDP) connections.

Instances of the `DatagramTransport' class are returned from
the @ref{934,,loop.create_datagram_endpoint()} event loop method.
@end deffn

@geindex SubprocessTransport (asyncio 中的類別)
@anchor{library/asyncio-protocol asyncio SubprocessTransport}@anchor{3769}
@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{36f9,,loop.subprocess_shell()} and
@ref{36f8,,loop.subprocess_exec()}.
@end deffn

@node Base Transport,Read-only Transports,Transports Hierarchy,Transports
@anchor{library/asyncio-protocol base-transport}@anchor{378c}
@subsubsection Base Transport


@geindex close() (asyncio.BaseTransport 的方法)
@anchor{library/asyncio-protocol asyncio BaseTransport close}@anchor{374b}
@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{378d,,protocol.connection_lost()} method will be called with
@ref{87e,,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{e6e}
@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{c8a}
@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{378e,,socket.socket.getpeername()}
(@code{None} on error)

@item 
@code{'socket'}: @ref{f9c,,socket.socket} instance

@item 
@code{'sockname'}: the socket's own address,
result of @ref{284,,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{1346,,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{378f,,ssl.SSLSocket.cipher()}

@item 
@code{'peercert'}: peer certificate; result of
@ref{11b3,,ssl.SSLSocket.getpeercert()}

@item 
@code{'sslcontext'}: @ref{355,,ssl.SSLContext} instance

@item 
@code{'ssl_object'}: @ref{d72,,ssl.SSLObject} or
@ref{ade,,ssl.SSLSocket} instance
@end itemize

@item 
pipe:


@itemize -

@item 
@code{'pipe'}: pipe object
@end itemize

@item 
subprocess:


@itemize -

@item 
@code{'subprocess'}: @ref{4b2,,subprocess.Popen} instance
@end itemize
@end itemize
@end deffn

@geindex set_protocol() (asyncio.BaseTransport 的方法)
@anchor{library/asyncio-protocol asyncio BaseTransport set_protocol}@anchor{3790}
@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{3791}
@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{3792}
@subsubsection Read-only Transports


@geindex is_reading() (asyncio.ReadTransport 的方法)
@anchor{library/asyncio-protocol asyncio ReadTransport is_reading}@anchor{d09}
@deffn {方法} ReadTransport.is_reading ()

Return @code{True} if the transport is receiving new data.


在 3.7 版被加入.

@end deffn

@geindex pause_reading() (asyncio.ReadTransport 的方法)
@anchor{library/asyncio-protocol asyncio ReadTransport pause_reading}@anchor{d0b}
@deffn {方法} ReadTransport.pause_reading ()

Pause the receiving end of the transport.  No data will be passed to
the protocol's @ref{1a48,,protocol.data_received()}
method until @ref{d0a,,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{d0a}
@deffn {方法} ReadTransport.resume_reading ()

Resume the receiving end.  The protocol's
@ref{1a48,,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{3793}
@subsubsection Write-only Transports


@geindex abort() (asyncio.WriteTransport 的方法)
@anchor{library/asyncio-protocol asyncio WriteTransport abort}@anchor{3794}
@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{378d,,protocol.connection_lost()} method will eventually be
called with @ref{87e,,None} as its argument.
@end deffn

@geindex can_write_eof() (asyncio.WriteTransport 的方法)
@anchor{library/asyncio-protocol asyncio WriteTransport can_write_eof}@anchor{3795}
@deffn {方法} WriteTransport.can_write_eof ()

Return @ref{e02,,True} if the transport supports
@ref{3796,,write_eof()}, @ref{d23,,False} if not.
@end deffn

@geindex get_write_buffer_size() (asyncio.WriteTransport 的方法)
@anchor{library/asyncio-protocol asyncio WriteTransport get_write_buffer_size}@anchor{3797}
@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{fbf}
@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{3798,,set_write_buffer_limits()} to set the limits.


在 3.4.2 版被加入.

@end deffn

@geindex set_write_buffer_limits() (asyncio.WriteTransport 的方法)
@anchor{library/asyncio-protocol asyncio WriteTransport set_write_buffer_limits}@anchor{3798}
@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{3799,,protocol.pause_writing()}
and @ref{379a,,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{3799,,pause_writing()} is called when the buffer size
becomes greater than or equal to the `high' value. If writing has
been paused, @ref{379a,,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{3799,,pause_writing()} to be called
whenever the buffer becomes non-empty.  Setting `low' to zero causes
@ref{379a,,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{fbf,,get_write_buffer_limits()}
to get the limits.
@end deffn

@geindex write() (asyncio.WriteTransport 的方法)
@anchor{library/asyncio-protocol asyncio WriteTransport write}@anchor{1760}
@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{175f}
@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{1760,,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{3796}
@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{369,,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{379b}
@subsubsection Datagram Transports


@geindex sendto() (asyncio.DatagramTransport 的方法)
@anchor{library/asyncio-protocol asyncio DatagramTransport sendto}@anchor{4c6}
@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{87e,,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{379c}
@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{378d,,protocol.connection_lost()}
method will eventually be called with @ref{87e,,None} as its argument.
@end deffn

@node Subprocess Transports,,Datagram Transports,Transports
@anchor{library/asyncio-protocol asyncio-subprocess-transports}@anchor{36fd}@anchor{library/asyncio-protocol subprocess-transports}@anchor{379d}
@subsubsection Subprocess Transports


@geindex get_pid() (asyncio.SubprocessTransport 的方法)
@anchor{library/asyncio-protocol asyncio SubprocessTransport get_pid}@anchor{379e}
@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{379f}
@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{87e,,None} if the subprocess was not created with @code{stdin=PIPE}

@item 
@code{1}: readable streaming transport of the standard output (`stdout'),
or @ref{87e,,None} if the subprocess was not created with @code{stdout=PIPE}

@item 
@code{2}: readable streaming transport of the standard error (`stderr'),
or @ref{87e,,None} if the subprocess was not created with @code{stderr=PIPE}

@item 
other `fd': @ref{87e,,None}
@end itemize
@end deffn

@geindex get_returncode() (asyncio.SubprocessTransport 的方法)
@anchor{library/asyncio-protocol asyncio SubprocessTransport get_returncode}@anchor{37a0}
@deffn {方法} SubprocessTransport.get_returncode ()

Return the subprocess return code as an integer or @ref{87e,,None}
if it hasn't returned, which is similar to the
@ref{c7a,,subprocess.Popen.returncode} attribute.
@end deffn

@geindex kill() (asyncio.SubprocessTransport 的方法)
@anchor{library/asyncio-protocol asyncio SubprocessTransport kill}@anchor{37a1}
@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{37a2,,terminate()}.

另請參閱 @ref{15d4,,subprocess.Popen.kill()}。
@end deffn

@geindex send_signal() (asyncio.SubprocessTransport 的方法)
@anchor{library/asyncio-protocol asyncio SubprocessTransport send_signal}@anchor{37a3}
@deffn {方法} SubprocessTransport.send_signal (signal)

Send the `signal' number to the subprocess, as in
@ref{15d5,,subprocess.Popen.send_signal()}.
@end deffn

@geindex terminate() (asyncio.SubprocessTransport 的方法)
@anchor{library/asyncio-protocol asyncio SubprocessTransport terminate}@anchor{37a2}
@deffn {方法} SubprocessTransport.terminate ()

Stop the subprocess.

On POSIX systems, this method sends @ref{15d6,,SIGTERM} to the subprocess.
On Windows, the Windows API function @code{TerminateProcess()} is called to
stop the subprocess.

另請參閱 @ref{15d3,,subprocess.Popen.terminate()}。
@end deffn

@geindex close() (asyncio.SubprocessTransport 的方法)
@anchor{library/asyncio-protocol asyncio SubprocessTransport close}@anchor{37a4}
@deffn {方法} SubprocessTransport.close ()

Kill the subprocess by calling the @ref{37a1,,kill()} method.

If the subprocess hasn't returned yet, and close transports of
`stdin', `stdout', and `stderr' pipes.
@end deffn

@node Protocols<2>,範例<25>,Transports,傳輸與協定
@anchor{library/asyncio-protocol asyncio-protocol}@anchor{3747}@anchor{library/asyncio-protocol protocols}@anchor{3785}
@subsubsection Protocols


`原始碼：'Lib/asyncio/protocols.py@footnote{https://github.com/python/cpython/tree/3.14/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{3748,,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{37a5}
@subsubsection Base Protocols


@geindex BaseProtocol (asyncio 中的類別)
@anchor{library/asyncio-protocol asyncio BaseProtocol}@anchor{3788}
@deffn {類別} asyncio.BaseProtocol

Base protocol with methods that all protocols share.
@end deffn

@geindex Protocol (asyncio 中的類別)
@anchor{library/asyncio-protocol asyncio Protocol}@anchor{3789}
@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{c8b}
@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}@anchor{8d6}
@deffn {類別} asyncio.DatagramProtocol (BaseProtocol)

The base class for implementing datagram (UDP) protocols.
@end deffn

@geindex SubprocessProtocol (asyncio 中的類別)
@anchor{library/asyncio-protocol asyncio SubprocessProtocol}@anchor{3768}
@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{37a6}
@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{3749}
@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{378d}
@deffn {方法} BaseProtocol.connection_lost (exc)

Called when the connection is lost or closed.

The argument is either an exception object or @ref{87e,,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{3798,,set_write_buffer_limits()}
method for more details.

@geindex pause_writing() (asyncio.BaseProtocol 的方法)
@anchor{library/asyncio-protocol asyncio BaseProtocol pause_writing}@anchor{3799}
@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{379a}
@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{3799,,pause_writing()} is not called: the buffer size must
go strictly over.

Conversely, @ref{379a,,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{37a7}
@subsubsection Streaming Protocols


Event methods, such as @ref{d01,,loop.create_server()},
@ref{4c5,,loop.create_unix_server()}, @ref{811,,loop.create_connection()},
@ref{36b4,,loop.create_unix_connection()}, @ref{9d7,,loop.connect_accepted_socket()},
@ref{36fb,,loop.connect_read_pipe()}, and @ref{36fc,,loop.connect_write_pipe()}
accept factories that return streaming protocols.

@geindex data_received() (asyncio.Protocol 的方法)
@anchor{library/asyncio-protocol asyncio Protocol data_received}@anchor{1a48}
@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{37a8,,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{37a8}
@deffn {方法} Protocol.eof_received ()

Called when the other end signals it won't send any more data
(for example by calling @ref{3796,,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{37a9}
@subsubsection Buffered Streaming Protocols



在 3.7 版被加入.


Buffered Protocols can be used with any event loop method
that supports @ref{37a7,,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{c8b,,BufferedProtocol}
instances:

@geindex get_buffer() (asyncio.BufferedProtocol 的方法)
@anchor{library/asyncio-protocol asyncio BufferedProtocol get_buffer}@anchor{37aa}
@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{260,,buffer protocol}.
@end deffn

@geindex buffer_updated() (asyncio.BufferedProtocol 的方法)
@anchor{library/asyncio-protocol asyncio BufferedProtocol buffer_updated}@anchor{37ab}
@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{37ac}
@deffn {方法} BufferedProtocol.eof_received ()

See the documentation of the @ref{37a8,,protocol.eof_received()} method.
@end deffn

@ref{37aa,,get_buffer()} can be called an arbitrary number
of times during a connection.  However, @ref{37a8,,protocol.eof_received()} is called at most once
and, if called, @ref{37aa,,get_buffer()} and
@ref{37ab,,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{37ad}
@subsubsection Datagram Protocols


Datagram Protocol instances should be constructed by protocol
factories passed to the @ref{934,,loop.create_datagram_endpoint()} method.

@geindex datagram_received() (asyncio.DatagramProtocol 的方法)
@anchor{library/asyncio-protocol asyncio DatagramProtocol datagram_received}@anchor{37ae}
@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{37af}
@deffn {方法} DatagramProtocol.error_received (exc)

Called when a previous send or receive operation raises an
@ref{2c0,,OSError}.  `exc' is the @ref{2c0,,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{2c0,,OSError} with @code{errno} set to @ref{1aa0,,errno.ENOBUFS} may
or may not be raised; if it is raised, it will be reported to
@ref{37af,,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{36fe}@anchor{library/asyncio-protocol subprocess-protocols}@anchor{37b0}
@subsubsection Subprocess Protocols


Subprocess Protocol instances should be constructed by protocol
factories passed to the @ref{36f8,,loop.subprocess_exec()} and
@ref{36f9,,loop.subprocess_shell()} methods.

@geindex pipe_data_received() (asyncio.SubprocessProtocol 的方法)
@anchor{library/asyncio-protocol asyncio SubprocessProtocol pipe_data_received}@anchor{1a7f}
@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{37b1}
@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{1a7e}
@deffn {方法} SubprocessProtocol.process_exited ()

Called when the child process has exited.

It can be called before @ref{1a7f,,pipe_data_received()} and
@ref{37b1,,pipe_connection_lost()} methods.
@end deffn

@node 範例<25>,,Protocols<2>,傳輸與協定
@anchor{library/asyncio-protocol examples}@anchor{378a}
@subsubsection 範例


@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,,範例<25>
@anchor{library/asyncio-protocol asyncio-example-tcp-echo-server-protocol}@anchor{36c9}@anchor{library/asyncio-protocol tcp-echo-server}@anchor{37b2}
@subsubsection TCP Echo Server


Create a TCP echo server using the @ref{d01,,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{36c7,,TCP echo server using streams}
example uses the high-level @ref{d07,,asyncio.start_server()} function.


@node TCP Echo Client,UDP Echo Server,TCP Echo Server,範例<25>
@anchor{library/asyncio-protocol asyncio-example-tcp-echo-client-protocol}@anchor{36c6}@anchor{library/asyncio-protocol tcp-echo-client}@anchor{37b3}
@subsubsection TCP Echo Client


A TCP echo client using the @ref{811,,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{36c4,,TCP echo client using streams}
example uses the high-level @ref{d06,,asyncio.open_connection()} function.


@node UDP Echo Server,UDP Echo Client,TCP Echo Client,範例<25>
@anchor{library/asyncio-protocol asyncio-udp-echo-server-protocol}@anchor{374d}@anchor{library/asyncio-protocol udp-echo-server}@anchor{37b4}
@subsubsection UDP Echo Server


A UDP echo server, using the @ref{934,,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,範例<25>
@anchor{library/asyncio-protocol asyncio-udp-echo-client-protocol}@anchor{374c}@anchor{library/asyncio-protocol udp-echo-client}@anchor{37b5}
@subsubsection UDP Echo Client


A UDP echo client, using the @ref{934,,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,範例<25>
@anchor{library/asyncio-protocol asyncio-example-create-connection}@anchor{36cd}@anchor{library/asyncio-protocol connecting-existing-sockets}@anchor{37b6}
@subsubsection Connecting Existing Sockets


Wait until a socket receives data using the
@ref{811,,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{36ce,,watch a file descriptor for read events} example uses the low-level
@ref{36cf,,loop.add_reader()} method to register an FD.

The @ref{36cb,,register an open socket to wait for data using streams} example uses high-level streams
created by the @ref{d06,,open_connection()} function in a coroutine.


@node loop subprocess_exec and SubprocessProtocol,,Connecting Existing Sockets,範例<25>
@anchor{library/asyncio-protocol asyncio-example-subprocess-proto}@anchor{370d}@anchor{library/asyncio-protocol loop-subprocess-exec-and-subprocessprotocol}@anchor{37b7}
@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{36f8,,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; print(datetime.datetime.now())'
    exit_future = asyncio.Future(loop=loop)

    # Create the subprocess controlled by DateProtocol;
    # redirect the standard output into a pipe.
    transport, protocol = await loop.subprocess_exec(
        lambda: DateProtocol(exit_future),
        sys.executable, '-c', code,
        stdin=None, stderr=None)

    # Wait for the subprocess exit using the process_exited()
    # method of the protocol.
    await exit_future

    # Close the stdout pipe.
    transport.close()

    # Read the output which was collected by the
    # pipe_data_received() method of the protocol.
    data = bytes(protocol.output)
    return data.decode('ascii').rstrip()

date = asyncio.run(get_date())
print(f"Current date: @{date@}")
@end example

See also the @ref{370c,,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,平臺支援,傳輸與協定,asyncio --- 非同步 I/O
@anchor{library/asyncio-policy doc}@anchor{37b8}@anchor{library/asyncio-policy asyncio-policies}@anchor{3735}@anchor{library/asyncio-policy policies}@anchor{37b9}@anchor{library/asyncio-policy translation-repo}@anchor{37ba}
@subsubsection Policies


@cartouche
@quotation 警告 
Policies are deprecated and will be removed in Python 3.16.
Users are encouraged to use the @ref{2f2,,asyncio.run()} function
or the @ref{2f4,,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{f71,,event loop},
as well as create new event loops.
The default policy can be @ref{37bb,,replaced} with
@ref{37bc,,built-in alternatives}
to use different event loop implementations,
or substituted by a @ref{37bd,,custom policy}
that can override these behaviors.

The @ref{37be,,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{2f1,,get_event_loop()}, @ref{1a84,,set_event_loop()}, and @ref{367b,,new_event_loop()}.

Policy objects should implement the APIs defined
in the @ref{30d,,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{37bb}@anchor{library/asyncio-policy getting-and-setting-the-policy}@anchor{37bf}
@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{311}
@deffn {函式} asyncio.get_event_loop_policy ()

Return the current process-wide policy.


在 3.14 版之後被棄用: The @ref{311,,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{312}
@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 @ref{312,,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{37be}@anchor{library/asyncio-policy policy-objects}@anchor{37c0}
@subsubsection Policy Objects


The abstract event loop policy base class is defined as follows:

@geindex AbstractEventLoopPolicy (asyncio 中的類別)
@anchor{library/asyncio-policy asyncio AbstractEventLoopPolicy}@anchor{30d}
@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{37c1}
@deffn {方法} get_event_loop ()

Get the event loop for the current context.

Return an event loop object implementing the
@ref{b4f,,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{37c2}
@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{37c3}
@deffn {方法} new_event_loop ()

Create and return a new event loop object.

This method should never return @code{None}.
@end deffn


在 3.14 版之後被棄用: The @ref{30d,,AbstractEventLoopPolicy} class is deprecated and
will be removed in Python 3.16.

@end deffn
@anchor{library/asyncio-policy asyncio-policy-builtin}@anchor{37bc}
asyncio ships with the following built-in policies:

@geindex DefaultEventLoopPolicy (asyncio 中的類別)
@anchor{library/asyncio-policy asyncio DefaultEventLoopPolicy}@anchor{30e}
@deffn {類別} asyncio.DefaultEventLoopPolicy

The default asyncio policy.  Uses @ref{313,,SelectorEventLoop}
on Unix and @ref{816,,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{816,,ProactorEventLoop} is now used by default.



在 3.14 版的變更: The @ref{2f1,,get_event_loop()} method of the default asyncio policy now
raises a @ref{244,,RuntimeError} if there is no set event loop.



在 3.14 版之後被棄用: The @ref{30e,,DefaultEventLoopPolicy} class is deprecated and
will be removed in Python 3.16.

@end deffn

@geindex WindowsSelectorEventLoopPolicy (asyncio 中的類別)
@anchor{library/asyncio-policy asyncio WindowsSelectorEventLoopPolicy}@anchor{30f}
@deffn {類別} asyncio.WindowsSelectorEventLoopPolicy

An alternative event loop policy that uses the
@ref{313,,SelectorEventLoop} event loop implementation.

@ref{2006,,可用性}: Windows.


在 3.14 版之後被棄用: The @ref{30f,,WindowsSelectorEventLoopPolicy} class is deprecated and
will be removed in Python 3.16.

@end deffn

@geindex WindowsProactorEventLoopPolicy (asyncio 中的類別)
@anchor{library/asyncio-policy asyncio WindowsProactorEventLoopPolicy}@anchor{310}
@deffn {類別} asyncio.WindowsProactorEventLoopPolicy

An alternative event loop policy that uses the
@ref{816,,ProactorEventLoop} event loop implementation.

@ref{2006,,可用性}: Windows.


在 3.14 版之後被棄用: The @ref{310,,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{37bd}@anchor{library/asyncio-policy custom-policies}@anchor{37c4}
@subsubsection Custom Policies


To implement a new event loop policy, it is recommended to subclass
@ref{30e,,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 平臺支援,擴充,Policies,asyncio --- 非同步 I/O
@anchor{library/asyncio-platforms doc}@anchor{37c5}@anchor{library/asyncio-platforms asyncio-platform-support}@anchor{3757}@anchor{library/asyncio-platforms platform-support}@anchor{37c6}@anchor{library/asyncio-platforms translation-repo}@anchor{37c7}
@subsubsection 平臺支援


@ref{b,,asyncio} module（模組）被設計為可攜的 (portable)，但由於平臺的底層架構和功能不同，在一些平臺上存在細微的差異和限制。

@menu
* 所有平台:: 
* Windows: Windows<82>. 
* macOS: macOS<51>. 

@end menu

@node 所有平台,Windows<82>,,平臺支援
@anchor{library/asyncio-platforms all-platforms}@anchor{37c8}
@subsubsection 所有平台



@itemize *

@item 
@ref{36cf,,loop.add_reader()} 和 @ref{3755,,loop.add_writer()} 不能用來監視檔案 I/O。
@end itemize

@node Windows<82>,macOS<51>,所有平台,平臺支援
@anchor{library/asyncio-platforms windows}@anchor{37c9}
@subsubsection Windows


`原始碼：'Lib/asyncio/proactor_events.py、source:`Lib/asyncio/windows_events.py、source:`Lib/asyncio/windows_utils.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/asyncio/proactor_events.py、source:`Lib/asyncio/windows_events.py、source:`Lib/asyncio/windows_utils.py}


__________________________________________________________________



在 3.8 版的變更: 在 Windows 上，現在 @ref{816,,ProactorEventLoop} 是預設的事件迴圈。


Windows 上的所有事件迴圈都不支援以下 method（方法）：


@itemize *

@item 
不支援 @ref{36b4,,loop.create_unix_connection()} 和 @ref{4c5,,loop.create_unix_server()}。@ref{1ad5,,socket.AF_UNIX} socket 系列常數僅限於 Unix 上使用。

@item 
不支援 @ref{375e,,loop.add_signal_handler()} 和 @ref{375f,,loop.remove_signal_handler()}。
@end itemize

@ref{313,,SelectorEventLoop} 有以下限制：


@itemize *

@item 
@ref{37ca,,SelectSelector} 只被用於等待 socket 事件：它支援 socket 且最多支援 512 個 socket。

@item 
@ref{36cf,,loop.add_reader()} 和 @ref{3755,,loop.add_writer()} 只接受 socket 處理函式（例如不支援 pipe 檔案描述器 (pipe file descriptor)）。

@item 
因為不支援 pipe，所以 @ref{36fb,,loop.connect_read_pipe()} 和 @ref{36fc,,loop.connect_write_pipe()} method 沒有被實作出來。

@item 
不支援@ref{366f,,子行程 (subprocess)}，也就是說 @ref{36f8,,loop.subprocess_exec()} 和 @ref{36f9,,loop.subprocess_shell()} method 沒有被實作出來。
@end itemize

@ref{816,,ProactorEventLoop} 有以下限制：


@itemize *

@item 
不支援 @ref{36cf,,loop.add_reader()} 和 @ref{3755,,loop.add_writer()} method。
@end itemize

Windows 上單調時鐘 (monotonic clock) 的解析度大約為 15.6 毫秒。最佳的解析度是 0.5 毫秒。解析度和硬體（HPET@footnote{https://zh.wikipedia.org/wiki/高精度事件計時器} 是否可用）與 Windows 的設定有關。

@menu
* Windows 的子行程支援:: 

@end menu

@node Windows 的子行程支援,,,Windows<82>
@anchor{library/asyncio-platforms asyncio-windows-subprocess}@anchor{36fa}@anchor{library/asyncio-platforms subprocess-support-on-windows}@anchor{37cb}
@subsubsection Windows 的子行程支援


在 Windows 上，預設的事件迴圈 @ref{816,,ProactorEventLoop} 支援子行程，而 @ref{313,,SelectorEventLoop} 則不支援。

@node macOS<51>,,Windows<82>,平臺支援
@anchor{library/asyncio-platforms macos}@anchor{37cc}
@subsubsection macOS


完整支援現在普遍流行的 macOS 版本。

@subsubheading macOS <= 10.8


在 macOS 10.6、10.7 和 10.8 上，預設的事件迴圈是使用 @ref{37cd,,selectors.KqueueSelector}，在這些版本上它並不支援字元裝置 (character device)。可以手工設置 @ref{313,,SelectorEventLoop} 來使用 @ref{37ca,,SelectSelector} 或 @ref{dcc,,PollSelector} 以在這些舊版 macOS 上支援字元裝置。例如：

@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 擴充,高階 API 索引,平臺支援,asyncio --- 非同步 I/O
@anchor{library/asyncio-extending doc}@anchor{37ce}@anchor{library/asyncio-extending extending}@anchor{37cf}@anchor{library/asyncio-extending translation-repo}@anchor{37d0}
@subsubsection 擴充


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,,擴充
@anchor{library/asyncio-extending writing-a-custom-event-loop}@anchor{37d1}
@subsubsection Writing a Custom Event Loop


@ref{b4f,,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,擴充
@anchor{library/asyncio-extending future-and-task-private-constructors}@anchor{37d2}
@subsubsection Future and Task private constructors


@ref{dc1,,asyncio.Future} and @ref{1c7,,asyncio.Task} should be never created directly,
please use corresponding @ref{e6f,,loop.create_future()} and @ref{1ca,,loop.create_task()},
or @ref{1c9,,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{37d3}
@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{37d4}
@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{1ca,,loop.create_task()} description.


在 3.11 版的變更: `context' argument is added.

@end deffn

@node Task lifetime support,,Future and Task private constructors,擴充
@anchor{library/asyncio-extending task-lifetime-support}@anchor{37d5}
@subsubsection Task lifetime support


A third party task implementation should call the following functions to keep a task
visible by @ref{b46,,asyncio.all_tasks()} and @ref{69e,,asyncio.current_task()}:

@geindex _register_task() (於 asyncio 模組中)
@anchor{library/asyncio-extending asyncio _register_task}@anchor{37d6}
@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{37d7}
@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{37d8}
@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{22c8,,coroutine.send()} or @ref{714,,coroutine.throw()}).
@end deffn

@geindex _leave_task() (於 asyncio 模組中)
@anchor{library/asyncio-extending asyncio _leave_task}@anchor{37d9}
@deffn {函式} asyncio._leave_task (loop, task)

Switch the current task back from `task' to @code{None}.

Call the function just after @ref{22c8,,coroutine.send()} or @ref{714,,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 高階 API 索引,低階 API 索引,擴充,asyncio --- 非同步 I/O
@anchor{library/asyncio-api-index doc}@anchor{a70}@anchor{library/asyncio-api-index high-level-api-index}@anchor{37da}@anchor{library/asyncio-api-index translation-repo}@anchor{37db}
@subsubsection 高階 API 索引


這個頁面列出了所有能使用 async/wait 的高階 asyncio API。

@menu
* 任務 (Tasks): 任務 Tasks. 
* 佇列 (Queues): 佇列 Queues<2>. 
* 子行程 (Subprocesses): 子行程 Subprocesses. 
* 串流 (Streams): 串流 Streams. 
* 同步化 (Synchronization): 同步化 Synchronization. 
* 例外: 例外<15>. 

@end menu

@node 任務 Tasks,佇列 Queues<2>,,高階 API 索引
@anchor{library/asyncio-api-index tasks}@anchor{37dc}
@subsubsection 任務 (Tasks)


用於執行非同步程式、建立 Task 物件、帶有超時 (timeout) 設定地等待多個事件的工具程式。


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{2f2,,run()}

@tab

建立事件迴圈 (event loop)、執行一個協程 (coroutine)、關閉事件迴圈。

@item

@ref{2f4,,Runner}

@tab

A context manager that simplifies multiple async function calls.

@item

@ref{1c7,,Task}

@tab

Task 物件。

@item

@ref{4cc,,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{1c9,,create_task()}

@tab

啟動一個 asyncio 的 Task 物件，然後回傳它。

@item

@ref{69e,,current_task()}

@tab

回傳目前 Task 物件。

@item

@ref{b46,,all_tasks()}

@tab

回傳事件迴圈中所有未完成的 task 物件。

@item

@code{await} @ref{c5b,,sleep()}

@tab

休眠數秒鐘。

@item

@code{await} @ref{80c,,gather()}

@tab

並行 (concurrent) 地執行事件的排程與等待。

@item

@code{await} @ref{80e,,wait_for()}

@tab

有超時設置的執行。

@item

@code{await} @ref{c5c,,shield()}

@tab

屏蔽取消操作。

@item

@code{await} @ref{6a0,,wait()}

@tab

監控完成情況。

@item

@ref{80d,,timeout()}

@tab

Run with a timeout. Useful in cases when @code{wait_for} is not suitable.

@item

@ref{adc,,to_thread()}

@tab

在不同的 OS 執行緒 (thread) 中非同步地執行一個函式。

@item

@ref{a79,,run_coroutine_threadsafe()}

@tab

從其他 OS 執行緒中為一個協程排程。

@item

@code{for in} @ref{4c1,,as_completed()}

@tab

用 @code{for} 迴圈來監控完成情況。

@end multitable


@subsubheading 範例



@itemize *

@item 
@ref{368e,,使用 asyncio.gather() 平行 (parallel) 執行}。

@item 
@ref{3696,,使用 asyncio.wait_for() 強制設置超時}。

@item 
@ref{36ab,,取消任務}。

@item 
@ref{368c,,使用 asyncio.sleep()}。

@item 
請參閱 @ref{366d,,Tasks 文件頁面}。
@end itemize

@node 佇列 Queues<2>,子行程 Subprocesses,任務 Tasks,高階 API 索引
@anchor{library/asyncio-api-index queues}@anchor{37dd}
@subsubsection 佇列 (Queues)


佇列應被用於為多個 asyncio Task 物件分配工作、實作 connection pools（連線池）以及 pub/sub（發行/訂閱）模式。


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{c61,,Queue}

@tab

一個先進先出 (FIFO) 佇列。

@item

@ref{371e,,PriorityQueue}

@tab

一個優先佇列 (priority queue)。

@item

@ref{3720,,LifoQueue}

@tab

一個後進先出 (LIFO) 佇列。

@end multitable


@subsubheading 範例



@itemize *

@item 
@ref{3722,,使用 asyncio.Queue 為多個 Task 分配工作}。

@item 
請參閱@ref{3670,,佇列文件頁面}。
@end itemize

@node 子行程 Subprocesses,串流 Streams,佇列 Queues<2>,高階 API 索引
@anchor{library/asyncio-api-index subprocesses}@anchor{37de}
@subsubsection 子行程 (Subprocesses)


用於衍生（spawn）子行程和執行 shell 指令的工具程式。


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@code{await} @ref{c62,,create_subprocess_exec()}

@tab

建立一個子行程。

@item

@code{await} @ref{c63,,create_subprocess_shell()}

@tab

執行一個 shell 命令。

@end multitable


@subsubheading 範例



@itemize *

@item 
@ref{36f2,,執行一個 shell 指令}。

@item 
請參閱@ref{366f,,子行程 APIs} 相關文件。
@end itemize

@node 串流 Streams,同步化 Synchronization,子行程 Subprocesses,高階 API 索引
@anchor{library/asyncio-api-index streams}@anchor{37df}
@subsubsection 串流 (Streams)


用於網路 IO 處理的高階 API。


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@code{await} @ref{d06,,open_connection()}

@tab

建立一個 TCP 連線。

@item

@code{await} @ref{36b3,,open_unix_connection()}

@tab

建立一個 Unix socket 連線。

@item

@code{await} @ref{d07,,start_server()}

@tab

啟動一個 TCP 伺服器。

@item

@code{await} @ref{36b5,,start_unix_server()}

@tab

啟動一個 Unix socket 伺服器。

@item

@ref{1b7b,,StreamReader}

@tab

接收網路資料的高階 async/await 物件。

@item

@ref{19c2,,StreamWriter}

@tab

傳送網路資料的高階 async/await 物件。

@end multitable


@subsubheading 範例



@itemize *

@item 
@ref{36af,,TCP 用戶端範例}。

@item 
請參閱@ref{366e,,串流 APIs} 文件。
@end itemize

@node 同步化 Synchronization,例外<15>,串流 Streams,高階 API 索引
@anchor{library/asyncio-api-index synchronization}@anchor{37e0}
@subsubsection 同步化 (Synchronization)


類似執行緒且能被用於 Task 中的同步化原始物件 (primitive)。


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{c5d,,Lock}

@tab

一個互斥鎖 (mutex lock)。

@item

@ref{2f3,,Event}

@tab

一個事件物件。

@item

@ref{c5e,,Condition}

@tab

一個條件物件。

@item

@ref{c5f,,Semaphore}

@tab

一個旗號 (semaphore) 物件。

@item

@ref{c60,,BoundedSemaphore}

@tab

一個有界的旗號物件。

@item

@ref{80f,,Barrier}

@tab

一個屏障物件。

@end multitable


@subsubheading 範例



@itemize *

@item 
@ref{36db,,使用 asyncio.Event}。

@item 
@ref{36e9,,使用 asyncio.Barrier}。

@item 
請參閱 asyncio 關於@ref{3671,,同步化原始物件}的文件。
@end itemize

@node 例外<15>,,同步化 Synchronization,高階 API 索引
@anchor{library/asyncio-api-index exceptions}@anchor{37e1}
@subsubsection 例外



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{4cf,,asyncio.CancelledError}

@tab

當一 Task 物件被取消時被引發。請參閱 @ref{4ce,,Task.cancel()}。

@item

@ref{810,,asyncio.BrokenBarrierError}

@tab

當一 Barrier 物件損壞時被引發。請參閱 @ref{36e8,,Barrier.wait()}。

@end multitable


@subsubheading 範例



@itemize *

@item 
@ref{36ab,,在取消請求發生的程式中處理 CancelledError 例外}。

@item 
請參閱 @ref{3724,,asyncio 專用例外}完整列表。
@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 低階 API 索引,使用 asyncio 開發,高階 API 索引,asyncio --- 非同步 I/O
@anchor{library/asyncio-llapi-index doc}@anchor{37e2}@anchor{library/asyncio-llapi-index low-level-api-index}@anchor{37e3}@anchor{library/asyncio-llapi-index translation-repo}@anchor{37e4}
@subsubsection 低階 API 索引


本頁列出所有低階 asyncio APIs。

@menu
* 取得事件迴圈:: 
* 事件迴圈方法: 事件迴圈方法<2>. 
* 傳輸:: 
* 協定:: 
* 事件迴圈 Policies:: 

@end menu

@node 取得事件迴圈,事件迴圈方法<2>,,低階 API 索引
@anchor{library/asyncio-llapi-index obtaining-the-event-loop}@anchor{37e5}
@subsubsection 取得事件迴圈



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{cf9,,asyncio.get_running_loop()}

@tab

`推薦使用'於取得目前運行事件迴圈 (event loop) 的函式。

@item

@ref{2f1,,asyncio.get_event_loop()}

@tab

獲得一個（正在運行的或透過目前 policy 建立的）事件迴圈實例。

@item

@ref{1a84,,asyncio.set_event_loop()}

@tab

透過目前 policy 來設定目前事件迴圈。

@item

@ref{367b,,asyncio.new_event_loop()}

@tab

建立一個新的事件迴圈。

@end multitable


@subsubheading 範例



@itemize *

@item 
@ref{3780,,使用 asyncio.get_running_loop()}。
@end itemize

@node 事件迴圈方法<2>,傳輸,取得事件迴圈,低階 API 索引
@anchor{library/asyncio-llapi-index event-loop-methods}@anchor{37e6}
@subsubsection 事件迴圈方法


也請查閱文件中關於@ref{373b,,事件迴圈方法}的主要段落。

@subsubheading 生命週期



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{e6d,,loop.run_until_complete()}

@tab

執行一個 Future/Task/awaitable（可等待物件）直到完成。

@item

@ref{373d,,loop.run_forever()}

@tab

持續運行事件迴圈。

@item

@ref{e72,,loop.stop()}

@tab

停止事件迴圈。

@item

@ref{373f,,loop.close()}

@tab

關閉事件迴圈。

@item

@ref{373e,,loop.is_running()}

@tab

如果事件迴圈正在執行則回傳 @code{True}。

@item

@ref{fbe,,loop.is_closed()}

@tab

如果事件迴圈已經被關閉則回傳 @code{True}。

@item

@code{await} @ref{e74,,loop.shutdown_asyncgens()}

@tab

關閉非同步產生器 (asynchronous generators)。

@end multitable


@subsubheading 除錯



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{fbc,,loop.set_debug()}

@tab

開啟或禁用除錯模式。

@item

@ref{fbd,,loop.get_debug()}

@tab

取得目前除錯模式。

@end multitable


@subsubheading 為回呼函式排程



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{cf2,,loop.call_soon()}

@tab

儘快呼叫回呼函式 (callback)。

@item

@ref{cf3,,loop.call_soon_threadsafe()}

@tab

@ref{cf2,,loop.call_soon()} 方法之有支援執行緒安全 (thread-safe) 變體。

@item

@ref{cf4,,loop.call_later()}

@tab

在給定時間`之後'呼叫回呼函式。

@item

@ref{cf5,,loop.call_at()}

@tab

在給定時間`當下'呼叫回呼函式。

@end multitable


@subsubheading 執行緒 (Thread)/直譯器 (Interpreter)/行程池 (Process Pool)



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@code{await} @ref{add,,loop.run_in_executor()}

@tab

在 @ref{24,,concurrent.futures} 執行器 (excutor) 中執行一個 CPU 密集型 (CPU-bound) 或其它阻塞型式的函式。

@item

@ref{942,,loop.set_default_executor()}

@tab

為 @ref{add,,loop.run_in_executor()} 設定預設執行器。

@end multitable


@subsubheading Tasks 與 Futures



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{e6f,,loop.create_future()}

@tab

建立一個 @ref{dc1,,Future} 物件。

@item

@ref{1ca,,loop.create_task()}

@tab

像是 @ref{1c7,,Task} 一樣，為協程 (coroutine) 排程。

@item

@ref{1c8,,loop.set_task_factory()}

@tab

設定被 @ref{1ca,,loop.create_task()} 用來建立 @ref{1c7,,Tasks} 的工廠函式 (factory)。

@item

@ref{fc0,,loop.get_task_factory()}

@tab

取得被 @ref{1ca,,loop.create_task()} 用來建立 @ref{1c7,,Tasks} 的工廠函式。

@end multitable


@subsubheading DNS



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@code{await} @ref{e09,,loop.getaddrinfo()}

@tab

非同步版本的 @ref{1a0e,,socket.getaddrinfo()}。

@item

@code{await} @ref{e0a,,loop.getnameinfo()}

@tab

非同步版本的 @ref{198b,,socket.getnameinfo()}。

@end multitable


@subsubheading 網路和 IPC



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@code{await} @ref{811,,loop.create_connection()}

@tab

開啟一個 TCP 連線。

@item

@code{await} @ref{d01,,loop.create_server()}

@tab

建立一個 TCP 伺服器。

@item

@code{await} @ref{36b4,,loop.create_unix_connection()}

@tab

開啟一個 Unix socket 連線。

@item

@code{await} @ref{4c5,,loop.create_unix_server()}

@tab

建立一個 Unix socket 伺服器。

@item

@code{await} @ref{9d7,,loop.connect_accepted_socket()}

@tab

將 @ref{f9c,,socket} 包裝成  @code{(transport, protocol)}。

@item

@code{await} @ref{934,,loop.create_datagram_endpoint()}

@tab

開啟一個資料單元 (datagram) (UDP) 連線。

@item

@code{await} @ref{3751,,loop.sendfile()}

@tab

透過傳輸通道傳送一個檔案。

@item

@code{await} @ref{cf7,,loop.start_tls()}

@tab

將一個已存在的連線升級到 TLS。

@item

@code{await} @ref{36fb,,loop.connect_read_pipe()}

@tab

將 pipe（管道）讀取端包裝成  @code{(transport, protocol)}。

@item

@code{await} @ref{36fc,,loop.connect_write_pipe()}

@tab

將 pipe 寫入端包裝成  @code{(transport, protocol)}。

@end multitable


@subsubheading Sockets



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@code{await} @ref{e06,,loop.sock_recv()}

@tab

從 @ref{f9c,,socket} 接收資料。

@item

@code{await} @ref{cf8,,loop.sock_recv_into()}

@tab

將從 @ref{f9c,,socket} 接收到的資料存放於一個緩衝區 (buffer) 中。

@item

@code{await} @ref{814,,loop.sock_recvfrom()}

@tab

從 @ref{f9c,,socket} 接收一個資料單元。

@item

@code{await} @ref{815,,loop.sock_recvfrom_into()}

@tab

將從 @ref{f9c,,socket} 接收到的資料單元存放於一個緩衝區中。

@item

@code{await} @ref{e07,,loop.sock_sendall()}

@tab

傳送資料到 @ref{f9c,,socket}。

@item

@code{await} @ref{813,,loop.sock_sendto()}

@tab

透過 @ref{f9c,,socket} 將資料單元傳送至給定的地址。

@item

@code{await} @ref{fc3,,loop.sock_connect()}

@tab

連接 @ref{f9c,,socket}。

@item

@code{await} @ref{e08,,loop.sock_accept()}

@tab

接受一個 @ref{f9c,,socket} 連線。

@item

@code{await} @ref{cfc,,loop.sock_sendfile()}

@tab

透過 @ref{f9c,,socket} 傳送一個檔案。

@item

@ref{36cf,,loop.add_reader()}

@tab

開始監控一個檔案描述器 (file descriptor) 的可讀取性。

@item

@ref{3754,,loop.remove_reader()}

@tab

停止監控一個檔案描述器的可讀取性。

@item

@ref{3755,,loop.add_writer()}

@tab

開始監控一個檔案描述器的可寫入性。

@item

@ref{3756,,loop.remove_writer()}

@tab

停止監控一個檔案描述器的可寫入性。

@end multitable


@subsubheading Unix 信號



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{375e,,loop.add_signal_handler()}

@tab

為 @ref{cb,,signal} 新增一個處理函式 (handler)。

@item

@ref{375f,,loop.remove_signal_handler()}

@tab

刪除 @ref{cb,,signal} 的處理函式。

@end multitable


@subsubheading 子行程



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{36f8,,loop.subprocess_exec()}

@tab

衍生 (spawn) 一個子行程 (subprocess)。

@item

@ref{36f9,,loop.subprocess_shell()}

@tab

從 shell 指令衍生一個子行程。

@end multitable


@subsubheading 錯誤處理



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{3763,,loop.call_exception_handler()}

@tab

呼叫例外處理函式。

@item

@ref{3762,,loop.set_exception_handler()}

@tab

設定一個新的例外處理函式。

@item

@ref{e70,,loop.get_exception_handler()}

@tab

取得目前例外處理函式。

@item

@ref{3764,,loop.default_exception_handler()}

@tab

預設例外處理函式實作。

@end multitable


@subsubheading 範例



@itemize *

@item 
@ref{376e,,使用 asyncio.new_event_loop() 和 loop.run_forever()}。

@item 
@ref{3770,,使用 loop.call_later()}。

@item 
使用 @code{loop.create_connection()} 以實作@ref{36c6,,一個 echo 用戶端}。

@item 
使用 @code{loop.create_connection()} 來@ref{36cd,,連接 socket}。

@item 
@ref{36ce,,使用 add_reader() 監控 FD 的讀取事件}。

@item 
@ref{3773,,使用 loop.add_signal_handler()}。

@item 
@ref{370d,,使用 loop.add_signal_handler()}。
@end itemize

@node 傳輸,協定,事件迴圈方法<2>,低階 API 索引
@anchor{library/asyncio-llapi-index transports}@anchor{37e7}
@subsubsection 傳輸


所有傳輸方式都有實作以下方法：


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{374b,,transport.close()}

@tab

關閉傳輸。

@item

@ref{e6e,,transport.is_closing()}

@tab

如果傳輸正在關閉或已經關閉則回傳 @code{True}。

@item

@ref{c8a,,transport.get_extra_info()}

@tab

請求傳輸的相關資訊。

@item

@ref{3790,,transport.set_protocol()}

@tab

設定一個新協定。

@item

@ref{3791,,transport.get_protocol()}

@tab

回傳目前協定。

@end multitable


可以接收資料（TCP 和 Unix 連線、pipe 等）的傳輸。它由 @ref{811,,loop.create_connection()}、@ref{36b4,,loop.create_unix_connection()}、@ref{36fb,,loop.connect_read_pipe()} 等方法回傳：

@subsubheading 讀取傳輸



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{d09,,transport.is_reading()}

@tab

如果傳輸正在接收則回傳 @code{True}。

@item

@ref{d0b,,transport.pause_reading()}

@tab

暫停接收。

@item

@ref{d0a,,transport.resume_reading()}

@tab

繼續接收。

@end multitable


可以傳送資料（TCP 和 Unix 連線、pipe 等）的傳輸。它由 @ref{811,,loop.create_connection()}、@ref{36b4,,loop.create_unix_connection()}、@ref{36fc,,loop.connect_write_pipe()} 等方法回傳：

@subsubheading 寫入傳輸



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{1760,,transport.write()}

@tab

將資料寫入傳輸。

@item

@ref{175f,,transport.writelines()}

@tab

將緩衝區資料寫入傳輸。

@item

@ref{3795,,transport.can_write_eof()}

@tab

如果傳輸支援傳送 EOF 則回傳  @ref{e02,,True}。

@item

@ref{3796,,transport.write_eof()}

@tab

在清除 (flush) 已緩衝的資料後關閉傳輸並傳送 EOF。

@item

@ref{3794,,transport.abort()}

@tab

立即關閉傳輸。

@item

@ref{3797,,transport.get_write_buffer_size()}

@tab

回傳目前輸出緩衝區的大小。

@item

@ref{fbf,,transport.get_write_buffer_limits()}

@tab

回傳用於寫入流量控制 (write flow control) 的高低標記位 (high and low water marks)。

@item

@ref{3798,,transport.set_write_buffer_limits()}

@tab

為寫入流量控制設定高低標記位。

@end multitable


由 @ref{934,,loop.create_datagram_endpoint()} 回傳的傳輸：

@subsubheading 資料單元傳輸



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{4c6,,transport.sendto()}

@tab

傳送資料到連線遠端。

@item

@ref{379c,,transport.abort()}

@tab

立即關閉傳輸。

@end multitable


基於子行程的低階傳輸抽象，它會由 @ref{36f8,,loop.subprocess_exec()} 和 @ref{36f9,,loop.subprocess_shell()} 所回傳：

@subsubheading 子行程傳輸



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{379e,,transport.get_pid()}

@tab

回傳子行程的行程 id。

@item

@ref{379f,,transport.get_pipe_transport()}

@tab

回傳被請求用於通訊 pipe （`stdin'、`stdout' 或 `stderr'）的傳輸。

@item

@ref{37a0,,transport.get_returncode()}

@tab

回傳子行程的回傳代號 (return code)。

@item

@ref{37a1,,transport.kill()}

@tab

殺死子行程。

@item

@ref{37a3,,transport.send_signal()}

@tab

傳送一個訊號到子行程。

@item

@ref{37a2,,transport.terminate()}

@tab

停止子行程。

@item

@ref{37a4,,transport.close()}

@tab

殺死子行程並關閉所有 pipes。

@end multitable


@node 協定,事件迴圈 Policies,傳輸,低階 API 索引
@anchor{library/asyncio-llapi-index protocols}@anchor{37e8}
@subsubsection 協定


協定類別可以實作以下`回呼方法'：


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@code{callback} @ref{3749,,connection_made()}

@tab

在連線建立時被呼叫。

@item

@code{callback} @ref{378d,,connection_lost()}

@tab

在失去連線或連線關閉時被呼叫。

@item

@code{callback} @ref{3799,,pause_writing()}

@tab

在傳輸緩衝區超過高標記位時被呼叫。

@item

@code{callback} @ref{379a,,resume_writing()}

@tab

在傳輸緩衝區低於低標記位時被呼叫。

@end multitable


@subsubheading 串流協定 (TCP, Unix socket, Pipes)



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@code{callback} @ref{1a48,,data_received()}

@tab

在接收到資料時被呼叫。

@item

@code{callback} @ref{37a8,,eof_received()}

@tab

在接收到 EOF 時被呼叫。

@end multitable


@subsubheading 緩衝串流協定



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@code{callback} @ref{37aa,,get_buffer()}

@tab

呼叫後會分配新的接收緩衝區。

@item

@code{callback} @ref{37ab,,buffer_updated()}

@tab

在以接收到的資料更新緩衝區時被呼叫。

@item

@code{callback} @ref{37ac,,eof_received()}

@tab

在接收到 EOF 時被呼叫。

@end multitable


@subsubheading 資料單元協定



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@code{callback} @ref{37ae,,datagram_received()}

@tab

在接收到資料單元時被呼叫。

@item

@code{callback} @ref{37af,,error_received()}

@tab

在前一個傳送或接收操作引發 @ref{2c0,,OSError} 時被呼叫。

@end multitable


@subsubheading 子行程協定



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@code{callback} @ref{1a7f,,pipe_data_received()}

@tab

在子行程向 `stdout' 或 `stderr' pipe 寫入資料時被呼叫。

@item

@code{callback} @ref{37b1,,pipe_connection_lost()}

@tab

在與子行程通訊的其中一個 pipes 關閉時被呼叫。

@item

@code{callback} @ref{1a7e,,process_exited()}

@tab

在子行程退出時呼叫。它可以在 @ref{1a7f,,pipe_data_received()} 和 @ref{37b1,,pipe_connection_lost()} 方法之前呼叫。

@end multitable


@node 事件迴圈 Policies,,協定,低階 API 索引
@anchor{library/asyncio-llapi-index event-loop-policies}@anchor{37e9}
@subsubsection 事件迴圈 Policies


Policy 是改變 @ref{2f1,,asyncio.get_event_loop()} 這類函式行為的一個低階機制。更多細節請見 @ref{3735,,Policy 相關段落}。

@subsubheading 存取 Policy



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{311,,asyncio.get_event_loop_policy()}

@tab

回傳目前整個行程中的 Policy。

@item

@ref{312,,asyncio.set_event_loop_policy()}

@tab

設定整個行程中的一個新 Policy。

@item

@ref{30d,,AbstractEventLoopPolicy}

@tab

Policy 物件的基礎類別。

@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 使用 asyncio 開發,,低階 API 索引,asyncio --- 非同步 I/O
@anchor{library/asyncio-dev doc}@anchor{37ea}@anchor{library/asyncio-dev asyncio-dev}@anchor{37eb}@anchor{library/asyncio-dev developing-with-asyncio}@anchor{37ec}@anchor{library/asyncio-dev translation-repo}@anchor{37ed}
@subsubsection 使用 asyncio 開發


非同步程式設計 (asynchronous programming) 與傳統的"順序"程式設計 (sequential programming) 不同。

本頁列出常見的錯誤和陷阱，並解釋如何避免它們。

@menu
* 除錯模式:: 
* 並行性和多執行緒 (Concurrency and Multithreading): 並行性和多執行緒 Concurrency and Multithreading. 
* 執行阻塞的程式:: 
* 日誌記錄:: 
* 偵測從未被等待的 (never-awaited) 協程: 偵測從未被等待的 never-awaited 協程. 
* 偵測從未被取得的 (never-retrieved) 例外: 偵測從未被取得的 never-retrieved 例外. 

@end menu

@node 除錯模式,並行性和多執行緒 Concurrency and Multithreading,,使用 asyncio 開發
@anchor{library/asyncio-dev asyncio-debug-mode}@anchor{2001}@anchor{library/asyncio-dev debug-mode}@anchor{37ee}
@subsubsection 除錯模式


在預設情況下 asyncio 以正式生產模式 (production mode) 執行。為了讓開發更輕鬆，asyncio 還有一種`除錯模式 (debug mode)'。

有幾種方法可以啟用 asyncio 除錯模式：


@itemize *

@item 
將 
@geindex PYTHONASYNCIODEBUG
@geindex 環境變數; PYTHONASYNCIODEBUG
@ref{2000,,PYTHONASYNCIODEBUG} 環境變數設定為 @code{1}。

@item 
使用 @ref{503,,Python 開發模式 (Development Mode)}。

@item 
將 @code{debug=True} 傳遞給 @ref{2f2,,asyncio.run()}。

@item 
呼叫 @ref{fbc,,loop.set_debug()}。
@end itemize

除了啟用除錯模式外，還要考慮：


@itemize *

@item 
將 @ref{37ef,,asyncio logger（日誌記錄器）}的日誌級别設置為 @ref{1fa4,,logging.DEBUG}，例如下面的程式片段可以在應用程式啟動時運行：

@example
logging.basicConfig(level=logging.DEBUG)
@end example

@item 
配置 @ref{118,,warnings} 模組以顯示 @ref{547,,ResourceWarning} 警告。一種方法是使用 @ref{abc,,-W} @code{default} 命令列選項。
@end itemize

啟用除錯模式時：


@itemize *

@item 
許多非執行緒安全 (non-threadsafe) 的 asyncio APIs（例如 @ref{cf2,,loop.call_soon()} 和 @ref{cf5,,loop.call_at()} 方法），如果從錯誤的執行緒呼叫就會引發例外。

@item 
如果執行一個 I/O 操作花費的時間太長，則將 I/O 選擇器 (selector) 的執行時間記錄到日誌中。

@item 
執行時間超過 100 毫秒的回呼 (callback) 將會被記錄於日誌。屬性 @ref{3766,,loop.slow_callback_duration} 可用於設定以秒為單位的最小執行持續時間，超過這個值執行時間就會被視為"緩慢"。
@end itemize

@node 並行性和多執行緒 Concurrency and Multithreading,執行阻塞的程式,除錯模式,使用 asyncio 開發
@anchor{library/asyncio-dev asyncio-multithreading}@anchor{369d}@anchor{library/asyncio-dev concurrency-and-multithreading}@anchor{37f0}
@subsubsection 並行性和多執行緒 (Concurrency and Multithreading)


事件迴圈在執行緒中運行（通常是主執行緒），並在其執行緒中執行所有回呼和 Tasks（任務）。當一個 Task 在事件迴圈中運行時，沒有其他 Task 可以在同一個執行緒中運行。當一個 Task 執行一個 @code{await} 運算式時，正在執行的 Task 會被暫停，而事件迴圈會執行下一個 Task。

要從不同的 OS 執行緒為一個 @ref{2c4f,,callback} 排程，應該使用 @ref{cf3,,loop.call_soon_threadsafe()} 方法。例如：

@example
loop.call_soon_threadsafe(callback, *args)
@end example

幾乎所有 asyncio 物件都不支援執行緒安全 (thread safe)，這通常不是問題，除非在 Task 或回呼函式之外有程式需要和它們一起運作。如果需要這樣的程式來呼叫低階 asyncio API，應該使用 @ref{cf3,,loop.call_soon_threadsafe()} 方法，例如：

@example
loop.call_soon_threadsafe(fut.cancel)
@end example

要從不同的 OS 執行緒為一個協程物件排程，應該使用 @ref{a79,,run_coroutine_threadsafe()} 函式。它會回傳一個 @ref{13b3,,concurrent.futures.Future} 以存取結果：

@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

為了能夠處理訊號，事件迴圈必須於主執行緒中運行。

@ref{add,,loop.run_in_executor()} 方法可以和 @ref{941,,concurrent.futures.ThreadPoolExecutor} 或 @ref{1d2,,InterpreterPoolExecutor} 一起使用，這能夠在作業系統上另一個不同的執行緒中執行阻塞程式，且避免阻塞執行事件迴圈的執行緒。

目前沒有什麼辦法能直接從另一個行程（例如透過 @ref{98,,multiprocessing} 啟動的程序）來為協程或回呼排程。@ref{373b,,事件迴圈方法}小節列出了可以從 pipes（管道）讀取並監視 file descriptor（檔案描述器）而不會阻塞事件迴圈的 API。此外，asyncio 的@ref{366f,,子行程} API 提供了一種啟動行程並從事件迴圈與其通訊的辦法。最後，之前提到的 @ref{add,,loop.run_in_executor()} 方法也可和 @ref{1d6,,concurrent.futures.ProcessPoolExecutor} 搭配使用，以在另一個行程中執行程式。

@node 執行阻塞的程式,日誌記錄,並行性和多執行緒 Concurrency and Multithreading,使用 asyncio 開發
@anchor{library/asyncio-dev asyncio-handle-blocking}@anchor{37f1}@anchor{library/asyncio-dev running-blocking-code}@anchor{37f2}
@subsubsection 執行阻塞的程式


不應該直接呼叫阻塞（CPU 密集型）程式。例如一個執行 1 秒 CPU 密集型計算的函式，那麼所有並行非同步 Tasks 和 IO 操作都會被延遲 1 秒。

一個 executor（執行器）可以被用來在不同的執行緒（包含不同直譯器）、或甚至不同的行程中執行任務，以避免事件迴圈阻塞了 OS 執行緒。詳情請見 @ref{add,,loop.run_in_executor()} 方法。

@node 日誌記錄,偵測從未被等待的 never-awaited 協程,執行阻塞的程式,使用 asyncio 開發
@anchor{library/asyncio-dev asyncio-logger}@anchor{37ef}@anchor{library/asyncio-dev logging}@anchor{37f3}
@subsubsection 日誌記錄


asyncio 使用 @ref{8b,,logging} 模組，所有日誌記錄都是透過 @code{"asyncio"} logger 執行的。

日誌級別被預設為 @ref{1fa5,,logging.INFO}，它可以很容易地被調整：

@example
logging.getLogger("asyncio").setLevel(logging.WARNING)
@end example

網路日誌記錄可能會阻塞事件迴圈。建議使用獨立的執行緒來處理日誌或使用非阻塞 IO，範例請參見 @ref{37f4,,Dealing with handlers that block}。

@node 偵測從未被等待的 never-awaited 協程,偵測從未被取得的 never-retrieved 例外,日誌記錄,使用 asyncio 開發
@anchor{library/asyncio-dev asyncio-coroutine-not-scheduled}@anchor{37f5}@anchor{library/asyncio-dev detect-never-awaited-coroutines}@anchor{37f6}
@subsubsection 偵測從未被等待的 (never-awaited) 協程


當協程函式被呼叫而不是被等待時（即執行 @code{coro()} 而不是 @code{await coro()}）或者協程沒有透過 @ref{1c9,,asyncio.create_task()} 被排程，asyncio 將會發出 @ref{4d2,,RuntimeWarning}：

@example
import asyncio

async def test():
    print("never scheduled")

async def main():
    test()

asyncio.run(main())
@end example

輸出：

@example
test.py:7: RuntimeWarning: coroutine 'test' was never awaited
  test()
@end example

除錯模式中的輸出：

@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

常用的修復方法是去等待協程或者呼叫 @ref{1c9,,asyncio.create_task()} 函式：

@example
async def main():
    await test()
@end example

@node 偵測從未被取得的 never-retrieved 例外,,偵測從未被等待的 never-awaited 協程,使用 asyncio 開發
@anchor{library/asyncio-dev detect-never-retrieved-exceptions}@anchor{37f7}
@subsubsection 偵測從未被取得的 (never-retrieved) 例外


如果呼叫 @ref{e73,,Future.set_exception()}，但 Future 物件從未被等待，例外將無法被傳播 (propagate) 到使用者程式。在這種情況下，當 Future 物件被垃圾回收 (garbage collected) 時，asyncio 將發出一則日誌訊息。

未處理例外的例子：

@example
import asyncio

async def bug():
    raise Exception("not consumed")

async def main():
    asyncio.create_task(bug())

asyncio.run(main())
@end example

輸出：

@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{2001,,啟用除錯模式}以取得任務建立處的追蹤資訊 (traceback)：

@example
asyncio.run(main(), debug=True)
@end example

除錯模式中的輸出：

@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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@cartouche
@quotation 備註 
asyncio 的原始碼可以在 Lib/asyncio/@footnote{https://github.com/python/cpython/tree/3.14/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 — 低階網路介面,ssl --- socket 物件的 TLS/SSL 包裝器,asyncio --- 非同步 I/O,網路與行程間通訊
@anchor{library/socket doc}@anchor{37f8}@anchor{library/socket module-socket}@anchor{d1}@anchor{library/socket socket-low-level-networking-interface}@anchor{37f9}@anchor{library/socket translation-repo}@anchor{37fa}
@subsection @code{socket} — 低階網路介面


@geindex module; socket

`原始碼：'Lib/socket.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/socket.py}


__________________________________________________________________


這個模組提供了操作 BSD `socket' 的介面。這在所有現代 Unix 系統、Windows、MacOS，以及一些其他平台上都可用。

@cartouche
@quotation 備註 
由於是呼叫作業系統的 socket API，某些行為可能會因平台而有所差異。
@end quotation
@end cartouche

@c include for modules that don't work on WASM

@ref{2006,,可用性}: not WASI.

此模組在 WebAssembly 平台上不起作用或無法使用。更多資訊請參閱 @ref{1a99,,WebAssembly 平台}。

@geindex object（物件）;socket

Python 的介面是將 Unix 的系統呼叫和 socket 函式庫介面直接轉換成 Python 的物件導向風格：@code{socket()} 函式會回傳一個 `socket 物件'，這個物件的方法實作了各種 socket 系統呼叫。與 C 語言介面相比，參數型別較為高階：就像 Python 文件操作中的 @code{read()} 和 @code{write()} 一樣，接收操作時會自動分配緩衝區，而發送操作時的緩衝區長度則是隱含的。


@subsubheading 也參考



@table @asis

@item @ref{d2,,socketserver} 模組

簡化編寫網路伺服器的類別。

@item @ref{d5,,ssl} 模組

對 socket 物件的 TLS/SSL 的包裝器 (wrapper)。
@end table


@menu
* Socket 系列家族:: 
* 模組內容: 模組內容<4>. 
* Socket 物件:: 
* Notes on socket timeouts:: 
* 範例: 範例<26>. 

@end menu

@node Socket 系列家族,模組內容<4>,,socket — 低階網路介面
@anchor{library/socket socket-families}@anchor{37fb}
@subsubsection Socket 系列家族


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{1ad5,,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{193,,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{1ad5,,AF_UNIX} socket paths were assumed to use UTF-8
encoding.



在 3.5 版的變更: Writable @ref{193,,bytes-like object} is now accepted.

@end itemize
@anchor{library/socket host-port}@anchor{37fc}

@itemize -

@item 
A pair @code{(host, port)} is used for the @ref{1ad2,,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{1ad3,,AF_INET6} address family, a four-tuple @code{(host, port, flowinfo,
scope_id)} is used, where `flowinfo' and `scope_id' represent the @code{sin6_flowinfo}
and @code{sin6_scope_id} members in @code{struct sockaddr_in6} in C.  For
@ref{d1,,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{37fd,,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{37fe,,CAN_ISOTP} protocol require a tuple @code{(interface, rx_addr, tx_addr)}
where both additional parameters are unsigned long integer that represent a
CAN identifier (standard or extended).

@item 
@ref{b23,,CAN_J1939} protocol require a tuple @code{(interface, name, pgn, addr)}
where additional parameters are 64-bit unsigned integer representing the
ECU name, a 32-bit unsigned integer representing the Parameter Group Number
(PGN), and an 8-bit integer representing the address.
@end itemize

@item 
A string or a tuple @code{(id, unit)} is used for the @code{SYSPROTO_CONTROL}
protocol of the @code{PF_SYSTEM} family. The string is the name of a
kernel control using a dynamically assigned ID. The tuple can be used if ID
and unit number of the kernel control are known or if a registered ID is
used.


在 3.3 版被加入.


@item 
@ref{1ad4,,AF_BLUETOOTH} supports the following protocols and address
formats:


@itemize -

@item 
@ref{283,,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{37ff,,BDADDR_BREDR} (default), @ref{3800,,BDADDR_LE_PUBLIC},
@ref{3801,,BDADDR_LE_RANDOM}.
@end itemize


在 3.14 版的變更: Added @code{cid} and @code{bdaddr_type} fields.


@item 
@ref{3802,,BTPROTO_RFCOMM} accepts @code{(bdaddr, channel)} where @code{bdaddr}
is the Bluetooth address as a string and @code{channel} is an integer.

@item 
@ref{281,,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{3803,,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 和 DragonFlyBSD 的支援。



在 3.13.3 版的變更: 新增對 FreeBSD 的支援。



在 3.14 版的變更: Added @code{channel} field.
@code{device_id} not packed in a tuple is now accepted.


@item 
@ref{282,,BTPROTO_SCO} accepts @code{bdaddr} where @code{bdaddr} is
the Bluetooth address as a string or a @ref{192,,bytes} object.
(ex. @code{'12:23:34:45:56:67'} or @code{b'12:23:34:45:56:67'})


在 3.14 版的變更: 新增對 FreeBSD 的支援。

@end itemize

@item 
@ref{ecd,,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{2006,,可用性}: Linux >= 2.6.38.

Some algorithm types require more recent Kernels.


在 3.6 版被加入.


@item 
@ref{d65,,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{2006,,可用性}: Linux >= 3.9

請見 @code{vsock(7)@footnote{https://manpages.debian.org/vsock(7)}}


在 3.7 版被加入.


@item 
@ref{3804,,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{1a64,,ETH_P_ALL} to capture all protocols,
one of the @ref{1a65,,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{2006,,可用性}: Linux >= 2.2.

@item 
@ref{3805,,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{2006,,可用性}: Linux >= 4.7.


在 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{2006,,可用性}: Linux >= 2.6.20, FreeBSD >= 10.1


在 3.9 版被加入.


@item 
@ref{3806,,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.


在 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{2c0,,OSError} or one of its
subclasses.

Non-blocking mode is supported through @ref{2eee,,setblocking()}.  A
generalization of this based on timeouts is supported through
@ref{3807,,settimeout()}.

@node 模組內容<4>,Socket 物件,Socket 系列家族,socket — 低階網路介面
@anchor{library/socket module-contents}@anchor{3808}
@subsubsection 模組內容


The module @ref{d1,,socket} exports the following elements.

@menu
* 例外: 例外<16>. 
* 常數: 常數<7>. 
* 函式: 函式<8>. 

@end menu

@node 例外<16>,常數<7>,,模組內容<4>
@anchor{library/socket exceptions}@anchor{3809}
@subsubsection 例外


@geindex error
@anchor{library/socket socket error}@anchor{1251}
@deffn {例外} socket.error

一個已棄用的 @ref{2c0,,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{2c0,,OSError}.

@end deffn

@geindex herror
@anchor{library/socket socket herror}@anchor{380a}
@deffn {例外} socket.herror

A subclass of @ref{2c0,,OSError}, this exception is raised for
address-related errors, i.e. for functions that use `h_errno' in the POSIX
C API, including @ref{1b83,,gethostbyname_ex()} and @ref{1b82,,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{2c0,,OSError}.

@end deffn

@geindex gaierror
@anchor{library/socket socket gaierror}@anchor{1a0f}
@deffn {例外} socket.gaierror

A subclass of @ref{2c0,,OSError}, this exception is raised for
address-related errors by @ref{1a0e,,getaddrinfo()} and @ref{198b,,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{2c0,,OSError}.

@end deffn

@geindex timeout
@anchor{library/socket socket timeout}@anchor{a2e}
@deffn {例外} socket.timeout

A deprecated alias of @ref{a2f,,TimeoutError}.

A subclass of @ref{2c0,,OSError}, this exception is raised when a timeout
occurs on a socket which has had timeouts enabled via a prior call to
@ref{3807,,settimeout()} (or implicitly through
@ref{380b,,setdefaulttimeout()}).  The accompanying value is a string
whose value is currently always "timed out".


在 3.3 版的變更: This class was made a subclass of @ref{2c0,,OSError}.



在 3.10 版的變更: This class was made an alias of @ref{a2f,,TimeoutError}.

@end deffn

@node 常數<7>,函式<8>,例外<16>,模組內容<4>
@anchor{library/socket constants}@anchor{380c}
@subsubsection 常數


The AF_* and SOCK_* constants are now @code{AddressFamily} and
@code{SocketKind} @ref{ed6,,IntEnum} collections.


在 3.4 版被加入.


@geindex AF_UNIX (於 socket 模組中)
@geindex AF_INET (於 socket 模組中)
@geindex AF_INET6 (於 socket 模組中)
@anchor{library/socket socket AF_UNIX}@anchor{1ad5}
@deffn {資料} socket.AF_UNIX
@anchor{library/socket socket AF_INET}@anchor{1ad2}
@deffnx {資料} socket.AF_INET
@anchor{library/socket socket AF_INET6}@anchor{1ad3}
@deffnx {資料} socket.AF_INET6

These constants represent the address (and protocol) families, used for the
first argument to @ref{f9c,,socket()}.  If the @ref{1ad5,,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{374f}
@deffn {資料} socket.AF_UNSPEC

@ref{374f,,AF_UNSPEC} means that
@ref{1a0e,,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{14f4}
@deffn {資料} socket.SOCK_STREAM
@anchor{library/socket socket SOCK_DGRAM}@anchor{14f3}
@deffnx {資料} socket.SOCK_DGRAM
@anchor{library/socket socket SOCK_RAW}@anchor{380d}
@deffnx {資料} socket.SOCK_RAW
@anchor{library/socket socket SOCK_RDM}@anchor{380e}
@deffnx {資料} socket.SOCK_RDM
@anchor{library/socket socket SOCK_SEQPACKET}@anchor{380f}
@deffnx {資料} socket.SOCK_SEQPACKET

These constants represent the socket types, used for the second argument to
@ref{f9c,,socket()}.  More constants may be available depending on the system.
(Only @ref{14f4,,SOCK_STREAM} and @ref{14f3,,SOCK_DGRAM} appear to be generally
useful.)
@end deffn

@geindex SOCK_CLOEXEC (於 socket 模組中)
@geindex SOCK_NONBLOCK (於 socket 模組中)
@anchor{library/socket socket SOCK_CLOEXEC}@anchor{e00}
@deffn {資料} socket.SOCK_CLOEXEC
@anchor{library/socket socket SOCK_NONBLOCK}@anchor{dff}
@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{2006,,可用性}: Linux >= 2.6.27.


在 3.2 版被加入.

@end deffn

@geindex SOMAXCONN (於 socket 模組中)
@anchor{library/socket socket-unix-constants}@anchor{d64}
@deffn {資料} SO_*
@anchor{library/socket socket SOMAXCONN}@anchor{105a}
@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{ecc,,setsockopt()} and @ref{ecb,,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}。

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.

@end deffn

@geindex AF_CAN (於 socket 模組中)
@geindex PF_CAN (於 socket 模組中)
@anchor{library/socket socket AF_CAN}@anchor{37fd}
@deffn {資料} socket.AF_CAN
@anchor{library/socket socket PF_CAN}@anchor{3810}
@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{2006,,可用性}: Linux >= 2.6.25, NetBSD >= 8.


在 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{119e}
@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{2006,,可用性}: 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


在 3.4 版被加入.

@end deffn

@geindex CAN_RAW_FD_FRAMES (於 socket 模組中)
@anchor{library/socket socket CAN_RAW_FD_FRAMES}@anchor{10c5}
@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{2006,,可用性}: Linux >= 3.6.


在 3.5 版被加入.

@end deffn

@geindex CAN_RAW_JOIN_FILTERS (於 socket 模組中)
@anchor{library/socket socket CAN_RAW_JOIN_FILTERS}@anchor{b22}
@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{2006,,可用性}: Linux >= 4.1.


在 3.9 版被加入.

@end deffn

@geindex CAN_ISOTP (於 socket 模組中)
@anchor{library/socket socket CAN_ISOTP}@anchor{37fe}
@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{2006,,可用性}: Linux >= 2.6.25.


在 3.7 版被加入.

@end deffn

@geindex CAN_J1939 (於 socket 模組中)
@anchor{library/socket socket CAN_J1939}@anchor{b23}
@deffn {資料} socket.CAN_J1939

CAN_J1939, in the CAN protocol family, is the SAE J1939 protocol.
J1939 constants, documented in the Linux documentation.

@ref{2006,,可用性}: Linux >= 5.4.


在 3.9 版被加入.

@end deffn

@geindex AF_DIVERT (於 socket 模組中)
@geindex PF_DIVERT (於 socket 模組中)
@anchor{library/socket socket AF_DIVERT}@anchor{3811}
@deffn {資料} socket.AF_DIVERT
@anchor{library/socket socket PF_DIVERT}@anchor{3812}
@deffnx {資料} socket.PF_DIVERT

These two constants, documented in the FreeBSD divert(4) manual page, are
also defined in the socket module.

@ref{2006,,可用性}: FreeBSD >= 14.0.


在 3.12 版被加入.

@end deffn

@geindex AF_PACKET (於 socket 模組中)
@geindex PF_PACKET (於 socket 模組中)
@anchor{library/socket socket AF_PACKET}@anchor{3804}
@deffn {資料} socket.AF_PACKET
@anchor{library/socket socket PF_PACKET}@anchor{3813}
@deffnx {資料} socket.PF_PACKET

@deffnx {資料} PACKET_*

Many constants of these forms, documented in the Linux documentation, are
also defined in the socket module.

@ref{2006,,可用性}: Linux >= 2.2.
@end deffn

@geindex ETH_P_ALL (於 socket 模組中)
@anchor{library/socket socket ETH_P_ALL}@anchor{1a64}
@deffn {資料} socket.ETH_P_ALL

@code{ETH_P_ALL} can be used in the @ref{f9c,,socket}
constructor as `proto' for the @ref{3804,,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{2006,,可用性}: Linux.


在 3.12 版被加入.

@end deffn

@geindex AF_RDS (於 socket 模組中)
@geindex PF_RDS (於 socket 模組中)
@geindex SOL_RDS (於 socket 模組中)
@anchor{library/socket socket AF_RDS}@anchor{3814}
@deffn {資料} socket.AF_RDS
@anchor{library/socket socket PF_RDS}@anchor{3815}
@deffnx {資料} socket.PF_RDS
@anchor{library/socket socket SOL_RDS}@anchor{3816}
@deffnx {資料} socket.SOL_RDS

@deffnx {資料} RDS_*

Many constants of these forms, documented in the Linux documentation, are
also defined in the socket module.

@ref{2006,,可用性}: Linux >= 2.6.30.


在 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{3817}
@deffn {資料} socket.SIO_RCVALL
@anchor{library/socket socket SIO_KEEPALIVE_VALS}@anchor{3818}
@deffnx {資料} socket.SIO_KEEPALIVE_VALS
@anchor{library/socket socket SIO_LOOPBACK_FAST_PATH}@anchor{eca}
@deffnx {資料} socket.SIO_LOOPBACK_FAST_PATH

@deffnx {資料} RCVALL_*

Constants for Windows' WSAIoctl(). The constants are used as arguments to the
@ref{ec9,,ioctl()} method of socket objects.


在 3.6 版的變更: 加入 @code{SIO_LOOPBACK_FAST_PATH}。

@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{ecd}
@deffn {資料} socket.AF_ALG
@anchor{library/socket socket SOL_ALG}@anchor{3819}
@deffnx {資料} socket.SOL_ALG

@deffnx {資料} ALG_*

Constants for Linux Kernel cryptography.

@ref{2006,,可用性}: Linux >= 2.6.38.


在 3.6 版被加入.

@end deffn

@geindex AF_VSOCK (於 socket 模組中)
@geindex IOCTL_VM_SOCKETS_GET_LOCAL_CID (於 socket 模組中)
@anchor{library/socket socket AF_VSOCK}@anchor{d65}
@deffn {資料} socket.AF_VSOCK
@anchor{library/socket socket IOCTL_VM_SOCKETS_GET_LOCAL_CID}@anchor{381a}
@deffnx {資料} socket.IOCTL_VM_SOCKETS_GET_LOCAL_CID

@deffnx {資料} VMADDR*

@deffnx {資料} SO_VM*

Constants for Linux host/guest communication.

@ref{2006,,可用性}: Linux >= 4.8.


在 3.7 版被加入.

@end deffn

@geindex AF_LINK (於 socket 模組中)
@anchor{library/socket socket AF_LINK}@anchor{119f}
@deffn {資料} socket.AF_LINK

@ref{2006,,可用性}: BSD, macOS.


在 3.4 版被加入.

@end deffn

@geindex has_ipv6 (於 socket 模組中)
@anchor{library/socket socket has_ipv6}@anchor{381b}
@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{1ad4}
@deffn {資料} socket.AF_BLUETOOTH
@anchor{library/socket socket BTPROTO_L2CAP}@anchor{283}
@deffnx {資料} socket.BTPROTO_L2CAP
@anchor{library/socket socket BTPROTO_RFCOMM}@anchor{3802}
@deffnx {資料} socket.BTPROTO_RFCOMM
@anchor{library/socket socket BTPROTO_HCI}@anchor{281}
@deffnx {資料} socket.BTPROTO_HCI
@anchor{library/socket socket BTPROTO_SCO}@anchor{282}
@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{381c}
@deffn {資料} socket.BDADDR_ANY
@anchor{library/socket socket BDADDR_LOCAL}@anchor{381d}
@deffnx {資料} socket.BDADDR_LOCAL

These are string constants containing Bluetooth addresses with special
meanings. For example, @ref{381c,,BDADDR_ANY} can be used to indicate
any address when specifying the binding socket with
@ref{3802,,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{37ff}
@deffn {資料} socket.BDADDR_BREDR
@anchor{library/socket socket BDADDR_LE_PUBLIC}@anchor{3800}
@deffnx {資料} socket.BDADDR_LE_PUBLIC
@anchor{library/socket socket BDADDR_LE_RANDOM}@anchor{3801}
@deffnx {資料} socket.BDADDR_LE_RANDOM

These constants describe the Bluetooth address type when binding or
connecting a @ref{283,,BTPROTO_L2CAP} socket.

@ref{2006,,可用性}: Linux, FreeBSD


在 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{381e}
@deffn {資料} socket.SOL_RFCOMM
@anchor{library/socket socket SOL_L2CAP}@anchor{381f}
@deffnx {資料} socket.SOL_L2CAP
@anchor{library/socket socket SOL_HCI}@anchor{3820}
@deffnx {資料} socket.SOL_HCI
@anchor{library/socket socket SOL_SCO}@anchor{3821}
@deffnx {資料} socket.SOL_SCO
@anchor{library/socket socket SOL_BLUETOOTH}@anchor{3822}
@deffnx {資料} socket.SOL_BLUETOOTH

Used in the level argument to the @ref{ecc,,setsockopt()} and
@ref{ecb,,getsockopt()} methods of Bluetooth socket objects.

@ref{3822,,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{3823}
@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{ecc,,setsockopt()}
and @ref{ecb,,getsockopt()} methods of Bluetooth socket objects.

@code{BT_*} and @ref{3823,,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.


在 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{3824}
@deffn {資料} socket.HCI_FILTER
@anchor{library/socket socket HCI_TIME_STAMP}@anchor{3825}
@deffnx {資料} socket.HCI_TIME_STAMP
@anchor{library/socket socket HCI_DATA_DIR}@anchor{3826}
@deffnx {資料} socket.HCI_DATA_DIR
@anchor{library/socket socket SO_HCI_EVT_FILTER}@anchor{3827}
@deffnx {資料} socket.SO_HCI_EVT_FILTER
@anchor{library/socket socket SO_HCI_PKT_FILTER}@anchor{3828}
@deffnx {資料} socket.SO_HCI_PKT_FILTER

Option names for use with @ref{281,,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{3829}
@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{2006,,可用性}: Linux


在 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{3803}
@deffn {資料} socket.HCI_CHANNEL_RAW
@anchor{library/socket socket HCI_CHANNEL_USER}@anchor{382a}
@deffnx {資料} socket.HCI_CHANNEL_USER
@anchor{library/socket socket HCI_CHANNEL_MONITOR}@anchor{382b}
@deffnx {資料} socket.HCI_CHANNEL_MONITOR
@anchor{library/socket socket HCI_CHANNEL_CONTROL}@anchor{382c}
@deffnx {資料} socket.HCI_CHANNEL_CONTROL
@anchor{library/socket socket HCI_CHANNEL_LOGGING}@anchor{382d}
@deffnx {資料} socket.HCI_CHANNEL_LOGGING

Possible values for @code{channel} field in the @ref{281,,BTPROTO_HCI} address.

@ref{2006,,可用性}: Linux


在 3.14 版被加入.

@end deffn

@geindex AF_QIPCRTR (於 socket 模組中)
@anchor{library/socket socket AF_QIPCRTR}@anchor{3805}
@deffn {資料} socket.AF_QIPCRTR

Constant for Qualcomm's IPC router protocol, used to communicate with
service providing remote processors.

@ref{2006,,可用性}: 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{382e}
@deffn {資料} socket.SCM_CREDS2
@anchor{library/socket socket LOCAL_CREDS}@anchor{382f}
@deffnx {資料} socket.LOCAL_CREDS
@anchor{library/socket socket LOCAL_CREDS_PERSISTENT}@anchor{3830}
@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.


在 3.11 版被加入.


@ref{2006,,可用性}: FreeBSD.
@end deffn

@geindex SO_INCOMING_CPU (於 socket 模組中)
@anchor{library/socket socket SO_INCOMING_CPU}@anchor{3831}
@deffn {資料} socket.SO_INCOMING_CPU

Constant to optimize CPU locality, to be used in conjunction with
@code{SO_REUSEPORT}.


在 3.11 版被加入.


@ref{2006,,可用性}: Linux >= 3.9
@end deffn

@geindex SO_REUSEPORT_LB (於 socket 模組中)
@anchor{library/socket socket SO_REUSEPORT_LB}@anchor{1845}
@deffn {資料} socket.SO_REUSEPORT_LB

@quotation

Constant to enable duplicate address and port bindings with load balancing.
@end quotation


在 3.14 版被加入.


@ref{2006,,可用性}: 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{3806}
@deffn {資料} socket.AF_HYPERV
@anchor{library/socket socket HV_PROTOCOL_RAW}@anchor{3832}
@deffnx {資料} socket.HV_PROTOCOL_RAW
@anchor{library/socket socket HVSOCKET_CONNECT_TIMEOUT}@anchor{3833}
@deffnx {資料} socket.HVSOCKET_CONNECT_TIMEOUT
@anchor{library/socket socket HVSOCKET_CONNECT_TIMEOUT_MAX}@anchor{3834}
@deffnx {資料} socket.HVSOCKET_CONNECT_TIMEOUT_MAX
@anchor{library/socket socket HVSOCKET_CONNECTED_SUSPEND}@anchor{3835}
@deffnx {資料} socket.HVSOCKET_CONNECTED_SUSPEND
@anchor{library/socket socket HVSOCKET_ADDRESS_FLAG_PASSTHRU}@anchor{3836}
@deffnx {資料} socket.HVSOCKET_ADDRESS_FLAG_PASSTHRU
@anchor{library/socket socket HV_GUID_ZERO}@anchor{3837}
@deffnx {資料} socket.HV_GUID_ZERO
@anchor{library/socket socket HV_GUID_WILDCARD}@anchor{3838}
@deffnx {資料} socket.HV_GUID_WILDCARD
@anchor{library/socket socket HV_GUID_BROADCAST}@anchor{3839}
@deffnx {資料} socket.HV_GUID_BROADCAST
@anchor{library/socket socket HV_GUID_CHILDREN}@anchor{383a}
@deffnx {資料} socket.HV_GUID_CHILDREN
@anchor{library/socket socket HV_GUID_LOOPBACK}@anchor{383b}
@deffnx {資料} socket.HV_GUID_LOOPBACK
@anchor{library/socket socket HV_GUID_PARENT}@anchor{383c}
@deffnx {資料} socket.HV_GUID_PARENT

Constants for Windows Hyper-V sockets for host/guest communications.

@ref{2006,,可用性}: Windows.


在 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{1a65}@anchor{library/socket socket ETHERTYPE_ARP}@anchor{383d}
@deffn {資料} socket.ETHERTYPE_ARP
@anchor{library/socket socket ETHERTYPE_IP}@anchor{383e}
@deffnx {資料} socket.ETHERTYPE_IP
@anchor{library/socket socket ETHERTYPE_IPV6}@anchor{383f}
@deffnx {資料} socket.ETHERTYPE_IPV6
@anchor{library/socket socket ETHERTYPE_VLAN}@anchor{3840}
@deffnx {資料} socket.ETHERTYPE_VLAN

IEEE 802.3 protocol number@footnote{https://www.iana.org/assignments/ieee-802-numbers/ieee-802-numbers.txt}.
constants.

@ref{2006,,可用性}: Linux, FreeBSD, macOS.


在 3.12 版被加入.

@end deffn

@geindex SHUT_RD (於 socket 模組中)
@geindex SHUT_WR (於 socket 模組中)
@geindex SHUT_RDWR (於 socket 模組中)
@anchor{library/socket socket SHUT_RD}@anchor{3841}
@deffn {資料} socket.SHUT_RD
@anchor{library/socket socket SHUT_WR}@anchor{3842}
@deffnx {資料} socket.SHUT_WR
@anchor{library/socket socket SHUT_RDWR}@anchor{3843}
@deffnx {資料} socket.SHUT_RDWR

These constants are used by the @ref{3844,,shutdown()} method of socket objects.

@ref{2006,,可用性}: not WASI.
@end deffn

@node 函式<8>,,常數<7>,模組內容<4>
@anchor{library/socket functions}@anchor{3845}
@subsubsection 函式


@menu
* 建立 sockets:: 
* 其他函式: 其他函式<2>. 

@end menu

@node 建立 sockets,其他函式<2>,,函式<8>
@anchor{library/socket creating-sockets}@anchor{3846}
@subsubsection 建立 sockets


The following functions all create @ref{3847,,socket objects}.

@geindex socket (socket 中的類別)
@anchor{library/socket socket socket}@anchor{f9c}
@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{1ad2,,AF_INET} (the default),
@ref{1ad3,,AF_INET6}, @ref{1ad5,,AF_UNIX}, @ref{37fd,,AF_CAN}, @ref{3804,,AF_PACKET},
or @ref{3814,,AF_RDS}. The socket type should be @ref{14f4,,SOCK_STREAM} (the
default), @ref{14f3,,SOCK_DGRAM}, @ref{380d,,SOCK_RAW} or perhaps one of the other
@code{SOCK_} constants. The protocol number is usually zero and may be omitted
or in the case where the address family is @ref{37fd,,AF_CAN} the protocol
should be one of @code{CAN_RAW}, @ref{119e,,CAN_BCM}, @ref{37fe,,CAN_ISOTP} or
@ref{b23,,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{378e,,socket.getpeername()} but not the actual OS resource.  Unlike
@ref{3848,,socket.fromfd()}, `fileno' will return the same socket and not a
duplicate. This may help close a detached socket using
@ref{d62,,socket.close()}.

The newly created socket is @ref{10f7,,non-inheritable}.

引發一個附帶引數 @code{self}、@code{family}、@code{type}、@code{protocol} 的@ref{1b70,,稽核事件} @code{socket.__new__}。


在 3.3 版的變更: The AF_CAN family was added.
The AF_RDS family was added.



在 3.4 版的變更: 新增 CAN_BCM 協定。



在 3.4 版的變更: The returned socket is now non-inheritable.



在 3.7 版的變更: 新增 CAN_ISOTP 協定。



在 3.7 版的變更: When @ref{dff,,SOCK_NONBLOCK} or @ref{e00,,SOCK_CLOEXEC}
bit flags are applied to `type' they are cleared, and
@ref{e01,,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 版的變更: 新增 CAN_J1939 協定。



在 3.10 版的變更: 新增 IPPROTO_MPTCP 協定。

@end deffn

@geindex socketpair() (於 socket 模組中)
@anchor{library/socket socket socketpair}@anchor{deb}
@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{f9c,,socket()} function above. The default family is @ref{1ad5,,AF_UNIX}
if defined on the platform; otherwise, the default is @ref{1ad2,,AF_INET}.

The newly created sockets are @ref{10f7,,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 的支援。

@end deffn

@geindex create_connection() (於 socket 模組中)
@anchor{library/socket socket create_connection}@anchor{87b}
@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{f9e,,socket.connect()}: if `host' is a non-numeric hostname,
it will try to resolve it for both @ref{1ad2,,AF_INET} and @ref{1ad3,,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{3849,,getdefaulttimeout()} is used.

If supplied, `source_address' must be a 2-tuple @code{(host, port)} for the
socket to bind to as its source address before connecting.  If host or port
are '@w{'} or 0 respectively the OS default behavior will be used.

When a connection cannot be created, an exception is raised. By default,
it is the exception from the last address in the list. If `all_errors'
is @code{True}, it is an @ref{4cd,,ExceptionGroup} containing the errors of all
attempts.


在 3.2 版的變更: 新增 `source_address'。



在 3.11 版的變更: 新增 `all_errors'。

@end deffn

@geindex create_server() (於 socket 模組中)
@anchor{library/socket socket create_server}@anchor{c17}
@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{1ad2,,AF_INET} or @ref{1ad3,,AF_INET6}.
`backlog' is the queue size passed to @ref{1059,,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{1ad3,,AF_INET6} and the platform
supports it the socket will be able to accept both IPv4 and IPv6 connections,
else it will raise @ref{2eb,,ValueError}. Most POSIX platforms and Windows are
supposed to support this functionality.
When this functionality is enabled the address returned by
@ref{378e,,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{c18,,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


在 3.8 版被加入.

@end deffn

@geindex has_dualstack_ipv6() (於 socket 模組中)
@anchor{library/socket socket has_dualstack_ipv6}@anchor{c18}
@deffn {函式} socket.has_dualstack_ipv6 ()

Return @code{True} if the platform supports creating a TCP socket which can
handle both IPv4 and IPv6 connections.


在 3.8 版被加入.

@end deffn

@geindex fromfd() (於 socket 模組中)
@anchor{library/socket socket fromfd}@anchor{3848}
@deffn {函式} socket.fromfd (fd, family, type, proto=0)

Duplicate the file descriptor `fd' (an integer as returned by a file object's
@ref{2b7e,,fileno()} method) and build a socket object from the result.  Address
family, socket type and protocol number are as for the @ref{f9c,,socket()} function
above. The file descriptor should refer to a socket, but this is not checked ---
subsequent operations on the object may fail if the file descriptor is invalid.
This function is rarely needed, but can be used to get or set socket options on
a socket passed to a program as standard input or output (such as a server
started by the Unix inet daemon).  The socket is assumed to be in blocking mode.

The newly created socket is @ref{10f7,,non-inheritable}.


在 3.4 版的變更: The returned socket is now non-inheritable.

@end deffn

@geindex fromshare() (於 socket 模組中)
@anchor{library/socket socket fromshare}@anchor{dfc}
@deffn {函式} socket.fromshare (data)

Instantiate a socket from data obtained from the @ref{dfd,,socket.share()}
method.  The socket is assumed to be in blocking mode.

@ref{2006,,可用性}: Windows.


在 3.3 版被加入.

@end deffn

@geindex SocketType (於 socket 模組中)
@anchor{library/socket socket SocketType}@anchor{384a}
@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 其他函式<2>,,建立 sockets,函式<8>
@anchor{library/socket other-functions}@anchor{384b}
@subsubsection 其他函式


The @ref{d1,,socket} module also offers various network-related services:

@geindex close() (於 socket 模組中)
@anchor{library/socket socket close}@anchor{d62}
@deffn {函式} socket.close (fd)

Close a socket file descriptor. This is like @ref{d63,,os.close()}, but for
sockets. On some platforms (most noticeable Windows) @ref{d63,,os.close()}
does not work for socket file descriptors.


在 3.7 版被加入.

@end deffn

@geindex getaddrinfo() (於 socket 模組中)
@anchor{library/socket socket getaddrinfo}@anchor{1a0e}
@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{374f,,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{f9c,,socket()} function.  `canonname' will be
a string representing the canonical name of the `host' if
@code{AI_CANONNAME} is part of the `flags' argument; else `canonname'
will be empty.  `sockaddr' is a tuple describing a socket address, whose
format depends on the returned `family' (a @code{(address, port)} 2-tuple for
@ref{1ad2,,AF_INET}, a @code{(address, port, flowinfo, scope_id)} 4-tuple for
@ref{1ad3,,AF_INET6}), and is meant to be passed to the @ref{f9e,,socket.connect()}
method.

@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{14f4,,SOCK_STREAM} or
@ref{14f3,,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

引發一個附帶引數 @code{host}、@code{port}、@code{family}、@code{type}、@code{protocol} 的@ref{1b70,,稽核事件} @code{socket.getaddrinfo}。

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{1a37}
@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{1b82,,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{2ed8,,gethostname()} is returned.
@end deffn

@geindex gethostbyname() (於 socket 模組中)
@anchor{library/socket socket gethostbyname}@anchor{384c}
@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{1b83,,gethostbyname_ex()} for a more complete
interface. @ref{384c,,gethostbyname()} does not support IPv6 name resolution, and
@ref{1a0e,,getaddrinfo()} should be used instead for IPv4/v6 dual stack support.

引發一個附帶引數 @code{hostname} 的@ref{1b70,,稽核事件} @code{socket.gethostbyname}。

@ref{2006,,可用性}: not WASI.
@end deffn

@geindex gethostbyname_ex() (於 socket 模組中)
@anchor{library/socket socket gethostbyname_ex}@anchor{1b83}
@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). @ref{1b83,,gethostbyname_ex()} does not support IPv6 name
resolution, and @ref{1a0e,,getaddrinfo()} should be used instead for IPv4/v6 dual
stack support.

引發一個附帶引數 @code{hostname} 的@ref{1b70,,稽核事件} @code{socket.gethostbyname}。

@ref{2006,,可用性}: not WASI.
@end deffn

@geindex gethostname() (於 socket 模組中)
@anchor{library/socket socket gethostname}@anchor{2ed8}
@deffn {函式} socket.gethostname ()

Return a string containing the hostname of the machine where  the Python
interpreter is currently executing.

引發一個不附帶引數的@ref{1b70,,稽核事件} @code{socket.gethostname}。

Note: @ref{2ed8,,gethostname()} doesn't always return the fully qualified domain
name; use @ref{1a37,,getfqdn()} for that.

@ref{2006,,可用性}: not WASI.
@end deffn

@geindex gethostbyaddr() (於 socket 模組中)
@anchor{library/socket socket gethostbyaddr}@anchor{1b82}
@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{1a37,,getfqdn()}. @ref{1b82,,gethostbyaddr()} supports
both IPv4 and IPv6.

引發一個附帶引數 @code{ip_address} 的@ref{1b70,,稽核事件} @code{socket.gethostbyaddr}。

@ref{2006,,可用性}: not WASI.
@end deffn

@geindex getnameinfo() (於 socket 模組中)
@anchor{library/socket socket getnameinfo}@anchor{198b}
@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)}}.

引發一個附帶引數 @code{sockaddr} 的@ref{1b70,,稽核事件} @code{socket.getnameinfo}。

@ref{2006,,可用性}: not WASI.
@end deffn

@geindex getprotobyname() (於 socket 模組中)
@anchor{library/socket socket getprotobyname}@anchor{384d}
@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{f9c,,socket()}
function.  This is usually only needed for sockets opened in "raw" mode
(@ref{380d,,SOCK_RAW}); for the normal socket modes, the correct protocol is chosen
automatically if the protocol is omitted or zero.

@ref{2006,,可用性}: not WASI.
@end deffn

@geindex getservbyname() (於 socket 模組中)
@anchor{library/socket socket getservbyname}@anchor{384e}
@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.

引發一個附帶引數 @code{sockaddr}、@code{protocolname} 的@ref{1b70,,稽核事件} @code{socket.getservbyname}。

@ref{2006,,可用性}: not WASI.
@end deffn

@geindex getservbyport() (於 socket 模組中)
@anchor{library/socket socket getservbyport}@anchor{384f}
@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.

引發一個附帶引數 @code{port}、@code{protocolname} 的@ref{1b70,,稽核事件} @code{socket.getservbyport}。

@ref{2006,,可用性}: not WASI.
@end deffn

@geindex ntohl() (於 socket 模組中)
@anchor{library/socket socket ntohl}@anchor{3850}
@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{a77}
@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{a78,,OverflowError} if `x' does not fit in a 16-bit unsigned
integer.

@end deffn

@geindex htonl() (於 socket 模組中)
@anchor{library/socket socket htonl}@anchor{3851}
@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{a76}
@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{a78,,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{b51}
@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.

@ref{b51,,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{2c0,,OSError} will be raised. Note that exactly what is valid depends on
the underlying C implementation of @code{inet_aton()}.

@ref{b51,,inet_aton()} does not support IPv6, and @ref{b52,,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{3852}
@deffn {函式} socket.inet_ntoa (packed_ip)

Convert a 32-bit packed IPv4 address (a @ref{193,,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{2c0,,OSError} will be raised. @ref{3852,,inet_ntoa()} does not
support IPv6, and @ref{11a0,,inet_ntop()} should be used instead for IPv4/v6 dual
stack support.


在 3.5 版的變更: Writable @ref{193,,bytes-like object} is now accepted.

@end deffn

@geindex inet_pton() (於 socket 模組中)
@anchor{library/socket socket inet_pton}@anchor{b52}
@deffn {函式} socket.inet_pton (address_family, ip_string)

Convert an IP address from its family-specific string format to a packed,
binary format. @ref{b52,,inet_pton()} is useful when a library or network protocol
calls for an object of type @code{in_addr} (similar to
@ref{b51,,inet_aton()}) or @code{in6_addr}.

Supported values for `address_family' are currently @ref{1ad2,,AF_INET} and
@ref{1ad3,,AF_INET6}. If the IP address string `ip_string' is invalid,
@ref{2c0,,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{2006,,可用性}: Unix, Windows.


在 3.4 版的變更: Windows support added

@end deffn

@geindex inet_ntop() (於 socket 模組中)
@anchor{library/socket socket inet_ntop}@anchor{11a0}
@deffn {函式} socket.inet_ntop (address_family, packed_ip)

Convert a packed IP address (a @ref{193,,bytes-like object} of some number of
bytes) to its standard, family-specific string representation (for
example, @code{'7.10.0.5'} or @code{'5aef:2b::8'}).
@ref{11a0,,inet_ntop()} is useful when a library or network protocol returns an
object of type @code{in_addr} (similar to @ref{3852,,inet_ntoa()}) or
@code{in6_addr}.

Supported values for `address_family' are currently @ref{1ad2,,AF_INET} and
@ref{1ad3,,AF_INET6}. If the bytes object `packed_ip' is not the correct
length for the specified address family, @ref{2eb,,ValueError} will be raised.
@ref{2c0,,OSError} is raised for errors from the call to @ref{11a0,,inet_ntop()}.

@ref{2006,,可用性}: Unix, Windows.


在 3.4 版的變更: Windows support added



在 3.5 版的變更: Writable @ref{193,,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{1ce0}
@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{fa1,,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{1cdf,,CMSG_SPACE()} and thus include
space for padding, even when the item will be the last in the
buffer.  Raises @ref{a78,,OverflowError} if `length' is outside the
permissible range of values.

@ref{2006,,可用性}: Unix, not WASI.

Most Unix platforms.


在 3.3 版被加入.

@end deffn

@geindex CMSG_SPACE() (於 socket 模組中)
@anchor{library/socket socket CMSG_SPACE}@anchor{1cdf}
@deffn {函式} socket.CMSG_SPACE (length)

Return the buffer size needed for @ref{fa1,,recvmsg()} to
receive an ancillary data item with associated data of the given
`length', along with any trailing padding.  The buffer space needed
to receive multiple items is the sum of the @ref{1cdf,,CMSG_SPACE()}
values for their associated data lengths.  Raises
@ref{a78,,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{2006,,可用性}: Unix, not WASI.

most Unix platforms.


在 3.3 版被加入.

@end deffn

@geindex getdefaulttimeout() (於 socket 模組中)
@anchor{library/socket socket getdefaulttimeout}@anchor{3849}
@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{380b}
@deffn {函式} socket.setdefaulttimeout (timeout)

Set the default timeout in seconds (float) for new socket objects.  When
the socket module is first imported, the default is @code{None}.  See
@ref{3807,,settimeout()} for possible values and their respective
meanings.
@end deffn

@geindex sethostname() (於 socket 模組中)
@anchor{library/socket socket sethostname}@anchor{133c}
@deffn {函式} socket.sethostname (name)

Set the machine's hostname to `name'.  This will raise an
@ref{2c0,,OSError} if you don't have enough rights.

引發一個附帶引數 @code{name} 的@ref{1b70,,稽核事件} @code{socket.sethostname}。

@ref{2006,,可用性}: Unix, not Android.


在 3.3 版被加入.

@end deffn

@geindex if_nameindex() (於 socket 模組中)
@anchor{library/socket socket if_nameindex}@anchor{c19}
@deffn {函式} socket.if_nameindex ()

Return a list of network interface information
(index int, name string) tuples.
@ref{2c0,,OSError} if the system call fails.

@ref{2006,,可用性}: Unix, Windows, not WASI.


在 3.3 版被加入.



在 3.8 版的變更: 增加對 Windows 的支援。


@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{c1a}
@deffn {函式} socket.if_nametoindex (if_name)

Return a network interface index number corresponding to an
interface name.
@ref{2c0,,OSError} if no interface with the given name exists.

@ref{2006,,可用性}: Unix, Windows, not WASI.


在 3.3 版被加入.



在 3.8 版的變更: 增加對 Windows 的支援。



@subsubheading 也參考


"Interface name" is a name as documented in @ref{c19,,if_nameindex()}.

@end deffn

@geindex if_indextoname() (於 socket 模組中)
@anchor{library/socket socket if_indextoname}@anchor{c1b}
@deffn {函式} socket.if_indextoname (if_index)

Return a network interface name corresponding to an
interface index number.
@ref{2c0,,OSError} if no interface with the given index exists.

@ref{2006,,可用性}: Unix, Windows, not WASI.


在 3.3 版被加入.



在 3.8 版的變更: 增加對 Windows 的支援。



@subsubheading 也參考


"Interface name" is a name as documented in @ref{c19,,if_nameindex()}.

@end deffn

@geindex send_fds() (於 socket 模組中)
@anchor{library/socket socket send_fds}@anchor{b24}
@deffn {函式} socket.send_fds (sock, buffers, fds[, flags[, address]])

Send the list of file descriptors `fds' over an @ref{1ad5,,AF_UNIX} socket `sock'.
The `fds' parameter is a sequence of file descriptors.
Consult @ref{69a,,sendmsg()} for the documentation of these parameters.

@ref{2006,,可用性}: Unix, not WASI.

Unix platforms supporting @ref{69a,,sendmsg()}
and @code{SCM_RIGHTS} mechanism.


在 3.9 版被加入.

@end deffn

@geindex recv_fds() (於 socket 模組中)
@anchor{library/socket socket recv_fds}@anchor{b25}
@deffn {函式} socket.recv_fds (sock, bufsize, maxfds[, flags])

Receive up to `maxfds' file descriptors from an @ref{1ad5,,AF_UNIX} socket `sock'.
Return @code{(msg, list(fds), flags, addr)}.
Consult @ref{fa1,,recvmsg()} for the documentation of these parameters.

@ref{2006,,可用性}: Unix, not WASI.

Unix platforms supporting @ref{fa1,,recvmsg()}
and @code{SCM_RIGHTS} mechanism.


在 3.9 版被加入.


@cartouche
@quotation 備註 
Any truncated integers at the end of the list of file descriptors.
@end quotation
@end cartouche
@end deffn

@node Socket 物件,Notes on socket timeouts,模組內容<4>,socket — 低階網路介面
@anchor{library/socket id1}@anchor{3853}@anchor{library/socket socket-objects}@anchor{3847}
@subsubsection Socket 物件


Socket objects have the following methods.  Except for
@ref{13a0,,makefile()}, these correspond to Unix system calls applicable
to sockets.


在 3.2 版的變更: Support for the @ref{1e1,,context manager} protocol was added.  Exiting the
context manager is equivalent to calling @ref{d62,,close()}.


@geindex accept() (socket.socket 的方法)
@anchor{library/socket socket socket accept}@anchor{f9d}
@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{10f7,,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{f83,,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{172e}
@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 above.)

引發一個附帶引數 @code{self}、@code{address} 的@ref{1b70,,稽核事件} @code{socket.bind}。

@ref{2006,,可用性}: not WASI.
@end deffn

@geindex close() (socket.socket 的方法)
@anchor{library/socket socket socket close}@anchor{f3a}
@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{13a0,,makefile()}
are closed.  Once that happens, all future operations on the socket
object will fail. The remote end will receive no more data (after
queued data is flushed).

Sockets are automatically closed when they are garbage-collected, but
it is recommended to @ref{d62,,close()} them explicitly, or to use a
@ref{186,,with} statement around them.


在 3.6 版的變更: @ref{2c0,,OSError} is now raised if an error occurs when the underlying
@code{close()} call is made.


@cartouche
@quotation 備註 
@ref{d62,,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{3844,,shutdown()}
before @ref{d62,,close()}.
@end quotation
@end cartouche
@end deffn

@geindex connect() (socket.socket 的方法)
@anchor{library/socket socket socket connect}@anchor{f9e}
@deffn {方法} socket.connect (address)

Connect to a remote socket at `address'. (The format of `address' depends on the
address family --- see above.)

If the connection is interrupted by a signal, the method waits until the
connection completes, or raise a @ref{a2f,,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{f83,,InterruptedError} exception if the connection is interrupted by a
signal (or the exception raised by the signal handler).

引發一個附帶引數 @code{self}、@code{address} 的@ref{1b70,,稽核事件} @code{socket.connect}。


在 3.5 版的變更: The method now waits until the connection completes instead of raising an
@ref{f83,,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{2006,,可用性}: not WASI.
@end deffn

@geindex connect_ex() (socket.socket 的方法)
@anchor{library/socket socket socket connect_ex}@anchor{172d}
@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.

引發一個附帶引數 @code{self}、@code{address} 的@ref{1b70,,稽核事件} @code{socket.connect}。

@ref{2006,,可用性}: not WASI.
@end deffn

@geindex detach() (socket.socket 的方法)
@anchor{library/socket socket socket detach}@anchor{141d}
@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.


在 3.2 版被加入.

@end deffn

@geindex dup() (socket.socket 的方法)
@anchor{library/socket socket socket dup}@anchor{3854}
@deffn {方法} socket.dup ()

Duplicate the socket.

The newly created socket is @ref{10f7,,non-inheritable}.


在 3.4 版的變更: The socket is now non-inheritable.


@ref{2006,,可用性}: not WASI.
@end deffn

@geindex fileno() (socket.socket 的方法)
@anchor{library/socket socket socket fileno}@anchor{3855}
@deffn {方法} socket.fileno ()

Return the socket's file descriptor (a small integer), or -1 on failure. This
is useful with @ref{f9b,,select.select()}.

Under Windows the small integer returned by this method cannot be used where a
file descriptor can be used (such as @ref{2232,,os.fdopen()}).  Unix does not have
this limitation.
@end deffn

@geindex get_inheritable() (socket.socket 的方法)
@anchor{library/socket socket socket get_inheritable}@anchor{10fc}
@deffn {方法} socket.get_inheritable ()

Get the @ref{10f7,,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.


在 3.4 版被加入.

@end deffn

@geindex getpeername() (socket.socket 的方法)
@anchor{library/socket socket socket getpeername}@anchor{378e}
@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 above.)  On some
systems this function is not supported.
@end deffn

@geindex getsockname() (socket.socket 的方法)
@anchor{library/socket socket socket getsockname}@anchor{284}
@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 above.)
@end deffn

@geindex getsockopt() (socket.socket 的方法)
@anchor{library/socket socket socket getsockopt}@anchor{ecb}
@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{d64,,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{db,,struct} for a way
to decode C structures encoded as byte strings).

@ref{2006,,可用性}: not WASI.
@end deffn

@geindex getblocking() (socket.socket 的方法)
@anchor{library/socket socket socket getblocking}@anchor{d61}
@deffn {方法} socket.getblocking ()

Return @code{True} if socket is in blocking mode, @code{False} if in
non-blocking.

這等同於檢查 @code{socket.gettimeout() != 0}。


在 3.7 版被加入.

@end deffn

@geindex gettimeout() (socket.socket 的方法)
@anchor{library/socket socket socket gettimeout}@anchor{3856}
@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{2eee,,setblocking()} or @ref{3807,,settimeout()}.
@end deffn

@geindex ioctl() (socket.socket 的方法)
@anchor{library/socket socket socket ioctl}@anchor{ec9}
@deffn {方法} socket.ioctl (control, option)

The @ref{ec9,,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{17d0,,fcntl.fcntl()} and @ref{166f,,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{2006,,可用性}: Windows


在 3.6 版的變更: 加入 @code{SIO_LOOPBACK_FAST_PATH}。

@end deffn

@geindex listen() (socket.socket 的方法)
@anchor{library/socket socket socket listen}@anchor{1059}
@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{2006,,可用性}: not WASI.


在 3.5 版的變更: The `backlog' parameter is now optional.

@end deffn

@geindex makefile() (socket.socket 的方法)
@anchor{library/socket socket socket makefile}@anchor{13a0}
@deffn {方法} socket.makefile (mode='r', buffering=None, *, encoding=None, errors=None, newline=None)

@geindex I/O control（I/O 控制）;buffering（緩衝）

Return a @ref{13c4,,file object} associated with the socket.  The exact returned
type depends on the arguments given to @ref{13a0,,makefile()}.  These arguments are
interpreted the same way as by the built-in @ref{315,,open()} function, except
the only supported `mode' values are @code{'r'} (default), @code{'w'}, @code{'b'}, or
a combination of those.

The socket must be in blocking mode; it can have a timeout, but the file
object's internal buffer may end up in an inconsistent state if a timeout
occurs.

Closing the file object returned by @ref{13a0,,makefile()} won't close the
original socket unless all other file objects have been closed and
@ref{d62,,socket.close()} has been called on the socket object.

@cartouche
@quotation 備註 
On Windows, the file-like object created by @ref{13a0,,makefile()} cannot be
used where a file object with a file descriptor is expected, such as the
stream arguments of @ref{4b2,,subprocess.Popen()}.
@end quotation
@end cartouche
@end deffn

@geindex recv() (socket.socket 的方法)
@anchor{library/socket socket socket recv}@anchor{f9f}
@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{f83,,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{fa0}
@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 above.)


在 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{f83,,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{198b,,getnameinfo()}.

@end deffn

@geindex recvmsg() (socket.socket 的方法)
@anchor{library/socket socket socket recvmsg}@anchor{fa1}
@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{1cdf,,CMSG_SPACE()} or @ref{1ce0,,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{f9f,,recv()}.

The return value is a 4-tuple: @code{(data, ancdata, msg_flags,
address)}.  The `data' item is a @ref{192,,bytes} object holding the
non-ancillary data received.  The `ancdata' item is a list of zero
or more tuples @code{(cmsg_level, cmsg_type, cmsg_data)} representing
the ancillary data (control messages) received: `cmsg_level' and
`cmsg_type' are integers specifying the protocol level and
protocol-specific type respectively, and `cmsg_data' is a
@ref{192,,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{69a,,sendmsg()} and @ref{fa1,,recvmsg()} can be used to
pass file descriptors between processes over an @ref{1ad5,,AF_UNIX}
socket.  When this facility is used (it is often restricted to
@ref{14f4,,SOCK_STREAM} sockets), @ref{fa1,,recvmsg()} will return, in its
ancillary data, items of the form @code{(socket.SOL_SOCKET,
socket.SCM_RIGHTS, fds)}, where `fds' is a @ref{192,,bytes} object
representing the new file descriptors as a binary array of the
native C int type.  If @ref{fa1,,recvmsg()} raises an
exception after the system call returns, it will first attempt to
close any file descriptors received via this mechanism.

Some systems do not indicate the truncated length of ancillary data
items which have been only partially received.  If an item appears
to extend beyond the end of the buffer, @ref{fa1,,recvmsg()} will issue
a @ref{4d2,,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{69a,,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{2006,,可用性}: Unix.

Most Unix platforms.


在 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{f83,,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{133b}
@deffn {方法} socket.recvmsg_into (buffers[, ancbufsize[, flags]])

Receive normal data and ancillary data from the socket, behaving as
@ref{fa1,,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{343,,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{185a,,sysconf()} value @code{SC_IOV_MAX})
on the number of buffers that can be used.  The `ancbufsize' and
`flags' arguments have the same meaning as for @ref{fa1,,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{fa1,,recvmsg()}.

範例：

@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{2006,,可用性}: Unix.

Most Unix platforms.


在 3.3 版被加入.

@end deffn

@geindex recvfrom_into() (socket.socket 的方法)
@anchor{library/socket socket socket recvfrom_into}@anchor{151f}
@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 above.)
@end deffn

@geindex recv_into() (socket.socket 的方法)
@anchor{library/socket socket socket recv_into}@anchor{151e}
@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{fa2}
@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{f9f,,recv()} above.
Returns the number of bytes sent. Applications are responsible for checking that
all data has been sent; if only some of the data was transmitted, the
application needs to attempt delivery of the remaining data. For further
information on this topic, consult the @ref{3857,,Socket 程式設計指南}.


在 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{f83,,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{fa3}
@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{f9f,,recv()} above.
Unlike @ref{fa2,,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{f83,,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{fa4}
@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{f9f,,recv()} above.  Return the number of
bytes sent. (The format of `address' depends on the address family --- see
above.)

引發一個附帶引數 @code{self}、@code{address} 的@ref{1b70,,稽核事件} @code{socket.sendto}。


在 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{f83,,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{69a}
@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{193,,bytes-like objects}
(e.g. @ref{192,,bytes} objects); the operating system may set a limit
(@ref{185a,,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{1cdf,,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{fa2,,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{1ad5,,AF_UNIX} socket, on systems which support the
@code{SCM_RIGHTS} mechanism.  See also @ref{fa1,,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{2006,,可用性}: Unix, not WASI.

Most Unix platforms.

引發一個附帶引數 @code{self}、@code{address} 的@ref{1b70,,稽核事件} @code{socket.sendmsg}。


在 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{f83,,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{ece}
@deffn {方法} socket.sendmsg_afalg ([msg], *, op[, iv[, assoclen[, flags]]])

Specialized version of @ref{69a,,sendmsg()} for @ref{ecd,,AF_ALG} socket.
Set mode, IV, AEAD associated data length and flags for @ref{ecd,,AF_ALG} socket.

@ref{2006,,可用性}: Linux >= 2.6.38.


在 3.6 版被加入.

@end deffn

@geindex sendfile() (socket.socket 的方法)
@anchor{library/socket socket socket sendfile}@anchor{1058}
@deffn {方法} socket.sendfile (file, offset=0, count=None)

Send a file until EOF is reached by using high-performance
@ref{cfd,,os.sendfile} and return the total number of bytes which were sent.
`file' must be a regular file object opened in binary mode. If
@ref{cfd,,os.sendfile} is not available (e.g. Windows) or `file' is not a
regular file @ref{fa2,,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{15a4,,file.tell()} can be used to figure out the number of
bytes which were sent. The socket must be of @ref{14f4,,SOCK_STREAM} type.
Non-blocking sockets are not supported.


在 3.5 版被加入.

@end deffn

@geindex set_inheritable() (socket.socket 的方法)
@anchor{library/socket socket socket set_inheritable}@anchor{10fd}
@deffn {方法} socket.set_inheritable (inheritable)

Set the @ref{10f7,,inheritable flag} of the socket's file
descriptor or socket's handle.


在 3.4 版被加入.

@end deffn

@geindex setblocking() (socket.socket 的方法)
@anchor{library/socket socket socket setblocking}@anchor{2eee}
@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{3807,,settimeout()} calls:


@itemize *

@item 
@code{sock.setblocking(True)} 等價於 @code{sock.settimeout(None)}

@item 
@code{sock.setblocking(False)} 等價於 @code{sock.settimeout(0.0)}
@end itemize


在 3.7 版的變更: The method no longer applies @ref{dff,,SOCK_NONBLOCK} flag on
@ref{e01,,socket.type}.

@end deffn

@geindex settimeout() (socket.socket 的方法)
@anchor{library/socket socket socket settimeout}@anchor{3807}
@deffn {方法} socket.settimeout (value)

Set a timeout on blocking socket operations.  The `value' argument can be a
nonnegative floating-point number expressing seconds, or @code{None}.
If a non-zero value is given, subsequent socket operations will raise a
@ref{a2e,,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{3858,,notes on socket timeouts}.


在 3.7 版的變更: The method no longer toggles @ref{dff,,SOCK_NONBLOCK} flag on
@ref{e01,,socket.type}.

@end deffn

@geindex setsockopt() (socket.socket 的方法)
@anchor{library/socket socket socket setsockopt}@anchor{ecc}
@deffn {方法} socket.setsockopt (level, optname, value: int)
@end deffn


@deffn {方法} socket.setsockopt (level, optname, value: buffer)
@end deffn


@deffn {方法} 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{193,,bytes-like object} representing a buffer. In the later
case it is up to the caller to ensure that the bytestring contains the
proper bits (see the optional built-in module @ref{db,,struct} for a way to
encode C structures as bytestrings). When `value' is set to @code{None},
`optlen' argument is required. It's equivalent to call @code{setsockopt()} C
function with @code{optval=NULL} and @code{optlen=optlen}.


在 3.5 版的變更: Writable @ref{193,,bytes-like object} is now accepted.



在 3.6 版的變更: setsockopt(level, optname, None, optlen: int) form added.


@ref{2006,,可用性}: not WASI.
@end deffn

@geindex shutdown() (socket.socket 的方法)
@anchor{library/socket socket socket shutdown}@anchor{3844}
@deffn {方法} socket.shutdown (how)

Shut down one or both halves of the connection.  If `how' is @ref{3841,,SHUT_RD},
further receives are disallowed.  If `how' is @ref{3842,,SHUT_WR}, further sends
are disallowed.  If `how' is @ref{3843,,SHUT_RDWR}, further sends and receives are
disallowed.

@ref{2006,,可用性}: not WASI.
@end deffn

@geindex share() (socket.socket 的方法)
@anchor{library/socket socket socket share}@anchor{dfd}
@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{dfc,,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{2006,,可用性}: Windows.


在 3.3 版被加入.

@end deffn

Note that there are no methods @code{read()} or @code{write()}; use
@ref{f9f,,recv()} and @ref{fa2,,send()} without `flags' argument instead.

Socket objects also have these (read-only) attributes that correspond to the
values given to the @ref{f9c,,socket} constructor.

@geindex family (socket.socket 的屬性)
@anchor{library/socket socket socket family}@anchor{3859}
@deffn {屬性} socket.family

The socket family.
@end deffn

@geindex type (socket.socket 的屬性)
@anchor{library/socket socket socket type}@anchor{e01}
@deffn {屬性} socket.type

The socket type.
@end deffn

@geindex proto (socket.socket 的屬性)
@anchor{library/socket socket socket proto}@anchor{385a}
@deffn {屬性} socket.proto

The socket protocol.
@end deffn

@node Notes on socket timeouts,範例<26>,Socket 物件,socket — 低階網路介面
@anchor{library/socket notes-on-socket-timeouts}@anchor{385b}@anchor{library/socket socket-timeouts}@anchor{3858}
@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{380b,,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{c6,,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{a2e,,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{3855,,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{385c}
@subsubsection Timeouts and the @code{connect} method


The @ref{f9e,,connect()} operation is also subject to the timeout
setting, and in general it is recommended to call @ref{3807,,settimeout()}
before calling @ref{f9e,,connect()} or pass a timeout parameter to
@ref{87b,,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{385d}
@subsubsection Timeouts and the @code{accept} method


If @ref{3849,,getdefaulttimeout()} is not @ref{87e,,None}, sockets returned by
the @ref{f9d,,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{f9d,,accept()} is in `blocking mode';

@item 
if the listening socket is in `non-blocking mode', whether the socket
returned by @ref{f9d,,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 範例<26>,,Notes on socket timeouts,socket — 低階網路介面
@anchor{library/socket example}@anchor{385e}@anchor{library/socket socket-example}@anchor{385f}
@subsubsection 範例


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{f9c,,socket()},
@ref{172e,,bind()}, @ref{1059,,listen()}, @ref{f9d,,accept()} (possibly
repeating the @ref{f9d,,accept()} to service more than one client), while a
client only needs the sequence @ref{f9c,,socket()}, @ref{f9e,,connect()}.  Also
note that the server does not @ref{fa3,,sendall()}/@ref{f9f,,recv()} on
the socket it is listening on but on the new socket returned by
@ref{f9d,,accept()}.

前兩個範例只支援 IPv4：

@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{119e,,CAN_BCM}) the socket, you
can use the @ref{fa2,,socket.send()} and @ref{f9f,,socket.recv()} operations (and
their counterparts) on the socket object as usual.

This last example might require special privileges:

@example
import socket
import struct


# CAN frame packing/unpacking (see 'struct can_frame' in <linux/can.h>)

can_frame_fmt = "=IB3x8s"
can_frame_size = struct.calcsize(can_frame_fmt)

def build_can_frame(can_id, data):
    can_dlc = len(data)
    data = data.ljust(8, b'\x00')
    return struct.pack(can_frame_fmt, can_id, can_dlc, data)

def dissect_can_frame(frame):
    can_id, can_dlc, data = struct.unpack(can_frame_fmt, frame)
    return (can_id, can_dlc, data[:can_dlc])


# create a raw socket and bind it to the 'vcan0' interface
s = socket.socket(socket.AF_CAN, socket.SOCK_RAW, socket.CAN_RAW)
s.bind(('vcan0',))

while True:
    cf, addr = s.recvfrom(can_frame_size)

    print('Received: can_id=%x, can_dlc=%x, data=%s' % dissect_can_frame(cf))

    try:
        s.send(cf)
    except OSError:
        print('Error sending CAN frame')

    try:
        s.send(build_can_frame(0x01, b'\x01\x02\x03'))
    except OSError:
        print('Error sending CAN frame')
@end example

Running an example several times with too small delay between executions, could
lead to this error:

@example
OSError: [Errno 98] Address already in use
@end example

This is because the previous execution has left the socket in a @code{TIME_WAIT}
state, and can't be immediately reused.

There is a @ref{d1,,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 --- socket 物件的 TLS/SSL 包裝器,select --- 等待 I/O 完成,socket — 低階網路介面,網路與行程間通訊
@anchor{library/ssl doc}@anchor{3860}@anchor{library/ssl module-ssl}@anchor{d5}@anchor{library/ssl ssl-tls-ssl-wrapper-for-socket-objects}@anchor{3861}@anchor{library/ssl translation-repo}@anchor{3862}
@subsection @code{ssl} --- socket 物件的 TLS/SSL 包裝器


@geindex module; ssl

`原始碼：'Lib/ssl.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/ssl.py}

@geindex OpenSSL;（用於 ssl 模組）

@geindex TLS
@geindex SSL
@geindex Transport Layer Security（傳輸層安全）
@geindex Secure Sockets Layer（安全 socket 層）


__________________________________________________________________


這個模組向用戶端及伺服器端提供了對於網路 socket 的傳輸層安全性協定（或稱為「安全通訊協定 (Secure Sockets Layer)」）加密及身分驗證功能。這個模組使用 OpenSSL 套件，它可以在所有的 Unix 系統、Windows、macOS、以及其他任何可能的平台上使用，只要事先在該平台上安裝 OpenSSL。

@cartouche
@quotation 備註 
由於呼叫了作業系統的 socket APIs，有些行為會根據平台而有所不同。OpenSSL 的安裝版本也會對模組的運作產生影響。例如，OpenSSL 版本 1.1.1 附帶 TLSv1.3。
@end quotation
@end cartouche

@cartouche
@quotation 警告 
在使用此模組之前，請閱讀 @ref{374a,,Security considerations}。如果不這樣做，可能會產生錯誤的安全性認知，因為 ssl 模組的預設設定未必適合你的應用程式。
@end quotation
@end cartouche

@c include for modules that don't work on WASM

@ref{2006,,可用性}: not WASI.

此模組在 WebAssembly 平台上不起作用或無法使用。更多資訊請參閱 @ref{1a99,,WebAssembly 平台}。

這個章節記錄了 @code{ssl} 模組的物件及函式；關於 TSL、SSL、以及憑證的更多資訊，可以去參考此章節底部的「詳情」部分。

此模組提供了一個 @ref{ade,,ssl.SSLSocket} 類別，它是從 @ref{f9c,,socket.socket} 衍生出來的，並且提供類似 socket 的包裝器，讓使用 SSL 進行資料傳輸時，可以進行資料的加密及解密。它也提供了一些額外的方法，如 @code{getpeercert()}，用於取得連結另一端的憑證；以及 @code{cipher()}，用於搜尋用於安全連接的加密方法 (cipher)；和 @code{get_verified_chain()}、@code{get_unverified_chain()} 能用於取得憑證鏈。

對於更複雜的應用程式，@ref{355,,ssl.SSLContext} 類別有助於管理設定及認證，然後可以透過 @ref{741,,SSLContext.wrap_socket()} 方法建立的 SSL socket 繼承這些設定和認證。


在 3.5.3 版的變更: 更新以支援與 OpenSSL 1.1.0 進行連結



在 3.6 版的變更: OpenSSL 0.9.8, 1.0.0 及 1.0.1 版本已被棄用且不再支援。在未來 ssl 模組將需要至少 OpenSSL 1.0.2 版本或 1.1.0 版本。



在 3.10 版的變更: 
@geindex Python Enhancement Proposals; PEP 644
PEP 644@footnote{https://peps.python.org/pep-0644/} 已經被實作。ssl 模組需要 OpenSSL 1.1.1 以上的版本才能使用。

使用已經被棄用的常數或函式將會導致棄用警示。


@menu
* 函式、常數與例外:: 
* SSL Sockets:: 
* SSL Contexts:: 
* Certificates:: 
* 範例: 範例<27>. 
* Notes on non-blocking sockets:: 
* 記憶體 BIO 支援: 記憶體 BIO 支援<2>. 
* SSL session:: 
* Security considerations: Security considerations<2>. 
* TLS 1.3: TLS 1 3. 

@end menu

@node 函式、常數與例外,SSL Sockets,,ssl --- socket 物件的 TLS/SSL 包裝器
@anchor{library/ssl functions-constants-and-exceptions}@anchor{3863}
@subsubsection 函式、常數與例外


@menu
* Socket 建立:: 
* 語境建立:: 
* 例外: 例外<17>. 
* 隨機產生:: 
* 認證處理:: 
* 常數: 常數<8>. 

@end menu

@node Socket 建立,語境建立,,函式、常數與例外
@anchor{library/ssl socket-creation}@anchor{3864}
@subsubsection Socket 建立


@ref{ade,,SSLSocket} 實例必須使用 @ref{741,,SSLContext.wrap_socket()} 方法來建立。輔助函式 @ref{47a,,create_default_context()} 會回傳有安全預設設定的新語境 (context)。

使用預設語境及 IPv4/IPv6 雙協定堆疊的用戶端 socket 範例：

@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

使用自訂語境及 IPv4 的用戶端 socket範例：

@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

在本地 IPv4 上監聽伺服器 socket 的範例：

@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 語境建立,例外<17>,Socket 建立,函式、常數與例外
@anchor{library/ssl context-creation}@anchor{3865}
@subsubsection 語境建立


一個可以幫忙建立出 @ref{355,,SSLContext} 物件以用於一般目的的方便函式。

@geindex create_default_context() (於 ssl 模組中)
@anchor{library/ssl ssl create_default_context}@anchor{47a}
@deffn {函式} ssl.create_default_context (purpose=Purpose.SERVER_AUTH, *, cafile=None, capath=None, cadata=None)

回傳一個新的 @ref{355,,SSLContext} 物件，使用給定 `purpose' 的預設值。這些設定是由 @ref{d5,,ssl} 選擇，通常比直接呼叫 @ref{355,,SSLContext} 有更高的安全性。

`cafile', `capath', `cadata' 是用來選擇用於憑證認證的 CA 憑證，就像 @ref{10e9,,SSLContext.load_verify_locations()} 一樣。如果三個值都是 @ref{87e,,None}，此函式會自動選擇系統預設的 CA 憑證。

這些設定包含：@ref{a69,,PROTOCOL_TLS_CLIENT} 或 @ref{a6a,,PROTOCOL_TLS_SERVER}、@ref{a33,,OP_NO_SSLv2}、以及 @ref{a34,,OP_NO_SSLv3}，使用高等加密套件但不包含 RC4 和未經身份驗證的加密套件。如果將 `purpose' 設定為 @ref{11ae,,SERVER_AUTH}，則會把 @ref{3866,,verify_mode} 設為 @ref{3867,,CERT_REQUIRED} 並使用設定的 CA 憑證(當 `cafile'、`capath' 或 `cadata' 其中一個值有被設定時) 或使用預設的 CA 憑證  @ref{11ad,,SSLContext.load_default_certs()} 。

當系統有支援 @ref{3868,,keylog_filename} 並且有設定環境變數 
@geindex SSLKEYLOGFILE
@geindex 環境變數; SSLKEYLOGFILE
@code{SSLKEYLOGFILE} 時 @ref{47a,,create_default_context()} 會啟用密鑰日誌記錄 (logging)。

The default settings for this context include
@ref{47b,,VERIFY_X509_PARTIAL_CHAIN} and @ref{47c,,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 備註 
協定、選項、加密方式和其它設定可以在不捨棄舊值的情況下直接更改成新的值，這些值代表了在相容性和安全性之間取得的合理平衡。

如果你的應用程式需要特殊的設定，你應該要自行建立一個 @ref{355,,SSLContext} 並自行調整設定。
@end quotation
@end cartouche

@cartouche
@quotation 備註 
如果你發現某些舊的用戶端或伺服器常適用此函式建立的 @ref{355,,SSLContext} 連線時，收到 "Protocol or cipher suite mismatch" 錯誤，這可能是因為他們的系統僅支援 SSL3.0，然而 SSL3.0 已被此函式用 @ref{a34,,OP_NO_SSLv3} 排除。目前廣泛認為 SSL3.0 已經被完全破解@footnote{https://en.wikipedia.org/wiki/POODLE}。如果你仍然希望在允許 SSL3.0 連線的情況下使用此函式，可以使用下面的方法：

@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{47c,,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


在 3.4 版被加入.



在 3.4.4 版的變更: 把 RC4 從預設加密方法字串中捨棄。



在 3.6 版的變更: 把 ChaCha20/Poly1305 加入預設加密方法字串。

把 3DES 從預設加密方法字串中捨棄。



在 3.8 版的變更: 增加了 
@geindex SSLKEYLOGFILE
@geindex 環境變數; SSLKEYLOGFILE
@code{SSLKEYLOGFILE} 對密鑰日誌記錄 (logging) 的支援。



在 3.10 版的變更: 目前語境使用 @ref{a69,,PROTOCOL_TLS_CLIENT} 協定或 @ref{a6a,,PROTOCOL_TLS_SERVER} 協定而非通用的 @ref{3869,,PROTOCOL_TLS}。



在 3.13 版的變更: The context now uses @ref{47b,,VERIFY_X509_PARTIAL_CHAIN} and
@ref{47c,,VERIFY_X509_STRICT} in its default verify flags.

@end deffn

@node 例外<17>,隨機產生,語境建立,函式、常數與例外
@anchor{library/ssl exceptions}@anchor{386a}
@subsubsection 例外


@geindex SSLError
@anchor{library/ssl ssl SSLError}@anchor{147a}
@deffn {例外} ssl.SSLError

引發由底層 SSL 實作（目前由 OpenSSL 函式庫提供）所引發的錯誤訊息。這表示在覆蓋底層網路連線的高階加密和身份驗證層中存在一些問題。這項錯誤是 @ref{2c0,,OSError} 的一個子型別。@ref{147a,,SSLError} 實例的錯誤程式代碼和訊息是由 OpenSSL 函式庫提供。


在 3.3 版的變更: @ref{147a,,SSLError} 曾經是 @ref{1251,,socket.error} 的一個子型別。


@geindex library (ssl.SSLError 的屬性)
@anchor{library/ssl ssl SSLError library}@anchor{1348}
@deffn {屬性} library

一個字串符號 (string mnemonic)，用來指定發生錯誤的 OpenSSL 子模組，如：@code{SSL}、@code{PEM} 或 @code{X509}。可能值的範圍取決於 OpenSSL 的版本。


在 3.3 版被加入.

@end deffn

@geindex reason (ssl.SSLError 的屬性)
@anchor{library/ssl ssl SSLError reason}@anchor{1349}
@deffn {屬性} reason

一個字串符號，用來指定發生錯誤的原因，如：@code{CERTIFICATE_VERIFY_FAILED}。可能值的範圍取決於 OpenSSL 的版本。


在 3.3 版被加入.

@end deffn
@end deffn

@geindex SSLZeroReturnError
@anchor{library/ssl ssl SSLZeroReturnError}@anchor{386b}
@deffn {例外} ssl.SSLZeroReturnError

一個 @ref{147a,,SSLError} 的子類別，當嘗試去讀寫已經被完全關閉的 SSL 連線時會被引發。請注意，這並不表示底層傳輸（例如 TCP）已經被關閉。


在 3.3 版被加入.

@end deffn

@geindex SSLWantReadError
@anchor{library/ssl ssl SSLWantReadError}@anchor{1064}
@deffn {例外} ssl.SSLWantReadError

一個 @ref{147a,,SSLError} 的子類別，當嘗試去讀寫資料前，底層 TCP 傳輸需要先接收更多資料時會由@ref{386c,,非阻塞的 SSL socket} 引發該錯誤。


在 3.3 版被加入.

@end deffn

@geindex SSLWantWriteError
@anchor{library/ssl ssl SSLWantWriteError}@anchor{1065}
@deffn {例外} ssl.SSLWantWriteError

一個 @ref{147a,,SSLError} 的子類別，當嘗試去讀寫資料前，底層 TCP 傳輸需要先發送更多資料時會由@ref{386c,,非阻塞的 SSL socket} 引發該錯誤。


在 3.3 版被加入.

@end deffn

@geindex SSLSyscallError
@anchor{library/ssl ssl SSLSyscallError}@anchor{386d}
@deffn {例外} ssl.SSLSyscallError

一個 @ref{147a,,SSLError} 的子類別，當嘗試去操作 SSL socket 時有系統錯誤產生會引發此錯誤。不幸的是，目前沒有任何簡單的方法可以去檢查原本的的 errno 編號。


在 3.3 版被加入.

@end deffn

@geindex SSLEOFError
@anchor{library/ssl ssl SSLEOFError}@anchor{1a03}
@deffn {例外} ssl.SSLEOFError

一個 @ref{147a,,SSLError} 的子類別，當 SSL 連線被突然終止時會引發此錯誤。通常，當此錯誤發生時，你不該再去重新使用底層傳輸。


在 3.3 版被加入.

@end deffn

@geindex SSLCertVerificationError
@anchor{library/ssl ssl SSLCertVerificationError}@anchor{d6d}
@deffn {例外} ssl.SSLCertVerificationError

當憑證驗證失敗時會引發的一個 @ref{147a,,SSLError} 子類別。


在 3.7 版被加入.


@geindex verify_code (ssl.SSLCertVerificationError 的屬性)
@anchor{library/ssl ssl SSLCertVerificationError verify_code}@anchor{386e}
@deffn {屬性} verify_code

一個表示驗證錯誤的錯誤數值編號。
@end deffn

@geindex verify_message (ssl.SSLCertVerificationError 的屬性)
@anchor{library/ssl ssl SSLCertVerificationError verify_message}@anchor{386f}
@deffn {屬性} verify_message

一個人類可讀的驗證錯誤字串。
@end deffn
@end deffn

@geindex CertificateError
@anchor{library/ssl ssl CertificateError}@anchor{3870}
@deffn {例外} ssl.CertificateError

@ref{d6d,,SSLCertVerificationError} 的別名。


在 3.7 版的變更: 此例外現在是 @ref{d6d,,SSLCertVerificationError} 的別名。

@end deffn

@node 隨機產生,認證處理,例外<17>,函式、常數與例外
@anchor{library/ssl random-generation}@anchor{3871}
@subsubsection 隨機產生


@geindex RAND_bytes() (於 ssl 模組中)
@anchor{library/ssl ssl RAND_bytes}@anchor{740}
@deffn {函式} ssl.RAND_bytes (num, /)

回傳 `num' 個加密性強的偽隨機位元組。如果 PRNG 未使用足夠的資料做為隨機種子 (seed) 或是目前的 RAND 方法不支持該操作則會導致 @ref{147a,,SSLError} 錯誤。@ref{1b7c,,RAND_status()} 函式可以用來檢查 PRNG 函式，而 @ref{3872,,RAND_add()} 則可以用來為 PRNG 設定隨機種子。

在幾乎所有的應用程式中，@ref{73f,,os.urandom()} 會是較好的選擇。

請閱讀維基百科的密碼學安全偽隨機數產生器 (CSPRNG)@footnote{https://en.wikipedia.org/wiki/Cryptographically_secure_pseudorandom_number_generator}文章來了解密碼學安全偽隨機數產生器的需求。


在 3.3 版被加入.

@end deffn

@geindex RAND_status() (於 ssl 模組中)
@anchor{library/ssl ssl RAND_status}@anchor{1b7c}
@deffn {函式} ssl.RAND_status ()

如果 SSL 偽隨機數產生器已經使用「足夠的」隨機性進行隨機種子生成，則回傳 @code{True} ，否則回傳 @code{False}。你可以使用 @code{ssl.RAND_egd()} 函式和 @ref{3872,,ssl.RAND_add()} 函式來增加偽隨機數產生器的隨機性。
@end deffn

@geindex RAND_add() (於 ssl 模組中)
@anchor{library/ssl ssl RAND_add}@anchor{3872}
@deffn {函式} ssl.RAND_add (bytes, entropy, /)

將給定的 `bytes' 混進 SSL 隨機偽隨機數產生器中。 `entropy' 參數（float 值）是指字串中包含熵值的下限（因此你可以將其設為 @code{0.0}）。請參閱 
@geindex RFC; RFC 1750
RFC 1750@footnote{https://datatracker.ietf.org/doc/html/rfc1750.html} 了解有關熵源的更多資訊。


在 3.5 版的變更: 可寫入的@ref{193,,類位元組物件}現在可被接受。

@end deffn

@node 認證處理,常數<8>,隨機產生,函式、常數與例外
@anchor{library/ssl certificate-handling}@anchor{3873}
@subsubsection 認證處理


@c import ssl

@geindex cert_time_to_seconds() (於 ssl 模組中)
@anchor{library/ssl ssl cert_time_to_seconds}@anchor{1066}
@deffn {函式} ssl.cert_time_to_seconds (cert_time)

回傳自紀元以來的秒數，給定的 @code{cert_time} 字串表示憑證的 "notBefore" 或 "notAfter" 日期，字串採用 @code{"%b %d %H:%M:%S %Y %Z"} 格式（C 語言區域設定）。

以下是一個範例：

@example
>>> import ssl
>>> timestamp = ssl.cert_time_to_seconds("Jan  5 09:34:43 2018 GMT")
>>> timestamp
1515144883
>>> from datetime import datetime
>>> print(datetime.utcfromtimestamp(timestamp))
2018-01-05 09:34:43
@end example

"notBefore" 或 "notAfter" 日期必須使用 GMT (
@geindex RFC; RFC 5280
RFC 5280@footnote{https://datatracker.ietf.org/doc/html/rfc5280.html})。


在 3.5 版的變更: 將輸入的時間直譯為 UTC 時間，如輸入字串中指定的 'GMT' 時區。在之前是使用本地的時區。回傳一個整數（在輸入格式中不包括秒的小數部分）。

@end deffn

@geindex get_server_certificate() (於 ssl 模組中)
@anchor{library/ssl ssl get_server_certificate}@anchor{a36}
@deffn {函式} ssl.get_server_certificate (addr, ssl_version=PROTOCOL_TLS_CLIENT, ca_certs=None[, timeout])

輸入使用 SSL 保護的伺服器的地址 @code{addr}，輸入形式為一個 pair (`hostname', `port-number')，取得該伺服器的憑證，並以 PEM 編碼字串的形式回傳。如果指定了 @code{ssl_version}，則使用指定的 SSL 協定來嘗試與伺服器連線。如果指定 `ca_certs'，則它應該是一個包含根憑證列表的檔案，並與 @ref{10e9,,SSLContext.load_verify_locations()} 中的參數 `cafile' 所使用的格式相同。此呼叫將嘗試使用該組根憑證對伺服器憑證進行驗證，如果驗證失敗，呼叫將失敗。可以使用 @code{timeout} 參數指定超時時間。


在 3.3 版的變更: 此函式現在是與 IPv6 相容的。



在 3.5 版的變更: 預設的 `ssl_version' 已經從 @ref{3874,,PROTOCOL_SSLv3} 改為 @ref{3869,,PROTOCOL_TLS}，已確保與現今的伺服器有最大的相容性。



在 3.10 版的變更: 新增 `timeout' 參數。

@end deffn

@geindex DER_cert_to_PEM_cert() (於 ssl 模組中)
@anchor{library/ssl ssl DER_cert_to_PEM_cert}@anchor{3875}
@deffn {函式} ssl.DER_cert_to_PEM_cert (der_cert_bytes)

給定一個以 DER 編碼的位元組 blob 作為憑證，回傳以 PEM 編碼字串版本的相同憑證。
@end deffn

@geindex PEM_cert_to_DER_cert() (於 ssl 模組中)
@anchor{library/ssl ssl PEM_cert_to_DER_cert}@anchor{3876}
@deffn {函式} ssl.PEM_cert_to_DER_cert (pem_cert_string)

給定一個以 ASCII PEM 的字串作為憑證，回傳以 DER 編碼的位元組序列的相同憑證。
@end deffn

@geindex get_default_verify_paths() (於 ssl 模組中)
@anchor{library/ssl ssl get_default_verify_paths}@anchor{11a5}
@deffn {函式} ssl.get_default_verify_paths ()

回傳一個具有 OpenSSL 的預設 cafile 和 capath 路徑的附名元組。這些路徑與 @ref{11a6,,SSLContext.set_default_verify_paths()} 使用的相同。回傳值是一個 @ref{857,,named tuple} @code{DefaultVerifyPaths}：


@itemize *

@item 
@code{cafile} - 解析後的 cafile 路徑，如果檔案不存在則為 @code{None}，

@item 
@code{capath} - 解析後的 capath 路徑，如果目錄不存在則為 @code{None}，

@item 
@code{openssl_cafile_env} - 指向 cafile 的 OpenSSL 環境密鑰，

@item 
@code{openssl_cafile} - hard coded 的 cafile 路徑，

@item 
@code{openssl_capath_env} - 指向 capath 的 OpenSSL 環境密鑰，

@item 
@code{openssl_capath} - hard coded 的 capath 目錄路徑
@end itemize


在 3.4 版被加入.

@end deffn

@geindex enum_certificates() (於 ssl 模組中)
@anchor{library/ssl ssl enum_certificates}@anchor{11b0}
@deffn {函式} ssl.enum_certificates (store_name)

從 Windows 的系統憑證儲存庫中搜尋憑證。`store_name' 可以是 @code{CA}、@code{ROOT} 或 @code{MY} 的其中一個。Windows 也可能會提供額外的憑證儲存庫。

此函式會回傳一個元組 (cert_bytes, encoding_type, trust) 串列。encoding_type 指定了 cert_bytes 的編碼格式。它可以是用來表示 X.509 ASN.1 資料的 @code{x509_asn} 或是用來表示 PKCS#7 ASN.1 資料的 @code{pkcs_7_asn}。Trust 通過一組 OIDS 來指定憑證的用途，或是如果憑證對所有用途都可以使用則回傳 @code{True}。

範例：

@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{2006,,可用性}: Windows.


在 3.4 版被加入.

@end deffn

@geindex enum_crls() (於 ssl 模組中)
@anchor{library/ssl ssl enum_crls}@anchor{11b1}
@deffn {函式} ssl.enum_crls (store_name)

從 Windows 的系統憑證儲存庫中搜尋 CRLs。`store_name' 可以是 @code{CA}、@code{ROOT} 或 @code{MY} 的其中一個。Windows 也可能會提供額外的憑證儲存庫。

此函式會回傳一個元組 (cert_bytes, encoding_type, trust) 串列。encoding_type 指定了 cert_bytes 的編碼格式。它可以是用來表示 X.509 ASN.1 資料的 @code{x509_asn} 或是用來表示 PKCS#7 ASN.1 資料的 @code{pkcs_7_asn}。

@ref{2006,,可用性}: Windows.


在 3.4 版被加入.

@end deffn

@node 常數<8>,,認證處理,函式、常數與例外
@anchor{library/ssl constants}@anchor{3877}
@subsubsection 常數


@quotation

所有的常數現在都是 @ref{ed6,,enum.IntEnum} 或 @ref{e95,,enum.IntFlag} 的集合。


在 3.6 版被加入.

@end quotation

@geindex CERT_NONE (於 ssl 模組中)
@anchor{library/ssl ssl CERT_NONE}@anchor{3878}
@deffn {資料} ssl.CERT_NONE

@ref{3866,,SSLContext.verify_mode} 可能的值。除了 @ref{3866,,SSLContext.verify_mode} 外，這是預設的模式。對於用戶端的 sockets，幾乎任何憑證都能被允許。驗證錯誤，像是不被信任或是過期的憑證，會被忽略並不會中止 TLS/SSL 握手。

在伺服器模式下，不會從用戶端請求任何憑證，所以用戶端不用發送任何用於用戶端憑證身分驗證的憑證。

參閱下方 @ref{374a,,Security considerations} 的討論。
@end deffn

@geindex CERT_OPTIONAL (於 ssl 模組中)
@anchor{library/ssl ssl CERT_OPTIONAL}@anchor{3879}
@deffn {資料} ssl.CERT_OPTIONAL

@ref{3866,,SSLContext.verify_mode} 可能的值。在用戶端模式下，@ref{3879,,CERT_OPTIONAL} 具有與 @ref{3867,,CERT_REQUIRED} 相同的含意。對於客戶端 sockets 推薦改用  @ref{3867,,CERT_REQUIRED}。

在伺服器模式下，客戶憑證請求會被發送給用戶端。用戶端可以選擇忽略請求或是選擇發送憑證來執行 TLS 用戶端憑證身分驗證。如果用戶端選擇發送憑證，則會對其進行驗證。任何驗證錯誤都會立刻終止 TLS 握手。

使用此設定需要將一組有效的 CA 憑證傳送給 @ref{10e9,,SSLContext.load_verify_locations()}。
@end deffn

@geindex CERT_REQUIRED (於 ssl 模組中)
@anchor{library/ssl ssl CERT_REQUIRED}@anchor{3867}
@deffn {資料} ssl.CERT_REQUIRED

@ref{3866,,SSLContext.verify_mode} 可能的值。在這個模式下，需要從 socket 連線的另一端取得憑證；如果未提供憑證或是驗證失敗，則將會導致 @ref{147a,,SSLError}。此模式`不能'在用戶端模式下對憑證進行驗證，因為它無法去配對主機名稱。@ref{387a,,check_hostname} 也必須被開起來來驗證憑證的真實性。@ref{a69,,PROTOCOL_TLS_CLIENT} 會使用  @ref{3867,,CERT_REQUIRED} 並預設開啟 @ref{387a,,check_hostname}。

對於 socket 伺服器，此模式會提供強制的 TLS 用戶端憑證驗證。用戶端憑證請求會被發送給用戶端並且用戶端必須提供有效且被信任的憑證。

使用此設定需要將一組有效的 CA 憑證傳送給 @ref{10e9,,SSLContext.load_verify_locations()}。
@end deffn

@geindex VerifyMode (ssl 中的類別)
@anchor{library/ssl ssl VerifyMode}@anchor{387b}
@deffn {類別} ssl.VerifyMode

@ref{ed6,,enum.IntEnum} 為 CERT_* 常數的一個集合。


在 3.6 版被加入.

@end deffn

@geindex VERIFY_DEFAULT (於 ssl 模組中)
@anchor{library/ssl ssl VERIFY_DEFAULT}@anchor{11aa}
@deffn {資料} ssl.VERIFY_DEFAULT

@ref{11a9,,SSLContext.verify_flags} 可能的值。在此模式下，不會檢查憑證吊銷列表 (CRLs)。預設的 OpenSSL 並不會請求及驗證 CRLs。


在 3.4 版被加入.

@end deffn

@geindex VERIFY_CRL_CHECK_LEAF (於 ssl 模組中)
@anchor{library/ssl ssl VERIFY_CRL_CHECK_LEAF}@anchor{11ab}
@deffn {資料} ssl.VERIFY_CRL_CHECK_LEAF

@ref{11a9,,SSLContext.verify_flags} 可能的值。在此模式下，只會檢查同等的憑證而不會去檢查中間的 CA 憑證。此模式需要提供由對等憑證發行者 (它的直接上級 CA) 的有效的 CRL 簽名。如果沒有用 @ref{10e9,,SSLContext.load_verify_locations} 載入適當的 CRL，則會驗證失敗。


在 3.4 版被加入.

@end deffn

@geindex VERIFY_CRL_CHECK_CHAIN (於 ssl 模組中)
@anchor{library/ssl ssl VERIFY_CRL_CHECK_CHAIN}@anchor{11ac}
@deffn {資料} ssl.VERIFY_CRL_CHECK_CHAIN

@ref{11a9,,SSLContext.verify_flags} 可能的值。在此模式下，會檢查對等憑證鍊中所有憑證的 CRLs。


在 3.4 版被加入.

@end deffn

@geindex VERIFY_X509_STRICT (於 ssl 模組中)
@anchor{library/ssl ssl VERIFY_X509_STRICT}@anchor{47c}
@deffn {資料} ssl.VERIFY_X509_STRICT

@ref{11a9,,SSLContext.verify_flags} 可能的值，用來禁用已損壞的 X.509 憑證的解決方法。


在 3.4 版被加入.

@end deffn

@geindex VERIFY_ALLOW_PROXY_CERTS (於 ssl 模組中)
@anchor{library/ssl ssl VERIFY_ALLOW_PROXY_CERTS}@anchor{1b91}
@deffn {資料} ssl.VERIFY_ALLOW_PROXY_CERTS

@ref{11a9,,SSLContext.verify_flags} 可能的值，用來啟用憑證代理驗證。


在 3.10 版被加入.

@end deffn

@geindex VERIFY_X509_TRUSTED_FIRST (於 ssl 模組中)
@anchor{library/ssl ssl VERIFY_X509_TRUSTED_FIRST}@anchor{387c}
@deffn {資料} ssl.VERIFY_X509_TRUSTED_FIRST

@ref{11a9,,SSLContext.verify_flags} 可能的值。它指示 OpenSSL 在構建信任鍊來驗證憑證時會優先使用被信任的憑證。此旗標預設開啟。


在 3.4.4 版被加入.

@end deffn

@geindex VERIFY_X509_PARTIAL_CHAIN (於 ssl 模組中)
@anchor{library/ssl ssl VERIFY_X509_PARTIAL_CHAIN}@anchor{47b}
@deffn {資料} ssl.VERIFY_X509_PARTIAL_CHAIN

@ref{11a9,,SSLContext.verify_flags} 可能的值。它指示 OpenSSL 接受信任儲存中的中間 CAs 作為信任錨，就像自簽名的根 CA 憑證。這樣就能去信任中間 CA 所頒發的憑證，而不一定非要去信任其祖先的根 CA。


在 3.10 版被加入.

@end deffn

@geindex VerifyFlags (ssl 中的類別)
@anchor{library/ssl ssl VerifyFlags}@anchor{387d}
@deffn {類別} ssl.VerifyFlags

@ref{e95,,enum.IntFlag} 為 VERIFY_* 常數的其中一個集合。


在 3.6 版被加入.

@end deffn

@geindex PROTOCOL_TLS (於 ssl 模組中)
@anchor{library/ssl ssl PROTOCOL_TLS}@anchor{3869}
@deffn {資料} ssl.PROTOCOL_TLS

選擇用戶端及伺服器均可以支援最高協定版本。儘管名稱只有 「TLS」，但實際上「SSL」和「TLS」均可以選擇。


在 3.6 版被加入.



在 3.10 版之後被棄用: TLS 的用戶端及伺服器端需要不同的預設值來實現安全通訊。通用的 TLS 協定常數已被廢除，並改用 @ref{a69,,PROTOCOL_TLS_CLIENT} 和 @ref{a6a,,PROTOCOL_TLS_SERVER}。

@end deffn

@geindex PROTOCOL_TLS_CLIENT (於 ssl 模組中)
@anchor{library/ssl ssl PROTOCOL_TLS_CLIENT}@anchor{a69}
@deffn {資料} ssl.PROTOCOL_TLS_CLIENT

自動協商用戶端和伺服器服務器都支援的最高協定版本，並配置用戶端語境連線。該協定預設啟用 @ref{3867,,CERT_REQUIRED} 和 @ref{387a,,check_hostname}。


在 3.6 版被加入.

@end deffn

@geindex PROTOCOL_TLS_SERVER (於 ssl 模組中)
@anchor{library/ssl ssl PROTOCOL_TLS_SERVER}@anchor{a6a}
@deffn {資料} ssl.PROTOCOL_TLS_SERVER

自動協商用戶端和伺服器都支援的最高協定版本，並配置用戶端語境連線。


在 3.6 版被加入.

@end deffn

@geindex PROTOCOL_SSLv23 (於 ssl 模組中)
@anchor{library/ssl ssl PROTOCOL_SSLv23}@anchor{387e}
@deffn {資料} ssl.PROTOCOL_SSLv23

@ref{3869,,PROTOCOL_TLS} 的別名。


在 3.6 版之後被棄用: 請改用 @ref{3869,,PROTOCOL_TLS}。

@end deffn

@geindex PROTOCOL_SSLv3 (於 ssl 模組中)
@anchor{library/ssl ssl PROTOCOL_SSLv3}@anchor{3874}
@deffn {資料} ssl.PROTOCOL_SSLv3

選擇第三版的 SSL 做為通道加密協定。

如果 OpenSSL 是用 @code{no-ssl3} 編譯的，則此項協定無法使用。

@cartouche
@quotation 警告 
第三版的 SSL 是不安全的，強烈建議不要使用。
@end quotation
@end cartouche


在 3.6 版之後被棄用: OpenSSL 已經終止了所有特定版本的協定。請改用預設的 @ref{a6a,,PROTOCOL_TLS_SERVER} 協定或帶有 @ref{d74,,SSLContext.minimum_version} 和 @ref{d75,,SSLContext.maximum_version} 的 @ref{a69,,PROTOCOL_TLS_CLIENT}。

@end deffn

@geindex PROTOCOL_TLSv1 (於 ssl 模組中)
@anchor{library/ssl ssl PROTOCOL_TLSv1}@anchor{387f}
@deffn {資料} ssl.PROTOCOL_TLSv1

選擇 1.0 版的 TLS 做為通道加密協定。


在 3.6 版之後被棄用: OpenSSL 已經將所有版本特定的協定棄用。

@end deffn

@geindex PROTOCOL_TLSv1_1 (於 ssl 模組中)
@anchor{library/ssl ssl PROTOCOL_TLSv1_1}@anchor{11a3}
@deffn {資料} ssl.PROTOCOL_TLSv1_1

選擇 1.1 版的 TLS 做為通道加密協定。只有在 1.0.1 版本以上的 OpenSSL 才可以選用。


在 3.4 版被加入.



在 3.6 版之後被棄用: OpenSSL 已經將所有版本特定的協定棄用。

@end deffn

@geindex PROTOCOL_TLSv1_2 (於 ssl 模組中)
@anchor{library/ssl ssl PROTOCOL_TLSv1_2}@anchor{11a4}
@deffn {資料} ssl.PROTOCOL_TLSv1_2

選擇 1.2 版的 TLS 做為通道加密協定。只有在 1.0.1 版本以上的 OpenSSL 才可以選用。


在 3.4 版被加入.



在 3.6 版之後被棄用: OpenSSL 已經將所有版本特定的協定棄用。

@end deffn

@geindex OP_ALL (於 ssl 模組中)
@anchor{library/ssl ssl OP_ALL}@anchor{3880}
@deffn {資料} ssl.OP_ALL

啟用對 SSL 實作時所產生的各種錯誤的緩解措施。此選項預設被設定。它不一定設定與 OpenSSL 的 @code{SSL_OP_ALL} 常數相同的旗標。


在 3.2 版被加入.

@end deffn

@geindex OP_NO_SSLv2 (於 ssl 模組中)
@anchor{library/ssl ssl OP_NO_SSLv2}@anchor{a33}
@deffn {資料} ssl.OP_NO_SSLv2

防止 SSLv2 連線。此選項只可以跟 @ref{3869,,PROTOCOL_TLS} 一起使用。它會防止同級 (peer)選用 SSLv2 做為協定版本。


在 3.2 版被加入.



在 3.6 版之後被棄用: SSLv2 已被棄用

@end deffn

@geindex OP_NO_SSLv3 (於 ssl 模組中)
@anchor{library/ssl ssl OP_NO_SSLv3}@anchor{a34}
@deffn {資料} ssl.OP_NO_SSLv3

防止 SSLv3 連線。此選項只可以跟 @ref{3869,,PROTOCOL_TLS} 一起使用。它會防止同級選用 SSLv3 做為協定版本。


在 3.2 版被加入.



在 3.6 版之後被棄用: SSLv3 已被棄用

@end deffn

@geindex OP_NO_TLSv1 (於 ssl 模組中)
@anchor{library/ssl ssl OP_NO_TLSv1}@anchor{3881}
@deffn {資料} ssl.OP_NO_TLSv1

防止 TLSv1 連線。此選項只可以跟 @ref{3869,,PROTOCOL_TLS} 一起使用。它會防止同級選用 TLSv1 做為協定版本。


在 3.2 版被加入.



在 3.7 版之後被棄用: 該選項自從 OpenSSL 1.1.0 以後已被棄用，請改用新的 @ref{d74,,SSLContext.minimum_version} 及 @ref{d75,,SSLContext.maximum_version} 代替。

@end deffn

@geindex OP_NO_TLSv1_1 (於 ssl 模組中)
@anchor{library/ssl ssl OP_NO_TLSv1_1}@anchor{3882}
@deffn {資料} ssl.OP_NO_TLSv1_1

防止 TLSv1.1 連線。此選項只可以跟 @ref{3869,,PROTOCOL_TLS} 一起使用。它會防止同級選用 TLSv1.1 做為協定版本。只有 1.0.1 版後的 OpenSSL 版本才能使用。


在 3.4 版被加入.



在 3.7 版之後被棄用: 此選項自 OpenSSL 1.1.0 版已被棄用。

@end deffn

@geindex OP_NO_TLSv1_2 (於 ssl 模組中)
@anchor{library/ssl ssl OP_NO_TLSv1_2}@anchor{3883}
@deffn {資料} ssl.OP_NO_TLSv1_2

防止 TLSv1.2 連線。此選項只可以跟 @ref{3869,,PROTOCOL_TLS} 一起使用。它會防止同級選用 TLSv1.2 做為協定版本。只有 1.0.1 版後的 OpenSSL 版本才能使用。


在 3.4 版被加入.



在 3.7 版之後被棄用: 此選項自 OpenSSL 1.1.0 版已被棄用。

@end deffn

@geindex OP_NO_TLSv1_3 (於 ssl 模組中)
@anchor{library/ssl ssl OP_NO_TLSv1_3}@anchor{1b5d}
@deffn {資料} ssl.OP_NO_TLSv1_3

防止 TLSv1.3 連線。此選項只可以跟 @ref{3869,,PROTOCOL_TLS} 一起使用。它會防止同級選用 TLSv1.3 做為協定版本。TSL1.3 只適用於 1.1.1 版以後的 OpenSSL。當使用 Python 編譯舊版的 OpenSSL 時，該標志預設為 `0'。


在 3.6.3 版被加入.



在 3.7 版之後被棄用: 此選項自 OpenSSL 1.1.0 以後已被棄用。它被添加到 2.7.15 和 3.6.3 中，以向後相容 OpenSSL 1.0.2。

@end deffn

@geindex OP_NO_RENEGOTIATION (於 ssl 模組中)
@anchor{library/ssl ssl OP_NO_RENEGOTIATION}@anchor{3884}
@deffn {資料} ssl.OP_NO_RENEGOTIATION

停用所有在 TLSv1.2 及更早版本的重協商 (renegotiation)。不發送 HelloRequest 訊息，並忽略通過 ClientHello 的重協商請求。

此選項僅適用於 OpenSSL 1.1.0h 及更新版本。


在 3.7 版被加入.

@end deffn

@geindex OP_CIPHER_SERVER_PREFERENCE (於 ssl 模組中)
@anchor{library/ssl ssl OP_CIPHER_SERVER_PREFERENCE}@anchor{134a}
@deffn {資料} ssl.OP_CIPHER_SERVER_PREFERENCE

使用伺服器的加密方法名稱字串排序優先順序，而不是用戶端的。此選項並不會影響到用戶端及 SSLv2 伺服器的 sockets。


在 3.3 版被加入.

@end deffn

@geindex OP_SINGLE_DH_USE (於 ssl 模組中)
@anchor{library/ssl ssl OP_SINGLE_DH_USE}@anchor{3885}
@deffn {資料} ssl.OP_SINGLE_DH_USE

防止對不同的 SSL 會談重複使用相同的 DH 密鑰。這會加強向前保密但需要更多的運算資源。此選項只適用於伺服器 sockets。


在 3.3 版被加入.

@end deffn

@geindex OP_SINGLE_ECDH_USE (於 ssl 模組中)
@anchor{library/ssl ssl OP_SINGLE_ECDH_USE}@anchor{3886}
@deffn {資料} ssl.OP_SINGLE_ECDH_USE

防止對不同的 SSL 會談重複使用相同的 ECDH 密鑰。這會加強向前保密但需要更多的運算資源。此選項只適用於伺服器 sockets。


在 3.3 版被加入.

@end deffn

@geindex OP_ENABLE_MIDDLEBOX_COMPAT (於 ssl 模組中)
@anchor{library/ssl ssl OP_ENABLE_MIDDLEBOX_COMPAT}@anchor{3887}
@deffn {資料} ssl.OP_ENABLE_MIDDLEBOX_COMPAT

在 TLS 1.3 握手中發送虛擬的變更加密方法規範 (CCS) 消息，以使 TLS 1.3 連接看起來更像 TLS 1.2 連線。

此選項僅適用於 OpenSSL 1.1.1 及更新版本。


在 3.8 版被加入.

@end deffn

@geindex OP_NO_COMPRESSION (於 ssl 模組中)
@anchor{library/ssl ssl OP_NO_COMPRESSION}@anchor{1347}
@deffn {資料} ssl.OP_NO_COMPRESSION

在 SSL 通道上禁用壓縮。如果應用程序協定支援自己的壓縮方案，這會很有用。


在 3.3 版被加入.

@end deffn

@geindex Options (ssl 中的類別)
@anchor{library/ssl ssl Options}@anchor{3888}
@deffn {類別} ssl.Options

@ref{e95,,enum.IntFlag} 為 OP_* 常數中的一個集合。
@end deffn

@geindex OP_NO_TICKET (於 ssl 模組中)
@anchor{library/ssl ssl OP_NO_TICKET}@anchor{3889}
@deffn {資料} ssl.OP_NO_TICKET

防止用戶端請求會談票據。


在 3.6 版被加入.

@end deffn

@geindex OP_IGNORE_UNEXPECTED_EOF (於 ssl 模組中)
@anchor{library/ssl ssl OP_IGNORE_UNEXPECTED_EOF}@anchor{a31}
@deffn {資料} ssl.OP_IGNORE_UNEXPECTED_EOF

忽略意外關閉的 TLS 連線。

此選項僅適用於 OpenSSL 3.0.0 及更新版本。


在 3.10 版被加入.

@end deffn

@geindex OP_ENABLE_KTLS (於 ssl 模組中)
@anchor{library/ssl ssl OP_ENABLE_KTLS}@anchor{1a53}
@deffn {資料} ssl.OP_ENABLE_KTLS

允許使用 TLS 核心。要想受益於該功能，OpenSSL 必須編譯為支援該功能，並且想使用的加密套件及擴充套件也必須被該功能支援 (該功能所支援的列表可能會因平台及核心而有所差異)。

請注意當允許使用 TLS 核心時，一些加密操作將直接由核心執行而不是經由任何由可用的 OpenSSL 所提供的程序，而這可能並非你所想使用的，例如：當應用程式要求所有的加密操作由 FIPS 提供執行。

此選項僅適用於 OpenSSL 3.0.0 及更新版本。


在 3.12 版被加入.

@end deffn

@geindex OP_LEGACY_SERVER_CONNECT (於 ssl 模組中)
@anchor{library/ssl ssl OP_LEGACY_SERVER_CONNECT}@anchor{1a38}
@deffn {資料} ssl.OP_LEGACY_SERVER_CONNECT

只允許 OpenSSL 與未修補的伺服器進行遺留 (legacy) 不安全重協商。


在 3.12 版被加入.

@end deffn

@geindex HAS_ALPN (於 ssl 模組中)
@anchor{library/ssl ssl HAS_ALPN}@anchor{1061}
@deffn {資料} ssl.HAS_ALPN

OpenSSL 函式庫是否內建支援 `應用層協定協商' TLS 擴充套件，該擴充套件描述在 
@geindex RFC; RFC 7301
RFC 7301@footnote{https://datatracker.ietf.org/doc/html/rfc7301.html} 中。


在 3.5 版被加入.

@end deffn

@geindex HAS_NEVER_CHECK_COMMON_NAME (於 ssl 模組中)
@anchor{library/ssl ssl HAS_NEVER_CHECK_COMMON_NAME}@anchor{388a}
@deffn {資料} ssl.HAS_NEVER_CHECK_COMMON_NAME

OpenSSL 函式庫是否內建支援不檢查主題通用名稱及 @ref{d6e,,SSLContext.hostname_checks_common_name} 是否可寫。


在 3.7 版被加入.

@end deffn

@geindex HAS_ECDH (於 ssl 模組中)
@anchor{library/ssl ssl HAS_ECDH}@anchor{388b}
@deffn {資料} ssl.HAS_ECDH

OpenSSL 函式庫是否內建支援基於橢圓曲線的 (Elliptic Curve-based) Diffie-Hellman 金鑰交換。此回傳值應該要為 true 除非發布者明確禁用此功能。


在 3.3 版被加入.

@end deffn

@geindex HAS_SNI (於 ssl 模組中)
@anchor{library/ssl ssl HAS_SNI}@anchor{388c}
@deffn {資料} ssl.HAS_SNI

OpenSSL 函式庫是否內建支援 `伺服器名稱提示' 擴充套件 (在 
@geindex RFC; RFC 6066
RFC 6066@footnote{https://datatracker.ietf.org/doc/html/rfc6066.html} 中定義)。


在 3.2 版被加入.

@end deffn

@geindex HAS_NPN (於 ssl 模組中)
@anchor{library/ssl ssl HAS_NPN}@anchor{388d}
@deffn {資料} ssl.HAS_NPN

OpenSSL 函式庫是否內建支援 `下一代協定協商' 該功能在應用層協定協商@footnote{https://en.wikipedia.org/wiki/Application-Layer_Protocol_Negotiation} 中有描述。當此值為 true 時，你可以使用 @ref{356,,SSLContext.set_npn_protocols()} 方法來公告你想支援的協定。


在 3.3 版被加入.

@end deffn

@geindex HAS_SSLv2 (於 ssl 模組中)
@anchor{library/ssl ssl HAS_SSLv2}@anchor{388e}
@deffn {資料} ssl.HAS_SSLv2

此 OpenSSL 函式庫是否內建支援 SSL 2.0 協定。


在 3.7 版被加入.

@end deffn

@geindex HAS_SSLv3 (於 ssl 模組中)
@anchor{library/ssl ssl HAS_SSLv3}@anchor{388f}
@deffn {資料} ssl.HAS_SSLv3

此 OpenSSL 函式庫是否內建支援 SSL 3.0 協定。


在 3.7 版被加入.

@end deffn

@geindex HAS_TLSv1 (於 ssl 模組中)
@anchor{library/ssl ssl HAS_TLSv1}@anchor{3890}
@deffn {資料} ssl.HAS_TLSv1

此 OpenSSL 函式庫是否內建支援 TLS 1.0 協定。


在 3.7 版被加入.

@end deffn

@geindex HAS_TLSv1_1 (於 ssl 模組中)
@anchor{library/ssl ssl HAS_TLSv1_1}@anchor{d76}
@deffn {資料} ssl.HAS_TLSv1_1

此 OpenSSL 函式庫是否內建支援 TLS 1.1 協定。


在 3.7 版被加入.

@end deffn

@geindex HAS_TLSv1_2 (於 ssl 模組中)
@anchor{library/ssl ssl HAS_TLSv1_2}@anchor{3891}
@deffn {資料} ssl.HAS_TLSv1_2

此 OpenSSL 函式庫是否內建支援 TLS 1.2 協定。


在 3.7 版被加入.

@end deffn

@geindex HAS_TLSv1_3 (於 ssl 模組中)
@anchor{library/ssl ssl HAS_TLSv1_3}@anchor{3892}
@deffn {資料} ssl.HAS_TLSv1_3

此 OpenSSL 函式庫是否內建支援 TLS 1.3 協定。


在 3.7 版被加入.

@end deffn

@geindex HAS_PSK (於 ssl 模組中)
@anchor{library/ssl ssl HAS_PSK}@anchor{3893}
@deffn {資料} ssl.HAS_PSK

此 OpenSSL 函式庫是否內建支援 TLS-PSK。


在 3.13 版被加入.

@end deffn

@geindex HAS_PHA (於 ssl 模組中)
@anchor{library/ssl ssl HAS_PHA}@anchor{286}
@deffn {資料} ssl.HAS_PHA

此 OpenSSL 函式庫是否內建支援 TLS-PHA。


在 3.14 版被加入.

@end deffn

@geindex CHANNEL_BINDING_TYPES (於 ssl 模組中)
@anchor{library/ssl ssl CHANNEL_BINDING_TYPES}@anchor{3894}
@deffn {資料} ssl.CHANNEL_BINDING_TYPES

支援的 TLS 通道綁定類型列表。列表中的字串可以作為 @ref{1345,,SSLSocket.get_channel_binding()} 的參數。


在 3.3 版被加入.

@end deffn

@geindex OPENSSL_VERSION (於 ssl 模組中)
@anchor{library/ssl ssl OPENSSL_VERSION}@anchor{141f}
@deffn {資料} ssl.OPENSSL_VERSION

直譯器所加載的 OpenSSL 函式庫的版本字串:

@example
>>> ssl.OPENSSL_VERSION
'OpenSSL 1.0.2k  26 Jan 2017'
@end example


在 3.2 版被加入.

@end deffn

@geindex OPENSSL_VERSION_INFO (於 ssl 模組中)
@anchor{library/ssl ssl OPENSSL_VERSION_INFO}@anchor{1420}
@deffn {資料} ssl.OPENSSL_VERSION_INFO

代表 OpenSSL 函式庫版本資訊的五個整數的元組：

@example
>>> ssl.OPENSSL_VERSION_INFO
(1, 0, 2, 11, 15)
@end example


在 3.2 版被加入.

@end deffn

@geindex OPENSSL_VERSION_NUMBER (於 ssl 模組中)
@anchor{library/ssl ssl OPENSSL_VERSION_NUMBER}@anchor{1421}
@deffn {資料} ssl.OPENSSL_VERSION_NUMBER

OpenSSL 函式庫的初始版本，以單一整數表示:

@example
>>> ssl.OPENSSL_VERSION_NUMBER
268443839
>>> hex(ssl.OPENSSL_VERSION_NUMBER)
'0x100020bf'
@end example


在 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{3895}
@deffn {資料} ssl.ALERT_DESCRIPTION_HANDSHAKE_FAILURE
@anchor{library/ssl ssl ALERT_DESCRIPTION_INTERNAL_ERROR}@anchor{3896}
@deffnx {資料} ssl.ALERT_DESCRIPTION_INTERNAL_ERROR

@deffnx {資料} ALERT_DESCRIPTION_*

來自 
@geindex RFC; RFC 5246
RFC 5246@footnote{https://datatracker.ietf.org/doc/html/rfc5246.html} 和其他文件的警報描述。IANA TLS Alert Registry@footnote{https://www.iana.org/assignments/tls-parameters/tls-parameters.xml#tls-parameters-6} 包含了此列表以及其含義定義所在的 RFC 的引用。

被用來做為 @ref{11b2,,SSLContext.set_servername_callback()} 中回呼函式的回傳值。


在 3.4 版被加入.

@end deffn

@geindex AlertDescription (ssl 中的類別)
@anchor{library/ssl ssl AlertDescription}@anchor{3897}
@deffn {類別} ssl.AlertDescription

@ref{ed6,,enum.IntEnum} 為 ALERT_DESCRIPTION_* 常數中的一個集合。


在 3.6 版被加入.

@end deffn

@geindex Purpose.SERVER_AUTH (於 ssl 模組中)
@anchor{library/ssl ssl Purpose SERVER_AUTH}@anchor{11ae}
@deffn {資料} Purpose.SERVER_AUTH

@ref{47a,,create_default_context()} 和 @ref{11ad,,SSLContext.load_default_certs()} 的選項。此值表示該語境可能會用於驗證網頁伺服器 (因此它將用於建立用戶端 socket）。


在 3.4 版被加入.

@end deffn

@geindex Purpose.CLIENT_AUTH (於 ssl 模組中)
@anchor{library/ssl ssl Purpose CLIENT_AUTH}@anchor{11af}
@deffn {資料} Purpose.CLIENT_AUTH

@ref{47a,,create_default_context()} 和 @ref{11ad,,SSLContext.load_default_certs()} 的選項。此值表示該語境可能會用於驗證網頁用戶端 (因此，它將用於建立伺服器端的 socket）。


在 3.4 版被加入.

@end deffn

@geindex SSLErrorNumber (ssl 中的類別)
@anchor{library/ssl ssl SSLErrorNumber}@anchor{3898}
@deffn {類別} ssl.SSLErrorNumber

@ref{ed6,,enum.IntEnum} 為 SSL_ERROR_* 常數中的一個集合。


在 3.6 版被加入.

@end deffn

@geindex TLSVersion (ssl 中的類別)
@anchor{library/ssl ssl TLSVersion}@anchor{3899}
@deffn {類別} ssl.TLSVersion

用於 @ref{d75,,SSLContext.maximum_version} 和 @ref{d74,,SSLContext.minimum_version} 的 SSL 和 TLS 版本 @ref{ed6,,enum.IntEnum} 集合。


在 3.7 版被加入.

@end deffn

@geindex MINIMUM_SUPPORTED (ssl.TLSVersion 的屬性)
@anchor{library/ssl ssl TLSVersion MINIMUM_SUPPORTED}@anchor{389a}
@deffn {屬性} TLSVersion.MINIMUM_SUPPORTED
@end deffn

@geindex MAXIMUM_SUPPORTED (ssl.TLSVersion 的屬性)
@anchor{library/ssl ssl TLSVersion MAXIMUM_SUPPORTED}@anchor{389b}
@deffn {屬性} TLSVersion.MAXIMUM_SUPPORTED

最低或最高支援的 SSL 或 TLS 版本。這些是特殊常數。它們的值並不反映可用的最低和最高 TLS/SSL 版本。
@end deffn

@geindex SSLv3 (ssl.TLSVersion 的屬性)
@anchor{library/ssl ssl TLSVersion SSLv3}@anchor{389c}
@deffn {屬性} TLSVersion.SSLv3
@end deffn

@geindex TLSv1 (ssl.TLSVersion 的屬性)
@anchor{library/ssl ssl TLSVersion TLSv1}@anchor{389d}
@deffn {屬性} TLSVersion.TLSv1
@end deffn

@geindex TLSv1_1 (ssl.TLSVersion 的屬性)
@anchor{library/ssl ssl TLSVersion TLSv1_1}@anchor{389e}
@deffn {屬性} TLSVersion.TLSv1_1
@end deffn

@geindex TLSv1_2 (ssl.TLSVersion 的屬性)
@anchor{library/ssl ssl TLSVersion TLSv1_2}@anchor{389f}
@deffn {屬性} TLSVersion.TLSv1_2
@end deffn

@geindex TLSv1_3 (ssl.TLSVersion 的屬性)
@anchor{library/ssl ssl TLSVersion TLSv1_3}@anchor{38a0}
@deffn {屬性} TLSVersion.TLSv1_3

SSL 3.0 到 TLS 1.3。


在 3.10 版之後被棄用: 除了 @ref{389f,,TLSVersion.TLSv1_2} 和 @ref{38a0,,TLSVersion.TLSv1_3} 之外，所有的 @ref{3899,,TLSVersion} 成員都已被棄用。

@end deffn

@node SSL Sockets,SSL Contexts,函式、常數與例外,ssl --- socket 物件的 TLS/SSL 包裝器
@anchor{library/ssl ssl-sockets}@anchor{38a1}
@subsubsection SSL Sockets


@geindex SSLSocket (ssl 中的類別)
@anchor{library/ssl ssl SSLSocket}@anchor{ade}
@deffn {類別} ssl.SSLSocket (socket.socket)

SSL sockets 提供以下 @ref{3847,,Socket 物件} 方法：


@itemize -

@item 
@ref{f9d,,accept()}

@item 
@ref{172e,,bind()}

@item 
@ref{f3a,,close()}

@item 
@ref{f9e,,connect()}

@item 
@ref{141d,,detach()}

@item 
@ref{3855,,fileno()}

@item 
@ref{378e,,getpeername()}、@ref{284,,getsockname()}

@item 
@ref{ecb,,getsockopt()}、@ref{ecc,,setsockopt()}

@item 
@ref{3856,,gettimeout()}、@ref{3807,,settimeout()}、@ref{2eee,,setblocking()}

@item 
@ref{1059,,listen()}

@item 
@ref{13a0,,makefile()}

@item 
@ref{f9f,,recv()}、@ref{151e,,recv_into()} （但不允許傳遞非零的 @code{flags} 引數）

@item 
@ref{fa2,,send()}、@ref{fa3,,sendall()} （同樣不允許傳遞非零的 @code{flags} 引數）

@item 
@ref{1058,,sendfile()} （但 @ref{cfd,,os.sendfile} 只能用於純文本 sockets，其餘則會使用 @ref{fa2,,send()}）

@item 
@ref{3844,,shutdown()}
@end itemize

然而，由於 SSL（和 TLS）協定在 TCP 之上有自己的框架，因此在某些方面，SSL sockets 的抽象可能會與普通作業系統級別的 sockets 規範有所不同。特別是請參閱@ref{386c,,關於 non-blocking sockets 的說明}。

@ref{ade,,SSLSocket} 的實例必須使用 @ref{741,,SSLContext.wrap_socket()} 方法建立。


在 3.5 版的變更: 新增 @code{sendfile()} 方法。



在 3.5 版的變更: @code{shutdown()} 不會在每次接收或發送位元組時重置 socket 超時時間。現在，socket 超時時間是關閉操作的最大總持續時間。



在 3.6 版之後被棄用: 直接建立 @ref{ade,,SSLSocket} 實例的方式已被棄用，請使用 @ref{741,,SSLContext.wrap_socket()} 來包裝 socket。



在 3.7 版的變更: @ref{ade,,SSLSocket} 實例必須使用 @ref{741,,wrap_socket()} 建立。在較早的版本中可以直接建立實例，但這從未被記錄或正式支援。



在 3.10 版的變更: Python 現在內部使用了 @code{SSL_read_ex} 和 @code{SSL_write_ex} 函式。這些函式支援讀取和寫入大於 2 GB 的資料。寫入零長度的資料不再會導致協定違規錯誤。

@end deffn

SSL sockets 還具有以下附加方法和屬性：

@geindex read() (ssl.SSLSocket 的方法)
@anchor{library/ssl ssl SSLSocket read}@anchor{1069}
@deffn {方法} SSLSocket.read (len=1024, buffer=None)

從 SSL socket 讀取 `len' 位元組的資料，並將結果以 @code{bytes} 實例的形式回傳。如果指定了 `buffer'，則將資料讀入緩衝區，並回傳讀取的位元組。

如果 socket 是@ref{386c,,非阻塞的}則會引發 @ref{1064,,SSLWantReadError} 或 @ref{1065,,SSLWantWriteError} 並且讀取操作將會被阻塞。

由於在任何時刻都可能發生重新協商，呼叫 @ref{1069,,read()} 也可能觸發寫入操作。


在 3.5 版的變更: 當接收或發送位元組時，socket 的超時時間將不再重置。現在，socket 超時時間是讀取最多 `len' 位元組的總最大持續時間。



在 3.6 版之後被棄用: 請改用 @code{recv()} 來替換掉 @ref{1069,,read()}。

@end deffn

@geindex write() (ssl.SSLSocket 的方法)
@anchor{library/ssl ssl SSLSocket write}@anchor{106a}
@deffn {方法} SSLSocket.write (data)

將 `data' 寫入 SSL socket 並回傳寫入的位元組數量。`data' 引數必須是支援緩衝區介面的物件。

如果 socket 是@ref{386c,,非阻塞的}則會引發 @ref{1064,,SSLWantReadError} 或 @ref{1065,,SSLWantWriteError} 並且寫入操作將會被阻塞。

由於在任何時刻都可能發生重新協商，呼叫 @ref{106a,,write()} 也可能觸發讀取操作。


在 3.5 版的變更: 當接收或發送位元組時，socket 的超時時間將不再重置。現在，socket 超時時間是寫入 `data' 的總最大持續時間。



在 3.6 版之後被棄用: 請改用 @code{send()} 來替換掉 @ref{106a,,write()}。

@end deffn

@cartouche
@quotation 備註 
@ref{1069,,read()} 和 @ref{106a,,write()} 方法為低階層的方法，負責讀取和寫入未加密的應用層資料，並將其加密/解密為加密的寫入層資料。這些方法需要一個已建立的 SSL 連接，即握手已完成，且未呼叫 @ref{38a2,,SSLSocket.unwrap()}。

通常你應該使用像 @ref{f9f,,recv()} 和 @ref{fa2,,send()} 這樣的 socket API 方法，而不是直接使用這些方法。
@end quotation
@end cartouche

@geindex do_handshake() (ssl.SSLSocket 的方法)
@anchor{library/ssl ssl SSLSocket do_handshake}@anchor{1068}
@deffn {方法} SSLSocket.do_handshake (block=False)

執行 SSL 設定握手。

If `block' is true and the timeout obtained by @ref{3856,,gettimeout()}
is zero, the socket is set in blocking mode until the handshake is performed.


在 3.4 版的變更: 當 socket 的 @ref{38a3,,context} 的 @ref{387a,,check_hostname} 屬性質為 true 時，握手方法也會執行 @code{match_hostname()}。



在 3.5 版的變更: Socket 超時時間已經不會在每次接收或傳送位元組時重置。現在，超時時間是握手過程的最大總持續時間。



在 3.7 版的變更: 在握手過程中，OpenSSL 會去配對主機名稱或 IP 地址。已不再使用 @code{match_hostname()} 函式。如果 OpenSSL 拒絕某個主機名稱或 IP 地址，握手將會提前中止，並向對方發送 TLS 警報訊息。

@end deffn

@geindex getpeercert() (ssl.SSLSocket 的方法)
@anchor{library/ssl ssl SSLSocket getpeercert}@anchor{11b3}
@deffn {方法} SSLSocket.getpeercert (binary_form=False)

如果連線端沒有證書，則回傳 @code{None}。如果 SSL 握手尚未完成，則引發 @ref{2eb,,ValueError}。

如果 @code{binary_form} 參數為 @ref{d23,,False}，且從對等 (peer) 接收到證書，則該方法回傳一個 @ref{183,,dict} 實例。如果證書未被驗證，則該字典為空。若證書已被驗證，則回傳的字典將包含數個鍵值，包括 @code{subject} (證書所簽發的對象) 和 @code{issuer} (簽發證書的主體)。如果證書中包含 `Subject Alternative Name' 擴充 (參考
@geindex RFC; RFC 3280
RFC 3280@footnote{https://datatracker.ietf.org/doc/html/rfc3280.html})，字典中還會有一個 @code{subjectAltName} 鍵。

@code{subject} 和 @code{issuer} 欄位欄位是包含相對識別名稱 (relative distinguished names, RDNs) 序列的元組，這些 RDN 來自證書資料結構中的相應欄位。每個 RDN 都是一組名稱與值的對。以下是現實中的範例：

@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

如果 @code{binary_form} 參數設定為 @ref{e02,,True}，且對等提供了證書，則該方法會以 DER 編碼形式 將整個證書以位元組序列形式回傳。如果對等未提供證書，則回傳 @ref{87e,,None}。對等是否提供證書取決於 SSL socket 的腳色：


@itemize *

@item 
對於用戶端 SSL socket，伺服器將永遠提供證書，無論是否需要進行驗證；

@item 
對於伺服器 SSL socket，用戶端僅在伺服器要求時才會提供證書；因此，如果你使用的是 @ref{3878,,CERT_NONE} (而非 @ref{3879,,CERT_OPTIONAL} 或 @ref{3867,,CERT_REQUIRED})，則 @ref{11b3,,getpeercert()} 會回傳 @ref{87e,,None}。
@end itemize

請見 @ref{387a,,SSLContext.check_hostname}。


在 3.2 版的變更: The returned dictionary includes additional items such as @code{issuer}
and @code{notBefore}.



在 3.4 版的變更: @ref{2eb,,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{18c3}
@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{18c4,,get_unverified_chain()}.


在 3.13 版被加入.

@end deffn

@geindex get_unverified_chain() (ssl.SSLSocket 的方法)
@anchor{library/ssl ssl SSLSocket get_unverified_chain}@anchor{18c4}
@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.


在 3.13 版被加入.

@end deffn

@geindex cipher() (ssl.SSLSocket 的方法)
@anchor{library/ssl ssl SSLSocket cipher}@anchor{378f}
@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{1067}
@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.  @ref{1067,,shared_ciphers()} returns
@code{None} if no connection has been established or the socket is a client
socket.


在 3.5 版被加入.

@end deffn

@geindex compression() (ssl.SSLSocket 的方法)
@anchor{library/ssl ssl SSLSocket compression}@anchor{1346}
@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{1347,,OP_NO_COMPRESSION} to disable SSL-level compression.


在 3.3 版被加入.

@end deffn

@geindex get_channel_binding() (ssl.SSLSocket 的方法)
@anchor{library/ssl ssl SSLSocket get_channel_binding}@anchor{1345}
@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{3894,,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{2eb,,ValueError} will be
raised if an unsupported channel binding type is requested.


在 3.3 版被加入.

@end deffn

@geindex selected_alpn_protocol() (ssl.SSLSocket 的方法)
@anchor{library/ssl ssl SSLSocket selected_alpn_protocol}@anchor{1060}
@deffn {方法} SSLSocket.selected_alpn_protocol ()

Return the protocol that was selected during the TLS handshake.  If
@ref{105f,,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.


在 3.5 版被加入.

@end deffn

@geindex selected_npn_protocol() (ssl.SSLSocket 的方法)
@anchor{library/ssl ssl SSLSocket selected_npn_protocol}@anchor{a6b}
@deffn {方法} SSLSocket.selected_npn_protocol ()

Return the higher-level protocol that was selected during the TLS/SSL
handshake. If @ref{356,,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}.


在 3.3 版被加入.



在 3.10 版之後被棄用: NPN has been superseded by ALPN

@end deffn

@geindex unwrap() (ssl.SSLSocket 的方法)
@anchor{library/ssl ssl SSLSocket unwrap}@anchor{38a2}
@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{c1e}
@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{c1d,,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{147a,,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{369,,NotImplementedError}.
@end quotation
@end cartouche


在 3.8 版被加入.

@end deffn

@geindex version() (ssl.SSLSocket 的方法)
@anchor{library/ssl ssl SSLSocket version}@anchor{1063}
@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.


在 3.5 版被加入.

@end deffn

@geindex pending() (ssl.SSLSocket 的方法)
@anchor{library/ssl ssl SSLSocket pending}@anchor{38a4}
@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{38a3}
@deffn {屬性} SSLSocket.context

The @ref{355,,SSLContext} object this SSL socket is tied to.


在 3.2 版被加入.

@end deffn

@geindex server_side (ssl.SSLSocket 的屬性)
@anchor{library/ssl ssl SSLSocket server_side}@anchor{38a5}
@deffn {屬性} SSLSocket.server_side

A boolean which is @code{True} for server-side sockets and @code{False} for
client-side sockets.


在 3.2 版被加入.

@end deffn

@geindex server_hostname (ssl.SSLSocket 的屬性)
@anchor{library/ssl ssl SSLSocket server_hostname}@anchor{d70}
@deffn {屬性} SSLSocket.server_hostname

Hostname of the server: @ref{169,,str} type, or @code{None} for server-side
socket or if the hostname was not specified in the constructor.


在 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{18a3}
@deffn {屬性} SSLSocket.session

The @ref{ed4,,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{1068,,do_handshake()} has been called to reuse a session.


在 3.6 版被加入.

@end deffn

@geindex session_reused (ssl.SSLSocket 的屬性)
@anchor{library/ssl ssl SSLSocket session_reused}@anchor{38a6}
@deffn {屬性} SSLSocket.session_reused


在 3.6 版被加入.

@end deffn

@node SSL Contexts,Certificates,SSL Sockets,ssl --- socket 物件的 TLS/SSL 包裝器
@anchor{library/ssl ssl-contexts}@anchor{38a7}
@subsubsection SSL Contexts



在 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{355}
@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{3869,,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{3869,,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{
@ref{355,,SSLContext} 預設會關閉 SSLv2 的 @ref{a33,,OP_NO_SSLv2}。
}

@tab

no

@tab

no

@tab

no

@item

`SSLv3'

@tab

no

@tab

yes

@tab

no @footnote{
@ref{355,,SSLContext} 預設會關閉 SSLv3 的 @ref{a34,,OP_NO_SSLv3}。
}

@tab

no

@tab

no

@tab

no

@item

`TLS' (`SSLv23') @footnote{
TLS 1.3 protocol will be available with @ref{3869,,PROTOCOL_TLS} in
OpenSSL >= 1.1.1. There is no dedicated PROTOCOL constant for just
TLS 1.3.
}

@tab

no @footnote{
@ref{355,,SSLContext} 預設會關閉 SSLv2 的 @ref{a33,,OP_NO_SSLv2}。
}

@tab

no @footnote{
@ref{355,,SSLContext} 預設會關閉 SSLv3 的 @ref{a34,,OP_NO_SSLv3}。
}

@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{47a,,create_default_context()} lets the @ref{d5,,ssl} module choose
security settings for a given purpose.



在 3.6 版的變更: The context is created with secure default values. The options
@ref{1347,,OP_NO_COMPRESSION}, @ref{134a,,OP_CIPHER_SERVER_PREFERENCE},
@ref{3885,,OP_SINGLE_DH_USE}, @ref{3886,,OP_SINGLE_ECDH_USE},
@ref{a33,,OP_NO_SSLv2},
and @ref{a34,,OP_NO_SSLv3} (except for @ref{3874,,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 版之後被棄用: @ref{355,,SSLContext} without protocol argument is deprecated. The
context class will either require @ref{a69,,PROTOCOL_TLS_CLIENT} or
@ref{a6a,,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{3869,,PROTOCOL_TLS}, @ref{a69,,PROTOCOL_TLS_CLIENT}, and
@ref{a6a,,PROTOCOL_TLS_SERVER} use TLS 1.2 as minimum TLS version.


@cartouche
@quotation 備註 
@ref{355,,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 備註 
@ref{355,,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{355,,SSLContext} 物件具有以下方法和屬性：

@geindex cert_store_stats() (ssl.SSLContext 的方法)
@anchor{library/ssl ssl SSLContext cert_store_stats}@anchor{11a7}
@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


在 3.4 版被加入.

@end deffn

@geindex load_cert_chain() (ssl.SSLContext 的方法)
@anchor{library/ssl ssl SSLContext load_cert_chain}@anchor{592}
@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{38a8,,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{147a,,SSLError} is raised if the private key doesn't
match with the certificate.


在 3.3 版的變更: 新增可選引數 `password'。

@end deffn

@geindex load_default_certs() (ssl.SSLContext 的方法)
@anchor{library/ssl ssl SSLContext load_default_certs}@anchor{11ad}
@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{11a6,,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{11ae,,Purpose.SERVER_AUTH} loads certificates, that are
flagged and trusted for TLS web server authentication (client side
sockets). @ref{11af,,Purpose.CLIENT_AUTH} loads CA certificates for client
certificate verification on the server side.


在 3.4 版被加入.

@end deffn

@geindex load_verify_locations() (ssl.SSLContext 的方法)
@anchor{library/ssl ssl SSLContext load_verify_locations}@anchor{10e9}
@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{3866,,verify_mode} is other than
@ref{3878,,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{11a9,,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{38a8,,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{193,,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 版的變更: 新增可選引數 `cadata'

@end deffn

@geindex get_ca_certs() (ssl.SSLContext 的方法)
@anchor{library/ssl ssl SSLContext get_ca_certs}@anchor{11a8}
@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{d23,,False} each list
entry is a dict like the output of @ref{11b3,,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


在 3.4 版被加入.

@end deffn

@geindex get_ciphers() (ssl.SSLContext 的方法)
@anchor{library/ssl ssl SSLContext get_ciphers}@anchor{ed5}
@deffn {方法} SSLContext.get_ciphers ()

Get a list of enabled ciphers. The list is in order of cipher priority.
See @ref{38a9,,SSLContext.set_ciphers()}.

範例：

@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


在 3.6 版被加入.

@end deffn

@geindex set_default_verify_paths() (ssl.SSLContext 的方法)
@anchor{library/ssl ssl SSLContext set_default_verify_paths}@anchor{11a6}
@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{38a9}
@deffn {方法} SSLContext.set_ciphers (ciphers, /)

Set the available ciphers for sockets created with this context.
It should be a string in the OpenSSL cipher list format@footnote{https://docs.openssl.org/master/man1/ciphers/}.
If no cipher can be selected (because compile-time options or other
configuration forbids use of all the specified ciphers), an
@ref{147a,,SSLError} will be raised.

@cartouche
@quotation 備註 
when connected, the @ref{378f,,SSLSocket.cipher()} method of SSL sockets will
give the currently selected cipher.

TLS 1.3 cipher suites cannot be disabled with
@ref{38a9,,set_ciphers()}.
@end quotation
@end cartouche
@end deffn

@geindex set_alpn_protocols() (ssl.SSLContext 的方法)
@anchor{library/ssl ssl SSLContext set_alpn_protocols}@anchor{105f}
@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{1060,,SSLSocket.selected_alpn_protocol()} method will
return the agreed-upon protocol.

此方法會在 @ref{1061,,HAS_ALPN} 為 @code{False} 時引發 @ref{369,,NotImplementedError}。


在 3.5 版被加入.

@end deffn

@geindex set_npn_protocols() (ssl.SSLContext 的方法)
@anchor{library/ssl ssl SSLContext set_npn_protocols}@anchor{356}
@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{a6b,,SSLSocket.selected_npn_protocol()} method will
return the agreed-upon protocol.

此方法會在 @ref{388d,,HAS_NPN} 為 @code{False} 時引發 @ref{369,,NotImplementedError}。


在 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{1b8b}
@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{ade,,ssl.SSLSocket}, the second is a string
that represents the server name that the client is intending to communicate
(or @ref{87e,,None} if the TLS Client Hello does not contain a server name)
and the third argument is the original @ref{355,,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{ade,,ssl.SSLSocket}'s
@ref{38a3,,SSLSocket.context} attribute to a new object of type
@ref{355,,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{1060,,SSLSocket.selected_alpn_protocol()} and @ref{38a3,,SSLSocket.context}.
The @ref{11b3,,SSLSocket.getpeercert()}, @ref{18c3,,SSLSocket.get_verified_chain()},
@ref{18c4,,SSLSocket.get_unverified_chain()} @ref{378f,,SSLSocket.cipher()}
and @ref{1346,,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{3896,,ALERT_DESCRIPTION_*} can be
returned.  Other return values will result in a TLS fatal error with
@ref{3896,,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{3895,,ALERT_DESCRIPTION_HANDSHAKE_FAILURE}.

This method will raise @ref{369,,NotImplementedError} if the OpenSSL library
had OPENSSL_NO_TLSEXT defined when it was built.


在 3.7 版被加入.

@end deffn

@geindex set_servername_callback() (ssl.SSLContext 的方法)
@anchor{library/ssl ssl SSLContext set_servername_callback}@anchor{11b2}
@deffn {方法} SSLContext.set_servername_callback (server_name_callback)

This is a legacy API retained for backwards compatibility. When possible,
you should use @ref{1b8b,,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{3896,,ALERT_DESCRIPTION_INTERNAL_ERROR} fatal TLS
alert message to the client.


在 3.4 版被加入.

@end deffn

@geindex load_dh_params() (ssl.SSLContext 的方法)
@anchor{library/ssl ssl SSLContext load_dh_params}@anchor{1343}
@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{3885,,OP_SINGLE_DH_USE} option to further improve security.


在 3.3 版被加入.

@end deffn

@geindex set_ecdh_curve() (ssl.SSLContext 的方法)
@anchor{library/ssl ssl SSLContext set_ecdh_curve}@anchor{1344}
@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{3886,,OP_SINGLE_ECDH_USE} option to further improve security.

此方法在 @ref{388b,,HAS_ECDH} 為 @code{False} 時不可用。


在 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{741}
@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{38aa,,SSLContext.sslsocket_class} (default @ref{ade,,SSLSocket}). The
returned SSL socket is tied to the context, its settings and certificates.
`sock' must be a @ref{14f4,,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{147a,,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{2eb,,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{1068,,SSLSocket.do_handshake()} method.  Calling
@ref{1068,,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{e02,,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{d23,,False}, it will raise the
exceptions back to the caller.

`session', see @ref{18a3,,session}.

To wrap an @ref{ade,,SSLSocket} in another @ref{ade,,SSLSocket}, use
@ref{d73,,SSLContext.wrap_bio()}.


在 3.5 版的變更: Always allow a server_hostname to be passed, even if OpenSSL does not
have SNI.



在 3.6 版的變更: 新增 `session' 引數。



在 3.7 版的變更: The method returns an instance of @ref{38aa,,SSLContext.sslsocket_class}
instead of hard-coded @ref{ade,,SSLSocket}.

@end deffn

@geindex sslsocket_class (ssl.SSLContext 的屬性)
@anchor{library/ssl ssl SSLContext sslsocket_class}@anchor{38aa}
@deffn {屬性} SSLContext.sslsocket_class

The return type of @ref{741,,SSLContext.wrap_socket()}, defaults to
@ref{ade,,SSLSocket}. The attribute can be assigned to on instances of
@ref{355,,SSLContext} in order to return a custom subclass of
@ref{ade,,SSLSocket}.


在 3.7 版被加入.

@end deffn

@geindex wrap_bio() (ssl.SSLContext 的方法)
@anchor{library/ssl ssl SSLContext wrap_bio}@anchor{d73}
@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{38ab,,SSLContext.sslobject_class} (default @ref{d72,,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{741,,SSLContext.wrap_socket()}.


在 3.6 版的變更: 新增 `session' 引數。



在 3.7 版的變更: The method returns an instance of @ref{38ab,,SSLContext.sslobject_class}
instead of hard-coded @ref{d72,,SSLObject}.

@end deffn

@geindex sslobject_class (ssl.SSLContext 的屬性)
@anchor{library/ssl ssl SSLContext sslobject_class}@anchor{38ab}
@deffn {屬性} SSLContext.sslobject_class

The return type of @ref{d73,,SSLContext.wrap_bio()}, defaults to
@ref{d72,,SSLObject}. The attribute can be overridden on instance of class
in order to return a custom subclass of @ref{d72,,SSLObject}.


在 3.7 版被加入.

@end deffn

@geindex session_stats() (ssl.SSLContext 的方法)
@anchor{library/ssl ssl SSLContext session_stats}@anchor{38ac}
@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{387a}
@deffn {屬性} SSLContext.check_hostname

Whether to match the peer cert's hostname in
@ref{1068,,SSLSocket.do_handshake()}. The context's
@ref{3866,,verify_mode} must be set to @ref{3879,,CERT_OPTIONAL} or
@ref{3867,,CERT_REQUIRED}, and you must pass `server_hostname' to
@ref{741,,wrap_socket()} in order to match the hostname.  Enabling
hostname checking automatically sets @ref{3866,,verify_mode} from
@ref{3878,,CERT_NONE} to @ref{3867,,CERT_REQUIRED}.  It cannot be set back to
@ref{3878,,CERT_NONE} as long as hostname checking is enabled. The
@ref{a69,,PROTOCOL_TLS_CLIENT} protocol enables hostname checking by default.
With other protocols, hostname checking must be enabled explicitly.

範例：

@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


在 3.4 版被加入.



在 3.7 版的變更: @ref{3866,,verify_mode} is now automatically changed
to @ref{3867,,CERT_REQUIRED}  when hostname checking is enabled and
@ref{3866,,verify_mode} is @ref{3878,,CERT_NONE}. Previously
the same operation would have failed with a @ref{2eb,,ValueError}.

@end deffn

@geindex keylog_filename (ssl.SSLContext 的屬性)
@anchor{library/ssl ssl SSLContext keylog_filename}@anchor{3868}
@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.


在 3.8 版被加入.

@end deffn

@geindex maximum_version (ssl.SSLContext 的屬性)
@anchor{library/ssl ssl SSLContext maximum_version}@anchor{d75}
@deffn {屬性} SSLContext.maximum_version

A @ref{3899,,TLSVersion} enum member representing the highest supported
TLS version. The value defaults to @ref{389b,,TLSVersion.MAXIMUM_SUPPORTED}.
The attribute is read-only for protocols other than @ref{3869,,PROTOCOL_TLS},
@ref{a69,,PROTOCOL_TLS_CLIENT}, and @ref{a6a,,PROTOCOL_TLS_SERVER}.

The attributes @ref{d75,,maximum_version},
@ref{d74,,minimum_version} and
@ref{a32,,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{3883,,OP_NO_TLSv1_2} in @ref{a32,,options} and
@ref{d75,,maximum_version} set to @ref{389f,,TLSVersion.TLSv1_2}
will not be able to establish a TLS 1.2 connection.


在 3.7 版被加入.

@end deffn

@geindex minimum_version (ssl.SSLContext 的屬性)
@anchor{library/ssl ssl SSLContext minimum_version}@anchor{d74}
@deffn {屬性} SSLContext.minimum_version

Like @ref{d75,,SSLContext.maximum_version} except it is the lowest
supported version or @ref{389a,,TLSVersion.MINIMUM_SUPPORTED}.


在 3.7 版被加入.

@end deffn

@geindex num_tickets (ssl.SSLContext 的屬性)
@anchor{library/ssl ssl SSLContext num_tickets}@anchor{38ad}
@deffn {屬性} SSLContext.num_tickets

Control the number of TLS 1.3 session tickets of a
@ref{a6a,,PROTOCOL_TLS_SERVER} context. The setting has no impact on TLS
1.0 to 1.2 connections.


在 3.8 版被加入.

@end deffn

@geindex options (ssl.SSLContext 的屬性)
@anchor{library/ssl ssl SSLContext options}@anchor{a32}
@deffn {屬性} SSLContext.options

An integer representing the set of SSL options enabled on this context.
The default value is @ref{3880,,OP_ALL}, but you can specify other options
such as @ref{a33,,OP_NO_SSLv2} by ORing them together.


在 3.6 版的變更: @ref{a32,,SSLContext.options} 會回傳 @ref{3888,,Options} 旗標：

@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{d74,,SSLContext.minimum_version} and
@ref{d75,,SSLContext.maximum_version} instead.

@end deffn

@geindex post_handshake_auth (ssl.SSLContext 的屬性)
@anchor{library/ssl ssl SSLContext post_handshake_auth}@anchor{c1d}
@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{3866,,SSLContext.verify_mode} must
be set to @ref{3879,,CERT_OPTIONAL} or @ref{3867,,CERT_REQUIRED}, too. The
actual client cert exchange is delayed until
@ref{c1e,,SSLSocket.verify_client_post_handshake()} is called and some I/O is
performed.


在 3.8 版被加入.

@end deffn

@geindex protocol (ssl.SSLContext 的屬性)
@anchor{library/ssl ssl SSLContext protocol}@anchor{38ae}
@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{d6e}
@deffn {屬性} SSLContext.hostname_checks_common_name

Whether @ref{387a,,check_hostname} falls back to verify the cert's
subject common name in the absence of a subject alternative name
extension (default: true).


在 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{38af}
@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.


在 3.10 版被加入.

@end deffn

@geindex verify_flags (ssl.SSLContext 的屬性)
@anchor{library/ssl ssl SSLContext verify_flags}@anchor{11a9}
@deffn {屬性} SSLContext.verify_flags

The flags for certificate verification operations. You can set flags like
@ref{11ab,,VERIFY_CRL_CHECK_LEAF} by ORing them together. By default OpenSSL
does neither require nor verify certificate revocation lists (CRLs).


在 3.4 版被加入.



在 3.6 版的變更: @ref{11a9,,SSLContext.verify_flags} 會回傳 @ref{387d,,VerifyFlags} 旗標：

@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{3866}
@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{3878,,CERT_NONE}, @ref{3879,,CERT_OPTIONAL} or @ref{3867,,CERT_REQUIRED}.


在 3.6 版的變更: @ref{3866,,SSLContext.verify_mode} 會回傳 @ref{387b,,VerifyMode} 列舉：

@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{38b0}
@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{193,,bytes-like object} representing the pre-shared key. Return a zero
length PSK to reject the connection.

Setting @code{callback} to @ref{87e,,None} removes any existing callback.

@cartouche
@quotation 備註 
使用 TLS 1.3 時：


@itemize -

@item 
@code{hint} 參數始終為 @ref{87e,,None}。

@item 
client-identity must be a non-empty string.
@end itemize
@end quotation
@end cartouche

範例用法：

@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{369,,NotImplementedError} if @ref{3893,,HAS_PSK} is
@code{False}.


在 3.13 版被加入.

@end deffn

@geindex set_psk_server_callback() (ssl.SSLContext 的方法)
@anchor{library/ssl ssl SSLContext set_psk_server_callback}@anchor{38b1}
@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{193,,bytes-like object} representing the pre-shared key.
Return a zero length PSK to reject the connection.

Setting @code{callback} to @ref{87e,,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
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{369,,NotImplementedError} if @ref{3893,,HAS_PSK} is
@code{False}.


在 3.13 版被加入.

@end deffn

@geindex certificates（憑證）

@geindex X509 certificate（X509 憑證）

@node Certificates,範例<27>,SSL Contexts,ssl --- socket 物件的 TLS/SSL 包裝器
@anchor{library/ssl certificates}@anchor{38b2}@anchor{library/ssl ssl-certificates}@anchor{38a8}
@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{38b3}
@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{38b4}
@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{11ad,,SSLContext.load_default_certs()}, this is done
automatically with @ref{47a,,create_default_context()}.

@node Combined key and certificate,Self-signed certificates,CA certificates,Certificates
@anchor{library/ssl combined-key-and-certificate}@anchor{38b5}
@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{592,,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{38b6}
@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 範例<27>,Notes on non-blocking sockets,Certificates,ssl --- socket 物件的 TLS/SSL 包裝器
@anchor{library/ssl examples}@anchor{38b7}
@subsubsection 範例


@menu
* Testing for SSL support:: 
* Client-side operation:: 
* 伺服器端操作:: 

@end menu

@node Testing for SSL support,Client-side operation,,範例<27>
@anchor{library/ssl testing-for-ssl-support}@anchor{38b8}
@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,伺服器端操作,Testing for SSL support,範例<27>
@anchor{library/ssl client-side-operation}@anchor{38b9}
@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{a69,,PROTOCOL_TLS_CLIENT} protocol configures the context for cert
validation and hostname verification. @ref{3866,,verify_mode} is
set to @ref{3867,,CERT_REQUIRED} and @ref{387a,,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{3867,,CERT_REQUIRED}
and @ref{387a,,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

參閱下方 @ref{374a,,Security considerations} 的討論。

@node 伺服器端操作,,Client-side operation,範例<27>
@anchor{library/ssl server-side-operation}@anchor{38ba}
@subsubsection 伺服器端操作


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{741,,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{386c,,non-blocking mode} and use an event loop).

@node Notes on non-blocking sockets,記憶體 BIO 支援<2>,範例<27>,ssl --- socket 物件的 TLS/SSL 包裝器
@anchor{library/ssl notes-on-non-blocking-sockets}@anchor{38bb}@anchor{library/ssl ssl-nonblocking}@anchor{386c}
@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{ade,,SSLSocket} methods will raise either
@ref{1065,,SSLWantWriteError} or @ref{1064,,SSLWantReadError} instead of
@ref{235,,BlockingIOError} if an I/O operation would
block. @ref{1064,,SSLWantReadError} will be raised if a read operation on
the underlying socket is necessary, and @ref{1065,,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{1065,,SSLWantWriteError} or
@ref{1064,,SSLWantReadError}.


@item 
Calling @ref{f9b,,select()} tells you that the OS-level socket can be
read from (or written to), but it does not imply that there is sufficient
data at the upper SSL layer.  For example, only part of an SSL frame might
have arrived.  Therefore, you must be ready to handle @code{SSLSocket.recv()}
and @code{SSLSocket.send()} failures, and retry after another call to
@ref{f9b,,select()}.

@item 
Conversely, since the SSL layer has its own framing, a SSL socket may
still have data available for reading without @ref{f9b,,select()}
being aware of it.  Therefore, you should first call
@code{SSLSocket.recv()} to drain any potentially available data, and then
only block on a @ref{f9b,,select()} call if still necessary.

(of course, similar provisions apply when using other primitives such as
@ref{2f5b,,poll()}, or those in the @ref{c7,,selectors} module)

@item 
The SSL handshake itself will be non-blocking: the
@ref{1068,,SSLSocket.do_handshake()} method has to be retried until it returns
successfully.  Here is a synopsis using @ref{f9b,,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{386c,,non-blocking SSL sockets} and provides a higher level @ref{366e,,Streams API}.
It polls for events using the @ref{c7,,selectors} module and
handles @ref{1065,,SSLWantWriteError}, @ref{1064,,SSLWantReadError} and
@ref{235,,BlockingIOError} exceptions. It runs the SSL handshake asynchronously
as well.


@node 記憶體 BIO 支援<2>,SSL session,Notes on non-blocking sockets,ssl --- socket 物件的 TLS/SSL 包裝器
@anchor{library/ssl memory-bio-support}@anchor{38bc}
@subsubsection 記憶體 BIO 支援



在 3.5 版被加入.


Ever since the SSL module was introduced in Python 2.6, the @ref{ade,,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{f9c,,socket.socket},
from which @ref{ade,,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{f9c,,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{ade,,SSLSocket} called @ref{d72,,SSLObject} is
provided.

@geindex SSLObject (ssl 中的類別)
@anchor{library/ssl ssl SSLObject}@anchor{d72}
@deffn {類別} ssl.SSLObject

A reduced-scope variant of @ref{ade,,SSLSocket} representing an SSL protocol
instance that does not contain any network IO methods. This class is
typically used by framework authors that want to implement asynchronous IO
for SSL through memory buffers.

This class implements an interface on top of a low-level SSL object as
implemented by OpenSSL. This object captures the state of an SSL connection
but does not provide any network IO itself. IO needs to be performed through
separate "BIO" objects which are OpenSSL's IO abstraction layer.

This class has no public constructor.  An @ref{d72,,SSLObject} instance
must be created using the @ref{d73,,wrap_bio()} method. This
method will create the @ref{d72,,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{38a3,,context}

@item 
@ref{38a5,,server_side}

@item 
@ref{d70,,server_hostname}

@item 
@ref{18a3,,session}

@item 
@ref{38a6,,session_reused}

@item 
@ref{1069,,read()}

@item 
@ref{106a,,write()}

@item 
@ref{11b3,,getpeercert()}

@item 
@ref{18c3,,get_verified_chain()}

@item 
@ref{18c4,,get_unverified_chain()}

@item 
@ref{1060,,selected_alpn_protocol()}

@item 
@ref{a6b,,selected_npn_protocol()}

@item 
@ref{378f,,cipher()}

@item 
@ref{1067,,shared_ciphers()}

@item 
@ref{1346,,compression()}

@item 
@ref{38a4,,pending()}

@item 
@ref{1068,,do_handshake()}

@item 
@ref{c1e,,verify_client_post_handshake()}

@item 
@ref{38a2,,unwrap()}

@item 
@ref{1345,,get_channel_binding()}

@item 
@ref{1063,,version()}
@end itemize

When compared to @ref{ade,,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{105d,,MemoryBIO} buffers.

@item 
There is no `do_handshake_on_connect' machinery. You must always manually
call @ref{1068,,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{1a03,,SSLEOFError} exception.

@item 
The method @ref{38a2,,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{11b2,,SSLContext.set_servername_callback()} will get an @ref{d72,,SSLObject}
instance instead of a @ref{ade,,SSLSocket} instance as its first parameter.
@end itemize

Some notes related to the use of @ref{d72,,SSLObject}:


@itemize -

@item 
All IO on an @ref{d72,,SSLObject} is @ref{386c,,non-blocking}.
This means that for example @ref{1069,,read()} will raise an
@ref{1064,,SSLWantReadError} if it needs more data than the incoming BIO has
available.
@end itemize


在 3.7 版的變更: @ref{d72,,SSLObject} instances must be created with
@ref{d73,,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{105d,,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{105d}
@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{38bd}
@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{38be}
@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{38bf}
@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{38c0}
@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{38c1}
@deffn {方法} write_eof ()

Write an EOF marker to the memory BIO. After this method has been called, it
is illegal to call @ref{38c0,,write()}. The attribute @ref{38be,,eof} will
become true after all data currently in the buffer has been read.
@end deffn
@end deffn

@node SSL session,Security considerations<2>,記憶體 BIO 支援<2>,ssl --- socket 物件的 TLS/SSL 包裝器
@anchor{library/ssl ssl-session}@anchor{38c2}
@subsubsection SSL session



在 3.6 版被加入.


@geindex SSLSession (ssl 中的類別)
@anchor{library/ssl ssl SSLSession}@anchor{ed4}
@deffn {類別} ssl.SSLSession

Session object used by @ref{18a3,,session}.

@geindex id (ssl.SSLSession 的屬性)
@anchor{library/ssl ssl SSLSession id}@anchor{38c3}
@deffn {屬性} id
@end deffn

@geindex time (ssl.SSLSession 的屬性)
@anchor{library/ssl ssl SSLSession time}@anchor{38c4}
@deffn {屬性} time
@end deffn

@geindex timeout (ssl.SSLSession 的屬性)
@anchor{library/ssl ssl SSLSession timeout}@anchor{38c5}
@deffn {屬性} timeout
@end deffn

@geindex ticket_lifetime_hint (ssl.SSLSession 的屬性)
@anchor{library/ssl ssl SSLSession ticket_lifetime_hint}@anchor{38c6}
@deffn {屬性} ticket_lifetime_hint
@end deffn

@geindex has_ticket (ssl.SSLSession 的屬性)
@anchor{library/ssl ssl SSLSession has_ticket}@anchor{38c7}
@deffn {屬性} has_ticket
@end deffn
@end deffn

@node Security considerations<2>,TLS 1 3,SSL session,ssl --- socket 物件的 TLS/SSL 包裝器
@anchor{library/ssl security-considerations}@anchor{38c8}@anchor{library/ssl ssl-security}@anchor{374a}
@subsubsection Security considerations


@menu
* Best defaults:: 
* 手動設定:: 
* Multi-processing:: 

@end menu

@node Best defaults,手動設定,,Security considerations<2>
@anchor{library/ssl best-defaults}@anchor{38c9}
@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{47a,,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{b1e,,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{592,,SSLContext.load_cert_chain()}.

By contrast, if you create the SSL context by calling the @ref{355,,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 手動設定,Multi-processing,Best defaults,Security considerations<2>
@anchor{library/ssl manual-settings}@anchor{38ca}
@subsubsection 手動設定


@menu
* 驗證憑證:: 
* 協定版本:: 
* Cipher selection:: 

@end menu

@node 驗證憑證,協定版本,,手動設定
@anchor{library/ssl verifying-certificates}@anchor{38cb}
@subsubsection 驗證憑證


When calling the @ref{355,,SSLContext} constructor directly,
@ref{3878,,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{3867,,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{11b3,,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{387a,,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{3867,,CERT_REQUIRED} and similarly check the client certificate.

@node 協定版本,Cipher selection,驗證憑證,手動設定
@anchor{library/ssl protocol-versions}@anchor{38cc}
@subsubsection 協定版本


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{a69,,PROTOCOL_TLS_CLIENT} or
@ref{a6a,,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{a69,,PROTOCOL_TLS_CLIENT}
implies certificate validation and hostname checks by default. You have to
load certificates into the context.

@node Cipher selection,,協定版本,手動設定
@anchor{library/ssl cipher-selection}@anchor{38cd}
@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{38a9,,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{ed5,,SSLContext.get_ciphers()} or the @code{openssl ciphers} command on your
system.

@node Multi-processing,,手動設定,Security considerations<2>
@anchor{library/ssl multi-processing}@anchor{38ce}
@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{4b0,,os.fork()}.  Any
successful call of @ref{3872,,RAND_add()} or @ref{740,,RAND_bytes()} is
sufficient.

@node TLS 1 3,,Security considerations<2>,ssl --- socket 物件的 TLS/SSL 包裝器
@anchor{library/ssl ssl-tlsv1-3}@anchor{d71}@anchor{library/ssl tls-1-3}@anchor{38cf}
@subsubsection TLS 1.3



在 3.7 版被加入.


The TLS 1.3 protocol behaves slightly differently than previous version
of TLS/SSL. Some new TLS 1.3 features are not yet available.


@itemize -

@item 
TLS 1.3 uses a disjunct set of cipher suites. All AES-GCM and
ChaCha20 cipher suites are enabled by default.  The method
@ref{38a9,,SSLContext.set_ciphers()} cannot enable or disable any TLS 1.3
ciphers yet, but @ref{ed5,,SSLContext.get_ciphers()} returns them.

@item 
Session tickets are no longer sent as part of the initial handshake and
are handled differently.  @ref{18a3,,SSLSocket.session} and @ref{ed4,,SSLSession}
are not compatible with TLS 1.3.

@item 
Client-side certificates are also no longer verified during the initial
handshake.  A server can request a certificate at any time.  Clients
process certificate requests while they send or receive application data
from the server.

@item 
TLS 1.3 features like early data, deferred TLS client cert request,
signature algorithm configuration, and rekeying are not supported yet.
@end itemize


@subsubheading 也參考



@table @asis

@item @ref{f9c,,socket.socket} 類別

底層 @ref{d1,,socket} 類別的文件

@item SSL/TLS Strong Encryption: An Introduction@footnote{https://httpd.apache.org/docs/trunk/en/ssl/ssl_intro.html}

Apache HTTP Server 文件的介紹

@geindex RFC; RFC 1422

@item RFC 1422: Privacy Enhancement for Internet Electronic Mail: Part II: Certificate-Based Key Management@footnote{https://datatracker.ietf.org/doc/html/rfc1422.html}

Steve Kent

@geindex RFC; RFC 4086

@item RFC 4086: Randomness Requirements for Security@footnote{https://datatracker.ietf.org/doc/html/rfc4086.html}

Donald E., Jeffrey I. Schiller

@geindex RFC; RFC 5280

@item RFC 5280: Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile@footnote{https://datatracker.ietf.org/doc/html/rfc5280.html}

D. Cooper

@geindex RFC; RFC 5246

@item RFC 5246: The Transport Layer Security (TLS) Protocol Version 1.2@footnote{https://datatracker.ietf.org/doc/html/rfc5246.html}

T. Dierks et. al.

@geindex RFC; RFC 6066

@item RFC 6066: Transport Layer Security (TLS) Extensions@footnote{https://datatracker.ietf.org/doc/html/rfc6066.html}

D. Eastlake

@item IANA TLS: Transport Layer Security (TLS) Parameters@footnote{https://www.iana.org/assignments/tls-parameters/tls-parameters.xml}

IANA

@geindex RFC; RFC 7525

@item RFC 7525: Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)@footnote{https://datatracker.ietf.org/doc/html/rfc7525.html}

IETF

@item Mozilla's Server Side TLS recommendations@footnote{https://wiki.mozilla.org/Security/Server_Side_TLS}

Mozilla
@end table


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node select --- 等待 I/O 完成,selectors --- 高階 I/O 多工,ssl --- socket 物件的 TLS/SSL 包裝器,網路與行程間通訊
@anchor{library/select doc}@anchor{38d0}@anchor{library/select module-select}@anchor{c6}@anchor{library/select select-waiting-for-i-o-completion}@anchor{38d1}@anchor{library/select translation-repo}@anchor{38d2}
@subsection @code{select} --- 等待 I/O 完成


@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{c7,,selectors} module allows high-level and efficient I/O
multiplexing, built upon the @ref{c6,,select} module primitives. Users are
encouraged to use the @ref{c7,,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{2006,,可用性}: not WASI.

此模組在 WebAssembly 平台上不起作用或無法使用。更多資訊請參閱 @ref{1a99,,WebAssembly 平台}。

The module defines the following:

@geindex error
@anchor{library/select select error}@anchor{1252}
@deffn {例外} select.error

A deprecated alias of @ref{2c0,,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{2c0,,OSError}.

@end deffn

@geindex devpoll() (於 select 模組中)
@anchor{library/select select devpoll}@anchor{1191}
@deffn {函式} select.devpoll ()

(Only supported on Solaris and derivatives.)  Returns a @code{/dev/poll}
polling object; see section @ref{38d3,,/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{10f7,,non-inheritable}.


在 3.3 版被加入.



在 3.4 版的變更: The new file descriptor is now non-inheritable.

@end deffn

@geindex epoll() (於 select 模組中)
@anchor{library/select select epoll}@anchor{118f}
@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()} 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{38d4,,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{186,,with} statement, the new file descriptor is automatically closed
at the end of the block.

The new file descriptor is @ref{10f7,,non-inheritable}.


在 3.3 版的變更: 新增 `flags' 參數。



在 3.4 版的變更: Support for the @ref{186,,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{10f9,,os.set_inheritable()} to make the file descriptor inheritable.

@end deffn

@geindex poll() (於 select 模組中)
@anchor{library/select select poll}@anchor{2f5b}
@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{38d5,,Polling Objects} below for the methods supported
by polling objects.
@end deffn

@geindex kqueue() (於 select 模組中)
@anchor{library/select select kqueue}@anchor{1994}
@deffn {函式} select.kqueue ()

(Only supported on BSD.)  Returns a kernel queue object; see section
@ref{38d6,,Kqueue Objects} below for the methods supported by kqueue objects.

The new file descriptor is @ref{10f7,,non-inheritable}.


在 3.4 版的變更: The new file descriptor is now non-inheritable.

@end deffn

@geindex kevent() (於 select 模組中)
@anchor{library/select select kevent}@anchor{38d7}
@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{38d8,,Kevent Objects} below for the methods supported by kevent objects.
@end deffn

@geindex select() (於 select 模組中)
@anchor{library/select select select}@anchor{f9b}
@deffn {函式} select.select (rlist, wlist, xlist[, timeout])

This is a straightforward interface to the Unix @code{select()} system call.
The first three arguments are iterables of 'waitable objects': either
integers representing file descriptors or objects with a parameterless method
named @ref{2b7e,,fileno()} returning such an integer:


@itemize *

@item 
`rlist': wait until ready for reading

@item 
`wlist': wait until ready for writing

@item 
`xlist': wait for an "exceptional condition" (see the manual page for what
your system considers such a condition)
@end itemize

Empty iterables are allowed, but acceptance of three empty iterables is
platform-dependent. (It is known to work on Unix but not on Windows.)  The
optional `timeout' argument specifies a time-out as a floating-point number
in seconds.  When the `timeout' argument is omitted the function blocks until
at least one file descriptor is ready.  A time-out value of zero specifies a
poll and never blocks.

The return value is a triple of lists of objects that are ready: subsets of the
first three arguments.  When the time-out is reached without a file descriptor
becoming ready, three empty lists are returned.

@geindex socket() (於 socket 模組)
@geindex popen() (於 os 模組)

Among the acceptable object types in the iterables are Python @ref{13c4,,file objects} (e.g. @code{sys.stdin}, or objects returned by
@ref{315,,open()} or @ref{319,,os.popen()}), socket objects returned by
@ref{f9c,,socket.socket()}.  You may also define a `wrapper' class yourself,
as long as it has an appropriate @ref{2b7e,,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{f83,,InterruptedError}.

@end deffn

@geindex PIPE_BUF (於 select 模組中)
@anchor{library/select select PIPE_BUF}@anchor{140b}
@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{f9b,,select()},
@code{poll()} or another interface in this module.  This doesn't apply
to other kind of file-like objects such as sockets.

This value is guaranteed by POSIX to be at least 512.

@ref{2006,,可用性}: Unix


在 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 --- 等待 I/O 完成
@anchor{library/select dev-poll-polling-objects}@anchor{38d9}@anchor{library/select devpoll-objects}@anchor{38d3}
@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{1193}
@deffn {方法} devpoll.close ()

Close the file descriptor of the polling object.


在 3.4 版被加入.

@end deffn

@geindex closed (select.devpoll 的屬性)
@anchor{library/select select devpoll closed}@anchor{1194}
@deffn {屬性} devpoll.closed

@code{True} if the polling object is closed.


在 3.4 版被加入.

@end deffn

@geindex fileno() (select.devpoll 的方法)
@anchor{library/select select devpoll fileno}@anchor{1192}
@deffn {方法} devpoll.fileno ()

Return the file descriptor number of the polling object.


在 3.4 版被加入.

@end deffn

@geindex register() (select.devpoll 的方法)
@anchor{library/select select devpoll register}@anchor{38da}
@deffn {方法} devpoll.register (fd[, eventmask])

Register a file descriptor with the polling object.  Future calls to the
@ref{2f5b,,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{2b7e,,fileno()} method that returns an integer.  File objects
implement @code{fileno()}, so they can also be used as the argument.

`eventmask' is an optional bitmask describing the type of events you want to
check for. The constants are the same that with @code{poll()}
object. The default value is a combination of the constants @code{POLLIN},
@code{POLLPRI}, and @code{POLLOUT}.

@cartouche
@quotation 警告 
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{38db}
@deffn {方法} devpoll.modify (fd[, eventmask])

This method does an @ref{38dc,,unregister()} followed by a
@ref{38da,,register()}. It is (a bit) more efficient that doing the same
explicitly.
@end deffn

@geindex unregister() (select.devpoll 的方法)
@anchor{library/select select devpoll unregister}@anchor{38dc}
@deffn {方法} devpoll.unregister (fd)

Remove a file descriptor being tracked by a polling object.  Just like the
@ref{38da,,register()} method, `fd' can be an integer or an object with a
@ref{2b7e,,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{f97}
@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{87e,,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{f83,,InterruptedError}.

@end deffn

@node Edge and Level Trigger Polling epoll Objects,Polling Objects,/dev/poll Polling Objects,select --- 等待 I/O 完成
@anchor{library/select edge-and-level-trigger-polling-epoll-objects}@anchor{38dd}@anchor{library/select epoll-objects}@anchor{38d4}
@subsubsection Edge and Level Trigger Polling (epoll) Objects


@quotation

@indicateurl{https://linux.die.net/man/4/epoll}

`eventmask'


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

常數

@tab

含義

@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

等價於 @code{EPOLLIN}

@item

@code{EPOLLRDBAND}

@tab

Priority data band can be read.

@item

@code{EPOLLWRNORM}

@tab

等價於 @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



在 3.6 版被加入: @code{EPOLLEXCLUSIVE} was added.  It's only supported by Linux Kernel 4.5
or later.



在 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{1190}
@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{38de}
@deffn {屬性} epoll.closed

@code{True} if the epoll object is closed.
@end deffn

@geindex fileno() (select.epoll 的方法)
@anchor{library/select select epoll fileno}@anchor{38df}
@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{38e0}
@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{38e1}
@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{38e2}
@deffn {方法} epoll.modify (fd, eventmask)

Modify a registered file descriptor.
@end deffn

@geindex unregister() (select.epoll 的方法)
@anchor{library/select select epoll unregister}@anchor{b4a}
@deffn {方法} epoll.unregister (fd)

Remove a registered file descriptor from the epoll object.


在 3.9 版的變更: The method no longer ignores the @ref{b4b,,EBADF} error.

@end deffn

@geindex poll() (select.epoll 的方法)
@anchor{library/select select epoll poll}@anchor{f98}
@deffn {方法} epoll.poll (timeout=None, maxevents=-1)

Wait for events. timeout in seconds (float)


在 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{f83,,InterruptedError}.

@end deffn

@node Polling Objects,Kqueue Objects,Edge and Level Trigger Polling epoll Objects,select --- 等待 I/O 完成
@anchor{library/select poll-objects}@anchor{38d5}@anchor{library/select polling-objects}@anchor{38e3}
@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{38e4}
@deffn {方法} poll.register (fd[, eventmask])

Register a file descriptor with the polling object.  Future calls to the
@ref{2f5b,,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{2b7e,,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

常數

@tab

含義

@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{38e5}
@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{2c0,,OSError} exception with errno
@code{ENOENT} to be raised.
@end deffn

@geindex unregister() (select.poll 的方法)
@anchor{library/select select poll unregister}@anchor{38e6}
@deffn {方法} poll.unregister (fd)

Remove a file descriptor being tracked by a polling object.  Just like the
@ref{38e4,,register()} method, `fd' can be an integer or an object with a
@ref{2b7e,,fileno()} method that returns an integer.

Attempting to remove a file descriptor that was never registered causes a
@ref{5df,,KeyError} exception to be raised.
@end deffn

@geindex poll() (select.poll 的方法)
@anchor{library/select select poll poll}@anchor{f9a}
@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{87e,,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{f83,,InterruptedError}.

@end deffn

@node Kqueue Objects,Kevent Objects,Polling Objects,select --- 等待 I/O 完成
@anchor{library/select id1}@anchor{38e7}@anchor{library/select kqueue-objects}@anchor{38d6}
@subsubsection Kqueue Objects


@geindex close() (select.kqueue 的方法)
@anchor{library/select select kqueue close}@anchor{38e8}
@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{38e9}
@deffn {屬性} kqueue.closed

@code{True} if the kqueue object is closed.
@end deffn

@geindex fileno() (select.kqueue 的方法)
@anchor{library/select select kqueue fileno}@anchor{38ea}
@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{38eb}
@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{f99}
@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 (floats 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{f83,,InterruptedError}.

@end deffn

@node Kevent Objects,,Kqueue Objects,select --- 等待 I/O 完成
@anchor{library/select id2}@anchor{38ec}@anchor{library/select kevent-objects}@anchor{38d8}
@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{38ed}
@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{2b7e,,fileno()} method. kevent
stores the integer internally.
@end deffn

@geindex filter (select.kevent 的屬性)
@anchor{library/select select kevent filter}@anchor{38ee}
@deffn {屬性} kevent.filter

Name of the kernel filter.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

常數

@tab

含義

@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{38ef}
@deffn {屬性} kevent.flags

Filter action.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

常數

@tab

含義

@item

@code{KQ_EV_ADD}

@tab

Adds or modifies an event

@item

@code{KQ_EV_DELETE}

@tab

Removes an event from the queue

@item

@code{KQ_EV_ENABLE}

@tab

Permitscontrol() to returns the event

@item

@code{KQ_EV_DISABLE}

@tab

Disablesevent

@item

@code{KQ_EV_ONESHOT}

@tab

Removes event after first occurrence

@item

@code{KQ_EV_CLEAR}

@tab

Reset the state after an event is retrieved

@item

@code{KQ_EV_SYSFLAGS}

@tab

internal event

@item

@code{KQ_EV_FLAG1}

@tab

internal event

@item

@code{KQ_EV_EOF}

@tab

Filter specific EOF condition

@item

@code{KQ_EV_ERROR}

@tab

See return values

@end multitable

@end deffn

@geindex fflags (select.kevent 的屬性)
@anchor{library/select select kevent fflags}@anchor{38f0}
@deffn {屬性} kevent.fflags

Filter specific flags.

@code{KQ_FILTER_READ} 和  @code{KQ_FILTER_WRITE} 篩選旗標：


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

常數

@tab

含義

@item

@code{KQ_NOTE_LOWAT}

@tab

low water mark of a socket buffer

@end multitable


@code{KQ_FILTER_VNODE} 篩選旗標：


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

常數

@tab

含義

@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} 篩選旗標：


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

常數

@tab

含義

@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} 篩選旗標（macOS 上不可用）：


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

常數

@tab

含義

@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{38f1}
@deffn {屬性} kevent.data

Filter specific data.
@end deffn

@geindex udata (select.kevent 的屬性)
@anchor{library/select select kevent udata}@anchor{38f2}
@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 --- 高階 I/O 多工,signal --- 設定非同步事件的處理函式,select --- 等待 I/O 完成,網路與行程間通訊
@anchor{library/selectors doc}@anchor{38f3}@anchor{library/selectors module-selectors}@anchor{c7}@anchor{library/selectors selectors-high-level-i-o-multiplexing}@anchor{38f4}@anchor{library/selectors translation-repo}@anchor{38f5}
@subsection @code{selectors} --- 高階 I/O 多工


@geindex module; selectors


在 3.4 版被加入.


`原始碼：'Lib/selectors.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/selectors.py}


__________________________________________________________________


@menu
* 簡介: 簡介<8>. 
* Classes: Classes<2>. 
* 範例: 範例<28>. 

@end menu

@node 簡介<8>,Classes<2>,,selectors --- 高階 I/O 多工
@anchor{library/selectors introduction}@anchor{38f6}
@subsubsection 簡介


This module allows high-level and efficient I/O multiplexing, built upon the
@ref{c6,,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{38f7,,BaseSelector} abstract base class, along with several
concrete implementations (@ref{37cd,,KqueueSelector}, @ref{dcb,,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{2b7e,,fileno()} method, or a raw file descriptor. See @ref{13c4,,file object}.

@ref{38f8,,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{c6,,select}

Low-level I/O multiplexing module.
@end table


@c include for modules that don't work on WASM

@ref{2006,,可用性}: not WASI.

此模組在 WebAssembly 平台上不起作用或無法使用。更多資訊請參閱 @ref{1a99,,WebAssembly 平台}。

@node Classes<2>,範例<28>,簡介<8>,selectors --- 高階 I/O 多工
@anchor{library/selectors classes}@anchor{38f9}
@subsubsection Classes


Classes hierarchy:

@example
BaseSelector
+-- SelectSelector
+-- PollSelector
+-- EpollSelector
+-- DevpollSelector
+-- KqueueSelector
@end example

In the following, `events' is a bitwise mask indicating which I/O events should
be waited for on a given file object. It can be a combination of the modules
constants below:

@quotation


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

常數

@tab

含義

@item

@geindex EVENT_READ (於 selectors 模組中)
@anchor{library/selectors selectors EVENT_READ}@anchor{38fa}
@deffn {資料} selectors.EVENT_READ
@end deffn

@tab

Available for read

@item

@geindex EVENT_WRITE (於 selectors 模組中)
@anchor{library/selectors selectors EVENT_WRITE}@anchor{38fb}
@deffn {資料} selectors.EVENT_WRITE
@end deffn

@tab

Available for write

@end multitable

@end quotation

@geindex SelectorKey (selectors 中的類別)
@anchor{library/selectors selectors SelectorKey}@anchor{38fc}
@deffn {類別} selectors.SelectorKey

A @ref{38fc,,SelectorKey} is a @ref{4db,,namedtuple} used to
associate a file object to its underlying file descriptor, selected event
mask and attached data. It is returned by several @ref{38f7,,BaseSelector}
methods.

@geindex fileobj (selectors.SelectorKey 的屬性)
@anchor{library/selectors selectors SelectorKey fileobj}@anchor{38fd}
@deffn {屬性} fileobj

File object registered.
@end deffn

@geindex fd (selectors.SelectorKey 的屬性)
@anchor{library/selectors selectors SelectorKey fd}@anchor{38fe}
@deffn {屬性} fd

Underlying file descriptor.
@end deffn

@geindex events (selectors.SelectorKey 的屬性)
@anchor{library/selectors selectors SelectorKey events}@anchor{38ff}
@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{3900}
@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{38f7}
@deffn {類別} selectors.BaseSelector

A @ref{38f7,,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{38f8,,DefaultSelector} instead, or one of @ref{37ca,,SelectSelector},
@ref{37cd,,KqueueSelector} etc. if you want to specifically use an
implementation, and your platform supports it.
@ref{38f7,,BaseSelector} and its concrete implementations support the
@ref{1e1,,context manager} protocol.

@geindex register() (selectors.BaseSelector 的方法)
@anchor{library/selectors selectors BaseSelector register}@anchor{3901}
@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{38fc,,SelectorKey} instance, or raises a
@ref{2eb,,ValueError} in case of invalid event mask or file descriptor, or
@ref{5df,,KeyError} if the file object is already registered.
@end deffn

@geindex unregister() (selectors.BaseSelector 的方法)
@anchor{library/selectors selectors BaseSelector unregister}@anchor{3902}
@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{38fc,,SelectorKey} instance, or raises a
@ref{5df,,KeyError} if `fileobj' is not registered.  It will raise
@ref{2eb,,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{dca}
@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{38fc,,SelectorKey} instance, or raises a
@ref{2eb,,ValueError} in case of invalid event mask or file descriptor, or
@ref{5df,,KeyError} if the file object is not registered.
@end deffn

@geindex select() (selectors.BaseSelector 的方法)
@anchor{library/selectors selectors BaseSelector select}@anchor{3903}
@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{38fc,,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{3904}
@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{3905}
@deffn {方法} get_key (fileobj)

Return the key associated with a registered file object.

This returns the @ref{38fc,,SelectorKey} instance associated to this file
object, or raises @ref{5df,,KeyError} if the file object is not registered.
@end deffn

@geindex get_map() (selectors.BaseSelector 的方法)
@anchor{library/selectors selectors BaseSelector get_map}@anchor{3906}
@deffn {方法} abstractmethod get_map ()

Return a mapping of file objects to selector keys.

This returns a @ref{abe,,Mapping} instance mapping
registered file objects to their associated @ref{38fc,,SelectorKey}
instance.
@end deffn
@end deffn

@geindex DefaultSelector (selectors 中的類別)
@anchor{library/selectors selectors DefaultSelector}@anchor{38f8}
@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{37ca}
@deffn {類別} selectors.SelectSelector

基於 @ref{f9b,,select.select()} 的選擇器。
@end deffn

@geindex PollSelector (selectors 中的類別)
@anchor{library/selectors selectors PollSelector}@anchor{dcc}
@deffn {類別} selectors.PollSelector

基於 @ref{2f5b,,select.poll()} 的選擇器。
@end deffn

@geindex EpollSelector (selectors 中的類別)
@anchor{library/selectors selectors EpollSelector}@anchor{dcb}
@deffn {類別} selectors.EpollSelector

基於 @ref{118f,,select.epoll()} 的選擇器。

@geindex fileno() (selectors.EpollSelector 的方法)
@anchor{library/selectors selectors EpollSelector fileno}@anchor{3907}
@deffn {方法} fileno ()

This returns the file descriptor used by the underlying
@ref{118f,,select.epoll()} object.
@end deffn
@end deffn

@geindex DevpollSelector (selectors 中的類別)
@anchor{library/selectors selectors DevpollSelector}@anchor{dcd}
@deffn {類別} selectors.DevpollSelector

基於 @ref{1191,,select.devpoll()} 的選擇器。

@geindex fileno() (selectors.DevpollSelector 的方法)
@anchor{library/selectors selectors DevpollSelector fileno}@anchor{3908}
@deffn {方法} fileno ()

This returns the file descriptor used by the underlying
@ref{1191,,select.devpoll()} object.
@end deffn


在 3.5 版被加入.

@end deffn

@geindex KqueueSelector (selectors 中的類別)
@anchor{library/selectors selectors KqueueSelector}@anchor{37cd}
@deffn {類別} selectors.KqueueSelector

基於 @ref{1994,,select.kqueue()} 的選擇器。

@geindex fileno() (selectors.KqueueSelector 的方法)
@anchor{library/selectors selectors KqueueSelector fileno}@anchor{3909}
@deffn {方法} fileno ()

This returns the file descriptor used by the underlying
@ref{1994,,select.kqueue()} object.
@end deffn
@end deffn

@node 範例<28>,,Classes<2>,selectors --- 高階 I/O 多工
@anchor{library/selectors examples}@anchor{390a}
@subsubsection 範例


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 --- 設定非同步事件的處理函式,mmap --- 記憶體對映檔案的支援,selectors --- 高階 I/O 多工,網路與行程間通訊
@anchor{library/signal doc}@anchor{390b}@anchor{library/signal module-signal}@anchor{cb}@anchor{library/signal signal-set-handlers-for-asynchronous-events}@anchor{390c}@anchor{library/signal translation-repo}@anchor{390d}
@subsection @code{signal} --- 設定非同步事件的處理函式


@geindex module; signal

`原始碼：'Lib/signal.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/signal.py}


__________________________________________________________________


本模組提供於 Python 中使用訊號處理程式的機制。

@menu
* 一般規則:: 
* 模組內容: 模組內容<5>. 
* 範例: 範例<29>. 
* 關於 SIGPIPE 的說明:: 
* 訊號處理程式與例外的說明:: 

@end menu

@node 一般規則,模組內容<5>,,signal --- 設定非同步事件的處理函式
@anchor{library/signal general-rules}@anchor{390e}
@subsubsection 一般規則


@ref{1335,,signal.signal()} 函式允許定義自訂的處理程式，會在收到訊號時執行。我們安裝了少數的預設處理程式：@ref{390f,,SIGPIPE} 會被忽略 (所以管道和 socket 上的寫入錯誤可以當作一般的 Python 例外報告)，而 @ref{253,,SIGINT}（如果父行程沒有改變它的話）會被轉換成 @ref{bbc,,KeyboardInterrupt} 例外。

特定訊號的處理程式一旦被設定，就會一直被安裝，直到被明確地重設為止 (不管底層的實作為何，Python 皆模擬出 BSD 風格的介面)，但 @ref{2f96,,SIGCHLD} 的處理程式除外，它會跟隨底層的實作。

在 WebAssembly 平台上，訊號是模擬出來的，故行為不同。有幾個函式和訊號在這些平台上是不可用的。

@menu
* Python 訊號處理程式的執行:: 
* 訊號和執行緒:: 

@end menu

@node Python 訊號處理程式的執行,訊號和執行緒,,一般規則
@anchor{library/signal execution-of-python-signal-handlers}@anchor{3910}
@subsubsection Python 訊號處理程式的執行


Python 訊號處理程式不會在低階（C 語言）訊號處理程式中執行。相反地，低階訊號處理程式會設定一個旗標，告訴@ref{3911,,虛擬機}在稍後執行相對應的 Python 訊號處理程式（例如在下一個 @ref{4a5,,bytecode} 指令）。這會有一些後果：


@itemize *

@item 
捕捉像 @ref{127c,,SIGFPE} 或 @ref{127b,,SIGSEGV} 這類由 C 程式碼中無效操作所引起的同步錯誤是沒有意義的。Python 將從訊號處理程式中回傳到 C 程式碼，而 C 程式碼很可能再次引發相同的訊號，導致 Python 明顯假當機 (hang)。從 Python 3.3 開始，你可以使用 @ref{5c,,faulthandler} 模組來報告同步錯誤。

@item 
純粹以 C 實作的長時間計算（例如在大量文字上的正規表示式比對）可能會不間斷地運行任意長度的時間而不考慮收到的任何訊號。當計算完成時，Python 訊號處理程式會被呼叫。

@item 
如果處理程式引發例外，就會在主執行緒中「憑空」產生例外。請參閱@ref{2596,,下面的說明}。
@end itemize

@node 訊號和執行緒,,Python 訊號處理程式的執行,一般規則
@anchor{library/signal id1}@anchor{3912}@anchor{library/signal signals-and-threads}@anchor{3913}
@subsubsection 訊號和執行緒


Python 訊號處理程式總是在主直譯器的主 Python 執行緒中執行，即使訊號是在另一個執行緒中接收到的。這意味著訊號不能用來做為執行緒間通訊的方式。你可以使用 @ref{f3,,threading} 模組的同步原語 (synchronization primitive) 來代替。

此外，只有主直譯器的主執行緒才被允許設定新的訊號處理程式。

@node 模組內容<5>,範例<29>,一般規則,signal --- 設定非同步事件的處理函式
@anchor{library/signal module-contents}@anchor{3914}
@subsubsection 模組內容



在 3.5 版的變更: 下面列出的訊號 (SIG*)、處理器（@ref{1ad7,,SIG_DFL}、@ref{1ad6,,SIG_IGN}）和訊號遮罩 (sigmask)（@ref{3915,,SIG_BLOCK}、@ref{3916,,SIG_UNBLOCK}、@ref{3917,,SIG_SETMASK}）的相關常數被轉換成 @ref{ed6,,enums}（@ref{3918,,Signals}、@ref{3919,,Handlers} 和 @ref{391a,,Sigmasks}）。@ref{1975,,getsignal()}、@ref{1331,,pthread_sigmask()}、@ref{1333,,sigpending()} 和 @ref{1334,,sigwait()} 函式會回傳可被人類閱讀的@ref{ed6,,枚舉}作為 @ref{3918,,Signals} 物件。


訊號模組定義了三個枚舉：

@geindex Signals (signal 中的類別)
@anchor{library/signal signal Signals}@anchor{3918}
@deffn {類別} signal.Signals

SIG* 常數和 CTRL_* 常數的 @ref{ed6,,enum.IntEnum} 集合。


在 3.5 版被加入.

@end deffn

@geindex Handlers (signal 中的類別)
@anchor{library/signal signal Handlers}@anchor{3919}
@deffn {類別} signal.Handlers

@ref{1ad7,,SIG_DFL} 和 @ref{1ad6,,SIG_IGN} 常數的 @ref{ed6,,enum.IntEnum} 集合。


在 3.5 版被加入.

@end deffn

@geindex Sigmasks (signal 中的類別)
@anchor{library/signal signal Sigmasks}@anchor{391a}
@deffn {類別} signal.Sigmasks

@ref{3915,,SIG_BLOCK}、@ref{3916,,SIG_UNBLOCK} 和 @ref{3917,,SIG_SETMASK} 常數的 @ref{ed6,,enum.IntEnum} 集合。

@ref{2006,,可用性}: Unix.

更多資訊請見 @code{sigprocmask(2)@footnote{https://manpages.debian.org/sigprocmask(2)}} 與 @code{pthread_sigmask(3)@footnote{https://manpages.debian.org/pthread_sigmask(3)}} 線上手冊。


在 3.5 版被加入.

@end deffn

在 @ref{cb,,signal} 模組中定義的變數有：

@geindex SIG_DFL (於 signal 模組中)
@anchor{library/signal signal SIG_DFL}@anchor{1ad7}
@deffn {資料} signal.SIG_DFL

這是兩種標準訊號處理選項之一；它會簡單地執行訊號的預設功能。例如，在大多數系統上，@ref{391b,,SIGQUIT} 的預設動作是轉儲 (dump) 核心並退出，而 @ref{2f96,,SIGCHLD} 的預設動作是直接忽略。
@end deffn

@geindex SIG_IGN (於 signal 模組中)
@anchor{library/signal signal SIG_IGN}@anchor{1ad6}
@deffn {資料} signal.SIG_IGN

這是另一個標準的訊號處理程式，會直接忽略給定的訊號。
@end deffn

@geindex SIGABRT (於 signal 模組中)
@anchor{library/signal signal SIGABRT}@anchor{127d}
@deffn {資料} signal.SIGABRT

來自 @code{abort(3)@footnote{https://manpages.debian.org/abort(3)}} 的中止訊號。
@end deffn

@geindex SIGALRM (於 signal 模組中)
@anchor{library/signal signal SIGALRM}@anchor{391c}
@deffn {資料} signal.SIGALRM

來自 @code{alarm(2)@footnote{https://manpages.debian.org/alarm(2)}} 的計時器訊號。

@ref{2006,,可用性}: Unix.
@end deffn

@geindex SIGBREAK (於 signal 模組中)
@anchor{library/signal signal SIGBREAK}@anchor{391d}
@deffn {資料} signal.SIGBREAK

從鍵盤中斷 (CTRL + BREAK)。

@ref{2006,,可用性}: Windows.
@end deffn

@geindex SIGBUS (於 signal 模組中)
@anchor{library/signal signal SIGBUS}@anchor{127e}
@deffn {資料} signal.SIGBUS

匯流排錯誤（記憶體存取不良）。

@ref{2006,,可用性}: Unix.
@end deffn

@geindex SIGCHLD (於 signal 模組中)
@anchor{library/signal signal SIGCHLD}@anchor{2f96}
@deffn {資料} signal.SIGCHLD

子行程停止或終止。

@ref{2006,,可用性}: Unix.
@end deffn

@geindex SIGCLD (於 signal 模組中)
@anchor{library/signal signal SIGCLD}@anchor{391e}
@deffn {資料} signal.SIGCLD

@ref{2f96,,SIGCHLD} 的別名。

@ref{2006,,可用性}: not macOS.
@end deffn

@geindex SIGCONT (於 signal 模組中)
@anchor{library/signal signal SIGCONT}@anchor{2fa4}
@deffn {資料} signal.SIGCONT

如果目前行程是被停止的，則繼續運行

@ref{2006,,可用性}: Unix.
@end deffn

@geindex SIGFPE (於 signal 模組中)
@anchor{library/signal signal SIGFPE}@anchor{127c}
@deffn {資料} signal.SIGFPE

浮點運算例外。例如除以零。


@subsubheading 也參考


@ref{b36,,ZeroDivisionError} 會在除法或模運算 (modulo operation) 的第二個引數為零時引發。

@end deffn

@geindex SIGHUP (於 signal 模組中)
@anchor{library/signal signal SIGHUP}@anchor{391f}
@deffn {資料} signal.SIGHUP

偵測到控制終端機掛斷 (hangup) 或控制行程死亡。

@ref{2006,,可用性}: Unix.
@end deffn

@geindex SIGILL (於 signal 模組中)
@anchor{library/signal signal SIGILL}@anchor{127f}
@deffn {資料} signal.SIGILL

非法指令。
@end deffn

@geindex SIGINT (於 signal 模組中)
@anchor{library/signal signal SIGINT}@anchor{253}
@deffn {資料} signal.SIGINT

從鍵盤中斷 (CTRL + C)。

預設動作是引發 @ref{bbc,,KeyboardInterrupt}。
@end deffn

@geindex SIGKILL (於 signal 模組中)
@anchor{library/signal signal SIGKILL}@anchor{d48}
@deffn {資料} signal.SIGKILL

殺死訊號。

它無法被捕捉、阻擋或忽略。

@ref{2006,,可用性}: Unix.
@end deffn

@geindex SIGPIPE (於 signal 模組中)
@anchor{library/signal signal SIGPIPE}@anchor{390f}
@deffn {資料} signal.SIGPIPE

管道中斷 (broken pipe)：寫到沒有讀取器 (reader) 的管道。

預設動作是忽略訊號。

@ref{2006,,可用性}: Unix.
@end deffn

@geindex SIGPROF (於 signal 模組中)
@anchor{library/signal signal SIGPROF}@anchor{3920}
@deffn {資料} signal.SIGPROF

Profiling timer expired.

@ref{2006,,可用性}: Unix.
@end deffn

@geindex SIGQUIT (於 signal 模組中)
@anchor{library/signal signal SIGQUIT}@anchor{391b}
@deffn {資料} signal.SIGQUIT

Terminal quit signal.

@ref{2006,,可用性}: Unix.
@end deffn

@geindex SIGSEGV (於 signal 模組中)
@anchor{library/signal signal SIGSEGV}@anchor{127b}
@deffn {資料} signal.SIGSEGV

記憶體區段錯誤 (segmentation fault)：無效記憶體參照。
@end deffn

@geindex SIGSTOP (於 signal 模組中)
@anchor{library/signal signal SIGSTOP}@anchor{3921}
@deffn {資料} signal.SIGSTOP

停止執行（無法被捕捉或忽略）。
@end deffn

@geindex SIGSTKFLT (於 signal 模組中)
@anchor{library/signal signal SIGSTKFLT}@anchor{1b1b}
@deffn {資料} signal.SIGSTKFLT

輔助處理器 (coprocessor) 上的堆疊錯誤 (stack fault)。Linux 核心不會引發此訊號：它只能在使用者空間 (user space) 中引發。

@ref{2006,,可用性}: Linux.

在訊號可用的架構上。請參閱 @code{signal(7)@footnote{https://manpages.debian.org/signal(7)}} 線上手冊以取得更多資訊。


在 3.11 版被加入.

@end deffn

@geindex SIGTERM (於 signal 模組中)
@anchor{library/signal signal SIGTERM}@anchor{15d6}
@deffn {資料} signal.SIGTERM

終止訊號。
@end deffn

@geindex SIGUSR1 (於 signal 模組中)
@anchor{library/signal signal SIGUSR1}@anchor{3922}
@deffn {資料} signal.SIGUSR1

使用者定義訊號 1。

@ref{2006,,可用性}: Unix.
@end deffn

@geindex SIGUSR2 (於 signal 模組中)
@anchor{library/signal signal SIGUSR2}@anchor{3923}
@deffn {資料} signal.SIGUSR2

使用者定義訊號 2。

@ref{2006,,可用性}: Unix.
@end deffn

@geindex SIGVTALRM (於 signal 模組中)
@anchor{library/signal signal SIGVTALRM}@anchor{3924}
@deffn {資料} signal.SIGVTALRM

Virtual timer expired.

@ref{2006,,可用性}: Unix.
@end deffn

@geindex SIGWINCH (於 signal 模組中)
@anchor{library/signal signal SIGWINCH}@anchor{3925}
@deffn {資料} signal.SIGWINCH

視窗調整大小訊號。

@ref{2006,,可用性}: Unix.
@end deffn

@geindex SIGXCPU (於 signal 模組中)
@anchor{library/signal signal SIGXCPU}@anchor{3926}
@deffn {資料} signal.SIGXCPU

CPU time limit exceeded.

@ref{2006,,可用性}: Unix.
@end deffn


@deffn {資料} SIG*

所有的訊號編號都是以符號定義的。例如，掛斷訊號被定義為 @ref{391f,,signal.SIGHUP}；變數名稱與 C 程式中使用的名稱相同，可在 @code{<signal.h>} 中找到。Unix 線上手冊 '@code{signal}' 列出了現有的訊號（在某些系統上是 @code{signal(2)@footnote{https://manpages.debian.org/signal(2)}}，在其他系統上是在 @code{signal(7)@footnote{https://manpages.debian.org/signal(7)}} 中）。請注意，並非所有系統都會定義同一套訊號名稱；只有那些由系統所定義的名稱才會由這個模組定義。
@end deffn

@geindex CTRL_C_EVENT (於 signal 模組中)
@anchor{library/signal signal CTRL_C_EVENT}@anchor{1560}
@deffn {資料} signal.CTRL_C_EVENT

與 @code{Ctrl}+@code{C} 擊鍵 (keystroke) 事件相對應的訊號。此訊號只能與 @ref{155f,,os.kill()} 搭配使用。

@ref{2006,,可用性}: Windows.


在 3.2 版被加入.

@end deffn

@geindex CTRL_BREAK_EVENT (於 signal 模組中)
@anchor{library/signal signal CTRL_BREAK_EVENT}@anchor{1561}
@deffn {資料} signal.CTRL_BREAK_EVENT

與 @code{Ctrl}+@code{Break} 擊鍵事件相對應的訊號。此訊號只能與 @ref{155f,,os.kill()} 搭配使用。

@ref{2006,,可用性}: Windows.


在 3.2 版被加入.

@end deffn

@geindex NSIG (於 signal 模組中)
@anchor{library/signal signal NSIG}@anchor{1ab5}
@deffn {資料} signal.NSIG

比最高編號訊號的編號多一。使用 @ref{3927,,valid_signals()} 來取得有效的訊號編號。
@end deffn

@geindex ITIMER_REAL (於 signal 模組中)
@anchor{library/signal signal ITIMER_REAL}@anchor{3928}
@deffn {資料} signal.ITIMER_REAL

即時減少間隔計時器 (interval timer)，並在到期時送出 @ref{391c,,SIGALRM}。
@end deffn

@geindex ITIMER_VIRTUAL (於 signal 模組中)
@anchor{library/signal signal ITIMER_VIRTUAL}@anchor{3929}
@deffn {資料} signal.ITIMER_VIRTUAL

僅在執行行程時遞減間隔計時器，並在到期時傳送 SIGVTALRM。
@end deffn

@geindex ITIMER_PROF (於 signal 模組中)
@anchor{library/signal signal ITIMER_PROF}@anchor{392a}
@deffn {資料} signal.ITIMER_PROF

當行程執行或系統代表行程執行時，都會減少間隔計時器。與 ITIMER_VIRTUAL 配合，這個計時器通常用來分析 (profile) 應用程式在使用者空間與核心空間 (kernel space) 所花費的時間。SIGPROF 會在到期時傳送。
@end deffn

@geindex SIG_BLOCK (於 signal 模組中)
@anchor{library/signal signal SIG_BLOCK}@anchor{3915}
@deffn {資料} signal.SIG_BLOCK

@ref{1331,,pthread_sigmask()} 的 `how' 參數的可能值，表示訊號將被阻檔。


在 3.3 版被加入.

@end deffn

@geindex SIG_UNBLOCK (於 signal 模組中)
@anchor{library/signal signal SIG_UNBLOCK}@anchor{3916}
@deffn {資料} signal.SIG_UNBLOCK

@ref{1331,,pthread_sigmask()} 的 `how' 參數的可能值，表示訊號將被解除阻檔。


在 3.3 版被加入.

@end deffn

@geindex SIG_SETMASK (於 signal 模組中)
@anchor{library/signal signal SIG_SETMASK}@anchor{3917}
@deffn {資料} signal.SIG_SETMASK

@ref{1331,,pthread_sigmask()} 的 `how' 參數的可能值，表示訊號遮罩 (signal mask) 要被取代。


在 3.3 版被加入.

@end deffn

@ref{cb,,signal} 模組定義了一個例外：

@geindex ItimerError
@anchor{library/signal signal ItimerError}@anchor{392b}
@deffn {例外} signal.ItimerError

當 @ref{392c,,setitimer()} 或 @ref{392d,,getitimer()} 底層實作發生錯誤時引發訊號。如果傳給 @ref{392c,,setitimer()} 的是無效的間隔計時器或負數時間，則預期會發生此錯誤。這個錯誤是 @ref{2c0,,OSError} 的子型別。


在 3.3 版被加入: 此錯誤過去是 @ref{124e,,IOError} 的子型別，現在是 @ref{2c0,,OSError} 的別名。

@end deffn

@ref{cb,,signal} 模組定義了下列函式：

@geindex alarm() (於 signal 模組中)
@anchor{library/signal signal alarm}@anchor{392e}
@deffn {函式} signal.alarm (time)

如果 `time' 非零，則此函式會要求在 `time' 秒後傳送 @ref{391c,,SIGALRM} 訊號給該行程。任何先前排程 (scheduled) 的警報都會被取消（任何時候都只能排程一個警報）。回傳值是先前設定的警報原本再等多久就會被傳送的秒數。如果 `time' 為零，則不會去排程任何警報，且已排程的警報會被取消。如果回傳值為零，則代表目前未排程任何警報。

@ref{2006,,可用性}: Unix.

更多資訊請見 @code{alarm(2)@footnote{https://manpages.debian.org/alarm(2)}} 線上手冊。
@end deffn

@geindex getsignal() (於 signal 模組中)
@anchor{library/signal signal getsignal}@anchor{1975}
@deffn {函式} signal.getsignal (signalnum)

回傳訊號 `signalnum' 的目前訊號處理程式。回傳值可以是一個可呼叫的 Python 物件，或是特殊值 @ref{1ad6,,signal.SIG_IGN}、@ref{1ad7,,signal.SIG_DFL} 或 @ref{87e,,None} 之一。這裡的 @ref{1ad6,,signal.SIG_IGN} 表示訊號先前被忽略，@ref{1ad7,,signal.SIG_DFL} 表示訊號先前使用預設的處理方式，而 @code{None} 表示先前的訊號處理程式並未從 Python 安裝。
@end deffn

@geindex strsignal() (於 signal 模組中)
@anchor{library/signal signal strsignal}@anchor{1ce7}
@deffn {函式} signal.strsignal (signalnum)

回傳訊號 `signalnum' 的描述，例如 @ref{253,,SIGINT} 的 "Interrupt"。如果 `signalnum' 沒有描述，則回傳 @ref{87e,,None}。如果 `signalnum' 無效則會引發 @ref{2eb,,ValueError}。


在 3.8 版被加入.

@end deffn

@geindex valid_signals() (於 signal 模組中)
@anchor{library/signal signal valid_signals}@anchor{3927}
@deffn {函式} signal.valid_signals ()

回傳此平台上的有效訊號編號集合。如果某些訊號被系統保留作為內部使用，則此值可能小於 @code{range(1, NSIG)}。


在 3.8 版被加入.

@end deffn

@geindex pause() (於 signal 模組中)
@anchor{library/signal signal pause}@anchor{392f}
@deffn {函式} signal.pause ()

使行程休眠，直到接收到訊號；然後呼叫適當的處理程式。不會回傳任何東西。

@ref{2006,,可用性}: Unix.

更多資訊請見 @code{signal(2)@footnote{https://manpages.debian.org/signal(2)}} 線上手冊。

也請見 @ref{1334,,sigwait()}、@ref{fa6,,sigwaitinfo()}、@ref{fa5,,sigtimedwait()} 和 @ref{1333,,sigpending()}。
@end deffn

@geindex raise_signal() (於 signal 模組中)
@anchor{library/signal signal raise_signal}@anchor{1ab9}
@deffn {函式} signal.raise_signal (signum)

傳送訊號至呼叫的行程。不會回傳任何東西。


在 3.8 版被加入.

@end deffn

@geindex pidfd_send_signal() (於 signal 模組中)
@anchor{library/signal signal pidfd_send_signal}@anchor{b1c}
@deffn {函式} signal.pidfd_send_signal (pidfd, sig, siginfo=None, flags=0)

傳送訊號 `sig' 到檔案描述器 `pidfd' 所指的行程。Python 目前不支援 `siginfo' 參數；它必須是 @code{None}。`flags' 引數是提供給未來的擴充；目前沒有定義旗標值。

更多資訊請見 @code{pidfd_send_signal(2)@footnote{https://manpages.debian.org/pidfd_send_signal(2)}} 線上手冊。

@ref{2006,,可用性}: Linux >= 5.1, Android >= @ref{d7d,,build-time} API level 31


在 3.9 版被加入.

@end deffn

@geindex pthread_kill() (於 signal 模組中)
@anchor{library/signal signal pthread_kill}@anchor{1332}
@deffn {函式} signal.pthread_kill (thread_id, signalnum)

將訊號 `signalnum' 傳送給與呼叫者在同一行程中的另一個執行緒 `thread_id'。目標執行緒能執行任何程式碼（無論為 Python 與否）。但是，如果目標執行緒正執行 Python 直譯器，Python 訊號處理程式將會@ref{3913,,由主直譯器的主執行緒來執行}。因此，向特定 Python 執行緒發送訊號的唯一意義是強制執行中的系統呼叫以 @ref{f83,,InterruptedError} 方式失敗。

使用 @ref{135b,,threading.get_ident()} 或 @ref{176,,threading.Thread} 物件的 @ref{2feb,,ident} 屬性來取得 `thread_id' 的適當值。

如果 `signalnum' 為 0，則不會傳送訊號，但仍會執行錯誤檢查；這可用來檢查目標執行緒是否仍在執行。

引發一個附帶引數 @code{thread_id}、@code{signalnum} 的@ref{1b70,,稽核事件} @code{signal.pthread_kill}。

@ref{2006,,可用性}: Unix.

更多資訊請見 @code{pthread_kill(3)@footnote{https://manpages.debian.org/pthread_kill(3)}} 線上手冊。

另請參閱 @ref{155f,,os.kill()}。


在 3.3 版被加入.

@end deffn

@geindex pthread_sigmask() (於 signal 模組中)
@anchor{library/signal signal pthread_sigmask}@anchor{1331}
@deffn {函式} signal.pthread_sigmask (how, mask)

擷取和/或變更呼叫執行緒的訊號遮罩。訊號遮罩是目前阻擋呼叫者傳送的訊號集合。將舊的訊號遮罩作為一組訊號集合回傳。

呼叫的行為取決於 `how' 的值，如下所示。


@itemize *

@item 
@ref{3915,,SIG_BLOCK}：被阻檔的訊號集合是目前訊號集合與 `mask' 引數的聯集。

@item 
@ref{3916,,SIG_UNBLOCK}：將 `mask' 中的訊號從目前阻檔的訊號集合中移除。嘗試為未被阻檔的訊號解除阻檔是允許的。

@item 
@ref{3917,,SIG_SETMASK}：將被阻檔的訊號集合設定為 `mask' 引數。
@end itemize

`mask' 是一組訊號編號（例如 @{@ref{253,,signal.SIGINT}, @ref{15d6,,signal.SIGTERM}@}）的集合。使用 @ref{3927,,valid_signals()} 來取得包含所有訊號的完整遮罩。

例如，@code{signal.pthread_sigmask(signal.SIG_BLOCK, [])} 會讀取呼叫執行緒的訊號遮罩。

@ref{d48,,SIGKILL} 和 @ref{3921,,SIGSTOP} 不能被阻檔。

@ref{2006,,可用性}: Unix.

更多資訊請見 @code{sigprocmask(2)@footnote{https://manpages.debian.org/sigprocmask(2)}} 與 @code{pthread_sigmask(3)@footnote{https://manpages.debian.org/pthread_sigmask(3)}} 線上手冊。

另請參閱 @ref{392f,,pause()}、@ref{1333,,sigpending()} 與 @ref{1334,,sigwait()}。


在 3.3 版被加入.

@end deffn

@geindex setitimer() (於 signal 模組中)
@anchor{library/signal signal setitimer}@anchor{392c}
@deffn {函式} signal.setitimer (which, seconds, interval=0.0)

設定由 `which' 指定的間隔計時器（@ref{3928,,signal.ITIMER_REAL}、@ref{3929,,signal.ITIMER_VIRTUAL} 或 @ref{392a,,signal.ITIMER_PROF} 之一）並在*seconds*（接受浮點數，與 @ref{392e,,alarm()} 不同）之後啟動，在之後的每 `interval' 秒啟動一次（如果 `interval' 非零）。`which' 指定的間隔計時器可透過將 `seconds' 設定為零來清除它。

當間隔計時器啟動時，一個訊號會被傳送給行程。傳送的訊號取決於使用的計時器；@ref{3928,,signal.ITIMER_REAL} 會傳送 @ref{391c,,SIGALRM}，@ref{3929,,signal.ITIMER_VIRTUAL} 會傳送 @ref{3924,,SIGVTALRM}，而 @ref{392a,,signal.ITIMER_PROF} 會傳送 @ref{3920,,SIGPROF}。

舊值會以一個元組回傳：(delay, interval)。

嘗試傳入無效的間隔計時器會導致 @ref{392b,,ItimerError}。

@ref{2006,,可用性}: Unix.
@end deffn

@geindex getitimer() (於 signal 模組中)
@anchor{library/signal signal getitimer}@anchor{392d}
@deffn {函式} signal.getitimer (which)

回傳由 `which' 指定之間隔計時器的目前值。

@ref{2006,,可用性}: Unix.
@end deffn

@geindex set_wakeup_fd() (於 signal 模組中)
@anchor{library/signal signal set_wakeup_fd}@anchor{d5f}
@deffn {函式} signal.set_wakeup_fd (fd, *, warn_on_full_buffer=True)

設定喚醒檔案描述器為 `fd'。當接收到其處理程式已有被註冊的訊號時，訊號編號會以單一位元組寫入 fd。如果你沒有為你在意的訊號註冊處理程式，就不會寫入到喚醒 fd。這可被函式庫用來喚醒輪詢 (wakeup a poll) 或 select 呼叫，讓訊號得以完全處理。

回傳舊的喚醒 fd（如果檔案描述器喚醒未啟用，則回傳 -1）。如果 `fd' 為 -1，則會停用檔案描述器喚醒。如果不是 -1，`fd' 必須是非阻塞的。在再次呼叫輪詢或 select 之前，由函式庫來決定是否移除 `fd' 中的任何位元組。

當啟用執行緒時，這個函式只能從@ref{3913,,主直譯器}的主執行緒來呼叫；嘗試從其他執行緒呼叫它將會引發 @ref{2eb,,ValueError} 例外。

使用這個函式有兩種常見的方式。在這兩種方法中，當訊號抵達時，你都要使用 fd 來喚醒，但它們的不同之處在於如何判斷`哪個或哪些'訊號有抵達。

在第一種方法中，我們從 fd 的緩衝區中讀取資料，而位元組值則提供訊號編號。這個方法很簡單，但在少數情況下可能會遇到問題：一般來說，fd 的緩衝區空間有限，如果太多訊號來得太快，那麼緩衝區可能會滿，而有些訊號可能會遺失。如果你使用這種方法，那麼你應該設定 @code{warn_on_full_buffer=True}，這至少會在訊號丟失時將警告印出到 stderr。

在第二種方法中，我們`只會'將喚醒 fd 用於喚醒，而忽略實際的位元組值。在這種情況下，我們只在乎 fd 的緩衝區是空或非空；即便緩衝區滿了也不代表有問題。如果你使用這種方法，那麼你應該設定 @code{warn_on_full_buffer=False}，這樣你的使用者就不會被虛假的警告訊息所混淆。


在 3.5 版的變更: 在 Windows 上，此功能現在也支援 socket 處理程式。



在 3.7 版的變更: 新增 @code{warn_on_full_buffer} 參數。

@end deffn

@geindex siginterrupt() (於 signal 模組中)
@anchor{library/signal signal siginterrupt}@anchor{1336}
@deffn {函式} signal.siginterrupt (signalnum, flag)

改變系統呼叫重新啟動的行為：如果 `flag' 是 @ref{d23,,False}，系統呼叫會在被訊號 `signalnum' 中斷時重新啟動，否則系統呼叫會被中斷。不會回傳任何東西。

@ref{2006,,可用性}: Unix.

更多資訊請見 @code{siginterrupt(3)@footnote{https://manpages.debian.org/siginterrupt(3)}} 線上手冊。

請注意，使用 @ref{cb,,signal()} 安裝訊號處理程式，會透過隱式呼叫 @code{siginterrupt()} 來將重新啟動的行為重設為可中斷，且指定訊號的 `flag' 值為 true。
@end deffn

@geindex signal() (於 signal 模組中)
@anchor{library/signal signal signal}@anchor{1335}
@deffn {函式} signal.signal (signalnum, handler)

將訊號 `signalnum' 的處理程式設定為函式 `handler'。`handler' 可以是帶兩個引數的可呼叫 Python 物件（見下面），或是特殊值 @ref{1ad6,,signal.SIG_IGN} 或 @ref{1ad7,,signal.SIG_DFL} 之一。先前的訊號處理程式將會被回傳（請參閱上面 @ref{1975,,getsignal()} 的說明）。（更多資訊請參閱 Unix 線上手冊 @code{signal(2)@footnote{https://manpages.debian.org/signal(2)}}）。

當啟用執行緒時，這個函式只能從@ref{3913,,主直譯器}的主執行緒來呼叫；嘗試從其他執行緒呼叫它將會引發 @ref{2eb,,ValueError} 例外。

`handler' 被呼叫時有兩個引數：訊號編號和目前的堆疊 frame（@code{None} 或一個 frame 物件；關於 frame 物件的描述，請參閱@ref{8e7,,型別階層中的描述}或 @ref{82,,inspect} 模組中的屬性描述）。

在 Windows 上，@ref{cb,,signal()} 只能在使用 @ref{127d,,SIGABRT}、@ref{127c,,SIGFPE}、@ref{127f,,SIGILL}、@ref{253,,SIGINT}、@ref{127b,,SIGSEGV}、@ref{15d6,,SIGTERM} 或 @ref{391d,,SIGBREAK} 時呼叫。在其他情況下會引發 @ref{2eb,,ValueError}。請注意，並非所有系統都定義相同的訊號名稱；如果訊號名稱沒有被定義為 @code{SIG*} 模組層級常數，則會引發 @ref{5e8,,AttributeError} 錯誤。
@end deffn

@geindex sigpending() (於 signal 模組中)
@anchor{library/signal signal sigpending}@anchor{1333}
@deffn {函式} signal.sigpending ()

檢查待傳送至呼叫執行緒的訊號集合（即阻檔時已被提出的訊號）。回傳待定訊號的集合。

@ref{2006,,可用性}: Unix.

更多資訊請見 @code{sigpending(2)@footnote{https://manpages.debian.org/sigpending(2)}} 線上手冊。

另請參閱 @ref{392f,,pause()}、@ref{1331,,pthread_sigmask()} 與 @ref{1334,,sigwait()}。


在 3.3 版被加入.

@end deffn

@geindex sigwait() (於 signal 模組中)
@anchor{library/signal signal sigwait}@anchor{1334}
@deffn {函式} signal.sigwait (sigset)

暫停呼叫執行緒的執行，直到送出訊號集合 `sigset' 中指定的一個訊號。函式接受訊號（將其從待定訊號清單中移除），並回傳訊號編號。

@ref{2006,,可用性}: Unix.

更多資訊請見 @code{sigwait(3)@footnote{https://manpages.debian.org/sigwait(3)}} 線上手冊。

另也請見 @ref{392f,,pause()}、@ref{1331,,pthread_sigmask()}、@ref{1333,,sigpending()}、@ref{fa6,,sigwaitinfo()} 和 @ref{fa5,,sigtimedwait()}。


在 3.3 版被加入.

@end deffn

@geindex sigwaitinfo() (於 signal 模組中)
@anchor{library/signal signal sigwaitinfo}@anchor{fa6}
@deffn {函式} signal.sigwaitinfo (sigset)

暫停呼叫執行緒的執行，直到送出訊號集合 `sigset' 中指定的一個訊號。該函式接受訊號，並將其從待定訊號清單中移除。如果 `sigset' 中的一個訊號已經是呼叫執行緒的待定訊號，函式會立即回傳該訊號的相關資訊。對於已傳送的訊號，訊號處理程式不會被呼叫。如果被不在 `sigset' 中的訊號中斷，函式會引發 @ref{f83,,InterruptedError}。

回傳值是一個物件，代表 @code{siginfo_t} 結構所包含的資料，即 @code{si_signo}、@code{si_code}、@code{si_errno}、@code{si_pid}、@code{si_uid}、@code{si_status}、@code{si_band}。

@ref{2006,,可用性}: Unix.

更多資訊請見 @code{sigwaitinfo(2)@footnote{https://manpages.debian.org/sigwaitinfo(2)}} 線上手冊。

另請參閱 @ref{392f,,pause()}、@ref{1334,,sigwait()} 與 @ref{fa5,,sigtimedwait()}。


在 3.3 版被加入.



在 3.5 版的變更: 現在如果被不在 `sigset' 中的訊號中斷，且訊號處理程式沒有引發例外，則會重試函式（理由請參閱 
@geindex Python Enhancement Proposals; PEP 475
PEP 475@footnote{https://peps.python.org/pep-0475/}）。

@end deffn

@geindex sigtimedwait() (於 signal 模組中)
@anchor{library/signal signal sigtimedwait}@anchor{fa5}
@deffn {函式} signal.sigtimedwait (sigset, timeout)

類似 @ref{fa6,,sigwaitinfo()}，但需要額外的 `timeout' 引數指定逾時時間。如果 `timeout' 指定為 @code{0}，會執行輪詢。如果發生逾時則會回傳 @ref{87e,,None}。

@ref{2006,,可用性}: Unix.

更多資訊請見 @code{sigtimedwait(2)@footnote{https://manpages.debian.org/sigtimedwait(2)}} 線上手冊。

另請參閱 @ref{392f,,pause()}、@ref{1334,,sigwait()} 與 @ref{fa6,,sigwaitinfo()}。


在 3.3 版被加入.



在 3.5 版的變更: 現在如果被不在 `sigset' 中的訊號中斷，且訊號處理程式沒有引發例外，則會使用重新計算的 `timeout' 重試函式（理由請參閱 
@geindex Python Enhancement Proposals; PEP 475
PEP 475@footnote{https://peps.python.org/pep-0475/}）。

@end deffn

@node 範例<29>,關於 SIGPIPE 的說明,模組內容<5>,signal --- 設定非同步事件的處理函式
@anchor{library/signal examples}@anchor{3930}@anchor{library/signal signal-example}@anchor{3931}
@subsubsection 範例


這是一個最小範例程式。它使用 @ref{392e,,alarm()} 函式來限制等待開啟檔案的時間；如果檔案是用於可能未開啟的序列裝置，這會很有用，因為這通常會導致 @ref{f8d,,os.open()} 無限期地被擱置。解決方法是在開啟檔案前設定一個 5 秒的警報；如果操作時間過長，警報訊號就會被送出，而處理程式會產生例外。

@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!")

# 設定訊號處理程式與五秒警報
signal.signal(signal.SIGALRM, handler)
signal.alarm(5)

# 這個 open() 可能無限期地被擱置
fd = os.open('/dev/ttyS0', os.O_RDWR)

signal.alarm(0)          # 停用警報
@end example

@node 關於 SIGPIPE 的說明,訊號處理程式與例外的說明,範例<29>,signal --- 設定非同步事件的處理函式
@anchor{library/signal note-on-sigpipe}@anchor{3932}
@subsubsection 關於 SIGPIPE 的說明


將程式的輸出管道化到 @code{head(1)@footnote{https://manpages.debian.org/head(1)}} 之類的工具，會在你的行程的標準輸出接收器提早關閉時，導致 @ref{390f,,SIGPIPE} 訊號傳送給你的行程。這會導致類似 @code{BrokenPipeError: [Errno 32] Broken pipe} 的例外。要處理這種情況，請將你的進入點包裝成如下的樣子來捕捉這個例外：

@example
import os
import sys

def main():
    try:
        # 模擬大量輸出（你的程式取代此迴圈）
        for x in range(10000):
            print("y")
        # 在這裡清除輸出以強制 SIGPIPE 在這個 try 區塊
        # 中被觸發
        sys.stdout.flush()
    except BrokenPipeError:
        # Python 在退出時清除標準串流；為剩下的輸出重新導向
        # 至 devnull 來避免關閉時的 BrokenPipeError
        devnull = os.open(os.devnull, os.O_WRONLY)
        os.dup2(devnull, sys.stdout.fileno())
        sys.exit(1)  # Python 在 EPIPE 時以錯誤碼 1 退出

if __name__ == '__main__':
    main()
@end example

不要為了避免 @ref{1257,,BrokenPipeError} 而將 @ref{390f,,SIGPIPE} 之處置 (disposition) 設定為 @ref{1ad7,,SIG_DFL}。這樣做會導致你的程式在寫入任何 socket 連線時被中斷而意外退出。

@node 訊號處理程式與例外的說明,,關於 SIGPIPE 的說明,signal --- 設定非同步事件的處理函式
@anchor{library/signal handlers-and-exceptions}@anchor{2596}@anchor{library/signal note-on-signal-handlers-and-exceptions}@anchor{3933}
@subsubsection 訊號處理程式與例外的說明


如果訊號處理程式產生例外，例外會傳送到主執行緒並可能在任何 @ref{4a5,,bytecode} 指令之後發生。最值得注意的是，@ref{bbc,,KeyboardInterrupt} 可能在執行過程中的任何時候出現。大多數 Python 程式碼，包括標準函式庫，都無法避免這種情況，因此 @ref{bbc,,KeyboardInterrupt}（或任何其他由訊號處理程式產生的例外）可能會在罕見的情況下使程式處於預期之外的狀態。

為了說明這個問題，請參考以下程式碼：

@example
class SpamContext:
    def __init__(self):
        self.lock = threading.Lock()

    def __enter__(self):
        # 如果 KeyboardInterrupt 在此發生則一切正常
        self.lock.acquire()
        # 如果 KeyboardInterrupt 在此發生，__exit__ 將不會被呼叫
        ...
        # KeyboardInterrupt 可能在函式回傳之前發生

    def __exit__(self, exc_type, exc_val, exc_tb):
        ...
        self.lock.release()
@end example

對許多程式來說，尤其是那些只想在 @ref{bbc,,KeyboardInterrupt} 時退出的程式，這並不是問題，但是對於複雜或需要高可靠性的應用程式來說，應該避免從訊號處理程式產生例外。它們也應該避免將捕獲 @ref{bbc,,KeyboardInterrupt} 作為一種優雅關閉 (gracefully shutting down) 的方式。相反地，它們應該安裝自己的 @ref{253,,SIGINT} 處理程式。以下是 HTTP 伺服器避免 @ref{bbc,,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 --- 記憶體對映檔案的支援,,signal --- 設定非同步事件的處理函式,網路與行程間通訊
@anchor{library/mmap doc}@anchor{3934}@anchor{library/mmap mmap-memory-mapped-file-support}@anchor{3935}@anchor{library/mmap module-mmap}@anchor{94}@anchor{library/mmap translation-repo}@anchor{3936}
@subsection @code{mmap} --- 記憶體對映檔案的支援


@geindex module; mmap


__________________________________________________________________


@c include for modules that don't work on WASM

@ref{2006,,可用性}: not WASI.

此模組在 WebAssembly 平台上不起作用或無法使用。更多資訊請參閱 @ref{1a99,,WebAssembly 平台}。

Memory-mapped file objects behave like both @ref{343,,bytearray} and like
@ref{13c4,,file objects}.  You can use mmap objects in most places
where @ref{343,,bytearray} are expected; for example, you can use the @ref{be,,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{514,,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{2b7e,,fileno()} method to obtain the correct value for the
`fileno' parameter.  Otherwise, you can open the file using the
@ref{f8d,,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{2b99,,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{198,,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 版的變更: 新增 @code{ACCESS_DEFAULT} 常數。


To map anonymous memory, -1 should be passed as the fileno along with the length.

@geindex mmap (mmap 中的類別)
@anchor{library/mmap mmap mmap}@anchor{514}
@deffn {類別} mmap.mmap (fileno, length, tagname=None, access=ACCESS_DEFAULT, offset=0)

`(Windows version)' Maps `length' bytes from the file specified by the
file handle `fileno', and creates a mmap object.  If `length' is larger
than the current size of the file, the file is extended to contain `length'
bytes.  If `length' is @code{0}, the maximum length of the map is the current
size of the file, except that if the file is empty Windows raises an
exception (you cannot create an empty mapping on Windows).

`tagname', if specified and not @code{None}, is a string giving a tag name for
the mapping.  Windows allows you to have many different mappings against
the same file.  If you specify the name of an existing tag, that tag is
opened, otherwise a new tag of this name is created.  If this parameter is
omitted or @code{None}, the mapping is created without a name.  Avoiding the
use of the `tagname' parameter will assist in keeping your code portable
between Unix and Windows.

`offset' may be specified as a non-negative integer offset. mmap references
will be relative to the offset from the beginning of the file. `offset'
defaults to 0.  `offset' must be a multiple of the @code{ALLOCATIONGRANULARITY}.

引發一個附帶引數 @code{fileno}、@code{length}、@code{access}、@code{offset} 的@ref{1b70,,稽核事件} @code{mmap.__new__}。
@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{514,,mmap} is called.

`flags' specifies the nature of the mapping. @ref{3937,,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{3938,,MAP_SHARED} creates a
mapping that's shared with all other processes mapping the same areas of
the file.  The default value is @ref{3938,,MAP_SHARED}. Some systems have
additional possible flags with the full list specified in
@ref{3939,,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{393a,,size()} and @ref{393b,,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{514,,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{514,,mmap} can also be used as a context manager in a @ref{186,,with}
statement:

@example
import mmap

with mmap.mmap(-1, 13) as mm:
    mm.write(b"Hello world!")
@end example


在 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:  # 在子行程中
    mm.seek(0)
    print(mm.readline())

    mm.close()
@end example

引發一個附帶引數 @code{fileno}、@code{length}、@code{access}、@code{offset} 的@ref{1b70,,稽核事件} @code{mmap.__new__}。

Memory-mapped file objects support the following methods:

@geindex close() (mmap.mmap 的方法)
@anchor{library/mmap mmap mmap close}@anchor{393c}
@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{393d}
@deffn {屬性} closed

若檔案已關閉則回傳 @code{True}。


在 3.2 版被加入.

@end deffn

@geindex find() (mmap.mmap 的方法)
@anchor{library/mmap mmap mmap find}@anchor{393e}
@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{193,,bytes-like object} is now accepted.

@end deffn

@geindex flush() (mmap.mmap 的方法)
@anchor{library/mmap mmap mmap flush}@anchor{c86}
@deffn {方法} flush ()

@deffnx {方法} flush (offset, size, /)

Flushes changes made to the in-memory copy of a file back to disk. Without
use of this call there is no guarantee that changes are written back before
the object is destroyed.  If `offset' and `size' are specified, only
changes to the given range of bytes will be flushed to disk; otherwise, the
whole extent of the mapping is flushed.  `offset' must be a multiple of the
@code{PAGESIZE} or @code{ALLOCATIONGRANULARITY}.

@code{None} is returned to indicate success.  An exception is raised when the
call failed.


在 3.8 版的變更: Previously, a nonzero value was returned on success; zero was returned
on error under Windows.  A zero value was returned on success; an
exception was raised on error under Unix.

@end deffn

@geindex madvise() (mmap.mmap 的方法)
@anchor{library/mmap mmap mmap madvise}@anchor{bf2}
@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{393f,,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.


在 3.8 版被加入.

@end deffn

@geindex move() (mmap.mmap 的方法)
@anchor{library/mmap mmap mmap move}@anchor{3940}
@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{198,,TypeError} exception.
@end deffn

@geindex read() (mmap.mmap 的方法)
@anchor{library/mmap mmap mmap read}@anchor{12de}
@deffn {方法} read ([n])

Return a @ref{192,,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{3941}
@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{3942}
@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{393b}
@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{198,,TypeError} exception.
Resizing a map created with `trackfd' set to @code{False},
will raise a @ref{2eb,,ValueError} exception.

`On Windows': Resizing the map will raise an @ref{2c0,,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.


在 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{3943}
@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{193,,bytes-like object} is now accepted.

@end deffn

@geindex seek() (mmap.mmap 的方法)
@anchor{library/mmap mmap mmap seek}@anchor{516}
@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{515}
@deffn {方法} seekable ()

Return whether the file supports seeking, and the return value is always @code{True}.


在 3.13 版被加入.

@end deffn

@geindex size() (mmap.mmap 的方法)
@anchor{library/mmap mmap mmap size}@anchor{393a}
@deffn {方法} size ()

Return the length of the file, which can be larger than the size of the
memory-mapped area.
@end deffn

@geindex tell() (mmap.mmap 的方法)
@anchor{library/mmap mmap mmap tell}@anchor{3944}
@deffn {方法} tell ()

Returns the current position of the file pointer.
@end deffn

@geindex write() (mmap.mmap 的方法)
@anchor{library/mmap mmap mmap write}@anchor{f41}
@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{2eb,,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{198,,TypeError} exception.


在 3.5 版的變更: Writable @ref{193,,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{3945}
@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{198,,TypeError} exception.
@end deffn
@end deffn

@menu
* MADV_* 常數:: 
* MAP_* 常數:: 

@end menu

@node MADV_* 常數,MAP_* 常數,,mmap --- 記憶體對映檔案的支援
@anchor{library/mmap madv-constants}@anchor{3946}@anchor{library/mmap madvise-constants}@anchor{393f}
@subsubsection MADV_* 常數


@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{3947}
@deffn {資料} mmap.MADV_NORMAL
@anchor{library/mmap mmap MADV_RANDOM}@anchor{3948}
@deffnx {資料} mmap.MADV_RANDOM
@anchor{library/mmap mmap MADV_SEQUENTIAL}@anchor{3949}
@deffnx {資料} mmap.MADV_SEQUENTIAL
@anchor{library/mmap mmap MADV_WILLNEED}@anchor{394a}
@deffnx {資料} mmap.MADV_WILLNEED
@anchor{library/mmap mmap MADV_DONTNEED}@anchor{394b}
@deffnx {資料} mmap.MADV_DONTNEED
@anchor{library/mmap mmap MADV_REMOVE}@anchor{394c}
@deffnx {資料} mmap.MADV_REMOVE
@anchor{library/mmap mmap MADV_DONTFORK}@anchor{394d}
@deffnx {資料} mmap.MADV_DONTFORK
@anchor{library/mmap mmap MADV_DOFORK}@anchor{394e}
@deffnx {資料} mmap.MADV_DOFORK
@anchor{library/mmap mmap MADV_HWPOISON}@anchor{394f}
@deffnx {資料} mmap.MADV_HWPOISON
@anchor{library/mmap mmap MADV_MERGEABLE}@anchor{3950}
@deffnx {資料} mmap.MADV_MERGEABLE
@anchor{library/mmap mmap MADV_UNMERGEABLE}@anchor{3951}
@deffnx {資料} mmap.MADV_UNMERGEABLE
@anchor{library/mmap mmap MADV_SOFT_OFFLINE}@anchor{3952}
@deffnx {資料} mmap.MADV_SOFT_OFFLINE
@anchor{library/mmap mmap MADV_HUGEPAGE}@anchor{3953}
@deffnx {資料} mmap.MADV_HUGEPAGE
@anchor{library/mmap mmap MADV_NOHUGEPAGE}@anchor{3954}
@deffnx {資料} mmap.MADV_NOHUGEPAGE
@anchor{library/mmap mmap MADV_DONTDUMP}@anchor{3955}
@deffnx {資料} mmap.MADV_DONTDUMP
@anchor{library/mmap mmap MADV_DODUMP}@anchor{3956}
@deffnx {資料} mmap.MADV_DODUMP
@anchor{library/mmap mmap MADV_FREE}@anchor{3957}
@deffnx {資料} mmap.MADV_FREE
@anchor{library/mmap mmap MADV_NOSYNC}@anchor{3958}
@deffnx {資料} mmap.MADV_NOSYNC
@anchor{library/mmap mmap MADV_AUTOSYNC}@anchor{3959}
@deffnx {資料} mmap.MADV_AUTOSYNC
@anchor{library/mmap mmap MADV_NOCORE}@anchor{395a}
@deffnx {資料} mmap.MADV_NOCORE
@anchor{library/mmap mmap MADV_CORE}@anchor{395b}
@deffnx {資料} mmap.MADV_CORE
@anchor{library/mmap mmap MADV_PROTECT}@anchor{395c}
@deffnx {資料} mmap.MADV_PROTECT
@anchor{library/mmap mmap MADV_FREE_REUSABLE}@anchor{395d}
@deffnx {資料} mmap.MADV_FREE_REUSABLE
@anchor{library/mmap mmap MADV_FREE_REUSE}@anchor{395e}
@deffnx {資料} mmap.MADV_FREE_REUSE

These options can be passed to @ref{bf2,,mmap.madvise()}.  Not every option will
be present on every system.

Availability: Systems with the madvise() system call.


在 3.8 版被加入.

@end deffn

@node MAP_* 常數,,MADV_* 常數,mmap --- 記憶體對映檔案的支援
@anchor{library/mmap id1}@anchor{395f}@anchor{library/mmap map-constants}@anchor{3939}
@subsubsection MAP_* 常數


@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{3938}
@deffn {資料} mmap.MAP_SHARED
@anchor{library/mmap mmap MAP_PRIVATE}@anchor{3937}
@deffnx {資料} mmap.MAP_PRIVATE
@anchor{library/mmap mmap MAP_32BIT}@anchor{196b}
@deffnx {資料} mmap.MAP_32BIT
@anchor{library/mmap mmap MAP_ALIGNED_SUPER}@anchor{1a12}
@deffnx {資料} mmap.MAP_ALIGNED_SUPER
@anchor{library/mmap mmap MAP_ANON}@anchor{3960}
@deffnx {資料} mmap.MAP_ANON
@anchor{library/mmap mmap MAP_ANONYMOUS}@anchor{3961}
@deffnx {資料} mmap.MAP_ANONYMOUS
@anchor{library/mmap mmap MAP_CONCEAL}@anchor{1a13}
@deffnx {資料} mmap.MAP_CONCEAL
@anchor{library/mmap mmap MAP_DENYWRITE}@anchor{3962}
@deffnx {資料} mmap.MAP_DENYWRITE
@anchor{library/mmap mmap MAP_EXECUTABLE}@anchor{3963}
@deffnx {資料} mmap.MAP_EXECUTABLE
@anchor{library/mmap mmap MAP_HASSEMAPHORE}@anchor{1966}
@deffnx {資料} mmap.MAP_HASSEMAPHORE
@anchor{library/mmap mmap MAP_JIT}@anchor{1968}
@deffnx {資料} mmap.MAP_JIT
@anchor{library/mmap mmap MAP_NOCACHE}@anchor{1967}
@deffnx {資料} mmap.MAP_NOCACHE
@anchor{library/mmap mmap MAP_NOEXTEND}@anchor{1965}
@deffnx {資料} mmap.MAP_NOEXTEND
@anchor{library/mmap mmap MAP_NORESERVE}@anchor{1964}
@deffnx {資料} mmap.MAP_NORESERVE
@anchor{library/mmap mmap MAP_POPULATE}@anchor{1bfd}
@deffnx {資料} mmap.MAP_POPULATE
@anchor{library/mmap mmap MAP_RESILIENT_CODESIGN}@anchor{1969}
@deffnx {資料} mmap.MAP_RESILIENT_CODESIGN
@anchor{library/mmap mmap MAP_RESILIENT_MEDIA}@anchor{196a}
@deffnx {資料} mmap.MAP_RESILIENT_MEDIA
@anchor{library/mmap mmap MAP_STACK}@anchor{3964}
@deffnx {資料} mmap.MAP_STACK
@anchor{library/mmap mmap MAP_TPRO}@anchor{196e}
@deffnx {資料} mmap.MAP_TPRO
@anchor{library/mmap mmap MAP_TRANSLATED_ALLOW_EXECUTE}@anchor{196c}
@deffnx {資料} mmap.MAP_TRANSLATED_ALLOW_EXECUTE
@anchor{library/mmap mmap MAP_UNIX03}@anchor{196d}
@deffnx {資料} mmap.MAP_UNIX03

These are the various flags that can be passed to @ref{514,,mmap.mmap()}.  @ref{1a12,,MAP_ALIGNED_SUPER}
is only available at FreeBSD and @ref{1a13,,MAP_CONCEAL} is only available at OpenBSD.  Note
that some options might not be present on some systems.


在 3.10 版的變更: 新增 @ref{1bfd,,MAP_POPULATE} 常數。



在 3.11 版被加入: 新增 @ref{3964,,MAP_STACK} 常數。



在 3.12 版被加入: 新增 @ref{1a12,,MAP_ALIGNED_SUPER} 和 @ref{1a13,,MAP_CONCEAL} 常數。



在 3.13 版被加入: Added @ref{196b,,MAP_32BIT}, @ref{1966,,MAP_HASSEMAPHORE}, @ref{1968,,MAP_JIT},
@ref{1967,,MAP_NOCACHE}, @ref{1965,,MAP_NOEXTEND}, @ref{1964,,MAP_NORESERVE},
@ref{1969,,MAP_RESILIENT_CODESIGN}, @ref{196a,,MAP_RESILIENT_MEDIA},
@ref{196e,,MAP_TPRO}, @ref{196c,,MAP_TRANSLATED_ALLOW_EXECUTE}, and
@ref{196d,,MAP_UNIX03} constants.

@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 網際網路資料處理,結構化標記處理工具,網路與行程間通訊,Python 標準函式庫 Standard Library
@anchor{library/netdata doc}@anchor{3965}@anchor{library/netdata internet-data-handling}@anchor{3966}@anchor{library/netdata netdata}@anchor{3967}@anchor{library/netdata translation-repo}@anchor{3968}
@section 網際網路資料處理


本章描述了支援網際網路上處理常用資料格式的模組。

@menu
* email: email --- 郵件和 MIME 處理套件. 郵件和 MIME 處理套件
* json: json --- JSON 編碼器與解碼器. JSON 編碼器與解碼器
* mailbox: mailbox --- 以各種格式操作郵件信箱. 以各種格式操作郵件信箱
* mimetypes: mimetypes --- 將檔案名稱對映到 MIME 類型. 將檔案名稱對映到 MIME 類型
* base64: base64 --- Base16、Base32、Base64、Base85 資料編碼. Base16、Base32、Base64、Base85 資料編碼
* binascii: binascii --- 在二進位制和 ASCII 之間轉換. 在二進位制和 ASCII 之間轉換
* quopri: quopri --- 編碼和解碼 MIME 可列印字元資料. 編碼和解碼 MIME 可列印字元資料

@end menu

@node email --- 郵件和 MIME 處理套件,json --- JSON 編碼器與解碼器,,網際網路資料處理
@anchor{library/email doc}@anchor{3969}@anchor{library/email email-an-email-and-mime-handling-package}@anchor{396a}@anchor{library/email module-email}@anchor{3f}
@subsection @code{email} --- 郵件和 MIME 處理套件


@geindex module; email

`原始碼：'Lib/email/__init__.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/email/__init__.py}


__________________________________________________________________


The @ref{3f,,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{cf,,smtplib}.  The @ref{3f,,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{48,,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{57a,,EmailMessage}
API.

The other two major components of the package are the @ref{52,,parser} and
the @ref{44,,generator}.  The parser takes the serialized version of an
email message (a stream of bytes) and converts it into a tree of
@ref{57a,,EmailMessage} objects.  The generator takes an
@ref{57a,,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{53,,policy} module.  Every
@ref{57a,,EmailMessage}, every @ref{44,,generator}, and every
@ref{52,,parser} has an associated @ref{53,,policy} object that
controls its behavior.  Usually an application only needs to specify the policy
when an @ref{57a,,EmailMessage} is created, either by directly
instantiating an @ref{57a,,EmailMessage}  to create a new email,
or by parsing an input stream using a @ref{52,,parser}.  But the policy can
be changed when the message is serialized using a @ref{44,,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 @ref{3f,,email} package.
We start with the @ref{48,,message} object model, which is the primary
interface an application will use, and follow that with the
@ref{52,,parser} and @ref{44,,generator} components.  Then we cover the
@ref{53,,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{52,,parser} may
detect.  Then we cover the @ref{46,,headerregistry} and the
@ref{41,,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{57b,,Message}
class, cover the legacy @ref{e92,,compat32} API that deals much more
directly with the details of how email messages are represented.  The
@ref{e92,,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{e92,,compat32} API for backward
compatibility reasons.


在 3.6 版的變更: Docs reorganized and rewritten to promote the new
@ref{57a,,EmailMessage}/@ref{12b8,,EmailPolicy}
API.


Contents of the @ref{3f,,email} package documentation:

@menu
* email.message：表示電子郵件訊息: email message：表示電子郵件訊息. 
* email.parser：剖析電子郵件訊息: email parser：剖析電子郵件訊息. 
* email.generator：產生 MIME 文件: email generator：產生 MIME 文件. 
* email.policy; Policy Objects: email policy Policy Objects. 
* email.errors：例外和缺陷類別: email errors：例外和缺陷類別. 
* email.headerregistry：自訂標頭物件: email headerregistry：自訂標頭物件. 
* email.contentmanager：管理 MIME 內容: email contentmanager：管理 MIME 內容. 
* email：範例:: 
* email.message.Message; Representing an email message using the compat32 API: email message Message Representing an email message using the compat32 API. 
* email.mime：從頭開始建立電子郵件和 MIME 物件: email mime：從頭開始建立電子郵件和 MIME 物件. 
* email.header：國際化標頭: email header：國際化標頭. 
* email.charset：字元集合的表示: email charset：字元集合的表示. 
* email.encoders：編碼器: email encoders：編碼器. 
* email.utils：雜項工具: email utils：雜項工具. 
* email.iterators：疊代器: email iterators：疊代器. 

@end menu

@node email message：表示電子郵件訊息,email parser：剖析電子郵件訊息,,email --- 郵件和 MIME 處理套件
@anchor{library/email message doc}@anchor{396b}@anchor{library/email message email-message-representing-an-email-message}@anchor{396c}@anchor{library/email message module-email message}@anchor{48}
@subsubsection @code{email.message}：表示電子郵件訊息


@geindex module; email.message

`原始碼：'Lib/email/message.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/email/message.py}


__________________________________________________________________



在 3.6 版被加入: @footnote{
Originally added in 3.4 as a @ref{123d,,provisional module}.  Docs for legacy message class moved to
@ref{396d,,email.message.Message; Representing an email message using the compat32 API}.
}


The central class in the @ref{3f,,email} package is the @ref{57a,,EmailMessage}
class, imported from the @ref{48,,email.message} module.  It is the base class for
the @ref{3f,,email} object model.  @ref{57a,,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{57a,,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{57a,,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{57a,,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{57a}
@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{396e,,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{53,,policy} documentation.

@geindex as_string() (email.message.EmailMessage 的方法)
@anchor{library/email message email message EmailMessage as_string}@anchor{396f}
@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{57b,,Message} class `maxheaderlen' is
accepted, but defaults to @code{None}, which means that by default the line
length is controlled by the
@ref{3970,,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{13cf,,Generator}.

Flattening the message may trigger changes to the @ref{57a,,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{13cf,,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{ff4,,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{3971}
@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{396f,,as_string()}.

@end deffn

@geindex as_bytes() (email.message.EmailMessage 的方法)
@anchor{library/email message email message EmailMessage as_bytes}@anchor{3972}
@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{13d0,,BytesGenerator}.

Flattening the message may trigger changes to the @ref{57a,,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{13d0,,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{3973}
@deffn {方法} __bytes__ ()

Equivalent to @ref{3972,,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{3974}
@deffn {方法} is_multipart ()

Return @code{True} if the message's payload is a list of
sub-@ref{57a,,EmailMessage} objects, otherwise return @code{False}.  When
@ref{3974,,is_multipart()} returns @code{False}, the payload should be a string
object (which might be a CTE encoded binary payload).  Note that
@ref{3974,,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
@ref{57a,,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{3975}
@deffn {方法} set_unixfrom (unixfrom)

Set the message's envelope header to `unixfrom', which should be a
string.  (See @ref{3976,,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{3977}
@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{3978,,keys()}, but in an @ref{57a,,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{3979}
@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{397a}
@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{397b}
@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{5df,,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{397c,,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{397d,,email.headerregistry.BaseHeader}.
@end deffn

@geindex __setitem__() (email.message.EmailMessage 的方法)
@anchor{library/email message email message EmailMessage __setitem__}@anchor{397e}
@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{53,,policy} defines certain headers to be unique (as the standard
policies do), this method may raise a @ref{2eb,,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{397f}
@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{3978}
@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{3980}
@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{3981}
@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{3982}
@deffn {方法} get (name, failobj=None)

Return the value of the named header field.  This is identical to
@ref{582,,__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{397c}
@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{3983}
@deffn {方法} add_header (_name, _value, **_params)

Extended header setting.  This method is similar to @ref{397e,,__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}.

以下是個範例：

@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{3984}
@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{5df,,KeyError}.
@end deffn

@geindex get_content_type() (email.message.EmailMessage 的方法)
@anchor{library/email message email message EmailMessage get_content_type}@anchor{3985}
@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{3986,,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,
@ref{3985,,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{3987}
@deffn {方法} get_content_maintype ()

Return the message's main content type.  This is the @code{maintype}
part of the string returned by @ref{3985,,get_content_type()}.
@end deffn

@geindex get_content_subtype() (email.message.EmailMessage 的方法)
@anchor{library/email message email message EmailMessage get_content_subtype}@anchor{3988}
@deffn {方法} get_content_subtype ()

Return the message's sub-content type.  This is the @code{subtype}
part of the string returned by @ref{3985,,get_content_type()}.
@end deffn

@geindex get_default_type() (email.message.EmailMessage 的方法)
@anchor{library/email message email message EmailMessage get_default_type}@anchor{3986}
@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{3989}
@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{398a}
@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 @ref{57a,,EmailMessage} objects is
deprecated.

Note that existing parameter values of headers may be accessed through
the @ref{398b,,params} attribute of the
header value (for example, @code{msg['Content-Type'].params['charset']}).


在 3.4 版的變更: 新增 @code{replace} 關鍵字。

@end deffn

@geindex del_param() (email.message.EmailMessage 的方法)
@anchor{library/email message email message EmailMessage del_param}@anchor{398c}
@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 @ref{57a,,EmailMessage} objects is
deprecated.
@end deffn

@geindex get_filename() (email.message.EmailMessage 的方法)
@anchor{library/email message email message EmailMessage get_filename}@anchor{398d}
@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{398e,,email.utils.unquote()}.
@end deffn

@geindex get_boundary() (email.message.EmailMessage 的方法)
@anchor{library/email message email message EmailMessage get_boundary}@anchor{398f}
@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{398e,,email.utils.unquote()}.
@end deffn

@geindex set_boundary() (email.message.EmailMessage 的方法)
@anchor{library/email message email message EmailMessage set_boundary}@anchor{3990}
@deffn {方法} set_boundary (boundary)

Set the @code{boundary} parameter of the @code{Content-Type} header to
`boundary'.  @ref{3990,,set_boundary()} will always quote `boundary' if
necessary.  A @ref{3991,,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{3983,,add_header()}, because @ref{3990,,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{3992}
@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{3993}
@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{3994}
@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{3995,,is_multipart()}.

@end deffn

@geindex get_content_disposition() (email.message.EmailMessage 的方法)
@anchor{library/email message email message EmailMessage get_content_disposition}@anchor{3996}
@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}.


在 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{3997}
@deffn {方法} walk ()

The @ref{3997,,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 @ref{3997,,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{3974,,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{3998}
@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{3999}
@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{399a}
@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{3997,,walk()}.)
@end deffn

@geindex get_content() (email.message.EmailMessage 的方法)
@anchor{library/email message email message EmailMessage get_content}@anchor{399b}
@deffn {方法} get_content (*args, content_manager=None, **kw)

Call the @ref{399c,,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{53,,policy}.
@end deffn

@geindex set_content() (email.message.EmailMessage 的方法)
@anchor{library/email message email message EmailMessage set_content}@anchor{1b5f}
@deffn {方法} set_content (*args, content_manager=None, **kw)

Call the @ref{399d,,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{53,,policy}.
@end deffn

@geindex make_related() (email.message.EmailMessage 的方法)
@anchor{library/email message email message EmailMessage make_related}@anchor{399e}
@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{399f}
@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{39a0}
@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{39a1}
@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{1b5f,,set_content()} method,
and @ref{39a2,,attach()} it to the @code{multipart}.  If
the message is a non-@code{multipart}, call @ref{399e,,make_related()} and then
proceed as above.  If the message is any other type of @code{multipart},
raise a @ref{198,,TypeError}. If `content_manager' is not specified, use
the @code{content_manager} specified by the current @ref{53,,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{39a3}
@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{1b5f,,set_content()} method, and
@ref{39a2,,attach()} it to the @code{multipart}.  If the
message is a non-@code{multipart} or @code{multipart/related}, call
@ref{399f,,make_alternative()} and then proceed as above.  If the message is
any other type of @code{multipart}, raise a @ref{198,,TypeError}. If
`content_manager' is not specified, use the @code{content_manager} specified
by the current @ref{53,,policy}.
@end deffn

@geindex add_attachment() (email.message.EmailMessage 的方法)
@anchor{library/email message email message EmailMessage add_attachment}@anchor{39a4}
@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{1b5f,,set_content()} method, and
@ref{39a2,,attach()} it to the @code{multipart}.  If the
message is a non-@code{multipart}, @code{multipart/related}, or
@code{multipart/alternative}, call @ref{39a0,,make_mixed()} and then proceed as
above. If `content_manager' is not specified, use the @code{content_manager}
specified by the current @ref{53,,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{39a5}
@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{39a6}
@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

@ref{57a,,EmailMessage} objects have the following instance attributes:

@geindex preamble (email.message.EmailMessage 的屬性)
@anchor{library/email message email message EmailMessage preamble}@anchor{39a7}
@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{139e,,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{13cf,,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{52,,email.parser} and
@ref{44,,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{39a8}
@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{39a7,,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{39a9}
@deffn {屬性} defects

The `defects' attribute contains a list of all the problems found when
parsing this message.  See @ref{43,,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{1135}
@deffn {類別} email.message.MIMEPart (policy=default)

This class represents a subpart of a MIME message.  It is identical to
@ref{57a,,EmailMessage}, except that no @code{MIME-Version} headers are
added when @ref{1b5f,,set_content()} is called, since sub-parts do
not need their own @code{MIME-Version} headers.
@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 email parser：剖析電子郵件訊息,email generator：產生 MIME 文件,email message：表示電子郵件訊息,email --- 郵件和 MIME 處理套件
@anchor{library/email parser doc}@anchor{39aa}@anchor{library/email parser email-parser-parsing-email-messages}@anchor{39ab}@anchor{library/email parser module-email parser}@anchor{52}@anchor{library/email parser translation-repo}@anchor{39ac}
@subsubsection @code{email.parser}：剖析電子郵件訊息


@geindex module; email.parser

`原始碼：'Lib/email/parser.py@footnote{https://github.com/python/cpython/tree/3.14/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{57a,,EmailMessage}
object, adding headers using the dictionary interface, and adding payload(s)
using @ref{1b5f,,set_content()} and related methods, or
they can be created by parsing a serialized representation of the email
message.

The @ref{3f,,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{57a,,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{3974,,is_multipart()}
method, and the subparts can be accessed via the payload manipulation methods,
such as @ref{3998,,get_body()},
@ref{399a,,iter_parts()}, and
@ref{3997,,walk()}.

There are actually two parser interfaces available for use, the @ref{139e,,Parser}
API and the incremental @ref{39ad,,FeedParser} API.  The @ref{139e,,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.  @ref{39ad,,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
@ref{39ad,,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{3f,,email} package's bundled parser and the
@ref{57a,,EmailMessage} class is embodied in the @ref{12b4,,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：剖析電子郵件訊息
@anchor{library/email parser feedparser-api}@anchor{39ae}
@subsubsection FeedParser API


The @ref{13cc,,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 @ref{13cc,,BytesFeedParser} can of
course be used to parse an email message fully contained in a @ref{193,,bytes-like object}, string, or file, but the @ref{13cd,,BytesParser} API may be more
convenient for such use cases.  The semantics and results of the two parser
APIs are identical.

The @ref{13cc,,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 @ref{13cc,,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{39a9,,defects} attribute with a list of any
problems it found in a message.  See the @ref{43,,email.errors} module for the
list of defects that it can find.

Here is the API for the @ref{13cc,,BytesFeedParser}:

@geindex BytesFeedParser (email.parser 中的類別)
@anchor{library/email parser email parser BytesFeedParser}@anchor{13cc}
@deffn {類別} email.parser.BytesFeedParser (_factory=None, *, policy=policy.compat32)

Create a @ref{13cc,,BytesFeedParser} instance.  Optional `_factory' is a
no-argument callable; if not specified use the
@ref{e91,,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{12b5,,compat32} policy, which maintains backward
compatibility with the Python 3.2 version of the email package and provides
@ref{57b,,Message} as the default factory.  All other policies
provide @ref{57a,,EmailMessage} as the default `_factory'. For
more information on what else `policy' controls, see the
@ref{53,,policy} documentation.

Note: `The policy keyword should always be specified'; The default will
change to @ref{396e,,email.policy.default} in a future version of Python.


在 3.2 版被加入.



在 3.3 版的變更: 新增 `policy' 關鍵字。



在 3.6 版的變更: `_factory' defaults to the policy @code{message_factory}.


@geindex feed() (email.parser.BytesFeedParser 的方法)
@anchor{library/email parser email parser BytesFeedParser feed}@anchor{39af}
@deffn {方法} feed (data)

Feed the parser some more data.  `data' should be a @ref{193,,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{39b0}
@deffn {方法} close ()

Complete the parsing of all previously fed data and return the root
message object.  It is undefined what happens if @ref{39af,,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{39ad}
@deffn {類別} email.parser.FeedParser (_factory=None, *, policy=policy.compat32)

Works like @ref{13cc,,BytesFeedParser} except that the input to the
@ref{39af,,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{ff4,,utf8} is
@code{True}, no binary attachments.


在 3.3 版的變更: 新增 `policy' 關鍵字。

@end deffn

@node Parser API,Additional notes,FeedParser API,email parser：剖析電子郵件訊息
@anchor{library/email parser parser-api}@anchor{39b1}
@subsubsection Parser API


The @ref{13cd,,BytesParser} class, imported from the @ref{52,,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{193,,bytes-like object} or file.  The
@ref{52,,email.parser} module also provides @ref{139e,,Parser} for parsing strings,
and header-only parsers, @ref{12bc,,BytesHeaderParser} and
@ref{12bd,,HeaderParser}, which can be used if you're only interested in the
headers of the message.  @ref{12bc,,BytesHeaderParser} and @ref{12bd,,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{13cd}
@deffn {類別} email.parser.BytesParser (_class=None, *, policy=policy.compat32)

Create a @ref{13cd,,BytesParser} instance.  The `_class' and `policy'
arguments have the same meaning and semantics as the `_factory'
and `policy' arguments of @ref{13cc,,BytesFeedParser}.

Note: `The policy keyword should always be specified'; The default will
change to @ref{396e,,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{39b2}
@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{152a,,readline()} and the @code{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{ff4,,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{39b3}
@deffn {方法} parsebytes (bytes, headersonly=False)

Similar to the @ref{39b2,,parse()} method, except it takes a @ref{193,,bytes-like object} instead of a file-like object.  Calling this method on a
@ref{193,,bytes-like object} is equivalent to wrapping `bytes' in a
@ref{109f,,BytesIO} instance first and calling @ref{39b2,,parse()}.

Optional `headersonly' is as with the @ref{39b2,,parse()} method.
@end deffn


在 3.2 版被加入.

@end deffn

@geindex BytesHeaderParser (email.parser 中的類別)
@anchor{library/email parser email parser BytesHeaderParser}@anchor{12bc}
@deffn {類別} email.parser.BytesHeaderParser (_class=None, *, policy=policy.compat32)

Exactly like @ref{13cd,,BytesParser}, except that `headersonly'
defaults to @code{True}.


在 3.3 版被加入.

@end deffn

@geindex Parser (email.parser 中的類別)
@anchor{library/email parser email parser Parser}@anchor{139e}
@deffn {類別} email.parser.Parser (_class=None, *, policy=policy.compat32)

This class is parallel to @ref{13cd,,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{39b4}
@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{1f6d,,readline()} and the
@ref{1f33,,read()} methods on file-like objects.

Other than the text mode requirement, this method operates like
@ref{39b2,,BytesParser.parse()}.
@end deffn

@geindex parsestr() (email.parser.Parser 的方法)
@anchor{library/email parser email parser Parser parsestr}@anchor{39b5}
@deffn {方法} parsestr (text, headersonly=False)

Similar to the @ref{39b4,,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{1124,,StringIO} instance first
and calling @ref{39b4,,parse()}.

Optional `headersonly' is as with the @ref{39b4,,parse()} method.
@end deffn
@end deffn

@geindex HeaderParser (email.parser 中的類別)
@anchor{library/email parser email parser HeaderParser}@anchor{12bd}
@deffn {類別} email.parser.HeaderParser (_class=None, *, policy=policy.compat32)

Exactly like @ref{139e,,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{3f,,email} package namespace.

@geindex message_from_bytes() (於 email 模組中)
@anchor{library/email parser email message_from_bytes}@anchor{13ca}
@deffn {函式} email.message_from_bytes (s, _class=None, *, policy=policy.compat32)

Return a message object structure from a @ref{193,,bytes-like object}.  This is
equivalent to @code{BytesParser().parsebytes(s)}.  Optional `_class' and
`policy' are interpreted as with the @ref{13cd,,BytesParser} class
constructor.


在 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{13cb}
@deffn {函式} email.message_from_binary_file (fp, _class=None, *, policy=policy.compat32)

Return a message object structure tree from an open binary @ref{13c4,,file object}.  This is equivalent to @code{BytesParser().parse(fp)}.  `_class' and
`policy' are interpreted as with the @ref{13cd,,BytesParser} class
constructor.


在 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{39b6}
@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{139e,,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{39b7}
@deffn {函式} email.message_from_file (fp, _class=None, *, policy=policy.compat32)

Return a message object structure tree from an open @ref{13c4,,file object}.
This is equivalent to @code{Parser().parse(fp)}.  `_class' and `policy' are
interpreted as with the @ref{139e,,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{13ca,,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：剖析電子郵件訊息
@anchor{library/email parser additional-notes}@anchor{39b8}
@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{3974,,is_multipart()}, and
@ref{399a,,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{3974,,is_multipart()}, and
@ref{399a,,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{3974,,is_multipart()} method will return @code{True}.
The single element yielded by @ref{399a,,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{3974,,is_multipart()} method may return @code{False}.
If such messages were parsed with the @ref{39ad,,FeedParser},
they will have an instance of the
@ref{39b9,,MultipartInvariantViolationDefect} class in their
`defects' attribute list.  See @ref{43,,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：產生 MIME 文件,email policy Policy Objects,email parser：剖析電子郵件訊息,email --- 郵件和 MIME 處理套件
@anchor{library/email generator doc}@anchor{39ba}@anchor{library/email generator email-generator-generating-mime-documents}@anchor{39bb}@anchor{library/email generator module-email generator}@anchor{44}@anchor{library/email generator translation-repo}@anchor{39bc}
@subsubsection @code{email.generator}：產生 MIME 文件


@geindex module; email.generator

`原始碼：'Lib/email/generator.py@footnote{https://github.com/python/cpython/tree/3.14/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{1054,,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{52,,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{53,,policy} is used for both.  That
is, parsing the serialized byte stream via the
@ref{13cd,,BytesParser} class and then regenerating the serialized
byte stream using @ref{13d0,,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{53,,email.policy} settings calling for
automatic adjustments (for example,
@ref{39bd,,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{57a,,EmailMessage} constructed by program may result in
changes to the @ref{57a,,EmailMessage} object as defaults are
filled in.)

The @ref{13cf,,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{13cf,,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{13d0}
@deffn {類別} email.generator.BytesGenerator (outfp, mangle_from_=None, maxheaderlen=None, *, policy=None)

Return a @ref{13d0,,BytesGenerator} object that will write any message provided
to the @ref{39be,,flatten()} method, or any surrogateescape encoded text provided
to the @ref{39bf,,write()} method, to the @ref{28ad,,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{ff2,,mangle_from_}
setting of the `policy' (which is @code{True} for the
@ref{e92,,compat32} policy and @code{False} for all others).
`mangle_from_' is intended for use when messages are stored in Unix mbox
format (see @ref{8f,,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{57b,,Message} or @ref{57a,,EmailMessage}
object passed to @code{flatten} to control the message generation.  See
@ref{53,,email.policy} for details on what `policy' controls.


在 3.2 版被加入.



在 3.3 版的變更: 新增關鍵字 `policy'。



在 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{39be}
@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 @ref{13d0,,BytesGenerator}
instance was created.

If the @ref{53,,policy} option @ref{39c0,,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{8f,,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{39c1}
@deffn {方法} clone (fp)

Return an independent clone of this @ref{13d0,,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{39bf}
@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
@ref{13d0,,BytesGenerator}'s constructor.
@end deffn
@end deffn

As a convenience, @ref{57a,,EmailMessage} provides the methods
@ref{3972,,as_bytes()} and @code{bytes(aMessage)} (a.k.a.
@ref{3973,,__bytes__()}), which simplify the generation of
a serialized binary representation of a message object.  For more detail, see
@ref{48,,email.message}.

Because strings cannot represent binary data, the @ref{13cf,,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 @ref{13cf,,Generator} serializing to an I/O stream
that is not "8 bit clean".  In other words, most applications will want
to be using @ref{13d0,,BytesGenerator}, and not @ref{13cf,,Generator}.

@geindex Generator (email.generator 中的類別)
@anchor{library/email generator email generator Generator}@anchor{13cf}
@deffn {類別} email.generator.Generator (outfp, mangle_from_=None, maxheaderlen=None, *, policy=None)

Return a @ref{13cf,,Generator} object that will write any message provided
to the @ref{39c2,,flatten()} method, or any text provided to the @ref{39c3,,write()}
method, to the @ref{28ad,,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{ff2,,mangle_from_}
setting of the `policy' (which is @code{True} for the
@ref{e92,,compat32} policy and @code{False} for all others).
`mangle_from_' is intended for use when messages are stored in Unix mbox
format (see @ref{8f,,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{57b,,Message} or @ref{57a,,EmailMessage}
object passed to @code{flatten} to control the message generation.  See
@ref{53,,email.policy} for details on what `policy' controls.


在 3.3 版的變更: 新增關鍵字 `policy'。



在 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{39c2}
@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 @ref{13cf,,Generator}
instance was created.

If the @ref{53,,policy} option @ref{39c0,,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{8f,,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{39c4}
@deffn {方法} clone (fp)

Return an independent clone of this @ref{13cf,,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{39c3}
@deffn {方法} write (s)

Write `s' to the `write' method of the `outfp' passed to the
@ref{13cf,,Generator}'s constructor.  This provides just enough file-like
API for @ref{13cf,,Generator} instances to be used in the @ref{1170,,print()}
function.
@end deffn
@end deffn

As a convenience, @ref{57a,,EmailMessage} provides the methods
@ref{396f,,as_string()} and @code{str(aMessage)} (a.k.a.
@ref{3971,,__str__()}), which simplify the generation of
a formatted string representation of a message object.  For more detail, see
@ref{48,,email.message}.

The @ref{44,,email.generator} module also provides a derived class,
@ref{e90,,DecodedGenerator}, which is like the @ref{13cf,,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{e90}
@deffn {類別} email.generator.DecodedGenerator (outfp, mangle_from_=None, maxheaderlen=None, fmt=None, *, policy=None)

Act like @ref{13cf,,Generator}, except that for any subpart of the message
passed to @ref{39c2,,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{13cf,,Generator} base class.
@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 email policy Policy Objects,email errors：例外和缺陷類別,email generator：產生 MIME 文件,email --- 郵件和 MIME 處理套件
@anchor{library/email policy doc}@anchor{39c5}@anchor{library/email policy email-policy-policy-objects}@anchor{39c6}@anchor{library/email policy module-email policy}@anchor{53}@anchor{library/email policy translation-repo}@anchor{39c7}
@subsubsection @code{email.policy}: Policy Objects


@geindex module; email.policy


在 3.3 版被加入.


`原始碼：'Lib/email/policy.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/email/policy.py}


__________________________________________________________________


The @ref{3f,,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{12b4,,Policy} object encapsulates a set of attributes and methods that
control the behavior of various components of the email package during use.
@ref{12b4,,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{52,,parser} classes and the related convenience functions, and for
the @ref{57b,,Message} class, this is the @ref{12b5,,Compat32}
policy, via its corresponding pre-defined instance @ref{e92,,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{57a,,EmailMessage} is the @ref{12b8,,EmailPolicy} policy, via
its pre-defined instance @ref{396e,,default}.

When a @ref{57b,,Message} or @ref{57a,,EmailMessage}
object is created, it acquires a policy.  If the message is created by a
@ref{52,,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{44,,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{52,,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
@ref{52,,parser} module.

The first part of this documentation covers the features of @ref{12b4,,Policy}, an
@ref{13b7,,abstract base class} that defines the features that are common to all
policy objects, including @ref{e92,,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{12b8,,EmailPolicy} and @ref{12b5,,Compat32}, which implement
the hooks that provide the standard behavior and the backward compatible
behavior and features, respectively.

@ref{12b4,,Policy} instances are immutable, but they can be cloned, accepting the
same keyword arguments as the class constructor and returning a new
@ref{12b4,,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{13d0,,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{1132,,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{12b4}
@deffn {類別} email.policy.Policy (**kw)

This is the @ref{13b7,,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{12b6,,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{3970}
@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{87e,,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{39c8}
@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{39c0}
@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{39c9,,fold_binary()} and @ref{ff4,,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{39ca}
@deffn {屬性} raise_on_defect

If @ref{e02,,True}, any defects encountered will be raised as errors.  If
@ref{d23,,False} (the default), defects will be passed to the
@ref{39cb,,register_defect()} method.
@end deffn

@geindex mangle_from_ (email.policy.Policy 的屬性)
@anchor{library/email policy email policy Policy mangle_from_}@anchor{ff2}
@deffn {屬性} mangle_from_

If @ref{e02,,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{d23,,False}.


在 3.5 版被加入.

@end deffn

@geindex message_factory (email.policy.Policy 的屬性)
@anchor{library/email policy email policy Policy message_factory}@anchor{e91}
@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{57b,,Message} is used.


在 3.6 版被加入.

@end deffn

@geindex verify_generated_headers (email.policy.Policy 的屬性)
@anchor{library/email policy email policy Policy verify_generated_headers}@anchor{4ed}
@deffn {屬性} verify_generated_headers

If @code{True} (the default), the generator will raise
@ref{39cc,,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{12b5,,Compat32} policy.
For backwards compatible, but unsafe, behavior, it must be set to
@code{False} explicitly.


在 3.13 版被加入.

@end deffn

The following @ref{12b4,,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{12b6}
@deffn {方法} clone (**kw)

Return a new @ref{12b4,,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 @ref{12b4,,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{39cd}
@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{39ce,,MessageDefect}.

The default implementation checks the @ref{39ca,,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{39cb,,register_defect()}.
@end deffn

@geindex register_defect() (email.policy.Policy 的方法)
@anchor{library/email policy email policy Policy register_defect}@anchor{39cb}
@deffn {方法} register_defect (obj, defect)

Register a `defect' on `obj'.  In the email package, `defect' will always
be a subclass of @ref{39ce,,MessageDefect}.

The default implementation calls the @code{append} method of the @code{defects}
attribute of `obj'.  When the email package calls @ref{39cd,,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{39cf}
@deffn {方法} header_max_count (name)

Return the maximum allowed number of headers named `name'.

Called when a header is added to an @ref{57a,,EmailMessage}
or @ref{57b,,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{2eb,,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{39d0}
@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{39d1}
@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{39d2}
@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{39d3}
@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{39c8,,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{39c9}
@deffn {方法} fold_binary (name, value)

The same as @ref{39d3,,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{12b8}
@deffn {類別} email.policy.EmailPolicy (**kw)

This concrete @ref{12b4,,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{e91,,message_factory}
attribute is @ref{57a,,EmailMessage}.

In addition to the settable attributes listed above that apply to all
policies, this policy adds the following additional attributes:


在 3.6 版被加入: @footnote{
Originally added in 3.3 as a @ref{123d,,provisional feature}.
}


@geindex utf8 (email.policy.EmailPolicy 的屬性)
@anchor{library/email policy email policy EmailPolicy utf8}@anchor{ff4}
@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 "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}).
@end deffn

@geindex refold_source (email.policy.EmailPolicy 的屬性)
@anchor{library/email policy email policy EmailPolicy refold_source}@anchor{39bd}
@deffn {屬性} refold_source

If the value for a header in the @code{Message} object originated from a
@ref{52,,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


預設為 @code{long}。
@end deffn

@geindex header_factory (email.policy.EmailPolicy 的屬性)
@anchor{library/email policy email policy EmailPolicy header_factory}@anchor{39d4}
@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{46,,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{1136}
@deffn {屬性} content_manager

An object with at least two methods: get_content and set_content.  When
the @ref{399b,,get_content()} or
@ref{1b5f,,set_content()} method of an
@ref{57a,,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{39d5,,raw_data_manager}.


在 3.4 版被加入.

@end deffn

The class provides the following concrete implementations of the abstract
methods of @ref{12b4,,Policy}:

@geindex header_max_count() (email.policy.EmailPolicy 的方法)
@anchor{library/email policy email policy EmailPolicy header_max_count}@anchor{39d6}
@deffn {方法} header_max_count (name)

Returns the value of the
@ref{39d7,,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{187d}
@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{39d8}
@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{39d9}
@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{1941}
@deffn {方法} fold (name, value)

Header folding is controlled by the @ref{39bd,,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{1457,,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{39da}
@deffn {方法} fold_binary (name, value)

The same as @ref{1941,,fold()} if @ref{39c0,,cte_type} is @code{7bit}, except
that the returned value is bytes.

If @ref{39c0,,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{12b8,,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{396e}
@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{39db}
@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{39dc}
@deffn {資料} email.policy.SMTPUTF8

The same as @code{SMTP} except that @ref{ff4,,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{1055,,smtplib.SMTP.send_message()} method handles this automatically).
@end deffn

@geindex HTTP (於 email.policy 模組中)
@anchor{library/email policy email policy HTTP}@anchor{39dd}
@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{39de}
@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{12b8,,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{57b,,Message} results in that
header being parsed and a header object created.

@item 
Fetching a header value from a @ref{57b,,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{57a,,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{46,,headerregistry}.

@geindex Compat32 (email.policy 中的類別)
@anchor{library/email policy email policy Compat32}@anchor{12b5}
@deffn {類別} email.policy.Compat32 (**kw)

This concrete @ref{12b4,,Policy} is the backward compatibility policy.  It
replicates the behavior of the email package in Python 3.2.  The
@ref{53,,policy} module also defines an instance of this class,
@ref{e92,,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{12b4,,Policy} default:

@geindex mangle_from_ (email.policy.Compat32 的屬性)
@anchor{library/email policy email policy Compat32 mangle_from_}@anchor{39df}
@deffn {屬性} mangle_from_

The default is @code{True}.
@end deffn

The class provides the following concrete implementations of the
abstract methods of @ref{12b4,,Policy}:

@geindex header_source_parse() (email.policy.Compat32 的方法)
@anchor{library/email policy email policy Compat32 header_source_parse}@anchor{187e}
@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{39e0}
@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{39e1}
@deffn {方法} header_fetch_parse (name, value)

If the value contains binary data, it is converted into a
@ref{1b60,,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{39e2}
@deffn {方法} fold (name, value)

Headers are folded using the @ref{1b60,,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{39e3}
@deffn {方法} fold_binary (name, value)

Headers are folded using the @ref{1b60,,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{e92}
@deffn {資料} email.policy.compat32

An instance of @ref{12b5,,Compat32}, providing  backward compatibility with the
behavior of the email package in Python 3.2.
@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 email errors：例外和缺陷類別,email headerregistry：自訂標頭物件,email policy Policy Objects,email --- 郵件和 MIME 處理套件
@anchor{library/email errors doc}@anchor{39e4}@anchor{library/email errors email-errors-exception-and-defect-classes}@anchor{39e5}@anchor{library/email errors module-email errors}@anchor{43}@anchor{library/email errors translation-repo}@anchor{39e6}
@subsubsection @code{email.errors}：例外和缺陷類別


@geindex module; email.errors

`原始碼：'Lib/email/errors.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/email/errors.py}


__________________________________________________________________


The following exception classes are defined in the @ref{43,,email.errors} module:

@geindex MessageError
@anchor{library/email errors email errors MessageError}@anchor{39e7}
@deffn {例外} email.errors.MessageError

This is the base class for all exceptions that the @ref{3f,,email} package can
raise.  It is derived from the standard @ref{bc4,,Exception} class and defines no
additional methods.
@end deffn

@geindex MessageParseError
@anchor{library/email errors email errors MessageParseError}@anchor{39e8}
@deffn {例外} email.errors.MessageParseError

This is the base class for exceptions raised by the
@ref{139e,,Parser} class.  It is derived from
@ref{39e7,,MessageError}.  This class is also used internally by the parser used
by @ref{46,,headerregistry}.
@end deffn

@geindex HeaderParseError
@anchor{library/email errors email errors HeaderParseError}@anchor{3991}
@deffn {例外} email.errors.HeaderParseError

Raised under some error conditions when parsing the 
@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html} headers of a
message, this class is derived from @ref{39e8,,MessageParseError}.  The
@ref{3990,,set_boundary()} method will raise this
error if the content type is unknown when the method is called.
@ref{1b60,,Header} may raise this error for certain base64
decoding errors, and when an attempt is made to create a header that appears
to contain an embedded header (that is, there is what is supposed to be a
continuation line that has no leading whitespace and looks like a header).
@end deffn

@geindex BoundaryError
@anchor{library/email errors email errors BoundaryError}@anchor{39e9}
@deffn {例外} email.errors.BoundaryError

Deprecated and no longer used.
@end deffn

@geindex MultipartConversionError
@anchor{library/email errors email errors MultipartConversionError}@anchor{39ea}
@deffn {例外} email.errors.MultipartConversionError

Raised if the @ref{39a2,,attach()} method is called
on an instance of a class derived from
@ref{39eb,,MIMENonMultipart} (e.g.
@ref{39ec,,MIMEImage}).
@ref{39ea,,MultipartConversionError} multiply
inherits from @ref{39e7,,MessageError} and the built-in @ref{198,,TypeError}.
@end deffn

@geindex HeaderWriteError
@anchor{library/email errors email errors HeaderWriteError}@anchor{39cc}
@deffn {例外} email.errors.HeaderWriteError

Raised when an error occurs when the @ref{44,,generator} outputs
headers.
@end deffn

@geindex MessageDefect
@anchor{library/email errors email errors MessageDefect}@anchor{39ce}
@deffn {例外} email.errors.MessageDefect

This is the base class for all defects found when parsing email messages.
It is derived from @ref{2eb,,ValueError}.
@end deffn

@geindex HeaderDefect
@anchor{library/email errors email errors HeaderDefect}@anchor{39ed}
@deffn {例外} email.errors.HeaderDefect

This is the base class for all defects found when parsing email headers.
It is derived from @ref{39ce,,MessageDefect}.
@end deffn

Here is the list of the defects that the @ref{39ad,,FeedParser}
can find while parsing messages.  Note that the defects are added to the message
where the problem was found, so for example, if a message nested inside a
@code{multipart/alternative} had a malformed header, that nested message
object would have a defect, but the containing messages would not.

All defect classes are subclassed from @ref{39ce,,email.errors.MessageDefect}.

@geindex NoBoundaryInMultipartDefect
@anchor{library/email errors email errors NoBoundaryInMultipartDefect}@anchor{39ee}
@deffn {例外} email.errors.NoBoundaryInMultipartDefect

A message claimed to be a multipart, but had no @code{boundary}
parameter.
@end deffn

@geindex StartBoundaryNotFoundDefect
@anchor{library/email errors email errors StartBoundaryNotFoundDefect}@anchor{39ef}
@deffn {例外} email.errors.StartBoundaryNotFoundDefect

The start boundary claimed in the @code{Content-Type} header was
never found.
@end deffn

@geindex CloseBoundaryNotFoundDefect
@anchor{library/email errors email errors CloseBoundaryNotFoundDefect}@anchor{39f0}
@deffn {例外} email.errors.CloseBoundaryNotFoundDefect

A start boundary was found, but no corresponding close boundary was ever
found.


在 3.3 版被加入.

@end deffn

@geindex FirstHeaderLineIsContinuationDefect
@anchor{library/email errors email errors FirstHeaderLineIsContinuationDefect}@anchor{39f1}
@deffn {例外} email.errors.FirstHeaderLineIsContinuationDefect

The message had a continuation line as its first header line.
@end deffn

@geindex MisplacedEnvelopeHeaderDefect
@anchor{library/email errors email errors MisplacedEnvelopeHeaderDefect}@anchor{39f2}
@deffn {例外} email.errors.MisplacedEnvelopeHeaderDefect

A "Unix From" header was found in the middle of a header block.
@end deffn

@geindex MissingHeaderBodySeparatorDefect
@anchor{library/email errors email errors MissingHeaderBodySeparatorDefect}@anchor{39f3}
@deffn {例外} email.errors.MissingHeaderBodySeparatorDefect

A line was found while parsing headers that had no leading white space but
contained no ':'.  Parsing continues assuming that the line represents the
first line of the body.


在 3.3 版被加入.

@end deffn

@geindex MalformedHeaderDefect
@anchor{library/email errors email errors MalformedHeaderDefect}@anchor{39f4}
@deffn {例外} email.errors.MalformedHeaderDefect

A header was found that was missing a colon, or was otherwise malformed.


在 3.3 版之後被棄用: This defect has not been used for several Python versions.

@end deffn

@geindex MultipartInvariantViolationDefect
@anchor{library/email errors email errors MultipartInvariantViolationDefect}@anchor{39b9}
@deffn {例外} email.errors.MultipartInvariantViolationDefect

A message claimed to be a @code{multipart}, but no subparts were found.
Note that when a message has this defect, its
@ref{3995,,is_multipart()} method may return @code{False}
even though its content type claims to be @code{multipart}.
@end deffn

@geindex InvalidBase64PaddingDefect
@anchor{library/email errors email errors InvalidBase64PaddingDefect}@anchor{39f5}
@deffn {例外} email.errors.InvalidBase64PaddingDefect

When decoding a block of base64 encoded bytes, the padding was not correct.
Enough padding is added to perform the decode, but the resulting decoded
bytes may be invalid.
@end deffn

@geindex InvalidBase64CharactersDefect
@anchor{library/email errors email errors InvalidBase64CharactersDefect}@anchor{39f6}
@deffn {例外} email.errors.InvalidBase64CharactersDefect

When decoding a block of base64 encoded bytes, characters outside the base64
alphabet were encountered.  The characters are ignored, but the resulting
decoded bytes may be invalid.
@end deffn

@geindex InvalidBase64LengthDefect
@anchor{library/email errors email errors InvalidBase64LengthDefect}@anchor{39f7}
@deffn {例外} email.errors.InvalidBase64LengthDefect

When decoding a block of base64 encoded bytes, the number of non-padding
base64 characters was invalid (1 more than a multiple of 4).  The encoded
block was kept as-is.
@end deffn

@geindex InvalidDateDefect
@anchor{library/email errors email errors InvalidDateDefect}@anchor{39f8}
@deffn {例外} email.errors.InvalidDateDefect

When decoding an invalid or unparsable date field.  The original value is
kept as-is.
@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：自訂標頭物件,email contentmanager：管理 MIME 內容,email errors：例外和缺陷類別,email --- 郵件和 MIME 處理套件
@anchor{library/email headerregistry doc}@anchor{39f9}@anchor{library/email headerregistry email-headerregistry-custom-header-objects}@anchor{39fa}@anchor{library/email headerregistry module-email headerregistry}@anchor{46}@anchor{library/email headerregistry translation-repo}@anchor{39fb}
@subsubsection @code{email.headerregistry}：自訂標頭物件


@geindex module; email.headerregistry

`原始碼：'Lib/email/headerregistry.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/email/headerregistry.py}


__________________________________________________________________



在 3.6 版被加入: @footnote{
Originally added in 3.3 as a @ref{123d,,provisional module}
}


Headers are represented by customized subclasses of @ref{169,,str}.  The
particular class used to represent a given header is determined by the
@ref{39d4,,header_factory} of the @ref{53,,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{12b8,,EmailPolicy}, all headers are produced by
@ref{39fc,,HeaderRegistry} and have @ref{397d,,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{39fd,,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 @ref{39fc,,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{39fc,,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{397d}
@deffn {類別} email.headerregistry.BaseHeader (name, value)

`name' and `value' are passed to @code{BaseHeader} from the
@ref{39d4,,header_factory} call.  The string value of
any header object is the `value' fully decoded to unicode.

這個基底類別定義了以下唯讀屬性：

@geindex name (email.headerregistry.BaseHeader 的屬性)
@anchor{library/email headerregistry email headerregistry BaseHeader name}@anchor{39fe}
@deffn {屬性} name

The name of the header (the portion of the field before the ':').  This
is exactly the value passed in the
@ref{39d4,,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{39ff}
@deffn {屬性} defects

A tuple of @ref{39ed,,HeaderDefect} instances reporting any
RFC compliance problems found during parsing.  The email package tries to
be complete about detecting compliance issues.  See the @ref{43,,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{39d7}
@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{3a00}
@deffn {方法} fold (*, policy)

Return a string containing @ref{39c8,,linesep}
characters as required to correctly fold the header according to
`policy'.  A @ref{39c0,,cte_type} of @code{8bit} will be
treated as if it were @code{7bit}, since headers may not contain arbitrary
binary data.  If @ref{ff4,,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{489,,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{39fd}
@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{3a01}
@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{3a02}
@deffn {屬性} datetime

If the header value can be recognized as a valid date of one form or
another, this attribute will contain a @ref{4dd,,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{3a02,,datetime} will be a
naive @ref{4dd,,datetime}.  If a specific timezone offset is
found (including @code{+0000}), then @ref{3a02,,datetime} will contain an aware
@code{datetime} that uses @ref{12c0,,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{4dd,,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{2f6,,localtime()} function from the
@ref{54,,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{3a03}
@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{3a04}
@deffn {屬性} groups

A tuple of @ref{3a05,,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{3a06,,display_name} is @code{None}.
@end deffn

@geindex addresses (email.headerregistry.AddressHeader 的屬性)
@anchor{library/email headerregistry email headerregistry AddressHeader addresses}@anchor{3a07}
@deffn {屬性} addresses

A tuple of @ref{3a08,,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{56,,idna} encoded domain names are also decoded to
unicode.  The @code{decoded} value is set by @ref{24fe,,joining} the
@ref{169,,str} value of the elements of the @code{groups} attribute with @code{',
'}.

A list of @ref{3a08,,Address} and @ref{3a05,,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{3a09}
@deffn {類別} email.headerregistry.SingleAddressHeader

A subclass of @ref{3a03,,AddressHeader} that adds one
additional attribute:

@geindex address (email.headerregistry.SingleAddressHeader 的屬性)
@anchor{library/email headerregistry email headerregistry SingleAddressHeader address}@anchor{3a0a}
@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{53,,policy}), accessing this attribute
will result in a @ref{2eb,,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{39d7,,max_count} is set to 1.

@geindex MIMEVersionHeader (email.headerregistry 中的類別)
@anchor{library/email headerregistry email headerregistry MIMEVersionHeader}@anchor{3a0b}
@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{3a0c}
@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{3a0d}
@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{3a0e}
@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{3a0f}
@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{398b}
@deffn {屬性} params

A dictionary mapping parameter names to parameter values.
@end deffn
@end deffn

@geindex ContentTypeHeader (email.headerregistry 中的類別)
@anchor{library/email headerregistry email headerregistry ContentTypeHeader}@anchor{3a10}
@deffn {類別} email.headerregistry.ContentTypeHeader

A @ref{3a0f,,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{3a11}
@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{3a12}
@deffn {屬性} maintype
@end deffn

@geindex subtype (email.headerregistry.ContentTypeHeader 的屬性)
@anchor{library/email headerregistry email headerregistry ContentTypeHeader subtype}@anchor{3a13}
@deffn {屬性} subtype
@end deffn
@end deffn

@geindex ContentDispositionHeader (email.headerregistry 中的類別)
@anchor{library/email headerregistry email headerregistry ContentDispositionHeader}@anchor{3a14}
@deffn {類別} email.headerregistry.ContentDispositionHeader

A @ref{3a0f,,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{3a15}
@deffn {屬性} content_disposition

@code{inline} and @code{attachment} are the only valid values in common use.
@end deffn
@end deffn

@geindex ContentTransferEncoding (email.headerregistry 中的類別)
@anchor{library/email headerregistry email headerregistry ContentTransferEncoding}@anchor{3a16}
@deffn {類別} email.headerregistry.ContentTransferEncoding

Handles the @code{Content-Transfer-Encoding} header.

@geindex cte (email.headerregistry.ContentTransferEncoding 的屬性)
@anchor{library/email headerregistry email headerregistry ContentTransferEncoding cte}@anchor{3a17}
@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{39fc}
@deffn {類別} email.headerregistry.HeaderRegistry (base_class=BaseHeader, default_class=UnstructuredHeader, use_default_map=True)

This is the factory used by @ref{12b8,,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{16a0,,__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} 有以下方法：

@geindex map_to_type() (email.headerregistry.HeaderRegistry 的方法)
@anchor{library/email headerregistry email headerregistry HeaderRegistry map_to_type}@anchor{3a18}
@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{3a19}
@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{3a1a}
@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{3a08}
@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

或是：

@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{3a1b}
@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{3a1c}
@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{3a1d}
@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{3a1e}
@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{3a1f}
@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{3a05}
@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{3a06}
@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{3a20}
@deffn {屬性} addresses

A possibly empty tuple of @ref{3a08,,Address} objects representing the
addresses in the group.
@end deffn

@geindex __str__() (email.headerregistry.Group 的方法)
@anchor{library/email headerregistry email headerregistry Group __str__}@anchor{3a21}
@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

@subsubheading 註解


@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：管理 MIME 內容,email：範例,email headerregistry：自訂標頭物件,email --- 郵件和 MIME 處理套件
@anchor{library/email contentmanager doc}@anchor{3a22}@anchor{library/email contentmanager email-contentmanager-managing-mime-content}@anchor{3a23}@anchor{library/email contentmanager module-email contentmanager}@anchor{41}@anchor{library/email contentmanager translation-repo}@anchor{3a24}
@subsubsection @code{email.contentmanager}：管理 MIME 內容


@geindex module; email.contentmanager

`原始碼：'Lib/email/contentmanager.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/email/contentmanager.py}


__________________________________________________________________



在 3.6 版被加入: @footnote{
Originally added in 3.4 as a @ref{123d,,provisional module}
}


@geindex ContentManager (email.contentmanager 中的類別)
@anchor{library/email contentmanager email contentmanager ContentManager}@anchor{3a25}
@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{399c}
@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{5df,,KeyError} for the
full MIME type.
@end deffn

@geindex set_content() (email.contentmanager.ContentManager 的方法)
@anchor{library/email contentmanager email contentmanager ContentManager set_content}@anchor{399d}
@deffn {方法} set_content (msg, obj, *args, **kw)

If the @code{maintype} is @code{multipart}, raise a @ref{198,,TypeError}; otherwise
look up a handler function based on the type of `obj' (see next
paragraph), call @ref{39a6,,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{2225,,qualname} (@code{typ.__qualname__})

@item 
the type's @ref{169f,,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{184a,,MRO} (@ref{2229,,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{5df,,KeyError} for the fully
qualified name of the type.

Also add a @code{MIME-Version} header if one is not present (see
also @ref{1135,,MIMEPart}).
@end deffn

@geindex add_get_handler() (email.contentmanager.ContentManager 的方法)
@anchor{library/email contentmanager email contentmanager ContentManager add_get_handler}@anchor{3a26}
@deffn {方法} add_get_handler (key, handler)

Record the function `handler' as the handler for `key'.  For the possible
values of `key', see @ref{3a27,,get_content()}.
@end deffn

@geindex add_set_handler() (email.contentmanager.ContentManager 的方法)
@anchor{library/email contentmanager email contentmanager ContentManager add_set_handler}@anchor{3a28}
@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{3a29,,set_content()}.  For the possible
values of `typekey', see @ref{3a29,,set_content()}.
@end deffn
@end deffn

@menu
* Content Manager Instances:: 

@end menu

@node Content Manager Instances,,,email contentmanager：管理 MIME 內容
@anchor{library/email contentmanager content-manager-instances}@anchor{3a2a}
@subsubsection Content Manager Instances


Currently the email package provides only one concrete content manager,
@ref{39d5,,raw_data_manager}, although more may be added in the future.
@ref{39d5,,raw_data_manager} is the
@ref{1136,,content_manager} provided by
@ref{12b8,,EmailPolicy} and its derivatives.

@geindex raw_data_manager (於 email.contentmanager 模組中)
@anchor{library/email contentmanager email contentmanager raw_data_manager}@anchor{39d5}
@deffn {資料} email.contentmanager.raw_data_manager

This content manager provides only a minimum interface beyond that provided
by @ref{57b,,Message} itself:  it deals only with text, raw
byte strings, and @ref{57b,,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{3a27}
@deffn {方法} email.contentmanager.get_content (msg, errors='replace')

Return the payload of the part as either a string (for @code{text} parts), an
@ref{57a,,EmailMessage} object (for @code{message/rfc822}
parts), or a @code{bytes} object (for all other non-multipart types).  Raise
a @ref{5df,,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{3a29}
@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{198,,TypeError} if they are not specified.

@item 
For @ref{57a,,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{2eb,,ValueError}.


@itemize *

@item 
For @code{str} objects, if `cte' is not set use heuristics to
determine the most compact encoding.  Prior to encoding,
@ref{1457,,str.splitlines()} is used to normalize all line boundaries,
ensuring that each line of the payload is terminated by the
current policy's @ref{39c8,,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{57a,,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{13d0,,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

@subsubheading 註解


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node email：範例,email message Message Representing an email message using the compat32 API,email contentmanager：管理 MIME 內容,email --- 郵件和 MIME 處理套件
@anchor{library/email examples doc}@anchor{3a2b}@anchor{library/email examples email-examples}@anchor{1137}@anchor{library/email examples id1}@anchor{3a2c}@anchor{library/email examples translation-repo}@anchor{3a2d}
@subsubsection @code{email}：範例


Here are a few examples of how to use the @ref{3f,,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{52,,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

@subsubheading 註解


@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：從頭開始建立電子郵件和 MIME 物件,email：範例,email --- 郵件和 MIME 處理套件
@anchor{library/email compat32-message doc}@anchor{3a2e}@anchor{library/email compat32-message compat32-message}@anchor{396d}@anchor{library/email compat32-message email-message-message-representing-an-email-message-using-the-compat32-api}@anchor{3a2f}@anchor{library/email compat32-message translation-repo}@anchor{3a30}
@subsubsection @code{email.message.Message}: Representing an email message using the @code{compat32} API


The @ref{57b,,Message} class is very similar to the
@ref{57a,,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
@ref{57a,,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{57b,,Message})
policy @ref{12b5,,Compat32}.  If you are going to use another policy,
you should be using the @ref{57a,,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{57b,,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{57b,,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
@ref{57b,,Message} objects, for MIME container documents (e.g.
@code{multipart/*} and @code{message/rfc822}).

Here are the methods of the @ref{57b,,Message} class:

@geindex Message (email.message 中的類別)
@anchor{library/email compat32-message email message Message}@anchor{57b}
@deffn {類別} email.message.Message (policy=compat32)

If `policy' is specified (it must be an instance of a @ref{53,,policy}
class) use the rules it specifies to update and serialize the representation
of the message.  If `policy' is not set, use the @ref{12b5,,compat32} policy, which maintains backward compatibility with
the Python 3.2 version of the email package.  For more information see the
@ref{53,,policy} documentation.


在 3.3 版的變更: 新增 `policy' 關鍵字引數。


@geindex as_string() (email.message.Message 的方法)
@anchor{library/email compat32-message email message Message as_string}@anchor{1131}
@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 @ref{57b,,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{13cf,,Generator} instance and use its
@ref{39c2,,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{1132,,as_bytes()} and
@ref{13d0,,BytesGenerator}.)


在 3.4 版的變更: 新增 `policy' 關鍵字引數。

@end deffn

@geindex __str__() (email.message.Message 的方法)
@anchor{library/email compat32-message email message Message __str__}@anchor{3a31}
@deffn {方法} __str__ ()

Equivalent to @ref{1131,,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{1132}
@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 @ref{57b,,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{13d0,,BytesGenerator} instance and use its
@ref{39be,,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


在 3.4 版被加入.

@end deffn

@geindex __bytes__() (email.message.Message 的方法)
@anchor{library/email compat32-message email message Message __bytes__}@anchor{1133}
@deffn {方法} __bytes__ ()

Equivalent to @ref{1132,,as_bytes()}.  Allows @code{bytes(msg)} to produce a
bytes object containing the formatted message.


在 3.4 版被加入.

@end deffn

@geindex is_multipart() (email.message.Message 的方法)
@anchor{library/email compat32-message email message Message is_multipart}@anchor{3995}
@deffn {方法} is_multipart ()

Return @code{True} if the message's payload is a list of
sub-@ref{57b,,Message} objects, otherwise return @code{False}.  When
@ref{3995,,is_multipart()} returns @code{False}, the payload should be a string
object (which might be a CTE encoded binary payload).  (Note that
@ref{3995,,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
@ref{57b,,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{3a32}
@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{3a33}
@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{39a2}
@deffn {方法} attach (payload)

Add the given `payload' to the current payload, which must be @code{None} or
a list of @ref{57b,,Message} objects before the call. After the call, the
payload will always be a list of @ref{57b,,Message} objects.  If you want to
set the payload to a scalar object (e.g. a string), use
@ref{3a34,,set_payload()} instead.

This is a legacy method.  On the
@ref{57a,,EmailMessage} class its functionality is
replaced by @ref{1b5f,,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{13ce}
@deffn {方法} get_payload (i=None, decode=False)

Return the current payload, which will be a list of
@ref{57b,,Message} objects when @ref{3995,,is_multipart()} is @code{True}, or a
string when @ref{3995,,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', @ref{13ce,,get_payload()} will return the `i'-th
element of the payload, counting from zero, if @ref{3995,,is_multipart()} is
@code{True}.  An @ref{1729,,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.  @ref{3995,,is_multipart()} is @code{False}) and `i' is
given, a @ref{198,,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{39f5,,InvalidBase64PaddingDefect} or
@ref{39f6,,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{57a,,EmailMessage} class its functionality is
replaced by @ref{399b,,get_content()} and
@ref{399a,,iter_parts()}.
@end deffn

@geindex set_payload() (email.message.Message 的方法)
@anchor{library/email compat32-message email message Message set_payload}@anchor{3a34}
@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{3a35,,set_charset()} for details.

This is a legacy method.  On the
@ref{57a,,EmailMessage} class its functionality is
replaced by @ref{1b5f,,set_content()}.
@end deffn

@geindex set_charset() (email.message.Message 的方法)
@anchor{library/email compat32-message email message Message set_charset}@anchor{3a35}
@deffn {方法} set_charset (charset)

Set the character set of the payload to `charset', which can either be a
@ref{ff6,,Charset} instance (see @ref{40,,email.charset}), a
string naming a character set, or @code{None}.  If it is a string, it will
be converted to a @ref{ff6,,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{198,,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{ff6,,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{57a,,EmailMessage} class its functionality is
replaced by the `charset' parameter of the
@ref{1b5f,,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{3a36}
@deffn {方法} get_charset ()

Return the @ref{ff6,,Charset} instance associated with the
message's payload.

This is a legacy method.  On the
@ref{57a,,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{3a37,,keys()}, but in a @ref{57b,,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{1b60,,Header} objects with
a charset of @code{unknown-8bit}.

@geindex __len__() (email.message.Message 的方法)
@anchor{library/email compat32-message email message Message __len__}@anchor{3a38}
@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{1a3a}
@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{3a39}
@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{5df,,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{3a3a,,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{17f8}
@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{3a3b}
@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{3a37}
@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{3a3c}
@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{3a3d}
@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{3a3e}
@deffn {方法} get (name, failobj=None)

Return the value of the named header field.  This is identical to
@ref{582,,__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{3a3a}
@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{17f9}
@deffn {方法} add_header (_name, _value, **_params)

Extended header setting.  This method is similar to @ref{17f8,,__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}.

以下是個範例：

@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{3a3f}
@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{5df,,KeyError} is raised.
@end deffn

@geindex get_content_type() (email.message.Message 的方法)
@anchor{library/email compat32-message email message Message get_content_type}@anchor{3a40}
@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{3a41,,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, @ref{3a40,,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{3a42}
@deffn {方法} get_content_maintype ()

Return the message's main content type.  This is the @code{maintype}
part of the string returned by @ref{3a40,,get_content_type()}.
@end deffn

@geindex get_content_subtype() (email.message.Message 的方法)
@anchor{library/email compat32-message email message Message get_content_subtype}@anchor{3a43}
@deffn {方法} get_content_subtype ()

Return the message's sub-content type.  This is the @code{subtype}
part of the string returned by @ref{3a40,,get_content_type()}.
@end deffn

@geindex get_default_type() (email.message.Message 的方法)
@anchor{library/email compat32-message email message Message get_default_type}@anchor{3a41}
@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{3a44}
@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{3a45}
@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{3a46,,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{57a,,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{3a46}
@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{3a47,,email.utils.collapse_rfc2231_value()}, passing in the return value
from @ref{3a46,,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{57a,,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{1134}
@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} 關鍵字。

@end deffn

@geindex del_param() (email.message.Message 的方法)
@anchor{library/email compat32-message email message Message del_param}@anchor{3a48}
@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{3a49}
@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{2eb,,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{57a,,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{3a4a}
@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{398e,,email.utils.unquote()}.
@end deffn

@geindex get_boundary() (email.message.Message 的方法)
@anchor{library/email compat32-message email message Message get_boundary}@anchor{3a4b}
@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{398e,,email.utils.unquote()}.
@end deffn

@geindex set_boundary() (email.message.Message 的方法)
@anchor{library/email compat32-message email message Message set_boundary}@anchor{3a4c}
@deffn {方法} set_boundary (boundary)

Set the @code{boundary} parameter of the @code{Content-Type} header to
`boundary'.  @ref{3a4c,,set_boundary()} will always quote `boundary' if
necessary.  A @ref{3991,,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{17f9,,add_header()}, because @ref{3a4c,,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{3a4d}
@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{3a36,,get_charset()} which returns the
@ref{ff6,,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{3a4e}
@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{ff3}
@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}.


在 3.5 版被加入.

@end deffn

@geindex walk() (email.message.Message 的方法)
@anchor{library/email compat32-message email message Message walk}@anchor{3a4f}
@deffn {方法} walk ()

The @ref{3a4f,,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 @ref{3a4f,,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{3995,,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

@ref{57b,,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{3a50}
@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{139e,,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{13cf,,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{52,,email.parser} and
@ref{44,,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{3a51}
@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{13cf,,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{3a52}
@deffn {屬性} defects

The `defects' attribute contains a list of all the problems found when
parsing this message.  See @ref{43,,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：從頭開始建立電子郵件和 MIME 物件,email header：國際化標頭,email message Message Representing an email message using the compat32 API,email --- 郵件和 MIME 處理套件
@anchor{library/email mime doc}@anchor{3a53}@anchor{library/email mime email-mime-creating-email-and-mime-objects-from-scratch}@anchor{3a54}@anchor{library/email mime module-email mime}@anchor{49}@anchor{library/email mime translation-repo}@anchor{3a55}
@subsubsection @code{email.mime}：從頭開始建立電子郵件和 MIME 物件


@geindex module; email.mime

`原始碼：'Lib/email/mime/@footnote{https://github.com/python/cpython/tree/3.14/Lib/email/mime/}


__________________________________________________________________


This module is part of the legacy (@code{Compat32}) email API.  Its functionality
is partially replaced by the @ref{41,,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{57b,,Message} objects by hand.  In fact, you can also take an
existing structure and add new @ref{57b,,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{57b,,Message}
instances, adding attachments and all the appropriate headers manually.  For MIME
messages though, the @ref{3f,,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{4c}@anchor{library/email mime email mime base MIMEBase}@anchor{3a56}
@deffn {類別} email.mime.base.MIMEBase (_maintype, _subtype, *, policy=compat32, **_params)

模組：@ref{4c,,email.mime.base}

This is the base class for all the MIME-specific subclasses of
@ref{57b,,Message}.  Ordinarily you won't create instances
specifically of @ref{3a56,,MIMEBase}, although you could.  @ref{3a56,,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{17f9,,Message.add_header}.

If `policy' is specified, (defaults to the
@ref{12b5,,compat32} policy) it will be passed to
@ref{57b,,Message}.

The @ref{3a56,,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 版的變更: 新增僅限關鍵字參數 `policy'。

@end deffn

@geindex module; email.mime.nonmultipart

@geindex MIMENonMultipart (email.mime.nonmultipart 中的類別)
@anchor{library/email mime module-email mime nonmultipart}@anchor{50}@anchor{library/email mime email mime nonmultipart MIMENonMultipart}@anchor{39eb}
@deffn {類別} email.mime.nonmultipart.MIMENonMultipart

模組：@ref{50,,email.mime.nonmultipart}

A subclass of @ref{3a56,,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{39a2,,attach()} method, which only makes sense for
@code{multipart} messages.  If @ref{39a2,,attach()}
is called, a @ref{39ea,,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{4f}@anchor{library/email mime email mime multipart MIMEMultipart}@anchor{3a57}
@deffn {類別} email.mime.multipart.MIMEMultipart (_subtype='mixed', boundary=None, _subparts=None, *, policy=compat32, **_params)

模組：@ref{4f,,email.mime.multipart}

A subclass of @ref{3a56,,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{39a2,,Message.attach} method.

Optional `policy' argument defaults to @ref{12b5,,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 版的變更: 新增僅限關鍵字參數 `policy'。

@end deffn

@geindex module; email.mime.application

@geindex MIMEApplication (email.mime.application 中的類別)
@anchor{library/email mime module-email mime application}@anchor{4a}@anchor{library/email mime email mime application MIMEApplication}@anchor{3a58}
@deffn {類別} email.mime.application.MIMEApplication (_data, _subtype='octet-stream', _encoder=email.encoders.encode_base64, *, policy=compat32, **_params)

模組：@ref{4a,,email.mime.application}

A subclass of @ref{39eb,,MIMENonMultipart}, the
@ref{3a58,,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 @ref{3a58,,MIMEApplication} instance. It should use
@ref{13ce,,get_payload()} and
@ref{3a34,,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{42,,email.encoders} module for a list of the built-in encoders.

Optional `policy' argument defaults to @ref{12b5,,compat32}.

`_params' are passed straight through to the base class constructor.


在 3.6 版的變更: 新增僅限關鍵字參數 `policy'。

@end deffn

@geindex module; email.mime.audio

@geindex MIMEAudio (email.mime.audio 中的類別)
@anchor{library/email mime module-email mime audio}@anchor{4b}@anchor{library/email mime email mime audio MIMEAudio}@anchor{3a59}
@deffn {類別} email.mime.audio.MIMEAudio (_audiodata, _subtype=None, _encoder=email.encoders.encode_base64, *, policy=compat32, **_params)

模組：@ref{4b,,email.mime.audio}

A subclass of @ref{39eb,,MIMENonMultipart}, the
@ref{3a59,,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{198,,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 @ref{3a59,,MIMEAudio} instance. It should use
@ref{13ce,,get_payload()} and
@ref{3a34,,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{42,,email.encoders} module for a list of the built-in encoders.

Optional `policy' argument defaults to @ref{12b5,,compat32}.

`_params' are passed straight through to the base class constructor.


在 3.6 版的變更: 新增僅限關鍵字參數 `policy'。

@end deffn

@geindex module; email.mime.image

@geindex MIMEImage (email.mime.image 中的類別)
@anchor{library/email mime module-email mime image}@anchor{4d}@anchor{library/email mime email mime image MIMEImage}@anchor{39ec}
@deffn {類別} email.mime.image.MIMEImage (_imagedata, _subtype=None, _encoder=email.encoders.encode_base64, *, policy=compat32, **_params)

模組：@ref{4d,,email.mime.image}

A subclass of @ref{39eb,,MIMENonMultipart}, the
@ref{39ec,,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{198,,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 @ref{39ec,,MIMEImage} instance. It should use
@ref{13ce,,get_payload()} and
@ref{3a34,,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{42,,email.encoders} module for a list of the built-in encoders.

Optional `policy' argument defaults to @ref{12b5,,compat32}.

`_params' are passed straight through to the @ref{3a56,,MIMEBase}
constructor.


在 3.6 版的變更: 新增僅限關鍵字參數 `policy'。

@end deffn

@geindex module; email.mime.message

@geindex MIMEMessage (email.mime.message 中的類別)
@anchor{library/email mime module-email mime message}@anchor{4e}@anchor{library/email mime email mime message MIMEMessage}@anchor{3a5a}
@deffn {類別} email.mime.message.MIMEMessage (_msg, _subtype='rfc822', *, policy=compat32)

模組：@ref{4e,,email.mime.message}

A subclass of @ref{39eb,,MIMENonMultipart}, the
@ref{3a5a,,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{57b,,Message} (or a subclass thereof), otherwise
a @ref{198,,TypeError} is raised.

Optional `_subtype' sets the subtype of the message; it defaults to
@code{rfc822}.

Optional `policy' argument defaults to @ref{12b5,,compat32}.


在 3.6 版的變更: 新增僅限關鍵字參數 `policy'。

@end deffn

@geindex module; email.mime.text

@geindex MIMEText (email.mime.text 中的類別)
@anchor{library/email mime module-email mime text}@anchor{51}@anchor{library/email mime email mime text MIMEText}@anchor{ff5}
@deffn {類別} email.mime.text.MIMEText (_text, _subtype='plain', _charset=None, *, policy=compat32)

模組：@ref{51,,email.mime.text}

A subclass of @ref{39eb,,MIMENonMultipart}, the
@ref{ff5,,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
@ref{39eb,,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{ff6,,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{12b5,,compat32}.


在 3.5 版的變更: `_charset' also accepts @ref{ff6,,Charset} instances.



在 3.6 版的變更: 新增僅限關鍵字參數 `policy'。

@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：國際化標頭,email charset：字元集合的表示,email mime：從頭開始建立電子郵件和 MIME 物件,email --- 郵件和 MIME 處理套件
@anchor{library/email header doc}@anchor{3a5b}@anchor{library/email header email-header-internationalized-headers}@anchor{3a5c}@anchor{library/email header module-email header}@anchor{45}@anchor{library/email header translation-repo}@anchor{3a5d}
@subsubsection @code{email.header}：國際化標頭


@geindex module; email.header

`原始碼：'Lib/email/header.py@footnote{https://github.com/python/cpython/tree/3.14/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{57a,,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{3f,,email} package supports these standards
in its @ref{45,,email.header} and @ref{40,,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{1b60,,Header} class and assign the field in the @ref{57b,,Message}
object to an instance of @ref{1b60,,Header} instead of using a string for the header
value.  Import the @ref{1b60,,Header} class from the @ref{45,,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{1b60,,Header} instance and passing in
the character set that the byte string was encoded in.  When the subsequent
@ref{57b,,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{1b60,,Header} class description:

@geindex Header (email.header 中的類別)
@anchor{library/email header email header Header}@anchor{1b60}
@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{3a5e,,append()} method calls.  `s' may be an instance of @ref{192,,bytes} or
@ref{169,,str}, but see the @ref{3a5e,,append()} documentation for semantics.

Optional `charset' serves two purposes: it has the same meaning as the `charset'
argument to the @ref{3a5e,,append()} method.  It also sets the default character set
for all subsequent @ref{3a5e,,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 @ref{3a5e,,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{3a5e,,append()} method.

@geindex append() (email.header.Header 的方法)
@anchor{library/email header email header Header append}@anchor{3a5e}
@deffn {方法} append (s, charset=None, errors='strict')

Append the string `s' to the MIME header.

Optional `charset', if given, should be a @ref{ff6,,Charset}
instance (see @ref{40,,email.charset}) or the name of a character set, which
will be converted to a @ref{ff6,,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{192,,bytes} or @ref{169,,str}.  If it is an
instance of @ref{192,,bytes}, then `charset' is the encoding of that byte
string, and a @ref{460,,UnicodeError} will be raised if the string cannot be
decoded with that character set.

If `s' is an instance of @ref{169,,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{3a5f}
@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 版的變更: 新增引數 `linesep'。

@end deffn

The @ref{1b60,,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{3a60}
@deffn {方法} __str__ ()

Returns an approximation of the @ref{1b60,,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{3a61}
@deffn {方法} __eq__ (other)

This method allows you to compare two @ref{1b60,,Header} instances for
equality.
@end deffn

@geindex __ne__() (email.header.Header 的方法)
@anchor{library/email header email header Header __ne__}@anchor{3a62}
@deffn {方法} __ne__ (other)

This method allows you to compare two @ref{1b60,,Header} instances for
inequality.
@end deffn
@end deffn

The @ref{45,,email.header} module also provides the following convenient functions.

@geindex decode_header() (於 email.header 模組中)
@anchor{library/email header email header decode_header}@anchor{12b9}
@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{192,,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{169,,str}.
@end enumerate

An @ref{3991,,email.errors.HeaderParseError} may be raised when certain decoding
errors occur (e.g. a base64 decoding exception).

以下為範例：

@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{39fc,,email.headerregistry.HeaderRegistry}.
@end quotation
@end cartouche
@end deffn

@geindex make_header() (於 email.header 模組中)
@anchor{library/email header email header make_header}@anchor{12ba}
@deffn {函式} email.header.make_header (decoded_seq, maxlinelen=None, header_name=None, continuation_ws=' ')

Create a @ref{1b60,,Header} instance from a sequence of pairs as returned by
@ref{12b9,,decode_header()}.

@ref{12b9,,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{1b60,,Header} instance.  Optional `maxlinelen', `header_name', and
`continuation_ws' are as in the @ref{1b60,,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：編碼器,email header：國際化標頭,email --- 郵件和 MIME 處理套件
@anchor{library/email charset doc}@anchor{3a63}@anchor{library/email charset email-charset-representing-character-sets}@anchor{3a64}@anchor{library/email charset module-email charset}@anchor{40}@anchor{library/email charset translation-repo}@anchor{3a65}
@subsubsection @code{email.charset}：字元集合的表示


@geindex module; email.charset

`原始碼：'Lib/email/charset.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/email/charset.py}


__________________________________________________________________


此模組是舊版 (@code{Compat32}) email API的其中一部份，在新版的 API 只有使用別名表。

此章節的其餘內容是模組的原始說明文件

此模組提供一個類別 @ref{ff6,,Charset} 來表示電子郵件訊息中的字元集合和字元集合轉換，也包含字元集合登錄檔 (registry) 和其他許多運用此登錄檔的便捷方法。@ref{ff6,,Charset} 的實例被 @ref{3f,,email} 套件中其他數個模組所使用。

從 @ref{40,,email.charset} 模組中引入此類別

@geindex Charset (email.charset 中的類別)
@anchor{library/email charset email charset Charset}@anchor{ff6}
@deffn {類別} email.charset.Charset (input_charset=DEFAULT_CHARSET)

將字元集合對映到其電子郵件特性 (properties)。

此類別提供有關於電子郵件對特定字元集合的規範資訊。考慮到適用之編解碼器 (codec) 的可用性，它還提供了在字元集合之間進行轉換的便利例行操作 (routine)。給定一個字元集合，它將盡量提供有關如何以符合 RFC (RFC-compliant) 的方式在電子郵件訊息中使用該字元集合的資訊。

在電子郵件標頭 (header) 或內文 (body) 用特定字元集合時必須使用可列印字元編碼 (quoted-printable) 或 base64 來編碼。特定字元集合不允許出現在電子郵件中、必須被徹底轉換。

可選的 `input_charset' 描述如下；`input_charset' 會被強制轉換 (coerced) 為小寫。經過別名標準化 (alias normalize) 後，會進到字元集合登錄檔 (registry) 去查詢此字元集合使用的標頭編碼、內文編碼以及輸出轉換編解碼器。舉例來說，如果 `input_charset' 是 @code{iso-8859-1}，標頭跟內文會以可列印字元編碼並且不需要輸出轉換編解碼器。如果 `input_charset' 是 @code{euc-jp}，標頭則會被編碼成 base64、內文不會被編碼，但輸出文字則會從 @code{euc-jp} 字元集合被轉換成 @code{iso-2022-jp} 字元集合。

@ref{ff6,,Charset} 實例有以下資料屬性：

@geindex input_charset (email.charset.Charset 的屬性)
@anchor{library/email charset email charset Charset input_charset}@anchor{3a66}
@deffn {屬性} input_charset

指定的初始字元集合。通用別名會被轉換成它們的`官方'電子郵件名稱（例如：@code{latin_1} 會被轉換成 @code{iso-8859-1}）。預設為 7 位元 @code{us-ascii}。
@end deffn

@geindex header_encoding (email.charset.Charset 的屬性)
@anchor{library/email charset email charset Charset header_encoding}@anchor{3a67}
@deffn {屬性} header_encoding

如果字元集合在被用於電子郵件標頭前必須被編碼的話，這個屬性會被設為 @code{charset.QP}（表示可列印字元編碼）、@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{3a68}
@deffn {屬性} body_encoding

與 `header_encoding' 相同，但表示郵件訊息內文的編碼，與上述的標頭編碼有可能不同。@code{charset.SHORTEST} 是不允許於 `body_encoding' 使用的。
@end deffn

@geindex output_charset (email.charset.Charset 的屬性)
@anchor{library/email charset email charset Charset output_charset}@anchor{3a69}
@deffn {屬性} output_charset

部分的字元集合在用於電子郵件的標頭或內文前必須先被轉換。如果 `input_charset' 是這些字元集合的其中之一，這個屬性將會包含輸出時轉換成的字元集合名稱。不然這個屬性則為 @code{None}。
@end deffn

@geindex input_codec (email.charset.Charset 的屬性)
@anchor{library/email charset email charset Charset input_codec}@anchor{3a6a}
@deffn {屬性} input_codec

用於將 `input_charset' 轉換成 Unicode 的 Python 編解碼器的名稱。如果不需要轉換編解碼器，這個屬性為 @code{None}。
@end deffn

@geindex output_codec (email.charset.Charset 的屬性)
@anchor{library/email charset email charset Charset output_codec}@anchor{3a6b}
@deffn {屬性} output_codec

用於將 Unicode 轉換成 `output_charset' 的 Python 編解碼器名稱。如果不需要轉換編解碼器，這個屬性將會與 `input_codec' 有相同的值。
@end deffn

@ref{ff6,,Charset} 實例還有以下方法：

@geindex get_body_encoding() (email.charset.Charset 的方法)
@anchor{library/email charset email charset Charset get_body_encoding}@anchor{3a6c}
@deffn {方法} get_body_encoding ()

回傳用於內文編碼的內容傳輸編碼 (content transfer encoding)。

這可以是字串 @code{quoted-printable} 或 @code{base64}，具體取決於所使用的編碼，或者它也可以是一個函式，在這種情況下，你應該使用單個引數呼叫該函式，即正被編碼的 Message 物件。然後函式應將 @code{Content-Transfer-Encoding} 標頭本身設定為任何適當的值。

如果 `body_encoding' 為 @code{QP} 則回傳字串 @code{quoted-printable}，如果 `body_encoding' 為 @code{BASE64} 則回傳字串 @code{base64}，否則回傳字串 @code{7bit} 。
@end deffn

@geindex get_output_charset() (email.charset.Charset 的方法)
@anchor{library/email charset email charset Charset get_output_charset}@anchor{3a6d}
@deffn {方法} get_output_charset ()

回傳輸出字元集合。

如果不為 @code{None} 則這會是 `output_charset' 屬性，否則它是 `input_charset'。
@end deffn

@geindex header_encode() (email.charset.Charset 的方法)
@anchor{library/email charset email charset Charset header_encode}@anchor{3a6e}
@deffn {方法} header_encode (string)

對字串 `string' 進行標頭編碼 (header-encode)。

編碼類型（base64 或可列印字元編碼）將基於 `header_encoding' 屬性。
@end deffn

@geindex header_encode_lines() (email.charset.Charset 的方法)
@anchor{library/email charset email charset Charset header_encode_lines}@anchor{3a6f}
@deffn {方法} header_encode_lines (string, maxlengths)

透過先將 `string' 轉換為位元組來對它進行標頭編碼。

這與 @ref{3a6e,,header_encode()} 類似，只不過字串不會超過由引數 `maxlengths' 給定的最大列長度 (maximum line length)，該引數必須是個疊代器：從此疊代器回傳的每個元素將提供下一個最大列長度。
@end deffn

@geindex body_encode() (email.charset.Charset 的方法)
@anchor{library/email charset email charset Charset body_encode}@anchor{3a70}
@deffn {方法} body_encode (string)

對字串 `string' 進行內文編碼 (body-encode)。

編碼類型（base64 或可列印字元編碼）將基於 `body_encoding' 屬性。
@end deffn

@ref{ff6,,Charset} 類別也提供了許多支援標準操作和內建函式的方法。

@geindex __str__() (email.charset.Charset 的方法)
@anchor{library/email charset email charset Charset __str__}@anchor{3a71}
@deffn {方法} __str__ ()

回傳強制轉換 `input_charset' 為小寫後的字串。@code{__repr__()} 是 @code{__str__()} 的別名。
@end deffn

@geindex __eq__() (email.charset.Charset 的方法)
@anchor{library/email charset email charset Charset __eq__}@anchor{3a72}
@deffn {方法} __eq__ (other)

此方法讓你比較兩個 @ref{ff6,,Charset} 實例的相等性。
@end deffn

@geindex __ne__() (email.charset.Charset 的方法)
@anchor{library/email charset email charset Charset __ne__}@anchor{3a73}
@deffn {方法} __ne__ (other)

此方法讓你比較兩個 @ref{ff6,,Charset} 實例的不相等性。
@end deffn
@end deffn

@ref{40,,email.charset} 模組還提供以下函式，用於將項目新增至全域字元集合、別名和編解碼器登錄檔中：

@geindex add_charset() (於 email.charset 模組中)
@anchor{library/email charset email charset add_charset}@anchor{3a74}
@deffn {函式} email.charset.add_charset (charset, header_enc=None, body_enc=None, output_charset=None)

將字元特性 (properties) 新增至全域登錄檔。

`charset' 是輸入的字元集合，且必須是字元集合的規範名稱 (canonical name)。

可選的 `header_enc' 和 `body_enc' 為 @code{charset.QP}（表示可列印字元編碼）、@code{charset.BASE64}（表示 base64 編碼）、@code{charset.SHORTEST}（表示最短的 base64 或可列印字元編碼）或 @code{None}（表示無編碼）。@code{SHORTEST} 僅在用於 `header_enc' 時有效。預設為 @code{None}，表示無編碼。

可選的 `output_charset' 是輸出應採用的字元集合。當呼叫 @code{Charset.convert()} 方法時，將從輸入字元集合轉換為 Unicode，再轉換為輸出字元集合。預設是以與輸入相同的字元集合輸出。

`input_charset' 和 `output_charset' 都必須在模組的字元集合到編解碼器對映 (character set-to-codec mapping) 中具有 Unicode 編解碼器項目；使用 @ref{3a75,,add_codec()} 來新增模組未知的編解碼器。有關更多資訊請參閱 @ref{1c,,codecs} 模組的文件。

全域字元集合登錄檔保存在模組全域字典 @code{CHARSETS} 中。
@end deffn

@geindex add_alias() (於 email.charset 模組中)
@anchor{library/email charset email charset add_alias}@anchor{3a76}
@deffn {函式} email.charset.add_alias (alias, canonical)

新增字元集合別名。`alias' 是別名，例如 @code{latin-1}。`canonical' 是字元集合的規範名稱，例如 @code{iso-8859-1}。

全域字元集合別名登錄檔保存在模組全域字典 @code{ALIASES} 中。
@end deffn

@geindex add_codec() (於 email.charset 模組中)
@anchor{library/email charset email charset add_codec}@anchor{3a75}
@deffn {函式} email.charset.add_codec (charset, codecname)

新增一個編解碼器，將給定字元集合中的字元與 Unicode 進行對映。

`charset' 是字元集合的規範名稱。`codecname' 是 Python 編解碼器的名稱，適用於 @ref{169,,str} 的 @ref{ac9,,encode()} 方法的第二個引數。
@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：編碼器,email utils：雜項工具,email charset：字元集合的表示,email --- 郵件和 MIME 處理套件
@anchor{library/email encoders doc}@anchor{3a77}@anchor{library/email encoders email-encoders-encoders}@anchor{3a78}@anchor{library/email encoders module-email encoders}@anchor{42}@anchor{library/email encoders translation-repo}@anchor{3a79}
@subsubsection @code{email.encoders}：編碼器


@geindex module; email.encoders

`原始碼：'Lib/email/encoders.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/email/encoders.py}


__________________________________________________________________


此模組是舊版 (@code{Compat32}) 電子郵件 API 的一部分。在新 API 中，此功能由 @ref{1b5f,,set_content()} 方法的 `cte' 參數提供。

此模組在 Python 3 中已棄用。不應明確呼叫此處提供的函式，因為 @ref{ff5,,MIMEText} 類別使用在該類別的實例化過程中傳遞的 `_subtype' 和 `_charset' 值來設定內容類型 (content type) 和 CTE 標頭。

本節中的其餘文字是該模組的原始文件。

從零開始建立 @ref{57b,,Message} 物件時，你通常需要對負載 (payload) 進行編碼，以便透過相容的郵件伺服器進行傳輸。對於包含二進位資料的 @code{image/*} 和 @code{text/*} 類型的訊息尤其如此。

@ref{3f,,email} 套件在其 @ref{42,,encoders} 模組中提供了一些方便的編碼器。這些編碼器實際上由 @ref{3a59,,MIMEAudio} 和 @ref{39ec,,MIMEImage} 類別建構函式使用來提供預設編碼。所有編碼器函式都只接受一個引數，也就是要編碼的訊息物件。他們通常會提取負載、對其進行編碼，然後將負載重設為新編碼的值。他們也應適當地設定 @code{Content-Transfer-Encoding} 標頭。

請注意，這些函式對於多部分訊息 (multipart message) 沒有意義。它們必須應用於各個子部分，如果傳遞類型為多部分訊息，則會引發 @ref{198,,TypeError}。

以下是提供的編碼函式：

@geindex encode_quopri() (於 email.encoders 模組中)
@anchor{library/email encoders email encoders encode_quopri}@anchor{3a7a}
@deffn {函式} email.encoders.encode_quopri (msg)

將負載編碼為可列印字元 (quoted-printable) 形式，並將 @code{Content-Transfer-Encoding} 標頭設定為 @code{quoted-printable} @footnote{
請注意，使用 @ref{3a7a,,encode_quopri()} 進行編碼也會對資料中的所有定位字元 (tab) 和空格字元進行編碼。
}。當大部分負載是正常的可列印資料，但包含一些不可列印的字元時，這是一種很好的編碼。
@end deffn

@geindex encode_base64() (於 email.encoders 模組中)
@anchor{library/email encoders email encoders encode_base64}@anchor{3a7b}
@deffn {函式} email.encoders.encode_base64 (msg)

將負載編碼為 base64 形式，並將 @code{Content-Transfer-Encoding} 標頭設定為 @code{base64}。當大部分負載是不可列印資料時，這是一種很好的編碼，因為它是比可列印字元更緊湊的形式。Base64 編碼的缺點是它使文字無法讓人類可讀。
@end deffn

@geindex encode_7or8bit() (於 email.encoders 模組中)
@anchor{library/email encoders email encoders encode_7or8bit}@anchor{3a7c}
@deffn {函式} email.encoders.encode_7or8bit (msg)

這實際上並沒有修改訊息的負載，但它確實根據負載資料將 @code{Content-Transfer-Encoding} 標頭設定為適當的 @code{7bit} 或 @code{8bit}。
@end deffn

@geindex encode_noop() (於 email.encoders 模組中)
@anchor{library/email encoders email encoders encode_noop}@anchor{3a7d}
@deffn {函式} email.encoders.encode_noop (msg)

這沒有任何作用；它甚至沒有設定 @code{Content-Transfer-Encoding} 標頭。
@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：雜項工具,email iterators：疊代器,email encoders：編碼器,email --- 郵件和 MIME 處理套件
@anchor{library/email utils doc}@anchor{3a7e}@anchor{library/email utils email-utils-miscellaneous-utilities}@anchor{3a7f}@anchor{library/email utils module-email utils}@anchor{54}@anchor{library/email utils translation-repo}@anchor{3a80}
@subsubsection @code{email.utils}：雜項工具


@geindex module; email.utils

`原始碼：'Lib/email/utils.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/email/utils.py}


__________________________________________________________________


There are a couple of useful utilities provided in the @ref{54,,email.utils}
module:

@geindex localtime() (於 email.utils 模組中)
@anchor{library/email utils email utils localtime}@anchor{2f6}
@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{4dd,,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.


在 3.3 版被加入.



Deprecated since version 3.12, removed in version 3.14: The `isdst' parameter.

@end deffn

@geindex make_msgid() (於 email.utils 模組中)
@anchor{library/email utils email utils make_msgid}@anchor{3a81}
@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 版的變更: 新增 `domain' 關鍵字。

@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{3a82}
@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{398e}
@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{4ef}
@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{139b}
@deffn {函式} email.utils.formataddr (pair, charset='utf-8')

The inverse of @ref{4ef,,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{169,,str} or a
@ref{ff6,,Charset}.  Defaults to @code{utf-8}.


在 3.3 版的變更: 新增 `charset' 選項。

@end deffn

@geindex getaddresses() (於 email.utils 模組中)
@anchor{library/email utils email utils getaddresses}@anchor{4ee}
@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{3a3a,,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{3a83}
@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 @ref{3a83,,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, @ref{3a83,,parsedate()} returns a 9-tuple that can be passed directly to
@ref{13e9,,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{1b35}
@deffn {函式} email.utils.parsedate_tz (date)

Performs the same function as @ref{3a83,,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{13e9,,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{12bf}
@deffn {函式} email.utils.parsedate_to_datetime (date)

The inverse of @ref{12be,,format_datetime()}.  Performs the same function as
@ref{3a83,,parsedate()}, but on success returns a @ref{4dd,,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{12c0,,timezone} @ref{7ef,,tzinfo}.


在 3.3 版被加入.

@end deffn

@geindex mktime_tz() (於 email.utils 模組中)
@anchor{library/email utils email utils mktime_tz}@anchor{3a84}
@deffn {函式} email.utils.mktime_tz (tuple)

Turn a 10-tuple as returned by @ref{1b35,,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{165f}
@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{13c1,,time.gmtime()} and @ref{16ed,,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{12be}
@deffn {函式} email.utils.format_datetime (dt, usegmt=False)

Like @code{formatdate}, but the input is a @ref{34,,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.


在 3.3 版被加入.

@end deffn

@geindex decode_rfc2231() (於 email.utils 模組中)
@anchor{library/email utils email utils decode_rfc2231}@anchor{3a85}
@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{3a86}
@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{3a47}
@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{3a46,,Message.get_param} may return a
3-tuple containing the character set,
language, and value.  @ref{3a47,,collapse_rfc2231_value()} turns this into a unicode
string.  Optional `errors' is passed to the `errors' argument of @ref{169,,str}'s
@ref{ac9,,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 @ref{3a47,,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{17a7}
@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

@subsubheading 註解


@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：疊代器,,email utils：雜項工具,email --- 郵件和 MIME 處理套件
@anchor{library/email iterators doc}@anchor{3a87}@anchor{library/email iterators email-iterators-iterators}@anchor{3a88}@anchor{library/email iterators module-email iterators}@anchor{47}@anchor{library/email iterators translation-repo}@anchor{3a89}
@subsubsection @code{email.iterators}：疊代器


@geindex module; email.iterators

`原始碼：'Lib/email/iterators.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/email/iterators.py}


__________________________________________________________________


Iterating over a message object tree is fairly easy with the
@ref{3a4f,,Message.walk} method.  The
@ref{47,,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{3a8a}
@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{1f6d,,readline()}, skipping over all the
intervening headers.

Optional `decode' is passed through to @ref{13ce,,Message.get_payload}.
@end deffn

@geindex typed_subpart_iterator() (於 email.iterators 模組中)
@anchor{library/email iterators email iterators typed_subpart_iterator}@anchor{3a8b}
@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 @ref{3a8b,,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{3a8c}
@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{1170,,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 @ref{cf,,smtplib} 模組

SMTP (Simple Mail Transport Protocol) client

@item @ref{b1,,poplib} 模組

POP (Post Office Protocol) client

@item @ref{78,,imaplib} 模組

IMAP (Internet Message Access Protocol) client

@item @ref{8f,,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 編碼器與解碼器,mailbox --- 以各種格式操作郵件信箱,email --- 郵件和 MIME 處理套件,網際網路資料處理
@anchor{library/json doc}@anchor{3a8d}@anchor{library/json json-json-encoder-and-decoder}@anchor{3a8e}@anchor{library/json module-json}@anchor{86}@anchor{library/json translation-repo}@anchor{3a8f}
@subsection @code{json} --- JSON 編碼器與解碼器


@geindex module; json

`原始碼：'Lib/json/__init__.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/json/__init__.py}


__________________________________________________________________


JSON (JavaScript Object Notation)@footnote{https://json.org} 是一個輕量化的資料交換格式，在 
@geindex RFC; RFC 7159
RFC 7159@footnote{https://datatracker.ietf.org/doc/html/rfc7159.html}（其廢棄了 
@geindex RFC; RFC 4627
RFC 4627@footnote{https://datatracker.ietf.org/doc/html/rfc4627.html}）及 ECMA-404@footnote{https://ecma-international.org/publications-and-standards/standards/ecma-404/} 裡面有詳細說明，它啟發自 JavaScript@footnote{https://en.wikipedia.org/wiki/JavaScript} 的物件字面語法 (object literal syntax)（雖然它並不是 JavaScript 的嚴格子集 @footnote{
如 @uref{https://www.rfc-editor.org/errata_search.php?rfc=7159,RFC 7159 更正} 所述，JSON 允許字串中出現 U+2028（列分隔符）和 U+2029（段落分隔符）字元，而 JavaScript（截至 ECMAScript 5.1 版）則不允許。
}）。

@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 警告 
當剖析無法信任來源的 JSON 資料時要小心。一段惡意的 JSON 字串可能會導致解碼器耗費大量 CPU 與記憶體資源。建議限制剖析資料的大小。
@end quotation
@end cartouche

此模組為習慣標準函式庫 @ref{91,,marshal} 與 @ref{ab,,pickle} 模組的使用者提供熟悉的 API。

對基本 Python 物件階層進行編碼：

@example
>>> import json
>>> json.dumps(['foo', @{'bar': ('baz', None, 1.0, 2)@}])
'["foo", @{"bar": ["baz", null, 1.0, 2]@}]'
>>> print(json.dumps("\"foo\bar"))
"\"foo\bar"
>>> print(json.dumps('\u1234'))
"\u1234"
>>> print(json.dumps('\\'))
"\\"
>>> print(json.dumps(@{"c": 0, "b": 0, "a": 0@}, sort_keys=True))
@{"a": 0, "b": 0, "c": 0@}
>>> from io import StringIO
>>> io = StringIO()
>>> json.dump(['streaming API'], io)
>>> io.getvalue()
'["streaming API"]'
@end example

改用緊湊型編碼方式：

@example
>>> import json
>>> json.dumps([1, 2, 3, @{'4': 5, '6': 7@}], separators=(',', ':'))
'[1,2,3,@{"4":5,"6":7@}]'
@end example

美化輸出：

@example
>>> import json
>>> print(json.dumps(@{'6': 7, '4': 5@}, sort_keys=True, indent=4))
@{
    "4": 5,
    "6": 7
@}
@end example

自訂 JSON 物件編碼方式：

@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

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

自訂 JSON 物件解碼方式：

@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

繼承 @ref{f3d,,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

在 shell 使用 @ref{86,,json} 來驗證和美化印出：

@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

更詳盡的文件請見 @ref{23e,,命令列介面}。

@cartouche
@quotation 備註 
JSON 語法是 YAML@footnote{https://yaml.org/} 1.2 語法的一種子集合。所以如果使用預設的設定的話（準確來說，使用預設的 `separators' 分隔符設定的話），這個模組的輸出也符合 YAML 1.0 和 1.1 的子集合規範。因此你也可以利用這個模組來當作 YAML 的序列化工具（serializer）。
@end quotation
@end cartouche

@cartouche
@quotation 備註 
這個模組的編、解碼器預設會保存輸入與輸出資料的順序關係，除非一開始的輸入本身就是無序的。
@end quotation
@end cartouche

@menu
* 基本用法: 基本用法<4>. 
* 編碼器與解碼器:: 
* 例外: 例外<18>. 
* 合規性與互通性（Interoperability）:: 
* 命令列介面: 命令列介面<6>. 

@end menu

@node 基本用法<4>,編碼器與解碼器,,json --- JSON 編碼器與解碼器
@anchor{library/json basic-usage}@anchor{3a90}
@subsubsection 基本用法


@geindex dump() (於 json 模組中)
@anchor{library/json json dump}@anchor{f3b}
@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)

參考這個 @ref{3a91,,Python-to-JSON 轉換表}將 `obj' 序列化為符合 JSON 格式的串流，並寫入到 `fp' （一個支援 @code{.write()} 方法的 @ref{28ad,,file-like object}）

@cartouche
@quotation 備註 
與 @ref{ab,,pickle} 和 @ref{91,,marshal} 不同，JSON 不具有二進位分框（binary framed）的協定，因此嘗試重複呼叫 @ref{f3b,,dump()} 來序列化多個物件到同一個 `fp' 裡將導致無效的 JSON 檔案。
@end quotation
@end cartouche

@*參數: 

@itemize *

@item 
@code{obj} (@ref{c75,,object}) -- 要被序列化的 Python 物件。

@item 
@code{fp} (@ref{28ad,,file-like object}) -- The file-like object `obj' will be serialized to.
The @code{json} module always produces @ref{169,,str} objects,
not @ref{192,,bytes} objects,
therefore @code{fp.write()} must support @ref{169,,str} input.

@item 
@code{skipkeys} (@ref{3c1,,bool}) -- If @code{True}, keys that are not of a basic type
(@ref{169,,str}, @ref{19b,,int}, @ref{196,,float}, @ref{3c1,,bool}, @code{None})
will be skipped instead of raising a @ref{198,,TypeError}.
Default @code{False}.

@item 
@code{ensure_ascii} (@ref{3c1,,bool}) -- If @code{True} (the default), the output is guaranteed to
have all incoming non-ASCII characters escaped.
If @code{False}, these characters will be outputted as-is.

@item 
@code{check_circular} (@ref{3c1,,bool}) -- 如為 @code{False}，則針對不同容器型別的循環參照 (circular reference) 檢查將會被跳過，若有循環參照則最後將引發 @ref{f63,,RecursionError}（或其他更糟的錯誤）。預設為 @code{True}。

@item 
@code{allow_nan} (@ref{3c1,,bool}) -- 如為 @code{False}，則序列化不符合嚴格 JSON 規範的超出範圍 @ref{196,,float} 值 (@code{nan}, @code{inf}, @code{-inf}) 會引發 @ref{2eb,,ValueError}。如為 @code{True}（預設值），則將使用它們的 JavaScript 等效表示 (@code{NaN}, @code{Infinity}, @code{-Infinity})。

@item 
@code{cls} (a @ref{f3d,,JSONEncoder} subclass) -- If set, a custom JSON encoder with the
@ref{3a92,,default()} method overridden,
for serializing into custom datatypes.
If @code{None} (the default), @code{JSONEncoder} is used.

@item 
@code{indent} (@ref{19b,,int}@code{ | }@ref{169,,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{60c,,tuple}@code{ | }@code{None}) -- 一個二元組：@code{(item_separator, key_separator)}。如為 @code{None}（預設值）則 `separators' 被預設為 @code{(', ', ': ')}，否則預設為 @code{(',', ': ')}。想要獲得最緊湊的 JSON 表示形式，你可以指定 @code{(',', ':')} 來消除空格。

@item 
@code{default} (@ref{2c2e,,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{198,,TypeError}.
If @code{None} (the default), @code{TypeError} is raised.

@item 
@code{sort_keys} (@ref{3c1,,bool}) -- If @code{True}, dictionaries will be outputted sorted by key.
Default @code{False}.
@end itemize



在 3.2 版的變更: 除了整數之外，`indent' 還允許使用字串作為輸入。



在 3.4 版的變更: 如果 `indent' 不是 @code{None}，則使用 @code{(',', ': ')} 作為預設值



在 3.6 版的變更: 所有可選參數現在都是@ref{59f,,僅限關鍵字}參數了。

@end deffn

@geindex dumps() (於 json 模組中)
@anchor{library/json json dumps}@anchor{f3c}
@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)

使用此@ref{3a93,,轉換表}來將 `obj' 序列化為 JSON 格式 @ref{169,,str}。這個引數的作用與 @ref{f3b,,dump()} 中的同名引數意義相同。

@cartouche
@quotation 備註 
JSON 鍵/值對中的鍵始終為 @ref{169,,str} 型別。當字典被轉換為 JSON 時，字典的所有鍵值資料型別都會被強制轉換為字串。因此，如果將字典先轉換為 JSON 格式然後再轉換回字典，則該字典可能不等於原始字典。也就是說，如果字典 x 含有非字串鍵值，則 @code{loads(dumps(x)) != x}。
@end quotation
@end cartouche
@end deffn

@geindex load() (於 json 模組中)
@anchor{library/json json load}@anchor{ead}
@deffn {函式} json.load (fp, *, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, **kw)

使用此 @ref{3a93,,JSON-to-Python 轉換表}將 `fp' 解碼為 Python 物件。

@*參數: 

@itemize *

@item 
@code{fp} (@ref{28ad,,file-like object}) -- A @code{.read()}-supporting @ref{1f34,,text file} or @ref{1f35,,binary file}
containing the JSON document to be deserialized.

@item 
@code{cls} (a @ref{f3e,,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{2c2e,,callable} | None) -- 如果有設定，會用解碼後的 JSON 物件字面值的結果（一個 @ref{183,,dict}）來呼叫此函式。此函式的回傳值將用來取代 @ref{183,,dict}。此功能可用於實作自訂解碼器，例如 JSON-RPC@footnote{https://www.jsonrpc.org} 類別提示。預設為 @code{None}。

@item 
@code{object_pairs_hook} (@ref{2c2e,,callable} | None) -- 如果有設定，會用任何 JSON 物件字面值以有序對串列解碼的結果來呼叫此函式。此函式的回傳值將用來取代 @ref{183,,dict}。此功能可用於實作自訂解碼器。如果也設定了 `object_hook'，以 `object_pairs_hook' 優先。預設為 @code{None}。

@item 
@code{parse_float} (@ref{2c2e,,callable} | None) -- 如果有設定，會用每個要被解碼的 JSON 浮點數字串來呼叫此函式。如果為 @code{None}（預設值），則等同於 @code{float(num_str)}。此功能可用於將 JSON 浮點數剖析為自訂資料型別，例如 @ref{1fe,,decimal.Decimal}。

@item 
@code{parse_int} (@ref{2c2e,,callable} | None) -- 如果有設定，會用每個要被解碼的 JSON 整數字串來呼叫此函式。如果為 @code{None}（預設值），則等同於 @code{int(num_str)}。此功能可用於將 JSON 整數剖析為自訂資料型別，例如 @ref{196,,float}。

@item 
@code{parse_constant} (@ref{2c2e,,callable} | None) -- 如果有設定，會用以下字串之一來呼叫此函式：@code{'-Infinity'}、@code{'Infinity'} 或 @code{'NaN'}。此功能可用於在遇到無效的 JSON 數字時引發例外。預設為 @code{None}。
@end itemize


@*引發: 

@itemize *

@item 
@ref{101d,,JSONDecodeError} -- 當被去序列化的資料不是有效的 JSON 文件時。

@item 
@ref{bff,,UnicodeDecodeError} -- 當被去序列化的資料不包含 UTF-8、UTF-16 或 UTF-32 編碼資料時。
@end itemize



在 3.1 版的變更: 


@itemize *

@item 
新增可選的 `object_pairs_hook' 參數。

@item 
遭遇 'null'、'true' 或 'false' 時不再以 `parse_constant' 給定的函式來處理了。
@end itemize



在 3.6 版的變更: 


@itemize *

@item 
所有可選參數現在都是@ref{59f,,僅限關鍵字}參數了。

@item 
現在，`fp' 可以是一個@ref{1f35,,二進位檔案}，前提是其編碼格式為 UTF-8、UTF-16 或 UTF-32。
@end itemize



在 3.11 版的變更: 預設 `parse_int' 使用的 @ref{19b,,int()} 函式現在有限制整數字串的長度上限了，限制由直譯器的@ref{804,,整數字串轉換長度限制}機制來達成，這能防止阻斷服務攻擊 (Denial of Service attacks)。

@end deffn

@geindex loads() (於 json 模組中)
@anchor{library/json json loads}@anchor{b45}
@deffn {函式} json.loads (s, *, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, **kw)

與 @ref{ead,,load()} 相同，但不是類檔案物件，而是使用@ref{3a93,,轉換表}將 `s'（一個包含 JSON 文件的 @ref{169,,str}、@ref{192,,bytes} 或 @ref{343,,bytearray} 實例）去序列化為 Python 物件。


在 3.6 版的變更: 現在，`s' 可以是一個二進位檔案如 @ref{192,,bytes} 或 @ref{343,,bytearray}，前提是其編碼格式為 UTF-8、UTF-16 或 UTF-32。



在 3.9 版的變更: 刪除關鍵字引數 `encoding'。

@end deffn

@node 編碼器與解碼器,例外<18>,基本用法<4>,json --- JSON 編碼器與解碼器
@anchor{library/json encoders-and-decoders}@anchor{3a94}
@subsubsection 編碼器與解碼器


@geindex JSONDecoder (json 中的類別)
@anchor{library/json json JSONDecoder}@anchor{f3e}
@deffn {類別} json.JSONDecoder (*, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, strict=True, object_pairs_hook=None)

簡易 JSON 解碼器

預設將執行下列資料型別轉換：
@anchor{library/json json-to-py-table}@anchor{3a93}

@multitable {xxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxx} 
@headitem

JSON

@tab

Python

@item

object

@tab

dict

@item

array

@tab

list

@item

string

@tab

str

@item

number (整數)

@tab

int

@item

number (實數)

@tab

float

@item

true

@tab

True

@item

false

@tab

False

@item

null

@tab

None

@end multitable


雖然 @code{NaN}、@code{Infinity} 和 @code{-Infinity} 並不符合 JSON 規範，但解碼器依然能正確地將其轉換到相應的 Python @code{float} 值。

`object_hook' 是一個可選函式，其接受一個解碼後的 JSON 物件作為輸入，並使用其回傳值來取代原先的 @ref{183,,dict}。這個功能可用於提供自訂的去序列化（例如支援 JSON-RPC@footnote{https://www.jsonrpc.org} 類別提示）。

`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{183,,dict}.  This feature can be used to implement custom decoders.  If
`object_hook' is also defined, the `object_pairs_hook' takes priority.


在 3.1 版的變更: 新增對於 `object_pairs_hook' 的支援。


`parse_float' 為可選函式，每個要被解碼的 JSON 浮點數字串都會改用這個參數給定的函式來進行解碼。預設情況這等效於 @code{float(num_str)}。這個參數可用於將 JSON 中的浮點數解碼或剖析為另一種資料型別（例如 @ref{1fe,,decimal.Decimal}）。

`parse_int' 為可選函式，當解碼 JSON 整數字串時會被呼叫。預設情況等效於 @code{int(num_str)}。這個參數可用於將 JSON 中的整數解碼或剖析為另一種資料型別（例如 @ref{196,,float}）。

`parse_constant' 為可選函式，在解碼時若遭遇字串 @code{'-Infinity'}、@code{'Infinity'} 或 @code{'NaN'} 其中之一則會改用這個參數給定的函式來進行解碼。這也可用於使解碼過程中遇到無效的 JSON 數字時引發一個例外。

如果 `strict' 被設為 false（預設值為 @code{True}），那麼字串中將允許控制字元。此語境中的控制字元指的是 ASCII 字元編碼在 0～31 範圍內的字元，包括 @code{'\t'`@w{`}（tab）、}'n'@code{、}'r'`@w{`} 和 @code{'\0'}。

如果被去序列化（deserialized）的資料不符合 JSON 格式，將會引發 @ref{101d,,JSONDecodeError} 例外。


在 3.6 版的變更: 所有參數現在都是@ref{59f,,僅限關鍵字參數}了。


@geindex decode() (json.JSONDecoder 的方法)
@anchor{library/json json JSONDecoder decode}@anchor{3a95}
@deffn {方法} decode (s)

回傳用 Python 型式表達的 `s' （一個含有 JSON 文件的 @ref{169,,str} 實例）。

若給定的輸入不符合 JSON 格式會引發 @ref{101d,,JSONDecodeError} 例外。
@end deffn

@geindex raw_decode() (json.JSONDecoder 的方法)
@anchor{library/json json JSONDecoder raw_decode}@anchor{3a96}
@deffn {方法} raw_decode (s)

將 `s' （一個開頭部分含有合格 JSON 文件的 @ref{169,,str}） 解碼，並將 JSON 文件結束點的索引值（index）和解碼結果合併為一個二元組（2-tuple）後回傳。

這個方法可以用來解碼尾段可能帶有 JSON 以外資料的文字。
@end deffn
@end deffn

@geindex JSONEncoder (json 中的類別)
@anchor{library/json json JSONEncoder}@anchor{f3d}
@deffn {類別} json.JSONEncoder (*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

可擴充的 Python 資料結構 JSON 編碼器。

預設可支援下列物件及型別：
@anchor{library/json py-to-json-table}@anchor{3a91}

@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxx} 
@headitem

Python

@tab

JSON

@item

dict

@tab

object

@item

list, tuple

@tab

array

@item

str

@tab

string

@item

int、float 或可作為整數或浮點數運算的衍生列舉（int- or float-derived Enums）

@tab

number

@item

True

@tab

true

@item

False

@tab

false

@item

None

@tab

null

@end multitable



在 3.4 版的變更: 增加對整數（int）、浮點數（float）或可作為整數或浮點數運算的衍生列舉（int- or float-derived Enums）類別的支援性。


若要擴充此功能來識別其他物件，請繼承並實作一個 @ref{3a92,,default()} 方法。此方法應回傳一個可序列化的 @code{o} 物件，否則此方法應呼叫父類別的 JSONEncoder.default 方法（以引發 @ref{198,,TypeError} 例外）。

若 `skipkeys' 為 false（預設值），則當在編碼不是 @ref{169,,str}、@ref{19b,,int}、@ref{196,,float}、@ref{3c1,,bool} 或 @code{None} 的鍵值時，將引發 @ref{198,,TypeError}。如果 `skipkeys' 為 true，這些項目將直接被跳過。

如果 `ensure_ascii' 被設為 true（預設值），則輸出時將確保所有輸入的非 ASCII 字元都會被跳脫。若 `ensure_ascii' 為 false，則這些字元將照原樣輸出。

如果 `check_circular' 為 true（預設值），則會在編碼期間檢查串列（list）、字典（dict）和自訂編碼物件的循環參照，以防止無限遞迴（一個會導致 @ref{f63,,RecursionError} 例外的問題）。否則不會進行此類檢查。

如果 `allow_nan' 為 true（預設值），則 @code{NaN}、@code{Infinity} 和 @code{-Infinity} 將按照原樣進行編碼。請記得此行為不符合標準 JSON 規範，但的確與大多數基於 JavaScript 的編碼器和解碼器一致。否則若設為 false，嘗試對這些浮點數進行編碼將引發 @ref{2eb,,ValueError} 例外。

如果 `sort_keys' 為 true（預設值：@code{False}），則 dictionary（字典）的輸出將按鍵值排序。這項功能可確保 JSON 序列化的結果能被互相比較，能讓日常的回歸測試檢查變得方便一些。

如果 `indent' 是非負整數或字串，則 JSON 陣列元素和物件成員將使用該縮排等級進行格式美化。縮排等級 0、負數或 @code{""} 只會插入換行符號。@code{None}（預設值）等於是選擇最緊湊的表示法。使用正整數縮排可以在每層縮排數量相同的空格。如果 `indent' 是一個字串（例如 @code{"\t"}），則該字串用於縮排每個層級。


在 3.2 版的變更: 除了整數之外，`indent' 還允許使用字串作為輸入。


如果有指定本引數內容，`separators' 應該是一個 @code{(item_separator, key_separator)} 二元組。如果 `indent' 為 @code{None} 則預設為 @code{(', ', ': ')}，否則預設為 @code{(',', ': ')}。想要獲得最緊湊的 JSON 表示形式，你可以改成指定 @code{(',', ':')} 來消除空格。


在 3.4 版的變更: 如果 `indent' 不是 @code{None}，則使用 @code{(',', ': ')} 作為預設值


如果有指定本參數，`default' 會是一個遭遇無法序列化的物件時會被呼叫的函式。它應該回傳該物件的 JSON 可編碼版本或引發 @ref{198,,TypeError}。如果未指定，則會直接引發 @ref{198,,TypeError}。


在 3.6 版的變更: 所有參數現在都是@ref{59f,,僅限關鍵字參數}了。


@geindex default() (json.JSONEncoder 的方法)
@anchor{library/json json JSONEncoder default}@anchor{3a92}
@deffn {方法} default (o)

在任意一個子類別裡實作這個方法時須讓其回傳一個可序列化的物件 `o' ，或呼叫原始的實作以引發 @ref{198,,TypeError} 例外。

舉例來說，想要讓編碼器支援任意疊代器（iterator），你可以實作這樣子的 @ref{3a92,,default()}：

@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{3a97}
@deffn {方法} encode (o)

回傳一個 Python 資料結構物件 `o' 的 JSON 的字串表示。例如：

@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{3a98}
@deffn {方法} iterencode (o)

將物件 `o' 編碼，並將結果統整為一個能依序產生（yield）各結果字串的物件。如下例：

@example
for chunk in json.JSONEncoder().iterencode(bigobject):
    mysocket.write(chunk)
@end example
@end deffn
@end deffn

@node 例外<18>,合規性與互通性（Interoperability）,編碼器與解碼器,json --- JSON 編碼器與解碼器
@anchor{library/json exceptions}@anchor{3a99}
@subsubsection 例外


@geindex JSONDecodeError
@anchor{library/json json JSONDecodeError}@anchor{101d}
@deffn {例外} json.JSONDecodeError (msg, doc, pos)

@ref{2eb,,ValueError} 的子類別具有下列額外屬性：

@geindex msg (json.JSONDecodeError 的屬性)
@anchor{library/json json JSONDecodeError msg}@anchor{3a9a}
@deffn {屬性} msg

未受格式化的錯誤訊息。
@end deffn

@geindex doc (json.JSONDecodeError 的屬性)
@anchor{library/json json JSONDecodeError doc}@anchor{3a9b}
@deffn {屬性} doc

正在被剖析的 JSON 文件。
@end deffn

@geindex pos (json.JSONDecodeError 的屬性)
@anchor{library/json json JSONDecodeError pos}@anchor{3a9c}
@deffn {屬性} pos

`doc' 剖析失敗處的起始點的索引值。
@end deffn

@geindex lineno (json.JSONDecodeError 的屬性)
@anchor{library/json json JSONDecodeError lineno}@anchor{3a9d}
@deffn {屬性} lineno

`pos' 所在的列（line）數。
@end deffn

@geindex colno (json.JSONDecodeError 的屬性)
@anchor{library/json json JSONDecodeError colno}@anchor{3a9e}
@deffn {屬性} colno

`pos' 所在的行（column）數。
@end deffn


在 3.5 版被加入.

@end deffn

@node 合規性與互通性（Interoperability）,命令列介面<6>,例外<18>,json --- JSON 編碼器與解碼器
@anchor{library/json standard-compliance-and-interoperability}@anchor{3a9f}
@subsubsection 合規性與互通性（Interoperability）


JSON 格式是由 
@geindex RFC; RFC 7159
RFC 7159@footnote{https://datatracker.ietf.org/doc/html/rfc7159.html} 和 ECMA-404@footnote{https://ecma-international.org/publications-and-standards/standards/ecma-404/} 規範的。本節詳細說明了本模組對 RFC 的遵循程度。簡單起見，@ref{f3d,,JSONEncoder} 和 @ref{f3e,,JSONDecoder} 子類別以及未明確提及的參數將不予討論。

這個模組的部份實作並未非常嚴格地遵循 RFC 規範。準確來說，下列實際實作符合 JavaScript 語法格式，但並不符合 JSON 格式：


@itemize -

@item 
無限（Infinite）和非數字（NaN）值會被接受。

@item 
同一個物件內可以有重複的名稱，但只有最後一個同名物件是有效的。
@end itemize

不過 RFC 准許遵循 RFC 的剖析器接受不合規的文字輸入，所以技術上來說若以預設設定運作，本模組的去序列化器（deserializer）是符合 RFC 規範的。

@menu
* 字元編碼格式:: 
* 正負無限與非數值:: 
* 物件內重複的名稱:: 
* 位於頂層的非物件及非列表值:: 
* 實作限制:: 

@end menu

@node 字元編碼格式,正負無限與非數值,,合規性與互通性（Interoperability）
@anchor{library/json character-encodings}@anchor{3aa0}
@subsubsection 字元編碼格式


RFC 要求 JSON 必須以 UTF-8、UTF-16 或 UTF-32 格式編碼。並推薦以 UTF-8 編碼以達成最佳的互通性。

RFC 准許但並不強制編碼器的 `ensure_ascii=True' 行為是預設值，但本模組依然實作了此一選項作為預設，因此本模組預設會跳脫所有非 ASCII 字元。

除了 `ensure_ascii' 選項參數之外，本模組嚴格遵循 Python 物件與 @ref{169,,Unicode strings} 之間的轉換規範，因此並不另外處理字元編碼的問題。

RFC 禁止在文件的開頭加上端序記號（Byte Order Mark），因此本模組的序列化器（serializer）也不會在輸出中加入端序記號。RFC 允許但不強制 JSON 去序列化器（deserializer）忽略文件初始的端序記號，因此本模組的去序列化器將在遭遇位於文件開頭的端序記號時引發 @ref{2eb,,ValueError} 例外。

RFC 並未明確禁止 JSON 文件包含無法對應有效 Unicode 字元的位元組序列（例如未配對的 UTF-16 代理對（surrogate pairs）），但這個特性的確可能會引起相容性問題。預設情況下，當原始輸入的 @ref{169,,str} 中存在此類序列時，該模組將接受並輸出這些序列的編碼位置（code points）。

@node 正負無限與非數值,物件內重複的名稱,字元編碼格式,合規性與互通性（Interoperability）
@anchor{library/json infinite-and-nan-number-values}@anchor{3aa1}
@subsubsection 正負無限與非數值


RFC 不允許表現無限大或非數值（NaN）。但預設情況下，這個模組仍接受並輸出 @code{Infinity}、@code{-Infinity} 和 @code{NaN}，如同它們是有效的 JSON 數值字面值：

@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

在序列化器中，`allow_nan' 參數可以改變這個行為。在去序列化器中，`parse_constant' 參數可以改變這個行為。

@node 物件內重複的名稱,位於頂層的非物件及非列表值,正負無限與非數值,合規性與互通性（Interoperability）
@anchor{library/json repeated-names-within-an-object}@anchor{3aa2}
@subsubsection 物件內重複的名稱


RFC 規範僅表明 JSON 物件中的名字應該是唯一的，但沒有強制要求如何處理重複的名字。預設情況下，本模組不會因此引發例外；相反的，它會忽略該名字的所有重複鍵值對，並只保留最後一個：

@example
>>> weird_json = '@{"x": 1, "x": 2, "x": 3@}'
>>> json.loads(weird_json)
@{'x': 3@}
@end example

`object_pairs_hook' 參數可以改變這個行為。

@node 位於頂層的非物件及非列表值,實作限制,物件內重複的名稱,合規性與互通性（Interoperability）
@anchor{library/json top-level-non-object-non-array-values}@anchor{3aa3}
@subsubsection 位於頂層的非物件及非列表值


由已廢棄的 
@geindex RFC; RFC 4627
RFC 4627@footnote{https://datatracker.ietf.org/doc/html/rfc4627.html} 所規範的舊版 JSON 要求 JSON 文字的頂層值必須是 JSON 物件或陣列（Python @ref{183,,dict} 或 @ref{24d,,list}），而且不能是 JSON 的 null、boolean、數字或字串值。 
@geindex RFC; RFC 7159
RFC 7159@footnote{https://datatracker.ietf.org/doc/html/rfc7159.html} 移除了這個限制，而本模組的序列化器或去串列化器中未曾實施過該限制。

如果想要最大限度地保留互通性，你可能還是會想要自行施加這個限制。

@node 實作限制,,位於頂層的非物件及非列表值,合規性與互通性（Interoperability）
@anchor{library/json implementation-limitations}@anchor{3aa4}
@subsubsection 實作限制


某些 JSON 去序列化器的實作可能會造成下列限制：


@itemize *

@item 
JSON 文件長度上限

@item 
JSON 物件或陣列的最大巢狀層數（level of nesting）限制

@item 
數字的精準度或範圍

@item 
JSON 字串長度上限
@end itemize

本模組除了 Python 資料型態本身或 Python 直譯器本身的限制以外，不會設定任何此類限制。

將資料序列化為 JSON 時，要注意可能會使用該 JSON 輸出的應用程式中的相關限制。特別要注意的是，JSON 數字常會被去序列化為 IEEE 754 雙精度浮點數（double），並因而受到其表示範圍和精度限制的影響。這在序列化極大的 Python @ref{19b,,int} 數值、或是序列化特殊數字型別的實例時（例如 @ref{1fe,,decimal.Decimal}）尤其重要。

@node 命令列介面<6>,,合規性與互通性（Interoperability）,json --- JSON 編碼器與解碼器
@anchor{library/json command-line-interface}@anchor{3aa5}@anchor{library/json json-commandline}@anchor{23e}@anchor{library/json module-json tool}@anchor{87}
@subsubsection 命令列介面


@geindex module; json.tool

`原始碼：'Lib/json/tool.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/json/tool.py}


__________________________________________________________________


The @ref{86,,json} module can be invoked as a script via @code{python -m json}
to validate and pretty-print JSON objects. The @ref{87,,json.tool} submodule
implements this interface.

如果沒有指定可選引數 @code{infile} 和 @code{outfile} ，則 @ref{758,,sys.stdin} 和 @ref{cc4,,sys.stdout} 將各自做為輸入和輸出的預設值。

@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 版的變更: 現在開始輸出和輸入的資料順序會是相同的。傳入 @ref{3aa6,,--sort-keys} 引數以按照鍵值的字母順序對輸出進行排序。



在 3.14 版的變更: The @ref{86,,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
* 命令列選項: 命令列選項<4>. 

@end menu

@node 命令列選項<4>,,,命令列介面<6>
@anchor{library/json command-line-options}@anchor{3aa7}
@subsubsection 命令列選項


@geindex json 命令列選項; infile
@anchor{library/json cmdoption-json-arg-infile}@anchor{3aa8}
@deffn {Option} infile

將被用於校驗或美化呈現的 JSON 文件：

@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

如果沒有指定 `infile' 則會從 @ref{758,,sys.stdin} 讀取輸入。
@end deffn

@geindex json 命令列選項; outfile
@anchor{library/json cmdoption-json-arg-outfile}@anchor{3aa9}
@deffn {Option} outfile

將 `infile' 的結果寫入到給定的 `outfile'。若未提供則寫入到 @ref{cc4,,sys.stdout}。
@end deffn

@geindex json 命令列選項; --sort-keys
@anchor{library/json cmdoption-json-sort-keys}@anchor{3aa6}
@deffn {Option} @w{-}@w{-}sort@w{-}keys

按照鍵值的字母順序對輸出字典進行排序。


在 3.5 版被加入.

@end deffn

@geindex json 命令列選項; --no-ensure-ascii
@anchor{library/json cmdoption-json-no-ensure-ascii}@anchor{3aaa}
@deffn {Option} @w{-}@w{-}no@w{-}ensure@w{-}ascii

關閉非 ASCII 字元的自動跳脫功能。詳情請參照 @ref{f3c,,json.dumps()}。


在 3.9 版被加入.

@end deffn

@geindex json 命令列選項; --json-lines
@anchor{library/json cmdoption-json-json-lines}@anchor{3aab}
@deffn {Option} @w{-}@w{-}json@w{-}lines

將每一行輸入都單獨輸出為一個 JSON 物件。


在 3.8 版被加入.

@end deffn

@geindex json 命令列選項; --indent
@geindex json 命令列選項; --tab
@geindex json 命令列選項; --no-indent
@geindex json 命令列選項; --compact
@anchor{library/json cmdoption-json-indent}@anchor{3aac}@anchor{library/json cmdoption-json-tab}@anchor{3aad}@anchor{library/json cmdoption-json-no-indent}@anchor{3aae}@anchor{library/json cmdoption-json-compact}@anchor{3aaf}
@deffn {Option} @w{-}@w{-}indent, @w{-}@w{-}tab, @w{-}@w{-}no@w{-}indent, @w{-}@w{-}compact

互斥的空白字元控制選項。


在 3.9 版被加入.

@end deffn

@geindex json 命令列選項; -h
@geindex json 命令列選項; --help
@anchor{library/json cmdoption-json-h}@anchor{3ab0}@anchor{library/json cmdoption-json-help}@anchor{3ab1}
@deffn {Option} @w{-}h, @w{-}@w{-}help

顯示說明訊息。
@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 mailbox --- 以各種格式操作郵件信箱,mimetypes --- 將檔案名稱對映到 MIME 類型,json --- JSON 編碼器與解碼器,網際網路資料處理
@anchor{library/mailbox doc}@anchor{3ab2}@anchor{library/mailbox mailbox-manipulate-mailboxes-in-various-formats}@anchor{3ab3}@anchor{library/mailbox module-mailbox}@anchor{8f}@anchor{library/mailbox translation-repo}@anchor{3ab4}
@subsection @code{mailbox} --- 以各種格式操作郵件信箱


@geindex module; mailbox

`原始碼：'Lib/mailbox.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/mailbox.py}


__________________________________________________________________


This module defines two classes, @ref{144d,,Mailbox} and @ref{1451,,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{48,,email.message} module's
@ref{57b,,Message} class with format-specific state and behavior.
Supported mailbox formats are Maildir, mbox, MH, Babyl, and MMDF.


@subsubheading 也參考



@table @asis

@item @ref{3f,,email} 模組

Represent and manipulate messages.
@end table


@menu
* Mailbox 物件:: 
* Message 物件:: 
* 例外: 例外<19>. 
* 範例: 範例<30>. 

@end menu

@node Mailbox 物件,Message 物件,,mailbox --- 以各種格式操作郵件信箱
@anchor{library/mailbox id1}@anchor{3ab5}@anchor{library/mailbox mailbox-objects}@anchor{3ab6}
@subsubsection @code{Mailbox} 物件


@geindex Mailbox (mailbox 中的類別)
@anchor{library/mailbox mailbox Mailbox}@anchor{144d}
@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{144c,,add()} and removed using a @code{del} statement or the set-like
methods @ref{3ab7,,remove()} and @ref{3ab8,,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{1451,,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{4c3,,iterator} iterates over message
representations, not keys as the default @ref{183,,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{5df,,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{656,,Maildir}; try to avoid using single-file formats such as
@ref{194a,,mbox} for
concurrent writing.  If you're modifying a mailbox, you `must' lock it by
calling the @ref{3ab9,,lock()} and @ref{3aba,,unlock()} methods `before' reading any
messages in the file or making any changes by adding or deleting a
message.  Failing to lock the mailbox runs the risk of losing messages or
corrupting the entire mailbox.
@end quotation
@end cartouche

@code{Mailbox} instances have the following methods:

@geindex add() (mailbox.Mailbox 的方法)
@anchor{library/mailbox mailbox Mailbox add}@anchor{144c}
@deffn {方法} add (message)

Add `message' to the mailbox and return the key that has been assigned to
it.

Parameter `message' may be a @ref{1451,,Message} instance, an
@ref{57b,,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 @ref{1451,,Message} subclass (e.g., if it's an
@ref{3976,,mboxMessage} instance and this is an @ref{194a,,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{3ab7}
@deffn {方法} remove (key)
@anchor{library/mailbox mailbox Mailbox __delitem__}@anchor{3abb}
@deffnx {方法} __delitem__ (key)
@anchor{library/mailbox mailbox Mailbox discard}@anchor{3ab8}
@deffnx {方法} discard (key)

Delete the message corresponding to `key' from the mailbox.

If no such message exists, a @ref{5df,,KeyError} exception is raised if the
method was called as @ref{3ab7,,remove()} or @ref{3abb,,__delitem__()} but no
exception is raised if the method was called as @ref{3ab8,,discard()}. The
behavior of @ref{3ab8,,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{3abc}
@deffn {方法} __setitem__ (key, message)

Replace the message corresponding to `key' with `message'. Raise a
@ref{5df,,KeyError} exception if no message already corresponds to `key'.

As with @ref{144c,,add()}, parameter `message' may be a @ref{1451,,Message}
instance, an @ref{57b,,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 @ref{1451,,Message} subclass
(e.g., if it's an @ref{3976,,mboxMessage} instance and this is an
@ref{194a,,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{3abd}
@deffn {方法} iterkeys ()

Return an @ref{4c3,,iterator} over all keys
@end deffn

@geindex keys() (mailbox.Mailbox 的方法)
@anchor{library/mailbox mailbox Mailbox keys}@anchor{3abe}
@deffn {方法} keys ()

The same as @ref{3abd,,iterkeys()}, except that a @ref{24d,,list} is returned
rather than an @ref{4c3,,iterator}
@end deffn

@geindex itervalues() (mailbox.Mailbox 的方法)
@geindex __iter__() (mailbox.Mailbox 的方法)
@anchor{library/mailbox mailbox Mailbox itervalues}@anchor{3abf}
@deffn {方法} itervalues ()
@anchor{library/mailbox mailbox Mailbox __iter__}@anchor{3ac0}
@deffnx {方法} __iter__ ()

Return an @ref{4c3,,iterator} over representations of all messages.
The messages are represented
as instances of the appropriate format-specific @ref{1451,,Message} subclass
unless a custom message factory was specified when the @code{Mailbox}
instance was initialized.

@cartouche
@quotation 備註 
The behavior of @ref{3ac0,,__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{3ac1}
@deffn {方法} values ()

The same as @ref{3abf,,itervalues()}, except that a @ref{24d,,list} is returned
rather than an @ref{4c3,,iterator}
@end deffn

@geindex iteritems() (mailbox.Mailbox 的方法)
@anchor{library/mailbox mailbox Mailbox iteritems}@anchor{3ac2}
@deffn {方法} iteritems ()

Return an @ref{4c3,,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{1451,,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{3ac3}
@deffn {方法} items ()

The same as @ref{3ac2,,iteritems()}, except that a @ref{24d,,list} of pairs is
returned rather than an @ref{4c3,,iterator} of pairs.
@end deffn

@geindex get() (mailbox.Mailbox 的方法)
@geindex __getitem__() (mailbox.Mailbox 的方法)
@anchor{library/mailbox mailbox Mailbox get}@anchor{3ac4}
@deffn {方法} get (key, default=None)
@anchor{library/mailbox mailbox Mailbox __getitem__}@anchor{3ac5}
@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
@ref{3ac4,,get()} and a @ref{5df,,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{1451,,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{3ac6}
@deffn {方法} get_message (key)

Return a representation of the message corresponding to `key' as an
instance of the appropriate format-specific @ref{1451,,Message} subclass, or
raise a @ref{5df,,KeyError} exception if no such message exists.
@end deffn

@geindex get_bytes() (mailbox.Mailbox 的方法)
@anchor{library/mailbox mailbox Mailbox get_bytes}@anchor{144f}
@deffn {方法} get_bytes (key)

Return a byte representation of the message corresponding to `key', or
raise a @ref{5df,,KeyError} exception if no such message exists.


在 3.2 版被加入.

@end deffn

@geindex get_string() (mailbox.Mailbox 的方法)
@anchor{library/mailbox mailbox Mailbox get_string}@anchor{1450}
@deffn {方法} get_string (key)

Return a string representation of the message corresponding to `key', or
raise a @ref{5df,,KeyError} exception if no such message exists.  The
message is processed through @ref{57b,,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{144e}
@deffn {方法} get_file (key)

Return a @ref{28ad,,file-like} representation of the
message corresponding to `key',
or raise a @ref{5df,,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{1f35,,binary file}; previously it was
incorrectly returned in text mode.  Also, the @ref{28ad,,file-like object}
now supports the @ref{1e1,,context manager} protocol: you can use a
@ref{186,,with} statement to automatically close it.


@cartouche
@quotation 備註 
Unlike other representations of messages,
@ref{28ad,,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{3ac7}
@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{3ac8}
@deffn {方法} __len__ ()

Return a count of messages in the mailbox.
@end deffn

@geindex clear() (mailbox.Mailbox 的方法)
@anchor{library/mailbox mailbox Mailbox clear}@anchor{3ac9}
@deffn {方法} clear ()

Delete all messages from the mailbox.
@end deffn

@geindex pop() (mailbox.Mailbox 的方法)
@anchor{library/mailbox mailbox Mailbox pop}@anchor{3aca}
@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{1451,,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{3acb}
@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{5df,,KeyError} exception. The
message is represented as an instance of the appropriate format-specific
@ref{1451,,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{3acc}
@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{3abc,,__setitem__()}. As with @ref{3abc,,__setitem__()},
each `key' must already correspond to a message in the mailbox or else a
@ref{5df,,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{1914}
@deffn {方法} flush ()

Write any pending changes to the filesystem. For some @ref{144d,,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{3ab9}
@deffn {方法} lock ()

Acquire an exclusive advisory lock on the mailbox so that other processes
know not to modify it. An @ref{3acd,,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{3aba}
@deffn {方法} unlock ()

Release the lock on the mailbox, if any.
@end deffn

@geindex close() (mailbox.Mailbox 的方法)
@anchor{library/mailbox mailbox Mailbox close}@anchor{3ace}
@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
* Mailbox 物件: Mailbox 物件<2>. 
* mbox 物件:: 
* MH 物件:: 
* Babyl 物件:: 
* MMDF 物件:: 

@end menu

@node Mailbox 物件<2>,mbox 物件,,Mailbox 物件
@anchor{library/mailbox mailbox-maildir}@anchor{3acf}@anchor{library/mailbox maildir-objects}@anchor{3ad0}
@subsubsection @code{Mailbox} 物件


@geindex Maildir (mailbox 中的類別)
@anchor{library/mailbox mailbox Maildir}@anchor{656}
@deffn {類別} mailbox.Maildir (dirname, factory=None, create=True)

A subclass of @ref{144d,,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{3ad1,,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{3ad2}
@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 版的變更: @ref{656,,Maildir} now ignores files with a leading dot.


@code{Maildir} instances have all of the methods of @ref{144d,,Mailbox} in
addition to the following:

@geindex list_folders() (mailbox.Maildir 的方法)
@anchor{library/mailbox mailbox Maildir list_folders}@anchor{3ad3}
@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{3ad4}
@deffn {方法} get_folder (folder)

Return a @code{Maildir} instance representing the folder whose name is
`folder'. A @ref{3ad5,,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{3ad6}
@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{3ad7}
@deffn {方法} remove_folder (folder)

Delete the folder whose name is `folder'. If the folder contains any
messages, a @ref{3ad8,,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{3ad9}
@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{1997}
@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{3ad1,,MaildirMessage} object, use
its @ref{3ada,,get_flags()} method instead, because
changes made by the message's @ref{3adb,,set_flags()},
@ref{3adc,,add_flag()} and @ref{3add,,remove_flag()}
methods are not reflected here until the mailbox's
@ref{3ade,,__setitem__()} method is called.


在 3.13 版被加入.

@end deffn

@geindex set_flags() (mailbox.Maildir 的方法)
@anchor{library/mailbox mailbox Maildir set_flags}@anchor{1998}
@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{3ad1,,MaildirMessage} object, use
its @ref{3adb,,set_flags()} method instead, because
changes made with this mailbox method will not be visible to the
message object's method, @ref{3ada,,get_flags()}.


在 3.13 版被加入.

@end deffn

@geindex add_flag() (mailbox.Maildir 的方法)
@anchor{library/mailbox mailbox Maildir add_flag}@anchor{1999}
@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{3adc,,add_flag()} method are similar to
those for @ref{1998,,set_flags()}; see the discussion there.


在 3.13 版被加入.

@end deffn

@geindex remove_flag() (mailbox.Maildir 的方法)
@anchor{library/mailbox mailbox Maildir remove_flag}@anchor{199a}
@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{3add,,remove_flag()} method are similar to
those for @ref{1998,,set_flags()}; see the discussion there.


在 3.13 版被加入.

@end deffn

@geindex get_info() (mailbox.Maildir 的方法)
@anchor{library/mailbox mailbox Maildir get_info}@anchor{1995}
@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{3ad1,,MaildirMessage} object, use
its @ref{3adf,,get_info()} method instead, because
changes made by the message's @ref{3ae0,,set_info()} method
are not reflected here until the mailbox's @ref{3ade,,__setitem__()} method
is called.


在 3.13 版被加入.

@end deffn

@geindex set_info() (mailbox.Maildir 的方法)
@anchor{library/mailbox mailbox Maildir set_info}@anchor{1996}
@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{3ad1,,MaildirMessage} object, use
its @ref{3ae0,,set_info()} method instead, because
changes made with this mailbox method will not be visible to the
message object's method, @ref{3adf,,get_info()}.


在 3.13 版被加入.

@end deffn

Some @ref{144d,,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{3ae1}
@deffn {方法} add (message)
@anchor{library/mailbox mailbox Maildir __setitem__}@anchor{3ade}
@deffnx {方法} __setitem__ (key, message)
@anchor{library/mailbox mailbox Maildir update}@anchor{3ae2}
@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{3ae3}
@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{3ae4}
@deffn {方法} lock ()
@anchor{library/mailbox mailbox Maildir unlock}@anchor{3ae5}
@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{3ae6}
@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{3ae7}
@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 物件,MH 物件,Mailbox 物件<2>,Mailbox 物件
@anchor{library/mailbox mailbox-mbox}@anchor{3ae8}@anchor{library/mailbox mbox-objects}@anchor{3ae9}
@subsubsection @code{mbox} 物件


@geindex mbox (mailbox 中的類別)
@anchor{library/mailbox mailbox mbox}@anchor{194a}
@deffn {類別} mailbox.mbox (path, factory=None, create=True)

A subclass of @ref{144d,,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{3976,,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{144d,,Mailbox} methods implemented by @code{mbox} deserve special
remarks:

@geindex get_bytes() (mailbox.mbox 的方法)
@anchor{library/mailbox mailbox mbox get_bytes}@anchor{3aea}
@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{3aeb}
@deffn {方法} get_file (key, from_=False)

Using the file after calling @ref{1914,,flush()} or
@ref{3ace,,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{3aec}
@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{3aed}
@deffn {方法} lock ()
@anchor{library/mailbox mailbox mbox unlock}@anchor{3aee}
@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 物件,Babyl 物件,mbox 物件,Mailbox 物件
@anchor{library/mailbox mailbox-mh}@anchor{3aef}@anchor{library/mailbox mh-objects}@anchor{3af0}
@subsubsection @code{MH} 物件


@geindex MH (mailbox 中的類別)
@anchor{library/mailbox mailbox MH}@anchor{197e}
@deffn {類別} mailbox.MH (path, factory=None, create=True)

A subclass of @ref{144d,,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{3af1,,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{144d,,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{3af2}
@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{3af3}
@deffn {方法} get_folder (folder)

Return an @code{MH} instance representing the folder whose name is
`folder'. A @ref{3ad5,,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{3af4}
@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{3af5}
@deffn {方法} remove_folder (folder)

Delete the folder whose name is `folder'. If the folder contains any
messages, a @ref{3ad8,,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{3af6}
@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{3af7}
@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{3af6,,get_sequences()}.
@end deffn

@geindex pack() (mailbox.MH 的方法)
@anchor{library/mailbox mailbox MH pack}@anchor{3af8}
@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{144d,,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{3af9}
@deffn {方法} remove (key)
@anchor{library/mailbox mailbox MH __delitem__}@anchor{3afa}
@deffnx {方法} __delitem__ (key)
@anchor{library/mailbox mailbox MH discard}@anchor{3afb}
@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{3afc}
@deffn {方法} lock ()
@anchor{library/mailbox mailbox MH unlock}@anchor{3afd}
@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{3afe}
@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{3aff}
@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{3b00}
@deffn {方法} close ()

@code{MH} instances do not keep any open files, so this method is
equivalent to @ref{3afd,,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 物件,MMDF 物件,MH 物件,Mailbox 物件
@anchor{library/mailbox babyl-objects}@anchor{3b01}@anchor{library/mailbox mailbox-babyl}@anchor{3b02}
@subsubsection @code{Babyl} 物件


@geindex Babyl (mailbox 中的類別)
@anchor{library/mailbox mailbox Babyl}@anchor{3b03}
@deffn {類別} mailbox.Babyl (path, factory=None, create=True)

A subclass of @ref{144d,,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{3b04,,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{144d,,Mailbox} in
addition to the following:

@geindex get_labels() (mailbox.Babyl 的方法)
@anchor{library/mailbox mailbox Babyl get_labels}@anchor{3b05}
@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{144d,,Mailbox} methods implemented by @code{Babyl} deserve special
remarks:

@geindex get_file() (mailbox.Babyl 的方法)
@anchor{library/mailbox mailbox Babyl get_file}@anchor{3b06}
@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{109f,,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{3b07}
@deffn {方法} lock ()
@anchor{library/mailbox mailbox Babyl unlock}@anchor{3b08}
@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 物件,,Babyl 物件,Mailbox 物件
@anchor{library/mailbox mailbox-mmdf}@anchor{3b09}@anchor{library/mailbox mmdf-objects}@anchor{3b0a}
@subsubsection @code{MMDF} 物件


@geindex MMDF (mailbox 中的類別)
@anchor{library/mailbox mailbox MMDF}@anchor{194b}
@deffn {類別} mailbox.MMDF (path, factory=None, create=True)

A subclass of @ref{144d,,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{3b0b,,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{144d,,Mailbox} methods implemented by @code{MMDF} deserve special
remarks:

@geindex get_bytes() (mailbox.MMDF 的方法)
@anchor{library/mailbox mailbox MMDF get_bytes}@anchor{3b0c}
@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{3b0d}
@deffn {方法} get_file (key, from_=False)

Using the file after calling @ref{1914,,flush()} or
@ref{3ace,,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{3b0e}
@deffn {方法} lock ()
@anchor{library/mailbox mailbox MMDF unlock}@anchor{3b0f}
@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 物件,例外<19>,Mailbox 物件,mailbox --- 以各種格式操作郵件信箱
@anchor{library/mailbox mailbox-message-objects}@anchor{3b10}@anchor{library/mailbox message-objects}@anchor{3b11}
@subsubsection @code{Message} 物件


@geindex Message (mailbox 中的類別)
@anchor{library/mailbox mailbox Message}@anchor{1451}
@deffn {類別} mailbox.Message (message=None)

A subclass of the @ref{48,,email.message} module's
@ref{57b,,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{57b,,email.message.Message} instance, its contents are
copied; furthermore, any format-specific information is converted insofar as
possible if `message' is a @code{Message} instance. If `message' is a string,
a byte string,
or a file, it should contain an 
@geindex RFC; RFC 2822
RFC 2822@footnote{https://datatracker.ietf.org/doc/html/rfc2822.html}-compliant message, which is read
and parsed.  Files should be open in binary mode, but text mode files
are accepted for backward compatibility.

The format-specific state and behaviors offered by subclasses vary, but in
general it is only the properties that are not specific to a particular
mailbox that are supported (although presumably the properties are specific
to a particular mailbox format). For example, file offsets for single-file
mailbox formats and file names for directory-based mailbox formats are not
retained, because they are only applicable to the original mailbox. But state
such as whether a message has been read by the user or marked as important is
retained, because it applies to the message itself.

There is no requirement that @code{Message} instances be used to represent
messages retrieved using @ref{144d,,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 物件:: 
* mboxMessage 物件:: 
* MHMessage 物件:: 
* BabylMessage 物件:: 
* MMDFMessage 物件:: 

@end menu

@node MaildirMessage 物件,mboxMessage 物件,,Message 物件
@anchor{library/mailbox mailbox-maildirmessage}@anchor{3b12}@anchor{library/mailbox maildirmessage-objects}@anchor{3b13}
@subsubsection @code{MaildirMessage} 物件


@geindex MaildirMessage (mailbox 中的類別)
@anchor{library/mailbox mailbox MaildirMessage}@anchor{3ad1}
@deffn {類別} mailbox.MaildirMessage (message=None)

A message with Maildir-specific behaviors. Parameter `message' has the same
meaning as with the @ref{1451,,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

旗標

@tab

含義

@tab

解釋

@item

D

@tab

草稿

@tab

編輯中

@item

F

@tab

已標記

@tab

標記為重要

@item

P

@tab

Passed

@tab

Forwarded, resent, or bounced

@item

R

@tab

已回覆

@tab

Replied to

@item

S

@tab

已查看

@tab

Read

@item

T

@tab

Trashed

@tab

Marked for subsequent deletion

@end multitable


@code{MaildirMessage} 實例提供以下方法：

@geindex get_subdir() (mailbox.MaildirMessage 的方法)
@anchor{library/mailbox mailbox MaildirMessage get_subdir}@anchor{3b14}
@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{3b15}
@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{3ada}
@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{3adb}
@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{3adc}
@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{3add}
@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' maybe a string of more than
one character.  If "info" contains experimental information rather than
flags, the current "info" is not modified.
@end deffn

@geindex get_date() (mailbox.MaildirMessage 的方法)
@anchor{library/mailbox mailbox MaildirMessage get_date}@anchor{3b16}
@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{3b17}
@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{3adf}
@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{3ae0}
@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{3976,,mboxMessage} or @ref{3b0b,,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{3976,,mboxMessage} 或 @ref{3b0b,,MMDFMessage} 狀態

@item

"cur" 子目錄

@tab

O 旗標

@item

F 旗標

@tab

F 旗標

@item

R 旗標

@tab

A 旗標

@item

S 旗標

@tab

R 旗標

@item

T 旗標

@tab

D 旗標

@end multitable


When a @code{MaildirMessage} instance is created based upon an
@ref{3af1,,MHMessage} instance, the following conversions take place:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Resulting state

@tab

@ref{3af1,,MHMessage} 狀態

@item

"cur" 子目錄

@tab

"unseen" 序列

@item

"cur" 子目錄和 S 旗標

@tab

沒有 "unseen" 序列

@item

F 旗標

@tab

"flagged" 序列

@item

R 旗標

@tab

"replied" 序列

@end multitable


When a @code{MaildirMessage} instance is created based upon a
@ref{3b04,,BabylMessage} instance, the following conversions take place:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Resulting state

@tab

@ref{3b04,,BabylMessage} 狀態

@item

"cur" 子目錄

@tab

"unseen" 標籤

@item

"cur" 子目錄和 S 旗標

@tab

沒有 "unseen" 標籤

@item

P 旗標

@tab

"forwarded" 或 "resent" 標籤

@item

R 旗標

@tab

"answered" 標籤

@item

T 旗標

@tab

"deleted" 標籤

@end multitable


@node mboxMessage 物件,MHMessage 物件,MaildirMessage 物件,Message 物件
@anchor{library/mailbox mailbox-mboxmessage}@anchor{3b18}@anchor{library/mailbox mboxmessage-objects}@anchor{3b19}
@subsubsection @code{mboxMessage} 物件


@geindex mboxMessage (mailbox 中的類別)
@anchor{library/mailbox mailbox mboxMessage}@anchor{3976}
@deffn {類別} mailbox.mboxMessage (message=None)

A message with mbox-specific behaviors. Parameter `message' has the same meaning
as with the @ref{1451,,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

旗標

@tab

含義

@tab

解釋

@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

已標記

@tab

標記為重要

@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} 實例提供以下方法：

@geindex get_from() (mailbox.mboxMessage 的方法)
@anchor{library/mailbox mailbox mboxMessage get_from}@anchor{3b1a}
@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{3b1b}
@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{ee1,,time.struct_time} instance, a
tuple suitable for passing to @ref{13ea,,time.strftime()}, or @code{True} (to use
@ref{13c1,,time.gmtime()}).
@end deffn

@geindex get_flags() (mailbox.mboxMessage 的方法)
@anchor{library/mailbox mailbox mboxMessage get_flags}@anchor{3b1c}
@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{3b1d}
@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{3b1e}
@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{3b1f}
@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' maybe a string of more than
one character.
@end deffn
@end deffn

When an @code{mboxMessage} instance is created based upon a
@ref{3ad1,,MaildirMessage} instance, a "From " line is generated based upon the
@ref{3ad1,,MaildirMessage} instance's delivery date, and the following conversions
take place:


@multitable {xxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Resulting state

@tab

@ref{3ad1,,MaildirMessage} 狀態

@item

R 旗標

@tab

S 旗標

@item

O 旗標

@tab

"cur" 子目錄

@item

D 旗標

@tab

T 旗標

@item

F 旗標

@tab

F 旗標

@item

A 旗標

@tab

R 旗標

@end multitable


When an @code{mboxMessage} instance is created based upon an
@ref{3af1,,MHMessage} instance, the following conversions take place:


@multitable {xxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Resulting state

@tab

@ref{3af1,,MHMessage} 狀態

@item

R 旗標和 O 旗標

@tab

沒有 "unseen" 序列

@item

O 旗標

@tab

"unseen" 序列

@item

F 旗標

@tab

"flagged" 序列

@item

A 旗標

@tab

"replied" 序列

@end multitable


When an @code{mboxMessage} instance is created based upon a
@ref{3b04,,BabylMessage} instance, the following conversions take place:


@multitable {xxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Resulting state

@tab

@ref{3b04,,BabylMessage} 狀態

@item

R 旗標和 O 旗標

@tab

沒有 "unseen" 標籤

@item

O 旗標

@tab

"unseen" 標籤

@item

D 旗標

@tab

"deleted" 標籤

@item

A 旗標

@tab

"answered" 標籤

@end multitable


When a @code{mboxMessage} instance is created based upon an
@ref{3b0b,,MMDFMessage}
instance, the "From " line is copied and all flags directly correspond:


@multitable {xxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Resulting state

@tab

@ref{3b0b,,MMDFMessage} 狀態

@item

R 旗標

@tab

R 旗標

@item

O 旗標

@tab

O 旗標

@item

D 旗標

@tab

D 旗標

@item

F 旗標

@tab

F 旗標

@item

A 旗標

@tab

A 旗標

@end multitable


@node MHMessage 物件,BabylMessage 物件,mboxMessage 物件,Message 物件
@anchor{library/mailbox mailbox-mhmessage}@anchor{3b20}@anchor{library/mailbox mhmessage-objects}@anchor{3b21}
@subsubsection @code{MHMessage} 物件


@geindex MHMessage (mailbox 中的類別)
@anchor{library/mailbox mailbox MHMessage}@anchor{3af1}
@deffn {類別} mailbox.MHMessage (message=None)

A message with MH-specific behaviors. Parameter `message' has the same meaning
as with the @ref{1451,,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

解釋

@item

unseen

@tab

Not read, but previously detected by MUA

@item

replied

@tab

Replied to

@item

flagged

@tab

標記為重要

@end multitable


@code{MHMessage} 實例提供以下方法：

@geindex get_sequences() (mailbox.MHMessage 的方法)
@anchor{library/mailbox mailbox MHMessage get_sequences}@anchor{3b22}
@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{3b23}
@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{3b24}
@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{3b25}
@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{3ad1,,MaildirMessage} instance, the following conversions take place:


@multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Resulting state

@tab

@ref{3ad1,,MaildirMessage} 狀態

@item

"unseen" 序列

@tab

無 S 旗標

@item

"replied" 序列

@tab

R 旗標

@item

"flagged" 序列

@tab

F 旗標

@end multitable


When an @code{MHMessage} instance is created based upon an
@ref{3976,,mboxMessage} or @ref{3b0b,,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{3976,,mboxMessage} 或 @ref{3b0b,,MMDFMessage} 狀態

@item

"unseen" 序列

@tab

無 R 旗標

@item

"replied" 序列

@tab

A 旗標

@item

"flagged" 序列

@tab

F 旗標

@end multitable


When an @code{MHMessage} instance is created based upon a
@ref{3b04,,BabylMessage} instance, the following conversions take place:


@multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Resulting state

@tab

@ref{3b04,,BabylMessage} 狀態

@item

"unseen" 序列

@tab

"unseen" 標籤

@item

"replied" 序列

@tab

"answered" 標籤

@end multitable


@node BabylMessage 物件,MMDFMessage 物件,MHMessage 物件,Message 物件
@anchor{library/mailbox babylmessage-objects}@anchor{3b26}@anchor{library/mailbox mailbox-babylmessage}@anchor{3b27}
@subsubsection @code{BabylMessage} 物件


@geindex BabylMessage (mailbox 中的類別)
@anchor{library/mailbox mailbox BabylMessage}@anchor{3b04}
@deffn {類別} mailbox.BabylMessage (message=None)

A message with Babyl-specific behaviors. Parameter `message' has the same
meaning as with the @ref{1451,,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

解釋

@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} 實例提供以下方法：

@geindex get_labels() (mailbox.BabylMessage 的方法)
@anchor{library/mailbox mailbox BabylMessage get_labels}@anchor{3b28}
@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{3b29}
@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{3b2a}
@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{3b2b}
@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{3b2c}
@deffn {方法} get_visible ()

Return a @ref{1451,,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{3b2d}
@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{1451,,Message} instance, an
@ref{57b,,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{3b2e}
@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{3ad1,,MaildirMessage} instance, the following conversions take place:


@multitable {xxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Resulting state

@tab

@ref{3ad1,,MaildirMessage} 狀態

@item

"unseen" 標籤

@tab

無 S 旗標

@item

"deleted" 標籤

@tab

T 旗標

@item

"answered" 標籤

@tab

R 旗標

@item

"forwarded" 標籤

@tab

P 旗標

@end multitable


When a @code{BabylMessage} instance is created based upon an
@ref{3976,,mboxMessage} or @ref{3b0b,,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{3976,,mboxMessage} 或 @ref{3b0b,,MMDFMessage} 狀態

@item

"unseen" 標籤

@tab

無 R 旗標

@item

"deleted" 標籤

@tab

D 旗標

@item

"answered" 標籤

@tab

A 旗標

@end multitable


When a @code{BabylMessage} instance is created based upon an
@ref{3af1,,MHMessage} instance, the following conversions take place:


@multitable {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Resulting state

@tab

@ref{3af1,,MHMessage} 狀態

@item

"unseen" 標籤

@tab

"unseen" 序列

@item

"answered" 標籤

@tab

"replied" 序列

@end multitable


@node MMDFMessage 物件,,BabylMessage 物件,Message 物件
@anchor{library/mailbox mailbox-mmdfmessage}@anchor{3b2f}@anchor{library/mailbox mmdfmessage-objects}@anchor{3b30}
@subsubsection @code{MMDFMessage} 物件


@geindex MMDFMessage (mailbox 中的類別)
@anchor{library/mailbox mailbox MMDFMessage}@anchor{3b0b}
@deffn {類別} mailbox.MMDFMessage (message=None)

A message with MMDF-specific behaviors. Parameter `message' has the same meaning
as with the @ref{1451,,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

旗標

@tab

含義

@tab

解釋

@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

已標記

@tab

標記為重要

@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{3976,,mboxMessage}:

@geindex get_from() (mailbox.MMDFMessage 的方法)
@anchor{library/mailbox mailbox MMDFMessage get_from}@anchor{3b31}
@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{3b32}
@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{ee1,,time.struct_time} instance, a
tuple suitable for passing to @ref{13ea,,time.strftime()}, or @code{True} (to use
@ref{13c1,,time.gmtime()}).
@end deffn

@geindex get_flags() (mailbox.MMDFMessage 的方法)
@anchor{library/mailbox mailbox MMDFMessage get_flags}@anchor{3b33}
@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{3b34}
@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{3b35}
@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{3b36}
@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' maybe a string of more than
one character.
@end deffn
@end deffn

When an @code{MMDFMessage} instance is created based upon a
@ref{3ad1,,MaildirMessage} instance, a "From " line is generated based upon the
@ref{3ad1,,MaildirMessage} instance's delivery date, and the following conversions
take place:


@multitable {xxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Resulting state

@tab

@ref{3ad1,,MaildirMessage} 狀態

@item

R 旗標

@tab

S 旗標

@item

O 旗標

@tab

"cur" 子目錄

@item

D 旗標

@tab

T 旗標

@item

F 旗標

@tab

F 旗標

@item

A 旗標

@tab

R 旗標

@end multitable


When an @code{MMDFMessage} instance is created based upon an
@ref{3af1,,MHMessage} instance, the following conversions take place:


@multitable {xxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Resulting state

@tab

@ref{3af1,,MHMessage} 狀態

@item

R 旗標和 O 旗標

@tab

沒有 "unseen" 序列

@item

O 旗標

@tab

"unseen" 序列

@item

F 旗標

@tab

"flagged" 序列

@item

A 旗標

@tab

"replied" 序列

@end multitable


When an @code{MMDFMessage} instance is created based upon a
@ref{3b04,,BabylMessage} instance, the following conversions take place:


@multitable {xxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Resulting state

@tab

@ref{3b04,,BabylMessage} 狀態

@item

R 旗標和 O 旗標

@tab

沒有 "unseen" 標籤

@item

O 旗標

@tab

"unseen" 標籤

@item

D 旗標

@tab

"deleted" 標籤

@item

A 旗標

@tab

"answered" 標籤

@end multitable


When an @code{MMDFMessage} instance is created based upon an
@ref{3976,,mboxMessage} instance, the "From " line is copied and all flags directly
correspond:


@multitable {xxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Resulting state

@tab

@ref{3976,,mboxMessage} 狀態

@item

R 旗標

@tab

R 旗標

@item

O 旗標

@tab

O 旗標

@item

D 旗標

@tab

D 旗標

@item

F 旗標

@tab

F 旗標

@item

A 旗標

@tab

A 旗標

@end multitable


@node 例外<19>,範例<30>,Message 物件,mailbox --- 以各種格式操作郵件信箱
@anchor{library/mailbox exceptions}@anchor{3b37}
@subsubsection 例外


The following exception classes are defined in the @code{mailbox} module:

@geindex Error
@anchor{library/mailbox mailbox Error}@anchor{3b38}
@deffn {例外} mailbox.Error

The based class for all other module-specific exceptions.
@end deffn

@geindex NoSuchMailboxError
@anchor{library/mailbox mailbox NoSuchMailboxError}@anchor{3ad5}
@deffn {例外} mailbox.NoSuchMailboxError

Raised when a mailbox is expected but is not found, such as when instantiating a
@ref{144d,,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{3ad8}
@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{3acd}
@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 a lock, or when a uniquely generated file name
already exists.
@end deffn

@geindex FormatError
@anchor{library/mailbox mailbox FormatError}@anchor{3b39}
@deffn {例外} mailbox.FormatError

Raised when the data in a file cannot be parsed, such as when an @ref{197e,,MH}
instance attempts to read a corrupted @code{.mh_sequences} file.
@end deffn

@node 範例<30>,,例外<19>,mailbox --- 以各種格式操作郵件信箱
@anchor{library/mailbox examples}@anchor{3b3a}@anchor{library/mailbox mailbox-examples}@anchor{3b3b}
@subsubsection 範例


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']       # 可能為 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 --- 將檔案名稱對映到 MIME 類型,base64 --- Base16、Base32、Base64、Base85 資料編碼,mailbox --- 以各種格式操作郵件信箱,網際網路資料處理
@anchor{library/mimetypes doc}@anchor{3b3c}@anchor{library/mimetypes mimetypes-map-filenames-to-mime-types}@anchor{3b3d}@anchor{library/mimetypes module-mimetypes}@anchor{93}@anchor{library/mimetypes translation-repo}@anchor{3b3e}
@subsection @code{mimetypes} --- 將檔案名稱對映到 MIME 類型


@geindex module; mimetypes

`原始碼：'Lib/mimetypes.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/mimetypes.py}

@geindex MIME;content type（內容類型）


__________________________________________________________________


The @ref{93,,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{3b3f,,init()} if they rely on
the information @ref{3b3f,,init()} sets up.

@geindex guess_type() (於 mimetypes 模組中)
@anchor{library/mimetypes mimetypes guess_type}@anchor{512}
@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{59b,,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 版的變更: 新增 `url' 做為 @ref{59b,,path-like object} 的支援。



在 3.13 版之後被棄用: Passing a file path instead of URL is @ref{23d,,soft deprecated}.
Use @ref{511,,guess_file_type()} for this.

@end deffn

@geindex guess_file_type() (於 mimetypes 模組中)
@anchor{library/mimetypes mimetypes guess_file_type}@anchor{511}
@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{512,,guess_type()} function, but accepts a path instead of URL.
Path can be a string, a bytes object or a @ref{59b,,path-like object}.


在 3.13 版被加入.

@end deffn

@geindex guess_all_extensions() (於 mimetypes 模組中)
@anchor{library/mimetypes mimetypes guess_all_extensions}@anchor{1b4c}
@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{512,,guess_type()} and @ref{511,,guess_file_type()}.

The optional `strict' argument has the same meaning as with the @ref{512,,guess_type()} function.
@end deffn

@geindex guess_extension() (於 mimetypes 模組中)
@anchor{library/mimetypes mimetypes guess_extension}@anchor{3b40}
@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{512,,guess_type()} and @ref{511,,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{512,,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{3b3f}
@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{3b41,,knownfiles}; on Windows, the
current registry settings are loaded.  Each file named in `files' or
@ref{3b41,,knownfiles} takes precedence over those named before it.  Calling
@ref{3b3f,,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{1bf8}
@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{3b42}
@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{3b43}
@deffn {資料} mimetypes.inited

Flag indicating whether or not the global data structures have been initialized.
This is set to @code{True} by @ref{3b3f,,init()}.
@end deffn

@geindex knownfiles (於 mimetypes 模組中)
@anchor{library/mimetypes mimetypes knownfiles}@anchor{3b41}
@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{3b44}
@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{3b45}
@deffn {資料} mimetypes.encodings_map

Dictionary mapping filename extensions to encoding types.
@end deffn

@geindex types_map (於 mimetypes 模組中)
@anchor{library/mimetypes mimetypes types_map}@anchor{3b46}
@deffn {資料} mimetypes.types_map

Dictionary mapping filename extensions to MIME types.
@end deffn

@geindex common_types (於 mimetypes 模組中)
@anchor{library/mimetypes mimetypes common_types}@anchor{3b47}
@deffn {資料} mimetypes.common_types

Dictionary mapping filename extensions to non-standard, but commonly found MIME
types.
@end deffn

模組的使用範例：

@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 物件:: 
* 命令列用法: 命令列用法<4>. 
* Command-line example:: 

@end menu

@node MimeTypes 物件,命令列用法<4>,,mimetypes --- 將檔案名稱對映到 MIME 類型
@anchor{library/mimetypes id1}@anchor{3b48}@anchor{library/mimetypes mimetypes-objects}@anchor{3b49}
@subsubsection MimeTypes 物件


The @ref{16ef,,MimeTypes} class may be useful for applications which may want more
than one MIME-type database; it provides an interface similar to the one of the
@ref{93,,mimetypes} module.

@geindex MimeTypes (mimetypes 中的類別)
@anchor{library/mimetypes mimetypes MimeTypes}@anchor{16ef}
@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{3b4a,,read()} or
@ref{3b4b,,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{3b4c}
@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{3b44,,suffix_map} defined in the module.
@end deffn

@geindex encodings_map (mimetypes.MimeTypes 的屬性)
@anchor{library/mimetypes mimetypes MimeTypes encodings_map}@anchor{3b4d}
@deffn {屬性} encodings_map

Dictionary mapping filename extensions to encoding types.  This is initially a
copy of the global @ref{3b45,,encodings_map} defined in the module.
@end deffn

@geindex types_map (mimetypes.MimeTypes 的屬性)
@anchor{library/mimetypes mimetypes MimeTypes types_map}@anchor{3b4e}
@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{3b47,,common_types} and
@ref{3b46,,types_map}.
@end deffn

@geindex types_map_inv (mimetypes.MimeTypes 的屬性)
@anchor{library/mimetypes mimetypes MimeTypes types_map_inv}@anchor{3b4f}
@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{3b47,,common_types} and @ref{3b46,,types_map}.
@end deffn

@geindex guess_extension() (mimetypes.MimeTypes 的方法)
@anchor{library/mimetypes mimetypes MimeTypes guess_extension}@anchor{3b50}
@deffn {方法} guess_extension (type, strict=True)

Similar to the @ref{3b40,,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{1ce1}
@deffn {方法} guess_type (url, strict=True)

Similar to the @ref{512,,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{3b51}
@deffn {方法} guess_file_type (path, *, strict=True)

Similar to the @ref{511,,guess_file_type()} function, using the tables stored
as part of the object.


在 3.13 版被加入.

@end deffn

@geindex guess_all_extensions() (mimetypes.MimeTypes 的方法)
@anchor{library/mimetypes mimetypes MimeTypes guess_all_extensions}@anchor{3b52}
@deffn {方法} guess_all_extensions (type, strict=True)

Similar to the @ref{1b4c,,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{3b4a}
@deffn {方法} read (filename, strict=True)

Load MIME information from a file named `filename'.  This uses @ref{3b4b,,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{3b4b}
@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{3b53}
@deffn {方法} read_windows_registry (strict=True)

Load MIME type information from the Windows registry.

@ref{2006,,可用性}: Windows.

If `strict' is @code{True}, information will be added to the list of standard
types, else to the list of non-standard types.


在 3.2 版被加入.

@end deffn

@geindex add_type() (mimetypes.MimeTypes 的方法)
@anchor{library/mimetypes mimetypes MimeTypes add_type}@anchor{318}
@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.


Deprecated since version 3.14, will be removed in version 3.16: Invalid, undotted extensions will raise a
@ref{2eb,,ValueError} in Python 3.16.

@end deffn
@end deffn

@node 命令列用法<4>,Command-line example,MimeTypes 物件,mimetypes --- 將檔案名稱對映到 MIME 類型
@anchor{library/mimetypes command-line-usage}@anchor{3b54}@anchor{library/mimetypes mimetypes-cli}@anchor{247}
@subsubsection 命令列用法


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 命令列選項; -h
@geindex mimetypes 命令列選項; --help
@anchor{library/mimetypes cmdoption-mimetypes-h}@anchor{3b55}
@deffn {程式選項} @w{-}h
@anchor{library/mimetypes cmdoption-mimetypes-help}@anchor{3b56}
@deffnx {程式選項} @w{-}@w{-}help

Show the help message and exit.
@end deffn

@geindex mimetypes 命令列選項; -e
@geindex mimetypes 命令列選項; --extension
@anchor{library/mimetypes cmdoption-mimetypes-e}@anchor{3b57}
@deffn {程式選項} @w{-}e
@anchor{library/mimetypes cmdoption-mimetypes-extension}@anchor{3b58}
@deffnx {程式選項} @w{-}@w{-}extension

Guess extension instead of type.
@end deffn

@geindex mimetypes 命令列選項; -l
@geindex mimetypes 命令列選項; --lenient
@anchor{library/mimetypes cmdoption-mimetypes-l}@anchor{3b59}
@deffn {程式選項} @w{-}l
@anchor{library/mimetypes cmdoption-mimetypes-lenient}@anchor{3b5a}
@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,,命令列用法<4>,mimetypes --- 將檔案名稱對映到 MIME 類型
@anchor{library/mimetypes command-line-example}@anchor{3b5b}
@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 資料編碼,binascii --- 在二進位制和 ASCII 之間轉換,mimetypes --- 將檔案名稱對映到 MIME 類型,網際網路資料處理
@anchor{library/base64 doc}@anchor{3b5c}@anchor{library/base64 base64-base16-base32-base64-base85-data-encodings}@anchor{3b5d}@anchor{library/base64 module-base64}@anchor{f}@anchor{library/base64 translation-repo}@anchor{3b5e}
@subsection @code{base64} --- Base16、Base32、Base64、Base85 資料編碼


@geindex module; base64

`原始碼：' Lib/base64.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/base64.py}

@geindex base64;encoding（編碼）
@geindex MIME;base64 encoding（base64 編碼）


__________________________________________________________________


這個模組提供將二進位資料編碼成可顯示 ASCII 字元以及解碼回原始資料的功能。這包括了 
@geindex RFC; RFC 4648
RFC 4648@footnote{https://datatracker.ietf.org/doc/html/rfc4648.html} 中@ref{3b5f,,指定的編碼}（Base64、Base32 和 Base16）和非標準的 @ref{3b60,,Base85 編碼}。

該模組提供了兩個介面。新介面支援將@ref{193,,類位元組物件} 編碼成 ASCII @ref{192,,bytes}，並將包含 ASCII 的@ref{193,,類位元組物件}或字串解碼為 @ref{192,,bytes}。支援 
@geindex RFC; RFC 4648
RFC 4648@footnote{https://datatracker.ietf.org/doc/html/rfc4648.html} 中定義的兩種 base-64 字母表（常見和 URL 安全 (URL-safe) 及檔案系統安全 (filesystem-safe) 字母表）。

@ref{3b61,,舊版介面}不支援從字串解碼，但它提供對@ref{13c4,,檔案物件}進行編碼和解碼的函式。它僅支援 Base64 標準字母表，並且按照 
@geindex RFC; RFC 2045
RFC 2045@footnote{https://datatracker.ietf.org/doc/html/rfc2045.html} 每 76 個字元添加換行字元。請注意，如果你需要 
@geindex RFC; RFC 2045
RFC 2045@footnote{https://datatracker.ietf.org/doc/html/rfc2045.html} 的支援，你可能會需要 @ref{3f,,email} 函式庫。


在 3.3 版的變更: 新介面的解碼功能現在接受 ASCII-only 的 Unicode 字串。



在 3.4 版的變更: 任何@ref{193,,類位元組物件}現在被該模組中的所有編碼和解碼函式接受。新增了對 Ascii85/Base85 的支援。


@menu
* RFC 4648 編碼:: 
* Base85 編碼:: 
* 舊版介面:: 
* 安全性注意事項: 安全性注意事項<2>. 

@end menu

@node RFC 4648 編碼,Base85 編碼,,base64 --- Base16、Base32、Base64、Base85 資料編碼
@anchor{library/base64 base64-rfc-4648}@anchor{3b5f}@anchor{library/base64 rfc-4648-encodings}@anchor{3b62}
@subsubsection RFC 4648 編碼


@geindex RFC; RFC 4648
RFC 4648@footnote{https://datatracker.ietf.org/doc/html/rfc4648.html} 編碼適合對二進位資料進行編碼來使得電子郵件、URL 或是 HTTP POST 內容等傳輸管道能夠安全地傳遞資料。

@geindex b64encode() (於 base64 模組中)
@anchor{library/base64 base64 b64encode}@anchor{3b63}
@deffn {函式} base64.b64encode (s, altchars=None)

使用 Base64 對@ref{193,,類位元組物件} `s' 進行編碼並回傳編碼過的 @ref{192,,bytes}。

可選的 `altchars' 必須是一個長度為 2 的@ref{193,,類位元組物件}，用來指定替代的字母表，以替換 @code{+} 和 @code{/} 字元。這使得應用程式可以生成對 URL 或檔案系統安全的 Base64 字串。預設值為 @code{None}，即使用標準的 Base64 字母表。

如果 `altchars' 的長度不是 2，可以斷言或引發 @ref{2eb,,ValueError}。如果 `altchars' 不是@ref{193,,類位元組物件}，則會引發 @ref{198,,TypeError}。
@end deffn

@geindex b64decode() (於 base64 模組中)
@anchor{library/base64 base64 b64decode}@anchor{1c59}
@deffn {函式} base64.b64decode (s, altchars=None, validate=False)

將經過 Base64 編碼的@ref{193,,類位元組物件}或 ASCII 字串 `s' 解碼，並回傳解碼後的 @ref{192,,bytes}。

可選的 `altchars' 必須是長度為 2 的@ref{193,,類位元組物件}或 ASCII 字串，用於指定替代字母表，取代 @code{+} 和 @code{/} 字元。

如果 `s' 填充 (pad) 不正確，將引發 @ref{1221,,binascii.Error} 例外。

如果 `validate' 為 @code{False}（預設值），在 padding check（填充檢查）之前，不屬於標準 base-64 字母表和替代字母表的字元將被丟棄。如果 `validate' 為 @code{True}，輸入中的這些非字母表字元將導致引發 @ref{1221,,binascii.Error}。

有關嚴格的 base64 檢查的更多資訊，請參閱 @ref{18fb,,binascii.a2b_base64()}。

如果 `altchars' 的長度不是 2，可能會斷言或引發 @ref{2eb,,ValueError}。
@end deffn

@geindex standard_b64encode() (於 base64 模組中)
@anchor{library/base64 base64 standard_b64encode}@anchor{3b64}
@deffn {函式} base64.standard_b64encode (s)

使用標準 Base64 字母表對@ref{193,,類位元組物件} `s' 進行編碼，並回傳編碼後的 @ref{192,,bytes}。
@end deffn

@geindex standard_b64decode() (於 base64 模組中)
@anchor{library/base64 base64 standard_b64decode}@anchor{3b65}
@deffn {函式} base64.standard_b64decode (s)

使用標準 Base64 字母表對@ref{193,,類位元組物件}或 ASCII 字串 `s' 進行解碼，並回傳解碼後的 @ref{192,,bytes}。
@end deffn

@geindex urlsafe_b64encode() (於 base64 模組中)
@anchor{library/base64 base64 urlsafe_b64encode}@anchor{3b66}
@deffn {函式} base64.urlsafe_b64encode (s)

使用 URL 安全和檔案系統安全的字母表對@ref{193,,類位元組物件} `s' 進行編碼，該字母表將標準 Base64 字母表中的 @code{+} 替換為 @code{-}，@code{/} 替換為 @code{_}，並回傳編碼後的 @ref{192,,bytes}。結果仍可能包含 @code{=}。
@end deffn

@geindex urlsafe_b64decode() (於 base64 模組中)
@anchor{library/base64 base64 urlsafe_b64decode}@anchor{3b67}
@deffn {函式} base64.urlsafe_b64decode (s)

使用 URL 安全和檔案系統安全字母表對@ref{193,,類位元組物件}或 ASCII 字串 `s' 進行解碼，該字母表將標準 Base64 字母表中的 @code{+} 替換為 @code{-}，@code{/} 替換為 @code{_}，並回傳解碼後的 @ref{192,,bytes}。
@end deffn

@geindex b32encode() (於 base64 模組中)
@anchor{library/base64 base64 b32encode}@anchor{3b68}
@deffn {函式} base64.b32encode (s)

使用 Base32 對@ref{193,,類位元組物件} `s' 進行編碼，並回傳編碼後的 @ref{192,,bytes}。
@end deffn

@geindex b32decode() (於 base64 模組中)
@anchor{library/base64 base64 b32decode}@anchor{1220}
@deffn {函式} base64.b32decode (s, casefold=False, map01=None)

解碼經過 Base32 編碼的@ref{193,,類位元組物件}或 ASCII 字串 `s'，並回傳解碼後的 @ref{192,,bytes}。

可選的 `casefold' 是一個是否接受小寫字母表作為輸入的旗標。出於安全性考量，預設值為 @code{False}。

@geindex RFC; RFC 4648
RFC 4648@footnote{https://datatracker.ietf.org/doc/html/rfc4648.html} 允許將數字 0 選擇性地對應對映為字母 O，並且允許將數字 1 選擇性地對映為字母 I 或字母 L。當可選的引數 `map01' 不為 @code{None} 時，指定數字 1 應該對映為哪個字母（當 `map01' 不為 @code{None} 時，數字 0 總是對映為字母 O）。出於安全性考量，預設值為 @code{None}，因此不允許在輸入中使用數字 0 和 1。

如果 `s' 的填充不正確或輸入中存在非字母表字元，將引發 @ref{1221,,binascii.Error}。
@end deffn

@geindex b32hexencode() (於 base64 模組中)
@anchor{library/base64 base64 b32hexencode}@anchor{9dd}
@deffn {函式} base64.b32hexencode (s)

類似於 @ref{3b68,,b32encode()}，但使用在 
@geindex RFC; RFC 4648
RFC 4648@footnote{https://datatracker.ietf.org/doc/html/rfc4648.html} 中定義的擴展十六進位字母表 (Extended Hex Alphabet)。


在 3.10 版被加入.

@end deffn

@geindex b32hexdecode() (於 base64 模組中)
@anchor{library/base64 base64 b32hexdecode}@anchor{9de}
@deffn {函式} base64.b32hexdecode (s, casefold=False)

類似於 @ref{3b68,,b32encode()}，但使用在 
@geindex RFC; RFC 4648
RFC 4648@footnote{https://datatracker.ietf.org/doc/html/rfc4648.html} 中定義的擴展十六進位字母表。

這個版本不允許將數字 0 對映為字母 O ，以及將數字 1 對映為字母 I 或字母 L，所有這些字元都包含在擴展十六進位字母表中，並且不能互換使用。


在 3.10 版被加入.

@end deffn

@geindex b16encode() (於 base64 模組中)
@anchor{library/base64 base64 b16encode}@anchor{3b69}
@deffn {函式} base64.b16encode (s)

使用 Base16 對@ref{193,,類位元組物件} `s' 進行編碼，並回傳編碼後的 @ref{192,,bytes}。
@end deffn

@geindex b16decode() (於 base64 模組中)
@anchor{library/base64 base64 b16decode}@anchor{2d3}
@deffn {函式} base64.b16decode (s, casefold=False)

解碼經過 Base16 編碼的@ref{193,,類位元組物件}或 ASCII 字串 `s'，並回傳解碼後的 @ref{192,,bytes}。

可選的 `casefold' 是一個是否接受小寫字母表作為輸入的旗標。出於安全性考量，預設值為 @code{False}。

如果 `s' 的填充不正確或輸入中存在非字母表字元，將引發 @ref{1221,,binascii.Error}。
@end deffn

@node Base85 編碼,舊版介面,RFC 4648 編碼,base64 --- Base16、Base32、Base64、Base85 資料編碼
@anchor{library/base64 base64-base-85}@anchor{3b60}@anchor{library/base64 base85-encodings}@anchor{3b6a}
@subsubsection Base85 編碼


Base85 encoding is not formally specified but rather a de facto standard,
thus different systems perform the encoding differently.

The @ref{111b,,a85encode()} and @ref{111d,,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{111b}
@deffn {函式} base64.a85encode (b, *, foldspaces=False, wrapcol=0, pad=False, adobe=False)

使用 Ascii85 對@ref{193,,類位元組物件} `b' 進行編碼，並回傳編碼後的 @ref{192,,bytes}。

`foldspaces' 是一個可選的旗標，它使用特殊的短序列 'y' 來替代連續的 4 個空格 (ASCII 0x20)，這是由 'btoa' 支援的功能。這個特性不被「標準」的 Ascii85 編碼所支援。

`wrapcol' 控制輸出是否應該包含換行字元 (@code{b'\n'}) 。如果這個值不為零，每行輸出的長度將不超過這個字元長度（不包含後面的換行符號）。

`pad' 控制是否在編碼之前將輸入填充為 4 的倍數。請注意，@code{btoa} 實作始終會填充。

`adobe' 控制編碼的位元組序列前後是否加上 @code{<~} 和 @code{~>}，這是 Adobe 實作中使用的。


在 3.4 版被加入.

@end deffn

@geindex a85decode() (於 base64 模組中)
@anchor{library/base64 base64 a85decode}@anchor{111c}
@deffn {函式} base64.a85decode (b, *, foldspaces=False, adobe=False, ignorechars=b' \t\n\r\x0b')

解碼經過 Ascii85 編碼的@ref{193,,類位元組物件}或 ASCII 字串 `b'，並回傳解碼後的 @ref{192,,bytes}。

`foldspaces' 是一個旗標，指定是否應該將短序列 'y' 視為 4 個連續的空格 (ASCII 0x20) 的簡寫。這個功能不受「標準」Ascii85 編碼的支援。

`adobe' 控制輸入序列是否符合 Adobe Ascii85 格式（即前後加上 @code{<~} 和 @code{~>}）。

`ignorechars' 是一個包含要從輸入中忽略的字元的@ref{193,,類位元組物件}或 ASCII 字串。這只包含空格字元，預設情況下包含 ASCII 中的所有空格字元。


在 3.4 版被加入.

@end deffn

@geindex b85encode() (於 base64 模組中)
@anchor{library/base64 base64 b85encode}@anchor{111d}
@deffn {函式} base64.b85encode (b, pad=False)

使用 Base85（例如，git 風格的二進位差異 (binary diff)）對@ref{193,,類位元組物件} `b' 進行編碼，並回傳編碼後的 @ref{192,,bytes}。

如果 `pad' 為 true，則在編碼之前，輸入將使用 @code{b'\0'} 進行填充，以使其長度為 4 的倍數。


在 3.4 版被加入.

@end deffn

@geindex b85decode() (於 base64 模組中)
@anchor{library/base64 base64 b85decode}@anchor{111e}
@deffn {函式} base64.b85decode (b)

解碼經過 base85 編碼的@ref{193,,類位元組物件}或 ASCII 字串 `b'，並回傳解碼後的 @ref{192,,bytes}。必要時會隱式移除填充。


在 3.4 版被加入.

@end deffn

@geindex z85encode() (於 base64 模組中)
@anchor{library/base64 base64 z85encode}@anchor{475}
@deffn {函式} base64.z85encode (s)

使用 Z85（如用於 ZeroMQ）對@ref{193,,類位元組物件} `s' 進行編碼，並回傳編碼後的 @ref{192,,bytes}。有關更多資訊，請參閱 Z85 規格@footnote{https://rfc.zeromq.org/spec/32/}。


在 3.13 版被加入.

@end deffn

@geindex z85decode() (於 base64 模組中)
@anchor{library/base64 base64 z85decode}@anchor{476}
@deffn {函式} base64.z85decode (s)

解碼經 Z85 編碼的@ref{193,,類位元組物件}或 ASCII 字串 `s'，並回傳解碼後的 @ref{192,,bytes}。有關更多資訊，請參閱 Z85 規格@footnote{https://rfc.zeromq.org/spec/32/}。


在 3.13 版被加入.

@end deffn

@node 舊版介面,安全性注意事項<2>,Base85 編碼,base64 --- Base16、Base32、Base64、Base85 資料編碼
@anchor{library/base64 base64-legacy}@anchor{3b61}@anchor{library/base64 legacy-interface}@anchor{3b6b}
@subsubsection 舊版介面


@geindex decode() (於 base64 模組中)
@anchor{library/base64 base64 decode}@anchor{3b6c}
@deffn {函式} base64.decode (input, output)

解碼二進位檔案 `input' 的內容，並將結果的二進位資料寫入 `output' 檔案。 `input' 和 `output' 必須是@ref{13c4,,檔案物件}。`input' 將被讀取，直到 @code{input.readline()} 回傳一個空的 bytes 物件為止。
@end deffn

@geindex decodebytes() (於 base64 模組中)
@anchor{library/base64 base64 decodebytes}@anchor{b44}
@deffn {函式} base64.decodebytes (s)

解碼必須包含一行或多行的 base64 編碼資料@ref{193,,類位元組物件} `s'，並回傳解碼後的 @ref{192,,bytes}。


在 3.1 版被加入.

@end deffn

@geindex encode() (於 base64 模組中)
@anchor{library/base64 base64 encode}@anchor{3b6d}
@deffn {函式} base64.encode (input, output)

編碼二進位檔案 `input' 的內容，並將結果的 base64 編碼資料寫入 `output' 檔案。`input' 和 `output' 必須是@ref{13c4,,檔案物件}。`input' 將被讀取，直到 @code{input.read()} 回傳一個空的 bytes 物件為止。@ref{3b6d,,encode()} 會在輸出的每 76 個位元組之後插入一個換行字元 (@code{b'\n'})，並確保輸出始終以換行字元結尾，符合 
@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{b43}
@deffn {函式} base64.encodebytes (s)

對包含任意二進位資料的@ref{193,,類位元組物件} `s' 進行編碼，並回傳包含 base64 編碼資料 @ref{192,,bytes}，在每 76 個輸出位元組後插入換行字元 (@code{b'\n'}) ，並確保有尾隨換行字元，符合 
@geindex RFC; RFC 2045
RFC 2045@footnote{https://datatracker.ietf.org/doc/html/rfc2045.html} (MIME) 的規定。


在 3.1 版被加入.

@end deffn

模組的一個範例用法：

@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 安全性注意事項<2>,,舊版介面,base64 --- Base16、Base32、Base64、Base85 資料編碼
@anchor{library/base64 base64-security}@anchor{3b6e}@anchor{library/base64 security-considerations}@anchor{3b6f}
@subsubsection 安全性注意事項


@geindex RFC; RFC 4648
RFC 4648@footnote{https://datatracker.ietf.org/doc/html/rfc4648.html}（第 12 節）中添加了一個新的安全性考量部分；建議對部署到正式環境的任何程式碼進行安全性部分的審查。


@subsubheading 也參考



@table @asis

@item @ref{11,,binascii} 模組

支援模組中包含 ASCII 到二進位 (ASCII-to-binary) 和二進位到 ASCII (binary-to-ASCII) 的轉換功能。

@geindex RFC; RFC 1521

@item RFC 1521@footnote{https://datatracker.ietf.org/doc/html/rfc1521.html} - MIME（多用途網際網路郵件擴展）第一部分：指定和描述網際網路主體格式的機制。

第 5.2 節，"Base64 Content-Transfer-Encoding"，提供了 base64 編碼的定義。
@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 --- 在二進位制和 ASCII 之間轉換,quopri --- 編碼和解碼 MIME 可列印字元資料,base64 --- Base16、Base32、Base64、Base85 資料編碼,網際網路資料處理
@anchor{library/binascii doc}@anchor{3b70}@anchor{library/binascii binascii-convert-between-binary-and-ascii}@anchor{3b71}@anchor{library/binascii module-binascii}@anchor{11}@anchor{library/binascii translation-repo}@anchor{3b72}
@subsection @code{binascii} --- 在二進位制和 ASCII 之間轉換


@geindex module; binascii

@geindex module（模組）;base64


__________________________________________________________________


The @ref{11,,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 @ref{11,,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{193,,bytes-like objects} (such as
@ref{192,,bytes}, @ref{343,,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

@ref{11,,binascii} 模組定義了以下函式：

@geindex a2b_uu() (於 binascii 模組中)
@anchor{library/binascii binascii a2b_uu}@anchor{3b73}
@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{d0e}
@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 版的變更: 新增 `backtick' 參數。

@end deffn

@geindex a2b_base64() (於 binascii 模組中)
@anchor{library/binascii binascii a2b_base64}@anchor{18fb}
@deffn {函式} binascii.a2b_base64 (string, /, *, strict_mode=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.

If `strict_mode' is true, only valid base64 data will be converted. Invalid base64
data will raise @ref{1221,,binascii.Error}.

Valid base64:


@itemize *

@item 
Conforms to 
@geindex RFC; RFC 3548
RFC 3548@footnote{https://datatracker.ietf.org/doc/html/rfc3548.html}.

@item 
Contains only characters from the base64 alphabet.

@item 
Contains no excess data after padding (including excess padding, newlines, etc.).

@item 
Does not start with a padding.
@end itemize


在 3.11 版的變更: 新增 `strict_mode' 參數。

@end deffn

@geindex b2a_base64() (於 binascii 模組中)
@anchor{library/binascii binascii b2a_base64}@anchor{e76}
@deffn {函式} binascii.b2a_base64 (data, *, newline=True)

Convert binary data to a line of ASCII characters in base64 coding. The return
value is the converted line, including a newline char if `newline' is
true.  The output of this function conforms to 
@geindex RFC; RFC 3548
RFC 3548@footnote{https://datatracker.ietf.org/doc/html/rfc3548.html}.


在 3.6 版的變更: 新增 `newline' 參數。

@end deffn

@geindex a2b_qp() (於 binascii 模組中)
@anchor{library/binascii binascii a2b_qp}@anchor{3b74}
@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{3b75}
@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{935}
@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{1960}
@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{272b}
@deffn {函式} binascii.b2a_hex (data[, sep[, bytes_per_sep=1]])
@anchor{library/binascii binascii hexlify}@anchor{3b76}
@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{f60,,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 版的變更: 新增 `sep' 與 `bytes_per_sep' 參數。

@end deffn

@geindex a2b_hex() (於 binascii 模組中)
@geindex unhexlify() (於 binascii 模組中)
@anchor{library/binascii binascii a2b_hex}@anchor{272c}
@deffn {函式} binascii.a2b_hex (hexstr)
@anchor{library/binascii binascii unhexlify}@anchor{1cef}
@deffnx {函式} binascii.unhexlify (hexstr)

Return the binary data represented by the hexadecimal string `hexstr'.  This
function is the inverse of @ref{272b,,b2a_hex()}. `hexstr' must contain an even number
of hexadecimal digits (which can be upper or lower case), otherwise an
@ref{1221,,Error} exception is raised.

Similar functionality (accepting only text string arguments, but more
liberal towards whitespace) is also accessible using the
@ref{190,,bytes.fromhex()} class method.
@end deffn

@geindex Error
@anchor{library/binascii binascii Error}@anchor{1221}
@deffn {例外} binascii.Error

Exception raised on errors. These are usually programming errors.
@end deffn

@geindex Incomplete
@anchor{library/binascii binascii Incomplete}@anchor{3b77}
@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


@subsubheading 也參考



@table @asis

@item @ref{f,,base64} 模組

Support for RFC compliant base64-style encoding in base 16, 32, 64,
and 85.

@item @ref{bc,,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 --- 編碼和解碼 MIME 可列印字元資料,,binascii --- 在二進位制和 ASCII 之間轉換,網際網路資料處理
@anchor{library/quopri doc}@anchor{3b78}@anchor{library/quopri module-quopri}@anchor{bc}@anchor{library/quopri quopri-encode-and-decode-mime-quoted-printable-data}@anchor{3b79}@anchor{library/quopri translation-repo}@anchor{3b7a}
@subsection @code{quopri} --- 編碼和解碼 MIME 可列印字元資料


@geindex module; quopri

`原始碼：'Lib/quopri.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/quopri.py}

@geindex quoted-printable（可列印字元）;encoding（編碼）
@geindex MIME;quoted-printable encoding（可列印字元編碼）


__________________________________________________________________


該模組根據 
@geindex RFC; RFC 1521
RFC 1521@footnote{https://datatracker.ietf.org/doc/html/rfc1521.html}：「MIME（多功能網際網路郵件擴充）第一部分：指定和描述網際網路訊息正文格式的機制」中的定義來執行可列印字元 (quoted-printable) 傳輸編碼和解碼。可列印字元編碼是為不可列印字元相對較少的資料而設計的；如果存在許多此類字元（例如發送圖形檔案時），則透過 @ref{f,,base64} 模組提供的 Base64 編碼方案會更加簡潔。

@geindex decode() (於 quopri 模組中)
@anchor{library/quopri quopri decode}@anchor{272e}
@deffn {函式} quopri.decode (input, output, header=False)

解碼 `input' 檔案的內容並將解碼後的二進位資料寫入 `output' 檔案。 `input' 和 `output' 必須是@ref{13c4,,二進位檔案物件}。如果可選參數 `header' 存在且為 true，則底線將被解碼為空格。這用於解碼如 
@geindex RFC; RFC 1522
RFC 1522@footnote{https://datatracker.ietf.org/doc/html/rfc1522.html}：「MIME（多功能網際網路郵件擴充）第二部分：非 ASCII 文字的訊息標頭擴充」中所述的 "Q" 編碼標頭。
@end deffn

@geindex encode() (於 quopri 模組中)
@anchor{library/quopri quopri encode}@anchor{272d}
@deffn {函式} quopri.encode (input, output, quotetabs, header=False)

對 `input' 檔案的內容進行編碼，並將生成的可列印字元資料寫入 `output' 檔案。 `input' 和 `output' 必須是@ref{13c4,,二進位檔案物件}。 `quotetabs'，一個非可選旗標，控制是否對嵌入的空格和製表符號 (tab) 進行編碼；當為 true 時，它將對此類嵌入的空白進行編碼，當為 false 時，它將不對它們進行編碼。請注意，出現在列尾的空格和製表符號都會按照 
@geindex RFC; RFC 1521
RFC 1521@footnote{https://datatracker.ietf.org/doc/html/rfc1521.html} 進行編碼。 `header' 是一個旗標，用於控制空格是否按照 
@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{3b7b}
@deffn {函式} quopri.decodestring (s, header=False)

與 @ref{272e,,decode()} 類似，不同之處在於它接受來源的 @ref{192,,bytes} 並回傳相應的已解碼 @ref{192,,bytes}。
@end deffn

@geindex encodestring() (於 quopri 模組中)
@anchor{library/quopri quopri encodestring}@anchor{3b7c}
@deffn {函式} quopri.encodestring (s, quotetabs=False, header=False)

與 @ref{272d,,encode()} 類似，不同之處在於它接受來源的 @ref{192,,bytes} 並回傳相應的已編碼 @ref{192,,bytes}。預設情況下，它向 @ref{272d,,encode()} 函式的 `quotetabs' 參數發送一個 @code{False} 值。
@end deffn


@subsubheading 也參考



@table @asis

@item @ref{f,,base64} 模組

對 MIME Base64 資料進行編碼和解碼
@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 結構化標記處理工具,網路協定 Internet protocols 及支援,網際網路資料處理,Python 標準函式庫 Standard Library
@anchor{library/markup doc}@anchor{3b7d}@anchor{library/markup markup}@anchor{3b7e}@anchor{library/markup structured-markup-processing-tools}@anchor{3b7f}@anchor{library/markup translation-repo}@anchor{3b80}
@section 結構化標記處理工具


Python 支援多種模組來處理各種形式的結構化資料標記。這包括用於處理標準通用標記語言 (SGML, Standard Generalized Markup Language) 和超文本標記語言 (HTML, Hypertext Markup Language) 的模組，以及用於處理可擴展標記語言 (XML, Extensible Markup Language) 的幾個介面。

@menu
* html: html --- 超文本標記語言 HTML 支援. 超文本標記語言 (HTML) 支援
* html.parser: html parser --- 簡單的 HTML 和 XHTML 剖析器. 簡單的 HTML 和 XHTML 剖析器
* html.entities: html entities --- HTML 一般實體的定義. HTML 一般實體的定義
* XML 處理模組:: 
* xml.etree.cElementTree: xml etree cElementTree --- ElementTree XML API. ElementTree XML API
* xml.dom: xml dom --- Document 物件模型 API. Document 物件模型 API
* xml.dom.minidom: xml dom minidom --- 最小的 DOM 實作. 最小的 DOM 實作
* xml.dom.pulldom: xml dom pulldom --- 支援建置部分 DOM 樹. 支援建置部分 DOM 樹
* xml.sax: xml sax --- SAX2 剖析器支援. SAX2 剖析器支援
* xml.sax.handler: xml sax handler --- SAX 處理函式的基本類別. SAX 處理函式的基本類別
* xml.sax.saxutils: xml sax saxutils --- SAX 工具程式. SAX 工具程式
* xml.sax.xmlreader: xml sax xmlreader --- XML 剖析器的介面. XML 剖析器的介面
* xml.parsers.expat: xml parsers expat --- 使用 Expat 進行快速 XML 剖析. 使用 Expat 進行快速 XML 剖析

@end menu

@node html --- 超文本標記語言 HTML 支援,html parser --- 簡單的 HTML 和 XHTML 剖析器,,結構化標記處理工具
@anchor{library/html doc}@anchor{3b81}@anchor{library/html html-hypertext-markup-language-support}@anchor{3b82}@anchor{library/html module-html}@anchor{6f}
@subsection @code{html} --- 超文本標記語言 (HTML) 支援


@geindex module; html

`原始碼：'Lib/html/__init__.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/html/__init__.py}


__________________________________________________________________


此模組定義了操作 HTML 的工具。

@geindex escape() (於 html 模組中)
@anchor{library/html html escape}@anchor{1209}
@deffn {函式} html.escape (s, quote=True)

將字串 `s' 中的 @code{&}、@code{<} 和 @code{>} 字元轉換為在 HTML 中安全的序列 (sequence)。如果你需要在 HTML 中顯示可能包含這些字元的文字，可以使用這個函式。如果選擇性的旗標 `quote' 為 true（預設），則 (@code{"}) 與 (@code{'}) 字元也會被轉換；這樣能包含在 HTML 中，被引號分隔的屬性值，如 @code{<a href="...">} 。如果 `quote' 設為 false，則 (@code{"}) 與 (@code{'}) 字元不會被轉換。


在 3.2 版被加入.

@end deffn

@geindex unescape() (於 html 模組中)
@anchor{library/html html unescape}@anchor{b47}
@deffn {函式} html.unescape (s)

將字串 `s' 中所有附名 (named) 且為數值的 (numeric) 字元參照（如： @code{&gt;}、 @code{&#62;}、@code{&#x3e;} ）轉換為對應的 Unicode 字元。此函式針對有效及無效的字元參照，皆使用 HTML 5 標準所定義的規則，以及 @ref{12d3,,HTML 5 附名字元參照清單} 。


在 3.4 版被加入.

@end deffn


__________________________________________________________________


@code{html} 套件中的子模組為：


@itemize *

@item 
@ref{71,,html.parser} -- 帶有寬鬆剖析模式的 HTML/XHTML 剖析器

@item 
@ref{70,,html.entities} -- HTML 實體的定義
@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 --- 簡單的 HTML 和 XHTML 剖析器,html entities --- HTML 一般實體的定義,html --- 超文本標記語言 HTML 支援,結構化標記處理工具
@anchor{library/html parser doc}@anchor{3b83}@anchor{library/html parser html-parser-simple-html-and-xhtml-parser}@anchor{3b84}@anchor{library/html parser module-html parser}@anchor{71}@anchor{library/html parser translation-repo}@anchor{3b85}
@subsection @code{html.parser} --- 簡單的 HTML 和 XHTML 剖析器


@geindex module; html.parser

`原始碼：'Lib/html/parser.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/html/parser.py}

@geindex HTML
@geindex XHTML


__________________________________________________________________


該模組定義了一個類別 @ref{a6e,,HTMLParser}，是剖析 (parse) HTML（HyperText Mark-up Language、超文本標記語言）和 XHTML 格式文本檔案的基礎。

@geindex HTMLParser (html.parser 中的類別)
@anchor{library/html parser html parser HTMLParser}@anchor{a6e}
@deffn {類別} html.parser.HTMLParser (*, convert_charrefs=True, scripting=False)

建立一個能夠剖析無效標記的剖析器實例。

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.

@ref{a6e,,HTMLParser} 實例被提供 HTML 資料，並在遇到開始標籤、結束標籤、文本、註解和其他標記元素時呼叫處理程式 (handler) 方法。使用者應該繼承 @ref{a6e,,HTMLParser} 並覆蓋其方法以實作所需的行為。

此剖析器不檢查結束標籤是否與開始標籤匹配，也不會為透過結束外部元素來隱晦地被結束的元素呼叫結束標籤處理程式。


在 3.4 版的變更: 新增關鍵字引數 `convert_charrefs'。



在 3.5 版的變更: 引數 `convert_charrefs' 的預設值現在是 @code{True}。



在 3.14.1 版的變更: Added the `scripting' parameter.

@end deffn

@menu
* HTML 剖析器應用程式範例:: 
* HTMLParser 方法:: 
* 範例: 範例<31>. 

@end menu

@node HTML 剖析器應用程式範例,HTMLParser 方法,,html parser --- 簡單的 HTML 和 XHTML 剖析器
@anchor{library/html parser example-html-parser-application}@anchor{3b86}
@subsubsection HTML 剖析器應用程式範例


以下的基礎範例是一個簡單的 HTML 剖析器，它使用 @ref{a6e,,HTMLParser} 類別，當遇到開始標籤、結束標籤和資料時將它們印出：

@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

輸出將是：

@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 方法,範例<31>,HTML 剖析器應用程式範例,html parser --- 簡單的 HTML 和 XHTML 剖析器
@anchor{library/html parser htmlparser-methods}@anchor{3b87}
@subsubsection @code{HTMLParser} 方法


@ref{a6e,,HTMLParser} 實例具有以下方法：

@geindex feed() (html.parser.HTMLParser 的方法)
@anchor{library/html parser html parser HTMLParser feed}@anchor{3b88}
@deffn {方法} HTMLParser.feed (data)

向剖析器提供一些文本。只要它由完整的元素組成，它就會被處理；不完整的資料會被緩衝，直到輸入更多資料或呼叫 @ref{17be,,close()}。 `data' 必須是 @ref{169,,str}。
@end deffn

@geindex close() (html.parser.HTMLParser 的方法)
@anchor{library/html parser html parser HTMLParser close}@anchor{17be}
@deffn {方法} HTMLParser.close ()

強制處理所有緩衝資料，如同它後面跟有文件結束標籤一樣。此方法可能有被衍生類別重新定義，以在輸入末尾定義額外的處理，但重新定義的版本仍應要呼叫 @ref{a6e,,HTMLParser} 基底類別方法 @ref{17be,,close()}。
@end deffn

@geindex reset() (html.parser.HTMLParser 的方法)
@anchor{library/html parser html parser HTMLParser reset}@anchor{3b89}
@deffn {方法} HTMLParser.reset ()

重置實例。丟棄所有未處理的資料。這在實例化時被會隱晦地呼叫。
@end deffn

@geindex getpos() (html.parser.HTMLParser 的方法)
@anchor{library/html parser html parser HTMLParser getpos}@anchor{3b8a}
@deffn {方法} HTMLParser.getpos ()

回傳目前列號 (line number) 和偏移量 (offset)。
@end deffn

@geindex get_starttag_text() (html.parser.HTMLParser 的方法)
@anchor{library/html parser html parser HTMLParser get_starttag_text}@anchor{3b8b}
@deffn {方法} HTMLParser.get_starttag_text ()

回傳最近開啟 (open) 的開始標籤的文本。這對於結構化處理通常不必要，但在處理「已部署」的 HTML 或以最少的更改重新生成輸入（可以保留屬性之間的空白等）時可能很有用。
@end deffn

當遇到資料或標記元素時將呼叫以下方法，並且它們應在子類別中被覆蓋。基底類別實作什麼都不做（除了 @ref{3b8c,,handle_startendtag()}）：

@geindex handle_starttag() (html.parser.HTMLParser 的方法)
@anchor{library/html parser html parser HTMLParser handle_starttag}@anchor{3b8d}
@deffn {方法} HTMLParser.handle_starttag (tag, attrs)

呼叫此方法來處理元素的開始標籤（例如 @code{<div id="main">}）。

`tag' 引數是轉換為小寫的標籤名稱。 `attrs' 引數是一個 @code{(name, value)} 對的列表，包含在標籤的 @code{<>} 括號內找到的屬性。 `name' 將被轉成小寫，`value' 中的引號會被刪除，字元和實體參照也會被替換。

例如，對於標籤 @code{<A HREF="https://www.cwi.nl/">}，這個方法會以 @code{handle_starttag('a', [('href', 'https://www.cwi.nl/')])} 的形式被呼叫。

在屬性值中來自 @ref{70,,html.entities} 的所有實體參照都會被替換。
@end deffn

@geindex handle_endtag() (html.parser.HTMLParser 的方法)
@anchor{library/html parser html parser HTMLParser handle_endtag}@anchor{3b8e}
@deffn {方法} HTMLParser.handle_endtag (tag)

呼叫此方法來處理元素的結束標籤（例如 @code{</div>}）。

`tag' 引數是轉換為小寫的標籤名稱。
@end deffn

@geindex handle_startendtag() (html.parser.HTMLParser 的方法)
@anchor{library/html parser html parser HTMLParser handle_startendtag}@anchor{3b8c}
@deffn {方法} HTMLParser.handle_startendtag (tag, attrs)

與 @ref{3b8d,,handle_starttag()} 類似，但在剖析器遇到 XHTML 樣式的空標籤 (@code{<img ... />}) 時呼叫。這個方法可能被需要這個特定詞彙資訊 (lexical information) 的子類別覆蓋；預設實作只是呼叫 @ref{3b8d,,handle_starttag()} 和 @ref{3b8e,,handle_endtag()}。
@end deffn

@geindex handle_data() (html.parser.HTMLParser 的方法)
@anchor{library/html parser html parser HTMLParser handle_data}@anchor{3b8f}
@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{3b90}
@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{3b91}
@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{3b92}
@deffn {方法} HTMLParser.handle_comment (data)

當遇到註解時呼叫此方法（例如 @code{<!--comment-->}）。

舉例來說，註解 @code{<!-- comment -->} 會使得此方法被以引數 @code{' comment '} 來呼叫。

Internet Explorer 條件式註解（conditional comments, condcoms）的內容也會被發送到這個方法，故以 @code{<!--[if IE 9]>IE9-specific content<![endif]-->} 為例，這個方法將會收到 @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{3b93}
@deffn {方法} HTMLParser.handle_decl (decl)

呼叫此方法來處理 HTML 文件類型聲明 (doctype declaration)（例如 @code{<!DOCTYPE html>}）。

`decl' 參數將是 @code{<!...>} 標記內聲明部分的全部內容（例如 @code{'DOCTYPE html'}）。
@end deffn

@geindex handle_pi() (html.parser.HTMLParser 的方法)
@anchor{library/html parser html parser HTMLParser handle_pi}@anchor{3b94}
@deffn {方法} HTMLParser.handle_pi (data)

遇到處理指示 (processing instruction) 時會呼叫的方法。 `data' 參數將包含整個處理指示。例如，對於處理指示 @code{<?proc color='red'>}，這個方法將以  @code{handle_pi("proc color='red'")} 形式被呼叫。它旨在被衍生類別覆蓋；基底類別實作中什麼都不做。

@cartouche
@quotation 備註 
@ref{a6e,,HTMLParser} 類別使用 SGML 語法規則來處理指示。使用有 @code{?} 跟隨在後面的 XHTML 處理指示將導致 @code{?} 被包含在 `data' 中。
@end quotation
@end cartouche
@end deffn

@geindex unknown_decl() (html.parser.HTMLParser 的方法)
@anchor{library/html parser html parser HTMLParser unknown_decl}@anchor{3b95}
@deffn {方法} HTMLParser.unknown_decl (data)

當剖析器讀取無法識別的聲明時會呼叫此方法。

`data' 參數將是 @code{<![...]>} 標記內聲明的全部內容。有時被衍生類別被覆蓋會是好用的。在基底類別實作中什麼都不做。
@end deffn

@node 範例<31>,,HTMLParser 方法,html parser --- 簡單的 HTML 和 XHTML 剖析器
@anchor{library/html parser examples}@anchor{3b96}@anchor{library/html parser htmlparser-examples}@anchor{3b97}
@subsubsection 範例


以下類別實作了一個剖析器，將用於解說更多範例：

@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

剖析文件類型：

@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

剖析一個具有一些屬性和標題的元素：

@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

剖析註解：

@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

剖析附名 (named) 且為數值的 (numeric) 字元參照，並將它們轉換為正確的字元（注意：這 3 個參照都等同於 @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{3b88,,feed()} works, but
@ref{3b8f,,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

也能夠剖析無效的 HTML（例如未加引號的屬性）：

@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 --- HTML 一般實體的定義,XML 處理模組,html parser --- 簡單的 HTML 和 XHTML 剖析器,結構化標記處理工具
@anchor{library/html entities doc}@anchor{3b98}@anchor{library/html entities html-entities-definitions-of-html-general-entities}@anchor{3b99}@anchor{library/html entities module-html entities}@anchor{70}@anchor{library/html entities translation-repo}@anchor{3b9a}
@subsection @code{html.entities} --- HTML 一般實體的定義


@geindex module; html.entities

`原始碼：'Lib/html/entities.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/html/entities.py}


__________________________________________________________________


該 module（模組）定義了四個字典：@ref{12d3,,html5}、@ref{3b9b,,name2codepoint}、@ref{3b9c,,codepoint2name} 以及 @ref{3b9d,,entitydefs}。

@geindex html5 (於 html.entities 模組中)
@anchor{library/html entities html entities html5}@anchor{12d3}
@deffn {資料} html.entities.html5

將 HTML5 命名字元引用 @footnote{
請見 @indicateurl{https://html.spec.whatwg.org/multipage/named-characters.html#named-character-references}
} 對映到同等 Unicode 字元的字典，例如 @code{html5['gt;'] == '>'}。請注意，後面的的分號包含在名稱中（例如 @code{'gt;'}），但有些名稱即使沒有分號也會被此標準接受：在這種情況下，名稱可帶有或不帶有 @code{';'}。請見 @ref{b47,,html.unescape()}。


在 3.3 版被加入.

@end deffn

@geindex entitydefs (於 html.entities 模組中)
@anchor{library/html entities html entities entitydefs}@anchor{3b9d}
@deffn {資料} html.entities.entitydefs

將 XHTML 1.0 實體定義對映到 ISO Latin-1 中的替換文字的字典。
@end deffn

@geindex name2codepoint (於 html.entities 模組中)
@anchor{library/html entities html entities name2codepoint}@anchor{3b9b}
@deffn {資料} html.entities.name2codepoint

將 HTML4 實體名稱對映到 Unicode 程式點的字典。
@end deffn

@geindex codepoint2name (於 html.entities 模組中)
@anchor{library/html entities html entities codepoint2name}@anchor{3b9c}
@deffn {資料} html.entities.codepoint2name

將 Unicode 程式點對映到 HTML4 實體名稱的字典。
@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 XML 處理模組,xml etree cElementTree --- ElementTree XML API,html entities --- HTML 一般實體的定義,結構化標記處理工具
@anchor{library/xml doc}@anchor{3b9e}@anchor{library/xml module-xml}@anchor{126}@anchor{library/xml translation-repo}@anchor{3b9f}@anchor{library/xml xml}@anchor{3ba0}@anchor{library/xml xml-processing-modules}@anchor{3ba1}
@subsection XML 處理模組


@geindex module; xml

`原始碼：'Lib/xml/@footnote{https://github.com/python/cpython/tree/3.14/Lib/xml/}


__________________________________________________________________


Python 處理 XML 的介面被歸類於 @code{xml} 套件中。

@cartouche
@quotation 備註 
如果你需要剖析不受信任或未經驗證的資料，請參閱 @ref{3ba2,,XML 安全性}。
@end quotation
@end cartouche

請務必注意 @ref{126,,xml} 套件中的模組要求至少有一個可用的 SAX 相容 XML 剖析器。Expat 剖析器包含在 Python 中，所以總是可以使用 @ref{12c,,xml.parsers.expat} 模組。

@ref{127,,xml.dom} 和 @ref{12f,,xml.sax} 套件的文件為 DOM 和 SAX 介面的 Python 繫結的定義。

以下是 XML 處理子模組：


@itemize *

@item 
@ref{12b,,xml.etree.ElementTree}：ElementTree API，一個簡單且輕量級的 XML 處理器
@end itemize



@itemize *

@item 
@ref{127,,xml.dom}：DOM API 定義

@item 
@ref{128,,xml.dom.minidom}：最小的 DOM 實作

@item 
@ref{129,,xml.dom.pulldom}：支援建置部分 DOM 樹
@end itemize



@itemize *

@item 
@ref{12f,,xml.sax}：SAX2 基底類別和便利函式

@item 
@ref{12c,,xml.parsers.expat}：Expat 剖析器繫結
@end itemize
@anchor{library/xml xml-security}@anchor{3ba2}
@menu
* XML 安全性:: 

@end menu

@node XML 安全性,,,XML 處理模組
@anchor{library/xml id1}@anchor{3ba3}@anchor{library/xml xml-vulnerabilities}@anchor{3ba4}
@subsubsection XML 安全性


攻擊者可以濫用 XML 功能來執行阻斷服務攻擊 (denial of service attack)、存取本地檔案、生成與其他機器的網路連接或繞過防火牆。

Expat 低於 2.6.0 的版本容易受到「十億笑聲」、「二次爆炸」與「大型 token」的影響。Python 也可能因為使用這些系統提供的舊版 Expat 而易受攻擊。請檢查 @code{pyexpat.EXPAT_VERSION}。

@ref{133,,xmlrpc} 容易受到「解壓縮炸彈」攻擊。


@table @asis

@item 十億笑聲 / 指數實體擴展

十億笑聲@footnote{https://en.wikipedia.org/wiki/Billion_laughs}攻擊（也稱為指數實體擴展 (exponential entity expansion)）使用多層巢狀實體。每個實體多次引用另一個實體，最終的實體定義包含一個小字串。指數擴展會產生數 GB 的文本，並消耗大量記憶體和 CPU 時間。

@item 二次爆炸實體擴展

二次爆炸攻擊類似於十億笑聲@footnote{https://en.wikipedia.org/wiki/Billion_laughs}攻擊；它也濫用實體擴展。它不是巢狀實體，而是一遍又一遍地重複一個具有幾千個字元的大型實體。該攻擊不如指數擴展那麼有效率，但它不會觸發那些用來防止深度巢狀實體的剖析器對策。

@item 解壓縮炸彈 (decompression bomb)

解壓縮炸彈（又名 ZIP bomb@footnote{https://en.wikipedia.org/wiki/Zip_bomb}）適用於所有可以剖析壓縮 XML 串流（例如 gzip 壓縮的 HTTP 串流或 LZMA 壓縮檔案）的 XML 函式庫。對於攻擊者來說，它可以將傳輸的資料量減少三個或更多數量級。

@item 大型 token

Expat 需要重新剖析未完成的 token；如果沒有 Expat 2.6.0 中引入的保護，這可能會導致二次 runtime 而導致剖析 XML 的應用程式出現阻斷服務。此問題記錄於 
@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 cElementTree --- ElementTree XML API,xml dom --- Document 物件模型 API,XML 處理模組,結構化標記處理工具
@anchor{library/xml etree elementtree doc}@anchor{3ba5}@anchor{library/xml etree elementtree module-xml etree ElementTree}@anchor{12b}@anchor{library/xml etree elementtree translation-repo}@anchor{3ba6}@anchor{library/xml etree elementtree xml-etree-elementtree-the-elementtree-xml-api}@anchor{3ba7}
@subsection @code{xml.etree.cElementTree} --- ElementTree XML API


@geindex module; xml.etree.ElementTree

`原始碼：'Lib/xml/etree/ElementTree.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/xml/etree/ElementTree.py}


__________________________________________________________________


The @ref{12b,,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 版之後被棄用: @code{xml.etree.cElementTree} 模組已被棄用。


@cartouche
@quotation 備註 
如果你需要剖析不受信任或未經驗證的資料，請參閱 @ref{3ba2,,XML 安全性}。
@end quotation
@end cartouche

@menu
* 教學: 教學<3>. 
* XPath 支援:: 
* Reference: Reference<5>. 
* XInclude support:: 
* Reference: Reference<6>. 

@end menu

@node 教學<3>,XPath 支援,,xml etree cElementTree --- ElementTree XML API
@anchor{library/xml etree elementtree tutorial}@anchor{3ba8}
@subsubsection 教學


This is a short tutorial for using @ref{12b,,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:: 
* 剖析 XML:: 
* Pull API for non-blocking parsing:: 
* Finding interesting elements:: 
* 改動 XML 檔案:: 
* 建立 XML 文件:: 
* Parsing XML with Namespaces:: 

@end menu

@node XML tree and elements,剖析 XML,,教學<3>
@anchor{library/xml etree elementtree xml-tree-and-elements}@anchor{3ba9}
@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{b3e,,ElementTree} represents the whole XML document as a tree, and
@ref{361,,Element} represents a single node in this tree.  Interactions with
the whole document (reading and writing to/from files) are usually done
on the @ref{b3e,,ElementTree} level.  Interactions with a single XML element
and its sub-elements are done on the @ref{361,,Element} level.

@node 剖析 XML,Pull API for non-blocking parsing,XML tree and elements,教學<3>
@anchor{library/xml etree elementtree elementtree-parsing-xml}@anchor{3baa}@anchor{library/xml etree elementtree parsing-xml}@anchor{3bab}
@subsubsection 剖析 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{3bac,,fromstring()} parses XML from a string directly into an @ref{361,,Element},
which is the root element of the parsed tree.  Other parsing functions may
create an @ref{b3e,,ElementTree}.  Check the documentation to be sure.

As an @ref{361,,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{c41,,TreeBuilder} instance to the @ref{c40,,XMLParser}
constructor.
@end quotation
@end cartouche

@node Pull API for non-blocking parsing,Finding interesting elements,剖析 XML,教學<3>
@anchor{library/xml etree elementtree elementtree-pull-parsing}@anchor{11ef}@anchor{library/xml etree elementtree pull-api-for-non-blocking-parsing}@anchor{3bad}
@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{c40,,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{361,,Element} objects.

The most powerful tool for doing this is @ref{11ee,,XMLPullParser}.  It does not
require a blocking read to obtain the XML data, and is instead fed with data
incrementally with @ref{3bae,,XMLPullParser.feed()} calls.  To get the parsed XML
elements, call @ref{3baf,,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{11ee,,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{574,,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{571,,XMLPullParser.flush()} can help reduce delay;
please make sure to study the related security notes.

@node Finding interesting elements,改動 XML 檔案,Pull API for non-blocking parsing,教學<3>
@anchor{library/xml etree elementtree finding-interesting-elements}@anchor{3bb0}
@subsubsection Finding interesting elements


@ref{361,,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{154f,,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{17f7,,Element.findall()} finds only elements with a tag which are direct
children of the current element.  @ref{17f5,,Element.find()} finds the `first' child
with a particular tag, and @ref{3bb1,,Element.text} accesses the element's text
content.  @ref{3bb2,,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{da1,,XPath}.

@node 改動 XML 檔案,建立 XML 文件,Finding interesting elements,教學<3>
@anchor{library/xml etree elementtree modifying-an-xml-file}@anchor{3bb3}
@subsubsection 改動 XML 檔案


@ref{b3e,,ElementTree} provides a simple way to build XML documents and write them to files.
The @ref{c83,,ElementTree.write()} method serves this purpose.

Once created, an @ref{361,,Element} object may be manipulated by directly changing
its fields (such as @ref{3bb1,,Element.text}), adding and modifying attributes
(@ref{3bb4,,Element.set()} method), as well as adding new children (for example
with @ref{3bb5,,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

XML 現在看起來像這樣：

@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{17f1,,Element.remove()}.  Let's say we want to
remove all countries with a rank higher than 50:

@example
>>> for country in root.findall('country'):
...     # 使用 root.findall() 來避免在遍歷時移除
...     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.

XML 現在看起來像這樣：

@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 建立 XML 文件,Parsing XML with Namespaces,改動 XML 檔案,教學<3>
@anchor{library/xml etree elementtree building-xml-documents}@anchor{3bb6}
@subsubsection 建立 XML 文件


The @ref{3bb7,,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,,建立 XML 文件,教學<3>
@anchor{library/xml etree elementtree parsing-xml-with-namespaces}@anchor{3bb8}
@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{17f5,,find()} or @ref{17f7,,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 支援,Reference<5>,教學<3>,xml etree cElementTree --- ElementTree XML API
@anchor{library/xml etree elementtree elementtree-xpath}@anchor{da1}@anchor{library/xml etree elementtree xpath-support}@anchor{3bb9}
@subsubsection XPath 支援


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
* 範例: 範例<32>. 
* 支援的 XPath 語法:: 

@end menu

@node 範例<32>,支援的 XPath 語法,,XPath 支援
@anchor{library/xml etree elementtree example}@anchor{3bba}
@subsubsection 範例


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{3baa,,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 支援的 XPath 語法,,範例<32>,XPath 支援
@anchor{library/xml etree elementtree supported-xpath-syntax}@anchor{3bbb}
@subsubsection 支援的 XPath 語法



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

語法

@tab

意義

@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 版的變更: 新增對星號萬用字元的支援。


@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

選擇所有具有給定屬性的元素。

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


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


在 3.7 版被加入.


@item

@code{[.!='text']}

@tab

Selects all elements whose complete text content,
including descendants, does not equal the given
@code{text}.


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


在 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 支援,xml etree cElementTree --- ElementTree XML API
@anchor{library/xml etree elementtree reference}@anchor{3bbc}
@subsubsection Reference


@menu
* 函式: 函式<9>. 

@end menu

@node 函式<9>,,,Reference<5>
@anchor{library/xml etree elementtree elementtree-functions}@anchor{3bbd}@anchor{library/xml etree elementtree functions}@anchor{3bbe}
@subsubsection 函式


@geindex canonicalize() (於 xml.etree.ElementTree 模組中)
@anchor{library/xml etree elementtree xml etree ElementTree canonicalize}@anchor{c3f}
@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.


在 3.8 版被加入.

@end deffn

@geindex Comment() (於 xml.etree.ElementTree 模組中)
@anchor{library/xml etree elementtree xml etree ElementTree Comment}@anchor{3bbf}
@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{c40,,XMLParser} skips over comments in the input
instead of creating comment objects for them. An @ref{b3e,,ElementTree} will
only contain comment nodes if they have been inserted into to
the tree using one of the @ref{361,,Element} methods.
@end deffn

@geindex dump() (於 xml.etree.ElementTree 模組中)
@anchor{library/xml etree elementtree xml etree ElementTree dump}@anchor{3bc0}
@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 @ref{3bc0,,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{3bac}
@deffn {函式} xml.etree.ElementTree.fromstring (text, parser=None)

Parses an XML section from a string constant.  Same as @ref{3bc1,,XML()}.  `text'
is a string containing XML data.  `parser' is an optional parser instance.
If not given, the standard @ref{c40,,XMLParser} parser is used.
Returns an @ref{361,,Element} instance.
@end deffn

@geindex fromstringlist() (於 xml.etree.ElementTree 模組中)
@anchor{library/xml etree elementtree xml etree ElementTree fromstringlist}@anchor{13d2}
@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{c40,,XMLParser}
parser is used.  Returns an @ref{361,,Element} instance.


在 3.2 版被加入.

@end deffn

@geindex indent() (於 xml.etree.ElementTree 模組中)
@anchor{library/xml etree elementtree xml etree ElementTree indent}@anchor{3bc2}
@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'.


在 3.9 版被加入.

@end deffn

@geindex iselement() (於 xml.etree.ElementTree 模組中)
@anchor{library/xml etree elementtree xml etree ElementTree iselement}@anchor{3bc3}
@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{574}
@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{13c4,,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{c40,,XMLParser} parser is used.  `parser' must be a subclass of
@ref{c40,,XMLParser} and can only use the default @ref{c41,,TreeBuilder} as a
target. Returns an @ref{4c3,,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 @ref{574,,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{11ee,,XMLPullParser}.

@cartouche
@quotation 備註 
@ref{574,,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 版之後被棄用: `parser' 引數。



在 3.8 版的變更: 新增 `context' 與 `check_hostname' 事件。



在 3.13 版的變更: 新增 @code{close()} 方法。

@end deffn

@geindex parse() (於 xml.etree.ElementTree 模組中)
@anchor{library/xml etree elementtree xml etree ElementTree parse}@anchor{3bc4}
@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{c40,,XMLParser} parser is used.  Returns an
@ref{b3e,,ElementTree} instance.
@end deffn

@geindex ProcessingInstruction() (於 xml.etree.ElementTree 模組中)
@anchor{library/xml etree elementtree xml etree ElementTree ProcessingInstruction}@anchor{3bc5}
@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{c40,,XMLParser} skips over processing instructions
in the input instead of creating PI objects for them. An
@ref{b3e,,ElementTree} will only contain processing instruction nodes if
they have been inserted into to the tree using one of the
@ref{361,,Element} methods.
@end deffn

@geindex register_namespace() (於 xml.etree.ElementTree 模組中)
@anchor{library/xml etree elementtree xml etree ElementTree register_namespace}@anchor{13d3}
@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.


在 3.2 版被加入.

@end deffn

@geindex SubElement() (於 xml.etree.ElementTree 模組中)
@anchor{library/xml etree elementtree xml etree ElementTree SubElement}@anchor{3bb7}
@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.
@end deffn

@geindex tostring() (於 xml.etree.ElementTree 模組中)
@anchor{library/xml etree elementtree xml etree ElementTree tostring}@anchor{11f0}
@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{361,,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{c83,,ElementTree.write()}. Returns an (optionally) encoded string
containing the XML data.


在 3.4 版的變更: 新增 `short_empty_elements' 參數。



在 3.8 版的變更: 新增 `xml_declaration' 與 `default_namespace' 參數。



在 3.8 版的變更: The @ref{11f0,,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{11f1}
@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{361,,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{c83,,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)}.


在 3.2 版被加入.



在 3.4 版的變更: 新增 `short_empty_elements' 參數。



在 3.8 版的變更: 新增 `xml_declaration' 與 `default_namespace' 參數。



在 3.8 版的變更: The @ref{11f1,,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{3bc1}
@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{c40,,XMLParser} parser is used.  Returns an @ref{361,,Element} instance.
@end deffn

@geindex XMLID() (於 xml.etree.ElementTree 模組中)
@anchor{library/xml etree elementtree xml etree ElementTree XMLID}@anchor{3bc6}
@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{c40,,XMLParser} parser is used.  Returns a tuple containing an
@ref{361,,Element} instance and a dictionary.
@end deffn

@node XInclude support,Reference<6>,Reference<5>,xml etree cElementTree --- ElementTree XML API
@anchor{library/xml etree elementtree elementtree-xinclude}@anchor{3bc7}@anchor{library/xml etree elementtree xinclude-support}@anchor{3bc8}
@subsubsection XInclude support


This module provides limited support for
XInclude directives@footnote{https://www.w3.org/TR/xinclude/}, via the @ref{12a,,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
* 範例: 範例<33>. 

@end menu

@node 範例<33>,,,XInclude support
@anchor{library/xml etree elementtree id3}@anchor{3bc9}
@subsubsection 範例


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 @ref{12b,,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 cElementTree --- ElementTree XML API
@anchor{library/xml etree elementtree id4}@anchor{3bca}
@subsubsection Reference


@menu
* 函式: 函式<10>. 
* Element 物件:: 
* ElementTree 物件:: 
* QName 物件:: 
* TreeBuilder 物件:: 
* XMLParser 物件:: 
* XMLPullParser 物件:: 
* 例外: 例外<20>. 

@end menu

@node 函式<10>,Element 物件,,Reference<6>
@anchor{library/xml etree elementtree elementinclude-functions}@anchor{3bcb}@anchor{library/xml etree elementtree id5}@anchor{3bcc}
@subsubsection 函式


@geindex module; xml.etree.ElementInclude

@geindex default_loader() (於 xml.etree.ElementInclude 模組中)
@anchor{library/xml etree elementtree module-xml etree ElementInclude}@anchor{12a}@anchor{library/xml etree elementtree xml etree ElementInclude default_loader}@anchor{3bcd}
@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{361,,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{3bce}
@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{361,,Element} or an
@ref{b3e,,ElementTree} instance to find such element.
`loader' is an optional resource loader.  If omitted, it defaults to @ref{3bcd,,default_loader()}.
If given, it should be a callable that implements the same interface as
@ref{3bcd,,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 版的變更: 新增 `base_url' 與 `max_depth' 參數。

@end deffn

@node Element 物件,ElementTree 物件,函式<10>,Reference<6>
@anchor{library/xml etree elementtree element-objects}@anchor{3bcf}@anchor{library/xml etree elementtree elementtree-element-objects}@anchor{3bd0}
@subsubsection Element 物件


@geindex Element (xml.etree.ElementTree 中的類別)
@anchor{library/xml etree elementtree xml etree ElementTree Element}@anchor{361}
@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.

@geindex tag (xml.etree.ElementTree.Element 的屬性)
@anchor{library/xml etree elementtree xml etree ElementTree Element tag}@anchor{154e}
@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{3bb1}
@deffn {屬性} text
@anchor{library/xml etree elementtree xml etree ElementTree Element tail}@anchor{3bd1}
@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{13d6,,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{3bd2}
@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{3bd3}
@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{3bb2}
@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{3bd4}
@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{3bd5}
@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{3bb4}
@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{3bb5}
@deffn {方法} append (subelement)

Adds the element `subelement' to the end of this element's internal list
of subelements.  Raises @ref{198,,TypeError} if `subelement' is not an
@ref{361,,Element}.
@end deffn

@geindex extend() (xml.etree.ElementTree.Element 的方法)
@anchor{library/xml etree elementtree xml etree ElementTree Element extend}@anchor{13d4}
@deffn {方法} extend (subelements)

Appends `subelements' from an iterable of elements.
Raises @ref{198,,TypeError} if a subelement is not an @ref{361,,Element}.


在 3.2 版被加入.

@end deffn

@geindex find() (xml.etree.ElementTree.Element 的方法)
@anchor{library/xml etree elementtree xml etree ElementTree Element find}@anchor{17f5}
@deffn {方法} find (match, namespaces=None)

Finds the first subelement matching `match'.  `match' may be a tag name
or a @ref{da1,,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{17f7}
@deffn {方法} findall (match, namespaces=None)

Finds all matching subelements, by tag name or
@ref{da1,,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{17f6}
@deffn {方法} findtext (match, default=None, namespaces=None)

Finds text for the first subelement matching `match'.  `match' may be
a tag name or a @ref{da1,,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{3bd6}
@deffn {方法} insert (index, subelement)

Inserts `subelement' at the given position in this element.  Raises
@ref{198,,TypeError} if `subelement' is not an @ref{361,,Element}.
@end deffn

@geindex iter() (xml.etree.ElementTree.Element 的方法)
@anchor{library/xml etree elementtree xml etree ElementTree Element iter}@anchor{154f}
@deffn {方法} iter (tag=None)

Creates a tree @ref{4c3,,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.


在 3.2 版被加入.

@end deffn

@geindex iterfind() (xml.etree.ElementTree.Element 的方法)
@anchor{library/xml etree elementtree xml etree ElementTree Element iterfind}@anchor{13d5}
@deffn {方法} iterfind (match, namespaces=None)

Finds all matching subelements, by tag name or
@ref{da1,,path}.  Returns an iterable yielding all
matching elements in document order. `namespaces' is an optional mapping
from namespace prefix to full name.


在 3.2 版被加入.

@end deffn

@geindex itertext() (xml.etree.ElementTree.Element 的方法)
@anchor{library/xml etree elementtree xml etree ElementTree Element itertext}@anchor{13d6}
@deffn {方法} itertext ()

Creates a text iterator.  The iterator loops over this element and all
subelements, in document order, and returns all inner text.


在 3.2 版被加入.

@end deffn

@geindex makeelement() (xml.etree.ElementTree.Element 的方法)
@anchor{library/xml etree elementtree xml etree ElementTree Element makeelement}@anchor{3bd7}
@deffn {方法} makeelement (tag, attrib)

Creates a new element object of the same type as this element.  Do not
call this method, use the @ref{3bb7,,SubElement()} factory function instead.
@end deffn

@geindex remove() (xml.etree.ElementTree.Element 的方法)
@anchor{library/xml etree elementtree xml etree ElementTree Element remove}@anchor{17f1}
@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

@ref{361,,Element} objects also support the following sequence type methods
for working with subelements: @ref{14cd,,__delitem__()},
@ref{582,,__getitem__()}, @ref{14cc,,__setitem__()},
@ref{2260,,__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{1a3,,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{c3f,,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 物件,QName 物件,Element 物件,Reference<6>
@anchor{library/xml etree elementtree elementtree-elementtree-objects}@anchor{3bd8}@anchor{library/xml etree elementtree elementtree-objects}@anchor{3bd9}
@subsubsection ElementTree 物件


@geindex ElementTree (xml.etree.ElementTree 中的類別)
@anchor{library/xml etree elementtree xml etree ElementTree ElementTree}@anchor{b3e}
@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{3bda}
@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{3bdb}
@deffn {方法} find (match, namespaces=None)

Same as @ref{17f5,,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{3bdc}
@deffn {方法} findall (match, namespaces=None)

Same as @ref{17f7,,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{3bdd}
@deffn {方法} findtext (match, default=None, namespaces=None)

Same as @ref{17f6,,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{3bde}
@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{3bdf}
@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{3be0}
@deffn {方法} iterfind (match, namespaces=None)

Same as @ref{13d5,,Element.iterfind()}, starting at the root of the tree.


在 3.2 版被加入.

@end deffn

@geindex parse() (xml.etree.ElementTree.ElementTree 的方法)
@anchor{library/xml etree elementtree xml etree ElementTree ElementTree parse}@anchor{3be1}
@deffn {方法} parse (source, parser=None)

Loads an external XML section into this element tree.  `source' is a file
name or @ref{13c4,,file object}.  `parser' is an optional parser instance.
If not given, the standard @ref{c40,,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{c83}
@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{13c4,,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{169,,str}) or binary (@ref{192,,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{13c4,,file object}; make sure you do not try to write a string to a
binary stream and vice versa.


在 3.4 版的變更: 新增 `short_empty_elements' 參數。



在 3.8 版的變更: The @ref{c83,,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 物件,TreeBuilder 物件,ElementTree 物件,Reference<6>
@anchor{library/xml etree elementtree elementtree-qname-objects}@anchor{3be2}@anchor{library/xml etree elementtree qname-objects}@anchor{3be3}
@subsubsection QName 物件


@geindex QName (xml.etree.ElementTree 中的類別)
@anchor{library/xml etree elementtree xml etree ElementTree QName}@anchor{3be4}
@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.
@ref{3be4,,QName} instances are opaque.
@end deffn

@node TreeBuilder 物件,XMLParser 物件,QName 物件,Reference<6>
@anchor{library/xml etree elementtree elementtree-treebuilder-objects}@anchor{3be5}@anchor{library/xml etree elementtree treebuilder-objects}@anchor{3be6}
@subsubsection TreeBuilder 物件


@geindex TreeBuilder (xml.etree.ElementTree 中的類別)
@anchor{library/xml etree elementtree xml etree ElementTree TreeBuilder}@anchor{c41}
@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{3bbf,,Comment()} and @ref{3bc5,,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{3be7}
@deffn {方法} close ()

Flushes the builder buffers, and returns the toplevel document
element.  Returns an @ref{361,,Element} instance.
@end deffn

@geindex data() (xml.etree.ElementTree.TreeBuilder 的方法)
@anchor{library/xml etree elementtree xml etree ElementTree TreeBuilder data}@anchor{3be8}
@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{13d7}
@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{1c35}
@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{3be9}
@deffn {方法} comment (text)

Creates a comment with the given `text'.  If @code{insert_comments} is true,
this will also add it to the tree.


在 3.8 版被加入.

@end deffn

@geindex pi() (xml.etree.ElementTree.TreeBuilder 的方法)
@anchor{library/xml etree elementtree xml etree ElementTree TreeBuilder pi}@anchor{3bea}
@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.


在 3.8 版被加入.

@end deffn

In addition, a custom @ref{c41,,TreeBuilder} object can provide the
following methods:

@geindex doctype() (xml.etree.ElementTree.TreeBuilder 的方法)
@anchor{library/xml etree elementtree xml etree ElementTree TreeBuilder doctype}@anchor{c85}
@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 @ref{c41,,TreeBuilder} class.


在 3.2 版被加入.

@end deffn

@geindex start_ns() (xml.etree.ElementTree.TreeBuilder 的方法)
@anchor{library/xml etree elementtree xml etree ElementTree TreeBuilder start_ns}@anchor{3beb}
@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.


在 3.8 版被加入.

@end deffn

@geindex end_ns() (xml.etree.ElementTree.TreeBuilder 的方法)
@anchor{library/xml etree elementtree xml etree ElementTree TreeBuilder end_ns}@anchor{3bec}
@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.


在 3.8 版被加入.

@end deffn
@end deffn

@geindex C14NWriterTarget (xml.etree.ElementTree 中的類別)
@anchor{library/xml etree elementtree xml etree ElementTree C14NWriterTarget}@anchor{3bed}
@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{c3f,,canonicalize()} function.  This class does not build a
tree but translates the callback events directly into a serialised form
using the `write' function.


在 3.8 版被加入.

@end deffn

@node XMLParser 物件,XMLPullParser 物件,TreeBuilder 物件,Reference<6>
@anchor{library/xml etree elementtree elementtree-xmlparser-objects}@anchor{3bee}@anchor{library/xml etree elementtree xmlparser-objects}@anchor{3bef}
@subsubsection XMLParser 物件


@geindex XMLParser (xml.etree.ElementTree 中的類別)
@anchor{library/xml etree elementtree xml etree ElementTree XMLParser}@anchor{c40}
@deffn {類別} xml.etree.ElementTree.XMLParser (*, target=None, encoding=None)

This class is the low-level building block of the module.  It uses
@ref{12c,,xml.parsers.expat} for efficient, event-based parsing of XML.  It can
be fed XML data incrementally with the @ref{3bf0,,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{c41,,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{59f,,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{3bf1}
@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{3bf0}
@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{570}
@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 @ref{570,,flush()} temporarily disables reparse deferral
with Expat (if currently enabled) and triggers a reparse.
Disabling reparse deferral has security consequences; please see
@ref{573,,xml.parsers.expat.xmlparser.SetReparseDeferralEnabled()} for details.

Note that @ref{570,,flush()} has been backported to some prior releases of
CPython as a security fix.  Check for availability of @ref{570,,flush()}
using @ref{6f2,,hasattr()} if used in code running across a variety of Python
versions.


在 3.13 版被加入.

@end deffn

@ref{3bf0,,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{c41,,TreeBuilder} class.  @ref{3bf1,,XMLParser.close()} calls
`target''s method @code{close()}. @ref{c40,,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 物件,例外<20>,XMLParser 物件,Reference<6>
@anchor{library/xml etree elementtree elementtree-xmlpullparser-objects}@anchor{3bf2}@anchor{library/xml etree elementtree xmlpullparser-objects}@anchor{3bf3}
@subsubsection XMLPullParser 物件


@geindex XMLPullParser (xml.etree.ElementTree 中的類別)
@anchor{library/xml etree elementtree xml etree ElementTree XMLPullParser}@anchor{11ee}
@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{c40,,XMLParser}, but instead of pushing calls to a
callback target, @ref{11ee,,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{3bae}
@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{571}
@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 @ref{571,,flush()} temporarily disables reparse deferral
with Expat (if currently enabled) and triggers a reparse.
Disabling reparse deferral has security consequences; please see
@ref{573,,xml.parsers.expat.xmlparser.SetReparseDeferralEnabled()} for details.

Note that @ref{571,,flush()} has been backported to some prior releases of
CPython as a security fix.  Check for availability of @ref{571,,flush()}
using @ref{6f2,,hasattr()} if used in code running across a variety of Python
versions.


在 3.13 版被加入.

@end deffn

@geindex close() (xml.etree.ElementTree.XMLPullParser 的方法)
@anchor{library/xml etree elementtree xml etree ElementTree XMLPullParser close}@anchor{3bf4}
@deffn {方法} close ()

Signal the parser that the data stream is terminated. Unlike
@ref{3bf1,,XMLParser.close()}, this method always returns @ref{87e,,None}.
Any events not yet retrieved when the parser is closed can still be
read with @ref{3baf,,read_events()}.
@end deffn

@geindex read_events() (xml.etree.ElementTree.XMLPullParser 的方法)
@anchor{library/xml etree elementtree xml etree ElementTree XMLPullParser read_events}@anchor{3baf}
@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{361,,Element} object, or other context value as follows.


@itemize *

@item 
@code{start}、@code{end}：目前的 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{87e,,None} (this may change in a future version)
@end itemize

Events provided in a previous call to @ref{3baf,,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 @ref{3baf,,read_events()} will have
unpredictable results.
@end deffn

@cartouche
@quotation 備註 
@ref{11ee,,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


在 3.4 版被加入.



在 3.8 版的變更: 新增 `context' 與 `check_hostname' 事件。

@end deffn

@node 例外<20>,,XMLPullParser 物件,Reference<6>
@anchor{library/xml etree elementtree exceptions}@anchor{3bf5}
@subsubsection 例外


@geindex ParseError (xml.etree.ElementTree 中的類別)
@anchor{library/xml etree elementtree xml etree ElementTree ParseError}@anchor{1478}
@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{3bf6}
@deffn {屬性} code

A numeric error code from the expat parser. See the documentation of
@ref{12c,,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{3bf7}
@deffn {屬性} position

A tuple of `line', `column' numbers, specifying where the error occurred.
@end deffn
@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 xml dom --- Document 物件模型 API,xml dom minidom --- 最小的 DOM 實作,xml etree cElementTree --- ElementTree XML API,結構化標記處理工具
@anchor{library/xml dom doc}@anchor{3bf8}@anchor{library/xml dom module-xml dom}@anchor{127}@anchor{library/xml dom translation-repo}@anchor{3bf9}@anchor{library/xml dom xml-dom-the-document-object-model-api}@anchor{3bfa}
@subsection @code{xml.dom} --- Document 物件模型 API


@geindex module; xml.dom

`原始碼：'Lib/xml/dom/__init__.py@footnote{https://github.com/python/cpython/tree/3.14/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{3bfb,,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{3bfc,,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{128,,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
* 模組內容: 模組內容<6>. 
* Objects in the DOM:: 
* Conformance:: 

@end menu

@node 模組內容<6>,Objects in the DOM,,xml dom --- Document 物件模型 API
@anchor{library/xml dom module-contents}@anchor{3bfd}
@subsubsection 模組內容


The @ref{127,,xml.dom} contains the following functions:

@geindex registerDOMImplementation() (於 xml.dom 模組中)
@anchor{library/xml dom xml dom registerDOMImplementation}@anchor{3bfe}
@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{3bfb}
@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{653,,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{3bff}
@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{3c00}
@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{3c01}
@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{3c02}
@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, @ref{127,,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,模組內容<6>,xml dom --- Document 物件模型 API
@anchor{library/xml dom dom-objects}@anchor{3c03}@anchor{library/xml dom objects-in-the-dom}@anchor{3c04}
@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{3c05,,DOMImplementation 物件}

@tab

Interface to the underlying
implementation.

@item

@code{Node}

@tab

@ref{3c06,,Node Objects}

@tab

Base interface for most objects
in a document.

@item

@code{NodeList}

@tab

@ref{225c,,NodeList 物件}

@tab

Interface for a sequence of
nodes.

@item

@code{DocumentType}

@tab

@ref{3c07,,DocumentType 物件}

@tab

Information about the
declarations needed to process
a document.

@item

@code{Document}

@tab

@ref{3c08,,Document Objects}

@tab

Object which represents an
entire document.

@item

@code{Element}

@tab

@ref{3c09,,Element Objects}

@tab

Element nodes in the document
hierarchy.

@item

@code{Attr}

@tab

@ref{3c0a,,Attr Objects}

@tab

Attribute value nodes on
element nodes.

@item

@code{Comment}

@tab

@ref{3c0b,,Comment Objects}

@tab

Representation of comments in
the source document.

@item

@code{Text}

@tab

@ref{3c0c,,Text and CDATASection Objects}

@tab

Nodes containing textual
content from the document.

@item

@code{ProcessingInstruction}

@tab

@ref{3c0d,,ProcessingInstruction 物件}

@tab

Processing instruction
representation.

@end multitable


An additional section describes the exceptions defined for working with the DOM
in Python.

@menu
* DOMImplementation 物件:: 
* Node Objects:: 
* NodeList 物件:: 
* DocumentType 物件:: 
* Document Objects:: 
* Element Objects:: 
* Attr Objects:: 
* NamedNodeMap 物件:: 
* Comment Objects:: 
* Text and CDATASection Objects:: 
* ProcessingInstruction 物件:: 
* 例外: 例外<21>. 

@end menu

@node DOMImplementation 物件,Node Objects,,Objects in the DOM
@anchor{library/xml dom dom-implementation-objects}@anchor{3c05}@anchor{library/xml dom domimplementation-objects}@anchor{3c0e}
@subsubsection DOMImplementation 物件


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{3c0f}
@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{3c10}
@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{3c11,,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{3c11}
@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 物件,DOMImplementation 物件,Objects in the DOM
@anchor{library/xml dom dom-node-objects}@anchor{3c06}@anchor{library/xml dom node-objects}@anchor{3c12}
@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{3c13}
@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{3c14}
@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{3c15}
@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{3c16}
@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{3c17}
@deffn {屬性} Node.nextSibling

The node that immediately follows this one with the same parent.  See also
@ref{3c16,,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{3c18}
@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{3c19}
@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{3c1a}
@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{3c1b}
@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{3c1c}
@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{3c1d}
@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{3c1e}
@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{3c1f}
@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{3c1e,,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{3c20}
@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{3c21}
@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{3c22}
@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{3c23}
@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{3c24}
@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{2eb,,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{3c25}
@deffn {方法} Node.removeChild (oldChild)

Remove a child node.  `oldChild' must be a child of this node; if not,
@ref{2eb,,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{3c26}
@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{2eb,,ValueError} is raised.
@end deffn

@geindex normalize() (xml.dom.Node 的方法)
@anchor{library/xml dom xml dom Node normalize}@anchor{3c27}
@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{3c28}
@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 物件,DocumentType 物件,Node Objects,Objects in the DOM
@anchor{library/xml dom dom-nodelist-objects}@anchor{225c}@anchor{library/xml dom nodelist-objects}@anchor{3c29}
@subsubsection NodeList 物件


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{3c2a}
@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{3c2b}
@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{2260,,__len__()} and
@ref{582,,__getitem__()}; this allows iteration over the @code{NodeList} in
@ref{348,,for} statements and proper support for the @ref{839,,len()} built-in
function.

If a DOM implementation supports modification of the document, the
@code{NodeList} implementation must also support the
@ref{14cc,,__setitem__()} and @ref{14cd,,__delitem__()} methods.

@node DocumentType 物件,Document Objects,NodeList 物件,Objects in the DOM
@anchor{library/xml dom documenttype-objects}@anchor{3c2c}@anchor{library/xml dom dom-documenttype-objects}@anchor{3c07}
@subsubsection DocumentType 物件


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{3c2d}
@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{3c2e}
@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{3c2f}
@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{3c30}
@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{3c31}
@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{3c32}
@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,DocumentType 物件,Objects in the DOM
@anchor{library/xml dom document-objects}@anchor{3c33}@anchor{library/xml dom dom-document-objects}@anchor{3c08}
@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{3c34}
@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{3c35}
@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{3c36}
@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{3c37}
@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{3c38}
@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{3c39}
@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{3c3a}
@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{3c3b}
@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{3c3c}
@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{3c3d}
@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,Attr Objects,Document Objects,Objects in the DOM
@anchor{library/xml dom dom-element-objects}@anchor{3c09}@anchor{library/xml dom element-objects}@anchor{3c3e}
@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{3c3f}
@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{3c40}
@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{3c41}
@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{3c42}
@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{3c43}
@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{3c44}
@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{3c45}
@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{3c46}
@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{3c47}
@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{3c48}
@deffn {方法} Element.removeAttribute (name)

Remove an attribute by name.  If there is no matching attribute, a
@ref{3c49,,NotFoundErr} is raised.
@end deffn

@geindex removeAttributeNode() (xml.dom.Element 的方法)
@anchor{library/xml dom xml dom Element removeAttributeNode}@anchor{3c4a}
@deffn {方法} Element.removeAttributeNode (oldAttr)

Remove and return `oldAttr' from the attribute list, if present. If `oldAttr' is
not present, @ref{3c49,,NotFoundErr} is raised.
@end deffn

@geindex removeAttributeNS() (xml.dom.Element 的方法)
@anchor{library/xml dom xml dom Element removeAttributeNS}@anchor{3c4b}
@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{3c4c}
@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{3c4d}
@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{3c4e,,InuseAttributeErr} will be raised.
@end deffn

@geindex setAttributeNodeNS() (xml.dom.Element 的方法)
@anchor{library/xml dom xml dom Element setAttributeNodeNS}@anchor{3c4f}
@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{3c4e,,InuseAttributeErr} will be raised.
@end deffn

@geindex setAttributeNS() (xml.dom.Element 的方法)
@anchor{library/xml dom xml dom Element setAttributeNS}@anchor{3c50}
@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 物件,Element Objects,Objects in the DOM
@anchor{library/xml dom attr-objects}@anchor{3c51}@anchor{library/xml dom dom-attr-objects}@anchor{3c0a}
@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{3c52}
@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{3c53}
@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{3c54}
@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{3c55}
@deffn {屬性} Attr.value

The text value of the attribute.  This is a synonym for the
@code{nodeValue} attribute.
@end deffn

@node NamedNodeMap 物件,Comment Objects,Attr Objects,Objects in the DOM
@anchor{library/xml dom dom-attributelist-objects}@anchor{3c56}@anchor{library/xml dom namednodemap-objects}@anchor{3c57}
@subsubsection NamedNodeMap 物件


@code{NamedNodeMap} does `not' inherit from @code{Node}.

@geindex length (xml.dom.NamedNodeMap 的屬性)
@anchor{library/xml dom xml dom NamedNodeMap length}@anchor{3c58}
@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{3c59}
@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 in the DOM
@anchor{library/xml dom comment-objects}@anchor{3c5a}@anchor{library/xml dom dom-comment-objects}@anchor{3c0b}
@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{3c5b}
@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 物件,Comment Objects,Objects in the DOM
@anchor{library/xml dom dom-text-objects}@anchor{3c0c}@anchor{library/xml dom text-and-cdatasection-objects}@anchor{3c5c}
@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{3c5d}
@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 物件,例外<21>,Text and CDATASection Objects,Objects in the DOM
@anchor{library/xml dom dom-pi-objects}@anchor{3c0d}@anchor{library/xml dom processinginstruction-objects}@anchor{3c5e}
@subsubsection ProcessingInstruction 物件


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{3c5f}
@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{3c60}
@deffn {屬性} ProcessingInstruction.data

The content of the processing instruction following the first whitespace
character.
@end deffn

@node 例外<21>,,ProcessingInstruction 物件,Objects in the DOM
@anchor{library/xml dom dom-exceptions}@anchor{3c61}@anchor{library/xml dom exceptions}@anchor{3c62}
@subsubsection 例外


The DOM Level 2 recommendation defines a single exception, @ref{3c63,,DOMException},
and a number of constants that allow applications to determine what sort of
error occurred. @ref{3c63,,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{3c63}
@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{3c64}
@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{3c65}
@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{3c66}
@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{3c4e}
@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{3c67}
@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{3c68}
@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{3c69}
@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{3c6a}
@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{3c6b}
@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{3c49}
@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{3c6c}
@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{3c6d}
@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{3c6e}
@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{3c6f}
@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{3c70}
@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

常數

@tab

例外

@item

@code{DOMSTRING_SIZE_ERR}

@tab

@ref{3c64,,DomstringSizeErr}

@item

@code{HIERARCHY_REQUEST_ERR}

@tab

@ref{3c65,,HierarchyRequestErr}

@item

@code{INDEX_SIZE_ERR}

@tab

@ref{3c66,,IndexSizeErr}

@item

@code{INUSE_ATTRIBUTE_ERR}

@tab

@ref{3c4e,,InuseAttributeErr}

@item

@code{INVALID_ACCESS_ERR}

@tab

@ref{3c67,,InvalidAccessErr}

@item

@code{INVALID_CHARACTER_ERR}

@tab

@ref{3c68,,InvalidCharacterErr}

@item

@code{INVALID_MODIFICATION_ERR}

@tab

@ref{3c69,,InvalidModificationErr}

@item

@code{INVALID_STATE_ERR}

@tab

@ref{3c6a,,InvalidStateErr}

@item

@code{NAMESPACE_ERR}

@tab

@ref{3c6b,,NamespaceErr}

@item

@code{NOT_FOUND_ERR}

@tab

@ref{3c49,,NotFoundErr}

@item

@code{NOT_SUPPORTED_ERR}

@tab

@ref{3c6c,,NotSupportedErr}

@item

@code{NO_DATA_ALLOWED_ERR}

@tab

@ref{3c6d,,NoDataAllowedErr}

@item

@code{NO_MODIFICATION_ALLOWED_ERR}

@tab

@ref{3c6e,,NoModificationAllowedErr}

@item

@code{SYNTAX_ERR}

@tab

@ref{3c6f,,SyntaxErr}

@item

@code{WRONG_DOCUMENT_ERR}

@tab

@ref{3c70,,WrongDocumentErr}

@end multitable


@node Conformance,,Objects in the DOM,xml dom --- Document 物件模型 API
@anchor{library/xml dom conformance}@anchor{3c71}@anchor{library/xml dom dom-conformance}@anchor{3bfc}
@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{3c72}@anchor{library/xml dom type-mapping}@anchor{3c73}
@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} 或 @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} 或 @code{bytes}

@item

@code{null}

@tab

@code{None}

@end multitable


@node Accessor Methods,,Type Mapping,Conformance
@anchor{library/xml dom accessor-methods}@anchor{3c74}@anchor{library/xml dom dom-accessor-methods}@anchor{3c75}
@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{5e8,,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 --- 最小的 DOM 實作,xml dom pulldom --- 支援建置部分 DOM 樹,xml dom --- Document 物件模型 API,結構化標記處理工具
@anchor{library/xml dom minidom doc}@anchor{3c76}@anchor{library/xml dom minidom module-xml dom minidom}@anchor{128}@anchor{library/xml dom minidom translation-repo}@anchor{3c77}@anchor{library/xml dom minidom xml-dom-minidom-minimal-dom-implementation}@anchor{3c78}
@subsection @code{xml.dom.minidom} --- 最小的 DOM 實作


@geindex module; xml.dom.minidom

`原始碼：'Lib/xml/dom/minidom.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/xml/dom/minidom.py}


__________________________________________________________________


@ref{128,,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{12b,,xml.etree.ElementTree} module for their XML processing instead.

@cartouche
@quotation 備註 
如果你需要剖析不受信任或未經驗證的資料，請參閱 @ref{3ba2,,XML 安全性}。
@end quotation
@end cartouche

DOM applications typically start by parsing some XML into a DOM.  With
@ref{128,,xml.dom.minidom}, this is done through the parse functions:

@example
from xml.dom.minidom import parse, parseString

dom1 = parse('c:\\temp\\mydata.xml')  # 以檔名來剖析 XML 檔案

datasource = open('c:\\temp\\mydata.xml')
dom2 = parse(datasource)  # 剖析開啟的檔案

dom3 = parseString('<myxml>Some data<empty/> some more data</myxml>')
@end example

@ref{3c79,,parse()} 函式可以接受一個檔案名稱或開啟的檔案物件。

@geindex parse() (於 xml.dom.minidom 模組中)
@anchor{library/xml dom minidom xml dom minidom parse}@anchor{3c79}
@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

如果你有一個字串中的 XML，你可以使用 @ref{3c7a,,parseString()} 函式來代替：

@geindex parseString() (於 xml.dom.minidom 模組中)
@anchor{library/xml dom minidom xml dom minidom parseString}@anchor{3c7a}
@deffn {函式} xml.dom.minidom.parseString (string, parser=None)

Return a @code{Document} that represents the `string'. This method creates an
@ref{1124,,io.StringIO} object for the string and passes that on to @ref{3c79,,parse()}.
@end deffn

這兩個函式都會回傳一個 @code{Document} 物件，表示文件的內容。

What the @ref{3c79,,parse()} and @ref{3c7a,,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 name 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{127,,xml.dom} package or the
@ref{128,,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 @ref{128,,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/}

W3C 對 @ref{128,,xml.dom.minidom} DOM 支援 的建議。
@end table


@menu
* DOM 物件:: 
* DOM 範例:: 
* minidom 和 DOM 標準:: 

@end menu

@node DOM 物件,DOM 範例,,xml dom minidom --- 最小的 DOM 實作
@anchor{library/xml dom minidom dom-objects}@anchor{3c7b}@anchor{library/xml dom minidom minidom-objects}@anchor{3c7c}
@subsubsection DOM 物件


The definition of the DOM API for Python is given as part of the @ref{127,,xml.dom}
module documentation.  This section lists the differences between the API and
@ref{128,,xml.dom.minidom}.

@geindex unlink() (xml.dom.minidom.Node 的方法)
@anchor{library/xml dom minidom xml dom minidom Node unlink}@anchor{3c7d}
@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{186,,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:
    ... # 使用 dom。
@end example
@end deffn

@geindex writexml() (xml.dom.minidom.Node 的方法)
@anchor{library/xml dom minidom xml dom minidom Node writexml}@anchor{c80}
@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 @ref{c80,,writexml()} method now preserves the attribute order specified
by the user.



在 3.9 版的變更: 新增 `standalone' 參數。

@end deffn

@geindex toxml() (xml.dom.minidom.Node 的方法)
@anchor{library/xml dom minidom xml dom minidom Node toxml}@anchor{c81}
@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{c80,,writexml()}.


在 3.8 版的變更: 現在 @ref{c81,,toxml()} 方法會保留使用者指定的屬性順序。



在 3.9 版的變更: 新增 `standalone' 參數。

@end deffn

@geindex toprettyxml() (xml.dom.minidom.Node 的方法)
@anchor{library/xml dom minidom xml dom minidom Node toprettyxml}@anchor{c82}
@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{c81,,toxml()}.

The `standalone' argument behaves exactly as in @ref{c80,,writexml()}.


在 3.8 版的變更: The @ref{c82,,toprettyxml()} method now preserves the attribute order specified
by the user.



在 3.9 版的變更: 新增 `standalone' 參數。

@end deffn

@node DOM 範例,minidom 和 DOM 標準,DOM 物件,xml dom minidom --- 最小的 DOM 實作
@anchor{library/xml dom minidom dom-example}@anchor{3c7e}@anchor{library/xml dom minidom id2}@anchor{3c7f}
@subsubsection DOM 範例


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 和 DOM 標準,,DOM 範例,xml dom minidom --- 最小的 DOM 實作
@anchor{library/xml dom minidom minidom-and-dom}@anchor{3c80}@anchor{library/xml dom minidom minidom-and-the-dom-standard}@anchor{3c81}
@subsubsection minidom 和 DOM 標準


The @ref{128,,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{349,,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. @ref{128,,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 @ref{128,,xml.dom.minidom}.
Instead, @ref{128,,xml.dom.minidom} uses standard Python exceptions such as
@ref{198,,TypeError} and @ref{5e8,,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 @ref{128,,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 --- 支援建置部分 DOM 樹,xml sax --- SAX2 剖析器支援,xml dom minidom --- 最小的 DOM 實作,結構化標記處理工具
@anchor{library/xml dom pulldom doc}@anchor{3c82}@anchor{library/xml dom pulldom module-xml dom pulldom}@anchor{129}@anchor{library/xml dom pulldom translation-repo}@anchor{3c83}@anchor{library/xml dom pulldom xml-dom-pulldom-support-for-building-partial-dom-trees}@anchor{3c84}
@subsection @code{xml.dom.pulldom} --- 支援建置部分 DOM 樹


@geindex module; xml.dom.pulldom

`原始碼：'Lib/xml/dom/pulldom.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/xml/dom/pulldom.py}


__________________________________________________________________


The @ref{129,,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 備註 
如果你需要剖析不受信任或未經驗證的資料，請參閱 @ref{3ba2,,XML 安全性}。
@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
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} 是一個常數，可以是以下其中一個：


@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{3c85,,DOMEventStream.expandNode()} method
and switch to DOM-related processing.

@geindex PullDom (xml.dom.pulldom 中的類別)
@anchor{library/xml dom pulldom xml dom pulldom PullDom}@anchor{3c86}
@deffn {類別} xml.dom.pulldom.PullDom (documentFactory=None)

@ref{3c87,,xml.sax.handler.ContentHandler} 的子類別。
@end deffn

@geindex SAX2DOM (xml.dom.pulldom 中的類別)
@anchor{library/xml dom pulldom xml dom pulldom SAX2DOM}@anchor{3c88}
@deffn {類別} xml.dom.pulldom.SAX2DOM (documentFactory=None)

@ref{3c87,,xml.sax.handler.ContentHandler} 的子類別。
@end deffn

@geindex parse() (於 xml.dom.pulldom 模組中)
@anchor{library/xml dom pulldom xml dom pulldom parse}@anchor{3c89}
@deffn {函式} xml.dom.pulldom.parse (stream_or_string, parser=None, bufsize=None)

Return a @ref{936,,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{3c8a,,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{3c8b,,parseString()} function instead:

@geindex parseString() (於 xml.dom.pulldom 模組中)
@anchor{library/xml dom pulldom xml dom pulldom parseString}@anchor{3c8b}
@deffn {函式} xml.dom.pulldom.parseString (string, parser=None)

回傳一個表示 (Unicode) `string' 的 @ref{936,,DOMEventStream}。
@end deffn

@geindex default_bufsize (於 xml.dom.pulldom 模組中)
@anchor{library/xml dom pulldom xml dom pulldom default_bufsize}@anchor{3c8c}
@deffn {資料} xml.dom.pulldom.default_bufsize

Default value for the `bufsize' parameter to @ref{3c89,,parse()}.

The value of this variable can be changed before calling @ref{3c89,,parse()} and
the new value will take effect.
@end deffn

@menu
* DOMEventStream 物件:: 

@end menu

@node DOMEventStream 物件,,,xml dom pulldom --- 支援建置部分 DOM 樹
@anchor{library/xml dom pulldom domeventstream-objects}@anchor{3c8d}@anchor{library/xml dom pulldom id1}@anchor{3c8e}
@subsubsection DOMEventStream 物件


@geindex DOMEventStream (xml.dom.pulldom 中的類別)
@anchor{library/xml dom pulldom xml dom pulldom DOMEventStream}@anchor{936}
@deffn {類別} xml.dom.pulldom.DOMEventStream (stream, parser, bufsize)


在 3.11 版的變更: 已移除對 @ref{582,,__getitem__()} 方法的支援。


@geindex getEvent() (xml.dom.pulldom.DOMEventStream 的方法)
@anchor{library/xml dom pulldom xml dom pulldom DOMEventStream getEvent}@anchor{3c8f}
@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{3c85,,expandNode()} is called.
@end deffn

@geindex expandNode() (xml.dom.pulldom.DOMEventStream 的方法)
@anchor{library/xml dom pulldom xml dom pulldom DOMEventStream expandNode}@anchor{3c85}
@deffn {方法} expandNode (node)

展開 `node' 的所有子節點到 `node'。範例：

@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':
        # 以下陳述式只會印出 '<p/>'
        print(node.toxml())
        doc.expandNode(node)
        # 以下陳述式會印出包含所有子節點的節點 '<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{3c90}
@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 --- SAX2 剖析器支援,xml sax handler --- SAX 處理函式的基本類別,xml dom pulldom --- 支援建置部分 DOM 樹,結構化標記處理工具
@anchor{library/xml sax doc}@anchor{3c91}@anchor{library/xml sax module-xml sax}@anchor{12f}@anchor{library/xml sax translation-repo}@anchor{3c92}@anchor{library/xml sax xml-sax-support-for-sax2-parsers}@anchor{3c93}
@subsection @code{xml.sax} --- SAX2 剖析器支援


@geindex module; xml.sax

`原始碼：'Lib/xml/sax/__init__.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/xml/sax/__init__.py}


__________________________________________________________________


The @ref{12f,,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 備註 
如果你需要剖析不受信任或未經驗證的資料，請參閱 @ref{3ba2,,XML 安全性}。
@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{3c94,,setFeature()} on the parser object
and argument @ref{3c95,,feature_external_ges}.


The convenience functions are:

@geindex make_parser() (於 xml.sax 模組中)
@anchor{library/xml sax xml sax make_parser}@anchor{1ce4}
@deffn {函式} xml.sax.make_parser (parser_list=[])

Create and return a SAX @ref{3c8a,,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{1caf}
@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{3c87,,ContentHandler} instance.  If
`error_handler' is given, it must be a SAX @ref{3c96,,ErrorHandler}
instance; if
omitted,  @ref{3c97,,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{1097}
@deffn {函式} xml.sax.parseString (string, handler, error_handler=handler.ErrorHandler())

Similar to @ref{1caf,,parse()}, but parses from a buffer `string' received as a
parameter.  `string' must be a @ref{169,,str} instance or a
@ref{193,,bytes-like object}.


在 3.5 版的變更: 新增 @ref{169,,str} 實例的支援。

@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{1096,,InputSource}, @ref{3c98,,Locator},
@code{Attributes}, @code{AttributesNS},
and @ref{3c8a,,XMLReader} interfaces are defined in the
module @ref{132,,xml.sax.xmlreader}.  The handler interfaces are defined in
@ref{130,,xml.sax.handler}.  For convenience,
@ref{1096,,InputSource} (which is often
instantiated directly) and the handler classes are also available from
@ref{12f,,xml.sax}.  These interfaces are described below.

In addition to these classes, @ref{12f,,xml.sax} provides the following exception
classes.

@geindex SAXException
@anchor{library/xml sax xml sax SAXException}@anchor{3c99}
@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{3c96,,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{3c97}
@deffn {例外} xml.sax.SAXParseException (msg, exception, locator)

Subclass of @ref{3c99,,SAXException} raised on parse errors. Instances of this
class are passed to the methods of the SAX
@ref{3c96,,ErrorHandler} interface to provide information
about the parse error.  This class supports the SAX
@ref{3c98,,Locator} interface as well as the
@ref{3c99,,SAXException} interface.
@end deffn

@geindex SAXNotRecognizedException
@anchor{library/xml sax xml sax SAXNotRecognizedException}@anchor{3c9a}
@deffn {例外} xml.sax.SAXNotRecognizedException (msg, exception=None)

Subclass of @ref{3c99,,SAXException} raised when a SAX
@ref{3c8a,,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{3c9b}
@deffn {例外} xml.sax.SAXNotSupportedException (msg, exception=None)

Subclass of @ref{3c99,,SAXException} raised when a SAX
@ref{3c8a,,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 @ref{130,,xml.sax.handler} 模組

Definitions of the interfaces for application-provided objects.

@item @ref{131,,xml.sax.saxutils} 模組

Convenience functions for use in SAX applications.

@item @ref{132,,xml.sax.xmlreader} 模組

Definitions of the interfaces for parser-provided objects.
@end table


@menu
* SAXException 物件:: 

@end menu

@node SAXException 物件,,,xml sax --- SAX2 剖析器支援
@anchor{library/xml sax sax-exception-objects}@anchor{3c9c}@anchor{library/xml sax saxexception-objects}@anchor{3c9d}
@subsubsection SAXException 物件


The @ref{3c99,,SAXException} exception class supports the following methods:

@geindex getMessage() (xml.sax.SAXException 的方法)
@anchor{library/xml sax xml sax SAXException getMessage}@anchor{3c9e}
@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{3c9f}
@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 工具程式,xml sax --- SAX2 剖析器支援,結構化標記處理工具
@anchor{library/xml sax handler doc}@anchor{3ca0}@anchor{library/xml sax handler module-xml sax handler}@anchor{130}@anchor{library/xml sax handler translation-repo}@anchor{3ca1}@anchor{library/xml sax handler xml-sax-handler-base-classes-for-sax-handlers}@anchor{3ca2}
@subsection @code{xml.sax.handler} --- SAX 處理函式的基本類別


@geindex module; xml.sax.handler

`原始碼：'Lib/xml/sax/handler.py@footnote{https://github.com/python/cpython/tree/3.14/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 @ref{130,,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{3c87}
@deffn {類別} xml.sax.handler.ContentHandler

This is the main callback interface in SAX, and the one most important to
applications. The order of events in this interface mirrors the order of the
information in the document.
@end deffn

@geindex DTDHandler (xml.sax.handler 中的類別)
@anchor{library/xml sax handler xml sax handler DTDHandler}@anchor{3ca3}
@deffn {類別} xml.sax.handler.DTDHandler

Handle DTD events.

This interface specifies only those DTD events required for basic parsing
(unparsed entities and attributes).
@end deffn

@geindex EntityResolver (xml.sax.handler 中的類別)
@anchor{library/xml sax handler xml sax handler EntityResolver}@anchor{3ca4}
@deffn {類別} xml.sax.handler.EntityResolver

Basic interface for resolving entities. If you create an object implementing
this interface, then register the object with your Parser, the parser will call
the method in your object to resolve all external entities.
@end deffn

@geindex ErrorHandler (xml.sax.handler 中的類別)
@anchor{library/xml sax handler xml sax handler ErrorHandler}@anchor{3c96}
@deffn {類別} xml.sax.handler.ErrorHandler

Interface used by the parser to present error and warning messages to the
application.  The methods of this object control whether errors are immediately
converted to exceptions or are handled in some other way.
@end deffn

@geindex LexicalHandler (xml.sax.handler 中的類別)
@anchor{library/xml sax handler xml sax handler LexicalHandler}@anchor{a55}
@deffn {類別} xml.sax.handler.LexicalHandler

Interface used by the parser to represent low frequency events which may not
be of interest to many applications.
@end deffn

In addition to these classes, @ref{130,,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{3ca5}
@deffn {資料} xml.sax.handler.feature_namespaces


@display
value: @code{"http://xml.org/sax/features/namespaces"}@w{ }
true: Perform Namespace processing.@w{ }
false: Optionally do not perform Namespace processing (implies namespace-prefixes; default).@w{ }
access: (parsing) read-only; (not parsing) read/write@w{ }
@end display


@end deffn

@geindex feature_namespace_prefixes (於 xml.sax.handler 模組中)
@anchor{library/xml sax handler xml sax handler feature_namespace_prefixes}@anchor{3ca6}
@deffn {資料} xml.sax.handler.feature_namespace_prefixes


@display
value: @code{"http://xml.org/sax/features/namespace-prefixes"}@w{ }
true: Report the original prefixed names and attributes used for Namespace declarations.@w{ }
false: Do not report attributes used for Namespace declarations, and optionally do not report original prefixed names (default).@w{ }
access: (parsing) read-only; (not parsing) read/write@w{ }
@end display


@end deffn

@geindex feature_string_interning (於 xml.sax.handler 模組中)
@anchor{library/xml sax handler xml sax handler feature_string_interning}@anchor{3ca7}
@deffn {資料} xml.sax.handler.feature_string_interning


@display
value: @code{"http://xml.org/sax/features/string-interning"}@w{ }
true: All element names, prefixes, attribute names, Namespace URIs, and local names are interned using the built-in intern function.@w{ }
false: Names are not necessarily interned, although they may be (default).@w{ }
access: (parsing) read-only; (not parsing) read/write@w{ }
@end display


@end deffn

@geindex feature_validation (於 xml.sax.handler 模組中)
@anchor{library/xml sax handler xml sax handler feature_validation}@anchor{3ca8}
@deffn {資料} xml.sax.handler.feature_validation


@display
value: @code{"http://xml.org/sax/features/validation"}@w{ }
true: Report all validation errors (implies external-general-entities and external-parameter-entities).@w{ }
false: Do not report validation errors.@w{ }
access: (parsing) read-only; (not parsing) read/write@w{ }
@end display


@end deffn

@geindex feature_external_ges (於 xml.sax.handler 模組中)
@anchor{library/xml sax handler xml sax handler feature_external_ges}@anchor{3c95}
@deffn {資料} xml.sax.handler.feature_external_ges


@display
value: @code{"http://xml.org/sax/features/external-general-entities"}@w{ }
true: Include all external general (text) entities.@w{ }
false: Do not include external general entities.@w{ }
access: (parsing) read-only; (not parsing) read/write@w{ }
@end display


@end deffn

@geindex feature_external_pes (於 xml.sax.handler 模組中)
@anchor{library/xml sax handler xml sax handler feature_external_pes}@anchor{3ca9}
@deffn {資料} xml.sax.handler.feature_external_pes


@display
value: @code{"http://xml.org/sax/features/external-parameter-entities"}@w{ }
true: Include all external parameter entities, including the external DTD subset.@w{ }
false: Do not include any external parameter entities, even the external DTD subset.@w{ }
access: (parsing) read-only; (not parsing) read/write@w{ }
@end display


@end deffn

@geindex all_features (於 xml.sax.handler 模組中)
@anchor{library/xml sax handler xml sax handler all_features}@anchor{3caa}
@deffn {資料} xml.sax.handler.all_features

List of all features.
@end deffn

@geindex property_lexical_handler (於 xml.sax.handler 模組中)
@anchor{library/xml sax handler xml sax handler property_lexical_handler}@anchor{3cab}
@deffn {資料} xml.sax.handler.property_lexical_handler


@display
value: @code{"http://xml.org/sax/properties/lexical-handler"}@w{ }
data type: xml.sax.handler.LexicalHandler (not supported in Python 2)@w{ }
description: An optional extension handler for lexical events like comments.@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{3cac}
@deffn {資料} xml.sax.handler.property_declaration_handler


@display
value: @code{"http://xml.org/sax/properties/declaration-handler"}@w{ }
data type: xml.sax.sax2lib.DeclHandler (not supported in Python 2)@w{ }
description: An optional extension handler for DTD-related events other than notations and unparsed entities.@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{3cad}
@deffn {資料} xml.sax.handler.property_dom_node


@display
value: @code{"http://xml.org/sax/properties/dom-node"}@w{ }
data type: org.w3c.dom.Node (not supported in Python 2)@w{ }
description: When parsing, the current DOM node being visited if this is a DOM iterator; when not parsing, the root DOM node for iteration.@w{ }
access: (parsing) read-only; (not parsing) read/write@w{ }
@end display


@end deffn

@geindex property_xml_string (於 xml.sax.handler 模組中)
@anchor{library/xml sax handler xml sax handler property_xml_string}@anchor{3cae}
@deffn {資料} xml.sax.handler.property_xml_string


@display
value: @code{"http://xml.org/sax/properties/xml-string"}@w{ }
data type: Bytes@w{ }
description: The literal string of characters that was the source for the current event.@w{ }
access: read-only@w{ }
@end display


@end deffn

@geindex all_properties (於 xml.sax.handler 模組中)
@anchor{library/xml sax handler xml sax handler all_properties}@anchor{3caf}
@deffn {資料} xml.sax.handler.all_properties

List of all known property names.
@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{3cb0}@anchor{library/xml sax handler contenthandler-objects}@anchor{3cb1}
@subsubsection ContentHandler 物件


Users are expected to subclass @ref{3c87,,ContentHandler} to support their
application.  The following methods are called by the parser on the appropriate
events in the input document:

@geindex setDocumentLocator() (xml.sax.handler.ContentHandler 的方法)
@anchor{library/xml sax handler xml sax handler ContentHandler setDocumentLocator}@anchor{3cb2}
@deffn {方法} ContentHandler.setDocumentLocator (locator)

Called by the parser to give the application a locator for locating the origin
of document events.

SAX parsers are strongly encouraged (though not absolutely required) to supply a
locator: if it does so, it must supply the locator to the application by
invoking this method before invoking any of the other methods in the
DocumentHandler interface.

The locator allows the application to determine the end position of any
document-related event, even if the parser is not reporting an error. Typically,
the application will use this information for reporting its own errors (such as
character content that does not match an application's business rules). The
information returned by the locator is probably not sufficient for use with a
search engine.

Note that the locator will return correct information only during the invocation
of the events in this interface. The application should not attempt to use it at
any other time.
@end deffn

@geindex startDocument() (xml.sax.handler.ContentHandler 的方法)
@anchor{library/xml sax handler xml sax handler ContentHandler startDocument}@anchor{3cb3}
@deffn {方法} ContentHandler.startDocument ()

Receive notification of the beginning of a document.

The SAX parser will invoke this method only once, before any other methods in
this interface or in DTDHandler (except for @ref{3cb2,,setDocumentLocator()}).
@end deffn

@geindex endDocument() (xml.sax.handler.ContentHandler 的方法)
@anchor{library/xml sax handler xml sax handler ContentHandler endDocument}@anchor{3cb4}
@deffn {方法} ContentHandler.endDocument ()

Receive notification of the end of a document.

The SAX parser will invoke this method only once, and it will be the last method
invoked during the parse. The parser shall not invoke this method until it has
either abandoned parsing (because of an unrecoverable error) or reached the end
of input.
@end deffn

@geindex startPrefixMapping() (xml.sax.handler.ContentHandler 的方法)
@anchor{library/xml sax handler xml sax handler ContentHandler startPrefixMapping}@anchor{3cb5}
@deffn {方法} ContentHandler.startPrefixMapping (prefix, uri)

Begin the scope of a prefix-URI Namespace mapping.

The information from this event is not necessary for normal Namespace
processing: the SAX XML reader will automatically replace prefixes for element
and attribute names when the @code{feature_namespaces} feature is enabled (the
default).

There are cases, however, when applications need to use prefixes in character
data or in attribute values, where they cannot safely be expanded automatically;
the @ref{3cb5,,startPrefixMapping()} and @ref{3cb6,,endPrefixMapping()} events supply the
information to the application to expand prefixes in those contexts itself, if
necessary.

@c XXX This is not really the default, is it? MvL

Note that @ref{3cb5,,startPrefixMapping()} and @ref{3cb6,,endPrefixMapping()} events are not
guaranteed to be properly nested relative to each-other: all
@ref{3cb5,,startPrefixMapping()} events will occur before the corresponding
@ref{1737,,startElement()} event, and all @ref{3cb6,,endPrefixMapping()} events will occur
after the corresponding @ref{1738,,endElement()} event, but their order is not
guaranteed.
@end deffn

@geindex endPrefixMapping() (xml.sax.handler.ContentHandler 的方法)
@anchor{library/xml sax handler xml sax handler ContentHandler endPrefixMapping}@anchor{3cb6}
@deffn {方法} ContentHandler.endPrefixMapping (prefix)

End the scope of a prefix-URI mapping.

See @ref{3cb5,,startPrefixMapping()} for details. This event will always occur after
the corresponding @ref{1738,,endElement()} event, but the order of
@ref{3cb6,,endPrefixMapping()} events is not otherwise guaranteed.
@end deffn

@geindex startElement() (xml.sax.handler.ContentHandler 的方法)
@anchor{library/xml sax handler xml sax handler ContentHandler startElement}@anchor{1737}
@deffn {方法} ContentHandler.startElement (name, attrs)

Signals the start of an element in non-namespace mode.

The `name' parameter contains the raw XML 1.0 name of the element type as a
string and the `attrs' parameter holds an object of the
@ref{3cb7,,Attributes} interface containing the attributes of
the element.  The object passed as `attrs' may be re-used by the parser; holding
on to a reference to it is not a reliable way to keep a copy of the attributes.
To keep a copy of the attributes, use the @ref{29,,copy()} method of the `attrs'
object.
@end deffn

@geindex endElement() (xml.sax.handler.ContentHandler 的方法)
@anchor{library/xml sax handler xml sax handler ContentHandler endElement}@anchor{1738}
@deffn {方法} ContentHandler.endElement (name)

Signals the end of an element in non-namespace mode.

The `name' parameter contains the name of the element type, just as with the
@ref{1737,,startElement()} event.
@end deffn

@geindex startElementNS() (xml.sax.handler.ContentHandler 的方法)
@anchor{library/xml sax handler xml sax handler ContentHandler startElementNS}@anchor{3cb8}
@deffn {方法} ContentHandler.startElementNS (name, qname, attrs)

Signals the start of an element in namespace mode.

The `name' parameter contains the name of the element type as a @code{(uri,
localname)} tuple, the `qname' parameter contains the raw XML 1.0 name used in
the source document, and the `attrs' parameter holds an instance of the
@ref{3cb9,,AttributesNS} interface
containing the attributes of the element.  If no namespace is associated with
the element, the `uri' component of `name' will be @code{None}.  The object passed
as `attrs' may be re-used by the parser; holding on to a reference to it is not
a reliable way to keep a copy of the attributes.  To keep a copy of the
attributes, use the @ref{29,,copy()} method of the `attrs' object.

Parsers may set the `qname' parameter to @code{None}, unless the
@code{feature_namespace_prefixes} feature is activated.
@end deffn

@geindex endElementNS() (xml.sax.handler.ContentHandler 的方法)
@anchor{library/xml sax handler xml sax handler ContentHandler endElementNS}@anchor{3cba}
@deffn {方法} ContentHandler.endElementNS (name, qname)

Signals the end of an element in namespace mode.

The `name' parameter contains the name of the element type, just as with the
@ref{3cb8,,startElementNS()} method, likewise the `qname' parameter.
@end deffn

@geindex characters() (xml.sax.handler.ContentHandler 的方法)
@anchor{library/xml sax handler xml sax handler ContentHandler characters}@anchor{1739}
@deffn {方法} ContentHandler.characters (content)

Receive notification of character data.

The Parser will call this method to report each chunk of character data. SAX
parsers may return all contiguous character data in a single chunk, or they may
split it into several chunks; however, all of the characters in any single event
must come from the same external entity so that the Locator provides useful
information.

`content' may be a string or bytes instance; the @code{expat} reader module
always produces strings.

@cartouche
@quotation 備註 
The earlier SAX 1 interface provided by the Python XML Special Interest Group
used a more Java-like interface for this method.  Since most parsers used from
Python did not take advantage of the older interface, the simpler signature was
chosen to replace it.  To convert old code to the new interface, use `content'
instead of slicing content with the old `offset' and `length' parameters.
@end quotation
@end cartouche
@end deffn

@geindex ignorableWhitespace() (xml.sax.handler.ContentHandler 的方法)
@anchor{library/xml sax handler xml sax handler ContentHandler ignorableWhitespace}@anchor{3cbb}
@deffn {方法} ContentHandler.ignorableWhitespace (whitespace)

Receive notification of ignorable whitespace in element content.

Validating Parsers must use this method to report each chunk of ignorable
whitespace (see the W3C XML 1.0 recommendation, section 2.10): non-validating
parsers may also use this method if they are capable of parsing and using
content models.

SAX parsers may return all contiguous whitespace in a single chunk, or they may
split it into several chunks; however, all of the characters in any single event
must come from the same external entity, so that the Locator provides useful
information.
@end deffn

@geindex processingInstruction() (xml.sax.handler.ContentHandler 的方法)
@anchor{library/xml sax handler xml sax handler ContentHandler processingInstruction}@anchor{3cbc}
@deffn {方法} ContentHandler.processingInstruction (target, data)

Receive notification of a processing instruction.

The Parser will invoke this method once for each processing instruction found:
note that processing instructions may occur before or after the main document
element.

A SAX parser should never report an XML declaration (XML 1.0, section 2.8) or a
text declaration (XML 1.0, section 4.3.1) using this method.
@end deffn

@geindex skippedEntity() (xml.sax.handler.ContentHandler 的方法)
@anchor{library/xml sax handler xml sax handler ContentHandler skippedEntity}@anchor{3cbd}
@deffn {方法} ContentHandler.skippedEntity (name)

Receive notification of a skipped entity.

The Parser will invoke this method once for each entity skipped. Non-validating
processors may skip entities if they have not seen the declarations (because,
for example, the entity was declared in an external DTD subset). All processors
may skip external entities, depending on the values of the
@code{feature_external_ges} and the @code{feature_external_pes} properties.
@end deffn

@node DTDHandler 物件,EntityResolver 物件,ContentHandler 物件,xml sax handler --- SAX 處理函式的基本類別
@anchor{library/xml sax handler dtd-handler-objects}@anchor{3cbe}@anchor{library/xml sax handler dtdhandler-objects}@anchor{3cbf}
@subsubsection DTDHandler 物件


@ref{3ca3,,DTDHandler} instances provide the following methods:

@geindex notationDecl() (xml.sax.handler.DTDHandler 的方法)
@anchor{library/xml sax handler xml sax handler DTDHandler notationDecl}@anchor{3cc0}
@deffn {方法} DTDHandler.notationDecl (name, publicId, systemId)

Handle a notation declaration event.
@end deffn

@geindex unparsedEntityDecl() (xml.sax.handler.DTDHandler 的方法)
@anchor{library/xml sax handler xml sax handler DTDHandler unparsedEntityDecl}@anchor{3cc1}
@deffn {方法} DTDHandler.unparsedEntityDecl (name, publicId, systemId, ndata)

Handle an unparsed entity declaration event.
@end deffn

@node EntityResolver 物件,ErrorHandler 物件,DTDHandler 物件,xml sax handler --- SAX 處理函式的基本類別
@anchor{library/xml sax handler entity-resolver-objects}@anchor{3cc2}@anchor{library/xml sax handler entityresolver-objects}@anchor{3cc3}
@subsubsection EntityResolver 物件


@geindex resolveEntity() (xml.sax.handler.EntityResolver 的方法)
@anchor{library/xml sax handler xml sax handler EntityResolver resolveEntity}@anchor{3cc4}
@deffn {方法} EntityResolver.resolveEntity (publicId, systemId)

Resolve the system identifier of an entity and return either the system
identifier to read from as a string, or an InputSource to read from. The default
implementation returns `systemId'.
@end deffn

@node ErrorHandler 物件,LexicalHandler 物件,EntityResolver 物件,xml sax handler --- SAX 處理函式的基本類別
@anchor{library/xml sax handler errorhandler-objects}@anchor{3cc5}@anchor{library/xml sax handler sax-error-handler}@anchor{3cc6}
@subsubsection ErrorHandler 物件


Objects with this interface are used to receive error and warning information
from the @ref{3c8a,,XMLReader}.  If you create an object that
implements this interface, then register the object with your
@ref{3c8a,,XMLReader}, the parser
will call the methods in your object to report all warnings and errors. There
are three levels of errors available: warnings, (possibly) recoverable errors,
and unrecoverable errors.  All methods take a @ref{3c97,,SAXParseException} as the
only parameter.  Errors and warnings may be converted to an exception by raising
the passed-in exception object.

@geindex error() (xml.sax.handler.ErrorHandler 的方法)
@anchor{library/xml sax handler xml sax handler ErrorHandler error}@anchor{3cc7}
@deffn {方法} ErrorHandler.error (exception)

Called when the parser encounters a recoverable error.  If this method does not
raise an exception, parsing may continue, but further document information
should not be expected by the application.  Allowing the parser to continue may
allow additional errors to be discovered in the input document.
@end deffn

@geindex fatalError() (xml.sax.handler.ErrorHandler 的方法)
@anchor{library/xml sax handler xml sax handler ErrorHandler fatalError}@anchor{3cc8}
@deffn {方法} ErrorHandler.fatalError (exception)

Called when the parser encounters an error it cannot recover from; parsing is
expected to terminate when this method returns.
@end deffn

@geindex warning() (xml.sax.handler.ErrorHandler 的方法)
@anchor{library/xml sax handler xml sax handler ErrorHandler warning}@anchor{3cc9}
@deffn {方法} ErrorHandler.warning (exception)

Called when the parser presents minor warning information to the application.
Parsing is expected to continue when this method returns, and document
information will continue to be passed to the application. Raising an exception
in this method will cause parsing to end.
@end deffn

@node LexicalHandler 物件,,ErrorHandler 物件,xml sax handler --- SAX 處理函式的基本類別
@anchor{library/xml sax handler lexical-handler-objects}@anchor{3cca}@anchor{library/xml sax handler lexicalhandler-objects}@anchor{3ccb}
@subsubsection LexicalHandler 物件


Optional SAX2 handler for lexical events.

This handler is used to obtain lexical information about an XML
document. Lexical information includes information describing the
document encoding used and XML comments embedded in the document, as
well as section boundaries for the DTD and for any CDATA sections.
The lexical handlers are used in the same manner as content handlers.

Set the LexicalHandler of an XMLReader by using the setProperty method
with the property identifier
@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{3ccc}
@deffn {方法} LexicalHandler.comment (content)

Reports a comment anywhere in the document (including the DTD and
outside the document element).
@end deffn

@geindex startDTD() (xml.sax.handler.LexicalHandler 的方法)
@anchor{library/xml sax handler xml sax handler LexicalHandler startDTD}@anchor{3ccd}
@deffn {方法} LexicalHandler.startDTD (name, public_id, system_id)

Reports the start of the DTD declarations if the document has an
associated DTD.
@end deffn

@geindex endDTD() (xml.sax.handler.LexicalHandler 的方法)
@anchor{library/xml sax handler xml sax handler LexicalHandler endDTD}@anchor{3cce}
@deffn {方法} LexicalHandler.endDTD ()

Reports the end of DTD declaration.
@end deffn

@geindex startCDATA() (xml.sax.handler.LexicalHandler 的方法)
@anchor{library/xml sax handler xml sax handler LexicalHandler startCDATA}@anchor{3ccf}
@deffn {方法} LexicalHandler.startCDATA ()

Reports the start of a CDATA marked section.

The contents of the CDATA marked section will be reported through
the characters handler.
@end deffn

@geindex endCDATA() (xml.sax.handler.LexicalHandler 的方法)
@anchor{library/xml sax handler xml sax handler LexicalHandler endCDATA}@anchor{3cd0}
@deffn {方法} LexicalHandler.endCDATA ()

Reports the end of a CDATA marked section.
@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 工具程式,xml sax xmlreader --- XML 剖析器的介面,xml sax handler --- SAX 處理函式的基本類別,結構化標記處理工具
@anchor{library/xml sax utils doc}@anchor{3cd1}@anchor{library/xml sax utils module-xml sax saxutils}@anchor{131}@anchor{library/xml sax utils translation-repo}@anchor{3cd2}@anchor{library/xml sax utils xml-sax-saxutils-sax-utilities}@anchor{3cd3}
@subsection @code{xml.sax.saxutils} --- SAX 工具程式


@geindex module; xml.sax.saxutils

`原始碼：'Lib/xml/sax/saxutils.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/xml/sax/saxutils.py}


__________________________________________________________________


模組 @ref{131,,xml.sax.saxutils} 包含了許多在建立 SAX 應用程式時非常有用的類別和函式，這些類別和函式可以直接使用，也可以作為基底類別。

@geindex escape() (於 xml.sax.saxutils 模組中)
@anchor{library/xml sax utils xml sax saxutils escape}@anchor{3cd4}
@deffn {函式} xml.sax.saxutils.escape (data, entities=@{@})

在資料字串中跳脫 @code{'&'}、@code{'<'} 及 @code{'>'}。

你可以透過傳入字典作為可選的 `entities' 參數，來跳脫其他資料字串。鍵和值都必須是字串；每個鍵都會被對應的值取代。即使提供 `entities'，@code{'&'}、@code{'<'} 和 @code{'>'} 字元始終會被跳脫。

@cartouche
@quotation 備註 
這個函式只能用來跳脫 XML 中無法直接使用的字元。請勿將此函式用作一般的字串轉換函式。
@end quotation
@end cartouche
@end deffn

@geindex unescape() (於 xml.sax.saxutils 模組中)
@anchor{library/xml sax utils xml sax saxutils unescape}@anchor{3cd5}
@deffn {函式} xml.sax.saxutils.unescape (data, entities=@{@})

取消跳脫資料字串中的 @code{'&amp;'}、@code{'&lt;'} 和 @code{'&gt;'}。

你可以透過傳入字典作為可選的 `entities' 參數，來取消其他字串的資料。鍵和值都必須是字串；每個鍵都會被對應的值取代。即使提供了 `entities'，@code{'&amp'}、@code{'&lt;’} 和 @code{‘&gt;'} 總是會取消跳脫。
@end deffn

@geindex quoteattr() (於 xml.sax.saxutils 模組中)
@anchor{library/xml sax utils xml sax saxutils quoteattr}@anchor{3cd6}
@deffn {函式} xml.sax.saxutils.quoteattr (data, entities=@{@})

類似於 @ref{3cd4,,escape()}，但也準備 `data' 作為屬性值。@ref{3cd6,,quoteattr()} 會根據 `data' 的內容選擇引號字元，嘗試避免在字串中編碼任何引號字元。如果 `data' 中已經有單引號和雙引號字元，雙引號字元將被編碼，而 `data' 將被雙引號包覆。結果字串可直接用作屬性值：

@example
>>> print("<element attr=%s>" % quoteattr("ab ' cd \" ef"))
<element attr="ab ' cd &quot; ef">
@end example

當使用參考具體語法為 HTML 或任何 SGML 產生屬性值時，此功能非常有用。
@end deffn

@geindex XMLGenerator (xml.sax.saxutils 中的類別)
@anchor{library/xml sax utils xml sax saxutils XMLGenerator}@anchor{3cd7}
@deffn {類別} xml.sax.saxutils.XMLGenerator (out=None, encoding='iso-8859-1', short_empty_elements=False)

這個類別透過將 SAX 事件寫回 XML 文件來實作 @ref{3c87,,ContentHandler} 介面。換句話說，使用 @ref{3cd7,,XMLGenerator} 作為內容處理器將會重現被剖析的原始文件。`out' 應該是類檔案物件，預設為 `sys.stdout'。`encoding' 是輸出串流的編碼，預設為 @code{'iso-8859-1'}。`short_empty_elements' 控制不包含內容的元素的格式：如果設定為 @code{False}（預設值），它們會以一對開始/結束（start/end）標籤的形式輸出；如果設定為 @code{True}，它們會以單一自封（self-closed）標籤的形式輸出。


在 3.2 版的變更: 新增 `short_empty_elements' 參數。

@end deffn

@geindex XMLFilterBase (xml.sax.saxutils 中的類別)
@anchor{library/xml sax utils xml sax saxutils XMLFilterBase}@anchor{3cd8}
@deffn {類別} xml.sax.saxutils.XMLFilterBase (base)

這個類別的設計是在 @ref{3c8a,,XMLReader} 與用戶端應用程式的事件處理程式之間。預設情況下，它什麼都不做，只是將要求傳送到閱讀器，並將事件未經修改地傳送到處理程式，但子類別可以覆寫特定的方法，以在傳送它們的時候修改事件串流或配置請求。
@end deffn

@geindex prepare_input_source() (於 xml.sax.saxutils 模組中)
@anchor{library/xml sax utils xml sax saxutils prepare_input_source}@anchor{3cd9}
@deffn {函式} xml.sax.saxutils.prepare_input_source (source, base='@w{'})

這個函式接收一個輸入來源和一個可選的基底 URL，並回傳一個完全解析的 @ref{1096,,InputSource} 物件，以準備讀取。輸入來源可以是字串、類檔案物件或 @ref{1096,,InputSource} 物件；剖析器會使用這個函式來實作它們的 @ref{3cda,,parse()} 方法的多型 `source' 引數。
@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 --- XML 剖析器的介面,xml parsers expat --- 使用 Expat 進行快速 XML 剖析,xml sax saxutils --- SAX 工具程式,結構化標記處理工具
@anchor{library/xml sax reader doc}@anchor{3cdb}@anchor{library/xml sax reader module-xml sax xmlreader}@anchor{132}@anchor{library/xml sax reader translation-repo}@anchor{3cdc}@anchor{library/xml sax reader xml-sax-xmlreader-interface-for-xml-parsers}@anchor{3cdd}
@subsection @code{xml.sax.xmlreader} --- XML 剖析器的介面


@geindex module; xml.sax.xmlreader

`原始碼：'Lib/xml/sax/xmlreader.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/xml/sax/xmlreader.py}


__________________________________________________________________


SAX parsers implement the @ref{3c8a,,XMLReader} interface. They are implemented in
a Python module, which must provide a function @code{create_parser()}. This
function is invoked by  @ref{1ce4,,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{3c8a}
@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{3cde}
@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{3c98}
@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{1096}
@deffn {類別} xml.sax.xmlreader.InputSource (system_id=None)

Encapsulation of the information needed by the @ref{3c8a,,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{3cda,,XMLReader.parse()} method and for returning from
EntityResolver.resolveEntity.

An @ref{1096,,InputSource} belongs to the application, the @ref{3c8a,,XMLReader} is
not allowed to modify @ref{1096,,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{3cdf}
@deffn {類別} xml.sax.xmlreader.AttributesImpl (attrs)

This is an implementation of the @code{Attributes} interface (see section
@ref{3cb7,,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{3ce0}
@deffn {類別} xml.sax.xmlreader.AttributesNSImpl (attrs, qnames)

Namespace-aware variant of @ref{3cdf,,AttributesImpl}, which will be passed to
@code{startElementNS()}. It is derived from @ref{3cdf,,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{3cb9,,The AttributesNS Interface}).
@end deffn

@menu
* XMLReader 物件:: 
* IncrementalParser 物件:: 
* Locator Objects:: 
* InputSource 物件:: 
* The Attributes Interface:: 
* The AttributesNS Interface:: 

@end menu

@node XMLReader 物件,IncrementalParser 物件,,xml sax xmlreader --- XML 剖析器的介面
@anchor{library/xml sax reader id1}@anchor{3ce1}@anchor{library/xml sax reader xmlreader-objects}@anchor{3ce2}
@subsubsection XMLReader 物件


The @ref{3c8a,,XMLReader} interface supports the following methods:

@geindex parse() (xml.sax.xmlreader.XMLReader 的方法)
@anchor{library/xml sax reader xml sax xmlreader XMLReader parse}@anchor{3cda}
@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{266,,pathlib.Path} or @ref{59b,,path-like}
object, or an @ref{1096,,InputSource} object. When
@ref{3cda,,parse()} returns, the input is completely processed, and the parser object
can be discarded or reset.


在 3.5 版的變更: 新增對字元串流的支援。



在 3.8 版的變更: 新增對類路徑物件的支援。

@end deffn

@geindex getContentHandler() (xml.sax.xmlreader.XMLReader 的方法)
@anchor{library/xml sax reader xml sax xmlreader XMLReader getContentHandler}@anchor{3ce3}
@deffn {方法} XMLReader.getContentHandler ()

Return the current @ref{3c87,,ContentHandler}.
@end deffn

@geindex setContentHandler() (xml.sax.xmlreader.XMLReader 的方法)
@anchor{library/xml sax reader xml sax xmlreader XMLReader setContentHandler}@anchor{3ce4}
@deffn {方法} XMLReader.setContentHandler (handler)

Set the current @ref{3c87,,ContentHandler}.  If no
@ref{3c87,,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{3ce5}
@deffn {方法} XMLReader.getDTDHandler ()

Return the current @ref{3ca3,,DTDHandler}.
@end deffn

@geindex setDTDHandler() (xml.sax.xmlreader.XMLReader 的方法)
@anchor{library/xml sax reader xml sax xmlreader XMLReader setDTDHandler}@anchor{3ce6}
@deffn {方法} XMLReader.setDTDHandler (handler)

Set the current @ref{3ca3,,DTDHandler}.  If no
@ref{3ca3,,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{3ce7}
@deffn {方法} XMLReader.getEntityResolver ()

Return the current @ref{3ca4,,EntityResolver}.
@end deffn

@geindex setEntityResolver() (xml.sax.xmlreader.XMLReader 的方法)
@anchor{library/xml sax reader xml sax xmlreader XMLReader setEntityResolver}@anchor{3ce8}
@deffn {方法} XMLReader.setEntityResolver (handler)

Set the current @ref{3ca4,,EntityResolver}.  If no
@ref{3ca4,,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{3ce9}
@deffn {方法} XMLReader.getErrorHandler ()

Return the current @ref{3c96,,ErrorHandler}.
@end deffn

@geindex setErrorHandler() (xml.sax.xmlreader.XMLReader 的方法)
@anchor{library/xml sax reader xml sax xmlreader XMLReader setErrorHandler}@anchor{3cea}
@deffn {方法} XMLReader.setErrorHandler (handler)

Set the current error handler.  If no @ref{3c96,,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{3ceb}
@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{3cec}
@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{130,,xml.sax.handler}.
@end deffn

@geindex setFeature() (xml.sax.xmlreader.XMLReader 的方法)
@anchor{library/xml sax reader xml sax xmlreader XMLReader setFeature}@anchor{3c94}
@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{3ced}
@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{130,,xml.sax.handler}.
@end deffn

@geindex setProperty() (xml.sax.xmlreader.XMLReader 的方法)
@anchor{library/xml sax reader xml sax xmlreader XMLReader setProperty}@anchor{3cee}
@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 物件,Locator Objects,XMLReader 物件,xml sax xmlreader --- XML 剖析器的介面
@anchor{library/xml sax reader incremental-parser-objects}@anchor{3cef}@anchor{library/xml sax reader incrementalparser-objects}@anchor{3cf0}
@subsubsection IncrementalParser 物件


Instances of @ref{3cde,,IncrementalParser} offer the following additional methods:

@geindex feed() (xml.sax.xmlreader.IncrementalParser 的方法)
@anchor{library/xml sax reader xml sax xmlreader IncrementalParser feed}@anchor{3cf1}
@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{3cf2}
@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{3cf3}
@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 物件,IncrementalParser 物件,xml sax xmlreader --- XML 剖析器的介面
@anchor{library/xml sax reader id2}@anchor{3cf4}@anchor{library/xml sax reader locator-objects}@anchor{3cf5}
@subsubsection Locator Objects


Instances of @ref{3c98,,Locator} provide these methods:

@geindex getColumnNumber() (xml.sax.xmlreader.Locator 的方法)
@anchor{library/xml sax reader xml sax xmlreader Locator getColumnNumber}@anchor{3cf6}
@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{3cf7}
@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{3cf8}
@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{3cf9}
@deffn {方法} Locator.getSystemId ()

Return the system identifier for the current event.
@end deffn

@node InputSource 物件,The Attributes Interface,Locator Objects,xml sax xmlreader --- XML 剖析器的介面
@anchor{library/xml sax reader input-source-objects}@anchor{3cfa}@anchor{library/xml sax reader inputsource-objects}@anchor{3cfb}
@subsubsection InputSource 物件


@geindex setPublicId() (xml.sax.xmlreader.InputSource 的方法)
@anchor{library/xml sax reader xml sax xmlreader InputSource setPublicId}@anchor{3cfc}
@deffn {方法} InputSource.setPublicId (id)

Sets the public identifier of this @ref{1096,,InputSource}.
@end deffn

@geindex getPublicId() (xml.sax.xmlreader.InputSource 的方法)
@anchor{library/xml sax reader xml sax xmlreader InputSource getPublicId}@anchor{3cfd}
@deffn {方法} InputSource.getPublicId ()

Returns the public identifier of this @ref{1096,,InputSource}.
@end deffn

@geindex setSystemId() (xml.sax.xmlreader.InputSource 的方法)
@anchor{library/xml sax reader xml sax xmlreader InputSource setSystemId}@anchor{3cfe}
@deffn {方法} InputSource.setSystemId (id)

Sets the system identifier of this @ref{1096,,InputSource}.
@end deffn

@geindex getSystemId() (xml.sax.xmlreader.InputSource 的方法)
@anchor{library/xml sax reader xml sax xmlreader InputSource getSystemId}@anchor{3cff}
@deffn {方法} InputSource.getSystemId ()

Returns the system identifier of this @ref{1096,,InputSource}.
@end deffn

@geindex setEncoding() (xml.sax.xmlreader.InputSource 的方法)
@anchor{library/xml sax reader xml sax xmlreader InputSource setEncoding}@anchor{3d00}
@deffn {方法} InputSource.setEncoding (encoding)

Sets the character encoding of this @ref{1096,,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{1096,,InputSource} is ignored if the
@ref{1096,,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{3d01}
@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{3d02}
@deffn {方法} InputSource.setByteStream (bytefile)

Set the byte stream (a @ref{1f35,,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{3d03}
@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{3d04}
@deffn {方法} InputSource.setCharacterStream (charfile)

Set the character stream (a @ref{1f34,,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{3d05}
@deffn {方法} InputSource.getCharacterStream ()

Get the character stream for this input source.
@end deffn

@node The Attributes Interface,The AttributesNS Interface,InputSource 物件,xml sax xmlreader --- XML 剖析器的介面
@anchor{library/xml sax reader attributes-objects}@anchor{3cb7}@anchor{library/xml sax reader the-attributes-interface}@anchor{3d06}
@subsubsection The @code{Attributes} Interface


@code{Attributes} objects implement a portion of the @ref{13bc,,mapping protocol}, including the methods @code{copy()},
@code{get()}, @ref{15b1,,__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{3d07}
@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{3d08}
@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{3d09}
@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{3d0a}
@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 --- XML 剖析器的介面
@anchor{library/xml sax reader attributes-ns-objects}@anchor{3cb9}@anchor{library/xml sax reader the-attributesns-interface}@anchor{3d0b}
@subsubsection The @code{AttributesNS} Interface


This interface is a subtype of the @code{Attributes} interface (see section
@ref{3cb7,,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{3d0c}
@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{3d0d}
@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{3d0e}
@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{3d0f}
@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 --- 使用 Expat 進行快速 XML 剖析,,xml sax xmlreader --- XML 剖析器的介面,結構化標記處理工具
@anchor{library/pyexpat doc}@anchor{3d10}@anchor{library/pyexpat module-xml parsers expat}@anchor{12c}@anchor{library/pyexpat translation-repo}@anchor{3d11}@anchor{library/pyexpat xml-parsers-expat-fast-xml-parsing-using-expat}@anchor{3d12}
@subsection @code{xml.parsers.expat} --- 使用 Expat 進行快速 XML 剖析


@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{3ba2,,XML 安全性}。
@end quotation
@end cartouche

@geindex Expat

The @ref{12c,,xml.parsers.expat} module is a Python interface to the Expat
non-validating XML parser. The module provides a single extension type,
@code{xmlparser}, that represents the current state of an XML parser.  After
an @code{xmlparser} object has been created, various attributes of the object
can be set to handler functions.  When an XML document is then fed to the
parser, the handler functions are called for the character data and markup in
the XML document.

@geindex module（模組）;pyexpat

This module uses the @code{pyexpat} module to provide access to the Expat
parser.  Direct use of the @code{pyexpat} module is deprecated.

這個模組提供一個例外和一個型別物件：

@geindex ExpatError
@anchor{library/pyexpat xml parsers expat ExpatError}@anchor{1479}
@deffn {例外} xml.parsers.expat.ExpatError

The exception raised when Expat reports an error.  See section
@ref{3d13,,ExpatError 例外} for more information on interpreting Expat errors.
@end deffn

@geindex error
@anchor{library/pyexpat xml parsers expat error}@anchor{3d14}
@deffn {例外} xml.parsers.expat.error

@ref{1479,,ExpatError} 的別名。
@end deffn

@geindex XMLParserType (於 xml.parsers.expat 模組中)
@anchor{library/pyexpat xml parsers expat XMLParserType}@anchor{3d15}
@deffn {資料} xml.parsers.expat.XMLParserType

The type of the return values from the @ref{3d16,,ParserCreate()} function.
@end deffn

@ref{12c,,xml.parsers.expat} 模組包含兩個函式：

@geindex ErrorString() (於 xml.parsers.expat 模組中)
@anchor{library/pyexpat xml parsers expat ErrorString}@anchor{3d17}
@deffn {函式} xml.parsers.expat.ErrorString (errno)

回傳一個給定錯誤編號 `errno' 的解釋字串。
@end deffn

@geindex ParserCreate() (於 xml.parsers.expat 模組中)
@anchor{library/pyexpat xml parsers expat ParserCreate}@anchor{3d16}
@deffn {函式} xml.parsers.expat.ParserCreate (encoding=None, namespace_separator=None)

Creates and returns a new @code{xmlparser} object.   `encoding', if specified,
must be a string naming the encoding  used by the XML data.  Expat doesn't
support as many encodings as Python does, and its repertoire of encodings can't
be extended; it supports UTF-8, UTF-16, ISO-8859-1 (Latin1), and ASCII.  If
`encoding' @footnote{
The encoding string included in XML output should conform to the
appropriate standards. For example, "UTF-8" is valid, but "UTF8" is
not. See @indicateurl{https://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl}
and @indicateurl{https://www.iana.org/assignments/character-sets/character-sets.xhtml}.
} is given it will override the implicit or explicit encoding of the
document.

Expat can optionally do XML namespace processing for you, enabled by providing a
value for `namespace_separator'.  The value must be a one-character string; a
@ref{2eb,,ValueError} will be raised if the string has an illegal length (@code{None}
is considered the same as omission).  When namespace processing is enabled,
element type names and attribute names that belong to a namespace will be
expanded.  The element name passed to the element handlers
@code{StartElementHandler} and @code{EndElementHandler} will be the
concatenation of the namespace URI, the namespace separator character, and the
local part of the name.  If the namespace separator is a zero byte (@code{chr(0)})
then the namespace URI and the local part will be concatenated without any
separator.

For example, if `namespace_separator' is set to a space character (@code{' '}) and
the following document is parsed:

@example
<?xml version="1.0"?>
<root xmlns    = "http://default-namespace.org/"
      xmlns:py = "http://www.python.org/ns/">
  <py:elem1 />
  <elem2 xmlns="" />
</root>
@end example

@code{StartElementHandler} 將會收到每個元素的以下字串：

@example
http://default-namespace.org/ root
http://www.python.org/ns/ elem1
elem2
@end example

Due to limitations in the @code{Expat} library used by @code{pyexpat},
the @code{xmlparser} instance returned can only be used to parse a single
XML document.  Call @code{ParserCreate} for each document to provide unique
parser instances.
@end deffn


@subsubheading 也參考



@table @asis

@item Expat XML 剖析器@footnote{http://www.libexpat.org/}

Expat 專案的首頁。
@end table


@menu
* XMLParser 物件: XMLParser 物件<2>. 
* ExpatError 例外:: 
* 範例: 範例<34>. 
* Content Model Descriptions:: 
* Expat 錯誤常數:: 

@end menu

@node XMLParser 物件<2>,ExpatError 例外,,xml parsers expat --- 使用 Expat 進行快速 XML 剖析
@anchor{library/pyexpat id2}@anchor{3d18}@anchor{library/pyexpat xmlparser-objects}@anchor{3d19}
@subsubsection XMLParser 物件


@code{xmlparser} 物件擁有以下方法：

@geindex Parse() (xml.parsers.expat.xmlparser 的方法)
@anchor{library/pyexpat xml parsers expat xmlparser Parse}@anchor{3d1a}
@deffn {方法} xmlparser.Parse (data[, isfinal])

Parses the contents of the string `data', calling the appropriate handler
functions to process the parsed data.  `isfinal' must be true on the final call
to this method; it allows the parsing of a single file in fragments,
not the submission of multiple files.
`data' can be the empty string at any time.
@end deffn

@geindex ParseFile() (xml.parsers.expat.xmlparser 的方法)
@anchor{library/pyexpat xml parsers expat xmlparser ParseFile}@anchor{3d1b}
@deffn {方法} xmlparser.ParseFile (file)

Parse XML data reading from the object `file'.  `file' only needs to provide
the @code{read(nbytes)} method, returning the empty string when there's no more
data.
@end deffn

@geindex SetBase() (xml.parsers.expat.xmlparser 的方法)
@anchor{library/pyexpat xml parsers expat xmlparser SetBase}@anchor{3d1c}
@deffn {方法} xmlparser.SetBase (base)

Sets the base to be used for resolving relative URIs in system identifiers in
declarations.  Resolving relative identifiers is left to the application: this
value will be passed through as the `base' argument to the
@ref{3d1d,,ExternalEntityRefHandler()}, @ref{3d1e,,NotationDeclHandler()}, and
@ref{3d1f,,UnparsedEntityDeclHandler()} functions.
@end deffn

@geindex GetBase() (xml.parsers.expat.xmlparser 的方法)
@anchor{library/pyexpat xml parsers expat xmlparser GetBase}@anchor{3d20}
@deffn {方法} xmlparser.GetBase ()

Returns a string containing the base set by a previous call to @ref{3d1c,,SetBase()},
or @code{None} if  @ref{3d1c,,SetBase()} hasn't been called.
@end deffn

@geindex GetInputContext() (xml.parsers.expat.xmlparser 的方法)
@anchor{library/pyexpat xml parsers expat xmlparser GetInputContext}@anchor{3d21}
@deffn {方法} xmlparser.GetInputContext ()

Returns the input data that generated the current event as a string. The data is
in the encoding of the entity which contains the text. When called while an
event handler is not active, the return value is @code{None}.
@end deffn

@geindex ExternalEntityParserCreate() (xml.parsers.expat.xmlparser 的方法)
@anchor{library/pyexpat xml parsers expat xmlparser ExternalEntityParserCreate}@anchor{1774}
@deffn {方法} xmlparser.ExternalEntityParserCreate (context[, encoding])

Create a "child" parser which can be used to parse an external parsed entity
referred to by content parsed by the parent parser.  The `context' parameter
should be the string passed to the @ref{3d1d,,ExternalEntityRefHandler()} handler
function, described below. The child parser is created with the
@ref{3d22,,ordered_attributes} and @ref{3d23,,specified_attributes} set to the values of
this parser.
@end deffn

@geindex SetParamEntityParsing() (xml.parsers.expat.xmlparser 的方法)
@anchor{library/pyexpat xml parsers expat xmlparser SetParamEntityParsing}@anchor{3d24}
@deffn {方法} xmlparser.SetParamEntityParsing (flag)

Control parsing of parameter entities (including the external DTD subset).
Possible `flag' values are @code{XML_PARAM_ENTITY_PARSING_NEVER},
@code{XML_PARAM_ENTITY_PARSING_UNLESS_STANDALONE} and
@code{XML_PARAM_ENTITY_PARSING_ALWAYS}.  Return true if setting the flag
was successful.
@end deffn

@geindex UseForeignDTD() (xml.parsers.expat.xmlparser 的方法)
@anchor{library/pyexpat xml parsers expat xmlparser UseForeignDTD}@anchor{3d25}
@deffn {方法} xmlparser.UseForeignDTD ([flag])

Calling this with a true value for `flag' (the default) will cause Expat to call
the @ref{3d1d,,ExternalEntityRefHandler} with @ref{87e,,None} for all arguments to
allow an alternate DTD to be loaded.  If the document does not contain a
document type declaration, the @ref{3d1d,,ExternalEntityRefHandler} will still be
called, but the @ref{3d26,,StartDoctypeDeclHandler} and
@ref{3d27,,EndDoctypeDeclHandler} will not be called.

Passing a false value for `flag' will cancel a previous call that passed a true
value, but otherwise has no effect.

This method can only be called before the @ref{3d1a,,Parse()} or @ref{3d1b,,ParseFile()}
methods are called; calling it after either of those have been called causes
@ref{1479,,ExpatError} to be raised with the @ref{1b,,code} attribute set to
@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{573}
@deffn {方法} xmlparser.SetReparseDeferralEnabled (enabled)

@cartouche
@quotation 警告 
Calling @code{SetReparseDeferralEnabled(False)} has security implications,
as detailed below; please make sure to understand these consequences
prior to using the @code{SetReparseDeferralEnabled} method.
@end quotation
@end cartouche

Expat 2.6.0 introduced a security mechanism called "reparse deferral"
where instead of causing denial of service through quadratic runtime
from reparsing large tokens, reparsing of unfinished tokens is now delayed
by default until a sufficient amount of input is reached.
Due to this delay, registered handlers may — depending of the sizing of
input chunks pushed to Expat — no longer be called right after pushing new
input to the parser.  Where immediate feedback and taking over responsibility
of protecting against denial of service from large tokens are both wanted,
calling @code{SetReparseDeferralEnabled(False)} disables reparse deferral
for the current Expat parser instance, temporarily or altogether.
Calling @code{SetReparseDeferralEnabled(True)} allows re-enabling reparse
deferral.

Note that @ref{573,,SetReparseDeferralEnabled()} has been backported to some
prior releases of CPython as a security fix.  Check for availability of
@ref{573,,SetReparseDeferralEnabled()} using @ref{6f2,,hasattr()} if used in code
running across a variety of Python versions.


在 3.13 版被加入.

@end deffn

@geindex GetReparseDeferralEnabled() (xml.parsers.expat.xmlparser 的方法)
@anchor{library/pyexpat xml parsers expat xmlparser GetReparseDeferralEnabled}@anchor{572}
@deffn {方法} xmlparser.GetReparseDeferralEnabled ()

Returns whether reparse deferral is currently enabled for the given
Expat parser instance.


在 3.13 版被加入.

@end deffn

@code{xmlparser} 物件擁有以下屬性：

@geindex buffer_size (xml.parsers.expat.xmlparser 的屬性)
@anchor{library/pyexpat xml parsers expat xmlparser buffer_size}@anchor{3d28}
@deffn {屬性} xmlparser.buffer_size

The size of the buffer used when @ref{16b6,,buffer_text} is true.
A new buffer size can be set by assigning a new integer value
to this attribute.
When the size is changed, the buffer will be flushed.
@end deffn

@geindex buffer_text (xml.parsers.expat.xmlparser 的屬性)
@anchor{library/pyexpat xml parsers expat xmlparser buffer_text}@anchor{16b6}
@deffn {屬性} xmlparser.buffer_text

Setting this to true causes the @code{xmlparser} object to buffer textual
content returned by Expat to avoid multiple calls to the
@ref{3d29,,CharacterDataHandler()} callback whenever possible.  This can improve
performance substantially since Expat normally breaks character data into chunks
at every line ending.  This attribute is false by default, and may be changed at
any time. Note that when it is false, data that does not contain newlines
may be chunked too.
@end deffn

@geindex buffer_used (xml.parsers.expat.xmlparser 的屬性)
@anchor{library/pyexpat xml parsers expat xmlparser buffer_used}@anchor{3d2a}
@deffn {屬性} xmlparser.buffer_used

If @ref{16b6,,buffer_text} is enabled, the number of bytes stored in the buffer.
These bytes represent UTF-8 encoded text.  This attribute has no meaningful
interpretation when @ref{16b6,,buffer_text} is false.
@end deffn

@geindex ordered_attributes (xml.parsers.expat.xmlparser 的屬性)
@anchor{library/pyexpat xml parsers expat xmlparser ordered_attributes}@anchor{3d22}
@deffn {屬性} xmlparser.ordered_attributes

Setting this attribute to a non-zero integer causes the attributes to be
reported as a list rather than a dictionary.  The attributes are presented in
the order found in the document text.  For each attribute, two list entries are
presented: the attribute name and the attribute value.  (Older versions of this
module also used this format.)  By default, this attribute is false; it may be
changed at any time.
@end deffn

@geindex specified_attributes (xml.parsers.expat.xmlparser 的屬性)
@anchor{library/pyexpat xml parsers expat xmlparser specified_attributes}@anchor{3d23}
@deffn {屬性} xmlparser.specified_attributes

If set to a non-zero integer, the parser will report only those attributes which
were specified in the document instance and not those which were derived from
attribute declarations.  Applications which set this need to be especially
careful to use what additional information is available from the declarations as
needed to comply with the standards for the behavior of XML processors.  By
default, this attribute is false; it may be changed at any time.
@end deffn

The following attributes contain values relating to the most recent error
encountered by an @code{xmlparser} object, and will only have correct values
once a call to @code{Parse()} or @code{ParseFile()} has raised an
@ref{1479,,xml.parsers.expat.ExpatError} exception.

@geindex ErrorByteIndex (xml.parsers.expat.xmlparser 的屬性)
@anchor{library/pyexpat xml parsers expat xmlparser ErrorByteIndex}@anchor{3d2b}
@deffn {屬性} xmlparser.ErrorByteIndex

Byte index at which an error occurred.
@end deffn

@geindex ErrorCode (xml.parsers.expat.xmlparser 的屬性)
@anchor{library/pyexpat xml parsers expat xmlparser ErrorCode}@anchor{3d2c}
@deffn {屬性} xmlparser.ErrorCode

Numeric code specifying the problem.  This value can be passed to the
@ref{3d17,,ErrorString()} function, or compared to one of the constants defined in the
@code{errors} object.
@end deffn

@geindex ErrorColumnNumber (xml.parsers.expat.xmlparser 的屬性)
@anchor{library/pyexpat xml parsers expat xmlparser ErrorColumnNumber}@anchor{3d2d}
@deffn {屬性} xmlparser.ErrorColumnNumber

Column number at which an error occurred.
@end deffn

@geindex ErrorLineNumber (xml.parsers.expat.xmlparser 的屬性)
@anchor{library/pyexpat xml parsers expat xmlparser ErrorLineNumber}@anchor{3d2e}
@deffn {屬性} xmlparser.ErrorLineNumber

Line number at which an error occurred.
@end deffn

The following attributes contain values relating to the current parse location
in an @code{xmlparser} object.  During a callback reporting a parse event they
indicate the location of the first of the sequence of characters that generated
the event.  When called outside of a callback, the position indicated will be
just past the last parse event (regardless of whether there was an associated
callback).

@geindex CurrentByteIndex (xml.parsers.expat.xmlparser 的屬性)
@anchor{library/pyexpat xml parsers expat xmlparser CurrentByteIndex}@anchor{3d2f}
@deffn {屬性} xmlparser.CurrentByteIndex

Current byte index in the parser input.
@end deffn

@geindex CurrentColumnNumber (xml.parsers.expat.xmlparser 的屬性)
@anchor{library/pyexpat xml parsers expat xmlparser CurrentColumnNumber}@anchor{3d30}
@deffn {屬性} xmlparser.CurrentColumnNumber

Current column number in the parser input.
@end deffn

@geindex CurrentLineNumber (xml.parsers.expat.xmlparser 的屬性)
@anchor{library/pyexpat xml parsers expat xmlparser CurrentLineNumber}@anchor{3d31}
@deffn {屬性} xmlparser.CurrentLineNumber

Current line number in the parser input.
@end deffn

Here is the list of handlers that can be set.  To set a handler on an
@code{xmlparser} object `o', use @code{o.handlername = func}.  `handlername' must
be taken from the following list, and `func' must be a callable object accepting
the correct number of arguments.  The arguments are all strings, unless
otherwise stated.

@geindex XmlDeclHandler() (xml.parsers.expat.xmlparser 的方法)
@anchor{library/pyexpat xml parsers expat xmlparser XmlDeclHandler}@anchor{3d32}
@deffn {方法} xmlparser.XmlDeclHandler (version, encoding, standalone)

Called when the XML declaration is parsed.  The XML declaration is the
(optional) declaration of the applicable version of the XML recommendation, the
encoding of the document text, and an optional "standalone" declaration.
`version' and `encoding' will be strings, and `standalone' will be @code{1} if the
document is declared standalone, @code{0} if it is declared not to be standalone,
or @code{-1} if the standalone clause was omitted. This is only available with
Expat version 1.95.0 or newer.
@end deffn

@geindex StartDoctypeDeclHandler() (xml.parsers.expat.xmlparser 的方法)
@anchor{library/pyexpat xml parsers expat xmlparser StartDoctypeDeclHandler}@anchor{3d26}
@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 and 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{3d27}
@deffn {方法} xmlparser.EndDoctypeDeclHandler ()

Called when Expat is done parsing the document type declaration. This requires
Expat version 1.2 or newer.
@end deffn

@geindex ElementDeclHandler() (xml.parsers.expat.xmlparser 的方法)
@anchor{library/pyexpat xml parsers expat xmlparser ElementDeclHandler}@anchor{174c}
@deffn {方法} xmlparser.ElementDeclHandler (name, model)

Called once for each element type declaration.  `name' is the name of the
element type, and `model' is a representation of the content model.
@end deffn

@geindex AttlistDeclHandler() (xml.parsers.expat.xmlparser 的方法)
@anchor{library/pyexpat xml parsers expat xmlparser AttlistDeclHandler}@anchor{3d33}
@deffn {方法} xmlparser.AttlistDeclHandler (elname, attname, type, default, required)

Called for each declared attribute for an element type.  If an attribute list
declaration declares three attributes, this handler is called three times, once
for each attribute.  `elname' is the name of the element to which the
declaration applies and `attname' is the name of the attribute declared.  The
attribute type is a string passed as `type'; the possible values are
@code{'CDATA'}, @code{'ID'}, @code{'IDREF'}, ... `default' gives the default value for
the attribute used when the attribute is not specified by the document instance,
or @code{None} if there is no default value (@code{#IMPLIED} values).  If the
attribute is required to be given in the document instance, `required' will be
true. This requires Expat version 1.95.0 or newer.
@end deffn

@geindex StartElementHandler() (xml.parsers.expat.xmlparser 的方法)
@anchor{library/pyexpat xml parsers expat xmlparser StartElementHandler}@anchor{3d34}
@deffn {方法} xmlparser.StartElementHandler (name, attributes)

Called for the start of every element.  `name' is a string containing the
element name, and `attributes' is the element attributes. If
@ref{3d22,,ordered_attributes} is true, this is a list (see
@ref{3d22,,ordered_attributes} for a full description). Otherwise it's a
dictionary mapping names to values.
@end deffn

@geindex EndElementHandler() (xml.parsers.expat.xmlparser 的方法)
@anchor{library/pyexpat xml parsers expat xmlparser EndElementHandler}@anchor{3d35}
@deffn {方法} xmlparser.EndElementHandler (name)

Called for the end of every element.
@end deffn

@geindex ProcessingInstructionHandler() (xml.parsers.expat.xmlparser 的方法)
@anchor{library/pyexpat xml parsers expat xmlparser ProcessingInstructionHandler}@anchor{3d36}
@deffn {方法} xmlparser.ProcessingInstructionHandler (target, data)

Called for every processing instruction.
@end deffn

@geindex CharacterDataHandler() (xml.parsers.expat.xmlparser 的方法)
@anchor{library/pyexpat xml parsers expat xmlparser CharacterDataHandler}@anchor{3d29}
@deffn {方法} xmlparser.CharacterDataHandler (data)

Called for character data.  This will be called for normal character data, CDATA
marked content, and ignorable whitespace.  Applications which must distinguish
these cases can use the @ref{3d37,,StartCdataSectionHandler},
@ref{3d38,,EndCdataSectionHandler}, and @ref{174c,,ElementDeclHandler} callbacks to
collect the required information. Note that the character data may be
chunked even if it is short and so you may receive more than one call to
@ref{3d29,,CharacterDataHandler()}. Set the @ref{16b6,,buffer_text} instance attribute
to @code{True} to avoid that.
@end deffn

@geindex UnparsedEntityDeclHandler() (xml.parsers.expat.xmlparser 的方法)
@anchor{library/pyexpat xml parsers expat xmlparser UnparsedEntityDeclHandler}@anchor{3d1f}
@deffn {方法} xmlparser.UnparsedEntityDeclHandler (entityName, base, systemId, publicId, notationName)

Called for unparsed (NDATA) entity declarations.  This is only present for
version 1.2 of the Expat library; for more recent versions, use
@ref{3d39,,EntityDeclHandler} instead.  (The underlying function in the Expat
library has been declared obsolete.)
@end deffn

@geindex EntityDeclHandler() (xml.parsers.expat.xmlparser 的方法)
@anchor{library/pyexpat xml parsers expat xmlparser EntityDeclHandler}@anchor{3d39}
@deffn {方法} xmlparser.EntityDeclHandler (entityName, is_parameter_entity, value, base, systemId, publicId, notationName)

Called for all entity declarations.  For parameter and internal entities,
`value' will be a string giving the declared contents of the entity; this will
be @code{None} for external entities.  The `notationName' parameter will be
@code{None} for parsed entities, and the name of the notation for unparsed
entities. `is_parameter_entity' will be true if the entity is a parameter entity
or false for general entities (most applications only need to be concerned with
general entities). This is only available starting with version 1.95.0 of the
Expat library.
@end deffn

@geindex NotationDeclHandler() (xml.parsers.expat.xmlparser 的方法)
@anchor{library/pyexpat xml parsers expat xmlparser NotationDeclHandler}@anchor{3d1e}
@deffn {方法} xmlparser.NotationDeclHandler (notationName, base, systemId, publicId)

Called for notation declarations.  `notationName', `base', and `systemId', and
`publicId' are strings if given.  If the public identifier is omitted,
`publicId' will be @code{None}.
@end deffn

@geindex StartNamespaceDeclHandler() (xml.parsers.expat.xmlparser 的方法)
@anchor{library/pyexpat xml parsers expat xmlparser StartNamespaceDeclHandler}@anchor{3d3a}
@deffn {方法} xmlparser.StartNamespaceDeclHandler (prefix, uri)

Called when an element contains a namespace declaration.  Namespace declarations
are processed before the @ref{3d34,,StartElementHandler} is called for the element
on which declarations are placed.
@end deffn

@geindex EndNamespaceDeclHandler() (xml.parsers.expat.xmlparser 的方法)
@anchor{library/pyexpat xml parsers expat xmlparser EndNamespaceDeclHandler}@anchor{3d3b}
@deffn {方法} xmlparser.EndNamespaceDeclHandler (prefix)

Called when the closing tag is reached for an element  that contained a
namespace declaration.  This is called once for each namespace declaration on
the element in the reverse of the order for which the
@ref{3d3a,,StartNamespaceDeclHandler} was called to indicate the start of each
namespace declaration's scope.  Calls to this handler are made after the
corresponding @ref{3d35,,EndElementHandler} for the end of the element.
@end deffn

@geindex CommentHandler() (xml.parsers.expat.xmlparser 的方法)
@anchor{library/pyexpat xml parsers expat xmlparser CommentHandler}@anchor{3d3c}
@deffn {方法} xmlparser.CommentHandler (data)

Called for comments.  `data' is the text of the comment, excluding the leading
@code{'<!-}@code{-'} and trailing @code{'-}@code{->'}.
@end deffn

@geindex StartCdataSectionHandler() (xml.parsers.expat.xmlparser 的方法)
@anchor{library/pyexpat xml parsers expat xmlparser StartCdataSectionHandler}@anchor{3d37}
@deffn {方法} xmlparser.StartCdataSectionHandler ()

Called at the start of a CDATA section.  This and @ref{3d38,,EndCdataSectionHandler}
are needed to be able to identify the syntactical start and end for CDATA
sections.
@end deffn

@geindex EndCdataSectionHandler() (xml.parsers.expat.xmlparser 的方法)
@anchor{library/pyexpat xml parsers expat xmlparser EndCdataSectionHandler}@anchor{3d38}
@deffn {方法} xmlparser.EndCdataSectionHandler ()

在 CDATA 區塊結束時呼叫。
@end deffn

@geindex DefaultHandler() (xml.parsers.expat.xmlparser 的方法)
@anchor{library/pyexpat xml parsers expat xmlparser DefaultHandler}@anchor{3d3d}
@deffn {方法} xmlparser.DefaultHandler (data)

Called for any characters in the XML document for which no applicable handler
has been specified.  This means characters that are part of a construct which
could be reported, but for which no handler has been supplied.
@end deffn

@geindex DefaultHandlerExpand() (xml.parsers.expat.xmlparser 的方法)
@anchor{library/pyexpat xml parsers expat xmlparser DefaultHandlerExpand}@anchor{3d3e}
@deffn {方法} xmlparser.DefaultHandlerExpand (data)

This is the same as the @ref{3d3d,,DefaultHandler()},  but doesn't inhibit expansion
of internal entities. The entity reference will not be passed to the default
handler.
@end deffn

@geindex NotStandaloneHandler() (xml.parsers.expat.xmlparser 的方法)
@anchor{library/pyexpat xml parsers expat xmlparser NotStandaloneHandler}@anchor{3d3f}
@deffn {方法} xmlparser.NotStandaloneHandler ()

Called if the XML document hasn't been declared as being a standalone document.
This happens when there is an external subset or a reference to a parameter
entity, but the XML declaration does not set standalone to @code{yes} in an XML
declaration.  If this handler returns @code{0}, then the parser will raise an
@code{XML_ERROR_NOT_STANDALONE} error.  If this handler is not set, no
exception is raised by the parser for this condition.
@end deffn

@geindex ExternalEntityRefHandler() (xml.parsers.expat.xmlparser 的方法)
@anchor{library/pyexpat xml parsers expat xmlparser ExternalEntityRefHandler}@anchor{3d1d}
@deffn {方法} xmlparser.ExternalEntityRefHandler (context, base, systemId, publicId)

Called for references to external entities.  `base' is the current base, as set
by a previous call to @ref{3d1c,,SetBase()}.  The public and system identifiers,
`systemId' and `publicId', are strings if given; if the public identifier is not
given, `publicId' will be @code{None}.  The `context' value is opaque and should
only be used as described below.

For external entities to be parsed, this handler must be implemented. It is
responsible for creating the sub-parser using
@code{ExternalEntityParserCreate(context)}, initializing it with the appropriate
callbacks, and parsing the entity.  This handler should return an integer; if it
returns @code{0}, the parser will raise an
@code{XML_ERROR_EXTERNAL_ENTITY_HANDLING} error, otherwise parsing will
continue.

If this handler is not provided, external entities are reported by the
@ref{3d3d,,DefaultHandler} callback, if provided.
@end deffn

@node ExpatError 例外,範例<34>,XMLParser 物件<2>,xml parsers expat --- 使用 Expat 進行快速 XML 剖析
@anchor{library/pyexpat expaterror-exceptions}@anchor{3d40}@anchor{library/pyexpat expaterror-objects}@anchor{3d13}
@subsubsection ExpatError 例外


@ref{1479,,ExpatError} exceptions have a number of interesting attributes:

@geindex code (xml.parsers.expat.ExpatError 的屬性)
@anchor{library/pyexpat xml parsers expat ExpatError code}@anchor{3d41}
@deffn {屬性} ExpatError.code

Expat's internal error number for the specific error.  The
@ref{3d42,,errors.messages} dictionary maps
these error numbers to Expat's error messages.  For example:

@example
from xml.parsers.expat import ParserCreate, ExpatError, errors

p = ParserCreate()
try:
    p.Parse(some_xml_document)
except ExpatError as err:
    print("Error:", errors.messages[err.code])
@end example

The @ref{12d,,errors} module also provides error message
constants and a dictionary @ref{3d43,,codes} mapping
these messages back to the error codes, see below.
@end deffn

@geindex lineno (xml.parsers.expat.ExpatError 的屬性)
@anchor{library/pyexpat xml parsers expat ExpatError lineno}@anchor{3d44}
@deffn {屬性} ExpatError.lineno

Line number on which the error was detected.  The first line is numbered @code{1}.
@end deffn

@geindex offset (xml.parsers.expat.ExpatError 的屬性)
@anchor{library/pyexpat xml parsers expat ExpatError offset}@anchor{3d45}
@deffn {屬性} ExpatError.offset

Character offset into the line where the error occurred.  The first column is
numbered @code{0}.
@end deffn

@node 範例<34>,Content Model Descriptions,ExpatError 例外,xml parsers expat --- 使用 Expat 進行快速 XML 剖析
@anchor{library/pyexpat example}@anchor{3d46}@anchor{library/pyexpat expat-example}@anchor{3d47}
@subsubsection 範例


The following program defines three handlers that just print out their
arguments.

@example
import xml.parsers.expat

# 3 handler functions
def start_element(name, attrs):
    print('Start element:', name, attrs)
def end_element(name):
    print('End element:', name)
def char_data(data):
    print('Character data:', repr(data))

p = xml.parsers.expat.ParserCreate()

p.StartElementHandler = start_element
p.EndElementHandler = end_element
p.CharacterDataHandler = char_data

p.Parse("""<?xml version="1.0"?>
<parent id="top"><child1 name="paul">Text goes here</child1>
<child2 name="fred">More text</child2>
</parent>""", 1)
@end example

這個程式的輸出是：

@example
Start element: parent @{'id': 'top'@}
Start element: child1 @{'name': 'paul'@}
Character data: 'Text goes here'
End element: child1
Character data: '\n'
Start element: child2 @{'name': 'fred'@}
Character data: 'More text'
End element: child2
Character data: '\n'
End element: parent
@end example

@node Content Model Descriptions,Expat 錯誤常數,範例<34>,xml parsers expat --- 使用 Expat 進行快速 XML 剖析
@anchor{library/pyexpat content-model-descriptions}@anchor{3d48}@anchor{library/pyexpat expat-content-models}@anchor{3d49}@anchor{library/pyexpat module-xml parsers expat model}@anchor{12e}
@subsubsection Content Model Descriptions


@geindex module; xml.parsers.expat.model

Content models are described using nested tuples.  Each tuple contains four
values: the type, the quantifier, the name, and a tuple of children.  Children
are simply additional content model descriptions.

The values of the first two fields are constants defined in the
@ref{12e,,xml.parsers.expat.model} module.  These constants can be collected in two
groups: the model type group and the quantifier group.

The constants in the model type group are:


@deffn {資料} xml.parsers.expat.model.XML_CTYPE_ANY

The element named by the model name was declared to have a content model of
@code{ANY}.
@end deffn


@deffn {資料} xml.parsers.expat.model.XML_CTYPE_CHOICE

The named element allows a choice from a number of options; this is used for
content models such as @code{(A | B | C)}.
@end deffn


@deffn {資料} xml.parsers.expat.model.XML_CTYPE_EMPTY

Elements which are declared to be @code{EMPTY} have this model type.
@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

Models which represent a series of models which follow one after the other are
indicated with this model type.  This is used for models such as @code{(A, B, C)}.
@end deffn

The constants in the quantifier group are:


@deffn {資料} xml.parsers.expat.model.XML_CQUANT_NONE

No modifier is given, so it can appear exactly once, as for @code{A}.
@end deffn


@deffn {資料} xml.parsers.expat.model.XML_CQUANT_OPT

The model is optional: it can appear once or not at all, as for @code{A?}.
@end deffn


@deffn {資料} xml.parsers.expat.model.XML_CQUANT_PLUS

The model must occur one or more times (like @code{A+}).
@end deffn


@deffn {資料} xml.parsers.expat.model.XML_CQUANT_REP

The model must occur zero or more times, as for @code{A*}.
@end deffn

@node Expat 錯誤常數,,Content Model Descriptions,xml parsers expat --- 使用 Expat 進行快速 XML 剖析
@anchor{library/pyexpat expat-error-constants}@anchor{3d4a}@anchor{library/pyexpat expat-errors}@anchor{3d4b}@anchor{library/pyexpat module-xml parsers expat errors}@anchor{12d}
@subsubsection Expat 錯誤常數


@geindex module; xml.parsers.expat.errors

The following constants are provided in the @ref{12d,,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}]}.

@code{errors} 模組有以下屬性：

@geindex codes (於 xml.parsers.expat.errors 模組中)
@anchor{library/pyexpat xml parsers expat errors codes}@anchor{3d43}
@deffn {資料} xml.parsers.expat.errors.codes

A dictionary mapping string descriptions to their error codes.


在 3.2 版被加入.

@end deffn

@geindex messages (於 xml.parsers.expat.errors 模組中)
@anchor{library/pyexpat xml parsers expat errors messages}@anchor{3d42}
@deffn {資料} xml.parsers.expat.errors.messages

A dictionary mapping numeric error codes to their string descriptions.


在 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{3d4c}
@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{3d4d}
@deffn {資料} xml.parsers.expat.errors.XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF

An entity reference in an attribute value referred to an external entity instead
of an internal entity.
@end deffn

@geindex XML_ERROR_BAD_CHAR_REF (於 xml.parsers.expat.errors 模組中)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_BAD_CHAR_REF}@anchor{3d4e}
@deffn {資料} xml.parsers.expat.errors.XML_ERROR_BAD_CHAR_REF

A character reference referred to a character which is illegal in XML (for
example, character @code{0}, or '@code{&#0;}').
@end deffn

@geindex XML_ERROR_BINARY_ENTITY_REF (於 xml.parsers.expat.errors 模組中)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_BINARY_ENTITY_REF}@anchor{3d4f}
@deffn {資料} xml.parsers.expat.errors.XML_ERROR_BINARY_ENTITY_REF

An entity reference referred to an entity which was declared with a notation, so
cannot be parsed.
@end deffn

@geindex XML_ERROR_DUPLICATE_ATTRIBUTE (於 xml.parsers.expat.errors 模組中)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_DUPLICATE_ATTRIBUTE}@anchor{3d50}
@deffn {資料} xml.parsers.expat.errors.XML_ERROR_DUPLICATE_ATTRIBUTE

An attribute was used more than once in a start tag.
@end deffn

@geindex XML_ERROR_INCORRECT_ENCODING (於 xml.parsers.expat.errors 模組中)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_INCORRECT_ENCODING}@anchor{3d51}
@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{3d52}
@deffn {資料} xml.parsers.expat.errors.XML_ERROR_INVALID_TOKEN

Raised when an input byte could not properly be assigned to a character; for
example, a NUL byte (value @code{0}) in a UTF-8 input stream.
@end deffn

@geindex XML_ERROR_JUNK_AFTER_DOC_ELEMENT (於 xml.parsers.expat.errors 模組中)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_JUNK_AFTER_DOC_ELEMENT}@anchor{3d53}
@deffn {資料} xml.parsers.expat.errors.XML_ERROR_JUNK_AFTER_DOC_ELEMENT

Something other than whitespace occurred after the document element.
@end deffn

@geindex XML_ERROR_MISPLACED_XML_PI (於 xml.parsers.expat.errors 模組中)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_MISPLACED_XML_PI}@anchor{3d54}
@deffn {資料} xml.parsers.expat.errors.XML_ERROR_MISPLACED_XML_PI

An XML declaration was found somewhere other than the start of the input data.
@end deffn

@geindex XML_ERROR_NO_ELEMENTS (於 xml.parsers.expat.errors 模組中)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_NO_ELEMENTS}@anchor{3d55}
@deffn {資料} xml.parsers.expat.errors.XML_ERROR_NO_ELEMENTS

The document contains no elements (XML requires all documents to contain exactly
one top-level element)..
@end deffn

@geindex XML_ERROR_NO_MEMORY (於 xml.parsers.expat.errors 模組中)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_NO_MEMORY}@anchor{3d56}
@deffn {資料} xml.parsers.expat.errors.XML_ERROR_NO_MEMORY

Expat was not able to allocate memory internally.
@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{3d57}
@deffn {資料} xml.parsers.expat.errors.XML_ERROR_PARAM_ENTITY_REF

A parameter entity reference was found where it was not allowed.
@end deffn

@geindex XML_ERROR_PARTIAL_CHAR (於 xml.parsers.expat.errors 模組中)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_PARTIAL_CHAR}@anchor{3d58}
@deffn {資料} xml.parsers.expat.errors.XML_ERROR_PARTIAL_CHAR

An incomplete character was found in the input.
@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{3d59}
@deffn {資料} xml.parsers.expat.errors.XML_ERROR_RECURSIVE_ENTITY_REF

An entity reference contained another reference to the same entity; possibly via
a different name, and possibly indirectly.
@end deffn

@geindex XML_ERROR_SYNTAX (於 xml.parsers.expat.errors 模組中)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_SYNTAX}@anchor{3d5a}
@deffn {資料} xml.parsers.expat.errors.XML_ERROR_SYNTAX

Some unspecified syntax error was encountered.
@end deffn

@geindex XML_ERROR_TAG_MISMATCH (於 xml.parsers.expat.errors 模組中)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_TAG_MISMATCH}@anchor{3d5b}
@deffn {資料} xml.parsers.expat.errors.XML_ERROR_TAG_MISMATCH

An end tag did not match the innermost open start tag.
@end deffn

@geindex XML_ERROR_UNCLOSED_TOKEN (於 xml.parsers.expat.errors 模組中)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_UNCLOSED_TOKEN}@anchor{3d5c}
@deffn {資料} xml.parsers.expat.errors.XML_ERROR_UNCLOSED_TOKEN

Some token (such as a start tag) was not closed before the end of the stream or
the next token was encountered.
@end deffn

@geindex XML_ERROR_UNDEFINED_ENTITY (於 xml.parsers.expat.errors 模組中)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_UNDEFINED_ENTITY}@anchor{3d5d}
@deffn {資料} xml.parsers.expat.errors.XML_ERROR_UNDEFINED_ENTITY

A reference was made to an entity which was not defined.
@end deffn

@geindex XML_ERROR_UNKNOWN_ENCODING (於 xml.parsers.expat.errors 模組中)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_UNKNOWN_ENCODING}@anchor{3d5e}
@deffn {資料} xml.parsers.expat.errors.XML_ERROR_UNKNOWN_ENCODING

The document encoding is not supported by 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{3d5f}
@deffn {資料} xml.parsers.expat.errors.XML_ERROR_UNCLOSED_CDATA_SECTION

A CDATA marked section was not closed.
@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{3d60}
@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{3d61}
@deffn {資料} xml.parsers.expat.errors.XML_ERROR_NOT_STANDALONE

The parser determined that the document was not "standalone" though it declared
itself to be in the XML declaration, and the @code{NotStandaloneHandler} was
set and returned @code{0}.
@end deffn

@geindex XML_ERROR_UNEXPECTED_STATE (於 xml.parsers.expat.errors 模組中)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_UNEXPECTED_STATE}@anchor{3d62}
@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{3d63}
@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{3d64}
@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 @ref{12c,,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{3d65}
@deffn {資料} xml.parsers.expat.errors.XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING

A behavioral change was requested after parsing started that can only be changed
before parsing has started.  This is (currently) only raised by
@code{UseForeignDTD()}.
@end deffn

@geindex XML_ERROR_UNBOUND_PREFIX (於 xml.parsers.expat.errors 模組中)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_UNBOUND_PREFIX}@anchor{3d66}
@deffn {資料} xml.parsers.expat.errors.XML_ERROR_UNBOUND_PREFIX

An undeclared prefix was found when namespace processing was enabled.
@end deffn

@geindex XML_ERROR_UNDECLARING_PREFIX (於 xml.parsers.expat.errors 模組中)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_UNDECLARING_PREFIX}@anchor{3d67}
@deffn {資料} xml.parsers.expat.errors.XML_ERROR_UNDECLARING_PREFIX

The document attempted to remove the namespace declaration associated with a
prefix.
@end deffn

@geindex XML_ERROR_INCOMPLETE_PE (於 xml.parsers.expat.errors 模組中)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_INCOMPLETE_PE}@anchor{3d68}
@deffn {資料} xml.parsers.expat.errors.XML_ERROR_INCOMPLETE_PE

A parameter entity contained incomplete markup.
@end deffn

@geindex XML_ERROR_XML_DECL (於 xml.parsers.expat.errors 模組中)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_XML_DECL}@anchor{3d69}
@deffn {資料} xml.parsers.expat.errors.XML_ERROR_XML_DECL

The document contained no document element at all.
@end deffn

@geindex XML_ERROR_TEXT_DECL (於 xml.parsers.expat.errors 模組中)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_TEXT_DECL}@anchor{3d6a}
@deffn {資料} xml.parsers.expat.errors.XML_ERROR_TEXT_DECL

There was an error parsing a text declaration in an external entity.
@end deffn

@geindex XML_ERROR_PUBLICID (於 xml.parsers.expat.errors 模組中)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_PUBLICID}@anchor{3d6b}
@deffn {資料} xml.parsers.expat.errors.XML_ERROR_PUBLICID

Characters were found in the public id that are not allowed.
@end deffn

@geindex XML_ERROR_SUSPENDED (於 xml.parsers.expat.errors 模組中)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_SUSPENDED}@anchor{3d6c}
@deffn {資料} xml.parsers.expat.errors.XML_ERROR_SUSPENDED

The requested operation was made on a suspended parser, but isn't allowed.  This
includes attempts to provide additional input or to stop the parser.
@end deffn

@geindex XML_ERROR_NOT_SUSPENDED (於 xml.parsers.expat.errors 模組中)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_NOT_SUSPENDED}@anchor{3d6d}
@deffn {資料} xml.parsers.expat.errors.XML_ERROR_NOT_SUSPENDED

An attempt to resume the parser was made when the parser had not been suspended.
@end deffn

@geindex XML_ERROR_ABORTED (於 xml.parsers.expat.errors 模組中)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_ABORTED}@anchor{3d6e}
@deffn {資料} xml.parsers.expat.errors.XML_ERROR_ABORTED

This should not be reported to Python applications.
@end deffn

@geindex XML_ERROR_FINISHED (於 xml.parsers.expat.errors 模組中)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_FINISHED}@anchor{3d6f}
@deffn {資料} xml.parsers.expat.errors.XML_ERROR_FINISHED

The requested operation was made on a parser which was finished parsing input,
but isn't allowed.  This includes attempts to provide additional input or to
stop the parser.
@end deffn

@geindex XML_ERROR_SUSPEND_PE (於 xml.parsers.expat.errors 模組中)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_SUSPEND_PE}@anchor{3d70}
@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{3d71}
@deffn {資料} xml.parsers.expat.errors.XML_ERROR_RESERVED_PREFIX_XML

An attempt was made to
undeclare reserved namespace prefix @code{xml}
or to bind it to another namespace URI.
@end deffn

@geindex XML_ERROR_RESERVED_PREFIX_XMLNS (於 xml.parsers.expat.errors 模組中)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_RESERVED_PREFIX_XMLNS}@anchor{3d72}
@deffn {資料} xml.parsers.expat.errors.XML_ERROR_RESERVED_PREFIX_XMLNS

An attempt was made to declare or undeclare reserved namespace prefix @code{xmlns}.
@end deffn

@geindex XML_ERROR_RESERVED_NAMESPACE_URI (於 xml.parsers.expat.errors 模組中)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_RESERVED_NAMESPACE_URI}@anchor{3d73}
@deffn {資料} xml.parsers.expat.errors.XML_ERROR_RESERVED_NAMESPACE_URI

An attempt was made to bind the URI of one the reserved namespace
prefixes @code{xml} and @code{xmlns} to another namespace prefix.
@end deffn

@geindex XML_ERROR_INVALID_ARGUMENT (於 xml.parsers.expat.errors 模組中)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_INVALID_ARGUMENT}@anchor{3d74}
@deffn {資料} xml.parsers.expat.errors.XML_ERROR_INVALID_ARGUMENT

This should not be reported to Python applications.
@end deffn

@geindex XML_ERROR_NO_BUFFER (於 xml.parsers.expat.errors 模組中)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_NO_BUFFER}@anchor{3d75}
@deffn {資料} xml.parsers.expat.errors.XML_ERROR_NO_BUFFER

This should not be reported to Python applications.
@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{3d76}
@deffn {資料} xml.parsers.expat.errors.XML_ERROR_AMPLIFICATION_LIMIT_BREACH

The limit on input amplification factor (from DTD and entities)
has been breached.
@end deffn

@geindex XML_ERROR_NOT_STARTED (於 xml.parsers.expat.errors 模組中)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_NOT_STARTED}@anchor{1844}
@deffn {資料} xml.parsers.expat.errors.XML_ERROR_NOT_STARTED

The parser was tried to be stopped or suspended before it started.


在 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 protocols 及支援,多媒體服務,結構化標記處理工具,Python 標準函式庫 Standard Library
@anchor{library/internet doc}@anchor{3d77}@anchor{library/internet internet}@anchor{3d78}@anchor{library/internet internet-protocols-and-support}@anchor{3d79}@anchor{library/internet translation-repo}@anchor{3d7a}
@section 網路協定 (Internet protocols) 及支援


@geindex WWW
@geindex Internet（網際網路）
@geindex World Wide Web （全球資訊網）

@geindex module（模組）;socket

這個章節講述的模組實作了網路協定及相關技術的支援；他們全都是用 Python 實作的。這裡的大多數模組都需要相依於系統的模組 @ref{d1,,socket}，目前普遍的平台都支援該模組。 以下為概述：

@menu
* webbrowser: webbrowser --- 方便的網頁瀏覽器控制器. 方便的網頁瀏覽器控制器
* wsgiref: wsgiref --- WSGI 工具與參考實作. WSGI 工具與參考實作
* urllib: urllib --- URL 處理模組. URL 處理模組
* urllib.request: urllib request --- 用來開啟 URLs 的可擴充函式庫. 用來開啟 URLs 的可擴充函式庫
* urllib.response: urllib response --- Response classes used by urllib. Response classes used by urllib
* urllib.parse: urllib parse --- 將 URL 剖析成元件. 將 URL 剖析成元件
* urllib.error: urllib error --- urllib request 引發的例外類別. urllib.request 引發的例外類別
* urllib.robotparser: urllib robotparser --- robots txt 的剖析器. robots.txt 的剖析器
* http: http --- HTTP 模組. HTTP 模組
* http.client: http client --- HTTP 協定用戶端. HTTP 協定用戶端
* ftplib: ftplib --- FTP 協定用戶端. FTP 協定用戶端
* poplib: poplib --- POP3 協定用戶端. POP3 協定用戶端
* imaplib: imaplib --- IMAP4 協定用戶端. IMAP4 協定用戶端
* smtplib: smtplib --- SMTP 協定用戶端. SMTP 協定用戶端
* uuid: uuid --- RFC 9562 定義的 UUID 物件. RFC 9562 定義的 UUID 物件
* socketserver: socketserver --- 用於網路伺服器的框架. 用於網路伺服器的框架
* http.server — HTTP 伺服器: http server — HTTP 伺服器. 
* http.cookies: http cookies --- HTTP 狀態管理. HTTP 狀態管理
* http.cookiejar: http cookiejar --- HTTP 用戶端的 Cookie 處理. HTTP 用戶端的 Cookie 處理
* xmlrpc: xmlrpc --- XMLRPC 伺服器與用戶模組. XMLRPC 伺服器與用戶模組
* xmlrpc.client: xmlrpc client --- XML-RPC 用戶端存取. XML-RPC 用戶端存取
* xmlrpc.server: xmlrpc server --- 基本 XML-RPC 伺服器. 基本 XML-RPC 伺服器
* ipaddress: ipaddress --- IPv4/IPv6 操作函式庫. IPv4/IPv6 操作函式庫

@end menu

@node webbrowser --- 方便的網頁瀏覽器控制器,wsgiref --- WSGI 工具與參考實作,,網路協定 Internet protocols 及支援
@anchor{library/webbrowser doc}@anchor{3d7b}@anchor{library/webbrowser module-webbrowser}@anchor{11b}@anchor{library/webbrowser webbrowser-convenient-web-browser-controller}@anchor{3d7c}
@subsection @code{webbrowser} --- 方便的網頁瀏覽器控制器


@geindex module; webbrowser

`原始碼：'Lib/webbrowser.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/webbrowser.py}


__________________________________________________________________


@ref{11b,,webbrowser} 模組提供了一個高階介面，允許向使用者顯示基於網頁的文件。在大多數情況下，只需從此模組呼叫 @ref{1802,,open()} 函式即可完成正確的操作。

在 Unix 下，X11 下首選圖形瀏覽器，但如果圖形瀏覽器不可用或 X11 顯示不可用，則將使用文字模式瀏覽器。如果使用文字模式瀏覽器，則呼叫程序將會阻塞 (block)，直到使用者退出瀏覽器。

如果環境變數 
@geindex BROWSER
@geindex 環境變數; BROWSER
@code{BROWSER} 存在，它會被直譯為以 @ref{1ffb,,os.pathsep} 分隔的瀏覽器串列，以在平台預設值之前嘗試。當串列部分的值包含字串 @code{%s} 時，它會被直譯為字面瀏覽器命令列，並使用引數 URL 替換 @code{%s}；如果值是指向已註冊瀏覽器之一的單個字，則此瀏覽器會被新增到搜尋串列的前面；如果該部分不包含 @code{%s}，則它僅被直譯為要啟動的瀏覽器的名稱。 @footnote{
此處命名的無完整路徑可執行檔將在 
@geindex PATH
@geindex 環境變數; PATH
@code{PATH} 環境變數中給定的目錄中被搜尋。
}


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


對於非 Unix 平台，或當 Unix 上有可用的遠端瀏覽器時，控制行程不會等待使用者以完成瀏覽器，而是允許遠端瀏覽器在顯示器上維護自己的視窗。如果遠端瀏覽器在 Unix 上不可用，控制行程將啟動新的瀏覽器並等待。

在 iOS 上，
@geindex BROWSER
@geindex 環境變數; BROWSER
@code{BROWSER} 環境變數以及控制自動引發 (autoraise)、瀏覽器設定和新分頁/視窗建立的任何引數都將被忽略。網頁將`始終'在使用者偏好的瀏覽器中的新分頁中開啟，並將瀏覽器帶到前台。在 iOS 上使用 @ref{11b,,webbrowser} 模組需要 @ref{2e,,ctypes} 模組。如果 @ref{2e,,ctypes} 不可用，則呼叫 @ref{1802,,open()} 將會失敗。

腳本 @code{webbrowser} 可以用作模組的命令列介面。它接受 URL 作為引數。它接受以下可選參數：

@geindex webbrowser 命令列選項; -n
@geindex webbrowser 命令列選項; --new-window
@anchor{library/webbrowser cmdoption-webbrowser-n}@anchor{3d7d}@anchor{library/webbrowser cmdoption-webbrowser-new-window}@anchor{3d7e}
@deffn {Option} @w{-}n, @w{-}@w{-}new@w{-}window

如果可能的話會在新的瀏覽器視窗中開啟 URL。
@end deffn

@geindex webbrowser 命令列選項; -t
@geindex webbrowser 命令列選項; --new-tab
@anchor{library/webbrowser cmdoption-webbrowser-t}@anchor{3d7f}@anchor{library/webbrowser cmdoption-webbrowser-new-tab}@anchor{3d80}
@deffn {Option} @w{-}t, @w{-}@w{-}new@w{-}tab

會在新的瀏覽器分頁 ("tab") 中開啟 URL。
@end deffn

這些選項自然是相互排斥的。用法範例如下：

@example
python -m webbrowser -t "https://www.python.org"
@end example

@ref{2006,,可用性}: not WASI, not Android.

以下例外有被定義於該模組：

@geindex Error
@anchor{library/webbrowser webbrowser Error}@anchor{3d81}
@deffn {例外} webbrowser.Error

當瀏覽器控制項發生錯誤時引發例外。
@end deffn

以下函式有被定義於該模組：

@geindex open() (於 webbrowser 模組中)
@anchor{library/webbrowser webbrowser open}@anchor{1802}
@deffn {函式} webbrowser.open (url, new=0, autoraise=True)

使用預設瀏覽器顯示 `url'。如果 `new' 為 0，則盡可能在同一瀏覽器視窗中開啟 `url'。如果 `new' 為 1，則盡可能開啟一個新的瀏覽器視窗。如果 `new' 為 2，則盡可能開啟一個新的瀏覽器分頁 ("tab")。如果 `autoraise' 為 @code{True}，則盡可能提升視窗（請注意，無論此變數的設定如何，許多視窗管理器下都會發生這種情況）。

如果瀏覽器成功啟動則回傳 @code{True}，否則回傳 @code{False}。

請注意，在某些平台上，嘗試使用此函式開啟檔案名稱可能能夠運作並啟動作業系統的關聯程式。然而這既不支援也不可移植。

引發一個附帶引數 @code{url} 的@ref{1b70,,稽核事件} @code{webbrowser.open}。
@end deffn

@geindex open_new() (於 webbrowser 模組中)
@anchor{library/webbrowser webbrowser open_new}@anchor{3d82}
@deffn {函式} webbrowser.open_new (url)

盡可能在預設瀏覽器的新視窗中開啟 `url'，否則在唯一的瀏覽器視窗中開啟 `url'。

如果瀏覽器成功啟動則回傳 @code{True}，否則回傳 @code{False}。
@end deffn

@geindex open_new_tab() (於 webbrowser 模組中)
@anchor{library/webbrowser webbrowser open_new_tab}@anchor{3d83}
@deffn {函式} webbrowser.open_new_tab (url)

盡可能在預設瀏覽器的新分頁 ("tab") 中開啟 `url'，否則相當於 @ref{3d82,,open_new()}。

如果瀏覽器成功啟動則回傳 @code{True}，否則回傳 @code{False}。
@end deffn

@geindex get() (於 webbrowser 模組中)
@anchor{library/webbrowser webbrowser get}@anchor{3d84}
@deffn {函式} webbrowser.get (using=None)

回傳瀏覽器類型`使用*（以引數 *using' 給定）的控制器物件。如果 `using' 為 @code{None}，則回傳適合呼叫者環境的預設瀏覽器控制器。
@end deffn

@geindex register() (於 webbrowser 模組中)
@anchor{library/webbrowser webbrowser register}@anchor{3d85}
@deffn {函式} webbrowser.register (name, constructor, instance=None, *, preferred=False)

註冊瀏覽器類型`名稱*（以引數 *name' 給定）。一旦註冊了瀏覽器類型，@ref{3d84,,get()} 函式就可以回傳該瀏覽器類型的控制器。如果沒有提供 `instance' 或為 @code{None}，則會在需要時不帶參數地呼叫 `constructor' 來建立實例。如果提供了 `instance'，`constructor' 將永遠不會被呼叫，並且可能為 @code{None}。

將 `preferred' 設為 @code{True} 會使該瀏覽器成為不帶引數的 @ref{3d84,,get()} 呼叫的偏好結果。否則只有當你計劃設定 
@geindex BROWSER
@geindex 環境變數; BROWSER
@code{BROWSER} 變數或使用與你宣告的處理程序名稱相符的非空引數呼叫 @ref{3d84,,get()} 時，此入口點才會有用。


在 3.7 版的變更: 新增了 `preferred' 僅限關鍵字參數。

@end deffn

預先定義了多種瀏覽器類型。此表給出了可以傳遞給 @ref{3d84,,get()} 函式的類型名稱以及控制器類別的相應實例化方式，這些都定義於此模組中。


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxx} 
@headitem

類型名稱

@tab

類別名稱

@tab

註解

@item

@code{'mozilla'}

@tab

@code{Mozilla('mozilla')}

@tab

@item

@code{'firefox'}

@tab

@code{Mozilla('mozilla')}

@tab

@item

@code{'epiphany'}

@tab

@code{Epiphany('epiphany')}

@tab

@item

@code{'kfmclient'}

@tab

@code{Konqueror()}

@tab

(1)

@item

@code{'konqueror'}

@tab

@code{Konqueror()}

@tab

(1)

@item

@code{'kfm'}

@tab

@code{Konqueror()}

@tab

(1)

@item

@code{'opera'}

@tab

@code{Opera()}

@tab

@item

@code{'links'}

@tab

@code{GenericBrowser('links')}

@tab

@item

@code{'elinks'}

@tab

@code{Elinks('elinks')}

@tab

@item

@code{'lynx'}

@tab

@code{GenericBrowser('lynx')}

@tab

@item

@code{'w3m'}

@tab

@code{GenericBrowser('w3m')}

@tab

@item

@code{'windows-default'}

@tab

@code{WindowsDefault}

@tab

(2)

@item

@code{'macosx'}

@tab

@code{MacOSXOSAScript('default')}

@tab

(3)

@item

@code{'safari'}

@tab

@code{MacOSXOSAScript('safari')}

@tab

(3)

@item

@code{'google-chrome'}

@tab

@code{Chrome('google-chrome')}

@tab

@item

@code{'chrome'}

@tab

@code{Chrome('chrome')}

@tab

@item

@code{'chromium'}

@tab

@code{Chromium('chromium')}

@tab

@item

@code{'chromium-browser'}

@tab

@code{Chromium('chromium-browser')}

@tab

@item

@code{'iosbrowser'}

@tab

@code{IOSBrowser}

@tab

(4)

@end multitable


註解：


@enumerate 

@item 
"Konqueror" 是 Unix 的 KDE 桌面環境的檔案管理器，只有在 KDE 運作時才有意義。最好能有某種可靠的 KDE 檢測方法；僅有 @code{KDEDIR} 變數是不夠的。另請注意，即使在 KDE 2 中使用 @code{konqueror} 命令時，也會使用 "kfm" 名稱 --- 該實作會選擇執行 Konqueror 的最佳策略。

@item 
僅在 Windows 平台上。

@item 
僅在 macOS 上。

@item 
僅在 iOS 上。
@end enumerate


在 3.2 版被加入: 新增了 @code{MacOSXOSAScript} 類別並於 Mac 上使用，而非使用先前的 @code{MacOSX} 類別。這增加了對開啟目前未設定為作業系統預設之瀏覽器的支援。



在 3.3 版被加入: 新增了對 Chrome/Chromium 的支援。



在 3.12 版的變更: 對多個過時瀏覽器的支援已被刪除。已刪除的瀏覽器包括 Grail、Mosaic、Netscape、Galeon、Skipstone、Iceape 和 Firefox 35 及以下版本。



在 3.13 版的變更: 新增了對 iOS 的支援。


以下是一些簡單範例：

@example
url = 'https://docs.python.org/'

# 如果瀏覽器視窗已打開，則在新分頁中開啟 URL。
webbrowser.open_new_tab(url)

# 在新視窗中開啟 URL，如果可能的話提升視窗。
webbrowser.open_new(url)
@end example

@menu
* 瀏覽器控制器物件:: 

@end menu

@node 瀏覽器控制器物件,,,webbrowser --- 方便的網頁瀏覽器控制器
@anchor{library/webbrowser browser-controller-objects}@anchor{3d86}@anchor{library/webbrowser browser-controllers}@anchor{3d87}
@subsubsection 瀏覽器控制器物件


瀏覽器控制器提供了 @ref{594,,name} 屬性和以下三個與模組層級便利函式相同的方法：

@geindex name (webbrowser.controller 的屬性)
@anchor{library/webbrowser webbrowser controller name}@anchor{594}
@deffn {屬性} controller.name

瀏覽器的系統相依名稱 (system-dependent name)。
@end deffn

@geindex open() (webbrowser.controller 的方法)
@anchor{library/webbrowser webbrowser controller open}@anchor{3d88}
@deffn {方法} controller.open (url, new=0, autoraise=True)

使用此控制器處理的瀏覽器顯示 `url'。如果 `new' 為 1，則盡可能開啟一個新的瀏覽器視窗。如果 `new' 為 2，則盡可能開啟一個新的瀏覽器分頁 ("tab")。
@end deffn

@geindex open_new() (webbrowser.controller 的方法)
@anchor{library/webbrowser webbrowser controller open_new}@anchor{3d89}
@deffn {方法} controller.open_new (url)

盡可能在此控制器處理的瀏覽器的新視窗中開啟 `url'，否則在唯一的瀏覽器視窗中開啟 `url'。別名為 @ref{3d82,,open_new()}。
@end deffn

@geindex open_new_tab() (webbrowser.controller 的方法)
@anchor{library/webbrowser webbrowser controller open_new_tab}@anchor{3d8a}
@deffn {方法} controller.open_new_tab (url)

盡可能在此控制器處理的瀏覽器的新分頁 ("tab") 中開啟 `url'，否則相當於 @ref{3d82,,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 工具與參考實作,urllib --- URL 處理模組,webbrowser --- 方便的網頁瀏覽器控制器,網路協定 Internet protocols 及支援
@anchor{library/wsgiref doc}@anchor{3d8b}@anchor{library/wsgiref module-wsgiref}@anchor{11e}@anchor{library/wsgiref translation-repo}@anchor{3d8c}@anchor{library/wsgiref wsgiref-wsgi-utilities-and-reference-implementation}@anchor{3d8d}
@subsection @code{wsgiref} --- WSGI 工具與參考實作


@geindex module; wsgiref

`原始碼：'Lib/wsgiref@footnote{https://github.com/python/cpython/tree/3.14/Lib/wsgiref}


__________________________________________________________________


網頁伺服器閘道介面 (WSGI) 是一個標準介面，用於連接網頁伺服器軟體與使用 Python 撰寫的網頁應用程式，擁有一個標準介面使得支援 WSGI 的應用程式可以與多個不同的網頁伺服器運行。

只有網頁伺服器與程式框架的作者需要瞭解 WSGI 設計的每個細節與邊角案例，你並不需要為了安裝 WSGI 應用程式或是使用現有框架撰寫網頁應用程式而必須理解每個細節。

@ref{11e,,wsgiref} 是 WSGI 規格的參考實作，可用於新增 WSGI 來支援網頁伺服器或框架，它提供操作 WSGI 環境變數以及回應標頭的工具，用於實作 WSGI 伺服器的基本類別，提供用於示範 HTTP 伺服器的 WSGI 應用程式、靜態型別檢查、以及驗證 WSGI 伺服器與應用程式是否符合 WSGI 規格的驗證工具 (
@geindex Python Enhancement Proposals; PEP 3333
PEP 3333@footnote{https://peps.python.org/pep-3333/})。

參閱 wsgi.readthedocs.io@footnote{https://wsgi.readthedocs.io/} 更多 WSGI 相關資訊，以及教學連結與其他資源。

@c XXX If you're just trying to write a web application...

@menu
* wsgiref.util: wsgiref util -- WSGI 環境工具. WSGI 環境工具
* wsgiref.headers: wsgiref headers -- WSGI 回應標頭工具. WSGI 回應標頭工具
* wsgiref.simple_server: wsgiref simple_server -- 一個簡單的 WSGI HTTP 伺服器. 一個簡單的 WSGI HTTP 伺服器
* wsgiref.validate: wsgiref validate --- WSGI 符合性檢查. WSGI 符合性檢查
* wsgiref.handlers: wsgiref handlers -- 伺服器 / 閘道基本類別. 伺服器 / 閘道基本類別
* wsgiref.types: wsgiref types -- 用於靜態型別檢查的 WSGI 型別. 用於靜態型別檢查的 WSGI 型別
* 範例: 範例<35>. 

@end menu

@node wsgiref util -- WSGI 環境工具,wsgiref headers -- WSGI 回應標頭工具,,wsgiref --- WSGI 工具與參考實作
@anchor{library/wsgiref module-wsgiref util}@anchor{123}@anchor{library/wsgiref wsgiref-util-wsgi-environment-utilities}@anchor{3d8e}
@subsubsection @code{wsgiref.util} -- WSGI 環境工具


@geindex module; wsgiref.util

這個模組提供許多用於處理 WSGI 環境運作的功能。WSGI 環境是一個包含 HTTP 請求變數的字典，如 
@geindex Python Enhancement Proposals; PEP 3333
PEP 3333@footnote{https://peps.python.org/pep-3333/} 所述。所有接受 `environ' 的參數的函式都需要提供符合 WSGI 標準的字典；請參閱 
@geindex Python Enhancement Proposals; PEP 3333
PEP 3333@footnote{https://peps.python.org/pep-3333/} 取得詳細規格，以及 @ref{3d8f,,WSGIEnvironment} 取得可用於使用型別註釋的型別別名。

@geindex guess_scheme() (於 wsgiref.util 模組中)
@anchor{library/wsgiref wsgiref util guess_scheme}@anchor{3d90}
@deffn {函式} wsgiref.util.guess_scheme (environ)

透過檢查 `environ' 字典中的 @code{HTTPS} 環境變數，回傳 @code{wsgi.url_scheme} 應該是 "http" 或 "https" 的猜測。回傳值為一個字串。

當建立一個包裝 CGI 或類似 FastCGI 的 CGI-like 協定閘道時，此函式非常有用。例如 FastCGI，通常提供這類協定的伺服器在通過 SSL 接收到請求時會包含 "1"，"yes"，或 "on" 的 @code{HTTPS} 變數，因此，如果找到這樣的值，此函式回傳 "https"，否則回傳 "http"。
@end deffn

@geindex request_uri() (於 wsgiref.util 模組中)
@anchor{library/wsgiref wsgiref util request_uri}@anchor{3d91}
@deffn {函式} wsgiref.util.request_uri (environ, include_query=True)

根據 
@geindex Python Enhancement Proposals; PEP 3333
PEP 3333@footnote{https://peps.python.org/pep-3333/} 中 "URL Reconstruction" 章節所找到的演算法，回傳完整的請求 URI，可選擇性的包含查詢字串，如果 `include_query' 設為 false，查詢字串不會被包含在結果的 URI 中。
@end deffn

@geindex application_uri() (於 wsgiref.util 模組中)
@anchor{library/wsgiref wsgiref util application_uri}@anchor{3d92}
@deffn {函式} wsgiref.util.application_uri (environ)

類似於 @ref{3d91,,request_uri()}，但忽略 @code{PATH_INFO} 和 @code{QUERY_STRING} 變數。結果是請求地址的應用程式物件的的基本 URI。
@end deffn

@geindex shift_path_info() (於 wsgiref.util 模組中)
@anchor{library/wsgiref wsgiref util shift_path_info}@anchor{3d93}
@deffn {函式} wsgiref.util.shift_path_info (environ)

將單一名稱從 @code{PATH_INFO} 移到 @code{SCRIPT_NAME} 並回傳該名稱。`environ' 字典會在適當時機被 `modified'；如果你需要保留原始完好無損的 @code{PATH_INFO} 或 @code{SCRIPT_NAME} 請使用副本。

如果在 @code{PATH_INFO} 中沒有剩餘的路徑片段，則回傳 @code{None}。

通常，此程式用於處理請求 URI 的每一部分路徑，例如將路徑視為一系列的字典鍵此程式會修改傳入的環境，使其適用於呼叫位於目標 URI 的 WSGI 應用程式。例如，如果在 @code{/foo} 上有一個 WSGI 應用程式且請求 URI 路徑為 @code{/foo/bar/baz}，並且位於 @code{/foo} 的 WSGI 應用程式呼叫 @ref{3d93,,shift_path_info()}，它將接收字串 "bar"，而環境將被更新為適用於傳遞給位於 @code{/foo/bar} 的 WSGI 應用程式。換句話說，@code{SCRIPT_NAME} 將從 @code{/foo} 變更為 @code{/foo/bar}，而 @code{PATH_INFO} 將從 @code{/bar/baz} 變更為 @code{/baz}。

當 @code{PATH_INFO} 只是一個 "/" 時， 此程式會回傳一個空字串，並在 @code{SCRIPT_NAME} 後添加尾部斜號，即使空路徑片段通常是被忽略的，而且 @code{SCRIPT_NAME} 通常不會以斜號結尾。這是刻意行為，以確保應用程式在使用這個程式進行物件遍歷時可以區分結尾為 @code{/x} 和結尾為 @code{/x/} 的 URIs。
@end deffn

@geindex setup_testing_defaults() (於 wsgiref.util 模組中)
@anchor{library/wsgiref wsgiref util setup_testing_defaults}@anchor{3d94}
@deffn {函式} wsgiref.util.setup_testing_defaults (environ)

為測試目的，以簡單的預設值更新 `environ' 。

這個程式新增 WSGI 所需的各種參數，包括 @code{HTTP_HOST}、@code{SERVER_NAME}、@code{SERVER_PORT}、@code{REQUEST_METHOD}、@code{SCRIPT_NAME}、@code{PATH_INFO}，以及所有 
@geindex Python Enhancement Proposals; PEP 3333
PEP 3333@footnote{https://peps.python.org/pep-3333/} 定義的 @code{wsgi.*} 變數，它只提供預設值，並且不會取代現有的這些變數設定。

這個程式目的為了讓 WSGI 伺服器和應用程式的單元測試更容易建置虛擬環境。實際的 WSGI 伺服器或應用程式不應該使用它，因為所產生的數據是假的！

Example usage (see also @ref{3d95,,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

除了上述的環境功能外，@ref{123,,wsgiref.util} 模組還提供以下各類工具：

@geindex is_hop_by_hop() (於 wsgiref.util 模組中)
@anchor{library/wsgiref wsgiref util is_hop_by_hop}@anchor{198c}
@deffn {函式} wsgiref.util.is_hop_by_hop (header_name)

如果 'header_name' 是根據 
@geindex RFC; RFC 2616
RFC 2616@footnote{https://datatracker.ietf.org/doc/html/rfc2616.html} 所定義的 HTTP/1.1 "Hop-by-Hop" 標頭，則回傳 @code{True}。
@end deffn

@geindex FileWrapper (wsgiref.util 中的類別)
@anchor{library/wsgiref wsgiref util FileWrapper}@anchor{937}
@deffn {類別} wsgiref.util.FileWrapper (filelike, blksize=8192)

@ref{3d96,,wsgiref.types.FileWrapper} 協定的具體實作，用於將類檔案物件轉換為 @ref{4c3,,iterator}。產生的物件是 @ref{1428,,iterable}。當物件進行疊代時，將可選的 `blksize' 引數重複傳遞給 `filelike' 物件的 @code{read()} 方法來獲得將產生（yield）的位元組字串。當 @code{read()} 回傳一個空位元組字串，代表疊代已結束且無法回復。

如果 `filelike' 有 @code{close()} 方法，則回傳的物件也會具有 @code{close()} 方法，並在呼叫時叫用 `filelike' 物件的 @code{close()} 方法。

用法範例：

@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 版的變更: 已移除對 @ref{582,,__getitem__()} 方法的支援。

@end deffn

@node wsgiref headers -- WSGI 回應標頭工具,wsgiref simple_server -- 一個簡單的 WSGI HTTP 伺服器,wsgiref util -- WSGI 環境工具,wsgiref --- WSGI 工具與參考實作
@anchor{library/wsgiref module-wsgiref headers}@anchor{120}@anchor{library/wsgiref wsgiref-headers-wsgi-response-header-tools}@anchor{3d97}
@subsubsection @code{wsgiref.headers} -- WSGI 回應標頭工具


@geindex module; wsgiref.headers

這個模組提供單一類別 @ref{1093,,Headers}，用於使用類似對映的介面方便地操作 WSGI 回應標頭。

@geindex Headers (wsgiref.headers 中的類別)
@anchor{library/wsgiref wsgiref headers Headers}@anchor{1093}
@deffn {類別} wsgiref.headers.Headers ([headers])

建立一個類似對映物件並包裝 `headers'，並且必須是符合 
@geindex Python Enhancement Proposals; PEP 3333
PEP 3333@footnote{https://peps.python.org/pep-3333/} 描述的 name/value 元組的標頭串列。`headers' 的預設值是一個空串列。

@ref{1093,,Headers} 物件支援典型對映操作包括 @code{__getitem__()}、@ref{1efb,,get()}、@ref{14cc,,__setitem__()}、@ref{1274,,setdefault()}、@ref{14cd,,__delitem__()} 以及 @ref{15b1,,__contains__()}。對於這些方法中的每一個，鍵是標頭名稱（以不區分大小寫方式處理），而值則是與該標頭名稱關聯的第一個值。設定標頭會刪除該標頭的所有現有值，然後將新值添加到包裝的標頭串列末尾。標頭的現有順序通常保持不變，新標頭會添加到包裝串列的末尾。

不同於字典，當你嘗試取得或刪除包裝的標頭串列不存在的鍵，@ref{1093,,Headers} 物件不會引發例外錯誤。取得不存在的標頭只會回傳 @code{None}，而刪除不存在的標頭則不會有任何效果。

@ref{1093,,Headers} 物件還支援 @code{keys()}、@code{value()}、和 @code{items()} 方法。由 @code{keys()} 和 @code{items()} 回傳的串列在存在多值標頭時可能會包含相同的鍵。@ref{1093,,Headers} 物件的 @code{len()} 與 @code{items()} 的長度相同，也與包裝標頭串列的長度相同。實際上，@code{items()} 方法只是回傳包裝的標頭串列的副本。

對 @code{Header} 物件呼叫 @code{bytes()} 會回傳適合作為 HTTP 傳輸回應標頭的格式化的位元組字串。每個標頭都與其值一起置於一行上，由冒號與空格分隔。每行以回車（carriage return）和換行（line feed）結束，而該位元組字串則以空行結束。

除了對映介面和格式化功能外，@ref{1093,,Headers} 物件還具有以下查詢及附加多值標頭的以及附加 MIME 參數標頭的方法：

@geindex get_all() (wsgiref.headers.Headers 的方法)
@anchor{library/wsgiref wsgiref headers Headers get_all}@anchor{3d98}
@deffn {方法} get_all (name)

回傳指定標頭的所有值的串列。

回傳的串列按照它們在在原始的標頭串列出現的順序或是被添加到此實例的順序進行排序，並且可能包含重複的內容。任何被刪除並重新插入的欄位都會被添加到標頭串列的末尾。如果不存在指定名稱的欄位，則回傳空串列。
@end deffn

@geindex add_header() (wsgiref.headers.Headers 的方法)
@anchor{library/wsgiref wsgiref headers Headers add_header}@anchor{3d99}
@deffn {方法} add_header (name, value, **_params)

添加一個（可能是多值的）標頭，可通過關鍵字引數來指定選擇性的 MIME 參數。

`name' 是要添加的標頭欄位。關鍵字引數可使於設定標頭欄位的 MIME 參數。每一個參數必須是字串或是 @code{None}。由於破折號在 Python 識別符中是非法的，但是許多 MIME 參數名稱包含破折號，因此參數名稱的底線會轉換成破折號。如果參數值是字串，則以 @code{name="value"} 的形式添加到標頭值參數中。如果它是 @code{None}，則僅添加參數名稱。（這使用於沒有值的 MIME 參數）使用範例：

@example
h.add_header('content-disposition', 'attachment', filename='bud.gif')
@end example

上述操作將添加看起來像這樣的標頭：

@example
Content-Disposition: attachment; filename="bud.gif"
@end example
@end deffn


在 3.5 版的變更: `headers' 參數是可選的。

@end deffn

@node wsgiref simple_server -- 一個簡單的 WSGI HTTP 伺服器,wsgiref validate --- WSGI 符合性檢查,wsgiref headers -- WSGI 回應標頭工具,wsgiref --- WSGI 工具與參考實作
@anchor{library/wsgiref module-wsgiref simple_server}@anchor{121}@anchor{library/wsgiref wsgiref-simple-server-a-simple-wsgi-http-server}@anchor{3d9a}
@subsubsection @code{wsgiref.simple_server} -- 一個簡單的 WSGI HTTP 伺服器


@geindex module; wsgiref.simple_server

這個模組實作一個簡單的的 HTTP 伺服器（基於 @ref{76,,http.server}）用於提供 WSGI 應用程式。每個伺服器執行個體在特定的主機與埠提供單一的 WSGI 應用程式。如果你想要在單一主機與埠上提供多個應用程式，你應該建立一個 WSGI 應用程式以剖析 @code{PATH_INFO} 去選擇為每個請求叫用哪個應用程式。（例如，使用來自 @ref{123,,wsgiref.util} 的 @code{shift_path_info()} 函式。）

@geindex make_server() (於 wsgiref.simple_server 模組中)
@anchor{library/wsgiref wsgiref simple_server make_server}@anchor{3d9b}
@deffn {函式} wsgiref.simple_server.make_server (host, port, app, server_class=WSGIServer, handler_class=WSGIRequestHandler)

建立一個新的 WSGI 伺服器監聽 `host' 和 `port'，接受 `app' 的連線。回傳值是提供 `server_class' 的實例，並將使用指定的 `handler_class' 處理請求。`app' 必須是一個 WSGI 應用程式物件，如 
@geindex Python Enhancement Proposals; PEP 3333
PEP 3333@footnote{https://peps.python.org/pep-3333/} 所定義。

用法範例：

@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{3d95}
@deffn {函式} wsgiref.simple_server.demo_app (environ, start_response)

這個函式是一個簡單但完整的 WSGI 應用程式，它回傳一個包含訊息 "Hello world!" 和在 `environ' 參數中提供的鍵值對串列的文字頁面。這對於驗證 WSGI 伺服器（例如 @ref{121,,wsgiref.simple_server}）是否能正確執行簡單的 WSGI 應用程式非常有用。

The `start_response' callable should follow the @ref{3d9c,,StartResponse} protocol.
@end deffn

@geindex WSGIServer (wsgiref.simple_server 中的類別)
@anchor{library/wsgiref wsgiref simple_server WSGIServer}@anchor{3d9d}
@deffn {類別} wsgiref.simple_server.WSGIServer (server_address, RequestHandlerClass)

建立一個 @ref{3d9d,,WSGIServer} 實例。`server_address' 應該是一個 @code{(host, port)} 元組，而 `RequestHandlerClass' 應該是 @ref{12cc,,http.server.BaseHTTPRequestHandler} 的子類別，將用於處理請求。

通常你不需要呼叫這個建構函式（constructor），因為 @ref{3d9b,,make_server()} 函式可以為你處理所有細節。

@ref{3d9d,,WSGIServer} 是 @ref{3d9e,,http.server.HTTPServer} 的子類別，因此它的所有方法（例如 @code{serve_forever()} 和 @code{handle_request()}）都可用。@ref{3d9d,,WSGIServer} 也提供這些特定於 WSGI 的方法：

@geindex set_app() (wsgiref.simple_server.WSGIServer 的方法)
@anchor{library/wsgiref wsgiref simple_server WSGIServer set_app}@anchor{3d9f}
@deffn {方法} set_app (application)

將可呼叫的 `application' 設定為接收請求的 WSGI 應用程式。
@end deffn

@geindex get_app() (wsgiref.simple_server.WSGIServer 的方法)
@anchor{library/wsgiref wsgiref simple_server WSGIServer get_app}@anchor{3da0}
@deffn {方法} get_app ()

回傳目前設定應用程式的可呼叫物件。
@end deffn

然而，通常情況下你不需要去使用這些額外方法，因為 @ref{3d9f,,set_app()} 通常會被 @ref{3d9b,,make_server()} 呼叫而 @ref{3da0,,get_app()} 主要存在於請求處理程式（handler）實例的好處上。
@end deffn

@geindex WSGIRequestHandler (wsgiref.simple_server 中的類別)
@anchor{library/wsgiref wsgiref simple_server WSGIRequestHandler}@anchor{3da1}
@deffn {類別} wsgiref.simple_server.WSGIRequestHandler (request, client_address, server)

為給定的 `request*（即一個 socket）、*client_address*（一個 `@w{`}(host,port)`@w{`} 位元組）、*server' (@ref{3d9d,,WSGIServer} 實例) 建立一個 HTTP 處理程式（handler）。

你不需要直接建立這個類別的實例；它們會在需要時由 @ref{3d9d,,WSGIServer} 物件自動建立。不過，你可以建立這個類別的子類別並將其作為 `handler_class' 提供給 @ref{3d9b,,make_server()} 函式。一些可能相關的方法可以在子類別中進行覆寫：

@geindex get_environ() (wsgiref.simple_server.WSGIRequestHandler 的方法)
@anchor{library/wsgiref wsgiref simple_server WSGIRequestHandler get_environ}@anchor{3da2}
@deffn {方法} get_environ ()

唯一個請求回傳一個 @ref{3d8f,,WSGIEnvironment} 字典。預設的實作會複製 @ref{3d9d,,WSGIServer} 物件的 @code{base_environ} 字典屬性的內容以及添加從 HTTP 請求中衍生的各種標頭。每次呼叫這個方法都應該回傳一個包含所有如 
@geindex Python Enhancement Proposals; PEP 3333
PEP 3333@footnote{https://peps.python.org/pep-3333/} 所指定的相關 CGI 環境變數的新字典。
@end deffn

@geindex get_stderr() (wsgiref.simple_server.WSGIRequestHandler 的方法)
@anchor{library/wsgiref wsgiref simple_server WSGIRequestHandler get_stderr}@anchor{3da3}
@deffn {方法} get_stderr ()

回傳的物件應該被用作 @code{wsgi.errors} 串流。預設實作只會回傳 @code{sys.stderr}。
@end deffn

@geindex handle() (wsgiref.simple_server.WSGIRequestHandler 的方法)
@anchor{library/wsgiref wsgiref simple_server WSGIRequestHandler handle}@anchor{3da4}
@deffn {方法} handle ()

處理 HTTP 請求。預設實作會使用 @code{wsgiref.handler} 類別來建立處置程式（handler）實例來實作實際 WSGI 應用程式介面。
@end deffn
@end deffn

@node wsgiref validate --- WSGI 符合性檢查,wsgiref handlers -- 伺服器 / 閘道基本類別,wsgiref simple_server -- 一個簡單的 WSGI HTTP 伺服器,wsgiref --- WSGI 工具與參考實作
@anchor{library/wsgiref module-wsgiref validate}@anchor{124}@anchor{library/wsgiref wsgiref-validate-wsgi-conformance-checker}@anchor{3da5}
@subsubsection @code{wsgiref.validate} --- WSGI 符合性檢查


@geindex module; wsgiref.validate

當建立新的 WSGI 應用程式物件、框架、伺服器、或是中介軟體（middleware）時，使用 @ref{124,,wsgiref.validate} 來驗證新程式碼的符合性可能會很有用。這個模組提供一個函式用於建立 WSGI 應用程式物件，並用於驗證 WSGI 伺服器或是閘道與 WSGI 應用程式物件之間的通訊，以檢查雙方協定的符合性。

請注意這個工具並不保證完全符合 
@geindex Python Enhancement Proposals; PEP 3333
PEP 3333@footnote{https://peps.python.org/pep-3333/}；這個模組中的錯誤不一定代表不存在錯誤。但是，如果如果這個模組產生錯誤，那麼幾乎可以確定伺服器或應用程式不是 100% 符合標準。

這個模組基於 Ian Bicking 的 "Python Paste" 函式庫的 @code{paste.lint} 模組。

@geindex validator() (於 wsgiref.validate 模組中)
@anchor{library/wsgiref wsgiref validate validator}@anchor{3da6}
@deffn {函式} wsgiref.validate.validator (application)

包裝 `application' 並回傳一個新的 WSGI 應用程式物件。回傳的應用程式將轉發所有請求給原始的 `application'，並檢查 `application' 和呼叫它的伺服器是否符合 WSGI 規範和 
@geindex RFC; RFC 2616
RFC 2616@footnote{https://datatracker.ietf.org/doc/html/rfc2616.html}。

任何在 @ref{8b0,,AssertionError} 中偵測不符合結果都會發起例外；但請注意，如何處理這些錯誤取決於伺服器。例如，基於 @ref{11f,,wsgiref.handlers} 的 @ref{121,,wsgiref.simple_server} 以及其他伺服器（未覆蓋錯誤處理方法以執行其他操作的伺服器）將僅輸出一條錯誤訊息，指示發生錯誤，並將回溯訊息輸出到 @code{sys.stderr} 或是其他錯誤串流。

這個包裝器也可以使用 @ref{118,,warnings} 模組生成輸出去指示一些可能有疑慮但實際上可能不會被 
@geindex Python Enhancement Proposals; PEP 3333
PEP 3333@footnote{https://peps.python.org/pep-3333/} 禁止的行為。除非使用 Python 命令列選項或 @ref{118,,warnings} API，抑制了這些警告，否則這類警告將被寫入到 @code{sys.stderr}（`not' @code{wsgi.errors}，除非它們碰巧是相同的物件）。

用法範例：

@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 -- 伺服器 / 閘道基本類別,wsgiref types -- 用於靜態型別檢查的 WSGI 型別,wsgiref validate --- WSGI 符合性檢查,wsgiref --- WSGI 工具與參考實作
@anchor{library/wsgiref module-wsgiref handlers}@anchor{11f}@anchor{library/wsgiref wsgiref-handlers-server-gateway-base-classes}@anchor{3da7}
@subsubsection @code{wsgiref.handlers} -- 伺服器 / 閘道基本類別


@geindex module; wsgiref.handlers

這個模組提供實作 WSGI 伺服器和閘道的基礎處理程式（handler）類別。這些基底類別處理程式大部分與 WSGI 應用程式通訊的工作，只要它們被提供 CGI-like 環境，以及輸入、輸出和錯誤串流。

@geindex CGIHandler (wsgiref.handlers 中的類別)
@anchor{library/wsgiref wsgiref handlers CGIHandler}@anchor{3da8}
@deffn {類別} wsgiref.handlers.CGIHandler

這是基於 CGI 的呼叫方式並透過 @code{sys.stdin}、@code{sys.stdout}、@code{sys.stderr} 和 @code{os.environ}。當你擁有一個 WSGI 應用程式並希望將其作為 CGI 腳本運行時是很有用的。只需叫用 @code{CGIHandler().run(app)}，其中 @code{app} 是你希望叫用的 WSGI 應用程式物件。

這個類別是 @ref{3da9,,BaseCGIHandler} 的子類別將 @code{wsgi.run_once} 設置為 true，@code{wsgi.multithread} 設置為 false，並將 @code{wsgi.multiprocess} 設置為 true，並且始終使用 @ref{df,,sys} 和 @ref{a5,,os} 來取得所需的 CGI 串流以及環境。
@end deffn

@geindex IISCGIHandler (wsgiref.handlers 中的類別)
@anchor{library/wsgiref wsgiref handlers IISCGIHandler}@anchor{3daa}
@deffn {類別} wsgiref.handlers.IISCGIHandler

這是用於在 Microsoft 的 IIS 網頁伺服器上部署時使用的 @ref{3da8,,CGIHandler} 的一個專門替代選擇，無需設置 config 的 allowPathInfo 選項（IIS>=7），或 metabase 的 allowPathInfoForScriptMappings 選項（IIS<7）。

預設情況下，IIS 提供的 @code{PATH_INFO} 會在前面複製 @code{SCRIPT_NAME}，對於希望實作路由的 WSGI 應用程式造成問題。這個處理程式（handler）會移除任何這樣的重複路徑。

IIS 可以配置去傳遞正確的 @code{PATH_INFO}，但這會導致 @code{PATH_TRANSLATED} 是錯誤的問題。幸運的是這個變數很少被使用並且不受 WSGI 保證。然而，在 IIS<7 上，這個設置只能在虛擬主機層級進行，影響所有其他腳本的對映，其中許多在暴露 @code{PATH_TRANSLATED} 問題時會中斷。由於這個原因幾乎從不會使用修復的 IIS<7（即使是 IIS7 也很少使用它，因為它仍然沒有相應的 UI）。

CGI 程式碼無法知道是否已設置該選項，因此提供了一個獨立的處理程式（handler）類別。它的使用方式與 @ref{3da8,,CGIHandler} 相同，即透過呼叫 @code{IISCGIHandler().run(app)} 來使用，其中 @code{app} 是你希望叫用的 WSGI 應用程式物件。


在 3.2 版被加入.

@end deffn

@geindex BaseCGIHandler (wsgiref.handlers 中的類別)
@anchor{library/wsgiref wsgiref handlers BaseCGIHandler}@anchor{3da9}
@deffn {類別} wsgiref.handlers.BaseCGIHandler (stdin, stdout, stderr, environ, multithread=True, multiprocess=False)

類似於 @ref{3da8,,CGIHandler}，但不是使用 @ref{df,,sys} 和 @ref{a5,,os} 模組，而是明確指定 CGI 環境與 I/O 串流。`multithread' 和 `multiprocess' 值用於設置由處理程式（handler）實例運行的任何應用程式的旗標。

這個類別是專門為除了 HTTP "origin servers" 以外的軟體一起使用的 @ref{3dab,,SimpleHandler} 的子類別。如果你正在撰寫一個使用 @code{Status:} 標頭來發送 HTTP 狀態的閘道協定實作（例如 CGI、FastCGI、SCGI 等），你可能會想要子類化這個類別來替代 @ref{3dab,,SimpleHandler}。
@end deffn

@geindex SimpleHandler (wsgiref.handlers 中的類別)
@anchor{library/wsgiref wsgiref handlers SimpleHandler}@anchor{3dab}
@deffn {類別} wsgiref.handlers.SimpleHandler (stdin, stdout, stderr, environ, multithread=True, multiprocess=False)

類似於 @ref{3da9,,BaseCGIHandler}，但是被設計使用在 HTTP origin 伺服器。如果你正在撰寫 HTTP 伺服器的實作，你可能會想要子類別化這個類別來替代 @ref{3da9,,BaseCGIHandler}。

這個類別是 @ref{1c9c,,BaseHandler} 的子類別。它透過建構函式去覆寫 @code{__init__()}、@ref{3dac,,get_stdin()}、@ref{3dad,,get_stderr()}、@ref{3dae,,add_cgi_vars()}、@ref{3daf,,_write()}、和 @ref{3db0,,_flush()} 方法來明確提供設置環境與串流。提供的環境與串流被儲存在 @code{stdin}、@code{stdout}、@code{stderr}、和 @code{environ} 環境中。

`stdout' 的 @ref{ed2,,write()} 方法應該完整地寫入每個塊（chunk），像是 @ref{89c,,io.BufferedIOBase}。
@end deffn

@geindex BaseHandler (wsgiref.handlers 中的類別)
@anchor{library/wsgiref wsgiref handlers BaseHandler}@anchor{1c9c}
@deffn {類別} wsgiref.handlers.BaseHandler

這是一個運行 WSGI 應用程式的抽象基底類別。每個實例將處理單個 HTTP 請求，儘管原則上你可以建立一個可重用於多個請求的子類別。

@ref{1c9c,,BaseHandler} 實例只有一個供外部使用的方法：

@geindex run() (wsgiref.handlers.BaseHandler 的方法)
@anchor{library/wsgiref wsgiref handlers BaseHandler run}@anchor{3db1}
@deffn {方法} run (app)

運行指定 WSGI 應用程式，`app'。
@end deffn

此方法在運行應用程式的過程中叫用了所有其他 @ref{1c9c,,BaseHandler} 的方法，因此這些方法主要存在是為了允許自定義整個過程。

以下方法必須在子類別中覆寫：

@geindex _write() (wsgiref.handlers.BaseHandler 的方法)
@anchor{library/wsgiref wsgiref handlers BaseHandler _write}@anchor{3daf}
@deffn {方法} _write (data)

緩衝要傳送給用戶端的位元組 `data'。如果這個方法實際上傳送了數據也是可以的；當底層系統實際具有這種區分時，@ref{1c9c,,BaseHandler} 為了更好的效能進而分離寫入和刷新操作。
@end deffn

@geindex _flush() (wsgiref.handlers.BaseHandler 的方法)
@anchor{library/wsgiref wsgiref handlers BaseHandler _flush}@anchor{3db0}
@deffn {方法} _flush ()

強制將緩衝數據傳送到用戶端。如果這是一個無操作（no-op）的方法（即，如果 @ref{3daf,,_write()} 實際上發送了數據），那麼是可以的。
@end deffn

@geindex get_stdin() (wsgiref.handlers.BaseHandler 的方法)
@anchor{library/wsgiref wsgiref handlers BaseHandler get_stdin}@anchor{3dac}
@deffn {方法} get_stdin ()

回傳一個與 @ref{3db2,,InputStream} 相容的物件並適用於用作目前正在處理請求的 @code{wsgi.input}。
@end deffn

@geindex get_stderr() (wsgiref.handlers.BaseHandler 的方法)
@anchor{library/wsgiref wsgiref handlers BaseHandler get_stderr}@anchor{3dad}
@deffn {方法} get_stderr ()

回傳一個與 @ref{3db3,,ErrorStream} 相容的物件並適用於用作目前正在處理請求的 @code{wsgi.errors}。
@end deffn

@geindex add_cgi_vars() (wsgiref.handlers.BaseHandler 的方法)
@anchor{library/wsgiref wsgiref handlers BaseHandler add_cgi_vars}@anchor{3dae}
@deffn {方法} add_cgi_vars ()

將目前請求的 CGI 變數插入到 @code{environ} 屬性中。
@end deffn

以下是你可能希望覆寫的其他方法和屬性。這個列表只是一個摘要，然而，不包括可以被覆寫的每個方法。在嘗試建立自定義的 @ref{1c9c,,BaseHandler} 子類別之前，你應該參考文件說明和原始碼以獲得更多資訊。

用於自定義 WSGI 環境的屬性和方法：

@geindex wsgi_multithread (wsgiref.handlers.BaseHandler 的屬性)
@anchor{library/wsgiref wsgiref handlers BaseHandler wsgi_multithread}@anchor{3db4}
@deffn {屬性} wsgi_multithread

用於 @code{wsgi.multithread} 環境變數的值。在 @ref{1c9c,,BaseHandler} 中預設為 true，但在其他子類別中可能有不同的預設值（或由建構函式設置）。
@end deffn

@geindex wsgi_multiprocess (wsgiref.handlers.BaseHandler 的屬性)
@anchor{library/wsgiref wsgiref handlers BaseHandler wsgi_multiprocess}@anchor{3db5}
@deffn {屬性} wsgi_multiprocess

用於 @code{wsgi.multiprocess} 環境變數的值。在 @ref{1c9c,,BaseHandler} 中預設為 true，但在其他子類別中可能有不同的預設值（或由建構函式設置）。
@end deffn

@geindex wsgi_run_once (wsgiref.handlers.BaseHandler 的屬性)
@anchor{library/wsgiref wsgiref handlers BaseHandler wsgi_run_once}@anchor{3db6}
@deffn {屬性} wsgi_run_once

用於 @code{wsgi.run_once} 環境變數的值。在 @ref{1c9c,,BaseHandler} 中預設為 false，但 @ref{3da8,,CGIHandler} 預設將其設置為 true。
@end deffn

@geindex os_environ (wsgiref.handlers.BaseHandler 的屬性)
@anchor{library/wsgiref wsgiref handlers BaseHandler os_environ}@anchor{3db7}
@deffn {屬性} os_environ

預設環境變數包含在每一個請求的 WSGI 環境中。預設情況下，這是在載入 @ref{11f,,wsgiref.handlers} 時的 @code{os.environ} 副本，但子類別可以在類別或實例層級建立自己的副本。注意字典應該被視為唯讀，因為預設值在多個類別與實例中共享。
@end deffn

@geindex server_software (wsgiref.handlers.BaseHandler 的屬性)
@anchor{library/wsgiref wsgiref handlers BaseHandler server_software}@anchor{3db8}
@deffn {屬性} server_software

如果設置 @ref{3db9,,origin_server} 屬性，則此屬性的值將用於設置預設的 @code{SERVER_SOFTWARE} WSGI 環境變數，並且還將用於設置 HTTP 回應中的預設 @code{Server:} 標頭。對於不是 HTTP origin 伺服器的處置程式（例如 @ref{3da9,,BaseCGIHandler} 和 @ref{3da8,,CGIHandler}），此屬性將被忽略。


在 3.3 版的變更: 將術語 "Python" 替換為特定實作的術語，如 "CPython"、"Jython" 等。

@end deffn

@geindex get_scheme() (wsgiref.handlers.BaseHandler 的方法)
@anchor{library/wsgiref wsgiref handlers BaseHandler get_scheme}@anchor{3dba}
@deffn {方法} get_scheme ()

回傳用於目前請求的 URL scheme。預設的實作使用 @ref{123,,wsgiref.util} 中的 @code{guess_scheme()} 函式去猜測 scheme 是 "http" 或是 "https"，基於目前請求的 @code{environ} 變數。
@end deffn

@geindex setup_environ() (wsgiref.handlers.BaseHandler 的方法)
@anchor{library/wsgiref wsgiref handlers BaseHandler setup_environ}@anchor{3dbb}
@deffn {方法} setup_environ ()

將 @code{environ} 屬性設置為完全填充的 WSGI 環境。預設的實作使用上述所有方法和屬性，以及 @ref{3dac,,get_stdin()}、@ref{3dad,,get_stderr()} 和 @ref{3dae,,add_cgi_vars()} 方法以及 @ref{3dbc,,wsgi_file_wrapper} 屬性。如果不呈現它也會插入一個 @code{SERVER_SOFTWARE} 關鍵字，只要 @ref{3db9,,origin_server} 屬性是一個 true 值並且 @ref{3db8,,server_software} 屬性被設置。
@end deffn

用於自定義例外處理的屬性和方法：

@geindex log_exception() (wsgiref.handlers.BaseHandler 的方法)
@anchor{library/wsgiref wsgiref handlers BaseHandler log_exception}@anchor{3dbd}
@deffn {方法} log_exception (exc_info)

將 `exc_info' 元組記錄到伺服器日誌中。`exc_info' 是一個 @code{(type, value, traceback)} 元組。預設實作只是將追蹤資訊寫入到請求的 @code{wsgi.errors} 串流中並刷新它。子類別可以覆蓋此方法以更改格式或重新定向輸出，將追蹤資訊發送給管理員，或執行其他被認為合適的操作。
@end deffn

@geindex traceback_limit (wsgiref.handlers.BaseHandler 的屬性)
@anchor{library/wsgiref wsgiref handlers BaseHandler traceback_limit}@anchor{3dbe}
@deffn {屬性} traceback_limit

預設的 @ref{3dbd,,log_exception()} 方法追蹤輸出中包含的最大幀數 。如果為 @code{None}，則包含所有幀。
@end deffn

@geindex error_output() (wsgiref.handlers.BaseHandler 的方法)
@anchor{library/wsgiref wsgiref handlers BaseHandler error_output}@anchor{3dbf}
@deffn {方法} error_output (environ, start_response)

這個方法是一個為使用者去產生錯誤頁面的 WSGI 應用程式。只有在標頭傳送給用戶端前如果發生錯誤才會被叫用。

此方法使用 @code{sys.exception()} 存取目前的錯誤，當呼叫它（如 
@geindex Python Enhancement Proposals; PEP 3333
PEP 3333@footnote{https://peps.python.org/pep-3333/} 的 "Error Handling" 部分所描述）時應該傳遞資訊給 `start_response'。特別是 `start_response' 可呼叫物件應該遵循 @ref{3d9c,,StartResponse} 協定。

預設的實作只是使用 @ref{3dc0,,error_status}、@ref{3dc1,,error_headers} 和 @ref{3dc2,,error_body} 屬性產生輸出頁面。子類別可以覆蓋此方法以生成更動態的錯誤輸出。

然而，從安全的角度並不建議向任何普通使用者顯示診斷資訊；理想情況下，你應該需要採取特殊措施才能啟用診斷輸出，這就是預設實作不包括任何診斷資訊的原因。
@end deffn

@geindex error_status (wsgiref.handlers.BaseHandler 的屬性)
@anchor{library/wsgiref wsgiref handlers BaseHandler error_status}@anchor{3dc0}
@deffn {屬性} error_status

用於錯誤回應的 HTTP 狀態。這應該是一個按照 
@geindex Python Enhancement Proposals; PEP 3333
PEP 3333@footnote{https://peps.python.org/pep-3333/} 定義的狀態字串；預設為 500 狀態碼和訊息。
@end deffn

@geindex error_headers (wsgiref.handlers.BaseHandler 的屬性)
@anchor{library/wsgiref wsgiref handlers BaseHandler error_headers}@anchor{3dc1}
@deffn {屬性} error_headers

用於錯誤回應的 HTTP 標頭。這應該是一個 WSGI 回應標頭的串列（@code{(name, value)} 元組），如 
@geindex Python Enhancement Proposals; PEP 3333
PEP 3333@footnote{https://peps.python.org/pep-3333/} 中所描述。預設串列只設置內容種類為 @code{text/plain}。
@end deffn

@geindex error_body (wsgiref.handlers.BaseHandler 的屬性)
@anchor{library/wsgiref wsgiref handlers BaseHandler error_body}@anchor{3dc2}
@deffn {屬性} error_body

錯誤回應的主體。這應該是一個 HTTP 回應內容的位元組字串。預設為純文字 "A server error occurred. Please contact the administrator."
@end deffn

用於 
@geindex Python Enhancement Proposals; PEP 3333
PEP 3333@footnote{https://peps.python.org/pep-3333/} 中的 "Optional Platform-Specific File Handling" 功能的方法和屬性：

@geindex wsgi_file_wrapper (wsgiref.handlers.BaseHandler 的屬性)
@anchor{library/wsgiref wsgiref handlers BaseHandler wsgi_file_wrapper}@anchor{3dbc}
@deffn {屬性} wsgi_file_wrapper

一個 @code{wsgi.file_wrapper} 工廠函式（factory），與 @ref{3d96,,wsgiref.types.FileWrapper} 相容，或者為 @code{None}。這個屬性的預設值是 @ref{937,,wsgiref.util.FileWrapper} 類別。
@end deffn

@geindex sendfile() (wsgiref.handlers.BaseHandler 的方法)
@anchor{library/wsgiref wsgiref handlers BaseHandler sendfile}@anchor{3dc3}
@deffn {方法} sendfile ()

覆蓋以實作特定平台的檔案傳輸。只有當應用程式的回傳值是由 @ref{3dbc,,wsgi_file_wrapper} 屬性指定的類別實例時才會呼叫此方法。如果它能夠成功傳輸檔案應該回傳一個 true 值，以便不執行預設的傳輸程式碼。該方法的預設實作只回傳一個 false 值。
@end deffn

其他方法和屬性：

@geindex origin_server (wsgiref.handlers.BaseHandler 的屬性)
@anchor{library/wsgiref wsgiref handlers BaseHandler origin_server}@anchor{3db9}
@deffn {屬性} origin_server

這個屬性應該被設置為 true 值，如果處理程式（handler）的 @ref{3daf,,_write()} 和 @ref{3db0,,_flush()} 被用於直接與用戶端通訊，而不是透過 CGI-like 的閘道協定希望 HTTP 狀態在特殊的 @code{Status:} 標頭中。

這個屬性在 @ref{3da9,,BaseCGIHandler} 預設值為 true，但是在 @ref{3da9,,BaseCGIHandler} 和 @ref{3da8,,CGIHandler} 為 false。
@end deffn

@geindex http_version (wsgiref.handlers.BaseHandler 的屬性)
@anchor{library/wsgiref wsgiref handlers BaseHandler http_version}@anchor{3dc4}
@deffn {屬性} http_version

如果 @ref{3db9,,origin_server} 為 true，則此字串屬性用於設定傳送給用戶端的回應的 HTTP 版本。預設為 @code{"1.0"}。
@end deffn
@end deffn

@geindex read_environ() (於 wsgiref.handlers 模組中)
@anchor{library/wsgiref wsgiref handlers read_environ}@anchor{13ba}
@deffn {函式} wsgiref.handlers.read_environ ()

從 @code{os.environ} 轉碼 CGI 變數到 
@geindex Python Enhancement Proposals; PEP 3333
PEP 3333@footnote{https://peps.python.org/pep-3333/} 中的 "bytes in unicode" 字串，並回傳一個新字典。這個函式被 @ref{3da8,,CGIHandler} 和 @ref{3daa,,IISCGIHandler} 使用來直接替代 @code{os.environ}，在所有平台和使用 Python 3 的網頁伺服器上不一定符合 WSGI 標準，具體來說，在 OS 的實際環境是 Unicode（例如 Windows）的情況下，或者在環境是位元組的情況下，但 Python 用於解碼它的系統編碼不是 ISO-8859-1 （例如使用 UTF-8 的 Unix 系統）。

如果你自己正在實作 CGI-based 處理程式（handler），你可能想要使用這個函式來替換單純直接從 @code{os.environ} 中複製值。


在 3.2 版被加入.

@end deffn

@node wsgiref types -- 用於靜態型別檢查的 WSGI 型別,範例<35>,wsgiref handlers -- 伺服器 / 閘道基本類別,wsgiref --- WSGI 工具與參考實作
@anchor{library/wsgiref module-wsgiref types}@anchor{122}@anchor{library/wsgiref wsgiref-types-wsgi-types-for-static-type-checking}@anchor{3dc5}
@subsubsection @code{wsgiref.types} -- 用於靜態型別檢查的 WSGI 型別


@geindex module; wsgiref.types

這個模組提供在 
@geindex Python Enhancement Proposals; PEP 3333
PEP 3333@footnote{https://peps.python.org/pep-3333/} 中所描述的各種用於靜態型別檢查的型別。


在 3.11 版被加入.


@geindex StartResponse (wsgiref.types 中的類別)
@anchor{library/wsgiref wsgiref types StartResponse}@anchor{3d9c}
@deffn {類別} wsgiref.types.StartResponse

一個描述 
@geindex Python Enhancement Proposals; PEP 3333#the-start-response-callable
start_response()@footnote{https://peps.python.org/pep-3333/#the-start-response-callable} 可呼叫物件的 @ref{565,,typing.Protocol} (
@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{3d8f}
@deffn {資料} wsgiref.types.WSGIEnvironment

一個描述 WSGI 環境字典的型別別名。
@end deffn

@geindex WSGIApplication (於 wsgiref.types 模組中)
@anchor{library/wsgiref wsgiref types WSGIApplication}@anchor{3dc6}
@deffn {資料} wsgiref.types.WSGIApplication

一個描述 WSGI 應用程式可呼叫物件的型別別名。
@end deffn

@geindex InputStream (wsgiref.types 中的類別)
@anchor{library/wsgiref wsgiref types InputStream}@anchor{3db2}
@deffn {類別} wsgiref.types.InputStream

一個描述 
@geindex Python Enhancement Proposals; PEP 3333#input-and-error-streams
WSGI 輸入串流@footnote{https://peps.python.org/pep-3333/#input-and-error-streams}的 @ref{565,,typing.Protocol}。
@end deffn

@geindex ErrorStream (wsgiref.types 中的類別)
@anchor{library/wsgiref wsgiref types ErrorStream}@anchor{3db3}
@deffn {類別} wsgiref.types.ErrorStream

一個描述 
@geindex Python Enhancement Proposals; PEP 3333#input-and-error-streams
WSGI 錯誤串流@footnote{https://peps.python.org/pep-3333/#input-and-error-streams}的 @ref{565,,typing.Protocol}。
@end deffn

@geindex FileWrapper (wsgiref.types 中的類別)
@anchor{library/wsgiref wsgiref types FileWrapper}@anchor{3d96}
@deffn {類別} wsgiref.types.FileWrapper

一個描述
@geindex Python Enhancement Proposals; PEP 3333#optional-platform-specific-file-handling
檔案包裝器@footnote{https://peps.python.org/pep-3333/#optional-platform-specific-file-handling}的 @ref{565,,typing.Protocol}。請參閱 @ref{937,,wsgiref.util.FileWrapper} 來瞭解此協定的具體實作。
@end deffn

@node 範例<35>,,wsgiref types -- 用於靜態型別檢查的 WSGI 型別,wsgiref --- WSGI 工具與參考實作
@anchor{library/wsgiref examples}@anchor{3dc7}
@subsubsection 範例


This is a working "Hello World" WSGI application, where the `start_response'
callable should follow the @ref{3d9c,,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

提供目前目錄的 WSGI 應用程式範例，並接受命令列上的可選目錄和埠號（預設：8000）：

@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 處理模組,urllib request --- 用來開啟 URLs 的可擴充函式庫,wsgiref --- WSGI 工具與參考實作,網路協定 Internet protocols 及支援
@anchor{library/urllib doc}@anchor{3dc8}@anchor{library/urllib module-urllib}@anchor{10e}@anchor{library/urllib translation-repo}@anchor{3dc9}@anchor{library/urllib urllib-url-handling-modules}@anchor{3dca}
@subsection @code{urllib} --- URL 處理模組


@geindex module; urllib

`原始碼：'Lib/urllib/@footnote{https://github.com/python/cpython/tree/3.14/Lib/urllib/}


__________________________________________________________________


@code{urllib} 是一個蒐集了許多處理 URLs 的 module（模組）的 package（套件）：


@itemize *

@item 
@ref{111,,urllib.request} 用來開啟和讀取 URLs

@item 
@ref{10f,,urllib.error} 包含了 @ref{111,,urllib.request} 所引發的例外

@item 
@ref{110,,urllib.parse} 用來剖析 URLs

@item 
@ref{113,,urllib.robotparser} 用來剖析 @code{robots.txt} 檔案
@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 --- 用來開啟 URLs 的可擴充函式庫,urllib response --- Response classes used by urllib,urllib --- URL 處理模組,網路協定 Internet protocols 及支援
@anchor{library/urllib request doc}@anchor{3dcb}@anchor{library/urllib request module-urllib request}@anchor{111}@anchor{library/urllib request translation-repo}@anchor{3dcc}@anchor{library/urllib request urllib-request-extensible-library-for-opening-urls}@anchor{3dcd}
@subsection @code{urllib.request} --- 用來開啟 URLs 的可擴充函式庫


@geindex module; urllib.request

`原始碼：'Lib/urllib/request.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/urllib/request.py}


__________________________________________________________________


@ref{111,,urllib.request} module（模組）定義了一些函式與 class（類別）用以開啟 URLs（大部分是 HTTP），並處理各式複雜情況如：basic 驗證與 digest 驗證、重新導向、cookies。


@subsubheading 也參考


有關於更高階的 HTTP 用戶端介面，推薦使用 Requests 套件@footnote{https://requests.readthedocs.io/en/master/}。


@cartouche
@quotation 警告 
On macOS it is unsafe to use this module in programs using
@ref{4b0,,os.fork()} because the @ref{3dce,,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{2006,,可用性}: not WASI.

此模組在 WebAssembly 平台上不起作用或無法使用。更多資訊請參閱 @ref{1a99,,WebAssembly 平台}。

@ref{111,,urllib.request} module 定義下列函式：

@geindex urlopen() (於 urllib.request 模組中)
@anchor{library/urllib request urllib request urlopen}@anchor{306}
@deffn {函式} urllib.request.urlopen (url, data=None[, timeout], *, context=None)

打開 `url'，其值可以是一個包含有效且適當編碼 URL 的字串或是一個 @ref{11d3,,Request} 物件。

`data' 必須是一個包含傳送給伺服器額外資料的物件，若不需要傳送額外資料則指定為 @code{None}。更多細節請見 @ref{11d3,,Request}。

urllib.request module 使用 HTTP/1.1 並包含 @code{Connection:close} header（標頭）在其 HTTP 請求中。

透過選擇性參數 `timeout' 來指定 blocking operations（阻塞性操作，如：嘗試連接）的 timeout（超時時間），以秒為單位。若沒有指定值，則會使用全域預設超時時間設定。實際上，此參數僅作用於 HTTP、HTTPS 以及 FTP 的連接。

若 `context' 有被指定時，它必須是一個 @ref{355,,ssl.SSLContext} 的實例並描述著各種 SSL 選項。更多細節請見 @ref{d2e,,HTTPSConnection}。

這個函式總是回傳一個可作為 @ref{1e1,,context manager} 使用的物件，並有著特性 (property) `url'、`headers' 與 `status'。欲知更多這些特性細節請參見 @ref{3dcf,,urllib.response.addinfourl}。

對於 HTTP 與 HTTPS 的 URLs，這個函式回傳一個稍有不同的 @ref{12cf,,http.client.HTTPResponse} 物件。除了上述提到的三個方法外，另有 msg 屬性並有著與 @ref{3dd0,,reason} 相同的資訊 --- 由伺服器回傳的原因敘述 (reason phrase)，而不是在 @ref{12cf,,HTTPResponse} 文件中提到的回應 headers。

對於 FTP、檔案及資料的 URLs，這個函式會回傳一個 @ref{3dcf,,urllib.response.addinfourl} 物件。

當遇到協定上的錯誤時會引發 @ref{2be,,URLError}。

請注意若沒有 handler 處理請求時，@code{None} 值將會被回傳。（即使有預設的全域類別 @ref{3dd1,,OpenerDirector} 使用 @ref{3dd2,,UnknownHandler} 來確保這種情況不會發生）

另外，若有偵測到代理服務的設定（例如當 @code{*_proxy} 環境變數像是：:envvar:!http_proxy` 有被設置時），@ref{1c7e,,ProxyHandler} 會被預設使用以確保請求有透過代理服務來處理。

Python 2.6 或更早版本的遺留函式 @code{urllib.urlopen} 已經不再被維護；新函式 @ref{306,,urllib.request.urlopen()} 對應到舊函式 @code{urllib2.urlopen}。有關代理服務的處理，以往是透過傳遞 dictionary（字典）參數給 @code{urllib.urlopen} 來取得的，現在則可以透過 @ref{1c7e,,ProxyHandler} 物件來取得。

預設的 opener 會觸發一個 @ref{1b70,,auditing event} @code{urllib.Request} 與其從請求物件中所獲得的引數 @code{fullurl}、@code{data}、@code{headers}、@code{method}。


在 3.2 版的變更: 新增 `cafile' 與 `capath'。

HTTPS 虛擬主機 (virtual hosts) 現已支援，只要 @ref{388c,,ssl.HAS_SNI} 的值為 true。

`data' 可以是一個可疊代物件。



在 3.3 版的變更: `cadefault' 被新增。



在 3.4.3 版的變更: `context' 被新增。



在 3.10 版的變更: 當 `context' 沒有被指定時，HTTPS 連線現在會傳送一個帶有協定指示器 @code{http/1.1} 的 ALPN 擴充 (extension)。自訂的 `context' 應該利用 @ref{105f,,set_alpn_protocols()} 來自行設定 ALPN 協定。



在 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{3dd3}
@deffn {函式} urllib.request.install_opener (opener)

安裝一個 @ref{3dd1,,OpenerDirector} 實例作為預設的全域 opener。僅在當你想要讓 urlopen 使用該 opener 時安裝一個 opener，否則的話應直接呼叫 @ref{11d7,,OpenerDirector.open()} 而非 @ref{306,,urlopen()}。程式碼不會檢查 class 是否真的為 @ref{3dd1,,OpenerDirector}，而是任何具有正確介面的 class 都能適用。
@end deffn

@geindex build_opener() (於 urllib.request 模組中)
@anchor{library/urllib request urllib request build_opener}@anchor{308}
@deffn {函式} urllib.request.build_opener ([handler, ...])

回傳一個 @ref{3dd1,,OpenerDirector} 實例，以給定的順序把 handlers 串接起來。`handler's 可以是 @ref{3dd4,,BaseHandler} 的實例，亦或是 @ref{3dd4,,BaseHandler} 的 subclasses（這個情況下必須有不帶參數的建構函式能夠被呼叫）。以下 classes 的實例順位會在 `handler's 之前，除非 `handler's 已經包含它們，是它們的實例，或是它們的 subclasses：@ref{1c7e,,ProxyHandler}（如果代理服務設定被偵測到）、@ref{3dd2,,UnknownHandler}、@ref{ef3,,HTTPHandler}、@ref{3dd5,,HTTPDefaultErrorHandler}、@ref{3dd6,,HTTPRedirectHandler}、@ref{3dd7,,FTPHandler}、@ref{3dd8,,FileHandler}、@ref{3dd9,,HTTPErrorProcessor}。

如果 Python 安裝時已帶有 SSL 支援（如果 @ref{d5,,ssl} module 能夠被 import），則 @ref{1424,,HTTPSHandler} 也在上述 class 之中。

一個 @ref{3dd4,,BaseHandler} 的 subclass 可能透過改變其 @code{handler_order} 屬性來調整它在 handlers list 中的位置。
@end deffn

@geindex pathname2url() (於 urllib.request 模組中)
@anchor{library/urllib request urllib request pathname2url}@anchor{2bf}
@deffn {函式} urllib.request.pathname2url (path, *, add_scheme=False)

Convert the given local path to a @code{file:} URL. This function uses
@ref{d97,,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{2c0,,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{2bd}
@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{1a41,,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{2be,,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{384c,,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{2be,,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{2c0,,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{2be,,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{3dce}
@deffn {函式} urllib.request.getproxies ()

這個輔助函式 (helper function) 回傳一個代理伺服器 URL mappings（對映）的 dictionary。在所有的作業系統中，它首先掃描環境中有著 @code{<scheme>_proxy} 名稱的變數（忽略大小寫的），如果找不到的話就會在 macOS 中的系統設定 (System Configuration) 或是 Windows 系統中的 Windows Systems Registry 尋找代理服務設定。如果大小寫的環境變數同時存在且值有不同，小寫的環境變數會被選用。

@cartouche
@quotation 備註 
如果環境變數 @code{REQUEST_METHOD} 有被設置（通常這代表著你的 script 是運行在一個共用閘道介面 (CGI) 環境中），那麼環境變數 @code{HTTP_PROXY} （大寫的 @code{_PROXY}）將被忽略。這是因為變數可以透過使用 "Proxy:" HTTP header 被注入。如果需要在共用閘道介面環境中使用 HTTP 代理服務，可以明確使用 @code{ProxyHandler}，亦或是確認變數名稱是小寫的（或至少 @code{_proxy} 後綴是小寫的）。
@end quotation
@end cartouche
@end deffn

提供了以下的 classes：

@geindex Request (urllib.request 中的類別)
@anchor{library/urllib request urllib request Request}@anchor{11d3}
@deffn {類別} urllib.request.Request (url, data=None, headers=@{@}, origin_req_host=None, unverifiable=False, method=None)

這個 class 是一個 URL 請求的抽象 class。

`url' 是一個包含有效且適當編碼的 URL 字串。

`data' 必須是一個包含要送到伺服器的附加資料的物件，若不需帶附加資料則其值應為 @code{None}。目前 HTTP 請求是唯一有使用 `data' 參數的，其支援的物件型別包含位元組、類檔案物件 (file-like objects)、以及可疊代的類位元組串物件 (bytes-like objects)。如果沒有提供 @code{Content-Length} 及 @code{Transfer-Encoding} headers 欄位，@ref{ef3,,HTTPHandler} 將會根據 `data' 的型別設置這些 header。@code{Content-Length} 會被用來傳送位元組串物件，而 
@geindex RFC; RFC 7230
RFC 7230@footnote{https://datatracker.ietf.org/doc/html/rfc7230.html} 章節 3.3.1 所定義的 @code{Transfer-Encoding: chunked} 則會被用來傳送檔案或是其它可疊代物件 (iterables)。

對於一個 HTTP POST 請求方法，`data' 應為一個標準 @code{application/x-www-form-urlencoded} 格式的 buffer。@ref{1090,,urllib.parse.urlencode()} 方法接受一個 mapping 或是 sequence（序列）的 2-tuples，並回傳一個對應格式的 ASCII 字串。在被作為 `data' 參數前它應該被編碼成位元組串。

`headers' 必須是一個 dictionary，並會被視為如同每對 key 和 value 作為引數來呼叫 @ref{3dda,,add_header()}。經常用於「偽裝」 @code{User-Agent}  header 的值，這個 header 是用來讓一個瀏覽器向伺服器表明自己的身分 --- 有些 HTTP 伺服器僅允許來自普通瀏覽器的請求，而不接受來自程式腳本的請求。例如，Mozilla Firefox 會將 header 的值設為 @code{"Mozilla/5.0 (X11; U; Linux i686) Gecko/20071127 Firefox/2.0.0.11"}，而 @ref{10e,,urllib} 的值則是 @code{"Python-urllib/2.6"}（在 Python 2.6 上）。所有 header 的鍵都會以 camel case（駝峰式大小寫）來傳送。

當有給定 `data' 引數時，一個適當的 @code{Content-Type} header 應該被設置。如果這個 header 沒有被提供且 `data' 也不為 @code{None} 時，預設值 @code{Content-Type: application/x-www-form-urlencoded} 會被新增至請求中。

接下來的兩個引數的介紹提供給那些有興趣正確處理第三方 HTTP cookies 的使用者：

`origin_req_host' 應為原始傳輸互動的請求主機 (request-host)，如同在 
@geindex RFC; RFC 2965
RFC 2965@footnote{https://datatracker.ietf.org/doc/html/rfc2965.html} 中的定義。預設值為 @code{http.cookiejar.request_host(self)}。這是使用者發起的原始請求的主機名稱或是 IP 位址。例如當請求是要求一個 HTML 文件中的一個影像，則這個屬性應為請求包含影像頁面的請求主機。

`unverifiable' 應該標示一個請求是否是無法驗證的，如同在 
@geindex RFC; RFC 2965
RFC 2965@footnote{https://datatracker.ietf.org/doc/html/rfc2965.html} 中的定義。其預設值為 @code{False}。一個無法驗證的請求是指使用者沒有機會去批准請求的 URL，例如一個對於 HTML 文件中的影像所做的請求，而使用者沒有機會去批准是否能自動擷取影像，則這個值應該為 true。

`method' 應為一個標示 HTTP 請求方法的字串（例如：@code{'HEAD'}）。如果有提供值，則會被存在 @ref{11d4,,method} 屬性中且被 @ref{136a,,get_method()} 所使用。當 `data' 是 @code{None} 時，其預設值為 @code{'GET'}，否則預設值為 @code{'POST'}。Subclasses 可以透過設置其 @ref{11d4,,method} 屬性來設定不一樣的預設請求方法。

@cartouche
@quotation 備註 
如果資料物件無法重複提供其內容（例如一個檔案或是只能產生一次內容的可疊代物件）且請求因為 HTTP 重導向 (redirects) 或是 HTTP 驗證 (authentication) 而被重新嘗試傳送，則該請求不會正常運作。`data' 會接在 headers 之後被送至 HTTP 伺服器。此函式庫沒有支援 100-continue expectation。
@end quotation
@end cartouche


在 3.3 版的變更: 新增 @ref{11d4,,Request.method} 引數到 Request class。



在 3.4 版的變更: 能夠在 class 中設置預設的 @ref{11d4,,Request.method}。



在 3.6 版的變更: 如果 @code{Content-Length} 尚未被提供且 `data' 既不是 @code{None} 也不是一個位元組串物件，則不會觸發錯誤，並 fall back（後備）使用分塊傳輸編碼 (chunked transfer encoding)。

@end deffn

@geindex OpenerDirector (urllib.request 中的類別)
@anchor{library/urllib request urllib request OpenerDirector}@anchor{3dd1}
@deffn {類別} urllib.request.OpenerDirector

The @ref{3dd1,,OpenerDirector} class opens URLs via @ref{3dd4,,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{3dd4}
@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{3dd5}
@deffn {類別} urllib.request.HTTPDefaultErrorHandler

A class which defines a default handler for HTTP error responses; all responses
are turned into @ref{11d9,,HTTPError} exceptions.
@end deffn

@geindex HTTPRedirectHandler (urllib.request 中的類別)
@anchor{library/urllib request urllib request HTTPRedirectHandler}@anchor{3dd6}
@deffn {類別} urllib.request.HTTPRedirectHandler

A class to handle redirections.
@end deffn

@geindex HTTPCookieProcessor (urllib.request 中的類別)
@anchor{library/urllib request urllib request HTTPCookieProcessor}@anchor{3ddb}
@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{1c7e}
@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{3dce,,getproxies()}.
@end quotation
@end cartouche
@end deffn

@geindex HTTPPasswordMgr (urllib.request 中的類別)
@anchor{library/urllib request urllib request HTTPPasswordMgr}@anchor{3ddc}
@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{3ddd}
@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{108f}
@deffn {類別} urllib.request.HTTPPasswordMgrWithPriorAuth

A variant of @ref{3ddd,,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.


在 3.5 版被加入.

@end deffn

@geindex AbstractBasicAuthHandler (urllib.request 中的類別)
@anchor{library/urllib request urllib request AbstractBasicAuthHandler}@anchor{1b71}
@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{3ddc,,HTTPPasswordMgr}; refer to section
@ref{3dde,,HTTPPasswordMgr 物件} for information on the interface that must be
supported.  If `passwd_mgr' also provides @code{is_authenticated} and
@code{update_authenticated} methods (see
@ref{3ddf,,HTTPPasswordMgrWithPriorAuth 物件}), 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.


在 3.5 版被加入: 新增 @code{is_authenticated} 的支援。

@end deffn

@geindex HTTPBasicAuthHandler (urllib.request 中的類別)
@anchor{library/urllib request urllib request HTTPBasicAuthHandler}@anchor{3de0}
@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{3ddc,,HTTPPasswordMgr}; refer to
section @ref{3dde,,HTTPPasswordMgr 物件} for information on the interface that must
be supported. HTTPBasicAuthHandler will raise a @ref{2eb,,ValueError} when
presented with a wrong Authentication scheme.
@end deffn

@geindex ProxyBasicAuthHandler (urllib.request 中的類別)
@anchor{library/urllib request urllib request ProxyBasicAuthHandler}@anchor{3de1}
@deffn {類別} urllib.request.ProxyBasicAuthHandler (password_mgr=None)

Handle authentication with the proxy. `password_mgr', if given, should be
something that is compatible with @ref{3ddc,,HTTPPasswordMgr}; refer to section
@ref{3dde,,HTTPPasswordMgr 物件} for information on the interface that must be
supported.
@end deffn

@geindex AbstractDigestAuthHandler (urllib.request 中的類別)
@anchor{library/urllib request urllib request AbstractDigestAuthHandler}@anchor{1c34}
@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{3ddc,,HTTPPasswordMgr}; refer to section
@ref{3dde,,HTTPPasswordMgr 物件} 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{3de2}
@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{3ddc,,HTTPPasswordMgr}; refer to
section @ref{3dde,,HTTPPasswordMgr 物件} 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{2eb,,ValueError} when presented with an authentication scheme other than
Digest or Basic.


在 3.3 版的變更: Raise @ref{2eb,,ValueError} on unsupported Authentication Scheme.

@end deffn

@geindex ProxyDigestAuthHandler (urllib.request 中的類別)
@anchor{library/urllib request urllib request ProxyDigestAuthHandler}@anchor{3de3}
@deffn {類別} urllib.request.ProxyDigestAuthHandler (password_mgr=None)

Handle authentication with the proxy. `password_mgr', if given, should be
something that is compatible with @ref{3ddc,,HTTPPasswordMgr}; refer to section
@ref{3dde,,HTTPPasswordMgr 物件} for information on the interface that must be
supported.
@end deffn

@geindex HTTPHandler (urllib.request 中的類別)
@anchor{library/urllib request urllib request HTTPHandler}@anchor{ef3}
@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{1424}
@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{d2e,,http.client.HTTPSConnection}.


在 3.2 版的變更: 新增 `context' 與 `check_hostname'。

@end deffn

@geindex FileHandler (urllib.request 中的類別)
@anchor{library/urllib request urllib request FileHandler}@anchor{3dd8}
@deffn {類別} urllib.request.FileHandler

Open local files.
@end deffn

@geindex DataHandler (urllib.request 中的類別)
@anchor{library/urllib request urllib request DataHandler}@anchor{11d2}
@deffn {類別} urllib.request.DataHandler

Open data URLs.


在 3.4 版被加入.

@end deffn

@geindex FTPHandler (urllib.request 中的類別)
@anchor{library/urllib request urllib request FTPHandler}@anchor{3dd7}
@deffn {類別} urllib.request.FTPHandler

打開 FTP URLs。
@end deffn

@geindex CacheFTPHandler (urllib.request 中的類別)
@anchor{library/urllib request urllib request CacheFTPHandler}@anchor{19e8}
@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{3dd2}
@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{3dd9}
@deffn {類別} urllib.request.HTTPErrorProcessor

Process HTTP error responses.
@end deffn

@menu
* Request 物件:: 
* OpenerDirector 物件:: 
* BaseHandler 物件:: 
* HTTPRedirectHandler 物件:: 
* HTTPCookieProcessor 物件:: 
* ProxyHandler 物件:: 
* HTTPPasswordMgr 物件:: 
* HTTPPasswordMgrWithPriorAuth 物件:: 
* AbstractBasicAuthHandler 物件:: 
* HTTPBasicAuthHandler 物件:: 
* ProxyBasicAuthHandler 物件:: 
* AbstractDigestAuthHandler 物件:: 
* HTTPDigestAuthHandler 物件:: 
* ProxyDigestAuthHandler 物件:: 
* HTTPHandler 物件:: 
* HTTPSHandler 物件:: 
* FileHandler 物件:: 
* DataHandler 物件:: 
* FTPHandler 物件:: 
* CacheFTPHandler 物件:: 
* UnknownHandler 物件:: 
* HTTPErrorProcessor 物件:: 
* 範例: 範例<36>. 
* 遺留介面:: 
* urllib.request 限制: urllib request 限制. 

@end menu

@node Request 物件,OpenerDirector 物件,,urllib request --- 用來開啟 URLs 的可擴充函式庫
@anchor{library/urllib request id1}@anchor{3de4}@anchor{library/urllib request request-objects}@anchor{3de5}
@subsubsection Request 物件


The following methods describe @ref{11d3,,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{11d5}
@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
@ref{11d5,,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{3de6}
@deffn {屬性} Request.type

The URI scheme.
@end deffn

@geindex host (urllib.request.Request 的屬性)
@anchor{library/urllib request urllib request Request host}@anchor{3de7}
@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{3de8}
@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{3de9}
@deffn {屬性} Request.selector

The URI path.  If the @ref{11d3,,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{11d6}
@deffn {屬性} Request.data

The entity body for the request, or @code{None} if not specified.


在 3.4 版的變更: Changing value of @ref{11d6,,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{3dea}
@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{11d4}
@deffn {屬性} Request.method

The HTTP request method to use.  By default its value is @ref{87e,,None},
which means that @ref{136a,,get_method()} will do its normal computation
of the method to be used.  Its value can be set (thus overriding the default
computation in @ref{136a,,get_method()}) either by providing a default
value by setting it at the class level in a @ref{11d3,,Request} subclass, or by
passing a value in to the @ref{11d3,,Request} constructor via the `method'
argument.


在 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{136a}
@deffn {方法} Request.get_method ()

Return a string indicating the HTTP request method.  If
@ref{11d4,,Request.method} is not @code{None}, return its value, otherwise return
@code{'GET'} if @ref{11d6,,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{11d4,,Request.method}.

@end deffn

@geindex add_header() (urllib.request.Request 的方法)
@anchor{library/urllib request urllib request Request add_header}@anchor{3dda}
@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{3deb}
@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{3dec}
@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{11d8}
@deffn {方法} Request.remove_header (header)

Remove named header from the request instance (both from regular and
unredirected headers).


在 3.4 版被加入.

@end deffn

@geindex get_full_url() (urllib.request.Request 的方法)
@anchor{library/urllib request urllib request Request get_full_url}@anchor{3ded}
@deffn {方法} Request.get_full_url ()

Return the URL given in the constructor.


在 3.4 版的變更.


回傳 @ref{11d5,,Request.full_url}
@end deffn

@geindex set_proxy() (urllib.request.Request 的方法)
@anchor{library/urllib request urllib request Request set_proxy}@anchor{3dee}
@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{3def}
@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{3df0}
@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 物件,BaseHandler 物件,Request 物件,urllib request --- 用來開啟 URLs 的可擴充函式庫
@anchor{library/urllib request opener-director-objects}@anchor{3df1}@anchor{library/urllib request openerdirector-objects}@anchor{3df2}
@subsubsection OpenerDirector 物件


@ref{3dd1,,OpenerDirector} 物件有以下的方法：

@geindex add_handler() (urllib.request.OpenerDirector 的方法)
@anchor{library/urllib request urllib request OpenerDirector add_handler}@anchor{3df3}
@deffn {方法} OpenerDirector.add_handler (handler)

`handler' should be an instance of @ref{3dd4,,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.

更多資訊請見 @ref{3df4,,BaseHandler.<protocol>_open()}。

@item 
@code{http_error_<type>()} --- signal that the handler knows how to handle HTTP
errors with HTTP error code `type'.

更多資訊請見 @ref{3df5,,BaseHandler.http_error_<nnn>()}。

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

更多資訊請見 @ref{3df6,,BaseHandler.<protocol>_request()}。

@item 
@code{<protocol>_response()} --- signal that the handler knows how to
post-process `protocol' responses.

更多資訊請見 @ref{3df7,,BaseHandler.<protocol>_response()}。
@end itemize
@end deffn

@geindex open() (urllib.request.OpenerDirector 的方法)
@anchor{library/urllib request urllib request OpenerDirector open}@anchor{11d7}
@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{306,,urlopen()} (which simply calls the @ref{315,,open()}
method on the currently installed global @ref{3dd1,,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{3df8}
@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{306,,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{87e,,None}
value (ie. a response), or raises an exception (usually
@ref{2be,,URLError}).  Exceptions are allowed to propagate.

In fact, the above algorithm is first tried for methods named
@ref{3df9,,default_open()}.  If all such methods return @ref{87e,,None}, the algorithm
is repeated for methods named like @code{<protocol>_open()}.  If all such methods
return @ref{87e,,None}, the algorithm is repeated for methods named
@ref{3dfa,,unknown_open()}.

Note that the implementation of these methods may involve calls of the parent
@ref{3dd1,,OpenerDirector} instance's @ref{11d7,,open()} and
@ref{3df8,,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 物件,HTTPRedirectHandler 物件,OpenerDirector 物件,urllib request --- 用來開啟 URLs 的可擴充函式庫
@anchor{library/urllib request base-handler-objects}@anchor{3dfb}@anchor{library/urllib request basehandler-objects}@anchor{3dfc}
@subsubsection BaseHandler 物件


@ref{3dd4,,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{3dfd}
@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{3dfe}
@deffn {方法} BaseHandler.close ()

Remove any parents.
@end deffn

The following attribute and methods should only be used by classes derived from
@ref{3dd4,,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{3dff}
@deffn {屬性} BaseHandler.parent

A valid @ref{3dd1,,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{3df9}
@deffn {方法} BaseHandler.default_open (req)

This method is `not' defined in @ref{3dd4,,BaseHandler}, but subclasses should
define it if they want to catch all URLs.

This method, if implemented, will be called by the parent
@ref{3dd1,,OpenerDirector}.  It should return a file-like object as described in
the return value of the @ref{11d7,,open()} method of @ref{3dd1,,OpenerDirector}, or @code{None}.
It should raise @ref{2be,,URLError}, unless a truly exceptional
thing happens (for example, @ref{181e,,MemoryError} should not be mapped to
@ref{2be,,URLError}).

This method will be called before any protocol-specific open method.
@end deffn

@anchor{library/urllib request protocol-open}@anchor{3df4}
@deffn {方法} BaseHandler.<protocol>_open(req)

This method is `not' defined in @ref{3dd4,,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{3dd1,,OpenerDirector}.
Return values should be the same as for  @ref{3df9,,default_open()}.
@end deffn

@geindex unknown_open() (urllib.request.BaseHandler 的方法)
@anchor{library/urllib request urllib request BaseHandler unknown_open}@anchor{3dfa}
@deffn {方法} BaseHandler.unknown_open (req)

This method is `not' defined in @ref{3dd4,,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{3dff,,parent}
@ref{3dd1,,OpenerDirector}.  Return values should be the same as for
@ref{3df9,,default_open()}.
@end deffn

@geindex http_error_default() (urllib.request.BaseHandler 的方法)
@anchor{library/urllib request urllib request BaseHandler http_error_default}@anchor{3e00}
@deffn {方法} BaseHandler.http_error_default (req, fp, code, msg, hdrs)

This method is `not' defined in @ref{3dd4,,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{3dd1,,OpenerDirector} getting
the error, and should not normally be called in other circumstances.

@ref{3dd1,,OpenerDirector} 會以五個位置引數呼叫此方法：


@enumerate 

@item 
一個 @ref{11d3,,Request} 物件

@item 
一個類檔案物件，包含 HTTP 錯誤主體，

@item 
HTTP 錯誤的三位數代號字串，

@item 
HTTP 錯誤代號的使用者可見解釋字串，以及

@item 
HTTP 錯誤的標頭，為一個對映物件。
@end enumerate

Return values and exceptions raised should be the same as those of
@ref{306,,urlopen()}.
@end deffn

@anchor{library/urllib request http-error-nnn}@anchor{3df5}
@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{3dd4,,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{3e00,,http_error_default()}.
@end deffn

@anchor{library/urllib request protocol-request}@anchor{3df6}
@deffn {方法} BaseHandler.<protocol>_request(req)

This method is `not' defined in @ref{3dd4,,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{3dd1,,OpenerDirector}.
`req' will be a @ref{11d3,,Request} object. The return value should be a
@ref{11d3,,Request} object.
@end deffn

@anchor{library/urllib request protocol-response}@anchor{3df7}
@deffn {方法} BaseHandler.<protocol>_response(req, response)

This method is `not' defined in @ref{3dd4,,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{3dd1,,OpenerDirector}.
`req' will be a @ref{11d3,,Request} object. `response' will be an object
implementing the same interface as the return value of @ref{306,,urlopen()}.  The
return value should implement the same interface as the return value of
@ref{306,,urlopen()}.
@end deffn

@node HTTPRedirectHandler 物件,HTTPCookieProcessor 物件,BaseHandler 物件,urllib request --- 用來開啟 URLs 的可擴充函式庫
@anchor{library/urllib request http-redirect-handler}@anchor{3e01}@anchor{library/urllib request httpredirecthandler-objects}@anchor{3e02}
@subsubsection HTTPRedirectHandler 物件


@cartouche
@quotation 備註 
Some HTTP redirections require action from this module's client code.  If this
is the case, @ref{11d9,,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{11d9,,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{3e03}
@deffn {方法} HTTPRedirectHandler.redirect_request (req, fp, code, msg, hdrs, newurl)

Return a @ref{11d3,,Request} or @code{None} in response to a redirect. This is called
by the default implementations of the @code{http_error_30*()} methods when a
redirection is received from the server.  If a redirection should take place,
return a new @ref{11d3,,Request} to allow @code{http_error_30*()} to perform the
redirect to `newurl'.  Otherwise, raise @ref{11d9,,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{3e04}
@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{3dd1,,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{3e05}
@deffn {方法} HTTPRedirectHandler.http_error_302 (req, fp, code, msg, hdrs)

The same as @ref{3e04,,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{3e06}
@deffn {方法} HTTPRedirectHandler.http_error_303 (req, fp, code, msg, hdrs)

The same as @ref{3e04,,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{3e07}
@deffn {方法} HTTPRedirectHandler.http_error_307 (req, fp, code, msg, hdrs)

The same as @ref{3e04,,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{3e08}
@deffn {方法} HTTPRedirectHandler.http_error_308 (req, fp, code, msg, hdrs)

The same as @ref{3e04,,http_error_301()}, but called for the 'permanent redirect'
response. It does not allow changing the request method from @code{POST}
to @code{GET}.


在 3.11 版被加入.

@end deffn

@node HTTPCookieProcessor 物件,ProxyHandler 物件,HTTPRedirectHandler 物件,urllib request --- 用來開啟 URLs 的可擴充函式庫
@anchor{library/urllib request http-cookie-processor}@anchor{3e09}@anchor{library/urllib request httpcookieprocessor-objects}@anchor{3e0a}
@subsubsection HTTPCookieProcessor 物件


@ref{3ddb,,HTTPCookieProcessor} 實例有一個屬性：

@geindex cookiejar (urllib.request.HTTPCookieProcessor 的屬性)
@anchor{library/urllib request urllib request HTTPCookieProcessor cookiejar}@anchor{3e0b}
@deffn {屬性} HTTPCookieProcessor.cookiejar

存放 cookies 的 @ref{3e0c,,http.cookiejar.CookieJar}。
@end deffn

@node ProxyHandler 物件,HTTPPasswordMgr 物件,HTTPCookieProcessor 物件,urllib request --- 用來開啟 URLs 的可擴充函式庫
@anchor{library/urllib request proxy-handler}@anchor{3e0d}@anchor{library/urllib request proxyhandler-objects}@anchor{3e0e}
@subsubsection ProxyHandler 物件



@deffn {方法} ProxyHandler.<protocol>_open(request)

The @ref{1c7e,,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 物件,HTTPPasswordMgrWithPriorAuth 物件,ProxyHandler 物件,urllib request --- 用來開啟 URLs 的可擴充函式庫
@anchor{library/urllib request http-password-mgr}@anchor{3dde}@anchor{library/urllib request httppasswordmgr-objects}@anchor{3e0f}
@subsubsection HTTPPasswordMgr 物件


These methods are available on @ref{3ddc,,HTTPPasswordMgr} and
@ref{3ddd,,HTTPPasswordMgrWithDefaultRealm} objects.

@geindex add_password() (urllib.request.HTTPPasswordMgr 的方法)
@anchor{library/urllib request urllib request HTTPPasswordMgr add_password}@anchor{3e10}
@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{1af6}
@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{3ddd,,HTTPPasswordMgrWithDefaultRealm} objects, the realm @code{None} will be
searched if the given `realm' has no matching user/password.
@end deffn

@node HTTPPasswordMgrWithPriorAuth 物件,AbstractBasicAuthHandler 物件,HTTPPasswordMgr 物件,urllib request --- 用來開啟 URLs 的可擴充函式庫
@anchor{library/urllib request http-password-mgr-with-prior-auth}@anchor{3ddf}@anchor{library/urllib request httppasswordmgrwithpriorauth-objects}@anchor{3e11}
@subsubsection HTTPPasswordMgrWithPriorAuth 物件


This password manager extends @ref{3ddd,,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{3e12}
@deffn {方法} HTTPPasswordMgrWithPriorAuth.add_password (realm, uri, user, passwd, is_authenticated=False)

`realm', `uri', `user', `passwd' are as for
@ref{3e10,,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{3e13}
@deffn {方法} HTTPPasswordMgrWithPriorAuth.find_user_password (realm, authuri)

Same as for @ref{3ddd,,HTTPPasswordMgrWithDefaultRealm} objects
@end deffn

@geindex update_authenticated() (urllib.request.HTTPPasswordMgrWithPriorAuth 的方法)
@anchor{library/urllib request urllib request HTTPPasswordMgrWithPriorAuth update_authenticated}@anchor{3e14}
@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{1af7}
@deffn {方法} HTTPPasswordMgrWithPriorAuth.is_authenticated (self, authuri)

Returns the current state of the @code{is_authenticated} flag for
the given URI.
@end deffn

@node AbstractBasicAuthHandler 物件,HTTPBasicAuthHandler 物件,HTTPPasswordMgrWithPriorAuth 物件,urllib request --- 用來開啟 URLs 的可擴充函式庫
@anchor{library/urllib request abstract-basic-auth-handler}@anchor{3e15}@anchor{library/urllib request abstractbasicauthhandler-objects}@anchor{3e16}
@subsubsection AbstractBasicAuthHandler 物件


@geindex http_error_auth_reqed() (urllib.request.AbstractBasicAuthHandler 的方法)
@anchor{library/urllib request urllib request AbstractBasicAuthHandler http_error_auth_reqed}@anchor{3e17}
@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{11d3,,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 物件,ProxyBasicAuthHandler 物件,AbstractBasicAuthHandler 物件,urllib request --- 用來開啟 URLs 的可擴充函式庫
@anchor{library/urllib request http-basic-auth-handler}@anchor{3e18}@anchor{library/urllib request httpbasicauthhandler-objects}@anchor{3e19}
@subsubsection HTTPBasicAuthHandler 物件


@geindex http_error_401() (urllib.request.HTTPBasicAuthHandler 的方法)
@anchor{library/urllib request urllib request HTTPBasicAuthHandler http_error_401}@anchor{3e1a}
@deffn {方法} HTTPBasicAuthHandler.http_error_401 (req, fp, code, msg, hdrs)

Retry the request with authentication information, if available.
@end deffn

@node ProxyBasicAuthHandler 物件,AbstractDigestAuthHandler 物件,HTTPBasicAuthHandler 物件,urllib request --- 用來開啟 URLs 的可擴充函式庫
@anchor{library/urllib request proxy-basic-auth-handler}@anchor{3e1b}@anchor{library/urllib request proxybasicauthhandler-objects}@anchor{3e1c}
@subsubsection ProxyBasicAuthHandler 物件


@geindex http_error_407() (urllib.request.ProxyBasicAuthHandler 的方法)
@anchor{library/urllib request urllib request ProxyBasicAuthHandler http_error_407}@anchor{3e1d}
@deffn {方法} ProxyBasicAuthHandler.http_error_407 (req, fp, code, msg, hdrs)

Retry the request with authentication information, if available.
@end deffn

@node AbstractDigestAuthHandler 物件,HTTPDigestAuthHandler 物件,ProxyBasicAuthHandler 物件,urllib request --- 用來開啟 URLs 的可擴充函式庫
@anchor{library/urllib request abstract-digest-auth-handler}@anchor{3e1e}@anchor{library/urllib request abstractdigestauthhandler-objects}@anchor{3e1f}
@subsubsection AbstractDigestAuthHandler 物件


@geindex http_error_auth_reqed() (urllib.request.AbstractDigestAuthHandler 的方法)
@anchor{library/urllib request urllib request AbstractDigestAuthHandler http_error_auth_reqed}@anchor{3e20}
@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{11d3,,Request} object, and `headers' should be the
error headers.
@end deffn

@node HTTPDigestAuthHandler 物件,ProxyDigestAuthHandler 物件,AbstractDigestAuthHandler 物件,urllib request --- 用來開啟 URLs 的可擴充函式庫
@anchor{library/urllib request http-digest-auth-handler}@anchor{3e21}@anchor{library/urllib request httpdigestauthhandler-objects}@anchor{3e22}
@subsubsection HTTPDigestAuthHandler 物件


@geindex http_error_401() (urllib.request.HTTPDigestAuthHandler 的方法)
@anchor{library/urllib request urllib request HTTPDigestAuthHandler http_error_401}@anchor{3e23}
@deffn {方法} HTTPDigestAuthHandler.http_error_401 (req, fp, code, msg, hdrs)

Retry the request with authentication information, if available.
@end deffn

@node ProxyDigestAuthHandler 物件,HTTPHandler 物件,HTTPDigestAuthHandler 物件,urllib request --- 用來開啟 URLs 的可擴充函式庫
@anchor{library/urllib request proxy-digest-auth-handler}@anchor{3e24}@anchor{library/urllib request proxydigestauthhandler-objects}@anchor{3e25}
@subsubsection ProxyDigestAuthHandler 物件


@geindex http_error_407() (urllib.request.ProxyDigestAuthHandler 的方法)
@anchor{library/urllib request urllib request ProxyDigestAuthHandler http_error_407}@anchor{3e26}
@deffn {方法} ProxyDigestAuthHandler.http_error_407 (req, fp, code, msg, hdrs)

Retry the request with authentication information, if available.
@end deffn

@node HTTPHandler 物件,HTTPSHandler 物件,ProxyDigestAuthHandler 物件,urllib request --- 用來開啟 URLs 的可擴充函式庫
@anchor{library/urllib request http-handler-objects}@anchor{3e27}@anchor{library/urllib request httphandler-objects}@anchor{3e28}
@subsubsection HTTPHandler 物件


@geindex http_open() (urllib.request.HTTPHandler 的方法)
@anchor{library/urllib request urllib request HTTPHandler http_open}@anchor{3e29}
@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 物件,FileHandler 物件,HTTPHandler 物件,urllib request --- 用來開啟 URLs 的可擴充函式庫
@anchor{library/urllib request https-handler-objects}@anchor{3e2a}@anchor{library/urllib request httpshandler-objects}@anchor{3e2b}
@subsubsection HTTPSHandler 物件


@geindex https_open() (urllib.request.HTTPSHandler 的方法)
@anchor{library/urllib request urllib request HTTPSHandler https_open}@anchor{3e2c}
@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 物件,DataHandler 物件,HTTPSHandler 物件,urllib request --- 用來開啟 URLs 的可擴充函式庫
@anchor{library/urllib request file-handler-objects}@anchor{3e2d}@anchor{library/urllib request filehandler-objects}@anchor{3e2e}
@subsubsection FileHandler 物件


@geindex file_open() (urllib.request.FileHandler 的方法)
@anchor{library/urllib request urllib request FileHandler file_open}@anchor{3e2f}
@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{2be,,URLError} is raised.

@end deffn

@node DataHandler 物件,FTPHandler 物件,FileHandler 物件,urllib request --- 用來開啟 URLs 的可擴充函式庫
@anchor{library/urllib request data-handler-objects}@anchor{3e30}@anchor{library/urllib request datahandler-objects}@anchor{3e31}
@subsubsection DataHandler 物件


@geindex data_open() (urllib.request.DataHandler 的方法)
@anchor{library/urllib request urllib request DataHandler data_open}@anchor{3e32}
@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{2eb,,ValueError} in that case.
@end deffn

@node FTPHandler 物件,CacheFTPHandler 物件,DataHandler 物件,urllib request --- 用來開啟 URLs 的可擴充函式庫
@anchor{library/urllib request ftp-handler-objects}@anchor{3e33}@anchor{library/urllib request ftphandler-objects}@anchor{3e34}
@subsubsection FTPHandler 物件


@geindex ftp_open() (urllib.request.FTPHandler 的方法)
@anchor{library/urllib request urllib request FTPHandler ftp_open}@anchor{3e35}
@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 物件,UnknownHandler 物件,FTPHandler 物件,urllib request --- 用來開啟 URLs 的可擴充函式庫
@anchor{library/urllib request cacheftp-handler-objects}@anchor{3e36}@anchor{library/urllib request cacheftphandler-objects}@anchor{3e37}
@subsubsection CacheFTPHandler 物件


@ref{19e8,,CacheFTPHandler} objects are @ref{3dd7,,FTPHandler} objects with the
following additional methods:

@geindex setTimeout() (urllib.request.CacheFTPHandler 的方法)
@anchor{library/urllib request urllib request CacheFTPHandler setTimeout}@anchor{3e38}
@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{3e39}
@deffn {方法} CacheFTPHandler.setMaxConns (m)

Set maximum number of cached connections to `m'.
@end deffn

@node UnknownHandler 物件,HTTPErrorProcessor 物件,CacheFTPHandler 物件,urllib request --- 用來開啟 URLs 的可擴充函式庫
@anchor{library/urllib request unknown-handler-objects}@anchor{3e3a}@anchor{library/urllib request unknownhandler-objects}@anchor{3e3b}
@subsubsection UnknownHandler 物件


@geindex unknown_open() (urllib.request.UnknownHandler 的方法)
@anchor{library/urllib request urllib request UnknownHandler unknown_open}@anchor{3e3c}
@deffn {方法} UnknownHandler.unknown_open ()

Raise a @ref{2be,,URLError} exception.
@end deffn

@node HTTPErrorProcessor 物件,範例<36>,UnknownHandler 物件,urllib request --- 用來開啟 URLs 的可擴充函式庫
@anchor{library/urllib request http-error-processor-objects}@anchor{3e3d}@anchor{library/urllib request httperrorprocessor-objects}@anchor{3e3e}
@subsubsection HTTPErrorProcessor 物件


@geindex http_response() (urllib.request.HTTPErrorProcessor 的方法)
@anchor{library/urllib request urllib request HTTPErrorProcessor http_response}@anchor{3e3f}
@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{3df8,,OpenerDirector.error()}.
Eventually, @ref{3dd5,,HTTPDefaultErrorHandler} will raise an
@ref{11d9,,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{3e40}
@deffn {方法} HTTPErrorProcessor.https_response (request, response)

Process HTTPS error responses.

The behavior is same as @ref{3e3f,,http_response()}.
@end deffn

@node 範例<36>,遺留介面,HTTPErrorProcessor 物件,urllib request --- 用來開啟 URLs 的可擴充函式庫
@anchor{library/urllib request examples}@anchor{3e41}@anchor{library/urllib request urllib-request-examples}@anchor{3e42}
@subsubsection 範例


In addition to the examples below, more examples are given in
@ref{3e43,,如何使用 urllib 套件取得網路資源}.

This example gets the python.org main page and displays the first 300 bytes of
it:

@example
>>> import urllib.request
>>> with urllib.request.urlopen('http://www.python.org/') as f:
...     print(f.read(300))
...
b'<!doctype html>\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{1e1,,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{11d3,,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

使用基本 HTTP 認證：

@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{308,,build_opener()} provides many handlers by default, including a
@ref{1c7e,,ProxyHandler}.  By default, @ref{1c7e,,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{1c7e,,ProxyHandler} with one that uses
programmatically supplied proxy URLs, and adds proxy authorization support with
@ref{3de1,,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)
# 這次我們直接使用它而不安裝 OpenerDirector:
with opener.open('http://www.example.com/login.html') as f:
   print(f.read().decode('utf-8'))
@end example

添加 HTTP 標頭：

使用 @ref{11d3,,Request} 建構函式的 `headers' 引數，或：

@example
import urllib.request
req = urllib.request.Request('http://www.example.com/')
req.add_header('Referer', 'http://www.python.org/')
# 自訂預設的使用者代理標頭值：
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{3dd1,,OpenerDirector} automatically adds a @code{User-Agent} header to
every @ref{11d3,,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{11d3,,Request} is passed to @ref{306,,urlopen()} (or
@ref{11d7,,OpenerDirector.open()}).
@anchor{library/urllib request urllib-examples}@anchor{3e44}
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 遺留介面,urllib request 限制,範例<36>,urllib request --- 用來開啟 URLs 的可擴充函式庫
@anchor{library/urllib request legacy-interface}@anchor{3e45}
@subsubsection 遺留介面


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{307}
@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{306,,urlopen()} returned (for
a remote object). Exceptions are the same as for @ref{306,,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{1090,,urllib.parse.urlencode()} function.

@ref{307,,urlretrieve()} will raise @ref{3e46,,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{1c85}
@deffn {函式} urllib.request.urlcleanup ()

Cleans up temporary files that may have been left behind by previous
calls to @ref{307,,urlretrieve()}.
@end deffn

@node urllib request 限制,,遺留介面,urllib request --- 用來開啟 URLs 的可擴充函式庫
@anchor{library/urllib request urllib-request-restrictions}@anchor{3e47}
@subsubsection @code{urllib.request} 限制


@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{307,,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{306,,urlopen()} and @ref{307,,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{306,,urlopen()} or @ref{307,,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{71,,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{62,,ftplib} module.
@end itemize

@node urllib response --- Response classes used by urllib,urllib parse --- 將 URL 剖析成元件,urllib request --- 用來開啟 URLs 的可擴充函式庫,網路協定 Internet protocols 及支援
@anchor{library/urllib request module-urllib response}@anchor{112}@anchor{library/urllib request urllib-response-response-classes-used-by-urllib}@anchor{3e48}
@subsection @code{urllib.response} --- Response classes used by urllib


@geindex module; urllib.response

The @ref{112,,urllib.response} module defines functions and classes which define a
minimal file-like interface, including @code{read()} and @code{readline()}.
Functions defined by this module are used internally by the @ref{111,,urllib.request} module.
The typical response object is a @ref{3dcf,,urllib.response.addinfourl} instance:

@geindex addinfourl (urllib.response 中的類別)
@anchor{library/urllib request urllib response addinfourl}@anchor{3dcf}
@deffn {類別} urllib.response.addinfourl

@geindex url (urllib.response.addinfourl 的屬性)
@anchor{library/urllib request urllib response addinfourl url}@anchor{1855}
@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{3e49}
@deffn {屬性} headers

Returns the headers of the response in the form of an @ref{57a,,EmailMessage} instance.
@end deffn

@geindex status (urllib.response.addinfourl 的屬性)
@anchor{library/urllib request urllib response addinfourl status}@anchor{3e4a}
@deffn {屬性} status


在 3.9 版被加入.


伺服器回傳的狀態碼。
@end deffn

@geindex geturl() (urllib.response.addinfourl 的方法)
@anchor{library/urllib request urllib response addinfourl geturl}@anchor{3e4b}
@deffn {方法} geturl ()


在 3.9 版之後被棄用: 已被 @ref{1855,,url} 取代而棄用。

@end deffn

@geindex info() (urllib.response.addinfourl 的方法)
@anchor{library/urllib request urllib response addinfourl info}@anchor{3e4c}
@deffn {方法} info ()


在 3.9 版之後被棄用: 已被 @ref{3e49,,headers} 取代而棄用。

@end deffn

@geindex code (urllib.response.addinfourl 的屬性)
@anchor{library/urllib request urllib response addinfourl code}@anchor{3e4d}
@deffn {屬性} code


在 3.9 版之後被棄用: 已被 @ref{3e4a,,status} 取代而棄用。

@end deffn

@geindex getcode() (urllib.response.addinfourl 的方法)
@anchor{library/urllib request urllib response addinfourl getcode}@anchor{3e4e}
@deffn {方法} getcode ()


在 3.9 版之後被棄用: 已被 @ref{3e4a,,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 --- 將 URL 剖析成元件,urllib error --- urllib request 引發的例外類別,urllib response --- Response classes used by urllib,網路協定 Internet protocols 及支援
@anchor{library/urllib parse doc}@anchor{3e4f}@anchor{library/urllib parse module-urllib parse}@anchor{110}@anchor{library/urllib parse translation-repo}@anchor{3e50}@anchor{library/urllib parse urllib-parse-parse-urls-into-components}@anchor{3e51}
@subsection @code{urllib.parse} --- 將 URL 剖析成元件


@geindex module; urllib.parse

`原始碼：'Lib/urllib/parse.py@footnote{https://github.com/python/cpython/tree/3.14/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{18f0,,--with-app-store-compliance} option.

The @ref{110,,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 --- 將 URL 剖析成元件
@anchor{library/urllib parse url-parsing}@anchor{3e52}
@subsubsection URL Parsing


The URL parsing functions focus on splitting a URL string into its components,
or on combining URL components into a URL string.

@geindex urlparse() (於 urllib.parse 模組中)
@anchor{library/urllib parse urllib parse urlparse}@anchor{360}
@deffn {函式} urllib.parse.urlparse (urlstring, scheme='@w{'}, allow_fragments=True)

Parse a URL into six components, returning a 6-item @ref{857,,named tuple}.  This
corresponds to the general structure of a URL:
@code{scheme://netloc/path;parameters?query#fragment}.
Each tuple item is a string, possibly empty. The components are not broken up
into smaller parts (for example, the network location is a single string), and %
escapes are not expanded. The delimiters as shown above are not part of the
result, except for a leading slash in the `path' component, which is retained if
present.  For example:

@example
>>> from urllib.parse import urlparse
>>> urlparse("scheme://netloc/path;parameters?query#fragment")
ParseResult(scheme='scheme', netloc='netloc', path='/path;parameters', params='@w{'},
            query='query', fragment='fragment')
>>> o = urlparse("http://docs.python.org:80/3/library/urllib.parse.html?"
...              "highlight=params#url-parsing")
>>> o
ParseResult(scheme='http', netloc='docs.python.org:80',
            path='/3/library/urllib.parse.html', params='@w{'},
            query='highlight=params', fragment='url-parsing')
>>> o.scheme
'http'
>>> o.netloc
'docs.python.org:80'
>>> o.hostname
'docs.python.org'
>>> o.port
80
>>> o._replace(fragment="").geturl()
'http://docs.python.org:80/3/library/urllib.parse.html?highlight=params'
@end example

Following the syntax specifications in 
@geindex RFC; RFC 1808
RFC 1808@footnote{https://datatracker.ietf.org/doc/html/rfc1808.html}, urlparse recognizes
a netloc only if it is properly introduced by '//'.  Otherwise the
input is presumed to be a relative URL and thus to start with
a path component.

@example
>>> from urllib.parse import urlparse
>>> urlparse('//www.cwi.nl:80/%7Eguido/Python.html')
ParseResult(scheme='@w{'}, netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
            params='@w{'}, query='@w{'}, fragment='@w{'})
>>> urlparse('www.cwi.nl/%7Eguido/Python.html')
ParseResult(scheme='@w{'}, netloc='@w{'}, path='www.cwi.nl/%7Eguido/Python.html',
            params='@w{'}, query='@w{'}, fragment='@w{'})
>>> urlparse('help/Python.html')
ParseResult(scheme='@w{'}, netloc='@w{'}, path='help/Python.html', params='@w{'},
            query='@w{'}, fragment='@w{'})
@end example

The `scheme' argument gives the default addressing scheme, to be
used only if the URL does not specify one.  It should be the same type
(text or bytes) as `urlstring', except that the default value @code{'@w{'}} is
always allowed, and is automatically converted to @code{b'@w{'}} if appropriate.

If the `allow_fragments' argument is false, fragment identifiers are not
recognized.  Instead, they are parsed as part of the path, parameters
or query component, and @code{fragment} is set to the empty string in
the return value.

The return value is a @ref{857,,named tuple}, which means that its items can
be accessed by index or as named attributes, which are:


@multitable {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

屬性

@tab

Index

@tab

Value

@tab

Value if not present

@item

@code{scheme}

@tab

0

@tab

URL scheme specifier

@tab

`scheme' parameter

@item

@code{netloc}

@tab

1

@tab

Network location part

@tab

empty string

@item

@code{path}

@tab

2

@tab

Hierarchical path

@tab

empty string

@item

@code{params}

@tab

3

@tab

Parameters for last
path element

@tab

empty string

@item

@code{query}

@tab

4

@tab

Query component

@tab

empty string

@item

@code{fragment}

@tab

5

@tab

Fragment identifier

@tab

empty string

@item

@code{username}

@tab

@tab

User name

@tab

@ref{87e,,None}

@item

@code{password}

@tab

@tab

Password

@tab

@ref{87e,,None}

@item

@code{hostname}

@tab

@tab

Host name (lower case)

@tab

@ref{87e,,None}

@item

@code{port}

@tab

@tab

Port number as integer,
if present

@tab

@ref{87e,,None}

@end multitable


Reading the @code{port} attribute will raise a @ref{2eb,,ValueError} if
an invalid port is specified in the URL.  See section
@ref{3e53,,Structured Parse Results} for more information on the result object.

Unmatched square brackets in the @code{netloc} attribute will raise a
@ref{2eb,,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{2eb,,ValueError}. If the URL is
decomposed before parsing, no error will be raised.

As is the case with all named tuples, the subclass has a few additional methods
and attributes that are particularly useful. One such method is @code{_replace()}.
The @code{_replace()} method will return a new ParseResult object replacing specified
fields with new values.

@example
>>> from urllib.parse import urlparse
>>> u = urlparse('//www.cwi.nl:80/%7Eguido/Python.html')
>>> u
ParseResult(scheme='@w{'}, netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
            params='@w{'}, query='@w{'}, fragment='@w{'})
>>> u._replace(scheme='http')
ParseResult(scheme='http', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
            params='@w{'}, query='@w{'}, fragment='@w{'})
@end example

@cartouche
@quotation 警告 
@ref{360,,urlparse()} does not perform validation.  See @ref{3e54,,URL parsing security} for details.
@end quotation
@end cartouche


在 3.2 版的變更: 新增剖析 IPv6 URL 的能力。



在 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{2eb,,ValueError}, instead of
returning @ref{87e,,None}.



在 3.8 版的變更: Characters that affect netloc parsing under NFKC normalization will
now raise @ref{2eb,,ValueError}.

@end deffn

@geindex parse_qs() (於 urllib.parse 模組中)
@anchor{library/urllib parse urllib parse parse_qs}@anchor{31e}
@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{2eb,,ValueError} exception.

The optional `encoding' and `errors' parameters specify how to decode
percent-encoded sequences into Unicode characters, as accepted by the
@ref{aca,,bytes.decode()} method.

The optional argument `max_num_fields' is the maximum number of fields to
read. If set, then throws a @ref{2eb,,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{1090,,urllib.parse.urlencode()} function (with the @code{doseq}
parameter set to @code{True}) to convert such dictionaries into query
strings.


在 3.2 版的變更: 新增 `encoding' 和 `errors' 參數。



在 3.8 版的變更: 新增 `max_num_fields' 參數。



在 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{31d}
@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{2eb,,ValueError} exception.

The optional `encoding' and `errors' parameters specify how to decode
percent-encoded sequences into Unicode characters, as accepted by the
@ref{aca,,bytes.decode()} method.

The optional argument `max_num_fields' is the maximum number of fields to
read. If set, then throws a @ref{2eb,,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{1090,,urllib.parse.urlencode()} function to convert such lists of pairs into
query strings.


在 3.2 版的變更: 新增 `encoding' 和 `errors' 參數。



在 3.8 版的變更: 新增 `max_num_fields' 參數。



在 3.10 版的變更: Added `separator' parameter with the default value of @code{&}. Python
versions earlier than Python 3.10 allowed using both @code{;} and @code{&} as
query parameter separator. This has been changed to allow only a single
separator key, with @code{&} as the default separator.

@end deffn

@geindex urlunparse() (於 urllib.parse 模組中)
@anchor{library/urllib parse urllib parse urlunparse}@anchor{18a5}
@deffn {函式} urllib.parse.urlunparse (parts)

Construct a URL from a tuple as returned by @code{urlparse()}. The `parts'
argument can be any six-item iterable. This may result in a slightly
different, but equivalent URL, if the URL that was parsed originally had
unnecessary delimiters (for example, a @code{?} with an empty query; the RFC
states that these are equivalent).
@end deffn

@geindex urlsplit() (於 urllib.parse 模組中)
@anchor{library/urllib parse urllib parse urlsplit}@anchor{f35}
@deffn {函式} urllib.parse.urlsplit (urlstring, scheme='@w{'}, allow_fragments=True)

This is similar to @ref{360,,urlparse()}, but does not split the params from the URL.
This should generally be used instead of @ref{360,,urlparse()} if the more recent URL
syntax allowing parameters to be applied to each segment of the `path' portion
of the URL (see 
@geindex RFC; RFC 2396
RFC 2396@footnote{https://datatracker.ietf.org/doc/html/rfc2396.html}) is wanted.  A separate function is needed to
separate the path segments and parameters.  This function returns a 5-item
@ref{857,,named tuple}:

@example
(addressing scheme, network location, path, query, fragment identifier).
@end example

The return value is a @ref{857,,named tuple}, its items can be accessed by index
or as named attributes:


@multitable {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

屬性

@tab

Index

@tab

Value

@tab

Value if not present

@item

@code{scheme}

@tab

0

@tab

URL scheme specifier

@tab

`scheme' parameter

@item

@code{netloc}

@tab

1

@tab

Network location part

@tab

empty string

@item

@code{path}

@tab

2

@tab

Hierarchical path

@tab

empty string

@item

@code{query}

@tab

3

@tab

Query component

@tab

empty string

@item

@code{fragment}

@tab

4

@tab

Fragment identifier

@tab

empty string

@item

@code{username}

@tab

@tab

User name

@tab

@ref{87e,,None}

@item

@code{password}

@tab

@tab

Password

@tab

@ref{87e,,None}

@item

@code{hostname}

@tab

@tab

Host name (lower case)

@tab

@ref{87e,,None}

@item

@code{port}

@tab

@tab

Port number as integer,
if present

@tab

@ref{87e,,None}

@end multitable


Reading the @code{port} attribute will raise a @ref{2eb,,ValueError} if
an invalid port is specified in the URL.  See section
@ref{3e53,,Structured Parse Results} for more information on the result object.

Unmatched square brackets in the @code{netloc} attribute will raise a
@ref{2eb,,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{2eb,,ValueError}. If the URL is
decomposed before parsing, no error will be raised.

Following some of the WHATWG spec@footnote{https://url.spec.whatwg.org/#concept-basic-url-parser} that updates RFC 3986, leading C0
control and space characters are stripped from the URL. @code{\n},
@code{\r} and tab @code{\t} characters are removed from the URL at any position.

@cartouche
@quotation 警告 
@ref{f35,,urlsplit()} does not perform validation.  See @ref{3e54,,URL parsing security} for details.
@end quotation
@end cartouche


在 3.6 版的變更: Out-of-range port numbers now raise @ref{2eb,,ValueError}, instead of
returning @ref{87e,,None}.



在 3.8 版的變更: Characters that affect netloc parsing under NFKC normalization will
now raise @ref{2eb,,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.

@end deffn

@geindex urlunsplit() (於 urllib.parse 模組中)
@anchor{library/urllib parse urllib parse urlunsplit}@anchor{18a4}
@deffn {函式} urllib.parse.urlunsplit (parts)

Combine the elements of a tuple as returned by @ref{f35,,urlsplit()} into a
complete URL as a string. The `parts' argument can be any five-item
iterable. This may result in a slightly different, but equivalent URL, if the
URL that was parsed originally had unnecessary delimiters (for example, a ?
with an empty query; the RFC states that these are equivalent).
@end deffn

@geindex urljoin() (於 urllib.parse 模組中)
@anchor{library/urllib parse urllib parse urljoin}@anchor{1091}
@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{360,,urlparse()}.

@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{f35,,urlsplit()} and
@ref{18a4,,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{1448}
@deffn {函式} urllib.parse.urldefrag (url)

If `url' contains a fragment identifier, return a modified version of `url'
with no fragment identifier, and the fragment identifier as a separate
string.  If there is no fragment identifier in `url', return `url' unmodified
and an empty string.

The return value is a @ref{857,,named tuple}, its items can be accessed by index
or as named attributes:


@multitable {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

屬性

@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

empty string

@end multitable


See section @ref{3e53,,Structured Parse Results} for more information on the result
object.


在 3.2 版的變更: Result is a structured object rather than a simple 2-tuple.

@end deffn

@geindex unwrap() (於 urllib.parse 模組中)
@anchor{library/urllib parse urllib parse unwrap}@anchor{3e55}
@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 --- 將 URL 剖析成元件
@anchor{library/urllib parse id1}@anchor{3e56}@anchor{library/urllib parse url-parsing-security}@anchor{3e54}
@subsubsection URL parsing security


The @ref{f35,,urlsplit()} and @ref{360,,urlparse()} APIs do not perform `validation' of
inputs.  They may not raise errors on inputs that other applications consider
invalid.  They may also succeed on some inputs that might not be considered
URLs elsewhere.  Their purpose is for practical functionality rather than
purity.

Instead of raising an exception on unusual input, they may instead return some
component parts as empty strings. Or components may contain more than perhaps
they should.

We recommend that users of these APIs where the values may be used anywhere
with security implications code defensively. Do some verification within your
code before trusting a returned component part.  Does that @code{scheme} make
sense?  Is that a sensible @code{path}?  Is there anything strange about that
@code{hostname}?  etc.

What constitutes a URL is not universally well defined.  Different applications
have different needs and desired constraints.  For instance the living WHATWG spec@footnote{https://url.spec.whatwg.org/#concept-basic-url-parser} describes what user facing web clients such as a web browser require.
While 
@geindex RFC; RFC 3986
RFC 3986@footnote{https://datatracker.ietf.org/doc/html/rfc3986.html} is more general.  These functions incorporate some aspects of
both, but cannot be claimed compliant with either.  The APIs and existing user
code with expectations on specific behaviors predate both standards leading us
to be very cautious about making API behavior changes.

@node Parsing ASCII Encoded Bytes,Structured Parse Results,URL parsing security,urllib parse --- 將 URL 剖析成元件
@anchor{library/urllib parse id2}@anchor{3e57}@anchor{library/urllib parse parsing-ascii-encoded-bytes}@anchor{144a}
@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{192,,bytes} and
@ref{343,,bytearray} objects in addition to @ref{169,,str} objects.

If @ref{169,,str} data is passed in, the result will also contain only
@ref{169,,str} data. If @ref{192,,bytes} or @ref{343,,bytearray} data is
passed in, the result will contain only @ref{192,,bytes} data.

Attempting to mix @ref{169,,str} data with @ref{192,,bytes} or
@ref{343,,bytearray} in a single function call will result in a
@ref{198,,TypeError} being raised, while attempting to pass in non-ASCII
byte values will trigger @ref{bff,,UnicodeDecodeError}.

To support easier conversion of result objects between @ref{169,,str} and
@ref{192,,bytes}, all return values from URL parsing functions provide
either an @code{encode()} method (when the result contains @ref{169,,str}
data) or a @code{decode()} method (when the result contains @ref{192,,bytes}
data). The signatures of these methods match those of the corresponding
@ref{169,,str} and @ref{192,,bytes} methods (except that the default encoding
is @code{'ascii'} rather than @code{'utf-8'}). Each produces a value of a
corresponding type that contains either @ref{192,,bytes} data (for
@code{encode()} methods) or @ref{169,,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 --- 將 URL 剖析成元件
@anchor{library/urllib parse structured-parse-results}@anchor{3e58}@anchor{library/urllib parse urlparse-result-object}@anchor{3e53}
@subsubsection Structured Parse Results


The result objects from the @ref{360,,urlparse()}, @ref{f35,,urlsplit()}  and
@ref{1448,,urldefrag()} functions are subclasses of the @ref{60c,,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{3e59}
@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.

For @ref{1448,,urldefrag()} results, only empty fragment identifiers will be removed.
For @ref{f35,,urlsplit()} and @ref{360,,urlparse()} results, all noted changes will be
made to the URL returned by this method.

The result of this method remains unchanged if passed back through the original
parsing function:

@example
>>> from urllib.parse import urlsplit
>>> url = 'HTTP://www.Python.org/doc/#'
>>> r1 = urlsplit(url)
>>> r1.geturl()
'http://www.Python.org/doc/'
>>> r2 = urlsplit(r1.geturl())
>>> r2.geturl()
'http://www.Python.org/doc/'
@end example
@end deffn

The following classes provide the implementations of the structured parse
results when operating on @ref{169,,str} objects:

@geindex DefragResult (urllib.parse 中的類別)
@anchor{library/urllib parse urllib parse DefragResult}@anchor{3e5a}
@deffn {類別} urllib.parse.DefragResult (url, fragment)

Concrete class for @ref{1448,,urldefrag()} results containing @ref{169,,str}
data. The @code{encode()} method returns a @ref{3e5b,,DefragResultBytes}
instance.


在 3.2 版被加入.

@end deffn

@geindex ParseResult (urllib.parse 中的類別)
@anchor{library/urllib parse urllib parse ParseResult}@anchor{3e5c}
@deffn {類別} urllib.parse.ParseResult (scheme, netloc, path, params, query, fragment)

Concrete class for @ref{360,,urlparse()} results containing @ref{169,,str}
data. The @code{encode()} method returns a @ref{3e5d,,ParseResultBytes}
instance.
@end deffn

@geindex SplitResult (urllib.parse 中的類別)
@anchor{library/urllib parse urllib parse SplitResult}@anchor{3e5e}
@deffn {類別} urllib.parse.SplitResult (scheme, netloc, path, query, fragment)

Concrete class for @ref{f35,,urlsplit()} results containing @ref{169,,str}
data. The @code{encode()} method returns a @ref{3e5f,,SplitResultBytes}
instance.
@end deffn

The following classes provide the implementations of the parse results when
operating on @ref{192,,bytes} or @ref{343,,bytearray} objects:

@geindex DefragResultBytes (urllib.parse 中的類別)
@anchor{library/urllib parse urllib parse DefragResultBytes}@anchor{3e5b}
@deffn {類別} urllib.parse.DefragResultBytes (url, fragment)

Concrete class for @ref{1448,,urldefrag()} results containing @ref{192,,bytes}
data. The @code{decode()} method returns a @ref{3e5a,,DefragResult}
instance.


在 3.2 版被加入.

@end deffn

@geindex ParseResultBytes (urllib.parse 中的類別)
@anchor{library/urllib parse urllib parse ParseResultBytes}@anchor{3e5d}
@deffn {類別} urllib.parse.ParseResultBytes (scheme, netloc, path, params, query, fragment)

Concrete class for @ref{360,,urlparse()} results containing @ref{192,,bytes}
data. The @code{decode()} method returns a @ref{3e5c,,ParseResult}
instance.


在 3.2 版被加入.

@end deffn

@geindex SplitResultBytes (urllib.parse 中的類別)
@anchor{library/urllib parse urllib parse SplitResultBytes}@anchor{3e5f}
@deffn {類別} urllib.parse.SplitResultBytes (scheme, netloc, path, query, fragment)

Concrete class for @ref{f35,,urlsplit()} results containing @ref{192,,bytes}
data. The @code{decode()} method returns a @ref{3e5e,,SplitResult}
instance.


在 3.2 版被加入.

@end deffn

@node URL Quoting,,Structured Parse Results,urllib parse --- 將 URL 剖析成元件
@anchor{library/urllib parse url-quoting}@anchor{3e60}
@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{d97}
@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{169,,str} or a @ref{192,,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{ac9,,str.encode()} method.
`encoding' defaults to @code{'utf-8'}.
`errors' defaults to @code{'strict'}, meaning unsupported characters raise a
@ref{880,,UnicodeEncodeError}.
`encoding' and `errors' must not be supplied if `string' is a
@ref{192,,bytes}, or a @ref{198,,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{1449}
@deffn {函式} urllib.parse.quote_plus (string, safe='@w{'}, encoding=None, errors=None)

Like @ref{d97,,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{1a80}
@deffn {函式} urllib.parse.quote_from_bytes (bytes, safe='/')

Like @ref{d97,,quote()}, but accepts a @ref{192,,bytes} object rather than a
@ref{169,,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{1a41}
@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{aca,,bytes.decode()} method.

`string' may be either a @ref{169,,str} or a @ref{192,,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{3e61}
@deffn {函式} urllib.parse.unquote_plus (string, encoding='utf-8', errors='replace')

Like @ref{1a41,,unquote()}, but also replace plus signs with spaces, as required
for unquoting HTML form values.

`string' must be a @ref{169,,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{1a42}
@deffn {函式} urllib.parse.unquote_to_bytes (string)

Replace @code{%@var{xx}} escapes with their single-octet equivalent, and return a
@ref{192,,bytes} object.

`string' may be either a @ref{169,,str} or a @ref{192,,bytes} object.

If it is a @ref{169,,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{1090}
@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{169,,str} or @ref{192,,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{306,,urlopen()} function, then
it should be encoded to bytes, otherwise it would result in a
@ref{198,,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{1449,,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{d97,,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{169,,str}).

To reverse this encoding process, @ref{31e,,parse_qs()} and @ref{31d,,parse_qsl()} are
provided in this module to parse query strings into Python data structures.

Refer to @ref{3e44,,urllib examples} to find out how the
@ref{1090,,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 版的變更: 新增 `quote_via' 參數。



在 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} - 統一資源識別碼

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} - 統一資源識別碼 (URI)：通用語法

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} - 統一資源定位器 (URL, Uniform Resource Locators)

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 --- urllib request 引發的例外類別,urllib robotparser --- robots txt 的剖析器,urllib parse --- 將 URL 剖析成元件,網路協定 Internet protocols 及支援
@anchor{library/urllib error doc}@anchor{3e62}@anchor{library/urllib error module-urllib error}@anchor{10f}@anchor{library/urllib error translation-repo}@anchor{3e63}@anchor{library/urllib error urllib-error-exception-classes-raised-by-urllib-request}@anchor{3e64}
@subsection @code{urllib.error} --- urllib.request 引發的例外類別


@geindex module; urllib.error

`原始碼：'Lib/urllib/error.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/urllib/error.py}


__________________________________________________________________


@ref{10f,,urllib.error} module（模組）為 @ref{111,,urllib.request} 所引發的例外定義了例外 (exception) 類別。基礎例外類別是 @ref{2be,,URLError}。

下列例外會被 @ref{10f,,urllib.error} 適時引發：

@geindex URLError
@anchor{library/urllib error urllib error URLError}@anchor{2be}
@deffn {例外} urllib.error.URLError

處理程式 (handler) 在遇到問題時會引發此例外（或其衍生例外）。它是 @ref{2c0,,OSError} 的一個子類別。

@geindex reason (urllib.error.URLError 的屬性)
@anchor{library/urllib error urllib error URLError reason}@anchor{3e65}
@deffn {屬性} reason

此錯誤的原因。它可以是一個訊息字串或另一個例外實例。
@end deffn


在 3.3 版的變更: @ref{2be,,URLError} 過去是 @ref{2c0,,OSError} 的子類別，但現在為 @ref{2c0,,OSError} 的別名。

@end deffn

@geindex HTTPError
@anchor{library/urllib error urllib error HTTPError}@anchor{11d9}
@deffn {例外} urllib.error.HTTPError (url, code, msg, hdrs, fp)

雖然是一個例外（@ref{2be,,URLError} 的一個子類別），@ref{11d9,,HTTPError} 也可以作為一個非例外的類檔案回傳值（與 @ref{306,,urlopen()} 所回傳的物件相同）。這適用於處理特殊 HTTP 錯誤，例如為請求認證。

@geindex url (urllib.error.HTTPError 的屬性)
@anchor{library/urllib error urllib error HTTPError url}@anchor{3e66}
@deffn {屬性} url

包含請求 URL。`filename' 屬性的別名。
@end deffn

@geindex code (urllib.error.HTTPError 的屬性)
@anchor{library/urllib error urllib error HTTPError code}@anchor{3e67}
@deffn {屬性} code

一個 HTTP 狀態碼，具體定義見 
@geindex RFC; RFC 2616
RFC 2616@footnote{https://datatracker.ietf.org/doc/html/rfc2616.html}。這個數值會對應到存放在 @ref{3e68,,http.server.BaseHTTPRequestHandler.responses} 程式碼 dictionary 中的某個值。
@end deffn

@geindex reason (urllib.error.HTTPError 的屬性)
@anchor{library/urllib error urllib error HTTPError reason}@anchor{3e69}
@deffn {屬性} reason

這通常是一個解釋本次錯誤原因的字串。為 `msg' 屬性的別名。
@end deffn

@geindex headers (urllib.error.HTTPError 的屬性)
@anchor{library/urllib error urllib error HTTPError headers}@anchor{11da}
@deffn {屬性} headers

導致 @ref{11d9,,HTTPError} 的特定 HTTP 請求的 HTTP 回應 header。為 `hdrs' 屬性的別名。


在 3.4 版被加入.

@end deffn

@geindex fp (urllib.error.HTTPError 的屬性)
@anchor{library/urllib error urllib error HTTPError fp}@anchor{3e6a}
@deffn {屬性} fp

一個類檔案物件，可以從中讀取 HTTP 錯誤主體 (body)。
@end deffn
@end deffn

@geindex ContentTooShortError
@anchor{library/urllib error urllib error ContentTooShortError}@anchor{3e46}
@deffn {例外} urllib.error.ContentTooShortError (msg, content)

此例外會在 @ref{307,,urlretrieve()} 函式檢查到已下載的資料量小於期待的資料量（由 `Content-Length' header 給定）時被引發。

@geindex content (urllib.error.ContentTooShortError 的屬性)
@anchor{library/urllib error urllib error ContentTooShortError content}@anchor{3e6b}
@deffn {屬性} content

已下載（可能已被截斷）的資料。
@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 --- robots txt 的剖析器,http --- HTTP 模組,urllib error --- urllib request 引發的例外類別,網路協定 Internet protocols 及支援
@anchor{library/urllib robotparser doc}@anchor{3e6c}@anchor{library/urllib robotparser module-urllib robotparser}@anchor{113}@anchor{library/urllib robotparser translation-repo}@anchor{3e6d}@anchor{library/urllib robotparser urllib-robotparser-parser-for-robots-txt}@anchor{3e6e}
@subsection @code{urllib.robotparser} --- robots.txt 的剖析器


@geindex module; urllib.robotparser

`原始碼：'Lib/urllib/robotparser.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/urllib/robotparser.py}

@geindex WWW
@geindex World Wide Web （全球資訊網）
@geindex URL（統一資源定位器）
@geindex robots.txt


__________________________________________________________________


此模組 (module) 提供了一個單獨的類別 (class) @ref{ef5,,RobotFileParser}，它可以知道某個特定 user agent（使用者代理）是否能在有發布 @code{robots.txt} 文件的網站 fetch（擷取）特定 URL。有關 @code{robots.txt} 文件結構的更多細節，請參閱 @indicateurl{http://www.robotstxt.org/orig.html}。

@geindex RobotFileParser (urllib.robotparser 中的類別)
@anchor{library/urllib robotparser urllib robotparser RobotFileParser}@anchor{ef5}
@deffn {類別} urllib.robotparser.RobotFileParser (url='@w{'})

此類別提供了一些方法可以讀取、剖析和回答關於 `url' 上的 @code{robots.txt} 文件的問題。

@geindex set_url() (urllib.robotparser.RobotFileParser 的方法)
@anchor{library/urllib robotparser urllib robotparser RobotFileParser set_url}@anchor{3e6f}
@deffn {方法} set_url (url)

設置指向 @code{robots.txt} 文件的 URL。
@end deffn

@geindex read() (urllib.robotparser.RobotFileParser 的方法)
@anchor{library/urllib robotparser urllib robotparser RobotFileParser read}@anchor{1842}
@deffn {方法} read ()

讀取 @code{robots.txt} URL 並將其輸入到剖析器。
@end deffn

@geindex parse() (urllib.robotparser.RobotFileParser 的方法)
@anchor{library/urllib robotparser urllib robotparser RobotFileParser parse}@anchor{1d4a}
@deffn {方法} parse (lines)

剖析 lines 引數。
@end deffn

@geindex can_fetch() (urllib.robotparser.RobotFileParser 的方法)
@anchor{library/urllib robotparser urllib robotparser RobotFileParser can_fetch}@anchor{3e70}
@deffn {方法} can_fetch (useragent, url)

根據從 @code{robots.txt} 文件中剖析出的規則，如果 `useragent' 被允許 fetch `url' 的話，則回傳 @code{True}。
@end deffn

@geindex mtime() (urllib.robotparser.RobotFileParser 的方法)
@anchor{library/urllib robotparser urllib robotparser RobotFileParser mtime}@anchor{3e71}
@deffn {方法} mtime ()

回傳最近一次 fetch @code{robots.txt} 文件的時間。這適用於需要定期檢查 @code{robots.txt} 文件更新情況的長時間運行網頁爬蟲。
@end deffn

@geindex modified() (urllib.robotparser.RobotFileParser 的方法)
@anchor{library/urllib robotparser urllib robotparser RobotFileParser modified}@anchor{3e72}
@deffn {方法} modified ()

將最近一次 fetch @code{robots.txt} 文件的時間設置為目前時間。
@end deffn

@geindex crawl_delay() (urllib.robotparser.RobotFileParser 的方法)
@anchor{library/urllib robotparser urllib robotparser RobotFileParser crawl_delay}@anchor{3e73}
@deffn {方法} crawl_delay (useragent)

針對指定的 `useragent' 從 @code{robots.txt} 回傳 @code{Crawl-delay} 參數的值。如果此參數不存在、不適用於指定的 `useragent' ，或是此參數在 @code{robots.txt} 中所指的條目含有無效語法，則回傳 @code{None}。


在 3.6 版被加入.

@end deffn

@geindex request_rate() (urllib.robotparser.RobotFileParser 的方法)
@anchor{library/urllib robotparser urllib robotparser RobotFileParser request_rate}@anchor{3e74}
@deffn {方法} request_rate (useragent)

以 @ref{857,,named tuple} @code{RequestRate(requests, seconds)} 的形式從 @code{robots.txt} 回傳 @code{Request-rate} 參數的內容。如果此參數不存在、不適用於指定的 `useragent' ，或是此參數在 @code{robots.txt} 中所指的條目含有無效語法，則回傳 @code{None}。


在 3.6 版被加入.

@end deffn

@geindex site_maps() (urllib.robotparser.RobotFileParser 的方法)
@anchor{library/urllib robotparser urllib robotparser RobotFileParser site_maps}@anchor{1cea}
@deffn {方法} site_maps ()

以 @ref{24d,,list()} 的形式從 @code{robots.txt} 回傳 @code{Sitemap} 參數的內容。如果此參數不存在或此參數在 @code{robots.txt} 中所指的條目含有無效語法，則回傳 @code{None}。


在 3.8 版被加入.

@end deffn
@end deffn

下面的範例展示了 @ref{ef5,,RobotFileParser} 類別的基本用法：

@example
>>> import urllib.robotparser
>>> rp = urllib.robotparser.RobotFileParser()
>>> rp.set_url("http://www.musi-cal.com/robots.txt")
>>> rp.read()
>>> rrate = rp.request_rate("*")
>>> rrate.requests
3
>>> rrate.seconds
20
>>> rp.crawl_delay("*")
6
>>> rp.can_fetch("*", "http://www.musi-cal.com/cgi-bin/search?city=San+Francisco")
False
>>> rp.can_fetch("*", "http://www.musi-cal.com/")
True
@end example

@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 模組,http client --- HTTP 協定用戶端,urllib robotparser --- robots txt 的剖析器,網路協定 Internet protocols 及支援
@anchor{library/http doc}@anchor{3e75}@anchor{library/http http-http-modules}@anchor{3e76}@anchor{library/http module-http}@anchor{72}@anchor{library/http translation-repo}@anchor{3e77}
@subsection @code{http} --- HTTP 模組


@geindex module; http

`原始碼：'Lib/http/__init__.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/http/__init__.py}

@geindex HTTP;protocol（協定）
@geindex HTTP;http（標準模組）


__________________________________________________________________


@ref{72,,http} 是一個收集了多個用於處理超文本傳輸協定 (HyperText Transfer Protocol) 之模組 (module) 的套件：


@itemize *

@item 
@ref{73,,http.client} 是一個低階的 HTTP 協定用戶端；對於高階的 URL 存取請使用 @ref{111,,urllib.request}

@item 
@ref{76,,http.server} 包含基於 @ref{d2,,socketserver} 的基本 HTTP 伺服器類別

@item 
@ref{75,,http.cookies} 包含通過 cookies 實作狀態管理的工具程式 (utilities)

@item 
@ref{74,,http.cookiejar} 提供了 cookies 的持續留存 (persistence)
@end itemize

The @ref{72,,http} module also defines the following enums that help you work with http related code:

@geindex HTTPStatus (http 中的類別)
@anchor{library/http http HTTPStatus}@anchor{af3}
@deffn {類別} http.HTTPStatus


在 3.5 版被加入.


@ref{ed6,,enum.IntEnum} 的子類別，它定義了一組 HTTP 狀態碼、原理短語 (reason phrase) 以及英文長描述。

用法：

@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 狀態碼:: 
* HTTP 狀態分類:: 
* HTTP 方法:: 

@end menu

@node HTTP 狀態碼,HTTP 狀態分類,,http --- HTTP 模組
@anchor{library/http http-status-codes}@anchor{3e78}@anchor{library/http id1}@anchor{3e79}
@subsubsection HTTP 狀態碼


@ref{af3,,http.HTTPStatus} 當中，已支援並且有於 IANA 註冊的狀態碼@footnote{https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml}有：


@multitable {xxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

狀態碼

@tab

列舉名稱

@tab

詳情

@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}，10.1 節

@item

@code{103}

@tab

@code{EARLY_HINTS}

@tab

用於指定提示 (Indicating Hints) 
@geindex RFC; RFC 8297
RFC 8297@footnote{https://datatracker.ietf.org/doc/html/rfc8297.html} 的 HTTP 狀態碼

@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}，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}，7.1 節（實驗性）

@item

@code{226}

@tab

@code{IM_USED}

@tab

HTTP 中的差分編碼 
@geindex RFC; RFC 3229
RFC 3229@footnote{https://datatracker.ietf.org/doc/html/rfc3229.html}，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}，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}，11.4 節

@item

@code{425}

@tab

@code{TOO_EARLY}

@tab

使用 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

額外的 HTTP 狀態碼 
@geindex RFC; RFC 6585
RFC 6585@footnote{https://datatracker.ietf.org/doc/html/rfc6585.html}

@item

@code{429}

@tab

@code{TOO_MANY_REQUESTS}

@tab

額外的 HTTP 狀態碼 
@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

額外的 HTTP 狀態碼 
@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

一個用來回報合法性障礙 (Legal Obstacles) 的 HTTP 狀態碼 
@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

HTTP 中的透明內容協商 (Transparent Content Negotiation) 
@geindex RFC; RFC 2295
RFC 2295@footnote{https://datatracker.ietf.org/doc/html/rfc2295.html}，8.1 節（實驗性）

@item

@code{507}

@tab

@code{INSUFFICIENT_STORAGE}

@tab

WebDAV 
@geindex RFC; RFC 4918
RFC 4918@footnote{https://datatracker.ietf.org/doc/html/rfc4918.html}，11.5 節

@item

@code{508}

@tab

@code{LOOP_DETECTED}

@tab

WebDAV 繫結擴充 
@geindex RFC; RFC 5842
RFC 5842@footnote{https://datatracker.ietf.org/doc/html/rfc5842.html}，7.2 節（實驗性）

@item

@code{510}

@tab

@code{NOT_EXTENDED}

@tab

一個 HTTP 擴充框架 
@geindex RFC; RFC 2774
RFC 2774@footnote{https://datatracker.ietf.org/doc/html/rfc2774.html}，7 節（實驗性）

@item

@code{511}

@tab

@code{NETWORK_AUTHENTICATION_REQUIRED}

@tab

額外的 HTTP 狀態碼 
@geindex RFC; RFC 6585
RFC 6585@footnote{https://datatracker.ietf.org/doc/html/rfc6585.html}，6 節

@end multitable


為了向後相容性，列舉值也以常數形式出現在 @ref{73,,http.client} 模組中。列舉名稱等於常數名稱（例如 @code{http.HTTPStatus.OK} 也可以是 @code{http.client.OK}）。


在 3.7 版的變更: 新增 @code{421 MISDIRECTED_REQUEST} 狀態碼。



在 3.8 版被加入: 新增 @code{451 UNAVAILABLE_FOR_LEGAL_REASONS} 狀態碼。



在 3.9 版被加入: 新增 @code{103 EARLY_HINTS}、@code{418 IM_A_TEAPOT} 與 @code{425 TOO_EARLY} 狀態碼。



在 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 狀態分類,HTTP 方法,HTTP 狀態碼,http --- HTTP 模組
@anchor{library/http http-status-category}@anchor{3e7a}
@subsubsection HTTP 狀態分類



在 3.12 版被加入.


The enum values have several properties to indicate the HTTP status category:


@multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Property

@tab

Indicates that

@tab

詳情

@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

用法：

@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{3e7b}
@deffn {類別} http.HTTPMethod


在 3.11 版被加入.


@ref{826,,enum.StrEnum} 的子類別，它定義了一組 HTTP 方法以及英文描述。

用法：

@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 方法,,HTTP 狀態分類,http --- HTTP 模組
@anchor{library/http http-methods}@anchor{3e7c}@anchor{library/http id2}@anchor{3e7d}
@subsubsection HTTP 方法


@ref{af3,,http.HTTPStatus} 當中，已支援並且有於 IANA 註冊的狀態碼@footnote{https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml}有：


@multitable {xxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

方法

@tab

列舉名稱

@tab

詳情

@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 協定用戶端,ftplib --- FTP 協定用戶端,http --- HTTP 模組,網路協定 Internet protocols 及支援
@anchor{library/http client doc}@anchor{3e7e}@anchor{library/http client http-client-http-protocol-client}@anchor{3e7f}@anchor{library/http client module-http client}@anchor{73}@anchor{library/http client translation-repo}@anchor{3e80}
@subsection @code{http.client} --- HTTP 協定用戶端


@geindex module; http.client

`原始碼：'Lib/http/client.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/http/client.py}

@geindex HTTP;protocol（協定）
@geindex HTTP;http.client（標準模組）

@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{111,,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{d5,,ssl} module).
@end quotation
@end cartouche

@c include for modules that don't work on WASM

@ref{2006,,可用性}: not WASI.

此模組在 WebAssembly 平台上不起作用或無法使用。更多資訊請參閱 @ref{1a99,,WebAssembly 平台}。

The module provides the following classes:

@geindex HTTPConnection (http.client 中的類別)
@anchor{library/http client http client HTTPConnection}@anchor{d2d}
@deffn {類別} http.client.HTTPConnection (host, port=None[, timeout], source_address=None, blocksize=8192)

An @ref{d2d,,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.

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'。



在 3.4 版的變更: The  `strict' parameter was removed. HTTP 0.9-style "Simple Responses" are
no longer supported.



在 3.7 版的變更: 新增 `blocksize' 參數。

@end deffn

@geindex HTTPSConnection (http.client 中的類別)
@anchor{library/http client http client HTTPSConnection}@anchor{d2e}
@deffn {類別} http.client.HTTPSConnection (host, port=None, *[, timeout], source_address=None, context=None, blocksize=8192)

A subclass of @ref{d2d,,HTTPConnection} that uses SSL for communication with
secure servers.  Default port is @code{443}.  If `context' is specified, it
must be a @ref{355,,ssl.SSLContext} instance describing the various SSL
options.

Please read @ref{374a,,Security considerations} for more information on best practices.


在 3.2 版的變更: 新增 `source_address'、`context' 與 `check_hostname'。



在 3.2 版的變更: This class now supports HTTPS virtual hosts if possible (that is,
if @ref{388c,,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{c1d,,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{105f,,set_alpn_protocols()}.



在 3.12 版的變更: The deprecated `key_file', `cert_file' and `check_hostname' parameters
have been removed.

@end deffn

@geindex HTTPResponse (http.client 中的類別)
@anchor{library/http client http client HTTPResponse}@anchor{12cf}
@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{1cf1}
@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{89c,,BufferedIOBase} reader
(i.e. not text) and must provide a valid 
@geindex RFC; RFC 2822
RFC 2822@footnote{https://datatracker.ietf.org/doc/html/rfc2822.html} style header.

This function returns an instance of @ref{3e81,,http.client.HTTPMessage}
that holds the header fields, but no payload
(the same as @ref{3e82,,HTTPResponse.msg}
and @ref{3e83,,http.server.BaseHTTPRequestHandler.headers}).
After returning, the file pointer `fp' is ready to read the HTTP body.

@cartouche
@quotation 備註 
@ref{1cf1,,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{3e84}
@deffn {例外} http.client.HTTPException

The base class of the other exceptions in this module.  It is a subclass of
@ref{bc4,,Exception}.
@end deffn

@geindex NotConnected
@anchor{library/http client http client NotConnected}@anchor{3e85}
@deffn {例外} http.client.NotConnected

A subclass of @ref{3e84,,HTTPException}.
@end deffn

@geindex InvalidURL
@anchor{library/http client http client InvalidURL}@anchor{3e86}
@deffn {例外} http.client.InvalidURL

A subclass of @ref{3e84,,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{3e87}
@deffn {例外} http.client.UnknownProtocol

A subclass of @ref{3e84,,HTTPException}.
@end deffn

@geindex UnknownTransferEncoding
@anchor{library/http client http client UnknownTransferEncoding}@anchor{3e88}
@deffn {例外} http.client.UnknownTransferEncoding

A subclass of @ref{3e84,,HTTPException}.
@end deffn

@geindex UnimplementedFileMode
@anchor{library/http client http client UnimplementedFileMode}@anchor{3e89}
@deffn {例外} http.client.UnimplementedFileMode

A subclass of @ref{3e84,,HTTPException}.
@end deffn

@geindex IncompleteRead
@anchor{library/http client http client IncompleteRead}@anchor{3e8a}
@deffn {例外} http.client.IncompleteRead

A subclass of @ref{3e84,,HTTPException}.
@end deffn

@geindex ImproperConnectionState
@anchor{library/http client http client ImproperConnectionState}@anchor{3e8b}
@deffn {例外} http.client.ImproperConnectionState

A subclass of @ref{3e84,,HTTPException}.
@end deffn

@geindex CannotSendRequest
@anchor{library/http client http client CannotSendRequest}@anchor{3e8c}
@deffn {例外} http.client.CannotSendRequest

A subclass of @ref{3e8b,,ImproperConnectionState}.
@end deffn

@geindex CannotSendHeader
@anchor{library/http client http client CannotSendHeader}@anchor{3e8d}
@deffn {例外} http.client.CannotSendHeader

A subclass of @ref{3e8b,,ImproperConnectionState}.
@end deffn

@geindex ResponseNotReady
@anchor{library/http client http client ResponseNotReady}@anchor{3e8e}
@deffn {例外} http.client.ResponseNotReady

A subclass of @ref{3e8b,,ImproperConnectionState}.
@end deffn

@geindex BadStatusLine
@anchor{library/http client http client BadStatusLine}@anchor{3e8f}
@deffn {例外} http.client.BadStatusLine

A subclass of @ref{3e84,,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{3e90}
@deffn {例外} http.client.LineTooLong

A subclass of @ref{3e84,,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{1005}
@deffn {例外} http.client.RemoteDisconnected

A subclass of @ref{125a,,ConnectionResetError} and @ref{3e8f,,BadStatusLine}.  Raised
by @ref{1004,,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.


在 3.5 版被加入: Previously, @ref{3e8f,,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{3e91}
@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{3e92}
@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{3e93}
@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{3e78,,HTTP 狀態碼} for a list of HTTP status codes that are
available in this module as constants.

@menu
* HTTPConnection 物件:: 
* HTTPResponse 物件:: 
* 範例: 範例<37>. 
* HTTPMessage 物件:: 

@end menu

@node HTTPConnection 物件,HTTPResponse 物件,,http client --- HTTP 協定用戶端
@anchor{library/http client httpconnection-objects}@anchor{3e94}@anchor{library/http client id1}@anchor{3e95}
@subsubsection HTTPConnection 物件


@ref{d2d,,HTTPConnection} instances have the following methods:

@geindex request() (http.client.HTTPConnection 的方法)
@anchor{library/http client http client HTTPConnection request}@anchor{ea2}
@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{169,,str}, a @ref{193,,bytes-like object}, an
open @ref{13c4,,file object}, or an iterable of @ref{192,,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 @ref{13c4,,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{89d,,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{13c4,,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{169,,str} or bytes-like object that is not also a file as the
body representation.
@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{1004}
@deffn {方法} HTTPConnection.getresponse ()

Should be called after a request is sent to get the response from the server.
Returns an @ref{12cf,,HTTPResponse} instance.

@cartouche
@quotation 備註 
Note that you must have read the whole response before you can send a new
request to the server.
@end quotation
@end cartouche


在 3.5 版的變更: If a @ref{1006,,ConnectionError} or subclass is raised, the
@ref{d2d,,HTTPConnection} object will be ready to reconnect when
a new request is sent.

@end deffn

@geindex set_debuglevel() (http.client.HTTPConnection 的方法)
@anchor{library/http client http client HTTPConnection set_debuglevel}@anchor{3e96}
@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{12cf,,HTTPResponse} objects that are created.


在 3.1 版被加入.

@end deffn

@geindex set_tunnel() (http.client.HTTPConnection 的方法)
@anchor{library/http client http client HTTPConnection set_tunnel}@anchor{1429}
@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{d2e,,HTTPSConnection}
constructor, and the address of the host that we eventually want to reach to
the @ref{1429,,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


在 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{19c5}
@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}.


在 3.12 版被加入.

@end deffn

@geindex connect() (http.client.HTTPConnection 的方法)
@anchor{library/http client http client HTTPConnection connect}@anchor{3e97}
@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.

引發一個附帶引數 @code{self}、@code{host}、@code{port} 的@ref{1b70,,稽核事件} @code{http.client.connect}。
@end deffn

@geindex close() (http.client.HTTPConnection 的方法)
@anchor{library/http client http client HTTPConnection close}@anchor{3e98}
@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{3e99}
@deffn {屬性} HTTPConnection.blocksize

Buffer size in bytes for sending a file-like message body.


在 3.7 版被加入.

@end deffn

As an alternative to using the @ref{ea2,,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{3e9a}
@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{3e9b}
@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{ea3}
@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{260,,buffer interface} the encoding will result in a single chunk.
If `message_body' is a @ref{2558,,collections.abc.Iterable}, each iteration
of `message_body' will result in a chunk.  If `message_body' is a
@ref{13c4,,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{3e9c}
@deffn {方法} HTTPConnection.send (data)

Send data to the server.  This should be used directly only after the
@ref{ea3,,endheaders()} method has been called and before @ref{1004,,getresponse()} is
called.

引發一個附帶引數 @code{self}、@code{data} 的@ref{1b70,,稽核事件} @code{http.client.send}。
@end deffn

@node HTTPResponse 物件,範例<37>,HTTPConnection 物件,http client --- HTTP 協定用戶端
@anchor{library/http client httpresponse-objects}@anchor{3e9d}@anchor{library/http client id2}@anchor{3e9e}
@subsubsection HTTPResponse 物件


An @ref{12cf,,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{89c,,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{1825}
@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{12d0}
@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.


在 3.3 版被加入.

@end deffn

@geindex getheader() (http.client.HTTPResponse 的方法)
@anchor{library/http client http client HTTPResponse getheader}@anchor{3e9f}
@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{3ea0}
@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{3ea1}
@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{3e82}
@deffn {屬性} HTTPResponse.msg

A @ref{3e81,,http.client.HTTPMessage} instance containing the response
headers.  @ref{3e81,,http.client.HTTPMessage} is a subclass of
@ref{57b,,email.message.Message}.
@end deffn

@geindex version (http.client.HTTPResponse 的屬性)
@anchor{library/http client http client HTTPResponse version}@anchor{3ea2}
@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{3ea3}
@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{3ea4}
@deffn {屬性} HTTPResponse.headers

Headers of the response in the form of an @ref{57a,,email.message.EmailMessage} instance.
@end deffn

@geindex status (http.client.HTTPResponse 的屬性)
@anchor{library/http client http client HTTPResponse status}@anchor{3ea5}
@deffn {屬性} HTTPResponse.status

Status code returned by server.
@end deffn

@geindex reason (http.client.HTTPResponse 的屬性)
@anchor{library/http client http client HTTPResponse reason}@anchor{3dd0}
@deffn {屬性} HTTPResponse.reason

Reason phrase returned by server.
@end deffn

@geindex debuglevel (http.client.HTTPResponse 的屬性)
@anchor{library/http client http client HTTPResponse debuglevel}@anchor{3ea6}
@deffn {屬性} HTTPResponse.debuglevel

A debugging hook.  If @ref{3ea6,,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{3ea7}
@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{3ea8}
@deffn {方法} HTTPResponse.geturl ()


在 3.9 版之後被棄用: Deprecated in favor of @ref{3ea3,,url}.

@end deffn

@geindex info() (http.client.HTTPResponse 的方法)
@anchor{library/http client http client HTTPResponse info}@anchor{3ea9}
@deffn {方法} HTTPResponse.info ()


在 3.9 版之後被棄用: Deprecated in favor of @ref{3ea4,,headers}.

@end deffn

@geindex getcode() (http.client.HTTPResponse 的方法)
@anchor{library/http client http client HTTPResponse getcode}@anchor{3eaa}
@deffn {方法} HTTPResponse.getcode ()


在 3.9 版之後被棄用: Deprecated in favor of @ref{3ea5,,status}.

@end deffn

@node 範例<37>,HTTPMessage 物件,HTTPResponse 物件,http client --- HTTP 協定用戶端
@anchor{library/http client examples}@anchor{3eab}
@subsubsection 範例


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{11d3,,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 物件,,範例<37>,http client --- HTTP 協定用戶端
@anchor{library/http client httpmessage-objects}@anchor{3eac}@anchor{library/http client id3}@anchor{3ead}
@subsubsection HTTPMessage 物件


@geindex HTTPMessage (http.client 中的類別)
@anchor{library/http client http client HTTPMessage}@anchor{3e81}
@deffn {類別} http.client.HTTPMessage (email.message.Message)
@end deffn

An @ref{3e81,,http.client.HTTPMessage} instance holds the headers from an HTTP
response.  It is implemented using the @ref{57b,,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 協定用戶端,poplib --- POP3 協定用戶端,http client --- HTTP 協定用戶端,網路協定 Internet protocols 及支援
@anchor{library/ftplib doc}@anchor{3eae}@anchor{library/ftplib ftplib-ftp-protocol-client}@anchor{3eaf}@anchor{library/ftplib module-ftplib}@anchor{62}@anchor{library/ftplib translation-repo}@anchor{3eb0}
@subsection @code{ftplib} --- FTP 協定用戶端


@geindex module; ftplib

`原始碼：'Lib/ftplib.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/ftplib.py}

@geindex FTP;protocol（協定）
@geindex FTP;ftplib（標準模組）


__________________________________________________________________


這個模組定義了 @ref{aed,,FTP} 類別和一些相關的項目。@ref{aed,,FTP} 類別實作了 FTP 協定的用戶端。你可以使用它來編寫能夠執行各種 FTP 自動作業的 Python 程式，例如鏡像 (mirror) 其他 FTP 伺服器。@ref{111,,urllib.request} 模組也使用它來處理使用 FTP 的 URL。有關 FTP（檔案傳輸協定）的更多資訊，請參閱 
@geindex RFC; RFC 959
RFC 959@footnote{https://datatracker.ietf.org/doc/html/rfc959.html}。

預設編碼是 UTF-8，遵循 
@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{2006,,可用性}: not WASI.

此模組在 WebAssembly 平台上不起作用或無法使用。更多資訊請參閱 @ref{1a99,,WebAssembly 平台}。

這是一個使用 @ref{62,,ftplib} 模組的會話範例：

@example
>>> from ftplib import FTP
>>> ftp = FTP('ftp.us.debian.org')  # connect to host, default port
>>> ftp.login()                     # user anonymous, passwd anonymous@@
'230 Login successful.'
>>> ftp.cwd('debian')               # change into "debian" directory
'250 Directory successfully changed.'
>>> ftp.retrlines('LIST')           # list directory contents
-rw-rw-r--    1 1176     1176         1063 Jun 15 10:18 README
...
drwxr-sr-x    5 1176     1176         4096 Dec 19  2000 pool
drwxr-sr-x    4 1176     1176         4096 Nov 17  2008 project
drwxr-xr-x    3 1176     1176         4096 Oct 10  2012 tools
'226 Directory send OK.'
>>> with open('README', 'wb') as fp:
>>>     ftp.retrbinary('RETR README', fp.write)
'226 Transfer complete.'
>>> ftp.quit()
'221 Goodbye.'
@end example

@menu
* 參考:: 

@end menu

@node 參考,,,ftplib --- FTP 協定用戶端
@anchor{library/ftplib ftplib-reference}@anchor{3eb1}@anchor{library/ftplib reference}@anchor{3eb2}
@subsubsection 參考


@menu
* FTP 物件:: 
* FTP_TLS 物件:: 
* 模組變數:: 

@end menu

@node FTP 物件,FTP_TLS 物件,,參考
@anchor{library/ftplib ftp-objects}@anchor{3eb3}@anchor{library/ftplib id1}@anchor{3eb4}
@subsubsection FTP 物件


@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{aed}
@deffn {類別} ftplib.FTP (host='@w{'}, user='@w{'}, passwd='@w{'}, acct='@w{'}, timeout=None, source_address=None, *, encoding='utf-8')

回傳一個新的 @ref{aed,,FTP} 類別實例。

@*參數: 

@itemize *

@item 
@code{host} (@ref{169,,str}) -- 要連接的主機名稱。如果有給定，@code{connect(host)} 會由建構函式來隱式地呼叫。

@item 
@code{user} (@ref{169,,str}) -- The username to log in with (default: @code{'anonymous'}). 如果有給定，@code{login(host, passwd, acct)} 會由建構函式來隱式地呼叫。

@item 
@code{passwd} (@ref{169,,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{169,,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{196,,float}@code{ | }@code{None}) -- 如 @ref{3eb5,,connect()} 的阻塞操作的超時設定，以秒為單位（預設：使用全域預設超時設定）。

@item 
@code{source_address} (@ref{60c,,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{169,,str}) -- The encoding for directories and filenames (default: @code{'utf-8'}).
@end itemize


@ref{aed,,FTP} 類別支援 @ref{186,,with} 陳述式，例如：

@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 版的變更: 新增了對 @ref{186,,with} 陳述式的支援。



在 3.3 版的變更: 新增 `source_address' 參數。



在 3.9 版的變更: 如果 `timeout' 參數設定為零，它將引發 @ref{2eb,,ValueError} 以防止建立非阻塞 socket。新增了 `encoding' 參數，預設值從 Latin-1 更改為 UTF-8 以遵循 
@geindex RFC; RFC 2640
RFC 2640@footnote{https://datatracker.ietf.org/doc/html/rfc2640.html}。


@code{FTP} 的多個可用方法大致有分為兩個方向：一種用於處理文本檔案 (text files)，另一種用於二進位檔案 (binary files)。這些以在文本檔案的 @code{lines} 或二進位檔案的 @code{binary} 前使用的命令命名。

@ref{aed,,FTP} 實例具有以下方法：

@geindex set_debuglevel() (ftplib.FTP 的方法)
@anchor{library/ftplib ftplib FTP set_debuglevel}@anchor{3eb6}
@deffn {方法} set_debuglevel (level)

將實例的偵錯級別設定為一個 @ref{19b,,int}，這控制印出的偵錯訊息輸出量。


@itemize *

@item 
@code{0}（預設值）：不產生偵錯輸出。

@item 
@code{1}：會產生適量的偵錯輸出，通常是每個請求輸出一行。

@item 
@code{2} 或更高的值：會產生最大量的偵錯輸出，以日誌紀錄下控制連線發送和接收的每個步驟。
@end itemize
@end deffn

@geindex connect() (ftplib.FTP 的方法)
@anchor{library/ftplib ftplib FTP connect}@anchor{3eb5}
@deffn {方法} connect (host='@w{'}, port=0, timeout=None, source_address=None)

連線到給定的主機 (host) 和連接埠 (port)。每個實例只應呼叫此函式一次；如果在建立 @ref{aed,,FTP} 實例時有給定 `host' 引數，則不應呼叫它。所有其他的 @code{FTP} 方法只能在成功建立連線後使用。

@*參數: 

@itemize *

@item 
@code{host} (@ref{169,,str}) -- 要連接的主機。

@item 
@code{port} (@ref{19b,,int}) -- 要連接的 TCP 連接埠（預設值：@code{21}，由 FTP 協定規範指定）。很少需要指定不同的連接埠號碼。

@item 
@code{timeout} (@ref{196,,float}@code{ | }@code{None}) -- 連線嘗試的超時設定，以秒為單位（預設：全域預設超時設定）。

@item 
@code{source_address} (@ref{60c,,tuple}@code{ | }@code{None}) -- A 2-tuple @code{(host, port)} for the socket to bind to as its
source address before connecting.
@end itemize


引發一個附帶引數 @code{self}、@code{host}、@code{port} 的@ref{1b70,,稽核事件} @code{ftplib.connect}。


在 3.3 版的變更: 新增 `source_address' 參數。

@end deffn

@geindex getwelcome() (ftplib.FTP 的方法)
@anchor{library/ftplib ftplib FTP getwelcome}@anchor{3eb7}
@deffn {方法} getwelcome ()

回傳伺服器為回應初始連線而發送的歡迎訊息。（此訊息有時會包含與使用者相關的免責聲明或幫助資訊。）
@end deffn

@geindex login() (ftplib.FTP 的方法)
@anchor{library/ftplib ftplib FTP login}@anchor{3eb8}
@deffn {方法} login (user='anonymous', passwd='@w{'}, acct='@w{'})

在以連線的伺服器上登入。在建立連線後，每個實例只應呼叫此函式一次；如果在建立 @ref{aed,,FTP} 實例時有給定 `host' 和 `user' 引數，則不應呼叫它。大多數 FTP 命令僅在用戶端登錄後才允許使用

@*參數: 

@itemize *

@item 
@code{user} (@ref{169,,str}) -- The username to log in with (default: @code{'anonymous'}).

@item 
@code{passwd} (@ref{169,,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{169,,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{3eb9}
@deffn {方法} abort ()

中止正在進行的檔案傳輸。使用它並不是都會成功，但值得一試。
@end deffn

@geindex sendcmd() (ftplib.FTP 的方法)
@anchor{library/ftplib ftplib FTP sendcmd}@anchor{3eba}
@deffn {方法} sendcmd (cmd)

向伺服器發送一個簡單的命令字串並回傳回應字串。

引發一個附帶引數 @code{self}、@code{cmd} 的@ref{1b70,,稽核事件} @code{ftplib.sendcmd}。
@end deffn

@geindex voidcmd() (ftplib.FTP 的方法)
@anchor{library/ftplib ftplib FTP voidcmd}@anchor{3ebb}
@deffn {方法} voidcmd (cmd)

向伺服器發送一個簡單的命令字串並處理回應。如果收到代表成功的回應狀態碼（範圍為 200--299 的狀態碼），則回傳回應字串，否則引發 @ref{3ebc,,error_reply}。

引發一個附帶引數 @code{self}、@code{cmd} 的@ref{1b70,,稽核事件} @code{ftplib.sendcmd}。
@end deffn

@geindex retrbinary() (ftplib.FTP 的方法)
@anchor{library/ftplib ftplib FTP retrbinary}@anchor{3ebd}
@deffn {方法} retrbinary (cmd, callback, blocksize=8192, rest=None)

以二進位傳輸模式 (binary transfer mode) 取得檔案。

@*參數: 

@itemize *

@item 
@code{cmd} (@ref{169,,str}) -- 一個正確的 @code{RETR} 指令：@code{"RETR @var{filename}"}。

@item 
@code{callback} (@ref{2c2e,,callable}) -- 為接收到的每個資料區塊呼叫的單一參數可呼叫物件，其單一引數是以 @ref{192,,bytes} 為形式的資料。

@item 
@code{blocksize} (@ref{19b,,int}) -- 在執行實際傳輸時所建立的低階 @ref{f9c,,socket} 物件上讀取的最大分塊 (chunk) 大小。這也對應於將傳遞給 `callback' 的最大資料大小。預設為 @code{8192}。

@item 
@code{rest} (@ref{19b,,int}) -- 一個要發送到伺服器的 @code{REST} 命令。參見 @ref{3ebe,,transfercmd()} 方法之 `rest' 參數的文件。
@end itemize

@end deffn

@geindex retrlines() (ftplib.FTP 的方法)
@anchor{library/ftplib ftplib FTP retrlines}@anchor{3ebf}
@deffn {方法} retrlines (cmd, callback=None)

在初始化時以 `encoding' 參數指定的編碼來取得檔案或目錄列表。 `cmd' 要是一個正確的 @code{RETR} 命令（見 @ref{3ebd,,retrbinary()}）或者一個像 @code{LIST} 或 @code{NLST} 的命令（通常只是字串 @code{'LIST'} )。 @code{LIST} 會取得檔案列表和這些檔案的相關資訊。 @code{NLST} 取得檔案名稱列表。會為每一行以一個字串引數呼叫 `callback' 函式，其引數包含已經刪除尾隨 CRLF 的一行。預設的 `callback' 會將各行印出到 @ref{cc4,,sys.stdout}。
@end deffn

@geindex set_pasv() (ftplib.FTP 的方法)
@anchor{library/ftplib ftplib FTP set_pasv}@anchor{3ec0}
@deffn {方法} set_pasv (val)

如果 `val' 為真，則啟用「被動」模式，否則禁用被動模式。被動模式預設開啟。
@end deffn

@geindex storbinary() (ftplib.FTP 的方法)
@anchor{library/ftplib ftplib FTP storbinary}@anchor{150a}
@deffn {方法} storbinary (cmd, fp, blocksize=8192, callback=None, rest=None)

以二進位傳輸模式儲存檔案。

@*參數: 

@itemize *

@item 
@code{cmd} (@ref{169,,str}) -- 一個正確的 @code{STOR} 指令：@code{"STOR @var{filename}"}。

@item 
@code{fp} (@ref{13c4,,file object}) -- 一個檔案物件（以二進位模式開啟），在大小為 `blocksize' 的區塊中使用其 @ref{1018,,read()} 方法讀取直到 EOF 來提供要儲存的資料。

@item 
@code{blocksize} (@ref{19b,,int}) -- 讀取區塊大小。預設為 @code{8192}。

@item 
@code{callback} (@ref{2c2e,,callable}) -- 為發送的每個資料區塊來呼叫的單一參數可呼叫物件，其單一引數是以 @ref{192,,bytes} 為形式的資料。

@item 
@code{rest} (@ref{19b,,int}) -- 一個要發送到伺服器的 @code{REST} 命令。參見 @ref{3ebe,,transfercmd()} 方法之 `rest' 參數的文件。
@end itemize



在 3.2 版的變更: 新增 `rest' 參數。

@end deffn

@geindex storlines() (ftplib.FTP 的方法)
@anchor{library/ftplib ftplib FTP storlines}@anchor{3ec1}
@deffn {方法} storlines (cmd, fp, callback=None)

以行模式 (line mode) 儲存檔案。 `cmd' 應是一個正確的 @code{STOR} 命令（參見 @ref{150a,,storbinary()}）。使用其 @ref{152a,,readline()} 方法從@ref{13c4,,檔案物件} `fp' （以二進位模式打開）讀取各行、直到 EOF，以提供要儲存的資料。 `callback' 是可選的單參數可呼叫物件，於發送後以各行進行呼叫。
@end deffn

@geindex transfercmd() (ftplib.FTP 的方法)
@anchor{library/ftplib ftplib FTP transfercmd}@anchor{3ebe}
@deffn {方法} transfercmd (cmd, rest=None)

通過資料連線啟動傳輸。如果傳輸為主動 (active) 模式，則發送 @code{EPRT} 或 @code{PORT} 命令和 `cmd' 指定的傳輸命令，並接受連線。如果伺服器是被動 (passive) 模式，則發送 @code{EPSV} 或 @code{PASV} 命令、連線、並啟動傳輸命令。無論哪種方式，都是回傳連線的 socket。

如果有給定可選的 `rest'，一個 @code{REST} 命令會被發送到伺服器，並以 `rest' 作為引數。`rest' 通常是請求檔案的一個位元組偏移量 (byte offset)，告訴伺服器以請求的偏移量重新開始發送檔案的位元組，並跳過初始位元組。但是請注意，@ref{3ebe,,transfercmd()} 方法將 `rest' 轉換為帶有初始化時指定的 `encoding' 參數的字串，但不會對字串的內容執行檢查。如果伺服器無法識別 @code{REST} 命令，則會引發 @ref{3ebc,,error_reply} 例外。如果發生這種情況，只需在沒有 `rest' 引數的情況下呼叫 @ref{3ebe,,transfercmd()}。
@end deffn

@geindex ntransfercmd() (ftplib.FTP 的方法)
@anchor{library/ftplib ftplib FTP ntransfercmd}@anchor{3ec2}
@deffn {方法} ntransfercmd (cmd, rest=None)

類似於 @ref{3ebe,,transfercmd()}，但回傳一個帶有資料連線和資料預期大小的元組。如果無法計算預期大小，則回傳 @code{None}。 `cmd' 和 `rest' 與 @ref{3ebe,,transfercmd()} 中的含義相同。
@end deffn

@geindex mlsd() (ftplib.FTP 的方法)
@anchor{library/ftplib ftplib FTP mlsd}@anchor{12c3}
@deffn {方法} mlsd (path='@w{'}, facts=[])

使用 @code{MLSD} 命令 (
@geindex RFC; RFC 3659
RFC 3659@footnote{https://datatracker.ietf.org/doc/html/rfc3659.html}) 列出標準格式的目錄。如果省略 `path' 則假定為作用於目前目錄。`facts' 是表示所需資訊類型的字串列表（例如 @code{["type", "size", "perm"]} ）。會回傳一個產生器物件，為每個在路徑中找到的檔案生成一個包含兩個元素的元組，第一個元素是檔案名稱，第二個元素是包含有關檔案名稱 facts的字典。該字典的內容可能受 `facts' 引數限制，但不保證伺服器會回傳所有請求的 facts。


在 3.3 版被加入.

@end deffn

@geindex nlst() (ftplib.FTP 的方法)
@anchor{library/ftplib ftplib FTP nlst}@anchor{12c4}
@deffn {方法} nlst (argument[, ...])

回傳由 @code{NLST} 命令回傳的檔案名稱列表。可選的 `argument' 是要列出的目錄（預設為目前伺服器目錄）。多個引數可用於將非標準選項傳遞給 @code{NLST} 命令。

@cartouche
@quotation 備註 
如果你的伺服器支援該命令，@ref{12c3,,mlsd()} 會提供更好的 API。
@end quotation
@end cartouche
@end deffn

@geindex dir() (ftplib.FTP 的方法)
@anchor{library/ftplib ftplib FTP dir}@anchor{12c5}
@deffn {方法} dir (argument[, ...])

生成由 @code{LIST} 命令回傳的目錄列表，並將其印出到標準輸出 (standard output)。可選的 `argument' 是要列出的目錄（預設為目前伺服器目錄）。有多個引數可用於將非標準選項傳遞給 @code{LIST} 命令。如果最後一個引數是一個函式，它被用作 @ref{3ebf,,retrlines()} 的 `callback' 函式；預設印出到 @ref{cc4,,sys.stdout}。此方法回傳 @code{None}。

@cartouche
@quotation 備註 
如果你的伺服器支援該命令，@ref{12c3,,mlsd()} 會提供更好的 API。
@end quotation
@end cartouche
@end deffn

@geindex rename() (ftplib.FTP 的方法)
@anchor{library/ftplib ftplib FTP rename}@anchor{3ec3}
@deffn {方法} rename (fromname, toname)

將伺服器上的檔案 `fromname' 重新命名為 `toname'。
@end deffn

@geindex delete() (ftplib.FTP 的方法)
@anchor{library/ftplib ftplib FTP delete}@anchor{3ec4}
@deffn {方法} delete (filename)

從伺服器中刪除名為 `filename' 的檔案。如果成功，回傳回應的文字，否則引發 @ref{3ec5,,error_perm} 權限錯誤或在其他錯誤發生時引發 @ref{3ebc,,error_reply}。
@end deffn

@geindex cwd() (ftplib.FTP 的方法)
@anchor{library/ftplib ftplib FTP cwd}@anchor{3ec6}
@deffn {方法} cwd (pathname)

設定伺服器上的目前目錄。
@end deffn

@geindex mkd() (ftplib.FTP 的方法)
@anchor{library/ftplib ftplib FTP mkd}@anchor{3ec7}
@deffn {方法} mkd (pathname)

在伺服器上建立一個新目錄。
@end deffn

@geindex pwd() (ftplib.FTP 的方法)
@anchor{library/ftplib ftplib FTP pwd}@anchor{3ec8}
@deffn {方法} pwd ()

回傳伺服器上目前目錄的路徑名。
@end deffn

@geindex rmd() (ftplib.FTP 的方法)
@anchor{library/ftplib ftplib FTP rmd}@anchor{3ec9}
@deffn {方法} rmd (dirname)

刪除伺服器上名為 `dirname' 的目錄。
@end deffn

@geindex size() (ftplib.FTP 的方法)
@anchor{library/ftplib ftplib FTP size}@anchor{3eca}
@deffn {方法} size (filename)

請求伺服器上名為 `filename' 的檔案的大小。成功時，檔案的大小作為整數回傳，否則回傳 @code{None}。請注意，@code{SIZE} 命令不是標準化的，但被許多常見的伺服器實作支援。
@end deffn

@geindex quit() (ftplib.FTP 的方法)
@anchor{library/ftplib ftplib FTP quit}@anchor{3ecb}
@deffn {方法} quit ()

向伺服器發送 @code{QUIT} 命令並關閉連線。這是關閉連線的「禮貌」方式，但如果伺服器對 @code{QUIT} 命令作出錯誤回應，它可能會引發例外。這意味著呼叫 @ref{3ecc,,close()} 方法使 @ref{aed,,FTP} 實例無法用於後續呼叫（見下文）。
@end deffn

@geindex close() (ftplib.FTP 的方法)
@anchor{library/ftplib ftplib FTP close}@anchor{3ecc}
@deffn {方法} close ()

單方面關閉連線。這不應該使用於已經關閉的連線，例如在成功呼叫 @ref{3ecb,,quit()} 之後。呼叫後就不應該再次使用 @ref{aed,,FTP} 實例（在呼叫 @ref{3ecc,,close()} 或 @ref{3ecb,,quit()} 後，你不能通過發出另一個 @ref{3eb8,,login()} 方法重新打開連線）。
@end deffn
@end deffn

@node FTP_TLS 物件,模組變數,FTP 物件,參考
@anchor{library/ftplib ftp-tls-objects}@anchor{3ecd}
@subsubsection FTP_TLS 物件


@geindex FTP_TLS (ftplib 中的類別)
@anchor{library/ftplib ftplib FTP_TLS}@anchor{aee}
@deffn {類別} ftplib.FTP_TLS (host='@w{'}, user='@w{'}, passwd='@w{'}, acct='@w{'}, *, context=None, timeout=None, source_address=None, encoding='utf-8')

An @ref{aed,,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{3ece,,prot_p()} method.
@end quotation
@end cartouche

@*參數: 

@itemize *

@item 
@code{host} (@ref{169,,str}) -- 要連接的主機名稱。如果有給定，@code{connect(host)} 會由建構函式來隱式地呼叫。

@item 
@code{user} (@ref{169,,str}) -- The username to log in with (default: @code{'anonymous'}). 如果有給定，@code{login(host, passwd, acct)} 會由建構函式來隱式地呼叫。

@item 
@code{passwd} (@ref{169,,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{169,,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{355,,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{374a,,Security considerations} for best practices.

@item 
@code{timeout} (@ref{196,,float}@code{ | }@code{None}) -- 如 @ref{3eb5,,connect()} 的阻塞操作的超時設定，以秒為單位（預設：使用全域預設超時設定）。

@item 
@code{source_address} (@ref{60c,,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{169,,str}) -- The encoding for directories and filenames (default: @code{'utf-8'}).
@end itemize



在 3.2 版被加入.



在 3.3 版的變更: 新增 `source_address' 參數。



在 3.4 版的變更: 該類別現在支援使用 @ref{387a,,ssl.SSLContext.check_hostname} 和 `Server Name Indication' 進行主機名 (hostname) 檢查（參見 @ref{388c,,ssl.HAS_SNI}）。



在 3.9 版的變更: 如果 `timeout' 參數設定為零，它將引發 @ref{2eb,,ValueError} 以防止建立非阻塞 socket。新增了 `encoding' 參數，預設值從 Latin-1 更改為 UTF-8 以遵循 
@geindex RFC; RFC 2640
RFC 2640@footnote{https://datatracker.ietf.org/doc/html/rfc2640.html}。



在 3.12 版的變更: 已棄用的 `keyfile' 和 `certfile' 參數已被移除。


這是一個使用 @ref{aee,,FTP_TLS} 類別的範例會話：

@example
>>> ftps = FTP_TLS('ftp.pureftpd.org')
>>> ftps.login()
'230 Anonymous user logged in'
>>> ftps.prot_p()
'200 Data protection level set to "private"'
>>> ftps.nlst()
['6jack', 'OpenBSD', 'antilink', 'blogbench', 'bsdcam', 'clockspeed', 'djbdns-jedi', 'docs', 'eaccelerator-jedi', 'favicon.ico', 'francotone', 'fugu', 'ignore', 'libpuzzle', 'metalog', 'minidentd', 'misc', 'mysql-udf-global-user-variables', 'php-jenkins-hash', 'php-skein-hash', 'php-webdav', 'phpaudit', 'phpbench', 'pincaster', 'ping', 'posto', 'pub', 'public', 'public_keys', 'pure-ftpd', 'qscan', 'qtc', 'sharedance', 'skycache', 'sound', 'tmp', 'ucarp']
@end example

@code{FTP_TLS} 類別繼承自 @ref{aed,,FTP}，並另外定義了這些的方法與屬性：

@geindex ssl_version (ftplib.FTP_TLS 的屬性)
@anchor{library/ftplib ftplib FTP_TLS ssl_version}@anchor{3ecf}
@deffn {屬性} ssl_version

要使用的 SSL 版本（預設為 @ref{387e,,ssl.PROTOCOL_SSLv23}）。
@end deffn

@geindex auth() (ftplib.FTP_TLS 的方法)
@anchor{library/ftplib ftplib FTP_TLS auth}@anchor{3ed0}
@deffn {方法} auth ()

根據 @ref{3ecf,,ssl_version} 屬性中指定的內容，使用 TLS 或 SSL 設定安全控制連線。


在 3.4 版的變更: 該方法現在支援使用 @ref{387a,,ssl.SSLContext.check_hostname} 和 `Server Name Indication' 進行主機名檢查（參見 @ref{388c,,ssl.HAS_SNI}）。

@end deffn

@geindex ccc() (ftplib.FTP_TLS 的方法)
@anchor{library/ftplib ftplib FTP_TLS ccc}@anchor{12c2}
@deffn {方法} ccc ()

將控制通道恢復為純文本。這對於利用知道如何在不打開固定連接埠的情況下使用非安全 (non-secure) FTP 以處理 NAT 的防火牆很有用。


在 3.3 版被加入.

@end deffn

@geindex prot_p() (ftplib.FTP_TLS 的方法)
@anchor{library/ftplib ftplib FTP_TLS prot_p}@anchor{3ece}
@deffn {方法} prot_p ()

設定安全資料連線。
@end deffn

@geindex prot_c() (ftplib.FTP_TLS 的方法)
@anchor{library/ftplib ftplib FTP_TLS prot_c}@anchor{3ed1}
@deffn {方法} prot_c ()

設定明文資料 (clear text data) 連線。
@end deffn
@end deffn

@node 模組變數,,FTP_TLS 物件,參考
@anchor{library/ftplib module-variables}@anchor{3ed2}
@subsubsection 模組變數


@geindex error_reply
@anchor{library/ftplib ftplib error_reply}@anchor{3ebc}
@deffn {例外} ftplib.error_reply

伺服器收到意外回覆時所引發的例外。
@end deffn

@geindex error_temp
@anchor{library/ftplib ftplib error_temp}@anchor{3ed3}
@deffn {例外} ftplib.error_temp

當收到表示暫時錯誤的錯誤碼（400--499 範圍內的回應狀態碼）時引發的例外。
@end deffn

@geindex error_perm
@anchor{library/ftplib ftplib error_perm}@anchor{3ec5}
@deffn {例外} ftplib.error_perm

當收到表示永久錯誤的錯誤碼（500--599 範圍內的回應狀態碼）時引發的例外。
@end deffn

@geindex error_proto
@anchor{library/ftplib ftplib error_proto}@anchor{3ed4}
@deffn {例外} ftplib.error_proto

當從伺服器收到不符合檔案傳輸協定回應規範的回覆時引發例外，即 1--5 範圍內的數字開頭。
@end deffn

@geindex all_errors (於 ftplib 模組中)
@anchor{library/ftplib ftplib all_errors}@anchor{3ed5}
@deffn {資料} ftplib.all_errors

@ref{aed,,FTP} 實例方法由於 FTP 連線問題（相對於呼叫者的程式錯誤）而可能引發的所有例外集合（元組形式）。該集合包括上面列出的四個例外以及 @ref{2c0,,OSError} 和 @ref{14da,,EOFError}。
@end deffn


@subsubheading 也參考



@table @asis

@item @ref{9f,,netrc} 模組

@code{.netrc} 檔案格式的剖析器。@code{.netrc} 檔案通常被 FTP 用戶端用來在提示使用者之前載入使用者身份驗證資訊。
@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 協定用戶端,imaplib --- IMAP4 協定用戶端,ftplib --- FTP 協定用戶端,網路協定 Internet protocols 及支援
@anchor{library/poplib doc}@anchor{3ed6}@anchor{library/poplib module-poplib}@anchor{b1}@anchor{library/poplib poplib-pop3-protocol-client}@anchor{3ed7}@anchor{library/poplib translation-repo}@anchor{3ed8}
@subsection @code{poplib} --- POP3 協定用戶端


@geindex module; poplib

@c revised by ESR, January 2000

`原始碼：'Lib/poplib.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/poplib.py}

@geindex POP3;protocol（協定）


__________________________________________________________________


This module defines a class, @ref{b14,,POP3}, which encapsulates a connection to a
POP3 server and implements the protocol as defined in 
@geindex RFC; RFC 1939
RFC 1939@footnote{https://datatracker.ietf.org/doc/html/rfc1939.html}. The
@ref{b14,,POP3} class supports both the minimal and optional command sets from
@geindex RFC; RFC 1939
RFC 1939@footnote{https://datatracker.ietf.org/doc/html/rfc1939.html}. The @ref{b14,,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{b15,,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{af6,,imaplib.IMAP4} class, as IMAP servers tend to be better implemented.

@c include for modules that don't work on WASM

@ref{2006,,可用性}: not WASI.

此模組在 WebAssembly 平台上不起作用或無法使用。更多資訊請參閱 @ref{1a99,,WebAssembly 平台}。

The @ref{b1,,poplib} module provides two classes:

@geindex POP3 (poplib 中的類別)
@anchor{library/poplib poplib POP3}@anchor{b14}
@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).

引發一個附帶引數 @code{self}、@code{host}、@code{port} 的@ref{1b70,,稽核事件} @code{poplib.connect}。

引發一個附帶引數 @code{self}、@code{line} 的@ref{1b70,,稽核事件} @code{poplib.putline}。其中 @code{line} 為即將傳送給遠端的位元組。


在 3.9 版的變更: If the `timeout' parameter is set to be zero, it will raise a
@ref{2eb,,ValueError} to prevent the creation of a non-blocking socket.

@end deffn

@geindex POP3_SSL (poplib 中的類別)
@anchor{library/poplib poplib POP3_SSL}@anchor{b15}
@deffn {類別} poplib.POP3_SSL (host, port=POP3_SSL_PORT, *, timeout=None, context=None)

This is a subclass of @ref{b14,,POP3} that connects to the server over an SSL
encrypted socket.  If `port' is not specified, 995, the standard POP3-over-SSL
port is used.  `timeout' works as in the @ref{b14,,POP3} constructor.
`context' is an optional @ref{355,,ssl.SSLContext} object which allows
bundling SSL configuration options, certificates and private keys into a
single (potentially long-lived) structure.  Please read @ref{374a,,Security considerations}
for best practices.

引發一個附帶引數 @code{self}、@code{host}、@code{port} 的@ref{1b70,,稽核事件} @code{poplib.connect}。

引發一個附帶引數 @code{self}、@code{line} 的@ref{1b70,,稽核事件} @code{poplib.putline}。其中 @code{line} 為即將傳送給遠端的位元組。


在 3.2 版的變更: `context' parameter added.



在 3.4 版的變更: The class now supports hostname check with
@ref{387a,,ssl.SSLContext.check_hostname} and `Server Name Indication' (see
@ref{388c,,ssl.HAS_SNI}).



在 3.9 版的變更: If the `timeout' parameter is set to be zero, it will raise a
@ref{2eb,,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 @ref{b1,,poplib} module:

@geindex error_proto
@anchor{library/poplib poplib error_proto}@anchor{139d}
@deffn {例外} poplib.error_proto

Exception raised on any errors from this module (errors from @ref{d1,,socket}
module are not caught). The reason for the exception is passed to the
constructor as a string.
@end deffn


@subsubheading 也參考



@table @asis

@item @ref{78,,imaplib} 模組

The standard Python IMAP module.

@item 關於 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 物件:: 
* POP3 範例:: 

@end menu

@node POP3 物件,POP3 範例,,poplib --- POP3 協定用戶端
@anchor{library/poplib id1}@anchor{3ed9}@anchor{library/poplib pop3-objects}@anchor{3eda}
@subsubsection POP3 物件


All POP3 commands are represented by methods of the same name, in lowercase;
most return the response text sent by the server.

@ref{b14,,POP3} 實例擁有以下方法：

@geindex set_debuglevel() (poplib.POP3 的方法)
@anchor{library/poplib poplib POP3 set_debuglevel}@anchor{3edb}
@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{3edc}
@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{1177}
@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'...]@}}.


在 3.4 版被加入.

@end deffn

@geindex user() (poplib.POP3 的方法)
@anchor{library/poplib poplib POP3 user}@anchor{3edd}
@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{3ede}
@deffn {方法} POP3.pass_ (password)

Send password, response includes message count and mailbox size. Note: the
mailbox on the server is locked until @ref{139c,,quit()} is called.
@end deffn

@geindex apop() (poplib.POP3 的方法)
@anchor{library/poplib poplib POP3 apop}@anchor{3edf}
@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{3ee0}
@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{3ee1}
@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{3ee2}
@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{3ee3}
@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{3ee4}
@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{3ee5}
@deffn {方法} POP3.rset ()

Remove any deletion marks for the mailbox.
@end deffn

@geindex noop() (poplib.POP3 的方法)
@anchor{library/poplib poplib POP3 noop}@anchor{3ee6}
@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{139c}
@deffn {方法} POP3.quit ()

Signoff:  commit changes, unlock mailbox, drop connection.
@end deffn

@geindex top() (poplib.POP3 的方法)
@anchor{library/poplib poplib POP3 top}@anchor{3ee7}
@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{3ee8}
@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{1044}
@deffn {方法} POP3.utf8 ()

Try to switch to UTF-8 mode. Returns the server response if successful,
raises @ref{139d,,error_proto} if not. Specified in 
@geindex RFC; RFC 6856
RFC 6856@footnote{https://datatracker.ietf.org/doc/html/rfc6856.html}.


在 3.5 版被加入.

@end deffn

@geindex stls() (poplib.POP3 的方法)
@anchor{library/poplib poplib POP3 stls}@anchor{1178}
@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{355,,ssl.SSLContext} object which allows
bundling SSL configuration options, certificates and private keys into
a single (potentially long-lived) structure.  Please read @ref{374a,,Security considerations}
for best practices.

This method supports hostname checking via
@ref{387a,,ssl.SSLContext.check_hostname} and `Server Name Indication' (see
@ref{388c,,ssl.HAS_SNI}).


在 3.4 版被加入.

@end deffn

Instances of @ref{b15,,POP3_SSL} have no additional methods. The interface of this
subclass is identical to its parent.

@node POP3 範例,,POP3 物件,poplib --- POP3 協定用戶端
@anchor{library/poplib id2}@anchor{3ee9}@anchor{library/poplib pop3-example}@anchor{3eea}
@subsubsection POP3 範例


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 協定用戶端,smtplib --- SMTP 協定用戶端,poplib --- POP3 協定用戶端,網路協定 Internet protocols 及支援
@anchor{library/imaplib doc}@anchor{3eeb}@anchor{library/imaplib imaplib-imap4-protocol-client}@anchor{3eec}@anchor{library/imaplib module-imaplib}@anchor{78}@anchor{library/imaplib translation-repo}@anchor{3eed}
@subsection @code{imaplib} --- IMAP4 協定用戶端


@geindex module; imaplib

@c revised by ESR, January 2000

@c changes for IMAP4_SSL by Tino Lange <Tino.Lange@isg.de>, March 2002

@c changes for IMAP4_stream by Piers Lauder <piers@communitysolutions.com.au>,
@c November 2002

@c changes for IMAP4 IDLE by Forest <forestix@nom.one>, August 2024

`原始碼：'Lib/imaplib.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/imaplib.py}

@geindex IMAP4;protocol（協定）
@geindex IMAP4_SSL;protocol（協定）
@geindex IMAP4_stream;protocol（協定）


__________________________________________________________________


This module defines three classes, @ref{af6,,IMAP4}, @ref{af7,,IMAP4_SSL} and
@ref{af9,,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{2006,,可用性}: not WASI.

此模組在 WebAssembly 平台上不起作用或無法使用。更多資訊請參閱 @ref{1a99,,WebAssembly 平台}。

Three classes are provided by the @ref{78,,imaplib} module, @ref{af6,,IMAP4} is the
base class:

@geindex IMAP4 (imaplib 中的類別)
@anchor{library/imaplib imaplib IMAP4}@anchor{af6}
@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 @ref{af6,,IMAP4} class supports the @ref{186,,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{186,,with} statement was added.



在 3.9 版的變更: 新增 `timeout' 選用參數。

@end deffn

Three exceptions are defined as attributes of the @ref{af6,,IMAP4} class:

@geindex IMAP4.error
@anchor{library/imaplib imaplib IMAP4 error}@anchor{177d}
@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{3eee}
@deffn {例外} IMAP4.abort

IMAP4 server errors cause this exception to be raised.  This is a sub-class of
@ref{177d,,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{3eef}
@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{177d,,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{af7}
@deffn {類別} imaplib.IMAP4_SSL (host='@w{'}, port=IMAP4_SSL_PORT, *, ssl_context=None, timeout=None)

This is a subclass derived from @ref{af6,,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{355,,ssl.SSLContext} object which allows bundling
SSL configuration options, certificates and private keys into a single
(potentially long-lived) structure.  Please read @ref{374a,,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' 參數。



在 3.4 版的變更: The class now supports hostname check with
@ref{387a,,ssl.SSLContext.check_hostname} and `Server Name Indication' (see
@ref{388c,,ssl.HAS_SNI}).



在 3.9 版的變更: 新增 `timeout' 選用參數。



在 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{af9}
@deffn {類別} imaplib.IMAP4_stream (command)

This is a subclass derived from @ref{af6,,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{3ef0}
@deffn {函式} imaplib.Internaldate2tuple (datestr)

Parse an IMAP4 @code{INTERNALDATE} string and return corresponding local
time.  The return value is a @ref{ee1,,time.struct_time} tuple or
@code{None} if the string has wrong format.
@end deffn

@geindex Int2AP() (於 imaplib 模組中)
@anchor{library/imaplib imaplib Int2AP}@anchor{3ef1}
@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{3ef2}
@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{3ef3}
@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{557,,time.time()}), a 9-tuple representing local time
an instance of @ref{ee1,,time.struct_time} (as returned by
@ref{16ed,,time.localtime()}), an aware instance of
@ref{4dd,,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 物件:: 
* IMAP4 範例:: 

@end menu

@node IMAP4 物件,IMAP4 範例,,imaplib --- IMAP4 協定用戶端
@anchor{library/imaplib id1}@anchor{3ef4}@anchor{library/imaplib imap4-objects}@anchor{3ef5}
@subsubsection IMAP4 物件


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:*'}).

@ref{af6,,IMAP4} 實例擁有以下方法：

@geindex append() (imaplib.IMAP4 的方法)
@anchor{library/imaplib imaplib IMAP4 append}@anchor{3ef6}
@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{3ef7}
@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{3ef8}
@deffn {方法} IMAP4.check ()

Checkpoint mailbox on server.
@end deffn

@geindex close() (imaplib.IMAP4 的方法)
@anchor{library/imaplib imaplib IMAP4 close}@anchor{afb}
@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{3ef9}
@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{3efa}
@deffn {方法} IMAP4.create (mailbox)

Create new mailbox named `mailbox'.
@end deffn

@geindex delete() (imaplib.IMAP4 的方法)
@anchor{library/imaplib imaplib IMAP4 delete}@anchor{3efb}
@deffn {方法} IMAP4.delete (mailbox)

Delete old mailbox named `mailbox'.
@end deffn

@geindex deleteacl() (imaplib.IMAP4 的方法)
@anchor{library/imaplib imaplib IMAP4 deleteacl}@anchor{3efc}
@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{1009}
@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}).


在 3.5 版被加入: The @ref{1009,,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{3efd}
@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{3efe}
@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{3eff}
@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{3f00}
@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{3f01}
@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{3f02}
@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{22d}
@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{186,,with} statement, produces IMAP untagged responses via the
@ref{4c3,,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{186,,with} context) can be retrieved in the usual way after
@code{IDLE} ends, using @ref{3f03,,IMAP4.response()}.

Responses are represented as @code{(type, [data, ...])} tuples, as described
in @ref{3ef5,,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{19b,,int} or
@ref{196,,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{af9,,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{3f04}
@deffn {方法} Idler.burst (interval=0.1)

Yield a burst of responses no more than `interval' seconds apart
(expressed as an @ref{19b,,int} or @ref{196,,float}).

This @ref{125c,,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{af9,,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
@ref{22d,,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 @ref{22d,,IMAP4.idle()} is usable only within a
@ref{186,,with} statement. Before or after that context, unsolicited
responses are collected internally whenever a command finishes, and can
be retrieved with @ref{3f03,,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


在 3.14 版被加入.

@end deffn

@geindex list() (imaplib.IMAP4 的方法)
@anchor{library/imaplib imaplib IMAP4 list}@anchor{3f05}
@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{3f06}
@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{177c}
@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.14 版的變更: An @ref{177d,,IMAP4.error} is raised if MD5 support is not available.

@end deffn

@geindex logout() (imaplib.IMAP4 的方法)
@anchor{library/imaplib imaplib IMAP4 logout}@anchor{c7b}
@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{3f07}
@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{3f08}
@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{3f09}
@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{3f0a}
@deffn {方法} IMAP4.noop ()

Send @code{NOOP} to server.
@end deffn

@geindex open() (imaplib.IMAP4 的方法)
@anchor{library/imaplib imaplib IMAP4 open}@anchor{af8}
@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{2eb,,ValueError} to reject creating a non-blocking socket.
This method is implicitly called by the @ref{af6,,IMAP4} constructor.
The connection objects established by this method will be used in
the @ref{3f0b,,IMAP4.read()}, @ref{3f0c,,IMAP4.readline()}, @ref{3f0d,,IMAP4.send()},
and @ref{3f0e,,IMAP4.shutdown()} methods. You may override this method.

引發一個附帶引數 @code{self}、@code{host}、@code{port} 的@ref{1b70,,稽核事件} @code{imaplib.open}。


在 3.9 版的變更: 新增 `timeout' 參數。

@end deffn

@geindex partial() (imaplib.IMAP4 的方法)
@anchor{library/imaplib imaplib IMAP4 partial}@anchor{3f0f}
@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{3f10}
@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{3f0b}
@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{3f0c}
@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{3f11}
@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{3f12}
@deffn {方法} IMAP4.rename (oldmailbox, newmailbox)

Rename mailbox named `oldmailbox' to `newmailbox'.
@end deffn

@geindex response() (imaplib.IMAP4 的方法)
@anchor{library/imaplib imaplib IMAP4 response}@anchor{3f03}
@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{3f13}
@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{1009,,enable()}
command.

範例：

@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{3f14}
@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{3f0d}
@deffn {方法} IMAP4.send (data)

Sends @code{data} to the remote server. You may override this method.

引發一個附帶引數 @code{self}、@code{data} 的@ref{1b70,,稽核事件} @code{imaplib.send}。
@end deffn

@geindex setacl() (imaplib.IMAP4 的方法)
@anchor{library/imaplib imaplib IMAP4 setacl}@anchor{3f15}
@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{3f16}
@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{3f17}
@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{3f0e}
@deffn {方法} IMAP4.shutdown ()

Close connection established in @code{open}.  This method is implicitly
called by @ref{c7b,,IMAP4.logout()}.  You may override this method.
@end deffn

@geindex socket() (imaplib.IMAP4 的方法)
@anchor{library/imaplib imaplib IMAP4 socket}@anchor{3f18}
@deffn {方法} IMAP4.socket ()

Returns socket instance used to connect to server.
@end deffn

@geindex sort() (imaplib.IMAP4 的方法)
@anchor{library/imaplib imaplib IMAP4 sort}@anchor{3f19}
@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{1426}
@deffn {方法} IMAP4.starttls (ssl_context=None)

Send a @code{STARTTLS} command.  The `ssl_context' argument is optional
and should be a @ref{355,,ssl.SSLContext} object.  This will enable
encryption on the IMAP connection.  Please read @ref{374a,,Security considerations} for
best practices.


在 3.2 版被加入.



在 3.4 版的變更: The method now supports hostname check with
@ref{387a,,ssl.SSLContext.check_hostname} and `Server Name Indication' (see
@ref{388c,,ssl.HAS_SNI}).

@end deffn

@geindex status() (imaplib.IMAP4 的方法)
@anchor{library/imaplib imaplib IMAP4 status}@anchor{3f1a}
@deffn {方法} IMAP4.status (mailbox, names)

Request named status conditions for `mailbox'.
@end deffn

@geindex store() (imaplib.IMAP4 的方法)
@anchor{library/imaplib imaplib IMAP4 store}@anchor{3f1b}
@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{3f1c}
@deffn {方法} IMAP4.subscribe (mailbox)

Subscribe to new mailbox.
@end deffn

@geindex thread() (imaplib.IMAP4 的方法)
@anchor{library/imaplib imaplib IMAP4 thread}@anchor{3f1d}
@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{3f1e}
@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{3f1f}
@deffn {方法} IMAP4.unsubscribe (mailbox)

Unsubscribe from old mailbox.
@end deffn

@geindex unselect() (imaplib.IMAP4 的方法)
@anchor{library/imaplib imaplib IMAP4 unselect}@anchor{afa}
@deffn {方法} IMAP4.unselect ()

@ref{afa,,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{afb,,imaplib.IMAP4.close()}, except
that no messages are permanently removed from the currently
selected mailbox.


在 3.9 版被加入.

@end deffn

@geindex xatom() (imaplib.IMAP4 的方法)
@anchor{library/imaplib imaplib IMAP4 xatom}@anchor{3f20}
@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{af6,,IMAP4}:

@geindex PROTOCOL_VERSION (imaplib.IMAP4 的屬性)
@anchor{library/imaplib imaplib IMAP4 PROTOCOL_VERSION}@anchor{3f21}
@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{3f22}
@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{100a}
@deffn {屬性} IMAP4.utf8_enabled

Boolean value that is normally @code{False}, but is set to @code{True} if an
@ref{1009,,enable()} command is successfully issued for the @code{UTF8=ACCEPT}
capability.


在 3.5 版被加入.

@end deffn

@node IMAP4 範例,,IMAP4 物件,imaplib --- IMAP4 協定用戶端
@anchor{library/imaplib id2}@anchor{3f23}@anchor{library/imaplib imap4-example}@anchor{3f24}
@subsubsection IMAP4 範例


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 協定用戶端,uuid --- RFC 9562 定義的 UUID 物件,imaplib --- IMAP4 協定用戶端,網路協定 Internet protocols 及支援
@anchor{library/smtplib doc}@anchor{3f25}@anchor{library/smtplib module-smtplib}@anchor{cf}@anchor{library/smtplib smtplib-smtp-protocol-client}@anchor{3f26}@anchor{library/smtplib translation-repo}@anchor{3f27}
@subsection @code{smtplib} --- SMTP 協定用戶端


@geindex module; smtplib

`原始碼：'Lib/smtplib.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/smtplib.py}

@geindex SMTP;protocol（協定）
@geindex Simple Mail Transfer Protocol（簡易郵件傳輸協定）


__________________________________________________________________


The @ref{cf,,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{2006,,可用性}: not WASI.

此模組在 WebAssembly 平台上不起作用或無法使用。更多資訊請參閱 @ref{1a99,,WebAssembly 平台}。

@geindex SMTP (smtplib 中的類別)
@anchor{library/smtplib smtplib SMTP}@anchor{b1e}
@deffn {類別} smtplib.SMTP (host='@w{'}, port=0, local_hostname=None[, timeout], source_address=None)

An @ref{b1e,,SMTP} instance encapsulates an SMTP connection.  It has methods
that support a full repertoire of SMTP and ESMTP operations. If the optional
`host' and `port' parameters are given, the SMTP @ref{1c78,,connect()} method is
called with those parameters during initialization.  If specified,
`local_hostname' is used as the FQDN of the local host in the HELO/EHLO
command.  Otherwise, the local hostname is found using
@ref{1a37,,socket.getfqdn()}.  If the @ref{1c78,,connect()} call returns anything other
than a success code, an @ref{3f28,,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{a2f,,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{1054,,sendmail()}, and @ref{3f29,,SMTP.quit()} methods.
An example is included below.

The @ref{b1e,,SMTP} class supports the @ref{186,,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

所有指令都會引發一個附帶引數 @code{self}、@code{data} 的@ref{1b70,,稽核事件} @code{smtplib.SMTP.send}，其中 @code{data} 為即將傳送至遠端的位元組。


在 3.3 版的變更: Support for the @ref{186,,with} statement was added.



在 3.3 版的變更: 新增 source_address 引數。



在 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{2eb,,ValueError} to prevent the creation of a non-blocking socket.

@end deffn

@geindex SMTP_SSL (smtplib 中的類別)
@anchor{library/smtplib smtplib SMTP_SSL}@anchor{b1f}
@deffn {類別} smtplib.SMTP_SSL (host='@w{'}, port=0, local_hostname=None, *[, timeout], context=None, source_address=None)

An @ref{b1f,,SMTP_SSL} instance behaves exactly the same as instances of
@ref{b1e,,SMTP}. @ref{b1f,,SMTP_SSL} should be used for situations where SSL is
required from the beginning of the connection and using @ref{1339,,starttls()}
is not appropriate. If `host' is not specified, the local host is used. If
`port' is zero, the standard SMTP-over-SSL port (465) is used.  The optional
arguments `local_hostname', `timeout' and `source_address' have the same
meaning as they do in the @ref{b1e,,SMTP} class.  `context', also optional,
can contain a @ref{355,,SSLContext} and allows configuring various
aspects of the secure connection.  Please read @ref{374a,,Security considerations} for
best practices.


在 3.3 版的變更: 新增 `context'。



在 3.3 版的變更: 新增 `source_address' 引數。



在 3.4 版的變更: The class now supports hostname check with
@ref{387a,,ssl.SSLContext.check_hostname} and `Server Name Indication' (see
@ref{388c,,ssl.HAS_SNI}).



在 3.9 版的變更: If the `timeout' parameter is set to be zero, it will raise a
@ref{2eb,,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{b20}
@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{1c78,,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{b1e,,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 版的變更: 新增 `timeout' 選用參數。

@end deffn

A nice selection of exceptions is defined as well:

@geindex SMTPException
@anchor{library/smtplib smtplib SMTPException}@anchor{119c}
@deffn {例外} smtplib.SMTPException

Subclass of @ref{2c0,,OSError} that is the base exception class for all
the other exceptions provided by this module.


在 3.4 版的變更: SMTPException became subclass of @ref{2c0,,OSError}

@end deffn

@geindex SMTPServerDisconnected
@anchor{library/smtplib smtplib SMTPServerDisconnected}@anchor{3f2a}
@deffn {例外} smtplib.SMTPServerDisconnected

This exception is raised when the server unexpectedly disconnects, or when an
attempt is made to use the @ref{b1e,,SMTP} instance before connecting it to a
server.
@end deffn

@geindex SMTPResponseException
@anchor{library/smtplib smtplib SMTPResponseException}@anchor{3f2b}
@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{3f2c}
@deffn {屬性} smtp_code

The error code.
@end deffn

@geindex smtp_error (smtplib.SMTPResponseException 的屬性)
@anchor{library/smtplib smtplib SMTPResponseException smtp_error}@anchor{3f2d}
@deffn {屬性} smtp_error

The error message.
@end deffn
@end deffn

@geindex SMTPSenderRefused
@anchor{library/smtplib smtplib SMTPSenderRefused}@anchor{3f2e}
@deffn {例外} smtplib.SMTPSenderRefused

Sender address refused.  In addition to the attributes set by on all
@ref{3f2b,,SMTPResponseException} exceptions, this sets 'sender' to the string that
the SMTP server refused.
@end deffn

@geindex SMTPRecipientsRefused
@anchor{library/smtplib smtplib SMTPRecipientsRefused}@anchor{3f2f}
@deffn {例外} smtplib.SMTPRecipientsRefused

All recipient addresses refused.

@geindex recipients (smtplib.SMTPRecipientsRefused 的屬性)
@anchor{library/smtplib smtplib SMTPRecipientsRefused recipients}@anchor{3f30}
@deffn {屬性} recipients

A dictionary of exactly the same sort as returned
by @ref{1054,,SMTP.sendmail()} containing the errors for
each recipient.
@end deffn
@end deffn

@geindex SMTPDataError
@anchor{library/smtplib smtplib SMTPDataError}@anchor{3f31}
@deffn {例外} smtplib.SMTPDataError

The SMTP server refused to accept the message data.
@end deffn

@geindex SMTPConnectError
@anchor{library/smtplib smtplib SMTPConnectError}@anchor{3f28}
@deffn {例外} smtplib.SMTPConnectError

Error occurred during establishment of a connection  with the server.
@end deffn

@geindex SMTPHeloError
@anchor{library/smtplib smtplib SMTPHeloError}@anchor{3f32}
@deffn {例外} smtplib.SMTPHeloError

The server refused our @code{HELO} message.
@end deffn

@geindex SMTPNotSupportedError
@anchor{library/smtplib smtplib SMTPNotSupportedError}@anchor{1c77}
@deffn {例外} smtplib.SMTPNotSupportedError

The command or option attempted is not supported by the server.


在 3.5 版被加入.

@end deffn

@geindex SMTPAuthenticationError
@anchor{library/smtplib smtplib SMTPAuthenticationError}@anchor{3f33}
@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} - 簡易郵件傳輸協定

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 物件:: 
* SMTP 範例:: 

@end menu

@node SMTP 物件,SMTP 範例,,smtplib --- SMTP 協定用戶端
@anchor{library/smtplib id1}@anchor{3f34}@anchor{library/smtplib smtp-objects}@anchor{3f35}
@subsubsection SMTP 物件


@ref{b1e,,SMTP} 實例擁有以下方法：

@geindex set_debuglevel() (smtplib.SMTP 的方法)
@anchor{library/smtplib smtplib SMTP set_debuglevel}@anchor{1053}
@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{3f36}
@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{3f2a,,SMTPServerDisconnected} will be raised.
@end deffn

@geindex connect() (smtplib.SMTP 的方法)
@anchor{library/smtplib smtplib SMTP connect}@anchor{1c78}
@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.

引發一個附帶引數 @code{self}、@code{host}、@code{port} 的@ref{1b70,,稽核事件} @code{smtplib.connect}。
@end deffn

@geindex helo() (smtplib.SMTP 的方法)
@anchor{library/smtplib smtplib SMTP helo}@anchor{3f37}
@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{3f38,,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{1054,,sendmail()} when necessary.
@end deffn

@geindex ehlo() (smtplib.SMTP 的方法)
@anchor{library/smtplib smtplib SMTP ehlo}@anchor{3f39}
@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{3f3a,,has_extn()}.
Also sets several informational attributes: the message returned by
the server is stored as the @ref{3f3b,,ehlo_resp} attribute, @ref{3f3c,,does_esmtp}
is set to @code{True} or @code{False} depending on whether the server supports
ESMTP, and @ref{3f3d,,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{3f3a,,has_extn()} before sending mail, it should not be
necessary to call this method explicitly.  It will be implicitly called by
@ref{1054,,sendmail()} when necessary.
@end deffn

@geindex ehlo_or_helo_if_needed() (smtplib.SMTP 的方法)
@anchor{library/smtplib smtplib SMTP ehlo_or_helo_if_needed}@anchor{3f3e}
@deffn {方法} SMTP.ehlo_or_helo_if_needed ()

This method calls @ref{3f39,,ehlo()} and/or @ref{3f37,,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{3f32,,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{3f3a}
@deffn {方法} SMTP.has_extn (name)

Return @ref{e02,,True} if `name' is in the set of SMTP service extensions returned
by the server, @ref{d23,,False} otherwise. Case is ignored.
@end deffn

@geindex verify() (smtplib.SMTP 的方法)
@anchor{library/smtplib smtplib SMTP verify}@anchor{3f3f}
@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{3f40}
@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{3f32,,SMTPHeloError}

The server didn't reply properly to the @code{HELO} greeting.

@item @ref{3f33,,SMTPAuthenticationError}

The server didn't accept the username/password combination.

@item @ref{1c77,,SMTPNotSupportedError}

The @code{AUTH} command is not supported by the server.

@item @ref{119c,,SMTPException}

No suitable authentication method was found.
@end table

Each of the authentication methods supported by @ref{cf,,smtplib} are tried in
turn if they are advertised as supported by the server.  See @ref{1052,,auth()}
for a list of supported authentication methods.  `initial_response_ok' is
passed through to @ref{1052,,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{1c77,,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{1052}
@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{3f3d,,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{3f40,,login()} method, which will try each of the above mechanisms
in turn, in the order listed.  @code{auth} is exposed to facilitate the
implementation of authentication methods not (or not yet) supported
directly by @ref{cf,,smtplib}.


在 3.5 版被加入.

@end deffn

@geindex starttls() (smtplib.SMTP 的方法)
@anchor{library/smtplib smtplib SMTP starttls}@anchor{1339}
@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{3f39,,ehlo()}
again.

If `keyfile' and `certfile' are provided, they are used to create an
@ref{355,,ssl.SSLContext}.

Optional `context' parameter is an @ref{355,,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{3f32,,SMTPHeloError}

The server didn't reply properly to the @code{HELO} greeting.

@item @ref{1c77,,SMTPNotSupportedError}

The server does not support the STARTTLS extension.

@item @ref{244,,RuntimeError}

SSL/TLS support is not available to your Python interpreter.
@end table


在 3.3 版的變更: 新增 `context'。



在 3.4 版的變更: The method now supports hostname check with
@ref{387a,,ssl.SSLContext.check_hostname} and `Server Name Indicator' (see
@ref{388c,,HAS_SNI}).



在 3.5 版的變更: The error raised for lack of STARTTLS support is now the
@ref{1c77,,SMTPNotSupportedError} subclass instead of the base
@ref{119c,,SMTPException}.

@end deffn

@geindex sendmail() (smtplib.SMTP 的方法)
@anchor{library/smtplib smtplib SMTP sendmail}@anchor{1054}
@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'.  (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{3f2f,,SMTPRecipientsRefused}

All recipients were refused.  Nobody got the mail.

@item @ref{3f32,,SMTPHeloError}

The server didn't reply properly to the @code{HELO} greeting.

@item @ref{3f2e,,SMTPSenderRefused}

The server didn't accept the `from_addr'.

@item @ref{3f31,,SMTPDataError}

The server replied with an unexpected error code (other than a refusal of a
recipient).

@item @ref{1c77,,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{1c77,,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{1055}
@deffn {方法} SMTP.send_message (msg, from_addr=None, to_addrs=None, mail_options=(), rcpt_options=())

This is a convenience method for calling @ref{1054,,sendmail()} with the message
represented by an @ref{57b,,email.message.Message} object.  The arguments have
the same meaning as for @ref{1054,,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{2eb,,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{13d0,,BytesGenerator} with @code{\r\n} as the `linesep', and
calls @ref{1054,,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{1c77,,SMTPNotSupportedError} is raised.  Otherwise the @code{Message} is
serialized with a clone of its @ref{53,,policy} with the
@ref{ff4,,utf8} attribute set to @code{True}, and
@code{SMTPUTF8} and @code{BODY=8BITMIME} are added to `mail_options'.


在 3.2 版被加入.



在 3.5 版被加入: Support for internationalized addresses (@code{SMTPUTF8}).

@end deffn

@geindex quit() (smtplib.SMTP 的方法)
@anchor{library/smtplib smtplib SMTP quit}@anchor{3f29}
@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.

此外，SMTP 實例擁有以下屬性：

@geindex helo_resp (smtplib.SMTP 的屬性)
@anchor{library/smtplib smtplib SMTP helo_resp}@anchor{3f38}
@deffn {屬性} SMTP.helo_resp

The response to the @code{HELO} command, see @ref{3f37,,helo()}.
@end deffn

@geindex ehlo_resp (smtplib.SMTP 的屬性)
@anchor{library/smtplib smtplib SMTP ehlo_resp}@anchor{3f3b}
@deffn {屬性} SMTP.ehlo_resp

The response to the @code{EHLO} command, see @ref{3f39,,ehlo()}.
@end deffn

@geindex does_esmtp (smtplib.SMTP 的屬性)
@anchor{library/smtplib smtplib SMTP does_esmtp}@anchor{3f3c}
@deffn {屬性} SMTP.does_esmtp

A boolean value indicating whether the server supports ESMTP, see
@ref{3f39,,ehlo()}.
@end deffn

@geindex esmtp_features (smtplib.SMTP 的屬性)
@anchor{library/smtplib smtplib SMTP esmtp_features}@anchor{3f3d}
@deffn {屬性} SMTP.esmtp_features

A dictionary of the names of SMTP service extensions supported by the server,
see @ref{3f39,,ehlo()}.
@end deffn

@node SMTP 範例,,SMTP 物件,smtplib --- SMTP 協定用戶端
@anchor{library/smtplib id2}@anchor{3f41}@anchor{library/smtplib smtp-example}@anchor{3f42}
@subsubsection SMTP 範例


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{3f,,email} package's features to
construct an email message, which you can then send
via @ref{1055,,send_message()}; see @ref{1137,,email：範例}.
@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 --- RFC 9562 定義的 UUID 物件,socketserver --- 用於網路伺服器的框架,smtplib --- SMTP 協定用戶端,網路協定 Internet protocols 及支援
@anchor{library/uuid doc}@anchor{3f43}@anchor{library/uuid module-uuid}@anchor{116}@anchor{library/uuid translation-repo}@anchor{3f44}@anchor{library/uuid uuid-uuid-objects-according-to-rfc-9562}@anchor{3f45}
@subsection @code{uuid} --- 
@geindex RFC; RFC 9562
`RFC 9562' 定義的 UUID 物件


@geindex module; uuid

`原始碼：'Lib/uuid.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/uuid.py}


__________________________________________________________________


This module provides immutable @ref{c4d,,UUID} objects (the @ref{c4d,,UUID} class)
and @ref{3f46,,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{d9c,,uuid1()} for UUID version 1, @ref{2e4,,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.

如果你只需要一個唯一的 ID，你應該呼叫 @ref{d9c,,uuid1()} 或 @ref{2e6,,uuid4()}。需要注意的是，@ref{d9c,,uuid1()} 可能會危害隱私，因為它會建立一個包含了電腦網路位址的 UUID。而 @ref{2e6,,uuid4()} 則會建立一個隨機的 UUID。

根據底層平台的支援情況，@ref{d9c,,uuid1()} 可能會也可能不會回傳一個「安全的」UUID。安全的 UUID 是使用同步方法生成的，以確保不會有兩個行程取得到相同的 UUID。所有 @ref{c4d,,UUID} 的實例都有一個 @ref{d9a,,is_safe} 屬性，該屬性使用下面這個列舉來傳遞有關 UUID 安全性的任何資訊：

@geindex SafeUUID (uuid 中的類別)
@anchor{library/uuid uuid SafeUUID}@anchor{3f47}
@deffn {類別} uuid.SafeUUID


在 3.7 版被加入.


@geindex safe (uuid.SafeUUID 的屬性)
@anchor{library/uuid uuid SafeUUID safe}@anchor{3f48}
@deffn {屬性} safe

該 UUID 是由平台以多行程安全的 (multiprocessing-safe) 方式生成的。
@end deffn

@geindex unsafe (uuid.SafeUUID 的屬性)
@anchor{library/uuid uuid SafeUUID unsafe}@anchor{3f49}
@deffn {屬性} unsafe

該 UUID 不是以多行程安全的方式生成的。
@end deffn

@geindex unknown (uuid.SafeUUID 的屬性)
@anchor{library/uuid uuid SafeUUID unknown}@anchor{3f4a}
@deffn {屬性} unknown

該平台不提供 UUID 是否為安全生成的資訊。
@end deffn
@end deffn

@geindex UUID (uuid 中的類別)
@anchor{library/uuid uuid UUID}@anchor{c4d}
@deffn {類別} uuid.UUID (hex=None, bytes=None, bytes_le=None, fields=None, int=None, version=None, *, is_safe=SafeUUID.unknown)

從以下其中一種引數來建立 UUID：由 32 個十六進位的數字組成的字串、以大端順序 (big-endian) 排列的 16 個位元組組成的字串作為 `bytes' 引數、以小端順序 (little-endian) 排列的 16 個位元組組成的字串作為 `bytes_le' 引數、由 6 個整數（32 位元的 `time_low'、16 位元的 `time_mid'、16 位元的 `time_hi_version'、8 位元的 `clock_seq_hi_variant'、8 位元的 `clock_seq_low'、48 位元的 `node'）組成的元組 (tuple) 作為 `fields' 引數，或者是單一的 128 位元整數作為 `int' 引數。當給定由十六進位的數字組成的字串時，大括號、連字符號和 URN 前綴都是可以選用的。例如，以下這些運算式都會產生相同的 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

必須正好給定其中一個引數 `hex'、`bytes'、`bytes_le'、`fields' 或 `int'。`version' 引數是選用的；如果給定了該引數，生成的 UUID 將根據 
@geindex RFC; RFC 9562
RFC 9562@footnote{https://datatracker.ietf.org/doc/html/rfc9562.html} 設置其變體 (variant) 和版本號，覆蓋掉給定的 `hex'、`bytes'、`bytes_le'、`fields' 或 `int' 中的位元。

UUID 物件之間的比較是透過比較它們的 @ref{3f4b,,UUID.int} 屬性。與非 UUID 的物件進行比較會引發 @ref{198,,TypeError}。

@code{str(uuid)} 會回傳一個像是 @code{12345678-1234-5678-1234-567812345678} 形式的字串，其中 32 個十六進位的數字代表 UUID。
@end deffn

@ref{c4d,,UUID} 實例有以下唯讀的屬性：

@geindex bytes (uuid.UUID 的屬性)
@anchor{library/uuid uuid UUID bytes}@anchor{3f4c}
@deffn {屬性} UUID.bytes

UUID 以 16 位元組的字串表示（包含 6 個整數欄位，按照大端位元組順序排列）。
@end deffn

@geindex bytes_le (uuid.UUID 的屬性)
@anchor{library/uuid uuid UUID bytes_le}@anchor{3f4d}
@deffn {屬性} UUID.bytes_le

UUID 以 16 位元組的字串表示（其中 `time_low'、`time_mid' 和 `time_hi_version' 按照小端位元組順序排列）。
@end deffn

@geindex fields (uuid.UUID 的屬性)
@anchor{library/uuid uuid UUID fields}@anchor{3f4e}
@deffn {屬性} UUID.fields

UUID 以 6 個整數欄位所組成的元組表示，也可以看作有 6 個個別屬性和 2 個衍生屬性：
@end deffn


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

欄位

@tab

意義

@item

@geindex time_low (uuid.UUID 的屬性)
@anchor{library/uuid uuid UUID time_low}@anchor{3f4f}
@deffn {屬性} UUID.time_low
@end deffn

@tab

UUID 的前 32 位元。只與版本 1 有關。

@item

@geindex time_mid (uuid.UUID 的屬性)
@anchor{library/uuid uuid UUID time_mid}@anchor{3f50}
@deffn {屬性} UUID.time_mid
@end deffn

@tab

UUID 接下來的 16 位元。只與版本 1 有關。

@item

@geindex time_hi_version (uuid.UUID 的屬性)
@anchor{library/uuid uuid UUID time_hi_version}@anchor{3f51}
@deffn {屬性} UUID.time_hi_version
@end deffn

@tab

UUID 接下來的 16 位元。只與版本 1 有關。

@item

@geindex clock_seq_hi_variant (uuid.UUID 的屬性)
@anchor{library/uuid uuid UUID clock_seq_hi_variant}@anchor{3f52}
@deffn {屬性} UUID.clock_seq_hi_variant
@end deffn

@tab

UUID 接下來的 8 位元。只與版本 1 和 6 有關。

@item

@geindex clock_seq_low (uuid.UUID 的屬性)
@anchor{library/uuid uuid UUID clock_seq_low}@anchor{3f53}
@deffn {屬性} UUID.clock_seq_low
@end deffn

@tab

UUID 接下來的 8 位元。只與版本 1 和 6 有關。

@item

@geindex node (uuid.UUID 的屬性)
@anchor{library/uuid uuid UUID node}@anchor{3f54}
@deffn {屬性} UUID.node
@end deffn

@tab

UUID 最後的 48 位元。只與版本 1 有關。

@item

@geindex time (uuid.UUID 的屬性)
@anchor{library/uuid uuid UUID time}@anchor{3f55}
@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{3f56}
@deffn {屬性} UUID.clock_seq
@end deffn

@tab

14 位元的序列號。只與版本 1 和 6 有關。

@end multitable


@geindex hex (uuid.UUID 的屬性)
@anchor{library/uuid uuid UUID hex}@anchor{1808}
@deffn {屬性} UUID.hex

UUID 以 32 個小寫十六進位字元組成的字串表示。
@end deffn

@geindex int (uuid.UUID 的屬性)
@anchor{library/uuid uuid UUID int}@anchor{3f4b}
@deffn {屬性} UUID.int

UUID 以 128 位元的整數表示。
@end deffn

@geindex urn (uuid.UUID 的屬性)
@anchor{library/uuid uuid UUID urn}@anchor{3f57}
@deffn {屬性} UUID.urn

UUID 以 
@geindex RFC; RFC 9562
RFC 9562@footnote{https://datatracker.ietf.org/doc/html/rfc9562.html} 中指定的 URN 形式表示。
@end deffn

@geindex variant (uuid.UUID 的屬性)
@anchor{library/uuid uuid UUID variant}@anchor{3f58}
@deffn {屬性} UUID.variant

UUID 的變體，決定 UUID 內部的佈局 (layout)，是 @ref{3f59,,RESERVED_NCS}、@ref{3f5a,,RFC_4122}、@ref{3f5b,,RESERVED_MICROSOFT} 或 @ref{3f5c,,RESERVED_FUTURE} 其中一個常數。
@end deffn

@geindex version (uuid.UUID 的屬性)
@anchor{library/uuid uuid UUID version}@anchor{3f5d}
@deffn {屬性} UUID.version

UUID 的版本號（1 到 8，只有當變體是 @ref{3f5a,,RFC_4122} 時才有意義）。


在 3.14 版的變更: 新增了 UUID 版本 6、7 和 8。

@end deffn

@geindex is_safe (uuid.UUID 的屬性)
@anchor{library/uuid uuid UUID is_safe}@anchor{d9a}
@deffn {屬性} UUID.is_safe

@ref{3f47,,SafeUUID} 的列舉，表示平台是否以多行程安全的方式產生 UUID。


在 3.7 版被加入.

@end deffn

@ref{116,,uuid} 模組定義了以下函式：

@geindex getnode() (於 uuid 模組中)
@anchor{library/uuid uuid getnode}@anchor{d9b}
@deffn {函式} uuid.getnode ()

取得 48 位元正整數形式的硬體位址。第一次執行時，有可能會啟動一個獨立的程式，這也許會相當耗時。如果所有取得硬體位址的嘗試都失敗，我們會根據 
@geindex RFC; RFC 4122
RFC 4122@footnote{https://datatracker.ietf.org/doc/html/rfc4122.html} 中的建議，使用一個 48 位元的隨機數，其中群播位元 (multicast bit)（第一個八位元組的最低有效位）設置為 1。「硬體位址」指的是網路介面 (network interface) 的 MAC 位址。在具有多個網路介面的機器上，將優先選擇通用管理 (universally administered) 的 MAC 位址（即第一個八位元組的第二個最低有效位是 `未設置的'），而不是本地管理 (locally administered) 的 MAC 位址，除此之外不保證任何選擇的順序。


在 3.7 版的變更: 通用管理的 MAC 位址優於本地管理的 MAC 位址，因為前者保證是全球唯一的，而後者不是。

@end deffn

@geindex uuid1() (於 uuid 模組中)
@anchor{library/uuid uuid-factory-functions}@anchor{3f46}@anchor{library/uuid uuid uuid1}@anchor{d9c}
@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{d9b,,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{2e4}
@deffn {函式} uuid.uuid3 (namespace, name)

根據 
@geindex RFC; RFC 9562 Section 5.3
RFC 9562@comma{} §5.3@footnote{https://datatracker.ietf.org/doc/html/rfc9562.html#section-5.3}，基於命名空間識別碼 (namespace identifier)（一個 UUID）和名稱（一個 @ref{192,,bytes} 物件或使用 UTF-8 編碼的字串）的 MD5 hash 來生成 UUID。
@end deffn

@geindex uuid4() (於 uuid 模組中)
@anchor{library/uuid uuid uuid4}@anchor{2e6}
@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{2e5}
@deffn {函式} uuid.uuid5 (namespace, name)

根據 
@geindex RFC; RFC 9562 Section 5.5
RFC 9562@comma{} §5.5@footnote{https://datatracker.ietf.org/doc/html/rfc9562.html#section-5.5}，基於命名空間識別碼（一個 UUID）和名稱（一個 @ref{192,,bytes} 物件或使用 UTF-8 編碼的字串）的 SHA-1 hash 來生成 UUID。
@end deffn

@geindex uuid6() (於 uuid 模組中)
@anchor{library/uuid uuid uuid6}@anchor{2c2}
@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{d9c,,uuid1()} to improve database locality.

When `node' is not specified, @ref{d9b,,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.


在 3.14 版被加入.

@end deffn

@geindex uuid7() (於 uuid 模組中)
@anchor{library/uuid uuid uuid7}@anchor{2c3}
@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.


在 3.14 版被加入.

@end deffn

@geindex uuid8() (於 uuid 模組中)
@anchor{library/uuid uuid uuid8}@anchor{2c4}
@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{2e6,,uuid4()} when
a UUID needs to be used in a security-sensitive context.


在 3.14 版被加入.

@end deffn

@ref{116,,uuid} 模組為 @ref{2e4,,uuid3()} 或 @ref{2e5,,uuid5()} 定義了以下的命名空間識別碼。

@geindex NAMESPACE_DNS (於 uuid 模組中)
@anchor{library/uuid uuid NAMESPACE_DNS}@anchor{3f5e}
@deffn {資料} uuid.NAMESPACE_DNS

當指定這個命名空間時，`name' 字串是一個完整網域名稱 (fully qualified domain name)。
@end deffn

@geindex NAMESPACE_URL (於 uuid 模組中)
@anchor{library/uuid uuid NAMESPACE_URL}@anchor{3f5f}
@deffn {資料} uuid.NAMESPACE_URL

當指定這個命名空間時，`name' 字串是一個 URL。
@end deffn

@geindex NAMESPACE_OID (於 uuid 模組中)
@anchor{library/uuid uuid NAMESPACE_OID}@anchor{3f60}
@deffn {資料} uuid.NAMESPACE_OID

當指定這個命名空間時，`name' 字串是一個 ISO OID。
@end deffn

@geindex NAMESPACE_X500 (於 uuid 模組中)
@anchor{library/uuid uuid NAMESPACE_X500}@anchor{3f61}
@deffn {資料} uuid.NAMESPACE_X500

當指定這個命名空間時，`name' 字串是以 DER 或文字輸出格式表示的 X.500 DN。
@end deffn

@ref{116,,uuid} 模組為 @ref{3f58,,variant} 屬性的可能值定義了以下常數：

@geindex RESERVED_NCS (於 uuid 模組中)
@anchor{library/uuid uuid RESERVED_NCS}@anchor{3f59}
@deffn {資料} uuid.RESERVED_NCS

保留供 NCS 相容性使用。
@end deffn

@geindex RFC_4122 (於 uuid 模組中)
@anchor{library/uuid uuid RFC_4122}@anchor{3f5a}
@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{3f5b}
@deffn {資料} uuid.RESERVED_MICROSOFT

保留供 Microsoft 相容性使用。
@end deffn

@geindex RESERVED_FUTURE (於 uuid 模組中)
@anchor{library/uuid uuid RESERVED_FUTURE}@anchor{3f5c}
@deffn {資料} uuid.RESERVED_FUTURE

保留供未來定義使用。
@end deffn

@ref{116,,uuid} 模組定義了特殊的 Nil 和 Max UUID 值：

@geindex NIL (於 uuid 模組中)
@anchor{library/uuid uuid NIL}@anchor{2c5}
@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}.


在 3.14 版被加入.

@end deffn

@geindex MAX (於 uuid 模組中)
@anchor{library/uuid uuid MAX}@anchor{2c6}
@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}.


在 3.14 版被加入.

@end deffn


@subsubheading 也參考



@table @asis

@geindex RFC; RFC 9562

@item RFC 9562@footnote{https://datatracker.ietf.org/doc/html/rfc9562.html} - 通用唯一辨識碼 (UUID, Universally Unique IDentifier) 的 URN 命名空間

這個規範定義了 UUID 的統一資源名稱 (Uniform Resource Name) 命名空間、UUID 的內部格式和生成 UUID 的方法。
@end table


@menu
* 命令列的用法:: 
* 範例: 範例<38>. 
* 命令列的範例:: 

@end menu

@node 命令列的用法,範例<38>,,uuid --- RFC 9562 定義的 UUID 物件
@anchor{library/uuid command-line-usage}@anchor{3f62}@anchor{library/uuid uuid-cli}@anchor{66e}
@subsubsection 命令列的用法



在 3.12 版被加入.


@ref{116,,uuid} 模組可以在命令列下作為腳本來執行。

@example
python -m uuid [-h] [-u @{uuid1,uuid3,uuid4,uuid5,uuid6,uuid7,uuid8@}] [-n NAMESPACE] [-N NAME]
@end example

可以接受以下選項：

@geindex uuid 命令列選項; -h
@geindex uuid 命令列選項; --help
@anchor{library/uuid cmdoption-uuid-h}@anchor{3f63}@anchor{library/uuid cmdoption-uuid-help}@anchor{3f64}
@deffn {Option} @w{-}h, @w{-}@w{-}help

顯示幫助訊息並退出。
@end deffn

@geindex uuid 命令列選項; -u
@geindex uuid 命令列選項; --uuid
@anchor{library/uuid cmdoption-uuid-u}@anchor{3f65}
@deffn {Option} @w{-}u <uuid>
@anchor{library/uuid cmdoption-uuid-uuid}@anchor{3f66}
@deffnx {Option} @w{-}@w{-}uuid <uuid>

指定要用來生成 UUID 的函式名稱。預設使用 @ref{2e6,,uuid4()}。


在 3.14 版的變更: Allow generating UUID versions 6, 7 and 8.

@end deffn

@geindex uuid 命令列選項; -n
@geindex uuid 命令列選項; --namespace
@anchor{library/uuid cmdoption-uuid-n}@anchor{3f67}
@deffn {Option} @w{-}n <namespace>
@anchor{library/uuid cmdoption-uuid-namespace}@anchor{3f68}
@deffnx {Option} @w{-}@w{-}namespace <namespace>

該命名空間是一個 @code{UUID} 或 @code{@@ns}，其中 @code{ns} 是指知名預定義 UUID 的命名空間名稱，例如 @code{@@dns}、@code{@@url}、@code{@@oid} 和 @code{@@x500}。 只有 @ref{2e4,,uuid3()} / @ref{2e5,,uuid5()} 函式會需要。
@end deffn

@geindex uuid 命令列選項; -N
@geindex uuid 命令列選項; --name
@anchor{library/uuid cmdoption-uuid-N}@anchor{3f69}
@deffn {Option} @w{-}N <name>
@anchor{library/uuid cmdoption-uuid-name}@anchor{3f6a}
@deffnx {Option} @w{-}@w{-}name <name>

用於生成 uuid 的名稱。只有 @ref{2e4,,uuid3()} / @ref{2e5,,uuid5()} 函式會需要。
@end deffn

@geindex uuid 命令列選項; -C
@geindex uuid 命令列選項; --count
@anchor{library/uuid cmdoption-uuid-C}@anchor{3f6b}
@deffn {Option} @w{-}C <num>
@anchor{library/uuid cmdoption-uuid-count}@anchor{2c7}
@deffnx {Option} @w{-}@w{-}count <num>

生成 `num' 個新 UUID。


在 3.14 版被加入.

@end deffn

@node 範例<38>,命令列的範例,命令列的用法,uuid --- RFC 9562 定義的 UUID 物件
@anchor{library/uuid example}@anchor{3f6c}@anchor{library/uuid uuid-example}@anchor{3f6d}
@subsubsection 範例


以下是一些 @ref{116,,uuid} 模組的典型使用範例：

@example
>>> import uuid

>>> # make a UUID based on the host ID and current time
>>> uuid.uuid1()
UUID('a8098c1a-f86e-11da-bd1a-00112444be1e')

>>> # make a UUID using an MD5 hash of a namespace UUID and a name
>>> uuid.uuid3(uuid.NAMESPACE_DNS, 'python.org')
UUID('6fa459ea-ee8a-3ca4-894e-db77e160355e')

>>> # make a random UUID
>>> uuid.uuid4()
UUID('16fd2706-8baf-433b-82eb-8c7fada847da')

>>> # make a UUID using a SHA-1 hash of a namespace UUID and a name
>>> uuid.uuid5(uuid.NAMESPACE_DNS, 'python.org')
UUID('886313e1-3b8a-5372-9b90-0c9aee199e5d')

>>> # make a UUID from a string of hex digits (braces and hyphens ignored)
>>> x = uuid.UUID('@{00010203-0405-0607-0809-0a0b0c0d0e0f@}')

>>> # convert a UUID to a string of hex digits in standard form
>>> str(x)
'00010203-0405-0607-0809-0a0b0c0d0e0f'

>>> # get the raw 16 bytes of the UUID
>>> x.bytes
b'\x00\x01\x02\x03\x04\x05\x06\x07\x08\t\n\x0b\x0c\r\x0e\x0f'

>>> # make a UUID from a 16-byte string
>>> uuid.UUID(bytes=x.bytes)
UUID('00010203-0405-0607-0809-0a0b0c0d0e0f')

>>> # 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 命令列的範例,,範例<38>,uuid --- RFC 9562 定義的 UUID 物件
@anchor{library/uuid command-line-example}@anchor{3f6e}@anchor{library/uuid uuid-cli-example}@anchor{3f6f}
@subsubsection 命令列的範例


以下是一些 @ref{116,,uuid} 命令列介面的典型使用範例：

@example
# 生成一個隨機的 UUID - 預設使用 uuid4()
$ python -m uuid

# 使用 uuid1() 生成一組 UUID
$ python -m uuid -u uuid1

# 使用 uuid5 生成一組 UUID
$ python -m uuid -u uuid5 -n @@url -N example.com

# 生成 42 個隨機 UUID
$ 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 --- 用於網路伺服器的框架,http server — HTTP 伺服器,uuid --- RFC 9562 定義的 UUID 物件,網路協定 Internet protocols 及支援
@anchor{library/socketserver doc}@anchor{3f70}@anchor{library/socketserver module-socketserver}@anchor{d2}@anchor{library/socketserver socketserver-a-framework-for-network-servers}@anchor{3f71}@anchor{library/socketserver translation-repo}@anchor{3f72}
@subsection @code{socketserver} --- 用於網路伺服器的框架


@geindex module; socketserver

`原始碼：'Lib/socketserver.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/socketserver.py}


__________________________________________________________________


The @ref{d2,,socketserver} module simplifies the task of writing network servers.

@c include for modules that don't work on WASM

@ref{2006,,可用性}: not WASI.

此模組在 WebAssembly 平台上不起作用或無法使用。更多資訊請參閱 @ref{1a99,,WebAssembly 平台}。

There are four basic concrete server classes:

@geindex TCPServer (socketserver 中的類別)
@anchor{library/socketserver socketserver TCPServer}@anchor{1520}
@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{3f73,,server_bind()} and
@ref{3f74,,server_activate()}.  The other parameters are passed to
the @ref{133e,,BaseServer} base class.
@end deffn

@geindex UDPServer (socketserver 中的類別)
@anchor{library/socketserver socketserver UDPServer}@anchor{3f75}
@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{1520,,TCPServer}.
@end deffn

@geindex UnixStreamServer (socketserver 中的類別)
@geindex UnixDatagramServer (socketserver 中的類別)
@anchor{library/socketserver socketserver UnixStreamServer}@anchor{3f76}
@deffn {類別} socketserver.UnixStreamServer (server_address, RequestHandlerClass, bind_and_activate=True)
@anchor{library/socketserver socketserver UnixDatagramServer}@anchor{3f77}
@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{1520,,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{d69,,ForkingMixIn} and @ref{d32,,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{3f78,,BaseRequestHandler} class and
overriding its @ref{3f79,,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{186,,with} statement. Then call the
@ref{1523,,handle_request()} or
@ref{1340,,serve_forever()} method of the server object to
process one or many requests.  Finally, call @ref{d67,,server_close()}
to close the socket (unless you used a @code{with} statement).

When inheriting from @ref{d32,,ThreadingMixIn} for threaded connection behavior,
you should explicitly declare how you want your threads to behave on an abrupt
shutdown.  The @ref{d32,,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{d23,,False}, meaning that
Python will not exit until all threads created by @ref{d32,,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:: 
* 範例: 範例<39>. 

@end menu

@node Server Creation Notes,Server Objects,,socketserver --- 用於網路伺服器的框架
@anchor{library/socketserver server-creation-notes}@anchor{3f7a}
@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{3f77,,UnixDatagramServer} derives from @ref{3f75,,UDPServer}, not from
@ref{3f76,,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{d69}
@deffn {類別} socketserver.ForkingMixIn
@anchor{library/socketserver socketserver ThreadingMixIn}@anchor{d32}
@deffnx {類別} socketserver.ThreadingMixIn

Forking and threading versions of each type of server can be created
using these mix-in classes.  For instance, @ref{3f7b,,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{3f75,,UDPServer}.  Setting the various attributes also changes the
behavior of the underlying server mechanism.

@ref{d69,,ForkingMixIn} and the Forking classes mentioned below are
only available on POSIX platforms that support @ref{4b0,,fork()}.

@geindex block_on_close (socketserver.ThreadingMixIn 的屬性)
@anchor{library/socketserver socketserver ThreadingMixIn block_on_close}@anchor{d68}
@deffn {屬性} block_on_close

@ref{d67,,ForkingMixIn.server_close}
waits until all child processes complete, except if
@ref{d68,,block_on_close} attribute is @code{False}.

@ref{d67,,ThreadingMixIn.server_close}
waits until all non-daemon threads complete, except if
@ref{d68,,block_on_close} attribute is @code{False}.
@end deffn

@geindex max_children (socketserver.ThreadingMixIn 的屬性)
@anchor{library/socketserver socketserver ThreadingMixIn max_children}@anchor{3f7c}
@deffn {屬性} max_children

Specify how many child processes will exist to handle requests at a time
for @ref{d69,,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{3f7d}
@deffn {屬性} daemon_threads

For @ref{d32,,ThreadingMixIn} use daemonic threads by setting
@ref{3f7d,,ThreadingMixIn.daemon_threads}
to @code{True} to not wait until threads complete.
@end deffn


在 3.7 版的變更: @ref{d67,,ForkingMixIn.server_close} and
@ref{d67,,ThreadingMixIn.server_close} now waits until all
child processes and non-daemonic threads complete.
Add a new @ref{d68,,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{3f7e}
@deffn {類別} socketserver.ForkingTCPServer
@anchor{library/socketserver socketserver ForkingUDPServer}@anchor{3f7f}
@deffnx {類別} socketserver.ForkingUDPServer
@anchor{library/socketserver socketserver ThreadingTCPServer}@anchor{3f80}
@deffnx {類別} socketserver.ThreadingTCPServer
@anchor{library/socketserver socketserver ThreadingUDPServer}@anchor{3f7b}
@deffnx {類別} socketserver.ThreadingUDPServer
@anchor{library/socketserver socketserver ForkingUnixStreamServer}@anchor{3f81}
@deffnx {類別} socketserver.ForkingUnixStreamServer
@anchor{library/socketserver socketserver ForkingUnixDatagramServer}@anchor{3f82}
@deffnx {類別} socketserver.ForkingUnixDatagramServer
@anchor{library/socketserver socketserver ThreadingUnixStreamServer}@anchor{3f83}
@deffnx {類別} socketserver.ThreadingUnixStreamServer
@anchor{library/socketserver socketserver ThreadingUnixDatagramServer}@anchor{3f84}
@deffnx {類別} socketserver.ThreadingUnixDatagramServer

These classes are pre-defined using the mix-in classes.
@end deffn


在 3.12 版被加入: The @code{ForkingUnixStreamServer} and @code{ForkingUnixDatagramServer} classes
were added.


To implement a service, you must derive a class from @ref{3f78,,BaseRequestHandler}
and redefine its @ref{3f79,,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{ed1,,StreamRequestHandler} or @ref{3f85,,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{3f79,,handle()} method.

Another approach to handling multiple simultaneous requests in an environment
that supports neither threads nor @ref{4b0,,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{c7,,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 --- 用於網路伺服器的框架
@anchor{library/socketserver server-objects}@anchor{3f86}
@subsubsection Server Objects


@geindex BaseServer (socketserver 中的類別)
@anchor{library/socketserver socketserver BaseServer}@anchor{133e}
@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{3f87,,server_address} and @ref{3f88,,RequestHandlerClass} attributes.

@geindex fileno() (socketserver.BaseServer 的方法)
@anchor{library/socketserver socketserver BaseServer fileno}@anchor{3f89}
@deffn {方法} fileno ()

Return an integer file descriptor for the socket on which the server is
listening.  This function is most commonly passed to @ref{c7,,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{1523}
@deffn {方法} handle_request ()

Process a single request.  This function calls the following methods in
order: @ref{3f8a,,get_request()}, @ref{3f8b,,verify_request()}, and
@ref{3f8c,,process_request()}.  If the user-provided
@ref{3f79,,handle()} method of the
handler class raises an exception, the server's @ref{f38,,handle_error()} method
will be called.  If no request is received within @ref{1521,,timeout}
seconds, @ref{1522,,handle_timeout()} will be called and @ref{1523,,handle_request()}
will return.
@end deffn

@geindex serve_forever() (socketserver.BaseServer 的方法)
@anchor{library/socketserver socketserver BaseServer serve_forever}@anchor{1340}
@deffn {方法} serve_forever (poll_interval=0.5)

Handle requests until an explicit @ref{1cde,,shutdown()} request.  Poll for
shutdown every `poll_interval' seconds.
Ignores the @ref{1521,,timeout} attribute.  It
also calls @ref{133f,,service_actions()}, which may be used by a subclass or mixin
to provide actions specific to a given service.  For example, the
@ref{d69,,ForkingMixIn} class uses @ref{133f,,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{133f}
@deffn {方法} service_actions ()

This is called in the @ref{1340,,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.


在 3.3 版被加入.

@end deffn

@geindex shutdown() (socketserver.BaseServer 的方法)
@anchor{library/socketserver socketserver BaseServer shutdown}@anchor{1cde}
@deffn {方法} shutdown ()

Tell the @ref{1340,,serve_forever()} loop to stop and wait until it does.
@ref{1cde,,shutdown()} must be called while @ref{1340,,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{d67}
@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{3f8d}
@deffn {屬性} address_family

The family of protocols to which the server's socket belongs.  Common
examples are @ref{1ad2,,socket.AF_INET}, @ref{1ad3,,socket.AF_INET6}, and
@ref{1ad5,,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{3f88}
@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{3f87}
@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{d1,,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{3f8e}
@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{3f8f}
@deffn {屬性} allow_reuse_address

Whether the server will allow the reuse of an address.  This defaults to
@ref{d23,,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{3f90}
@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{3f90,,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{3f91}
@deffn {屬性} socket_type

The type of socket used by the server; @ref{14f4,,socket.SOCK_STREAM} and
@ref{14f3,,socket.SOCK_DGRAM} are two common values.
@end deffn

@geindex timeout (socketserver.BaseServer 的屬性)
@anchor{library/socketserver socketserver BaseServer timeout}@anchor{1521}
@deffn {屬性} timeout

Timeout duration, measured in seconds, or @ref{87e,,None} if no timeout is
desired.  If @ref{1523,,handle_request()} receives no incoming requests within the
timeout period, the @ref{1522,,handle_timeout()} method is called.
@end deffn

There are various server methods that can be overridden by subclasses of base
server classes like @ref{1520,,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{3f92}
@deffn {方法} finish_request (request, client_address)

Actually processes the request by instantiating @ref{3f88,,RequestHandlerClass} and
calling its @ref{3f79,,handle()} method.
@end deffn

@geindex get_request() (socketserver.BaseServer 的方法)
@anchor{library/socketserver socketserver BaseServer get_request}@anchor{3f8a}
@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{f38}
@deffn {方法} handle_error (request, client_address)

This function is called if the @ref{3f79,,handle()}
method of a @ref{3f88,,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{bc4,,Exception}
class.

@end deffn

@geindex handle_timeout() (socketserver.BaseServer 的方法)
@anchor{library/socketserver socketserver BaseServer handle_timeout}@anchor{1522}
@deffn {方法} handle_timeout ()

This function is called when the @ref{1521,,timeout} attribute has been set to a
value other than @ref{87e,,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{3f8c}
@deffn {方法} process_request (request, client_address)

Calls @ref{3f92,,finish_request()} to create an instance of the
@ref{3f88,,RequestHandlerClass}.  If desired, this function can create a new process
or thread to handle the request; the @ref{d69,,ForkingMixIn} and
@ref{d32,,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{3f74}
@deffn {方法} server_activate ()

Called by the server's constructor to activate the server.  The default behavior
for a TCP server just invokes @ref{1059,,listen()}
on the server's socket.  May be overridden.
@end deffn

@geindex server_bind() (socketserver.BaseServer 的方法)
@anchor{library/socketserver socketserver BaseServer server_bind}@anchor{3f73}
@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{3f8b}
@deffn {方法} verify_request (request, client_address)

Must return a Boolean value; if the value is @ref{e02,,True}, the request will
be processed, and if it's @ref{d23,,False}, the request will be denied.  This
function can be overridden to implement access controls for a server. The
default implementation always returns @ref{e02,,True}.
@end deffn


在 3.6 版的變更: Support for the @ref{1e1,,context manager} protocol was added.  Exiting the
context manager is equivalent to calling @ref{d67,,server_close()}.

@end deffn

@node Request Handler Objects,範例<39>,Server Objects,socketserver --- 用於網路伺服器的框架
@anchor{library/socketserver request-handler-objects}@anchor{3f93}
@subsubsection Request Handler Objects


@geindex BaseRequestHandler (socketserver 中的類別)
@anchor{library/socketserver socketserver BaseRequestHandler}@anchor{3f78}
@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{3f79,,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{3f94}
@deffn {方法} setup ()

Called before the @ref{3f79,,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{3f79}
@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{3f95,,request}; the client
address as @ref{3f96,,client_address}; and the server instance as
@ref{3f97,,server}, in case it needs access to per-server information.

The type of @ref{3f95,,request} is different for datagram or stream
services.  For stream services, @ref{3f95,,request} is a socket object; for
datagram services, @ref{3f95,,request} is a pair of string and socket.
@end deffn

@geindex finish() (socketserver.BaseRequestHandler 的方法)
@anchor{library/socketserver socketserver BaseRequestHandler finish}@anchor{3f98}
@deffn {方法} finish ()

Called after the @ref{3f79,,handle()} method to perform any clean-up actions
required.  The default implementation does nothing.  If @ref{3f94,,setup()}
raises an exception, this function will not be called.
@end deffn

@geindex request (socketserver.BaseRequestHandler 的屬性)
@anchor{library/socketserver socketserver BaseRequestHandler request}@anchor{3f95}
@deffn {屬性} request

The `new' @ref{f9c,,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{3f96}
@deffn {屬性} client_address

Client address returned by @ref{3f8a,,BaseServer.get_request()}.
@end deffn

@geindex server (socketserver.BaseRequestHandler 的屬性)
@anchor{library/socketserver socketserver BaseRequestHandler server}@anchor{3f97}
@deffn {屬性} server

@ref{133e,,BaseServer} object used for handling the request.
@end deffn
@end deffn

@geindex StreamRequestHandler (socketserver 中的類別)
@geindex DatagramRequestHandler (socketserver 中的類別)
@anchor{library/socketserver socketserver StreamRequestHandler}@anchor{ed1}
@deffn {類別} socketserver.StreamRequestHandler
@anchor{library/socketserver socketserver DatagramRequestHandler}@anchor{3f85}
@deffnx {類別} socketserver.DatagramRequestHandler

These @ref{3f78,,BaseRequestHandler} subclasses override the
@ref{3f94,,setup()} and @ref{3f98,,finish()}
methods, and provide @ref{3f99,,rfile} and @ref{ed0,,wfile} attributes.

@geindex rfile (socketserver.DatagramRequestHandler 的屬性)
@anchor{library/socketserver socketserver DatagramRequestHandler rfile}@anchor{3f99}
@deffn {屬性} rfile

A file object from which receives the request is read.
Support the @ref{89c,,io.BufferedIOBase} readable interface.
@end deffn

@geindex wfile (socketserver.DatagramRequestHandler 的屬性)
@anchor{library/socketserver socketserver DatagramRequestHandler wfile}@anchor{ed0}
@deffn {屬性} wfile

A file object to which the reply is written.
Support the @ref{89c,,io.BufferedIOBase} writable interface
@end deffn


在 3.6 版的變更: @ref{ed0,,wfile} also supports the
@ref{89c,,io.BufferedIOBase} writable interface.

@end deffn

@node 範例<39>,,Request Handler Objects,socketserver --- 用於網路伺服器的框架
@anchor{library/socketserver examples}@anchor{3f9a}
@subsubsection 範例


@menu
* socketserver.TCPServer 範例: socketserver TCPServer 範例. 
* socketserver.UDPServer 範例: socketserver UDPServer 範例. 
* Asynchronous Mixins:: 

@end menu

@node socketserver TCPServer 範例,socketserver UDPServer 範例,,範例<39>
@anchor{library/socketserver socketserver-tcpserver-example}@anchor{3f9b}
@subsubsection @code{socketserver.TCPServer} 範例


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 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 範例,Asynchronous Mixins,socketserver TCPServer 範例,範例<39>
@anchor{library/socketserver socketserver-udpserver-example}@anchor{3f9c}
@subsubsection @code{socketserver.UDPServer} 範例


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 範例,範例<39>
@anchor{library/socketserver asynchronous-mixins}@anchor{3f9d}
@subsubsection Asynchronous Mixins


To build asynchronous handlers, use the @ref{d32,,ThreadingMixIn} and
@ref{d69,,ForkingMixIn} classes.

An example for the @ref{d32,,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{d69,,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{4b0,,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 伺服器,http cookies --- HTTP 狀態管理,socketserver --- 用於網路伺服器的框架,網路協定 Internet protocols 及支援
@anchor{library/http server doc}@anchor{3f9e}@anchor{library/http server http-server-http-servers}@anchor{3f9f}@anchor{library/http server module-http server}@anchor{76}@anchor{library/http server translation-repo}@anchor{3fa0}
@subsection @code{http.server} — HTTP 伺服器


@geindex module; http.server

`原始碼：'Lib/http/server.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/http/server.py}

@geindex WWW;server（伺服器）
@geindex HTTP;protocol（協定）
@geindex URL（統一資源定位器）
@geindex httpd


__________________________________________________________________


此模組定義了用於實作 HTTP 伺服器的類別。

@cartouche
@quotation 警告 
@ref{76,,http.server} is not recommended for production. It only implements
@ref{3fa1,,basic security checks}.
@end quotation
@end cartouche

@c include for modules that don't work on WASM

@ref{2006,,可用性}: not WASI.

此模組在 WebAssembly 平台上不起作用或無法使用。更多資訊請參閱 @ref{1a99,,WebAssembly 平台}。

One class, @ref{3d9e,,HTTPServer}, is a @ref{1520,,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{3d9e}
@deffn {類別} http.server.HTTPServer (server_address, RequestHandlerClass)

This class builds on the @ref{1520,,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{d31}
@deffn {類別} http.server.ThreadingHTTPServer (server_address, RequestHandlerClass)

This class is identical to HTTPServer but uses threads to handle
requests by using the @ref{d32,,ThreadingMixIn}. This
is useful to handle web browsers pre-opening sockets, on which
@ref{3d9e,,HTTPServer} would wait indefinitely.


在 3.7 版被加入.

@end deffn

@geindex HTTPSServer (http.server 中的類別)
@anchor{library/http server http server HTTPSServer}@anchor{228}
@deffn {類別} http.server.HTTPSServer (server_address, RequestHandlerClass, bind_and_activate=True, *, certfile, keyfile=None, password=None, alpn_protocols=None)

Subclass of @ref{3d9e,,HTTPServer} with a wrapped socket using the @ref{d5,,ssl} module.
If the @ref{d5,,ssl} module is not available, instantiating a @code{HTTPSServer}
object fails with a @ref{244,,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{592,,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.


在 3.14 版被加入.

@end deffn

@geindex ThreadingHTTPSServer (http.server 中的類別)
@anchor{library/http server http server ThreadingHTTPSServer}@anchor{3fa2}
@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{228,,HTTPSServer} but uses threads to handle
requests by inheriting from @ref{d32,,ThreadingMixIn}. This is
analogous to @ref{d31,,ThreadingHTTPServer} only using @ref{228,,HTTPSServer}.


在 3.14 版被加入.

@end deffn

The @ref{3d9e,,HTTPServer}, @ref{d31,,ThreadingHTTPServer}, @ref{228,,HTTPSServer} and
@ref{3fa2,,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{12cc}
@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 (e.g. GET or POST).
@ref{12cc,,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.

@ref{12cc,,BaseHTTPRequestHandler} 有以下實例變數：

@geindex client_address (http.server.BaseHTTPRequestHandler 的屬性)
@anchor{library/http server http server BaseHTTPRequestHandler client_address}@anchor{3fa3}
@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{3fa4}
@deffn {屬性} server

Contains the server instance.
@end deffn

@geindex close_connection (http.server.BaseHTTPRequestHandler 的屬性)
@anchor{library/http server http server BaseHTTPRequestHandler close_connection}@anchor{3fa5}
@deffn {屬性} close_connection

Boolean that should be set before @ref{3fa6,,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{3fa7}
@deffn {屬性} requestline

Contains the string representation of the HTTP request line. The
terminating CRLF is stripped. This attribute should be set by
@ref{3fa6,,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{3fa8}
@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{3fa9}
@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{3faa}
@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{3e83}
@deffn {屬性} headers

Holds an instance of the class specified by the @ref{3fab,,MessageClass} class
variable. This instance parses and manages the headers in the HTTP
request. The @ref{1cf1,,parse_headers()} function from
@ref{73,,http.client} is used to parse the headers and it requires that the
HTTP request provide a valid 
@geindex RFC; RFC 2822
RFC 2822@footnote{https://datatracker.ietf.org/doc/html/rfc2822.html} style header.
@end deffn

@geindex rfile (http.server.BaseHTTPRequestHandler 的屬性)
@anchor{library/http server http server BaseHTTPRequestHandler rfile}@anchor{3fac}
@deffn {屬性} rfile

An @ref{89c,,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{3fad}
@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{89c,,io.BufferedIOBase} stream.

@end deffn

@ref{12cc,,BaseHTTPRequestHandler} 擁有以下屬性：

@geindex server_version (http.server.BaseHTTPRequestHandler 的屬性)
@anchor{library/http server http server BaseHTTPRequestHandler server_version}@anchor{3fae}
@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{3faf}
@deffn {屬性} sys_version

Contains the Python system version, in a form usable by the
@ref{3fb0,,version_string} method and the @ref{3fae,,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{114b}
@deffn {屬性} error_message_format

Specifies a format string that should be used by @ref{114a,,send_error()} method
for building an error response to the client. The string is filled by
default with variables from @ref{3e68,,responses} based on the status code
that passed to @ref{114a,,send_error()}.
@end deffn

@geindex error_content_type (http.server.BaseHTTPRequestHandler 的屬性)
@anchor{library/http server http server BaseHTTPRequestHandler error_content_type}@anchor{3fb1}
@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{3fb2}
@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{3fb3,,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{3fab}
@deffn {屬性} MessageClass

Specifies an @ref{57b,,email.message.Message}-like class to parse HTTP
headers.  Typically, this is not overridden, and it defaults to
@ref{3e81,,http.client.HTTPMessage}.
@end deffn

@geindex responses (http.server.BaseHTTPRequestHandler 的屬性)
@anchor{library/http server http server BaseHTTPRequestHandler responses}@anchor{3e68}
@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{3fb4,,send_response_only()} and @ref{114a,,send_error()} methods.
@end deffn

@ref{12cc,,BaseHTTPRequestHandler} 實例擁有以下方法：

@geindex handle() (http.server.BaseHTTPRequestHandler 的方法)
@anchor{library/http server http server BaseHTTPRequestHandler handle}@anchor{3fb5}
@deffn {方法} handle ()

Calls @ref{3fa6,,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{3fa6}
@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{3fb6}
@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 e.g. server can choose to send @code{417
Expectation Failed} as a response header and @code{return False}.


在 3.2 版被加入.

@end deffn

@geindex send_error() (http.server.BaseHTTPRequestHandler 的方法)
@anchor{library/http server http server BaseHTTPRequestHandler send_error}@anchor{114a}
@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{114b,,error_message_format} attribute and emitted, after
a complete set of headers, as the response body.  The @ref{3e68,,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{3fb7}
@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{3fb0,,version_string()} and
@ref{3fb8,,date_time_string()} methods, respectively. If the server does not
intend to send any other headers using the @ref{3fb3,,send_header()} method,
then @ref{3fb7,,send_response()} should be followed by an @ref{12cd,,end_headers()}
call.


在 3.3 版的變更: Headers are stored to an internal buffer and @ref{12cd,,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{3fb3}
@deffn {方法} send_header (keyword, value)

Adds the HTTP header to an internal buffer which will be written to the
output stream when either @ref{12cd,,end_headers()} or @ref{12ce,,flush_headers()} is
invoked. `keyword' should specify the header keyword, with `value'
specifying its value. Note that, after the send_header calls are done,
@ref{12cd,,end_headers()} MUST BE called in order to complete the operation.


在 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{3fb4}
@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.


在 3.2 版被加入.

@end deffn

@geindex end_headers() (http.server.BaseHTTPRequestHandler 的方法)
@anchor{library/http server http server BaseHTTPRequestHandler end_headers}@anchor{12cd}
@deffn {方法} end_headers ()

Adds a blank line
(indicating the end of the HTTP headers in the response)
to the headers buffer and calls @ref{12ce,,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{12ce}
@deffn {方法} flush_headers ()

Finally send the headers to the output stream and flush the internal
headers buffer.


在 3.3 版被加入.

@end deffn

@geindex log_request() (http.server.BaseHTTPRequestHandler 的方法)
@anchor{library/http server http server BaseHTTPRequestHandler log_request}@anchor{3fb9}
@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{3fba}
@deffn {方法} log_error (...)

Logs an error when a request cannot be fulfilled. By default, it passes
the message to @ref{3fbb,,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{3fbb}
@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
@ref{3fbb,,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{3fb0}
@deffn {方法} version_string ()

Returns the server software's version string. This is a combination of the
@ref{3fae,,server_version} and @ref{3faf,,sys_version} attributes.
@end deffn

@geindex date_time_string() (http.server.BaseHTTPRequestHandler 的方法)
@anchor{library/http server http server BaseHTTPRequestHandler date_time_string}@anchor{3fb8}
@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{557,,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{3fbc}
@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{3fbd}
@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{d30}
@deffn {類別} http.server.SimpleHTTPRequestHandler (request, client_address, server, directory=None)

This class serves files from the directory `directory' and below,
or the current directory if `directory' is not provided, directly
mapping the directory structure to HTTP requests.


在 3.7 版的變更: 新增 `directory' 參數。



在 3.9 版的變更: The `directory' parameter accepts a @ref{59b,,path-like object}.


A lot of the work, such as parsing the request, is done by the base class
@ref{12cc,,BaseHTTPRequestHandler}.  This class implements the @ref{3fbe,,do_GET()}
and @ref{3fbf,,do_HEAD()} functions.

The following are defined as class-level attributes of
@ref{d30,,SimpleHTTPRequestHandler}:

@geindex server_version (http.server.SimpleHTTPRequestHandler 的屬性)
@anchor{library/http server http server SimpleHTTPRequestHandler server_version}@anchor{3fc0}
@deffn {屬性} server_version

This will be @code{"SimpleHTTP/" + __version__}, where @code{__version__} is
defined at the module level.
@end deffn

@geindex extensions_map (http.server.SimpleHTTPRequestHandler 的屬性)
@anchor{library/http server http server SimpleHTTPRequestHandler extensions_map}@anchor{3fc1}
@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

@ref{d30,,SimpleHTTPRequestHandler} 類別定義了以下方法：

@geindex do_HEAD() (http.server.SimpleHTTPRequestHandler 的方法)
@anchor{library/http server http server SimpleHTTPRequestHandler do_HEAD}@anchor{3fbf}
@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{3fbe,,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{3fbe}
@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{12fb,,os.listdir()} to scan the directory, and returns a @code{404} error
response if the @ref{12fb,,listdir()} fails.

If the request was mapped to a file, it is opened. Any @ref{2c0,,OSError}
exception in opening the requested file is mapped to a @code{404},
@code{'File not found'} error. If there was an @code{'If-Modified-Since'}
header in the request, and the file was not modified after this time,
a @code{304}, @code{'Not Modified'} response is sent. Otherwise, the content
type is guessed by calling the @code{guess_type()} method, which in turn
uses the `extensions_map' variable, and the file contents are returned.

A @code{'Content-type:'} header with the guessed content type is output,
followed by a @code{'Content-Length:'} header with the file's size and a
@code{'Last-Modified:'} header with the file's modification time.

Then follows a blank line signifying the end of the headers, and then the
contents of the file are output.

For example usage, see the implementation of the @code{test} function
in Lib/http/server.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/http/server.py}.


在 3.7 版的變更: Support of the @code{'If-Modified-Since'} header.

@end deffn
@end deffn

The @ref{d30,,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{d30,,SimpleHTTPRequestHandler} can also be subclassed to enhance behavior,
such as using different index file names by overriding the class attribute
@code{index_pages}.

@geindex CGIHTTPRequestHandler (http.server 中的類別)
@anchor{library/http server http server CGIHTTPRequestHandler}@anchor{324}
@deffn {類別} http.server.CGIHTTPRequestHandler (request, client_address, server)

This class is used to serve either files or output of CGI scripts from the
current directory and below. Note that mapping HTTP hierarchic structure to
local directory structure is exactly as in @ref{d30,,SimpleHTTPRequestHandler}.

@cartouche
@quotation 備註 
CGI scripts run by the @ref{324,,CGIHTTPRequestHandler} class cannot execute
redirects (HTTP code 302), because code 200 (script output follows) is
sent prior to execution of the CGI script.  This pre-empts the status
code.
@end quotation
@end cartouche

The class will however, run the CGI script, instead of serving it as a file,
if it guesses it to be a CGI script.  Only directory-based CGI are used ---
the other common server configuration is to treat special extensions as
denoting CGI scripts.

The @code{do_GET()} and @code{do_HEAD()} functions are modified to run CGI scripts
and serve the output, instead of serving files, if the request leads to
somewhere below the @code{cgi_directories} path.

@ref{324,,CGIHTTPRequestHandler} 類別定義了以下資料成員：

@geindex cgi_directories (http.server.CGIHTTPRequestHandler 的屬性)
@anchor{library/http server http server CGIHTTPRequestHandler cgi_directories}@anchor{3fc2}
@deffn {屬性} cgi_directories

This defaults to @code{['/cgi-bin', '/htbin']} and describes directories to
treat as containing CGI scripts.
@end deffn

@ref{324,,CGIHTTPRequestHandler} 類別定義了以下方法：

@geindex do_POST() (http.server.CGIHTTPRequestHandler 的方法)
@anchor{library/http server http server CGIHTTPRequestHandler do_POST}@anchor{3fc3}
@deffn {方法} do_POST ()

This method serves the @code{'POST'} request type, only allowed for CGI
scripts.  Error 501, "Can only POST to CGI scripts", is output when trying
to POST to a non-CGI url.
@end deffn

Note that CGI scripts will be run with UID of user nobody, for security
reasons.  Problems with the CGI script will be translated to error 403.


Deprecated since version 3.13, will be removed in version 3.15: @ref{324,,CGIHTTPRequestHandler} is being removed in 3.15.  CGI has not
been considered a good way to do things for well over a decade. This code
has been unmaintained for a while now and sees very little practical use.
Retaining it could lead to further @ref{3fa1,,security considerations}.

@end deffn

@menu
* 命令列介面: 命令列介面<7>. 
* 安全性注意事項: 安全性注意事項<3>. 

@end menu

@node 命令列介面<7>,安全性注意事項<3>,,http server — HTTP 伺服器
@anchor{library/http server command-line-interface}@anchor{3fc4}@anchor{library/http server http-server-cli}@anchor{114c}
@subsubsection 命令列介面


@ref{76,,http.server} can also be invoked directly using the @ref{23c,,-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

可接受以下選項：

@geindex http.server 命令列選項; port
@anchor{library/http server cmdoption-http server-arg-port}@anchor{3fc5}
@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 命令列選項; -b
@geindex http.server 命令列選項; --bind
@anchor{library/http server cmdoption-http server-b}@anchor{3fc6}@anchor{library/http server cmdoption-http server-bind}@anchor{3fc7}
@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


在 3.4 版被加入.



在 3.8 版的變更: 於 @code{--bind} 選項中支援 IPv6。

@end deffn

@geindex http.server 命令列選項; -d
@geindex http.server 命令列選項; --directory
@anchor{library/http server cmdoption-http server-d}@anchor{17bc}@anchor{library/http server cmdoption-http server-directory}@anchor{3fc8}
@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


在 3.7 版被加入.

@end deffn

@geindex http.server 命令列選項; -p
@geindex http.server 命令列選項; --protocol
@anchor{library/http server cmdoption-http server-p}@anchor{3fc9}@anchor{library/http server cmdoption-http server-protocol}@anchor{3fca}
@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


在 3.11 版被加入.

@end deffn

@geindex http.server 命令列選項; --cgi
@anchor{library/http server cmdoption-http server-cgi}@anchor{3fcb}
@deffn {Option} @w{-}@w{-}cgi

@ref{324,,CGIHTTPRequestHandler} can be enabled in the command line by passing
the @code{--cgi} option:

@example
python -m http.server --cgi
@end example


Deprecated since version 3.13, will be removed in version 3.15: @ref{76,,http.server} command line @code{--cgi} support is being removed
because @ref{324,,CGIHTTPRequestHandler} is being removed.

@end deffn

@cartouche
@quotation 警告 
@ref{324,,CGIHTTPRequestHandler} and the @code{--cgi} command-line option
are not intended for use by untrusted clients and may be vulnerable
to exploitation. Always use within a secure environment.
@end quotation
@end cartouche

@geindex http.server 命令列選項; --tls-cert
@anchor{library/http server cmdoption-http server-tls-cert}@anchor{229}
@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


在 3.14 版被加入.

@end deffn

@geindex http.server 命令列選項; --tls-key
@anchor{library/http server cmdoption-http server-tls-key}@anchor{22a}
@deffn {Option} @w{-}@w{-}tls@w{-}key

Specifies a private key file for HTTPS connections.

This option requires @code{--tls-cert} to be specified.


在 3.14 版被加入.

@end deffn

@geindex http.server 命令列選項; --tls-password-file
@anchor{library/http server cmdoption-http server-tls-password-file}@anchor{22b}
@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 @cite{--tls-cert`} to be specified.


在 3.14 版被加入.

@end deffn

@node 安全性注意事項<3>,,命令列介面<7>,http server — HTTP 伺服器
@anchor{library/http server http-server-security}@anchor{3fa1}@anchor{library/http server security-considerations}@anchor{3fcc}
@subsubsection 安全性注意事項


@geindex http.server;security（安全）

@ref{d30,,SimpleHTTPRequestHandler} will follow symbolic links when handling
requests, this makes it possible for files outside of the specified directory
to be served.

Earlier versions of Python did not scrub control characters from the
log messages emitted to stderr from @code{python -m http.server} or the
default @ref{12cc,,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 狀態管理,http cookiejar --- HTTP 用戶端的 Cookie 處理,http server — HTTP 伺服器,網路協定 Internet protocols 及支援
@anchor{library/http cookies doc}@anchor{3fcd}@anchor{library/http cookies http-cookies-http-state-management}@anchor{3fce}@anchor{library/http cookies module-http cookies}@anchor{75}@anchor{library/http cookies translation-repo}@anchor{3fcf}
@subsection @code{http.cookies} --- HTTP 狀態管理


@geindex module; http.cookies

`原始碼：'Lib/http/cookies.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/http/cookies.py}


__________________________________________________________________


@ref{75,,http.cookies} 模組定義了 cookie 概念的抽象化的類別，cookie 是一種 HTTP 狀態管理機制。它支援簡單的純字串 cookie，也提供了將任何可序列化的資料型別作為 cookie 值的抽象化。

此模組原先嚴格遵循了 
@geindex RFC; RFC 2109
RFC 2109@footnote{https://datatracker.ietf.org/doc/html/rfc2109.html} 和 
@geindex RFC; RFC 2068
RFC 2068@footnote{https://datatracker.ietf.org/doc/html/rfc2068.html} 規範所描述的剖析規則。自從發現 MSIE 3.0x 並不遵循這些規範所描述的字元規則，許多目前的瀏覽器和伺服器也在處理 cookie 時放寬了剖析規則。因此，此模組現在使用的剖析規則比之前的更為寬鬆。

字元集 @ref{14c4,,string.ascii_letters}、@ref{25cd,,string.digits} 和 @code{!#$%&'*+-.^_`|~} 表示此模組在 cookie 名稱 (@ref{df6,,key}) 中允許的合法字元集合。


在 3.3 版的變更: 允許 ':' 作為有效的 cookie 名稱字元。


@cartouche
@quotation 備註 
當遇到無效的 cookie 時，會引發 @ref{3fd0,,CookieError}，因此如果你的 cookie 資料來自瀏覽器，在剖析時你應該總是為無效資料作準備並捕捉 @ref{3fd0,,CookieError}。
@end quotation
@end cartouche

@geindex CookieError
@anchor{library/http cookies http cookies CookieError}@anchor{3fd0}
@deffn {例外} http.cookies.CookieError

因為不符合 
@geindex RFC; RFC 2109
RFC 2109@footnote{https://datatracker.ietf.org/doc/html/rfc2109.html} 而引發的例外：不正確的屬性、不正確的 @code{Set-Cookie} 標頭等。
@end deffn

@geindex BaseCookie (http.cookies 中的類別)
@anchor{library/http cookies http cookies BaseCookie}@anchor{3fd1}
@deffn {類別} http.cookies.BaseCookie ([input])

這個類別是一個類似字典的物件，其中的鍵是字串，而值則是 @ref{df9,,Morsel} 實例。請注意，當設定鍵的值時，值會先被轉換為一個包含該鍵和值的 @ref{df9,,Morsel}。

如果有給定 `input'，它會被傳遞給 @ref{3fd2,,load()} 方法。
@end deffn

@geindex SimpleCookie (http.cookies 中的類別)
@anchor{library/http cookies http cookies SimpleCookie}@anchor{1cec}
@deffn {類別} http.cookies.SimpleCookie ([input])

這個類別繼承自 @ref{3fd1,,BaseCookie} 並覆寫了 @ref{3fd3,,value_decode()} 和 @ref{3fd4,,value_encode()}。@code{SimpleCookie} 支援字串作為 cookie 值。當設定值時，@code{SimpleCookie} 會呼叫內建的 @ref{169,,str()} 來將值轉換為字串。從 HTTP 接收的值會保持為字串。
@end deffn


@subsubheading 也參考



@table @asis

@item @ref{74,,http.cookiejar} 模組

用於網路`用戶端'的 HTTP cookie 處理。@ref{74,,http.cookiejar} 和 @ref{75,,http.cookies} 模組互不相依。

@geindex RFC; RFC 2109

@item RFC 2109@footnote{https://datatracker.ietf.org/doc/html/rfc2109.html} - HTTP 狀態管理機制

這是此模組實作的狀態管理規範。
@end table


@menu
* Cookie 物件:: 
* Morsel 物件:: 
* 範例: 範例<40>. 

@end menu

@node Cookie 物件,Morsel 物件,,http cookies --- HTTP 狀態管理
@anchor{library/http cookies cookie-objects}@anchor{3fd5}@anchor{library/http cookies id1}@anchor{3fd6}
@subsubsection Cookie 物件


@geindex value_decode() (http.cookies.BaseCookie 的方法)
@anchor{library/http cookies http cookies BaseCookie value_decode}@anchor{3fd3}
@deffn {方法} BaseCookie.value_decode (val)

從字串表示回傳 @code{(real_value, coded_value)} 的元組。@code{real_value} 可以是任何型別。此方法在 @ref{3fd1,,BaseCookie} 中不做解碼 --- 它存在以便可以被覆寫。
@end deffn

@geindex value_encode() (http.cookies.BaseCookie 的方法)
@anchor{library/http cookies http cookies BaseCookie value_encode}@anchor{3fd4}
@deffn {方法} BaseCookie.value_encode (val)

回傳一個元組 @code{(real_value, coded_value)}。`val' 可以是任何型別，但 @code{coded_value} 總是會被轉換為字串。此方法在 @ref{3fd1,,BaseCookie} 中不做編碼 --- 它存在以便可以被覆寫。

一般來說，@ref{3fd4,,value_encode()} 和 @ref{3fd3,,value_decode()} 應該在 `value_decode' 的範圍內是互逆的 (inverse)。
@end deffn

@geindex output() (http.cookies.BaseCookie 的方法)
@anchor{library/http cookies http cookies BaseCookie output}@anchor{3fd7}
@deffn {方法} BaseCookie.output (attrs=None, header='Set-Cookie:', sep='\r\n')

回傳一個適合作為 HTTP 標頭來傳送的字串表示。`attrs' 和 `header' 會傳送給每個 @ref{df9,,Morsel} 的 @ref{3fd8,,output()} 方法。`sep' 用來連接標頭，預設為 @code{'\r\n'} (CRLF) 的組合。
@end deffn

@geindex js_output() (http.cookies.BaseCookie 的方法)
@anchor{library/http cookies http cookies BaseCookie js_output}@anchor{3fd9}
@deffn {方法} BaseCookie.js_output (attrs=None)

回傳一個可嵌入的 JavaScript 片段，如果在支援 JavaScript 的瀏覽器上執行，它的行為會與 HTTP 標頭被傳送的情況相同。

`attrs' 的意義與 @ref{3fd7,,output()} 裡的相同。
@end deffn

@geindex load() (http.cookies.BaseCookie 的方法)
@anchor{library/http cookies http cookies BaseCookie load}@anchor{3fd2}
@deffn {方法} BaseCookie.load (rawdata)

如果 `rawdata' 是字串，會將其作為 @code{HTTP_COOKIE} 剖析，並將在其中找到的值當作 @ref{df9,,Morsel} 新增。如果它是一個字典，則等同於：

@example
for k, v in rawdata.items():
    cookie[k] = v
@end example
@end deffn

@node Morsel 物件,範例<40>,Cookie 物件,http cookies --- HTTP 狀態管理
@anchor{library/http cookies id2}@anchor{3fda}@anchor{library/http cookies morsel-objects}@anchor{3fdb}
@subsubsection Morsel 物件


@geindex Morsel (http.cookies 中的類別)
@anchor{library/http cookies http cookies Morsel}@anchor{df9}
@deffn {類別} http.cookies.Morsel

抽象化一個鍵 / 值對，它有一些 
@geindex RFC; RFC 2109
RFC 2109@footnote{https://datatracker.ietf.org/doc/html/rfc2109.html} 屬性。

Morsel 是一種類似字典的物件，其鍵的集合是固定的 --- 有效的 
@geindex RFC; RFC 2109
RFC 2109@footnote{https://datatracker.ietf.org/doc/html/rfc2109.html} 屬性，它們是：

@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{3fdc}
@deffn {屬性} expires
@anchor{library/http cookies http cookies Morsel path}@anchor{3fdd}
@deffnx {屬性} path
@anchor{library/http cookies http cookies Morsel comment}@anchor{3fde}
@deffnx {屬性} comment
@anchor{library/http cookies http cookies Morsel domain}@anchor{3fdf}
@deffnx {屬性} domain

@deffnx {屬性} max@w{-}age
@anchor{library/http cookies http cookies Morsel secure}@anchor{3fe0}
@deffnx {屬性} secure
@anchor{library/http cookies http cookies Morsel version}@anchor{3fe1}
@deffnx {屬性} version
@anchor{library/http cookies http cookies Morsel httponly}@anchor{15c7}
@deffnx {屬性} httponly
@anchor{library/http cookies http cookies Morsel samesite}@anchor{3fe2}
@deffnx {屬性} samesite
@anchor{library/http cookies http cookies Morsel partitioned}@anchor{3fe3}
@deffnx {屬性} partitioned
@end deffn
@end quotation

屬性 @ref{15c7,,httponly} 指定 cookie 僅在 HTTP 請求中傳輸，而不可通過 JavaScript 存取。這是為了減輕某些形式的跨網站腳本攻擊。

@ref{3fe2,,samesite} 屬性控制瀏覽器要在何時將 cookie 與跨網站請求一起傳送，這有助於減輕 CSRF 攻擊。有效值為 "Strict"（僅在同站請求時傳送）、"Lax"（同站請求和頂層導航時傳送）和 "None"（同站請求和跨站請求時傳送）。使用 "None" 時，必須同時設定 "secure" 屬性，這是現代瀏覽器的要求。

The attribute @ref{3fe3,,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.

鍵不區分大小寫，其預設值為 @code{'@w{'}}。


在 3.5 版的變更: @code{__eq__()} 現在會考慮 @ref{df6,,key} 和 @ref{df7,,value}。



在 3.7 版的變更: 屬性 @ref{df6,,key}、@ref{df7,,value} 和 @ref{df8,,coded_value} 是唯讀的。請使用 @ref{dfa,,set()} 來設定它們。



在 3.8 版的變更: 新增對 @ref{3fe2,,samesite} 屬性的支援。



在 3.14 版的變更: 新增對 @ref{3fe3,,partitioned} 屬性的支援。

@end deffn

@geindex value (http.cookies.Morsel 的屬性)
@anchor{library/http cookies http cookies Morsel value}@anchor{df7}
@deffn {屬性} Morsel.value

cookie 的值。
@end deffn

@geindex coded_value (http.cookies.Morsel 的屬性)
@anchor{library/http cookies http cookies Morsel coded_value}@anchor{df8}
@deffn {屬性} Morsel.coded_value

cookie 的編碼值 --- 這是應該被傳送的值。
@end deffn

@geindex key (http.cookies.Morsel 的屬性)
@anchor{library/http cookies http cookies Morsel key}@anchor{df6}
@deffn {屬性} Morsel.key

cookie 的名稱。
@end deffn

@geindex set() (http.cookies.Morsel 的方法)
@anchor{library/http cookies http cookies Morsel set}@anchor{dfa}
@deffn {方法} Morsel.set (key, value, coded_value)

設定 `key'、`value' 和 `coded_value' 屬性。
@end deffn

@geindex isReservedKey() (http.cookies.Morsel 的方法)
@anchor{library/http cookies http cookies Morsel isReservedKey}@anchor{3fe4}
@deffn {方法} Morsel.isReservedKey (K)

`K' 是否為 @ref{df9,,Morsel} 的鍵集合中的成員。
@end deffn

@geindex output() (http.cookies.Morsel 的方法)
@anchor{library/http cookies http cookies Morsel output}@anchor{3fd8}
@deffn {方法} Morsel.output (attrs=None, header='Set-Cookie:')

回傳適合作為 HTTP 標頭傳送的 Morsel 的字串表示。預設會包含所有屬性，除非有給定 `attrs'，在此情況下，它應該是一個要使用的屬性的串列。預設的 `header' 是 @code{"Set-Cookie:"}。
@end deffn

@geindex js_output() (http.cookies.Morsel 的方法)
@anchor{library/http cookies http cookies Morsel js_output}@anchor{3fe5}
@deffn {方法} Morsel.js_output (attrs=None)

回傳一個可嵌入的 JavaScript 片段，如果在支援 JavaScript 的瀏覽器上執行，它的行為會與 HTTP 標頭被傳送的情況相同。

`attrs' 的意義與 @ref{3fd8,,output()} 裡的相同。
@end deffn

@geindex OutputString() (http.cookies.Morsel 的方法)
@anchor{library/http cookies http cookies Morsel OutputString}@anchor{3fe6}
@deffn {方法} Morsel.OutputString (attrs=None)

回傳表示 Morsel 的字串，不包含周圍任何的 HTTP 或 JavaScript。

`attrs' 的意義與 @ref{3fd8,,output()} 裡的相同。
@end deffn

@geindex update() (http.cookies.Morsel 的方法)
@anchor{library/http cookies http cookies Morsel update}@anchor{10c4}
@deffn {方法} Morsel.update (values)

更新 Morsel 字典中的值為 `values' 字典中的值。如果 `values' 字典中的任何鍵不是有效的 
@geindex RFC; RFC 2109
RFC 2109@footnote{https://datatracker.ietf.org/doc/html/rfc2109.html} 屬性則引發錯誤。


在 3.5 版的變更: 對於無效的鍵會引發錯誤。

@end deffn

@geindex copy() (http.cookies.Morsel 的方法)
@anchor{library/http cookies http cookies Morsel copy}@anchor{10c3}
@deffn {方法} Morsel.copy (value)

回傳 Morsel 物件的淺層複製。


在 3.5 版的變更: 回傳 Morsel 物件而不是字典。

@end deffn

@geindex setdefault() (http.cookies.Morsel 的方法)
@anchor{library/http cookies http cookies Morsel setdefault}@anchor{3fe7}
@deffn {方法} Morsel.setdefault (key, value=None)

如果鍵不是一個有效的 
@geindex RFC; RFC 2109
RFC 2109@footnote{https://datatracker.ietf.org/doc/html/rfc2109.html} 屬性會引發錯誤，否則行為與 @ref{1274,,dict.setdefault()} 相同。
@end deffn

@node 範例<40>,,Morsel 物件,http cookies --- HTTP 狀態管理
@anchor{library/http cookies cookie-example}@anchor{3fe8}@anchor{library/http cookies example}@anchor{3fe9}
@subsubsection 範例


以下範例示範如何使用 @ref{75,,http.cookies} 模組。

@example
>>> from http import cookies
>>> C = cookies.SimpleCookie()
>>> C["fig"] = "newton"
>>> C["sugar"] = "wafer"
>>> print(C) # 產生 HTTP 標頭
Set-Cookie: fig=newton
Set-Cookie: sugar=wafer
>>> print(C.output()) # 同上
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") # 從字串（HTTP 標頭）載入
>>> print(C)
Set-Cookie: chips=ahoy
Set-Cookie: vienna=finger
>>> C = cookies.SimpleCookie()
>>> C.load('keebler="E=everybody; L=\\"Loves\\"; fudge=\\012;";')
>>> print(C)
Set-Cookie: keebler="E=everybody; L=\"Loves\"; fudge=\012;"
>>> C = cookies.SimpleCookie()
>>> C["oreo"] = "doublestuff"
>>> C["oreo"]["path"] = "/"
>>> print(C)
Set-Cookie: oreo=doublestuff; Path=/
>>> C = cookies.SimpleCookie()
>>> C["twix"] = "none for you"
>>> C["twix"].value
'none for you'
>>> C = cookies.SimpleCookie()
>>> C["number"] = 7 # 等同於 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 --- HTTP 用戶端的 Cookie 處理,xmlrpc --- XMLRPC 伺服器與用戶模組,http cookies --- HTTP 狀態管理,網路協定 Internet protocols 及支援
@anchor{library/http cookiejar doc}@anchor{3fea}@anchor{library/http cookiejar http-cookiejar-cookie-handling-for-http-clients}@anchor{3feb}@anchor{library/http cookiejar module-http cookiejar}@anchor{74}@anchor{library/http cookiejar translation-repo}@anchor{3fec}
@subsection @code{http.cookiejar} --- HTTP 用戶端的 Cookie 處理


@geindex module; http.cookiejar

`原始碼：'Lib/http/cookiejar.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/http/cookiejar.py}


__________________________________________________________________


@ref{74,,http.cookiejar} 模組定義了自動處理 HTTP cookie 的類別。當需要存取小量資料 —— `cookies' —— 的網站時會非常有用。這些資料會依據網頁伺服器的 HTTP 回應來設置於用戶端機器，並在之後的請求中被回傳到伺服器。

一般的 Netscape cookie 協定和 
@geindex RFC; RFC 2965
RFC 2965@footnote{https://datatracker.ietf.org/doc/html/rfc2965.html} 定義的 cookie 協定都會被處理。RFC 2965 的處理預設是關閉的。
@geindex RFC; RFC 2109
RFC 2109@footnote{https://datatracker.ietf.org/doc/html/rfc2109.html} cookie 會被剖析為 Netscape cookie，然後根據有生效的「策略」來被看作為 Netscape 或 RFC 2965 cookie。@ref{74,,http.cookiejar} 會嘗試遵循實際上的 Netscape cookie 協定（與原始的 Netscape 規格中的協定有很大的不同），包括 RFC 2965 所引進的 @code{max-age} 和 @code{port} cookie 屬性。

@cartouche
@quotation 備註 
在 @code{Set-Cookie} 和 @code{Set-Cookie2} 標頭中出現的各種命名參數（例如 @code{domain} 和 @code{expires}）通常被稱為 `attributes'。為了與 Python 的屬性分別開，這個模組的說明檔案改用 `cookie-attribute' 來稱呼。
@end quotation
@end cartouche

模組定義了以下例外：

@geindex LoadError
@anchor{library/http cookiejar http cookiejar LoadError}@anchor{3fed}
@deffn {例外} http.cookiejar.LoadError

當從檔案載入 cookies 失敗時，@ref{3fee,,FileCookieJar} 的實例會引發這個例外。@ref{3fed,,LoadError} 是 @ref{2c0,,OSError} 的子類別。


在 3.3 版的變更: @ref{3fed,,LoadError} 以前是 @ref{124e,,IOError} 的子型別，現在是 @ref{2c0,,OSError} 的別名。

@end deffn

這個模組提供了以下類別：

@geindex CookieJar (http.cookiejar 中的類別)
@anchor{library/http cookiejar http cookiejar CookieJar}@anchor{3e0c}
@deffn {類別} http.cookiejar.CookieJar (policy=None)

`policy' 是實作了 @ref{3fef,,CookiePolicy} 介面的一個物件。

@ref{3e0c,,CookieJar} 類別會儲存 HTTP cookies。它會從 HTTP 請求中抽取出 cookies，並在 HTTP 回應中將它們回傳。@ref{3e0c,,CookieJar} 實例會在必要時自動使包含的 cookies 過期。它的子類別也負責從檔案或資料庫中儲存和擷取 cookies。
@end deffn

@geindex FileCookieJar (http.cookiejar 中的類別)
@anchor{library/http cookiejar http cookiejar FileCookieJar}@anchor{3fee}
@deffn {類別} http.cookiejar.FileCookieJar (filename=None, delayload=None, policy=None)

`policy' 是實作了 @ref{3fef,,CookiePolicy} 介面的一個物件。至於其他引數，請參閱對應屬性的說明文件。

一個可以從磁碟上的檔案載入 Cookie，也可以儲存 Cookie 到磁碟上檔案的 @ref{3e0c,,CookieJar}。在 @ref{3ff0,,load()} 或 @ref{3ff1,,revert()} 方法被呼叫之前，Cookie 並`不會'從指定的檔案載入。這個類別的子類別有記載於 @ref{3ff2,,FileCookieJar 子類別及與網頁瀏覽器的合作} 章節。

這個類別不應該直接初始化 - 請使用下面的子類別代替。


在 3.8 版的變更: filename 參數支援傳入一個 @ref{59b,,path-like object}。

@end deffn

@geindex CookiePolicy (http.cookiejar 中的類別)
@anchor{library/http cookiejar http cookiejar CookiePolicy}@anchor{3fef}
@deffn {類別} http.cookiejar.CookiePolicy

此類別負責決定是否應從伺服器接受 / 回傳每個 cookie。
@end deffn

@geindex DefaultCookiePolicy (http.cookiejar 中的類別)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy}@anchor{1cbc}
@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'))

建構函式引數只能以關鍵字引數的形式傳送。`blocked_domains' 是我們從不接受 cookies 或回傳 cookies 的網域名稱序列。`allowed_domains' 如果不是 @ref{87e,,None}，這是我們接受並回傳 cookies 的唯一網域名稱序列。 `secure_protocols' 是可以加入安全 cookies 的通訊協定序列。預設情況下，`https' 和 `wss'（安全 websocket）會被視為安全通訊協定。所有其他引數請參閱 @ref{3fef,,CookiePolicy} 及 @ref{1cbc,,DefaultCookiePolicy} 物件的說明文件。

@ref{1cbc,,DefaultCookiePolicy} 實作了 Netscape 和 
@geindex RFC; RFC 2965
RFC 2965@footnote{https://datatracker.ietf.org/doc/html/rfc2965.html} cookies 的標準接受/拒絕規則。預設情況下，
@geindex RFC; RFC 2109
RFC 2109@footnote{https://datatracker.ietf.org/doc/html/rfc2109.html} cookies（即在 @code{Set-Cookie} 標頭中接收到的版本 cookie-attribute 為 1 的 cookies）會根據 RFC 2965 規則處理。 但是，如果 RFC 2965 處理被關閉，或者 @ref{3ff3,,rfc2109_as_netscape} 是 @code{True}，RFC 2109 cookie 會被 @ref{3e0c,,CookieJar} 實例「降級 」為 Netscape cookie，方法是將 @ref{3ff4,,Cookie} 實例的 @code{version} 屬性設為 0。@ref{1cbc,,DefaultCookiePolicy} 也提供了一些參數來允許對策略進行一些微調。
@end deffn

@geindex Cookie (http.cookiejar 中的類別)
@anchor{library/http cookiejar http cookiejar Cookie}@anchor{3ff4}
@deffn {類別} http.cookiejar.Cookie

這個類別代表 Netscape、
@geindex RFC; RFC 2109
RFC 2109@footnote{https://datatracker.ietf.org/doc/html/rfc2109.html} 和 
@geindex RFC; RFC 2965
RFC 2965@footnote{https://datatracker.ietf.org/doc/html/rfc2965.html} cookies。 我們不希望 @ref{74,,http.cookiejar} 的使用者建立自己的 @ref{3ff4,,Cookie} 實例。 如有必要，請在 @ref{3e0c,,CookieJar} 實例上呼叫 @code{make_cookies()}。
@end deffn


@subsubheading 也參考



@table @asis

@item @ref{111,,urllib.request} 模組

URL 打開時會自動處理 cookie。

@item @ref{75,,http.cookies} 模組

HTTP cookie 類別，主要用於伺服器端程式碼。 @ref{74,,http.cookiejar} 和 @ref{75,,http.cookies} 模組不互相依賴。

@item @indicateurl{https://curl.se/rfc/cookie_spec.html}

原始 Netscape cookie 協定的規範。雖然這仍是主流協定，但所有主要瀏覽器（以及 @ref{74,,http.cookiejar}）實作的「Netscape cookie 協定」與 @code{cookie_spec.html} 中實作的協定只有一點相似之處。

@geindex RFC; RFC 2109

@item RFC 2109@footnote{https://datatracker.ietf.org/doc/html/rfc2109.html} - HTTP 狀態管理機制

被 
@geindex RFC; RFC 2965
RFC 2965@footnote{https://datatracker.ietf.org/doc/html/rfc2965.html} 所取代，會使用 @code{Set-Cookie} 設定 version=1。

@geindex RFC; RFC 2965

@item RFC 2965@footnote{https://datatracker.ietf.org/doc/html/rfc2965.html} - HTTP 狀態管理機制

有錯誤修正的 Netscape 通訊協定。使用 @code{Set-Cookie2} 取代 @code{Set-Cookie}。未被廣泛使用。

@item @indicateurl{https://kristol.org/cookie/errata.html}

未完成的 
@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} - HTTP 狀態管理使用方法


@menu
* CookieJar 與 FileCookieJar 物件:: 
* FileCookieJar 子類別及與網頁瀏覽器的合作:: 
* CookiePolicy 物件:: 
* DefaultCookiePolicy 物件:: 
* Cookie 物件: Cookie 物件<2>. 
* 範例: 範例<41>. 

@end menu

@node CookieJar 與 FileCookieJar 物件,FileCookieJar 子類別及與網頁瀏覽器的合作,,http cookiejar --- HTTP 用戶端的 Cookie 處理
@anchor{library/http cookiejar cookie-jar-objects}@anchor{3ff5}@anchor{library/http cookiejar cookiejar-and-filecookiejar-objects}@anchor{3ff6}
@subsubsection CookieJar 與 FileCookieJar 物件


@ref{3e0c,,CookieJar} 物件支援 @ref{4c3,,iterator} 協定來遍歷包含的 @ref{3ff4,,Cookie} 物件。

@ref{3e0c,,CookieJar} 擁有以下方法：

@geindex add_cookie_header() (http.cookiejar.CookieJar 的方法)
@anchor{library/http cookiejar http cookiejar CookieJar add_cookie_header}@anchor{3ff7}
@deffn {方法} CookieJar.add_cookie_header (request)

將正確的 @code{Cookie} 標頭加入 `request'。

如果策略允許（即 @ref{3e0c,,CookieJar} 的 @ref{3fef,,CookiePolicy} 實例的 @code{rfc2965} 和 @code{hide_cookie2} 屬性分別為 true 和 false），@code{Cookie2} 標頭也會在適當的時候加入。

如 @ref{111,,urllib.request} 文件所述，`request' 物件（通常是 @ref{11d3,,urllib.request.Request} 的實例）必須支援 @code{get_full_url()}、@code{has_header()}、@code{get_header()}、@code{header_items()}、@code{add_unredirected_header()} 方法與 @code{host}、@code{type}、@code{unverifiable}、@code{origin_req_host} 屬性。


在 3.3 版的變更: `request' 物件需要 @code{origin_req_host} 屬性。已移除對已廢棄方法 @code{get_origin_req_host()} 的依賴。

@end deffn

@geindex extract_cookies() (http.cookiejar.CookieJar 的方法)
@anchor{library/http cookiejar http cookiejar CookieJar extract_cookies}@anchor{3ff8}
@deffn {方法} CookieJar.extract_cookies (response, request)

在策略允許的情況下，從 HTTP `response' 抽取出 cookies 並儲存到 @ref{3e0c,,CookieJar} 中。

@ref{3e0c,,CookieJar} 會在 `response' 引數中尋找允許的 @code{Set-Cookie} 和 @code{Set-Cookie2} 標頭，並視情況儲存 cookies（需經 @ref{3ff9,,CookiePolicy.set_ok()} 方法的檢測）。

`response' 物件（通常是呼叫 @ref{306,,urllib.request.urlopen()} 的結果或類似的東西）應該支援 @code{info()} 方法，它會回傳一個 @ref{57b,,email.message.Message} 的實例。

如 @ref{111,,urllib.request} 的檔案所說，`request' 物件（通常是 @ref{11d3,,urllib.request.Request} 的實例）必須支援 @code{get_full_url()} 方法以及 @code{host}、@code{unverifiable} 和 @code{origin_req_host} 等屬性，該請求被用於設置 cookie-attributes 的預設值並檢查 cookie 是否允許被設置。


在 3.3 版的變更: `request' 物件需要 @code{origin_req_host} 屬性。已移除對已廢棄方法 @code{get_origin_req_host()} 的依賴。

@end deffn

@geindex set_policy() (http.cookiejar.CookieJar 的方法)
@anchor{library/http cookiejar http cookiejar CookieJar set_policy}@anchor{3ffa}
@deffn {方法} CookieJar.set_policy (policy)

設定要使用的 @ref{3fef,,CookiePolicy} 實例。
@end deffn

@geindex make_cookies() (http.cookiejar.CookieJar 的方法)
@anchor{library/http cookiejar http cookiejar CookieJar make_cookies}@anchor{3ffb}
@deffn {方法} CookieJar.make_cookies (response, request)

回傳從 `response' 物件抽取出的 @ref{3ff4,,Cookie} 物件序列。

有關 `response' 和 `request' 引數所需的介面，請參閱 @ref{3ff8,,extract_cookies()} 的說明檔案。
@end deffn

@geindex set_cookie_if_ok() (http.cookiejar.CookieJar 的方法)
@anchor{library/http cookiejar http cookiejar CookieJar set_cookie_if_ok}@anchor{3ffc}
@deffn {方法} CookieJar.set_cookie_if_ok (cookie, request)

如果策略允許這麼做，設定 @ref{3ff4,,Cookie}。
@end deffn

@geindex set_cookie() (http.cookiejar.CookieJar 的方法)
@anchor{library/http cookiejar http cookiejar CookieJar set_cookie}@anchor{3ffd}
@deffn {方法} CookieJar.set_cookie (cookie)

設定一個 @ref{3ff4,,Cookie}，不經過策略檢查。
@end deffn

@geindex clear() (http.cookiejar.CookieJar 的方法)
@anchor{library/http cookiejar http cookiejar CookieJar clear}@anchor{3ffe}
@deffn {方法} CookieJar.clear ([domain[, path[, name]]])

清除一些 cookies。

如果不帶引數地叫用，則清除所有 cookies。如果給定單一引數，則只移除屬於該 `domain' 的 cookies。如果給定兩個引數，則會移除屬於指定 `domain' 和 URL `path' 的 cookie。 如果給定三個引數，則會移除指定 `domain'、`path' 和 `name' 的 cookie。

如果沒有符合的 cookie 存在，則引發 @ref{5df,,KeyError}。
@end deffn

@geindex clear_session_cookies() (http.cookiejar.CookieJar 的方法)
@anchor{library/http cookiejar http cookiejar CookieJar clear_session_cookies}@anchor{3fff}
@deffn {方法} CookieJar.clear_session_cookies ()

刪除所有 session cookies。

刪除所有包含有 true @code{discard} 屬性的 cookie (通常是因為它們沒有 @cite{max-age} 或 @cite{expires} cookie 屬性，或有明確的 @cite{discard} cookie 屬性)。 對於互動式瀏覽器，工作階段的結束通常對應於關閉瀏覽器視窗。

請注意 @code{save()} 方法無論如何都不會儲存 session cookies，除非你透過傳入 true `ignore_discard' 引數來要求。
@end deffn

@ref{3fee,,FileCookieJar} 實例有下列附加方法：

@geindex save() (http.cookiejar.FileCookieJar 的方法)
@anchor{library/http cookiejar http cookiejar FileCookieJar save}@anchor{4000}
@deffn {方法} FileCookieJar.save (filename=None, ignore_discard=False, ignore_expires=False)

將 cookies 儲存到檔案中。

這個基底類別會產生 @ref{369,,NotImplementedError}。子類別可以不實作此方法。

`filename' 是儲存 cookies 的檔案名稱。 如果 `filename' 未指定，則會使用 @code{self.filename} (其預設值是傳給建構函式的值（如果有）)；如果 @code{self.filename} 是 @ref{87e,,None}，則會產生 @ref{2eb,,ValueError}。

`ignore_discard': 即使設定為捨棄的 cookies 也會儲存。`ignore_expires': 保存過期的 cookie

如果檔案已經存在，則會被覆寫，因此會抹除其中包含的所有 cookies。 儲存的 cookies 可以稍後使用 @ref{3ff0,,load()} 或 @ref{3ff1,,revert()} 方法還原。
@end deffn

@geindex load() (http.cookiejar.FileCookieJar 的方法)
@anchor{library/http cookiejar http cookiejar FileCookieJar load}@anchor{3ff0}
@deffn {方法} FileCookieJar.load (filename=None, ignore_discard=False, ignore_expires=False)

從檔案中載入 cookies。

舊的 cookies 會被保留，除非被新載入的 cookies 覆蓋。

引數與 @ref{4000,,save()} 相同。

被命名的檔案必須是類別所能正確剖析的格式，否則會產生 @ref{3fed,,LoadError}。此外，@ref{2c0,,OSError} 可能會被引發，例如檔案不存在時。


在 3.3 版的變更: 以前會引發 @ref{124e,,IOError}，現在它是 @ref{2c0,,OSError} 的別名。

@end deffn

@geindex revert() (http.cookiejar.FileCookieJar 的方法)
@anchor{library/http cookiejar http cookiejar FileCookieJar revert}@anchor{3ff1}
@deffn {方法} FileCookieJar.revert (filename=None, ignore_discard=False, ignore_expires=False)

清除所有 cookies， 並從儲存的檔案重新載入 cookies。

@ref{3ff1,,revert()} 可以產生與 @ref{3ff0,,load()} 相同的例外。如果失敗，物件的狀態不會被改變。
@end deffn

@ref{3fee,,FileCookieJar} 實例擁有以下公開屬性：

@geindex filename (http.cookiejar.FileCookieJar 的屬性)
@anchor{library/http cookiejar http cookiejar FileCookieJar filename}@anchor{4001}
@deffn {屬性} FileCookieJar.filename

保存 cookie 的預設檔案的檔案名稱。 此屬性可以被指定。
@end deffn

@geindex delayload (http.cookiejar.FileCookieJar 的屬性)
@anchor{library/http cookiejar http cookiejar FileCookieJar delayload}@anchor{4002}
@deffn {屬性} FileCookieJar.delayload

若為 true，則從硬盤惰性地載入 cookies。 此屬性不應被指定。 這只是一個提示，因為這只會影響效能，不會影響行為 (除非磁碟上的 cookies 正在改變)。一個 @ref{3e0c,,CookieJar} 物件可以忽略它。 沒有一個包含在標準函式庫中的 @ref{3fee,,FileCookieJar} 類別會惰性地載入 cookies。
@end deffn

@node FileCookieJar 子類別及與網頁瀏覽器的合作,CookiePolicy 物件,CookieJar 與 FileCookieJar 物件,http cookiejar --- HTTP 用戶端的 Cookie 處理
@anchor{library/http cookiejar file-cookie-jar-classes}@anchor{3ff2}@anchor{library/http cookiejar filecookiejar-subclasses-and-co-operation-with-web-browsers}@anchor{4003}
@subsubsection FileCookieJar 子類別及與網頁瀏覽器的合作


以下 @ref{3e0c,,CookieJar} 子類別提供用於讀取和寫入。

@geindex MozillaCookieJar (http.cookiejar 中的類別)
@anchor{library/http cookiejar http cookiejar MozillaCookieJar}@anchor{4004}
@deffn {類別} http.cookiejar.MozillaCookieJar (filename=None, delayload=None, policy=None)

一個能夠以 Mozilla @code{cookies.txt} 檔案格式（該格式也被 curl 和 Lynx 以及 Netscape 瀏覽器所使用）從磁碟載入和儲存 cookie 的 @ref{3fee,,FileCookieJar}。

@cartouche
@quotation 備註 
這會遺失關於 
@geindex RFC; RFC 2965
RFC 2965@footnote{https://datatracker.ietf.org/doc/html/rfc2965.html} cookie 的訊息，以及較新或非標準 cookie 屬性（例如 @code{port}）的訊息。
@end quotation
@end cartouche

@cartouche
@quotation 警告 
如果 Cookie 遺失或損壞會造成不便，請在儲存之前先備份 Cookie（有些微妙的情況可能會導致檔案在載入/儲存往返過程中發生輕微變化）。
@end quotation
@end cartouche

另外請注意，在 Mozilla 執行時儲存的 cookies 會被 Mozilla 刪除。
@end deffn

@geindex LWPCookieJar (http.cookiejar 中的類別)
@anchor{library/http cookiejar http cookiejar LWPCookieJar}@anchor{4005}
@deffn {類別} http.cookiejar.LWPCookieJar (filename=None, delayload=None, policy=None)

一個 @ref{3fee,,FileCookieJar} 可以從 libwww-perl 函式庫的 @cite{Set-Cookie3} 檔案格式載入 cookies 並儲存 cookies 到磁碟。如果你想要將 cookie 儲存在人類可讀的檔案中，這是很方便的。


在 3.8 版的變更: filename 參數支援傳入一個 @ref{59b,,path-like object}。

@end deffn

@node CookiePolicy 物件,DefaultCookiePolicy 物件,FileCookieJar 子類別及與網頁瀏覽器的合作,http cookiejar --- HTTP 用戶端的 Cookie 處理
@anchor{library/http cookiejar cookie-policy-objects}@anchor{4006}@anchor{library/http cookiejar cookiepolicy-objects}@anchor{4007}
@subsubsection CookiePolicy 物件


實作 @ref{3fef,,CookiePolicy} 介面的物件有以下方法：

@geindex set_ok() (http.cookiejar.CookiePolicy 的方法)
@anchor{library/http cookiejar http cookiejar CookiePolicy set_ok}@anchor{3ff9}
@deffn {方法} CookiePolicy.set_ok (cookie, request)

回傳值表示的是否接受伺服器 cookie 的布林值。

`cookie' 是一個 @ref{3ff4,,Cookie} 實例。 `request' 是一個實作了 @ref{3ff8,,CookieJar.extract_cookies()} 文件所定義的介面的物件。
@end deffn

@geindex return_ok() (http.cookiejar.CookiePolicy 的方法)
@anchor{library/http cookiejar http cookiejar CookiePolicy return_ok}@anchor{4008}
@deffn {方法} CookiePolicy.return_ok (cookie, request)

回傳布林值，表示 cookie 是否應回傳伺服器。

`cookie' 是一個 @ref{3ff4,,Cookie} 實例。 `request' 是一個實作了 @ref{3ff7,,CookieJar.add_cookie_header()} 文件所定義的介面的物件。
@end deffn

@geindex domain_return_ok() (http.cookiejar.CookiePolicy 的方法)
@anchor{library/http cookiejar http cookiejar CookiePolicy domain_return_ok}@anchor{4009}
@deffn {方法} CookiePolicy.domain_return_ok (domain, request)

在給定 cookie 網域如果不應回傳 cookie，則回傳 @code{False}。

此方法為一種最佳化。它消除了檢查每個具有特定網域的 cookie 的需要（這可能需要讀取許多檔案）。從 @ref{4009,,domain_return_ok()} 和 @ref{400a,,path_return_ok()} 回傳 true 會把所有的工作留給 @ref{4008,,return_ok()}。

如果 @ref{4009,,domain_return_ok()} 對 cookie 網域回傳 true，@ref{400a,,path_return_ok()} 就會被用來呼叫 cookie 路徑。否則 @ref{400a,,path_return_ok()} 和 @ref{4008,,return_ok()} 永遠不會被呼叫。如果 @ref{400a,,path_return_ok()} 回傳 true，則會呼叫 @ref{4008,,return_ok()} 附帶的 @ref{3ff4,,Cookie} 物件本身以進行全面檢查。否則，@ref{4008,,return_ok()} 將永遠不會被呼叫。

請注意，@ref{4009,,domain_return_ok()} 是針對每個 `cookie' 網域來呼叫的，而不只是針對 `request' 網域。 例如，如果請求網域是 @code{"www.example.com"} ，這個函式可能會同時被 @code{".example.com"} 和 @code{"www.example.com"} 呼叫。 同樣的道理也適用於 @ref{400a,,path_return_ok()}。

`request' 引數與 @ref{4008,,return_ok()} 的說明文件相同。
@end deffn

@geindex path_return_ok() (http.cookiejar.CookiePolicy 的方法)
@anchor{library/http cookiejar http cookiejar CookiePolicy path_return_ok}@anchor{400a}
@deffn {方法} CookiePolicy.path_return_ok (path, request)

給定 cookie 路徑如不應該回傳 cookie，則回傳 @code{False} 。

關於 @ref{4009,,domain_return_ok()} 請見文件。
@end deffn

除了實作上述方法外， @ref{3fef,,CookiePolicy} 介面的實作也必須提供下列屬性，指出應該使用哪些通訊協定，以及如何使用。所有這些屬性都可以被指定。

@geindex netscape (http.cookiejar.CookiePolicy 的屬性)
@anchor{library/http cookiejar http cookiejar CookiePolicy netscape}@anchor{400b}
@deffn {屬性} CookiePolicy.netscape

實作 Netscape 協定。
@end deffn

@geindex rfc2965 (http.cookiejar.CookiePolicy 的屬性)
@anchor{library/http cookiejar http cookiejar CookiePolicy rfc2965}@anchor{400c}
@deffn {屬性} CookiePolicy.rfc2965

實作 
@geindex RFC; RFC 2965
RFC 2965@footnote{https://datatracker.ietf.org/doc/html/rfc2965.html} 協定。
@end deffn

@geindex hide_cookie2 (http.cookiejar.CookiePolicy 的屬性)
@anchor{library/http cookiejar http cookiejar CookiePolicy hide_cookie2}@anchor{400d}
@deffn {屬性} CookiePolicy.hide_cookie2

不要在請求中加入 @code{Cookie2} 標頭（這個標頭的存在向伺服器表明我們能夠正確剖析 
@geindex RFC; RFC 2965
RFC 2965@footnote{https://datatracker.ietf.org/doc/html/rfc2965.html} cookie）。
@end deffn

以 @ref{1cbc,,DefaultCookiePolicy} 為子類別定義 @ref{3fef,,CookiePolicy} 類別，並覆寫其中的一些或全部方法是最有用的。@ref{3fef,,CookiePolicy} 本身可以用做 '無策略'，允許設定和接收任何和所有的 cookies (這不太可能有用)。

@node DefaultCookiePolicy 物件,Cookie 物件<2>,CookiePolicy 物件,http cookiejar --- HTTP 用戶端的 Cookie 處理
@anchor{library/http cookiejar default-cookie-policy-objects}@anchor{400e}@anchor{library/http cookiejar defaultcookiepolicy-objects}@anchor{400f}
@subsubsection DefaultCookiePolicy 物件


執行接受和回傳 cookie 的標準規則。

同時支援 
@geindex RFC; RFC 2965
RFC 2965@footnote{https://datatracker.ietf.org/doc/html/rfc2965.html} 和 Netscape cookies。 RFC 2965 的處理預設為關閉。

提供你自己的策略的最簡單方法是覆寫此類別，並在你覆寫的實作中呼叫其方法，然後再加入你自己的額外檢查：

@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

除了實作 @ref{3fef,,CookiePolicy} 介面所需的功能外，這個類別還允許你阻止或允許網域名稱設定和接收 cookies。 還有調整嚴格度的控制選項，可讓你稍微收緊相對寬鬆的 Netscape 通訊協定（代價是阻擋一些良性 cookies）。

提供網域阻止清單和允許清單（預設都關閉）。只有不在阻止清單中和在允許清單中（如果允許清單是有效的）的網域才參與 cookie 設定和回傳。使用 `blocked_domains' 構造函式引數，以及 @code{blocked_domains()} 和 @code{set_blocked_domains()} 方法（以及 `allowed_domains' 的相應引數和方法）。如果你設定了允許清單，你可以透過設定為 @ref{87e,,None} 來再次關閉它。

封鎖或允許清單中不以點開頭的網域必須與 cookie 網域相等才能匹配。 例如，@code{"example.com"} 會與封鎖清單項目 @code{"example.com"} 匹配，但 @code{"www.example.com"} 則不會。 以點開頭的網域也會與更特定的網域相匹配。例如，@code{"www.example.com"} 和 @code{"www.coyote.example.com"} 都匹配 @code{".example.com"}（但 @code{"example.com"} 本身不匹配）。 IP 位址是例外，它們必須完全匹配。例如，如果 blocked_domains 包含 @code{"192.168.1.2"} 和 @code{".168.1.2"}，則 192.168.1.2 會被封鎖，但 193.168.1.2 則不會。

@ref{1cbc,,DefaultCookiePolicy} 實作了下列附加方法：

@geindex blocked_domains() (http.cookiejar.DefaultCookiePolicy 的方法)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy blocked_domains}@anchor{4010}
@deffn {方法} DefaultCookiePolicy.blocked_domains ()

回傳被阻止網域的序列（以元組形式）。
@end deffn

@geindex set_blocked_domains() (http.cookiejar.DefaultCookiePolicy 的方法)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy set_blocked_domains}@anchor{4011}
@deffn {方法} DefaultCookiePolicy.set_blocked_domains (blocked_domains)

設定阻止網域的順序。
@end deffn

@geindex is_blocked() (http.cookiejar.DefaultCookiePolicy 的方法)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy is_blocked}@anchor{4012}
@deffn {方法} DefaultCookiePolicy.is_blocked (domain)

如果 `domain' 在設定或接收 cookies 的阻止列表上，則回傳 @code{True}。
@end deffn

@geindex allowed_domains() (http.cookiejar.DefaultCookiePolicy 的方法)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy allowed_domains}@anchor{4013}
@deffn {方法} DefaultCookiePolicy.allowed_domains ()

回傳 @ref{87e,,None}，或允許網域的序列（以元組形式）。
@end deffn

@geindex set_allowed_domains() (http.cookiejar.DefaultCookiePolicy 的方法)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy set_allowed_domains}@anchor{4014}
@deffn {方法} DefaultCookiePolicy.set_allowed_domains (allowed_domains)

設定允許網域的序列，或 @ref{87e,,None}。
@end deffn

@geindex is_not_allowed() (http.cookiejar.DefaultCookiePolicy 的方法)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy is_not_allowed}@anchor{4015}
@deffn {方法} DefaultCookiePolicy.is_not_allowed (domain)

如果 `domain' 不在設定或接收 cookies 的允許清單上，則回傳 @code{True}。
@end deffn

@ref{1cbc,,DefaultCookiePolicy} 實例有以下屬性，這些屬性都是由同名的建構函式引數初始化，而且都可以被指定。

@geindex rfc2109_as_netscape (http.cookiejar.DefaultCookiePolicy 的屬性)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy rfc2109_as_netscape}@anchor{3ff3}
@deffn {屬性} DefaultCookiePolicy.rfc2109_as_netscape

如果為 true，請求 @ref{3e0c,,CookieJar} 實例透過設定 @ref{3ff4,,Cookie} 實例的版本屬性為 0，將 
@geindex RFC; RFC 2109
RFC 2109@footnote{https://datatracker.ietf.org/doc/html/rfc2109.html} cookies (即在 @code{Set-Cookie} 標頭中收到的、版本 cookie 屬性為 1 的 cookies) 降級為 Netscape cookies。 預設值是 @ref{87e,,None}，在這種情況下，如果且僅如果 
@geindex RFC; RFC 2965
RFC 2965@footnote{https://datatracker.ietf.org/doc/html/rfc2965.html} 處理被關閉，RFC 2109 cookies 才會被降級。 因此，RFC 2109 cookie 在預設情況下被降級。
@end deffn

一般的調整嚴格度的控制選項：

@geindex strict_domain (http.cookiejar.DefaultCookiePolicy 的屬性)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy strict_domain}@anchor{4016}
@deffn {屬性} DefaultCookiePolicy.strict_domain

不允許網站設定具有國家代碼頂層域名的兩層域名，如 @code{.co.uk}、@code{.gov.uk}、@code{.co.nz} 等。 這遠遠不夠完美，也不能保證一定有效！
@end deffn

@geindex RFC; RFC 2965
RFC 2965@footnote{https://datatracker.ietf.org/doc/html/rfc2965.html} 通訊協定調整嚴格度的控制選項：

@geindex strict_rfc2965_unverifiable (http.cookiejar.DefaultCookiePolicy 的屬性)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy strict_rfc2965_unverifiable}@anchor{4017}
@deffn {屬性} DefaultCookiePolicy.strict_rfc2965_unverifiable

遵循針對不可驗證事務（transaction）的 
@geindex RFC; RFC 2965
RFC 2965@footnote{https://datatracker.ietf.org/doc/html/rfc2965.html} 規則（不可驗證事務通常是由重定向或請求發佈在其它網站的圖片導致的）。 如果該屬性為假值，則`永遠不會'基於可驗證性而阻止 cookie
@end deffn

Netscape 通訊協定調整嚴格度的控制選項：

@geindex strict_ns_unverifiable (http.cookiejar.DefaultCookiePolicy 的屬性)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy strict_ns_unverifiable}@anchor{4018}
@deffn {屬性} DefaultCookiePolicy.strict_ns_unverifiable

即便是對 Netscape cookie 也要應用 
@geindex RFC; RFC 2965
RFC 2965@footnote{https://datatracker.ietf.org/doc/html/rfc2965.html} 規則。
@end deffn

@geindex strict_ns_domain (http.cookiejar.DefaultCookiePolicy 的屬性)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy strict_ns_domain}@anchor{4019}
@deffn {屬性} DefaultCookiePolicy.strict_ns_domain

指明針對 Netscape cookie 的網域匹配規則的嚴格程度。 可接受的值見下文。
@end deffn

@geindex strict_ns_set_initial_dollar (http.cookiejar.DefaultCookiePolicy 的屬性)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy strict_ns_set_initial_dollar}@anchor{401a}
@deffn {屬性} DefaultCookiePolicy.strict_ns_set_initial_dollar

忽略 Set-Cookie: 標頭中名稱以 @code{'$'} 開頭的 cookies。
@end deffn

@geindex strict_ns_set_path (http.cookiejar.DefaultCookiePolicy 的屬性)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy strict_ns_set_path}@anchor{401b}
@deffn {屬性} DefaultCookiePolicy.strict_ns_set_path

不允許設置路徑與請求 URL 路徑不匹配的 cookie。
@end deffn

@ref{4019,,strict_ns_domain} 是一系列旗標。它的值由將旗標按位元或組成（例如，@code{DomainStrictNoDots|DomainStrictNonDomain} 表示兩個旗標都被設定）。

@geindex DomainStrictNoDots (http.cookiejar.DefaultCookiePolicy 的屬性)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy DomainStrictNoDots}@anchor{401c}
@deffn {屬性} DefaultCookiePolicy.DomainStrictNoDots

設定 cookie 時，「host 前綴」不得包含點（例如，@code{www.foo.bar.com} 不能為 @code{.bar.com} 設定 cookie，因為 @code{www.foo} 包含一個點）。
@end deffn

@geindex DomainStrictNonDomain (http.cookiejar.DefaultCookiePolicy 的屬性)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy DomainStrictNonDomain}@anchor{401d}
@deffn {屬性} DefaultCookiePolicy.DomainStrictNonDomain

未明確指定 @code{domain} cookie-attribute 的 Cookie 只能回傳給與設定 Cookie 的網域相同的網域（例如，@code{spam.example.com} 將不會回傳來自 @code{example.com} 但沒有 @code{domain} cookie-attribute 的 Cookie）。
@end deffn

@geindex DomainRFC2965Match (http.cookiejar.DefaultCookiePolicy 的屬性)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy DomainRFC2965Match}@anchor{401e}
@deffn {屬性} DefaultCookiePolicy.DomainRFC2965Match

設定 cookie 時，需要完整的 
@geindex RFC; RFC 2965
RFC 2965@footnote{https://datatracker.ietf.org/doc/html/rfc2965.html} 網域匹配。
@end deffn

為了方便起見，以下屬性是上述旗標最有用的組合：

@geindex DomainLiberal (http.cookiejar.DefaultCookiePolicy 的屬性)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy DomainLiberal}@anchor{401f}
@deffn {屬性} DefaultCookiePolicy.DomainLiberal

等於 0（即關閉上述所有 Netscape 網域嚴格度旗標）。
@end deffn

@geindex DomainStrict (http.cookiejar.DefaultCookiePolicy 的屬性)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy DomainStrict}@anchor{4020}
@deffn {屬性} DefaultCookiePolicy.DomainStrict

等價於 @code{DomainStrictNoDots|DomainStrictNonDomain}。
@end deffn

@node Cookie 物件<2>,範例<41>,DefaultCookiePolicy 物件,http cookiejar --- HTTP 用戶端的 Cookie 處理
@anchor{library/http cookiejar cookie-objects}@anchor{4021}
@subsubsection Cookie 物件


@ref{3ff4,,Cookie} 實例的 Python 屬性大致對應於各種 cookie 標準中指定的標準 cookie 屬性。 這個對應關係不是一一對應的，因為有複雜的規則來指定預設值，因為 @code{max-age} 和 @code{expires} cookie 屬性包含相等的訊息，也因為 
@geindex RFC; RFC 2109
RFC 2109@footnote{https://datatracker.ietf.org/doc/html/rfc2109.html} cookie 可能會被 @ref{74,,http.cookiejar} 從版本 1「降級」到版本 0 (Netscape) cookie。

除了在 @ref{3fef,,CookiePolicy} 方法中的罕見情況外，不應該對這些屬性進行指定。 這個類別不會強制執行內部一致性，所以如果你這麼做，你應該要知道你在做什麼。

@geindex version (http.cookiejar.Cookie 的屬性)
@anchor{library/http cookiejar http cookiejar Cookie version}@anchor{4022}
@deffn {屬性} Cookie.version

整數或 @ref{87e,,None}。 Netscape cookie 的 @ref{4022,,version} 為 0。 
@geindex RFC; RFC 2965
RFC 2965@footnote{https://datatracker.ietf.org/doc/html/rfc2965.html} 和 
@geindex RFC; RFC 2109
RFC 2109@footnote{https://datatracker.ietf.org/doc/html/rfc2109.html} cookie 的 @code{version} cookie 屬性為 1。但是，請注意 @ref{74,,http.cookiejar} 可能會將 RFC 2109 cookie 「降級」 為 Netscape cookie，在這種情況下 @ref{4022,,version} 為 0。
@end deffn

@geindex name (http.cookiejar.Cookie 的屬性)
@anchor{library/http cookiejar http cookiejar Cookie name}@anchor{4023}
@deffn {屬性} Cookie.name

Cookie 名稱（字串）。
@end deffn

@geindex value (http.cookiejar.Cookie 的屬性)
@anchor{library/http cookiejar http cookiejar Cookie value}@anchor{4024}
@deffn {屬性} Cookie.value

Cookie 值（字串），或 @ref{87e,,None}。
@end deffn

@geindex port (http.cookiejar.Cookie 的屬性)
@anchor{library/http cookiejar http cookiejar Cookie port}@anchor{4025}
@deffn {屬性} Cookie.port

代表一個連接埠或一組連接埠的字串 (例如「80」，或「880,8080」)，或 @ref{87e,,None}。
@end deffn

@geindex domain (http.cookiejar.Cookie 的屬性)
@anchor{library/http cookiejar http cookiejar Cookie domain}@anchor{4026}
@deffn {屬性} Cookie.domain

Cookie 網域（字串）。
@end deffn

@geindex path (http.cookiejar.Cookie 的屬性)
@anchor{library/http cookiejar http cookiejar Cookie path}@anchor{4027}
@deffn {屬性} Cookie.path

Cookie 路徑（字串，例如 @code{'/acme/rocket_launchers'}）。
@end deffn

@geindex secure (http.cookiejar.Cookie 的屬性)
@anchor{library/http cookiejar http cookiejar Cookie secure}@anchor{4028}
@deffn {屬性} Cookie.secure

如果 cookie 只能透過安全連線回傳，則為 @code{True}。
@end deffn

@geindex expires (http.cookiejar.Cookie 的屬性)
@anchor{library/http cookiejar http cookiejar Cookie expires}@anchor{4029}
@deffn {屬性} Cookie.expires

自 epoch 起計算的整數到期時間，以秒為單位，或 @ref{87e,,None}。另請參閱 @ref{402a,,is_expired()} 方法。
@end deffn

@geindex discard (http.cookiejar.Cookie 的屬性)
@anchor{library/http cookiejar http cookiejar Cookie discard}@anchor{402b}
@deffn {屬性} Cookie.discard

如果這是 session cookie，即為 @code{True}。
@end deffn

@geindex comment (http.cookiejar.Cookie 的屬性)
@anchor{library/http cookiejar http cookiejar Cookie comment}@anchor{402c}
@deffn {屬性} Cookie.comment

來自伺服器解釋此 cookie 功能的字串註解，或 @ref{87e,,None}。
@end deffn

@geindex comment_url (http.cookiejar.Cookie 的屬性)
@anchor{library/http cookiejar http cookiejar Cookie comment_url}@anchor{402d}
@deffn {屬性} Cookie.comment_url

鏈接到來自伺服器的解釋此 cookie 功能的註釋的 URL，或者為 @ref{87e,,None}。
@end deffn

@geindex rfc2109 (http.cookiejar.Cookie 的屬性)
@anchor{library/http cookiejar http cookiejar Cookie rfc2109}@anchor{402e}
@deffn {屬性} Cookie.rfc2109

@code{True} 如果這個 cookie 是以 
@geindex RFC; RFC 2109
RFC 2109@footnote{https://datatracker.ietf.org/doc/html/rfc2109.html} cookie 的形式收到的 (即這個 cookie 是在 @code{Set-Cookie} 標頭中收到的，而且在那個標頭中的 Version cookie-attribute 的值是 1)。 提供這個屬性的原因是 @ref{74,,http.cookiejar} 可能會將 RFC 2109 cookie 「降級」 為 Netscape cookie，在這種情況下 @ref{4022,,version} 的值是 0。
@end deffn

@geindex port_specified (http.cookiejar.Cookie 的屬性)
@anchor{library/http cookiejar http cookiejar Cookie port_specified}@anchor{402f}
@deffn {屬性} Cookie.port_specified

如果伺服器顯式地指定了一個連接埠或一組連接埠（在 @code{Set-Cookie} / @code{Set-Cookie2} 標頭中)。
@end deffn

@geindex domain_specified (http.cookiejar.Cookie 的屬性)
@anchor{library/http cookiejar http cookiejar Cookie domain_specified}@anchor{4030}
@deffn {屬性} Cookie.domain_specified

如果伺服器明確指定網域，則為 @code{True}。
@end deffn

@geindex domain_initial_dot (http.cookiejar.Cookie 的屬性)
@anchor{library/http cookiejar http cookiejar Cookie domain_initial_dot}@anchor{4031}
@deffn {屬性} Cookie.domain_initial_dot

如果伺服器明確指定的網域以點 (@code{'.'}) 開頭，則為 @code{True}。
@end deffn

Cookies 可能具有額外的非標準 cookie 屬性。你可以使用下列方法存取這些屬性：

@geindex has_nonstandard_attr() (http.cookiejar.Cookie 的方法)
@anchor{library/http cookiejar http cookiejar Cookie has_nonstandard_attr}@anchor{4032}
@deffn {方法} Cookie.has_nonstandard_attr (name)

如果 cookie 具有指定的 cookie 屬性，則回傳 @code{True} 。
@end deffn

@geindex get_nonstandard_attr() (http.cookiejar.Cookie 的方法)
@anchor{library/http cookiejar http cookiejar Cookie get_nonstandard_attr}@anchor{4033}
@deffn {方法} Cookie.get_nonstandard_attr (name, default=None)

如果 cookie 具有指定的 cookie 屬性，則回傳其值。否則，回傳 `default'。
@end deffn

@geindex set_nonstandard_attr() (http.cookiejar.Cookie 的方法)
@anchor{library/http cookiejar http cookiejar Cookie set_nonstandard_attr}@anchor{4034}
@deffn {方法} Cookie.set_nonstandard_attr (name, value)

設定指定 cookie 屬性的值。
@end deffn

@ref{3ff4,,Cookie} 類別也定義了以下方法：

@geindex is_expired() (http.cookiejar.Cookie 的方法)
@anchor{library/http cookiejar http cookiejar Cookie is_expired}@anchor{402a}
@deffn {方法} Cookie.is_expired (now=None)

如果 cookie 已經超過伺服器要求的過期時間，則回傳 @code{True} 。 如果給定了 `now' （以自紀元起的秒數為單位），則會回傳 cookie 是否已在指定時間過期。
@end deffn

@node 範例<41>,,Cookie 物件<2>,http cookiejar --- HTTP 用戶端的 Cookie 處理
@anchor{library/http cookiejar examples}@anchor{4035}
@subsubsection 範例


第一個範例展示了 @ref{74,,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

本範例說明如何使用你的 Netscape、Mozilla 或 Lynx cookies 打開 URL (假設 Unix/Netscape 會慣用 cookies 檔案的位置)：

@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

下一個範例說明 @ref{1cbc,,DefaultCookiePolicy} 的使用。開啟 
@geindex RFC; RFC 2965
RFC 2965@footnote{https://datatracker.ietf.org/doc/html/rfc2965.html} cookies，在設定和回傳 Netscape cookies 時對網域更嚴格，並阻止某些網域設定 cookies 或讓其回傳：

@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 伺服器與用戶模組,xmlrpc client --- XML-RPC 用戶端存取,http cookiejar --- HTTP 用戶端的 Cookie 處理,網路協定 Internet protocols 及支援
@anchor{library/xmlrpc doc}@anchor{4036}@anchor{library/xmlrpc module-xmlrpc}@anchor{133}@anchor{library/xmlrpc translation-repo}@anchor{4037}@anchor{library/xmlrpc xmlrpc-xmlrpc-server-and-client-modules}@anchor{4038}
@subsection @code{xmlrpc} --- XMLRPC 伺服器與用戶模組


@geindex module; xmlrpc

XML-RPC 是一種遠端程序呼叫 (Remote Procedure Call) 方法，它使用通過 HTTP 傳輸（transport）的 XML 來做傳遞。有了它，用戶端可以在遠端伺服器上呼叫帶有參數的方法（伺服器以 URI 命名）並取得結構化的資料。

@code{xmlrpc} 是一個集合了 XML-RPC 伺服器與用戶端模組實作的套件。這些模組是：


@itemize *

@item 
@ref{134,,xmlrpc.client}

@item 
@ref{135,,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 用戶端存取,xmlrpc server --- 基本 XML-RPC 伺服器,xmlrpc --- XMLRPC 伺服器與用戶模組,網路協定 Internet protocols 及支援
@anchor{library/xmlrpc client doc}@anchor{4039}@anchor{library/xmlrpc client module-xmlrpc client}@anchor{134}@anchor{library/xmlrpc client translation-repo}@anchor{403a}@anchor{library/xmlrpc client xmlrpc-client-xml-rpc-client-access}@anchor{403b}
@subsection @code{xmlrpc.client} --- XML-RPC 用戶端存取


@geindex module; xmlrpc.client

`原始碼：'Lib/xmlrpc/client.py@footnote{https://github.com/python/cpython/tree/3.14/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 @ref{134,,xmlrpc.client} module is not secure against maliciously
constructed data.  If you need to parse untrusted or unauthenticated data,
see @ref{3ba2,,XML 安全性}.
@end quotation
@end cartouche


在 3.5 版的變更: For HTTPS URIs, @ref{134,,xmlrpc.client} now performs all the necessary
certificate and hostname checks by default.


@c include for modules that don't work on WASM

@ref{2006,,可用性}: not WASI.

此模組在 WebAssembly 平台上不起作用或無法使用。更多資訊請參閱 @ref{1a99,,WebAssembly 平台}。

@geindex ServerProxy (xmlrpc.client 中的類別)
@anchor{library/xmlrpc client xmlrpc client ServerProxy}@anchor{c43}
@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 @ref{c43,,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{198,,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{4dd,,datetime.datetime} objects and binary data to be
presented as @ref{192,,bytes} objects; this flag is false by default.
@ref{4dd,,datetime.datetime}, @ref{192,,bytes} and @ref{343,,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{355,,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 版的變更: 新增 `use_builtin_types' 旗標。



在 3.8 版的變更: 新增 `headers' 參數。


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{3c1,,bool}

@item

@code{int}、@code{i1}、@code{i2}、@code{i4}、@code{i8} 或 @code{biginteger}

@tab

@ref{19b,,int} in range from -2147483648 to 2147483647.
Values get the @code{<int>} tag.

@item

@code{double} 或 @code{float}

@tab

@ref{196,,float}.  Values get the @code{<double>} tag.

@item

@code{string}

@tab

@ref{169,,str}

@item

@code{array}

@tab

@ref{24d,,list} or @ref{60c,,tuple} containing
conformable elements.  Arrays are returned as
@ref{24d,,lists}.

@item

@code{struct}

@tab

@ref{183,,dict}.  Keys must be strings, values may be
any conformable type.  Objects of user-defined
classes can be passed in; only their
@ref{776,,__dict__} attribute is transmitted.

@item

@code{dateTime.iso8601}

@tab

@ref{15da,,DateTime} or @ref{4dd,,datetime.datetime}.
Returned type depends on values of
`use_builtin_types' and `use_datetime' flags.

@item

@code{base64}

@tab

@ref{403c,,Binary}, @ref{192,,bytes} or
@ref{343,,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{1fe,,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{403d,,Fault} instance, used to signal XML-RPC server errors, or
@ref{403e,,ProtocolError} used to signal an error in the HTTP/HTTPS transport layer.
Both @ref{403d,,Fault} and @ref{403e,,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{192,,bytes} or @ref{343,,bytearray} classes or the
@ref{403c,,Binary} wrapper class described below.

@code{Server} is retained as an alias for @ref{c43,,ServerProxy} for backwards
compatibility.  New code should use @ref{c43,,ServerProxy}.


在 3.5 版的變更: 加入 `context' 引數。



在 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 物件:: 
* 日期時間物件:: 
* Binary Objects:: 
* Fault Objects:: 
* ProtocolError 物件:: 
* MultiCall 物件:: 
* 便捷的函式:: 
* Example of Client Usage:: 
* Example of Client and Server Usage:: 

@end menu

@node ServerProxy 物件,日期時間物件,,xmlrpc client --- XML-RPC 用戶端存取
@anchor{library/xmlrpc client id1}@anchor{403f}@anchor{library/xmlrpc client serverproxy-objects}@anchor{4040}
@subsubsection ServerProxy 物件


A @ref{c43,,ServerProxy} instance has a method corresponding to each remote
procedure call accepted by the XML-RPC server.  Calling the method performs an
RPC, dispatched by both name and argument signature (e.g. the same method name
can be overloaded with multiple argument signatures).  The RPC finishes by
returning a value, which may be either returned data in a conformant type or a
@ref{403d,,Fault} or @ref{403e,,ProtocolError} object indicating an error.

Servers that support the XML introspection API support some common methods
grouped under the reserved @code{system} attribute:

@geindex listMethods() (xmlrpc.client.ServerProxy.system 的方法)
@anchor{library/xmlrpc client xmlrpc client ServerProxy system listMethods}@anchor{4041}
@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{4042}
@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{4043}
@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{c43,,ServerProxy} support the @ref{1e1,,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 日期時間物件,Binary Objects,ServerProxy 物件,xmlrpc client --- XML-RPC 用戶端存取
@anchor{library/xmlrpc client datetime-objects}@anchor{4044}@anchor{library/xmlrpc client id2}@anchor{4045}
@subsubsection 日期時間物件


@geindex DateTime (xmlrpc.client 中的類別)
@anchor{library/xmlrpc client xmlrpc client DateTime}@anchor{15da}
@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{4dd,,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{4046}
@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{4047}
@deffn {方法} encode (out)

Write the XML-RPC encoding of this @ref{15da,,DateTime} item to the `out' stream
object.
@end deffn

It also supports certain of Python's built-in operators through
@ref{14a1,,rich comparison} and @ref{828,,__repr__()}
methods.
@end deffn

A working example follows. The server code:

@example
import datetime
from xmlrpc.server import SimpleXMLRPCServer
import xmlrpc.client

def today():
    today = datetime.datetime.today()
    return xmlrpc.client.DateTime(today)

server = SimpleXMLRPCServer(("localhost", 8000))
print("Listening on port 8000...")
server.register_function(today, "today")
server.serve_forever()
@end example

The client code for the preceding server:

@example
import xmlrpc.client
import datetime

proxy = xmlrpc.client.ServerProxy("http://localhost:8000/")

today = proxy.today()
# 將 ISO8601 字串轉換成 datetime 物件
converted = datetime.datetime.strptime(today.value, "%Y%m%dT%H:%M:%S")
print("Today: %s" % converted.strftime("%d.%m.%Y, %H:%M"))
@end example

@node Binary Objects,Fault Objects,日期時間物件,xmlrpc client --- XML-RPC 用戶端存取
@anchor{library/xmlrpc client binary-objects}@anchor{4048}@anchor{library/xmlrpc client id3}@anchor{4049}
@subsubsection Binary Objects


@geindex Binary (xmlrpc.client 中的類別)
@anchor{library/xmlrpc client xmlrpc client Binary}@anchor{403c}
@deffn {類別} xmlrpc.client.Binary

This class may be initialized from bytes data (which may include NULs). The
primary access to the content of a @ref{403c,,Binary} object is provided by an
attribute:

@geindex data (xmlrpc.client.Binary 的屬性)
@anchor{library/xmlrpc client xmlrpc client Binary data}@anchor{404a}
@deffn {屬性} data

The binary data encapsulated by the @ref{403c,,Binary} instance.  The data is
provided as a @ref{192,,bytes} object.
@end deffn

@ref{403c,,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{404b}
@deffn {方法} decode (bytes)

Accept a base64 @ref{192,,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{404c}
@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{ce9,,__eq__()} and @ref{170b,,__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 物件,Binary Objects,xmlrpc client --- XML-RPC 用戶端存取
@anchor{library/xmlrpc client fault-objects}@anchor{404d}@anchor{library/xmlrpc client id4}@anchor{404e}
@subsubsection Fault Objects


@geindex Fault (xmlrpc.client 中的類別)
@anchor{library/xmlrpc client xmlrpc client Fault}@anchor{403d}
@deffn {類別} xmlrpc.client.Fault

A @ref{403d,,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{404f}
@deffn {屬性} faultCode

An int indicating the fault type.
@end deffn

@geindex faultString (xmlrpc.client.Fault 的屬性)
@anchor{library/xmlrpc client xmlrpc client Fault faultString}@anchor{4050}
@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{403d,,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 物件,MultiCall 物件,Fault Objects,xmlrpc client --- XML-RPC 用戶端存取
@anchor{library/xmlrpc client protocol-error-objects}@anchor{4051}@anchor{library/xmlrpc client protocolerror-objects}@anchor{4052}
@subsubsection ProtocolError 物件


@geindex ProtocolError (xmlrpc.client 中的類別)
@anchor{library/xmlrpc client xmlrpc client ProtocolError}@anchor{403e}
@deffn {類別} xmlrpc.client.ProtocolError

A @ref{403e,,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{4053}
@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{4054}
@deffn {屬性} errcode

The error code.
@end deffn

@geindex errmsg (xmlrpc.client.ProtocolError 的屬性)
@anchor{library/xmlrpc client xmlrpc client ProtocolError errmsg}@anchor{4055}
@deffn {屬性} errmsg

The error message or diagnostic string.
@end deffn

@geindex headers (xmlrpc.client.ProtocolError 的屬性)
@anchor{library/xmlrpc client xmlrpc client ProtocolError headers}@anchor{4056}
@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{403e,,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 物件,便捷的函式,ProtocolError 物件,xmlrpc client --- XML-RPC 用戶端存取
@anchor{library/xmlrpc client multicall-objects}@anchor{4057}
@subsubsection MultiCall 物件


The @ref{4058,,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{4058}
@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 parameters in the
@ref{4058,,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{125c,,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 便捷的函式,Example of Client Usage,MultiCall 物件,xmlrpc client --- XML-RPC 用戶端存取
@anchor{library/xmlrpc client convenience-functions}@anchor{4059}
@subsubsection 便捷的函式


@geindex dumps() (於 xmlrpc.client 模組中)
@anchor{library/xmlrpc client xmlrpc client dumps}@anchor{405a}
@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{403d,,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{87e,,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{162c}
@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{403d,,Fault} exception.
The `use_builtin_types' flag can be used to cause date/time values to be
presented as @ref{4dd,,datetime.datetime} objects and binary data to be
presented as @ref{192,,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 版的變更: 新增 `use_builtin_types' 旗標。

@end deffn

@node Example of Client Usage,Example of Client and Server Usage,便捷的函式,xmlrpc client --- XML-RPC 用戶端存取
@anchor{library/xmlrpc client example-of-client-usage}@anchor{405b}@anchor{library/xmlrpc client xmlrpc-client-example}@anchor{405c}
@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 用戶端存取
@anchor{library/xmlrpc client example-of-client-and-server-usage}@anchor{405d}
@subsubsection Example of Client and Server Usage


See @ref{405e,,SimpleXMLRPCServer 範例}.

@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 --- 基本 XML-RPC 伺服器,ipaddress --- IPv4/IPv6 操作函式庫,xmlrpc client --- XML-RPC 用戶端存取,網路協定 Internet protocols 及支援
@anchor{library/xmlrpc server doc}@anchor{405f}@anchor{library/xmlrpc server module-xmlrpc server}@anchor{135}@anchor{library/xmlrpc server translation-repo}@anchor{4060}@anchor{library/xmlrpc server xmlrpc-server-basic-xml-rpc-servers}@anchor{4061}
@subsection @code{xmlrpc.server} --- 基本 XML-RPC 伺服器


@geindex module; xmlrpc.server

`原始碼：'Lib/xmlrpc/server.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/xmlrpc/server.py}


__________________________________________________________________


The @ref{135,,xmlrpc.server} module provides a basic server framework for XML-RPC
servers written in Python.  Servers can either be free standing, using
@ref{4062,,SimpleXMLRPCServer}, or embedded in a CGI environment, using
@ref{4063,,CGIXMLRPCRequestHandler}.

@cartouche
@quotation 警告 
The @ref{135,,xmlrpc.server} module is not secure against maliciously
constructed data.  If you need to parse untrusted or unauthenticated data,
see @ref{3ba2,,XML 安全性}.
@end quotation
@end cartouche

@c include for modules that don't work on WASM

@ref{2006,,可用性}: not WASI.

此模組在 WebAssembly 平台上不起作用或無法使用。更多資訊請參閱 @ref{1a99,,WebAssembly 平台}。

@geindex SimpleXMLRPCServer (xmlrpc.server 中的類別)
@anchor{library/xmlrpc server xmlrpc server SimpleXMLRPCServer}@anchor{4062}
@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{1528,,SimpleXMLRPCRequestHandler}.  The `addr' and `requestHandler' parameters
are passed to the @ref{1520,,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{134,,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{162c,,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{4063}
@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{134,,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{162c,,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{1528}
@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{4062,,SimpleXMLRPCServer} constructor parameter is honored.
@end deffn

@menu
* SimpleXMLRPCServer 物件:: 
* CGIXMLRPCRequestHandler:: 
* Documenting XMLRPC server:: 
* DocXMLRPCServer 物件:: 
* DocCGIXMLRPCRequestHandler:: 

@end menu

@node SimpleXMLRPCServer 物件,CGIXMLRPCRequestHandler,,xmlrpc server --- 基本 XML-RPC 伺服器
@anchor{library/xmlrpc server simple-xmlrpc-servers}@anchor{4064}@anchor{library/xmlrpc server simplexmlrpcserver-objects}@anchor{4065}
@subsubsection SimpleXMLRPCServer 物件


The @ref{4062,,SimpleXMLRPCServer} class is based on
@ref{1520,,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{4066}
@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{14d5,,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{14d5,,function.__name__} will be used.


在 3.7 版的變更: @ref{4066,,register_function()} 也可被當作裝飾器使用。

@end deffn

@geindex register_instance() (xmlrpc.server.SimpleXMLRPCServer 的方法)
@anchor{library/xmlrpc server xmlrpc server SimpleXMLRPCServer register_instance}@anchor{4067}
@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{4066,,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{4068}
@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{4069}
@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{406a}
@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 範例:: 

@end menu

@node SimpleXMLRPCServer 範例,,,SimpleXMLRPCServer 物件
@anchor{library/xmlrpc server id1}@anchor{406b}@anchor{library/xmlrpc server simplexmlrpcserver-example}@anchor{405e}
@subsubsection SimpleXMLRPCServer 範例


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 only within a secure, closed network.
@end quotation
@end cartouche

@example
import datetime

class ExampleService:
    def getData(self):
        return '42'

    class currentTime:
        @@staticmethod
        def getCurrentTime():
            return datetime.datetime.now()

with SimpleXMLRPCServer(("localhost", 8000)) as server:
    server.register_function(pow)
    server.register_function(lambda x,y: x+y, 'add')
    server.register_instance(ExampleService(), allow_dotted_names=True)
    server.register_multicall_functions()
    print('Serving XML-RPC on localhost port 8000')
    try:
        server.serve_forever()
    except KeyboardInterrupt:
        print("\nKeyboard interrupt received, exiting.")
        sys.exit(0)
@end example

This ExampleService demo can be invoked from the command line:

@example
python -m xmlrpc.server
@end example

The client that interacts with the above server is included in
@code{Lib/xmlrpc/client.py}:

@example
server = ServerProxy("http://localhost:8000")

try:
    print(server.currentTime.getCurrentTime())
except Error as v:
    print("ERROR", v)

multi = MultiCall(server)
multi.getData()
multi.pow(2,9)
multi.add(1,2)
try:
    for response in multi():
        print(response)
except Error as v:
    print("ERROR", v)
@end example

This client which interacts with the demo XMLRPC server can be invoked as:

@example
python -m xmlrpc.client
@end example

@node CGIXMLRPCRequestHandler,Documenting XMLRPC server,SimpleXMLRPCServer 物件,xmlrpc server --- 基本 XML-RPC 伺服器
@anchor{library/xmlrpc server cgixmlrpcrequesthandler}@anchor{406c}
@subsubsection CGIXMLRPCRequestHandler


The @ref{4063,,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{406d}
@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{14d5,,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{14d5,,function.__name__} will be used.


在 3.7 版的變更: @ref{406d,,register_function()} 也可被當作裝飾器使用。

@end deffn

@geindex register_instance() (xmlrpc.server.CGIXMLRPCRequestHandler 的方法)
@anchor{library/xmlrpc server xmlrpc server CGIXMLRPCRequestHandler register_instance}@anchor{406e}
@deffn {方法} CGIXMLRPCRequestHandler.register_instance (instance)

Register an object which is used to expose method names  which have not been
registered using @ref{406d,,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{406f}
@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{4070}
@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{4071}
@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
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 物件,CGIXMLRPCRequestHandler,xmlrpc server --- 基本 XML-RPC 伺服器
@anchor{library/xmlrpc server documenting-xmlrpc-server}@anchor{4072}
@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{1c6f,,DocXMLRPCServer}, or embedded in a CGI environment, using
@ref{4073,,DocCGIXMLRPCRequestHandler}.

@geindex DocXMLRPCServer (xmlrpc.server 中的類別)
@anchor{library/xmlrpc server xmlrpc server DocXMLRPCServer}@anchor{1c6f}
@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{4062,,SimpleXMLRPCServer}; `requestHandler' defaults to
@ref{4074,,DocXMLRPCRequestHandler}.


在 3.3 版的變更: The `use_builtin_types' flag was added.

@end deffn

@geindex DocCGIXMLRPCRequestHandler (xmlrpc.server 中的類別)
@anchor{library/xmlrpc server xmlrpc server DocCGIXMLRPCRequestHandler}@anchor{4073}
@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{4074}
@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{1c6f,,DocXMLRPCServer} constructor parameter is
honored.
@end deffn

@node DocXMLRPCServer 物件,DocCGIXMLRPCRequestHandler,Documenting XMLRPC server,xmlrpc server --- 基本 XML-RPC 伺服器
@anchor{library/xmlrpc server doc-xmlrpc-servers}@anchor{4075}@anchor{library/xmlrpc server docxmlrpcserver-objects}@anchor{4076}
@subsubsection DocXMLRPCServer 物件


The @ref{1c6f,,DocXMLRPCServer} class is derived from @ref{4062,,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{4077}
@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{4078}
@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{4079}
@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 物件,xmlrpc server --- 基本 XML-RPC 伺服器
@anchor{library/xmlrpc server doccgixmlrpcrequesthandler}@anchor{407a}
@subsubsection DocCGIXMLRPCRequestHandler


The @ref{4073,,DocCGIXMLRPCRequestHandler} class is derived from
@ref{4063,,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{407b}
@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{407c}
@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{407d}
@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 操作函式庫,,xmlrpc server --- 基本 XML-RPC 伺服器,網路協定 Internet protocols 及支援
@anchor{library/ipaddress doc}@anchor{407e}@anchor{library/ipaddress ipaddress-ipv4-ipv6-manipulation-library}@anchor{407f}@anchor{library/ipaddress module-ipaddress}@anchor{84}@anchor{library/ipaddress translation-repo}@anchor{4080}
@subsection @code{ipaddress} --- IPv4/IPv6 操作函式庫


@geindex module; ipaddress

`原始碼：'Lib/ipaddress.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/ipaddress.py}


__________________________________________________________________


@ref{84,,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{4081,,ipaddress 模組介紹}.


在 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 操作函式庫
@anchor{library/ipaddress convenience-factory-functions}@anchor{4082}
@subsubsection Convenience factory functions


The @ref{84,,ipaddress} module provides factory functions to conveniently create
IP addresses, networks and interfaces:

@geindex ip_address() (於 ipaddress 模組中)
@anchor{library/ipaddress ipaddress ip_address}@anchor{4083}
@deffn {函式} ipaddress.ip_address (address)

Return an @ref{507,,IPv4Address} or @ref{508,,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{2eb,,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{4084}
@deffn {函式} ipaddress.ip_network (address, strict=True)

Return an @ref{509,,IPv4Network} or @ref{50a,,IPv6Network} object depending on
the IP address passed as argument.  `address' is a string or integer
representing the IP network.  Either IPv4 or IPv6 networks may be supplied;
integers less than @code{2**32} will be considered to be IPv4 by default.  `strict'
is passed to @ref{509,,IPv4Network} or @ref{50a,,IPv6Network} constructor.  A
@ref{2eb,,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{4085}
@deffn {函式} ipaddress.ip_interface (address)

Return an @ref{1ac3,,IPv4Interface} or @ref{1ac4,,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{2eb,,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 操作函式庫
@anchor{library/ipaddress ip-addresses}@anchor{4086}
@subsubsection IP Addresses


@menu
* Address objects:: 
* Conversion to Strings and Integers:: 
* 運算子: 運算子<2>. 

@end menu

@node Address objects,Conversion to Strings and Integers,,IP Addresses
@anchor{library/ipaddress address-objects}@anchor{4087}
@subsubsection Address objects


The @ref{507,,IPv4Address} and @ref{508,,IPv6Address} objects share a lot of common
attributes.  Some attributes that are only meaningful for IPv6 addresses are
also implemented by @ref{507,,IPv4Address} objects, in order to make it easier to
write code that handles both IP versions correctly.  Address objects are
@ref{81d,,hashable}, so they can be used as keys in dictionaries.

@geindex IPv4Address (ipaddress 中的類別)
@anchor{library/ipaddress ipaddress IPv4Address}@anchor{507}
@deffn {類別} ipaddress.IPv4Address (address)

Construct an IPv4 address.  An @ref{4088,,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{192,,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{b52,,inet_pton()}.


@geindex version (ipaddress.IPv4Address 的屬性)
@anchor{library/ipaddress ipaddress IPv4Address version}@anchor{4089}
@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{408a}
@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{408b}
@deffn {屬性} compressed
@end deffn

@geindex exploded (ipaddress.IPv4Address 的屬性)
@anchor{library/ipaddress ipaddress IPv4Address exploded}@anchor{408c}
@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{408d}
@deffn {屬性} packed

The binary representation of this address - a @ref{192,,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{101b}
@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.


在 3.5 版被加入.

@end deffn

@geindex is_multicast (ipaddress.IPv4Address 的屬性)
@anchor{library/ipaddress ipaddress IPv4Address is_multicast}@anchor{408e}
@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{1916}
@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{408f,,IPv6Address.ipv4_mapped}):

@example
address.is_private == address.ipv4_mapped.is_private
@end example
@end itemize

@code{is_private} has value opposite to @ref{115a,,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} 被視為私有。

@item 
@code{2002::/16} 被視為私有。

@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{115a}
@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{408f,,IPv6Address.ipv4_mapped}):

@example
address.is_global == address.ipv4_mapped.is_global
@end example

@code{is_global} has value opposite to @ref{1916,,is_private}, except for the shared address space
(@code{100.64.0.0/10} range) where they are both @code{False}.


在 3.4 版被加入.



在 3.13 版的變更: Fixed some false positives and false negatives, see @ref{1916,,is_private} for details.

@end deffn

@geindex is_unspecified (ipaddress.IPv4Address 的屬性)
@anchor{library/ipaddress ipaddress IPv4Address is_unspecified}@anchor{4090}
@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{4091}
@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{4092,,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{4093}
@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{4094}
@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{506}
@deffn {屬性} ipv6_mapped

@ref{507,,IPv4Address} object representing the IPv4-mapped IPv6 address. See 
@geindex RFC; RFC 4291
RFC 4291@footnote{https://datatracker.ietf.org/doc/html/rfc4291.html}.


在 3.13 版被加入.

@end deffn
@end deffn

@geindex __format__() (ipaddress.IPv4Address 的方法)
@anchor{library/ipaddress ipaddress IPv4Address __format__}@anchor{4095}
@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{169,,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


在 3.9 版被加入.

@end deffn

@geindex IPv6Address (ipaddress 中的類別)
@anchor{library/ipaddress ipaddress IPv6Address}@anchor{508}
@deffn {類別} ipaddress.IPv6Address (address)

Construct an IPv6 address.  An @ref{4088,,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{192,,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{4096}
@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{4097}
@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{507,,IPv4Address} class:

@geindex packed (ipaddress.IPv6Address 的屬性)
@anchor{library/ipaddress ipaddress IPv6Address packed}@anchor{4098}
@deffn {屬性} packed
@end deffn

@geindex reverse_pointer (ipaddress.IPv6Address 的屬性)
@anchor{library/ipaddress ipaddress IPv6Address reverse_pointer}@anchor{18a0}
@deffn {屬性} reverse_pointer
@end deffn

@geindex version (ipaddress.IPv6Address 的屬性)
@anchor{library/ipaddress ipaddress IPv6Address version}@anchor{4099}
@deffn {屬性} version
@end deffn

@geindex max_prefixlen (ipaddress.IPv6Address 的屬性)
@anchor{library/ipaddress ipaddress IPv6Address max_prefixlen}@anchor{409a}
@deffn {屬性} max_prefixlen
@end deffn

@geindex is_multicast (ipaddress.IPv6Address 的屬性)
@anchor{library/ipaddress ipaddress IPv6Address is_multicast}@anchor{409b}
@deffn {屬性} is_multicast
@end deffn

@geindex is_private (ipaddress.IPv6Address 的屬性)
@anchor{library/ipaddress ipaddress IPv6Address is_private}@anchor{1917}
@deffn {屬性} is_private
@end deffn

@geindex is_global (ipaddress.IPv6Address 的屬性)
@anchor{library/ipaddress ipaddress IPv6Address is_global}@anchor{1918}
@deffn {屬性} is_global


在 3.4 版被加入.

@end deffn

@geindex is_unspecified (ipaddress.IPv6Address 的屬性)
@anchor{library/ipaddress ipaddress IPv6Address is_unspecified}@anchor{409c}
@deffn {屬性} is_unspecified
@end deffn

@geindex is_reserved (ipaddress.IPv6Address 的屬性)
@anchor{library/ipaddress ipaddress IPv6Address is_reserved}@anchor{409d}
@deffn {屬性} is_reserved
@end deffn

@geindex is_loopback (ipaddress.IPv6Address 的屬性)
@anchor{library/ipaddress ipaddress IPv6Address is_loopback}@anchor{1901}
@deffn {屬性} is_loopback
@end deffn

@geindex is_link_local (ipaddress.IPv6Address 的屬性)
@anchor{library/ipaddress ipaddress IPv6Address is_link_local}@anchor{409e}
@deffn {屬性} is_link_local
@end deffn

@geindex is_site_local (ipaddress.IPv6Address 的屬性)
@anchor{library/ipaddress ipaddress IPv6Address is_site_local}@anchor{4092}
@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{1916,,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{408f}
@deffn {屬性} ipv4_mapped

For addresses that appear to be IPv4 mapped addresses (starting with
@code{::FFFF/96}), this property will report 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{b01}
@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{409f}
@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{40a0}
@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{40a1}
@deffn {方法} IPv6Address.__format__ (fmt)

Refer to the corresponding method documentation in
@ref{507,,IPv4Address}.


在 3.9 版被加入.

@end deffn

@node Conversion to Strings and Integers,運算子<2>,Address objects,IP Addresses
@anchor{library/ipaddress conversion-to-strings-and-integers}@anchor{40a2}
@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{169,,str()} and @ref{19b,,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 運算子<2>,,Conversion to Strings and Integers,IP Addresses
@anchor{library/ipaddress operators}@anchor{40a3}
@subsubsection 運算子


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
* 比較運算子:: 
* 算術運算子:: 

@end menu

@node 比較運算子,算術運算子,,運算子<2>
@anchor{library/ipaddress comparison-operators}@anchor{40a4}
@subsubsection 比較運算子


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 算術運算子,,比較運算子,運算子<2>
@anchor{library/ipaddress arithmetic-operators}@anchor{40a5}
@subsubsection 算術運算子


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 操作函式庫
@anchor{library/ipaddress ip-network-definitions}@anchor{40a6}
@subsubsection IP Network definitions


The @ref{509,,IPv4Network} and @ref{50a,,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:: 
* 運算子: 運算子<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{40a7}
@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,運算子<3>,Prefix net mask and host mask,IP Network definitions
@anchor{library/ipaddress network-objects}@anchor{40a8}
@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{509,,IPv4Network} and @ref{50a,,IPv6Network},
so to avoid duplication they are only documented for @ref{509,,IPv4Network}.
Network objects are @ref{81d,,hashable}, so they can be used as keys in
dictionaries.

@geindex IPv4Network (ipaddress 中的類別)
@anchor{library/ipaddress ipaddress IPv4Network}@anchor{509}
@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{192,,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{507,,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{4088,,AddressValueError} is raised if `address' is not a valid IPv4
address.  A @ref{40a9,,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{2eb,,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{198,,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{40aa}
@deffn {屬性} version
@end deffn

@geindex max_prefixlen (ipaddress.IPv4Network 的屬性)
@anchor{library/ipaddress ipaddress IPv4Network max_prefixlen}@anchor{40ab}
@deffn {屬性} max_prefixlen

Refer to the corresponding attribute documentation in
@ref{507,,IPv4Address}.
@end deffn

@geindex is_multicast (ipaddress.IPv4Network 的屬性)
@anchor{library/ipaddress ipaddress IPv4Network is_multicast}@anchor{40ac}
@deffn {屬性} is_multicast
@end deffn

@geindex is_private (ipaddress.IPv4Network 的屬性)
@anchor{library/ipaddress ipaddress IPv4Network is_private}@anchor{40ad}
@deffn {屬性} is_private
@end deffn

@geindex is_unspecified (ipaddress.IPv4Network 的屬性)
@anchor{library/ipaddress ipaddress IPv4Network is_unspecified}@anchor{40ae}
@deffn {屬性} is_unspecified
@end deffn

@geindex is_reserved (ipaddress.IPv4Network 的屬性)
@anchor{library/ipaddress ipaddress IPv4Network is_reserved}@anchor{40af}
@deffn {屬性} is_reserved
@end deffn

@geindex is_loopback (ipaddress.IPv4Network 的屬性)
@anchor{library/ipaddress ipaddress IPv4Network is_loopback}@anchor{40b0}
@deffn {屬性} is_loopback
@end deffn

@geindex is_link_local (ipaddress.IPv4Network 的屬性)
@anchor{library/ipaddress ipaddress IPv4Network is_link_local}@anchor{40b1}
@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{40b2}
@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{40b3}
@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{40b4}
@deffn {屬性} hostmask

The host mask, as an @ref{507,,IPv4Address} object.
@end deffn

@geindex netmask (ipaddress.IPv4Network 的屬性)
@anchor{library/ipaddress ipaddress IPv4Network netmask}@anchor{40b5}
@deffn {屬性} netmask

The net mask, as an @ref{507,,IPv4Address} object.
@end deffn

@geindex with_prefixlen (ipaddress.IPv4Network 的屬性)
@anchor{library/ipaddress ipaddress IPv4Network with_prefixlen}@anchor{40b6}
@deffn {屬性} with_prefixlen
@end deffn

@geindex compressed (ipaddress.IPv4Network 的屬性)
@anchor{library/ipaddress ipaddress IPv4Network compressed}@anchor{40b7}
@deffn {屬性} compressed
@end deffn

@geindex exploded (ipaddress.IPv4Network 的屬性)
@anchor{library/ipaddress ipaddress IPv4Network exploded}@anchor{40b8}
@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{40b9}
@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{40ba}
@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{40bb}
@deffn {屬性} num_addresses

The total number of addresses in the network.
@end deffn

@geindex prefixlen (ipaddress.IPv4Network 的屬性)
@anchor{library/ipaddress ipaddress IPv4Network prefixlen}@anchor{40bc}
@deffn {屬性} prefixlen

Length of the network prefix, in bits.
@end deffn

@geindex hosts() (ipaddress.IPv4Network 的方法)
@anchor{library/ipaddress ipaddress IPv4Network hosts}@anchor{40bd}
@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{40be}
@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{40bf}
@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{2eb,,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{109b}
@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{109c}
@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{40c0}
@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


在 3.7 版被加入.

@end deffn

@geindex supernet_of() (ipaddress.IPv4Network 的方法)
@anchor{library/ipaddress ipaddress IPv4Network supernet_of}@anchor{40c1}
@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


在 3.7 版被加入.

@end deffn

@geindex compare_networks() (ipaddress.IPv4Network 的方法)
@anchor{library/ipaddress ipaddress IPv4Network compare_networks}@anchor{40c2}
@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{50a}
@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{192,,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{508,,IPv6Address} object; and the netmask is an
integer representing the prefix length.
@end enumerate

An @ref{4088,,AddressValueError} is raised if `address' is not a valid IPv6
address.  A @ref{40a9,,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{2eb,,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{40c3}
@deffn {屬性} version
@end deffn

@geindex max_prefixlen (ipaddress.IPv6Network 的屬性)
@anchor{library/ipaddress ipaddress IPv6Network max_prefixlen}@anchor{40c4}
@deffn {屬性} max_prefixlen
@end deffn

@geindex is_multicast (ipaddress.IPv6Network 的屬性)
@anchor{library/ipaddress ipaddress IPv6Network is_multicast}@anchor{40c5}
@deffn {屬性} is_multicast
@end deffn

@geindex is_private (ipaddress.IPv6Network 的屬性)
@anchor{library/ipaddress ipaddress IPv6Network is_private}@anchor{40c6}
@deffn {屬性} is_private
@end deffn

@geindex is_unspecified (ipaddress.IPv6Network 的屬性)
@anchor{library/ipaddress ipaddress IPv6Network is_unspecified}@anchor{40c7}
@deffn {屬性} is_unspecified
@end deffn

@geindex is_reserved (ipaddress.IPv6Network 的屬性)
@anchor{library/ipaddress ipaddress IPv6Network is_reserved}@anchor{40c8}
@deffn {屬性} is_reserved
@end deffn

@geindex is_loopback (ipaddress.IPv6Network 的屬性)
@anchor{library/ipaddress ipaddress IPv6Network is_loopback}@anchor{40c9}
@deffn {屬性} is_loopback
@end deffn

@geindex is_link_local (ipaddress.IPv6Network 的屬性)
@anchor{library/ipaddress ipaddress IPv6Network is_link_local}@anchor{40ca}
@deffn {屬性} is_link_local
@end deffn

@geindex network_address (ipaddress.IPv6Network 的屬性)
@anchor{library/ipaddress ipaddress IPv6Network network_address}@anchor{40cb}
@deffn {屬性} network_address
@end deffn

@geindex broadcast_address (ipaddress.IPv6Network 的屬性)
@anchor{library/ipaddress ipaddress IPv6Network broadcast_address}@anchor{40cc}
@deffn {屬性} broadcast_address
@end deffn

@geindex hostmask (ipaddress.IPv6Network 的屬性)
@anchor{library/ipaddress ipaddress IPv6Network hostmask}@anchor{40cd}
@deffn {屬性} hostmask
@end deffn

@geindex netmask (ipaddress.IPv6Network 的屬性)
@anchor{library/ipaddress ipaddress IPv6Network netmask}@anchor{40ce}
@deffn {屬性} netmask
@end deffn

@geindex with_prefixlen (ipaddress.IPv6Network 的屬性)
@anchor{library/ipaddress ipaddress IPv6Network with_prefixlen}@anchor{40cf}
@deffn {屬性} with_prefixlen
@end deffn

@geindex compressed (ipaddress.IPv6Network 的屬性)
@anchor{library/ipaddress ipaddress IPv6Network compressed}@anchor{40d0}
@deffn {屬性} compressed
@end deffn

@geindex exploded (ipaddress.IPv6Network 的屬性)
@anchor{library/ipaddress ipaddress IPv6Network exploded}@anchor{40d1}
@deffn {屬性} exploded
@end deffn

@geindex with_netmask (ipaddress.IPv6Network 的屬性)
@anchor{library/ipaddress ipaddress IPv6Network with_netmask}@anchor{40d2}
@deffn {屬性} with_netmask
@end deffn

@geindex with_hostmask (ipaddress.IPv6Network 的屬性)
@anchor{library/ipaddress ipaddress IPv6Network with_hostmask}@anchor{40d3}
@deffn {屬性} with_hostmask
@end deffn

@geindex num_addresses (ipaddress.IPv6Network 的屬性)
@anchor{library/ipaddress ipaddress IPv6Network num_addresses}@anchor{40d4}
@deffn {屬性} num_addresses
@end deffn

@geindex prefixlen (ipaddress.IPv6Network 的屬性)
@anchor{library/ipaddress ipaddress IPv6Network prefixlen}@anchor{40d5}
@deffn {屬性} prefixlen
@end deffn

@geindex hosts() (ipaddress.IPv6Network 的方法)
@anchor{library/ipaddress ipaddress IPv6Network hosts}@anchor{40d6}
@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{40d7}
@deffn {方法} overlaps (other)
@end deffn

@geindex address_exclude() (ipaddress.IPv6Network 的方法)
@anchor{library/ipaddress ipaddress IPv6Network address_exclude}@anchor{40d8}
@deffn {方法} address_exclude (network)
@end deffn

@geindex subnets() (ipaddress.IPv6Network 的方法)
@anchor{library/ipaddress ipaddress IPv6Network subnets}@anchor{40d9}
@deffn {方法} subnets (prefixlen_diff=1, new_prefix=None)
@end deffn

@geindex supernet() (ipaddress.IPv6Network 的方法)
@anchor{library/ipaddress ipaddress IPv6Network supernet}@anchor{40da}
@deffn {方法} supernet (prefixlen_diff=1, new_prefix=None)
@end deffn

@geindex subnet_of() (ipaddress.IPv6Network 的方法)
@anchor{library/ipaddress ipaddress IPv6Network subnet_of}@anchor{40db}
@deffn {方法} subnet_of (other)
@end deffn

@geindex supernet_of() (ipaddress.IPv6Network 的方法)
@anchor{library/ipaddress ipaddress IPv6Network supernet_of}@anchor{40dc}
@deffn {方法} supernet_of (other)
@end deffn

@geindex compare_networks() (ipaddress.IPv6Network 的方法)
@anchor{library/ipaddress ipaddress IPv6Network compare_networks}@anchor{40dd}
@deffn {方法} compare_networks (other)

Refer to the corresponding attribute documentation in
@ref{509,,IPv4Network}.
@end deffn

@geindex is_site_local (ipaddress.IPv6Network 的屬性)
@anchor{library/ipaddress ipaddress IPv6Network is_site_local}@anchor{40de}
@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 運算子<3>,,Network objects,IP Network definitions
@anchor{library/ipaddress id1}@anchor{40df}
@subsubsection 運算子


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:: 
* 疊代:: 
* Networks as containers of addresses:: 

@end menu

@node Logical operators,疊代,,運算子<3>
@anchor{library/ipaddress logical-operators}@anchor{40e0}
@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 疊代,Networks as containers of addresses,Logical operators,運算子<3>
@anchor{library/ipaddress iteration}@anchor{40e1}
@subsubsection 疊代


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{40bd,,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,,疊代,運算子<3>
@anchor{library/ipaddress networks-as-containers-of-addresses}@anchor{40e2}
@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 操作函式庫
@anchor{library/ipaddress interface-objects}@anchor{40e3}
@subsubsection Interface objects


Interface objects are @ref{81d,,hashable}, so they can be used as keys in
dictionaries.

@geindex IPv4Interface (ipaddress 中的類別)
@anchor{library/ipaddress ipaddress IPv4Interface}@anchor{1ac3}
@deffn {類別} ipaddress.IPv4Interface (address)

Construct an IPv4 interface.  The meaning of `address' is as in the
constructor of @ref{509,,IPv4Network}, except that arbitrary host addresses
are always accepted.

@ref{1ac3,,IPv4Interface} is a subclass of @ref{507,,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{40e4}
@deffn {屬性} ip

The address (@ref{507,,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{40e5}
@deffn {屬性} network

The network (@ref{509,,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{40e6}
@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{40e7}
@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{40e8}
@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{1ac4}
@deffn {類別} ipaddress.IPv6Interface (address)

Construct an IPv6 interface.  The meaning of `address' is as in the
constructor of @ref{50a,,IPv6Network}, except that arbitrary host addresses
are always accepted.

@ref{1ac4,,IPv6Interface} is a subclass of @ref{508,,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{40e9}
@deffn {屬性} ip
@end deffn

@geindex network (ipaddress.IPv6Interface 的屬性)
@anchor{library/ipaddress ipaddress IPv6Interface network}@anchor{40ea}
@deffn {屬性} network
@end deffn

@geindex with_prefixlen (ipaddress.IPv6Interface 的屬性)
@anchor{library/ipaddress ipaddress IPv6Interface with_prefixlen}@anchor{40eb}
@deffn {屬性} with_prefixlen
@end deffn

@geindex with_netmask (ipaddress.IPv6Interface 的屬性)
@anchor{library/ipaddress ipaddress IPv6Interface with_netmask}@anchor{40ec}
@deffn {屬性} with_netmask
@end deffn

@geindex with_hostmask (ipaddress.IPv6Interface 的屬性)
@anchor{library/ipaddress ipaddress IPv6Interface with_hostmask}@anchor{40ed}
@deffn {屬性} with_hostmask

Refer to the corresponding attribute documentation in
@ref{1ac3,,IPv4Interface}.
@end deffn
@end deffn

@menu
* 運算子: 運算子<4>. 

@end menu

@node 運算子<4>,,,Interface objects
@anchor{library/ipaddress id2}@anchor{40ee}
@subsubsection 運算子


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>,,,運算子<4>
@anchor{library/ipaddress id3}@anchor{40ef}
@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 操作函式庫
@anchor{library/ipaddress other-module-level-functions}@anchor{40f0}
@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{40f1}
@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{2eb,,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{40f2}
@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{2eb,,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{109d}
@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{507,,IPv4Address} or
@ref{508,,IPv6Address} in the range and `last' is the last @ref{507,,IPv4Address}
or @ref{508,,IPv6Address} in the range.  A @ref{198,,TypeError} is raised if
`first' or `last' are not IP addresses or are not of the same version.  A
@ref{2eb,,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{109e}
@deffn {函式} ipaddress.collapse_addresses (addresses)

Return an iterator of the collapsed @ref{509,,IPv4Network} or
@ref{50a,,IPv6Network} objects.  `addresses' is an @ref{1428,,iterable} of
@ref{509,,IPv4Network} or @ref{50a,,IPv6Network} objects.  A @ref{198,,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{40f3}
@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 @ref{84,,ipaddress} sort these anyway.  If you need to do this, you can use
this function as the `key' argument to @ref{dc2,,sorted()}.

`obj' is either a network or address object.
@end deffn

@node Custom Exceptions,,Other Module Level Functions,ipaddress --- IPv4/IPv6 操作函式庫
@anchor{library/ipaddress custom-exceptions}@anchor{40f4}
@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{4088}
@deffn {例外} ipaddress.AddressValueError (ValueError)

Any value error related to the address.
@end deffn

@geindex NetmaskValueError
@anchor{library/ipaddress ipaddress NetmaskValueError}@anchor{40a9}
@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 多媒體服務,國際化,網路協定 Internet protocols 及支援,Python 標準函式庫 Standard Library
@anchor{library/mm doc}@anchor{40f5}@anchor{library/mm mmedia}@anchor{40f6}@anchor{library/mm multimedia-services}@anchor{40f7}@anchor{library/mm translation-repo}@anchor{40f8}
@section 多媒體服務


此章節所描述的模組 (module) 實作了多種在多媒體服務中相當有用的演算法和介面，並可在安裝時決定是否要使用它們。以下為綜述：

@menu
* wave: wave --- 讀寫 WAV 檔案. 讀寫 WAV 檔案
* colorsys: colorsys --- 顏色系統間的轉換. 顏色系統間的轉換

@end menu

@node wave --- 讀寫 WAV 檔案,colorsys --- 顏色系統間的轉換,,多媒體服務
@anchor{library/wave doc}@anchor{40f9}@anchor{library/wave module-wave}@anchor{119}@anchor{library/wave wave-read-and-write-wav-files}@anchor{40fa}
@subsection @code{wave} --- 讀寫 WAV 檔案


@geindex module; wave

@c Documentations stolen from comments in file.

`原始碼：'Lib/wave.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/wave.py}


__________________________________________________________________


@ref{119,,wave} 模組為波形音訊檔案格式「WAVE」（或稱「WAV」）提供了便捷的介面。僅支援未壓縮的 PCM 編碼波形檔。


在 3.12 版的變更: 增加了標頭  @code{WAVE_FORMAT_EXTENSIBLE} 的支援，要求的擴展格式為 @code{KSDATAFORMAT_SUBTYPE_PCM}。


@ref{119,,wave} 模組定義了以下的函式和例外:

@geindex open() (於 wave 模組中)
@anchor{library/wave wave open}@anchor{b3c}
@deffn {函式} wave.open (file, mode=None)

如果 `file' 是一個字串，會打開對應名稱的檔案，否則會以類檔案物件處理。`mode' 可以是：


@table @asis

@item @code{'rb'}

唯讀模式。

@item @code{'wb'}

唯寫模式。
@end table

請注意，不支援同時讀寫 WAV 檔案。

`mode' 設定為 @code{'rb'} 時，會回傳一個 @ref{333,,Wave_read} 物件，`mode' 設定為 @code{'wb'} 時，則回傳一個 @ref{334,,Wave_write} 物件。如果省略 `mode'，並且將類檔案 (file-like) 物件作為 `file' 參數傳遞，則 @code{file.mode} 會是 `mode' 的預設值。

如果你傳遞一個類檔案物件，當呼叫其 @code{close()} 方法時，wave 物件不會自動關閉該物件；關閉檔案物件的責任會在呼叫者上。

@ref{b3c,,open()} 函式可以在 @ref{186,,with} 陳述式中使用。當 @code{with} 區塊完成時，會呼叫 @ref{40fb,,Wave_read.close()} 或是 @ref{40fc,,Wave_write.close()} 方法。


在 3.4 版的變更: 增加對不可搜尋 (unseekable) 檔案的支援。

@end deffn

@geindex Error
@anchor{library/wave wave Error}@anchor{40fd}
@deffn {例外} wave.Error

當不符合 WAV 格式或無法操作時會引發錯誤。
@end deffn

@menu
* Wave_read 物件:: 
* Wave_write 物件:: 

@end menu

@node Wave_read 物件,Wave_write 物件,,wave --- 讀寫 WAV 檔案
@anchor{library/wave id1}@anchor{40fe}@anchor{library/wave wave-read-objects}@anchor{40ff}
@subsubsection Wave_read 物件


@geindex Wave_read (wave 中的類別)
@anchor{library/wave wave Wave_read}@anchor{333}
@deffn {類別} wave.Wave_read

讀取一個 WAV 檔案。

由 @ref{b3c,,open()} 回傳的 Wave_read 物件具有以下方法：

@geindex close() (wave.Wave_read 的方法)
@anchor{library/wave wave Wave_read close}@anchor{40fb}
@deffn {方法} close ()

關閉 @ref{119,,wave} 開啟的串流並使該實例無法使用。當物件回收時自動呼叫。
@end deffn

@geindex getnchannels() (wave.Wave_read 的方法)
@anchor{library/wave wave Wave_read getnchannels}@anchor{4100}
@deffn {方法} getnchannels ()

回傳音訊聲道的數量（單聲道為 @code{1}，立體聲為 @code{2}）。
@end deffn

@geindex getsampwidth() (wave.Wave_read 的方法)
@anchor{library/wave wave Wave_read getsampwidth}@anchor{4101}
@deffn {方法} getsampwidth ()

回傳以位元組表示的取樣寬度 (sample width)。
@end deffn

@geindex getframerate() (wave.Wave_read 的方法)
@anchor{library/wave wave Wave_read getframerate}@anchor{4102}
@deffn {方法} getframerate ()

回傳取樣率。
@end deffn

@geindex getnframes() (wave.Wave_read 的方法)
@anchor{library/wave wave Wave_read getnframes}@anchor{4103}
@deffn {方法} getnframes ()

回傳音訊幀數。
@end deffn

@geindex getcomptype() (wave.Wave_read 的方法)
@anchor{library/wave wave Wave_read getcomptype}@anchor{4104}
@deffn {方法} getcomptype ()

回傳壓縮類型（僅支援 @code{'NONE'} 類型）。
@end deffn

@geindex getcompname() (wave.Wave_read 的方法)
@anchor{library/wave wave Wave_read getcompname}@anchor{4105}
@deffn {方法} getcompname ()

@ref{4104,,getcomptype()} 的人類可讀的版本。通常使用 @code{'not compressed'} 代替 @code{'NONE'}。
@end deffn

@geindex getparams() (wave.Wave_read 的方法)
@anchor{library/wave wave Wave_read getparams}@anchor{11e5}
@deffn {方法} getparams ()

回傳一個 @ref{4db,,namedtuple()} @code{(nchannels, sampwidth, framerate, nframes, comptype, compname)}，等同於 @code{get*()} 方法的輸出。
@end deffn

@geindex readframes() (wave.Wave_read 的方法)
@anchor{library/wave wave Wave_read readframes}@anchor{4106}
@deffn {方法} readframes (n)

讀取並回傳以 @ref{192,,bytes} 物件表示的最多 `n' 個音訊幀。
@end deffn

@geindex rewind() (wave.Wave_read 的方法)
@anchor{library/wave wave Wave_read rewind}@anchor{4107}
@deffn {方法} rewind ()

重置檔案指標至音訊流的開頭。
@end deffn

以下兩個方法是為了與舊的 @code{aifc} 模組保持相容性，並不執行任何操作。

@geindex getmarkers() (wave.Wave_read 的方法)
@anchor{library/wave wave Wave_read getmarkers}@anchor{336}
@deffn {方法} getmarkers ()

回傳 @code{None}。


Deprecated since version 3.13, will be removed in version 3.15: 該方法是為了保持與 @code{aifc} 模組相容性而留存，此模組已於 Python 3.13 中刪除。

@end deffn

@geindex getmark() (wave.Wave_read 的方法)
@anchor{library/wave wave Wave_read getmark}@anchor{335}
@deffn {方法} getmark (id)

引發錯誤。


Deprecated since version 3.13, will be removed in version 3.15: 該方法是為了保持與 @code{aifc} 模組相容性而留存，此模組已於 Python 3.13 中刪除。

@end deffn

以下兩個方法所定義的「位置」，在它們之間是相容的，但其他情況下則取決於具體實作方式。

@geindex setpos() (wave.Wave_read 的方法)
@anchor{library/wave wave Wave_read setpos}@anchor{4108}
@deffn {方法} setpos (pos)

將檔案指標設定為指定的位置。
@end deffn

@geindex tell() (wave.Wave_read 的方法)
@anchor{library/wave wave Wave_read tell}@anchor{4109}
@deffn {方法} tell ()

回傳目前的檔案指標位置。
@end deffn
@end deffn

@node Wave_write 物件,,Wave_read 物件,wave --- 讀寫 WAV 檔案
@anchor{library/wave id2}@anchor{410a}@anchor{library/wave wave-write-objects}@anchor{11e6}
@subsubsection Wave_write 物件


@geindex Wave_write (wave 中的類別)
@anchor{library/wave wave Wave_write}@anchor{334}
@deffn {類別} wave.Wave_write

寫入一個 WAV 檔案。

Wave_write 物件，由 @ref{b3c,,open()} 回傳。

對於可搜尋 (seekable) 的輸出串流，@code{wave} 標頭將自動更新，以反映實際寫入的幀數。對於不可搜尋的串流，當寫入第一個幀資料時，`nframes' 的值必須是準確的。要取得準確的 `nframes' 值，可以通過呼叫 @ref{410b,,setnframes()} 或 @ref{410c,,setparams()} 方法，並在呼叫 @ref{40fc,,close()} 之前設定將寫入的幀數量，然後使用 @ref{11e7,,writeframesraw()} 方法寫入幀資料；或者通過呼叫 @ref{11e8,,writeframes()} 方法一次性寫入所有的幀資料。在後一種情況下，@ref{11e8,,writeframes()} 方法將計算資料中的幀數量，並在寫入幀資料之前相應地設定 `nframes' 的值。


在 3.4 版的變更: 增加對不可搜尋 (unseekable) 檔案的支援。


Wave_write 物件具有以下方法：

@geindex close() (wave.Wave_write 的方法)
@anchor{library/wave wave Wave_write close}@anchor{40fc}
@deffn {方法} close ()

確保 `nframes' 正確，如果該檔案是由 @ref{119,,wave} 開啟的，則關閉該檔案。此方法在物件回收時被呼叫。如果輸出串流不可搜尋且 `nframes' 不符合實際寫入的幀數，則會引發例外。
@end deffn

@geindex setnchannels() (wave.Wave_write 的方法)
@anchor{library/wave wave Wave_write setnchannels}@anchor{410d}
@deffn {方法} setnchannels (n)

設定音訊的通道數量。
@end deffn

@geindex setsampwidth() (wave.Wave_write 的方法)
@anchor{library/wave wave Wave_write setsampwidth}@anchor{410e}
@deffn {方法} setsampwidth (n)

設定取樣寬度為 `n' 個位元組。
@end deffn

@geindex setframerate() (wave.Wave_write 的方法)
@anchor{library/wave wave Wave_write setframerate}@anchor{410f}
@deffn {方法} setframerate (n)

設定取樣頻率為 `n'。


在 3.2 版的變更: 此方法的非整數輸入會被將四捨五入到最接近的整數。

@end deffn

@geindex setnframes() (wave.Wave_write 的方法)
@anchor{library/wave wave Wave_write setnframes}@anchor{410b}
@deffn {方法} setnframes (n)

設定幀數為 `n'。如果實際寫入的幀數不同，則稍後將進行更改（如果輸出串流不可搜尋，則此嘗試將引發錯誤）。
@end deffn

@geindex setcomptype() (wave.Wave_write 的方法)
@anchor{library/wave wave Wave_write setcomptype}@anchor{4110}
@deffn {方法} setcomptype (type, name)

設定壓縮類型和描述。目前只支援壓縮類型為 @code{NONE}，表示無壓縮。
@end deffn

@geindex setparams() (wave.Wave_write 的方法)
@anchor{library/wave wave Wave_write setparams}@anchor{410c}
@deffn {方法} setparams (tuple)

這個 `tuple' 應該是 @code{(nchannels, sampwidth, framerate, nframes, comptype, compname)}，值需要是符合 @code{set*()} 方法的參數。設定所有參數。
@end deffn

@geindex tell() (wave.Wave_write 的方法)
@anchor{library/wave wave Wave_write tell}@anchor{4111}
@deffn {方法} tell ()

回傳檔案中的指標位置，其指標位置含意與 @ref{4109,,Wave_read.tell()} 和 @ref{4108,,Wave_read.setpos()} 是一致的。
@end deffn

@geindex writeframesraw() (wave.Wave_write 的方法)
@anchor{library/wave wave Wave_write writeframesraw}@anchor{11e7}
@deffn {方法} writeframesraw (data)

寫入音訊幀，不修正 `nframes'。


在 3.4 版的變更: 現在可接受任何 @ref{193,,bytes-like object}。

@end deffn

@geindex writeframes() (wave.Wave_write 的方法)
@anchor{library/wave wave Wave_write writeframes}@anchor{11e8}
@deffn {方法} writeframes (data)

寫入音訊幀並確保 `nframes' 正確。如果輸出串流不可搜尋，並且在寫入 `data' 後已寫入的總幀數與先前設定的 `nframes' 值不符，則會引發錯誤。


在 3.4 版的變更: 現在可接受任何 @ref{193,,bytes-like object}。


注意在呼叫 @ref{11e8,,writeframes()} 或 @ref{11e7,,writeframesraw()} 之後設置任何參數都是無效的，任何嘗試這樣做的操作都會引發 @ref{40fd,,wave.Error}。
@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 --- 讀寫 WAV 檔案,多媒體服務
@anchor{library/colorsys doc}@anchor{4112}@anchor{library/colorsys colorsys-conversions-between-color-systems}@anchor{4113}@anchor{library/colorsys module-colorsys}@anchor{20}@anchor{library/colorsys translation-repo}@anchor{4114}
@subsection @code{colorsys} --- 顏色系統間的轉換


@geindex module; colorsys

`原始碼：'Lib/colorsys.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/colorsys.py}


__________________________________________________________________


@ref{20,,colorsys} 模組 (module) 定義了電腦顯示器所用的 RGB （紅綠藍）色彩空間與三種其他色彩座標系統：YIQ、HLS (色相、亮度、飽和度) 和 HSV (色相、 飽和度、 明度) 所表示的顏色值之間的雙向轉換。所有這些色彩空間的座標都使用浮點數值 (floating-point) 來表示。在 YIQ 空間中，Y 座標值為 0 和 1 之間，而 I 和 Q 座標均可以為正數或負數。在所有其他空間中，座標值均為 0 和 1 之間。


@subsubheading 也參考


有關色彩空間的更多資訊請見 @indicateurl{https://poynton.ca/ColorFAQ.html} 和 @indicateurl{https://www.cambridgeincolour.com/tutorials/color-spaces.htm}。


@ref{20,,colorsys} 模組定義了以下函式：

@geindex rgb_to_yiq() (於 colorsys 模組中)
@anchor{library/colorsys colorsys rgb_to_yiq}@anchor{4115}
@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{4116}
@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{19c4}
@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{4117}
@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{4118}
@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{4119}
@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 國際化,以 Tk 打造圖形使用者介面 Graphical User Interfaces,多媒體服務,Python 標準函式庫 Standard Library
@anchor{library/i18n doc}@anchor{411a}@anchor{library/i18n i18n}@anchor{411b}@anchor{library/i18n internationalization}@anchor{411c}@anchor{library/i18n translation-repo}@anchor{411d}
@section 國際化


本章所描述的模組透過提供用於程式訊息中語言的選擇機制或是調整輸出以符合當地慣例，來幫助你編寫不依賴語言和地區設定的軟體

本章節所描述的模組列表為：

@menu
* gettext: gettext --- 多語言國際化服務. 多語言國際化服務
* locale: locale --- 國際化服務. 國際化服務

@end menu

@node gettext --- 多語言國際化服務,locale --- 國際化服務,,國際化
@anchor{library/gettext doc}@anchor{411e}@anchor{library/gettext gettext-multilingual-internationalization-services}@anchor{411f}@anchor{library/gettext module-gettext}@anchor{67}
@subsection @code{gettext} --- 多語言國際化服務


@geindex module; gettext

`原始碼：'Lib/gettext.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/gettext.py}


__________________________________________________________________


The @ref{67,,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:: 
* 致謝: 致謝<9>. 

@end menu

@node GNU gettext API,Class-based API,,gettext --- 多語言國際化服務
@anchor{library/gettext gnu-gettext-api}@anchor{4120}
@subsubsection GNU @code{gettext} API


The @ref{67,,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{4121}
@deffn {函式} gettext.bindtextdomain (domain, localedir=None)

Bind the `domain' to the locale directory `localedir'.  More concretely,
@ref{67,,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{3e4,,sys.base_prefix}). For this reason, it is always best to call
@ref{4121,,bindtextdomain()} with an explicit absolute path at the start of your
application.
}
@end deffn

@geindex textdomain() (於 gettext 模組中)
@anchor{library/gettext gettext textdomain}@anchor{4122}
@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 _ （底線）;gettext

@geindex gettext() (於 gettext 模組中)
@anchor{library/gettext gettext gettext}@anchor{165e}
@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{4123}
@deffn {函式} gettext.dgettext (domain, message)

Like @ref{165e,,gettext()}, but look the message up in the specified `domain'.
@end deffn

@geindex ngettext() (於 gettext 模組中)
@anchor{library/gettext gettext ngettext}@anchor{4124}
@deffn {函式} gettext.ngettext (singular, plural, n)

Like @ref{165e,,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{4125}
@deffn {函式} gettext.dngettext (domain, singular, plural, n)

Like @ref{4124,,ngettext()}, but look the message up in the specified `domain'.
@end deffn

@geindex pgettext() (於 gettext 模組中)
@anchor{library/gettext gettext pgettext}@anchor{bdf}
@deffn {函式} gettext.pgettext (context, message)
@end deffn

@geindex dpgettext() (於 gettext 模組中)
@anchor{library/gettext gettext dpgettext}@anchor{4126}
@deffn {函式} gettext.dpgettext (domain, context, message)
@end deffn

@geindex npgettext() (於 gettext 模組中)
@anchor{library/gettext gettext npgettext}@anchor{4127}
@deffn {函式} gettext.npgettext (context, singular, plural, n)
@end deffn

@geindex dnpgettext() (於 gettext 模組中)
@anchor{library/gettext gettext dnpgettext}@anchor{4128}
@deffn {函式} gettext.dnpgettext (domain, context, singular, plural, n)

Similar to the corresponding functions without the @code{p} in the prefix (that
is, @ref{67,,gettext()}, @ref{4123,,dgettext()}, @ref{4124,,ngettext()}, @ref{4125,,dngettext()}),
but the translation is restricted to the given message `context'.


在 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 --- 多語言國際化服務
@anchor{library/gettext class-based-api}@anchor{4129}
@subsubsection Class-based API


The class-based API of the @ref{67,,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{412a,,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{412b}
@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{4122,,textdomain()} takes.  Optional
`localedir' is as in @ref{4121,,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{
請見上方 @ref{4121,,bindtextdomain()} 之註解。
}  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.

@ref{412b,,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 @ref{412b,,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{c64}
@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{412b,,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{412a,,GNUTranslations}.  The class's constructor must
take a single @ref{13c4,,file object} argument.

If multiple files are found, later files are used as fallbacks for earlier ones.
To allow setting the fallback, @ref{750,,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{2c0,,OSError} if
`fallback' is false (which is the default), and returns a
@ref{412c,,NullTranslations} instance if `fallback' is true.


在 3.3 版的變更: @ref{124e,,IOError} 曾經被引發，現在它是一個 @ref{2c0,,OSError} 的別名。



在 3.11 版的變更: `codeset' 參數被移除。

@end deffn

@geindex install() (於 gettext 模組中)
@anchor{library/gettext gettext install}@anchor{c65}
@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{c64,,translation()}.

For the `names' parameter, please see the description of the translation
object's @ref{412d,,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{412e}
@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{412c,,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{412c}
@deffn {類別} gettext.NullTranslations (fp=None)

Takes an optional @ref{13c4,,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{412f,,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{4130}
@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{412f}
@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{4131}
@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{4132}
@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{4133}
@deffn {方法} pgettext (context, message)

If a fallback has been set, forward @ref{bdf,,pgettext()} to the fallback.
Otherwise, return the translated message.  Overridden in derived classes.


在 3.8 版被加入.

@end deffn

@geindex npgettext() (gettext.NullTranslations 的方法)
@anchor{library/gettext gettext NullTranslations npgettext}@anchor{4134}
@deffn {方法} npgettext (context, singular, plural, n)

If a fallback has been set, forward @ref{4127,,npgettext()} to the fallback.
Otherwise, return the translated message.  Overridden in derived classes.


在 3.8 版被加入.

@end deffn

@geindex info() (gettext.NullTranslations 的方法)
@anchor{library/gettext gettext NullTranslations info}@anchor{4135}
@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{4136}
@deffn {方法} charset ()

Return the encoding of the message catalog file.
@end deffn

@geindex install() (gettext.NullTranslations 的方法)
@anchor{library/gettext gettext NullTranslations install}@anchor{412d}
@deffn {方法} install (names=None)

This method installs @ref{4131,,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 版的變更: 新增 @code{'pgettext'} 與 @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{4137}
@subsubsection The @code{GNUTranslations} class


The @code{gettext} module provides one additional class derived from
@ref{412c,,NullTranslations}: @ref{412a,,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{412a,,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{412a,,GNUTranslations} class can raise @ref{2c0,,OSError}.

@geindex GNUTranslations (gettext 中的類別)
@anchor{library/gettext gettext GNUTranslations}@anchor{412a}
@deffn {類別} gettext.GNUTranslations

The following methods are overridden from the base class implementation:

@geindex gettext() (gettext.GNUTranslations 的方法)
@anchor{library/gettext gettext GNUTranslations gettext}@anchor{4138}
@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{4131,,gettext()} method.  Otherwise, the
`message' id is returned.
@end deffn

@geindex ngettext() (gettext.GNUTranslations 的方法)
@anchor{library/gettext gettext GNUTranslations ngettext}@anchor{4139}
@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{4132,,ngettext()}
method.  Otherwise, when `n' is 1 `singular' is returned, and `plural' is
returned in all other cases.

以下是個範例：

@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{413a}
@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
@ref{bdf,,pgettext()} method.  Otherwise, the `message' id is returned.


在 3.8 版被加入.

@end deffn

@geindex npgettext() (gettext.GNUTranslations 的方法)
@anchor{library/gettext gettext GNUTranslations npgettext}@anchor{413b}
@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
@ref{4127,,npgettext()} method.  Otherwise, when `n' is 1 `singular' is
returned, and `plural' is returned in all other cases.


在 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{413c}
@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{413d}
@subsubsection The Catalog constructor


@geindex GNOME

GNOME uses a version of the @ref{67,,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{c64,,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,致謝<9>,Class-based API,gettext --- 多語言國際化服務
@anchor{library/gettext i18n-howto}@anchor{3280}@anchor{library/gettext internationalizing-your-programs-and-modules}@anchor{413e}
@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 @ref{67,,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{67,,_}.  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
@ref{67,,gettext} module for the actual translation processing at
run-time.

How you use the @ref{67,,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{413f}
@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{4140}
@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{c65,,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{4141}
@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{4142}
@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{1a62,,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 致謝<9>,,Internationalizing your programs and modules,gettext --- 多語言國際化服務
@anchor{library/gettext acknowledgements}@anchor{4143}
@subsubsection 致謝


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

@subsubheading 註解


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node locale --- 國際化服務,,gettext --- 多語言國際化服務,國際化
@anchor{library/locale doc}@anchor{4144}@anchor{library/locale locale-internationalization-services}@anchor{4145}@anchor{library/locale module-locale}@anchor{8a}@anchor{library/locale translation-repo}@anchor{4146}
@subsection @code{locale} --- 國際化服務


@geindex module; locale

`原始碼：'Lib/locale.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/locale.py}


__________________________________________________________________


The @ref{8a,,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 @ref{8a,,locale} module is implemented on top of the @code{_locale} module,
which in turn uses an ANSI C locale implementation if available.

The @ref{8a,,locale} module defines the following exception and functions:

@geindex Error
@anchor{library/locale locale Error}@anchor{4147}
@deffn {例外} locale.Error

Exception raised when the locale passed to @ref{327,,setlocale()} is not
recognized.
@end deffn

@geindex setlocale() (於 locale 模組中)
@anchor{library/locale locale setlocale}@anchor{327}
@deffn {函式} locale.setlocale (category, locale=None)

If `locale' is given and not @code{None}, @ref{327,,setlocale()} modifies the locale
setting for the `category'. The available categories are listed in the data
description below. `locale' may be a @ref{4148,,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{4147,,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{4148,,locale name},
but without encoding and @code{@@}-modifier.
The language code and encoding can be @code{None}.

If `locale' is omitted or @code{None}, the current setting for `category' is
returned.

@ref{327,,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.
@end deffn

@geindex localeconv() (於 locale 模組中)
@anchor{library/locale locale localeconv}@anchor{df3}
@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

分類

@tab

Key

@tab

含義

@item

@ref{4149,,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{414a,,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{414b,,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{414a,,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{452}
@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 @ref{452,,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{414c}
@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{414d}
@deffn {資料} locale.D_T_FMT

Get a string that can be used as a format string for @ref{13ea,,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{414e}
@deffn {資料} locale.D_FMT

Get a string that can be used as a format string for @ref{13ea,,time.strftime()} to
represent a date in a locale-specific way.
@end deffn

@geindex T_FMT (於 locale 模組中)
@anchor{library/locale locale T_FMT}@anchor{414f}
@deffn {資料} locale.T_FMT

Get a string that can be used as a format string for @ref{13ea,,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{4150}
@deffn {資料} locale.T_FMT_AMPM

Get a format string for @ref{13ea,,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{4151}
@deffn {資料} locale.DAY_1
@anchor{library/locale locale DAY_2}@anchor{4152}
@deffnx {資料} locale.DAY_2
@anchor{library/locale locale DAY_3}@anchor{4153}
@deffnx {資料} locale.DAY_3
@anchor{library/locale locale DAY_4}@anchor{4154}
@deffnx {資料} locale.DAY_4
@anchor{library/locale locale DAY_5}@anchor{4155}
@deffnx {資料} locale.DAY_5
@anchor{library/locale locale DAY_6}@anchor{4156}
@deffnx {資料} locale.DAY_6
@anchor{library/locale locale DAY_7}@anchor{4157}
@deffnx {資料} locale.DAY_7

Get the name of the n-th day of the week.

@cartouche
@quotation 備註 
This follows the US convention of @ref{4151,,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{4158}
@deffn {資料} locale.ABDAY_1
@anchor{library/locale locale ABDAY_2}@anchor{4159}
@deffnx {資料} locale.ABDAY_2
@anchor{library/locale locale ABDAY_3}@anchor{415a}
@deffnx {資料} locale.ABDAY_3
@anchor{library/locale locale ABDAY_4}@anchor{415b}
@deffnx {資料} locale.ABDAY_4
@anchor{library/locale locale ABDAY_5}@anchor{415c}
@deffnx {資料} locale.ABDAY_5
@anchor{library/locale locale ABDAY_6}@anchor{415d}
@deffnx {資料} locale.ABDAY_6
@anchor{library/locale locale ABDAY_7}@anchor{415e}
@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{415f}
@deffn {資料} locale.MON_1
@anchor{library/locale locale MON_2}@anchor{4160}
@deffnx {資料} locale.MON_2
@anchor{library/locale locale MON_3}@anchor{4161}
@deffnx {資料} locale.MON_3
@anchor{library/locale locale MON_4}@anchor{4162}
@deffnx {資料} locale.MON_4
@anchor{library/locale locale MON_5}@anchor{4163}
@deffnx {資料} locale.MON_5
@anchor{library/locale locale MON_6}@anchor{4164}
@deffnx {資料} locale.MON_6
@anchor{library/locale locale MON_7}@anchor{4165}
@deffnx {資料} locale.MON_7
@anchor{library/locale locale MON_8}@anchor{4166}
@deffnx {資料} locale.MON_8
@anchor{library/locale locale MON_9}@anchor{4167}
@deffnx {資料} locale.MON_9
@anchor{library/locale locale MON_10}@anchor{4168}
@deffnx {資料} locale.MON_10
@anchor{library/locale locale MON_11}@anchor{4169}
@deffnx {資料} locale.MON_11
@anchor{library/locale locale MON_12}@anchor{416a}
@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{416b}
@deffn {資料} locale.ABMON_1
@anchor{library/locale locale ABMON_2}@anchor{416c}
@deffnx {資料} locale.ABMON_2
@anchor{library/locale locale ABMON_3}@anchor{416d}
@deffnx {資料} locale.ABMON_3
@anchor{library/locale locale ABMON_4}@anchor{416e}
@deffnx {資料} locale.ABMON_4
@anchor{library/locale locale ABMON_5}@anchor{416f}
@deffnx {資料} locale.ABMON_5
@anchor{library/locale locale ABMON_6}@anchor{4170}
@deffnx {資料} locale.ABMON_6
@anchor{library/locale locale ABMON_7}@anchor{4171}
@deffnx {資料} locale.ABMON_7
@anchor{library/locale locale ABMON_8}@anchor{4172}
@deffnx {資料} locale.ABMON_8
@anchor{library/locale locale ABMON_9}@anchor{4173}
@deffnx {資料} locale.ABMON_9
@anchor{library/locale locale ABMON_10}@anchor{4174}
@deffnx {資料} locale.ABMON_10
@anchor{library/locale locale ABMON_11}@anchor{4175}
@deffnx {資料} locale.ABMON_11
@anchor{library/locale locale ABMON_12}@anchor{4176}
@deffnx {資料} locale.ABMON_12

Get the abbreviated name of the n-th month.
@end deffn

@geindex RADIXCHAR (於 locale 模組中)
@anchor{library/locale locale RADIXCHAR}@anchor{4177}
@deffn {資料} locale.RADIXCHAR

Get the radix character (decimal dot, decimal comma, etc.).
@end deffn

@geindex THOUSEP (於 locale 模組中)
@anchor{library/locale locale THOUSEP}@anchor{4178}
@deffn {資料} locale.THOUSEP

Get the separator character for thousands (groups of three digits).
@end deffn

@geindex YESEXPR (於 locale 模組中)
@anchor{library/locale locale YESEXPR}@anchor{4179}
@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{417a}
@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{4179,,YESEXPR} and
@ref{417a,,NOEXPR} use syntax suitable for the
@code{regex} function from the C library, which might
differ from the syntax used in @ref{be,,re}.
@end quotation
@end cartouche
@end deffn

@geindex CRNCYSTR (於 locale 模組中)
@anchor{library/locale locale CRNCYSTR}@anchor{417b}
@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{417c}
@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{13ea,,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{417d}
@deffn {資料} locale.ERA_D_T_FMT

Get a format string for @ref{13ea,,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{417e}
@deffn {資料} locale.ERA_D_FMT

Get a format string for @ref{13ea,,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{417f}
@deffn {資料} locale.ERA_T_FMT

Get a format string for @ref{13ea,,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{4180}
@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{325}
@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{4148,,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)}.


Deprecated since version 3.11, will be removed in version 3.15.

@end deffn

@geindex getlocale() (於 locale 模組中)
@anchor{library/locale locale getlocale}@anchor{326}
@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{4181,,LC_ALL}.  It defaults to @ref{4182,,LC_CTYPE}.

The language code has the same format as a @ref{4148,,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 getpreferredencoding() (於 locale 模組中)
@anchor{library/locale locale getpreferredencoding}@anchor{755}
@deffn {函式} locale.getpreferredencoding (do_setlocale=True)

Return the @ref{545,,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{327,,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{85f,,Python UTF-8 Mode} is enabled, always
return @code{'utf-8'}, the @ref{545,,locale encoding} and the `do_setlocale'
argument are ignored.

The @ref{4183,,Python preinitialization} configures the LC_CTYPE
locale. See also the @ref{756,,filesystem encoding and error handler}.


在 3.7 版的變更: The function now always returns @code{"utf-8"} on Android or if the
@ref{85f,,Python UTF-8 Mode} is enabled.

@end deffn

@geindex getencoding() (於 locale 模組中)
@anchor{library/locale locale getencoding}@anchor{328}
@deffn {函式} locale.getencoding ()

Get the current @ref{545,,locale encoding}:


@itemize *

@item 
On Android and VxWorks, return @code{"utf-8"}.

@item 
On Unix, return the encoding of the current @ref{4182,,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{4183,,Python preinitialization} configures the LC_CTYPE
locale. See also the @ref{756,,filesystem encoding and error handler}.

This function is similar to
@ref{755,,getpreferredencoding(False)} except this
function ignores the @ref{85f,,Python UTF-8 Mode}.


在 3.11 版被加入.

@end deffn

@geindex normalize() (於 locale 模組中)
@anchor{library/locale locale normalize}@anchor{4184}
@deffn {函式} locale.normalize (localename)

Returns a normalized locale code for the given locale name.  The returned locale
code is formatted for use with @ref{327,,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{327,,setlocale()}.
@end deffn

@geindex strcoll() (於 locale 模組中)
@anchor{library/locale locale strcoll}@anchor{4185}
@deffn {函式} locale.strcoll (string1, string2)

Compares two strings according to the current @ref{4186,,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{1753}
@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{73b}
@deffn {函式} locale.format_string (format, val, grouping=False, monetary=False)

Formats a number `val' according to the current @ref{4149,,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{4187}
@deffn {函式} locale.currency (val, symbol=True, grouping=False, international=False)

Formats a number `val' according to the current @ref{414b,,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{327,,setlocale()} first.
@end quotation
@end cartouche
@end deffn

@geindex str() (於 locale 模組中)
@anchor{library/locale locale str}@anchor{4188}
@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{1021}
@deffn {函式} locale.delocalize (string)

Converts a string into a normalized number string, following the
@ref{4149,,LC_NUMERIC} settings.


在 3.5 版被加入.

@end deffn

@geindex localize() (於 locale 模組中)
@anchor{library/locale locale localize}@anchor{4189}
@deffn {函式} locale.localize (string, grouping=False, monetary=False)

Converts a normalized number string into a formatted string following the
@ref{4149,,LC_NUMERIC} settings.


在 3.10 版被加入.

@end deffn

@geindex atof() (於 locale 模組中)
@anchor{library/locale locale atof}@anchor{418a}
@deffn {函式} locale.atof (string, func=float)

Converts a string to a number, following the @ref{4149,,LC_NUMERIC} settings,
by calling `func' on the result of calling @ref{1021,,delocalize()} on `string'.
@end deffn

@geindex atoi() (於 locale 模組中)
@anchor{library/locale locale atoi}@anchor{418b}
@deffn {函式} locale.atoi (string)

Converts a string to an integer, following the @ref{4149,,LC_NUMERIC} conventions.
@end deffn

@geindex LC_CTYPE (於 locale 模組中)
@anchor{library/locale locale LC_CTYPE}@anchor{4182}
@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, an internal @code{pyctype.h} provides locale-independent
equivalents like @code{Py_TOLOWER}.
@end deffn

@geindex LC_COLLATE (於 locale 模組中)
@anchor{library/locale locale LC_COLLATE}@anchor{4186}
@deffn {資料} locale.LC_COLLATE

Locale category for sorting strings.  The functions @ref{4185,,strcoll()} and
@ref{1753,,strxfrm()} of the @ref{8a,,locale} module are affected.
@end deffn

@geindex LC_TIME (於 locale 模組中)
@anchor{library/locale locale LC_TIME}@anchor{418c}
@deffn {資料} locale.LC_TIME

Locale category for the formatting of time.  The function @ref{13ea,,time.strftime()}
follows these conventions.
@end deffn

@geindex LC_MONETARY (於 locale 模組中)
@anchor{library/locale locale LC_MONETARY}@anchor{414b}
@deffn {資料} locale.LC_MONETARY

Locale category for formatting of monetary values.  The available options are
available from the @ref{df3,,localeconv()} function.
@end deffn

@geindex LC_MESSAGES (於 locale 模組中)
@anchor{library/locale locale LC_MESSAGES}@anchor{418d}
@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{2ed6,,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{4149}
@deffn {資料} locale.LC_NUMERIC

Locale category for formatting numbers.  The functions @ref{73b,,format_string()},
@ref{418b,,atoi()}, @ref{418a,,atof()} and @ref{4188,,str()} of the @ref{8a,,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{4181}
@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{414a}
@deffn {資料} locale.CHAR_MAX

This is a symbolic constant used for different values returned by
@ref{df3,,localeconv()}.
@end deffn

範例：

@example
>>> import locale
>>> loc = locale.getlocale()  # get current locale
# use German locale; name might vary with platform
>>> locale.setlocale(locale.LC_ALL, 'de_DE')
>>> locale.strcoll('f\xe4n', 'foo')  # compare a string containing an umlaut
>>> locale.setlocale(locale.LC_ALL, '@w{'})   # use user's preferred locale
>>> locale.setlocale(locale.LC_ALL, 'C')  # use default (C) locale
>>> locale.setlocale(locale.LC_ALL, loc)  # restore saved locale
@end example

@menu
* 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 --- 國際化服務
@anchor{library/locale background-details-hints-tips-and-caveats}@anchor{418e}
@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{4182,,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{327,,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{13ea,,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{418a,,atof()}, @ref{418b,,atoi()},
@ref{73b,,format_string()}, @ref{4188,,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 --- 國際化服務
@anchor{library/locale locale-name}@anchor{4148}@anchor{library/locale locale-names}@anchor{418f}
@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 --- 國際化服務
@anchor{library/locale embedding-locale}@anchor{4190}@anchor{library/locale for-extension-writers-and-programs-that-embed-python}@anchor{4191}
@subsubsection For extension writers and programs that embed Python


Extension modules should never call @ref{327,,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 @ref{8a,,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 --- 國際化服務
@anchor{library/locale access-to-message-catalogs}@anchor{4192}@anchor{library/locale locale-gettext}@anchor{4193}
@subsubsection Access to message catalogs


@geindex gettext() (於 locale 模組中)
@anchor{library/locale locale gettext}@anchor{4194}
@deffn {函式} locale.gettext (msg)
@end deffn

@geindex dgettext() (於 locale 模組中)
@anchor{library/locale locale dgettext}@anchor{4195}
@deffn {函式} locale.dgettext (domain, msg)
@end deffn

@geindex dcgettext() (於 locale 模組中)
@anchor{library/locale locale dcgettext}@anchor{4196}
@deffn {函式} locale.dcgettext (domain, msg, category)
@end deffn

@geindex textdomain() (於 locale 模組中)
@anchor{library/locale locale textdomain}@anchor{4197}
@deffn {函式} locale.textdomain (domain)
@end deffn

@geindex bindtextdomain() (於 locale 模組中)
@anchor{library/locale locale bindtextdomain}@anchor{4198}
@deffn {函式} locale.bindtextdomain (domain, dir)
@end deffn

@geindex bind_textdomain_codeset() (於 locale 模組中)
@anchor{library/locale locale bind_textdomain_codeset}@anchor{4199}
@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{67,,gettext()},
@ref{4195,,dgettext()}, @ref{4196,,dcgettext()}, @ref{4197,,textdomain()}, @ref{4198,,bindtextdomain()},
and @ref{4199,,bind_textdomain_codeset()}.  These are similar to the same functions in
the @ref{67,,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{67,,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 打造圖形使用者介面 Graphical User Interfaces,開發工具,國際化,Python 標準函式庫 Standard Library
@anchor{library/tk doc}@anchor{419a}@anchor{library/tk graphical-user-interfaces-with-tk}@anchor{419b}@anchor{library/tk tkinter}@anchor{419c}@anchor{library/tk translation-repo}@anchor{419d}
@section 以 Tk 打造圖形使用者介面 (Graphical User Interfaces)


@geindex GUI
@geindex Graphical User Interface（圖形使用者介面）
@geindex Tkinter
@geindex Tk

Tk/Tcl 長期以來一直是 Python 不可或缺的一部分。它提供了一個強大且獨立於平台的視窗工具包，可供使用 @ref{f6,,tkinter} 套件及其擴充套件 @ref{ff,,tkinter.ttk} 模組的 Python 開發者使用。

@ref{f6,,tkinter} 套件是 Tcl/Tk 之上的一個輕薄物件導向層。要使用 @ref{f6,,tkinter}，你不需要編寫 Tcl 程式，但會需要查閱 Tk 文件和部份 Tcl 文件。@ref{f6,,tkinter} 是一組將 Tk 小工具 (widget) 實作為 Python 類別的包裝器。

@ref{f6,,tkinter} 的主要優點是速度快，而且通常與 Python 捆綁 (bundle) 在一起。儘管其標準文件不是很完整，但還是有些不錯的材料，包括：參考資料、教學、書籍等。@ref{f6,,tkinter} 曾因其過時的外觀而眾所皆知，但這在 Tk 8.5 中得到了極大的改進。此外，還有許多其他你可能會感興趣的 GUI 函式庫。Python wiki 列出了幾個替代的 GUI 框架和工具@footnote{https://wiki.python.org/moin/GuiProgramming}。

@menu
* tkinter: tkinter --- Tcl/Tk 的 Python 介面. Tcl/Tk 的 Python 介面
* tkinter.colorchooser: tkinter colorchooser --- 顏色選擇對話框. 顏色選擇對話框
* tkinter.font: tkinter font --- Tkinter 字型包裝器. Tkinter 字型包裝器
* Tkinter 對話框:: 
* tkinter.messagebox: tkinter messagebox --- Tkinter 訊息提示. Tkinter 訊息提示
* tkinter.scrolledtext: tkinter scrolledtext --- 捲動文字小工具. 捲動文字小工具
* tkinter.dnd: tkinter dnd --- 拖放支援. 拖放支援
* tkinter.ttk: tkinter ttk --- Tk 主題化小工具. Tk 主題化小工具
* IDLE: IDLE --- Python 編輯器與 shell<2>. Python 編輯器與 shell
* turtle: turtle --- 龜圖學 Turtle graphics. 龜圖學 (Turtle graphics)

@end menu

@node tkinter --- Tcl/Tk 的 Python 介面,tkinter colorchooser --- 顏色選擇對話框,,以 Tk 打造圖形使用者介面 Graphical User Interfaces
@anchor{library/tkinter doc}@anchor{419e}@anchor{library/tkinter module-tkinter}@anchor{f6}@anchor{library/tkinter tkinter-python-interface-to-tcl-tk}@anchor{419f}
@subsection @code{tkinter} --- Tcl/Tk 的 Python 介面


@geindex module; tkinter

`原始碼：'Lib/tkinter/__init__.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/tkinter/__init__.py}


__________________________________________________________________


@ref{f6,,tkinter} 套件（「Tk 介面」）是 Tcl/Tk GUI 工具集的標準 Python 介面。Tk 和 @ref{f6,,tkinter} 在大多數 Unix 平台（包含 macOS）以及 Windows 系統上都可以使用。

從命令列執行 @code{python -m tkinter} 應該會開啟一個展示簡單 Tk 介面的視窗，讓你知道 @ref{f6,,tkinter} 已正確安裝在你的系統上，並且也會顯示已安裝的 Tcl/Tk 版本，這樣你就可以閱讀該版本專屬的 Tcl/Tk 文件。

Tkinter 支援一系列的 Tcl/Tk 版本，這些版本可以是有或沒有執行緒支援的建構版本。官方的 Python 二進位發行版捆綁了有執行緒支援的 Tcl/Tk 8.6。關於支援版本的更多資訊，請參閱 @ref{3,,_tkinter} 模組的原始碼。

Tkinter 並非一個輕薄的包裝器，而是加入了相當多自身的邏輯，使其體驗更具 Python 風格（pythonic）。本文件將著重於這些新增和變更，對於未變更的細節，則會引導讀者參閱官方的 Tcl/Tk 文件。

@cartouche
@quotation 備註 
Tcl/Tk 8.5（2007）引入了一套現代化的主題式使用者介面元件，以及一個用以操作它們的新 API。新舊 API 目前都還能使用。你在網路上找到的大多數文件仍使用舊版 API，而且可能已經嚴重過時。
@end quotation
@end cartouche


@subsubheading 也參考



@itemize *

@item 

@table @asis

@item TkDocs@footnote{https://tkdocs.com/}

關於使用 Tkinter 建立使用者介面的詳盡教學。內容解釋了關鍵概念，並使用現代 API 來說明建議的方法。
@end table

@item 

@table @asis

@item Tkinter 8.5 reference: a GUI for Python@footnote{https://www.tkdocs.com/shipman/}

Tkinter 8.5 的參考文件，詳細說明了可用的類別、方法和選項。
@end table
@end itemize

Tcl/Tk 相關資源：


@itemize *

@item 

@table @asis

@item Tk 指令@footnote{https://www.tcl.tk/man/tcl8.6/TkCmd/contents.htm}

Tkinter 所使用的每個底層 Tcl/Tk 指令的綜合參考資料。
@end table

@item 

@table @asis

@item Tcl/Tk 首頁@footnote{https://www.tcl.tk}

額外的文件，以及連至 Tcl/Tk 核心開發的連結。
@end table
@end itemize

書籍：


@itemize *

@item 

@table @asis

@item Modern Tkinter for Busy Python Developers@footnote{https://tkdocs.com/book.html}

由 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}

由 Alan D. Moore 所著。（ISBN 978-1788835886）
@end table

@item 

@table @asis

@item Programming Python@footnote{https://learning-python.com/about-pp4e.html}

由 Mark Lutz 所著；對 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}

由 Tcl/Tk 發明者 John Ousterhout 與 Ken Jones 所著；不包含 Tkinter。（ISBN 978-0321336330）
@end table
@end itemize


@menu
* 架構:: 
* Tkinter 模組:: 
* Tkinter 應急指南:: 
* 執行緒模型:: 
* 實用參考:: 
* 檔案處理常式:: 

@end menu

@node 架構,Tkinter 模組,,tkinter --- Tcl/Tk 的 Python 介面
@anchor{library/tkinter architecture}@anchor{41a0}
@subsubsection 架構


Tcl/Tk 並非單一函式庫，而是由幾個不同的模組所組成，每個模組都有獨立的功能和官方文件。Python 的二進位發行版也隨附了一個附加模組。


@table @asis

@item Tcl

Tcl 是一個動態直譯的程式語言，就像 Python 一樣。雖然它可以作為通用程式語言獨立使用，但它最常被嵌入到 C 應用程式中，作為腳本引擎或 Tk 工具集的介面。Tcl 函式庫有一個 C 介面，可用於建立和管理一個或多個 Tcl 直譯器的實例，在這些實例中執行 Tcl 指令和腳本，並新增以 Tcl 或 C 實作的自訂指令。每個直譯器都有一個事件佇列，並有設施可以向其傳送事件並加以處理。與 Python 不同，Tcl 的執行模型是圍繞著協同多工（cooperative multitasking）設計的，而 Tkinter 則彌合了這種差異（詳情請參閱 @ref{41a1,,Threading model}）。

@item Tk

Tk 是一個以 C 實作的 Tcl 套件@footnote{https://wiki.tcl-lang.org/37432}，它新增了自訂指令來建立和操作 GUI 元件。每個 @ref{1903,,Tk} 物件都嵌入了自己載入 Tk 的 Tcl 直譯器實例。Tk 的元件非常可自訂，但代價是外觀較為過時。Tk 使用 Tcl 的事件佇列來產生和處理 GUI 事件。

@item Ttk

主題式 Tk（Ttk）是較新的一族 Tk 元件，相較於許多傳統的 Tk 元件，它在不同平台上提供了更好的外觀。從 Tk 8.5 版開始，Ttk 作為 Tk 的一部分發行。Python 的繫結（bindings）則在一個獨立的模組 @ref{ff,,tkinter.ttk} 中提供。
@end table

在內部，Tk 和 Ttk 使用底層作業系統的設施，即 Unix/X11 上的 Xlib、macOS 上的 Cocoa、Windows 上的 GDI。

當你的 Python 應用程式使用 Tkinter 中的類別（例如，建立一個元件）時，@ref{f6,,tkinter} 模組會先組合一個 Tcl/Tk 指令字串。它將該 Tcl 指令字串傳遞給一個內部的 @ref{3,,_tkinter} 二進位模組，後者再呼叫 Tcl 直譯器來對其進行計算。Tcl 直譯器接著會呼叫 Tk 和/或 Ttk 套件，而這些套件又會再呼叫 Xlib、Cocoa 或 GDI。

@node Tkinter 模組,Tkinter 應急指南,架構,tkinter --- Tcl/Tk 的 Python 介面
@anchor{library/tkinter tkinter-modules}@anchor{41a2}
@subsubsection Tkinter 模組


對 Tkinter 的支援分散在數個模組中。大多數應用程式將需要主要的 @ref{f6,,tkinter} 模組，以及 @ref{ff,,tkinter.ttk} 模組，後者提供了現代主題式元件集和 API：

@example
from tkinter import *
from tkinter import ttk
@end example

@geindex Tk (tkinter 中的類別)
@anchor{library/tkinter tkinter Tk}@anchor{1903}
@deffn {類別} tkinter.Tk (screenName=None, baseName=None, className='Tk', useTk=True, sync=False, use=None)

建構一個頂層 Tk 元件，它通常是應用程式的主視窗，並為此元件初始化一個 Tcl 直譯器。每個實例都有其自己關聯的 Tcl 直譯器。

@ref{1903,,Tk} 類別通常使用所有預設值來實例化。然而，目前可辨識下列關鍵字引數：


@table @asis

@item `screenName'

當給定（作為字串）時，設定 
@geindex DISPLAY
@geindex 環境變數; DISPLAY
@code{DISPLAY} 環境變數。（僅限 X11）

@item `baseName'

設定檔的名稱。預設情況下，`baseName' 是從程式名稱（@code{sys.argv[0]}）衍生而來。

@item `className'

元件類別的名稱。用作設定檔，也用作呼叫 Tcl 時的名稱（`interp' 中的 `argv0'）。

@item `useTk'

若為 @code{True}，則初始化 Tk 子系統。@ref{41a3,,tkinter.Tcl()} 函式會將此設定為 @code{False}。

@item `sync'

若為 @code{True}，則同步執行所有 X 伺服器指令，以便立即回報錯誤。可用於偵錯。（僅限 X11）

@item `use'

指定要嵌入應用程式的視窗 `id'，而不是將其建立為獨立的頂層視窗。`id' 必須以與頂層元件的 -use 選項值相同的方式指定（也就是說，其形式類似 @code{winfo_id()} 回傳的形式）。

請注意，在某些平台上，只有當 `id' 指向一個已啟用 -container 選項的 Tk 框架或頂層視窗時，此功能才能正常運作。
@end table

@ref{1903,,Tk} 會讀取名為 @code{.`className'.tcl} 和 @code{.`baseName'.tcl} 的設定檔，並在 Tcl 直譯器中進行直譯，並對 @code{.`className'.py} 和 @code{.`baseName'.py} 的內容呼叫 @ref{49d,,exec()}。設定檔的路徑是 
@geindex HOME
@geindex 環境變數; HOME
@code{HOME} 環境變數，如果未定義，則是 @ref{2b09,,os.curdir}。

@geindex tk (tkinter.Tk 的屬性)
@anchor{library/tkinter tkinter Tk tk}@anchor{41a4}
@deffn {屬性} tk

透過實例化 @ref{1903,,Tk} 建立的 Tk 應用程式物件。這提供了對 Tcl 直譯器的存取。每個附加到同一個 @ref{1903,,Tk} 實例的元件，其 @ref{41a4,,tk} 屬性都具有相同的值。
@end deffn

@geindex master (tkinter.Tk 的屬性)
@anchor{library/tkinter tkinter Tk master}@anchor{41a5}
@deffn {屬性} master

包含此元件的元件物件。對於 @ref{1903,,Tk}，`master' 是 @ref{87e,,None}，因為它是主視窗。`master' 和 `parent' 這兩個術語很相似，有時會作為引數名稱互換使用；然而，呼叫 @code{winfo_parent()} 會回傳元件名稱的字串，而 @ref{41a5,,master} 則回傳物件。`parent'/`child' 反映了樹狀關係，而 `master'/`slave' 反映了容器結構。
@end deffn

@geindex children (tkinter.Tk 的屬性)
@anchor{library/tkinter tkinter Tk children}@anchor{41a6}
@deffn {屬性} children

此元件的直接子代，形式為一個 @ref{183,,dict}，其中鍵為子元件的名稱，值為子實例物件。
@end deffn
@end deffn

@geindex Tcl() (於 tkinter 模組中)
@anchor{library/tkinter tkinter Tcl}@anchor{41a3}
@deffn {函式} tkinter.Tcl (screenName=None, baseName=None, className='Tk', useTk=False)

@ref{41a3,,Tcl()} 函式是一個工廠函式，它建立的物件與 @ref{1903,,Tk} 類別建立的物件非常相似，只是它不會初始化 Tk 子系統。這在驅動 Tcl 直譯器時最為有用，尤其是在不希望建立額外頂層視窗的環境中，或者在無法建立的環境中（例如沒有 X 伺服器的 Unix/Linux 系統）。由 @ref{41a3,,Tcl()} 物件建立的物件可以透過呼叫其 @code{loadtk()} 方法來建立一個頂層視窗（並初始化 Tk 子系統）。
@end deffn

提供 Tk 支援的模組包括：


@table @asis

@item @ref{f6,,tkinter}

主要的 Tkinter 模組。

@item @ref{f7,,tkinter.colorchooser}

讓使用者選擇顏色的對話方塊。

@item @ref{f8,,tkinter.commondialog}

此處列出的其他模組中定義的對話方塊的基底類別。

@item @ref{fa,,tkinter.filedialog}

讓使用者指定要開啟或儲存的檔案的通用對話方塊。

@item @ref{fb,,tkinter.font}

協助處理字型的工具程式。

@item @ref{fc,,tkinter.messagebox}

存取標準的 Tk 對話方塊。

@item @ref{fd,,tkinter.scrolledtext}

內建垂直捲軸的文字元件。

@item @ref{fe,,tkinter.simpledialog}

基本的對話方塊和便利函式。

@item @ref{ff,,tkinter.ttk}

在 Tk 8.5 中引入的主題式元件集，為主 @ref{f6,,tkinter} 模組中的許多傳統元件提供了現代化的替代方案。
@end table

額外模組：

@geindex module; _tkinter
@anchor{library/tkinter module-_tkinter}@anchor{3}

@table @asis

@item @ref{3,,_tkinter}

一個包含 Tcl/Tk 低階介面的二進位模組。它由主 @ref{f6,,tkinter} 模組自動引入，應用程式開發者不應直接使用它。它通常是一個共享函式庫（或 DLL），但在某些情況下可能會與 Python 直譯器靜態連結。

@item @ref{77,,idlelib}

Python 的整合開發與學習環境（IDLE）。基於 @ref{f6,,tkinter}。

@item @code{tkinter.constants}

在將各種參數傳遞給 Tkinter 呼叫時，可用於替代字串的符號常數。由主 @ref{f6,,tkinter} 模組自動引入。

@item @ref{f9,,tkinter.dnd}

（實驗性）對 @ref{f6,,tkinter} 的拖放支援。當它被 Tk DND 取代時，將會被棄用。

@item @ref{107,,turtle}

在 Tk 視窗中的海龜繪圖。
@end table

@node Tkinter 應急指南,執行緒模型,Tkinter 模組,tkinter --- Tcl/Tk 的 Python 介面
@anchor{library/tkinter tkinter-life-preserver}@anchor{41a7}
@subsubsection Tkinter 應急指南


本節並非旨在成為 Tk 或 Tkinter 的詳盡教學。為此，請參閱前面提到的外部資源之一。相反地，本節提供了一個快速導覽，介紹 Tkinter 應用程式的外觀、識別基礎的 Tk 概念，並解釋 Tkinter 包裝器的結構。

本節的其餘部分將幫助你識別在 Tkinter 應用程式中所需的類別、方法和選項，以及在哪裡可以找到關於它們的更詳細文件，包括在官方的 Tcl/Tk 參考手冊中。

@menu
* 一個 Hello World 程式:: 
* 重要的 Tk 概念:: 
* 了解 Tkinter 如何包裝 Tcl/Tk:: 
* 我該如何...？哪個選項可以...？: 我該如何 ？哪個選項可以 ？. 
* 瀏覽 Tcl/Tk 參考手冊:: 

@end menu

@node 一個 Hello World 程式,重要的 Tk 概念,,Tkinter 應急指南
@anchor{library/tkinter a-hello-world-program}@anchor{41a8}
@subsubsection 一個 Hello World 程式


我們將從一個 Tkinter 的 "Hello World" 應用程式開始。這不是我們能寫出的最小程式，但足以說明一些你需要知道的關鍵概念。

@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

在引入之後，下一行建立了一個 @code{Tk} 類別的實例，它會初始化 Tk 並建立其關聯的 Tcl 直譯器。它還會建立一個頂層視窗，稱為根視窗，作為應用程式的主視窗。

接下來的一行建立了一個框架元件，在本例中，它將包含我們接下來要建立的一個標籤和一個按鈕。該框架被放置在根視窗內。

下一行建立了一個包含靜態文字字串的標籤元件。@code{grid()} 方法用於指定標籤在其包含的框架元件中的相對佈局（位置），類似於 HTML 中表格的運作方式。

然後建立一個按鈕元件，並放置在標籤的右側。當按下時，它將呼叫根視窗的 @code{destroy()} 方法。

最後，@code{mainloop()} 方法將所有內容顯示在螢幕上，並回應使用者輸入，直到程式終止。

@node 重要的 Tk 概念,了解 Tkinter 如何包裝 Tcl/Tk,一個 Hello World 程式,Tkinter 應急指南
@anchor{library/tkinter important-tk-concepts}@anchor{41a9}
@subsubsection 重要的 Tk 概念


即使是這個簡單的程式也說明了以下關鍵的 Tk 概念：


@table @asis

@item 元件（widgets）

一個 Tkinter 使用者介面是由個別的`元件'所組成。每個元件都表示為一個 Python 物件，從 @code{ttk.Frame}、@code{ttk.Label} 和 @code{ttk.Button} 等類別實例化而來。

@item 元件階層（widget hierarchy）

元件被安排在一個`階層'中。標籤和按鈕被包含在一個框架內，而框架又被包含在根視窗內。在建立每個`子'元件時，其`父'元件會作為第一個引數傳遞給元件的建構函式。

@item 設定選項（configuration options）

元件具有`設定選項'，可以修改其外觀和行為，例如在標籤或按鈕中顯示的文字。不同類別的元件會有不同的選項集。

@item 佈局管理（geometry management）

元件在建立時不會自動新增到使用者介面中。像 @code{grid} 這樣的`佈局管理器'（geometry manager）會控制它們在使用者介面中的放置位置。

@item 事件迴圈（event loop）

Tkinter 只有在主動執行`事件迴圈'時，才會對使用者輸入、程式的變更，甚至螢幕刷新做出反應。如果你的程式沒有執行事件迴圈，你的使用者介面將不會更新。
@end table

@node 了解 Tkinter 如何包裝 Tcl/Tk,我該如何 ？哪個選項可以 ？,重要的 Tk 概念,Tkinter 應急指南
@anchor{library/tkinter understanding-how-tkinter-wraps-tcl-tk}@anchor{41aa}
@subsubsection 了解 Tkinter 如何包裝 Tcl/Tk


當你的應用程式使用 Tkinter 的類別和方法時，Tkinter 內部正在組合代表 Tcl/Tk 指令的字串，並在附加到你應用程式 @code{Tk} 實例的 Tcl 直譯器中執行這些指令。

無論是試圖瀏覽參考文件、尋找正確的方法或選項、改寫一些現有程式碼，還是偵錯你的 Tkinter 應用程式，在某些時候，了解那些底層 Tcl/Tk 指令的樣貌會很有幫助。

為了說明，以下是上面 Tkinter 腳本主要部分的 Tcl/Tk 對等程式碼。

@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 的語法類似於許多 shell 語言，第一個字是要執行的指令，後面跟著該指令的引數，以空格分隔。在不深入太多細節的情況下，請注意以下幾點：


@itemize *

@item 
用於建立元件的指令（如 @code{ttk::frame}）對應於 Tkinter 中的元件類別。

@item 
Tcl 元件選項（如 @code{-text}）對應於 Tkinter 中的關鍵字引數。

@item 
在 Tcl 中，元件是透過`路徑名稱'（如 @code{.frm.btn}）來參照，而 Tkinter 不使用名稱，而是使用物件參照。

@item 
元件在元件階層中的位置被編碼在其（階層式）路徑名稱中，該路徑名稱使用 @code{.}（點）作為路徑分隔符。根視窗的路徑名稱就是 @code{.}（點）。在 Tkinter 中，階層不是由路徑名稱定義的，而是在建立每個子元件時指定父元件來定義的。

@item 
在 Tcl 中實作為獨立`指令'的操作（如 @code{grid} 或 @code{destroy}），在 Tkinter 中則表示為元件物件上的`方法'。正如你稍後會看到的，在其他時候，Tcl 使用的看起來像是對元件物件的方法呼叫，這更接近 Tkinter 中的用法。
@end itemize

@node 我該如何 ？哪個選項可以 ？,瀏覽 Tcl/Tk 參考手冊,了解 Tkinter 如何包裝 Tcl/Tk,Tkinter 應急指南
@anchor{library/tkinter how-do-i-what-option-does}@anchor{41ab}
@subsubsection 我該如何...？哪個選項可以...？


如果你不確定如何在 Tkinter 中做某件事，並且無法立即在你正在使用的教學或參考文件中找到它，這裡有一些可能有幫助的策略。

首先，請記住，個別元件的運作細節可能會因 Tkinter 和 Tcl/Tk 的不同版本而異。如果你正在搜尋文件，請確保它對應於你系統上安裝的 Python 和 Tcl/Tk 版本。

在搜尋如何使用 API 時，知道你正在使用的類別、選項或方法的確切名稱會很有幫助。自省（Introspection），無論是在互動式 Python shell 中還是使用 @ref{1170,,print()}，都可以幫助你識別所需內容。

要找出任何元件上有哪些可用的設定選項，請呼叫其 @code{configure()} 方法，該方法會回傳一個字典，其中包含有關每個物件的各種資訊，包括其預設值和目前值。使用 @code{keys()} 僅取得每個選項的名稱。

@example
btn = ttk.Button(frm, ...)
print(btn.configure().keys())
@end example

由於大多數元件有許多共通的設定選項，找出特定於某個元件類別的選項會很有用。將選項串列與像框架這樣較簡單的元件的選項串列進行比較，是做到這一點的一種方法。

@example
print(set(btn.configure().keys()) - set(frm.configure().keys()))
@end example

同樣地，你可以使用標準的 @ref{83d,,dir()} 函式來尋找元件物件可用的方法。如果你試一下，你會看到有超過 200 個常見的元件方法，所以再次強調，識別特定於某個元件類別的方法是很有幫助的。

@example
print(dir(btn))
print(set(dir(btn)) - set(dir(frm)))
@end example

@node 瀏覽 Tcl/Tk 參考手冊,,我該如何 ？哪個選項可以 ？,Tkinter 應急指南
@anchor{library/tkinter navigating-the-tcl-tk-reference-manual}@anchor{41ac}
@subsubsection 瀏覽 Tcl/Tk 參考手冊


如前所述，官方的 Tk 指令@footnote{https://www.tcl.tk/man/tcl8.6/TkCmd/contents.htm} 參考手冊（man pages）通常是對元件上特定操作作用的最準確描述。即使你知道所需選項或方法的名稱，你可能仍有幾個地方需要查看。

雖然 Tkinter 中的所有操作都實作為對元件物件的方法呼叫，但你已經看到許多 Tcl/Tk 操作顯示為指令，這些指令將元件路徑名稱作為其第一個參數，後面跟著可選的參數，例如：

@example
destroy .
grid .frm.btn -column 0 -row 0
@end example

然而，其他的看起來更像是對元件物件呼叫的方法（事實上，當你在 Tcl/Tk 中建立一個元件時，它會建立一個以元件路徑名稱為名的 Tcl 指令，該指令的第一個參數是要呼叫的方法名稱）。

@example
.frm.btn invoke
.frm.lbl configure -text "Goodbye"
@end example

在官方的 Tcl/Tk 參考文件中，你會在特定元件的 man page 上找到大多數看起來像方法呼叫的操作（例如，你可以在 ttk::button@footnote{https://www.tcl.tk/man/tcl8.6/TkCmd/ttk_button.htm} man page 上找到 @code{invoke()} 方法），而將元件作為參數的函式通常有自己的 man page（例如 grid@footnote{https://www.tcl.tk/man/tcl8.6/TkCmd/grid.htm}）。

你可以在 options@footnote{https://www.tcl.tk/man/tcl8.6/TkCmd/options.htm} 或 ttk::widget@footnote{https://www.tcl.tk/man/tcl8.6/TkCmd/ttk_widget.htm} man page 中找到許多常見的選項和方法，而其他的則在特定元件類別的 man page 中找到。

你還會發現許多 Tkinter 方法有複合名稱，例如 @code{winfo_x()}、@code{winfo_height()}、@code{winfo_viewable()}。你可以在 winfo@footnote{https://www.tcl.tk/man/tcl8.6/TkCmd/winfo.htm} man page 中找到所有這些文件的說明。

@cartouche
@quotation 備註 
有點令人困惑的是，所有 Tkinter 元件上還有一些方法，它們實際上並不是對該元件進行操作，而是在全域範圍內操作，獨立於任何元件。例如存取剪貼簿或系統鈴聲的方法。（它們恰好被實作為所有 Tkinter 元件都繼承的基底 @code{Widget} 類別中的方法）。
@end quotation
@end cartouche

@node 執行緒模型,實用參考,Tkinter 應急指南,tkinter --- Tcl/Tk 的 Python 介面
@anchor{library/tkinter threading-model}@anchor{41a1}
@subsubsection 執行緒模型


Python 和 Tcl/Tk 有非常不同的執行緒模型，@ref{f6,,tkinter} 試圖彌合這種差異。如果你使用執行緒，你可能需要意識到這一點。

一個 Python 直譯器可能有多個與之關聯的執行緒。在 Tcl 中，可以建立多個執行緒，但每個執行緒都有一個獨立的 Tcl 直譯器實例與之關聯。執行緒也可以建立多個直譯器實例，但每個直譯器實例只能由建立它的那個執行緒使用。

由 @ref{f6,,tkinter} 建立的每個 @code{Tk} 物件都包含一個 Tcl 直譯器。它還會追蹤是哪個執行緒建立了該直譯器。可以從任何 Python 執行緒呼叫 @ref{f6,,tkinter}。在內部，如果呼叫來自建立 @code{Tk} 物件的執行緒以外的執行緒，則會將一個事件發佈到直譯器的事件佇列中，執行後，結果會回傳給呼叫的 Python 執行緒。

Tcl/Tk 應用程式通常是事件驅動的，這意味著在初始化之後，直譯器會執行一個事件迴圈（即 @code{Tk.mainloop()}）並回應事件。因為它是單執行緒的，事件處理常式必須快速回應，否則它們會阻塞其他事件的處理。為避免這種情況，任何長時間執行的計算都不應在事件處理常式中執行，而是使用計時器將其分解成更小的部分，或在另一個執行緒中執行。這與許多 GUI 工具集不同，在那些工具集中，GUI 在一個與所有應用程式碼（包括事件處理常式）完全分離的執行緒中執行。

如果 Tcl 直譯器沒有在執行事件迴圈和處理事件，那麼從執行 Tcl 直譯器的執行緒以外的執行緒發出的任何 @ref{f6,,tkinter} 呼叫都將失敗。

存在一些特殊情況：


@itemize *

@item 
Tcl/Tk 函式庫可以被建構成不具備執行緒感知能力。在這種情況下，@ref{f6,,tkinter} 會從原始的 Python 執行緒呼叫該函式庫，即使這與建立 Tcl 直譯器的執行緒不同。一個全域鎖確保一次只發生一個呼叫。

@item 
雖然 @ref{f6,,tkinter} 允許你建立多個 @code{Tk} 物件的實例（每個都有自己的直譯器），但屬於同一個執行緒的所有直譯器共享一個共同的事件佇列，這很快就會變得混亂。在實務上，不要一次建立多個 @code{Tk} 的實例。否則，最好在不同的執行緒中建立它們，並確保你正在執行一個具備執行緒感知能力的 Tcl/Tk 建構版本。

@item 
阻塞事件處理常式並不是防止 Tcl 直譯器重新進入事件迴圈的唯一方法。甚至可以執行多個巢狀的事件迴圈或完全放棄事件迴圈。如果你在事件或執行緒方面做任何複雜的操作，請注意這些可能性。

@item 
目前有少數幾個 @ref{f6,,tkinter} 函式只有在從建立 Tcl 直譯器的執行緒中呼叫時才能正常運作。
@end itemize

@node 實用參考,檔案處理常式,執行緒模型,tkinter --- Tcl/Tk 的 Python 介面
@anchor{library/tkinter handy-reference}@anchor{41ad}
@subsubsection 實用參考


@menu
* 設定選項: 設定選項<2>. 
* Packer 佈局管理器:: 
* Packer 選項:: 
* 耦合元件變數:: 
* 視窗管理器:: 
* Tk 選項資料型別:: 
* 繫結與事件:: 
* index 參數:: 
* 圖片:: 

@end menu

@node 設定選項<2>,Packer 佈局管理器,,實用參考
@anchor{library/tkinter setting-options}@anchor{41ae}@anchor{library/tkinter tkinter-setting-options}@anchor{41af}
@subsubsection 設定選項


選項控制著諸如元件的顏色和邊框寬度等。選項可以透過三種方式設定：


@table @asis

@item 在物件建立時，使用關鍵字引數

@example
fred = Button(self, fg="red", bg="blue")
@end example

@item 在物件建立後，將選項名稱視為字典索引

@example
fred["fg"] = "red"
fred["bg"] = "blue"
@end example

@item 在物件建立後，使用 config() 方法更新多個屬性

@example
fred.config(fg="red", bg="blue")
@end example
@end table

有關給定選項及其行為的完整解釋，請參閱相關元件的 Tk man pages。

請注意，man pages 為每個元件列出了「標準選項」和「元件特定選項」。前者是許多元件共有的選項串列，後者是該特定元件特有的選項。標準選項記錄在 @code{options(3)@footnote{https://manpages.debian.org/options(3)}} man page 中。

本文件中未對標準選項和元件特定選項進行區分。某些選項不適用於某些類型的元件。給定元件是否回應特定選項取決於該元件的類別；按鈕有 @code{command} 選項，標籤則沒有。

給定元件支援的選項列在該元件的 man page 中，或者可以在 runtime 透過不帶引數呼叫 @code{config()} 方法，或對該元件呼叫 @code{keys()} 方法來查詢。這些呼叫的回傳值是一個字典，其鍵是選項名稱的字串（例如 @code{'relief'}），其值是 5-tuples。

某些選項，如 @code{bg}，是具有長名稱的常見選項的同義詞（@code{bg} 是 "background" 的簡寫）。將簡寫選項的名稱傳遞給 @code{config()} 方法將回傳一個 2-tuple，而不是 5-tuple。回傳的 2-tuple 將包含同義詞的名稱和「真實」選項（例如 @code{('bg', 'background')}）。


@multitable {xxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxx} 
@headitem

索引

@tab

含義

@tab

範例

@item

0

@tab

選項名稱

@tab

@code{'relief'}

@item

1

@tab

用於資料庫查詢的選項名稱

@tab

@code{'relief'}

@item

2

@tab

用於資料庫查詢的選項類別

@tab

@code{'Relief'}

@item

3

@tab

預設值

@tab

@code{'raised'}

@item

4

@tab

目前值

@tab

@code{'groove'}

@end multitable


範例：

@example
>>> print(fred.config())
@{'relief': ('relief', 'relief', 'Relief', 'raised', 'groove')@}
@end example

當然，印出的字典將包含所有可用的選項及其值。這僅作為一個範例。

@node Packer 佈局管理器,Packer 選項,設定選項<2>,實用參考
@anchor{library/tkinter the-packer}@anchor{41b0}
@subsubsection Packer 佈局管理器


@geindex packing（元件）

packer 是 Tk 的佈局管理（geometry manager）機制之一。佈局管理器（geometry manager）用於指定元件在其容器（它們共同的 `master'）內的相對位置。與較為繁瑣的 `placer'（較不常用，我們在此不予介紹）相比，packer 採用定性的關係規範——`上方'、`左方'、`填滿'等——並為你計算出確切的放置座標。

任何 `master' 元件的大小由其內部的「slave 元件」的大小決定。packer 用於控制 slave 元件在被 packed 的 master 內部出現的位置。你可以將元件 pack 到框架中，再將框架 pack 到其他框架中，以達到你想要的佈局。此外，一旦 packed，佈局會動態調整以適應設定的增量變更。

請注意，元件在透過佈局管理器（geometry manager）指定其佈局（geometry）之前是不會出現的。一個常見的早期錯誤是忽略了佈局（geometry）指定，然後在元件被建立但沒有任何東西出現時感到驚訝。一個元件只有在例如 packer 的 @code{pack()} 方法被應用於其上之後才會出現。

pack() 方法可以與關鍵字選項/值對一起呼叫，以控制元件在其容器中出現的位置，以及當主應用程式視窗調整大小時它的行為方式。以下是一些範例：

@example
fred.pack()                     # 預設為 side = "top"
fred.pack(side="left")
fred.pack(expand=1)
@end example

@node Packer 選項,耦合元件變數,Packer 佈局管理器,實用參考
@anchor{library/tkinter packer-options}@anchor{41b1}
@subsubsection Packer 選項


有關 packer 及其可接受選項的更詳盡資訊，請參閱 man pages 和 John Ousterhout 書中的第 183 頁。


@table @asis

@item anchor

錨點類型。表示 packer 將每個 slave 放置在其區域中的位置。

@item expand

布林值，@code{0} 或 @code{1}。

@item fill

合法值：@code{'x'}、@code{'y'}、@code{'both'}、@code{'none'}。

@item ipadx 和 ipady

一個距離——指定 slave 元件每側的內部填充。

@item padx 和 pady

一個距離——指定 slave 元件每側的外部填充。

@item side

合法值為：@code{'left'}、@code{'right'}、@code{'top'}、@code{'bottom'}。
@end table

@node 耦合元件變數,視窗管理器,Packer 選項,實用參考
@anchor{library/tkinter coupling-widget-variables}@anchor{41b2}
@subsubsection 耦合元件變數


某些元件（如文字輸入元件）的當前值設定可以透過使用特殊選項直接連接到應用程式變數。這些選項是 @code{variable}、@code{textvariable}、@code{onvalue}、@code{offvalue} 和 @code{value}。這種連接是雙向的：如果變數因任何原因發生變化，與之連接的元件將會更新以反映新值。

不幸的是，在 @ref{f6,,tkinter} 的目前實作中，無法透過 @code{variable} 或 @code{textvariable} 選項將任意的 Python 變數傳遞給元件。唯一適用此功能的變數類型是從 @ref{f6,,tkinter} 中定義的一個名為 Variable 的類別繼承的子類別變數。

已經定義了許多有用的 Variable 子類別：@code{StringVar}、@code{IntVar}、@code{DoubleVar} 和 @code{BooleanVar}。要讀取此類變數的目前值，請對其呼叫 @code{get()} 方法，要更改其值，則呼叫 @code{set()} 方法。如果你遵循此協定，元件將始終追蹤變數的值，無需你進一步干預。

舉例來說：

@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()

        # 建立應用程式變數。
        self.contents = tk.StringVar()
        # 將其設定為某個值。
        self.contents.set("this is a variable")
        # 告訴 entry 元件監視此變數。
        self.entrythingy["textvariable"] = self.contents

        # 為使用者按下 return 鍵定義一個回呼。
        # 它會印出變數的目前值。
        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 視窗管理器,Tk 選項資料型別,耦合元件變數,實用參考
@anchor{library/tkinter the-window-manager}@anchor{41b3}
@subsubsection 視窗管理器


@geindex 視窗管理器（元件）

在 Tk 中，有一個工具指令 @code{wm}，用於與視窗管理器互動。@code{wm} 指令的選項允許你控制標題、位置、圖示點陣圖等。在 @ref{f6,,tkinter} 中，這些指令已實作為 @code{Wm} 類別上的方法。頂層元件是 @code{Wm} 類別的子類別，因此可以直接呼叫 @code{Wm} 方法。

要取得包含給定元件的頂層視窗，你通常可以直接參照該元件的 master。當然，如果該元件被 packed 在一個框架內，master 將不代表一個頂層視窗。要取得包含任意元件的頂層視窗，你可以呼叫 @code{_root()} 方法。此方法以底線開頭，表示此函式是實作的一部分，而不是 Tk 功能的介面。

以下是一些常見用法範例：

@example
import tkinter as tk

class App(tk.Frame):
    def __init__(self, master=None):
        super().__init__(master)
        self.pack()

# 建立應用程式
myapp = App()

#
# 以下是對視窗管理器類別的方法呼叫
#
myapp.master.title("My Do-Nothing Application")
myapp.master.maxsize(1000, 400)

# 啟動程式
myapp.mainloop()
@end example

@node Tk 選項資料型別,繫結與事件,視窗管理器,實用參考
@anchor{library/tkinter tk-option-data-types}@anchor{41b4}
@subsubsection Tk 選項資料型別


@geindex Tk 選項資料型別


@table @asis

@item anchor

合法值為羅盤方位點：@code{"n"}、@code{"ne"}、@code{"e"}、@code{"se"}、@code{"s"}、@code{"sw"}、@code{"w"}、@code{"nw"}，以及 @code{"center"}。

@item bitmap

有八個內建的、命名的點陣圖：@code{'error'}、@code{'gray25'}、@code{'gray50'}、@code{'hourglass'}、@code{'info'}、@code{'questhead'}、@code{'question'}、@code{'warning'}。要指定一個 X 點陣圖檔名，請給出檔案的完整路徑，並在前面加上一個 @code{@@}，例如 @code{"@@/usr/contrib/bitmap/gumby.bit"}。

@item boolean

你可以傳遞整數 0 或 1，或字串 @code{"yes"} 或 @code{"no"}。

@item callback

這是任何不帶引數的 Python 函式。例如：

@example
def print_it():
    print("hi there")
fred["command"] = print_it
@end example

@item color

顏色可以以 rgb.txt 檔案中的 X 顏色名稱給出，或以表示 RGB 值的字串給出，範圍可以是 4 位元：@code{"#RGB"}、8 位元：@code{"#RRGGBB"}、12 位元：@code{"#RRRGGGBBB"} 或 16 位元：@code{"#RRRRGGGGBBBB"}，其中 R、G、B 在此代表任何合法的十六進位數字。詳情請參閱 Ousterhout 書中的第 160 頁。

@item cursor

可以使用 @code{cursorfont.h} 中的標準 X 游標名稱，無需 @code{XC_} 前綴。例如，要取得手形游標（@code{XC_hand2}），請使用字串 @code{"hand2"}。你也可以指定自己的點陣圖和遮罩檔案。請參閱 Ousterhout 書中的第 179 頁。

@item distance

螢幕距離可以以像素或絕對距離指定。像素以數字給出，絕對距離以字串給出，尾隨字元表示單位：@code{c} 代表公分，@code{i} 代表英寸，@code{m} 代表毫米，@code{p} 代表印刷的點。例如，3.5 英寸表示為 @code{"3.5i"}。

@item font

Tk 使用串列字型名稱格式，例如 @code{@{courier 10 bold@}}。帶有正數的字型大小以點為單位；帶有負數的大小以像素為單位。

@item geometry

這是一個 @code{widthxheight} 形式的字串，其中 width 和 height 對於大多數元件是以像素為單位（對於顯示文字的元件則以字元為單位）。例如：@code{fred["geometry"] = "200x100"}。

@item justify

合法值為字串：@code{"left"}、@code{"center"} 和 @code{"right"}。

@item region

這是一個由四個以空格分隔的元素組成的字串，每個元素都是一個合法的距離（見上文）。例如：@code{"2 3 4 5"}、@code{"3i 2i 4.5i 2i"} 和 @code{"3c 2c 4c 10.43c"} 都是合法的區域。

@item relief

決定元件的邊框樣式。合法值為：@code{"raised"}、@code{"sunken"}、@code{"flat"}、@code{"groove"} 和 @code{"ridge"}。

@item scrollcommand

這幾乎總是某個捲軸元件的 @code{set()} 方法，但也可以是任何接受單一引數的元件方法。

@item wrap

必須是以下之一：@code{"none"}、@code{"char"} 或 @code{"word"}。
@end table

@node 繫結與事件,index 參數,Tk 選項資料型別,實用參考
@anchor{library/tkinter bindings-and-events}@anchor{41b5}@anchor{library/tkinter id2}@anchor{41b6}
@subsubsection 繫結與事件


@geindex bind（元件）
@geindex 事件（元件）

來自元件指令的 bind 方法允許你監視某些事件，並在該事件類型發生時觸發一個回呼函式。bind 方法的形式是：

@example
def bind(self, sequence, func, add='@w{'}):
@end example

其中：


@table @asis

@item sequence

是一個表示目標事件類型的字串。（詳情請參閱 @code{bind(3tk)@footnote{https://manpages.debian.org/bind(3tk)}} man page，以及 John Ousterhout 的書 @cite{Tcl and the Tk Toolkit (2nd edition)} 的第 201 頁）。

@item func

是一個 Python 函式，接受一個引數，在事件發生時被呼叫。一個 Event 實例將作為引數傳遞。（以這種方式部署的函式通常稱為`回呼'。）

@item add

是可選的，可以是 @code{'@w{'}} 或 @code{'+'}。傳遞一個空字串表示此繫結將取代與此事件關聯的任何其他繫結。傳遞一個 @code{'+'} 意味著此函式將被新增到繫結到此事件類型的函式串列中。
@end table

舉例來說：

@example
def turn_red(self, event):
    event.widget["activeforeground"] = "red"

self.button.bind("<Enter>", self.turn_red)
@end example

請注意在 @code{turn_red()} 回呼中如何存取事件的 widget 欄位。此欄位包含捕獲 X 事件的元件。下表列出了你可以存取的其他事件欄位，以及它們在 Tk 中的表示方式，這在參閱 Tk man pages 時可能很有用。


@multitable {xxxxxx} {xxxxxxxxxxxxxxxxxxxxxxx} {xxxxxx} {xxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Tk

@tab

Tkinter 事件欄位

@tab

Tk

@tab

Tkinter 事件欄位

@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 index 參數,圖片,繫結與事件,實用參考
@anchor{library/tkinter the-index-parameter}@anchor{41b7}
@subsubsection index 參數


許多元件需要傳遞 "index" 參數。這些參數用於指向 Text 元件中的特定位置、Entry 元件中的特定字元，或 Menu 元件中的特定選單項目。


@table @asis

@item Entry 元件索引（index、view index 等）

Entry 元件具有參照所顯示文字中字元位置的選項。你可以使用這些 @ref{f6,,tkinter} 函式來存取文字元件中的這些特殊點：

@item Text 元件索引

Text 元件的索引表示法非常豐富，在 Tk man pages 中有最好的描述。

@item 選單索引（menu.invoke()、menu.entryconfig() 等）

選單的某些選項和方法會操作特定的選單項目。每當選項或參數需要選單索引時，你可以傳入：


@itemize *

@item 
一個整數，它參照元件中項目的數字位置，從頂部開始計數，從 0 開始；

@item 
字串 @code{"active"}，它參照目前在游標下的選單位置；

@item 
字串 @code{"last"}，它參照最後一個選單項目；

@item 
一個以 @code{@@} 為前綴的整數，如 @code{@@6}，其中該整數被解釋為選單座標系統中的 y 像素座標；

@item 
字串 @code{"none"}，表示完全沒有選單項目，最常用於 menu.activate() 以停用所有項目，最後，

@item 
一個文字字串，它會與從選單頂部掃描到底部的選單項目標籤進行模式匹配。請注意，此索引類型在所有其他類型之後考慮，這意味著標籤為 @code{last}、@code{active} 或 @code{none} 的選單項目的匹配可能會被解釋為上述的字面值。
@end itemize
@end table

@node 圖片,,index 參數,實用參考
@anchor{library/tkinter images}@anchor{41b8}
@subsubsection 圖片


可以透過 @code{tkinter.Image} 的相應子類別來建立不同格式的圖片：


@itemize *

@item 
@code{BitmapImage} 用於 XBM 格式的圖片。

@item 
@code{PhotoImage} 用於 PGM、PPM、GIF 和 PNG 格式的圖片。後者從 Tk 8.6 開始支援。
@end itemize

任一類型的圖片都是透過 @code{file} 或 @code{data} 選項建立的（也有其他選項可用）。


在 3.13 版的變更: 新增了 @code{PhotoImage} 方法 @code{copy_replace()}，用於將一個區域從一個圖片複製到另一個圖片，可能帶有像素縮放和/或子採樣。將 `from_coords' 參數新增到 @code{PhotoImage} 方法 @code{copy()}、@code{zoom()} 和 @code{subsample()}。將 `zoom' 和 `subsample' 參數新增到 @code{PhotoImage} 方法 @code{copy()}。


然後，圖片物件可以在任何支援 @code{image} 選項的元件（例如標籤、按鈕、選單）中使用。在這些情況下，Tk 將不會保留對圖片的參照。當對圖片物件的最後一個 Python 參照被刪除時，圖片資料也會被刪除，Tk 將在使用該圖片的任何地方顯示一個空框。


@subsubheading 也參考


Pillow@footnote{https://python-pillow.org/} 套件新增了對 BMP、JPEG、TIFF 和 WebP 等格式的支援。


@node 檔案處理常式,,實用參考,tkinter --- Tcl/Tk 的 Python 介面
@anchor{library/tkinter file-handlers}@anchor{41b9}@anchor{library/tkinter tkinter-file-handlers}@anchor{41ba}
@subsubsection 檔案處理常式


Tk 允許你註冊和取消註冊一個回呼函式，當檔案描述器上可以進行 I/O 時，該函式將從 Tk 主迴圈中被呼叫。每個檔案描述器只能註冊一個處理常式。範例程式碼：

@example
import tkinter
widget = tkinter.Tk()
mask = tkinter.READABLE | tkinter.WRITABLE
widget.tk.createfilehandler(file, mask, callback)
...
widget.tk.deletefilehandler(file)
@end example

此功能在 Windows 上不可用。

由於你不知道有多少位元組可供讀取，你可能不想使用 @ref{89c,,BufferedIOBase} 或 @ref{89d,,TextIOBase} 的 @ref{1529,,read()} 或 @ref{152a,,readline()} 方法，因為這些方法會堅持讀取預定義數量的位元組。對於 sockets（通訊端），@ref{f9f,,recv()} 或 @ref{fa0,,recvfrom()} 方法可以正常運作；對於其他檔案，請使用原始讀取或 @code{os.read(file.fileno(), maxbytecount)}。

@geindex createfilehandler() (_tkinter.Widget.tk 的方法)
@anchor{library/tkinter tkinter Widget tk createfilehandler}@anchor{41bb}
@deffn {方法} Widget.tk.createfilehandler (file, mask, func)

註冊檔案處理常式回呼函式 `func'。`file' 引數可以是一個具有 @ref{2b7e,,fileno()} 方法的物件（例如檔案或 socket（通訊端）物件），或是一個整數檔案描述器。`mask' 引數是下面三個常數中任意一個的 OR 組合。回呼函式被呼叫的方式如下：

@example
callback(file, mask)
@end example
@end deffn

@geindex deletefilehandler() (_tkinter.Widget.tk 的方法)
@anchor{library/tkinter tkinter Widget tk deletefilehandler}@anchor{41bc}
@deffn {方法} Widget.tk.deletefilehandler (file)

取消註冊檔案處理常式。
@end deffn

@geindex READABLE (於 _tkinter 模組中)
@geindex WRITABLE (於 _tkinter 模組中)
@geindex EXCEPTION (於 _tkinter 模組中)
@anchor{library/tkinter tkinter READABLE}@anchor{41bd}
@deffn {資料} _tkinter.READABLE
@anchor{library/tkinter tkinter WRITABLE}@anchor{41be}
@deffnx {資料} _tkinter.WRITABLE
@anchor{library/tkinter tkinter EXCEPTION}@anchor{41bf}
@deffnx {資料} _tkinter.EXCEPTION

用於 `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)

@node tkinter colorchooser --- 顏色選擇對話框,tkinter font --- Tkinter 字型包裝器,tkinter --- Tcl/Tk 的 Python 介面,以 Tk 打造圖形使用者介面 Graphical User Interfaces
@anchor{library/tkinter colorchooser doc}@anchor{41c0}@anchor{library/tkinter colorchooser module-tkinter colorchooser}@anchor{f7}@anchor{library/tkinter colorchooser tkinter-colorchooser-color-choosing-dialog}@anchor{41c1}@anchor{library/tkinter colorchooser translation-repo}@anchor{41c2}
@subsection @code{tkinter.colorchooser} --- 顏色選擇對話框


@geindex module; tkinter.colorchooser

`原始碼：'Lib/tkinter/colorchooser.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/tkinter/colorchooser.py}


__________________________________________________________________


@ref{f7,,tkinter.colorchooser} 模組提供類別 @ref{41c3,,Chooser} 當作與原生顏色選擇器對話框的介面。@code{Chooser} 實作了一個顏色選擇的互動視窗。類別 @code{Chooser} 繼承了類別 @ref{41c4,,Dialog}。

@geindex Chooser (tkinter.colorchooser 中的類別)
@anchor{library/tkinter colorchooser tkinter colorchooser Chooser}@anchor{41c3}
@deffn {類別} tkinter.colorchooser.Chooser (master=None, **options)
@end deffn

@geindex askcolor() (於 tkinter.colorchooser 模組中)
@anchor{library/tkinter colorchooser tkinter colorchooser askcolor}@anchor{41c5}
@deffn {函式} tkinter.colorchooser.askcolor (color=None, **options)

建立一個顏色選擇對話框。一旦呼叫這個方法便會顯示視窗，等待使用者做出選擇後，回傳選擇的顏色（或者是 @code{None}）給呼叫者。
@end deffn


@subsubheading 也參考



@table @asis

@item @ref{f8,,tkinter.commondialog} 模組

Tkinter 標準對話框模組
@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 字型包裝器,Tkinter 對話框,tkinter colorchooser --- 顏色選擇對話框,以 Tk 打造圖形使用者介面 Graphical User Interfaces
@anchor{library/tkinter font doc}@anchor{41c6}@anchor{library/tkinter font module-tkinter font}@anchor{fb}@anchor{library/tkinter font tkinter-font-tkinter-font-wrapper}@anchor{41c7}@anchor{library/tkinter font translation-repo}@anchor{41c8}
@subsection @code{tkinter.font} --- Tkinter 字型包裝器


@geindex module; tkinter.font

`原始碼：'Lib/tkinter/font.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/tkinter/font.py}


__________________________________________________________________


@ref{fb,,tkinter.font} 模組提供類別 @ref{1bc0,,Font}，可以建立及使用已命名的字型。

不同的字重 (font weights) 以及傾斜 (slant) 是：

@geindex NORMAL (於 tkinter.font 模組中)
@geindex BOLD (於 tkinter.font 模組中)
@geindex ITALIC (於 tkinter.font 模組中)
@geindex ROMAN (於 tkinter.font 模組中)
@anchor{library/tkinter font tkinter font NORMAL}@anchor{41c9}
@deffn {資料} tkinter.font.NORMAL
@anchor{library/tkinter font tkinter font BOLD}@anchor{41ca}
@deffnx {資料} tkinter.font.BOLD
@anchor{library/tkinter font tkinter font ITALIC}@anchor{41cb}
@deffnx {資料} tkinter.font.ITALIC
@anchor{library/tkinter font tkinter font ROMAN}@anchor{41cc}
@deffnx {資料} tkinter.font.ROMAN
@end deffn

@geindex Font (tkinter.font 中的類別)
@anchor{library/tkinter font tkinter font Font}@anchor{1bc0}
@deffn {類別} tkinter.font.Font (root=None, font=None, name=None, exists=False, **options)

類別 @ref{1bc0,,Font} 代表一個已命名字型。`Font' 實例會被賦予一個的名字，也可以特指他們的字型家族 (font family)、字級 (size)、以及外觀設定。已命名字型是 Tk 建立及辨識字型為單一物件的方式，而不是每次出現時特指字型的屬性。

@quotation

引數：

@quotation


@display
`font' - 字型指定符號元組 (family, size, options)@w{ }
`name' - 獨特字型名稱@w{ }
`exists' - 如果存在的話，指向現有的已命名字型@w{ }
@end display


@end quotation

額外的關鍵字選項（若已指定 `font' 則會忽略）：

@quotation


@display
`family' - 字型家族，例如：Courier、Times@w{ }
`size' - 字級@w{ }
@display
如果 `size' 是正數則會直譯成以點 (point) 為單位的字級。@w{ }
如果 `size' 是負數則會變成絕對值@w{ }
以像素 (pixel) 為單位的字級。@w{ }
@end display
`weight' - 強調字型，例如：NORMAL（標準體）、BOLD（粗體）@w{ }
`slant' - 例如：ROMAN（正體）、ITALIC（斜體）@w{ }
`underline' - 字型加上底線（0 - 無底線、 1 - 加上底線）@w{ }
`overstrike' - 字型加上刪除線（0 - 無刪除線、 1 - 加上刪除線）@w{ }
@end display


@end quotation
@end quotation

@geindex actual() (tkinter.font.Font 的方法)
@anchor{library/tkinter font tkinter font Font actual}@anchor{41cd}
@deffn {方法} actual (option=None, displayof=None)

回傳字型的屬性。
@end deffn

@geindex cget() (tkinter.font.Font 的方法)
@anchor{library/tkinter font tkinter font Font cget}@anchor{41ce}
@deffn {方法} cget (option)

取得字型的其中一個屬性。
@end deffn

@geindex config() (tkinter.font.Font 的方法)
@anchor{library/tkinter font tkinter font Font config}@anchor{41cf}
@deffn {方法} config (**options)

修改字體的多個屬性。
@end deffn

@geindex copy() (tkinter.font.Font 的方法)
@anchor{library/tkinter font tkinter font Font copy}@anchor{41d0}
@deffn {方法} copy ()

回傳目前字體的新實例。
@end deffn

@geindex measure() (tkinter.font.Font 的方法)
@anchor{library/tkinter font tkinter font Font measure}@anchor{41d1}
@deffn {方法} measure (text, displayof=None)

回傳目前字型被格式化時，在特定顯示區域中文字所用的空間。若顯示區域沒有被指定，則會假定主程式視窗為顯示區域。
@end deffn

@geindex metrics() (tkinter.font.Font 的方法)
@anchor{library/tkinter font tkinter font Font metrics}@anchor{41d2}
@deffn {方法} metrics (*options, **kw)

回傳字型特定的資料。其選項包含：


@table @asis

@item `ascent' - 基準線以及最高點的距離

在字型中的一個字母可以佔用的空間

@item `descent' - 基準線以及最低點的距離

在字型中的一個字母可以佔用的空間

@item `linespace' - 最小所需的垂直間距

在字型中的任兩個字母之間，確保跨行時不會有垂直重疊。
@end table

`fixed' - 若字型為等寬 (fixed-width) 的則為 1，否則為 0
@end deffn
@end deffn

@geindex families() (於 tkinter.font 模組中)
@anchor{library/tkinter font tkinter font families}@anchor{41d3}
@deffn {函式} tkinter.font.families (root=None, displayof=None)

回傳不同的字型家族。
@end deffn

@geindex names() (於 tkinter.font 模組中)
@anchor{library/tkinter font tkinter font names}@anchor{41d4}
@deffn {函式} tkinter.font.names (root=None)

回傳已定義字型的名字。
@end deffn

@geindex nametofont() (於 tkinter.font 模組中)
@anchor{library/tkinter font tkinter font nametofont}@anchor{1bc2}
@deffn {函式} tkinter.font.nametofont (name, root=None)

回傳一個 @ref{1bc0,,Font}，代表一個 tk 已命名字型。


在 3.10 版的變更: 新增 `root' 參數。

@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 對話框,tkinter messagebox --- Tkinter 訊息提示,tkinter font --- Tkinter 字型包裝器,以 Tk 打造圖形使用者介面 Graphical User Interfaces
@anchor{library/dialog doc}@anchor{41d5}@anchor{library/dialog tkinter-dialogs}@anchor{41d6}@anchor{library/dialog translation-repo}@anchor{41d7}
@subsection Tkinter 對話框


@menu
* tkinter.simpledialog: tkinter simpledialog --- 標準 Tkinter 輸入對話框. 標準 Tkinter 輸入對話框
* tkinter.filedialog: tkinter filedialog --- 檔案選擇對話框. 檔案選擇對話框
* tkinter.commondialog: tkinter commondialog --- Dialog window templates. Dialog window templates

@end menu

@node tkinter simpledialog --- 標準 Tkinter 輸入對話框,tkinter filedialog --- 檔案選擇對話框,,Tkinter 對話框
@anchor{library/dialog module-tkinter simpledialog}@anchor{fe}@anchor{library/dialog tkinter-simpledialog-standard-tkinter-input-dialogs}@anchor{41d8}
@subsubsection @code{tkinter.simpledialog} --- 標準 Tkinter 輸入對話框


@geindex module; tkinter.simpledialog

`原始碼：'Lib/tkinter/simpledialog.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/tkinter/simpledialog.py}


__________________________________________________________________


The @ref{fe,,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{41d9}
@deffn {函式} tkinter.simpledialog.askfloat (title, prompt, **kw)
@anchor{library/dialog tkinter simpledialog askinteger}@anchor{1bc3}
@deffnx {函式} tkinter.simpledialog.askinteger (title, prompt, **kw)
@anchor{library/dialog tkinter simpledialog askstring}@anchor{41da}
@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{41db}
@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{41dc}
@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{41dd}
@deffn {方法} buttonbox ()

Default behaviour adds OK and Cancel buttons. Override for custom button
layouts.
@end deffn
@end deffn

@node tkinter filedialog --- 檔案選擇對話框,tkinter commondialog --- Dialog window templates,tkinter simpledialog --- 標準 Tkinter 輸入對話框,Tkinter 對話框
@anchor{library/dialog module-tkinter filedialog}@anchor{fa}@anchor{library/dialog tkinter-filedialog-file-selection-dialogs}@anchor{41de}
@subsubsection @code{tkinter.filedialog} --- 檔案選擇對話框


@geindex module; tkinter.filedialog

`原始碼：'Lib/tkinter/filedialog.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/tkinter/filedialog.py}


__________________________________________________________________


The @ref{fa,,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 --- 檔案選擇對話框
@anchor{library/dialog native-load-save-dialogs}@anchor{41df}
@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{41e0}
@deffn {函式} tkinter.filedialog.askopenfile (mode='r', **options)
@anchor{library/dialog tkinter filedialog askopenfiles}@anchor{41e1}
@deffnx {函式} tkinter.filedialog.askopenfiles (mode='r', **options)

The above two functions create an @ref{41e2,,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{41e3}
@deffn {函式} tkinter.filedialog.asksaveasfile (mode='w', **options)

Create a @ref{41e4,,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{41e5}
@deffn {函式} tkinter.filedialog.askopenfilename (**options)
@anchor{library/dialog tkinter filedialog askopenfilenames}@anchor{41e6}
@deffnx {函式} tkinter.filedialog.askopenfilenames (**options)

The above two functions create an @ref{41e2,,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{41e7}
@deffn {函式} tkinter.filedialog.asksaveasfilename (**options)

Create a @ref{41e4,,SaveAs} dialog and return the selected filename.
@end deffn

@geindex askdirectory() (於 tkinter.filedialog 模組中)
@anchor{library/dialog tkinter filedialog askdirectory}@anchor{41e8}
@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{41e2}
@deffn {類別} tkinter.filedialog.Open (master=None, **options)
@anchor{library/dialog tkinter filedialog SaveAs}@anchor{41e4}
@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{41e9}
@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{41ea}
@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{41eb}
@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{41ec}
@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{41ed}
@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{41ee}
@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{41ef}
@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{41f0}
@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{41f1}
@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{41f2}
@deffn {方法} get_selection ()

Retrieve the currently selected item.
@end deffn

@geindex go() (tkinter.filedialog.FileDialog 的方法)
@anchor{library/dialog tkinter filedialog FileDialog go}@anchor{41f3}
@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{41f4}
@deffn {方法} ok_event (event)

Exit dialog returning current selection.
@end deffn

@geindex quit() (tkinter.filedialog.FileDialog 的方法)
@anchor{library/dialog tkinter filedialog FileDialog quit}@anchor{41f5}
@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{41f6}
@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{41f7}
@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{41f8}
@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{41f9}
@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{41fa}
@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{41fb}
@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 --- 檔案選擇對話框,Tkinter 對話框
@anchor{library/dialog module-tkinter commondialog}@anchor{f8}@anchor{library/dialog tkinter-commondialog-dialog-window-templates}@anchor{41fc}
@subsubsection @code{tkinter.commondialog} --- Dialog window templates


@geindex module; tkinter.commondialog

`原始碼：'Lib/tkinter/commondialog.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/tkinter/commondialog.py}


__________________________________________________________________


The @ref{f8,,tkinter.commondialog} module provides the @ref{41c4,,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{41c4}
@deffn {類別} tkinter.commondialog.Dialog (master=None, **options)

@geindex show() (tkinter.commondialog.Dialog 的方法)
@anchor{library/dialog tkinter commondialog Dialog show}@anchor{41fd}
@deffn {方法} show (**options)

Render the Dialog window.
@end deffn
@end deffn


@subsubheading 也參考


@ref{fc,,tkinter.messagebox} 模組、@ref{1f2d,,讀寫檔案}


@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 訊息提示,tkinter scrolledtext --- 捲動文字小工具,Tkinter 對話框,以 Tk 打造圖形使用者介面 Graphical User Interfaces
@anchor{library/tkinter messagebox doc}@anchor{41fe}@anchor{library/tkinter messagebox module-tkinter messagebox}@anchor{fc}@anchor{library/tkinter messagebox tkinter-messagebox-tkinter-message-prompts}@anchor{41ff}@anchor{library/tkinter messagebox translation-repo}@anchor{4200}
@subsection @code{tkinter.messagebox} --- Tkinter 訊息提示


@geindex module; tkinter.messagebox

`原始碼：'Lib/tkinter/messagebox.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/tkinter/messagebox.py}


__________________________________________________________________


@ref{fc,,tkinter.messagebox} 模組提供了模板基底類別以及各種常用配置的便捷方法。訊息框 (message box) 是互動視窗 (modal)，會基於使用者的選擇回傳（@code{True}、@code{False}、@code{None}、@ref{4201,,OK}、@ref{4202,,CANCEL}、@ref{4203,,YES}、@ref{4204,,NO}）的子集。常見的訊息框樣式 (style) 和版面配置 (layout) 包括但不限於：


@float Figure

@image{python-figures/tk_msg,,,,png}

@end float


@geindex Message (tkinter.messagebox 中的類別)
@anchor{library/tkinter messagebox tkinter messagebox Message}@anchor{4205}
@deffn {類別} tkinter.messagebox.Message (master=None, **options)

建立一個訊息視窗，其中包含應用程式指定的訊息、一個圖示和一組按鈕。訊息視窗中的每個按鈕都有唯一的符號名稱作為識別（請參考 `type' 選項）。

支援以下選項：

@quotation


@table @asis

@item `command'

指定當使用者關閉對話框 (dialog) 時要呼叫的函式。使用者按一下以關閉對話框的按鈕的名稱作為引數傳遞。此選項僅適用於 macOS。

@item `default'

給出此訊息視窗的預設按鈕的@ref{4206,,符號名稱}（@ref{4201,,OK}、@ref{4202,,CANCEL} 等）。如果未指定此選項，則對話框中的第一個按鈕將成為預設按鈕。

@item `detail'

透過 `message' 選項指定將輔助訊息給主訊息。訊息詳細資訊將顯示在主要訊息下方，並且在作業系統支援的情況下，將以比主要訊息更不強調的字體顯示。

@item `icon'

指定要顯示的@ref{4207,,圖示}。如果未指定此選項，則會顯示 @ref{4208,,INFO} 圖示。

@item `message'

指定要在此訊息框中顯示的訊息。預設值為空字串。

@item `parent'

使指定視窗成為訊息框的邏輯父視窗 (logical parent window)。訊息框顯示在其父視窗的頂部。

@item `title'

指定顯示為訊息框標題的字串。此選項在 macOS 上被忽略，其平台指南禁止在此類對話方塊上使用標題。

@item `type'

安排一組需顯示的@ref{4209,,預先定義的按鈕組合}。
@end table
@end quotation

@geindex show() (tkinter.messagebox.Message 的方法)
@anchor{library/tkinter messagebox tkinter messagebox Message show}@anchor{420a}
@deffn {方法} show (**options)

顯示訊息視窗並等待使用者選擇其中一個按鈕。然後回傳所選按鈕的符號名稱。關鍵字引數可以覆寫建構函式中指定的選項。
@end deffn
@end deffn

`資訊訊息框'

@geindex showinfo() (於 tkinter.messagebox 模組中)
@anchor{library/tkinter messagebox tkinter messagebox showinfo}@anchor{420b}
@deffn {函式} tkinter.messagebox.showinfo (title=None, message=None, **options)

建立並顯示具有指定標題和訊息的資訊訊息框。
@end deffn

`警告訊息框'

@geindex showwarning() (於 tkinter.messagebox 模組中)
@anchor{library/tkinter messagebox tkinter messagebox showwarning}@anchor{420c}
@deffn {函式} tkinter.messagebox.showwarning (title=None, message=None, **options)

建立並顯示具有指定標題和訊息的警告訊息框。
@end deffn

@geindex showerror() (於 tkinter.messagebox 模組中)
@anchor{library/tkinter messagebox tkinter messagebox showerror}@anchor{420d}
@deffn {函式} tkinter.messagebox.showerror (title=None, message=None, **options)

建立並顯示具有指定標題和訊息的錯誤訊息框。
@end deffn

`問題留言框'

@geindex askquestion() (於 tkinter.messagebox 模組中)
@anchor{library/tkinter messagebox tkinter messagebox askquestion}@anchor{420e}
@deffn {函式} tkinter.messagebox.askquestion (title=None, message=None, *, type=YESNO, **options)

問一個問題。預設顯示按鈕 @ref{4203,,YES} 和 @ref{4204,,NO}。回傳所選按鈕的符號名稱。
@end deffn

@geindex askokcancel() (於 tkinter.messagebox 模組中)
@anchor{library/tkinter messagebox tkinter messagebox askokcancel}@anchor{420f}
@deffn {函式} tkinter.messagebox.askokcancel (title=None, message=None, **options)

詢問操作是否應該繼續。顯示按鈕 @ref{4201,,OK} 和 @ref{4202,,CANCEL}。如果答案正確則傳回 @code{True}，否則回傳 @code{False}。
@end deffn

@geindex askretrycancel() (於 tkinter.messagebox 模組中)
@anchor{library/tkinter messagebox tkinter messagebox askretrycancel}@anchor{4210}
@deffn {函式} tkinter.messagebox.askretrycancel (title=None, message=None, **options)

詢問是否應重試操作。顯示按鈕 @ref{4211,,RETRY} 和 @ref{4202,,CANCEL}。如果答案為是，則回傳 @code{True}，否則回傳 @code{False}。
@end deffn

@geindex askyesno() (於 tkinter.messagebox 模組中)
@anchor{library/tkinter messagebox tkinter messagebox askyesno}@anchor{4212}
@deffn {函式} tkinter.messagebox.askyesno (title=None, message=None, **options)

問一個問題。顯示按鈕 @ref{4203,,YES} 和 @ref{4204,,NO}。如果答案為是，則回傳 @code{True}，否則回傳 @code{False}。
@end deffn

@geindex askyesnocancel() (於 tkinter.messagebox 模組中)
@anchor{library/tkinter messagebox tkinter messagebox askyesnocancel}@anchor{4213}
@deffn {函式} tkinter.messagebox.askyesnocancel (title=None, message=None, **options)

問一個問題。顯示按鈕 @ref{4203,,YES}、@ref{4204,,NO} 和 @ref{4202,,CANCEL}。如果答案為是，則回傳 @code{True}；如果取消則回傳 @code{None}，否則回傳 @code{False}。
@end deffn
@anchor{library/tkinter messagebox messagebox-buttons}@anchor{4206}
按鈕的符號名稱：

@geindex ABORT (於 tkinter.messagebox 模組中)
@anchor{library/tkinter messagebox tkinter messagebox ABORT}@anchor{4214}
@deffn {資料} tkinter.messagebox.ABORT = 'abort'
@end deffn

@geindex RETRY (於 tkinter.messagebox 模組中)
@anchor{library/tkinter messagebox tkinter messagebox RETRY}@anchor{4211}
@deffn {資料} tkinter.messagebox.RETRY = 'retry'
@end deffn

@geindex IGNORE (於 tkinter.messagebox 模組中)
@anchor{library/tkinter messagebox tkinter messagebox IGNORE}@anchor{4215}
@deffn {資料} tkinter.messagebox.IGNORE = 'ignore'
@end deffn

@geindex OK (於 tkinter.messagebox 模組中)
@anchor{library/tkinter messagebox tkinter messagebox OK}@anchor{4201}
@deffn {資料} tkinter.messagebox.OK = 'ok'
@end deffn

@geindex CANCEL (於 tkinter.messagebox 模組中)
@anchor{library/tkinter messagebox tkinter messagebox CANCEL}@anchor{4202}
@deffn {資料} tkinter.messagebox.CANCEL = 'cancel'
@end deffn

@geindex YES (於 tkinter.messagebox 模組中)
@anchor{library/tkinter messagebox tkinter messagebox YES}@anchor{4203}
@deffn {資料} tkinter.messagebox.YES = 'yes'
@end deffn

@geindex NO (於 tkinter.messagebox 模組中)
@anchor{library/tkinter messagebox tkinter messagebox NO}@anchor{4204}
@deffn {資料} tkinter.messagebox.NO = 'no'
@end deffn
@anchor{library/tkinter messagebox messagebox-types}@anchor{4209}
預先定義的按鈕組合：

@geindex ABORTRETRYIGNORE (於 tkinter.messagebox 模組中)
@anchor{library/tkinter messagebox tkinter messagebox ABORTRETRYIGNORE}@anchor{4216}
@deffn {資料} tkinter.messagebox.ABORTRETRYIGNORE = 'abortretryignore'

顯示三個按鈕，其符號名稱為 @ref{4214,,ABORT}、@ref{4211,,RETRY} 和 @ref{4215,,IGNORE}。
@end deffn


@deffn {資料} tkinter.messagebox.OK = 'ok'

顯示一個按鈕，其符號名稱為 @ref{4201,,OK}。
@end deffn

@geindex OKCANCEL (於 tkinter.messagebox 模組中)
@anchor{library/tkinter messagebox tkinter messagebox OKCANCEL}@anchor{4217}
@deffn {資料} tkinter.messagebox.OKCANCEL = 'okcancel'

顯示兩個按鈕，其符號名稱為 @ref{4201,,OK} 和 @ref{4202,,CANCEL}。
@end deffn

@geindex RETRYCANCEL (於 tkinter.messagebox 模組中)
@anchor{library/tkinter messagebox tkinter messagebox RETRYCANCEL}@anchor{4218}
@deffn {資料} tkinter.messagebox.RETRYCANCEL = 'retrycancel'

顯示兩個按鈕，其符號名稱為 @ref{4211,,RETRY} 和 @ref{4202,,CANCEL}。
@end deffn

@geindex YESNO (於 tkinter.messagebox 模組中)
@anchor{library/tkinter messagebox tkinter messagebox YESNO}@anchor{4219}
@deffn {資料} tkinter.messagebox.YESNO = 'yesno'

顯示兩個按鈕，其符號名稱為 @ref{4203,,YES} 和 @ref{4204,,NO}。
@end deffn

@geindex YESNOCANCEL (於 tkinter.messagebox 模組中)
@anchor{library/tkinter messagebox tkinter messagebox YESNOCANCEL}@anchor{421a}
@deffn {資料} tkinter.messagebox.YESNOCANCEL = 'yesnocancel'

顯示三個按鈕，其符號名稱為 @ref{4203,,YES}、@ref{4204,,NO} 和 @ref{4202,,CANCEL}。
@end deffn
@anchor{library/tkinter messagebox messagebox-icons}@anchor{4207}
圖示圖像：

@geindex ERROR (於 tkinter.messagebox 模組中)
@anchor{library/tkinter messagebox tkinter messagebox ERROR}@anchor{421b}
@deffn {資料} tkinter.messagebox.ERROR = 'error'
@end deffn

@geindex INFO (於 tkinter.messagebox 模組中)
@anchor{library/tkinter messagebox tkinter messagebox INFO}@anchor{4208}
@deffn {資料} tkinter.messagebox.INFO = 'info'
@end deffn

@geindex QUESTION (於 tkinter.messagebox 模組中)
@anchor{library/tkinter messagebox tkinter messagebox QUESTION}@anchor{421c}
@deffn {資料} tkinter.messagebox.QUESTION = 'question'
@end deffn

@geindex WARNING (於 tkinter.messagebox 模組中)
@anchor{library/tkinter messagebox tkinter messagebox WARNING}@anchor{421d}
@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 --- 捲動文字小工具,tkinter dnd --- 拖放支援,tkinter messagebox --- Tkinter 訊息提示,以 Tk 打造圖形使用者介面 Graphical User Interfaces
@anchor{library/tkinter scrolledtext doc}@anchor{421e}@anchor{library/tkinter scrolledtext module-tkinter scrolledtext}@anchor{fd}@anchor{library/tkinter scrolledtext tkinter-scrolledtext-scrolled-text-widget}@anchor{421f}@anchor{library/tkinter scrolledtext translation-repo}@anchor{4220}
@subsection @code{tkinter.scrolledtext} --- 捲動文字小工具


@geindex module; tkinter.scrolledtext

`原始碼：'Lib/tkinter/scrolledtext.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/tkinter/scrolledtext.py}


__________________________________________________________________


The @ref{fd,,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{4221,,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{4221,,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{4221}
@deffn {類別} tkinter.scrolledtext.ScrolledText (master=None, **kw)

@geindex frame (tkinter.scrolledtext.ScrolledText 的屬性)
@anchor{library/tkinter scrolledtext tkinter scrolledtext ScrolledText frame}@anchor{4222}
@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{4223}
@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 --- 拖放支援,tkinter ttk --- Tk 主題化小工具,tkinter scrolledtext --- 捲動文字小工具,以 Tk 打造圖形使用者介面 Graphical User Interfaces
@anchor{library/tkinter dnd doc}@anchor{4224}@anchor{library/tkinter dnd module-tkinter dnd}@anchor{f9}@anchor{library/tkinter dnd tkinter-dnd-drag-and-drop-support}@anchor{4225}@anchor{library/tkinter dnd translation-repo}@anchor{4226}
@subsection @code{tkinter.dnd} --- 拖放支援


@geindex module; tkinter.dnd

`原始碼：'Lib/tkinter/dnd.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/tkinter/dnd.py}


__________________________________________________________________


@cartouche
@quotation 備註 
這是一個實驗性的功能，並將在被 Tk DND 取代時棄用。
@end quotation
@end cartouche

@ref{f9,,tkinter.dnd} 模組為單一應用程式內、同一個視窗內或視窗之間的物件提供拖放支援。要讓一個物件可以被拖動，你必須為它建立一個事件繫結來啟動拖放過程。你通常會將一個 ButtonPress 事件繫結到你所寫的回呼函式（請參閱 @ref{41b5,,繫結與事件}）。該函式應該呼叫 @ref{4227,,dnd_start()}，其中 'source' 是要被拖動的物件，而 'event' 是觸發呼叫的事件（你的回呼函式的引數）。

目標物件的選擇過程如下：


@enumerate 

@item 
由上而下搜尋滑鼠下方的區域以尋找目標元件（widget）
@end enumerate

@quotation


@itemize *

@item 
目標元件應該要有一個可呼叫的 `dnd_accept' 屬性（attribute）

@item 
如果 `dnd_accept' 不存在或回傳 @code{None}，搜尋會移至父元件

@item 
如果找不到目標元件，則目標物件為 @code{None}
@end itemize
@end quotation


@enumerate 2

@item 
呼叫 `<old_target>.dnd_leave(source, event)'

@item 
呼叫 `<new_target>.dnd_enter(source, event)'

@item 
呼叫 `<target>.dnd_commit(source, event)' 以通知放下動作

@item 
呼叫 `<source>.dnd_end(target, event)' 以表示拖放結束
@end enumerate

@geindex DndHandler (tkinter.dnd 中的類別)
@anchor{library/tkinter dnd tkinter dnd DndHandler}@anchor{4228}
@deffn {類別} tkinter.dnd.DndHandler (source, event)

`DndHandler' 類別處理拖放事件，它會追蹤事件元件的根上的 Motion 和 ButtonRelease 事件。

@geindex cancel() (tkinter.dnd.DndHandler 的方法)
@anchor{library/tkinter dnd tkinter dnd DndHandler cancel}@anchor{4229}
@deffn {方法} cancel (event=None)

取消拖放過程。
@end deffn

@geindex finish() (tkinter.dnd.DndHandler 的方法)
@anchor{library/tkinter dnd tkinter dnd DndHandler finish}@anchor{422a}
@deffn {方法} finish (event, commit=0)

執行拖放結束函式。
@end deffn

@geindex on_motion() (tkinter.dnd.DndHandler 的方法)
@anchor{library/tkinter dnd tkinter dnd DndHandler on_motion}@anchor{422b}
@deffn {方法} on_motion (event)

在拖動過程中檢查滑鼠下方的區域以尋找目標物件。
@end deffn

@geindex on_release() (tkinter.dnd.DndHandler 的方法)
@anchor{library/tkinter dnd tkinter dnd DndHandler on_release}@anchor{422c}
@deffn {方法} on_release (event)

當釋放模式被觸發時，發出拖動結束的訊號。
@end deffn
@end deffn

@geindex dnd_start() (於 tkinter.dnd 模組中)
@anchor{library/tkinter dnd tkinter dnd dnd_start}@anchor{4227}
@deffn {函式} tkinter.dnd.dnd_start (source, event)

用於拖放過程的工廠函式。
@end deffn


@subsubheading 也參考


@ref{41b5,,繫結與事件}


@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 主題化小工具,IDLE --- Python 編輯器與 shell<2>,tkinter dnd --- 拖放支援,以 Tk 打造圖形使用者介面 Graphical User Interfaces
@anchor{library/tkinter ttk doc}@anchor{422d}@anchor{library/tkinter ttk module-tkinter ttk}@anchor{ff}@anchor{library/tkinter ttk tkinter-ttk-tk-themed-widgets}@anchor{422e}@anchor{library/tkinter ttk translation-repo}@anchor{422f}
@subsection @code{tkinter.ttk} --- Tk 主題化小工具


@geindex module; tkinter.ttk

`原始碼：'Lib/tkinter/ttk.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/tkinter/ttk.py}

@geindex ttk


__________________________________________________________________


The @ref{ff,,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 @ref{ff,,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
* 使用 Ttk:: 
* Ttk Widgets:: 
* Widget:: 
* Combobox:: 
* Spinbox:: 
* Notebook:: 
* Progressbar:: 
* Separator:: 
* Sizegrip:: 
* Treeview:: 
* Ttk Styling:: 

@end menu

@node 使用 Ttk,Ttk Widgets,,tkinter ttk --- Tk 主題化小工具
@anchor{library/tkinter ttk using-ttk}@anchor{4230}
@subsubsection 使用 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 @ref{ff,,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,使用 Ttk,tkinter ttk --- Tk 主題化小工具
@anchor{library/tkinter ttk ttk-widgets}@anchor{4231}
@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{d88,,Spinbox}.
The other six are new: @ref{4232,,Combobox}, @ref{4233,,Notebook},
@ref{4234,,Progressbar}, @code{Separator}, @code{Sizegrip} and
@ref{c7e,,Treeview}. And all them are subclasses of @ref{4235,,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{4236,,TtkStyling}, see the @ref{55a,,Style} class
documentation.

@node Widget,Combobox,Ttk Widgets,tkinter ttk --- Tk 主題化小工具
@anchor{library/tkinter ttk widget}@anchor{4237}
@subsubsection Widget


@code{ttk.Widget} defines standard options and methods supported by Tk
themed widgets and is not supposed to be directly instantiated.

@menu
* 標準選項:: 
* Scrollable Widget Options:: 
* Label Options:: 
* 相容性選項:: 
* Widget States:: 
* ttk.Widget: ttk Widget. 

@end menu

@node 標準選項,Scrollable Widget Options,,Widget
@anchor{library/tkinter ttk standard-options}@anchor{4238}
@subsubsection 標準選項


All the @code{ttk} Widgets accept the following options:


@multitable {xxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

選項

@tab

描述

@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,標準選項,Widget
@anchor{library/tkinter ttk scrollable-widget-options}@anchor{4239}
@subsubsection Scrollable Widget Options


The following options are supported by widgets that are controlled by a
scrollbar.


@multitable {xxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

選項

@tab

描述

@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,相容性選項,Scrollable Widget Options,Widget
@anchor{library/tkinter ttk label-options}@anchor{423a}
@subsubsection Label Options


The following options are supported by labels, buttons and other button-like
widgets.


@multitable {xxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

選項

@tab

描述

@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{1bd2,,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 相容性選項,Widget States,Label Options,Widget
@anchor{library/tkinter ttk compatibility-options}@anchor{423b}
@subsubsection 相容性選項



@multitable {xxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

選項

@tab

描述

@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{423c,,Widget.state()} method does not
affect this option.

@end multitable


@node Widget States,ttk Widget,相容性選項,Widget
@anchor{library/tkinter ttk widget-states}@anchor{423d}
@subsubsection Widget States


The widget state is a bitmap of independent state flags.


@multitable {xxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

旗標

@tab

描述

@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{423e}
@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{4235}
@deffn {類別} tkinter.ttk.Widget

@geindex identify() (tkinter.ttk.Widget 的方法)
@anchor{library/tkinter ttk tkinter ttk Widget identify}@anchor{423f}
@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{4240}
@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{423c}
@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 主題化小工具
@anchor{library/tkinter ttk combobox}@anchor{4241}
@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{4235,,Widget}: @code{Widget.cget()},
@code{Widget.configure()}, @ref{423f,,Widget.identify()}, @ref{4240,,Widget.instate()}
and @ref{423c,,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
* 選項:: 
* Virtual events:: 
* ttk.Combobox: ttk Combobox. 

@end menu

@node 選項,Virtual events,,Combobox
@anchor{library/tkinter ttk options}@anchor{4242}
@subsubsection 選項


This widget accepts the following specific options:


@multitable {xxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

選項

@tab

描述

@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,選項,Combobox
@anchor{library/tkinter ttk virtual-events}@anchor{4243}
@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{4244}
@subsubsection ttk.Combobox


@geindex Combobox (tkinter.ttk 中的類別)
@anchor{library/tkinter ttk tkinter ttk Combobox}@anchor{4232}
@deffn {類別} tkinter.ttk.Combobox

@geindex current() (tkinter.ttk.Combobox 的方法)
@anchor{library/tkinter ttk tkinter ttk Combobox current}@anchor{4245}
@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{4246}
@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{4247}
@deffn {方法} set (value)

Sets the value of the combobox to `value'.
@end deffn
@end deffn

@node Spinbox,Notebook,Combobox,tkinter ttk --- Tk 主題化小工具
@anchor{library/tkinter ttk spinbox}@anchor{4248}
@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{4235,,Widget}: @code{Widget.cget()},
@code{Widget.configure()}, @ref{423f,,Widget.identify()}, @ref{4240,,Widget.instate()}
and @ref{423c,,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
* 選項: 選項<2>. 
* Virtual events: Virtual events<2>. 
* ttk.Spinbox: ttk Spinbox. 

@end menu

@node 選項<2>,Virtual events<2>,,Spinbox
@anchor{library/tkinter ttk id1}@anchor{4249}
@subsubsection 選項


This widget accepts the following specific options:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

選項

@tab

描述

@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,選項<2>,Spinbox
@anchor{library/tkinter ttk id2}@anchor{424a}
@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{424b}
@subsubsection ttk.Spinbox


@geindex Spinbox (tkinter.ttk 中的類別)
@anchor{library/tkinter ttk tkinter ttk Spinbox}@anchor{d88}
@deffn {類別} tkinter.ttk.Spinbox

@geindex get() (tkinter.ttk.Spinbox 的方法)
@anchor{library/tkinter ttk tkinter ttk Spinbox get}@anchor{424c}
@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{424d}
@deffn {方法} set (value)

Sets the value of the spinbox to `value'.
@end deffn
@end deffn

@node Notebook,Progressbar,Spinbox,tkinter ttk --- Tk 主題化小工具
@anchor{library/tkinter ttk notebook}@anchor{424e}
@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
* 選項: 選項<3>. 
* Tab Options:: 
* Tab Identifiers:: 
* 虛擬事件:: 
* ttk.Notebook: ttk Notebook. 

@end menu

@node 選項<3>,Tab Options,,Notebook
@anchor{library/tkinter ttk id3}@anchor{424f}
@subsubsection 選項


This widget accepts the following specific options:


@multitable {xxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

選項

@tab

描述

@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,選項<3>,Notebook
@anchor{library/tkinter ttk tab-options}@anchor{4250}
@subsubsection Tab Options


There are also specific options for tabs:


@multitable {xxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

選項

@tab

描述

@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{4235,,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{423a,,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{4251,,Notebook.enable_traversal()} is
called.

@end multitable


@node Tab Identifiers,虛擬事件,Tab Options,Notebook
@anchor{library/tkinter ttk tab-identifiers}@anchor{4252}
@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{4253,,Notebook.index()})
@end itemize

@node 虛擬事件,ttk Notebook,Tab Identifiers,Notebook
@anchor{library/tkinter ttk id4}@anchor{4254}
@subsubsection 虛擬事件


This widget generates a `<<NotebookTabChanged>>' virtual event after a new
tab is selected.

@node ttk Notebook,,虛擬事件,Notebook
@anchor{library/tkinter ttk ttk-notebook}@anchor{4255}
@subsubsection ttk.Notebook


@geindex Notebook (tkinter.ttk 中的類別)
@anchor{library/tkinter ttk tkinter ttk Notebook}@anchor{4233}
@deffn {類別} tkinter.ttk.Notebook

@geindex add() (tkinter.ttk.Notebook 的方法)
@anchor{library/tkinter ttk tkinter ttk Notebook add}@anchor{4256}
@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.

可用的選項清單請見 @ref{4250,,Tab Options}。
@end deffn

@geindex forget() (tkinter.ttk.Notebook 的方法)
@anchor{library/tkinter ttk tkinter ttk Notebook forget}@anchor{4257}
@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{4258}
@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{4256,,add()} command.
@end deffn

@geindex identify() (tkinter.ttk.Notebook 的方法)
@anchor{library/tkinter ttk tkinter ttk Notebook identify}@anchor{4259}
@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{4253}
@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{425a}
@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.

可用的選項清單請見 @ref{4250,,Tab Options}。
@end deffn

@geindex select() (tkinter.ttk.Notebook 的方法)
@anchor{library/tkinter ttk tkinter ttk Notebook select}@anchor{425b}
@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{425c}
@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{425d}
@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{4251}
@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 主題化小工具
@anchor{library/tkinter ttk progressbar}@anchor{425e}
@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
* 選項: 選項<4>. 
* ttk.Progressbar: ttk Progressbar. 

@end menu

@node 選項<4>,ttk Progressbar,,Progressbar
@anchor{library/tkinter ttk id5}@anchor{425f}
@subsubsection 選項


This widget accepts the following specific options:


@multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

選項

@tab

描述

@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

"determinate" 與 "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,,選項<4>,Progressbar
@anchor{library/tkinter ttk ttk-progressbar}@anchor{4260}
@subsubsection ttk.Progressbar


@geindex Progressbar (tkinter.ttk 中的類別)
@anchor{library/tkinter ttk tkinter ttk Progressbar}@anchor{4234}
@deffn {類別} tkinter.ttk.Progressbar

@geindex start() (tkinter.ttk.Progressbar 的方法)
@anchor{library/tkinter ttk tkinter ttk Progressbar start}@anchor{4261}
@deffn {方法} start (interval=None)

Begin autoincrement mode: schedules a recurring timer event that calls
@ref{4262,,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{4262}
@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{4263}
@deffn {方法} stop ()

Stop autoincrement mode: cancels any recurring timer event initiated by
@ref{4261,,Progressbar.start()} for this progress bar.
@end deffn
@end deffn

@node Separator,Sizegrip,Progressbar,tkinter ttk --- Tk 主題化小工具
@anchor{library/tkinter ttk separator}@anchor{4264}
@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
* 選項: 選項<5>. 

@end menu

@node 選項<5>,,,Separator
@anchor{library/tkinter ttk id6}@anchor{4265}
@subsubsection 選項


This widget accepts the following specific option:


@multitable {xxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

選項

@tab

描述

@item

orient

@tab

One of "horizontal" or "vertical". Specifies the orientation of
the separator.

@end multitable


@node Sizegrip,Treeview,Separator,tkinter ttk --- Tk 主題化小工具
@anchor{library/tkinter ttk sizegrip}@anchor{4266}
@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{4267}
@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{4268}
@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 主題化小工具
@anchor{library/tkinter ttk treeview}@anchor{4269}
@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{426a,,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{4239,,Scrollable Widget Options} and the methods
@ref{426b,,Treeview.xview()} and @ref{426c,,Treeview.yview()}.

@menu
* 選項: 選項<6>. 
* Item Options:: 
* Tag Options:: 
* Column Identifiers:: 
* 虛擬事件: 虛擬事件<2>. 
* ttk.Treeview: ttk Treeview. 

@end menu

@node 選項<6>,Item Options,,Treeview
@anchor{library/tkinter ttk id7}@anchor{426d}
@subsubsection 選項


This widget accepts the following specific options:


@multitable {xxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

選項

@tab

描述

@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,選項<6>,Treeview
@anchor{library/tkinter ttk item-options}@anchor{426e}
@subsubsection Item Options


The following item options may be specified for items in the insert and item
widget commands.


@multitable {xxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

選項

@tab

描述

@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{426f}
@subsubsection Tag Options


The following options may be specified on tags:


@multitable {xxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

選項

@tab

描述

@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,虛擬事件<2>,Tag Options,Treeview
@anchor{library/tkinter ttk column-identifiers}@anchor{426a}
@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

註解：


@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 虛擬事件<2>,ttk Treeview,Column Identifiers,Treeview
@anchor{library/tkinter ttk id8}@anchor{4270}
@subsubsection 虛擬事件


The Treeview widget generates the following virtual events.


@multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

事件

@tab

描述

@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{4271,,Treeview.focus()} and @ref{c7d,,Treeview.selection()} methods can be used
to determine the affected item or items.

@node ttk Treeview,,虛擬事件<2>,Treeview
@anchor{library/tkinter ttk ttk-treeview}@anchor{4272}
@subsubsection ttk.Treeview


@geindex Treeview (tkinter.ttk 中的類別)
@anchor{library/tkinter ttk tkinter ttk Treeview}@anchor{c7e}
@deffn {類別} tkinter.ttk.Treeview

@geindex bbox() (tkinter.ttk.Treeview 的方法)
@anchor{library/tkinter ttk tkinter ttk Treeview bbox}@anchor{4273}
@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{4274}
@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{4275}
@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{4276}
@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.

有效的選項/值為：


@table @asis

@item `id'

回傳欄位名稱。這是唯讀選項。

@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{4277}
@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{4278}
@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{4279}
@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{4271}
@deffn {方法} focus (item=None)

If `item' is specified, sets the focus item to `item'. Otherwise, returns
the current focus item, or '@w{'} if there is none.
@end deffn

@geindex heading() (tkinter.ttk.Treeview 的方法)
@anchor{library/tkinter ttk tkinter ttk Treeview heading}@anchor{427a}
@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.

有效的選項/值為：


@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{427b}
@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{427c}
@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{427d}
@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{427e}
@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{427f}
@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{4280}
@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{4281}
@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.

可用的選項清單請見 @ref{426e,,Item Options}。
@end deffn

@geindex item() (tkinter.ttk.Treeview 的方法)
@anchor{library/tkinter ttk tkinter ttk Treeview item}@anchor{4282}
@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{4283}
@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{4284}
@deffn {方法} next (item)

Returns the identifier of `item''s next sibling, or '@w{'} 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{4285}
@deffn {方法} parent (item)

Returns the ID of the parent of `item', or '@w{'} 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{4286}
@deffn {方法} prev (item)

Returns the identifier of `item''s previous sibling, or '@w{'} 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{4287}
@deffn {方法} reattach (item, parent, index)

一個 @ref{4283,,Treeview.move()} 的別名。
@end deffn

@geindex see() (tkinter.ttk.Treeview 的方法)
@anchor{library/tkinter ttk tkinter ttk Treeview see}@anchor{4288}
@deffn {方法} see (item)

確保 `item' 是可見的。

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{c7d}
@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{c7f}
@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{4289}
@deffn {方法} selection_add (*items)

將 `items' 加入選擇。


在 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{428a}
@deffn {方法} selection_remove (*items)

從選擇中移除 `items'。


在 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{428b}
@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{428c}
@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{428d}
@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{428e}
@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{428f}
@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{426b}
@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{426c}
@deffn {方法} yview (*args)

Query or modify vertical position of the treeview.
@end deffn
@end deffn

@node Ttk Styling,,Treeview,tkinter ttk --- Tk 主題化小工具
@anchor{library/tkinter ttk ttk-styling}@anchor{4290}@anchor{library/tkinter ttk ttkstyling}@anchor{4236}
@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{55a}
@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{4291}
@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{1bd2}
@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{4292}
@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{4293}
@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{4294,,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{559}
@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
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',
@ref{559,,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
style = ttk.Style(root)
style.element_create('plain.background', 'from', 'default')
@end example

If "vsapi" is used as the value of `etype', @ref{559,,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
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{4295}
@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{4296}
@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{4297}
@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{4298,,theme_settings()}.
@end deffn

@geindex theme_settings() (tkinter.ttk.Style 的方法)
@anchor{library/tkinter ttk tkinter ttk Style theme_settings}@anchor{4298}
@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{4291,,Style.configure()}, @ref{1bd2,,Style.map()}, @ref{4293,,Style.layout()} and
@ref{559,,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{4299}
@deffn {方法} theme_names ()

回傳所有已知的主題。
@end deffn

@geindex theme_use() (tkinter.ttk.Style 的方法)
@anchor{library/tkinter ttk tkinter ttk Style theme_use}@anchor{429a}
@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{4294}
@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.

有效的選項/值為：


@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 或 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{423f,,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{4294,,Layout}.
@end table
@anchor{library/tkinter ttk layout}@anchor{429b}
@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 編輯器與 shell<2>,turtle --- 龜圖學 Turtle graphics,tkinter ttk --- Tk 主題化小工具,以 Tk 打造圖形使用者介面 Graphical User Interfaces
@anchor{library/idle doc}@anchor{429c}@anchor{library/idle idle}@anchor{1210}@anchor{library/idle idle-python-editor-and-shell}@anchor{429d}@anchor{library/idle translation-repo}@anchor{429e}
@subsection IDLE --- Python 編輯器與 shell


`原始碼：'Lib/idlelib/@footnote{https://github.com/python/cpython/tree/3.14/Lib/idlelib/}

@geindex IDLE
@geindex Python Editor（Python 編輯器）
@geindex Integrated Development Environment（整合開發環境）

@c Remember to update Lib/idlelib/help.html with idlelib.help.copy_source() when modifying this file.


__________________________________________________________________


IDLE 是 Python 的整合開發與學習環境 (Integrated Development and Learning Environment)。

IDLE 具有以下功能：


@itemize *

@item 
跨平台：在 Windows、Unix 和 macOS 上的運作大致相同

@item 
Python shell window（互動式直譯器）提供有色彩的程式碼輸入、輸出和錯誤訊息

@item 
多視窗文字編輯器，具有多次復原、Python 語法上色、智慧縮排、呼叫提示、自動完成等功能

@item 
能在任何視窗中搜尋、編輯器視窗中取代文字，以及搜尋多個檔案 (grep)

@item 
具有持久性斷點、能夠逐步執行和檢視全域和區域命名空間的除錯器

@item 
設定、瀏覽器和其他對話框
@end itemize

@menu
* 目錄:: 
* Editing and Navigation:: 
* Startup and Code Execution:: 
* Help and Preferences:: 
* idlelib: idlelib --- implementation of IDLE application. implementation of IDLE application

@end menu

@node 目錄,Editing and Navigation,,IDLE --- Python 編輯器與 shell<2>
@anchor{library/idle menus}@anchor{429f}
@subsubsection 目錄


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,,目錄
@anchor{library/idle file-menu-shell-and-editor}@anchor{42a0}
@subsubsection File menu (Shell and Editor)



@table @asis

@item 新增檔案

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 namager is set to hide
extensions, the current extension will be omitted in the file name box.
If the new filename has no '.', '.py' and '.txt' will be added for Python
and text files, except that on macOS Aqua,'.py' is added for all files.)

@item Save Copy As...

Save the current window to different file without changing the associated
file.  (See Save As note above about filename extensions.)

@item Print Window

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 離開 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,目錄
@anchor{library/idle edit-menu-shell-and-editor}@anchor{42a1}
@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{42a2,,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{42a3,,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,目錄
@anchor{library/idle format-menu}@anchor{42a4}@anchor{library/idle format-menu-editor-window-only}@anchor{42a5}
@subsubsection Format menu (Editor window only)



@table @asis

@item Format Paragraph

Reformat the current blank-line-delimited paragraph in comment block or
multiline string or selected line in a string.  All lines in the
paragraph will be formatted to less than N columns, where N defaults to 72.

@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 Chitespace

Remove trailing space and other whitespace characters after the last
non-whitespace character of a line by applying 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,目錄
@anchor{library/idle run-menu-editor-window-only}@anchor{42a6}
@subsubsection Run menu (Editor window only)

@anchor{library/idle run-module}@anchor{42a7}

@table @asis

@item Run Module

Do @ref{42a8,,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{42a9}

@table @asis

@item Run... Customized

Same as @ref{42a7,,Run Module}, but run the module with customized
settings.  `Command Line Arguments' extend @ref{1465,,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{42a8}

@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{42aa}

@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,目錄
@anchor{library/idle shell-menu-shell-window-only}@anchor{42ab}
@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,目錄
@anchor{library/idle debug-menu-shell-window-only}@anchor{42ac}
@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,目錄
@anchor{library/idle options-menu-shell-and-editor}@anchor{42ad}
@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{42ae,,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{42af,,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{42ae,,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,目錄
@anchor{library/idle window-menu-shell-and-editor}@anchor{42b0}
@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,目錄
@anchor{library/idle help-menu-shell-and-editor}@anchor{42b1}
@subsubsection Help menu (Shell and Editor)



@table @asis

@item 關於 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 文件

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{42b2,,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,目錄
@anchor{library/idle context-menus}@anchor{42b3}
@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,目錄,IDLE --- Python 編輯器與 shell<2>
@anchor{library/idle editing-and-navigation}@anchor{42b4}@anchor{library/idle id1}@anchor{42b5}
@subsubsection Editing and Navigation


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

@end menu

@node Editor windows,Key bindings,,Editing and Navigation
@anchor{library/idle editor-windows}@anchor{42b6}
@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{42b7}
@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{42b8}
@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{42a4,,Format menu}.

@node Search and Replace,Completions,Automatic indentation,Editing and Navigation
@anchor{library/idle search-and-replace}@anchor{42b9}
@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{42a2}@anchor{library/idle id2}@anchor{42ba}
@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{873,,os.sep} or
@ref{874,,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,Code Context,Completions,Editing and Navigation
@anchor{library/idle calltips}@anchor{42a3}@anchor{library/idle id3}@anchor{42bb}
@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 Code Context,Shell window,Calltips,Editing and Navigation
@anchor{library/idle code-context}@anchor{42af}@anchor{library/idle id4}@anchor{42bc}
@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{42bd}
@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{18e,,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{42be}
@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{a06,,soft keywords} @ref{a07,,match},
@ref{a07,,case}, and @ref{a08,,_} 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 編輯器與 shell<2>
@anchor{library/idle startup-and-code-execution}@anchor{42bf}
@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{1b8,,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
* 命令列用法: 命令列用法<5>. 
* Startup failure:: 
* Running user code:: 
* User output in Shell:: 
* Developing tkinter applications:: 
* Running without a subprocess:: 

@end menu

@node 命令列用法<5>,Startup failure,,Startup and Code Execution
@anchor{library/idle command-line-usage}@anchor{42c0}
@subsubsection 命令列用法


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 命令列選項; -c
@anchor{library/idle cmdoption-idle-c}@anchor{42c1}
@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 命令列選項; -d
@anchor{library/idle cmdoption-idle-d}@anchor{42c2}
@deffn {Option} @w{-}d

Enable the debugger and open the shell window.
@end deffn

@geindex idle 命令列選項; -e
@anchor{library/idle cmdoption-idle-e}@anchor{42c3}
@deffn {Option} @w{-}e

Open an editor window.
@end deffn

@geindex idle 命令列選項; -h
@anchor{library/idle cmdoption-idle-h}@anchor{42c4}
@deffn {Option} @w{-}h

Print a help message with legal combinations of options and exit.
@end deffn

@geindex idle 命令列選項; -i
@anchor{library/idle cmdoption-idle-i}@anchor{42c5}
@deffn {Option} @w{-}i

Open a shell window.
@end deffn

@geindex idle 命令列選項; -r
@anchor{library/idle cmdoption-idle-r}@anchor{42c6}
@deffn {Option} @w{-}r <file>

Run the specified file in the shell window.
@end deffn

@geindex idle 命令列選項; -s
@anchor{library/idle cmdoption-idle-s}@anchor{42c7}
@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{1b8,,PYTHONSTARTUP}) before opening the shell window.
@end deffn

@geindex idle 命令列選項; -t
@anchor{library/idle cmdoption-idle-t}@anchor{42c8}
@deffn {Option} @w{-}t <title>

Set the title of the shell window.
@end deffn

@geindex idle 命令列選項; -
@anchor{library/idle cmdoption-idle-0}@anchor{42c9}
@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,命令列用法<5>,Startup and Code Execution
@anchor{library/idle startup-failure}@anchor{42ca}
@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{42cb}
@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{24b9,,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{42cc}
@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{42cd}
@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{42ce}
@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 編輯器與 shell<2>
@anchor{library/idle help-and-preferences}@anchor{42cf}
@subsubsection Help and Preferences


@menu
* Help sources:: 
* 設定偏好:: 
* macOS 上的 IDLE:: 
* Extensions:: 

@end menu

@node Help sources,設定偏好,,Help and Preferences
@anchor{library/idle help-sources}@anchor{42b2}@anchor{library/idle id5}@anchor{42d0}
@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 設定偏好,macOS 上的 IDLE,Help sources,Help and Preferences
@anchor{library/idle preferences}@anchor{42ae}@anchor{library/idle setting-preferences}@anchor{42d1}
@subsubsection 設定偏好


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 macOS 上的 IDLE,Extensions,設定偏好,Help and Preferences
@anchor{library/idle idle-on-macos}@anchor{42d2}
@subsubsection macOS 上的 IDLE


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,,macOS 上的 IDLE,Help and Preferences
@anchor{library/idle extensions}@anchor{42d3}
@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 編輯器與 shell<2>
@anchor{library/idle idlelib-implementation-of-idle-application}@anchor{42d4}@anchor{library/idle module-idlelib}@anchor{77}
@subsubsection idlelib --- implementation of IDLE application


@geindex module; idlelib

`原始碼：'Lib/idlelib/@footnote{https://github.com/python/cpython/tree/3.14/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 編輯器與 shell<2>,以 Tk 打造圖形使用者介面 Graphical User Interfaces
@anchor{library/turtle doc}@anchor{42d5}@anchor{library/turtle module-turtle}@anchor{107}@anchor{library/turtle translation-repo}@anchor{42d6}@anchor{library/turtle turtle-turtle-graphics}@anchor{42d7}
@subsection @code{turtle} --- 龜圖學 (Turtle graphics)


@geindex module; turtle

`原始碼：'Lib/turtle.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/turtle.py}

@c from turtle import *
@c turtle = Turtle()

@c import os
@c os.remove("my_drawing.ps")


__________________________________________________________________


@menu
* 介紹:: 
* Get started:: 
* 教學: 教學<4>. 
* How to...: How to. 
* Turtle graphics reference:: 
* Methods of RawTurtle/Turtle and corresponding functions:: 
* Methods of TurtleScreen/Screen and corresponding functions:: 
* Public classes:: 
* 解釋: 解釋<2>. 
* Help and configuration:: 
* turtledemo: turtledemo --- Demo scripts. 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 介紹,Get started,,turtle --- 龜圖學 Turtle graphics
@anchor{library/turtle introduction}@anchor{42d8}
@subsubsection 介紹


龜圖學是由 Wally Feurzeig，Seymour Papert 與 Cynthia Solomon 於 1967 年開發的，一個 以 Logo 程式語言撰寫的廣受歡迎的幾何繪圖工具@footnote{https://en.wikipedia.org/wiki/Turtle_(robot)}。

@node Get started,教學<4>,介紹,turtle --- 龜圖學 Turtle graphics
@anchor{library/turtle get-started}@anchor{42d9}
@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



龜可以使用重複簡單動作之程式來畫出複雜的形狀。

@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 教學<4>,How to,Get started,turtle --- 龜圖學 Turtle graphics
@anchor{library/turtle turtle-tutorial}@anchor{42da}@anchor{library/turtle tutorial}@anchor{42db}
@subsubsection 教學


New users should start here. In this tutorial we'll explore some of the
basics of turtle drawing.

@menu
* 啟動一個烏龜環境:: 
* 基本繪圖:: 
* Making algorithmic patterns:: 

@end menu

@node 啟動一個烏龜環境,基本繪圖,,教學<4>
@anchor{library/turtle starting-a-turtle-environment}@anchor{42dc}
@subsubsection 啟動一個烏龜環境


在 Python shell 中，引入 @code{turtle} 模組中所有物件：

@example
from turtle import *
@end example

If you run into a @code{No module named '_tkinter'} error, you'll have to
install the @ref{f6,,Tk interface package} on your system.

@node 基本繪圖,Making algorithmic patterns,啟動一個烏龜環境,教學<4>
@anchor{library/turtle basic-drawing}@anchor{42dd}
@subsubsection 基本繪圖


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,,基本繪圖
@anchor{library/turtle pen-control}@anchor{42de}
@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,基本繪圖
@anchor{library/turtle the-turtle-s-position}@anchor{42df}
@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,,基本繪圖,教學<4>
@anchor{library/turtle making-algorithmic-patterns}@anchor{42e0}
@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,教學<4>,turtle --- 龜圖學 Turtle graphics
@anchor{library/turtle how-to}@anchor{42e1}@anchor{library/turtle turtle-how-to}@anchor{42e2}
@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{42e3}
@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{42da,,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{34c5,,forward()}. These are especially
useful when working with learners for whom typing is not a skill.
@anchor{library/turtle note}@anchor{42e4}
@quotation

You'll need to have the @ref{f6,,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{42e5}
@subsubsection Automatically begin and end filling


Starting with Python 3.14, you can use the @ref{2a3,,fill()} @ref{1e1,,context manager}
instead of @ref{42e6,,begin_fill()} and @ref{42e7,,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{42e8}
@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{42e9}
@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{42ea}
@subsubsection Use object-oriented turtle graphics



@subsubheading 也參考


@ref{42eb,,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{42ec,,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{42ed}
@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{42ee}
@subsubsection Turtle methods



@table @asis

@item Turtle motion


@table @asis

@item Move and draw


@display
@ref{34c5,,forward()} | @ref{42ef,,fd()}@w{ }
@ref{42f0,,backward()} | @ref{42f1,,bk()} | @ref{42f2,,back()}@w{ }
@ref{42f3,,right()} | @ref{42f4,,rt()}@w{ }
@ref{42f5,,left()} | @ref{42f6,,lt()}@w{ }
@ref{42f7,,goto()} | @ref{42f8,,setpos()} | @ref{42f9,,setposition()}@w{ }
@ref{19e6,,teleport()}@w{ }
@ref{42fa,,setx()}@w{ }
@ref{42fb,,sety()}@w{ }
@ref{42fc,,setheading()} | @ref{42fd,,seth()}@w{ }
@ref{42fe,,home()}@w{ }
@ref{42ff,,circle()}@w{ }
@ref{4300,,dot()}@w{ }
@ref{4301,,stamp()}@w{ }
@ref{4302,,clearstamp()}@w{ }
@ref{4303,,clearstamps()}@w{ }
@ref{4304,,undo()}@w{ }
@ref{4305,,speed()}@w{ }
@end display



@item Tell Turtle's state


@display
@ref{4306,,position()} | @ref{4307,,pos()}@w{ }
@ref{4308,,towards()}@w{ }
@ref{4309,,xcor()}@w{ }
@ref{430a,,ycor()}@w{ }
@ref{430b,,heading()}@w{ }
@ref{430c,,distance()}@w{ }
@end display



@item Setting and measurement


@display
@ref{430d,,degrees()}@w{ }
@ref{430e,,radians()}@w{ }
@end display


@end table

@item Pen control


@table @asis

@item Drawing state


@display
@ref{430f,,pendown()} | @ref{4310,,pd()} | @ref{4311,,down()}@w{ }
@ref{4312,,penup()} | @ref{4313,,pu()} | @ref{4314,,up()}@w{ }
@ref{4315,,pensize()} | @ref{4316,,width()}@w{ }
@ref{4317,,pen()}@w{ }
@ref{4318,,isdown()}@w{ }
@end display



@item Color control


@display
@ref{4319,,color()}@w{ }
@ref{431a,,pencolor()}@w{ }
@ref{431b,,fillcolor()}@w{ }
@end display



@item Filling


@display
@ref{431c,,filling()}@w{ }
@ref{2a3,,fill()}@w{ }
@ref{42e6,,begin_fill()}@w{ }
@ref{42e7,,end_fill()}@w{ }
@end display



@item More drawing control


@display
@ref{431d,,reset()}@w{ }
@ref{431e,,clear()}@w{ }
@ref{431f,,write()}@w{ }
@end display


@end table

@item Turtle state


@table @asis

@item Visibility


@display
@ref{4320,,showturtle()} | @ref{4321,,st()}@w{ }
@ref{4322,,hideturtle()} | @ref{4323,,ht()}@w{ }
@ref{4324,,isvisible()}@w{ }
@end display



@item Appearance


@display
@ref{4325,,shape()}@w{ }
@ref{4326,,resizemode()}@w{ }
@ref{4327,,shapesize()} | @ref{4328,,turtlesize()}@w{ }
@ref{4329,,shearfactor()}@w{ }
@ref{927,,tiltangle()}@w{ }
@ref{432a,,tilt()}@w{ }
@ref{432b,,shapetransform()}@w{ }
@ref{432c,,get_shapepoly()}@w{ }
@end display


@end table

@item Using events


@display
@ref{432d,,onclick()}@w{ }
@ref{432e,,onrelease()}@w{ }
@ref{432f,,ondrag()}@w{ }
@end display



@item Special Turtle methods


@display
@ref{2a4,,poly()}@w{ }
@ref{4330,,begin_poly()}@w{ }
@ref{4331,,end_poly()}@w{ }
@ref{4332,,get_poly()}@w{ }
@ref{4333,,clone()}@w{ }
@ref{4334,,getturtle()} | @ref{4335,,getpen()}@w{ }
@ref{4336,,getscreen()}@w{ }
@ref{4337,,setundobuffer()}@w{ }
@ref{4338,,undobufferentries()}@w{ }
@end display


@end table

@node Methods of TurtleScreen/Screen,,Turtle methods,Turtle graphics reference
@anchor{library/turtle methods-of-turtlescreen-screen}@anchor{4339}
@subsubsection Methods of TurtleScreen/Screen



@table @asis

@item Window control


@display
@ref{433a,,bgcolor()}@w{ }
@ref{433b,,bgpic()}@w{ }
@ref{433c,,clearscreen()}@w{ }
@ref{433d,,resetscreen()}@w{ }
@ref{433e,,screensize()}@w{ }
@ref{433f,,setworldcoordinates()}@w{ }
@end display



@item Animation control


@display
@ref{2a5,,no_animation()}@w{ }
@ref{4340,,delay()}@w{ }
@ref{4341,,tracer()}@w{ }
@ref{4342,,update()}@w{ }
@end display



@item Using screen events


@display
@ref{4343,,listen()}@w{ }
@ref{4344,,onkey()} | @ref{4345,,onkeyrelease()}@w{ }
@ref{4346,,onkeypress()}@w{ }
@ref{432d,,onclick()} | @ref{4347,,onscreenclick()}@w{ }
@ref{4348,,ontimer()}@w{ }
@ref{4349,,mainloop()} | @ref{434a,,done()}@w{ }
@end display



@item Settings and special methods


@display
@ref{434b,,mode()}@w{ }
@ref{434c,,colormode()}@w{ }
@ref{434d,,getcanvas()}@w{ }
@ref{434e,,getshapes()}@w{ }
@ref{434f,,register_shape()} | @ref{4350,,addshape()}@w{ }
@ref{4351,,turtles()}@w{ }
@ref{4352,,window_height()}@w{ }
@ref{4353,,window_width()}@w{ }
@end display



@item Input methods


@display
@ref{1b78,,textinput()}@w{ }
@ref{1b79,,numinput()}@w{ }
@end display



@item Methods specific to Screen


@display
@ref{4354,,bye()}@w{ }
@ref{4355,,exitonclick()}@w{ }
@ref{18d4,,save()}@w{ }
@ref{4356,,setup()}@w{ }
@ref{4357,,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{4358}
@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{4359}
@subsubsection Turtle motion


@geindex forward() (於 turtle 模組中)
@geindex fd() (於 turtle 模組中)
@anchor{library/turtle turtle forward}@anchor{34c5}
@deffn {函式} turtle.forward (distance)
@anchor{library/turtle turtle fd}@anchor{42ef}
@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{42f2}
@deffn {函式} turtle.back (distance)
@anchor{library/turtle turtle bk}@anchor{42f1}
@deffnx {函式} turtle.bk (distance)
@anchor{library/turtle turtle backward}@anchor{42f0}
@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{42f3}
@deffn {函式} turtle.right (angle)
@anchor{library/turtle turtle rt}@anchor{42f4}
@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{430d,,degrees()} and @ref{430e,,radians()} functions.)  Angle
orientation depends on the turtle mode, see @ref{434b,,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{42f5}
@deffn {函式} turtle.left (angle)
@anchor{library/turtle turtle lt}@anchor{42f6}
@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{430d,,degrees()} and @ref{430e,,radians()} functions.)  Angle
orientation depends on the turtle mode, see @ref{434b,,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{42f7}
@deffn {函式} turtle.goto (x, y=None)
@anchor{library/turtle turtle setpos}@anchor{42f8}
@deffnx {函式} turtle.setpos (x, y=None)
@anchor{library/turtle turtle setposition}@anchor{42f9}
@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{435a,,Vec2D}
(e.g. as returned by @ref{4307,,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{19e6}
@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


在 3.12 版被加入.

@end deffn

@geindex setx() (於 turtle 模組中)
@anchor{library/turtle turtle setx}@anchor{42fa}
@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{42fb}
@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{42fc}
@deffn {函式} turtle.setheading (to_angle)
@anchor{library/turtle turtle seth}@anchor{42fd}
@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{42fe}
@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{434b,,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{42ff}
@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{4300}
@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{4301}
@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{4302}
@deffn {函式} turtle.clearstamp (stampid)

@*參數: 
@code{stampid} -- an integer, must be return value of previous
@ref{4301,,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{4303}
@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{4304}
@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{4305}
@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{435b}
@subsubsection Tell Turtle's state


@geindex position() (於 turtle 模組中)
@geindex pos() (於 turtle 模組中)
@anchor{library/turtle turtle position}@anchor{4306}
@deffn {函式} turtle.position ()
@anchor{library/turtle turtle pos}@anchor{4307}
@deffnx {函式} turtle.pos ()

Return the turtle's current location (x,y) (as a @ref{435a,,Vec2D} vector).

@example
>>> turtle.pos()
(440.00,-0.00)
@end example
@end deffn

@geindex towards() (於 turtle 模組中)
@anchor{library/turtle turtle towards}@anchor{4308}
@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{4309}
@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{430a}
@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{430b}
@deffn {函式} turtle.heading ()

Return the turtle's current heading (value depends on the turtle mode, see
@ref{434b,,mode()}).

@example
>>> turtle.home()
>>> turtle.left(67)
>>> turtle.heading()
67.0
@end example
@end deffn

@geindex distance() (於 turtle 模組中)
@anchor{library/turtle turtle distance}@anchor{430c}
@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{435c}
@subsubsection Settings for measurement


@geindex degrees() (於 turtle 模組中)
@anchor{library/turtle turtle degrees}@anchor{430d}
@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{430e}
@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{435d}
@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{435e}
@subsubsection Drawing state


@geindex pendown() (於 turtle 模組中)
@geindex pd() (於 turtle 模組中)
@geindex down() (於 turtle 模組中)
@anchor{library/turtle turtle pendown}@anchor{430f}
@deffn {函式} turtle.pendown ()
@anchor{library/turtle turtle pd}@anchor{4310}
@deffnx {函式} turtle.pd ()
@anchor{library/turtle turtle down}@anchor{4311}
@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{4312}
@deffn {函式} turtle.penup ()
@anchor{library/turtle turtle pu}@anchor{4313}
@deffnx {函式} turtle.pu ()
@anchor{library/turtle turtle up}@anchor{4314}
@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{4315}
@deffn {函式} turtle.pensize (width=None)
@anchor{library/turtle turtle width}@anchor{4316}
@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{4317}
@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 @ref{4317,,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{4318}
@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{435f}
@subsubsection Color control


@geindex pencolor() (於 turtle 模組中)
@anchor{library/turtle turtle pencolor}@anchor{431a}
@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{434c,,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{431b}
@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{434c,,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))  # 為整數而非浮點數
>>> 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{4319}
@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{431a,,pencolor()} and
@ref{431b,,fillcolor()}.

@item @code{color(colorstring)}, @code{color((r,g,b))}, @code{color(r,g,b)}

Inputs as in @ref{431a,,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{434c,,colormode()}.

@node Filling,More drawing control,Color control,Pen control<2>
@anchor{library/turtle filling}@anchor{4360}
@subsubsection Filling


@c >>> turtle.home()

@geindex filling() (於 turtle 模組中)
@anchor{library/turtle turtle filling}@anchor{431c}
@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{2a3}
@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{42e6,,begin_fill()} before the
fill-block and @ref{42e7,,end_fill()} after the fill-block:

@example
>>> turtle.color("black", "red")
>>> turtle.begin_fill()
>>> turtle.circle(80)
>>> turtle.end_fill()
@end example


在 3.14 版被加入.

@end deffn

@geindex begin_fill() (於 turtle 模組中)
@anchor{library/turtle turtle begin_fill}@anchor{42e6}
@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{42e7}
@deffn {函式} turtle.end_fill ()

Fill the shape drawn after the last call to @ref{42e6,,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{4361}
@subsubsection More drawing control


@geindex reset() (於 turtle 模組中)
@anchor{library/turtle turtle reset}@anchor{431d}
@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{431e}
@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{431f}
@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{4362}
@subsubsection Turtle state


@menu
* Visibility:: 
* Appearance:: 

@end menu

@node Visibility,Appearance,,Turtle state
@anchor{library/turtle visibility}@anchor{4363}
@subsubsection Visibility


@geindex hideturtle() (於 turtle 模組中)
@geindex ht() (於 turtle 模組中)
@anchor{library/turtle turtle hideturtle}@anchor{4322}
@deffn {函式} turtle.hideturtle ()
@anchor{library/turtle turtle ht}@anchor{4323}
@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{4320}
@deffn {函式} turtle.showturtle ()
@anchor{library/turtle turtle st}@anchor{4321}
@deffnx {函式} turtle.st ()

Make the turtle visible.

@example
>>> turtle.showturtle()
@end example
@end deffn

@geindex isvisible() (於 turtle 模組中)
@anchor{library/turtle turtle isvisible}@anchor{4324}
@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{4364}
@subsubsection Appearance


@geindex shape() (於 turtle 模組中)
@anchor{library/turtle turtle shape}@anchor{4325}
@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{434f,,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{4326}
@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{4327,,shapesize()}.

@item 
"noresize": no adaption of the turtle's appearance takes place.
@end itemize

@code{resizemode("user")} is called by @ref{4327,,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{4327}
@deffn {函式} turtle.shapesize (stretch_wid=None, stretch_len=None, outline=None)
@anchor{library/turtle turtle turtlesize}@anchor{4328}
@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{4329}
@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{432a}
@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{927}
@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{432b}
@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{432c}
@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{4365}
@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{432e}
@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{432f}
@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{4366}
@subsubsection Special Turtle methods


@geindex poly() (於 turtle 模組中)
@anchor{library/turtle turtle poly}@anchor{2a4}
@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


在 3.14 版被加入.

@end deffn

@geindex begin_poly() (於 turtle 模組中)
@anchor{library/turtle turtle begin_poly}@anchor{4330}
@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{4331}
@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{4332}
@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{4333}
@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{4334}
@deffn {函式} turtle.getturtle ()
@anchor{library/turtle turtle getpen}@anchor{4335}
@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{4336}
@deffn {函式} turtle.getscreen ()

Return the @ref{4367,,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{4337}
@deffn {函式} turtle.setundobuffer (size)

@*參數: 
@code{size} -- 一個整數或 @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{4304,,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{4338}
@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{4368}@anchor{library/turtle compoundshapes}@anchor{4369}
@subsubsection Compound shapes


To use compound turtle shapes, which consist of several polygons of different
color, you must use the helper class @ref{436a,,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{436b,,addcomponent()} method.

舉例來說：

@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{436a,,Shape} class is used internally by the @ref{434f,,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{436c}
@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{436d}
@subsubsection Window control


@geindex bgcolor() (於 turtle 模組中)
@anchor{library/turtle turtle bgcolor}@anchor{433a}
@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{434c,,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{433b}
@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{433c}
@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{433d}
@deffn {函式} turtle.resetscreen ()

Reset all Turtles on the Screen to their initial state.
@end deffn

@geindex screensize() (於 turtle 模組中)
@anchor{library/turtle turtle screensize}@anchor{433e}
@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{433f}
@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)   # 一個一般的八邊形
@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{436e}
@subsubsection Animation control


@geindex no_animation() (於 turtle 模組中)
@anchor{library/turtle turtle no_animation}@anchor{2a5}
@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


在 3.14 版被加入.

@end deffn

@geindex delay() (於 turtle 模組中)
@anchor{library/turtle turtle delay}@anchor{4340}
@deffn {函式} turtle.delay (delay=None)

@*參數: 
@code{delay} -- 正整數


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.

可選引數：

@example
>>> screen.delay()
10
>>> screen.delay(5)
>>> screen.delay()
5
@end example
@end deffn

@geindex tracer() (於 turtle 模組中)
@anchor{library/turtle turtle tracer}@anchor{4341}
@deffn {函式} turtle.tracer (n=None, delay=None)

@*參數: 

@itemize *

@item 
@code{n} -- 非負整數

@item 
@code{delay} -- 非負整數
@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{4340,,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{4342}
@deffn {函式} turtle.update ()

Perform a TurtleScreen update. To be used when tracer is turned off.
@end deffn

另請參閱 RawTurtle/Turtle 的 @ref{4305,,speed()} 方法。

@node Using screen events,Input methods,Animation control,Methods of TurtleScreen/Screen and corresponding functions
@anchor{library/turtle using-screen-events}@anchor{436f}
@subsubsection Using screen events


@geindex listen() (於 turtle 模組中)
@anchor{library/turtle turtle listen}@anchor{4343}
@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 @ref{4343,,listen()} to the onclick method.
@end deffn

@geindex onkey() (於 turtle 模組中)
@geindex onkeyrelease() (於 turtle 模組中)
@anchor{library/turtle turtle onkey}@anchor{4344}
@deffn {函式} turtle.onkey (fun, key)
@anchor{library/turtle turtle onkeyrelease}@anchor{4345}
@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{4343,,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{4346}
@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{4343,,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{432d}
@deffn {函式} turtle.onclick (fun, btn=1, add=None)
@anchor{library/turtle turtle onscreenclick}@anchor{4347}
@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{4348}
@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{4349}
@deffn {函式} turtle.mainloop ()
@anchor{library/turtle turtle done}@anchor{434a}
@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{4370}
@subsubsection Input methods


@geindex textinput() (於 turtle 模組中)
@anchor{library/turtle turtle textinput}@anchor{1b78}
@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{1b79}
@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{4371}
@subsubsection Settings and special methods


@geindex mode() (於 turtle 模組中)
@anchor{library/turtle turtle mode}@anchor{434b}
@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 @ref{107,,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{434c}
@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{434d}
@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{434e}
@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{434f}
@deffn {函式} turtle.register_shape (name, shape=None)
@anchor{library/turtle turtle addshape}@anchor{4350}
@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{436a,,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{4351}
@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{4352}
@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{4353}
@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{4372}@anchor{library/turtle screenspecific}@anchor{4373}
@subsubsection Methods specific to Screen, not inherited from TurtleScreen


@geindex bye() (於 turtle 模組中)
@anchor{library/turtle turtle bye}@anchor{4354}
@deffn {函式} turtle.bye ()

Shut the turtlegraphics window.
@end deffn

@geindex exitonclick() (於 turtle 模組中)
@anchor{library/turtle turtle exitonclick}@anchor{4355}
@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{18d4}
@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


在 3.14 版被加入.

@end deffn

@geindex setup() (於 turtle 模組中)
@anchor{library/turtle turtle setup}@anchor{4356}
@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{4357}
@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,解釋<2>,Methods of TurtleScreen/Screen and corresponding functions,turtle --- 龜圖學 Turtle graphics
@anchor{library/turtle public-classes}@anchor{4374}
@subsubsection Public classes


@geindex RawTurtle (turtle 中的類別)
@geindex RawPen (turtle 中的類別)
@anchor{library/turtle turtle RawTurtle}@anchor{4375}
@deffn {類別} turtle.RawTurtle (canvas)
@anchor{library/turtle turtle RawPen}@anchor{4376}
@deffnx {類別} turtle.RawPen (canvas)

@*參數: 
@code{canvas} -- a @code{tkinter.Canvas}, a @ref{4377,,ScrolledCanvas} or a
@ref{4367,,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{4378}
@deffn {類別} turtle.Turtle

Subclass of RawTurtle, has the same interface but draws on a default
@ref{42ec,,Screen} object created automatically when needed for the first time.
@end deffn

@geindex TurtleScreen (turtle 中的類別)
@anchor{library/turtle turtle TurtleScreen}@anchor{4367}
@deffn {類別} turtle.TurtleScreen (cv)

@*參數: 
@code{cv} -- 一個 @code{tkinter.Canvas}


Provides screen oriented methods like @ref{433a,,bgcolor()} etc. that are described
above.
@end deffn

@geindex Screen (turtle 中的類別)
@anchor{library/turtle turtle Screen}@anchor{42ec}
@deffn {類別} turtle.Screen

Subclass of TurtleScreen, with @ref{4373,,four methods added}.
@end deffn

@geindex ScrolledCanvas (turtle 中的類別)
@anchor{library/turtle turtle ScrolledCanvas}@anchor{4377}
@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{436a}
@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{436b,,addcomponent()} method)

@end multitable


@geindex addcomponent() (turtle.Shape 的方法)
@anchor{library/turtle turtle Shape addcomponent}@anchor{436b}
@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
>>> 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

請見@ref{4369,,Compound shapes}。
@end deffn
@end deffn

@geindex Vec2D (turtle 中的類別)
@anchor{library/turtle turtle Vec2D}@anchor{435a}
@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} 向量加法

@item 
@code{a - b} 向量減法

@item 
@code{a * b} 內積

@item 
@code{k * a} and @code{a * k} multiplication with scalar

@item 
@code{abs(a)} a 的絕對值

@item 
@code{a.rotate(angle)} 旋轉
@end itemize
@end deffn

@node 解釋<2>,Help and configuration,Public classes,turtle --- 龜圖學 Turtle graphics
@anchor{library/turtle explanation}@anchor{4379}@anchor{library/turtle turtle-explanation}@anchor{42eb}
@subsubsection 解釋


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{4378,,Turtle} instance will automatically create a @ref{42ec,,Screen}
instance if one is not already present.

@code{Turtle} is a subclass of @ref{4375,,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{4377,,ScrolledCanvas}
or @ref{4367,,TurtleScreen}.

@ref{4367,,TurtleScreen} is the basic drawing surface for a
turtle. @ref{42ec,,Screen} is a subclass of @code{TurtleScreen}, and
includes @ref{4373,,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{4377,,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,解釋<2>,turtle --- 龜圖學 Turtle graphics
@anchor{library/turtle help-and-configuration}@anchor{437a}
@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{437b}
@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{acb,,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{437c}
@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{437d}
@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 @ref{107,,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{437e}
@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{4356,,Screen.setup}
method.

@item 
Line 5 and 6 correspond to the arguments of the method
@ref{433e,,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 @ref{107,,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{4355,,exitonclick()} to enter the
mainloop.
@end itemize

There can be a @code{turtle.cfg} file in the directory where @ref{107,,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{108}@anchor{library/turtle turtledemo-demo-scripts}@anchor{437f}
@subsubsection @code{turtledemo} --- Demo scripts


@geindex module; turtledemo

The @ref{108,,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 @ref{108,,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 @ref{107,,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 {xxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Name

@tab

描述

@tab

Features

@item

bytedesign

@tab

complex classical
turtle graphics pattern

@tab

@ref{4341,,tracer()}, delay,
@ref{4342,,update()}

@item

chaos

@tab

graphs Verhulst dynamics,
shows that computer's
computations can generate
results sometimes against the
common sense expectations

@tab

world coordinates

@item

clock

@tab

analog clock showing time
of your computer

@tab

turtles as clock's
hands, ontimer

@item

colormixer

@tab

experiment with r, g, b

@tab

@ref{432f,,ondrag()}

@item

forest

@tab

3 breadth-first trees

@tab

randomization

@item

fractalcurves

@tab

Hilbert & Koch curves

@tab

recursion

@item

lindenmayer

@tab

ethnomathematics
(indian kolams)

@tab

L-System

@item

minimal_hanoi

@tab

河內塔

@tab

Rectangular Turtles
as Hanoi discs
(shape, shapesize)

@item

nim

@tab

play the classical nim game
with three heaps of sticks
against the computer.

@tab

turtles as nimsticks,
event driven (mouse,
keyboard)

@item

paint

@tab

super minimalistic
drawing program

@tab

@ref{432d,,onclick()}

@item

peace

@tab

elementary

@tab

turtle: appearance
and animation

@item

penrose

@tab

aperiodic tiling with
kites and darts

@tab

@ref{4301,,stamp()}

@item

planet_and_moon

@tab

simulation of
gravitational system

@tab

compound shapes,
@ref{435a,,Vec2D}

@item

rosette

@tab

a pattern from the wikipedia
article on turtle graphics

@tab

@ref{4333,,clone()},
@ref{4304,,undo()}

@item

round_dance

@tab

dancing turtles rotating
pairwise in opposite
direction

@tab

compound shapes, clone
shapesize, tilt,
get_shapepoly, update

@item

sorting_animate

@tab

visual demonstration of
different sorting methods

@tab

simple alignment,
randomization

@item

tree

@tab

a (graphical) breadth
first tree (using generators)

@tab

@ref{4333,,clone()}

@item

two_canvases

@tab

simple design

@tab

turtles on two
canvases

@item

yinyang

@tab

another elementary example

@tab

@ref{42ff,,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{4380}
@subsubsection Changes since Python 2.6



@itemize -

@item 
The methods @ref{4341,,Turtle.tracer}, @ref{4353,,Turtle.window_width} and
@ref{4352,,Turtle.window_height} have been eliminated.
Methods with these names and functionality are now available only
as methods of @ref{42ec,,Screen}. The functions derived from these remain
available. (In fact already in Python 2.6 these methods were merely
duplications of the corresponding
@ref{4367,,TurtleScreen}/@ref{42ec,,Screen} methods.)

@item 
The method @code{Turtle.fill()} has been eliminated.
The behaviour of @ref{42e6,,begin_fill()} and @ref{42e7,,end_fill()}
have changed slightly: now every filling process must be completed with an
@code{end_fill()} call.

@item 
A method @ref{431c,,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{4381}
@subsubsection Changes since Python 3.0



@itemize -

@item 
The @ref{4378,,Turtle} methods @ref{4329,,shearfactor()}, @ref{432b,,shapetransform()} and
@ref{432c,,get_shapepoly()} have been added. Thus the full range of
regular linear transforms is now available for transforming turtle shapes.
@ref{927,,tiltangle()} has been enhanced in functionality: it now can
be used to get or set the tilt angle.

@item 
The @ref{42ec,,Screen} method @ref{4346,,onkeypress()} has been added as a complement to
@ref{4344,,onkey()}. As the latter binds actions to the key release event,
an alias: @ref{4345,,onkeyrelease()} was also added for it.

@item 
The method @ref{4349,,Screen.mainloop} has been added,
so there is no longer a need to use the standalone @ref{4349,,mainloop()} function
when working with @ref{42ec,,Screen} and @ref{4378,,Turtle} objects.

@item 
Two input methods have been added: @ref{1b78,,Screen.textinput} and
@ref{1b79,,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 開發工具,除錯與效能分析,以 Tk 打造圖形使用者介面 Graphical User Interfaces,Python 標準函式庫 Standard Library
@anchor{library/development doc}@anchor{4382}@anchor{library/development development}@anchor{4383}@anchor{library/development development-tools}@anchor{4384}@anchor{library/development translation-repo}@anchor{4385}
@section 開發工具


本章所描述的模組可以幫助你編寫軟體。例如 @ref{ba,,pydoc} 模組可以根據模組的內容生成文件；@ref{3e,,doctest} 和 @ref{10c,,unittest} 模組則包含編寫單元測試的框架，這些測試程式碼會自動執行並驗證輸出結果是否正確。

本章節所描述的模組列表為：

@menu
* typing: typing --- 支援型別提示. 支援型別提示
* pydoc: pydoc --- 文件產生器與線上幫助系統. 文件產生器與線上幫助系統
* Python 開發模式:: 
* doctest: doctest --- 測試互動式 Python 範例. 測試互動式 Python 範例
* unittest: unittest --- 單元測試框架. 單元測試框架
* unittest.mock — mock 物件函式庫: unittest mock — mock 物件函式庫. 
* unittest.mock: unittest mock --- 入門指南. 入門指南
* test: test --- Python 的回歸測試 regression tests 套件. Python 的回歸測試 (regression tests) 套件
* test.support: test support --- Python 測試套件的工具. Python 測試套件的工具
* test.support.socket_helper: test support socket_helper --- 用於 socket 測試的工具. 用於 socket 測試的工具
* test.support.script_helper: test support script_helper --- 用於 Python 執行測試的工具. 用於 Python 執行測試的工具
* test.support.bytecode_helper: test support bytecode_helper --- 用於測試位元組碼能正確產生的支援工具. 用於測試位元組碼能正確產生的支援工具
* test.support.threading_helper: test support threading_helper --- Utilities for threading tests. Utilities for threading tests
* test.support.os_helper: test support os_helper --- 用於 os 測試的工具. 用於 os 測試的工具
* test.support.import_helper: test support import_helper --- 用於 import 測試的工具. 用於 import 測試的工具
* test.support.warnings_helper: test support warnings_helper --- 用於 warnings 測試的工具. 用於 warnings 測試的工具

@end menu

@node typing --- 支援型別提示,pydoc --- 文件產生器與線上幫助系統,,開發工具
@anchor{library/typing doc}@anchor{4386}@anchor{library/typing typing-support-for-type-hints}@anchor{4387}
@subsection @code{typing} --- 支援型別提示


@c import typing
@c from dataclasses import dataclass
@c from typing import *

@geindex module; typing
@anchor{library/typing module-typing}@anchor{10a}

在 3.5 版被加入.


`原始碼：'Lib/typing.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/typing.py}

@cartouche
@quotation 備註 
Python runtime 不強制要求函式與變數的型別註釋。他們可以被第三方工具使用，如：@ref{56e,,型別檢查器}、IDE、linter 等。
@end quotation
@end cartouche


__________________________________________________________________


此模組提供 runtime 型別提示支援。

動腦筋思考下面的函式：

@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

函式 @code{surface_area_of_cube} 需要一個引數且預期是一個 @ref{196,,float} 的實例，如 @code{edge_length: float} 所指出的@ref{227d,,型別提示}。這個函式預期會回傳一個 @ref{169,,str} 的實例，如 @code{-> str} 所指出的提示。

儘管型別提示可以是簡單類別，像是 @ref{196,,float} 或 @ref{169,,str}，他們也可以變得更為複雜。模組 @ref{10a,,typing} 提供一組更高階的型別提示詞彙。

新功能會頻繁的新增至 @code{typing} 模組中。typing_extensions@footnote{https://pypi.org/project/typing_extensions/} 套件為這些新功能提供了 backport（向後移植的）版本，提供給舊版本的 Python 使用。


@subsubheading 也參考



@table @asis

@item 型別小抄 (Typing cheat sheet)@footnote{https://mypy.readthedocs.io/en/stable/cheat_sheet_py3.html}

型別提示的快速預覽（發布於 mypy 的文件中）

@item mypy 文件@footnote{https://mypy.readthedocs.io/en/stable/index.html}的 型別系統參考資料 (Type System Reference) 章節

Python 的加註型別系統是基於 PEPs 進行標準化，所以這個參照 (reference) 應該在多數 Python 型別檢查器中廣為使用。（某些部分依然是特定給 mypy 使用。）

@item Python 的靜態型別 (Static Typing)@footnote{https://typing.python.org/en/latest/}

由社群編寫的跨平台型別檢查器文件 (type-checker-agnostic) 詳細描述加註型別系統的功能、實用的加註型別衍伸工具、以及加註型別的最佳實踐 (best practice)。
@end table


@menu
* Python 型別系統的技術規範:: 
* 型別別名:: 
* NewType:: 
* 註釋 callable 物件:: 
* 泛型:: 
* 註釋元組 (tuple): 註釋元組 tuple. 
* 類別物件的型別:: 
* Annotating generators and coroutines:: 
* 使用者定義泛型型別:: 
* Any 型別:: 
* 標稱 (nominal) 子型別 vs 結構子型別: 標稱 nominal 子型別 vs 結構子型別. 
* 模組內容: 模組內容<7>. 
* 主要功能的棄用時程表:: 

@end menu

@node Python 型別系統的技術規範,型別別名,,typing --- 支援型別提示
@anchor{library/typing relevant-peps}@anchor{4388}@anchor{library/typing specification-for-the-python-type-system}@anchor{4389}
@subsubsection Python 型別系統的技術規範


關於 Python 型別系統標準的 (canonical)、最新的技術規範可以在Python 型別系統的技術規範@footnote{https://typing.python.org/en/latest/spec/index.html}找到。

@node 型別別名,NewType,Python 型別系統的技術規範,typing --- 支援型別提示
@anchor{library/typing id2}@anchor{438a}@anchor{library/typing type-aliases}@anchor{67c}
@subsubsection 型別別名


一個型別別名被定義來使用 @ref{665,,type} 陳述式，其建立了 @ref{2ae,,TypeAliasType} 的實例。在這個範例中，@code{Vector} 及 @code{list[float]} 會被當作和靜態型別檢查器一樣同等對待：

@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

型別別名對於簡化複雜的型別簽名 (complex type signature) 非常好用。舉例來說：

@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

@ref{665,,type} 陳述式是 Python 3.12 的新功能。為了向後相容性，型別別名可以透過簡單的賦值來建立：

@example
Vector = list[float]
@end example

或是用 @ref{9c5,,TypeAlias} 標記，讓它明確的表示這是一個型別別名，而非一般的變數賦值：

@example
from typing import TypeAlias

Vector: TypeAlias = list[float]
@end example

@node NewType,註釋 callable 物件,型別別名,typing --- 支援型別提示
@anchor{library/typing distinct}@anchor{438b}@anchor{library/typing newtype}@anchor{438c}
@subsubsection NewType


使用 @ref{eec,,NewType} 輔助工具 (helper) 建立獨特型別：

@example
from typing import NewType

UserId = NewType('UserId', int)
some_id = UserId(524313)
@end example

若它是原本型別的子類別，靜態型別檢查器會將其視為一個新的型別。這對於幫助擷取邏輯性錯誤非常有用：

@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

你依然可以在對於型別 @code{UserId} 的變數中執行所有 @code{int} 的操作。這讓你可以在預期接受 @code{int} 的地方傳遞一個 @code{UserId}，還能預防你意外使用無效的方法建立一個 @code{UserId}：

@example
# 'output' is of type 'int', not 'UserId'
output = UserId(23413) + UserId(54341)
@end example

注意這只會透過靜態型別檢查器強制檢查。在 runtime 中，陳述式 (statement) @code{Derived = NewType('Derived', Base)} 會使 @code{Derived} 成為一個 callable（可呼叫物件），會立即回傳任何你傳遞的引數。這意味著 expression （運算式）@code{Derived(some_value)} 不會建立一個新的類別或過度引入原有的函式呼叫。

更精確地說，expression @code{some_value is Derived(some_value)} 在 runtime 永遠為 true。

這會無法建立一個 @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

無論如何，這有辦法基於 '衍生的' @code{NewType} 建立一個 @ref{eec,,NewType}：

@example
from typing import NewType

UserId = NewType('UserId', int)

ProUserId = NewType('ProUserId', UserId)
@end example

以及針對 @code{ProUserId} 的型別檢查會如期運作。

更多細節請見 
@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/}。

@cartouche
@quotation 備註 
請記得使用型別別名是宣告兩種型別是互相`相等'的。使用 @code{type Alias = Original} 則會讓靜態型別檢查器在任何情況之下將 @code{Alias} 視為與 @code{Original} `完全相等'。這當你想把複雜的型別簽名進行簡化時，非常好用。

相反的，@code{NewType} 宣告一個型別會是另外一種型別的子類別。使用 @code{Derived = NewType('Derived', Original)} 會使靜態型別檢查器將 @code{Derived} 視為 @code{Original} 的子類別，也意味著一個型別為 @code{Original} 的值，不能被使用在任何預期接收到型別 @code{Derived} 的值的區域。這當你想用最小的 runtime 成本預防邏輯性錯誤而言，非常有用。
@end quotation
@end cartouche


在 3.5.2 版被加入.



在 3.10 版的變更: 現在的 @code{NewType} 比起一個函式更像一個類別。因此，比起一般的函式，呼叫 @code{NewType} 需要額外的 runtime 成本。



在 3.11 版的變更: 呼叫 @code{NewType} 的效能已經恢復與 Python 3.9 相同的水準。


@node 註釋 callable 物件,泛型,NewType,typing --- 支援型別提示
@anchor{library/typing annotating-callable-objects}@anchor{438d}@anchor{library/typing annotating-callables}@anchor{2579}
@subsubsection 註釋 callable 物件


函式，或者是其他 @ref{2c2e,,callable} 物件，可以使用 @ref{9e4,,collections.abc.Callable} 或以棄用的 @ref{9c1,,typing.Callable} 進行註釋。 @code{Callable[[int], str]} 象徵為一個函式，可以接受一個型別為 @ref{19b,,int} 的引數，並回傳一個 @ref{169,,str}。

舉例來說：

@example
from collections.abc import Callable, Awaitable

def feeder(get_next_item: Callable[[], str]) -> None:
    ...  # 主體

def async_query(on_success: Callable[[int], None],
                on_error: Callable[[int, Exception], None]) -> None:
    ...  # 主體

async def on_update(value: str) -> None:
    ...  # 主體

callback: Callable[[str], Awaitable[None]] = on_update
@end example

@geindex ...;ellipsis literal

使用下標語法 (subscription syntax) 時，必須使用到兩個值，分別為引述串列以及回傳類別。引數串列必須為一個型別串列：@ref{482,,ParamSpec}、@ref{9c0,,Concatenate} 或是一個刪節號 (ellipsis, @code{...})。回傳類別必為一個單一類別。

若刪節號字面值 @code{...} 被當作引數串列給定，其指出一個具任何、任意參數列表的 callable 會被接受：

@example
def concat(x: str, y: str) -> str:
    return x + y

x: Callable[..., str]
x = str     # OK
x = concat  # 也 OK
@end example

@code{Callable} 不如有可變數量引數的函式、@ref{438e,,overloaded functions}、或是僅限關鍵字參數的函式，可以表示複雜簽名。然而，這些簽名可以透過定義一個具有 @ref{773,,__call__()} 方法的 @ref{565,,Protocol} 類別進行表示：

@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

Callable 物件可以取用其他 callable 當作引數使用，可以透過 @ref{482,,ParamSpec} 指出他們的參數型別是個別獨立的。另外，如果這個 callable 從其他 callable 新增或刪除引數時，將會使用到 @ref{9c0,,Concatenate} 運算子。他們可以分別採用 @code{Callable[ParamSpecVariable, ReturnType]} 以及 @code{Callable[Concatenate[Arg1Type, Arg2Type, ..., ParamSpecVariable], ReturnType]} 的形式。


在 3.10 版的變更: @code{Callable} 現已支援 @ref{482,,ParamSpec} 以及 @ref{9c0,,Concatenate}。請參閱 
@geindex Python Enhancement Proposals; PEP 612
PEP 612@footnote{https://peps.python.org/pep-0612/} 閱讀詳細內容。



@subsubheading 也參考


@ref{482,,ParamSpec} 以及 @ref{9c0,,Concatenate} 的文件中，提供範例如何在 @code{Callable} 中使用。


@node 泛型,註釋元組 tuple,註釋 callable 物件,typing --- 支援型別提示
@anchor{library/typing generics}@anchor{227b}@anchor{library/typing id3}@anchor{438f}
@subsubsection 泛型


因為關於物件的型別資訊留存在容器之內，且無法使用通用的方式進行靜態推論 (statically inferred)，許多標準函式庫的容器類別支援以下標來表示容器內預期的元素。

@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

泛型函式及類別可以使用@ref{5a7,,型別參數語法 (type parameter syntax)} 進行參數化 (parameterize) ：

@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

或是直接使用 @ref{481,,TypeVar} 工廠 (factory)：

@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 版的變更: 在 Python 3.12 中，泛型的語法支援是全新功能。


@node 註釋元組 tuple,類別物件的型別,泛型,typing --- 支援型別提示
@anchor{library/typing annotating-tuples}@anchor{257a}@anchor{library/typing id4}@anchor{4390}
@subsubsection 註釋元組 (tuple)


在 Python 大多數的容器當中，加註型別系統認為容器內的所有元素會是相同型別。舉例來說：

@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{24d,,list} 只接受一個型別引數，所以型別檢查器可能在上述 @code{y} 賦值 (assignment) 觸發錯誤。類似的範例，@ref{abe,,Mapping} 只接受兩個型別引數：第一個引數指出 keys（鍵）的型別；第二個引數指出 values（值）的型別。

然而，與其他多數的 Python 容器不同，在慣用的 (idiomatic) Python 程式碼中，元組可以擁有不完全相同型別的元素是相當常見的。為此，元組在 Python 的加註型別系統中是個特例 (special-cased)。@ref{60c,,tuple} 接受`任何數量'的型別引數：

@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

為了標示一個元組可以為`任意'長度，且所有元素皆是相同型別 @code{T}，請使用 刪節號字面值 (literal ellipsis) @code{...}：@code{tuple[T, ...]}。為了標示一個空元組，請使用 @code{tuple[()]}。單純使用 @code{tuple} 作為註釋會與使用 @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 類別物件的型別,Annotating generators and coroutines,註釋元組 tuple,typing --- 支援型別提示
@anchor{library/typing the-type-of-class-objects}@anchor{4391}@anchor{library/typing type-of-class-objects}@anchor{4392}
@subsubsection 類別物件的型別


一個變數被註釋為 @code{C} 可以接受一個型別為 @code{C} 的值。相對的，一個變數備註解為 @code{type[C]} （或已棄用的 @ref{4393,,typing.Type[C]}）可以接受本身為該類別的值 -- 具體來說，他可能會接受 @code{C} 的`類別物件'。舉例來說：

@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

請記得 @code{type[C]} 是共變 (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

@ref{f3f,,type} 僅有的合法參數是類別、@ref{8b3,,Any}、@ref{227b,,型別變數}以及這些型別任意組合成的聯集。舉例來說：

@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]} 等價於 @ref{f3f,,type} ，其為 Python @ref{2270,,metaclass 階層結構 (hierachy)}。

@node Annotating generators and coroutines,使用者定義泛型型別,類別物件的型別,typing --- 支援型別提示
@anchor{library/typing annotating-generators-and-coroutines}@anchor{284b}@anchor{library/typing id5}@anchor{4394}
@subsubsection Annotating generators and coroutines


A generator can be annotated using the generic type
@ref{fd6,,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{fd6,,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{2558,,Iterable[YieldType]}
or @ref{2559,,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{e82,,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{fda,,AsyncIterable[YieldType]}
and @ref{fd9,,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{fd8,,Coroutine[YieldType@comma{} SendType@comma{} ReturnType]}.
Generic arguments correspond to those of @ref{fd6,,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 使用者定義泛型型別,Any 型別,Annotating generators and coroutines,typing --- 支援型別提示
@anchor{library/typing user-defined-generic-types}@anchor{4395}@anchor{library/typing user-defined-generics}@anchor{6ef}
@subsubsection 使用者定義泛型型別


一個使用者定義的類別可以被定義成一個泛型類別。

@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

這個語法指出類別 @code{LoggedVar} 透過一個單一的 @ref{4396,,型別變數} @code{T} 進行參數化 (parameterised)。這使得 @code{T} 在類別中有效的成為型別。

泛型類別隱性繼承了 @ref{174e,,Generic}。為了相容 Python 3.11 及更早版本，也可以明確的繼承 @ref{174e,,Generic} 並指出是一個泛型類別：

@example
from typing import TypeVar, Generic

T = TypeVar('T')

class LoggedVar(Generic[T]):
    ...
@end example

泛型類別有 @ref{93b,,__class_getitem__()} 方法，其意味著可以在 runtime 進行參數化（如下述的 @code{LoggedVar[int]}）：

@example
from collections.abc import Iterable

def zero_all_vars(vars: Iterable[LoggedVar[int]]) -> None:
    for var in vars:
        var.set(0)
@end example

一個泛型型別可以有任意數量的型別變數。所有種類的 @ref{481,,TypeVar} 都可以作為泛型型別的參數：

@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

@ref{174e,,Generic} 的每個型別變數引數必不相同。因此以下是無效的：

@example
from typing import TypeVar, Generic
...

class Pair[M, M]:  # SyntaxError
    ...

T = TypeVar('T')

class Pair(Generic[T, T]):   # INVALID
    ...
@end example

泛型類別亦可以繼承其他類別：

@example
from collections.abc import Sized

class LinkedList[T](Sized):
    ...
@end example

當繼承泛型類別時，部份的型別參數可固定：

@example
from collections.abc import Mapping

class MyDict[T](Mapping[str, T]):
    ...
@end example

在這種情況下 @code{MyDict} 有一個單一的參數 @code{T}。

若使用泛型類別卻沒有特指型別參數，則會將每個位置視為 @ref{8b3,,Any}。在下列的範例中 @code{MyIterable} 不是泛型，但隱性繼承了 @code{Iterable[Any]}：

@example
from collections.abc import Iterable

class MyIterable(Iterable): # Same as Iterable[Any]
    ...
@end example

使用者定義的泛型型別別名也有支援。例如：

@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

為了向後相容性，泛型型別別名可以透過簡單的賦值來建立：

@example
from collections.abc import Iterable
from typing import TypeVar

S = TypeVar("S")
Response = Iterable[S] | int
@end example


在 3.7 版的變更: @ref{174e,,Generic} 不再是一個自訂的 metaclass。



在 3.12 版的變更: 在版本 3.12 新增了泛型及型別別名的語法支援。在之前的版本中，泛型類別必須顯性繼承 @ref{174e,,Generic} 或是包含一個型別變數在基底類別 (base) 當中。


使用者定義的參數運算式 (parameter expression) 泛型一樣有支援，透過 @code{[**P]} 格式的參數規格變數來進行表示。對於上述作為參數規格變數的型別變數，將持續被 @code{typing} 模組視為一個特定的型別變數。對此，其中一個例外是一個型別列表可以替代 @ref{482,,ParamSpec}：

@example
>>> class Z[T, **P]: ...  # T 為 TypeVar；P 為 ParamSpec
...
>>> Z[int, [dict, float]]
__main__.Z[int, [dict, float]]
@end example

具有 @ref{482,,ParamSpec} 的泛型類別可以透過顯性繼承 @ref{174e,,Generic} 進行建立。在這種情況下，不需要使用 @code{**}：

@example
from typing import ParamSpec, Generic

P = ParamSpec('P')

class Z(Generic[P]):
    ...
@end example

另外一個 @ref{481,,TypeVar} 以及 @ref{482,,ParamSpec} 之間的差異是，基於美觀因素，只有一個參數規格變數的泛型可以接受如 @code{X[[Type1, Type2, ...]]} 以及 @code{X[Type1, Type2, ...]} 的參數列表。在內部中，後者會被轉換為前者，所以在下方的範例中為相等的：

@example
>>> class X[**P]: ...
...
>>> X[int, str]
__main__.X[[int, str]]
>>> X[[int, str]]
__main__.X[[int, str]]
@end example

請記得，具有 @ref{482,,ParamSpec} 的泛型在某些情況下替換之後可能不會有正確的 @code{__parameters__}，因為參數規格主要還是用於靜態型別檢查。


在 3.10 版的變更: @ref{174e,,Generic} 現在可以透過參數運算式來進行參數化。詳細內容請見 @ref{482,,ParamSpec} 以及 
@geindex Python Enhancement Proposals; PEP 612
PEP 612@footnote{https://peps.python.org/pep-0612/}。


一個使用者定義的泛型類別可以將 ABC 作為他們的基底類別，且不會有 metaclass 衝突。泛型的 metaclass 則不支援。參數化泛型的輸出將被存為快取，而在 @code{typing} 模組中多數的型別皆為 @ref{81d,,hashable} 且可以比較相等性。

@node Any 型別,標稱 nominal 子型別 vs 結構子型別,使用者定義泛型型別,typing --- 支援型別提示
@anchor{library/typing the-any-type}@anchor{4397}
@subsubsection @code{Any} 型別


@ref{8b3,,Any} 是一種特別的型別。一個靜態型別檢查器會將每個型別視為可相容於 @ref{8b3,,Any} 且 @ref{8b3,,Any} 也可以相容於每個型別。

這意味著如果在一個為 @ref{8b3,,Any} 的值上執行任何操作或呼叫方法是可行的，且可以賦值給任意變數：

@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

請注意，當賦予型別為 @ref{8b3,,Any} 的值更精確的型別時，將不會執行任何型別檢查。舉例來說，靜態型別檢查器不會在 runtime 中，將 @code{a} 賦值給 @code{s} 的情況下回報錯誤，儘管 @code{s} 是被宣告為型別 @ref{169,,str} 卻接收到 @ref{19b,,int} 的值！

另外，所有缺少回傳型別或參數型別的函式將會隱性預設為 @ref{8b3,,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

當你需要混和動態及靜態的型別程式碼，這個行為允許 @ref{8b3,,Any} 被當作一個`緊急出口 (escape hatch)'使用。

@ref{8b3,,Any} 的行為對比 @ref{c75,,object} 的行為。與 @ref{8b3,,Any} 相似，所有的型別會作為 @ref{c75,,object} 的子型別。然而，不像 @ref{8b3,,Any}，反之不亦然：@ref{c75,,object} 並`不是'一個其他型別的子型別。

這意味著當一個值的型別為 @ref{c75,,object} 時，型別檢查器會拒絕幾乎所有的操作，並將賦予這個值到一個特定型別變數（或是當作回傳值使用）視為一個型別錯誤。舉例來說：

@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

使用 @ref{c75,,object} ，將指出在型別安全 (typesafe) 的習慣之下一個值可以為任意型別。使用 @ref{8b3,,Any}，將指出這個值是個動態型別。

@node 標稱 nominal 子型別 vs 結構子型別,模組內容<7>,Any 型別,typing --- 支援型別提示
@anchor{library/typing nominal-vs-structural-subtyping}@anchor{4398}
@subsubsection 標稱 (nominal) 子型別 vs 結構子型別


最初 
@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/} 定義 Python 靜態型別系統使用`標稱子型別'。這意味著只有 @code{A} 為 @code{B} 的子類別時，@code{A} 才被允許使用在預期是類別 @code{B} 出現的地方。

這個需求之前也被運用在抽象基底類別，例如 @ref{2558,,Iterable}。這種方式的問題在於，一個類別需要顯式的標記來支援他們，這並不符合 Python 風格，也不像一個常見的慣用動態型別 Python 程式碼。舉例來說，下列程式碼符合 
@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/} 可以透過使用上方的程式碼，且在類別定義時不用顯式基底類別解決這個問題，讓 @code{Bucket} 被靜態型別檢查器隱性認為是 @code{Sized} 以及 @code{Iterable[int]} 兩者的子型別。這就是眾所周知的`結構子型別'（或是靜態鴨子型別）：

@example
from collections.abc import Iterator, Iterable

class Bucket:  # 注意：沒有基底類別
    ...
    def __len__(self) -> int: ...
    def __iter__(self) -> Iterator[int]: ...

def collect(items: Iterable[int]) -> int: ...
result = collect(Bucket())  # Passes type check
@end example

而且，基於一個特別的型別  @ref{565,,Protocol} 建立子型別時，使用者可以定義新的協定並充份發揮結構子型別的優勢（請見下方範例）。

@node 模組內容<7>,主要功能的棄用時程表,標稱 nominal 子型別 vs 結構子型別,typing --- 支援型別提示
@anchor{library/typing module-contents}@anchor{4399}
@subsubsection 模組內容


模組 @code{typing} 定義了下列的類別、函式以及裝飾器。

@menu
* 特別型別原語 (primitive): 特別型別原語 primitive. 
* 協定: 協定<2>. 
* ABCs and Protocols for working with I/O:: 
* 函式與裝飾器:: 
* Introspection helpers:: 
* 常數: 常數<9>. 
* 棄用的別名:: 

@end menu

@node 特別型別原語 primitive,協定<2>,,模組內容<7>
@anchor{library/typing special-typing-primitives}@anchor{439a}
@subsubsection 特別型別原語 (primitive)


@menu
* 特別型別:: 
* 特別型式:: 
* Building generic types and type aliases:: 
* Other special directives:: 

@end menu

@node 特別型別,特別型式,,特別型別原語 primitive
@anchor{library/typing special-types}@anchor{439b}
@subsubsection 特別型別


這些可以在註釋中做為型別。他們並不支援 @code{[]} 的下標使用。

@geindex Any (於 typing 模組中)
@anchor{library/typing typing Any}@anchor{8b3}
@deffn {資料} typing.Any

特別型別，指出一個不受約束 (unconstrained) 的型別。


@itemize *

@item 
所有型別皆與 @ref{8b3,,Any} 相容。

@item 
@ref{8b3,,Any} 相容於所有型別。
@end itemize


在 3.11 版的變更: @ref{8b3,,Any} 可以作為一個基礎類別。這對於在任何地方使用鴨子型別或是高度動態的型別，避免型別檢查器的錯誤是非常有用的。

@end deffn

@geindex AnyStr (於 typing 模組中)
@anchor{library/typing typing AnyStr}@anchor{5a6}
@deffn {資料} typing.AnyStr

一個@ref{439c,,不受約束的型別變數}。

定義：

@example
AnyStr = TypeVar('AnyStr', str, bytes)
@end example

@code{AnyStr} 是對於函式有用的，他可以接受 @ref{169,,str} 或 @ref{192,,bytes} 引數但不可以將此兩種混合。

舉例來說：

@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

請注意，儘管他的名稱相近，@code{AnyStr} 與 @ref{8b3,,Any} 型別無關，更不代表是「任何字串」的意思。尤其，@code{AnyStr} 與 @code{str | bytes} 兩者不同且具有不同的使用情境：

@example
# Invalid use of AnyStr:
# The type variable is used only once in the function signature,
# so cannot be "solved" by the type checker
def greet_bad(cond: bool) -> AnyStr:
    return "hi there!" if cond else b"greetings!"

# The better way of annotating this function:
def greet_proper(cond: bool) -> str | bytes:
    return "hi there!" if cond else b"greetings!"
@end example


Deprecated since version 3.13, will be removed in version 3.18: Deprecated in favor of the new @ref{5a7,,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{7df}
@deffn {資料} typing.LiteralString

特別型別，只包含文本字串。

任何文本字串都相容於 @code{LiteralString}，對於另一個 @code{LiteralString} 亦是如此。然而，若是一個型別僅為 @code{str} 的物件則不相容。一個字串若是透過組合多個 @code{LiteralString} 型別的物件建立，則此字串也可以視為 @code{LiteralString}。

舉例來說：

@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} 對於敏感的 API 來說是有用的，其中任意的使用者產生的字串可能會產生問題。舉例來說，上面兩個案例中產生的型別檢查器錯誤是脆弱的且容易受到 SQL 注入攻擊。

更多細節請見 
@geindex Python Enhancement Proposals; PEP 675
PEP 675@footnote{https://peps.python.org/pep-0675/}。


在 3.11 版被加入.

@end deffn

@geindex Never (於 typing 模組中)
@geindex NoReturn (於 typing 模組中)
@anchor{library/typing typing Never}@anchor{8af}
@deffn {資料} typing.Never
@anchor{library/typing typing NoReturn}@anchor{439d}
@deffnx {資料} typing.NoReturn

@code{Never} 和 @code{NoReturn} 表示底部型別 (bottom type)@footnote{https://en.wikipedia.org/wiki/Bottom_type}，為一個沒有任何成員的型別。

它們可以被用來代表一個不會回傳的函式，像是 @ref{277,,sys.exit()}：

@example
from typing import Never  # 或 NoReturn

def stop() -> Never:
    raise RuntimeError('no way')
@end example

或被用來定義一個不應被呼叫的函式，因為不會有有效的引數，、像是 @ref{8ae,,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} 以及 @code{NoReturn} 在型別系統中具有相同的意義且靜態型別檢查器會將兩者視為相等。


在 3.6.2 版被加入: 新增 @ref{439d,,NoReturn}。



在 3.11 版被加入: 新增 @ref{8af,,Never}。

@end deffn

@geindex Self (於 typing 模組中)
@anchor{library/typing typing Self}@anchor{7dc}
@deffn {資料} typing.Self

特別型別，用來表示目前類別之內 (enclosed class)。

舉例來說：

@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

這個註釋在語意上相等於下列內容，且形式更為簡潔：

@example
from typing import TypeVar

Self = TypeVar("Self", bound="Foo")

class Foo:
    def return_self(self: Self) -> Self:
        ...
        return self
@end example

一般來說，如果某個東西回傳 @code{self} 如上方的範例所示，你則應該使用 @code{Self} 做為回傳值的註釋。若 @code{Foo.return_self} 被註釋為回傳 @code{"Foo"}，則型別檢查器應該推論這個從 @code{SubclassOfFoo.return_self} 回傳的物件為 @code{Foo} 型別，而並非回傳 @code{SubclassOfFoo} 型別。

其他常見的使用案例包含：


@itemize -

@item 
@ref{489,,classmethod} 被用來作為替代的建構函式 (constructor) 並回傳 @code{cls} 參數的實例。

@item 
註釋一個回傳自己的 @ref{7dd,,__enter__()} 方法。
@end itemize

當類別被子類別化時，若方法不保證回傳一個子類別的實例，你不應該使用 @code{Self} 作為回傳註釋：

@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

更多細節請見 
@geindex Python Enhancement Proposals; PEP 673
PEP 673@footnote{https://peps.python.org/pep-0673/}。


在 3.11 版被加入.

@end deffn

@geindex TypeAlias (於 typing 模組中)
@anchor{library/typing typing TypeAlias}@anchor{9c5}
@deffn {資料} typing.TypeAlias

做為明確宣告一個@ref{67c,,型別別名} 的特別註釋。

舉例來說：

@example
from typing import TypeAlias

Factors: TypeAlias = list[int]
@end example

@code{TypeAlias} 在舊的 Python 版本中特別有用，其註釋別名可以用來進行傳遞參照 (forward reference)，因為對於型別檢查器來說，分辨這些別名與一般的變數賦值相當困難：

@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

更多細節請見 
@geindex Python Enhancement Proposals; PEP 613
PEP 613@footnote{https://peps.python.org/pep-0613/}。


在 3.10 版被加入.



在 3.12 版之後被棄用: @ref{9c5,,TypeAlias} 被棄用，請改用 @ref{665,,type} 陳述式來建立 @ref{2ae,,TypeAliasType} 的實例，其自然可以支援傳遞參照的使用。請注意，雖然 @ref{9c5,,TypeAlias} 以及 @ref{2ae,,TypeAliasType} 提供相似的用途且具有相似的名稱，他們是不同的，且後者不是前者的型別。現在還沒有移除 @ref{9c5,,TypeAlias} 的計畫，但鼓勵使用者們遷移 (migrate) 至 @ref{665,,type} 陳述式。

@end deffn

@node 特別型式,Building generic types and type aliases,特別型別,特別型別原語 primitive
@anchor{library/typing special-forms}@anchor{439e}
@subsubsection 特別型式


這些在註釋中可以當作型別使用。他們全都支援 @code{[]} 的下標使用，但每個都具有獨特的語法。

@geindex Union (typing 中的類別)
@anchor{library/typing typing Union}@anchor{2a8}
@deffn {類別} typing.Union

聯集型別；@code{Union[X, Y]} 與 @code{X | Y} 是相等的，且都意味著 X 或 Y 兩者其一。

為了定義聯集，例如可以使用 @code{Union[int, str]} 或是使用簡寫 (shorthand) @code{int | str}。使用這種簡寫是非常推薦的。詳細請看：


@itemize *

@item 
引數必須為型別且必須有至少一個。

@item 
聯集中的聯集會是扁平化的 (flattened)，舉例來說：

@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{2ae,,TypeAliasType}:

@example
type A = Union[int, str]
Union[A, float] != Union[int, str, float]
@end example

@item 
單一引數的聯集會消失不見，舉例來說：

@example
Union[int] == int  # 實際上建構函式會回傳 int
@end example

@item 
多餘的引數會被略過，舉例來說：

@example
Union[int, str, int] == Union[int, str] == int | str
@end example

@item 
當比較聯集時，引數的順序會被忽略，舉例來說：

@example
Union[int, str] == Union[str, int]
@end example

@item 
你不能建立 @code{Union} 的子類別或是實例。

@item 
你不能寫成 @code{Union[X][Y]}。
@end itemize


在 3.7 版的變更: 請勿在 runtime 中將顯性子類別從聯集中移除。



在 3.10 版的變更: 現在可以將聯集寫成 @code{X | Y}。請見@ref{9be,,聯集型別運算式}。



在 3.14 版的變更: @ref{2a7,,types.UnionType} is now an alias for @ref{2a8,,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{8ba}
@deffn {資料} typing.Optional

@code{Optional[X]} 與 @code{X | None} 是相等的（或是 @code{Union[X, None]}）。

請注意，這與具有預設值的選擇性引數 (optional argument) 不是相同的概念。一個具有預設值的選擇性引數的型別註釋中不具有 @code{Optional} 限定符 (qualifier)，單純的因為它就是選擇性的。舉例來說：

@example
def foo(arg: int = 0) -> None:
    ...
@end example

另一方面，如果一個顯性的值 @code{None} 是被允許的，不論引數是不是選擇性的，@code{Optional} 都適用。舉例來說：

@example
def foo(arg: Optional[int] = None) -> None:
    ...
@end example


在 3.10 版的變更: 現在可以將 Optional 寫成 @code{X | None}。請見@ref{9be,,聯集型別運算式}。

@end deffn

@geindex Concatenate (於 typing 模組中)
@anchor{library/typing typing Concatenate}@anchor{9c0}
@deffn {資料} typing.Concatenate

用於註釋高階函式的特別型式。

@geindex ...;ellipsis literal

@code{Concatenate} 可以被用在@ref{2579,,可呼叫物件}與 @ref{482,,ParamSpec} 的接合 (conjunction) 並註釋一個高階的 Callable 物件可以新增、移除、轉換另一個 Callable 物件的參數。使用方法是依照這個格式 @code{Concatenate[Arg1Type, Arg2Type, ..., ParamSpecVariable]}。@code{Concatenate} 目前只在 @ref{2579,,Callable 物件}中第一個引數使用時有效。@code{Concatenate} 的最後一個參數必須為一個 @ref{482,,ParamSpec} 或是刪節號 (@code{...})。

舉例來說，註釋一個為裝飾過後的函式提供 @ref{1943,,threading.Lock} 的裝飾器 @code{with_lock}，@code{Concatenate} 可以用於指出 @code{with_lock} 預期一個 Callable 物件，該物件可以接受 @code{Lock} 作為第一引數，並回傳一個具有不同型別簽名 Callable 物件。在這種情況下，@ref{482,,ParamSpec} 指出回傳的 Callable 物件的參數型別會依賴傳遞的 Callable 物件的參數型別：

@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


在 3.10 版被加入.



@subsubheading 也參考



@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 612
PEP 612@footnote{https://peps.python.org/pep-0612/} -- 參數技術規範變數

@item 
@ref{482,,ParamSpec}

@item 
@ref{2579,,註釋 callable 物件}
@end itemize

@end deffn

@geindex Literal (於 typing 模組中)
@anchor{library/typing typing Literal}@anchor{a4e}
@deffn {資料} typing.Literal

特殊型別格式，用於定義「文本型別 (literal type)」。

@code{Literal} 可以用於型別檢查器並指出註釋物件具有一個與提供的文本相同的值。

舉例來說：

@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[...]} 不可以進行子類別化。在 runtime 之中，任意的值是允許作為 @code{Literal[...]} 的型別引數，但型別檢查器可能會加強限制。更多有關文本型別的詳細資訊請看 
@geindex Python Enhancement Proposals; PEP 586
PEP 586@footnote{https://peps.python.org/pep-0586/}。

其他細節：


@itemize *

@item 
引數必須為文本值且必須有至少一個。

@item 
巢狀的 @code{Literal} 會是扁平化的 (flattened)，舉例來說：

@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{2ae,,TypeAliasType}:

@example
type A = Literal[1, 2]
assert Literal[A, 3] != Literal[1, 2, 3]
@end example

@item 
多餘的引數會被略過，舉例來說：

@example
assert Literal[1, 2, 1] == Literal[1, 2]
@end example

@item 
當比較文本時，引數的順序會被忽略，舉例來說：

@example
assert Literal[1, 2] == Literal[2, 1]
@end example

@item 
你不能建立 @code{Literal} 的子類別或是實例。

@item 
你不能寫成 @code{Literal[X][Y]}。
@end itemize


在 3.8 版被加入.



在 3.9.1 版的變更: @code{Literal} 現在可以刪除重複 (de-deplicate) 的參數。@code{Literal} 物件的相等性比較不再依照相依性排序。@code{Literal} 物件現在會在相等性比較期間，若任一個其中的參數無法 @ref{81d,,hashable} 時，則會引發一個 @ref{198,,TypeError} 例外。

@end deffn

@geindex ClassVar (於 typing 模組中)
@anchor{library/typing typing ClassVar}@anchor{567}
@deffn {資料} typing.ClassVar

特殊型別建構，用來標記類別變數。

如同在 
@geindex Python Enhancement Proposals; PEP 526
PEP 526@footnote{https://peps.python.org/pep-0526/} 中的介紹，一個變數註解被包裝在 ClassVar 中時，會指出一個給定的屬性 (attribute) 意圖被當作類別變數使用，且不該被設定成該類別的實例。使用方法如下：

@example
class Starship:
    stats: ClassVar[dict[str, int]] = @{@} # 類別變數
    damage: int = 10                     # 實例變數
@end example

@ref{567,,ClassVar} 只接受型別請不得使用下標。

@ref{567,,ClassVar} 並不代表該類別本身，而且不應該和 @ref{2ad,,isinstance()} 或是 @ref{9bd,,issubclass()} 一起使用。@ref{567,,ClassVar} 不會改變 Python runtime 的行為，但它可以被第三方的型別檢查器使用。舉例來說，一個型別檢查器可能會標記下方的程式碼為一個錯誤：

@example
enterprise_d = Starship(3000)
enterprise_d.stats = @{@} # Error, setting class variable on instance
Starship.stats = @{@}     # This is OK
@end example


在 3.5.3 版被加入.



在 3.13 版的變更: @ref{567,,ClassVar} can now be nested in @ref{568,,Final} and vice versa.

@end deffn

@geindex Final (於 typing 模組中)
@anchor{library/typing typing Final}@anchor{568}
@deffn {資料} typing.Final

特殊型別建構，用來指出給型別檢查器的最終名稱。

最終名稱不可以在任何作用域 (scope) 中重新賦值。在類別作用域中宣告的最終名稱，不得在子類別中進行覆寫 (override)。

舉例來說：

@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

這些屬性 (property) 不會在 runtime 時進行檢查。更多詳細資訊請看 
@geindex Python Enhancement Proposals; PEP 591
PEP 591@footnote{https://peps.python.org/pep-0591/}。


在 3.8 版被加入.



在 3.13 版的變更: @ref{568,,Final} can now be nested in @ref{567,,ClassVar} and vice versa.

@end deffn

@geindex Required (於 typing 模組中)
@anchor{library/typing typing Required}@anchor{7d9}
@deffn {資料} typing.Required

特殊型別建構，用來標記一個 @ref{331,,TypedDict} 鍵值是必須的。

主要用於 @code{total=False} 的 TypedDict。更多細節請見 @ref{331,,TypedDict} 與 
@geindex Python Enhancement Proposals; PEP 655
PEP 655@footnote{https://peps.python.org/pep-0655/}。


在 3.11 版被加入.

@end deffn

@geindex NotRequired (於 typing 模組中)
@anchor{library/typing typing NotRequired}@anchor{7da}
@deffn {資料} typing.NotRequired

特殊型別建構，用來標記一個 @ref{331,,TypedDict} 鍵值是可能消失的。

更多細節請見 @ref{331,,TypedDict} 與 
@geindex Python Enhancement Proposals; PEP 655
PEP 655@footnote{https://peps.python.org/pep-0655/}。


在 3.11 版被加入.

@end deffn

@geindex ReadOnly (於 typing 模組中)
@anchor{library/typing typing ReadOnly}@anchor{485}
@deffn {資料} typing.ReadOnly

特殊型別建構，用來標記一個 @ref{331,,TypedDict} 的項目是唯讀的。

舉例來說：

@example
class Movie(TypedDict):
   title: ReadOnly[str]
   year: int

def mutate_movie(m: Movie) -> None:
   m["year"] = 1999  # allowed
   m["title"] = "The Matrix"  # 型別檢查器錯誤
@end example

這些屬性 (property) 不會在 runtime 時進行檢查。

更多細節請見 @ref{331,,TypedDict} 與 
@geindex Python Enhancement Proposals; PEP 705
PEP 705@footnote{https://peps.python.org/pep-0705/}。


在 3.13 版被加入.

@end deffn

@geindex Annotated (於 typing 模組中)
@anchor{library/typing typing Annotated}@anchor{b2e}
@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{8bb,,@@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{2ad,,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  # 順序是有意義的
@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{2ae,,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{483,,TypeVarTuple}:

@example
type Variadic[*Ts] = Annotated[*Ts, Ann1] = Annotated[T1, T2, T3, ..., Ann1]  # 無效
@end example

where @code{T1}, @code{T2}, ... are @ref{481,,TypeVars}. This is invalid as
only one type should be passed to Annotated.

By default, @ref{8b9,,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{2ab,,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



在 3.9 版被加入.

@end deffn

@geindex TypeIs (於 typing 模組中)
@anchor{library/typing typing TypeIs}@anchor{486}
@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{487,,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 
回傳值是一個布林值。

@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

舉例來說：

@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}).


在 3.13 版被加入.

@end deffn

@geindex TypeGuard (於 typing 模組中)
@anchor{library/typing typing TypeGuard}@anchor{487}
@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{486,,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 
回傳值是一個布林值。

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

舉例來說：

@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} 和 @code{TypeGuard} 在以下幾個方面有所不同：


@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


在 3.10 版被加入.

@end deffn

@geindex Unpack (於 typing 模組中)
@anchor{library/typing typing Unpack}@anchor{18fd}
@deffn {資料} typing.Unpack

Typing operator to conceptually mark an object as having been unpacked.

For example, using the unpack operator @code{*} on a
@ref{439f,,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{483,,typing.TypeVarTuple} and
@ref{60c,,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{331,,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.


在 3.11 版被加入.

@end deffn

@node Building generic types and type aliases,Other special directives,特別型式,特別型別原語 primitive
@anchor{library/typing building-generic-types-and-type-aliases}@anchor{43a0}
@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{5a7,,type parameter lists} and the @ref{665,,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{174e}
@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{67a,,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{67b,,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{4396}@anchor{library/typing typing TypeVar}@anchor{481}
@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{67b,,generic functions},
@ref{67a,,generic classes}, and
@ref{67d,,generic type aliases}:

@example
class Sequence[T]:  # T 是一個 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')  # 可以是任何東西
S = TypeVar('S', bound=str)  # 可以是任何 str 的子型別
A = TypeVar('A', str, bytes)  # 必須是 str 或 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{174e,,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{5a7,,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{439c}
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

在 runtime @code{isinstance(x, T)} 會引發 @ref{198,,TypeError}。

@geindex __name__ (typing.TypeVar 的屬性)
@anchor{library/typing typing TypeVar __name__}@anchor{43a1}
@deffn {屬性} __name__

The name of the type variable.
@end deffn

@geindex __covariant__ (typing.TypeVar 的屬性)
@anchor{library/typing typing TypeVar __covariant__}@anchor{43a2}
@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{43a3}
@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{43a4}
@deffn {屬性} __infer_variance__

Whether the type variable's variance should be inferred by type checkers.


在 3.12 版被加入.

@end deffn

@geindex __bound__ (typing.TypeVar 的屬性)
@anchor{library/typing typing TypeVar __bound__}@anchor{43a5}
@deffn {屬性} __bound__

The upper bound of the type variable, if any.


在 3.12 版的變更: For type variables created through @ref{5a7,,type parameter syntax},
the bound is evaluated only when the attribute is accessed, not when
the type variable is created (see @ref{67e,,Lazy evaluation}).

@end deffn

@geindex evaluate_bound() (typing.TypeVar 的方法)
@anchor{library/typing typing TypeVar evaluate_bound}@anchor{43a6}
@deffn {方法} evaluate_bound ()

An @ref{43a7,,evaluate function} corresponding to the @ref{43a5,,__bound__} attribute.
When called directly, this method supports only the @ref{15e,,VALUE}
format, which is equivalent to accessing the @ref{43a5,,__bound__} attribute directly,
but the method object can be passed to @ref{43a8,,annotationlib.call_evaluate_function()}
to evaluate the value in a different format.


在 3.14 版被加入.

@end deffn

@geindex __constraints__ (typing.TypeVar 的屬性)
@anchor{library/typing typing TypeVar __constraints__}@anchor{43a9}
@deffn {屬性} __constraints__

A tuple containing the constraints of the type variable, if any.


在 3.12 版的變更: For type variables created through @ref{5a7,,type parameter syntax},
the constraints are evaluated only when the attribute is accessed, not when
the type variable is created (see @ref{67e,,Lazy evaluation}).

@end deffn

@geindex evaluate_constraints() (typing.TypeVar 的方法)
@anchor{library/typing typing TypeVar evaluate_constraints}@anchor{43aa}
@deffn {方法} evaluate_constraints ()

An @ref{43a7,,evaluate function} corresponding to the @ref{43a9,,__constraints__} attribute.
When called directly, this method supports only the @ref{15e,,VALUE}
format, which is equivalent to accessing the @ref{43a9,,__constraints__} attribute directly,
but the method object can be passed to @ref{43a8,,annotationlib.call_evaluate_function()}
to evaluate the value in a different format.


在 3.14 版被加入.

@end deffn

@geindex __default__ (typing.TypeVar 的屬性)
@anchor{library/typing typing TypeVar __default__}@anchor{43ab}
@deffn {屬性} __default__

The default value of the type variable, or @ref{563,,typing.NoDefault} if it
has no default.


在 3.13 版被加入.

@end deffn

@geindex evaluate_default() (typing.TypeVar 的方法)
@anchor{library/typing typing TypeVar evaluate_default}@anchor{43ac}
@deffn {方法} evaluate_default ()

An @ref{43a7,,evaluate function} corresponding to the @ref{43ab,,__default__} attribute.
When called directly, this method supports only the @ref{15e,,VALUE}
format, which is equivalent to accessing the @ref{43ab,,__default__} attribute directly,
but the method object can be passed to @ref{43a8,,annotationlib.call_evaluate_function()}
to evaluate the value in a different format.


在 3.14 版被加入.

@end deffn

@geindex has_default() (typing.TypeVar 的方法)
@anchor{library/typing typing TypeVar has_default}@anchor{43ad}
@deffn {方法} has_default ()

Return whether or not the type variable has a default value. This is equivalent
to checking whether @ref{43ab,,__default__} is not the @ref{563,,typing.NoDefault}
singleton, except that it does not force evaluation of the
@ref{67e,,lazily evaluated} default value.


在 3.13 版被加入.

@end deffn


在 3.12 版的變更: Type variables can now be declared using the
@ref{5a7,,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 版的變更: 新增對預設值的支援。

@end deffn

@geindex TypeVarTuple (typing 中的類別)
@anchor{library/typing typevartuple}@anchor{439f}@anchor{library/typing typing TypeVarTuple}@anchor{483}
@deffn {類別} typing.TypeVarTuple (name, *, default=typing.NoDefault)

Type variable tuple. A specialized form of @ref{4396,,type variable}
that enables `variadic' generics.

Type variable tuples can be declared in @ref{5a7,,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{18fd,,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          # 無效
x: tuple[Ts]   # 無效
x: tuple[*Ts]  # 正確的做法
@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]            # 無效
class Array[*Shape, *Shape]:  # 無效
    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{43ae}
@deffn {屬性} __name__

The name of the type variable tuple.
@end deffn

@geindex __default__ (typing.TypeVarTuple 的屬性)
@anchor{library/typing typing TypeVarTuple __default__}@anchor{43af}
@deffn {屬性} __default__

The default value of the type variable tuple, or @ref{563,,typing.NoDefault} if it
has no default.


在 3.13 版被加入.

@end deffn

@geindex evaluate_default() (typing.TypeVarTuple 的方法)
@anchor{library/typing typing TypeVarTuple evaluate_default}@anchor{43b0}
@deffn {方法} evaluate_default ()

An @ref{43a7,,evaluate function} corresponding to the @ref{43af,,__default__} attribute.
When called directly, this method supports only the @ref{15e,,VALUE}
format, which is equivalent to accessing the @ref{43af,,__default__} attribute directly,
but the method object can be passed to @ref{43a8,,annotationlib.call_evaluate_function()}
to evaluate the value in a different format.


在 3.14 版被加入.

@end deffn

@geindex has_default() (typing.TypeVarTuple 的方法)
@anchor{library/typing typing TypeVarTuple has_default}@anchor{43b1}
@deffn {方法} has_default ()

Return whether or not the type variable tuple has a default value. This is equivalent
to checking whether @ref{43af,,__default__} is not the @ref{563,,typing.NoDefault}
singleton, except that it does not force evaluation of the
@ref{67e,,lazily evaluated} default value.


在 3.13 版被加入.

@end deffn


在 3.11 版被加入.



在 3.12 版的變更: Type variable tuples can now be declared using the
@ref{5a7,,type parameter} syntax introduced by 
@geindex Python Enhancement Proposals; PEP 695
PEP 695@footnote{https://peps.python.org/pep-0695/}.



在 3.13 版的變更: 新增對預設值的支援。

@end deffn

@geindex ParamSpec (typing 中的類別)
@anchor{library/typing typing ParamSpec}@anchor{482}
@deffn {類別} typing.ParamSpec (name, *, bound=None, covariant=False, contravariant=False, default=typing.NoDefault)

Parameter specification variable.  A specialized version of
@ref{4396,,type variables}.

In @ref{5a7,,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{174e,,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{481,,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{8b3,,Any}.

@item 
@ref{43b2,,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{43b3}
@deffn {屬性} args
@end deffn

@geindex kwargs (typing.ParamSpec 的屬性)
@anchor{library/typing typing ParamSpec kwargs}@anchor{43b4}
@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{9c2,,ParamSpecArgs} and @ref{9c3,,ParamSpecKwargs}.
@end deffn

@geindex __name__ (typing.ParamSpec 的屬性)
@anchor{library/typing typing ParamSpec __name__}@anchor{43b5}
@deffn {屬性} __name__

The name of the parameter specification.
@end deffn

@geindex __default__ (typing.ParamSpec 的屬性)
@anchor{library/typing typing ParamSpec __default__}@anchor{43b6}
@deffn {屬性} __default__

The default value of the parameter specification, or @ref{563,,typing.NoDefault} if it
has no default.


在 3.13 版被加入.

@end deffn

@geindex evaluate_default() (typing.ParamSpec 的方法)
@anchor{library/typing typing ParamSpec evaluate_default}@anchor{43b7}
@deffn {方法} evaluate_default ()

An @ref{43a7,,evaluate function} corresponding to the @ref{43b6,,__default__} attribute.
When called directly, this method supports only the @ref{15e,,VALUE}
format, which is equivalent to accessing the @ref{43b6,,__default__} attribute directly,
but the method object can be passed to @ref{43a8,,annotationlib.call_evaluate_function()}
to evaluate the value in a different format.


在 3.14 版被加入.

@end deffn

@geindex has_default() (typing.ParamSpec 的方法)
@anchor{library/typing typing ParamSpec has_default}@anchor{43b8}
@deffn {方法} has_default ()

Return whether or not the parameter specification has a default value. This is equivalent
to checking whether @ref{43b6,,__default__} is not the @ref{563,,typing.NoDefault}
singleton, except that it does not force evaluation of the
@ref{67e,,lazily evaluated} default value.


在 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{481,,TypeVar}.  However the actual semantics of these keywords are yet to
be decided.


在 3.10 版被加入.



在 3.12 版的變更: Parameter specifications can now be declared using the
@ref{5a7,,type parameter} syntax introduced by 
@geindex Python Enhancement Proposals; PEP 695
PEP 695@footnote{https://peps.python.org/pep-0695/}.



在 3.13 版的變更: 新增對預設值的支援。


@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/} -- 參數技術規範變數

@item 
@ref{9c0,,Concatenate}

@item 
@ref{2579,,註釋 callable 物件}
@end itemize

@end deffn

@geindex ParamSpecArgs (於 typing 模組中)
@geindex ParamSpecKwargs (於 typing 模組中)
@anchor{library/typing typing ParamSpecArgs}@anchor{9c2}
@deffn {資料} typing.ParamSpecArgs
@anchor{library/typing typing ParamSpecKwargs}@anchor{9c3}
@deffnx {資料} typing.ParamSpecKwargs

Arguments and keyword arguments attributes of a @ref{482,,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{2ab,,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


在 3.10 版被加入.

@end deffn

@geindex TypeAliasType (typing 中的類別)
@anchor{library/typing typing TypeAliasType}@anchor{2ae}
@deffn {類別} typing.TypeAliasType (name, value, *, type_params=())

The type of type aliases created through the @ref{665,,type} statement.

舉例來說：

@example
>>> type Alias = int
>>> type(Alias)
<class 'typing.TypeAliasType'>
@end example


在 3.12 版被加入.


@geindex __name__ (typing.TypeAliasType 的屬性)
@anchor{library/typing typing TypeAliasType __name__}@anchor{43b9}
@deffn {屬性} __name__

The name of the type alias:

@example
>>> type Alias = int
>>> Alias.__name__
'Alias'
@end example
@end deffn

@geindex __module__ (typing.TypeAliasType 的屬性)
@anchor{library/typing typing TypeAliasType __module__}@anchor{43ba}
@deffn {屬性} __module__

The name of the module in which the type alias was defined:

@example
>>> type Alias = int
>>> Alias.__module__
'__main__'
@end example
@end deffn

@geindex __type_params__ (typing.TypeAliasType 的屬性)
@anchor{library/typing typing TypeAliasType __type_params__}@anchor{43bb}
@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{43bc}
@deffn {屬性} __value__

The type alias's value. This is @ref{67e,,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{43bd}
@deffn {方法} evaluate_value ()

An @ref{43a7,,evaluate function} corresponding to the @ref{43bc,,__value__} attribute.
When called directly, this method supports only the @ref{15e,,VALUE}
format, which is equivalent to accessing the @ref{43bc,,__value__} attribute directly,
but the method object can be passed to @ref{43a8,,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


在 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


在 3.14 版被加入.

@end deffn

@node Other special directives,,Building generic types and type aliases,特別型別原語 primitive
@anchor{library/typing other-special-directives}@anchor{43be}
@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{330}
@deffn {類別} typing.NamedTuple

Typed version of @ref{4db,,collections.namedtuple()}.

用法：

@example
class Employee(NamedTuple):
    name: str
    id: int
@end example

這等價於：

@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{4db,,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.11 版的變更: Added support for generic namedtuples.



在 3.14 版的變更: Using @ref{1a6,,super()} (and the @code{__class__} @ref{180c,,closure variable}) in methods of @code{NamedTuple} subclasses
is unsupported and causes a @ref{198,,TypeError}.



Deprecated since version 3.13, will be removed in version 3.15: The undocumented keyword argument syntax for creating NamedTuple classes
(@code{NT = NamedTuple("NT", x=int)}) is deprecated, and will be disallowed
in 3.15. Use the class-based syntax or the functional syntax instead.



Deprecated since version 3.13, will be removed in version 3.15: When using the functional syntax to create a NamedTuple class, failing to
pass a value to the 'fields' parameter (@code{NT = NamedTuple("NT")}) is
deprecated. Passing @code{None} to the 'fields' parameter
(@code{NT = NamedTuple("NT", None)}) is also deprecated. Both will be
disallowed in Python 3.15. To create a NamedTuple class with 0 fields,
use @code{class NT(NamedTuple): pass} or @code{NT = NamedTuple("NT", [])}.

@end deffn

@geindex NewType (typing 中的類別)
@anchor{library/typing typing NewType}@anchor{eec}
@deffn {類別} typing.NewType (name, tp)

Helper class to create low-overhead @ref{438b,,distinct types}.

A @code{NewType} is considered a distinct type by a typechecker. At runtime,
however, calling a @code{NewType} returns its argument unchanged.

用法：

@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{43bf}
@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{43c0}
@deffn {屬性} __name__

The name of the new type.
@end deffn

@geindex __supertype__ (typing.NewType 的屬性)
@anchor{library/typing typing NewType __supertype__}@anchor{43c1}
@deffn {屬性} __supertype__

The type that the new type is based on.
@end deffn


在 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{565}
@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{66d,,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{2ad,,isinstance()} or @ref{9bd,,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


在 3.8 版被加入.

@end deffn

@geindex runtime_checkable() (於 typing 模組中)
@anchor{library/typing typing runtime_checkable}@anchor{66d}
@deffn {函式} @@typing.runtime_checkable

Mark a protocol class as a runtime protocol.

Such a protocol can be used with @ref{2ad,,isinstance()} and @ref{9bd,,issubclass()}.
This allows a simple-minded structural check, very similar to "one trick ponies"
in @ref{1f,,collections.abc} such as @ref{2558,,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

This decorator raises @ref{198,,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{d72,,ssl.SSLObject}
is a class, therefore it passes an @ref{9bd,,issubclass()}
check against @ref{2579,,Callable}. However, the
@code{ssl.SSLObject.__init__} method exists only to raise a
@ref{198,,TypeError} with a more informative message, therefore making
it impossible to call (instantiate) @ref{d72,,ssl.SSLObject}.
@end quotation
@end cartouche

@cartouche
@quotation 備註 
An @ref{2ad,,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{6f2,,hasattr()} calls for structural checks in performance-sensitive
code.
@end quotation
@end cartouche


在 3.8 版被加入.



在 3.12 版的變更: The internal implementation of @ref{2ad,,isinstance()} checks against
runtime-checkable protocols now uses @ref{6b5,,inspect.getattr_static()}
to look up attributes (previously, @ref{6f2,,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{2ad,,isinstance()} checks comparing objects to the
protocol. See @ref{6f1,,What's new in Python 3.12}
for more details.

@end deffn

@geindex TypedDict (typing 中的類別)
@anchor{library/typing typing TypedDict}@anchor{331}
@deffn {類別} typing.TypedDict (dict)

Special construct to add type hints to a dictionary.
At runtime it is a plain @ref{183,,dict}.

@code{TypedDict} declares a dictionary type that expects all of its
instances to have a certain set of keys, where each key is
associated with a value of a consistent type. This expectation
is not checked at runtime but is only enforced by type checkers.
Usage:

@example
class Point2D(TypedDict):
    x: int
    y: int
    label: str

a: Point2D = @{'x': 1, 'y': 2, 'label': 'good'@}  # OK
b: Point2D = @{'z': 3, 'label': 'bad'@}           # Fails type check

assert Point2D(x=1, y=2, label='first') == dict(x=1, y=2, label='first')
@end example

An alternative way to create a @code{TypedDict} is by using
function-call syntax. The second argument must be a literal @ref{183,,dict}:

@example
Point2D = TypedDict('Point2D', @{'x': int, 'y': int, 'label': str@})
@end example

This functional syntax allows defining keys which are not valid
@ref{2164,,identifiers}, for example because they are
keywords or contain hyphens, or when key names must not be
@ref{1f6a,,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{7da,,NotRequired}:

@example
class Point2D(TypedDict):
    x: int
    y: int
    label: NotRequired[str]

# 替代語法
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

# 替代語法
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{7d9,,Required}:

@example
class Point2D(TypedDict, total=False):
    x: Required[int]
    y: Required[int]
    label: str

# 替代語法
Point2D = TypedDict('Point2D', @{
    'x': Required[int],
    'y': Required[int],
    'label': str
@}, total=False)
@end example

It is possible for a @code{TypedDict} type to inherit from one or more other @code{TypedDict} types
using the class-based syntax.
Usage:

@example
class Point3D(Point2D):
    z: int
@end example

@code{Point3D} has three items: @code{x}, @code{y} and @code{z}. It is equivalent to this
definition:

@example
class Point3D(TypedDict):
    x: int
    y: int
    z: int
@end example

A @code{TypedDict} cannot inherit from a non-@code{TypedDict} class,
except for @ref{174e,,Generic}. For example:

@example
class X(TypedDict):
    x: int

class Y(TypedDict):
    y: int

class Z(object): pass  # 一個非 TypedDict 的類別

class XY(X, Y): pass  # OK

class XZ(X, Z): pass  # 引發 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{174e,,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{9d2,,註釋 (annotation) 最佳實踐} for more information on annotations best practices),
@ref{43c2,,__total__}, @ref{43c3,,__required_keys__}, and @ref{43c4,,__optional_keys__}.

@geindex __total__ (typing.TypedDict 的屬性)
@anchor{library/typing typing TypedDict __total__}@anchor{43c2}
@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{7da,,NotRequired}, or it may inherit from another
@code{TypedDict} with @code{total=False}. Therefore, it is generally better to use
@ref{43c3,,__required_keys__} and @ref{43c4,,__optional_keys__} for introspection.
@end deffn

@geindex __required_keys__ (typing.TypedDict 的屬性)
@anchor{library/typing typing TypedDict __required_keys__}@anchor{43c3}
@deffn {屬性} __required_keys__


在 3.9 版被加入.

@end deffn

@geindex __optional_keys__ (typing.TypedDict 的屬性)
@anchor{library/typing typing TypedDict __optional_keys__}@anchor{43c4}
@deffn {屬性} __optional_keys__

@code{Point2D.__required_keys__} and @code{Point2D.__optional_keys__} return
@ref{7eb,,frozenset} objects containing required and non-required keys, respectively.

Keys marked with @ref{7d9,,Required} will always appear in @code{__required_keys__}
and keys marked with @ref{7da,,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


在 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

Support for @ref{485,,ReadOnly} is reflected in the following attributes:

@geindex __readonly_keys__ (typing.TypedDict 的屬性)
@anchor{library/typing typing TypedDict __readonly_keys__}@anchor{43c5}
@deffn {屬性} __readonly_keys__

A @ref{7eb,,frozenset} containing the names of all read-only keys. Keys
are read-only if they carry the @ref{485,,ReadOnly} qualifier.


在 3.13 版被加入.

@end deffn

@geindex __mutable_keys__ (typing.TypedDict 的屬性)
@anchor{library/typing typing TypedDict __mutable_keys__}@anchor{43c6}
@deffn {屬性} __mutable_keys__

A @ref{7eb,,frozenset} containing the names of all mutable keys. Keys
are mutable if they do not carry the @ref{485,,ReadOnly} qualifier.


在 3.13 版被加入.

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


在 3.8 版被加入.



在 3.11 版的變更: Added support for marking individual keys as @ref{7d9,,Required} or @ref{7da,,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{485,,ReadOnly} qualifier was added.



Deprecated since version 3.13, will be removed in version 3.15: When using the functional syntax to create a TypedDict class, failing to
pass a value to the 'fields' parameter (@code{TD = TypedDict("TD")}) is
deprecated. Passing @code{None} to the 'fields' parameter
(@code{TD = TypedDict("TD", None)}) is also deprecated. Both will be
disallowed in Python 3.15. To create a TypedDict class with 0 fields,
use @code{class TD(TypedDict): pass} or @code{TD = TypedDict("TD", @{@})}.

@end deffn

@node 協定<2>,ABCs and Protocols for working with I/O,特別型別原語 primitive,模組內容<7>
@anchor{library/typing protocols}@anchor{43c7}
@subsubsection 協定


The following protocols are provided by the @code{typing} module. All are decorated
with @ref{66d,,@@runtime_checkable}.

@geindex SupportsAbs (typing 中的類別)
@anchor{library/typing typing SupportsAbs}@anchor{43c8}
@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{7f7}
@deffn {類別} typing.SupportsBytes

一個有抽象方法 @code{__bytes__} 的 ABC。
@end deffn

@geindex SupportsComplex (typing 中的類別)
@anchor{library/typing typing SupportsComplex}@anchor{7f6}
@deffn {類別} typing.SupportsComplex

一個有抽象方法 @code{__complex__} 的 ABC。
@end deffn

@geindex SupportsFloat (typing 中的類別)
@anchor{library/typing typing SupportsFloat}@anchor{43c9}
@deffn {類別} typing.SupportsFloat

一個有抽象方法 @code{__float__} 的 ABC。
@end deffn

@geindex SupportsIndex (typing 中的類別)
@anchor{library/typing typing SupportsIndex}@anchor{c31}
@deffn {類別} typing.SupportsIndex

一個有抽象方法 @code{__index__} 的 ABC。


在 3.8 版被加入.

@end deffn

@geindex SupportsInt (typing 中的類別)
@anchor{library/typing typing SupportsInt}@anchor{c30}
@deffn {類別} typing.SupportsInt

一個有抽象方法 @code{__int__} 的 ABC。
@end deffn

@geindex SupportsRound (typing 中的類別)
@anchor{library/typing typing SupportsRound}@anchor{43ca}
@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,函式與裝飾器,協定<2>,模組內容<7>
@anchor{library/typing abcs-and-protocols-for-working-with-i-o}@anchor{43cb}@anchor{library/typing typing-io}@anchor{2fde}
@subsubsection ABCs and Protocols for working with I/O


@geindex IO (typing 中的類別)
@geindex TextIO (typing 中的類別)
@geindex BinaryIO (typing 中的類別)
@anchor{library/typing typing IO}@anchor{238}
@deffn {類別} typing.IO [AnyStr]
@anchor{library/typing typing TextIO}@anchor{239}
@deffnx {類別} typing.TextIO [AnyStr]
@anchor{library/typing typing BinaryIO}@anchor{23a}
@deffnx {類別} typing.BinaryIO [AnyStr]

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{315,,open()}. Please note that these classes are not protocols, and
their interface is fairly broad.
@end deffn

The protocols @ref{236,,io.Reader} and @ref{237,,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{2558,,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 函式與裝飾器,Introspection helpers,ABCs and Protocols for working with I/O,模組內容<7>
@anchor{library/typing functions-and-decorators}@anchor{43cc}
@subsubsection 函式與裝飾器


@geindex cast() (於 typing 模組中)
@anchor{library/typing typing cast}@anchor{43b2}
@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{8b2}
@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


在 3.11 版被加入.

@end deffn

@geindex assert_never() (於 typing 模組中)
@anchor{library/typing typing assert_never}@anchor{8ae}
@deffn {函式} typing.assert_never (arg, /)

Ask a static type checker to confirm that a line of code is unreachable.

舉例來說：

@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{19b,,int} or a @ref{169,,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{196,,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{8af,,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.



在 3.11 版被加入.

@end deffn

@geindex reveal_type() (於 typing 模組中)
@anchor{library/typing typing reveal_type}@anchor{8b1}
@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{b2a,,sys.stderr} and returns the argument unchanged (allowing the call to
be used within an expression):

@example
x = reveal_type(1)  # 印出 "Runtime type is int"
print(x)  # 印出 "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.


在 3.11 版被加入.

@end deffn

@geindex dataclass_transform() (於 typing 模組中)
@anchor{library/typing typing dataclass_transform}@anchor{6f4}
@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{4dc,,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{4dc,,@@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{4dc,,@@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{4dc,,@@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{3c1,,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{3c1,,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{3c1,,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{3c1,,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}.


在 3.12 版被加入.



@item 
@code{field_specifiers} (@ref{60c,,tuple}@code{[}@ref{9e4,,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{18c1,,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.

更多細節請見 
@geindex Python Enhancement Proposals; PEP 681
PEP 681@footnote{https://peps.python.org/pep-0681/}。


在 3.11 版被加入.

@end deffn

@geindex overload() (於 typing 模組中)
@anchor{library/typing overload}@anchor{43cd}@anchor{library/typing typing overload}@anchor{438e}
@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{369,,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):
    ...  # 實際的實作在這邊
@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{8b5,,get_overloads()}.

@end deffn

@geindex get_overloads() (於 typing 模組中)
@anchor{library/typing typing get_overloads}@anchor{8b5}
@deffn {函式} typing.get_overloads (func)

Return a sequence of @ref{438e,,@@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{438e,,@@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.


在 3.11 版被加入.

@end deffn

@geindex clear_overloads() (於 typing 模組中)
@anchor{library/typing typing clear_overloads}@anchor{8b6}
@deffn {函式} typing.clear_overloads ()

Clear all registered overloads in the internal registry.

This can be used to reclaim the memory used by the registry.


在 3.11 版被加入.

@end deffn

@geindex final() (於 typing 模組中)
@anchor{library/typing typing final}@anchor{8b4}
@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.

舉例來說：

@example
class Base:
    @@final
    def done(self) -> None:
        ...
class Sub(Base):
    def done(self) -> None:  # 型別檢查器回報的錯誤
        ...

@@final
class Leaf:
    ...
class Other(Leaf):  # 型別檢查器回報的錯誤
    ...
@end example

這些屬性 (property) 不會在 runtime 時進行檢查。更多詳細資訊請看 
@geindex Python Enhancement Proposals; PEP 591
PEP 591@footnote{https://peps.python.org/pep-0591/}。


在 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{8bb}
@deffn {函式} @@typing.no_type_check

Decorator to indicate that annotations are not type hints.

This works as a class or function @ref{932,,decorator}.  With a class, it
applies recursively to all methods and classes defined in that class
(but not to methods defined in its superclasses or subclasses). Type
checkers will ignore all annotations in a function or class with this
decorator.

@code{@@no_type_check} mutates the decorated object in place.
@end deffn

@geindex no_type_check_decorator() (於 typing 模組中)
@anchor{library/typing typing no_type_check_decorator}@anchor{332}
@deffn {函式} @@typing.no_type_check_decorator

Decorator to give another decorator the @ref{8bb,,no_type_check()} effect.

This wraps the decorator with something that wraps the decorated
function in @ref{8bb,,no_type_check()}.


Deprecated since version 3.13, will be removed in version 3.15: No type checker ever added support for @code{@@no_type_check_decorator}. It
is therefore deprecated, and will be removed in Python 3.15.

@end deffn

@geindex override() (於 typing 模組中)
@anchor{library/typing typing override}@anchor{675}
@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.

舉例來說：

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

更多細節請見 
@geindex Python Enhancement Proposals; PEP 698
PEP 698@footnote{https://peps.python.org/pep-0698/}。


在 3.12 版被加入.

@end deffn

@geindex type_check_only() (於 typing 模組中)
@anchor{library/typing typing type_check_only}@anchor{43ce}
@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,常數<9>,函式與裝飾器,模組內容<7>
@anchor{library/typing introspection-helpers}@anchor{43cf}
@subsubsection Introspection helpers


@geindex get_type_hints() (於 typing 模組中)
@anchor{library/typing typing get_type_hints}@anchor{8b9}
@deffn {函式} typing.get_type_hints (obj, globalns=None, localns=None, include_extras=False)

Return a dictionary containing type hints for a function, method, module
or class object.

This is often the same as @code{obj.__annotations__}, but this function makes
the following changes to the annotations dictionary:


@itemize *

@item 
Forward references encoded as string literals or @ref{1afa,,ForwardRef}
objects are handled by evaluating them in `globalns', `localns', and
(where applicable) `obj''s @ref{5a7,,type parameter} namespace.
If `globalns' or `localns' is not given, appropriate namespace
dictionaries are inferred from `obj'.

@item 
@code{None} is replaced with @ref{a4b,,types.NoneType}.

@item 
If @ref{8bb,,@@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{2229,,C.__mro__} and iteratively
combining
@code{__annotations__} dictionaries. Annotations on classes appearing
earlier in the @ref{248c,,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{b2e,,Annotated} for more information).
@end itemize

See also @ref{457,,annotationlib.get_annotations()}, a lower-level function that
returns annotations more directly.

@cartouche
@quotation 警示 
This function may execute arbitrary code contained in annotations.
See @ref{43d0,,Security implications of introspecting annotations} for more information.
@end quotation
@end cartouche

@cartouche
@quotation 備註 
If any forward references in the annotations of `obj' are not resolvable
or are not valid Python code, this function will raise an exception
such as @ref{450,,NameError}. For example, this can happen with imported
@ref{67c,,type aliases} that include forward references,
or with names imported under @ref{eeb,,if TYPE_CHECKING}.
@end quotation
@end cartouche


在 3.9 版的變更: 新增 @code{include_extras} 參數（如 
@geindex Python Enhancement Proposals; PEP 593
PEP 593@footnote{https://peps.python.org/pep-0593/} 中所述）。更多資訊請見 @ref{b2e,,Annotated} 的文件。



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

@end deffn

@geindex get_origin() (於 typing 模組中)
@anchor{library/typing typing get_origin}@anchor{2ab}
@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{9c2,,ParamSpecArgs} or @ref{9c3,,ParamSpecKwargs},
return the underlying @ref{482,,ParamSpec}.
Return @code{None} for unsupported objects.

舉例：

@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


在 3.8 版被加入.

@end deffn

@geindex get_args() (於 typing 模組中)
@anchor{library/typing typing get_args}@anchor{2ac}
@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{a4e,,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.

舉例：

@example
assert get_args(int) == ()
assert get_args(Dict[int, str]) == (int, str)
assert get_args(Union[int, str]) == (int, str)
@end example


在 3.8 版被加入.

@end deffn

@geindex get_protocol_members() (於 typing 模組中)
@anchor{library/typing typing get_protocol_members}@anchor{564}
@deffn {函式} typing.get_protocol_members (tp)

Return the set of members defined in a @ref{565,,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{198,,TypeError} for arguments that are not Protocols.


在 3.13 版被加入.

@end deffn

@geindex is_protocol() (於 typing 模組中)
@anchor{library/typing typing is_protocol}@anchor{566}
@deffn {函式} typing.is_protocol (tp)

確定一個型別是否 @ref{565,,Protocol}。

舉例來說：

@example
class P(Protocol):
    def a(self) -> str: ...
    b: int

is_protocol(P)    # => True
is_protocol(int)  # => False
@end example


在 3.13 版被加入.

@end deffn

@geindex is_typeddict() (於 typing 模組中)
@anchor{library/typing typing is_typeddict}@anchor{a4f}
@deffn {函式} typing.is_typeddict (tp)

Check if a type is a @ref{331,,TypedDict}.

舉例來說：

@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


在 3.10 版被加入.

@end deffn

@geindex ForwardRef (typing 中的類別)
@anchor{library/typing typing ForwardRef}@anchor{1afa}
@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


在 3.7.4 版被加入.



在 3.14 版的變更: This is now an alias for @ref{17d8,,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{1798}
@deffn {函式} typing.evaluate_forward_ref (forward_ref, *, owner=None, globals=None, locals=None, type_params=None, format=annotationlib.Format.VALUE)

Evaluate an @ref{17d8,,annotationlib.ForwardRef} as a @ref{227d,,type hint}.

This is similar to calling @ref{1785,,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{1785,,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{43d0,,Security implications of introspecting annotations} for more information.
@end quotation
@end cartouche


在 3.14 版被加入.

@end deffn

@geindex NoDefault (於 typing 模組中)
@anchor{library/typing typing NoDefault}@anchor{563}
@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


在 3.13 版被加入.

@end deffn

@node 常數<9>,棄用的別名,Introspection helpers,模組內容<7>
@anchor{library/typing constant}@anchor{43d1}
@subsubsection 常數


@geindex TYPE_CHECKING (於 typing 模組中)
@anchor{library/typing typing TYPE_CHECKING}@anchor{eeb}
@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.

用法：

@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{457,,annotationlib.get_annotations()} with a @code{format} parameter
of @ref{160,,annotationlib.Format.STRING} or
@ref{15f,,annotationlib.Format.FORWARDREF} to safely retrieve the
annotations without raising @ref{450,,NameError}.


在 3.5.2 版被加入.

@end deffn
@anchor{library/typing generic-concrete-collections}@anchor{43d2}
@node 棄用的別名,,常數<9>,模組內容<7>
@anchor{library/typing deprecated-aliases}@anchor{43d3}@anchor{library/typing id6}@anchor{43d4}
@subsubsection 棄用的別名


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
* 內建型別的別名:: 
* collections 中型別的別名:: 
* Aliases to other concrete types:: 
* collections.abc 中容器 ABC 的別名: collections abc 中容器 ABC 的別名. 
* collections.abc 中非同步 ABC 的別名: collections abc 中非同步 ABC 的別名. 
* Aliases to other ABCs in collections.abc: Aliases to other ABCs in collections abc. 
* contextlib ABC 的別名:: 

@end menu

@node 內建型別的別名,collections 中型別的別名,,棄用的別名
@anchor{library/typing aliases-to-built-in-types}@anchor{43d5}@anchor{library/typing corresponding-to-built-in-types}@anchor{43d6}
@subsubsection 內建型別的別名


@geindex Dict (typing 中的類別)
@anchor{library/typing typing Dict}@anchor{43d7}
@deffn {類別} typing.Dict (dict, MutableMapping[KT, VT])

棄用 @ref{183,,dict} 的別名。

Note that to annotate arguments, it is preferred
to use an abstract collection type such as @ref{abe,,Mapping}
rather than to use @ref{183,,dict} or @code{typing.Dict}.


在 3.9 版之後被棄用: @ref{183,,builtins.dict} now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{8b8,,泛型別名型別}.

@end deffn

@geindex List (typing 中的類別)
@anchor{library/typing typing List}@anchor{43d8}
@deffn {類別} typing.List (list, MutableSequence[T])

棄用 @ref{24d,,list} 的別名。

Note that to annotate arguments, it is preferred
to use an abstract collection type such as
@ref{13c5,,Sequence} or @ref{2558,,Iterable}
rather than to use @ref{24d,,list} or @code{typing.List}.


在 3.9 版之後被棄用: @ref{24d,,builtins.list} now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{8b8,,泛型別名型別}.

@end deffn

@geindex Set (typing 中的類別)
@anchor{library/typing typing Set}@anchor{43d9}
@deffn {類別} typing.Set (set, MutableSet[T])

棄用 @ref{184,,builtins.set} 的別名。

Note that to annotate arguments, it is preferred
to use an abstract collection type such as @ref{2550,,collections.abc.Set}
rather than to use @ref{184,,set} or @ref{43d9,,typing.Set}.


在 3.9 版之後被棄用: @ref{184,,builtins.set} now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{8b8,,泛型別名型別}.

@end deffn

@geindex FrozenSet (typing 中的類別)
@anchor{library/typing typing FrozenSet}@anchor{43da}
@deffn {類別} typing.FrozenSet (frozenset, AbstractSet[T_co])

棄用 @ref{7eb,,builtins.frozenset} 的別名。


在 3.9 版之後被棄用: @ref{7eb,,builtins.frozenset}
now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{8b8,,泛型別名型別}.

@end deffn

@geindex Tuple (於 typing 模組中)
@anchor{library/typing typing Tuple}@anchor{43db}
@deffn {資料} typing.Tuple

棄用 @ref{60c,,tuple} 的別名。

@ref{60c,,tuple} and @code{Tuple} are special-cased in the type system; see
@ref{257a,,註釋元組 (tuple)} for more details.


在 3.9 版之後被棄用: @ref{60c,,builtins.tuple} now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{8b8,,泛型別名型別}.

@end deffn

@geindex Type (typing 中的類別)
@anchor{library/typing typing Type}@anchor{4393}
@deffn {類別} typing.Type (Generic[CT_co])

棄用 @ref{f3f,,type} 的別名。

See @ref{4392,,類別物件的型別} for details on using @ref{f3f,,type} or
@code{typing.Type} in type annotations.


在 3.5.2 版被加入.



在 3.9 版之後被棄用: @ref{f3f,,builtins.type} now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{8b8,,泛型別名型別}.

@end deffn

@node collections 中型別的別名,Aliases to other concrete types,內建型別的別名,棄用的別名
@anchor{library/typing aliases-to-types-in-collections}@anchor{43dc}@anchor{library/typing corresponding-to-types-in-collections}@anchor{43dd}
@subsubsection @code{collections} 中型別的別名


@geindex DefaultDict (typing 中的類別)
@anchor{library/typing typing DefaultDict}@anchor{43de}
@deffn {類別} typing.DefaultDict (collections.defaultdict, MutableMapping[KT, VT])

棄用 @ref{13bd,,collections.defaultdict} 的別名。


在 3.5.2 版被加入.



在 3.9 版之後被棄用: @ref{13bd,,collections.defaultdict} now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{8b8,,泛型別名型別}.

@end deffn

@geindex OrderedDict (typing 中的類別)
@anchor{library/typing typing OrderedDict}@anchor{43df}
@deffn {類別} typing.OrderedDict (collections.OrderedDict, MutableMapping[KT, VT])

棄用 @ref{7ec,,collections.OrderedDict} 的別名。


在 3.7.2 版被加入.



在 3.9 版之後被棄用: @ref{7ec,,collections.OrderedDict} now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{8b8,,泛型別名型別}.

@end deffn

@geindex ChainMap (typing 中的類別)
@anchor{library/typing typing ChainMap}@anchor{43e0}
@deffn {類別} typing.ChainMap (collections.ChainMap, MutableMapping[KT, VT])

棄用 @ref{e11,,collections.ChainMap} 的別名。


在 3.6.1 版被加入.



在 3.9 版之後被棄用: @ref{e11,,collections.ChainMap} now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{8b8,,泛型別名型別}.

@end deffn

@geindex Counter (typing 中的類別)
@anchor{library/typing typing Counter}@anchor{43e1}
@deffn {類別} typing.Counter (collections.Counter, Dict[T, int])

棄用 @ref{1292,,collections.Counter} 的別名。


在 3.6.1 版被加入.



在 3.9 版之後被棄用: @ref{1292,,collections.Counter} now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{8b8,,泛型別名型別}.

@end deffn

@geindex Deque (typing 中的類別)
@anchor{library/typing typing Deque}@anchor{43e2}
@deffn {類別} typing.Deque (deque, MutableSequence[T])

棄用 @ref{7ed,,collections.deque} 的別名。


在 3.6.1 版被加入.



在 3.9 版之後被棄用: @ref{7ed,,collections.deque} now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{8b8,,泛型別名型別}.

@end deffn

@node Aliases to other concrete types,collections abc 中容器 ABC 的別名,collections 中型別的別名,棄用的別名
@anchor{library/typing aliases-to-other-concrete-types}@anchor{43e3}@anchor{library/typing other-concrete-types}@anchor{43e4}
@subsubsection Aliases to other concrete types


@geindex Pattern (typing 中的類別)
@geindex Match (typing 中的類別)
@anchor{library/typing typing Pattern}@anchor{92d}
@deffn {類別} typing.Pattern
@anchor{library/typing typing Match}@anchor{43e5}
@deffnx {類別} typing.Match

Deprecated aliases corresponding to the return types from
@ref{dc9,,re.compile()} and @ref{142e,,re.match()}.

These types (and the corresponding functions) are generic over
@ref{5a6,,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{be,,re} now support @code{[]}.
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{8b8,,泛型別名型別}.

@end deffn

@geindex Text (typing 中的類別)
@anchor{library/typing typing Text}@anchor{35e}
@deffn {類別} typing.Text

棄用 @ref{169,,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


在 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{169,,str} instead of @code{Text}.

@end deffn
@anchor{library/typing abstract-base-classes}@anchor{43e6}
@node collections abc 中容器 ABC 的別名,collections abc 中非同步 ABC 的別名,Aliases to other concrete types,棄用的別名
@anchor{library/typing aliases-to-container-abcs-in-collections-abc}@anchor{43e7}@anchor{library/typing corresponding-to-collections-in-collections-abc}@anchor{43e8}
@subsubsection @code{collections.abc} 中容器 ABC 的別名


@geindex AbstractSet (typing 中的類別)
@anchor{library/typing typing AbstractSet}@anchor{43e9}
@deffn {類別} typing.AbstractSet (Collection[T_co])

棄用 @ref{2550,,collections.abc.Set} 的別名。


在 3.9 版之後被棄用: @ref{2550,,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{8b8,,泛型別名型別}.

@end deffn

@geindex ByteString (typing 中的類別)
@anchor{library/typing typing ByteString}@anchor{344}
@deffn {類別} typing.ByteString (Sequence[int])

棄用 @ref{341,,collections.abc.ByteString} 的別名。

使用 @code{isinstance(obj, collections.abc.Buffer)} 來測試 @code{obj} 是否在 runtime 實作了@ref{260,,緩衝區協定}。在型別註解的使用中，請用 @ref{342,,Buffer} 或明確指定你的程式碼所支援型別的聯集（例如 @code{bytes | bytearray | memoryview}）。

@code{ByteString} 最初被設計為一個抽象類別，以作為 @ref{192,,bytes} 和 @ref{343,,bytearray} 的超型別 (supertype)。然而由於 ABC 從未擁有任何方法，知道一個物件是 @code{ByteString} 的實例從未真正告訴你任何關於該物件的有用資訊。其他常見的緩衝區型別如 @ref{165,,memoryview} 也從未被理解為 @code{ByteString} 的子型別（無論是在 runtime 還是由靜態型別檢查器）。

更多細節請見 
@geindex Python Enhancement Proposals; PEP 688#current-options
PEP 688@footnote{https://peps.python.org/pep-0688/#current-options}。


Deprecated since version 3.9, will be removed in version 3.17.

@end deffn

@geindex Collection (typing 中的類別)
@anchor{library/typing typing Collection}@anchor{eea}
@deffn {類別} typing.Collection (Sized, Iterable[T_co], Container[T_co])

棄用 @ref{e7f,,collections.abc.Collection} 的別名。


在 3.6 版被加入.



在 3.9 版之後被棄用: @ref{e7f,,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{8b8,,泛型別名型別}.

@end deffn

@geindex Container (typing 中的類別)
@anchor{library/typing typing Container}@anchor{43ea}
@deffn {類別} typing.Container (Generic[T_co])

棄用 @ref{255a,,collections.abc.Container} 的別名。


在 3.9 版之後被棄用: @ref{255a,,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{8b8,,泛型別名型別}.

@end deffn

@geindex ItemsView (typing 中的類別)
@anchor{library/typing typing ItemsView}@anchor{43eb}
@deffn {類別} typing.ItemsView (MappingView, AbstractSet[tuple[KT_co, VT_co]])

棄用 @ref{255e,,collections.abc.ItemsView} 的別名。


在 3.9 版之後被棄用: @ref{255e,,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{8b8,,泛型別名型別}.

@end deffn

@geindex KeysView (typing 中的類別)
@anchor{library/typing typing KeysView}@anchor{43ec}
@deffn {類別} typing.KeysView (MappingView, AbstractSet[KT_co])

棄用 @ref{255d,,collections.abc.KeysView} 的別名。


在 3.9 版之後被棄用: @ref{255d,,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{8b8,,泛型別名型別}.

@end deffn

@geindex Mapping (typing 中的類別)
@anchor{library/typing typing Mapping}@anchor{43ed}
@deffn {類別} typing.Mapping (Collection[KT], Generic[KT, VT_co])

棄用 @ref{abe,,collections.abc.Mapping} 的別名。


在 3.9 版之後被棄用: @ref{abe,,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{8b8,,泛型別名型別}.

@end deffn

@geindex MappingView (typing 中的類別)
@anchor{library/typing typing MappingView}@anchor{43ee}
@deffn {類別} typing.MappingView (Sized)

棄用 @ref{255c,,collections.abc.MappingView} 的別名。


在 3.9 版之後被棄用: @ref{255c,,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{8b8,,泛型別名型別}.

@end deffn

@geindex MutableMapping (typing 中的類別)
@anchor{library/typing typing MutableMapping}@anchor{43ef}
@deffn {類別} typing.MutableMapping (Mapping[KT, VT])

棄用 @ref{12ad,,collections.abc.MutableMapping} 的別名。


在 3.9 版之後被棄用: @ref{12ad,,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{8b8,,泛型別名型別}.

@end deffn

@geindex MutableSequence (typing 中的類別)
@anchor{library/typing typing MutableSequence}@anchor{43f0}
@deffn {類別} typing.MutableSequence (Sequence[T])

棄用 @ref{4ba,,collections.abc.MutableSequence} 的別名。


在 3.9 版之後被棄用: @ref{4ba,,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{8b8,,泛型別名型別}.

@end deffn

@geindex MutableSet (typing 中的類別)
@anchor{library/typing typing MutableSet}@anchor{43f1}
@deffn {類別} typing.MutableSet (AbstractSet[T])

棄用 @ref{255b,,collections.abc.MutableSet} 的別名。


在 3.9 版之後被棄用: @ref{255b,,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{8b8,,泛型別名型別}.

@end deffn

@geindex Sequence (typing 中的類別)
@anchor{library/typing typing Sequence}@anchor{43f2}
@deffn {類別} typing.Sequence (Reversible[T_co], Collection[T_co])

棄用 @ref{13c5,,collections.abc.Sequence} 的別名。


在 3.9 版之後被棄用: @ref{13c5,,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{8b8,,泛型別名型別}.

@end deffn

@geindex ValuesView (typing 中的類別)
@anchor{library/typing typing ValuesView}@anchor{43f3}
@deffn {類別} typing.ValuesView (MappingView, Collection[_VT_co])

棄用 @ref{255f,,collections.abc.ValuesView} 的別名。


在 3.9 版之後被棄用: @ref{255f,,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{8b8,,泛型別名型別}.

@end deffn

@node collections abc 中非同步 ABC 的別名,Aliases to other ABCs in collections abc,collections abc 中容器 ABC 的別名,棄用的別名
@anchor{library/typing aliases-to-asynchronous-abcs-in-collections-abc}@anchor{43f4}@anchor{library/typing asynchronous-programming}@anchor{43f5}
@subsubsection @code{collections.abc} 中非同步 ABC 的別名


@geindex Coroutine (typing 中的類別)
@anchor{library/typing typing Coroutine}@anchor{1bff}
@deffn {類別} typing.Coroutine (Awaitable[ReturnType], Generic[YieldType, SendType, ReturnType])

棄用 @ref{fd8,,collections.abc.Coroutine} 的別名。

See @ref{284b,,Annotating generators and coroutines}
for details on using @ref{fd8,,collections.abc.Coroutine}
and @code{typing.Coroutine} in type annotations.


在 3.5.3 版被加入.



在 3.9 版之後被棄用: @ref{fd8,,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{8b8,,泛型別名型別}.

@end deffn

@geindex AsyncGenerator (typing 中的類別)
@anchor{library/typing typing AsyncGenerator}@anchor{18fa}
@deffn {類別} typing.AsyncGenerator (AsyncIterator[YieldType], Generic[YieldType, SendType])

棄用 @ref{e82,,collections.abc.AsyncGenerator} 的別名。

See @ref{284b,,Annotating generators and coroutines}
for details on using @ref{e82,,collections.abc.AsyncGenerator}
and @code{typing.AsyncGenerator} in type annotations.


在 3.6.1 版被加入.



在 3.9 版之後被棄用: @ref{e82,,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{8b8,,泛型別名型別}.



在 3.13 版的變更: @code{SendType} 參數現在有預設值。

@end deffn

@geindex AsyncIterable (typing 中的類別)
@anchor{library/typing typing AsyncIterable}@anchor{43f6}
@deffn {類別} typing.AsyncIterable (Generic[T_co])

棄用 @ref{fda,,collections.abc.AsyncIterable} 的別名。


在 3.5.2 版被加入.



在 3.9 版之後被棄用: @ref{fda,,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{8b8,,泛型別名型別}.

@end deffn

@geindex AsyncIterator (typing 中的類別)
@anchor{library/typing typing AsyncIterator}@anchor{43f7}
@deffn {類別} typing.AsyncIterator (AsyncIterable[T_co])

棄用 @ref{fd9,,collections.abc.AsyncIterator} 的別名。


在 3.5.2 版被加入.



在 3.9 版之後被棄用: @ref{fd9,,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{8b8,,泛型別名型別}.

@end deffn

@geindex Awaitable (typing 中的類別)
@anchor{library/typing typing Awaitable}@anchor{43f8}
@deffn {類別} typing.Awaitable (Generic[T_co])

棄用 @ref{fd7,,collections.abc.Awaitable} 的別名。


在 3.5.2 版被加入.



在 3.9 版之後被棄用: @ref{fd7,,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{8b8,,泛型別名型別}.

@end deffn

@node Aliases to other ABCs in collections abc,contextlib ABC 的別名,collections abc 中非同步 ABC 的別名,棄用的別名
@anchor{library/typing aliases-to-other-abcs-in-collections-abc}@anchor{43f9}@anchor{library/typing corresponding-to-other-types-in-collections-abc}@anchor{43fa}
@subsubsection Aliases to other ABCs in @code{collections.abc}


@geindex Iterable (typing 中的類別)
@anchor{library/typing typing Iterable}@anchor{43fb}
@deffn {類別} typing.Iterable (Generic[T_co])

棄用 @ref{2558,,collections.abc.Iterable} 的別名。


在 3.9 版之後被棄用: @ref{2558,,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{8b8,,泛型別名型別}.

@end deffn

@geindex Iterator (typing 中的類別)
@anchor{library/typing typing Iterator}@anchor{43fc}
@deffn {類別} typing.Iterator (Iterable[T_co])

棄用 @ref{2559,,collections.abc.Iterator} 的別名。


在 3.9 版之後被棄用: @ref{2559,,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{8b8,,泛型別名型別}.

@end deffn

@geindex Callable (於 typing 模組中)
@anchor{library/typing typing Callable}@anchor{9c1}
@deffn {資料} typing.Callable

棄用 @ref{9e4,,collections.abc.Callable} 的別名。

See @ref{2579,,註釋 callable 物件} for details on how to use
@ref{9e4,,collections.abc.Callable} and @code{typing.Callable} in type annotations.


在 3.9 版之後被棄用: @ref{9e4,,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{8b8,,泛型別名型別}.



在 3.10 版的變更: @code{Callable} 現已支援 @ref{482,,ParamSpec} 以及 @ref{9c0,,Concatenate}。請參閱 
@geindex Python Enhancement Proposals; PEP 612
PEP 612@footnote{https://peps.python.org/pep-0612/} 閱讀詳細內容。

@end deffn

@geindex Generator (typing 中的類別)
@anchor{library/typing typing Generator}@anchor{18f9}
@deffn {類別} typing.Generator (Iterator[YieldType], Generic[YieldType, SendType, ReturnType])

棄用 @ref{fd6,,collections.abc.Generator} 的別名。

See @ref{284b,,Annotating generators and coroutines}
for details on using @ref{fd6,,collections.abc.Generator}
and @code{typing.Generator} in type annotations.


在 3.9 版之後被棄用: @ref{fd6,,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{8b8,,泛型別名型別}.



在 3.13 版的變更: Default values for the send and return types were added.

@end deffn

@geindex Hashable (typing 中的類別)
@anchor{library/typing typing Hashable}@anchor{710}
@deffn {類別} typing.Hashable

棄用 @ref{712,,collections.abc.Hashable} 的別名。


在 3.12 版之後被棄用: 改為直接使用 @ref{712,,collections.abc.Hashable}。

@end deffn

@geindex Reversible (typing 中的類別)
@anchor{library/typing typing Reversible}@anchor{43fd}
@deffn {類別} typing.Reversible (Iterable[T_co])

棄用 @ref{e80,,collections.abc.Reversible} 的別名。


在 3.9 版之後被棄用: @ref{e80,,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{8b8,,泛型別名型別}.

@end deffn

@geindex Sized (typing 中的類別)
@anchor{library/typing typing Sized}@anchor{711}
@deffn {類別} typing.Sized

棄用 @ref{713,,collections.abc.Sized} 的別名。


在 3.12 版之後被棄用: 改為直接使用 @ref{713,,collections.abc.Sized}。

@end deffn

@node contextlib ABC 的別名,,Aliases to other ABCs in collections abc,棄用的別名
@anchor{library/typing aliases-to-contextlib-abcs}@anchor{43fe}@anchor{library/typing context-manager-types}@anchor{43ff}
@subsubsection @code{contextlib} ABC 的別名


@geindex ContextManager (typing 中的類別)
@anchor{library/typing typing ContextManager}@anchor{e86}
@deffn {類別} typing.ContextManager (Generic[T_co, ExitT_co])

Deprecated alias to @ref{e85,,contextlib.AbstractContextManager}.

The first type parameter, @code{T_co}, represents the type returned by
the @ref{7dd,,__enter__()} method. The optional second type parameter, @code{ExitT_co},
which defaults to @code{bool | None}, represents the type returned by the
@ref{1501,,__exit__()} method.


在 3.5.4 版被加入.



在 3.9 版之後被棄用: @ref{e85,,contextlib.AbstractContextManager}
now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{8b8,,泛型別名型別}.



在 3.13 版的變更: Added the optional second type parameter, @code{ExitT_co}.

@end deffn

@geindex AsyncContextManager (typing 中的類別)
@anchor{library/typing typing AsyncContextManager}@anchor{18f7}
@deffn {類別} typing.AsyncContextManager (Generic[T_co, AExitT_co])

Deprecated alias to @ref{d18,,contextlib.AbstractAsyncContextManager}.

The first type parameter, @code{T_co}, represents the type returned by
the @ref{22cd,,__aenter__()} method. The optional second type parameter, @code{AExitT_co},
which defaults to @code{bool | None}, represents the type returned by the
@ref{18f8,,__aexit__()} method.


在 3.6.2 版被加入.



在 3.9 版之後被棄用: @ref{d18,,contextlib.AbstractAsyncContextManager}
now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{8b8,,泛型別名型別}.



在 3.13 版的變更: Added the optional second type parameter, @code{AExitT_co}.

@end deffn

@node 主要功能的棄用時程表,,模組內容<7>,typing --- 支援型別提示
@anchor{library/typing deprecation-timeline-of-major-features}@anchor{4400}
@subsubsection 主要功能的棄用時程表


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

棄用於

@tab

Projected removal

@tab

PEP/issue

@item

@code{typing} versions of standard collections

@tab

3.9

@tab

Undecided (see @ref{43d3,,棄用的別名} for more information)

@tab

@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/}

@item

@ref{344,,typing.ByteString}

@tab

3.9

@tab

3.17

@tab

gh-91896@footnote{https://github.com/python/cpython/issues/91896}

@item

@ref{35e,,typing.Text}

@tab

3.11

@tab

Undecided

@tab

gh-92332@footnote{https://github.com/python/cpython/issues/92332}

@item

@ref{710,,typing.Hashable} 和 @ref{711,,typing.Sized}

@tab

3.12

@tab

Undecided

@tab

gh-94309@footnote{https://github.com/python/cpython/issues/94309}

@item

@ref{9c5,,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{332,,@@typing.no_type_check_decorator}

@tab

3.13

@tab

3.15

@tab

gh-106309@footnote{https://github.com/python/cpython/issues/106309}

@item

@ref{5a6,,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 --- 文件產生器與線上幫助系統,Python 開發模式,typing --- 支援型別提示,開發工具
@anchor{library/pydoc doc}@anchor{4401}@anchor{library/pydoc module-pydoc}@anchor{ba}@anchor{library/pydoc pydoc-documentation-generator-and-online-help-system}@anchor{4402}@anchor{library/pydoc translation-repo}@anchor{4403}
@subsection @code{pydoc} --- 文件產生器與線上幫助系統


@geindex module; pydoc

`原始碼：'Lib/pydoc.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/pydoc.py}

@geindex documentation（文件）;generation（產生）
@geindex documentation（文件）;online（線上）
@geindex help（幫助）;online（線上）


__________________________________________________________________


@code{pydoc} 模組會自動從 Python 模組產生文件。文件可以以文字頁面的形式呈現在主控台上、提供給網頁瀏覽器，或儲存為 HTML 檔案。

對於模組、類別、函式和方法，所顯示的文件是從物件的說明字串（也就是物件的 @ref{b18,,__doc__} 屬性）以及遞迴地從其可文件化成員的說明字串所取得。如果沒有說明字串，@code{pydoc} 會嘗試從原始碼檔案中，類別、函式或方法定義正上方的註解區塊，或從模組的頂部取得描述（參見 @ref{189e,,inspect.getcomments()}）。

內建函式 @ref{acb,,help()} 會在互動式直譯器中呼叫線上幫助系統，它會使用 @code{pydoc} 在主控台上以文字形式產生文件。同樣的文字文件也可以在 Python 直譯器外部檢視，方法是在作業系統的命令提示字元中，將 @code{pydoc} 當作腳本執行。例如，執行：

@example
python -m pydoc sys
@end example

在 shell 提示字元下，將會顯示 @ref{df,,sys} 模組的文件，其風格類似於 Unix @code{man} 命令所顯示的使用手冊。@code{pydoc} 的引數可以是函式、模組或套件的名稱，或是一個指向模組中或套件中模組內的類別、方法或函式的點號參照 (dotted reference)。如果 @code{pydoc} 的引數看起來像一個路徑（也就是說，它包含你作業系統的路徑分隔符，例如 Unix 中的斜線），並且指向一個已存在的 Python 原始碼檔案，那麼就會為該檔案產生文件。

@cartouche
@quotation 備註 
為了找到物件及其文件，@code{pydoc} 會引入要文件化的模組。因此，任何在模組層級的程式碼都會在那個時候被執行。使用 @code{if __name__ == '__main__':} 的防護措施，可以確保程式碼只在檔案作為腳本被呼叫時執行，而不會在被引入時就執行。
@end quotation
@end cartouche

當在主控台印出輸出內容時，@code{pydoc} 會嘗試將輸出內容做分頁以便於閱讀。如果 
@geindex MANPAGER
@geindex 環境變數; MANPAGER
@code{MANPAGER} 或 
@geindex PAGER
@geindex 環境變數; PAGER
@code{PAGER} 環境變數其中之一被設定，@code{pydoc} 將會使用其值作為分頁程式。當兩者都被設定時，會使用 
@geindex MANPAGER
@geindex 環境變數; MANPAGER
@code{MANPAGER}。

在引數前指定一個 @code{-w} 旗標，將會使 HTML 文件被寫入目前目錄的一個檔案中，而不是在主控台上顯示文字。

在引數前指定一個 @code{-k} 旗標，將會搜尋所有可用模組的摘要行 (synopsis lines)，尋找作為引數給出的關鍵字，其方式同樣類似於 Unix 的 @code{man} 命令。一個模組的摘要行是其說明字串的第一行。

你也可以使用 @code{pydoc} 在本機上啟動一個 HTTP 伺服器，它會向來訪的網頁瀏覽器提供文件。@code{python -m pydoc -p 1234} 將會在 1234 埠啟動一個 HTTP 伺服器，讓你可以用你偏好的網頁瀏覽器在 @code{http://localhost:1234/} 瀏覽文件。指定 @code{0} 作為通訊埠編號將會選擇一個任意未使用的通訊埠。

@code{python -m pydoc -n <hostname>} 將會啟動伺服器並在給定的主機名稱上監聽。預設的主機名稱是 'localhost'，但如果你希望伺服器能被其他機器連線，你可能會想改變伺服器回應的主機名稱。在開發期間，如果你想在容器內執行 pydoc，這點特別有用。

@code{python -m pydoc -b} 將會啟動伺服器，並額外開啟一個網頁瀏覽器到模組索引頁面。每個提供的頁面頂部都有一個導覽列，你可以在那裡 `Get'（取得）個別項目的幫助、`Search'（搜尋）所有在其摘要行中包含關鍵字的模組，以及前往 `Module index'（模組索引）、`Topics'（主題）和 `Keywords'（關鍵字）頁面。

當 @code{pydoc} 產生文件時，它會使用目前的環境和路徑來定位模組。因此，呼叫 @code{pydoc spam} 所產生的文件，會完全對應到你啟動 Python 直譯器並輸入 @code{import spam} 時所取得的模組版本。

核心模組的文件被假定存放在 @code{https://docs.python.org/X.Y/library/}，其中 @code{X} 和 @code{Y} 是 Python 直譯器的主版本號和次版本號。這可以透過將 @code{PYTHONDOCS} 環境變數設定為不同的 URL 或包含函式庫參考使用手冊的本機目錄來覆寫。


在 3.2 版的變更: 新增 @code{-b} 選項。



在 3.3 版的變更: 移除 @code{-g} 命令列選項。



在 3.4 版的變更: @code{pydoc} 現在使用 @ref{22f,,inspect.signature()} 而不是 @ref{939,,inspect.getfullargspec()} 來從可呼叫物件中提取簽章資訊。



在 3.7 版的變更: 新增 @code{-n} 選項。


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Python 開發模式,doctest --- 測試互動式 Python 範例,pydoc --- 文件產生器與線上幫助系統,開發工具
@anchor{library/devmode doc}@anchor{4404}@anchor{library/devmode devmode}@anchor{503}@anchor{library/devmode python-development-mode}@anchor{4405}@anchor{library/devmode translation-repo}@anchor{4406}
@subsection Python 開發模式



在 3.7 版被加入.


Python 開發模式引入了額外的 runtime 檢查，預設啟用這些檢查的成本太高。如果程式碼正確，它不應比預設值更詳細；僅當偵測到問題時才會發出新警告。

可以使用 @ref{16f,,-X dev} 命令列選項或將 
@geindex PYTHONDEVMODE
@geindex 環境變數; PYTHONDEVMODE
@ref{cde,,PYTHONDEVMODE} 環境變數設為 1 來啟用它。

另請參閱 @ref{504,,Python 除錯建置}。

@menu
* Python 開發模式的影響:: 
* ResourceWarning 範例:: 
* 檔案描述器的錯誤範例:: 

@end menu

@node Python 開發模式的影響,ResourceWarning 範例,,Python 開發模式
@anchor{library/devmode effects-of-the-python-development-mode}@anchor{4407}
@subsubsection Python 開發模式的影響


啟用 Python 開發模式類似以下指令，但具有如下所述的附加效果：

@example
PYTHONMALLOC=debug PYTHONASYNCIODEBUG=1 python -W default -X faulthandler
@end example

Python 開發模式的效果：


@itemize *

@item 
新增 @code{default} @ref{1ff1,,警告過濾器}。以下警告會被顯示：


@itemize *

@item 
@ref{1a3,,DeprecationWarning}

@item 
@ref{717,,ImportWarning}

@item 
@ref{abd,,PendingDeprecationWarning}

@item 
@ref{547,,ResourceWarning}
@end itemize

一般來說，上述警告會被預設的@ref{1ff1,,警告過濾器}給過濾掉。

它的行為就像使用 @ref{abc,,-W default} 命令列選項一樣。

使用 @ref{abc,,-W error} 命令列選項或將 
@geindex PYTHONWARNINGS
@geindex 環境變數; PYTHONWARNINGS
@ref{d9e,,PYTHONWARNINGS} 環境變數設為 @code{error} 會將警告視為錯誤。

@item 
在記憶體分配器上安裝除錯 hook（掛鉤）以檢查：


@itemize *

@item 
緩衝區下溢 (underflow)

@item 
緩衝區溢位 (overflow)

@item 
記憶體分配器 API 違規

@item 
GIL 的不安全使用
@end itemize

請參閱 @ref{e5f,,PyMem_SetupDebugHooks()} C 函式。

它的行為就好像是將 
@geindex PYTHONMALLOC
@geindex 環境變數; PYTHONMALLOC
@ref{e59,,PYTHONMALLOC} 環境變數設定為 @code{debug} 一樣。

若要啟用 Python 開發模式而不在記憶體分配器上安裝偵錯 hook，請將 
@geindex PYTHONMALLOC
@geindex 環境變數; PYTHONMALLOC
@ref{e59,,PYTHONMALLOC} 環境變數設為 @code{default}。

@item 
在 Python 啟動時呼叫 @ref{20f,,faulthandler.enable()} 來為 @ref{127b,,SIGSEGV}、@ref{127c,,SIGFPE}、@ref{127d,,SIGABRT}、@ref{127e,,SIGBUS} 和 @ref{127f,,SIGILL} 訊號安裝處理函式以在當機時傾印 (dump) Python 回溯 (traceback)。

它的行為就像使用 @ref{16f,,-X faulthandler} 命令列選項或將 
@geindex PYTHONFAULTHANDLER
@geindex 環境變數; PYTHONFAULTHANDLER
@ref{1280,,PYTHONFAULTHANDLER} 環境變數設定為 @code{1}。

@item 
啟用 @ref{2001,,asyncio 除錯模式}。例如 @ref{b,,asyncio} 會檢查未被等待的 (not awaited) 協程並記錄 (log) 它們。

它的行為就像將 
@geindex PYTHONASYNCIODEBUG
@geindex 環境變數; PYTHONASYNCIODEBUG
@ref{2000,,PYTHONASYNCIODEBUG} 環境變數設定為 1 一樣。

@item 
檢查字串編碼和解碼操作的 `encoding' 和 `errors' 引數。例如：@ref{315,,open()}、@ref{ac9,,str.encode()} 和 @ref{aca,,bytes.decode()}。

預設情況下，為了獲得最佳效能，僅在第一個編碼/解碼錯誤時檢查 `errors' 引數，並且有時會因為是空字串而忽略 `encoding' 引數。

@item 
@ref{500,,io.IOBase} 解構函式會記錄 @code{close()} 例外。

@item 
將 @ref{895,,sys.flags} 的 @ref{1d49,,dev_mode} 屬性設為 @code{True}。
@end itemize

Python 開發模式預設不會啟用 @ref{105,,tracemalloc} 模組，因為（效能和記憶體的）開銷太大。啟用 @ref{105,,tracemalloc} 模組可提供有關某些錯誤來源的附加資訊。例如 @ref{547,,ResourceWarning} 記錄了分配資源之處的回溯、緩衝區溢位錯誤記錄了分配記憶體區塊的回溯。

Python 開發模式不會防止 @ref{18c,,-O} 命令列選項刪除 @ref{b57,,assert} 陳述式，也不會防止將 @ref{9d3,,__debug__} 設定為 @code{False}。

Python 開發模式只能在 Python 啟動時啟用。它的值可以從 @ref{895,,sys.flags.dev_mode} 讀取。


在 3.8 版的變更: @ref{500,,io.IOBase} 解構函式現在會記錄 @code{close()} 例外。



在 3.9 版的變更: 現在會為字串編碼和解碼操作檢查 `encoding' 和 `errors' 引數。


@node ResourceWarning 範例,檔案描述器的錯誤範例,Python 開發模式的影響,Python 開發模式
@anchor{library/devmode resourcewarning-example}@anchor{4408}
@subsubsection ResourceWarning 範例


計算命令列中指定的文字檔案列數的腳本範例：

@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

該腳本不會明確關閉檔案。預設情況下，Python 不會發出任何警告。使用 README.txt 的範例，該檔案有 269 列：

@example
$ python script.py README.txt
269
@end example

啟用 Python 開發模式會顯示 @ref{547,,ResourceWarning} 警告：

@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

此外，啟用 @ref{105,,tracemalloc} 會顯示檔案被開啟的那一列：

@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

修復方法是明確關閉該檔案。以下是使用情境管理器的範例：

@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

不明確關閉資源可能會使資源開啟的時間比預期的長得多；它可能會在退出 Python 時導致嚴重問題。在 CPython 中很糟糕，但在 PyPy 中更糟。明確關閉資源使應用程式更具確定性和可靠性。

@node 檔案描述器的錯誤範例,,ResourceWarning 範例,Python 開發模式
@anchor{library/devmode bad-file-descriptor-error-example}@anchor{4409}
@subsubsection 檔案描述器的錯誤範例


顯示自身第一列的腳本：

@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

預設情況下，Python 不會發出任何警告：

@example
$ python script.py
import os
@end example

Python 開發模式在最終化 (finalize) 檔案物件時顯示 @ref{547,,ResourceWarning} 並記錄 "Bad file descriptor" 錯誤：

@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())} 會關閉檔案描述器。當檔案物件最終化函式 (finalizer) 嘗試再次關閉檔案描述器時，它會失敗並出現 @code{Bad file descriptor} 錯誤。檔案描述器只能關閉一次。在最壞的情況下，將它關閉兩次可能會導致崩潰 (crash)（相關範例請參閱 bpo-18748@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18748}）。

修復方法是刪除 @code{os.close(fp.fileno())} 那列，或使用 @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 --- 測試互動式 Python 範例,unittest --- 單元測試框架,Python 開發模式,開發工具
@anchor{library/doctest doc}@anchor{440a}@anchor{library/doctest doctest-test-interactive-python-examples}@anchor{440b}@anchor{library/doctest module-doctest}@anchor{3e}@anchor{library/doctest translation-repo}@anchor{440c}
@subsection @code{doctest} --- 測試互動式 Python 範例


@geindex module; doctest

`原始碼：'Lib/doctest.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/doctest.py}


__________________________________________________________________


The @ref{3e,,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 
透過驗證測試檔案或測試物件中的互動式範例是否按預期運作來執行迴歸測試。

@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, @ref{3e,,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 @ref{3e,,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 @ref{3e,,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}.


在 3.13 版被加入: Output is colorized by default and can be
@ref{1b7,,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. 
* 命令列用法: 命令列用法<6>. 
* 運作方式:: 
* 基礎 API:: 
* Unittest API:: 
* Advanced API:: 
* 偵錯:: 
* Soapbox:: 

@end menu

@node Simple Usage Checking Examples in Docstrings,Simple Usage Checking Examples in a Text File,,doctest --- 測試互動式 Python 範例
@anchor{library/doctest doctest-simple-testmod}@anchor{440d}@anchor{library/doctest simple-usage-checking-examples-in-docstrings}@anchor{440e}
@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{1662,,testmod()}, or
prohibit it by passing @code{verbose=False}.  In either of those cases,
@ref{1465,,sys.argv} is not examined by @ref{1662,,testmod()} (so passing @code{-v} or not
has no effect).

There is also a command line shortcut for running @ref{1662,,testmod()}, see section
@ref{440f,,命令列用法}.

For more information on @ref{1662,,testmod()}, see section @ref{4410,,基礎 API}.

@node Simple Usage Checking Examples in a Text File,命令列用法<6>,Simple Usage Checking Examples in Docstrings,doctest --- 測試互動式 Python 範例
@anchor{library/doctest doctest-simple-testfile}@anchor{4411}@anchor{library/doctest simple-usage-checking-examples-in-a-text-file}@anchor{4412}
@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{4413,,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{1662,,testmod()}, @ref{4413,,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{4413,,testfile()} looks for files in the calling module's directory.
See section @ref{4410,,基礎 API} for a description of the optional arguments
that can be used to tell it to look for files in other locations.

Like @ref{1662,,testmod()}, @ref{4413,,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{4413,,testfile()}, see section
@ref{440f,,命令列用法}.

For more information on @ref{4413,,testfile()}, see section @ref{4410,,基礎 API}.

@node 命令列用法<6>,運作方式,Simple Usage Checking Examples in a Text File,doctest --- 測試互動式 Python 範例
@anchor{library/doctest command-line-usage}@anchor{4414}@anchor{library/doctest doctest-cli}@anchor{440f}
@subsubsection 命令列用法


可以從命令列以腳本方式叫用 @ref{3e,,doctest} 模組：

@example
python -m doctest [-v] [-o OPTION] [-f] file [file ...]
@end example

@geindex doctest 命令列選項; -v
@geindex doctest 命令列選項; --verbose
@anchor{library/doctest cmdoption-doctest-v}@anchor{4415}@anchor{library/doctest cmdoption-doctest-verbose}@anchor{4416}
@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{1662,,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{4413,,testfile()} instead:

@example
python -m doctest -v example.txt
@end example
@end deffn

@geindex doctest 命令列選項; -o
@geindex doctest 命令列選項; --option
@anchor{library/doctest cmdoption-doctest-o}@anchor{4417}@anchor{library/doctest cmdoption-doctest-option}@anchor{4418}
@deffn {Option} @w{-}o, @w{-}@w{-}option <option>

Option flags control various aspects of doctest's behavior, see section
@ref{112e,,可選旗標}.


在 3.4 版被加入.

@end deffn

@geindex doctest 命令列選項; -f
@geindex doctest 命令列選項; --fail-fast
@anchor{library/doctest cmdoption-doctest-f}@anchor{4419}@anchor{library/doctest cmdoption-doctest-fail-fast}@anchor{441a}
@deffn {Option} @w{-}f, @w{-}@w{-}fail@w{-}fast

This is shorthand for @code{-o FAIL_FAST}.


在 3.4 版被加入.

@end deffn

@node 運作方式,基礎 API,命令列用法<6>,doctest --- 測試互動式 Python 範例
@anchor{library/doctest doctest-how-it-works}@anchor{441b}@anchor{library/doctest how-it-works}@anchor{441c}
@subsubsection 運作方式


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?:: 
* 可選旗標:: 
* Directives:: 
* 警告: 警告<2>. 

@end menu

@node Which Docstrings Are Examined?,How are Docstring Examples Recognized?,,運作方式
@anchor{library/doctest doctest-which-docstrings}@anchor{441d}@anchor{library/doctest which-docstrings-are-examined}@anchor{441e}
@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{441f}
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?,運作方式
@anchor{library/doctest doctest-finding-examples}@anchor{4420}@anchor{library/doctest how-are-docstring-examples-recognized}@anchor{4421}
@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
>>> # 註解會被忽略
>>> 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{4422,,NORMALIZE_WHITESPACE} option or @ref{4423,,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{4424,,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?,運作方式
@anchor{library/doctest doctest-execution-context}@anchor{4425}@anchor{library/doctest what-s-the-execution-context}@anchor{4426}
@subsubsection What's the Execution Context?


By default, each time @ref{3e,,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{1662,,testmod()} or @ref{4413,,testfile()} instead.

@node What About Exceptions?,可選旗標,What's the Execution Context?,運作方式
@anchor{library/doctest doctest-exceptions}@anchor{4427}@anchor{library/doctest what-about-exceptions}@anchor{4428}
@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.

簡單範例：

@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{2eb,,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{2eb,,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{1663,,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{2eb,,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{1509,,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{18e,,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 ^ （插入符號）;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{4429}
@node 可選旗標,Directives,What About Exceptions?,運作方式
@anchor{library/doctest doctest-options}@anchor{112e}@anchor{library/doctest option-flags}@anchor{442a}
@subsubsection 可選旗標


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{2375,,bitwise ORed} together and passed to various functions.
The names can also be used in @ref{4423,,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{442b}
@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{442b,,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{442c}
@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{442c,,DONT_ACCEPT_BLANKLINE} is specified, this substitution is not allowed.
@end deffn

@geindex NORMALIZE_WHITESPACE (於 doctest 模組中)
@anchor{library/doctest doctest NORMALIZE_WHITESPACE}@anchor{4422}
@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{4422,,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 ...;於 doctests 中

@geindex ELLIPSIS (於 doctest 模組中)
@anchor{library/doctest doctest ELLIPSIS}@anchor{1663}
@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{1509}
@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{198,,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{1663,,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{1509,,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{442d}
@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{442e}
@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{1664}
@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{1665}
@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{1666}
@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{442f}
@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{442f,,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{112f}
@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{4430}
@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 @ref{3e,,doctest} internals via subclassing:

@geindex register_optionflag() (於 doctest 模組中)
@anchor{library/doctest doctest register_optionflag}@anchor{4431}
@deffn {函式} doctest.register_optionflag (name)

Create a new option flag with a given name, and return the new flag's integer
value.  @ref{4431,,register_optionflag()} can be used when subclassing
@ref{4432,,OutputChecker} or @ref{4433,,DocTestRunner} to create new options that are
supported by your subclasses.  @ref{4431,,register_optionflag()} should always be
called using the following idiom:

@example
MY_FLAG = register_optionflag('MY_FLAG')
@end example
@end deffn

@geindex # （井字號）;於 doctests 中
@geindex + （加號）;於 doctests 中
@geindex - （減號）;於 doctests 中

@node Directives,警告<2>,可選旗標,運作方式
@anchor{library/doctest directives}@anchor{4434}@anchor{library/doctest doctest-directives}@anchor{4423}
@subsubsection Directives


Doctest directives may be used to modify the @ref{112e,,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{4435}directive:             "#" "doctest:" @ref{4436,,directive_options}
@anchor{library/doctest grammar-token-doctest-directive_options}@anchor{4436}directive_options:     @ref{4437,,directive_option} ("," @ref{4437,,directive_option})*
@anchor{library/doctest grammar-token-doctest-directive_option}@anchor{4437}directive_option:      @ref{4438,,on_or_off} @ref{4439,,directive_option_name}
@anchor{library/doctest grammar-token-doctest-on_or_off}@anchor{4438}on_or_off:             "+" | "-"
@anchor{library/doctest grammar-token-doctest-directive_option_name}@anchor{4439}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.

舉例來說，這個測試會通過：

@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 警告<2>,,Directives,運作方式
@anchor{library/doctest doctest-warnings}@anchor{443a}@anchor{library/doctest warnings}@anchor{443b}
@subsubsection 警告


@ref{3e,,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{1663,,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  # 有風險
1.9952623149688797
>>> round(1000**0.1, 9) # 更安全
1.995262315
>>> print(f'@{1000**0.1:.4f@}') # 更加安全
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 基礎 API,Unittest API,運作方式,doctest --- 測試互動式 Python 範例
@anchor{library/doctest basic-api}@anchor{443c}@anchor{library/doctest doctest-basic-api}@anchor{4410}
@subsubsection 基礎 API


The functions @ref{1662,,testmod()} and @ref{4413,,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{440d,,Simple Usage; Checking Examples in Docstrings}
and @ref{4411,,Simple Usage; Checking Examples in a Text File}.

@geindex testfile() (於 doctest 模組中)
@anchor{library/doctest doctest testfile}@anchor{4413}
@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{165a,,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{1465,,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{2375,,bitwise OR} of option flags.
See section @ref{112e,,可選旗標}.

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{4424,,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{1662}
@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.

回傳 @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{443d,,doctest.master.summarize} in
conjunction with @ref{1662,,testmod()} continues to get output for objects with no
tests. The `exclude_empty' argument to the newer @ref{18ff,,DocTestFinder}
constructor defaults to true.

Optional arguments `extraglobs', `verbose', `report', `optionflags',
`raise_on_error', and `globs' are the same as for function @ref{4413,,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{443e}
@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{4413,,testfile()} above.
@end deffn

@node Unittest API,Advanced API,基礎 API,doctest --- 測試互動式 Python 範例
@anchor{library/doctest doctest-unittest-api}@anchor{443f}@anchor{library/doctest unittest-api}@anchor{4440}
@subsubsection Unittest API


As your collection of doctest'ed modules grows, you'll want a way to run all
their doctests systematically.  @ref{3e,,doctest} provides two functions that can
be used to create @ref{10c,,unittest} test suites from modules and text files
containing doctests.  To integrate with @ref{10c,,unittest} test discovery, include
a @ref{4441,,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{ff0,,unittest.TestSuite} instances
from text files and modules with doctests:

@geindex DocFileSuite() (於 doctest 模組中)
@anchor{library/doctest doctest DocFileSuite}@anchor{4442}
@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{ff0,,unittest.TestSuite}.

The returned @ref{ff0,,unittest.TestSuite} is to be run by the unittest framework
and runs the interactive examples in each file.  If an example in any file
fails, then the synthesized unit test fails, and a @ref{4443,,failureException}
exception is raised showing the name of the file containing the test and a
(sometimes approximate) line number.  If all the examples in a file are
skipped, then the synthesized unit test is also marked as skipped.

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{197a,,DocTest} object.  The `setUp' function can access the
test globals as the @ref{4444,,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{197a,,DocTest} object.  The `tearDown' function can
access the test globals as the @ref{4444,,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{112e,,可選旗標}. See function @ref{4445,,set_unittest_reportflags()} below
for a better way to set reporting options.

Optional argument `parser' specifies a @ref{4424,,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 @ref{4442,,DocFileSuite()}.
@end deffn

@geindex DocTestSuite() (於 doctest 模組中)
@anchor{library/doctest doctest DocTestSuite}@anchor{fef}
@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{ff0,,unittest.TestSuite}.

The returned @ref{ff0,,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.
If any of the doctests fail, then the synthesized unit test fails,
and a @ref{4443,,unittest.TestCase.failureException} exception is raised
showing the name of the file containing the test and a (sometimes approximate)
line number.  If all the examples in a docstring are skipped, then the

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{2221,,__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{18ff,,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{4442,,DocFileSuite()} above, but they are called for each docstring.

This function uses the same search technique as @ref{1662,,testmod()}.


在 3.5 版的變更: @ref{fef,,DocTestSuite()} returns an empty @ref{ff0,,unittest.TestSuite} if `module'
contains no docstrings instead of raising @ref{2eb,,ValueError}.

@end deffn

Under the covers, @ref{fef,,DocTestSuite()} creates a @ref{ff0,,unittest.TestSuite} out
of @code{doctest.DocTestCase} instances, and @code{DocTestCase} is a
subclass of @ref{2b3,,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{10c,,unittest} integration.

Similarly, @ref{4442,,DocFileSuite()} creates a @ref{ff0,,unittest.TestSuite} out of
@code{doctest.DocFileCase} instances, and @code{DocFileCase} is a subclass
of @code{DocTestCase}.

So both ways of creating a @ref{ff0,,unittest.TestSuite} run instances of
@code{DocTestCase}.  This is important for a subtle reason: when you run
@ref{3e,,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{10c,,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, @ref{3e,,doctest} also supports a notion of @code{doctest}
reporting flags specific to @ref{10c,,unittest} support, via this function:

@geindex set_unittest_reportflags() (於 doctest 模組中)
@anchor{library/doctest doctest set_unittest_reportflags}@anchor{4445}
@deffn {函式} doctest.set_unittest_reportflags (flags)

Set the @ref{3e,,doctest} reporting flags to use.

Argument `flags' takes the @ref{2375,,bitwise OR} of option flags.  See
section @ref{112e,,可選旗標}.  Only "reporting flags" can be used.

This is a module-global setting, and affects all future doctests run by module
@ref{10c,,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{2375,,bitwise ORed} into the option flags, and the option flags
so augmented are passed to the @ref{4433,,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{10c,,unittest} reporting flags in effect before the function
was called is returned by the function.
@end deffn

@node Advanced API,偵錯,Unittest API,doctest --- 測試互動式 Python 範例
@anchor{library/doctest advanced-api}@anchor{4446}@anchor{library/doctest doctest-advanced-api}@anchor{4447}
@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{4448,,Example}: A single Python @ref{2aae,,statement}, paired with its expected
output.

@item 
@ref{197a,,DocTest}: A collection of @ref{4448,,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{18ff,,DocTestFinder}: Finds all docstrings in a given module, and uses a
@ref{4424,,DocTestParser} to create a @ref{197a,,DocTest} from every docstring that
contains interactive examples.

@item 
@ref{4424,,DocTestParser}: Creates a @ref{197a,,DocTest} object from a string (such
as an object's docstring).

@item 
@ref{4433,,DocTestRunner}: Executes the examples in a @ref{197a,,DocTest}, and uses
an @ref{4432,,OutputChecker} to verify their output.

@item 
@ref{4432,,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 物件:: 
* Example 物件:: 
* DocTestFinder 物件:: 
* DocTestParser 物件:: 
* TestResults 物件:: 
* DocTestRunner 物件:: 
* OutputChecker 物件:: 

@end menu

@node DocTest 物件,Example 物件,,Advanced API
@anchor{library/doctest doctest-doctest}@anchor{4449}@anchor{library/doctest doctest-objects}@anchor{444a}
@subsubsection DocTest 物件


@geindex DocTest (doctest 中的類別)
@anchor{library/doctest doctest DocTest}@anchor{197a}
@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.

@ref{197a,,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{444b}
@deffn {屬性} examples

A list of @ref{4448,,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{4444}
@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{4444,,globs}
after the test is run.
@end deffn

@geindex name (doctest.DocTest 的屬性)
@anchor{library/doctest doctest DocTest name}@anchor{444c}
@deffn {屬性} name

A string name identifying the @ref{197a,,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{444d}
@deffn {屬性} filename

The name of the file that this @ref{197a,,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{175d}
@deffn {屬性} lineno

The line number within @ref{444d,,filename} where this @ref{197a,,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{444e}
@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 物件,DocTestFinder 物件,DocTest 物件,Advanced API
@anchor{library/doctest doctest-example}@anchor{444f}@anchor{library/doctest example-objects}@anchor{4450}
@subsubsection Example 物件


@geindex Example (doctest 中的類別)
@anchor{library/doctest doctest Example}@anchor{4448}
@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.

@ref{4448,,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{4451}
@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{4452}
@deffn {屬性} want

The expected output from running the example's source code (either from
stdout, or a traceback in case of exception).  @ref{4452,,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{4453}
@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{a47,,traceback.format_exception_only()}.  @ref{4453,,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{4454}
@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{4455}
@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{4456}
@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{4433,,DocTestRunner}'s @ref{112e,,optionflags}).
By default, no options are set.
@end deffn
@end deffn

@node DocTestFinder 物件,DocTestParser 物件,Example 物件,Advanced API
@anchor{library/doctest doctest-doctestfinder}@anchor{4457}@anchor{library/doctest doctestfinder-objects}@anchor{4458}
@subsubsection DocTestFinder 物件


@geindex DocTestFinder (doctest 中的類別)
@anchor{library/doctest doctest DocTestFinder}@anchor{18ff}
@deffn {類別} doctest.DocTestFinder (verbose=False, parser=DocTestParser(), recurse=True, exclude_empty=True)

A processing class used to extract the @ref{197a,,DocTest}s that are relevant to
a given object, from its docstring and the docstrings of its contained objects.
@ref{197a,,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{4424,,DocTestParser} object (or a
drop-in replacement) that is used to extract doctests from docstrings.

If the optional argument `recurse' is false, then @ref{19c1,,DocTestFinder.find()}
will only examine the given object, and not any contained objects.

If the optional argument `exclude_empty' is false, then
@ref{19c1,,DocTestFinder.find()} will include tests for objects with empty docstrings.

@ref{18ff,,DocTestFinder} 定義了以下方法：

@geindex find() (doctest.DocTestFinder 的方法)
@anchor{library/doctest doctest DocTestFinder find}@anchor{19c1}
@deffn {方法} find (obj[, name][, module][, globs][, extraglobs])

Return a list of the @ref{197a,,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{197a,,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{197a,,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{2221,,__dict__}, if specified, or @code{@{@}} otherwise.
If `extraglobs' is not specified, then it defaults to @code{@{@}}.
@end deffn
@end deffn

@node DocTestParser 物件,TestResults 物件,DocTestFinder 物件,Advanced API
@anchor{library/doctest doctest-doctestparser}@anchor{4459}@anchor{library/doctest doctestparser-objects}@anchor{445a}
@subsubsection DocTestParser 物件


@geindex DocTestParser (doctest 中的類別)
@anchor{library/doctest doctest DocTestParser}@anchor{4424}
@deffn {類別} doctest.DocTestParser

A processing class used to extract interactive examples from a string, and use
them to create a @ref{197a,,DocTest} object.

@ref{4424,,DocTestParser} 定義了以下方法：

@geindex get_doctest() (doctest.DocTestParser 的方法)
@anchor{library/doctest doctest DocTestParser get_doctest}@anchor{445b}
@deffn {方法} get_doctest (string, globs, name, filename, lineno)

Extract all doctest examples from the given string, and collect them into a
@ref{197a,,DocTest} object.

`globs', `name', `filename', and `lineno' are attributes for the new
@code{DocTest} object.  See the documentation for @ref{197a,,DocTest} for more
information.
@end deffn

@geindex get_examples() (doctest.DocTestParser 的方法)
@anchor{library/doctest doctest DocTestParser get_examples}@anchor{445c}
@deffn {方法} get_examples (string, name='<string>')

Extract all doctest examples from the given string, and return them as a list
of @ref{4448,,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{445d}
@deffn {方法} parse (string, name='<string>')

Divide the given string into examples and intervening text, and return them as
a list of alternating @ref{4448,,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 物件,DocTestRunner 物件,DocTestParser 物件,Advanced API
@anchor{library/doctest testresults-objects}@anchor{445e}
@subsubsection TestResults 物件


@geindex TestResults (doctest 中的類別)
@anchor{library/doctest doctest TestResults}@anchor{445f}
@deffn {類別} doctest.TestResults (failed, attempted)

@geindex failed (doctest.TestResults 的屬性)
@anchor{library/doctest doctest TestResults failed}@anchor{4460}
@deffn {屬性} failed

失敗的測試數量。
@end deffn

@geindex attempted (doctest.TestResults 的屬性)
@anchor{library/doctest doctest TestResults attempted}@anchor{4461}
@deffn {屬性} attempted

嘗試的測試數量。
@end deffn

@geindex skipped (doctest.TestResults 的屬性)
@anchor{library/doctest doctest TestResults skipped}@anchor{4eb}
@deffn {屬性} skipped

跳過的測試數量。


在 3.13 版被加入.

@end deffn
@end deffn

@node DocTestRunner 物件,OutputChecker 物件,TestResults 物件,Advanced API
@anchor{library/doctest doctest-doctestrunner}@anchor{4462}@anchor{library/doctest doctestrunner-objects}@anchor{4463}
@subsubsection DocTestRunner 物件


@geindex DocTestRunner (doctest 中的類別)
@anchor{library/doctest doctest DocTestRunner}@anchor{4433}
@deffn {類別} doctest.DocTestRunner (checker=None, verbose=None, optionflags=0)

A processing class used to execute and verify the interactive examples in a
@ref{197a,,DocTest}.

The comparison between expected outputs and actual outputs is done by an
@ref{4432,,OutputChecker}.  This comparison may be customized with a number of
option flags; see section @ref{112e,,可選旗標} 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{4e9,,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{4464,,report_start()}, @ref{4465,,report_success()},
@ref{4466,,report_unexpected_exception()}, and @ref{4467,,report_failure()}.

The optional keyword argument `checker' specifies the @ref{4432,,OutputChecker}
object (or drop-in replacement) that should be used to compare the expected
outputs to the actual outputs of doctest examples.

The optional keyword argument `verbose' controls the @ref{4433,,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{112e,,可選旗標}.

The test runner accumulates statistics. The aggregated number of attempted,
failed and skipped examples is also available via the @ref{4468,,tries},
@ref{4469,,failures} and @ref{4ea,,skips} attributes. The @ref{4e9,,run()} and
@ref{443d,,summarize()} methods return a @ref{445f,,TestResults} instance.

@ref{4433,,DocTestRunner} 定義了以下方法：

@geindex report_start() (doctest.DocTestRunner 的方法)
@anchor{library/doctest doctest DocTestRunner report_start}@anchor{4464}
@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 @ref{4433,,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{4e9,,DocTestRunner.run()}.
@end deffn

@geindex report_success() (doctest.DocTestRunner 的方法)
@anchor{library/doctest doctest DocTestRunner report_success}@anchor{4465}
@deffn {方法} report_success (out, test, example, got)

Report that the given example ran successfully.  This method is provided to
allow subclasses of @ref{4433,,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{4e9,,DocTestRunner.run()}.
@end deffn

@geindex report_failure() (doctest.DocTestRunner 的方法)
@anchor{library/doctest doctest DocTestRunner report_failure}@anchor{4467}
@deffn {方法} report_failure (out, test, example, got)

Report that the given example failed.  This method is provided to allow
subclasses of @ref{4433,,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{4e9,,DocTestRunner.run()}.
@end deffn

@geindex report_unexpected_exception() (doctest.DocTestRunner 的方法)
@anchor{library/doctest doctest DocTestRunner report_unexpected_exception}@anchor{4466}
@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 @ref{4433,,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{893,,sys.exc_info()}). `test' is the test containing `example'.  `out' is the
output function that was passed to @ref{4e9,,DocTestRunner.run()}.
@end deffn

@geindex run() (doctest.DocTestRunner 的方法)
@anchor{library/doctest doctest DocTestRunner run}@anchor{4e9}
@deffn {方法} run (test, compileflags=None, out=None, clear_globs=True)

Run the examples in `test' (a @ref{197a,,DocTest} object), and display the
results using the writer function `out'. Return a @ref{445f,,TestResults}
instance.

The examples are run in the namespace @code{test.globs}.  If `clear_globs' is
true (the default), then this namespace will be cleared after the test runs,
to help with garbage collection. If you would like to examine the namespace
after the test completes, then use `clear_globs=False'.

`compileflags' gives the set of flags that should be used by the Python
compiler when running the examples.  If not specified, then it will default to
the set of future-import flags that apply to `globs'.

The output of each example is checked using the @ref{4433,,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{443d}
@deffn {方法} summarize (verbose=None)

Print a summary of all the test cases that have been run by this DocTestRunner,
and return a @ref{445f,,TestResults} instance.

The optional `verbose' argument controls how detailed the summary is.  If the
verbosity is not specified, then the @ref{4433,,DocTestRunner}'s verbosity is
used.
@end deffn

@ref{4424,,DocTestParser} 有以下屬性：

@geindex tries (doctest.DocTestRunner 的屬性)
@anchor{library/doctest doctest DocTestRunner tries}@anchor{4468}
@deffn {屬性} tries

嘗試的範例數量。
@end deffn

@geindex failures (doctest.DocTestRunner 的屬性)
@anchor{library/doctest doctest DocTestRunner failures}@anchor{4469}
@deffn {屬性} failures

失敗的範例數量。
@end deffn

@geindex skips (doctest.DocTestRunner 的屬性)
@anchor{library/doctest doctest DocTestRunner skips}@anchor{4ea}
@deffn {屬性} skips

跳過的範例數量。


在 3.13 版被加入.

@end deffn
@end deffn

@node OutputChecker 物件,,DocTestRunner 物件,Advanced API
@anchor{library/doctest doctest-outputchecker}@anchor{446a}@anchor{library/doctest outputchecker-objects}@anchor{446b}
@subsubsection OutputChecker 物件


@geindex OutputChecker (doctest 中的類別)
@anchor{library/doctest doctest OutputChecker}@anchor{4432}
@deffn {類別} doctest.OutputChecker

A class used to check the whether the actual output from a doctest example
matches the expected output.  @ref{4432,,OutputChecker} defines two methods:
@ref{446c,,check_output()}, which compares a given pair of outputs, and returns @code{True}
if they match; and @ref{446d,,output_difference()}, which returns a string describing
the differences between two outputs.

@ref{4432,,OutputChecker} 定義了以下方法：

@geindex check_output() (doctest.OutputChecker 的方法)
@anchor{library/doctest doctest OutputChecker check_output}@anchor{446c}
@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{112e,,可選旗標} for more information about option flags.
@end deffn

@geindex output_difference() (doctest.OutputChecker 的方法)
@anchor{library/doctest doctest OutputChecker output_difference}@anchor{446d}
@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 偵錯,Soapbox,Advanced API,doctest --- 測試互動式 Python 範例
@anchor{library/doctest debugging}@anchor{446e}@anchor{library/doctest doctest-debugging}@anchor{446f}
@subsubsection 偵錯


Doctest 提供了幾種偵錯 doctest 範例的機制：


@itemize *

@item 
Several functions convert doctests to executable Python programs, which can be
run under the Python debugger, @ref{aa,,pdb}.

@item 
The @ref{4470,,DebugRunner} class is a subclass of @ref{4433,,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{10c,,unittest} cases generated by @ref{fef,,DocTestSuite()} support the
@ref{4471,,debug()} method defined by @ref{2b3,,unittest.TestCase}.

@item 
You can add a call to @ref{272,,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{4472}
@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{4473}
@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{4472,,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{4471}
@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{4473,,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{15d1,,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{49d,,exec()} call to @ref{4474,,pdb.run()}.
@end deffn

@geindex debug_src() (於 doctest 模組中)
@anchor{library/doctest doctest debug_src}@anchor{4475}
@deffn {函式} doctest.debug_src (src, pm=False, globs=None)

Debug the doctests in a string.

This is like function @ref{4471,,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{4471,,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{4470,,DebugRunner} class, and the special exceptions it may raise, are of
most interest to testing framework authors, and will only be sketched here.  See
the source code, and especially @ref{4470,,DebugRunner}'s docstring (which is a
doctest!) for more details:

@geindex DebugRunner (doctest 中的類別)
@anchor{library/doctest doctest DebugRunner}@anchor{4470}
@deffn {類別} doctest.DebugRunner (checker=None, verbose=None, optionflags=0)

A subclass of @ref{4433,,DocTestRunner} that raises an exception as soon as a
failure is encountered.  If an unexpected exception occurs, an
@ref{4476,,UnexpectedException} exception is raised, containing the test, the
example, and the original exception.  If the output doesn't match, then a
@ref{4477,,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{4433,,DocTestRunner} in section @ref{4447,,Advanced API}.
@end deffn

There are two exceptions that may be raised by @ref{4470,,DebugRunner} instances:

@geindex DocTestFailure
@anchor{library/doctest doctest DocTestFailure}@anchor{4477}
@deffn {例外} doctest.DocTestFailure (test, example, got)

An exception raised by @ref{4433,,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{4477,,DocTestFailure} 定義了以下屬性：

@geindex test (doctest.DocTestFailure 的屬性)
@anchor{library/doctest doctest DocTestFailure test}@anchor{4478}
@deffn {屬性} DocTestFailure.test

The @ref{197a,,DocTest} object that was being run when the example failed.
@end deffn

@geindex example (doctest.DocTestFailure 的屬性)
@anchor{library/doctest doctest DocTestFailure example}@anchor{4479}
@deffn {屬性} DocTestFailure.example

The @ref{4448,,Example} that failed.
@end deffn

@geindex got (doctest.DocTestFailure 的屬性)
@anchor{library/doctest doctest DocTestFailure got}@anchor{447a}
@deffn {屬性} DocTestFailure.got

The example's actual output.
@end deffn

@geindex UnexpectedException
@anchor{library/doctest doctest UnexpectedException}@anchor{4476}
@deffn {例外} doctest.UnexpectedException (test, example, exc_info)

An exception raised by @ref{4433,,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{4476,,UnexpectedException} 定義了以下屬性：

@geindex test (doctest.UnexpectedException 的屬性)
@anchor{library/doctest doctest UnexpectedException test}@anchor{447b}
@deffn {屬性} UnexpectedException.test

The @ref{197a,,DocTest} object that was being run when the example failed.
@end deffn

@geindex example (doctest.UnexpectedException 的屬性)
@anchor{library/doctest doctest UnexpectedException example}@anchor{447c}
@deffn {屬性} UnexpectedException.example

The @ref{4448,,Example} that failed.
@end deffn

@geindex exc_info (doctest.UnexpectedException 的屬性)
@anchor{library/doctest doctest UnexpectedException exc_info}@anchor{447d}
@deffn {屬性} UnexpectedException.exc_info

A tuple containing information about the unexpected exception, as returned by
@ref{893,,sys.exc_info()}.
@end deffn

@node Soapbox,,偵錯,doctest --- 測試互動式 Python 範例
@anchor{library/doctest doctest-soapbox}@anchor{447e}@anchor{library/doctest soapbox}@anchor{447f}
@subsubsection Soapbox


As mentioned in the introduction, @ref{3e,,doctest} has grown to have three primary
uses:


@enumerate 

@item 
Checking examples in docstrings.

@item 
回歸測試。

@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 @ref{3e,,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{4413,,testfile()} or @ref{4442,,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{441f,,__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 --- 單元測試框架,unittest mock — mock 物件函式庫,doctest --- 測試互動式 Python 範例,開發工具
@anchor{library/unittest doc}@anchor{4480}@anchor{library/unittest module-unittest}@anchor{10c}@anchor{library/unittest translation-repo}@anchor{4481}@anchor{library/unittest unittest-unit-testing-framework}@anchor{4482}
@subsection @code{unittest} --- 單元測試框架


@geindex module; unittest

`原始碼：'Lib/unittest/__init__.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/unittest/__init__.py}


__________________________________________________________________


（假如你已經熟悉相關基礎的測試概念，你可能會希望跳過以下段落，直接參考 @ref{4483,,assert 方法清單}。）

@ref{10c,,unittest} 原生的單元測試框架最初由 JUnit 開發，和其他程式語言相似有主要的單元測試框架。支援自動化測試，對測試分享安裝與關閉程式碼，集合所有匯總的測試，並且獨立各個測試報告框架。

@ref{10c,,unittest} 用來作為實現支援一些重要的物件導向方法的概念：


@table @asis

@item test fixture

一個 `test fixture' 代表執行一個或多個測試所需要的準備，以及其他相關清理操作，例如可以是建立臨時性的或是代理用 (proxy) 資料庫、目錄、或是啟動一個伺服器程序。

@item test case（測試用例）

一個 `test case' 是一個獨立的單元測試。這是用來確認一個特定設定的輸入的特殊回饋。 @ref{10c,,unittest} 提供一個基礎類別，類別 @ref{2b3,,TestCase}，可以用來建立一個新的測試條例。

@item test suite（測試套件）

`test suite' 是一個搜集測試條例，測試套件，或是兩者皆有。它需要一起被執行並用來匯總測試。

@item test runner（測試執行器）

`test runner' 是一個編排測試執行與提供結果給使用者的一個元件。執行器可以使用圖形化介面，文字介面或是回傳一個特別值用來標示出執行測試的結果。
@end table


@subsubheading 也參考



@table @asis

@item @ref{3e,,doctest} 模組

另一個執行測試的模組，但使用不一樣的測試方法與規範。

@item Simple Smalltalk Testing: With Patterns@footnote{https://web.archive.org/web/20150315073817/http://www.xprogramming.com/testfram.htm}

Kent Beck 的原始論文討論使用 @ref{10c,,unittest} 這樣模式的測試框架。

@item pytest@footnote{https://docs.pytest.org/}

第三方的單元測試框架，但在撰寫測試時使用更輕量的語法。例如： @code{assert func(10) == 42}。

@item The Python Testing Tools Taxonomy@footnote{https://wiki.python.org/moin/PythonTestingToolsTaxonomy}

一份詳細的 Python 測試工具列表，包含 functional testing 框架和mock object 函式庫。

@item Testing in Python Mailing List@footnote{http://lists.idyll.org/listinfo/testing-in-python}

一個專門興趣的群組用來討論 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
* 簡單範例:: 
* 命令列介面: 命令列介面<8>. 
* Test Discovery（測試探索）:: 
* Organizing test code:: 
* Re-using old test code:: 
* Skipping tests and expected failures:: 
* Distinguishing test iterations using subtests:: 
* 類別與函式:: 
* Class and Module Fixtures:: 
* Signal Handling:: 

@end menu

@node 簡單範例,命令列介面<8>,,unittest --- 單元測試框架
@anchor{library/unittest basic-example}@anchor{4484}@anchor{library/unittest unittest-minimal-example}@anchor{4485}
@subsubsection 簡單範例


@ref{10c,,unittest} 模組提供一系列豐富的工具用來建構與執行測試。本節將展示這一系列工具中一部份，它們已能滿足大部份使用者需求。

這是一段簡短的腳本用來測試 3 個字串方法：

@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

測試用例 (test case) 可以透過繼承 @ref{2b3,,unittest.TestCase} 類別來建立。這裡定義了三個獨立的物件方法，名稱皆以 @code{test} 開頭。這樣的命名方式能告知 test runner 哪些物件方法為定義的測試。

每個測試的關鍵為呼叫 @ref{745,,assertEqual()} 來確認是否為期望的結果； @ref{743,,assertTrue()} 或是 @ref{744,,assertFalse()} 用來驗證一個條件式； @ref{749,,assertRaises()} 用來驗證是否觸發一個特定的 exception。使用這些物件方法來取代 @ref{b57,,assert} 陳述句，將能使 test runner 收集所有的測試結果並產生一個報表。

The @ref{153a,,setUp()} and @ref{153b,,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{4486,,Organizing test code}.

最後將顯示一個簡單的方法去執行測試 @ref{11de,,unittest.main()} 提供一個命令列介面測試腳本。當透過命令列執行，輸出結果將會像是：

@example
...
----------------------------------------------------------------------
Ran 3 tests in 0.000s

OK
@end example

在測試時加入 @code{-v} 選項將指示 @ref{11de,,unittest.main()} 提高 verbosity 層級，產生以下的輸出：

@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

以上的例子顯示大多數使用 @ref{10c,,unittest} 特徵足以滿足大多數日常測試的需求。接下來第一部分文件的剩餘部分將繼續探索完整特徵設定。


在 3.11 版的變更: The behavior of returning a value from a test method (other than the default
@code{None} value), is now deprecated.


@node 命令列介面<8>,Test Discovery（測試探索）,簡單範例,unittest --- 單元測試框架
@anchor{library/unittest command-line-interface}@anchor{4487}@anchor{library/unittest unittest-command-line-interface}@anchor{4488}
@subsubsection 命令列介面


單元測試模組可以透過命令列執行測試模組，物件甚至個別的測試方法：

@example
python -m unittest test_module1 test_module2
python -m unittest test_module.TestClass
python -m unittest test_module.TestClass.test_method
@end example

你可以通過一個串列與任何模組名稱的組合，完全符合類別與方法的名稱。

測試模組可以根據檔案路徑指定：

@example
python -m unittest tests/test_something.py
@end example

這允許你使用 shell 檔案名稱補完功能 (filename completion) 來指定測試模組。給定的檔案路徑必須亦能被當作模組 import。此路徑轉換為模組名稱的方式為移除 '.py' 並將路徑分隔符 (path separator) 轉換成 '.'。 假如你的測試檔案無法被 import 成模組，你應該直接執行該測試檔案。

通過增加 -v 的旗標數，可以在你執行測試時得到更多細節（更高的 verbosity）：

@example
python -m unittest -v test_module
@end example

若執行時不代任何引數，將執行 @ref{4489,,Test Discovery（測試探索）}：

@example
python -m unittest
@end example

列出所有命令列選項：

@example
python -m unittest -h
@end example


在 3.2 版的變更: 在早期的版本可以個別執行測試方法和不需要模組或是類別。



在 3.14 版被加入: Output is colorized by default and can be
@ref{1b7,,controlled using environment variables}.


@menu
* 命令列模式選項:: 

@end menu

@node 命令列模式選項,,,命令列介面<8>
@anchor{library/unittest command-line-options}@anchor{448a}
@subsubsection 命令列模式選項


@code{unittest} 支援以下命令列選項：

@geindex unittest 命令列選項; -b
@geindex unittest 命令列選項; --buffer
@anchor{library/unittest cmdoption-unittest-b}@anchor{1532}@anchor{library/unittest cmdoption-unittest-buffer}@anchor{448b}
@deffn {Option} @w{-}b, @w{-}@w{-}buffer

Standard output 與 standard error stream 將在測試執行被緩衝 (buffer)。這些輸出在測試通過時被丟棄。若是測試錯誤或失則，這些輸出將會正常地被印出，並且被加入至錯誤訊息中。
@end deffn

@geindex unittest 命令列選項; -c
@geindex unittest 命令列選項; --catch
@anchor{library/unittest cmdoption-unittest-c}@anchor{1533}@anchor{library/unittest cmdoption-unittest-catch}@anchor{448c}
@deffn {Option} @w{-}c, @w{-}@w{-}catch

@code{Control}-@code{C} 測試執行過程中等待正確的測試結果並回報目前為止所有的測試結果。第二個 @code{Control}-@code{C} 拋出一般例外 @ref{bbc,,KeyboardInterrupt}。

參照 @ref{448d,,Signal Handling} 針對函式提供的功能。
@end deffn

@geindex unittest 命令列選項; -f
@geindex unittest 命令列選項; --failfast
@anchor{library/unittest cmdoption-unittest-f}@anchor{1535}@anchor{library/unittest cmdoption-unittest-failfast}@anchor{448e}
@deffn {Option} @w{-}f, @w{-}@w{-}failfast

在第一次錯誤或是失敗停止執行測試。
@end deffn

@geindex unittest 命令列選項; -k
@anchor{library/unittest cmdoption-unittest-k}@anchor{448f}
@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{1b57,,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 命令列選項; --locals
@anchor{library/unittest cmdoption-unittest-locals}@anchor{4490}
@deffn {Option} @w{-}@w{-}locals

透過 traceback 顯示本地變數。
@end deffn

@geindex unittest 命令列選項; --durations
@anchor{library/unittest cmdoption-unittest-durations}@anchor{4491}
@deffn {Option} @w{-}@w{-}durations N

Show the N slowest test cases (N=0 for all).
@end deffn


在 3.2 版被加入: 增加命令列模式選項 @code{-b} 、 @code{-c} 與 @code{-f}。



在 3.5 版被加入: 命令列選項 @code{--locals}。



在 3.7 版被加入: 命令列選項 @code{-k}。



在 3.12 版被加入: 命令列選項 @code{--durations}。


對執行所有的專案或是一個子集合測試，命令列模式可以可以被用來做測試探索。

@node Test Discovery（測試探索）,Organizing test code,命令列介面<8>,unittest --- 單元測試框架
@anchor{library/unittest test-discovery}@anchor{4492}@anchor{library/unittest unittest-test-discovery}@anchor{4489}
@subsubsection Test Discovery（測試探索）



在 3.2 版被加入.


單元測試支援簡單的 test discovery（測試探索）。為了相容於測試探索，所有的測試檔案都要是@ref{1f05,,模組}或是@ref{1f15,,套件}，並能從專案的最上層目錄中 import（代表它們的檔案名稱必須是有效的 @ref{2164,,identifiers}）。

Test discovery（測試探索）實作在 @ref{11e0,,TestLoader.discover()}，但也可以被用於命令列模式。基本的命令列模式用法如下：

@example
cd project_directory
python -m unittest discover
@end example

@cartouche
@quotation 備註 
@code{python -m unittest} 作為捷徑，其功能相當於 @code{python -m unittest discover}。假如你想傳遞引數至探索測試的話，一定要明確地加入 @code{discover} 子指令。
@end quotation
@end cartouche

@code{discover} 子命令有以下幾個選項：

@geindex unittest-discover 命令列選項; -v
@geindex unittest-discover 命令列選項; --verbose
@anchor{library/unittest cmdoption-unittest-discover-v}@anchor{4493}@anchor{library/unittest cmdoption-unittest-discover-verbose}@anchor{4494}
@deffn {Option} @w{-}v, @w{-}@w{-}verbose

詳細 (verbose) 輸出
@end deffn

@geindex unittest-discover 命令列選項; -s
@geindex unittest-discover 命令列選項; --start-directory
@anchor{library/unittest cmdoption-unittest-discover-s}@anchor{4495}@anchor{library/unittest cmdoption-unittest-discover-start-directory}@anchor{4496}
@deffn {Option} @w{-}s, @w{-}@w{-}start@w{-}directory directory

開始尋找的資料夾（預設為 @code{.}）
@end deffn

@geindex unittest-discover 命令列選項; -p
@geindex unittest-discover 命令列選項; --pattern
@anchor{library/unittest cmdoption-unittest-discover-p}@anchor{4497}@anchor{library/unittest cmdoption-unittest-discover-pattern}@anchor{4498}
@deffn {Option} @w{-}p, @w{-}@w{-}pattern pattern

匹配測試檔案的模式（預設為 @code{test*.py}）
@end deffn

@geindex unittest-discover 命令列選項; -t
@geindex unittest-discover 命令列選項; --top-level-directory
@anchor{library/unittest cmdoption-unittest-discover-t}@anchor{4499}@anchor{library/unittest cmdoption-unittest-discover-top-level-directory}@anchor{449a}
@deffn {Option} @w{-}t, @w{-}@w{-}top@w{-}level@w{-}directory directory

專案的最高階層目錄（預設為開始的資料夾）
@end deffn

@ref{4495,,-s}, @ref{4497,,-p}, 和 @ref{4499,,-t} 選項依照傳遞位置作為引數排序順序。以下兩個命令列被視為等價：

@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{449b,,load_tests protocol}.


在 3.4 版的變更: Test discovery supports @ref{2b2,,namespace packages}.



在 3.11 版的變更: Test discovery dropped the @ref{2b2,,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{2b2,,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 --- 單元測試框架
@anchor{library/unittest organizing-test-code}@anchor{449c}@anchor{library/unittest organizing-tests}@anchor{4486}
@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 @ref{10c,,unittest},
test cases are represented by @ref{2b3,,unittest.TestCase} instances.
To make your own test cases you must write subclasses of
@ref{2b3,,TestCase} or use @ref{19cb,,FunctionTestCase}.

The testing code of a @ref{2b3,,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{2b3,,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{4483,,assert* methods}
provided by the @ref{2b3,,TestCase} base class.  If the test fails, an
exception will be raised with an explanatory message, and @ref{10c,,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{153a,,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{153a,,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{153b,,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{153a,,setUp()} succeeded, @ref{153b,,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{153a,,setUp()}, @ref{153b,,tearDown()}, and @code{__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.  @ref{10c,,unittest} provides a mechanism for
this: the `test suite', represented by @ref{10c,,unittest}'s
@ref{ff0,,TestSuite} class.  In most cases, calling @ref{11de,,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 --- 單元測試框架
@anchor{library/unittest legacy-unit-tests}@anchor{449d}@anchor{library/unittest re-using-old-test-code}@anchor{449e}
@subsubsection Re-using old test code


Some users will find that they have existing test code that they would like to
run from @ref{10c,,unittest}, without converting every old test function to a
@ref{2b3,,TestCase} subclass.

For this reason, @ref{10c,,unittest} provides a @ref{19cb,,FunctionTestCase} class.
This subclass of @ref{2b3,,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{19cb,,FunctionTestCase} can be used to quickly convert an
existing test base over to a @ref{10c,,unittest}-based system, this approach is
not recommended.  Taking the time to set up proper @ref{2b3,,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{3e,,doctest}
module.  If so, @ref{3e,,doctest} provides a @code{DocTestSuite} class that can
automatically build @ref{ff0,,unittest.TestSuite} instances from the existing
@ref{3e,,doctest}-based tests.

@node Skipping tests and expected failures,Distinguishing test iterations using subtests,Re-using old test code,unittest --- 單元測試框架
@anchor{library/unittest skipping-tests-and-expected-failures}@anchor{449f}@anchor{library/unittest unittest-skipping}@anchor{44a0}
@subsubsection Skipping tests and expected failures



在 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{1368,,TestResult}.

Skipping a test is simply a matter of using the @ref{1c87,,skip()} @ref{932,,decorator}
or one of its conditional variants, calling @ref{44a1,,TestCase.skipTest()} within a
@ref{153a,,setUp()} or test method, or raising @ref{11df,,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{153a,,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{44a2,,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{1c87,,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{1c87}
@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{44a3}
@deffn {函式} @@unittest.skipIf (condition, reason)

Skip the decorated test if `condition' is true.
@end deffn

@geindex skipUnless() (於 unittest 模組中)
@anchor{library/unittest unittest skipUnless}@anchor{44a4}
@deffn {函式} @@unittest.skipUnless (condition, reason)

Skip the decorated test unless `condition' is true.
@end deffn

@geindex expectedFailure() (於 unittest 模組中)
@anchor{library/unittest unittest expectedFailure}@anchor{44a2}
@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{11df}
@deffn {例外} unittest.SkipTest (reason)

This exception is raised to skip a test.

Usually you can use @ref{44a1,,TestCase.skipTest()} or one of the skipping
decorators instead of raising this directly.
@end deffn

Skipped tests will not have @ref{153a,,setUp()} or @ref{153b,,tearDown()} run around them.
Skipped classes will not have @ref{c3a,,setUpClass()} or @ref{1538,,tearDownClass()} run.
Skipped modules will not have @ref{c39,,setUpModule()} or @ref{1537,,tearDownModule()} run.

@node Distinguishing test iterations using subtests,類別與函式,Skipping tests and expected failures,unittest --- 單元測試框架
@anchor{library/unittest distinguishing-test-iterations-using-subtests}@anchor{44a5}@anchor{library/unittest subtests}@anchor{11dd}
@subsubsection Distinguishing test iterations using subtests



在 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{11dc,,subTest()} context manager.

舉例來說，以下測試：

@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

會有以下輸出：

@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 類別與函式,Class and Module Fixtures,Distinguishing test iterations using subtests,unittest --- 單元測試框架
@anchor{library/unittest classes-and-functions}@anchor{44a6}@anchor{library/unittest unittest-contents}@anchor{44a7}
@subsubsection 類別與函式


This section describes in depth the API of @ref{10c,,unittest}.

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

@end menu

@node Test cases,Grouping tests,,類別與函式
@anchor{library/unittest test-cases}@anchor{44a8}@anchor{library/unittest testcase-objects}@anchor{44a9}
@subsubsection Test cases


@geindex TestCase (unittest 中的類別)
@anchor{library/unittest unittest TestCase}@anchor{2b3}
@deffn {類別} unittest.TestCase (methodName='runTest')

Instances of the @ref{2b3,,TestCase} class represent the logical test units
in the @ref{10c,,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 @ref{2b3,,TestCase} will run a single base method: the method
named `methodName'.
In most uses of @ref{2b3,,TestCase}, you will neither change
the `methodName' nor reimplement the default @code{runTest()} method.


在 3.2 版的變更: @ref{2b3,,TestCase} can be instantiated successfully without providing a
`methodName'. This makes it easier to experiment with @ref{2b3,,TestCase}
from the interactive interpreter.


@ref{2b3,,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{153a}
@deffn {方法} setUp ()

Method called to prepare the test fixture.  This is called immediately
before calling the test method; other than @ref{8b0,,AssertionError} or @ref{11df,,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{153b}
@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{8b0,,AssertionError} or @ref{11df,,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{153a,,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{c3a}
@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{489,,classmethod()}:

@example
@@classmethod
def setUpClass(cls):
    ...
@end example

更多細節請見 @ref{44aa,,Class and Module Fixtures}。


在 3.2 版被加入.

@end deffn

@geindex tearDownClass() (unittest.TestCase 的方法)
@anchor{library/unittest unittest TestCase tearDownClass}@anchor{1538}
@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{489,,classmethod()}:

@example
@@classmethod
def tearDownClass(cls):
    ...
@end example

更多細節請見 @ref{44aa,,Class and Module Fixtures}。


在 3.2 版被加入.

@end deffn

@geindex run() (unittest.TestCase 的方法)
@anchor{library/unittest unittest TestCase run}@anchor{1367}
@deffn {方法} run (result=None)

Run the test, collecting the result into the @ref{1368,,TestResult} object
passed as `result'.  If `result' is omitted or @code{None}, a temporary
result object is created (by calling the @ref{44ab,,defaultTestResult()}
method) and used. The result object is returned to @ref{1367,,run()}'s
caller.

The same effect may be had by simply calling the @ref{2b3,,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{44a1}
@deffn {方法} skipTest (reason)

Calling this during a test method or @ref{153a,,setUp()} skips the current
test.  See @ref{44a0,,Skipping tests and expected failures} for more information.


在 3.1 版被加入.

@end deffn

@geindex subTest() (unittest.TestCase 的方法)
@anchor{library/unittest unittest TestCase subTest}@anchor{11dc}
@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.

更多資訊請見 @ref{11dd,,Distinguishing test iterations using subtests}。


在 3.4 版被加入.

@end deffn

@geindex debug() (unittest.TestCase 的方法)
@anchor{library/unittest unittest TestCase debug}@anchor{1b4b}
@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{4483}
The @ref{2b3,,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

方法

@tab

Checks that

@tab

New in

@item

@ref{745,,assertEqual(a@comma{} b)}

@tab

@code{a == b}

@tab

@item

@ref{746,,assertNotEqual(a@comma{} b)}

@tab

@code{a != b}

@tab

@item

@ref{743,,assertTrue(x)}

@tab

@code{bool(x) is True}

@tab

@item

@ref{744,,assertFalse(x)}

@tab

@code{bool(x) is False}

@tab

@item

@ref{153c,,assertIs(a@comma{} b)}

@tab

@code{a is b}

@tab

3.1

@item

@ref{153d,,assertIsNot(a@comma{} b)}

@tab

@code{a is not b}

@tab

3.1

@item

@ref{148b,,assertIsNone(x)}

@tab

@code{x is None}

@tab

3.1

@item

@ref{148c,,assertIsNotNone(x)}

@tab

@code{x is not None}

@tab

3.1

@item

@ref{1545,,assertIn(a@comma{} b)}

@tab

@code{a in b}

@tab

3.1

@item

@ref{1546,,assertNotIn(a@comma{} b)}

@tab

@code{a not in b}

@tab

3.1

@item

@ref{153e,,assertIsInstance(a@comma{} b)}

@tab

@code{isinstance(a, b)}

@tab

3.2

@item

@ref{153f,,assertNotIsInstance(a@comma{} b)}

@tab

@code{not isinstance(a, b)}

@tab

3.2

@item

@ref{2b6,,assertIsSubclass(a@comma{} b)}

@tab

@code{issubclass(a, b)}

@tab

3.14

@item

@ref{2b7,,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{1536,,longMessage}).
Note that the `msg' keyword argument can be passed to @ref{749,,assertRaises()},
@ref{74b,,assertRaisesRegex()}, @ref{1365,,assertWarns()}, @ref{1366,,assertWarnsRegex()}
only when they are used as a context manager.

@geindex assertEqual() (unittest.TestCase 的方法)
@anchor{library/unittest unittest TestCase assertEqual}@anchor{745}
@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{1549,,addTypeEqualityFunc()} the type-specific equality
function will be called in order to generate a more useful default
error message (see also the @ref{44ac,,list of type-specific methods}).


在 3.1 版的變更: Added the automatic calling of type-specific equality function.



在 3.2 版的變更: @ref{1544,,assertMultiLineEqual()} added as the default type equality
function for comparing strings.

@end deffn

@geindex assertNotEqual() (unittest.TestCase 的方法)
@anchor{library/unittest unittest TestCase assertNotEqual}@anchor{746}
@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{743}
@deffn {方法} assertTrue (expr, msg=None)
@anchor{library/unittest unittest TestCase assertFalse}@anchor{744}
@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{153c}
@deffn {方法} assertIs (first, second, msg=None)
@anchor{library/unittest unittest TestCase assertIsNot}@anchor{153d}
@deffnx {方法} assertIsNot (first, second, msg=None)

Test that `first' and `second' are (or are not) the same object.


在 3.1 版被加入.

@end deffn

@geindex assertIsNone() (unittest.TestCase 的方法)
@geindex assertIsNotNone() (unittest.TestCase 的方法)
@anchor{library/unittest unittest TestCase assertIsNone}@anchor{148b}
@deffn {方法} assertIsNone (expr, msg=None)
@anchor{library/unittest unittest TestCase assertIsNotNone}@anchor{148c}
@deffnx {方法} assertIsNotNone (expr, msg=None)

Test that `expr' is (or is not) @code{None}.


在 3.1 版被加入.

@end deffn

@geindex assertIn() (unittest.TestCase 的方法)
@geindex assertNotIn() (unittest.TestCase 的方法)
@anchor{library/unittest unittest TestCase assertIn}@anchor{1545}
@deffn {方法} assertIn (member, container, msg=None)
@anchor{library/unittest unittest TestCase assertNotIn}@anchor{1546}
@deffnx {方法} assertNotIn (member, container, msg=None)

Test that `member' is (or is not) in `container'.


在 3.1 版被加入.

@end deffn

@geindex assertIsInstance() (unittest.TestCase 的方法)
@geindex assertNotIsInstance() (unittest.TestCase 的方法)
@anchor{library/unittest unittest TestCase assertIsInstance}@anchor{153e}
@deffn {方法} assertIsInstance (obj, cls, msg=None)
@anchor{library/unittest unittest TestCase assertNotIsInstance}@anchor{153f}
@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{2ad,,isinstance()}).
To check for the exact type, use @ref{153c,,assertIs(type(obj)@comma{} cls)}.


在 3.2 版被加入.

@end deffn

@geindex assertIsSubclass() (unittest.TestCase 的方法)
@geindex assertNotIsSubclass() (unittest.TestCase 的方法)
@anchor{library/unittest unittest TestCase assertIsSubclass}@anchor{2b6}
@deffn {方法} assertIsSubclass (cls, superclass, msg=None)
@anchor{library/unittest unittest TestCase assertNotIsSubclass}@anchor{2b7}
@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{9bd,,issubclass()}).
To check for the exact type, use @ref{153c,,assertIs(cls@comma{} superclass)}.


在 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

方法

@tab

Checks that

@tab

New in

@item

@ref{749,,assertRaises(exc@comma{} fun@comma{} *args@comma{} **kwds)}

@tab

@code{fun(*args, **kwds)} 會引發 `exc'

@tab

@item

@ref{74b,,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{1365,,assertWarns(warn@comma{} fun@comma{} *args@comma{} **kwds)}

@tab

@code{fun(*args, **kwds)} 會引發 `warn'

@tab

3.2

@item

@ref{1366,,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{a52,,assertLogs(logger@comma{} level)}

@tab

The @code{with} block logs on `logger'
with minimum `level'

@tab

3.4

@item

@ref{a51,,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{749}
@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
@ref{749,,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, @ref{749,,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 版的變更: 新增 @ref{749,,assertRaises()} 可作為情境管理器使用的能力。



在 3.2 版的變更: 新增 @code{exception} 屬性。



在 3.3 版的變更: 新增作為情境管理器使用時的 `msg' 引數。

@end deffn

@geindex assertRaisesRegex() (unittest.TestCase 的方法)
@anchor{library/unittest unittest TestCase assertRaisesRegex}@anchor{74b}
@deffn {方法} assertRaisesRegex (exception, regex, callable, *args, **kwds)

@deffnx {方法} assertRaisesRegex (exception, regex, *, msg=None)

Like @ref{749,,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{142d,,re.search()}.  Examples:

@example
self.assertRaisesRegex(ValueError, "invalid literal for.*XYZ'$",
                       int, 'XYZ')
@end example

或是：

@example
with self.assertRaisesRegex(ValueError, 'literal'):
   int('XYZ')
@end example


在 3.1 版被加入: 以 @code{assertRaisesRegexp} 為名新增。



在 3.2 版的變更: 重新命名為 @ref{74b,,assertRaisesRegex()}。



在 3.3 版的變更: 新增作為情境管理器使用時的 `msg' 引數。

@end deffn

@geindex assertWarns() (unittest.TestCase 的方法)
@anchor{library/unittest unittest TestCase assertWarns}@anchor{1365}
@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
@ref{1365,,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, @ref{1365,,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

This method works regardless of the warning filters in place when it
is called.


在 3.2 版被加入.



在 3.3 版的變更: 新增作為情境管理器使用時的 `msg' 引數。

@end deffn

@geindex assertWarnsRegex() (unittest.TestCase 的方法)
@anchor{library/unittest unittest TestCase assertWarnsRegex}@anchor{1366}
@deffn {方法} assertWarnsRegex (warning, regex, callable, *args, **kwds)

@deffnx {方法} assertWarnsRegex (warning, regex, *, msg=None)

Like @ref{1365,,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{142d,,re.search()}.  Example:

@example
self.assertWarnsRegex(DeprecationWarning,
                      r'legacy_function\(\) is deprecated',
                      legacy_function, 'XYZ')
@end example

或是：

@example
with self.assertWarnsRegex(RuntimeWarning, 'unsafe frobnicating'):
    frobnicate('/etc/passwd')
@end example


在 3.2 版被加入.



在 3.3 版的變更: 新增作為情境管理器使用時的 `msg' 引數。

@end deffn

@geindex assertLogs() (unittest.TestCase 的方法)
@anchor{library/unittest unittest TestCase assertLogs}@anchor{a52}
@deffn {方法} assertLogs (logger=None, level=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{d3e,,logging.Logger} object or a
@ref{169,,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{1fa7,,logging.ERROR}).  The default is @ref{1fa5,,logging.INFO}.

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{44ad}
@deffn {屬性} records

A list of @ref{11e1,,logging.LogRecord} objects of the matching
log messages.
@end deffn

@geindex output (unittest.TestCase 的屬性)
@anchor{library/unittest unittest TestCase output}@anchor{44ae}
@deffn {屬性} output

A list of @ref{169,,str} objects with the formatted output of
matching messages.
@end deffn

範例：

@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


在 3.4 版被加入.

@end deffn

@geindex assertNoLogs() (unittest.TestCase 的方法)
@anchor{library/unittest unittest TestCase assertNoLogs}@anchor{a51}
@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{d3e,,logging.Logger} object or a
@ref{169,,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{1fa7,,logging.ERROR}).  The default is @ref{1fa5,,logging.INFO}.

Unlike @ref{a52,,assertLogs()}, nothing will be returned by the context
manager.


在 3.10 版被加入.

@end deffn

There are also other methods used to perform more specific checks, such as:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxx} 
@headitem

方法

@tab

Checks that

@tab

New in

@item

@ref{747,,assertAlmostEqual(a@comma{} b)}

@tab

@code{round(a-b, 7) == 0}

@tab

@item

@ref{748,,assertNotAlmostEqual(a@comma{} b)}

@tab

@code{round(a-b, 7) != 0}

@tab

@item

@ref{1540,,assertGreater(a@comma{} b)}

@tab

@code{a > b}

@tab

3.1

@item

@ref{1541,,assertGreaterEqual(a@comma{} b)}

@tab

@code{a >= b}

@tab

3.1

@item

@ref{1542,,assertLess(a@comma{} b)}

@tab

@code{a < b}

@tab

3.1

@item

@ref{1543,,assertLessEqual(a@comma{} b)}

@tab

@code{a <= b}

@tab

3.1

@item

@ref{74a,,assertRegex(s@comma{} r)}

@tab

@code{r.search(s)}

@tab

3.1

@item

@ref{74c,,assertNotRegex(s@comma{} r)}

@tab

@code{not r.search(s)}

@tab

3.2

@item

@ref{142b,,assertCountEqual(a@comma{} b)}

@tab

`a' and `b' have the same
elements in the same number,
regardless of their order.

@tab

3.2

@item

@ref{2b8,,assertStartsWith(a@comma{} b)}

@tab

@code{a.startswith(b)}

@tab

3.14

@item

@ref{2b9,,assertNotStartsWith(a@comma{} b)}

@tab

@code{not a.startswith(b)}

@tab

3.14

@item

@ref{2ba,,assertEndsWith(a@comma{} b)}

@tab

@code{a.endswith(b)}

@tab

3.14

@item

@ref{2bb,,assertNotEndsWith(a@comma{} b)}

@tab

@code{not a.endswith(b)}

@tab

3.14

@item

@ref{2b4,,assertHasAttr(a@comma{} b)}

@tab

@code{hastattr(a, b)}

@tab

3.14

@item

@ref{2b5,,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{747}
@deffn {方法} assertAlmostEqual (first, second, places=7, msg=None, delta=None)
@anchor{library/unittest unittest TestCase assertNotAlmostEqual}@anchor{748}
@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{14db,,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{198,,TypeError}.


在 3.2 版的變更: @ref{747,,assertAlmostEqual()} automatically considers almost equal objects
that compare equal.  @ref{748,,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{1540}
@deffn {方法} assertGreater (first, second, msg=None)
@anchor{library/unittest unittest TestCase assertGreaterEqual}@anchor{1541}
@deffnx {方法} assertGreaterEqual (first, second, msg=None)
@anchor{library/unittest unittest TestCase assertLess}@anchor{1542}
@deffnx {方法} assertLess (first, second, msg=None)
@anchor{library/unittest unittest TestCase assertLessEqual}@anchor{1543}
@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


在 3.1 版被加入.

@end deffn

@geindex assertRegex() (unittest.TestCase 的方法)
@geindex assertNotRegex() (unittest.TestCase 的方法)
@anchor{library/unittest unittest TestCase assertRegex}@anchor{74a}
@deffn {方法} assertRegex (text, regex, msg=None)
@anchor{library/unittest unittest TestCase assertNotRegex}@anchor{74c}
@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{142d,,re.search()}.


在 3.1 版被加入: 以 @code{assertRegexpMatches} 為名新增。



在 3.2 版的變更: @code{assertRegexpMatches()} 方法已重新命名為 @ref{74a,,assertRegex()}。



在 3.2 版被加入: @ref{74c,,assertNotRegex()}。

@end deffn

@geindex assertCountEqual() (unittest.TestCase 的方法)
@anchor{library/unittest unittest TestCase assertCountEqual}@anchor{142b}
@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.


在 3.2 版被加入.

@end deffn

@geindex assertStartsWith() (unittest.TestCase 的方法)
@anchor{library/unittest unittest TestCase assertStartsWith}@anchor{2b8}
@deffn {方法} assertStartsWith (s, prefix, msg=None)
@end deffn

@geindex assertNotStartsWith() (unittest.TestCase 的方法)
@anchor{library/unittest unittest TestCase assertNotStartsWith}@anchor{2b9}
@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.


在 3.14 版被加入.

@end deffn

@geindex assertEndsWith() (unittest.TestCase 的方法)
@anchor{library/unittest unittest TestCase assertEndsWith}@anchor{2ba}
@deffn {方法} assertEndsWith (s, suffix, msg=None)
@end deffn

@geindex assertNotEndsWith() (unittest.TestCase 的方法)
@anchor{library/unittest unittest TestCase assertNotEndsWith}@anchor{2bb}
@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.


在 3.14 版被加入.

@end deffn

@geindex assertHasAttr() (unittest.TestCase 的方法)
@anchor{library/unittest unittest TestCase assertHasAttr}@anchor{2b4}
@deffn {方法} assertHasAttr (obj, name, msg=None)
@end deffn

@geindex assertNotHasAttr() (unittest.TestCase 的方法)
@anchor{library/unittest unittest TestCase assertNotHasAttr}@anchor{2b5}
@deffn {方法} assertNotHasAttr (obj, name, msg=None)

Test that the object `obj' has (or has not) an attribute `name'.


在 3.14 版被加入.

@end deffn
@anchor{library/unittest type-specific-methods}@anchor{44ac}
The @ref{745,,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{1549,,addTypeEqualityFunc()}:

@geindex addTypeEqualityFunc() (unittest.TestCase 的方法)
@anchor{library/unittest unittest TestCase addTypeEqualityFunc}@anchor{1549}
@deffn {方法} addTypeEqualityFunc (typeobj, function)

Registers a type-specific method called by @ref{745,,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 @ref{745,,assertEqual()} does.  It must raise
@ref{4443,,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.


在 3.1 版被加入.

@end deffn

The list of type-specific methods automatically used by
@ref{745,,assertEqual()} are summarized in the following table.  Note
that it's usually not necessary to invoke these methods directly.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxx} 
@headitem

方法

@tab

Used to compare

@tab

New in

@item

@ref{1544,,assertMultiLineEqual(a@comma{} b)}

@tab

字串

@tab

3.1

@item

@ref{148a,,assertSequenceEqual(a@comma{} b)}

@tab

序列

@tab

3.1

@item

@ref{1488,,assertListEqual(a@comma{} b)}

@tab

串列

@tab

3.1

@item

@ref{1489,,assertTupleEqual(a@comma{} b)}

@tab

元組

@tab

3.1

@item

@ref{1486,,assertSetEqual(a@comma{} b)}

@tab

集合或凍結集合

@tab

3.1

@item

@ref{1487,,assertDictEqual(a@comma{} b)}

@tab

字典

@tab

3.1

@end multitable


@geindex assertMultiLineEqual() (unittest.TestCase 的方法)
@anchor{library/unittest unittest TestCase assertMultiLineEqual}@anchor{1544}
@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{745,,assertEqual()}.


在 3.1 版被加入.

@end deffn

@geindex assertSequenceEqual() (unittest.TestCase 的方法)
@anchor{library/unittest unittest TestCase assertSequenceEqual}@anchor{148a}
@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{745,,assertEqual()}, but
it's used to implement @ref{1488,,assertListEqual()} and
@ref{1489,,assertTupleEqual()}.


在 3.1 版被加入.

@end deffn

@geindex assertListEqual() (unittest.TestCase 的方法)
@geindex assertTupleEqual() (unittest.TestCase 的方法)
@anchor{library/unittest unittest TestCase assertListEqual}@anchor{1488}
@deffn {方法} assertListEqual (first, second, msg=None)
@anchor{library/unittest unittest TestCase assertTupleEqual}@anchor{1489}
@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{745,,assertEqual()}.


在 3.1 版被加入.

@end deffn

@geindex assertSetEqual() (unittest.TestCase 的方法)
@anchor{library/unittest unittest TestCase assertSetEqual}@anchor{1486}
@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{745,,assertEqual()}.

Fails if either of `first' or `second' does not have a @code{set.difference()}
method.


在 3.1 版被加入.

@end deffn

@geindex assertDictEqual() (unittest.TestCase 的方法)
@anchor{library/unittest unittest TestCase assertDictEqual}@anchor{1487}
@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{745,,assertEqual()}.


在 3.1 版被加入.

@end deffn
@anchor{library/unittest other-methods-and-attrs}@anchor{44af}
Finally the @ref{2b3,,TestCase} provides the following methods and attributes:

@geindex fail() (unittest.TestCase 的方法)
@anchor{library/unittest unittest TestCase fail}@anchor{44b0}
@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{4443}
@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{8b0,,AssertionError}.
@end deffn

@geindex longMessage (unittest.TestCase 的屬性)
@anchor{library/unittest unittest TestCase longMessage}@anchor{1536}
@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.


在 3.1 版被加入.

@end deffn

@geindex maxDiff (unittest.TestCase 的屬性)
@anchor{library/unittest unittest TestCase maxDiff}@anchor{142c}
@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{148a,,assertSequenceEqual()} (including all the sequence comparison
methods that delegate to it), @ref{1487,,assertDictEqual()} and
@ref{1544,,assertMultiLineEqual()}.

Setting @code{maxDiff} to @code{None} means that there is no maximum length of
diffs.


在 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{44b1}
@deffn {方法} countTestCases ()

Return the number of tests represented by this test object.  For
@ref{2b3,,TestCase} instances, this will always be @code{1}.
@end deffn

@geindex defaultTestResult() (unittest.TestCase 的方法)
@anchor{library/unittest unittest TestCase defaultTestResult}@anchor{44ab}
@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{1367,,run()} method).

For @ref{2b3,,TestCase} instances, this will always be an instance of
@ref{1368,,TestResult}; subclasses of @ref{2b3,,TestCase} should override this
as necessary.
@end deffn

@geindex id() (unittest.TestCase 的方法)
@anchor{library/unittest unittest TestCase id}@anchor{44b2}
@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{44b3}
@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{74d,,TextTestResult} in Python 3.2.

@end deffn

@geindex addCleanup() (unittest.TestCase 的方法)
@anchor{library/unittest unittest TestCase addCleanup}@anchor{c6b}
@deffn {方法} addCleanup (function, /, *args, **kwargs)

Add a function to be called after @ref{153b,,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
@ref{c6b,,addCleanup()} when they are added.

If @ref{153a,,setUp()} fails, meaning that @ref{153b,,tearDown()} is not called,
then any cleanup functions added will still be called.


在 3.1 版被加入.

@end deffn

@geindex enterContext() (unittest.TestCase 的方法)
@anchor{library/unittest unittest TestCase enterContext}@anchor{8c0}
@deffn {方法} enterContext (cm)

Enter the supplied @ref{1e1,,context manager}.  If successful, also
add its @ref{1501,,__exit__()} method as a cleanup function by
@ref{c6b,,addCleanup()} and return the result of the
@ref{7dd,,__enter__()} method.


在 3.11 版被加入.

@end deffn

@geindex doCleanups() (unittest.TestCase 的方法)
@anchor{library/unittest unittest TestCase doCleanups}@anchor{1539}
@deffn {方法} doCleanups ()

This method is called unconditionally after @ref{153b,,tearDown()}, or
after @ref{153a,,setUp()} if @ref{153a,,setUp()} raises an exception.

It is responsible for calling all the cleanup functions added by
@ref{c6b,,addCleanup()}. If you need cleanup functions to be called
`prior' to @ref{153b,,tearDown()} then you can call @ref{1539,,doCleanups()}
yourself.

@ref{1539,,doCleanups()} pops methods off the stack of cleanup
functions one at a time, so it can be called at any time.


在 3.1 版被加入.

@end deffn

@geindex addClassCleanup() (unittest.TestCase 的類別方法)
@anchor{library/unittest unittest TestCase addClassCleanup}@anchor{c38}
@deffn {方法} classmethod addClassCleanup (function, /, *args, **kwargs)

Add a function to be called after @ref{1538,,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
@ref{c38,,addClassCleanup()} when they are added.

If @ref{c3a,,setUpClass()} fails, meaning that @ref{1538,,tearDownClass()} is not
called, then any cleanup functions added will still be called.


在 3.8 版被加入.

@end deffn

@geindex enterClassContext() (unittest.TestCase 的類別方法)
@anchor{library/unittest unittest TestCase enterClassContext}@anchor{8c1}
@deffn {方法} classmethod enterClassContext (cm)

Enter the supplied @ref{1e1,,context manager}.  If successful, also
add its @ref{1501,,__exit__()} method as a cleanup function by
@ref{c38,,addClassCleanup()} and return the result of the
@ref{7dd,,__enter__()} method.


在 3.11 版被加入.

@end deffn

@geindex doClassCleanups() (unittest.TestCase 的類別方法)
@anchor{library/unittest unittest TestCase doClassCleanups}@anchor{44b4}
@deffn {方法} classmethod doClassCleanups ()

This method is called unconditionally after @ref{1538,,tearDownClass()}, or
after @ref{c3a,,setUpClass()} if @ref{c3a,,setUpClass()} raises an exception.

It is responsible for calling all the cleanup functions added by
@ref{c38,,addClassCleanup()}. If you need cleanup functions to be called
`prior' to @ref{1538,,tearDownClass()} then you can call
@ref{44b4,,doClassCleanups()} yourself.

@ref{44b4,,doClassCleanups()} pops methods off the stack of cleanup
functions one at a time, so it can be called at any time.


在 3.8 版被加入.

@end deffn
@end deffn

@geindex IsolatedAsyncioTestCase (unittest 中的類別)
@anchor{library/unittest unittest IsolatedAsyncioTestCase}@anchor{35f}
@deffn {類別} unittest.IsolatedAsyncioTestCase (methodName='runTest')

This class provides an API similar to @ref{2b3,,TestCase} and also accepts
coroutines as test functions.


在 3.8 版被加入.


@geindex loop_factory (unittest.IsolatedAsyncioTestCase 的屬性)
@anchor{library/unittest unittest IsolatedAsyncioTestCase loop_factory}@anchor{44b5}
@deffn {屬性} loop_factory

The `loop_factory' passed to @ref{2f4,,asyncio.Runner}. Override
in subclasses with @ref{19b9,,asyncio.EventLoop} to avoid using the
asyncio policy system.


在 3.13 版被加入.

@end deffn

@geindex asyncSetUp() (unittest.IsolatedAsyncioTestCase 的方法)
@anchor{library/unittest unittest IsolatedAsyncioTestCase asyncSetUp}@anchor{44b6}
@deffn {方法} async asyncSetUp ()

Method called to prepare the test fixture. This is called after @code{setUp()}.
This is called immediately before calling the test method; other than
@ref{8b0,,AssertionError} or @ref{11df,,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{44b7}
@deffn {方法} async asyncTearDown ()

Method called immediately after the test method has been called and the
result recorded.  This is called before @code{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{8b0,,AssertionError} or @ref{11df,,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{44b6,,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{44b8}
@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{8c2}
@deffn {方法} async enterAsyncContext (cm)

Enter the supplied @ref{7e8,,asynchronous context manager}.  If successful,
also add its @ref{18f8,,__aexit__()} method as a cleanup function by
@ref{44b8,,addAsyncCleanup()} and return the result of the
@ref{22cd,,__aenter__()} method.


在 3.11 版被加入.

@end deffn

@geindex run() (unittest.IsolatedAsyncioTestCase 的方法)
@anchor{library/unittest unittest IsolatedAsyncioTestCase run}@anchor{44b9}
@deffn {方法} run (result=None)

Sets up a new event loop to run the test, collecting the result into
the @ref{1368,,TestResult} object passed as `result'.  If `result' is
omitted or @code{None}, a temporary result object is created (by calling
the @code{defaultTestResult()} method) and used. The result object is
returned to @ref{44b9,,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{19cb}
@deffn {類別} unittest.FunctionTestCase (testFunc, setUp=None, tearDown=None, description=None)

This class implements the portion of the @ref{2b3,,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
@ref{10c,,unittest}-based test framework.
@end deffn

@node Grouping tests,Loading and running tests,Test cases,類別與函式
@anchor{library/unittest grouping-tests}@anchor{44ba}@anchor{library/unittest testsuite-objects}@anchor{44bb}
@subsubsection Grouping tests


@geindex TestSuite (unittest 中的類別)
@anchor{library/unittest unittest TestSuite}@anchor{ff0}
@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 @ref{ff0,,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.

@ref{ff0,,TestSuite} objects behave much like @ref{2b3,,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 @ref{ff0,,TestSuite} instances:

@geindex addTest() (unittest.TestSuite 的方法)
@anchor{library/unittest unittest TestSuite addTest}@anchor{44bc}
@deffn {方法} addTest (test)

Add a @ref{2b3,,TestCase} or @ref{ff0,,TestSuite} to the suite.
@end deffn

@geindex addTests() (unittest.TestSuite 的方法)
@anchor{library/unittest unittest TestSuite addTests}@anchor{44bd}
@deffn {方法} addTests (tests)

Add all the tests from an iterable of @ref{2b3,,TestCase} and @ref{ff0,,TestSuite}
instances to this test suite.

This is equivalent to iterating over `tests', calling @ref{44bc,,addTest()} for
each element.
@end deffn

@ref{ff0,,TestSuite} shares the following methods with @ref{2b3,,TestCase}:

@geindex run() (unittest.TestSuite 的方法)
@anchor{library/unittest unittest TestSuite run}@anchor{44be}
@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{1367,,TestCase.run()}, @ref{44be,,TestSuite.run()} requires the result object to
be passed in.
@end deffn

@geindex debug() (unittest.TestSuite 的方法)
@anchor{library/unittest unittest TestSuite debug}@anchor{44bf}
@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{44c0}
@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{1224}
@deffn {方法} __iter__ ()

Tests grouped by a @ref{ff0,,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{44be,,TestSuite.run()} must be the
same for each call iteration. After @ref{44be,,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 @ref{ff0,,TestSuite} accessed tests directly rather
than through iteration, so overriding @code{__iter__()} wasn't sufficient
for providing tests.



在 3.4 版的變更: In earlier versions the @ref{ff0,,TestSuite} held references to each
@ref{2b3,,TestCase} after @ref{44be,,TestSuite.run()}. Subclasses can restore
that behavior by overriding @code{TestSuite._removeTestAtIndex()}.

@end deffn

In the typical usage of a @ref{ff0,,TestSuite} object, the @ref{44be,,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,類別與函式
@anchor{library/unittest loading-and-running-tests}@anchor{44c1}
@subsubsection Loading and running tests


@geindex TestLoader (unittest 中的類別)
@anchor{library/unittest unittest TestLoader}@anchor{58d}
@deffn {類別} unittest.TestLoader

The @ref{58d,,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
@ref{10c,,unittest} module provides an instance that can be shared as
@ref{44c2,,unittest.defaultTestLoader}.  Using a subclass or instance, however,
allows customization of some configurable properties.

@ref{58d,,TestLoader} objects have the following attributes:

@geindex errors (unittest.TestLoader 的屬性)
@anchor{library/unittest unittest TestLoader errors}@anchor{1087}
@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.


在 3.5 版被加入.

@end deffn

@ref{58d,,TestLoader} objects have the following methods:

@geindex loadTestsFromTestCase() (unittest.TestLoader 的方法)
@anchor{library/unittest unittest TestLoader loadTestsFromTestCase}@anchor{58f}
@deffn {方法} loadTestsFromTestCase (testCaseClass)

Return a suite of all test cases contained in the @ref{2b3,,TestCase}-derived
@code{testCaseClass}.

A test case instance is created for each method named by
@ref{590,,getTestCaseNames()}. By default these are the method names
beginning with @code{test}. If @ref{590,,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{58e}
@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{2b3,,TestCase} and
creates an instance of the class for each test method defined for the
class.

@cartouche
@quotation 備註 
While using a hierarchy of @ref{2b3,,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{449b,,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{1547}
@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{ff0,,TestSuite} instance, or a callable object which returns a
@ref{2b3,,TestCase} or @ref{ff0,,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{2b3,,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{653,,ImportError} or @ref{5e8,,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{44c3}
@deffn {方法} loadTestsFromNames (names, module=None)

Similar to @ref{1547,,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{590}
@deffn {方法} getTestCaseNames (testCaseClass)

Return a sorted sequence of method names found within `testCaseClass';
this should be a subclass of @ref{2b3,,TestCase}.
@end deffn

@geindex discover() (unittest.TestLoader 的方法)
@anchor{library/unittest unittest TestLoader discover}@anchor{11e0}
@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{11df,,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.


在 3.2 版被加入.



在 3.4 版的變更: Modules that raise @ref{11df,,SkipTest} on import are recorded as skips,
not errors.

`start_dir' can be a @ref{2b2,,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{2b2,,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{2b2,,namespace package}.

@end deffn

The following attributes of a @ref{58d,,TestLoader} can be configured either by
subclassing or assignment on an instance:

@geindex testMethodPrefix (unittest.TestLoader 的屬性)
@anchor{library/unittest unittest TestLoader testMethodPrefix}@anchor{44c4}
@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{590,,getTestCaseNames()} and all the @code{loadTestsFrom*}
methods.
@end deffn

@geindex sortTestMethodsUsing (unittest.TestLoader 的屬性)
@anchor{library/unittest unittest TestLoader sortTestMethodsUsing}@anchor{44c5}
@deffn {屬性} sortTestMethodsUsing

Function to be used to compare method names when sorting them in
@ref{590,,getTestCaseNames()} and all the @code{loadTestsFrom*} methods.
@end deffn

@geindex suiteClass (unittest.TestLoader 的屬性)
@anchor{library/unittest unittest TestLoader suiteClass}@anchor{1548}
@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{ff0,,TestSuite} class.

This affects all the @code{loadTestsFrom*} methods.
@end deffn

@geindex testNamePatterns (unittest.TestLoader 的屬性)
@anchor{library/unittest unittest TestLoader testNamePatterns}@anchor{44c6}
@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{1b57,,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.


在 3.7 版被加入.

@end deffn
@end deffn

@geindex TestResult (unittest 中的類別)
@anchor{library/unittest unittest TestResult}@anchor{1368}
@deffn {類別} unittest.TestResult

This class is used to compile information about which tests have succeeded
and which have failed.

A @ref{1368,,TestResult} object stores the results of a set of tests.  The
@ref{2b3,,TestCase} and @ref{ff0,,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 @ref{10c,,unittest} may want access to the
@ref{1368,,TestResult} object generated by running a set of tests for reporting
purposes; a @ref{1368,,TestResult} instance is returned by the
@code{TestRunner.run()} method for this purpose.

@ref{1368,,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{44c7}
@deffn {屬性} errors

A list containing 2-tuples of @ref{2b3,,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{44c8}
@deffn {屬性} failures

A list containing 2-tuples of @ref{2b3,,TestCase} instances and strings
holding formatted tracebacks. Each tuple represents a test where a failure
was explicitly signalled using the @ref{4483,,assert* methods}.
@end deffn

@geindex skipped (unittest.TestResult 的屬性)
@anchor{library/unittest unittest TestResult skipped}@anchor{44c9}
@deffn {屬性} skipped

A list containing 2-tuples of @ref{2b3,,TestCase} instances and strings
holding the reason for skipping the test.


在 3.1 版被加入.

@end deffn

@geindex expectedFailures (unittest.TestResult 的屬性)
@anchor{library/unittest unittest TestResult expectedFailures}@anchor{44ca}
@deffn {屬性} expectedFailures

A list containing 2-tuples of @ref{2b3,,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{44cb}
@deffn {屬性} unexpectedSuccesses

A list containing @ref{2b3,,TestCase} instances that were marked as expected
failures, but succeeded.
@end deffn

@geindex collectedDurations (unittest.TestResult 的屬性)
@anchor{library/unittest unittest TestResult collectedDurations}@anchor{19ce}
@deffn {屬性} collectedDurations

A list containing 2-tuples of test case names and floats
representing the elapsed time of each test which was run.


在 3.12 版被加入.

@end deffn

@geindex shouldStop (unittest.TestResult 的屬性)
@anchor{library/unittest unittest TestResult shouldStop}@anchor{44cc}
@deffn {屬性} shouldStop

Set to @code{True} when the execution of tests should stop by @ref{44cd,,stop()}.
@end deffn

@geindex testsRun (unittest.TestResult 的屬性)
@anchor{library/unittest unittest TestResult testsRun}@anchor{44ce}
@deffn {屬性} testsRun

The total number of tests run so far.
@end deffn

@geindex buffer (unittest.TestResult 的屬性)
@anchor{library/unittest unittest TestResult buffer}@anchor{44cf}
@deffn {屬性} buffer

If set to true, @code{sys.stdout} and @code{sys.stderr} will be buffered in between
@ref{44d0,,startTest()} and @ref{44d1,,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.


在 3.2 版被加入.

@end deffn

@geindex failfast (unittest.TestResult 的屬性)
@anchor{library/unittest unittest TestResult failfast}@anchor{44d2}
@deffn {屬性} failfast

If set to true @ref{44cd,,stop()} will be called on the first failure or error,
halting the test run.


在 3.2 版被加入.

@end deffn

@geindex tb_locals (unittest.TestResult 的屬性)
@anchor{library/unittest unittest TestResult tb_locals}@anchor{44d3}
@deffn {屬性} tb_locals

If set to true then local variables will be shown in tracebacks.


在 3.5 版被加入.

@end deffn

@geindex wasSuccessful() (unittest.TestResult 的方法)
@anchor{library/unittest unittest TestResult wasSuccessful}@anchor{44d4}
@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{44cb,,unexpectedSuccesses}
from tests marked with the @ref{44a2,,expectedFailure()} decorator.

@end deffn

@geindex stop() (unittest.TestResult 的方法)
@anchor{library/unittest unittest TestResult stop}@anchor{44cd}
@deffn {方法} stop ()

This method can be called to signal that the set of tests being run should
be aborted by setting the @ref{44cc,,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{1a01,,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 @ref{1368,,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{44d0}
@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{44d1}
@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{154a}
@deffn {方法} startTestRun ()

Called once before any tests are executed.


在 3.1 版被加入.

@end deffn

@geindex stopTestRun() (unittest.TestResult 的方法)
@anchor{library/unittest unittest TestResult stopTestRun}@anchor{154b}
@deffn {方法} stopTestRun ()

Called once after all tests are executed.


在 3.1 版被加入.

@end deffn

@geindex addError() (unittest.TestResult 的方法)
@anchor{library/unittest unittest TestResult addError}@anchor{1b4e}
@deffn {方法} addError (test, err)

Called when the test case `test' raises an unexpected exception. `err' is a
tuple of the form returned by @ref{893,,sys.exc_info()}: @code{(type, value,
traceback)}.

The default implementation appends a tuple @code{(test, formatted_err)} to
the instance's @ref{44c7,,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{1b4d}
@deffn {方法} addFailure (test, err)

Called when the test case `test' signals a failure. `err' is a tuple of
the form returned by @ref{893,,sys.exc_info()}: @code{(type, value, traceback)}.

The default implementation appends a tuple @code{(test, formatted_err)} to
the instance's @ref{44c8,,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{44d5}
@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{1b4f}
@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{44c9,,skipped} attribute.
@end deffn

@geindex addExpectedFailure() (unittest.TestResult 的方法)
@anchor{library/unittest unittest TestResult addExpectedFailure}@anchor{44d6}
@deffn {方法} addExpectedFailure (test, err)

Called when the test case `test' fails or errors, but was marked with
the @ref{44a2,,expectedFailure()} decorator.

The default implementation appends a tuple @code{(test, formatted_err)} to
the instance's @ref{44ca,,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{44d7}
@deffn {方法} addUnexpectedSuccess (test)

Called when the test case `test' was marked with the
@ref{44a2,,expectedFailure()} decorator, but succeeded.

The default implementation appends the test to the instance's
@ref{44cb,,unexpectedSuccesses} attribute.
@end deffn

@geindex addSubTest() (unittest.TestResult 的方法)
@anchor{library/unittest unittest TestResult addSubTest}@anchor{1b50}
@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{2b3,,TestCase} instance describing the subtest.

If `outcome' is @ref{87e,,None}, the subtest succeeded.  Otherwise,
it failed with an exception where `outcome' is a tuple of the form
returned by @ref{893,,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.


在 3.4 版被加入.

@end deffn

@geindex addDuration() (unittest.TestResult 的方法)
@anchor{library/unittest unittest TestResult addDuration}@anchor{1a02}
@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.


在 3.12 版被加入.

@end deffn
@end deffn

@geindex TextTestResult (unittest 中的類別)
@anchor{library/unittest unittest TextTestResult}@anchor{74d}
@deffn {類別} unittest.TextTestResult (stream, descriptions, verbosity, *, durations=None)

A concrete implementation of @ref{1368,,TestResult} used by the
@ref{1a01,,TextTestRunner}. Subclasses should accept @code{**kwargs} to ensure
compatibility as the interface changes.


在 3.2 版被加入.



在 3.12 版的變更: 新增 `durations' 關鍵字參數。

@end deffn

@geindex defaultTestLoader (於 unittest 模組中)
@anchor{library/unittest unittest defaultTestLoader}@anchor{44c2}
@deffn {資料} unittest.defaultTestLoader

Instance of the @ref{58d,,TestLoader} class intended to be shared.  If no
customization of the @ref{58d,,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{1a01}
@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{b2a,,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{1a3,,DeprecationWarning},
@ref{abd,,PendingDeprecationWarning}, @ref{547,,ResourceWarning} and
@ref{717,,ImportWarning} even if they are @ref{44d8,,ignored by default}.  This behavior can
be overridden using Python's @code{-Wd} or @code{-Wa} options
(see @ref{1ff0,,Warning control}) and leaving
`warnings' to @code{None}.


在 3.2 版的變更: 新增 `warnings' 參數。



在 3.2 版的變更: The default stream is set to @ref{b2a,,sys.stderr} at instantiation time rather
than import time.



在 3.5 版的變更: 新增 `tb_locals' 參數。



在 3.12 版的變更: 新增 `durations' 參數。


@geindex _makeResult() (unittest.TextTestRunner 的方法)
@anchor{library/unittest unittest TextTestRunner _makeResult}@anchor{44d9}
@deffn {方法} _makeResult ()

This method returns the instance of @code{TestResult} used by @ref{44da,,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{74d,,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{44da}
@deffn {方法} run (test)

This method is the main public interface to the @code{TextTestRunner}. This
method takes a @ref{ff0,,TestSuite} or @ref{2b3,,TestCase} instance. A
@ref{1368,,TestResult} is created by calling
@ref{44d9,,_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{11de}
@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{1465,,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{277,,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{58d,,TestLoader} instance,
and defaults to @ref{44c2,,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{277,,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{448a,,command-line options}.

The `warnings' argument specifies the @ref{1b1,,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{1ff0,,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{1368,,unittest.TestResult}.


在 3.1 版的變更: 新增 `exit' 參數。



在 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 協定:: 

@end menu

@node load_tests 協定,,,Loading and running tests
@anchor{library/unittest id1}@anchor{449b}@anchor{library/unittest load-tests-protocol}@anchor{4441}
@subsubsection load_tests 協定



在 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{58e,,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}.

它應該回傳一個 @ref{ff0,,TestSuite}。

`loader' is the instance of @ref{58d,,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{2b3,,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{11e0,,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{ff0,,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,類別與函式,unittest --- 單元測試框架
@anchor{library/unittest class-and-module-fixtures}@anchor{44aa}
@subsubsection Class and Module Fixtures


Class and module level fixtures are implemented in @ref{ff0,,TestSuite}. When
the test suite encounters a test from a new class then @code{tearDownClass()}
from the previous class (if there is one) is called, followed by
@code{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{2b3,,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 和 tearDownClass:: 
* setUpModule 和 tearDownModule:: 

@end menu

@node setUpClass 和 tearDownClass,setUpModule 和 tearDownModule,,Class and Module Fixtures
@anchor{library/unittest setupclass-and-teardownclass}@anchor{44db}
@subsubsection setUpClass 和 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{2b3,,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{11df,,SkipTest} exception then the class will be reported as having been skipped
instead of as an error.

@node setUpModule 和 tearDownModule,,setUpClass 和 tearDownClass,Class and Module Fixtures
@anchor{library/unittest setupmodule-and-teardownmodule}@anchor{44dc}
@subsubsection setUpModule 和 tearDownModule


@geindex setUpModule() (於 unittest 模組中)
@geindex tearDownModule() (於 unittest 模組中)
@anchor{library/unittest unittest setUpModule}@anchor{c39}
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{11df,,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{c37}
@deffn {函式} unittest.addModuleCleanup (function, /, *args, **kwargs)

Add a function to be called after @ref{1537,,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{c37,,addModuleCleanup()} when they are added.

If @ref{c39,,setUpModule()} fails, meaning that @ref{1537,,tearDownModule()} is not
called, then any cleanup functions added will still be called.


在 3.8 版被加入.

@end deffn

@geindex enterModuleContext() (於 unittest 模組中)
@anchor{library/unittest unittest enterModuleContext}@anchor{8c3}
@deffn {函式} unittest.enterModuleContext (cm)

Enter the supplied @ref{1e1,,context manager}.  If successful, also
add its @ref{1501,,__exit__()} method as a cleanup function by
@ref{c37,,addModuleCleanup()} and return the result of the
@ref{7dd,,__enter__()} method.


在 3.11 版被加入.

@end deffn

@geindex doModuleCleanups() (於 unittest 模組中)
@anchor{library/unittest unittest doModuleCleanups}@anchor{1af3}
@deffn {函式} unittest.doModuleCleanups ()

This function is called unconditionally after @ref{1537,,tearDownModule()}, or
after @ref{c39,,setUpModule()} if @ref{c39,,setUpModule()} raises an exception.

It is responsible for calling all the cleanup functions added by
@ref{c37,,addModuleCleanup()}. If you need cleanup functions to be called
`prior' to @ref{1537,,tearDownModule()} then you can call
@ref{1af3,,doModuleCleanups()} yourself.

@ref{1af3,,doModuleCleanups()} pops methods off the stack of cleanup
functions one at a time, so it can be called at any time.


在 3.8 版被加入.

@end deffn

@node Signal Handling,,Class and Module Fixtures,unittest --- 單元測試框架
@anchor{library/unittest signal-handling}@anchor{448d}
@subsubsection Signal Handling



在 3.2 版被加入.


The @ref{1533,,-c/--catch} command-line option to unittest,
along with the @code{catchbreak} parameter to @ref{11de,,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{bbc,,KeyboardInterrupt} in the usual way.

The control-c handling signal handler attempts to remain compatible with code or
tests that install their own @ref{253,,signal.SIGINT} handler. If the @code{unittest}
handler is called but `isn't' the installed @ref{253,,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{1534,,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{44dd}
@deffn {函式} unittest.installHandler ()

Install the control-c handler. When a @ref{253,,signal.SIGINT} is received
(usually in response to the user pressing control-c) all registered results
have @ref{44cd,,stop()} called.
@end deffn

@geindex registerResult() (於 unittest 模組中)
@anchor{library/unittest unittest registerResult}@anchor{44de}
@deffn {函式} unittest.registerResult (result)

Register a @ref{1368,,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{1368,,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{44df}
@deffn {函式} unittest.removeResult (result)

Remove a registered result. Once a result has been removed then
@ref{44cd,,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{1534}
@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 物件函式庫,unittest mock --- 入門指南,unittest --- 單元測試框架,開發工具
@anchor{library/unittest mock doc}@anchor{44e0}@anchor{library/unittest mock module-unittest mock}@anchor{10d}@anchor{library/unittest mock translation-repo}@anchor{44e1}@anchor{library/unittest mock unittest-mock-mock-object-library}@anchor{44e2}
@subsection @code{unittest.mock} — mock 物件函式庫


@geindex module; unittest.mock


在 3.3 版被加入.


`原始碼：'Lib/unittest/mock.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/unittest/mock.py}


__________________________________________________________________


@ref{10d,,unittest.mock} 在 Python 中是一個用於進行測試的函式庫。 它允許你用 mock 物件在測試中替換部分系統，並判定它們是如何被使用的。

@ref{10d,,unittest.mock} 提供了一個以 @ref{c36,,Mock} 為核心的類別，去除在測試中建立大量 stubs 的需求。 在執行動作之後，你可以判定哪些 method （方法）／屬性被使用，以及有哪些引數被呼叫。 你還可以用常規的方式指定回傳值與設定所需的屬性。

此外，mock 還提供了一個 @ref{108d,,patch()} 裝飾器，用於 patching 測試範圍內對 module（模組）以及 class（類別）級別的屬性，以及用於建立唯一物件的 @ref{d94,,sentinel}。有關如何使用 @ref{c36,,Mock}、@ref{108a,,MagicMock} 和 @ref{108d,,patch()} 的一些範例，請參閱@ref{44e3,,快速導引}。

Mock 被設計用於與 @ref{10c,,unittest} 一起使用，並且基於 「action（操作） -> assertion（判定）」 模式，而不是許多 mocking 框架使用的 「record（記錄） -> replay（重播）」 模式。

對於早期版本的 Python，有一個 backport（向後移植的）@ref{10d,,unittest.mock} 可以使用，可從 PyPI 下載 mock@footnote{https://pypi.org/project/mock/}。

@menu
* 快速導引:: 
* Mock 類別:: 
* Patchers:: 
* MagicMock 以及魔術方法支援:: 
* 輔助函式: 輔助函式<2>. 
* side_effect、return_value 和 wraps 的優先順序:: 

@end menu

@node 快速導引,Mock 類別,,unittest mock — mock 物件函式庫
@anchor{library/unittest mock quick-guide}@anchor{44e3}
@subsubsection 快速導引


@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{c36,,Mock} 和 @ref{108a,,MagicMock} 物件在你存取它們時建立所有屬性和 method（方法），並儲存它們如何被使用的詳細訊息。你可以配置它們，以指定回傳值或限制可用的屬性，然後對它們的使用方式做出判定：

@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{44e4,,side_effect} 允許你執行 side effects，包含在 mock 被呼叫時引發例外：

@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 有許多其他方法可以讓你配置與控制它的行為。例如，`spec' 引數可以配置 mock ，讓其從另一個物件取得規格。嘗試讀取 mock 中不存在於規格中的屬性或方法將會失敗，並出現 @ref{5e8,,AttributeError}。

@ref{108d,,patch()} 裝飾器／情境管理器可以在測試中簡單的 mock 模組中的類別或物件。被指定的物件在測試期間會被替換為 mock（或其他物件），並在測試結束時恢復：

@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 備註 
當你巢狀使用 patch 裝飾器時，mock 傳遞到被裝飾函式的順序會跟其被應用的順序相同（一般 `Python' 應用裝飾器的順序）。這意味著由下而上，因此在上面的範例中，@code{module.ClassName1} 的 mock 會先被傳入。

使用 @ref{108d,,patch()} 時，需注意的是你得在被查找物件的命名空間中（in the namespace where they are looked up）patch 物件。這通常很直接，但若需要快速導引，請參閱@ref{44e5,,該 patch 何處}。
@end quotation
@end cartouche

裝飾器 @ref{108d,,patch()} 也可以在 with 陳述式中被用來作為情境管理器：

@example
>>> with patch.object(ProductionClass, 'method', return_value=None) as mock_method:
...     thing = ProductionClass()
...     thing.method(1, 2, 3)
...
>>> mock_method.assert_called_once_with(1, 2, 3)
@end example

也有 @ref{18ce,,patch.dict()}，用於在測試範圍中設定 dictionary（字典）內的值，並在測試結束時將其恢復為原始狀態：

@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 支援對 Python 的@ref{44e6,,魔術方法}的 mocking。最簡單使用魔術方法的方式是使用 @ref{108a,,MagicMock} 類別。它允許你執行以下操作：

@example
>>> mock = MagicMock()
>>> mock.__str__.return_value = 'foobarbaz'
>>> str(mock)
'foobarbaz'
>>> mock.__str__.assert_called_with()
@end example

Mock 允許你將函式（或其他 Mock 實例）分配給魔術方法，並且它們將被適當地呼叫。@ref{108a,,MagicMock} 類別是一個 Mock 的變體，它為你預先建好了所有魔術方法（好吧，所有有用的方法）。

以下是在一般 Mock 類別中使用魔術方法的範例：

@example
>>> mock = Mock()
>>> mock.__str__ = Mock(return_value='wheeeeee')
>>> str(mock)
'wheeeeee'
@end example

為了確保測試中的 mock 物件與它們要替換的物件具有相同的 api，你可以使用@ref{44e7,,自動規格}。自動規格（auto-speccing）可以通過 patch 的 `autospec' 引數或 @ref{189a,,create_autospec()} 函式來完成。自動規格建立的 mock 物件與它們要替換的物件具有相同的屬性和方法，並且任何函式和方法（包括建構函式）都具有與真實物件相同的呼叫簽名（call signature）。

這可以確保如果使用方法錯誤，你的 mock 會跟實際程式碼以相同的方式失敗：

@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{189a,,create_autospec()} 也可以用在類別上，它複製了 @code{__init__} 方法的簽名，它也可以用在可呼叫物件上，其複製了 @code{__call__} 方法的簽名。

@node Mock 類別,Patchers,快速導引,unittest mock — mock 物件函式庫
@anchor{library/unittest mock the-mock-class}@anchor{44e8}
@subsubsection Mock 類別


@c import asyncio
@c import inspect
@c import unittest
@c import threading
@c from unittest.mock import sentinel, DEFAULT, ANY
@c from unittest.mock import patch, call, Mock, MagicMock, PropertyMock, AsyncMock
@c from unittest.mock import ThreadingMock
@c from unittest.mock import mock_open

@ref{c36,,Mock} 是一個彈性的的 mock 物件，旨在代替程式碼中 stubs 和 test doubles （測試替身）的使用。Mock 是可呼叫的，並在你存取它們時將屬性建立為新的 mock @footnote{
唯一的例外是魔術方法和屬性（具有前後雙底線）。Mock 不會建立這些，而是會引發 @ref{5e8,,AttributeError}。這是因為直譯器通常會隱式地要求這些方法，在期望得到一個魔術方法卻獲得一個新的 Mock 物件時，會讓直譯器`非常'困惑。如果你需要魔術方法的支援，請參閱@ref{44e6,,魔術方法}。
}。存取相同的屬性將永遠回傳相同的 mock。Mock 記錄了你如何使用它們，允許你判定你的程式碼對 mock 的行為。

@ref{108a,,MagicMock} 是 @ref{c36,,Mock} 的子類別，其中所有魔術方法均已預先建立並可供使用。也有不可呼叫的變體，在你 mock 無法呼叫的物件時很有用：@ref{44e9,,NonCallableMock} 和 @ref{44ea,,NonCallableMagicMock}

@ref{108d,,patch()} 裝飾器可以輕鬆地用 @ref{c36,,Mock} 物件臨時替換特定模組中的類別。預設情況下，@ref{108d,,patch()} 會為你建立一個 @ref{108a,,MagicMock}。你可以使用 @ref{108d,,patch()} 的 `new_callable' 引數指定 @ref{c36,,Mock} 的替代類別。

@geindex Mock (unittest.mock 中的類別)
@anchor{library/unittest mock unittest mock Mock}@anchor{c36}
@deffn {類別} unittest.mock.Mock (spec=None, side_effect=None, return_value=DEFAULT, wraps=None, name=None, spec_set=None, unsafe=False, **kwargs)

建立一個新的 @ref{c36,,Mock} 物件。@ref{c36,,Mock} 接受數個可選的引數來指定 Mock 物件的行為：


@itemize *

@item 
`spec'：這可以是字串的 list（串列），也可以是充當 mock 物件規格的現有物件（類別或實例）。如果傳入一個物件，則通過對該物件呼叫 dir 來形成字串的串列（不包括不支援的魔術屬性和方法）。存取不在此串列中的任何屬性都會引發 @ref{5e8,,AttributeError}。

如果 `spec' 是一個物件（而不是一個字串的串列），那麼 @ref{16a1,,__class__} 會回傳 spec 物件的類別。這允許 mocks 通過 @ref{2ad,,isinstance()} 測試。

@item 
`spec_set'：`spec' 的一個更嚴格的變體。如果使用 `spec_set'，在 mock 上嘗試 `set' 或取得不在傳遞給 `spec_set' 的物件上的屬性將會引發 @ref{5e8,,AttributeError}。

@item 
`side_effect'：每當呼叫 Mock 時要呼叫的函式，參見 @ref{44e4,,side_effect} 屬性，用於引發例外或動態變更回傳值。該函式使用與 mock 相同的引數呼叫，且除非它回傳 @ref{44eb,,DEFAULT}，否則此函式的回傳值將用作回傳值。

`side_effect' 也可以是一個例外的類別或實例。在這種情況下，當呼叫 mock 時，該例外將被引發。

如果 `side_effect' 是一個可疊代物件，那麼對 mock 的每次呼叫將回傳可疊代物件中的下一個值。

`side_effect' 可以通過將其設置為 @code{None} 來清除。

@item 
`return_value'：當呼叫 mock 時回傳的值。預設情況下，這是一個新的 Mock（在首次存取時建立）。參見 @ref{44ec,,return_value} 屬性。

@item 
`unsafe'：預設情況下，存取任何以 `assert'、`assret'、`asert'、`aseert' 或 `assrt' 開頭的屬性將引發 @ref{5e8,,AttributeError}。如果傳遞 @code{unsafe=True}，將會允許存取這些屬性。


在 3.5 版被加入.


@item 
`wraps'：被 mock 物件包裝的項目。如果 `wraps' 不是 @code{None}，那麼呼叫 Mock 將通過被包裝的物件（回傳真實結果）。存取 mock 的屬性將會回傳一個 Mock 物件，該物件包裝了被包裝物件的對應屬性（因此嘗試存取不存在的屬性將引發 @ref{5e8,,AttributeError}）。

如果 mock 已經明確設定了 `return_value'，那麼呼叫並不會被傳遞到被包裝的物件，而是回傳已設定好的 `return_value'。

@item 
`name'：如果 mock 有一個名稱，那麼它會被用於 mock 的 repr。這對於除錯很有用。此名稱將被傳播到子 mocks。
@end itemize

Mocks 還可以使用任意的關鍵字引數進行呼叫。這些關鍵字引數將在建立 mock 之後用於設定 mock 的屬性。欲知更多，請參見 @ref{44ed,,configure_mock()} 方法。

@geindex assert_called() (unittest.mock.Mock 的方法)
@anchor{library/unittest mock unittest mock Mock assert_called}@anchor{eef}
@deffn {方法} assert_called ()

確認 mock 至少被呼叫一次。

@example
>>> mock = Mock()
>>> mock.method()
<Mock name='mock.method()' id='...'>
>>> mock.method.assert_called()
@end example


在 3.6 版被加入.

@end deffn

@geindex assert_called_once() (unittest.mock.Mock 的方法)
@anchor{library/unittest mock unittest mock Mock assert_called_once}@anchor{ef0}
@deffn {方法} assert_called_once ()

確認 mock 只被呼叫一次。

@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


在 3.6 版被加入.

@end deffn

@geindex assert_called_with() (unittest.mock.Mock 的方法)
@anchor{library/unittest mock unittest mock Mock assert_called_with}@anchor{1ccb}
@deffn {方法} assert_called_with (*args, **kwargs)

這個方法是一個便利的方式，用來斷言最後一次呼叫是以特定方式進行的：

@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{44ee}
@deffn {方法} assert_called_once_with (*args, **kwargs)

確認 mock 只被呼叫一次，且該次呼叫使用了指定的引數。

@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{44ef}
@deffn {方法} assert_any_call (*args, **kwargs)

斷言 mock 已經被使用指定的引數呼叫。

這個斷言在 mock 曾經被呼叫過時通過，不同於 @ref{1ccb,,assert_called_with()} 和 @ref{44ee,,assert_called_once_with()}，他們針對的是最近的一次的呼叫，而且對於 @ref{44ee,,assert_called_once_with()}，最近一次的呼叫還必須也是唯一一次的呼叫。

@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{1972}
@deffn {方法} assert_has_calls (calls, any_order=False)

斷言 mock 已經使用指定的呼叫方式來呼叫。此斷言會檢查 @ref{44f0,,mock_calls} 串列中的呼叫。

如果 `any_order' 為 false，那麼這些呼叫必須按照順序。在指定的呼叫之前或之後可以有額外的呼叫。

如果 `any_order' 為 true，那麼這些呼叫可以以任何順序出現，但它們必須全部出現在 @ref{44f0,,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{1089}
@deffn {方法} assert_not_called ()

斷言 mock 從未被呼叫。

@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


在 3.5 版被加入.

@end deffn

@geindex reset_mock() (unittest.mock.Mock 的方法)
@anchor{library/unittest mock unittest mock Mock reset_mock}@anchor{ef1}
@deffn {方法} reset_mock (*, return_value=False, side_effect=False)

reset_mock 方法重置 mock 物件上的所有呼叫屬性：

@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{44ec,,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{44e4,,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 @ref{ef1,,reset_mock()} `doesn't' clear the
@ref{44ec,,return_value}, @ref{44e4,,side_effect} or any child attributes you have
set using normal assignment by default.

Child mocks are reset as well.


在 3.6 版的變更: reset_mock 函式新增了兩個僅限關鍵字引數 (keyword-only arguments)。

@end deffn

@geindex mock_add_spec() (unittest.mock.Mock 的方法)
@anchor{library/unittest mock unittest mock Mock mock_add_spec}@anchor{44f1}
@deffn {方法} mock_add_spec (spec, spec_set=False)

向 mock 增加一個規格 (spec)。`spec' 可以是一個物件或一個字串串列 (list of strings)。只有在 `spec' 上的屬性才能作為 mock 的屬性被取得。

如果 `spec_set' 為 true，那麼只能設定在規格中的屬性。
@end deffn

@geindex attach_mock() (unittest.mock.Mock 的方法)
@anchor{library/unittest mock unittest mock Mock attach_mock}@anchor{18bc}
@deffn {方法} attach_mock (mock, attribute)

將一個 mock 作為這個 Mock 的屬性附加，取代它的名稱和上代 (parent)。對附加的 mock 的呼叫將被記錄在這個 Mock 的 @ref{44f2,,method_calls} 和 @ref{44f0,,mock_calls} 屬性中。
@end deffn

@geindex configure_mock() (unittest.mock.Mock 的方法)
@anchor{library/unittest mock unittest mock Mock configure_mock}@anchor{44ed}
@deffn {方法} configure_mock (**kwargs)

透過關鍵字引數在 mock 上設定屬性。

可以在使用 method（方法）呼叫時，使用標準點記法 (dot notation) 並將字典拆開，為 child mock 設定屬性、回傳值和 side effects：

@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

同樣的事情可以在 mock 的建構函式呼叫中實現：

@example
>>> attrs = @{'method.return_value': 3, 'other.side_effect': KeyError@}
>>> mock = Mock(some_attribute='eggs', **attrs)
>>> mock.some_attribute
'eggs'
>>> mock.method()
3
>>> mock.other()
Traceback (most recent call last):
  ...
KeyError
@end example

@ref{44ed,,configure_mock()} 的存在是為了在 mock 被建立後更容易進行組態設定。
@end deffn

@geindex __dir__() (unittest.mock.Mock 的方法)
@anchor{library/unittest mock unittest mock Mock __dir__}@anchor{44f3}
@deffn {方法} __dir__ ()

@ref{c36,,Mock} 物件限制了 @code{dir(some_mock)} 僅顯示有用的結果。對於具有 `spec' 的 mock，這包含所有被允許的 mock 屬性。

請參閱 @ref{44f4,,FILTER_DIR} 以了解這種過濾行為的作用，以及如何關閉它。
@end deffn

@geindex _get_child_mock() (unittest.mock.Mock 的方法)
@anchor{library/unittest mock unittest mock Mock _get_child_mock}@anchor{44f5}
@deffn {方法} _get_child_mock (**kw)

建立為了得到屬性和回傳值的 child mock。預設情況下，child mock 將與其上代是相同的型別。Mock 的子類別可能會想要置換此行為，以自定義 child mock 的建立方式。

對於不可呼叫的 mock，將使用可呼叫的變體，而不是任何的自定義子類別。
@end deffn

@geindex called (unittest.mock.Mock 的屬性)
@anchor{library/unittest mock unittest mock Mock called}@anchor{44f6}
@deffn {屬性} called

一個 boolean（布林），表述 mock 物件是否已經被呼叫：

@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{44f7}
@deffn {屬性} call_count

一個整數，告訴你 mock 物件被呼叫的次數：

@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{44ec}
@deffn {屬性} return_value

設定此值以配置呼叫 mock 時回傳的值：

@example
>>> mock = Mock()
>>> mock.return_value = 'fish'
>>> mock()
'fish'
@end example

預設的回傳值是一個 mock 物件，你也可以按照正常的方式配置它：

@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{44ec,,return_value} 也可以在建構函式中設定：

@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{44e4}
@deffn {屬性} side_effect

這可以是一個在呼叫 mock 時要呼叫的函式、一個可疊代物件，或者要引發的例外（類別或實例）。

如果你傳遞一個函式，它將被呼叫，其引數與 mock 相同，且除非該函式回傳 @ref{44eb,,DEFAULT} 單例 (singleton)，否則對 mock 的呼叫將回傳函式回傳的任何值。如果函式回傳 @ref{44eb,,DEFAULT}，那麼 mock 將回傳其正常的回傳值（從 @ref{44ec,,return_value} 得到）。

如果你傳遞一個可疊代物件，它將被用於檢索一個疊代器，該疊代器必須在每次呼叫時產出 (yield) 一個值。這個值可以是要引發的例外實例，或者是對 mock 呼叫時要回傳的值（處理 @ref{44eb,,DEFAULT} 的方式與函式的狀況相同）。

以下是一個引發例外的 mock 的範例（用於測試 API 的例外處理）：

@example
>>> mock = Mock()
>>> mock.side_effect = Exception('Boom!')
>>> mock()
Traceback (most recent call last):
  ...
Exception: Boom!
@end example

使用 @ref{44e4,,side_effect} 回傳一連串值的範例：

@example
>>> mock = Mock()
>>> mock.side_effect = [3, 2, 1]
>>> mock(), mock(), mock()
(3, 2, 1)
@end example

使用可被呼叫物件的範例：

@example
>>> mock = Mock(return_value=3)
>>> def side_effect(*args, **kwargs):
...     return DEFAULT
...
>>> mock.side_effect = side_effect
>>> mock()
3
@end example

@ref{44e4,,side_effect} 可以在建構函式中設定。以下是一個範例，它將 mock 被呼叫時給的值加一並回傳：

@example
>>> side_effect = lambda value: value + 1
>>> mock = Mock(side_effect=side_effect)
>>> mock(3)
4
>>> mock(-8)
-7
@end example

將 @ref{44e4,,side_effect} 設定為 @code{None} 可以清除它：

@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{1c32}
@deffn {屬性} call_args

這會是 @code{None}（如果 mock 尚未被呼叫），或是 mock 上次被呼叫時使用的引數。這將以元組的形式呈現：第一個成員 (member)，其可以通過 @code{args} 屬性存取，是 mock 被呼叫時傳遞的所有位置引數（或一個空元組）。第二個成員，其可以通過 @code{kwargs} 屬性存取，是所有關鍵字引數（或一個空字典）。

@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{1c32,,call_args}，以及串列 @ref{44f8,,call_args_list}、@ref{44f2,,method_calls} 和 @ref{44f0,,mock_calls} 的成員都是 @ref{1c7c,,call} 物件。這些都是元組，因此可以解包以取得各個引數並進行更複雜的斷言。參見 @ref{44f9,,calls as tuples}。


在 3.8 版的變更: 新增 @code{args} 與 @code{kwargs} 特性。

@end deffn

@geindex call_args_list (unittest.mock.Mock 的屬性)
@anchor{library/unittest mock unittest mock Mock call_args_list}@anchor{44f8}
@deffn {屬性} call_args_list

這是按順序列出所有呼叫 mock 物件的串列（因此串列的長度表示它被呼叫的次數）。在任何呼叫發生之前，它會是一個空的串列。 @ref{1c7c,,call} 物件可用於方便地建構呼叫的串列，以便與 @ref{44f8,,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

@ref{44f8,,call_args_list} 的成員都是 @ref{1c7c,,call} 物件。這些物件可以被拆包為元組，以取得各個引數。參見 @ref{44f9,,calls as tuples}。
@end deffn

@geindex method_calls (unittest.mock.Mock 的屬性)
@anchor{library/unittest mock unittest mock Mock method_calls}@anchor{44f2}
@deffn {屬性} method_calls

除了追蹤對自身的呼叫之外，mock 還會追蹤對方法和屬性的呼叫，以及`它們（這些方法和屬性）'的方法和屬性：

@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

@ref{44f2,,method_calls} 的成員都是 @ref{1c7c,,call} 物件。這些物件可以拆包為元組，以取得各個引數。參見 @ref{44f9,,calls as tuples}。
@end deffn

@geindex mock_calls (unittest.mock.Mock 的屬性)
@anchor{library/unittest mock unittest mock Mock mock_calls}@anchor{44f0}
@deffn {屬性} mock_calls

@ref{44f0,,mock_calls} 記錄了 `所有' 對 mock 物件的呼叫，包含其方法、魔術方法以及回傳值 mock。

@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

@code{method_calls} 的成員都是 @ref{1c7c,,call} 物件。這些物件可以拆包為元組，以取得各個引數。參見 @ref{44f9,,calls as tuples}。

@cartouche
@quotation 備註 
@ref{44f0,,mock_calls} 記錄的方式意味著在進行巢狀呼叫時，上代 (ancestor) 呼叫的參數不會被記錄，因此在比較時它們將始終相等：

@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{44fa}
@deffn {屬性} __class__

通常，物件的 @code{__class__} 屬性會回傳它的型別。但對於擁有 @code{spec} 的 mock 物件，@code{__class__} 會回傳 spec 的類別。這允許 mock 物件通過對它們所替代或偽裝的物件進行的 @ref{2ad,,isinstance()} 測試：

@example
>>> mock = Mock(spec=3)
>>> isinstance(mock, int)
True
@end example

@code{__class__} 可以被指定，這允許 mock 通過 @ref{2ad,,isinstance()} 檢查，而不需要強制使用 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{44e9}
@deffn {類別} unittest.mock.NonCallableMock (spec=None, wraps=None, name=None, spec_set=None, **kwargs)

@ref{c36,,Mock} 的一個不可呼叫版本。建構函式參數的意義與 @ref{c36,,Mock} 相同，其例外為 `return_value' 和 `side_effect' 在不可呼叫的 mock 上無意義。
@end deffn

使用類別或實例作為 @code{spec} 或 @code{spec_set} 的 mock 物件能夠通過 @ref{2ad,,isinstance()} 測試：

@example
>>> mock = Mock(spec=SomeClass)
>>> isinstance(mock, SomeClass)
True
>>> mock = Mock(spec_set=SomeClass())
>>> isinstance(mock, SomeClass)
True
@end example

@ref{c36,,Mock} 類別支援 mock 魔術方法。細節請參考@ref{44e6,,魔術方法}。

Mock類別和 @ref{108d,,patch()} 裝飾器於組態時接受任意的關鍵字引數。對於 @ref{108d,,patch()} 裝飾器，這些關鍵字會傳遞給正在建立 mock 的建構函式。這些關鍵字引數用於配置 mock 的屬性：

@example
>>> m = MagicMock(attribute=3, other='fish')
>>> m.attribute
3
>>> m.other
'fish'
@end example

Child mock 的回傳值和 side effect 可以使用使用點記法進行設置。由於你無法直接在呼叫中使用帶有點 (.) 的名稱，因此你必須建立一個字典並使用 @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

在匹配對 mock 的呼叫時，使用 `spec'（或 `spec_set'）建立的可呼叫 mock 將會內省 (introspect) 規格物件的簽名 (signature)。因此，它可以匹配實際呼叫的引數，無論它們是按位置傳遞還是按名稱傳遞：

@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

這適用於 @ref{1ccb,,assert_called_with()}、@ref{44ee,,assert_called_once_with()}、@ref{1972,,assert_has_calls()} 和 @ref{44ef,,assert_any_call()}。在使用 @ref{44e7,,Autospeccing（自動規格）} 時，它還適用於 mock 物件的方法呼叫。


在 3.4 版的變更: 對於已經設置了規格（spec）和自動規格（autospec）的 mock 物件，新增簽名內省功能。


@geindex PropertyMock (unittest.mock 中的類別)
@anchor{library/unittest mock unittest mock PropertyMock}@anchor{44fb}
@deffn {類別} unittest.mock.PropertyMock (*args, **kwargs)

一個理應在類別上當成 @ref{4ae,,property} 或其他 @ref{17fc,,descriptor} 的 mock。@ref{44fb,,PropertyMock} 提供了 @ref{16dc,,__get__()} 和 @ref{2267,,__set__()} 方法，因此你可以在它被提取時指定回傳值。

從物件中提取 @ref{44fb,,PropertyMock} 實例會不帶任何引數呼叫 mock。設定它則會用設定的值來呼叫 mock：

@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

由於 mock 屬性的儲存方式，你無法直接將 @ref{44fb,,PropertyMock} 附加到 mock 物件。但是你可以將其附加到 mock 型別的物件：

@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{5e8,,AttributeError} is raised by @ref{44fb,,PropertyMock},
it will be interpreted as a missing descriptor and
@ref{6f3,,__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

詳情請見 @ref{6f3,,__getattr__()}。
@end quotation
@end cartouche

@geindex AsyncMock (unittest.mock 中的類別)
@anchor{library/unittest mock unittest mock AsyncMock}@anchor{c35}
@deffn {類別} unittest.mock.AsyncMock (spec=None, side_effect=None, return_value=DEFAULT, wraps=None, name=None, spec_set=None, unsafe=False, **kwargs)

@ref{108a,,MagicMock} 的非同步版本。@ref{c35,,AsyncMock} 物件的表現將被視為非同步函式，並且呼叫的結果是一個可等待物件。

@example
>>> mock = AsyncMock()
>>> inspect.iscoroutinefunction(mock)
True
>>> inspect.isawaitable(mock())
True
@end example

@code{mock()} 的結果是一個非同步函式，在它被等待後將具有 @code{side_effect} 或 @code{return_value} 的結果：


@itemize -

@item 
如果 @code{side_effect} 是一個函式，非同步函式將回傳該函式的結果，

@item 
如果 @code{side_effect} 是一個例外，則非同步函式將引發該例外，

@item 
如果 @code{side_effect} 是一個可疊代物件，非同步函式將回傳可疊代物件的下一個值，但如果結果序列耗盡，將立即引發 @code{StopAsyncIteration}，

@item 
如果 @code{side_effect} 沒有被定義，非同步函式將回傳由 @code{return_value} 定義的值，因此在預設情況下，非同步函式回傳一個新的 @ref{c35,,AsyncMock} 物件。
@end itemize

將 @ref{c36,,Mock} 或 @ref{108a,,MagicMock} 的 `spec' 設定為非同步函式將導致在呼叫後回傳一個協程物件。

@example
>>> async def async_func(): pass
...
>>> mock = MagicMock(async_func)
>>> mock
<MagicMock spec='function' id='...'>
>>> mock()
<coroutine object AsyncMockMixin._mock_call at ...>
@end example

將 @ref{c36,,Mock}、@ref{108a,,MagicMock} 或 @ref{c35,,AsyncMock} 的 `spec' 設定為具有同步和非同步函式的類別，會自動檢測同步函式並將其設定為 @ref{108a,,MagicMock}（如果上代 mock 為 @ref{c35,,AsyncMock} 或 @ref{108a,,MagicMock}）或 @ref{c36,,Mock}（如果上代 mock 為 @ref{c36,,Mock}）。所有非同步函式將被設定為 @ref{c35,,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


在 3.8 版被加入.


@geindex assert_awaited() (unittest.mock.AsyncMock 的方法)
@anchor{library/unittest mock unittest mock AsyncMock assert_awaited}@anchor{44fc}
@deffn {方法} assert_awaited ()

斷言 mock 至少被等待過一次。請注意這與物件是否被呼叫是分開的，@code{await} 關鍵字必須被使用：

@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{44fd}
@deffn {方法} assert_awaited_once ()

斷言 mock 正好被等待了一次。

@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{44fe}
@deffn {方法} assert_awaited_with (*args, **kwargs)

斷言最後一次等待使用了指定的引數。

@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{44ff}
@deffn {方法} assert_awaited_once_with (*args, **kwargs)

斷言 mock 只被等待了一次並使用了指定的引數。

@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{4500}
@deffn {方法} assert_any_await (*args, **kwargs)

斷言 mock 曾經被使用指定的引數等待過。

@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{4501}
@deffn {方法} assert_has_awaits (calls, any_order=False)

斷言 mock 已被使用指定的呼叫進行等待。@ref{1c31,,await_args_list} 串列將被檢查以確認等待的內容。

如果 `any_order' 為 false，則等待必須按照順序。指定的等待之前或之後可以有額外的呼叫。

如果 `any_order' 為 true，則等待可以以任何順序出現，但它們必須全部出現在 @ref{1c31,,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{4502}
@deffn {方法} assert_not_awaited ()

斷言 mock 從未被等待。

@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{4503}
@deffn {方法} reset_mock (*args, **kwargs)

參見 @ref{ef1,,Mock.reset_mock()}。同時將 @ref{4504,,await_count} 設定為 0，@ref{4505,,await_args} 設定為 None，並清除 @ref{1c31,,await_args_list}。
@end deffn

@geindex await_count (unittest.mock.AsyncMock 的屬性)
@anchor{library/unittest mock unittest mock AsyncMock await_count}@anchor{4504}
@deffn {屬性} await_count

一個整數，用來記錄 mock 物件已被等待的次數。

@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{4505}
@deffn {屬性} await_args

這可能是 @code{None}（如果 mock 尚未被等待），或者是上次等待 mock 時使用的引數。與 @ref{1c32,,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{1c31}
@deffn {屬性} await_args_list

這是一個按照順序記錄 mock 物件所有等待的串列（因此串列的長度表示該物件已被等待的次數）。在進行任何等待之前，此串列為空。

@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{4506}
@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{108a,,MagicMock} for multithreading tests. The
@ref{4506,,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{4507,,ThreadingMock.DEFAULT_TIMEOUT} attribute, which defaults to blocking (@code{None}).

You can configure the global default timeout by setting @ref{4507,,ThreadingMock.DEFAULT_TIMEOUT}.

@geindex wait_until_called() (unittest.mock.ThreadingMock 的方法)
@anchor{library/unittest mock unittest mock ThreadingMock wait_until_called}@anchor{4508}
@deffn {方法} wait_until_called (*, timeout=UNSET)

等待直到 mock 被呼叫。

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{8b0,,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{4509}
@deffn {方法} wait_until_any_call_with (*args, **kwargs)

等到直到 mock 被以特定引數呼叫。

If a timeout was passed at the creation of the mock
the function raises an @ref{8b0,,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{4507}
@deffn {屬性} DEFAULT_TIMEOUT

Global default timeout in seconds to create instances of @ref{4506,,ThreadingMock}.
@end deffn


在 3.13 版被加入.

@end deffn

@menu
* 呼叫:: 
* 刪除屬性:: 
* Mock 名稱與名稱屬性:: 
* 如同屬性一般附加 mock:: 

@end menu

@node 呼叫,刪除屬性,,Mock 類別
@anchor{library/unittest mock calling}@anchor{450a}
@subsubsection 呼叫


Mock 物件可被呼叫。呼叫將回傳設定為 @ref{44ec,,return_value} 屬性的值。預設的回傳值是一個新的 Mock 物件；它會在第一次存取回傳值時（無論是顯式存取還是透過呼叫 Mock）被建立，但是這個回傳值會被儲存，之後每次都回傳同一個值。

對物件的呼叫會被記錄在如 @ref{1c32,,call_args} 和 @ref{44f8,,call_args_list} 等屬性中。

如果 @ref{44e4,,side_effect} 被設定，那麼在呼叫被記錄後它才會被呼叫，所以如果 @code{side_effect} 引發例外，呼叫仍然會被記錄。

呼叫 mock 時引發例外的最簡單方式是將 @ref{44e4,,side_effect} 設定為例外類別或實例：

@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

如果 @ref{44e4,,side_effect} 是一個函式，則該函式回傳的東西就是對 mock 的呼叫所回傳的值。@code{side_effect} 函式會使用與 mock 相同的引數被呼叫。這讓你可以根據輸入動態地變更呼叫的回傳值：

@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

如果你希望 mock 仍然回傳預設的回傳值（一個新的 mock），或者是任何已設定的回傳值，有兩種方法可以實現。從 @ref{44e4,,side_effect} 內部回傳 @ref{44ec,,return_value}，或回傳 @ref{44eb,,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

要刪除 @ref{44e4,,side_effect}，並恢復預設行為，將 @code{side_effect} 設為 @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

@ref{44e4,,side_effect} 也可以是任何可疊代的物件。對 mock 的重複呼叫將從可疊代物件中回傳值（直到疊代物件耗盡並引發 @ref{df0,,StopIteration} 為止）：

@example
>>> m = MagicMock(side_effect=[1, 2, 3])
>>> m()
1
>>> m()
2
>>> m()
3
>>> m()
Traceback (most recent call last):
  ...
StopIteration
@end example

如果可疊代物件中的任何成員是例外，則它們將被引發而不是被回傳：

@example
>>> iterable = (33, ValueError, 66)
>>> m = MagicMock(side_effect=iterable)
>>> m()
33
>>> m()
Traceback (most recent call last):
 ...
ValueError
>>> m()
66
@end example

@node 刪除屬性,Mock 名稱與名稱屬性,呼叫,Mock 類別
@anchor{library/unittest mock deleting-attributes}@anchor{450b}@anchor{library/unittest mock id2}@anchor{450c}
@subsubsection 刪除屬性


Mock 物件會在需要時建立屬性。這使得它們可以假裝成任何種類的物件。

你可能希望一個 mock 物件在 @ref{6f2,,hasattr()} 呼叫時回傳 @code{False}，或者在屬性被提取時引發 @ref{5e8,,AttributeError}。你可以通過將物件提供為 mock 的 @code{spec} 來實現這一點，但這並不總是那麼好用。

你可以通過刪除屬性來「阻擋」它們。一旦刪除，再次存取該屬性將會引發 @ref{5e8,,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 名稱與名稱屬性,如同屬性一般附加 mock,刪除屬性,Mock 類別
@anchor{library/unittest mock mock-names-and-the-name-attribute}@anchor{450d}
@subsubsection Mock 名稱與名稱屬性


由於 "name" 是傳遞給 @ref{c36,,Mock} 建構函式的引數，如果你想讓你的 mock 物件擁有 "name" 屬性，你不能在建立時直接傳遞它。有兩種替代方法。其中一個選擇是使用 @ref{44ed,,configure_mock()}：

@example
>>> mock = MagicMock()
>>> mock.configure_mock(name='my_name')
>>> mock.name
'my_name'
@end example

更簡單的方法是在 mock 建立後直接設定 "name" 屬性：

@example
>>> mock = MagicMock()
>>> mock.name = "foo"
@end example

@node 如同屬性一般附加 mock,,Mock 名稱與名稱屬性,Mock 類別
@anchor{library/unittest mock attaching-mocks-as-attributes}@anchor{450e}
@subsubsection 如同屬性一般附加 mock


當你將一個 mock 附加為另一個 mock 的屬性（或作為回傳值），它將成為該 mock 的「子代 (child)」。對子代的呼叫將被記錄在上代的 @ref{44f2,,method_calls} 和 @ref{44f0,,mock_calls} 屬性中。這對於配置子代並將它們附加到上代，或將 mock 附加到記錄所有對子代的呼叫的上代並允許你對 mock 間的呼叫順序進行斷言非常有用：

@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

如果 mock 有 name 引數，則上述規則會有例外。這使你可以防止「親屬關係 (parenting)」的建立，假設因為某些原因你不希望這種狀況發生。

@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

由 @ref{108d,,patch()} 為你建立的 mock 會自動被賦予名稱。若要將具有名稱的 mock 附加到上代，你可以使用 @ref{18bc,,attach_mock()} 方法：

@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 Patchers,MagicMock 以及魔術方法支援,Mock 類別,unittest mock — mock 物件函式庫
@anchor{library/unittest mock the-patchers}@anchor{450f}
@subsubsection Patchers


patch 裝飾器僅用於在裝飾的函式範圍內對物件進行 patch。它們會自動為你處理 patch 的中止，即使有異常被引發也是如此。所有這些函式也可以在 with 陳述式中使用，或者作為類別裝飾器使用。

@menu
* patch:: 
* patch.object: patch object. 
* patch.dict: patch dict. 
* patch.multiple: patch multiple. 
* patch 方法：啟動與停止:: 
* patch 內建函式:: 
* TEST_PREFIX:: 
* 巢狀使用 Patch 裝飾器:: 
* 該 patch 何處:: 
* Patch 描述器與代理物件 (Proxy Objects): Patch 描述器與代理物件 Proxy Objects. 

@end menu

@node patch,patch object,,Patchers
@anchor{library/unittest mock patch}@anchor{4510}
@subsubsection patch


@cartouche
@quotation 備註 
關鍵是要在正確的命名空間進行 patch。請參閱 @ref{4511,,where to patch} 一節。
@end quotation
@end cartouche

@geindex patch() (於 unittest.mock 模組中)
@anchor{library/unittest mock unittest mock patch}@anchor{108d}
@deffn {函式} unittest.mock.patch (target, new=DEFAULT, spec=None, create=False, spec_set=None, autospec=None, new_callable=None, **kwargs)

@ref{108d,,patch()} 充當函式裝飾器、類別裝飾器或情境管理器。在函式或 with 陳述式的內部，`目標'會被 patch 成一個`新的'物件。當函式或 with 陳述式結束時，patch 就會被解除。

如果 `new' 被省略，則如果被 patch 的物件是非同步函式，目標會被替換為 @ref{c35,,AsyncMock}，反之則替換為 @ref{108a,,MagicMock}。如果 @ref{108d,,patch()} 做為裝飾器使用且省略了 `new'，則所建立的 mock 會作為額外的引數傳遞給被裝飾的函式。如果 @ref{108d,,patch()} 作為情境管理器使用，則所建立的 mock 將由情境管理器回傳。

`target' 應該是以 @code{'package.module.ClassName'} 形式出現的字串。`target' 會被引入並用 `new' 物件替換指定的物件，因此 `target' 必須可從你呼叫 @ref{108d,,patch()} 的環境中引入。target 在執行被裝飾的函式時被引入，而不是在裝飾器作用時 (decoration time)。

`spec' 和 `spec_set' 關鍵字引數會傳遞給 @ref{108a,,MagicMock}，如果 patch 正在為你建立一個。

此外，你還可以傳遞 @code{spec=True} 或 @code{spec_set=True}，這將導致 patch 將被 mock 的物件作為 spec/spec_set 物件傳遞。

`new_callable' 允許你指定一個不同的類別或可呼叫的物件，用於被呼叫並建立 `new' 物件。預設情況下，對於非同步函式使用 @ref{c35,,AsyncMock}，而對於其他情況則使用 @ref{108a,,MagicMock}。

`spec' 的一種更強大的形式是 `autospec'。如果你設定 @code{autospec=True}，則該 mock 將使用被替換物件的規格來建立。該 mock 的所有屬性也將具有被替換物件的對應屬性的規格。被 mock 的方法和函式將檢查其引數，如果呼叫時引數與規格不符（被使用錯誤的簽名 (signature) 呼叫），將引發 @ref{198,,TypeError}。對於替換類別的 mock，它們的回傳值（即 'instance'）將具有與類別相同的規格。請參閱 @ref{189a,,create_autospec()} 函式和 @ref{44e7,,Autospeccing（自動規格）}。

你可以用 @code{autospec=some_object} 替代 @code{autospec=True}，以使用任意物件作為規格，而不是被替換的物件。

預設情況下，@ref{108d,,patch()} 將無法取代不存在的屬性。如果你傳入 @code{create=True}，且屬性不存在，則當被 patch 的函式被呼叫時，patch 將為你建立該屬性，並在被 patch 的函式結束後再次刪除它。這對於撰寫針對你的生產程式碼在執行環境建立的屬性的測試時非常有用。此功能預設為關閉，因為這可能會相當危險。開啟這個功能後，你可以對於實際上不存在的 API 撰寫會通過的測試！

@cartouche
@quotation 備註 

在 3.5 版的變更: 如果你正在 patch 模組中的內建函式，那麼你不需要傳遞 @code{create=True}，它預設會被加入。

@end quotation
@end cartouche

patch 可以做為 @ref{2b3,,TestCase} 類別的裝飾器使用。它透過裝飾類別中的每個測試方法來運作。當你的測試方法共享一組常見的 patch 時，這會減少繁冗的代碼。@ref{108d,,patch()} 通過搜尋以 @code{patch.TEST_PREFIX} 開頭的方法名來尋找測試。預設情況下會是 @code{'test'}，這與 @ref{10c,,unittest} 尋找測試的方式相匹配。你可以通過設定 @code{patch.TEST_PREFIX} 來指定別的前綴。

透過 with 陳述式，Patch 可以做為情境管理器使用。patch 適用於 with 陳述式之後的縮排區塊。如果你使用 "as"，則被 patch 的物件將被綁定到 "as" 後面的名稱；如果 @ref{108d,,patch()} 正在為你建立一個 mock 物件，這會非常有用。

@ref{108d,,patch()} 接受任意的關鍵字引數。如果被 patch 的物件是非同步的，這些將會被傳遞給 @ref{c35,,AsyncMock}，如果是同步的則會傳遞給 @ref{108a,,MagicMock}，或如果指定了 `new_callable'，則傳遞給它。

@code{patch.dict(...)}、@code{patch.multiple(...)} 和 @code{patch.object(...)} 可用於其餘的使用情境。
@end deffn

@ref{108d,,patch()} 作為函式裝飾器，為你建立 mock 並將其傳遞給被裝飾的函式：

@example
>>> @@patch('__main__.SomeClass')
... def function(normal_argument, mock_class):
...     print(mock_class is SomeClass)
...
>>> function(None)
True
@end example

Patch 一個類別會以 @ref{108a,,MagicMock} `實例'取代該類別。如果該類別在被測試的程式碼中實例化，那麼它將是會被使用的 mock 的 @ref{44ec,,return_value}。

如果該類別被實例化多次，你可以使用 @ref{44e4,,side_effect} 來每次回傳一個新的 mock。 或者你可以將 `return_value' 設定成你想要的任何值。

若要配置被 patch 的類別的`實例'方法的回傳值，你必須在 @ref{44ec,,return_value} 上進行配置。例如：

@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

如果你使用 `spec' 或 `spec_set' 且 @ref{108d,,patch()} 正在取代一個`類別'，那麼被建立的 mock 的回傳值將具有相同的規格。：

@example
>>> Original = Class
>>> patcher = patch('__main__.Class', spec=True)
>>> MockClass = patcher.start()
>>> instance = MockClass()
>>> assert isinstance(instance, Original)
>>> patcher.stop()
@end example

當你想要為被建立的 mock 使用一個替代的類別取代預設的 @ref{108a,,MagicMock} 時，`new_callable' 引數非常有用。例如，如果你想要一個 @ref{44e9,,NonCallableMock} 被使用：

@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

另一個用法是用一個 @ref{1124,,io.StringIO} 實例替換一個物件：

@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

當 @ref{108d,,patch()} 為你建立 mock 時，通常你需要做的第一件事就是配置 mock。其中一些配置可以在對 patch 的呼叫中完成。你傳遞到呼叫中的任何關鍵字都將用於在被建立的 mock 上設定屬性：

@example
>>> patcher = patch('__main__.thing', first='one', second='two')
>>> mock_thing = patcher.start()
>>> mock_thing.first
'one'
>>> mock_thing.second
'two'
@end example

除了被建立的 mock 上的屬性外，還可以配置 child mock 的 @ref{44ec,,return_value} 和 @ref{44e4,,side_effect}。它們在語法上不能直接作為關鍵字引數傳入，但是以它們作為鍵的字典仍然可以使用 @code{**} 擴充為一個 @ref{108d,,patch()} 呼叫：

@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

預設情況下，嘗試 patch 模組中不存在的函式（或類別中的方法或屬性）將會失敗，並引發 @ref{5e8,,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

但是在對 @ref{108d,,patch()} 的呼叫中增加 @code{create=True} 將使前面的範例按照預期運作：

@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{108d,,patch()} 現在會回傳一個 @ref{c35,,AsyncMock}。


@node patch object,patch dict,patch,Patchers
@anchor{library/unittest mock patch-object}@anchor{4512}
@subsubsection patch.object


@geindex patch.object() (於 unittest.mock 模組中)
@anchor{library/unittest mock unittest mock patch object}@anchor{1871}
@deffn {函式} patch.object (target, attribute, new=DEFAULT, spec=None, create=False, spec_set=None, autospec=None, new_callable=None, **kwargs)

使用一個 mock 物件 patch 一個物件（`目標'）上的命名成員（`屬性'）。

@ref{1871,,patch.object()} 可以做為裝飾器、類別裝飾器或情境管理器使用。引數 `new'、`spec'、`create'、`spec_set'、`autospec' 和 `new_callable' 與在 @ref{108d,,patch()} 中的引數具有相同的意義。與 @ref{108d,,patch()} 一樣，@ref{1871,,patch.object()} 接受任意關鍵字引數來配置它所建立的 mock 物件。

當作為類別裝飾器使用時，@ref{1871,,patch.object()} 會遵循 @code{patch.TEST_PREFIX} 來選擇要包裝的方法。
@end deffn

你可以使用三個引數或兩個引數來呼叫 @ref{1871,,patch.object()}。三個引數的形式接受要被 patch 的物件、屬性名稱和要替換掉屬性的物件。

當使用兩個引數的形式呼叫時，你會省略要替換的物件，一個 mock 會為你建立並將其作為額外的引數傳遞給被裝飾的函式：

@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' 和 @ref{1871,,patch.object()} 的其他引數與在 @ref{108d,,patch()} 中的引數具有相同的意義。

@node patch dict,patch multiple,patch object,Patchers
@anchor{library/unittest mock patch-dict}@anchor{4513}
@subsubsection patch.dict


@geindex patch.dict() (於 unittest.mock 模組中)
@anchor{library/unittest mock unittest mock patch dict}@anchor{18ce}
@deffn {函式} patch.dict (in_dict, values=(), clear=False, **kwargs)

Patch 字典或類字典的物件，並在測試後將字典回復到其原本的狀態，其中回復的字典是測試前字典的複本。

`in_dict' 可以是一個字典或一個類對映的容器。如果它是一個對映，那麼它至少必須支援取得、設定、刪除項目以及對鍵的疊代。

`in_dict' 也可以是指定字典名稱的字串，然後透過 import 來取得該字典。

`values' 可以是要設定的值的字典。`values' 也可以是 @code{(key, value)} 對 (pairs) 的可疊代物件。

如果 `clear' 為 true，則在設定新值之前字典將被清除。

也可以使用任意關鍵字引數呼叫 @ref{18ce,,patch.dict()} 以在字典中設定值。


在 3.8 版的變更: @ref{18ce,,patch.dict()} 現在在做為情境管理器使用時回傳被 patch 的字典。

@end deffn

@ref{18ce,,patch.dict()} 可以做為情境管理器、裝飾器或類別裝飾器使用：

@example
>>> foo = @{@}
>>> @@patch.dict(foo, @{'newkey': 'newvalue'@})
... def test():
...     assert foo == @{'newkey': 'newvalue'@}
...
>>> test()
>>> assert foo == @{@}
@end example

當作為類別裝飾器使用時，@ref{18ce,,patch.dict()} 會遵循 @code{patch.TEST_PREFIX}（預設為 @code{'test'}）來選擇要包裝的方法：

@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

如果你想在測試中使用不同的前綴，你可以透過設定 @code{patch.TEST_PREFIX} 來告知 patcher 使用不同的前綴。請參閱 @ref{4514,,TEST_PREFIX} 以得知如何修改前綴的更多內容。

@ref{18ce,,patch.dict()} 可用於在字典中新增成員，或單純地讓測試更改字典，並確保在測試結束時將字典回復原狀。

@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

可以在 @ref{18ce,,patch.dict()} 呼叫中使用關鍵字來設定字典中的值：

@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{18ce,,patch.dict()} 可以與實際上不是字典的類字典物件一起使用。最低限度它們必須支援項目的取得、設定、刪除以及疊代或隸屬資格檢測。這對應到魔術方法中的 @ref{582,,__getitem__()}、@ref{14cc,,__setitem__()}、@ref{14cd,,__delitem__()} 以及 @ref{1f71,,__iter__()} 或 @ref{15b1,,__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 方法：啟動與停止,patch dict,Patchers
@anchor{library/unittest mock patch-multiple}@anchor{4515}
@subsubsection patch.multiple


@geindex patch.multiple() (於 unittest.mock 模組中)
@anchor{library/unittest mock unittest mock patch multiple}@anchor{4516}
@deffn {函式} patch.multiple (target, spec=None, create=False, spec_set=None, autospec=None, new_callable=None, **kwargs)

在一次呼叫中執行多個 patch。它接受被 patch 的物件（作為物件或透過 import 取得物件的字串）和 patch 的關鍵字引數：

@example
with patch.multiple(settings, FIRST_PATCH='one', SECOND_PATCH='two'):
    ...
@end example

如果你想要 @ref{4516,,patch.multiple()} 為你建立 mock，請使用 @ref{44eb,,DEFAULT} 作為值。在這種情況下，被建立的 mock 會透過關鍵字傳遞到被裝飾的函式中，並且當 @ref{4516,,patch.multiple()} 作為情境管理器時會回傳字典。

@ref{4516,,patch.multiple()} 可以做為裝飾器、類別裝飾器或情境管理器使用。引數 `spec'、`spec_set'、`create'、`autospec' 和 `new_callable' 與在 @ref{108d,,patch()} 中的引數具有相同的意義。這些引數將應用於由 @ref{4516,,patch.multiple()} 完成的`所有' patch。

當作為類別裝飾器使用時，@ref{4516,,patch.multiple()} 遵循 @code{patch.TEST_PREFIX} 來選擇要包裝的方法。
@end deffn

如果你想要 @ref{4516,,patch.multiple()} 為你建立 mock，那麼你可以使用 @ref{44eb,,DEFAULT} 作為值。如果你使用 @ref{4516,,patch.multiple()} 作為裝飾器，那麼被建立的 mock 將透過關鍵字傳遞到被裝飾的函式中。：

@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{4516,,patch.multiple()} 可以與其他 @code{patch} 裝飾器巢狀使用，但需要將透過關鍵字傳遞的引數放在 @ref{108d,,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

如果 @ref{4516,,patch.multiple()} 作為情境管理器使用，則情境管理器回傳的值是一個字典，其中被建立的 mock 會按名稱作為其鍵值：

@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 方法：啟動與停止,patch 內建函式,patch multiple,Patchers
@anchor{library/unittest mock patch-methods-start-and-stop}@anchor{4517}@anchor{library/unittest mock start-and-stop}@anchor{4518}
@subsubsection patch 方法：啟動與停止


所有的 patcher 都有 @code{start()} 與 @code{stop()} 方法。這使得在 @code{setUp} 方法中進行 patch 或在你想要在沒有巢狀使用裝飾器或 with 陳述式的情況下進行多個 patch 時變得更簡單。

要使用它們，請像平常一樣呼叫 @ref{108d,,patch()}、@ref{1871,,patch.object()} 或 @ref{18ce,,patch.dict()} ，並保留對回傳的 @code{patcher} 物件的參照。之後你就可以呼叫 @code{start()} 將 patch 準備就緒，並呼叫 @code{stop()} 來取消 patch。

如果你使用 @ref{108d,,patch()} 為你建立 mock，那麼它將透過呼叫 @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

一個典型的用法是在一個 @ref{2b3,,TestCase} 的 @code{setUp} 方法中執行多個 patch：

@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 警示 
如果你使用這個技巧，你必須確保透過呼叫 @code{stop} 來 "取消" patch。這可能會比你想像的還要複雜一點，因為如果有例外在 @code{setUp} 中被引發，則 @code{tearDown} 就不會被呼叫。@ref{c6b,,unittest.TestCase.addCleanup()} 會讓這稍微簡單一點：

@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

作為額外的好處，你不再需要保留對 @code{patcher} 物件的參照。
@end quotation
@end cartouche

也可以使用 @ref{4519,,patch.stopall()} 來停止所有已啟動的 patch。

@geindex patch.stopall() (於 unittest.mock 模組中)
@anchor{library/unittest mock unittest mock patch stopall}@anchor{4519}
@deffn {函式} patch.stopall ()

停止所有運作的 patch。只停止以 @code{start} 啟動的 patch。
@end deffn

@node patch 內建函式,TEST_PREFIX,patch 方法：啟動與停止,Patchers
@anchor{library/unittest mock id4}@anchor{451a}@anchor{library/unittest mock patch-builtins}@anchor{451b}
@subsubsection patch 內建函式


你可以 patch 模組內的任何內建函式。以下範例 patch 內建函式 @ref{21ef,,ord()}：

@example
>>> @@patch('__main__.ord')
... def test(mock_ord):
...     mock_ord.return_value = 101
...     print(ord('c'))
...
>>> test()
101
@end example

@node TEST_PREFIX,巢狀使用 Patch 裝飾器,patch 內建函式,Patchers
@anchor{library/unittest mock id5}@anchor{451c}@anchor{library/unittest mock test-prefix}@anchor{4514}
@subsubsection TEST_PREFIX


所有 patcher 都可以作為類別裝飾器使用。以這種方式使用時，它們包裝了類別上的每個測試方法。Patcher 將 @code{'test'} 開頭的方法認定為測試方法。這與 @ref{58d,,unittest.TestLoader} 預設尋找測試方法的方式相同。

你可能會想為你的測試使用不同的前綴。你可以透過設定 @code{patch.TEST_PREFIX} 來告知 patcher 使用不同的前綴：

@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 巢狀使用 Patch 裝飾器,該 patch 何處,TEST_PREFIX,Patchers
@anchor{library/unittest mock nesting-patch-decorators}@anchor{451d}
@subsubsection 巢狀使用 Patch 裝飾器


如果你想執行多個 patch，那麼你可以簡單地堆疊裝飾器。

你可以使用這個模式來堆疊多個 patch 裝飾器：

@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

請注意，裝飾器是從底部向上應用的。這是 Python 應用裝飾器的標準方式。被建立的 mock 傳遞到測試函式中的順序與此順序相同。

@node 該 patch 何處,Patch 描述器與代理物件 Proxy Objects,巢狀使用 Patch 裝飾器,Patchers
@anchor{library/unittest mock id6}@anchor{4511}@anchor{library/unittest mock where-to-patch}@anchor{44e5}
@subsubsection 該 patch 何處


@ref{108d,,patch()} 的工作原理是（暫時）將 `name' 指向的物件變更為另一個物件。可以有許多 name 指向任何單一物件，因此為了使 patch 起作用，你必須確保你 patch 了被測試系統使用的 name。

基本原則是在物件`被查找'的位置進行 patch，該位置不一定與其被定義的位置相同。幾個範例將有助於闡明這一點。

想像一下，我們想要測試一個專案，其結構如下：

@example
a.py
    -> Defines SomeClass

b.py
    -> from a import SomeClass
    -> some_function instantiates SomeClass
@end example

現在我們想要測試 @code{some_function}，但我們想使用 @ref{108d,,patch()} mock @code{SomeClass}。問題是，當我們 import 模組 b 時（我們必須這樣做），它會從模組 a import @code{SomeClass}。如果我們使用 @ref{108d,,patch()} 來 mock @code{a.SomeClass}，那麼它對我們的測試就不會有任何影響；模組 b 已經有了一個`真實的' @code{SomeClass} 的參照 ，看起來我們的 patch 並沒有任何效果。

關鍵是在使用（或查找它）的地方 patch @code{SomeClass}。在這個情況下，@code{some_function} 實際上會在我們 import 它的模組 b 中查找 @code{SomeClass}。這裡的 patch 應該長得像這樣：

@example
@@patch('b.SomeClass')
@end example

然而，考慮另一種情況，其中模組 b 並不是使用 @code{from a import SomeClass}，而是 @code{import a}，然後 @code{some_function} 使用 @code{a.SomeClass}。這兩種 import 形式都很常見。在這種情況下，我們想要 patch 的類別正在其模組中被查找，因此我們必須 patch @code{a.SomeClass}：

@example
@@patch('a.SomeClass')
@end example

@node Patch 描述器與代理物件 Proxy Objects,,該 patch 何處,Patchers
@anchor{library/unittest mock patching-descriptors-and-proxy-objects}@anchor{451e}
@subsubsection Patch 描述器與代理物件 (Proxy Objects)


@ref{4510,,patch} 和 @ref{4512,,patch.object} 都正確地 patch 和還原描述器：類別方法、靜態方法以及屬性。你應該在 `類別' 而不是實例上 patch 它們。它們還可以使用代理屬性存取的`一些'物件，例如 django 設定物件@footnote{https://web.archive.org/web/20200603181648/http://www.voidspace.org.uk/python/weblog/arch_d7_2010_12_04.shtml#e1198}。

@node MagicMock 以及魔術方法支援,輔助函式<2>,Patchers,unittest mock — mock 物件函式庫
@anchor{library/unittest mock magicmock-and-magic-method-support}@anchor{451f}
@subsubsection MagicMock 以及魔術方法支援


@menu
* Mock 魔術方法:: 
* Magic Mock:: 

@end menu

@node Mock 魔術方法,Magic Mock,,MagicMock 以及魔術方法支援
@anchor{library/unittest mock magic-methods}@anchor{44e6}@anchor{library/unittest mock mocking-magic-methods}@anchor{4520}
@subsubsection Mock 魔術方法


@ref{c36,,Mock} 支援 mock Python 協定方法，其也被稱作 @ref{4521,,"魔術方法"}。這允許 mock 物件替換容器或實作 Python 協定的其他物件。

由於魔術方法被查找的方式與一般的方法 @footnote{
魔術方法`應該'在類別而不是實例上被查找。不同版本的 Python 對於這條規則的適用並不一致。支援的協定方法應適用於所有支援的 Python 版本。
} 不同，因此專門實作了此支援方式。這代表著僅有特定的魔術方法被此方式支援。現在已支援清單中已經`幾乎'包含了所有魔術方法。如果你需要 mock 任何魔術方法而其尚未被支援，請讓我們知道。

你可以透過將你感興趣的方法設定為函式或 mock 實例來 mock 魔術方法。如果你使用函式，那麼它`必須'將 @code{self} 作為第一個引數 @footnote{
該函式基本上與類別掛鉤，但每個 @code{Mock} 實例都與其他實例保持隔離。
}。

@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

一個用法是在 @ref{186,,with} 陳述式中 mock 作為情境管理器使用的物件：

@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

對魔術方法的呼叫並不會出現在 @ref{44f2,,method_calls} 中，它們會被記錄在 @ref{44f0,,mock_calls} 內。

@cartouche
@quotation 備註 
如果你使用`spec'關鍵字引數來建立一個 mock，則嘗試設定規格中未包含的魔術方法將引發一個 @ref{5e8,,AttributeError}。
@end quotation
@end cartouche

已支援的魔術方法的完整列表是：


@itemize *

@item 
@code{__hash__}、@code{__sizeof__}、 @code{__repr__} 和 @code{__str__}

@item 
@code{__dir__}、 @code{__format__} 和 @code{__subclasses__}

@item 
@code{__round__}、@code{__floor__}、@code{__trunc__} 和 @code{__ceil__}

@item 
比較方法：@code{__lt__}、@code{__gt__}、@code{__le__}、@code{__ge__}、@code{__eq__} 和 @code{__ne__}

@item 
容器方法：@code{__getitem__}、@code{__setitem__}、@code{__delitem__}、@code{__contains__}、@code{__len__}、@code{__iter__}、@code{__reversed__} 和 @code{__missing__}

@item 
情境管理器：@code{__enter__}、@code{__exit__}、@code{__aenter__} 和 @code{__aexit__}

@item 
一元數值方法：@code{__neg__}、@code{__pos__} 和 @code{__invert__}

@item 
數值方法（包括右側 (right hand) 和原地 (in-place) 變體）：@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__} 和 @code{__pow__}

@item 
數值轉換方法：@code{__complex__}、@code{__int__}、@code{__float__} 和 @code{__index__}

@item 
描述器方法：@code{__get__}、@code{__set__} 和 @code{__delete__}

@item 
Pickling：@code{__reduce__}、@code{__reduce_ex__}、@code{__getinitargs__}、@code{__getnewargs__}、@code{__getstate__} 和 @code{__setstate__}

@item 
檔案系統路徑表示法：@code{__fspath__}

@item 
非同步疊代方法：@code{__aiter__} 和 @code{__anext__}
@end itemize


在 3.8 版的變更: 新增對於 @ref{e47,,os.PathLike.__fspath__()} 的支援。



在 3.8 版的變更: 新增對於 @code{__aenter__}、@code{__aexit__}、@code{__aiter__} 和 @code{__anext__} 的支援。


以下方法存在，但「不」被支援，因為它們在被 mock 使用時，會無法動態設定，或可能導致問題：


@itemize *

@item 
@code{__getattr__}、@code{__setattr__}、@code{__init__} 和 @code{__new__}

@item 
@code{__prepare__}、@code{__instancecheck__}、@code{__subclasscheck__}、@code{__del__}
@end itemize

@node Magic Mock,,Mock 魔術方法,MagicMock 以及魔術方法支援
@anchor{library/unittest mock magic-mock}@anchor{4522}
@subsubsection Magic Mock


@code{MagicMock} 有兩個變體：@ref{108a,,MagicMock} 和 @ref{44ea,,NonCallableMagicMock}。

@geindex MagicMock (unittest.mock 中的類別)
@anchor{library/unittest mock unittest mock MagicMock}@anchor{108a}
@deffn {類別} unittest.mock.MagicMock (*args, **kw)

@code{MagicMock} 是 @ref{c36,,Mock} 的子類別，其預設具有大多數@ref{4521,,魔術方法}的實作。你可以使用 @code{MagicMock}，而無需自行配置魔術方法。

建構函式參數的意義與 @ref{c36,,Mock} 中的參數相同。

如果你使用 `spec' 或 `spec_set' 引數，那麼`只有'規格中存在的魔術方法會被建立。
@end deffn

@geindex NonCallableMagicMock (unittest.mock 中的類別)
@anchor{library/unittest mock unittest mock NonCallableMagicMock}@anchor{44ea}
@deffn {類別} unittest.mock.NonCallableMagicMock (*args, **kw)

@ref{108a,,MagicMock} 的不可呼叫版本。

建構函式參數的意義與 @ref{108a,,MagicMock} 中的參數相同，但 `return_value' 和 `side_effect' 除外，它們對不可呼叫的 mock 來說沒有任何意義。
@end deffn

魔術方法是使用 @ref{108a,,MagicMock} 物件設定的，因此你可以配置它們並以一般的方法來使用它們：

@example
>>> mock = MagicMock()
>>> mock[3] = 'fish'
>>> mock.__setitem__.assert_called_with(3, 'fish')
>>> mock.__getitem__.return_value = 'result'
>>> mock[2]
'result'
@end example

預設情況下，許多協定方法都需要回傳特定種類的物件。這些方法預先配置了預設回傳值，因此如果你對回傳值不感興趣，則無需執行任何操作即可使用它們。如果你想更改預設值，你仍然可以手動`設定'回傳值。

方法及其預設值：


@itemize *

@item 
@code{__lt__}：@ref{1a2,,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__}：mock 的預設雜湊

@item 
@code{__str__}：mock 的預設字串

@item 
@code{__sizeof__}：mock 的預設 sizeof
@end itemize

舉例來說：

@example
>>> mock = MagicMock()
>>> int(mock)
1
>>> len(mock)
0
>>> list(mock)
[]
>>> object() in mock
False
@end example

@code{__eq__()} 和 @code{__ne__()} 這兩個相等的方法是特別的。它們使用 @ref{44e4,,side_effect} 屬性對識別性 (identity) 進行預設的相等比較，除非你變更它們的回傳值以回傳其他內容：

@example
>>> MagicMock() == 3
False
>>> MagicMock() != 3
True
>>> mock = MagicMock()
>>> mock.__eq__.return_value = True
>>> mock == 3
True
@end example

@code{MagicMock.__iter__()} 的回傳值可以是任何可疊代物件，且不需是一個疊代器：

@example
>>> mock = MagicMock()
>>> mock.__iter__.return_value = ['a', 'b', 'c']
>>> list(mock)
['a', 'b', 'c']
>>> list(mock)
['a', 'b', 'c']
@end example

如果回傳值`是'一個疊代器，那麼對其進行一次疊代將消耗它，並且後續疊代將產生一個空串列：

@example
>>> mock.__iter__.return_value = iter(['a', 'b', 'c'])
>>> list(mock)
['a', 'b', 'c']
>>> list(mock)
[]
@end example

@code{MagicMock} 配置了所有支援的魔術方法，除了一些少見和過時的方法。如果你想要，你仍然可以設定這些魔術方法。

@code{MagicMock} 中支援但預設未設置的魔術方法包含：


@itemize *

@item 
@code{__subclasses__}

@item 
@code{__dir__}

@item 
@code{__format__}

@item 
@code{__get__}、@code{__set__} 和 @code{__delete__}

@item 
@code{__reversed__} 和 @code{__missing__}

@item 
@code{__reduce__}、@code{__reduce_ex__}、@code{__getinitargs__}、@code{__getnewargs__}、@code{__getstate__} 和 @code{__setstate__}

@item 
@code{__getformat__}
@end itemize

@node 輔助函式<2>,side_effect、return_value 和 wraps 的優先順序,MagicMock 以及魔術方法支援,unittest mock — mock 物件函式庫
@anchor{library/unittest mock helpers}@anchor{4523}
@subsubsection 輔助函式


@menu
* sentinel（哨兵）:: 
* DEFAULT:: 
* call:: 
* create_autospec:: 
* ANY:: 
* FILTER_DIR:: 
* mock_open:: 
* Autospeccing（自動規格）:: 
* 密封 mock:: 

@end menu

@node sentinel（哨兵）,DEFAULT,,輔助函式<2>
@anchor{library/unittest mock sentinel}@anchor{4524}
@subsubsection sentinel（哨兵）


@geindex sentinel (於 unittest.mock 模組中)
@anchor{library/unittest mock unittest mock sentinel}@anchor{d94}
@deffn {資料} unittest.mock.sentinel

@code{哨兵}物件提供了一種為你的測試提供獨特物件的便利方式。

當你使用名稱存取屬性時，屬性會根據需要被建立。存取相同的屬性將始終回傳相同的物件。回傳的物件會具有合適的 repr，讓測試失敗的訊息是可閱讀的。


在 3.7 版的變更: @code{哨兵}屬性現在當被@ref{29,,複製}或@ref{ab,,序列化}時會保留其識別性。

@end deffn

在測試時，有時你需要測試特定物件是否作為引數被傳遞給另一個方法或回傳。建立命名的哨兵物件來測試這一點是常見的。@ref{d94,,sentinel} 提供了一種此類建立和測試物件識別性的便利方式。

在這個例子中，我們 monkey patch @code{method} 以回傳 @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（哨兵）,輔助函式<2>
@anchor{library/unittest mock default}@anchor{4525}
@subsubsection DEFAULT


@geindex DEFAULT (於 unittest.mock 模組中)
@anchor{library/unittest mock unittest mock DEFAULT}@anchor{44eb}
@deffn {資料} unittest.mock.DEFAULT

@ref{44eb,,DEFAULT} 物件是一個預先建立的哨兵（實際上是 @code{sentinel.DEFAULT}）。它可以被 @ref{44e4,,side_effect} 函式使用來表示正常的回傳值應該被使用。
@end deffn

@node call,create_autospec,DEFAULT,輔助函式<2>
@anchor{library/unittest mock call}@anchor{4526}
@subsubsection call


@geindex call() (於 unittest.mock 模組中)
@anchor{library/unittest mock unittest mock call}@anchor{1c7c}
@deffn {函式} unittest.mock.call (*args, **kwargs)

與 @ref{1c32,,call_args}、@ref{44f8,,call_args_list}、@ref{44f0,,mock_calls} 和 @ref{44f2,,method_calls} 相比，@ref{1c7c,,call()} 是一個用於進行更簡單的斷言的輔助物件。@ref{1c7c,,call()} 也可以與 @ref{1972,,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{4527}
@deffn {方法} call.call_list ()

對於表示多個呼叫的 call 物件，@ref{4527,,call_list()} 回傳所有中間呼叫以及最終呼叫的串列。
@end deffn

@code{call_list} 在對「鍊接呼叫 (chained calls)」進行斷言時特別有用。鍊接呼叫是在單行程式碼進行的多次呼叫。這會導致 mock 上的 @ref{44f0,,mock_calls} 中出現多個項目。手動建構呼叫序列會相當單調乏味。

@ref{4527,,call_list()} 可以從同一個鍊接呼叫建構呼叫序列：

@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{44f9}
取決於它的建構方式，一個 @code{call} 物件會是（位置引數, 關鍵字引數）的元組，或是 (名稱, 位置引數, 關鍵字引數) 的元組。當你自己建構它們時，這並不是那麼有趣，但是 @ref{1c32,,Mock.call_args}、@ref{44f8,,Mock.call_args_list} 和 @ref{44f0,,Mock.mock_calls} 屬性中的 @code{call} 物件可以被內省以取得它們包含的各個引數。

@ref{1c32,,Mock.call_args} 和 @ref{44f8,,Mock.call_args_list} 中的 @code{call} 物件是（位置引數, 關鍵字引數）的二元組，而 @ref{44f0,,Mock.mock_calls} 中的 @code{call} 物件以及你自己建立的 @code{call} 物件是（名稱, 位置引數, 關鍵字引數）的三元組。

你可以利用它們作為元組的特性來提取單個引數，以進行更複雜的內省和斷言。位置引數是一個元組（如果沒有位置引數則為空元組），關鍵字引數是一個字典：

@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,輔助函式<2>
@anchor{library/unittest mock create-autospec}@anchor{4528}
@subsubsection create_autospec


@geindex create_autospec() (於 unittest.mock 模組中)
@anchor{library/unittest mock unittest mock create_autospec}@anchor{189a}
@deffn {函式} unittest.mock.create_autospec (spec, spec_set=False, instance=False, **kwargs)

使用另一個物件作為規格建立一個 mock 物件。Mock 上的屬性將使用 `spec' 物件上的對應屬性作為其規格。

被 mock 的函式或方法將檢查其引數，以確保他們被使用正確的簽名來呼叫。

如果 `spec_set' 為 @code{True}，則嘗試設定規格物件上不存在的屬性將引發 @ref{5e8,,AttributeError}。

如果一個類別作為規格使用，則 mock（該類別的實例）的回傳值將具有相同的規格。你可以透過傳遞 @code{instance=True} 來使用一個類別作為一個實例物件的規格。只有當 mock 的實例是可呼叫物件時，回傳的 mock 才會是可呼叫物件。

@ref{189a,,create_autospec()} 也接受任意的關鍵字引數，這些引數會傳遞給已建立的 mock 的建構函式。
@end deffn

請參閱 @ref{44e7,,Autospeccing（自動規格）} 以得知如何以 @ref{189a,,create_autospec()} 使用自動規格以及如何在 @ref{108d,,patch()} 中使用 `autospec' 引數的範例。


在 3.8 版的變更: 如果目標是一個非同步函式，@ref{189a,,create_autospec()} 現在會回傳一個 @ref{c35,,AsyncMock}。


@node ANY,FILTER_DIR,create_autospec,輔助函式<2>
@anchor{library/unittest mock any}@anchor{4529}
@subsubsection ANY


@geindex ANY (於 unittest.mock 模組中)
@anchor{library/unittest mock unittest mock ANY}@anchor{1c7a}
@deffn {資料} unittest.mock.ANY
@end deffn

有時你可能需要對 mock 的呼叫中的`某些'引數進行斷言，但你不在意其他的某些引數，或想將它們單獨從 @ref{1c32,,call_args} 中取出並進行更加複雜的斷言。

要忽略某些引數，你可以傳入對`所有物件'來說都相等的物件。那麼無論傳入什麼內容，對 @code{assert_used_with()} 和 @code{assert_used_once_with()} 的呼叫都會成功。

@example
>>> mock = Mock(return_value=None)
>>> mock('foo', bar=object())
>>> mock.assert_called_once_with('foo', bar=ANY)
@end example

@ref{1c7a,,ANY} 也可以用來與呼叫串列進行比較，例如 @ref{44f0,,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{1c7a,,ANY} 不只能與呼叫物件比較，其也可以在測試斷言中使用：

@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,輔助函式<2>
@anchor{library/unittest mock filter-dir}@anchor{452a}
@subsubsection FILTER_DIR


@geindex FILTER_DIR (於 unittest.mock 模組中)
@anchor{library/unittest mock unittest mock FILTER_DIR}@anchor{44f4}
@deffn {資料} unittest.mock.FILTER_DIR
@end deffn

@ref{44f4,,FILTER_DIR} 是一個模組級別的變數，用於控制 mock 物件回應 @ref{83d,,dir()} 的方式。其預設值為 @code{True}，它使用以下描述的過濾方式來只顯示有用的成員。如果你不喜歡這個過濾方式，或由於診斷意圖而需要將其關閉，請設定 @code{mock.FILTER_DIR = False}。

當過濾方式開啟時，@code{dir(some_mock)} 僅會顯示有用的屬性，並將包括通常不會顯示的任何動態建立的屬性。如果 mock 是使用 `spec'（或 `autospec'）來建立的，那麼源頭的所有屬性都會顯示，即使它們尚未被存取：

@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

許多不是很有用的（對 @ref{c36,,Mock} 來說是私有的，而不是被 mock 的東西）底線和雙底線前綴屬性已從在 @ref{c36,,Mock} 上呼叫 @ref{83d,,dir()} 的結果中濾除。如果你不喜歡這種特性，可以透過設定模組級別開關 @ref{44f4,,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

或者，你可以只使用 @code{vars(my_mock)}（實例成員）和 @code{dir(type(my_mock))}（型別成員）來略過過濾，而不考慮 @ref{44f4,,FILTER_DIR}。

@node mock_open,Autospeccing（自動規格）,FILTER_DIR,輔助函式<2>
@anchor{library/unittest mock mock-open}@anchor{452b}
@subsubsection mock_open


@geindex mock_open() (於 unittest.mock 模組中)
@anchor{library/unittest mock unittest mock mock_open}@anchor{11e2}
@deffn {函式} unittest.mock.mock_open (mock=None, read_data=None)

用於建立取代 @ref{315,,open()} 用途的 mock 的輔助函式。它適用於直接呼叫或用作情境管理器的 @ref{315,,open()}。

`mock' 引數是要配置的 mock 物件。如果其為 @code{None}（預設值），那麼就會為你建立一個 @ref{108a,,MagicMock}，其 API 限制在標準檔案處理上可用的方法或屬性。

`read_data' 是檔案處理方法 @ref{1018,,read()}、@ref{152a,,readline()} 和 @ref{264c,,readlines()} 的回傳字串。對這些方法的呼叫將從 `read_data' 取得資料，直到資料耗盡。對這些方法的 mock 非常單純：每次呼叫 `mock' 時，`read_data' 都會倒回到起點。如果你需要對提供給測試程式碼的資料進行更多控制，你會需要自行客製化這個 mock。如果這樣還不夠，PyPI@footnote{https://pypi.org} 上的其中一個記憶體內檔案系統 (in-memory filesystem) 套件可以提供用於測試的真實檔案系統。


在 3.4 版的變更: 新增對 @ref{152a,,readline()} 和 @ref{264c,,readlines()} 的支援。@ref{1018,,read()} 的 mock 更改為消耗 `read_data' 而不是在每次呼叫時回傳它。



在 3.5 版的變更: 現在，每次呼叫 `mock' 時都會重置 `read_data'。



在 3.8 版的變更: 新增 @ref{1f71,,__iter__()} 到實作中，以便使疊代（例如在 for 迴圈中）正確地消耗 `read_data'。

@end deffn

使用 @ref{315,,open()} 作為情境管理器是確保檔案處理正確關閉的好方式，且這種方式正在變得普遍：

@example
with open('/some/path', 'w') as f:
    f.write('something')
@end example

問題是，即使你 mock 了對 @ref{315,,open()} 的呼叫，它也是作為情境管理器使用的`回傳物件'（且其 @ref{7dd,,__enter__()} 和 @code{__exit__()} 已被呼叫）。

使用 @ref{108a,,MagicMock} mock 情境管理器相當常見並且精細，因此輔助函式就非常有用：

@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

以及讀取檔案：

@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（自動規格）,密封 mock,mock_open,輔助函式<2>
@anchor{library/unittest mock auto-speccing}@anchor{44e7}@anchor{library/unittest mock autospeccing}@anchor{452c}
@subsubsection Autospeccing（自動規格）


自動規格以 mock 現有的 @code{spec} 功能作為基礎。它將 mock 的 api 限制為原始物件（規格）的 api，但它是遞迴的（惰性 (lazily) 實現），因此 mock 的屬性僅具有與規格的屬性相同的 api。此外，被 mock 的函式/方法具有與原始的函式/方法相同的呼叫簽名，因此如果它們被不正確地呼叫，就會引發 @ref{198,,TypeError}。

在解釋自動規格如何運作之前，我們先解釋為什麼需要它。

@ref{c36,,Mock} 是一個非常強大且靈活的物件，但它有一個常見的 mock 缺陷。如果你重構某些程式碼或重新命名成員等，則任何仍然使用`舊 api' 但使用 mock 而非真實物件的程式碼測試仍然會通過。這意味著即使你的程式碼壞了，但測試仍可以全部通過。


在 3.5 版的變更: 在 3.5 之前，當測試應該引發錯誤時，斷言單字中存在拼字錯誤的測驗會默默地通過。你仍可以透過將 @code{unsafe=True} 傳遞給 Mock 來實作此行為。


謹記這是你需要有整合測試和單元測試的另一個原因。單獨測試所有內容都很好，但如果你不測試你的單元是如何「連接在一起」的，那麼測試還是有機會發現很多錯誤。

@ref{10d,,unittest.mock} 已經提供了一個功能來幫助解決這個問題，其稱為 speccing。如果你使用類別或實例作為 mock 的 @code{spec}，那麼你在 mock 上只能存取真實類別中存在的屬性：

@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

該規格僅適用於 mock 本身，因此在 mock 上的任何方法仍然有相同的問題：

@example
>>> mock.header_items()
<mock.Mock object at 0x...>
>>> mock.header_items.assret_called_with()  # 故意的錯字！
@end example

自動規格解決了這個問題。你可以將 @code{autospec=True} 傳遞給 @ref{108d,,patch()} / @ref{1871,,patch.object()} 或使用 @ref{189a,,create_autospec()} 函式建立帶有規格的 mock。如果你對 @ref{108d,,patch()} 使用 @code{autospec=True} 引數，則被取代的物件將作為規格物件使用。因為規格是「惰性」完成的（規格是在 mock 被存取時作為屬性被建立的），所以你可以將它與非常複雜或深度巢狀使用的物件（例如連續引用的模組）一起使用，而不會過於影響性能。

這是一個正在使用的例子：

@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

你可以看到 @code{request.Request} 有一個規格。@code{request.Request} 在建構函式中接受兩個引數（其中之一是 `self'）。如果我們錯誤地呼叫它，會發生以下情況：

@example
>>> req = request.Request()
Traceback (most recent call last):
 ...
TypeError: <lambda>() takes at least 2 arguments (1 given)
@end example

此規格也適用於實例化的類別（即有規格的 mock 的回傳值）：

@example
>>> req = request.Request('foo')
>>> req
<NonCallableMagicMock name='request.Request()' spec='Request' id='...'>
@end example

@code{Request} 物件不是可呼叫物件，因此實例化我們 mock out 的 @code{request.Request} 的回傳值是不可呼叫的 mock。規格到位後，斷言中的任何拼字錯誤都會引發正確的錯誤：

@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

在許多情況下，你只需要將 @code{autospec=True} 新增至現有的 @ref{108d,,patch()} 呼叫中，然後就可以防止因拼字錯誤和 api 變更而導致的錯誤。

除了透過 @ref{108d,,patch()} 使用 `autospec' 之外，還有一個 @ref{189a,,create_autospec()} 用於直接建立有自動規格的 mock：

@example
>>> from urllib import request
>>> mock_request = create_autospec(request)
>>> mock_request.Request('foo', 'bar')
<NonCallableMagicMock name='mock.Request()' spec='Request' id='...'>
@end example

然而，這並非完全沒有限制，這就是為什麼它不是預設的行為。為了理解規格物件上有哪些可用屬性，autospec 必須內省（存取屬性）規格。當你遍歷 mock 上的屬性時，原始物件的對應遍歷正在默默發生。如果你的規格物件具有可以觸發程式碼執行的屬性或描述器，那麼你可能無法使用 autospec。換句話說，設計你的物件讓內省是安全的 @footnote{
這只適用於類別或已經實例化的物件。呼叫一個被 mock 的類別來建立一個 mock 實例`不會'建立真的實例。它僅查找屬性及對 @ref{83d,,dir()} 的呼叫。
} 會比較好。

一個更嚴重的問題是，在 @ref{8b7,,__init__()} 方法中建立實例屬性是常見的，而其根本不存在於類別中。`autospec' 無法知道任何動態建立的屬性，並將 api 限制為可見的屬性。：

@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

有幾種不同的方法可以解決這個問題。最簡單但可能有點煩人的方法是在建立後簡單地在 mock 上設定所需的屬性。因為雖然 `autospec' 不允許你取得規格中不存在的屬性，但是它不會阻止你設定它們：

@example
>>> with patch('__main__.Something', autospec=True):
...   thing = Something()
...   thing.a = 33
...
@end example

`spec' 和 `autospec' 有一個更激進的版本，它會`確實地'阻止你設定不存在的屬性。如果你想確保你的程式碼僅能`設定'有效的屬性，那麼這會很有用，但顯然它也順便阻止了這個特殊情況：

@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

解決問題的最佳方法可能是新增類別屬性作為在 @ref{8b7,,__init__()} 中初始化的實例成員的預設值。請注意，如果你僅在 @code{__init__()} 中設定預設屬性，那麼透過類別屬性（當然在實例之間共用）提供它們也會更快。例如：

@example
class Something:
    a = 33
@end example

這就帶來了另一個問題。為稍後將成為不同型別的物件的成員提供預設值 @code{None} 是相對常見的。@code{None} 作為規格是無用的，因為它不允許你存取其上的`任何'屬性或方法。由於 @code{None} 作為規格`永遠不會'有用，並且可能表示通常屬於其他型別的成員，因此自動規格不會對設定為 @code{None} 的成員使用規格。這些會只是普通的 mock（通常是 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

如果修改正式生產 (production) 類別以新增預設值不符合你的喜好，那麼還有更多選擇。其中之一就是簡單地使用實例作為規格而不是使用類別。另一種是建立一個正式生產類別的子類別，並將預設值新增至子類別中，而不影響正式生產類別。這兩個都需要你使用替代物件作為規格。值得慶幸的是 @ref{108d,,patch()} 支援這一點 - 你可以簡單地將替代物件作為 `autospec' 引數傳遞：

@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 密封 mock,,Autospeccing（自動規格）,輔助函式<2>
@anchor{library/unittest mock sealing-mocks}@anchor{452d}
@subsubsection 密封 mock


@c from unittest.mock import seal

@geindex seal() (於 unittest.mock 模組中)
@anchor{library/unittest mock unittest mock seal}@anchor{d95}
@deffn {函式} unittest.mock.seal (mock)

當存取被密封的 mock 的屬性或其任何已經遞迴 mock 的屬性時，seal 將停用 mock 的自動建立。

如果將具有名稱或規格的 mock 實例指派給屬性，則不會出現在密封鏈中。這表示可藉由固定 mock 物件的一部分來防止密封。：

@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


在 3.7 版被加入.

@end deffn

@node side_effect、return_value 和 wraps 的優先順序,,輔助函式<2>,unittest mock — mock 物件函式庫
@anchor{library/unittest mock order-of-precedence-of-side-effect-return-value-and-wraps}@anchor{452e}
@subsubsection @code{side_effect}、@code{return_value} 和 `wraps' 的優先順序


它們的優先順序是：


@enumerate 

@item 
@ref{44e4,,side_effect}

@item 
@ref{44ec,,return_value}

@item 
`wraps'
@end enumerate

如果這三個都有設定，mock 將會回傳來自 @ref{44e4,,side_effect} 的值，並忽略 @ref{44ec,,return_value} 和被包裝物件。如果設定了任兩項，則優先順序較高的一項將回傳該值。無論先設定哪個順序，優先順序都保持不變。

@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

由於 @code{None} 是 @ref{44e4,,side_effect} 的預設值，如果將其值重新賦值回為 @code{None}，則會檢查 @ref{44ec,,return_value} 和被包裝物件之間的優先順序，忽略 @ref{44e4,,side_effect}。

@example
>>> order_mock.get_value.side_effect = None
>>> order_mock.get_value()
'second'
@end example

如果 @ref{44e4,,side_effect} 回傳的值是 @ref{44eb,,DEFAULT}，它將被忽略，並且優先順序被移動到後面一個以獲得要回傳的值。

@example
>>> from unittest.mock import DEFAULT
>>> order_mock.get_value.side_effect = [DEFAULT]
>>> order_mock.get_value()
'second'
@end example

當 @ref{c36,,Mock} 包裝一個物件時，@ref{44ec,,return_value} 的預設值將為 @ref{44eb,,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

優先順序將忽略該值，並將移動到最後一個，即被包裝物件。

當對被包裝物件進行真正的呼叫時，建立此 mock 的實例將回傳該類別的真實實例。必須傳遞被包裝物件所需的位置引數（如果存在）。

@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

但如果你為其賦予 @code{None} 則不會被忽略，因為它是明確賦值。因此，優先順序不會移至被包裝物件。

@example
>>> order_mock.get_value.return_value = None
>>> order_mock.get_value() is None
True
@end example

即使你在初始化 mock 時同時設定所有三個，優先順序也保持不變：

@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

如果 @ref{44e4,,side_effect} 已耗盡，則優先順序將不會使值由後面取得。相反地這會引發 @code{StopIteration} 例外。

@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 --- Python 的回歸測試 regression tests 套件,unittest mock — mock 物件函式庫,開發工具
@anchor{library/unittest mock-examples doc}@anchor{452f}@anchor{library/unittest mock-examples translation-repo}@anchor{4530}@anchor{library/unittest mock-examples unittest-mock-getting-started}@anchor{4531}
@subsection @code{unittest.mock} --- 入門指南



在 3.3 版被加入.

@anchor{library/unittest mock-examples getting-started}@anchor{4532}
@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 的方式:: 
* Patch 裝飾器:: 
* 更多範例:: 

@end menu

@node 使用 Mock 的方式,Patch 裝飾器,,unittest mock --- 入門指南
@anchor{library/unittest mock-examples using-mock}@anchor{4533}
@subsubsection 使用 Mock 的方式


@menu
* 使用 Mock 來 patching 方法:: 
* 對物件的方法呼叫使用 mock:: 
* Mock 類別: Mock 類別<2>. 
* 命名你的 mock:: 
* 追蹤所有呼叫:: 
* 設定回傳值和屬性:: 
* 透過 mock 引發例外:: 
* Side effect 函式以及可疊代物件:: 
* Mock 非同步可疊代物件:: 
* Mock 非同步情境管理器:: 
* 從現有物件建立 mock:: 
* 使用 side_effect 回傳各別檔案內容:: 

@end menu

@node 使用 Mock 來 patching 方法,對物件的方法呼叫使用 mock,,使用 Mock 的方式
@anchor{library/unittest mock-examples mock-patching-methods}@anchor{4534}
@subsubsection 使用 Mock 來 patching 方法


@ref{c36,,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

一旦我們的 mock 已經被使用（例如在這個範例中的 @code{real.method}），它就有了方法和屬性，允許你對其使用方式進行斷言 (assertions)。

@cartouche
@quotation 備註 
在大多數的範例中，@ref{c36,,Mock} 和 @ref{108a,,MagicMock} 類別是可以互換的。不過由於 @code{MagicMock} 是功能更強大的類別，因此通常它是一個更好的選擇。
@end quotation
@end cartouche

一旦 mock 被呼叫，它的 @ref{44f6,,called} 屬性將被設定為 @code{True}。更重要的是，我們可以使用 @ref{1ccb,,assert_called_with()} 或 @ref{44ee,,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,Mock 類別<2>,使用 Mock 來 patching 方法,使用 Mock 的方式
@anchor{library/unittest mock-examples mock-for-method-calls-on-an-object}@anchor{4535}
@subsubsection 對物件的方法呼叫使用 mock


在上一個範例中，我們直接對物件上的方法進行 patch，以檢查它是否被正確呼叫。另一個常見的用法是將一個物件傳遞給一個方法（或受測系統的某一部分），然後檢查它是否以正確的方式被使用。

下面是一個單純的 @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

我們不必做任何額外的事情來為 mock 提供 'close' 方法，存取 close 會建立它。因此，如果 'close' 並未被呼叫過，在測試中存取 'close' 就會建立它，但 @ref{1ccb,,assert_called_with()} 就會引發一個失敗的例外。

@node Mock 類別<2>,命名你的 mock,對物件的方法呼叫使用 mock,使用 Mock 的方式
@anchor{library/unittest mock-examples mocking-classes}@anchor{4536}
@subsubsection Mock 類別


一個常見的使用案例是在測試的時候 mock 被程式碼實例化的類別。當你 patch 一個類別時，該類別就會被替換為 mock。實例是透過`呼叫類別'建立的。這代表你可以透過查看被 mock 的類別的回傳值來存取「mock 實例」。

在下面的範例中，我們有一個函式 @code{some_function}，它實例化 @code{Foo} 並呼叫它的方法。對 @ref{108d,,patch()} 的呼叫將類別 @code{Foo} 替換為一個 mock。@code{Foo} 實例是呼叫 mock 的結果，因此它是透過修改 mock @ref{44ec,,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 命名你的 mock,追蹤所有呼叫,Mock 類別<2>,使用 Mock 的方式
@anchor{library/unittest mock-examples naming-your-mocks}@anchor{4537}
@subsubsection 命名你的 mock


為你的 mock 命名可能會很有用。這個名稱會顯示在 mock 的 repr 中，且當 mock 出現在測試的失敗訊息中時，名稱會很有幫助。該名稱也會傳播到 mock 的屬性或方法：

@example
>>> mock = MagicMock(name='foo')
>>> mock
<MagicMock name='foo' id='...'>
>>> mock.method
<MagicMock name='foo.method' id='...'>
@end example

@node 追蹤所有呼叫,設定回傳值和屬性,命名你的 mock,使用 Mock 的方式
@anchor{library/unittest mock-examples tracking-all-calls}@anchor{4538}
@subsubsection 追蹤所有呼叫


通常你會想要追蹤對一個方法的多個呼叫。@ref{44f0,,mock_calls} 屬性記錄對 mock 的子屬性以及其子屬性的所有呼叫。

@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{1c7c,,call} 物件來建構串列以與 @code{mock_calls} 進行比較：

@example
>>> expected = [call.method(), call.attribute.method(10, x=53)]
>>> mock.mock_calls == expected
True
@end example

然而，回傳 mock 的呼叫的參數不會被記錄，這代表在巢狀呼叫中，無法追蹤用於建立上代的參數 important 的值：

@example
>>> m = Mock()
>>> m.factory(important=True).deliver()
<Mock name='mock.factory().deliver()' id='...'>
>>> m.mock_calls[-1] == call.factory(important=False).deliver()
True
@end example

@node 設定回傳值和屬性,透過 mock 引發例外,追蹤所有呼叫,使用 Mock 的方式
@anchor{library/unittest mock-examples setting-return-values-and-attributes}@anchor{4539}
@subsubsection 設定回傳值和屬性


在 mock 物件上設定回傳值非常簡單：

@example
>>> mock = Mock()
>>> mock.return_value = 3
>>> mock()
3
@end example

當然，你可以對 mock 上的方法執行相同的操作：

@example
>>> mock = Mock()
>>> mock.method.return_value = 3
>>> mock.method()
3
@end example

回傳值也可以在建構函式中設定：

@example
>>> mock = Mock(return_value=3)
>>> mock()
3
@end example

如果你需要在 mock 上進行屬性設置，只需執行以下操作：

@example
>>> mock = Mock()
>>> mock.x = 3
>>> mock.x
3
@end example

有時你想要 mock 更複雜的情況，例如 @code{mock.connection.cursor().execute("SELECT 1")}。如果我們希望此呼叫回傳一個串列，那麼我們就必須配置巢狀呼叫的結果。

如下所示，我們可以使用 @ref{1c7c,,call} 在「鍊接呼叫 (chained 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 透過 mock 引發例外,Side effect 函式以及可疊代物件,設定回傳值和屬性,使用 Mock 的方式
@anchor{library/unittest mock-examples raising-exceptions-with-mocks}@anchor{453a}
@subsubsection 透過 mock 引發例外


一個有用的屬性是 @ref{44e4,,side_effect}。如果將其設定為例外類別或實例，則當 mock 被呼叫時將引發例外。

@example
>>> mock = Mock(side_effect=Exception('Boom!'))
>>> mock()
Traceback (most recent call last):
  ...
Exception: Boom!
@end example

@node Side effect 函式以及可疊代物件,Mock 非同步可疊代物件,透過 mock 引發例外,使用 Mock 的方式
@anchor{library/unittest mock-examples side-effect-functions-and-iterables}@anchor{453b}
@subsubsection Side effect 函式以及可疊代物件


@code{side_effect} 也可以設定為函式或可疊代物件。@code{side_effect} 作為可疊代物件的使用案例是：當你的 mock 將會被多次呼叫，且你希望每次呼叫回傳不同的值。當你將 @code{side_effect} 設定為可疊代物件時，對 mock 的每次呼叫都會傳回可疊代物件中的下一個值：

@example
>>> mock = MagicMock(side_effect=[4, 5, 6])
>>> mock()
4
>>> mock()
5
>>> mock()
6
@end example

對於更進階的使用案例，例如根據 mock 被呼叫的內容動態變更回傳值，可以將 @code{side_effect} 設成一個函式。該函式會使用與 mock 相同的引數被呼叫。函式回傳的內容就會是呼叫回傳的內容：

@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 Mock 非同步可疊代物件,Mock 非同步情境管理器,Side effect 函式以及可疊代物件,使用 Mock 的方式
@anchor{library/unittest mock-examples mocking-asynchronous-iterators}@anchor{453c}
@subsubsection Mock 非同步可疊代物件


從 Python 3.8 開始，@code{AsyncMock} 和 @code{MagicMock} 支援透過 @code{__aiter__} 來 mock @ref{f72,,Asynchronous Iterators}。@code{__aiter__} 的 @ref{44ec,,return_value} 屬性可用來設定用於疊代的回傳值。

@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 Mock 非同步情境管理器,從現有物件建立 mock,Mock 非同步可疊代物件,使用 Mock 的方式
@anchor{library/unittest mock-examples mocking-asynchronous-context-manager}@anchor{453d}
@subsubsection Mock 非同步情境管理器


從 Python 3.8 開始，@code{AsyncMock} 和 @code{MagicMock} 支援透過 @code{__aenter__} 和 @code{__aexit__} 來 mock @ref{80b,,Asynchronous Context Managers}。預設情況下，@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 從現有物件建立 mock,使用 side_effect 回傳各別檔案內容,Mock 非同步情境管理器,使用 Mock 的方式
@anchor{library/unittest mock-examples creating-a-mock-from-an-existing-object}@anchor{453e}
@subsubsection 從現有物件建立 mock


過度使用 mock 的一個問題是，它將你的測試與 mock 的實作結合在一起，而不是與真實的程式碼結合。假設你有一個實作 @code{some_method} 的類別，在另一個類別的測試中，你提供了一個 mock 的物件，其`也'提供了 @code{some_method}。如果之後你重構第一個類別，使其不再具有 @code{some_method} - 那麼即使你的程式碼已經損壞，你的測試也將繼續通過！

@ref{c36,,Mock} 允許你使用 `spec' 關鍵字引數提供一個物件作為 mock 的規格。對 mock 存取規格物件上不存在的方法或屬性將立即引發一個屬性錯誤。如果你更改規格的實作，那麼使用該類別的測試將立即失敗，而無需在這些測試中實例化該類別。

@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

使用規格還可以更聰明地匹配對 mock 的呼叫，無論引數是作為位置引數還是命名引數傳遞：

@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

如果你希望這種更聰明的匹配也可以應用於 mock 上的方法呼叫，你可以使用@ref{44e7,,自動規格}。

如果你想要一種更強大的規格形式來防止設定任意屬性以及取得它們，那麼你可以使用 `spec_set' 而不是 `spec'。

@node 使用 side_effect 回傳各別檔案內容,,從現有物件建立 mock,使用 Mock 的方式
@anchor{library/unittest mock-examples using-side-effect-to-return-per-file-content}@anchor{453f}
@subsubsection 使用 side_effect 回傳各別檔案內容


@ref{11e2,,mock_open()} 是用於 patch @ref{315,,open()} 方法。@ref{44e4,,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 裝飾器,更多範例,使用 Mock 的方式,unittest mock --- 入門指南
@anchor{library/unittest mock-examples patch-decorators}@anchor{4540}
@subsubsection Patch 裝飾器


@cartouche
@quotation 備註 
使用 @ref{108d,,patch()} 時，需注意的是你得在被查找物件的命名空間中（in the namespace where they are looked up）patch 物件。這通常很直接，但若需要快速導引，請參閱@ref{44e5,,該 patch 何處}。
@end quotation
@end cartouche

測試中的常見需求是 patch 類別屬性或模組屬性，例如 patch 一個內建函式（built-in）或 patch 模組中的類別以測試它是否已實例化。模組和類別實際上是全域的，因此在測試後必須撤銷它們的 patch，否則 patch 將延續到其他測試中並導致難以診斷問題。

mock 為此提供了三個方便的裝飾器：@ref{108d,,patch()}、@ref{1871,,patch.object()} 和 @ref{18ce,,patch.dict()}。@code{patch} 接受單一字串，格式為 @code{package.module.Class.attribute}，用來指定要 patch 的屬性。同時它也可以接受你想要替換的屬性（或類別或其他）的值。@code{patch.object} 接受一個物件和你想要 patch 的屬性的名稱，同時也可以接受要 patch 的值。

@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

如果你要 patch 一個模組（包括 @ref{13,,builtins}），請使用 @ref{108d,,patch()} 而非 @ref{1871,,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

如有需要，模組名稱可以含有 @code{.}，形式為 @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

如果你想使用一個 mock 進行 patch，你可以使用僅帶有一個引數的 @ref{108d,,patch()}（或帶有兩個引數的 @ref{1871,,patch.object()}）。Mock 將被建立並被傳遞到測試函式 / 方法中：

@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

你可以使用這個模式堆疊多個 patch 裝飾器：

@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

當你巢狀使用 patch 裝飾器時，mock 傳遞到被裝飾函式的順序會跟其被應用的順序相同（一般 `Python' 應用裝飾器的順序）。這意味著由下而上，因此在上面的範例中，@code{module.ClassName2} 的 mock 會先被傳入。

也有 @ref{18ce,,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{108d,,patch()} 為你建立一個 mock 時，你可以使用 with 陳述式的 "as" 形式來取得 mock 的參照：

@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 更多範例,,Patch 裝飾器,unittest mock --- 入門指南
@anchor{library/unittest mock-examples further-examples}@anchor{4541}@anchor{library/unittest mock-examples id1}@anchor{4542}
@subsubsection 更多範例


以下是一些更進階一點的情境的範例。

@menu
* Mock 鍊接呼叫:: 
* 部分 mocking:: 
* Mock 產生器方法:: 
* 對每個測試方法應用相同的 patch:: 
* Mock Unbound Methods （未繫結方法）:: 
* 使用 mock 檢查多個呼叫:: 
* 應對可變引數:: 
* 巢狀使用 Patch:: 
* 使用 MagicMock 來 mock 字典:: 
* Mock 子類別及其屬性:: 
* 使用 patch.dict 來 mock import: 使用 patch dict 來 mock import. 
* 追蹤呼叫順序與更簡潔的呼叫斷言:: 
* 更複雜的引數匹配:: 

@end menu

@node Mock 鍊接呼叫,部分 mocking,,更多範例
@anchor{library/unittest mock-examples mocking-chained-calls}@anchor{4543}
@subsubsection Mock 鍊接呼叫


一旦你了解了 @ref{44ec,,return_value} 屬性，mock 鍊接呼叫其實就很簡單了。當一個 mock 第一次被呼叫，或者你在它被呼叫之前取得其 @code{return_value} 時，一個新的 @ref{c36,,Mock} 就會被建立。

這代表你可以透過查問 @code{return_value} mock 來了解一個對被 mock 的物件的呼叫回傳的物件是如何被使用的：

@example
>>> mock = Mock()
>>> mock().foo(a=2, b=3)
<Mock name='mock().foo()' id='...'>
>>> mock.return_value.foo.assert_called_with(a=2, b=3)
@end example

這裡只需一個簡單的步驟即可進行配置並對鍊接呼叫進行斷言。當然，另一種選擇是先以更容易被測試的方式撰寫程式碼...

所以，假設我們有一些程式碼，看起來大概像這樣：

@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} 是否以正確的方式使用 @code{response} 物件。

由於此呼叫鍊是從實例屬性進行的，因此我們可以在 @code{Something} 實例上 monkey patch @code{backend} 屬性。在這種特定的情況下，我們只對最終呼叫 @code{start_call} 的回傳值感興趣，因此我們不需要做太多配置。我們假設它傳回的物件是類檔案物件 (file-like)，因此我們會確保我們的 response 物件使用內建的 @ref{315,,open()} 作為其 @code{spec}。

為此，我們建立一個 mock 實例作為我們的 mock backend，並為其建立一個 mock response 物件。要將 response 設定為最後的 @code{start_call} 的回傳值，我們可以這樣做：

@example
mock_backend.get_endpoint.return_value.create_call.return_value.start_call.return_value = mock_response
@end example

我們可以使用 @ref{44ed,,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

有了這些，我們就可以原地 (in place) monkey patch "mock backend"，並且可以進行真正的呼叫：

@example
>>> something.backend = mock_backend
>>> something.method()
@end example

藉由使用 @ref{44f0,,mock_calls}，我們可以使用單一一個斷言來檢查鍊接呼叫。一個鍊接呼叫是一行程式碼中的多個呼叫，因此 @code{mock_calls} 中會有多個項目。我們可以使用 @ref{4527,,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,Mock 產生器方法,Mock 鍊接呼叫,更多範例
@anchor{library/unittest mock-examples partial-mocking}@anchor{4544}
@subsubsection 部分 mocking


在某些測試中，我們會想 mock 對 @ref{16be,,datetime.date.today()} 的呼叫以回傳一個已知日期，但我不想阻止測試中的程式碼建立新的日期物件。不幸的是 @ref{1fa,,datetime.date} 是用 C 語言寫的，所以們我不能 monkey patch 靜態的 @ref{16be,,datetime.date.today()} 方法。

我們找到了一種簡單的方法來做到這一點，其用 mock 有效地包裝日期類別，但將對建構函式的呼叫傳遞給真實的類別（並返回真實的實例）。

這裡使用 @ref{108d,,patch 裝飾器} 來 mock 被測模組中的 @code{date} 類別。然後，mock 日期類別上的 @ref{44e4,,side_effect} 屬性會被設定為回傳真實日期的 lambda 函式。當 mock 日期類別被呼叫時，將透過 @code{side_effect} 建構並回傳真實日期。：

@example
>>> from datetime import date
>>> with patch('mymodule.date') as mock_date:
...     mock_date.today.return_value = date(2010, 10, 8)
...     mock_date.side_effect = lambda *args, **kw: date(*args, **kw)
...
...     assert mymodule.date.today() == date(2010, 10, 8)
...     assert mymodule.date(2009, 6, 8) == date(2009, 6, 8)
@end example

注意，我們沒有全域 patch @ref{1fa,,datetime.date}，而是在`使用'它的模組中 patch @code{date}。請參閱 @ref{44e5,,該 patch 何處}。

當 @code{date.today()} 被呼叫時，一個已知日期會被回傳，但對 @code{date(...)} 建構函式的呼叫仍然會回傳正常日期。如果不這樣使用，你可能會發現自己必須使用與被測程式碼完全相同的演算法來計算預期結果，這是一個典型的測試的反面模式 (anti-pattern)。

對日期建構函式的呼叫被記錄在 @code{mock_date} 屬性（@code{call_count} 及其相關屬性）中，這對你的測試也可能有用處。

處理 mock 日期或其他內建類別的另一種方法在 這個 blog@footnote{https://williambert.online/2011/07/how-to-unit-testing-in-django-with-mocking-and-patching/} 中討論。

@node Mock 產生器方法,對每個測試方法應用相同的 patch,部分 mocking,更多範例
@anchor{library/unittest mock-examples mocking-a-generator-method}@anchor{4545}
@subsubsection Mock 產生器方法


Python 產生器是一個函式或方法，它使用 @ref{bb9,,yield} 陳述式在疊代 @footnote{
還有關於產生器運算式及產生器的更多 @uref{http://www.dabeaz.com/coroutines/index.html,進階用法} ，但我們在這裡不考慮它們。一個關於產生器及其強大功能的優良說明是：@uref{http://www.dabeaz.com/generators/,Generator Tricks for Systems Programmers}。
} 時回傳一系列的值。

產生器方法 / 函式會被呼叫以回傳產生器物件。之後此產生器會進行疊代。疊代的協定方法是 @ref{1f71,,__iter__()}，所以我們可以使用 @ref{108a,,MagicMock} 來 mock 它。

下面是一個範例類別，其包含實作產生器的一個 "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

我們該如何 mock 這個類別，特別是它的 "iter" 方法呢？

要配置從疊代回傳的值（隱含在對 @ref{24d,,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 對每個測試方法應用相同的 patch,Mock Unbound Methods （未繫結方法）,Mock 產生器方法,更多範例
@anchor{library/unittest mock-examples applying-the-same-patch-to-every-test-method}@anchor{4546}
@subsubsection 對每個測試方法應用相同的 patch


如果你希望 patch 能用在多個測試方法上，顯而易見的方式是將 patch 裝飾器應用於每個方法。這感覺是不必要的重複行為，因此你可以使用 @ref{108d,,patch()}（及其他 patch 的變體）作為類別裝飾器。這會將 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

管理 patch 的另一種方式是使用 @ref{4518,,patch 方法：啟動與停止}。這允許你將 patch 移到你的 @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} 來 "取消" patch。這可能會比你想像的還要複雜一點，因為如果有例外在 @code{setUp} 中被引發，則 @code{tearDown} 就不會被呼叫。@ref{c6b,,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 Mock Unbound Methods （未繫結方法）,使用 mock 檢查多個呼叫,對每個測試方法應用相同的 patch,更多範例
@anchor{library/unittest mock-examples mocking-unbound-methods}@anchor{4547}
@subsubsection Mock Unbound Methods （未繫結方法）


在撰寫測試時，當我們需要 patch 一個`未繫結方法'（patch 類別上的方法而不是實例上的方法）。我們需要將 self 作為第一個引數傳入，因為我們想斷言哪些物件正在呼叫這個特定方法。問題是你無法為此使用 mock 進行 patch，因為就算你用一個 mock 替換未繫結方法，從實例取得它時它也不會成為一個繫結方法，因此 self 並不會被傳遞。解決方法是使用真實的函式來 patch 未繫結方法。@ref{108d,,patch()} 裝飾器使得用 mock 來 patch out 方法是如此的簡單，以至於建立一個真正的函式相對變得很麻煩。

如果你將 @code{autospec=True} 傳遞給 patch，那麼它會使用`真的'函式物件來進行 patch。此函式物件與它所替換的函式物件具有相同的簽名，但實際上委託給 mock。你仍然會以與之前完全相同的方式自動建立 mock。但這意味著，如果你使用它來 patch 類別上的未繫結方法，則從實例取得的 mock 函式將轉換為繫結方法。@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 實例 patch out，並且不被使用 @code{self} 進行呼叫。

@node 使用 mock 檢查多個呼叫,應對可變引數,Mock Unbound Methods （未繫結方法）,更多範例
@anchor{library/unittest mock-examples checking-multiple-calls-with-mock}@anchor{4548}
@subsubsection 使用 mock 檢查多個呼叫


mock 有很好的 API，用於對 mock 物件的使用方式做出斷言。

@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

如果你的 mock 只被呼叫一次，你可以使用 @ref{44ee,,assert_called_once_with()} 方法，其也斷言 @ref{44f7,,call_count} 是1。

@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} 都對`最近一次'的呼叫做出斷言。如果你的 mock 將被多次呼叫，並且你想要對`所有'這些呼叫進行斷言，你可以使用 @ref{44f8,,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{1c7c,,call} 輔助函式可以輕鬆地對這些呼叫做出斷言。你可以建立預期呼叫的清單並將其與 @code{call_args_list} 進行比較。這看起來與 @code{call_args_list} 的 repr 非常相似：

@example
>>> expected = [call(1, 2, 3), call(4, 5, 6), call()]
>>> mock.call_args_list == expected
True
@end example

@node 應對可變引數,巢狀使用 Patch,使用 mock 檢查多個呼叫,更多範例
@anchor{library/unittest mock-examples coping-with-mutable-arguments}@anchor{4549}
@subsubsection 應對可變引數


另一種情況很少見，但可能會困擾你，那就是當你的 mock 被使用可變引數呼叫。@code{call_args} 和 @code{call_args_list} 儲存對引數的`參照'。如果引數被測試中的程式碼改變，那麼你將無法再對 mock 被呼叫時的值進行斷言。

這是一些秀出問題的程式碼範例。 想像 '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

一種可能是讓 mock 複製你傳入的引數。如果你進行的斷言依賴於物件識別性來確定相等性，這就可能導致問題。

以下是一種使用 @ref{44e4,,side_effect} 功能的解法。如果你為 mock 提供一個 @code{side_effect} 函式，則 @code{side_effect} 將被使用與 mock 相同的引數呼叫。這使我們有機會複製引數並將其儲存以供之後的斷言。在這個範例中，我們使用`另一個' mock 來儲存引數，以便我們可以使用 mock 方法來執行斷言。同樣的，有一個輔助函式為我們設定了這些。：

@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} 與將要被呼叫的 mock 一起被呼叫。它回傳一個我們會對其進行斷言的新的 mock。@code{side_effect} 函式建立引數們的副本，並用該副本呼叫我們的 @code{new_mock}。

@cartouche
@quotation 備註 
如果你的 mock 只會被使用一次，則有一種更簡單的方法可以在呼叫引數時檢查它們。你可以簡單地在 @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{c36,,Mock} 或 @ref{108a,,MagicMock} 的子類別來複製（使用 @ref{d5d,,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} 的所有子代 (child) 也會具有 @code{CopyingMock} 型別。

@node 巢狀使用 Patch,使用 MagicMock 來 mock 字典,應對可變引數,更多範例
@anchor{library/unittest mock-examples nesting-patches}@anchor{454a}
@subsubsection 巢狀使用 Patch


將 patch 作為情境管理器使用很好，但是如果你使用複數個 patch，你最終可能會得到巢狀的 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 的 @code{cleanup} 函式以及 @ref{4518,,patch 方法：啟動與停止} 來達到相同的效果，而不會出現因巢狀導致的縮排。一個簡單的輔助方法 @code{create_patch} 會將 patch 放置到位並為我們回傳被建立的 mock：

@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 字典,Mock 子類別及其屬性,巢狀使用 Patch,更多範例
@anchor{library/unittest mock-examples mocking-a-dictionary-with-magicmock}@anchor{454b}
@subsubsection 使用 MagicMock 來 mock 字典


你可能會想要 mock 字典或其他容器物件，記錄對它的所有存取，同時讓它仍然像字典一樣運作。

我們可以使用 @ref{108a,,MagicMock} 來做到這一點，它的行為會與字典一致，並使用 @ref{44e4,,side_effect} 將字典存取委託給我們控制下的真實底層字典。

當 @code{MagicMock} 的 @ref{582,,__getitem__()} 和 @ref{14cc,,__setitem__()} 方法被呼叫時（一般的字典存取）， @code{side_effect} 會被使用鍵 (key) 來呼叫 （在 @code{__setitem__} 的情況也會使用值 (value)）。我們也可以控制回傳的內容。

使用 @code{MagicMock} 後，我們可以使用諸如 @ref{44f8,,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} 會像一般的字典一樣運作，但會記錄存取。如果你嘗試存取不存在的鍵，它甚至會引發一個 @ref{5df,,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

在上述方式被使用後，你就可以使用普通的 mock 方法和屬性對存取進行斷言：

@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 來 mock import,使用 MagicMock 來 mock 字典,更多範例
@anchor{library/unittest mock-examples mock-subclasses-and-their-attributes}@anchor{454c}
@subsubsection Mock 子類別及其屬性


你會想子類別化 @ref{c36,,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} 實例的標準行為是屬性 mock 和回傳值 mock 會與存取它們的 mock 具有相同的型別。這確保了 @code{Mock} 屬性是 @code{Mocks}，@code{MagicMock} 屬性是 @code{MagicMocks} @footnote{
此規則的例外是非可呼叫物件的 mock。屬性使用可呼叫物件的變體，否則非可呼叫物件的 mock 無法具有可呼叫的方法。
}。因此，如果你要子類別化以新增輔助方法，那麼它們也可用於子類別實例的屬性 mock 和回傳值 mock。

@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}正在子類別化 mock 以建立 Twisted adaptor@footnote{https://twisted.org/documents/11.0.0/api/twisted.python.components.html}。將其應用於屬性實際上會導致錯誤。

@code{Mock} （及其各種形式）使用名為 @code{_get_child_mock} 的方法來為屬性和回傳值建立這些 "子 mock"。你可以透過置換此方法來防止你的子類別被用為屬性。其簽名是取用任意的關鍵字引數（@code{**kwargs}），然後將其傳遞給 mock 建構函式：

@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 import,追蹤呼叫順序與更簡潔的呼叫斷言,Mock 子類別及其屬性,更多範例
@anchor{library/unittest mock-examples mocking-imports-with-patch-dict}@anchor{454d}
@subsubsection 使用 patch.dict 來 mock import


可能會讓 mock 很困難的一種情況是在函式內部進行區域 import。這些狀況會更難進行 mock，因為它們沒有使用我們可以 patch out 的模組命名空間中的物件。

一般來說，我們應該避免區域 import 的發生。有時這樣做是為了防止循環相依 (circular dependencies)，為此`通常'有更好的方式來解決問題（例如重構程式碼）或透過延遲 import 來防止「前期成本 (up front costs)」。這也可以透過比無條件的區域 import 更好的方式來解決（例如將模組儲存為類別或模組屬性，並且僅在第一次使用時進行 import）。

除此之外，還有一種方法可以使用 @code{mock} 來影響 import 的結果。Import 會從 @ref{17c0,,sys.modules} 字典中取得一個`物件'。請注意，它會取得一個`物件'，而該物件不需要是一個模組。初次 import 模組會導致模組物件被放入 @code{sys.modules} 中，因此通常當你 import 某些東西時，你會得到一個模組。但並非一定要如此。

這代表你可以使用 @ref{18ce,,patch.dict()} 來`暫時'在 @ref{17c0,,sys.modules} 中原地放置 mock。在這個 patch 作用時的任何 import 都會取得這個 mock。當 patch 完成時（被裝飾的函式結束、with 陳述式主體完成或 @code{patcher.stop()} 被呼叫），那麼之前在 @code{sys.modules} 中的任何內容都會被安全地復原。

下面是一個 mock out '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} 成功了，但在離開之後，@ref{17c0,,sys.modules} 中就沒有 'fooble' 了。

這也適用於 @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

透過稍微多一點的處理，你也可以 mock 套件的引入：

@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 來 mock import,更多範例
@anchor{library/unittest mock-examples tracking-order-of-calls-and-less-verbose-call-assertions}@anchor{454e}
@subsubsection 追蹤呼叫順序與更簡潔的呼叫斷言


@ref{c36,,Mock} 類別可以讓你透過 @ref{44f2,,method_calls} 屬性追蹤 mock 物件上方法呼叫的`順序'。這不會讓你可以追蹤不同的 mock 物件之間的呼叫順序，然而我們可以使用 @ref{44f0,,mock_calls} 來達到相同的效果。

因為 mock 會在 @code{mock_calls} 中追蹤對子 mock 的呼叫，且存取 mock 的任意屬性會建立一個子 mock，所以我們可以從父 mock 建立不同的 mock。之後對這些子 mock 的呼叫將依序全部記錄在父 mock 的 @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

之後我們可以透過與管理器 (manager) mock 上的 @code{mock_calls} 屬性進行比較來斷言呼叫及其順序：

@example
>>> expected_calls = [call.foo.something(), call.bar.other.thing()]
>>> manager.mock_calls == expected_calls
True
@end example

如果 @code{patch} 正在被建立並放置為你的 mock，那麼你可以使用 @ref{18bc,,attach_mock()} 方法將它們附加到管理器 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{1972,,assert_has_calls()} 方法。這需要一個呼叫串列（使用 @ref{1c7c,,call} 物件建構）。如果該呼叫序列位於 @ref{44f0,,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()} 並不是對 mock 進行的唯一呼叫，斷言仍會成功。

有時可能會對一個 mock 進行多次呼叫，而你只對斷言其中`某些'呼叫感興趣。你甚至可能不關心順序。在這種情況下，你可以將 @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 更複雜的引數匹配,,追蹤呼叫順序與更簡潔的呼叫斷言,更多範例
@anchor{library/unittest mock-examples more-complex-argument-matching}@anchor{454f}
@subsubsection 更複雜的引數匹配


使用與 @ref{1c7a,,ANY} 相同的基本概念，我們可以實作匹配器 (matcher)，對用來作為 mock 引數的物件進行更複雜的斷言。

假設我們預期某個物件會被傳進 mock，預設情況下，該 mock 會根據物件識別性進行相等比較（對使用者定義類別的 Python 預設行為）。要使用 @ref{1ccb,,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{Foo} 物件和比較函式實例化的。在 @code{assert_called_with} 中，@code{Matcher} 相等方法將被呼叫，它將呼叫 mock 時傳入的物件與我們建立匹配器時傳入的物件進行比較。如果它們匹配，則 @code{assert_called_with} 會通過，如果它們不匹配，則會引發 @ref{8b0,,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

透過一些調整，你可以讓比較函式直接引發 @ref{8b0,,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 --- Python 的回歸測試 regression tests 套件,test support --- Python 測試套件的工具,unittest mock --- 入門指南,開發工具
@anchor{library/test doc}@anchor{4550}@anchor{library/test module-test}@anchor{e8}@anchor{library/test test-regression-tests-package-for-python}@anchor{4551}@anchor{library/test translation-repo}@anchor{4552}
@subsection @code{test} --- Python 的回歸測試 (regression tests) 套件


@geindex module; test

@cartouche
@quotation 備註 
The @ref{e8,,test} package is meant for internal use by Python only. It is
documented for the benefit of the core developers of Python. Any use of
this package outside of Python's standard library is discouraged as code
mentioned here can change or be removed without notice between releases of
Python.
@end quotation
@end cartouche


__________________________________________________________________


The @ref{e8,,test} package contains all regression tests for Python as well as the
modules @ref{ea,,test.support} and @ref{e9,,test.regrtest}.
@ref{ea,,test.support} is used to enhance your tests while
@ref{e9,,test.regrtest} drives the testing suite.

Each module in the @ref{e8,,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{10c,,unittest} or @ref{3e,,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 @ref{10c,,unittest} 模組

撰寫 PyUnit 回歸測試。

@item @ref{3e,,doctest} 模組

鑲嵌在文件字串中的測試。
@end table


@menu
* 撰寫 test 套件的單元測試:: 
* 使用命令列介面執行測試:: 

@end menu

@node 撰寫 test 套件的單元測試,使用命令列介面執行測試,,test --- Python 的回歸測試 regression tests 套件
@anchor{library/test writing-tests}@anchor{4553}@anchor{library/test writing-unit-tests-for-the-test-package}@anchor{4554}
@subsubsection 撰寫 @code{test} 套件的單元測試


It is preferred that tests that use the @ref{10c,,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{e9,,test.regrtest},
on its own as a script that supports the @ref{10c,,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{2b3,,unittest.TestCase} are run as tests.  The @code{TestFuncAcceptsSequencesMixin} class in the example above
does not have any data and so can't be run by itself, thus it does not
inherit from @ref{2b3,,unittest.TestCase}.
@end itemize


@subsubheading 也參考



@table @asis

@item 測試驅動開發

由 Kent Beck 所著，關於先寫測試再寫程式的書籍。
@end table


@node 使用命令列介面執行測試,,撰寫 test 套件的單元測試,test --- Python 的回歸測試 regression tests 套件
@anchor{library/test module-test regrtest}@anchor{e9}@anchor{library/test regrtest}@anchor{1204}@anchor{library/test running-tests-using-the-command-line-interface}@anchor{4555}
@subsubsection 使用命令列介面執行測試


@geindex module; test.regrtest

The @ref{e8,,test} package can be run as a script to drive Python's regression
test suite, thanks to the @ref{23c,,-m} option: @code{python -m test}. Under
the hood, it uses @ref{e9,,test.regrtest}; the call @code{python -m
test.regrtest} used in previous Python versions still works.  Running the
script by itself automatically starts running all regression tests in the
@ref{e8,,test} package. It does this by finding all modules in the package whose
name starts with @code{test_}, importing them, and executing the function
@code{test_main()} if present or loading the tests via
unittest.TestLoader.loadTestsFromModule if @code{test_main} does not exist.  The
names of tests to execute may also be passed to the script. Specifying a single
regression test (@code{python -m test test_spam}) will minimize output and
only print whether the test passed or failed.

Running @ref{e8,,test} directly allows what resources are available for
tests to use to be set. You do this by using the @code{-u} command-line
option. Specifying @code{all} as the value for the @code{-u} option enables all
possible resources: @code{python -m test -uall}.
If all but one resource is desired (a more common case), a
comma-separated list of resources that are not desired may be listed after
@code{all}. The command @code{python -m test -uall,-audio,-largefile}
will run @ref{e8,,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.


在 3.14 版被加入: Output is colorized by default and can be
@ref{1b7,,controlled using environment variables}.


@node test support --- Python 測試套件的工具,test support socket_helper --- 用於 socket 測試的工具,test --- Python 的回歸測試 regression tests 套件,開發工具
@anchor{library/test module-test support}@anchor{ea}@anchor{library/test test-support-utilities-for-the-python-test-suite}@anchor{4556}
@subsection @code{test.support} --- Python 測試套件的工具


@geindex module; test.support

@ref{ea,,test.support} 模組提供 Python 回歸測試套件的支援。

@cartouche
@quotation 備註 
@ref{ea,,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

此模組定義了以下例外：

@geindex TestFailed
@anchor{library/test test support TestFailed}@anchor{4557}
@deffn {例外} test.support.TestFailed

Exception to be raised when a test fails. This is deprecated in favor of
@ref{10c,,unittest}-based tests and @ref{2b3,,unittest.TestCase}'s assertion
methods.
@end deffn

@geindex ResourceDenied
@anchor{library/test test support ResourceDenied}@anchor{4558}
@deffn {例外} test.support.ResourceDenied

Subclass of @ref{11df,,unittest.SkipTest}. Raised when a resource (such as a
network connection) is not available. Raised by the @ref{4559,,requires()}
function.
@end deffn

@ref{ea,,test.support} 模組定義了以下常數：

@geindex verbose (於 test.support 模組中)
@anchor{library/test test support verbose}@anchor{455a}
@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{e9,,test.regrtest}.
@end deffn

@geindex is_jython (於 test.support 模組中)
@anchor{library/test test support is_jython}@anchor{455b}
@deffn {資料} test.support.is_jython

如果執行的直譯器是 Jython，則為 @code{True}。
@end deffn

@geindex is_android (於 test.support 模組中)
@anchor{library/test test support is_android}@anchor{455c}
@deffn {資料} test.support.is_android

如果 @code{sys.platform} 是 @code{android} 則為 @code{True}。
@end deffn

@geindex is_emscripten (於 test.support 模組中)
@anchor{library/test test support is_emscripten}@anchor{455d}
@deffn {資料} test.support.is_emscripten

如果 @code{sys.platform} 是 @code{emscripten} 則為 @code{True}。
@end deffn

@geindex is_wasi (於 test.support 模組中)
@anchor{library/test test support is_wasi}@anchor{455e}
@deffn {資料} test.support.is_wasi

如果 @code{sys.platform} 是 @code{wasi} 則為 @code{True}。
@end deffn

@geindex is_apple_mobile (於 test.support 模組中)
@anchor{library/test test support is_apple_mobile}@anchor{455f}
@deffn {資料} test.support.is_apple_mobile

如果 @code{sys.platform} 是 @code{ios}、@code{tvos} 或 @code{watchos} 則為 @code{True}。
@end deffn

@geindex is_apple (於 test.support 模組中)
@anchor{library/test test support is_apple}@anchor{4560}
@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{4561}
@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{1c65}
@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{f9e,,connect()},
@ref{f9f,,recv()} and @ref{fa2,,send()} methods of
@ref{f9c,,socket.socket}.

預設值為 5 秒。

另請參閱 @ref{1c66,,INTERNET_TIMEOUT}。
@end deffn

@geindex INTERNET_TIMEOUT (於 test.support 模組中)
@anchor{library/test test support INTERNET_TIMEOUT}@anchor{1c66}
@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 @ref{1c66,,INTERNET_TIMEOUT} should not mark a test as
failed, but skip the test instead: see
@ref{4562,,transient_internet()}.

預設值為 1 分鐘。

另請參閱 @ref{1c65,,LOOPBACK_TIMEOUT}。
@end deffn

@geindex SHORT_TIMEOUT (於 test.support 模組中)
@anchor{library/test test support SHORT_TIMEOUT}@anchor{1b65}
@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 @ref{1b65,,SHORT_TIMEOUT} starts to fail randomly on slow
buildbots, use @ref{1c67,,LONG_TIMEOUT} instead.

預設值為 30 秒。
@end deffn

@geindex LONG_TIMEOUT (於 test.support 模組中)
@anchor{library/test test support LONG_TIMEOUT}@anchor{1c67}
@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.

預設值為 5 分鐘。

請參閱 @ref{1c65,,LOOPBACK_TIMEOUT}、@ref{1c66,,INTERNET_TIMEOUT} 和 @ref{1b65,,SHORT_TIMEOUT}。
@end deffn

@geindex PGO (於 test.support 模組中)
@anchor{library/test test support PGO}@anchor{4563}
@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{4564}
@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{4565}
@deffn {資料} test.support.Py_DEBUG

@code{True} if Python was built with the @ref{17b1,,Py_DEBUG} macro
defined, that is, if
Python was @ref{504,,built in debug mode}.


在 3.12 版被加入.

@end deffn

@geindex SOCK_MAX_SIZE (於 test.support 模組中)
@anchor{library/test test support SOCK_MAX_SIZE}@anchor{4566}
@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{4567}
@deffn {資料} test.support.TEST_SUPPORT_DIR

設定為包含 @ref{ea,,test.support} 的頂層目錄。
@end deffn

@geindex TEST_HOME_DIR (於 test.support 模組中)
@anchor{library/test test support TEST_HOME_DIR}@anchor{4568}
@deffn {資料} test.support.TEST_HOME_DIR

設定為測試套件的頂層目錄。
@end deffn

@geindex TEST_DATA_DIR (於 test.support 模組中)
@anchor{library/test test support TEST_DATA_DIR}@anchor{4569}
@deffn {資料} test.support.TEST_DATA_DIR

設定為測試套件中的 @code{data} 目錄。
@end deffn

@geindex MAX_Py_ssize_t (於 test.support 模組中)
@anchor{library/test test support MAX_Py_ssize_t}@anchor{456a}
@deffn {資料} test.support.MAX_Py_ssize_t

設定為 @ref{13c6,,sys.maxsize} 以進行大記憶體測試。
@end deffn

@geindex max_memuse (於 test.support 模組中)
@anchor{library/test test support max_memuse}@anchor{456b}
@deffn {資料} test.support.max_memuse

Set by @ref{456c,,set_memlimit()} as the memory limit for big memory tests.
Limited by @ref{456a,,MAX_Py_ssize_t}.
@end deffn

@geindex real_max_memuse (於 test.support 模組中)
@anchor{library/test test support real_max_memuse}@anchor{456d}
@deffn {資料} test.support.real_max_memuse

Set by @ref{456c,,set_memlimit()} as the memory limit for big memory tests.  Not
limited by @ref{456a,,MAX_Py_ssize_t}.
@end deffn

@geindex MISSING_C_DOCSTRINGS (於 test.support 模組中)
@anchor{library/test test support MISSING_C_DOCSTRINGS}@anchor{456e}
@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{2065,,configure --without-doc-strings} option.

另請參閱 @ref{456f,,HAVE_DOCSTRINGS} 變數。
@end deffn

@geindex HAVE_DOCSTRINGS (於 test.support 模組中)
@anchor{library/test test support HAVE_DOCSTRINGS}@anchor{456f}
@deffn {資料} test.support.HAVE_DOCSTRINGS

Set to @code{True} if function docstrings are available.
See the @ref{18c,,python -OO} option, which strips docstrings of functions implemented in Python.

請參閱 @ref{456e,,MISSING_C_DOCSTRINGS} 變數。
@end deffn

@geindex TEST_HTTP_URL (於 test.support 模組中)
@anchor{library/test test support TEST_HTTP_URL}@anchor{4570}
@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{4571}
@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{4572}
@deffn {資料} test.support.NEVER_EQ

Object that is not equal to anything (even to @ref{4571,,ALWAYS_EQ}).
Used to test mixed type comparison.
@end deffn

@geindex LARGEST (於 test.support 模組中)
@anchor{library/test test support LARGEST}@anchor{4573}
@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{4574}
@deffn {資料} test.support.SMALLEST

Object that is less than anything (except itself).
Used to test mixed type comparison.
@end deffn

@ref{ea,,test.support} 模組定義了以下函式：

@geindex busy_retry() (於 test.support 模組中)
@anchor{library/test test support busy_retry}@anchor{4575}
@deffn {函式} test.support.busy_retry (timeout, err_msg=None, /, *, error=True)

執行迴圈主體直到 @code{break} 停止迴圈。

After `timeout' seconds, raise an @ref{8b0,,AssertionError} if `error' is true,
or just stop the loop if `error' is false.

範例：

@example
for _ in support.busy_retry(support.SHORT_TIMEOUT):
    if check():
        break
@end example

error=False 用法範例：

@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{4576}
@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).

請見 @ref{4575,,busy_retry()} 文件以瞭解參數用法。

在 SHORT_TIMEOUT 秒後引發例外的範例：

@example
for _ in support.sleeping_retry(support.SHORT_TIMEOUT):
    if check():
        break
@end example

error=False 用法範例：

@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{4577}
@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{e9,,test.regrtest} is executing the
tests.
@end deffn

@geindex python_is_optimized() (於 test.support 模組中)
@anchor{library/test test support python_is_optimized}@anchor{4578}
@deffn {函式} test.support.python_is_optimized ()

如果 Python 不是使用 @code{-O0} 或 @code{-Og} 建置則回傳 @code{True}。
@end deffn

@geindex with_pymalloc() (於 test.support 模組中)
@anchor{library/test test support with_pymalloc}@anchor{4579}
@deffn {函式} test.support.with_pymalloc ()

回傳 @code{_testcapi.WITH_PYMALLOC}。
@end deffn

@geindex requires() (於 test.support 模組中)
@anchor{library/test test support requires}@anchor{4559}
@deffn {函式} test.support.requires (resource, msg=None)

Raise @ref{4558,,ResourceDenied} if `resource' is not available. `msg' is the
argument to @ref{4558,,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{e9,,test.regrtest}.
@end deffn

@geindex sortdict() (於 test.support 模組中)
@anchor{library/test test support sortdict}@anchor{457a}
@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{457b}
@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{457c}
@deffn {函式} test.support.get_pagesize ()

Get size of a page in bytes.


在 3.12 版被加入.

@end deffn

@geindex setswitchinterval() (於 test.support 模組中)
@anchor{library/test test support setswitchinterval}@anchor{457d}
@deffn {函式} test.support.setswitchinterval (interval)

Set the @ref{b3b,,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{457e}
@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{456c}
@deffn {函式} test.support.set_memlimit (limit)

Set the values for @ref{456b,,max_memuse} and @ref{456d,,real_max_memuse} for big
memory tests.
@end deffn

@geindex record_original_stdout() (於 test.support 模組中)
@anchor{library/test test support record_original_stdout}@anchor{457f}
@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{4580}
@deffn {函式} test.support.get_original_stdout ()

Return the original stdout set by @ref{457f,,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{4581}
@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{4582}
@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{4583}
@deffn {函式} test.support.captured_stdin ()
@anchor{library/test test support captured_stdout}@anchor{4584}
@deffnx {函式} test.support.captured_stdout ()
@anchor{library/test test support captured_stderr}@anchor{1ca1}
@deffnx {函式} test.support.captured_stderr ()

A context managers that temporarily replaces the named stream with
@ref{1124,,io.StringIO} object.

使用輸出串流的範例：

@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
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{4585}
@deffn {函式} test.support.disable_faulthandler ()

A context manager that temporary disables @ref{5c,,faulthandler}.
@end deffn

@geindex gc_collect() (於 test.support 模組中)
@anchor{library/test test support gc_collect}@anchor{4586}
@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{4587}
@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{4588}
@deffn {函式} test.support.swap_attr (obj, attr, new_val)

Context manager to swap out an attribute with a new object.

用法：

@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{4589}
@deffn {函式} test.support.swap_item (obj, attr, new_val)

Context manager to swap out an item with a new object.

用法：

@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{458a}
@deffn {函式} test.support.flush_std_streams ()

Call the @code{flush()} method on @ref{cc4,,sys.stdout} and then on
@ref{b2a,,sys.stderr}. It can be used to make sure that the logs order is
consistent before writing into stderr.


在 3.11 版被加入.

@end deffn

@geindex print_warning() (於 test.support 模組中)
@anchor{library/test test support print_warning}@anchor{458b}
@deffn {函式} test.support.print_warning (msg)

Print a warning into @ref{458c,,sys.__stderr__}. Format the message as:
@code{f"Warning -- @{msg@}"}. If `msg' is made of multiple lines, add
@code{"Warning -- "} prefix to each line.


在 3.9 版被加入.

@end deffn

@geindex wait_process() (於 test.support 模組中)
@anchor{library/test test support wait_process}@anchor{1c26}
@deffn {函式} test.support.wait_process (pid, *, exitcode, timeout=None)

Wait until process `pid' completes and check that the process exit code is
`exitcode'.

如果行程退出代號不等於 `exitcode' 則引發 @ref{8b0,,AssertionError}。

If the process runs longer than `timeout' seconds (@ref{1b65,,SHORT_TIMEOUT} by
default), kill the process and raise an @ref{8b0,,AssertionError}. The timeout
feature is not available on Windows.


在 3.9 版被加入.

@end deffn

@geindex calcobjsize() (於 test.support 模組中)
@anchor{library/test test support calcobjsize}@anchor{458d}
@deffn {函式} test.support.calcobjsize (fmt)

Return the size of the @ref{5d7,,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{458e}
@deffn {函式} test.support.calcvobjsize (fmt)

Return the size of the @ref{458f,,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{4590}
@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{4591}
@deffn {函式} @@test.support.anticipate_failure (condition)

A decorator to conditionally mark tests with
@ref{44a2,,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{4592}
@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{4593}
@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{4594}
@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{4595}
@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{4596}
@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{4597}
@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{4598}
@deffn {函式} @@test.support.requires_gil_enabled

Decorator for skipping tests on the free-threaded build.  If the
@ref{164,,GIL} is disabled, the test is skipped.
@end deffn

@geindex requires_IEEE_754() (於 test.support 模組中)
@anchor{library/test test support requires_IEEE_754}@anchor{4599}
@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{459a}
@deffn {函式} @@test.support.requires_zlib

如果 @ref{139,,zlib} 不存在則跳過測試的裝飾器。
@end deffn

@geindex requires_gzip() (於 test.support 模組中)
@anchor{library/test test support requires_gzip}@anchor{459b}
@deffn {函式} @@test.support.requires_gzip

如果 @ref{6b,,gzip} 不存在則跳過測試的裝飾器。
@end deffn

@geindex requires_bz2() (於 test.support 模組中)
@anchor{library/test test support requires_bz2}@anchor{459c}
@deffn {函式} @@test.support.requires_bz2

如果 @ref{14,,bz2} 不存在則跳過測試的裝飾器。
@end deffn

@geindex requires_lzma() (於 test.support 模組中)
@anchor{library/test test support requires_lzma}@anchor{459d}
@deffn {函式} @@test.support.requires_lzma

如果 @ref{8e,,lzma} 不存在則跳過測試的裝飾器。
@end deffn

@geindex requires_resource() (於 test.support 模組中)
@anchor{library/test test support requires_resource}@anchor{459e}
@deffn {函式} @@test.support.requires_resource (resource)

如果 `resource' 不可用則跳過測試的裝飾器。
@end deffn

@geindex requires_docstrings() (於 test.support 模組中)
@anchor{library/test test support requires_docstrings}@anchor{459f}
@deffn {函式} @@test.support.requires_docstrings

Decorator for only running the test if @ref{456f,,HAVE_DOCSTRINGS}.
@end deffn

@geindex requires_limited_api() (於 test.support 模組中)
@anchor{library/test test support requires_limited_api}@anchor{45a0}
@deffn {函式} @@test.support.requires_limited_api

Decorator for only running the test if @ref{62f,,Limited C API}
is available.
@end deffn

@geindex cpython_only() (於 test.support 模組中)
@anchor{library/test test support cpython_only}@anchor{45a1}
@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{45a2}
@deffn {函式} @@test.support.impl_detail (msg=None, **guards)

Decorator for invoking @ref{457e,,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{45a3}
@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{45a4}
@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{45a5}
@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{45a6}
@deffn {函式} @@test.support.bigmemtest (size, memuse, dry_run=True)

大記憶體測試的裝飾器。

`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{45a7}
@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{45a8}
@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{45a9}
@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{10c,,unittest} instance for the test.  `errtext' is the
regular expression which should match the string representation of the
raised @ref{18e,,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{45aa}
@deffn {函式} test.support.open_urlresource (url, *args, **kw)

Open `url'.  If open fails, raises @ref{4557,,TestFailed}.
@end deffn

@geindex reap_children() (於 test.support 模組中)
@anchor{library/test test support reap_children}@anchor{45ab}
@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{45ac}
@deffn {函式} test.support.get_attribute (obj, name)

Get an attribute, raising @ref{11df,,unittest.SkipTest} if @ref{5e8,,AttributeError}
is raised.
@end deffn

@geindex catch_unraisable_exception() (於 test.support 模組中)
@anchor{library/test test support catch_unraisable_exception}@anchor{1c86}
@deffn {函式} test.support.catch_unraisable_exception ()

Context manager catching unraisable exception using
@ref{502,,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.

用法：

@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


在 3.8 版被加入.

@end deffn

@geindex load_package_tests() (於 test.support 模組中)
@anchor{library/test test support load_package_tests}@anchor{45ad}
@deffn {函式} test.support.load_package_tests (pkg_dir, loader, standard_tests, pattern)

Generic implementation of the @ref{10c,,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{45ae}
@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'.

這預設會跳過以 '_' 開頭的私有屬性，但會包含所有魔術方法，即以 '__' 開頭和結尾的方法。


在 3.5 版被加入.

@end deffn

@geindex patch() (於 test.support 模組中)
@anchor{library/test test support patch}@anchor{45af}
@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{45b0}
@deffn {函式} test.support.run_in_subinterp (code)

Run `code' in subinterpreter.  Raise @ref{11df,,unittest.SkipTest} if
@ref{105,,tracemalloc} is enabled.
@end deffn

@geindex check_free_after_iterating() (於 test.support 模組中)
@anchor{library/test test support check_free_after_iterating}@anchor{45b1}
@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{45b2}
@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{1c01}
@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{2581,,__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
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


在 3.6 版被加入.

@end deffn

@geindex skip_if_broken_multiprocessing_synchronize() (於 test.support 模組中)
@anchor{library/test test support skip_if_broken_multiprocessing_synchronize}@anchor{1c02}
@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{2c0,,OSError}.


在 3.10 版被加入.

@end deffn

@geindex check_disallow_instantiation() (於 test.support 模組中)
@anchor{library/test test support check_disallow_instantiation}@anchor{45b3}
@deffn {函式} test.support.check_disallow_instantiation (test_case, tp, *args, **kwds)

Assert that type `tp' cannot be instantiated using `args' and `kwds'.


在 3.10 版被加入.

@end deffn

@geindex adjust_int_max_str_digits() (於 test.support 模組中)
@anchor{library/test test support adjust_int_max_str_digits}@anchor{45b4}
@deffn {函式} test.support.adjust_int_max_str_digits (max_digits)

This function returns a context manager that will change the global
@ref{185e,,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.


在 3.11 版被加入.

@end deffn

@ref{ea,,test.support} 模組定義了以下類別：

@geindex SuppressCrashReport (test.support 中的類別)
@anchor{library/test test support SuppressCrashReport}@anchor{45b5}
@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{175c,,resource.setrlimit()} is used to set
@ref{45b6,,resource.RLIMIT_CORE}'s soft limit to 0 to prevent coredump file
creation.

在兩個平台上，舊值會被 @ref{1501,,__exit__()} 還原。
@end deffn

@geindex SaveSignals (test.support 中的類別)
@anchor{library/test test support SaveSignals}@anchor{45b7}
@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{45b8}
@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{45b9}
@deffn {方法} restore (self)

Set the signal numbers from the @ref{45b8,,save()} dictionary to the saved
handler.
@end deffn
@end deffn

@geindex Matcher (test.support 中的類別)
@anchor{library/test test support Matcher}@anchor{45ba}
@deffn {類別} test.support.Matcher

@geindex matches() (test.support.Matcher 的方法)
@anchor{library/test test support Matcher matches}@anchor{45bb}
@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{45bc}
@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 --- 用於 socket 測試的工具,test support script_helper --- 用於 Python 執行測試的工具,test support --- Python 測試套件的工具,開發工具
@anchor{library/test module-test support socket_helper}@anchor{ef}@anchor{library/test test-support-socket-helper-utilities-for-socket-tests}@anchor{45bd}
@subsection @code{test.support.socket_helper} --- 用於 socket 測試的工具


@geindex module; test.support.socket_helper

The @ref{ef,,test.support.socket_helper} module provides support for socket tests.


在 3.9 版被加入.


@geindex IPV6_ENABLED (於 test.support.socket_helper 模組中)
@anchor{library/test test support socket_helper IPV6_ENABLED}@anchor{45be}
@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{45bf}
@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{1ad2,,AF_INET},
@ref{14f4,,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{45c0,,bind_port()} should be used for any tests
where a server socket needs to be bound to a particular port for the
duration of the test.
Which one to use depends on whether the calling code is creating a Python
socket, or if an unused port needs to be provided in a constructor
or passed to an external program (i.e. the @code{-accept} argument to
openssl's s_server mode).  Always prefer @ref{45c0,,bind_port()} over
@ref{45bf,,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{45c0}
@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{1ad2,,AF_INET} and @code{sock.type} is
@ref{14f4,,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{45c1}
@deffn {函式} test.support.socket_helper.bind_unix_socket (sock, addr)

Bind a Unix socket, raising @ref{11df,,unittest.SkipTest} if
@ref{f39,,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{45c2}
@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{4562}
@deffn {函式} test.support.socket_helper.transient_internet (resource_name, *, timeout=30.0, errnos=())

A context manager that raises @ref{4558,,ResourceDenied} when
various issues with the internet connection manifest themselves as
exceptions.
@end deffn

@node test support script_helper --- 用於 Python 執行測試的工具,test support bytecode_helper --- 用於測試位元組碼能正確產生的支援工具,test support socket_helper --- 用於 socket 測試的工具,開發工具
@anchor{library/test module-test support script_helper}@anchor{ee}@anchor{library/test test-support-script-helper-utilities-for-the-python-execution-tests}@anchor{45c3}
@subsection @code{test.support.script_helper} --- 用於 Python 執行測試的工具


@geindex module; test.support.script_helper

@ref{ee,,test.support.script_helper} 模組提供 Python 的腳本執行測試的支援。

@geindex interpreter_requires_environment() (於 test.support.script_helper 模組中)
@anchor{library/test test support script_helper interpreter_requires_environment}@anchor{45c4}
@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{3ee,,PYTHONHOME} is one way to get most of the testsuite to run
in that situation.  
@geindex PYTHONPATH
@geindex 環境變數; PYTHONPATH
@ref{1218,,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{45c5}
@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 版的變更: 此函式不再從 `stderr' 中移除空白。

@end deffn

@geindex assert_python_ok() (於 test.support.script_helper 模組中)
@anchor{library/test test support script_helper assert_python_ok}@anchor{45c6}
@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 版的變更: 此函式不再從 `stderr' 中移除空白。

@end deffn

@geindex assert_python_failure() (於 test.support.script_helper 模組中)
@anchor{library/test test support script_helper assert_python_failure}@anchor{45c7}
@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.

更多選項請見 @ref{45c6,,assert_python_ok()}。


在 3.9 版的變更: 此函式不再從 `stderr' 中移除空白。

@end deffn

@geindex spawn_python() (於 test.support.script_helper 模組中)
@anchor{library/test test support script_helper spawn_python}@anchor{45c8}
@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{4b2,,subprocess.Popen()}. Returns a
@ref{4b2,,subprocess.Popen} object.
@end deffn

@geindex kill_python() (於 test.support.script_helper 模組中)
@anchor{library/test test support script_helper kill_python}@anchor{45c9}
@deffn {函式} test.support.script_helper.kill_python (p)

Run the given @ref{4b2,,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{45ca}
@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{45cb}
@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{45cc}
@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{45cd}
@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 --- 用於測試位元組碼能正確產生的支援工具,test support threading_helper --- Utilities for threading tests,test support script_helper --- 用於 Python 執行測試的工具,開發工具
@anchor{library/test module-test support bytecode_helper}@anchor{eb}@anchor{library/test test-support-bytecode-helper-support-tools-for-testing-correct-bytecode-generation}@anchor{45ce}
@subsection @code{test.support.bytecode_helper} --- 用於測試位元組碼能正確產生的支援工具


@geindex module; test.support.bytecode_helper

@ref{eb,,test.support.bytecode_helper} 模組提供測試和檢查位元組碼產生的支援。


在 3.9 版被加入.


此模組定義了以下類別：

@geindex BytecodeTestCase (test.support.bytecode_helper 中的類別)
@anchor{library/test test support bytecode_helper BytecodeTestCase}@anchor{45cf}
@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{45d0}
@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{45d1}
@deffn {方法} BytecodeTestCase.assertInBytecode (x, opname, argval=_UNSPECIFIED)

Return instr if `opname' is found, otherwise throws @ref{8b0,,AssertionError}.
@end deffn

@geindex assertNotInBytecode() (test.support.bytecode_helper.BytecodeTestCase 的方法)
@anchor{library/test test support bytecode_helper BytecodeTestCase assertNotInBytecode}@anchor{45d2}
@deffn {方法} BytecodeTestCase.assertNotInBytecode (x, opname, argval=_UNSPECIFIED)

Throws @ref{8b0,,AssertionError} if `opname' is found.
@end deffn

@node test support threading_helper --- Utilities for threading tests,test support os_helper --- 用於 os 測試的工具,test support bytecode_helper --- 用於測試位元組碼能正確產生的支援工具,開發工具
@anchor{library/test module-test support threading_helper}@anchor{f0}@anchor{library/test test-support-threading-helper-utilities-for-threading-tests}@anchor{45d3}
@subsection @code{test.support.threading_helper} --- Utilities for threading tests


@geindex module; test.support.threading_helper

The @ref{f0,,test.support.threading_helper} module provides support for threading tests.


在 3.10 版被加入.


@geindex join_thread() (於 test.support.threading_helper 模組中)
@anchor{library/test test support threading_helper join_thread}@anchor{45d4}
@deffn {函式} test.support.threading_helper.join_thread (thread, timeout=None)

Join a `thread' within `timeout'.  Raise an @ref{8b0,,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{45d5}
@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{45d6}
@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{34ec,,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{45d7}
@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{45d8}
@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{45d9}
@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{45da}
@deffn {函式} test.support.threading_helper.catch_threading_exception ()

Context manager catching @ref{176,,threading.Thread} exception using
@ref{a44,,threading.excepthook()}.

當捕捉到例外時會設定的屬性：


@itemize *

@item 
@code{exc_type}

@item 
@code{exc_value}

@item 
@code{exc_traceback}

@item 
@code{thread}
@end itemize

參閱 @ref{a44,,threading.excepthook()} 文件。

這些屬性會在離開情境管理器時被刪除。

用法：

@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


在 3.8 版被加入.

@end deffn

@geindex run_concurrently() (於 test.support.threading_helper 模組中)
@anchor{library/test test support threading_helper run_concurrently}@anchor{45db}
@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 --- 用於 os 測試的工具,test support import_helper --- 用於 import 測試的工具,test support threading_helper --- Utilities for threading tests,開發工具
@anchor{library/test module-test support os_helper}@anchor{ed}@anchor{library/test test-support-os-helper-utilities-for-os-tests}@anchor{45dc}
@subsection @code{test.support.os_helper} --- 用於 os 測試的工具


@geindex module; test.support.os_helper

@ref{ed,,test.support.os_helper} 模組提供 os 測試的支援。


在 3.10 版被加入.


@geindex FS_NONASCII (於 test.support.os_helper 模組中)
@anchor{library/test test support os_helper FS_NONASCII}@anchor{45dd}
@deffn {資料} test.support.os_helper.FS_NONASCII

A non-ASCII character encodable by @ref{e4a,,os.fsencode()}.
@end deffn

@geindex SAVEDCWD (於 test.support.os_helper 模組中)
@anchor{library/test test support os_helper SAVEDCWD}@anchor{45de}
@deffn {資料} test.support.os_helper.SAVEDCWD

設定為 @ref{1874,,os.getcwd()}。
@end deffn

@geindex TESTFN (於 test.support.os_helper 模組中)
@anchor{library/test test support os_helper TESTFN}@anchor{45df}
@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{45e0}
@deffn {資料} test.support.os_helper.TESTFN_NONASCII

Set to a filename containing the @ref{45dd,,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{45e1}
@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{45e2}
@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{45e3}
@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{15d9}
@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 版的變更: 新增字典介面。

@end deffn

@geindex FakePath (test.support.os_helper 中的類別)
@anchor{library/test test support os_helper FakePath}@anchor{45e4}
@deffn {類別} test.support.os_helper.FakePath (path)

Simple @ref{59b,,path-like object}.  It implements the
@ref{e47,,__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{45e5}
@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{17ed}
@deffn {方法} EnvironmentVarGuard.unset (envvar, *others)

暫時取消一個或多個環境變數。


在 3.14 版的變更: 可以取消多於一個環境變數。

@end deffn

@geindex can_symlink() (於 test.support.os_helper 模組中)
@anchor{library/test test support os_helper can_symlink}@anchor{45e6}
@deffn {函式} test.support.os_helper.can_symlink ()

如果作業系統支援符號連結則回傳 @code{True}，否則回傳 @code{False}。
@end deffn

@geindex can_xattr() (於 test.support.os_helper 模組中)
@anchor{library/test test support os_helper can_xattr}@anchor{45e7}
@deffn {函式} test.support.os_helper.can_xattr ()

如果作業系統支援 xattr 則回傳 @code{True}，否則回傳 @code{False}。
@end deffn

@geindex change_cwd() (於 test.support.os_helper 模組中)
@anchor{library/test test support os_helper change_cwd}@anchor{45e8}
@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{45e9}
@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{45ea}
@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{45eb}
@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{45ec}
@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{45ed}
@deffn {函式} test.support.os_helper.rmdir (filename)

Call @ref{12f4,,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{45ee}
@deffn {函式} test.support.os_helper.rmtree (path)

Call @ref{354,,shutil.rmtree()} on `path' or call @ref{6c1,,os.lstat()} and
@ref{12f4,,os.rmdir()} to remove a path and its contents.  As with @ref{45ed,,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{45ef}
@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{45f0}
@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{45f1}
@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{528,,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{45f2}
@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{528,,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{45f3}
@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{45f4}
@deffn {函式} test.support.os_helper.unlink (filename)

Call @ref{12f6,,os.unlink()} on `filename'.  As with @ref{45ed,,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 --- 用於 import 測試的工具,test support warnings_helper --- 用於 warnings 測試的工具,test support os_helper --- 用於 os 測試的工具,開發工具
@anchor{library/test module-test support import_helper}@anchor{ec}@anchor{library/test test-support-import-helper-utilities-for-import-tests}@anchor{45f5}
@subsection @code{test.support.import_helper} --- 用於 import 測試的工具


@geindex module; test.support.import_helper

@ref{ec,,test.support.import_helper} 模組提供 import 測試的支援。


在 3.10 版被加入.


@geindex forget() (於 test.support.import_helper 模組中)
@anchor{library/test test support import_helper forget}@anchor{45f6}
@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{1b64}
@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{653,,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}.

如果無法引入指定的模組則此函式會引發 @ref{653,,ImportError}。

用法範例：

@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


在 3.1 版被加入.

@end deffn

@geindex import_module() (於 test.support.import_helper 模組中)
@anchor{library/test test support import_helper import_module}@anchor{45f7}
@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{11df,,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{291,,sys.platform}.


在 3.1 版被加入.

@end deffn

@geindex modules_setup() (於 test.support.import_helper 模組中)
@anchor{library/test test support import_helper modules_setup}@anchor{45f8}
@deffn {函式} test.support.import_helper.modules_setup ()

回傳 @ref{17c0,,sys.modules} 的複本。
@end deffn

@geindex modules_cleanup() (於 test.support.import_helper 模組中)
@anchor{library/test test support import_helper modules_cleanup}@anchor{45f9}
@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{45fa}
@deffn {函式} test.support.import_helper.unload (name)

從 @code{sys.modules} 中刪除 `name'。
@end deffn

@geindex make_legacy_pyc() (於 test.support.import_helper 模組中)
@anchor{library/test test support import_helper make_legacy_pyc}@anchor{45fb}
@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{45fc}
@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{1a3,,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{45fd}
@deffn {類別} test.support.import_helper.DirsOnSysPath (*paths)

A context manager to temporarily add directories to @ref{3e2,,sys.path}.

This makes a copy of @ref{3e2,,sys.path}, appends any directories given
as positional arguments, then reverts @ref{3e2,,sys.path} to the copied
settings when the context ends.

Note that `all' @ref{3e2,,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 --- 用於 warnings 測試的工具,,test support import_helper --- 用於 import 測試的工具,開發工具
@anchor{library/test module-test support warnings_helper}@anchor{f1}@anchor{library/test test-support-warnings-helper-utilities-for-warnings-tests}@anchor{45fe}
@subsection @code{test.support.warnings_helper} --- 用於 warnings 測試的工具


@geindex module; test.support.warnings_helper

@ref{f1,,test.support.warnings_helper} 模組提供 warnings 測試的支援。


在 3.10 版被加入.


@geindex ignore_warnings() (於 test.support.warnings_helper 模組中)
@anchor{library/test test support warnings_helper ignore_warnings}@anchor{45ff}
@deffn {函式} test.support.warnings_helper.ignore_warnings (*, category)

Suppress warnings that are instances of `category',
which must be @ref{25bd,,Warning} or a subclass.
Roughly equivalent to @ref{179,,warnings.catch_warnings()}
with @ref{8c8,,warnings.simplefilter('ignore'@comma{} category=category)}.
For example:

@example
@@warning_helper.ignore_warnings(category=DeprecationWarning)
def test_suppress_warning():
    # do something
@end example


在 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{4600}
@deffn {函式} test.support.warnings_helper.check_no_resource_warning (testcase)

Context manager to check that no @ref{547,,ResourceWarning} was raised.  You
must remove the object which may emit @ref{547,,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{4601}
@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{1ae,,SyntaxWarning} is emitted only once, and that it
will be converted to a @ref{18e,,SyntaxError} when turned into error.
`testcase' is the @ref{10c,,unittest} instance for the test.  `errtext' is the
regular expression which should match the string representation of the
emitted @ref{1ae,,SyntaxWarning} and raised @ref{18e,,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.


在 3.8 版被加入.

@end deffn

@geindex check_warnings() (於 test.support.warnings_helper 模組中)
@anchor{library/test test support warnings_helper check_warnings}@anchor{4602}
@deffn {函式} test.support.warnings_helper.check_warnings (*filters, quiet=True)

A convenience wrapper for @ref{179,,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{8c8,,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}.

如果沒有指定引數，預設為：

@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{179,,catch_warnings()} is available via the recorder object's
@ref{118,,warnings} attribute.  As a convenience, the attributes of the object
representing the most recent warning can also be accessed directly through
the recorder object (see example below).  If no warning has been raised,
then any of the attributes that would otherwise be expected on an object
representing a warning will return @code{None}.

The recorder object also has a @code{reset()} method, which clears the
warnings list.

The context manager is designed to be used like this:

@example
with check_warnings(("assertion is always true", SyntaxWarning),
                    ("", UserWarning)):
    exec('assert(False, "Hey!")')
    warnings.warn(UserWarning("Hide me!"))
@end example

In this case if either warning was not raised, or some other warning was
raised, @ref{4602,,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 版的變更: 新的可選引數 `filters' 和 `quiet'。

@end deffn

@geindex WarningsRecorder (test.support.warnings_helper 中的類別)
@anchor{library/test test support warnings_helper WarningsRecorder}@anchor{4603}
@deffn {類別} test.support.warnings_helper.WarningsRecorder

Class used to record warnings for unit tests. See documentation of
@ref{4602,,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 除錯與效能分析,軟體封裝與發布,開發工具,Python 標準函式庫 Standard Library
@anchor{library/debug doc}@anchor{4604}@anchor{library/debug debugging-and-profiling}@anchor{4605}@anchor{library/debug translation-repo}@anchor{4606}
@section 除錯與效能分析


這些函式庫幫助你進行 Python 程式開發：除錯器允許你在程式碼中單步 (step) 執行、分析堆疊框 (stack frames) 以及設置中斷點 (breakpoints) 等，效能分析工具執行程式碼並提供關於執行時間的詳細分析，讓你找到程式中的瓶頸 (bottlenecks)。事件稽核 (auditing events) 提供執行時期行為的可見性，否則的話可能需要更侵入性的除錯或修補。

@geindex audit events（稽核事件）
@anchor{library/audit_events audit-events}@anchor{1b27}
@menu
* 稽核事件表:: 
* bdb: bdb --- 偵錯器框架. 偵錯器框架
* faulthandler: faulthandler --- 傾印 Python 回溯. 傾印 Python 回溯
* pdb: pdb --- Python 偵錯器. Python 偵錯器
* Python 的分析器:: 
* timeit: timeit --- 測量小量程式片段的執行時間. 測量小量程式片段的執行時間
* trace: trace --- 追蹤或追查 Python 陳述式執行. 追蹤或追查 Python 陳述式執行
* tracemalloc: tracemalloc --- 追蹤記憶體配置. 追蹤記憶體配置

@end menu

@node 稽核事件表,bdb --- 偵錯器框架,,除錯與效能分析
@anchor{library/audit_events doc}@anchor{4607}@anchor{library/audit_events audit-events-table}@anchor{4608}
@subsection 稽核事件表


這張表包含了所有在 CPython 運行環境 (runtime) 與標準函式庫對於 @ref{1882,,sys.audit()} 或 @ref{60b,,PySys_Audit()} 的呼叫所觸發的事件。這些呼叫是在 3.8 或更新的版本中被新增（請見 
@geindex Python Enhancement Proposals; PEP 578
PEP 578@footnote{https://peps.python.org/pep-0578/}）。

請參考 @ref{4609,,sys.addaudithook()} 及 @ref{460a,,PySys_AddAuditHook()} 來了解如何處理這些事件。

這張表是從 CPython 文件產生的，可能不包含其它實作所觸發的事件。請參考你的運行環境 (runtime) 特定文件來了解實際會觸發的事件。


@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{460b,,[1]}

@item

array.__new__

@tab

@code{typecode}, @code{initializer}

@tab

@ref{4b9,,[1]}

@item

builtins.breakpoint

@tab

@code{breakpointhook}

@tab

@ref{271,,[1]}

@item

builtins.id

@tab

@code{id}

@tab

@ref{161a,,[1]}

@item

builtins.input

@tab

@code{prompt}

@tab

@ref{14d9,,[1]}

@item

builtins.input/result

@tab

@code{result}

@tab

@ref{14d9,,[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{32e,,[1]}

@item

compile

@tab

@code{source}, @code{filename}

@tab

@ref{4ac,,[1]}

@item

cpython.PyConfig_Set

@tab

@code{name}, @code{value}

@tab

@ref{37b,,[1]}

@item

cpython.PyInterpreterState_Clear

@tab



@tab

@ref{460c,,[1]}

@item

cpython.PyInterpreterState_New

@tab



@tab

@ref{460d,,[1]}

@item

cpython._PySys_ClearAuditHooks

@tab



@tab

@ref{f0c,,[1]}

@item

cpython.remote_debugger_script

@tab

@code{script_path}

@tab

@ref{460e,,[1]}

@item

cpython.run_command

@tab

@code{command}

@tab

@ref{1a8,,[1]}

@item

cpython.run_file

@tab

@code{filename}

@tab

@ref{460f,,[1]}

@item

cpython.run_interactivehook

@tab

@code{hook}

@tab

@ref{11c3,,[1]}

@item

cpython.run_module

@tab

@code{module-name}

@tab

@ref{23c,,[1]}

@item

cpython.run_startup

@tab

@code{filename}

@tab

@ref{1b8,,[1]}

@item

cpython.run_stdin

@tab



@tab

@ref{4610,,[1]}@ref{4611,,[2]}@ref{4612,,[3]}

@item

ctypes.addressof

@tab

@code{obj}

@tab

@ref{31ea,,[1]}

@item

ctypes.call_function

@tab

@code{func_pointer}, @code{arguments}

@tab

@ref{31e4,,[1]}

@item

ctypes.cdata

@tab

@code{address}

@tab

@ref{31f5,,[1]}

@item

ctypes.cdata/buffer

@tab

@code{pointer}, @code{size}, @code{offset}

@tab

@ref{31fa,,[1]}@ref{31fb,,[2]}

@item

ctypes.create_string_buffer

@tab

@code{init}, @code{size}

@tab

@ref{31a2,,[1]}

@item

ctypes.create_unicode_buffer

@tab

@code{init}, @code{size}

@tab

@ref{1c7d,,[1]}

@item

ctypes.dlopen

@tab

@code{name}

@tab

@ref{31e2,,[1]}

@item

ctypes.dlsym

@tab

@code{library}, @code{name}

@tab

@ref{31e2,,[1]}

@item

ctypes.dlsym/handle

@tab

@code{handle}, @code{name}

@tab

@ref{31e2,,[1]}

@item

ctypes.get_errno

@tab



@tab

@ref{31dc,,[1]}

@item

ctypes.get_last_error

@tab



@tab

@ref{31de,,[1]}

@item

ctypes.memoryview_at

@tab

@code{address}, @code{size}, @code{readonly}

@tab

@ref{4613,,[1]}

@item

ctypes.set_errno

@tab

@code{errno}

@tab

@ref{31dd,,[1]}

@item

ctypes.set_exception

@tab

@code{code}

@tab

@ref{31e4,,[1]}

@item

ctypes.set_last_error

@tab

@code{error}

@tab

@ref{31df,,[1]}

@item

ctypes.string_at

@tab

@code{ptr}, @code{size}

@tab

@ref{1ec,,[1]}

@item

ctypes.wstring_at

@tab

@code{ptr}, @code{size}

@tab

@ref{31f4,,[1]}

@item

ensurepip.bootstrap

@tab

@code{root}

@tab

@ref{4614,,[1]}

@item

exec

@tab

@code{code_object}

@tab

@ref{49e,,[1]}@ref{49d,,[2]}

@item

fcntl.fcntl

@tab

@code{fd}, @code{cmd}, @code{arg}

@tab

@ref{17d0,,[1]}

@item

fcntl.flock

@tab

@code{fd}, @code{operation}

@tab

@ref{4615,,[1]}

@item

fcntl.ioctl

@tab

@code{fd}, @code{request}, @code{arg}

@tab

@ref{166f,,[1]}

@item

fcntl.lockf

@tab

@code{fd}, @code{cmd}, @code{len}, @code{start}, @code{whence}

@tab

@ref{15e3,,[1]}

@item

ftplib.connect

@tab

@code{self}, @code{host}, @code{port}

@tab

@ref{3eb5,,[1]}

@item

ftplib.sendcmd

@tab

@code{self}, @code{cmd}

@tab

@ref{3eba,,[1]}@ref{3ebb,,[2]}

@item

function.__new__

@tab

@code{code}

@tab

@ref{a7a,,[1]}

@item

gc.get_objects

@tab

@code{generation}

@tab

@ref{9fd,,[1]}

@item

gc.get_referents

@tab

@code{objs}

@tab

@ref{9ff,,[1]}

@item

gc.get_referrers

@tab

@code{objs}

@tab

@ref{9fe,,[1]}

@item

glob.glob

@tab

@code{pathname}, @code{recursive}

@tab

@ref{59a,,[1]}@ref{a01,,[2]}

@item

glob.glob/2

@tab

@code{pathname}, @code{recursive}, @code{root_dir}, @code{dir_fd}

@tab

@ref{59a,,[1]}@ref{a01,,[2]}

@item

http.client.connect

@tab

@code{self}, @code{host}, @code{port}

@tab

@ref{3e97,,[1]}

@item

http.client.send

@tab

@code{self}, @code{data}

@tab

@ref{3e9c,,[1]}

@item

imaplib.open

@tab

@code{self}, @code{host}, @code{port}

@tab

@ref{af8,,[1]}

@item

imaplib.send

@tab

@code{self}, @code{data}

@tab

@ref{3f0d,,[1]}

@item

import

@tab

@code{module}, @code{filename}, @code{sys.path}, @code{sys.meta_path}, @code{sys.path_hooks}

@tab

@ref{7f1,,[1]}

@item

marshal.dumps

@tab

@code{value}, @code{version}

@tab

@ref{2bf6,,[1]}

@item

marshal.load

@tab



@tab

@ref{1cbe,,[1]}

@item

marshal.loads

@tab

@code{bytes}

@tab

@ref{1cbe,,[1]}

@item

mmap.__new__

@tab

@code{fileno}, @code{length}, @code{access}, @code{offset}

@tab

@ref{514,,[1]}

@item

msvcrt.get_osfhandle

@tab

@code{fd}

@tab

@ref{4616,,[1]}

@item

msvcrt.locking

@tab

@code{fd}, @code{mode}, @code{nbytes}

@tab

@ref{4617,,[1]}

@item

msvcrt.open_osfhandle

@tab

@code{handle}, @code{flags}

@tab

@ref{4618,,[1]}

@item

object.__delattr__

@tab

@code{obj}, @code{name}

@tab

@ref{222e,,[1]}

@item

object.__getattr__

@tab

@code{obj}, @code{name}

@tab

@ref{dc6,,[1]}

@item

object.__setattr__

@tab

@code{obj}, @code{name}, @code{value}

@tab

@ref{222d,,[1]}

@item

open

@tab

@code{path}, @code{mode}, @code{flags}

@tab

@ref{315,,[1]}@ref{739,,[2]}@ref{f8d,,[3]}

@item

os.add_dll_directory

@tab

@code{path}

@tab

@ref{bd4,,[1]}

@item

os.chdir

@tab

@code{path}

@tab

@ref{81a,,[1]}@ref{f84,,[2]}

@item

os.chflags

@tab

@code{path}, @code{flags}

@tab

@ref{12ee,,[1]}@ref{2f2c,,[2]}

@item

os.chmod

@tab

@code{path}, @code{mode}, @code{dir_fd}

@tab

@ref{524,,[1]}@ref{525,,[2]}@ref{523,,[3]}

@item

os.chown

@tab

@code{path}, @code{uid}, @code{gid}, @code{dir_fd}

@tab

@ref{12ef,,[1]}@ref{f85,,[2]}@ref{2f2d,,[3]}

@item

os.exec

@tab

@code{path}, @code{args}, @code{env}

@tab

@ref{2f66,,[1]}

@item

os.fork

@tab



@tab

@ref{4b0,,[1]}

@item

os.forkpty

@tab



@tab

@ref{4b1,,[1]}

@item

os.fwalk

@tab

@code{top}, @code{topdown}, @code{onerror}, @code{follow_symlinks}, @code{dir_fd}

@tab

@ref{d4a,,[1]}

@item

os.getxattr

@tab

@code{path}, @code{attribute}

@tab

@ref{1305,,[1]}

@item

os.kill

@tab

@code{pid}, @code{sig}

@tab

@ref{155f,,[1]}

@item

os.killpg

@tab

@code{pgid}, @code{sig}

@tab

@ref{1c84,,[1]}

@item

os.link

@tab

@code{src}, @code{dst}, @code{src_dir_fd}, @code{dst_dir_fd}

@tab

@ref{12f0,,[1]}

@item

os.listdir

@tab

@code{path}

@tab

@ref{12fb,,[1]}

@item

os.listdrives

@tab



@tab

@ref{6be,,[1]}

@item

os.listmounts

@tab

@code{volume}

@tab

@ref{6c0,,[1]}

@item

os.listvolumes

@tab



@tab

@ref{6bf,,[1]}

@item

os.listxattr

@tab

@code{path}

@tab

@ref{1306,,[1]}

@item

os.lockf

@tab

@code{fd}, @code{cmd}, @code{len}

@tab

@ref{1314,,[1]}

@item

os.mkdir

@tab

@code{path}, @code{mode}, @code{dir_fd}

@tab

@ref{527,,[1]}@ref{526,,[2]}

@item

os.posix_spawn

@tab

@code{path}, @code{argv}, @code{env}

@tab

@ref{529,,[1]}@ref{1cd9,,[2]}

@item

os.putenv

@tab

@code{key}, @code{value}

@tab

@ref{25b,,[1]}

@item

os.remove

@tab

@code{path}, @code{dir_fd}

@tab

@ref{12f1,,[1]}@ref{2f31,,[2]}@ref{12f6,,[3]}

@item

os.removexattr

@tab

@code{path}, @code{attribute}

@tab

@ref{1307,,[1]}

@item

os.rename

@tab

@code{src}, @code{dst}, @code{src_dir_fd}, @code{dst_dir_fd}

@tab

@ref{12f2,,[1]}@ref{2f32,,[2]}@ref{12f3,,[3]}

@item

os.rmdir

@tab

@code{path}, @code{dir_fd}

@tab

@ref{12f4,,[1]}

@item

os.scandir

@tab

@code{path}

@tab

@ref{c4b,,[1]}

@item

os.setxattr

@tab

@code{path}, @code{attribute}, @code{value}, @code{flags}

@tab

@ref{1308,,[1]}

@item

os.spawn

@tab

@code{mode}, @code{path}, @code{args}, @code{env}

@tab

@ref{31a,,[1]}

@item

os.startfile

@tab

@code{path}, @code{operation}

@tab

@ref{1b81,,[1]}

@item

os.startfile/2

@tab

@code{path}, @code{operation}, @code{arguments}, @code{cwd}, @code{show_cmd}

@tab

@ref{1b81,,[1]}

@item

os.symlink

@tab

@code{src}, @code{dst}, @code{dir_fd}

@tab

@ref{12f5,,[1]}

@item

os.system

@tab

@code{command}

@tab

@ref{1652,,[1]}

@item

os.truncate

@tab

@code{fd}, @code{length}

@tab

@ref{f8a,,[1]}@ref{1037,,[2]}

@item

os.unsetenv

@tab

@code{key}

@tab

@ref{25c,,[1]}

@item

os.utime

@tab

@code{path}, @code{times}, @code{ns}, @code{dir_fd}

@tab

@ref{12f7,,[1]}

@item

os.walk

@tab

@code{top}, @code{topdown}, @code{onerror}, @code{followlinks}

@tab

@ref{6c9,,[1]}

@item

pathlib.Path.glob

@tab

@code{self}, @code{pattern}

@tab

@ref{532,,[1]}

@item

pathlib.Path.rglob

@tab

@code{self}, @code{pattern}

@tab

@ref{533,,[1]}

@item

pdb.Pdb

@tab



@tab

@ref{273,,[1]}

@item

pickle.find_class

@tab

@code{module}, @code{name}

@tab

@ref{2bcc,,[1]}

@item

poplib.connect

@tab

@code{self}, @code{host}, @code{port}

@tab

@ref{b14,,[1]}@ref{b15,,[2]}

@item

poplib.putline

@tab

@code{self}, @code{line}

@tab

@ref{b14,,[1]}@ref{b15,,[2]}

@item

pty.spawn

@tab

@code{argv}

@tab

@ref{117d,,[1]}

@item

resource.prlimit

@tab

@code{pid}, @code{resource}, @code{limits}

@tab

@ref{1185,,[1]}

@item

resource.setrlimit

@tab

@code{resource}, @code{limits}

@tab

@ref{175c,,[1]}

@item

setopencodehook

@tab



@tab

@ref{19e9,,[1]}

@item

shutil.chown

@tab

@code{path}, @code{user}, @code{group}

@tab

@ref{543,,[1]}

@item

shutil.copyfile

@tab

@code{src}, @code{dst}

@tab

@ref{c46,,[1]}@ref{c47,,[2]}@ref{c45,,[3]}

@item

shutil.copymode

@tab

@code{src}, @code{dst}

@tab

@ref{c46,,[1]}@ref{1974,,[2]}

@item

shutil.copystat

@tab

@code{src}, @code{dst}

@tab

@ref{c47,,[1]}@ref{132f,,[2]}

@item

shutil.copytree

@tab

@code{src}, @code{dst}

@tab

@ref{c15,,[1]}

@item

shutil.make_archive

@tab

@code{base_name}, @code{format}, @code{root_dir}, @code{base_dir}

@tab

@ref{6d3,,[1]}

@item

shutil.move

@tab

@code{src}, @code{dst}

@tab

@ref{c48,,[1]}

@item

shutil.rmtree

@tab

@code{path}, @code{dir_fd}

@tab

@ref{354,,[1]}

@item

shutil.unpack_archive

@tab

@code{filename}, @code{extract_dir}, @code{format}

@tab

@ref{68f,,[1]}

@item

signal.pthread_kill

@tab

@code{thread_id}, @code{signalnum}

@tab

@ref{1332,,[1]}

@item

smtplib.connect

@tab

@code{self}, @code{host}, @code{port}

@tab

@ref{1c78,,[1]}

@item

smtplib.send

@tab

@code{self}, @code{data}

@tab

@ref{b1e,,[1]}

@item

socket.__new__

@tab

@code{self}, @code{family}, @code{type}, @code{protocol}

@tab

@ref{f9c,,[1]}

@item

socket.bind

@tab

@code{self}, @code{address}

@tab

@ref{172e,,[1]}

@item

socket.connect

@tab

@code{self}, @code{address}

@tab

@ref{f9e,,[1]}@ref{172d,,[2]}

@item

socket.getaddrinfo

@tab

@code{host}, @code{port}, @code{family}, @code{type}, @code{protocol}

@tab

@ref{1a0e,,[1]}

@item

socket.gethostbyaddr

@tab

@code{ip_address}

@tab

@ref{1b82,,[1]}

@item

socket.gethostbyname

@tab

@code{hostname}

@tab

@ref{384c,,[1]}@ref{1b83,,[2]}

@item

socket.gethostname

@tab



@tab

@ref{2ed8,,[1]}

@item

socket.getnameinfo

@tab

@code{sockaddr}

@tab

@ref{198b,,[1]}

@item

socket.getservbyname

@tab

@code{servicename}, @code{protocolname}

@tab

@ref{384e,,[1]}

@item

socket.getservbyport

@tab

@code{port}, @code{protocolname}

@tab

@ref{384f,,[1]}

@item

socket.sendmsg

@tab

@code{self}, @code{address}

@tab

@ref{69a,,[1]}

@item

socket.sendto

@tab

@code{self}, @code{address}

@tab

@ref{fa4,,[1]}

@item

socket.sethostname

@tab

@code{name}

@tab

@ref{133c,,[1]}

@item

sqlite3.connect

@tab

@code{database}

@tab

@ref{5a0,,[1]}

@item

sqlite3.connect/handle

@tab

@code{connection_handle}

@tab

@ref{5a0,,[1]}

@item

sqlite3.enable_load_extension

@tab

@code{connection}, @code{enabled}

@tab

@ref{a38,,[1]}

@item

sqlite3.load_extension

@tab

@code{connection}, @code{path}

@tab

@ref{6d8,,[1]}

@item

subprocess.Popen

@tab

@code{executable}, @code{args}, @code{cwd}, @code{env}

@tab

@ref{4b2,,[1]}

@item

sys._current_exceptions

@tab



@tab

@ref{6e2,,[1]}

@item

sys._current_frames

@tab



@tab

@ref{162a,,[1]}

@item

sys._getframe

@tab

@code{frame}

@tab

@ref{8e8,,[1]}

@item

sys._getframemodulename

@tab

@code{depth}

@tab

@ref{1a2a,,[1]}

@item

sys.addaudithook

@tab



@tab

@ref{460a,,[1]}@ref{4609,,[2]}

@item

sys.excepthook

@tab

@code{hook}, @code{type}, @code{value}, @code{traceback}

@tab

@ref{a05,,[1]}

@item

sys.monitoring.register_callback

@tab

@code{func}

@tab

@ref{4619,,[1]}

@item

sys.remote_exec

@tab

@code{pid}

@tab

@ref{461a,,[1]}

@item

sys.set_asyncgen_hooks_finalizer

@tab



@tab

@ref{18f4,,[1]}

@item

sys.set_asyncgen_hooks_firstiter

@tab



@tab

@ref{18f4,,[1]}

@item

sys.setprofile

@tab



@tab

@ref{16f2,,[1]}

@item

sys.settrace

@tab



@tab

@ref{2e1,,[1]}

@item

sys.unraisablehook

@tab

@code{hook}, @code{unraisable}

@tab

@ref{502,,[1]}

@item

syslog.closelog

@tab



@tab

@ref{75a,,[1]}

@item

syslog.openlog

@tab

@code{ident}, @code{logoption}, @code{facility}

@tab

@ref{759,,[1]}

@item

syslog.setlogmask

@tab

@code{maskpri}

@tab

@ref{461b,,[1]}

@item

syslog.syslog

@tab

@code{priority}, @code{message}

@tab

@ref{75b,,[1]}

@item

tempfile.mkdtemp

@tab

@code{fullpath}

@tab

@ref{1435,,[1]}@ref{528,,[2]}

@item

tempfile.mkstemp

@tab

@code{fullpath}

@tab

@ref{6e6,,[1]}@ref{2b7b,,[2]}@ref{2b7c,,[3]}

@item

time.sleep

@tab

@code{secs}

@tab

@ref{461c,,[1]}

@item

urllib.Request

@tab

@code{fullurl}, @code{data}, @code{headers}, @code{method}

@tab

@ref{306,,[1]}

@item

webbrowser.open

@tab

@code{url}

@tab

@ref{1802,,[1]}

@item

winreg.ConnectRegistry

@tab

@code{computer_name}, @code{key}

@tab

@ref{461d,,[1]}

@item

winreg.CreateKey

@tab

@code{key}, @code{sub_key}, @code{access}

@tab

@ref{461e,,[1]}@ref{155a,,[2]}

@item

winreg.DeleteKey

@tab

@code{key}, @code{sub_key}, @code{access}

@tab

@ref{461f,,[1]}@ref{155b,,[2]}

@item

winreg.DeleteValue

@tab

@code{key}, @code{value}

@tab

@ref{4620,,[1]}

@item

winreg.DisableReflectionKey

@tab

@code{key}

@tab

@ref{155c,,[1]}

@item

winreg.EnableReflectionKey

@tab

@code{key}

@tab

@ref{155d,,[1]}

@item

winreg.EnumKey

@tab

@code{key}, @code{index}

@tab

@ref{4621,,[1]}

@item

winreg.EnumValue

@tab

@code{key}, @code{index}

@tab

@ref{4622,,[1]}

@item

winreg.ExpandEnvironmentStrings

@tab

@code{str}

@tab

@ref{15ef,,[1]}

@item

winreg.LoadKey

@tab

@code{key}, @code{sub_key}, @code{file_name}

@tab

@ref{4623,,[1]}

@item

winreg.OpenKey

@tab

@code{key}, @code{sub_key}, @code{access}

@tab

@ref{4624,,[1]}

@item

winreg.OpenKey/result

@tab

@code{key}

@tab

@ref{461e,,[1]}@ref{155a,,[2]}@ref{4624,,[3]}

@item

winreg.PyHKEY.Detach

@tab

@code{key}

@tab

@ref{4625,,[1]}

@item

winreg.QueryInfoKey

@tab

@code{key}

@tab

@ref{4626,,[1]}

@item

winreg.QueryReflectionKey

@tab

@code{key}

@tab

@ref{155e,,[1]}

@item

winreg.QueryValue

@tab

@code{key}, @code{sub_key}, @code{value_name}

@tab

@ref{4627,,[1]}@ref{4628,,[2]}

@item

winreg.SaveKey

@tab

@code{key}, @code{file_name}

@tab

@ref{4629,,[1]}

@item

winreg.SetValue

@tab

@code{key}, @code{sub_key}, @code{type}, @code{value}

@tab

@ref{462a,,[1]}@ref{1a49,,[2]}

@end multitable


下列事件是內部觸發的，與任何 CPython 的公開 API 並無關係：


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

稽核事件

@tab

引數

@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



在 3.14 版被加入: 內部稽核事件 @code{_posixsubprocess.fork_exec}。


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node bdb --- 偵錯器框架,faulthandler --- 傾印 Python 回溯,稽核事件表,除錯與效能分析
@anchor{library/bdb doc}@anchor{462b}@anchor{library/bdb bdb-debugger-framework}@anchor{462c}@anchor{library/bdb module-bdb}@anchor{10}@anchor{library/bdb translation-repo}@anchor{462d}
@subsection @code{bdb} --- 偵錯器框架


@geindex module; bdb

`原始碼：'Lib/bdb.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/bdb.py}


__________________________________________________________________


The @ref{10,,bdb} module handles basic debugger functions, like setting breakpoints
or managing execution via the debugger.

有定義以下例外：

@geindex BdbQuit
@anchor{library/bdb bdb BdbQuit}@anchor{278}
@deffn {例外} bdb.BdbQuit

由 @ref{2d5,,Bdb} 類別所引發的例外，用來退出偵錯器。
@end deffn

@ref{10,,bdb} 模組也定義了兩個類別：

@geindex Breakpoint (bdb 中的類別)
@anchor{library/bdb bdb Breakpoint}@anchor{462e}
@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{462f,,bpbynumber}
and by @code{(file, line)} pairs through @ref{4630,,bplist}.  The former points to
a single instance of class @ref{462e,,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{4631,,file name} should
be in canonical form.  If a @ref{4632,,funcname} is defined, a breakpoint
@ref{4633,,hit} will be counted when the first line of that function is
executed.  A @ref{4634,,conditional} breakpoint always counts a
@ref{4633,,hit}.

@ref{462e,,Breakpoint} 實例有以下方法：

@geindex deleteMe() (bdb.Breakpoint 的方法)
@anchor{library/bdb bdb Breakpoint deleteMe}@anchor{4635}
@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{4636}
@deffn {方法} enable ()

Mark the breakpoint as enabled.
@end deffn

@geindex disable() (bdb.Breakpoint 的方法)
@anchor{library/bdb bdb Breakpoint disable}@anchor{4637}
@deffn {方法} disable ()

Mark the breakpoint as disabled.
@end deffn

@geindex bpformat() (bdb.Breakpoint 的方法)
@anchor{library/bdb bdb Breakpoint bpformat}@anchor{4638}
@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


在 3.2 版被加入.

@end deffn

@geindex bpprint() (bdb.Breakpoint 的方法)
@anchor{library/bdb bdb Breakpoint bpprint}@anchor{4639}
@deffn {方法} bpprint (out=None)

Print the output of @ref{4638,,bpformat()} to the file `out', or if it is
@code{None}, to standard output.
@end deffn

@ref{462e,,Breakpoint} 實例有以下屬性：

@geindex file (bdb.Breakpoint 的屬性)
@anchor{library/bdb bdb Breakpoint file}@anchor{4631}
@deffn {屬性} file

@ref{462e,,Breakpoint} 的檔案名稱。
@end deffn

@geindex line (bdb.Breakpoint 的屬性)
@anchor{library/bdb bdb Breakpoint line}@anchor{463a}
@deffn {屬性} line

Line number of the @ref{462e,,Breakpoint} within @ref{4631,,file}.
@end deffn

@geindex temporary (bdb.Breakpoint 的屬性)
@anchor{library/bdb bdb Breakpoint temporary}@anchor{463b}
@deffn {屬性} temporary

@code{True} if a @ref{462e,,Breakpoint} at (file, line) is temporary.
@end deffn

@geindex cond (bdb.Breakpoint 的屬性)
@anchor{library/bdb bdb Breakpoint cond}@anchor{4634}
@deffn {屬性} cond

Condition for evaluating a @ref{462e,,Breakpoint} at (file, line).
@end deffn

@geindex funcname (bdb.Breakpoint 的屬性)
@anchor{library/bdb bdb Breakpoint funcname}@anchor{4632}
@deffn {屬性} funcname

Function name that defines whether a @ref{462e,,Breakpoint} is hit upon
entering the function.
@end deffn

@geindex enabled (bdb.Breakpoint 的屬性)
@anchor{library/bdb bdb Breakpoint enabled}@anchor{463c}
@deffn {屬性} enabled

如 @ref{462e,,Breakpoint} 有被啟用則為 @code{True}。
@end deffn

@geindex bpbynumber (bdb.Breakpoint 的屬性)
@anchor{library/bdb bdb Breakpoint bpbynumber}@anchor{462f}
@deffn {屬性} bpbynumber

Numeric index for a single instance of a @ref{462e,,Breakpoint}.
@end deffn

@geindex bplist (bdb.Breakpoint 的屬性)
@anchor{library/bdb bdb Breakpoint bplist}@anchor{4630}
@deffn {屬性} bplist

Dictionary of @ref{462e,,Breakpoint} instances indexed by
(@ref{4631,,file}, @ref{463a,,line}) tuples.
@end deffn

@geindex ignore (bdb.Breakpoint 的屬性)
@anchor{library/bdb bdb Breakpoint ignore}@anchor{463d}
@deffn {屬性} ignore

Number of times to ignore a @ref{462e,,Breakpoint}.
@end deffn

@geindex hits (bdb.Breakpoint 的屬性)
@anchor{library/bdb bdb Breakpoint hits}@anchor{4633}
@deffn {屬性} hits

Count of the number of times a @ref{462e,,Breakpoint} has been hit.
@end deffn
@end deffn

@geindex Bdb (bdb 中的類別)
@anchor{library/bdb bdb Bdb}@anchor{2d5}
@deffn {類別} bdb.Bdb (skip=None, backend='settrace')

The @ref{2d5,,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{273,,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 @ref{2d5,,Bdb}. It
can be either @code{'settrace'} or @code{'monitoring'}. @code{'settrace'} uses
@ref{2e1,,sys.settrace()} which has the best backward compatibility. The
@code{'monitoring'} backend uses the new @ref{e0,,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 版的變更: 新增 `skip' 引數。



在 3.14 版的變更: 新增 `backend' 參數。


The following methods of @ref{2d5,,Bdb} normally don't need to be overridden.

@geindex canonic() (bdb.Bdb 的方法)
@anchor{library/bdb bdb Bdb canonic}@anchor{463e}
@deffn {方法} canonic (filename)

Return canonical form of `filename'.

For real file names, the canonical form is an operating-system-dependent,
@ref{2b08,,case-normalized} @ref{151b,,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{463f}
@deffn {方法} start_trace (self)

Start tracing. For @code{'settrace'} backend, this method is equivalent to
@code{sys.settrace(self.trace_dispatch)}


在 3.14 版被加入.

@end deffn

@geindex stop_trace() (bdb.Bdb 的方法)
@anchor{library/bdb bdb Bdb stop_trace}@anchor{4640}
@deffn {方法} stop_trace (self)

Stop tracing. For @code{'settrace'} backend, this method is equivalent to
@code{sys.settrace(None)}


在 3.14 版被加入.

@end deffn

@geindex reset() (bdb.Bdb 的方法)
@anchor{library/bdb bdb Bdb reset}@anchor{4641}
@deffn {方法} reset ()

Set the @code{botframe}, @code{stopframe}, @code{returnframe} and
@ref{4642,,quitting} attributes with values ready to start debugging.
@end deffn

@geindex trace_dispatch() (bdb.Bdb 的方法)
@anchor{library/bdb bdb Bdb trace_dispatch}@anchor{4643}
@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.

@item 
@code{"c_call"}: A C function is about to be called.

@item 
@code{"c_return"}: A C function has returned.

@item 
@code{"c_exception"}: A C function has raised an exception.
@end itemize

For the Python events, specialized functions (see below) are called.  For
the C events, no action is taken.

The `arg' parameter depends on the previous event.

See the documentation for @ref{2e1,,sys.settrace()} for more information on the
trace function.  For more information on code and frame objects, refer to
@ref{21e4,,標準型別階層}.
@end deffn

@geindex dispatch_line() (bdb.Bdb 的方法)
@anchor{library/bdb bdb Bdb dispatch_line}@anchor{4644}
@deffn {方法} dispatch_line (frame)

If the debugger should stop on the current line, invoke the
@ref{4645,,user_line()} method (which should be overridden in subclasses).
Raise a @ref{278,,BdbQuit} exception if the @ref{4642,,quitting} flag is set
(which can be set from @ref{4645,,user_line()}).  Return a reference to the
@ref{4643,,trace_dispatch()} method for further tracing in that scope.
@end deffn

@geindex dispatch_call() (bdb.Bdb 的方法)
@anchor{library/bdb bdb Bdb dispatch_call}@anchor{4646}
@deffn {方法} dispatch_call (frame, arg)

If the debugger should stop on this function call, invoke the
@ref{4647,,user_call()} method (which should be overridden in subclasses).
Raise a @ref{278,,BdbQuit} exception if the @ref{4642,,quitting} flag is set
(which can be set from @ref{4647,,user_call()}).  Return a reference to the
@ref{4643,,trace_dispatch()} method for further tracing in that scope.
@end deffn

@geindex dispatch_return() (bdb.Bdb 的方法)
@anchor{library/bdb bdb Bdb dispatch_return}@anchor{4648}
@deffn {方法} dispatch_return (frame, arg)

If the debugger should stop on this function return, invoke the
@ref{4649,,user_return()} method (which should be overridden in subclasses).
Raise a @ref{278,,BdbQuit} exception if the @ref{4642,,quitting} flag is set
(which can be set from @ref{4649,,user_return()}).  Return a reference to the
@ref{4643,,trace_dispatch()} method for further tracing in that scope.
@end deffn

@geindex dispatch_exception() (bdb.Bdb 的方法)
@anchor{library/bdb bdb Bdb dispatch_exception}@anchor{464a}
@deffn {方法} dispatch_exception (frame, arg)

If the debugger should stop at this exception, invokes the
@ref{464b,,user_exception()} method (which should be overridden in subclasses).
Raise a @ref{278,,BdbQuit} exception if the @ref{4642,,quitting} flag is set
(which can be set from @ref{464b,,user_exception()}).  Return a reference to the
@ref{4643,,trace_dispatch()} method for further tracing in that scope.
@end deffn

Normally derived classes don't override the following methods, but they may
if they want to redefine the definition of stopping and breakpoints.

@geindex is_skipped_line() (bdb.Bdb 的方法)
@anchor{library/bdb bdb Bdb is_skipped_line}@anchor{464c}
@deffn {方法} is_skipped_line (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{464d}
@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{464e}
@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{464f,,effective()}.
@end deffn

@geindex break_anywhere() (bdb.Bdb 的方法)
@anchor{library/bdb bdb Bdb break_anywhere}@anchor{4650}
@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{4647}
@deffn {方法} user_call (frame, argument_list)

Called from @ref{4646,,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{4645}
@deffn {方法} user_line (frame)

Called from @ref{4644,,dispatch_line()} when either @ref{464d,,stop_here()} or
@ref{464e,,break_here()} returns @code{True}.
@end deffn

@geindex user_return() (bdb.Bdb 的方法)
@anchor{library/bdb bdb Bdb user_return}@anchor{4649}
@deffn {方法} user_return (frame, return_value)

Called from @ref{4648,,dispatch_return()} when @ref{464d,,stop_here()} returns @code{True}.
@end deffn

@geindex user_exception() (bdb.Bdb 的方法)
@anchor{library/bdb bdb Bdb user_exception}@anchor{464b}
@deffn {方法} user_exception (frame, exc_info)

Called from @ref{464a,,dispatch_exception()} when @ref{464d,,stop_here()}
returns @code{True}.
@end deffn

@geindex do_clear() (bdb.Bdb 的方法)
@anchor{library/bdb bdb Bdb do_clear}@anchor{4651}
@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{4652}
@deffn {方法} set_step ()

Stop after one line of code.
@end deffn

@geindex set_next() (bdb.Bdb 的方法)
@anchor{library/bdb bdb Bdb set_next}@anchor{4653}
@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{4654}
@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{4655}
@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{4656}
@deffn {方法} set_trace ([frame])

Start debugging from `frame'.  If `frame' is not specified, debugging
starts from caller's frame.


在 3.13 版的變更: @ref{4657,,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{4658}
@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{4642}
@deffn {方法} set_quit ()

@geindex quitting (bdb.Bdb attribute)

Set the @code{quitting} attribute to @code{True}.  This raises @ref{278,,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{4659}
@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{463e,,canonic()} method.
@end deffn

@geindex clear_break() (bdb.Bdb 的方法)
@anchor{library/bdb bdb Bdb clear_break}@anchor{465a}
@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{465b}
@deffn {方法} clear_bpbynumber (arg)

Delete the breakpoint which has the index `arg' in the
@ref{462f,,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{465c}
@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{465d}
@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{465e}
@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{2eb,,ValueError} is raised.


在 3.2 版被加入.

@end deffn

@geindex get_break() (bdb.Bdb 的方法)
@anchor{library/bdb bdb Bdb get_break}@anchor{465f}
@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{4660}
@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{4661}
@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{4662}
@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{4663}
@deffn {方法} disable_current_event ()

Disable the current event until the next time @ref{4664,,restart_events()} is
called. This is helpful when the debugger is not interested in the current
line.


在 3.14 版被加入.

@end deffn

@geindex restart_events() (bdb.Bdb 的方法)
@anchor{library/bdb bdb Bdb restart_events}@anchor{4664}
@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.


在 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{4665}
@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{4666}
@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 
函式名稱或 @code{"<lambda>"}。

@item 
輸入引數。

@item 
回傳值。

@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{2aae,,statement}, given as a string.

@geindex run() (bdb.Bdb 的方法)
@anchor{library/bdb bdb Bdb run}@anchor{4667}
@deffn {方法} run (cmd, globals=None, locals=None)

Debug a statement executed via the @ref{49d,,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{4668}
@deffn {方法} runeval (expr, globals=None, locals=None)

Debug an expression executed via the @ref{49e,,eval()} function.  `globals' and
`locals' have the same meaning as in @ref{4667,,run()}.
@end deffn

@geindex runctx() (bdb.Bdb 的方法)
@anchor{library/bdb bdb Bdb runctx}@anchor{4669}
@deffn {方法} runctx (cmd, globals, locals)

For backwards compatibility.  Calls the @ref{4667,,run()} method.
@end deffn

@geindex runcall() (bdb.Bdb 的方法)
@anchor{library/bdb bdb Bdb runcall}@anchor{c68}
@deffn {方法} runcall (func, /, *args, **kwds)

Debug a single function call, and return its result.
@end deffn
@end deffn

最後，這個模組定義了以下函式：

@geindex checkfuncname() (於 bdb 模組中)
@anchor{library/bdb bdb checkfuncname}@anchor{466a}
@deffn {函式} bdb.checkfuncname (b, frame)

Return @code{True} if we should break here, depending on the way the
@ref{462e,,Breakpoint} `b' was set.

If it was set via line number, it checks if
@ref{463a,,b.line} is the same as the one in `frame'.
If the breakpoint was set via
@ref{4632,,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{464f}
@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{4630,,bplist} for the
(@ref{4631,,file}, @ref{463a,,line})
(which must exist) that is @ref{463c,,enabled}, for
which @ref{466a,,checkfuncname()} is true, and that has neither a false
@ref{4634,,condition} nor positive
@ref{463d,,ignore} count.  The `flag', meaning that a
temporary breakpoint should be deleted, is @code{False} only when the
@ref{4634,,cond} cannot be evaluated (in which case,
@ref{463d,,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{4657}
@deffn {函式} bdb.set_trace ()

Start debugging with a @ref{2d5,,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 --- 傾印 Python 回溯,pdb --- Python 偵錯器,bdb --- 偵錯器框架,除錯與效能分析
@anchor{library/faulthandler doc}@anchor{466b}@anchor{library/faulthandler faulthandler-dump-the-python-traceback}@anchor{466c}@anchor{library/faulthandler module-faulthandler}@anchor{5c}@anchor{library/faulthandler translation-repo}@anchor{466d}
@subsection @code{faulthandler} --- 傾印 Python 回溯


@geindex module; faulthandler


在 3.3 版被加入.



__________________________________________________________________


This module contains functions to dump Python tracebacks explicitly, on a fault,
after a timeout, or on a user signal. Call @ref{20f,,faulthandler.enable()} to
install fault handlers for the @ref{127b,,SIGSEGV},
@ref{127c,,SIGFPE}, @ref{127d,,SIGABRT}, @ref{127e,,SIGBUS}, and
@ref{127f,,SIGILL} signals. You can also
enable them at startup by setting the 
@geindex PYTHONFAULTHANDLER
@geindex 環境變數; PYTHONFAULTHANDLER
@ref{1280,,PYTHONFAULTHANDLER} environment
variable or by using the @ref{16f,,-X} @code{faulthandler} command line option.

The fault handler is compatible with system fault handlers like Apport or the
Windows fault handler. The module uses an alternative stack for signal handlers
if the @code{sigaltstack()} function is available. This allows it to dump the
traceback even on a stack overflow.

The fault handler is called on catastrophic cases and therefore can only use
signal-safe functions (e.g. it cannot allocate memory on the heap). Because of
this limitation traceback dumping is minimal compared to normal Python
tracebacks:


@itemize *

@item 
Only ASCII is supported. The @code{backslashreplace} error handler is used on
encoding.

@item 
Each string is limited to 500 characters.

@item 
Only the filename, the function name and the line number are
displayed. (no source code)

@item 
It is limited to 100 frames and 100 threads.

@item 
The order is reversed: the most recent call is shown first.
@end itemize

By default, the Python traceback is written to @ref{b2a,,sys.stderr}. To see
tracebacks, applications must be run in the terminal. A log file can
alternatively be passed to @ref{20f,,faulthandler.enable()}.

The module is implemented in C, so tracebacks can be dumped on a crash or when
Python is deadlocked.

The @ref{503,,Python Development Mode} calls @ref{20f,,faulthandler.enable()}
at Python startup.


@subsubheading 也參考



@table @asis

@item @ref{aa,,pdb} 模組

Interactive source code debugger for Python programs.

@item @ref{104,,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:: 
* 範例: 範例<42>. 

@end menu

@node Dumping the traceback,Dumping the C stack,,faulthandler --- 傾印 Python 回溯
@anchor{library/faulthandler dumping-the-traceback}@anchor{466e}
@subsubsection Dumping the traceback


@geindex dump_traceback() (於 faulthandler 模組中)
@anchor{library/faulthandler faulthandler dump_traceback}@anchor{ffa}
@deffn {函式} faulthandler.dump_traceback (file=sys.stderr, all_threads=True)

Dump the tracebacks of all threads into `file'. If `all_threads' is
@code{False}, dump only the current thread.


@subsubheading 也參考


@ref{1080,,traceback.print_tb()}, which can be used to print a traceback object.



在 3.5 版的變更: Added support for passing file descriptor to this function.

@end deffn

@node Dumping the C stack,Fault handler state,Dumping the traceback,faulthandler --- 傾印 Python 回溯
@anchor{library/faulthandler dumping-the-c-stack}@anchor{466f}
@subsubsection Dumping the C stack



在 3.14 版被加入.


@geindex dump_c_stack() (於 faulthandler 模組中)
@anchor{library/faulthandler faulthandler dump_c_stack}@anchor{20e}
@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{20d}@anchor{library/faulthandler id1}@anchor{4670}
@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{8fd,,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 --- 傾印 Python 回溯
@anchor{library/faulthandler fault-handler-state}@anchor{4671}
@subsubsection Fault handler state


@geindex enable() (於 faulthandler 模組中)
@anchor{library/faulthandler faulthandler enable}@anchor{20f}
@deffn {函式} faulthandler.enable (file=sys.stderr, all_threads=True, c_stack=True)

Enable the fault handler: install handlers for the @ref{127b,,SIGSEGV},
@ref{127c,,SIGFPE}, @ref{127d,,SIGABRT}, @ref{127e,,SIGBUS}
and @ref{127f,,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{4672,,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{20e,,dump_c_stack()} for
more information on compatibility.


在 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{164,,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.

@end deffn

@geindex disable() (於 faulthandler 模組中)
@anchor{library/faulthandler faulthandler disable}@anchor{4673}
@deffn {函式} faulthandler.disable ()

Disable the fault handler: uninstall the signal handlers installed by
@ref{20f,,enable()}.
@end deffn

@geindex is_enabled() (於 faulthandler 模組中)
@anchor{library/faulthandler faulthandler is_enabled}@anchor{4674}
@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 --- 傾印 Python 回溯
@anchor{library/faulthandler dumping-the-tracebacks-after-a-timeout}@anchor{4675}
@subsubsection Dumping the tracebacks after a timeout


@geindex dump_traceback_later() (於 faulthandler 模組中)
@anchor{library/faulthandler faulthandler dump_traceback_later}@anchor{ffb}
@deffn {函式} faulthandler.dump_traceback_later (timeout, repeat=False, file=sys.stderr, exit=False)

Dump the tracebacks of all threads, after a timeout of `timeout' seconds, or
every `timeout' seconds if `repeat' is @code{True}.  If `exit' is @code{True}, call
@code{_exit()} with status=1 after dumping the tracebacks.  (Note
@code{_exit()} exits the process immediately, which means it doesn't do any
cleanup like flushing file buffers.) If the function is called twice, the new
call replaces previous parameters and resets the timeout. The timer has a
sub-second resolution.

The `file' must be kept open until the traceback is dumped or
@ref{4676,,cancel_dump_traceback_later()} is called: see @ref{4672,,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.

@end deffn

@geindex cancel_dump_traceback_later() (於 faulthandler 模組中)
@anchor{library/faulthandler faulthandler cancel_dump_traceback_later}@anchor{4676}
@deffn {函式} faulthandler.cancel_dump_traceback_later ()

Cancel the last call to @ref{ffb,,dump_traceback_later()}.
@end deffn

@node Dumping the traceback on a user signal,Issue with file descriptors,Dumping the tracebacks after a timeout,faulthandler --- 傾印 Python 回溯
@anchor{library/faulthandler dumping-the-traceback-on-a-user-signal}@anchor{4677}
@subsubsection Dumping the traceback on a user signal


@geindex register() (於 faulthandler 模組中)
@anchor{library/faulthandler faulthandler register}@anchor{ff9}
@deffn {函式} faulthandler.register (signum, file=sys.stderr, all_threads=True, chain=False)

Register a user signal: install a handler for the `signum' signal to dump
the traceback of all threads, or of the current thread if `all_threads' is
@code{False}, into `file'. Call the previous handler if chain is @code{True}.

The `file' must be kept open until the signal is unregistered by
@ref{4678,,unregister()}: see @ref{4672,,issue with file descriptors}.

Not available on Windows.


在 3.5 版的變更: Added support for passing file descriptor to this function.

@end deffn

@geindex unregister() (於 faulthandler 模組中)
@anchor{library/faulthandler faulthandler unregister}@anchor{4678}
@deffn {函式} faulthandler.unregister (signum)

Unregister a user signal: uninstall the handler of the `signum' signal
installed by @ref{ff9,,register()}. Return @code{True} if the signal was registered,
@code{False} otherwise.

Not available on Windows.
@end deffn

@node Issue with file descriptors,範例<42>,Dumping the traceback on a user signal,faulthandler --- 傾印 Python 回溯
@anchor{library/faulthandler faulthandler-fd}@anchor{4672}@anchor{library/faulthandler issue-with-file-descriptors}@anchor{4679}
@subsubsection Issue with file descriptors


@ref{20f,,enable()}, @ref{ffb,,dump_traceback_later()} and @ref{ff9,,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{d52,,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 範例<42>,,Issue with file descriptors,faulthandler --- 傾印 Python 回溯
@anchor{library/faulthandler example}@anchor{467a}
@subsubsection 範例


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.14/_ctypes.cpython-314d-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.14/_ctypes.cpython-314d-x86_64-linux-gnu.so", at +0x15a33 [0x77b7315e6a33]
  Binary file "/opt/python/build/lib.linux-x86_64-3.14/_ctypes.cpython-314d-x86_64-linux-gnu.so", at +0x164fa [0x77b7315e74fa]
  Binary file "/opt/python/build/lib.linux-x86_64-3.14/_ctypes.cpython-314d-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 --- Python 偵錯器,Python 的分析器,faulthandler --- 傾印 Python 回溯,除錯與效能分析
@anchor{library/pdb doc}@anchor{467b}@anchor{library/pdb debugger}@anchor{467c}@anchor{library/pdb module-pdb}@anchor{aa}@anchor{library/pdb pdb-the-python-debugger}@anchor{467d}@anchor{library/pdb translation-repo}@anchor{467e}
@subsection @code{pdb} --- Python 偵錯器


@geindex module; pdb

`原始碼：'Lib/pdb.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/pdb.py}

@geindex debugging（偵錯）


__________________________________________________________________


@ref{aa,,pdb} 模組定義了一個 Python 程式的互動式原始碼偵錯器。它支援在原始碼列層級 (source line level) 設定（條件式的）斷點 (breakpoint) 和單步執行、檢視 stack frame（堆疊框）、列出原始碼、以及在任何 stack frame 情境 (context) 中為任意 Python 程式碼求值 (evaluation)。它還支援事後偵錯 (post-mortem debugging)，並可以在程式控制下呼叫。

@geindex Pdb（pdb 中的類別）
@geindex module（模組）;bdb
@geindex module（模組）;cmd

偵錯器是可擴充的 —— 偵錯器實際被定義為 @ref{273,,Pdb} 類別。該類別目前沒有文件，但可以很容易地透過閱讀原始碼來理解它。擴充套件介面使用了 @ref{10,,bdb} 和 @ref{1a,,cmd} 模組。


@subsubheading 也參考



@table @asis

@item @ref{5c,,faulthandler} 模組

用於在出現故障時、超時 (timeout) 後或於接收到使用者訊號時，顯式地轉儲 (dump) Python 回溯 (traceback)。

@item @ref{104,,traceback} 模組

用於提取、格式化和印出 Python 程式 stack trace（堆疊追蹤）的標準介面。
@end table


自一個執行中程式切入偵錯器的典型用法為插入：

@example
import pdb; pdb.set_trace()
@end example

或：

@example
breakpoint()
@end example

到你想切入偵錯器的位置，然後執行程式，就可以單步執行上述陳述式之後的程式碼，並可以使用 @ref{467f,,continue} 命令來離開偵錯器、繼續執行。


在 3.7 版的變更: 當使用預設值呼叫時，可以使用內建的 @ref{271,,breakpoint()} 來取代 @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

偵錯器的提示字元是 @code{(Pdb)}，這表示你處於偵錯模式：

@example
> ...(2)double()
-> breakpoint()
(Pdb) p x
3
(Pdb) continue
3 * 2 is 6
@end example


在 3.3 版的變更: 透過 @ref{bf,,readline} 模組達成的 tab 補全可用於補全本模組的命令和命令的引數，例如會提供目前的全域和區域名稱以作為 @code{p} 命令的引數。

@anchor{library/pdb pdb-cli}@anchor{2e2}
你還可以從命令列叫用 @ref{aa,,pdb} 來偵錯其他腳本。例如：

@example
python -m pdb [-c command] (-m module | -p pid | pyfile) [args ...]
@end example

當作為模組叫用時，如果被偵錯的程序不正常地退出，pdb 將自動進入事後偵錯。事後偵錯後（或程式正常退出後），pdb 將重新啟動程式。自動重新啟動會保留 pdb 的狀態（例如斷點），並且在大多數情況下比在程式退出時退出偵錯器更有用。

@geindex pdb 命令列選項; -c
@geindex pdb 命令列選項; --command
@anchor{library/pdb cmdoption-pdb-c}@anchor{4680}@anchor{library/pdb cmdoption-pdb-command}@anchor{4681}
@deffn {Option} @w{-}c, @w{-}@w{-}command <command>

就像在 @code{.pdbrc} 檔案中給定的那樣來執行命令；請參閱@ref{4682,,偵錯器命令}。


在 3.2 版的變更: 新增了 @code{-c} 選項。

@end deffn

@geindex pdb 命令列選項; -m
@anchor{library/pdb cmdoption-pdb-m}@anchor{4683}
@deffn {Option} @w{-}m <module>

以類似於 @code{python -m} 的方式來執行模組。與腳本一樣，偵錯器將在模組的第一列之前暫停執行。


在 3.7 版的變更: 新增了 @code{-m} 選項。

@end deffn

@geindex pdb 命令列選項; -p
@geindex pdb 命令列選項; --pid
@anchor{library/pdb cmdoption-pdb-p}@anchor{270}@anchor{library/pdb cmdoption-pdb-pid}@anchor{4684}
@deffn {Option} @w{-}p, @w{-}@w{-}pid <pid>

Attach to the process with the specified PID.


在 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

在偵錯器控制下執行陳述式的典型用法是：

@example
>>> import pdb
>>> def f(x):
...     print(1 / x)
>>> pdb.run("f(2)")
> <string>(1)<module>()
(Pdb) continue
0.5
>>>
@end example

檢查一個損壞程式的典型用法：

@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 版的變更: 
@geindex Python Enhancement Proposals; PEP 667
PEP 667@footnote{https://peps.python.org/pep-0667/} 的實作意味著透過 @code{pdb} 進行的名稱賦予 (name assignments) 會立即影響有效作用域，即使在@ref{49c,,最佳化作用域}內運作也是如此。


本模組定義了下列函式，每個函式進入偵錯器的方式略有不同：

@geindex run() (於 pdb 模組中)
@anchor{library/pdb pdb run}@anchor{4474}
@deffn {函式} pdb.run (statement, globals=None, locals=None)

在偵錯器控制下執行 `statement'（以字串或程式碼物件形式給定）。偵錯提示字元會在執行任何程式碼前出現；你可以設定斷點並輸入 @ref{467f,,continue}，或也可以使用 @ref{4685,,step} 或 @ref{4686,,next} 逐步執行陳述式（這些命令在下面都有說明）。可選引數 `globals' 和 `locals' 指定程式碼執行的環境；預設使用 @ref{1,,__main__} 模組的字典。（請參閱內建函式 @ref{49d,,exec()} 或 @ref{49e,,eval()} 的說明。）
@end deffn

@geindex runeval() (於 pdb 模組中)
@anchor{library/pdb pdb runeval}@anchor{4687}
@deffn {函式} pdb.runeval (expression, globals=None, locals=None)

在偵錯器控制下為 `expression' 求值（以字串或程式碼物件形式給定）。當 @ref{4687,,runeval()} 回傳時，它回傳 `expression' 的值。除此之外，該函式與 @ref{4474,,run()} 類似。
@end deffn

@geindex runcall() (於 pdb 模組中)
@anchor{library/pdb pdb runcall}@anchor{4688}
@deffn {函式} pdb.runcall (function, *args, **kwds)

使用給定的引數呼叫 `function'（只可以是函式或方法物件，不能是字串）。@ref{4688,,runcall()} 回傳的是所呼叫函式的回傳值。偵錯器提示字元將在進入函式後立即出現。
@end deffn

@geindex set_trace() (於 pdb 模組中)
@anchor{library/pdb pdb set_trace}@anchor{272}
@deffn {函式} pdb.set_trace (*, header=None, commands=None)

在呼叫此函式的 stack frame 進入偵錯器。用於在程式中給定之處寫死 (hard-code) 一個斷點，即便該程式碼不在偵錯狀態（如斷言失敗時）。如有給定 `header'，它將在偵錯正要開始前被印出到控制台。如果給定了 `commands' 引數，它會是在偵錯器啟動時要執行的命令清單。


在 3.7 版的變更: 僅限關鍵字引數 `header'。



在 3.13 版的變更: @ref{272,,set_trace()} 將立即進入偵錯器，而不是在下一列要執行的程式碼中。



在 3.14 版被加入: `commands' 引數。

@end deffn

@geindex set_trace_async() (於 pdb 模組中)
@anchor{library/pdb pdb set_trace_async}@anchor{279}
@deffn {函式} awaitable pdb.set_trace_async (*, header=None, commands=None)

async version of @ref{272,,set_trace()}. This function should be used inside an
async function with @ref{18d,,await}.

@example
async def f():
    await pdb.set_trace_async()
@end example

@ref{18d,,await} statements are supported if the debugger is invoked by this function.


在 3.14 版被加入.

@end deffn

@geindex post_mortem() (於 pdb 模組中)
@anchor{library/pdb pdb post_mortem}@anchor{15d1}
@deffn {函式} pdb.post_mortem (t=None)

進入所給定例外或@ref{ce3,,回溯物件}的事後偵錯。如果沒有給定，預設使用目前正在處理的例外，或如果沒有例外則會引發 @code{ValueError}。


在 3.13 版的變更: 新增對例外物件的支援。

@end deffn

@geindex pm() (於 pdb 模組中)
@anchor{library/pdb pdb pm}@anchor{53a}
@deffn {函式} pdb.pm ()

進入在 @ref{6de,,sys.last_exc} 中發現的例外的事後偵錯。
@end deffn

@geindex set_default_backend() (於 pdb 模組中)
@anchor{library/pdb pdb set_default_backend}@anchor{4689}
@deffn {函式} pdb.set_default_backend (backend)

There are two supported backends for pdb: @code{'settrace'} and @code{'monitoring'}.
See @ref{2d5,,bdb.Bdb} for details. The user can set the default backend to
use if none is specified when instantiating @ref{273,,Pdb}. If no backend is
specified, the default is @code{'settrace'}.

@cartouche
@quotation 備註 
@ref{271,,breakpoint()} and @ref{272,,set_trace()} will not be affected by this
function. They always use @code{'monitoring'} backend.
@end quotation
@end cartouche


在 3.14 版被加入.

@end deffn

@geindex get_default_backend() (於 pdb 模組中)
@anchor{library/pdb pdb get_default_backend}@anchor{468a}
@deffn {函式} pdb.get_default_backend ()

Returns the default backend for pdb.


在 3.14 版被加入.

@end deffn

@code{run*} 函式和 @ref{272,,set_trace()} 都是別名，用於實例化 (instantiate) @ref{273,,Pdb} 類別並呼叫同名方法。如果要使用更多功能，則必須自己執行以下操作：

@geindex Pdb (pdb 中的類別)
@anchor{library/pdb pdb Pdb}@anchor{273}
@deffn {類別} pdb.Pdb (completekey='tab', stdin=None, stdout=None, skip=None, nosigint=False, readrc=True, mode=None, backend=None, colorize=False)

@ref{273,,Pdb} 是偵錯器類別。

`completekey'、`stdin' 與 `stdout' 引數會被傳到底層的 @ref{17cc,,cmd.Cmd} 類別；請於該文件閱讀相關敘述。

如果給定 `skip' 引數，則它必須是一個給出 glob 樣式之模組名稱的疊代器。如果遇到匹配這些樣式的模組，偵錯器將不會進入來自該模組的 frame。 @footnote{
一個 frame 是否會被認為源自特定模組是由該 frame 全域性變數中的 @code{__name__} 來決定的。
}

預設情況下，當你發出 @ref{467f,,continue} 命令時，Pdb 會為 SIGINT 訊號（即使用者在控制台上按下 @code{Ctrl}-@code{C} 時會發送的訊號）設定一個處理程式 (handler)，這允許你透過按下 @code{Ctrl}-@code{C} 再次切入偵錯器。如果你希望 Pdb 不影響到 SIGINT 處理程式，請將 `nosigint' 設定為 true。

`readrc' 引數預設為 true，它控制 Pdb 是否從檔案系統載入 .pdbrc 檔案。

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{4689,,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.

啟用追蹤 (tracing) 且帶有 `skip' 引數的呼叫示範：

@example
import pdb; pdb.Pdb(skip=['django.*']).set_trace()
@end example

不帶引數地引發一個@ref{1b70,,稽核事件 (auditing event)} @code{pdb.Pdb}。


在 3.1 版的變更: 新增了 `skip' 參數。



在 3.2 版的變更: 新增了 `nosigint' 參數。以前 SIGINT 處理程式從未被 Pdb 設定過。



在 3.6 版的變更: `readrc' 引數。



在 3.14 版被加入: 新增了 `mode' 引數。



在 3.14 版被加入: 新增了 `backend' 引數。



在 3.14 版被加入: 新增了 `colorize' 引數。



在 3.14 版的變更: Inline breakpoints like @ref{271,,breakpoint()} or @ref{272,,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{468b}
@deffn {方法} run (statement, globals=None, locals=None)
@anchor{library/pdb pdb Pdb runeval}@anchor{468c}
@deffnx {方法} runeval (expression, globals=None, locals=None)
@anchor{library/pdb pdb Pdb runcall}@anchor{468d}
@deffnx {方法} runcall (function, *args, **kwds)
@anchor{library/pdb pdb Pdb set_trace}@anchor{274}
@deffnx {方法} set_trace ()

請見上面關於這些函式的文件說明。
@end deffn
@end deffn

@menu
* 偵錯器命令:: 

@end menu

@node 偵錯器命令,,,pdb --- Python 偵錯器
@anchor{library/pdb debugger-commands}@anchor{4682}@anchor{library/pdb id2}@anchor{468e}
@subsubsection 偵錯器命令


下方列出的是偵錯器能認得的命令。如下所示，大多數命令可以縮寫為一個或兩個字母。如 @code{h(elp)} 表示可以輸入 @code{h} 或 @code{help} 來輸入幫助命令（但不能輸入 @code{he} 或 @code{hel}，也不能是 @code{H} 或 @code{Help} 或 @code{HELP}）。命令的引數必須用空格（空格符 (spaces) 或製表符 (tabs)）分隔。在命令語法中，可選引數被括在方括號 (@code{[]}) 中；使用時請勿輸入方括號。命令語法中的選擇項由豎線 (@code{|}) 分隔。

輸入一個空白列 (blank line) 將重複上次輸入的命令。例外：如果上一個命令是 @ref{468f,,list} 命令，則會列出接下來的 11 列。

偵錯器無法識別的命令將被認為是 Python 陳述式，並以正在偵錯的程式之情境來執行。Python 陳述式也可以用驚嘆號 (@code{!}) 作為前綴，這是檢視正在偵錯之程式的強大方法，甚至可以修改變數或呼叫函式。當此類陳述式發生例外，將印出例外名稱，但偵錯器的狀態不會改變。


在 3.13 版的變更: 現在可以正確辨識並執行前綴為 pdb 命令的運算式/陳述式。


偵錯器有支援設定@ref{4690,,別名}。別名可以有參數，使得偵錯器對被檢查的情境有一定程度的適應性。

在一列中可以輸入多個以 @code{;;} 分隔的命令。（不能使用單個 @code{;}，因為它用於分隔傳遞給 Python 剖析器一列中的多個命令。）切分命令沒運用什麼高深的方式；輸入總是在第一處 @code{;;} 被切分開，即使它位於引號內的字串之中。對於具有雙分號字串的一個變通解法，是使用隱式字串連接 @code{';'@w{'};'} 或 @code{";"";"}。

要設定臨時全域變數，請使用`便利變數 (convenience variable)'。`便利變數'是名稱以 @code{$} 開頭的變數。例如 @code{$foo = 1} 會設定一個全域變數 @code{$foo}，你可以在偵錯器會話 (debugger session) 中使用它。當程式恢復執行時，`便利變數'將被清除，因此與使用 @code{foo = 1} 等普通變數相比，它不太會去干擾你的程式。

共有四個預先設定的`便利變數'：


@itemize *

@item 
@code{$_frame}：目前正在偵錯的 frame

@item 
@code{$_retval}：frame 回傳時的回傳值

@item 
@code{$_exception}：frame 引發例外時的例外

@item 
@code{$_asynctask}: the asyncio task if pdb stops in an async function
@end itemize


在 3.12 版被加入: 新增了`便利變數'功能。



在 3.14 版被加入: 新增了 @code{$_asynctask} 便利變數。


@geindex .pdbrc;file（檔案）
@geindex debugger（偵錯器）;configuration（設定）;file（檔案）

如果 @code{.pdbrc} 檔案存在於使用者的家目錄或目前目錄中，則會使用 @code{'utf-8'} 編碼讀取並執行該檔案，就像在偵錯器提示字元下鍵入該檔案一樣，除了空列和以 @code{#} 開頭的列會被忽略之外。這對於別名設定特別有用。如果兩個檔案都存在，則先讀取家目錄中的檔案，且定義於其中的別名可以被本地檔案覆蓋。


在 3.2 版的變更: @code{.pdbrc} 現在可以包含繼續偵錯的命令，如 @ref{467f,,continue} 或 @ref{4686,,next}。以前檔案中的這些命令是無效的。



在 3.11 版的變更: @code{.pdbrc} 現在使用 @code{'utf-8'} 編碼讀取。以前它是使用系統區域設定編碼讀取的。


@geindex help (pdb command)
@anchor{library/pdb pdbcommand-help}@anchor{4691}
@deffn {Pdbcommand} h(elp) [command]

如不帶引數，印出可用的命令列表。引數為 `command' 時，印出有關該命令的幫助訊息，@code{help pdb} 會顯示完整文件（即 @ref{aa,,pdb} 模組的說明字串 (docstring)）。由於 `command' 引數必須是一個識別字 (identifier)，若要取得 @code{!} 命令的幫助訊息則必須輸入 @code{help exec}。
@end deffn

@geindex where (pdb command)
@anchor{library/pdb pdbcommand-where}@anchor{4692}
@deffn {Pdbcommand} w(here) [count]

印出 stack trace，最新的 frame 會位於底部。如果 `count' 為 0，則印出目前的 frame 條目。如果 `count' 為負數，印出最舊的 `count' 個 frame。如果 `count' 為正數，印出最新的 `count' 個 frame。箭頭（@code{>}）表示目前的 frame，它也決定了大多數命令的情境。


在 3.14 版的變更: `count' argument is added.

@end deffn

@geindex down (pdb command)
@anchor{library/pdb pdbcommand-down}@anchor{4693}
@deffn {Pdbcommand} d(own) [count]

在 stack trace 中，將目前 frame 向下移動 `count' 級（預設為 1 級，移往較新的 frame）。
@end deffn

@geindex up (pdb command)
@anchor{library/pdb pdbcommand-up}@anchor{4694}
@deffn {Pdbcommand} u(p) [count]

在 stack trace 中，將目前 frame 向上移動 `count' 級（預設為 1 級，移向較舊的 frame）。
@end deffn

@geindex break (pdb command)
@anchor{library/pdb pdbcommand-break}@anchor{4695}
@deffn {Pdbcommand} b(reak) [([filename:]lineno | function) [, condition]]

如帶有 `lineno' 引數，則在目前檔案中的 `lineno' 列處設定中斷。列號可以以 `filename' 和冒號為前綴，以指定另一個檔案（可能是尚未載入的檔案）中的斷點。該檔案會在 @ref{3e2,,sys.path} 上搜尋。可接受的 `filename' 形式為 @code{/abspath/to/file.py}、@code{relpath/file.py}、@code{module} 和 @code{package.module}。

如帶有 `function' 引數，在該函式內的第一個可執行陳述式處設定中斷。`function' 可以是任何其求值結果為目前命名空間中函式的運算式。

如果第二個引數存在，它是一個運算式，在斷點生效前其必須求值為 true

如果不帶引數執行會列出所有斷點資訊，包括每個斷點、命中該斷點的次數、目前的忽略次數以及關聯的條件（如存在）。

每個斷點都有賦予一個編號，所有其他斷點命令都參照該編號。
@end deffn

@geindex tbreak (pdb command)
@anchor{library/pdb pdbcommand-tbreak}@anchor{4696}
@deffn {Pdbcommand} tbreak [([filename:]lineno | function) [, condition]]

臨時斷點，在第一次遇見時會自動被刪除。它的引數與 @ref{4695,,break} 相同。
@end deffn

@geindex clear (pdb command)
@anchor{library/pdb pdbcommand-clear}@anchor{4697}
@deffn {Pdbcommand} cl(ear) [filename:lineno | bpnumber ...]

如帶有 `filename:lineno' 引數，則清除此列上的所有斷點。如果引數是空格分隔的斷點編號列表，則清除這些斷點。如果不帶引數則清除所有斷點（但會先提示確認）。
@end deffn

@geindex disable (pdb command)
@anchor{library/pdb pdbcommand-disable}@anchor{4698}
@deffn {Pdbcommand} disable bpnumber [bpnumber ...]

停用斷點，斷點以空格分隔的斷點編號列表來給定。停用斷點表示它不會導致程式停止執行，但是與清除斷點不同，停用的斷點將保留在斷點列表中並且可以（重新）啟用。
@end deffn

@geindex enable (pdb command)
@anchor{library/pdb pdbcommand-enable}@anchor{4699}
@deffn {Pdbcommand} enable bpnumber [bpnumber ...]

啟用指定的斷點。
@end deffn

@geindex ignore (pdb command)
@anchor{library/pdb pdbcommand-ignore}@anchor{469a}
@deffn {Pdbcommand} ignore bpnumber [count]

為給定的斷點編號設定忽略計數。如果省略 `count' 則忽略計數設定為 0。當忽略計數為 0 時，斷點將變為有效狀態。當非 0 時，每次到達斷點，且斷點沒有被禁用，且任何關聯的條件被求值為 true，則 `count' 就會遞減。
@end deffn

@geindex condition (pdb command)
@anchor{library/pdb pdbcommand-condition}@anchor{469b}
@deffn {Pdbcommand} condition bpnumber [condition]

為斷點設定一個新 `condition'，為一個運算式，且其求值結果為 true 時斷點才會起作用。如果沒有給定 `condition'，則刪除任何現有條件，也就是不為斷點設定條件。
@end deffn

@geindex commands (pdb command)
@anchor{library/pdb pdbcommand-commands}@anchor{276}
@deffn {Pdbcommand} commands [bpnumber]

為編號是 `bpnumber' 的斷點指定一系列命令。命令內容出現在後續的幾列中。輸入僅包含 @code{end} 的一列來結束命令列表。例如：

@example
(Pdb) commands 1
(com) p some_variable
(com) end
(Pdb)
@end example

要刪除斷點上的所有命令，請輸入 @code{commands} 並立即以 @code{end} 結尾，也就是不指定任何命令。

不帶有 `bpnumber' 引數則 @code{commands} 會關聯到上一個設定的斷點。

可以使用斷點命令來重新啟動程式，只需使用 @ref{467f,,continue} 或 @ref{4685,,step} 命令，或其他可以繼續執行程式的命令。

如果指定了某個繼續執行程式的命令（目前包括 @ref{467f,,continue}、@ref{4685,,step}、@ref{4686,,next}、@ref{469c,,return}、@ref{469d,,until}、@ref{469e,,jump}、@ref{469f,,quit} 及它們的縮寫）將終止命令列表（就像該命令後馬上跟著 end）。因為在任何時候繼續執行下去（即使是簡單的 next 或 step），都可能會遇到另一個斷點，該斷點可能具有自己的命令列表，這會導致無法確定要執行哪個列表。

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{4685}
@deffn {Pdbcommand} s(tep)

執行目前列，在第一個可以停止的位置（在被呼叫的函式內部或在目前函式的下一列）停止。
@end deffn

@geindex next (pdb command)
@anchor{library/pdb pdbcommand-next}@anchor{4686}
@deffn {Pdbcommand} n(ext)

繼續執行，直至執行到目前函式的下一列或者目前函式回傳為止。（@ref{4686,,next} 和 @ref{4685,,step} 之間的區別在於 @ref{4685,,step} 會在被呼叫函式的內部停止、而 @ref{4686,,next}（幾乎）全速執行被呼叫的函式，並僅在目前函式的下一列停止。）
@end deffn

@geindex until (pdb command)
@anchor{library/pdb pdbcommand-until}@anchor{469d}
@deffn {Pdbcommand} unt(il) [lineno]

如果不帶引數則繼續執行，直到列號比目前的列大時停止。

如帶有 `lineno' 則繼續執行，直到到達列號大於或等於 `lineno' 的那一列。在這兩種情況下，目前 frame 回傳時也會停止。


在 3.2 版的變更: 允許明確給定一個列號。

@end deffn

@geindex return (pdb command)
@anchor{library/pdb pdbcommand-return}@anchor{469c}
@deffn {Pdbcommand} r(eturn)

繼續執行，直到目前的函式回傳。
@end deffn

@geindex continue (pdb command)
@anchor{library/pdb pdbcommand-continue}@anchor{467f}
@deffn {Pdbcommand} c(ont(inue))

繼續執行，除非遇到斷點才停下來。
@end deffn

@geindex jump (pdb command)
@anchor{library/pdb pdbcommand-jump}@anchor{469e}
@deffn {Pdbcommand} j(ump) lineno

設定即將執行的下一列，僅可用於堆疊中最底部的 frame。這讓你可以跳回去並再次執行程式碼，或者往前跳以跳過不想執行的程式碼。

需要注意的是，不是所有的跳轉都是被允許的 -- 例如不能跳轉到 @ref{348,,for} 迴圈的中間或跳出 @ref{1b0,,finally} 子句。
@end deffn

@geindex list (pdb command)
@anchor{library/pdb pdbcommand-list}@anchor{468f}
@deffn {Pdbcommand} l(ist) [first[, last]]

列出目前檔案的原始碼。如果不帶引數，則列出目前列周圍的 11 列，或繼續先前的列表操作。如果用 @code{.} 作為引數，則列出目前列周圍的 11 列。如果帶有一個引數，則列出那一列周圍的 11 列。如果帶有兩個引數，則列出給定範圍中的程式碼；如果第二個引數小於第一個引數，則將其直譯為要列出的列數。

目前 frame 中的目前列會用 @code{->} 標記出來。如果正在偵錯一個例外，且引發或傳遞該例外的那一列不是目前列，則會用 @code{>>} 來標記該列。


在 3.2 版的變更: 新增了 @code{>>} 標記。

@end deffn

@geindex ll (pdb command)
@anchor{library/pdb pdbcommand-ll}@anchor{46a0}
@deffn {Pdbcommand} ll | longlist

列出目前函式或 frame 的所有原始碼。相關列的標記方式與 @ref{468f,,list} 相同。


在 3.2 版被加入.

@end deffn

@geindex args (pdb command)
@anchor{library/pdb pdbcommand-args}@anchor{46a1}
@deffn {Pdbcommand} a(rgs)

印出目前函式的引數及它們目前的值。
@end deffn

@geindex p (pdb command)
@anchor{library/pdb pdbcommand-p}@anchor{1171}
@deffn {Pdbcommand} p expression

在目前情境中為 `expression' 求值並印出其值。

@cartouche
@quotation 備註 
也可以使用 @code{print()}，但它不是一個偵錯器命令 --- 它會執行 Python @ref{1170,,print()} 函式。
@end quotation
@end cartouche
@end deffn

@geindex pp (pdb command)
@anchor{library/pdb pdbcommand-pp}@anchor{46a2}
@deffn {Pdbcommand} pp expression

與 @ref{1171,,p} 命令類似，除了 `expression' 的值是使用 @ref{b3,,pprint} 模組美化後印出來的。
@end deffn

@geindex whatis (pdb command)
@anchor{library/pdb pdbcommand-whatis}@anchor{46a3}
@deffn {Pdbcommand} whatis expression

印出 `expression' 的型別。
@end deffn

@geindex source (pdb command)
@anchor{library/pdb pdbcommand-source}@anchor{46a4}
@deffn {Pdbcommand} source expression

嘗試取得 `expression' 的原始碼並顯示它。


在 3.2 版被加入.

@end deffn

@geindex display (pdb command)
@anchor{library/pdb pdbcommand-display}@anchor{275}
@deffn {Pdbcommand} display [expression]

每次在目前 frame 中停止執行時，顯示 `expression' 的值（如果有變更）。

如果不帶有 `expression'，則列出目前 frame 的所有運算式。

@cartouche
@quotation 備註 
display 會對 `expression' 求值並將結果與之前 `expression' 的求值結果進行比較，因此當結果可變時，display 可能無法取得其變更。
@end quotation
@end cartouche

範例如下：

@example
lst = []
breakpoint()
pass
lst.append(1)
print(lst)
@end example

display 不會意識到 @code{lst} 已更改，因為其求值結果在比較之前已被 @code{lst.append(1)} 原地 (in place) 修改：

@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

你可以運用複製機制的一些技巧來使其能夠運作：

@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


在 3.2 版被加入.

@end deffn

@geindex undisplay (pdb command)
@anchor{library/pdb pdbcommand-undisplay}@anchor{46a5}
@deffn {Pdbcommand} undisplay [expression]

不再顯示目前 frame 中的 `expression'。如果不帶有 `expression'，則清除目前 frame 的所有顯示運算式。


在 3.2 版被加入.

@end deffn

@geindex interact (pdb command)
@anchor{library/pdb pdbcommand-interact}@anchor{46a6}
@deffn {Pdbcommand} interact

在從目前作用域的區域和全域命名空間初始化的新全域命名空間中啟動互動式直譯器（使用 @ref{1b,,code} 模組）。可使用 @code{exit()} 或 @code{quit()} 退出直譯器並回到偵錯器。

@cartouche
@quotation 備註 
由於 @code{interact} 為程式碼執行建立了一個新的專用命名空間，因此變數的賦值不會影響原始命名空間，但是對任何被參照的可變物件的修改將像往常一樣反映在原始命名空間中。
@end quotation
@end cartouche


在 3.2 版被加入.



在 3.13 版的變更: @code{exit()} 和 @code{quit()} 可用來退出 @ref{46a6,,interact} 命令。



在 3.13 版的變更: @ref{46a6,,interact} 將其輸出導向到偵錯器的輸出通道 (output channel)，而不是 @ref{b2a,,sys.stderr}。

@end deffn

@geindex alias (pdb command)
@anchor{library/pdb debugger-aliases}@anchor{4690}@anchor{library/pdb pdbcommand-alias}@anchor{46a7}
@deffn {Pdbcommand} alias [name [command]]

建立一個名為 `name' 的別名，用於執行 `command'。`command' `不得'用引號包起來。可被替換的參數要用 @code{%1}、@code{%2}、 ... 和 @code{%9} 標示，而 @code{%*} 則被所有參數替換。如果省略 `command'，則顯示 `name' 的目前別名。如果未給定引數，則列出所有別名。

巢狀別名是允許的，且可包含能在 pdb 提示字元下合法輸入的任何內容。請注意，內部 pdb 命令`可以'被別名所覆蓋。這樣的命令在別名被移除前都將被隱藏。別名會遞迴地應用到命令列的第一個單詞；該列內的其他單詞則不會受影響。

作為範例，這裡列出了兩個有用的別名（特別是放在 @code{.pdbrc} 檔案中時）：

@example
# 印出實例變數（用法如 "pi classInst"）
alias pi for k in %1.__dict__.keys(): print(f"%1.@{k@} = @{%1.__dict__[k]@}")
# 印出 self 中的實例變數
alias ps pi self
@end example
@end deffn

@geindex unalias (pdb command)
@anchor{library/pdb pdbcommand-unalias}@anchor{46a8}
@deffn {Pdbcommand} unalias name

刪除指定的別名 `name'。
@end deffn

@geindex ! (pdb command)
@anchor{library/pdb pdbcommand-0}@anchor{46a9}
@deffn {Pdbcommand} ! statement

在目前 stack frame 的情境中執行（單列）`statement'。除非陳述式的第一個單詞類似於偵錯器命令，否則可以省略驚嘆號，例如：

@example
(Pdb) ! n=42
(Pdb)
@end example

要設定全域變數，你可以在同一列的賦值命令前面加上 @ref{4a7,,global} 陳述式，例如：

@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{46aa}
@deffn {Pdbcommand} run [args ...]
@anchor{library/pdb pdbcommand-restart}@anchor{46ab}
@deffnx {Pdbcommand} restart [args ...]

重新啟動已偵錯完畢的 Python 程式。如果提供了 `args'，它將以 @ref{c9,,shlex} 分割，並將結果用作新的 @ref{1465,,sys.argv}。歷史記錄、斷點、操作和偵錯器選項均會被保留。@ref{46ab,,restart} 是 @ref{46aa,,run} 的別名。


在 3.14 版的變更: @ref{46aa,,run} and @ref{46ab,,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{469f}
@deffn {Pdbcommand} q(uit)

離開偵錯器，執行中的程式會被中止。輸入檔案結尾 (end-of-file) 相當於 @ref{469f,,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{277,,sys.exit()} immediately, instead of raising @ref{278,,bdb.BdbQuit}
in the next trace event.

@end deffn

@geindex debug (pdb command)
@anchor{library/pdb pdbcommand-debug}@anchor{46ac}
@deffn {Pdbcommand} debug code

進入一個遞迴偵錯器，逐步執行 `code'（這是要在目前環境中執行的任意運算式或陳述式）。
@end deffn

@geindex retval (pdb command)
@anchor{library/pdb pdbcommand-retval}@anchor{46ad}
@deffn {Pdbcommand} retval

印出目前函式最後一次回傳的回傳值。
@end deffn

@geindex exceptions (pdb command)
@anchor{library/pdb pdbcommand-exceptions}@anchor{53b}
@deffn {Pdbcommand} exceptions [excnumber]

列出鏈接例外 (chained exceptions)，或在其間跳轉。

當使用 @code{pdb.pm()} 或 @code{Pdb.post_mortem(...)} 於鏈接例外而不是回溯時，它允許使用者在鏈接例外之間移動，使用 @code{exceptions} 命令以列出例外，並使用 @code{exceptions <number>} 切換到該例外。

範例如下：

@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

呼叫 @code{pdb.pm()} 將允許在例外之間移動：

@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


在 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 的分析器,timeit --- 測量小量程式片段的執行時間,pdb --- Python 偵錯器,除錯與效能分析
@anchor{library/profile doc}@anchor{46ae}@anchor{library/profile profile}@anchor{46af}@anchor{library/profile the-python-profilers}@anchor{46b0}@anchor{library/profile translation-repo}@anchor{46b1}
@subsection Python 的分析器


`原始碼：'Lib/profile.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/profile.py} 與 Lib/pstats.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/pstats.py}


__________________________________________________________________


@menu
* 分析器簡介:: 
* Instant User's Manual:: 
* profile 與 cProfile 模組參考文件:: 
* Stats 類別:: 
* What Is Deterministic Profiling?:: 
* 限制:: 
* 校正:: 
* Using a custom timer:: 

@end menu

@node 分析器簡介,Instant User's Manual,,Python 的分析器
@anchor{library/profile introduction-to-the-profilers}@anchor{46b2}@anchor{library/profile profiler-introduction}@anchor{46b3}
@subsubsection 分析器簡介


@geindex deterministic profiling
@geindex profiling@comma{} deterministic

@ref{2b,,cProfile} and @ref{b4,,profile} provide `deterministic profiling' of
Python programs. A `profile' is a set of statistics that describes how
often and for how long various parts of the program executed. These statistics
can be formatted into reports via the @ref{b5,,pstats} module.

The Python standard library provides two different implementations of the same
profiling interface:


@enumerate 

@item 
@ref{2b,,cProfile} is recommended for most users; it's a C extension with
reasonable overhead that makes it suitable for profiling long-running
programs.  Based on @code{lsprof}, contributed by Brett Rosen and Ted
Czotter.

@item 
@ref{b4,,profile}, a pure Python module whose interface is imitated by
@ref{2b,,cProfile}, but which adds significant overhead to profiled programs.
If you're trying to extend the profiler in some way, the task might be easier
with this module.  Originally designed and written by Jim Roskind.
@end enumerate

@cartouche
@quotation 備註 
The profiler modules are designed to provide an execution profile for a given
program, not for benchmarking purposes (for that, there is @ref{f5,,timeit} for
reasonably accurate results).  This particularly applies to benchmarking
Python code against C code: the profilers introduce overhead for Python code,
but not for C-level functions, and so the C code would seem faster than any
Python one.
@end quotation
@end cartouche

@node Instant User's Manual,profile 與 cProfile 模組參考文件,分析器簡介,Python 的分析器
@anchor{library/profile instant-user-s-manual}@anchor{46b4}@anchor{library/profile profile-instant}@anchor{46b5}
@subsubsection Instant User's Manual


This section is provided for users that "don't want to read the manual." It
provides a very brief overview, and allows a user to rapidly perform profiling
on an existing application.

To profile a function that takes a single argument, you can do:

@example
import cProfile
import re
cProfile.run('re.compile("foo|bar")')
@end example

(Use @ref{b4,,profile} instead of @ref{2b,,cProfile} if the latter is not available on
your system.)

The above action would run @ref{dc9,,re.compile()} and print profile results like
the following:

@example
      214 function calls (207 primitive calls) in 0.002 seconds

Ordered by: cumulative time

ncalls  tottime  percall  cumtime  percall filename:lineno(function)
     1    0.000    0.000    0.002    0.002 @{built-in method builtins.exec@}
     1    0.000    0.000    0.001    0.001 <string>:1(<module>)
     1    0.000    0.000    0.001    0.001 __init__.py:250(compile)
     1    0.000    0.000    0.001    0.001 __init__.py:289(_compile)
     1    0.000    0.000    0.000    0.000 _compiler.py:759(compile)
     1    0.000    0.000    0.000    0.000 _parser.py:937(parse)
     1    0.000    0.000    0.000    0.000 _compiler.py:598(_code)
     1    0.000    0.000    0.000    0.000 _parser.py:435(_parse_sub)
@end example

The first line indicates that 214 calls were monitored.  Of those calls, 207
were `primitive', meaning that the call was not induced via recursion. The
next line: @code{Ordered by: cumulative time} indicates the output is sorted
by the @code{cumtime} values. The column headings include:


@table @asis

@item ncalls

for the number of calls.

@item tottime

for the total time spent in the given function (and excluding time made in
calls to sub-functions)

@item percall

is the quotient of @code{tottime} divided by @code{ncalls}

@item cumtime

is the cumulative time spent in this and all subfunctions (from invocation
till exit). This figure is accurate `even' for recursive functions.

@item percall

is the quotient of @code{cumtime} divided by primitive calls

@item filename:lineno(function)

provides the respective data of each function
@end table

When there are two numbers in the first column (for example @code{3/1}), it means
that the function recursed.  The second value is the number of primitive calls
and the former is the total number of calls.  Note that when the function does
not recurse, these two values are the same, and only the single figure is
printed.

Instead of printing the output at the end of the profile run, you can save the
results to a file by specifying a filename to the @code{run()} function:

@example
import cProfile
import re
cProfile.run('re.compile("foo|bar")', 'restats')
@end example

The @ref{46b6,,pstats.Stats} class reads profile results from a file and formats
them in various ways.
@anchor{library/profile profile-cli}@anchor{46b7}
The files @ref{2b,,cProfile} and @ref{b4,,profile} can also be invoked as a script to
profile another script.  For example:

@example
python -m cProfile [-o output_file] [-s sort_order] (-m module | myscript.py)
@end example

@geindex cProfile 命令列選項; -o
@anchor{library/profile cmdoption-cProfile-o}@anchor{46b8}
@deffn {Option} @w{-}o <output_file>

Writes the profile results to a file instead of to stdout.
@end deffn

@geindex cProfile 命令列選項; -s
@anchor{library/profile cmdoption-cProfile-s}@anchor{46b9}
@deffn {Option} @w{-}s <sort_order>

Specifies one of the @ref{46ba,,sort_stats()} sort values
to sort the output by.
This only applies when @ref{46b8,,-o} is not supplied.
@end deffn

@geindex cProfile 命令列選項; -m
@anchor{library/profile cmdoption-cProfile-m}@anchor{46bb}
@deffn {Option} @w{-}m <module>

Specifies that a module is being profiled instead of a script.


在 3.7 版被加入: 新增 @code{-m} 選項到 @ref{2b,,cProfile}。



在 3.8 版被加入: 新增 @code{-m} 選項到 @ref{b4,,profile}。

@end deffn

The @ref{b5,,pstats} module's @ref{46b6,,Stats} class has a variety of methods
for manipulating and printing the data saved into a profile results file:

@example
import pstats
from pstats import SortKey
p = pstats.Stats('restats')
p.strip_dirs().sort_stats(-1).print_stats()
@end example

The @ref{46bc,,strip_dirs()} method removed the extraneous path from all
the module names. The @ref{46ba,,sort_stats()} method sorted all the
entries according to the standard module/line/name string that is printed. The
@ref{46bd,,print_stats()} method printed out all the statistics.  You
might try the following sort calls:

@example
p.sort_stats(SortKey.NAME)
p.print_stats()
@end example

The first call will actually sort the list by function name, and the second call
will print out the statistics.  The following are some interesting calls to
experiment with:

@example
p.sort_stats(SortKey.CUMULATIVE).print_stats(10)
@end example

This sorts the profile by cumulative time in a function, and then only prints
the ten most significant lines.  If you want to understand what algorithms are
taking time, the above line is what you would use.

If you were looking to see what functions were looping a lot, and taking a lot
of time, you would do:

@example
p.sort_stats(SortKey.TIME).print_stats(10)
@end example

to sort according to time spent within each function, and then print the
statistics for the top ten functions.

You might also try:

@example
p.sort_stats(SortKey.FILENAME).print_stats('__init__')
@end example

This will sort all the statistics by file name, and then print out statistics
for only the class init methods (since they are spelled with @code{__init__} in
them).  As one final example, you could try:

@example
p.sort_stats(SortKey.TIME, SortKey.CUMULATIVE).print_stats(.5, 'init')
@end example

This line sorts statistics with a primary key of time, and a secondary key of
cumulative time, and then prints out some of the statistics. To be specific, the
list is first culled down to 50% (re: @code{.5}) of its original size, then only
lines containing @code{init} are maintained, and that sub-sub-list is printed.

If you wondered what functions called the above functions, you could now (@code{p}
is still sorted according to the last criteria) do:

@example
p.print_callers(.5, 'init')
@end example

and you would get a list of callers for each of the listed functions.

If you want more functionality, you're going to have to read the manual, or
guess what the following functions do:

@example
p.print_callees()
p.add('restats')
@end example

Invoked as a script, the @ref{b5,,pstats} module is a statistics browser for
reading and examining profile dumps.  It has a simple line-oriented interface
(implemented using @ref{1a,,cmd}) and interactive help.

@node profile 與 cProfile 模組參考文件,Stats 類別,Instant User's Manual,Python 的分析器
@anchor{library/profile module-cProfile}@anchor{2b}@anchor{library/profile profile-and-cprofile-module-reference}@anchor{46be}
@subsubsection @code{profile} 與 @code{cProfile} 模組參考文件


@geindex module; cProfile

@geindex module; profile
@anchor{library/profile module-profile}@anchor{b4}
Both the @ref{b4,,profile} and @ref{2b,,cProfile} modules provide the following
functions:

@geindex run() (於 profile 模組中)
@anchor{library/profile profile run}@anchor{46bf}
@deffn {函式} profile.run (command, filename=None, sort=-1)

This function takes a single argument that can be passed to the @ref{49d,,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{46b6,,Stats}
instance and prints a simple profiling report. If the sort value is specified,
it is passed to this @ref{46b6,,Stats} instance to control how the
results are sorted.
@end deffn

@geindex runctx() (於 profile 模組中)
@anchor{library/profile profile runctx}@anchor{46c0}
@deffn {函式} profile.runctx (command, globals, locals, filename=None, sort=-1)

This function is similar to @ref{46bf,,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{46bf,,run()} function above.
@end deffn

@geindex Profile (profile 中的類別)
@anchor{library/profile profile Profile}@anchor{bcd}
@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 @code{cProfile.run()} function provides.

A custom timer can be supplied for measuring how long code takes to run via
the `timer' argument. This must be a function that returns a single number
representing the current time. If the number is an integer, the `timeunit'
specifies a multiplier that specifies the duration of each unit of time. For
example, if the timer returns times measured in thousands of seconds, the
time unit would be @code{.001}.

Directly using the @ref{bcd,,Profile} class allows formatting profile results
without writing the profile data to a file:

@example
import cProfile, pstats, io
from pstats import SortKey
pr = cProfile.Profile()
pr.enable()
# ... do something ...
pr.disable()
s = io.StringIO()
sortby = SortKey.CUMULATIVE
ps = pstats.Stats(pr, stream=s).sort_stats(sortby)
ps.print_stats()
print(s.getvalue())
@end example

The @ref{bcd,,Profile} class can also be used as a context manager (supported
only in @ref{2b,,cProfile} module. see @ref{22bc,,情境管理器型別}):

@example
import cProfile

with cProfile.Profile() as pr:
    # ... do something ...

    pr.print_stats()
@end example


在 3.8 版的變更: 新增情境管理器的支援。


@geindex enable() (profile.Profile 的方法)
@anchor{library/profile profile Profile enable}@anchor{46c1}
@deffn {方法} enable ()

Start collecting profiling data. Only in @ref{2b,,cProfile}.
@end deffn

@geindex disable() (profile.Profile 的方法)
@anchor{library/profile profile Profile disable}@anchor{46c2}
@deffn {方法} disable ()

Stop collecting profiling data. Only in @ref{2b,,cProfile}.
@end deffn

@geindex create_stats() (profile.Profile 的方法)
@anchor{library/profile profile Profile create_stats}@anchor{46c3}
@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{46c4}
@deffn {方法} print_stats (sort=-1)

Create a @ref{46b6,,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{46ba,,Stats.sort_stats}.


在 3.13 版被加入: @ref{46c4,,print_stats()} now accepts a tuple of keys.

@end deffn

@geindex dump_stats() (profile.Profile 的方法)
@anchor{library/profile profile Profile dump_stats}@anchor{46c5}
@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{46c6}
@deffn {方法} run (cmd)

Profile the cmd via @ref{49d,,exec()}.
@end deffn

@geindex runctx() (profile.Profile 的方法)
@anchor{library/profile profile Profile runctx}@anchor{46c7}
@deffn {方法} runctx (cmd, globals, locals)

Profile the cmd via @ref{49d,,exec()} with the specified global and
local environment.
@end deffn

@geindex runcall() (profile.Profile 的方法)
@anchor{library/profile profile Profile runcall}@anchor{c67}
@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{277,,sys.exit()} call
during the called command/function execution) no profiling results will be
printed.

@node Stats 類別,What Is Deterministic Profiling?,profile 與 cProfile 模組參考文件,Python 的分析器
@anchor{library/profile profile-stats}@anchor{46c8}@anchor{library/profile the-stats-class}@anchor{46c9}
@subsubsection @code{Stats} 類別


Analysis of the profiler data is done using the @ref{46b6,,Stats} class.

@geindex module; pstats

@geindex Stats (pstats 中的類別)
@anchor{library/profile module-pstats}@anchor{b5}@anchor{library/profile pstats Stats}@anchor{46b6}
@deffn {類別} pstats.Stats (*filenames or profile, stream=sys.stdout)

This class constructor creates an instance of a "statistics object" from a
`filename' (or list of filenames) or from a @code{Profile} instance. Output
will be printed to the stream specified by `stream'.

The file selected by the above constructor must have been created by the
corresponding version of @ref{b4,,profile} or @ref{2b,,cProfile}.  To be specific,
there is `no' file compatibility guaranteed with future versions of this
profiler, and there is no compatibility with files produced by other
profilers, or the same profiler run on a different operating system.  If
several files are provided, all the statistics for identical functions will
be coalesced, so that an overall view of several processes can be considered
in a single report.  If additional files need to be combined with data in an
existing @ref{46b6,,Stats} object, the @ref{46ca,,add()} method
can be used.

Instead of reading the profile data from a file, a @code{cProfile.Profile}
or @ref{bcd,,profile.Profile} object can be used as the profile data source.

@ref{46b6,,Stats} 物件有以下方法：

@geindex strip_dirs() (pstats.Stats 的方法)
@anchor{library/profile pstats Stats strip_dirs}@anchor{46bc}
@deffn {方法} strip_dirs ()

This method for the @ref{46b6,,Stats} class removes all leading path
information from file names.  It is very useful in reducing the size of
the printout to fit within (close to) 80 columns.  This method modifies
the object, and the stripped information is lost.  After performing a
strip operation, the object is considered to have its entries in a
"random" order, as it was just after object initialization and loading.
If @ref{46bc,,strip_dirs()} causes two function names to be
indistinguishable (they are on the same line of the same filename, and
have the same function name), then the statistics for these two entries
are accumulated into a single entry.
@end deffn

@geindex add() (pstats.Stats 的方法)
@anchor{library/profile pstats Stats add}@anchor{46ca}
@deffn {方法} add (*filenames)

This method of the @ref{46b6,,Stats} class accumulates additional profiling
information into the current profiling object.  Its arguments should refer
to filenames created by the corresponding version of @ref{46bf,,profile.run()}
or @code{cProfile.run()}. Statistics for identically named (re: file, line,
name) functions are automatically accumulated into single function
statistics.
@end deffn

@geindex dump_stats() (pstats.Stats 的方法)
@anchor{library/profile pstats Stats dump_stats}@anchor{46cb}
@deffn {方法} dump_stats (filename)

Save the data loaded into the @ref{46b6,,Stats} object to a file named
`filename'.  The file is created if it does not exist, and is overwritten
if it already exists.  This is equivalent to the method of the same name
on the @ref{bcd,,profile.Profile} and @code{cProfile.Profile} classes.
@end deffn

@geindex sort_stats() (pstats.Stats 的方法)
@anchor{library/profile pstats Stats sort_stats}@anchor{46ba}
@deffn {方法} sort_stats (*keys)

This method modifies the @ref{46b6,,Stats} object by sorting it according to
the supplied criteria.  The argument can be either a string or a SortKey
enum identifying the basis of a sort (example: @code{'time'}, @code{'name'},
@code{SortKey.TIME} or @code{SortKey.NAME}). The SortKey enums argument have
advantage over the string argument in that it is more robust and less
error prone.

When more than one key is provided, then additional keys are used as
secondary criteria when there is equality in all keys selected before
them.  For example, @code{sort_stats(SortKey.NAME, SortKey.FILE)} will sort
all the entries according to their function name, and resolve all ties
(identical function names) by sorting by file name.

For the string argument, abbreviations can be used for any key names, as
long as the abbreviation is unambiguous.

The following are the valid string and SortKey:


@multitable {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Valid String Arg

@tab

Valid enum Arg

@tab

含義

@item

@code{'calls'}

@tab

SortKey.CALLS

@tab

call count

@item

@code{'cumulative'}

@tab

SortKey.CUMULATIVE

@tab

cumulative time

@item

@code{'cumtime'}

@tab

N/A

@tab

cumulative time

@item

@code{'file'}

@tab

N/A

@tab

file name（檔案名稱）

@item

@code{'filename'}

@tab

SortKey.FILENAME

@tab

file name（檔案名稱）

@item

@code{'module'}

@tab

N/A

@tab

file name（檔案名稱）

@item

@code{'ncalls'}

@tab

N/A

@tab

call count

@item

@code{'pcalls'}

@tab

SortKey.PCALLS

@tab

primitive call count

@item

@code{'line'}

@tab

SortKey.LINE

@tab

列號

@item

@code{'name'}

@tab

SortKey.NAME

@tab

function name

@item

@code{'nfl'}

@tab

SortKey.NFL

@tab

name/file/line

@item

@code{'stdname'}

@tab

SortKey.STDNAME

@tab

standard name

@item

@code{'time'}

@tab

SortKey.TIME

@tab

internal time

@item

@code{'tottime'}

@tab

N/A

@tab

internal time

@end multitable


Note that all sorts on statistics are in descending order (placing most
time consuming items first), where as name, file, and line number searches
are in ascending order (alphabetical). The subtle distinction between
@code{SortKey.NFL} and @code{SortKey.STDNAME} is that the standard name is a
sort of the name as printed, which means that the embedded line numbers
get compared in an odd way.  For example, lines 3, 20, and 40 would (if
the file names were the same) appear in the string order 20, 3 and 40.
In contrast, @code{SortKey.NFL} does a numeric compare of the line numbers.
In fact, @code{sort_stats(SortKey.NFL)} is the same as
@code{sort_stats(SortKey.NAME, SortKey.FILENAME, SortKey.LINE)}.

For backward-compatibility reasons, the numeric arguments @code{-1}, @code{0},
@code{1}, and @code{2} are permitted.  They are interpreted as @code{'stdname'},
@code{'calls'}, @code{'time'}, and @code{'cumulative'} respectively.  If this old
style format (numeric) is used, only one sort key (the numeric key) will
be used, and additional arguments will be silently ignored.

@c For compatibility with the old profiler.


在 3.7 版被加入: Added the SortKey enum.

@end deffn

@geindex reverse_order() (pstats.Stats 的方法)
@anchor{library/profile pstats Stats reverse_order}@anchor{46cc}
@deffn {方法} reverse_order ()

This method for the @ref{46b6,,Stats} class reverses the ordering of the
basic list within the object.  Note that by default ascending vs
descending order is properly selected based on the sort key of choice.

@c This method is provided primarily for compatibility with the old
@c profiler.
@end deffn

@geindex print_stats() (pstats.Stats 的方法)
@anchor{library/profile pstats Stats print_stats}@anchor{46bd}
@deffn {方法} print_stats (*restrictions)

This method for the @ref{46b6,,Stats} class prints out a report as described
in the @ref{46bf,,profile.run()} definition.

The order of the printing is based on the last
@ref{46ba,,sort_stats()} operation done on the object (subject to
caveats in @ref{46ca,,add()} and
@ref{46bc,,strip_dirs()}).

The arguments provided (if any) can be used to limit the list down to the
significant entries.  Initially, the list is taken to be the complete set
of profiled functions.  Each restriction is either an integer (to select a
count of lines), or a decimal fraction between 0.0 and 1.0 inclusive (to
select a percentage of lines), or a string that will be interpreted as a
regular expression (to pattern match the standard name that is printed).
If several restrictions are provided, then they are applied sequentially.
For example:

@example
print_stats(.1, 'foo:')
@end example

would first limit the printing to first 10% of list, and then only print
functions that were part of filename @code{.*foo:}.  In contrast, the
command:

@example
print_stats('foo:', .1)
@end example

would limit the list to all functions having file names @code{.*foo:},
and then proceed to only print the first 10% of them.
@end deffn

@geindex print_callers() (pstats.Stats 的方法)
@anchor{library/profile pstats Stats print_callers}@anchor{46cd}
@deffn {方法} print_callers (*restrictions)

This method for the @ref{46b6,,Stats} class prints a list of all functions
that called each function in the profiled database.  The ordering is
identical to that provided by @ref{46bd,,print_stats()}, and the
definition of the restricting argument is also identical.  Each caller is
reported on its own line.  The format differs slightly depending on the
profiler that produced the stats:


@itemize *

@item 
With @ref{b4,,profile}, a number is shown in parentheses after each caller
to show how many times this specific call was made.  For convenience, a
second non-parenthesized number repeats the cumulative time spent in the
function at the right.

@item 
With @ref{2b,,cProfile}, each caller is preceded by three numbers: the
number of times this specific call was made, and the total and
cumulative times spent in the current function while it was invoked by
this specific caller.
@end itemize
@end deffn

@geindex print_callees() (pstats.Stats 的方法)
@anchor{library/profile pstats Stats print_callees}@anchor{46ce}
@deffn {方法} print_callees (*restrictions)

This method for the @ref{46b6,,Stats} class prints a list of all function
that were called by the indicated function.  Aside from this reversal of
direction of calls (re: called vs was called by), the arguments and
ordering are identical to the @ref{46cd,,print_callers()} method.
@end deffn

@geindex get_stats_profile() (pstats.Stats 的方法)
@anchor{library/profile pstats Stats get_stats_profile}@anchor{46cf}
@deffn {方法} get_stats_profile ()

This method returns an instance of StatsProfile, which contains a mapping
of function names to instances of FunctionProfile. Each FunctionProfile
instance holds information related to the function's profile such as how
long the function took to run, how many times it was called, etc...


在 3.9 版被加入: Added the following dataclasses: StatsProfile, FunctionProfile.
Added the following function: get_stats_profile.

@end deffn
@end deffn

@node What Is Deterministic Profiling?,限制,Stats 類別,Python 的分析器
@anchor{library/profile deterministic-profiling}@anchor{46d0}@anchor{library/profile what-is-deterministic-profiling}@anchor{46d1}
@subsubsection What Is Deterministic Profiling?


`Deterministic profiling' is meant to reflect the fact that all `function
call', `function return', and `exception' events are monitored, and precise
timings are made for the intervals between these events (during which time the
user's code is executing).  In contrast, `statistical profiling' (which is
not done by this module) randomly samples the effective instruction pointer, and
deduces where time is being spent.  The latter technique traditionally involves
less overhead (as the code does not need to be instrumented), but provides only
relative indications of where time is being spent.

In Python, since there is an interpreter active during execution, the presence
of instrumented code is not required in order to do deterministic profiling.
Python automatically provides a `hook' (optional callback) for each event.
In addition, the interpreted nature of Python tends to add so much overhead to
execution, that deterministic profiling tends to only add small processing
overhead in typical applications.  The result is that deterministic profiling is
not that expensive, yet provides extensive run time statistics about the
execution of a Python program.

Call count statistics can be used to identify bugs in code (surprising counts),
and to identify possible inline-expansion points (high call counts).  Internal
time statistics can be used to identify "hot loops" that should be carefully
optimized.  Cumulative time statistics should be used to identify high level
errors in the selection of algorithms.  Note that the unusual handling of
cumulative times in this profiler allows statistics for recursive
implementations of algorithms to be directly compared to iterative
implementations.

@node 限制,校正,What Is Deterministic Profiling?,Python 的分析器
@anchor{library/profile limitations}@anchor{46d2}@anchor{library/profile profile-limitations}@anchor{46d3}
@subsubsection 限制


One limitation has to do with accuracy of timing information. There is a
fundamental problem with deterministic profilers involving accuracy.  The most
obvious restriction is that the underlying "clock" is only ticking at a rate
(typically) of about .001 seconds.  Hence no measurements will be more accurate
than the underlying clock.  If enough measurements are taken, then the "error"
will tend to average out. Unfortunately, removing this first error induces a
second source of error.

The second problem is that it "takes a while" from when an event is dispatched
until the profiler's call to get the time actually `gets' the state of the
clock.  Similarly, there is a certain lag when exiting the profiler event
handler from the time that the clock's value was obtained (and then squirreled
away), until the user's code is once again executing.  As a result, functions
that are called many times, or call many functions, will typically accumulate
this error. The error that accumulates in this fashion is typically less than
the accuracy of the clock (less than one clock tick), but it `can' accumulate
and become very significant.

The problem is more important with @ref{b4,,profile} than with the lower-overhead
@ref{2b,,cProfile}.  For this reason, @ref{b4,,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 校正,Using a custom timer,限制,Python 的分析器
@anchor{library/profile calibration}@anchor{46d4}@anchor{library/profile profile-calibration}@anchor{46d5}
@subsubsection 校正


The profiler of the @ref{b4,,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{46d3,,限制}).

@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,,校正,Python 的分析器
@anchor{library/profile profile-timers}@anchor{46d6}@anchor{library/profile using-a-custom-timer}@anchor{46d7}
@subsubsection Using a custom timer


If you want to change how current time is determined (for example, to force use
of wall-clock time or elapsed process time), pass the timing function you want
to the @code{Profile} class constructor:

@example
pr = profile.Profile(your_time_func)
@end example

The resulting profiler will then call @code{your_time_func}. Depending on whether
you are using @ref{bcd,,profile.Profile} or @code{cProfile.Profile},
@code{your_time_func}'s return value will be interpreted differently:


@table @asis

@item @ref{bcd,,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{1316,,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{46d5,,校正}).  For most machines, a timer
that returns a lone integer value will provide the best results in terms of
low overhead during profiling.  (@ref{1316,,os.times()} is `pretty' bad, as it
returns a tuple of floating-point values).  If you want to substitute a
better timer in the cleanest fashion, derive a class and hardwire a
replacement dispatch method that best handles your timer call, along with the
appropriate calibration constant.

@item @code{cProfile.Profile}

@code{your_time_func} should return a single number.  If it returns integers,
you can also invoke the class constructor with a second argument specifying
the real duration of one unit of time.  For example, if
@code{your_integer_time_func} returns times measured in thousands of seconds,
you would construct the @code{Profile} instance as follows:

@example
pr = cProfile.Profile(your_integer_time_func, 0.001)
@end example

As the @code{cProfile.Profile} class cannot be calibrated, custom timer
functions should be used with care and should be as fast as possible.  For
the best results with a custom timer, it might be necessary to hard-code it
in the C source of the internal @code{_lsprof} module.
@end table

Python 3.3 adds several new functions in @ref{f4,,time} that can be used to make
precise measurements of process or wall-clock time. For example, see
@ref{c71,,time.perf_counter()}.

@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 陳述式執行,Python 的分析器,除錯與效能分析
@anchor{library/timeit doc}@anchor{46d8}@anchor{library/timeit module-timeit}@anchor{f5}@anchor{library/timeit timeit-measure-execution-time-of-small-code-snippets}@anchor{46d9}@anchor{library/timeit translation-repo}@anchor{46da}
@subsection @code{timeit} --- 測量小量程式片段的執行時間


@geindex module; timeit

`原始碼：'Lib/timeit.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/timeit.py}

@geindex 基準量測 (Benchmarking)
@geindex 性能表現


__________________________________________________________________


該模組提供了一種對少量 Python 程式碼進行計時的簡單方法。它有一個@ref{46db,,命令列介面}和一個@ref{46dc,,可呼叫介面}，它避免了許多測量執行時間的常見陷阱。另請參閱由 O'Reilly 出版的 `Python 錦囊妙計 (Python Cookbook)' 第二版中 Tim Peters 所寫的「演算法」章節的介紹。

@menu
* 基礎範例: 基礎範例<2>. 
* Python 介面:: 
* 命令列介面: 命令列介面<9>. 
* 範例: 範例<43>. 

@end menu

@node 基礎範例<2>,Python 介面,,timeit --- 測量小量程式片段的執行時間
@anchor{library/timeit basic-examples}@anchor{46dd}
@subsubsection 基礎範例


以下範例展示了如何使用@ref{46db,,命令列介面}來比較三個不同的運算式：

@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{46dc,,Python 介面}來實現：

@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{46dc,,Python 介面}傳遞可呼叫物件：

@example
>>> timeit.timeit(lambda: "-".join(map(str, range(100))), number=10000)
0.19665591977536678
@end example

但請注意，僅當使用命令列介面時 @ref{1079,,timeit()} 才會自動確定重複次數。在@ref{46de,,範例}章節中有更進階的範例。

@node Python 介面,命令列介面<9>,基礎範例<2>,timeit --- 測量小量程式片段的執行時間
@anchor{library/timeit id1}@anchor{46df}@anchor{library/timeit python-interface}@anchor{46dc}
@subsubsection Python 介面


該模組定義了三個便利函式和一個公開類別：

@geindex timeit() (於 timeit 模組中)
@anchor{library/timeit timeit timeit}@anchor{1079}
@deffn {函式} timeit.timeit (stmt='pass', setup='pass', timer=<default timer>, number=1000000, globals=None)

使用給定的陳述式、`setup' 程式碼和 `timer' 函式建立一個 @ref{16bc,,Timer} 實例，並執行其 @ref{ee4,,timeit()} 方法 `number' 次。可選的 `globals' 引數指定會在其中執行程式碼的命名空間。


在 3.5 版的變更: 新增 `globals' 選用參數。

@end deffn

@geindex repeat() (於 timeit 模組中)
@anchor{library/timeit timeit repeat}@anchor{46e0}
@deffn {函式} timeit.repeat (stmt='pass', setup='pass', timer=<default timer>, repeat=5, number=1000000, globals=None)

使用給定的陳述式、`setup' 程式碼和 `timer' 函式建立一個 @ref{16bc,,Timer} 實例，並使用給定的 `repeat' 計數和 `number' 來運行其 @ref{46e1,,repeat()} 方法。可選的 `globals' 引數指定會在其中執行程式碼的命名空間。


在 3.5 版的變更: 新增 `globals' 選用參數。



在 3.7 版的變更: `repeat' 的預設值從 3 更改為 5。

@end deffn

@geindex default_timer() (於 timeit 模組中)
@anchor{library/timeit timeit default_timer}@anchor{46e2}
@deffn {函式} timeit.default_timer ()

預設計時器始終為 time.perf_counter()，會回傳浮點秒數。另一種方法是 time.perf_counter_ns，會回傳整數奈秒。


在 3.3 版的變更: @ref{c71,,time.perf_counter()} 現在是預設計時器。

@end deffn

@geindex Timer (timeit 中的類別)
@anchor{library/timeit timeit Timer}@anchor{16bc}
@deffn {類別} timeit.Timer (stmt='pass', setup='pass', timer=<timer function>, globals=None)

用於計時小程式碼片段執行速度的類別。

建構函式接受一個要計時的陳述式、一個用於設定的附加陳述式和一個計時器函式。兩個陳述式都預設為 @code{'pass'}；計時器函式會與平台相依（請參閱模組文件字串 (doc string)）。`stmt' 和 `setup' 還可以包含由 @code{;} 或換行符號分隔的多個陳述式，只要它們不包含多行字串文字即可。預設情況下，該陳述式將在 timeit 的命名空間內執行；可以透過將命名空間傳遞給 `globals' 來控制此行為。

要測量第一個陳述式的執行時間，請使用 @ref{ee4,,timeit()} 方法。@ref{46e1,,repeat()} 和 @ref{ee3,,autorange()} 方法是多次呼叫 @ref{ee4,,timeit()} 的便捷方法。

`setup' 的執行時間不包含在總體運行計時中。

`stmt' 和 `setup' 參數還可以接受無需引數即可呼叫的物件。這會把對它們的呼叫嵌入到計時器函式中，然後由 @ref{ee4,,timeit()} 去執行。請注意，在這種情況下，因有額外的函式呼叫，時間開銷 (timing overhead) 會稍大一些。


在 3.5 版的變更: 新增 `globals' 選用參數。


@geindex timeit() (timeit.Timer 的方法)
@anchor{library/timeit timeit Timer timeit}@anchor{ee4}
@deffn {方法} timeit (number=1000000)

主陳述式執行 `number' 次的時間。這將執行一次設定陳述式，然後回傳多次執行主陳述式所需的時間。預設計時器以浮點形式回傳秒數，引數是迴圈的次數，預設為一百萬次。要使用的主陳述式、設定陳述式和計時器函式會被傳遞給建構函式。

@cartouche
@quotation 備註 
預設情況下 @ref{ee4,,timeit()} 在計時期間會暫時關閉@ref{1765,,垃圾回收}。這種方法的優點是它使獨立時序更具可比較性，缺點是 GC 可能是被測函式性能的重要組成部分。如果是這樣，可以將 GC 作為 `setup' 字串中的第一個陳述式以重新啟用。例如：

@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{ee3}
@deffn {方法} autorange (callback=None)

自動決定呼叫 @ref{ee4,,timeit()} 次數。

這是一個便捷函式，它重複呼叫 @ref{ee4,,timeit()} 以使得總時間 >= 0.2 秒，再回傳最終結果（迴圈數、該迴圈數所花費的時間）。它以 1、2、5、10、20、50... 的順序遞增數字來呼叫 @ref{ee4,,timeit()} 直到所用時間至少為 0.2 秒。

如果有給定 `callback' 且不是 @code{None}，則每次試驗後都會使用兩個引數來呼叫它：@code{callback(number, time_taken)}。


在 3.6 版被加入.

@end deffn

@geindex repeat() (timeit.Timer 的方法)
@anchor{library/timeit timeit Timer repeat}@anchor{46e1}
@deffn {方法} repeat (repeat=5, number=1000000)

呼叫 @ref{ee4,,timeit()} 數次。

這是一個方便的函式，它會重複呼叫 @ref{ee4,,timeit()} 並回傳結果列表。第一個引數指定呼叫 @ref{ee4,,timeit()} 的次數，第二個引數指定 @ref{ee4,,timeit()} 的 `number' 引數。

@cartouche
@quotation 備註 
人們很容易根據結果向量來計算出平均值和標準差並將其作為依歸，然而這並不是很有用。在典型情況下，最低值給出了機器運行給定程式碼片段的速度的下限；結果向量中較高的值通常不是由 Python 速度的變化所引起，而是由干擾計時精度的其他行程造成的。因此，結果中的 @ref{1106,,min()} 可能是你應該感興趣的唯一數字。在解讀該數據後，你應該查看整個向量並以常識判讀而非單純仰賴統計資訊。
@end quotation
@end cartouche


在 3.7 版的變更: `repeat' 的預設值從 3 更改為 5。

@end deffn

@geindex print_exc() (timeit.Timer 的方法)
@anchor{library/timeit timeit Timer print_exc}@anchor{46e3}
@deffn {方法} print_exc (file=None)

從計時程式碼印出回溯 (traceback) 的輔助函式。

典型用法：

@example
t = Timer(...)       # 在 try/except 之外
try:
    t.timeit(...)    # 或 t.repeat(...)
except Exception:
    t.print_exc()
@end example

相對於標準回溯的優點是，已編譯模板中的原始程式碼會被顯示出來。可選的 `file' 引數指定回溯的發送位置；它預設為 @ref{b2a,,sys.stderr}。
@end deffn
@end deffn

@node 命令列介面<9>,範例<43>,Python 介面,timeit --- 測量小量程式片段的執行時間
@anchor{library/timeit command-line-interface}@anchor{46e4}@anchor{library/timeit timeit-command-line-interface}@anchor{46db}
@subsubsection 命令列介面


當從命令列作為程式呼叫時，請使用以下形式：

@example
python -m timeit [-n N] [-r N] [-u U] [-s S] [-p] [-v] [-h] [statement ...]
@end example

其中之以下選項：

@geindex timeit 命令列選項; -n
@geindex timeit 命令列選項; --number
@anchor{library/timeit cmdoption-timeit-n}@anchor{46e5}@anchor{library/timeit cmdoption-timeit-number}@anchor{46e6}
@deffn {Option} @w{-}n N, @w{-}@w{-}number=N

執行 'statement' 多少次
@end deffn

@geindex timeit 命令列選項; -r
@geindex timeit 命令列選項; --repeat
@anchor{library/timeit cmdoption-timeit-r}@anchor{46e7}@anchor{library/timeit cmdoption-timeit-repeat}@anchor{46e8}
@deffn {Option} @w{-}r N, @w{-}@w{-}repeat=N

計時器重複多少次（預設 5）
@end deffn

@geindex timeit 命令列選項; -s
@geindex timeit 命令列選項; --setup
@anchor{library/timeit cmdoption-timeit-s}@anchor{46e9}@anchor{library/timeit cmdoption-timeit-setup}@anchor{46ea}
@deffn {Option} @w{-}s S, @w{-}@w{-}setup=S

會在一開始執行一次的陳述式（預設為 @code{pass}）
@end deffn

@geindex timeit 命令列選項; -p
@geindex timeit 命令列選項; --process
@anchor{library/timeit cmdoption-timeit-p}@anchor{46eb}@anchor{library/timeit cmdoption-timeit-process}@anchor{46ec}
@deffn {Option} @w{-}p, @w{-}@w{-}process

若要測量行程時間 (process time) 而非掛鐘時間 (wallclock time)，請使用 @ref{c72,,time.process_time()} 而不是預設的 @ref{c71,,time.perf_counter()}


在 3.3 版被加入.

@end deffn

@geindex timeit 命令列選項; -u
@geindex timeit 命令列選項; --unit
@anchor{library/timeit cmdoption-timeit-u}@anchor{46ed}@anchor{library/timeit cmdoption-timeit-unit}@anchor{46ee}
@deffn {Option} @w{-}u, @w{-}@w{-}unit=U

指定定時器輸出的時間單位；可以選擇 @code{nsec}、@code{usec}、@code{msec} 或 @code{sec}


在 3.5 版被加入.

@end deffn

@geindex timeit 命令列選項; -v
@geindex timeit 命令列選項; --verbose
@anchor{library/timeit cmdoption-timeit-v}@anchor{46ef}@anchor{library/timeit cmdoption-timeit-verbose}@anchor{46f0}
@deffn {Option} @w{-}v, @w{-}@w{-}verbose

印出原始計時結果；重複執行以獲得更高的數字精度
@end deffn

@geindex timeit 命令列選項; -h
@geindex timeit 命令列選項; --help
@anchor{library/timeit cmdoption-timeit-h}@anchor{46f1}@anchor{library/timeit cmdoption-timeit-help}@anchor{46f2}
@deffn {Option} @w{-}h, @w{-}@w{-}help

印出一條簡短的使用訊息並退出
@end deffn

可以透過將每一列陳述式指定為單獨引數來給定多列陳述式；可透過將引數括在引號中並使用前導空格以實現縮進列 (indented lines)。多個 @ref{46e9,,-s} 選項的作用類似。

如果沒有給定 @ref{46e5,,-n}，則透過嘗試從序列 1, 2, 5, 10, 20, 50, ... 中增加數字來計算合適的迴圈次數，直到總時間至少為 0.2 秒。

@ref{46e2,,default_timer()} 測量可能會受到同一台機器上運行的其他程式的影響，因此，當需要精確計時時，最好的做法是重複計時幾次並使用最佳時間。@ref{46e7,,-r} 選項對此很有用；在大多數情況下，預設的重複 5 次可能就足夠了。你可以使用 @ref{c72,,time.process_time()} 來測量 CPU 時間。

@cartouche
@quotation 備註 
執行 pass 陳述式會產生一定的基本開銷。這裡的程式碼並不試圖隱藏它，但你應該意識到它的存在。可以透過不帶引數呼叫程式來測量這個基本開銷，且不同 Python 版本之間的基本開銷可能有所不同。
@end quotation
@end cartouche

@node 範例<43>,,命令列介面<9>,timeit --- 測量小量程式片段的執行時間
@anchor{library/timeit examples}@anchor{46f3}@anchor{library/timeit timeit-examples}@anchor{46de}
@subsubsection 範例


可以提供一個僅會在開始時執行一次的設定陳述式：

@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

輸出中包含三個欄位。迴圈計數，它告訴你每次計時迴圈內重複運行陳述式主體的次數。重複計數（「最好的 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{16bc,,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{6f2,,hasattr()} 與 @ref{8f0,,try}/@ref{1ab,,except} 來測試缺失和存在之物件屬性並比較其花費 (cost)：

@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

要讓 @ref{f5,,timeit} 模組存取你定義的函式，你可以傳遞一個包含 import 陳述式的 `setup' 參數：

@example
def test():
    """一個笨笨的測試函式"""
    L = [i for i in range(100)]

if __name__ == '__main__':
    import timeit
    print(timeit.timeit("test()", setup="from __main__ import test"))
@end example

另一種選擇是將 @ref{1b1e,,globals()} 傳遞給 `globals' 參數，這將導致程式碼在目前的全域命名空間中執行，這比單獨指定 import 更方便：

@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 --- 追蹤記憶體配置,timeit --- 測量小量程式片段的執行時間,除錯與效能分析
@anchor{library/trace doc}@anchor{46f4}@anchor{library/trace module-trace}@anchor{103}@anchor{library/trace trace-trace-or-track-python-statement-execution}@anchor{46f5}@anchor{library/trace translation-repo}@anchor{46f6}
@subsection @code{trace} --- 追蹤或追查 Python 陳述式執行


@geindex module; trace

`原始碼：'Lib/trace.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/trace.py}


__________________________________________________________________


@ref{103,,trace} 模組可用來追蹤程式執行過程、產生帶註解的陳述式涵蓋範圍清單、輸出呼叫者／被呼叫者的關係，以及在程式執行期間被執行的函式串列。它可以在其他程式中使用，也可以從命令列啟動。


@subsubheading 也參考



@table @asis

@item Coverage.py@footnote{https://coverage.readthedocs.io/}

一款受歡迎的第三方涵蓋範圍工具，提供 HTML 輸出與分支涵蓋等進階功能。
@end table


@menu
* 命令列用法: 命令列用法<7>. 
* 程式介面:: 

@end menu

@node 命令列用法<7>,程式介面,,trace --- 追蹤或追查 Python 陳述式執行
@anchor{library/trace command-line-usage}@anchor{46f7}@anchor{library/trace trace-cli}@anchor{46f8}
@subsubsection 命令列用法


@ref{103,,trace} 模組可從命令列執行，用法可以非常簡單，如：:

@example
python -m trace --count -C . somefile.py ...
@end example

上述命令會執行 @code{somefile.py}，並將產生執行期間所引入的所有 Python 模組的帶註解串列，輸出至目前目錄。

@geindex trace 命令列選項; --help
@anchor{library/trace cmdoption-trace-help}@anchor{46f9}
@deffn {Option} @w{-}@w{-}help

顯示用法並結束程式。
@end deffn

@geindex trace 命令列選項; --version
@anchor{library/trace cmdoption-trace-version}@anchor{46fa}
@deffn {Option} @w{-}@w{-}version

顯示模組版本並結束程式。
@end deffn


在 3.8 版被加入: 新增 @code{--module} 選項，允許執行可執行模組。


@menu
* 主要選項:: 
* 修飾子（Modifier）:: 
* 篩選子（Filter）:: 

@end menu

@node 主要選項,修飾子（Modifier）,,命令列用法<7>
@anchor{library/trace main-options}@anchor{46fb}
@subsubsection 主要選項


執行 @ref{103,,trace} 時，至少必須指定以下選項之一。@ref{46fc,,--listfuncs} 選項與 @ref{46fd,,--trace} 及 @ref{46fe,,--count} 選項互斥。當提供 @ref{46fc,,--listfuncs} 時，將不接受 @ref{46fe,,--count} 或 @ref{46fd,,--trace}，反之亦然。

@geindex trace 命令列選項; -c
@geindex trace 命令列選項; --count
@anchor{library/trace cmdoption-trace-c}@anchor{46fe}@anchor{library/trace cmdoption-trace-count}@anchor{46ff}
@deffn {Option} @w{-}c, @w{-}@w{-}count

在程式執行結束時產生一組帶註解串列檔案，顯示每個陳述式被執行的次數。參見下方的 @ref{4700,,--coverdir}、@ref{4701,,--file} 及 @ref{4702,,--no-report}。
@end deffn

@geindex trace 命令列選項; -t
@geindex trace 命令列選項; --trace
@anchor{library/trace cmdoption-trace-t}@anchor{46fd}@anchor{library/trace cmdoption-trace-trace}@anchor{4703}
@deffn {Option} @w{-}t, @w{-}@w{-}trace

執行時即時顯示每一行。
@end deffn

@geindex trace 命令列選項; -l
@geindex trace 命令列選項; --listfuncs
@anchor{library/trace cmdoption-trace-l}@anchor{46fc}@anchor{library/trace cmdoption-trace-listfuncs}@anchor{4704}
@deffn {Option} @w{-}l, @w{-}@w{-}listfuncs

顯示程式執行過程中被呼叫的函式。
@end deffn

@geindex trace 命令列選項; -r
@geindex trace 命令列選項; --report
@anchor{library/trace cmdoption-trace-r}@anchor{4705}@anchor{library/trace cmdoption-trace-report}@anchor{4706}
@deffn {Option} @w{-}r, @w{-}@w{-}report

從先前使用 @ref{46fe,,--count} 與 @ref{4701,,--file} 選項執行過的程式生成帶註解的串列，不會執行任何程式碼。
@end deffn

@geindex trace 命令列選項; -T
@geindex trace 命令列選項; --trackcalls
@anchor{library/trace cmdoption-trace-T}@anchor{4707}@anchor{library/trace cmdoption-trace-trackcalls}@anchor{4708}
@deffn {Option} @w{-}T, @w{-}@w{-}trackcalls

顯示程式執行時產生的呼叫關係。
@end deffn

@node 修飾子（Modifier）,篩選子（Filter）,主要選項,命令列用法<7>
@anchor{library/trace modifiers}@anchor{4709}
@subsubsection 修飾子（Modifier）


@geindex trace 命令列選項; -f
@geindex trace 命令列選項; --file
@anchor{library/trace cmdoption-trace-f}@anchor{4701}@anchor{library/trace cmdoption-trace-file}@anchor{470a}
@deffn {Option} @w{-}f, @w{-}@w{-}file=<file>

指定用來累積多次追蹤結果的檔案之名稱。應與 @ref{46fe,,--count} 選項搭配使用。
@end deffn

@geindex trace 命令列選項; -C
@geindex trace 命令列選項; --coverdir
@anchor{library/trace cmdoption-trace-C}@anchor{4700}@anchor{library/trace cmdoption-trace-coverdir}@anchor{470b}
@deffn {Option} @w{-}C, @w{-}@w{-}coverdir=<dir>

報告檔案的輸出目錄。@code{package.module} 的涵蓋範圍報告將寫入檔案：@code{`dir'/`package'/`module'.cover}。
@end deffn

@geindex trace 命令列選項; -m
@geindex trace 命令列選項; --missing
@anchor{library/trace cmdoption-trace-m}@anchor{470c}@anchor{library/trace cmdoption-trace-missing}@anchor{470d}
@deffn {Option} @w{-}m, @w{-}@w{-}missing

在產生帶註解的串列時，使用 @code{>>>>>>} 標記未被執行的程式碼行。
@end deffn

@geindex trace 命令列選項; -s
@geindex trace 命令列選項; --summary
@anchor{library/trace cmdoption-trace-s}@anchor{470e}@anchor{library/trace cmdoption-trace-summary}@anchor{470f}
@deffn {Option} @w{-}s, @w{-}@w{-}summary

使用 @ref{46fe,,--count} 或 @ref{4705,,--report} 時，會將每個處理過的檔案摘要輸出至 stdout。
@end deffn

@geindex trace 命令列選項; -R
@geindex trace 命令列選項; --no-report
@anchor{library/trace cmdoption-trace-R}@anchor{4702}@anchor{library/trace cmdoption-trace-no-report}@anchor{4710}
@deffn {Option} @w{-}R, @w{-}@w{-}no@w{-}report

不產生帶註解的串列。若你打算多次使用 @ref{46fe,,--count} 執行程式，並在最後再統一產生串列，這會很有幫助。
@end deffn

@geindex trace 命令列選項; -g
@geindex trace 命令列選項; --timing
@anchor{library/trace cmdoption-trace-g}@anchor{4711}@anchor{library/trace cmdoption-trace-timing}@anchor{4712}
@deffn {Option} @w{-}g, @w{-}@w{-}timing

在每一行前加上自程式啟動以來的經過時間。僅在追蹤時使用。
@end deffn

@node 篩選子（Filter）,,修飾子（Modifier）,命令列用法<7>
@anchor{library/trace filters}@anchor{4713}
@subsubsection 篩選子（Filter）


這些選項可以重複使用多次。

@geindex trace 命令列選項; --ignore-module
@anchor{library/trace cmdoption-trace-ignore-module}@anchor{4714}
@deffn {Option} @w{-}@w{-}ignore@w{-}module=<mod>

忽略所指定的模組名稱及其子模組（若為套件）。引數可以是以逗號分隔的名稱串列。
@end deffn

@geindex trace 命令列選項; --ignore-dir
@anchor{library/trace cmdoption-trace-ignore-dir}@anchor{4715}
@deffn {Option} @w{-}@w{-}ignore@w{-}dir=<dir>

忽略指定目錄及其子目錄中的所有模組與套件。引數可以是以 @ref{1ffb,,os.pathsep} 分隔的目錄串列。
@end deffn

@node 程式介面,,命令列用法<7>,trace --- 追蹤或追查 Python 陳述式執行
@anchor{library/trace programmatic-interface}@anchor{4716}@anchor{library/trace trace-api}@anchor{4717}
@subsubsection 程式介面


@geindex Trace (trace 中的類別)
@anchor{library/trace trace Trace}@anchor{4718}
@deffn {類別} trace.Trace (count=1, trace=1, countfuncs=0, countcallers=0, ignoremods=(), ignoredirs=(), infile=None, outfile=None, timing=False)

建立一個物件以追蹤單一陳述式或運算式的執行。所有參數皆為可選的。`count' 啟用行數統計，`trace' 啟用逐行追蹤執行，`countfuncs' 可列出執行期間呼叫的函式，`countcallers' 追蹤呼叫關係，`ignoremods' 是要忽略的模組或套件名稱串列，`ignoredirs' 是其模組或套件應被忽略的目錄串列，`infile' 是讀取儲存計數資料的檔案名稱，`outfile' 是要寫入更新後計數資料的檔案名稱，`timing' 則會顯示自開始追蹤以來的時間戳記。

@geindex run() (trace.Trace 的方法)
@anchor{library/trace trace Trace run}@anchor{4719}
@deffn {方法} run (cmd)

執行命令，並依目前追蹤參數收集執行統計資料。`cmd' 必須是可傳入 @ref{49d,,exec()} 的字串或程式碼物件。
@end deffn

@geindex runctx() (trace.Trace 的方法)
@anchor{library/trace trace Trace runctx}@anchor{471a}
@deffn {方法} runctx (cmd, globals=None, locals=None)

在指定的全域與區域命名空間中，根據目前的追蹤參數執行命令並收集統計資料。若未指定，`globals' 與 `locals' 預設為空字典。
@end deffn

@geindex runfunc() (trace.Trace 的方法)
@anchor{library/trace trace Trace runfunc}@anchor{c69}
@deffn {方法} runfunc (func, /, *args, **kwds)

在目前的追蹤參數下，使用 @ref{4718,,Trace} 物件控制呼叫 `func'，並傳入指定的引數。
@end deffn

@geindex results() (trace.Trace 的方法)
@anchor{library/trace trace Trace results}@anchor{471b}
@deffn {方法} results ()

回傳一個 @ref{471c,,CoverageResults} 物件，包含指定 @ref{4718,,Trace} 實例中所有先前對 @code{run}、@code{runctx} 與 @code{runfunc} 呼叫的累積結果。不會重設累積的追蹤結果。
@end deffn
@end deffn

@geindex CoverageResults (trace 中的類別)
@anchor{library/trace trace CoverageResults}@anchor{471c}
@deffn {類別} trace.CoverageResults

一個用來儲存涵蓋範圍結果的容器，由 @ref{471b,,Trace.results()} 建立。不應由使用者直接建立。

@geindex update() (trace.CoverageResults 的方法)
@anchor{library/trace trace CoverageResults update}@anchor{471d}
@deffn {方法} update (other)

合併來自另一個 @ref{471c,,CoverageResults} 物件的資料。
@end deffn

@geindex write_results() (trace.CoverageResults 的方法)
@anchor{library/trace trace CoverageResults write_results}@anchor{471e}
@deffn {方法} write_results (show_missing=True, summary=False, coverdir=None, *, ignore_missing_files=False)

寫入涵蓋範圍結果。將 `show_missing' 設為真可顯示未被執行的程式碼行；將 `summary' 設為真則會在輸出中加入每個模組的涵蓋範圍摘要。`coverdir' 指定輸出涵蓋範圍結果檔案的目錄，若為 @code{None}，則每個原始檔案的結果會輸出至其所在目錄中。

若 `ignore_missing_files' 為 @code{True}，則會忽略那些已不存在的檔案的涵蓋範圍資料，不會顯示任何錯誤。否則，缺少的檔案將會引發 @ref{264,,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 執行新的命令
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 --- 追蹤或追查 Python 陳述式執行,除錯與效能分析
@anchor{library/tracemalloc doc}@anchor{471f}@anchor{library/tracemalloc module-tracemalloc}@anchor{105}@anchor{library/tracemalloc tracemalloc-trace-memory-allocations}@anchor{4720}@anchor{library/tracemalloc translation-repo}@anchor{4721}
@subsection @code{tracemalloc} --- 追蹤記憶體配置


@geindex module; tracemalloc


在 3.4 版被加入.


`原始碼：'Lib/tracemalloc.py@footnote{https://github.com/python/cpython/tree/3.14/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{1ff4,,PYTHONTRACEMALLOC} environment
variable to @code{1}, or by using @ref{16f,,-X} @code{tracemalloc} command line
option. The @ref{1ff3,,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{1ff4,,PYTHONTRACEMALLOC} environment variable to @code{25}, or use the
@ref{16f,,-X} @code{tracemalloc=25} command line option.

@menu
* 範例: 範例<44>. 
* API:: 

@end menu

@node 範例<44>,API,,tracemalloc --- 追蹤記憶體配置
@anchor{library/tracemalloc examples}@anchor{4722}
@subsubsection 範例


@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,,範例<44>
@anchor{library/tracemalloc display-the-top-10}@anchor{4723}
@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{4db,,namedtuple} types.

更多選項請見 @ref{4724,,Snapshot.statistics()}。

@node Compute differences,Get the traceback of a memory block,Display the top 10,範例<44>
@anchor{library/tracemalloc compute-differences}@anchor{4725}
@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{89,,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{4726,,Snapshot.dump()} method to analyze the snapshot offline. Then use the
@ref{4727,,Snapshot.load()} method reload the snapshot.

@node Get the traceback of a memory block,Pretty top,Compute differences,範例<44>
@anchor{library/tracemalloc get-the-traceback-of-a-memory-block}@anchor{4728}
@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{7b,,importlib} module to
load data (bytecode and constants) from modules: @code{870.1 KiB}. The traceback is
where the @ref{7b,,importlib} loaded data most recently: on the @code{import pdb}
line of the @ref{3e,,doctest} module. The traceback may change if a new module is
loaded.

@node Pretty top,,Get the traceback of a memory block,範例<44>
@anchor{library/tracemalloc pretty-top}@anchor{4729}
@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

更多選項請見 @ref{4724,,Snapshot.statistics()}。

@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{472a}
@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{472b,,get_traced_memory()} and @ref{b2c,,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

輸出：

@example
first_size=664, first_peak=3592984
second_size=804, second_peak=29704
@end example

Using @ref{b2c,,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{1ff3,,start()} call. Without the call to
@ref{b2c,,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{24d,,list}, and writing
@code{sum(range(...))}).

@node API,,範例<44>,tracemalloc --- 追蹤記憶體配置
@anchor{library/tracemalloc api}@anchor{472c}
@subsubsection API


@menu
* 函式: 函式<11>. 
* DomainFilter:: 
* Filter:: 
* Frame:: 
* Snapshot:: 
* Statistic:: 
* StatisticDiff:: 
* Trace:: 
* Traceback:: 

@end menu

@node 函式<11>,DomainFilter,,API
@anchor{library/tracemalloc functions}@anchor{472d}
@subsubsection 函式


@geindex clear_traces() (於 tracemalloc 模組中)
@anchor{library/tracemalloc tracemalloc clear_traces}@anchor{472e}
@deffn {函式} tracemalloc.clear_traces ()

Clear traces of memory blocks allocated by Python.

另請參閱 @ref{1823,,stop()}。
@end deffn

@geindex get_object_traceback() (於 tracemalloc 模組中)
@anchor{library/tracemalloc tracemalloc get_object_traceback}@anchor{1e00}
@deffn {函式} tracemalloc.get_object_traceback (obj)

Get the traceback where the Python object `obj' was allocated.
Return a @ref{d8a,,Traceback} instance, or @code{None} if the @ref{105,,tracemalloc}
module is not tracing memory allocations or did not trace the allocation of
the object.

另請參閱 @ref{9fe,,gc.get_referrers()} 與 @ref{1a26,,sys.getsizeof()} 函式。
@end deffn

@geindex get_traceback_limit() (於 tracemalloc 模組中)
@anchor{library/tracemalloc tracemalloc get_traceback_limit}@anchor{472f}
@deffn {函式} tracemalloc.get_traceback_limit ()

Get the maximum number of frames stored in the traceback of a trace.

The @ref{105,,tracemalloc} module must be tracing memory allocations to
get the limit, otherwise an exception is raised.

The limit is set by the @ref{1ff3,,start()} function.
@end deffn

@geindex get_traced_memory() (於 tracemalloc 模組中)
@anchor{library/tracemalloc tracemalloc get_traced_memory}@anchor{472b}
@deffn {函式} tracemalloc.get_traced_memory ()

Get the current size and peak size of memory blocks traced by the
@ref{105,,tracemalloc} module as a tuple: @code{(current: int, peak: int)}.
@end deffn

@geindex reset_peak() (於 tracemalloc 模組中)
@anchor{library/tracemalloc tracemalloc reset_peak}@anchor{b2c}
@deffn {函式} tracemalloc.reset_peak ()

Set the peak size of memory blocks traced by the @ref{105,,tracemalloc} module
to the current size.

Do nothing if the @ref{105,,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{472e,,clear_traces()}. Snapshots taken with
@ref{4730,,take_snapshot()} before a call to @ref{b2c,,reset_peak()} can be
meaningfully compared to snapshots taken after the call.

另請參閱 @ref{472b,,get_traced_memory()}。


在 3.9 版被加入.

@end deffn

@geindex get_tracemalloc_memory() (於 tracemalloc 模組中)
@anchor{library/tracemalloc tracemalloc get_tracemalloc_memory}@anchor{4731}
@deffn {函式} tracemalloc.get_tracemalloc_memory ()

Get the memory usage in bytes of the @ref{105,,tracemalloc} module used to store
traces of memory blocks.
Return an @ref{19b,,int}.
@end deffn

@geindex is_tracing() (於 tracemalloc 模組中)
@anchor{library/tracemalloc tracemalloc is_tracing}@anchor{4732}
@deffn {函式} tracemalloc.is_tracing ()

@code{True} if the @ref{105,,tracemalloc} module is tracing Python memory
allocations, @code{False} otherwise.

另請參閱 @ref{1ff3,,start()} 與 @ref{1823,,stop()} 函式。
@end deffn

@geindex start() (於 tracemalloc 模組中)
@anchor{library/tracemalloc tracemalloc start}@anchor{1ff3}
@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{4733,,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{4734,,Snapshot.compare_to()} and @ref{4724,,Snapshot.statistics()} methods.

Storing more frames increases the memory and CPU overhead of the
@ref{105,,tracemalloc} module. Use the @ref{4731,,get_tracemalloc_memory()} function
to measure how much memory is used by the @ref{105,,tracemalloc} module.

The 
@geindex PYTHONTRACEMALLOC
@geindex 環境變數; PYTHONTRACEMALLOC
@ref{1ff4,,PYTHONTRACEMALLOC} environment variable
(@code{PYTHONTRACEMALLOC=NFRAME}) and the @ref{16f,,-X} @code{tracemalloc=NFRAME}
command line option can be used to start tracing at startup.

See also @ref{1823,,stop()}, @ref{4732,,is_tracing()} and @ref{472f,,get_traceback_limit()}
functions.
@end deffn

@geindex stop() (於 tracemalloc 模組中)
@anchor{library/tracemalloc tracemalloc stop}@anchor{1823}
@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{4730,,take_snapshot()} function to take a snapshot of traces before
clearing them.

See also @ref{1ff3,,start()}, @ref{4732,,is_tracing()} and @ref{472e,,clear_traces()}
functions.
@end deffn

@geindex take_snapshot() (於 tracemalloc 模組中)
@anchor{library/tracemalloc tracemalloc take_snapshot}@anchor{4730}
@deffn {函式} tracemalloc.take_snapshot ()

Take a snapshot of traces of memory blocks allocated by Python. Return a new
@ref{4735,,Snapshot} instance.

The snapshot does not include memory blocks allocated before the
@ref{105,,tracemalloc} module started to trace memory allocations.

Tracebacks of traces are limited to @ref{472f,,get_traceback_limit()} frames. Use
the `nframe' parameter of the @ref{1ff3,,start()} function to store more frames.

The @ref{105,,tracemalloc} module must be tracing memory allocations to take a
snapshot, see the @ref{1ff3,,start()} function.

另請參閱 @ref{1e00,,get_object_traceback()} 函式。
@end deffn

@node DomainFilter,Filter,函式<11>,API
@anchor{library/tracemalloc domainfilter}@anchor{4736}
@subsubsection DomainFilter


@geindex DomainFilter (tracemalloc 中的類別)
@anchor{library/tracemalloc tracemalloc DomainFilter}@anchor{ee8}
@deffn {類別} tracemalloc.DomainFilter (inclusive: bool, domain: int)

Filter traces of memory blocks by their address space (domain).


在 3.6 版被加入.


@geindex inclusive (tracemalloc.DomainFilter 的屬性)
@anchor{library/tracemalloc tracemalloc DomainFilter inclusive}@anchor{4737}
@deffn {屬性} inclusive

If `inclusive' is @code{True} (include), match memory blocks allocated
in the address space @ref{4738,,domain}.

If `inclusive' is @code{False} (exclude), match memory blocks not allocated
in the address space @ref{4738,,domain}.
@end deffn

@geindex domain (tracemalloc.DomainFilter 的屬性)
@anchor{library/tracemalloc tracemalloc DomainFilter domain}@anchor{4738}
@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{4739}
@subsubsection Filter


@geindex Filter (tracemalloc 中的類別)
@anchor{library/tracemalloc tracemalloc Filter}@anchor{473a}
@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{1b56,,fnmatch.fnmatch()} function for the syntax of
`filename_pattern'. The @code{'.pyc'} file extension is
replaced with @code{'.py'}.

範例：


@itemize *

@item 
@code{Filter(True, subprocess.__file__)} only includes traces of the
@ref{dc,,subprocess} module

@item 
@code{Filter(False, tracemalloc.__file__)} excludes traces of the
@ref{105,,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 版的變更: 新增 @ref{473b,,domain} 屬性。


@geindex domain (tracemalloc.Filter 的屬性)
@anchor{library/tracemalloc tracemalloc Filter domain}@anchor{473b}
@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{473c}
@deffn {屬性} inclusive

If `inclusive' is @code{True} (include), only match memory blocks allocated
in a file with a name matching @ref{473d,,filename_pattern} at line number
@ref{473e,,lineno}.

If `inclusive' is @code{False} (exclude), ignore memory blocks allocated in
a file with a name matching @ref{473d,,filename_pattern} at line number
@ref{473e,,lineno}.
@end deffn

@geindex lineno (tracemalloc.Filter 的屬性)
@anchor{library/tracemalloc tracemalloc Filter lineno}@anchor{473e}
@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{473d}
@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{473f}
@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{472f,,get_traceback_limit()} function and @ref{4740,,Snapshot.traceback_limit}
attribute.
@end deffn
@end deffn

@node Frame,Snapshot,Filter,API
@anchor{library/tracemalloc frame}@anchor{4741}
@subsubsection Frame


@geindex Frame (tracemalloc 中的類別)
@anchor{library/tracemalloc tracemalloc Frame}@anchor{4742}
@deffn {類別} tracemalloc.Frame

Frame of a traceback.

The @ref{d8a,,Traceback} class is a sequence of @ref{4742,,Frame} instances.

@geindex filename (tracemalloc.Frame 的屬性)
@anchor{library/tracemalloc tracemalloc Frame filename}@anchor{4743}
@deffn {屬性} filename

Filename (@code{str}).
@end deffn

@geindex lineno (tracemalloc.Frame 的屬性)
@anchor{library/tracemalloc tracemalloc Frame lineno}@anchor{4744}
@deffn {屬性} lineno

Line number (@code{int}).
@end deffn
@end deffn

@node Snapshot,Statistic,Frame,API
@anchor{library/tracemalloc snapshot}@anchor{4745}
@subsubsection Snapshot


@geindex Snapshot (tracemalloc 中的類別)
@anchor{library/tracemalloc tracemalloc Snapshot}@anchor{4735}
@deffn {類別} tracemalloc.Snapshot

Snapshot of traces of memory blocks allocated by Python.

The @ref{4730,,take_snapshot()} function creates a snapshot instance.

@geindex compare_to() (tracemalloc.Snapshot 的方法)
@anchor{library/tracemalloc tracemalloc Snapshot compare_to}@anchor{4734}
@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{4746,,StatisticDiff} instances grouped by `key_type'.

See the @ref{4724,,Snapshot.statistics()} method for `key_type' and `cumulative'
parameters.

The result is sorted from the biggest to the smallest by: absolute value
of @ref{4747,,StatisticDiff.size_diff}, @ref{4748,,StatisticDiff.size}, absolute
value of @ref{4749,,StatisticDiff.count_diff}, @ref{474a,,Statistic.count} and
then by @ref{474b,,StatisticDiff.traceback}.
@end deffn

@geindex dump() (tracemalloc.Snapshot 的方法)
@anchor{library/tracemalloc tracemalloc Snapshot dump}@anchor{4726}
@deffn {方法} dump (filename)

Write the snapshot into a file.

Use @ref{4727,,load()} to reload the snapshot.
@end deffn

@geindex filter_traces() (tracemalloc.Snapshot 的方法)
@anchor{library/tracemalloc tracemalloc Snapshot filter_traces}@anchor{474c}
@deffn {方法} filter_traces (filters)

Create a new @ref{4735,,Snapshot} instance with a filtered @ref{474d,,traces}
sequence, `filters' is a list of @ref{ee8,,DomainFilter} and
@ref{473a,,Filter} instances.  If `filters' is an empty list, return a new
@ref{4735,,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{ee8,,DomainFilter} instances are now also accepted in `filters'.

@end deffn

@geindex load() (tracemalloc.Snapshot 的類別方法)
@anchor{library/tracemalloc tracemalloc Snapshot load}@anchor{4727}
@deffn {方法} classmethod load (filename)

Load a snapshot from a file.

另請參閱 @ref{4726,,dump()}。
@end deffn

@geindex statistics() (tracemalloc.Snapshot 的方法)
@anchor{library/tracemalloc tracemalloc Snapshot statistics}@anchor{4724}
@deffn {方法} statistics (key_type: str, cumulative: bool = False)

Get statistics as a sorted list of @ref{474e,,Statistic} instances grouped
by `key_type':


@multitable {xxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

key_type

@tab

描述

@item

@code{'filename'}

@tab

filename

@item

@code{'lineno'}

@tab

filename and line number

@item

@code{'traceback'}

@tab

traceback

@end multitable


If `cumulative' is @code{True}, cumulate size and count of memory blocks of
all frames of the traceback of a trace, not only the most recent frame.
The cumulative mode can only be used with `key_type' equals to
@code{'filename'} and @code{'lineno'}.

The result is sorted from the biggest to the smallest by:
@ref{474f,,Statistic.size}, @ref{474a,,Statistic.count} and then by
@ref{4750,,Statistic.traceback}.
@end deffn

@geindex traceback_limit (tracemalloc.Snapshot 的屬性)
@anchor{library/tracemalloc tracemalloc Snapshot traceback_limit}@anchor{4740}
@deffn {屬性} traceback_limit

Maximum number of frames stored in the traceback of @ref{474d,,traces}:
result of the @ref{472f,,get_traceback_limit()} when the snapshot was taken.
@end deffn

@geindex traces (tracemalloc.Snapshot 的屬性)
@anchor{library/tracemalloc tracemalloc Snapshot traces}@anchor{474d}
@deffn {屬性} traces

Traces of all memory blocks allocated by Python: sequence of
@ref{4751,,Trace} instances.

The sequence has an undefined order. Use the @ref{4724,,Snapshot.statistics()}
method to get a sorted list of statistics.
@end deffn
@end deffn

@node Statistic,StatisticDiff,Snapshot,API
@anchor{library/tracemalloc statistic}@anchor{4752}
@subsubsection Statistic


@geindex Statistic (tracemalloc 中的類別)
@anchor{library/tracemalloc tracemalloc Statistic}@anchor{474e}
@deffn {類別} tracemalloc.Statistic

Statistic on memory allocations.

@ref{4724,,Snapshot.statistics()} returns a list of @ref{474e,,Statistic} instances.

另請參閱 @ref{4746,,StatisticDiff} 類別。

@geindex count (tracemalloc.Statistic 的屬性)
@anchor{library/tracemalloc tracemalloc Statistic count}@anchor{474a}
@deffn {屬性} count

Number of memory blocks (@code{int}).
@end deffn

@geindex size (tracemalloc.Statistic 的屬性)
@anchor{library/tracemalloc tracemalloc Statistic size}@anchor{474f}
@deffn {屬性} size

Total size of memory blocks in bytes (@code{int}).
@end deffn

@geindex traceback (tracemalloc.Statistic 的屬性)
@anchor{library/tracemalloc tracemalloc Statistic traceback}@anchor{4750}
@deffn {屬性} traceback

Traceback where the memory block was allocated, @ref{d8a,,Traceback}
instance.
@end deffn
@end deffn

@node StatisticDiff,Trace,Statistic,API
@anchor{library/tracemalloc statisticdiff}@anchor{4753}
@subsubsection StatisticDiff


@geindex StatisticDiff (tracemalloc 中的類別)
@anchor{library/tracemalloc tracemalloc StatisticDiff}@anchor{4746}
@deffn {類別} tracemalloc.StatisticDiff

Statistic difference on memory allocations between an old and a new
@ref{4735,,Snapshot} instance.

@ref{4734,,Snapshot.compare_to()} returns a list of @ref{4746,,StatisticDiff}
instances. See also the @ref{474e,,Statistic} class.

@geindex count (tracemalloc.StatisticDiff 的屬性)
@anchor{library/tracemalloc tracemalloc StatisticDiff count}@anchor{4754}
@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{4749}
@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{4748}
@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{4747}
@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{474b}
@deffn {屬性} traceback

Traceback where the memory blocks were allocated, @ref{d8a,,Traceback}
instance.
@end deffn
@end deffn

@node Trace,Traceback,StatisticDiff,API
@anchor{library/tracemalloc trace}@anchor{4755}
@subsubsection Trace


@geindex Trace (tracemalloc 中的類別)
@anchor{library/tracemalloc tracemalloc Trace}@anchor{4751}
@deffn {類別} tracemalloc.Trace

Trace of a memory block.

The @ref{474d,,Snapshot.traces} attribute is a sequence of @ref{4751,,Trace}
instances.


在 3.6 版的變更: 新增 @ref{4756,,domain} 屬性。


@geindex domain (tracemalloc.Trace 的屬性)
@anchor{library/tracemalloc tracemalloc Trace domain}@anchor{4756}
@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{4757}
@deffn {屬性} size

Size of the memory block in bytes (@code{int}).
@end deffn

@geindex traceback (tracemalloc.Trace 的屬性)
@anchor{library/tracemalloc tracemalloc Trace traceback}@anchor{4758}
@deffn {屬性} traceback

Traceback where the memory block was allocated, @ref{d8a,,Traceback}
instance.
@end deffn
@end deffn

@node Traceback,,Trace,API
@anchor{library/tracemalloc traceback}@anchor{4759}
@subsubsection Traceback


@geindex Traceback (tracemalloc 中的類別)
@anchor{library/tracemalloc tracemalloc Traceback}@anchor{d8a}
@deffn {類別} tracemalloc.Traceback

Sequence of @ref{4742,,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{472f,,get_traceback_limit()} frames. See the @ref{4730,,take_snapshot()} function.
The original number of frames of the traceback is stored in the
@ref{4733,,Traceback.total_nframe} attribute. That allows to know if a traceback
has been truncated by the traceback limit.

The @ref{4758,,Trace.traceback} attribute is an instance of @ref{d8a,,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{4733}
@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{4733,,Traceback.total_nframe} attribute was added.


@geindex format() (tracemalloc.Traceback 的方法)
@anchor{library/tracemalloc tracemalloc Traceback format}@anchor{d8b}
@deffn {方法} format (limit=None, most_recent_first=False)

Format the traceback as a list of lines. Use the @ref{89,,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{475a,,traceback.format_tb()} function, except that
@ref{d8b,,format()} does not include newlines.

範例：

@example
print("Traceback (most recent call first):")
for line in traceback:
    print(line)
@end example

輸出：

@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 軟體封裝與發布,Python Runtime 服務,除錯與效能分析,Python 標準函式庫 Standard Library
@anchor{library/distribution doc}@anchor{475b}@anchor{library/distribution software-packaging-and-distribution}@anchor{475c}@anchor{library/distribution translation-repo}@anchor{475d}
@section 軟體封裝與發布


這些函式庫可以幫助你發布和安裝 Python 軟體。雖然這些模組設計是為了與 Python 套件索引 (Python Package Index)@footnote{https://pypi.org} 結合使用，但它們也可以搭配本地索引伺服器，甚至可以在沒有任何索引伺服器的情況下使用。

@menu
* ensurepip: ensurepip --- pip 安裝器的初始建置 bootstrapping. pip 安裝器的初始建置 (bootstrapping)
* venv: venv --- 建立虛擬環境. 建立虛擬環境
* zipapp —-- 管理可執行的 Python zip 封存檔案:: 

@end menu

@node ensurepip --- pip 安裝器的初始建置 bootstrapping,venv --- 建立虛擬環境,,軟體封裝與發布
@anchor{library/ensurepip doc}@anchor{475e}@anchor{library/ensurepip ensurepip-bootstrapping-the-pip-installer}@anchor{475f}@anchor{library/ensurepip module-ensurepip}@anchor{59}
@subsection @code{ensurepip} --- @code{pip} 安裝器的初始建置 (bootstrapping)


@geindex module; ensurepip


在 3.4 版被加入.


`原始碼：'Lib/ensurepip@footnote{https://github.com/python/cpython/tree/3.14/Lib/ensurepip}


__________________________________________________________________


@ref{59,,ensurepip} 套件 (package) 為既有的 Python 安裝或虛擬環境提供 @code{pip} 安裝器初始建置 (bootstrapping) 的支援。這個初始建置的方式應證了事實 —— @code{pip} 是有其獨立發布週期的專案，且其最新可用穩定的版本，會與 CPython 直譯器 (interpreter) 之維護和功能發布綁定。

大多數情況下，Python 的終端使用者不需要直接叫用此模組（因為 @code{pip} 預設應為初始建置），但若安裝 Python 時 @code{pip} 被省略（或建立一虛擬環境時），又或是 @code{pip} 被明確解除安裝時，則此模組的初始建置仍有可能用上。

@cartouche
@quotation 備註 
此模組`不會'通過網路存取。所有需要用來初始建置 @code{pip} 的元件都已包含在套件之內。
@end quotation
@end cartouche


@subsubheading 也參考



@table @asis

@item @ref{10f3,,安裝 Python 模組}

對於終端使用者安裝 Python 套件的指引

@geindex Python Enhancement Proposals; PEP 453

@item PEP 453@footnote{https://peps.python.org/pep-0453/}: 在 Python 安裝中的 pip 明確初始建置

此模組的最初設計理念與規範。
@end table


@c include for modules that don't work on WASM or mobile platforms

@ref{2006,,可用性}: not Android, not iOS, not WASI.

此模組在@ref{2120,,行動平台}或@ref{1a99,,WebAssembly 平台}上不支援。

@menu
* 命令列介面: 命令列介面<10>. 
* 模組 API:: 

@end menu

@node 命令列介面<10>,模組 API,,ensurepip --- pip 安裝器的初始建置 bootstrapping
@anchor{library/ensurepip command-line-interface}@anchor{4760}
@subsubsection 命令列介面


使用直譯器 (interpreter) 的 @code{-m} 來叫用命令列介面

最簡單可行的呼叫：

@example
python -m ensurepip
@end example

若 @code{pip} 未安裝，此呼叫會將其安裝；否則甚麼也不做。可透過傳入 @code{--upgrade} 參數來確保 @code{pip} 的安裝版本至少為目前 @code{ensurepip} 中最新可用的版本：

@example
python -m ensurepip --upgrade
@end example

預設上，@code{pip} 會被安裝至目前虛擬環境（若已啟動虛擬環境）或系統端的套件（若沒有啟動的虛擬環境）。安裝位置可透過兩個額外的命令列選項來控制：

@geindex ensurepip 命令列選項; --root
@anchor{library/ensurepip cmdoption-ensurepip-root}@anchor{4761}
@deffn {Option} @w{-}@w{-}root <dir>

安裝 @code{pip} 到給定的根目錄 (root directory) 的相對路徑，而不是目前虛擬環境（若存在）的根目錄，或目前 Python 安裝版所預設的根目錄。
@end deffn

@geindex ensurepip 命令列選項; --user
@anchor{library/ensurepip cmdoption-ensurepip-user}@anchor{4762}
@deffn {Option} @w{-}@w{-}user

安裝 @code{pip} 到使用者端的套件目錄，而不是全域安裝到目前的 Python 安裝版（此選項不允許在一啟動的虛擬環境中使用）。
@end deffn

預設會安裝 @code{pipX} 和 @code{pipX.Y} 腳本（X.Y 代表用來叫用 @code{ensurepip} 的 Python 之版本）。安裝的腳本可透過兩個額外的命令列選項來控制：

@geindex ensurepip 命令列選項; --altinstall
@anchor{library/ensurepip cmdoption-ensurepip-altinstall}@anchor{4763}
@deffn {Option} @w{-}@w{-}altinstall

若要求一個替代安裝版，則`不會'安裝 @code{pipX} 腳本。
@end deffn

@geindex ensurepip 命令列選項; --default-pip
@anchor{library/ensurepip cmdoption-ensurepip-default-pip}@anchor{4764}
@deffn {Option} @w{-}@w{-}default@w{-}pip

若要求安裝「預設 pip」，則會安裝 @code{pip} 腳本，及 2 個常規腳本。
@end deffn

提供兩種指令選項將會導致例外 (exception) 。

@node 模組 API,,命令列介面<10>,ensurepip --- pip 安裝器的初始建置 bootstrapping
@anchor{library/ensurepip module-api}@anchor{4765}
@subsubsection 模組 API


@ref{59,,ensurepip} 開放了兩個用於編寫程式的函式：

@geindex version() (於 ensurepip 模組中)
@anchor{library/ensurepip ensurepip version}@anchor{4766}
@deffn {函式} ensurepip.version ()

回傳一個字串，用以標明初始建置時，安裝的 pip 的可行版本號。
@end deffn

@geindex bootstrap() (於 ensurepip 模組中)
@anchor{library/ensurepip ensurepip bootstrap}@anchor{4614}
@deffn {函式} ensurepip.bootstrap (root=None, upgrade=False, user=False, altinstall=False, default_pip=False, verbosity=0)

在目前或指定的環境之中建立 @code{pip}。

`root' 指定一個替代的根目錄，作為安裝的相對路徑。若 `root' 為 @code{None}，則安裝使用目前環境的預設安裝位置。

`upgrade' 指出是否要將一個既有的較早版本的 @code{pip} 升級至可用的新版。

`user' 指出是否要使用使用者的安裝方案而不是全域安裝。

預設會安裝 @code{pipX} 和 @code{pipX.Y} 腳本（X.Y 代表 Python 的目前版本）。

如果啟用了 `altinstall'，則不會安裝 @code{pipX}。

如果啟用了 `default_pip'，則會安裝 @code{pip}，以及 2 個常規腳本。

同時啟用 `altinstall' 跟 `default_pip'，將會觸發 @ref{2eb,,ValueError}。

`verbosity' 用來控制初始建置操作內，對於 @ref{cc4,,sys.stdout} 的輸出等級。

引發一個附帶引數 @code{root} 的@ref{1b70,,稽核事件} @code{ensurepip.bootstrap}。

@cartouche
@quotation 備註 
初始建置的過程對於 @code{sys.path} 及 @code{os.environ} 均有副作用。改為在一子行程 (subprocess) 呼叫命令列介面可避免這些副作用。
@end quotation
@end cartouche

@cartouche
@quotation 備註 
初始建置的過程也許會安裝 @code{pip} 所需要的額外的模組，但其他軟體不應該假設這些相依 (dependency) 總是預設存在（因為這些相依很可能會在未來版本的 @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 --- 建立虛擬環境,zipapp —-- 管理可執行的 Python zip 封存檔案,ensurepip --- pip 安裝器的初始建置 bootstrapping,軟體封裝與發布
@anchor{library/venv doc}@anchor{4767}@anchor{library/venv module-venv}@anchor{117}@anchor{library/venv translation-repo}@anchor{4768}@anchor{library/venv venv-creation-of-virtual-environments}@anchor{4769}
@subsection @code{venv} --- 建立虛擬環境


@geindex module; venv


在 3.3 版被加入.


`原始碼：'Lib/venv/@footnote{https://github.com/python/cpython/tree/3.14/Lib/venv/}

@geindex Environments （環境）;virtual （虛擬）


__________________________________________________________________

@anchor{library/venv venv-def}@anchor{3e5}@anchor{library/venv venv-intro}@anchor{476a}
@code{venv} 模組支援建立輕量級的「虛擬環境」，每個虛擬環境都有獨立安裝在其 @ref{cc,,site} 目錄中的一組 Python 套件。虛擬環境是建立在既有的 Python 安裝上（稱為該虛擬環境的「基底」Python）之上，預設會與基底環境中的套件隔離，使得僅能存取明確安裝在虛擬環境中的套件。更多資訊請參閱 @ref{476b,,虛擬環境} 以及 @ref{cc,,site} 的@ref{476c,,虛擬環境文件}。

在使用虛擬環境中時，像 pip@footnote{https://pypi.org/project/pip/} 這樣的常用安裝工具會自動將 Python 套件安裝至虛擬環境中，而不需要額外指定。

虛擬環境是（主要的特性）：


@itemize *

@item 
用來包含特定的 Python 直譯器、函式庫與二進位檔案，以支援某個專案（函式庫或應用程式）。預設情況下，這些內容會與其他虛擬環境中的軟體以及作業系統中安裝的 Python 直譯器與函式庫隔離。

@item 
被包含在一個目錄中，通常命名為專案目錄下的 @code{.venv} 或 @code{venv}，也可能是在用來管理多個虛擬環境的容器目錄中，例如 @code{~/.virtualenvs}。

@item 
不應提交至 Git 等版本控制系統。

@item 
被視為可拋棄的資源——應能簡單地刪除並從頭重新建立。請勿將任何專案程式碼放置於虛擬環境中。

@item 
不應移動或複製——若需在其他位置使用，應重新建立相同的虛擬環境。
@end itemize

更多關於 Python 虛擬環境的背景資訊請見 
@geindex Python Enhancement Proposals; PEP 405
PEP 405@footnote{https://peps.python.org/pep-0405/}。


@subsubheading 也參考


Python 套件指南：建立與使用虛擬環境@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{2006,,可用性}: not Android, not iOS, not WASI.

此模組在@ref{2120,,行動平台}或@ref{1a99,,WebAssembly 平台}上不支援。

@menu
* 建立虛擬環境: 建立虛擬環境<2>. 
* 虛擬環境如何運作:: 
* API: API<2>. 
* 一個擴展 EnvBuilder 的範例:: 

@end menu

@node 建立虛擬環境<2>,虛擬環境如何運作,,venv --- 建立虛擬環境
@anchor{library/venv creating-virtual-environments}@anchor{476d}
@subsubsection 建立虛擬環境


@ref{3e5,,虛擬環境}是透過執行 @code{venv} 模組來建立：

@example
python -m venv /path/to/new/virtual/environment
@end example

執行此命令會建立目標目錄（同時也會建立任何還不存在的父目錄）並在目錄中放置一個名為 @code{pyvenv.cfg} 的檔案，其中包含一個指向執行該命令的 Python 安裝路徑的 @code{home} 鍵。它同時會建立一個 @code{bin} （在 Windows 上為 @code{Scripts}）子目錄，其中包含一個 Python 二進位檔案的副本/符號連結（根據建立環境時使用的平台或引數而定）。此外，它還會建立一個 @code{lib/pythonX.Y/site-packages} 子目錄（在 Windows 上為 @code{Lib\site-packages}）。如果指定的目錄已存在，則將重新使用該目錄。


在 3.5 版的變更: 目前建議使用 @code{venv} 來建立虛擬環境。



Deprecated since version 3.6, removed in version 3.8: @code{pyvenv} 是在 Python 3.3 和 3.4 中建立虛擬環境的推薦工具，但在 Python 3.5 中已被直接執行 @code{venv} 所取代。


在 Windows 上，執行以下命令以使用 @code{venv}：

@example
PS> python -m venv C:\path\to\new\virtual\environment
@end example

如果使用 @code{-h} 選項執行該命令，將會顯示可用的選項：

@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 命令列選項; ENV_DIR
@anchor{library/venv venv-cli}@anchor{476e}@anchor{library/venv cmdoption-venv-arg-ENV_DIR}@anchor{476f}
@deffn {Option} ENV_DIR

A required argument specifying the directory to create the environment in.
@end deffn

@geindex venv 命令列選項; --system-site-packages
@anchor{library/venv cmdoption-venv-system-site-packages}@anchor{4770}
@deffn {Option} @w{-}@w{-}system@w{-}site@w{-}packages

Give the virtual environment access to the system site-packages directory.
@end deffn

@geindex venv 命令列選項; --symlinks
@anchor{library/venv cmdoption-venv-symlinks}@anchor{4771}
@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 命令列選項; --copies
@anchor{library/venv cmdoption-venv-copies}@anchor{4772}
@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 命令列選項; --clear
@anchor{library/venv cmdoption-venv-clear}@anchor{4773}
@deffn {Option} @w{-}@w{-}clear

Delete the contents of the environment directory if it already exists, before environment creation.
@end deffn

@geindex venv 命令列選項; --upgrade
@anchor{library/venv cmdoption-venv-upgrade}@anchor{4774}
@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 命令列選項; --without-pip
@anchor{library/venv cmdoption-venv-without-pip}@anchor{4775}
@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 命令列選項; --prompt
@anchor{library/venv cmdoption-venv-prompt}@anchor{4776}
@deffn {Option} @w{-}@w{-}prompt <PROMPT>

Provides an alternative prompt prefix for this environment.
@end deffn

@geindex venv 命令列選項; --upgrade-deps
@anchor{library/venv cmdoption-venv-upgrade-deps}@anchor{4777}
@deffn {Option} @w{-}@w{-}upgrade@w{-}deps

Upgrade core dependencies (pip) to the latest version in PyPI.
@end deffn

@geindex venv 命令列選項; --without-scm-ignore-files
@anchor{library/venv cmdoption-venv-without-scm-ignore-files}@anchor{4778}
@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 版的變更: 預設會安裝 pip，並新增了 @code{--without-pip} 和 @code{--copies} 選項



在 3.4 版的變更: 在較早的版本中，如果目標目錄已存在，除非提供了 @code{--clear} 或 @code{--upgrade} 選項，否則會引發錯誤。



在 3.9 版的變更: 新增 @code{--upgrade-deps} 選項以將 pip 和 setuptools 升級至 PyPI 上的最新版本



在 3.12 版的變更: @code{setuptools} 不再是 venv 的核心相依套件。



在 3.13 版的變更: 新增 @code{--without-scm-ignore-files} 選項



在 3.13 版的變更: @code{venv} 現在預設會為 Git 建立 @code{.gitignore} 檔案。


@cartouche
@quotation 備註 
雖然在 Windows 上支援符號連結，但並不建議使用。特別需要注意的是，在檔案總管中按兩下 @code{python.exe} 會急切地解析符號連結並忽略虛擬環境。
@end quotation
@end cartouche

@cartouche
@quotation 備註 
在 Microsoft Windows 上，可能需要通過設置使用者的執行策略來啟用 @code{Activate.ps1} 腳本。你可以發出以下 PowerShell 命令來執行此操作：

@example
PS C:\> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
@end example

有關更多資訊，請參閱關於執行策略@footnote{https://go.microsoft.com/fwlink/?LinkID=135170}。
@end quotation
@end cartouche

被建立的 @code{pyvenv.cfg} 檔案還包括了 @code{include-system-site-packages} 的鍵，如果使用 @code{venv} 執行時帶有 @code{--system-site-packages} 選項，則設置為 @code{true}，否則設置為 @code{false}。

除非 @code{--without-pip} 選項被提供，否則將叫用 @ref{59,,ensurepip} 來啟動 @code{pip} 到虛擬環境中。

可以向 @code{venv} 提供多個路徑，這樣每個提供的路徑都將根據給定的選項建立一個相同的虛擬環境。

@node 虛擬環境如何運作,API<2>,建立虛擬環境<2>,venv --- 建立虛擬環境
@anchor{library/venv how-venvs-work}@anchor{4779}@anchor{library/venv venv-explanation}@anchor{676}
@subsubsection 虛擬環境如何運作


當 Python 直譯器跑在虛擬環境時，@ref{3e6,,sys.prefix} 和 @ref{3e9,,sys.exec_prefix} 會指向虛擬環境的目錄，而 @ref{3e4,,sys.base_prefix} 和 @ref{3e8,,sys.base_exec_prefix} 會指向建立虛擬環境的基礎 Python 的目錄。檢查 @code{sys.prefix != sys.base_prefix} 就可以確定目前的直譯器是否跑在虛擬環境中。

虛擬環境可以透過位於二進位檔案目錄中的腳本「啟用」（在 POSIX 上為 @code{bin}；在 Windows 上為 @code{Scripts}）這會將該目錄加入到你的 
@geindex PATH
@geindex 環境變數; PATH
@code{PATH}，當你運行 @code{python} 時就會叫用該環境的直譯器並且執行已安裝的腳本，而不需要使用完整的路徑。啟動腳本的方式因平台而異（@code{@var{<venv>}} 需要替換成包含虛擬環境的目錄路徑）


@multitable {xxxxxxxxxxxxxxx} {xxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

平台

@tab

Shell

@tab

啟動虛擬環境的指令

@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



在 3.4 版被加入: @code{fish} 和 @code{csh} 啟動腳本。



在 3.8 版被加入: PowerShell 的啟動腳本安裝在 POSIX 上支援 PowerShell Core。


你不用特別開啟虛擬環境，你可以在呼叫 Python 時指定該環境下 Python 直譯器的完整路徑。此外，所有安裝在環境裡的腳本都應該都可以在未啟用虛擬環境的情況下運行。

為了實現這一點，安裝在虛擬環境中的腳本會有一個 "shebang" 列，此列指向該環境的 Python 直譯器 @code{#!/@var{<path-to-venv>}/bin/python}。這代表無論 
@geindex PATH
@geindex 環境變數; PATH
@code{PATH} 的值為何，該腳本都會在直譯器上運行。在 Windows 上，如果你安裝了 @ref{7d3,,Python 安裝管理員}，則支援 "shebang" 列處理。因此，在 Windows 檔案總管（Windows Explorer）中雙擊已安裝的腳本，應該可以在沒有啟用環境或將其加入 
@geindex PATH
@geindex 環境變數; PATH
@code{PATH} 的情況下正確地運行。

當虛擬環境被啟用時，@code{VIRTUAL_ENV} 環境變數會被設置為該環境的路徑。由於不需要明確啟用虛擬環境才能使用它。因此，無法依賴 @code{VIRTUAL_ENV} 來判斷是否正在使用虛擬環境。

@cartouche
@quotation 警告 
因為安裝在環境中的腳本不應該預期該環境已經被啟動，所以它們的 shebang 列會包含環境直譯器的絕對路徑。因此，在一般情況下，環境本質上是不可攜帶的。你應該使用一個簡單的方法來重新建立一個環境（例如：如果你有一個名為 @code{requirements.txt} 的需求檔案，你可以使用環境的 @code{pip install -r requirements.txt} 來安裝環境所需的所有套件）。如果出於某種原因，你需要將環境移至新位置，你應該在所需位置重新建立它，並刪除舊位置的環境。如果你移動環境是因為移動了其父目錄，你應該在新位置重新建立環境。否則，安裝在該環境中的軟體可能無法正常運作。
@end quotation
@end cartouche

你可以在 shell 輸入 @code{deactivate} 來關閉虛擬環境。具體的使用方式因平台而異，是內部實作的細節（通常會使用腳本或是 shell 函式）

@node API<2>,一個擴展 EnvBuilder 的範例,虛擬環境如何運作,venv --- 建立虛擬環境
@anchor{library/venv api}@anchor{477a}@anchor{library/venv venv-api}@anchor{10f0}
@subsubsection API


上述提到的高階 method（方法）透過簡單的 API 使用， 為第三方虛擬環境建立者提供可以依據他們需求來建立環境的客製化機制： @ref{56b,,EnvBuilder} class。

@geindex EnvBuilder (venv 中的類別)
@anchor{library/venv venv EnvBuilder}@anchor{56b}
@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())

進行實例化時，class @ref{56b,,EnvBuilder} 接受下列的關鍵字引數：


@itemize *

@item 
`system_site_packages' -- 為一個 boolean （布林值），並表明系統的 Python site-packages 是否可以在環境中可用（預設為 @code{False} ）。

@item 
`clear' -- 為一個 boolean，如果為 true，則在建立環境之前，刪除目標目錄內所有存在的內容。

@item 
`symlinks' --  為一個 boolean，並表明是否嘗試與 Python 二進位檔案建立符號連結而不是複製該檔案。

@item 
`upgrade' -- 為一個 boolean，若為 true，則會在執行 Python 時為現有的環境進行升級。目的是讓 Python 可以升級到位（預設為 @code{False}）。

@item 
`with_pip' -- 為一個 boolean，若為 true，則確保 pip 有安裝至虛擬環境之中。當有 @code{--default-pip} 的選項時，會使用 @ref{59,,ensurepip}。

@item 
`prompt' -- 為一個 String（字串），該字串會在虛擬環境啟動時被使用。（預設為 @code{None}，代表該環境的目錄名稱會被使用）倘若出現特殊字串 @code{"."} ，則目前目錄的 basename 會做為提示路徑使用。

@item 
`upgrade_deps' -- 更新基礎 venv 模組至 PyPI 的最新版本

@item 
`scm_ignore_files'——根據可疊代物件中指定的來源控制管理（SCM），建立對應的忽略檔。支援情況取決於是否有名為 @code{create_@{scm@}_ignore_file} 的方法。預設唯一支援的值是 @code{"git"}，透過 @ref{477b,,create_git_ignore_file()} 方法提供支援。
@end itemize


在 3.4 版的變更: 新增 @code{with_pip} 參數



在 3.6 版的變更: 新增 @code{prompt} 參數



在 3.9 版的變更: 新增 @code{upgrade_deps} 參數



在 3.13 版的變更: 新增 @code{scm_ignore_files} 參數


@ref{56b,,EnvBuilder} 可以被用作為基底類別。

@geindex create() (venv.EnvBuilder 的方法)
@anchor{library/venv venv EnvBuilder create}@anchor{477c}
@deffn {方法} create (env_dir)

透過指定將會容納虛擬環境的目標目錄來建立一個虛擬環境（絕對路徑或相對路徑到該目錄），也就是在該目錄中容納虛擬環境。@code{create} method 將會在指定的目錄下建立環境，或是觸發適當的例外。

@ref{56b,,EnvBuilder} class 的 @code{create} method 會闡述可用的 Hooks 以客製化 subclass （子類別）:

@example
def create(self, env_dir):
    """
    在目標目錄中建立一個虛擬化的 Python 環境。
    env_dir 是要建立虛擬環境的目標目錄。
    """
    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

每個 methods @ref{477d,,ensure_directories()}、@ref{477e,,create_configuration()}、@ref{477f,,setup_python()}、@ref{4780,,setup_scripts()} 及 @ref{4781,,post_setup()} 都可以被覆寫。
@end deffn

@geindex ensure_directories() (venv.EnvBuilder 的方法)
@anchor{library/venv venv EnvBuilder ensure_directories}@anchor{477d}
@deffn {方法} ensure_directories (env_dir)

建立還不存在的環境目錄及必要的子目錄，並回傳一個情境物件（context object）。這個情境物件只是一個屬性 (例如：路徑) 的所有者，可被其他 method 使用。如果 @ref{56b,,EnvBuilder} 已被建立且帶有 @code{clear=True} 的引數，該環境目錄下的內容將被清空，以及所有必要的子目錄將被重新建立。

回傳的情境物件（context object）其型別會是 @ref{4e0,,types.SimpleNamespace}，並包含以下屬性：


@itemize *

@item 
@code{env_dir} —— 虛擬環境的位置。用於啟用腳本中的 @code{__VENV_DIR__}（參見 @ref{4782,,install_scripts()}）。

@item 
@code{env_name} —— 虛擬環境的名稱。用於啟用腳本中的 @code{__VENV_NAME__}（參見 @ref{4782,,install_scripts()}）。

@item 
@code{prompt} —— 啟用腳本所使用的提示字元。用於啟用腳本中的 @code{__VENV_PROMPT__}（參見 @ref{4782,,install_scripts()}）。

@item 
@code{executable} —— 虛擬環境所使用的底層 Python 執行檔。在從其他虛擬環境建立虛擬環境的情況下，也會一併考慮該情境。

@item 
@code{inc_path} —— 虛擬環境的 include 路徑。

@item 
@code{lib_path} —— 虛擬環境的 purelib 路徑。

@item 
@code{bin_path} —— 虛擬環境的腳本路徑。

@item 
@code{bin_name} —— 相對於虛擬環境位置的腳本路徑名稱。用於啟用腳本中的 @code{__VENV_BIN_NAME__}（參見 @ref{4782,,install_scripts()}）。

@item 
@code{env_exe} —— 虛擬環境中 Python 直譯器的名稱。用於啟用腳本中的 @code{__VENV_PYTHON__}（參見 @ref{4782,,install_scripts()}）。

@item 
@code{env_exec_cmd} —— Python 直譯器名稱，會將檔案系統重新導向後納入考慮。可用於在虛擬環境中執行 Python。
@end itemize


在 3.11 版的變更: `venv' 使用 @ref{447,,sysconfig 安裝配置方案} 來建構所建立目錄的路徑。



在 3.12 版的變更: @code{lib_path} 屬性已新增至情境中，且情境物件已加入文件說明。

@end deffn

@geindex create_configuration() (venv.EnvBuilder 的方法)
@anchor{library/venv venv EnvBuilder create_configuration}@anchor{477e}
@deffn {方法} create_configuration (context)

在環境中建立 @code{pyvenv.cfg} 設定檔。
@end deffn

@geindex setup_python() (venv.EnvBuilder 的方法)
@anchor{library/venv venv EnvBuilder setup_python}@anchor{477f}
@deffn {方法} setup_python (context)

在環境中建立 Python 執行檔的複本或符號連結。在 POSIX 系統上，若使用了特定的 @code{python3.x} 執行檔，將建立指向該執行檔的 @code{python} 與 @code{python3} 符號連結（除非這些名稱的檔案已存在）。
@end deffn

@geindex setup_scripts() (venv.EnvBuilder 的方法)
@anchor{library/venv venv EnvBuilder setup_scripts}@anchor{4780}
@deffn {方法} setup_scripts (context)

將符合平台的啟用腳本安裝到虛擬環境中。
@end deffn

@geindex upgrade_dependencies() (venv.EnvBuilder 的方法)
@anchor{library/venv venv EnvBuilder upgrade_dependencies}@anchor{4783}
@deffn {方法} upgrade_dependencies (context)

更新虛擬環境中的核心 venv 相依套件（目前為 pip@footnote{https://pypi.org/project/pip/}）。此動作會透過執行虛擬環境中的 @code{pip} 執行檔來完成。


在 3.9 版被加入.



在 3.12 版的變更: setuptools@footnote{https://pypi.org/project/setuptools/} 不再是核心 venv 的相依項目。

@end deffn

@geindex post_setup() (venv.EnvBuilder 的方法)
@anchor{library/venv venv EnvBuilder post_setup}@anchor{4781}
@deffn {方法} post_setup (context)

此佔位方法在虛擬環境中預先安裝套件，或執行其他建立後的動作，可由第三方實作覆寫。
@end deffn

@geindex install_scripts() (venv.EnvBuilder 的方法)
@anchor{library/venv venv EnvBuilder install_scripts}@anchor{4782}
@deffn {方法} install_scripts (context, path)

此方法可由子類別中的 @ref{4780,,setup_scripts()} 或 @ref{4781,,post_setup()} 呼叫，協助將自訂腳本安裝到虛擬環境中。

`path' 是一個目錄的路徑，該目錄應包含子目錄 @code{common}、@code{posix} 和 @code{nt}；每個子目錄中都包含指向環境中 @code{bin} 目錄的腳本。在執行部分佔位符文字替換後，將會複製 @code{common} 及與 @ref{2eb5,,os.name} 對應的目錄的內容：


@itemize *

@item 
@code{__VENV_DIR__} 會被替換為環境目錄的絕對路徑。

@item 
@code{__VENV_NAME__} 會被替換為環境的名稱（即該環境目錄路徑的最後一段）。

@item 
@code{__VENV_PROMPT__} 會被替換為提示字元（即以括號包裹的環境名稱，並附帶一個空格）。

@item 
@code{__VENV_BIN_NAME__} 會被替換為 bin 目錄的名稱（可能是 @code{bin} 或 @code{Scripts}）。

@item 
@code{__VENV_PYTHON__} 會被替換為環境中 Python 執行檔的絕對路徑。
@end itemize

允許這些目錄存在（例如當更新既有環境時）。
@end deffn

@geindex create_git_ignore_file() (venv.EnvBuilder 的方法)
@anchor{library/venv venv EnvBuilder create_git_ignore_file}@anchor{477b}
@deffn {方法} create_git_ignore_file (context)

在虛擬環境中建立一個 @code{.gitignore} 檔案，讓 Git 原始碼控管工具忽略整個目錄。


在 3.13 版被加入.

@end deffn


在 3.7.2 版的變更: Windows 現在使用重新導向腳本來處理 @code{python[w].exe}，而不再複製實際的二進位檔。在 3.7.2 中，只有當從原始碼樹中建構時，@ref{477f,,setup_python()} 才會執行操作。



在 3.7.3 版的變更: Windows會在 @ref{477f,,setup_python()} 中複製重新導向腳本，而非在 @ref{4780,,setup_scripts()} 中進行。這在 3.7.2 中並非如此。若使用符號連結，則會連結至原始的可執行檔。

@end deffn

也有一個方便的模組層級的函式：

@geindex create() (於 venv 模組中)
@anchor{library/venv venv create}@anchor{56c}
@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())

使用提供的關鍵字引數建立一個 @ref{56b,,EnvBuilder}，並以 `env_dir' 作為引數呼叫其 @ref{477c,,create()} 方法。


在 3.3 版被加入.



在 3.4 版的變更: 新增 `with_pip' 參數



在 3.6 版的變更: 新增 `prompt' 參數



在 3.9 版的變更: 新增 `upgrade_deps' 參數



在 3.13 版的變更: 新增 `scm_ignore_files'  參數

@end deffn

@node 一個擴展 EnvBuilder 的範例,,API<2>,venv --- 建立虛擬環境
@anchor{library/venv an-example-of-extending-envbuilder}@anchor{4784}
@subsubsection 一個擴展 @code{EnvBuilder} 的範例


以下的腳本展示了如何透過實作子類別來擴充 @ref{56b,,EnvBuilder}，並在建立的虛擬環境中安裝 setuptools 與 pip：

@example
import os
import os.path
from subprocess import Popen, PIPE
import sys
from threading import Thread
from urllib.parse import urlparse
from urllib.request import urlretrieve
import venv

class ExtendedEnvBuilder(venv.EnvBuilder):
    """
    此建構子會安裝 setuptools 和 pip，使你能夠使用 pip 或
    easy_install 安裝其他套件到建立的虛擬環境中。

    :param nodist: 若為 true，則不會安裝 setuptools 和 pip 至
                   所建立的虛擬環境中。
    :param nopip: 若為 true，則不會安裝 pip 至所建立的
                  虛擬環境中。
    :param progress: 若安裝了 setuptools 或 pip，可透過傳入 progress
                     可呼叫物件來監控安裝進度。若有指定，該可呼叫物件會接收兩個引數：
                     一個表示進度的字串，以及一個表示該字串來源的情境。
                     context 引數可能有三種值：
                     'main' 表示該呼叫來自 virtualize() 本身，
                     'stdout' 與 'stderr' 則分別表示從子行程輸出資料串流中
                     讀取的輸出內容，該子行程用於安裝應用程式。

                     若未指定可呼叫物件，則預設的進度資訊會輸出至 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):
        """
        設定在建立虛擬環境時需預先安裝的套件。

        :param context: 處理中的虛擬環境建立請求所需的資訊。
        """
        os.environ['VIRTUAL_ENV'] = context.env_dir
        if not self.nodist:
            self.install_setuptools(context)
       # 沒有 setuptools 就無法安裝 pip
        if not self.nopip and not self.nodist:
            self.install_pip(context)

    def reader(self, stream, context):
        """
        從子行程的輸出串流中讀取每一列，並將其傳遞給進度回呼函式（若有指定），或將進度資訊寫入 sys.stderr。
        """
        progress = self.progress
        while True:
            s = stream.readline()
            if not s:
                break
            if progress is not None:
                progress(s, context)
            else:
                if not self.verbose:
                    sys.stderr.write('.')
                else:
                    sys.stderr.write(s.decode('utf-8'))
                sys.stderr.flush()
        stream.close()

    def install_script(self, context, name, url):
        _, _, path, _, _, _ = urlparse(url)
        fn = os.path.split(path)[-1]
        binpath = context.bin_path
        distpath = os.path.join(binpath, fn)
        # 將腳本下載到虛擬環境的執行檔資料夾中
        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()
        # 安裝到虛擬環境中
        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')
        # 清理——不再需要
        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)
        # 清除已下載的 setuptools 檔案
        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):
        """
        在虛擬環境中安裝 pip。

        :param context: 處理中的虛擬環境建立請求相關資訊。
        """
        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

此腳本也可從線上@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 —-- 管理可執行的 Python zip 封存檔案,,venv --- 建立虛擬環境,軟體封裝與發布
@anchor{library/zipapp doc}@anchor{4785}@anchor{library/zipapp module-zipapp}@anchor{136}@anchor{library/zipapp translation-repo}@anchor{4786}@anchor{library/zipapp zipapp-manage-executable-python-zip-archives}@anchor{4787}
@subsection @code{zipapp} —-- 管理可執行的 Python zip 封存檔案


@geindex module; zipapp


在 3.5 版被加入.


`原始碼：'Lib/zipapp.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/zipapp.py}

@geindex Executable Zip Files（可執行的 Zip 檔案）


__________________________________________________________________


本模組提供工具來建立包含 Python 程式碼的 zip 檔案，這些檔案可以 @ref{1fe1,,直接由 Python 直譯器執行}。此模組同時提供了 @ref{4788,,zipapp 命令列介面} 和 @ref{4789,,zipapp Python API}。

@menu
* 基本範例:: 
* 命令列介面: 命令列介面<11>. 
* Python API:: 
* 範例: 範例<45>. 
* 指定直譯器:: 
* 使用 zipapp 建立獨立應用程式:: 
* Python Zip 應用程式封存檔案格式:: 

@end menu

@node 基本範例,命令列介面<11>,,zipapp —-- 管理可執行的 Python zip 封存檔案
@anchor{library/zipapp basic-example}@anchor{478a}
@subsubsection 基本範例


以下範例展示了如何使用 @ref{4788,,zipapp 命令列介面}，從一個包含 Python 程式碼的目錄中建立一個可執行的封存檔案。執行時，該封存檔案將會執行封存檔案中 @code{myapp} 模組的 @code{main} 函式。

@example
$ python -m zipapp myapp -m "myapp:main"
$ python myapp.pyz
<output from myapp>
@end example

@node 命令列介面<11>,Python API,基本範例,zipapp —-- 管理可執行的 Python zip 封存檔案
@anchor{library/zipapp command-line-interface}@anchor{478b}@anchor{library/zipapp zipapp-command-line-interface}@anchor{4788}
@subsubsection 命令列介面


當從命令列作為程式呼叫時，會使用以下格式：

@example
$ python -m zipapp source [options]
@end example

如果 `source' 是一個目錄，這將會從 `source' 的內容建立一個封存檔案。如果 `source' 是一個檔案，它應該是一個封存檔案，並且它將被複製到目標封存檔案（或者如果指定了 --info 選項，將會顯示其 shebang 行的內容）。

可使用以下選項：

@geindex zipapp 命令列選項; -o
@geindex zipapp 命令列選項; --output
@anchor{library/zipapp cmdoption-zipapp-o}@anchor{478c}@anchor{library/zipapp cmdoption-zipapp-output}@anchor{478d}
@deffn {Option} @w{-}o <output>, @w{-}@w{-}output=<output>

將輸出寫入名為 `output' 的檔案。如果未指定此選項，輸出檔名將與輸入 `source' 相同，並加上 @code{.pyz} 副檔名。如果給定了明確的檔名，則會直接使用它（因此如果需要，應包含 @code{.pyz} 副檔名）。

如果 `source' 是一個封存檔案，則必須指定輸出檔名（且在這種情況下，`output' 不得與 `source' 相同）。
@end deffn

@geindex zipapp 命令列選項; -p
@geindex zipapp 命令列選項; --python
@anchor{library/zipapp cmdoption-zipapp-p}@anchor{478e}@anchor{library/zipapp cmdoption-zipapp-python}@anchor{478f}
@deffn {Option} @w{-}p <interpreter>, @w{-}@w{-}python=<interpreter>

在封存檔案中加入一行 @code{#!}，指定 `interpreter' 作為要執行的命令。此外，在 POSIX 上，使封存檔案成為可執行檔。預設是不寫入 @code{#!} 行，也不讓檔案成為可執行檔。
@end deffn

@geindex zipapp 命令列選項; -m
@geindex zipapp 命令列選項; --main
@anchor{library/zipapp cmdoption-zipapp-m}@anchor{4790}@anchor{library/zipapp cmdoption-zipapp-main}@anchor{4791}
@deffn {Option} @w{-}m <mainfn>, @w{-}@w{-}main=<mainfn>

在封存檔案中寫入一個執行 `mainfn' 的 @code{__main__.py} 檔案。`mainfn' 引數應為 "pkg.mod:fn" 的形式，其中 "pkg.mod" 是封存檔案中的一個套件/模組，而 "fn" 是給定模組中的一個可呼叫物件。@code{__main__.py} 檔案將會執行該可呼叫物件。

複製封存檔案時，不可指定 @ref{4790,,--main}。
@end deffn

@geindex zipapp 命令列選項; -c
@geindex zipapp 命令列選項; --compress
@anchor{library/zipapp cmdoption-zipapp-c}@anchor{4792}@anchor{library/zipapp cmdoption-zipapp-compress}@anchor{4793}
@deffn {Option} @w{-}c, @w{-}@w{-}compress

使用 deflate 方法壓縮檔案，以減少輸出檔案的大小。預設情況下，檔案在封存檔案中是不壓縮儲存的。

複製封存檔案時，@ref{4792,,--compress} 沒有作用。


在 3.7 版被加入.

@end deffn

@geindex zipapp 命令列選項; --info
@anchor{library/zipapp cmdoption-zipapp-info}@anchor{4794}
@deffn {Option} @w{-}@w{-}info

顯示嵌入在封存檔案中的直譯器，以供診斷之用。在這種情況下，任何其他選項都會被忽略，且 SOURCE 必須是一個封存檔案，而不是一個目錄。
@end deffn

@geindex zipapp 命令列選項; -h
@geindex zipapp 命令列選項; --help
@anchor{library/zipapp cmdoption-zipapp-h}@anchor{4795}@anchor{library/zipapp cmdoption-zipapp-help}@anchor{4796}
@deffn {Option} @w{-}h, @w{-}@w{-}help

印出簡短的使用訊息並退出。
@end deffn

@node Python API,範例<45>,命令列介面<11>,zipapp —-- 管理可執行的 Python zip 封存檔案
@anchor{library/zipapp python-api}@anchor{4797}@anchor{library/zipapp zipapp-python-api}@anchor{4789}
@subsubsection Python API


此模組定義了兩個便利的函式：

@geindex create_archive() (於 zipapp 模組中)
@anchor{library/zipapp zipapp create_archive}@anchor{da4}
@deffn {函式} zipapp.create_archive (source, target=None, interpreter=None, main=None, filter=None, compressed=False)

從 `source' 建立一個應用程式封存檔案。source 可以是以下任何一種：


@itemize *

@item 
一個目錄的名稱，或是一個指向目錄的 @ref{59b,,類路徑物件}，在這種情況下，將會從該目錄的內容建立一個新的應用程式封存檔案。

@item 
一個現有應用程式封存檔案的名稱，或是一個指向該檔案的 @ref{59b,,類路徑物件}，在這種情況下，該檔案會被複製到目標（並修改它以反映為 `interpreter' 引數所給定的值）。如果需要，檔名應包含 @code{.pyz} 副檔名。

@item 
一個以位元組模式開啟以供讀取的檔案物件。該檔案的內容應該是一個應用程式封存檔案，並且檔案物件被假定位於封存檔案的開頭。
@end itemize

`target' 引數決定了產生的封存檔案將被寫入何處：


@itemize *

@item 
如果它是一個檔案的名稱，或是一個 @ref{59b,,類路徑物件}，封存檔案將被寫入該檔案。

@item 
如果它是一個開啟的檔案物件，封存檔案將被寫入該檔案物件，該物件必須以位元組模式開啟以供寫入。

@item 
如果省略了 target（或為 @code{None}），則 source 必須是一個目錄，而 target 將是一個與 source 同名的檔案，並加上 @code{.pyz} 副檔名。
@end itemize

`interpreter' 引數指定了將用來執行封存檔案的 Python 直譯器名稱。它會作為「shebang」行寫入封存檔案的開頭。在 POSIX 上，這將由作業系統解讀，而在 Windows 上，它將由 Python 啟動器處理。省略 `interpreter' 將導致不寫入 shebang 行。如果指定了直譯器，且 target 是一個檔名，則目標檔案的可執行位元將被設定。

`main' 引數指定了一個可呼叫物件的名稱，它將被用作封存檔案的主程式。只有當 source 是一個目錄，且該 source 尚未包含 @code{__main__.py} 檔案時，才能指定此引數。`main' 引數應採用「pkg.module:callable」的形式，封存檔案將透過引入「pkg.module」並執行給定的無引數可呼叫物件來執行。如果 source 是一個目錄且不包含 @code{__main__.py} 檔案，則省略 `main' 會導致錯誤，因為這樣產生的封存檔案將無法執行。

可選的 `filter' 引數指定了一個回呼函式，該函式會被傳入一個 Path 物件，代表要加入的檔案路徑（相對於 source 目錄）。如果要加入該檔案，它應該回傳 @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{4798}
@deffn {函式} zipapp.get_interpreter (archive)

回傳封存檔案開頭 @code{#!} 行中指定的直譯器。如果沒有 @code{#!} 行，則回傳 @ref{87e,,None}。`archive' 引數可以是一個檔名或一個以位元組模式開啟以供讀取的類檔案物件。它被假定位於封存檔案的開頭。
@end deffn

@node 範例<45>,指定直譯器,Python API,zipapp —-- 管理可執行的 Python zip 封存檔案
@anchor{library/zipapp examples}@anchor{4799}@anchor{library/zipapp zipapp-examples}@anchor{479a}
@subsubsection 範例


將一個目錄打包成一個封存檔案，並執行它。

@example
$ python -m zipapp myapp
$ python myapp.pyz
<output from myapp>
@end example

使用 @ref{da4,,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{da4,,create_archive()} 函式建立一個修改過的封存檔案：

@example
>>> import zipapp
>>> zipapp.create_archive('old_archive.pyz', 'new_archive.pyz', '/usr/bin/python3')
@end example

要原地 (in place) 更新檔案，請使用 @ref{109f,,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 建立獨立應用程式,範例<45>,zipapp —-- 管理可執行的 Python zip 封存檔案
@anchor{library/zipapp specifying-the-interpreter}@anchor{479b}@anchor{library/zipapp zipapp-specifying-the-interpreter}@anchor{479c}
@subsubsection 指定直譯器


請注意，如果你指定了一個直譯器然後分發你的應用程式封存檔案，你需要確保所使用的直譯器是可攜的。Windows 的 Python 啟動器支援大多數常見形式的 POSIX @code{#!} 行，但還有其他問題需要考慮：


@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」這樣的確切版本，因為舉例來說，你將需要為 Python 3.5 的使用者更改你的 shebang 行。
@end itemize

通常，你應該使用「/usr/bin/env python2」或「/usr/bin/env python3」，這取決於你的程式碼是為 Python 2 還是 Python 3 編寫的。

@node 使用 zipapp 建立獨立應用程式,Python Zip 應用程式封存檔案格式,指定直譯器,zipapp —-- 管理可執行的 Python zip 封存檔案
@anchor{library/zipapp creating-standalone-applications-with-zipapp}@anchor{479d}
@subsubsection 使用 zipapp 建立獨立應用程式


使用 @ref{136,,zipapp} 模組，可以建立獨立的 Python 程式，這些程式可以分發給終端使用者，他們只需要在他們的系統上安裝合適版本的 Python。實現這一點的關鍵是將應用程式的所有依賴項與應用程式程式碼一起打包到封存檔案中。

建立獨立封存檔案的步驟如下：


@enumerate 

@item 
像平常一樣在一個目錄中建立你的應用程式，這樣你就有一個 @code{myapp} 目錄，其中包含一個 @code{__main__.py} 檔案和任何支援的應用程式程式碼。

@item 
使用 pip 將你應用程式的所有依賴項安裝到 @code{myapp} 目錄中：

@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{479c,,指定直譯器}。它可以作為單一檔案交付給使用者。

在 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{479e}
@subsubsection 注意事項


如果你的應用程式依賴於一個包含 C 擴充的套件，該套件無法從 zip 檔案中執行（這是一個作業系統的限制，因為可執行程式碼必須存在於檔案系統中，作業系統的載入器才能載入它）。在這種情況下，你可以從 zipfile 中排除該依賴項，並要求你的使用者安裝它，或者將它與你的 zipfile 一起發布，並在你的 @code{__main__.py} 中加入程式碼，將包含解壓縮後模組的目錄加入到 @code{sys.path} 中。在這種情況下，你需要確保為你的目標架構提供適當的二進位檔案（並可能在 runtime 根據使用者的機器選擇正確的版本加入到 @code{sys.path} 中）。

@node Python Zip 應用程式封存檔案格式,,使用 zipapp 建立獨立應用程式,zipapp —-- 管理可執行的 Python zip 封存檔案
@anchor{library/zipapp the-python-zip-application-archive-format}@anchor{479f}
@subsubsection Python Zip 應用程式封存檔案格式


自 2.6 版以來，Python 就能夠執行包含 @code{__main__.py} 檔案的 zip 檔案。為了能被 Python 執行，一個應用程式封存檔案只需要是一個標準的 zip 檔案，其中包含一個 @code{__main__.py} 檔案，該檔案將作為應用程式的進入點執行。如同任何 Python 腳本一樣，腳本的父目錄（在此情況下是 zip 檔案）將被放置在 @ref{3e2,,sys.path} 上，因此可以從 zip 檔案中引入更多的模組。

zip 檔案格式允許在 zip 檔案前附加任意資料。zip 應用程式格式利用此功能在檔案前附加一個標準的 POSIX「shebang」行（@code{#!/path/to/interpreter}）。

因此，Python zip 應用程式格式的正式定義如下：


@enumerate 

@item 
一個可選的 shebang 行，包含字元 @code{b'#!'}，後跟一個直譯器名稱，然後是一個換行符（@code{b'\n'}）。直譯器名稱可以是任何作業系統「shebang」處理或 Windows 上的 Python 啟動器可接受的內容。在 Windows 上，直譯器應以 UTF-8 編碼，在 POSIX 上應以 @ref{e4e,,sys.getfilesystemencoding()} 編碼。

@item 
由 @ref{137,,zipfile} 模組產生的標準 zipfile 資料。zipfile 內容*必須*包含一個名為 @code{__main__.py} 的檔案（該檔案必須位於 zipfile 的「根目錄」中——即，它不能在子目錄中）。zipfile 資料可以被壓縮或不壓縮。
@end enumerate

如果應用程式封存檔案有 shebang 行，它在 POSIX 系統上可能會設定可執行位元，以允許其直接執行。

沒有要求必須使用此模組中的工具來建立應用程式封存檔案——此模組是一個便利工具，但以任何方式建立的符合上述格式的封存檔案對 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 服務,自訂 Python 直譯器,軟體封裝與發布,Python 標準函式庫 Standard Library
@anchor{library/python doc}@anchor{47a0}@anchor{library/python python}@anchor{47a1}@anchor{library/python python-runtime-services}@anchor{47a2}@anchor{library/python translation-repo}@anchor{47a3}
@section Python Runtime 服務


本章節所描述的模組提供了與 Python 直譯器及其與環境互動相關的廣泛服務。以下是概觀：

@menu
* sys: sys --- 系統特定的參數與函式. 系統特定的參數與函式
* sys.monitoring: sys monitoring --- 執行事件監控. 執行事件監控
* sysconfig: sysconfig --- 提供 Python 設定資訊的存取. 提供 Python 設定資訊的存取
* builtins: builtins --- 內建物件. 內建物件
* __main__: __main__ --- 頂層程式碼環境. 頂層程式碼環境
* warnings: warnings --- 警告控制. 警告控制
* dataclasses: dataclasses --- Data Classes. Data Classes
* contextlib: contextlib --- with 陳述式工具程式. with 陳述式工具程式
* abc: abc --- 抽象基底類別. 抽象基底類別
* atexit: atexit --- 退出處理函式. 退出處理函式
* traceback: traceback --- 列印或取得堆疊回溯 stack traceback. 列印或取得堆疊回溯 (stack traceback)
* __future__: __future__ --- Future 陳述式定義. Future 陳述式定義
* gc: gc --- 垃圾回收器介面 Garbage Collector interface. 垃圾回收器介面 (Garbage Collector interface)
* inspect: inspect --- 檢視活動物件. 檢視活動物件
* annotationlib: annotationlib --- 用於自我檢查註釋的功能. 用於自我檢查註釋的功能
* site: site --- Site-specific configuration hook. Site-specific configuration hook

@end menu

@node sys --- 系統特定的參數與函式,sys monitoring --- 執行事件監控,,Python Runtime 服務
@anchor{library/sys doc}@anchor{47a4}@anchor{library/sys module-sys}@anchor{df}@anchor{library/sys sys-system-specific-parameters-and-functions}@anchor{47a5}
@subsection @code{sys} --- 系統特定的參數與函式


@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 abiflags (於 sys 模組中)
@anchor{library/sys sys abiflags}@anchor{c50}
@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/}.


在 3.2 版被加入.



在 3.8 版的變更: Default flags became an empty string (@code{m} flag for pymalloc has been
removed).


@ref{2006,,可用性}: Unix.
@end deffn

@geindex addaudithook() (於 sys 模組中)
@anchor{library/sys sys addaudithook}@anchor{4609}
@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{1882,,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{460a,,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{460a,,PySys_AddAuditHook()} before initialising the runtime, and any
modules allowing arbitrary memory modification (such as @ref{2e,,ctypes}) should
be completely removed or closely monitored.

呼叫 @ref{4609,,sys.addaudithook()} 本身會引發一個不帶任何引數、名為 @code{sys.addaudithook} 的稽核事件。如果任何現有的 hook 引發從 @ref{244,,RuntimeError} 衍生的例外，則不會添加新的 hook 並抑制異常。因此，除非呼叫者控制所有已存在的 hook，他們不能假設他們的 hook 已被添加。

所有會被 CPython 所引發的事件請參考@ref{1b27,,稽核事件總表}、設計相關討論請見 
@geindex Python Enhancement Proposals; PEP 578
PEP 578@footnote{https://peps.python.org/pep-0578/}。


在 3.8 版被加入.



在 3.8.1 版的變更: Exceptions derived from @ref{bc4,,Exception} but not @ref{244,,RuntimeError}
are no longer suppressed.


`CPython 實作細節：' When tracing is enabled (see @ref{2e1,,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{1465}
@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{1a8,,-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{5f,,fileinput} module.

另請參閱 @ref{a3a,,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{1b70}@anchor{library/sys sys audit}@anchor{1882}
@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.

舉例來說，一個名為 @code{os.chdir} 的稽核事件擁有一個引數 `path'，其內容為所要求的新工作目錄。

@ref{1882,,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{4609,,sys.addaudithook()} or
@ref{460a,,PySys_AddAuditHook()} functions.

The native equivalent of this function is @ref{60b,,PySys_Audit()}. Using the
native function is preferred when possible.

所有會被 CPython 所引發的事件請參考@ref{1b27,,稽核事件總表}。


在 3.8 版被加入.

@end deffn

@geindex base_exec_prefix (於 sys 模組中)
@anchor{library/sys sys base_exec_prefix}@anchor{3e8}
@deffn {資料} sys.base_exec_prefix

Equivalent to @ref{3e9,,exec_prefix}, but referring to the base Python installation.

When running under @ref{476b,,虛擬環境},
@ref{3e9,,exec_prefix} gets overwritten to the virtual environment prefix.
@ref{3e8,,base_exec_prefix}, conversely, does not change, and always points to
the base Python installation.
Refer to @ref{476b,,虛擬環境} for more information.


在 3.3 版被加入.

@end deffn

@geindex base_prefix (於 sys 模組中)
@anchor{library/sys sys base_prefix}@anchor{3e4}
@deffn {資料} sys.base_prefix

Equivalent to @ref{3e6,,prefix}, but referring to the base Python installation.

When running under @ref{3e5,,virtual environment},
@ref{3e6,,prefix} gets overwritten to the virtual environment prefix.
@ref{3e4,,base_prefix}, conversely, does not change, and always points to
the base Python installation.
Refer to @ref{476b,,虛擬環境} for more information.


在 3.3 版被加入.

@end deffn

@geindex byteorder (於 sys 模組中)
@anchor{library/sys sys byteorder}@anchor{24a7}
@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{1f0e}
@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.)

另請參閱 @ref{a3b,,sys.stdlib_module_names} 清單。
@end deffn

@geindex call_tracing() (於 sys 模組中)
@anchor{library/sys sys call_tracing}@anchor{1ae9}
@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{2e1,,settrace()} or @ref{16f2,,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{47a6}
@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{292}
@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{362,,_clear_internal_caches()} function instead.

@end deffn

@geindex _clear_internal_caches() (於 sys 模組中)
@anchor{library/sys sys _clear_internal_caches}@anchor{362}
@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.


在 3.13 版被加入.

@end deffn

@geindex _current_frames() (於 sys 模組中)
@anchor{library/sys sys _current_frames}@anchor{162a}
@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{104,,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.

引發一個不附帶引數的@ref{1b70,,稽核事件} @code{sys._current_frames}。
@end deffn

@geindex _current_exceptions() (於 sys 模組中)
@anchor{library/sys sys _current_exceptions}@anchor{6e2}
@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.

引發一個不附帶引數的@ref{1b70,,稽核事件} @code{sys._current_exceptions}。


在 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{cc8}
@deffn {函式} sys.breakpointhook ()

This hook function is called by built-in @ref{271,,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{cc9,,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{271,,breakpoint()}
function.

Note that if anything goes wrong while importing the callable named by
@geindex PYTHONBREAKPOINT
@geindex 環境變數; PYTHONBREAKPOINT
@ref{cc9,,PYTHONBREAKPOINT}, a @ref{4d2,,RuntimeWarning} is reported and the
breakpoint is ignored.

Also note that if @code{sys.breakpointhook()} is overridden programmatically,
@geindex PYTHONBREAKPOINT
@geindex 環境變數; PYTHONBREAKPOINT
@ref{cc9,,PYTHONBREAKPOINT} is `not' consulted.


在 3.7 版被加入.

@end deffn

@geindex _debugmallocstats() (於 sys 模組中)
@anchor{library/sys sys _debugmallocstats}@anchor{47a7}
@deffn {函式} sys._debugmallocstats ()

Print low-level information to stderr about the state of CPython's memory
allocator.

If Python is @ref{504,,built in debug mode} (@ref{65e,,configure --with-pydebug option}), it also performs some expensive
internal consistency checks.


在 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{47a8}
@deffn {資料} sys.dllhandle

Integer specifying the handle of the Python DLL.

@ref{2006,,可用性}: Windows.
@end deffn

@geindex displayhook() (於 sys 模組中)
@anchor{library/sys sys displayhook}@anchor{1713}
@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{2281,,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{880,,UnicodeEncodeError}.

@end deffn

@geindex dont_write_bytecode (於 sys 模組中)
@anchor{library/sys sys dont_write_bytecode}@anchor{47a9}
@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{15c4,,-B} command line option and the
@geindex PYTHONDONTWRITEBYTECODE
@geindex 環境變數; PYTHONDONTWRITEBYTECODE
@ref{15c5,,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{1ab8}
@deffn {資料} sys._emscripten_info

A @ref{857,,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{47aa}
@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{47ab}
@deffn {屬性} _emscripten_info.runtime

運行環境字串，例如瀏覽器使用者代理 (browser user agent) @code{'Node.js v14.18.2'} 或 @code{'UNKNOWN'}。
@end deffn

@geindex pthreads (sys._emscripten_info 的屬性)
@anchor{library/sys sys _emscripten_info pthreads}@anchor{47ac}
@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{47ad}
@deffn {屬性} _emscripten_info.shared_memory

@code{True} if Python is compiled with shared memory support.
@end deffn

@ref{2006,,可用性}: Emscripten.


在 3.11 版被加入.

@end deffn

@geindex pycache_prefix (於 sys 模組中)
@anchor{library/sys sys pycache_prefix}@anchor{b93}
@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{16f,,-X}
@code{pycache_prefix=PATH} command-line option or the
@geindex PYTHONPYCACHEPREFIX
@geindex 環境變數; PYTHONPYCACHEPREFIX
@ref{b92,,PYTHONPYCACHEPREFIX} environment variable (command-line takes
precedence). If neither are set, it is @code{None}.


在 3.8 版被加入.

@end deffn

@geindex excepthook() (於 sys 模組中)
@anchor{library/sys sys excepthook}@anchor{a05}
@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{f37,,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{244,,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{502,,sys.unraisablehook()} function handles unraisable exceptions
and the @ref{a44,,threading.excepthook()} function handles exception raised
by @ref{c28,,threading.Thread.run()}.

@end deffn

@geindex __breakpointhook__ (於 sys 模組中)
@geindex __displayhook__ (於 sys 模組中)
@geindex __excepthook__ (於 sys 模組中)
@geindex __unraisablehook__ (於 sys 模組中)
@anchor{library/sys sys __breakpointhook__}@anchor{47ae}
@deffn {資料} sys.__breakpointhook__
@anchor{library/sys sys __displayhook__}@anchor{47af}
@deffnx {資料} sys.__displayhook__
@anchor{library/sys sys __excepthook__}@anchor{47b0}
@deffnx {資料} sys.__excepthook__
@anchor{library/sys sys __unraisablehook__}@anchor{47b1}
@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.


在 3.7 版被加入: __breakpointhook__



在 3.8 版被加入: __unraisablehook__

@end deffn

@geindex exception() (於 sys 模組中)
@anchor{library/sys sys exception}@anchor{894}
@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}.


在 3.11 版被加入.

@end deffn

@geindex exc_info() (於 sys 模組中)
@anchor{library/sys sys exc_info}@anchor{893}
@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{894,,exception()} would return @code{e}), @ref{893,,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{7d0,,BaseException}), the exception itself, and a @ref{ce3,,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 @ref{893,,exc_info()}.

@end deffn

@geindex exec_prefix (於 sys 模組中)
@anchor{library/sys sys exec_prefix}@anchor{3e9}
@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{3e5,,virtual environment} is in effect, this @ref{3e9,,exec_prefix}
will point to the virtual environment. The value for the Python installation
will still be available, via @ref{3e8,,base_exec_prefix}.
Refer to @ref{476b,,虛擬環境} for more information.
@end quotation
@end cartouche


在 3.14 版的變更: When running under a @ref{3e5,,virtual environment},
@ref{3e6,,prefix} and @ref{3e9,,exec_prefix} are now set to the virtual
environment prefix by the @ref{1849,,path initialization},
instead of @ref{cc,,site}. This means that @ref{3e6,,prefix} and
@ref{3e9,,exec_prefix} always point to the virtual environment, even when
@ref{cc,,site} is disabled (@ref{13a9,,-S}).

@end deffn

@geindex executable (於 sys 模組中)
@anchor{library/sys sys executable}@anchor{3eb}
@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{3eb,,sys.executable} will be an empty string
or @code{None}.
@end deffn

@geindex exit() (於 sys 模組中)
@anchor{library/sys sys exit}@anchor{277}
@deffn {函式} sys.exit ([arg])

Raise a @ref{f37,,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 kind of errors.  If another type of
object is passed, @code{None} is equivalent to passing zero, and any other
object is printed to @ref{b2a,,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 @ref{2495,,exit()} ultimately "only" raises an exception, it will only exit
the process when called from the main thread, and the exception is not
intercepted. Cleanup actions specified by finally clauses of @ref{8f0,,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{f37,,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{895}
@deffn {資料} sys.flags

The @ref{857,,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{47b2}
@deffn {屬性} flags.debug
@end deffn

@tab

@ref{1fe9,,-d}

@item

@geindex inspect (sys.flags 的屬性)
@anchor{library/sys sys flags inspect}@anchor{47b3}
@deffn {屬性} flags.inspect
@end deffn

@tab

@ref{16cf,,-i}

@item

@geindex interactive (sys.flags 的屬性)
@anchor{library/sys sys flags interactive}@anchor{47b4}
@deffn {屬性} flags.interactive
@end deffn

@tab

@ref{16cf,,-i}

@item

@geindex isolated (sys.flags 的屬性)
@anchor{library/sys sys flags isolated}@anchor{47b5}
@deffn {屬性} flags.isolated
@end deffn

@tab

@ref{b4e,,-I}

@item

@geindex optimize (sys.flags 的屬性)
@anchor{library/sys sys flags optimize}@anchor{47b6}
@deffn {屬性} flags.optimize
@end deffn

@tab

@ref{18c,,-O} 或 @ref{fb0,,-OO}

@item

@geindex dont_write_bytecode (sys.flags 的屬性)
@anchor{library/sys sys flags dont_write_bytecode}@anchor{47b7}
@deffn {屬性} flags.dont_write_bytecode
@end deffn

@tab

@ref{15c4,,-B}

@item

@geindex no_user_site (sys.flags 的屬性)
@anchor{library/sys sys flags no_user_site}@anchor{47b8}
@deffn {屬性} flags.no_user_site
@end deffn

@tab

@ref{1586,,-s}

@item

@geindex no_site (sys.flags 的屬性)
@anchor{library/sys sys flags no_site}@anchor{47b9}
@deffn {屬性} flags.no_site
@end deffn

@tab

@ref{13a9,,-S}

@item

@geindex ignore_environment (sys.flags 的屬性)
@anchor{library/sys sys flags ignore_environment}@anchor{47ba}
@deffn {屬性} flags.ignore_environment
@end deffn

@tab

@ref{b4d,,-E}

@item

@geindex verbose (sys.flags 的屬性)
@anchor{library/sys sys flags verbose}@anchor{47bb}
@deffn {屬性} flags.verbose
@end deffn

@tab

@ref{161c,,-v}

@item

@geindex bytes_warning (sys.flags 的屬性)
@anchor{library/sys sys flags bytes_warning}@anchor{47bc}
@deffn {屬性} flags.bytes_warning
@end deffn

@tab

@ref{7f2,,-b}

@item

@geindex quiet (sys.flags 的屬性)
@anchor{library/sys sys flags quiet}@anchor{47bd}
@deffn {屬性} flags.quiet
@end deffn

@tab

@ref{1fec,,-q}

@item

@geindex hash_randomization (sys.flags 的屬性)
@anchor{library/sys sys flags hash_randomization}@anchor{47be}
@deffn {屬性} flags.hash_randomization
@end deffn

@tab

@ref{1d3f,,-R}

@item

@geindex dev_mode (sys.flags 的屬性)
@anchor{library/sys sys flags dev_mode}@anchor{1d49}
@deffn {屬性} flags.dev_mode
@end deffn

@tab

@ref{16f,,-X dev} （@ref{503,,Python 開發模式}）

@item

@geindex utf8_mode (sys.flags 的屬性)
@anchor{library/sys sys flags utf8_mode}@anchor{47bf}
@deffn {屬性} flags.utf8_mode
@end deffn

@tab

@ref{16f,,-X utf8}

@item

@geindex safe_path (sys.flags 的屬性)
@anchor{library/sys sys flags safe_path}@anchor{539}
@deffn {屬性} flags.safe_path
@end deffn

@tab

@ref{7ba,,-P}

@item

@geindex int_max_str_digits (sys.flags 的屬性)
@anchor{library/sys sys flags int_max_str_digits}@anchor{2585}
@deffn {屬性} flags.int_max_str_digits
@end deffn

@tab

@ref{16f,,-X int_max_str_digits}
(@ref{804,,integer string conversion length limitation})

@item

@geindex warn_default_encoding (sys.flags 的屬性)
@anchor{library/sys sys flags warn_default_encoding}@anchor{47c0}
@deffn {屬性} flags.warn_default_encoding
@end deffn

@tab

@ref{16f,,-X warn_default_encoding}

@item

@geindex gil (sys.flags 的屬性)
@anchor{library/sys sys flags gil}@anchor{47c1}
@deffn {屬性} flags.gil
@end deffn

@tab

@ref{16f,,-X gil} and 
@geindex PYTHON_GIL
@geindex 環境變數; PYTHON_GIL
@ref{495,,PYTHON_GIL}

@item

@geindex thread_inherit_context (sys.flags 的屬性)
@anchor{library/sys sys flags thread_inherit_context}@anchor{175}
@deffn {屬性} flags.thread_inherit_context
@end deffn

@tab

@ref{16f,,-X thread_inherit_context} and
@geindex PYTHON_THREAD_INHERIT_CONTEXT
@geindex 環境變數; PYTHON_THREAD_INHERIT_CONTEXT
@ref{17e4,,PYTHON_THREAD_INHERIT_CONTEXT}

@item

@geindex context_aware_warnings (sys.flags 的屬性)
@anchor{library/sys sys flags context_aware_warnings}@anchor{18a}
@deffn {屬性} flags.context_aware_warnings
@end deffn

@tab

@ref{16f,,-X context_aware_warnings} and
@geindex PYTHON_CONTEXT_AWARE_WARNINGS
@geindex 環境變數; PYTHON_CONTEXT_AWARE_WARNINGS
@ref{17db,,PYTHON_CONTEXT_AWARE_WARNINGS}

@end multitable



在 3.2 版的變更: 新增 @code{quiet} 屬性，用於新的 @ref{1fec,,-q} 旗標。



在 3.2.3 版被加入: @code{hash_randomization} 屬性。



在 3.3 版的變更: 移除過時的 @code{division_warning} 屬性。



在 3.4 版的變更: 新增 @code{isolated} 屬性，用於 @ref{b4e,,-I} @code{isolated} 旗標。



在 3.7 版的變更: Added the @code{dev_mode} attribute for the new @ref{503,,Python Development Mode} and the @code{utf8_mode} attribute for the new  @ref{16f,,-X}
@code{utf8} flag.



在 3.10 版的變更: 新增 @code{warn_default_encoding} 屬性，用於 @ref{16f,,-X} @code{warn_default_encoding} 旗標。



在 3.11 版的變更: 新增 @code{safe_path} 屬性，用於 @ref{7ba,,-P} 選項。



在 3.11 版的變更: 新增 @code{int_max_str_digits} 屬性。



在 3.13 版的變更: 新增 @code{gil} 屬性。



在 3.14 版的變更: 新增 @code{thread_inherit_context} 屬性。



在 3.14 版的變更: 新增 @code{context_aware_warnings} 屬性。

@end deffn

@geindex float_info (於 sys 模組中)
@anchor{library/sys sys float_info}@anchor{1c98}
@deffn {資料} sys.float_info

A @ref{857,,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{47c2,,[C99]}, 'Characteristics of floating types', for details.
Attributes of the @code{float_info} named tuple



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

屬性

@tab

float.h macro

@tab

解釋

@item

@geindex epsilon (sys.float_info 的屬性)
@anchor{library/sys sys float_info epsilon}@anchor{47c3}
@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.

另請參閱 @ref{b05,,math.ulp()}。

@item

@geindex dig (sys.float_info 的屬性)
@anchor{library/sys sys float_info dig}@anchor{47c4}
@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{47c5}
@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{47c6}
@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{47c7}
@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{47c8}
@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{47c9}
@deffn {屬性} float_info.min
@end deffn

@tab

@code{DBL_MIN}

@tab

The minimum representable positive `normalized' float.

Use @ref{b05,,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{47ca}
@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{47cb}
@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{47cc}
@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{47cd}
@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{47c4,,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{47c4,,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{14fb}
@deffn {資料} sys.float_repr_style

A string indicating how the @ref{1c1,,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.


在 3.1 版被加入.

@end deffn

@geindex getallocatedblocks() (於 sys 模組中)
@anchor{library/sys sys getallocatedblocks}@anchor{11c2}
@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{362,,_clear_internal_caches()} and @ref{1b3,,gc.collect()} to get more
predictable results.

If a Python build or implementation cannot reasonably compute this
information, @ref{11c2,,getallocatedblocks()} is allowed to return 0 instead.


在 3.4 版被加入.

@end deffn

@geindex getunicodeinternedsize() (於 sys 模組中)
@anchor{library/sys sys getunicodeinternedsize}@anchor{47ce}
@deffn {函式} sys.getunicodeinternedsize ()

Return the number of unicode objects that have been interned.


在 3.12 版被加入.

@end deffn

@geindex getandroidapilevel() (於 sys 模組中)
@anchor{library/sys sys getandroidapilevel}@anchor{d7d}
@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{1919,,platform.android_ver()}.

@ref{2006,,可用性}: Android.


在 3.7 版被加入.

@end deffn

@geindex getdefaultencoding() (於 sys 模組中)
@anchor{library/sys sys getdefaultencoding}@anchor{47cf}
@deffn {函式} sys.getdefaultencoding ()

Return @code{'utf-8'}. This is the name of the default string encoding, used
in methods like @ref{ac9,,str.encode()}.
@end deffn

@geindex getdlopenflags() (於 sys 模組中)
@anchor{library/sys sys getdlopenflags}@anchor{1702}
@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{1319,,os.RTLD_LAZY}).

@ref{2006,,可用性}: Unix.
@end deffn

@geindex getfilesystemencoding() (於 sys 模組中)
@anchor{library/sys sys getfilesystemencoding}@anchor{e4e}
@deffn {函式} sys.getfilesystemencoding ()

Get the @ref{756,,filesystem encoding}:
the encoding used with the @ref{756,,filesystem error handler} to convert between Unicode filenames and bytes
filenames. The filesystem error handler is returned from
@ref{edd,,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{e4a,,os.fsencode()} and @ref{e49,,os.fsdecode()} should be used to ensure that
the correct encoding and errors mode are used.

The @ref{756,,filesystem encoding and error handler} are configured at Python
startup by the @ref{98b,,PyConfig_Read()} function: see
@ref{419,,filesystem_encoding} and
@ref{41a,,filesystem_errors} members of @ref{3f4,,PyConfig}.


在 3.2 版的變更: @ref{e4e,,getfilesystemencoding()} 的結果不再為 @code{None}。



在 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{33d,,_enablelegacywindowsfsencoding()} for more information.



在 3.7 版的變更: Return @code{'utf-8'} if the @ref{85f,,Python UTF-8 Mode} is
enabled.

@end deffn

@geindex getfilesystemencodeerrors() (於 sys 模組中)
@anchor{library/sys sys getfilesystemencodeerrors}@anchor{edd}
@deffn {函式} sys.getfilesystemencodeerrors ()

Get the @ref{756,,filesystem error handler}: the error handler used with the @ref{756,,filesystem encoding} to convert between Unicode
filenames and bytes filenames. The filesystem encoding is returned from
@ref{e4e,,getfilesystemencoding()}.

@ref{e4a,,os.fsencode()} and @ref{e49,,os.fsdecode()} should be used to ensure that
the correct encoding and errors mode are used.

The @ref{756,,filesystem encoding and error handler} are configured at Python
startup by the @ref{98b,,PyConfig_Read()} function: see
@ref{419,,filesystem_encoding} and
@ref{41a,,filesystem_errors} members of @ref{3f4,,PyConfig}.


在 3.6 版被加入.

@end deffn

@geindex get_int_max_str_digits() (於 sys 模組中)
@anchor{library/sys sys get_int_max_str_digits}@anchor{179b}
@deffn {函式} sys.get_int_max_str_digits ()

Returns the current value for the @ref{804,,integer string conversion length limitation}. See also @ref{185e,,set_int_max_str_digits()}.


在 3.11 版被加入.

@end deffn

@geindex getrefcount() (於 sys 模組中)
@anchor{library/sys sys getrefcount}@anchor{2ce}
@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 @ref{2ce,,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{290,,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{290,,Immortal} objects with a large reference count can be
identified via @ref{28f,,_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{6e4}
@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{6e3,,setrecursionlimit()}.
@end deffn

@geindex getsizeof() (於 sys 模組中)
@anchor{library/sys sys getsizeof}@anchor{1a26}
@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{198,,TypeError} will be raised.

@ref{1a26,,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 @ref{1a26,,getsizeof()} recursively to find the size of
containers and all their contents.
@end deffn

@geindex getswitchinterval() (於 sys 模組中)
@anchor{library/sys sys getswitchinterval}@anchor{b3a}
@deffn {函式} sys.getswitchinterval ()

Return the interpreter's "thread switch interval" in seconds; see
@ref{b3b,,setswitchinterval()}.


在 3.2 版被加入.

@end deffn

@geindex _getframe() (於 sys 模組中)
@anchor{library/sys sys _getframe}@anchor{8e8}
@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{2eb,,ValueError} is raised.  The default
for `depth' is zero, returning the frame at the top of the call stack.

引發一個附帶引數 @code{frame} 的@ref{1b70,,稽核事件} @code{sys._getframe}。

`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{1a2a}
@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.

引發一個附帶引數 @code{depth} 的@ref{1b70,,稽核事件} @code{sys._getframemodulename}。

`CPython 實作細節：' This function should be used for internal and specialized purposes only.
It is not guaranteed to exist in all implementations of Python.


在 3.12 版被加入.

@end deffn

@geindex getobjects() (於 sys 模組中)
@anchor{library/sys sys getobjects}@anchor{28e}
@deffn {函式} sys.getobjects (limit[, type])

This function only exists if CPython was built using the
specialized configure option @ref{62e,,--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{47d0,,PyInterpreterConfig.use_main_obmalloc} set to 1
or using @ref{1a72,,Py_NewInterpreter()}, and the
@ref{163,,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{15d7}
@deffn {函式} sys.getprofile ()

@geindex profile function
@geindex profiler

Get the profiler function as set by @ref{16f2,,setprofile()}.
@end deffn

@geindex gettrace() (於 sys 模組中)
@anchor{library/sys sys gettrace}@anchor{15d8}
@deffn {函式} sys.gettrace ()

@geindex trace function
@geindex debugger（除錯器）

Get the trace function as set by @ref{2e1,,settrace()}.

`CPython 實作細節：' The @ref{15d8,,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{ede}
@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

含義

@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{2006,,可用性}: Windows.


在 3.2 版的變更: Changed to a named tuple and added `service_pack_minor',
`service_pack_major', `suite_mask', and `product_type'.



在 3.6 版的變更: 新增 `platform_version'

@end deffn

@geindex get_asyncgen_hooks() (於 sys 模組中)
@anchor{library/sys sys get_asyncgen_hooks}@anchor{1aea}
@deffn {函式} sys.get_asyncgen_hooks ()

Returns an `asyncgen_hooks' object, which is similar to a
@ref{4db,,namedtuple} of the form @code{(firstiter, finalizer)},
where `firstiter' and `finalizer' are expected to be either @code{None} or
functions which take an @ref{47d1,,asynchronous generator iterator} as an
argument, and are used to schedule finalization of an asynchronous
generator by an event loop.


在 3.6 版被加入: 更多細節請見 
@geindex Python Enhancement Proposals; PEP 525
PEP 525@footnote{https://peps.python.org/pep-0525/}。


@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{d7e}
@deffn {函式} sys.get_coroutine_origin_tracking_depth ()

Get the current coroutine origin tracking depth, as set by
@ref{d7f,,set_coroutine_origin_tracking_depth()}.


在 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{11fa}
@deffn {資料} sys.hash_info

A @ref{857,,named tuple} giving parameters of the numeric hash
implementation.  For more details about hashing of numeric types, see
@ref{24ae,,數值型別的雜湊}.

@geindex width (sys.hash_info 的屬性)
@anchor{library/sys sys hash_info width}@anchor{47d2}
@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{24af}
@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{47d3}
@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{47d4}
@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{47d5}
@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{47d6}
@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{47d7}
@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{47d8}
@deffn {屬性} hash_info.seed_bits

The size of the seed key of the hash algorithm
@end deffn


在 3.2 版被加入.



在 3.4 版的變更: 新增 `algorithm'、`hash_bits' 與 `seed_bits'

@end deffn

@geindex hexversion (於 sys 模組中)
@anchor{library/sys sys hexversion}@anchor{47d9}
@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{14d0,,hex()} function.  The
@ref{857,,named tuple}  @ref{8a7,,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{47da,,API 和 ABI 版本管理}.
@end deffn

@geindex implementation (於 sys 模組中)
@anchor{library/sys sys implementation}@anchor{734}
@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{8a7,,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{47d9,,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{734,,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,
@ref{734,,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.


在 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{1494}
@deffn {資料} sys.int_info

A @ref{857,,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{47db}
@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{47dc}
@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{2586}
@deffn {屬性} int_info.default_max_str_digits

The default value for @ref{179b,,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{47dd}
@deffn {屬性} int_info.str_digits_check_threshold

The minimum non-zero value for @ref{185e,,sys.set_int_max_str_digits()},
@geindex PYTHONINTMAXSTRDIGITS
@geindex 環境變數; PYTHONINTMAXSTRDIGITS
@ref{1a79,,PYTHONINTMAXSTRDIGITS}, or @ref{16f,,-X int_max_str_digits}.
@end deffn


在 3.1 版被加入.



在 3.11 版的變更: 新增 @ref{2586,,default_max_str_digits} 和 @ref{47dd,,str_digits_check_threshold}。

@end deffn

@geindex __interactivehook__ (於 sys 模組中)
@anchor{library/sys sys __interactivehook__}@anchor{11c3}
@deffn {資料} sys.__interactivehook__

When this attribute exists, its value is automatically called (with no
arguments) when the interpreter is launched in @ref{441,,interactive mode}.  This is done after the 
@geindex PYTHONSTARTUP
@geindex 環境變數; PYTHONSTARTUP
@ref{1b8,,PYTHONSTARTUP} file is
read, so that you can set this hook there.  The @ref{cc,,site} module
@ref{11c4,,sets this}.


Raises an @ref{1b70,,auditing event}
@code{cpython.run_interactivehook} with the hook object as the argument when
the hook is called on startup.



在 3.4 版被加入.

@end deffn

@geindex intern() (於 sys 模組中)
@anchor{library/sys sys intern}@anchor{14dc}
@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{290,,immortal}; you must keep a reference to the
return value of @ref{14dc,,intern()} around to benefit from it.
@end deffn

@geindex _is_gil_enabled() (於 sys 模組中)
@anchor{library/sys sys _is_gil_enabled}@anchor{47de}
@deffn {函式} sys._is_gil_enabled ()

Return @ref{e02,,True} if the @ref{164,,GIL} is enabled and @ref{d23,,False} if
it is disabled.


在 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{c77}
@deffn {函式} sys.is_finalizing ()

Return @ref{e02,,True} if the main Python interpreter is
@ref{474,,shutting down}. Return @ref{d23,,False} otherwise.

另請參閱 @ref{473,,PythonFinalizationError} 例外。


在 3.5 版被加入.

@end deffn

@geindex _jit (於 sys 模組中)
@anchor{library/sys sys _jit}@anchor{293}
@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.


在 3.14 版被加入.


@geindex _jit.is_available() (於 sys 模組中)
@anchor{library/sys sys _jit is_available}@anchor{44d}
@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{44c,,--enable-experimental-jit} option on all other platforms.
@end deffn

@geindex _jit.is_enabled() (於 sys 模組中)
@anchor{library/sys sys _jit is_enabled}@anchor{44e}
@deffn {函式} _jit.is_enabled ()

Return @code{True} if JIT compilation is enabled for the current Python
process (implies @ref{44d,,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{44b,,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{17e1}
@deffn {函式} _jit.is_active ()

Return @code{True} if the topmost Python frame is currently executing JIT
code (implies @ref{44e,,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{6de}
@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.)


在 3.12 版被加入.

@end deffn

@geindex _is_immortal() (於 sys 模組中)
@anchor{library/sys sys _is_immortal}@anchor{28f}
@deffn {函式} sys._is_immortal (op)

Return @ref{e02,,True} if the given object is @ref{290,,immortal}, @ref{d23,,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


在 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{553}
@deffn {函式} sys._is_interned (string)

Return @ref{e02,,True} if the given string is "interned", @ref{d23,,False}
otherwise.


在 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{6df}
@deffn {資料} sys.last_type
@anchor{library/sys sys last_value}@anchor{6e0}
@deffnx {資料} sys.last_value
@anchor{library/sys sys last_traceback}@anchor{6e1}
@deffnx {資料} sys.last_traceback

These three variables are deprecated; use @ref{6de,,sys.last_exc} instead.
They hold the legacy representation of @code{sys.last_exc}, as returned
from @ref{893,,exc_info()} above.
@end deffn

@geindex maxsize (於 sys 模組中)
@anchor{library/sys sys maxsize}@anchor{13c6}
@deffn {資料} sys.maxsize

An integer giving the maximum value a variable of type @ref{c4c,,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{1248}
@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{f22}
@deffn {資料} sys.meta_path

A list of @ref{126b,,meta path finder} objects that have their
@ref{a61,,find_spec()} methods called to see if one
of the objects can find the module to be imported. By default, it holds entries
that implement Python's default import semantics. The
@ref{a61,,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{1f1b,,__path__}
attribute is passed in as a second argument. The method returns a
@ref{2215,,module spec}, or @code{None} if the module cannot be found.


@subsubheading 也參考



@table @asis

@item @ref{a67,,importlib.abc.MetaPathFinder}

The abstract base class defining the interface of finder objects on
@ref{f22,,meta_path}.

@item @ref{2130,,importlib.machinery.ModuleSpec}

The concrete class which
@ref{a61,,find_spec()} should return
instances of.
@end table



在 3.4 版的變更: @ref{2215,,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 @ref{f22,,meta_path} entry didn't have a
@ref{a61,,find_spec()} method.

@end deffn

@geindex modules (於 sys 模組中)
@anchor{library/sys sys modules}@anchor{17c0}
@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{a3a}
@deffn {資料} sys.orig_argv

The list of the original command line arguments passed to the Python
executable.

The elements of @ref{a3a,,sys.orig_argv} are the arguments to the Python interpreter,
while the elements of @ref{1465,,sys.argv} are the arguments to the user's program.
Arguments consumed by the interpreter itself will be present in @ref{a3a,,sys.orig_argv}
and missing from @ref{1465,,sys.argv}.


在 3.10 版被加入.

@end deffn

@geindex path (於 sys 模組中)
@anchor{library/sys sys path}@anchor{3e2}
@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{1218,,PYTHONPATH}, plus an installation-dependent
default.

By default, as initialized upon program startup, a potentially unsafe path
is prepended to @ref{3e2,,sys.path} (`before' the entries inserted as a result
of 
@geindex PYTHONPATH
@geindex 環境變數; PYTHONPATH
@ref{1218,,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{7ba,,-P} command
line option or the 
@geindex PYTHONSAFEPATH
@geindex 環境變數; PYTHONSAFEPATH
@ref{7bb,,PYTHONSAFEPATH} environment variable.

A program is free to modify this list for its own purposes.  Only strings
should be added to @ref{3e2,,sys.path}; all other data types are
ignored during import.


@subsubheading 也參考



@itemize *

@item 
Module @ref{cc,,site} This describes how to use .pth files to
extend @ref{3e2,,sys.path}.
@end itemize

@end deffn

@geindex path_hooks (於 sys 模組中)
@anchor{library/sys sys path_hooks}@anchor{121f}
@deffn {資料} sys.path_hooks

A list of callables that take a path argument to try to create a
@ref{221c,,finder} for the path. If a finder can be created, it is to be
returned by the callable, else raise @ref{653,,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{7f3}
@deffn {資料} sys.path_importer_cache

A dictionary acting as a cache for @ref{221c,,finder} objects. The keys are
paths that have been passed to @ref{121f,,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 @ref{121f,,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{291}
@deffn {資料} sys.platform

A string containing a platform identifier. Known values are:


@multitable {xxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

系統

@tab

@code{platform} 值

@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 專屬的程式碼...
@end example


在 3.3 版的變更: On Linux, @ref{291,,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{291,,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{291,,sys.platform} now returns @code{'android'} rather than
@code{'linux'}.



在 3.14 版的變更: On FreeBSD, @ref{291,,sys.platform} doesn't contain the major version anymore.
It is always @code{'freebsd'}, instead of @code{'freebsd13'} or @code{'freebsd14'}.



@subsubheading 也參考


@ref{2eb5,,os.name} has a coarser granularity.  @ref{1317,,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{b29}
@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{5b,,errno} module,
the exact filename is platform specific)

@item 
@code{/usr/lib/pythonX.Y/site-packages/} (always use @code{lib}, not
@ref{b29,,sys.platlibdir}): Third-party modules

@item 
@code{/usr/lib64/pythonX.Y/site-packages/}:
C extension modules of third-party packages
@end itemize


在 3.9 版被加入.

@end deffn

@geindex prefix (於 sys 模組中)
@anchor{library/sys sys prefix}@anchor{3e6}
@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{2015,,--prefix}
argument to the @code{configure} script.  See
@ref{447,,Installation paths} for derived paths.

@cartouche
@quotation 備註 
If a @ref{3e5,,virtual environment} is in effect, this @ref{3e6,,prefix}
will point to the virtual environment. The value for the Python installation
will still be available, via @ref{3e4,,base_prefix}.
Refer to @ref{476b,,虛擬環境} for more information.
@end quotation
@end cartouche


在 3.14 版的變更: When running under a @ref{3e5,,virtual environment},
@ref{3e6,,prefix} and @ref{3e9,,exec_prefix} are now set to the virtual
environment prefix by the @ref{1849,,path initialization},
instead of @ref{cc,,site}. This means that @ref{3e6,,prefix} and
@ref{3e9,,exec_prefix} always point to the virtual environment, even when
@ref{cc,,site} is disabled (@ref{13a9,,-S}).

@end deffn

@geindex ps1 (於 sys 模組中)
@geindex ps2 (於 sys 模組中)
@anchor{library/sys sys ps1}@anchor{1ffc}
@deffn {資料} sys.ps1
@anchor{library/sys sys ps2}@anchor{1ffd}
@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{169,,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{1320}
@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{1319,,os.RTLD_LAZY}).

@ref{2006,,可用性}: Unix.
@end deffn

@geindex set_int_max_str_digits() (於 sys 模組中)
@anchor{library/sys sys set_int_max_str_digits}@anchor{185e}
@deffn {函式} sys.set_int_max_str_digits (maxdigits)

Set the @ref{804,,integer string conversion length limitation} used by this interpreter. See also
@ref{179b,,get_int_max_str_digits()}.


在 3.11 版被加入.

@end deffn

@geindex setprofile() (於 sys 模組中)
@anchor{library/sys sys setprofile}@anchor{16f2}
@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{46af,,Python 的分析器} for more information on the
Python profiler.  The system's profile function is called similarly to the
system's trace function (see @ref{2e1,,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{2e1,,settrace()}.
To trace calls with @code{setprofile()} inside a tracing function
(e.g. in a debugger breakpoint), see @ref{1ae9,,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

引發一個不附帶引數的@ref{1b70,,稽核事件} @code{sys.setprofile}。
@end deffn

@geindex setrecursionlimit() (於 sys 模組中)
@anchor{library/sys sys setrecursionlimit}@anchor{6e3}
@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{f63,,RecursionError} exception is raised.


在 3.5.1 版的變更: A @ref{f63,,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{b3b}
@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.


在 3.2 版被加入.

@end deffn

@geindex settrace() (於 sys 模組中)
@anchor{library/sys sys settrace}@anchor{2e1}
@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
@ref{2e1,,settrace()} for each thread being debugged or use @ref{a41,,threading.settrace()}.

Trace functions should have three arguments: `frame', `event', and
`arg'. `frame' is the @ref{8e7,,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{1ae9,,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{dd1,,f_trace_lines} to @ref{d23,,False} on that
@ref{8e7,,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{3c,,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{dd2,,f_trace_opcodes} to @ref{e02,,True} on the
@ref{8e7,,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 @ref{2e1,,settrace()} doesn't do. Note that in order
for this to work, a global tracing function must have been installed
with @ref{2e1,,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{21e4,,標準型別階層}.

引發一個不附帶引數的@ref{1b70,,稽核事件} @code{sys.settrace}。

`CPython 實作細節：' The @ref{2e1,,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{dd1,,f_trace_lines} and
@ref{dd2,,f_trace_opcodes} attributes added to frames

@end deffn

@geindex set_asyncgen_hooks() (於 sys 模組中)
@anchor{library/sys sys set_asyncgen_hooks}@anchor{18f4}
@deffn {函式} sys.set_asyncgen_hooks ([firstiter] [, finalizer])

Accepts two optional keyword arguments which are callables that accept an
@ref{47d1,,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.

引發一個不附帶引數的@ref{1b70,,稽核事件} @code{sys.set_asyncgen_hooks_firstiter}。

引發一個不附帶引數的@ref{1b70,,稽核事件} @code{sys.set_asyncgen_hooks_finalizer}。

Two auditing events are raised because the underlying API consists of two
calls, each of which must raise its own event.


在 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/3.14/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{d7f}
@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.


在 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{693}
@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{2006,,可用性}: Linux.


在 3.12 版被加入.



@subsubheading 也參考



@itemize *

@item 
@ref{4a9,,Python 對 Linux perf 分析器的支援}

@item 
@indicateurl{https://perf.wiki.kernel.org}
@end itemize

@end deffn

@geindex deactivate_stack_trampoline() (於 sys 模組中)
@anchor{library/sys sys deactivate_stack_trampoline}@anchor{694}
@deffn {函式} sys.deactivate_stack_trampoline ()

Deactivate the current stack profiler trampoline backend.

If no stack profiler is activated, this function has no effect.

@ref{2006,,可用性}: Linux.


在 3.12 版被加入.

@end deffn

@geindex is_stack_trampoline_active() (於 sys 模組中)
@anchor{library/sys sys is_stack_trampoline_active}@anchor{695}
@deffn {函式} sys.is_stack_trampoline_active ()

Return @code{True} if a stack profiler trampoline is active.

@ref{2006,,可用性}: Linux.


在 3.12 版被加入.

@end deffn

@geindex remote_exec() (於 sys 模組中)
@anchor{library/sys sys remote_exec}@anchor{16d}
@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.


When the code is executed in the remote process, an
@ref{1b70,,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{16d,,sys.remote_exec()}.



When the script is executed in the remote process, an
@ref{1b70,,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{16d,,sys.remote_exec()}.


@ref{2006,,可用性}: Unix, Windows.


在 3.14 版被加入.

@end deffn

@geindex _enablelegacywindowsfsencoding() (於 sys 模組中)
@anchor{library/sys sys _enablelegacywindowsfsencoding}@anchor{33d}
@deffn {函式} sys._enablelegacywindowsfsencoding ()

Changes the @ref{756,,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{33e,,PYTHONLEGACYWINDOWSFSENCODING}
environment variable before launching Python.

See also @ref{e4e,,sys.getfilesystemencoding()} and
@ref{edd,,sys.getfilesystemencodeerrors()}.

@ref{2006,,可用性}: 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{33e,,PYTHONLEGACYWINDOWSFSENCODING} instead.
@end quotation
@end cartouche


在 3.6 版被加入: 更多細節請見 
@geindex Python Enhancement Proposals; PEP 529
PEP 529@footnote{https://peps.python.org/pep-0529/}。



Deprecated since version 3.13, will be removed in version 3.16: Use 
@geindex PYTHONLEGACYWINDOWSFSENCODING
@geindex 環境變數; PYTHONLEGACYWINDOWSFSENCODING
@ref{33e,,PYTHONLEGACYWINDOWSFSENCODING} instead.

@end deffn

@geindex stdin (於 sys 模組中)
@geindex stdout (於 sys 模組中)
@geindex stderr (於 sys 模組中)
@anchor{library/sys sys stdin}@anchor{758}
@deffn {資料} sys.stdin
@anchor{library/sys sys stdout}@anchor{cc4}
@deffnx {資料} sys.stdout
@anchor{library/sys sys stderr}@anchor{b2a}
@deffnx {資料} sys.stderr

@ref{13c4,,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{14d9,,input()});

@item 
@code{stdout} is used for the output of @ref{1170,,print()} and @ref{2281,,expression}
statements and for the prompts of @ref{14d9,,input()};

@item 
The interpreter's own prompts and its error messages go to @code{stderr}.
@end itemize

These streams are regular @ref{1f34,,text files} like those
returned by the @ref{315,,open()} function.  Their parameters are chosen as
follows:


@itemize *

@item 
The encoding and error handling are is initialized from
@ref{63c,,PyConfig.stdio_encoding} and @ref{47df,,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{545,,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{1205,,PYTHONIOENCODING} environment variable before
starting Python or by using the new @ref{16f,,-X} @code{utf8} command
line option and 
@geindex PYTHONUTF8
@geindex 環境變數; PYTHONUTF8
@ref{cc6,,PYTHONUTF8} environment variable.  However,
for the Windows console, this only applies when
@geindex PYTHONLEGACYWINDOWSSTDIO
@geindex 環境變數; PYTHONLEGACYWINDOWSSTDIO
@ref{e50,,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{1c56,,-u} command-line option or setting the
@geindex PYTHONUNBUFFERED
@geindex 環境變數; PYTHONUNBUFFERED
@ref{1c57,,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{14a4,,buffer} object.  For example, to
write bytes to @ref{cc4,,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{1124,,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{47e0}
@deffn {資料} sys.__stdin__
@anchor{library/sys sys __stdout__}@anchor{2bae}
@deffnx {資料} sys.__stdout__
@anchor{library/sys sys __stderr__}@anchor{458c}
@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{a3b}
@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.

另請參閱 @ref{1f0e,,sys.builtin_module_names} 清單。


在 3.10 版被加入.

@end deffn

@geindex thread_info (於 sys 模組中)
@anchor{library/sys sys thread_info}@anchor{1351}
@deffn {資料} sys.thread_info

A @ref{857,,named tuple} holding information about the thread
implementation.

@geindex name (sys.thread_info 的屬性)
@anchor{library/sys sys thread_info name}@anchor{47e1}
@deffn {屬性} thread_info.name

The name of the thread implementation:


@itemize *

@item 
@code{"nt"}: Windows 執行緒

@item 
@code{"pthread"}: POSIX 執行緒

@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{47e2}
@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} 表示此資訊未知
@end itemize
@end deffn

@geindex version (sys.thread_info 的屬性)
@anchor{library/sys sys thread_info version}@anchor{47e3}
@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


在 3.3 版被加入.

@end deffn

@geindex tracebacklimit (於 sys 模組中)
@anchor{library/sys sys tracebacklimit}@anchor{18ab}
@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{502}
@deffn {函式} sys.unraisablehook (unraisable, /)

處理一個不可被引發的例外。

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{1b3,,gc.collect()}).

`unraisable' 引數具有以下屬性：


@itemize *

@item 
@code{exc_type}: 例外型別。

@item 
@code{exc_value}: 例外值，可以為 @code{None}。

@item 
@code{exc_traceback}: 例外追蹤，可以為 @code{None}。

@item 
@code{err_msg}: 錯誤訊息，可以為 @code{None}。

@item 
@code{object}: 導致例外的物件，可以為 @code{None}。
@end itemize

The default hook formats @code{err_msg} and @code{object} as:
@code{f'@{err_msg@}: @{object!r@}'}; use "Exception ignored in" error message
if @code{err_msg} is @code{None}.

@ref{502,,sys.unraisablehook()} can be overridden to control how unraisable
exceptions are handled.


@subsubheading 也參考


處理未被捕捉到例外的 @ref{a05,,excepthook()}。


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



在 3.8 版被加入.

@end deffn

@geindex version (於 sys 模組中)
@anchor{library/sys sys version}@anchor{497}
@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{8a7,,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{47e4}
@deffn {資料} sys.api_version

The C API version, equivalent to the C macro @ref{47e5,,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{8a7}
@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 版的變更: 新增了附名的元件屬性。

@end deffn

@geindex warnoptions (於 sys 模組中)
@anchor{library/sys sys warnoptions}@anchor{3f3}
@deffn {資料} sys.warnoptions

This is an implementation detail of the warnings framework; do not modify this
value.  Refer to the @ref{118,,warnings} module for more information on the warnings
framework.
@end deffn

@geindex winver (於 sys 模組中)
@anchor{library/sys sys winver}@anchor{47e6}
@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 @ref{df,,sys}
module for informational purposes; modifying this value has no effect on the
registry keys used by Python.

@ref{2006,,可用性}: Windows.
@end deffn


@deffn {資料} sys.monitoring

Namespace containing functions and constants for register callbacks
and controlling monitoring events.
See  @ref{e0,,sys.monitoring} for details.
@end deffn

@geindex _xoptions (於 sys 模組中)
@anchor{library/sys sys _xoptions}@anchor{1ff8}
@deffn {資料} sys._xoptions

A dictionary of the various implementation-specific flags passed through
the @ref{16f,,-X} command-line option.  Option names are either mapped to
their values, if given explicitly, or to @ref{e02,,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{16f,,-X}.  Other implementations may export them through other
means, or not at all.


在 3.2 版被加入.

@end deffn

@subsubheading 引用


@anchor{library/sys c99}@anchor{47c2}@w{(C99)} 
ISO/IEC 9899:1999.  "Programming languages -- C."  公開草案可在以下網址取得 @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 --- 執行事件監控,sysconfig --- 提供 Python 設定資訊的存取,sys --- 系統特定的參數與函式,Python Runtime 服務
@anchor{library/sys monitoring doc}@anchor{47e7}@anchor{library/sys monitoring module-sys monitoring}@anchor{e0}@anchor{library/sys monitoring sys-monitoring-execution-event-monitoring}@anchor{47e8}@anchor{library/sys monitoring translation-repo}@anchor{47e9}
@subsection @code{sys.monitoring} --- 執行事件監控


@geindex module; sys.monitoring


在 3.12 版被加入.



__________________________________________________________________


@cartouche
@quotation 備註 
@ref{e0,,sys.monitoring} 是 @ref{df,,sys} 模組內的一個命名空間，不是一個獨立的模組，所以不需要 @code{import sys.monitoring}，只需 @code{import sys} 然後使用 @code{sys.monitoring}。
@end quotation
@end cartouche

此命名空間提供對啟動和控制事件監控所需的函式和常數的存取。

當程式執行時，會發生一些能被監控工具關注的事件。@ref{e0,,sys.monitoring} 命名空間提供了在發生欲關注事件時接收回呼的方法。

監控 API 由三個元件組成：


@itemize *

@item 
@ref{47ea,,工具識別器}

@item 
@ref{47eb,,事件}

@item 
@ref{47ec,,回呼 (callbacks)}
@end itemize

@menu
* 工具識別器:: 
* 事件:: 
* 開啟和關閉事件:: 
* 註冊回呼函式:: 

@end menu

@node 工具識別器,事件,,sys monitoring --- 執行事件監控
@anchor{library/sys monitoring tool-identifiers}@anchor{47ea}
@subsubsection 工具識別器


工具識別器是一個整數和關聯的名稱。工具識別器用於防止工具相互干擾並允許多個工具同時運作。目前工具是完全獨立的，不能用來互相監控。將來此限制可能會取消。

在註冊或啟動事件之前，工具應選擇一個識別器。識別器是 0 到 5（含）範圍內的整數。

@menu
* 註冊和使用工具:: 

@end menu

@node 註冊和使用工具,,,工具識別器
@anchor{library/sys monitoring registering-and-using-tools}@anchor{47ed}
@subsubsection 註冊和使用工具


@geindex use_tool_id() (於 sys.monitoring 模組中)
@anchor{library/sys monitoring sys monitoring use_tool_id}@anchor{47ee}
@deffn {函式} sys.monitoring.use_tool_id (tool_id: int, name: str, /) -> None

必須在使用 `tool_id' 之前呼叫。`tool_id' 必須在 0 到 5（含）範圍內。如果 `tool_id' 正在使用，則引發 @ref{2eb,,ValueError}。
@end deffn

@geindex clear_tool_id() (於 sys.monitoring 模組中)
@anchor{library/sys monitoring sys monitoring clear_tool_id}@anchor{1894}
@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{47ef}
@deffn {函式} sys.monitoring.free_tool_id (tool_id: int, /) -> None

一旦工具不再需要 `tool_id' 就應該被呼叫。在釋放 `tool_id' 之前會呼叫 @ref{1894,,clear_tool_id()}。
@end deffn

@geindex get_tool() (於 sys.monitoring 模組中)
@anchor{library/sys monitoring sys monitoring get_tool}@anchor{47f0}
@deffn {函式} sys.monitoring.get_tool (tool_id: int, /) -> str | None

如果 `tool_id' 正在使用，則回傳該工具的名稱，否則回傳 @code{None}。`tool_id' 必須在 0 到 5（含）範圍內。
@end deffn

對於事件，虛擬機器對所有 ID 的處理都是相同的，但預先定義了以下 ID，以使工具間的協作更容易：

@example
sys.monitoring.DEBUGGER_ID = 0
sys.monitoring.COVERAGE_ID = 1
sys.monitoring.PROFILER_ID = 2
sys.monitoring.OPTIMIZER_ID = 5
@end example

@node 事件,開啟和關閉事件,工具識別器,sys monitoring --- 執行事件監控
@anchor{library/sys monitoring events}@anchor{47eb}
@subsubsection 事件


支援以下事件：

@geindex BRANCH_LEFT (monitoring event)
@anchor{library/sys monitoring monitoring-event-BRANCH_LEFT}@anchor{295}
@deffn {monitoring-event} sys.monitoring.events.BRANCH_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{296}
@deffn {monitoring-event} sys.monitoring.events.BRANCH_RIGHT

一個條件分支往右。
@end deffn

@geindex CALL (monitoring event)
@anchor{library/sys monitoring monitoring-event-CALL}@anchor{1912}
@deffn {monitoring-event} sys.monitoring.events.CALL

Python 程式碼中的呼叫（事件發生在呼叫之前）。
@end deffn

@geindex C_RAISE (monitoring event)
@anchor{library/sys monitoring monitoring-event-C_RAISE}@anchor{47f1}
@deffn {monitoring-event} sys.monitoring.events.C_RAISE

從任何可呼叫物件引發的例外，除 Python 函式外（事件發生在退出之後）。
@end deffn

@geindex C_RETURN (monitoring event)
@anchor{library/sys monitoring monitoring-event-C_RETURN}@anchor{47f2}
@deffn {monitoring-event} sys.monitoring.events.C_RETURN

從任何可呼叫函式回傳，除 Python 函式外（事件發生在回傳之後）。
@end deffn

@geindex EXCEPTION_HANDLED (monitoring event)
@anchor{library/sys monitoring monitoring-event-EXCEPTION_HANDLED}@anchor{47f3}
@deffn {monitoring-event} sys.monitoring.events.EXCEPTION_HANDLED

一個例外被處理。
@end deffn

@geindex INSTRUCTION (monitoring event)
@anchor{library/sys monitoring monitoring-event-INSTRUCTION}@anchor{47f4}
@deffn {monitoring-event} sys.monitoring.events.INSTRUCTION

虛擬機器指令即將被執行。
@end deffn

@geindex JUMP (monitoring event)
@anchor{library/sys monitoring monitoring-event-JUMP}@anchor{47f5}
@deffn {monitoring-event} sys.monitoring.events.JUMP

在控制流程圖中進行無條件跳轉。
@end deffn

@geindex LINE (monitoring event)
@anchor{library/sys monitoring monitoring-event-LINE}@anchor{47f6}
@deffn {monitoring-event} sys.monitoring.events.LINE

即將執行的指令與前一條指令的列號不同。
@end deffn

@geindex PY_RESUME (monitoring event)
@anchor{library/sys monitoring monitoring-event-PY_RESUME}@anchor{47f7}
@deffn {monitoring-event} sys.monitoring.events.PY_RESUME

Python 函式的繼續執行（對於產生器和協程函式），除了 @code{throw()} 呼叫。
@end deffn

@geindex PY_RETURN (monitoring event)
@anchor{library/sys monitoring monitoring-event-PY_RETURN}@anchor{47f8}
@deffn {monitoring-event} sys.monitoring.events.PY_RETURN

從 Python 函式回傳（發生在即將回傳之前，被呼叫者的 frame 將位於堆疊上）。
@end deffn

@geindex PY_START (monitoring event)
@anchor{library/sys monitoring monitoring-event-PY_START}@anchor{47f9}
@deffn {monitoring-event} sys.monitoring.events.PY_START

Python 函式的開始（在呼叫後立即發生，被呼叫者的 frame 將位於堆疊上）
@end deffn

@geindex PY_THROW (monitoring event)
@anchor{library/sys monitoring monitoring-event-PY_THROW}@anchor{17d4}
@deffn {monitoring-event} sys.monitoring.events.PY_THROW

Python 函式透過 @code{throw()} 呼叫來繼續。
@end deffn

@geindex PY_UNWIND (monitoring event)
@anchor{library/sys monitoring monitoring-event-PY_UNWIND}@anchor{47fa}
@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{47fb}
@deffn {monitoring-event} sys.monitoring.events.PY_YIELD

來自 Python 函式的 yield（在即將 yield 之前發生，被呼叫者的 frame 將位於堆疊上）。
@end deffn

@geindex RAISE (monitoring event)
@anchor{library/sys monitoring monitoring-event-RAISE}@anchor{18d7}
@deffn {monitoring-event} sys.monitoring.events.RAISE

例外被引發，除了那些會導致 @ref{47fc,,STOP_ITERATION} 的事件外。
@end deffn

@geindex RERAISE (monitoring event)
@anchor{library/sys monitoring monitoring-event-RERAISE}@anchor{47fd}
@deffn {monitoring-event} sys.monitoring.events.RERAISE

例外被重新引發 (re-raise)，例如在 @ref{1b0,,finally} 區塊的最後。
@end deffn

@geindex STOP_ITERATION (monitoring event)
@anchor{library/sys monitoring monitoring-event-STOP_ITERATION}@anchor{47fc}
@deffn {monitoring-event} sys.monitoring.events.STOP_ITERATION

一個人為的 @ref{df0,,StopIteration} 被引發；請參閱 @ref{47fe,,STOP_ITERATION 事件}。
@end deffn

將來可能會新增更多事件。

這些事件是 @code{sys.monitoring.events} 命名空間的屬性。每個事件以 2 次方的整數常數表示。要定義一組事件，只要將個別事件以 bitwise OR 相接即可。例如，若要指定 @ref{47f8,,PY_RETURN} 和 @ref{47f9,,PY_START} 兩個事件，請使用運算式 @code{PY_RETURN | PY_START}。

@geindex NO_EVENTS (monitoring event)
@anchor{library/sys monitoring monitoring-event-NO_EVENTS}@anchor{47ff}
@deffn {monitoring-event} sys.monitoring.events.NO_EVENTS

@code{0} 的別名，以便使用者可以進行明確比較，例如：

@example
if get_events(DEBUGGER_ID) == NO_EVENTS:
    ...
@end example

Setting this event deactivates all events.
@end deffn

@menu
* 區域事件:: 
* 已棄用的事件:: 
* 附屬事件 (ancillary events): 附屬事件 ancillary events. 
* 其他事件:: 
* STOP_ITERATION 事件:: 

@end menu

@node 區域事件,已棄用的事件,,事件
@anchor{library/sys monitoring local-events}@anchor{4800}@anchor{library/sys monitoring monitoring-event-local}@anchor{4801}
@subsubsection 區域事件


區域事件與程式的正常執行相關，並發生在明確定義的位置。所有區域事件都可以被停用。區域事件有：


@itemize *

@item 
@ref{47f9,,PY_START}

@item 
@ref{47f7,,PY_RESUME}

@item 
@ref{47f8,,PY_RETURN}

@item 
@ref{47fb,,PY_YIELD}

@item 
@ref{1912,,CALL}

@item 
@ref{47f6,,LINE}

@item 
@ref{47f4,,INSTRUCTION}

@item 
@ref{47f5,,JUMP}

@item 
@ref{295,,BRANCH_LEFT}

@item 
@ref{296,,BRANCH_RIGHT}

@item 
@ref{47fc,,STOP_ITERATION}
@end itemize

@node 已棄用的事件,附屬事件 ancillary events,區域事件,事件
@anchor{library/sys monitoring deprecated-event}@anchor{4802}
@subsubsection 已棄用的事件



@itemize *

@item 
@code{BRANCH}
@end itemize

The @code{BRANCH} event is deprecated in 3.14.
Using @ref{295,,BRANCH_LEFT} and @ref{296,,BRANCH_RIGHT}
events will give much better performance as they can be disabled
independently.

@node 附屬事件 ancillary events,其他事件,已棄用的事件,事件
@anchor{library/sys monitoring ancillary-events}@anchor{4803}
@subsubsection 附屬事件 (ancillary events)


附屬事件可以像其他事件一樣被監控，但由另一個事件所控制：


@itemize *

@item 
@ref{47f1,,C_RAISE}

@item 
@ref{47f2,,C_RETURN}
@end itemize

@ref{47f2,,C_RETURN} 和 @ref{47f1,,C_RAISE} 事件由 @ref{1912,,CALL} 事件控制。只有當對應的 @ref{1912,,CALL} 事件受到監控時，才會看到 @ref{47f2,,C_RETURN} 和 @ref{47f1,,C_RAISE} 事件。

@node 其他事件,STOP_ITERATION 事件,附屬事件 ancillary events,事件
@anchor{library/sys monitoring other-events}@anchor{4804}
@subsubsection 其他事件


其他事件不一定與程式中的特定位置相關聯，也不能單獨停用。

其他可以監控的事件有：


@itemize *

@item 
@ref{17d4,,PY_THROW}

@item 
@ref{47fa,,PY_UNWIND}

@item 
@ref{18d7,,RAISE}

@item 
@ref{47f3,,EXCEPTION_HANDLED}
@end itemize

@node STOP_ITERATION 事件,,其他事件,事件
@anchor{library/sys monitoring the-stop-iteration-event}@anchor{47fe}
@subsubsection STOP_ITERATION 事件


@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} 指出從產生器或協程回傳值時要引發 @ref{df0,,StopIteration} 例外。然而，這是一種非常低效的回傳值方式，因此有一些 Python 實作（特別是 CPython 3.12+）不會引發例外，除非它對其他程式碼是可見的。

為了允許工具去監控真正的例外而不減慢產生器和協程的速度，提供了 @ref{47fc,,STOP_ITERATION} 事件。與 @ref{18d7,,RAISE} 不同，@ref{47fc,,STOP_ITERATION} 可以區域停用。

Note that the @ref{47fc,,STOP_ITERATION} event and the
@ref{18d7,,RAISE} event for a @ref{df0,,StopIteration} exception are
equivalent, and are treated as interchangeable when generating events.
Implementations will favor @ref{47fc,,STOP_ITERATION} for performance
reasons, but may generate a @ref{18d7,,RAISE} event with a
@ref{df0,,StopIteration}.

@node 開啟和關閉事件,註冊回呼函式,事件,sys monitoring --- 執行事件監控
@anchor{library/sys monitoring turning-events-on-and-off}@anchor{4805}
@subsubsection 開啟和關閉事件


為了監控一個事件，必須打開它並註冊相應的回呼。可以透過將事件設定為全域與/或只為特定程式碼物件來開啟或關閉事件。即使事件在全域和區域都被打開，事件也只會觸發一次。

@menu
* 全域設定事件:: 
* 各別程式碼物件事件:: 
* 停用事件:: 

@end menu

@node 全域設定事件,各別程式碼物件事件,,開啟和關閉事件
@anchor{library/sys monitoring setting-events-globally}@anchor{4806}
@subsubsection 全域設定事件


可以透過修改正在監控的事件集合來全域地控制事件。

@geindex get_events() (於 sys.monitoring 模組中)
@anchor{library/sys monitoring sys monitoring get_events}@anchor{4807}
@deffn {函式} sys.monitoring.get_events (tool_id: int, /) -> int

回傳代表所有有效事件的 @code{int}。
@end deffn

@geindex set_events() (於 sys.monitoring 模組中)
@anchor{library/sys monitoring sys monitoring set_events}@anchor{4808}
@deffn {函式} sys.monitoring.set_events (tool_id: int, event_set: int, /) -> None

啟動 `event_set' 中設定的所有事件。如果 `tool_id' 並未正在被使用，則引發 @ref{2eb,,ValueError}。
@end deffn

預設沒有有效事件。

@node 各別程式碼物件事件,停用事件,全域設定事件,開啟和關閉事件
@anchor{library/sys monitoring per-code-object-events}@anchor{4809}
@subsubsection 各別程式碼物件事件


事件還可以基於各別程式碼物件進行控制。下面定義的、接受 @ref{32e,,types.CodeType} 的函式應該準備好接受來自 Python 中未定義函式的類似物件（請參閱 @ref{480,,監控 C API}）。

@geindex get_local_events() (於 sys.monitoring 模組中)
@anchor{library/sys monitoring sys monitoring get_local_events}@anchor{480a}
@deffn {函式} sys.monitoring.get_local_events (tool_id: int, code: CodeType, /) -> int

回傳 `code' 的所有區域事件
@end deffn

@geindex set_local_events() (於 sys.monitoring 模組中)
@anchor{library/sys monitoring sys monitoring set_local_events}@anchor{480b}
@deffn {函式} sys.monitoring.set_local_events (tool_id: int, code: CodeType, event_set: int, /) -> None

啟動 `event_set' 中針對 `code' 設定的所有區域事件。如果 `tool_id' 並未正在被使用，則引發 @ref{2eb,,ValueError}。
@end deffn

@node 停用事件,,各別程式碼物件事件,開啟和關閉事件
@anchor{library/sys monitoring disabling-events}@anchor{480c}
@subsubsection 停用事件


@geindex DISABLE (於 sys.monitoring 模組中)
@anchor{library/sys monitoring sys monitoring DISABLE}@anchor{480d}
@deffn {資料} sys.monitoring.DISABLE

可以從回呼函式回傳的特殊值，以停用目前程式碼位置的事件。
@end deffn

可透過回呼函式回傳 @ref{480d,,sys.monitoring.DISABLE} 來停用特定程式碼位置的區域事件。這不會改變被設定的事件，或相同事件的任何其他程式碼位置。

停用特定位置的事件對於高效能監控非常重要。舉例來說，如果除少數斷點外，偵錯器可以停用所有監控，那麼在偵錯器下執行程式就不會有任何開銷 (overhead)。

@geindex restart_events() (於 sys.monitoring 模組中)
@anchor{library/sys monitoring sys monitoring restart_events}@anchor{480e}
@deffn {函式} sys.monitoring.restart_events () -> None

為所有工具啟用由 @ref{480d,,sys.monitoring.DISABLE} 停用的所有事件。
@end deffn

@node 註冊回呼函式,,開啟和關閉事件,sys monitoring --- 執行事件監控
@anchor{library/sys monitoring callbacks}@anchor{47ec}@anchor{library/sys monitoring registering-callback-functions}@anchor{480f}
@subsubsection 註冊回呼函式


@geindex register_callback() (於 sys.monitoring 模組中)
@anchor{library/sys monitoring sys monitoring register_callback}@anchor{4619}
@deffn {函式} sys.monitoring.register_callback (tool_id: int, event: int, func: Callable | None, /) -> Callable | None

使用給定的 `tool_id' 來註冊對 `event' 的可呼叫物件 `func'

如果給定的 `tool_id' 和 `event' 已經註冊了另一個回呼，則會取消註冊並回傳。否則 @ref{4619,,register_callback()} 會回傳 @code{None}。

以 @code{func} 引數引發一個@ref{1b70,,稽核事件 (auditing event)} @code{sys.monitoring.register_callback}。
@end deffn

可以透過呼叫 @code{sys.monitoring.register_callback(tool_id, event, None)} 來取消註冊函式。

回呼函式可以隨時被註冊和取消註冊。

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
* 回呼函式引數:: 

@end menu

@node 回呼函式引數,,,註冊回呼函式
@anchor{library/sys monitoring callback-function-arguments}@anchor{4810}
@subsubsection 回呼函式引數


@geindex MISSING (於 sys.monitoring 模組中)
@anchor{library/sys monitoring sys monitoring MISSING}@anchor{4811}
@deffn {資料} sys.monitoring.MISSING

傳遞給回呼函式的特殊值，表示該呼叫沒有引數。
@end deffn

當有效事件發生時，已註冊的回呼函式會被呼叫。回傳非 @ref{480d,,DISABLE} 物件的回呼函式將不會有任何效果。不同的事件會為回呼函式提供不同的引數，如下所示：


@itemize *

@item 
@ref{47f9,,PY_START} 和 @ref{47f7,,PY_RESUME}：

@example
func(code: CodeType, instruction_offset: int) -> object
@end example

@item 
@ref{47f8,,PY_RETURN} 和 @ref{47fb,,PY_YIELD}：

@example
func(code: CodeType, instruction_offset: int, retval: object) -> object
@end example

@item 
@ref{1912,,CALL}、@ref{47f1,,C_RAISE} 和 @ref{47f2,,C_RETURN}（`arg0' 可以特別是 @ref{4811,,MISSING}）：

@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{4811,,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{18d7,,RAISE}、@ref{47fd,,RERAISE}、@ref{47f3,,EXCEPTION_HANDLED}、@ref{47fa,,PY_UNWIND}、@ref{17d4,,PY_THROW} 和 @ref{47fc,,STOP_ITERATION}：

@example
func(code: CodeType, instruction_offset: int, exception: BaseException) -> object
@end example

@item 
@ref{47f6,,LINE}：

@example
func(code: CodeType, line_number: int) -> object
@end example

@item 
@ref{295,,BRANCH_LEFT}, @ref{296,,BRANCH_RIGHT} and @ref{47f5,,JUMP}:

@example
func(code: CodeType, instruction_offset: int, destination_offset: int) -> object
@end example

請注意，`destination_offset' 是程式碼接下來要執行的地方。

@item 
@ref{47f4,,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 --- 提供 Python 設定資訊的存取,builtins --- 內建物件,sys monitoring --- 執行事件監控,Python Runtime 服務
@anchor{library/sysconfig doc}@anchor{4812}@anchor{library/sysconfig module-sysconfig}@anchor{e1}@anchor{library/sysconfig sysconfig-provide-access-to-python-s-configuration-information}@anchor{4813}@anchor{library/sysconfig translation-repo}@anchor{4814}
@subsection @code{sysconfig} --- 提供 Python 設定資訊的存取


@geindex module; sysconfig


在 3.2 版被加入.


`原始碼：'Lib/sysconfig@footnote{https://github.com/python/cpython/tree/3.14/Lib/sysconfig}

@geindex configuration information（設定資訊）


__________________________________________________________________


The @ref{e1,,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:: 
* 安裝路徑函式:: 
* 其他函式: 其他函式<3>. 
* 命令列用法: 命令列用法<8>. 

@end menu

@node Configuration variables,Installation paths,,sysconfig --- 提供 Python 設定資訊的存取
@anchor{library/sysconfig configuration-variables}@anchor{4815}
@subsubsection Configuration variables


A Python distribution contains a @code{Makefile} and a @code{pyconfig.h}
header file that are necessary to build both the Python binary itself and
third-party C extensions compiled using @code{setuptools}.

@ref{e1,,sysconfig} puts all variables found in these files in a dictionary that
can be accessed using @ref{298,,get_config_vars()} or @ref{174,,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{298}
@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{174}
@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
>>> 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 --- 提供 Python 設定資訊的存取
@anchor{library/sysconfig id1}@anchor{4816}@anchor{library/sysconfig installation-paths}@anchor{447}
@subsubsection Installation paths


Python uses an installation scheme that differs depending on the platform and on
the installation options.  These schemes are stored in @ref{e1,,sysconfig} under
unique identifiers based on the value returned by @ref{2eb5,,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{151d,,site.USER_BASE}).

@item 
`posix_venv': scheme for @ref{117,,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{117,,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 --- 提供 Python 設定資訊的存取
@anchor{library/sysconfig sysconfig-user-scheme}@anchor{1ffe}@anchor{library/sysconfig user-scheme}@anchor{4817}
@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{151d,,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{1fed,,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{4818}
@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{4819}
@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{481a}
@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 --- 提供 Python 設定資訊的存取
@anchor{library/sysconfig home-scheme}@anchor{481b}@anchor{library/sysconfig sysconfig-home-scheme}@anchor{481c}
@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{481d}
@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,安裝路徑函式,Home scheme,sysconfig --- 提供 Python 設定資訊的存取
@anchor{library/sysconfig prefix-scheme}@anchor{481e}@anchor{library/sysconfig sysconfig-prefix-scheme}@anchor{481f}
@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{4820}
@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{4821}
@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 安裝路徑函式,其他函式<3>,Prefix scheme,sysconfig --- 提供 Python 設定資訊的存取
@anchor{library/sysconfig installation-path-functions}@anchor{4822}
@subsubsection 安裝路徑函式


@ref{e1,,sysconfig} provides some functions to determine these installation paths.

@geindex get_scheme_names() (於 sysconfig 模組中)
@anchor{library/sysconfig sysconfig get_scheme_names}@anchor{4823}
@deffn {函式} sysconfig.get_scheme_names ()

Return a tuple containing all schemes currently supported in
@ref{e1,,sysconfig}.
@end deffn

@geindex get_default_scheme() (於 sysconfig 模組中)
@anchor{library/sysconfig sysconfig get_default_scheme}@anchor{1ada}
@deffn {函式} sysconfig.get_default_scheme ()

Return the default scheme name for the current platform.


在 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{898}
@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{4823,,get_scheme_names()}. It
can be passed to @ref{e1,,sysconfig} functions that take a `scheme' argument,
such as @ref{33f,,get_paths()}.


在 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{4824}
@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{1ada,,get_default_scheme()} and
@ref{898,,get_preferred_scheme()} instead.


在 3.10 版被加入.

@end deffn

@geindex get_path_names() (於 sysconfig 模組中)
@anchor{library/sysconfig sysconfig get_path_names}@anchor{4825}
@deffn {函式} sysconfig.get_path_names ()

Return a tuple containing all path names currently supported in
@ref{e1,,sysconfig}.
@end deffn

@geindex get_path() (於 sysconfig 模組中)
@anchor{library/sysconfig sysconfig get_path}@anchor{152e}
@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{4825,,get_path_names()}.

@ref{e1,,sysconfig} stores installation paths corresponding to each path name,
for each platform, with variables to be expanded.  For instance the `stdlib'
path for the `nt' scheme is: @code{@{base@}/Lib}.

@ref{152e,,get_path()} will use the variables returned by @ref{298,,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{4823,,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{298,,get_config_vars()}.

If `expand' is set to @code{False}, the path will not be expanded using the
variables.

如果找不到 `name'，則引發 @ref{5df,,KeyError}。
@end deffn

@geindex get_paths() (於 sysconfig 模組中)
@anchor{library/sysconfig sysconfig get_paths}@anchor{33f}
@deffn {函式} sysconfig.get_paths ([scheme[, vars[, expand]]])

Return a dictionary containing all installation paths corresponding to an
installation scheme. See @ref{152e,,get_path()} for more information.

If `scheme' is not provided, will use the default scheme for the current
platform.

If `vars' is provided, it must be a dictionary of variables that will
update the dictionary used to expand the paths.

If `expand' is set to false, the paths will not be expanded.

If `scheme' is not an existing scheme, @ref{33f,,get_paths()} will raise a
@ref{5df,,KeyError}.
@end deffn

@node 其他函式<3>,命令列用法<8>,安裝路徑函式,sysconfig --- 提供 Python 設定資訊的存取
@anchor{library/sysconfig other-functions}@anchor{4826}
@subsubsection 其他函式


@geindex get_python_version() (於 sysconfig 模組中)
@anchor{library/sysconfig sysconfig get_python_version}@anchor{1444}
@deffn {函式} sysconfig.get_python_version ()

回傳 @code{MAJOR.MINOR} Python 版本號碼字串。類似於 @code{'%d.%d' % sys.version_info[:2]}。
@end deffn

@geindex get_platform() (於 sysconfig 模組中)
@anchor{library/sysconfig sysconfig get_platform}@anchor{1443}
@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{1317,,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:

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{291,,sys.platform}.
@end deffn

@geindex is_python_build() (於 sysconfig 模組中)
@anchor{library/sysconfig sysconfig is_python_build}@anchor{32c}
@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{4827}
@deffn {函式} sysconfig.parse_config_h (fp[, vars])

剖析一個 @code{config.h} 風格的檔案。

`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{4828}
@deffn {函式} sysconfig.get_config_h_filename ()

回傳 @code{pyconfig.h} 的路徑。
@end deffn

@geindex get_makefile_filename() (於 sysconfig 模組中)
@anchor{library/sysconfig sysconfig get_makefile_filename}@anchor{4829}
@deffn {函式} sysconfig.get_makefile_filename ()

回傳 @code{Makefile} 的路徑。
@end deffn
@anchor{library/sysconfig sysconfig-cli}@anchor{482a}
@node 命令列用法<8>,,其他函式<3>,sysconfig --- 提供 Python 設定資訊的存取
@anchor{library/sysconfig command-line-usage}@anchor{482b}@anchor{library/sysconfig using-sysconfig-as-a-script}@anchor{482c}
@subsubsection 命令列用法


You can use @ref{e1,,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{1443,,get_platform()}, @ref{1444,,get_python_version()}, @ref{152e,,get_path()} and
@ref{298,,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 --- 內建物件,__main__ --- 頂層程式碼環境,sysconfig --- 提供 Python 設定資訊的存取,Python Runtime 服務
@anchor{library/builtins doc}@anchor{482d}@anchor{library/builtins builtins-built-in-objects}@anchor{482e}@anchor{library/builtins module-builtins}@anchor{13}@anchor{library/builtins translation-repo}@anchor{482f}
@subsection @code{builtins} --- 內建物件


@geindex module; builtins


__________________________________________________________________


該模組提供對 Python 所有'內建'識別符號的直接存取；例如 @code{builtins.open} 是內建函式 @ref{315,,open()} 的全名。

大多數應用程式通常不會顯式地存取此模組，但在提供與內建值同名之物件的模組中可能很有用，不過其中還會需要內建該名稱。例如，在一個將內建 @ref{315,,open()} 包裝起來以實現另一版本 @ref{315,,open()} 函式的模組中，這個模組可以直接被使用：

@example
import builtins

def open(path):
    f = builtins.open(path, 'r')
    return UpperCaser(f)

class UpperCaser:
    '@w{'}'將輸出轉換成大寫的檔案包裝器'@w{'}'

    def __init__(self, f):
        self._f = f

    def read(self, count=-1):
        return self._f.read(count).upper()

    # ...
@end example

有個實作細節是，大多數模組都將名稱 @code{__builtins__} 作為其全域性變數的一部分以提使用。@code{__builtins__} 的值通常是這個模組或者這個模組的 @ref{776,,__dict__} 屬性值。由於這是一個實作細節，因此 Python 的其他實作可能不會使用它。


@subsubheading 也參考



@itemize *

@item 
@ref{2490,,內建常數}

@item 
@ref{1b3a,,內建的例外}

@item 
@ref{145d,,內建函式}

@item 
@ref{2499,,內建型別}
@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__ --- 頂層程式碼環境,warnings --- 警告控制,builtins --- 內建物件,Python Runtime 服務
@anchor{library/__main__ doc}@anchor{4830}@anchor{library/__main__ main-top-level-code-environment}@anchor{4831}@anchor{library/__main__ module-__main__}@anchor{1}@anchor{library/__main__ translation-repo}@anchor{4832}
@subsection @code{__main__} --- 頂層程式碼環境


@geindex module; __main__


__________________________________________________________________


在 Python 中，特殊名稱 @code{__main__} 用於兩個重要的建構：


@enumerate 

@item 
程式頂層環境的名稱，可以使用 @code{__name__ == '__main__'} 運算式進行檢查；和

@item 
在 Python 套件中的 @code{__main__.py} 檔案。
@end enumerate

這兩種機制都與 Python 模組有關；使用者如何與它們互動以及它們如何彼此互動。下面會詳細解釋它們。如果你不熟悉 Python 模組，請參閱教學章節 @ref{1f05,,模組 (Module)} 的介紹。

@menu
* __name__ == '__main__':: 
* Python 套件中的 __main__.py: Python 套件中的 __main__ py. 
* import __main__:: 

@end menu

@node __name__ == '__main__',Python 套件中的 __main__ py,,__main__ --- 頂層程式碼環境
@anchor{library/__main__ name-equals-main}@anchor{4833}@anchor{library/__main__ name-main}@anchor{4834}
@subsubsection @code{__name__ == '__main__'}


當引入 Python 模組或套件時，@code{__name__} 設定為模組的名稱。通常來說，這是 Python 檔案本身的名稱，且不含 .py 副檔名：

@example
>>> import configparser
>>> configparser.__name__
'configparser'
@end example

如果檔案是套件的一部分，則 @code{__name__} 也會包含父套件 (parent package) 的路徑：

@example
>>> from concurrent.futures import process
>>> process.__name__
'concurrent.futures.process'
@end example

但是，如果模組在頂層程式碼環境中執行，則其 @code{__name__} 將被設定為字串 @code{'__main__'}。

@menu
* 什麼是「頂層程式碼環境」？:: 
* 慣用 (Idiomatic) 用法: 慣用 Idiomatic 用法. 
* 打包時須考慮的事情:: 

@end menu

@node 什麼是「頂層程式碼環境」？,慣用 Idiomatic 用法,,__name__ == '__main__'
@anchor{library/__main__ what-is-the-top-level-code-environment}@anchor{4835}
@subsubsection 什麼是「頂層程式碼環境」？


@code{__main__} 是執行頂層程式碼的環境名稱。「頂層程式碼」是使用者指定且第一個開始運作的 Python 模組。它是「頂層」的原因是因為它引入程式所需的所有其他模組。有時「頂層程式碼」被稱為應用程式的`入口點'。

頂層程式碼環境可以是：


@itemize *

@item 
互動式提示字元的作用域：

@example
>>> __name__
'__main__'
@end example

@item 
將 Python 模組作為檔案引數傳遞給 Python 直譯器：

@example
$ python helloworld.py
Hello, world!
@end example

@item 
使用 @ref{23c,,-m} 引數傳遞給 Python 直譯器的 Python 模組或套件：

@example
$ python -m tarfile
usage: tarfile.py [-h] [-v] (...)
@end example

@item 
Python 直譯器從標準輸入讀取 Python 程式碼：

@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 
使用 @ref{1a8,,-c} 引數傳遞給 Python 直譯器的 Python 程式碼：

@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

在這些情況下，頂層模組的 @code{__name__} 都會設定為 @code{'__main__'}。

因此，模組可以透過檢查自己的 @code{__name__} 來發現它是否在頂層環境中執行，這允許當模組未從 import 陳述式初始化時，使用常見的慣用語法 (idiom) 來有條件地執行程式碼：

@example
if __name__ == '__main__':
    # Execute when the module is not initialized from an import statement.
    ...
@end example


@subsubheading 也參考


若要更詳細地了解如何在所有情況下設定 @code{__name__}，請參閱教學章節 @ref{1f05,,模組 (Module)}。


@node 慣用 Idiomatic 用法,打包時須考慮的事情,什麼是「頂層程式碼環境」？,__name__ == '__main__'
@anchor{library/__main__ idiomatic-usage}@anchor{4836}
@subsubsection 慣用 (Idiomatic) 用法


某些模組包含僅供腳本使用的程式碼，例如剖析命令列引數或從標準輸入取得資料。如果從不同的模組匯入這樣的模組（例如對其進行單元測試 (unit test)），則腳本程式碼也會無意間執行。

這就是使用 @code{if __name__ == '__main__'} 程式碼區塊派上用場的地方。除非該模組在頂層環境中執行，否則此區塊中的程式碼不會執行。

在 @code{if __name__ == '__main__'} 下面的區塊中放置盡可能少的陳述式可以提高程式碼的清晰度和正確性。大多數情況下，名為 @code{main} 的函式封裝 (encapsulate) 了程式的主要行為：

@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

請注意，如果模組沒有將程式碼封裝在 @code{main} 函式中，而是直接將其放在 @code{if __name__ == '__main__'} 區塊中，則 @code{phrase} 變數對於整個模組來說將是全域的。這很容易出錯，因為模組中的其他函式可能會無意中使用此全域變數而不是區域變數。@code{main} 函式解決了這個問題。

使用 @code{main} 函式還有一個額外的好處，@code{echo} 函式本身是隔離的 (isolated) 並且可以在其他地方引入。當引入 @code{echo.py} 時，@code{echo} 和 @code{main} 函式將被定義，但它們都不會被呼叫，因為 @code{__name__ != '__main__'}。

@node 打包時須考慮的事情,,慣用 Idiomatic 用法,__name__ == '__main__'
@anchor{library/__main__ packaging-considerations}@anchor{4837}
@subsubsection 打包時須考慮的事情


@code{main} 函式通常用於透過將它們指定為控制台腳本的入口點來建立命令列工具。完成後，pip@footnote{https://pip.pypa.io/} 將函式呼叫插入到模板腳本中，其中 @code{main} 的回傳值被傳遞到 @ref{277,,sys.exit()} 中。例如：

@example
sys.exit(main())
@end example

由於對 @code{main} 的呼叫包含在 @ref{277,,sys.exit()} 中，因此期望你的函式將傳回一些可接受作為 @ref{277,,sys.exit()} 輸入的值；通常來說，會是一個整數或 @code{None}（如果你的函式沒有 return 陳述式，則相當於回傳此值）。

透過我們自己主動遵循這個慣例，我們的模組在直接執行時（即 @code{python echo.py}）的行為，將和我們稍後將其打包為 pip 可安裝套件中的控制台腳本入口點相同。

特別是，要謹慎處理從 @code{main} 函式回傳字串。@ref{277,,sys.exit()} 會將字串引數直譯為失敗訊息，因此你的程式將有一個表示失敗的結束代碼 @code{1}，並且該字串將被寫入 @ref{b2a,,sys.stderr}。前面的 @code{echo.py} 範例使用慣例的 @code{sys.exit(main())} 進行示範。


@subsubheading 也參考


Python 打包使用者指南@footnote{https://packaging.python.org/}包含一系列如何使用現代工具發行和安裝 Python 套件的教學和參考資料。


@node Python 套件中的 __main__ py,import __main__,__name__ == '__main__',__main__ --- 頂層程式碼環境
@anchor{library/__main__ main-py-in-python-packages}@anchor{4838}
@subsubsection Python 套件中的 @code{__main__.py}


如果你不熟悉 Python 套件，請參閱 @ref{1f15,,套件 (Package)} 的教學章節。最常見的是，@code{__main__.py} 檔案用於為套件提供命令列介面。假設下面有虛構的套件 "bandclass"：

@example
bandclass
  ├── __init__.py
  ├── __main__.py
  └── student.py
@end example

當使用 @ref{23c,,-m} 旗標 (flag) 直接從命令列呼叫套件本身時，將執行 @code{__main__.py}。例如：

@example
$ python -m bandclass
@end example

該命令將導致 @code{__main__.py} 執行。如何利用此機制將取決於你正在編寫的套件的性質，但在這種虛構的情況下，允許教師搜尋學生可能是有意義的：

@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

請注意，@code{from .student import search_students} 是相對引入的範例。在引用套件內的模組時，可以使用此引入樣式。有關更多詳細資訊，請參閱 @ref{1f05,,模組 (Module)} 教學章節中的 @ref{1f19,,套件內引用}。

@menu
* 慣用 (Idiomatic) 用法: 慣用 Idiomatic 用法<2>. 

@end menu

@node 慣用 Idiomatic 用法<2>,,,Python 套件中的 __main__ py
@anchor{library/__main__ id1}@anchor{4839}
@subsubsection 慣用 (Idiomatic) 用法


@code{__main__.py} 的內容通常不會被 @code{if __name__ == '__main__'} 區塊包圍。相反的，這些檔案保持簡短並引入其他模組的函式來執行。那些其他模組就可以輕鬆地進行單元測試並且可以正確地重複使用。

如果在套件裡面的 @code{__main__.py} 檔案使用 @code{if __name__ == '__main__'} 區塊，它依然會如預期般地運作。因為當引入套件，其 @code{__name__} 屬性將會包含套件的路徑：

@example
>>> import asyncio.__main__
>>> asyncio.__main__.__name__
'asyncio.__main__'
@end example

但這對於 @code{.zip} 檔案根目錄中的 @code{__main__.py} 檔案不起作用。因此，為了保持一致性，最小的、沒有 @code{__name__} 檢查的 @code{__main__.py} 會是首選。


@subsubheading 也參考


請參閱 @ref{117,,venv} 作為標準函式庫中具有最小 @code{__main__.py} 的套件為範例。它不包含 @code{if __name__ == '__main__'} 區塊。你可以使用 @code{python -m venv [directory]} 來呼叫它。

請參閱 @ref{c3,,runpy} 取得有關直譯器可執行檔的 @ref{23c,,-m} 旗標的更多詳細資訊。

請參閱 @ref{136,,zipapp} 了解如何執行打包成 `.zip' 檔案的應用程式。在這種情況下，Python 會在封存檔案的根目錄中尋找 @code{__main__.py} 檔案。


@node import __main__,,Python 套件中的 __main__ py,__main__ --- 頂層程式碼環境
@anchor{library/__main__ import-main}@anchor{483a}
@subsubsection @code{import __main__}


無論 Python 程式是從哪個模組啟動的，在同一程式中執行的其他模組都可以透過匯入 @code{__main__} 模組來引入頂層環境的作用域 (@ref{1f06,,namespace})。這不會引入 @code{__main__.py} 檔案，而是引入接收特殊名稱 @code{'__main__'} 的模組。

這是一個使用 @code{__main__} 命名空間的範例模組：

@example
# namely.py

import __main__

def did_user_define_their_name():
    return 'my_name' in dir(__main__)

def print_user_name():
    if not did_user_define_their_name():
        raise ValueError('Define the variable `my_name`!')

    print(__main__.my_name)
@end example

該模組的範例用法如下：

@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

現在，如果我們啟動程式，結果將如下所示：

@example
$ python start.py
Define the variable `my_name`!
@end example

程式的結束代碼將為 1，表示出現錯誤。取消註解 @code{my_name = "Dinsdale"} 而修復程式後，現在它以狀態碼 0 結束，表示成功：

@example
$ python start.py
Dinsdale
@end example

請注意，引入 @code{__main__} 並不會因為不經意地執行放在 @code{start} 模組中 @code{if __name__ == "__main__"} 區塊的頂層程式碼（本來是給腳本使用的）而造成任何問題。為什麼這樣做會如預期運作？

當 Python 直譯器啟動時，會在 @ref{17c0,,sys.modules} 中插入一個空的 @code{__main__} 模組，並透過執行頂層程式碼來填充它。在我們的範例中，這是 @code{start} 模組，它將逐行執行並引入 @code{namely}。接著，@code{namely} 引入 @code{__main__}（其實是 @code{start}）。這就是一個引入循環！幸運的是，由於部分填充的 @code{__main__} 模組存在於 @ref{17c0,,sys.modules} 中，Python 將其傳遞給 @code{namely}。請參閱引入系統參考文件中的@ref{230e,,關於 __main__ 的特別考量}了解其工作原理的詳細資訊。

Python REPL 是「頂層環境」的另一個範例，因此 REPL 中定義的任何內容都成為 作域的一部分：

@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

@code{__main__} 作用域用於 @ref{aa,,pdb} 和 @ref{c2,,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__ --- 頂層程式碼環境,Python Runtime 服務
@anchor{library/warnings doc}@anchor{483b}@anchor{library/warnings module-warnings}@anchor{118}@anchor{library/warnings translation-repo}@anchor{483c}@anchor{library/warnings warnings-warning-control}@anchor{483d}
@subsection @code{warnings} --- 警告控制


@geindex module; warnings

`原始碼：'Lib/warnings.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/warnings.py}

@geindex warnings （警告）


__________________________________________________________________


警告訊息通常會在需要提醒使用者程式中的某些狀況時發出，而該狀況（通常）不至於需要引發例外並終止程式。舉例來說，當程式使用一個過時的模組時，就可能會需要發出警告。

Python 程式設計師可以透過呼叫此模組中定義的 @ref{170d,,warn()} 函式來發出警告。（C 語言的程式設計師則使用 @ref{1641,,PyErr_WarnEx()}；詳情請參閱 @ref{483e,,例外處理}）。

警告訊息通常會被寫入 @ref{b2a,,sys.stderr}，但它們的處理方式可以被彈性地更改，從忽略所有警告到將它們轉為例外都可以。警告的處理方式會根據 @ref{25bc,,警告類別}、警告訊息的文本，以及發出警告的原始碼位置而有所不同。在同一個原始碼位置重複出現的特定警告通常會被抑制。

警告控制有兩個階段：首先，每當發出一個警告時，會先決定是否該發出訊息；接著，如果要發出訊息，它會使用一個可由使用者設定的掛鉤 (hook) 來格式化並印出。

是否要發出警告訊息是由 @ref{1b1,,警告過濾器} 所控制，它是一連串的匹配規則和動作。可以透過呼叫 @ref{169d,,filterwarnings()} 來新增規則到過濾器中，並透過呼叫 @ref{483f,,resetwarnings()} 將其重設為預設狀態。

警告訊息的印出是透過呼叫 @ref{4840,,showwarning()} 來完成，而它可以被覆寫；此函式的預設實作會透過呼叫 @ref{1cc0,,formatwarning()} 來格式化訊息，它也可以被自訂的實作使用。


@subsubheading 也參考


@ref{3059,,logging.captureWarnings()} 允許你使用標準的 logging 基礎設施來處理所有警告。


@menu
* 警告類別:: 
* 警告過濾器:: 
* 暫時抑制警告:: 
* 測試警告:: 
* 為新版相依套件更新程式碼:: 
* 可用的函式:: 
* 可用的情境管理器:: 
* 情境管理器的並行安全性:: 

@end menu

@node 警告類別,警告過濾器,,warnings --- 警告控制
@anchor{library/warnings id1}@anchor{4841}@anchor{library/warnings warning-categories}@anchor{25bc}
@subsubsection 警告類別


有許多內建的例外代表警告類別。這種分類方式對於能夠過濾掉特定群組的警告很有用。

雖然這些在技術上是 @ref{25ba,,內建例外}，但它們被記錄在這裡，因為從概念上來說，它們屬於警告機制的一部分。

使用者程式碼可以透過繼承其中一個標準警告類別來定義額外的警告類別。一個警告類別必須永遠是 @ref{25bd,,Warning} 類別的子類別。

目前定義了以下警告類別：


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

類別

@tab

描述

@item

@ref{25bd,,Warning}

@tab

這是所有警告類別的基底類別。它是 @ref{bc4,,Exception} 的子類別。

@item

@ref{25be,,UserWarning}

@tab

@ref{170d,,warn()} 的預設類別。

@item

@ref{1a3,,DeprecationWarning}

@tab

關於已棄用功能的警告的基底類別，當這些警告是針對其他 Python 開發者時（預設為忽略，除非由 @code{__main__} 中的程式碼觸發）。

@item

@ref{1ae,,SyntaxWarning}

@tab

Base category for warnings about dubious
syntactic features (typically emitted when
compiling Python source code, and hence
may not be suppressed by runtime filters)

@item

@ref{4d2,,RuntimeWarning}

@tab

關於可疑 runtime 功能的警告的基底類別。

@item

@ref{651,,FutureWarning}

@tab

關於已棄用功能的警告的基底類別，當這些警告是針對以 Python 編寫的應用程式的終端使用者時。

@item

@ref{abd,,PendingDeprecationWarning}

@tab

關於未來將被棄用的功能的警告的基底類別（預設為忽略）。

@item

@ref{717,,ImportWarning}

@tab

在引入模組過程中觸發的警告的基底類別（預設為忽略）。

@item

@ref{161b,,UnicodeWarning}

@tab

與 Unicode 相關的警告的基底類別。

@item

@ref{e17,,BytesWarning}

@tab

與 @ref{192,,bytes} 和 @ref{343,,bytearray} 相關的警告的基底類別。

@item

@ref{547,,ResourceWarning}

@tab

與資源使用相關的警告的基底類別（預設為忽略）。

@end multitable



在 3.7 版的變更: 在過去，@ref{1a3,,DeprecationWarning} 和 @ref{651,,FutureWarning} 是根據一個功能是被完全移除還是改變其行為來區分的。它們現在是根據其目標受眾以及預設警告過濾器處理它們的方式來區分。


@node 警告過濾器,暫時抑制警告,警告類別,warnings --- 警告控制
@anchor{library/warnings the-warnings-filter}@anchor{4842}@anchor{library/warnings warning-filter}@anchor{1b1}
@subsubsection 警告過濾器


警告過濾器控制警告是被忽略、顯示，還是轉為錯誤（引發一個例外）。

從概念上講，警告過濾器維護一個有序的過濾器規格串列；任何特定的警告都會依次與串列中的每個過濾器規格進行比對，直到找到匹配項；過濾器決定了匹配項的處理方式。每個條目都是一個 (`action', `message', `category', `module', `lineno') 形式的元組，其中：


@itemize *

@item 
`action' 是以下字串之一：


@multitable {xxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

值

@tab

處理方式

@item

@code{"default"}

@tab

為發出警告的每個位置（模組 + 行號）印出第一次出現的匹配警告

@item

@code{"error"}

@tab

將匹配的警告轉為例外

@item

@code{"ignore"}

@tab

永不印出匹配的警告

@item

@code{"always"}

@tab

總是印出匹配的警告

@item

@code{"all"}

@tab

"always" 的別名

@item

@code{"module"}

@tab

為發出警告的每個模組印出第一次出現的匹配警告（不論行號）

@item

@code{"once"}

@tab

只印出第一次出現的匹配警告，不論位置

@end multitable


@item 
`message' 是一個包含正規表示式的字串，警告訊息的開頭必須與其匹配（不區分大小寫）。在 @ref{abc,,-W} 和 
@geindex PYTHONWARNINGS
@geindex 環境變數; PYTHONWARNINGS
@ref{d9e,,PYTHONWARNINGS} 中，`message' 是一個字面字串，警告訊息的開頭必須包含該字串（不區分大小寫），並忽略 `message' 開頭或結尾的任何空白字元。

@item 
`category' 是一個類別（@ref{25bd,,Warning} 的子類別），警告類別必須是它的子類別才能匹配。

@item 
`module' 是一個包含正規表示式的字串，完整限定模組名稱的開頭必須與其匹配（區分大小寫）。在 @ref{abc,,-W} 和 
@geindex PYTHONWARNINGS
@geindex 環境變數; PYTHONWARNINGS
@ref{d9e,,PYTHONWARNINGS} 中，`module' 是一個字面字串，完整限定模組名稱必須與其相等（區分大小寫），並忽略 `module' 開頭或結尾的任何空白字元。

@item 
`lineno' 是一個整數，發出警告的行號必須與其匹配，或者為 @code{0} 以匹配所有行號。
@end itemize

由於 @ref{25bd,,Warning} 類別衍生自內建的 @ref{bc4,,Exception} 類別，要將警告轉為錯誤，我們只需引發 @code{category(message)}。

如果一個警告被回報且不匹配任何已註冊的過濾器，則會套用 "default" 動作（因此得名）。

@menu
* 重複警告的抑制標準:: 
* 描述警告過濾器:: 
* 預設警告過濾器:: 
* 覆寫預設過濾器:: 

@end menu

@node 重複警告的抑制標準,描述警告過濾器,,警告過濾器
@anchor{library/warnings id2}@anchor{4843}@anchor{library/warnings repeated-warning-suppression-criteria}@anchor{4844}
@subsubsection 重複警告的抑制標準


抑制重複警告的過濾器會套用以下標準來判斷一個警告是否被視為重複：


@itemize -

@item 
@code{"default"}：只有當 (`message', `category', `module', `lineno') 都相同時，警告才被視為重複。

@item 
@code{"module"}：如果 (`message', `category', `module') 相同，則警告被視為重複，忽略行號。

@item 
@code{"once"}：如果 (`message', `category') 相同，則警告被視為重複，忽略模組和行號。
@end itemize

@node 描述警告過濾器,預設警告過濾器,重複警告的抑制標準,警告過濾器
@anchor{library/warnings describing-warning-filters}@anchor{1ff1}@anchor{library/warnings id3}@anchor{4845}
@subsubsection 描述警告過濾器


警告過濾器由傳遞給 Python 直譯器命令列的 @ref{abc,,-W} 選項和 
@geindex PYTHONWARNINGS
@geindex 環境變數; PYTHONWARNINGS
@ref{d9e,,PYTHONWARNINGS} 環境變數初始化。直譯器會將所有提供條目的引數未經直譯地儲存在 @ref{3f3,,sys.warnoptions} 中；@ref{118,,warnings} 模組在首次引入時會剖析這些引數（無效選項會被忽略，並在向 @ref{b2a,,sys.stderr} 印出一條訊息後）。

個別的警告過濾器被指定為一系列由冒號分隔的欄位：

@example
action:message:category:module:line
@end example

這些欄位中每一個的含義都如 @ref{1b1,,警告過濾器} 中所述。當在單一行中列出多個過濾器時（例如 
@geindex PYTHONWARNINGS
@geindex 環境變數; PYTHONWARNINGS
@ref{d9e,,PYTHONWARNINGS}），個別的過濾器會以逗號分隔，且後面列出的過濾器優先於前面列出的過濾器（因為它們是從左到右應用的，而最近應用的過濾器優先於較早的過濾器）。

常用的警告過濾器適用於所有警告、特定類別的警告，或由特定模組或套件引發的警告。一些範例如下：

@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{4846}@anchor{library/warnings id4}@anchor{4847}
@subsubsection 預設警告過濾器


預設情況下，Python 會安裝數個警告過濾器，這些過濾器可以被 @ref{abc,,-W} 命令列選項、
@geindex PYTHONWARNINGS
@geindex 環境變數; PYTHONWARNINGS
@ref{d9e,,PYTHONWARNINGS} 環境變數以及對 @ref{169d,,filterwarnings()} 的呼叫所覆寫。

在常規的發行建置中，預設的警告過濾器有以下條目（按優先順序排列）：

@example
default::DeprecationWarning:__main__
ignore::DeprecationWarning
ignore::PendingDeprecationWarning
ignore::ImportWarning
ignore::ResourceWarning
@end example

在 @ref{504,,偵錯建置} 中，預設警告過濾器串列是空的。


在 3.2 版的變更: 除了 @ref{abd,,PendingDeprecationWarning} 之外，@ref{1a3,,DeprecationWarning} 現在也預設被忽略。



在 3.7 版的變更: 當直接由 @code{__main__} 中的程式碼觸發時，@ref{1a3,,DeprecationWarning} 會再次預設顯示。



在 3.7 版的變更: @ref{e17,,BytesWarning} 不再出現在預設過濾器串列中，而是在指定 @ref{7f2,,-b} 兩次時，透過 @ref{3f3,,sys.warnoptions} 進行設定。


@node 覆寫預設過濾器,,預設警告過濾器,警告過濾器
@anchor{library/warnings overriding-the-default-filter}@anchor{4848}@anchor{library/warnings warning-disable}@anchor{4849}
@subsubsection 覆寫預設過濾器


以 Python 編寫的應用程式的開發者可能希望預設對其使用者隱藏 `所有' Python 層級的警告，並且只在執行測試或以其他方式處理應用程式時才顯示它們。用於將過濾器設定傳遞給直譯器的 @ref{3f3,,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

最後，建議在 @code{__main__} 以外的命名空間中執行使用者程式碼的互動式 shell 開發者，應確保 @ref{1a3,,DeprecationWarning} 訊息預設為可見，可使用如下程式碼（其中 @code{user_ns} 是用於執行互動式輸入程式碼的模組）：

@example
import warnings
warnings.filterwarnings("default", category=DeprecationWarning,
                                   module=user_ns.get("__name__"))
@end example

@node 暫時抑制警告,測試警告,警告過濾器,warnings --- 警告控制
@anchor{library/warnings temporarily-suppressing-warnings}@anchor{484a}@anchor{library/warnings warning-suppress}@anchor{484b}
@subsubsection 暫時抑制警告


如果你正在使用的程式碼，你知道它會引發一個警告（例如一個已棄用的函式），但你不想看到這個警告（即使警告已透過命令列明確設定），那麼可以使用 @ref{179,,catch_warnings} 情境管理器來抑制該警告：

@example
import warnings

def fxn():
    warnings.warn("deprecated", DeprecationWarning)

with warnings.catch_warnings():
    warnings.simplefilter("ignore")
    fxn()
@end example

在情境管理器中，所有警告都將被直接忽略。這允許你在使用已知的已棄用程式碼時不必看到警告，同時又不會抑制其他可能不知道自己正在使用已棄用程式碼的程式碼所發出的警告。

@quotation

@cartouche
@quotation 備註 
See @ref{484c,,情境管理器的並行安全性} for details on the
concurrency-safety of the @ref{179,,catch_warnings} context manager when
used in programs using multiple threads or async functions.
@end quotation
@end cartouche
@end quotation

@node 測試警告,為新版相依套件更新程式碼,暫時抑制警告,warnings --- 警告控制
@anchor{library/warnings testing-warnings}@anchor{484d}@anchor{library/warnings warning-testing}@anchor{484e}
@subsubsection 測試警告


要測試程式碼引發的警告，請使用 @ref{179,,catch_warnings} 情境管理器。透過它，你可以暫時改變警告過濾器以方便你的測試。例如，執行以下操作來捕獲所有引發的警告以進行檢查：

@example
import warnings

def fxn():
    warnings.warn("deprecated", DeprecationWarning)

with warnings.catch_warnings(record=True) as w:
    # 讓所有警告總是會被觸發。
    warnings.simplefilter("always")
    # 觸發一個警告。
    fxn()
    # 驗證一些事情
    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} 規則已經被引發過，那麼無論設定什麼過濾器，這個警告都不會再出現，除非與該警告相關的警告註冊表已被清除。

一旦情境管理器退出，警告過濾器就會恢復到進入情境時的狀態。這可以防止測試在不同測試之間以意想不到的方式更改警告過濾器，從而導致不確定的測試結果。

@quotation

@cartouche
@quotation 備註 
See @ref{484c,,情境管理器的並行安全性} for details on the
concurrency-safety of the @ref{179,,catch_warnings} context manager when
used in programs using multiple threads or async functions.
@end quotation
@end cartouche
@end quotation

在測試多個會引發同類警告的操作時，重要的是要以一種能確認每個操作都在引發新警告的方式來進行測試（例如，將警告設定為引發例外，並檢查操作是否引發例外；檢查警告串列的長度在每次操作後是否持續增加；或者在每次新操作前從警告串列中刪除先前的條目）。

@node 為新版相依套件更新程式碼,可用的函式,測試警告,warnings --- 警告控制
@anchor{library/warnings updating-code-for-new-versions-of-dependencies}@anchor{484f}@anchor{library/warnings warning-ignored}@anchor{44d8}
@subsubsection 為新版相依套件更新程式碼


主要針對 Python 開發者（而非以 Python 編寫的應用程式的終端使用者）的警告類別預設會被忽略。

值得注意的是，這個「預設忽略」串列包括 @ref{1a3,,DeprecationWarning}（除了 @code{__main__} 以外的所有模組），這意味著開發者應該確保在測試他們的程式碼時，讓通常被忽略的警告可見，以便及時收到未來 API 破壞性變更的通知（無論是在標準函式庫還是第三方套件中）。

在理想情況下，程式碼會有一個合適的測試套件，而測試執行器會在執行測試時負責隱式地啟用所有警告（@ref{10c,,unittest} 模組提供的測試執行器就是這樣做的）。

在較不理想的情況下，可以透過將 @ref{abc,,-Wd} 傳遞給 Python 直譯器（這是 @code{-W default} 的簡寫）或在環境中設定 @code{PYTHONWARNINGS=default} 來檢查應用程式是否使用了已棄用的介面。這會為所有警告啟用預設處理，包括那些預設被忽略的警告。要更改對遇到的警告所採取的動作，你可以更改傳遞給 @ref{abc,,-W} 的引數（例如 @code{-W error}）。有關更多可能性的詳細資訊，請參閱 @ref{abc,,-W} 旗標。

@node 可用的函式,可用的情境管理器,為新版相依套件更新程式碼,warnings --- 警告控制
@anchor{library/warnings available-functions}@anchor{4850}@anchor{library/warnings warning-functions}@anchor{4851}
@subsubsection 可用的函式


@geindex warn() (於 warnings 模組中)
@anchor{library/warnings warnings warn}@anchor{170d}
@deffn {函式} warnings.warn (message, category=None, stacklevel=1, source=None, *, skip_file_prefixes=())

發出一個警告，或者可能忽略它或引發一個例外。`category' 引數（如果提供）必須是一個 @ref{25bc,,警告類別}；它預設為 @ref{25be,,UserWarning}。或者，`message' 可以是一個 @ref{25bd,,Warning} 實例，在這種情況下 `category' 將被忽略，並使用 @code{message.__class__}。在這種情況下，訊息文本將是 @code{str(message)}。如果發出的特定警告被 @ref{1b1,,警告過濾器} 轉為錯誤，此函式會引發一個例外。`stacklevel' 引數可以被以 Python 編寫的包裝函式使用，如下所示：

@example
def deprecated_api(message):
    warnings.warn(message, DeprecationWarning, stacklevel=2)
@end example

這會讓警告指向 @code{deprecated_api} 的呼叫者，而不是 @code{deprecated_api} 本身的原始碼（因為後者會違背警告訊息的目的）。

`skip_file_prefixes' 關鍵字引數可用於指示在計算堆疊層級時應忽略哪些堆疊框。當你希望警告總是在套件外部的呼叫點出現，而固定的 `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} 套件之外的呼叫程式碼中，指向 @code{example.lower.one_way()} 和 @code{example.higher.another_way()} 的呼叫點。

`source'（如果提供）是發出 @ref{547,,ResourceWarning} 的已銷毀物件。


在 3.6 版的變更: 新增 `source' 參數。



在 3.12 版的變更: 新增 `skip_file_prefixes'。

@end deffn

@geindex warn_explicit() (於 warnings 模組中)
@anchor{library/warnings warnings warn_explicit}@anchor{ef8}
@deffn {函式} warnings.warn_explicit (message, category, filename, lineno, module=None, registry=None, module_globals=None, source=None)

這是一個 @ref{170d,,warn()} 功能的低階介面，明確傳入訊息、類別、檔名和行號，以及可選的其他引數。`message' 必須是字串，`category' 必須是 @ref{25bd,,Warning} 的子類別，或者 `message' 可以是 @ref{25bd,,Warning} 的實例，在這種情況下 `category' 將被忽略。

`module', if supplied, should be the module name.
If no module is passed, the filename with @code{.py} stripped is used.

`registry', if supplied, should be the @code{__warningregistry__} dictionary
of the module.
If no registry is passed, each warning is treated as the first occurrence,
that is, filter actions @code{"default"}, @code{"module"} and @code{"once"} are
handled as @code{"always"}.

`module_globals'（如果提供）應該是發出警告的程式碼所使用的全域命名空間。（此引數用於支援顯示在 zip 檔案或其他非檔案系統引入來源中找到的模組的原始碼）。

`source'（如果提供）是發出 @ref{547,,ResourceWarning} 的已銷毀物件。


在 3.6 版的變更: 新增 `source' 參數。

@end deffn

@geindex showwarning() (於 warnings 模組中)
@anchor{library/warnings warnings showwarning}@anchor{4840}
@deffn {函式} warnings.showwarning (message, category, filename, lineno, file=None, line=None)

將警告寫入一個檔案。預設實作會呼叫 @code{formatwarning(message, category, filename, lineno, line)} 並將結果字串寫入 `file'，預設為 @ref{b2a,,sys.stderr}。你可以透過賦值給 @code{warnings.showwarning} 來用任何可呼叫物件取代此函式。`line' 是要包含在警告訊息中的一行原始碼；如果未提供 `line'，@ref{4840,,showwarning()} 將嘗試讀取由 `filename' 和 `lineno' 指定的行。
@end deffn

@geindex formatwarning() (於 warnings 模組中)
@anchor{library/warnings warnings formatwarning}@anchor{1cc0}
@deffn {函式} warnings.formatwarning (message, category, filename, lineno, line=None)

以標準方式格式化警告。這會回傳一個可能包含嵌入換行符並以換行符結尾的字串。`line' 是要包含在警告訊息中的一行原始碼；如果未提供 `line'，@ref{1cc0,,formatwarning()} 將嘗試讀取由 `filename' 和 `lineno' 指定的行。
@end deffn

@geindex filterwarnings() (於 warnings 模組中)
@anchor{library/warnings warnings filterwarnings}@anchor{169d}
@deffn {函式} warnings.filterwarnings (action, message='@w{'}, category=Warning, module='@w{'}, lineno=0, append=False)

在 @ref{1b1,,警告過濾器規格} 串列中插入一個條目。預設情況下，條目會插入到最前面；如果 `append' 為 true，則會插入到最後面。這會檢查引數的型別，編譯 `message' 和 `module' 的正規表示式，並將它們作為一個元組插入到警告過濾器串列中。如果兩個條目都匹配一個特定的警告，那麼串列中較靠前的條目會覆寫較後面的條目。省略的引數預設為一個能匹配所有內容的值。
@end deffn

@geindex simplefilter() (於 warnings 模組中)
@anchor{library/warnings warnings simplefilter}@anchor{8c8}
@deffn {函式} warnings.simplefilter (action, category=Warning, lineno=0, append=False)

在 @ref{1b1,,警告過濾器規格} 串列中插入一個簡單的條目。函式參數的含義與 @ref{169d,,filterwarnings()} 相同，但不需要正規表示式，因為只要類別和行號匹配，插入的過濾器總是會匹配任何模組中的任何訊息。
@end deffn

@geindex resetwarnings() (於 warnings 模組中)
@anchor{library/warnings warnings resetwarnings}@anchor{483f}
@deffn {函式} warnings.resetwarnings ()

重設警告過濾器。這會捨棄所有先前對 @ref{169d,,filterwarnings()} 的呼叫效果，包括 @ref{abc,,-W} 命令列選項和對 @ref{8c8,,simplefilter()} 的呼叫。
@end deffn

@geindex deprecated() (於 warnings 模組中)
@anchor{library/warnings warnings deprecated}@anchor{484}
@deffn {函式} @@warnings.deprecated (msg, *, category=DeprecationWarning, stacklevel=1)

用來指示一個類別、函式或重載 (overload) 已被棄用的裝飾器。

當此裝飾器應用於一個物件時，在使用該物件時，可能會在 runtime 發出棄用警告。@ref{56e,,靜態型別檢查器} 也會在使用已棄用物件時產生診斷訊息。

用法：

@example
from warnings import deprecated
from typing import overload

@@deprecated("改用 B")
class A:
    pass

@@deprecated("改用 g")
def f():
    pass

@@overload
@@deprecated("對 int 的支援已棄用")
def g(x: int) -> int: ...
@@overload
def g(x: str) -> int: ...
@end example

由 `category' 指定的警告將在使用已棄用物件時於 runtime 發出。對於函式，這發生在呼叫時；對於類別，發生在實例化和建立子類別時。如果 `category' 是 @code{None}，則在 runtime 不會發出警告。`stacklevel' 決定了警告發出的位置。如果它是 @code{1}（預設值），警告會在已棄用物件的直接呼叫者處發出；如果更高，它會在堆疊的更上層發出。靜態型別檢查器的行為不受 `category' 和 `stacklevel' 引數的影響。

傳遞給裝飾器的棄用訊息會儲存在被裝飾物件的 @code{__deprecated__} 屬性中。如果應用於重載，裝飾器必須在 @ref{438e,,@@~typing.overload} 裝飾器之後，這樣屬性才會存在於 @ref{8b5,,typing.get_overloads()} 回傳的重載上。


在 3.13 版被加入: 參閱 
@geindex Python Enhancement Proposals; PEP 702
PEP 702@footnote{https://peps.python.org/pep-0702/}。

@end deffn

@node 可用的情境管理器,情境管理器的並行安全性,可用的函式,warnings --- 警告控制
@anchor{library/warnings available-context-managers}@anchor{4852}
@subsubsection 可用的情境管理器


@geindex catch_warnings (warnings 中的類別)
@anchor{library/warnings warnings catch_warnings}@anchor{179}
@deffn {類別} warnings.catch_warnings (*, record=False, module=None, action=None, category=Warning, lineno=0, append=False)

一個情境管理器，它會複製並在退出時恢復警告過濾器和 @ref{4840,,showwarning()} 函式。如果 `record' 引數為 @ref{d23,,False}（預設值），情境管理器在進入時回傳 @ref{87e,,None}。如果 `record' 為 @ref{e02,,True}，則會回傳一個串列，該串列會由自訂的 @ref{4840,,showwarning()} 函式（該函式也會抑制對 @code{sys.stdout} 的輸出）所看到的物件逐步填充。串列中的每個物件都具有與 @ref{4840,,showwarning()} 的引數同名的屬性。

`module' 引數接受一個模組，用以取代預設的 @ref{118,,warnings} 模組，而該（被傳入）模組的過濾器將會受到保護。此引數主要用於測試 @ref{118,,warnings} 模組本身。

如果 `action' 引數不是 @code{None}，則其餘引數會傳遞給 @ref{8c8,,simplefilter()}，就像在進入情境時立即呼叫它一樣。

有關 `category' 和 `lineno' 參數的含義，請參閱 @ref{1b1,,警告過濾器}。

@cartouche
@quotation 備註 
See @ref{484c,,情境管理器的並行安全性} for details on the
concurrency-safety of the @ref{179,,catch_warnings} context manager when
used in programs using multiple threads or async functions.
@end quotation
@end cartouche


在 3.11 版的變更: 新增 `action'、`category'、`lineno' 和 `append' 參數。

@end deffn

@node 情境管理器的並行安全性,,可用的情境管理器,warnings --- 警告控制
@anchor{library/warnings concurrent-safety-of-context-managers}@anchor{4853}@anchor{library/warnings warning-concurrent-safe}@anchor{484c}
@subsubsection 情境管理器的並行安全性


The behavior of @ref{179,,catch_warnings} context manager depends on the
@ref{18a,,sys.flags.context_aware_warnings} flag.  If the flag is true, the
context manager behaves in a concurrent-safe fashion and otherwise not.
Concurrent-safe means that it is both thread-safe and safe to use within
@ref{366d,,asyncio coroutines} and tasks.  Being thread-safe means
that behavior is predictable in a multi-threaded program.  The flag defaults
to true for free-threaded builds and false otherwise.

If the @ref{18a,,context_aware_warnings} flag is false, then
@ref{179,,catch_warnings} will modify the global attributes of the
@ref{118,,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 @ref{179,,catch_warnings} class at the same time, the
behavior is undefined.

If the flag is true, @ref{179,,catch_warnings} will not modify global
attributes and will instead use a @ref{17f0,,ContextVar} to
store the newly established warning filtering state.  A context variable
provides thread-local storage and it makes the use of @ref{179,,catch_warnings}
thread-safe.

The `record' parameter of the context handler also behaves differently
depending on the value of the flag.  When `record' is true and the flag is
false, the context manager works by replacing and then later restoring the
module's @ref{4840,,showwarning()} function.  That is not concurrent-safe.

When `record' is true and the flag is true, the @ref{4840,,showwarning()} function
is not replaced.  Instead, the recording status is indicated by an internal
property in the context variable.  In this case, the @ref{4840,,showwarning()}
function will not be restored when exiting the context handler.

The @ref{18a,,context_aware_warnings} flag can be set the @ref{16f,,-X context_aware_warnings} command-line option or by the
@geindex PYTHON_CONTEXT_AWARE_WARNINGS
@geindex 環境變數; PYTHON_CONTEXT_AWARE_WARNINGS
@ref{17db,,PYTHON_CONTEXT_AWARE_WARNINGS} environment variable.

@quotation

@cartouche
@quotation 備註 
It is likely that most programs that desire thread-safe
behaviour of the warnings module will also want to set the
@ref{175,,thread_inherit_context} flag to true.  That flag
causes threads created by @ref{176,,threading.Thread} to start
with a copy of the context variables from the thread starting
it.  When true, the context established by @ref{179,,catch_warnings}
in one thread will also apply to new threads started by it.  If false,
new threads will start with an empty warnings context variable,
meaning that any filtering that was established by a
@ref{179,,catch_warnings} context manager will no longer be active.
@end quotation
@end cartouche
@end quotation


在 3.14 版的變更: 新增了 @ref{18a,,sys.flags.context_aware_warnings} 旗標，以及在該旗標為 true 時用於 @ref{179,,catch_warnings} 的情境變數。先前 Python 版本的行為就像該旗標始終設置為 false 一樣。


@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 --- with 陳述式工具程式,warnings --- 警告控制,Python Runtime 服務
@anchor{library/dataclasses doc}@anchor{4854}@anchor{library/dataclasses dataclasses-data-classes}@anchor{4855}@anchor{library/dataclasses module-dataclasses}@anchor{33}@anchor{library/dataclasses translation-repo}@anchor{4856}
@subsection @code{dataclasses} --- Data Classes


@geindex module; dataclasses

`原始碼：'Lib/dataclasses.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/dataclasses.py}


__________________________________________________________________


This module provides a decorator and functions for automatically
adding generated @ref{1b62,,special methods} such as @ref{8b7,,__init__()} and
@ref{828,,__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.


在 3.7 版被加入.


@menu
* 模組內容: 模組內容<8>. 
* Post-init processing:: 
* 類別變數:: 
* Init-only variables:: 
* 凍結實例:: 
* 繼承:: 
* Re-ordering of keyword-only parameters in __init__(): Re-ordering of keyword-only parameters in __init__. 
* 預設工廠函式:: 
* 可變預設值:: 
* Descriptor-typed fields:: 

@end menu

@node 模組內容<8>,Post-init processing,,dataclasses --- Data Classes
@anchor{library/dataclasses module-contents}@anchor{4857}
@subsubsection 模組內容


@geindex dataclass() (於 dataclasses 模組中)
@anchor{library/dataclasses dataclasses dataclass}@anchor{4dc}
@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{932,,decorator} that is used to add generated
@ref{1b62,,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{f4c,,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.

如下所述，@code{@@dataclass} 裝飾器會向類別新增各種 "dunder" 方法。如果類別中已存在任何新增的方法，則行為會取決於參數，如下方文件所述。裝飾器會回傳呼叫它的同一個類別；不會建立新類別。

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

@code{@@dataclass} 的參數是：


@itemize -

@item 
`init'：如果為真（預設值），將生成一個 @ref{8b7,,__init__()} 方法。

如果該類別已經定義了 @code{__init__()}，則此參數會被忽略。

@item 
`repr': If true (the default), a @ref{828,,__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)}.

如果該類別已經定義了 @code{__repr__()}，則此參數會被忽略。

@item 
`eq': If true (the default), an @ref{ce9,,__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.

如果該類別已經定義了 @code{__eq__()}，則此參數會被忽略。

@item 
`order': If true (the default is @code{False}), @ref{14a1,,__lt__()},
@ref{150b,,__le__()}, @ref{150c,,__gt__()}, and @ref{150d,,__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{2eb,,ValueError} is raised.

如果該類別已經定義了 @code{__lt__()}、@code{__le__()}、@code{__gt__()} 或 @code{__ge__()} 中的任何一個，則引發 @ref{198,,TypeError}。

@item 
`unsafe_hash': If true, force @code{dataclasses} to create a
@ref{cea,,__hash__()} method, even though it may not be safe to do so.
Otherwise, generate a @ref{cea,,__hash__()} method according to how
`eq' and `frozen' are set.
The default value is @code{False}.

@code{__hash__()} is used by built-in @ref{7fa,,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{cea,,__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{198,,TypeError}.

如果 `eq' 和 `frozen' 都為真，預設情況下 @code{@@dataclass} 會為你生成一個 @code{__hash__()} 方法。如果 `eq' 為真且 `frozen' 為假，@code{__hash__()} 將被設定為 @code{None}，並將其標記為不可雜湊（因為它是可變的）。如果 `eq' 為假，@code{__hash__()} 將保持不變，這意味著將使用超類別的 @code{__hash__()} 方法（如果超類別是 @ref{c75,,object}，這意味著它將回退到基於 id 的雜湊）。

@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{4858,,discussion} below.

如果類別中定義了 @ref{222d,,__setattr__()} 或 @ref{222e,,__delattr__()} 且 `frozen' 為真，則會引發 @ref{198,,TypeError}。

@item 
`match_args': If true (the default is @code{True}), the
@ref{1b75,,__match_args__} tuple will be created from the list of
non keyword-only parameters to the generated @ref{8b7,,__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


在 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{8b7,,__init__()}
parameter generated from a keyword-only field must be specified
with a keyword when @code{__init__()} is called. See the @ref{21fd,,parameter}
glossary entry for details.  Also see the
@ref{4859,,KW_ONLY} section.

Keyword-only fields are not included in @code{__match_args__}.
@end itemize

@quotation


在 3.10 版被加入.

@end quotation


@itemize -

@item 
`slots': If true (the default is @code{False}), @ref{16df,,__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{198,,TypeError}
is raised.
@end itemize

@quotation

@cartouche
@quotation 警告 
Passing parameters to a base class @ref{83c,,__init_subclass__()}
when using @code{slots=True} will result in a @ref{198,,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


在 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{226c,,overriding them}.
Therefore, do not use @code{__slots__} to retrieve the field names of a
dataclass. Use @ref{189b,,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{11eb,,weakref-able}.
It is an error to specify @code{weakref_slot=True}
without also specifying @code{slots=True}.
@end itemize

@quotation


在 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{8b7,,__init__()} method, which will be defined as:

@example
def __init__(self, a: int, b: int = 0):
@end example

@ref{198,,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{18c1}
@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{485a,,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 @ref{485a,,MISSING} value.

@code{field()} 的參數是：


@itemize -

@item 
`default'：如果有提供，這將是該欄位的預設值。這是必需的，因為 @code{field()} 呼叫本身會替換預設值的正常位置。

@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{8b7,,__init__()} method.

@item 
`repr': If true (the default), this field is included in the
string returned by the generated @ref{828,,__repr__()} method.

@item 
`hash': This can be a bool or @code{None}.  If true, this field is
included in the generated @ref{cea,,__hash__()} method.  If false,
this field is excluded from the generated @ref{cea,,__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{ce9,,__eq__()},
@ref{150c,,__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{691,,MappingProxyType()} to make it read-only, and exposed
on the @ref{18c2,,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{8b7,,__init__()} method's
parameters are computed.

Keyword-only fields are also not included in @code{__match_args__}.
@end itemize

@quotation


在 3.10 版被加入.

@end quotation


@itemize -

@item 
`doc': optional docstring for this field.
@end itemize

@quotation


在 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{4dc,,@@dataclass} decorator runs, the class
attributes will all contain the default values for the fields, just
as if the default value itself were specified.  For example,
after:

@example
@@dataclass
class C:
    x: int
    y: int = field(repr=False)
    z: int = field(repr=False, default=10)
    t: int = 20
@end example

The class attribute @code{C.z} will be @code{10}, the class attribute
@code{C.t} will be @code{20}, and the class attributes @code{C.x} and
@code{C.y} will not be set.
@end deffn

@geindex Field (dataclasses 中的類別)
@anchor{library/dataclasses dataclasses Field}@anchor{18c2}
@deffn {類別} dataclasses.Field

@code{Field} objects describe each defined field. These objects
are created internally, and are returned by the @ref{189b,,fields()}
module-level method (see below).  Users should never instantiate a
@code{Field} object directly.  Its documented attributes are:


@itemize -

@item 
@code{name}：欄位的名稱。

@item 
@code{type}：欄位的型別。

@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{18c1,,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{1ad9}
@deffn {類別} dataclasses.InitVar

@code{InitVar[T]} type annotations describe variables that are @ref{485b,,init-only}. Fields annotated with @code{InitVar}
are considered pseudo-fields, and thus are neither returned by the
@ref{189b,,fields()} function nor used in any way except adding them as
parameters to @ref{8b7,,__init__()} and an optional
@ref{485c,,__post_init__()}.
@end deffn

@geindex fields() (於 dataclasses 模組中)
@anchor{library/dataclasses dataclasses fields}@anchor{189b}
@deffn {函式} dataclasses.fields (class_or_instance)

Returns a tuple of @ref{18c2,,Field} objects that define the fields for this
dataclass.  Accepts either a dataclass, or an instance of a dataclass.
Raises @ref{198,,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{19e4}
@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,
lists, and tuples are recursed into.  Other objects are copied with
@ref{d5d,,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{198,,TypeError} if `obj' is not a dataclass
instance.
@end deffn

@geindex astuple() (於 dataclasses 模組中)
@anchor{library/dataclasses dataclasses astuple}@anchor{19ed}
@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, lists, and
tuples are recursed into. Other objects are copied with
@ref{d5d,,copy.deepcopy()}.

從前面的例子繼續：

@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{198,,TypeError} if `obj' is not a dataclass
instance.
@end deffn

@geindex make_dataclass() (於 dataclasses 模組中)
@anchor{library/dataclasses dataclasses make_dataclass}@anchor{17dc}
@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{8b3,,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{4dc,,@@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{4dc,,@@dataclass}. By default, the @ref{4dc,,@@dataclass}
function is used.

This function is not strictly required, because any Python
mechanism for creating a new class with @ref{456,,__annotations__} can
then apply the @ref{4dc,,@@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

相當於：

@example
@@dataclass
class C:
    x: int
    y: 'typing.Any'
    z: int = 5

    def add_one(self):
        return self.x + 1
@end example


在 3.14 版被加入: Added the `decorator' parameter.

@end deffn

@geindex replace() (於 dataclasses 模組中)
@anchor{library/dataclasses dataclasses replace}@anchor{19bc}
@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{198,,TypeError}.  If keys in `changes' are not
field names of the given dataclass, raises @ref{198,,TypeError}.

The newly returned object is created by calling the @ref{8b7,,__init__()}
method of the dataclass.  This ensures that
@ref{485c,,__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{485c,,__post_init__()}.

It is an error for `changes' to contain any fields that are
defined as having @code{init=False}.  A @ref{2eb,,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{485c,,__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{1c0,,copy.replace()}.
@end deffn

@geindex is_dataclass() (於 dataclasses 模組中)
@anchor{library/dataclasses dataclasses is_dataclass}@anchor{1b29}
@deffn {函式} dataclasses.is_dataclass (obj)

如果它的參數是一個資料類別（包含一個資料類別的子類別）或一個實例則回傳 @code{True}，否則回傳 @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{485a}
@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{4859}
@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{8b7,,__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}.


在 3.10 版被加入.

@end deffn

@geindex FrozenInstanceError
@anchor{library/dataclasses dataclasses FrozenInstanceError}@anchor{485d}
@deffn {例外} dataclasses.FrozenInstanceError

Raised when an implicitly defined @ref{222d,,__setattr__()} or
@ref{222e,,__delattr__()} is called on a dataclass which was defined with
@code{frozen=True}. It is a subclass of @ref{5e8,,AttributeError}.
@end deffn

@node Post-init processing,類別變數,模組內容<8>,dataclasses --- Data Classes
@anchor{library/dataclasses id1}@anchor{485e}@anchor{library/dataclasses post-init-processing}@anchor{485f}
@subsubsection Post-init processing


@geindex __post_init__() (於 dataclasses 模組中)
@anchor{library/dataclasses dataclasses __post_init__}@anchor{485c}
@deffn {函式} dataclasses.__post_init__ ()

When defined on the class, it will be called by the generated
@ref{8b7,,__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{8b7,,__init__()} method generated by @ref{4dc,,@@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{485c,,__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{19bc,,replace()} handles @code{init=False} fields.

@node 類別變數,Init-only variables,Post-init processing,dataclasses --- Data Classes
@anchor{library/dataclasses class-variables}@anchor{4860}@anchor{library/dataclasses dataclasses-class-variables}@anchor{4861}
@subsubsection 類別變數


One of the few places where @ref{4dc,,@@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{567,,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{189b,,fields()} function.

@node Init-only variables,凍結實例,類別變數,dataclasses --- Data Classes
@anchor{library/dataclasses dataclasses-init-only-variables}@anchor{485b}@anchor{library/dataclasses init-only-variables}@anchor{4862}
@subsubsection Init-only variables


Another place where @ref{4dc,,@@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{1ad9,,InitVar}.  If a field
is an @ref{1ad9,,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{189b,,fields()} function.  Init-only fields are added as
parameters to the generated @ref{8b7,,__init__()} method, and are passed to
the optional @ref{485c,,__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{189b,,fields()} will return @ref{18c2,,Field} objects for @code{i} and
@code{j}, but not for @code{database}.

@node 凍結實例,繼承,Init-only variables,dataclasses --- Data Classes
@anchor{library/dataclasses dataclasses-frozen}@anchor{4858}@anchor{library/dataclasses frozen-instances}@anchor{4863}
@subsubsection 凍結實例


It is not possible to create truly immutable Python objects.  However,
by passing @code{frozen=True} to the @ref{4dc,,@@dataclass} decorator you can
emulate immutability.  In that case, dataclasses will add
@ref{222d,,__setattr__()} and @ref{222e,,__delattr__()} methods to the class.  These
methods will raise a @ref{485d,,FrozenInstanceError} when invoked.

There is a tiny performance penalty when using @code{frozen=True}:
@ref{8b7,,__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 繼承,Re-ordering of keyword-only parameters in __init__,凍結實例,dataclasses --- Data Classes
@anchor{library/dataclasses dataclasses-inheritance}@anchor{4864}@anchor{library/dataclasses inheritance}@anchor{4865}
@subsubsection 繼承


When the dataclass is being created by the @ref{4dc,,@@dataclass} decorator,
it looks through all of the class's base classes in reverse MRO (that
is, starting at @ref{c75,,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{19b,,int}, as specified in class @code{C}.

The generated @ref{8b7,,__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__,預設工廠函式,繼承,dataclasses --- Data Classes
@anchor{library/dataclasses re-ordering-of-keyword-only-parameters-in-init}@anchor{4866}
@subsubsection Re-ordering of keyword-only parameters in @code{__init__()}


After the parameters needed for @ref{8b7,,__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 預設工廠函式,可變預設值,Re-ordering of keyword-only parameters in __init__,dataclasses --- Data Classes
@anchor{library/dataclasses default-factory-functions}@anchor{4867}
@subsubsection 預設工廠函式


If a @ref{18c1,,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{8b7,,__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 可變預設值,Descriptor-typed fields,預設工廠函式,dataclasses --- Data Classes
@anchor{library/dataclasses mutable-default-values}@anchor{4868}
@subsubsection 可變預設值


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 = []      # 這段程式碼會引發 ValueError
    def add(self, element):
        self.x.append(element)
@end example

它會生成類似的程式碼：

@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{4dc,,@@dataclass} decorator will raise a @ref{2eb,,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{24d,,list},
@ref{183,,dict}, or @ref{184,,set}, unhashable objects are now not allowed as
default values.  Unhashability is used to approximate
mutability.


@node Descriptor-typed fields,,可變預設值,dataclasses --- Data Classes
@anchor{library/dataclasses descriptor-typed-fields}@anchor{4869}
@subsubsection Descriptor-typed fields


Fields that are assigned @ref{e44,,descriptor objects} as their
default value have the following special behaviors:


@itemize *

@item 
The value for the field passed to the dataclass's @ref{8b7,,__init__()} method is
passed to the descriptor's @ref{2267,,__set__()} method rather than overwriting the
descriptor object.

@item 
Similarly, when getting or setting the field, the descriptor's
@ref{16dc,,__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{4dc,,@@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{5e8,,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    # 以 2.5 呼叫 __set__
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 --- with 陳述式工具程式,abc --- 抽象基底類別,dataclasses --- Data Classes,Python Runtime 服務
@anchor{library/contextlib doc}@anchor{486a}@anchor{library/contextlib contextlib-utilities-for-with-statement-contexts}@anchor{486b}@anchor{library/contextlib module-contextlib}@anchor{27}@anchor{library/contextlib translation-repo}@anchor{486c}
@subsection @code{contextlib} --- @code{with} 陳述式工具程式


@geindex module; contextlib

`原始碼：'Lib/contextlib.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/contextlib.py}


__________________________________________________________________


This module provides utilities for common tasks involving the @ref{186,,with}
statement. For more information see also @ref{22bc,,情境管理器型別} and
@ref{22ba,,With 陳述式的情境管理器}.

@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 --- with 陳述式工具程式
@anchor{library/contextlib utilities}@anchor{486d}
@subsubsection Utilities


Functions and classes provided:

@geindex AbstractContextManager (contextlib 中的類別)
@anchor{library/contextlib contextlib AbstractContextManager}@anchor{e85}
@deffn {類別} contextlib.AbstractContextManager

An @ref{13b7,,abstract base class} for classes that implement
@ref{7dd,,object.__enter__()} and @ref{1501,,object.__exit__()}. A default
implementation for @ref{7dd,,object.__enter__()} is provided which returns
@code{self} while @ref{1501,,object.__exit__()} is an abstract method which by default
returns @code{None}. See also the definition of @ref{22bc,,情境管理器型別}.


在 3.6 版被加入.

@end deffn

@geindex AbstractAsyncContextManager (contextlib 中的類別)
@anchor{library/contextlib contextlib AbstractAsyncContextManager}@anchor{d18}
@deffn {類別} contextlib.AbstractAsyncContextManager

An @ref{13b7,,abstract base class} for classes that implement
@ref{22cd,,object.__aenter__()} and @ref{18f8,,object.__aexit__()}. A default
implementation for @ref{22cd,,object.__aenter__()} is provided which returns
@code{self} while @ref{18f8,,object.__aexit__()} is an abstract method which by default
returns @code{None}. See also the definition of
@ref{80b,,Asynchronous Context Managers}.


在 3.7 版被加入.

@end deffn

@geindex contextmanager() (於 contextlib 模組中)
@anchor{library/contextlib contextlib contextmanager}@anchor{1403}
@deffn {函式} @@contextlib.contextmanager

This function is a @ref{932,,decorator} that can be used to define a factory
function for @ref{186,,with} statement context managers, without needing to
create a class or separate @ref{7dd,,__enter__()} and @ref{1501,,__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{125c,,generator}-iterator when
called. This iterator must yield exactly one value, which will be bound to
the targets in the @ref{186,,with} statement's @code{as} clause, if any.

At the point where the generator yields, the block nested in the @ref{186,,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{8f0,,try}...@ref{1ab,,except}...@ref{1b0,,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.

@ref{1403,,contextmanager()} uses @ref{1402,,ContextDecorator} so the context managers
it creates can be used as decorators as well as in @ref{186,,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 @ref{1403,,contextmanager()} to meet the requirement that context
managers support multiple invocations in order to be used as decorators).


在 3.2 版的變更: Use of @ref{1402,,ContextDecorator}.

@end deffn

@geindex asynccontextmanager() (於 contextlib 模組中)
@anchor{library/contextlib contextlib asynccontextmanager}@anchor{d17}
@deffn {函式} @@contextlib.asynccontextmanager

Similar to @ref{1403,,contextmanager()}, but creates an
@ref{80b,,asynchronous context manager}.

This function is a @ref{932,,decorator} that can be used to define a factory
function for @ref{185,,async with} statement asynchronous context managers,
without needing to create a class or separate @ref{22cd,,__aenter__()} and
@ref{18f8,,__aexit__()} methods. It must be applied to an @ref{2342,,asynchronous generator} function.

一個簡單範例：

@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


在 3.7 版被加入.


Context managers defined with @ref{d17,,asynccontextmanager()} can be used
either as decorators or with @ref{185,,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 @ref{d17,,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 @ref{d17,,asynccontextmanager()} can
be used as decorators.

@end deffn

@geindex closing() (於 contextlib 模組中)
@anchor{library/contextlib contextlib closing}@anchor{1581}
@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{186,,with} block is exited.

@cartouche
@quotation 備註 
Most types managing resources support the @ref{1e1,,context manager} protocol,
which closes `thing' on leaving the @ref{186,,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{306,,urlopen()} would normally be used in a context manager.
@end quotation
@end cartouche
@end deffn

@geindex aclosing() (於 contextlib 模組中)
@anchor{library/contextlib contextlib aclosing}@anchor{9e7}
@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{17f,,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).


在 3.10 版被加入.

@end deffn

@geindex nullcontext() (於 contextlib 模組中)
@anchor{library/contextlib simplifying-support-for-single-optional-context-managers}@anchor{486e}@anchor{library/contextlib contextlib nullcontext}@anchor{9e8}
@deffn {函式} contextlib.nullcontext (enter_result=None)

Return a context manager that returns `enter_result' from @code{__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

一個使用 `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{80b,,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


在 3.7 版被加入.



在 3.10 版的變更: @ref{7e8,,asynchronous context manager} support was added.

@end deffn

@geindex suppress() (於 contextlib 模組中)
@anchor{library/contextlib contextlib suppress}@anchor{1123}
@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.

舉例來說：

@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{486f,,reentrant}.

If the code within the @code{with} block raises a
@ref{560,,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{1988,,derive()}
method.


在 3.4 版被加入.



在 3.12 版的變更: @code{suppress} now supports suppressing exceptions raised as
part of a @ref{560,,BaseExceptionGroup}.

@end deffn

@geindex redirect_stdout() (於 contextlib 模組中)
@anchor{library/contextlib contextlib redirect_stdout}@anchor{fe2}
@deffn {函式} contextlib.redirect_stdout (new_target)

Context manager for temporarily redirecting @ref{cc4,,sys.stdout} to
another file or file-like object.

This tool adds flexibility to existing functions or classes whose output
is hardwired to stdout.

For example, the output of @ref{acb,,help()} normally is sent to `sys.stdout'.
You can capture that output in a string by redirecting the output to an
@ref{1124,,io.StringIO} object. The replacement stream is returned from the
@code{__enter__} method and so is available as the target of the
@ref{186,,with} statement:

@example
with redirect_stdout(io.StringIO()) as f:
    help(pow)
s = f.getvalue()
@end example

To send the output of @ref{acb,,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{acb,,help()} to `sys.stderr':

@example
with redirect_stdout(sys.stderr):
    help(pow)
@end example

Note that the global side effect on @ref{cc4,,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{486f,,reentrant}.


在 3.4 版被加入.

@end deffn

@geindex redirect_stderr() (於 contextlib 模組中)
@anchor{library/contextlib contextlib redirect_stderr}@anchor{fe1}
@deffn {函式} contextlib.redirect_stderr (new_target)

Similar to @ref{fe2,,redirect_stdout()} but redirecting
@ref{b2a,,sys.stderr} to another file or file-like object.

This context manager is @ref{486f,,reentrant}.


在 3.5 版被加入.

@end deffn

@geindex chdir() (於 contextlib 模組中)
@anchor{library/contextlib contextlib chdir}@anchor{819}
@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{81a,,chdir()}, it changes the current
working directory upon entering and restores the old one on exit.

This context manager is @ref{486f,,reentrant}.


在 3.11 版被加入.

@end deffn

@geindex ContextDecorator (contextlib 中的類別)
@anchor{library/contextlib contextlib ContextDecorator}@anchor{1402}
@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
@code{__enter__} and @code{__exit__} as normal. @code{__exit__} retains its optional
exception handling even when used as a decorator.

@code{ContextDecorator} is used by @ref{1403,,contextmanager()}, so you get this
functionality automatically.

@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{186,,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


在 3.2 版被加入.

@end deffn

@geindex AsyncContextDecorator (contextlib 中的類別)
@anchor{library/contextlib contextlib AsyncContextDecorator}@anchor{9e9}
@deffn {類別} contextlib.AsyncContextDecorator

Similar to @ref{1402,,ContextDecorator} but only for asynchronous functions.

@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


在 3.10 版被加入.

@end deffn

@geindex ExitStack (contextlib 中的類別)
@anchor{library/contextlib contextlib ExitStack}@anchor{d16}
@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{7dd,,__enter__()} method returns the @ref{d16,,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{186,,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{186,,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.


在 3.3 版被加入.


@geindex enter_context() (contextlib.ExitStack 的方法)
@anchor{library/contextlib contextlib ExitStack enter_context}@anchor{7e7}
@deffn {方法} enter_context (cm)

Enters a new context manager and adds its @ref{1501,,__exit__()} method to
the callback stack. The return value is the result of the context
manager's own @ref{7dd,,__enter__()} method.

These context managers may suppress exceptions just as they normally
would if used directly as part of a @ref{186,,with} statement.


在 3.11 版的變更: Raises @ref{198,,TypeError} instead of @ref{5e8,,AttributeError} if `cm'
is not a context manager.

@end deffn

@geindex push() (contextlib.ExitStack 的方法)
@anchor{library/contextlib contextlib ExitStack push}@anchor{4870}
@deffn {方法} push (exit)

Adds a context manager's @ref{1501,,__exit__()} method to the callback stack.

As @code{__enter__} is `not' invoked, this method can be used to cover
part of an @ref{7dd,,__enter__()} implementation with a context manager's own
@ref{1501,,__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{1501,,__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{1501,,__exit__()} methods can.

The passed in object is returned from the function, allowing this
method to be used as a function decorator.
@end deffn

@geindex callback() (contextlib.ExitStack 的方法)
@anchor{library/contextlib contextlib ExitStack callback}@anchor{c6d}
@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{4871}
@deffn {方法} pop_all ()

Transfers the callback stack to a fresh @ref{d16,,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{186,,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{4872}
@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{d19}
@deffn {類別} contextlib.AsyncExitStack

An @ref{80b,,asynchronous context manager}, similar
to @ref{d16,,ExitStack}, that supports combining both synchronous and
asynchronous context managers, as well as having coroutines for
cleanup logic.

The @ref{4872,,close()} method is not implemented; @ref{4873,,aclose()} must be used
instead.

@geindex enter_async_context() (contextlib.AsyncExitStack 的方法)
@anchor{library/contextlib contextlib AsyncExitStack enter_async_context}@anchor{7e9}
@deffn {方法} async enter_async_context (cm)

Similar to @ref{7e7,,ExitStack.enter_context()} but expects an asynchronous context
manager.


在 3.11 版的變更: Raises @ref{198,,TypeError} instead of @ref{5e8,,AttributeError} if `cm'
is not an asynchronous context manager.

@end deffn

@geindex push_async_exit() (contextlib.AsyncExitStack 的方法)
@anchor{library/contextlib contextlib AsyncExitStack push_async_exit}@anchor{4874}
@deffn {方法} push_async_exit (exit)

Similar to @ref{4870,,ExitStack.push()} but expects either an asynchronous context manager
or a coroutine function.
@end deffn

@geindex push_async_callback() (contextlib.AsyncExitStack 的方法)
@anchor{library/contextlib contextlib AsyncExitStack push_async_callback}@anchor{c6e}
@deffn {方法} push_async_callback (callback, /, *args, **kwds)

Similar to @ref{c6d,,ExitStack.callback()} but expects a coroutine function.
@end deffn

@geindex aclose() (contextlib.AsyncExitStack 的方法)
@anchor{library/contextlib contextlib AsyncExitStack aclose}@anchor{4873}
@deffn {方法} async aclose ()

Similar to @ref{4872,,ExitStack.close()} but properly handles awaitables.
@end deffn

Continuing the example for @ref{d17,,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


在 3.7 版被加入.

@end deffn

@node Examples and Recipes<2>,Single use reusable and reentrant context managers,Utilities,contextlib --- with 陳述式工具程式
@anchor{library/contextlib examples-and-recipes}@anchor{4875}
@subsubsection Examples and Recipes


This section describes some examples and recipes for making effective use of
the tools provided by @ref{27,,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{4876}
@subsubsection Supporting a variable number of context managers


The primary use case for @ref{d16,,ExitStack} is the one given in the class
documentation: supporting a variable number of context managers and other
cleanup operations in a single @ref{186,,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{d16,,ExitStack} also makes it quite easy to use @ref{186,,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{4877}
@subsubsection Catching exceptions from @code{__enter__} methods


It is occasionally desirable to catch exceptions from an @code{__enter__}
method implementation, `without' inadvertently catching exceptions from
the @ref{186,,with} statement body or the context manager's @code{__exit__}
method. By using @ref{d16,,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{8f0,,try}/@ref{1ab,,except}/@ref{1b0,,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{d16,,ExitStack} can make it
easier to handle various situations that can't be handled directly in a
@ref{186,,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{4878}
@subsubsection Cleaning up in an @code{__enter__} implementation


As noted in the documentation of @ref{4870,,ExitStack.push()}, this
method can be useful in cleaning up an already allocated resource if later
steps in the @ref{7dd,,__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{4879}
@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{d16,,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{c6d,,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{487a}
@subsubsection Using a context manager as a function decorator


@ref{1402,,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{1402,,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{7dd,,__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/} - "with" 陳述式

The specification, background, and examples for the Python @ref{186,,with}
statement.
@end table


@node Single use reusable and reentrant context managers,,Examples and Recipes<2>,contextlib --- with 陳述式工具程式
@anchor{library/contextlib single-use-reusable-and-reentrant-cms}@anchor{1125}@anchor{library/contextlib single-use-reusable-and-reentrant-context-managers}@anchor{487b}
@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{186,,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{186,,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{186,,with} statement will close the file, preventing any
further IO operations using that file object.

Context managers created using @ref{1403,,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{486f}@anchor{library/contextlib reentrant-context-managers}@anchor{487c}
@subsubsection Reentrant context managers


More sophisticated context managers may be "reentrant". These context
managers can not only be used in multiple @ref{186,,with} statements,
but may also be used `inside' a @code{with} statement that is already
using the same context manager.

@ref{32d,,threading.RLock} is an example of a reentrant context manager, as are
@ref{1123,,suppress()}, @ref{fe2,,redirect_stdout()}, and @ref{819,,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{fe2,,redirect_stdout()}, for example, is definitely not thread safe, as it
makes a global modification to the system state by binding @ref{cc4,,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{487d}@anchor{library/contextlib reusable-context-managers}@anchor{487e}
@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{1943,,threading.Lock} is an example of a reusable, but not reentrant,
context manager (for a reentrant lock, it is necessary to use
@ref{32d,,threading.RLock} instead).

Another example of a reusable, but not reentrant, context manager is
@ref{d16,,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{d16,,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 --- 抽象基底類別,atexit --- 退出處理函式,contextlib --- with 陳述式工具程式,Python Runtime 服務
@anchor{library/abc doc}@anchor{487f}@anchor{library/abc abc-abstract-base-classes}@anchor{4880}@anchor{library/abc module-abc}@anchor{4}@anchor{library/abc translation-repo}@anchor{4881}
@subsection @code{abc} --- 抽象基底類別


@geindex module; abc

@c much of the content adapted from docstrings

`原始碼：'Lib/abc.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/abc.py}


__________________________________________________________________


如同在 
@geindex Python Enhancement Proposals; PEP 3119
PEP 3119@footnote{https://peps.python.org/pep-3119/} 中所述，該模組提供了在 Python 中定義@ref{13b7,,抽象基底類別} (ABC) 的基礎元件；若想瞭解為什麼需要在 Python 中增加這個模組，請見 PEP 文件。（也請見 
@geindex Python Enhancement Proposals; PEP 3141
PEP 3141@footnote{https://peps.python.org/pep-3141/} 以及 @ref{a2,,numbers} 模組以瞭解基於 ABC 的數字型別階層關係。）

@ref{1e,,collections} 模組中有一些衍生自 ABC 的具體類別；當然這些類別還可以進一步衍生出其他類別。此外，@ref{1f,,collections.abc} 子模組中有一些 ABC 可被用於測試一個類別或實例是否提供特定介面，例如它是否@ref{81d,,可雜湊 (hashable)} 或它是否為@ref{13bc,,對映}。

該模組提供了一個用來定義 ABC 的元類別 (metaclass) @ref{1116,,ABCMeta} 和另一個以繼承的方式定義 ABC 的工具類別 @ref{1115,,ABC}：

@geindex ABC (abc 中的類別)
@anchor{library/abc abc ABC}@anchor{1115}
@deffn {類別} abc.ABC

一個使用 @ref{1116,,ABCMeta} 作為元類別的工具類別。抽象基底類別可以透過自 @code{ABC} 衍生而建立，這就避免了在某些情況下會令人混淆的元類別用法，用法如以下範例：

@example
from abc import ABC

class MyABC(ABC):
    pass
@end example

注意 @code{ABC} 的型別仍然是 @ref{1116,,ABCMeta}，因此繼承 @code{ABC} 仍然需要關注使用元類別的注意事項，如多重繼承可能會導致元類別衝突。當然你也可以傳入元類別關鍵字並直接使用 @code{ABCMeta} 來定義一個抽象基底類別，例如：

@example
from abc import ABCMeta

class MyABC(metaclass=ABCMeta):
    pass
@end example


在 3.4 版被加入.

@end deffn

@geindex ABCMeta (abc 中的類別)
@anchor{library/abc abc ABCMeta}@anchor{1116}
@deffn {類別} abc.ABCMeta

用於定義抽象基底類別（ABC）的元類別。

使用該元類別以建立一個 ABC。一個 ABC 可以像 mix-in 類別一樣直接被子類別繼承。你也可以將不相關的具體類別（甚至是內建類別）和 ABC 註冊為「虛擬子類別 (virtual subclass)」 —— 這些類別以及它們的子類別會被內建函式 @ref{9bd,,issubclass()} 識別為已註冊 ABC 的子類別，但是該 ABC 不會出現在其 MRO（Method Resolution Order，方法解析順序）中，由該 ABC 所定義的方法實作也不可呼叫（即使透過 @ref{1a6,,super()} 呼叫也不行）。@footnote{
C++ 程式設計師需要注意到 Python 中虛擬基底類別的概念和 C++ 中的並不相同。
}

使用 @code{ABCMeta} 作為元類別建立的類別含有以下的方法：

@geindex register() (abc.ABCMeta 的方法)
@anchor{library/abc abc ABCMeta register}@anchor{1289}
@deffn {方法} register (subclass)

將`子類別'註冊為該 ABC 的「抽象子類別」，例如：

@example
from abc import ABC

class MyABC(ABC):
    pass

MyABC.register(tuple)

assert issubclass(tuple, MyABC)
assert isinstance((), MyABC)
@end example


在 3.3 版的變更: 回傳已註冊的子類別，使其能夠作為類別裝飾器。



在 3.4 版的變更: 你可以使用 @ref{1114,,get_cache_token()} 函式來檢測對 @code{register()} 的呼叫。

@end deffn

你也可以覆寫 (override) 虛擬基底類別中的這個方法：

@geindex __subclasshook__() (abc.ABCMeta 的方法)
@anchor{library/abc abc ABCMeta __subclasshook__}@anchor{2849}
@deffn {方法} __subclasshook__ (subclass)

（必須定義為類別方法。）

檢查 `subclass' 是否該被認為是該 ABC 的子類別，也就是說你可以直接自訂 @ref{9bd,,issubclass()} 的行為，而不用對於那些你希望定義為該 ABC 的子類別的類別都個別呼叫 @ref{1289,,register()} 方法。（這個類別方法是在 ABC 的 @ref{2279,,__subclasscheck__()} 方法中呼叫。）

此方法必須回傳 @code{True}、@code{False} 或是 @ref{1a2,,NotImplemented}。如果回傳 @code{True}，`subclass' 就會被認為是這個 ABC 的子類別。如果回傳 @code{False}，`subclass' 就會被判定並非該 ABC 的子類別，即便正常情況應如此。如果回傳 @code{NotImplemented}，子類別檢查會按照正常機制繼續執行。

@c XXX explain the "usual mechanism"
@end deffn

為了對這些概念做一演示，請見以下定義 ABC 的範例：

@example
class Foo:
    def __getitem__(self, index):
        ...
    def __len__(self):
        ...
    def get_iterator(self):
        return iter(self)

class MyIterable(ABC):

    @@abstractmethod
    def __iter__(self):
        while False:
            yield None

    def get_iterator(self):
        return self.__iter__()

    @@classmethod
    def __subclasshook__(cls, C):
        if cls is MyIterable:
            if any("__iter__" in B.__dict__ for B in C.__mro__):
                return True
        return NotImplemented

MyIterable.register(Foo)
@end example

ABC @code{MyIterable} 定義了作為抽象方法的一個標準疊代方法 @ref{e64,,__iter__()}。這裡給定的實作仍可在子類別中被呼叫。@code{get_iterator()} 方法也是 @code{MyIterable} 抽象基底類別的一部分，但它不必被非抽象衍生類別覆寫。

這裡定義的 @ref{2849,,__subclasshook__()} 類別方法說明任何在其 @ref{776,,__dict__} (或在其透過 @ref{2229,,__mro__} 列表存取的基底類別) 中具有 @ref{e64,,__iter__()} 方法的類別也都會被視為 @code{MyIterable}。

最後，即使 @code{Foo} 沒有定義 @ref{e64,,__iter__()} 方法（它使用了以 @ref{2260,,__len__()} 和 @ref{582,,__getitem__()} 所定義的舊式可疊代物件協定），最末一行使其成為 @code{MyIterable} 的一個虛擬子類別。請注意這不會使 @code{get_iterator} 成為 @code{Foo} 的一個可用方法，所以它是需要被另外提供的。
@end deffn

@code{abc} 模組也提供了這些裝飾器：

@geindex abstractmethod() (於 abc 模組中)
@anchor{library/abc abc abstractmethod}@anchor{1286}
@deffn {函式} @@abc.abstractmethod

用於表示抽象方法的裝飾器。

類別的元類別是 @ref{1116,,ABCMeta} 或是從該類別衍生才能使用此裝飾器。一個具有衍生自 @code{ABCMeta} 之元類別的類別不可以被實例化，除非它全部的抽象方法和特性均已被覆寫。抽象方法可透過任何一般的 'super' 呼叫機制來呼叫。@code{abstractmethod()} 可被用於為特性和描述器宣告的抽象方法。

僅在使用 @ref{4882,,update_abstractmethods()} 函式時，才能夠動態地為一個類別新增抽象方法，或者嘗試在方法或類別被建立後修改其抽象狀態。@code{abstractmethod()} 只會影響使用常規繼承所衍生出的子類別；透過 ABC 的 @ref{1289,,register()} 方法註冊的「虛擬子類別」不會受到影響。

當 @code{abstractmethod()} 與其他方法描述器 (method descriptor) 配合應用時，它應被當最內層的裝飾器，如以下用法範例所示：

@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

為了能正確地與 ABC 機制實作相互操作，描述器必須使用 @code{__isabstractmethod__} 將自身標識為抽象的。一般來說，如果被用於組成描述器的任一方法是抽象的，則此屬性應當為 @code{True}。 例如，Python 的內建 @ref{4ae,,property} 所做的就等價於：

@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 備註 
不同於 Java 抽象方法，這些抽象方法可能具有一個實作。這個實作可在覆寫它的類別上透過 @ref{1a6,,super()} 機制來呼叫。這在使用協作多重繼承 (cooperative multiple-inheritance) 的框架中，可以被用作 super 呼叫的一個端點 (end-point)。
@end quotation
@end cartouche
@end deffn

@code{abc} 模組還支援下列舊式裝飾器：

@geindex abstractclassmethod() (於 abc 模組中)
@anchor{library/abc abc abstractclassmethod}@anchor{1287}
@deffn {函式} @@abc.abstractclassmethod


在 3.2 版被加入.



在 3.3 版之後被棄用: 現在可以讓 @ref{489,,classmethod} 配合 @ref{1286,,abstractmethod()} 使用，使得此裝飾器變得冗餘。


內建 @ref{489,,classmethod()} 的子類別，表示為一個抽象類別方法。在其他方面它都類似於 @ref{1286,,abstractmethod()}。

這個特例已被棄用，因為現在當 @ref{489,,classmethod()} 裝飾器應用於抽象方法時已會被正確地標識為是抽象的：

@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{1288}
@deffn {函式} @@abc.abstractstaticmethod


在 3.2 版被加入.



在 3.3 版之後被棄用: 現在可以讓 @ref{451,,staticmethod} 配合 @ref{1286,,abstractmethod()} 使用，使得此裝飾器變得冗餘。


內建 @ref{451,,staticmethod()} 的子類別，表示為一個抽象靜態方法。在其他方面它都類似於 @ref{1286,,abstractmethod()}。

這個特例已被棄用，因為現在當 @ref{451,,staticmethod()} 裝飾器應用於抽象方法時已會被正確地標識為是抽象的：

@example
class C(ABC):
    @@staticmethod
    @@abstractmethod
    def my_abstract_staticmethod(arg):
        ...
@end example
@end deffn

@geindex abstractproperty() (於 abc 模組中)
@anchor{library/abc abc abstractproperty}@anchor{1285}
@deffn {函式} @@abc.abstractproperty


在 3.3 版之後被棄用: 現在可以讓 @ref{4ae,,property}、@ref{1928,,property.getter()}、@ref{1929,,property.setter()} 和 @ref{192a,,property.deleter()} 配合 @ref{1286,,abstractmethod()} 使用，使得此裝飾器變得冗餘。


內建 @ref{4ae,,property()} 的子類別，表示為一個抽象特性。

這個特例已被棄用，因為現在當 @ref{4ae,,property()} 裝飾器應用於抽象方法時已會被正確地標識為是抽象的：

@example
class C(ABC):
    @@property
    @@abstractmethod
    def my_abstract_property(self):
        ...
@end example

上面的例子定義了一個唯讀特性；你也可以透過適當地將一個或多個底層方法標記為抽象的來定義可讀寫的抽象特性：

@example
class C(ABC):
    @@property
    def x(self):
        ...

    @@x.setter
    @@abstractmethod
    def x(self, val):
        ...
@end example

如果只有某些元件是抽象的，則只需更新那些元件即可在子類別中建立具體的特性：

@example
class D(C):
    @@C.x.setter
    def x(self, val):
        ...
@end example
@end deffn

@code{abc} 模組也提供了這些函式：

@geindex get_cache_token() (於 abc 模組中)
@anchor{library/abc abc get_cache_token}@anchor{1114}
@deffn {函式} abc.get_cache_token ()

回傳目前 ABC 快取令牌 (cache token)。

此令牌是一個（支援相等性測試的）不透明物件 (opaque object)，用於為虛擬子類別標識抽象基底類別快取的目前版本。此令牌會在任何 ABC 上每次呼叫 @ref{1289,,ABCMeta.register()} 時發生更改。


在 3.4 版被加入.

@end deffn

@geindex update_abstractmethods() (於 abc 模組中)
@anchor{library/abc abc update_abstractmethods}@anchor{4882}
@deffn {函式} abc.update_abstractmethods (cls)

重新計算一個抽象類別之抽象狀態的函式。如果一個類別的抽象方法在建立後被實作或被修改，則應當呼叫此函式。通常此函式應在一個類別裝飾器內部被呼叫。

回傳 `cls'，使其能夠用作為類別的裝飾器。

如果 `cls' 不是 @ref{1116,,ABCMeta} 的實例則不做任何操作。

@cartouche
@quotation 備註 
此函式會假定 `cls' 的超類別 (superclass) 已經被更新。它不會更新任何子類別。
@end quotation
@end cartouche


在 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 --- 退出處理函式,traceback --- 列印或取得堆疊回溯 stack traceback,abc --- 抽象基底類別,Python Runtime 服務
@anchor{library/atexit doc}@anchor{4883}@anchor{library/atexit atexit-exit-handlers}@anchor{4884}@anchor{library/atexit module-atexit}@anchor{d}@anchor{library/atexit translation-repo}@anchor{4885}
@subsection @code{atexit} --- 退出處理函式


@geindex module; atexit


__________________________________________________________________


@ref{d,,atexit} 模組定義了註冊和註銷清理函式 (cleanup function) 的函式，這樣的註冊函式會在直譯器正常終止時自動執行。@ref{d,,atexit} 按照這些函式註冊之`反序'來運行這些函式；如果你有註冊 @code{A}、@code{B} 和 @code{C}，則在直譯器終止時它們將按 @code{C}、@code{B}、@code{A} 的順序運行。

`注意：'當程式被一個不是來自 Python 的訊號終止、偵測到有 Python 嚴重內部錯誤時或者 @ref{25a4,,os._exit()} 被呼叫時，透過此模組註冊的函式就不會被呼叫。

`注意：'在清理函式中註冊或註銷函式的作用並未定義。


在 3.7 版的變更: 當與 C-API 子直譯器 (subinterpreter) 一起使用時，已註冊函式對於它們所註冊的直譯器來說是區域的 (local)。


@geindex register() (於 atexit 模組中)
@anchor{library/atexit atexit register}@anchor{a75}
@deffn {函式} atexit.register (func, *args, **kwargs)

將 `func' 註冊為要在終止時執行的函式。任何要傳遞給 `func' 的可選引數都必須作為引數傳遞給 @ref{a75,,register()}。可以多次註冊相同的函式和引數。

在程式正常終止時（例如呼叫 @ref{277,,sys.exit()} 或主要模組執行完成），所有已註冊函式都會依照後進先出的順序呼叫。這邊做的假設是較低階的模組通常會在較高階模組之前被引入，因此較低階模組必須在比較後面才被清理。

如果在執行退出處理函式期間引發例外，則會列印回溯 (traceback)（除非引發 @ref{f37,,SystemExit}）並儲存例外資訊。在所有退出處理函式都有嘗試運作過後，將重新引發最後一個引發的例外。

該函式回傳 `func'，這使得可以將其作為裝飾器使用。

@cartouche
@quotation 警告 
啟動新執行緒或從已註冊函式呼叫 @ref{4b0,,os.fork()} 可能會導致 Python 主要 runtime 執行緒釋放執行緒狀態，而內部 @ref{f3,,threading} 例程或新行程嘗試使用該狀態所形成的競態條件 (race condition)。這可能會導致崩潰 (crash) 而不是完整關閉中止。
@end quotation
@end cartouche


在 3.12 版的變更: 嘗試在已註冊函式中啟動新執行緒或 @ref{4b0,,os.fork()} 新行程現在會導致 @ref{244,,RuntimeError}。

@end deffn

@geindex unregister() (於 atexit 模組中)
@anchor{library/atexit atexit unregister}@anchor{4886}
@deffn {函式} atexit.unregister (func)

從在直譯器中止時會執行之函式串列中刪除 `func'。如果 `func' 先前未被註冊，則 @ref{4886,,unregister()} 不會執行任何操作。如果 `func' 已被註冊多次，則該函式在 @ref{d,,atexit} 呼叫堆疊 (call stack) 中的所有存在都會被刪除。會在註銷期間於內部使用相等性比較 (@code{==})，因此函式參照不需要具有匹配的識別性。
@end deffn


@subsubheading 也參考



@table @asis

@item @ref{bf,,readline} 模組

@ref{d,,atexit} 用於讀取和寫入 @ref{bf,,readline} 歷史檔案的一個不錯的範例。
@end table


@menu
* atexit 範例:: 

@end menu

@node atexit 範例,,,atexit --- 退出處理函式
@anchor{library/atexit atexit-example}@anchor{4887}@anchor{library/atexit id1}@anchor{4888}
@subsubsection @code{atexit} 範例


以下的簡單範例示範了模組如何在被引入時以檔案來初始化計數器，並在程式終止時自動儲存計數器的更新值，而不需要仰賴應用程式在終止時明確呼叫該模組。

@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

位置引數和關鍵字引數也可以被傳遞給 @ref{a75,,register()}，以便在呼叫時也傳遞給已註冊函式：

@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

作為@ref{932,,裝飾器}使用：

@example
import atexit

@@atexit.register
def goodbye():
    print('You are now leaving the Python sector.')
@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 traceback --- 列印或取得堆疊回溯 stack traceback,__future__ --- Future 陳述式定義,atexit --- 退出處理函式,Python Runtime 服務
@anchor{library/traceback doc}@anchor{4889}@anchor{library/traceback module-traceback}@anchor{104}@anchor{library/traceback traceback-print-or-retrieve-a-stack-traceback}@anchor{488a}@anchor{library/traceback translation-repo}@anchor{488b}
@subsection @code{traceback} --- 列印或取得堆疊回溯 (stack traceback)


@geindex module; traceback

`原始碼：'Lib/traceback.py@footnote{https://github.com/python/cpython/tree/3.14/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{ce3,,traceback objects} --- these are
objects of type @ref{ce1,,types.TracebackType},
which are assigned to the @ref{14c7,,__traceback__} field of
@ref{7d0,,BaseException} instances.


@subsubheading 也參考



@table @asis

@item @ref{5c,,faulthandler} 模組

Used to dump Python tracebacks explicitly, on a fault, after a timeout, or on a user signal.

@item @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{55d,,TracebackException} class and its helper classes
@ref{107e,,StackSummary} and @ref{107f,,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


在 3.13 版被加入: Output is colorized by default and can be
@ref{1b7,,controlled using environment variables}.


@menu
* Module-Level Functions:: 
* TracebackException 物件:: 
* StackSummary 物件:: 
* FrameSummary 物件:: 
* Examples of Using the Module-Level Functions:: 
* TracebackException 的使用範例:: 

@end menu

@node Module-Level Functions,TracebackException 物件,,traceback --- 列印或取得堆疊回溯 stack traceback
@anchor{library/traceback module-level-functions}@anchor{488c}
@subsubsection Module-Level Functions


@geindex print_tb() (於 traceback 模組中)
@anchor{library/traceback traceback print_tb}@anchor{1080}
@deffn {函式} traceback.print_tb (tb, limit=None, file=None)

Print up to `limit' stack trace entries from
@ref{ce3,,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{b2a,,sys.stderr}; otherwise it should be an open
@ref{13c4,,file} or @ref{28ad,,file-like object} to
receive the output.

@cartouche
@quotation 備註 
The meaning of the `limit' parameter is different than the meaning
of @ref{18ab,,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 版的變更: 新增負數 `limit' 的支援。

@end deffn

@geindex print_exception() (於 traceback 模組中)
@anchor{library/traceback traceback print_exception}@anchor{a48}
@deffn {函式} traceback.print_exception (exc, /[, value, tb], limit=None, file=None, chain=True)

Print exception information and stack trace entries from
@ref{ce3,,traceback object}
`tb' to `file'. This differs from @ref{1080,,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 ^ （插入符號）;marker（標記）


@itemize *

@item 
if `type(value)' is @ref{18e,,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{1080,,print_tb()}.
If `chain' is true (the default), then chained exceptions (the
@ref{14c9,,__cause__} or @ref{14c8,,__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{1b36}
@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{488d}
@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{6de,,sys.last_exc}).
@end deffn

@geindex print_stack() (於 traceback 模組中)
@anchor{library/traceback traceback print_stack}@anchor{1081}
@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{8e7,,stack frame}
to start.  The optional `file' argument has the same meaning as for
@ref{1080,,print_tb()}.


在 3.5 版的變更: 新增負數 `limit' 的支援。

@end deffn

@geindex extract_tb() (於 traceback 模組中)
@anchor{library/traceback traceback extract_tb}@anchor{488e}
@deffn {函式} traceback.extract_tb (tb, limit=None)

Return a @ref{107e,,StackSummary} object representing a list of "pre-processed"
stack trace entries extracted from the
@ref{ce3,,traceback object} `tb'.  It is useful
for alternate formatting of stack traces.  The optional `limit' argument has
the same meaning as for @ref{1080,,print_tb()}.  A "pre-processed" stack trace
entry is a @ref{107f,,FrameSummary} object containing attributes
@ref{488f,,filename}, @ref{4890,,lineno},
@ref{4891,,name}, and @ref{4892,,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{4893}
@deffn {函式} traceback.extract_stack (f=None, limit=None)

Extract the raw traceback from the current
@ref{8e7,,stack frame}.  The return value has
the same format as for @ref{488e,,extract_tb()}.  The optional `f' and `limit'
arguments have the same meaning as for @ref{1081,,print_stack()}.
@end deffn

@geindex print_list() (於 traceback 模組中)
@anchor{library/traceback traceback print_list}@anchor{185c}
@deffn {函式} traceback.print_list (extracted_list, file=None)

Print the list of tuples as returned by @ref{488e,,extract_tb()} or
@ref{4893,,extract_stack()} as a formatted stack trace to the given file.
If `file' is @code{None}, the output is written to @ref{b2a,,sys.stderr}.
@end deffn

@geindex format_list() (於 traceback 模組中)
@anchor{library/traceback traceback format_list}@anchor{4894}
@deffn {函式} traceback.format_list (extracted_list)

Given a list of tuples or @ref{107f,,FrameSummary} objects as returned by
@ref{488e,,extract_tb()} or @ref{4893,,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{a47}
@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{6e0,,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{18e,,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{258e,,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{560,,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{258e,,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{a46}
@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{a48,,print_exception()}.  The
return value is a list of strings, each ending in a newline and some
containing internal newlines.  When these lines are concatenated and printed,
exactly the same text is printed as does @ref{a48,,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{a48,,print_exception()}.

@end deffn

@geindex format_exc() (於 traceback 模組中)
@anchor{library/traceback traceback format_exc}@anchor{4895}
@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{475a}
@deffn {函式} traceback.format_tb (tb, limit=None)

@code{format_list(extract_tb(tb, limit))} 的簡寫。
@end deffn

@geindex format_stack() (於 traceback 模組中)
@anchor{library/traceback traceback format_stack}@anchor{4896}
@deffn {函式} traceback.format_stack (f=None, limit=None)

@code{format_list(extract_stack(f, limit))} 的簡寫。
@end deffn

@geindex clear_frames() (於 traceback 模組中)
@anchor{library/traceback traceback clear_frames}@anchor{11cf}
@deffn {函式} traceback.clear_frames (tb)

Clears the local variables of all the stack frames in a
@ref{ce3,,traceback} `tb'
by calling the @ref{57f,,clear()} method of each
@ref{8e7,,frame object}.


在 3.4 版被加入.

@end deffn

@geindex walk_stack() (於 traceback 模組中)
@anchor{library/traceback traceback walk_stack}@anchor{107c}
@deffn {函式} traceback.walk_stack (f)

Walk a stack following @ref{987,,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{4897,,StackSummary.extract()}.


在 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{107d}
@deffn {函式} traceback.walk_tb (tb)

Walk a traceback following @ref{ce2,,tb_next} yielding the frame and
line number
for each frame. This helper is used with @ref{4897,,StackSummary.extract()}.


在 3.5 版被加入.

@end deffn

@node TracebackException 物件,StackSummary 物件,Module-Level Functions,traceback --- 列印或取得堆疊回溯 stack traceback
@anchor{library/traceback tracebackexception-objects}@anchor{4898}
@subsubsection @code{TracebackException} 物件



在 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{ce3,,traceback} and @ref{8e7,,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{55d}
@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{107e,,StackSummary}
class.

If `compact' is true, only data that is required by
@code{TracebackException}'s @ref{199,,format()} method
is saved in the class attributes. In particular, the
@ref{4899,,__context__} field is calculated only if @ref{489a,,__cause__} is
@code{None} and @ref{489b,,__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{560,,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 版的變更: 新增 `compact' 參數。



在 3.11 版的變更: 新增 `max_group_width' 和 `max_group_depth' 參數。


@geindex __cause__ (traceback.TracebackException 的屬性)
@anchor{library/traceback traceback TracebackException __cause__}@anchor{489a}
@deffn {屬性} __cause__

A @code{TracebackException} of the original
@ref{14c9,,__cause__}.
@end deffn

@geindex __context__ (traceback.TracebackException 的屬性)
@anchor{library/traceback traceback TracebackException __context__}@anchor{4899}
@deffn {屬性} __context__

A @code{TracebackException} of the original
@ref{14c8,,__context__}.
@end deffn

@geindex exceptions (traceback.TracebackException 的屬性)
@anchor{library/traceback traceback TracebackException exceptions}@anchor{489c}
@deffn {屬性} exceptions

If @code{self} represents an @ref{4cd,,ExceptionGroup}, this field holds a list of
@code{TracebackException} instances representing the nested exceptions.
Otherwise it is @code{None}.


在 3.11 版被加入.

@end deffn

@geindex __suppress_context__ (traceback.TracebackException 的屬性)
@anchor{library/traceback traceback TracebackException __suppress_context__}@anchor{489b}
@deffn {屬性} __suppress_context__

The @ref{23bc,,__suppress_context__} value from the original
exception.
@end deffn

@geindex __notes__ (traceback.TracebackException 的屬性)
@anchor{library/traceback traceback TracebackException __notes__}@anchor{489d}
@deffn {屬性} __notes__

The @ref{258e,,__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.


在 3.11 版被加入.

@end deffn

@geindex stack (traceback.TracebackException 的屬性)
@anchor{library/traceback traceback TracebackException stack}@anchor{489e}
@deffn {屬性} stack

A @ref{107e,,StackSummary} representing the traceback.
@end deffn

@geindex exc_type (traceback.TracebackException 的屬性)
@anchor{library/traceback traceback TracebackException exc_type}@anchor{55e}
@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{55c}
@deffn {屬性} exc_type_str

String display of the class of the original exception.


在 3.13 版被加入.

@end deffn

@geindex filename (traceback.TracebackException 的屬性)
@anchor{library/traceback traceback TracebackException filename}@anchor{489f}
@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{48a0}
@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{48a1}
@deffn {屬性} end_lineno

For syntax errors - the end line number where the error occurred.
Can be @code{None} if not present.


在 3.10 版被加入.

@end deffn

@geindex text (traceback.TracebackException 的屬性)
@anchor{library/traceback traceback TracebackException text}@anchor{48a2}
@deffn {屬性} text

For syntax errors - the text where the error occurred.
@end deffn

@geindex offset (traceback.TracebackException 的屬性)
@anchor{library/traceback traceback TracebackException offset}@anchor{48a3}
@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{48a4}
@deffn {屬性} end_offset

For syntax errors - the end offset into the text where the error occurred.
Can be @code{None} if not present.


在 3.10 版被加入.

@end deffn

@geindex msg (traceback.TracebackException 的屬性)
@anchor{library/traceback traceback TracebackException msg}@anchor{48a5}
@deffn {屬性} msg

For syntax errors - the compiler error message.
@end deffn

@geindex from_exception() (traceback.TracebackException 的類別方法)
@anchor{library/traceback traceback TracebackException from_exception}@anchor{48a6}
@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{107e,,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{8ab}
@deffn {方法} print (*, file=None, chain=True)

Print to `file' (default @code{sys.stderr}) the exception information returned by
@ref{199,,format()}.


在 3.11 版被加入.

@end deffn

@geindex format() (traceback.TracebackException 的方法)
@anchor{library/traceback traceback TracebackException format}@anchor{48a7}
@deffn {方法} format (*, chain=True)

Format the exception.

If `chain' is not @code{True}, @ref{489a,,__cause__} and @ref{4899,,__context__}
will not be formatted.

The return value is a generator of strings, each ending in a newline and
some containing internal newlines. @ref{a48,,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{55f}
@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{18e,,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{560,,BaseExceptionGroup}, the nested exceptions are included as
well, recursively, with indentation relative to their nesting depth.


在 3.11 版的變更: The exception's @ref{258e,,notes} are now
included in the output.



在 3.13 版的變更: 新增 `show_group' 參數。

@end deffn
@end deffn

@node StackSummary 物件,FrameSummary 物件,TracebackException 物件,traceback --- 列印或取得堆疊回溯 stack traceback
@anchor{library/traceback stacksummary-objects}@anchor{48a8}
@subsubsection @code{StackSummary} 物件



在 3.5 版被加入.


@code{StackSummary} objects represent a call stack ready for formatting.

@geindex StackSummary (traceback 中的類別)
@anchor{library/traceback traceback StackSummary}@anchor{107e}
@deffn {類別} traceback.StackSummary

@geindex extract() (traceback.StackSummary 的類別方法)
@anchor{library/traceback traceback StackSummary extract}@anchor{4897}
@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{107c,,walk_stack()} or
@ref{107d,,walk_tb()}).

If `limit' is supplied, only this many frames are taken from `frame_gen'.
If `lookup_lines' is @code{False}, the returned @ref{107f,,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{1c1,,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{48a9}
@deffn {方法} classmethod from_list (a_list)

Construct a @code{StackSummary} object from a supplied list of
@ref{107f,,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{48aa}
@deffn {方法} format ()

Returns a list of strings ready for printing.  Each string in the
resulting list corresponds to a single @ref{8e7,,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{8aa}
@deffn {方法} format_frame_summary (frame_summary)

Returns a string for printing one of the @ref{8e7,,frames}
involved in the stack.
This method is called for each @ref{107f,,FrameSummary} object to be
printed by @ref{48aa,,StackSummary.format()}. If it returns @code{None}, the
frame is omitted from the output.


在 3.11 版被加入.

@end deffn
@end deffn

@node FrameSummary 物件,Examples of Using the Module-Level Functions,StackSummary 物件,traceback --- 列印或取得堆疊回溯 stack traceback
@anchor{library/traceback framesummary-objects}@anchor{48ab}
@subsubsection @code{FrameSummary} 物件



在 3.5 版被加入.


A @code{FrameSummary} object represents a single @ref{8e7,,frame}
in a @ref{ce3,,traceback}.

@geindex FrameSummary (traceback 中的類別)
@anchor{library/traceback traceback FrameSummary}@anchor{107f}
@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{8e7,,frame} in the
@ref{ce3,,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{4892,,line}
attribute accessed (which also happens when casting it to a @ref{60c,,tuple}).
@ref{4892,,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{488f}
@deffn {屬性} filename

The filename of the source code for this frame. Equivalent to accessing
@ref{1565,,f.f_code.co_filename} on a
@ref{8e7,,frame object} `f'.
@end deffn

@geindex lineno (traceback.FrameSummary 的屬性)
@anchor{library/traceback traceback FrameSummary lineno}@anchor{4890}
@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{4891}
@deffn {屬性} name

Equivalent to accessing @ref{2236,,f.f_code.co_name} on
a @ref{8e7,,frame object} `f'.
@end deffn

@geindex line (traceback.FrameSummary 的屬性)
@anchor{library/traceback traceback FrameSummary line}@anchor{4892}
@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{48ac}
@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{48ad}
@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{48ae}
@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,TracebackException 的使用範例,FrameSummary 物件,traceback --- 列印或取得堆疊回溯 stack traceback
@anchor{library/traceback examples-of-using-the-module-level-functions}@anchor{48af}@anchor{library/traceback traceback-example}@anchor{48b0}
@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 TracebackException 的使用範例,,Examples of Using the Module-Level Functions,traceback --- 列印或取得堆疊回溯 stack traceback
@anchor{library/traceback examples-of-using-tracebackexception}@anchor{48b1}
@subsubsection @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 陳述式定義,gc --- 垃圾回收器介面 Garbage Collector interface,traceback --- 列印或取得堆疊回溯 stack traceback,Python Runtime 服務
@anchor{library/__future__ doc}@anchor{48b2}@anchor{library/__future__ future-future-statement-definitions}@anchor{48b3}@anchor{library/__future__ module-__future__}@anchor{0}@anchor{library/__future__ translation-repo}@anchor{48b4}
@subsection @code{__future__} --- Future 陳述式定義


@geindex module; __future__

`原始碼：'Lib/__future__.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/__future__.py}


__________________________________________________________________


@code{from __future__ import feature} 形式的引入被稱為 @ref{45b,,future 陳述式}。這些是 Python 編譯器的特殊情況，允許在該功能成為標準版本之前在包含 future 陳述式的模組中使用新的 Python 功能。

雖然這些 future 陳述式被 Python 編譯器賦予了額外的特殊意義，但它們仍然像任何其他 import 陳述式一樣執行，且 @ref{0,,__future__} 由引入系統以和任何其他 Python 模組相同的方式處理。這個設計有三個目的：


@itemize *

@item 
為了避免混淆分析引入陳述式並預期要找到它們正在引入之模組的現有工具。

@item 
記錄何時出現不相容的變更，以及何時開始強制執行這些變更。這是一種可執行文件的形式，可以透過引入 @ref{0,,__future__} 並檢查其內容以程式化的方式進行檢查。

@item 
確保 @ref{45b,,future 陳述式}在 Python 2.1 之前的版本中運行至少會產生 runtime 例外（@ref{0,,__future__} 的引入將會失敗，因為 2.1 之前沒有該名稱的模組）。
@end itemize

@menu
* 模組內容: 模組內容<9>. 

@end menu

@node 模組內容<9>,,,__future__ --- Future 陳述式定義
@anchor{library/__future__ module-contents}@anchor{48b5}
@subsubsection 模組內容


不會從 @ref{0,,__future__} 中刪除任何功能描述。自從在 Python 2.1 中引入以來，以下功能已透過這種機制引入到該語言中：


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

功能

@tab

可選的版本

@tab

強制性的版本

@tab

影響

@item

@geindex nested_scopes (於 __future__ 模組中)
@anchor{library/__future__ future__ nested_scopes}@anchor{48b6}
@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{48b7}
@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{48b8}
@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{48b9}
@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{48ba}
@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/}: `"with" 陳述式 (The "with" Statement)'

@item

@geindex print_function (於 __future__ 模組中)
@anchor{library/__future__ future__ print_function}@anchor{48bb}
@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/}: `使 print 成為一個函式 (Make print a function)'

@item

@geindex unicode_literals (於 __future__ 模組中)
@anchor{library/__future__ future__ unicode_literals}@anchor{48bc}
@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/}: `Python 3000 中的位元組字面值 (Bytes literals in Python 3000)'

@item

@geindex generator_stop (於 __future__ 模組中)
@anchor{library/__future__ future__ generator_stop}@anchor{48bd}
@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 處理 (StopIteration handling inside generators)'

@item

@geindex annotations (於 __future__ 模組中)
@anchor{library/__future__ future__ annotations}@anchor{48be}
@deffn {資料} __future__.annotations
@end deffn

@tab

3.7.0b1

@tab

從未 @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{48bf}@anchor{library/__future__ future__ _Feature}@anchor{2471}
@deffn {類別} __future__._Feature

@code{__future__.py} 中的每個陳述式的形式如下：

@example
FeatureName = _Feature(OptionalRelease, MandatoryRelease,
                       CompilerFlag)
@end example

通常，`OptionalRelease' 會小於 `MandatoryRelease'，且兩者都是與 @ref{8a7,,sys.version_info} 形式相同的 5 元組 (5-tuple)：

@example
(PY_MAJOR_VERSION, # 2.1.0a3 裡面的 2；為一整數
 PY_MINOR_VERSION, # 1；為一整數
 PY_MICRO_VERSION, # 0；為一整數
 PY_RELEASE_LEVEL, # "alpha"、"beta"、"candidate" 或 "final"; ；為一字串
 PY_RELEASE_SERIAL # 3；為一整數
)
@end example
@end deffn

@geindex getOptionalRelease() (__future__._Feature 的方法)
@anchor{library/__future__ future__ _Feature getOptionalRelease}@anchor{48c0}
@deffn {方法} _Feature.getOptionalRelease ()

`OptionalRelease' 記錄該功能首次發布時的 Python 版本。
@end deffn

@geindex getMandatoryRelease() (__future__._Feature 的方法)
@anchor{library/__future__ future__ _Feature getMandatoryRelease}@anchor{48c1}
@deffn {方法} _Feature.getMandatoryRelease ()

如果 `MandatoryRelease' 尚未發布，`MandatoryRelease' 會預測該功能將成為該語言一部分的版本。

否則 `MandatoryRelease' 會記錄該功能是何時成為語言的一部分；在該版本或之後的版本中，模組不再需要 future 聲明來使用相關功能，但可以繼續使用此種引入方式。

`MandatoryRelease' 也可能是 @code{None}，這意味著計劃中的功能被丟棄或者仍未決定。
@end deffn

@geindex compiler_flag (__future__._Feature 的屬性)
@anchor{library/__future__ future__ _Feature compiler_flag}@anchor{2244}
@deffn {屬性} _Feature.compiler_flag

`CompilerFlag' 是（位元欄位 (bitfield)）旗標，應在第四個引數中傳遞給內建函式 @ref{4ac,,compile()} 以在動態編譯的程式碼中啟用該功能。此旗標儲存在 @ref{2471,,_Feature} 實例上的 @ref{2244,,_Feature.compiler_flag} 屬性中。
@end deffn


@subsubheading 也參考



@table @asis

@item @ref{45b,,Future statements}

編譯器如何處理 future 引入。

@geindex Python Enhancement Proposals; PEP 236

@item PEP 236@footnote{https://peps.python.org/pep-0236/} - 回到 __future__

__future__ 機制的原始提案。
@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 --- 檢視活動物件,__future__ --- Future 陳述式定義,Python Runtime 服務
@anchor{library/gc doc}@anchor{48c2}@anchor{library/gc gc-garbage-collector-interface}@anchor{48c3}@anchor{library/gc module-gc}@anchor{64}@anchor{library/gc translation-repo}@anchor{48c4}
@subsection @code{gc} --- 垃圾回收器介面 (Garbage Collector interface)


@geindex module; gc


__________________________________________________________________


此 module（模組）提供可選的垃圾回收器介面，提供的功能包括：關閉回收器、調整回收頻率、設定除錯選項。它同時提供對回收器有找到但是無法釋放的不可達物件 (unreachable object) 的存取。由於 Python 使用了帶有參照計數的回收器，如果你確定你的程式不會產生參照迴圈 (reference cycle)，你可以關閉回收器。可以透過呼叫 @code{gc.disable()} 關閉自動垃圾回收。若要為一個存在記憶體流失的程式 (leaking program) 除錯，請呼叫 @code{gc.set_debug(gc.DEBUG_LEAK)}；需要注意的是，它包含 @code{gc.DEBUG_SAVEALL}，使得被回收的物件會被存放在 gc.garbage 中以待檢查。

@ref{64,,gc} module 提供下列函式：

@geindex enable() (於 gc 模組中)
@anchor{library/gc gc enable}@anchor{48c5}
@deffn {函式} gc.enable ()

啟用自動垃圾回收。
@end deffn

@geindex disable() (於 gc 模組中)
@anchor{library/gc gc disable}@anchor{48c6}
@deffn {函式} gc.disable ()

停用自動垃圾回收。
@end deffn

@geindex isenabled() (於 gc 模組中)
@anchor{library/gc gc isenabled}@anchor{48c7}
@deffn {函式} gc.isenabled ()

如果啟用了自動回收則回傳 @code{True}。
@end deffn

@geindex collect() (於 gc 模組中)
@anchor{library/gc gc collect}@anchor{1b3}
@deffn {函式} gc.collect (generation=2)

啟動垃圾回收。可選的引數 `generation' 可以是一個指明需要回收哪一代垃圾的整數（從 0 到 2）。當 generation 數值無效時，會引發 @ref{2eb,,ValueError} 例外。可回收物件與不可回收物件的總和會被回傳。

呼叫 @code{gc.collect(0)} 將對年輕代執行 GC 回收。

呼叫 @code{gc.collect(1)} 將對年輕代執行 GC 回收並對年老代執行增量回收。

呼叫 @code{gc.collect(2)} 或 @code{gc.collect()} 執行完整回收

每當執行完整回收或最高代 (2) 回收時，為多個內建型別所維護的空閒列表會被清空。為了特定型別的實現，特別是 @ref{196,,float}，在某些空閒列表中並非所有項目都會被釋放。

當直譯器已經執行收集時呼叫 @code{gc.collect()} 的效果是未定義的。


在 3.14 版的變更: @code{generation=1} 會執行增量收集。

@end deffn

@geindex set_debug() (於 gc 模組中)
@anchor{library/gc gc set_debug}@anchor{48c8}
@deffn {函式} gc.set_debug (flags)

設定垃圾回收器的除錯旗標。除錯資訊會被寫入 @code{sys.stderr}。請見下方的除錯旗標列表，可以使用位元操作 (bit operation) 進行設定以控制除錯程式。
@end deffn

@geindex get_debug() (於 gc 模組中)
@anchor{library/gc gc get_debug}@anchor{48c9}
@deffn {函式} gc.get_debug ()

回傳目前設置的除錯旗標。
@end deffn

@geindex get_objects() (於 gc 模組中)
@anchor{library/gc gc get_objects}@anchor{9fd}
@deffn {函式} gc.get_objects (generation=None)

回傳一個包含回收器正在追蹤的所有物件的 list，除去所回傳的 list。如果 `generation' 不為 @code{None}，只回傳以下物件。


@itemize *

@item 
0: 年輕代中的所有物件。

@item 
1: 沒有物件，因為不存在第一代（截至 Python 3.14）

@item 
2: 年老代中的所有物件。
@end itemize


在 3.8 版的變更: 新增 `generation' 參數。



在 3.14 版的變更: 第一代已被刪除


引發一個附帶引數 @code{generation} 的@ref{1b70,,稽核事件 (auditing event)} @code{gc.get_objects}。
@end deffn

@geindex get_stats() (於 gc 模組中)
@anchor{library/gc gc get_stats}@anchor{2dc}
@deffn {函式} gc.get_stats ()

回傳一個包含三個字典物件的 list，每個字典分別包含對應代中自從直譯器開始執行後的垃圾回收統計資料。字典的鍵的數目在將來可能會改變，但目前每個字典包含以下項目：


@itemize *

@item 
@code{collections} 是該代被回收的次數；

@item 
@code{collected} 是該代中被回收的物件總數；

@item 
@code{uncollectable} 是在這一代中被發現無法回收的物件總數（因此被移到 @ref{13c2,,garbage} list 中）。
@end itemize


在 3.4 版被加入.

@end deffn

@geindex set_threshold() (於 gc 模組中)
@anchor{library/gc gc set_threshold}@anchor{2da}
@deffn {函式} gc.set_threshold (threshold0[, threshold1[, threshold2]])

設定垃圾回收閾值（回收頻率）。 將 `threshold0' 設為零會停止回收。

GC 根據物件是否在回收中倖存下來而將其分為兩代。新的物件會被放置在年輕代中。如果一個物件在回收中倖存下來，它將被移動到年老代中。

為了決定何時運行，回收器會追蹤自上次回收以來物件分配和釋放的數量。當分配數量減去釋放數量超過 `threshold0' 時，回收就會開始。每次回收都會去回收年輕代中的所有物件和年老代的部分物件。

在自由執行緒建置 (free-threaded build) 中，在運行回收器之前還會檢查行程記憶體使用量的增加。如果自上次回收以來記憶體使用量未增加 10%，且物件分配的淨數量未超過 `threshold0' 的 40 倍，則不會運行回收。

年老代中被回收的物件比例與 `threshold1' 成`反比'。`threshold1' 越大，年老代中物件的回收就越慢。以預設值 10 來說，每次回收時會掃描年老代中的 1%。

`threshold2' 會被忽略。

有關更多資訊，請參閱垃圾回收器設計@footnote{https://github.com/python/cpython/blob/3.14/InternalDocs/garbage_collector.md}。


在 3.14 版的變更: `threshold2' 會被忽略

@end deffn

@geindex get_count() (於 gc 模組中)
@anchor{library/gc gc get_count}@anchor{2db}
@deffn {函式} gc.get_count ()

將目前回收計數以 @code{(count0, count1, count2)} 形式的 tuple 回傳。
@end deffn

@geindex get_threshold() (於 gc 模組中)
@anchor{library/gc gc get_threshold}@anchor{2d9}
@deffn {函式} gc.get_threshold ()

將目前回收閾值以 @code{(threshold0, threshold1, threshold2)} 形式的 tuple 回傳。
@end deffn

@geindex get_referrers() (於 gc 模組中)
@anchor{library/gc gc get_referrers}@anchor{9fe}
@deffn {函式} gc.get_referrers (*objs)

回傳包含直接參照 objs 中任一個物件的物件 list。這個函式只定位支援垃圾回收的容器；參照了其它物件但不支援垃圾回收的擴充套件型別無法被找到。

需要注意的是，已經解除參照的物件，但仍存在於參照迴圈中未被回收時，該物件仍然會被作為參照者出現在回傳的 list 中。若只要取得目前正在參照的物件，需要在呼叫 @ref{9fe,,get_referrers()} 之前呼叫 @ref{1b3,,collect()}。

@cartouche
@quotation 警告 
在使用 @ref{9fe,,get_referrers()} 回傳的物件時必須要小心，因為其中的一些物件可能仍在建構中而處於暫時無效的狀態。不要把 @ref{9fe,,get_referrers()} 用於除錯以外的其它目的。
@end quotation
@end cartouche

引發一個附帶引數 @code{objs} 的@ref{1b70,,稽核事件} @code{gc.get_referrers}。
@end deffn

@geindex get_referents() (於 gc 模組中)
@anchor{library/gc gc get_referents}@anchor{9ff}
@deffn {函式} gc.get_referents (*objs)

回傳包含被任意一個引數直接參照之物件的 list。回傳的被參照物件是有被引數的 C 語言級別 @ref{979,,tp_traverse} 方法（若存在）瀏覽到的物件，可能不是所有的實際直接可達物件。只有支援垃圾回收的物件支援 @ref{979,,tp_traverse} 方法，並且此方法只會瀏覽涉及參照迴圈的物件。因此，可以有以下例子：一個整數對於一個引數是直接可達的，這個整數物件有可能出現或不出現在結果的 list 當中。

引發一個附帶引數 @code{objs} 的@ref{1b70,,稽核事件} @code{gc.get_referents}。
@end deffn

@geindex is_tracked() (於 gc 模組中)
@anchor{library/gc gc is_tracked}@anchor{150e}
@deffn {函式} gc.is_tracked (obj)

當物件正在被垃圾回收器追蹤時回傳 @code{True}，否則回傳 @code{False}。一般來說，原子型別 (atomic type) 的實例不會被追蹤，而非原子型別（如容器、使用者自己定義的物件）會被追蹤。然而，有一些特定型別最佳化會被用來減少垃圾回收器在簡單實例（如只含有原子性的鍵和值的字典）上的足跡：

@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


在 3.1 版被加入.

@end deffn

@geindex is_finalized() (於 gc 模組中)
@anchor{library/gc gc is_finalized}@anchor{af0}
@deffn {函式} gc.is_finalized (obj)

如果給定物件已被垃圾回收器終結則回傳 @code{True}，否則回傳 @code{False}。：

@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


在 3.9 版被加入.

@end deffn

@geindex freeze() (於 gc 模組中)
@anchor{library/gc gc freeze}@anchor{d26}
@deffn {函式} gc.freeze ()

凍結 (freeze) 垃圾回收器所追蹤的所有物件；將它們移至永久代並忽略所有未來的收集動作。

如果一個行程將在沒有 @code{exec()} 的情況下進行 @code{fork()}，避免子行程中不必要的寫入時複製將最大化記憶體共享並減少整體記憶體使用。這需要避免在父行程的記憶體頁面中建立已釋放的「漏洞」，並確保子行程中的 GC 收集不會觸及源自父行程的長壽命物件的 @code{gc_refs} 計數器。要實現這兩個目標，請在父行程的早期呼叫 @code{gc.disable()}，在 @code{fork()} 之前呼叫 @code{gc.freeze()}，並儘早在子行程中呼叫 @code{gc.enable()}。


在 3.7 版被加入.

@end deffn

@geindex unfreeze() (於 gc 模組中)
@anchor{library/gc gc unfreeze}@anchor{d27}
@deffn {函式} gc.unfreeze ()

解凍 (unfreeze) 永久代中的物件，並將它們放回到最年老代中。


在 3.7 版被加入.

@end deffn

@geindex get_freeze_count() (於 gc 模組中)
@anchor{library/gc gc get_freeze_count}@anchor{d28}
@deffn {函式} gc.get_freeze_count ()

回傳永久代中的物件數量。


在 3.7 版被加入.

@end deffn

以下變數僅供唯讀存取（你可以修改其值但不應該重新繫結 (rebind) 它們）：

@geindex garbage (於 gc 模組中)
@anchor{library/gc gc garbage}@anchor{13c2}
@deffn {資料} gc.garbage

一個回收器發現不可達而又無法被釋放的物件（不可回收物件）list。從 Python 3.4 開始，該 list 在大多數時候都應該是空的，除非使用了有非 @code{NULL} @code{tp_del} 槽位的 C 擴充套件型別的實例。

如果設定了 @ref{48ca,,DEBUG_SAVEALL}，則所有不可達物件將被加進該 list 而不會被釋放。


在 3.2 版的變更: 當 @ref{474,,interpreter shutdown} 即直譯器關閉時，若此 list 非空，會產生 @ref{547,,ResourceWarning}，在預設情況下此警告不會被提醒。如果設定了 @ref{13c3,,DEBUG_UNCOLLECTABLE}，所有無法被回收的物件會被印出。



在 3.4 版的變更: 根據 
@geindex Python Enhancement Proposals; PEP 442
PEP 442@footnote{https://peps.python.org/pep-0442/}，帶有 @ref{11f8,,__del__()} method 的物件最終不會在 @ref{13c2,,gc.garbage} 內。

@end deffn

@geindex callbacks (於 gc 模組中)
@anchor{library/gc gc callbacks}@anchor{12c8}
@deffn {資料} gc.callbacks

會被垃圾回收器在回收開始前和完成後叫用的一系列回呼函式 (callback) 。這些回呼函式在被呼叫時附帶兩個引數：`phase' 和 `info'。

`phase' 可為以下兩者之一：

@quotation

"start"：垃圾回收即將開始。

"stop"：垃圾回收已結束。
@end quotation

`info' 是一個字典，提供回呼函式更多資訊。已有定義的鍵有：

@quotation

"generation"（代）：正在被回收的最年老的一代。

"collected"（已回收的）：當 `phase' 為 "stop" 時，被成功回收的物件的數目。

"uncollectable"（不可回收的）：當 `phase' 為 "stop" 時，不能被回收並被放入 @ref{13c2,,garbage} 的物件的數目。
@end quotation

應用程式可以把他們自己的回呼函式加入此 list。主要的使用場景有：

@quotation

收集垃圾回收的統計資料，如：不同代的回收頻率、回收任務所花費的時間。

讓應用程式可以識別和清理他們自己在 @ref{13c2,,garbage} 中的不可回收型別物件。
@end quotation


在 3.3 版被加入.

@end deffn

以下常數是為了和 @ref{48c8,,set_debug()} 一起使用所提供：

@geindex DEBUG_STATS (於 gc 模組中)
@anchor{library/gc gc DEBUG_STATS}@anchor{48cb}
@deffn {資料} gc.DEBUG_STATS

在回收完成後印出統計資訊。當調校回收頻率設定時，這些資訊會很有用。
@end deffn

@geindex DEBUG_COLLECTABLE (於 gc 模組中)
@anchor{library/gc gc DEBUG_COLLECTABLE}@anchor{48cc}
@deffn {資料} gc.DEBUG_COLLECTABLE

當發現可回收物件時印出資訊。
@end deffn

@geindex DEBUG_UNCOLLECTABLE (於 gc 模組中)
@anchor{library/gc gc DEBUG_UNCOLLECTABLE}@anchor{13c3}
@deffn {資料} gc.DEBUG_UNCOLLECTABLE

印出找到的不可回收物件的資訊（指不能被回收器回收的不可達物件）。這些物件會被新增到 @code{garbage} list 中。


在 3.2 版的變更: 當 @ref{474,,interpreter shutdown}（直譯器關閉）時，若 @ref{13c2,,garbage} list 不是空的，那這些內容也會被印出。

@end deffn

@geindex DEBUG_SAVEALL (於 gc 模組中)
@anchor{library/gc gc DEBUG_SAVEALL}@anchor{48ca}
@deffn {資料} gc.DEBUG_SAVEALL

設定後，所有回收器找到的不可達物件會被加進 `garbage' 而不是直接被釋放。這在為一個記憶體流失的程式除錯時會很有用。
@end deffn

@geindex DEBUG_LEAK (於 gc 模組中)
@anchor{library/gc gc DEBUG_LEAK}@anchor{48cd}
@deffn {資料} gc.DEBUG_LEAK

要印出記憶體流失程式之相關資訊時，回收器所需的除錯旗標。（等同於 @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 --- 檢視活動物件,annotationlib --- 用於自我檢查註釋的功能,gc --- 垃圾回收器介面 Garbage Collector interface,Python Runtime 服務
@anchor{library/inspect doc}@anchor{48ce}@anchor{library/inspect inspect-inspect-live-objects}@anchor{48cf}@anchor{library/inspect translation-repo}@anchor{48d0}
@subsection @code{inspect} --- 檢視活動物件


@c import inspect
@c from inspect import *

@geindex module; inspect
@anchor{library/inspect module-inspect}@anchor{82}
`原始碼：'Lib/inspect.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/inspect.py}


__________________________________________________________________


The @ref{82,,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:: 
* 取得原始碼:: 
* Introspecting callables with the Signature object:: 
* 類別與函式: 類別與函式<2>. 
* 直譯器堆疊:: 
* 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:: 
* 命令列介面: 命令列介面<12>. 

@end menu

@node Types and members,取得原始碼,,inspect --- 檢視活動物件
@anchor{library/inspect inspect-types}@anchor{1c5b}@anchor{library/inspect types-and-members}@anchor{48d1}
@subsubsection Types and members


The @ref{1b0c,,getmembers()} function retrieves the members of an object such as a
class or module. The functions whose names begin with "is" are mainly
provided as convenient choices for the second argument to @ref{1b0c,,getmembers()}.
They also help you determine when you can expect to find the following special
attributes (see @ref{2213,,Import-related attributes on module objects} for module attributes):

@c this function name is too big to fit in the ascii-art table below


@multitable {xxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Type

@tab

屬性

@tab

描述

@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{5a7,,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

函式

@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{4a5,,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{5a7,,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{2243,,here}

@item

@tab

co_lnotab

@tab

encoded mapping of line
numbers to bytecode
indices

@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

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_code

@tab

code（程式碼）

@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_code

@tab

code（程式碼）

@item

@tab

cr_origin

@tab

where coroutine was
created, or @code{None}. See
@ref{d7f,,sys.set_coroutine_origin_tracking_depth()}

@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 版的變更: 將 @code{__qualname__} 和 @code{gi_yieldfrom} 屬性加到產生器。

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 版的變更: 新增協程的 @code{cr_origin} 屬性。



在 3.10 版的變更: 新增函式的 @code{__builtins__} 屬性。



在 3.14 版的變更: 新增 @code{f_generator} 屬性到 frame。


@geindex getmembers() (於 inspect 模組中)
@anchor{library/inspect inspect getmembers}@anchor{1b0c}
@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 備註 
@ref{1b0c,,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{176b,,__dir__()}.
@end quotation
@end cartouche
@end deffn

@geindex getmembers_static() (於 inspect 模組中)
@anchor{library/inspect inspect getmembers_static}@anchor{852}
@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 備註 
@ref{852,,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


在 3.11 版被加入.

@end deffn

@geindex getmodulename() (於 inspect 模組中)
@anchor{library/inspect inspect getmodulename}@anchor{f2f}
@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{48d2,,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 版的變更: 此函式直接基於 @ref{7b,,importlib}。

@end deffn

@geindex ismodule() (於 inspect 模組中)
@anchor{library/inspect inspect ismodule}@anchor{48d3}
@deffn {函式} inspect.ismodule (object)

如果物件是模組，則回傳 @code{True}。
@end deffn

@geindex isclass() (於 inspect 模組中)
@anchor{library/inspect inspect isclass}@anchor{48d4}
@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{48d5}
@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{232}
@deffn {函式} inspect.ispackage (object)

如果物件是 @ref{233,,package}，則回傳 @code{True}。


在 3.14 版被加入.

@end deffn

@geindex isfunction() (於 inspect 模組中)
@anchor{library/inspect inspect isfunction}@anchor{48d6}
@deffn {函式} inspect.isfunction (object)

Return @code{True} if the object is a Python function, which includes functions
created by a @ref{2a65,,lambda} expression.
@end deffn

@geindex isgeneratorfunction() (於 inspect 模組中)
@anchor{library/inspect inspect isgeneratorfunction}@anchor{1a8a}
@deffn {函式} inspect.isgeneratorfunction (object)

如果物件是 Python 產生器函式，則回傳 @code{True}。


在 3.8 版的變更: Functions wrapped in @ref{217,,functools.partial()} now return @code{True} if the
wrapped function is a Python generator function.



在 3.13 版的變更: Functions wrapped in @ref{218,,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{48d7}
@deffn {函式} inspect.isgenerator (object)

如果物件是產生器，則回傳 @code{True}。
@end deffn

@geindex iscoroutinefunction() (於 inspect 模組中)
@anchor{library/inspect inspect iscoroutinefunction}@anchor{30c}
@deffn {函式} inspect.iscoroutinefunction (object)

Return @code{True} if the object is a @ref{f6e,,coroutine function} (a function
defined with an @ref{7e6,,async def} syntax), a @ref{217,,functools.partial()}
wrapping a @ref{f6e,,coroutine function}, or a sync function marked with
@ref{6b1,,markcoroutinefunction()}.


在 3.5 版被加入.



在 3.8 版的變更: Functions wrapped in @ref{217,,functools.partial()} now return @code{True} if the
wrapped function is a @ref{f6e,,coroutine function}.



在 3.12 版的變更: Sync functions marked with @ref{6b1,,markcoroutinefunction()} now return
@code{True}.



在 3.13 版的變更: Functions wrapped in @ref{218,,functools.partialmethod()} now return @code{True}
if the wrapped function is a @ref{f6e,,coroutine function}.

@end deffn

@geindex markcoroutinefunction() (於 inspect 模組中)
@anchor{library/inspect inspect markcoroutinefunction}@anchor{6b1}
@deffn {函式} inspect.markcoroutinefunction (func)

Decorator to mark a callable as a @ref{f6e,,coroutine function} if it would not
otherwise be detected by @ref{30c,,iscoroutinefunction()}.

This may be of use for sync functions that return a @ref{6b2,,coroutine}, if
the function is passed to an API that requires @ref{30c,,iscoroutinefunction()}.

When possible, using an @ref{7e6,,async def} function is preferred. Also
acceptable is calling the function and testing the return with
@ref{1012,,iscoroutine()}.


在 3.12 版被加入.

@end deffn

@geindex iscoroutine() (於 inspect 模組中)
@anchor{library/inspect inspect iscoroutine}@anchor{1012}
@deffn {函式} inspect.iscoroutine (object)

Return @code{True} if the object is a @ref{6b2,,coroutine} created by an
@ref{7e6,,async def} function.


在 3.5 版被加入.

@end deffn

@geindex isawaitable() (於 inspect 模組中)
@anchor{library/inspect inspect isawaitable}@anchor{1013}
@deffn {函式} inspect.isawaitable (object)

Return @code{True} if the object can be used in @ref{18d,,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


在 3.5 版被加入.

@end deffn

@geindex isasyncgenfunction() (於 inspect 模組中)
@anchor{library/inspect inspect isasyncgenfunction}@anchor{1a8b}
@deffn {函式} inspect.isasyncgenfunction (object)

Return @code{True} if the object is an @ref{2342,,asynchronous generator} function,
for example:

@example
>>> async def agen():
...     yield 1
...
>>> inspect.isasyncgenfunction(agen)
True
@end example


在 3.6 版被加入.



在 3.8 版的變更: Functions wrapped in @ref{217,,functools.partial()} now return @code{True} if the
wrapped function is an @ref{2342,,asynchronous generator} function.



在 3.13 版的變更: Functions wrapped in @ref{218,,functools.partialmethod()} now return @code{True}
if the wrapped function is a @ref{f6e,,coroutine function}.

@end deffn

@geindex isasyncgen() (於 inspect 模組中)
@anchor{library/inspect inspect isasyncgen}@anchor{48d8}
@deffn {函式} inspect.isasyncgen (object)

Return @code{True} if the object is an @ref{47d1,,asynchronous generator iterator}
created by an @ref{2342,,asynchronous generator} function.


在 3.6 版被加入.

@end deffn

@geindex istraceback() (於 inspect 模組中)
@anchor{library/inspect inspect istraceback}@anchor{48d9}
@deffn {函式} inspect.istraceback (object)

Return @code{True} if the object is a traceback.
@end deffn

@geindex isframe() (於 inspect 模組中)
@anchor{library/inspect inspect isframe}@anchor{48da}
@deffn {函式} inspect.isframe (object)

Return @code{True} if the object is a frame.
@end deffn

@geindex iscode() (於 inspect 模組中)
@anchor{library/inspect inspect iscode}@anchor{48db}
@deffn {函式} inspect.iscode (object)

如果物件是程式碼，則回傳 @code{True}。
@end deffn

@geindex isbuiltin() (於 inspect 模組中)
@anchor{library/inspect inspect isbuiltin}@anchor{48dc}
@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{853}
@deffn {函式} inspect.ismethodwrapper (object)

Return @code{True} if the type of object is a @ref{854,,MethodWrapperType}.

These are instances of @ref{854,,MethodWrapperType}, such as @ref{829,,__str__()},
@ref{ce9,,__eq__()} and @ref{828,,__repr__()}.


在 3.11 版被加入.

@end deffn

@geindex isroutine() (於 inspect 模組中)
@anchor{library/inspect inspect isroutine}@anchor{1afd}
@deffn {函式} inspect.isroutine (object)

如果物件是使用者定義或內建的函式或方法，則回傳 @code{True}。
@end deffn

@geindex isabstract() (於 inspect 模組中)
@anchor{library/inspect inspect isabstract}@anchor{48dd}
@deffn {函式} inspect.isabstract (object)

如果物件是抽象基底類別，則回傳 @code{True}。
@end deffn

@geindex ismethoddescriptor() (於 inspect 模組中)
@anchor{library/inspect inspect ismethoddescriptor}@anchor{18b5}
@deffn {函式} inspect.ismethoddescriptor (object)

Return @code{True} if the object is a method descriptor, but not if
@ref{48d5,,ismethod()}, @ref{48d4,,isclass()}, @ref{48d6,,isfunction()} or @ref{48dc,,isbuiltin()}
are true.

This, for example, is true of @code{int.__add__}.  An object passing this test
has a @ref{16dc,,__get__()} method, but not a @ref{2267,,__set__()}
method or a @ref{18b6,,__delete__()} method.  Beyond that, the set of
attributes varies.  A @ref{1261,,__name__} attribute is usually
sensible, and @ref{b18,,__doc__} often is.

Methods implemented via descriptors that also pass one of the other tests
return @code{False} from the @ref{18b5,,ismethoddescriptor()} test, simply because the
other tests promise more -- you can, e.g., count on having the
@ref{14fd,,__func__} attribute (etc) when an object passes
@ref{48d5,,ismethod()}.


在 3.13 版的變更: This function no longer incorrectly reports objects with @ref{16dc,,__get__()}
and @ref{18b6,,__delete__()}, but not @ref{2267,,__set__()}, as being method
descriptors (such objects are data descriptors, not method descriptors).

@end deffn

@geindex isdatadescriptor() (於 inspect 模組中)
@anchor{library/inspect inspect isdatadescriptor}@anchor{48de}
@deffn {函式} inspect.isdatadescriptor (object)

如果物件是資料描述器，則回傳 @code{True}。

Data descriptors have a @ref{2267,,__set__} or a @ref{18b6,,__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{1261,,__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{48df}
@deffn {函式} inspect.isgetsetdescriptor (object)

Return @code{True} if the object is a getset descriptor.

`CPython 實作細節：' getsets are attributes defined in extension modules via
@ref{dad,,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{48e0}
@deffn {函式} inspect.ismemberdescriptor (object)

如果物件是成員描述器，則回傳 @code{True}。

`CPython 實作細節：' Member descriptors are attributes defined in extension modules via
@ref{76a,,PyMemberDef} structures.  For Python implementations without such
types, this method will always return @code{False}.
@end deffn

@node 取得原始碼,Introspecting callables with the Signature object,Types and members,inspect --- 檢視活動物件
@anchor{library/inspect inspect-source}@anchor{48e1}@anchor{library/inspect retrieving-source-code}@anchor{48e2}
@subsubsection 取得原始碼


@geindex getdoc() (於 inspect 模組中)
@anchor{library/inspect inspect getdoc}@anchor{be4}
@deffn {函式} inspect.getdoc (object)

Get the documentation string for an object, cleaned up with @ref{197d,,cleandoc()}.
If the documentation string for an object is not provided and the object is
a class, a method, a property or a descriptor, retrieve the documentation
string from the inheritance hierarchy.
Return @code{None} if the documentation string is invalid or missing.


在 3.5 版的變更: Documentation strings are now inherited if not overridden.

@end deffn

@geindex getcomments() (於 inspect 模組中)
@anchor{library/inspect inspect getcomments}@anchor{189e}
@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{1d4c}
@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{198,,TypeError} if the object is a built-in module,
class, or function.
@end deffn

@geindex getmodule() (於 inspect 模組中)
@anchor{library/inspect inspect getmodule}@anchor{1a9c}
@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{1a9d}
@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{198,,TypeError} if the object is a built-in module, class, or
function.
@end deffn

@geindex getsourcelines() (於 inspect 模組中)
@anchor{library/inspect inspect getsourcelines}@anchor{174f}
@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{2c0,,OSError} is raised if the source code cannot
be retrieved.
A @ref{198,,TypeError} is raised if the object is a built-in module, class, or
function.


在 3.3 版的變更: @ref{2c0,,OSError} is raised instead of @ref{124e,,IOError}, now an alias of the
former.

@end deffn

@geindex getsource() (於 inspect 模組中)
@anchor{library/inspect inspect getsource}@anchor{1759}
@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{2c0,,OSError} is raised if the source code
cannot be retrieved.
A @ref{198,,TypeError} is raised if the object is a built-in module, class, or
function.


在 3.3 版的變更: @ref{2c0,,OSError} is raised instead of @ref{124e,,IOError}, now an alias of the
former.

@end deffn

@geindex cleandoc() (於 inspect 模組中)
@anchor{library/inspect inspect cleandoc}@anchor{197d}
@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,類別與函式<2>,取得原始碼,inspect --- 檢視活動物件
@anchor{library/inspect inspect-signature-object}@anchor{48e3}@anchor{library/inspect introspecting-callables-with-the-signature-object}@anchor{48e4}
@subsubsection Introspecting callables with the Signature object



在 3.3 版被加入.


The @ref{4de,,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{22f}
@deffn {函式} inspect.signature (callable, *, follow_wrapped=True, globals=None, locals=None, eval_str=False, annotation_format=Format.VALUE)

Return a @ref{4de,,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{217,,functools.partial()} objects.

If some of the annotations are strings (e.g., because
@code{from __future__ import annotations} was used), @ref{22f,,signature()} will
attempt to automatically un-stringize the annotations using
@ref{457,,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{230,,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{2eb,,ValueError} if no signature can be provided, and
@ref{198,,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{457,,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{2480,,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{4de}
@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{4df,,Parameter} object in its @ref{48e5,,parameters} collection.

The optional `parameters' argument is a sequence of @ref{4df,,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{48e6,,Signature.replace()} or
@ref{1c0,,copy.replace()} to make a modified copy.


在 3.5 版的變更: @code{Signature} objects are now picklable and @ref{81d,,hashable}.


@geindex empty (inspect.Signature 的屬性)
@anchor{library/inspect inspect Signature empty}@anchor{48e7}
@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{48e5}
@deffn {屬性} parameters

An ordered mapping of parameters' names to the corresponding
@ref{4df,,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{48e8}
@deffn {屬性} return_annotation

The "return" annotation for the callable.  If the callable has no "return"
annotation, this attribute is set to @ref{48e7,,Signature.empty}.
@end deffn

@geindex bind() (inspect.Signature 的方法)
@anchor{library/inspect inspect Signature bind}@anchor{180b}
@deffn {方法} bind (*args, **kwargs)

Create a mapping from positional and keyword arguments to parameters.
Returns @ref{1264,,BoundArguments} if @code{*args} and @code{**kwargs} match the
signature, or raises a @ref{198,,TypeError}.
@end deffn

@geindex bind_partial() (inspect.Signature 的方法)
@anchor{library/inspect inspect Signature bind_partial}@anchor{48e9}
@deffn {方法} bind_partial (*args, **kwargs)

Works the same way as @ref{180b,,Signature.bind()}, but allows the omission of
some required arguments (mimics @ref{217,,functools.partial()} behavior.)
Returns @ref{1264,,BoundArguments}, or raises a @ref{198,,TypeError} if the
passed arguments do not match the signature.
@end deffn

@geindex replace() (inspect.Signature 的方法)
@anchor{library/inspect inspect Signature replace}@anchor{48e6}
@deffn {方法} replace (*[, parameters][, return_annotation])

Create a new @ref{4de,,Signature} instance based on the instance
@ref{48e6,,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{48e7,,Signature.empty}.

@example
>>> def test(a, b):
...     pass
...
>>> sig = signature(test)
>>> new_sig = sig.replace(return_annotation="new return anno")
>>> str(new_sig)
"(a, b) -> 'new return anno'"
@end example

@ref{4de,,Signature} objects are also supported by the generic function
@ref{1c0,,copy.replace()}.
@end deffn

@geindex format() (inspect.Signature 的方法)
@anchor{library/inspect inspect Signature format}@anchor{231}
@deffn {方法} format (*, max_width=None, quote_annotation_strings=True)

Create a string representation of the @ref{4de,,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{15c,,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{160,,STRING} format or if
@code{from __future__ import annotations} was used.


在 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{93a}
@deffn {方法} classmethod from_callable (obj, *, follow_wrapped=True, globals=None, locals=None, eval_str=False)

Return a @ref{4de,,Signature} (or its subclass) object for a given callable
`obj'.

This method simplifies subclassing of @ref{4de,,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{22f,,signature()}.


在 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{4df}
@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{48ea,,Parameter.replace()} or @ref{1c0,,copy.replace()} to create a modified copy.


在 3.5 版的變更: Parameter objects are now picklable and @ref{81d,,hashable}.


@geindex empty (inspect.Parameter 的屬性)
@anchor{library/inspect inspect Parameter empty}@anchor{48eb}
@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{48ec}
@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{48ed}
@deffn {屬性} default

The default value for the parameter.  If the parameter has no default
value, this attribute is set to @ref{48eb,,Parameter.empty}.
@end deffn

@geindex annotation (inspect.Parameter 的屬性)
@anchor{library/inspect inspect Parameter annotation}@anchor{48ee}
@deffn {屬性} annotation

The annotation for the parameter.  If the parameter has no annotation,
this attribute is set to @ref{48eb,,Parameter.empty}.
@end deffn

@geindex kind (inspect.Parameter 的屬性)
@anchor{library/inspect inspect Parameter kind}@anchor{48ef}
@deffn {屬性} kind

Describes how argument values are bound to the parameter.  The possible
values are accessible via @ref{4df,,Parameter} (like @code{Parameter.KEYWORD_ONLY}),
and support comparison and ordering, in the following order:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

名稱

@tab

意義

@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{48f0}
@deffn {屬性} kind.description

Describes an enum value of @ref{48ef,,Parameter.kind}.


在 3.8 版被加入.


範例：列印所有引數的描述：

@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{48ea}
@deffn {方法} replace (*[, name][, kind][, default][, annotation])

Create a new @ref{4df,,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{48eb,,Parameter.empty}.

@example
>>> from inspect import Parameter
>>> param = Parameter('foo', Parameter.KEYWORD_ONLY, default=42)
>>> str(param)
'foo=42'

>>> str(param.replace()) # Will create a shallow copy of 'param'
'foo=42'

>>> str(param.replace(default=Parameter.empty, annotation='spam'))
"foo: 'spam'"
@end example

@ref{4df,,Parameter} objects are also supported by the generic function
@ref{1c0,,copy.replace()}.
@end deffn


在 3.4 版的變更: In Python 3.3 @ref{4df,,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{1264}
@deffn {類別} inspect.BoundArguments

Result of a @ref{180b,,Signature.bind()} or @ref{48e9,,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{aff}
@deffn {屬性} arguments

A mutable mapping of parameters' names to arguments' values.
Contains only explicitly bound arguments.  Changes in @ref{aff,,arguments}
will reflect in @ref{48f1,,args} and @ref{48f2,,kwargs}.

Should be used in conjunction with @ref{48e5,,Signature.parameters} for any
argument processing purposes.

@cartouche
@quotation 備註 
Arguments for which @ref{180b,,Signature.bind()} or
@ref{48e9,,Signature.bind_partial()} relied on a default value are skipped.
However, if needed, use @ref{1011,,BoundArguments.apply_defaults()} to add
them.
@end quotation
@end cartouche


在 3.9 版的變更: @ref{aff,,arguments} is now of type @ref{183,,dict}. Formerly, it was of
type @ref{7ec,,collections.OrderedDict}.

@end deffn

@geindex args (inspect.BoundArguments 的屬性)
@anchor{library/inspect inspect BoundArguments args}@anchor{48f1}
@deffn {屬性} args

A tuple of positional arguments values.  Dynamically computed from the
@ref{aff,,arguments} attribute.
@end deffn

@geindex kwargs (inspect.BoundArguments 的屬性)
@anchor{library/inspect inspect BoundArguments kwargs}@anchor{48f2}
@deffn {屬性} kwargs

A dict of keyword arguments values.  Dynamically computed from the
@ref{aff,,arguments} attribute.  Arguments that can be passed positionally
are included in @ref{48f1,,args} instead.
@end deffn

@geindex signature (inspect.BoundArguments 的屬性)
@anchor{library/inspect inspect BoundArguments signature}@anchor{48f3}
@deffn {屬性} signature

A reference to the parent @ref{4de,,Signature} object.
@end deffn

@geindex apply_defaults() (inspect.BoundArguments 的方法)
@anchor{library/inspect inspect BoundArguments apply_defaults}@anchor{1011}
@deffn {方法} apply_defaults ()

為遺漏的引數設定預設值。

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


在 3.5 版被加入.

@end deffn

The @ref{48f1,,args} and @ref{48f2,,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/} - 函式簽名物件。

詳細的規格、實作細節和範例。
@end table


@node 類別與函式<2>,直譯器堆疊,Introspecting callables with the Signature object,inspect --- 檢視活動物件
@anchor{library/inspect classes-and-functions}@anchor{48f4}@anchor{library/inspect inspect-classes-functions}@anchor{48f5}
@subsubsection 類別與函式


@geindex getclasstree() (於 inspect 模組中)
@anchor{library/inspect inspect getclasstree}@anchor{48f6}
@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{939}
@deffn {函式} inspect.getfullargspec (func)

Get the names and default values of a Python function's parameters.  A
@ref{857,,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{22f,,signature()} and
@ref{48e3,,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.


在 3.4 版的變更: This function is now based on @ref{22f,,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{22f,,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.

@end deffn

@geindex getargvalues() (於 inspect 模組中)
@anchor{library/inspect inspect getargvalues}@anchor{10ba}
@deffn {函式} inspect.getargvalues (frame)

Get information about arguments passed into a particular frame.  A
@ref{857,,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{10bb}
@deffn {函式} inspect.formatargvalues (args[, varargs, varkw, locals, formatarg, formatvarargs, formatvarkw, formatvalue])

Format a pretty argument spec from the four values returned by
@ref{10ba,,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{48f7}
@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{10b9}
@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


在 3.2 版被加入.



在 3.5 版之後被棄用: 請改用 @ref{180b,,Signature.bind()} 與 @ref{48e9,,Signature.bind_partial()}。

@end deffn

@geindex getclosurevars() (於 inspect 模組中)
@anchor{library/inspect inspect getclosurevars}@anchor{12d6}
@deffn {函式} inspect.getclosurevars (func)

Get the mapping of external name references in a Python function or
method `func' to their current values. A
@ref{857,,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.

如果 `func' 不是 Python 函式或方法，則引發 @ref{198,,TypeError}。


在 3.3 版被加入.

@end deffn

@geindex unwrap() (於 inspect 模組中)
@anchor{library/inspect inspect unwrap}@anchor{1157}
@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{22f,,signature()} uses this to stop unwrapping if any object in the
chain has a @code{__signature__} attribute defined.

如果遇到循環，則引發 @ref{2eb,,ValueError}。


在 3.4 版被加入.

@end deffn

@geindex get_annotations() (於 inspect 模組中)
@anchor{library/inspect inspect get_annotations}@anchor{a0d}
@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{457,,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{43d0,,Security implications of introspecting annotations} for more information.
@end quotation
@end cartouche


在 3.10 版被加入.



在 3.14 版的變更: This function is now an alias for @ref{457,,annotationlib.get_annotations()}.
Calling it as @code{inspect.get_annotations} will continue to work.

@end deffn

@node 直譯器堆疊,Fetching attributes statically,類別與函式<2>,inspect --- 檢視活動物件
@anchor{library/inspect inspect-stack}@anchor{48f8}@anchor{library/inspect the-interpreter-stack}@anchor{48f9}
@subsubsection 直譯器堆疊


Some of the following functions return
@ref{855,,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{855}
@deffn {類別} inspect.FrameInfo

@geindex frame (inspect.FrameInfo 的屬性)
@anchor{library/inspect inspect FrameInfo frame}@anchor{48fa}
@deffn {屬性} frame

The @ref{8e7,,frame object} that the record corresponds to.
@end deffn

@geindex filename (inspect.FrameInfo 的屬性)
@anchor{library/inspect inspect FrameInfo filename}@anchor{48fb}
@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{48fc}
@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{48fd}
@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{48fe}
@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{48ff}
@deffn {屬性} index

The index of the current line being executed in the @ref{48fe,,code_context} list.
@end deffn

@geindex positions (inspect.FrameInfo 的屬性)
@anchor{library/inspect inspect FrameInfo positions}@anchor{4900}
@deffn {屬性} positions

A @ref{18a6,,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{857,,named tuple} instead of a @ref{60c,,tuple}.



在 3.11 版的變更: @code{FrameInfo} is now a class instance
(that is backwards compatible with the previous @ref{857,,named tuple}).

@end deffn

@geindex Traceback (inspect 中的類別)
@anchor{library/inspect inspect Traceback}@anchor{856}
@deffn {類別} inspect.Traceback

@geindex filename (inspect.Traceback 的屬性)
@anchor{library/inspect inspect Traceback filename}@anchor{4901}
@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{4902}
@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{4903}
@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{4904}
@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{4905}
@deffn {屬性} index

The index of the current line being executed in the @ref{4904,,code_context} list.
@end deffn

@geindex positions (inspect.Traceback 的屬性)
@anchor{library/inspect inspect Traceback positions}@anchor{4906}
@deffn {屬性} positions

A @ref{18a6,,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{857,,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{1b0,,finally} clause.  This is also important if the cycle detector was
disabled when Python was compiled or using @ref{48c6,,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{57f,,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{858}
@deffn {函式} inspect.getframeinfo (frame, context=1)

Get information about a frame or traceback object.  A @ref{856,,Traceback} object
is returned.


在 3.11 版的變更: A @ref{856,,Traceback} object is returned instead of a named tuple.

@end deffn

@geindex getouterframes() (於 inspect 模組中)
@anchor{library/inspect inspect getouterframes}@anchor{859}
@deffn {函式} inspect.getouterframes (frame, context=1)

Get a list of @ref{855,,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{857,,named tuples}
@code{FrameInfo(frame, filename, lineno, function, code_context, index)}
is returned.



在 3.11 版的變更: 回傳一個 @ref{855,,FrameInfo} 物件串列。

@end deffn

@geindex getinnerframes() (於 inspect 模組中)
@anchor{library/inspect inspect getinnerframes}@anchor{85a}
@deffn {函式} inspect.getinnerframes (traceback, context=1)

Get a list of @ref{855,,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{857,,named tuples}
@code{FrameInfo(frame, filename, lineno, function, code_context, index)}
is returned.



在 3.11 版的變更: 回傳一個 @ref{855,,FrameInfo} 物件串列。

@end deffn

@geindex currentframe() (於 inspect 模組中)
@anchor{library/inspect inspect currentframe}@anchor{8e9}
@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{85b}
@deffn {函式} inspect.stack (context=1)

Return a list of @ref{855,,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{857,,named tuples}
@code{FrameInfo(frame, filename, lineno, function, code_context, index)}
is returned.



在 3.11 版的變更: 回傳一個 @ref{855,,FrameInfo} 物件串列。

@end deffn

@geindex trace() (於 inspect 模組中)
@anchor{library/inspect inspect trace}@anchor{85c}
@deffn {函式} inspect.trace (context=1)

Return a list of @ref{855,,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{857,,named tuples}
@code{FrameInfo(frame, filename, lineno, function, code_context, index)}
is returned.



在 3.11 版的變更: 回傳一個 @ref{855,,FrameInfo} 物件串列。

@end deffn

@node Fetching attributes statically,Current State of Generators Coroutines and Asynchronous Generators,直譯器堆疊,inspect --- 檢視活動物件
@anchor{library/inspect fetching-attributes-statically}@anchor{4907}
@subsubsection Fetching attributes statically


Both @ref{dc5,,getattr()} and @ref{6f2,,hasattr()} can trigger code execution when
fetching or checking for the existence of attributes. Descriptors, like
properties, will be invoked and @ref{6f3,,__getattr__()} and
@ref{dc6,,__getattribute__()}
may be called.

For cases where you want passive introspection, like documentation tools, this
can be inconvenient. @ref{6b5,,getattr_static()} has the same signature as @ref{dc5,,getattr()}
but avoids executing code when it fetches attributes.

@geindex getattr_static() (於 inspect 模組中)
@anchor{library/inspect inspect getattr_static}@anchor{6b5}
@deffn {函式} inspect.getattr_static (obj, attr, default=None)

Retrieve attributes without triggering dynamic lookup via the
descriptor protocol, @ref{6f3,,__getattr__()}
or @ref{dc6,,__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{776,,__dict__} is shadowed by another member (for
example a property) then this function will be unable to find instance
members.


在 3.2 版被加入.

@end deffn

@ref{6b5,,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 --- 檢視活動物件
@anchor{library/inspect current-state-of-generators-coroutines-and-asynchronous-generators}@anchor{4908}
@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{1437,,getgeneratorstate()} allows the current state of a
generator to be determined easily.

@geindex getgeneratorstate() (於 inspect 模組中)
@anchor{library/inspect inspect getgeneratorstate}@anchor{1437}
@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


在 3.2 版被加入.

@end deffn

@geindex getcoroutinestate() (於 inspect 模組中)
@anchor{library/inspect inspect getcoroutinestate}@anchor{1015}
@deffn {函式} inspect.getcoroutinestate (coroutine)

Get current state of a coroutine object.  The function is intended to be
used with coroutine objects created by @ref{7e6,,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


在 3.5 版被加入.

@end deffn

@geindex getasyncgenstate() (於 inspect 模組中)
@anchor{library/inspect inspect getasyncgenstate}@anchor{6b3}
@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{7e6,,async def} functions which use the @ref{bb9,,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: 等待開始執行。

@item 
AGEN_RUNNING: 目前正在被直譯器執行。

@item 
AGEN_SUSPENDED: 目前於 yield 運算式暫停。

@item 
AGEN_CLOSED: 執行已完成。
@end itemize


在 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{12d7}
@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{469,,locals()} in the body of the
generator, and all the same caveats apply.

If `generator' is a @ref{125c,,generator} with no currently associated frame,
then an empty dictionary is returned.  @ref{198,,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.


在 3.3 版被加入.

@end deffn

@geindex getcoroutinelocals() (於 inspect 模組中)
@anchor{library/inspect inspect getcoroutinelocals}@anchor{1014}
@deffn {函式} inspect.getcoroutinelocals (coroutine)

This function is analogous to @ref{12d7,,getgeneratorlocals()}, but
works for coroutine objects created by @ref{7e6,,async def} functions.


在 3.5 版被加入.

@end deffn

@geindex getasyncgenlocals() (於 inspect 模組中)
@anchor{library/inspect inspect getasyncgenlocals}@anchor{6b4}
@deffn {函式} inspect.getasyncgenlocals (agen)

This function is analogous to @ref{12d7,,getgeneratorlocals()}, but
works for asynchronous generator objects created by @ref{7e6,,async def}
functions which use the @ref{bb9,,yield} statement.


在 3.12 版被加入.

@end deffn

@node Code Objects Bit Flags,Buffer flags,Current State of Generators Coroutines and Asynchronous Generators,inspect --- 檢視活動物件
@anchor{library/inspect code-objects-bit-flags}@anchor{4909}@anchor{library/inspect inspect-module-co-flags}@anchor{2243}
@subsubsection Code Objects Bit Flags


Python code objects have a @ref{1848,,co_flags} attribute,
which is a bitmap of the following flags:

@geindex CO_OPTIMIZED (於 inspect 模組中)
@anchor{library/inspect inspect CO_OPTIMIZED}@anchor{490a}
@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{490b}
@deffn {資料} inspect.CO_NEWLOCALS

If set, a new dict will be created for the frame's @ref{4a0,,f_locals}
when the code object is executed.
@end deffn

@geindex CO_VARARGS (於 inspect 模組中)
@anchor{library/inspect inspect CO_VARARGS}@anchor{490c}
@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{490d}
@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{490e}
@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{490f}
@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{4910}
@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.


在 3.5 版被加入.

@end deffn

@geindex CO_ITERABLE_COROUTINE (於 inspect 模組中)
@anchor{library/inspect inspect CO_ITERABLE_COROUTINE}@anchor{4911}
@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.


在 3.5 版被加入.

@end deffn

@geindex CO_ASYNC_GENERATOR (於 inspect 模組中)
@anchor{library/inspect inspect CO_ASYNC_GENERATOR}@anchor{4912}
@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.


在 3.6 版被加入.

@end deffn

@geindex CO_HAS_DOCSTRING (於 inspect 模組中)
@anchor{library/inspect inspect CO_HAS_DOCSTRING}@anchor{2245}
@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{1814,,co_consts}.


在 3.14 版被加入.

@end deffn

@geindex CO_METHOD (於 inspect 模組中)
@anchor{library/inspect inspect CO_METHOD}@anchor{4913}
@deffn {資料} inspect.CO_METHOD

The flag is set when the code object is a function defined in class
scope.


在 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 @ref{82,,inspect} module
for any introspection needs.
@end quotation
@end cartouche

@node Buffer flags,命令列介面<12>,Code Objects Bit Flags,inspect --- 檢視活動物件
@anchor{library/inspect buffer-flags}@anchor{4914}
@subsubsection Buffer flags


@geindex BufferFlags (inspect 中的類別)
@anchor{library/inspect inspect BufferFlags}@anchor{686}
@deffn {類別} inspect.BufferFlags

This is an @ref{e95,,enum.IntFlag} that represents the flags that
can be passed to the @ref{685,,__buffer__()} method of objects
implementing the @ref{260,,buffer protocol}.

The meaning of the flags is explained at @ref{4915,,Buffer request types}.

@geindex SIMPLE (inspect.BufferFlags 的屬性)
@anchor{library/inspect inspect BufferFlags SIMPLE}@anchor{4916}
@deffn {屬性} SIMPLE
@end deffn

@geindex WRITABLE (inspect.BufferFlags 的屬性)
@anchor{library/inspect inspect BufferFlags WRITABLE}@anchor{4917}
@deffn {屬性} WRITABLE
@end deffn

@geindex FORMAT (inspect.BufferFlags 的屬性)
@anchor{library/inspect inspect BufferFlags FORMAT}@anchor{4918}
@deffn {屬性} FORMAT
@end deffn

@geindex ND (inspect.BufferFlags 的屬性)
@anchor{library/inspect inspect BufferFlags ND}@anchor{4919}
@deffn {屬性} ND
@end deffn

@geindex STRIDES (inspect.BufferFlags 的屬性)
@anchor{library/inspect inspect BufferFlags STRIDES}@anchor{491a}
@deffn {屬性} STRIDES
@end deffn

@geindex C_CONTIGUOUS (inspect.BufferFlags 的屬性)
@anchor{library/inspect inspect BufferFlags C_CONTIGUOUS}@anchor{491b}
@deffn {屬性} C_CONTIGUOUS
@end deffn

@geindex F_CONTIGUOUS (inspect.BufferFlags 的屬性)
@anchor{library/inspect inspect BufferFlags F_CONTIGUOUS}@anchor{491c}
@deffn {屬性} F_CONTIGUOUS
@end deffn

@geindex ANY_CONTIGUOUS (inspect.BufferFlags 的屬性)
@anchor{library/inspect inspect BufferFlags ANY_CONTIGUOUS}@anchor{491d}
@deffn {屬性} ANY_CONTIGUOUS
@end deffn

@geindex INDIRECT (inspect.BufferFlags 的屬性)
@anchor{library/inspect inspect BufferFlags INDIRECT}@anchor{491e}
@deffn {屬性} INDIRECT
@end deffn

@geindex CONTIG (inspect.BufferFlags 的屬性)
@anchor{library/inspect inspect BufferFlags CONTIG}@anchor{491f}
@deffn {屬性} CONTIG
@end deffn

@geindex CONTIG_RO (inspect.BufferFlags 的屬性)
@anchor{library/inspect inspect BufferFlags CONTIG_RO}@anchor{4920}
@deffn {屬性} CONTIG_RO
@end deffn

@geindex STRIDED (inspect.BufferFlags 的屬性)
@anchor{library/inspect inspect BufferFlags STRIDED}@anchor{4921}
@deffn {屬性} STRIDED
@end deffn

@geindex STRIDED_RO (inspect.BufferFlags 的屬性)
@anchor{library/inspect inspect BufferFlags STRIDED_RO}@anchor{4922}
@deffn {屬性} STRIDED_RO
@end deffn

@geindex RECORDS (inspect.BufferFlags 的屬性)
@anchor{library/inspect inspect BufferFlags RECORDS}@anchor{4923}
@deffn {屬性} RECORDS
@end deffn

@geindex RECORDS_RO (inspect.BufferFlags 的屬性)
@anchor{library/inspect inspect BufferFlags RECORDS_RO}@anchor{4924}
@deffn {屬性} RECORDS_RO
@end deffn

@geindex FULL (inspect.BufferFlags 的屬性)
@anchor{library/inspect inspect BufferFlags FULL}@anchor{4925}
@deffn {屬性} FULL
@end deffn

@geindex FULL_RO (inspect.BufferFlags 的屬性)
@anchor{library/inspect inspect BufferFlags FULL_RO}@anchor{4926}
@deffn {屬性} FULL_RO
@end deffn

@geindex READ (inspect.BufferFlags 的屬性)
@anchor{library/inspect inspect BufferFlags READ}@anchor{1860}
@deffn {屬性} READ
@end deffn

@geindex WRITE (inspect.BufferFlags 的屬性)
@anchor{library/inspect inspect BufferFlags WRITE}@anchor{1861}
@deffn {屬性} WRITE
@end deffn


在 3.12 版被加入.

@end deffn

@node 命令列介面<12>,,Buffer flags,inspect --- 檢視活動物件
@anchor{library/inspect command-line-interface}@anchor{4927}@anchor{library/inspect inspect-module-cli}@anchor{1156}
@subsubsection 命令列介面


The @ref{82,,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
appended a colon and the qualified name of the target object.

@geindex inspect 命令列選項; --details
@anchor{library/inspect cmdoption-inspect-details}@anchor{4928}
@deffn {Option} @w{-}@w{-}details

Print information about the specified object rather than the source 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 annotationlib --- 用於自我檢查註釋的功能,site --- Site-specific configuration hook,inspect --- 檢視活動物件,Python Runtime 服務
@anchor{library/annotationlib doc}@anchor{4929}@anchor{library/annotationlib annotationlib-functionality-for-introspecting-annotations}@anchor{492a}@anchor{library/annotationlib module-annotationlib}@anchor{6}@anchor{library/annotationlib translation-repo}@anchor{492b}
@subsection @code{annotationlib} --- 用於自我檢查註釋的功能


@geindex module; annotationlib


在 3.14 版被加入.


`原始碼：' Lib/annotationlib.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/annotationlib.py}

@c import annotationlib
@c from annotationlib import *


__________________________________________________________________


The @code{annotationlib} module provides tools for introspecting
@ref{15c,,annotations} on modules, classes, and functions.

Annotations are @ref{67e,,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{230,,Format}), each of which works best for different use cases:


@itemize *

@item 
@ref{15e,,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{15f,,FORWARDREF} returns @ref{17d8,,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{160,,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{457,,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{15d,,annotate function}
that is used to evaluate annotations, such as @ref{459,,get_annotate_from_class_namespace()}
and @ref{1754,,call_annotate_function()}, as well as the
@ref{43a8,,call_evaluate_function()} function for working with
@ref{43a7,,evaluate functions}.

@cartouche
@quotation 警示 
Most functionality in this module can execute arbitrary code; see
@ref{43d0,,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{9d2,,註釋 (annotation) 最佳實踐} provides best practices for working with
annotations.

typing-extensions@footnote{https://pypi.org/project/typing-extensions/} provides a backport of @ref{457,,get_annotations()}
that works on earlier versions of Python.


@menu
* Annotation semantics:: 
* Classes: Classes<3>. 
* Functions:: 
* Recipes: Recipes<2>. 
* STRING 格式的限制:: 
* FORWARDREF 格式的限制:: 
* Security implications of introspecting annotations:: 

@end menu

@node Annotation semantics,Classes<3>,,annotationlib --- 用於自我檢查註釋的功能
@anchor{library/annotationlib annotation-semantics}@anchor{492c}
@subsubsection Annotation semantics


The way annotations are evaluated has changed over the history of Python 3,
and currently still depends on a @ref{45b,,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{450,,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<3>,Functions,Annotation semantics,annotationlib --- 用於自我檢查註釋的功能
@anchor{library/annotationlib classes}@anchor{492d}
@subsubsection Classes


@geindex Format (annotationlib 中的類別)
@anchor{library/annotationlib annotationlib Format}@anchor{230}
@deffn {類別} annotationlib.Format

An @ref{ed6,,IntEnum} describing the formats in which annotations
can be returned. Members of the enum, or their equivalent integer values,
can be passed to @ref{457,,get_annotations()} and other functions in this
module, as well as to @ref{18df,,__annotate__} functions.

@geindex VALUE (annotationlib.Format 的屬性)
@anchor{library/annotationlib annotationlib Format VALUE}@anchor{15e}
@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{492e}
@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{15e,,Format.VALUE} format, or raise @ref{369,,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{15f}
@deffn {屬性} FORWARDREF = 3

Values are real annotation values (as per @ref{15e,,Format.VALUE} format)
for defined values, and @ref{17d8,,ForwardRef} proxies for undefined
values. Real objects may contain references to @ref{17d8,,ForwardRef}
proxy objects.
@end deffn

@geindex STRING (annotationlib.Format 的屬性)
@anchor{library/annotationlib annotationlib Format STRING}@anchor{160}
@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


在 3.14 版被加入.

@end deffn

@geindex ForwardRef (annotationlib 中的類別)
@anchor{library/annotationlib annotationlib ForwardRef}@anchor{17d8}
@deffn {類別} annotationlib.ForwardRef

A proxy object for forward references in annotations.

Instances of this class are returned when the @ref{15f,,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{492f}
@deffn {屬性} __forward_arg__

A string containing the code that was evaluated to produce the
@ref{17d8,,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{1785}
@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{15e,,VALUE} (the default),
this method may throw an exception, such as @ref{450,,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{15f,,FORWARDREF},
the method will never throw an exception, but may return a @ref{17d8,,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 @ref{15f,,FORWARDREF} format will return
@code{list[ForwardRef('undefined')]}. If the `format' argument is
@ref{160,,STRING}, the method will return @ref{492f,,__forward_arg__}.

The `owner' parameter provides the preferred mechanism for passing scope
information to this method. The owner of a @ref{17d8,,ForwardRef} is the
object that contains the annotation from which the @ref{17d8,,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 @ref{17d8,,ForwardRef}
is evaluated. `globals' and `locals' are passed to @ref{49e,,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{67a,,generic classes} and @ref{67b,,functions}.
It is a tuple of @ref{5a7,,type parameters} that are in scope
while the forward reference is being evaluated. For example, if evaluating a
@ref{17d8,,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__}.

@ref{17d8,,ForwardRef} instances returned by @ref{457,,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. @ref{17d8,,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
@ref{17d8,,ForwardRef} does not contain information about its origin,
empty globals and locals dictionaries are used.
@end deffn


在 3.14 版被加入.

@end deffn

@node Functions,Recipes<2>,Classes<3>,annotationlib --- 用於自我檢查註釋的功能
@anchor{library/annotationlib functions}@anchor{4930}
@subsubsection Functions


@geindex annotations_to_string() (於 annotationlib 模組中)
@anchor{library/annotationlib annotationlib annotations_to_string}@anchor{4931}
@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{17d5,,type_repr()}.
This is meant as a helper for user-provided
annotate functions that support the @ref{160,,STRING} format but
do not have access to the code creating the annotations.

For example, this is used to implement the @ref{160,,STRING} for
@ref{331,,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


在 3.14 版被加入.

@end deffn

@geindex call_annotate_function() (於 annotationlib 模組中)
@anchor{library/annotationlib annotationlib call_annotate_function}@anchor{1754}
@deffn {函式} annotationlib.call_annotate_function (annotate, format, *, owner=None)

Call the @ref{15d,,annotate function} `annotate' with the given `format',
a member of the @ref{230,,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{15e,,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{15f,,FORWARDREF} format to produce a @ref{17d8,,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.



在 3.14 版被加入.

@end deffn

@geindex call_evaluate_function() (於 annotationlib 模組中)
@anchor{library/annotationlib annotationlib call_evaluate_function}@anchor{43a8}
@deffn {函式} annotationlib.call_evaluate_function (evaluate, format, *, owner=None)

Call the @ref{43a7,,evaluate function} `evaluate' with the given `format',
a member of the @ref{230,,Format} enum, and return the value produced by
the function. This is similar to @ref{1754,,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{43bd,,typing.TypeAliasType.evaluate_value()}, the value of type aliases

@item 
@ref{43a6,,typing.TypeVar.evaluate_bound()}, the bound of type variables

@item 
@ref{43aa,,typing.TypeVar.evaluate_constraints()}, the constraints of
type variables

@item 
@ref{43ac,,typing.TypeVar.evaluate_default()}, the default value of
type variables

@item 
@ref{43b7,,typing.ParamSpec.evaluate_default()}, the default value of
parameter specifications

@item 
@ref{43b0,,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


在 3.14 版被加入.

@end deffn

@geindex get_annotate_from_class_namespace() (於 annotationlib 模組中)
@anchor{library/annotationlib annotationlib get_annotate_from_class_namespace}@anchor{459}
@deffn {函式} annotationlib.get_annotate_from_class_namespace (namespace)

Retrieve the @ref{15d,,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{4932,,below} for an example using this function in a metaclass.


在 3.14 版被加入.

@end deffn

@geindex get_annotations() (於 annotationlib 模組中)
@anchor{library/annotationlib annotationlib get_annotations}@anchor{457}
@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{18df,,__annotate__} or @ref{456,,__annotations__} attributes.
Passing any other object raises @ref{198,,TypeError}.

The `format' parameter controls the format in which annotations are returned,
and must be a member of the @ref{230,,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{15f,,FORWARDREF}.
If this is not implemented, it will then check if @ref{492e,,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{15e,,VALUE}.
If @ref{15e,,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{4931,,annotations_to_string()}.


@itemize *

@item 
When calling @code{object.__annotate__} it is first called with @ref{160,,STRING}.
If this is not implemented, it will then check if @ref{492e,,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{15e,,VALUE}
with the result converted using @ref{4931,,annotations_to_string()}.
If @ref{15e,,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{49e,,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{15e,,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{49e,,eval()} on those values:


@itemize *

@item 
If eval_str is true, @ref{49e,,eval()} is called on values of type
@code{str}. (Note that @code{get_annotations()} doesn't catch
exceptions; if @ref{49e,,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{49e,,eval()}; see the documentation
for @ref{49e,,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 
如果 `obj' 是模組，則 `globals' 預設為 @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{14d4,,obj.__globals__},
although if `obj' is a wrapped function (using
@ref{121d,,functools.update_wrapper()}) or a @ref{217,,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{9d2,,註釋 (annotation) 最佳實踐} 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


在 3.14 版被加入.

@end deffn

@geindex type_repr() (於 annotationlib 模組中)
@anchor{library/annotationlib annotationlib type_repr}@anchor{17d5}
@deffn {函式} annotationlib.type_repr (value)

Convert an arbitrary Python value to a format suitable for use by the
@ref{160,,STRING} format. This calls @ref{1c1,,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{160,,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.


在 3.14 版被加入.

@end deffn

@node Recipes<2>,STRING 格式的限制,Functions,annotationlib --- 用於自我檢查註釋的功能
@anchor{library/annotationlib recipes}@anchor{4933}
@subsubsection Recipes


@menu
* Using annotations in a metaclass:: 

@end menu

@node Using annotations in a metaclass,,,Recipes<2>
@anchor{library/annotationlib annotationlib-metaclass}@anchor{4932}@anchor{library/annotationlib using-annotations-in-a-metaclass}@anchor{4934}
@subsubsection Using annotations in a metaclass


A @ref{2270,,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{459,,get_annotate_from_class_namespace()} can be used to get the
annotate function, and @ref{1754,,call_annotate_function()} can be used to call it and
retrieve the annotations. Using the @ref{15f,,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{567,,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 STRING 格式的限制,FORWARDREF 格式的限制,Recipes<2>,annotationlib --- 用於自我檢查註釋的功能
@anchor{library/annotationlib limitations-of-the-string-format}@anchor{4935}
@subsubsection @code{STRING} 格式的限制


The @ref{160,,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{1c7b,,ast.BinOp}

@item 
@ref{4936,,ast.UnaryOp}


@itemize *

@item 
@ref{4937,,ast.Invert} (@code{~})、@ref{4938,,ast.UAdd} (@code{+}) 和 @ref{4939,,ast.USub} (@code{-}) 有被支援

@item 
@ref{493a,,ast.Not} (@code{not}) 並不被支援
@end itemize

@item 
@ref{1c12,,ast.Dict}（除了使用 @code{**} 解包的情況）

@item 
@ref{493b,,ast.Set}

@item 
@ref{493c,,ast.Compare}


@itemize *

@item 
@ref{493d,,ast.Eq} 和 @ref{493e,,ast.NotEq} 有被支援

@item 
@ref{493f,,ast.Lt}, @ref{4940,,ast.LtE}, @ref{4941,,ast.Gt}, and @ref{4942,,ast.GtE} are supported, but the operand may be flipped

@item 
@ref{4943,,ast.Is}, @ref{4944,,ast.IsNot}, @ref{4945,,ast.In}, and @ref{4946,,ast.NotIn} are not supported
@end itemize

@item 
@ref{4947,,ast.Call} (except when using @code{**} unpacking)

@item 
@ref{2ee,,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{4948,,ast.Attribute} (assuming the value is not a constant)

@item 
@ref{4949,,ast.Subscript} (assuming the value is not a constant)

@item 
@ref{494a,,ast.Starred} (@code{*} unpacking)

@item 
@ref{1bf4,,ast.Name}

@item 
@ref{494b,,ast.List}

@item 
@ref{494c,,ast.Tuple}

@item 
@ref{494d,,ast.Slice}
@end itemize

The following are unsupported, but throw an informative error when encountered by the
stringifier:


@itemize *

@item 
@ref{494e,,ast.FormattedValue} (f-strings; error is not detected if conversion specifiers like @code{!r}
are used)

@item 
@ref{19ad,,ast.JoinedStr}（f 字串）
@end itemize

以下是不支援的，並且會導致不正確的輸出：


@itemize *

@item 
@ref{494f,,ast.BoolOp}（@code{and} 和 @code{or}）

@item 
@ref{4950,,ast.IfExp}

@item 
@ref{4951,,ast.Lambda}

@item 
@ref{4952,,ast.ListComp}

@item 
@ref{4953,,ast.SetComp}

@item 
@ref{4954,,ast.DictComp}

@item 
@ref{4955,,ast.GeneratorExp}
@end itemize

The following are disallowed in annotation scopes and therefore not relevant:


@itemize *

@item 
@ref{4956,,ast.NamedExpr} (@code{:=})

@item 
@ref{4957,,ast.Await}

@item 
@ref{4958,,ast.Yield}

@item 
@ref{4959,,ast.YieldFrom}
@end itemize

@node FORWARDREF 格式的限制,Security implications of introspecting annotations,STRING 格式的限制,annotationlib --- 用於自我檢查註釋的功能
@anchor{library/annotationlib limitations-of-the-forwardref-format}@anchor{495a}
@subsubsection @code{FORWARDREF} 格式的限制


The @ref{15f,,FORWARDREF} format aims to produce real values as much
as possible, with anything that cannot be resolved replaced with
@ref{17d8,,ForwardRef} objects. It is affected by broadly the same Limitations
as the @ref{160,,STRING} format: annotations that perform operations on
literals or that use unsupported expression types may raise exceptions when
evaluated using the @ref{15f,,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,,FORWARDREF 格式的限制,annotationlib --- 用於自我檢查註釋的功能
@anchor{library/annotationlib annotationlib-security}@anchor{43d0}@anchor{library/annotationlib security-implications-of-introspecting-annotations}@anchor{495b}
@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{457,,get_annotations()} may call an arbitrary @ref{15d,,annotate function}, and
@ref{1785,,ForwardRef.evaluate()} may call @ref{49e,,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{456,,__annotations__} attribute,
and for various functions in the @ref{10a,,typing} module that work with annotations, such as
@ref{8b9,,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{17d8,,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 --- 用於自我檢查註釋的功能,Python Runtime 服務
@anchor{library/site doc}@anchor{495c}@anchor{library/site module-site}@anchor{cc}@anchor{library/site site-site-specific-configuration-hook}@anchor{495d}@anchor{library/site translation-repo}@anchor{495e}
@subsection @code{site} --- Site-specific configuration hook


@geindex module; site

`原始碼：'Lib/site.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/site.py}


__________________________________________________________________


`This module is automatically imported during initialization.' The automatic
import can be suppressed using the interpreter's @ref{13a9,,-S} option.

@geindex module（模組）;search（搜尋）;path（路徑）

Importing this module normally appends site-specific paths to the module search path
and adds @ref{2493,,callables}, including @ref{acb,,help()} to the built-in
namespace. However, Python startup option @ref{13a9,,-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{1fee,,main()} function.


在 3.3 版的變更: Importing the module used to trigger paths manipulation even when using
@ref{13a9,,-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{1f4,,free threading} build, and is
appended if @code{"t"} is present in the @ref{c50,,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{1f4,,Free threading} Python installations are
identified by the "t" suffix in the version-specific directory name, such as
@code{lib/python3.13t/}.



在 3.14 版的變更: @ref{cc,,site} is no longer responsible for updating @ref{3e6,,sys.prefix} and
@ref{3e9,,sys.exec_prefix} on @ref{476b,,虛擬環境}. This is
now done during the @ref{1849,,path initialization}. As a result,
under @ref{476b,,虛擬環境}, @ref{3e6,,sys.prefix} and
@ref{3e9,,sys.exec_prefix} no longer depend on the @ref{cc,,site} initialization,
and are therefore unaffected by @ref{13a9,,-S}.

@anchor{library/site site-virtual-environments-configuration}@anchor{476c}
When running under a @ref{476b,,virtual environment},
the @code{pyvenv.cfg} file in @ref{3e6,,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.

@geindex # （井字號）;comment（註解）
@geindex statement（陳述式）;import（引入）

A path configuration file is a file whose name has the form @code{`name'.pth}
and exists in one of the four directories mentioned above; its contents are
additional items (one per line) to be added to @code{sys.path}.  Non-existing items
are never added to @code{sys.path}, and no check is made that the item refers to a
directory rather than a file.  No item is added to @code{sys.path} more than
once.  Blank lines and lines beginning with @code{#} are skipped.  Lines starting
with @code{import} (followed by space or tab) are executed.

@cartouche
@quotation 備註 
An executable line in a @code{.pth} file is run at every Python startup,
regardless of whether a particular module is actually going to be used.
Its impact should thus be kept to a minimum.
The primary intended purpose of executable lines is to make the
corresponding module(s) importable
(load 3rd-party import hooks, adjust 
@geindex PATH
@geindex 環境變數; PATH
@code{PATH} etc).
Any other initialization is supposed to be done upon a module's
actual import, if and when it happens.
Limiting a code chunk to a single line is a deliberate measure
to discourage putting anything more complex here.
@end quotation
@end cartouche


在 3.13 版的變更: The @code{.pth} files are now decoded by UTF-8 at first and then by the
@ref{545,,locale encoding} if it fails.


@geindex package（套件）
@geindex path（路徑）;configuration（設定）;file（檔案）

For example, suppose @code{sys.prefix} and @code{sys.exec_prefix} are set to
@code{/usr/local}.  The Python X.Y library is then installed in
@code{/usr/local/lib/python`X.Y'}.  Suppose this has
a subdirectory @code{/usr/local/lib/python`X.Y'/site-packages} with three
subsubdirectories, @code{foo}, @code{bar} and @code{spam}, and two path
configuration files, @code{foo.pth} and @code{bar.pth}.  Assume
@code{foo.pth} contains the following:

@example
# foo package configuration

foo
bar
bletch
@end example

and @code{bar.pth} contains:

@example
# bar package configuration

bar
@end example

Then the following version-specific directories are added to
@code{sys.path}, in this order:

@example
/usr/local/lib/pythonX.Y/site-packages/bar
/usr/local/lib/pythonX.Y/site-packages/foo
@end example

Note that @code{bletch} is omitted because it doesn't exist; the @code{bar}
directory precedes the @code{foo} directory because @code{bar.pth} comes
alphabetically before @code{foo.pth}; and @code{spam} is omitted because it is
not mentioned in either path configuration file.

@menu
* sitecustomize:: 
* usercustomize:: 
* Readline configuration:: 
* 模組內容: 模組內容<10>. 
* 命令列介面: 命令列介面<13>. 

@end menu

@node sitecustomize,usercustomize,,site --- Site-specific configuration hook
@anchor{library/site module-sitecustomize}@anchor{cd}@anchor{library/site sitecustomize}@anchor{495f}
@subsubsection @code{sitecustomize}


@geindex module; sitecustomize

After these path manipulations, an attempt is made to import a module named
@ref{cd,,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{653,,ImportError} or its subclass
exception, and the exception's @ref{2594,,name}
attribute equals to @code{'sitecustomize'},
it is silently ignored.  If Python is started without output streams available, as
with @code{pythonw.exe} on Windows (which is used by default to start IDLE),
attempted output from @ref{cd,,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{114}@anchor{library/site usercustomize}@anchor{4960}
@subsubsection @code{usercustomize}


@geindex module; usercustomize

After this, an attempt is made to import a module named @ref{114,,usercustomize},
which can perform arbitrary user-specific customizations, if
@ref{4961,,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{1586,,-s}.  If this import fails with an @ref{653,,ImportError} or
its subclass exception, and the exception's @ref{2594,,name}
attribute equals to @code{'usercustomize'}, it is silently ignored.

Note that for some non-Unix systems, @code{sys.prefix} and @code{sys.exec_prefix} are
empty, and the path manipulations are skipped; however the import of
@ref{cd,,sitecustomize} and @ref{114,,usercustomize} is still attempted.

@node Readline configuration,模組內容<10>,usercustomize,site --- Site-specific configuration hook
@anchor{library/site readline-configuration}@anchor{4962}@anchor{library/site rlcompleter-config}@anchor{11c4}
@subsubsection Readline configuration


On systems that support @ref{bf,,readline}, this module will also import and
configure the @ref{c2,,rlcompleter} module, if Python is started in
@ref{441,,interactive mode} and without the @ref{13a9,,-S} option.
The default behavior is enable tab-completion and to use
@code{~/.python_history} as the history save file.  To disable it, delete (or
override) the @ref{11c3,,sys.__interactivehook__} attribute in your
@ref{cd,,sitecustomize} or @ref{114,,usercustomize} module or your
@geindex PYTHONSTARTUP
@geindex 環境變數; PYTHONSTARTUP
@ref{1b8,,PYTHONSTARTUP} file.


在 3.4 版的變更: Activation of rlcompleter and history was made automatic.


@node 模組內容<10>,命令列介面<13>,Readline configuration,site --- Site-specific configuration hook
@anchor{library/site module-contents}@anchor{4963}
@subsubsection 模組內容


@geindex PREFIXES (於 site 模組中)
@anchor{library/site site PREFIXES}@anchor{4964}
@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{4961}
@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{1586,,-s} or
@geindex PYTHONNOUSERSITE
@geindex 環境變數; PYTHONNOUSERSITE
@ref{1587,,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{1fed}
@deffn {資料} site.USER_SITE

Path to the user site-packages for the running Python.  Can be @code{None} if
@ref{1441,,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{151d}
@deffn {資料} site.USER_BASE

Path to the base directory for the user site-packages.  Can be @code{None} if
@ref{1440,,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{1ffe,,user installation scheme}.
See also 
@geindex PYTHONUSERBASE
@geindex 環境變數; PYTHONUSERBASE
@ref{1585,,PYTHONUSERBASE}.
@end deffn

@geindex main() (於 site 模組中)
@anchor{library/site site main}@anchor{1fee}
@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{13a9,,-S} flag.


在 3.3 版的變更: This function used to be called unconditionally.

@end deffn

@geindex addsitedir() (於 site 模組中)
@anchor{library/site site addsitedir}@anchor{2136}
@deffn {函式} site.addsitedir (sitedir, known_paths=None)

Add a directory to sys.path and process its @code{.pth} files.  Typically
used in @ref{cd,,sitecustomize} or @ref{114,,usercustomize} (see above).
@end deffn

@geindex getsitepackages() (於 site 模組中)
@anchor{library/site site getsitepackages}@anchor{143f}
@deffn {函式} site.getsitepackages ()

Return a list containing all global site-packages directories.


在 3.2 版被加入.

@end deffn

@geindex getuserbase() (於 site 模組中)
@anchor{library/site site getuserbase}@anchor{1440}
@deffn {函式} site.getuserbase ()

Return the path of the user base directory, @ref{151d,,USER_BASE}.  If it is not
initialized yet, this function will also set it, respecting
@geindex PYTHONUSERBASE
@geindex 環境變數; PYTHONUSERBASE
@ref{1585,,PYTHONUSERBASE}.


在 3.2 版被加入.

@end deffn

@geindex getusersitepackages() (於 site 模組中)
@anchor{library/site site getusersitepackages}@anchor{1441}
@deffn {函式} site.getusersitepackages ()

Return the path of the user-specific site-packages directory,
@ref{1fed,,USER_SITE}.  If it is not initialized yet, this function will also set
it, respecting @ref{151d,,USER_BASE}.  To determine if the user-specific
site-packages was added to @code{sys.path} @ref{4961,,ENABLE_USER_SITE} should be
used.


在 3.2 版被加入.

@end deffn

@node 命令列介面<13>,,模組內容<10>,site --- Site-specific configuration hook
@anchor{library/site command-line-interface}@anchor{4965}@anchor{library/site site-commandline}@anchor{4966}
@subsubsection 命令列介面


The @ref{cc,,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{3e2,,sys.path} on the standard output, followed by the value of
@ref{151d,,USER_BASE} and whether the directory exists, then the same thing for
@ref{1fed,,USER_SITE}, and finally the value of @ref{4961,,ENABLE_USER_SITE}.

@geindex site 命令列選項; --user-base
@anchor{library/site cmdoption-site-user-base}@anchor{4967}
@deffn {Option} @w{-}@w{-}user@w{-}base

Print the path to the user base directory.
@end deffn

@geindex site 命令列選項; --user-site
@anchor{library/site cmdoption-site-user-site}@anchor{4968}
@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{1ffb,,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 
@ref{1849,,sys.path 模組搜尋路徑的初始化} -- The initialization of @ref{3e2,,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 
請參閱 @ref{25,,concurrent.interpreters} 模組，它同樣揭露了核心的 runtime 功能。
@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 直譯器,引入模組,Python Runtime 服務,Python 標準函式庫 Standard Library
@anchor{library/custominterp doc}@anchor{4969}@anchor{library/custominterp custom-python-interpreters}@anchor{496a}@anchor{library/custominterp custominterp}@anchor{496b}@anchor{library/custominterp translation-repo}@anchor{496c}
@section 自訂 Python 直譯器


本章介紹的模組可用於編寫類似於 Python 交互式直譯器的介面。如果你需要一個在 Python 語言基礎上支援某些特殊功能的直譯器，可以參考 @ref{1b,,code} 模組。（ @ref{1d,,codeop} 模組屬於底層工具，用於支援編譯可能不完整的 Python 程式碼。）

本章節所描述的模組清單為：

@menu
* code: code --- 直譯器基底類別. 直譯器基底類別
* codeop: codeop --- 編譯 Python 程式碼. 編譯 Python 程式碼

@end menu

@node code --- 直譯器基底類別,codeop --- 編譯 Python 程式碼,,自訂 Python 直譯器
@anchor{library/code doc}@anchor{496d}@anchor{library/code code-interpreter-base-classes}@anchor{496e}@anchor{library/code module-code}@anchor{1b}
@subsection @code{code} --- 直譯器基底類別


@geindex module; code

`原始碼：'Lib/code.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/code.py}


__________________________________________________________________


@code{code} 模組提供在 Python 中實作讀取-求值-印出迴圈（read-eval-print loops）的設施。包含兩個類別和便利函式，可用於建立提供互動式直譯器提示的應用程式。

@geindex InteractiveInterpreter (code 中的類別)
@anchor{library/code code InteractiveInterpreter}@anchor{18aa}
@deffn {類別} code.InteractiveInterpreter (locals=None)

這個類別處理剖析和直譯器狀態（使用者的命名空間）；它不處理輸入緩衝、提示或輸入檔案命名（檔案名稱總是明確傳入）。可選的 `locals' 引數指定一個對映，作為執行程式碼的命名空間；它預設為新建立的字典，鍵 @code{'__name__'} 設為 @code{'__console__'} 而鍵 @code{'__doc__'} 會設為 @code{None}。

請注意，在 @code{InteractiveInterpreter} 實例下建立的函式和類別物件將屬於由 `locals' 指定的命名空間。只有當 `locals' 是現有模組的命名空間時，它們才會是可被 pickle 的。
@end deffn

@geindex InteractiveConsole (code 中的類別)
@anchor{library/code code InteractiveConsole}@anchor{26b3}
@deffn {類別} code.InteractiveConsole (locals=None, filename='<console>', local_exit=False)

近似地模擬出互動式 Python 直譯器的行為。這個類別建立在 @ref{18aa,,InteractiveInterpreter} 的基礎上，並加入使用熟悉的 @code{sys.ps1} 和 @code{sys.ps2} 的提示，以及輸入緩衝。如果 `local_exit' 為 true，控制台中的 @code{exit()} 和 @code{quit()} 將不會引發 @ref{f37,,SystemExit}，而是回傳到呼叫程式碼。


在 3.13 版的變更: 新增 `local_exit' 參數。

@end deffn

@geindex interact() (於 code 模組中)
@anchor{library/code code interact}@anchor{1809}
@deffn {函式} code.interact (banner=None, readfunc=None, local=None, exitmsg=None, local_exit=False)

執行 read-eval-print 迴圈的便利函式。這會建立一個 @ref{26b3,,InteractiveConsole} 的新實例，並設定 `readfunc' 以用於 @ref{496f,,InteractiveConsole.raw_input()} 方法（如有提供）。如果 `local' 有被提供，它會被傳給 @ref{26b3,,InteractiveConsole} 的建構函式以作為直譯器迴圈的預設命名空間。如果有提供 `local_exit'，它會被傳給 @ref{26b3,,InteractiveConsole} 構建函式。然後實例的 @ref{4970,,interact()} 方法會執行，並傳入 `banner' 和 `exitmsg' 以作為要使用的橫幅和退出訊息（如有提供）。控制台物件在使用後就會被丟棄。


在 3.6 版的變更: 新增 `exitmsg' 參數。



在 3.13 版的變更: 新增 `local_exit' 參數。

@end deffn

@geindex compile_command() (於 code 模組中)
@anchor{library/code code compile_command}@anchor{4971}
@deffn {函式} code.compile_command (source, filename='<input>', symbol='single')

這個函式對於想要模擬 Python 的直譯器主迴圈（即讀取-求值-印出迴圈）的程式很有用。最棘手的部分是判斷使用者何時輸入了一個不完整的命令，而這個命令可以透過輸入更多文字來完成（相對於完整的命令或語法錯誤）。這個函式`幾乎'總是做出與真正的直譯器主迴圈相同的判斷。

`source' 是來源字串；`filename' 是讀取來源的可選檔案名稱，預設為 @code{'<input>'}；`symbol' 是可選的文法 (grammar) 起始符號，其應為 @code{'single'}（預設值）、@code{'eval'} 或 @code{'exec'}。

如果命令完整且有效，則回傳程式碼物件（與 @code{compile(source,filename,symbol)} 相同）；如果命令不完整，則回傳 @code{None}；如果命令完整但包含語法錯誤，則引發 @ref{18e,,SyntaxError}，如果命令包含無效的字面值 (literal)，則引發 @ref{a78,,OverflowError} 或 @ref{2eb,,ValueError}。
@end deffn

@menu
* 互動式直譯器物件:: 
* 互動式控制台物件:: 

@end menu

@node 互動式直譯器物件,互動式控制台物件,,code --- 直譯器基底類別
@anchor{library/code interactive-interpreter-objects}@anchor{4972}@anchor{library/code interpreter-objects}@anchor{4973}
@subsubsection 互動式直譯器物件


@geindex runsource() (code.InteractiveInterpreter 的方法)
@anchor{library/code code InteractiveInterpreter runsource}@anchor{4974}
@deffn {方法} InteractiveInterpreter.runsource (source, filename='<input>', symbol='single')

在直譯器中編譯並執行某些原始碼。引數與 @ref{4971,,compile_command()} 相同；`filename' 的預設值是 @code{'<input>'}，`symbol' 的預設值是 @code{'single'}。有幾種情況會發生：


@itemize *

@item 
輸入不正確；@ref{4971,,compile_command()} 會引發例外（@ref{18e,,SyntaxError} 或 @ref{a78,,OverflowError}）。語法回溯 (syntax traceback) 會透過呼叫 @ref{4975,,showsyntaxerror()} 方法來印出。@ref{4974,,runsource()} 會回傳 @code{False}。

@item 
輸入不完整，需要更多輸入；@ref{4971,,compile_command()} 回傳了 @code{None}。@ref{4974,,runsource()} 會回傳 @code{True}。

@item 
輸入完整；@ref{4971,,compile_command()} 回傳一個程式碼物件。程式碼會透過呼叫 @ref{4976,,runcode()} 執行（它也會處理執行時的例外，除 @ref{f37,,SystemExit} 以外）。@ref{4974,,runsource()} 會回傳 @code{False}。
@end itemize

回傳值可用來決定是使用 @code{sys.ps1} 還是 @code{sys.ps2} 以提示下一列。
@end deffn

@geindex runcode() (code.InteractiveInterpreter 的方法)
@anchor{library/code code InteractiveInterpreter runcode}@anchor{4976}
@deffn {方法} InteractiveInterpreter.runcode (code)

執行程式碼物件。當例外發生時，會呼叫 @ref{fc9,,showtraceback()} 來顯示回溯。除了 @ref{f37,,SystemExit} 允許繼續傳播之外，所有的例外都會被捕獲。

關於 @ref{bbc,,KeyboardInterrupt} 的注意事項：此例外可能發生在此程式碼的其他地方，而且不一定會被捕獲到。呼叫者應該準備好處理它。
@end deffn

@geindex showsyntaxerror() (code.InteractiveInterpreter 的方法)
@anchor{library/code code InteractiveInterpreter showsyntaxerror}@anchor{4975}
@deffn {方法} InteractiveInterpreter.showsyntaxerror (filename=None)

顯示剛剛發生的語法錯誤。這不會顯示堆疊追蹤 (stack trace)，因為語法錯誤沒有堆疊追蹤。如果給出 `filename'，它會被塞入例外，而不是 Python 剖析器提供的預設檔案名稱，因為它從字串讀取時總是使用 @code{'<string>'}。輸出會由 @ref{4977,,write()} 方法寫入。
@end deffn

@geindex showtraceback() (code.InteractiveInterpreter 的方法)
@anchor{library/code code InteractiveInterpreter showtraceback}@anchor{fc9}
@deffn {方法} InteractiveInterpreter.showtraceback ()

顯示剛剛發生的例外。我們移除第一個堆疊項目，因為它在直譯器物件的實作範圍內。輸出由 @ref{4977,,write()} 方法寫入。


在 3.5 版的變更: 會顯示完整的連鎖回溯記錄，而不只是主要回溯。

@end deffn

@geindex write() (code.InteractiveInterpreter 的方法)
@anchor{library/code code InteractiveInterpreter write}@anchor{4977}
@deffn {方法} InteractiveInterpreter.write (data)

寫入字串到標準錯誤串流 (@code{sys.stderr})。衍生類別應覆寫此功能，以根據需求提供適當的輸出處理。
@end deffn

@node 互動式控制台物件,,互動式直譯器物件,code --- 直譯器基底類別
@anchor{library/code console-objects}@anchor{4978}@anchor{library/code interactive-console-objects}@anchor{4979}
@subsubsection 互動式控制台物件


@ref{26b3,,InteractiveConsole} 類別是 @ref{18aa,,InteractiveInterpreter} 的子類別，因此提供了所有直譯器物件的方法以及下列新增的功能。

@geindex interact() (code.InteractiveConsole 的方法)
@anchor{library/code code InteractiveConsole interact}@anchor{4970}
@deffn {方法} InteractiveConsole.interact (banner=None, exitmsg=None)

近似地模擬互動式 Python 控制台。可選的 `banner' 引數指定在第一次互動之前要印出的横幅；預設會印出類似標準 Python 直譯器所列印的横幅，接著是控制台物件在括弧中的類別名稱 (以免與真正的直譯器混淆 -- 因為它是如此接近！)。

可選的 `exitmsg' 引數指定退出時列印的退出訊息。傳遞空字串以抑制退出訊息。如果沒有給 `exitmsg' 或 @code{None}，則會印出預設訊息。


在 3.4 版的變更: 若要抑制印出任何橫幅，請傳入空字串。



在 3.6 版的變更: 退出時印出退出訊息。

@end deffn

@geindex push() (code.InteractiveConsole 的方法)
@anchor{library/code code InteractiveConsole push}@anchor{497a}
@deffn {方法} InteractiveConsole.push (line)

推送一行原始文字到直譯器。這一行不應該有尾部換行符號；它可能有內部換行符號。這行文字會被附加到緩衝區，並且直譯器的 @ref{4974,,runsource()} 方法會被呼叫，並以緩衝區的串接內容做為原始碼。如果這表示命令已執行或無效，緩衝區會被重設；否則，命令會不完整，且緩衝區會保持該行被附加後的樣子。如果需要更多的輸入，回傳值是 @code{True}，如果該行已經以某種方式處理，回傳值是 @code{False}（這與 @code{runsource()} 相同）。
@end deffn

@geindex resetbuffer() (code.InteractiveConsole 的方法)
@anchor{library/code code InteractiveConsole resetbuffer}@anchor{497b}
@deffn {方法} InteractiveConsole.resetbuffer ()

從輸入緩衝區移除任何未處理的原始文字。
@end deffn

@geindex raw_input() (code.InteractiveConsole 的方法)
@anchor{library/code code InteractiveConsole raw_input}@anchor{496f}
@deffn {方法} InteractiveConsole.raw_input (prompt='@w{'})

寫入一個提示並讀取一行。回傳的行不包括尾部的換行符號。當使用者輸入 EOF 鍵序時，會引發 @ref{14da,,EOFError}。基底實作會從 @code{sys.stdin} 讀取；子類別可以用不同的實作替代。
@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 --- 編譯 Python 程式碼,,code --- 直譯器基底類別,自訂 Python 直譯器
@anchor{library/codeop doc}@anchor{497c}@anchor{library/codeop codeop-compile-python-code}@anchor{497d}@anchor{library/codeop module-codeop}@anchor{1d}@anchor{library/codeop translation-repo}@anchor{497e}
@subsection @code{codeop} --- 編譯 Python 程式碼


@geindex module; codeop

`原始碼：'Lib/codeop.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/codeop.py}


__________________________________________________________________


@ref{1d,,codeop} 模組提供了可以模擬 Python read-eval-print 循環的工具程式 (utilities)，就像在 @ref{1b,,code} 模組中所做的那樣。因此你可能不想直接使用該模組；如果你想在程式中包含這樣的循環，你可能需要使用 @ref{1b,,code} 模組。

這個任務有兩個部分：


@enumerate 

@item 
能夠判斷一列輸入是否完成了一項 Python 陳述式：簡而言之，判斷接下來是列印 '@code{>>>}' 還是 '@code{...}'。

@item 
記住使用者輸入了哪些未來陳述式，以便後續輸入可以在這些陳述式生效的情況下進行編譯。
@end enumerate

@ref{1d,,codeop} 模組提供了一種完成上述每項任務的方法，以及同時完成這兩項任務的方法。

只做前者：

@geindex compile_command() (於 codeop 模組中)
@anchor{library/codeop codeop compile_command}@anchor{1a82}
@deffn {函式} codeop.compile_command (source, filename='<input>', symbol='single')

嘗試編譯 `source'，它應該是 Python 程式碼的字串，如果 `source' 是有效的 Python 程式碼，則回傳一個程式碼物件 (code object)。在這種情況下，程式碼物件的檔案名稱屬性將為 `filename'，預設為 @code{'<input>'}。如果 `source' 不是有效的 Python 程式碼，而是有效 Python 程式碼的前綴，則回傳 @code{None}。

如果 `source' 有問題，就會引發例外。如果存在無效的 Python 語法則會引發 @ref{18e,,SyntaxError}；如果存在無效的文字 (literal)，則會引發 @ref{a78,,OverflowError} 或 @ref{2eb,,ValueError}。

`symbol' 引數決定 `source' 是否編譯為陳述式（@code{'single'}，為預設值）、為@ref{2aae,,陳述式}序列 (@code{'exec'}) 或為@ref{2281,,運算式} (@code{'eval'})。任何其他值都會導致引發 @ref{2eb,,ValueError}。

@cartouche
@quotation 備註 
剖析器 (parser) 有可能（但通常不會）在到達原始碼的結尾之前停止剖析並獲得成功的結果；在這種情況下，尾隨符號可能會被忽略而不是導致錯誤。例如，反斜線後面加上兩個換行符號後可以是任意的無意義符號。這個問題在未來會因為剖析器 API 的改善而被解決。
@end quotation
@end cartouche
@end deffn

@geindex Compile (codeop 中的類別)
@anchor{library/codeop codeop Compile}@anchor{497f}
@deffn {類別} codeop.Compile

此類別的實例具有 @ref{773,,__call__()} 方法，其簽名與內建函式 @ref{4ac,,compile()} 相同，區別在於如果實例編譯包含 @ref{0,,__future__} 陳述式的程式文本，實例會「記住」並使用該陳述式開始編譯所有後續程式文本。
@end deffn

@geindex CommandCompiler (codeop 中的類別)
@anchor{library/codeop codeop CommandCompiler}@anchor{4980}
@deffn {類別} codeop.CommandCompiler

此類別的實例具有 @ref{773,,__call__()} 方法，其簽名與內建函式 @ref{1a82,,compile_command()} 相同，區別在於如果實例編譯包含 @ref{0,,__future__} 陳述式的程式文本，實例會「記住」並使用該陳述式開始編譯所有後續程式文本。
@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 引入模組,Python 語言服務,自訂 Python 直譯器,Python 標準函式庫 Standard Library
@anchor{library/modules doc}@anchor{4981}@anchor{library/modules importing-modules}@anchor{4982}@anchor{library/modules modules}@anchor{4983}@anchor{library/modules translation-repo}@anchor{4984}
@section 引入模組


本章節所描述的模組提供了引入其他 Python 模組的新方法，以及用於自訂引入過程的 hook。

本章節所描述的完整模組列表為：

@menu
* zipimport: zipimport --- 從 Zip 封存檔案匯入模組. 從 Zip 封存檔案匯入模組
* pkgutil: pkgutil --- 套件擴充工具程式. 套件擴充工具程式
* modulefinder: modulefinder --- 搜尋腳本所使用的模組. 搜尋腳本所使用的模組
* runpy: runpy --- 定位並執行 Python 模組. 定位並執行 Python 模組
* importlib: importlib --- import 的實作. import 的實作
* importlib.resources: importlib resources -- 套件資源的讀取、開啟與存取. 套件資源的讀取、開啟與存取
* importlib.resources.abc: importlib resources abc -- 資源的抽象基底類別. 資源的抽象基底類別
* importlib.metadata: importlib metadata -- 存取套件的元資料. 存取套件的元資料
* sys.path 模組搜尋路徑的初始化: sys path 模組搜尋路徑的初始化. 

@end menu

@node zipimport --- 從 Zip 封存檔案匯入模組,pkgutil --- 套件擴充工具程式,,引入模組
@anchor{library/zipimport doc}@anchor{4985}@anchor{library/zipimport module-zipimport}@anchor{138}@anchor{library/zipimport zipimport-import-modules-from-zip-archives}@anchor{4986}
@subsection @code{zipimport} --- 從 Zip 封存檔案匯入模組


@geindex module; zipimport

`原始碼：'Lib/zipimport.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/zipimport.py}


__________________________________________________________________


此模組新增了從 ZIP 格式封存檔案中引入 Python 模組（@code{*.py}、@code{*.pyc}）和套件的能力。通常不需要明確地使用 @ref{138,,zipimport} 模組；對於 @ref{3e2,,sys.path} 中指向 ZIP 封存檔案路徑的項目，內建的 @ref{7f1,,import} 機制會自動使用它。

通常 @ref{3e2,,sys.path} 是一個由目錄名稱字串組成的串列。此模組也允許 @ref{3e2,,sys.path} 的一個項目是命名 ZIP 封存檔案的字串。ZIP 封存檔案可以包含子目錄結構以支援套件引入，並且可以指定封存檔案內的路徑以僅從子目錄中引入。例如路徑 @code{example.zip/lib/} 將只會從封存檔案內的 @code{lib/} 子目錄中引入。

ZIP 封存檔案中可以存在任何檔案，但引入器只會對 @code{.py} 和 @code{.pyc} 檔案起作用。不允許從 ZIP 引入動態模組（@code{.pyd}、@code{.so}）。請注意，如果封存檔案只包含 @code{.py} 檔案，Python 將不會試圖透過新增對應的 @code{.pyc} 檔案來修改封存檔案，這意味著如果 ZIP 封存檔案不包含 @code{.pyc} 檔案，引入可能會相當慢。


在 3.13 版的變更: 支援 ZIP64。



在 3.8 版的變更: 在過去，不支援帶有封存檔案註解的 ZIP 封存檔案。



@subsubheading 也參考



@table @asis

@item PKZIP Application Note@footnote{https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT}

由 ZIP 格式和所用演算法的創造者 Phil Katz 編寫的關於 ZIP 檔案格式的文件。

@geindex Python Enhancement Proposals; PEP 273

@item PEP 273@footnote{https://peps.python.org/pep-0273/} - 從 Zip 封存檔案引入模組

由 James C. Ahlstrom 編寫，他也提供了一個實作。Python 2.3 遵循 
@geindex Python Enhancement Proposals; PEP 273
PEP 273@footnote{https://peps.python.org/pep-0273/} 中的規範，但使用由 Just van Rossum 編寫的實作，該實作使用了 
@geindex Python Enhancement Proposals; PEP 302
PEP 302@footnote{https://peps.python.org/pep-0302/} 中描述的引入掛鉤。

@item @ref{7b,,importlib} - 引入機制的實作

提供所有引入器要實作的相關協定的套件。
@end table


此模組定義了一個例外：

@geindex ZipImportError
@anchor{library/zipimport zipimport ZipImportError}@anchor{4987}
@deffn {例外} zipimport.ZipImportError

由 zipimporter 物件引發的例外。它是 @ref{653,,ImportError} 的子類別，所以也可以被捕捉為 @ref{653,,ImportError}。
@end deffn

@menu
* zipimporter 物件:: 
* 範例: 範例<46>. 

@end menu

@node zipimporter 物件,範例<46>,,zipimport --- 從 Zip 封存檔案匯入模組
@anchor{library/zipimport id1}@anchor{4988}@anchor{library/zipimport zipimporter-objects}@anchor{4989}
@subsubsection zipimporter 物件


@ref{498a,,zipimporter} 是用於引入 ZIP 檔案的類別。

@geindex zipimporter (zipimport 中的類別)
@anchor{library/zipimport zipimport zipimporter}@anchor{498a}
@deffn {類別} zipimport.zipimporter (archivepath)

建立一個新的 zipimporter 實例。`archivepath' 必須是 ZIP 檔案的路徑，或是 ZIP 檔案內的特定路徑。例如，@code{foo/bar.zip/lib} 的 `archivepath' 將會在 ZIP 檔案 @code{foo/bar.zip} 內的 @code{lib} 目錄中尋找模組（如果該目錄存在的話）。

如果 `archivepath' 未指向一個有效的 ZIP 封存檔案，則會引發 @ref{4987,,ZipImportError}。


在 3.12 版的變更: 在 3.10 版中已棄用的 @code{find_loader()} 和 @code{find_module()} 方法現已被移除。請改用 @ref{a57,,find_spec()}。


@geindex create_module() (zipimport.zipimporter 的方法)
@anchor{library/zipimport zipimport zipimporter create_module}@anchor{a58}
@deffn {方法} create_module (spec)

@ref{ea7,,importlib.abc.Loader.create_module()} 的實作，回傳 @ref{87e,,None} 以明確請求預設語意。


在 3.10 版被加入.

@end deffn

@geindex exec_module() (zipimport.zipimporter 的方法)
@anchor{library/zipimport zipimport zipimporter exec_module}@anchor{338}
@deffn {方法} exec_module (module)

@ref{a63,,importlib.abc.Loader.exec_module()} 的實作。


在 3.10 版被加入.

@end deffn

@geindex find_spec() (zipimport.zipimporter 的方法)
@anchor{library/zipimport zipimport zipimporter find_spec}@anchor{a57}
@deffn {方法} find_spec (fullname, target=None)

@ref{a65,,importlib.abc.PathEntryFinder.find_spec()} 的一個實作。


在 3.10 版被加入.

@end deffn

@geindex get_code() (zipimport.zipimporter 的方法)
@anchor{library/zipimport zipimport zipimporter get_code}@anchor{498b}
@deffn {方法} get_code (fullname)

回傳指定模組的程式碼物件。如果模組無法被引入，則引發 @ref{4987,,ZipImportError}。
@end deffn

@geindex get_data() (zipimport.zipimporter 的方法)
@anchor{library/zipimport zipimport zipimporter get_data}@anchor{498c}
@deffn {方法} get_data (pathname)

回傳與 `pathname' 相關的資料。如果找不到檔案，則引發 @ref{2c0,,OSError}。


在 3.3 版的變更: 過去會引發 @ref{124e,,IOError}，現在它是 @ref{2c0,,OSError} 的別名。

@end deffn

@geindex get_filename() (zipimport.zipimporter 的方法)
@anchor{library/zipimport zipimport zipimporter get_filename}@anchor{498d}
@deffn {方法} get_filename (fullname)

回傳如果指定模組被引入時 @code{__file__} 會被設定的值。如果模組無法被引入，則引發 @ref{4987,,ZipImportError}。


在 3.1 版被加入.

@end deffn

@geindex get_source() (zipimport.zipimporter 的方法)
@anchor{library/zipimport zipimport zipimporter get_source}@anchor{498e}
@deffn {方法} get_source (fullname)

回傳指定模組的原始碼。如果找不到模組，則引發 @ref{4987,,ZipImportError}；如果封存檔案包含該模組但沒有其原始碼，則回傳 @ref{87e,,None}。
@end deffn

@geindex is_package() (zipimport.zipimporter 的方法)
@anchor{library/zipimport zipimport zipimporter is_package}@anchor{498f}
@deffn {方法} is_package (fullname)

如果由 `fullname' 指定的模組是一個套件，則回傳 @code{True}。如果找不到模組，則引發 @ref{4987,,ZipImportError}。
@end deffn

@geindex load_module() (zipimport.zipimporter 的方法)
@anchor{library/zipimport zipimport zipimporter load_module}@anchor{337}
@deffn {方法} load_module (fullname)

載入由 `fullname' 指定的模組。`fullname' 必須是完整限定（以點分隔）的模組名稱。成功時回傳引入的模組，失敗時引發 @ref{4987,,ZipImportError}。


Deprecated since version 3.10, will be removed in version 3.15: 請改用 @ref{338,,exec_module()}。

@end deffn

@geindex invalidate_caches() (zipimport.zipimporter 的方法)
@anchor{library/zipimport zipimport zipimporter invalidate_caches}@anchor{a59}
@deffn {方法} invalidate_caches ()

清除關於在 ZIP 封存檔案中找到的檔案資訊的內部快取。


在 3.10 版被加入.

@end deffn

@geindex archive (zipimport.zipimporter 的屬性)
@anchor{library/zipimport zipimport zipimporter archive}@anchor{4990}
@deffn {屬性} archive

引入器關聯的 ZIP 檔案的檔名，不包含可能的子路徑。
@end deffn

@geindex prefix (zipimport.zipimporter 的屬性)
@anchor{library/zipimport zipimport zipimporter prefix}@anchor{4991}
@deffn {屬性} prefix

在 ZIP 檔案內搜尋模組的子路徑。對於指向 ZIP 檔案根目錄的 zipimporter 物件，這是一個空字串。
@end deffn

@ref{4990,,archive} 和 @ref{4991,,prefix} 屬性（attribute），當用斜線組合時，等於給予 @ref{498a,,zipimporter} 建構函式的原始 `archivepath' 引數。
@end deffn

@node 範例<46>,,zipimporter 物件,zipimport --- 從 Zip 封存檔案匯入模組
@anchor{library/zipimport examples}@anchor{4992}@anchor{library/zipimport zipimport-examples}@anchor{4993}
@subsubsection 範例


這是一個從 ZIP 封存檔案引入模組的範例——請注意，@ref{138,,zipimport} 模組並未被明確使用。

@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
>>> # 將封存檔案新增到系統路徑的最前面
>>> 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 --- 套件擴充工具程式,modulefinder --- 搜尋腳本所使用的模組,zipimport --- 從 Zip 封存檔案匯入模組,引入模組
@anchor{library/pkgutil doc}@anchor{4994}@anchor{library/pkgutil module-pkgutil}@anchor{ae}@anchor{library/pkgutil pkgutil-package-extension-utility}@anchor{4995}@anchor{library/pkgutil translation-repo}@anchor{4996}
@subsection @code{pkgutil} --- 套件擴充工具程式


@geindex module; pkgutil

`原始碼：'Lib/pkgutil.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/pkgutil.py}


__________________________________________________________________


此模組提供了引入系統 (import system) 的工具程式，特別是套件相關支援。

@geindex ModuleInfo (pkgutil 中的類別)
@anchor{library/pkgutil pkgutil ModuleInfo}@anchor{f43}
@deffn {類別} pkgutil.ModuleInfo (module_finder, name, ispkg)

一個包含模組資訊之簡短摘要的附名元組 (namedtuple)。


在 3.6 版被加入.

@end deffn

@geindex extend_path() (於 pkgutil 模組中)
@anchor{library/pkgutil pkgutil extend_path}@anchor{188a}
@deffn {函式} pkgutil.extend_path (path, name)

擴充組成一個套件之模組的搜尋路徑。預期用法是將以下程式碼放入套件的 @code{__init__.py}：

@example
from pkgutil import extend_path
__path__ = extend_path(__path__, __name__)
@end example

對於 @ref{3e2,,sys.path} 上具有與套件名稱相符的子目錄的每個目錄，將該子目錄新增至套件的 @ref{1f1b,,__path__} 中。如果想要將單一邏輯套件的不同部分給分配到多個目錄時，這會非常有用。

它還會尋找 @code{*.pkg} 檔案，其中開頭的 @code{*} 與 `name' 引數相符。此功能類似於 @code{*.pth} 檔案（更多資訊請參閱 @ref{cc,,site} 模組），但他不特別處理以 @code{import} 為開頭的行。@code{*.pkg} 檔案從表面上看是受信任的：除了跳過空行和備註之外，在 @code{*.pkg} 檔案中找到的所有條目都將新增到路徑中，無論它們是否存在於檔案系統。（這是一個功能。）

如果輸入路徑不是串列（像是凍結套件 (frozen package) 的情況），它將原封不動地被回傳。輸入路徑不會被修改；而是回傳擴充後的副本。僅將項目附加到副本的尾端。

@ref{3e2,,sys.path} 被假設是一個序列，@ref{3e2,,sys.path} 中的項目裡，若不是代表現存目錄的字串則將被忽略。@ref{3e2,,sys.path} 上用作檔案名稱時導致錯誤的 Unicode 項目可能會導致此函式引發例外（與 @ref{bfc,,os.path.isdir()} 行為一致）。
@end deffn

@geindex get_importer() (於 pkgutil 模組中)
@anchor{library/pkgutil pkgutil get_importer}@anchor{4997}
@deffn {函式} pkgutil.get_importer (path_item)

取得給定之 `path_item' 的 @ref{221c,,finder}。

如果回傳的尋檢器 (finder) 是由路徑勾點 (path hook) 所新建立的，則它會被快取在 @ref{7f3,,sys.path_importer_cache} 中。

如果需要重新掃描 @ref{121f,,sys.path_hooks}，可以手動清除快取（或部分快取）。


在 3.3 版的變更: 更新為直接基於 @ref{7b,,importlib}，而不是依賴套件內部 
@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{139a}
@deffn {函式} pkgutil.iter_importers (fullname='@w{'})

yield 給定模組名稱的 @ref{221c,,finder} 物件。

如果 `fullname' 包含 @code{'.'}，則尋檢器將針對包含 `fullname' 的套件，否則它們全部會是在頂層被註冊的尋檢器（即 @ref{f22,,sys.meta_path} 和 @ref{121f,,sys.path_hooks} 上的尋檢器）。

如果指定的模組位於套件中，則作為呼叫此函式的副作用 (side effect) ，該套件會被引入。

如果未指定模組名稱，則會產生所有頂層尋檢器。


在 3.3 版的變更: 更新為直接基於 @ref{7b,,importlib}，而不是依賴套件內部 
@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{f42}
@deffn {函式} pkgutil.iter_modules (path=None, prefix='@w{'})

yield `path' 上所有子模組的 @ref{f43,,ModuleInfo}，或者如果 `path' 為 @code{None}，則產生 @ref{3e2,,sys.path} 上的所有頂層模組。

`path' 應該是 @code{None} 或用來尋找模組的路徑串列。

`prefix' 是在輸出的每個模組名稱前面的輸出字串。

@cartouche
@quotation 備註 
僅適用於有定義 @code{iter_modules()} 方法的 @ref{221c,,finder}。此介面並非是標準的，因此該模組還提供了 @ref{126d,,importlib.machinery.FileFinder} 和 @ref{498a,,zipimport.zipimporter} 的實作。
@end quotation
@end cartouche


在 3.3 版的變更: 更新為直接基於 @ref{7b,,importlib}，而不是依賴套件內部 
@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{df4}
@deffn {函式} pkgutil.walk_packages (path=None, prefix='@w{'}, onerror=None)

為 `path' 上的所有模組遞迴 yield 出 @ref{f43,,ModuleInfo}，或如果 `path' 為 @code{None} 則 yield 所有可存取的模組。

`path' 應該是 @code{None} 或用來尋找模組的路徑串列。

`prefix' 是在輸出的每個模組名稱前面的輸出字串。

請注意，此函式必須引入給定之 `path' 上的所有`套件'（`不是'所有模組！），以便存取 @code{__path__} 屬性來尋找子模組。

`onerror' 是一個函式，如果在嘗試引入套件時發生任何例外，則使用一個引數（正在引入之套件的名稱）來呼叫函式。如果未提供 `onerror' 函式，則會捕獲並忽略 @ref{653,,ImportError}，同時傳播所有其他例外並終止搜尋。

範例：

@example
# 列出 Python 可存取的所有模組
walk_packages()

# 列出 ctypes 的所有子模組
walk_packages(ctypes.__path__, ctypes.__name__ + '.')
@end example

@cartouche
@quotation 備註 
僅適用於有定義 @code{iter_modules()} 方法的 @ref{221c,,finder}。此介面並非是標準的，因此該模組還提供了 @ref{126d,,importlib.machinery.FileFinder} 和 @ref{498a,,zipimport.zipimporter} 的實作。
@end quotation
@end cartouche


在 3.3 版的變更: 更新為直接基於 @ref{7b,,importlib}，而不是依賴套件內部 
@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{4998}
@deffn {函式} pkgutil.get_data (package, resource)

從套件中取得資源。

這是 @ref{1978,,loader} @ref{4999,,get_data} API 的包裝器。`package' 引數應該是採用標準模組格式 (@code{foo.bar}) 的套件名稱。`resource' 引數應為相對檔案名稱的形式，並使用 @code{/} 作為路徑分隔符號。不允許使用父目錄名稱 @code{..}，也不允許使用根目錄名稱（以 @code{/} 開頭）。

該函式回傳一個二進位字串，它是指定資源的內容。

對於位於檔案系統中且已被引入過的套件，這大致相當於：

@example
d = os.path.dirname(sys.modules[package].__file__)
data = open(os.path.join(d, resource), 'rb').read()
@end example

如果無法定位或載入套件，或者它使用不支援 @ref{4999,,get_data} 的 @ref{1978,,loader} 則回傳 @code{None}。特別是@ref{2b2,,命名空間套件}的 @ref{1978,,loader} 不支援 @ref{4999,,get_data}。
@end deffn

@geindex resolve_name() (於 pkgutil 模組中)
@anchor{library/pkgutil pkgutil resolve_name}@anchor{499a}
@deffn {函式} pkgutil.resolve_name (name)

將名稱解析為物件。

標準函式庫中的許多地方都使用了此功能（請參閱 bpo-12915@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12915}），且相同功能也被用於擁有廣大使用者的第三方套件，如 setuptools、Django 和 Pyramid。

`name' 預期要是以下格式之一的字串，其中 W 是有效 Python 識別字的簡寫，而點 (dot) 代表這些偽正規表示式 (pseudo-regex) 中的字面句點 (literal period)：


@itemize *

@item 
@code{W(.W)*}

@item 
@code{W(.W)*:(W(.W)*)?}
@end itemize

第一種形式僅是為了要向後相容。它假設點名稱 (dotted name) 的某些部分是一個套件，其餘部分是該套件內某處的物件，其可能巢狀地存在於 (nested) 其他物件內。由於無法透過檢查 (inspection) 來推斷出套件停止的位置和物件層次結構的開始位置，因此必須使用此形式來重複嘗試引入。

在第二種形式中，呼叫者透過使用一個冒號來明確標明分隔點：冒號左側的點名稱是要引入的套件，右側的點名稱是該套件內的物件層次結構。這種形式只需要一次引入。如果它以冒號結尾，則回傳一個模組物件。

此函式會回傳一個物件（可能是一個模組），或引發以下其中一個例外：

@ref{2eb,,ValueError} -- 如果 `name' 不是可辨識的格式。

@ref{653,,ImportError} -- 如果在不應該失敗的情況下引入失敗。

@ref{5e8,,AttributeError} -- 如果在遍歷引入套件中的物件層次結構以取得所需物件時發生失敗。


在 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 modulefinder --- 搜尋腳本所使用的模組,runpy --- 定位並執行 Python 模組,pkgutil --- 套件擴充工具程式,引入模組
@anchor{library/modulefinder doc}@anchor{499b}@anchor{library/modulefinder module-modulefinder}@anchor{95}@anchor{library/modulefinder modulefinder-find-modules-used-by-a-script}@anchor{499c}@anchor{library/modulefinder translation-repo}@anchor{499d}
@subsection @code{modulefinder} --- 搜尋腳本所使用的模組


@geindex module; modulefinder

`原始碼：'Lib/modulefinder.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/modulefinder.py}


__________________________________________________________________


此模組提供了一個 @ref{1cae,,ModuleFinder} 類別，可用於確定腳本引入的模組集合。@code{modulefinder.py} 也可以作為腳本運行，其將 Python 腳本的檔案名稱作為它的引數，並在之後會列印出引入模組的報告。

@geindex AddPackagePath() (於 modulefinder 模組中)
@anchor{library/modulefinder modulefinder AddPackagePath}@anchor{499e}
@deffn {函式} modulefinder.AddPackagePath (pkg_name, path)

記錄在指定的 `path' 中可以找到名為 `pkg_name' 的套件。
@end deffn

@geindex ReplacePackage() (於 modulefinder 模組中)
@anchor{library/modulefinder modulefinder ReplacePackage}@anchor{499f}
@deffn {函式} modulefinder.ReplacePackage (oldname, newname)

允許指定名為 `oldname' 的模組實際上是名為 `newname' 的套件。
@end deffn

@geindex ModuleFinder (modulefinder 中的類別)
@anchor{library/modulefinder modulefinder ModuleFinder}@anchor{1cae}
@deffn {類別} modulefinder.ModuleFinder (path=None, debug=0, excludes=[], replace_paths=[])

此類別提供 @ref{49a0,,run_script()} 和 @ref{49a1,,report()} 方法來決定腳本引入的模組集合。`path' 可以是搜尋模組的目錄串列；如果未指定，則使用 @code{sys.path}。`debug' 設定偵錯等級；較高的值可使類別列印有關其即將執行之操作的偵錯訊息。`excludes' 是要從分析中排除的模組名稱串列。`replace_paths' 是將在模組路徑中替換的 @code{(oldpath, newpath)} 元組串列。

@geindex report() (modulefinder.ModuleFinder 的方法)
@anchor{library/modulefinder modulefinder ModuleFinder report}@anchor{49a1}
@deffn {方法} report ()

將報告列印到標準輸出，其中列出了腳本引入的模組及其路徑，以及丟失或似乎丟失的模組。
@end deffn

@geindex run_script() (modulefinder.ModuleFinder 的方法)
@anchor{library/modulefinder modulefinder ModuleFinder run_script}@anchor{49a0}
@deffn {方法} run_script (pathname)

分析 `pathname' 檔案的內容，該檔案必須包含 Python 程式碼。
@end deffn

@geindex modules (modulefinder.ModuleFinder 的屬性)
@anchor{library/modulefinder modulefinder ModuleFinder modules}@anchor{49a2}
@deffn {屬性} modules

將模組名稱對應到模組的字典。請參閱 @ref{49a3,,ModuleFinder 的用法範例}。
@end deffn
@end deffn

@menu
* ModuleFinder 的用法範例:: 

@end menu

@node ModuleFinder 的用法範例,,,modulefinder --- 搜尋腳本所使用的模組
@anchor{library/modulefinder example-usage-of-modulefinder}@anchor{49a4}@anchor{library/modulefinder modulefinder-example}@anchor{49a3}
@subsubsection @code{ModuleFinder} 的用法範例


將被分析的腳本 (bacon.py)：

@example
import re, itertools

try:
    import baconhameggs
except ImportError:
    pass

try:
    import guido.python.ham
except ImportError:
    pass
@end example

將輸出 bacon.py 報告的腳本：

@example
from modulefinder import ModuleFinder

finder = ModuleFinder()
finder.run_script('bacon.py')

print('載入模組:')
for name, mod in finder.modules.items():
    print('%s: ' % name, end='@w{'})
    print(','.join(list(mod.globalnames.keys())[:3]))

print('-'*50)
print('模組沒有被引入:')
print('\n'.join(finder.badmodules.keys()))
@end example

範例輸出（可能因架構而異）：

@example
載入模組:
_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
---------------------------------------------------
模組沒有被引入:
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 --- 定位並執行 Python 模組,importlib --- import 的實作,modulefinder --- 搜尋腳本所使用的模組,引入模組
@anchor{library/runpy doc}@anchor{49a5}@anchor{library/runpy module-runpy}@anchor{c3}@anchor{library/runpy runpy-locating-and-executing-python-modules}@anchor{49a6}@anchor{library/runpy translation-repo}@anchor{49a7}
@subsection @code{runpy} --- 定位並執行 Python 模組


@geindex module; runpy

`原始碼：'Lib/runpy.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/runpy.py}


__________________________________________________________________


The @ref{c3,,runpy} module is used to locate and run Python modules without
importing them first. Its main use is to implement the @ref{23c,,-m} command
line switch that allows scripts to be located using the Python module
namespace rather than the filesystem.

Note that this is `not' a sandbox module - all code is executed in the
current process, and any side effects (such as cached imports of other
modules) will remain in place after the functions have returned.

Furthermore, any functions and classes defined by the executed code are not
guaranteed to work correctly after a @ref{c3,,runpy} function has returned.
If that limitation is not acceptable for a given use case, @ref{7b,,importlib}
is likely to be a more suitable choice than this module.

The @ref{c3,,runpy} module provides two functions:

@geindex run_module() (於 runpy 模組中)
@anchor{library/runpy runpy run_module}@anchor{1ac1}
@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 @ref{1ac1,,run_module()}.

The special global variables @code{__name__}, @code{__spec__}, @code{__file__},
@code{__cached__}, @code{__loader__} and @code{__package__} are set in the globals
dictionary before the module code is executed. (Note that this is a
minimal set of variables - other variables may be set implicitly as an
interpreter implementation detail.)

@code{__name__} is set to `run_name' if this optional argument is not
@ref{87e,,None}, to @code{mod_name + '.__main__'} if the named module is a
package and to the `mod_name' argument otherwise.

@code{__spec__} will be set appropriately for the `actually' imported
module (that is, @code{__spec__.name} will always be `mod_name' or
@code{mod_name + '.__main__'}, never `run_name').

@code{__file__}, @code{__cached__}, @code{__loader__} and @code{__package__} are
@ref{2213,,set as normal} based on the module spec.

If the argument `alter_sys' is supplied and evaluates to @ref{e02,,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{df,,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{23c,,-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 版的變更: 新增 @code{__cached__} 全域變數（請參閱 
@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{2130,,ModuleSpec} for alternatives.

@end deffn

@geindex run_path() (於 runpy 模組中)
@anchor{library/runpy runpy run_path}@anchor{49f}
@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{3e2,,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{3e2,,sys.path} entry (typically a zipfile or
directory), the entry is first added to the beginning of @code{sys.path}. The
function then looks for and executes a @ref{1,,__main__} module using the
updated path. Note that there is no special protection against invoking
an existing @code{__main__} entry located elsewhere on @code{sys.path} if
there is no such module at the specified location.

The optional dictionary argument `init_globals' may be used to pre-populate
the module's globals dictionary before the code is executed.
`init_globals' will not be modified. If any of the special global variables
below are defined in `init_globals', those definitions are
overridden by @ref{49f,,run_path()}.

The special global variables @code{__name__}, @code{__spec__}, @code{__file__},
@code{__cached__}, @code{__loader__} and @code{__package__} are set in the globals
dictionary before the module code is executed. (Note that this is a
minimal set of variables - other variables may be set implicitly as an
interpreter implementation detail.)

@code{__name__} is set to `run_name' if this optional argument is not
@ref{87e,,None} and to @code{'<run_path>'} otherwise.

If `file_path' directly references a script file (whether as source
or as precompiled byte code), then @code{__file__} will be set to
`file_path', and @code{__spec__}, @code{__cached__}, @code{__loader__} and
@code{__package__} will all be set to @ref{87e,,None}.

If `file_path' is a reference to a valid @ref{3e2,,sys.path} entry, then
@code{__spec__} will be set appropriately for the imported @ref{1,,__main__}
module (that is, @code{__spec__.name} will always be @code{__main__}).
@code{__file__}, @code{__cached__}, @code{__loader__} and @code{__package__} will be
@ref{2213,,set as normal} based on the module spec.

A number of alterations are also made to the @ref{df,,sys} module. Firstly,
@ref{3e2,,sys.path} may be altered as described above. @code{sys.argv[0]} is updated
with the value of `file_path' and @code{sys.modules[__name__]} is updated
with a temporary module object for the module being executed. All
modifications to items in @ref{df,,sys} are reverted before the function
returns.

Note that, unlike @ref{1ac1,,run_module()}, the alterations made to @ref{df,,sys}
are not optional in this function as these adjustments are essential to
allowing the execution of @ref{3e2,,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{1fe1,,介面選項} for equivalent functionality on the
command line (@code{python path/to/script}).



在 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{3e2,,sys.path} entry rather
than being executed directly.



在 3.12 版的變更: The setting of @code{__cached__}, @code{__loader__}, and
@code{__package__} are deprecated.

@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{1c70,,命令列與環境} - CPython command line details

The @ref{735,,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 --- import 的實作,importlib resources -- 套件資源的讀取、開啟與存取,runpy --- 定位並執行 Python 模組,引入模組
@anchor{library/importlib doc}@anchor{49a8}@anchor{library/importlib importlib-the-implementation-of-import}@anchor{49a9}@anchor{library/importlib module-importlib}@anchor{7b}@anchor{library/importlib translation-repo}@anchor{49aa}
@subsection @code{importlib} --- @code{import} 的實作


@geindex module; importlib


在 3.1 版被加入.


`原始碼：'Lib/importlib/__init__.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/importlib/__init__.py}


__________________________________________________________________


@menu
* 簡介: 簡介<9>. 
* 函式: 函式<12>. 
* importlib.abc: importlib abc -- Abstract base classes related to import. Abstract base classes related to import
* importlib.machinery: importlib machinery -- Importers and path hooks. Importers and path hooks
* importlib.util: importlib util -- Utility code for importers. Utility code for importers
* 範例: 範例<47>. 

@end menu

@node 簡介<9>,函式<12>,,importlib --- import 的實作
@anchor{library/importlib introduction}@anchor{49ab}
@subsubsection 簡介


@ref{7b,,importlib} 的目的可分為三個部分。

第一是提供 Python 原始碼中 @ref{7f1,,import} 陳述式的實作（因此，也延伸到 @ref{ac8,,__import__()} 函式）。這讓 @code{import} 實作可以移植到任何 Python 直譯器。同時，這也提供了一個比用其他程式語言實作更容易理解的版本。

Two, the components to implement @ref{7f1,,import} are exposed in this
package, making it easier for users to create their own custom objects (known
generically as an @ref{22f8,,importer}) to participate in the import process.

Three, the package contains modules exposing additional functionality for
managing aspects of Python packages:


@itemize *

@item 
@ref{7e,,importlib.metadata} presents access to metadata from third-party
distributions.

@item 
@ref{7f,,importlib.resources} provides routines for accessing non-code
"resources" from Python packages.
@end itemize


@subsubheading 也參考



@table @asis

@item @ref{7f1,,import 陳述式}

The language reference for the @ref{7f1,,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{17c0,,sys.modules}).

@item @ref{1268,,__import__()} 函式

The @ref{7f1,,import} statement is syntactic sugar for this function.

@item @ref{1849,,sys.path 模組搜尋路徑的初始化}

The initialization of @ref{3e2,,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/}

多階段擴充模組初始化

@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 函式<12>,importlib abc -- Abstract base classes related to import,簡介<9>,importlib --- import 的實作
@anchor{library/importlib functions}@anchor{49ac}
@subsubsection 函式


@geindex __import__() (於 importlib 模組中)
@anchor{library/importlib importlib __import__}@anchor{1268}
@deffn {函式} importlib.__import__ (name, globals=None, locals=None, fromlist=(), level=0)

An implementation of the built-in @ref{ac8,,__import__()} function.

@cartouche
@quotation 備註 
Programmatic importing of modules should use @ref{735,,import_module()}
instead of this function.
@end quotation
@end cartouche
@end deffn

@geindex import_module() (於 importlib 模組中)
@anchor{library/importlib importlib import_module}@anchor{735}
@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 @ref{735,,import_module()} function acts as a simplifying wrapper around
@ref{1268,,importlib.__import__()}. This means all semantics of the function are
derived from @ref{1268,,importlib.__import__()}. The most important difference
between these two functions is that @ref{735,,import_module()} returns the
specified package or module (e.g. @code{pkg.mod}), while @ref{ac8,,__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{e05,,invalidate_caches()} in order for the new module to be
noticed by the import system.


在 3.3 版的變更: Parent packages are automatically imported.

@end deffn

@geindex invalidate_caches() (於 importlib 模組中)
@anchor{library/importlib importlib invalidate_caches}@anchor{e05}
@deffn {函式} importlib.invalidate_caches ()

Invalidate the internal caches of finders stored at
@ref{f22,,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.


在 3.3 版被加入.



在 3.10 版的變更: Namespace packages created/installed in a different @ref{3e2,,sys.path}
location after the same namespace was already imported are noticed.

@end deffn

@geindex reload() (於 importlib 模組中)
@anchor{library/importlib importlib reload}@anchor{736}
@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{17c0,,sys.modules}).

When @ref{736,,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{1978,,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{8f0,,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{df,,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{14ac,,from} ...
@ref{7f1,,import} ..., calling @ref{736,,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.


在 3.4 版被加入.



在 3.7 版的變更: @ref{d35,,ModuleNotFoundError} is raised when the module being reloaded lacks
a @ref{2130,,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{1943,,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,函式<12>,importlib --- import 的實作
@anchor{library/importlib importlib-abc-abstract-base-classes-related-to-import}@anchor{49ad}@anchor{library/importlib module-importlib abc}@anchor{7c}
@subsubsection @code{importlib.abc} -- Abstract base classes related to import


@geindex module; importlib.abc

`原始碼：'Lib/importlib/abc.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/importlib/abc.py}


__________________________________________________________________


The @ref{7c,,importlib.abc} module contains all of the core abstract base classes
used by @ref{7f1,,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{a67}
@deffn {類別} importlib.abc.MetaPathFinder

An abstract base class representing a @ref{126b,,meta path finder}.


在 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{a61}
@deffn {方法} find_spec (fullname, path, target=None)

An abstract method for finding a @ref{2215,,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{1f1b,,__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{a66,,importlib.util.spec_from_loader()} may be useful for implementing
concrete @code{MetaPathFinders}.


在 3.4 版被加入.

@end deffn

@geindex invalidate_caches() (importlib.abc.MetaPathFinder 的方法)
@anchor{library/importlib importlib abc MetaPathFinder invalidate_caches}@anchor{49ae}
@deffn {方法} invalidate_caches ()

An optional method which, when called, should invalidate any internal
cache used by the finder. Used by @ref{e05,,importlib.invalidate_caches()}
when invalidating the caches of all finders on @ref{f22,,sys.meta_path}.


在 3.4 版的變更: Returns @code{None} when called instead of @ref{1a2,,NotImplemented}.

@end deffn
@end deffn

@geindex PathEntryFinder (importlib.abc 中的類別)
@anchor{library/importlib importlib abc PathEntryFinder}@anchor{a68}
@deffn {類別} importlib.abc.PathEntryFinder

An abstract base class representing a @ref{126c,,path entry finder}.  Though
it bears some similarities to @ref{a67,,MetaPathFinder}, @code{PathEntryFinder}
is meant for use only within the path-based import subsystem provided
by @ref{121e,,importlib.machinery.PathFinder}.


在 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{a65}
@deffn {方法} find_spec (fullname, target=None)

An abstract method for finding a @ref{2215,,spec} for
the specified module.  The finder will search for the module only
within the @ref{2307,,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{a66,,importlib.util.spec_from_loader()}
may be useful for implementing concrete @code{PathEntryFinders}.


在 3.4 版被加入.

@end deffn

@geindex invalidate_caches() (importlib.abc.PathEntryFinder 的方法)
@anchor{library/importlib importlib abc PathEntryFinder invalidate_caches}@anchor{49af}
@deffn {方法} invalidate_caches ()

An optional method which, when called, should invalidate any internal
cache used by the finder. Used by
@ref{e04,,importlib.machinery.PathFinder.invalidate_caches()}
when invalidating the caches of all cached finders.
@end deffn
@end deffn

@geindex Loader (importlib.abc 中的類別)
@anchor{library/importlib importlib abc Loader}@anchor{10c2}
@deffn {類別} importlib.abc.Loader

An abstract base class for a @ref{1978,,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{49b0,,importlib.resources.abc.ResourceReader}.


在 3.7 版的變更: Introduced the optional @code{get_resource_reader()} method.


@geindex create_module() (importlib.abc.Loader 的方法)
@anchor{library/importlib importlib abc Loader create_module}@anchor{ea7}
@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.


在 3.4 版被加入.



在 3.6 版的變更: This method is no longer optional when
@ref{a63,,exec_module()} is defined.

@end deffn

@geindex exec_module() (importlib.abc.Loader 的方法)
@anchor{library/importlib importlib abc Loader exec_module}@anchor{a63}
@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 @ref{a63,,exec_module()} is called.  When this method exists,
@ref{ea7,,create_module()} must be defined.


在 3.4 版被加入.



在 3.6 版的變更: @ref{ea7,,create_module()} 也必須被定義。

@end deffn

@geindex load_module() (importlib.abc.Loader 的方法)
@anchor{library/importlib importlib abc Loader load_module}@anchor{a62}
@deffn {方法} load_module (fullname)

A legacy method for loading a module.  If the module cannot be
loaded, @ref{653,,ImportError} is raised, otherwise the loaded module is
returned.

If the requested module already exists in @ref{17c0,,sys.modules}, that
module should be used and reloaded.
Otherwise the loader should create a new module and insert it into
@ref{17c0,,sys.modules} before any loading begins, to prevent recursion
from the import.  If the loader inserted a module and the load fails, it
must be removed by the loader from @ref{17c0,,sys.modules}; modules already
in @ref{17c0,,sys.modules} before the loader began execution should be left
alone.

The loader should set several attributes on the module
(note that some of these attributes can change when a module is
reloaded):


@itemize -

@item 
@ref{1583,,module.__name__}

@item 
@ref{221b,,module.__file__}

@item 
@ref{320,,module.__cached__} `（已棄用）'

@item 
@ref{1f1b,,module.__path__}

@item 
@ref{322,,module.__package__} `（已棄用）'

@item 
@ref{33a,,module.__loader__} `（已棄用）'
@end itemize

When @ref{a63,,exec_module()} is available then backwards-compatible
functionality is provided.


在 3.4 版的變更: Raise @ref{653,,ImportError} when called instead of
@ref{369,,NotImplementedError}.  Functionality provided when
@ref{a63,,exec_module()} is available.



Deprecated since version 3.4, will be removed in version 3.15: The recommended API for loading a module is @ref{a63,,exec_module()}
(and @ref{ea7,,create_module()}).  Loaders should implement it instead of
@ref{a62,,load_module()}.  The import machinery takes care of all the
other responsibilities of @ref{a62,,load_module()} when
@ref{a63,,exec_module()} is implemented.

@end deffn
@end deffn

@geindex ResourceLoader (importlib.abc 中的類別)
@anchor{library/importlib importlib abc ResourceLoader}@anchor{ddd}
@deffn {類別} importlib.abc.ResourceLoader

`Superseded by TraversableResources'

@quotation

An abstract base class for a @ref{1978,,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{2f8,,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{4999}
@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{2c0,,OSError} is to be raised if the `path' cannot
be found. The `path' is expected to be constructed using a module's
@ref{221b,,__file__} attribute or an item from a package's
@ref{1f1b,,__path__}.


在 3.4 版的變更: Raises @ref{2c0,,OSError} instead of @ref{369,,NotImplementedError}.

@end quotation
@end deffn
@end quotation
@end deffn

@geindex InspectLoader (importlib.abc 中的類別)
@anchor{library/importlib importlib abc InspectLoader}@anchor{114f}
@deffn {類別} importlib.abc.InspectLoader

An abstract base class for a @ref{1978,,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{1150}
@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{653,,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 方法


在 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{1153}
@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{f30,,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{653,,ImportError} if the loader cannot find the module specified.


在 3.4 版的變更: Raises @ref{653,,ImportError} instead of @ref{369,,NotImplementedError}.

@end quotation
@end deffn

@geindex is_package() (importlib.abc.InspectLoader 的方法)
@anchor{library/importlib importlib abc InspectLoader is_package}@anchor{49b1}
@deffn {方法} is_package (fullname)

An optional method to return a true value if the module is a package, a
false value otherwise. @ref{653,,ImportError} is raised if the
@ref{1978,,loader} cannot find the module.


在 3.4 版的變更: Raises @ref{653,,ImportError} instead of @ref{369,,NotImplementedError}.

@end deffn

@geindex source_to_code() (importlib.abc.InspectLoader 的靜態方法)
@anchor{library/importlib importlib abc InspectLoader source_to_code}@anchor{100d}
@deffn {方法} static source_to_code (data, path='<string>')

Create a code object from Python source.

The `data' argument can be whatever the @ref{4ac,,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__)}.


在 3.4 版被加入.



在 3.5 版的變更: Made the method static.

@end deffn

@geindex exec_module() (importlib.abc.InspectLoader 的方法)
@anchor{library/importlib importlib abc InspectLoader exec_module}@anchor{120d}
@deffn {方法} exec_module (module)

@ref{a63,,Loader.exec_module()} 的實作。


在 3.4 版被加入.

@end deffn

@geindex load_module() (importlib.abc.InspectLoader 的方法)
@anchor{library/importlib importlib abc InspectLoader load_module}@anchor{49b2}
@deffn {方法} load_module (fullname)

@ref{a62,,Loader.load_module()} 的實作。


Deprecated since version 3.4, will be removed in version 3.15: 請改用 @ref{120d,,exec_module()}。

@end deffn
@end deffn

@geindex ExecutionLoader (importlib.abc 中的類別)
@anchor{library/importlib importlib abc ExecutionLoader}@anchor{49b3}
@deffn {類別} importlib.abc.ExecutionLoader

An abstract base class which inherits from @ref{114f,,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{49b4}
@deffn {方法} abstractmethod get_filename (fullname)

@quotation

An abstract method that is to return the value of
@ref{221b,,__file__} for the specified module. If no path is
available, @ref{653,,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{653,,ImportError} instead of @ref{369,,NotImplementedError}.

@end quotation
@end deffn
@end deffn

@geindex FileLoader (importlib.abc 中的類別)
@anchor{library/importlib importlib abc FileLoader}@anchor{126e}
@deffn {類別} importlib.abc.FileLoader (fullname, path)

An abstract base class which inherits from @ref{ddd,,ResourceLoader} and
@ref{49b3,,ExecutionLoader}, providing concrete implementations of
@ref{4999,,ResourceLoader.get_data()} and @ref{49b4,,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.


在 3.3 版被加入.


@geindex name (importlib.abc.FileLoader 的屬性)
@anchor{library/importlib importlib abc FileLoader name}@anchor{49b5}
@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{49b6}
@deffn {屬性} path

Path to the file of the module.
@end deffn

@geindex load_module() (importlib.abc.FileLoader 的方法)
@anchor{library/importlib importlib abc FileLoader load_module}@anchor{49b7}
@deffn {方法} load_module (fullname)

Calls super's @code{load_module()}.


Deprecated since version 3.4, will be removed in version 3.15: Use @ref{a63,,Loader.exec_module()} instead.

@end deffn

@geindex get_filename() (importlib.abc.FileLoader 的方法)
@anchor{library/importlib importlib abc FileLoader get_filename}@anchor{49b8}
@deffn {方法} abstractmethod get_filename (fullname)

Returns @ref{49b6,,path}.
@end deffn

@geindex get_data() (importlib.abc.FileLoader 的方法)
@anchor{library/importlib importlib abc FileLoader get_data}@anchor{49b9}
@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{49ba}
@deffn {類別} importlib.abc.SourceLoader

An abstract base class for implementing source (and optionally bytecode)
file loading. The class inherits from both @ref{ddd,,ResourceLoader} and
@ref{49b3,,ExecutionLoader}, requiring the implementation of:


@itemize *

@item 
@ref{4999,,ResourceLoader.get_data()}

@item 

@table @asis

@item @ref{49b4,,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{369,,NotImplementedError}) causes the loader to
only work with source code. Implementing the methods allows the loader to
work with source `and' bytecode files; it does not allow for `sourceless'
loading where only bytecode is provided.  Bytecode files are an
optimization to speed up loading by removing the parsing step of Python's
compiler, and so no bytecode-specific API is exposed.

@geindex path_stats() (importlib.abc.SourceLoader 的方法)
@anchor{library/importlib importlib abc SourceLoader path_stats}@anchor{138b}
@deffn {方法} path_stats (path)

Optional abstract method which returns a @ref{183,,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{2c0,,OSError} is raised.


在 3.3 版被加入.



在 3.4 版的變更: Raise @ref{2c0,,OSError} instead of @ref{369,,NotImplementedError}.

@end deffn

@geindex path_mtime() (importlib.abc.SourceLoader 的方法)
@anchor{library/importlib importlib abc SourceLoader path_mtime}@anchor{138a}
@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{138b,,path_stats()}.  You don't
have to implement it, but it is still available for compatibility
purposes. Raise @ref{2c0,,OSError} if the path cannot be handled.



在 3.4 版的變更: Raise @ref{2c0,,OSError} instead of @ref{369,,NotImplementedError}.

@end deffn

@geindex set_data() (importlib.abc.SourceLoader 的方法)
@anchor{library/importlib importlib abc SourceLoader set_data}@anchor{49bb}
@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{25b7,,errno.EACCES}/@ref{f39,,PermissionError}), do not propagate the
exception.


在 3.4 版的變更: No longer raises @ref{369,,NotImplementedError} when called.

@end deffn

@geindex get_code() (importlib.abc.SourceLoader 的方法)
@anchor{library/importlib importlib abc SourceLoader get_code}@anchor{49bc}
@deffn {方法} get_code (fullname)

Concrete implementation of @ref{1150,,InspectLoader.get_code()}.
@end deffn

@geindex exec_module() (importlib.abc.SourceLoader 的方法)
@anchor{library/importlib importlib abc SourceLoader exec_module}@anchor{120e}
@deffn {方法} exec_module (module)

Concrete implementation of @ref{a63,,Loader.exec_module()}.


在 3.4 版被加入.

@end deffn

@geindex load_module() (importlib.abc.SourceLoader 的方法)
@anchor{library/importlib importlib abc SourceLoader load_module}@anchor{49bd}
@deffn {方法} load_module (fullname)

Concrete implementation of @ref{a62,,Loader.load_module()}.


Deprecated since version 3.4, will be removed in version 3.15: Use @ref{120e,,exec_module()} instead.

@end deffn

@geindex get_source() (importlib.abc.SourceLoader 的方法)
@anchor{library/importlib importlib abc SourceLoader get_source}@anchor{121c}
@deffn {方法} get_source (fullname)

Concrete implementation of @ref{1153,,InspectLoader.get_source()}.
@end deffn

@geindex is_package() (importlib.abc.SourceLoader 的方法)
@anchor{library/importlib importlib abc SourceLoader is_package}@anchor{49be}
@deffn {方法} is_package (fullname)

Concrete implementation of @ref{49b1,,InspectLoader.is_package()}. A module
is determined to be a package if its file path (as provided by
@ref{49b4,,ExecutionLoader.get_filename()}) is a file named
@code{__init__} when the file extension is removed `and' the module name
itself does not end in @code{__init__}.
@end deffn
@end deffn

@geindex ResourceReader (importlib.abc 中的類別)
@anchor{library/importlib importlib abc ResourceReader}@anchor{cec}
@deffn {類別} importlib.abc.ResourceReader

`Superseded by TraversableResources'

An @ref{13b7,,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{59b,,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{87e,,None}. An object compatible with this ABC should only be
returned when the specified module is a package.


在 3.7 版被加入.



Deprecated since version 3.12, removed in version 3.14: Use @ref{2f8,,importlib.resources.abc.TraversableResources} instead.


@geindex open_resource() (importlib.abc.ResourceReader 的方法)
@anchor{library/importlib importlib abc ResourceReader open_resource}@anchor{49bf}
@deffn {方法} abstractmethod open_resource (resource)

@quotation

Returns an opened, @ref{28ad,,file-like object} for binary reading
of the `resource'.

If the resource cannot be found, @ref{264,,FileNotFoundError} is
raised.
@end quotation
@end deffn

@geindex resource_path() (importlib.abc.ResourceReader 的方法)
@anchor{library/importlib importlib abc ResourceReader resource_path}@anchor{49c0}
@deffn {方法} abstractmethod resource_path (resource)

@quotation

Returns the file system path to the `resource'.

If the resource does not concretely exist on the file system,
raise @ref{264,,FileNotFoundError}.
@end quotation
@end deffn

@geindex is_resource() (importlib.abc.ResourceReader 的方法)
@anchor{library/importlib importlib abc ResourceReader is_resource}@anchor{49c1}
@deffn {方法} abstractmethod is_resource (name)

@quotation

Returns @code{True} if the named `name' is considered a resource.
@ref{264,,FileNotFoundError} is raised if `name' does not exist.
@end quotation
@end deffn

@geindex contents() (importlib.abc.ResourceReader 的方法)
@anchor{library/importlib importlib abc ResourceReader contents}@anchor{1ced}
@deffn {方法} abstractmethod contents ()

@quotation

Returns an @ref{1428,,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{49c1,,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 quotation
@end deffn
@end deffn

@geindex Traversable (importlib.abc 中的類別)
@anchor{library/importlib importlib abc Traversable}@anchor{1b3b}
@deffn {類別} importlib.abc.Traversable

An object with a subset of @ref{266,,pathlib.Path} methods suitable for
traversing directories and opening files.

For a representation of the object on the file-system, use
@ref{6ae,,importlib.resources.as_file()}.


在 3.9 版被加入.



Deprecated since version 3.12, removed in version 3.14: Use @ref{2f9,,importlib.resources.abc.Traversable} instead.


@geindex name (importlib.abc.Traversable 的屬性)
@anchor{library/importlib importlib abc Traversable name}@anchor{49c2}
@deffn {屬性} name

Abstract. The base name of this object without any parent references.
@end deffn

@geindex iterdir() (importlib.abc.Traversable 的方法)
@anchor{library/importlib importlib abc Traversable iterdir}@anchor{49c3}
@deffn {方法} abstractmethod iterdir ()

Yield @code{Traversable} objects in @code{self}.
@end deffn

@geindex is_dir() (importlib.abc.Traversable 的方法)
@anchor{library/importlib importlib abc Traversable is_dir}@anchor{49c4}
@deffn {方法} abstractmethod is_dir ()

Return @code{True} if @code{self} is a directory.
@end deffn

@geindex is_file() (importlib.abc.Traversable 的方法)
@anchor{library/importlib importlib abc Traversable is_file}@anchor{49c5}
@deffn {方法} abstractmethod is_file ()

Return @code{True} if @code{self} is a file.
@end deffn

@geindex joinpath() (importlib.abc.Traversable 的方法)
@anchor{library/importlib importlib abc Traversable joinpath}@anchor{49c6}
@deffn {方法} abstractmethod joinpath (child)

Return Traversable child in @code{self}.
@end deffn

@geindex __truediv__() (importlib.abc.Traversable 的方法)
@anchor{library/importlib importlib abc Traversable __truediv__}@anchor{49c7}
@deffn {方法} abstractmethod __truediv__ (child)

Return @code{Traversable} child in @code{self}.
@end deffn

@geindex open() (importlib.abc.Traversable 的方法)
@anchor{library/importlib importlib abc Traversable open}@anchor{49c8}
@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{2aec,,pathlib.Path.open}).

When opening as text, accepts encoding parameters such as those
accepted by @ref{9b7,,io.TextIOWrapper}.
@end deffn

@geindex read_bytes() (importlib.abc.Traversable 的方法)
@anchor{library/importlib importlib abc Traversable read_bytes}@anchor{49c9}
@deffn {方法} read_bytes ()

Read contents of @code{self} as bytes.
@end deffn

@geindex read_text() (importlib.abc.Traversable 的方法)
@anchor{library/importlib importlib abc Traversable read_text}@anchor{49ca}
@deffn {方法} read_text (encoding=None)

Read contents of @code{self} as text.
@end deffn
@end deffn

@geindex TraversableResources (importlib.abc 中的類別)
@anchor{library/importlib importlib abc TraversableResources}@anchor{1b39}
@deffn {類別} importlib.abc.TraversableResources

An abstract base class for resource readers capable of serving
the @ref{6af,,importlib.resources.files()} interface. Subclasses
@ref{49b0,,importlib.resources.abc.ResourceReader} and provides
concrete implementations of the @ref{49b0,,importlib.resources.abc.ResourceReader}'s
abstract methods. Therefore, any loader supplying
@ref{1b39,,importlib.abc.TraversableResources} also supplies ResourceReader.

Loaders that wish to support resource reading are expected to
implement this interface.


在 3.9 版被加入.



Deprecated since version 3.12, removed in version 3.14: Use @ref{2f8,,importlib.resources.abc.TraversableResources} instead.


@geindex files() (importlib.abc.TraversableResources 的方法)
@anchor{library/importlib importlib abc TraversableResources files}@anchor{49cb}
@deffn {方法} abstractmethod files ()

Returns a @ref{2f9,,importlib.resources.abc.Traversable} object for the loaded
package.
@end deffn
@end deffn

@node importlib machinery -- Importers and path hooks,importlib util -- Utility code for importers,importlib abc -- Abstract base classes related to import,importlib --- import 的實作
@anchor{library/importlib importlib-machinery-importers-and-path-hooks}@anchor{49cc}@anchor{library/importlib module-importlib machinery}@anchor{7d}
@subsubsection @code{importlib.machinery} -- Importers and path hooks


@geindex module; importlib.machinery

`原始碼：'Lib/importlib/machinery.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/importlib/machinery.py}


__________________________________________________________________


This module contains the various objects that help @ref{7f1,,import}
find and load modules.

@geindex SOURCE_SUFFIXES (於 importlib.machinery 模組中)
@anchor{library/importlib importlib machinery SOURCE_SUFFIXES}@anchor{731}
@deffn {資料} importlib.machinery.SOURCE_SUFFIXES

A list of strings representing the recognized file suffixes for source
modules.


在 3.3 版被加入.

@end deffn

@geindex DEBUG_BYTECODE_SUFFIXES (於 importlib.machinery 模組中)
@anchor{library/importlib importlib machinery DEBUG_BYTECODE_SUFFIXES}@anchor{1826}
@deffn {資料} importlib.machinery.DEBUG_BYTECODE_SUFFIXES

A list of strings representing the file suffixes for non-optimized bytecode
modules.


在 3.3 版被加入.



在 3.5 版之後被棄用: Use @ref{733,,BYTECODE_SUFFIXES} instead.

@end deffn

@geindex OPTIMIZED_BYTECODE_SUFFIXES (於 importlib.machinery 模組中)
@anchor{library/importlib importlib machinery OPTIMIZED_BYTECODE_SUFFIXES}@anchor{1827}
@deffn {資料} importlib.machinery.OPTIMIZED_BYTECODE_SUFFIXES

A list of strings representing the file suffixes for optimized bytecode
modules.


在 3.3 版被加入.



在 3.5 版之後被棄用: Use @ref{733,,BYTECODE_SUFFIXES} instead.

@end deffn

@geindex BYTECODE_SUFFIXES (於 importlib.machinery 模組中)
@anchor{library/importlib importlib machinery BYTECODE_SUFFIXES}@anchor{733}
@deffn {資料} importlib.machinery.BYTECODE_SUFFIXES

A list of strings representing the recognized file suffixes for bytecode
modules (including the leading dot).


在 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{732}
@deffn {資料} importlib.machinery.EXTENSION_SUFFIXES

A list of strings representing the recognized file suffixes for
extension modules.


在 3.3 版被加入.

@end deffn

@geindex all_suffixes() (於 importlib.machinery 模組中)
@anchor{library/importlib importlib machinery all_suffixes}@anchor{48d2}
@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{f2f,,inspect.getmodulename()}).


在 3.3 版被加入.

@end deffn

@geindex BuiltinImporter (importlib.machinery 中的類別)
@anchor{library/importlib importlib machinery BuiltinImporter}@anchor{ea8}
@deffn {類別} importlib.machinery.BuiltinImporter

An @ref{22f8,,importer} for built-in modules. All known built-in modules are
listed in @ref{1f0e,,sys.builtin_module_names}. This class implements the
@ref{a67,,importlib.abc.MetaPathFinder} and
@ref{114f,,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{121a}
@deffn {類別} importlib.machinery.FrozenImporter

An @ref{22f8,,importer} for frozen modules. This class implements the
@ref{a67,,importlib.abc.MetaPathFinder} and
@ref{114f,,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{f21}
@deffn {類別} importlib.machinery.WindowsRegistryFinder

@ref{221c,,Finder} for modules declared in the Windows registry.  This class
implements the @ref{a67,,importlib.abc.MetaPathFinder} ABC.

Only class methods are defined by this class to alleviate the need for
instantiation.


在 3.3 版被加入.



在 3.6 版之後被棄用: Use @ref{cc,,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{121e}
@deffn {類別} importlib.machinery.PathFinder

A @ref{221c,,Finder} for @ref{3e2,,sys.path} and package @code{__path__} attributes.
This class implements the @ref{a67,,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{120c}
@deffn {方法} classmethod find_spec (fullname, path=None, target=None)

Class method that attempts to find a @ref{2215,,spec}
for the module specified by `fullname' on @ref{3e2,,sys.path} or, if
defined, on `path'. For each path entry that is searched,
@ref{7f3,,sys.path_importer_cache} is checked. If a non-false object
is found then it is used as the @ref{126c,,path entry finder} to look
for the module being searched for. If no entry is found in
@ref{7f3,,sys.path_importer_cache}, then @ref{121f,,sys.path_hooks} is
searched for a finder for the path entry and, if found, is stored
in @ref{7f3,,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.


在 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{7f3,,sys.path_importer_cache}.

@end deffn

@geindex invalidate_caches() (importlib.machinery.PathFinder 的類別方法)
@anchor{library/importlib importlib machinery PathFinder invalidate_caches}@anchor{e04}
@deffn {方法} classmethod invalidate_caches ()

Calls @ref{49af,,importlib.abc.PathEntryFinder.invalidate_caches()} on all
finders stored in @ref{7f3,,sys.path_importer_cache} that define the method.
Otherwise entries in @ref{7f3,,sys.path_importer_cache} set to @code{None} are
deleted.


在 3.7 版的變更: Entries of @code{None} in @ref{7f3,,sys.path_importer_cache} are deleted.

@end deffn


在 3.4 版的變更: Calls objects in @ref{121f,,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{126d}
@deffn {類別} importlib.machinery.FileFinder (path, *loader_details)

A concrete implementation of @ref{a68,,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{e05,,importlib.invalidate_caches()}.


在 3.3 版被加入.


@geindex path (importlib.machinery.FileFinder 的屬性)
@anchor{library/importlib importlib machinery FileFinder path}@anchor{49cd}
@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{10c1}
@deffn {方法} find_spec (fullname, target=None)

Attempt to find the spec to handle `fullname' within @ref{49cd,,path}.


在 3.4 版被加入.

@end deffn

@geindex invalidate_caches() (importlib.machinery.FileFinder 的方法)
@anchor{library/importlib importlib machinery FileFinder invalidate_caches}@anchor{49ce}
@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{49cf}
@deffn {方法} classmethod path_hook (*loader_details)

A class method which returns a closure for use on @ref{121f,,sys.path_hooks}.
An instance of @ref{126d,,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{653,,ImportError} is raised.
@end deffn
@end deffn

@geindex SourceFileLoader (importlib.machinery 中的類別)
@anchor{library/importlib importlib machinery SourceFileLoader}@anchor{126f}
@deffn {類別} importlib.machinery.SourceFileLoader (fullname, path)

A concrete implementation of @ref{49ba,,importlib.abc.SourceLoader} by
subclassing @ref{126e,,importlib.abc.FileLoader} and providing some concrete
implementations of other methods.


在 3.3 版被加入.


@geindex name (importlib.machinery.SourceFileLoader 的屬性)
@anchor{library/importlib importlib machinery SourceFileLoader name}@anchor{49d0}
@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{49d1}
@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{49d2}
@deffn {方法} is_package (fullname)

Return @code{True} if @ref{49d1,,path} appears to be for a package.
@end deffn

@geindex path_stats() (importlib.machinery.SourceFileLoader 的方法)
@anchor{library/importlib importlib machinery SourceFileLoader path_stats}@anchor{49d3}
@deffn {方法} path_stats (path)

Concrete implementation of @ref{138b,,importlib.abc.SourceLoader.path_stats()}.
@end deffn

@geindex set_data() (importlib.machinery.SourceFileLoader 的方法)
@anchor{library/importlib importlib machinery SourceFileLoader set_data}@anchor{49d4}
@deffn {方法} set_data (path, data)

Concrete implementation of @ref{49bb,,importlib.abc.SourceLoader.set_data()}.
@end deffn

@geindex load_module() (importlib.machinery.SourceFileLoader 的方法)
@anchor{library/importlib importlib machinery SourceFileLoader load_module}@anchor{f1f}
@deffn {方法} load_module (name=None)

Concrete implementation of @ref{a62,,importlib.abc.Loader.load_module()} where
specifying the name of the module to load is optional.


Deprecated since version 3.6, will be removed in version 3.15: Use @ref{a63,,importlib.abc.Loader.exec_module()} instead.

@end deffn
@end deffn

@geindex SourcelessFileLoader (importlib.machinery 中的類別)
@anchor{library/importlib importlib machinery SourcelessFileLoader}@anchor{1270}
@deffn {類別} importlib.machinery.SourcelessFileLoader (fullname, path)

A concrete implementation of @ref{126e,,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.


在 3.3 版被加入.


@geindex name (importlib.machinery.SourcelessFileLoader 的屬性)
@anchor{library/importlib importlib machinery SourcelessFileLoader name}@anchor{49d5}
@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{49d6}
@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{49d7}
@deffn {方法} is_package (fullname)

Determines if the module is a package based on @ref{49d6,,path}.
@end deffn

@geindex get_code() (importlib.machinery.SourcelessFileLoader 的方法)
@anchor{library/importlib importlib machinery SourcelessFileLoader get_code}@anchor{49d8}
@deffn {方法} get_code (fullname)

Returns the code object for @ref{49d5,,name} created from @ref{49d6,,path}.
@end deffn

@geindex get_source() (importlib.machinery.SourcelessFileLoader 的方法)
@anchor{library/importlib importlib machinery SourcelessFileLoader get_source}@anchor{49d9}
@deffn {方法} get_source (fullname)

Returns @code{None} as bytecode files have no source when this loader is
used.
@end deffn

@geindex load_module() (importlib.machinery.SourcelessFileLoader 的方法)
@anchor{library/importlib importlib machinery SourcelessFileLoader load_module}@anchor{f20}
@deffn {方法} load_module (name=None)
@end deffn

Concrete implementation of @ref{a62,,importlib.abc.Loader.load_module()} where
specifying the name of the module to load is optional.


Deprecated since version 3.6, will be removed in version 3.15: Use @ref{a63,,importlib.abc.Loader.exec_module()} instead.

@end deffn

@geindex ExtensionFileLoader (importlib.machinery 中的類別)
@anchor{library/importlib importlib machinery ExtensionFileLoader}@anchor{ea9}
@deffn {類別} importlib.machinery.ExtensionFileLoader (fullname, path)

A concrete implementation of @ref{49b3,,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.


在 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{49da}
@deffn {屬性} name

Name of the module the loader supports.
@end deffn

@geindex path (importlib.machinery.ExtensionFileLoader 的屬性)
@anchor{library/importlib importlib machinery ExtensionFileLoader path}@anchor{49db}
@deffn {屬性} path

Path to the extension module.
@end deffn

@geindex create_module() (importlib.machinery.ExtensionFileLoader 的方法)
@anchor{library/importlib importlib machinery ExtensionFileLoader create_module}@anchor{49dc}
@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/}.


在 3.5 版被加入.

@end deffn

@geindex exec_module() (importlib.machinery.ExtensionFileLoader 的方法)
@anchor{library/importlib importlib machinery ExtensionFileLoader exec_module}@anchor{49dd}
@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/}.


在 3.5 版被加入.

@end deffn

@geindex is_package() (importlib.machinery.ExtensionFileLoader 的方法)
@anchor{library/importlib importlib machinery ExtensionFileLoader is_package}@anchor{49de}
@deffn {方法} is_package (fullname)

Returns @code{True} if the file path points to a package's @code{__init__}
module based on @ref{732,,EXTENSION_SUFFIXES}.
@end deffn

@geindex get_code() (importlib.machinery.ExtensionFileLoader 的方法)
@anchor{library/importlib importlib machinery ExtensionFileLoader get_code}@anchor{49df}
@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{49e0}
@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{1154}
@deffn {方法} get_filename (fullname)

Returns @ref{49db,,path}.


在 3.4 版被加入.

@end deffn
@end deffn

@geindex NamespaceLoader (importlib.machinery 中的類別)
@anchor{library/importlib importlib machinery NamespaceLoader}@anchor{1151}
@deffn {類別} importlib.machinery.NamespaceLoader (name, path, path_finder)

A concrete implementation of @ref{114f,,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


在 3.11 版被加入.

@end deffn

@geindex ModuleSpec (importlib.machinery 中的類別)
@anchor{library/importlib importlib machinery ModuleSpec}@anchor{2130}
@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{2216,,__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{221b,,__file__} at runtime and this will not be
automatically reflected in the module's
@ref{49e1,,__spec__.origin}, and vice versa.


在 3.4 版被加入.


@geindex name (importlib.machinery.ModuleSpec 的屬性)
@anchor{library/importlib importlib machinery ModuleSpec name}@anchor{2217}
@deffn {屬性} name

The module's fully qualified name (see @ref{1583,,module.__name__}).
The @ref{221c,,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{33b}
@deffn {屬性} loader

The @ref{1978,,loader} used to load the module (see @ref{33a,,module.__loader__}).
The @ref{221c,,finder} should always set this attribute.
@end deffn

@geindex origin (importlib.machinery.ModuleSpec 的屬性)
@anchor{library/importlib importlib machinery ModuleSpec origin}@anchor{49e1}
@deffn {屬性} origin

The location the @ref{1978,,loader} should use to load the module
(see @ref{221b,,module.__file__}).
For example, for modules loaded from a @code{.py} file this is the filename.
The @ref{221c,,finder} should always set this attribute to a meaningful value
for the @ref{1978,,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{221a}
@deffn {屬性} submodule_search_locations

A (possibly empty) @ref{70f,,sequence} of strings enumerating the locations
in which a package's submodules will be found
(see @ref{1f1b,,module.__path__}). Most of the time there will only be a
single directory in this list.

The @ref{221c,,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{49e2}
@deffn {屬性} loader_state

The @ref{221c,,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{321}
@deffn {屬性} cached

The filename of a compiled version of the module's code
(see @ref{320,,module.__cached__}).
The @ref{221c,,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{323}
@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{322,,module.__package__}.
If the module is a package then this is the same as @ref{2217,,name}.
@end deffn

@geindex has_location (importlib.machinery.ModuleSpec 的屬性)
@anchor{library/importlib importlib machinery ModuleSpec has_location}@anchor{49e3}
@deffn {屬性} has_location

@code{True} if the spec's @ref{49e1,,origin} refers to a loadable location,
@code{False} otherwise.  This value impacts how @code{origin} is interpreted
and how the module's @ref{221b,,__file__} is populated.
@end deffn
@end deffn

@geindex AppleFrameworkLoader (importlib.machinery 中的類別)
@anchor{library/importlib importlib machinery AppleFrameworkLoader}@anchor{212f}
@deffn {類別} importlib.machinery.AppleFrameworkLoader (name, path)

A specialization of @ref{ea9,,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.


在 3.13 版被加入.


@ref{2006,,可用性}: iOS.

@geindex name (importlib.machinery.AppleFrameworkLoader 的屬性)
@anchor{library/importlib importlib machinery AppleFrameworkLoader name}@anchor{49e4}
@deffn {屬性} name

Name of the module the loader supports.
@end deffn

@geindex path (importlib.machinery.AppleFrameworkLoader 的屬性)
@anchor{library/importlib importlib machinery AppleFrameworkLoader path}@anchor{49e5}
@deffn {屬性} path

Path to the @code{.fwork} file for the extension module.
@end deffn
@end deffn

@node importlib util -- Utility code for importers,範例<47>,importlib machinery -- Importers and path hooks,importlib --- import 的實作
@anchor{library/importlib importlib-util-utility-code-for-importers}@anchor{49e6}@anchor{library/importlib module-importlib util}@anchor{81}
@subsubsection @code{importlib.util} -- Utility code for importers


@geindex module; importlib.util

`原始碼：'Lib/importlib/util.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/importlib/util.py}


__________________________________________________________________


This module contains the various objects that help in the construction of
an @ref{22f8,,importer}.

@geindex MAGIC_NUMBER (於 importlib.util 模組中)
@anchor{library/importlib importlib util MAGIC_NUMBER}@anchor{730}
@deffn {資料} importlib.util.MAGIC_NUMBER

The bytes which represent the bytecode version number. If you need help with
loading/writing bytecode then consider @ref{49ba,,importlib.abc.SourceLoader}.


在 3.4 版被加入.

@end deffn

@geindex cache_from_source() (於 importlib.util 模組中)
@anchor{library/importlib importlib util cache_from_source}@anchor{351}
@deffn {函式} importlib.util.cache_from_source (path, debug_override=None, *, optimization=None)

Return the 
@geindex Python Enhancement Proposals; PEP 3147
PEP 3147@footnote{https://peps.python.org/pep-3147/}/
@geindex Python Enhancement Proposals; PEP 488
PEP 488@footnote{https://peps.python.org/pep-0488/} path to the byte-compiled file associated
with the source `path'.  For example, if `path' is @code{/foo/bar/baz.py} the return
value would be @code{/foo/bar/__pycache__/baz.cpython-32.pyc} for Python 3.2.
The @code{cpython-32} string comes from the current magic tag (see
@code{get_tag()}; if @code{sys.implementation.cache_tag} is not defined then
@ref{369,,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{2eb,,ValueError} is raised.

The `debug_override' parameter is deprecated and can be used to override
the system's value for @code{__debug__}. A @code{True} value is the equivalent of
setting `optimization' to the empty string. A @code{False} value is the same as
setting `optimization' to @code{1}. If both `debug_override' an `optimization'
are not @code{None} then @ref{198,,TypeError} is raised.


在 3.4 版被加入.



在 3.5 版的變更: The `optimization' parameter was added and the `debug_override' parameter
was deprecated.



在 3.6 版的變更: 接受一個 @ref{59b,,path-like object}。

@end deffn

@geindex source_from_cache() (於 importlib.util 模組中)
@anchor{library/importlib importlib util source_from_cache}@anchor{737}
@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{2eb,,ValueError} is raised. If
@code{sys.implementation.cache_tag} is not defined,
@ref{369,,NotImplementedError} is raised.


在 3.4 版被加入.



在 3.6 版的變更: 接受一個 @ref{59b,,path-like object}。

@end deffn

@geindex decode_source() (於 importlib.util 模組中)
@anchor{library/importlib importlib util decode_source}@anchor{1152}
@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{1153,,importlib.abc.InspectLoader.get_source()}).


在 3.4 版被加入.

@end deffn

@geindex resolve_name() (於 importlib.util 模組中)
@anchor{library/importlib importlib util resolve_name}@anchor{afd}
@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{653,,ImportError} is raised if `name' is a relative module name but
`package' is a false value (e.g. @code{None} or the empty string).
@ref{653,,ImportError} is also raised if a relative name would escape its
containing package (e.g. requesting @code{..bacon} from within the @code{spam}
package).


在 3.3 版被加入.



在 3.9 版的變更: To improve consistency with import statements, raise
@ref{653,,ImportError} instead of @ref{2eb,,ValueError} for invalid relative
import attempts.

@end deffn

@geindex find_spec() (於 importlib.util 模組中)
@anchor{library/importlib importlib util find_spec}@anchor{5a9}
@deffn {函式} importlib.util.find_spec (name, package=None)

Find the @ref{2215,,spec} for a module, optionally relative to
the specified `package' name. If the module is in @ref{17c0,,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{2eb,,ValueError} is raised).
Otherwise a search using @ref{f22,,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()}.


在 3.4 版被加入.



在 3.7 版的變更: Raises @ref{d35,,ModuleNotFoundError} instead of @ref{5e8,,AttributeError} if
`package' is in fact not a package (i.e. lacks a
@ref{1f1b,,__path__} attribute).

@end deffn

@geindex module_from_spec() (於 importlib.util 模組中)
@anchor{library/importlib importlib util module_from_spec}@anchor{100e}
@deffn {函式} importlib.util.module_from_spec (spec)

Create a new module based on `spec' and
@ref{ea7,,spec.loader.create_module}.

If @ref{ea7,,spec.loader.create_module}
does not return @code{None}, then any pre-existing attributes will not be reset.
Also, no @ref{5e8,,AttributeError} will be raised if triggered while accessing
`spec' or setting an attribute on the module.

This function is preferred over using @ref{100f,,types.ModuleType} to create a
new module as `spec' is used to set as many import-controlled attributes on
the module as possible.


在 3.5 版被加入.

@end deffn

@geindex spec_from_loader() (於 importlib.util 模組中)
@anchor{library/importlib importlib util spec_from_loader}@anchor{a66}
@deffn {函式} importlib.util.spec_from_loader (name, loader, *, origin=None, is_package=None)

A factory function for creating a @ref{2130,,ModuleSpec}
instance based on a loader.  The parameters have the same meaning as they do
for ModuleSpec.  The function uses available @ref{1978,,loader} APIs, such as
@code{InspectLoader.is_package()}, to fill in any missing
information on the spec.


在 3.4 版被加入.

@end deffn

@geindex spec_from_file_location() (於 importlib.util 模組中)
@anchor{library/importlib importlib util spec_from_file_location}@anchor{eaa}
@deffn {函式} importlib.util.spec_from_file_location (name, location, *, loader=None, submodule_search_locations=None)

A factory function for creating a @ref{2130,,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.


在 3.4 版被加入.



在 3.6 版的變更: 接受一個 @ref{59b,,path-like object}。

@end deffn

@geindex source_hash() (於 importlib.util 模組中)
@anchor{library/importlib importlib util source_hash}@anchor{d36}
@deffn {函式} importlib.util.source_hash (source_bytes)

Return the hash of `source_bytes' as bytes. A hash-based @code{.pyc} file embeds
the @ref{d36,,source_hash()} of the corresponding source file's contents in its
header.


在 3.7 版被加入.

@end deffn

@geindex _incompatible_extension_module_restrictions() (於 importlib.util 模組中)
@anchor{library/importlib importlib util _incompatible_extension_module_restrictions}@anchor{49e7}
@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.

你可以透過實作多階段初始化的基本介面 (
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}) 並假稱有多個直譯器（或直譯器各別持有的 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


在 3.12 版被加入.

@end deffn

@geindex LazyLoader (importlib.util 中的類別)
@anchor{library/importlib importlib util LazyLoader}@anchor{ea6}
@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{a63,,exec_module()} as control over what module type
is used for the module is required. For those same reasons, the loader's
@ref{ea7,,create_module()} method must return @code{None} or a
type for which its @code{__class__} attribute can be mutated along with not
using @ref{7f0,,slots}. Finally, modules which substitute the object
placed into @ref{17c0,,sys.modules} will not work as there is no way to properly
replace the module references throughout the interpreter safely;
@ref{2eb,,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


在 3.5 版被加入.



在 3.6 版的變更: Began calling @ref{ea7,,create_module()}, removing the
compatibility warning for @ref{ea8,,importlib.machinery.BuiltinImporter} and
@ref{ea9,,importlib.machinery.ExtensionFileLoader}.


@geindex factory() (importlib.util.LazyLoader 的類別方法)
@anchor{library/importlib importlib util LazyLoader factory}@anchor{49e8}
@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 範例<47>,,importlib util -- Utility code for importers,importlib --- import 的實作
@anchor{library/importlib examples}@anchor{49e9}@anchor{library/importlib importlib-examples}@anchor{49ea}
@subsubsection 範例


@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,,範例<47>
@anchor{library/importlib importing-programmatically}@anchor{49eb}
@subsubsection Importing programmatically


To programmatically import a module, use @ref{735,,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,範例<47>
@anchor{library/importlib checking-if-a-module-can-be-imported}@anchor{49ec}
@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{5a9,,importlib.util.find_spec()}.

Note that if @code{name} is a submodule (contains a dot),
@ref{5a9,,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,範例<47>
@anchor{library/importlib importing-a-source-file-directly}@anchor{49ed}
@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{3e2,,sys.path} being searched. Alternatives should first be considered first,
such as modifying @ref{3e2,,sys.path} when a proper module is required, or using
@ref{49f,,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,範例<47>
@anchor{library/importlib implementing-lazy-imports}@anchor{49ee}
@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 是一個真實的模組物件，
>>> # 但它尚未載入到記憶體中。
>>> lazy_typing.TYPE_CHECKING
False
@end example

@node Setting up an importer,Approximating importlib import_module,Implementing lazy imports,範例<47>
@anchor{library/importlib setting-up-an-importer}@anchor{49ef}
@subsubsection Setting up an importer


For deep customizations of import, you typically want to implement an
@ref{22f8,,importer}. This means managing both the @ref{221c,,finder} and @ref{1978,,loader}
side of things. For finders there are two flavours to choose from depending on
your needs: a @ref{126b,,meta path finder} or a @ref{126c,,path entry finder}. The
former is what you would put on @ref{f22,,sys.meta_path} while the latter is what
you create using a @ref{2309,,path entry hook} on @ref{121f,,sys.path_hooks} which works
with @ref{3e2,,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,範例<47>
@anchor{library/importlib approximating-importlib-import-module}@anchor{49f0}
@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{735,,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 -- 資源的抽象基底類別,importlib --- import 的實作,引入模組
@anchor{library/importlib resources doc}@anchor{49f1}@anchor{library/importlib resources importlib-resources-package-resource-reading-opening-and-access}@anchor{49f2}@anchor{library/importlib resources module-importlib resources}@anchor{7f}@anchor{library/importlib resources translation-repo}@anchor{49f3}
@subsection @code{importlib.resources} -- 套件資源的讀取、開啟與存取


@geindex module; importlib.resources

`原始碼：'Lib/importlib/resources/__init__.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/importlib/resources/__init__.py}


__________________________________________________________________



在 3.7 版被加入.


This module leverages Python's import system to provide access to `resources'
within `packages'.

"Resources" are file-like resources associated with a module or package in
Python. The resources may be contained directly in a package, within a
subdirectory contained in that package, or adjacent to modules outside a
package. Resources may be text or binary. As a result, a package's Python
module sources (.py), compilation artifacts (pycache), and installation
artifacts (like @ref{32a,,reserved filenames}
in directories) are technically de-facto resources of that package.
In practice, however, resources are primarily those non-Python artifacts
exposed specifically by the package author.

Resources can be opened or read in either binary or text mode.

Resources are roughly akin to files inside directories, though it's important
to keep in mind that this is just a metaphor.  Resources and packages `do
not' have to exist as physical files and directories on the file system:
for example, a package and its resources can be imported from a zip file using
@ref{138,,zipimport}.

@cartouche
@quotation 備註 
This module provides functionality similar to pkg_resources@footnote{https://setuptools.readthedocs.io/en/latest/pkg_resources.html} Basic Resource Access@footnote{https://setuptools.readthedocs.io/en/latest/pkg_resources.html#basic-resource-access}
without the performance overhead of that package.  This makes reading
resources included in packages easier, with more stable and consistent
semantics.

The standalone backport of this module provides more information
on using importlib.resources@footnote{https://importlib-resources.readthedocs.io/en/latest/using.html} and
migrating from pkg_resources to importlib.resources@footnote{https://importlib-resources.readthedocs.io/en/latest/migration.html}.
@end quotation
@end cartouche

@ref{10c2,,Loaders} that wish to support resource reading should implement a
@code{get_resource_reader(fullname)} method as specified by
@ref{49b0,,importlib.resources.abc.ResourceReader}.

@geindex Anchor (importlib.resources 中的類別)
@anchor{library/importlib resources importlib resources Anchor}@anchor{49f4}
@deffn {類別} importlib.resources.Anchor

Represents an anchor for resources, either a @ref{100f,,module object} or a module name as a string. Defined as
@code{Union[str, ModuleType]}.
@end deffn

@geindex files() (於 importlib.resources 模組中)
@anchor{library/importlib resources importlib resources files}@anchor{6af}
@deffn {函式} importlib.resources.files (anchor: Anchor | None = None)

Returns a @ref{2f9,,Traversable} object
representing the resource container (think directory) and its resources
(think files). A Traversable may contain other containers (think
subdirectories).

`anchor' is an optional @ref{49f4,,Anchor}. If the anchor is a
package, resources are resolved from that package. If a module,
resources are resolved adjacent to that module (in the same package
or the package root). If the anchor is omitted, the caller's module
is used.


在 3.9 版被加入.



在 3.12 版的變更: `package' parameter was renamed to `anchor'. `anchor' can now
be a non-package module and if omitted will default to the caller's
module. `package' is still accepted for compatibility but will raise
a @ref{1a3,,DeprecationWarning}. Consider passing the anchor positionally or
using @code{importlib_resources >= 5.10} for a compatible interface
on older Pythons.

@end deffn

@geindex as_file() (於 importlib.resources 模組中)
@anchor{library/importlib resources importlib resources as_file}@anchor{6ae}
@deffn {函式} importlib.resources.as_file (traversable)

Given a @ref{2f9,,Traversable} object representing
a file or directory, typically from @ref{6af,,importlib.resources.files()},
return a context manager for use in a @ref{186,,with} statement.
The context manager provides a @ref{266,,pathlib.Path} object.

Exiting the context manager cleans up any temporary file or directory
created when the resource was extracted from e.g. a zip file.

Use @code{as_file} when the Traversable methods
(@code{read_text}, etc) are insufficient and an actual file or directory on
the file system is required.


在 3.9 版被加入.



在 3.12 版的變更: Added support for `traversable' representing a directory.

@end deffn

@menu
* Functional API:: 

@end menu

@node Functional API,,,importlib resources -- 套件資源的讀取、開啟與存取
@anchor{library/importlib resources functional-api}@anchor{49f5}@anchor{library/importlib resources importlib-resources-functional}@anchor{49f6}
@subsubsection Functional API


A set of simplified, backwards-compatible helpers is available.
These allow common operations in a single function call.

For all the following functions:


@itemize -

@item 
`anchor' is an @ref{49f4,,Anchor},
as in @ref{6af,,files()}.
Unlike in @code{files}, it may not be omitted.

@item 
`path_names' are components of a resource's path name, relative to
the anchor.
For example, to get the text of resource named @code{info.txt}, use:

@example
importlib.resources.read_text(my_module, "info.txt")
@end example

Like @ref{2f9,,Traversable.joinpath},
The individual components should use forward slashes (@code{/})
as path separators.
For example, the following are equivalent:

@example
importlib.resources.read_binary(my_module, "pics/painting.png")
importlib.resources.read_binary(my_module, "pics", "painting.png")
@end example

For backward compatibility reasons, functions that read text require
an explicit `encoding' argument if multiple `path_names' are given.
For example, to get the text of @code{info/chapter1.txt}, use:

@example
importlib.resources.read_text(my_module, "info", "chapter1.txt",
                              encoding='utf-8')
@end example
@end itemize

@geindex open_binary() (於 importlib.resources 模組中)
@anchor{library/importlib resources importlib resources open_binary}@anchor{4f9}
@deffn {函式} importlib.resources.open_binary (anchor, *path_names)

Open the named resource for binary reading.

See @ref{49f6,,the introduction} for
details on `anchor' and `path_names'.

This function returns a @ref{23a,,BinaryIO} object,
that is, a binary stream open for reading.

這個函式大致等同於：

@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{4fa}
@deffn {函式} importlib.resources.open_text (anchor, *path_names, encoding='utf-8', errors='strict')

Open the named resource for text reading.
By default, the contents are read as strict UTF-8.

See @ref{49f6,,the introduction} for
details on `anchor' and `path_names'.
`encoding' and `errors' have the same meaning as in built-in @ref{315,,open()}.

For backward compatibility reasons, the `encoding' argument must be given
explicitly if there are multiple `path_names'.
This limitation is scheduled to be removed in Python 3.15.

This function returns a @ref{239,,TextIO} object,
that is, a text stream open for reading.

這個函式大致等同於：

@example
files(anchor).joinpath(*path_names).open('r', encoding=encoding)
@end example


在 3.13 版的變更: Multiple `path_names' are accepted.
`encoding' and `errors' must be given as keyword arguments.

@end deffn

@geindex read_binary() (於 importlib.resources 模組中)
@anchor{library/importlib resources importlib resources read_binary}@anchor{4fc}
@deffn {函式} importlib.resources.read_binary (anchor, *path_names)

以 @ref{192,,bytes} 形式讀取並回傳指定資源的內容。

See @ref{49f6,,the introduction} for
details on `anchor' and `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{4fd}
@deffn {函式} importlib.resources.read_text (anchor, *path_names, encoding='utf-8', errors='strict')

Read and return the contents of the named resource as @ref{169,,str}.
By default, the contents are read as strict UTF-8.

See @ref{49f6,,the introduction} for
details on `anchor' and `path_names'.
`encoding' and `errors' have the same meaning as in built-in @ref{315,,open()}.

For backward compatibility reasons, the `encoding' argument must be given
explicitly if there are multiple `path_names'.
This limitation is scheduled to be removed in Python 3.15.

這個函式大致等同於：

@example
files(anchor).joinpath(*path_names).read_text(encoding=encoding)
@end example


在 3.13 版的變更: Multiple `path_names' are accepted.
`encoding' and `errors' must be given as keyword arguments.

@end deffn

@geindex path() (於 importlib.resources 模組中)
@anchor{library/importlib resources importlib resources path}@anchor{4fb}
@deffn {函式} importlib.resources.path (anchor, *path_names)

Provides the path to the `resource' as an actual file system path.  This
function returns a context manager for use in a @ref{186,,with} statement.
The context manager provides a @ref{266,,pathlib.Path} object.

Exiting the context manager cleans up any temporary files created, e.g.
when the resource needs to be extracted from a zip file.

For example, the @ref{a1d,,stat()} method requires
an actual file system path; it can be used like this:

@example
with importlib.resources.path(anchor, "resource.txt") as fspath:
    result = fspath.stat()
@end example

See @ref{49f6,,the introduction} for
details on `anchor' and `path_names'.

這個函式大致等同於：

@example
as_file(files(anchor).joinpath(*path_names))
@end example


在 3.13 版的變更: Multiple `path_names' are accepted.
`encoding' and `errors' must be given as keyword arguments.

@end deffn

@geindex is_resource() (於 importlib.resources 模組中)
@anchor{library/importlib resources importlib resources is_resource}@anchor{4f8}
@deffn {函式} importlib.resources.is_resource (anchor, *path_names)

Return @code{True} if the named resource exists, otherwise @code{False}.
This function does not consider directories to be resources.

See @ref{49f6,,the introduction} for
details on `anchor' and `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{4fe}
@deffn {函式} importlib.resources.contents (anchor, *path_names)

Return an iterable over the named items within the package or path.
The iterable returns names of resources (e.g. files) and non-resources
(e.g. directories) as @ref{169,,str}.
The iterable does not recurse into subdirectories.

See @ref{49f6,,the introduction} for
details on `anchor' and `path_names'.

這個函式大致等同於：

@example
for resource in files(anchor).joinpath(*path_names).iterdir():
    yield resource.name
@end example


在 3.11 版之後被棄用: Prefer @code{iterdir()} as above, which offers more control over the
results and richer functionality.

@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 -- 資源的抽象基底類別,importlib metadata -- 存取套件的元資料,importlib resources -- 套件資源的讀取、開啟與存取,引入模組
@anchor{library/importlib resources abc doc}@anchor{49f7}@anchor{library/importlib resources abc importlib-resources-abc-abstract-base-classes-for-resources}@anchor{49f8}@anchor{library/importlib resources abc module-importlib resources abc}@anchor{80}@anchor{library/importlib resources abc translation-repo}@anchor{49f9}
@subsection @code{importlib.resources.abc} -- 資源的抽象基底類別


@geindex module; importlib.resources.abc

`原始碼：'Lib/importlib/resources/abc.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/importlib/resources/abc.py}


__________________________________________________________________



在 3.11 版被加入.


@geindex ResourceReader (importlib.resources.abc 中的類別)
@anchor{library/importlib resources abc importlib resources abc ResourceReader}@anchor{49b0}
@deffn {類別} importlib.resources.abc.ResourceReader

`Superseded by TraversableResources'

An @ref{13b7,,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{59b,,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{87e,,None}. An object compatible with this ABC should only be
returned when the specified module is a package.


在 3.12 版之後被棄用: Use @ref{2f8,,importlib.resources.abc.TraversableResources} instead.


@geindex open_resource() (importlib.resources.abc.ResourceReader 的方法)
@anchor{library/importlib resources abc importlib resources abc ResourceReader open_resource}@anchor{49fa}
@deffn {方法} abstractmethod open_resource (resource)

Returns an opened, @ref{28ad,,file-like object} for binary reading
of the `resource'.

If the resource cannot be found, @ref{264,,FileNotFoundError} is
raised.
@end deffn

@geindex resource_path() (importlib.resources.abc.ResourceReader 的方法)
@anchor{library/importlib resources abc importlib resources abc ResourceReader resource_path}@anchor{49fb}
@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{264,,FileNotFoundError}.
@end deffn

@geindex is_resource() (importlib.resources.abc.ResourceReader 的方法)
@anchor{library/importlib resources abc importlib resources abc ResourceReader is_resource}@anchor{49fc}
@deffn {方法} abstractmethod is_resource (name)

Returns @code{True} if the named `name' is considered a resource.
@ref{264,,FileNotFoundError} is raised if `name' does not exist.
@end deffn

@geindex contents() (importlib.resources.abc.ResourceReader 的方法)
@anchor{library/importlib resources abc importlib resources abc ResourceReader contents}@anchor{49fd}
@deffn {方法} abstractmethod contents ()

Returns an @ref{1428,,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{49fc,,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{2f9}
@deffn {類別} importlib.resources.abc.Traversable

An object with a subset of @ref{266,,pathlib.Path} methods suitable for
traversing directories and opening files.

For a representation of the object on the file-system, use
@ref{6ae,,importlib.resources.as_file()}.

@geindex name (importlib.resources.abc.Traversable 的屬性)
@anchor{library/importlib resources abc importlib resources abc Traversable name}@anchor{49fe}
@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{49ff}
@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{4a00}
@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{4a01}
@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{4a02}
@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{4a03}
@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{4a04}
@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{2aec,,pathlib.Path.open}).

When opening as text, accepts encoding parameters such as those
accepted by @ref{9b7,,io.TextIOWrapper}.
@end deffn

@geindex read_bytes() (importlib.resources.abc.Traversable 的方法)
@anchor{library/importlib resources abc importlib resources abc Traversable read_bytes}@anchor{4a05}
@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{4a06}
@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{2f8}
@deffn {類別} importlib.resources.abc.TraversableResources

An abstract base class for resource readers capable of serving
the @ref{6af,,importlib.resources.files()} interface. Subclasses
@ref{49b0,,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{4a07}
@deffn {方法} abstractmethod files ()

Returns a @ref{2f9,,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 -- 存取套件的元資料,sys path 模組搜尋路徑的初始化,importlib resources abc -- 資源的抽象基底類別,引入模組
@anchor{library/importlib metadata doc}@anchor{4a08}@anchor{library/importlib metadata importlib-metadata-accessing-package-metadata}@anchor{4a09}@anchor{library/importlib metadata module-importlib metadata}@anchor{7e}@anchor{library/importlib metadata translation-repo}@anchor{4a0a}@anchor{library/importlib metadata using}@anchor{4a0b}
@subsection @code{importlib.metadata} -- 存取套件的元資料


@geindex module; importlib.metadata


在 3.8 版被加入.



在 3.10 版的變更: @code{importlib.metadata} is no longer provisional.


`原始碼：'Lib/importlib/metadata/__init__.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/importlib/metadata/__init__.py}

@code{importlib.metadata} is a library that provides access to
the metadata of an installed Distribution Package@footnote{https://packaging.python.org/en/latest/glossary/#term-Distribution-Package},
such as its entry points
or its top-level names (Import Package@footnote{https://packaging.python.org/en/latest/glossary/#term-Import-Package}s, modules, if any).
Built in part on Python's import system, this library
intends to replace similar functionality in the entry point API@footnote{https://setuptools.readthedocs.io/en/latest/pkg_resources.html#entry-points} and metadata API@footnote{https://setuptools.readthedocs.io/en/latest/pkg_resources.html#metadata-api} of @code{pkg_resources}. Along with
@ref{7f,,importlib.resources},
this package can eliminate the need to use the older and less efficient
@code{pkg_resources} package.

@code{importlib.metadata} operates on third-party `distribution packages'
installed into Python's @code{site-packages} directory via tools such as
pip@footnote{https://pypi.org/project/pip/}.
Specifically, it works with distributions with discoverable
@code{dist-info} or @code{egg-info} directories,
and metadata defined by the Core metadata specifications@footnote{https://packaging.python.org/en/latest/specifications/core-metadata/#core-metadata}.

@cartouche
@quotation 重要 
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{a0a,,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{3e2,,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<2>. 
* Functional API: Functional API<2>. 
* Distributions:: 
* Distribution Discovery:: 
* Implementing Custom Providers:: 

@end menu

@node Overview<2>,Functional API<2>,,importlib metadata -- 存取套件的元資料
@anchor{library/importlib metadata overview}@anchor{4a0c}
@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{583,,EntryPoint} objects.

You can get the @ref{4a0d,,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{4a0e,,distribution's version number}, list its
@ref{4a0f,,constituent files}, and get a list of the distribution's
@ref{4a10,,Distribution requirements}.

@geindex PackageNotFoundError
@anchor{library/importlib metadata importlib metadata PackageNotFoundError}@anchor{4a11}
@deffn {例外} importlib.metadata.PackageNotFoundError

Subclass of @ref{d35,,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<2>,Distributions,Overview<2>,importlib metadata -- 存取套件的元資料
@anchor{library/importlib metadata functional-api}@anchor{4a12}
@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<2>
@anchor{library/importlib metadata entry-points}@anchor{583}@anchor{library/importlib metadata id2}@anchor{4a13}
@subsubsection Entry points


@geindex entry_points() (於 importlib.metadata 模組中)
@anchor{library/importlib metadata importlib metadata entry_points}@anchor{4a14}
@deffn {函式} importlib.metadata.entry_points (**select_params)

Returns a @ref{4a15,,EntryPoints} instance describing entry points for the
current environment. Any given keyword parameters are passed to the
@code{select()} method for comparison to the attributes of
the individual entry point definitions.

Note: it is not currently possible to query for entry points based on
their @code{EntryPoint.dist} attribute (as different @code{Distribution}
instances do not currently compare equal, even if they have the same attributes)
@end deffn

@geindex EntryPoints (importlib.metadata 中的類別)
@anchor{library/importlib metadata importlib metadata EntryPoints}@anchor{4a15}
@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{4a16}
@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{582,,__getitem__()}).


@node Distribution metadata,Distribution versions,Entry points,Functional API<2>
@anchor{library/importlib metadata distribution-metadata}@anchor{4a17}@anchor{library/importlib metadata metadata}@anchor{4a0d}
@subsubsection Distribution metadata


@geindex metadata() (於 importlib.metadata 模組中)
@anchor{library/importlib metadata importlib metadata metadata}@anchor{4a18}
@deffn {函式} importlib.metadata.metadata (distribution_name)

Return the distribution metadata corresponding to the named
distribution package as a @ref{4a19,,PackageMetadata} instance.

Raises @ref{4a11,,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{4a19}
@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{4a19,,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.

新增 @code{json} 屬性。


@node Distribution versions,Distribution files,Distribution metadata,Functional API<2>
@anchor{library/importlib metadata distribution-versions}@anchor{4a1a}@anchor{library/importlib metadata version}@anchor{4a0e}
@subsubsection Distribution versions


@geindex version() (於 importlib.metadata 模組中)
@anchor{library/importlib metadata importlib metadata version}@anchor{18cd}
@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{4a11,,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<2>
@anchor{library/importlib metadata distribution-files}@anchor{4a1b}@anchor{library/importlib metadata files}@anchor{4a0f}
@subsubsection Distribution files


@geindex files() (於 importlib.metadata 模組中)
@anchor{library/importlib metadata importlib metadata files}@anchor{4a1c}
@deffn {函式} importlib.metadata.files (distribution_name)

Return the full set of files contained within the named
distribution package.

Raises @ref{4a11,,PackageNotFoundError} if the named distribution
package is not installed in the current Python environment.

Returns @ref{87e,,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{4a1d}
@deffn {類別} importlib.metadata.PackagePath

A @ref{6c6,,pathlib.PurePath} derived object with additional @code{dist},
@code{size}, and @code{hash} properties corresponding to the distribution
package's installation metadata for that file.
@end deffn

The @code{files()} function takes a
Distribution Package@footnote{https://packaging.python.org/en/latest/glossary/#term-Distribution-Package}
name and returns all of the files installed by this distribution. Each file is reported
as a @ref{4a1d,,PackagePath} instance. For example:

@example
>>> util = [p for p in files('wheel') if 'util.py' in str(p)][0]
>>> util
PackagePath('wheel/util.py')
>>> util.size
859
>>> util.dist
<importlib.metadata._hooks.PathDistribution object at 0x101e0cef0>
>>> util.hash
<FileHash mode: sha256 value: bYkw5oMccfazVCoYQwKkkemoVyMAFoR34mmKBx8R1NI>
@end example

Once you have the file, you can also read its contents:

@example
>>> print(util.read_text())
import base64
import sys
...
def as_bytes(s):
    if isinstance(s, text_type):
        return s.encode('utf-8')
    return s
@end example

You can also use the @code{locate()} method to get the absolute
path to the file:

@example
>>> util.locate()
PosixPath('/home/gustav/example/lib/site-packages/wheel/util.py')
@end example

In the case where the metadata file listing files
(@code{RECORD} or @code{SOURCES.txt}) is missing, @code{files()} will
return @ref{87e,,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<2>
@anchor{library/importlib metadata distribution-requirements}@anchor{4a1e}@anchor{library/importlib metadata requirements}@anchor{4a10}
@subsubsection Distribution requirements


@geindex requires() (於 importlib.metadata 模組中)
@anchor{library/importlib metadata importlib metadata requires}@anchor{4a1f}
@deffn {函式} importlib.metadata.requires (distribution_name)

Return the declared dependency specifiers for the named
distribution package.

Raises @ref{4a11,,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{a0a}
@node Mapping import to distribution packages,,Distribution requirements,Functional API<2>
@anchor{library/importlib metadata import-distribution-package-mapping}@anchor{4a20}@anchor{library/importlib metadata mapping-import-to-distribution-packages}@anchor{4a21}
@subsubsection Mapping import to distribution packages


@geindex packages_distributions() (於 importlib.metadata 模組中)
@anchor{library/importlib metadata importlib metadata packages_distributions}@anchor{4a22}
@deffn {函式} importlib.metadata.packages_distributions ()

Return a mapping from the top level module and import package
names found via @ref{f22,,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.


在 3.10 版被加入.


@node Distributions,Distribution Discovery,Functional API<2>,importlib metadata -- 存取套件的元資料
@anchor{library/importlib metadata distributions}@anchor{a0b}@anchor{library/importlib metadata id9}@anchor{4a23}
@subsubsection Distributions


@geindex distribution() (於 importlib.metadata 模組中)
@anchor{library/importlib metadata importlib metadata distribution}@anchor{4a24}
@deffn {函式} importlib.metadata.distribution (distribution_name)

Return a @ref{4a25,,Distribution} instance describing the named
distribution package.

Raises @ref{4a11,,PackageNotFoundError} if the named distribution
package is not installed in the current Python environment.
@end deffn

@geindex Distribution (importlib.metadata 中的類別)
@anchor{library/importlib metadata importlib metadata Distribution}@anchor{4a25}
@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.
@end deffn

While the module level API described above is the most common and convenient usage,
you can get all of that information from the @code{Distribution} class.
@code{Distribution} is an abstract object that represents the metadata for
a Python Distribution Package@footnote{https://packaging.python.org/en/latest/glossary/#term-Distribution-Package}.
You can get the concrete @code{Distribution} subclass instance for an installed
distribution package by calling the @ref{4a24,,distribution()} function:

@example
>>> from importlib.metadata import distribution
>>> dist = distribution('wheel')
>>> type(dist)
<class 'importlib.metadata.PathDistribution'>
@end example

Thus, an alternative way to get the version number is through the
@code{Distribution} instance:

@example
>>> dist.version
'0.32.3'
@end example

There are all kinds of additional metadata available on @code{Distribution}
instances:

@example
>>> dist.metadata['Requires-Python']
'>=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*'
>>> dist.metadata['License']
'MIT'
@end example

For editable packages, an @code{origin} property may present 
@geindex Python Enhancement Proposals; PEP 610
PEP 610@footnote{https://peps.python.org/pep-0610/}
metadata:

@example
>>> dist.origin.url
'file:///path/to/wheel-0.32.3.editable-py3-none-any.whl'
@end example

The full set of available metadata is not described here.
See the PyPA Core metadata specification@footnote{https://packaging.python.org/en/latest/specifications/core-metadata/#core-metadata} for additional details.


在 3.13 版被加入: 新增 @code{.origin} 屬性 (property)。


@node Distribution Discovery,Implementing Custom Providers,Distributions,importlib metadata -- 存取套件的元資料
@anchor{library/importlib metadata distribution-discovery}@anchor{4a26}
@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{192,,bytes} objects on @code{sys.path}.

@item 
@code{importlib.metadata} will incidentally honor @ref{266,,pathlib.Path} objects on @code{sys.path} even though such values will be ignored for imports.
@end itemize

@node Implementing Custom Providers,,Distribution Discovery,importlib metadata -- 存取套件的元資料
@anchor{library/importlib metadata implementing-custom-providers}@anchor{4a27}
@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{3e2,,sys.path} searches, or
package loaders directly,
the metadata for a distribution is found through import
system @ref{22f6,,finders}. To find a distribution package's metadata,
@code{importlib.metadata} queries the list of @ref{126b,,meta path finders} on
@ref{f22,,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{a67,,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{f22,,sys.meta_path} and presents this extended interface as the
@code{DistributionFinder} abstract base class, which defines this abstract
method:

@example
@@abc.abstractmethod
def find_distributions(context=DistributionFinder.Context()) -> 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 @code{DistributionFinder.Context} object provides @code{.path} and @code{.name}
properties indicating the path to search and name to match and may
supply other relevant context 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
* 範例: 範例<48>. 

@end menu

@node 範例<48>,,,Implementing Custom Providers
@anchor{library/importlib metadata example}@anchor{4a28}
@subsubsection 範例


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
@code{DistributionFinder}:

@example
from importlib.metadata import DistributionFinder

class DatabaseImporter(DistributionFinder):
    ...

    def find_distributions(self, context=DistributionFinder.Context()):
        query = dict(name=context.name) if context.name else @{@}
        for dist_record in self.db.query_distributions(query):
            yield DatabaseDistribution(dist_record)
@end example

In this way, @code{query_distributions} would return records for
each distribution served by the database matching the query. For
example, if @code{requests-1.0} is in the database, @code{find_distributions}
would yield a @code{DatabaseDistribution} for @code{Context(name='requests')}
or @code{Context(name=None)}.

For the sake of simplicity, this example ignores @code{context.path}. The
@code{path} attribute defaults to @code{sys.path} and is the set of import paths to
be considered in the search. A @code{DatabaseImporter} could potentially function
without any concern for a search path. Assuming the importer does no
partitioning, the "path" would be irrelevant. In order to illustrate the
purpose of @code{path}, the example would need to illustrate a more complex
@code{DatabaseImporter} whose behavior varied depending on
@code{sys.path}/@code{PYTHONPATH}. In that case, the @code{find_distributions} should
honor the @code{context.path} and only yield @code{Distribution}s pertinent to that
path.

@code{DatabaseDistribution}, then, would look something like:

@example
class DatabaseDistribution(importlib.metadata.Distribution):
    def __init__(self, record):
        self.record = record

    def read_text(self, filename):
        """
        Read a file like "METADATA" for the current distribution.
        """
        if filename == "METADATA":
            return f"""Name: @{self.record.name@}
Version: @{self.record.version@}
"""
        if filename == "entry_points.txt":
            return "\n".join(
              f"""[@{ep.group@}]\n@{ep.name@}=@{ep.value@}"""
              for ep in self.record.entry_points)

    def locate_file(self, path):
        raise RuntimeError("This distribution has no file system")
@end example

This basic implementation should provide metadata and entry points for
packages served by the @code{DatabaseImporter}, assuming that the
@code{record} supplies suitable @code{.name}, @code{.version}, and
@code{.entry_points} attributes.

The @code{DatabaseDistribution} may also provide other metadata files, like
@code{RECORD} (required for @code{Distribution.files}) or override the
implementation of @code{Distribution.files}. See the source for more inspiration.

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node sys path 模組搜尋路徑的初始化,,importlib metadata -- 存取套件的元資料,引入模組
@anchor{library/sys_path_init doc}@anchor{4a29}@anchor{library/sys_path_init sys-path-init}@anchor{1849}@anchor{library/sys_path_init the-initialization-of-the-sys-path-module-search-path}@anchor{4a2a}@anchor{library/sys_path_init translation-repo}@anchor{4a2b}
@subsection @code{sys.path} 模組搜尋路徑的初始化


A module search path is initialized when Python starts. This module search path
may be accessed at @ref{3e2,,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{1a8,,-c}
command, or @ref{23c,,-m} module.

The 
@geindex PYTHONPATH
@geindex 環境變數; PYTHONPATH
@ref{1218,,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{1218,,PYTHONPATH} will affect all installed Python versions/environments.
Be wary of setting this in your shell profile or global environment variables.
The @ref{cc,,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{2115,,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{3ee,,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{b29,,sys.platlibdir} and 
@geindex PYTHONPLATLIBDIR
@geindex 環境變數; PYTHONPLATLIBDIR
@ref{1bf5,,PYTHONPLATLIBDIR}.

Once found, @code{prefix} and @code{exec_prefix} are available at
@ref{3e4,,sys.base_prefix} and @ref{3e8,,sys.base_exec_prefix} respectively.

If 
@geindex PYTHONHOME
@geindex 環境變數; PYTHONHOME
@ref{3ee,,PYTHONHOME} is not set, and a @code{pyvenv.cfg} file is found alongside
the main executable, or in its parent directory, @ref{3e6,,sys.prefix} and
@ref{3e9,,sys.exec_prefix} get set to the directory containing @code{pyvenv.cfg},
otherwise they are set to the same value as @ref{3e4,,sys.base_prefix} and
@ref{3e8,,sys.base_exec_prefix}, respectively.
This is used by @ref{476b,,虛擬環境}.

Finally, the @ref{cc,,site} module is processed and @code{site-packages} directories
are added to the module search path. A common way to customize the search path is
to create @ref{cd,,sitecustomize} or @ref{114,,usercustomize} modules as described in
the @ref{cc,,site} module documentation.

@cartouche
@quotation 備註 
Certain command line options may further affect path calculations.
See @ref{b4d,,-E}, @ref{b4e,,-I}, @ref{1586,,-s} and @ref{13a9,,-S} for further details.
@end quotation
@end cartouche


在 3.14 版的變更: @ref{3e6,,sys.prefix} and @ref{3e9,,sys.exec_prefix} are now set to the
@code{pyvenv.cfg} directory during the path initialization. This was previously
done by @ref{cc,,site}, therefore affected by @ref{13a9,,-S}.


@menu
* 虛擬環境:: 
* _pth 檔案:: 
* Embedded Python:: 

@end menu

@node 虛擬環境,_pth 檔案,,sys path 模組搜尋路徑的初始化
@anchor{library/sys_path_init sys-path-init-virtual-environments}@anchor{476b}@anchor{library/sys_path_init virtual-environments}@anchor{4a2c}
@subsubsection 虛擬環境


Virtual environments place a @code{pyvenv.cfg} file in their prefix, which causes
@ref{3e6,,sys.prefix} and @ref{3e9,,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{3e4,,sys.base_prefix} and @ref{3e8,,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{cc,,site} initialization.
Please refer to @ref{cc,,site}'s
@ref{476c,,virtual environments documentation}.

@cartouche
@quotation 備註 
@geindex PYTHONHOME
@geindex 環境變數; PYTHONHOME
@ref{3ee,,PYTHONHOME} overrides the @code{pyvenv.cfg} detection.
@end quotation
@end cartouche

@cartouche
@quotation 備註 
There are other ways how "virtual environments" could be implemented, this
documentation refers implementations based on the @code{pyvenv.cfg} mechanism,
such as @ref{117,,venv}. Most virtual environment implementations follow the
model set by @ref{117,,venv}, but there may be exotic implementations that
diverge from it.
@end quotation
@end cartouche

@node _pth 檔案,Embedded Python,虛擬環境,sys path 模組搜尋路徑的初始化
@anchor{library/sys_path_init pth-files}@anchor{4a2d}
@subsubsection _pth 檔案


To completely override @ref{3e2,,sys.path} create a @code{._pth} file with the same
name as the shared library or executable (@code{python._pth} or @code{python311._pth}).
The shared library path is always known on Windows, however it may not be
available on other platforms. In the @code{._pth} file specify one line for each path
to add to @ref{3e2,,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{cc,,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{cc,,site} module when @code{import site} has been specified.

@node Embedded Python,,_pth 檔案,sys path 模組搜尋路徑的初始化
@anchor{library/sys_path_init embedded-python}@anchor{4a2e}
@subsubsection Embedded Python


If Python is embedded within another application @ref{3f5,,Py_InitializeFromConfig()} and
the @ref{3f4,,PyConfig} structure can be used to initialize Python. The path specific
details are described at @ref{aa1,,Python 路徑配置}.


@subsubheading 也參考



@itemize *

@item 
@ref{e15,,找尋模組} 有關於 Windows 的詳細資訊。

@item 
@ref{200b,,在 Unix 平臺上使用 Python} 有關於 Unix 的詳細資訊。
@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 語言服務,MS Windows 特有服務,引入模組,Python 標準函式庫 Standard Library
@anchor{library/language doc}@anchor{4a2f}@anchor{library/language language}@anchor{4a30}@anchor{library/language python-language-services}@anchor{4a31}@anchor{library/language translation-repo}@anchor{4a32}
@section Python 語言服務


Python 提供了許多模組來協助處理 Python 語言。這些模組支援標記化、剖析、語法分析、位元組碼反組譯，以及其他各種設施。

這些模組包括：

@menu
* ast: ast --- 抽象語法樹 Abstract Syntax Trees. 抽象語法樹 (Abstract Syntax Trees)
* symtable: symtable --- 存取編譯器的符號表. 存取編譯器的符號表
* token: token --- 與 Python 剖析樹一起使用的常數. 與 Python 剖析樹一起使用的常數
* keyword: keyword --- 檢驗 Python 關鍵字. 檢驗 Python 關鍵字
* tokenize: tokenize --- Tokenizer for Python source. Tokenizer for Python source
* tabnanny: tabnanny --- 偵測不良縮排. 偵測不良縮排
* pyclbr: pyclbr --- Python 模組瀏覽器支援. Python 模組瀏覽器支援
* py_compile — 編譯 Python 來源檔案:: 
* compileall: compileall --- 位元組編譯 Python 函式庫. 位元組編譯 Python 函式庫
* dis: dis --- Python bytecode 的反組譯器. Python bytecode 的反組譯器
* pickletools: pickletools --- pickle 開發者的工具. pickle 開發者的工具

@end menu

@node ast --- 抽象語法樹 Abstract Syntax Trees,symtable --- 存取編譯器的符號表,,Python 語言服務
@anchor{library/ast doc}@anchor{4a33}@anchor{library/ast ast-abstract-syntax-trees}@anchor{4a34}@anchor{library/ast module-ast}@anchor{9}
@subsection @code{ast} --- 抽象語法樹 (Abstract Syntax Trees)


@geindex module; ast

@c import ast

`原始碼：'Lib/ast.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/ast.py}


__________________________________________________________________


@ref{9,,ast} 模組可以幫助 Python 應用程式處理 Python 抽象語法文法 (abstract syntax grammar) 樹狀資料結構。抽象語法本身可能會隨著每個 Python 版本發布而改變；此模組有助於以程式化的方式來得知目前文法的面貌。

要生成抽象語法樹，可以透過將 @ref{4a35,,ast.PyCF_ONLY_AST} 作為旗標傳遞給內建函式 @ref{4ac,,compile()} 或使用此模組所提供的 @ref{1c2,,parse()} 輔助函式。結果將會是一個物件的樹，其類別都繼承自 @ref{4be,,ast.AST}。可以使用內建的 @ref{4ac,,compile()} 函式將抽象語法樹編譯成 Python 程式碼物件。

@menu
* 抽象文法 (Abstract Grammar): 抽象文法 Abstract Grammar. 
* 節點 (Node) 類別: 節點 Node 類別. 
* ast 輔助程式:: 
* 編譯器旗標: 編譯器旗標<2>. 
* 命令列用法: 命令列用法<9>. 

@end menu

@node 抽象文法 Abstract Grammar,節點 Node 類別,,ast --- 抽象語法樹 Abstract Syntax Trees
@anchor{library/ast abstract-grammar}@anchor{4a36}@anchor{library/ast id1}@anchor{4a37}
@subsubsection 抽象文法 (Abstract Grammar)


抽象文法目前定義如下：

@example
-- ASDL's 4 builtin types are:
-- identifier, int, string, constant

module Python
@{
    mod = Module(stmt* body, type_ignore* type_ignores)
        | Interactive(stmt* body)
        | Expression(expr body)
        | FunctionType(expr* argtypes, expr returns)

    stmt = FunctionDef(identifier name, arguments args,
                       stmt* body, expr* decorator_list, expr? returns,
                       string? type_comment, type_param* type_params)
          | AsyncFunctionDef(identifier name, arguments args,
                             stmt* body, expr* decorator_list, expr? returns,
                             string? type_comment, type_param* type_params)

          | ClassDef(identifier name,
             expr* bases,
             keyword* keywords,
             stmt* body,
             expr* decorator_list,
             type_param* type_params)
          | Return(expr? value)

          | Delete(expr* targets)
          | Assign(expr* targets, expr value, string? type_comment)
          | TypeAlias(expr name, type_param* type_params, expr value)
          | AugAssign(expr target, operator op, expr value)
          -- 'simple' indicates that we annotate simple name without parens
          | AnnAssign(expr target, expr annotation, expr? value, int simple)

          -- use 'orelse' because else is a keyword in target languages
          | For(expr target, expr iter, stmt* body, stmt* orelse, string? type_comment)
          | AsyncFor(expr target, expr iter, stmt* body, stmt* orelse, string? type_comment)
          | While(expr test, stmt* body, stmt* orelse)
          | If(expr test, stmt* body, stmt* orelse)
          | With(withitem* items, stmt* body, string? type_comment)
          | AsyncWith(withitem* items, stmt* body, string? type_comment)

          | Match(expr subject, match_case* cases)

          | Raise(expr? exc, expr? cause)
          | Try(stmt* body, excepthandler* handlers, stmt* orelse, stmt* finalbody)
          | TryStar(stmt* body, excepthandler* handlers, stmt* orelse, stmt* finalbody)
          | Assert(expr test, expr? msg)

          | Import(alias* names)
          | ImportFrom(identifier? module, alias* names, int? level)

          | Global(identifier* names)
          | Nonlocal(identifier* names)
          | Expr(expr value)
          | Pass | Break | Continue

          -- col_offset is the byte offset in the utf8 string the parser uses
          attributes (int lineno, int col_offset, int? end_lineno, int? end_col_offset)

          -- BoolOp() can use left & right?
    expr = BoolOp(boolop op, expr* values)
         | NamedExpr(expr target, expr value)
         | BinOp(expr left, operator op, expr right)
         | UnaryOp(unaryop op, expr operand)
         | Lambda(arguments args, expr body)
         | IfExp(expr test, expr body, expr orelse)
         | Dict(expr?* keys, expr* values)
         | Set(expr* elts)
         | ListComp(expr elt, comprehension* generators)
         | SetComp(expr elt, comprehension* generators)
         | DictComp(expr key, expr value, comprehension* generators)
         | GeneratorExp(expr elt, comprehension* generators)
         -- the grammar constrains where yield expressions can occur
         | Await(expr value)
         | Yield(expr? value)
         | YieldFrom(expr value)
         -- need sequences for compare to distinguish between
         -- x < 4 < 3 and (x < 4) < 3
         | Compare(expr left, cmpop* ops, expr* comparators)
         | Call(expr func, expr* args, keyword* keywords)
         | FormattedValue(expr value, int conversion, expr? format_spec)
         | 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 類別,ast 輔助程式,抽象文法 Abstract Grammar,ast --- 抽象語法樹 Abstract Syntax Trees
@anchor{library/ast node-classes}@anchor{4a38}
@subsubsection 節點 (Node) 類別


@geindex AST (ast 中的類別)
@anchor{library/ast ast AST}@anchor{4be}
@deffn {類別} ast.AST

這是所有 AST 節點類別的基礎。實際的節點類別是衍生自 @code{Parser/Python.asdl} 檔案，該檔案在@ref{4a36,,上方} 重現。它們被定義於 @code{_ast} 的 C 模組中，並於 @ref{9,,ast} 中重新匯出。

抽象文法中為每個左側符號定義了一個類別（例如 @code{ast.stmt} 或 @code{ast.expr}）。此外，也為每個右側的建構函式 (constructor) 定義了一個類別；這些類別繼承自左側樹的類別。例如，@ref{1c7b,,ast.BinOp} 繼承自 @code{ast.expr}。對於具有替代方案（即為「和 (sums)」）的生產規則，左側類別是抽象的：僅有特定建構函式節點的實例會被建立。

@geindex ? （問號）;於 AST 文法中

@geindex * （星號）;於 AST 文法中

@geindex _fields (ast.AST 的屬性)
@anchor{library/ast ast AST _fields}@anchor{1764}
@deffn {屬性} _fields

每個具體類別都有一個屬性 @code{_fields}，它會給出所有子節點的名稱。

具體類別的每個實例對於每個子節點都有一個屬性，其型別如文法中所定義。例如，@ref{1c7b,,ast.BinOp} 實例具有型別為 @code{ast.expr} 的屬性 @code{left}。

如果這些屬性在文法中被標記為可選（使用問號），則該值可能為 @code{None}。如果屬性可以有零個或多個值（用星號標記），則這些值將表示為 Python 串列。使用 @ref{4ac,,compile()} 編譯 AST 時，所有可能的屬性都必須存在並且具有有效值。
@end deffn

@geindex _field_types (ast.AST 的屬性)
@anchor{library/ast ast AST _field_types}@anchor{4bf}
@deffn {屬性} _field_types

每個具體類別上的 @code{_field_types} 屬性是將欄位名稱（也在 @ref{1764,,_fields} 中列出）對映到其型別的字典。

@example
>>> ast.TypeVar._field_types
@{'name': <class 'str'>, 'bound': ast.expr | None, 'default_value': ast.expr | None@}
@end example


在 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{4a39}
@deffn {屬性} lineno
@anchor{library/ast ast AST col_offset}@anchor{4a3a}
@deffnx {屬性} col_offset
@anchor{library/ast ast AST end_lineno}@anchor{4a3b}
@deffnx {屬性} end_lineno
@anchor{library/ast ast AST end_col_offset}@anchor{4a3c}
@deffnx {屬性} end_col_offset

@code{ast.expr} 和 @code{ast.stmt} 子類別的實例具有 @ref{4a39,,lineno}、@ref{4a3a,,col_offset}、@ref{4a3b,,end_lineno} 和 @ref{4a3c,,end_col_offset} 屬性。@ref{4a39,,lineno} 和 @ref{4a3b,,end_lineno} 是原始文本跨度 (source text span) 的第一個和最後一個列號（1-indexed，因此第一列號是 1）以及 @ref{4a3a,,col_offset} 和 @ref{4a3c,,end_col_offset} 是生成節點的第一個和最後一個標記對應的 UTF-8 位元組偏移量。會記錄 UTF-8 偏移量是因為剖析器 (parser) 內部使用 UTF-8。

請注意，編譯器並不需要結束位置，因此其為可選的。結束偏移量在最後一個符號`之後'，例如可以使用 @code{source_line[node.col_offset : node.end_col_offset]} 來取得單列運算式節點 (expression node) 的原始片段。
@end deffn

@code{ast.T} 類別的建構函式按以下方式剖析其引數：


@itemize *

@item 
如果有位置引數，則必須與 @code{T._fields} 中的項目一樣多；它們將被賦値為這些名稱的屬性。

@item 
如果有關鍵字引數，它們會將相同名稱的屬性設定為給定值。
@end itemize

例如，要建立並填充 (populate) @ref{4936,,ast.UnaryOp} 節點，你可以使用：

@example
node = ast.UnaryOp(ast.USub(), ast.Constant(5, lineno=0, col_offset=0),
                   lineno=0, col_offset=0)
@end example

如果建構函式中省略了文法中可選的欄位，則它預設為 @code{None}。如果省略串列欄位，則預設為空串列。如果省略 @code{ast.expr_context} 型別的欄位，則預設為 @ref{4bd,,Load()}。如果省略任何其他欄位，則會引發 @ref{1a3,,DeprecationWarning}，且 AST 節點將沒有此欄位。在 Python 3.15 中，這種情況會引發錯誤。
@end deffn


在 3.8 版的變更: @ref{2ee,,ast.Constant} 類別現在用於所有常數。



在 3.9 版的變更: 以它們的值表示簡單索引，擴充切片 (slice) 則以元組 (tuple) 表示。



在 3.14 版的變更: The @ref{828,,__repr__()} output of @ref{4be,,AST} nodes includes
the values of the node fields.



在 3.8 版之後被棄用: 舊的類別 @code{ast.Num}、@code{ast.Str}、@code{ast.Bytes}、@code{ast.NameConstant} 和 @code{ast.Ellipsis} 仍然可用，但它們將在未來的 Python 釋出版本中移除。與此同時，實例化它們將回傳不同類別的實例。



在 3.9 版之後被棄用: 舊的類別 @code{ast.Index} 和 @code{ast.ExtSlice} 仍然可用，但它們將在未來的 Python 版本中刪除。同時，實例化它們會回傳不同類別的實例。



Deprecated since version 3.13, will be removed in version 3.15: 先前版本的 Python 允許建立缺少必填欄位的 AST 節點。同樣地，AST 節點建構函式允許將任意關鍵字引數設為 AST 節點的屬性，即使它們與 AST 節點的任何欄位都不匹配。此行為已被棄用，並將在 Python 3.15 中刪除。


@cartouche
@quotation 備註 
這裡顯示的特定節點類別的描述最初是從出色的 Green Tree Snakes@footnote{https://greentreesnakes.readthedocs.io/en/latest/} 專案和所有貢獻者那裡改編而來的。
@end quotation
@end cartouche

@menu
* 根節點:: 
* 文本 (Literals): 文本 Literals. 
* 變數:: 
* 運算式: 運算式<2>. 
* 陳述式:: 
* 流程控制:: 
* 模式匹配 (pattern matching): 模式匹配 pattern matching. 
* Type annotations:: 
* 型別參數 (type parameters): 型別參數 type parameters. 
* 函式和類別定義:: 
* async 和 await:: 

@end menu

@node 根節點,文本 Literals,,節點 Node 類別
@anchor{library/ast ast-root-nodes}@anchor{4a3d}@anchor{library/ast root-nodes}@anchor{4a3e}
@subsubsection 根節點


@geindex Module (ast 中的類別)
@anchor{library/ast ast Module}@anchor{4a3f}
@deffn {類別} ast.Module (body, type_ignores)

一個 Python 模組，與@ref{2447,,檔案輸入} 一樣。由 @ref{1c2,,ast.parse()} 在預設的 @code{"exec"} `mode' 下生成的節點型別。

@code{body} 是模組的@ref{4a40,,陳述式} 的一個 @ref{24d,,list}。

@code{type_ignores} 是模組的忽略型別註解的 @ref{24d,,list}；有關更多詳細資訊，請參閱 @ref{1c2,,ast.parse()}。

@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{4a41}
@deffn {類別} ast.Expression (body)

單個 Python @ref{244d,,運算式輸入}。當 `mode' 是 @code{"eval"} 時節點型別由 @ref{1c2,,ast.parse()} 生成。

@code{body} 是單個節點，是@ref{4a42,,運算式型別}的其中之一。

@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{17f4}
@deffn {類別} ast.Interactive (body)

單個@ref{244a,,互動式輸入}，和@ref{48f,,互動模式}中所述的相似。當 `mode' 是 @code{"single"} 時節點型別由 @ref{1c2,,ast.parse()} 生成。

@code{body} 是@ref{4a40,,陳述式節點 (statement nodes)} 的 @ref{24d,,list}。

@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{4a43}
@deffn {類別} ast.FunctionType (argtypes, returns)

函式的舊式型別註解的表示法，因為 3.5 之前的 Python 版本不支援 
@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/} 註釋。當 `mode' 是 @code{"func_type"} 時節點型別由 @ref{1c2,,ast.parse()} 生成。

這種型別的註解看起來像這樣：

@example
def sum_two_number(a, b):
    # type: (int, int) -> int
    return a + b
@end example

@code{argtypes} 是@ref{4a42,,運算式節點}的 @ref{24d,,list}。

@code{returns} 是單個@ref{4a42,,運算式節點}。

@example
>>> print(ast.dump(ast.parse('(int, str) -> List[int]', mode='func_type'), indent=4))
FunctionType(
    argtypes=[
        Name(id='int', ctx=Load()),
        Name(id='str', ctx=Load())],
    returns=Subscript(
        value=Name(id='List', ctx=Load()),
        slice=Name(id='int', ctx=Load()),
        ctx=Load()))
@end example


在 3.8 版被加入.

@end deffn

@node 文本 Literals,變數,根節點,節點 Node 類別
@anchor{library/ast literals}@anchor{4a44}
@subsubsection 文本 (Literals)


@geindex Constant (ast 中的類別)
@anchor{library/ast ast Constant}@anchor{2ee}
@deffn {類別} ast.Constant (value)

一個常數值。@code{Constant} 文本的 @code{value} 屬性包含它所代表的 Python 物件。表示的值可以是 @ref{169,,str}、@ref{192,,bytes}、@ref{19b,,int}、@ref{196,,float}、@ref{197,,complex} 和 @ref{3c1,,bool} 的實例，以及常數 @ref{87e,,None} 和 @ref{21dd,,Ellipsis}。

@example
>>> print(ast.dump(ast.parse('123', mode='eval'), indent=4))
Expression(
    body=Constant(value=123))
@end example
@end deffn

@geindex FormattedValue (ast 中的類別)
@anchor{library/ast ast FormattedValue}@anchor{494e}
@deffn {類別} ast.FormattedValue (value, conversion, format_spec)

表示 f 字串 (f-string) 中的單個格式化欄位的節點。如果字串包含單個格式欄位並且沒有其他內容，則可以隔離 (isolate) 該節點，否則它將出現在 @ref{19ad,,JoinedStr} 中。


@itemize *

@item 
@code{value} 為任何運算式節點（例如文字、變數或函式呼叫）。

@item 
@code{conversion} 是一個整數：


@itemize *

@item 
-1: 無格式化

@item 
97 (@code{ord('a')})：@code{！a} @ref{15dd,,ASCII} 格式化

@item 
114 (@code{ord('r')})：@code{!r} @ref{1c1,,repr()} 格式化

@item 
115 (@code{ord('s')})：@code{!s} @ref{169,,string} 格式化
@end itemize

@item 
@code{format_spec} 是一個 @ref{19ad,,JoinedStr} 節點，表示值的格式，若未指定格式則為 @code{None}。@code{conversion} 和 @code{format_spec} 可以同時設定。
@end itemize
@end deffn

@geindex JoinedStr (ast 中的類別)
@anchor{library/ast ast JoinedStr}@anchor{19ad}
@deffn {類別} ast.JoinedStr (values)

一個 f 字串，包含一系列 @ref{494e,,FormattedValue} 和 @ref{2ee,,Constant} 節點。

@example
>>> print(ast.dump(ast.parse('f"sin(@{a@}) is @{sin(a):.3@}"', mode='eval'), indent=4))
Expression(
    body=JoinedStr(
        values=[
            Constant(value='sin('),
            FormattedValue(
                value=Name(id='a', ctx=Load()),
                conversion=-1),
            Constant(value=') is '),
            FormattedValue(
                value=Call(
                    func=Name(id='sin', ctx=Load()),
                    args=[
                        Name(id='a', ctx=Load())]),
                conversion=-1,
                format_spec=JoinedStr(
                    values=[
                        Constant(value='.3')]))]))
@end example
@end deffn

@geindex TemplateStr (ast 中的類別)
@anchor{library/ast ast TemplateStr}@anchor{4a45}
@deffn {類別} ast.TemplateStr (values, /)


在 3.14 版被加入.


Node representing a template string literal, comprising a series of
@ref{174d,,Interpolation} and @ref{2ee,,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', ctx=Load()),
                str='name',
                conversion=-1),
            Constant(value=' finished '),
            Interpolation(
                value=Name(id='place', ctx=Load()),
                str='place',
                conversion=-1,
                format_spec=JoinedStr(
                    values=[
                        Constant(value='ordinal')]))]))
@end example
@end deffn

@geindex Interpolation (ast 中的類別)
@anchor{library/ast ast Interpolation}@anchor{174d}
@deffn {類別} ast.Interpolation (value, str, conversion, format_spec=None)


在 3.14 版被加入.


Node representing a single interpolation field in a template string literal.


@itemize *

@item 
@code{value} 為任何運算式節點（例如文字、變數或函式呼叫）。這和 @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{ad9,,ast.unparse()}. This no longer guarantees that the
generated code is identical to the original and is intended for code
generation.

@item 
@code{conversion} 是一個整數：


@itemize *

@item 
-1：無規範

@item 
97 (@code{ord('a')})：@code{!a} @ref{15dd,,ASCII} 轉換

@item 
114 (@code{ord('r')})：@code{!r} @ref{1c1,,repr()} 轉換

@item 
115 (@code{ord('s')})：@code{!s} @ref{169,,string} 轉換
@end itemize

這與 @code{FormattedValue.conversion} 的意思相同。

@item 
@code{format_spec} 是一個 @ref{19ad,,JoinedStr} 節點，表示值的格式，若未指定格式則為 @code{None}。@code{conversion} 和 @code{format_spec} 可以同時設定。這與 @code{FormattedValue.format_spec} 的意思相同。
@end itemize
@end deffn

@geindex List (ast 中的類別)
@geindex Tuple (ast 中的類別)
@anchor{library/ast ast List}@anchor{494b}
@deffn {類別} ast.List (elts, ctx)
@anchor{library/ast ast Tuple}@anchor{494c}
@deffnx {類別} ast.Tuple (elts, ctx)

串列或元組。@code{elts} 保存表示元素的節點串列。如果容器是賦值目標（即 @code{(x,y)=something} ），則 @code{ctx} 是 @ref{4a46,,Store}，否則是 @ref{4bd,,Load}。

@example
>>> print(ast.dump(ast.parse('[1, 2, 3]', mode='eval'), indent=4))
Expression(
    body=List(
        elts=[
            Constant(value=1),
            Constant(value=2),
            Constant(value=3)],
        ctx=Load()))
>>> print(ast.dump(ast.parse('(1, 2, 3)', mode='eval'), indent=4))
Expression(
    body=Tuple(
        elts=[
            Constant(value=1),
            Constant(value=2),
            Constant(value=3)],
        ctx=Load()))
@end example
@end deffn

@geindex Set (ast 中的類別)
@anchor{library/ast ast Set}@anchor{493b}
@deffn {類別} ast.Set (elts)

一個集合。@code{elts} 保存表示集合之元素的節點串列。

@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{1c12}
@deffn {類別} ast.Dict (keys, values)

一個字典 (dictionary)。@code{keys} 和 @code{values} 分別按匹配順序保存表示鍵和值的節點串列（為呼叫 @code{dictionary.keys()} 和 @code{dictionary.values()} 時將回傳的內容）。

當使用字典文本進行字典解包 (unpack) 時，要擴充的運算式位於 @code{values} 串列中，在 @code{keys} 中的相應位置有一個 @code{None}。

@example
>>> print(ast.dump(ast.parse('@{"a":1, **d@}', mode='eval'), indent=4))
Expression(
    body=Dict(
        keys=[
            Constant(value='a'),
            None],
        values=[
            Constant(value=1),
            Name(id='d', ctx=Load())]))
@end example
@end deffn

@node 變數,運算式<2>,文本 Literals,節點 Node 類別
@anchor{library/ast variables}@anchor{4a47}
@subsubsection 變數


@geindex Name (ast 中的類別)
@anchor{library/ast ast Name}@anchor{1bf4}
@deffn {類別} ast.Name (id, ctx)

一個變數名稱。@code{id} 將名稱以字串形式保存，且 @code{ctx} 是以下型別之一。
@end deffn

@geindex Load (ast 中的類別)
@geindex Store (ast 中的類別)
@geindex Del (ast 中的類別)
@anchor{library/ast ast Load}@anchor{4bd}
@deffn {類別} ast.Load
@anchor{library/ast ast Store}@anchor{4a46}
@deffnx {類別} ast.Store
@anchor{library/ast ast Del}@anchor{4a48}
@deffnx {類別} ast.Del

變數參照可用於載入變數的值、為其分配新值或刪除它。變數參照被賦予情境 (context) 來區分這些情況。

@example
>>> print(ast.dump(ast.parse('a'), indent=4))
Module(
    body=[
        Expr(
            value=Name(id='a', ctx=Load()))])

>>> print(ast.dump(ast.parse('a = 1'), indent=4))
Module(
    body=[
        Assign(
            targets=[
                Name(id='a', ctx=Store())],
            value=Constant(value=1))])

>>> print(ast.dump(ast.parse('del a'), indent=4))
Module(
    body=[
        Delete(
            targets=[
                Name(id='a', ctx=Del())])])
@end example
@end deffn

@geindex Starred (ast 中的類別)
@anchor{library/ast ast Starred}@anchor{494a}
@deffn {類別} ast.Starred (value, ctx)

一個 @code{*var} 變數參照。@code{value} 保存變數，通常是一個 @ref{1bf4,,Name} 節點。在使用 @code{*args} 建置 @ref{4947,,Call} 節點時必須使用此型別。

@example
>>> print(ast.dump(ast.parse('a, *b = it'), indent=4))
Module(
    body=[
        Assign(
            targets=[
                Tuple(
                    elts=[
                        Name(id='a', ctx=Store()),
                        Starred(
                            value=Name(id='b', ctx=Store()),
                            ctx=Store())],
                    ctx=Store())],
            value=Name(id='it', ctx=Load()))])
@end example
@end deffn

@node 運算式<2>,陳述式,變數,節點 Node 類別
@anchor{library/ast ast-expressions}@anchor{4a42}@anchor{library/ast expressions}@anchor{4a49}
@subsubsection 運算式


@geindex Expr (ast 中的類別)
@anchor{library/ast ast Expr}@anchor{4a4a}
@deffn {類別} ast.Expr (value)

當運算式（例如函式呼叫）本身作為陳述式出現且未使用或儲存其回傳值時，它將被包裝在此容器中。@code{value} 保存此區段 (section) 中的一個其他節點：@ref{2ee,,Constant}、@ref{1bf4,,Name}、@ref{4951,,Lambda}、@ref{4958,,Yield} 或 @ref{4959,,YieldFrom}

@example
>>> print(ast.dump(ast.parse('-a'), indent=4))
Module(
    body=[
        Expr(
            value=UnaryOp(
                op=USub(),
                operand=Name(id='a', ctx=Load())))])
@end example
@end deffn

@geindex UnaryOp (ast 中的類別)
@anchor{library/ast ast UnaryOp}@anchor{4936}
@deffn {類別} ast.UnaryOp (op, operand)

一元運算 (unary operation)。@code{op} 是運算子，@code{operand} 是任何運算式節點。
@end deffn

@geindex UAdd (ast 中的類別)
@geindex USub (ast 中的類別)
@geindex Not (ast 中的類別)
@geindex Invert (ast 中的類別)
@anchor{library/ast ast UAdd}@anchor{4938}
@deffn {類別} ast.UAdd
@anchor{library/ast ast USub}@anchor{4939}
@deffnx {類別} ast.USub
@anchor{library/ast ast Not}@anchor{493a}
@deffnx {類別} ast.Not
@anchor{library/ast ast Invert}@anchor{4937}
@deffnx {類別} ast.Invert

一元運算子標記。 @ref{493a,,Not} 是 @code{not} 關鍵字、@ref{4937,,Invert} 是 @code{~} 運算子。

@example
>>> print(ast.dump(ast.parse('not x', mode='eval'), indent=4))
Expression(
    body=UnaryOp(
        op=Not(),
        operand=Name(id='x', ctx=Load())))
@end example
@end deffn

@geindex BinOp (ast 中的類別)
@anchor{library/ast ast BinOp}@anchor{1c7b}
@deffn {類別} ast.BinOp (left, op, right)

二元運算 (binary operation)（如加法或除法）。 @code{op} 是運算子、@code{left} 和 @code{right} 是任意運算式節點。

@example
>>> print(ast.dump(ast.parse('x + y', mode='eval'), indent=4))
Expression(
    body=BinOp(
        left=Name(id='x', ctx=Load()),
        op=Add(),
        right=Name(id='y', ctx=Load())))
@end example
@end deffn

@geindex Add (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{4a4b}
@deffn {類別} ast.Add
@anchor{library/ast ast Sub}@anchor{4a4c}
@deffnx {類別} ast.Sub
@anchor{library/ast ast Mult}@anchor{4a4d}
@deffnx {類別} ast.Mult
@anchor{library/ast ast Div}@anchor{4a4e}
@deffnx {類別} ast.Div
@anchor{library/ast ast FloorDiv}@anchor{4a4f}
@deffnx {類別} ast.FloorDiv
@anchor{library/ast ast Mod}@anchor{4a50}
@deffnx {類別} ast.Mod
@anchor{library/ast ast Pow}@anchor{4a51}
@deffnx {類別} ast.Pow
@anchor{library/ast ast LShift}@anchor{4a52}
@deffnx {類別} ast.LShift
@anchor{library/ast ast RShift}@anchor{4a53}
@deffnx {類別} ast.RShift
@anchor{library/ast ast BitOr}@anchor{4a54}
@deffnx {類別} ast.BitOr
@anchor{library/ast ast BitXor}@anchor{4a55}
@deffnx {類別} ast.BitXor
@anchor{library/ast ast BitAnd}@anchor{4a56}
@deffnx {類別} ast.BitAnd
@anchor{library/ast ast MatMult}@anchor{4a57}
@deffnx {類別} ast.MatMult

二元運算子 token。
@end deffn

@geindex BoolOp (ast 中的類別)
@anchor{library/ast ast BoolOp}@anchor{494f}
@deffn {類別} ast.BoolOp (op, values)

布林運算 'or' 或 'and'。@code{op} 是 @ref{4a58,,Or} 或 @ref{4a59,,And}。@code{values} 是有所涉及的值。使用同一運算子的連續操作（例如 @code{a or b or c}）會被折疊為具有多個值的一個節點。

這不包括 @code{not}，它是一個 @ref{4936,,UnaryOp}。

@example
>>> print(ast.dump(ast.parse('x or y', mode='eval'), indent=4))
Expression(
    body=BoolOp(
        op=Or(),
        values=[
            Name(id='x', ctx=Load()),
            Name(id='y', ctx=Load())]))
@end example
@end deffn

@geindex And (ast 中的類別)
@geindex Or (ast 中的類別)
@anchor{library/ast ast And}@anchor{4a59}
@deffn {類別} ast.And
@anchor{library/ast ast Or}@anchor{4a58}
@deffnx {類別} ast.Or

布林運算子 token。
@end deffn

@geindex Compare (ast 中的類別)
@anchor{library/ast ast Compare}@anchor{493c}
@deffn {類別} ast.Compare (left, ops, comparators)

兩個或多個值的比較。@code{left} 是比較中的第一個值、@code{ops} 是運算子串列、@code{comparators} 是要比較的第一個元素之後值的串列。

@example
>>> print(ast.dump(ast.parse('1 <= a < 10', mode='eval'), indent=4))
Expression(
    body=Compare(
        left=Constant(value=1),
        ops=[
            LtE(),
            Lt()],
        comparators=[
            Name(id='a', ctx=Load()),
            Constant(value=10)]))
@end example
@end deffn

@geindex Eq (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{493d}
@deffn {類別} ast.Eq
@anchor{library/ast ast NotEq}@anchor{493e}
@deffnx {類別} ast.NotEq
@anchor{library/ast ast Lt}@anchor{493f}
@deffnx {類別} ast.Lt
@anchor{library/ast ast LtE}@anchor{4940}
@deffnx {類別} ast.LtE
@anchor{library/ast ast Gt}@anchor{4941}
@deffnx {類別} ast.Gt
@anchor{library/ast ast GtE}@anchor{4942}
@deffnx {類別} ast.GtE
@anchor{library/ast ast Is}@anchor{4943}
@deffnx {類別} ast.Is
@anchor{library/ast ast IsNot}@anchor{4944}
@deffnx {類別} ast.IsNot
@anchor{library/ast ast In}@anchor{4945}
@deffnx {類別} ast.In
@anchor{library/ast ast NotIn}@anchor{4946}
@deffnx {類別} ast.NotIn

比較運算子 token。
@end deffn

@geindex Call (ast 中的類別)
@anchor{library/ast ast Call}@anchor{4947}
@deffn {類別} ast.Call (func, args, keywords)

一個函式呼叫。@code{func} 是該函式，通常是一個 @ref{1bf4,,Name} 或 @ref{4948,,Attribute} 物件。而在引數中：


@itemize *

@item 
@code{args} 保存按位置傳遞的引數串列。

@item 
@code{keywords} 保存一個 @ref{4a5a,,keyword} 物件串列，表示透過關鍵字傳遞的引數。
@end itemize

@code{args} 和 @code{keywords} 引數是可選的，預設為空串列。

@example
>>> print(ast.dump(ast.parse('func(a, b=c, *d, **e)', mode='eval'), indent=4))
Expression(
    body=Call(
        func=Name(id='func', ctx=Load()),
        args=[
            Name(id='a', ctx=Load()),
            Starred(
                value=Name(id='d', ctx=Load()),
                ctx=Load())],
        keywords=[
            keyword(
                arg='b',
                value=Name(id='c', ctx=Load())),
            keyword(
                value=Name(id='e', ctx=Load()))]))
@end example
@end deffn

@geindex keyword (ast 中的類別)
@anchor{library/ast ast keyword}@anchor{4a5a}
@deffn {類別} ast.keyword (arg, value)

函式呼叫或類別定義的關鍵字引數。@code{arg} 是參數名稱的原始字串，@code{value} 是要傳入的節點。
@end deffn

@geindex IfExp (ast 中的類別)
@anchor{library/ast ast IfExp}@anchor{4950}
@deffn {類別} ast.IfExp (test, body, orelse)

像是 @code{a if b else c} 之類的運算式。每個欄位都保存一個節點，因此在以下範例中，所有三個都是 @ref{1bf4,,Name} 節點。

@example
>>> print(ast.dump(ast.parse('a if b else c', mode='eval'), indent=4))
Expression(
    body=IfExp(
        test=Name(id='b', ctx=Load()),
        body=Name(id='a', ctx=Load()),
        orelse=Name(id='c', ctx=Load())))
@end example
@end deffn

@geindex Attribute (ast 中的類別)
@anchor{library/ast ast Attribute}@anchor{4948}
@deffn {類別} ast.Attribute (value, attr, ctx)

屬性的存取，例如 @code{d.keys}。@code{value} 是一個節點，通常是一個 @ref{1bf4,,Name}。@code{attr} 是一個屬性名稱的字串，@code{ctx} 根據屬性的作用方式可能是 @ref{4bd,,Load}、@ref{4a46,,Store} 或 @ref{4a48,,Del}。

@example
>>> print(ast.dump(ast.parse('snake.colour', mode='eval'), indent=4))
Expression(
    body=Attribute(
        value=Name(id='snake', ctx=Load()),
        attr='colour',
        ctx=Load()))
@end example
@end deffn

@geindex NamedExpr (ast 中的類別)
@anchor{library/ast ast NamedExpr}@anchor{4956}
@deffn {類別} ast.NamedExpr (target, value)

一個附名運算式 (named expression)。該 AST 節點由賦值運算式運算子（也稱為海象運算子）產生。相對於 @ref{4a5b,,Assign} 節點之第一個引數可為多個節點，在這種情況下 @code{target} 和 @code{value} 都必須是單個節點。

@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


在 3.8 版被加入.

@end deffn

@menu
* 下標 (Subscripting): 下標 Subscripting. 
* 綜合運算式 (comprehensions): 綜合運算式 comprehensions. 

@end menu

@node 下標 Subscripting,綜合運算式 comprehensions,,運算式<2>
@anchor{library/ast subscripting}@anchor{4a5c}
@subsubsection 下標 (Subscripting)


@geindex Subscript (ast 中的類別)
@anchor{library/ast ast Subscript}@anchor{4949}
@deffn {類別} ast.Subscript (value, slice, ctx)

一個下標，例如 @code{l[1]}。@code{value} 是下標物件（通常是序列或對映）。@code{slice} 是索引、切片或鍵。它可以是一個 @ref{494c,,Tuple} 並包含一個 @ref{494d,,Slice}。根據下標執行的操作不同，@code{ctx} 可以是 @ref{4bd,,Load}、@ref{4a46,,Store} 或 @ref{4a48,,Del}。

@example
>>> print(ast.dump(ast.parse('l[1:2, 3]', mode='eval'), indent=4))
Expression(
    body=Subscript(
        value=Name(id='l', ctx=Load()),
        slice=Tuple(
            elts=[
                Slice(
                    lower=Constant(value=1),
                    upper=Constant(value=2)),
                Constant(value=3)],
            ctx=Load()),
        ctx=Load()))
@end example
@end deffn

@geindex Slice (ast 中的類別)
@anchor{library/ast ast Slice}@anchor{494d}
@deffn {類別} ast.Slice (lower, upper, step)

常規切片（形式為 @code{lower:upper} 或 @code{lower:upper:step}）。只能直接或者或者作為 @ref{494c,,Tuple} 的元素出現在 @ref{4949,,Subscript} 的 `slice' 欄位內。

@example
>>> print(ast.dump(ast.parse('l[1:2]', mode='eval'), indent=4))
Expression(
    body=Subscript(
        value=Name(id='l', ctx=Load()),
        slice=Slice(
            lower=Constant(value=1),
            upper=Constant(value=2)),
        ctx=Load()))
@end example
@end deffn

@node 綜合運算式 comprehensions,,下標 Subscripting,運算式<2>
@anchor{library/ast comprehensions}@anchor{4a5d}
@subsubsection 綜合運算式 (comprehensions)


@geindex ListComp (ast 中的類別)
@geindex SetComp (ast 中的類別)
@geindex GeneratorExp (ast 中的類別)
@geindex DictComp (ast 中的類別)
@anchor{library/ast ast ListComp}@anchor{4952}
@deffn {類別} ast.ListComp (elt, generators)
@anchor{library/ast ast SetComp}@anchor{4953}
@deffnx {類別} ast.SetComp (elt, generators)
@anchor{library/ast ast GeneratorExp}@anchor{4955}
@deffnx {類別} ast.GeneratorExp (elt, generators)
@anchor{library/ast ast DictComp}@anchor{4954}
@deffnx {類別} ast.DictComp (key, value, generators)

串列和集合綜合運算、生成器運算式和字典綜合運算。@code{elt}（或 @code{key} 和 @code{value}）是單個節點，表示各個項目會被求值 (evaluate) 的部分。

@code{generators} 是一個 @ref{4a5e,,comprehension} 節點的串列。

@example
>>> print(ast.dump(
...     ast.parse('[x for x in numbers]', mode='eval'),
...     indent=4,
... ))
Expression(
    body=ListComp(
        elt=Name(id='x', ctx=Load()),
        generators=[
            comprehension(
                target=Name(id='x', ctx=Store()),
                iter=Name(id='numbers', ctx=Load()),
                is_async=0)]))
>>> print(ast.dump(
...     ast.parse('@{x: x**2 for x in numbers@}', mode='eval'),
...     indent=4,
... ))
Expression(
    body=DictComp(
        key=Name(id='x', ctx=Load()),
        value=BinOp(
            left=Name(id='x', ctx=Load()),
            op=Pow(),
            right=Constant(value=2)),
        generators=[
            comprehension(
                target=Name(id='x', ctx=Store()),
                iter=Name(id='numbers', ctx=Load()),
                is_async=0)]))
>>> print(ast.dump(
...     ast.parse('@{x for x in numbers@}', mode='eval'),
...     indent=4,
... ))
Expression(
    body=SetComp(
        elt=Name(id='x', ctx=Load()),
        generators=[
            comprehension(
                target=Name(id='x', ctx=Store()),
                iter=Name(id='numbers', ctx=Load()),
                is_async=0)]))
@end example
@end deffn

@geindex comprehension (ast 中的類別)
@anchor{library/ast ast comprehension}@anchor{4a5e}
@deffn {類別} ast.comprehension (target, iter, ifs, is_async)

綜合運算中的一個 @code{for} 子句。@code{target} 是用於每個元素的參照 - 通常是 @ref{1bf4,,Name} 或 @ref{494c,,Tuple} 節點。@code{iter} 是要疊代的物件。@code{ifs} 是測試運算式的串列：每個 @code{for} 子句可以有多個 @code{ifs}。

@code{is_async} 表示綜合運算式是非同步的（使用 @code{async for} 而不是 @code{for} ）。該值為整數（0 或 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', ctx=Load()),
            args=[
                Name(id='c', ctx=Load())]),
        generators=[
            comprehension(
                target=Name(id='line', ctx=Store()),
                iter=Name(id='file', ctx=Load()),
                is_async=0),
            comprehension(
                target=Name(id='c', ctx=Store()),
                iter=Name(id='line', ctx=Load()),
                is_async=0)]))

>>> print(ast.dump(ast.parse('(n**2 for n in it if n>5 if n<10)', mode='eval'),
...                indent=4)) # generator comprehension
Expression(
    body=GeneratorExp(
        elt=BinOp(
            left=Name(id='n', ctx=Load()),
            op=Pow(),
            right=Constant(value=2)),
        generators=[
            comprehension(
                target=Name(id='n', ctx=Store()),
                iter=Name(id='it', ctx=Load()),
                ifs=[
                    Compare(
                        left=Name(id='n', ctx=Load()),
                        ops=[
                            Gt()],
                        comparators=[
                            Constant(value=5)]),
                    Compare(
                        left=Name(id='n', ctx=Load()),
                        ops=[
                            Lt()],
                        comparators=[
                            Constant(value=10)])],
                is_async=0)]))

>>> print(ast.dump(ast.parse('[i async for i in soc]', mode='eval'),
...                indent=4)) # Async comprehension
Expression(
    body=ListComp(
        elt=Name(id='i', ctx=Load()),
        generators=[
            comprehension(
                target=Name(id='i', ctx=Store()),
                iter=Name(id='soc', ctx=Load()),
                is_async=1)]))
@end example
@end deffn

@node 陳述式,流程控制,運算式<2>,節點 Node 類別
@anchor{library/ast ast-statements}@anchor{4a40}@anchor{library/ast statements}@anchor{4a5f}
@subsubsection 陳述式


@geindex Assign (ast 中的類別)
@anchor{library/ast ast Assign}@anchor{4a5b}
@deffn {類別} ast.Assign (targets, value, type_comment)

一個賦值。@code{targets} 是節點串列，@code{value} 是單個節點。

@code{targets} 中的多個節點表示為每個節點分配相同的值。解包是透過在 @code{targets} 中放置一個 @ref{494c,,Tuple} 或 @ref{494b,,List} 來表示的。

@geindex type_comment (ast.Assign 的屬性)
@anchor{library/ast ast Assign type_comment}@anchor{4a60}
@deffn {屬性} type_comment

@code{type_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', ctx=Load()))])
@end example
@end deffn

@geindex AnnAssign (ast 中的類別)
@anchor{library/ast ast AnnAssign}@anchor{4a61}
@deffn {類別} ast.AnnAssign (target, annotation, value, simple)

帶有型別註釋的賦值。@code{target} 是單個節點，可以是 @ref{1bf4,,Name}、@ref{4948,,Attribute} 或 @ref{4949,,Subscript}。@code{annotation} 是註釋，例如 @ref{2ee,,Constant} 或 @ref{1bf4,,Name} 節點。@code{value} 是單個可選節點。

@code{simple} 總會是 0（表示一個「複雜」目標）或 1（表示一個「簡單」目標）。一個「簡單」目標僅包含一個 @ref{1bf4,,Name} 節點，且不出現在括號之間；所有其他目標都被視為是複雜的。只有簡單目標會出現在模組和類別的 @ref{456,,__annotations__} 字典中。

@example
>>> print(ast.dump(ast.parse('c: int'), indent=4))
Module(
    body=[
        AnnAssign(
            target=Name(id='c', ctx=Store()),
            annotation=Name(id='int', ctx=Load()),
            simple=1)])

>>> print(ast.dump(ast.parse('(a): int = 1'), indent=4)) # Annotation with parenthesis
Module(
    body=[
        AnnAssign(
            target=Name(id='a', ctx=Store()),
            annotation=Name(id='int', ctx=Load()),
            value=Constant(value=1),
            simple=0)])

>>> print(ast.dump(ast.parse('a.b: int'), indent=4)) # Attribute annotation
Module(
    body=[
        AnnAssign(
            target=Attribute(
                value=Name(id='a', ctx=Load()),
                attr='b',
                ctx=Store()),
            annotation=Name(id='int', ctx=Load()),
            simple=0)])

>>> print(ast.dump(ast.parse('a[1]: int'), indent=4)) # Subscript annotation
Module(
    body=[
        AnnAssign(
            target=Subscript(
                value=Name(id='a', ctx=Load()),
                slice=Constant(value=1),
                ctx=Store()),
            annotation=Name(id='int', ctx=Load()),
            simple=0)])
@end example
@end deffn

@geindex AugAssign (ast 中的類別)
@anchor{library/ast ast AugAssign}@anchor{4a62}
@deffn {類別} ast.AugAssign (target, op, value)

增加賦值 (augmented assignment)，例如 @code{a += 1}。在下面的範例中，@code{target} 是 @code{x} 的 @ref{1bf4,,Name} 節點（帶有 @ref{4a46,,Store} 情境），@code{op} 是 @ref{4a4b,,Add}，@code{value} 是一個值為 1 的 @ref{2ee,,Constant}。

與 @ref{4a5b,,Assign} 的目標不同，@code{target} 屬性不能屬於 @ref{494c,,Tuple} 或 @ref{494b,,List} 類別。

@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{4a63}
@deffn {類別} ast.Raise (exc, cause)

一個 @code{raise} 陳述式。@code{exc} 是要引發的例外物件，通常是 @ref{4947,,Call} 或 @ref{1bf4,,Name}，若是獨立的 @code{raise} 則為 @code{None}。@code{cause} 是 @code{raise x from y} 中的可選部分 @code{y}。

@example
>>> print(ast.dump(ast.parse('raise x from y'), indent=4))
Module(
    body=[
        Raise(
            exc=Name(id='x', ctx=Load()),
            cause=Name(id='y', ctx=Load()))])
@end example
@end deffn

@geindex Assert (ast 中的類別)
@anchor{library/ast ast Assert}@anchor{4a64}
@deffn {類別} ast.Assert (test, msg)

一個斷言 (assertion)。@code{test} 保存條件，例如 @ref{493c,,Compare} 節點。@code{msg} 保存失敗訊息。

@example
>>> print(ast.dump(ast.parse('assert x,y'), indent=4))
Module(
    body=[
        Assert(
            test=Name(id='x', ctx=Load()),
            msg=Name(id='y', ctx=Load()))])
@end example
@end deffn

@geindex Delete (ast 中的類別)
@anchor{library/ast ast Delete}@anchor{4a65}
@deffn {類別} ast.Delete (targets)

代表一個 @code{del} 陳述式。@code{targets} 是節點串列，例如 @ref{1bf4,,Name}、@ref{4948,,Attribute} 或 @ref{4949,,Subscript} 節點。

@example
>>> print(ast.dump(ast.parse('del x,y,z'), indent=4))
Module(
    body=[
        Delete(
            targets=[
                Name(id='x', ctx=Del()),
                Name(id='y', ctx=Del()),
                Name(id='z', ctx=Del())])])
@end example
@end deffn

@geindex Pass (ast 中的類別)
@anchor{library/ast ast Pass}@anchor{4a66}
@deffn {類別} ast.Pass

一個 @code{pass} 陳述式。

@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{19a6}
@deffn {類別} ast.TypeAlias (name, type_params, value)

透過 @ref{665,,type} 陳述式建立的@ref{67c,,型別別名 (type alias)}。@code{name} 是別名的名稱、@code{type_params} 是@ref{4a67,,型別參數 (type parameter)} 的串列、@code{value} 是型別別名的值。

@example
>>> print(ast.dump(ast.parse('type Alias = int'), indent=4))
Module(
    body=[
        TypeAlias(
            name=Name(id='Alias', ctx=Store()),
            value=Name(id='int', ctx=Load()))])
@end example


在 3.12 版被加入.

@end deffn

其他僅適用於函式或迴圈內部的陳述式將在其他部分中描述。

@menu
* 引入 (imports): 引入 imports. 

@end menu

@node 引入 imports,,,陳述式
@anchor{library/ast imports}@anchor{4a68}
@subsubsection 引入 (imports)


@geindex Import (ast 中的類別)
@anchor{library/ast ast Import}@anchor{4a69}
@deffn {類別} ast.Import (names)

一個 import 陳述式。@code{names} 是 @ref{1b74,,alias} 節點的串列。

@example
>>> print(ast.dump(ast.parse('import x,y,z'), indent=4))
Module(
    body=[
        Import(
            names=[
                alias(name='x'),
                alias(name='y'),
                alias(name='z')])])
@end example
@end deffn

@geindex ImportFrom (ast 中的類別)
@anchor{library/ast ast ImportFrom}@anchor{4a6a}
@deffn {類別} ast.ImportFrom (module, names, level)

代表 @code{from x import y}。@code{module} 是 'from' 名稱的原始字串，前面沒有任何的點 (dot)，或者對於諸如 @code{from . import foo} 之類的陳述式則為 @code{None}。@code{level} 是一個整數，保存相對引入的級別（0 表示絕對引入）。

@example
>>> print(ast.dump(ast.parse('from y import x,y,z'), indent=4))
Module(
    body=[
        ImportFrom(
            module='y',
            names=[
                alias(name='x'),
                alias(name='y'),
                alias(name='z')],
            level=0)])
@end example
@end deffn

@geindex alias (ast 中的類別)
@anchor{library/ast ast alias}@anchor{1b74}
@deffn {類別} ast.alias (name, asname)

這兩個參數都是名稱的原始字串。如果要使用常規名稱，@code{asname} 可以為 @code{None}。

@example
>>> print(ast.dump(ast.parse('from ..foo.bar import a as b, c'), indent=4))
Module(
    body=[
        ImportFrom(
            module='foo.bar',
            names=[
                alias(name='a', asname='b'),
                alias(name='c')],
            level=2)])
@end example
@end deffn

@node 流程控制,模式匹配 pattern matching,陳述式,節點 Node 類別
@anchor{library/ast control-flow}@anchor{4a6b}
@subsubsection 流程控制


@cartouche
@quotation 備註 
諸如 @code{else} 之類的可選子句如果不存在，則將被儲存為空串列。
@end quotation
@end cartouche

@geindex If (ast 中的類別)
@anchor{library/ast ast If}@anchor{4a6c}
@deffn {類別} ast.If (test, body, orelse)

一個 @code{if} 陳述式。@code{test} 保存單個節點，例如 @ref{493c,,Compare} 節點。@code{body} 和 @code{orelse} 各自保存一個節點串列。

@code{elif} 子句在 AST 中沒有特殊表示，而是在前一個子句的 @code{orelse} 部分中作為額外的 @ref{4a6c,,If} 節點出現。

@example
>>> print(ast.dump(ast.parse("""
... if x:
...    ...
... elif y:
...    ...
... else:
...    ...
... """), indent=4))
Module(
    body=[
        If(
            test=Name(id='x', ctx=Load()),
            body=[
                Expr(
                    value=Constant(value=Ellipsis))],
            orelse=[
                If(
                    test=Name(id='y', ctx=Load()),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))],
                    orelse=[
                        Expr(
                            value=Constant(value=Ellipsis))])])])
@end example
@end deffn

@geindex For (ast 中的類別)
@anchor{library/ast ast For}@anchor{4a6d}
@deffn {類別} ast.For (target, iter, body, orelse, type_comment)

一個 @code{for} 迴圈。 @code{target} 保存迴圈賦予的變數，為單個 @ref{1bf4,,Name}、@ref{494c,,Tuple}、@ref{494b,,List}、@ref{4948,,Attribute} 或 @ref{4949,,Subscript} 節點。@code{iter} 保存要迴圈跑過的項目，也為單個節點。@code{body} 和 @code{orelse} 包含要執行的節點串列。如果迴圈正常完成，則執行 @code{orelse} 中的內容，而不是透過 @code{break} 陳述式執行。

@geindex type_comment (ast.For 的屬性)
@anchor{library/ast ast For type_comment}@anchor{4a6e}
@deffn {屬性} type_comment

@code{type_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', ctx=Load()),
            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{4a6f}
@deffn {類別} ast.While (test, body, orelse)

一個 @code{while} 迴圈。@code{test} 保存條件，例如 @ref{493c,,Compare} 節點。

@example
>>> print(ast.dump(ast.parse("""
... while x:
...    ...
... else:
...    ...
... """), indent=4))
Module(
    body=[
        While(
            test=Name(id='x', ctx=Load()),
            body=[
                Expr(
                    value=Constant(value=Ellipsis))],
            orelse=[
                Expr(
                    value=Constant(value=Ellipsis))])])
@end example
@end deffn

@geindex Break (ast 中的類別)
@geindex Continue (ast 中的類別)
@anchor{library/ast ast Break}@anchor{4a70}
@deffn {類別} ast.Break
@anchor{library/ast ast Continue}@anchor{4a71}
@deffnx {類別} ast.Continue

@code{break} 和 @code{continue} 陳述式。

@example
>>> print(ast.dump(ast.parse("""\
... for a in b:
...     if a > 5:
...         break
...     else:
...         continue
...
... """), indent=4))
Module(
    body=[
        For(
            target=Name(id='a', ctx=Store()),
            iter=Name(id='b', ctx=Load()),
            body=[
                If(
                    test=Compare(
                        left=Name(id='a', ctx=Load()),
                        ops=[
                            Gt()],
                        comparators=[
                            Constant(value=5)]),
                    body=[
                        Break()],
                    orelse=[
                        Continue()])])])
@end example
@end deffn

@geindex Try (ast 中的類別)
@anchor{library/ast ast Try}@anchor{4a72}
@deffn {類別} ast.Try (body, handlers, orelse, finalbody)

@code{try} 區塊。除 @code{handlers} 是 @ref{4a73,,ExceptHandler} 節點的串列外，其他所有屬性都是要執行之節點的串列。

@example
>>> print(ast.dump(ast.parse("""
... try:
...    ...
... except Exception:
...    ...
... except OtherException as e:
...    ...
... else:
...    ...
... finally:
...    ...
... """), indent=4))
Module(
    body=[
        Try(
            body=[
                Expr(
                    value=Constant(value=Ellipsis))],
            handlers=[
                ExceptHandler(
                    type=Name(id='Exception', ctx=Load()),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))]),
                ExceptHandler(
                    type=Name(id='OtherException', ctx=Load()),
                    name='e',
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))])],
            orelse=[
                Expr(
                    value=Constant(value=Ellipsis))],
            finalbody=[
                Expr(
                    value=Constant(value=Ellipsis))])])
@end example
@end deffn

@geindex TryStar (ast 中的類別)
@anchor{library/ast ast TryStar}@anchor{4a74}
@deffn {類別} ast.TryStar (body, handlers, orelse, finalbody)

@code{try} 區塊，後面跟著 @code{except*} 子句。這些屬性與 @ref{4a72,,Try} 相同，但是 @code{handlers} 中的 @ref{4a73,,ExceptHandler} 節點被直譯 (interpret) 為 @code{except*} 區塊而不是 @code{except}。

@example
>>> print(ast.dump(ast.parse("""
... try:
...    ...
... except* Exception:
...    ...
... """), indent=4))
Module(
    body=[
        TryStar(
            body=[
                Expr(
                    value=Constant(value=Ellipsis))],
            handlers=[
                ExceptHandler(
                    type=Name(id='Exception', ctx=Load()),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))])])])
@end example


在 3.11 版被加入.

@end deffn

@geindex ExceptHandler (ast 中的類別)
@anchor{library/ast ast ExceptHandler}@anchor{4a73}
@deffn {類別} ast.ExceptHandler (type, name, body)

單個 @code{except} 子句。@code{type} 是會被匹配的例外型別，通常是一個 @ref{1bf4,,Name} 節點（或者 @code{None} 表示會捕捉到所有例外的 @code{except:} 子句）。@code{name} 是用於保存例外的名稱之原始字串，如果子句沒有 @code{as foo} ，則為 @code{None}。@code{body} 是節點串列。

@example
>>> print(ast.dump(ast.parse("""\
... try:
...     a + 1
... except TypeError:
...     pass
... """), indent=4))
Module(
    body=[
        Try(
            body=[
                Expr(
                    value=BinOp(
                        left=Name(id='a', ctx=Load()),
                        op=Add(),
                        right=Constant(value=1)))],
            handlers=[
                ExceptHandler(
                    type=Name(id='TypeError', ctx=Load()),
                    body=[
                        Pass()])])])
@end example
@end deffn

@geindex With (ast 中的類別)
@anchor{library/ast ast With}@anchor{4a75}
@deffn {類別} ast.With (items, body, type_comment)

一個 @code{with} 區塊。@code{items} 是表示情境管理器的 @ref{4a76,,withitem} 節點串列，@code{body} 是情境內的縮進區塊。

@geindex type_comment (ast.With 的屬性)
@anchor{library/ast ast With type_comment}@anchor{4a77}
@deffn {屬性} type_comment

@code{type_comment} 是一個可選字串，其中的註解為型別註釋。
@end deffn
@end deffn

@geindex withitem (ast 中的類別)
@anchor{library/ast ast withitem}@anchor{4a76}
@deffn {類別} ast.withitem (context_expr, optional_vars)

@code{with} 區塊中的單個情境管理器。@code{context_expr} 是情境管理器，通常是一個 @ref{4947,,Call} 節點。@code{Optional_vars} 是 @code{as foo} 部分的 @ref{1bf4,,Name}、@ref{494c,,Tuple} 或 @ref{494b,,List}，或者如果不使用則為 @code{None} 。

@example
>>> print(ast.dump(ast.parse("""\
... with a as b, c as d:
...    something(b, d)
... """), indent=4))
Module(
    body=[
        With(
            items=[
                withitem(
                    context_expr=Name(id='a', ctx=Load()),
                    optional_vars=Name(id='b', ctx=Store())),
                withitem(
                    context_expr=Name(id='c', ctx=Load()),
                    optional_vars=Name(id='d', ctx=Store()))],
            body=[
                Expr(
                    value=Call(
                        func=Name(id='something', ctx=Load()),
                        args=[
                            Name(id='b', ctx=Load()),
                            Name(id='d', ctx=Load())]))])])
@end example
@end deffn

@node 模式匹配 pattern matching,Type annotations,流程控制,節點 Node 類別
@anchor{library/ast pattern-matching}@anchor{4a78}
@subsubsection 模式匹配 (pattern matching)


@geindex Match (ast 中的類別)
@anchor{library/ast ast Match}@anchor{4a79}
@deffn {類別} ast.Match (subject, cases)

一個 @code{match} 陳述式。@code{subject} 保存匹配的主題（與案例匹配的物件），@code{cases} 包含具有不同案例的 @ref{4a7a,,match_case} 節點的可疊代物件。


在 3.10 版被加入.

@end deffn

@geindex match_case (ast 中的類別)
@anchor{library/ast ast match_case}@anchor{4a7a}
@deffn {類別} ast.match_case (pattern, guard, body)

@code{match} 陳述式中的單個案例模式。@code{pattern} 包含主題將與之匹配的匹配模式。請注意，為模式生成的 @ref{4be,,AST} 節點與為運算式生成的節點不同，即使它們共享相同的語法。

@code{guard} 屬性包含一個運算式，如果模式與主題匹配，則將對該運算式求值。

@code{body} 包含一個節點串列，如果模式匹配並且為防護運算式 (guard expression) 的求值 (evaluate) 結果為真，則會執行該節點串列。

@example
>>> print(ast.dump(ast.parse("""
... match x:
...     case [x] if x>0:
...         ...
...     case tuple():
...         ...
... """), indent=4))
Module(
    body=[
        Match(
            subject=Name(id='x', ctx=Load()),
            cases=[
                match_case(
                    pattern=MatchSequence(
                        patterns=[
                            MatchAs(name='x')]),
                    guard=Compare(
                        left=Name(id='x', ctx=Load()),
                        ops=[
                            Gt()],
                        comparators=[
                            Constant(value=0)]),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))]),
                match_case(
                    pattern=MatchClass(
                        cls=Name(id='tuple', ctx=Load())),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))])])])
@end example


在 3.10 版被加入.

@end deffn

@geindex MatchValue (ast 中的類別)
@anchor{library/ast ast MatchValue}@anchor{4a7b}
@deffn {類別} ast.MatchValue (value)

以相等性進行比較的匹配文本或值的模式。@code{value} 是一個運算式節點。允許值節點受到匹配陳述式文件中所述的限制。如果匹配主題等於求出值，則此模式成功。

@example
>>> print(ast.dump(ast.parse("""
... match x:
...     case "Relevant":
...         ...
... """), indent=4))
Module(
    body=[
        Match(
            subject=Name(id='x', ctx=Load()),
            cases=[
                match_case(
                    pattern=MatchValue(
                        value=Constant(value='Relevant')),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))])])])
@end example


在 3.10 版被加入.

@end deffn

@geindex MatchSingleton (ast 中的類別)
@anchor{library/ast ast MatchSingleton}@anchor{4a7c}
@deffn {類別} ast.MatchSingleton (value)

按識別性 (identity) 進行比較的匹配文本模式。@code{value} 是要與 @code{None}、@code{True} 或 @code{False} 進行比較的單例 (singleton)。如果匹配主題是給定的常數，則此模式成功。

@example
>>> print(ast.dump(ast.parse("""
... match x:
...     case None:
...         ...
... """), indent=4))
Module(
    body=[
        Match(
            subject=Name(id='x', ctx=Load()),
            cases=[
                match_case(
                    pattern=MatchSingleton(value=None),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))])])])
@end example


在 3.10 版被加入.

@end deffn

@geindex MatchSequence (ast 中的類別)
@anchor{library/ast ast MatchSequence}@anchor{4a7d}
@deffn {類別} ast.MatchSequence (patterns)

匹配序列模式。如果主題是一個序列，@code{patterns} 包含與主題元素匹配的模式。如果子模式之一是 @code{MatchStar} 節點，則匹配可變長度序列，否則匹配固定長度序列。

@example
>>> print(ast.dump(ast.parse("""
... match x:
...     case [1, 2]:
...         ...
... """), indent=4))
Module(
    body=[
        Match(
            subject=Name(id='x', ctx=Load()),
            cases=[
                match_case(
                    pattern=MatchSequence(
                        patterns=[
                            MatchValue(
                                value=Constant(value=1)),
                            MatchValue(
                                value=Constant(value=2))]),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))])])])
@end example


在 3.10 版被加入.

@end deffn

@geindex MatchStar (ast 中的類別)
@anchor{library/ast ast MatchStar}@anchor{4a7e}
@deffn {類別} ast.MatchStar (name)

以可變長度匹配序列模式匹配序列的其餘部分。如果 @code{name} 不是 @code{None}，則如果整體序列模式成功，則包含其餘序列元素的串列將綁定到該名稱。

@example
>>> print(ast.dump(ast.parse("""
... match x:
...     case [1, 2, *rest]:
...         ...
...     case [*_]:
...         ...
... """), indent=4))
Module(
    body=[
        Match(
            subject=Name(id='x', ctx=Load()),
            cases=[
                match_case(
                    pattern=MatchSequence(
                        patterns=[
                            MatchValue(
                                value=Constant(value=1)),
                            MatchValue(
                                value=Constant(value=2)),
                            MatchStar(name='rest')]),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))]),
                match_case(
                    pattern=MatchSequence(
                        patterns=[
                            MatchStar()]),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))])])])
@end example


在 3.10 版被加入.

@end deffn

@geindex MatchMapping (ast 中的類別)
@anchor{library/ast ast MatchMapping}@anchor{4a7f}
@deffn {類別} ast.MatchMapping (keys, patterns, rest)

匹配對映模式。@code{keys} 是運算式節點的序列。@code{patterns} 是相應的模式節點序列。@code{rest} 是一個可選名稱，可以指定它來捕獲剩餘的對映元素。允許的鍵運算式受到匹配陳述式文件中所述的限制。

如果主題是對映，所有求值出的鍵運算式都存在於對映中，並且與每個鍵對應的值與相應的子模式匹配，則此模式成功。如果 @code{rest} 不是 @code{None}，則如果整體對映模式成功，則包含其餘對映元素的字典將綁定到該名稱。

@example
>>> print(ast.dump(ast.parse("""
... match x:
...     case @{1: _, 2: _@}:
...         ...
...     case @{**rest@}:
...         ...
... """), indent=4))
Module(
    body=[
        Match(
            subject=Name(id='x', ctx=Load()),
            cases=[
                match_case(
                    pattern=MatchMapping(
                        keys=[
                            Constant(value=1),
                            Constant(value=2)],
                        patterns=[
                            MatchAs(),
                            MatchAs()]),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))]),
                match_case(
                    pattern=MatchMapping(rest='rest'),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))])])])
@end example


在 3.10 版被加入.

@end deffn

@geindex MatchClass (ast 中的類別)
@anchor{library/ast ast MatchClass}@anchor{4a80}
@deffn {類別} ast.MatchClass (cls, patterns, kwd_attrs, kwd_patterns)

匹配類別模式。@code{cls} 是一個給定要匹配的名義類別 (nominal class) 的運算式。@code{patterns} 是要與類別定義的模式匹配屬性序列進行匹配的模式節點序列。@code{kwd_attrs} 是要匹配的附加屬性序列（在類別模式中指定為關鍵字引數），@code{kwd_patterns} 是相應的模式（在類別模式中指定為關鍵字的值）。

如果主題是指定類別的實例，所有位置模式都與相應的類別定義屬性匹配，並且任何指定的關鍵字屬性與其相應模式匹配，則此模式成功。

注意：類別可以定義一個回傳 self 的特性 (property)，以便將模式節點與正在匹配的實例進行匹配。一些內建型別也以這種方式匹配，如同匹配陳述式文件中所述。

@example
>>> print(ast.dump(ast.parse("""
... match x:
...     case Point2D(0, 0):
...         ...
...     case Point3D(x=0, y=0, z=0):
...         ...
... """), indent=4))
Module(
    body=[
        Match(
            subject=Name(id='x', ctx=Load()),
            cases=[
                match_case(
                    pattern=MatchClass(
                        cls=Name(id='Point2D', ctx=Load()),
                        patterns=[
                            MatchValue(
                                value=Constant(value=0)),
                            MatchValue(
                                value=Constant(value=0))]),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))]),
                match_case(
                    pattern=MatchClass(
                        cls=Name(id='Point3D', ctx=Load()),
                        kwd_attrs=[
                            'x',
                            'y',
                            'z'],
                        kwd_patterns=[
                            MatchValue(
                                value=Constant(value=0)),
                            MatchValue(
                                value=Constant(value=0)),
                            MatchValue(
                                value=Constant(value=0))]),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))])])])
@end example


在 3.10 版被加入.

@end deffn

@geindex MatchAs (ast 中的類別)
@anchor{library/ast ast MatchAs}@anchor{4a81}
@deffn {類別} ast.MatchAs (pattern, name)

匹配的 「as 模式 (as-pattern)」，為捕獲模式 (capture pattern) 或通配模式 (wildcard pattern)。@code{pattern} 包含主題將與之匹配的匹配模式。如果模式為 @code{None}，則該節點代表捕獲模式（即裸名 (bare name)）並且始終會成功。

@code{name} 屬性包含模式成功時將綁定的名稱。如果 @code{name} 為 @code{None}，則 @code{pattern} 也必須為 @code{None}，並且節點代表通配模式。

@example
>>> print(ast.dump(ast.parse("""
... match x:
...     case [x] as y:
...         ...
...     case _:
...         ...
... """), indent=4))
Module(
    body=[
        Match(
            subject=Name(id='x', ctx=Load()),
            cases=[
                match_case(
                    pattern=MatchAs(
                        pattern=MatchSequence(
                            patterns=[
                                MatchAs(name='x')]),
                        name='y'),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))]),
                match_case(
                    pattern=MatchAs(),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))])])])
@end example


在 3.10 版被加入.

@end deffn

@geindex MatchOr (ast 中的類別)
@anchor{library/ast ast MatchOr}@anchor{4a82}
@deffn {類別} ast.MatchOr (patterns)

匹配的 「or 模式 (or-pattern)」。 or 模式依次將其每個子模式與主題進行匹配，直到成功為止，然後 or 模式就會被認為是成功的。如果沒有一個子模式成功，則 or 模式將失敗。 @code{patterns} 屬性包含將與主題進行匹配的匹配模式節點串列。

@example
>>> print(ast.dump(ast.parse("""
... match x:
...     case [x] | (y):
...         ...
... """), indent=4))
Module(
    body=[
        Match(
            subject=Name(id='x', ctx=Load()),
            cases=[
                match_case(
                    pattern=MatchOr(
                        patterns=[
                            MatchSequence(
                                patterns=[
                                    MatchAs(name='x')]),
                            MatchAs(name='y')]),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))])])])
@end example


在 3.10 版被加入.

@end deffn

@node Type annotations,型別參數 type parameters,模式匹配 pattern matching,節點 Node 類別
@anchor{library/ast type-annotations}@anchor{4a83}
@subsubsection Type annotations


@geindex TypeIgnore (ast 中的類別)
@anchor{library/ast ast TypeIgnore}@anchor{1a52}
@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', ctx=Load()),
            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{1c2,,ast.parse()} for more details.
@end quotation
@end cartouche


在 3.8 版被加入.

@end deffn

@node 型別參數 type parameters,函式和類別定義,Type annotations,節點 Node 類別
@anchor{library/ast ast-type-params}@anchor{4a67}@anchor{library/ast type-parameters}@anchor{4a84}
@subsubsection 型別參數 (type parameters)


@ref{5a7,,型別參數}可以存在於類別、函式和型別別名上。

@geindex TypeVar (ast 中的類別)
@anchor{library/ast ast TypeVar}@anchor{4a85}
@deffn {類別} ast.TypeVar (name, bound, default_value)

一個 @ref{481,,typing.TypeVar}。@code{name} 是型別變數的名稱。@code{bound} 是（如果有存在的）界限 (bound) 或約束 (constraint)。如果 @code{bound} 是一個 @ref{494c,,Tuple}，它代表約束；否則它代表界限。@code{default_value} 為預設值；如果 @code{TypeVar} 沒有預設值，那此屬性會被設為 @code{None}。

@example
>>> print(ast.dump(ast.parse("type Alias[T: int = bool] = list[T]"), indent=4))
Module(
    body=[
        TypeAlias(
            name=Name(id='Alias', ctx=Store()),
            type_params=[
                TypeVar(
                    name='T',
                    bound=Name(id='int', ctx=Load()),
                    default_value=Name(id='bool', ctx=Load()))],
            value=Subscript(
                value=Name(id='list', ctx=Load()),
                slice=Name(id='T', ctx=Load()),
                ctx=Load()))])
@end example


在 3.12 版被加入.



在 3.13 版的變更: 新增 `default_value' 參數。

@end deffn

@geindex ParamSpec (ast 中的類別)
@anchor{library/ast ast ParamSpec}@anchor{4a86}
@deffn {類別} ast.ParamSpec (name, default_value)

一個 @ref{482,,typing.ParamSpec}。@code{name} 是參數規範的名稱。@code{default_value} 是預設值；如果 @code{ParamSpec} 沒有預設值，則該屬性將設定為 @code{None}。

@example
>>> print(ast.dump(ast.parse("type Alias[**P = [int, str]] = Callable[P, int]"), indent=4))
Module(
    body=[
        TypeAlias(
            name=Name(id='Alias', ctx=Store()),
            type_params=[
                ParamSpec(
                    name='P',
                    default_value=List(
                        elts=[
                            Name(id='int', ctx=Load()),
                            Name(id='str', ctx=Load())],
                        ctx=Load()))],
            value=Subscript(
                value=Name(id='Callable', ctx=Load()),
                slice=Tuple(
                    elts=[
                        Name(id='P', ctx=Load()),
                        Name(id='int', ctx=Load())],
                    ctx=Load()),
                ctx=Load()))])
@end example


在 3.12 版被加入.



在 3.13 版的變更: 新增 `default_value' 參數。

@end deffn

@geindex TypeVarTuple (ast 中的類別)
@anchor{library/ast ast TypeVarTuple}@anchor{4a87}
@deffn {類別} ast.TypeVarTuple (name, default_value)

一個 @ref{483,,typing.TypeVarTuple}。@code{name} 是型別變數元組的名稱。@code{default_value} 為預設值；如果 @code{TypeVarTuple} 沒有預設值，那此屬性會被設為 @code{None}。

@example
>>> print(ast.dump(ast.parse("type Alias[*Ts = ()] = tuple[*Ts]"), indent=4))
Module(
    body=[
        TypeAlias(
            name=Name(id='Alias', ctx=Store()),
            type_params=[
                TypeVarTuple(
                    name='Ts',
                    default_value=Tuple(ctx=Load()))],
            value=Subscript(
                value=Name(id='tuple', ctx=Load()),
                slice=Tuple(
                    elts=[
                        Starred(
                            value=Name(id='Ts', ctx=Load()),
                            ctx=Load())],
                    ctx=Load()),
                ctx=Load()))])
@end example


在 3.12 版被加入.



在 3.13 版的變更: 新增 `default_value' 參數。

@end deffn

@node 函式和類別定義,async 和 await,型別參數 type parameters,節點 Node 類別
@anchor{library/ast function-and-class-definitions}@anchor{4a88}
@subsubsection 函式和類別定義


@geindex FunctionDef (ast 中的類別)
@anchor{library/ast ast FunctionDef}@anchor{19ca}
@deffn {類別} ast.FunctionDef (name, args, body, decorator_list, returns, type_comment, type_params)

一個函式定義。


@itemize *

@item 
@code{name} 是函式名稱的原始字串。

@item 
@code{args} 是一個 @ref{4a89,,arguments} 節點。

@item 
@code{body} 是函式內節點的串列。

@item 
@code{decorator_list} 是要應用的裝飾器串列，在最外層者會被儲存在首位（即串列中首位將會是最後一個被應用的那個）。

@item 
@code{returns} 是回傳註釋。

@item 
@code{type_params} 是@ref{4a67,,型別參數}的串列。
@end itemize

@geindex type_comment (ast.FunctionDef 的屬性)
@anchor{library/ast ast FunctionDef type_comment}@anchor{4a8a}
@deffn {屬性} type_comment

@code{type_comment} 是一個可選字串，其中的註解為型別註釋。
@end deffn


在 3.12 版的變更: 新增了 @code{type_params}。

@end deffn

@geindex Lambda (ast 中的類別)
@anchor{library/ast ast Lambda}@anchor{4951}
@deffn {類別} ast.Lambda (args, body)

@code{lambda} 是可以在運算式內使用的最小函式定義。與 @ref{19ca,,FunctionDef} 不同，@code{body} 保存單個節點。

@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{4a89}
@deffn {類別} ast.arguments (posonlyargs, args, vararg, kwonlyargs, kw_defaults, kwarg, defaults)

函式的引數。


@itemize *

@item 
@code{posonlyargs}、@code{args} 和 @code{kwonlyargs} 是 @ref{4a8b,,arg} 節點的串列。

@item 
@code{vararg} 和 @code{kwarg} 是單個 @ref{4a8b,,arg} 節點，指的是 @code{*args, **kwargs} 參數。

@item 
@code{kw_defaults} 是僅限關鍵字引數的預設值串列。如果其中某個為 @code{None}，則相應參數就會是必要的。

@item 
@code{defaults} 是可以按位置傳遞的引數的預設值串列。如果預設值較少，則它們對應於最後 n 個引數。
@end itemize
@end deffn

@geindex arg (ast 中的類別)
@anchor{library/ast ast arg}@anchor{4a8b}
@deffn {類別} ast.arg (arg, annotation, type_comment)

串列中的單個引數。@code{arg} 是引數名稱的原始字串，@code{annotation} 是它的註釋，例如 @ref{1bf4,,Name} 節點。

@geindex type_comment (ast.arg 的屬性)
@anchor{library/ast ast arg type_comment}@anchor{4a8c}
@deffn {屬性} type_comment

@code{type_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', ctx=Load()),
                Name(id='decorator2', ctx=Load())],
            returns=Constant(value='return annotation'))])
@end example
@end deffn

@geindex Return (ast 中的類別)
@anchor{library/ast ast Return}@anchor{4a8d}
@deffn {類別} ast.Return (value)

一個 @code{return} 陳述式。

@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{4958}
@deffn {類別} ast.Yield (value)
@anchor{library/ast ast YieldFrom}@anchor{4959}
@deffnx {類別} ast.YieldFrom (value)

一個 @code{yield} 或 @code{yield from} 運算式。因為這些是運算式，所以如果不使用發送回來的值，則必須將它們包裝在 @ref{4a4a,,Expr} 節點中。

@example
>>> print(ast.dump(ast.parse('yield x'), indent=4))
Module(
    body=[
        Expr(
            value=Yield(
                value=Name(id='x', ctx=Load())))])

>>> print(ast.dump(ast.parse('yield from x'), indent=4))
Module(
    body=[
        Expr(
            value=YieldFrom(
                value=Name(id='x', ctx=Load())))])
@end example
@end deffn

@geindex Global (ast 中的類別)
@geindex Nonlocal (ast 中的類別)
@anchor{library/ast ast Global}@anchor{4a8e}
@deffn {類別} ast.Global (names)
@anchor{library/ast ast Nonlocal}@anchor{4a8f}
@deffnx {類別} ast.Nonlocal (names)

@code{global} 和 @code{nonlocal} 陳述式。@code{names} 是原始字串的串列。

@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{19c8}
@deffn {類別} ast.ClassDef (name, bases, keywords, body, decorator_list, type_params)

一個類別定義。


@itemize *

@item 
@code{name} 是類別名稱的原始字串

@item 
@code{bases} 是被顯式指定的基底類別節點串列。

@item 
@code{keywords} 是一個 @ref{4a5a,,keyword} 節點的串列，主要用於 'metaclass'（元類別）。如 
@geindex Python Enhancement Proposals; PEP 3115
PEP 3115@footnote{https://peps.python.org/pep-3115/} 所述，其他關鍵字將被傳遞到 metaclass。

@item 
@code{body} 是表示類別定義中程式碼的節點串列。

@item 
@code{decorator_list} 是一個節點串列，如 @ref{19ca,,FunctionDef} 中所示。

@item 
@code{type_params} 是@ref{4a67,,型別參數}的串列。
@end itemize

@example
>>> print(ast.dump(ast.parse("""\
... @@decorator1
... @@decorator2
... class Foo(base1, base2, metaclass=meta):
...     pass
... """), indent=4))
Module(
    body=[
        ClassDef(
            name='Foo',
            bases=[
                Name(id='base1', ctx=Load()),
                Name(id='base2', ctx=Load())],
            keywords=[
                keyword(
                    arg='metaclass',
                    value=Name(id='meta', ctx=Load()))],
            body=[
                Pass()],
            decorator_list=[
                Name(id='decorator1', ctx=Load()),
                Name(id='decorator2', ctx=Load())])])
@end example


在 3.12 版的變更: 新增了 @code{type_params}。

@end deffn

@node async 和 await,,函式和類別定義,節點 Node 類別
@anchor{library/ast async-and-await}@anchor{4a90}
@subsubsection async 和 await


@geindex AsyncFunctionDef (ast 中的類別)
@anchor{library/ast ast AsyncFunctionDef}@anchor{19c9}
@deffn {類別} ast.AsyncFunctionDef (name, args, body, decorator_list, returns, type_comment, type_params)

一個 @code{async def} 函式定義。與 @ref{19ca,,FunctionDef} 具有相同的欄位。


在 3.12 版的變更: 新增了 @code{type_params}。

@end deffn

@geindex Await (ast 中的類別)
@anchor{library/ast ast Await}@anchor{4957}
@deffn {類別} ast.Await (value)

一個 @code{await} 運算式。@code{value} 是它等待的東西。僅在 @ref{19c9,,AsyncFunctionDef} 主體 (body) 中有效。
@end deffn

@example
>>> print(ast.dump(ast.parse("""\
... async def f():
...     await other_func()
... """), indent=4))
Module(
    body=[
        AsyncFunctionDef(
            name='f',
            args=arguments(),
            body=[
                Expr(
                    value=Await(
                        value=Call(
                            func=Name(id='other_func', ctx=Load()))))])])
@end example

@geindex AsyncFor (ast 中的類別)
@geindex AsyncWith (ast 中的類別)
@anchor{library/ast ast AsyncFor}@anchor{4a91}
@deffn {類別} ast.AsyncFor (target, iter, body, orelse, type_comment)
@anchor{library/ast ast AsyncWith}@anchor{4a92}
@deffnx {類別} ast.AsyncWith (items, body, type_comment)

@code{async for} 迴圈和 @code{async with} 情境管理器。它們分別具有與 @ref{4a6d,,For} 和 @ref{4a75,,With} 相同的欄位。僅在 @ref{19c9,,AsyncFunctionDef} 主體中有效。
@end deffn

@cartouche
@quotation 備註 
當字串被 @ref{1c2,,ast.parse()} 剖析時，回傳樹的運算子節點（@code{ast.operator}、@code{ast.unaryop}、@code{ast.cmpop}、@code{ast.boolop} 和 @code{ast.expr_context} 的子類別）將是單例。對其中之一的更改將反映在所有其他出現的相同值中（例如 @ref{4a4b,,ast.Add}）。
@end quotation
@end cartouche

@node ast 輔助程式,編譯器旗標<2>,節點 Node 類別,ast --- 抽象語法樹 Abstract Syntax Trees
@anchor{library/ast ast-helpers}@anchor{4a93}
@subsubsection @code{ast} 輔助程式


除了節點類別之外，@ref{9,,ast} 模組還定義了這些用於遍歷 (traverse) 抽象語法樹的實用函式和類別：

@geindex parse() (於 ast 模組中)
@anchor{library/ast ast parse}@anchor{1c2}
@deffn {函式} ast.parse (source, filename='<unknown>', mode='exec', *, type_comments=False, feature_version=None, optimize=-1)

將原始碼剖析為 AST 節點，相當於 @code{compile(source, filename, mode, flags=FLAGS_VALUE, optimize=optimize)}，其中 @code{FLAGS_VALUE} 在 @code{optimize <= 0} 時為 @code{ast.PyCF_ONLY_AST}，否則為 @code{ast.PyCF_OPTIMIZED_AST}。

如果給定 @code{type_comments=True}，剖析器將被修改為檢查並回傳 
@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{4a94,,ast.PyCF_TYPE_COMMENTS} 新增到傳遞給 @ref{4ac,,compile()} 的旗標中。這將報告錯誤型別註釋的語法錯誤。如果沒有此旗標，型別註釋將被忽略，並且所選 AST 節點上的 @code{type_comment} 欄位將始終為 @code{None}。此外，@code{# type: ignore} 註釋的位置將作為 @ref{4a3f,,Module} 的 @code{type_ignores} 屬性回傳（否則它始終是一個空串列）。

此外，如果 @code{mode} 是 @code{'func_type'}，則輸入語法將會依據 
@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/}「簽名型別註解 (signature type comments)」而被修改，例如 @code{(str, int) -> List[str]}。

將 @code{feature_version} 設定為元組 @code{(major, minor)} 將「盡可能」嘗試使用該 Python 版本的文法進行剖析。目前 @code{major} 必須等於 @code{3}。例如，設定 @code{feature_version=(3, 9)} 將嘗試禁止剖析 @ref{a07,,match} 陳述式。目前 @code{major} 必須為 @code{3}、支援的最低版本為 @code{(3, 7)}（這在未來的 Python 版本中可能會增加）；最高的是 @code{sys.version_info[0:2]}。「盡可能」嘗試意味著不能保證剖析（或剖析的成功）與在與 @code{feature_version} 對應的 Python 版本上運行時相同。

如果來源包含 null 字元 (@code{\0})，則會引發 @ref{2eb,,ValueError}。

@cartouche
@quotation 警告 
請注意，成功將原始碼剖析為 AST 物件並不能保證提供的原始碼是可以執行的有效 Python 程式碼，因為編譯步驟可能會引發進一步的 @ref{18e,,SyntaxError} 例外。例如，原始的 @code{return 42} 為 return 陳述式生成一個有效的 AST 節點，但它不能單獨編譯（它需要位於函式節點內）。

特別是 @ref{1c2,,ast.parse()} 不會執行任何範圍檢查，而編譯步驟才會執行此操作。
@end quotation
@end cartouche

@cartouche
@quotation 警告 
由於 Python AST 編譯器中的堆疊 (stack) 深度限制，太大或太複雜的字串可能會導致 Python 直譯器崩潰。
@end quotation
@end cartouche


在 3.8 版的變更: 新增 @code{type_comments}、@code{mode='func_type'} 與 @code{feature_version}。



在 3.13 版的變更: @code{feature_version} 的最低支援版本現在是 @code{(3, 7)}。新增了 @code{optimize} 引數。

@end deffn

@geindex unparse() (於 ast 模組中)
@anchor{library/ast ast unparse}@anchor{ad9}
@deffn {函式} ast.unparse (ast_obj)

反剖析 @ref{4be,,ast.AST} 物件並生成一個帶有程式碼的字串，如果使用 @ref{1c2,,ast.parse()} 剖析回來，該程式碼將生成等效的 @ref{4be,,ast.AST} 物件。

@cartouche
@quotation 警告 
生成的程式碼字串不一定等於生成 @ref{4be,,ast.AST} 物件的原始程式碼（沒有任何編譯器最佳化，例如常數元組/凍結集合）。
@end quotation
@end cartouche

@cartouche
@quotation 警告 
嘗試剖析高度複雜的運算式會導致 @ref{f63,,RecursionError}。
@end quotation
@end cartouche


在 3.9 版被加入.

@end deffn

@geindex literal_eval() (於 ast 模組中)
@anchor{library/ast ast literal_eval}@anchor{e0d}
@deffn {函式} ast.literal_eval (node_or_string)

為僅包含 Python 文本或容器之顯示的運算式節點或字串來求值。提供的字串或節點只能包含以下 Python 文本結構：字串、位元組、數字、元組、串列、字典、集合、布林值、@code{None} 和 @code{Ellipsis}。

這可用於為包含 Python 值的字串求值，而無需自己剖析這些值。它無法計算任意複雜的運算式，例如涉及運算子或索引。

該函式過去被記錄為「安全」，但沒有定義其含義，這有點誤導讀者，它是特別設計為不去執行 Python 程式碼，與更通用的 @ref{49e,,eval()} 不同。沒有命名空間、沒有名稱查找、也沒有呼叫的能力。但它也不能免受攻擊：相對較小的輸入可能會導致記憶體耗盡或 C 堆疊耗盡，從而導致行程崩潰。某些輸入也可能會出現 CPU 消耗過多而導致拒絕服務的情況。因此不建議在不受信任的資料上呼叫它。

@cartouche
@quotation 警告 
由於 Python AST 編譯器的堆疊深度限制，Python 直譯器可能會崩潰。

它可能會引發 @ref{2eb,,ValueError}、@ref{198,,TypeError}、@ref{18e,,SyntaxError}、@ref{181e,,MemoryError} 和 @ref{f63,,RecursionError}，具體取決於格式錯誤的輸入。
@end quotation
@end cartouche


在 3.2 版的變更: 現在允許位元組和集合文本 (set literal)。



在 3.9 版的變更: 現在支援使用 @code{'set()'} 建立空集合。



在 3.10 版的變更: 對於字串輸入，前導空格和定位字元 (tab) 現在已被去除。

@end deffn

@geindex get_docstring() (於 ast 模組中)
@anchor{library/ast ast get_docstring}@anchor{1d02}
@deffn {函式} ast.get_docstring (node, clean=True)

回傳給定 `node' 的文件字串 (docstring)（必須是 @ref{19ca,,FunctionDef}、@ref{19c9,,AsyncFunctionDef}、@ref{19c8,,ClassDef} 或 @ref{4a3f,,Module} 節點）或如果它沒有文件字串則為 @code{None}。如果 `clean' 為 true，則使用 @ref{197d,,inspect.cleandoc()} 清理文件字串的縮排。


在 3.5 版的變更: 目前已支援 @ref{19c9,,AsyncFunctionDef}。

@end deffn

@geindex get_source_segment() (於 ast 模組中)
@anchor{library/ast ast get_source_segment}@anchor{bc2}
@deffn {函式} ast.get_source_segment (source, node, *, padded=False)

取得生成 `node' 的 `source' 的原始碼片段。如果某些位置資訊（@ref{4a39,,lineno}、@ref{4a3b,,end_lineno}、@ref{4a3a,,col_offset} 或 @ref{4a3c,,end_col_offset}）遺漏，則回傳 @code{None}。

如果 `padded' 為 @code{True}，則多列陳述式的第一列將用空格填充 (padded) 以匹配其原始位置。


在 3.8 版被加入.

@end deffn

@geindex fix_missing_locations() (於 ast 模組中)
@anchor{library/ast ast fix_missing_locations}@anchor{4a95}
@deffn {函式} ast.fix_missing_locations (node)

當你使用 @ref{4ac,,compile()} 編譯節點樹時，對於每個有支援 @ref{4a39,,lineno} 和 @ref{4a3a,,col_offset} 屬性之節點，編譯器預期他們的這些屬性都要存在。填入生成的節點相當繁瑣，因此該輔助工具透過將這些屬性設定為父節點的值，在尚未設定的地方遞迴地新增這些屬性。它從 `node' 開始遞迴地作用。
@end deffn

@geindex increment_lineno() (於 ast 模組中)
@anchor{library/ast ast increment_lineno}@anchor{1a51}
@deffn {函式} ast.increment_lineno (node, n=1)

將樹中從 `node' 開始的每個節點的列號和結束列號增加 `n'。這對於「移動程式碼」到檔案中的不同位置很有用。
@end deffn

@geindex copy_location() (於 ast 模組中)
@anchor{library/ast ast copy_location}@anchor{4a96}
@deffn {函式} ast.copy_location (new_node, old_node)

如果可行，將原始位置（@ref{4a39,,lineno}、@ref{4a3a,,col_offset}、@ref{4a3b,,end_lineno} 和 @ref{4a3c,,end_col_offset} ）從 `old_node' 複製到 `new_node'，並回傳 `new_node' 。
@end deffn

@geindex iter_fields() (於 ast 模組中)
@anchor{library/ast ast iter_fields}@anchor{4a97}
@deffn {函式} ast.iter_fields (node)

為 `node' 上存在的 @code{node._fields} 中的每個欄位生成一個 @code{(fieldname, value)} 元組。
@end deffn

@geindex iter_child_nodes() (於 ast 模組中)
@anchor{library/ast ast iter_child_nodes}@anchor{4a98}
@deffn {函式} ast.iter_child_nodes (node)

生成 `node' 的所有直接子節點，即作為節點的所有欄位以及作為節點串列欄位的所有項目。
@end deffn

@geindex walk() (於 ast 模組中)
@anchor{library/ast ast walk}@anchor{4a99}
@deffn {函式} ast.walk (node)

遞迴地生成樹中從 `node' 開始的所有後代節點（包括 `node' 本身），不按指定順序。如果你只想就地修改節點而不關心情境，這非常有用。
@end deffn

@geindex NodeVisitor (ast 中的類別)
@anchor{library/ast ast NodeVisitor}@anchor{2ef}
@deffn {類別} ast.NodeVisitor

節點瀏覽者基底類別，它遍歷抽象語法樹並為找到的每個節點呼叫瀏覽者函式。該函式可能會回傳一個由 @ref{4a9a,,visit()} 方法轉發的值。

這個類別應該被子類別化，子類別新增瀏覽者方法。

@geindex visit() (ast.NodeVisitor 的方法)
@anchor{library/ast ast NodeVisitor visit}@anchor{4a9a}
@deffn {方法} visit (node)

瀏覽一個節點。預設實作呼叫名為 @code{self.visit_@var{classname}} 的方法，其中 `classname' 是節點類別的名稱，或者在該方法不存在時呼叫 @ref{4a9b,,generic_visit()}。
@end deffn

@geindex generic_visit() (ast.NodeVisitor 的方法)
@anchor{library/ast ast NodeVisitor generic_visit}@anchor{4a9b}
@deffn {方法} generic_visit (node)

該瀏覽者對該節點的所有子節點呼叫 @ref{4a9a,,visit()}。

請注意，除非瀏覽者呼叫 @ref{4a9b,,generic_visit()} 或瀏覽它們本身，否則不會瀏覽具有自定義瀏覽者方法的節點之子節點。
@end deffn

@geindex visit_Constant() (ast.NodeVisitor 的方法)
@anchor{library/ast ast NodeVisitor visit_Constant}@anchor{c5a}
@deffn {方法} visit_Constant (node)

處理所有常數節點。
@end deffn

如果你想在遍歷期間將變更應用 (apply) 於節點，請不要使用 @ref{2ef,,NodeVisitor}。為此，有個允許修改的特殊遍歷瀏覽者工具 @ref{4a9c,,NodeTransformer}。


在 3.8 版之後被棄用: @code{visit_Num()}、@code{visit_Str()}、@code{visit_Bytes()}、@code{visit_NameConstant()} 和 @code{visit_Ellipsis()} 方法現已棄用，並且不會在未來的Python 版本中被呼叫。新增 @ref{c5a,,visit_Constant()} 方法來處理所有常數節點。

@end deffn

@geindex NodeTransformer (ast 中的類別)
@anchor{library/ast ast NodeTransformer}@anchor{4a9c}
@deffn {類別} ast.NodeTransformer

一個 @ref{2ef,,NodeVisitor} 子類別，它會遍歷抽象語法樹並允許修改節點。

@ref{4a9c,,NodeTransformer} 將遍歷 AST 並使用瀏覽者方法的回傳值來替換或刪除舊節點。如果瀏覽者方法的回傳值為 @code{None}，則該節點將從其位置中刪除，否則將被替換為回傳值。回傳值可能是原始節點，在這種情況下不會發生替換。

下面是一個示範用的 transformer，它將查找所有出現名稱 (@code{foo}) 並改寫為 @code{data['foo']}：

@example
class RewriteName(NodeTransformer):

    def visit_Name(self, node):
        return Subscript(
            value=Name(id='data', ctx=Load()),
            slice=Constant(value=node.id),
            ctx=node.ctx
        )
@end example

請記住，如果你正在操作的節點有子節點，你必須自己轉換子節點或先呼叫該節點的 @ref{4a9b,,generic_visit()} 方法。

對於屬於陳述式總集 (collection) 一部分的節點（適用於所有陳述式節點），瀏覽者還可以回傳節點串列，而不僅僅是單個節點。

如果 @ref{4a9c,,NodeTransformer} 引進了新節點（不屬於原始樹的一部分），但沒有給它們提供位置資訊（例如 @ref{4a39,,lineno}），則應使用新的子樹呼叫 @ref{4a95,,fix_missing_locations()} 以重新計算位置資訊：

@example
tree = ast.parse('foo', mode='eval')
new_tree = fix_missing_locations(RewriteName().visit(tree))
@end example

你通常會像這樣使用 transformer：

@example
node = YourTransformer().visit(node)
@end example
@end deffn

@geindex dump() (於 ast 模組中)
@anchor{library/ast ast dump}@anchor{ad8}
@deffn {函式} ast.dump (node, annotate_fields=True, include_attributes=False, *, indent=None, show_empty=False)

回傳 `node' 中樹的格式化傾印 (formatted dump)，這主要用於除錯。如果 `annotate_fields' 為 true（為預設值），則回傳的字串將顯示欄位的名稱和值。如果 `annotate_fields' 為 false，則透過省略明確的欄位名稱，結果字串將更加縮減簡潔。預設情況下，不會傾印列號和行偏移量等屬性。如果需要，可以設定 `include_attributes' 為 true。

如果 `indent' 是非負整數或字串，那麼樹將使用該縮排級別來做漂亮印出 (pretty-print)。縮排級別 0、負數或 @code{""} 只會插入換列符號 (newlines)。@code{None}（預設值）代表選擇單列表示。使用正整數縮排可以在每個級別縮排相同數量的空格。如果 `indent' 是一個字串（例如 @code{"\t"}），則該字串用於縮排每個級別。

如果 `show_empty' 為 false（預設值），則輸出中將省略可選的空串列。可選的 @code{None} 值總是會被省略。


在 3.9 版的變更: 新增 `indent' 選項。



在 3.13 版的變更: 新增 `show_empty' 選項。

@example
>>> print(ast.dump(ast.parse("""\
... async def f():
...     await other_func()
... """), indent=4, show_empty=True))
Module(
    body=[
        AsyncFunctionDef(
            name='f',
            args=arguments(
                posonlyargs=[],
                args=[],
                kwonlyargs=[],
                kw_defaults=[],
                defaults=[]),
            body=[
                Expr(
                    value=Await(
                        value=Call(
                            func=Name(id='other_func', ctx=Load()),
                            args=[],
                            keywords=[])))],
            decorator_list=[],
            type_params=[])],
    type_ignores=[])
@end example

@end deffn

@node 編譯器旗標<2>,命令列用法<9>,ast 輔助程式,ast --- 抽象語法樹 Abstract Syntax Trees
@anchor{library/ast ast-compiler-flags}@anchor{2470}@anchor{library/ast compiler-flags}@anchor{4a9d}
@subsubsection 編譯器旗標


可以將以下旗標傳遞給 @ref{4ac,,compile()} 以變更對程式的編譯效果：

@geindex PyCF_ALLOW_TOP_LEVEL_AWAIT (於 ast 模組中)
@anchor{library/ast ast PyCF_ALLOW_TOP_LEVEL_AWAIT}@anchor{4a9e}
@deffn {資料} ast.PyCF_ALLOW_TOP_LEVEL_AWAIT

啟用對最高階 @code{await}、@code{async for}、@code{async with} 和非同步綜合運算的支援。


在 3.8 版被加入.

@end deffn

@geindex PyCF_ONLY_AST (於 ast 模組中)
@anchor{library/ast ast PyCF_ONLY_AST}@anchor{4a35}
@deffn {資料} ast.PyCF_ONLY_AST

生成並回傳抽象語法樹，而不是回傳已編譯的程式碼物件。
@end deffn

@geindex PyCF_OPTIMIZED_AST (於 ast 模組中)
@anchor{library/ast ast PyCF_OPTIMIZED_AST}@anchor{4a9f}
@deffn {資料} ast.PyCF_OPTIMIZED_AST

回傳的 AST 會根據 @ref{4ac,,compile()} 或 @ref{1c2,,ast.parse()} 中的 `optimize' 引數進行最佳化。


在 3.13 版被加入.

@end deffn

@geindex PyCF_TYPE_COMMENTS (於 ast 模組中)
@anchor{library/ast ast PyCF_TYPE_COMMENTS}@anchor{4a94}
@deffn {資料} ast.PyCF_TYPE_COMMENTS

啟用對 
@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/} 樣式型別註釋的支援 (@code{# type: <type>}, @code{# type: ignore <stuff>})。


在 3.8 版被加入.

@end deffn

@geindex compare() (於 ast 模組中)
@anchor{library/ast ast compare}@anchor{1bf}
@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.


在 3.14 版被加入.

@end deffn

@node 命令列用法<9>,,編譯器旗標<2>,ast --- 抽象語法樹 Abstract Syntax Trees
@anchor{library/ast ast-cli}@anchor{4aa0}@anchor{library/ast command-line-usage}@anchor{4aa1}
@subsubsection 命令列用法



在 3.9 版被加入.


@ref{9,,ast} 模組可以作為腳本從命令列執行，可以像這樣簡單地做到：

@example
python -m ast [-m <mode>] [-a] [infile]
@end example

以下選項可被接受：

@geindex ast 命令列選項; -h
@geindex ast 命令列選項; --help
@anchor{library/ast cmdoption-ast-h}@anchor{4aa2}@anchor{library/ast cmdoption-ast-help}@anchor{4aa3}
@deffn {Option} @w{-}h, @w{-}@w{-}help

顯示幫助訊息並退出。
@end deffn

@geindex ast 命令列選項; -m
@geindex ast 命令列選項; --mode
@anchor{library/ast cmdoption-ast-m}@anchor{4aa4}
@deffn {Option} @w{-}m <mode>
@anchor{library/ast cmdoption-ast-mode}@anchor{4aa5}
@deffnx {Option} @w{-}@w{-}mode <mode>

指定必須編譯哪種類型的程式碼，像是 @ref{1c2,,parse()} 中的 `mode' 引數。
@end deffn

@geindex ast 命令列選項; --no-type-comments
@anchor{library/ast cmdoption-ast-no-type-comments}@anchor{4aa6}
@deffn {Option} @w{-}@w{-}no@w{-}type@w{-}comments

不要剖析型別註解。
@end deffn

@geindex ast 命令列選項; -a
@geindex ast 命令列選項; --include-attributes
@anchor{library/ast cmdoption-ast-a}@anchor{4aa7}@anchor{library/ast cmdoption-ast-include-attributes}@anchor{4aa8}
@deffn {Option} @w{-}a, @w{-}@w{-}include@w{-}attributes

包括列號和行偏移量等屬性。
@end deffn

@geindex ast 命令列選項; -i
@geindex ast 命令列選項; --indent
@anchor{library/ast cmdoption-ast-i}@anchor{4aa9}
@deffn {Option} @w{-}i <indent>
@anchor{library/ast cmdoption-ast-indent}@anchor{4aaa}
@deffnx {Option} @w{-}@w{-}indent <indent>

AST 中節點的縮進（空格數）。
@end deffn

@geindex ast 命令列選項; --feature-version
@anchor{library/ast cmdoption-ast-feature-version}@anchor{1c3}
@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.


在 3.14 版被加入.

@end deffn

@geindex ast 命令列選項; -O
@geindex ast 命令列選項; --optimize
@anchor{library/ast cmdoption-ast-O}@anchor{4aab}
@deffn {Option} @w{-}O <level>
@anchor{library/ast cmdoption-ast-optimize}@anchor{1c4}
@deffnx {Option} @w{-}@w{-}optimize <level>

Optimization level for parser. Defaults to no optimization.


在 3.14 版被加入.

@end deffn

@geindex ast 命令列選項; --show-empty
@anchor{library/ast cmdoption-ast-show-empty}@anchor{1c5}
@deffn {Option} @w{-}@w{-}show@w{-}empty

Show empty lists and fields that are @code{None}. Defaults to not showing empty
objects.


在 3.14 版被加入.

@end deffn

如果指定了 @code{infile}，則其內容將被剖析為 AST 並傾印 (dump) 到 stdout。否則會從 stdin 讀取內容。


@subsubheading 也參考


Green Tree Snakes@footnote{https://greentreesnakes.readthedocs.io/} 是一個外部文件資源，提供了有關使用 Python AST 的詳細資訊。

ASTTokens@footnote{https://asttokens.readthedocs.io/en/latest/user-guide.html} 使用生成它們的原始碼中的標記和文本的位置來註釋 Python AST。這對於進行原始碼轉換的工具很有幫助。

leoAst.py@footnote{https://leo-editor.github.io/leo-editor/appendices.html#leoast-py} 透過在 token 和 ast 節點之間插入雙向鏈結，統一了 python 程式的基於 token 和基於剖析樹的視圖。

LibCST@footnote{https://libcst.readthedocs.io/} 將程式碼剖析為具體語法樹 (Concrete Syntax Tree)，看起來像 ast 樹並保留所有格式詳細資訊。它對於建置自動重構 (codemod) 應用程式和 linter 非常有用。

Parso@footnote{https://parso.readthedocs.io} 是一個 Python 剖析器，支援不同 Python 版本的錯誤復原和往返剖析。Parso 還能夠列出 Python 檔案中的多個語法錯誤。


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node symtable --- 存取編譯器的符號表,token --- 與 Python 剖析樹一起使用的常數,ast --- 抽象語法樹 Abstract Syntax Trees,Python 語言服務
@anchor{library/symtable doc}@anchor{4aac}@anchor{library/symtable module-symtable}@anchor{de}@anchor{library/symtable symtable-access-to-the-compiler-s-symbol-tables}@anchor{4aad}@anchor{library/symtable translation-repo}@anchor{4aae}
@subsection @code{symtable} --- 存取編譯器的符號表


@geindex module; symtable

`原始碼：'Lib/symtable.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/symtable.py}


__________________________________________________________________


符號表 (symbol table) 是在生成位元組碼 (bytecode) 之前由編譯器從 AST 生成的。符號表負責計算程式碼中每個識別器 (identifier) 的作用域。@ref{de,,symtable} 提供了一個介面來檢查這些表。

@menu
* 產生符號表:: 
* 檢查符號表:: 
* 命令列用法: 命令列用法<10>. 

@end menu

@node 產生符號表,檢查符號表,,symtable --- 存取編譯器的符號表
@anchor{library/symtable generating-symbol-tables}@anchor{4aaf}
@subsubsection 產生符號表


@geindex symtable() (於 symtable 模組中)
@anchor{library/symtable symtable symtable}@anchor{1c9a}
@deffn {函式} symtable.symtable (code, filename, compile_type)

回傳 Python 原始 `code' 的頂層 @ref{4ab0,,SymbolTable}。`filename' 是包含程式碼之檔案之名稱。`compile_type' 類似於 @ref{4ac,,compile()} 的 `mode' 引數。
@end deffn

@node 檢查符號表,命令列用法<10>,產生符號表,symtable --- 存取編譯器的符號表
@anchor{library/symtable examining-symbol-tables}@anchor{4ab1}
@subsubsection 檢查符號表


@geindex SymbolTableType (symtable 中的類別)
@anchor{library/symtable symtable SymbolTableType}@anchor{18b9}
@deffn {類別} symtable.SymbolTableType

表明 @ref{4ab0,,SymbolTable} 物件型別的列舉。

@geindex MODULE (symtable.SymbolTableType 的屬性)
@anchor{library/symtable symtable SymbolTableType MODULE}@anchor{4ab2}
@deffn {屬性} MODULE = "module"

用於模組的符號表。
@end deffn

@geindex FUNCTION (symtable.SymbolTableType 的屬性)
@anchor{library/symtable symtable SymbolTableType FUNCTION}@anchor{4ab3}
@deffn {屬性} FUNCTION = "function"

用於函式的符號表。
@end deffn

@geindex CLASS (symtable.SymbolTableType 的屬性)
@anchor{library/symtable symtable SymbolTableType CLASS}@anchor{4ab4}
@deffn {屬性} CLASS = "class"

用於類別的符號表。
@end deffn

以下成員代表不同風格的@ref{4a6,,註釋作用域}。

@geindex ANNOTATION (symtable.SymbolTableType 的屬性)
@anchor{library/symtable symtable SymbolTableType ANNOTATION}@anchor{4ab5}
@deffn {屬性} ANNOTATION = "annotation"

如果 @code{from __future__ import annotations} 處於活動狀態，則用於註解。
@end deffn

@geindex TYPE_ALIAS (symtable.SymbolTableType 的屬性)
@anchor{library/symtable symtable SymbolTableType TYPE_ALIAS}@anchor{4ab6}
@deffn {屬性} TYPE_ALIAS = "type alias"

用於 @ref{665,,type} 結構的符號表。
@end deffn

@geindex TYPE_PARAMETERS (symtable.SymbolTableType 的屬性)
@anchor{library/symtable symtable SymbolTableType TYPE_PARAMETERS}@anchor{4ab7}
@deffn {屬性} TYPE_PARAMETERS = "type parameters"

用於@ref{67b,,泛型函式 (generic functions)}或@ref{67a,,泛型類別 (generic classes)}的符號表。
@end deffn

@geindex TYPE_VARIABLE (symtable.SymbolTableType 的屬性)
@anchor{library/symtable symtable SymbolTableType TYPE_VARIABLE}@anchor{4ab8}
@deffn {屬性} TYPE_VARIABLE = "type variable"

用於形式意義上 (formal sense) 的繫結、約束元組 (constraint tuple) 或單一型別變數的預設值的符號表，即 TypeVar、TypeVarTuple 或 ParamSpec 物件（後兩者不支援繫結或約束元組）。
@end deffn


在 3.13 版被加入.

@end deffn

@geindex SymbolTable (symtable 中的類別)
@anchor{library/symtable symtable SymbolTable}@anchor{4ab0}
@deffn {類別} symtable.SymbolTable

一個區塊 (block) 的命名空間表 (namespace table) 。建構函式 (constructor) 並不公開。

@geindex get_type() (symtable.SymbolTable 的方法)
@anchor{library/symtable symtable SymbolTable get_type}@anchor{18ba}
@deffn {方法} get_type ()

回傳符號表的類型。可能的值為 @ref{18b9,,SymbolTableType} 列舉的成員。


在 3.12 版的變更: 新增了 @code{'annotation'}、@code{'TypeVar bound'}、@code{'type alias'} 和 @code{'type parameter'} 作為可能的回傳值。



在 3.13 版的變更: 回傳值是 @ref{18b9,,SymbolTableType} 列舉的成員。

回傳字串的確切值在未來可能會發生變化，因此建議使用 @ref{18b9,,SymbolTableType} 成員而不是寫死 (hard-coded) 字串。

@end deffn

@geindex get_id() (symtable.SymbolTable 的方法)
@anchor{library/symtable symtable SymbolTable get_id}@anchor{4ab9}
@deffn {方法} get_id ()

回傳表的識別器。
@end deffn

@geindex get_name() (symtable.SymbolTable 的方法)
@anchor{library/symtable symtable SymbolTable get_name}@anchor{4aba}
@deffn {方法} get_name ()

回傳表的名稱。如果表用於類別，則這是類別的名稱；如果表用於函式，則這是函式的名稱；如果表是全域的，則為 @code{'top'} （@ref{18ba,,get_type()} 會回傳 @code{'module'}）。對於型別參數作用域（用於泛型類別、函式和型別別名），它是底層類別、函式或型別別名的名稱。對於型別別名作用域，它是型別別名的名稱。對於 @ref{481,,TypeVar} 綁定作用域，它會是 @code{TypeVar} 的名稱。
@end deffn

@geindex get_lineno() (symtable.SymbolTable 的方法)
@anchor{library/symtable symtable SymbolTable get_lineno}@anchor{4abb}
@deffn {方法} get_lineno ()

回傳此表所代表的區塊中第一行的編號。
@end deffn

@geindex is_optimized() (symtable.SymbolTable 的方法)
@anchor{library/symtable symtable SymbolTable is_optimized}@anchor{4abc}
@deffn {方法} is_optimized ()

如果可以最佳化該表中的區域變數，則回傳 @code{True}。
@end deffn

@geindex is_nested() (symtable.SymbolTable 的方法)
@anchor{library/symtable symtable SymbolTable is_nested}@anchor{4abd}
@deffn {方法} is_nested ()

如果區塊是巢狀類別或函式，則回傳 @code{True}。
@end deffn

@geindex has_children() (symtable.SymbolTable 的方法)
@anchor{library/symtable symtable SymbolTable has_children}@anchor{4abe}
@deffn {方法} has_children ()

如果區塊內有巢狀命名空間，則回傳 @code{True}。這些可以透過 @ref{4abf,,get_children()} 獲得。
@end deffn

@geindex get_identifiers() (symtable.SymbolTable 的方法)
@anchor{library/symtable symtable SymbolTable get_identifiers}@anchor{4ac0}
@deffn {方法} get_identifiers ()

回傳包含表中符號之名稱的視圖物件 (view object)。請參閱@ref{254e,,視圖物件的文件}。
@end deffn

@geindex lookup() (symtable.SymbolTable 的方法)
@anchor{library/symtable symtable SymbolTable lookup}@anchor{4ac1}
@deffn {方法} lookup (name)

在表中查找 `name' 並回傳一個 @ref{289,,Symbol} 實例。
@end deffn

@geindex get_symbols() (symtable.SymbolTable 的方法)
@anchor{library/symtable symtable SymbolTable get_symbols}@anchor{4ac2}
@deffn {方法} get_symbols ()

回傳表中名稱的 @ref{289,,Symbol} 實例串列。
@end deffn

@geindex get_children() (symtable.SymbolTable 的方法)
@anchor{library/symtable symtable SymbolTable get_children}@anchor{4abf}
@deffn {方法} get_children ()

回傳巢狀符號表的串列。
@end deffn
@end deffn

@geindex Function (symtable 中的類別)
@anchor{library/symtable symtable Function}@anchor{4ac3}
@deffn {類別} symtable.Function

一個函式或方法的命名空間。該類別繼承自 @ref{4ab0,,SymbolTable}。

@geindex get_parameters() (symtable.Function 的方法)
@anchor{library/symtable symtable Function get_parameters}@anchor{4ac4}
@deffn {方法} get_parameters ()

回傳一個包含此函式參數名稱的元組 (tuple)。
@end deffn

@geindex get_locals() (symtable.Function 的方法)
@anchor{library/symtable symtable Function get_locals}@anchor{4ac5}
@deffn {方法} get_locals ()

回傳一個包含此函式中區域變數 (locals) 名稱的元組。
@end deffn

@geindex get_globals() (symtable.Function 的方法)
@anchor{library/symtable symtable Function get_globals}@anchor{4ac6}
@deffn {方法} get_globals ()

回傳一個包含此函式中全域變數 (globals) 名稱的元組。
@end deffn

@geindex get_nonlocals() (symtable.Function 的方法)
@anchor{library/symtable symtable Function get_nonlocals}@anchor{4ac7}
@deffn {方法} get_nonlocals ()

回傳一個包含此函式中明確宣告的非區域變數 (nonlocals) 名稱的元組。
@end deffn

@geindex get_frees() (symtable.Function 的方法)
@anchor{library/symtable symtable Function get_frees}@anchor{4ac8}
@deffn {方法} get_frees ()

回傳一個包含此函式中的@ref{180c,,自由（閉包）變數 (free (closure) variables)} 名稱的元組。
@end deffn
@end deffn

@geindex Class (symtable 中的類別)
@anchor{library/symtable symtable Class}@anchor{4ac9}
@deffn {類別} symtable.Class

一個類別的命名空間。該類別繼承自 @ref{4ab0,,SymbolTable}。

@geindex get_methods() (symtable.Class 的方法)
@anchor{library/symtable symtable Class get_methods}@anchor{31c}
@deffn {方法} get_methods ()

回傳一個包含類別中聲明的類似方法之函式名稱的元組。

在這裡，術語「方法 (method)」表示透過 @ref{164f,,def} 或 @ref{7e6,,async def} 在類別主體中定義的`任何'函式。

@ref{31c,,get_methods()} 不會取得更深作用域內定義的函式（例如在內部類別中）。

舉例來說：

@c import warnings
@c context = warnings.catch_warnings()
@c context.__enter__()
@c warnings.simplefilter("ignore", category=DeprecationWarning)

@c context.__exit__()

@example
>>> import symtable
>>> st = symtable.symtable('@w{'}'
... def outer(): pass
...
... class A:
...    def f():
...        def w(): pass
...
...    def g(self): pass
...
...    @@classmethod
...    async def h(cls): pass
...
...    global outer
...    def outer(self): pass
... '@w{'}', 'test', 'exec')
>>> class_A = st.get_children()[2]
>>> class_A.get_methods()
('f', 'g', 'h')
@end example

儘管 @code{A().f()} 會在 runtime 引發 @ref{198,,TypeError}，但 @code{A.f} 仍然被視為類似方法的函式。


Deprecated since version 3.14, will be removed in version 3.16.

@end deffn
@end deffn

@geindex Symbol (symtable 中的類別)
@anchor{library/symtable symtable Symbol}@anchor{289}
@deffn {類別} symtable.Symbol

@ref{4ab0,,SymbolTable} 中的條目對應於來源中的識別器。建構函式不是公開的。

@geindex get_name() (symtable.Symbol 的方法)
@anchor{library/symtable symtable Symbol get_name}@anchor{4aca}
@deffn {方法} get_name ()

回傳符號的名稱。
@end deffn

@geindex is_referenced() (symtable.Symbol 的方法)
@anchor{library/symtable symtable Symbol is_referenced}@anchor{4acb}
@deffn {方法} is_referenced ()

如果該符號在其區塊中使用，則回傳 @code{True}。
@end deffn

@geindex is_imported() (symtable.Symbol 的方法)
@anchor{library/symtable symtable Symbol is_imported}@anchor{4acc}
@deffn {方法} is_imported ()

如果符號是從 import 陳述式建立的，則回傳 @code{True}。
@end deffn

@geindex is_parameter() (symtable.Symbol 的方法)
@anchor{library/symtable symtable Symbol is_parameter}@anchor{4acd}
@deffn {方法} is_parameter ()

如果符號是一個參數，則回傳 @code{True}。
@end deffn

@geindex is_type_parameter() (symtable.Symbol 的方法)
@anchor{library/symtable symtable Symbol is_type_parameter}@anchor{18bb}
@deffn {方法} is_type_parameter ()

如果符號是一個型別參數，則回傳 @code{True}。


在 3.14 版被加入.

@end deffn

@geindex is_global() (symtable.Symbol 的方法)
@anchor{library/symtable symtable Symbol is_global}@anchor{4ace}
@deffn {方法} is_global ()

如果符號是全域的，則回傳 @code{True}。
@end deffn

@geindex is_nonlocal() (symtable.Symbol 的方法)
@anchor{library/symtable symtable Symbol is_nonlocal}@anchor{1cd5}
@deffn {方法} is_nonlocal ()

如果符號是非區域的，則回傳 @code{True}。
@end deffn

@geindex is_declared_global() (symtable.Symbol 的方法)
@anchor{library/symtable symtable Symbol is_declared_global}@anchor{1526}
@deffn {方法} is_declared_global ()

如果使用全域陳述式將符號聲明為全域的，則回傳 @code{True}。
@end deffn

@geindex is_local() (symtable.Symbol 的方法)
@anchor{library/symtable symtable Symbol is_local}@anchor{4acf}
@deffn {方法} is_local ()

如果符號是其區塊的區域符號，則回傳 @code{True}。
@end deffn

@geindex is_annotated() (symtable.Symbol 的方法)
@anchor{library/symtable symtable Symbol is_annotated}@anchor{4ad0}
@deffn {方法} is_annotated ()

如果符號有被註釋，則回傳 @code{True}。


在 3.6 版被加入.

@end deffn

@geindex is_free() (symtable.Symbol 的方法)
@anchor{library/symtable symtable Symbol is_free}@anchor{4ad1}
@deffn {方法} is_free ()

如果該符號在其區塊中被參照 (referenced) 但未被賦值 (assigned)，則回傳 @code{True}。
@end deffn

@geindex is_free_class() (symtable.Symbol 的方法)
@anchor{library/symtable symtable Symbol is_free_class}@anchor{28c}
@deffn {方法} is_free_class ()

Return `True' if a class-scoped symbol is free from
the perspective of a method.

參考以下範例：

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


在 3.14 版被加入.

@end deffn

@geindex is_assigned() (symtable.Symbol 的方法)
@anchor{library/symtable symtable Symbol is_assigned}@anchor{4ad2}
@deffn {方法} is_assigned ()

如果該符號被賦值到其區塊中，則回傳 @code{True}。
@end deffn

@geindex is_comp_iter() (symtable.Symbol 的方法)
@anchor{library/symtable symtable Symbol is_comp_iter}@anchor{28b}
@deffn {方法} is_comp_iter ()

Return @code{True} if the symbol is a comprehension iteration variable.


在 3.14 版被加入.

@end deffn

@geindex is_comp_cell() (symtable.Symbol 的方法)
@anchor{library/symtable symtable Symbol is_comp_cell}@anchor{28a}
@deffn {方法} is_comp_cell ()

Return @code{True} if the symbol is a cell in an inlined comprehension.


在 3.14 版被加入.

@end deffn

@geindex is_namespace() (symtable.Symbol 的方法)
@anchor{library/symtable symtable Symbol is_namespace}@anchor{4ad3}
@deffn {方法} is_namespace ()

如果名稱綁定引入 (introduce) 新的命名空間，則回傳 @code{True}。

如果名稱用作函式或類別陳述式的目標，則這將會是 true。

舉例來說：

@example
>>> table = symtable.symtable("def some_func(): pass", "string", "exec")
>>> table.lookup("some_func").is_namespace()
True
@end example

請注意，單個名稱可以綁定到多個物件。如果結果為 @code{True}，則該名稱也可能被綁定到其他物件，例如 int 或 list，而不會引入新的命名空間。
@end deffn

@geindex get_namespaces() (symtable.Symbol 的方法)
@anchor{library/symtable symtable Symbol get_namespaces}@anchor{4ad4}
@deffn {方法} get_namespaces ()

回傳綁定到該名稱的命名空間的串列。
@end deffn

@geindex get_namespace() (symtable.Symbol 的方法)
@anchor{library/symtable symtable Symbol get_namespace}@anchor{4ad5}
@deffn {方法} get_namespace ()

回傳綁定到該名稱的命名空間。如果該名稱綁定了多個命名空間或沒有命名空間，則會引發 @ref{2eb,,ValueError}。
@end deffn
@end deffn

@node 命令列用法<10>,,檢查符號表,symtable --- 存取編譯器的符號表
@anchor{library/symtable command-line-usage}@anchor{4ad6}@anchor{library/symtable symtable-cli}@anchor{4ad7}
@subsubsection 命令列用法



在 3.13 版被加入.


@ref{de,,symtable} 模組可以從命令列作為腳本執行。

@example
python -m symtable [infile...]
@end example

為指定的 Python 原始檔產生符號表並轉儲 (dump) 到 stdout。如果未指定輸入檔案，則從 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 --- 與 Python 剖析樹一起使用的常數,keyword --- 檢驗 Python 關鍵字,symtable --- 存取編譯器的符號表,Python 語言服務
@anchor{library/token doc}@anchor{4ad8}@anchor{library/token module-token}@anchor{100}@anchor{library/token token-constants-used-with-python-parse-trees}@anchor{4ad9}@anchor{library/token translation-repo}@anchor{4ada}
@subsection @code{token} --- 與 Python 剖析樹一起使用的常數


@geindex module; token

`原始碼：'Lib/token.py@footnote{https://github.com/python/cpython/tree/3.14/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{4adb,,PLUS} or @ref{214e,,OP}, or
a @code{"match"} token may be either @ref{217c,,NAME} or @ref{4adc,,SOFT_KEYWORD}.

@geindex tok_name (於 token 模組中)
@anchor{library/token token tok_name}@anchor{4add}
@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{4ade}
@deffn {函式} token.ISTERMINAL (x)

Return @code{True} for terminal token values.
@end deffn

@geindex ISNONTERMINAL() (於 token 模組中)
@anchor{library/token token ISNONTERMINAL}@anchor{4adf}
@deffn {函式} token.ISNONTERMINAL (x)

Return @code{True} for non-terminal token values.
@end deffn

@geindex ISEOF() (於 token 模組中)
@anchor{library/token token ISEOF}@anchor{4ae0}
@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{217c}
@deffn {資料} token.NAME

Token value that indicates an @ref{2164,,identifier}.
Note that keywords are also initially tokenized as @code{NAME} tokens.
@end deffn

@geindex NUMBER (於 token 模組中)
@anchor{library/token token NUMBER}@anchor{217d}
@deffn {資料} token.NUMBER

Token value that indicates a @ref{2165,,numeric literal}
@end deffn

@geindex STRING (於 token 模組中)
@anchor{library/token token STRING}@anchor{217e}
@deffn {資料} token.STRING

Token value that indicates a @ref{2163,,string or byte literal},
excluding @ref{19a,,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{214e}
@deffn {資料} token.OP

A generic token value that indicates an
@ref{2150,,operator} or @ref{214f,,delimiter}.

`CPython 實作細節：' This value is only reported by the @ref{101,,tokenize} module.
Internally, the tokenizer uses
@ref{21d3,,exact token types} instead.
@end deffn

@geindex COMMENT (於 token 模組中)
@anchor{library/token token COMMENT}@anchor{4ae1}
@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{2158}
@deffn {資料} token.NEWLINE

Token value that indicates the end of a @ref{2169,,logical line}.
@end deffn

@geindex NL (於 token 模組中)
@anchor{library/token token NL}@anchor{4ae2}
@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{1fc3}
@deffn {資料} token.INDENT

Token value used at the beginning of a @ref{2169,,logical line}
to indicate the start of an @ref{2160,,indented block}.
@end deffn

@geindex DEDENT (於 token 模組中)
@anchor{library/token token DEDENT}@anchor{2176}
@deffn {資料} token.DEDENT

Token value used at the beginning of a @ref{2169,,logical line}
to indicate the end of an @ref{2160,,indented block}.
@end deffn

@geindex FSTRING_START (於 token 模組中)
@anchor{library/token token FSTRING_START}@anchor{4ae3}
@deffn {資料} token.FSTRING_START

Token value used to indicate the beginning of an
@ref{19a,,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{4ae4}
@deffn {資料} token.FSTRING_MIDDLE

Token value used for literal text inside an @ref{19a,,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{4ae5,,LBRACE}, @ref{4ae6,,RBRACE}, @ref{4ae7,,EXCLAMATION} and @ref{4ae8,,COLON}
tokens.
@end deffn

@geindex FSTRING_END (於 token 模組中)
@anchor{library/token token FSTRING_END}@anchor{4ae9}
@deffn {資料} token.FSTRING_END

Token value used to indicate the end of a @ref{19a,,f-string}.

`CPython 實作細節：' The token string contains the closing quote(s).
@end deffn

@geindex TSTRING_START (於 token 模組中)
@anchor{library/token token TSTRING_START}@anchor{4aea}
@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.


在 3.14 版被加入.

@end deffn

@geindex TSTRING_MIDDLE (於 token 模組中)
@anchor{library/token token TSTRING_MIDDLE}@anchor{4aeb}
@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{4ae5,,LBRACE}, @ref{4ae6,,RBRACE}, @ref{4ae7,,EXCLAMATION} and @ref{4ae8,,COLON}
tokens.


在 3.14 版被加入.

@end deffn

@geindex TSTRING_END (於 token 模組中)
@anchor{library/token token TSTRING_END}@anchor{4aec}
@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).


在 3.14 版被加入.

@end deffn

@geindex ENDMARKER (於 token 模組中)
@anchor{library/token token ENDMARKER}@anchor{2179}
@deffn {資料} token.ENDMARKER

Token value that indicates the end of input.
Used in @ref{2443,,top-level grammar rules}.
@end deffn

@geindex ENCODING (於 token 模組中)
@anchor{library/token token ENCODING}@anchor{4aed}
@deffn {資料} token.ENCODING

Token value that indicates the encoding used to decode the source bytes
into text. The first token returned by @ref{6f9,,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{101,,tokenize} module.
@end deffn

The following token types are not produced by the @ref{101,,tokenize} module,
and are defined for special uses in the tokenizer or parser:

@geindex TYPE_IGNORE (於 token 模組中)
@anchor{library/token token TYPE_IGNORE}@anchor{4aee}
@deffn {資料} token.TYPE_IGNORE

Token value indicating that a @code{type: ignore} comment was recognized.
Such tokens are produced instead of regular @ref{4ae1,,COMMENT} tokens only
with the @ref{4a94,,PyCF_TYPE_COMMENTS} flag.
@end deffn

@geindex TYPE_COMMENT (於 token 模組中)
@anchor{library/token token TYPE_COMMENT}@anchor{4aef}
@deffn {資料} token.TYPE_COMMENT

Token value indicating that a type comment was recognized.
Such tokens are produced instead of regular @ref{4ae1,,COMMENT} tokens only
with the @ref{4a94,,PyCF_TYPE_COMMENTS} flag.
@end deffn

@geindex SOFT_KEYWORD (於 token 模組中)
@anchor{library/token token SOFT_KEYWORD}@anchor{4adc}
@deffn {資料} token.SOFT_KEYWORD

Token value indicating a @ref{a06,,soft keyword}.

The tokenizer never produces this value.
To check for a soft keyword, pass a @ref{217c,,NAME} token's string to
@ref{4af0,,keyword.issoftkeyword()}.
@end deffn

@geindex ERRORTOKEN (於 token 模組中)
@anchor{library/token token ERRORTOKEN}@anchor{4af1}
@deffn {資料} token.ERRORTOKEN

Token value used to indicate wrong input.

The @ref{101,,tokenize} module generally indicates errors by
raising exceptions instead of emitting this token.
It can also emit tokens such as @ref{214e,,OP} or @ref{217c,,NAME} with strings that
are later rejected by the parser.
@end deffn
@anchor{library/token token-operators-delimiters}@anchor{21d3}
The remaining tokens represent specific @ref{2150,,operators} and
@ref{214f,,delimiters}.
(The @ref{101,,tokenize} module reports these as @ref{214e,,OP}; see @code{exact_type}
in the @ref{101,,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{4af2}
@deffn {資料} token.LPAR
@end deffn

@tab

@code{"("}

@item

@geindex RPAR (於 token 模組中)
@anchor{library/token token RPAR}@anchor{4af3}
@deffn {資料} token.RPAR
@end deffn

@tab

@code{")"}

@item

@geindex LSQB (於 token 模組中)
@anchor{library/token token LSQB}@anchor{4af4}
@deffn {資料} token.LSQB
@end deffn

@tab

@code{"["}

@item

@geindex RSQB (於 token 模組中)
@anchor{library/token token RSQB}@anchor{4af5}
@deffn {資料} token.RSQB
@end deffn

@tab

@code{"]"}

@item

@geindex COLON (於 token 模組中)
@anchor{library/token token COLON}@anchor{4ae8}
@deffn {資料} token.COLON
@end deffn

@tab

@code{":"}

@item

@geindex COMMA (於 token 模組中)
@anchor{library/token token COMMA}@anchor{4af6}
@deffn {資料} token.COMMA
@end deffn

@tab

@code{","}

@item

@geindex SEMI (於 token 模組中)
@anchor{library/token token SEMI}@anchor{4af7}
@deffn {資料} token.SEMI
@end deffn

@tab

@code{";"}

@item

@geindex PLUS (於 token 模組中)
@anchor{library/token token PLUS}@anchor{4adb}
@deffn {資料} token.PLUS
@end deffn

@tab

@code{"+"}

@item

@geindex MINUS (於 token 模組中)
@anchor{library/token token MINUS}@anchor{4af8}
@deffn {資料} token.MINUS
@end deffn

@tab

@code{"-"}

@item

@geindex STAR (於 token 模組中)
@anchor{library/token token STAR}@anchor{4af9}
@deffn {資料} token.STAR
@end deffn

@tab

@code{"*"}

@item

@geindex SLASH (於 token 模組中)
@anchor{library/token token SLASH}@anchor{4afa}
@deffn {資料} token.SLASH
@end deffn

@tab

@code{"/"}

@item

@geindex VBAR (於 token 模組中)
@anchor{library/token token VBAR}@anchor{4afb}
@deffn {資料} token.VBAR
@end deffn

@tab

@code{"|"}

@item

@geindex AMPER (於 token 模組中)
@anchor{library/token token AMPER}@anchor{4afc}
@deffn {資料} token.AMPER
@end deffn

@tab

@code{"&"}

@item

@geindex LESS (於 token 模組中)
@anchor{library/token token LESS}@anchor{4afd}
@deffn {資料} token.LESS
@end deffn

@tab

@code{"<"}

@item

@geindex GREATER (於 token 模組中)
@anchor{library/token token GREATER}@anchor{4afe}
@deffn {資料} token.GREATER
@end deffn

@tab

@code{">"}

@item

@geindex EQUAL (於 token 模組中)
@anchor{library/token token EQUAL}@anchor{4aff}
@deffn {資料} token.EQUAL
@end deffn

@tab

@code{"="}

@item

@geindex DOT (於 token 模組中)
@anchor{library/token token DOT}@anchor{4b00}
@deffn {資料} token.DOT
@end deffn

@tab

@code{"."}

@item

@geindex PERCENT (於 token 模組中)
@anchor{library/token token PERCENT}@anchor{4b01}
@deffn {資料} token.PERCENT
@end deffn

@tab

@code{"%"}

@item

@geindex LBRACE (於 token 模組中)
@anchor{library/token token LBRACE}@anchor{4ae5}
@deffn {資料} token.LBRACE
@end deffn

@tab

@code{"@{"}

@item

@geindex RBRACE (於 token 模組中)
@anchor{library/token token RBRACE}@anchor{4ae6}
@deffn {資料} token.RBRACE
@end deffn

@tab

@code{"@}"}

@item

@geindex EQEQUAL (於 token 模組中)
@anchor{library/token token EQEQUAL}@anchor{4b02}
@deffn {資料} token.EQEQUAL
@end deffn

@tab

@code{"=="}

@item

@geindex NOTEQUAL (於 token 模組中)
@anchor{library/token token NOTEQUAL}@anchor{4b03}
@deffn {資料} token.NOTEQUAL
@end deffn

@tab

@code{"!="}

@item

@geindex LESSEQUAL (於 token 模組中)
@anchor{library/token token LESSEQUAL}@anchor{4b04}
@deffn {資料} token.LESSEQUAL
@end deffn

@tab

@code{"<="}

@item

@geindex GREATEREQUAL (於 token 模組中)
@anchor{library/token token GREATEREQUAL}@anchor{4b05}
@deffn {資料} token.GREATEREQUAL
@end deffn

@tab

@code{">="}

@item

@geindex TILDE (於 token 模組中)
@anchor{library/token token TILDE}@anchor{4b06}
@deffn {資料} token.TILDE
@end deffn

@tab

@code{"~"}

@item

@geindex CIRCUMFLEX (於 token 模組中)
@anchor{library/token token CIRCUMFLEX}@anchor{4b07}
@deffn {資料} token.CIRCUMFLEX
@end deffn

@tab

@code{"^"}

@item

@geindex LEFTSHIFT (於 token 模組中)
@anchor{library/token token LEFTSHIFT}@anchor{4b08}
@deffn {資料} token.LEFTSHIFT
@end deffn

@tab

@code{"<<"}

@item

@geindex RIGHTSHIFT (於 token 模組中)
@anchor{library/token token RIGHTSHIFT}@anchor{4b09}
@deffn {資料} token.RIGHTSHIFT
@end deffn

@tab

@code{">>"}

@item

@geindex DOUBLESTAR (於 token 模組中)
@anchor{library/token token DOUBLESTAR}@anchor{4b0a}
@deffn {資料} token.DOUBLESTAR
@end deffn

@tab

@code{"**"}

@item

@geindex PLUSEQUAL (於 token 模組中)
@anchor{library/token token PLUSEQUAL}@anchor{4b0b}
@deffn {資料} token.PLUSEQUAL
@end deffn

@tab

@code{"+="}

@item

@geindex MINEQUAL (於 token 模組中)
@anchor{library/token token MINEQUAL}@anchor{4b0c}
@deffn {資料} token.MINEQUAL
@end deffn

@tab

@code{"-="}

@item

@geindex STAREQUAL (於 token 模組中)
@anchor{library/token token STAREQUAL}@anchor{4b0d}
@deffn {資料} token.STAREQUAL
@end deffn

@tab

@code{"*="}

@item

@geindex SLASHEQUAL (於 token 模組中)
@anchor{library/token token SLASHEQUAL}@anchor{4b0e}
@deffn {資料} token.SLASHEQUAL
@end deffn

@tab

@code{"/="}

@item

@geindex PERCENTEQUAL (於 token 模組中)
@anchor{library/token token PERCENTEQUAL}@anchor{4b0f}
@deffn {資料} token.PERCENTEQUAL
@end deffn

@tab

@code{"%="}

@item

@geindex AMPEREQUAL (於 token 模組中)
@anchor{library/token token AMPEREQUAL}@anchor{4b10}
@deffn {資料} token.AMPEREQUAL
@end deffn

@tab

@code{"&="}

@item

@geindex VBAREQUAL (於 token 模組中)
@anchor{library/token token VBAREQUAL}@anchor{4b11}
@deffn {資料} token.VBAREQUAL
@end deffn

@tab

@code{"|="}

@item

@geindex CIRCUMFLEXEQUAL (於 token 模組中)
@anchor{library/token token CIRCUMFLEXEQUAL}@anchor{4b12}
@deffn {資料} token.CIRCUMFLEXEQUAL
@end deffn

@tab

@code{"^="}

@item

@geindex LEFTSHIFTEQUAL (於 token 模組中)
@anchor{library/token token LEFTSHIFTEQUAL}@anchor{4b13}
@deffn {資料} token.LEFTSHIFTEQUAL
@end deffn

@tab

@code{"<<="}

@item

@geindex RIGHTSHIFTEQUAL (於 token 模組中)
@anchor{library/token token RIGHTSHIFTEQUAL}@anchor{4b14}
@deffn {資料} token.RIGHTSHIFTEQUAL
@end deffn

@tab

@code{">>="}

@item

@geindex DOUBLESTAREQUAL (於 token 模組中)
@anchor{library/token token DOUBLESTAREQUAL}@anchor{4b15}
@deffn {資料} token.DOUBLESTAREQUAL
@end deffn

@tab

@code{"**="}

@item

@geindex DOUBLESLASH (於 token 模組中)
@anchor{library/token token DOUBLESLASH}@anchor{4b16}
@deffn {資料} token.DOUBLESLASH
@end deffn

@tab

@code{"//"}

@item

@geindex DOUBLESLASHEQUAL (於 token 模組中)
@anchor{library/token token DOUBLESLASHEQUAL}@anchor{4b17}
@deffn {資料} token.DOUBLESLASHEQUAL
@end deffn

@tab

@code{"//="}

@item

@geindex AT (於 token 模組中)
@anchor{library/token token AT}@anchor{4b18}
@deffn {資料} token.AT
@end deffn

@tab

@code{"@@"}

@item

@geindex ATEQUAL (於 token 模組中)
@anchor{library/token token ATEQUAL}@anchor{4b19}
@deffn {資料} token.ATEQUAL
@end deffn

@tab

@code{"@@="}

@item

@geindex RARROW (於 token 模組中)
@anchor{library/token token RARROW}@anchor{4b1a}
@deffn {資料} token.RARROW
@end deffn

@tab

@code{"->"}

@item

@geindex ELLIPSIS (於 token 模組中)
@anchor{library/token token ELLIPSIS}@anchor{4b1b}
@deffn {資料} token.ELLIPSIS
@end deffn

@tab

@code{"..."}

@item

@geindex COLONEQUAL (於 token 模組中)
@anchor{library/token token COLONEQUAL}@anchor{4b1c}
@deffn {資料} token.COLONEQUAL
@end deffn

@tab

@code{":="}

@item

@geindex EXCLAMATION (於 token 模組中)
@anchor{library/token token EXCLAMATION}@anchor{4ae7}
@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{4b1d}
@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{1854}
@deffn {資料} token.EXACT_TOKEN_TYPES

A dictionary mapping the string representation of a token to its numeric code.


在 3.8 版被加入.

@end deffn


在 3.5 版的變更: Added @code{AWAIT} and @code{ASYNC} tokens.



在 3.7 版的變更: Added @ref{4ae1,,COMMENT}, @ref{4ae2,,NL} and @ref{4aed,,ENCODING} tokens.



在 3.7 版的變更: Removed @code{AWAIT} and @code{ASYNC} tokens. "async" and "await" are
now tokenized as @ref{217c,,NAME} tokens.



在 3.8 版的變更: Added @ref{4aef,,TYPE_COMMENT}, @ref{4aee,,TYPE_IGNORE}, @ref{4b1c,,COLONEQUAL}.
Added @code{AWAIT} and @code{ASYNC} tokens back (they're needed
to support parsing older Python versions for @ref{1c2,,ast.parse()} with
@code{feature_version} set to 6 or lower).



在 3.12 版的變更: 新增 @ref{4ae7,,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 --- 檢驗 Python 關鍵字,tokenize --- Tokenizer for Python source,token --- 與 Python 剖析樹一起使用的常數,Python 語言服務
@anchor{library/keyword doc}@anchor{4b1e}@anchor{library/keyword keyword-testing-for-python-keywords}@anchor{4b1f}@anchor{library/keyword module-keyword}@anchor{88}@anchor{library/keyword translation-repo}@anchor{4b20}
@subsection @code{keyword} --- 檢驗 Python 關鍵字


@geindex module; keyword

`原始碼：'Lib/keyword.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/keyword.py}


__________________________________________________________________


此模組允許 Python 程式確定某個字串是否為@ref{214d,,關鍵字} 或@ref{a06,,軟關鍵字 (soft keyword)}。

@geindex iskeyword() (於 keyword 模組中)
@anchor{library/keyword keyword iskeyword}@anchor{24fd}
@deffn {函式} keyword.iskeyword (s)

如果 `s' 是一個 Python @ref{214d,,關鍵字}則回傳 @code{True}。
@end deffn

@geindex kwlist (於 keyword 模組中)
@anchor{library/keyword keyword kwlist}@anchor{4b21}
@deffn {資料} keyword.kwlist

包含直譯器定義的所有 @ref{214d,,關鍵字} 的序列。如果所定義的任何關鍵字僅在特定 @ref{0,,__future__} 陳述式生效時被啟用，它們也將被包含在內。
@end deffn

@geindex issoftkeyword() (於 keyword 模組中)
@anchor{library/keyword keyword issoftkeyword}@anchor{4af0}
@deffn {函式} keyword.issoftkeyword (s)

如果 `s' 是一個 Python @ref{a06,,軟關鍵字} 則回傳 @code{True}。


在 3.9 版被加入.

@end deffn

@geindex softkwlist (於 keyword 模組中)
@anchor{library/keyword keyword softkwlist}@anchor{4b22}
@deffn {資料} keyword.softkwlist

包含直譯器定義的所有 @ref{a06,,軟關鍵字} 的序列。如果所定義的任何軟關鍵字僅在特定 @ref{0,,__future__} 陳述式生效時被啟用，它們也將被包含在內。


在 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 --- 偵測不良縮排,keyword --- 檢驗 Python 關鍵字,Python 語言服務
@anchor{library/tokenize doc}@anchor{4b23}@anchor{library/tokenize module-tokenize}@anchor{101}@anchor{library/tokenize tokenize-tokenizer-for-python-source}@anchor{4b24}@anchor{library/tokenize translation-repo}@anchor{4b25}
@subsection @code{tokenize} --- Tokenizer for Python source


@geindex module; tokenize

`原始碼：'Lib/tokenize.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/tokenize.py}


__________________________________________________________________


The @ref{101,,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{2150,,operator} and
@ref{214f,,delimiter} tokens and @ref{21dd,,Ellipsis} are returned using
the generic @ref{214e,,OP} token type.  The exact
type can be determined by checking the @code{exact_type} property on the
@ref{857,,named tuple} returned from @ref{6f9,,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{1c2,,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:: 
* 命令列用法: 命令列用法<11>. 
* 範例: 範例<49>. 

@end menu

@node Tokenizing Input,命令列用法<11>,,tokenize --- Tokenizer for Python source
@anchor{library/tokenize tokenizing-input}@anchor{4b26}
@subsubsection Tokenizing Input


The primary entry point is a @ref{125c,,generator}:

@geindex tokenize() (於 tokenize 模組中)
@anchor{library/tokenize tokenize tokenize}@anchor{6f9}
@deffn {函式} tokenize.tokenize (readline)

The @ref{6f9,,tokenize()} generator requires one argument, `readline', which
must be a callable object which provides the same interface as the
@ref{152a,,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{857,,named tuple}
with the field names:
@code{type string start end line}.

The returned @ref{857,,named tuple} has an additional property named
@code{exact_type} that contains the exact operator type for
@ref{214e,,OP} tokens.  For all other token types @code{exact_type}
equals the named tuple @code{type} field.


在 3.1 版的變更: 新增附名元組 (named tuple) 的支援。



在 3.3 版的變更: 新增 @code{exact_type} 的支援。


@ref{6f9,,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{6fa}
@deffn {函式} tokenize.generate_tokens (readline)

Tokenize a source reading unicode strings instead of bytes.

Like @ref{6f9,,tokenize()}, the `readline' argument is a callable returning
a single line of input. However, @ref{6fa,,generate_tokens()} expects `readline'
to return a str object rather than bytes.

The result is an iterator yielding named tuples, exactly like
@ref{6f9,,tokenize()}. It does not yield an @ref{4aed,,ENCODING} token.
@end deffn

All constants from the @ref{100,,token} module are also exported from
@ref{101,,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{1829}
@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{4aed,,ENCODING} token, which
is the first token sequence output by @ref{6f9,,tokenize()}. If there is no
encoding token in the input, it returns a str instead.
@end deffn

@ref{6f9,,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{1750}
@deffn {函式} tokenize.detect_encoding (readline)

The @ref{1750,,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{6f9,,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{18e,,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{2b92,,open()} to open Python source files: it uses
@ref{1750,,detect_encoding()} to detect the file encoding.
@end deffn

@geindex open() (於 tokenize 模組中)
@anchor{library/tokenize tokenize open}@anchor{2b92}
@deffn {函式} tokenize.open (filename)

Open a file in read only mode using the encoding detected by
@ref{1750,,detect_encoding()}.


在 3.2 版被加入.

@end deffn

@geindex TokenError
@anchor{library/tokenize tokenize TokenError}@anchor{75d}
@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

或是：

@example
[1,
 2,
 3
@end example
@end deffn

@node 命令列用法<11>,範例<49>,Tokenizing Input,tokenize --- Tokenizer for Python source
@anchor{library/tokenize command-line-usage}@anchor{4b27}@anchor{library/tokenize tokenize-cli}@anchor{4b28}
@subsubsection 命令列用法



在 3.3 版被加入.


The @ref{101,,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

可接受以下選項：

@geindex tokenize 命令列選項; -h
@geindex tokenize 命令列選項; --help
@anchor{library/tokenize cmdoption-tokenize-h}@anchor{4b29}@anchor{library/tokenize cmdoption-tokenize-help}@anchor{4b2a}
@deffn {Option} @w{-}h, @w{-}@w{-}help

show this help message and exit
@end deffn

@geindex tokenize 命令列選項; -e
@geindex tokenize 命令列選項; --exact
@anchor{library/tokenize cmdoption-tokenize-e}@anchor{4b2b}@anchor{library/tokenize cmdoption-tokenize-exact}@anchor{4b2c}
@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.

@node 範例<49>,,命令列用法<11>,tokenize --- Tokenizer for Python source
@anchor{library/tokenize examples}@anchor{4b2d}
@subsubsection 範例


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{4b2b,,-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{6fa,,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{6f9,,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 --- 偵測不良縮排,pyclbr --- Python 模組瀏覽器支援,tokenize --- Tokenizer for Python source,Python 語言服務
@anchor{library/tabnanny doc}@anchor{4b2e}@anchor{library/tabnanny module-tabnanny}@anchor{e3}@anchor{library/tabnanny tabnanny-detection-of-ambiguous-indentation}@anchor{4b2f}@anchor{library/tabnanny translation-repo}@anchor{4b30}
@subsection @code{tabnanny} --- 偵測不良縮排


@geindex module; tabnanny

@c rudimentary documentation based on module comments

`原始碼：'Lib/tabnanny.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/tabnanny.py}


__________________________________________________________________


目前現況是此模組打算以腳本方式被呼叫使用，但也可以將其引入於 IDE 中並使用下方敘述的 @ref{4b31,,check()} 函式。

@cartouche
@quotation 備註 
此模組所提供的 API 很有可能會在未來的發佈版本中有所變更，且有可能不具有向後相容性。
@end quotation
@end cartouche

@geindex check() (於 tabnanny 模組中)
@anchor{library/tabnanny tabnanny check}@anchor{4b31}
@deffn {函式} tabnanny.check (file_or_dir)

如果 `file_or_dir' 是個目錄且並非符號鏈接 (symbolic link)，則會遞迴地在名為 `file_or_dir' 的目錄樹 (directory tree) 中不斷下行檢查所有 @code{.py} 檔案。如果 `file_or_dir' 是個一般 Python 原始檔案，則為其檢查空格相關問題。診斷訊息會以 @ref{1170,,print()} 函式輸出至標準輸出 (standard output) 當中。
@end deffn

@geindex verbose (於 tabnanny 模組中)
@anchor{library/tabnanny tabnanny verbose}@anchor{4b32}
@deffn {資料} tabnanny.verbose

標示是否要印出詳細訊息 (verbose message) 的旗標，若是以腳本方式呼叫的話則可以用 @code{-v} 選項來增加。
@end deffn

@geindex filename_only (於 tabnanny 模組中)
@anchor{library/tabnanny tabnanny filename_only}@anchor{4b33}
@deffn {資料} tabnanny.filename_only

標示是否要只印出那些有空白相關問題檔案之檔名的旗標，若是以腳本方式呼叫的話則可以用 @code{-q} 選項來設為真值。
@end deffn

@geindex NannyNag
@anchor{library/tabnanny tabnanny NannyNag}@anchor{4b34}
@deffn {例外} tabnanny.NannyNag

當偵測到不良縮排時，此例外會被 @ref{4b35,,process_tokens()} 引發，會在 @ref{4b31,,check()} 中捕獲與處理。
@end deffn

@geindex process_tokens() (於 tabnanny 模組中)
@anchor{library/tabnanny tabnanny process_tokens}@anchor{4b35}
@deffn {函式} tabnanny.process_tokens (tokens)

此函式被 @ref{4b31,,check()} 用來處理由 @ref{101,,tokenize} 產生的標記 (token)。
@end deffn

@c XXX document errprint, format_witnesses, Whitespace, check_equal, indents,
@c reset_globals


@subsubheading 也參考



@table @asis

@item @ref{101,,tokenize} 模組

Python 原始程式碼的詞彙掃描器 (lexical scanner)。
@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 模組瀏覽器支援,py_compile — 編譯 Python 來源檔案,tabnanny --- 偵測不良縮排,Python 語言服務
@anchor{library/pyclbr doc}@anchor{4b36}@anchor{library/pyclbr module-pyclbr}@anchor{b9}@anchor{library/pyclbr pyclbr-python-module-browser-support}@anchor{4b37}@anchor{library/pyclbr translation-repo}@anchor{4b38}
@subsection @code{pyclbr} --- Python 模組瀏覽器支援


@geindex module; pyclbr

`原始碼：'Lib/pyclbr.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/pyclbr.py}


__________________________________________________________________


@ref{b9,,pyclbr} 模組可以提供一個使用 Python 編寫的模組中定義的函式、類別和方法的有限資訊。這些資訊足以實作一個模組瀏覽器。這些資訊是從 Python 原始碼中抽取出來的，而不是透過引入模組，因此這個模組可以安全地與不信任的程式碼一起使用。此限制使得此模組無法與非 Python 實作的模組一起使用，包括所有標準與可選的擴充模組。

@geindex readmodule() (於 pyclbr 模組中)
@anchor{library/pyclbr pyclbr readmodule}@anchor{a25}
@deffn {函式} pyclbr.readmodule (module, path=None)

回傳模組層級的類別名稱與類別描述器對應的字典。如果可能的話，會包含引入基底類別的描述器。參數 `module' 是包含要讀取的模組名稱的字串；它可以是套件中的模組名稱。如果給定，`path' 是以 @code{sys.path} 為前綴的目錄路徑序列，用來定位模組原始碼。

此函式為原始介面，僅保留用於向後相容性。它回傳的會是 readmodule_ex 回傳結果的篩選後版本。
@end deffn

@geindex readmodule_ex() (於 pyclbr 模組中)
@anchor{library/pyclbr pyclbr readmodule_ex}@anchor{a26}
@deffn {函式} pyclbr.readmodule_ex (module, path=None)

回傳一個以字典為基礎的樹狀結構，包含在模組中以 @code{def} 或 @code{class} 陳述式定義的每個函式和類別的函式或類別描述器。回傳的字典會將模組層級的函式和類別名稱對映到它們的描述器。巢狀物件會輸入其父物件的子字典。與 readmodule 一樣，`module' 會指定要讀取的模組，而 `path' 則會預先加入 sys.path。如果要讀取的模組是一個套件，回傳的字典有一個 key @code{'__path__'}，其值是一個包含套件搜尋路徑的串列。
@end deffn


在 3.7 版被加入: 巢狀定義（nested definitions）的描述器。這些描述器可透過新的子屬性來存取。每個描述器都有一個新的父屬性。


這些函式所回傳的描述器是 Function 和 Class 類別的實例。使用者不需要建立這些類別的實例。

@menu
* 函式物件:: 
* 類別物件:: 

@end menu

@node 函式物件,類別物件,,pyclbr --- Python 模組瀏覽器支援
@anchor{library/pyclbr function-objects}@anchor{4b39}@anchor{library/pyclbr pyclbr-function-objects}@anchor{4b3a}
@subsubsection 函式物件


@geindex Function (pyclbr 中的類別)
@anchor{library/pyclbr pyclbr Function}@anchor{4b3b}
@deffn {類別} pyclbr.Function

Class @code{Function} 實例描述由 def 陳述式定義的函式。它們具有以下屬性：

@geindex file (pyclbr.Function 的屬性)
@anchor{library/pyclbr pyclbr Function file}@anchor{4b3c}
@deffn {屬性} file

定義函式的檔案名稱。
@end deffn

@geindex module (pyclbr.Function 的屬性)
@anchor{library/pyclbr pyclbr Function module}@anchor{4b3d}
@deffn {屬性} module

定義所述函式的模組名稱。
@end deffn

@geindex name (pyclbr.Function 的屬性)
@anchor{library/pyclbr pyclbr Function name}@anchor{4b3e}
@deffn {屬性} name

函式的名稱。
@end deffn

@geindex lineno (pyclbr.Function 的屬性)
@anchor{library/pyclbr pyclbr Function lineno}@anchor{4b3f}
@deffn {屬性} lineno

檔案中定義開始的行號。
@end deffn

@geindex parent (pyclbr.Function 的屬性)
@anchor{library/pyclbr pyclbr Function parent}@anchor{4b40}
@deffn {屬性} parent

對於頂層函式（top-level functions）為 @code{None}。對於巢狀函式，則使用父函式。


在 3.7 版被加入.

@end deffn

@geindex children (pyclbr.Function 的屬性)
@anchor{library/pyclbr pyclbr Function children}@anchor{4b41}
@deffn {屬性} children

一個 @ref{183,,dictionary} 將名稱對應到巢狀函式和類別的描述器。


在 3.7 版被加入.

@end deffn

@geindex is_async (pyclbr.Function 的屬性)
@anchor{library/pyclbr pyclbr Function is_async}@anchor{4b42}
@deffn {屬性} is_async

對於使用 @ref{7e6,,async} 前綴定義的函式是 @code{True}，否則是 @code{False}。


在 3.10 版被加入.

@end deffn
@end deffn

@node 類別物件,,函式物件,pyclbr --- Python 模組瀏覽器支援
@anchor{library/pyclbr class-objects}@anchor{4b43}@anchor{library/pyclbr pyclbr-class-objects}@anchor{4b44}
@subsubsection 類別物件


@geindex Class (pyclbr 中的類別)
@anchor{library/pyclbr pyclbr Class}@anchor{4b45}
@deffn {類別} pyclbr.Class

Class @code{Class} 實例描述由 class 陳述式定義的類別。它們具有與 @ref{4b3b,,Functions} 相同的屬性，以及另外兩個屬性。

@geindex file (pyclbr.Class 的屬性)
@anchor{library/pyclbr pyclbr Class file}@anchor{4b46}
@deffn {屬性} file

定義類別的檔案名稱。
@end deffn

@geindex module (pyclbr.Class 的屬性)
@anchor{library/pyclbr pyclbr Class module}@anchor{4b47}
@deffn {屬性} module

定義所述類別的模組名稱。
@end deffn

@geindex name (pyclbr.Class 的屬性)
@anchor{library/pyclbr pyclbr Class name}@anchor{4b48}
@deffn {屬性} name

類別的名稱。
@end deffn

@geindex lineno (pyclbr.Class 的屬性)
@anchor{library/pyclbr pyclbr Class lineno}@anchor{4b49}
@deffn {屬性} lineno

檔案中定義開始的行號。
@end deffn

@geindex parent (pyclbr.Class 的屬性)
@anchor{library/pyclbr pyclbr Class parent}@anchor{4b4a}
@deffn {屬性} parent

對於頂層類別為 @code{None}。對於巢狀類別，則使用父類別。


在 3.7 版被加入.

@end deffn

@geindex children (pyclbr.Class 的屬性)
@anchor{library/pyclbr pyclbr Class children}@anchor{4b4b}
@deffn {屬性} children

將名稱對應到巢狀函式和類別的描述器的字典。


在 3.7 版被加入.

@end deffn

@geindex super (pyclbr.Class 的屬性)
@anchor{library/pyclbr pyclbr Class super}@anchor{4b4c}
@deffn {屬性} super

描述被描述類別的直接基底類別的 @code{Class} 物件串列。被命名為超類別（superclasses）但無法被 @ref{a26,,readmodule_ex()} 發現的類別會以類別名稱的字串形式列出，而不是 @code{Class} 物件。
@end deffn

@geindex methods (pyclbr.Class 的屬性)
@anchor{library/pyclbr pyclbr Class methods}@anchor{4b4d}
@deffn {屬性} methods

一個 @ref{183,,dictionary} 方法名稱對應到行號。這可以從較新的 @ref{4b4b,,children} 字典衍生出來，但為了向後相容性而保留。
@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 — 編譯 Python 來源檔案,compileall --- 位元組編譯 Python 函式庫,pyclbr --- Python 模組瀏覽器支援,Python 語言服務
@anchor{library/py_compile doc}@anchor{4b4e}@anchor{library/py_compile module-py_compile}@anchor{b8}@anchor{library/py_compile py-compile-compile-python-source-files}@anchor{4b4f}@anchor{library/py_compile translation-repo}@anchor{4b50}
@subsection @code{py_compile} — 編譯 Python 來源檔案


@geindex module; py_compile

@c documentation based on module docstrings

`原始碼：'Lib/py_compile.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/py_compile.py}

@geindex file（檔案）;byte-code（位元組碼）


__________________________________________________________________


The @ref{b8,,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{4b51}
@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{c11}
@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{4b51,,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{4b51,,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{121b,,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
@ref{4ac,,compile()} function.  The default of @code{-1} selects the optimization
level of the current interpreter.

`invalidation_mode' should be a member of the @ref{4b52,,PycInvalidationMode}
enum and controls how the generated bytecode cache is invalidated at
runtime.  The default is @ref{4b53,,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{4b54,,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{7b,,importlib} for the byte-code cache file writing.
This means file creation/writing semantics now match what @ref{7b,,importlib}
does, e.g. permissions, write-and-move semantics, etc. Also added the
caveat that @ref{121b,,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{4b53,,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 版的變更: 新增 `quiet' 參數。

@end deffn

@geindex PycInvalidationMode (py_compile 中的類別)
@anchor{library/py_compile py_compile PycInvalidationMode}@anchor{4b52}
@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{7fb,,Cached bytecode invalidation} for more information on how Python invalidates
@code{.pyc} files at runtime.


在 3.7 版被加入.


@geindex TIMESTAMP (py_compile.PycInvalidationMode 的屬性)
@anchor{library/py_compile py_compile PycInvalidationMode TIMESTAMP}@anchor{4b54}
@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{4b53}
@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{4b55}
@deffn {屬性} UNCHECKED_HASH

Like @ref{4b53,,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
* 命令列介面: 命令列介面<14>. 

@end menu

@node 命令列介面<14>,,,py_compile — 編譯 Python 來源檔案
@anchor{library/py_compile command-line-interface}@anchor{4b56}@anchor{library/py_compile py-compile-cli}@anchor{4b57}
@subsubsection 命令列介面


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 命令列選項; <file>
@geindex python--m-py_compile 命令列選項; -
@anchor{library/py_compile cmdoption-python-m-py_compile-arg-file}@anchor{4b58}
@deffn {Option} <file> ... <fileN>
@anchor{library/py_compile cmdoption-python-m-py_compile}@anchor{4b59}
@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 命令列選項; -q
@geindex python--m-py_compile 命令列選項; --quiet
@anchor{library/py_compile cmdoption-python-m-py_compile-q}@anchor{4b5a}@anchor{library/py_compile cmdoption-python-m-py_compile-quiet}@anchor{4b5b}
@deffn {Option} @w{-}q, @w{-}@w{-}quiet

Suppress errors output.
@end deffn


在 3.2 版的變更: 新增對 @code{-} 的支援。



在 3.10 版的變更: 新增對 @ref{4b5a,,-q} 的支援。



@subsubheading 也參考



@table @asis

@item @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 --- 位元組編譯 Python 函式庫,dis --- Python bytecode 的反組譯器,py_compile — 編譯 Python 來源檔案,Python 語言服務
@anchor{library/compileall doc}@anchor{4b5c}@anchor{library/compileall compileall-byte-compile-python-libraries}@anchor{4b5d}@anchor{library/compileall module-compileall}@anchor{21}@anchor{library/compileall translation-repo}@anchor{4b5e}
@subsection @code{compileall} --- 位元組編譯 Python 函式庫


@geindex module; compileall

`原始碼：'Lib/compileall.py@footnote{https://github.com/python/cpython/tree/3.14/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{2006,,可用性}: not WASI.

此模組在 WebAssembly 平台上不起作用或無法使用。更多資訊請參閱 @ref{1a99,,WebAssembly 平台}。

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

@end menu

@node Command-line use,Public functions,,compileall --- 位元組編譯 Python 函式庫
@anchor{library/compileall command-line-use}@anchor{4b5f}@anchor{library/compileall compileall-cli}@anchor{4b60}
@subsubsection Command-line use


This module can work as a script (using @code{python -m compileall}) to
compile Python sources.

@geindex compileall 命令列選項; directory
@geindex compileall 命令列選項; file
@anchor{library/compileall cmdoption-compileall-arg-directory}@anchor{4b61}
@deffn {Option} directory ...
@anchor{library/compileall cmdoption-compileall-arg-file}@anchor{4b62}
@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 命令列選項; -l
@anchor{library/compileall cmdoption-compileall-l}@anchor{4b63}
@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 命令列選項; -f
@anchor{library/compileall cmdoption-compileall-f}@anchor{4b64}
@deffn {Option} @w{-}f

Force rebuild even if timestamps are up-to-date.
@end deffn

@geindex compileall 命令列選項; -q
@anchor{library/compileall cmdoption-compileall-q}@anchor{4b65}
@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 命令列選項; -d
@anchor{library/compileall cmdoption-compileall-d}@anchor{4b66}
@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 命令列選項; -s
@anchor{library/compileall cmdoption-compileall-s}@anchor{4b67}
@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 命令列選項; -p
@anchor{library/compileall cmdoption-compileall-p}@anchor{4b68}
@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 命令列選項; -x
@anchor{library/compileall cmdoption-compileall-x}@anchor{4b69}
@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 命令列選項; -i
@anchor{library/compileall cmdoption-compileall-i}@anchor{4b6a}
@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 命令列選項; -b
@anchor{library/compileall cmdoption-compileall-b}@anchor{4b6b}
@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 命令列選項; -r
@anchor{library/compileall cmdoption-compileall-r}@anchor{4b6c}
@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 命令列選項; -j
@anchor{library/compileall cmdoption-compileall-j}@anchor{4b6d}
@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{4d5,,os.process_cpu_count()}
will be used.
@end deffn

@geindex compileall 命令列選項; --invalidation-mode
@anchor{library/compileall cmdoption-compileall-invalidation-mode}@anchor{4b6e}
@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{7fb,,Cached bytecode invalidation} 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 命令列選項; -o
@anchor{library/compileall cmdoption-compileall-o}@anchor{4b6f}
@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 命令列選項; -e
@anchor{library/compileall cmdoption-compileall-e}@anchor{4b70}
@deffn {Option} @w{-}e dir

Ignore symlinks pointing outside the given directory.
@end deffn

@geindex compileall 命令列選項; --hardlink-dupes
@anchor{library/compileall cmdoption-compileall-hardlink-dupes}@anchor{4b71}
@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 版的變更: 新增選項 @code{-i}、@code{-b} 與 @code{-h}。



在 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 版的變更: 新增選項 @code{--invalidation-mode}。



在 3.9 版的變更: Added the @code{-s}, @code{-p}, @code{-e} and @code{--hardlink-dupes} options.
Raised the default recursion limit from 10 to
@ref{6e4,,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{4ac,,compile()} function, because the Python interpreter itself already
provides the option: @code{python -O -m compileall}.

Similarly, the @ref{4ac,,compile()} function respects the @ref{b93,,sys.pycache_prefix}
setting. The generated bytecode cache will only be useful if @ref{4ac,,compile()} is
run with the same @ref{b93,,sys.pycache_prefix} (if any) that will be used at
runtime.

@node Public functions,,Command-line use,compileall --- 位元組編譯 Python 函式庫
@anchor{library/compileall public-functions}@anchor{4b72}
@subsubsection Public functions


@geindex compile_dir() (於 compileall 模組中)
@anchor{library/compileall compileall compile_dir}@anchor{d13}
@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{1182,,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{4ac,,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{2eb,,ValueError} will be raised.

`invalidation_mode' should be a member of the
@ref{4b52,,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{e46,,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 版的變更: 新增 `legacy' 與 `optimize' 參數。



在 3.5 版的變更: 新增 `workers' 參數。



在 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{59b,,path-like object}.



在 3.7 版的變更: 新增 `invalidation_mode' 參數。



在 3.7.2 版的變更: 新增 `invalidation_mode' 參數的預設值被更新為 @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{fdc}
@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{1182,,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{4ac,,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{4b52,,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{e46,,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 版被加入.



在 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 版的變更: 新增 `invalidation_mode' 參數。



在 3.7.2 版的變更: 新增 `invalidation_mode' 參數的預設值被更新為 @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{fdd}
@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{d13,,compile_dir()}
function.  Note that unlike the other compile functions, @code{maxlevels}
defaults to @code{0}.


在 3.2 版的變更: 新增 `legacy' 與 `optimize' 參數。



在 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 版的變更: 新增 `invalidation_mode' 參數。



在 3.7.2 版的變更: 新增 `invalidation_mode' 參數的預設值被更新為 @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 @ref{b8,,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 --- Python bytecode 的反組譯器,pickletools --- pickle 開發者的工具,compileall --- 位元組編譯 Python 函式庫,Python 語言服務
@anchor{library/dis doc}@anchor{4b73}@anchor{library/dis dis-disassembler-for-python-bytecode}@anchor{4b74}@anchor{library/dis module-dis}@anchor{3c}@anchor{library/dis translation-repo}@anchor{4b75}
@subsection @code{dis} --- Python bytecode 的反組譯器


@geindex module; dis

`原始碼：'Lib/dis.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/dis.py}

@c import dis
@c def myfunc(alist):
@c     return len(alist)


__________________________________________________________________


@ref{3c,,dis} 模組支援反組譯分析 CPython @ref{4a5,,bytecode}。CPython bytecode 作為輸入的模組被定義於 @code{Include/opcode.h} 並且被編譯器和直譯器所使用。

`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{900,,CACHE} instructions. These instructions
are hidden by default, but can be shown by passing @code{show_caches=True} to
any @ref{3c,,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{900,,CACHE} entries.

As a consequence, the presence of the @ref{900,,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{208,,-P} command-line option
and the @code{show_positions} argument were added.

The @ref{209,,-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
* 命令列介面: 命令列介面<15>. 
* Bytecode analysis:: 
* 分析函式:: 
* Python 位元組碼指令:: 
* Opcode collections:: 

@end menu

@node 命令列介面<15>,Bytecode analysis,,dis --- Python bytecode 的反組譯器
@anchor{library/dis command-line-interface}@anchor{4b76}@anchor{library/dis dis-cli}@anchor{4b77}
@subsubsection 命令列介面


The @ref{3c,,dis} module can be invoked as a script from the command line:

@example
python -m dis [-h] [-C] [-O] [-P] [-S] [infile]
@end example

可接受以下選項：

@geindex dis 命令列選項; -h
@geindex dis 命令列選項; --help
@anchor{library/dis cmdoption-dis-h}@anchor{4b78}@anchor{library/dis cmdoption-dis-help}@anchor{4b79}
@deffn {Option} @w{-}h, @w{-}@w{-}help

Display usage and exit.
@end deffn

@geindex dis 命令列選項; -C
@geindex dis 命令列選項; --show-caches
@anchor{library/dis cmdoption-dis-C}@anchor{4b7a}@anchor{library/dis cmdoption-dis-show-caches}@anchor{4b7b}
@deffn {Option} @w{-}C, @w{-}@w{-}show@w{-}caches

Show inline caches.


在 3.13 版被加入.

@end deffn

@geindex dis 命令列選項; -O
@geindex dis 命令列選項; --show-offsets
@anchor{library/dis cmdoption-dis-O}@anchor{4e6}@anchor{library/dis cmdoption-dis-show-offsets}@anchor{4b7c}
@deffn {Option} @w{-}O, @w{-}@w{-}show@w{-}offsets

Show offsets of instructions.


在 3.13 版被加入.

@end deffn

@geindex dis 命令列選項; -P
@geindex dis 命令列選項; --show-positions
@anchor{library/dis cmdoption-dis-P}@anchor{208}@anchor{library/dis cmdoption-dis-show-positions}@anchor{4b7d}
@deffn {Option} @w{-}P, @w{-}@w{-}show@w{-}positions

Show positions of instructions in the source code.


在 3.14 版被加入.

@end deffn

@geindex dis 命令列選項; -S
@geindex dis 命令列選項; --specialized
@anchor{library/dis cmdoption-dis-S}@anchor{209}@anchor{library/dis cmdoption-dis-specialized}@anchor{4b7e}
@deffn {Option} @w{-}S, @w{-}@w{-}specialized

Show specialized bytecode.


在 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,分析函式,命令列介面<15>,dis --- Python bytecode 的反組譯器
@anchor{library/dis bytecode-analysis}@anchor{4b7f}
@subsubsection Bytecode analysis



在 3.4 版被加入.


The bytecode analysis API allows pieces of Python code to be wrapped in a
@ref{204,,Bytecode} object that provides easy access to details of the compiled
code.

@geindex Bytecode (dis 中的類別)
@anchor{library/dis dis Bytecode}@anchor{204}
@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{4ac,,compile()}).

This is a convenience wrapper around many of the functions listed below, most
notably @ref{4e7,,get_instructions()}, as iterating over a @ref{204,,Bytecode}
instance yields the bytecode operations as @ref{203,,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{112a,,dis()} will display a "current
instruction" marker against the specified opcode.

If `show_caches' is @code{True}, @ref{112a,,dis()} will display inline cache
entries used by the interpreter to specialize the bytecode.

If `adaptive' is @code{True}, @ref{112a,,dis()} will display specialized bytecode
that may be different from the original bytecode.

If `show_offsets' is @code{True}, @ref{112a,,dis()} will include instruction
offsets in the output.

If `show_positions' is @code{True}, @ref{112a,,dis()} will include instruction
source code positions in the output.

@geindex from_traceback() (dis.Bytecode 的類別方法)
@anchor{library/dis dis Bytecode from_traceback}@anchor{112b}
@deffn {方法} classmethod from_traceback (tb, *, show_caches=False)

Construct a @ref{204,,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{4b80}
@deffn {資料} codeobj

The compiled code object.
@end deffn

@geindex Bytecode.first_line (於 dis 模組中)
@anchor{library/dis dis Bytecode first_line}@anchor{4b81}
@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{112a}
@deffn {方法} dis ()

Return a formatted view of the bytecode operations (the same as printed by
@ref{205,,dis.dis()}, but returned as a multi-line string).
@end deffn

@geindex info() (dis.Bytecode 的方法)
@anchor{library/dis dis Bytecode info}@anchor{4b82}
@deffn {方法} info ()

Return a formatted multi-line string with detailed information about the
code object, like @ref{143a,,code_info()}.
@end deffn


在 3.7 版的變更: This can now handle coroutine and asynchronous generator objects.



在 3.11 版的變更: 新增 `show_caches' 與 `adaptive' 參數。



在 3.13 版的變更: 新增 `show_offsets' 參數。



在 3.14 版的變更: 新增 `show_positions' 參數。

@end deffn

範例：

@example
>>> bytecode = dis.Bytecode(myfunc)
>>> for instr in bytecode:
...     print(instr.opname)
...
RESUME
LOAD_GLOBAL
LOAD_FAST_BORROW
CALL
RETURN_VALUE
@end example

@node 分析函式,Python 位元組碼指令,Bytecode analysis,dis --- Python bytecode 的反組譯器
@anchor{library/dis analysis-functions}@anchor{4b83}
@subsubsection 分析函式


The @ref{3c,,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{143a}
@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.


在 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{1129}
@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.


在 3.2 版被加入.



在 3.4 版的變更: 新增 `file' 參數。

@end deffn

@geindex dis() (於 dis 模組中)
@anchor{library/dis dis dis}@anchor{205}
@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{4a6,,annotation scopes}.
Strings are first compiled to code objects with the @ref{4ac,,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 版的變更: 新增 `file' 參數。



在 3.7 版的變更: Implemented recursive disassembling and added `depth' parameter.



在 3.7 版的變更: This can now handle coroutine and asynchronous generator objects.



在 3.11 版的變更: 新增 `show_caches' 與 `adaptive' 參數。



在 3.13 版的變更: 新增 `show_offsets' 參數。



在 3.14 版的變更: 新增 `show_positions' 參數。

@end deffn

@geindex distb() (於 dis 模組中)
@anchor{library/dis dis distb}@anchor{206}
@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 版的變更: 新增 `file' 參數。



在 3.11 版的變更: 新增 `show_caches' 與 `adaptive' 參數。



在 3.13 版的變更: 新增 `show_offsets' 參數。



在 3.14 版的變更: 新增 `show_positions' 參數。

@end deffn

@geindex disassemble() (於 dis 模組中)
@geindex disco() (於 dis 模組中)
@anchor{library/dis dis disassemble}@anchor{207}
@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{4b84}
@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 版的變更: 新增 `file' 參數。



在 3.11 版的變更: 新增 `show_caches' 與 `adaptive' 參數。



在 3.13 版的變更: 新增 `show_offsets' 參數。



在 3.14 版的變更: 新增 `show_positions' 參數。

@end deffn

@geindex get_instructions() (於 dis 模組中)
@anchor{library/dis dis get_instructions}@anchor{4e7}
@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{203,,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{3c,,dis()}.


在 3.4 版被加入.



在 3.11 版的變更: 新增 `show_caches' 與 `adaptive' 參數。



在 3.13 版的變更: The `show_caches' parameter is deprecated and has no effect. The iterator
generates the @ref{203,,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{4b85}
@deffn {函式} dis.findlinestarts (code)

This generator function uses the @ref{34e,,co_lines()} method
of the @ref{4e1,,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{34e,,co_lines()} method is used instead of the
@ref{2241,,co_firstlineno} and @ref{32f,,co_lnotab}
attributes of the @ref{4e1,,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{4b86}
@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{112c}
@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}, @ref{112c,,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.


在 3.4 版被加入.



在 3.8 版的變更: 新增 `jump' 參數。



在 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 位元組碼指令,Opcode collections,分析函式,dis --- Python bytecode 的反組譯器
@anchor{library/dis bytecodes}@anchor{7c8}@anchor{library/dis python-bytecode-instructions}@anchor{4b87}
@subsubsection Python 位元組碼指令


The @ref{4e7,,get_instructions()} function and @ref{204,,Bytecode} class provide
details of bytecode instructions as @ref{203,,Instruction} instances:

@geindex Instruction (dis 中的類別)
@anchor{library/dis dis Instruction}@anchor{203}
@deffn {類別} dis.Instruction

位元組碼操作的詳細資訊

@geindex Instruction.opcode (於 dis 模組中)
@anchor{library/dis dis Instruction opcode}@anchor{4b88}
@deffn {資料} opcode

numeric code for operation, corresponding to the opcode values listed
below and the bytecode values in the @ref{4b89,,Opcode collections}.
@end deffn

@geindex Instruction.opname (於 dis 模組中)
@anchor{library/dis dis Instruction opname}@anchor{4b8a}
@deffn {資料} opname

操作的可讀名稱
@end deffn

@geindex Instruction.baseopcode (於 dis 模組中)
@anchor{library/dis dis Instruction baseopcode}@anchor{4b8b}
@deffn {資料} baseopcode

numeric code for the base operation if operation is specialized;
otherwise equal to @ref{4b88,,opcode}
@end deffn

@geindex Instruction.baseopname (於 dis 模組中)
@anchor{library/dis dis Instruction baseopname}@anchor{4b8c}
@deffn {資料} baseopname

human readable name for the base operation if operation is specialized;
otherwise equal to @ref{4b8d,,opname}
@end deffn

@geindex Instruction.arg (於 dis 模組中)
@anchor{library/dis dis Instruction arg}@anchor{4b8e}
@deffn {資料} arg

numeric argument to operation (if any), otherwise @code{None}
@end deffn

@geindex Instruction.oparg (於 dis 模組中)
@anchor{library/dis dis Instruction oparg}@anchor{4b8f}
@deffn {資料} oparg

@ref{4b8e,,arg} 的別名。
@end deffn

@geindex Instruction.argval (於 dis 模組中)
@anchor{library/dis dis Instruction argval}@anchor{4b90}
@deffn {資料} argval

resolved arg value (if any), otherwise @code{None}
@end deffn

@geindex Instruction.argrepr (於 dis 模組中)
@anchor{library/dis dis Instruction argrepr}@anchor{4b91}
@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{4b92}
@deffn {資料} offset

start index of operation within bytecode sequence
@end deffn

@geindex Instruction.start_offset (於 dis 模組中)
@anchor{library/dis dis Instruction start_offset}@anchor{4b93}
@deffn {資料} start_offset

start index of operation within bytecode sequence, including prefixed
@code{EXTENDED_ARG} operations if present; otherwise equal to @ref{4b92,,offset}
@end deffn

@geindex Instruction.cache_offset (於 dis 模組中)
@anchor{library/dis dis Instruction cache_offset}@anchor{4b94}
@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{4b95}
@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{4b96}
@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{4b97}
@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{4b98}
@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{4b99}
@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{4b9a}
@deffn {資料} positions

@ref{18a6,,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{4b9b}
@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


在 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{18a6}
@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{4b9c}
@deffn {資料} lineno
@end deffn

@geindex Positions.end_lineno (於 dis 模組中)
@anchor{library/dis dis Positions end_lineno}@anchor{4b9d}
@deffn {資料} end_lineno
@end deffn

@geindex Positions.col_offset (於 dis 模組中)
@anchor{library/dis dis Positions col_offset}@anchor{4b9e}
@deffn {資料} col_offset
@end deffn

@geindex Positions.end_col_offset (於 dis 模組中)
@anchor{library/dis dis Positions end_col_offset}@anchor{4b9f}
@deffn {資料} end_col_offset
@end deffn


在 3.11 版被加入.

@end deffn

The Python compiler currently generates the following bytecode 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{4ba0}
@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{374}
@deffn {Opcode} NOT_TAKEN

Do nothing code.
Used by the interpreter to record @ref{295,,BRANCH_LEFT}
and @ref{296,,BRANCH_RIGHT} events for @ref{e0,,sys.monitoring}.


在 3.14 版被加入.

@end deffn

@geindex POP_ITER (opcode)
@anchor{library/dis opcode-POP_ITER}@anchor{36e}
@deffn {Opcode} POP_ITER

Removes the iterator from the top of the stack.


在 3.14 版被加入.

@end deffn

@geindex POP_TOP (opcode)
@anchor{library/dis opcode-POP_TOP}@anchor{4ba1}
@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{4ba2}
@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.


在 3.12 版被加入.

@end deffn

@geindex END_SEND (opcode)
@anchor{library/dis opcode-END_SEND}@anchor{4ba3}
@deffn {Opcode} END_SEND

Implements @code{del STACK[-2]}.
Used to clean up when a generator exits.


在 3.12 版被加入.

@end deffn

@geindex COPY (opcode)
@anchor{library/dis opcode-COPY}@anchor{90f}
@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


在 3.11 版被加入.

@end deffn

@geindex SWAP (opcode)
@anchor{library/dis opcode-SWAP}@anchor{910}
@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


在 3.11 版被加入.

@end deffn

@geindex CACHE (opcode)
@anchor{library/dis opcode-CACHE}@anchor{900}
@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.


在 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{4ba4}
@deffn {Opcode} UNARY_NEGATIVE

實作 @code{STACK[-1] = -STACK[-1]}。
@end deffn

@geindex UNARY_NOT (opcode)
@anchor{library/dis opcode-UNARY_NOT}@anchor{19b2}
@deffn {Opcode} UNARY_NOT

實作 @code{STACK[-1] = not STACK[-1]}。


在 3.13 版的變更: This instruction now requires an exact @ref{3c1,,bool} operand.

@end deffn

@geindex UNARY_INVERT (opcode)
@anchor{library/dis opcode-UNARY_INVERT}@anchor{4ba5}
@deffn {Opcode} UNARY_INVERT

實作 @code{STACK[-1] = ~STACK[-1]}。
@end deffn

@geindex GET_ITER (opcode)
@anchor{library/dis opcode-GET_ITER}@anchor{4ba6}
@deffn {Opcode} GET_ITER

實作 @code{STACK[-1] = iter(STACK[-1])}。
@end deffn

@geindex GET_YIELD_FROM_ITER (opcode)
@anchor{library/dis opcode-GET_YIELD_FROM_ITER}@anchor{4ba7}
@deffn {Opcode} GET_YIELD_FROM_ITER

If @code{STACK[-1]} is a @ref{dd4,,generator iterator} or @ref{6b2,,coroutine} object
it is left as is.  Otherwise, implements @code{STACK[-1] = iter(STACK[-1])}.


在 3.5 版被加入.

@end deffn

@geindex TO_BOOL (opcode)
@anchor{library/dis opcode-TO_BOOL}@anchor{19af}
@deffn {Opcode} TO_BOOL

Implements @code{STACK[-1] = bool(STACK[-1])}.


在 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{364}
@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


在 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{1ad0}
@deffn {Opcode} STORE_SUBSCR

實作了：

@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{4ba8}
@deffn {Opcode} DELETE_SUBSCR

實作了：

@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{6fe}
@deffn {Opcode} BINARY_SLICE

實作了：

@example
end = STACK.pop()
start = STACK.pop()
container = STACK.pop()
STACK.append(container[start:end])
@end example


在 3.12 版被加入.

@end deffn

@geindex STORE_SLICE (opcode)
@anchor{library/dis opcode-STORE_SLICE}@anchor{6ff}
@deffn {Opcode} STORE_SLICE

實作了：

@example
end = STACK.pop()
start = STACK.pop()
container = STACK.pop()
values = STACK.pop()
container[start:end] = value
@end example


在 3.12 版被加入.

@end deffn

`Coroutine opcodes'

@geindex GET_AWAITABLE (opcode)
@anchor{library/dis opcode-GET_AWAITABLE}@anchor{1aed}
@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{4911,,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


在 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{4ba9}
@deffn {Opcode} GET_AITER

Implements @code{STACK[-1] = STACK[-1].__aiter__()}.


在 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{4baa}
@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}.


在 3.5 版被加入.

@end deffn

@geindex END_ASYNC_FOR (opcode)
@anchor{library/dis opcode-END_ASYNC_FOR}@anchor{c97}
@deffn {Opcode} END_ASYNC_FOR

Terminates an @ref{c98,,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{1cd7,,StopAsyncIteration}, it is re-raised.


在 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{702}
@deffn {Opcode} CLEANUP_THROW

Handles an exception raised during a @ref{715,,throw()} or
@ref{19b7,,close()} call through the current frame.  If @code{STACK[-1]} is an
instance of @ref{df0,,StopIteration}, pop three values from the stack and push
its @code{value} member.  Otherwise, re-raise @code{STACK[-1]}.


在 3.12 版被加入.

@end deffn

`Miscellaneous opcodes'

@geindex SET_ADD (opcode)
@anchor{library/dis opcode-SET_ADD}@anchor{4bab}
@deffn {Opcode} SET_ADD (i)

實作了：

@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{4bac}
@deffn {Opcode} LIST_APPEND (i)

實作了：

@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{c99}
@deffn {Opcode} MAP_ADD (i)

實作了：

@example
value = STACK.pop()
key = STACK.pop()
dict.__setitem__(STACK[-i], key, value)
@end example

Used to implement dict comprehensions.


在 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{4bab,,SET_ADD}, @ref{4bac,,LIST_APPEND} and @ref{c99,,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{1a63}
@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{5b2}
@deffn {Opcode} YIELD_VALUE

Yields @code{STACK.pop()} from a @ref{125c,,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{f4b}
@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{f4c,,variable annotations}
statically.


在 3.6 版被加入.

@end deffn

@geindex POP_EXCEPT (opcode)
@anchor{library/dis opcode-POP_EXCEPT}@anchor{4bad}
@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{4bae}
@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{a7f,,f_lasti} of the current frame.


在 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{90a}
@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.


在 3.11 版被加入.

@end deffn

@geindex CHECK_EXC_MATCH (opcode)
@anchor{library/dis opcode-CHECK_EXC_MATCH}@anchor{911}
@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.


在 3.11 版被加入.

@end deffn

@geindex CHECK_EG_MATCH (opcode)
@anchor{library/dis opcode-CHECK_EG_MATCH}@anchor{909}
@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}.


在 3.11 版被加入.

@end deffn

@geindex WITH_EXCEPT_START (opcode)
@anchor{library/dis opcode-WITH_EXCEPT_START}@anchor{4baf}
@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{186,,with} statement.


在 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{368}
@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{b57,,assert}
statement to load @ref{8b0,,AssertionError}.


在 3.14 版被加入.

@end deffn

@geindex LOAD_BUILD_CLASS (opcode)
@anchor{library/dis opcode-LOAD_BUILD_CLASS}@anchor{4bb0}
@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{4bb1}
@deffn {Opcode} GET_LEN

Perform @code{STACK.append(len(STACK[-1]))}. Used in @ref{a07,,match} statements where
comparison with structure of pattern is needed.


在 3.10 版被加入.

@end deffn

@geindex MATCH_MAPPING (opcode)
@anchor{library/dis opcode-MATCH_MAPPING}@anchor{4bb2}
@deffn {Opcode} MATCH_MAPPING

If @code{STACK[-1]} is an instance of @ref{abe,,collections.abc.Mapping} (or, more
technically: if it has the @ref{1b5a,,Py_TPFLAGS_MAPPING} flag set in its
@ref{1b73,,tp_flags}), push @code{True} onto the stack.  Otherwise,
push @code{False}.


在 3.10 版被加入.

@end deffn

@geindex MATCH_SEQUENCE (opcode)
@anchor{library/dis opcode-MATCH_SEQUENCE}@anchor{4bb3}
@deffn {Opcode} MATCH_SEQUENCE

If @code{STACK[-1]} is an instance of @ref{13c5,,collections.abc.Sequence} and is `not' an instance
of @ref{169,,str}/@ref{192,,bytes}/@ref{343,,bytearray} (or, more technically: if it has
the @ref{1b5b,,Py_TPFLAGS_SEQUENCE} flag set in its @ref{1b73,,tp_flags}),
push @code{True} onto the stack.  Otherwise, push @code{False}.


在 3.10 版被加入.

@end deffn

@geindex MATCH_KEYS (opcode)
@anchor{library/dis opcode-MATCH_KEYS}@anchor{918}
@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{60c,,tuple}
containing the corresponding values. Otherwise, push @code{None}.


在 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{4bb4}
@deffn {Opcode} STORE_NAME (namei)

Implements @code{name = STACK.pop()}. `namei' is the index of `name' in the attribute
@ref{2240,,co_names} of the @ref{4e1,,code object}.
The compiler tries to use @ref{19b4,,STORE_FAST} or @ref{4bb5,,STORE_GLOBAL} if possible.
@end deffn

@geindex DELETE_NAME (opcode)
@anchor{library/dis opcode-DELETE_NAME}@anchor{4bb6}
@deffn {Opcode} DELETE_NAME (namei)

Implements @code{del name}, where `namei' is the index into @ref{2240,,co_names}
attribute of the @ref{4e1,,code object}.
@end deffn

@geindex UNPACK_SEQUENCE (opcode)
@anchor{library/dis opcode-UNPACK_SEQUENCE}@anchor{1aef}
@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{4bb7}
@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{1aee}
@deffn {Opcode} STORE_ATTR (namei)

實作了：

@example
obj = STACK.pop()
value = STACK.pop()
obj.name = value
@end example

where `namei' is the index of name in @ref{2240,,co_names} of the
@ref{4e1,,code object}.
@end deffn

@geindex DELETE_ATTR (opcode)
@anchor{library/dis opcode-DELETE_ATTR}@anchor{4bb8}
@deffn {Opcode} DELETE_ATTR (namei)

實作了：

@example
obj = STACK.pop()
del obj.name
@end example

where `namei' is the index of name into @ref{2240,,co_names} of the
@ref{4e1,,code object}.
@end deffn

@geindex STORE_GLOBAL (opcode)
@anchor{library/dis opcode-STORE_GLOBAL}@anchor{4bb5}
@deffn {Opcode} STORE_GLOBAL (namei)

Works as @ref{4bb4,,STORE_NAME}, but stores the name as a global.
@end deffn

@geindex DELETE_GLOBAL (opcode)
@anchor{library/dis opcode-DELETE_GLOBAL}@anchor{4bb9}
@deffn {Opcode} DELETE_GLOBAL (namei)

Works as @ref{4bb6,,DELETE_NAME}, but deletes a global name.
@end deffn

@geindex LOAD_CONST (opcode)
@anchor{library/dis opcode-LOAD_CONST}@anchor{4bba}
@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{36c}
@deffn {Opcode} LOAD_SMALL_INT (i)

Pushes the integer @code{i} onto the stack.
@code{i} must be in @code{range(256)}


在 3.14 版被加入.

@end deffn

@geindex LOAD_NAME (opcode)
@anchor{library/dis opcode-LOAD_NAME}@anchor{4bbb}
@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{707}
@deffn {Opcode} LOAD_LOCALS

Pushes a reference to the locals dictionary onto the stack.  This is used
to prepare namespace dictionaries for @ref{705,,LOAD_FROM_DICT_OR_DEREF}
and @ref{706,,LOAD_FROM_DICT_OR_GLOBALS}.


在 3.12 版被加入.

@end deffn

@geindex LOAD_FROM_DICT_OR_GLOBALS (opcode)
@anchor{library/dis opcode-LOAD_FROM_DICT_OR_GLOBALS}@anchor{706}
@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{19ab,,LOAD_GLOBAL}.
This is used for loading global variables in
@ref{4a6,,annotation scopes} within class bodies.


在 3.12 版被加入.

@end deffn

@geindex BUILD_TEMPLATE (opcode)
@anchor{library/dis opcode-BUILD_TEMPLATE}@anchor{366}
@deffn {Opcode} BUILD_TEMPLATE

Constructs a new @ref{16a,,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


在 3.14 版被加入.

@end deffn

@geindex BUILD_INTERPOLATION (opcode)
@anchor{library/dis opcode-BUILD_INTERPOLATION}@anchor{365}
@deffn {Opcode} BUILD_INTERPOLATION (format)

Constructs a new @ref{16b,,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


在 3.14 版被加入.

@end deffn

@geindex BUILD_TUPLE (opcode)
@anchor{library/dis opcode-BUILD_TUPLE}@anchor{4bbc}
@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{4bbd}
@deffn {Opcode} BUILD_LIST (count)

Works as @ref{4bbc,,BUILD_TUPLE}, but creates a list.
@end deffn

@geindex BUILD_SET (opcode)
@anchor{library/dis opcode-BUILD_SET}@anchor{4bbe}
@deffn {Opcode} BUILD_SET (count)

Works as @ref{4bbc,,BUILD_TUPLE}, but creates a set.
@end deffn

@geindex BUILD_MAP (opcode)
@anchor{library/dis opcode-BUILD_MAP}@anchor{367}
@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{f48}
@deffn {Opcode} BUILD_STRING (count)

Concatenates `count' strings from the stack and pushes the resulting string
onto the stack.


在 3.6 版被加入.

@end deffn

@geindex LIST_EXTEND (opcode)
@anchor{library/dis opcode-LIST_EXTEND}@anchor{4bbf}
@deffn {Opcode} LIST_EXTEND (i)

實作了：

@example
seq = STACK.pop()
list.extend(STACK[-i], seq)
@end example

Used to build lists.


在 3.9 版被加入.

@end deffn

@geindex SET_UPDATE (opcode)
@anchor{library/dis opcode-SET_UPDATE}@anchor{4bc0}
@deffn {Opcode} SET_UPDATE (i)

實作了：

@example
seq = STACK.pop()
set.update(STACK[-i], seq)
@end example

Used to build sets.


在 3.9 版被加入.

@end deffn

@geindex DICT_UPDATE (opcode)
@anchor{library/dis opcode-DICT_UPDATE}@anchor{4bc1}
@deffn {Opcode} DICT_UPDATE (i)

實作了：

@example
map = STACK.pop()
dict.update(STACK[-i], map)
@end example

Used to build dicts.


在 3.9 版被加入.

@end deffn

@geindex DICT_MERGE (opcode)
@anchor{library/dis opcode-DICT_MERGE}@anchor{4bc2}
@deffn {Opcode} DICT_MERGE (i)

Like @ref{4bc1,,DICT_UPDATE} but raises an exception for duplicate keys.


在 3.9 版被加入.

@end deffn

@geindex LOAD_ATTR (opcode)
@anchor{library/dis opcode-LOAD_ATTR}@anchor{6fd}
@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{90d,,CALL}
or @ref{370,,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{6fb}
@deffn {Opcode} LOAD_SUPER_ATTR (namei)

This opcode implements @ref{1a6,,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{6fd,,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{6fd,,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{1a6,,super()} (unset means zero-argument).


在 3.12 版被加入.

@end deffn

@geindex COMPARE_OP (opcode)
@anchor{library/dis opcode-COMPARE_OP}@anchor{b58}
@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{3c1,,bool}.

@end deffn

@geindex IS_OP (opcode)
@anchor{library/dis opcode-IS_OP}@anchor{18a2}
@deffn {Opcode} IS_OP (invert)

Performs @code{is} comparison, or @code{is not} if @code{invert} is 1.


在 3.9 版被加入.

@end deffn

@geindex CONTAINS_OP (opcode)
@anchor{library/dis opcode-CONTAINS_OP}@anchor{18a1}
@deffn {Opcode} CONTAINS_OP (invert)

Performs @code{in} comparison, or @code{not in} if @code{invert} is 1.


在 3.9 版被加入.

@end deffn

@geindex IMPORT_NAME (opcode)
@anchor{library/dis opcode-IMPORT_NAME}@anchor{4bc3}
@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{ac8,,__import__()}.
The module object is pushed onto the stack.  The current namespace is not affected: for a proper import statement, a subsequent @ref{19b4,,STORE_FAST} instruction
modifies the namespace.
@end deffn

@geindex IMPORT_FROM (opcode)
@anchor{library/dis opcode-IMPORT_FROM}@anchor{4bc4}
@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{19b4,,STORE_FAST} instruction.
@end deffn

@geindex JUMP_FORWARD (opcode)
@anchor{library/dis opcode-JUMP_FORWARD}@anchor{18d5}
@deffn {Opcode} JUMP_FORWARD (delta)

Increments bytecode counter by `delta'.
@end deffn

@geindex JUMP_BACKWARD (opcode)
@anchor{library/dis opcode-JUMP_BACKWARD}@anchor{912}
@deffn {Opcode} JUMP_BACKWARD (delta)

Decrements bytecode counter by `delta'. Checks for interrupts.


在 3.11 版被加入.

@end deffn

@geindex JUMP_BACKWARD_NO_INTERRUPT (opcode)
@anchor{library/dis opcode-JUMP_BACKWARD_NO_INTERRUPT}@anchor{906}
@deffn {Opcode} JUMP_BACKWARD_NO_INTERRUPT (delta)

Decrements bytecode counter by `delta'. Does not check for interrupts.


在 3.11 版被加入.

@end deffn

@geindex POP_JUMP_IF_TRUE (opcode)
@anchor{library/dis opcode-POP_JUMP_IF_TRUE}@anchor{19b0}
@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{3c1,,bool} operand.

@end deffn

@geindex POP_JUMP_IF_FALSE (opcode)
@anchor{library/dis opcode-POP_JUMP_IF_FALSE}@anchor{19b1}
@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{3c1,,bool} operand.

@end deffn

@geindex POP_JUMP_IF_NOT_NONE (opcode)
@anchor{library/dis opcode-POP_JUMP_IF_NOT_NONE}@anchor{1aaf}
@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.


在 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{1aae}
@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.


在 3.11 版被加入.



在 3.12 版的變更: This is no longer a pseudo-instruction.

@end deffn

@geindex FOR_ITER (opcode)
@anchor{library/dis opcode-FOR_ITER}@anchor{1a0d}
@deffn {Opcode} FOR_ITER (delta)

@code{STACK[-1]} is an @ref{4c3,,iterator}.  Call its @ref{14ce,,__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{19ab}
@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{4bc5}
@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{172a,,UnboundLocalError}.

@end deffn

@geindex LOAD_FAST_BORROW (opcode)
@anchor{library/dis opcode-LOAD_FAST_BORROW}@anchor{36a}
@deffn {Opcode} LOAD_FAST_BORROW (var_num)

Pushes a borrowed reference to the local @code{co_varnames[var_num]} onto the
stack.


在 3.14 版被加入.

@end deffn

@geindex LOAD_FAST_LOAD_FAST (opcode)
@anchor{library/dis opcode-LOAD_FAST_LOAD_FAST}@anchor{4bc6}
@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.


在 3.13 版被加入.

@end deffn

@geindex LOAD_FAST_BORROW_LOAD_FAST_BORROW (opcode)
@anchor{library/dis opcode-LOAD_FAST_BORROW_LOAD_FAST_BORROW}@anchor{36b}
@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.


在 3.14 版被加入.

@end deffn

@geindex LOAD_FAST_CHECK (opcode)
@anchor{library/dis opcode-LOAD_FAST_CHECK}@anchor{704}
@deffn {Opcode} LOAD_FAST_CHECK (var_num)

Pushes a reference to the local @code{co_varnames[var_num]} onto the stack,
raising an @ref{172a,,UnboundLocalError} if the local variable has not been
initialized.


在 3.12 版被加入.

@end deffn

@geindex LOAD_FAST_AND_CLEAR (opcode)
@anchor{library/dis opcode-LOAD_FAST_AND_CLEAR}@anchor{703}
@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}.


在 3.12 版被加入.

@end deffn

@geindex STORE_FAST (opcode)
@anchor{library/dis opcode-STORE_FAST}@anchor{19b4}
@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{4bc7}
@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]}.


在 3.13 版被加入.

@end deffn

@geindex STORE_FAST_LOAD_FAST (opcode)
@anchor{library/dis opcode-STORE_FAST_LOAD_FAST}@anchor{4bc8}
@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.


在 3.13 版被加入.

@end deffn

@geindex DELETE_FAST (opcode)
@anchor{library/dis opcode-DELETE_FAST}@anchor{4bc9}
@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{907}
@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.


在 3.11 版被加入.

@end deffn

@geindex LOAD_DEREF (opcode)
@anchor{library/dis opcode-LOAD_DEREF}@anchor{4bca}
@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{223c,,co_varnames}.

@end deffn

@geindex LOAD_FROM_DICT_OR_DEREF (opcode)
@anchor{library/dis opcode-LOAD_FROM_DICT_OR_DEREF}@anchor{705}
@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{4bca,,LOAD_DEREF}. This is used for loading
@ref{180c,,closure variables} in class bodies (which previously used
@code{LOAD_CLASSDEREF}) and in
@ref{4a6,,annotation scopes} within class bodies.


在 3.12 版被加入.

@end deffn

@geindex STORE_DEREF (opcode)
@anchor{library/dis opcode-STORE_DEREF}@anchor{4bcb}
@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{223c,,co_varnames}.

@end deffn

@geindex DELETE_DEREF (opcode)
@anchor{library/dis opcode-DELETE_DEREF}@anchor{4bcc}
@deffn {Opcode} DELETE_DEREF (i)

Empties the cell contained in slot @code{i} of the "fast locals" storage.
Used by the @ref{1a62,,del} statement.


在 3.2 版被加入.



在 3.11 版的變更: @code{i} is no longer offset by the length of @ref{223c,,co_varnames}.

@end deffn

@geindex COPY_FREE_VARS (opcode)
@anchor{library/dis opcode-COPY_FREE_VARS}@anchor{905}
@deffn {Opcode} COPY_FREE_VARS (n)

Copies the @code{n} @ref{180c,,free (closure) variables} from the closure
into the frame. Removes the need for special code on the caller's side when calling
closures.


在 3.11 版被加入.

@end deffn

@geindex RAISE_VARARGS (opcode)
@anchor{library/dis opcode-RAISE_VARARGS}@anchor{4bcd}
@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{90d}
@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} 或 @code{NULL}

@item 
剩餘的位置引數
@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.


在 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{370,,CALL_KW}.

@end deffn

@geindex CALL_KW (opcode)
@anchor{library/dis opcode-CALL_KW}@anchor{370}
@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} 或 @code{NULL}

@item 
剩餘的位置引數

@item 
The named arguments

@item 
A @ref{60c,,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.


在 3.13 版被加入.

@end deffn

@geindex CALL_FUNCTION_EX (opcode)
@anchor{library/dis opcode-CALL_FUNCTION_EX}@anchor{f4a}
@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.


在 3.6 版被加入.

@end deffn

@geindex PUSH_NULL (opcode)
@anchor{library/dis opcode-PUSH_NULL}@anchor{90e}
@deffn {Opcode} PUSH_NULL

Pushes a @code{NULL} to the stack.
Used in the call sequence to match the @code{NULL} pushed by
@code{LOAD_METHOD} for non-method calls.


在 3.11 版被加入.

@end deffn

@geindex MAKE_FUNCTION (opcode)
@anchor{library/dis opcode-MAKE_FUNCTION}@anchor{f49}
@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{4bce,,SET_FUNCTION_ATTRIBUTE}.

@end deffn

@geindex SET_FUNCTION_ATTRIBUTE (opcode)
@anchor{library/dis opcode-SET_FUNCTION_ATTRIBUTE}@anchor{4bce}
@deffn {Opcode} SET_FUNCTION_ATTRIBUTE (flag)

Sets an attribute on a function object. Expects the function at @code{STACK[-1]}
and the attribute value to set at @code{STACK[-2]}; consumes both and leaves the
function at @code{STACK[-1]}. The flag determines which attribute to set:


@itemize *

@item 
@code{0x01} a tuple of default values for positional-only and
positional-or-keyword parameters in positional order

@item 
@code{0x02} a dictionary of keyword-only parameters' default values

@item 
@code{0x04} a tuple of strings containing parameters' annotations

@item 
@code{0x08} a tuple containing cells for free variables, making a closure
@end itemize


在 3.13 版被加入.

@end deffn

@geindex BUILD_SLICE (opcode)
@anchor{library/dis opcode-BUILD_SLICE}@anchor{4bcf}
@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{68d,,slice()} built-in function for more information.
@end deffn

@geindex EXTENDED_ARG (opcode)
@anchor{library/dis opcode-EXTENDED_ARG}@anchor{1a61}
@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{4bd0}
@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{169,,str()} on `value'

@item 
@code{oparg == 2}: call @ref{1c1,,repr()} on `value'

@item 
@code{oparg == 3}: call @ref{15dd,,ascii()} on `value'
@end itemize

Used for implementing formatted string literals (f-strings).


在 3.13 版被加入.

@end deffn

@geindex FORMAT_SIMPLE (opcode)
@anchor{library/dis opcode-FORMAT_SIMPLE}@anchor{4bd1}
@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).


在 3.13 版被加入.

@end deffn

@geindex FORMAT_WITH_SPEC (opcode)
@anchor{library/dis opcode-FORMAT_WITH_SPEC}@anchor{4bd2}
@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).


在 3.13 版被加入.

@end deffn

@geindex MATCH_CLASS (opcode)
@anchor{library/dis opcode-MATCH_CLASS}@anchor{917}
@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}.


在 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{5b3}
@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.


在 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{903}
@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.


在 3.11 版被加入.

@end deffn

@geindex SEND (opcode)
@anchor{library/dis opcode-SEND}@anchor{904}
@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{df0,,StopIteration}, pop the top value from the stack,
push the exception's @code{value} attribute, and increment the bytecode counter
by `delta'.


在 3.11 版被加入.

@end deffn

@geindex HAVE_ARGUMENT (opcode)
@anchor{library/dis opcode-HAVE_ARGUMENT}@anchor{6aa}
@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{599,,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 @ref{3c,,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{599,,hasarg} instead.

@end deffn

@geindex CALL_INTRINSIC_1 (opcode)
@anchor{library/dis opcode-CALL_INTRINSIC_1}@anchor{700}
@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

運算元

@tab

描述

@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{481,,typing.TypeVar}

@item

@code{INTRINSIC_PARAMSPEC}

@tab

Creates a
@ref{482,,typing.ParamSpec}

@item

@code{INTRINSIC_TYPEVARTUPLE}

@tab

Creates a
@ref{483,,typing.TypeVarTuple}

@item

@code{INTRINSIC_SUBSCRIPT_GENERIC}

@tab

Returns @ref{174e,,typing.Generic}
subscripted with the argument

@item

@code{INTRINSIC_TYPEALIAS}

@tab

Creates a
@ref{2ae,,typing.TypeAliasType};
used in the @ref{665,,type}
statement. The argument is a tuple
of the type alias's name,
type parameters, and value.

@end multitable



在 3.12 版被加入.

@end deffn

@geindex CALL_INTRINSIC_2 (opcode)
@anchor{library/dis opcode-CALL_INTRINSIC_2}@anchor{701}
@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

運算元

@tab

描述

@item

@code{INTRINSIC_2_INVALID}

@tab

Not valid

@item

@code{INTRINSIC_PREP_RERAISE_STAR}

@tab

Calculates the
@ref{4cd,,ExceptionGroup} to raise
from a @code{try-except*}.

@item

@code{INTRINSIC_TYPEVAR_WITH_BOUND}

@tab

Creates a @ref{481,,typing.TypeVar}
with a bound.

@item

@code{INTRINSIC_TYPEVAR_WITH_CONSTRAINTS}

@tab

Creates a
@ref{481,,typing.TypeVar} with
constraints.

@item

@code{INTRINSIC_SET_FUNCTION_TYPE_PARAMS}

@tab

Sets the @code{__type_params__}
attribute of a function.

@end multitable



在 3.12 版被加入.

@end deffn

@geindex LOAD_SPECIAL (opcode)
@anchor{library/dis opcode-LOAD_SPECIAL}@anchor{36d}
@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.


在 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{4bd3}
@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{4bd4}
@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{4bd5}
@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{186,,with} and @ref{185,,async with}
constructs, which push the return value of the context manager's
@ref{7dd,,__enter__()} or @ref{22cd,,__aenter__()} to the stack.
@end deffn

@geindex POP_BLOCK (opcode)
@anchor{library/dis opcode-POP_BLOCK}@anchor{4bd6}
@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 LOAD_CONST_IMMORTAL (opcode)
@anchor{library/dis opcode-LOAD_CONST_IMMORTAL}@anchor{373}
@deffn {Opcode} LOAD_CONST_IMMORTAL (consti)

Works as @ref{4bba,,LOAD_CONST}, but is more efficient for immortal objects.
@end deffn

@geindex JUMP (opcode)
@geindex JUMP_NO_INTERRUPT (opcode)
@anchor{library/dis opcode-JUMP}@anchor{4bd7}
@deffn {Opcode} JUMP
@anchor{library/dis opcode-JUMP_NO_INTERRUPT}@anchor{1ace}
@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{371}
@deffn {Opcode} JUMP_IF_TRUE
@anchor{library/dis opcode-JUMP_IF_FALSE}@anchor{372}
@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{19ae}
@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 位元組碼指令,dis --- Python bytecode 的反組譯器
@anchor{library/dis id1}@anchor{4bd8}@anchor{library/dis opcode-collections}@anchor{4b89}
@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{4b8d}
@deffn {資料} dis.opname

Sequence of operation names, indexable using the bytecode.
@end deffn

@geindex opmap (於 dis 模組中)
@anchor{library/dis dis opmap}@anchor{4bd9}
@deffn {資料} dis.opmap

Dictionary mapping operation names to bytecodes.
@end deffn

@geindex cmp_op (於 dis 模組中)
@anchor{library/dis dis cmp_op}@anchor{4bda}
@deffn {資料} dis.cmp_op

Sequence of all compare operation names.
@end deffn

@geindex hasarg (於 dis 模組中)
@anchor{library/dis dis hasarg}@anchor{599}
@deffn {資料} dis.hasarg

Sequence of bytecodes that use their argument.


在 3.12 版被加入.

@end deffn

@geindex hasconst (於 dis 模組中)
@anchor{library/dis dis hasconst}@anchor{4bdb}
@deffn {資料} dis.hasconst

Sequence of bytecodes that access a constant.
@end deffn

@geindex hasfree (於 dis 模組中)
@anchor{library/dis dis hasfree}@anchor{4bdc}
@deffn {資料} dis.hasfree

Sequence of bytecodes that access a @ref{180c,,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{4bdd}
@deffn {資料} dis.hasname

Sequence of bytecodes that access an attribute by name.
@end deffn

@geindex hasjump (於 dis 模組中)
@anchor{library/dis dis hasjump}@anchor{4bde}
@deffn {資料} dis.hasjump

Sequence of bytecodes that have a jump target. All jumps
are relative.


在 3.13 版被加入.

@end deffn

@geindex haslocal (於 dis 模組中)
@anchor{library/dis dis haslocal}@anchor{4bdf}
@deffn {資料} dis.haslocal

Sequence of bytecodes that access a local variable.
@end deffn

@geindex hascompare (於 dis 模組中)
@anchor{library/dis dis hascompare}@anchor{4be0}
@deffn {資料} dis.hascompare

Sequence of bytecodes of Boolean operations.
@end deffn

@geindex hasexc (於 dis 模組中)
@anchor{library/dis dis hasexc}@anchor{6ab}
@deffn {資料} dis.hasexc

Sequence of bytecodes that set an exception handler.


在 3.12 版被加入.

@end deffn

@geindex hasjrel (於 dis 模組中)
@anchor{library/dis dis hasjrel}@anchor{4be1}
@deffn {資料} dis.hasjrel

Sequence of bytecodes that have a relative jump target.


在 3.13 版之後被棄用: All jumps are now relative. Use @ref{4bde,,hasjump}.

@end deffn

@geindex hasjabs (於 dis 模組中)
@anchor{library/dis dis hasjabs}@anchor{4be2}
@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 --- pickle 開發者的工具,,dis --- Python bytecode 的反組譯器,Python 語言服務
@anchor{library/pickletools doc}@anchor{4be3}@anchor{library/pickletools module-pickletools}@anchor{ac}@anchor{library/pickletools pickletools-tools-for-pickle-developers}@anchor{4be4}@anchor{library/pickletools translation-repo}@anchor{4be5}
@subsection @code{pickletools} --- pickle 開發者的工具


@geindex module; pickletools

`原始碼：'Lib/pickletools.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/pickletools.py}


__________________________________________________________________


該模組包含與 @ref{ab,,pickle} 模組的詳細資訊相關的各種常數、一些有關實作的冗長註釋以及一些用於分析已 pickle 資料的有用函式。該模組的內容對於有 @ref{ab,,pickle} 相關工作的 Python 核心開發人員很有用；@ref{ab,,pickle} 模組的一般使用者可能不會發現 @ref{ac,,pickletools} 模組。

@menu
* 命令列用法: 命令列用法<12>. 
* 程式化介面:: 

@end menu

@node 命令列用法<12>,程式化介面,,pickletools --- pickle 開發者的工具
@anchor{library/pickletools command-line-usage}@anchor{4be6}@anchor{library/pickletools pickletools-cli}@anchor{2be2}
@subsubsection 命令列用法



在 3.2 版被加入.


當從命令列呼叫時，@code{python -m pickletools} 將拆解 (disassemble) 一個或多個 pickle 檔案的內容。請注意，如果你想查看儲存在 pickle 中的 Python 物件而不是 pickle 格式的詳細資訊，你可能需要使用 @code{-m pickle}。但是，當你要檢查的 pickle 檔案來自不受信任的來源時，@code{-m pickletools} 是一個更安全的選項，因為它不執行 pickle 位元組碼。

例如，pickle 於檔案 @code{x.pickle} 中的元組 @code{(1, 2)}：

@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
* 命令列選項: 命令列選項<5>. 

@end menu

@node 命令列選項<5>,,,命令列用法<12>
@anchor{library/pickletools command-line-options}@anchor{4be7}
@subsubsection 命令列選項


@geindex pickletools 命令列選項; -a
@geindex pickletools 命令列選項; --annotate
@anchor{library/pickletools cmdoption-pickletools-a}@anchor{4be8}@anchor{library/pickletools cmdoption-pickletools-annotate}@anchor{4be9}
@deffn {Option} @w{-}a, @w{-}@w{-}annotate

用簡短的操作碼 (opcode) 描述註釋每一行。
@end deffn

@geindex pickletools 命令列選項; -o
@geindex pickletools 命令列選項; --output
@anchor{library/pickletools cmdoption-pickletools-o}@anchor{4bea}@anchor{library/pickletools cmdoption-pickletools-output}@anchor{4beb}
@deffn {Option} @w{-}o, @w{-}@w{-}output=<file>

應將輸出結果寫入之檔案的名稱。
@end deffn

@geindex pickletools 命令列選項; -l
@geindex pickletools 命令列選項; --indentlevel
@anchor{library/pickletools cmdoption-pickletools-l}@anchor{4bec}@anchor{library/pickletools cmdoption-pickletools-indentlevel}@anchor{4bed}
@deffn {Option} @w{-}l, @w{-}@w{-}indentlevel=<num>

新 MARK 級別縮進的空格數。
@end deffn

@geindex pickletools 命令列選項; -m
@geindex pickletools 命令列選項; --memo
@anchor{library/pickletools cmdoption-pickletools-m}@anchor{4bee}@anchor{library/pickletools cmdoption-pickletools-memo}@anchor{4bef}
@deffn {Option} @w{-}m, @w{-}@w{-}memo

當拆解多個物件時，會在拆解間保留備忘錄。
@end deffn

@geindex pickletools 命令列選項; -p
@geindex pickletools 命令列選項; --preamble
@anchor{library/pickletools cmdoption-pickletools-p}@anchor{4bf0}@anchor{library/pickletools cmdoption-pickletools-preamble}@anchor{4bf1}
@deffn {Option} @w{-}p, @w{-}@w{-}preamble=<preamble>

當指定多個 pickle 檔案時，會在每次拆解之前印出給定的一段序言 (preamble)。
@end deffn

@geindex pickletools 命令列選項; pickle_file
@anchor{library/pickletools cmdoption-pickletools-arg-pickle_file}@anchor{4bf2}
@deffn {Option} pickle_file

A pickle file to read, or @code{-} to indicate reading from standard input.
@end deffn

@node 程式化介面,,命令列用法<12>,pickletools --- pickle 開發者的工具
@anchor{library/pickletools programmatic-interface}@anchor{4bf3}
@subsubsection 程式化介面


@geindex dis() (於 pickletools 模組中)
@anchor{library/pickletools pickletools dis}@anchor{eb9}
@deffn {函式} pickletools.dis (pickle, out=None, memo=None, indentlevel=4, annotate=0)

將 pickle 的符號拆解 (symbolic disassembly) 輸出到類檔案物件 `out'，預設為 @code{sys.stdout}。`pickle' 可以是字串或類檔案物件。`memo' 可以是一個 Python 字典，將用作 pickle 的備忘錄；它可用於對同一 pickler 建立的多個 pickle 執行拆解。串流中由 @code{MARK} 操作碼指示的連續級別由 `indentlevel' 空格縮進。如果為 `annotate' 指定非零值，則輸出中的每個操作碼都會用簡短的描述進行註釋。`annotate' 的值用作為註釋之起始行提示。


在 3.2 版的變更: 新增 `annotate' 參數。

@end deffn

@geindex genops() (於 pickletools 模組中)
@anchor{library/pickletools pickletools genops}@anchor{4bf4}
@deffn {函式} pickletools.genops (pickle)

提供 pickle 中所有操作碼的一個 @ref{4c3,,iterator}，回傳形式為 @code{(opcode, arg, pos)} 三元組序列。`opcode' 是 @code{OpcodeInfo} 類別的實例；`arg' 是操作碼引數的解碼值（作為 Python 物件）；`pos' 是該操作碼所在的位置。`pickle' 可以是字串或類檔案物件。
@end deffn

@geindex optimize() (於 pickletools 模組中)
@anchor{library/pickletools pickletools optimize}@anchor{2bc9}
@deffn {函式} pickletools.optimize (picklestring)

消除未使用的 @code{PUT} 操作碼後回傳一個新的等效 pickle 字串。最佳化後的 pickle 更短、傳輸時間更少、需要更小的儲存空間，且 unpickle 效率也更高。
@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 特有服務,Unix 特有服務,Python 語言服務,Python 標準函式庫 Standard Library
@anchor{library/windows doc}@anchor{4bf5}@anchor{library/windows ms-windows-specific-services}@anchor{4bf6}@anchor{library/windows mswin-specific-services}@anchor{20e4}@anchor{library/windows translation-repo}@anchor{4bf7}
@section MS Windows 特有服務


此章節描述僅在 MS Windows 系統上可用的模組 (module)。

@menu
* msvcrt: msvcrt --- MS VC++ runtime 提供的有用例程. MS VC++ runtime 提供的有用例程
* winreg: winreg --- Windows 註冊表存取. Windows 註冊表存取
* winsound: winsound --- Windows 的音效播放介面. Windows 的音效播放介面

@end menu

@node msvcrt --- MS VC++ runtime 提供的有用例程,winreg --- Windows 註冊表存取,,MS Windows 特有服務
@anchor{library/msvcrt doc}@anchor{4bf8}@anchor{library/msvcrt module-msvcrt}@anchor{97}@anchor{library/msvcrt msvcrt-useful-routines-from-the-ms-vc-runtime}@anchor{4bf9}
@subsection @code{msvcrt} --- MS VC++ runtime 提供的有用例程


@geindex module; msvcrt


__________________________________________________________________


These functions provide access to some useful capabilities on Windows platforms.
Some higher-level modules use these functions to build the Windows
implementations of their services. For example, the @ref{66,,getpass} module uses
this in the implementation of the @ref{66,,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.


在 3.3 版的變更: Operations in this module now raise @ref{2c0,,OSError} where @ref{124e,,IOError}
was raised.


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

@end menu

@node File Operations,Console I/O,,msvcrt --- MS VC++ runtime 提供的有用例程
@anchor{library/msvcrt file-operations}@anchor{4bfa}@anchor{library/msvcrt msvcrt-files}@anchor{4bfb}
@subsubsection File Operations


@geindex locking() (於 msvcrt 模組中)
@anchor{library/msvcrt msvcrt locking}@anchor{4617}
@deffn {函式} msvcrt.locking (fd, mode, nbytes)

Lock part of a file based on file descriptor `fd' from the C runtime. Raises
@ref{2c0,,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.

引發一個附帶引數 @code{fd}、@code{mode}、@code{nbytes} 的@ref{1b70,,稽核事件} @code{msvcrt.locking}。
@end deffn

@geindex LK_LOCK (於 msvcrt 模組中)
@geindex LK_RLCK (於 msvcrt 模組中)
@anchor{library/msvcrt msvcrt LK_LOCK}@anchor{4bfc}
@deffn {資料} msvcrt.LK_LOCK
@anchor{library/msvcrt msvcrt LK_RLCK}@anchor{4bfd}
@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{2c0,,OSError} is raised.
@end deffn

@geindex LK_NBLCK (於 msvcrt 模組中)
@geindex LK_NBRLCK (於 msvcrt 模組中)
@anchor{library/msvcrt msvcrt LK_NBLCK}@anchor{4bfe}
@deffn {資料} msvcrt.LK_NBLCK
@anchor{library/msvcrt msvcrt LK_NBRLCK}@anchor{4bff}
@deffnx {資料} msvcrt.LK_NBRLCK

Locks the specified bytes. If the bytes cannot be locked, @ref{2c0,,OSError} is
raised.
@end deffn

@geindex LK_UNLCK (於 msvcrt 模組中)
@anchor{library/msvcrt msvcrt LK_UNLCK}@anchor{4c00}
@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{4c01}
@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{2f06,,os.O_TEXT}; for binary, it should be
@ref{2ef7,,os.O_BINARY}.
@end deffn

@geindex open_osfhandle() (於 msvcrt 模組中)
@anchor{library/msvcrt msvcrt open_osfhandle}@anchor{4618}
@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{2ef9,,os.O_APPEND},
@ref{2ef5,,os.O_RDONLY}, @ref{2f06,,os.O_TEXT} and @ref{2f01,,os.O_NOINHERIT}.
The returned file descriptor may be used as a parameter
to @ref{2232,,os.fdopen()} to create a file object.

The file descriptor is inheritable by default. Pass @ref{2f01,,os.O_NOINHERIT}
flag to make it non inheritable.

引發一個附帶引數 @code{handle}、@code{flags} 的@ref{1b70,,稽核事件} @code{msvcrt.open_osfhandle}。
@end deffn

@geindex get_osfhandle() (於 msvcrt 模組中)
@anchor{library/msvcrt msvcrt get_osfhandle}@anchor{4616}
@deffn {函式} msvcrt.get_osfhandle (fd)

Return the file handle for the file descriptor `fd'. Raises @ref{2c0,,OSError} if
`fd' is not recognized.

引發一個附帶引數 @code{fd} 的@ref{1b70,,稽核事件} @code{msvcrt.get_osfhandle}。
@end deffn

@node Console I/O,Other Functions,File Operations,msvcrt --- MS VC++ runtime 提供的有用例程
@anchor{library/msvcrt console-i-o}@anchor{4c02}@anchor{library/msvcrt msvcrt-console}@anchor{4c03}
@subsubsection Console I/O


@geindex kbhit() (於 msvcrt 模組中)
@anchor{library/msvcrt msvcrt kbhit}@anchor{4c04}
@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{4c05}
@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{15ec}
@deffn {函式} msvcrt.getwch ()

Wide char variant of @ref{4c05,,getch()}, returning a Unicode value.
@end deffn

@geindex getche() (於 msvcrt 模組中)
@anchor{library/msvcrt msvcrt getche}@anchor{4c06}
@deffn {函式} msvcrt.getche ()

Similar to @ref{4c05,,getch()}, but the keypress will be echoed if it represents a
printable character.
@end deffn

@geindex getwche() (於 msvcrt 模組中)
@anchor{library/msvcrt msvcrt getwche}@anchor{15ed}
@deffn {函式} msvcrt.getwche ()

Wide char variant of @ref{4c06,,getche()}, returning a Unicode value.
@end deffn

@geindex putch() (於 msvcrt 模組中)
@anchor{library/msvcrt msvcrt putch}@anchor{4c07}
@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{15ee}
@deffn {函式} msvcrt.putwch (unicode_char)

Wide char variant of @ref{4c07,,putch()}, accepting a Unicode value.
@end deffn

@geindex ungetch() (於 msvcrt 模組中)
@anchor{library/msvcrt msvcrt ungetch}@anchor{4c08}
@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{4c05,,getch()} or @ref{4c06,,getche()}.
@end deffn

@geindex ungetwch() (於 msvcrt 模組中)
@anchor{library/msvcrt msvcrt ungetwch}@anchor{4c09}
@deffn {函式} msvcrt.ungetwch (unicode_char)

Wide char variant of @ref{4c08,,ungetch()}, accepting a Unicode value.
@end deffn

@node Other Functions,,Console I/O,msvcrt --- MS VC++ runtime 提供的有用例程
@anchor{library/msvcrt msvcrt-other}@anchor{4c0a}@anchor{library/msvcrt other-functions}@anchor{4c0b}
@subsubsection Other Functions


@geindex heapmin() (於 msvcrt 模組中)
@anchor{library/msvcrt msvcrt heapmin}@anchor{4c0c}
@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{2c0,,OSError}.
@end deffn

@geindex set_error_mode() (於 msvcrt 模組中)
@anchor{library/msvcrt msvcrt set_error_mode}@anchor{4c0d}
@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{4c0e,,REPORT_ERRMODE}. Returns the old setting
or -1 if an error occurs. Only available in
@ref{504,,debug build of Python}.
@end deffn

@geindex OUT_TO_DEFAULT (於 msvcrt 模組中)
@anchor{library/msvcrt msvcrt OUT_TO_DEFAULT}@anchor{4c0f}
@deffn {資料} msvcrt.OUT_TO_DEFAULT

Error sink is determined by the app's type. Only available in
@ref{504,,debug build of Python}.
@end deffn

@geindex OUT_TO_STDERR (於 msvcrt 模組中)
@anchor{library/msvcrt msvcrt OUT_TO_STDERR}@anchor{4c10}
@deffn {資料} msvcrt.OUT_TO_STDERR

Error sink is a standard error. Only available in
@ref{504,,debug build of Python}.
@end deffn

@geindex OUT_TO_MSGBOX (於 msvcrt 模組中)
@anchor{library/msvcrt msvcrt OUT_TO_MSGBOX}@anchor{4c11}
@deffn {資料} msvcrt.OUT_TO_MSGBOX

Error sink is a message box. Only available in
@ref{504,,debug build of Python}.
@end deffn

@geindex REPORT_ERRMODE (於 msvcrt 模組中)
@anchor{library/msvcrt msvcrt REPORT_ERRMODE}@anchor{4c0e}
@deffn {資料} msvcrt.REPORT_ERRMODE

Report the current error mode value. Only available in
@ref{504,,debug build of Python}.
@end deffn

@geindex CrtSetReportMode() (於 msvcrt 模組中)
@anchor{library/msvcrt msvcrt CrtSetReportMode}@anchor{4c12}
@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{504,,debug build of Python}.
@end deffn

@geindex CrtSetReportFile() (於 msvcrt 模組中)
@anchor{library/msvcrt msvcrt CrtSetReportFile}@anchor{4c13}
@deffn {函式} msvcrt.CrtSetReportFile (type, file)

After you use @ref{4c12,,CrtSetReportMode()} to specify @ref{4c14,,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{504,,debug build of Python}.
@end deffn

@geindex CRT_WARN (於 msvcrt 模組中)
@anchor{library/msvcrt msvcrt CRT_WARN}@anchor{4c15}
@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{4c16}
@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{4c17}
@deffn {資料} msvcrt.CRT_ASSERT

Assertion failures.
@end deffn

@geindex CRTDBG_MODE_DEBUG (於 msvcrt 模組中)
@anchor{library/msvcrt msvcrt CRTDBG_MODE_DEBUG}@anchor{4c18}
@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{4c14}
@deffn {資料} msvcrt.CRTDBG_MODE_FILE

Writes the message to a user-supplied file handle. @ref{4c13,,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{4c19}
@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{4c1a}
@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{1557}
@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{1558}
@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{1559}
@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 註冊表存取,winsound --- Windows 的音效播放介面,msvcrt --- MS VC++ runtime 提供的有用例程,MS Windows 特有服務
@anchor{library/winreg doc}@anchor{4c1b}@anchor{library/winreg module-winreg}@anchor{11c}@anchor{library/winreg translation-repo}@anchor{4c1c}@anchor{library/winreg winreg-windows-registry-access}@anchor{4c1d}
@subsection @code{winreg} --- Windows 註冊表存取


@geindex module; winreg


__________________________________________________________________


These functions expose the Windows registry API to Python.  Instead of using an
integer as the registry handle, a @ref{4c1e,,handle object} is used
to ensure that the handles are closed correctly, even if the programmer neglects
to explicitly close them.
@anchor{library/winreg exception-changed}@anchor{4c1f}

在 3.3 版的變更: Several functions in this module used to raise a
@ref{1250,,WindowsError}, which is now an alias of @ref{2c0,,OSError}.


@menu
* 函式: 函式<13>. 
* 常數: 常數<10>. 
* Registry Handle Objects:: 

@end menu

@node 函式<13>,常數<10>,,winreg --- Windows 註冊表存取
@anchor{library/winreg functions}@anchor{4c20}@anchor{library/winreg id1}@anchor{4c21}
@subsubsection 函式


This module offers the following functions:

@geindex CloseKey() (於 winreg 模組中)
@anchor{library/winreg winreg CloseKey}@anchor{4c22}
@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{4c23,,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{461d}
@deffn {函式} winreg.ConnectRegistry (computer_name, key)

Establishes a connection to a predefined registry handle on another computer,
and returns a @ref{4c1e,,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{2c0,,OSError} exception is raised.

引發一個附帶引數 @code{computer_name}、@code{key} 的@ref{1b70,,稽核事件} @code{winreg.ConnectRegistry}。


在 3.3 版的變更: See @ref{4c1f,,above}.

@end deffn

@geindex CreateKey() (於 winreg 模組中)
@anchor{library/winreg winreg CreateKey}@anchor{461e}
@deffn {函式} winreg.CreateKey (key, sub_key)

Creates or opens the specified key, returning a
@ref{4c1e,,handle object}.

`key' is an already open key, or one of the predefined
@ref{4c24,,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{2c0,,OSError} exception is raised.

引發一個附帶引數 @code{key}、@code{sub_key}、@code{access} 的@ref{1b70,,稽核事件} @code{winreg.CreateKey}。

引發一個附帶引數 @code{key} 的@ref{1b70,,稽核事件} @code{winreg.OpenKey/result}。


在 3.3 版的變更: See @ref{4c1f,,above}.

@end deffn

@geindex CreateKeyEx() (於 winreg 模組中)
@anchor{library/winreg winreg CreateKeyEx}@anchor{155a}
@deffn {函式} winreg.CreateKeyEx (key, sub_key, reserved=0, access=KEY_WRITE)

Creates or opens the specified key, returning a
@ref{4c1e,,handle object}.

`key' is an already open key, or one of the predefined
@ref{4c24,,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{4c25,,KEY_WRITE}.  See
@ref{4c26,,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{2c0,,OSError} exception is raised.

引發一個附帶引數 @code{key}、@code{sub_key}、@code{access} 的@ref{1b70,,稽核事件} @code{winreg.CreateKey}。

引發一個附帶引數 @code{key} 的@ref{1b70,,稽核事件} @code{winreg.OpenKey/result}。


在 3.2 版被加入.



在 3.3 版的變更: See @ref{4c1f,,above}.

@end deffn

@geindex DeleteKey() (於 winreg 模組中)
@anchor{library/winreg winreg DeleteKey}@anchor{461f}
@deffn {函式} winreg.DeleteKey (key, sub_key)

Deletes the specified key.

`key' is an already open key, or one of the predefined
@ref{4c24,,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{2c0,,OSError} exception is raised.

引發一個附帶引數 @code{key}、@code{sub_key}、@code{access} 的@ref{1b70,,稽核事件} @code{winreg.DeleteKey}。


在 3.3 版的變更: See @ref{4c1f,,above}.

@end deffn

@geindex DeleteKeyEx() (於 winreg 模組中)
@anchor{library/winreg winreg DeleteKeyEx}@anchor{155b}
@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{4c24,,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{4c27,,KEY_WOW64_64KEY}.
On 32-bit Windows, the WOW64 constants are ignored.
See @ref{4c26,,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{2c0,,OSError} exception is raised.

On unsupported Windows versions, @ref{369,,NotImplementedError} is raised.

引發一個附帶引數 @code{key}、@code{sub_key}、@code{access} 的@ref{1b70,,稽核事件} @code{winreg.DeleteKey}。


在 3.2 版被加入.



在 3.3 版的變更: See @ref{4c1f,,above}.

@end deffn

@geindex DeleteValue() (於 winreg 模組中)
@anchor{library/winreg winreg DeleteValue}@anchor{4620}
@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{4c24,,HKEY_* constants}.

`value' is a string that identifies the value to remove.

引發一個附帶引數 @code{key}、@code{value} 的@ref{1b70,,稽核事件} @code{winreg.DeleteValue}。
@end deffn

@geindex EnumKey() (於 winreg 模組中)
@anchor{library/winreg winreg EnumKey}@anchor{4621}
@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{4c24,,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{2c0,,OSError} exception is
raised, indicating, no more values are available.

引發一個附帶引數 @code{key}、@code{index} 的@ref{1b70,,稽核事件} @code{winreg.EnumKey}。


在 3.3 版的變更: See @ref{4c1f,,above}.

@end deffn

@geindex EnumValue() (於 winreg 模組中)
@anchor{library/winreg winreg EnumValue}@anchor{4622}
@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{4c24,,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{2c0,,OSError} exception is
raised, indicating no more values.

The result is a tuple of 3 items:


@multitable {xxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Index

@tab

含義

@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{1a49,,SetValueEx()})

@end multitable


引發一個附帶引數 @code{key}、@code{index} 的@ref{1b70,,稽核事件} @code{winreg.EnumValue}。


在 3.3 版的變更: See @ref{4c1f,,above}.

@end deffn

@geindex % （百分號）;environment variables expansion (Windows) （環境變數展開 (Windows)）

@geindex ExpandEnvironmentStrings() (於 winreg 模組中)
@anchor{library/winreg winreg ExpandEnvironmentStrings}@anchor{15ef}
@deffn {函式} winreg.ExpandEnvironmentStrings (str)

Expands environment variable placeholders @code{%NAME%} in strings like
@ref{4c28,,REG_EXPAND_SZ}:

@example
>>> ExpandEnvironmentStrings('%windir%')
'C:\\Windows'
@end example

引發一個附帶引數 @code{str} 的@ref{1b70,,稽核事件} @code{winreg.ExpandEnvironmentStrings}。
@end deffn

@geindex FlushKey() (於 winreg 模組中)
@anchor{library/winreg winreg FlushKey}@anchor{4c29}
@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{4c24,,HKEY_* constants}.

It is not necessary to call @ref{4c29,,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{4c22,,CloseKey()}, the
@ref{4c29,,FlushKey()} method returns only when all the data has been written to the
registry. An application should only call @ref{4c29,,FlushKey()} if it requires
absolute certainty that registry changes are on disk.

@cartouche
@quotation 備註 
If you don't know whether a @ref{4c29,,FlushKey()} call is required, it probably
isn't.
@end quotation
@end cartouche
@end deffn

@geindex LoadKey() (於 winreg 模組中)
@anchor{library/winreg winreg LoadKey}@anchor{4623}
@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{461d,,ConnectRegistry()} or one of the constants
@ref{4c2a,,HKEY_USERS} or @ref{4c2b,,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{4629,,SaveKey()} function. Under the file allocation
table (FAT) file system, the filename may not have an extension.

A call to @ref{4623,,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{461d,,ConnectRegistry()}, then the path
specified in `file_name' is relative to the remote computer.

引發一個附帶引數 @code{key}、@code{sub_key}、@code{file_name} 的@ref{1b70,,稽核事件} @code{winreg.LoadKey}。
@end deffn

@geindex OpenKey() (於 winreg 模組中)
@geindex OpenKeyEx() (於 winreg 模組中)
@anchor{library/winreg winreg OpenKey}@anchor{4624}
@deffn {函式} winreg.OpenKey (key, sub_key, reserved=0, access=KEY_READ)
@anchor{library/winreg winreg OpenKeyEx}@anchor{4c2c}
@deffnx {函式} winreg.OpenKeyEx (key, sub_key, reserved=0, access=KEY_READ)

Opens the specified key, returning a @ref{4c1e,,handle object}.

`key' is an already open key, or one of the predefined
@ref{4c24,,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{4c2d,,KEY_READ}.  See @ref{4c26,,Access Rights} for other allowed values.

The result is a new handle to the specified key.

If the function fails, @ref{2c0,,OSError} is raised.

引發一個附帶引數 @code{key}、@code{sub_key}、@code{access} 的@ref{1b70,,稽核事件} @code{winreg.OpenKey}。

引發一個附帶引數 @code{key} 的@ref{1b70,,稽核事件} @code{winreg.OpenKey/result}。


在 3.2 版的變更: Allow the use of named arguments.



在 3.3 版的變更: See @ref{4c1f,,above}.

@end deffn

@geindex QueryInfoKey() (於 winreg 模組中)
@anchor{library/winreg winreg QueryInfoKey}@anchor{4626}
@deffn {函式} winreg.QueryInfoKey (key)

Returns information about a key, as a tuple.

`key' is an already open key, or one of the predefined
@ref{4c24,,HKEY_* constants}.

The result is a tuple of 3 items:


@multitable {xxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Index

@tab

含義

@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


引發一個附帶引數 @code{key} 的@ref{1b70,,稽核事件} @code{winreg.QueryInfoKey}。
@end deffn

@geindex QueryValue() (於 winreg 模組中)
@anchor{library/winreg winreg QueryValue}@anchor{4627}
@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{4c24,,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{462a,,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{4628,,QueryValueEx()} if possible.

引發一個附帶引數 @code{key}、@code{sub_key}、@code{value_name} 的@ref{1b70,,稽核事件} @code{winreg.QueryKey}。
@end deffn

@geindex QueryValueEx() (於 winreg 模組中)
@anchor{library/winreg winreg QueryValueEx}@anchor{4628}
@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{4c24,,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

含義

@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{1a49,,SetValueEx()})

@end multitable


引發一個附帶引數 @code{key}、@code{sub_key}、@code{value_name} 的@ref{1b70,,稽核事件} @code{winreg.QueryKey}。
@end deffn

@geindex SaveKey() (於 winreg 模組中)
@anchor{library/winreg winreg SaveKey}@anchor{4629}
@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{4c24,,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{4623,,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.

引發一個附帶引數 @code{key}、@code{file_name} 的@ref{1b70,,稽核事件} @code{winreg.SaveKey}。
@end deffn

@geindex SetValue() (於 winreg 模組中)
@anchor{library/winreg winreg SetValue}@anchor{462a}
@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{4c24,,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{4c2e,,REG_SZ}, meaning only strings are supported.  Use the @ref{1a49,,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{4c2f,,KEY_SET_VALUE} access.

引發一個附帶引數 @code{key}、@code{sub_key}、@code{type}、@code{value} 的@ref{1b70,,稽核事件} @code{winreg.SetValue}。
@end deffn

@geindex SetValueEx() (於 winreg 模組中)
@anchor{library/winreg winreg SetValueEx}@anchor{1a49}
@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{4c24,,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{4c30,,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{4c2f,,KEY_SET_VALUE} access.

To open the key, use the @ref{461e,,CreateKey()} or @ref{4624,,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.

引發一個附帶引數 @code{key}、@code{sub_key}、@code{type}、@code{value} 的@ref{1b70,,稽核事件} @code{winreg.SetValue}。
@end deffn

@geindex DisableReflectionKey() (於 winreg 模組中)
@anchor{library/winreg winreg DisableReflectionKey}@anchor{155c}
@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{4c24,,HKEY_* constants}.

Will generally raise @ref{369,,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.

引發一個附帶引數 @code{key} 的@ref{1b70,,稽核事件} @code{winreg.DsiableReflectionKey}。
@end deffn

@geindex EnableReflectionKey() (於 winreg 模組中)
@anchor{library/winreg winreg EnableReflectionKey}@anchor{155d}
@deffn {函式} winreg.EnableReflectionKey (key)

Restores registry reflection for the specified disabled key.

`key' is an already open key, or one of the predefined @ref{4c24,,HKEY_* constants}.

Will generally raise @ref{369,,NotImplementedError} if executed on a 32-bit operating
system.

Restoring reflection for a key does not affect reflection of any subkeys.

引發一個附帶引數 @code{key} 的@ref{1b70,,稽核事件} @code{winreg.EnableReflectionKey}。
@end deffn

@geindex QueryReflectionKey() (於 winreg 模組中)
@anchor{library/winreg winreg QueryReflectionKey}@anchor{155e}
@deffn {函式} winreg.QueryReflectionKey (key)

Determines the reflection state for the specified key.

`key' is an already open key, or one of the predefined
@ref{4c24,,HKEY_* constants}.

Returns @code{True} if reflection is disabled.

Will generally raise @ref{369,,NotImplementedError} if executed on a 32-bit
operating system.

引發一個附帶引數 @code{key} 的@ref{1b70,,稽核事件} @code{winreg.QueryReflectionKey}。
@end deffn

@node 常數<10>,Registry Handle Objects,函式<13>,winreg --- Windows 註冊表存取
@anchor{library/winreg constants}@anchor{4c31}@anchor{library/winreg id2}@anchor{4c32}
@subsubsection 常數


The following constants are defined for use in many @ref{11c,,winreg} functions.

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

@end menu

@node HKEY_* Constants,Access Rights,,常數<10>
@anchor{library/winreg hkey-constants}@anchor{4c24}@anchor{library/winreg id3}@anchor{4c33}
@subsubsection HKEY_* Constants


@geindex HKEY_CLASSES_ROOT (於 winreg 模組中)
@anchor{library/winreg winreg HKEY_CLASSES_ROOT}@anchor{4c34}
@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{4c35}
@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{4c2b}
@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{4c2a}
@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{4c36}
@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{4c37}
@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{4c38}
@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,常數<10>
@anchor{library/winreg access-rights}@anchor{4c26}@anchor{library/winreg id4}@anchor{4c39}
@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{4c3a}
@deffn {資料} winreg.KEY_ALL_ACCESS

Combines the STANDARD_RIGHTS_REQUIRED, @ref{4c3b,,KEY_QUERY_VALUE},
@ref{4c2f,,KEY_SET_VALUE}, @ref{4c3c,,KEY_CREATE_SUB_KEY},
@ref{4c3d,,KEY_ENUMERATE_SUB_KEYS}, @ref{4c3e,,KEY_NOTIFY},
and @ref{4c3f,,KEY_CREATE_LINK} access rights.
@end deffn

@geindex KEY_WRITE (於 winreg 模組中)
@anchor{library/winreg winreg KEY_WRITE}@anchor{4c25}
@deffn {資料} winreg.KEY_WRITE

Combines the STANDARD_RIGHTS_WRITE, @ref{4c2f,,KEY_SET_VALUE}, and
@ref{4c3c,,KEY_CREATE_SUB_KEY} access rights.
@end deffn

@geindex KEY_READ (於 winreg 模組中)
@anchor{library/winreg winreg KEY_READ}@anchor{4c2d}
@deffn {資料} winreg.KEY_READ

Combines the STANDARD_RIGHTS_READ, @ref{4c3b,,KEY_QUERY_VALUE},
@ref{4c3d,,KEY_ENUMERATE_SUB_KEYS}, and @ref{4c3e,,KEY_NOTIFY} values.
@end deffn

@geindex KEY_EXECUTE (於 winreg 模組中)
@anchor{library/winreg winreg KEY_EXECUTE}@anchor{4c40}
@deffn {資料} winreg.KEY_EXECUTE

Equivalent to @ref{4c2d,,KEY_READ}.
@end deffn

@geindex KEY_QUERY_VALUE (於 winreg 模組中)
@anchor{library/winreg winreg KEY_QUERY_VALUE}@anchor{4c3b}
@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{4c2f}
@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{4c3c}
@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{4c3d}
@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{4c3e}
@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{4c3f}
@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{4c41}@anchor{library/winreg bit-specific}@anchor{4c42}
@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{4c27}
@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{4c43}
@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,常數<10>
@anchor{library/winreg id5}@anchor{4c44}@anchor{library/winreg value-types}@anchor{4c30}
@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{4c45}
@deffn {資料} winreg.REG_BINARY

Binary data in any form.
@end deffn

@geindex REG_DWORD (於 winreg 模組中)
@anchor{library/winreg winreg REG_DWORD}@anchor{4c46}
@deffn {資料} winreg.REG_DWORD

32-bit number.
@end deffn

@geindex REG_DWORD_LITTLE_ENDIAN (於 winreg 模組中)
@anchor{library/winreg winreg REG_DWORD_LITTLE_ENDIAN}@anchor{4c47}
@deffn {資料} winreg.REG_DWORD_LITTLE_ENDIAN

A 32-bit number in little-endian format. Equivalent to @ref{4c46,,REG_DWORD}.
@end deffn

@geindex REG_DWORD_BIG_ENDIAN (於 winreg 模組中)
@anchor{library/winreg winreg REG_DWORD_BIG_ENDIAN}@anchor{4c48}
@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{4c28}
@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{4c49}
@deffn {資料} winreg.REG_LINK

A Unicode symbolic link.
@end deffn

@geindex REG_MULTI_SZ (於 winreg 模組中)
@anchor{library/winreg winreg REG_MULTI_SZ}@anchor{1c8c}
@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{4c4a}
@deffn {資料} winreg.REG_NONE

No defined value type.
@end deffn

@geindex REG_QWORD (於 winreg 模組中)
@anchor{library/winreg winreg REG_QWORD}@anchor{efa}
@deffn {資料} winreg.REG_QWORD

A 64-bit number.


在 3.6 版被加入.

@end deffn

@geindex REG_QWORD_LITTLE_ENDIAN (於 winreg 模組中)
@anchor{library/winreg winreg REG_QWORD_LITTLE_ENDIAN}@anchor{4c4b}
@deffn {資料} winreg.REG_QWORD_LITTLE_ENDIAN

A 64-bit number in little-endian format. Equivalent to @ref{efa,,REG_QWORD}.


在 3.6 版被加入.

@end deffn

@geindex REG_RESOURCE_LIST (於 winreg 模組中)
@anchor{library/winreg winreg REG_RESOURCE_LIST}@anchor{4c4c}
@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{4c4d}
@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{4c4e}
@deffn {資料} winreg.REG_RESOURCE_REQUIREMENTS_LIST

A hardware resource list.
@end deffn

@geindex REG_SZ (於 winreg 模組中)
@anchor{library/winreg winreg REG_SZ}@anchor{4c2e}
@deffn {資料} winreg.REG_SZ

A null-terminated string.
@end deffn

@node Registry Handle Objects,,常數<10>,winreg --- Windows 註冊表存取
@anchor{library/winreg handle-object}@anchor{4c1e}@anchor{library/winreg registry-handle-objects}@anchor{4c4f}
@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{4c23,,Close()} method on the object, or the @ref{4c22,,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{14d6,,__bool__()} -- thus

@example
if handle:
    print("Yes")
@end example

will print @code{Yes} if the handle is currently valid (has not been closed or
detached).

The object also support comparison semantics, so handle objects will compare
true if they both reference the same underlying Windows handle value.

Handle objects can be converted to an integer (e.g., using the built-in
@ref{19b,,int()} function), in which case the underlying Windows handle value is
returned.  You can also use the @ref{4625,,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{4c23}
@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{4625}
@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.

引發一個附帶引數 @code{key} 的@ref{1b70,,稽核事件} @code{winreg.PyHKEY.Detach}。
@end deffn

@geindex __enter__() (winreg.PyHKEY 的方法)
@geindex __exit__() (winreg.PyHKEY 的方法)
@anchor{library/winreg winreg PyHKEY __enter__}@anchor{4c50}
@deffn {方法} PyHKEY.__enter__ ()
@anchor{library/winreg winreg PyHKEY __exit__}@anchor{4c51}
@deffnx {方法} PyHKEY.__exit__ (*exc_info)

The HKEY object implements @ref{7dd,,__enter__()} and
@ref{1501,,__exit__()} and thus supports the context protocol for the
@ref{186,,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{186,,with} block.
@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 winsound --- Windows 的音效播放介面,,winreg --- Windows 註冊表存取,MS Windows 特有服務
@anchor{library/winsound doc}@anchor{4c52}@anchor{library/winsound module-winsound}@anchor{11d}@anchor{library/winsound translation-repo}@anchor{4c53}@anchor{library/winsound winsound-sound-playing-interface-for-windows}@anchor{4c54}
@subsection @code{winsound} --- Windows 的音效播放介面


@geindex module; winsound


__________________________________________________________________


@ref{11d,,winsound} 模組提供存取 Windows 平台所提供的基本音效播放機制。它包含數個函式與常數。

@geindex Beep() (於 winsound 模組中)
@anchor{library/winsound winsound Beep}@anchor{efc}
@deffn {函式} winsound.Beep (frequency, duration)

讓電腦的喇叭發出嗶聲。`frequency' 參數指定音效的頻率（以赫茲為單位），範圍必須介於 37 到 32,767 之間。`duration' 參數指定音效持續的時間（以毫秒為單位）。若系統無法讓喇叭發出嗶聲，則會引發 @ref{244,,RuntimeError}。
@end deffn

@geindex PlaySound() (於 winsound 模組中)
@anchor{library/winsound winsound PlaySound}@anchor{efe}
@deffn {函式} winsound.PlaySound (sound, flags)

呼叫平台 API 中底層的 @code{PlaySound()} 函式。`sound' 參數可以是檔案名稱、系統音效別名、作為 @ref{193,,bytes-like object} 的音訊資料，或 @code{None}。其直譯方式取決於 `flags' 的值，該值可以是以下所述常數的位元 OR 組合。若 `sound' 為 @code{None}，則會停止任何正在播放的波形音效。若系統回報錯誤，則會引發 @ref{244,,RuntimeError}。
@end deffn

@geindex MessageBeep() (於 winsound 模組中)
@anchor{library/winsound winsound MessageBeep}@anchor{efd}
@deffn {函式} winsound.MessageBeep (type=MB_OK)

呼叫平台 API 中底層的 @code{MessageBeep()} 函式。此函式會播放登錄檔中指定的音效。`type' 引數指定要播放的音效類型，可接受的值包括 @code{-1}、@code{MB_ICONASTERISK}、@code{MB_ICONEXCLAMATION}、@code{MB_ICONHAND}、@code{MB_ICONQUESTION} 與 @code{MB_OK}，這些皆會在下文中說明。數值 @code{-1} 會產生「簡單嗶聲」，當無法播放其他音效時即作為最終退路。若系統回報錯誤，則會引發 @ref{244,,RuntimeError}。
@end deffn

@geindex SND_FILENAME (於 winsound 模組中)
@anchor{library/winsound winsound SND_FILENAME}@anchor{4c55}
@deffn {資料} winsound.SND_FILENAME

`sound' 參數為 WAV 檔案名稱。請勿與 @ref{4c56,,SND_ALIAS} 同時使用。
@end deffn

@geindex SND_ALIAS (於 winsound 模組中)
@anchor{library/winsound winsound SND_ALIAS}@anchor{4c56}
@deffn {資料} winsound.SND_ALIAS

`sound' 參數為登錄檔中的音效關聯名稱。若登錄檔中找不到此名稱，則會播放系統預設音效，除非同時指定了 @ref{4c57,,SND_NODEFAULT}。若沒有註冊預設音效，則會引發 @ref{244,,RuntimeError}。請勿與 @ref{4c55,,SND_FILENAME} 同時使用。

所有 Win32 系統至少支援以下項目；大多數系統支援更多：


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

@ref{efe,,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
# 播放 Windows 的離開音效。
winsound.PlaySound("SystemExit", winsound.SND_ALIAS)

# 若有註冊預設音效，可能會播放該音效
# （因為 "*" 可能不是任何音效的註冊名稱）。
winsound.PlaySound("*", winsound.SND_ALIAS)
@end example
@end deffn

@geindex SND_LOOP (於 winsound 模組中)
@anchor{library/winsound winsound SND_LOOP}@anchor{4c58}
@deffn {資料} winsound.SND_LOOP

重複播放音效。必須同時使用 @ref{4c59,,SND_ASYNC} 旗標以避免阻塞。不能與 @ref{4c5a,,SND_MEMORY} 一同使用。
@end deffn

@geindex SND_MEMORY (於 winsound 模組中)
@anchor{library/winsound winsound SND_MEMORY}@anchor{4c5a}
@deffn {資料} winsound.SND_MEMORY

傳入 @ref{efe,,PlaySound()} 的 `sound' 參數是 WAV 檔案的記憶體映像，型別為 @ref{193,,bytes-like object}。

@cartouche
@quotation 備註 
此模組不支援從記憶體映像非同步播放音效，因此若同時使用本旗標與 @ref{4c59,,SND_ASYNC}，將引發 @ref{244,,RuntimeError}。
@end quotation
@end cartouche
@end deffn

@geindex SND_PURGE (於 winsound 模組中)
@anchor{library/winsound winsound SND_PURGE}@anchor{4c5b}
@deffn {資料} winsound.SND_PURGE

停止播放指定音效的所有實例。

@cartouche
@quotation 備註 
此旗標在現代 Windows 平台上不支援。
@end quotation
@end cartouche
@end deffn

@geindex SND_ASYNC (於 winsound 模組中)
@anchor{library/winsound winsound SND_ASYNC}@anchor{4c59}
@deffn {資料} winsound.SND_ASYNC

立即回傳，使音效可非同步播放。
@end deffn

@geindex SND_NODEFAULT (於 winsound 模組中)
@anchor{library/winsound winsound SND_NODEFAULT}@anchor{4c57}
@deffn {資料} winsound.SND_NODEFAULT

若找不到指定的音效，則不播放系統預設音效。
@end deffn

@geindex SND_NOSTOP (於 winsound 模組中)
@anchor{library/winsound winsound SND_NOSTOP}@anchor{4c5c}
@deffn {資料} winsound.SND_NOSTOP

不中斷目前正在播放的音效。
@end deffn

@geindex SND_NOWAIT (於 winsound 模組中)
@anchor{library/winsound winsound SND_NOWAIT}@anchor{4c5d}
@deffn {資料} winsound.SND_NOWAIT

若音效驅動程式正在忙碌，則立即回傳此。

@cartouche
@quotation 備註 
此旗標在現代 Windows 平台上不支援。
@end quotation
@end cartouche
@end deffn

@geindex SND_APPLICATION (於 winsound 模組中)
@anchor{library/winsound winsound SND_APPLICATION}@anchor{4c5e}
@deffn {資料} winsound.SND_APPLICATION

`sound' 參數為登錄檔中的應用程式特定別名。此旗標可與 @ref{4c56,,SND_ALIAS} 一同使用，以指定應用程式自訂的音效別名。
@end deffn

@geindex SND_SENTRY (於 winsound 模組中)
@anchor{library/winsound winsound SND_SENTRY}@anchor{4c5f}
@deffn {資料} winsound.SND_SENTRY

當音效被播放時，會觸發 SoundSentry 事件。


在 3.14 版被加入.

@end deffn

@geindex SND_SYNC (於 winsound 模組中)
@anchor{library/winsound winsound SND_SYNC}@anchor{4c60}
@deffn {資料} winsound.SND_SYNC

音效會同步播放。這是預設行為。


在 3.14 版被加入.

@end deffn

@geindex SND_SYSTEM (於 winsound 模組中)
@anchor{library/winsound winsound SND_SYSTEM}@anchor{4c61}
@deffn {資料} winsound.SND_SYSTEM

將音效指派給系統通知音效的音訊工作階段 (audio session)。


在 3.14 版被加入.

@end deffn

@geindex MB_ICONASTERISK (於 winsound 模組中)
@anchor{library/winsound winsound MB_ICONASTERISK}@anchor{4c62}
@deffn {資料} winsound.MB_ICONASTERISK

播放 @code{SystemDefault} 音效。
@end deffn

@geindex MB_ICONEXCLAMATION (於 winsound 模組中)
@anchor{library/winsound winsound MB_ICONEXCLAMATION}@anchor{4c63}
@deffn {資料} winsound.MB_ICONEXCLAMATION

播放 @code{SystemExclamation} 音效。
@end deffn

@geindex MB_ICONHAND (於 winsound 模組中)
@anchor{library/winsound winsound MB_ICONHAND}@anchor{4c64}
@deffn {資料} winsound.MB_ICONHAND

播放 @code{SystemHand} 音效。
@end deffn

@geindex MB_ICONQUESTION (於 winsound 模組中)
@anchor{library/winsound winsound MB_ICONQUESTION}@anchor{4c65}
@deffn {資料} winsound.MB_ICONQUESTION

播放 @code{SystemQuestion} 音效。
@end deffn

@geindex MB_OK (於 winsound 模組中)
@anchor{library/winsound winsound MB_OK}@anchor{4c66}
@deffn {資料} winsound.MB_OK

播放 @code{SystemDefault} 音效。
@end deffn

@geindex MB_ICONERROR (於 winsound 模組中)
@anchor{library/winsound winsound MB_ICONERROR}@anchor{4c67}
@deffn {資料} winsound.MB_ICONERROR

播放 @code{SystemHand} 音效。


在 3.14 版被加入.

@end deffn

@geindex MB_ICONINFORMATION (於 winsound 模組中)
@anchor{library/winsound winsound MB_ICONINFORMATION}@anchor{4c68}
@deffn {資料} winsound.MB_ICONINFORMATION

播放 @code{SystemDefault} 音效。


在 3.14 版被加入.

@end deffn

@geindex MB_ICONSTOP (於 winsound 模組中)
@anchor{library/winsound winsound MB_ICONSTOP}@anchor{4c69}
@deffn {資料} winsound.MB_ICONSTOP

播放 @code{SystemHand} 音效。


在 3.14 版被加入.

@end deffn

@geindex MB_ICONWARNING (於 winsound 模組中)
@anchor{library/winsound winsound MB_ICONWARNING}@anchor{4c6a}
@deffn {資料} winsound.MB_ICONWARNING

播放 @code{SystemExclamation} 音效。


在 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 特有服務,模組命令列介面,MS Windows 特有服務,Python 標準函式庫 Standard Library
@anchor{library/unix doc}@anchor{4c6b}@anchor{library/unix translation-repo}@anchor{4c6c}@anchor{library/unix unix}@anchor{4c6d}@anchor{library/unix unix-specific-services}@anchor{4c6e}
@section Unix 特有服務


此章節所描述的模組 (module) 提供了針對 Unix 作業系統獨有特性的介面，或在某些情況下可用於其他 Unix 變形版本。以下為概述：

@menu
* shlex: shlex --- 簡單的語法分析. 簡單的語法分析
* posix: posix --- 最常見的 POSIX 系統呼叫. 最常見的 POSIX 系統呼叫
* pwd: pwd --- 密碼資料庫. 密碼資料庫
* grp: grp --- 群組資料庫. 群組資料庫
* termios: termios --- POSIX 風格 tty 控制. POSIX 風格 tty 控制
* tty: tty --- 終端機控制函式. 終端機控制函式
* pty: pty --- 偽終端工具. 偽終端工具
* fcntl: fcntl --- fcntl 和 ioctl 系統呼叫. fcntl 和 ioctl 系統呼叫
* resource: resource --- 資源使用資訊. 資源使用資訊
* syslog: syslog --- Unix syslog 函式庫例程. Unix syslog 函式庫例程

@end menu

@node shlex --- 簡單的語法分析,posix --- 最常見的 POSIX 系統呼叫,,Unix 特有服務
@anchor{library/shlex doc}@anchor{4c6f}@anchor{library/shlex module-shlex}@anchor{c9}@anchor{library/shlex shlex-simple-lexical-analysis}@anchor{4c70}
@subsection @code{shlex} --- 簡單的語法分析


@geindex module; shlex

`原始碼：'Lib/shlex.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/shlex.py}


__________________________________________________________________


The @ref{ec3,,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.

@ref{c9,,shlex} 模組定義了以下函式：

@geindex split() (於 shlex 模組中)
@anchor{library/shlex shlex split}@anchor{757}
@deffn {函式} shlex.split (s, comments=False, posix=True)

Split the string `s' using shell-like syntax. If `comments' is @ref{d23,,False}
(the default), the parsing of comments in the given string will be disabled
(setting the @ref{4c71,,commenters} attribute of the
@ref{ec3,,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{758,,sys.stdin}.

@end deffn

@geindex join() (於 shlex 模組中)
@anchor{library/shlex shlex join}@anchor{c13}
@deffn {函式} shlex.join (split_command)

Concatenate the tokens of the list `split_command' and return a string.
This function is the inverse of @ref{757,,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{57c,,quote()}).


在 3.8 版被加入.

@end deffn

@geindex quote() (於 shlex 模組中)
@anchor{library/shlex shlex quote}@anchor{57c}
@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{360a}
@cartouche
@quotation 警告 
The @code{shlex} module is `only designed for Unix shells'.

The @ref{57c,,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{d79,,subprocess.run()} with @code{shell=False}.
@end quotation
@end cartouche

This idiom would be unsafe:

@example
>>> filename = 'somefile; rm -rf ~'
>>> command = 'ls -l @{@}'.format(filename)
>>> print(command)  # executed by a shell: boom!
ls -l somefile; rm -rf ~
@end example

@ref{57c,,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{757,,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


在 3.3 版被加入.

@end deffn

@ref{c9,,shlex} 模組定義了以下類別：

@geindex shlex (shlex 中的類別)
@anchor{library/shlex shlex shlex}@anchor{ec3}
@deffn {類別} shlex.shlex (instream=None, infile=None, posix=False, punctuation_chars=False)

A @ref{ec3,,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{1f33,,read()} and @ref{1f6d,,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{4c72,,infile} attribute.  If the `instream'
argument is omitted or equal to @code{sys.stdin}, this second argument
defaults to "stdin".  The `posix' argument defines the operational mode:
when `posix' is not true (default), the @ref{ec3,,shlex} instance will
operate in compatibility mode.  When operating in POSIX mode,
@ref{ec3,,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{4c73,,wordchars} attribute that appear in
`punctuation_chars' will be removed from @ref{4c73,,wordchars}.  See
@ref{ec4,,Improved Compatibility with Shells} for more information. `punctuation_chars'
can be set only upon @ref{ec3,,shlex} instance creation and can't be
modified later.


在 3.6 版的變更: 新增 `punctuation_chars' 參數。

@end deffn


@subsubheading 也參考



@table @asis

@item @ref{26,,configparser} 模組

Parser for configuration files similar to the Windows @code{.ini} files.
@end table


@menu
* shlex 物件:: 
* Parsing Rules:: 
* Improved Compatibility with Shells:: 

@end menu

@node shlex 物件,Parsing Rules,,shlex --- 簡單的語法分析
@anchor{library/shlex id1}@anchor{4c74}@anchor{library/shlex shlex-objects}@anchor{4c75}
@subsubsection shlex 物件


@ref{ec3,,shlex} 實例有以下方法：

@geindex get_token() (shlex.shlex 的方法)
@anchor{library/shlex shlex shlex get_token}@anchor{4c76}
@deffn {方法} shlex.get_token ()

Return a token.  If tokens have been stacked using @ref{4c77,,push_token()}, pop a
token off the stack.  Otherwise, read one from the input stream.  If reading
encounters an immediate end-of-file, @ref{4c78,,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{4c77}
@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{4c79}
@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{4c7a}
@deffn {方法} shlex.sourcehook (filename)

When @ref{ec3,,shlex} detects a source request (see @ref{4c7b,,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{315,,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{501,,close()} method of the sourced input stream when it returns
EOF.

For more explicit control of source stacking, use the @ref{4c7c,,push_source()} and
@ref{4c7d,,pop_source()} methods.
@end deffn

@geindex push_source() (shlex.shlex 的方法)
@anchor{library/shlex shlex shlex push_source}@anchor{4c7c}
@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{4c7a,,sourcehook()} method.
@end deffn

@geindex pop_source() (shlex.shlex 的方法)
@anchor{library/shlex shlex shlex pop_source}@anchor{4c7d}
@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{4c7e}
@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 @ref{c9,,shlex} users to generate error
messages in the standard, parseable format understood by Emacs and other Unix
tools.
@end deffn

Instances of @ref{ec3,,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{4c71}
@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{4c73}
@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{1c7f,,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{4c7f,,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{4c80}
@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{4c81}
@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{4c82}
@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{4c83}
@deffn {屬性} shlex.escapedquotes

Characters in @ref{4c82,,quotes} that will interpret escape characters defined in
@ref{4c81,,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{4c7f}
@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{ec3,,shlex}, getting
tokens in a similar way to shell arguments.  When used in combination with
@ref{1c7f,,punctuation_chars}, tokens will be split on whitespace in addition to
those characters.


在 3.8 版的變更: The @ref{1c7f,,punctuation_chars} attribute was made compatible with the
@ref{4c7f,,whitespace_split} attribute.

@end deffn

@geindex infile (shlex.shlex 的屬性)
@anchor{library/shlex shlex shlex infile}@anchor{4c72}
@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{4c84}
@deffn {屬性} shlex.instream

The input stream from which this @ref{ec3,,shlex} instance is reading
characters.
@end deffn

@geindex source (shlex.shlex 的屬性)
@anchor{library/shlex shlex shlex source}@anchor{4c7b}
@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{501,,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{4c85}
@deffn {屬性} shlex.debug

If this attribute is numeric and @code{1} or more, a @ref{ec3,,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{4c86}
@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{4c87}
@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{4c78}
@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{1c7f}
@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.


在 3.6 版被加入.

@end deffn

@node Parsing Rules,Improved Compatibility with Shells,shlex 物件,shlex --- 簡單的語法分析
@anchor{library/shlex parsing-rules}@anchor{4c88}@anchor{library/shlex shlex-parsing-rules}@anchor{4c89}
@subsubsection Parsing Rules


When operating in non-POSIX mode, @ref{ec3,,shlex} will try to obey to the
following rules.


@itemize *

@item 
Quote characters are not recognized within words (@code{Do"Not"Separate} is
parsed as the single word @code{Do"Not"Separate});

@item 
Escape characters are not recognized;

@item 
Enclosing characters in quotes preserve the literal value of all characters
within the quotes;

@item 
Closing quotes separate words (@code{"Do"Separate} is parsed as @code{"Do"} and
@code{Separate});

@item 
If @ref{4c7f,,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{ec3,,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{ec3,,shlex} will try to obey to the
following parsing rules.


@itemize *

@item 
Quotes are stripped out, and do not separate words (@code{"Do"Not"Separate"} is
parsed as the single word @code{DoNotSeparate});

@item 
Non-quoted escape characters (e.g. @code{'\'}) preserve the literal value of the
next character that follows;

@item 
Enclosing characters in quotes which are not part of
@ref{4c83,,escapedquotes} (e.g. @code{"'"}) preserve the literal value
of all characters within the quotes;

@item 
Enclosing characters in quotes which are part of
@ref{4c83,,escapedquotes} (e.g. @code{'"'}) preserves the literal value
of all characters within the quotes, with the exception of the characters
mentioned in @ref{4c81,,escape}.  The escape characters retain its
special meaning only when followed by the quote in use, or the escape
character itself. Otherwise the escape character will be considered a
normal character.

@item 
EOF is signaled with a @ref{87e,,None} value;

@item 
Quoted empty strings (@code{'@w{'}}) are allowed.
@end itemize

@node Improved Compatibility with Shells,,Parsing Rules,shlex --- 簡單的語法分析
@anchor{library/shlex improved-compatibility-with-shells}@anchor{4c8a}@anchor{library/shlex improved-shell-compatibility}@anchor{ec4}
@subsubsection Improved Compatibility with Shells



在 3.6 版被加入.


The @ref{c9,,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{4c73,,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{4c7f,,whitespace_split} when using
@ref{1c7f,,punctuation_chars}, which will negate
@ref{4c73,,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{ec3,,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 --- 最常見的 POSIX 系統呼叫,pwd --- 密碼資料庫,shlex --- 簡單的語法分析,Unix 特有服務
@anchor{library/posix doc}@anchor{4c8b}@anchor{library/posix module-posix}@anchor{b2}@anchor{library/posix posix-the-most-common-posix-system-calls}@anchor{4c8c}@anchor{library/posix translation-repo}@anchor{4c8d}
@subsection @code{posix} --- 最常見的 POSIX 系統呼叫


@geindex module; posix


__________________________________________________________________


該模組提供對由 C 標準和 POSIX 標準（一種偽裝的 Unix 介面）所標準化的作業系統功能的存取。

@ref{2006,,可用性}: Unix.

@geindex module（模組）;os

`不要直接引入此模組。'請改為引入 @ref{a5,,os} 模組，它提供了此介面的`可移植 (portable)' 版本。在 Unix 上，@ref{a5,,os} 模組提供了 @ref{b2,,posix} 介面的超集 (superset)。在非 Unix 作業系統上，@ref{b2,,posix} 模組不可用，但始終可以通過 @ref{a5,,os} 介面使用一個子集。一旦 @ref{a5,,os} 有被引入，使用它代替 @ref{b2,,posix} `不會有'性能損失。此外，@ref{a5,,os} 提供了一些額外的功能，例如當 @code{os.environ} 中的條目更改時自動呼叫 @ref{25b,,putenv()}。

錯誤會以例外的形式被回報；常見的例外是因為型別錯誤而給出的，而系統呼叫回報的錯誤會引發 @ref{2c0,,OSError}。

@menu
* 對大檔案 (Large File) 的支援: 對大檔案 Large File 的支援. 
* 值得注意的模組內容:: 

@end menu

@node 對大檔案 Large File 的支援,值得注意的模組內容,,posix --- 最常見的 POSIX 系統呼叫
@anchor{library/posix large-file-support}@anchor{4c8e}@anchor{library/posix posix-large-files}@anchor{4c8f}
@subsubsection 對大檔案 (Large File) 的支援


@geindex large files（大型檔案）
@geindex file（檔案）;large files（大型檔案）

一些作業系統（包括 AIX 和 Solaris）支援來自 C 程式模型且大於 2 GiB 的檔案，其中 int 和 long 是 32-bit（32 位元）的值。這通常透過將相關大小和偏移量 (offset) 種類定義為 64-bit 值來實作。此類檔案有時被稱為「大檔案 (`large files')」。

當 @code{off_t} 的大小大於 long 且 long long 的大小至少與 @code{off_t} 相同時，對大檔案的支援會被啟用。可能需要使用某些編譯器旗標來配置和編譯 Python 以啟用此模式。例如，對於 Solaris 2.6 和 2.7，你需要執行如下操作：

@example
CFLAGS="`getconf LFS_CFLAGS`" OPT="-g -O2 $CFLAGS" \
        ./configure
@end example

在支援大檔案的 Linux 系統上，這可能有效：

@example
CFLAGS='-D_LARGEFILE64_SOURCE -D_FILE_OFFSET_BITS=64' OPT="-g -O2 $CFLAGS" \
        ./configure
@end example

@node 值得注意的模組內容,,對大檔案 Large File 的支援,posix --- 最常見的 POSIX 系統呼叫
@anchor{library/posix notable-module-contents}@anchor{4c90}@anchor{library/posix posix-contents}@anchor{4c91}
@subsubsection 值得注意的模組內容


除了 @ref{a5,,os} 模組說明文件中描述的許多函式外，@ref{b2,,posix} 還定義了以下資料項目：

@geindex environ (於 posix 模組中)
@anchor{library/posix posix environ}@anchor{4c92}
@deffn {資料} posix.environ

表示直譯器啟動時的字串環境的字典。鍵和值在 Unix 上是位元組，在 Windows 上是 str。例如，@code{environ[b'HOME']}（Windows 上為 @code{environ['HOME']}）是你的主目錄的路徑名，等同於 C 語言中的 @code{getenv("HOME")}。

修改這個字典不會影響由 @ref{2ecb,,execv()}、@ref{319,,popen()} 或 @ref{1652,,system()} 傳遞的字串環境；如果你需要更改環境，請將 @code{environ} 傳遞給 @ref{12fa,,execve()} 或將變數賦值和匯出陳述句新增到 @ref{1652,,system()} 或 @ref{319,,popen()} 的指令字串中。


在 3.2 版的變更: 在 Unix 上，鍵和值是位元組。


@cartouche
@quotation 備註 
@ref{a5,,os} 模組提供了 @code{environ} 的替代實作，會在修改時更新環境。另請注意，更新 @ref{259,,os.environ} 將使該字典變成過時的。建議使用 @ref{a5,,os} 模組版本，而不是直接存取 @ref{b2,,posix} 模組。
@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 --- 群組資料庫,posix --- 最常見的 POSIX 系統呼叫,Unix 特有服務
@anchor{library/pwd doc}@anchor{4c93}@anchor{library/pwd module-pwd}@anchor{b7}@anchor{library/pwd pwd-the-password-database}@anchor{4c94}@anchor{library/pwd translation-repo}@anchor{4c95}
@subsection @code{pwd} --- 密碼資料庫


@geindex module; pwd


__________________________________________________________________


此模組提供對 Unix 使用者帳戶和密碼資料庫的存取介面。它適用於所有 Unix 版本。

@ref{2006,,可用性}: Unix, not WASI, not iOS.

密碼資料庫條目被報告為類似元組的物件 (tuple-like object)，其屬性會對應於 @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

數值的使用者 ID

@item

3

@tab

@code{pw_gid}

@tab

數值的群組 ID

@item

4

@tab

@code{pw_gecos}

@tab

使用者名稱或註解欄位

@item

5

@tab

@code{pw_dir}

@tab

使用者主目錄 (home directory)

@item

6

@tab

@code{pw_shell}

@tab

使用者命令直譯器

@end multitable


uid 和 gid 項目為整數，其他項目都是字串。如果找不到請求的條目，則會引發 @ref{5df,,KeyError}。

@cartouche
@quotation 備註 
在傳統的 Unix 中，@code{pw_passwd} 欄位通常包含一個使用 DES 衍生演算法加密的密碼。然而，大多數現代 Unix 是使用所謂的 `shadow password' 系統。在那些 Unix 上，`pw_passwd' 欄位僅包含一個星號 (@code{'*'}) 或字母 @code{'x'}，其中加密密碼儲存在非全域可讀的 (not world readable) @code{/etc/shadow} 檔案中。`pw_passwd' 欄位是否包含任何有用的內容取決於系統。
@end quotation
@end cartouche

它定義了以下項目：

@geindex getpwuid() (於 pwd 模組中)
@anchor{library/pwd pwd getpwuid}@anchor{1cda}
@deffn {函式} pwd.getpwuid (uid)

回傳給定數值使用者 ID 的密碼資料庫條目。
@end deffn

@geindex getpwnam() (於 pwd 模組中)
@anchor{library/pwd pwd getpwnam}@anchor{35fa}
@deffn {函式} pwd.getpwnam (name)

回傳給定使用者名稱的密碼資料庫條目。
@end deffn

@geindex getpwall() (於 pwd 模組中)
@anchor{library/pwd pwd getpwall}@anchor{4c96}
@deffn {函式} pwd.getpwall ()

以任意順序回傳所有可用密碼資料庫條目的 list。
@end deffn


@subsubheading 也參考



@table @asis

@item @ref{6a,,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 --- 群組資料庫,termios --- POSIX 風格 tty 控制,pwd --- 密碼資料庫,Unix 特有服務
@anchor{library/grp doc}@anchor{4c97}@anchor{library/grp grp-the-group-database}@anchor{4c98}@anchor{library/grp module-grp}@anchor{6a}@anchor{library/grp translation-repo}@anchor{4c99}
@subsection @code{grp} --- 群組資料庫


@geindex module; grp


__________________________________________________________________


該模組提供對 Unix 群組資料庫的存取， 所有 Unix 版本皆可使用。

@ref{2006,,可用性}: Unix, not WASI, not Android, not iOS.

群組資料庫條目以類似 tuple 物件的方式報傳入， 其屬性對應於 @code{group} 結構的成員（屬性欄位如下， 請參閱 @code{<grp.h>}）：


@multitable {xxxxxxxxx} {xxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

索引

@tab

屬性

@tab

含義

@item

0

@tab

gr_name

@tab

群組名稱

@item

1

@tab

gr_passwd

@tab

（被加密後的）群組密碼；大部分情況下是空的

@item

2

@tab

gr_gid

@tab

群組的數字 ID

@item

3

@tab

gr_mem

@tab

所有群組成員的使用者名稱

@end multitable


gid 是整數，name 和 password 是字串， 而 member list 是字串串列。（請注意， 根據密碼資料庫， 大多數使用者並未被明確列為其所在群組的成員。 請檢查這兩個資料庫，以取得完整的成員資訊。 另外請注意，以 @code{+} 或 @code{-} 開頭的 @code{gr_name} 很可能是 YP/NIS 參照，可能無法透過 @ref{35f9,,getgrnam()} 或 @ref{f1d,,getgrgid()} 取得）。

它定義了以下項目：

@geindex getgrgid() (於 grp 模組中)
@anchor{library/grp grp getgrgid}@anchor{f1d}
@deffn {函式} grp.getgrgid (id)

回傳給定群組 ID 的群組資料庫條目。 @ref{5df,,KeyError} 會在找不到所要求的條目時被引發。


在 3.10 版的變更: @ref{198,,TypeError} 會在非整數的引數如浮點數或字串被傳入時被引發。

@end deffn

@geindex getgrnam() (於 grp 模組中)
@anchor{library/grp grp getgrnam}@anchor{35f9}
@deffn {函式} grp.getgrnam (name)

回傳給定群組名稱的群組資料庫條目。 @ref{5df,,KeyError} 會在找不到所要求的條目時引發。
@end deffn

@geindex getgrall() (於 grp 模組中)
@anchor{library/grp grp getgrall}@anchor{1856}
@deffn {函式} grp.getgrall ()

以任意順序傳回所有可用群組條目的串列。
@end deffn


@subsubheading 也參考



@table @asis

@item @ref{b7,,pwd} 模組

使用者資料庫的介面，與此類似。
@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 風格 tty 控制,tty --- 終端機控制函式,grp --- 群組資料庫,Unix 特有服務
@anchor{library/termios doc}@anchor{4c9a}@anchor{library/termios module-termios}@anchor{e7}@anchor{library/termios termios-posix-style-tty-control}@anchor{4c9b}@anchor{library/termios translation-repo}@anchor{4c9c}
@subsection @code{termios} --- POSIX 風格 tty 控制


@geindex module; termios

@geindex POSIX;I/O control（I/O 控制）
@geindex tty;I/O control（I/O 控制）


__________________________________________________________________


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{2006,,可用性}: 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{13c4,,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.

此模組定義了以下函式：

@geindex tcgetattr() (於 termios 模組中)
@anchor{library/termios termios tcgetattr}@anchor{1942}
@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 @ref{e7,,termios} module.
@end deffn

@geindex tcsetattr() (於 termios 模組中)
@anchor{library/termios termios tcsetattr}@anchor{19bb}
@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{1942,,tcgetattr()}.  The `when' argument
determines when the attributes are changed:

@geindex TCSANOW (於 termios 模組中)
@anchor{library/termios termios TCSANOW}@anchor{4c9d}
@deffn {資料} termios.TCSANOW

Change attributes immediately.
@end deffn

@geindex TCSADRAIN (於 termios 模組中)
@anchor{library/termios termios TCSADRAIN}@anchor{4c9e}
@deffn {資料} termios.TCSADRAIN

Change attributes after transmitting all queued output.
@end deffn

@geindex TCSAFLUSH (於 termios 模組中)
@anchor{library/termios termios TCSAFLUSH}@anchor{4c9f}
@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{4ca0}
@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{4ca1}
@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{4ca2}
@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{4ca3}
@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{4ca4}
@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}.


在 3.11 版被加入.

@end deffn

@geindex tcsetwinsize() (於 termios 模組中)
@anchor{library/termios termios tcsetwinsize}@anchor{4ca5}
@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{4ca4,,tcgetwinsize()}. Requires at least one of the pairs
(@code{termios.TIOCGWINSZ}, @code{termios.TIOCSWINSZ});
(@code{termios.TIOCGSIZE}, @code{termios.TIOCSSIZE}) to be defined.


在 3.11 版被加入.

@end deffn


@subsubheading 也參考



@table @asis

@item @ref{106,,tty} 模組

Convenience functions for common terminal control operations.
@end table


@menu
* 範例: 範例<50>. 

@end menu

@node 範例<50>,,,termios --- POSIX 風格 tty 控制
@anchor{library/termios example}@anchor{4ca6}@anchor{library/termios termios-example}@anchor{4ca7}
@subsubsection 範例


Here's a function that prompts for a password with echoing turned off.  Note the
technique using a separate @ref{1942,,tcgetattr()} call and a @ref{8f0,,try} ...
@ref{1b0,,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 --- 終端機控制函式,pty --- 偽終端工具,termios --- POSIX 風格 tty 控制,Unix 特有服務
@anchor{library/tty doc}@anchor{4ca8}@anchor{library/tty module-tty}@anchor{106}@anchor{library/tty translation-repo}@anchor{4ca9}@anchor{library/tty tty-terminal-control-functions}@anchor{4caa}
@subsection @code{tty} --- 終端機控制函式


@geindex module; tty

`原始碼：'Lib/tty.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/tty.py}


__________________________________________________________________


@ref{106,,tty} 模組定義了將 tty 放入 cbreak 和 raw 模式的函式。

@ref{2006,,可用性}: Unix.

因為它需要 @ref{e7,,termios} 模組，所以只能在 Unix 上執行。

@ref{106,,tty} 模組定義了以下函式：

@geindex cfmakeraw() (於 tty 模組中)
@anchor{library/tty tty cfmakeraw}@anchor{1993}
@deffn {函式} tty.cfmakeraw (mode)

將 tty 屬性串列 `mode' 轉換成原始模式下的 tty 屬性串列，這個串列就像 @ref{1942,,termios.tcgetattr()} 所回傳的一樣。


在 3.12 版被加入.

@end deffn

@geindex cfmakecbreak() (於 tty 模組中)
@anchor{library/tty tty cfmakecbreak}@anchor{1945}
@deffn {函式} tty.cfmakecbreak (mode)

將 tty 屬性串列 `mode' 轉換成 cbreak 模式下的 tty 屬性串列，這個串列就像 @ref{1942,,termios.tcgetattr()} 所回傳的一樣。

這會清除 `mode' 中的 @code{ECHO} 和 @code{ICANON} 本地模式旗標，並將最小輸入設定為 1 位元組，且無延遲。


在 3.12 版被加入.



在 3.12.2 版的變更: 不再清除 @code{ICRNL} 標記。這符合 Linux 和 macOS 的 @code{stty cbreak} 行為，也符合 @ref{1944,,setcbreak()} 歷來的做法。

@end deffn

@geindex setraw() (於 tty 模組中)
@anchor{library/tty tty setraw}@anchor{1992}
@deffn {函式} tty.setraw (fd, when=termios.TCSAFLUSH)

將檔案描述器 `fd' 的模式更改為 raw。如果 `when' 被省略，則預設為 @ref{4c9f,,termios.TCSAFLUSH}，並傳遞給 @ref{19bb,,termios.tcsetattr()}。@ref{1942,,termios.tcgetattr()} 的回傳值會在設定 `fd' 模式為 raw 之前先儲存起來。此函式回傳這個值。


在 3.12 版的變更: 現在的回傳值為原本的 tty 屬性，而不是 @code{None}。

@end deffn

@geindex setcbreak() (於 tty 模組中)
@anchor{library/tty tty setcbreak}@anchor{1944}
@deffn {函式} tty.setcbreak (fd, when=termios.TCSAFLUSH)

將檔案描述器 `fd' 的模式更改為 cbreak。如果 `when' 被省略，則預設為 @ref{4c9f,,termios.TCSAFLUSH}，並傳遞給 @ref{19bb,,termios.tcsetattr()}。@ref{1942,,termios.tcgetattr()} 的回傳值會在設定 `fd' 模式為 raw 之前先儲存起來。此函式回傳這個值。

這會清除 @code{ECHO} 和 @code{ICANON} 本地模式旗標，並將最小輸入設定為 1 位元組，且無延遲。


在 3.12 版的變更: 現在的回傳值為原本的 tty 屬性，而不是 @code{None}。



在 3.12.2 版的變更: 不再清除 @code{ICRNL} 旗標。這恢復了 Python 3.11 及更早版本的行為，也符合 Linux、macOS 及 BSD 在他們的 @code{stty(1)} man 頁面中描述的 cbreak 模式。

@end deffn


@subsubheading 也參考



@table @asis

@item @ref{e7,,termios} 模組

低階終端機控制介面。
@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 --- fcntl 和 ioctl 系統呼叫,tty --- 終端機控制函式,Unix 特有服務
@anchor{library/pty doc}@anchor{4cab}@anchor{library/pty module-pty}@anchor{b6}@anchor{library/pty pty-pseudo-terminal-utilities}@anchor{4cac}@anchor{library/pty translation-repo}@anchor{4cad}
@subsection @code{pty} --- 偽終端工具


@geindex module; pty

`原始碼：'Lib/pty.py@footnote{https://github.com/python/cpython/tree/3.14/Lib/pty.py}


__________________________________________________________________


The @ref{b6,,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{2006,,可用性}: Unix.

Pseudo-terminal handling is highly platform dependent. This code is mainly
tested on Linux, FreeBSD, and macOS (it is supposed to work on other POSIX
platforms but it's not been thoroughly tested).

@ref{b6,,pty} 模組定義了以下函式：

@geindex fork() (於 pty 模組中)
@anchor{library/pty pty fork}@anchor{1a14}
@deffn {函式} pty.fork ()

Fork. Connect the child's controlling terminal to a pseudo-terminal. Return
value is @code{(pid, fd)}. Note that the child  gets `pid' 0, and the `fd' is
`invalid'. The parent's return value is the `pid' of the child, and `fd' is a
file descriptor connected to the child's controlling terminal (and also to the
child's standard input and output).

@cartouche
@quotation 警告 
On macOS the use of this function is unsafe when mixed with using
higher-level system APIs, and that includes using @ref{111,,urllib.request}.
@end quotation
@end cartouche
@end deffn

@geindex openpty() (於 pty 模組中)
@anchor{library/pty pty openpty}@anchor{300}
@deffn {函式} pty.openpty ()

Open a new pseudo-terminal pair, using @ref{2f0c,,os.openpty()} if possible, or
emulation code for generic Unix systems. Return a pair of file descriptors
@code{(master, slave)}, for the master and the slave end, respectively.
@end deffn

@geindex spawn() (於 pty 模組中)
@anchor{library/pty pty spawn}@anchor{117d}
@deffn {函式} pty.spawn (argv[, master_read[, stdin_read]])

Spawn a process, and connect its controlling terminal with the current
process's standard io. This is often used to baffle programs which insist on
reading from the controlling terminal. It is expected that the process
spawned behind the pty will eventually terminate, and when it does `spawn'
will return.

A loop copies STDIN of the current process to the child and data received
from the child to STDOUT of the current process. It is not signaled to the
child if STDIN of the current process closes down.

The functions `master_read' and `stdin_read' are passed a file descriptor
which they should read from, and they should always return a byte string. In
order to force spawn to return before the child process exits an
empty byte array should be returned to signal end of file.

The default implementation for both functions will read and return up to 1024
bytes each time the function is called. The `master_read' callback is passed
the pseudoterminal’s master file descriptor to read output from the child
process, and `stdin_read' is passed file descriptor 0, to read from the
parent process's standard input.

Returning an empty byte string from either callback is interpreted as an
end-of-file (EOF) condition, and that callback will not be called after
that. If `stdin_read' signals EOF the controlling terminal can no longer
communicate with the parent process OR the child process. Unless the child
process will quit without any input, `spawn' will then loop forever. If
`master_read' signals EOF the same behavior results (on linux at least).

Return the exit status value from @ref{f95,,os.waitpid()} on the child process.

@ref{b0e,,os.waitstatus_to_exitcode()} can be used to convert the exit status into
an exit code.

引發一個附帶引數 @code{argv} 的@ref{1b70,,稽核事件} @code{pty.spawn}。


在 3.4 版的變更: @ref{117d,,spawn()} now returns the status value from @ref{f95,,os.waitpid()}
on the child process.

@end deffn

@menu
* 範例: 範例<51>. 

@end menu

@node 範例<51>,,,pty --- 偽終端工具
@anchor{library/pty example}@anchor{4cae}
@subsubsection 範例


The following program acts like the Unix command @code{script(1)@footnote{https://manpages.debian.org/script(1)}}, using a
pseudo-terminal to record all input and output of a terminal session in a
"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 --- fcntl 和 ioctl 系統呼叫,resource --- 資源使用資訊,pty --- 偽終端工具,Unix 特有服務
@anchor{library/fcntl doc}@anchor{4caf}@anchor{library/fcntl fcntl-the-fcntl-and-ioctl-system-calls}@anchor{4cb0}@anchor{library/fcntl module-fcntl}@anchor{5d}@anchor{library/fcntl translation-repo}@anchor{4cb1}
@subsection @code{fcntl} --- @code{fcntl} 和 @code{ioctl} 系統呼叫


@geindex module; fcntl

@geindex UNIX;file control（檔案控制）
@geindex UNIX;I/O control（I/O 控制）


__________________________________________________________________


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{2006,,可用性}: 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{500,,io.IOBase} object, such as @code{sys.stdin}
itself, which provides a @ref{2b7e,,fileno()} that returns a genuine file
descriptor.


在 3.3 版的變更: Operations in this module used to raise an @ref{124e,,IOError} where they now
raise an @ref{2c0,,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{bf5,,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 @ref{5d,,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.


這個模組定義了以下函式：

@geindex fcntl() (於 fcntl 模組中)
@anchor{library/fcntl fcntl fcntl}@anchor{17d0}
@deffn {函式} fcntl.fcntl (fd, cmd, arg=0, /)

Perform the operation `cmd' on file descriptor `fd' (file objects providing
a @ref{2b7e,,fileno()} method are accepted as well).  The values used
for `cmd' are operating system dependent, and are available as constants
in the @ref{5d,,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{193,,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{1477,,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{192,,bytes} object.
The length of the returned object will be the same as the length of the
`arg' argument. This is limited to 1024 bytes.

If the @code{fcntl()} call fails, an @ref{2c0,,OSError} is raised.

@cartouche
@quotation 備註 
If the type or the size of `arg' does not match the type or size
of the argument of the operation (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 1024 bytes),
this is most likely to result in a segmentation violation or
a more subtle data corruption.
@end quotation
@end cartouche

引發一個附帶引數 @code{fd}、@code{cmd}、@code{arg} 的@ref{1b70,,稽核事件} @code{fcntl.fcntl}。


在 3.14 版的變更: Add support of arbitrary @ref{193,,bytes-like objects},
not only @ref{192,,bytes}.

@end deffn

@geindex ioctl() (於 fcntl 模組中)
@anchor{library/fcntl fcntl ioctl}@anchor{166f}
@deffn {函式} fcntl.ioctl (fd, request, arg=0, mutate_flag=True, /)

This function is identical to the @ref{17d0,,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{e7,,termios} module, under the same names as used in
the relevant C header files.

The parameter `arg' can be an integer, a @ref{193,,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{17d0,,fcntl()}
function.

If `arg' supports the read-write buffer interface (like @ref{343,,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 @ref{166f,,ioctl()} and copied back
into the supplied buffer.

If the @code{ioctl()} call fails, an @ref{2c0,,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 1024 bytes,
or the size of the mutable bytes-like object is too small),
this is most likely to result in a segmentation violation or
a more subtle data corruption.
@end quotation
@end cartouche

範例：

@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

引發一個附帶引數 @code{fd}、@code{request}、@code{arg} 的@ref{1b70,,稽核事件} @code{fcntl.ioctl}。


在 3.14 版的變更: The GIL is always released during a system call.
System calls failing with EINTR are automatically retried.

@end deffn

@geindex flock() (於 fcntl 模組中)
@anchor{library/fcntl fcntl flock}@anchor{4615}
@deffn {函式} fcntl.flock (fd, operation, /)

Perform the lock operation `operation' on file descriptor `fd' (file objects providing
a @ref{2b7e,,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{2c0,,OSError} exception is raised.

引發一個附帶引數 @code{fd}、@code{operation} 的@ref{1b70,,稽核事件} @code{fcntl.flock}。
@end deffn

@geindex lockf() (於 fcntl 模組中)
@anchor{library/fcntl fcntl lockf}@anchor{15e3}
@deffn {函式} fcntl.lockf (fd, cmd, len=0, start=0, whence=0, /)

This is essentially a wrapper around the @ref{17d0,,fcntl()} locking calls.
`fd' is the file descriptor (file objects providing a @ref{2b7e,,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{4cb2}
@deffn {資料} fcntl.LOCK_UN

Release an existing lock.
@end deffn

@geindex LOCK_SH (於 fcntl 模組中)
@anchor{library/fcntl fcntl LOCK_SH}@anchor{4cb3}
@deffn {資料} fcntl.LOCK_SH

Acquire a shared lock.
@end deffn

@geindex LOCK_EX (於 fcntl 模組中)
@anchor{library/fcntl fcntl LOCK_EX}@anchor{4cb4}
@deffn {資料} fcntl.LOCK_EX

Acquire an exclusive lock.
@end deffn

@geindex LOCK_NB (於 fcntl 模組中)
@anchor{library/fcntl fcntl LOCK_NB}@anchor{4cb5}
@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{2c0,,OSError} will be raised and the exception will have an `errno'
attribute set to @ref{25b7,,EACCES} or @ref{25a8,,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{148d,,io.IOBase.seek()}, specifically:


@itemize *

@item 
@code{0} -- relative to the start of the file (@ref{148e,,os.SEEK_SET})

@item 
@code{1} -- relative to the current buffer position (@ref{148f,,os.SEEK_CUR})

@item 
@code{2} -- relative to the end of the file (@ref{1490,,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.

引發一個附帶引數 @code{fd}、@code{cmd}、@code{len}、@code{start}、@code{whence} 的@ref{1b70,,稽核事件} @code{fcntl.lockf}。
@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{192,,bytes} object.  The
structure lay-out for the `lockdata' variable is system dependent --- therefore
using the @ref{4615,,flock()} call may be better.


@subsubheading 也參考



@table @asis

@item @ref{a5,,os} 模組

If the locking flags @ref{1626,,O_SHLOCK} and @ref{1627,,O_EXLOCK} are
present in the @ref{a5,,os} module (on BSD only), the @ref{f8d,,os.open()}
function provides an alternative to the @ref{15e3,,lockf()} and @ref{4615,,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 --- 資源使用資訊,syslog --- Unix syslog 函式庫例程,fcntl --- fcntl 和 ioctl 系統呼叫,Unix 特有服務
@anchor{library/resource doc}@anchor{4cb6}@anchor{library/resource module-resource}@anchor{c1}@anchor{library/resource resource-resource-usage-information}@anchor{4cb7}@anchor{library/resource translation-repo}@anchor{4cb8}
@subsection @code{resource} --- 資源使用資訊


@geindex module; resource


__________________________________________________________________


This module provides basic mechanisms for measuring and controlling system
resources utilized by a program.

@ref{2006,,可用性}: 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{2c0,,OSError} is raised on syscall failure.

@geindex error
@anchor{library/resource resource error}@anchor{4cb9}
@deffn {例外} resource.error

A deprecated alias of @ref{2c0,,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{2c0,,OSError}.

@end deffn

@menu
* Resource Limits:: 
* Resource Usage:: 

@end menu

@node Resource Limits,Resource Usage,,resource --- 資源使用資訊
@anchor{library/resource resource-limits}@anchor{4cba}
@subsubsection Resource Limits


Resources usage can be limited using the @ref{175c,,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{175b}
@deffn {資料} resource.RLIM_INFINITY

Constant used to represent the limit for an unlimited resource.
@end deffn

@geindex getrlimit() (於 resource 模組中)
@anchor{library/resource resource getrlimit}@anchor{175a}
@deffn {函式} resource.getrlimit (resource)

Returns a tuple @code{(soft, hard)} with the current soft and hard limits of
`resource'. Raises @ref{2eb,,ValueError} if an invalid resource is specified, or
@ref{4cb9,,error} if the underlying system call fails unexpectedly.
@end deffn

@geindex setrlimit() (於 resource 模組中)
@anchor{library/resource resource setrlimit}@anchor{175c}
@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{175b,,RLIM_INFINITY} can be used to request a limit that is
unlimited.

Raises @ref{2eb,,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{175b,,RLIM_INFINITY} when the hard or
system limit for that resource is not unlimited will result in a
@ref{2eb,,ValueError}.  A process with the effective UID of super-user can
request any valid limit value, including unlimited, but @ref{2eb,,ValueError}
will still be raised if the requested limit exceeds the system imposed
limit.

@code{setrlimit} may also raise @ref{4cb9,,error} if the underlying system call
fails.

VxWorks only supports setting @ref{4cbb,,RLIMIT_NOFILE}.

引發一個附帶引數 @code{resource}、@code{limits} 的@ref{1b70,,稽核事件} @code{resource.setrlimit}。
@end deffn

@geindex prlimit() (於 resource 模組中)
@anchor{library/resource resource prlimit}@anchor{1185}
@deffn {函式} resource.prlimit (pid, resource[, limits])

Combines @ref{175c,,setrlimit()} and @ref{175a,,getrlimit()} in one function and
supports to get and set the resources limits of an arbitrary process. If
`pid' is 0, then the call applies to the current process. `resource' and
`limits' have the same meaning as in @ref{175c,,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{1256,,ProcessLookupError} when `pid' can't be found and
@ref{f39,,PermissionError} when the user doesn't have @code{CAP_SYS_RESOURCE} for
the process.

引發一個附帶引數 @code{pid}、@code{resource}、@code{limits} 的@ref{1b70,,稽核事件} @code{resource.prlimit}。

@ref{2006,,可用性}: Linux >= 2.6.36 with glibc >= 2.13.


在 3.4 版被加入.

@end deffn

These symbols define resources whose consumption can be controlled using the
@ref{175c,,setrlimit()} and @ref{175a,,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{45b6}
@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{4cbc}
@deffn {資料} resource.RLIMIT_CPU

The maximum amount of processor time (in seconds) that a process can use. If
this limit is exceeded, a @ref{3926,,SIGXCPU} signal is sent to the process. (See
the @ref{cb,,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{4cbd}
@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{4cbe}
@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{4cbf}
@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{4cc0}
@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{4cc1}
@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{4cbb}
@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{4cc2}
@deffn {資料} resource.RLIMIT_OFILE

The BSD name for @ref{4cbb,,RLIMIT_NOFILE}.
@end deffn

@geindex RLIMIT_MEMLOCK (於 resource 模組中)
@anchor{library/resource resource RLIMIT_MEMLOCK}@anchor{4cc3}
@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{4cc4}
@deffn {資料} resource.RLIMIT_VMEM

The largest area of mapped memory which the process may occupy.
Usually an alias of @ref{4cc5,,RLIMIT_AS}.

@ref{2006,,可用性}: Solaris, FreeBSD, NetBSD.
@end deffn

@geindex RLIMIT_AS (於 resource 模組中)
@anchor{library/resource resource RLIMIT_AS}@anchor{4cc5}
@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{1186}
@deffn {資料} resource.RLIMIT_MSGQUEUE

The number of bytes that can be allocated for POSIX message queues.

@ref{2006,,可用性}: Linux >= 2.6.8.


在 3.4 版被加入.

@end deffn

@geindex RLIMIT_NICE (於 resource 模組中)
@anchor{library/resource resource RLIMIT_NICE}@anchor{1187}
@deffn {資料} resource.RLIMIT_NICE

The ceiling for the process's nice level (calculated as 20 - rlim_cur).

@ref{2006,,可用性}: Linux >= 2.6.12.


在 3.4 版被加入.

@end deffn

@geindex RLIMIT_RTPRIO (於 resource 模組中)
@anchor{library/resource resource RLIMIT_RTPRIO}@anchor{1188}
@deffn {資料} resource.RLIMIT_RTPRIO

The ceiling of the real-time priority.

@ref{2006,,可用性}: Linux >= 2.6.12.


在 3.4 版被加入.

@end deffn

@geindex RLIMIT_RTTIME (於 resource 模組中)
@anchor{library/resource resource RLIMIT_RTTIME}@anchor{1189}
@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{2006,,可用性}: Linux >= 2.6.25.


在 3.4 版被加入.

@end deffn

@geindex RLIMIT_SIGPENDING (於 resource 模組中)
@anchor{library/resource resource RLIMIT_SIGPENDING}@anchor{118a}
@deffn {資料} resource.RLIMIT_SIGPENDING

The number of signals which the process may queue.

@ref{2006,,可用性}: Linux >= 2.6.8.


在 3.4 版被加入.

@end deffn

@geindex RLIMIT_SBSIZE (於 resource 模組中)
@anchor{library/resource resource RLIMIT_SBSIZE}@anchor{118b}
@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{2006,,可用性}: FreeBSD, NetBSD.


在 3.4 版被加入.

@end deffn

@geindex RLIMIT_SWAP (於 resource 模組中)
@anchor{library/resource resource RLIMIT_SWAP}@anchor{118c}
@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{2006,,可用性}: FreeBSD >= 8.


在 3.4 版被加入.

@end deffn

@geindex RLIMIT_NPTS (於 resource 模組中)
@anchor{library/resource resource RLIMIT_NPTS}@anchor{118d}
@deffn {資料} resource.RLIMIT_NPTS

The maximum number of pseudo-terminals created by this user id.

@ref{2006,,可用性}: FreeBSD >= 8.


在 3.4 版被加入.

@end deffn

@geindex RLIMIT_KQUEUES (於 resource 模組中)
@anchor{library/resource resource RLIMIT_KQUEUES}@anchor{1b9e}
@deffn {資料} resource.RLIMIT_KQUEUES

The maximum number of kqueues this user id is allowed to create.

@ref{2006,,可用性}: FreeBSD >= 11.


在 3.10 版被加入.

@end deffn

@node Resource Usage,,Resource Limits,resource --- 資源使用資訊
@anchor{library/resource resource-usage}@anchor{4cc6}
@subsubsection Resource Usage


These functions are used to retrieve resource usage information:

@geindex getrusage() (於 resource 模組中)
@anchor{library/resource resource getrusage}@anchor{1628}
@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.

一個簡單範例：

@example
from resource import *
import time

# a non CPU-bound task
time.sleep(3)
print(getrusage(RUSAGE_SELF))

# a CPU-bound task
for i in range(10 ** 8):
   _ = 1 + 1
print(getrusage(RUSAGE_SELF))
@end example

The fields of the return value each describe how a particular system resource
has been used, e.g. amount of time spent running is user mode or number of times
the process was swapped out of main memory. Some values are dependent on the
clock tick internal, e.g. the amount of memory the process is using.

For backward compatibility, the return value is also accessible as a tuple of 16
elements.

The fields @code{ru_utime} and @code{ru_stime} of the return value are
floating-point values representing the amount of time spent executing in user
mode and the amount of time spent executing in system mode, respectively. The
remaining values are integers. Consult the @code{getrusage(2)@footnote{https://manpages.debian.org/getrusage(2)}} man page for
detailed information about these values. A brief summary is presented here:


@multitable {xxxxxxxxxx} {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{2eb,,ValueError} if an invalid `who' parameter is
specified. It may also raise @ref{4cb9,,error} exception in unusual circumstances.
@end deffn

@geindex getpagesize() (於 resource 模組中)
@anchor{library/resource resource getpagesize}@anchor{4cc7}
@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{1628,,getrusage()}
function to specify which processes information should be provided for.

@geindex RUSAGE_SELF (於 resource 模組中)
@anchor{library/resource resource RUSAGE_SELF}@anchor{4cc8}
@deffn {資料} resource.RUSAGE_SELF

Pass to @ref{1628,,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{4cc9}
@deffn {資料} resource.RUSAGE_CHILDREN

Pass to @ref{1628,,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{4cca}
@deffn {資料} resource.RUSAGE_BOTH

Pass to @ref{1628,,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{4ccb}
@deffn {資料} resource.RUSAGE_THREAD

Pass to @ref{1628,,getrusage()} to request resources consumed by the current
thread.  May not be available on all systems.


在 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 函式庫例程,,resource --- 資源使用資訊,Unix 特有服務
@anchor{library/syslog doc}@anchor{4ccc}@anchor{library/syslog module-syslog}@anchor{e2}@anchor{library/syslog syslog-unix-syslog-library-routines}@anchor{4ccd}@anchor{library/syslog translation-repo}@anchor{4cce}
@subsection @code{syslog} --- Unix syslog 函式庫例程


@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{2006,,可用性}: 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{8d,,logging.handlers} module as @ref{865,,SysLogHandler}.

該模組定義了以下函式：

@geindex syslog() (於 syslog 模組中)
@anchor{library/syslog syslog syslog}@anchor{75b}
@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{4ccf,,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{759,,openlog()} call is used.

If @ref{759,,openlog()} has not been called prior to the call to @ref{e2,,syslog()},
@ref{759,,openlog()} will be called with no arguments.

引發一個附帶引數 @code{priority}、@code{message} 的@ref{1b70,,稽核事件} @code{syslog.syslog}。


在 3.2 版的變更: In previous versions, @ref{759,,openlog()} would not be called automatically if
it wasn't called prior to the call to @ref{e2,,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{759,,openlog()} must be called in the main interpreter before @ref{e2,,syslog()} may be used
in a subinterpreter.  Otherwise it will raise @ref{244,,RuntimeError}.

@end deffn

@geindex openlog() (於 syslog 模組中)
@anchor{library/syslog syslog openlog}@anchor{759}
@deffn {函式} syslog.openlog ([ident[, logoption[, facility]]])

Logging options of subsequent @ref{e2,,syslog()} calls can be set by calling
@ref{759,,openlog()}.  @ref{e2,,syslog()} will call @ref{759,,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{4cd0,,LOG_USER}) sets the default facility for
messages which do not have a facility explicitly encoded.

引發一個附帶引數 @code{ident}、@code{logoption}、@code{facility} 的@ref{1b70,,稽核事件} @code{syslog.openlog}。


在 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{244,,RuntimeError} if called in a subinterpreter.

@end deffn

@geindex closelog() (於 syslog 模組中)
@anchor{library/syslog syslog closelog}@anchor{75a}
@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{759,,openlog()} will be called on the first @ref{e2,,syslog()} call (if
@ref{759,,openlog()} hasn't already been called), and `ident' and other
@ref{759,,openlog()} parameters are reset to defaults.

引發一個不附帶引數的@ref{1b70,,稽核事件} @code{syslog.closelog}。


在 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{244,,RuntimeError} if called in a subinterpreter.

@end deffn

@geindex setlogmask() (於 syslog 模組中)
@anchor{library/syslog syslog setlogmask}@anchor{461b}
@deffn {函式} syslog.setlogmask (maskpri)

Set the priority mask to `maskpri' and return the previous mask value.  Calls
to @ref{e2,,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'.

引發一個附帶引數 @code{maskpri} 的@ref{1b70,,稽核事件} @code{syslog.setlogmask}。
@end deffn

這個模組定義了以下常數：

@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{4cd1}
@deffn {資料} syslog.LOG_EMERG
@anchor{library/syslog syslog LOG_ALERT}@anchor{4cd2}
@deffnx {資料} syslog.LOG_ALERT
@anchor{library/syslog syslog LOG_CRIT}@anchor{4cd3}
@deffnx {資料} syslog.LOG_CRIT
@anchor{library/syslog syslog LOG_ERR}@anchor{4cd4}
@deffnx {資料} syslog.LOG_ERR
@anchor{library/syslog syslog LOG_WARNING}@anchor{4cd5}
@deffnx {資料} syslog.LOG_WARNING
@anchor{library/syslog syslog LOG_NOTICE}@anchor{4cd6}
@deffnx {資料} syslog.LOG_NOTICE
@anchor{library/syslog syslog LOG_INFO}@anchor{4ccf}
@deffnx {資料} syslog.LOG_INFO
@anchor{library/syslog syslog LOG_DEBUG}@anchor{4cd7}
@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{4cd8}
@deffn {資料} syslog.LOG_AUTH
@anchor{library/syslog syslog LOG_AUTHPRIV}@anchor{4cd9}
@deffnx {資料} syslog.LOG_AUTHPRIV
@anchor{library/syslog syslog LOG_CRON}@anchor{4cda}
@deffnx {資料} syslog.LOG_CRON
@anchor{library/syslog syslog LOG_DAEMON}@anchor{4cdb}
@deffnx {資料} syslog.LOG_DAEMON
@anchor{library/syslog syslog LOG_FTP}@anchor{4cdc}
@deffnx {資料} syslog.LOG_FTP
@anchor{library/syslog syslog LOG_INSTALL}@anchor{4cdd}
@deffnx {資料} syslog.LOG_INSTALL
@anchor{library/syslog syslog LOG_KERN}@anchor{4cde}
@deffnx {資料} syslog.LOG_KERN
@anchor{library/syslog syslog LOG_LAUNCHD}@anchor{4cdf}
@deffnx {資料} syslog.LOG_LAUNCHD
@anchor{library/syslog syslog LOG_LPR}@anchor{4ce0}
@deffnx {資料} syslog.LOG_LPR
@anchor{library/syslog syslog LOG_MAIL}@anchor{4ce1}
@deffnx {資料} syslog.LOG_MAIL
@anchor{library/syslog syslog LOG_NETINFO}@anchor{4ce2}
@deffnx {資料} syslog.LOG_NETINFO
@anchor{library/syslog syslog LOG_NEWS}@anchor{4ce3}
@deffnx {資料} syslog.LOG_NEWS
@anchor{library/syslog syslog LOG_RAS}@anchor{4ce4}
@deffnx {資料} syslog.LOG_RAS
@anchor{library/syslog syslog LOG_REMOTEAUTH}@anchor{4ce5}
@deffnx {資料} syslog.LOG_REMOTEAUTH
@anchor{library/syslog syslog LOG_SYSLOG}@anchor{4ce6}
@deffnx {資料} syslog.LOG_SYSLOG
@anchor{library/syslog syslog LOG_USER}@anchor{4cd0}
@deffnx {資料} syslog.LOG_USER
@anchor{library/syslog syslog LOG_UUCP}@anchor{4ce7}
@deffnx {資料} syslog.LOG_UUCP
@anchor{library/syslog syslog LOG_LOCAL0}@anchor{4ce8}
@deffnx {資料} syslog.LOG_LOCAL0
@anchor{library/syslog syslog LOG_LOCAL1}@anchor{4ce9}
@deffnx {資料} syslog.LOG_LOCAL1
@anchor{library/syslog syslog LOG_LOCAL2}@anchor{4cea}
@deffnx {資料} syslog.LOG_LOCAL2
@anchor{library/syslog syslog LOG_LOCAL3}@anchor{4ceb}
@deffnx {資料} syslog.LOG_LOCAL3
@anchor{library/syslog syslog LOG_LOCAL4}@anchor{4cec}
@deffnx {資料} syslog.LOG_LOCAL4
@anchor{library/syslog syslog LOG_LOCAL5}@anchor{4ced}
@deffnx {資料} syslog.LOG_LOCAL5
@anchor{library/syslog syslog LOG_LOCAL6}@anchor{4cee}
@deffnx {資料} syslog.LOG_LOCAL6
@anchor{library/syslog syslog LOG_LOCAL7}@anchor{4cef}
@deffnx {資料} syslog.LOG_LOCAL7

Facilities, depending on availability in @code{<syslog.h>} for @ref{4cd9,,LOG_AUTHPRIV},
@ref{4cdc,,LOG_FTP}, @ref{4ce2,,LOG_NETINFO}, @ref{4ce5,,LOG_REMOTEAUTH},
@ref{4cdd,,LOG_INSTALL} and @ref{4ce4,,LOG_RAS}.


在 3.13 版的變更: Added @ref{4cdc,,LOG_FTP}, @ref{4ce2,,LOG_NETINFO}, @ref{4ce5,,LOG_REMOTEAUTH},
@ref{4cdd,,LOG_INSTALL}, @ref{4ce4,,LOG_RAS}, and @ref{4cdf,,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{4cf0}
@deffn {資料} syslog.LOG_PID
@anchor{library/syslog syslog LOG_CONS}@anchor{4cf1}
@deffnx {資料} syslog.LOG_CONS
@anchor{library/syslog syslog LOG_NDELAY}@anchor{4cf2}
@deffnx {資料} syslog.LOG_NDELAY
@anchor{library/syslog syslog LOG_ODELAY}@anchor{4cf3}
@deffnx {資料} syslog.LOG_ODELAY
@anchor{library/syslog syslog LOG_NOWAIT}@anchor{4cf4}
@deffnx {資料} syslog.LOG_NOWAIT
@anchor{library/syslog syslog LOG_PERROR}@anchor{4cf5}
@deffnx {資料} syslog.LOG_PERROR

Log options, depending on availability in @code{<syslog.h>} for
@ref{4cf3,,LOG_ODELAY}, @ref{4cf4,,LOG_NOWAIT} and @ref{4cf5,,LOG_PERROR}.
@end deffn

@menu
* 範例: 範例<52>. 

@end menu

@node 範例<52>,,,syslog --- Unix syslog 函式庫例程
@anchor{library/syslog examples}@anchor{4cf6}
@subsubsection 範例


@menu
* 簡單範例: 簡單範例<2>. 

@end menu

@node 簡單範例<2>,,,範例<52>
@anchor{library/syslog simple-example}@anchor{4cf7}
@subsubsection 簡單範例


一組簡單範例：

@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 模組命令列介面,已被取代的模組,Unix 特有服務,Python 標準函式庫 Standard Library
@anchor{library/cmdline doc}@anchor{4cf8}@anchor{library/cmdline library-cmdline}@anchor{4cf9}@anchor{library/cmdline modules-command-line-interface-cli}@anchor{4cfa}@anchor{library/cmdline translation-repo}@anchor{4cfb}
@section 模組命令列介面


以下模組具有命令列介面。


@itemize *

@item 
@ref{4aa0,,ast}

@item 
@ref{3677,,asyncio}

@item 
@ref{f,,base64}

@item 
@ref{1d0,,calendar}

@item 
@ref{1b,,code}

@item 
@ref{4b60,,compileall}

@item 
@ref{2b,,cProfile}: 請見 @ref{46b7,,profile}

@item 
@ref{4b77,,dis}

@item 
@ref{440f,,doctest}

@item 
@code{encodings.rot_13}

@item 
@ref{59,,ensurepip}

@item 
@ref{5e,,filecmp}

@item 
@ref{5f,,fileinput}

@item 
@ref{62,,ftplib}

@item 
@ref{2d0d,,gzip}

@item 
@ref{114c,,http.server}

@item 
@code{idlelib}

@item 
@ref{1156,,inspect}

@item 
@ref{23e,,json}

@item 
@ref{247,,mimetypes}

@item 
@ref{aa,,pdb}

@item 
@ref{2be1,,pickle}

@item 
@ref{2be2,,pickletools}

@item 
@ref{30f9,,platform}

@item 
@ref{b1,,poplib}

@item 
@ref{46b7,,profile}

@item 
@ref{b5,,pstats}

@item 
@ref{4b57,,py_compile}

@item 
@ref{b9,,pyclbr}

@item 
@ref{ba,,pydoc}

@item 
@ref{bc,,quopri}

@item 
@ref{479,,random}

@item 
@ref{c3,,runpy}

@item 
@ref{4966,,site}

@item 
@ref{66c,,sqlite3}

@item 
@ref{4ad7,,symtable}

@item 
@ref{482a,,sysconfig}

@item 
@ref{e3,,tabnanny}

@item 
@ref{11c6,,tarfile}

@item 
@code{this}

@item 
@ref{46db,,timeit}

@item 
@ref{4b28,,tokenize}

@item 
@ref{46f8,,trace}

@item 
@ref{108,,turtledemo}

@item 
@ref{4488,,unittest}

@item 
@ref{66e,,uuid}

@item 
@ref{117,,venv}

@item 
@ref{11b,,webbrowser}

@item 
@ref{4788,,zipapp}

@item 
@ref{2d7c,,zipfile}
@end itemize

另請見 @ref{1c70,,Python 命令列介面}。

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node 已被取代的模組,已移除的模組,模組命令列介面,Python 標準函式庫 Standard Library
@anchor{library/superseded doc}@anchor{4cfc}@anchor{library/superseded superseded}@anchor{4cfd}@anchor{library/superseded superseded-modules}@anchor{4cfe}@anchor{library/superseded translation-repo}@anchor{4cff}
@section 已被取代的模組


此章節所描述的模組在大多數使用情況下已被其他模組取代，僅為了向後相容性而被保留下來。

某些模組出現在本章節，可能是因為它們能解決的問題是問題空間的有限子集，而標準函式庫的其他地方提供了更通用的解決方案（例如，@ref{65,,getopt} 只處理「在 Python 中模擬 C 語言中 @code{getopt()} 這個 API 」這項非常具體的任務，而非像 @ref{a4,,optparse} 和 @ref{7,,argparse} 那樣提供更廣泛的命令列選項剖析與引數剖析功能）。

或者， 某些模組出現在本章節，可能是因為它們已被明確棄用（deprecated），並將在未來版本中移除；又或者它們屬於 @ref{23d,,soft deprecated} 狀態，官方強烈不建議在新專案中使用。隨著 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/} 移除了多個過時模組，目前標準函式庫中已不存在後者（軟性棄用）這類模組。

@menu
* getopt: getopt --- 用於命令列選項的 C 風格剖析器. 用於命令列選項的 C 風格剖析器

@end menu

@node getopt --- 用於命令列選項的 C 風格剖析器,,,已被取代的模組
@anchor{library/getopt doc}@anchor{4d00}@anchor{library/getopt getopt-c-style-parser-for-command-line-options}@anchor{4d01}@anchor{library/getopt module-getopt}@anchor{65}
@subsection @code{getopt} --- 用於命令列選項的 C 風格剖析器


@geindex module; getopt

`原始碼：'Lib/getopt.py@footnote{https://github.com/python/cpython/tree/3.14/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{3220,,選擇一個命令列參數剖析函式庫} for
additional details.

這個模組提供兩個函式和一個例外：

@geindex getopt() (於 getopt 模組中)
@anchor{library/getopt getopt getopt}@anchor{16af}
@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{1857,,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{16ae}
@deffn {函式} getopt.gnu_getopt (args, shortopts, longopts=[])

This function works like @ref{65,,getopt()}, except that GNU style scanning mode is
used by default. This means that option and non-option arguments may be
intermixed. The @ref{65,,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{1857}
@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{4d02}
@deffn {例外} getopt.error

為了向後相容性而設的 @ref{1857,,GetoptError} 別名。
@end deffn

一個僅使用 Unix 風格選項的範例：

@example
>>> import getopt
>>> args = '-a -b -cfoo -d bar a1 a2'.split()
>>> args
['-a', '-b', '-cfoo', '-d', 'bar', 'a1', 'a2']
>>> optlist, args = getopt.getopt(args, 'abc:d:')
>>> optlist
[('-a', '@w{'}), ('-b', '@w{'}), ('-c', 'foo'), ('-d', 'bar')]
>>> args
['a1', 'a2']
@end example

使用長選項名稱同樣容易：

@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

在腳本中，典型的用法如下：

@example
import getopt, sys

def main():
    try:
        opts, args = getopt.getopt(sys.argv[1:], "ho:v", ["help", "output="])
    except getopt.GetoptError as err:
        # 印出幫助訊息並退出：
        print(err)  # 會印出像是 "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

參見 @ref{3220,,選擇一個命令列參數剖析函式庫} 以瞭解這段程式碼的 @code{argparse} 版本與 @code{optparse}（以及 @code{getopt}）版本在行為上的差異。


@subsubheading 也參考



@table @asis

@item @ref{a4,,optparse} 模組

宣告式命令列選項剖析。

@item @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)

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node 已移除的模組,安全性注意事項<4>,已被取代的模組,Python 標準函式庫 Standard Library
@anchor{library/removed doc}@anchor{4d03}@anchor{library/removed removed}@anchor{4d04}@anchor{library/removed removed-modules}@anchor{4d05}@anchor{library/removed translation-repo}@anchor{4d06}
@section 已移除的模組


本章描述的模組已從 Python 標準函式庫中移除。這裡提供文件以協助尋找替代方案。

@menu
* aifc: aifc --- 讀寫 AIFF 與 AIFC 檔案. 讀寫 AIFF 與 AIFC 檔案
* asynchat: asynchat --- 非同步 socket 指令/回應處理函式. 非同步 socket 指令/回應處理函式
* asyncore: asyncore --- 非同步 socket 處理函式. 非同步 socket 處理函式
* audioop: audioop --- 操作原始聲音檔案. 操作原始聲音檔案
* cgi: cgi --- 通用閘道器介面支援. 通用閘道器介面支援
* cgitb: cgitb --- CGI 腳本的回溯管理器 traceback manager. CGI 腳本的回溯管理器 (traceback manager)
* chunk: chunk --- 讀取 IFF 分塊資料. 讀取 IFF 分塊資料
* crypt: crypt --- 用於檢查 Unix 密碼的函式. 用於檢查 Unix 密碼的函式
* distutils: distutils --- 建置與安裝 Python 模組. 建置與安裝 Python 模組
* imghdr: imghdr --- 判定圖片種類. 判定圖片種類
* imp: imp --- 存取引入系統內層. 存取引入系統內層
* mailcap: mailcap --- Mailcap 檔案處理. Mailcap 檔案處理
* msilib: msilib --- 讀寫 Microsoft Installer 檔案. 讀寫 Microsoft Installer 檔案
* nis: nis --- Sun NIS Yellow Pages 介面. Sun NIS (Yellow Pages) 介面
* nntplib: nntplib --- NNTP 協定用戶端. NNTP 協定用戶端
* ossaudiodev: ossaudiodev --- 對 OSS 相容聲音裝置的存取. 對 OSS 相容聲音裝置的存取
* pipes: pipes --- shell pipelines 介面. shell pipelines 介面
* smtpd: smtpd --- SMTP 伺服器. SMTP 伺服器
* sndhdr: sndhdr --- 判定聲音檔案的種類. 判定聲音檔案的種類
* spwd: spwd --- shadow 密碼資料庫. shadow 密碼資料庫
* sunau: sunau --- 讀寫 Sun AU 檔案. 讀寫 Sun AU 檔案
* telnetlib: telnetlib --- Telnet 用戶端. Telnet 用戶端
* uu: uu --- uuencode 檔案的編碼與解碼. uuencode 檔案的編碼與解碼
* xdrlib: xdrlib --- XDR 資料的編碼與解碼. XDR 資料的編碼與解碼

@end menu

@node aifc --- 讀寫 AIFF 與 AIFC 檔案,asynchat --- 非同步 socket 指令/回應處理函式,,已移除的模組
@anchor{library/aifc doc}@anchor{4d07}@anchor{library/aifc aifc-read-and-write-aiff-and-aifc-files}@anchor{4d08}@anchor{library/aifc module-aifc}@anchor{5}
@subsection @code{aifc} --- 讀寫 AIFF 與 AIFC 檔案


@geindex module; aifc


Deprecated since version 3.11, removed in version 3.13.


這個模組已不再是 Python 標準函式庫的一部分。它在 Python 3.11 中被棄用，並@ref{46b,,已在 Python 3.13 中被移除}。它的移除是在 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/} 中決定的。

最後提供 @code{aifc} 模組的 Python 版本是 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 --- 非同步 socket 指令/回應處理函式,asyncore --- 非同步 socket 處理函式,aifc --- 讀寫 AIFF 與 AIFC 檔案,已移除的模組
@anchor{library/asynchat doc}@anchor{4d09}@anchor{library/asynchat asynchat-asynchronous-socket-command-response-handler}@anchor{4d0a}@anchor{library/asynchat module-asynchat}@anchor{a}@anchor{library/asynchat translation-repo}@anchor{4d0b}
@subsection @code{asynchat} --- 非同步 socket 指令/回應處理函式


@geindex module; asynchat


Deprecated since version 3.6, removed in version 3.12.


這個模組已不再是 Python 標準函式庫的一部分。它在 Python 3.6 中被棄用，並@ref{71f,,已在 Python 3.12 中被移除}。它的移除是在 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/} 中決定的。

應用程式應改用 @ref{b,,asyncio} 模組。

最後提供 @code{asynchat} 模組的 Python 版本是 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 --- 非同步 socket 處理函式,audioop --- 操作原始聲音檔案,asynchat --- 非同步 socket 指令/回應處理函式,已移除的模組
@anchor{library/asyncore doc}@anchor{4d0c}@anchor{library/asyncore asyncore-asynchronous-socket-handler}@anchor{4d0d}@anchor{library/asyncore module-asyncore}@anchor{c}@anchor{library/asyncore translation-repo}@anchor{4d0e}
@subsection @code{asyncore} --- 非同步 socket 處理函式


@geindex module; asyncore


Deprecated since version 3.6, removed in version 3.12.


這個模組已不再是 Python 標準函式庫的一部分。它在 Python 3.6 中被棄用，並@ref{71f,,已在 Python 3.12 中被移除}。它的移除是在 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/} 中決定的。

應用程式應改用 @ref{b,,asyncio} 模組。

最後提供 @code{asyncore} 模組的 Python 版本是 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 --- 操作原始聲音檔案,cgi --- 通用閘道器介面支援,asyncore --- 非同步 socket 處理函式,已移除的模組
@anchor{library/audioop doc}@anchor{4d0f}@anchor{library/audioop audioop-manipulate-raw-audio-data}@anchor{4d10}@anchor{library/audioop module-audioop}@anchor{e}@anchor{library/audioop translation-repo}@anchor{4d11}
@subsection @code{audioop} --- 操作原始聲音檔案


@geindex module; audioop


Deprecated since version 3.11, removed in version 3.13.


這個模組已不再是 Python 標準函式庫的一部分。它在 Python 3.11 中被棄用，並@ref{46b,,已在 Python 3.13 中被移除}。它的移除是在 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/} 中決定的。

最後提供 @code{audioop} 模組的 Python 版本是 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 --- 通用閘道器介面支援,cgitb --- CGI 腳本的回溯管理器 traceback manager,audioop --- 操作原始聲音檔案,已移除的模組
@anchor{library/cgi doc}@anchor{4d12}@anchor{library/cgi cgi-common-gateway-interface-support}@anchor{4d13}@anchor{library/cgi module-cgi}@anchor{16}@anchor{library/cgi translation-repo}@anchor{4d14}
@subsection @code{cgi} --- 通用閘道器介面支援


@geindex module; cgi


Deprecated since version 3.11, removed in version 3.13.


這個模組已不再是 Python 標準函式庫的一部分。它在 Python 3.11 中被棄用，並@ref{46b,,已在 Python 3.13 中被移除}。它的移除是在 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/} 中決定的。

可以改用 PyPI 上的模組 fork：legacy-cgi@footnote{https://pypi.org/project/legacy-cgi/}。這是 cgi 模組的一個副本，不再由 Python 核心團隊維護或支援。

最後提供 @code{cgi} 模組的 Python 版本是 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 cgitb --- CGI 腳本的回溯管理器 traceback manager,chunk --- 讀取 IFF 分塊資料,cgi --- 通用閘道器介面支援,已移除的模組
@anchor{library/cgitb doc}@anchor{4d15}@anchor{library/cgitb cgitb-traceback-manager-for-cgi-scripts}@anchor{4d16}@anchor{library/cgitb module-cgitb}@anchor{17}@anchor{library/cgitb translation-repo}@anchor{4d17}
@subsection @code{cgitb} --- CGI 腳本的回溯管理器 (traceback manager)


@geindex module; cgitb


Deprecated since version 3.11, removed in version 3.13.


這個模組已不再是 Python 標準函式庫的一部分。它在 Python 3.11 中被棄用，並@ref{46b,,已在 Python 3.13 中被移除}。它的移除是在 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/} 中決定的。

可以改用 PyPI 上的模組 fork：legacy-cgi@footnote{https://pypi.org/project/legacy-cgi/}。這是 cgi 模組的一個複本，不再由 Python 核心團隊維護或支援。

最後提供 @code{cgitb} 模組的 Python 版本是 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 --- 讀取 IFF 分塊資料,crypt --- 用於檢查 Unix 密碼的函式,cgitb --- CGI 腳本的回溯管理器 traceback manager,已移除的模組
@anchor{library/chunk doc}@anchor{4d18}@anchor{library/chunk chunk-read-iff-chunked-data}@anchor{4d19}@anchor{library/chunk module-chunk}@anchor{18}@anchor{library/chunk translation-repo}@anchor{4d1a}
@subsection @code{chunk} --- 讀取 IFF 分塊資料


@geindex module; chunk


Deprecated since version 3.11, removed in version 3.13.


這個模組已不再是 Python 標準函式庫的一部分。它在 Python 3.11 中被棄用，並@ref{46b,,已在 Python 3.13 中被移除}。它的移除是在 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/} 中決定的。

最後提供 @code{chunk} 模組的 Python 版本是 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 --- 用於檢查 Unix 密碼的函式,distutils --- 建置與安裝 Python 模組,chunk --- 讀取 IFF 分塊資料,已移除的模組
@anchor{library/crypt doc}@anchor{4d1b}@anchor{library/crypt crypt-function-to-check-unix-passwords}@anchor{4d1c}@anchor{library/crypt module-crypt}@anchor{2c}@anchor{library/crypt translation-repo}@anchor{4d1d}
@subsection @code{crypt} --- 用於檢查 Unix 密碼的函式


@geindex module; crypt


Deprecated since version 3.11, removed in version 3.13.


這個模組已不再是 Python 標準函式庫的一部分。它在 Python 3.11 中被棄用，並@ref{46b,,已在 Python 3.13 中被移除}。它的移除是在 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/} 中決定的。

應用程式可以改用標準函式庫中的 @ref{6c,,hashlib} 模組。其他可能的替代方案是 PyPI 上的第三方庫：legacycrypt@footnote{https://pypi.org/project/legacycrypt/}、bcrypt@footnote{https://pypi.org/project/bcrypt/} 或 argon2-cffi@footnote{https://pypi.org/project/argon2-cffi/}。這些函式庫並不受 Python 核心團隊支援或維護。

最後提供 @code{crypt} 模組的 Python 版本是 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 --- 建置與安裝 Python 模組,imghdr --- 判定圖片種類,crypt --- 用於檢查 Unix 密碼的函式,已移除的模組
@anchor{library/distutils doc}@anchor{4d1e}@anchor{library/distutils distutils-building-and-installing-python-modules}@anchor{4d1f}@anchor{library/distutils module-distutils}@anchor{3d}@anchor{library/distutils translation-repo}@anchor{4d20}
@subsection @code{distutils} --- 建置與安裝 Python 模組


@geindex module; distutils


Deprecated since version 3.10, removed in version 3.12.


這個模組已不再是 Python 標準函式庫的一部分。它在 Python 3.10 中被棄用，並@ref{725,,已在 Python 3.12 中被移除}。它的移除是在 
@geindex Python Enhancement Proposals; PEP 632
PEP 632@footnote{https://peps.python.org/pep-0632/} 中決定的，該 PEP 附有遷移建議@footnote{https://peps.python.org/pep-0632/#migration-advice}。

最後提供 @code{distutils} 模組的 Python 版本是 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 --- 判定圖片種類,imp --- 存取引入系統內層,distutils --- 建置與安裝 Python 模組,已移除的模組
@anchor{library/imghdr doc}@anchor{4d21}@anchor{library/imghdr imghdr-determine-the-type-of-an-image}@anchor{4d22}@anchor{library/imghdr module-imghdr}@anchor{79}@anchor{library/imghdr translation-repo}@anchor{4d23}
@subsection @code{imghdr} --- 判定圖片種類


@geindex module; imghdr


Deprecated since version 3.11, removed in version 3.13.


這個模組已不再是 Python 標準函式庫的一部分。它在 Python 3.11 中被棄用，並@ref{46b,,已在 Python 3.13 中被移除}。它的移除是在 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/} 中決定的。

可能的替代方案是 PyPI 上的第三方函式庫：filetype@footnote{https://pypi.org/project/filetype/}、puremagic@footnote{https://pypi.org/project/puremagic/} 或 python-magic@footnote{https://pypi.org/project/python-magic/}。它們並不受 Python 核心團隊支援或維護。

最後提供 @code{imghdr} 模組的 Python 版本是 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 --- 存取引入系統內層,mailcap --- Mailcap 檔案處理,imghdr --- 判定圖片種類,已移除的模組
@anchor{library/imp doc}@anchor{4d24}@anchor{library/imp imp-access-the-import-internals}@anchor{4d25}@anchor{library/imp module-imp}@anchor{7a}@anchor{library/imp translation-repo}@anchor{4d26}
@subsection @code{imp} --- 存取引入系統內層


@geindex module; imp


Deprecated since version 3.4, removed in version 3.12.


這個模組已不再是 Python 標準函式庫的一部分。它在 Python 3.4 中被棄用，並@ref{72f,,已在 Python 3.12 中被移除}。

其@ref{72f,,移除通知}包含了從 @code{imp} 遷移至 @ref{7b,,importlib} 的指引。

最後提供 @code{imp} 模組的 Python 版本是 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 檔案處理,msilib --- 讀寫 Microsoft Installer 檔案,imp --- 存取引入系統內層,已移除的模組
@anchor{library/mailcap doc}@anchor{4d27}@anchor{library/mailcap mailcap-mailcap-file-handling}@anchor{4d28}@anchor{library/mailcap module-mailcap}@anchor{90}@anchor{library/mailcap translation-repo}@anchor{4d29}
@subsection @code{mailcap} --- Mailcap 檔案處理


@geindex module; mailcap


Deprecated since version 3.11, removed in version 3.13.


這個模組已不再是 Python 標準函式庫的一部分。它在 Python 3.11 中被棄用，並@ref{46b,,已在 Python 3.13 中被移除}。它的移除是在 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/} 中決定的。

最後提供 @code{mailcap} 模組的 Python 版本是 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 --- 讀寫 Microsoft Installer 檔案,nis --- Sun NIS Yellow Pages 介面,mailcap --- Mailcap 檔案處理,已移除的模組
@anchor{library/msilib doc}@anchor{4d2a}@anchor{library/msilib module-msilib}@anchor{96}@anchor{library/msilib msilib-read-and-write-microsoft-installer-files}@anchor{4d2b}@anchor{library/msilib translation-repo}@anchor{4d2c}
@subsection @code{msilib} --- 讀寫 Microsoft Installer 檔案


@geindex module; msilib


Deprecated since version 3.11, removed in version 3.13.


這個模組已不再是 Python 標準函式庫的一部分。它在 Python 3.11 中被棄用，並@ref{46b,,已在 Python 3.13 中被移除}。它的移除是在 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/} 中決定的。

最後提供 @code{msilib} 模組的 Python 版本是 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 --- Sun NIS Yellow Pages 介面,nntplib --- NNTP 協定用戶端,msilib --- 讀寫 Microsoft Installer 檔案,已移除的模組
@anchor{library/nis doc}@anchor{4d2d}@anchor{library/nis module-nis}@anchor{a0}@anchor{library/nis nis-interface-to-suns-nis-yellow-pages}@anchor{4d2e}@anchor{library/nis translation-repo}@anchor{4d2f}
@subsection @code{nis} --- Sun NIS (Yellow Pages) 介面


@geindex module; nis


Deprecated since version 3.11, removed in version 3.13.


這個模組已不再是 Python 標準函式庫的一部分。它在 Python 3.11 中被棄用，並@ref{46b,,已在 Python 3.13 中被移除}。它的移除是在 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/} 中決定的。

最後提供 @code{nis} 模組的 Python 版本是 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 協定用戶端,ossaudiodev --- 對 OSS 相容聲音裝置的存取,nis --- Sun NIS Yellow Pages 介面,已移除的模組
@anchor{library/nntplib doc}@anchor{4d30}@anchor{library/nntplib module-nntplib}@anchor{a1}@anchor{library/nntplib nntplib-nntp-protocol-client}@anchor{4d31}@anchor{library/nntplib translation-repo}@anchor{4d32}
@subsection @code{nntplib} --- NNTP 協定用戶端


@geindex module; nntplib


Deprecated since version 3.11, removed in version 3.13.


這個模組已不再是 Python 標準函式庫的一部分。它在 Python 3.11 中被棄用，並@ref{46b,,已在 Python 3.13 中被移除}。它的移除是在 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/} 中決定的。

最後提供 @code{nntplib} 模組的 Python 版本是 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 --- 對 OSS 相容聲音裝置的存取,pipes --- shell pipelines 介面,nntplib --- NNTP 協定用戶端,已移除的模組
@anchor{library/ossaudiodev doc}@anchor{4d33}@anchor{library/ossaudiodev module-ossaudiodev}@anchor{a7}@anchor{library/ossaudiodev ossaudiodev-access-to-oss-compatible-audio-devices}@anchor{4d34}@anchor{library/ossaudiodev translation-repo}@anchor{4d35}
@subsection @code{ossaudiodev} --- 對 OSS 相容聲音裝置的存取


@geindex module; ossaudiodev


Deprecated since version 3.11, removed in version 3.13.


這個模組已不再是 Python 標準函式庫的一部分。它在 Python 3.11 中被棄用，並@ref{46b,,已在 Python 3.13 中被移除}。它的移除是在 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/} 中決定的。

最後提供 @code{ossaudiodev} 模組的 Python 版本是 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 --- shell pipelines 介面,smtpd --- SMTP 伺服器,ossaudiodev --- 對 OSS 相容聲音裝置的存取,已移除的模組
@anchor{library/pipes doc}@anchor{4d36}@anchor{library/pipes module-pipes}@anchor{ad}@anchor{library/pipes pipes-interface-to-shell-pipelines}@anchor{4d37}@anchor{library/pipes translation-repo}@anchor{4d38}
@subsection @code{pipes} --- shell pipelines 介面


@geindex module; pipes


Deprecated since version 3.11, removed in version 3.13.


這個模組已不再是 Python 標準函式庫的一部分。它在 Python 3.11 中被棄用，並@ref{46b,,已在 Python 3.13 中被移除}。它的移除是在 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/} 中決定的。

應用程式應改用 @ref{dc,,subprocess} 模組。

最後提供 @code{pipes} 模組的 Python 版本是 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 伺服器,sndhdr --- 判定聲音檔案的種類,pipes --- shell pipelines 介面,已移除的模組
@anchor{library/smtpd doc}@anchor{4d39}@anchor{library/smtpd module-smtpd}@anchor{ce}@anchor{library/smtpd smtpd-smtp-server}@anchor{4d3a}@anchor{library/smtpd translation-repo}@anchor{4d3b}
@subsection @code{smtpd} --- SMTP 伺服器


@geindex module; smtpd


Deprecated since version 3.6, removed in version 3.12.


這個模組已不再是 Python 標準函式庫的一部分。它在 Python 3.6 中被棄用，並@ref{71f,,已在 Python 3.12 中被移除}。它的移除是在 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/} 中決定的。

一個可能的替代方案是第三方 aiosmtpd@footnote{https://pypi.org/project/aiosmtpd/} 函式庫。這個函式庫並不是由 Python 核心團隊維護或支援。

最後提供 @code{smtpd} 模組的 Python 版本是 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 --- 判定聲音檔案的種類,spwd --- shadow 密碼資料庫,smtpd --- SMTP 伺服器,已移除的模組
@anchor{library/sndhdr doc}@anchor{4d3c}@anchor{library/sndhdr module-sndhdr}@anchor{d0}@anchor{library/sndhdr sndhdr-determine-type-of-sound-file}@anchor{4d3d}@anchor{library/sndhdr translation-repo}@anchor{4d3e}
@subsection @code{sndhdr} --- 判定聲音檔案的種類


@geindex module; sndhdr


Deprecated since version 3.11, removed in version 3.13.


這個模組已不再是 Python 標準函式庫的一部分。它在 Python 3.11 中被棄用，並@ref{46b,,已在 Python 3.13 中被移除}。它的移除是在 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/} 中決定的。

可能的替代方案是 PyPI 上的第三方模組：filetype@footnote{https://pypi.org/project/filetype/}、puremagic@footnote{https://pypi.org/project/puremagic/} 或 python-magic@footnote{https://pypi.org/project/python-magic/}。它們並不受 Python 核心團隊支援或維護。

最後提供 @code{sndhdr} 模組的 Python 版本是 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 --- shadow 密碼資料庫,sunau --- 讀寫 Sun AU 檔案,sndhdr --- 判定聲音檔案的種類,已移除的模組
@anchor{library/spwd doc}@anchor{4d3f}@anchor{library/spwd module-spwd}@anchor{d3}@anchor{library/spwd spwd-the-shadow-password-database}@anchor{4d40}@anchor{library/spwd translation-repo}@anchor{4d41}
@subsection @code{spwd} --- shadow 密碼資料庫


@geindex module; spwd


Deprecated since version 3.11, removed in version 3.13.


這個模組已不再是 Python 標準函式庫的一部分。它在 Python 3.11 中被棄用，並@ref{46b,,已在 Python 3.13 中被移除}。它的移除是在 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/} 中決定的。

可能的替代方案是 PyPI 上的第三方函式庫：python-pam@footnote{https://pypi.org/project/python-pam/}。這並不受 Python 核心團隊支援或維護。

最後提供 @code{spwd} 模組的 Python 版本是 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 --- 讀寫 Sun AU 檔案,telnetlib --- Telnet 用戶端,spwd --- shadow 密碼資料庫,已移除的模組
@anchor{library/sunau doc}@anchor{4d42}@anchor{library/sunau module-sunau}@anchor{dd}@anchor{library/sunau sunau-read-and-write-sun-au-files}@anchor{4d43}@anchor{library/sunau translation-repo}@anchor{4d44}
@subsection @code{sunau} --- 讀寫 Sun AU 檔案


@geindex module; sunau


Deprecated since version 3.11, removed in version 3.13.


這個模組已不再是 Python 標準函式庫的一部分。它在 Python 3.11 中被棄用，並@ref{46b,,已在 Python 3.13 中被移除}。它的移除是在 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/} 中決定的。

最後提供 @code{sunau} 模組的 Python 版本是 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 用戶端,uu --- uuencode 檔案的編碼與解碼,sunau --- 讀寫 Sun AU 檔案,已移除的模組
@anchor{library/telnetlib doc}@anchor{4d45}@anchor{library/telnetlib module-telnetlib}@anchor{e5}@anchor{library/telnetlib telnetlib-telnet-client}@anchor{4d46}@anchor{library/telnetlib translation-repo}@anchor{4d47}
@subsection @code{telnetlib} --- Telnet 用戶端


@geindex module; telnetlib


Deprecated since version 3.11, removed in version 3.13.


這個模組已不再是 Python 標準函式庫的一部分。它在 Python 3.11 中被棄用，並@ref{46b,,已在 Python 3.13 中被移除}。它的移除是在 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/} 中決定的。

可能的替代方案是 PyPI 上的第三方函式庫：telnetlib3@footnote{https://pypi.org/project/telnetlib3/} 或 Exscript@footnote{https://pypi.org/project/Exscript/}。它們並不受 Python 核心團隊支援或維護。

最後提供 @code{telnetlib} 模組的 Python 版本是 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 --- uuencode 檔案的編碼與解碼,xdrlib --- XDR 資料的編碼與解碼,telnetlib --- Telnet 用戶端,已移除的模組
@anchor{library/uu doc}@anchor{4d48}@anchor{library/uu module-uu}@anchor{115}@anchor{library/uu translation-repo}@anchor{4d49}@anchor{library/uu uu-encode-and-decode-uuencode-files}@anchor{4d4a}
@subsection @code{uu} --- uuencode 檔案的編碼與解碼


@geindex module; uu


Deprecated since version 3.11, removed in version 3.13.


這個模組已不再是 Python 標準函式庫的一部分。它在 Python 3.11 中被棄用，並@ref{46b,,已在 Python 3.13 中被移除}。它的移除是在 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/} 中決定的。

最後提供 @code{uu} 模組的 Python 版本是 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 --- XDR 資料的編碼與解碼,,uu --- uuencode 檔案的編碼與解碼,已移除的模組
@anchor{library/xdrlib doc}@anchor{4d4b}@anchor{library/xdrlib module-xdrlib}@anchor{125}@anchor{library/xdrlib translation-repo}@anchor{4d4c}@anchor{library/xdrlib xdrlib-encode-and-decode-xdr-data}@anchor{4d4d}
@subsection @code{xdrlib} --- XDR 資料的編碼與解碼


@geindex module; xdrlib


Deprecated since version 3.11, removed in version 3.13.


這個模組已不再是 Python 標準函式庫的一部分。它在 Python 3.11 中被棄用，並@ref{46b,,已在 Python 3.13 中被移除}。它的移除是在 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/} 中決定的。

最後提供 @code{xdrlib} 模組的 Python 版本是 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{4d4e}
@node 安全性注意事項<4>,,已移除的模組,Python 標準函式庫 Standard Library
@anchor{library/security_warnings doc}@anchor{4d4f}@anchor{library/security_warnings security-considerations}@anchor{4d50}@anchor{library/security_warnings translation-repo}@anchor{4d51}
@section 安全性注意事項


以下模組具有特定的安全性注意事項：


@itemize *

@item 
@ref{f,,base64}：@ref{3b6e,,base64 安全性注意事項}在 
@geindex RFC; RFC 4648
RFC 4648@footnote{https://datatracker.ietf.org/doc/html/rfc4648.html}

@item 
@ref{6c,,hashlib}：@ref{2e7b,,所有建構函式都採用 "usedforsecurity" 僅限關鍵字引數，並禁用已知的不安全與被阻擋的演算法}

@item 
@ref{76,,http.server} 不適合在正式環境使用，因其僅實作基本的安全檢查。請參閱@ref{3fa1,,安全注意事項}。

@item 
@ref{8b,,logging}：@ref{3061,,日誌配置使用 eval()}

@item 
@ref{98,,multiprocessing}：@ref{353a,,Connection.recv() 使用 pickle}

@item 
@ref{ab,,pickle}：@ref{2bcd,,限制 pickle 中的全域變數}

@item 
@ref{bd,,random} 不該用於安全性相關用途，請改用 @ref{c5,,secrets}

@item 
@ref{c8,,shelve}：@ref{2bef,,shelve 為基於 pickle，因此不適合用來處理不受信任的來源}

@item 
@ref{d5,,ssl}：@ref{374a,,SSL/TLS 安全性注意事項}

@item 
@ref{dc,,subprocess}：@ref{3609,,子行程安全性注意事項}

@item 
@ref{e6,,tempfile}：@ref{2b87,,mktemp 由於存在競爭條件 (race condition) 漏洞而被棄用}

@item 
@ref{126,,xml}：@ref{3ba2,,XML 安全性}

@item 
@ref{137,,zipfile}：@ref{2d8b,,惡意準備的 .zip 檔案可能會導致硬碟空間耗盡}
@end itemize

@ref{b4e,,-I} 命令列選項可用於在隔離模式下運行 Python。若其無法使用，可以改用 @ref{7ba,,-P} 選項或 
@geindex PYTHONSAFEPATH
@geindex 環境變數; PYTHONSAFEPATH
@ref{7bb,,PYTHONSAFEPATH} 環境變數，避免 @ref{3e2,,sys.path} 新增潛在的不安全路徑，例如目前目錄、腳本的目錄或空字串。

@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 參考手冊,Python 標準函式庫 Standard Library,Top
@anchor{extending/index doc}@anchor{4d52}@anchor{extending/index extending-and-embedding-the-python-interpreter}@anchor{4d53}@anchor{extending/index extending-index}@anchor{1e84}@anchor{extending/index translation-repo}@anchor{4d54}
@chapter 擴充和嵌入 Python 直譯器


這份說明文件描述如何在 C 或 C++ 中編寫模組，並使用新模組來擴充 Python 直譯器功能。那些模組不僅可以定義新的函式，也可以定義新的物件型別及其方法 (method)。文件內容也會描述如何將 Python 直譯器嵌入另一個應用程式中，做為一種擴充語言 (extension language) 使用。最後，它會展示如何編譯及連結擴充模組，使那些模組可以動態地（在執行環境）被載入到直譯器中，前提是底層作業系統有支援這個功能。

這份說明文件假設你具備 Python 的基礎知識。關於此語言的非正式介紹，請參閱 @ref{1e83,,Python 教學}。@ref{14a,,Python 語言參考手冊}給予此語言更為正式的定義。@ref{149,,Python 標準函式庫 (Standard Library)} 記錄了賦予此語言廣泛應用範圍的物件型別、函式與（內建的和以 Python 編寫的）模組。

關於完整的 Python/C API 詳細介紹，請參閱另外一份 @ref{1e85,,Python/C API 參考手冊}。

@menu
* 推薦的第三方工具:: 
* 不使用第三方工具建立擴充:: 
* 在更大的應用程式中嵌入 CPython 運行環境 (runtime): 在更大的應用程式中嵌入 CPython 運行環境 runtime. 

@end menu

@node 推薦的第三方工具,不使用第三方工具建立擴充,,擴充和嵌入 Python 直譯器
@anchor{extending/index recommended-third-party-tools}@anchor{4d55}
@section 推薦的第三方工具


這份指南僅涵蓋了此 CPython 版本所提供的、用以建立擴充的基本工具。有一些@ref{4d56,,第三方工具}，提供了更為簡單及更為複雜的多種方法，來為 Python 建立 C 和 C++ 擴充。

@node 不使用第三方工具建立擴充,在更大的應用程式中嵌入 CPython 運行環境 runtime,推薦的第三方工具,擴充和嵌入 Python 直譯器
@anchor{extending/index creating-extensions-without-third-party-tools}@anchor{4d57}
@section 不使用第三方工具建立擴充


本指南中的這一節將說明，在沒有第三方工具的協助下，如何建立 C 和 C ++ 擴充。它主要是寫給使用那些工具的創作者們，而不是讓你建立自己的 C 擴充的推薦方法。


@subsubheading 也參考


@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/} -- 多階段擴充模組初始化


@menu
* 以 C 或 C++ 擴充 Python:: 
* 擴充型別定義教學:: 
* Defining Extension Types; Assorted Topics: Defining Extension Types Assorted Topics. 
* 建立 C 與 C++ 擴充套件:: 
* 建置 Windows 上的 C 和 C++ 擴充:: 

@end menu

@node 以 C 或 C++ 擴充 Python,擴充型別定義教學,,不使用第三方工具建立擴充
@anchor{extending/extending doc}@anchor{4d58}@anchor{extending/extending extending-intro}@anchor{4d59}@anchor{extending/extending extending-python-with-c-or-c}@anchor{4d5a}
@subsection 以 C 或 C++ 擴充 Python


如果你會撰寫 C 程式語言，那要向 Python 新增內建模組就不困難。這種`擴充模組 (extension modules)' 可以做兩件在 Python 中無法直接完成的事：它們可以實作新的內建物件型別，並且可以呼叫 C 的函式庫函式和系統呼叫。

為了支援擴充，Python API (Application Programmers Interface) 定義了一組函式、巨集和變數，提供對 Python run-time 系統大部分面向的存取。Python API 是透過引入標頭檔 @code{"Python.h"} 來被納入到一個 C 原始碼檔案中。

擴充模組的編譯取決於其預期用途以及你的系統設定；詳細資訊將在後面的章節中提供。

@cartouche
@quotation 備註 
C 擴充介面是 CPython 所特有的，擴充模組在其他 Python 實作上無法運作。在許多情況下，可以避免撰寫 C 擴充並保留對其他實作的可移植性。例如，如果你的用例是呼叫 C 函式庫函式或系統呼叫，你應該考慮使用 @ref{2e,,ctypes} 模組或 cffi@footnote{https://cffi.readthedocs.io/} 函式庫，而不是編寫自定義的 C 程式碼。這些模組讓你可以撰寫 Python 程式碼來與 C 程式碼介接，而且比起撰寫和編譯 C 擴充模組，這些模組在 Python 實作之間更容易移植。
@end quotation
@end cartouche

@menu
* 一個簡單範例:: 
* 插曲：錯誤與例外:: 
* 回到範例:: 
* 模組的方法表和初始化函式:: 
* Compilation and Linkage:: 
* Calling Python Functions from C:: 
* Extracting Parameters in Extension Functions:: 
* Keyword Parameters for Extension Functions:: 
* Building Arbitrary Values:: 
* 參照計數:: 
* Writing Extensions in C++:: 
* Providing a C API for an Extension Module:: 

@end menu

@node 一個簡單範例,插曲：錯誤與例外,,以 C 或 C++ 擴充 Python
@anchor{extending/extending a-simple-example}@anchor{4d5b}@anchor{extending/extending extending-simpleexample}@anchor{4d5c}
@subsubsection 一個簡單範例


讓我們來建立一個叫做 @code{spam}（Monty Python 粉絲最愛的食物...）的擴充模組。假設我們要建立一個 Python 介面給 C 函式庫的函式 @code{system()} @footnote{
An interface for this function already exists in the standard module @ref{a5,,os}
--- it was chosen as a simple and straightforward example.
} 使用，這個函式接受一個以 null 終止的 (null-terminated) 字元字串做為引數，並回傳一個整數。我們希望這個函式可以在 Python 中被呼叫，如下所示：

@example
>>> import spam
>>> status = spam.system("ls -l")
@end example

首先建立一個檔案 @code{spammodule.c}。（從過去歷史來看，如果一個模組叫做 @code{spam}，包含其實作的 C 檔案就會叫做 @code{spammodule.c}；如果模組名稱很長，像是 @code{spammify}，模組名稱也可以只是 @code{spammify.c}）。

我們檔案的前兩列可以為：

@example
#define PY_SSIZE_T_CLEAN
#include <Python.h>
@end example

這會將 Python API 拉進來（你可以加入註解來說明模組的目的，也可以加入版權聲明)。

@cartouche
@quotation 備註 
由於 Python 可能定義一些影響系統上某些標準標頭檔的預處理器定義，你`必須'在引入任何標準標頭檔之前引入 @code{Python.h}。

@code{#define PY_SSIZE_T_CLEAN} 被用來表示在某些 API 中應該使用 @code{Py_ssize_t} 而不是 @code{int}。自 Python 3.13 起，它就不再是必要的了，但我們在此保留它以便向後相容。關於這個巨集的描述請參閱 @ref{624,,字串與緩衝區}。
@end quotation
@end cartouche

All user-visible symbols defined by @code{Python.h} have a prefix of @code{Py} or
@code{PY}, except those defined in standard header files.

@cartouche
@quotation 小訣竅 
For backward compatibility, @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.
If using the limited C API version 3.13 or newer, the implicit includes are:


@itemize *

@item 
@code{<assert.h>}

@item 
@code{<intrin.h>}（在 Windows 上）

@item 
@code{<inttypes.h>}

@item 
@code{<limits.h>}

@item 
@code{<math.h>}

@item 
@code{<stdarg.h>}

@item 
@code{<wchar.h>}

@item 
@code{<sys/types.h>}（如果存在）
@end itemize

If @ref{658,,Py_LIMITED_API} is not defined, or is set to version 3.12 or older,
the headers below are also included:


@itemize *

@item 
@code{<ctype.h>}

@item 
@code{<unistd.h>}（在 POSIX 上）
@end itemize

If @ref{658,,Py_LIMITED_API} is not defined, or is set to version 3.10 or older,
the headers below are also included:


@itemize *

@item 
@code{<errno.h>}

@item 
@code{<stdio.h>}

@item 
@code{<stdlib.h>}

@item 
@code{<string.h>}
@end itemize
@end quotation
@end cartouche

接下來我們要加入到模組檔案的是 C 函式，當 Python 運算式 @code{spam.system(string)} 要被求值 (evaluated) 時就會被呼叫（我們很快就會看到它最後是如何被呼叫的）：

@example
static PyObject *
spam_system(PyObject *self, PyObject *args)
@{
    const char *command;
    int sts;

    if (!PyArg_ParseTuple(args, "s", &command))
        return NULL;
    sts = system(command);
    return PyLong_FromLong(sts);
@}
@end example

可以很直觀地從 Python 的引數串列（例如單一的運算式 @code{"ls -l"}）直接轉換成傳給 C 函式的引數。C 函式總是有兩個引數，習慣上會命名為 `self' 和 `args'。

對於模組層級的函式，`self' 引數會指向模組物件；而對於方法來說則是指向物件的實例。

`args' 引數會是一個指向包含引數的 Python 元組物件的指標。元組中的每一項都對應於呼叫的引數串列中的一個引數。引數是 Python 物件 --- 為了在我們的 C 函式中對它們做任何事情，我們必須先將它們轉換成 C 值。Python API 中的 @ref{3bf,,PyArg_ParseTuple()} 函式能夠檢查引數型別並將他們轉換為 C 值。它使用模板字串來決定所需的引數型別以及儲存轉換值的 C 變數型別。稍後會再詳細說明。

如果所有的引數都有正確的型別，且其元件已儲存在傳入位址的變數中，則 @ref{3bf,,PyArg_ParseTuple()} 會回傳 true（非零）。如果傳入的是無效引數串列則回傳 false（零）。在後者情況下，它也會產生適當的例外，因此呼叫函式可以立即回傳 @code{NULL}（就像我們在範例中所看到的）。

@node 插曲：錯誤與例外,回到範例,一個簡單範例,以 C 或 C++ 擴充 Python
@anchor{extending/extending extending-errors}@anchor{4d5d}@anchor{extending/extending intermezzo-errors-and-exceptions}@anchor{4d5e}
@subsubsection 插曲：錯誤與例外


在整個 Python 直譯器中的一個重要慣例為：當一個函式失敗時，它就應該設定一個例外條件，並回傳一個錯誤值（通常是 @code{-1} 或一個 @code{NULL} 指標）。例外資訊會儲存在直譯器執行緒狀態的三個成員中。如果沒有例外，它們就會是 @code{NULL}。否則，它們是由 @ref{893,,sys.exc_info()} 所回傳的 Python 元組中的 C 等效元組。它們是例外型別、例外實例和回溯物件。了解它們對於理解錯誤是如何傳遞是很重要的。

Python API 定義了許多能夠設定各種類型例外的函式。

最常見的是 @ref{795,,PyErr_SetString()}。它的引數是一個例外物件和一個 C 字串。例外物件通常是預先定義的物件，例如 @ref{4d5f,,PyExc_ZeroDivisionError}。C 字串則指出錯誤的原因，並被轉換為 Python 字串物件且被儲存為例外的「關聯值 (associated value)」。

另一個有用的函式是 @ref{4d60,,PyErr_SetFromErrno()}，它只接受一個例外引數，並透過檢查全域變數 @code{errno} 來建立關聯值。最一般的函式是 @ref{794,,PyErr_SetObject()}，它接受兩個物件引數，即例外和它的關聯值。你不需要對傳給任何這些函式的物件呼叫 @ref{788,,Py_INCREF()}。

你可以使用 @ref{1ba7,,PyErr_Occurred()} 來不具破壞性地測試例外是否已被設定。這會回傳目前的例外物件，如果沒有例外發生則回傳 @code{NULL}。你通常不需要呼叫 @ref{1ba7,,PyErr_Occurred()} 來查看函式呼叫是否發生錯誤，因為你應可從回傳值就得知。

當函式 `f' 呼叫另一個函式 `g' 時檢測到後者失敗，`f' 本身應該回傳一個錯誤值（通常是 @code{NULL} 或 @code{-1}）。它`不'應該呼叫 @code{PyErr_*} 函式的其中一個，這會已被 `g' 呼叫過。`f' 的呼叫者然後也應該回傳一個錯誤指示給`它的'呼叫者，同樣`不會'呼叫 @code{PyErr_*}，依此類推 --- 最詳細的錯誤原因已經被首先檢測到它的函式回報了。一旦錯誤到達 Python 直譯器的主要迴圈，這會中止目前執行的 Python 程式碼，並嘗試尋找 Python 程式設計者指定的例外處理程式。

（在某些情況下，模組可以透過呼叫另一個 @code{PyErr_*} 函式來提供更詳細的錯誤訊息，在這種情況下這樣做是沒問題的。然而這一般來說並非必要，而且可能會導致錯誤原因資訊的遺失：大多數的操作都可能因為各種原因而失敗。）

要忽略由函式呼叫失敗所設定的例外，必須明確地呼叫 @ref{122c,,PyErr_Clear()} 來清除例外條件。C 程式碼唯一要呼叫 @ref{122c,,PyErr_Clear()} 的情況為當它不想將錯誤傳遞給直譯器而想要完全是自己來處理它時（可能是要再嘗試其他東西，或者假裝什麼都沒出錯）。

每個失敗的 @code{malloc()} 呼叫都必須被轉換成一個例外 --- @code{malloc()}（或 @code{realloc()}）的直接呼叫者必須呼叫 @ref{4d61,,PyErr_NoMemory()} 並回傳一個失敗指示器。所有建立物件的函式（例如 @ref{1af0,,PyLong_FromLong()}）都已經這麼做了，所以這個注意事項只和那些直接呼叫 @code{malloc()} 的函式有關。

還要注意的是，有 @ref{3bf,,PyArg_ParseTuple()} 及同系列函式的這些重要例外，回傳整數狀態的函式通常會回傳一個正值或 0 表示成功、回傳 @code{-1} 表示失敗，就像 Unix 系統呼叫一樣。

最後，在回傳錯誤指示器時要注意垃圾清理（透過對你已經建立的物件呼叫 @ref{98a,,Py_XDECREF()} 或 @ref{789,,Py_DECREF()}）！

你完全可以自行選擇要產生的例外。有一些預先宣告的 C 物件會對應到所有內建的 Python 例外，例如 @ref{4d5f,,PyExc_ZeroDivisionError}，你可以直接使用它們。當然，你應該明智地選擇例外，像是不要使用 @ref{4d62,,PyExc_TypeError} 來表示檔案無法打開（應該是 @ref{4d63,,PyExc_OSError}）。如果引數串列有問題，@ref{3bf,,PyArg_ParseTuple()} 函式通常會引發 @ref{4d62,,PyExc_TypeError}。如果你有一個引數的值必須在一個特定的範圍內或必須滿足其他條件，則可以使用 @ref{4d64,,PyExc_ValueError}。

你也可以定義一個你的模組特有的新例外。最簡單的方式是在檔案的開頭宣告一個靜態全域物件變數：

@example
static PyObject *SpamError = NULL;
@end example

and initialize it by calling @ref{146a,,PyErr_NewException()} in the module's
@ref{b6c,,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{b6c,,Py_mod_exec} function is called.

For now, let's avoid the issue: we will block repeated initialization by raising an
@ref{653,,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

請注意，例外物件的 Python 名稱是 @code{spam.error}。如同@ref{1b3a,,內建的例外}所述，@ref{146a,,PyErr_NewException()} 函式可能會建立一個基底類別為 @ref{bc4,,Exception} 的類別（除非傳入另一個類別來代替 @code{NULL}）。

請注意，@code{SpamError} 變數保留了對新建立的例外類別的參照；這是故意的！因為外部程式碼可能會從模組中移除這個例外，所以需要一個對這個類別的參照來確保它不會被丟棄而導致 @code{SpamError} 變成一個迷途指標 (dangling pointer)。如果它變成迷途指標，那產生例外的 C 程式碼可能會導致核心轉儲 (core dump) 或其他不預期的 side effect。

For now, the @ref{789,,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.

我們稍後會討論 @ref{16c7,,PyMODINIT_FUNC} 作為函式回傳型別的用法。

可以在你的擴充模組中呼叫 @ref{795,,PyErr_SetString()} 來引發 @code{spam.error} 例外，如下所示：

@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 回到範例,模組的方法表和初始化函式,插曲：錯誤與例外,以 C 或 C++ 擴充 Python
@anchor{extending/extending back-to-the-example}@anchor{4d65}@anchor{extending/extending backtoexample}@anchor{4d66}
@subsubsection 回到範例


回到我們的範例函式，現在你應該可以理解這個陳述式了：

@example
if (!PyArg_ParseTuple(args, "s", &command))
    return NULL;
@end example

如果在引數串列中檢測到錯誤則會回傳 @code{NULL}（回傳物件指標之函式的錯誤指示器），其依賴於 @ref{3bf,,PyArg_ParseTuple()} 設定的例外，否則引數的字串值會已被複製到區域變數 @code{command} 中。這是一個指標賦值，你不應該修改它所指向的字串（所以在標準 C 中，@code{command} 變數應該正確地被宣告為 @code{const char *command}）。

接下來的陳述式會呼叫 Unix 函式 @code{system()}，並將剛才從 @ref{3bf,,PyArg_ParseTuple()} 得到的字串傳給它：

@example
sts = system(command);
@end example

我們的 @code{spam.system()} 函式必須以 Python 物件的形式來回傳 @code{sts} 的值。這是透過 @ref{1af0,,PyLong_FromLong()} 函式來達成。

@example
return PyLong_FromLong(sts);
@end example

在這種情況下它會回傳一個整數物件。(是的，在 Python 中連整數也是堆積 (heap) 上的物件！)

如果你有一個不回傳任何有用引數的 C 函式（一個回傳 void 的函式），對應的 Python 函式必須回傳 @code{None}。你需要以下這個慣例來達成（由 @ref{1668,,Py_RETURN_NONE} 巨集實作）：

@example
Py_INCREF(Py_None);
return Py_None;
@end example

@ref{4d67,,Py_None} 是特殊 Python 物件 @code{None} 的 C 名稱。它是一個真正的 Python 物件而不是一個 @code{NULL} 指標，在大多數的情況下它的意思是「錯誤」，如我們所見過的那樣。

@node 模組的方法表和初始化函式,Compilation and Linkage,回到範例,以 C 或 C++ 擴充 Python
@anchor{extending/extending methodtable}@anchor{4d68}@anchor{extending/extending the-module-s-method-table-and-initialization-function}@anchor{4d69}
@subsubsection 模組的方法表和初始化函式


我承諾過要展示 @code{spam_system()} 是如何從 Python 程式中呼叫的。首先，我們需要在「方法表」中列出它的名稱和位址：

@example
static PyMethodDef spam_methods[] = @{
    ...
    @{"system",  spam_system, METH_VARARGS,
     "Execute a shell command."@},
    ...
    @{NULL, NULL, 0, NULL@}        /* Sentinel */
@};
@end example

請注意第三個項目 (@code{METH_VARARGS})。這是一個告訴直譯器 C 函式之呼叫方式的旗標。通常應該是 @code{METH_VARARGS} 或 @code{METH_VARARGS | METH_KEYWORDS}；@code{0} 表示是使用 @ref{3bf,,PyArg_ParseTuple()} 的一個過時變體。

當只使用 @code{METH_VARARGS} 時，函式應預期 Python 層級的參數是以元組形式傳入且能夠接受以 @ref{3bf,,PyArg_ParseTuple()} 進行剖析；有關此函式的更多資訊將在下面提供。

如果要將關鍵字引數傳給函式，可以在第三個欄位設定 @ref{4d6a,,METH_KEYWORDS} 位元。在這種情況下，C 函式應該要能接受第三個 @code{PyObject *} 參數，這個參數將會是關鍵字的字典。可使用 @ref{61c,,PyArg_ParseTupleAndKeywords()} 來剖析這種函式的引數。

方法表必須在模組定義結構中被參照：

@example
static struct PyModuleDef spam_module = @{
    ...
    .m_methods = spam_methods,
    ...
@};
@end example

反過來說，這個結構必須在模組的初始化函式中被傳給直譯器。初始化函式必須被命名為 @code{PyInit_name()}，其中 `name' 是模組的名稱，且應該是模組檔案中唯一定義的非「靜態 (@code{static})」項目：

@example
PyMODINIT_FUNC
PyInit_spam(void)
@{
    return PyModuleDef_Init(&spam_module);
@}
@end example

請注意，@ref{16c7,,PyMODINIT_FUNC} 宣告函式的回傳型別為 @code{PyObject *}、宣告平台所需的任何特殊連結宣告、並針對 C++ 宣告函式為 @code{extern "C"}。

@code{PyInit_spam()} is called when each interpreter imports its module
@code{spam} for the first time.  (See below for comments about embedding Python.)
A pointer to the module definition must be returned via @ref{4d6b,,PyModuleDef_Init()},
so that the import machinery can create the module and store it in @code{sys.modules}.

嵌入 Python 時，除非在 @code{PyImport_Inittab} 表中有相關條目，否則不會自動呼叫 @code{PyInit_spam()} 函式。要將模組加入初始化表，請使用 @ref{1a5f,,PyImport_AppendInittab()} 並在隨後選擇性地將該模組引入：

@example
#define PY_SSIZE_T_CLEAN
#include <Python.h>

int
main(int argc, char *argv[])
@{
    PyStatus status;
    PyConfig config;
    PyConfig_InitPythonConfig(&config);

    /* 在 Py_Initialize 之前加入內建模組 */
    if (PyImport_AppendInittab("spam", PyInit_spam) == -1) @{
        fprintf(stderr, "Error: could not extend in-built modules table\n");
        exit(1);
    @}

    /* 將 argv[0] 傳給 Python 直譯器 */
    status = PyConfig_SetBytesString(&config, &config.program_name, argv[0]);
    if (PyStatus_Exception(status)) @{
        goto exception;
    @}

    /* 初始化 Python 直譯器。這會是必要的。
       如果此步驟失敗就會導致嚴重錯誤。*/
    status = Py_InitializeFromConfig(&config);
    if (PyStatus_Exception(status)) @{
        goto exception;
    @}
    PyConfig_Clear(&config);

    /* 可選擇引入模組；或者
       可以延遲引入，直至嵌入式腳本
       將其引入。*/
    PyObject *pmodule = PyImport_ImportModule("spam");
    if (!pmodule) @{
        PyErr_Print();
        fprintf(stderr, "Error: could not import module 'spam'\n");
    @}

    // ... 在此使用 Python C API ...

    return 0;

  exception:
     PyConfig_Clear(&config);
     Py_ExitStatusException(status);
@}
@end example

@cartouche
@quotation 備註 
If you declare a global variable or a local static one, the module may
experience unintended side-effects on re-initialisation, for example when
removing entries from @code{sys.modules} or importing compiled modules into
multiple interpreters within a process
(or following a @code{fork()} without an intervening @code{exec()}).
If module state is not yet fully @ref{166,,isolated},
authors should consider marking the module as having no support for subinterpreters
(via @ref{4d6c,,Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED}).
@end quotation
@end cartouche

Python 原始碼發行版本中包含了一個更實質的範例模組 @code{Modules/xxlimited.c}。這個檔案可以當作模板使用，也可以簡單地當作範例來閱讀。

@node Compilation and Linkage,Calling Python Functions from C,模組的方法表和初始化函式,以 C 或 C++ 擴充 Python
@anchor{extending/extending compilation}@anchor{4d6d}@anchor{extending/extending compilation-and-linkage}@anchor{4d6e}
@subsubsection Compilation and Linkage


There are two more things to do before you can use your new extension: compiling
and linking it with the Python system.  If you use dynamic loading, the details
may depend on the style of dynamic loading your system uses; see the chapters
about building extension modules (chapter @ref{4d6f,,建立 C 與 C++ 擴充套件}) and additional
information that pertains only to building on Windows (chapter
@ref{20e8,,建置 Windows 上的 C 和 C++ 擴充}) for more information about this.

If you can't use dynamic loading, or 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.  Luckily, this is very simple on Unix: just 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,Compilation and Linkage,以 C 或 C++ 擴充 Python
@anchor{extending/extending calling-python-functions-from-c}@anchor{4d70}@anchor{extending/extending callingpython}@anchor{4d71}
@subsubsection Calling Python Functions from C


So far we have 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{1a8,,-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{788,,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{16fc,,METH_VARARGS} flag; this is described in section @ref{4d68,,模組的方法表和初始化函式}.  The
@ref{3bf,,PyArg_ParseTuple()} function and its arguments are documented in section
@ref{4d72,,Extracting Parameters in Extension Functions}.

The macros @ref{c51,,Py_XINCREF()} and @ref{98a,,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{4d73,,參照計數}.

@geindex PyObject_CallObject（C 函式）

Later, when it is time to call the function, you call the C function
@ref{4d74,,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{3c0,,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{4d74,,PyObject_CallObject()} returns a Python object pointer: this is the return
value of the Python function.  @ref{4d74,,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{789,,Py_DECREF()}-ed immediately after the @ref{4d74,,PyObject_CallObject()}
call.

The return value of @ref{4d74,,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{789,,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{4d74,,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{122c,,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{4d74,,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{3c0,,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{3c0,,Py_BuildValue()} may run out of memory, and this should be checked.

You may also call a function with keyword arguments by using
@ref{635,,PyObject_Call()}, which supports arguments and keyword arguments.  As in
the above example, we use @ref{3c0,,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

@node Extracting Parameters in Extension Functions,Keyword Parameters for Extension Functions,Calling Python Functions from C,以 C 或 C++ 擴充 Python
@anchor{extending/extending extracting-parameters-in-extension-functions}@anchor{4d75}@anchor{extending/extending parsetuple}@anchor{4d72}
@subsubsection Extracting Parameters in Extension Functions


@geindex PyArg_ParseTuple（C 函式）

The @ref{3bf,,PyArg_ParseTuple()} function is 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{3d3,,剖析引數與建置數值} in the Python/C API Reference
Manual.  The remaining arguments must be addresses of variables whose type is
determined by the format string.

Note that while @ref{3bf,,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!

一些呼叫範例：

@example
#define PY_SSIZE_T_CLEAN
#include <Python.h>
@end example

@example
int ok;
int i, j;
long k, l;
const char *s;
Py_ssize_t size;

ok = PyArg_ParseTuple(args, ""); /* 沒有引數 */
    /* Python 呼叫：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,以 C 或 C++ 擴充 Python
@anchor{extending/extending keyword-parameters-for-extension-functions}@anchor{4d76}@anchor{extending/extending parsetupleandkeywords}@anchor{4d77}
@subsubsection Keyword Parameters for Extension Functions


@geindex PyArg_ParseTupleAndKeywords（C 函式）

The @ref{61c,,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{3bf,,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{61c,,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{198,,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 */
@};

static struct PyModuleDef keywdarg_module = @{
    .m_base = PyModuleDef_HEAD_INIT,
    .m_name = "keywdarg",
    .m_size = 0,
    .m_methods = keywdarg_methods,
@};

PyMODINIT_FUNC
PyInit_keywdarg(void)
@{
    return PyModuleDef_Init(&keywdarg_module);
@}
@end example

@node Building Arbitrary Values,參照計數,Keyword Parameters for Extension Functions,以 C 或 C++ 擴充 Python
@anchor{extending/extending building-arbitrary-values}@anchor{4d78}@anchor{extending/extending buildvalue}@anchor{4d79}
@subsubsection Building Arbitrary Values


This function is the counterpart to @ref{3bf,,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{3bf,,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{3bf,,PyArg_ParseTuple()}: while the latter requires its
first argument to be a tuple (since Python argument lists are always represented
as tuples internally), @ref{3c0,,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 參照計數,Writing Extensions in C++,Building Arbitrary Values,以 C 或 C++ 擴充 Python
@anchor{extending/extending refcounts}@anchor{4d73}@anchor{extending/extending reference-counts}@anchor{4d7a}
@subsubsection 參照計數


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{64,,gc} module exposes a way to run the detector (the
@ref{1b3,,collect()} function), as well as configuration
interfaces and the ability to disable the detector at runtime.

@menu
* Python 中的參照計數:: 
* Ownership Rules:: 
* Thin Ice:: 
* NULL 指標:: 

@end menu

@node Python 中的參照計數,Ownership Rules,,參照計數
@anchor{extending/extending refcountsinpython}@anchor{4d7b}@anchor{extending/extending reference-counting-in-python}@anchor{4d7c}
@subsubsection 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{789,,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{789,,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 @ref{789,,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{789,,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{788,,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,Python 中的參照計數,參照計數
@anchor{extending/extending ownership-rules}@anchor{4d7d}@anchor{extending/extending ownershiprules}@anchor{4d7e}
@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{1af0,,PyLong_FromLong()} and @ref{3c0,,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,
@ref{1af0,,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{5e7,,PyObject_GetAttrString()}.  The picture
is less clear, here, however, since a few common routines are exceptions:
@ref{4d7f,,PyTuple_GetItem()}, @ref{5f7,,PyList_GetItem()}, @ref{620,,PyDict_GetItem()}, and
@ref{621,,PyDict_GetItemString()} all return references that you borrow from the
tuple, list or dictionary.

The function @ref{5f4,,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{788,,Py_INCREF()} to become an independent owner.  There are exactly two
important exceptions to this rule: @ref{4d80,,PyTuple_SetItem()} and
@ref{1830,,PyList_SetItem()}.  These functions take over ownership of the item passed
to them --- even if they fail!  (Note that @ref{4d81,,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{788,,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 指標,Ownership Rules,參照計數
@anchor{extending/extending thin-ice}@anchor{4d82}@anchor{extending/extending thinice}@anchor{4d83}
@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{789,,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{1830,,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,
@ref{1830,,PyList_SetItem()} calls @ref{789,,Py_DECREF()} on the replaced item,
which invokes replaced item's corresponding
@ref{4d84,,tp_dealloc} function. During
deallocation, @ref{4d84,,tp_dealloc} calls
@ref{c94,,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 @ref{1830,,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{46e,,global lock}
protecting Python's entire object space.
However, it is possible to temporarily release this lock using the macro
@ref{4d85,,Py_BEGIN_ALLOW_THREADS}, and to re-acquire it using
@ref{c76,,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 指標,,Thin Ice,參照計數
@anchor{extending/extending null-pointers}@anchor{4d86}@anchor{extending/extending nullpointers}@anchor{4d87}
@subsubsection NULL 指標


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{788,,Py_INCREF()} and @ref{789,,Py_DECREF()} do not check for @code{NULL}
pointers --- however, their variants @ref{c51,,Py_XINCREF()} and @ref{98a,,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,參照計數,以 C 或 C++ 擴充 Python
@anchor{extending/extending cplusplus}@anchor{4d88}@anchor{extending/extending writing-extensions-in-c}@anchor{4d89}
@subsubsection 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++,以 C 或 C++ 擴充 Python
@anchor{extending/extending providing-a-c-api-for-an-extension-module}@anchor{4d8a}@anchor{extending/extending using-capsules}@anchor{1555}
@subsubsection 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 (as discussed in section
@ref{4d68,,模組的方法表和初始化函式}). 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{4d8b,,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{1b24,,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 section
@ref{4d5c,,一個簡單範例}. 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{b6c,,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{b6c,,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{28a1,,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 Assorted Topics,以 C 或 C++ 擴充 Python,不使用第三方工具建立擴充
@anchor{extending/newtypes_tutorial doc}@anchor{1ae1}@anchor{extending/newtypes_tutorial defining-extension-types-tutorial}@anchor{4d8c}@anchor{extending/newtypes_tutorial defining-new-types}@anchor{4d8d}@anchor{extending/newtypes_tutorial translation-repo}@anchor{4d8e}
@subsection 擴充型別定義教學


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{169,,str}
and @ref{24d,,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,,擴充型別定義教學
@anchor{extending/newtypes_tutorial dnt-basics}@anchor{4d8f}@anchor{extending/newtypes_tutorial the-basics}@anchor{4d90}
@subsubsection The Basics


The @ref{8fd,,CPython} runtime sees all Python objects as variables of type
@ref{5d7,,PyObject}*, which serves as a "base type" for all Python objects.
The @ref{5d7,,PyObject} structure itself only contains the object's
@ref{4d91,,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{796,,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{5d7,,PyObject}, containing a pointer to a type object and a
reference count (these can be accessed using the macros @ref{3c7,,Py_TYPE}
and @ref{2cf,,Py_REFCNT} respectively).  The reason for the macro is to
abstract away the layout and to enable additional fields in @ref{504,,debug builds}.

@cartouche
@quotation 備註 
There is no semicolon above after the @ref{14de,,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{c93,,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{c93,,PyTypeObject} in @code{object.h} has
many more @ref{b7b,,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{ba,,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{226d,,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{b75,,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{16a0,,__bases__}, or else it will not be able to call your type's
@ref{799,,__new__()} method without getting an error.  You can avoid this problem by
ensuring that your type has a larger value for @ref{b75,,tp_basicsize} than its
base type does.  Most of the time, this will be true anyway, because either your
base type will be @ref{c75,,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{4d92,,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{4d93,,tp_doc}.

@example
.tp_doc = PyDoc_STR("Custom objects"),
@end example

To enable object creation, we have to provide a @ref{798,,tp_new}
handler.  This is the equivalent of the Python method @ref{799,,__new__()}, but
has to be specified explicitly.  In this case, we can just use the default
implementation provided by the API function @ref{4d94,,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{4d95,,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,擴充型別定義教學
@anchor{extending/newtypes_tutorial adding-data-and-methods-to-the-basic-example}@anchor{4d96}
@subsubsection 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{4d84,,tp_dealloc} member:

@example
.tp_dealloc = Custom_dealloc,
@end example

This method first clears the reference counts of the two Python attributes.
@ref{98a,,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{4d97,,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{798,,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{799,,__new__()} method.
It is not required to define a @code{tp_new} member, and indeed many extension
types will simply reuse @ref{4d94,,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{4d98,,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{4d98,,tp_alloc}
result against @code{NULL} before proceeding.

@cartouche
@quotation 備註 
We didn't fill the @ref{4d98,,tp_alloc} slot ourselves. Rather
@ref{97a,,PyType_Ready()} fills it for us by inheriting it from our base class,
which is @ref{c75,,object} by default.  Most types use the default allocation
strategy.
@end quotation
@end cartouche

@cartouche
@quotation 備註 
If you are creating a co-operative @ref{798,,tp_new} (one
that calls a base type's @ref{798,,tp_new} or @ref{799,,__new__()}),
you must `not' try to determine what method to call using method resolution
order at runtime.  Always statically determine what type you are going to
call, and call its @ref{798,,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{198,,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{79a,,tp_init} slot.

@example
.tp_init = Custom_init,
@end example

The @ref{79a,,tp_init} slot is exposed in Python as the
@ref{8b7,,__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{8b7,,__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{4d99,,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{4d99,,thread state} nor cause any calls back into our type's code;

@item 
when decrementing a reference count in a @ref{4d84,,tp_dealloc}
handler on a type which doesn't support cyclic garbage collection @footnote{
We relied on this in the @ref{4d84,,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{4d9a,,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{4d9b,,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{16c8,,METH_NOARGS} flag to indicate that the method
is expecting no arguments other than `self')

and assign it to the @ref{4d9c,,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{4d9d,,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{b6b,,PyModuleDef} struct, and update the full class
name in the @ref{c93,,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,擴充型別定義教學
@anchor{extending/newtypes_tutorial providing-finer-control-over-data-attributes}@anchor{4d9e}
@subsubsection 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{dad,,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{4d9f,,tp_getset} slot:

@example
.tp_getset = Custom_getsetters,
@end example

The last item in a @ref{dad,,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{79a,,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{98a,,Py_XDECREF()} calls can be converted to
@ref{789,,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,擴充型別定義教學
@anchor{extending/newtypes_tutorial supporting-cyclic-garbage-collection}@anchor{4da0}
@subsubsection Supporting cyclic garbage collection


Python has a @ref{1765,,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{169,,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{4da1,,Py_VISIT()} macro that automates calling visit
functions.  With @ref{4da1,,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{979,,tp_traverse} implementation must name its
arguments exactly `visit' and `arg' in order to use @ref{4da1,,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{791,,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{98a,,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{791,,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{791,,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{16f9,,PyObject_GC_UnTrack()} before clearing members.
Here is our reimplemented deallocator using @ref{16f9,,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{978,,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{4d98,,tp_alloc} or
@ref{4d97,,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,擴充型別定義教學
@anchor{extending/newtypes_tutorial subclassing-other-types}@anchor{4da2}
@subsubsection 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{c93,,PyTypeObject} it needs. It can be difficult to share
these @ref{c93,,PyTypeObject} structures between extension modules.

In this example we will create a @code{SubList} type that inherits from the
built-in @ref{24d,,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{14de,,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{8b7,,__init__()} method of the base
type.

This pattern is important when writing a type with custom
@ref{798,,tp_new} and @ref{4d84,,tp_dealloc}
members.  The @ref{798,,tp_new} handler should not actually
create the memory for the object with its @ref{4d98,,tp_alloc},
but let the base class handle it by calling its own @ref{798,,tp_new}.

The @ref{c93,,PyTypeObject} struct supports a @ref{2227,,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{4da3,,PyList_Type}; it should be done in the @ref{b6c,,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{97a,,PyType_Ready()}, the type structure must have the
@ref{2227,,tp_base} slot filled in.  When we are deriving an
existing type, it is not necessary to fill out the @ref{4d98,,tp_alloc}
slot with @ref{4d94,,PyType_GenericNew()} -- the allocation function from the base
type will be inherited.

After that, calling @ref{97a,,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++ 擴充套件,擴充型別定義教學,不使用第三方工具建立擴充
@anchor{extending/newtypes doc}@anchor{4da4}@anchor{extending/newtypes defining-extension-types-assorted-topics}@anchor{4da5}@anchor{extending/newtypes new-types-topics}@anchor{4da6}@anchor{extending/newtypes translation-repo}@anchor{4da7}
@subsection Defining Extension Types: Assorted Topics

@anchor{extending/newtypes dnt-type-methods}@anchor{4da8}
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{c93,,PyTypeObject}, with some fields only used in
@ref{504,,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{226d,,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{4da9}
@subsubsection 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{16f9,,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 函式）
@geindex PyErr_Restore（C 函式）

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{426,,PyErr_Fetch()} and
@ref{429,,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{979,,tp_traverse}
and/or @ref{4daa,,tp_clear}), some of the object's members can have been
cleared or finalized by the time @ref{4d84,,tp_dealloc} is called.  Second, in
@ref{4d84,,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 @ref{4d84,,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{4d84,,tp_dealloc}, and instead use the new
@ref{c94,,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{4dab}
@subsubsection Object Presentation


In Python, there are two ways to generate a textual representation of an object:
the @ref{1c1,,repr()} function, and the @ref{169,,str()} function.  (The @ref{1170,,print()}
function just calls @ref{169,,str()}.)  These handlers are both optional.

@example
reprfunc tp_repr;
reprfunc tp_str;
@end example

The @ref{4dac,,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{4dac,,tp_repr} handler is specified, the interpreter will supply a
representation that uses the type's @ref{1ba8,,tp_name} and a uniquely identifying
value for the object.

The @ref{4dad,,tp_str} handler is to @ref{169,,str()} what the @ref{4dac,,tp_repr} handler
described above is to @ref{1c1,,repr()}; that is, it is called when Python code calls
@ref{169,,str()} on an instance of your object.  Its implementation is very similar
to the @ref{4dac,,tp_repr} function, but the resulting string is intended for human
consumption.  If @ref{4dad,,tp_str} is not specified, the @ref{4dac,,tp_repr} handler is
used instead.

以下是個簡單的範例：

@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{4dae}
@subsubsection 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{5d7,,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{5d7,,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{4d9b}@anchor{extending/newtypes id1}@anchor{4daf}
@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{97a,,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{97a,,PyType_Ready()} is called, it uses three tables referenced by the
type object to create @ref{17fc,,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{19b5,,tp_getattro} and @ref{4db0,,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{4d9c,,tp_methods} is not @code{NULL}, it must refer to an array of
@ref{16cb,,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{4db1,,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{17fc,,descriptor} will be constructed and added to the
type which will be able to extract a value from the instance structure.  The
@ref{4db2,,type} field should contain a type code like @ref{7a5,,Py_T_INT} or
@ref{7a6,,Py_T_DOUBLE}; the value will be used to determine how to
convert Python values to and from C values.  The @ref{4db3,,flags} field is used to
store flags which control how the attribute can be accessed: you can set it to
@ref{7a7,,Py_READONLY} to prevent Python code from setting it.

An interesting advantage of using the @ref{4d9a,,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{1f5c,,__doc__} attribute.

As with the @ref{4d9c,,tp_methods} table, a sentinel entry with a @ref{4db1,,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{4db4}
@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{5d7,,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{4db5,,tp_getattr} handler is called when the object requires an attribute
look-up.  It is called in the same situations where the @ref{6f3,,__getattr__()}
method of a class would be called.

舉例來說：

@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{4db6,,tp_setattr} handler is called when the @ref{222d,,__setattr__()} or
@ref{222e,,__delattr__()} method of a class instance would be called.  When an
attribute should be deleted, the third parameter will be @code{NULL}.  Here is an
example that simply raises an exception; if this were really all you wanted, the
@ref{4db6,,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{4db7}
@subsubsection Object Comparison


@example
richcmpfunc tp_richcompare;
@end example

The @ref{4db8,,tp_richcompare} handler is called when comparisons are needed.  It is
analogous to the @ref{225f,,rich comparison methods}, like
@code{__lt__()}, and also called by @ref{4db9,,PyObject_RichCompare()} and
@ref{1c55,,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{4dba}
@subsubsection Abstract Protocol Support


Python supports a variety of `abstract' 'protocols;' the specific interfaces
provided to use these interfaces are documented in @ref{4dbb,,抽象物件層 (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{1615,,PyNumberMethods}, @ref{4dbc,,PySequenceMethods}, or
@ref{4dbd,,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{1464,,Py_hash_t} is a signed integer type with a platform-varying width.
Returning @code{-1} from @ref{4dbe,,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{774,,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{3bf,,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{61c,,PyArg_ParseTupleAndKeywords()} to extract the arguments.  If you
do not want to support keyword arguments and this is non-@code{NULL}, raise a
@ref{198,,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
/* 疊代器 */
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{16e3,,tp_iter} corresponds
to the Python @ref{e64,,__iter__()} method, while @ref{16e4,,tp_iternext}
corresponds to the Python @ref{14ce,,__next__()} method.

Any @ref{1428,,iterable} object must implement the @ref{16e3,,tp_iter}
handler, which must return an @ref{4c3,,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{16e3,,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{16e3,,tp_iter}
by returning a new reference to themselves -- and should also therefore
implement the @ref{16e4,,tp_iternext}  handler.
@end itemize

Any @ref{4c3,,iterator} object should implement both @ref{16e3,,tp_iter}
and @ref{16e4,,tp_iternext}.  An iterator's
@ref{16e3,,tp_iter} handler should return a new reference
to the iterator.  Its @ref{16e4,,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, @ref{16e4,,tp_iternext}
may return @code{NULL} without setting an exception, or it may set
@ref{df0,,StopIteration} `in addition' to returning @code{NULL}; avoiding
the exception can yield slightly better performance.  If an actual error
occurs, @ref{16e4,,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{4dbf}@anchor{extending/newtypes weakref-support}@anchor{287d}
@subsubsection 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{11a,,weakref} module.


For an object to be weakly referenceable, the extension type must set the
@code{Py_TPFLAGS_MANAGED_WEAKREF} bit of the @ref{1b73,,tp_flags}
field. The legacy @ref{b76,,tp_weaklistoffset} field should
be left as zero.

Concretely, here is how the statically declared type object would look:

@example
static PyTypeObject TrivialType = @{
    PyVarObject_HEAD_INIT(NULL, 0)
    /* ... other members omitted for brevity ... */
    .tp_flags = Py_TPFLAGS_MANAGED_WEAKREF | ...,
@};
@end example

The only further addition is that @code{tp_dealloc} needs to clear any weak
references (by calling @ref{78f,,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{4dc0}
@subsubsection More Suggestions


In order to learn how to implement any specific method for your new data type,
get the @ref{8fd,,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{1bad,,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++ 擴充套件,建置 Windows 上的 C 和 C++ 擴充,Defining Extension Types Assorted Topics,不使用第三方工具建立擴充
@anchor{extending/building doc}@anchor{4dc1}@anchor{extending/building building}@anchor{4d6f}@anchor{extending/building building-c-and-c-extensions}@anchor{4dc2}@anchor{extending/building translation-repo}@anchor{4dc3}
@subsection 建立 C 與 C++ 擴充套件


一個 CPython 的 C 擴充套件是一個共用函式庫（例如在 Linux 上的 @code{.so} 檔案，在 Windows 上的 @code{.pyd}），會匯出一個`初始化函式'。

詳見 @ref{4dc4,,Defining extension modules}。
@anchor{extending/building install-index}@anchor{10f4}
@menu
* 用 setuptools 建置 C 與 C++ 擴充套件:: 

@end menu

@node 用 setuptools 建置 C 與 C++ 擴充套件,,,建立 C 與 C++ 擴充套件
@anchor{extending/building building-c-and-c-extensions-with-setuptools}@anchor{4dc5}@anchor{extending/building setuptools-index}@anchor{10f5}
@subsubsection 用 setuptools 建置 C 與 C++ 擴充套件


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

直到 Python 3.12 版本前，@ref{3d,,distutils} 模組都被包含在標準函式庫中，現在是作為 Setuptools 的一部分來維護。

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node 建置 Windows 上的 C 和 C++ 擴充,,建立 C 與 C++ 擴充套件,不使用第三方工具建立擴充
@anchor{extending/windows doc}@anchor{4dc6}@anchor{extending/windows building-c-and-c-extensions-on-windows}@anchor{4dc7}@anchor{extending/windows building-on-windows}@anchor{20e8}@anchor{extending/windows translation-repo}@anchor{4dc8}
@subsection 建置 Windows 上的 C 和 C++ 擴充


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,,建置 Windows 上的 C 和 C++ 擴充
@anchor{extending/windows a-cookbook-approach}@anchor{4dc9}@anchor{extending/windows win-cookbook}@anchor{4dca}
@subsubsection 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{10f5,,用 setuptools 建置 C 與 C++ 擴充套件}.  If you find you really need to do
things manually, it may be instructive to study the project file for the
winsound@footnote{https://github.com/python/cpython/tree/3.14/PCbuild/winsound.vcxproj} standard library module.

@node Differences Between Unix and Windows,Using DLLs in Practice,A Cookbook Approach,建置 Windows 上的 C 和 C++ 擴充
@anchor{extending/windows differences-between-unix-and-windows}@anchor{4dcb}@anchor{extending/windows dynamic-linking}@anchor{4dcc}
@subsubsection 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{442}
@deffn {C 巨集} Py_NO_LINK_LIB

Turn off the implicit, @code{#pragma}-based linkage with the Python
library, performed inside CPython header files.


在 3.14 版被加入.

@end deffn

@node Using DLLs in Practice,,Differences Between Unix and Windows,建置 Windows 上的 C 和 C++ 擴充
@anchor{extending/windows using-dlls-in-practice}@anchor{4dcd}@anchor{extending/windows win-dlls}@anchor{4dce}
@subsubsection 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{4dcf,,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{3bf,,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{442,,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{3bf,,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 在更大的應用程式中嵌入 CPython 運行環境 runtime,,不使用第三方工具建立擴充,擴充和嵌入 Python 直譯器
@anchor{extending/index embedding-the-cpython-runtime-in-a-larger-application}@anchor{4dd0}
@section 在更大的應用程式中嵌入 CPython 運行環境 (runtime)


有時候，相較於建立一個擴充，使其在 Python 直譯器中可作為主應用程式運行，還不如將 CPython 運行環境嵌入至一個更大的應用程式中更可取。本節將涵蓋一些要成功完成此任務所涉及的細節。

@menu
* 在其它 App 內嵌入 Python:: 

@end menu

@node 在其它 App 內嵌入 Python,,,在更大的應用程式中嵌入 CPython 運行環境 runtime
@anchor{extending/embedding doc}@anchor{4dd1}@anchor{extending/embedding embedding}@anchor{211f}@anchor{extending/embedding embedding-python-in-another-application}@anchor{4dd2}
@subsection 在其它 App 內嵌入 Python


前面的章節討論了如何擴充 Python，也就是如何透過附加一個 C 函式庫來擴充 Python 的功能。但也可以反過來做：將 Python 嵌入你的 C/C++ 應用程式中。嵌入讓你的應用程式能夠以 Python 而非 C 或 C++ 來實作應用程式的某些功能。這可以用於許多目的；其中一個例子是允許使用者透過撰寫一些 Python 腳本來根據他們的需求客製化應用程式。如果某些功能用 Python 寫起來比較容易，你也可以自己使用這種方法。

嵌入 Python 與擴充 Python 類似，但不完全相同。差別在於當你擴充 Python 時，應用程式的主程式仍然是 Python 直譯器，而當你嵌入 Python，主程式可能與 Python 無關 — 相反地，應用程式的某些部分偶爾會呼叫 Python 直譯器來執行一些 Python 程式碼。

所以如果你要嵌入 Python，你要提供自己的主程式。這個主程式必須做的事情之一是初始化 Python 直譯器，或至少必須要呼叫函式 @ref{45e,,Py_Initialize()}。還有一些可選的呼叫來傳遞命令列引數給 Python。然後你就可以在應用程式的任何部分呼叫直譯器。

有幾種不同的方式來呼叫直譯器：你可以傳遞一個包含 Python 陳述式的字串給 @ref{4dd3,,PyRun_SimpleString()}，或者你可以傳遞一個 stdio 檔案指標和檔案名稱（僅用於錯誤訊息中的識別）給 @ref{4dd4,,PyRun_SimpleFile()}。你也可以呼叫前面章節中描述的較低層級操作來建構和使用 Python 物件。


@subsubheading 也參考



@table @asis

@item @ref{1e85,,Python/C API 參考手冊}

Python 的 C 介面詳細資訊在此手冊中提供。大量必要的資訊可以在這裡找到。
@end table


@menu
* 非常高階的嵌入:: 
* 超越非常高階嵌入：概觀:: 
* 純嵌入:: 
* 擴充嵌入式 Python:: 
* 在 C++ 中嵌入 Python:: 
* 在類 Unix 系統下編譯和連結:: 

@end menu

@node 非常高階的嵌入,超越非常高階嵌入：概觀,,在其它 App 內嵌入 Python
@anchor{extending/embedding high-level-embedding}@anchor{4dd5}@anchor{extending/embedding very-high-level-embedding}@anchor{4dd6}
@subsubsection 非常高階的嵌入


嵌入 Python 最簡單的形式是使用非常高階的介面。此介面用於執行 Python 腳本而無需直接與應用程式互動。例如這可以用來對檔案執行一些操作。

@example
#define PY_SSIZE_T_CLEAN
#include <Python.h>

int
main(int argc, char *argv[])
@{
    PyStatus status;
    PyConfig config;
    PyConfig_InitPythonConfig(&config);

    /* 建議但非必要 */
    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} 被用來指示某些 API 應該使用 @code{Py_ssize_t} 而不是 @code{int}。從 Python 3.13 開始不再需要它，但我們保留它以維持向後相容性。關於此巨集的描述請參閱 @ref{624,,字串與緩衝區}。
@end quotation
@end cartouche

@ref{3f0,,PyConfig.program_name} 的設定應該在 @ref{3f5,,Py_InitializeFromConfig()} 前呼叫，以告知直譯器 Python run-time 函式庫的路徑。接下來，Python 直譯器會用 @ref{45e,,Py_Initialize()} 初始化，然後執行一個硬編碼的 Python 腳本來印出日期和時間。之後，@ref{f0c,,Py_FinalizeEx()} 呼叫會關閉直譯器，接著程式結束。在真實的程式中，你可能想要從另一個來源取得 Python 腳本，或許是文字編輯器例程、檔案或資料庫。從檔案取得 Python 程式碼可以更好地使用 @ref{4dd4,,PyRun_SimpleFile()} 函式來完成，這樣可以省去分配記憶體空間和載入檔案內容的麻煩。

@node 超越非常高階嵌入：概觀,純嵌入,非常高階的嵌入,在其它 App 內嵌入 Python
@anchor{extending/embedding beyond-very-high-level-embedding-an-overview}@anchor{4dd7}@anchor{extending/embedding lower-level-embedding}@anchor{4dd8}
@subsubsection 超越非常高階嵌入：概觀


高階介面讓你能夠從應用程式中執行任意的 Python 程式碼片段，但交換資料值的過程可以說相當繁瑣。如果你想進行這類操作，應該使用較低階的呼叫。雖然需要撰寫更多的 C 程式碼，但幾乎可以實現任何功能。

需要注意的是，雖然目的不同，但擴充 Python 與嵌入 Python 其實是非常相似的操作，前面章節討論的大多數主題在這裡同樣適用。為了說明這一點，請思考從 Python 到 C 的擴充程式碼實際上做了什麼：


@enumerate 

@item 
將資料值從 Python 轉換為 C，

@item 
使用轉換後的值呼叫 C 例程，並

@item 
將呼叫中的資料值從 C 轉換為 Python。
@end enumerate

當嵌入 Python 時，介面程式碼會：


@enumerate 

@item 
將資料值從 C 轉換為 Python，

@item 
使用轉換後的值呼叫 Python 介面例程，並

@item 
將呼叫中的資料值從 Python 轉換為 C。
@end enumerate

如你所見，資料轉換的步驟只是互換了順序，以配合跨語言傳遞方向的不同。唯一的差別在於兩個資料轉換之間所呼叫的例程：在擴充時你呼叫的是 C 例程；在嵌入時則呼叫 Python 例程。

本章不會討論如何將資料從 Python 轉換為 C 或從 C 轉換回 Python，且假設讀者已經知道參照的正確使用方式與錯誤處理。由於這些部分與擴充直譯器時相同，相關資訊可參考前面的章節。

@node 純嵌入,擴充嵌入式 Python,超越非常高階嵌入：概觀,在其它 App 內嵌入 Python
@anchor{extending/embedding id1}@anchor{4dd9}@anchor{extending/embedding pure-embedding}@anchor{4dda}
@subsubsection 純嵌入


第一個程式的目標是執行 Python 腳本中的函式。就像在非常高階介面的章節中一樣，Python 直譯器不會直接與應用程式互動（但這在下一節會改變）。

執行 Python 腳本中定義函式的程式碼是：

@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

此程式碼使用 @code{argv[1]} 載入 Python 腳本，並呼叫 @code{argv[2]} 中所指定的函式。其整數引數則來自 @code{argv} 陣列中的其他值。如果你@ref{4ddb,,編譯並連結}此程式（我們稱完成的可執行檔為 @code{call}），並用它來執行 Python 腳本，例如：

@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

那麼結果應該是：

@example
$ call multiply multiply 3 2
Will compute 3 times 2
Result of call: 6
@end example

雖然以其功能而言這個程式相當龐大，但大部分的程式碼是用於 Python 與 C 之間的資料轉換以及錯誤回報。至於與嵌入 Python 有關的重點部分，則從以下開始：

@example
Py_Initialize();
pName = PyUnicode_DecodeFSDefault(argv[1]);
/* Error checking of pName left out */
pModule = PyImport_Import(pName);
@end example

在初始化直譯器後，腳本使用 @ref{15f3,,PyImport_Import()} 載入。此例程需要一個 Python 字串作為其引數，該字串使用 @ref{19da,,PyUnicode_DecodeFSDefault()} 資料轉換例程建構。

@example
pFunc = PyObject_GetAttrString(pModule, argv[2]);
/* pFunc is a new reference */

if (pFunc && PyCallable_Check(pFunc)) @{
    ...
@}
Py_XDECREF(pFunc);
@end example

腳本載入後，會使用 @ref{5e7,,PyObject_GetAttrString()} 來取得所需的名稱。如果該名稱存在，且回傳的物件是可呼叫的，便可安全地假設它是一個函式。接著，程式會以一般方式建立引數的元組。之後便以下列方式呼叫該 Python 函式：

@example
pValue = PyObject_CallObject(pFunc, pArgs);
@end example

函式回傳時，@code{pValue} 要不是 @code{NULL} 就是包含函式回傳值的參照。請務必在檢查值之後釋放參照。

@node 擴充嵌入式 Python,在 C++ 中嵌入 Python,純嵌入,在其它 App 內嵌入 Python
@anchor{extending/embedding extending-embedded-python}@anchor{4ddc}@anchor{extending/embedding extending-with-embedding}@anchor{4ddd}
@subsubsection 擴充嵌入式 Python


到目前為止，嵌入式 Python 直譯器尚無法存取應用程式本身的功能。Python API 允許透過擴充嵌入式直譯器來達成這點。也就是說，嵌入式直譯器可以由應用程式所提供的例程加以擴充。雖然聽起來複雜但其實並不難。只要暫時忘記是應用程式啟動了 Python 直譯器，改以將應用程式視為一組子程序，並撰寫一些膠合程式碼讓 Python 能夠存取這些例程，就像你撰寫一般 Python 擴充一樣。例如：

@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

在 @code{main()} 函式的正上方插入上述程式碼。同時，在呼叫 @ref{45e,,Py_Initialize()} 之前插入以下兩個陳述式：

@example
numargs = argc;
PyImport_AppendInittab("emb", &PyInit_emb);
@end example

這兩行初始化 @code{numargs} 變數，並讓 @code{emb.numargs()} 函式可供嵌入式 Python 直譯器使用。有了這些擴充後，Python 腳本便可以執行像是以下的操作

@example
import emb
print("Number of arguments", emb.numargs())
@end example

在真實的應用程式中，這些方法會向 Python 公開應用程式的 API。

@c TODO: threads, code examples do not really behave well if errors happen
@c (what to watch out for)

@node 在 C++ 中嵌入 Python,在類 Unix 系統下編譯和連結,擴充嵌入式 Python,在其它 App 內嵌入 Python
@anchor{extending/embedding embedding-python-in-c}@anchor{4dde}@anchor{extending/embedding embeddingincplusplus}@anchor{4ddf}
@subsubsection 在 C++ 中嵌入 Python


也可以將 Python 嵌入 C++ 程式中；具體如何做取決於所使用的 C++ 系統的細節；一般來說，你需要用 C++ 撰寫主程式，並使用 C++ 編譯器來編譯和連結你的程式。不需要使用 C++ 重新編譯 Python 本身。

@node 在類 Unix 系統下編譯和連結,,在 C++ 中嵌入 Python,在其它 App 內嵌入 Python
@anchor{extending/embedding compiling}@anchor{4ddb}@anchor{extending/embedding compiling-and-linking-under-unix-like-systems}@anchor{4de0}
@subsubsection 在類 Unix 系統下編譯和連結


要找到傳遞給編譯器（和連結器）的正確旗標以便將 Python 直譯器嵌入你的應用程式中，並不一定是簡單的事，特別是因為 Python 需要載入作為 C 動態擴充（@code{.so} 檔案）實作的函式庫模組，而這些模組又必須與 Python 進行連結。

要找出所需的編譯器和連結器旗標，你可以執行作為安裝過程的一部分產生的 @code{python`X.Y'-config} 腳本（也可能有 @code{python3-config} 腳本可用）。此腳本提供多種選項，其中以下幾個最為實用：


@itemize *

@item 
@code{pythonX.Y-config --cflags} 會給你編譯時建議的旗標：

@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} 會給你連結時建議的旗標：

@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 備註 
為了避免多個 Python 安裝之間產生混淆（特別是系統自帶的 Python 與自行編譯的 Python 之間），建議使用 @code{python`X.Y'-config} 的絕對路徑，如上面的例子所示。
@end quotation
@end cartouche

如果此程序對你不起作用（並不保證在所有類 Unix 平台上都能運作；不過我們歡迎@ref{4de1,,錯誤回報}），你將需要參閱系統的動態連結相關文件，並／或檢查 Python 的 @code{Makefile}（可使用 @ref{4829,,sysconfig.get_makefile_filename()} 來找到其位置）和編譯選項。在這種情況下，@ref{e1,,sysconfig} 模組是一個實用的工具，可用於以程式化方式擷取並組合所需的組態值。例如：

@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)

@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 參考手冊,安裝 Python 模組,擴充和嵌入 Python 直譯器,Top
@anchor{c-api/index doc}@anchor{4de2}@anchor{c-api/index c-api-index}@anchor{1e85}@anchor{c-api/index python-c-api-reference-manual}@anchor{4de3}@anchor{c-api/index translation-repo}@anchor{4de4}
@chapter Python/C API 參考手冊


對於想要編寫擴充模組或是嵌入 Python 的 C 和 C++ 程式設計師們，這份手冊記錄了可使用的 API（應用程式介面）。在@ref{1e84,,擴充和嵌入 Python 直譯器}中也有相關的內容，它描述了編寫擴充的一般原則，但並沒有詳細說明 API 函式。

@menu
* 簡介: 簡介<10>. 
* C API 穩定性:: 
* The Very High Level Layer:: 
* 參照計數: 參照計數<3>. 
* 例外處理:: 
* Defining extension modules:: 
* 工具:: 
* 抽象物件層 (Abstract Objects Layer): 抽象物件層 Abstract Objects Layer. 
* 具體物件層:: 
* 初始化、終結化與執行緒:: 
* Python 初始化設定:: 
* 記憶體管理:: 
* 物件實作支援:: 
* API 和 ABI 版本管理:: 
* 監控 C API:: 
* Generating Execution Events:: 

@end menu

@node 簡介<10>,C API 穩定性,,Python/C API 參考手冊
@anchor{c-api/intro doc}@anchor{4de5}@anchor{c-api/intro api-intro}@anchor{4de6}@anchor{c-api/intro introduction}@anchor{4de7}
@section 簡介


對於 Python 的應用程式開發介面使得 C 和 C++ 開發者能夠在各種層級存取 Python 直譯器。該 API 同樣可用於 C++，但為簡潔起見，通常將其稱為 Python/C API。使用 Python/C API 有兩個不同的原因，第一個是為特定目的來編寫`擴充模組'；這些是擴充 Python 直譯器的 C 模組，這可能是最常見的用法。第二個原因是在更大的應用程式中將 Python 作為零件使用；這種技術通常在應用程式中稱為 `embedding'（嵌入式）Python。

編寫擴充模組是一個相對容易理解的過程，其中「食譜 (cookbook)」方法很有效。有幾種工具可以在一定程度上自動化該過程，儘管人們從早期就將 Python 嵌入到其他應用程式中，但嵌入 Python 的過程並不像編寫擴充那樣簡單。

不論你是嵌入還是擴充 Python，許多 API 函式都是很有用的；此外，大多數嵌入 Python 的應用程式也需要提供自定義擴充模組，因此在嘗試將 Python 嵌入實際應用程式之前熟悉編寫擴充可能是個好主意。

@menu
* Language version compatibility:: 
* 編寫標準:: 
* 引入檔案 (include files): 引入檔案 include files. 
* 有用的巨集:: 
* 物件、型別和參照計數:: 
* 例外: 例外<22>. 
* 嵌入式Python:: 
* 除錯建置:: 
* Recommended third party tools:: 

@end menu

@node Language version compatibility,編寫標準,,簡介<10>
@anchor{c-api/intro language-version-compatibility}@anchor{4de8}
@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 編寫標準,引入檔案 include files,Language version compatibility,簡介<10>
@anchor{c-api/intro coding-standards}@anchor{4de9}
@subsection 編寫標準


如果你正在編寫要引入於 CPython 中的 C 程式碼，你`必須'遵循 
@geindex Python Enhancement Proposals; PEP 7
PEP 7@footnote{https://peps.python.org/pep-0007/} 中定義的指南和標準。無論你貢獻的 Python 版本如何，這些指南都適用。對於你自己的第三方擴充模組，則不必遵循這些約定，除非你希望最終將它們貢獻給 Python。

@node 引入檔案 include files,有用的巨集,編寫標準,簡介<10>
@anchor{c-api/intro api-includes}@anchor{97f}@anchor{c-api/intro include-files}@anchor{4dea}
@subsection 引入檔案 (include files)


使用 Python/C API 所需的所有函式、型別和巨集的定義都透過以下這幾行來在你的程式碼中引入：

@example
#define PY_SSIZE_T_CLEAN
#include <Python.h>
@end example

這意味著會引入以下標準標頭：@code{<stdio.h>}、@code{<string.h>}、@code{<errno.h>}、@code{<limits.h>}、@code{<assert.h>} 和 @code{<stdlib.h>}（如果可用）。

@cartouche
@quotation 備註 
由於 Python 可能會定義一些會影響某些系統上標準標頭檔的預處理器 (pre-processor)，因此你`必須'在引入任何標準標頭檔之前引入 @code{Python.h}。

建議在引入 @code{Python.h} 之前都要定義 @code{PY_SSIZE_T_CLEAN}。有關此巨集的說明，請參閱@ref{3d3,,剖析引數與建置數值}。
@end quotation
@end cartouche

所有定義於 Python.h 中且使用者可見的名稱（另外透過標準標頭檔引入的除外）都具有 @code{Py} 或 @code{_Py} 前綴。以 @code{_Py} 開頭的名稱供 Python 實作內部使用，擴充編寫者不應使用。結構成員名稱沒有保留前綴。

@cartouche
@quotation 備註 
使用者程式碼不應定義任何以 @code{Py} 或 @code{_Py} 開頭的名稱。這會讓讀者感到困惑，並危及使用者程式碼在未來 Python 版本上的可移植性，這些版本可能會定義以這些前綴之一開頭的其他名稱。
@end quotation
@end cartouche

標頭檔通常隨 Python 一起安裝。在 Unix 上它們位於目錄 @code{`prefix'/include/pythonversion/} 和 @code{`exec_prefix'/include/pythonversion/}，其中 @ref{2015,,prefix} 和 @ref{2016,,exec_prefix} 由 Python 的 @code{configure} 腳本的相應參數定義，`version' 是 @code{'%d.%d' % sys.version_info[:2]}。在 Windows 上，標頭安裝在 @code{`prefix'/include} 中，其中 @code{prefix} 是指定給安裝程式 (installer) 用的安裝目錄。

要引入標頭，請將兩個（如果不同）目錄放在編譯器的引入搜尋路徑 (search path) 中。`不要'將父目錄放在搜尋路徑上，然後使用 @code{#include <pythonX.Y/Python.h>}；這會在多平台建置上壞掉，因為 @ref{2015,,prefix} 下獨立於平台的標頭包括來自 @ref{2016,,exec_prefix} 的平台特定標頭。

C++ 使用者應注意，儘管 API 完全使用 C 來定義，但標頭檔適當地將入口點聲明為 @code{extern "C"}。因此，無需執行任何特殊操作即可使用 C++ 中的 API。

@node 有用的巨集,物件、型別和參照計數,引入檔案 include files,簡介<10>
@anchor{c-api/intro useful-macros}@anchor{4deb}
@subsection 有用的巨集


Python 標頭檔中定義了幾個有用的巨集，大多被定義在它們有用的地方附近（例如 @ref{1668,,Py_RETURN_NONE}、@ref{16c7,,PyMODINIT_FUNC}），其他是更通用的工具程式。以下並不一定是完整的列表。

@geindex Py_ABS (C macro)
@anchor{c-api/intro c Py_ABS}@anchor{4dec}
@deffn {C 巨集} Py_ABS (x)

回傳 @code{x} 的絕對值。


在 3.3 版被加入.

@end deffn

@geindex Py_ALWAYS_INLINE (C macro)
@anchor{c-api/intro c Py_ALWAYS_INLINE}@anchor{1b6d}
@deffn {C 巨集} Py_ALWAYS_INLINE

要求編譯器總是嵌入靜態行內函式 (static inline function)，編譯器可以忽略它並決定不嵌入該函式。

在禁用函式嵌入的除錯模式下建置 Python 時，它可用於嵌入有性能要求的靜態行內函式。例如，MSC 在除錯模式下建置時禁用函式嵌入。

盲目地使用 Py_ALWAYS_INLINE 標記靜態行內函式可能會導致更差的性能（例如程式碼大小增加）。在成本/收益分析方面，編譯器通常比開發人員更聰明。

如果 Python 是@ref{504,,在除錯模式下建置}（如果 @ref{17b1,,Py_DEBUG} 巨集有被定義），@ref{1b6d,,Py_ALWAYS_INLINE} 巨集就什麼都不會做。

它必須在函式回傳型別之前被指定。用法：

@example
static inline Py_ALWAYS_INLINE int random(void) @{ return 4; @}
@end example


在 3.11 版被加入.

@end deffn

@geindex Py_CHARMASK (C macro)
@anchor{c-api/intro c Py_CHARMASK}@anchor{4ded}
@deffn {C 巨集} Py_CHARMASK (c)

引數必須是 [-128, 127] 或 [0, 255] 範圍內的字元或整數。這個巨集會將 @code{c} 轉換為 @code{unsigned char} 並回傳。
@end deffn

@geindex Py_DEPRECATED (C macro)
@anchor{c-api/intro c Py_DEPRECATED}@anchor{c92}
@deffn {C 巨集} Py_DEPRECATED (version)

將其用於已棄用的聲明。巨集必須放在符號名稱之前。

範例：

@example
Py_DEPRECATED(3.8) PyAPI_FUNC(int) Py_OldFunction(void);
@end example


在 3.8 版的變更: 新增了 MSVC 支援。

@end deffn

@geindex Py_GETENV (C macro)
@anchor{c-api/intro c Py_GETENV}@anchor{4dee}
@deffn {C 巨集} Py_GETENV (s)

類似於 @code{getenv(s)}，但如果在命令列上傳遞了 @ref{b4d,,-E} 則回傳 @code{NULL} （請見 @ref{409,,PyConfig.use_environment}）。
@end deffn

@geindex Py_MAX (C macro)
@anchor{c-api/intro c Py_MAX}@anchor{4def}
@deffn {C 巨集} Py_MAX (x, y)

回傳 @code{x} 和 @code{y} 之間的最大值。


在 3.3 版被加入.

@end deffn

@geindex Py_MEMBER_SIZE (C macro)
@anchor{c-api/intro c Py_MEMBER_SIZE}@anchor{4df0}
@deffn {C 巨集} Py_MEMBER_SIZE (type, member)

以位元組為單位回傳結構 (@code{type}) @code{member} 的大小。


在 3.6 版被加入.

@end deffn

@geindex Py_MIN (C macro)
@anchor{c-api/intro c Py_MIN}@anchor{4df1}
@deffn {C 巨集} Py_MIN (x, y)

回傳 @code{x} 和 @code{y} 之間的最小值。


在 3.3 版被加入.

@end deffn

@geindex Py_NO_INLINE (C macro)
@anchor{c-api/intro c Py_NO_INLINE}@anchor{1789}
@deffn {C 巨集} Py_NO_INLINE

禁用函式的嵌入。例如，它減少了 C 堆疊的消耗：對大量嵌入程式碼的 LTO+PGO 建置很有用（請參閱 bpo-33720@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33720}）。

用法：

@example
Py_NO_INLINE static int random(void) @{ return 4; @}
@end example


在 3.11 版被加入.

@end deffn

@geindex Py_STRINGIFY (C macro)
@anchor{c-api/intro c Py_STRINGIFY}@anchor{4df2}
@deffn {C 巨集} Py_STRINGIFY (x)

將 @code{x} 轉換為 C 字串。例如 @code{Py_STRINGIFY(123)} 會回傳 @code{"123"}。


在 3.4 版被加入.

@end deffn

@geindex Py_UNREACHABLE (C macro)
@anchor{c-api/intro c Py_UNREACHABLE}@anchor{da9}
@deffn {C 巨集} Py_UNREACHABLE ()

當你的設計中有無法達到的程式碼路徑時，請使用此選項。例如在 @code{case} 語句已涵蓋了所有可能值的 @code{switch} 陳述式中的 @code{default:} 子句。在你可能想要呼叫 @code{assert(0)} 或 @code{abort()} 的地方使用它。

在發布模式 (release mode) 下，巨集幫助編譯器最佳化程式碼，並避免有關無法存取程式碼的警告。例如該巨集是在發布模式下於 GCC 使用 @code{__builtin_unreachable()} 來實作。

@code{Py_UNREACHABLE()} 的一個用途是，在對一個永不回傳但並未聲明為 @code{_Py_NO_RETURN} 的函式之呼叫後使用。

如果程式碼路徑是極不可能但在特殊情況下可以到達，則不得使用此巨集。例如在低記憶體條件下或系統呼叫回傳了超出預期範圍的值。在這種情況下，最好將錯誤回報給呼叫者。如果無法回報錯誤則可以使用 @ref{b71,,Py_FatalError()}。


在 3.7 版被加入.

@end deffn

@geindex Py_UNUSED (C macro)
@anchor{c-api/intro c Py_UNUSED}@anchor{19dc}
@deffn {C 巨集} Py_UNUSED (arg)

將此用於函式定義中未使用的參數以消除編譯器警告。例如：@code{int func(int a, int Py_UNUSED(b)) @{ return a; @}}。


在 3.4 版被加入.

@end deffn

@geindex PyDoc_STRVAR (C macro)
@anchor{c-api/intro c PyDoc_STRVAR}@anchor{1c24}
@deffn {C 巨集} PyDoc_STRVAR (name, str)

建立一個名為 @code{name} 的變數，可以在文件字串中使用。如果 Python 是在沒有文件字串的情況下建置，則該值將為空。

如 
@geindex Python Enhancement Proposals; PEP 7
PEP 7@footnote{https://peps.python.org/pep-0007/} 中所指明，使用 @ref{1c24,,PyDoc_STRVAR} 作為文件字串可以支援在沒有文件字串的情況下建置 Python。

範例：

@example
PyDoc_STRVAR(pop_doc, "Remove and return the rightmost element.");

static PyMethodDef deque_methods[] = @{
    // ...
    @{"pop", (PyCFunction)deque_pop, METH_NOARGS, pop_doc@},
    // ...
@}
@end example
@end deffn

@geindex PyDoc_STR (C macro)
@anchor{c-api/intro c PyDoc_STR}@anchor{1ac0}
@deffn {C 巨集} PyDoc_STR (str)

為給定的輸入字串建立一個文件字串，如果文件字串被禁用則建立空字串。

如 
@geindex Python Enhancement Proposals; PEP 7
PEP 7@footnote{https://peps.python.org/pep-0007/} 中所指明，使用 @ref{1ac0,,PyDoc_STR} 指定文件字串以支援在沒有文件字串下建置 Python。

範例：

@example
static PyMethodDef pysqlite_row_methods[] = @{
    @{"keys", (PyCFunction)pysqlite_row_keys, METH_NOARGS,
        PyDoc_STR("Returns the keys of the row.")@},
    @{NULL, NULL@}
@};
@end example
@end deffn

@node 物件、型別和參照計數,例外<22>,有用的巨集,簡介<10>
@anchor{c-api/intro api-objects}@anchor{4df3}@anchor{c-api/intro objects-types-and-reference-counts}@anchor{4df4}
@subsection 物件、型別和參照計數


@geindex object（物件）;type（型別）

大多數 Python/C API 函式都有一個或多個引數以及一個型別為 @ref{5d7,,PyObject}* 的回傳值，此型別是一個指標，指向一個表示任意 Python 物件的晦暗 (opaque) 資料型別。由於在大多數情況下，Python 語言以相同的方式處理所有 Python 物件型別（例如賦值、作用域規則和引數傳遞），因此它們應該由單個 C 型別來表示。幾乎所有的 Python 物件都存在於堆積 (heap) 中：你永遠不會聲明 @ref{5d7,,PyObject} 型別的自動變數或靜態變數，只能聲明 @ref{5d7,,PyObject}* 型別的指標變數。唯一的例外是型別物件；由於它們絕不能被釋放，因此它們通常是靜態 @ref{c93,,PyTypeObject} 物件。

所有 Python 物件（甚至是 Python 整數）都有一個型別 (`type') 和一個參照計數 (`reference count')。一個物件的型別決定了它是什麼種類的物件（例如一個整數、一個 list 或一個使用者定義的函式；還有更多型別，請見@ref{21e4,,標準型別階層}）。對於每個眾所周知的型別，都有一個巨集來檢查物件是否屬於該型別；例如，若（且唯若）*a* 指向的物件是 Python list 時，@code{PyList_Check(a)} 為真。

@menu
* 參照計數: 參照計數<2>. 
* 型別:: 

@end menu

@node 參照計數<2>,型別,,物件、型別和參照計數
@anchor{c-api/intro api-refcounts}@anchor{4df5}@anchor{c-api/intro reference-counts}@anchor{4df6}
@subsubsection 參照計數


參照計數很重要，因為現今的電腦記憶體大小是有限的（而且通常是非常有限的）；它計算有多少個不同的地方用有了一個物件的@ref{5da,,強參照}。這樣的地方可以是另一個物件，或者全域（或靜態）C 變數，或者某個 C 函式中的本地變數。當一個物件的最後一個@ref{5da,,強參照}被釋放時（即其的參照計數變為零），該物件將被解除配置 (deallocated)。如果它包含對其他物件的參照，則它們的參照會被釋放。如果這樣的釋放使得再也沒有任何對於它們的參照，則可以依次為那些其他物件解除配置，依此類推。（此處相互參照物件的存在是個明顯的問題；目前，解決方案是「就不要那樣做」。）

@geindex Py_INCREF（C 函式）
@geindex Py_DECREF（C 函式）

參照計數總是被明確地操作。正常的方法是使用巨集 @ref{788,,Py_INCREF()} 來取得對於物件的參照（即參照計數加一），並使用巨集 @ref{789,,Py_DECREF()} 來釋放參照（即將參照計數減一）。@ref{789,,Py_DECREF()} 巨集比 incref 巨集複雜得多，因為它必須檢查參照計數是否變為零，然後呼叫物件的釋放器 (deallocator)。釋放器是包含在物件型別結構中的函式指標。特定型別的釋放器，在如果是一個複合物件型別（例如 list）時負責釋放物件中包含的其他物件的參照，並執行任何需要的額外完結步驟。參照計數不可能溢出；至少與虛擬記憶體中用來保存參照計數的不同記憶體位置數量一樣多的位元會被使用（假設 @code{sizeof(Py_ssize_t) >= sizeof(void*)}）。因此參照計數增加是一個簡單的操作。

沒有必要為每個包含物件指標的本地變數物件都持有一個@ref{5da,,強參照}（即增加參照計數）。理論上，當變數指向它時，物件的參照計數會增加 1，而當變數離開作用域時就會減少 1。然而這兩者會相互抵消，所以最後參照計數沒有改變。使用參照計數的唯一真正原因是防止物件還有變數指向它時被解除配置。如果我們知道至少有一個物件的其他參照生存了至少與我們的變數一樣久，就不需要臨時增加建立新的@ref{5da,,強參照}（即增加參照計數）。出現這種情況的一個重要情況是在從 Python 呼叫的擴充模組中作為引數傳遞給 C 函式的物件；呼叫機制保證在呼叫期間保持對每個參數的參照。

然而，一個常見的陷阱是從一個 list 中提取一個物件並保留它一段時間而不取得其參照。某些其他操作可能會從列表中刪除該物件，減少其參照計數並可能取消分配它。真正的危險是看似無害的操作可能會叫用可以執行此操作的任意 Python 程式碼；有一個程式碼路徑允許控制權從 @ref{789,,Py_DECREF()} 回歸使用者，因此幾乎任何操作都有潛在危險。

一種安全的方法是都使用通用 (generics) 操作（名稱以 @code{PyObject_}、@code{PyNumber_}、@code{PySequence_} 或 @code{PyMapping_} 開頭的函式）。這些操作總是建立新的對於它們回傳物件的@ref{5da,,強參照}（即增加其參照計數）。這讓呼叫者有責任在處理完結果後呼叫 @ref{789,,Py_DECREF()}；這就成為第二本質。

@menu
* 參照計數詳細資訊:: 

@end menu

@node 參照計數詳細資訊,,,參照計數<2>
@anchor{c-api/intro api-refcountdetails}@anchor{4df7}@anchor{c-api/intro reference-count-details}@anchor{4df8}
@subsubsection 參照計數詳細資訊


Python/C API 中函式的參照計數行為最好用`參照的所有權'來解釋。所有權附屬於參照而非物件（物件並非被擁有，它們總是共享的）。「擁有參照」意味著當不再需要該參照時，負責在其上呼叫 Py_DECREF。所有權也可以轉移，這意味著接收參照所有權的程式碼最終會負責在不需要參照時透過呼叫 @ref{789,,Py_DECREF()} 或 @ref{98a,,Py_XDECREF()} 釋放參照 --- 或者將這個責任再傳遞出去（通常是給它的呼叫者）。當一個函式將參照的所有權傳遞給它的呼叫者時，呼叫者被稱為接收到一個`新'參照。當沒有所有權轉移時，呼叫者被稱為`借用'參照。如果是@ref{3d5,,借用參照}就不需要做任何事情。

相反地，當呼叫的函式傳入物件的參照時，有兩種可能性：函式有`竊取 (steal)' 物件的參照，或者沒有。 `竊取參照'意味著當你將參照傳遞給函式時，該函式假定它現在擁有該參照，並且你不再對它負責。

@geindex PyList_SetItem（C 函式）
@geindex PyTuple_SetItem（C 函式）

很少有函式會竊取參照；兩個值得注意的例外是 @ref{1830,,PyList_SetItem()} 和 @ref{4d80,,PyTuple_SetItem()}，它們竊取了對項目的參照（但不是對項目所在的 tuple 或 list 的參照！）。因為有著使用新建立的物件來增加 (populate) tuple 或 list 的習慣，這些函式旨在竊取參照；例如，建立 tuple @code{(1, 2, "three")} 的程式碼可以如下所示（先暫時忘記錯誤處理；更好的編寫方式如下所示）：

@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

這裡 @ref{1af0,,PyLong_FromLong()} 會回傳一個新的參照，它立即被 @ref{4d80,,PyTuple_SetItem()} 竊取。如果你想繼續使用一個物件，儘管對它的參照將被竊取，請在呼叫參照竊取函式之前使用 @ref{788,,Py_INCREF()} 來取得另一個參照。

附帶地說，@ref{4d80,,PyTuple_SetItem()} 是設定 tuple 項目的`唯一'方法； @ref{1cfc,,PySequence_SetItem()} 和 @ref{4df9,,PyObject_SetItem()} 拒絕這樣做，因為 tuple 是一種不可變 (immutable) 的資料型別。你應該只對你自己建立的 tuple 使用 @ref{4d80,,PyTuple_SetItem()}。

可以使用 @ref{4dfa,,PyList_New()} 和 @ref{1830,,PyList_SetItem()} 編寫用於填充列表的等效程式碼。

但是在實際操作中你很少會使用這些方法來建立和增加 tuple 和 list。有一個通用函式 @ref{3c0,,Py_BuildValue()} 可以從 C 值建立最常見的物件，由 `format string' 引導。例如上面的兩個程式碼可以用以下程式碼替換（它還負責了錯誤檢查）：

@example
PyObject *tuple, *list;

tuple = Py_BuildValue("(iis)", 1, 2, "three");
list = Py_BuildValue("[iis]", 1, 2, "three");
@end example

更常見的是以那些借用參照的項目來使用 @ref{4df9,,PyObject_SetItem()} 及其系列函式，比如傳遞給你正在編寫的函式的引數。在那種情況下，他們關於參照的行為會比較穩健，因為你不取得新的一個參照就可以放棄參照（「讓它被竊取」）。例如，此函式將 list（實際上是任何可變序列）的所有項目設定於給定項目：

@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()

函式回傳值的情況略有不同。雖然傳遞對大多數函式的參照不會改變你對該參照的所有權責任，但許多回傳物件參照的函式會給你該參照的所有權。原因很簡單：在很多情況下，回傳的物件是即時建立的，你獲得的參照是對該物件的唯一參照。因此回傳物件參照的通用函式，如 @ref{5e2,,PyObject_GetItem()} 和 @ref{1cfb,,PySequence_GetItem()}，總是回傳一個新的參照（呼叫者成為參照的所有者）。

重要的是要意識到你是否擁有一個函式回傳的參照只取決於你呼叫哪個函式 --- `羽毛 (plumage)*（作為引數傳遞給函式的物件之型別）*不會進入它！'因此，如果你使用 @ref{5f7,,PyList_GetItem()} 從 list 中提取一個項目，你不會擁有其參照 --- 但如果你使用 @ref{1cfb,,PySequence_GetItem()} 從同一 list 中取得相同的項目（且恰好使用完全相同的引數），你確實會擁有對回傳物件的參照。

@geindex PyList_GetItem（C 函式）
@geindex PySequence_GetItem（C 函式）

以下是一個範例，說明如何編寫函式來計算一個整數 list 中項目的總和；一次使用 @ref{5f7,,PyList_GetItem()}，一次使用 @ref{1cfb,,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 型別,,參照計數<2>,物件、型別和參照計數
@anchor{c-api/intro api-types}@anchor{4dfb}@anchor{c-api/intro types}@anchor{4dfc}
@subsubsection 型別


有少數幾個其他的資料型別在 Python/C API 中發揮重要作用；大多數是簡單的 C 型別，例如 int、long、double 和 char*。一些結構型別被用於描述用於列出模組所匯出的函式或新物件型別的資料屬性的靜態表，其他則用於描述複數的值。這些將與使用它們的函式一起討論。

@geindex Py_ssize_t (C type)
@anchor{c-api/intro c Py_ssize_t}@anchor{c4c}
@deffn {C 型別} type Py_ssize_t
` 為 @ref{76e,,穩定 ABI 的一部分}.'
一個帶符號的整數型別，使得 @code{sizeof(Py_ssize_t) == sizeof(size_t)}。 C99 沒有直接定義這樣的東西（size_t 是無符號整數型別）。有關詳細資訊，請參閱 
@geindex Python Enhancement Proposals; PEP 353
PEP 353@footnote{https://peps.python.org/pep-0353/}。 @code{PY_SSIZE_T_MAX} 是 @ref{c4c,,Py_ssize_t} 型別的最大正值。
@end deffn

@node 例外<22>,嵌入式Python,物件、型別和參照計數,簡介<10>
@anchor{c-api/intro api-exceptions}@anchor{4dfd}@anchor{c-api/intro exceptions}@anchor{4dfe}
@subsection 例外


如果需要特定的錯誤處理，Python 開發者就只需要處理例外；未處理的例外會自動傳遞給呼叫者，然後傳遞給呼叫者的呼叫者，依此類推，直到它們到達頂層直譯器，在那裡它們透過堆疊回溯 (stack trace) 回報給使用者。

@geindex PyErr_Occurred（C 函式）

然而，對於 C 開發者來說，錯誤檢查總是必須是顯式的。除非在函式的文件中另有明確聲明，否則 Python/C API 中的所有函式都可以引發例外。通常當一個函式遇到錯誤時，它會設定一個例外，丟棄它擁有的任何物件參照，並回傳一個錯誤指示器。如果沒有另外文件記錄，這個指示器要麼是 @code{NULL} 不然就是 @code{-1}，取決於函式的回傳型別。有些函式會回傳布林值 true/false 結果，false 表示錯誤。很少有函式不回傳明確的錯誤指示器或者有不明確的回傳值，而需要使用 @ref{1ba7,,PyErr_Occurred()} 明確測試錯誤。這些例外都會被明確地記錄於文件。

@geindex PyErr_SetString（C 函式）
@geindex PyErr_Clear（C 函式）

例外的狀態會在個別執行緒的儲存空間 (per-thread storage) 中維護（這相當於在非執行緒應用程式中使用全域儲存空間）。執行緒可以處於兩種狀態之一：發生例外或未發生例外。函式 @ref{1ba7,,PyErr_Occurred()} 可用於檢查這一點：當例外發生時，它回傳對例外型別物件的借用參照，否則回傳 @code{NULL}。設定例外狀態的函式有很多：@ref{795,,PyErr_SetString()} 是最常見的（儘管不是最通用的）設定例外狀態的函式，而 @ref{122c,,PyErr_Clear()} 是用來清除例外狀態。

完整的例外狀態由三個（都可以為 @code{NULL} 的）物件組成：例外型別、對應的例外值和回溯。這些與 @code{sys.exc_info()} 的 Python 結果具有相同的含義；但是它們並不相同：Python 物件表示由 Python @ref{8f0,,try} ... @ref{1ab,,except} 陳述式處理的最後一個例外，而 C 層級的例外狀態僅在例外在 C 函式間傳遞時存在，直到它到達 Python 位元組碼直譯器的主迴圈，該迴圈負責將它傳遞給 @code{sys.exc_info()} 和其系列函式。

@geindex exc_info （sys 模組中）

請注意，從 Python 1.5 開始，從 Python 程式碼存取例外狀態的首選且支援執行緒安全的方法是呼叫 @ref{893,,sys.exc_info()} 函式，它回傳 Python 程式碼的個別執行緒例外狀態。此外，兩種存取例外狀態方法的語義都發生了變化，因此捕獲例外的函式將保存和恢復其執行緒的例外狀態，從而保留其呼叫者的例外狀態。這可以防止例外處理程式碼中的常見錯誤，這些錯誤是由看似無辜的函式覆蓋了正在處理的例外而引起的；它還替回溯中被堆疊框 (stack frame) 參照的物件減少了通常不需要的生命週期延長。

作為一般原則，呼叫另一個函式來執行某些任務的函式應該檢查被呼叫函式是否引發了例外，如果是，則將例外狀態傳遞給它的呼叫者。它應該丟棄它擁有的任何物件參照，並回傳一個錯誤指示符，但它`不應該'設定另一個例外 --- 這將覆蓋剛剛引發的例外，並丟失關於錯誤確切原因的重要資訊。

@geindex sum_sequence()

上面的 @code{sum_sequence()} 範例展示了一個檢測例外並將其繼續傳遞的例子。碰巧這個例子在檢測到錯誤時不需要清理任何擁有的參照。以下範例函式展示了一些錯誤清理。首先，為了提醒你為什麼喜歡 Python，我們展示了等效的 Python 程式碼：

@example
def incr_item(dict, key):
    try:
        item = dict[key]
    except KeyError:
        item = 0
    dict[key] = item + 1
@end example

@geindex incr_item()

這是相應的 C 程式碼：

@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 函式）
@geindex PyErr_Clear（C 函式）
@geindex Py_XDECREF（C 函式）

這個例子代表了在 C 語言中對使用 @code{goto} 陳述句的認同！它闡述了以 @ref{4dff,,PyErr_ExceptionMatches()} 和 @ref{122c,,PyErr_Clear()} 來處理特定的例外，以及以 @ref{98a,,Py_XDECREF()} 來配置其所擁有且可能為 @code{NULL} 的參照（注意名稱中的 @code{'X'}；@ref{789,,Py_DECREF()} 在遇到 @code{NULL} 參照時會崩潰）。重要的是，用於保存擁有的參照的變數被初始化為 @code{NULL} 以使其能夠順利作用；同樣地，回傳值被初始化為 @code{-1}（失敗），並且僅在最後一次呼叫成功後才設定為成功。

@node 嵌入式Python,除錯建置,例外<22>,簡介<10>
@anchor{c-api/intro api-embedding}@anchor{4e00}@anchor{c-api/intro embedding-python}@anchor{4e01}
@subsection 嵌入式Python


只有 Python 直譯器的嵌入者（而不是擴充編寫者）需要擔心的一項重要任務是 Python 直譯器的初始化與完成階段。直譯器的大部分功能只能在直譯器初始化後使用。

@geindex Py_Initialize（C 函式）
@geindex module（模組）;builtins（內建）
@geindex module（模組）;__main__
@geindex module（模組）;sys
@geindex module（模組）;search（搜尋）;path（路徑）
@geindex path（sys 模組中）

基本的初始化函式是 @ref{45e,,Py_Initialize()}。這會初始化帶有載入模組的表，並建立基礎模組 @ref{13,,builtins}、@ref{1,,__main__} 和 @ref{df,,sys}。它還會初始化模組搜索路徑 (@code{sys.path})。

@ref{45e,,Py_Initialize()} 不設定「腳本引數列表 (script argument list)」 (@code{sys.argv})。如果稍後將要執行的 Python 程式碼需要此變數，則必須設定 @ref{3ef,,PyConfig.argv} 和 @ref{1bdd,,PyConfig.parse_argv}，請見 @ref{63e,,Python 初始化配置}。

在大多數系統上（特別是在 Unix 和 Windows 上，儘管細節略有不同），@ref{45e,,Py_Initialize()} 會假設Python 函式庫相對於 Python 直譯器可執行檔案的位置固定，並根據其對標準 Python 直譯器可執行檔案位置的最佳猜測來計算模組搜尋路徑。或者更詳細地說，它會在 shell 命令搜尋路徑（環境變數 
@geindex PATH
@geindex 環境變數; PATH
@code{PATH}）中找到名為 @code{python} 的可執行檔案，並在其父目錄中查找一個名為 @code{lib/python`X.Y'} 的目錄的相對位置。

例如，如果在 @code{/usr/local/bin/python} 中找到 Python 可執行檔案，它將假定函式庫位於 @code{/usr/local/lib/python`X.Y'} 中。（事實上這個特定的路徑也是「後備 (fallback)」位置，當在 
@geindex PATH
@geindex 環境變數; PATH
@code{PATH} 中找不到名為 @code{python} 的可執行檔案時使用。）使用者可以透過設定環境變數來覆蓋此行為 
@geindex PYTHONHOME
@geindex 環境變數; PYTHONHOME
@ref{3ee,,PYTHONHOME}，或者透過設定 
@geindex PYTHONPATH
@geindex 環境變數; PYTHONPATH
@ref{1218,,PYTHONPATH} 在標準路徑前面插入額外的目錄。

@geindex Py_GetPath（C 函式）
@geindex Py_GetPrefix（C 函式）
@geindex Py_GetExecPrefix（C 函式）
@geindex Py_GetProgramFullPath（C 函式）

嵌入的應用程式可以透過在呼叫 @ref{3f5,,Py_InitializeFromConfig()} `之前'設定 @ref{3f0,,PyConfig.program_name} 來引導搜尋。請注意 
@geindex PYTHONHOME
@geindex 環境變數; PYTHONHOME
@ref{3ee,,PYTHONHOME} 仍然覆蓋它並且 
@geindex PYTHONPATH
@geindex 環境變數; PYTHONPATH
@ref{1218,,PYTHONPATH} 仍然插入在標準路徑的前面。需要完全控制權的應用程式必須實作自己的 @ref{3e1,,Py_GetPath()}、@ref{3e3,,Py_GetPrefix()}、@ref{3e7,,Py_GetExecPrefix()} 和 @ref{3ea,,Py_GetProgramFullPath()}（全部定義在 @code{Modules/getpath.c})。

@geindex Py_IsInitialized（C 函式）

有時會希望能夠「取消初始化 (uninitialize)」Python。例如，應用程式可能想要重新開始（再次呼叫 @ref{45e,,Py_Initialize()}）或者應用程式簡單地完成了對 Python 的使用並想要釋放 Python 分配的記憶體。這可以透過呼叫 @ref{f0c,,Py_FinalizeEx()} 來完成。如果 Python 目前處於初始化狀態，函式 @ref{4e02,,Py_IsInitialized()} 會回傳 true。有關這些功能的更多資訊將在後面的章節中給出。請注意 @ref{f0c,,Py_FinalizeEx()} `不會'釋放由 Python 直譯器分配的所有記憶體，例如目前無法釋放被擴充模組所分配的記憶體。

@node 除錯建置,Recommended third party tools,嵌入式Python,簡介<10>
@anchor{c-api/intro api-debugging}@anchor{4e03}@anchor{c-api/intro debugging-builds}@anchor{4e04}
@subsection 除錯建置


Python 可以在建置時使用多個巨集來啟用對直譯器和擴充模組的額外檢查，這些檢查往往會在執行環境 (runtime) 增加大量開銷 (overhead)，因此預設情況下不啟用它們。

Python 原始碼發佈版本中的 @code{Misc/SpecialBuilds.txt} 檔案有一份包含多種除錯構置的完整列表，為支援追蹤參照計數、為記憶體分配器除錯或對主直譯器迴圈進行低階分析的建置。本節的其餘部分將僅描述最常用的建置。

@geindex Py_DEBUG (C macro)
@anchor{c-api/intro c Py_DEBUG}@anchor{17b1}
@deffn {C 巨集} Py_DEBUG
@end deffn

使用定義的 @code{Py_DEBUG} 巨集編譯直譯器會生成 @ref{504,,Python 的除錯建置}。 @code{Py_DEBUG} 在 Unix 建置中要透過在 @code{./configure} 命令中加入 @ref{65e,,--with-pydebug} 來啟用。非 Python 限定的 @code{_DEBUG} 巨集的存在也暗示了這一點。當 @code{Py_DEBUG} 在 Unix 建置中啟用時，編譯器最佳化會被禁用。

除了下面描述的參照計數除錯之外，還會執行額外的檢查，請參閱 @ref{504,,Python 除錯建置}。

定義 @code{Py_TRACE_REFS} 來啟用參照追蹤（參見@ref{62e,,設定 --with-trace-refs 選項}）。當有定義時，透過向每個 @ref{5d7,,PyObject} 新增兩個額外欄位來維護有效物件的循環雙向鍊表 (circular doubly linked list)。全體分配也有被追蹤。退出時將印出所有現行參照。（在交互模式下，這發生在直譯器運行的每個陳述句之後。）

有關更多詳細資訊，請參閱 Python 原始碼發布版中的 @code{Misc/SpecialBuilds.txt}。

@node Recommended third party tools,,除錯建置,簡介<10>
@anchor{c-api/intro c-api-tools}@anchor{4d56}@anchor{c-api/intro recommended-third-party-tools}@anchor{4e05}
@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 穩定性,The Very High Level Layer,簡介<10>,Python/C API 參考手冊
@anchor{c-api/stable doc}@anchor{4e06}@anchor{c-api/stable c-api-stability}@anchor{4e07}@anchor{c-api/stable stable}@anchor{76e}@anchor{c-api/stable translation-repo}@anchor{4e08}
@section C API 穩定性


除非有另外記錄於文件，Python 的 C API 被包含在向後相容性策略 
@geindex Python Enhancement Proposals; PEP 387
PEP 387@footnote{https://peps.python.org/pep-0387/} 中。大多數改動都是相容於原始碼的（通常只會增加新的 API）。更改現有 API 或刪除 API 僅在棄用期後或修復嚴重問題時進行。

CPython 的應用程式二進位介面 (Application Binary Interface, ABI) 在次要版本中是向前和向後相容的（如果它們以相同的方式編譯；請參閱下面的@ref{4e09,,平台注意事項}）。因此，為 Python 3.10.0 編譯的程式碼將能夠在 3.10.8 上運行，反之亦然，但 3.9.x 和 3.11.x 就需要分別編譯。

C API 有兩層級，有不同的穩定性期望：


@itemize -

@item 
@ref{762,,不穩定 API}，可能會在次要版本中發生變化，而沒有棄用階段。會在名稱中以 @code{PyUnstable} 前綴來標記。

@item 
@ref{62f,,受限 API}，在多個次要版本之間相容。當有定義 @ref{658,,Py_LIMITED_API} 時，只有這個子集會從 @code{Python.h} 公開。
@end itemize

下面將更詳細地討論這些內容。

帶有底線前綴的名稱是私有 API (private API)，像是 @code{_Py_InternalState}，即使在補丁版本 (patch release) 中也可能被更改，不會另行通知。如果你需要使用這個 API，可以聯繫 CPython 開發者@footnote{https://discuss.python.org/c/core-dev/c-api/30} 並針對你的使用方法來討論是否新增公開的 API。

@menu
* 不穩定的 C API:: 
* 穩定的應用程式二進位介面:: 
* 平台注意事項:: 
* 受限 API 的內容:: 

@end menu

@node 不穩定的 C API,穩定的應用程式二進位介面,,C API 穩定性
@anchor{c-api/stable id1}@anchor{4e0a}@anchor{c-api/stable unstable-c-api}@anchor{762}
@subsection 不穩定的 C API


@geindex PyUnstable

任何以 @code{PyUnstable} 前綴命名的 API 都會公開 CPython 實作細節，並可能在每個次要版本中進行更改（例如從 3.9 到 3.10），而不會出現任何棄用警告。但是它不會在錯誤修復發布版本中發生變化（例如從 3.10.0 到 3.10.1）。

它通常用於專門的低階工具，例如偵錯器。

使用此 API 的專案應該要遵循 CPython 開發細節，並花費額外的力氣來針對這些變動來做調整。

@node 穩定的應用程式二進位介面,平台注意事項,不穩定的 C API,C API 穩定性
@anchor{c-api/stable id2}@anchor{4e0b}@anchor{c-api/stable stable-application-binary-interface}@anchor{4dcf}
@subsection 穩定的應用程式二進位介面


為簡單起見，本文件討論`擴充 (extension)'，但受限 API 和穩定 ABI 在所有 API 使用方式中都以相同的方式運作 -- 例如在嵌入式 Python (embedding Python) 中。

@menu
* 受限 C API:: 
* 穩定 ABI:: 
* 受限 API 範圍和性能:: 
* 受限 API 注意事項:: 

@end menu

@node 受限 C API,穩定 ABI,,穩定的應用程式二進位介面
@anchor{c-api/stable id3}@anchor{4e0c}@anchor{c-api/stable limited-c-api}@anchor{62f}
@subsubsection 受限 C API


Python 3.2 引入了`受限 API (Limited API)'，它是 Python C API 的一個子集。僅使用受限 API 的擴充可以只編譯一次就被載入於多個版本的 Python。受限 API 的內容@ref{995,,列在下方}。

@geindex Py_LIMITED_API (C macro)
@anchor{c-api/stable c Py_LIMITED_API}@anchor{658}
@deffn {C 巨集} Py_LIMITED_API

在包含 @code{Python.h} 之前定義此巨集以選擇只使用受限 API，並挑選受限 API 版本。

將 @code{Py_LIMITED_API} 定義為對應於你的擴充有支援的最低 Python 版本的 @ref{380,,PY_VERSION_HEX} 值。該擴充與從指定版本開始的所有 Python 3 版本之 ABI 相容，並且可以使用過去版本有引入的受限 API。

與其直接使用 @code{PY_VERSION_HEX} 巨集，不如寫死 (hardcode) 最小次要版本（例如代表 Python 3.10 的 @code{0x030A0000}），以便在使用未來的 Python 版本進行編譯時仍保持穩定性。

你還可以將 @code{Py_LIMITED_API} 定義為 @code{3}，這與 @code{0x03020000}（Python 3.2，引入了受限 API 的版本）相同。
@end deffn

@node 穩定 ABI,受限 API 範圍和性能,受限 C API,穩定的應用程式二進位介面
@anchor{c-api/stable id4}@anchor{4e0d}@anchor{c-api/stable stable-abi}@anchor{4e0e}
@subsubsection 穩定 ABI


為了實現它，Python 提供了一個`穩定 ABI (Stable ABI)'：一組將在各個 Python 3.x 版本之間保持 ABI 相容的符號。

@cartouche
@quotation 備註 
穩定 ABI 可以防止 ABI 問題，例如由於結構布局或函式簽名變化導致缺少符號或數據損壞的鏈接器 (linker) 錯誤。然而，Python 的其他變化可能會改變 `行為' 的擴充。有關詳細信息，請參閱 Python 的向後相容性政策 (
@geindex Python Enhancement Proposals; PEP 387
PEP 387@footnote{https://peps.python.org/pep-0387/})。
@end quotation
@end cartouche

穩定 ABI 被包含在@ref{62f,,受限 API} 中開放的符號，但也包含其他符號 - 例如，支援舊版受限 API 所必需的函式。

在 Windows 上，使用穩定 ABI 的擴充應該連接到 @code{python3.dll} 而不是特定版本的函式庫，例如 @code{python39.dll}。

在某些平台上，Python 將查找並加載以 @code{abi3} 標籤命名的共享函式庫檔案（例如 @code{mymodule.abi3.so}）。它不檢查此類擴充是否符合穩定的 ABI。確保的責任在使用者（或者打包工具）身上，例如使用 3.10+ 受限 API 建置的擴充不會為較低版本的 Python 所安裝。

穩定 ABI 中的所有函式都作為函式存在於 Python 的共享函式庫中，而不僅是作為巨集。這使得它們可被用於不使用 C 預處理器 (preprocessor) 的語言。

@node 受限 API 範圍和性能,受限 API 注意事項,穩定 ABI,穩定的應用程式二進位介面
@anchor{c-api/stable limited-api-scope-and-performance}@anchor{4e0f}
@subsubsection 受限 API 範圍和性能


受限 API 的目標是允許使用完整的 C API 進行所有可能的操作，但可能會降低性能。

例如，雖然 @ref{5f7,,PyList_GetItem()} 可用，但它的「不安全」巨集變體 @ref{4e10,,PyList_GET_ITEM()} 為不可用。巨集運行可以更快，因為它可以依賴 list 物件的特定版本實作細節。

如果沒有定義 @code{Py_LIMITED_API}，一些 C API 函式將被嵌入或被替換為巨集。定義 @code{Py_LIMITED_API} 會禁用嵌入，從而隨著 Python 資料結構的改進而提高穩定性，但可能會降低性能。

透過省略 @code{Py_LIMITED_API} 定義，可以使用特定版本的 ABI 編譯受限 API 擴充。這可以提高該 Python 版本的性能，但會限制相容性。使用 @code{Py_LIMITED_API} 編譯將產生一個擴充，可以在特定版本的擴充不可用的地方發布 — 例如，用於即將發布的 Python 版本的預發布版本 (prerelease)。

@node 受限 API 注意事項,,受限 API 範圍和性能,穩定的應用程式二進位介面
@anchor{c-api/stable limited-api-caveats}@anchor{4e11}
@subsubsection 受限 API 注意事項


請注意，使用 @code{Py_LIMITED_API} 進行編譯`不'完全保證程式碼符合@ref{62f,,受限 API} 或@ref{4e0e,,穩定 ABI}。@code{Py_LIMITED_API} 僅涵蓋定義，但 API 還包括其他議題，例如預期的語義 (semantic)。

@code{Py_LIMITED_API} 無法防範的一個問題是使用在較低 Python 版本中無效的引數來呼叫函式。例如一個開始接受 @code{NULL} 作為引數的函式。在 Python 3.9 中，@code{NULL} 現在代表選擇預設行為，但在 Python 3.8 中，引數將被直接使用，導致 @code{NULL} 取消參照 (dereference) 且崩潰 (crash)。類似的引數適用於結構 (struct) 的欄位。

另一個問題是，當有定義 @code{Py_LIMITED_API} 時，一些結構欄位目前不會被隱藏，即使它們是受限 API 的一部分。

出於這些原因，我們建議要以它支援的`所有'次要 Python 版本來測試擴充，並且最好使用`最低'版本進行建置。

我們也建議要查看所有使用過的 API 的文件，檢查它是否明確屬於受限 API。即使有定義 @code{Py_LIMITED_API}，一些私有聲明也會因為技術原因（或者甚至是無意地，例如臭蟲）而被公開出來。

另請注意，受限 API 不一定是穩定的：在 Python 3.8 中使用 @code{Py_LIMITED_API} 進行編譯意味著擴充將能以 Python 3.12 運行，但不一定能以 Python 3.12 `編譯'。特別是如果穩定 ABI 保持穩定，部分受限 API 可能會被棄用和刪除。

@node 平台注意事項,受限 API 的內容,穩定的應用程式二進位介面,C API 穩定性
@anchor{c-api/stable platform-considerations}@anchor{4e12}@anchor{c-api/stable stable-abi-platform}@anchor{4e09}
@subsection 平台注意事項


ABI 穩定性不僅取決於 Python，還取決於使用的編譯器、低階函式庫和編譯器選項。出於@ref{4e0e,,穩定 ABI} 的目的，這些細節定義了一個「平台」。它們通常取決於作業系統種類和處理器架構

每個特定的 Python 發布者都有責任確保特定平台上的所有 Python 版本都以不破壞穩定 ABI 的方式建置。@code{python.org} 和許多第三方發布者發布的 Windows 和 macOS 版本就是這種情況。

@node 受限 API 的內容,,平台注意事項,C API 穩定性
@anchor{c-api/stable contents-of-limited-api}@anchor{4e13}@anchor{c-api/stable limited-api-list}@anchor{995}
@subsection 受限 API 的內容


目前，@ref{62f,,受限 API} 包括以下項目：



@itemize *

@item 
@ref{779,,PY_VECTORCALL_ARGUMENTS_OFFSET}

@item 
@ref{4e14,,PyAIter_Check()}

@item 
@ref{1791,,PyArg_Parse()}

@item 
@ref{3bf,,PyArg_ParseTuple()}

@item 
@ref{61c,,PyArg_ParseTupleAndKeywords()}

@item 
@ref{16fa,,PyArg_UnpackTuple()}

@item 
@ref{4e15,,PyArg_VaParse()}

@item 
@ref{61d,,PyArg_VaParseTupleAndKeywords()}

@item 
@ref{4e16,,PyArg_ValidateKeywordArguments()}

@item 
@ref{4e17,,PyBaseObject_Type}

@item 
@ref{4e18,,PyBool_FromLong()}

@item 
@ref{4e19,,PyBool_Type}

@item 
@ref{95b,,PyBuffer_FillContiguousStrides()}

@item 
@ref{95c,,PyBuffer_FillInfo()}

@item 
@ref{958,,PyBuffer_FromContiguous()}

@item 
@ref{955,,PyBuffer_GetPointer()}

@item 
@ref{95a,,PyBuffer_IsContiguous()}

@item 
@ref{633,,PyBuffer_Release()}

@item 
@ref{956,,PyBuffer_SizeFromFormat()}

@item 
@ref{957,,PyBuffer_ToContiguous()}

@item 
@code{PyByteArrayIter_Type}

@item 
@ref{4e1a,,PyByteArray_AsString()}

@item 
@ref{4e1b,,PyByteArray_Concat()}

@item 
@ref{15a0,,PyByteArray_FromObject()}

@item 
@ref{15a1,,PyByteArray_FromStringAndSize()}

@item 
@ref{4e1c,,PyByteArray_Resize()}

@item 
@ref{4e1d,,PyByteArray_Size()}

@item 
@ref{4e1e,,PyByteArray_Type}

@item 
@code{PyBytesIter_Type}

@item 
@ref{a7e,,PyBytes_AsString()}

@item 
@ref{4e1f,,PyBytes_AsStringAndSize()}

@item 
@ref{4e20,,PyBytes_Concat()}

@item 
@ref{4e21,,PyBytes_ConcatAndDel()}

@item 
@code{PyBytes_DecodeEscape()}

@item 
@ref{1cd3,,PyBytes_FromFormat()}

@item 
@ref{4e22,,PyBytes_FromFormatV()}

@item 
@ref{4e23,,PyBytes_FromObject()}

@item 
@ref{4e24,,PyBytes_FromString()}

@item 
@ref{1598,,PyBytes_FromStringAndSize()}

@item 
@code{PyBytes_Repr()}

@item 
@ref{4e25,,PyBytes_Size()}

@item 
@ref{4e26,,PyBytes_Type}

@item 
@ref{166c,,PyCFunction}

@item 
@ref{4e27,,PyCFunctionFast}

@item 
@ref{4e28,,PyCFunctionFastWithKeywords}

@item 
@ref{4e29,,PyCFunctionWithKeywords}

@item 
@code{PyCFunction_GetFlags()}

@item 
@code{PyCFunction_GetFunction()}

@item 
@code{PyCFunction_GetSelf()}

@item 
@ref{1ba9,,PyCFunction_New()}

@item 
@ref{1c3f,,PyCFunction_NewEx()}

@item 
@code{PyCFunction_Type}

@item 
@ref{1ba3,,PyCMethod_New()}

@item 
@ref{4e2a,,PyCallIter_New()}

@item 
@ref{4e2b,,PyCallIter_Type}

@item 
@ref{4e2c,,PyCallable_Check()}

@item 
@ref{4e2d,,PyCapsule_Destructor}

@item 
@ref{4e2e,,PyCapsule_GetContext()}

@item 
@ref{4e2f,,PyCapsule_GetDestructor()}

@item 
@ref{4e30,,PyCapsule_GetName()}

@item 
@ref{4e31,,PyCapsule_GetPointer()}

@item 
@ref{1b24,,PyCapsule_Import()}

@item 
@ref{1554,,PyCapsule_IsValid()}

@item 
@ref{4d8b,,PyCapsule_New()}

@item 
@ref{4e32,,PyCapsule_SetContext()}

@item 
@ref{4e33,,PyCapsule_SetDestructor()}

@item 
@ref{4e34,,PyCapsule_SetName()}

@item 
@ref{4e35,,PyCapsule_SetPointer()}

@item 
@code{PyCapsule_Type}

@item 
@code{PyClassMethodDescr_Type}

@item 
@ref{4e36,,PyCodec_BackslashReplaceErrors()}

@item 
@ref{3df,,PyCodec_Decode()}

@item 
@ref{4e37,,PyCodec_Decoder()}

@item 
@ref{3e0,,PyCodec_Encode()}

@item 
@ref{4e38,,PyCodec_Encoder()}

@item 
@ref{4e39,,PyCodec_IgnoreErrors()}

@item 
@ref{4e3a,,PyCodec_IncrementalDecoder()}

@item 
@ref{4e3b,,PyCodec_IncrementalEncoder()}

@item 
@ref{4e3c,,PyCodec_KnownEncoding()}

@item 
@ref{4e3d,,PyCodec_LookupError()}

@item 
@ref{10aa,,PyCodec_NameReplaceErrors()}

@item 
@ref{4e3e,,PyCodec_Register()}

@item 
@ref{4e3f,,PyCodec_RegisterError()}

@item 
@ref{4e40,,PyCodec_ReplaceErrors()}

@item 
@ref{4e41,,PyCodec_StreamReader()}

@item 
@ref{4e42,,PyCodec_StreamWriter()}

@item 
@ref{4e43,,PyCodec_StrictErrors()}

@item 
@ref{a8e,,PyCodec_Unregister()}

@item 
@ref{4e44,,PyCodec_XMLCharRefReplaceErrors()}

@item 
@ref{4e45,,PyComplex_FromDoubles()}

@item 
@ref{1962,,PyComplex_ImagAsDouble()}

@item 
@ref{1961,,PyComplex_RealAsDouble()}

@item 
@ref{4e46,,PyComplex_Type}

@item 
@ref{4e47,,PyDescr_NewClassMethod()}

@item 
@ref{4e48,,PyDescr_NewGetSet()}

@item 
@ref{4e49,,PyDescr_NewMember()}

@item 
@ref{1c3e,,PyDescr_NewMethod()}

@item 
@code{PyDictItems_Type}

@item 
@code{PyDictIterItem_Type}

@item 
@code{PyDictIterKey_Type}

@item 
@code{PyDictIterValue_Type}

@item 
@code{PyDictKeys_Type}

@item 
@ref{4e4a,,PyDictProxy_New()}

@item 
@code{PyDictProxy_Type}

@item 
@code{PyDictRevIterItem_Type}

@item 
@code{PyDictRevIterKey_Type}

@item 
@code{PyDictRevIterValue_Type}

@item 
@code{PyDictValues_Type}

@item 
@ref{4e4b,,PyDict_Clear()}

@item 
@ref{5d6,,PyDict_Contains()}

@item 
@ref{65a,,PyDict_Copy()}

@item 
@ref{4e4c,,PyDict_DelItem()}

@item 
@ref{4e4d,,PyDict_DelItemString()}

@item 
@ref{620,,PyDict_GetItem()}

@item 
@ref{5d8,,PyDict_GetItemRef()}

@item 
@ref{621,,PyDict_GetItemString()}

@item 
@ref{41f,,PyDict_GetItemStringRef()}

@item 
@ref{5d9,,PyDict_GetItemWithError()}

@item 
@ref{4e4e,,PyDict_Items()}

@item 
@ref{4e4f,,PyDict_Keys()}

@item 
@ref{4e50,,PyDict_Merge()}

@item 
@ref{4e51,,PyDict_MergeFromSeq2()}

@item 
@ref{4e52,,PyDict_New()}

@item 
@ref{18e9,,PyDict_Next()}

@item 
@ref{4d81,,PyDict_SetItem()}

@item 
@ref{18e7,,PyDict_SetItemString()}

@item 
@ref{4e53,,PyDict_Size()}

@item 
@ref{4e54,,PyDict_Type}

@item 
@ref{4e55,,PyDict_Update()}

@item 
@ref{4e56,,PyDict_Values()}

@item 
@ref{4e57,,PyEllipsis_Type}

@item 
@code{PyEnum_Type}

@item 
@ref{4e58,,PyErr_BadArgument()}

@item 
@ref{4e59,,PyErr_BadInternalCall()}

@item 
@ref{68c,,PyErr_CheckSignals()}

@item 
@ref{122c,,PyErr_Clear()}

@item 
@code{PyErr_Display()}

@item 
@ref{433,,PyErr_DisplayException()}

@item 
@ref{4dff,,PyErr_ExceptionMatches()}

@item 
@ref{426,,PyErr_Fetch()}

@item 
@ref{10ac,,PyErr_Format()}

@item 
@ref{10ab,,PyErr_FormatV()}

@item 
@ref{96e,,PyErr_GetExcInfo()}

@item 
@ref{96b,,PyErr_GetHandledException()}

@item 
@ref{427,,PyErr_GetRaisedException()}

@item 
@ref{4e5a,,PyErr_GivenExceptionMatches()}

@item 
@ref{146a,,PyErr_NewException()}

@item 
@ref{1469,,PyErr_NewExceptionWithDoc()}

@item 
@ref{4d61,,PyErr_NoMemory()}

@item 
@ref{428,,PyErr_NormalizeException()}

@item 
@ref{1ba7,,PyErr_Occurred()}

@item 
@ref{1bfa,,PyErr_Print()}

@item 
@ref{4e5b,,PyErr_PrintEx()}

@item 
@code{PyErr_ProgramText()}

@item 
@ref{f0e,,PyErr_ResourceWarning()}

@item 
@ref{429,,PyErr_Restore()}

@item 
@ref{4e5c,,PyErr_SetExcFromWindowsErr()}

@item 
@ref{19d8,,PyErr_SetExcFromWindowsErrWithFilename()}

@item 
@ref{4e5d,,PyErr_SetExcFromWindowsErrWithFilenameObject()}

@item 
@ref{4e5e,,PyErr_SetExcFromWindowsErrWithFilenameObjects()}

@item 
@ref{96d,,PyErr_SetExcInfo()}

@item 
@ref{4d60,,PyErr_SetFromErrno()}

@item 
@ref{19d7,,PyErr_SetFromErrnoWithFilename()}

@item 
@ref{4e5f,,PyErr_SetFromErrnoWithFilenameObject()}

@item 
@ref{4e60,,PyErr_SetFromErrnoWithFilenameObjects()}

@item 
@ref{4e61,,PyErr_SetFromWindowsErr()}

@item 
@ref{19d9,,PyErr_SetFromWindowsErrWithFilename()}

@item 
@ref{96c,,PyErr_SetHandledException()}

@item 
@ref{f34,,PyErr_SetImportError()}

@item 
@ref{f0d,,PyErr_SetImportErrorSubclass()}

@item 
@ref{4e62,,PyErr_SetInterrupt()}

@item 
@ref{a95,,PyErr_SetInterruptEx()}

@item 
@ref{4e63,,PyErr_SetNone()}

@item 
@ref{794,,PyErr_SetObject()}

@item 
@ref{42a,,PyErr_SetRaisedException()}

@item 
@ref{795,,PyErr_SetString()}

@item 
@ref{4e64,,PyErr_SyntaxLocation()}

@item 
@ref{4e65,,PyErr_SyntaxLocationEx()}

@item 
@ref{1641,,PyErr_WarnEx()}

@item 
@ref{19df,,PyErr_WarnExplicit()}

@item 
@ref{4e66,,PyErr_WarnFormat()}

@item 
@ref{5ea,,PyErr_WriteUnraisable()}

@item 
@ref{641,,PyEval_AcquireThread()}

@item 
@ref{a7d,,PyEval_EvalCode()}

@item 
@ref{1a25,,PyEval_EvalCodeEx()}

@item 
@ref{4e67,,PyEval_EvalFrame()}

@item 
@ref{1229,,PyEval_EvalFrameEx()}

@item 
@ref{5ec,,PyEval_GetBuiltins()}

@item 
@ref{1a78,,PyEval_GetFrame()}

@item 
@ref{5eb,,PyEval_GetFrameBuiltins()}

@item 
@ref{5ed,,PyEval_GetFrameGlobals()}

@item 
@ref{5ef,,PyEval_GetFrameLocals()}

@item 
@ref{4e68,,PyEval_GetFuncDesc()}

@item 
@ref{4e69,,PyEval_GetFuncName()}

@item 
@ref{5ee,,PyEval_GetGlobals()}

@item 
@ref{5f0,,PyEval_GetLocals()}

@item 
@ref{190e,,PyEval_InitThreads()}

@item 
@ref{4e6a,,PyEval_ReleaseThread()}

@item 
@ref{640,,PyEval_RestoreThread()}

@item 
@ref{63f,,PyEval_SaveThread()}

@item 
@ref{4e6b,,PyExc_ArithmeticError}

@item 
@ref{4e6c,,PyExc_AssertionError}

@item 
@ref{4e6d,,PyExc_AttributeError}

@item 
@ref{4e6e,,PyExc_BaseException}

@item 
@ref{4e6f,,PyExc_BaseExceptionGroup}

@item 
@ref{4e70,,PyExc_BlockingIOError}

@item 
@ref{4e71,,PyExc_BrokenPipeError}

@item 
@ref{4e72,,PyExc_BufferError}

@item 
@ref{4e73,,PyExc_BytesWarning}

@item 
@ref{4e74,,PyExc_ChildProcessError}

@item 
@ref{4e75,,PyExc_ConnectionAbortedError}

@item 
@ref{4e76,,PyExc_ConnectionError}

@item 
@ref{4e77,,PyExc_ConnectionRefusedError}

@item 
@ref{4e78,,PyExc_ConnectionResetError}

@item 
@ref{4e79,,PyExc_DeprecationWarning}

@item 
@ref{4e7a,,PyExc_EOFError}

@item 
@ref{4e7b,,PyExc_EncodingWarning}

@item 
@ref{4e7c,,PyExc_EnvironmentError}

@item 
@ref{4e7d,,PyExc_Exception}

@item 
@ref{4e7e,,PyExc_FileExistsError}

@item 
@ref{4e7f,,PyExc_FileNotFoundError}

@item 
@ref{4e80,,PyExc_FloatingPointError}

@item 
@ref{4e81,,PyExc_FutureWarning}

@item 
@ref{4e82,,PyExc_GeneratorExit}

@item 
@ref{4e83,,PyExc_IOError}

@item 
@ref{4e84,,PyExc_ImportError}

@item 
@ref{4e85,,PyExc_ImportWarning}

@item 
@ref{4e86,,PyExc_IndentationError}

@item 
@ref{4e87,,PyExc_IndexError}

@item 
@ref{4e88,,PyExc_InterruptedError}

@item 
@ref{4e89,,PyExc_IsADirectoryError}

@item 
@ref{4e8a,,PyExc_KeyError}

@item 
@ref{4e8b,,PyExc_KeyboardInterrupt}

@item 
@ref{4e8c,,PyExc_LookupError}

@item 
@ref{4e8d,,PyExc_MemoryError}

@item 
@ref{4e8e,,PyExc_ModuleNotFoundError}

@item 
@ref{4e8f,,PyExc_NameError}

@item 
@ref{4e90,,PyExc_NotADirectoryError}

@item 
@ref{4e91,,PyExc_NotImplementedError}

@item 
@ref{4d63,,PyExc_OSError}

@item 
@ref{4e92,,PyExc_OverflowError}

@item 
@ref{4e93,,PyExc_PendingDeprecationWarning}

@item 
@ref{4e94,,PyExc_PermissionError}

@item 
@ref{4e95,,PyExc_ProcessLookupError}

@item 
@ref{10ad,,PyExc_RecursionError}

@item 
@ref{4e96,,PyExc_ReferenceError}

@item 
@ref{4e97,,PyExc_ResourceWarning}

@item 
@ref{4e98,,PyExc_RuntimeError}

@item 
@ref{4e99,,PyExc_RuntimeWarning}

@item 
@ref{4e9a,,PyExc_StopAsyncIteration}

@item 
@ref{4e9b,,PyExc_StopIteration}

@item 
@ref{4e9c,,PyExc_SyntaxError}

@item 
@ref{4e9d,,PyExc_SyntaxWarning}

@item 
@ref{4e9e,,PyExc_SystemError}

@item 
@ref{4e9f,,PyExc_SystemExit}

@item 
@ref{4ea0,,PyExc_TabError}

@item 
@ref{4ea1,,PyExc_TimeoutError}

@item 
@ref{4d62,,PyExc_TypeError}

@item 
@ref{4ea2,,PyExc_UnboundLocalError}

@item 
@ref{4ea3,,PyExc_UnicodeDecodeError}

@item 
@ref{4ea4,,PyExc_UnicodeEncodeError}

@item 
@ref{4ea5,,PyExc_UnicodeError}

@item 
@ref{4ea6,,PyExc_UnicodeTranslateError}

@item 
@ref{4ea7,,PyExc_UnicodeWarning}

@item 
@ref{4ea8,,PyExc_UserWarning}

@item 
@ref{4d64,,PyExc_ValueError}

@item 
@ref{4ea9,,PyExc_Warning}

@item 
@ref{4eaa,,PyExc_WindowsError}

@item 
@ref{4d5f,,PyExc_ZeroDivisionError}

@item 
@ref{c52,,PyExceptionClass_Name()}

@item 
@ref{784,,PyException_GetArgs()}

@item 
@ref{4eab,,PyException_GetCause()}

@item 
@ref{4eac,,PyException_GetContext()}

@item 
@ref{4ead,,PyException_GetTraceback()}

@item 
@ref{785,,PyException_SetArgs()}

@item 
@ref{4eae,,PyException_SetCause()}

@item 
@ref{4eaf,,PyException_SetContext()}

@item 
@ref{1c97,,PyException_SetTraceback()}

@item 
@ref{4eb0,,PyFile_FromFd()}

@item 
@ref{4eb1,,PyFile_GetLine()}

@item 
@ref{4eb2,,PyFile_WriteObject()}

@item 
@ref{4eb3,,PyFile_WriteString()}

@item 
@code{PyFilter_Type}

@item 
@ref{c56,,PyFloat_AsDouble()}

@item 
@ref{4eb4,,PyFloat_FromDouble()}

@item 
@ref{4eb5,,PyFloat_FromString()}

@item 
@ref{15e7,,PyFloat_GetInfo()}

@item 
@ref{15e5,,PyFloat_GetMax()}

@item 
@ref{15e6,,PyFloat_GetMin()}

@item 
@ref{4eb6,,PyFloat_Type}

@item 
@ref{984,,PyFrameObject}

@item 
@ref{985,,PyFrame_GetCode()}

@item 
@ref{986,,PyFrame_GetLineNumber()}

@item 
@ref{163c,,PyFrozenSet_New()}

@item 
@ref{4eb7,,PyFrozenSet_Type}

@item 
@ref{b7c,,PyGC_Collect()}

@item 
@ref{a9c,,PyGC_Disable()}

@item 
@ref{a9b,,PyGC_Enable()}

@item 
@ref{a9d,,PyGC_IsEnabled()}

@item 
@ref{642,,PyGILState_Ensure()}

@item 
@ref{4eb8,,PyGILState_GetThisThreadState()}

@item 
@ref{643,,PyGILState_Release()}

@item 
@ref{4eb9,,PyGILState_STATE}

@item 
@ref{dad,,PyGetSetDef}

@item 
@code{PyGetSetDescr_Type}

@item 
@ref{5f4,,PyImport_AddModule()}

@item 
@ref{4eba,,PyImport_AddModuleObject()}

@item 
@ref{5f3,,PyImport_AddModuleRef()}

@item 
@ref{1a5f,,PyImport_AppendInittab()}

@item 
@ref{4ebb,,PyImport_ExecCodeModule()}

@item 
@ref{4ebc,,PyImport_ExecCodeModuleEx()}

@item 
@ref{4ebd,,PyImport_ExecCodeModuleObject()}

@item 
@ref{4ebe,,PyImport_ExecCodeModuleWithPathnames()}

@item 
@ref{19d6,,PyImport_GetImporter()}

@item 
@ref{13a4,,PyImport_GetMagicNumber()}

@item 
@ref{4ebf,,PyImport_GetMagicTag()}

@item 
@ref{da7,,PyImport_GetModule()}

@item 
@ref{4ec0,,PyImport_GetModuleDict()}

@item 
@ref{15f3,,PyImport_Import()}

@item 
@ref{4ec1,,PyImport_ImportFrozenModule()}

@item 
@ref{4ec2,,PyImport_ImportFrozenModuleObject()}

@item 
@ref{3da,,PyImport_ImportModule()}

@item 
@ref{13a5,,PyImport_ImportModuleLevel()}

@item 
@ref{4ec3,,PyImport_ImportModuleLevelObject()}

@item 
@ref{3d9,,PyImport_ImportModuleNoBlock()}

@item 
@ref{4ec4,,PyImport_ReloadModule()}

@item 
@ref{b78,,PyIndex_Check()}

@item 
@ref{ab1,,PyInterpreterState}

@item 
@ref{460c,,PyInterpreterState_Clear()}

@item 
@ref{4ec5,,PyInterpreterState_Delete()}

@item 
@ref{644,,PyInterpreterState_Get()}

@item 
@ref{4ec6,,PyInterpreterState_GetDict()}

@item 
@ref{dba,,PyInterpreterState_GetID()}

@item 
@ref{460d,,PyInterpreterState_New()}

@item 
@ref{1baa,,PyIter_Check()}

@item 
@ref{397,,PyIter_Next()}

@item 
@ref{396,,PyIter_NextItem()}

@item 
@ref{a8f,,PyIter_Send()}

@item 
@code{PyListIter_Type}

@item 
@code{PyListRevIter_Type}

@item 
@ref{4ec7,,PyList_Append()}

@item 
@ref{4ec8,,PyList_AsTuple()}

@item 
@ref{5f7,,PyList_GetItem()}

@item 
@ref{5f6,,PyList_GetItemRef()}

@item 
@ref{4ec9,,PyList_GetSlice()}

@item 
@ref{182f,,PyList_Insert()}

@item 
@ref{4dfa,,PyList_New()}

@item 
@ref{4eca,,PyList_Reverse()}

@item 
@ref{1830,,PyList_SetItem()}

@item 
@ref{4ecb,,PyList_SetSlice()}

@item 
@ref{1611,,PyList_Size()}

@item 
@ref{4ecc,,PyList_Sort()}

@item 
@ref{4da3,,PyList_Type}

@item 
@ref{39c,,PyLongObject}

@item 
@code{PyLongRangeIter_Type}

@item 
@ref{18d8,,PyLong_AsDouble()}

@item 
@ref{5fc,,PyLong_AsInt()}

@item 
@ref{39d,,PyLong_AsInt32()}

@item 
@ref{39e,,PyLong_AsInt64()}

@item 
@ref{5fd,,PyLong_AsLong()}

@item 
@ref{1467,,PyLong_AsLongAndOverflow()}

@item 
@ref{4ecd,,PyLong_AsLongLong()}

@item 
@ref{1466,,PyLong_AsLongLongAndOverflow()}

@item 
@ref{5fe,,PyLong_AsNativeBytes()}

@item 
@ref{4ece,,PyLong_AsSize_t()}

@item 
@ref{4ecf,,PyLong_AsSsize_t()}

@item 
@ref{39f,,PyLong_AsUInt32()}

@item 
@ref{3a0,,PyLong_AsUInt64()}

@item 
@ref{4ed0,,PyLong_AsUnsignedLong()}

@item 
@ref{1495,,PyLong_AsUnsignedLongLong()}

@item 
@ref{1c93,,PyLong_AsUnsignedLongLongMask()}

@item 
@ref{4ed1,,PyLong_AsUnsignedLongMask()}

@item 
@ref{4ed2,,PyLong_AsVoidPtr()}

@item 
@ref{b33,,PyLong_FromDouble()}

@item 
@ref{3a1,,PyLong_FromInt32()}

@item 
@ref{3a2,,PyLong_FromInt64()}

@item 
@ref{1af0,,PyLong_FromLong()}

@item 
@ref{1af1,,PyLong_FromLongLong()}

@item 
@ref{5ff,,PyLong_FromNativeBytes()}

@item 
@ref{1833,,PyLong_FromSize_t()}

@item 
@ref{1815,,PyLong_FromSsize_t()}

@item 
@ref{4ed3,,PyLong_FromString()}

@item 
@ref{3a3,,PyLong_FromUInt32()}

@item 
@ref{3a4,,PyLong_FromUInt64()}

@item 
@ref{1831,,PyLong_FromUnsignedLong()}

@item 
@ref{1832,,PyLong_FromUnsignedLongLong()}

@item 
@ref{600,,PyLong_FromUnsignedNativeBytes()}

@item 
@ref{4ed4,,PyLong_FromVoidPtr()}

@item 
@ref{4ed5,,PyLong_GetInfo()}

@item 
@ref{4ed6,,PyLong_Type}

@item 
@code{PyMap_Type}

@item 
@ref{4ed7,,PyMapping_Check()}

@item 
@ref{5e3,,PyMapping_GetItemString()}

@item 
@ref{5e0,,PyMapping_GetOptionalItem()}

@item 
@ref{5e1,,PyMapping_GetOptionalItemString()}

@item 
@ref{618,,PyMapping_HasKey()}

@item 
@ref{61a,,PyMapping_HasKeyString()}

@item 
@ref{619,,PyMapping_HasKeyStringWithError()}

@item 
@ref{617,,PyMapping_HasKeyWithError()}

@item 
@ref{db2,,PyMapping_Items()}

@item 
@ref{db0,,PyMapping_Keys()}

@item 
@ref{4ed8,,PyMapping_Length()}

@item 
@ref{4ed9,,PyMapping_SetItemString()}

@item 
@ref{1cfe,,PyMapping_Size()}

@item 
@ref{db1,,PyMapping_Values()}

@item 
@ref{10a8,,PyMem_Calloc()}

@item 
@ref{1639,,PyMem_Free()}

@item 
@ref{e5b,,PyMem_Malloc()}

@item 
@ref{62a,,PyMem_RawCalloc()}

@item 
@ref{62c,,PyMem_RawFree()}

@item 
@ref{629,,PyMem_RawMalloc()}

@item 
@ref{62b,,PyMem_RawRealloc()}

@item 
@ref{122d,,PyMem_Realloc()}

@item 
@ref{76a,,PyMemberDef}

@item 
@code{PyMemberDescr_Type}

@item 
@ref{7a3,,PyMember_GetOne()}

@item 
@ref{7a4,,PyMember_SetOne()}

@item 
@ref{95d,,PyMemoryView_FromBuffer()}

@item 
@ref{1371,,PyMemoryView_FromMemory()}

@item 
@ref{4eda,,PyMemoryView_FromObject()}

@item 
@ref{4edb,,PyMemoryView_GetContiguous()}

@item 
@code{PyMemoryView_Type}

@item 
@ref{16cb,,PyMethodDef}

@item 
@code{PyMethodDescr_Type}

@item 
@ref{b6b,,PyModuleDef}

@item 
@code{PyModuleDef_Base}

@item 
@ref{4d6b,,PyModuleDef_Init()}

@item 
@code{PyModuleDef_Type}

@item 
@ref{601,,PyModule_Add()}

@item 
@ref{4edc,,PyModule_AddFunctions()}

@item 
@ref{1730,,PyModule_AddIntConstant()}

@item 
@ref{603,,PyModule_AddObject()}

@item 
@ref{602,,PyModule_AddObjectRef()}

@item 
@ref{1731,,PyModule_AddStringConstant()}

@item 
@ref{b63,,PyModule_AddType()}

@item 
@ref{4edd,,PyModule_Create2()}

@item 
@ref{10b0,,PyModule_ExecDef()}

@item 
@ref{10af,,PyModule_FromDefAndSpec2()}

@item 
@ref{4ede,,PyModule_GetDef()}

@item 
@ref{4edf,,PyModule_GetDict()}

@item 
@ref{42b,,PyModule_GetFilename()}

@item 
@ref{42c,,PyModule_GetFilenameObject()}

@item 
@ref{4ee0,,PyModule_GetName()}

@item 
@ref{4ee1,,PyModule_GetNameObject()}

@item 
@ref{b6e,,PyModule_GetState()}

@item 
@ref{4ee2,,PyModule_New()}

@item 
@ref{4ee3,,PyModule_NewObject()}

@item 
@ref{4ee4,,PyModule_SetDocString()}

@item 
@ref{4ee5,,PyModule_Type}

@item 
@ref{4ee6,,PyNumber_Absolute()}

@item 
@ref{4ee7,,PyNumber_Add()}

@item 
@ref{4ee8,,PyNumber_And()}

@item 
@ref{4ee9,,PyNumber_AsSsize_t()}

@item 
@ref{c53,,PyNumber_Check()}

@item 
@ref{4eea,,PyNumber_Divmod()}

@item 
@ref{c55,,PyNumber_Float()}

@item 
@ref{4eeb,,PyNumber_FloorDivide()}

@item 
@ref{4eec,,PyNumber_InPlaceAdd()}

@item 
@ref{4eed,,PyNumber_InPlaceAnd()}

@item 
@ref{4eee,,PyNumber_InPlaceFloorDivide()}

@item 
@ref{4eef,,PyNumber_InPlaceLshift()}

@item 
@ref{10b2,,PyNumber_InPlaceMatrixMultiply()}

@item 
@ref{4ef0,,PyNumber_InPlaceMultiply()}

@item 
@ref{4ef1,,PyNumber_InPlaceOr()}

@item 
@ref{4ef2,,PyNumber_InPlacePower()}

@item 
@ref{4ef3,,PyNumber_InPlaceRemainder()}

@item 
@ref{4ef4,,PyNumber_InPlaceRshift()}

@item 
@ref{4ef5,,PyNumber_InPlaceSubtract()}

@item 
@ref{4ef6,,PyNumber_InPlaceTrueDivide()}

@item 
@ref{4ef7,,PyNumber_InPlaceXor()}

@item 
@ref{a8a,,PyNumber_Index()}

@item 
@ref{4ef8,,PyNumber_Invert()}

@item 
@ref{c54,,PyNumber_Long()}

@item 
@ref{4ef9,,PyNumber_Lshift()}

@item 
@ref{10b1,,PyNumber_MatrixMultiply()}

@item 
@ref{4efa,,PyNumber_Multiply()}

@item 
@ref{4efb,,PyNumber_Negative()}

@item 
@ref{4efc,,PyNumber_Or()}

@item 
@ref{4efd,,PyNumber_Positive()}

@item 
@ref{4efe,,PyNumber_Power()}

@item 
@ref{4eff,,PyNumber_Remainder()}

@item 
@ref{4f00,,PyNumber_Rshift()}

@item 
@ref{4f01,,PyNumber_Subtract()}

@item 
@ref{1aa2,,PyNumber_ToBase()}

@item 
@ref{4f02,,PyNumber_TrueDivide()}

@item 
@ref{4f03,,PyNumber_Xor()}

@item 
@ref{42d,,PyOS_AfterFork()}

@item 
@ref{42e,,PyOS_AfterFork_Child()}

@item 
@ref{db4,,PyOS_AfterFork_Parent()}

@item 
@ref{db3,,PyOS_BeforeFork()}

@item 
@ref{1acb,,PyOS_CheckStack()}

@item 
@ref{f0f,,PyOS_FSPath()}

@item 
@ref{79d,,PyOS_InputHook}

@item 
@code{PyOS_InterruptOccurred()}

@item 
@ref{4f04,,PyOS_double_to_string()}

@item 
@ref{1732,,PyOS_getsig()}

@item 
@code{PyOS_mystricmp()}

@item 
@code{PyOS_mystrnicmp()}

@item 
@ref{1733,,PyOS_setsig()}

@item 
@ref{4f05,,PyOS_sighandler_t}

@item 
@ref{16fd,,PyOS_snprintf()}

@item 
@ref{1496,,PyOS_string_to_double()}

@item 
@ref{4f06,,PyOS_strtol()}

@item 
@ref{4f07,,PyOS_strtoul()}

@item 
@ref{16fe,,PyOS_vsnprintf()}

@item 
@ref{5d7,,PyObject}

@item 
@ref{a96,,PyObject.ob_refcnt}

@item 
@ref{4d95,,PyObject.ob_type}

@item 
@ref{4f08,,PyObject_ASCII()}

@item 
@ref{4f09,,PyObject_AsFileDescriptor()}

@item 
@ref{4f0a,,PyObject_Bytes()}

@item 
@ref{635,,PyObject_Call()}

@item 
@ref{637,,PyObject_CallFunction()}

@item 
@ref{4f0b,,PyObject_CallFunctionObjArgs()}

@item 
@ref{638,,PyObject_CallMethod()}

@item 
@ref{1ca8,,PyObject_CallMethodObjArgs()}

@item 
@ref{634,,PyObject_CallNoArgs()}

@item 
@ref{4d74,,PyObject_CallObject()}

@item 
@ref{10a9,,PyObject_Calloc()}

@item 
@ref{631,,PyObject_CheckBuffer()}

@item 
@ref{78f,,PyObject_ClearWeakRefs()}

@item 
@ref{959,,PyObject_CopyData()}

@item 
@ref{17ae,,PyObject_DelAttr()}

@item 
@ref{17af,,PyObject_DelAttrString()}

@item 
@ref{4f0c,,PyObject_DelItem()}

@item 
@ref{4f0d,,PyObject_DelItemString()}

@item 
@ref{4f0e,,PyObject_Dir()}

@item 
@ref{4f0f,,PyObject_Format()}

@item 
@ref{e5a,,PyObject_Free()}

@item 
@ref{16f7,,PyObject_GC_Del()}

@item 
@ref{b65,,PyObject_GC_IsFinalized()}

@item 
@ref{b64,,PyObject_GC_IsTracked()}

@item 
@ref{16f8,,PyObject_GC_Track()}

@item 
@ref{16f9,,PyObject_GC_UnTrack()}

@item 
@ref{4f10,,PyObject_GenericGetAttr()}

@item 
@ref{1bef,,PyObject_GenericGetDict()}

@item 
@ref{4f11,,PyObject_GenericSetAttr()}

@item 
@ref{4f12,,PyObject_GenericSetDict()}

@item 
@ref{4f13,,PyObject_GetAIter()}

@item 
@ref{5e6,,PyObject_GetAttr()}

@item 
@ref{5e7,,PyObject_GetAttrString()}

@item 
@ref{632,,PyObject_GetBuffer()}

@item 
@ref{5e2,,PyObject_GetItem()}

@item 
@ref{4f14,,PyObject_GetIter()}

@item 
@ref{5e4,,PyObject_GetOptionalAttr()}

@item 
@ref{5e5,,PyObject_GetOptionalAttrString()}

@item 
@ref{764,,PyObject_GetTypeData()}

@item 
@ref{614,,PyObject_HasAttr()}

@item 
@ref{616,,PyObject_HasAttrString()}

@item 
@ref{615,,PyObject_HasAttrStringWithError()}

@item 
@ref{613,,PyObject_HasAttrWithError()}

@item 
@ref{434,,PyObject_Hash()}

@item 
@ref{15be,,PyObject_HashNotImplemented()}

@item 
@ref{c57,,PyObject_Init()}

@item 
@ref{1c0a,,PyObject_InitVar()}

@item 
@ref{10a1,,PyObject_IsInstance()}

@item 
@ref{10a2,,PyObject_IsSubclass()}

@item 
@ref{4f15,,PyObject_IsTrue()}

@item 
@ref{4f16,,PyObject_Length()}

@item 
@ref{e5d,,PyObject_Malloc()}

@item 
@ref{4f17,,PyObject_Not()}

@item 
@ref{163a,,PyObject_Realloc()}

@item 
@ref{122a,,PyObject_Repr()}

@item 
@ref{4db9,,PyObject_RichCompare()}

@item 
@ref{1c55,,PyObject_RichCompareBool()}

@item 
@ref{4f18,,PyObject_SelfIter()}

@item 
@ref{4f19,,PyObject_SetAttr()}

@item 
@ref{18e8,,PyObject_SetAttrString()}

@item 
@ref{4df9,,PyObject_SetItem()}

@item 
@ref{4f1a,,PyObject_Size()}

@item 
@ref{122b,,PyObject_Str()}

@item 
@ref{4f1b,,PyObject_Type()}

@item 
@ref{777,,PyObject_Vectorcall()}

@item 
@ref{778,,PyObject_VectorcallMethod()}

@item 
@ref{4f1c,,PyProperty_Type}

@item 
@code{PyRangeIter_Type}

@item 
@code{PyRange_Type}

@item 
@code{PyReversed_Type}

@item 
@ref{4f1d,,PySeqIter_New()}

@item 
@ref{4f1e,,PySeqIter_Type}

@item 
@ref{4f1f,,PySequence_Check()}

@item 
@ref{4f20,,PySequence_Concat()}

@item 
@ref{3d7,,PySequence_Contains()}

@item 
@ref{4f21,,PySequence_Count()}

@item 
@ref{1cfd,,PySequence_DelItem()}

@item 
@ref{4f22,,PySequence_DelSlice()}

@item 
@ref{1817,,PySequence_Fast()}

@item 
@ref{1cfb,,PySequence_GetItem()}

@item 
@ref{4f23,,PySequence_GetSlice()}

@item 
@ref{3d6,,PySequence_In()}

@item 
@ref{4f24,,PySequence_InPlaceConcat()}

@item 
@ref{4f25,,PySequence_InPlaceRepeat()}

@item 
@ref{4f26,,PySequence_Index()}

@item 
@ref{4f27,,PySequence_Length()}

@item 
@ref{4f28,,PySequence_List()}

@item 
@ref{4f29,,PySequence_Repeat()}

@item 
@ref{1cfc,,PySequence_SetItem()}

@item 
@ref{4f2a,,PySequence_SetSlice()}

@item 
@ref{1cfa,,PySequence_Size()}

@item 
@ref{4f2b,,PySequence_Tuple()}

@item 
@code{PySetIter_Type}

@item 
@ref{163d,,PySet_Add()}

@item 
@ref{4f2c,,PySet_Clear()}

@item 
@ref{163f,,PySet_Contains()}

@item 
@ref{163e,,PySet_Discard()}

@item 
@ref{163b,,PySet_New()}

@item 
@ref{4f2d,,PySet_Pop()}

@item 
@ref{1640,,PySet_Size()}

@item 
@ref{4f2e,,PySet_Type}

@item 
@ref{431,,PySlice_AdjustIndices()}

@item 
@ref{4f2f,,PySlice_GetIndices()}

@item 
@ref{42f,,PySlice_GetIndicesEx()}

@item 
@ref{4f30,,PySlice_New()}

@item 
@ref{4f31,,PySlice_Type}

@item 
@ref{430,,PySlice_Unpack()}

@item 
@ref{4f32,,PyState_AddModule()}

@item 
@ref{4f33,,PyState_FindModule()}

@item 
@ref{4f34,,PyState_RemoveModule()}

@item 
@ref{daf,,PyStructSequence_Desc}

@item 
@ref{dae,,PyStructSequence_Field}

@item 
@ref{4f35,,PyStructSequence_GetItem()}

@item 
@ref{4f36,,PyStructSequence_New()}

@item 
@ref{4f37,,PyStructSequence_NewType()}

@item 
@ref{4f38,,PyStructSequence_SetItem()}

@item 
@ref{b70,,PyStructSequence_UnnamedField}

@item 
@code{PySuper_Type}

@item 
@ref{60b,,PySys_Audit()}

@item 
@ref{60a,,PySys_AuditTuple()}

@item 
@ref{4f39,,PySys_FormatStderr()}

@item 
@ref{4f3a,,PySys_FormatStdout()}

@item 
@ref{622,,PySys_GetObject()}

@item 
@ref{4f3b,,PySys_GetXOptions()}

@item 
@ref{3f2,,PySys_ResetWarnOptions()}

@item 
@ref{190d,,PySys_SetArgv()}

@item 
@ref{190c,,PySys_SetArgvEx()}

@item 
@ref{4f3c,,PySys_SetObject()}

@item 
@ref{4f3d,,PySys_WriteStderr()}

@item 
@ref{4f3e,,PySys_WriteStdout()}

@item 
@ref{988,,PyThreadState}

@item 
@ref{18ea,,PyThreadState_Clear()}

@item 
@ref{1c52,,PyThreadState_Delete()}

@item 
@ref{60d,,PyThreadState_Get()}

@item 
@ref{4f3f,,PyThreadState_GetDict()}

@item 
@ref{989,,PyThreadState_GetFrame()}

@item 
@ref{b61,,PyThreadState_GetID()}

@item 
@ref{b60,,PyThreadState_GetInterpreter()}

@item 
@ref{4f40,,PyThreadState_New()}

@item 
@ref{db8,,PyThreadState_SetAsyncExc()}

@item 
@ref{4f41,,PyThreadState_Swap()}

@item 
@code{PyThread_GetInfo()}

@item 
@ref{43f,,PyThread_ReInitTLS()}

@item 
@code{PyThread_acquire_lock()}

@item 
@code{PyThread_acquire_lock_timed()}

@item 
@code{PyThread_allocate_lock()}

@item 
@ref{435,,PyThread_create_key()}

@item 
@ref{437,,PyThread_delete_key()}

@item 
@ref{43d,,PyThread_delete_key_value()}

@item 
@code{PyThread_exit_thread()}

@item 
@code{PyThread_free_lock()}

@item 
@ref{43b,,PyThread_get_key_value()}

@item 
@code{PyThread_get_stacksize()}

@item 
@code{PyThread_get_thread_ident()}

@item 
@code{PyThread_get_thread_native_id()}

@item 
@code{PyThread_init_thread()}

@item 
@code{PyThread_release_lock()}

@item 
@ref{439,,PyThread_set_key_value()}

@item 
@code{PyThread_set_stacksize()}

@item 
@code{PyThread_start_new_thread()}

@item 
@ref{436,,PyThread_tss_alloc()}

@item 
@ref{4f42,,PyThread_tss_create()}

@item 
@ref{43e,,PyThread_tss_delete()}

@item 
@ref{438,,PyThread_tss_free()}

@item 
@ref{43c,,PyThread_tss_get()}

@item 
@ref{4f43,,PyThread_tss_is_created()}

@item 
@ref{43a,,PyThread_tss_set()}

@item 
@code{PyTraceBack_Here()}

@item 
@code{PyTraceBack_Print()}

@item 
@code{PyTraceBack_Type}

@item 
@code{PyTupleIter_Type}

@item 
@ref{4d7f,,PyTuple_GetItem()}

@item 
@ref{4f44,,PyTuple_GetSlice()}

@item 
@ref{636,,PyTuple_New()}

@item 
@ref{4f45,,PyTuple_Pack()}

@item 
@ref{4d80,,PyTuple_SetItem()}

@item 
@ref{4f46,,PyTuple_Size()}

@item 
@ref{4f47,,PyTuple_Type}

@item 
@ref{c93,,PyTypeObject}

@item 
@ref{4f48,,PyType_ClearCache()}

@item 
@ref{3ad,,PyType_Freeze()}

@item 
@ref{76b,,PyType_FromMetaclass()}

@item 
@ref{76c,,PyType_FromModuleAndSpec()}

@item 
@ref{796,,PyType_FromSpec()}

@item 
@ref{797,,PyType_FromSpecWithBases()}

@item 
@ref{c58,,PyType_GenericAlloc()}

@item 
@ref{4d94,,PyType_GenericNew()}

@item 
@ref{3ae,,PyType_GetBaseByToken()}

@item 
@ref{1c09,,PyType_GetFlags()}

@item 
@ref{60e,,PyType_GetFullyQualifiedName()}

@item 
@ref{b5d,,PyType_GetModule()}

@item 
@ref{62d,,PyType_GetModuleByDef()}

@item 
@ref{610,,PyType_GetModuleName()}

@item 
@ref{b5e,,PyType_GetModuleState()}

@item 
@ref{950,,PyType_GetName()}

@item 
@ref{951,,PyType_GetQualName()}

@item 
@ref{a93,,PyType_GetSlot()}

@item 
@ref{765,,PyType_GetTypeDataSize()}

@item 
@ref{4f49,,PyType_IsSubtype()}

@item 
@ref{1aaa,,PyType_Modified()}

@item 
@ref{97a,,PyType_Ready()}

@item 
@ref{4f4a,,PyType_Slot}

@item 
@ref{19db,,PyType_Spec}

@item 
@ref{768,,PyType_Type}

@item 
@ref{4f4b,,PyUnicodeDecodeError_Create()}

@item 
@ref{4f4c,,PyUnicodeDecodeError_GetEncoding()}

@item 
@ref{4f4d,,PyUnicodeDecodeError_GetEnd()}

@item 
@ref{4f4e,,PyUnicodeDecodeError_GetObject()}

@item 
@ref{4f4f,,PyUnicodeDecodeError_GetReason()}

@item 
@ref{4f50,,PyUnicodeDecodeError_GetStart()}

@item 
@ref{4f51,,PyUnicodeDecodeError_SetEnd()}

@item 
@ref{4f52,,PyUnicodeDecodeError_SetReason()}

@item 
@ref{4f53,,PyUnicodeDecodeError_SetStart()}

@item 
@ref{4f54,,PyUnicodeEncodeError_GetEncoding()}

@item 
@ref{1866,,PyUnicodeEncodeError_GetEnd()}

@item 
@ref{4f55,,PyUnicodeEncodeError_GetObject()}

@item 
@ref{4f56,,PyUnicodeEncodeError_GetReason()}

@item 
@ref{1869,,PyUnicodeEncodeError_GetStart()}

@item 
@ref{4f57,,PyUnicodeEncodeError_SetEnd()}

@item 
@ref{4f58,,PyUnicodeEncodeError_SetReason()}

@item 
@ref{4f59,,PyUnicodeEncodeError_SetStart()}

@item 
@ref{4f5a,,PyUnicodeIter_Type}

@item 
@ref{4f5b,,PyUnicodeTranslateError_GetEnd()}

@item 
@ref{4f5c,,PyUnicodeTranslateError_GetObject()}

@item 
@ref{4f5d,,PyUnicodeTranslateError_GetReason()}

@item 
@ref{4f5e,,PyUnicodeTranslateError_GetStart()}

@item 
@ref{4f5f,,PyUnicodeTranslateError_SetEnd()}

@item 
@ref{4f60,,PyUnicodeTranslateError_SetReason()}

@item 
@ref{4f61,,PyUnicodeTranslateError_SetStart()}

@item 
@ref{4f62,,PyUnicode_Append()}

@item 
@ref{4f63,,PyUnicode_AppendAndDel()}

@item 
@ref{1393,,PyUnicode_AsASCIIString()}

@item 
@ref{4f64,,PyUnicode_AsCharmapString()}

@item 
@code{PyUnicode_AsDecodedObject()}

@item 
@code{PyUnicode_AsDecodedUnicode()}

@item 
@code{PyUnicode_AsEncodedObject()}

@item 
@ref{4f65,,PyUnicode_AsEncodedString()}

@item 
@code{PyUnicode_AsEncodedUnicode()}

@item 
@ref{1392,,PyUnicode_AsLatin1String()}

@item 
@ref{1394,,PyUnicode_AsMBCSString()}

@item 
@ref{1391,,PyUnicode_AsRawUnicodeEscapeString()}

@item 
@ref{1379,,PyUnicode_AsUCS4()}

@item 
@ref{aaf,,PyUnicode_AsUCS4Copy()}

@item 
@ref{4f66,,PyUnicode_AsUTF16String()}

@item 
@ref{4f67,,PyUnicode_AsUTF32String()}

@item 
@ref{a90,,PyUnicode_AsUTF8AndSize()}

@item 
@ref{138f,,PyUnicode_AsUTF8String()}

@item 
@ref{1390,,PyUnicode_AsUnicodeEscapeString()}

@item 
@ref{1cff,,PyUnicode_AsWideChar()}

@item 
@ref{ab0,,PyUnicode_AsWideCharString()}

@item 
@ref{19b3,,PyUnicode_BuildEncodingMap()}

@item 
@ref{aab,,PyUnicode_Compare()}

@item 
@ref{1468,,PyUnicode_CompareWithASCIIString()}

@item 
@ref{13a2,,PyUnicode_Concat()}

@item 
@ref{4f68,,PyUnicode_Contains()}

@item 
@ref{4f69,,PyUnicode_Count()}

@item 
@ref{1c90,,PyUnicode_Decode()}

@item 
@ref{4f6a,,PyUnicode_DecodeASCII()}

@item 
@ref{4f6b,,PyUnicode_DecodeCharmap()}

@item 
@ref{4f6c,,PyUnicode_DecodeCodePageStateful()}

@item 
@ref{19da,,PyUnicode_DecodeFSDefault()}

@item 
@ref{4f6d,,PyUnicode_DecodeFSDefaultAndSize()}

@item 
@ref{4f6e,,PyUnicode_DecodeLatin1()}

@item 
@ref{4f6f,,PyUnicode_DecodeLocale()}

@item 
@ref{dbd,,PyUnicode_DecodeLocaleAndSize()}

@item 
@ref{4f70,,PyUnicode_DecodeMBCS()}

@item 
@ref{4f71,,PyUnicode_DecodeMBCSStateful()}

@item 
@ref{4f72,,PyUnicode_DecodeRawUnicodeEscape()}

@item 
@ref{4f73,,PyUnicode_DecodeUTF16()}

@item 
@ref{4f74,,PyUnicode_DecodeUTF16Stateful()}

@item 
@ref{4f75,,PyUnicode_DecodeUTF32()}

@item 
@ref{4f76,,PyUnicode_DecodeUTF32Stateful()}

@item 
@ref{4f77,,PyUnicode_DecodeUTF7()}

@item 
@ref{4f78,,PyUnicode_DecodeUTF7Stateful()}

@item 
@ref{4f79,,PyUnicode_DecodeUTF8()}

@item 
@ref{1a5b,,PyUnicode_DecodeUTF8Stateful()}

@item 
@ref{4f7a,,PyUnicode_DecodeUnicodeEscape()}

@item 
@ref{1395,,PyUnicode_EncodeCodePage()}

@item 
@ref{1cf9,,PyUnicode_EncodeFSDefault()}

@item 
@ref{dbe,,PyUnicode_EncodeLocale()}

@item 
@ref{3b0,,PyUnicode_Equal()}

@item 
@ref{612,,PyUnicode_EqualToUTF8()}

@item 
@ref{611,,PyUnicode_EqualToUTF8AndSize()}

@item 
@ref{f10,,PyUnicode_FSConverter()}

@item 
@ref{790,,PyUnicode_FSDecoder()}

@item 
@ref{4f7b,,PyUnicode_Find()}

@item 
@ref{aad,,PyUnicode_FindChar()}

@item 
@ref{4f7c,,PyUnicode_Format()}

@item 
@ref{4f7d,,PyUnicode_FromEncodedObject()}

@item 
@ref{623,,PyUnicode_FromFormat()}

@item 
@ref{78d,,PyUnicode_FromFormatV()}

@item 
@ref{4f7e,,PyUnicode_FromObject()}

@item 
@ref{4f7f,,PyUnicode_FromOrdinal()}

@item 
@ref{4f80,,PyUnicode_FromString()}

@item 
@ref{4f81,,PyUnicode_FromStringAndSize()}

@item 
@ref{138d,,PyUnicode_FromWideChar()}

@item 
@ref{4f82,,PyUnicode_GetDefaultEncoding()}

@item 
@ref{aa7,,PyUnicode_GetLength()}

@item 
@ref{18e6,,PyUnicode_InternFromString()}

@item 
@ref{aa5,,PyUnicode_InternInPlace()}

@item 
@ref{1c4f,,PyUnicode_IsIdentifier()}

@item 
@ref{13a3,,PyUnicode_Join()}

@item 
@ref{1811,,PyUnicode_Partition()}

@item 
@ref{1812,,PyUnicode_RPartition()}

@item 
@ref{1810,,PyUnicode_RSplit()}

@item 
@ref{1372,,PyUnicode_ReadChar()}

@item 
@ref{4f83,,PyUnicode_Replace()}

@item 
@ref{4f84,,PyUnicode_Resize()}

@item 
@ref{4f85,,PyUnicode_RichCompare()}

@item 
@ref{4f86,,PyUnicode_Split()}

@item 
@ref{4f87,,PyUnicode_Splitlines()}

@item 
@ref{aaa,,PyUnicode_Substring()}

@item 
@ref{aac,,PyUnicode_Tailmatch()}

@item 
@ref{4f88,,PyUnicode_Translate()}

@item 
@ref{4f89,,PyUnicode_Type}

@item 
@ref{1373,,PyUnicode_WriteChar()}

@item 
@ref{458f,,PyVarObject}

@item 
@code{PyVarObject.ob_base}

@item 
@ref{4f8a,,PyVarObject.ob_size}

@item 
@ref{771,,PyVectorcall_Call()}

@item 
@ref{770,,PyVectorcall_NARGS()}

@item 
@code{PyWeakReference}

@item 
@ref{3db,,PyWeakref_GetObject()}

@item 
@ref{3dd,,PyWeakref_GetRef()}

@item 
@ref{4f8b,,PyWeakref_NewProxy()}

@item 
@ref{1b06,,PyWeakref_NewRef()}

@item 
@code{PyWrapperDescr_Type}

@item 
@ref{4f8c,,PyWrapper_New()}

@item 
@code{PyZip_Type}

@item 
@ref{b6f,,Py_AddPendingCall()}

@item 
@ref{4f8d,,Py_AtExit()}

@item 
@ref{4d85,,Py_BEGIN_ALLOW_THREADS}

@item 
@ref{4f8e,,Py_BLOCK_THREADS}

@item 
@ref{3c0,,Py_BuildValue()}

@item 
@ref{baf,,Py_BytesMain()}

@item 
@ref{a7c,,Py_CompileString()}

@item 
@ref{4f8f,,Py_DecRef()}

@item 
@ref{dbb,,Py_DecodeLocale()}

@item 
@ref{c76,,Py_END_ALLOW_THREADS}

@item 
@ref{dbc,,Py_EncodeLocale()}

@item 
@ref{17c3,,Py_EndInterpreter()}

@item 
@ref{3d0,,Py_EnterRecursiveCall()}

@item 
@ref{f46,,Py_Exit()}

@item 
@ref{b71,,Py_FatalError()}

@item 
@code{Py_FileSystemDefaultEncodeErrors}

@item 
@code{Py_FileSystemDefaultEncoding}

@item 
@ref{45d,,Py_Finalize()}

@item 
@ref{f0c,,Py_FinalizeEx()}

@item 
@ref{4f90,,Py_GenericAlias()}

@item 
@ref{4f91,,Py_GenericAliasType}

@item 
@ref{1629,,Py_GetBuildInfo()}

@item 
@ref{4f92,,Py_GetCompiler()}

@item 
@ref{5f1,,Py_GetConstant()}

@item 
@ref{5f2,,Py_GetConstantBorrowed()}

@item 
@ref{4f93,,Py_GetCopyright()}

@item 
@ref{3e7,,Py_GetExecPrefix()}

@item 
@ref{3e1,,Py_GetPath()}

@item 
@ref{4f94,,Py_GetPlatform()}

@item 
@ref{3e3,,Py_GetPrefix()}

@item 
@ref{3ea,,Py_GetProgramFullPath()}

@item 
@ref{3ec,,Py_GetProgramName()}

@item 
@ref{3ed,,Py_GetPythonHome()}

@item 
@code{Py_GetRecursionLimit()}

@item 
@ref{4f95,,Py_GetVersion()}

@item 
@code{Py_HasFileSystemDefaultEncoding}

@item 
@ref{4f96,,Py_IncRef()}

@item 
@ref{45e,,Py_Initialize()}

@item 
@ref{4f97,,Py_InitializeEx()}

@item 
@ref{a97,,Py_Is()}

@item 
@ref{a9a,,Py_IsFalse()}

@item 
@ref{5f5,,Py_IsFinalizing()}

@item 
@ref{4e02,,Py_IsInitialized()}

@item 
@ref{a98,,Py_IsNone()}

@item 
@ref{a99,,Py_IsTrue()}

@item 
@ref{b62,,Py_LeaveRecursiveCall()}

@item 
@ref{e19,,Py_Main()}

@item 
@code{Py_MakePendingCalls()}

@item 
@ref{1a72,,Py_NewInterpreter()}

@item 
@ref{a91,,Py_NewRef()}

@item 
@ref{37e,,Py_PACK_FULL_VERSION()}

@item 
@ref{37d,,Py_PACK_VERSION()}

@item 
@ref{2cf,,Py_REFCNT()}

@item 
@ref{4f98,,Py_ReprEnter()}

@item 
@ref{4f99,,Py_ReprLeave()}

@item 
@ref{190b,,Py_SetProgramName()}

@item 
@ref{190a,,Py_SetPythonHome()}

@item 
@code{Py_SetRecursionLimit()}

@item 
@ref{3c7,,Py_TYPE()}

@item 
@ref{33c,,Py_UCS4}

@item 
@ref{4f9a,,Py_UNBLOCK_THREADS}

@item 
@code{Py_UTF8Mode}

@item 
@ref{4f9b,,Py_VaBuildValue()}

@item 
@ref{37f,,Py_Version}

@item 
@ref{a92,,Py_XNewRef()}

@item 
@ref{954,,Py_buffer}

@item 
@code{Py_intptr_t}

@item 
@ref{c4c,,Py_ssize_t}

@item 
@code{Py_uintptr_t}

@item 
@ref{4f9c,,allocfunc}

@item 
@ref{4f9d,,binaryfunc}

@item 
@ref{4f9e,,descrgetfunc}

@item 
@ref{4f9f,,descrsetfunc}

@item 
@ref{4fa0,,destructor}

@item 
@ref{4fa1,,getattrfunc}

@item 
@ref{4fa2,,getattrofunc}

@item 
@ref{4fa3,,getbufferproc}

@item 
@ref{4fa4,,getiterfunc}

@item 
@ref{4fa5,,getter}

@item 
@ref{4fa6,,hashfunc}

@item 
@ref{4fa7,,initproc}

@item 
@ref{4fa8,,inquiry}

@item 
@ref{4fa9,,iternextfunc}

@item 
@ref{4faa,,lenfunc}

@item 
@ref{4fab,,newfunc}

@item 
@ref{4fac,,objobjargproc}

@item 
@ref{4fad,,objobjproc}

@item 
@ref{4fae,,releasebufferproc}

@item 
@ref{4faf,,reprfunc}

@item 
@ref{4fb0,,richcmpfunc}

@item 
@ref{4fb1,,setattrfunc}

@item 
@ref{4fb2,,setattrofunc}

@item 
@ref{4fb3,,setter}

@item 
@ref{4fb4,,ssizeargfunc}

@item 
@ref{4fb5,,ssizeobjargproc}

@item 
@code{ssizessizeargfunc}

@item 
@code{ssizessizeobjargproc}

@item 
@code{symtable}

@item 
@ref{4fb6,,ternaryfunc}

@item 
@ref{4fb7,,traverseproc}

@item 
@ref{4fb8,,unaryfunc}

@item 
@ref{772,,vectorcallfunc}

@item 
@ref{4fb9,,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,參照計數<3>,C API 穩定性,Python/C API 參考手冊
@anchor{c-api/veryhigh doc}@anchor{4fba}@anchor{c-api/veryhigh the-very-high-level-layer}@anchor{4fbb}@anchor{c-api/veryhigh translation-repo}@anchor{4fbc}@anchor{c-api/veryhigh veryhigh}@anchor{4fbd}
@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{4fbe,,Py_eval_input},
@ref{4fbf,,Py_file_input}, and @ref{4fc0,,Py_single_input}.  These are described
following the functions which accept them as parameters.

Note also that several of these functions take FILE* parameters.  One
particular issue which needs to be handled carefully is that the @code{FILE}
structure for different C libraries can be different and incompatible.  Under
Windows (at least), it is possible for dynamically linked extensions to actually
use different libraries, so care should be taken that FILE* parameters
are only passed to these functions if it is certain that they were created by
the same library that the Python runtime is using.

@geindex PyRun_AnyFile (C function)
@anchor{c-api/veryhigh c PyRun_AnyFile}@anchor{4fc1}
@deffn {C 函式} int PyRun_AnyFile (FILE *fp, const char *filename)

This is a simplified interface to @ref{4fc2,,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{4fc3}
@deffn {C 函式} int PyRun_AnyFileFlags (FILE *fp, const char *filename, PyCompilerFlags *flags)

This is a simplified interface to @ref{4fc2,,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{4fc4}
@deffn {C 函式} int PyRun_AnyFileEx (FILE *fp, const char *filename, int closeit)

This is a simplified interface to @ref{4fc2,,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{4fc2}
@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{4fc5,,PyRun_InteractiveLoop()}, otherwise return the result of
@ref{4dd4,,PyRun_SimpleFile()}.  `filename' is decoded from the filesystem
encoding (@ref{e4e,,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{4dd3}
@deffn {C 函式} int PyRun_SimpleString (const char *command)

This is a simplified interface to @ref{4fc6,,PyRun_SimpleStringFlags()} below,
leaving the @ref{c8f,,PyCompilerFlags}* argument set to @code{NULL}.
@end deffn

@geindex PyRun_SimpleStringFlags (C function)
@anchor{c-api/veryhigh c PyRun_SimpleStringFlags}@anchor{4fc6}
@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 @ref{1,,__main__} does not already exist, it
is created.  Returns @code{0} on success or @code{-1} if an exception was raised.  If
there was an error, there is no way to get the exception information. For the
meaning of `flags', see below.

Note that if an otherwise unhandled @ref{f37,,SystemExit} is raised, this
function will not return @code{-1}, but exit the process, as long as
@ref{3ff,,PyConfig.inspect} is zero.
@end deffn

@geindex PyRun_SimpleFile (C function)
@anchor{c-api/veryhigh c PyRun_SimpleFile}@anchor{4dd4}
@deffn {C 函式} int PyRun_SimpleFile (FILE *fp, const char *filename)

This is a simplified interface to @ref{1bbe,,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{4fc7}
@deffn {C 函式} int PyRun_SimpleFileEx (FILE *fp, const char *filename, int closeit)

This is a simplified interface to @ref{1bbe,,PyRun_SimpleFileExFlags()} below,
leaving `flags' set to @code{NULL}.
@end deffn

@geindex PyRun_SimpleFileExFlags (C function)
@anchor{c-api/veryhigh c PyRun_SimpleFileExFlags}@anchor{1bbe}
@deffn {C 函式} int PyRun_SimpleFileExFlags (FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)

Similar to @ref{4fc6,,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{756,,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_InteractiveOne (C function)
@anchor{c-api/veryhigh c PyRun_InteractiveOne}@anchor{4fc8}
@deffn {C 函式} int PyRun_InteractiveOne (FILE *fp, const char *filename)

This is a simplified interface to @ref{4fc9,,PyRun_InteractiveOneFlags()} below,
leaving `flags' set to @code{NULL}.
@end deffn

@geindex PyRun_InteractiveOneFlags (C function)
@anchor{c-api/veryhigh c PyRun_InteractiveOneFlags}@anchor{4fc9}
@deffn {C 函式} int PyRun_InteractiveOneFlags (FILE *fp, const char *filename, PyCompilerFlags *flags)

Read and execute a single statement from a file associated with an
interactive device according to the `flags' argument.  The user will be
prompted using @code{sys.ps1} and @code{sys.ps2}.  `filename' is decoded from the
@ref{756,,filesystem encoding and error handler}.

Returns @code{0} when the input was
executed successfully, @code{-1} if there was an exception, or an error code
from the @code{errcode.h} include file distributed as part of Python if
there was a parse error.  (Note that @code{errcode.h} is not included by
@code{Python.h}, so must be included specifically if needed.)
@end deffn

@geindex PyRun_InteractiveLoop (C function)
@anchor{c-api/veryhigh c PyRun_InteractiveLoop}@anchor{4fc5}
@deffn {C 函式} int PyRun_InteractiveLoop (FILE *fp, const char *filename)

This is a simplified interface to @ref{4fca,,PyRun_InteractiveLoopFlags()} below,
leaving `flags' set to @code{NULL}.
@end deffn

@geindex PyRun_InteractiveLoopFlags (C function)
@anchor{c-api/veryhigh c PyRun_InteractiveLoopFlags}@anchor{4fca}
@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{756,,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{79d}
@deffn {C 變數} int (*PyOS_InputHook)(void)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Can be set to point to a function with the prototype
@code{int func(void)}.  The function will be called when Python's
interpreter prompt is about to become idle and wait for user input
from the terminal.  The return value is ignored.  Overriding this
hook can be used to integrate the interpreter's prompt with other
event loops, as done in the @code{Modules/_tkinter.c} in the
Python source code.


在 3.12 版的變更: This function is only called from the
@ref{163,,main interpreter}.

@end deffn

@geindex PyOS_ReadlineFunctionPointer (C var)
@anchor{c-api/veryhigh c PyOS_ReadlineFunctionPointer}@anchor{79e}
@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{bf,,readline} module sets
this hook to provide line-editing and tab-completion features.

The result must be a string allocated by @ref{629,,PyMem_RawMalloc()} or
@ref{62b,,PyMem_RawRealloc()}, or @code{NULL} if an error occurred.


在 3.4 版的變更: The result must be allocated by @ref{629,,PyMem_RawMalloc()} or
@ref{62b,,PyMem_RawRealloc()}, instead of being allocated by
@ref{e5b,,PyMem_Malloc()} or @ref{122d,,PyMem_Realloc()}.



在 3.12 版的變更: This function is only called from the
@ref{163,,main interpreter}.

@end deffn

@geindex PyRun_String (C function)
@anchor{c-api/veryhigh c PyRun_String}@anchor{1c89}
@deffn {C 函式} @ref{5d7,,PyObject} *PyRun_String (const char *str, int start, PyObject *globals, PyObject *locals)
`回傳值：新的參照。'
This is a simplified interface to @ref{4fcb,,PyRun_StringFlags()} below, leaving
`flags' set to @code{NULL}.
@end deffn

@geindex PyRun_StringFlags (C function)
@anchor{c-api/veryhigh c PyRun_StringFlags}@anchor{4fcb}
@deffn {C 函式} @ref{5d7,,PyObject} *PyRun_StringFlags (const char *str, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)
`回傳值：新的參照。'
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 one of the following:
@ref{4fbe,,Py_eval_input}, @ref{4fbf,,Py_file_input}, or @ref{4fc0,,Py_single_input}.

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{4fcc}
@deffn {C 函式} @ref{5d7,,PyObject} *PyRun_File (FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals)
`回傳值：新的參照。'
This is a simplified interface to @ref{4fcd,,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{4fce}
@deffn {C 函式} @ref{5d7,,PyObject} *PyRun_FileEx (FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit)
`回傳值：新的參照。'
This is a simplified interface to @ref{4fcd,,PyRun_FileExFlags()} below, leaving
`flags' set to @code{NULL}.
@end deffn

@geindex PyRun_FileFlags (C function)
@anchor{c-api/veryhigh c PyRun_FileFlags}@anchor{4fcf}
@deffn {C 函式} @ref{5d7,,PyObject} *PyRun_FileFlags (FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)
`回傳值：新的參照。'
This is a simplified interface to @ref{4fcd,,PyRun_FileExFlags()} below, leaving
`closeit' set to @code{0}.
@end deffn

@geindex PyRun_FileExFlags (C function)
@anchor{c-api/veryhigh c PyRun_FileExFlags}@anchor{4fcd}
@deffn {C 函式} @ref{5d7,,PyObject} *PyRun_FileExFlags (FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit, PyCompilerFlags *flags)
`回傳值：新的參照。'
Similar to @ref{4fcb,,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{756,,filesystem encoding and error handler}.
If `closeit' is true, the file is closed before @ref{4fcd,,PyRun_FileExFlags()}
returns.
@end deffn

@geindex Py_CompileString (C function)
@anchor{c-api/veryhigh c Py_CompileString}@anchor{a7c}
@deffn {C 函式} @ref{5d7,,PyObject} *Py_CompileString (const char *str, const char *filename, int start)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
This is a simplified interface to @ref{4fd0,,Py_CompileStringFlags()} below, leaving
`flags' set to @code{NULL}.
@end deffn

@geindex Py_CompileStringFlags (C function)
@anchor{c-api/veryhigh c Py_CompileStringFlags}@anchor{4fd0}
@deffn {C 函式} @ref{5d7,,PyObject} *Py_CompileStringFlags (const char *str, const char *filename, int start, PyCompilerFlags *flags)
`回傳值：新的參照。'
This is a simplified interface to @ref{4fd1,,Py_CompileStringExFlags()} below, with
`optimize' set to @code{-1}.
@end deffn

@geindex Py_CompileStringObject (C function)
@anchor{c-api/veryhigh c Py_CompileStringObject}@anchor{4fd2}
@deffn {C 函式} @ref{5d7,,PyObject} *Py_CompileStringObject (const char *str, PyObject *filename, int start, PyCompilerFlags *flags, int optimize)
`回傳值：新的參照。'
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{4fbe,,Py_eval_input},
@ref{4fbf,,Py_file_input}, or @ref{4fc0,,Py_single_input}.  The filename specified by
`filename' is used to construct the code object and may appear in tracebacks or
@ref{18e,,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{18c,,-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).


在 3.4 版被加入.

@end deffn

@geindex Py_CompileStringExFlags (C function)
@anchor{c-api/veryhigh c Py_CompileStringExFlags}@anchor{4fd1}
@deffn {C 函式} @ref{5d7,,PyObject} *Py_CompileStringExFlags (const char *str, const char *filename, int start, PyCompilerFlags *flags, int optimize)
`回傳值：新的參照。'
Like @ref{4fd2,,Py_CompileStringObject()}, but `filename' is a byte string
decoded from the @ref{756,,filesystem encoding and error handler}.


在 3.2 版被加入.

@end deffn

@geindex PyEval_EvalCode (C function)
@anchor{c-api/veryhigh c PyEval_EvalCode}@anchor{a7d}
@deffn {C 函式} @ref{5d7,,PyObject} *PyEval_EvalCode (PyObject *co, PyObject *globals, PyObject *locals)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
This is a simplified interface to @ref{1a25,,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{1a25}
@deffn {C 函式} @ref{5d7,,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)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{59f,,keyword-only} arguments and a closure tuple of cells.
@end deffn

@geindex PyEval_EvalFrame (C function)
@anchor{c-api/veryhigh c PyEval_EvalFrame}@anchor{4e67}
@deffn {C 函式} @ref{5d7,,PyObject} *PyEval_EvalFrame (PyFrameObject *f)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Evaluate an execution frame.  This is a simplified interface to
@ref{1229,,PyEval_EvalFrameEx()}, for backward compatibility.
@end deffn

@geindex PyEval_EvalFrameEx (C function)
@anchor{c-api/veryhigh c PyEval_EvalFrameEx}@anchor{1229}
@deffn {C 函式} @ref{5d7,,PyObject} *PyEval_EvalFrameEx (PyFrameObject *f, int throwflag)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{715,,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{4fd3}
@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 Py_eval_input (C var)
@anchor{c-api/veryhigh c Py_eval_input}@anchor{4fbe}
@deffn {C 變數} int Py_eval_input

@geindex Py_CompileString（C 函式）

The start symbol from the Python grammar for isolated expressions; for use with
@ref{a7c,,Py_CompileString()}.
@end deffn

@geindex Py_file_input (C var)
@anchor{c-api/veryhigh c Py_file_input}@anchor{4fbf}
@deffn {C 變數} int Py_file_input

@geindex Py_CompileString（C 函式）

The start symbol from the Python grammar for sequences of statements as read
from a file or other source; for use with @ref{a7c,,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{4fc0}
@deffn {C 變數} int Py_single_input

@geindex Py_CompileString（C 函式）

The start symbol from the Python grammar for a single statement; for use with
@ref{a7c,,Py_CompileString()}. This is the symbol used for the interactive
interpreter loop.
@end deffn

@geindex PyCompilerFlags (C struct)
@anchor{c-api/veryhigh c PyCompilerFlags}@anchor{c8f}
@deffn {C 結構} 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{4fd4,,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{4fd4}
@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{4fd5}
@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{4fd4,,cf_flags}.
@end deffn


在 3.8 版的變更: 新增 `cf_feature_version' 欄位。


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{4fd6}
@deffn {C 巨集} PyCF_ALLOW_TOP_LEVEL_AWAIT
@anchor{c-api/veryhigh c PyCF_ONLY_AST}@anchor{4fd7}
@deffnx {C 巨集} PyCF_ONLY_AST
@anchor{c-api/veryhigh c PyCF_OPTIMIZED_AST}@anchor{4fd8}
@deffnx {C 巨集} PyCF_OPTIMIZED_AST
@anchor{c-api/veryhigh c PyCF_TYPE_COMMENTS}@anchor{4fd9}
@deffnx {C 巨集} PyCF_TYPE_COMMENTS

See @ref{2470,,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{4fda,,CO_FUTURE_ANNOTATIONS} to enable features normally
selectable using @ref{45b,,future statements}.
See @ref{4fdb,,程式碼物件旗標} for a complete 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 參照計數<3>,例外處理,The Very High Level Layer,Python/C API 參考手冊
@anchor{c-api/refcounting doc}@anchor{4fdc}@anchor{c-api/refcounting countingrefs}@anchor{4fdd}@anchor{c-api/refcounting reference-counting}@anchor{4fde}@anchor{c-api/refcounting translation-repo}@anchor{4fdf}
@section 參照計數


本節中的函式與巨集用於管理 Python 物件的參照計數。

@geindex Py_REFCNT (C function)
@anchor{c-api/refcounting c Py_REFCNT}@anchor{2cf}
@deffn {C 函式} @ref{c4c,,Py_ssize_t} Py_REFCNT (PyObject *o)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.14 版本開始.'
取得物件 `o' 的參照計數。

請注意，回傳的值可能實際上並不反映實際保存了多少對該物件的參照。例如，某些物件是「@ref{290,,不滅的 (immortal)}」，並且具有非常高的參照計數，不能反映實際的參照數量。因此，除了 0 或 1 以外，不要依賴回傳值的準確性。

使用 @ref{a9f,,Py_SET_REFCNT()} 函式設定物件參照計數。

@cartouche
@quotation 備註 
On @ref{1f4,,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{3c4,,PyUnstable_Object_IsUniquelyReferenced()}
for that instead.

See also the function @ref{3c5,,PyUnstable_Object_IsUniqueReferencedTemporary()}.
@end quotation
@end cartouche


在 3.10 版的變更: @ref{2cf,,Py_REFCNT()} 更改為行內靜態函式 (inline static function)。



在 3.11 版的變更: 參數型別不再是 const @ref{5d7,,PyObject}*。

@end deffn

@geindex Py_SET_REFCNT (C function)
@anchor{c-api/refcounting c Py_SET_REFCNT}@anchor{a9f}
@deffn {C 函式} void Py_SET_REFCNT (PyObject *o, Py_ssize_t refcnt)

設定物件 `o' 的參照計數。

在@ref{202f,,啟用自由執行緒的 Python 建置}中，如果 `refcnt' 大於 @code{UINT32_MAX}，則該物件會被設為@ref{290,,不滅的 (immortal)}。

請注意，此函式對@ref{290,,不滅的}物件沒有影響。


在 3.9 版被加入.



在 3.12 版的變更: 不滅的物件不會被修改。

@end deffn

@geindex Py_INCREF (C function)
@anchor{c-api/refcounting c Py_INCREF}@anchor{788}
@deffn {C 函式} void Py_INCREF (PyObject *o)

代表取得對於物件 `o' 的新@ref{5da,,強參照}，即它正在使用且不應被銷毀。

請注意，此函式對@ref{290,,不滅的}物件沒有影響。

此函式通常用於將@ref{3d5,,借用參照}原地 (in-place) 轉換為@ref{5da,,強參照}。@ref{a91,,Py_NewRef()} 函式可用於建立新的@ref{5da,,強參照}。

使用完該物件後，透過呼叫 @ref{789,,Py_DECREF()} 來釋放它。

該物件不能為 @code{NULL}；如果你不確定它不是 @code{NULL}，請使用 @ref{c51,,Py_XINCREF()}。

不要期望此函式會以任何方式實際修改 `o'，至少對於
@geindex Python Enhancement Proposals; PEP 0683
某些物件@footnote{https://peps.python.org/pep-0683/}來說，此函式沒有任何效果。


在 3.12 版的變更: 不滅的物件不會被修改。

@end deffn

@geindex Py_XINCREF (C function)
@anchor{c-api/refcounting c Py_XINCREF}@anchor{c51}
@deffn {C 函式} void Py_XINCREF (PyObject *o)

與 @ref{788,,Py_INCREF()} 類似，但物件 `o' 可以為 @code{NULL}，在這種情況下這就不會有任何效果。

另請見 @ref{a92,,Py_XNewRef()}。
@end deffn

@geindex Py_NewRef (C function)
@anchor{c-api/refcounting c Py_NewRef}@anchor{a91}
@deffn {C 函式} @ref{5d7,,PyObject} *Py_NewRef (PyObject *o)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.10 版本開始.'
建立對物件的新@ref{5da,,強參照}：於 `o' 呼叫 @ref{788,,Py_INCREF()} 並回傳物件 `o'。

當不再需要@ref{5da,,強參照}時，應對其呼叫 @ref{789,,Py_DECREF()} 以釋放該參照。

物件 `o' 不能為 @code{NULL}；如果 `o' 可以為 @code{NULL}，則使用 @ref{a92,,Py_XNewRef()}。

舉例來說：

@example
Py_INCREF(obj);
self->attr = obj;
@end example

可以寫成：

@example
self->attr = Py_NewRef(obj);
@end example

另請參閱 @ref{788,,Py_INCREF()}。


在 3.10 版被加入.

@end deffn

@geindex Py_XNewRef (C function)
@anchor{c-api/refcounting c Py_XNewRef}@anchor{a92}
@deffn {C 函式} @ref{5d7,,PyObject} *Py_XNewRef (PyObject *o)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.10 版本開始.'
與 @ref{a91,,Py_NewRef()} 類似，但物件 `o' 可以為 NULL。

如果物件 `o' 為 @code{NULL}，則該函式僅回傳 @code{NULL}。


在 3.10 版被加入.

@end deffn

@geindex Py_DECREF (C function)
@anchor{c-api/refcounting c Py_DECREF}@anchor{789}
@deffn {C 函式} void Py_DECREF (PyObject *o)

釋放一個對物件 `o' 的@ref{5da,,強參照}，代表該參照不會再被使用。

請注意，此函式對@ref{290,,不滅的}物件沒有影響。

如果最後一個@ref{5da,,強參照}被釋放（即物件的參照計數達到零），則觸發物件之型別的釋放函式 (deallocation function)（不得為 @code{NULL}）。

此函式通常用於在退出作用域之前刪除@ref{5da,,強參照}。

該物件不能為 @code{NULL}；如果你不確定它不是 @code{NULL}，請改用 @ref{98a,,Py_XDECREF()}。

不要期望此函式會以任何方式實際修改 `o'，至少對於
@geindex Python Enhancement Proposals; PEP 683
某些物件@footnote{https://peps.python.org/pep-0683/}來說，此函式沒有任何效果。

@cartouche
@quotation 警告 
釋放函式可以導致任意 Python 程式碼被叫用（例如，當釋放具有 @ref{11f8,,__del__()} 方法的類別實例時）。雖然此類程式碼中的例外不會被傳遞出來，但​​執行的程式碼可以自由存取所有 Python 全域變數。這意味著在叫用 @ref{789,,Py_DECREF()} 之前，可從全域變數存取的任何物件都應處於一致狀態。例如，從 list 中刪除物件的程式碼應將已刪除物件的參照複製到臨時變數中，更新 list 資料結構，然後為臨時變數呼叫 @ref{789,,Py_DECREF()}。
@end quotation
@end cartouche


在 3.12 版的變更: 不滅的物件不會被修改。

@end deffn

@geindex Py_XDECREF (C function)
@anchor{c-api/refcounting c Py_XDECREF}@anchor{98a}
@deffn {C 函式} void Py_XDECREF (PyObject *o)

和 @ref{789,,Py_DECREF()} 類似，但該物件可以是 @code{NULL}，在這種情況下巨集不起作用。在這裡也會出現與 @ref{789,,Py_DECREF()} 相同的警告。
@end deffn

@geindex Py_CLEAR (C function)
@anchor{c-api/refcounting c Py_CLEAR}@anchor{791}
@deffn {C 函式} void Py_CLEAR (PyObject *o)

釋放對於物件 `o' 的@ref{5da,,強參照}。該物件可能是 @code{NULL}，在這種情況下巨集不起作用；否則，效果與 @ref{789,,Py_DECREF()} 相同，除非引數也設定為 @code{NULL}。@ref{789,,Py_DECREF()} 的警告不適用於傳遞的物件，因為巨集在釋放其參照之前小心地使用臨時變數並將引數設定為 @code{NULL}。

每當要釋放垃圾回收 (garbage collection) 期間可能被遍歷到之對於物件的參照時，使用此巨集是個好主意。


在 3.12 版的變更: 巨集引數現在僅會被求值 (evaluate) 一次。如果引數有其他副作用，則不再重複作用。

@end deffn

@geindex Py_IncRef (C function)
@anchor{c-api/refcounting c Py_IncRef}@anchor{4f96}
@deffn {C 函式} void Py_IncRef (PyObject *o)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
代表取得對於物件 `o' 的@ref{5da,,強參照}。@ref{c51,,Py_XINCREF()} 的函式版本。它可用於 Python 的 runtime 動態嵌入。
@end deffn

@geindex Py_DecRef (C function)
@anchor{c-api/refcounting c Py_DecRef}@anchor{4f8f}
@deffn {C 函式} void Py_DecRef (PyObject *o)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
釋放對物件 `o' 的@ref{5da,,強參照}。@ref{98a,,Py_XDECREF()} 的函式版本。它可用於 Python 的 runtime 動態嵌入。
@end deffn

@geindex Py_SETREF (C macro)
@anchor{c-api/refcounting c Py_SETREF}@anchor{792}
@deffn {C 巨集} Py_SETREF (dst, src)

巨集安全地釋放對於物件 `dst' 的@ref{5da,,強參照}並將 `dst' 設定為 `src'。

與 @ref{791,,Py_CLEAR()} 的情況一樣，「明顯的」程式碼可能是致命的：

@example
Py_DECREF(dst);
dst = src;
@end example

安全的方法是：

@example
Py_SETREF(dst, src);
@end example

這會在釋放對 `dst' 舊值的參照`之前'將 `dst' 設定為 `src'，使得因 `dst' 被拆除而觸發的任何副作用 (side-effect) 之程式碼不會相信 `dst' 是指向一個有效物件。


在 3.6 版被加入.



在 3.12 版的變更: 巨集引數現在僅會被求值一次。如果引數有其他副作用，則不再重複作用。

@end deffn

@geindex Py_XSETREF (C macro)
@anchor{c-api/refcounting c Py_XSETREF}@anchor{793}
@deffn {C 巨集} Py_XSETREF (dst, src)

@ref{792,,Py_SETREF} 巨集的變體，請改用 @ref{98a,,Py_XDECREF()} 而非 @ref{789,,Py_DECREF()}。


在 3.6 版被加入.



在 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 例外處理,Defining extension modules,參照計數<3>,Python/C API 參考手冊
@anchor{c-api/exceptions doc}@anchor{4fe0}@anchor{c-api/exceptions exception-handling}@anchor{4fe1}@anchor{c-api/exceptions exceptionhandling}@anchor{483e}@anchor{c-api/exceptions translation-repo}@anchor{4fe2}
@section 例外處理


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{893,,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:: 
* 訊號處理:: 
* 例外類別: 例外類別<2>. 
* 例外物件:: 
* Unicode 例外物件:: 
* 遞迴控制:: 
* 例外和警告型別:: 

@end menu

@node Printing and clearing,Raising exceptions,,例外處理
@anchor{c-api/exceptions printing-and-clearing}@anchor{4fe3}
@subsection Printing and clearing


@geindex PyErr_Clear (C function)
@anchor{c-api/exceptions c PyErr_Clear}@anchor{122c}
@deffn {C 函式} void PyErr_Clear ()
` 為 @ref{76e,,穩定 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{4e5b}
@deffn {C 函式} void PyErr_PrintEx (int set_sys_last_vars)
` 為 @ref{76e,,穩定 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{6de,,sys.last_exc} is
set to the printed exception. For backwards compatibility, the
deprecated variables @ref{6df,,sys.last_type}, @ref{6e0,,sys.last_value} and
@ref{6e1,,sys.last_traceback} are also set to the type, value and traceback
of this exception, respectively.


在 3.12 版的變更: 新增 @ref{6de,,sys.last_exc} 設定。

@end deffn

@geindex PyErr_Print (C function)
@anchor{c-api/exceptions c PyErr_Print}@anchor{1bfa}
@deffn {C 函式} void PyErr_Print ()
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@code{PyErr_PrintEx(1)} 的別名。
@end deffn

@geindex PyErr_WriteUnraisable (C function)
@anchor{c-api/exceptions c PyErr_WriteUnraisable}@anchor{5ea}
@deffn {C 函式} void PyErr_WriteUnraisable (PyObject *obj)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Call @ref{502,,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{11f8,,__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 版的變更: 使用 @ref{502,,sys.unraisablehook()}。

@end deffn

@geindex PyErr_FormatUnraisable (C function)
@anchor{c-api/exceptions c PyErr_FormatUnraisable}@anchor{5e9}
@deffn {C 函式} void PyErr_FormatUnraisable (const char *format, ...)

Similar to @ref{5ea,,PyErr_WriteUnraisable()}, but the `format' and subsequent
parameters help format the warning message; they have the same meaning and
values as in @ref{623,,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.


在 3.13 版被加入.

@end deffn

@geindex PyErr_DisplayException (C function)
@anchor{c-api/exceptions c PyErr_DisplayException}@anchor{433}
@deffn {C 函式} void PyErr_DisplayException (PyObject *exc)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.12 版本開始.'
Print the standard traceback display of @code{exc} to @code{sys.stderr}, including
chained exceptions and notes.


在 3.12 版被加入.

@end deffn

@node Raising exceptions,Issuing warnings,Printing and clearing,例外處理
@anchor{c-api/exceptions raising-exceptions}@anchor{4fe4}
@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{795}
@deffn {C 函式} void PyErr_SetString (PyObject *type, const char *message)
` 為 @ref{76e,,穩定 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{4e98,,PyExc_RuntimeError}.  You need not create a new
@ref{5da,,strong reference} to it (e.g. with @ref{788,,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{794}
@deffn {C 函式} void PyErr_SetObject (PyObject *type, PyObject *value)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
This function is similar to @ref{795,,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{10ac}
@deffn {C 函式} @ref{5d7,,PyObject} *PyErr_Format (PyObject *exception, const char *format, ...)
`回傳值：總是為 NULL。'` 為 @ref{76e,,穩定 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{623,,PyUnicode_FromFormat()}. `format' is an ASCII-encoded
string.
@end deffn

@geindex PyErr_FormatV (C function)
@anchor{c-api/exceptions c PyErr_FormatV}@anchor{10ab}
@deffn {C 函式} @ref{5d7,,PyObject} *PyErr_FormatV (PyObject *exception, const char *format, va_list vargs)
`回傳值：總是為 NULL。'` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.5 版本開始.'
Same as @ref{10ac,,PyErr_Format()}, but taking a @code{va_list} argument rather
than a variable number of arguments.


在 3.5 版被加入.

@end deffn

@geindex PyErr_SetNone (C function)
@anchor{c-api/exceptions c PyErr_SetNone}@anchor{4e63}
@deffn {C 函式} void PyErr_SetNone (PyObject *type)
` 為 @ref{76e,,穩定 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{4e58}
@deffn {C 函式} int PyErr_BadArgument ()
` 為 @ref{76e,,穩定 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{4d61}
@deffn {C 函式} @ref{5d7,,PyObject} *PyErr_NoMemory ()
`回傳值：總是為 NULL。'` 為 @ref{76e,,穩定 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{4d60}
@deffn {C 函式} @ref{5d7,,PyObject} *PyErr_SetFromErrno (PyObject *type)
`回傳值：總是為 NULL。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
@geindex strerror（C 函式）

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{68c,,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{4e5f}
@deffn {C 函式} @ref{5d7,,PyObject} *PyErr_SetFromErrnoWithFilenameObject (PyObject *type, PyObject *filenameObject)
`回傳值：總是為 NULL。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Similar to @ref{4d60,,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{2c0,,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{4e60}
@deffn {C 函式} @ref{5d7,,PyObject} *PyErr_SetFromErrnoWithFilenameObjects (PyObject *type, PyObject *filenameObject, PyObject *filenameObject2)
`回傳值：總是為 NULL。'` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.7 版本開始.'
Similar to @ref{4e5f,,PyErr_SetFromErrnoWithFilenameObject()}, but takes a second
filename object, for raising errors when a function that takes two filenames
fails.


在 3.4 版被加入.

@end deffn

@geindex PyErr_SetFromErrnoWithFilename (C function)
@anchor{c-api/exceptions c PyErr_SetFromErrnoWithFilename}@anchor{19d7}
@deffn {C 函式} @ref{5d7,,PyObject} *PyErr_SetFromErrnoWithFilename (PyObject *type, const char *filename)
`回傳值：總是為 NULL。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Similar to @ref{4e5f,,PyErr_SetFromErrnoWithFilenameObject()}, but the filename
is given as a C string.  `filename' is decoded from the @ref{756,,filesystem encoding and error handler}.
@end deffn

@geindex PyErr_SetFromWindowsErr (C function)
@anchor{c-api/exceptions c PyErr_SetFromWindowsErr}@anchor{4e61}
@deffn {C 函式} @ref{5d7,,PyObject} *PyErr_SetFromWindowsErr (int ierr)
`回傳值：總是為 NULL。'` 為 @ref{76e,,穩定 ABI 的一部分} on Windows 自 3.7 版本開始.'
This is a convenience function to raise @ref{2c0,,OSError}. If called with
`ierr' of @code{0}, the error code returned by a call to @code{GetLastError()}
is used instead.  It calls the Win32 function @code{FormatMessage()} to retrieve
the Windows description of error code given by `ierr' or @code{GetLastError()},
then it constructs a @ref{2c0,,OSError} object with the @ref{259a,,winerror}
attribute set to the error code, the @ref{259b,,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{2006,,可用性}: Windows.
@end deffn

@geindex PyErr_SetExcFromWindowsErr (C function)
@anchor{c-api/exceptions c PyErr_SetExcFromWindowsErr}@anchor{4e5c}
@deffn {C 函式} @ref{5d7,,PyObject} *PyErr_SetExcFromWindowsErr (PyObject *type, int ierr)
`回傳值：總是為 NULL。'` 為 @ref{76e,,穩定 ABI 的一部分} on Windows 自 3.7 版本開始.'
Similar to @ref{4e61,,PyErr_SetFromWindowsErr()}, with an additional parameter
specifying the exception type to be raised.

@ref{2006,,可用性}: Windows.
@end deffn

@geindex PyErr_SetFromWindowsErrWithFilename (C function)
@anchor{c-api/exceptions c PyErr_SetFromWindowsErrWithFilename}@anchor{19d9}
@deffn {C 函式} @ref{5d7,,PyObject} *PyErr_SetFromWindowsErrWithFilename (int ierr, const char *filename)
`回傳值：總是為 NULL。'` 為 @ref{76e,,穩定 ABI 的一部分} on Windows 自 3.7 版本開始.'
Similar to @ref{4e61,,PyErr_SetFromWindowsErr()}, with the additional behavior
that if `filename' is not @code{NULL}, it is decoded from the filesystem
encoding (@ref{e49,,os.fsdecode()}) and passed to the constructor of
@ref{2c0,,OSError} as a third parameter to be used to define the
@code{filename} attribute of the exception instance.

@ref{2006,,可用性}: Windows.
@end deffn

@geindex PyErr_SetExcFromWindowsErrWithFilenameObject (C function)
@anchor{c-api/exceptions c PyErr_SetExcFromWindowsErrWithFilenameObject}@anchor{4e5d}
@deffn {C 函式} @ref{5d7,,PyObject} *PyErr_SetExcFromWindowsErrWithFilenameObject (PyObject *type, int ierr, PyObject *filename)
`回傳值：總是為 NULL。'` 為 @ref{76e,,穩定 ABI 的一部分} on Windows 自 3.7 版本開始.'
Similar to @ref{4e5c,,PyErr_SetExcFromWindowsErr()}, with the additional behavior
that if `filename' is not @code{NULL}, it is passed to the constructor of
@ref{2c0,,OSError} as a third parameter to be used to define the
@code{filename} attribute of the exception instance.

@ref{2006,,可用性}: Windows.
@end deffn

@geindex PyErr_SetExcFromWindowsErrWithFilenameObjects (C function)
@anchor{c-api/exceptions c PyErr_SetExcFromWindowsErrWithFilenameObjects}@anchor{4e5e}
@deffn {C 函式} @ref{5d7,,PyObject} *PyErr_SetExcFromWindowsErrWithFilenameObjects (PyObject *type, int ierr, PyObject *filename, PyObject *filename2)
`回傳值：總是為 NULL。'` 為 @ref{76e,,穩定 ABI 的一部分} on Windows 自 3.7 版本開始.'
Similar to @ref{4e5d,,PyErr_SetExcFromWindowsErrWithFilenameObject()},
but accepts a second filename object.

@ref{2006,,可用性}: Windows.


在 3.4 版被加入.

@end deffn

@geindex PyErr_SetExcFromWindowsErrWithFilename (C function)
@anchor{c-api/exceptions c PyErr_SetExcFromWindowsErrWithFilename}@anchor{19d8}
@deffn {C 函式} @ref{5d7,,PyObject} *PyErr_SetExcFromWindowsErrWithFilename (PyObject *type, int ierr, const char *filename)
`回傳值：總是為 NULL。'` 為 @ref{76e,,穩定 ABI 的一部分} on Windows 自 3.7 版本開始.'
Similar to @ref{19d9,,PyErr_SetFromWindowsErrWithFilename()}, with an additional
parameter specifying the exception type to be raised.

@ref{2006,,可用性}: Windows.
@end deffn

@geindex PyErr_SetImportError (C function)
@anchor{c-api/exceptions c PyErr_SetImportError}@anchor{f34}
@deffn {C 函式} @ref{5d7,,PyObject} *PyErr_SetImportError (PyObject *msg, PyObject *name, PyObject *path)
`回傳值：總是為 NULL。'` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.7 版本開始.'
This is a convenience function to raise @ref{653,,ImportError}. `msg' will be
set as the exception's message string. `name' and `path', both of which can
be @code{NULL}, will be set as the @ref{653,,ImportError}'s respective @code{name}
and @code{path} attributes.


在 3.3 版被加入.

@end deffn

@geindex PyErr_SetImportErrorSubclass (C function)
@anchor{c-api/exceptions c PyErr_SetImportErrorSubclass}@anchor{f0d}
@deffn {C 函式} @ref{5d7,,PyObject} *PyErr_SetImportErrorSubclass (PyObject *exception, PyObject *msg, PyObject *name, PyObject *path)
`回傳值：總是為 NULL。'` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.6 版本開始.'
Much like @ref{f34,,PyErr_SetImportError()} but this function allows for
specifying a subclass of @ref{653,,ImportError} to raise.


在 3.6 版被加入.

@end deffn

@geindex PyErr_SyntaxLocationObject (C function)
@anchor{c-api/exceptions c PyErr_SyntaxLocationObject}@anchor{4fe5}
@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{18e,,SyntaxError}, then it sets additional
attributes, which make the exception printing subsystem think the exception
is a @ref{18e,,SyntaxError}.


在 3.4 版被加入.

@end deffn

@geindex PyErr_SyntaxLocationEx (C function)
@anchor{c-api/exceptions c PyErr_SyntaxLocationEx}@anchor{4e65}
@deffn {C 函式} void PyErr_SyntaxLocationEx (const char *filename, int lineno, int col_offset)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.7 版本開始.'
Like @ref{4fe5,,PyErr_SyntaxLocationObject()}, but `filename' is a byte string
decoded from the @ref{756,,filesystem encoding and error handler}.


在 3.2 版被加入.

@end deffn

@geindex PyErr_SyntaxLocation (C function)
@anchor{c-api/exceptions c PyErr_SyntaxLocation}@anchor{4e64}
@deffn {C 函式} void PyErr_SyntaxLocation (const char *filename, int lineno)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Like @ref{4e65,,PyErr_SyntaxLocationEx()}, but the `col_offset' parameter is
omitted.
@end deffn

@geindex PyErr_BadInternalCall (C function)
@anchor{c-api/exceptions c PyErr_BadInternalCall}@anchor{4e59}
@deffn {C 函式} void PyErr_BadInternalCall ()
` 為 @ref{76e,,穩定 ABI 的一部分}.'
This is a shorthand for @code{PyErr_SetString(PyExc_SystemError, message)},
where `message' indicates that an internal operation (e.g. a Python/C API
function) was invoked with an illegal argument.  It is mostly for internal
use.
@end deffn

@node Issuing warnings,Querying the error indicator,Raising exceptions,例外處理
@anchor{c-api/exceptions issuing-warnings}@anchor{4fe6}
@subsection Issuing warnings


Use these functions to issue warnings from C code.  They mirror similar
functions exported by the Python @ref{118,,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{789,,Py_DECREF()} owned references and return
an error value).

@geindex PyErr_WarnEx (C function)
@anchor{c-api/exceptions c PyErr_WarnEx}@anchor{1641}
@deffn {C 函式} int PyErr_WarnEx (PyObject *category, const char *message, Py_ssize_t stack_level)
` 為 @ref{76e,,穩定 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{1641,,PyErr_WarnEx()}, 2 is  the function above that,
and so forth.

Warning categories must be subclasses of @ref{4ea9,,PyExc_Warning};
@ref{4ea9,,PyExc_Warning} is a subclass of @ref{4e7d,,PyExc_Exception};
the default warning category is @ref{4e99,,PyExc_RuntimeWarning}. The standard
Python warning categories are available as global variables whose names are
enumerated at @ref{4fe7,,警告型別}.

For information about warning control, see the documentation for the
@ref{118,,warnings} module and the @ref{abc,,-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{4fe8}
@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{ef8,,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.


在 3.4 版被加入.

@end deffn

@geindex PyErr_WarnExplicit (C function)
@anchor{c-api/exceptions c PyErr_WarnExplicit}@anchor{19df}
@deffn {C 函式} int PyErr_WarnExplicit (PyObject *category, const char *message, const char *filename, int lineno, const char *module, PyObject *registry)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Similar to @ref{4fe8,,PyErr_WarnExplicitObject()} except that `message' and
`module' are UTF-8 encoded strings, and `filename' is decoded from the
@ref{756,,filesystem encoding and error handler}.
@end deffn

@geindex PyErr_WarnFormat (C function)
@anchor{c-api/exceptions c PyErr_WarnFormat}@anchor{4e66}
@deffn {C 函式} int PyErr_WarnFormat (PyObject *category, Py_ssize_t stack_level, const char *format, ...)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Function similar to @ref{1641,,PyErr_WarnEx()}, but use
@ref{623,,PyUnicode_FromFormat()} to format the warning message.  `format' is
an ASCII-encoded string.


在 3.2 版被加入.

@end deffn

@geindex PyErr_ResourceWarning (C function)
@anchor{c-api/exceptions c PyErr_ResourceWarning}@anchor{f0e}
@deffn {C 函式} int PyErr_ResourceWarning (PyObject *source, Py_ssize_t stack_level, const char *format, ...)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.6 版本開始.'
Function similar to @ref{4e66,,PyErr_WarnFormat()}, but `category' is
@ref{547,,ResourceWarning} and it passes `source' to @code{warnings.WarningMessage}.


在 3.6 版被加入.

@end deffn

@node Querying the error indicator,訊號處理,Issuing warnings,例外處理
@anchor{c-api/exceptions querying-the-error-indicator}@anchor{4fe9}
@subsection Querying the error indicator


@geindex PyErr_Occurred (C function)
@anchor{c-api/exceptions c PyErr_Occurred}@anchor{1ba7}
@deffn {C 函式} @ref{5d7,,PyObject} *PyErr_Occurred ()
`回傳值：借用參照。'` 為 @ref{76e,,穩定 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{429,,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{789,,Py_DECREF()}
it.

The caller must have an @ref{4d99,,attached thread state}.

@cartouche
@quotation 備註 
Do not compare the return value to a specific exception; use
@ref{4dff,,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{4dff}
@deffn {C 函式} int PyErr_ExceptionMatches (PyObject *exc)
` 為 @ref{76e,,穩定 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{4e5a}
@deffn {C 函式} int PyErr_GivenExceptionMatches (PyObject *given, PyObject *exc)
` 為 @ref{76e,,穩定 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{427}
@deffn {C 函式} @ref{5d7,,PyObject} *PyErr_GetRaisedException (void)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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.

舉例來說：

@example
@{
   PyObject *exc = PyErr_GetRaisedException();

   /* ... 可能會產生其他錯誤的程式碼 ... */

   PyErr_SetRaisedException(exc);
@}
@end example


@subsubheading 也參考


@ref{96b,,PyErr_GetHandledException()},
to save the exception currently being handled.



在 3.12 版被加入.

@end deffn

@geindex PyErr_SetRaisedException (C function)
@anchor{c-api/exceptions c PyErr_SetRaisedException}@anchor{42a}
@deffn {C 函式} void PyErr_SetRaisedException (PyObject *exc)
` 為 @ref{76e,,穩定 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


在 3.12 版被加入.

@end deffn

@geindex PyErr_Fetch (C function)
@anchor{c-api/exceptions c PyErr_Fetch}@anchor{426}
@deffn {C 函式} void PyErr_Fetch (PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)
` 為 @ref{76e,,穩定 ABI 的一部分}.'

在 3.12 版之後被棄用: 請改用 @ref{427,,PyErr_GetRaisedException()}。


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.

舉例來說：

@example
@{
   PyObject *type, *value, *traceback;
   PyErr_Fetch(&type, &value, &traceback);

   /* ... 可能會產生其他錯誤的程式碼 ... */

   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{429}
@deffn {C 函式} void PyErr_Restore (PyObject *type, PyObject *value, PyObject *traceback)
` 為 @ref{76e,,穩定 ABI 的一部分}.'

在 3.12 版之後被棄用: 請改用 @ref{42a,,PyErr_SetRaisedException()}。


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{426,,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{428}
@deffn {C 函式} void PyErr_NormalizeException (PyObject **exc, PyObject **val, PyObject **tb)
` 為 @ref{76e,,穩定 ABI 的一部分}.'

在 3.12 版之後被棄用: Use @ref{427,,PyErr_GetRaisedException()} instead,
to avoid any possible de-normalization.


Under certain circumstances, the values returned by @ref{426,,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{14c7,,__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{96b}
@deffn {C 函式} @ref{5d7,,PyObject} *PyErr_GetHandledException (void)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.11 版本開始.'
Retrieve the active exception instance, as would be returned by @ref{894,,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{96c,,PyErr_SetHandledException()} to restore or
clear the exception state.
@end quotation
@end cartouche


在 3.11 版被加入.

@end deffn

@geindex PyErr_SetHandledException (C function)
@anchor{c-api/exceptions c PyErr_SetHandledException}@anchor{96c}
@deffn {C 函式} void PyErr_SetHandledException (PyObject *exc)
` 為 @ref{76e,,穩定 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{96b,,PyErr_GetHandledException()} to get the exception
state.
@end quotation
@end cartouche


在 3.11 版被加入.

@end deffn

@geindex PyErr_GetExcInfo (C function)
@anchor{c-api/exceptions c PyErr_GetExcInfo}@anchor{96e}
@deffn {C 函式} void PyErr_GetExcInfo (PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.7 版本開始.'
Retrieve the old-style representation of the exception info, as known from
@ref{893,,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{96b,,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{96d,,PyErr_SetExcInfo()} to restore or clear the
exception state.
@end quotation
@end cartouche


在 3.3 版被加入.

@end deffn

@geindex PyErr_SetExcInfo (C function)
@anchor{c-api/exceptions c PyErr_SetExcInfo}@anchor{96d}
@deffn {C 函式} void PyErr_SetExcInfo (PyObject *type, PyObject *value, PyObject *traceback)
` 為 @ref{76e,,穩定 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{96c,,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{96e,,PyErr_GetExcInfo()} to read the exception
state.
@end quotation
@end cartouche


在 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 訊號處理,例外類別<2>,Querying the error indicator,例外處理
@anchor{c-api/exceptions signal-handling}@anchor{4fea}
@subsection 訊號處理


@geindex PyErr_CheckSignals (C function)
@anchor{c-api/exceptions c PyErr_CheckSignals}@anchor{68c}
@deffn {C 函式} int PyErr_CheckSignals ()
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@geindex module（模組）;signal（訊號）
@geindex SIGINT（C 巨集）
@geindex KeyboardInterrupt（內建例外）

This function interacts with Python's signal handling.

If the function is called from the main thread and under the main Python
interpreter, it checks whether a signal has been sent to the processes
and if so, invokes the corresponding signal handler.  If the @ref{cb,,signal}
module is supported, this can invoke a signal handler written in Python.

The function attempts to handle all pending signals, and then returns @code{0}.
However, if a Python signal handler raises an exception, the error
indicator is set and the function returns @code{-1} immediately (such that
other pending signals may not have been handled yet: they will be on the
next @ref{68c,,PyErr_CheckSignals()} invocation).

If the function is called from a non-main thread, or under a non-main
Python interpreter, it does nothing and returns @code{0}.

This function can be called by long-running C code that wants to
be interruptible by user requests (such as by pressing Ctrl-C).

@cartouche
@quotation 備註 
The default Python signal handler for @code{SIGINT} raises the
@ref{bbc,,KeyboardInterrupt} exception.
@end quotation
@end cartouche
@end deffn

@geindex PyErr_SetInterrupt (C function)
@anchor{c-api/exceptions c PyErr_SetInterrupt}@anchor{4e62}
@deffn {C 函式} void PyErr_SetInterrupt ()
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@geindex module（模組）;signal（訊號）
@geindex SIGINT（C 巨集）
@geindex KeyboardInterrupt（內建例外）

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{4d99,,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{a95}
@deffn {C 函式} int PyErr_SetInterruptEx (int signum)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.10 版本開始.'
@geindex module（模組）;signal（訊號）
@geindex KeyboardInterrupt（內建例外）

Simulate the effect of a signal arriving. The next time
@ref{68c,,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{1ad7,,signal.SIG_DFL} or @ref{1ad6,,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{4d99,,attached thread state} and from a C signal handler.
@end quotation
@end cartouche


在 3.10 版被加入.

@end deffn

@geindex PySignal_SetWakeupFd (C function)
@anchor{c-api/exceptions c PySignal_SetWakeupFd}@anchor{15d2}
@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{d5f,,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 例外類別<2>,例外物件,訊號處理,例外處理
@anchor{c-api/exceptions exception-classes}@anchor{4feb}
@subsection 例外類別


@geindex PyErr_NewException (C function)
@anchor{c-api/exceptions c PyErr_NewException}@anchor{146a}
@deffn {C 函式} @ref{5d7,,PyObject} *PyErr_NewException (const char *name, PyObject *base, PyObject *dict)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{bc4,,Exception} (accessible in C as
@ref{4e7d,,PyExc_Exception}).

The @ref{60f,,__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{1469}
@deffn {C 函式} @ref{5d7,,PyObject} *PyErr_NewExceptionWithDoc (const char *name, const char *doc, PyObject *base, PyObject *dict)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Same as @ref{146a,,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.


在 3.2 版被加入.

@end deffn

@geindex PyExceptionClass_Check (C function)
@anchor{c-api/exceptions c PyExceptionClass_Check}@anchor{4fec}
@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{c52}
@deffn {C 函式} const char *PyExceptionClass_Name (PyObject *ob)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.8 版本開始.'
回傳例外類別 `ob' 的 @ref{1ba8,,tp_name}。
@end deffn

@node 例外物件,Unicode 例外物件,例外類別<2>,例外處理
@anchor{c-api/exceptions exception-objects}@anchor{4fed}
@subsection 例外物件


@geindex PyException_GetTraceback (C function)
@anchor{c-api/exceptions c PyException_GetTraceback}@anchor{4ead}
@deffn {C 函式} @ref{5d7,,PyObject} *PyException_GetTraceback (PyObject *ex)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return the traceback associated with the exception as a new reference, as
accessible from Python through the @ref{14c7,,__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{1c97}
@deffn {C 函式} int PyException_SetTraceback (PyObject *ex, PyObject *tb)
` 為 @ref{76e,,穩定 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{4eac}
@deffn {C 函式} @ref{5d7,,PyObject} *PyException_GetContext (PyObject *ex)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{14c8,,__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{4eaf}
@deffn {C 函式} void PyException_SetContext (PyObject *ex, PyObject *ctx)
` 為 @ref{76e,,穩定 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{4eab}
@deffn {C 函式} @ref{5d7,,PyObject} *PyException_GetCause (PyObject *ex)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{14c9,,__cause__} attribute.
@end deffn

@geindex PyException_SetCause (C function)
@anchor{c-api/exceptions c PyException_SetCause}@anchor{4eae}
@deffn {C 函式} void PyException_SetCause (PyObject *ex, PyObject *cause)
` 為 @ref{76e,,穩定 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{23bc,,__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{784}
@deffn {C 函式} @ref{5d7,,PyObject} *PyException_GetArgs (PyObject *ex)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.12 版本開始.'
回傳例外 `ex' 的 @ref{786,,args}。
@end deffn

@geindex PyException_SetArgs (C function)
@anchor{c-api/exceptions c PyException_SetArgs}@anchor{785}
@deffn {C 函式} void PyException_SetArgs (PyObject *ex, PyObject *args)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.12 版本開始.'
設定例外 `ex' 的 @ref{786,,args} 為 `args'。
@end deffn

@geindex PyUnstable_Exc_PrepReraiseStar (C function)
@anchor{c-api/exceptions c PyUnstable_Exc_PrepReraiseStar}@anchor{4fee}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnstable_Exc_PrepReraiseStar (PyObject *orig, PyObject *excs)

@cartouche
@quotation 這是 不穩定 API，它可能在小版本發布中沒有任何警告地被變更。 `這是 @ref{762,,不穩定 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{4cd,,ExceptionGroup} that needs to be reraised in the end, or
@code{None} if there is nothing to reraise.


在 3.12 版被加入.

@end deffn

@node Unicode 例外物件,遞迴控制,例外物件,例外處理
@anchor{c-api/exceptions unicode-exception-objects}@anchor{4fef}@anchor{c-api/exceptions unicodeexceptions}@anchor{45f}
@subsection Unicode 例外物件


The following functions are used to create and modify Unicode exceptions from C.

@geindex PyUnicodeDecodeError_Create (C function)
@anchor{c-api/exceptions c PyUnicodeDecodeError_Create}@anchor{4f4b}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicodeDecodeError_Create (const char *encoding, const char *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Create a @ref{bff,,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{4f4c}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicodeDecodeError_GetEncoding (PyObject *exc)
@anchor{c-api/exceptions c PyUnicodeEncodeError_GetEncoding}@anchor{4f54}
@deffnx {C 函式} @ref{5d7,,PyObject} *PyUnicodeEncodeError_GetEncoding (PyObject *exc)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{4f4e}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicodeDecodeError_GetObject (PyObject *exc)
@anchor{c-api/exceptions c PyUnicodeEncodeError_GetObject}@anchor{4f55}
@deffnx {C 函式} @ref{5d7,,PyObject} *PyUnicodeEncodeError_GetObject (PyObject *exc)
@anchor{c-api/exceptions c PyUnicodeTranslateError_GetObject}@anchor{4f5c}
@deffnx {C 函式} @ref{5d7,,PyObject} *PyUnicodeTranslateError_GetObject (PyObject *exc)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{4f50}
@deffn {C 函式} int PyUnicodeDecodeError_GetStart (PyObject *exc, Py_ssize_t *start)
@anchor{c-api/exceptions c PyUnicodeEncodeError_GetStart}@anchor{1869}
@deffnx {C 函式} int PyUnicodeEncodeError_GetStart (PyObject *exc, Py_ssize_t *start)
@anchor{c-api/exceptions c PyUnicodeTranslateError_GetStart}@anchor{4f5e}
@deffnx {C 函式} int PyUnicodeTranslateError_GetStart (PyObject *exc, Py_ssize_t *start)
` 為 @ref{76e,,穩定 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{1867,,UnicodeError.object} is an empty sequence, the resulting
`start' is @code{0}. Otherwise, it is clipped to @code{[0, len(object) - 1]}.


@subsubheading 也參考


@ref{1834,,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{4f53}
@deffn {C 函式} int PyUnicodeDecodeError_SetStart (PyObject *exc, Py_ssize_t start)
@anchor{c-api/exceptions c PyUnicodeEncodeError_SetStart}@anchor{4f59}
@deffnx {C 函式} int PyUnicodeEncodeError_SetStart (PyObject *exc, Py_ssize_t start)
@anchor{c-api/exceptions c PyUnicodeTranslateError_SetStart}@anchor{4f61}
@deffnx {C 函式} int PyUnicodeTranslateError_SetStart (PyObject *exc, Py_ssize_t start)
` 為 @ref{76e,,穩定 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{4f4d}
@deffn {C 函式} int PyUnicodeDecodeError_GetEnd (PyObject *exc, Py_ssize_t *end)
@anchor{c-api/exceptions c PyUnicodeEncodeError_GetEnd}@anchor{1866}
@deffnx {C 函式} int PyUnicodeEncodeError_GetEnd (PyObject *exc, Py_ssize_t *end)
@anchor{c-api/exceptions c PyUnicodeTranslateError_GetEnd}@anchor{4f5b}
@deffnx {C 函式} int PyUnicodeTranslateError_GetEnd (PyObject *exc, Py_ssize_t *end)
` 為 @ref{76e,,穩定 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{1867,,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{4f51}
@deffn {C 函式} int PyUnicodeDecodeError_SetEnd (PyObject *exc, Py_ssize_t end)
@anchor{c-api/exceptions c PyUnicodeEncodeError_SetEnd}@anchor{4f57}
@deffnx {C 函式} int PyUnicodeEncodeError_SetEnd (PyObject *exc, Py_ssize_t end)
@anchor{c-api/exceptions c PyUnicodeTranslateError_SetEnd}@anchor{4f5f}
@deffnx {C 函式} int PyUnicodeTranslateError_SetEnd (PyObject *exc, Py_ssize_t end)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Set the `end' attribute of the given exception object to `end'.  Return @code{0}
on success, @code{-1} on failure.


@subsubheading 也參考


@ref{1835,,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{4f4f}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicodeDecodeError_GetReason (PyObject *exc)
@anchor{c-api/exceptions c PyUnicodeEncodeError_GetReason}@anchor{4f56}
@deffnx {C 函式} @ref{5d7,,PyObject} *PyUnicodeEncodeError_GetReason (PyObject *exc)
@anchor{c-api/exceptions c PyUnicodeTranslateError_GetReason}@anchor{4f5d}
@deffnx {C 函式} @ref{5d7,,PyObject} *PyUnicodeTranslateError_GetReason (PyObject *exc)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
回傳給定例外物件的 `reason' 屬性。
@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{4f52}
@deffn {C 函式} int PyUnicodeDecodeError_SetReason (PyObject *exc, const char *reason)
@anchor{c-api/exceptions c PyUnicodeEncodeError_SetReason}@anchor{4f58}
@deffnx {C 函式} int PyUnicodeEncodeError_SetReason (PyObject *exc, const char *reason)
@anchor{c-api/exceptions c PyUnicodeTranslateError_SetReason}@anchor{4f60}
@deffnx {C 函式} int PyUnicodeTranslateError_SetReason (PyObject *exc, const char *reason)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Set the `reason' attribute of the given exception object to `reason'.  Return
@code{0} on success, @code{-1} on failure.
@end deffn

@node 遞迴控制,例外和警告型別,Unicode 例外物件,例外處理
@anchor{c-api/exceptions recursion}@anchor{4ff0}@anchor{c-api/exceptions recursion-control}@anchor{4ff1}
@subsection 遞迴控制


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{79c,,call protocol} takes care of recursion handling.

@geindex Py_EnterRecursiveCall (C function)
@anchor{c-api/exceptions c Py_EnterRecursiveCall}@anchor{3d0}
@deffn {C 函式} int Py_EnterRecursiveCall (const char *where)
` 為 @ref{76e,,穩定 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{f63,,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{f63,,RecursionError} message caused by the recursion
depth limit.


在 3.9 版的變更: This function is now also available in the @ref{62f,,limited API}.

@end deffn

@geindex Py_LeaveRecursiveCall (C function)
@anchor{c-api/exceptions c Py_LeaveRecursiveCall}@anchor{b62}
@deffn {C 函式} void Py_LeaveRecursiveCall (void)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.9 版本開始.'
Ends a @ref{3d0,,Py_EnterRecursiveCall()}.  Must be called once for each
`successful' invocation of @ref{3d0,,Py_EnterRecursiveCall()}.


在 3.9 版的變更: This function is now also available in the @ref{62f,,limited API}.

@end deffn

Properly implementing @ref{4dac,,tp_repr} for container types requires
special recursion handling.  In addition to protecting the stack,
@ref{4dac,,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{13f4,,reprlib.recursive_repr()}.

@geindex Py_ReprEnter (C function)
@anchor{c-api/exceptions c Py_ReprEnter}@anchor{4f98}
@deffn {C 函式} int Py_ReprEnter (PyObject *object)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Called at the beginning of the @ref{4dac,,tp_repr} implementation to
detect cycles.

If the object has already been processed, the function returns a
positive integer.  In that case the @ref{4dac,,tp_repr} implementation
should return a string object indicating a cycle.  As examples,
@ref{183,,dict} objects return @code{@{...@}} and @ref{24d,,list} objects
return @code{[...]}.

The function will return a negative integer if the recursion limit
is reached.  In that case the @ref{4dac,,tp_repr} implementation should
typically return @code{NULL}.

Otherwise, the function returns zero and the @ref{4dac,,tp_repr}
implementation can continue normally.
@end deffn

@geindex Py_ReprLeave (C function)
@anchor{c-api/exceptions c Py_ReprLeave}@anchor{4f99}
@deffn {C 函式} void Py_ReprLeave (PyObject *object)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Ends a @ref{4f98,,Py_ReprEnter()}.  Must be called once for each
invocation of @ref{4f98,,Py_ReprEnter()} that returns zero.
@end deffn

@node 例外和警告型別,,遞迴控制,例外處理
@anchor{c-api/exceptions exception-and-warning-types}@anchor{4ff2}@anchor{c-api/exceptions standardexceptions}@anchor{4ff3}
@subsection 例外和警告型別


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{5d7,,PyObject}*; they are all class objects.

For completeness, here are all the variables:

@menu
* 例外型別:: 
* OSError 別名:: 
* 警告型別:: 

@end menu

@node 例外型別,OSError 別名,,例外和警告型別
@anchor{c-api/exceptions exception-types}@anchor{4ff4}
@subsubsection 例外型別



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

C 名稱

@tab

Python 名稱

@item

@geindex PyExc_BaseException (C var)
@anchor{c-api/exceptions c PyExc_BaseException}@anchor{4e6e}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_BaseException
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@tab

@ref{7d0,,BaseException}

@item

@geindex PyExc_BaseExceptionGroup (C var)
@anchor{c-api/exceptions c PyExc_BaseExceptionGroup}@anchor{4e6f}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_BaseExceptionGroup
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.11 版本開始.'
@end deffn

@tab

@ref{560,,BaseExceptionGroup}

@item

@geindex PyExc_Exception (C var)
@anchor{c-api/exceptions c PyExc_Exception}@anchor{4e7d}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_Exception
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@tab

@ref{bc4,,Exception}

@item

@geindex PyExc_ArithmeticError (C var)
@anchor{c-api/exceptions c PyExc_ArithmeticError}@anchor{4e6b}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_ArithmeticError
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@tab

@ref{258f,,ArithmeticError}

@item

@geindex PyExc_AssertionError (C var)
@anchor{c-api/exceptions c PyExc_AssertionError}@anchor{4e6c}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_AssertionError
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@tab

@ref{8b0,,AssertionError}

@item

@geindex PyExc_AttributeError (C var)
@anchor{c-api/exceptions c PyExc_AttributeError}@anchor{4e6d}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_AttributeError
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@tab

@ref{5e8,,AttributeError}

@item

@geindex PyExc_BlockingIOError (C var)
@anchor{c-api/exceptions c PyExc_BlockingIOError}@anchor{4e70}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_BlockingIOError
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.7 版本開始.'
@end deffn

@tab

@ref{235,,BlockingIOError}

@item

@geindex PyExc_BrokenPipeError (C var)
@anchor{c-api/exceptions c PyExc_BrokenPipeError}@anchor{4e71}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_BrokenPipeError
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.7 版本開始.'
@end deffn

@tab

@ref{1257,,BrokenPipeError}

@item

@geindex PyExc_BufferError (C var)
@anchor{c-api/exceptions c PyExc_BufferError}@anchor{4e72}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_BufferError
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@tab

@ref{1adb,,BufferError}

@item

@geindex PyExc_ChildProcessError (C var)
@anchor{c-api/exceptions c PyExc_ChildProcessError}@anchor{4e74}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_ChildProcessError
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.7 版本開始.'
@end deffn

@tab

@ref{1253,,ChildProcessError}

@item

@geindex PyExc_ConnectionAbortedError (C var)
@anchor{c-api/exceptions c PyExc_ConnectionAbortedError}@anchor{4e75}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_ConnectionAbortedError
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.7 版本開始.'
@end deffn

@tab

@ref{1258,,ConnectionAbortedError}

@item

@geindex PyExc_ConnectionError (C var)
@anchor{c-api/exceptions c PyExc_ConnectionError}@anchor{4e76}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_ConnectionError
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.7 版本開始.'
@end deffn

@tab

@ref{1006,,ConnectionError}

@item

@geindex PyExc_ConnectionRefusedError (C var)
@anchor{c-api/exceptions c PyExc_ConnectionRefusedError}@anchor{4e77}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_ConnectionRefusedError
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.7 版本開始.'
@end deffn

@tab

@ref{1259,,ConnectionRefusedError}

@item

@geindex PyExc_ConnectionResetError (C var)
@anchor{c-api/exceptions c PyExc_ConnectionResetError}@anchor{4e78}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_ConnectionResetError
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.7 版本開始.'
@end deffn

@tab

@ref{125a,,ConnectionResetError}

@item

@geindex PyExc_EOFError (C var)
@anchor{c-api/exceptions c PyExc_EOFError}@anchor{4e7a}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_EOFError
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@tab

@ref{14da,,EOFError}

@item

@geindex PyExc_FileExistsError (C var)
@anchor{c-api/exceptions c PyExc_FileExistsError}@anchor{4e7e}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_FileExistsError
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.7 版本開始.'
@end deffn

@tab

@ref{121b,,FileExistsError}

@item

@geindex PyExc_FileNotFoundError (C var)
@anchor{c-api/exceptions c PyExc_FileNotFoundError}@anchor{4e7f}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_FileNotFoundError
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.7 版本開始.'
@end deffn

@tab

@ref{264,,FileNotFoundError}

@item

@geindex PyExc_FloatingPointError (C var)
@anchor{c-api/exceptions c PyExc_FloatingPointError}@anchor{4e80}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_FloatingPointError
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@tab

@ref{2590,,FloatingPointError}

@item

@geindex PyExc_GeneratorExit (C var)
@anchor{c-api/exceptions c PyExc_GeneratorExit}@anchor{4e82}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_GeneratorExit
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@tab

@ref{15bf,,GeneratorExit}

@item

@geindex PyExc_ImportError (C var)
@anchor{c-api/exceptions c PyExc_ImportError}@anchor{4e84}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_ImportError
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@tab

@ref{653,,ImportError}

@item

@geindex PyExc_IndentationError (C var)
@anchor{c-api/exceptions c PyExc_IndentationError}@anchor{4e86}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_IndentationError
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@tab

@ref{9a4,,IndentationError}

@item

@geindex PyExc_IndexError (C var)
@anchor{c-api/exceptions c PyExc_IndexError}@anchor{4e87}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_IndexError
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@tab

@ref{1729,,IndexError}

@item

@geindex PyExc_InterruptedError (C var)
@anchor{c-api/exceptions c PyExc_InterruptedError}@anchor{4e88}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_InterruptedError
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.7 版本開始.'
@end deffn

@tab

@ref{f83,,InterruptedError}

@item

@geindex PyExc_IsADirectoryError (C var)
@anchor{c-api/exceptions c PyExc_IsADirectoryError}@anchor{4e89}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_IsADirectoryError
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.7 版本開始.'
@end deffn

@tab

@ref{1254,,IsADirectoryError}

@item

@geindex PyExc_KeyError (C var)
@anchor{c-api/exceptions c PyExc_KeyError}@anchor{4e8a}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_KeyError
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@tab

@ref{5df,,KeyError}

@item

@geindex PyExc_KeyboardInterrupt (C var)
@anchor{c-api/exceptions c PyExc_KeyboardInterrupt}@anchor{4e8b}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_KeyboardInterrupt
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@tab

@ref{bbc,,KeyboardInterrupt}

@item

@geindex PyExc_LookupError (C var)
@anchor{c-api/exceptions c PyExc_LookupError}@anchor{4e8c}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_LookupError
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@tab

@ref{2500,,LookupError}

@item

@geindex PyExc_MemoryError (C var)
@anchor{c-api/exceptions c PyExc_MemoryError}@anchor{4e8d}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_MemoryError
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@tab

@ref{181e,,MemoryError}

@item

@geindex PyExc_ModuleNotFoundError (C var)
@anchor{c-api/exceptions c PyExc_ModuleNotFoundError}@anchor{4e8e}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_ModuleNotFoundError
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.6 版本開始.'
@end deffn

@tab

@ref{d35,,ModuleNotFoundError}

@item

@geindex PyExc_NameError (C var)
@anchor{c-api/exceptions c PyExc_NameError}@anchor{4e8f}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_NameError
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@tab

@ref{450,,NameError}

@item

@geindex PyExc_NotADirectoryError (C var)
@anchor{c-api/exceptions c PyExc_NotADirectoryError}@anchor{4e90}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_NotADirectoryError
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.7 版本開始.'
@end deffn

@tab

@ref{1255,,NotADirectoryError}

@item

@geindex PyExc_NotImplementedError (C var)
@anchor{c-api/exceptions c PyExc_NotImplementedError}@anchor{4e91}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_NotImplementedError
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@tab

@ref{369,,NotImplementedError}

@item

@geindex PyExc_OSError (C var)
@anchor{c-api/exceptions c PyExc_OSError}@anchor{4d63}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_OSError
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@tab

@ref{2c0,,OSError}

@item

@geindex PyExc_OverflowError (C var)
@anchor{c-api/exceptions c PyExc_OverflowError}@anchor{4e92}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_OverflowError
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@tab

@ref{a78,,OverflowError}

@item

@geindex PyExc_PermissionError (C var)
@anchor{c-api/exceptions c PyExc_PermissionError}@anchor{4e94}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_PermissionError
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.7 版本開始.'
@end deffn

@tab

@ref{f39,,PermissionError}

@item

@geindex PyExc_ProcessLookupError (C var)
@anchor{c-api/exceptions c PyExc_ProcessLookupError}@anchor{4e95}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_ProcessLookupError
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.7 版本開始.'
@end deffn

@tab

@ref{1256,,ProcessLookupError}

@item

@geindex PyExc_PythonFinalizationError (C var)
@anchor{c-api/exceptions c PyExc_PythonFinalizationError}@anchor{4ff5}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_PythonFinalizationError
@end deffn

@tab

@ref{473,,PythonFinalizationError}

@item

@geindex PyExc_RecursionError (C var)
@anchor{c-api/exceptions c PyExc_RecursionError}@anchor{10ad}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_RecursionError
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.7 版本開始.'
@end deffn

@tab

@ref{f63,,RecursionError}

@item

@geindex PyExc_ReferenceError (C var)
@anchor{c-api/exceptions c PyExc_ReferenceError}@anchor{4e96}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_ReferenceError
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@tab

@ref{1701,,ReferenceError}

@item

@geindex PyExc_RuntimeError (C var)
@anchor{c-api/exceptions c PyExc_RuntimeError}@anchor{4e98}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_RuntimeError
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@tab

@ref{244,,RuntimeError}

@item

@geindex PyExc_StopAsyncIteration (C var)
@anchor{c-api/exceptions c PyExc_StopAsyncIteration}@anchor{4e9a}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_StopAsyncIteration
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.7 版本開始.'
@end deffn

@tab

@ref{1cd7,,StopAsyncIteration}

@item

@geindex PyExc_StopIteration (C var)
@anchor{c-api/exceptions c PyExc_StopIteration}@anchor{4e9b}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_StopIteration
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@tab

@ref{df0,,StopIteration}

@item

@geindex PyExc_SyntaxError (C var)
@anchor{c-api/exceptions c PyExc_SyntaxError}@anchor{4e9c}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_SyntaxError
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@tab

@ref{18e,,SyntaxError}

@item

@geindex PyExc_SystemError (C var)
@anchor{c-api/exceptions c PyExc_SystemError}@anchor{4e9e}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_SystemError
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@tab

@ref{78e,,SystemError}

@item

@geindex PyExc_SystemExit (C var)
@anchor{c-api/exceptions c PyExc_SystemExit}@anchor{4e9f}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_SystemExit
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@tab

@ref{f37,,SystemExit}

@item

@geindex PyExc_TabError (C var)
@anchor{c-api/exceptions c PyExc_TabError}@anchor{4ea0}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_TabError
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@tab

@ref{75e,,TabError}

@item

@geindex PyExc_TimeoutError (C var)
@anchor{c-api/exceptions c PyExc_TimeoutError}@anchor{4ea1}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_TimeoutError
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.7 版本開始.'
@end deffn

@tab

@ref{a2f,,TimeoutError}

@item

@geindex PyExc_TypeError (C var)
@anchor{c-api/exceptions c PyExc_TypeError}@anchor{4d62}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_TypeError
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@tab

@ref{198,,TypeError}

@item

@geindex PyExc_UnboundLocalError (C var)
@anchor{c-api/exceptions c PyExc_UnboundLocalError}@anchor{4ea2}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_UnboundLocalError
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@tab

@ref{172a,,UnboundLocalError}

@item

@geindex PyExc_UnicodeDecodeError (C var)
@anchor{c-api/exceptions c PyExc_UnicodeDecodeError}@anchor{4ea3}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_UnicodeDecodeError
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@tab

@ref{bff,,UnicodeDecodeError}

@item

@geindex PyExc_UnicodeEncodeError (C var)
@anchor{c-api/exceptions c PyExc_UnicodeEncodeError}@anchor{4ea4}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_UnicodeEncodeError
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@tab

@ref{880,,UnicodeEncodeError}

@item

@geindex PyExc_UnicodeError (C var)
@anchor{c-api/exceptions c PyExc_UnicodeError}@anchor{4ea5}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_UnicodeError
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@tab

@ref{460,,UnicodeError}

@item

@geindex PyExc_UnicodeTranslateError (C var)
@anchor{c-api/exceptions c PyExc_UnicodeTranslateError}@anchor{4ea6}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_UnicodeTranslateError
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@tab

@ref{1868,,UnicodeTranslateError}

@item

@geindex PyExc_ValueError (C var)
@anchor{c-api/exceptions c PyExc_ValueError}@anchor{4d64}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_ValueError
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@tab

@ref{2eb,,ValueError}

@item

@geindex PyExc_ZeroDivisionError (C var)
@anchor{c-api/exceptions c PyExc_ZeroDivisionError}@anchor{4d5f}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_ZeroDivisionError
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@tab

@ref{b36,,ZeroDivisionError}

@end multitable



在 3.3 版被加入: @ref{4e70,,PyExc_BlockingIOError}, @ref{4e71,,PyExc_BrokenPipeError}, @ref{4e74,,PyExc_ChildProcessError}, @ref{4e76,,PyExc_ConnectionError}, @ref{4e75,,PyExc_ConnectionAbortedError}, @ref{4e77,,PyExc_ConnectionRefusedError}, @ref{4e78,,PyExc_ConnectionResetError}, @ref{4e7e,,PyExc_FileExistsError}, @ref{4e7f,,PyExc_FileNotFoundError}, @ref{4e88,,PyExc_InterruptedError}, @ref{4e89,,PyExc_IsADirectoryError}, @ref{4e90,,PyExc_NotADirectoryError}, @ref{4e94,,PyExc_PermissionError}, @ref{4e95,,PyExc_ProcessLookupError} 和 @ref{4ea1,,PyExc_TimeoutError} 是在 
@geindex Python Enhancement Proposals; PEP 3151
PEP 3151@footnote{https://peps.python.org/pep-3151/} 被引入。



在 3.5 版被加入: @ref{4e9a,,PyExc_StopAsyncIteration} 和 @ref{10ad,,PyExc_RecursionError}。



在 3.6 版被加入: @ref{4e8e,,PyExc_ModuleNotFoundError}。



在 3.11 版被加入: @ref{4e6f,,PyExc_BaseExceptionGroup}


@node OSError 別名,警告型別,例外型別,例外和警告型別
@anchor{c-api/exceptions oserror-aliases}@anchor{4ff6}
@subsubsection OSError 別名


The following are a compatibility aliases to @ref{4d63,,PyExc_OSError}.


在 3.3 版的變更: These aliases used to be separate exception types.



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

C 名稱

@tab

Python 名稱

@tab

註解

@item

@geindex PyExc_EnvironmentError (C var)
@anchor{c-api/exceptions c PyExc_EnvironmentError}@anchor{4e7c}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_EnvironmentError
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@tab

@ref{2c0,,OSError}

@tab

@item

@geindex PyExc_IOError (C var)
@anchor{c-api/exceptions c PyExc_IOError}@anchor{4e83}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_IOError
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@tab

@ref{2c0,,OSError}

@tab

@item

@geindex PyExc_WindowsError (C var)
@anchor{c-api/exceptions c PyExc_WindowsError}@anchor{4eaa}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_WindowsError
` 為 @ref{76e,,穩定 ABI 的一部分} on Windows 自 3.7 版本開始.'
@end deffn

@tab

@ref{2c0,,OSError}

@tab

@ref{4ff7,,[win]}

@end multitable


註解：

@anchor{c-api/exceptions win}@anchor{4ff7}@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 警告型別,,OSError 別名,例外和警告型別
@anchor{c-api/exceptions standardwarningcategories}@anchor{4fe7}@anchor{c-api/exceptions warning-types}@anchor{4ff8}
@subsubsection 警告型別



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

C 名稱

@tab

Python 名稱

@item

@geindex PyExc_Warning (C var)
@anchor{c-api/exceptions c PyExc_Warning}@anchor{4ea9}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_Warning
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@tab

@ref{25bd,,Warning}

@item

@geindex PyExc_BytesWarning (C var)
@anchor{c-api/exceptions c PyExc_BytesWarning}@anchor{4e73}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_BytesWarning
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@tab

@ref{e17,,BytesWarning}

@item

@geindex PyExc_DeprecationWarning (C var)
@anchor{c-api/exceptions c PyExc_DeprecationWarning}@anchor{4e79}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_DeprecationWarning
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@tab

@ref{1a3,,DeprecationWarning}

@item

@geindex PyExc_EncodingWarning (C var)
@anchor{c-api/exceptions c PyExc_EncodingWarning}@anchor{4e7b}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_EncodingWarning
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.10 版本開始.'
@end deffn

@tab

@ref{1ff5,,EncodingWarning}

@item

@geindex PyExc_FutureWarning (C var)
@anchor{c-api/exceptions c PyExc_FutureWarning}@anchor{4e81}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_FutureWarning
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@tab

@ref{651,,FutureWarning}

@item

@geindex PyExc_ImportWarning (C var)
@anchor{c-api/exceptions c PyExc_ImportWarning}@anchor{4e85}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_ImportWarning
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@tab

@ref{717,,ImportWarning}

@item

@geindex PyExc_PendingDeprecationWarning (C var)
@anchor{c-api/exceptions c PyExc_PendingDeprecationWarning}@anchor{4e93}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_PendingDeprecationWarning
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@tab

@ref{abd,,PendingDeprecationWarning}

@item

@geindex PyExc_ResourceWarning (C var)
@anchor{c-api/exceptions c PyExc_ResourceWarning}@anchor{4e97}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_ResourceWarning
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.7 版本開始.'
@end deffn

@tab

@ref{547,,ResourceWarning}

@item

@geindex PyExc_RuntimeWarning (C var)
@anchor{c-api/exceptions c PyExc_RuntimeWarning}@anchor{4e99}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_RuntimeWarning
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@tab

@ref{4d2,,RuntimeWarning}

@item

@geindex PyExc_SyntaxWarning (C var)
@anchor{c-api/exceptions c PyExc_SyntaxWarning}@anchor{4e9d}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_SyntaxWarning
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@tab

@ref{1ae,,SyntaxWarning}

@item

@geindex PyExc_UnicodeWarning (C var)
@anchor{c-api/exceptions c PyExc_UnicodeWarning}@anchor{4ea7}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_UnicodeWarning
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@tab

@ref{161b,,UnicodeWarning}

@item

@geindex PyExc_UserWarning (C var)
@anchor{c-api/exceptions c PyExc_UserWarning}@anchor{4ea8}
@deffn {C 變數} @ref{5d7,,PyObject} *PyExc_UserWarning
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@tab

@ref{25be,,UserWarning}

@end multitable



在 3.2 版被加入: @ref{4e97,,PyExc_ResourceWarning}。



在 3.10 版被加入: @ref{4e7b,,PyExc_EncodingWarning}。


@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,工具,例外處理,Python/C API 參考手冊
@anchor{c-api/extension-modules doc}@anchor{4ff9}@anchor{c-api/extension-modules defining-extension-modules}@anchor{4ffa}@anchor{c-api/extension-modules extension-modules}@anchor{4dc4}@anchor{c-api/extension-modules translation-repo}@anchor{4ffb}
@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 @ref{4ffc,,initialization function}.

To be importable by default (that is, by
@ref{ea9,,importlib.machinery.ExtensionFileLoader}),
the shared library must be available on @ref{3e2,,sys.path},
and must be named after the module name plus an extension listed in
@ref{732,,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

Normally, the initialization function returns a module definition initialized
using @ref{4d6b,,PyModuleDef_Init()}.
This allows splitting the creation process into several phases:


@itemize -

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

@item 
By default, Python itself creates the module object -- that is, it does
the equivalent of @ref{799,,object.__new__()} for classes.
It also sets initial attributes like @ref{322,,__package__} and
@ref{33a,,__loader__}.

@item 
Afterwards, the module object is initialized using extension-specific
code -- the equivalent of @ref{8b7,,__init__()} on classes.
@end itemize

This is called `multi-phase initialization' to distinguish it from the legacy
(but still supported) `single-phase initialization' scheme,
where the initialization function returns a fully constructed module.
See the @ref{4ffd,,single-phase-initialization section below}
for details.


在 3.5 版的變更: Added support for multi-phase initialization (
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).


@menu
* Multiple module instances:: 
* Initialization function:: 
* Multi-phase initialization:: 
* Legacy single-phase initialization:: 

@end menu

@node Multiple module instances,Initialization function,,Defining extension modules
@anchor{c-api/extension-modules multiple-module-instances}@anchor{4ffe}
@subsection Multiple module instances


By default, extension modules are not singletons.
For example, if the @ref{17c0,,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{163,,sub-interpreters}
or after Python runtime reinitialization
(@ref{45d,,Py_Finalize()} and @ref{45e,,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{166,,隔離擴充模組} for more details and a practical guide.

A simpler way to avoid these issues is
@ref{4fff,,raising an error on repeated initialization}.

All modules are expected to support
@ref{163,,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{5000,,Py_mod_multiple_interpreters} slot.

@node Initialization function,Multi-phase initialization,Multiple module instances,Defining extension modules
@anchor{c-api/extension-modules extension-export-hook}@anchor{4ffc}@anchor{c-api/extension-modules initialization-function}@anchor{5001}
@subsection Initialization function


The initialization function defined by an extension module has the
following signature:

@geindex PyInit_modulename (C function)
@anchor{c-api/extension-modules c PyInit_modulename}@anchor{5002}
@deffn {C 函式} @ref{5d7,,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 modules with ASCII-only names, the function must instead be named
@code{PyInit_@var{<name>}}, with @code{<name>} replaced by the name of the module.
When using @ref{5003,,Multi-phase initialization}, non-ASCII module names
are allowed. In this case, the initialization function name is
@code{PyInitU_@var{<name>}}, with @code{<name>} encoded using Python's
`punycode' encoding with hyphens replaced by underscores. In Python:

@example
def initfunc_name(name):
    try:
        suffix = b'_' + name.encode('ascii')
    except UnicodeEncodeError:
        suffix = b'U_' + name.encode('punycode').replace(b'-', b'_')
    return b'PyInit' + suffix
@end example

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{16c7}
@deffn {C 巨集} PyMODINIT_FUNC

Declare an extension module initialization function.
This macro:


@itemize *

@item 
specifies the @ref{5d7,,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

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

It is possible to export multiple modules from a single shared library by
defining multiple initialization functions. However, importing them requires
using symbolic links or a custom importer, because by default only the
function corresponding to the filename is found.
See the Multiple modules in one library@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.

The initialization function is typically the only non-@code{static}
item defined in the module's C source.

@node Multi-phase initialization,Legacy single-phase initialization,Initialization function,Defining extension modules
@anchor{c-api/extension-modules id1}@anchor{5004}@anchor{c-api/extension-modules multi-phase-initialization}@anchor{5003}
@subsection Multi-phase initialization


Normally, the @ref{4ffc,,initialization function}
(@code{PyInit_modulename}) returns a @ref{b6b,,PyModuleDef} instance with
non-@code{NULL} @ref{5005,,m_slots}.
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{4d6b}
@deffn {C 函式} @ref{5d7,,PyObject} *PyModuleDef_Init (PyModuleDef *def)
` 為 @ref{76e,,穩定 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 for @ref{5003,,Multi-phase initialization}.
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.


在 3.5 版被加入.

@end deffn

@node Legacy single-phase initialization,,Multi-phase initialization,Defining extension modules
@anchor{c-api/extension-modules legacy-single-phase-initialization}@anchor{5006}@anchor{c-api/extension-modules single-phase-initialization}@anchor{4ffd}
@subsection Legacy single-phase initialization


@cartouche
@quotation 注意 
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.
@end quotation
@end cartouche

In single-phase initialization, the
@ref{4ffc,,initialization function} (@code{PyInit_modulename})
should create, populate and return a module object.
This is typically done using @ref{5007,,PyModule_Create()} and functions like
@ref{602,,PyModule_AddObjectRef()}.

Single-phase initialization differs from the @ref{5003,,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{4f33,,PyState_FindModule()}.
@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 工具,抽象物件層 Abstract Objects Layer,Defining extension modules,Python/C API 參考手冊
@anchor{c-api/utilities doc}@anchor{5008}@anchor{c-api/utilities id1}@anchor{5009}@anchor{c-api/utilities translation-repo}@anchor{500a}@anchor{c-api/utilities utilities}@anchor{500b}
@section 工具


本章中的函式可用來執行各種工具任務，包括幫助 C 程式碼提升跨平臺可攜性 (portable)、在 C 中使用 Python module（模組）、以及剖析函式引數並基於 C 中的值來構建 Python 中的值等。

@menu
* 作業系統工具:: 
* 系統函式:: 
* 行程控制:: 
* 引入模組: 引入模組<2>. 
* 資料 marshal 操作的支援:: 
* 剖析引數與建置數值:: 
* 字串轉換與格式化:: 
* PyHash API:: 
* Reflection:: 
* 編解碼器註冊表和支援函式:: 
* PyTime C API:: 
* 對 Perf Map 的支援:: 

@end menu

@node 作業系統工具,系統函式,,工具
@anchor{c-api/sys doc}@anchor{500c}@anchor{c-api/sys operating-system-utilities}@anchor{500d}@anchor{c-api/sys os}@anchor{500e}
@subsection 作業系統工具


@geindex PyOS_FSPath (C function)
@anchor{c-api/sys c PyOS_FSPath}@anchor{f0f}
@deffn {C 函式} @ref{5d7,,PyObject} *PyOS_FSPath (PyObject *path)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.6 版本開始.'
Return the file system representation for `path'. If the object is a
@ref{169,,str} or @ref{192,,bytes} object, then a new
@ref{5da,,strong reference} is returned.
If the object implements the @ref{e46,,os.PathLike} interface,
then @ref{e47,,__fspath__()} is returned as long as it is a
@ref{169,,str} or @ref{192,,bytes} object. Otherwise @ref{198,,TypeError} is raised
and @code{NULL} is returned.


在 3.6 版被加入.

@end deffn

@geindex Py_FdIsInteractive (C function)
@anchor{c-api/sys c Py_FdIsInteractive}@anchor{500f}
@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{3fd,,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{db3}
@deffn {C 函式} void PyOS_BeforeFork ()
` 為 @ref{76e,,穩定 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{5010,,"main" thread} (of the
@ref{163,,"main" interpreter}).  The same is
true for @code{PyOS_BeforeFork()}.
@end quotation
@end cartouche


在 3.7 版被加入.

@end deffn

@geindex PyOS_AfterFork_Parent (C function)
@anchor{c-api/sys c PyOS_AfterFork_Parent}@anchor{db4}
@deffn {C 函式} void PyOS_AfterFork_Parent ()
` 為 @ref{76e,,穩定 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{5010,,"main" thread} (of the
@ref{163,,"main" interpreter}).  The same is
true for @code{PyOS_AfterFork_Parent()}.
@end quotation
@end cartouche


在 3.7 版被加入.

@end deffn

@geindex PyOS_AfterFork_Child (C function)
@anchor{c-api/sys c PyOS_AfterFork_Child}@anchor{42e}
@deffn {C 函式} void PyOS_AfterFork_Child ()
` 為 @ref{76e,,穩定 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{5010,,"main" thread} (of the
@ref{163,,"main" interpreter}).  The same is
true for @code{PyOS_AfterFork_Child()}.
@end quotation
@end cartouche


在 3.7 版被加入.



@subsubheading 也參考


@ref{353,,os.register_at_fork()} allows registering custom Python functions
to be called by @ref{db3,,PyOS_BeforeFork()},
@ref{db4,,PyOS_AfterFork_Parent()} and  @ref{42e,,PyOS_AfterFork_Child()}.

@end deffn

@geindex PyOS_AfterFork (C function)
@anchor{c-api/sys c PyOS_AfterFork}@anchor{42d}
@deffn {C 函式} void PyOS_AfterFork ()
` 為 @ref{76e,,穩定 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{42e,,PyOS_AfterFork_Child()}.

@end deffn

@geindex PyOS_CheckStack (C function)
@anchor{c-api/sys c PyOS_CheckStack}@anchor{1acb}
@deffn {C 函式} int PyOS_CheckStack ()
` 為 @ref{76e,,穩定 ABI 的一部分} on platforms with USE_STACKCHECK 自 3.7 版本開始.'
@geindex USE_STACKCHECK（C 巨集）

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{4f05}
@deffn {C 型別} typedef void (*PyOS_sighandler_t)(int)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@geindex PyOS_getsig (C function)
@anchor{c-api/sys c PyOS_getsig}@anchor{1732}
@deffn {C 函式} @ref{4f05,,PyOS_sighandler_t} PyOS_getsig (int i)
` 為 @ref{76e,,穩定 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{1733}
@deffn {C 函式} @ref{4f05,,PyOS_sighandler_t} PyOS_setsig (int i, PyOS_sighandler_t h)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Set the signal handler for signal `i' to be `h'; return the old signal handler.
This is a thin wrapper around either @code{sigaction()} or @code{signal()}.  Do
not call those functions directly!
@end deffn

@geindex Py_DecodeLocale (C function)
@anchor{c-api/sys c Py_DecodeLocale}@anchor{dbb}
@deffn {C 函式} wchar_t *Py_DecodeLocale (const char *arg, size_t *size)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.7 版本開始.'
@cartouche
@quotation 警告 
This function should not be called directly: use the @ref{3f4,,PyConfig}
API with the @ref{ba2,,PyConfig_SetBytesString()} function which ensures
that @ref{4183,,Python is preinitialized}.

This function must not be called before @ref{4183,,Python is preinitialized} and so that the LC_CTYPE locale is properly configured: see
the @ref{41c,,Py_PreInitialize()} function.
@end quotation
@end cartouche

Decode a byte string from the @ref{756,,filesystem encoding and error handler}.
If the error handler is @ref{2700,,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{62c,,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{756,,filesystem encoding and error handler} are selected by
@ref{98b,,PyConfig_Read()}: see @ref{419,,filesystem_encoding} and
@ref{41a,,filesystem_errors} members of @ref{3f4,,PyConfig}.

Decoding errors should never happen, unless there is a bug in the C
library.

Use the @ref{dbc,,Py_EncodeLocale()} function to encode the character string
back to a byte string.


@subsubheading 也參考


The @ref{4f6d,,PyUnicode_DecodeFSDefaultAndSize()} and
@ref{dbd,,PyUnicode_DecodeLocaleAndSize()} functions.



在 3.5 版被加入.



在 3.7 版的變更: The function now uses the UTF-8 encoding in the @ref{85f,,Python UTF-8 Mode}.



在 3.8 版的變更: The function now uses the UTF-8 encoding on Windows if
@ref{416,,PyPreConfig.legacy_windows_fs_encoding} is zero;

@end deffn

@geindex Py_EncodeLocale (C function)
@anchor{c-api/sys c Py_EncodeLocale}@anchor{dbc}
@deffn {C 函式} char *Py_EncodeLocale (const wchar_t *text, size_t *error_pos)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.7 版本開始.'
Encode a wide character string to the @ref{756,,filesystem encoding and error handler}. If the error handler is @ref{2700,,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{1639,,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{756,,filesystem encoding and error handler} are selected by
@ref{98b,,PyConfig_Read()}: see @ref{419,,filesystem_encoding} and
@ref{41a,,filesystem_errors} members of @ref{3f4,,PyConfig}.

Use the @ref{dbb,,Py_DecodeLocale()} function to decode the bytes string back
to a wide character string.

@cartouche
@quotation 警告 
This function must not be called before @ref{4183,,Python is preinitialized} and so that the LC_CTYPE locale is properly configured: see
the @ref{41c,,Py_PreInitialize()} function.
@end quotation
@end cartouche


@subsubheading 也參考


The @ref{1cf9,,PyUnicode_EncodeFSDefault()} and
@ref{dbe,,PyUnicode_EncodeLocale()} functions.



在 3.5 版被加入.



在 3.7 版的變更: The function now uses the UTF-8 encoding in the @ref{85f,,Python UTF-8 Mode}.



在 3.8 版的變更: The function now uses the UTF-8 encoding on Windows if
@ref{416,,PyPreConfig.legacy_windows_fs_encoding} is zero.

@end deffn

@geindex Py_fopen (C function)
@anchor{c-api/sys c Py_fopen}@anchor{391}
@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{169,,str} object, a @ref{192,,bytes} object,
or a @ref{59b,,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{392,,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{4d99,,attached thread state}.


在 3.14 版被加入.

@end deffn

@geindex Py_fclose (C function)
@anchor{c-api/sys c Py_fclose}@anchor{392}
@deffn {C 函式} int Py_fclose (FILE *file)

Close a file that was opened by @ref{391,,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{392,,Py_fclose()}) to the stream results in undefined behavior.


在 3.14 版被加入.

@end deffn

@node 系統函式,行程控制,作業系統工具,工具
@anchor{c-api/sys system-functions}@anchor{5011}@anchor{c-api/sys systemfunctions}@anchor{5012}
@subsection 系統函式


These are utility functions that make functionality from the @ref{df,,sys} module
accessible to C code.  They all work with the current interpreter thread's
@ref{df,,sys} module's dict, which is contained in the internal thread state structure.

@geindex PySys_GetObject (C function)
@anchor{c-api/sys c PySys_GetObject}@anchor{622}
@deffn {C 函式} @ref{5d7,,PyObject} *PySys_GetObject (const char *name)
`回傳值：借用參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return the object `name' from the @ref{df,,sys} module or @code{NULL} if it does
not exist, without setting an exception.
@end deffn

@geindex PySys_SetObject (C function)
@anchor{c-api/sys c PySys_SetObject}@anchor{4f3c}
@deffn {C 函式} int PySys_SetObject (const char *name, PyObject *v)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Set `name' in the @ref{df,,sys} module to `v' unless `v' is @code{NULL}, in which
case `name' is deleted from the sys module. Returns @code{0} on success, @code{-1}
on error.
@end deffn

@geindex PySys_ResetWarnOptions (C function)
@anchor{c-api/sys c PySys_ResetWarnOptions}@anchor{3f2}
@deffn {C 函式} void PySys_ResetWarnOptions ()
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Reset @ref{3f3,,sys.warnoptions} to an empty list. This function may be
called prior to @ref{45e,,Py_Initialize()}.


Deprecated since version 3.13, will be removed in version 3.15: Clear @ref{3f3,,sys.warnoptions} and @code{warnings.filters} instead.

@end deffn

@geindex PySys_WriteStdout (C function)
@anchor{c-api/sys c PySys_WriteStdout}@anchor{4f3e}
@deffn {C 函式} void PySys_WriteStdout (const char *format, ...)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Write the output string described by `format' to @ref{cc4,,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{cc4,,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{4f3d}
@deffn {C 函式} void PySys_WriteStderr (const char *format, ...)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
As @ref{4f3e,,PySys_WriteStdout()}, but write to @ref{b2a,,sys.stderr} or `stderr'
instead.
@end deffn

@geindex PySys_FormatStdout (C function)
@anchor{c-api/sys c PySys_FormatStdout}@anchor{4f3a}
@deffn {C 函式} void PySys_FormatStdout (const char *format, ...)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Function similar to PySys_WriteStdout() but format the message using
@ref{78d,,PyUnicode_FromFormatV()} and don't truncate the message to an
arbitrary length.


在 3.2 版被加入.

@end deffn

@geindex PySys_FormatStderr (C function)
@anchor{c-api/sys c PySys_FormatStderr}@anchor{4f39}
@deffn {C 函式} void PySys_FormatStderr (const char *format, ...)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
As @ref{4f3a,,PySys_FormatStdout()}, but write to @ref{b2a,,sys.stderr} or `stderr'
instead.


在 3.2 版被加入.

@end deffn

@geindex PySys_GetXOptions (C function)
@anchor{c-api/sys c PySys_GetXOptions}@anchor{4f3b}
@deffn {C 函式} @ref{5d7,,PyObject} *PySys_GetXOptions ()
`回傳值：借用參照。'` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.7 版本開始.'
Return the current dictionary of @ref{16f,,-X} options, similarly to
@ref{1ff8,,sys._xoptions}.  On error, @code{NULL} is returned and an exception is
set.


在 3.2 版被加入.

@end deffn

@geindex PySys_Audit (C function)
@anchor{c-api/sys c PySys_Audit}@anchor{60b}
@deffn {C 函式} int PySys_Audit (const char *event, const char *format, ...)
` 為 @ref{76e,,穩定 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{3c0,,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{c4c,,Py_ssize_t}, regardless of whether @code{PY_SSIZE_T_CLEAN} was defined.

@ref{1882,,sys.audit()} performs the same function from Python code.

請參閱 @ref{60a,,PySys_AuditTuple()}。


在 3.8 版被加入.



在 3.8.2 版的變更: Require @ref{c4c,,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{60a}
@deffn {C 函式} int PySys_AuditTuple (const char *event, PyObject *args)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.13 版本開始.'
Similar to @ref{60b,,PySys_Audit()}, but pass arguments as a Python object.
`args' must be a @ref{60c,,tuple}. To pass no arguments, `args' can be `NULL'.


在 3.13 版被加入.

@end deffn

@geindex PySys_AddAuditHook (C function)
@anchor{c-api/sys c PySys_AddAuditHook}@anchor{460a}
@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{45e,,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{bc4,,Exception} (other errors will not be silenced).

The hook function is always called with an @ref{4d99,,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{1b27,,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{bc4,,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{5013}
@deffn {C 型別} typedef int (*Py_AuditHookFunction)(const char *event, @ref{5d7,,PyObject} *args, void *userData)

The type of the hook function.
`event' is the C string event argument passed to @ref{60b,,PySys_Audit()} or
@ref{60a,,PySys_AuditTuple()}.
`args' is guaranteed to be a @ref{5014,,PyTupleObject}.
`userData' is the argument passed to PySys_AddAuditHook().
@end deffn


在 3.8 版被加入.

@end deffn

@node 行程控制,引入模組<2>,系統函式,工具
@anchor{c-api/sys process-control}@anchor{5015}@anchor{c-api/sys processcontrol}@anchor{5016}
@subsection 行程控制


@geindex Py_FatalError (C function)
@anchor{c-api/sys c Py_FatalError}@anchor{b71}
@deffn {C 函式} void Py_FatalError (const char *message)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@geindex abort（C 函式）

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{f46}
@deffn {C 函式} void Py_Exit (int status)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@geindex Py_FinalizeEx（C 函式）
@geindex exit（C 函式）

Exit the current process.  This calls @ref{f0c,,Py_FinalizeEx()} and then calls the
standard C library function @code{exit(status)}.  If @ref{f0c,,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{4f8d}
@deffn {C 函式} int Py_AtExit (void (*func)())
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@geindex Py_FinalizeEx（C 函式）
@geindex cleanup functions（清理函式）

Register a cleanup function to be called by @ref{f0c,,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{4f8d,,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{1865,,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 引入模組<2>,資料 marshal 操作的支援,行程控制,工具
@anchor{c-api/import doc}@anchor{5017}@anchor{c-api/import importing}@anchor{5018}@anchor{c-api/import importing-modules}@anchor{5019}@anchor{c-api/import translation-repo}@anchor{501a}
@subsection 引入模組


@geindex PyImport_ImportModule (C function)
@anchor{c-api/import c PyImport_ImportModule}@anchor{3da}
@deffn {C 函式} @ref{5d7,,PyObject} *PyImport_ImportModule (const char *name)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
@geindex package variable（套件變數）;__all__
@geindex __all__（套件變數）
@geindex modules（sys 模組中）

This is a wrapper around @ref{15f3,,PyImport_Import()} which takes a
const char* as an argument instead of a @ref{5d7,,PyObject}*.
@end deffn

@geindex PyImport_ImportModuleNoBlock (C function)
@anchor{c-api/import c PyImport_ImportModuleNoBlock}@anchor{3d9}
@deffn {C 函式} @ref{5d7,,PyObject} *PyImport_ImportModuleNoBlock (const char *name)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
This function is a deprecated alias of @ref{3da,,PyImport_ImportModule()}.


在 3.3 版的變更: This function used to fail immediately when the import lock was held
by another thread.  In Python 3.3 though, the locking scheme switched
to per-module locks for most purposes, so this function's special
behaviour isn't needed anymore.



Deprecated since version 3.13, will be removed in version 3.15: 請改用 @ref{3da,,PyImport_ImportModule()}。

@end deffn

@geindex PyImport_ImportModuleEx (C function)
@anchor{c-api/import c PyImport_ImportModuleEx}@anchor{13a6}
@deffn {C 函式} @ref{5d7,,PyObject} *PyImport_ImportModuleEx (const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist)
`回傳值：新的參照。'
@geindex built-in function（內建函式）;__import__

Import a module.  This is best described by referring to the built-in Python
function @ref{ac8,,__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{ac8,,__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{3da,,PyImport_ImportModule()}.
@end deffn

@geindex PyImport_ImportModuleLevelObject (C function)
@anchor{c-api/import c PyImport_ImportModuleLevelObject}@anchor{4ec3}
@deffn {C 函式} @ref{5d7,,PyObject} *PyImport_ImportModuleLevelObject (PyObject *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.7 版本開始.'
Import a module.  This is best described by referring to the built-in Python
function @ref{ac8,,__import__()}, as the standard @ref{ac8,,__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{ac8,,__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.


在 3.3 版被加入.

@end deffn

@geindex PyImport_ImportModuleLevel (C function)
@anchor{c-api/import c PyImport_ImportModuleLevel}@anchor{13a5}
@deffn {C 函式} @ref{5d7,,PyObject} *PyImport_ImportModuleLevel (const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Similar to @ref{4ec3,,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{15f3}
@deffn {C 函式} @ref{5d7,,PyObject} *PyImport_Import (PyObject *name)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{ac8,,__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{4ec4}
@deffn {C 函式} @ref{5d7,,PyObject} *PyImport_ReloadModule (PyObject *m)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{5f3}
@deffn {C 函式} @ref{5d7,,PyObject} *PyImport_AddModuleRef (const char *name)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{5da,,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{3da,,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.


在 3.13 版被加入.

@end deffn

@geindex PyImport_AddModuleObject (C function)
@anchor{c-api/import c PyImport_AddModuleObject}@anchor{4eba}
@deffn {C 函式} @ref{5d7,,PyObject} *PyImport_AddModuleObject (PyObject *name)
`回傳值：借用參照。'` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.7 版本開始.'
Similar to @ref{5f3,,PyImport_AddModuleRef()}, but return a @ref{3d5,,borrowed reference} and `name' is a Python @ref{169,,str} object.


在 3.3 版被加入.

@end deffn

@geindex PyImport_AddModule (C function)
@anchor{c-api/import c PyImport_AddModule}@anchor{5f4}
@deffn {C 函式} @ref{5d7,,PyObject} *PyImport_AddModule (const char *name)
`回傳值：借用參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Similar to @ref{5f3,,PyImport_AddModuleRef()}, but return a @ref{3d5,,borrowed reference}.
@end deffn

@geindex PyImport_ExecCodeModule (C function)
@anchor{c-api/import c PyImport_ExecCodeModule}@anchor{4ebb}
@deffn {C 函式} @ref{5d7,,PyObject} *PyImport_ExecCodeModule (const char *name, PyObject *co)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{4ac,,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{17c0,,sys.modules} in error cases, even if `name' was already
in @ref{17c0,,sys.modules} on entry to @ref{4ebb,,PyImport_ExecCodeModule()}.  Leaving
incompletely initialized modules in @ref{17c0,,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{2216,,__spec__} and @ref{33a,,__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{126f,,SourceFileLoader} otherwise.

The module's @ref{221b,,__file__} attribute will be set to the code
object's @ref{1565,,co_filename}.  If applicable,
@ref{320,,__cached__} will also be set.

This function will reload the module if it was already imported.  See
@ref{4ec4,,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{4ebc,,PyImport_ExecCodeModuleEx()} and
@ref{4ebe,,PyImport_ExecCodeModuleWithPathnames()}.


在 3.12 版的變更: The setting of @ref{320,,__cached__} and @ref{33a,,__loader__}
is deprecated. See @ref{2130,,ModuleSpec} for
alternatives.

@end deffn

@geindex PyImport_ExecCodeModuleEx (C function)
@anchor{c-api/import c PyImport_ExecCodeModuleEx}@anchor{4ebc}
@deffn {C 函式} @ref{5d7,,PyObject} *PyImport_ExecCodeModuleEx (const char *name, PyObject *co, const char *pathname)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Like @ref{4ebb,,PyImport_ExecCodeModule()}, but the @ref{221b,,__file__}
attribute of the module object is set to `pathname' if it is non-@code{NULL}.

也請見 @ref{4ebe,,PyImport_ExecCodeModuleWithPathnames()}。
@end deffn

@geindex PyImport_ExecCodeModuleObject (C function)
@anchor{c-api/import c PyImport_ExecCodeModuleObject}@anchor{4ebd}
@deffn {C 函式} @ref{5d7,,PyObject} *PyImport_ExecCodeModuleObject (PyObject *name, PyObject *co, PyObject *pathname, PyObject *cpathname)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.7 版本開始.'
Like @ref{4ebc,,PyImport_ExecCodeModuleEx()}, but the @ref{320,,__cached__}
attribute of the module object is set to `cpathname' if it is
non-@code{NULL}.  Of the three functions, this is the preferred one to use.


在 3.3 版被加入.



在 3.12 版的變更: Setting @ref{320,,__cached__} is deprecated. See
@ref{2130,,ModuleSpec} for alternatives.

@end deffn

@geindex PyImport_ExecCodeModuleWithPathnames (C function)
@anchor{c-api/import c PyImport_ExecCodeModuleWithPathnames}@anchor{4ebe}
@deffn {C 函式} @ref{5d7,,PyObject} *PyImport_ExecCodeModuleWithPathnames (const char *name, PyObject *co, const char *pathname, const char *cpathname)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Like @ref{4ebd,,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}.


在 3.2 版被加入.



在 3.3 版的變更: Uses @code{imp.source_from_cache()} in calculating the source path if
only the bytecode path is provided.



在 3.12 版的變更: 不再使用已被移除的 @code{imp} 模組。

@end deffn

@geindex PyImport_GetMagicNumber (C function)
@anchor{c-api/import c PyImport_GetMagicNumber}@anchor{13a4}
@deffn {C 函式} long PyImport_GetMagicNumber ()
` 為 @ref{76e,,穩定 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 版的變更: 當失敗時回傳 @code{-1}。

@end deffn

@geindex PyImport_GetMagicTag (C function)
@anchor{c-api/import c PyImport_GetMagicTag}@anchor{4ebf}
@deffn {C 函式} const char *PyImport_GetMagicTag ()
` 為 @ref{76e,,穩定 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.


在 3.2 版被加入.

@end deffn

@geindex PyImport_GetModuleDict (C function)
@anchor{c-api/import c PyImport_GetModuleDict}@anchor{4ec0}
@deffn {C 函式} @ref{5d7,,PyObject} *PyImport_GetModuleDict ()
`回傳值：借用參照。'` 為 @ref{76e,,穩定 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{da7}
@deffn {C 函式} @ref{5d7,,PyObject} *PyImport_GetModule (PyObject *name)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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.


在 3.7 版被加入.

@end deffn

@geindex PyImport_GetImporter (C function)
@anchor{c-api/import c PyImport_GetImporter}@anchor{19d6}
@deffn {C 函式} @ref{5d7,,PyObject} *PyImport_GetImporter (PyObject *path)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return a finder object for a @ref{3e2,,sys.path}/@code{pkg.__path__} item
`path', possibly by fetching it from the @ref{7f3,,sys.path_importer_cache}
dict.  If it wasn't yet cached, traverse @ref{121f,,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{22fc,,path based finder} could not find a
finder for this path item. Cache the result in @ref{7f3,,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{4ec2}
@deffn {C 函式} int PyImport_ImportFrozenModuleObject (PyObject *name)
` 為 @ref{76e,,穩定 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{3da,,PyImport_ImportModule()}.  (Note the misnomer --- this function would
reload the module if it was already imported.)


在 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{4ec1}
@deffn {C 函式} int PyImport_ImportFrozenModule (const char *name)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Similar to @ref{4ec2,,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{971}
@deffn {C 結構} 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{31cd}
@deffn {C 變數} const struct @ref{971,,_frozen} *PyImport_FrozenModules

This pointer is initialized to point to an array of @ref{971,,_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{1a5f}
@deffn {C 函式} int PyImport_AppendInittab (const char *name, PyObject *(*initfunc)(void))
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Add a single module to the existing table of built-in modules.  This is a
convenience wrapper around @ref{1a60,,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{45e,,Py_Initialize()}.
@end deffn

@geindex _inittab (C struct)
@anchor{c-api/import c _inittab}@anchor{501b}
@deffn {C 結構} 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{1a60,,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{501c}
@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{501d}
@deffn {C 成員函數} @ref{5d7,,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{1a60}
@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{501c,,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{45e,,Py_Initialize()}.

If Python is initialized multiple times, @ref{1a5f,,PyImport_AppendInittab()} or
@ref{1a60,,PyImport_ExtendInittab()} must be called before each Python
initialization.
@end deffn

@geindex PyImport_ImportModuleAttr (C function)
@anchor{c-api/import c PyImport_ImportModuleAttr}@anchor{394}
@deffn {C 函式} @ref{5d7,,PyObject} *PyImport_ImportModuleAttr (PyObject *mod_name, PyObject *attr_name)
`回傳值：新的參照。'
Import the module `mod_name' and get its attribute `attr_name'.

名稱必須是 Python @ref{169,,str} 物件。

Helper function combining @ref{15f3,,PyImport_Import()} and
@ref{5e6,,PyObject_GetAttr()}. For example, it can raise @ref{653,,ImportError} if
the module is not found, and @ref{5e8,,AttributeError} if the attribute doesn't
exist.


在 3.14 版被加入.

@end deffn

@geindex PyImport_ImportModuleAttrString (C function)
@anchor{c-api/import c PyImport_ImportModuleAttrString}@anchor{395}
@deffn {C 函式} @ref{5d7,,PyObject} *PyImport_ImportModuleAttrString (const char *mod_name, const char *attr_name)
`回傳值：新的參照。'
Similar to @ref{394,,PyImport_ImportModuleAttr()}, but names are UTF-8 encoded
strings instead of Python @ref{169,,str} objects.


在 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 資料 marshal 操作的支援,剖析引數與建置數值,引入模組<2>,工具
@anchor{c-api/marshal doc}@anchor{501e}@anchor{c-api/marshal data-marshalling-support}@anchor{501f}@anchor{c-api/marshal marshalling-utils}@anchor{5020}@anchor{c-api/marshal translation-repo}@anchor{5021}
@subsection 資料 marshal 操作的支援


這些例程允許 C 程式碼使用與 @ref{91,,marshal} 模組相同的資料格式來處理序列化物件。有函式可以將資料寫入序列化格式，還有其他函式可以用來讀取回資料。用來儲存 marshal 過的資料的檔案必須以二進位模式開啟。

數值會以最低有效位元組 (the least significant byte) 優先的方式儲存。

The module supports several versions of the data format; see
the @ref{91,,Python module documentation} for details.

@geindex Py_MARSHAL_VERSION (C macro)
@anchor{c-api/marshal c Py_MARSHAL_VERSION}@anchor{5022}
@deffn {C 巨集} Py_MARSHAL_VERSION

The current format version. See @ref{2bf5,,marshal.version}.
@end deffn

@geindex PyMarshal_WriteLongToFile (C function)
@anchor{c-api/marshal c PyMarshal_WriteLongToFile}@anchor{991}
@deffn {C 函式} void PyMarshal_WriteLongToFile (long value, FILE *file, int version)

將一個 long 整數 `value' marshal 為 `file'。這只會寫入 `value' 的最低有效 32 位元；無論原生 long 型別的大小如何。`version' 表示檔案的格式。

這個函式可能會失敗，這時會設定錯誤指示器。使用 @ref{1ba7,,PyErr_Occurred()} 來檢查是否發生錯誤。
@end deffn

@geindex PyMarshal_WriteObjectToFile (C function)
@anchor{c-api/marshal c PyMarshal_WriteObjectToFile}@anchor{992}
@deffn {C 函式} void PyMarshal_WriteObjectToFile (PyObject *value, FILE *file, int version)

將一個 Python 物件 `value' marshal 為 `file'。`version' 表示檔案的格式。

這個函式可能會失敗，這時會設定錯誤指示器。使用 @ref{1ba7,,PyErr_Occurred()} 來檢查是否發生錯誤。
@end deffn

@geindex PyMarshal_WriteObjectToString (C function)
@anchor{c-api/marshal c PyMarshal_WriteObjectToString}@anchor{994}
@deffn {C 函式} @ref{5d7,,PyObject} *PyMarshal_WriteObjectToString (PyObject *value, int version)
`回傳值：新的參照。'
回傳一個位元組物件，包含 `value' 的 marshal 表示。`version' 為檔案的格式。
@end deffn

以下函式允許將 marshal 過後的值讀取回來。

@geindex PyMarshal_ReadLongFromFile (C function)
@anchor{c-api/marshal c PyMarshal_ReadLongFromFile}@anchor{5023}
@deffn {C 函式} long PyMarshal_ReadLongFromFile (FILE *file)

從一個為讀取而開啟的 FILE* 中的資料串流回傳一個 C long。無論 long 的原生大小如何，這個函式只能讀取 32 位元的值。

在錯誤發生時，會設定合適的例外（@ref{14da,,EOFError}）並回傳 @code{-1}。
@end deffn

@geindex PyMarshal_ReadShortFromFile (C function)
@anchor{c-api/marshal c PyMarshal_ReadShortFromFile}@anchor{5024}
@deffn {C 函式} int PyMarshal_ReadShortFromFile (FILE *file)

從一個為讀取而開啟的 FILE* 中的資料串流回傳一個 C short。無論 short 的原生大小如何，這個函式只能讀取 16 位元的值。

在錯誤發生時，會設定合適的例外（@ref{14da,,EOFError}）並回傳 @code{-1}。
@end deffn

@geindex PyMarshal_ReadObjectFromFile (C function)
@anchor{c-api/marshal c PyMarshal_ReadObjectFromFile}@anchor{5025}
@deffn {C 函式} @ref{5d7,,PyObject} *PyMarshal_ReadObjectFromFile (FILE *file)
`回傳值：新的參照。'
從一個為讀取而開啟的 FILE* 中的資料串流回傳一個 Python 物件。

在錯誤發生時，會設定合適的例外（@ref{14da,,EOFError}、@ref{2eb,,ValueError} 或 @ref{198,,TypeError}）並回傳 @code{NULL}。
@end deffn

@geindex PyMarshal_ReadLastObjectFromFile (C function)
@anchor{c-api/marshal c PyMarshal_ReadLastObjectFromFile}@anchor{5026}
@deffn {C 函式} @ref{5d7,,PyObject} *PyMarshal_ReadLastObjectFromFile (FILE *file)
`回傳值：新的參照。'
從一個為讀取而開啟的 FILE* 中的資料串流回傳一個 Python 物件。與 @ref{5025,,PyMarshal_ReadObjectFromFile()} 不同，這個函式假設不會從檔案中讀取其他物件，允許它積極地將檔案資料載入記憶體，以便反序列化可以從記憶體中的資料操作，而不是從檔案中逐位元組讀取。只有在確定不會從檔案中讀取其他內容時，才使用這個變體。

在錯誤發生時，會設定合適的例外（@ref{14da,,EOFError}、@ref{2eb,,ValueError} 或 @ref{198,,TypeError}）並回傳 @code{NULL}。
@end deffn

@geindex PyMarshal_ReadObjectFromString (C function)
@anchor{c-api/marshal c PyMarshal_ReadObjectFromString}@anchor{993}
@deffn {C 函式} @ref{5d7,,PyObject} *PyMarshal_ReadObjectFromString (const char *data, Py_ssize_t len)
`回傳值：新的參照。'
從一個包含 `len' 位元組、被 `data' 指向的位元組緩衝區中的資料串流回傳一個 Python 物件。

在錯誤發生時，會設定合適的例外（@ref{14da,,EOFError}、@ref{2eb,,ValueError} 或 @ref{198,,TypeError}）並回傳 @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 剖析引數與建置數值,字串轉換與格式化,資料 marshal 操作的支援,工具
@anchor{c-api/arg doc}@anchor{5027}@anchor{c-api/arg arg-parsing}@anchor{3d3}@anchor{c-api/arg parsing-arguments-and-building-values}@anchor{5028}@anchor{c-api/arg translation-repo}@anchor{5029}
@subsection 剖析引數與建置數值


These functions are useful when creating your own extension functions and
methods.  Additional information and examples are available in
@ref{1e84,,擴充和嵌入 Python 直譯器}.

The first three of these functions described, @ref{3bf,,PyArg_ParseTuple()},
@ref{61c,,PyArg_ParseTupleAndKeywords()}, and @ref{1791,,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
* 剖析引數: 剖析引數<2>. 
* 建置數值:: 

@end menu

@node 剖析引數<2>,建置數值,,剖析引數與建置數值
@anchor{c-api/arg parsing-arguments}@anchor{502a}
@subsubsection 剖析引數


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
* 字串與緩衝區:: 
* 數字:: 
* 其他物件:: 
* API 函式:: 

@end menu

@node 字串與緩衝區,數字,,剖析引數<2>
@anchor{c-api/arg arg-parsing-string-and-buffers}@anchor{624}@anchor{c-api/arg strings-and-buffers}@anchor{502b}
@subsubsection 字串與緩衝區


@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{954,,Py_buffer} structure.
This locks the underlying buffer so that the caller can subsequently use
the buffer even inside a @ref{4d85,,Py_BEGIN_ALLOW_THREADS}
block without the risk of mutable data being resized or destroyed.
As a result, `you have to call' @ref{633,,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{1639,,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{3d4}
Other formats take a @ref{169,,str} or a read-only @ref{193,,bytes-like object},
such as @ref{192,,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{95f,,PyBufferProcs.bf_releasebuffer} field must be @code{NULL}.
This disallows common mutable objects such as @ref{343,,bytearray},
but also some read-only objects such as @ref{165,,memoryview} of
@ref{192,,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{169,,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{2eb,,ValueError} exception is raised. Unicode objects are converted
to C strings using @code{'utf-8'} encoding. If this conversion fails, a
@ref{460,,UnicodeError} is raised.

@cartouche
@quotation 備註 
This format does not accept @ref{193,,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{f10,,PyUnicode_FSConverter()}
as `converter'.
@end quotation
@end cartouche


在 3.5 版的變更: Previously, @ref{198,,TypeError} was raised when embedded null code points
were encountered in the Python string.


@item @code{s*} (@ref{169,,str} 或 @ref{193,,bytes-like object}) [Py_buffer]

This format accepts Unicode objects as well as bytes-like objects.
It fills a @ref{954,,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{169,,str}、唯讀的 @ref{193,,bytes-like object}) [const char *, @ref{c4c,,Py_ssize_t}]

Like @code{s*}, except that it provides a @ref{3d4,,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{169,,str} 或 @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{169,,str}、@ref{193,,bytes-like object} 或 @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{954,,Py_buffer} structure is set to @code{NULL}.

@item @code{z#} (@ref{169,,str}、唯讀的 @ref{193,,bytes-like object} 或 @code{None}) [const char *, @ref{c4c,,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} (唯讀的 @ref{193,,bytes-like object}) [const char *]

This format converts a bytes-like object to a C pointer to a
@ref{3d4,,borrowed} character string;
it does not accept Unicode objects.  The bytes buffer must not
contain embedded null bytes; if it does, a @ref{2eb,,ValueError}
exception is raised.


在 3.5 版的變更: Previously, @ref{198,,TypeError} was raised when embedded null bytes were
encountered in the bytes buffer.


@item @code{y*} (@ref{193,,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#} (唯讀的 @ref{193,,bytes-like object}) [const char *, @ref{c4c,,Py_ssize_t}]

This variant on @code{s#} doesn't accept Unicode objects, only bytes-like
objects.

@item @code{S} (@ref{192,,bytes}) [PyBytesObject *]

Requires that the Python object is a @ref{192,,bytes} object, without
attempting any conversion.  Raises @ref{198,,TypeError} if the object is not
a bytes object.  The C variable may also be declared as @ref{5d7,,PyObject}*.

@item @code{Y} (@ref{343,,bytearray}) [PyByteArrayObject *]

Requires that the Python object is a @ref{343,,bytearray} object, without
attempting any conversion.  Raises @ref{198,,TypeError} if the object is not
a @ref{343,,bytearray} object. The C variable may also be declared as @ref{5d7,,PyObject}*.

@item @code{U} (@ref{169,,str}) [PyObject *]

Requires that the Python object is a Unicode object, without attempting
any conversion.  Raises @ref{198,,TypeError} if the object is not a Unicode
object.  The C variable may also be declared as @ref{5d7,,PyObject}*.

@item @code{w*} (可讀寫 @ref{193,,bytes-like object}) [Py_buffer]

This format accepts any object which implements the read-write buffer
interface. It fills a @ref{954,,Py_buffer} structure provided by the caller.
The buffer may contain embedded null bytes. The caller has to call
@ref{633,,PyBuffer_Release()} when it is done with the buffer.

@item @code{es} (@ref{169,,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{3bf,,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{1639,,PyMem_Free()} to
free the allocated buffer after use.

@item @code{et} (@ref{169,,str}、@ref{192,,bytes} 或 @ref{343,,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{169,,str}) [const char *encoding, char **buffer, @ref{c4c,,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.

有兩個操作模式：

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{1639,,PyMem_Free()} to free the allocated buffer after usage.

If `*buffer' points to a non-@code{NULL} pointer (an already allocated buffer),
@ref{3bf,,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{2eb,,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{169,,str}, @ref{192,,bytes} or @ref{343,,bytearray}) [const char *encoding, char **buffer, @ref{c4c,,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 數字,其他物件,字串與緩衝區,剖析引數<2>
@anchor{c-api/arg numbers}@anchor{502c}
@subsubsection 數字


These formats allow representing Python numbers or single characters as C numbers.
Formats that require @ref{19b,,int}, @ref{196,,float} or @ref{197,,complex} can
also use the corresponding special methods @ref{19e,,__index__()},
@ref{bb8,,__float__()} or @ref{7f8,,__complex__()} to convert
the Python object to the required type.

For signed integer formats, @ref{a78,,OverflowError} is raised if the value
is out of range for the C type.
For unsigned integer formats, no range checking is done --- the
most significant bits are silently truncated when the receiving field is too
small to receive the value.


@table @asis

@item @code{b} (@ref{19b,,int}) [unsigned char]

將一個 Python 非負整數轉換成無符號 tiny integer（小整數），儲存在 C 的 unsigned

@item @code{B} (@ref{19b,,int}) [unsigned char]

將一個 Python 整數轉換成 tiny integer，轉換過程無溢位檢查，儲存在 C 的 unsigned char。

@item @code{h} (@ref{19b,,int}) [short int]

將一個 Python 整數轉換成 C 的 short int。

@item @code{H} (@ref{19b,,int}) [unsigned short int]

將一個 Python 整數轉換成 C 的 unsigned short int，轉換過程無溢位檢查。

@item @code{i} (@ref{19b,,int}) [int]

將一個 Python 整數轉換成 C 的 int。

@item @code{I} (@ref{19b,,int}) [unsigned int]

將一個 Python 整數轉換成 C 的 unsigned int，轉換過程無溢位檢查。

@item @code{l} (@ref{19b,,int}) [long int]

將一個 Python 整數轉換成 C 的 long int。

@item @code{k} (@ref{19b,,int}) [unsigned long]

將一個 Python 整數轉換成 C 的 unsigned long，轉換過程無溢位檢查。


在 3.14 版的變更: 如有提供則使用 @ref{19e,,__index__()}。


@item @code{L} (@ref{19b,,int}) [long long]

將一個 Python 整數轉換成 C 的 long long。

@item @code{K} (@ref{19b,,int}) [unsigned long long]

將一個 Python 整數轉換成 C 的 unsigned long long，轉換過程無溢位檢查。


在 3.14 版的變更: 如有提供則使用 @ref{19e,,__index__()}。


@item @code{n} (@ref{19b,,int}) [@ref{c4c,,Py_ssize_t}]

將一個 Python 整數轉換成 C 的 @ref{c4c,,Py_ssize_t}。

@item @code{c} (@ref{192,,bytes} 或長度為 1 的 @ref{343,,bytearray}) [char]

Convert a Python byte, represented as a @ref{192,,bytes} or
@ref{343,,bytearray} object of length 1, to a C char.


在 3.3 版的變更: 允許 @ref{343,,bytearray} 物件。


@item @code{C} (長度為 1 的 @ref{169,,str}) [int]

Convert a Python character, represented as a @ref{169,,str} object of
length 1, to a C int.

@item @code{f} (@ref{196,,float}) [float]

將一個 Python 浮點數轉換成 C 的 :c:type:float。

@item @code{d} (@ref{196,,float}) [double]

將一個 Python 浮點數轉換成 C 的 :c:type:double。

@item @code{D} (@ref{197,,complex}) [Py_complex]

將一個 Python 複數轉換成 C 的 @ref{502d,,Py_complex} 結構。
@end table

@node 其他物件,API 函式,數字,剖析引數<2>
@anchor{c-api/arg other-objects}@anchor{502e}
@subsubsection 其他物件



@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{5da,,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{5d7,,PyObject}*) into which
the object pointer is stored.  If the Python object does not have the required
type, @ref{198,,TypeError} is raised.
@end table
@anchor{c-api/arg o-ampersand}@anchor{502f}

@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{5030}
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{f10,,PyUnicode_FSConverter()} and
@ref{790,,PyUnicode_FSDecoder()}.


在 3.1 版的變更: 新增 @code{Py_CLEANUP_SUPPORTED}。


@item @code{p} (@ref{3c1,,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{17d7,,真值檢測} for more
information about how Python tests values for truth.


在 3.3 版被加入.


@item @code{(items)} (sequence) [`matching-items']

The object must be a Python sequence (except @ref{169,,str}, @ref{192,,bytes}
or @ref{343,,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{3d4,,borrowed buffer} (@code{s}, @code{s#}, @code{z}, @code{z#}, @code{y}, or @code{y#})
or a @ref{3d5,,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{169,,str} and @ref{343,,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{3bf,,PyArg_ParseTuple()} does not touch the contents of the corresponding C
variable(s).

@item @code{$}

@ref{61c,,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.


在 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{3bf,,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 函式,,其他物件,剖析引數<2>
@anchor{c-api/arg api-functions}@anchor{5031}
@subsubsection API 函式


@geindex PyArg_ParseTuple (C function)
@anchor{c-api/arg c PyArg_ParseTuple}@anchor{3bf}
@deffn {C 函式} int PyArg_ParseTuple (PyObject *args, const char *format, ...)
` 為 @ref{76e,,穩定 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{4e15}
@deffn {C 函式} int PyArg_VaParse (PyObject *args, const char *format, va_list vargs)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Identical to @ref{3bf,,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{61c}
@deffn {C 函式} int PyArg_ParseTupleAndKeywords (PyObject *args, PyObject *kw, const char *format, char *const *keywords, ...)
` 為 @ref{76e,,穩定 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{c6f,,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{61e,,PY_CXX_CONST} macro.
@end quotation
@end cartouche


在 3.6 版的變更: 新增對@ref{c6f,,僅限位置參數}的支援。



在 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{61d}
@deffn {C 函式} int PyArg_VaParseTupleAndKeywords (PyObject *args, PyObject *kw, const char *format, char *const *keywords, va_list vargs)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Identical to @ref{61c,,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{4e16}
@deffn {C 函式} int PyArg_ValidateKeywordArguments (PyObject*)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Ensure that the keys in the keywords argument dictionary are strings.  This
is only needed if @ref{61c,,PyArg_ParseTupleAndKeywords()} is not used, since the
latter already does this check.


在 3.2 版被加入.

@end deffn

@geindex PyArg_Parse (C function)
@anchor{c-api/arg c PyArg_Parse}@anchor{1791}
@deffn {C 函式} int PyArg_Parse (PyObject *args, const char *format, ...)
` 為 @ref{76e,,穩定 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
// Function using METH_O calling convention
static PyObject*
my_function(PyObject *module, PyObject *arg)
@{
    int value;
    if (!PyArg_Parse(arg, "i:my_function", &value)) @{
        return NULL;
    @}
    // ... use value ...
@}
@end example
@end deffn

@geindex PyArg_UnpackTuple (C function)
@anchor{c-api/arg c PyArg_UnpackTuple}@anchor{16fa}
@deffn {C 函式} int PyArg_UnpackTuple (PyObject *args, const char *name, Py_ssize_t min, Py_ssize_t max, ...)
` 為 @ref{76e,,穩定 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{16fc,,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{5d7,,PyObject}* variable; these will be filled in with the values from
`args'; they will contain @ref{3d5,,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{16fa,,PyArg_UnpackTuple()} in this example is entirely equivalent to
this call to @ref{3bf,,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{61e}
@deffn {C 巨集} PY_CXX_CONST

The value to be inserted, if any, before char *const*
in the `keywords' parameter declaration of
@ref{61c,,PyArg_ParseTupleAndKeywords()} and
@ref{61d,,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}.


在 3.13 版被加入.

@end deffn

@node 建置數值,,剖析引數<2>,剖析引數與建置數值
@anchor{c-api/arg building-values}@anchor{5032}
@subsubsection 建置數值


@geindex Py_BuildValue (C function)
@anchor{c-api/arg c Py_BuildValue}@anchor{3c0}
@deffn {C 函式} @ref{5d7,,PyObject} *Py_BuildValue (const char *format, ...)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{3c0,,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{3c0,,Py_BuildValue()}.  In other words, if your code invokes @code{malloc()}
and passes the allocated memory to @ref{3c0,,Py_BuildValue()}, your code is
responsible for calling @code{free()} for that memory once
@ref{3c0,,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{169,,str} 或 @code{None}) [const char *]

Convert a null-terminated C string to a Python @ref{169,,str} object using @code{'utf-8'}
encoding. If the C string pointer is @code{NULL}, @code{None} is used.

@item @code{s#} (@ref{169,,str} 或 @code{None}) [const char *, @ref{c4c,,Py_ssize_t}]

Convert a C string and its length to a Python @ref{169,,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{192,,bytes}) [const char *]

This converts a C string to a Python @ref{192,,bytes} object.  If the C
string pointer is @code{NULL}, @code{None} is returned.

@item @code{y#} (@ref{192,,bytes}) [const char *, @ref{c4c,,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{169,,str} 或 @code{None}) [const char *]

和 @code{s} 相同。

@item @code{z#} (@ref{169,,str} 或 @code{None}) [const char *, @ref{c4c,,Py_ssize_t}]

和 @code{s#} 相同。

@item @code{u} (@ref{169,,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{169,,str}) [const wchar_t *, @ref{c4c,,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{169,,str} 或 @code{None}) [const char *]

和 @code{s} 相同。

@item @code{U#} (@ref{169,,str} 或 @code{None}) [const char *, @ref{c4c,,Py_ssize_t}]

和 @code{s#} 相同。

@item @code{i} (@ref{19b,,int}) [int]

將一個 C 的 int 轉換成 Python 整數物件。

@item @code{b} (@ref{19b,,int}) [char]

將一個 C 的 char 轉換成 Python 整數物件。

@item @code{h} (@ref{19b,,int}) [short int]

將一個 C 的 short int 轉換成 Python 整數物件。

@item @code{l} (@ref{19b,,int}) [long int]

將一個 C 的 long int 轉換成 Python 整數物件。

@item @code{B} (@ref{19b,,int}) [unsigned char]

將一個 C 的 unsigned char 轉換成 Python 整數物件。

@item @code{H} (@ref{19b,,int}) [unsigned short int]

將一個 C 的 unsigned short int 轉換成 Python 整數物件。

@item @code{I} (@ref{19b,,int}) [unsigned int]

將一個 C 的 unsigned int 轉換成 Python 整數物件。

@item @code{k} (@ref{19b,,int}) [unsigned long]

將一個 C 的 unsigned long 轉換成 Python 整數物件。

@item @code{L} (@ref{19b,,int}) [long long]

將一個 C 的 long long 轉換成 Python 整數物件。
@end table
@anchor{c-api/arg capi-py-buildvalue-format-k}@anchor{17e6}

@table @asis

@item @code{K} (@ref{19b,,int}) [unsigned long long]

將一個 C 的 unsigned long long 轉換成 Python 整數物件。

@item @code{n} (@ref{19b,,int}) [@ref{c4c,,Py_ssize_t}]

將一個 C 的 @ref{c4c,,Py_ssize_t} 轉換成 Python 整數。

@item @code{p} (@ref{3c1,,bool}) [int]

將一個 C 的 int 轉換成 Python @ref{3c1,,bool} 物件。

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


在 3.14 版被加入.


@item @code{c} (長度為 1 的 @ref{192,,bytes}) [char]

將一個 C 中代表一個位元組的 int 轉換成 Python 中長度為一的 @ref{192,,bytes}。

@item @code{C} (長度為 1 的 @ref{169,,str}) [int]

將一個 C 中代表一個字元的 int 轉換成 Python 中長度為一的 @ref{169,,str}。

@item @code{d} (@ref{196,,float}) [double]

將一個 C 的 double 轉換成 Python 浮點數。

@item @code{f} (@ref{196,,float}) [float]

將一個 C 的 float 轉換成 Python 浮點數。

@item @code{D} (@ref{197,,complex}) [Py_complex *]

將一個 C 的 @ref{502d,,Py_complex} 結構轉換成 Python 複數。

@item @code{O} (object) [PyObject *]

Pass a Python object untouched but create a new
@ref{5da,,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{3c0,,Py_BuildValue()} will return @code{NULL} but won't
raise an exception.  If no exception has been raised yet, @ref{78e,,SystemError} is
set.

@item @code{S} (object) [PyObject *]

和 @code{O} 相同。

@item @code{N} (object) [PyObject *]

Same as @code{O}, except it doesn't create a new @ref{5da,,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{60c,,tuple}) [`matching-items']

Convert a sequence of C values to a Python tuple with the same number of items.

@item @code{[items]} (@ref{24d,,list}) [`matching-items']

Convert a sequence of C values to a Python list with the same number of items.

@item @code{@{items@}} (@ref{183,,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{78e,,SystemError} exception is
set and @code{NULL} returned.
@end deffn

@geindex Py_VaBuildValue (C function)
@anchor{c-api/arg c Py_VaBuildValue}@anchor{4f9b}
@deffn {C 函式} @ref{5d7,,PyObject} *Py_VaBuildValue (const char *format, va_list vargs)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Identical to @ref{3c0,,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 字串轉換與格式化,PyHash API,剖析引數與建置數值,工具
@anchor{c-api/conversion doc}@anchor{5033}@anchor{c-api/conversion string-conversion}@anchor{5034}@anchor{c-api/conversion string-conversion-and-formatting}@anchor{5035}@anchor{c-api/conversion translation-repo}@anchor{5036}
@subsection 字串轉換與格式化


用於數字轉換和格式化字串輸出的函式。

@geindex PyOS_snprintf (C function)
@anchor{c-api/conversion c PyOS_snprintf}@anchor{16fd}
@deffn {C 函式} int PyOS_snprintf (char *str, size_t size, const char *format, ...)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
根據格式字串 `format' 和額外引數，輸出不超過 `size' 位元組給 `str'。請參閱 Unix 使用手冊 @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{16fe}
@deffn {C 函式} int PyOS_vsnprintf (char *str, size_t size, const char *format, va_list va)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
根據格式字串 `format' 和變數引數串列 `va'，輸出不超過 `size' 位元組給 `str'。Unix 使用手冊 @code{vsnprintf(3)@footnote{https://manpages.debian.org/vsnprintf(3)}}。
@end deffn

@ref{16fd,,PyOS_snprintf()} 和 @ref{16fe,,PyOS_vsnprintf()} 包裝標準 C 函式庫函式 @code{snprintf()} 和 @code{vsnprintf()}。它們的目的是確保邊角案例 (corner case) 下的行為一致，而標準 C 函式則不然。

包裝器確保回傳時 @code{str[size-1]} 始終為 @code{'\0'}。他們永遠不會在 str 中寫入超過 `size' 位元組（包括尾隨的 @code{'\0'}）。這兩個函式都要求 @code{str != NULL}、@code{size > 0}、@code{format != NULL} 和 @code{size < INT_MAX}。請注意，這表示沒有與 C99 @code{n = snprintf(NULL, 0, ...)} 等效的函式來決定必要的緩衝區大小。

這些函式的回傳值 (`rv') 應如下被直譯：


@itemize *

@item 
當 @code{0 <= rv < size} 時，輸出轉換成功，`rv' 字元被寫入 `str'（不包括 @code{str[rv]} 處的尾隨 @code{'\0'} 位元組）。

@item 
當 @code{rv >= size} 時，輸出轉換被截斷，並且需要具有 @code{rv + 1} 位元組的緩衝區才能成功。在這種情況下，@code{str[size-1]} 是 @code{'\0'}。

@item 
當 @code{rv < 0} 時，代表「有不好的事情發生了」。在這種情況下，@code{str[size-1]} 也是 @code{'\0'}，但 `str' 的其餘部分未定義。錯誤的確切原因取決於底層平台。
@end itemize

以下函式提供與區域設定無關 (locale-independent) 的字串到數字的轉換。

@geindex PyOS_strtoul (C function)
@anchor{c-api/conversion c PyOS_strtoul}@anchor{4f07}
@deffn {C 函式} unsigned long PyOS_strtoul (const char *str, char **ptr, int base)
` 為 @ref{76e,,穩定 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.

也請見 Unix 使用手冊 @code{strtoul(3)@footnote{https://manpages.debian.org/strtoul(3)}}。


在 3.2 版被加入.

@end deffn

@geindex PyOS_strtol (C function)
@anchor{c-api/conversion c PyOS_strtol}@anchor{4f06}
@deffn {C 函式} long PyOS_strtol (const char *str, char **ptr, int base)
` 為 @ref{76e,,穩定 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{4f07,,PyOS_strtoul()}, but return a long value instead
and @code{LONG_MAX} on overflows.

也請見 Unix 使用手冊 @code{strtol(3)@footnote{https://manpages.debian.org/strtol(3)}}。


在 3.2 版被加入.

@end deffn

@geindex PyOS_string_to_double (C function)
@anchor{c-api/conversion c PyOS_string_to_double}@anchor{1496}
@deffn {C 函式} double PyOS_string_to_double (const char *s, char **endptr, PyObject *overflow_exception)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
將字串 @code{s} 轉換為 double，失敗時引發 Python 例外。接受的字串集合對應於 Python 的 @ref{196,,float()} 建構函式接受的字串集合，但 @code{s} 不得有前導或尾隨的空格。轉換與目前區域設定無關。

如果 @code{endptr} 為 @code{NULL}，則轉換整個字串。如果字串不是浮點數的有效表示，則引發 @ref{2eb,,ValueError} 並回傳 @code{-1.0}。

如果 endptr 不是 @code{NULL}，則盡可能轉換字串，並將 @code{*endptr} 設定為指向第一個未轉換的字元。如果字串的初始片段都不是浮點數的有效表示，則設定 @code{*endptr} 指向字串的開頭，引發 ValueError 並回傳 @code{-1.0}。

如果 @code{s} 表示的值太大而無法儲存在浮點數中（例如 @code{"1e500"} 在許多平台上都是這樣的字串），如果 @code{overflow_exception} 為 @code{NULL} 則回傳 @code{Py_INFINITY}（會帶有適當的符號）並且不設定任何例外。否則， @code{overflow_exception} 必須指向一個 Python 例外物件；引發該例外並回傳 @code{-1.0}。在這兩種情況下，將 @code{*endptr} 設定為指向轉換後的值之後的第一個字元。

如果轉換期間發生任何其他錯誤（例如記憶體不足的錯誤），請設定適當的 Python 例外並回傳 @code{-1.0}。


在 3.1 版被加入.

@end deffn

@geindex PyOS_double_to_string (C function)
@anchor{c-api/conversion c PyOS_double_to_string}@anchor{4f04}
@deffn {C 函式} char *PyOS_double_to_string (double val, char format_code, int precision, int flags, int *ptype)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
使用提供的 `format_code'、`precision' 和 `flags' 將 double `val' 轉換為字串。

`format_code' 必須是 @code{'e'}、@code{'E'}、@code{'f'}、@code{'F'}、@code{'g'}、@code{'G'} 或 @code{'r'} 其中之一。對於 @code{'r'}，提供的 `precision' 必須為 0 並會被忽略。@code{'r'} 格式碼指定標準 @ref{1c1,,repr()} 格式。

`flags' 可以是零個或多個值 @code{Py_DTSF_SIGN}、@code{Py_DTSF_ADD_DOT_0} 或 @code{Py_DTSF_ALT}，會被聯集在一起：


@itemize *

@item 
@code{Py_DTSF_SIGN} 代表總是在回傳的字串前面加上符號字元，即使 `val' 非負數。

@item 
@code{Py_DTSF_ADD_DOT_0} 代表確保回傳的字串看起來不會像整數。

@item 
@code{Py_DTSF_ALT} 代表要套用「備用的 (alternate)」格式化規則。有關詳細資訊，請參閱 @ref{16fd,,PyOS_snprintf()} @code{'#'} 的文件。
@end itemize

如果 `ptype' 是非 @code{NULL}，那麼它指向的值將被設定為 @code{Py_DTST_FINITE}、@code{Py_DTST_INFINITE} 或 @code{Py_DTST_NAN} 其中之一，分別代表 `val' 是有限數、無限數或非數。

回傳值是指向 `buffer' 的指標，其中包含轉換後的字串，如果轉換失敗則回傳 @code{NULL}。呼叫者負責透過呼叫 @ref{1639,,PyMem_Free()} 來釋放回傳的字串。


在 3.1 版被加入.

@end deffn

@geindex PyOS_stricmp (C function)
@anchor{c-api/conversion c PyOS_stricmp}@anchor{5037}
@deffn {C 函式} int PyOS_stricmp (const char *s1, const char *s2)

不區分大小寫的字串比較。函式的作用方式幾乎與 @code{strcmp()} 相同，只是它忽略大小寫。
@end deffn

@geindex PyOS_strnicmp (C function)
@anchor{c-api/conversion c PyOS_strnicmp}@anchor{5038}
@deffn {C 函式} int PyOS_strnicmp (const char *s1, const char *s2, Py_ssize_t size)

不區分大小寫的字串比較。函式的作用方式幾乎與 @code{strncmp()} 相同，只是它忽略大小寫。
@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,字串轉換與格式化,工具
@anchor{c-api/hash doc}@anchor{5039}@anchor{c-api/hash pyhash-api}@anchor{503a}@anchor{c-api/hash translation-repo}@anchor{503b}
@subsection PyHash API


另請參閱 @ref{4dbe,,PyTypeObject.tp_hash} 成員和 @ref{24ae,,數值型別的雜湊}。

@geindex Py_hash_t (C type)
@anchor{c-api/hash c Py_hash_t}@anchor{1464}
@deffn {C 型別} type Py_hash_t

雜湊值型別：有符號整數。


在 3.2 版被加入.

@end deffn

@geindex Py_uhash_t (C type)
@anchor{c-api/hash c Py_uhash_t}@anchor{503c}
@deffn {C 型別} type Py_uhash_t

雜湊值型別：無符號整數。


在 3.2 版被加入.

@end deffn

@geindex PyHASH_MODULUS (C macro)
@anchor{c-api/hash c PyHASH_MODULUS}@anchor{1937}
@deffn {C 巨集} PyHASH_MODULUS

用於數值雜湊方案的梅森質數 (Mersenne prime)@footnote{https://en.wikipedia.org/wiki/Mersenne_prime} @code{P = 2**n -1}。


在 3.13 版被加入.

@end deffn

@geindex PyHASH_BITS (C macro)
@anchor{c-api/hash c PyHASH_BITS}@anchor{1938}
@deffn {C 巨集} PyHASH_BITS

@ref{1937,,PyHASH_MODULUS} 中 @code{P} 的指數 @code{n}。


在 3.13 版被加入.

@end deffn

@geindex PyHASH_MULTIPLIER (C macro)
@anchor{c-api/hash c PyHASH_MULTIPLIER}@anchor{18ed}
@deffn {C 巨集} PyHASH_MULTIPLIER

用於字串和其他各種雜湊的質數乘數 (prime multiplier)。


在 3.13 版被加入.

@end deffn

@geindex PyHASH_INF (C macro)
@anchor{c-api/hash c PyHASH_INF}@anchor{1939}
@deffn {C 巨集} PyHASH_INF

正無窮大回傳的雜湊值。


在 3.13 版被加入.

@end deffn

@geindex PyHASH_IMAG (C macro)
@anchor{c-api/hash c PyHASH_IMAG}@anchor{193a}
@deffn {C 巨集} PyHASH_IMAG

用於複數虛數部分的乘數。


在 3.13 版被加入.

@end deffn

@geindex PyHash_FuncDef (C type)
@anchor{c-api/hash c PyHash_FuncDef}@anchor{503d}
@deffn {C 型別} type PyHash_FuncDef

@ref{503e,,PyHash_GetFuncDef()} 所使用的雜湊函式定義。

@geindex PyHash_FuncDef.hash (C member)
@anchor{c-api/hash c PyHash_FuncDef hash}@anchor{503f}
@deffn {C 成員函數} @ref{1464,,Py_hash_t} (*const hash)(const void*, @ref{c4c,,Py_ssize_t})

雜湊函式。
@end deffn

@geindex PyHash_FuncDef.name (C member)
@anchor{c-api/hash c PyHash_FuncDef name}@anchor{5040}
@deffn {C 成員函數} const char *name

雜湊函式名稱（UTF-8 編碼字串）。
@end deffn

@geindex PyHash_FuncDef.hash_bits (C member)
@anchor{c-api/hash c PyHash_FuncDef hash_bits}@anchor{5041}
@deffn {C 成員函數} const int hash_bits

雜湊值的內部大小（以位元為單位）。
@end deffn

@geindex PyHash_FuncDef.seed_bits (C member)
@anchor{c-api/hash c PyHash_FuncDef seed_bits}@anchor{5042}
@deffn {C 成員函數} const int seed_bits

Seed 輸入的大小（以位元為單位）。
@end deffn


在 3.4 版被加入.

@end deffn

@geindex PyHash_GetFuncDef (C function)
@anchor{c-api/hash c PyHash_GetFuncDef}@anchor{503e}
@deffn {C 函式} @ref{503d,,PyHash_FuncDef} *PyHash_GetFuncDef (void)

取得雜湊函式定義。


@subsubheading 也參考


@geindex Python Enhancement Proposals; PEP 456
PEP 456@footnote{https://peps.python.org/pep-0456/}「安全且可交替使用的雜湊演算法 (Secure and interchangeable hash algorithm)」。



在 3.4 版被加入.

@end deffn

@geindex Py_HashPointer (C function)
@anchor{c-api/hash c Py_HashPointer}@anchor{423}
@deffn {C 函式} @ref{1464,,Py_hash_t} Py_HashPointer (const void *ptr)

雜湊指標值：將指標值作為整數處理（在內部轉型為 @code{uintptr_t}）。指標不會被取值 (dereference)。

此函式不會失敗：它不會回傳 @code{-1}。


在 3.13 版被加入.

@end deffn

@geindex Py_HashBuffer (C function)
@anchor{c-api/hash c Py_HashBuffer}@anchor{393}
@deffn {C 函式} @ref{1464,,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{192,,bytes}, @ref{165,,memoryview}, and other built-in objects
that implement the @ref{260,,buffer protocol}.

Use this function to implement hashing for immutable objects whose
@ref{4db8,,tp_richcompare} function compares to another
object's buffer.

`len' 必須大於或等於 @code{0}。

此函式總是會成功執行。


在 3.14 版被加入.

@end deffn

@geindex PyObject_GenericHash (C function)
@anchor{c-api/hash c PyObject_GenericHash}@anchor{604}
@deffn {C 函式} @ref{1464,,Py_hash_t} PyObject_GenericHash (PyObject *obj)

泛用雜湊函式，旨在放入型別物件的 @code{tp_hash} 插槽中。其結果僅取決於物件的識別性。

在 CPython 中，它等價於 @ref{423,,Py_HashPointer()}。


在 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,編解碼器註冊表和支援函式,PyHash API,工具
@anchor{c-api/reflection doc}@anchor{5043}@anchor{c-api/reflection id1}@anchor{5044}@anchor{c-api/reflection reflection}@anchor{5045}@anchor{c-api/reflection translation-repo}@anchor{5046}
@subsection Reflection


@geindex PyEval_GetBuiltins (C function)
@anchor{c-api/reflection c PyEval_GetBuiltins}@anchor{5ec}
@deffn {C 函式} @ref{5d7,,PyObject} *PyEval_GetBuiltins (void)
`回傳值：借用參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'

在 3.13 版之後被棄用: Use @ref{5eb,,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{5f0}
@deffn {C 函式} @ref{5d7,,PyObject} *PyEval_GetLocals (void)
`回傳值：借用參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'

在 3.13 版之後被棄用: Use either @ref{5ef,,PyEval_GetFrameLocals()} to obtain the same behaviour as calling
@ref{469,,locals()} in Python code, or else call @ref{659,,PyFrame_GetLocals()} on the result
of @ref{1a78,,PyEval_GetFrame()} to access the @ref{4a0,,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{469,,locals()} for details of the mapping returned at different scopes.

As this function returns a @ref{3d5,,borrowed reference}, the dictionary returned for
@ref{49c,,optimized scopes} is cached on the frame object and will remain
alive as long as the frame object does. Unlike @ref{5ef,,PyEval_GetFrameLocals()} and
@ref{469,,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{659,,PyFrame_GetLocals()}, @ref{469,,locals()}, and
@ref{4a0,,FrameType.f_locals} no longer make use of the shared cache
dictionary. Refer to the @ref{46a,,What's New entry} for
additional details.

@end deffn

@geindex PyEval_GetGlobals (C function)
@anchor{c-api/reflection c PyEval_GetGlobals}@anchor{5ee}
@deffn {C 函式} @ref{5d7,,PyObject} *PyEval_GetGlobals (void)
`回傳值：借用參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'

在 3.13 版之後被棄用: Use @ref{5ed,,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{1a78}
@deffn {C 函式} @ref{984,,PyFrameObject} *PyEval_GetFrame (void)
`回傳值：借用參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return the @ref{4d99,,attached thread state}'s frame, which is @code{NULL} if no frame is
currently executing.

另請見 @ref{989,,PyThreadState_GetFrame()}。
@end deffn

@geindex PyEval_GetFrameBuiltins (C function)
@anchor{c-api/reflection c PyEval_GetFrameBuiltins}@anchor{5eb}
@deffn {C 函式} @ref{5d7,,PyObject} *PyEval_GetFrameBuiltins (void)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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.


在 3.13 版被加入.

@end deffn

@geindex PyEval_GetFrameLocals (C function)
@anchor{c-api/reflection c PyEval_GetFrameLocals}@anchor{5ef}
@deffn {C 函式} @ref{5d7,,PyObject} *PyEval_GetFrameLocals (void)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{469,,locals()} in Python code.

To access @ref{4a0,,f_locals} on the current frame without making an independent
snapshot in @ref{49c,,optimized scopes}, call @ref{659,,PyFrame_GetLocals()}
on the result of @ref{1a78,,PyEval_GetFrame()}.


在 3.13 版被加入.

@end deffn

@geindex PyEval_GetFrameGlobals (C function)
@anchor{c-api/reflection c PyEval_GetFrameGlobals}@anchor{5ed}
@deffn {C 函式} @ref{5d7,,PyObject} *PyEval_GetFrameGlobals (void)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{1b1e,,globals()} in Python code.


在 3.13 版被加入.

@end deffn

@geindex PyEval_GetFuncName (C function)
@anchor{c-api/reflection c PyEval_GetFuncName}@anchor{4e69}
@deffn {C 函式} const char *PyEval_GetFuncName (PyObject *func)
` 為 @ref{76e,,穩定 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{4e68}
@deffn {C 函式} const char *PyEval_GetFuncDesc (PyObject *func)
` 為 @ref{76e,,穩定 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{4e69,,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 編解碼器註冊表和支援函式,PyTime C API,Reflection,工具
@anchor{c-api/codec doc}@anchor{5047}@anchor{c-api/codec codec-registry}@anchor{f2b}@anchor{c-api/codec codec-registry-and-support-functions}@anchor{5048}@anchor{c-api/codec translation-repo}@anchor{5049}
@subsection 編解碼器註冊表和支援函式


@geindex PyCodec_Register (C function)
@anchor{c-api/codec c PyCodec_Register}@anchor{4e3e}
@deffn {C 函式} int PyCodec_Register (PyObject *search_function)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
註冊一個新的編解碼器搜尋函式。

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{a8e}
@deffn {C 函式} int PyCodec_Unregister (PyObject *search_function)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.10 版本開始.'
取消註冊編解碼器搜尋函式並清除註冊表 (registry) 的快取。如果搜尋函式並未被註冊，則不執行任何操作。成功回傳 0，發生錯誤時會引發例外並回傳 -1。


在 3.10 版被加入.

@end deffn

@geindex PyCodec_KnownEncoding (C function)
@anchor{c-api/codec c PyCodec_KnownEncoding}@anchor{4e3c}
@deffn {C 函式} int PyCodec_KnownEncoding (const char *encoding)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
回傳 @code{1} 或 @code{0}，具體取決於是否有給定 `encoding' 的已註冊編解碼器。這個函式總會成功。
@end deffn

@geindex PyCodec_Encode (C function)
@anchor{c-api/codec c PyCodec_Encode}@anchor{3e0}
@deffn {C 函式} @ref{5d7,,PyObject} *PyCodec_Encode (PyObject *object, const char *encoding, const char *errors)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
基於泛用編解碼器的編碼 API。

`object' 被傳遞給以給定 `encoding' 所查找到的編碼器函式，並使用以 `errors' 定義的錯誤處理方法。`errors' 可以設為 @code{NULL} 來使用編解碼器定義的預設方法。如果找不到編碼器，則引發 @ref{2500,,LookupError}。
@end deffn

@geindex PyCodec_Decode (C function)
@anchor{c-api/codec c PyCodec_Decode}@anchor{3df}
@deffn {C 函式} @ref{5d7,,PyObject} *PyCodec_Decode (PyObject *object, const char *encoding, const char *errors)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
基於泛用編解碼器的解碼 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{2500,,LookupError} if no decoder can be found.
@end deffn

@menu
* 編解碼器查找 API:: 
* 用於 Unicode 編碼錯誤處理程式的註冊 API:: 

@end menu

@node 編解碼器查找 API,用於 Unicode 編碼錯誤處理程式的註冊 API,,編解碼器註冊表和支援函式
@anchor{c-api/codec codec-lookup-api}@anchor{504a}
@subsubsection 編解碼器查找 API


在以下函式中，查找的 `encoding' 字串的所有字元將轉換為小寫，這使得透過此機制查找的編碼可以不區分大小寫而更有效率。如果未找到編解碼器，則會設定 @ref{5df,,KeyError} 並回傳 @code{NULL}。

@geindex PyCodec_Encoder (C function)
@anchor{c-api/codec c PyCodec_Encoder}@anchor{4e38}
@deffn {C 函式} @ref{5d7,,PyObject} *PyCodec_Encoder (const char *encoding)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
取得給定 `encoding' 的編碼器函式。
@end deffn

@geindex PyCodec_Decoder (C function)
@anchor{c-api/codec c PyCodec_Decoder}@anchor{4e37}
@deffn {C 函式} @ref{5d7,,PyObject} *PyCodec_Decoder (const char *encoding)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
取得給定 `encoding' 的解碼器函式。
@end deffn

@geindex PyCodec_IncrementalEncoder (C function)
@anchor{c-api/codec c PyCodec_IncrementalEncoder}@anchor{4e3b}
@deffn {C 函式} @ref{5d7,,PyObject} *PyCodec_IncrementalEncoder (const char *encoding, const char *errors)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
取得給定 `encoding' 的 @ref{26e3,,IncrementalEncoder} 物件。
@end deffn

@geindex PyCodec_IncrementalDecoder (C function)
@anchor{c-api/codec c PyCodec_IncrementalDecoder}@anchor{4e3a}
@deffn {C 函式} @ref{5d7,,PyObject} *PyCodec_IncrementalDecoder (const char *encoding, const char *errors)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
取得給定 `encoding' 的 @ref{26e4,,IncrementalDecoder} 物件。
@end deffn

@geindex PyCodec_StreamReader (C function)
@anchor{c-api/codec c PyCodec_StreamReader}@anchor{4e41}
@deffn {C 函式} @ref{5d7,,PyObject} *PyCodec_StreamReader (const char *encoding, PyObject *stream, const char *errors)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
取得給定 `encoding' 的 @ref{26e8,,StreamReader} 工廠函式。
@end deffn

@geindex PyCodec_StreamWriter (C function)
@anchor{c-api/codec c PyCodec_StreamWriter}@anchor{4e42}
@deffn {C 函式} @ref{5d7,,PyObject} *PyCodec_StreamWriter (const char *encoding, PyObject *stream, const char *errors)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
取得給定 `encoding' 的 @ref{26e7,,StreamWriter} 工廠函式。
@end deffn

@node 用於 Unicode 編碼錯誤處理程式的註冊 API,,編解碼器查找 API,編解碼器註冊表和支援函式
@anchor{c-api/codec registry-api-for-unicode-encoding-error-handlers}@anchor{504b}
@subsubsection 用於 Unicode 編碼錯誤處理程式的註冊 API


@geindex PyCodec_RegisterError (C function)
@anchor{c-api/codec c PyCodec_RegisterError}@anchor{4e3f}
@deffn {C 函式} int PyCodec_RegisterError (const char *name, PyObject *error)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
在給定的 `name' 下註冊錯誤處理回呼 (callback) 函式 `error'。當編解碼器遇到無法編碼的字元/無法解碼的位元組並且 `name' 被指定為呼叫編碼/解碼函式時的錯誤參數時，將呼叫此回呼函式。

回呼取得單個引數，即 @ref{880,,UnicodeEncodeError}、@ref{bff,,UnicodeDecodeError} 或 @ref{1868,,UnicodeTranslateError} 的實例，其中包含關於有問題的字元或位元組序列及其在原始字串中偏移量的資訊（有關取得此資訊的函式，請參閱 @ref{45f,,Unicode 例外物件}）。回呼必須引發給定的例外，或者回傳一個包含有問題序列的替換的二元組 (two-item tuple)，以及一個代表原始字串中應該被恢復的編碼/解碼偏移量的整數。

成功時回傳 @code{0}，錯誤時回傳 @code{-1}。
@end deffn

@geindex PyCodec_LookupError (C function)
@anchor{c-api/codec c PyCodec_LookupError}@anchor{4e3d}
@deffn {C 函式} @ref{5d7,,PyObject} *PyCodec_LookupError (const char *name)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
查找 `name' 下已註冊的錯誤處理回呼函式。作為一種特殊情況，可以傳遞 @code{NULL}，在這種情況下，將回傳 "strict" 的錯誤處理回呼。
@end deffn

@geindex PyCodec_StrictErrors (C function)
@anchor{c-api/codec c PyCodec_StrictErrors}@anchor{4e43}
@deffn {C 函式} @ref{5d7,,PyObject} *PyCodec_StrictErrors (PyObject *exc)
`回傳值：總是為 NULL。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
引發 `exc' 作為例外。
@end deffn

@geindex PyCodec_IgnoreErrors (C function)
@anchor{c-api/codec c PyCodec_IgnoreErrors}@anchor{4e39}
@deffn {C 函式} @ref{5d7,,PyObject} *PyCodec_IgnoreErrors (PyObject *exc)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
忽略 unicode 錯誤，跳過錯誤的輸入。
@end deffn

@geindex PyCodec_ReplaceErrors (C function)
@anchor{c-api/codec c PyCodec_ReplaceErrors}@anchor{4e40}
@deffn {C 函式} @ref{5d7,,PyObject} *PyCodec_ReplaceErrors (PyObject *exc)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
將 unicode 編碼錯誤替換為 @code{?} 或 @code{U+FFFD}。
@end deffn

@geindex PyCodec_XMLCharRefReplaceErrors (C function)
@anchor{c-api/codec c PyCodec_XMLCharRefReplaceErrors}@anchor{4e44}
@deffn {C 函式} @ref{5d7,,PyObject} *PyCodec_XMLCharRefReplaceErrors (PyObject *exc)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
將 unicode 編碼錯誤替換為 XML 字元參照。
@end deffn

@geindex PyCodec_BackslashReplaceErrors (C function)
@anchor{c-api/codec c PyCodec_BackslashReplaceErrors}@anchor{4e36}
@deffn {C 函式} @ref{5d7,,PyObject} *PyCodec_BackslashReplaceErrors (PyObject *exc)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
將 unicode 編碼錯誤替換為反斜線跳脫（@code{\x}、@code{\u} 和 @code{\U}）。
@end deffn

@geindex PyCodec_NameReplaceErrors (C function)
@anchor{c-api/codec c PyCodec_NameReplaceErrors}@anchor{10aa}
@deffn {C 函式} @ref{5d7,,PyObject} *PyCodec_NameReplaceErrors (PyObject *exc)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.7 版本開始.'
將 unicode 編碼錯誤替換為 @code{\N@{...@}} 跳脫。


在 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 PyTime C API,對 Perf Map 的支援,編解碼器註冊表和支援函式,工具
@anchor{c-api/time doc}@anchor{47e}@anchor{c-api/time c-api-time}@anchor{5ca}@anchor{c-api/time pytime-c-api}@anchor{504c}@anchor{c-api/time translation-repo}@anchor{504d}
@subsection PyTime C API



在 3.13 版被加入.


時鐘 C API 提供對系統時鐘的存取。它類似於 Python 的 @ref{f4,,time} 模組。

對於與 @ref{34,,datetime} 模組相關的 C API，請參閱 @ref{504e,,DateTime 物件}。

@menu
* 型別: 型別<2>. 
* 時鐘函式:: 
* 原始時鐘函式:: 
* 轉換函式:: 

@end menu

@node 型別<2>,時鐘函式,,PyTime C API
@anchor{c-api/time types}@anchor{504f}
@subsubsection 型別


@geindex PyTime_t (C type)
@anchor{c-api/time c PyTime_t}@anchor{5cb}
@deffn {C 型別} type PyTime_t

以奈秒為單位的時間戳記或持續時長，以有符號的 64 位元整數表示。

時間戳記的參照點取決於所使用的時鐘。例如 @ref{5d3,,PyTime_Time()} 回傳相對於 UNIX 紀元 (UNIX epoch) 的時間戳記。

支援的範圍約為 [-292.3 年；+292.3 年]。以 Unix 紀元 (1970 年 1 月 1 日) 為參照，支援的日期範圍約為 [1677-09-21; 2262-04-11]。確切的限制是以常數的形式公開出來：
@end deffn

@geindex PyTime_MIN (C var)
@anchor{c-api/time c PyTime_MIN}@anchor{5cc}
@deffn {C 變數} @ref{5cb,,PyTime_t} PyTime_MIN

@ref{5cb,,PyTime_t} 的最小值。
@end deffn

@geindex PyTime_MAX (C var)
@anchor{c-api/time c PyTime_MAX}@anchor{5cd}
@deffn {C 變數} @ref{5cb,,PyTime_t} PyTime_MAX

@ref{5cb,,PyTime_t} 的最大值。
@end deffn

@node 時鐘函式,原始時鐘函式,型別<2>,PyTime C API
@anchor{c-api/time clock-functions}@anchor{5050}
@subsubsection 時鐘函式


以下的函式接受一個指向 @ref{5cb,,PyTime_t} 的指標，並將其設定為特定時鐘的值。每個時鐘的詳細資訊紀錄在相對應的 Python 函式說明文件中。

函式成功時會回傳 @code{0} 或在失敗時回傳 @code{-1}（並設定一個例外）。

在整數溢位時，它們會設定 @ref{4e92,,PyExc_OverflowError} 例外，並將 @code{*result} 設定為夾在 @code{[PyTime_MIN; PyTime_MAX]} 範圍內的值。（在目前的系統上，整數溢位很可能是由於錯誤設定的系統時間所造成。）

如同任何其他 C API（除非另有指定），必須在具有 @ref{4d99,,attached thread state} 的情況下呼叫函式。

@geindex PyTime_Monotonic (C function)
@anchor{c-api/time c PyTime_Monotonic}@anchor{5cf}
@deffn {C 函式} int PyTime_Monotonic (PyTime_t *result)

讀取單調時鐘。請參閱 @ref{556,,time.monotonic()} 取得此時鐘的重要詳細資訊。
@end deffn

@geindex PyTime_PerfCounter (C function)
@anchor{c-api/time c PyTime_PerfCounter}@anchor{5d1}
@deffn {C 函式} int PyTime_PerfCounter (PyTime_t *result)

讀取效能計數器。請參閱 @ref{c71,,time.perf_counter()} 以取得此時鐘的重要詳細資訊。
@end deffn

@geindex PyTime_Time (C function)
@anchor{c-api/time c PyTime_Time}@anchor{5d3}
@deffn {C 函式} int PyTime_Time (PyTime_t *result)

讀取「牆上時鐘 (wall clock)」的時間。請參閱 @ref{557,,time.time()} 以取得詳細資訊。
@end deffn

@node 原始時鐘函式,轉換函式,時鐘函式,PyTime C API
@anchor{c-api/time raw-clock-functions}@anchor{5051}
@subsubsection 原始時鐘函式


類似於時鐘函式，但不會在出錯時設定例外，也不需要呼叫者擁有 @ref{4d99,,attached thread state}。

成功時函式會回傳 @code{0}。

失敗時，它們會將 @code{*result} 設為 @code{0} 並回傳 @code{-1}, 而`不'設定例外。要取得錯誤原因，請@ref{4d99,,附加}一個 @ref{17c4,,thread state}，並呼叫常規（非 @code{Raw}）函式。請注意，常規函式可能會在 @code{Raw} 的函式失敗後成功。

@geindex PyTime_MonotonicRaw (C function)
@anchor{c-api/time c PyTime_MonotonicRaw}@anchor{5d0}
@deffn {C 函式} int PyTime_MonotonicRaw (PyTime_t *result)

類似於 @ref{5cf,,PyTime_Monotonic()}，但不會在錯誤時設定例外，也不需要擁有 @ref{4d99,,attached thread state}。
@end deffn

@geindex PyTime_PerfCounterRaw (C function)
@anchor{c-api/time c PyTime_PerfCounterRaw}@anchor{5d2}
@deffn {C 函式} int PyTime_PerfCounterRaw (PyTime_t *result)

類似於 @ref{5d1,,PyTime_PerfCounter()}，但不會在錯誤時設定例外，也不需要擁有 @ref{4d99,,attached thread state}。
@end deffn

@geindex PyTime_TimeRaw (C function)
@anchor{c-api/time c PyTime_TimeRaw}@anchor{5d4}
@deffn {C 函式} int PyTime_TimeRaw (PyTime_t *result)

類似於 @ref{5d3,,PyTime_Time()}，但不會在錯誤時設定例外，也不需要擁有 @ref{4d99,,attached thread state}。
@end deffn

@node 轉換函式,,原始時鐘函式,PyTime C API
@anchor{c-api/time conversion-functions}@anchor{5052}
@subsubsection 轉換函式


@geindex PyTime_AsSecondsDouble (C function)
@anchor{c-api/time c PyTime_AsSecondsDouble}@anchor{5ce}
@deffn {C 函式} double PyTime_AsSecondsDouble (PyTime_t t)

將時間戳記轉換為 C double 的秒數。

此函式不會失敗，但請注意 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 對 Perf Map 的支援,,PyTime C API,工具
@anchor{c-api/perfmaps doc}@anchor{5053}@anchor{c-api/perfmaps perfmaps}@anchor{5054}@anchor{c-api/perfmaps support-for-perf-maps}@anchor{5055}@anchor{c-api/perfmaps translation-repo}@anchor{5056}
@subsection 對 Perf Map 的支援


在支援的平台上（截至撰寫本文時，僅限 Linux），runtime 可以利用 `perf map 檔案'使得外部分析工具（例如 perf@footnote{https://perf.wiki.kernel.org/index.php/Main_Page}）可以見到 Python 函式。正在運行的行程可能會在 @code{/tmp} 目錄中建立一個檔案，其中包含可以將一段可執行程式碼對映到名稱的各個條目。此介面在 Linux Perf 工具的文件@footnote{https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/perf/Documentation/jit-interface.txt}中有被描述。

在 Python 中，這些輔助 API 可以被依賴於運行期間 (on the fly) 產生機器碼的函式庫和功能所使用。

請注意，這些 API 不需要持有 @ref{4d99,,attached thread state}。

@geindex PyUnstable_PerfMapState_Init (C function)
@anchor{c-api/perfmaps c PyUnstable_PerfMapState_Init}@anchor{19f9}
@deffn {C 函式} int PyUnstable_PerfMapState_Init (void)

@cartouche
@quotation 這是 不穩定 API，它可能在小版本發布中沒有任何警告地被變更。 `這是 @ref{762,,不穩定 API}，它可能在小版本發布中沒有任何警告地被變更。'
@end quotation
@end cartouche

打開 @code{/tmp/perf-$pid.map} 檔案，除非它已經打開，並建立一個鎖以確保執行緒安全地 (thread-safe) 寫入該檔案（前提是寫入是透過 @ref{19f8,,PyUnstable_WritePerfMapEntry()} 完成的）。通常不需要明確地呼叫它；只需使用 @ref{19f8,,PyUnstable_WritePerfMapEntry()} 它就會在首次呼叫時初始化狀態。

建立/打開 perf map 檔案成功時回傳 @code{0}，失敗時回傳 @code{-1}，建立鎖時失敗則回傳 @code{-2}。檢查 @code{errno} 以取得更多造成失敗的資訊。
@end deffn

@geindex PyUnstable_WritePerfMapEntry (C function)
@anchor{c-api/perfmaps c PyUnstable_WritePerfMapEntry}@anchor{19f8}
@deffn {C 函式} int PyUnstable_WritePerfMapEntry (const void *code_addr, unsigned int code_size, const char *entry_name)

@cartouche
@quotation 這是 不穩定 API，它可能在小版本發布中沒有任何警告地被變更。 `這是 @ref{762,,不穩定 API}，它可能在小版本發布中沒有任何警告地被變更。'
@end quotation
@end cartouche

將單一條目寫入 @code{/tmp/perf-$pid.map} 檔案。此函式是執行緒安全的。以下是一個條目的範例：

@example
# 位址        大小  名稱
7f3529fcf759 b     py::bar:/run/t.py
@end example

如果尚未開啟 perf map 檔案，將在寫入條目之前呼叫 @ref{19f9,,PyUnstable_PerfMapState_Init()}。成功時回傳 @code{0}，失敗時回傳與 @ref{19f9,,PyUnstable_PerfMapState_Init()} 失敗時相同的錯誤碼。
@end deffn

@geindex PyUnstable_PerfMapState_Fini (C function)
@anchor{c-api/perfmaps c PyUnstable_PerfMapState_Fini}@anchor{19fa}
@deffn {C 函式} void PyUnstable_PerfMapState_Fini (void)

@cartouche
@quotation 這是 不穩定 API，它可能在小版本發布中沒有任何警告地被變更。 `這是 @ref{762,,不穩定 API}，它可能在小版本發布中沒有任何警告地被變更。'
@end quotation
@end cartouche

關閉由 @ref{19f9,,PyUnstable_PerfMapState_Init()} 開啟的 perf map 檔案，這是在直譯器關閉期間由 runtime 本身呼叫的。一般來說，除了處理 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,具體物件層,工具,Python/C API 參考手冊
@anchor{c-api/abstract doc}@anchor{5057}@anchor{c-api/abstract abstract}@anchor{4dbb}@anchor{c-api/abstract abstract-objects-layer}@anchor{5058}@anchor{c-api/abstract translation-repo}@anchor{5059}
@section 抽象物件層 (Abstract Objects Layer)


本章中的函式與 Python 物件相互作用，無論其型別、或具有廣泛類別的物件型別（例如所有數值型別或所有序列型別）。當使用於不適用的物件型別時，他們會引發一個 Python 異常 (exception)。

這些函式是不可能用於未正確初始化的物件（例如一個由 @ref{4dfa,,PyList_New()} 建立的 list 物件），而其中的項目沒有被設為一些非 @code{NULL} 的值。

@menu
* 物件協定:: 
* 呼叫協定 (Call Protocol): 呼叫協定 Call Protocol. 
* 數字協定:: 
* 序列協定:: 
* 對映協定:: 
* 疊代器協定:: 
* 緩衝協定 (Buffer Protocol): 緩衝協定 Buffer Protocol. 

@end menu

@node 物件協定,呼叫協定 Call Protocol,,抽象物件層 Abstract Objects Layer
@anchor{c-api/object doc}@anchor{505a}@anchor{c-api/object object}@anchor{505b}@anchor{c-api/object object-protocol}@anchor{505c}
@subsection 物件協定


@geindex Py_GetConstant (C function)
@anchor{c-api/object c Py_GetConstant}@anchor{5f1}
@deffn {C 函式} @ref{5d7,,PyObject} *Py_GetConstant (unsigned int constant_id)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.13 版本開始.'
Get a @ref{5da,,strong reference} to a constant.

如果 `constant_id' 無效，則設定一個例外並回傳 @code{NULL}。

`constant_id' 必須是這些常數識別字之一：


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

常數識別字

@tab

數值

@tab

回傳物件

@item

@geindex Py_CONSTANT_NONE (C macro)
@anchor{c-api/object c Py_CONSTANT_NONE}@anchor{505d}
@deffn {C 巨集} Py_CONSTANT_NONE
@end deffn

@tab

@code{0}

@tab

@ref{87e,,None}

@item

@geindex Py_CONSTANT_FALSE (C macro)
@anchor{c-api/object c Py_CONSTANT_FALSE}@anchor{505e}
@deffn {C 巨集} Py_CONSTANT_FALSE
@end deffn

@tab

@code{1}

@tab

@ref{d23,,False}

@item

@geindex Py_CONSTANT_TRUE (C macro)
@anchor{c-api/object c Py_CONSTANT_TRUE}@anchor{505f}
@deffn {C 巨集} Py_CONSTANT_TRUE
@end deffn

@tab

@code{2}

@tab

@ref{e02,,True}

@item

@geindex Py_CONSTANT_ELLIPSIS (C macro)
@anchor{c-api/object c Py_CONSTANT_ELLIPSIS}@anchor{5060}
@deffn {C 巨集} Py_CONSTANT_ELLIPSIS
@end deffn

@tab

@code{3}

@tab

@ref{21dd,,Ellipsis}

@item

@geindex Py_CONSTANT_NOT_IMPLEMENTED (C macro)
@anchor{c-api/object c Py_CONSTANT_NOT_IMPLEMENTED}@anchor{5061}
@deffn {C 巨集} Py_CONSTANT_NOT_IMPLEMENTED
@end deffn

@tab

@code{4}

@tab

@ref{1a2,,NotImplemented}

@item

@geindex Py_CONSTANT_ZERO (C macro)
@anchor{c-api/object c Py_CONSTANT_ZERO}@anchor{5062}
@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{5063}
@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{5064}
@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{5065}
@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{5066}
@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.


在 3.13 版被加入.


在 CPython 中，所有這些常數都是@ref{290,,不滅}的。
@end deffn

@geindex Py_GetConstantBorrowed (C function)
@anchor{c-api/object c Py_GetConstantBorrowed}@anchor{5f2}
@deffn {C 函式} @ref{5d7,,PyObject} *Py_GetConstantBorrowed (unsigned int constant_id)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.13 版本開始.'
Similar to @ref{5f1,,Py_GetConstant()}, but return a @ref{3d5,,borrowed reference}.

This function is primarily intended for backwards compatibility:
using @ref{5f1,,Py_GetConstant()} is recommended for new code.

The reference is borrowed from the interpreter, and is valid until the
interpreter finalization.


在 3.13 版被加入.

@end deffn

@geindex Py_NotImplemented (C var)
@anchor{c-api/object c Py_NotImplemented}@anchor{5067}
@deffn {C 變數} @ref{5d7,,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{176d}
@deffn {C 巨集} Py_RETURN_NOTIMPLEMENTED

Properly handle returning @ref{5067,,Py_NotImplemented} from within a C
function (that is, create a new @ref{5da,,strong reference}
to @ref{1a2,,NotImplemented} and return it).
@end deffn

@geindex Py_PRINT_RAW (C macro)
@anchor{c-api/object c Py_PRINT_RAW}@anchor{5068}
@deffn {C 巨集} Py_PRINT_RAW

Flag to be used with multiple functions that print the object (like
@ref{18e5,,PyObject_Print()} and @ref{4eb2,,PyFile_WriteObject()}).
If passed, these function would use the @ref{169,,str()} of the object
instead of the @ref{1c1,,repr()}.
@end deffn

@geindex PyObject_Print (C function)
@anchor{c-api/object c PyObject_Print}@anchor{18e5}
@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{5068,,Py_PRINT_RAW}; if given, the @ref{169,,str()} of the object is written
instead of the @ref{1c1,,repr()}.
@end deffn

@geindex PyObject_HasAttrWithError (C function)
@anchor{c-api/object c PyObject_HasAttrWithError}@anchor{613}
@deffn {C 函式} int PyObject_HasAttrWithError (PyObject *o, PyObject *attr_name)
` 為 @ref{76e,,穩定 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}.


在 3.13 版被加入.

@end deffn

@geindex PyObject_HasAttrStringWithError (C function)
@anchor{c-api/object c PyObject_HasAttrStringWithError}@anchor{615}
@deffn {C 函式} int PyObject_HasAttrStringWithError (PyObject *o, const char *attr_name)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.13 版本開始.'
This is the same as @ref{613,,PyObject_HasAttrWithError()}, but `attr_name' is
specified as a const char* UTF-8 encoded bytes string,
rather than a @ref{5d7,,PyObject}*.


在 3.13 版被加入.

@end deffn

@geindex PyObject_HasAttr (C function)
@anchor{c-api/object c PyObject_HasAttr}@anchor{614}
@deffn {C 函式} int PyObject_HasAttr (PyObject *o, PyObject *attr_name)
` 為 @ref{76e,,穩定 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{6f3,,__getattr__()} and
@ref{dc6,,__getattribute__()} methods aren't propagated,
but instead given to @ref{502,,sys.unraisablehook()}.
For proper error handling, use @ref{613,,PyObject_HasAttrWithError()},
@ref{5e4,,PyObject_GetOptionalAttr()} or @ref{5e6,,PyObject_GetAttr()} instead.
@end quotation
@end cartouche
@end deffn

@geindex PyObject_HasAttrString (C function)
@anchor{c-api/object c PyObject_HasAttrString}@anchor{616}
@deffn {C 函式} int PyObject_HasAttrString (PyObject *o, const char *attr_name)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
This is the same as @ref{614,,PyObject_HasAttr()}, but `attr_name' is
specified as a const char* UTF-8 encoded bytes string,
rather than a @ref{5d7,,PyObject}*.

@cartouche
@quotation 備註 
Exceptions that occur when this calls @ref{6f3,,__getattr__()} and
@ref{dc6,,__getattribute__()} methods or while creating the temporary
@ref{169,,str} object are silently ignored.
For proper error handling, use @ref{615,,PyObject_HasAttrStringWithError()},
@ref{5e5,,PyObject_GetOptionalAttrString()}
or @ref{5e7,,PyObject_GetAttrString()} instead.
@end quotation
@end cartouche
@end deffn

@geindex PyObject_GetAttr (C function)
@anchor{c-api/object c PyObject_GetAttr}@anchor{5e6}
@deffn {C 函式} @ref{5d7,,PyObject} *PyObject_GetAttr (PyObject *o, PyObject *attr_name)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{5e4,,PyObject_GetOptionalAttr()} instead.
@end deffn

@geindex PyObject_GetAttrString (C function)
@anchor{c-api/object c PyObject_GetAttrString}@anchor{5e7}
@deffn {C 函式} @ref{5d7,,PyObject} *PyObject_GetAttrString (PyObject *o, const char *attr_name)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
This is the same as @ref{5e6,,PyObject_GetAttr()}, but `attr_name' is
specified as a const char* UTF-8 encoded bytes string,
rather than a @ref{5d7,,PyObject}*.

If the missing attribute should not be treated as a failure, you can use
@ref{5e5,,PyObject_GetOptionalAttrString()} instead.
@end deffn

@geindex PyObject_GetOptionalAttr (C function)
@anchor{c-api/object c PyObject_GetOptionalAttr}@anchor{5e4}
@deffn {C 函式} int PyObject_GetOptionalAttr (PyObject *obj, PyObject *attr_name, PyObject **result);
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.13 版本開始.'
Variant of @ref{5e6,,PyObject_GetAttr()} which doesn't raise
@ref{5e8,,AttributeError} if the attribute is not found.

If the attribute is found, return @code{1} and set `*result' to a new
@ref{5da,,strong reference} to the attribute.
If the attribute is not found, return @code{0} and set `*result' to @code{NULL};
the @ref{5e8,,AttributeError} is silenced.
If an error other than @ref{5e8,,AttributeError} is raised, return @code{-1} and
set `*result' to @code{NULL}.


在 3.13 版被加入.

@end deffn

@geindex PyObject_GetOptionalAttrString (C function)
@anchor{c-api/object c PyObject_GetOptionalAttrString}@anchor{5e5}
@deffn {C 函式} int PyObject_GetOptionalAttrString (PyObject *obj, const char *attr_name, PyObject **result);
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.13 版本開始.'
This is the same as @ref{5e4,,PyObject_GetOptionalAttr()}, but `attr_name' is
specified as a const char* UTF-8 encoded bytes string,
rather than a @ref{5d7,,PyObject}*.


在 3.13 版被加入.

@end deffn

@geindex PyObject_GenericGetAttr (C function)
@anchor{c-api/object c PyObject_GenericGetAttr}@anchor{4f10}
@deffn {C 函式} @ref{5d7,,PyObject} *PyObject_GenericGetAttr (PyObject *o, PyObject *name)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{776,,__dict__} (if present).  As outlined in @ref{e44,,實作描述器},
data descriptors take preference over instance attributes, while non-data
descriptors don't.  Otherwise, an @ref{5e8,,AttributeError} is raised.
@end deffn

@geindex PyObject_SetAttr (C function)
@anchor{c-api/object c PyObject_SetAttr}@anchor{4f19}
@deffn {C 函式} int PyObject_SetAttr (PyObject *o, PyObject *attr_name, PyObject *v)
` 為 @ref{76e,,穩定 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{17ae,,PyObject_DelAttr()}, but there are currently no
plans to remove it.
@end deffn

@geindex PyObject_SetAttrString (C function)
@anchor{c-api/object c PyObject_SetAttrString}@anchor{18e8}
@deffn {C 函式} int PyObject_SetAttrString (PyObject *o, const char *attr_name, PyObject *v)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
This is the same as @ref{4f19,,PyObject_SetAttr()}, but `attr_name' is
specified as a const char* UTF-8 encoded bytes string,
rather than a @ref{5d7,,PyObject}*.

If `v' is @code{NULL}, the attribute is deleted, but this feature is
deprecated in favour of using @ref{17af,,PyObject_DelAttrString()}.

The number of different attribute names passed to this function
should be kept small, usually by using a statically allocated string
as `attr_name'.
For attribute names that aren't known at compile time, prefer calling
@ref{4f80,,PyUnicode_FromString()} and @ref{4f19,,PyObject_SetAttr()} directly.
For more details, see @ref{18e6,,PyUnicode_InternFromString()}, which may be
used internally to create a key object.
@end deffn

@geindex PyObject_GenericSetAttr (C function)
@anchor{c-api/object c PyObject_GenericSetAttr}@anchor{4f11}
@deffn {C 函式} int PyObject_GenericSetAttr (PyObject *o, PyObject *name, PyObject *value)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Generic attribute setter and deleter function that is meant
to be put into a type object's @ref{4db0,,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{776,,__dict__} (if present).
On success, @code{0} is returned, otherwise an @ref{5e8,,AttributeError}
is raised and @code{-1} is returned.
@end deffn

@geindex PyObject_DelAttr (C function)
@anchor{c-api/object c PyObject_DelAttr}@anchor{17ae}
@deffn {C 函式} int PyObject_DelAttr (PyObject *o, PyObject *attr_name)
` 為 @ref{76e,,穩定 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{17af}
@deffn {C 函式} int PyObject_DelAttrString (PyObject *o, const char *attr_name)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.13 版本開始.'
This is the same as @ref{17ae,,PyObject_DelAttr()}, but `attr_name' is
specified as a const char* UTF-8 encoded bytes string,
rather than a @ref{5d7,,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{4f80,,PyUnicode_FromString()} and @ref{17ae,,PyObject_DelAttr()} directly.
For more details, see @ref{18e6,,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{1bef}
@deffn {C 函式} @ref{5d7,,PyObject} *PyObject_GenericGetDict (PyObject *o, void *context)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{776,,__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{5e6,,PyObject_GetAttr()}
when accessing an attribute on the object.

在失敗時，會回傳 @code{NULL} 並設定例外。


在 3.3 版被加入.

@end deffn

@geindex PyObject_GenericSetDict (C function)
@anchor{c-api/object c PyObject_GenericSetDict}@anchor{4f12}
@deffn {C 函式} int PyObject_GenericSetDict (PyObject *o, PyObject *value, void *context)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.7 版本開始.'
A generic implementation for the setter of a @code{__dict__} descriptor. This
implementation does not allow the dictionary to be deleted.


在 3.3 版被加入.

@end deffn

@geindex _PyObject_GetDictPtr (C function)
@anchor{c-api/object c _PyObject_GetDictPtr}@anchor{5069}
@deffn {C 函式} @ref{5d7,,PyObject} **_PyObject_GetDictPtr (PyObject *obj)

Return a pointer to @ref{776,,__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{5e6,,PyObject_GetAttr()}
when accessing an attribute on the object.
@end deffn

@geindex PyObject_RichCompare (C function)
@anchor{c-api/object c PyObject_RichCompare}@anchor{4db9}
@deffn {C 函式} @ref{5d7,,PyObject} *PyObject_RichCompare (PyObject *o1, PyObject *o2, int opid)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Compare the values of `o1' and `o2' using the operation specified by `opid',
which must be one of @ref{506a,,Py_LT}, @ref{506b,,Py_LE}, @ref{506c,,Py_EQ},
@ref{506d,,Py_NE}, @ref{506e,,Py_GT}, or @ref{506f,,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{1c55}
@deffn {C 函式} int PyObject_RichCompareBool (PyObject *o1, PyObject *o2, int opid)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Compare the values of `o1' and `o2' using the operation specified by `opid',
like @ref{4db9,,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{1c55,,PyObject_RichCompareBool()}
will always return @code{1} for @ref{506c,,Py_EQ} and @code{0} for @ref{506d,,Py_NE}.
@end quotation
@end cartouche

@geindex PyObject_Format (C function)
@anchor{c-api/object c PyObject_Format}@anchor{4f0f}
@deffn {C 函式} @ref{5d7,,PyObject} *PyObject_Format (PyObject *obj, PyObject *format_spec)
` 為 @ref{76e,,穩定 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{122a}
@deffn {C 函式} @ref{5d7,,PyObject} *PyObject_Repr (PyObject *o)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
@geindex bulit-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{1c1,,repr()} built-in function.


在 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{4f08}
@deffn {C 函式} @ref{5d7,,PyObject} *PyObject_ASCII (PyObject *o)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
@geindex bulit-in function（內建函式）;ascii

As @ref{122a,,PyObject_Repr()}, compute a string representation of object `o', but
escape the non-ASCII characters in the string returned by
@ref{122a,,PyObject_Repr()} with @code{\x}, @code{\u} or @code{\U} escapes.  This generates
a string similar to that returned by @ref{122a,,PyObject_Repr()} in Python 2.
Called by the @ref{15dd,,ascii()} built-in function.

@geindex string（字串）;PyObject_Str（C 函式）
@end deffn

@geindex PyObject_Str (C function)
@anchor{c-api/object c PyObject_Str}@anchor{122b}
@deffn {C 函式} @ref{5d7,,PyObject} *PyObject_Str (PyObject *o)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{169,,str()} built-in function
and, therefore, by the @ref{1170,,print()} function.


在 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{4f0a}
@deffn {C 函式} @ref{5d7,,PyObject} *PyObject_Bytes (PyObject *o)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
@geindex bulit-in function（內建函式）;bytes（位元組）

Compute a bytes representation of object `o'.  @code{NULL} is returned on
failure and a bytes object on success.  This is equivalent to the Python
expression @code{bytes(o)}, when `o' is not an integer.  Unlike @code{bytes(o)},
a TypeError is raised when `o' is an integer instead of a zero-initialized
bytes object.
@end deffn

@geindex PyObject_IsSubclass (C function)
@anchor{c-api/object c PyObject_IsSubclass}@anchor{10a2}
@deffn {C 函式} int PyObject_IsSubclass (PyObject *derived, PyObject *cls)
` 為 @ref{76e,,穩定 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{2279,,__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{2229,,cls.__mro__}.

Normally only class objects, i.e. instances of @ref{f3f,,type} or a derived
class, are considered classes.  However, objects can override this by having
a @ref{16a0,,__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{10a1}
@deffn {C 函式} int PyObject_IsInstance (PyObject *inst, PyObject *cls)
` 為 @ref{76e,,穩定 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{2278,,__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{16a1,,__class__} attribute.

An object `cls' can override if it is considered a class, and what its base
classes are, by having a @ref{16a0,,__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{434}
@deffn {C 函式} @ref{1464,,Py_hash_t} PyObject_Hash (PyObject *o)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@geindex bulit-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{c4c,,Py_ssize_t}.

@end deffn

@geindex PyObject_HashNotImplemented (C function)
@anchor{c-api/object c PyObject_HashNotImplemented}@anchor{15be}
@deffn {C 函式} @ref{1464,,Py_hash_t} PyObject_HashNotImplemented (PyObject *o)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Set a @ref{198,,TypeError} indicating that @code{type(o)} is not @ref{81d,,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{4f15}
@deffn {C 函式} int PyObject_IsTrue (PyObject *o)
` 為 @ref{76e,,穩定 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{4f17}
@deffn {C 函式} int PyObject_Not (PyObject *o)
` 為 @ref{76e,,穩定 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{4f1b}
@deffn {C 函式} @ref{5d7,,PyObject} *PyObject_Type (PyObject *o)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
@geindex bulit-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{78e,,SystemError} and returns @code{NULL}.  This
is equivalent to the Python expression @code{type(o)}.
This function creates a new @ref{5da,,strong reference} to the return value.
There's really no reason to use this
function instead of the @ref{3c7,,Py_TYPE()} function, which returns a
pointer of type @ref{c93,,PyTypeObject}*, except when a new
@ref{5da,,strong reference} is needed.
@end deffn

@geindex PyObject_TypeCheck (C function)
@anchor{c-api/object c PyObject_TypeCheck}@anchor{1bad}
@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{4f1a}
@deffn {C 函式} @ref{c4c,,Py_ssize_t} PyObject_Size (PyObject *o)
@anchor{c-api/object c PyObject_Length}@anchor{4f16}
@deffnx {C 函式} @ref{c4c,,Py_ssize_t} PyObject_Length (PyObject *o)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@geindex bulit-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{11ff}
@deffn {C 函式} @ref{c4c,,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{1109,,__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)}.


在 3.4 版被加入.

@end deffn

@geindex PyObject_GetItem (C function)
@anchor{c-api/object c PyObject_GetItem}@anchor{5e2}
@deffn {C 函式} @ref{5d7,,PyObject} *PyObject_GetItem (PyObject *o, PyObject *key)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{4df9}
@deffn {C 函式} int PyObject_SetItem (PyObject *o, PyObject *key, PyObject *v)
` 為 @ref{76e,,穩定 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{4f0c}
@deffn {C 函式} int PyObject_DelItem (PyObject *o, PyObject *key)
` 為 @ref{76e,,穩定 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{4f0d}
@deffn {C 函式} int PyObject_DelItemString (PyObject *o, const char *key)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
This is the same as @ref{4f0c,,PyObject_DelItem()}, but `key' is
specified as a const char* UTF-8 encoded bytes string,
rather than a @ref{5d7,,PyObject}*.
@end deffn

@geindex PyObject_Dir (C function)
@anchor{c-api/object c PyObject_Dir}@anchor{4f0e}
@deffn {C 函式} @ref{5d7,,PyObject} *PyObject_Dir (PyObject *o)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{1ba7,,PyErr_Occurred()} will return false.
@end deffn

@geindex PyObject_GetIter (C function)
@anchor{c-api/object c PyObject_GetIter}@anchor{4f14}
@deffn {C 函式} @ref{5d7,,PyObject} *PyObject_GetIter (PyObject *o)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{198,,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{4f18}
@deffn {C 函式} @ref{5d7,,PyObject} *PyObject_SelfIter (PyObject *obj)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
This is equivalent to the Python @code{__iter__(self): return self} method.
It is intended for @ref{4c3,,iterator} types, to be used in the @ref{16e3,,PyTypeObject.tp_iter} slot.
@end deffn

@geindex PyObject_GetAIter (C function)
@anchor{c-api/object c PyObject_GetAIter}@anchor{4f13}
@deffn {C 函式} @ref{5d7,,PyObject} *PyObject_GetAIter (PyObject *o)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{198,,TypeError} and
returns @code{NULL} if the object cannot be iterated.


在 3.10 版被加入.

@end deffn

@geindex PyObject_GetTypeData (C function)
@anchor{c-api/object c PyObject_GetTypeData}@anchor{764}
@deffn {C 函式} void *PyObject_GetTypeData (PyObject *o, PyTypeObject *cls)
` 為 @ref{76e,,穩定 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{763,,PyType_Spec.basicsize}.
Python does not check this.

錯誤時設定一個例外並回傳 @code{NULL}。


在 3.12 版被加入.

@end deffn

@geindex PyType_GetTypeDataSize (C function)
@anchor{c-api/object c PyType_GetTypeDataSize}@anchor{765}
@deffn {C 函式} @ref{c4c,,Py_ssize_t} PyType_GetTypeDataSize (PyTypeObject *cls)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.12 版本開始.'
Return the size of the instance memory space reserved for `cls', i.e. the size of the
memory @ref{764,,PyObject_GetTypeData()} returns.

This may be larger than requested using @ref{763,,-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{763,,PyType_Spec.basicsize}.
Python does not check this.

錯誤時設定一個例外並回傳一個負值。


在 3.12 版被加入.

@end deffn

@geindex PyObject_GetItemData (C function)
@anchor{c-api/object c PyObject_GetItemData}@anchor{767}
@deffn {C 函式} void *PyObject_GetItemData (PyObject *o)

Get a pointer to per-item data for a class with
@ref{766,,Py_TPFLAGS_ITEMS_AT_END}.

錯誤時設定一個例外並回傳 @code{NULL}。如果 `o' 沒有設定 @ref{766,,Py_TPFLAGS_ITEMS_AT_END}，則會引發 @ref{198,,TypeError}。


在 3.12 版被加入.

@end deffn

@geindex PyObject_VisitManagedDict (C function)
@anchor{c-api/object c PyObject_VisitManagedDict}@anchor{605}
@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{607,,Py_TPFLAGS_MANAGED_DICT} flag set.


在 3.13 版被加入.

@end deffn

@geindex PyObject_ClearManagedDict (C function)
@anchor{c-api/object c PyObject_ClearManagedDict}@anchor{606}
@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{607,,Py_TPFLAGS_MANAGED_DICT} flag set.


在 3.13 版被加入.

@end deffn

@geindex PyUnstable_Object_EnableDeferredRefcount (C function)
@anchor{c-api/object c PyUnstable_Object_EnableDeferredRefcount}@anchor{3c3}
@deffn {C 函式} int PyUnstable_Object_EnableDeferredRefcount (PyObject *obj)

@cartouche
@quotation 這是 不穩定 API，它可能在小版本發布中沒有任何警告地被變更。 `這是 @ref{762,,不穩定 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{1f4,,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{164,,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{150e,,gc.is_tracked()} and
@ref{b64,,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{798,,tp_new}
slot.


在 3.14 版被加入.

@end deffn

@geindex PyUnstable_Object_IsUniqueReferencedTemporary (C function)
@anchor{c-api/object c PyUnstable_Object_IsUniqueReferencedTemporary}@anchor{3c5}
@deffn {C 函式} int PyUnstable_Object_IsUniqueReferencedTemporary (PyObject *obj)

@cartouche
@quotation 這是 不穩定 API，它可能在小版本發布中沒有任何警告地被變更。 `這是 @ref{762,,不穩定 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{3d5,,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

另請參閱 @ref{2cf,,Py_REFCNT()} 函式。


在 3.14 版被加入.

@end deffn

@geindex PyUnstable_IsImmortal (C function)
@anchor{c-api/object c PyUnstable_IsImmortal}@anchor{3c2}
@deffn {C 函式} int PyUnstable_IsImmortal (PyObject *obj)

@cartouche
@quotation 這是 不穩定 API，它可能在小版本發布中沒有任何警告地被變更。 `這是 @ref{762,,不穩定 API}，它可能在小版本發布中沒有任何警告地被變更。'
@end quotation
@end cartouche

This function returns non-zero if `obj' is @ref{290,,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


在 3.14 版被加入.

@end deffn

@geindex PyUnstable_TryIncRef (C function)
@anchor{c-api/object c PyUnstable_TryIncRef}@anchor{183a}
@deffn {C 函式} int PyUnstable_TryIncRef (PyObject *obj)

@cartouche
@quotation 這是 不穩定 API，它可能在小版本發布中沒有任何警告地被變更。 `這是 @ref{762,,不穩定 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{183b,,PyUnstable_EnableTryIncRef()} must have been called
earlier on `obj' or this function may spuriously return @code{0} in the
@ref{1f4,,free threading} build.

This function is logically equivalent to the following C code, except that
it behaves atomically in the @ref{1f4,,free threading} 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{5070,,weak reference object}.

Typically, correct use of this function requires support from `obj''s
deallocator (@ref{4d84,,tp_dealloc}).
For example, the following sketch could be adapted to implement a
"weakmap" that works like a @ref{1890,,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


在 3.14 版被加入.

@end deffn

@geindex PyUnstable_EnableTryIncRef (C function)
@anchor{c-api/object c PyUnstable_EnableTryIncRef}@anchor{183b}
@deffn {C 函式} void PyUnstable_EnableTryIncRef (PyObject *obj)

@cartouche
@quotation 這是 不穩定 API，它可能在小版本發布中沒有任何警告地被變更。 `這是 @ref{762,,不穩定 API}，它可能在小版本發布中沒有任何警告地被變更。'
@end quotation
@end cartouche

Enables subsequent uses of @ref{183a,,PyUnstable_TryIncRef()} on `obj'.  The
caller must hold a @ref{5da,,strong reference} to `obj' when calling this.


在 3.14 版被加入.

@end deffn

@geindex PyUnstable_Object_IsUniquelyReferenced (C function)
@anchor{c-api/object c PyUnstable_Object_IsUniquelyReferenced}@anchor{3c4}
@deffn {C 函式} int PyUnstable_Object_IsUniquelyReferenced (PyObject *op)

@cartouche
@quotation 這是 不穩定 API，它可能在小版本發布中沒有任何警告地被變更。 `這是 @ref{762,,不穩定 API}，它可能在小版本發布中沒有任何警告地被變更。'
@end quotation
@end cartouche

Determine if `op' only has one reference.

On GIL-enabled builds, this function is equivalent to
@ref{2cf,,Py_REFCNT}(@ref{3c4,,op}) == 1.

On a @ref{1f4,,free threaded} build, this checks if `op''s
@ref{4d91,,reference count} is equal to one and additionally checks if `op'
is only used by this thread. @ref{2cf,,Py_REFCNT}(@ref{3c4,,op}) == 1 is `not'
thread-safe on free threaded builds; prefer this function.

The caller must hold an @ref{4d99,,attached thread state}, despite the fact
that this function doesn't call into the Python interpreter. This function
cannot fail.


在 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 呼叫協定 Call Protocol,數字協定,物件協定,抽象物件層 Abstract Objects Layer
@anchor{c-api/call doc}@anchor{5071}@anchor{c-api/call call}@anchor{79c}@anchor{c-api/call call-protocol}@anchor{5072}@anchor{c-api/call translation-repo}@anchor{5073}
@subsection 呼叫協定 (Call Protocol)


CPython 支援兩種不同的呼叫協定：`tp_call' 和 vectorcall（向量呼叫）。

@menu
* tp_call 協定:: 
* Vectorcall 協定:: 
* 物件呼叫 API:: 
* 呼叫支援 API:: 

@end menu

@node tp_call 協定,Vectorcall 協定,,呼叫協定 Call Protocol
@anchor{c-api/call the-tp-call-protocol}@anchor{5074}
@subsubsection `tp_call' 協定


設定 @ref{774,,tp_call} 的類別之實例都是可呼叫的。該擴充槽 (slot) 的簽章為：

@example
PyObject *tp_call(PyObject *callable, PyObject *args, PyObject *kwargs);
@end example

要達成一個呼叫會使用一個 tuple（元組）表示位置引數、一個 dict 表示關鍵字引數，類似於 Python 程式碼中的 @code{callable(*args, **kwargs)}。`args' 必須不為 NULL（如果沒有引數，會使用一個空 tuple），但如果沒有關鍵字引數，`kwargs' 可以是 `NULL'。

這個慣例不僅會被 `tp_call' 使用，@ref{798,,tp_new} 和 @ref{79a,,tp_init} 也這樣傳遞引數。

使用 @ref{635,,PyObject_Call()} 或其他@ref{5075,,呼叫 API} 來呼叫一個物件。

@node Vectorcall 協定,物件呼叫 API,tp_call 協定,呼叫協定 Call Protocol
@anchor{c-api/call the-vectorcall-protocol}@anchor{5076}@anchor{c-api/call vectorcall}@anchor{76d}
@subsubsection Vectorcall 協定



在 3.9 版被加入.


Vectorcall 協定是在 
@geindex Python Enhancement Proposals; PEP 590
PEP 590@footnote{https://peps.python.org/pep-0590/} 被引入的，它是使函式呼叫更加有效率的附加協定。

經驗法則上，如果可呼叫物件有支援，CPython 於內部呼叫中會更傾向使用 vectorcall。然而，這並不是一個硬性規定。此外，有些第三方擴充套件會直接使用 `tp_call'（而不是使用 @ref{635,,PyObject_Call()}）。因此，一個支援 vectorcall 的類別也必須實作 @ref{774,,tp_call}。此外，無論使用哪種協定，可呼叫物件的行為都必須是相同的。要達成這個目的的推薦做法是將 @ref{774,,tp_call} 設定為 @ref{771,,PyVectorcall_Call()}。這值得一再提醒：

@cartouche
@quotation 警告 
一個支援 vectorcall 的類別`必須'也實作具有相同語義的 @ref{774,,tp_call}。
@end quotation
@end cartouche


在 3.12 版的變更: 當一個類別的 @ref{773,,__call__()} 方法被重新賦值時，@ref{76f,,Py_TPFLAGS_HAVE_VECTORCALL} 旗標現在會被移除。（這會在內部設定 @ref{774,,tp_call}，因此可能會使它與 vectorcall 函式有不同的行為。）在較早的 Python 版本中，vectorcall 應該只與 @ref{3cd,,immutable} 或靜態型別一起使用。


如果一個類別的 vectorcall 比 `tp_call' 慢，就不應該實作 vectorcall。例如，如果被呼叫者需要將引數轉換為 args tuple（引數元組）和 kwargs dict（關鍵字引數字典），那麼實作 vectorcall 就沒有意義。

類別可以透過啟用 @ref{76f,,Py_TPFLAGS_HAVE_VECTORCALL} 旗標並將 @ref{5077,,tp_vectorcall_offset} 設定為物件結構中有出現 `vectorcallfunc' 的 offset 來實作 vectorcall 協定。這是一個指向具有以下簽章之函式的指標：

@geindex vectorcallfunc (C type)
@anchor{c-api/call c vectorcallfunc}@anchor{772}
@deffn {C 型別} typedef @ref{5d7,,PyObject} *(*vectorcallfunc)(@ref{5d7,,PyObject} *callable, @ref{5d7,,PyObject} *const *args, size_t nargsf, @ref{5d7,,PyObject} *kwnames)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.12 版本開始.'
@end deffn


@itemize -

@item 
`callable' 是指被呼叫的物件。

@item 

@table @asis

@item `args' 是一個 C 語言陣列 (array)，包含位置引數與後面

關鍵字引數的值。如果沒有引數，這個值可以是 `NULL'。
@end table

@item 

@table @asis

@item `nargsf' 是位置引數的數量加上可能會有的

@ref{779,,PY_VECTORCALL_ARGUMENTS_OFFSET} 旗標。如果要從 `nargsf' 獲得實際的位置引數數量，請使用 @ref{770,,PyVectorcall_NARGS()}。
@end table

@item 

@table @asis

@item `kwnames' 是一個包含所有關鍵字引數名稱的 tuple；

換句話說，就是 kwargs 字典的鍵。這些名字必須是字串（@code{str} 或其子類別的實例)，並且它們必須是不重複的。如果沒有關鍵字引數，那麼 `kwnames' 可以用 `NULL' 代替。
@end table
@end itemize

@geindex PY_VECTORCALL_ARGUMENTS_OFFSET (C macro)
@anchor{c-api/call c PY_VECTORCALL_ARGUMENTS_OFFSET}@anchor{779}
@deffn {C 巨集} PY_VECTORCALL_ARGUMENTS_OFFSET
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.12 版本開始.'
如果在 vectorcall 的 `nargsf' 引數中設定了此旗標，則允許被呼叫者臨時更改 @code{args[-1]} 的值。換句話說，`args' 指向向量中的引數 1（不是 0）。被呼叫方必須在回傳之前還原 @code{args[-1]} 的值。

對於 @ref{778,,PyObject_VectorcallMethod()}，這個旗標的改變意味著可能是 @code{args[0]} 被改變。

當可以以幾乎無代價的方式（無需佔據額外的記憶體）來達成，那麼會推薦呼叫者使用 @ref{779,,PY_VECTORCALL_ARGUMENTS_OFFSET}。這樣做會讓如 bound method（繫結方法）之類的可呼叫函式非常有效地繼續向前呼叫（這類函式包含一個在首位的 `self' 引數）。


在 3.8 版被加入.

@end deffn

要呼叫一個實作了 vectorcall 的物件，請就像其他可呼叫物件一樣使用@ref{5075,,呼叫 API} 中的函式。@ref{777,,PyObject_Vectorcall()} 通常是最有效率的。

@menu
* 遞迴控制: 遞迴控制<2>. 
* Vectorcall 支援 API:: 

@end menu

@node 遞迴控制<2>,Vectorcall 支援 API,,Vectorcall 協定
@anchor{c-api/call recursion-control}@anchor{5078}
@subsubsection 遞迴控制


在使用 `tp_call' 時，被呼叫者不必擔心@ref{4ff0,,遞迴}：CPython 對於使用 `tp_call' 的呼叫會使用 @ref{3d0,,Py_EnterRecursiveCall()} 和 @ref{b62,,Py_LeaveRecursiveCall()}。

為保證效率，這不適用於使用 vectorcall 的呼叫：被呼叫方在需要時應當使用 `Py_EnterRecursiveCall' 和 `Py_LeaveRecursiveCall'。

@node Vectorcall 支援 API,,遞迴控制<2>,Vectorcall 協定
@anchor{c-api/call vectorcall-support-api}@anchor{5079}
@subsubsection Vectorcall 支援 API


@geindex PyVectorcall_NARGS (C function)
@anchor{c-api/call c PyVectorcall_NARGS}@anchor{770}
@deffn {C 函式} @ref{c4c,,Py_ssize_t} PyVectorcall_NARGS (size_t nargsf)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.12 版本開始.'
給定一個 vectorcall `nargsf' 引數，回傳引數的實際數量。目前等同於：

@example
(Py_ssize_t)(nargsf & ~PY_VECTORCALL_ARGUMENTS_OFFSET)
@end example

然而，應使用 @code{PyVectorcall_NARGS} 函式以便將來需要擴充。


在 3.8 版被加入.

@end deffn

@geindex PyVectorcall_Function (C function)
@anchor{c-api/call c PyVectorcall_Function}@anchor{507a}
@deffn {C 函式} @ref{772,,vectorcallfunc} PyVectorcall_Function (PyObject *op)

如果 `op' 不支援 vectorcall 協定（因為型別不支援或特定實例不支援），就回傳 `NULL'。否則，回傳儲存在 `op' 中的 vectorcall 函式指標。這個函式不會引發例外。

這大多在檢查 `op' 是否支援 vectorcall 時能派上用場，可以透過檢查 @code{PyVectorcall_Function(op) != NULL} 來達成。


在 3.9 版被加入.

@end deffn

@geindex PyVectorcall_Call (C function)
@anchor{c-api/call c PyVectorcall_Call}@anchor{771}
@deffn {C 函式} @ref{5d7,,PyObject} *PyVectorcall_Call (PyObject *callable, PyObject *tuple, PyObject *dict)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.12 版本開始.'
呼叫 `callable' 的 @ref{772,,vectorcallfunc}，其位置引數和關鍵字引數分別以 tuple 和 dict 格式給定。

這是一個專門函式，其目的是被放入 @ref{774,,tp_call} 擴充槽或是用於 @code{tp_call} 的實作。它不會檢查 @ref{76f,,Py_TPFLAGS_HAVE_VECTORCALL} 旗標並且它不會退回 (fall back) 使用 @code{tp_call}。


在 3.8 版被加入.

@end deffn

@node 物件呼叫 API,呼叫支援 API,Vectorcall 協定,呼叫協定 Call Protocol
@anchor{c-api/call capi-call}@anchor{5075}@anchor{c-api/call object-calling-api}@anchor{507b}
@subsubsection 物件呼叫 API


有多個函式可被用來呼叫 Python 物件。各個函式會將其引數轉換為被呼叫物件所支援的慣用形式 – 可以是 `tp_call' 或 vectorcall。為了儘可能減少轉換的進行，請選擇一個適合你所擁有資料格式的函式。

下表總結了可用的函式；請參閱各個說明文件以瞭解詳情。


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxx} 
@headitem

函式

@tab

callable

@tab

args

@tab

kwargs

@item

@ref{635,,PyObject_Call()}

@tab

@code{PyObject *}

@tab

tuple

@tab

dict/@code{NULL}

@item

@ref{634,,PyObject_CallNoArgs()}

@tab

@code{PyObject *}

@tab

---

@tab

---

@item

@ref{b66,,PyObject_CallOneArg()}

@tab

@code{PyObject *}

@tab

一個物件

@tab

---

@item

@ref{4d74,,PyObject_CallObject()}

@tab

@code{PyObject *}

@tab

tuple/@code{NULL}

@tab

---

@item

@ref{637,,PyObject_CallFunction()}

@tab

@code{PyObject *}

@tab

format

@tab

---

@item

@ref{638,,PyObject_CallMethod()}

@tab

物件 + @code{char*}

@tab

format

@tab

---

@item

@ref{4f0b,,PyObject_CallFunctionObjArgs()}

@tab

@code{PyObject *}

@tab

可變引數

@tab

---

@item

@ref{1ca8,,PyObject_CallMethodObjArgs()}

@tab

物件 + 名稱

@tab

可變引數

@tab

---

@item

@ref{507c,,PyObject_CallMethodNoArgs()}

@tab

物件 + 名稱

@tab

---

@tab

---

@item

@ref{507d,,PyObject_CallMethodOneArg()}

@tab

物件 + 名稱

@tab

一個物件

@tab

---

@item

@ref{777,,PyObject_Vectorcall()}

@tab

@code{PyObject *}

@tab

vectorcall

@tab

vectorcall

@item

@ref{507e,,PyObject_VectorcallDict()}

@tab

@code{PyObject *}

@tab

vectorcall

@tab

dict/@code{NULL}

@item

@ref{778,,PyObject_VectorcallMethod()}

@tab

引數 + 名稱

@tab

vectorcall

@tab

vectorcall

@end multitable


@geindex PyObject_Call (C function)
@anchor{c-api/call c PyObject_Call}@anchor{635}
@deffn {C 函式} @ref{5d7,,PyObject} *PyObject_Call (PyObject *callable, PyObject *args, PyObject *kwargs)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
呼叫一個可呼叫的 Python 物件 `callable'，附帶由 tuple `args' 所給定的引數及由字典 `kwargs' 所給定的關鍵字引數。

`args' 必須不為 `NULL'；如果不需要引數，請使用一個空 tuple。如果不需要關鍵字引數，則 `kwargs' 可以為 `NULL'。

成功時回傳結果，或在失敗時引發一個例外並回傳 `NULL'。

這等價於 Python 運算式 @code{callable(*args, **kwargs)}。
@end deffn

@geindex PyObject_CallNoArgs (C function)
@anchor{c-api/call c PyObject_CallNoArgs}@anchor{634}
@deffn {C 函式} @ref{5d7,,PyObject} *PyObject_CallNoArgs (PyObject *callable)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.10 版本開始.'
呼叫一個可呼叫的 Python 物件 `callable' 並不附帶任何引數。這是不帶引數呼叫 Python 可呼叫物件的最有效方式。

成功時回傳結果，或在失敗時引發一個例外並回傳 `NULL'。


在 3.9 版被加入.

@end deffn

@geindex PyObject_CallOneArg (C function)
@anchor{c-api/call c PyObject_CallOneArg}@anchor{b66}
@deffn {C 函式} @ref{5d7,,PyObject} *PyObject_CallOneArg (PyObject *callable, PyObject *arg)
`回傳值：新的參照。'
呼叫一個可呼叫的 Python 物件 `callable' 並附帶正好一個位置引數 `arg' 而沒有關鍵字引數。

成功時回傳結果，或在失敗時引發一個例外並回傳 `NULL'。


在 3.9 版被加入.

@end deffn

@geindex PyObject_CallObject (C function)
@anchor{c-api/call c PyObject_CallObject}@anchor{4d74}
@deffn {C 函式} @ref{5d7,,PyObject} *PyObject_CallObject (PyObject *callable, PyObject *args)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
呼叫一個可呼叫的 Python 物件 `callable'，附帶由 tuple `args' 所給定的引數。如果不需要傳入引數，則 `args' 可以為 `NULL'。

成功時回傳結果，或在失敗時引發一個例外並回傳 `NULL'。

這等價於 Python 運算式 @code{callable(*args)}。
@end deffn

@geindex PyObject_CallFunction (C function)
@anchor{c-api/call c PyObject_CallFunction}@anchor{637}
@deffn {C 函式} @ref{5d7,,PyObject} *PyObject_CallFunction (PyObject *callable, const char *format, ...)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
呼叫一個可呼叫的 Python 物件 `callable'，附帶數量可變的 C 引數。這些 C 引數使用 @ref{3c0,,Py_BuildValue()} 風格的格式字串來描述。格式可以為 `NULL'，表示沒有提供任何引數。

成功時回傳結果，或在失敗時引發一個例外並回傳 `NULL'。

這等價於 Python 運算式 @code{callable(*args)}。

注意，如果你只傳入 @ref{5d7,,PyObject}* 引數，則 @ref{4f0b,,PyObject_CallFunctionObjArgs()} 是另一個更快速的選擇。


在 3.4 版的變更: 這個 `format' 的型別已從 @code{char *} 更改。

@end deffn

@geindex PyObject_CallMethod (C function)
@anchor{c-api/call c PyObject_CallMethod}@anchor{638}
@deffn {C 函式} @ref{5d7,,PyObject} *PyObject_CallMethod (PyObject *obj, const char *name, const char *format, ...)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
呼叫 `obj' 物件中名為 `name' 的 method 並附帶數量可變的 C 引數。這些 C 引數由 @ref{3c0,,Py_BuildValue()} 格式字串來描述，並應當生成一個 tuple。

格式可以為 `NULL'，表示沒有提供任何引數。

成功時回傳結果，或在失敗時引發一個例外並回傳 `NULL'。

這等價於 Python 運算式 @code{obj.name(arg1, arg2, ...)}。

注意，如果你只傳入 @ref{5d7,,PyObject}* 引數，則 @ref{1ca8,,PyObject_CallMethodObjArgs()} 是另一個更快速的選擇。


在 3.4 版的變更: `name' 和 `format' 的型別已從 @code{char *} 更改。

@end deffn

@geindex PyObject_CallFunctionObjArgs (C function)
@anchor{c-api/call c PyObject_CallFunctionObjArgs}@anchor{4f0b}
@deffn {C 函式} @ref{5d7,,PyObject} *PyObject_CallFunctionObjArgs (PyObject *callable, ...)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
呼叫一個可呼叫的 Python 物件 `callable'，附帶數量可變的 @ref{5d7,,PyObject}* 引數。這些引數是以位置在 `NULL' 後面、數量可變的參數來提供。

成功時回傳結果，或在失敗時引發一個例外並回傳 `NULL'。

這等價於 Python 運算式 @code{callable(arg1, arg2, ...)}。
@end deffn

@geindex PyObject_CallMethodObjArgs (C function)
@anchor{c-api/call c PyObject_CallMethodObjArgs}@anchor{1ca8}
@deffn {C 函式} @ref{5d7,,PyObject} *PyObject_CallMethodObjArgs (PyObject *obj, PyObject *name, ...)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
呼叫 Python 物件 `obj' 中的一個 method，其中 method 名稱由 `name' 中的 Python 字串物件給定。被呼叫時會附帶數量可變的 @ref{5d7,,PyObject}* 引數。這些引數是以位置在 `NULL' 後面、且數量可變的參數來提供。

成功時回傳結果，或在失敗時引發一個例外並回傳 `NULL'。
@end deffn

@geindex PyObject_CallMethodNoArgs (C function)
@anchor{c-api/call c PyObject_CallMethodNoArgs}@anchor{507c}
@deffn {C 函式} @ref{5d7,,PyObject} *PyObject_CallMethodNoArgs (PyObject *obj, PyObject *name)

不附帶任何引數地呼叫 Python 物件 `obj' 中的一個 method，其中 method 名稱由 `name' 中的 Python 字串物件給定。

成功時回傳結果，或在失敗時引發一個例外並回傳 `NULL'。


在 3.9 版被加入.

@end deffn

@geindex PyObject_CallMethodOneArg (C function)
@anchor{c-api/call c PyObject_CallMethodOneArg}@anchor{507d}
@deffn {C 函式} @ref{5d7,,PyObject} *PyObject_CallMethodOneArg (PyObject *obj, PyObject *name, PyObject *arg)

附帶一個位置引數 `arg' 地呼叫 Python 物件 `obj' 中的一個 method，其中 method 名稱由 `name' 中的 Python 字串物件給定。

成功時回傳結果，或在失敗時引發一個例外並回傳 `NULL'。


在 3.9 版被加入.

@end deffn

@geindex PyObject_Vectorcall (C function)
@anchor{c-api/call c PyObject_Vectorcall}@anchor{777}
@deffn {C 函式} @ref{5d7,,PyObject} *PyObject_Vectorcall (PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.12 版本開始.'
呼叫一個可呼叫的 Python 物件 `callable'。附帶引數與 @ref{772,,vectorcallfunc} 的相同。如果 `callable' 支援 @ref{76d,,vectorcall}，則它會直接呼叫存放在 `callable' 中的 vectorcall 函式。

成功時回傳結果，或在失敗時引發一個例外並回傳 `NULL'。


在 3.9 版被加入.

@end deffn

@geindex PyObject_VectorcallDict (C function)
@anchor{c-api/call c PyObject_VectorcallDict}@anchor{507e}
@deffn {C 函式} @ref{5d7,,PyObject} *PyObject_VectorcallDict (PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwdict)

附帶與在 @ref{76d,,vectorcall} 協定中傳入的相同位置引數來呼叫 `callable'，但會加上以字典 `kwdict' 格式傳入的關鍵字引數。`args' 陣列將只包含位置引數。

無論內部使用了哪一種協定，都會需要進行引數的轉換。因此，此函式應該只有在呼叫方已經擁有一個要作為關鍵字引數的字典、但沒有作為位置引數的 tuple 時才被使用。


在 3.9 版被加入.

@end deffn

@geindex PyObject_VectorcallMethod (C function)
@anchor{c-api/call c PyObject_VectorcallMethod}@anchor{778}
@deffn {C 函式} @ref{5d7,,PyObject} *PyObject_VectorcallMethod (PyObject *name, PyObject *const *args, size_t nargsf, PyObject *kwnames)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.12 版本開始.'
使用 vectorcall 呼叫慣例來呼叫一個 method。method 的名稱以 Python 字串 `name' 的格式給定。被呼叫 method 的物件為 `args[0]'，而 `args' 陣列從 `args[1]' 開始的部分則代表呼叫的引數。必須傳入至少一個位置引數。`nargsf' 為包括 `args[0]' 在內的位置引數的數量，如果 @code{args[0]} 的值可能被臨時改變則要再加上 @ref{779,,PY_VECTORCALL_ARGUMENTS_OFFSET}。關鍵字引數可以像在 @ref{777,,PyObject_Vectorcall()} 中一樣被傳入。

如果物件具有 @ref{507f,,Py_TPFLAGS_METHOD_DESCRIPTOR} 特性，這將以完整的 `args' 向量作為引數來呼叫 unbound method（未繫結方法）物件。

成功時回傳結果，或在失敗時引發一個例外並回傳 `NULL'。


在 3.9 版被加入.

@end deffn

@node 呼叫支援 API,,物件呼叫 API,呼叫協定 Call Protocol
@anchor{c-api/call call-support-api}@anchor{5080}
@subsubsection 呼叫支援 API


@geindex PyCallable_Check (C function)
@anchor{c-api/call c PyCallable_Check}@anchor{4e2c}
@deffn {C 函式} int PyCallable_Check (PyObject *o)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
判定物件 `o' 是否為可呼叫的。如果物件是可呼叫物件則回傳 @code{1}，其他情況回傳 @code{0}。這個函式不會呼叫失敗。
@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,抽象物件層 Abstract Objects Layer
@anchor{c-api/number doc}@anchor{5081}@anchor{c-api/number number}@anchor{5082}@anchor{c-api/number number-protocol}@anchor{5083}@anchor{c-api/number translation-repo}@anchor{5084}
@subsection 數字協定


@geindex PyNumber_Check (C function)
@anchor{c-api/number c PyNumber_Check}@anchor{c53}
@deffn {C 函式} int PyNumber_Check (PyObject *o)
` 為 @ref{76e,,穩定 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{4ee7}
@deffn {C 函式} @ref{5d7,,PyObject} *PyNumber_Add (PyObject *o1, PyObject *o2)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{4f01}
@deffn {C 函式} @ref{5d7,,PyObject} *PyNumber_Subtract (PyObject *o1, PyObject *o2)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{4efa}
@deffn {C 函式} @ref{5d7,,PyObject} *PyNumber_Multiply (PyObject *o1, PyObject *o2)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{10b1}
@deffn {C 函式} @ref{5d7,,PyObject} *PyNumber_MatrixMultiply (PyObject *o1, PyObject *o2)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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}.


在 3.5 版被加入.

@end deffn

@geindex PyNumber_FloorDivide (C function)
@anchor{c-api/number c PyNumber_FloorDivide}@anchor{4eeb}
@deffn {C 函式} @ref{5d7,,PyObject} *PyNumber_FloorDivide (PyObject *o1, PyObject *o2)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{4f02}
@deffn {C 函式} @ref{5d7,,PyObject} *PyNumber_TrueDivide (PyObject *o1, PyObject *o2)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{4eff}
@deffn {C 函式} @ref{5d7,,PyObject} *PyNumber_Remainder (PyObject *o1, PyObject *o2)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{4eea}
@deffn {C 函式} @ref{5d7,,PyObject} *PyNumber_Divmod (PyObject *o1, PyObject *o2)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
@geindex built-in function（內建函式）;divmod

See the built-in function @ref{b90,,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{4efe}
@deffn {C 函式} @ref{5d7,,PyObject} *PyNumber_Power (PyObject *o1, PyObject *o2, PyObject *o3)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
@geindex built-in function（內建函式）;pow

See the built-in function @ref{1a4,,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{4d67,,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{4efb}
@deffn {C 函式} @ref{5d7,,PyObject} *PyNumber_Negative (PyObject *o)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{4efd}
@deffn {C 函式} @ref{5d7,,PyObject} *PyNumber_Positive (PyObject *o)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{4ee6}
@deffn {C 函式} @ref{5d7,,PyObject} *PyNumber_Absolute (PyObject *o)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{4ef8}
@deffn {C 函式} @ref{5d7,,PyObject} *PyNumber_Invert (PyObject *o)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{4ef9}
@deffn {C 函式} @ref{5d7,,PyObject} *PyNumber_Lshift (PyObject *o1, PyObject *o2)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{4f00}
@deffn {C 函式} @ref{5d7,,PyObject} *PyNumber_Rshift (PyObject *o1, PyObject *o2)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{4ee8}
@deffn {C 函式} @ref{5d7,,PyObject} *PyNumber_And (PyObject *o1, PyObject *o2)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{4f03}
@deffn {C 函式} @ref{5d7,,PyObject} *PyNumber_Xor (PyObject *o1, PyObject *o2)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{4efc}
@deffn {C 函式} @ref{5d7,,PyObject} *PyNumber_Or (PyObject *o1, PyObject *o2)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{4eec}
@deffn {C 函式} @ref{5d7,,PyObject} *PyNumber_InPlaceAdd (PyObject *o1, PyObject *o2)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{4ef5}
@deffn {C 函式} @ref{5d7,,PyObject} *PyNumber_InPlaceSubtract (PyObject *o1, PyObject *o2)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{4ef0}
@deffn {C 函式} @ref{5d7,,PyObject} *PyNumber_InPlaceMultiply (PyObject *o1, PyObject *o2)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{10b2}
@deffn {C 函式} @ref{5d7,,PyObject} *PyNumber_InPlaceMatrixMultiply (PyObject *o1, PyObject *o2)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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}.


在 3.5 版被加入.

@end deffn

@geindex PyNumber_InPlaceFloorDivide (C function)
@anchor{c-api/number c PyNumber_InPlaceFloorDivide}@anchor{4eee}
@deffn {C 函式} @ref{5d7,,PyObject} *PyNumber_InPlaceFloorDivide (PyObject *o1, PyObject *o2)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{4ef6}
@deffn {C 函式} @ref{5d7,,PyObject} *PyNumber_InPlaceTrueDivide (PyObject *o1, PyObject *o2)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{4ef3}
@deffn {C 函式} @ref{5d7,,PyObject} *PyNumber_InPlaceRemainder (PyObject *o1, PyObject *o2)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{4ef2}
@deffn {C 函式} @ref{5d7,,PyObject} *PyNumber_InPlacePower (PyObject *o1, PyObject *o2, PyObject *o3)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
@geindex built-in function（內建函式）;pow

See the built-in function @ref{1a4,,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{4d67,,Py_None}, or an in-place variant of
@code{pow(o1, o2, o3)} otherwise. If `o3' is to be ignored, pass @ref{4d67,,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{4eef}
@deffn {C 函式} @ref{5d7,,PyObject} *PyNumber_InPlaceLshift (PyObject *o1, PyObject *o2)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{4ef4}
@deffn {C 函式} @ref{5d7,,PyObject} *PyNumber_InPlaceRshift (PyObject *o1, PyObject *o2)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{4eed}
@deffn {C 函式} @ref{5d7,,PyObject} *PyNumber_InPlaceAnd (PyObject *o1, PyObject *o2)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{4ef7}
@deffn {C 函式} @ref{5d7,,PyObject} *PyNumber_InPlaceXor (PyObject *o1, PyObject *o2)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{4ef1}
@deffn {C 函式} @ref{5d7,,PyObject} *PyNumber_InPlaceOr (PyObject *o1, PyObject *o2)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{c54}
@deffn {C 函式} @ref{5d7,,PyObject} *PyNumber_Long (PyObject *o)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{c55}
@deffn {C 函式} @ref{5d7,,PyObject} *PyNumber_Float (PyObject *o)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{a8a}
@deffn {C 函式} @ref{5d7,,PyObject} *PyNumber_Index (PyObject *o)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Returns the `o' converted to a Python int on success or @code{NULL} with a
@ref{198,,TypeError} exception raised on failure.


在 3.10 版的變更: The result always has exact type @ref{19b,,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{1aa2}
@deffn {C 函式} @ref{5d7,,PyObject} *PyNumber_ToBase (PyObject *n, int base)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{a8a,,PyNumber_Index()} first.
@end deffn

@geindex PyNumber_AsSsize_t (C function)
@anchor{c-api/number c PyNumber_AsSsize_t}@anchor{4ee9}
@deffn {C 函式} @ref{c4c,,Py_ssize_t} PyNumber_AsSsize_t (PyObject *o, PyObject *exc)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Returns `o' converted to a @ref{c4c,,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{c4c,,Py_ssize_t} value would raise an @ref{a78,,OverflowError}, then the
`exc' argument is the type of exception that will be raised (usually
@ref{1729,,IndexError} or @ref{a78,,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{b78}
@deffn {C 函式} int PyIndex_Check (PyObject *o)
` 為 @ref{76e,,穩定 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 序列協定,對映協定,數字協定,抽象物件層 Abstract Objects Layer
@anchor{c-api/sequence doc}@anchor{5085}@anchor{c-api/sequence sequence}@anchor{5086}@anchor{c-api/sequence sequence-protocol}@anchor{5087}@anchor{c-api/sequence translation-repo}@anchor{5088}
@subsection 序列協定


@geindex PySequence_Check (C function)
@anchor{c-api/sequence c PySequence_Check}@anchor{4f1f}
@deffn {C 函式} int PySequence_Check (PyObject *o)
` 為 @ref{76e,,穩定 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{582,,__getitem__()}
method, unless they are @ref{183,,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{1cfa}
@deffn {C 函式} @ref{c4c,,Py_ssize_t} PySequence_Size (PyObject *o)
@anchor{c-api/sequence c PySequence_Length}@anchor{4f27}
@deffnx {C 函式} @ref{c4c,,Py_ssize_t} PySequence_Length (PyObject *o)
` 為 @ref{76e,,穩定 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{4f20}
@deffn {C 函式} @ref{5d7,,PyObject} *PySequence_Concat (PyObject *o1, PyObject *o2)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{4f29}
@deffn {C 函式} @ref{5d7,,PyObject} *PySequence_Repeat (PyObject *o, Py_ssize_t count)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{4f24}
@deffn {C 函式} @ref{5d7,,PyObject} *PySequence_InPlaceConcat (PyObject *o1, PyObject *o2)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{4f25}
@deffn {C 函式} @ref{5d7,,PyObject} *PySequence_InPlaceRepeat (PyObject *o, Py_ssize_t count)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{1cfb}
@deffn {C 函式} @ref{5d7,,PyObject} *PySequence_GetItem (PyObject *o, Py_ssize_t i)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{4f23}
@deffn {C 函式} @ref{5d7,,PyObject} *PySequence_GetSlice (PyObject *o, Py_ssize_t i1, Py_ssize_t i2)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{1cfc}
@deffn {C 函式} int PySequence_SetItem (PyObject *o, Py_ssize_t i, PyObject *v)
` 為 @ref{76e,,穩定 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{1cfd,,PySequence_DelItem()}.
@end deffn

@geindex PySequence_DelItem (C function)
@anchor{c-api/sequence c PySequence_DelItem}@anchor{1cfd}
@deffn {C 函式} int PySequence_DelItem (PyObject *o, Py_ssize_t i)
` 為 @ref{76e,,穩定 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{4f2a}
@deffn {C 函式} int PySequence_SetSlice (PyObject *o, Py_ssize_t i1, Py_ssize_t i2, PyObject *v)
` 為 @ref{76e,,穩定 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{4f22}
@deffn {C 函式} int PySequence_DelSlice (PyObject *o, Py_ssize_t i1, Py_ssize_t i2)
` 為 @ref{76e,,穩定 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{4f21}
@deffn {C 函式} @ref{c4c,,Py_ssize_t} PySequence_Count (PyObject *o, PyObject *value)
` 為 @ref{76e,,穩定 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{3d7}
@deffn {C 函式} int PySequence_Contains (PyObject *o, PyObject *value)
` 為 @ref{76e,,穩定 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{3d6}
@deffn {C 函式} int PySequence_In (PyObject *o, PyObject *value)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@ref{3d7,,PySequence_Contains()} 的別名。


在 3.14 版之後被棄用: The function is @ref{23d,,soft deprecated} and should no longer be used to
write new code.

@end deffn

@geindex PySequence_Index (C function)
@anchor{c-api/sequence c PySequence_Index}@anchor{4f26}
@deffn {C 函式} @ref{c4c,,Py_ssize_t} PySequence_Index (PyObject *o, PyObject *value)
` 為 @ref{76e,,穩定 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{4f28}
@deffn {C 函式} @ref{5d7,,PyObject} *PySequence_List (PyObject *o)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{4f2b}
@deffn {C 函式} @ref{5d7,,PyObject} *PySequence_Tuple (PyObject *o)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{1817}
@deffn {C 函式} @ref{5d7,,PyObject} *PySequence_Fast (PyObject *o, const char *m)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{198,,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{5014,,PyTupleObject} or a @ref{5089,,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{3c8}
@deffn {C 函式} @ref{c4c,,Py_ssize_t} PySequence_Fast_GET_SIZE (PyObject *o)

Returns the length of `o', assuming that `o' was returned by
@ref{1817,,PySequence_Fast()} and that `o' is not @code{NULL}.  The size can also be
retrieved by calling @ref{1cfa,,PySequence_Size()} on `o', but
@ref{3c8,,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{3c9}
@deffn {C 函式} @ref{5d7,,PyObject} *PySequence_Fast_GET_ITEM (PyObject *o, Py_ssize_t i)
`回傳值：借用參照。'
Return the `i'th element of `o', assuming that `o' was returned by
@ref{1817,,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{3ca}
@deffn {C 函式} @ref{5d7,,PyObject} **PySequence_Fast_ITEMS (PyObject *o)

Return the underlying array of PyObject pointers.  Assumes that `o' was returned
by @ref{1817,,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{508a}
@deffn {C 函式} @ref{5d7,,PyObject} *PySequence_ITEM (PyObject *o, Py_ssize_t i)
`回傳值：新的參照。'
Return the `i'th element of `o' or @code{NULL} on failure. Faster form of
@ref{1cfb,,PySequence_GetItem()} but without checking that
@ref{4f1f,,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 對映協定,疊代器協定,序列協定,抽象物件層 Abstract Objects Layer
@anchor{c-api/mapping doc}@anchor{508b}@anchor{c-api/mapping mapping}@anchor{508c}@anchor{c-api/mapping mapping-protocol}@anchor{508d}@anchor{c-api/mapping translation-repo}@anchor{508e}
@subsection 對映協定


另請參閱 @ref{5e2,,PyObject_GetItem()}、@ref{4df9,,PyObject_SetItem()} 和 @ref{4f0c,,PyObject_DelItem()}。

@geindex PyMapping_Check (C function)
@anchor{c-api/mapping c PyMapping_Check}@anchor{4ed7}
@deffn {C 函式} int PyMapping_Check (PyObject *o)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
如果物件有提供對映協定或支援切片 (slicing) 則回傳 @code{1}，否則回傳 @code{0}。請注意，對於具有 @ref{582,,__getitem__()} 方法的 Python 類別，它會回傳 @code{1}，因為通常無法確定該類別支援什麼類型的鍵。這個函式總會是成功的。
@end deffn

@geindex PyMapping_Size (C function)
@geindex PyMapping_Length (C function)
@anchor{c-api/mapping c PyMapping_Size}@anchor{1cfe}
@deffn {C 函式} @ref{c4c,,Py_ssize_t} PyMapping_Size (PyObject *o)
@anchor{c-api/mapping c PyMapping_Length}@anchor{4ed8}
@deffnx {C 函式} @ref{c4c,,Py_ssize_t} PyMapping_Length (PyObject *o)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@geindex built-in function（內建函式）;len

成功時回傳物件 `o' 中的鍵數，失敗時回傳 @code{-1}。這相當於 Python 運算式 @code{len(o)}。
@end deffn

@geindex PyMapping_GetItemString (C function)
@anchor{c-api/mapping c PyMapping_GetItemString}@anchor{5e3}
@deffn {C 函式} @ref{5d7,,PyObject} *PyMapping_GetItemString (PyObject *o, const char *key)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
這與 @ref{5e2,,PyObject_GetItem()} 相同，但 `key' 被指定為 const char* UTF-8 編碼位元組字串，而不是 @ref{5d7,,PyObject}*。
@end deffn

@geindex PyMapping_GetOptionalItem (C function)
@anchor{c-api/mapping c PyMapping_GetOptionalItem}@anchor{5e0}
@deffn {C 函式} int PyMapping_GetOptionalItem (PyObject *obj, PyObject *key, PyObject **result)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.13 版本開始.'
Variant of @ref{5e2,,PyObject_GetItem()} which doesn't raise
@ref{5df,,KeyError} if the key is not found.

If the key is found, return @code{1} and set `*result' to a new
@ref{5da,,strong reference} to the corresponding value.
If the key is not found, return @code{0} and set `*result' to @code{NULL};
the @ref{5df,,KeyError} is silenced.
If an error other than @ref{5df,,KeyError} is raised, return @code{-1} and
set `*result' to @code{NULL}.


在 3.13 版被加入.

@end deffn

@geindex PyMapping_GetOptionalItemString (C function)
@anchor{c-api/mapping c PyMapping_GetOptionalItemString}@anchor{5e1}
@deffn {C 函式} int PyMapping_GetOptionalItemString (PyObject *obj, const char *key, PyObject **result)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.13 版本開始.'
這與 @ref{5e0,,PyMapping_GetOptionalItem()} 相同，但 `key' 被指定為 const char* UTF-8 編碼位元組字串，而不是 @ref{5d7,,PyObject}*。


在 3.13 版被加入.

@end deffn

@geindex PyMapping_SetItemString (C function)
@anchor{c-api/mapping c PyMapping_SetItemString}@anchor{4ed9}
@deffn {C 函式} int PyMapping_SetItemString (PyObject *o, const char *key, PyObject *v)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
這與 @ref{4df9,,PyObject_SetItem()} 相同，但 `key' 被指定為 const char* UTF-8 編碼位元組字串，而不是 @ref{5d7,,PyObject}*。
@end deffn

@geindex PyMapping_DelItem (C function)
@anchor{c-api/mapping c PyMapping_DelItem}@anchor{508f}
@deffn {C 函式} int PyMapping_DelItem (PyObject *o, PyObject *key)

這是 @ref{4f0c,,PyObject_DelItem()} 的別名。
@end deffn

@geindex PyMapping_DelItemString (C function)
@anchor{c-api/mapping c PyMapping_DelItemString}@anchor{5090}
@deffn {C 函式} int PyMapping_DelItemString (PyObject *o, const char *key)

這與 @ref{4f0c,,PyObject_DelItem()} 相同，但 `key' 被指定為 const char* UTF-8 編碼位元組字串，而不是 @ref{5d7,,PyObject}*。
@end deffn

@geindex PyMapping_HasKeyWithError (C function)
@anchor{c-api/mapping c PyMapping_HasKeyWithError}@anchor{617}
@deffn {C 函式} int PyMapping_HasKeyWithError (PyObject *o, PyObject *key)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.13 版本開始.'
如果對映物件具有鍵 `key' 則回傳 @code{1}，否則回傳 @code{0}。這相當於 Python 運算式 @code{key in o}。失敗時回傳 @code{-1}。


在 3.13 版被加入.

@end deffn

@geindex PyMapping_HasKeyStringWithError (C function)
@anchor{c-api/mapping c PyMapping_HasKeyStringWithError}@anchor{619}
@deffn {C 函式} int PyMapping_HasKeyStringWithError (PyObject *o, const char *key)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.13 版本開始.'
這與 @ref{617,,PyMapping_HasKeyWithError()} 相同，但 `key' 被指定為 const char* UTF-8 編碼位元組字串，而不是 @ref{5d7,,PyObject}*。


在 3.13 版被加入.

@end deffn

@geindex PyMapping_HasKey (C function)
@anchor{c-api/mapping c PyMapping_HasKey}@anchor{618}
@deffn {C 函式} int PyMapping_HasKey (PyObject *o, PyObject *key)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
如果對映物件具有鍵 `key' 則回傳 @code{1}，否則回傳 @code{0}。這相當於 Python 運算式 @code{key in o}。這個函式總會是成功的。

@cartouche
@quotation 備註 
當它呼叫 @ref{582,,__getitem__()} 方法時發生的例外將被默默忽略。為了適當地處理錯誤，請改用 @ref{617,,PyMapping_HasKeyWithError()}、@ref{5e0,,PyMapping_GetOptionalItem()} 或 @ref{5e2,,PyObject_GetItem()}。
@end quotation
@end cartouche
@end deffn

@geindex PyMapping_HasKeyString (C function)
@anchor{c-api/mapping c PyMapping_HasKeyString}@anchor{61a}
@deffn {C 函式} int PyMapping_HasKeyString (PyObject *o, const char *key)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
這與 @ref{618,,PyMapping_HasKey()} 相同，但 `key' 被指定為 const char* UTF-8 編碼位元組字串，而不是 @ref{5d7,,PyObject}*。

@cartouche
@quotation 備註 
當它呼叫 @ref{582,,__getitem__()} 方法或建立臨時 @ref{169,,str} 物件時發生的例外將被默默忽略。為了適當地處理錯誤，請改用 @ref{619,,PyMapping_HasKeyStringWithError()}、@ref{5e1,,PyMapping_GetOptionalItemString()} 或 @ref{5e3,,PyMapping_GetItemString()}。
@end quotation
@end cartouche
@end deffn

@geindex PyMapping_Keys (C function)
@anchor{c-api/mapping c PyMapping_Keys}@anchor{db0}
@deffn {C 函式} @ref{5d7,,PyObject} *PyMapping_Keys (PyObject *o)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
成功時回傳一個物件 `o' 內之鍵的串列，失敗時回傳 @code{NULL}。


在 3.7 版的變更: 在以前，該函式會回傳串列或元組。

@end deffn

@geindex PyMapping_Values (C function)
@anchor{c-api/mapping c PyMapping_Values}@anchor{db1}
@deffn {C 函式} @ref{5d7,,PyObject} *PyMapping_Values (PyObject *o)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
成功時回傳物件 `o' 中值的串列。失敗時回傳 @code{NULL}。


在 3.7 版的變更: 在以前，該函式會回傳串列或元組。

@end deffn

@geindex PyMapping_Items (C function)
@anchor{c-api/mapping c PyMapping_Items}@anchor{db2}
@deffn {C 函式} @ref{5d7,,PyObject} *PyMapping_Items (PyObject *o)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
成功時回傳物件 `o' 內之項目的串列，其中每個項目都是包含鍵值對的元組。失敗時回傳 @code{NULL}。


在 3.7 版的變更: 在以前，該函式會回傳串列或元組。

@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 疊代器協定,緩衝協定 Buffer Protocol,對映協定,抽象物件層 Abstract Objects Layer
@anchor{c-api/iter doc}@anchor{5091}@anchor{c-api/iter iterator}@anchor{5092}@anchor{c-api/iter iterator-protocol}@anchor{5093}@anchor{c-api/iter translation-repo}@anchor{5094}
@subsection 疊代器協定


有兩個專門用於疊代器的函式。

@geindex PyIter_Check (C function)
@anchor{c-api/iter c PyIter_Check}@anchor{1baa}
@deffn {C 函式} int PyIter_Check (PyObject *o)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.8 版本開始.'
如果物件 `o' 可以安全地傳遞給 @ref{396,,PyIter_NextItem()} 則回傳非零 (non-zero)，否則回傳 0。這個函式一定會執行成功。
@end deffn

@geindex PyAIter_Check (C function)
@anchor{c-api/iter c PyAIter_Check}@anchor{4e14}
@deffn {C 函式} int PyAIter_Check (PyObject *o)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.10 版本開始.'
如果物件 `o' 有提供 @code{AsyncIterator} 協定，則回傳非零，否則回傳 0。這個函式一定會執行成功。


在 3.10 版被加入.

@end deffn

@geindex PyIter_NextItem (C function)
@anchor{c-api/iter c PyIter_NextItem}@anchor{396}
@deffn {C 函式} int PyIter_NextItem (PyObject *iter, PyObject **item)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.14 版本開始.'
Return @code{1} and set `item' to a @ref{5da,,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.


在 3.14 版被加入.

@end deffn

@geindex PyIter_Next (C function)
@anchor{c-api/iter c PyIter_Next}@anchor{397}
@deffn {C 函式} @ref{5d7,,PyObject} *PyIter_Next (PyObject *o)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
這是 @code{PyIter_NextItem()} 的舊版本，為了向後相容而保留。請優先使用 @ref{396,,PyIter_NextItem()}。

回傳疊代器 `o' 的下一個值。根據 @ref{1baa,,PyIter_Check()}，該物件必須是一個疊代器（由呼叫者檢查）。如果沒有剩餘值，則回傳 @code{NULL} 且不設定例外。如果檢索項目時發生錯誤，則回傳 @code{NULL} 並傳遞例外。
@end deffn

@geindex PySendResult (C type)
@anchor{c-api/iter c PySendResult}@anchor{5095}
@deffn {C 型別} type PySendResult

用於表示 @ref{a8f,,PyIter_Send()} 不同結果的列舉 (enum) 值。


在 3.10 版被加入.

@end deffn

@geindex PyIter_Send (C function)
@anchor{c-api/iter c PyIter_Send}@anchor{a8f}
@deffn {C 函式} @ref{5095,,PySendResult} PyIter_Send (PyObject *iter, PyObject *arg, PyObject **presult)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.10 版本開始.'
將 `arg' 值發送到疊代器 `iter' 中。回傳：


@itemize -

@item 
如果疊代器有回傳則為 @code{PYGEN_RETURN}。回傳值透過 `presult' 回傳。

@item 
如果疊代器有產生 (yield) 則為 @code{PYGEN_NEXT}。產生值透過 `presult' 回傳。

@item 
如果疊代器引發例外則為 @code{PYGEN_ERROR}。 `presult' 被設定為 @code{NULL}。
@end itemize


在 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（緩衝介面）;(請見緩衝協定)
@geindex buffer object（緩衝物件）;(請見緩衝協定)

@node 緩衝協定 Buffer Protocol,,疊代器協定,抽象物件層 Abstract Objects Layer
@anchor{c-api/buffer doc}@anchor{5096}@anchor{c-api/buffer buffer-protocol}@anchor{5097}@anchor{c-api/buffer bufferobjects}@anchor{260}@anchor{c-api/buffer translation-repo}@anchor{5098}
@subsection 緩衝協定 (Buffer Protocol)


Certain objects available in Python wrap access to an underlying memory
array or `buffer'.  Such objects include the built-in @ref{192,,bytes} and
@ref{343,,bytearray}, and some extension types like @ref{4b9,,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{260,,buffer protocol}.  This protocol has two sides:

@geindex PyBufferProcs（C 型別）


@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{5099,,緩衝區物件結構}; for
Python see @ref{22c0,,Emulating buffer types}.

@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{165,,memoryview}.
@end itemize

Simple objects such as @ref{192,,bytes} and @ref{343,,bytearray} expose their
underlying buffer in byte-oriented form.  Other forms are possible; for example,
the elements exposed by an @ref{4b9,,array.array} can be multi-byte values.

An example consumer of the buffer interface is the @ref{ed2,,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{180e,,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{632,,PyObject_GetBuffer()} with the right parameters;

@item 
call @ref{3bf,,PyArg_ParseTuple()} (or one of its siblings) with one of the
@code{y*}, @code{w*} or @code{s*} @ref{3d3,,format codes}.
@end itemize

In both cases, @ref{633,,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.


在 3.12 版被加入: The buffer protocol is now accessible in Python, see
@ref{22c0,,Emulating buffer types} and @ref{165,,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{509a}@anchor{c-api/buffer id1}@anchor{509b}
@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{5d7,,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{509c,,memoryview} object
can be created.

For short instructions how to write an exporting object, see
@ref{5099,,Buffer Object Structures}. For obtaining
a buffer, see @ref{632,,PyObject_GetBuffer()}.

@geindex Py_buffer (C type)
@anchor{c-api/buffer c Py_buffer}@anchor{954}
@deffn {C 型別} type Py_buffer
` 為 @ref{76e,,穩定 ABI 的一部分} （包含所有成員） 自 3.11 版本開始.'
@geindex Py_buffer.buf (C member)
@anchor{c-api/buffer c Py_buffer buf}@anchor{509d}
@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{509e,,strides}
the value may point to the end of the memory block.

For @ref{2535,,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{509f}
@deffn {C 成員函數} @ref{5d7,,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{633,,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{95d,,PyMemoryView_FromBuffer()} or @ref{95c,,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{50a0}
@deffn {C 成員函數} @ref{c4c,,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{50a1,,PyBUF_SIMPLE} or @ref{15ad,,PyBUF_WRITABLE}.
@end deffn

@geindex Py_buffer.readonly (C member)
@anchor{c-api/buffer c Py_buffer readonly}@anchor{50a2}
@deffn {C 成員函數} int readonly

An indicator of whether the buffer is read-only. This field is controlled
by the @ref{15ad,,PyBUF_WRITABLE} flag.
@end deffn

@geindex Py_buffer.itemsize (C member)
@anchor{c-api/buffer c Py_buffer itemsize}@anchor{50a3}
@deffn {C 成員函數} @ref{c4c,,Py_ssize_t} itemsize

Item size in bytes of a single element. Same as the value of @ref{1c72,,struct.calcsize()}
called on non-@code{NULL} @ref{50a4,,format} values.

Important exception: If a consumer requests a buffer without the
@ref{50a5,,PyBUF_FORMAT} flag, @ref{50a4,,format} will
be set to  @code{NULL},  but @ref{50a3,,itemsize} still has
the value for the original format.

If @ref{50a6,,shape} is present, the equality
@code{product(shape) * itemsize == len} still holds and the consumer
can use @ref{50a3,,itemsize} to navigate the buffer.

If @ref{50a6,,shape} is @code{NULL} as a result of a @ref{50a1,,PyBUF_SIMPLE}
or a @ref{15ad,,PyBUF_WRITABLE} request, the consumer must disregard
@ref{50a3,,itemsize} and assume @code{itemsize == 1}.
@end deffn

@geindex Py_buffer.format (C member)
@anchor{c-api/buffer c Py_buffer format}@anchor{50a4}
@deffn {C 成員函數} char *format

A `NULL' terminated string in @ref{db,,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{50a5,,PyBUF_FORMAT} flag.
@end deffn

@geindex Py_buffer.ndim (C member)
@anchor{c-api/buffer c Py_buffer ndim}@anchor{50a7}
@deffn {C 成員函數} int ndim

The number of dimensions the memory represents as an n-dimensional array.
If it is @code{0}, @ref{509d,,buf} points to a single item representing
a scalar. In this case, @ref{50a6,,shape}, @ref{509e,,strides}
and @ref{50a8,,suboffsets} MUST be @code{NULL}.
The maximum number of dimensions is given by @ref{50a9,,PyBUF_MAX_NDIM}.
@end deffn

@geindex Py_buffer.shape (C member)
@anchor{c-api/buffer c Py_buffer shape}@anchor{50a6}
@deffn {C 成員函數} @ref{c4c,,Py_ssize_t} *shape

An array of @ref{c4c,,Py_ssize_t} of length @ref{50a7,,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{50a0,,len}.

Shape values are restricted to @code{shape[n] >= 0}. The case
@code{shape[n] == 0} requires special attention. See @ref{50aa,,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{509e}
@deffn {C 成員函數} @ref{c4c,,Py_ssize_t} *strides

An array of @ref{c4c,,Py_ssize_t} of length @ref{50a7,,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{50aa,,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{50a8}
@deffn {C 成員函數} @ref{c4c,,Py_ssize_t} *suboffsets

An array of @ref{c4c,,Py_ssize_t} of length @ref{50a7,,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{50aa,,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{50ab}
@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

常數：

@geindex PyBUF_MAX_NDIM (C macro)
@anchor{c-api/buffer c PyBUF_MAX_NDIM}@anchor{50a9}
@deffn {C 巨集} PyBUF_MAX_NDIM

The maximum number of dimensions the memory represents.
Exporters MUST respect this limit, consumers of multi-dimensional
buffers SHOULD be able to handle up to @code{PyBUF_MAX_NDIM} dimensions.
Currently set to 64.
@end deffn

@node Buffer request types,Complex arrays,Buffer structure,緩衝協定 Buffer Protocol
@anchor{c-api/buffer buffer-request-types}@anchor{4915}@anchor{c-api/buffer id2}@anchor{50ac}
@subsubsection Buffer request types


Buffers are usually obtained by sending a buffer request to an exporting
object via @ref{632,,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{954,,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{50ad}
@subsubsection request-independent fields


The following fields are not influenced by `flags' and must always be filled in
with the correct values: @ref{509f,,obj}, @ref{509d,,buf},
@ref{50a0,,len}, @ref{50a3,,itemsize}, @ref{50a7,,ndim}.

@node readonly format,shape strides suboffsets,request-independent fields,Buffer request types
@anchor{c-api/buffer readonly-format}@anchor{50ae}
@subsubsection readonly, format


@quotation

@geindex PyBUF_WRITABLE (C macro)
@anchor{c-api/buffer c PyBUF_WRITABLE}@anchor{15ad}
@deffn {C 巨集} PyBUF_WRITABLE

Controls the @ref{50a2,,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{50a1,,PyBUF_SIMPLE} | @ref{15ad,,PyBUF_WRITABLE}
can be used to request a simple writable buffer.
@end deffn

@geindex PyBUF_FORMAT (C macro)
@anchor{c-api/buffer c PyBUF_FORMAT}@anchor{50a5}
@deffn {C 巨集} PyBUF_FORMAT

Controls the @ref{50a4,,format} field. If set, this field MUST
be filled in correctly. Otherwise, this field MUST be @code{NULL}.
@end deffn
@end quotation

@ref{15ad,,PyBUF_WRITABLE} can be |'d to any of the flags in the next section.
Since @ref{50a1,,PyBUF_SIMPLE} is defined as 0, @ref{15ad,,PyBUF_WRITABLE}
can be used as a stand-alone flag to request a simple writable buffer.

@ref{50a5,,PyBUF_FORMAT} must be |'d to any of the flags except @ref{50a1,,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{50af}
@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{50b0}
@deffn {C 巨集} PyBUF_INDIRECT
@end deffn

@tab

yes

@tab

yes

@tab

if needed

@item

@geindex PyBUF_STRIDES (C macro)
@anchor{c-api/buffer c PyBUF_STRIDES}@anchor{50b1}
@deffn {C 巨集} PyBUF_STRIDES
@end deffn

@tab

yes

@tab

yes

@tab

NULL

@item

@geindex PyBUF_ND (C macro)
@anchor{c-api/buffer c PyBUF_ND}@anchor{50b2}
@deffn {C 巨集} PyBUF_ND
@end deffn

@tab

yes

@tab

NULL

@tab

NULL

@item

@geindex PyBUF_SIMPLE (C macro)
@anchor{c-api/buffer c PyBUF_SIMPLE}@anchor{50a1}
@deffn {C 巨集} PyBUF_SIMPLE
@end deffn

@tab

NULL

@tab

NULL

@tab

NULL

@end multitable


@geindex contiguous（連續的）
@geindex C-contiguous（C 連續的）
@geindex Fortran contiguous（Fortran 連續的）

@node contiguity requests,compound requests,shape strides suboffsets,Buffer request types
@anchor{c-api/buffer contiguity-requests}@anchor{50b3}
@subsubsection contiguity requests


C or Fortran @ref{2535,,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{15ae}
@deffn {C 巨集} PyBUF_C_CONTIGUOUS
@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{15af}
@deffn {C 巨集} PyBUF_F_CONTIGUOUS
@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{50b4}
@deffn {C 巨集} PyBUF_ANY_CONTIGUOUS
@end deffn

@tab

yes

@tab

yes

@tab

NULL

@tab

C 或 F

@item

@ref{50b2,,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{50b5}
@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{95a,,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{50b6}
@deffn {C 巨集} PyBUF_FULL
@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{50b7}
@deffn {C 巨集} PyBUF_FULL_RO
@end deffn

@tab

yes

@tab

yes

@tab

if needed

@tab

U

@tab

1 或 0

@tab

yes

@item

@geindex PyBUF_RECORDS (C macro)
@anchor{c-api/buffer c PyBUF_RECORDS}@anchor{50b8}
@deffn {C 巨集} PyBUF_RECORDS
@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{50b9}
@deffn {C 巨集} PyBUF_RECORDS_RO
@end deffn

@tab

yes

@tab

yes

@tab

NULL

@tab

U

@tab

1 或 0

@tab

yes

@item

@geindex PyBUF_STRIDED (C macro)
@anchor{c-api/buffer c PyBUF_STRIDED}@anchor{50ba}
@deffn {C 巨集} PyBUF_STRIDED
@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{50bb}
@deffn {C 巨集} PyBUF_STRIDED_RO
@end deffn

@tab

yes

@tab

yes

@tab

NULL

@tab

U

@tab

1 或 0

@tab

NULL

@item

@geindex PyBUF_CONTIG (C macro)
@anchor{c-api/buffer c PyBUF_CONTIG}@anchor{50bc}
@deffn {C 巨集} PyBUF_CONTIG
@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{50bd}
@deffn {C 巨集} PyBUF_CONTIG_RO
@end deffn

@tab

yes

@tab

NULL

@tab

NULL

@tab

C

@tab

1 或 0

@tab

NULL

@end multitable


@node Complex arrays,Buffer-related functions,Buffer request types,緩衝協定 Buffer Protocol
@anchor{c-api/buffer complex-arrays}@anchor{50aa}
@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{50be}
@subsubsection NumPy-style: shape and strides


The logical structure of NumPy-style arrays is defined by @ref{50a3,,itemsize},
@ref{50a7,,ndim}, @ref{50a6,,shape} and @ref{509e,,strides}.

If @code{ndim == 0}, the memory location pointed to by @ref{509d,,buf} is
interpreted as a scalar of size @ref{50a3,,itemsize}. In that case,
both @ref{50a6,,shape} and @ref{509e,,strides} are @code{NULL}.

If @ref{509e,,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{509d,,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{50bf}
@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{509d,,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{50c0}
@subsubsection Buffer-related functions


@geindex PyObject_CheckBuffer (C function)
@anchor{c-api/buffer c PyObject_CheckBuffer}@anchor{631}
@deffn {C 函式} int PyObject_CheckBuffer (PyObject *obj)
` 為 @ref{76e,,穩定 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{632,,PyObject_GetBuffer()} will
succeed.  This function always succeeds.
@end deffn

@geindex PyObject_GetBuffer (C function)
@anchor{c-api/buffer c PyObject_GetBuffer}@anchor{632}
@deffn {C 函式} int PyObject_GetBuffer (PyObject *exporter, Py_buffer *view, int flags)
` 為 @ref{76e,,穩定 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{1adb,,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{5099,,Buffer Object Structures}).

Successful calls to @ref{632,,PyObject_GetBuffer()} must be paired with calls
to @ref{633,,PyBuffer_Release()}, similar to @code{malloc()} and @code{free()}.
Thus, after the consumer is done with the buffer, @ref{633,,PyBuffer_Release()}
must be called exactly once.
@end deffn

@geindex PyBuffer_Release (C function)
@anchor{c-api/buffer c PyBuffer_Release}@anchor{633}
@deffn {C 函式} void PyBuffer_Release (Py_buffer *view)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.11 版本開始.'
Release the buffer `view' and release the @ref{5da,,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{632,,PyObject_GetBuffer()}.
@end deffn

@geindex PyBuffer_SizeFromFormat (C function)
@anchor{c-api/buffer c PyBuffer_SizeFromFormat}@anchor{956}
@deffn {C 函式} @ref{c4c,,Py_ssize_t} PyBuffer_SizeFromFormat (const char *format)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.11 版本開始.'
Return the implied @ref{50a3,,itemsize} from @ref{50a4,,format}.
On error, raise an exception and return -1.


在 3.9 版被加入.

@end deffn

@geindex PyBuffer_IsContiguous (C function)
@anchor{c-api/buffer c PyBuffer_IsContiguous}@anchor{95a}
@deffn {C 函式} int PyBuffer_IsContiguous (const Py_buffer *view, char order)
` 為 @ref{76e,,穩定 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{2535,,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{955}
@deffn {C 函式} void *PyBuffer_GetPointer (const Py_buffer *view, const Py_ssize_t *indices)
` 為 @ref{76e,,穩定 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{958}
@deffn {C 函式} int PyBuffer_FromContiguous (const Py_buffer *view, const void *buf, Py_ssize_t len, char fort)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.11 版本開始.'
Copy contiguous `len' bytes from `buf' to `view'.
`fort' can be @code{'C'} or @code{'F'} (for C-style or Fortran-style ordering).
@code{0} is returned on success, @code{-1} on error.
@end deffn

@geindex PyBuffer_ToContiguous (C function)
@anchor{c-api/buffer c PyBuffer_ToContiguous}@anchor{957}
@deffn {C 函式} int PyBuffer_ToContiguous (void *buf, const Py_buffer *src, Py_ssize_t len, char order)
` 為 @ref{76e,,穩定 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{959}
@deffn {C 函式} int PyObject_CopyData (PyObject *dest, PyObject *src)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.11 版本開始.'
Copy data from `src' to `dest' buffer. Can convert between C-style and
or Fortran-style buffers.

成功時回傳 @code{0}，錯誤時回傳 @code{-1}。
@end deffn

@geindex PyBuffer_FillContiguousStrides (C function)
@anchor{c-api/buffer c PyBuffer_FillContiguousStrides}@anchor{95b}
@deffn {C 函式} void PyBuffer_FillContiguousStrides (int ndims, Py_ssize_t *shape, Py_ssize_t *strides, int itemsize, char order)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.11 版本開始.'
Fill the `strides' array with byte-strides of a @ref{2535,,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{95c}
@deffn {C 函式} int PyBuffer_FillInfo (Py_buffer *view, PyObject *exporter, void *buf, Py_ssize_t len, int readonly, int flags)
` 為 @ref{76e,,穩定 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{15ad,,PyBUF_WRITABLE} is set in `flags'.

On success, set @code{view->obj} to a new reference to `exporter' and
return 0. Otherwise, raise @ref{1adb,,BufferError}, set
@code{view->obj} to @code{NULL} and return @code{-1};

If this function is used as part of a @ref{5099,,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 具體物件層,初始化、終結化與執行緒,抽象物件層 Abstract Objects Layer,Python/C API 參考手冊
@anchor{c-api/concrete doc}@anchor{50c1}@anchor{c-api/concrete concrete}@anchor{50c2}@anchor{c-api/concrete concrete-objects-layer}@anchor{50c3}@anchor{c-api/concrete translation-repo}@anchor{50c4}
@section 具體物件層


此章節列出的函式僅能接受某些特定的 Python 物件型別，將錯誤型別的物件傳遞給它們並不是什麼好事，如果你從 Python 程式當中接收到一個不確定是否為正確型別的物件，那麼請一定要先做型別檢查。例如使用 @ref{50c5,,PyDict_Check()} 來確認一個物件是否為字典。本章結構類似於 Python 物件型別的"族譜圖 (family tree)"。

@cartouche
@quotation 警告 
雖然本章所述之函式仔細地檢查了傳入物件的型別，但大多並無檢查是否為 @code{NULL}。允許 @code{NULL} 的傳入可能造成記憶體的不合法存取和直譯器的立即中止。
@end quotation
@end cartouche

@menu
* 基礎物件:: 
* 數值物件:: 
* 序列物件:: 
* 容器物件:: 
* 函式物件: 函式物件<2>. 
* 其他物件: 其他物件<2>. 

@end menu

@node 基礎物件,數值物件,,具體物件層
@anchor{c-api/concrete fundamental}@anchor{50c6}@anchor{c-api/concrete fundamental-objects}@anchor{50c7}
@subsection 基礎物件


此段落描述 Python 型別物件與單例 (singleton) 物件 @code{None}。

@menu
* 型別物件:: 
* None 物件:: 

@end menu

@node 型別物件,None 物件,,基礎物件
@anchor{c-api/type doc}@anchor{50c8}@anchor{c-api/type type-objects}@anchor{50c9}@anchor{c-api/type typeobjects}@anchor{50ca}
@subsubsection 型別物件


@geindex object（物件）;type（型別）

@geindex PyTypeObject (C type)
@anchor{c-api/type c PyTypeObject}@anchor{c93}
@deffn {C 型別} type PyTypeObject
` 為 @ref{76e,,受限 API 的一部分} （做為一個不透明結構 (opaque struct)）.'
The C structure of the objects used to describe built-in types.
@end deffn

@geindex PyType_Type (C var)
@anchor{c-api/type c PyType_Type}@anchor{768}
@deffn {C 變數} @ref{c93,,PyTypeObject} PyType_Type
` 為 @ref{76e,,穩定 ABI 的一部分}.'
This is the type object for type objects; it is the same object as
@ref{f3f,,type} in the Python layer.
@end deffn

@geindex PyType_Check (C function)
@anchor{c-api/type c PyType_Check}@anchor{1c50}
@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{1c51}
@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{4f48}
@deffn {C 函式} unsigned int PyType_ClearCache ()
` 為 @ref{76e,,穩定 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{1c09}
@deffn {C 函式} unsigned long PyType_GetFlags (PyTypeObject *type)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return the @ref{1b73,,tp_flags} member of `type'. This function is primarily
meant for use with @code{Py_LIMITED_API}; the individual flag bits are
guaranteed to be stable across Python releases, but access to
@ref{1b73,,tp_flags} itself is not part of the @ref{62f,,limited API}.


在 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{19dd}
@deffn {C 函式} @ref{5d7,,PyObject} *PyType_GetDict (PyTypeObject *type)

Return the type object's internal namespace, which is otherwise only
exposed via a read-only proxy (@ref{e52,,cls.__dict__}).
This is a
replacement for accessing @ref{19de,,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{5e6,,PyObject_GetAttr()}) isn't adequate.

Extension modules should continue to use @code{tp_dict},
directly or indirectly, when setting up their own types.


在 3.12 版被加入.

@end deffn

@geindex PyType_Modified (C function)
@anchor{c-api/type c PyType_Modified}@anchor{1aaa}
@deffn {C 函式} void PyType_Modified (PyTypeObject *type)
` 為 @ref{76e,,穩定 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{77e}
@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{77f,,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{77e,,PyType_AddWatcher()} is not thread-safe,
so it must be called at start up (before spawning the first thread).


在 3.12 版被加入.

@end deffn

@geindex PyType_ClearWatcher (C function)
@anchor{c-api/type c PyType_ClearWatcher}@anchor{50cb}
@deffn {C 函式} int PyType_ClearWatcher (int watcher_id)

Clear watcher identified by `watcher_id' (previously returned from
@ref{77e,,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{77e,,PyType_AddWatcher()}.


在 3.12 版被加入.

@end deffn

@geindex PyType_Watch (C function)
@anchor{c-api/type c PyType_Watch}@anchor{77f}
@deffn {C 函式} int PyType_Watch (int watcher_id, PyObject *type)

Mark `type' as watched. The callback granted `watcher_id' by
@ref{77e,,PyType_AddWatcher()} will be called whenever
@ref{1aaa,,PyType_Modified()} reports a change to `type'. (The callback may be
called only once for a series of consecutive modifications to `type', if
@code{_PyType_Lookup()} is not called on `type' between the modifications;
this is an implementation detail and subject to change.)

An extension should never call @code{PyType_Watch} with a `watcher_id' that was
not returned to it by a previous call to @ref{77e,,PyType_AddWatcher()}.


在 3.12 版被加入.

@end deffn

@geindex PyType_WatchCallback (C type)
@anchor{c-api/type c PyType_WatchCallback}@anchor{50cc}
@deffn {C 型別} typedef int (*PyType_WatchCallback)(@ref{5d7,,PyObject} *type)

Type of a type-watcher callback function.

The callback must not modify `type' or cause @ref{1aaa,,PyType_Modified()} to be
called on `type' or any type in its MRO; violating this rule could cause
infinite recursion.


在 3.12 版被加入.

@end deffn

@geindex PyType_HasFeature (C function)
@anchor{c-api/type c PyType_HasFeature}@anchor{1c08}
@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_IS_GC (C function)
@anchor{c-api/type c PyType_IS_GC}@anchor{50cd}
@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{978,,Py_TPFLAGS_HAVE_GC}.
@end deffn

@geindex PyType_IsSubtype (C function)
@anchor{c-api/type c PyType_IsSubtype}@anchor{4f49}
@deffn {C 函式} int PyType_IsSubtype (PyTypeObject *a, PyTypeObject *b)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return true if `a' is a subtype of `b'.

This function only checks for actual subtypes, which means that
@ref{2279,,__subclasscheck__()} is not called on `b'.  Call
@ref{10a2,,PyObject_IsSubclass()} to do the same check that @ref{9bd,,issubclass()}
would do.
@end deffn

@geindex PyType_GenericAlloc (C function)
@anchor{c-api/type c PyType_GenericAlloc}@anchor{c58}
@deffn {C 函式} @ref{5d7,,PyObject} *PyType_GenericAlloc (PyTypeObject *type, Py_ssize_t nitems)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Generic handler for the @ref{4d98,,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{c57,,PyObject_Init()} or @ref{1c0a,,PyObject_InitVar()}.

Do not call this directly to allocate memory for an object; call the type's
@ref{4d98,,tp_alloc} slot instead.

For types that support garbage collection (i.e., the
@ref{978,,Py_TPFLAGS_HAVE_GC} flag is set), this function behaves like
@ref{c90,,PyObject_GC_New} or @ref{c91,,PyObject_GC_NewVar} (except the
memory is guaranteed to be zeroed before initialization), and should be
paired with @ref{16f7,,PyObject_GC_Del()} in @ref{4d97,,tp_free}.
Otherwise, it behaves like @ref{b73,,PyObject_New} or
@ref{b74,,PyObject_NewVar} (except the memory is guaranteed to be zeroed
before initialization) and should be paired with @ref{e5a,,PyObject_Free()} in
@ref{4d97,,tp_free}.
@end deffn

@geindex PyType_GenericNew (C function)
@anchor{c-api/type c PyType_GenericNew}@anchor{4d94}
@deffn {C 函式} @ref{5d7,,PyObject} *PyType_GenericNew (PyTypeObject *type, PyObject *args, PyObject *kwds)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Generic handler for the @ref{798,,tp_new} slot of a type
object.  Creates a new instance using the type's
@ref{4d98,,tp_alloc} slot and returns the resulting object.
@end deffn

@geindex PyType_Ready (C function)
@anchor{c-api/type c PyType_Ready}@anchor{97a}
@deffn {C 函式} int PyType_Ready (PyTypeObject *type)
` 為 @ref{76e,,穩定 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{978,,Py_TPFLAGS_HAVE_GC} in its flags, then
the GC protocol will be automatically implemented from its parents. On
the contrary, if the type being created does include
@ref{978,,Py_TPFLAGS_HAVE_GC} in its flags then it `must' implement the
GC protocol itself by at least implementing the
@ref{979,,tp_traverse} handle.
@end quotation
@end cartouche
@end deffn

@geindex PyType_GetName (C function)
@anchor{c-api/type c PyType_GetName}@anchor{950}
@deffn {C 函式} @ref{5d7,,PyObject} *PyType_GetName (PyTypeObject *type)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.11 版本開始.'
Return the type's name. Equivalent to getting the type's
@ref{169f,,__name__} attribute.


在 3.11 版被加入.

@end deffn

@geindex PyType_GetQualName (C function)
@anchor{c-api/type c PyType_GetQualName}@anchor{951}
@deffn {C 函式} @ref{5d7,,PyObject} *PyType_GetQualName (PyTypeObject *type)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.11 版本開始.'
Return the type's qualified name. Equivalent to getting the
type's @ref{2225,,__qualname__} attribute.


在 3.11 版被加入.

@end deffn

@geindex PyType_GetFullyQualifiedName (C function)
@anchor{c-api/type c PyType_GetFullyQualifiedName}@anchor{60e}
@deffn {C 函式} @ref{5d7,,PyObject} *PyType_GetFullyQualifiedName (PyTypeObject *type)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.13 版本開始.'
Return the type's fully qualified name. Equivalent to
@code{f"@{type.__module__@}.@{type.__qualname__@}"}, or @ref{2225,,type.__qualname__}
if @ref{60f,,type.__module__} is not a string or is equal to @code{"builtins"}.


在 3.13 版被加入.

@end deffn

@geindex PyType_GetModuleName (C function)
@anchor{c-api/type c PyType_GetModuleName}@anchor{610}
@deffn {C 函式} @ref{5d7,,PyObject} *PyType_GetModuleName (PyTypeObject *type)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.13 版本開始.'
Return the type's module name. Equivalent to getting the
@ref{60f,,type.__module__} attribute.


在 3.13 版被加入.

@end deffn

@geindex PyType_GetSlot (C function)
@anchor{c-api/type c PyType_GetSlot}@anchor{a93}
@deffn {C 函式} void *PyType_GetSlot (PyTypeObject *type, int slot)
` 為 @ref{76e,,穩定 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{50ce,,PyType_Slot.slot} for possible values of the `slot' argument.


在 3.4 版被加入.



在 3.10 版的變更: @ref{a93,,PyType_GetSlot()} can now accept all types.
Previously, it was limited to @ref{b55,,heap types}.

@end deffn

@geindex PyType_GetModule (C function)
@anchor{c-api/type c PyType_GetModule}@anchor{b5d}
@deffn {C 函式} @ref{5d7,,PyObject} *PyType_GetModule (PyTypeObject *type)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.10 版本開始.'
Return the module object associated with the given type when the type was
created using @ref{76c,,PyType_FromModuleAndSpec()}.

If no module is associated with the given type, sets @ref{198,,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{960,,PyCMethod} to get the class that defines the method.
See @ref{62d,,PyType_GetModuleByDef()} for cases when @code{PyCMethod} cannot
be used.


在 3.9 版被加入.

@end deffn

@geindex PyType_GetModuleState (C function)
@anchor{c-api/type c PyType_GetModuleState}@anchor{b5e}
@deffn {C 函式} void *PyType_GetModuleState (PyTypeObject *type)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.10 版本開始.'
Return the state of the module object associated with the given type.
This is a shortcut for calling @ref{b6e,,PyModule_GetState()} on the result
of @ref{b5d,,PyType_GetModule()}.

If no module is associated with the given type, sets @ref{198,,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.


在 3.9 版被加入.

@end deffn

@geindex PyType_GetModuleByDef (C function)
@anchor{c-api/type c PyType_GetModuleByDef}@anchor{62d}
@deffn {C 函式} @ref{5d7,,PyObject} *PyType_GetModuleByDef (PyTypeObject *type, struct PyModuleDef *def)
`回傳值：借用參照。'` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.13 版本開始.'
Find the first superclass whose module was created from
the given @ref{b6b,,PyModuleDef} `def', and return that module.

If no module is found, raises a @ref{198,,TypeError} and returns @code{NULL}.

This function is intended to be used together with
@ref{b6e,,PyModule_GetState()} to get module state from slot methods (such as
@ref{79a,,tp_init} or @ref{50cf,,nb_add})
and other places where a method's defining class cannot be passed using the
@ref{960,,PyCMethod} calling convention.

The returned reference is @ref{3d5,,borrowed} from `type',
and will be valid as long as you hold a reference to `type'.
Do not release it with @ref{789,,Py_DECREF()} or similar.


在 3.11 版被加入.

@end deffn

@geindex PyType_GetBaseByToken (C function)
@anchor{c-api/type c PyType_GetBaseByToken}@anchor{3ae}
@deffn {C 函式} int PyType_GetBaseByToken (PyTypeObject *type, void *token, PyTypeObject **result)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.14 版本開始.'
Find the first superclass in `type''s @ref{248c,,method resolution order} whose
@ref{3af,,Py_tp_token} token is equal to the given one.


@itemize *

@item 
If found, set `*result' to a new @ref{5da,,strong reference}
to it and return @code{1}.

@item 
如果沒找到，則將 `*result' 設為 @code{NULL} 並回傳 @code{0}。

@item 
在發生錯誤時，將 `*result' 設為 @code{NULL} 並回傳 @code{-1}，同時設定例外。
@end itemize

如果 `result' 引數為 @code{NULL}，則不會設定 `*result'。如果你只需要回傳值，請使用此選項。

`token' 引數不可為 @code{NULL}。


在 3.14 版被加入.

@end deffn

@geindex PyUnstable_Type_AssignVersionTag (C function)
@anchor{c-api/type c PyUnstable_Type_AssignVersionTag}@anchor{50d0}
@deffn {C 函式} int PyUnstable_Type_AssignVersionTag (PyTypeObject *type)

@cartouche
@quotation 這是 不穩定 API，它可能在小版本發布中沒有任何警告地被變更。 `這是 @ref{762,,不穩定 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.


在 3.12 版被加入.

@end deffn

@menu
* Creating Heap-Allocated Types:: 

@end menu

@node Creating Heap-Allocated Types,,,型別物件
@anchor{c-api/type creating-heap-allocated-types}@anchor{50d1}
@subsubsection Creating Heap-Allocated Types


The following functions and structs are used to create
@ref{b55,,heap types}.

@geindex PyType_FromMetaclass (C function)
@anchor{c-api/type c PyType_FromMetaclass}@anchor{76b}
@deffn {C 函式} @ref{5d7,,PyObject} *PyType_FromMetaclass (PyTypeObject *metaclass, PyObject *module, PyType_Spec *spec, PyObject *bases)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.12 版本開始.'
Create and return a @ref{b55,,heap type} from the `spec'
(see @ref{aa3,,Py_TPFLAGS_HEAPTYPE}).

The metaclass `metaclass' is used to construct the resulting type object.
When `metaclass' is @code{NULL}, the metaclass is derived from `bases'
(or `Py_tp_base[s]' slots if `bases' is @code{NULL}, see below).

Metaclasses that override @ref{798,,tp_new} are not
supported, except if @code{tp_new} is @code{NULL}.

The `bases' argument can be used to specify base classes; it can either
be only one class or a tuple of classes.
If `bases' is @code{NULL}, the `Py_tp_bases' slot is used instead.
If that also is @code{NULL}, the `Py_tp_base' slot is used instead.
If that also is @code{NULL}, the new type derives from @ref{c75,,object}.

The `module' argument can be used to record the module in which the new
class is defined. It must be a module object or @code{NULL}.
If not @code{NULL}, the module is associated with the new type and can later be
retrieved with @ref{b5d,,PyType_GetModule()}.
The associated module is not inherited by subclasses; it must be specified
for each class individually.

This function calls @ref{97a,,PyType_Ready()} on the new type.

Note that this function does `not' fully match the behavior of
calling @ref{f3f,,type()} or using the @ref{14d8,,class} statement.
With user-provided base types or metaclasses, prefer
@ref{5075,,calling} @ref{f3f,,type} (or the metaclass)
over @code{PyType_From*} functions.
Specifically:


@itemize *

@item 
@ref{799,,__new__()} is not called on the new class
(and it must be set to @code{type.__new__}).

@item 
@ref{8b7,,__init__()} is not called on the new class.

@item 
@ref{83c,,__init_subclass__()} is not called on any bases.

@item 
@ref{e43,,__set_name__()} is not called on new descriptors.
@end itemize


在 3.12 版被加入.

@end deffn

@geindex PyType_FromModuleAndSpec (C function)
@anchor{c-api/type c PyType_FromModuleAndSpec}@anchor{76c}
@deffn {C 函式} @ref{5d7,,PyObject} *PyType_FromModuleAndSpec (PyObject *module, PyType_Spec *spec, PyObject *bases)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.10 版本開始.'
等價於 @code{PyType_FromMetaclass(NULL, module, spec, bases)}。


在 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{f3f,,type} instances were returned.

The @ref{798,,tp_new} of the metaclass is `ignored'.
which may result in incomplete initialization.
Creating classes whose metaclass overrides
@ref{798,,tp_new} is deprecated.



在 3.14 版的變更: Creating classes whose metaclass overrides
@ref{798,,tp_new} is no longer allowed.

@end deffn

@geindex PyType_FromSpecWithBases (C function)
@anchor{c-api/type c PyType_FromSpecWithBases}@anchor{797}
@deffn {C 函式} @ref{5d7,,PyObject} *PyType_FromSpecWithBases (PyType_Spec *spec, PyObject *bases)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.3 版本開始.'
等價於 @code{PyType_FromMetaclass(NULL, NULL, spec, bases)}。


在 3.3 版被加入.



在 3.12 版的變更: The function now finds and uses a metaclass corresponding to the provided
base classes.  Previously, only @ref{f3f,,type} instances were returned.

The @ref{798,,tp_new} of the metaclass is `ignored'.
which may result in incomplete initialization.
Creating classes whose metaclass overrides
@ref{798,,tp_new} is deprecated.



在 3.14 版的變更: Creating classes whose metaclass overrides
@ref{798,,tp_new} is no longer allowed.

@end deffn

@geindex PyType_FromSpec (C function)
@anchor{c-api/type c PyType_FromSpec}@anchor{796}
@deffn {C 函式} @ref{5d7,,PyObject} *PyType_FromSpec (PyType_Spec *spec)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
等價於 @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{f3f,,type} instances were returned.

The @ref{798,,tp_new} of the metaclass is `ignored'.
which may result in incomplete initialization.
Creating classes whose metaclass overrides
@ref{798,,tp_new} is deprecated.



在 3.14 版的變更: Creating classes whose metaclass overrides
@ref{798,,tp_new} is no longer allowed.

@end deffn

@geindex PyType_Freeze (C function)
@anchor{c-api/type c PyType_Freeze}@anchor{3ad}
@deffn {C 函式} int PyType_Freeze (PyTypeObject *type)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.14 版本開始.'
Make a type immutable: set the @ref{3cd,,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.


在 3.14 版被加入.

@end deffn

@geindex PyType_Spec (C type)
@anchor{c-api/type c PyType_Spec}@anchor{19db}
@deffn {C 型別} type PyType_Spec
` 為 @ref{76e,,穩定 ABI 的一部分} （包含所有成員）.'
Structure defining a type's behavior.

@geindex PyType_Spec.name (C member)
@anchor{c-api/type c PyType_Spec name}@anchor{50d2}
@deffn {C 成員函數} const char *name

Name of the type, used to set @ref{1ba8,,PyTypeObject.tp_name}.
@end deffn

@geindex PyType_Spec.basicsize (C member)
@anchor{c-api/type c PyType_Spec basicsize}@anchor{763}
@deffn {C 成員函數} int basicsize

If positive, specifies the size of the instance in bytes.
It is used to set @ref{b75,,PyTypeObject.tp_basicsize}.

If zero, specifies that @ref{b75,,tp_basicsize}
should be inherited.

If negative, the absolute value specifies how much space instances of the
class need `in addition' to the superclass.
Use @ref{764,,PyObject_GetTypeData()} to get a pointer to subclass-specific
memory reserved this way.
For negative @code{basicsize}, Python will insert padding when
needed to meet @ref{b75,,tp_basicsize}'s alignment
requirements.


在 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{50d3}
@deffn {C 成員函數} int itemsize

Size of one element of a variable-size type, in bytes.
Used to set @ref{226d,,PyTypeObject.tp_itemsize}.
See @code{tp_itemsize} documentation for caveats.

If zero, @ref{226d,,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{226d,,tp_itemsize}).

@item 
The requested @ref{763,,PyType_Spec.basicsize} is positive,
suggesting that the memory layout of the base class is known.

@item 
The requested @ref{763,,PyType_Spec.basicsize} is zero,
suggesting that the subclass does not access the instance's memory
directly.

@item 
With the @ref{766,,Py_TPFLAGS_ITEMS_AT_END} flag.
@end itemize
@end deffn

@geindex PyType_Spec.flags (C member)
@anchor{c-api/type c PyType_Spec flags}@anchor{50d4}
@deffn {C 成員函數} unsigned int flags

Type flags, used to set @ref{1b73,,PyTypeObject.tp_flags}.

If the @code{Py_TPFLAGS_HEAPTYPE} flag is not set,
@ref{797,,PyType_FromSpecWithBases()} sets it automatically.
@end deffn

@geindex PyType_Spec.slots (C member)
@anchor{c-api/type c PyType_Spec slots}@anchor{50d5}
@deffn {C 成員函數} @ref{4f4a,,PyType_Slot} *slots

Array of @ref{4f4a,,PyType_Slot} structures.
Terminated by the special slot value @code{@{0, NULL@}}.

Each slot ID should be specified at most once.
@end deffn
@end deffn

@geindex PyType_Slot (C type)
@anchor{c-api/type c PyType_Slot}@anchor{4f4a}
@deffn {C 型別} type PyType_Slot
` 為 @ref{76e,,穩定 ABI 的一部分} （包含所有成員）.'
Structure defining optional functionality of a type, containing a slot ID
and a value pointer.

@geindex PyType_Slot.slot (C member)
@anchor{c-api/type c PyType_Slot slot}@anchor{50ce}
@deffn {C 成員函數} int slot

A slot ID.

Slot IDs are named like the field names of the structures
@ref{c93,,PyTypeObject}, @ref{1615,,PyNumberMethods},
@ref{4dbc,,PySequenceMethods}, @ref{4dbd,,PyMappingMethods} and
@ref{50d6,,PyAsyncMethods} with an added @code{Py_} prefix.
For example, use:


@itemize *

@item 
@code{Py_tp_dealloc} to set @ref{4d84,,PyTypeObject.tp_dealloc}

@item 
@code{Py_nb_add} to set @ref{50cf,,PyNumberMethods.nb_add}

@item 
@code{Py_sq_length} to set @ref{50d7,,PySequenceMethods.sq_length}
@end itemize

An additional slot is supported that does not correspond to a
@code{PyTypeObject} struct field:


@itemize *

@item 
@ref{3af,,Py_tp_token}
@end itemize

The following “offset” fields cannot be set using @ref{4f4a,,PyType_Slot}:


@itemize *

@item 
@ref{b76,,tp_weaklistoffset}
(use @ref{775,,Py_TPFLAGS_MANAGED_WEAKREF} instead if possible)

@item 
@ref{50d8,,tp_dictoffset}（如果可能，請改用 @ref{607,,Py_TPFLAGS_MANAGED_DICT}）

@item 
@ref{5077,,tp_vectorcall_offset}（請用 @ref{50d9,,PyMemberDef} 中的 @code{"__vectorcalloffset__"}）
@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{4d9a,,Py_tp_members}.
See @ref{50d9,,PyMemberDef documentation}
for details.

The following internal fields cannot be set at all when creating a heap
type:


@itemize *

@item 
@ref{19de,,tp_dict},
@ref{50da,,tp_mro},
@ref{50db,,tp_cache},
@ref{78b,,tp_subclasses}, and
@ref{50dc,,tp_weaklist}.
@end itemize

Setting @code{Py_tp_bases} or @code{Py_tp_base} may be
problematic on some platforms.
To avoid issues, use the `bases' argument of
@ref{797,,PyType_FromSpecWithBases()} instead.


在 3.9 版的變更: Slots in @ref{50dd,,PyBufferProcs} may be set in the unlimited API.



在 3.11 版的變更: @ref{95e,,bf_getbuffer} and
@ref{95f,,bf_releasebuffer} are now available
under the @ref{62f,,limited API}.



在 3.14 版的變更: The field @ref{18e4,,tp_vectorcall} can now set
using @code{Py_tp_vectorcall}.  See the field's documentation
for details.

@end deffn

@geindex PyType_Slot.pfunc (C member)
@anchor{c-api/type c PyType_Slot pfunc}@anchor{50de}
@deffn {C 成員函數} void *pfunc

The desired value of the slot. In most cases, this is a pointer
to a function.

`pfunc' values may not be @code{NULL}, except for the following slots:


@itemize *

@item 
@code{Py_tp_doc}

@item 
@ref{3af,,Py_tp_token} (for clarity, prefer @ref{50df,,Py_TP_USE_SPEC}
rather than @code{NULL})
@end itemize
@end deffn
@end deffn

@geindex Py_tp_token (C macro)
@anchor{c-api/type c Py_tp_token}@anchor{3af}
@deffn {C 巨集} Py_tp_token

A @ref{50ce,,slot} that records a static memory layout ID
for a class.

If the @ref{19db,,PyType_Spec} of the class is statically
allocated, the token can be set to the spec using the special value
@ref{50df,,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{3ae,,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{a93,,PyType_GetSlot()} with @code{Py_tp_token}.


在 3.14 版被加入.


@geindex Py_TP_USE_SPEC (C macro)
@anchor{c-api/type c Py_TP_USE_SPEC}@anchor{50df}
@deffn {C 巨集} Py_TP_USE_SPEC

Used as a value with @ref{3af,,Py_tp_token} to set the token to the
class's @ref{19db,,PyType_Spec}.
Expands to @code{NULL}.


在 3.14 版被加入.

@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 None 物件,,型別物件,基礎物件
@anchor{c-api/none doc}@anchor{50e0}@anchor{c-api/none noneobject}@anchor{50e1}@anchor{c-api/none the-none-object}@anchor{50e2}@anchor{c-api/none translation-repo}@anchor{50e3}
@subsubsection @code{None} 物件


@geindex object（物件）;None

Note that the @ref{c93,,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{4d67}
@deffn {C 變數} @ref{5d7,,PyObject} *Py_None

The Python @code{None} object, denoting lack of value.  This object has no methods
and is @ref{290,,immortal}.


在 3.12 版的變更: @ref{4d67,,Py_None} 為@ref{290,,不滅的 (immortal)}。

@end deffn

@geindex Py_RETURN_NONE (C macro)
@anchor{c-api/none c Py_RETURN_NONE}@anchor{1668}
@deffn {C 巨集} Py_RETURN_NONE

Return @ref{4d67,,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 數值物件,序列物件,基礎物件,具體物件層
@anchor{c-api/concrete numeric-objects}@anchor{50e4}@anchor{c-api/concrete numericobjects}@anchor{50e5}
@subsection 數值物件


@geindex object（物件）;numeric（數值）

@menu
* 整數物件:: 
* Boolean（布林）物件:: 
* 浮點數（Floating-Point）物件:: 
* 複數物件:: 

@end menu

@node 整數物件,Boolean（布林）物件,,數值物件
@anchor{c-api/long doc}@anchor{50e6}@anchor{c-api/long integer-objects}@anchor{50e7}@anchor{c-api/long longobjects}@anchor{50e8}
@subsubsection 整數物件


@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{1ba7,,PyErr_Occurred()} to disambiguate.

@geindex PyLongObject (C type)
@anchor{c-api/long c PyLongObject}@anchor{39c}
@deffn {C 型別} type PyLongObject
` 為 @ref{76e,,受限 API 的一部分} （做為一個不透明結構 (opaque struct)）.'
This subtype of @ref{5d7,,PyObject} represents a Python integer object.
@end deffn

@geindex PyLong_Type (C var)
@anchor{c-api/long c PyLong_Type}@anchor{4ed6}
@deffn {C 變數} @ref{c93,,PyTypeObject} PyLong_Type
` 為 @ref{76e,,穩定 ABI 的一部分}.'
This instance of @ref{c93,,PyTypeObject} represents the Python integer type.
This is the same object as @ref{19b,,int} in the Python layer.
@end deffn

@geindex PyLong_Check (C function)
@anchor{c-api/long c PyLong_Check}@anchor{50e9}
@deffn {C 函式} int PyLong_Check (PyObject *p)

Return true if its argument is a @ref{39c,,PyLongObject} or a subtype of
@ref{39c,,PyLongObject}.  This function always succeeds.
@end deffn

@geindex PyLong_CheckExact (C function)
@anchor{c-api/long c PyLong_CheckExact}@anchor{50ea}
@deffn {C 函式} int PyLong_CheckExact (PyObject *p)

Return true if its argument is a @ref{39c,,PyLongObject}, but not a subtype of
@ref{39c,,PyLongObject}.  This function always succeeds.
@end deffn

@geindex PyLong_FromLong (C function)
@anchor{c-api/long c PyLong_FromLong}@anchor{1af0}
@deffn {C 函式} @ref{5d7,,PyObject} *PyLong_FromLong (long v)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return a new @ref{39c,,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{256}.  When you create an int in that range
you actually just get back a reference to the existing object.
@end deffn

@geindex PyLong_FromUnsignedLong (C function)
@anchor{c-api/long c PyLong_FromUnsignedLong}@anchor{1831}
@deffn {C 函式} @ref{5d7,,PyObject} *PyLong_FromUnsignedLong (unsigned long v)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return a new @ref{39c,,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{1815}
@deffn {C 函式} @ref{5d7,,PyObject} *PyLong_FromSsize_t (Py_ssize_t v)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return a new @ref{39c,,PyLongObject} object from a C @ref{c4c,,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{1833}
@deffn {C 函式} @ref{5d7,,PyObject} *PyLong_FromSize_t (size_t v)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return a new @ref{39c,,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{1af1}
@deffn {C 函式} @ref{5d7,,PyObject} *PyLong_FromLongLong (long long v)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return a new @ref{39c,,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{3a1}
@deffn {C 函式} @ref{5d7,,PyObject} *PyLong_FromInt32 (int32_t value)
@anchor{c-api/long c PyLong_FromInt64}@anchor{3a2}
@deffnx {C 函式} @ref{5d7,,PyObject} *PyLong_FromInt64 (int64_t value)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.14 版本開始.'
Return a new @ref{39c,,PyLongObject} object from a signed C
int32_t or int64_t, or @code{NULL}
with an exception set on failure.


在 3.14 版被加入.

@end deffn

@geindex PyLong_FromUnsignedLongLong (C function)
@anchor{c-api/long c PyLong_FromUnsignedLongLong}@anchor{1832}
@deffn {C 函式} @ref{5d7,,PyObject} *PyLong_FromUnsignedLongLong (unsigned long long v)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return a new @ref{39c,,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{3a3}
@deffn {C 函式} @ref{5d7,,PyObject} *PyLong_FromUInt32 (uint32_t value)
@anchor{c-api/long c PyLong_FromUInt64}@anchor{3a4}
@deffnx {C 函式} @ref{5d7,,PyObject} *PyLong_FromUInt64 (uint64_t value)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.14 版本開始.'
Return a new @ref{39c,,PyLongObject} object from an unsigned C
uint32_t or uint64_t, or @code{NULL}
with an exception set on failure.


在 3.14 版被加入.

@end deffn

@geindex PyLong_FromDouble (C function)
@anchor{c-api/long c PyLong_FromDouble}@anchor{b33}
@deffn {C 函式} @ref{5d7,,PyObject} *PyLong_FromDouble (double v)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return a new @ref{39c,,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{4ed3}
@deffn {C 函式} @ref{5d7,,PyObject} *PyLong_FromString (const char *str, char **pend, int base)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return a new @ref{39c,,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{21c0,,Integer literals} definition; in this case, leading
zeros in a non-zero decimal number raises a @ref{2eb,,ValueError}.  If `base' is not
@code{0}, it must be between @code{2} and @code{36}, inclusive.  Leading and trailing
whitespace and single underscores after a base specifier and between digits are
ignored.  If there are no digits or `str' is not NULL-terminated following the
digits and trailing whitespace, @ref{2eb,,ValueError} will be raised.


@subsubheading 也參考


@ref{5fe,,PyLong_AsNativeBytes()} and
@ref{5ff,,PyLong_FromNativeBytes()} functions can be used to convert
a @ref{39c,,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{aae}
@deffn {C 函式} @ref{5d7,,PyObject} *PyLong_FromUnicodeObject (PyObject *u, int base)
`回傳值：新的參照。'
Convert a sequence of Unicode digits in the string `u' to a Python integer
value.


在 3.3 版被加入.

@end deffn

@geindex PyLong_FromVoidPtr (C function)
@anchor{c-api/long c PyLong_FromVoidPtr}@anchor{4ed4}
@deffn {C 函式} @ref{5d7,,PyObject} *PyLong_FromVoidPtr (void *p)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Create a Python integer from the pointer `p'. The pointer value can be
retrieved from the resulting value using @ref{4ed2,,PyLong_AsVoidPtr()}.
@end deffn

@geindex PyLong_FromNativeBytes (C function)
@anchor{c-api/long c PyLong_FromNativeBytes}@anchor{5ff}
@deffn {C 函式} @ref{5d7,,PyObject} *PyLong_FromNativeBytes (const void *buffer, size_t n_bytes, int flags)
` 為 @ref{76e,,穩定 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{5fe,,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{600,,PyLong_FromUnsignedNativeBytes()}. Other flags are ignored.


在 3.13 版被加入.

@end deffn

@geindex PyLong_FromUnsignedNativeBytes (C function)
@anchor{c-api/long c PyLong_FromUnsignedNativeBytes}@anchor{600}
@deffn {C 函式} @ref{5d7,,PyObject} *PyLong_FromUnsignedNativeBytes (const void *buffer, size_t n_bytes, int flags)
` 為 @ref{76e,,穩定 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{5fe,,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.


在 3.13 版被加入.

@end deffn

@geindex PyLong_AsLong (C function)
@anchor{c-api/long c PyLong_AsLong}@anchor{5fd}
@deffn {C 函式} long PyLong_AsLong (PyObject *obj)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@geindex LONG_MAX（C 巨集）
@geindex OverflowError（內建例外）

Return a C long representation of `obj'.  If `obj' is not an
instance of @ref{39c,,PyLongObject}, first call its @ref{19e,,__index__()} method
(if present) to convert it to a @ref{39c,,PyLongObject}.

Raise @ref{a78,,OverflowError} if the value of `obj' is out of range for a
long.

Returns @code{-1} on error.  Use @ref{1ba7,,PyErr_Occurred()} to disambiguate.


在 3.8 版的變更: Use @ref{19e,,__index__()} if available.



在 3.10 版的變更: This function will no longer use @ref{19d,,__int__()}.


@geindex PyLong_AS_LONG (C function)
@anchor{c-api/long c PyLong_AS_LONG}@anchor{50eb}
@deffn {C 函式} long PyLong_AS_LONG (PyObject *obj)

A @ref{23d,,soft deprecated} alias.
Exactly equivalent to the preferred @code{PyLong_AsLong}. In particular,
it can fail with @ref{a78,,OverflowError} or another exception.


在 3.14 版之後被棄用: The function is soft deprecated.

@end deffn
@end deffn

@geindex PyLong_AsInt (C function)
@anchor{c-api/long c PyLong_AsInt}@anchor{5fc}
@deffn {C 函式} int PyLong_AsInt (PyObject *obj)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.13 版本開始.'
Similar to @ref{5fd,,PyLong_AsLong()}, but store the result in a C
int instead of a C long.


在 3.13 版被加入.

@end deffn

@geindex PyLong_AsLongAndOverflow (C function)
@anchor{c-api/long c PyLong_AsLongAndOverflow}@anchor{1467}
@deffn {C 函式} long PyLong_AsLongAndOverflow (PyObject *obj, int *overflow)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return a C long representation of `obj'.  If `obj' is not an
instance of @ref{39c,,PyLongObject}, first call its @ref{19e,,__index__()}
method (if present) to convert it to a @ref{39c,,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{1ba7,,PyErr_Occurred()} to disambiguate.


在 3.8 版的變更: Use @ref{19e,,__index__()} if available.



在 3.10 版的變更: This function will no longer use @ref{19d,,__int__()}.

@end deffn

@geindex PyLong_AsLongLong (C function)
@anchor{c-api/long c PyLong_AsLongLong}@anchor{4ecd}
@deffn {C 函式} long long PyLong_AsLongLong (PyObject *obj)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@geindex OverflowError（內建例外）

Return a C long long representation of `obj'.  If `obj' is not an
instance of @ref{39c,,PyLongObject}, first call its @ref{19e,,__index__()} method
(if present) to convert it to a @ref{39c,,PyLongObject}.

Raise @ref{a78,,OverflowError} if the value of `obj' is out of range for a
long long.

Returns @code{-1} on error.  Use @ref{1ba7,,PyErr_Occurred()} to disambiguate.


在 3.8 版的變更: Use @ref{19e,,__index__()} if available.



在 3.10 版的變更: This function will no longer use @ref{19d,,__int__()}.

@end deffn

@geindex PyLong_AsLongLongAndOverflow (C function)
@anchor{c-api/long c PyLong_AsLongLongAndOverflow}@anchor{1466}
@deffn {C 函式} long long PyLong_AsLongLongAndOverflow (PyObject *obj, int *overflow)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return a C long long representation of `obj'.  If `obj' is not an
instance of @ref{39c,,PyLongObject}, first call its @ref{19e,,__index__()} method
(if present) to convert it to a @ref{39c,,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{1ba7,,PyErr_Occurred()} to disambiguate.


在 3.2 版被加入.



在 3.8 版的變更: Use @ref{19e,,__index__()} if available.



在 3.10 版的變更: This function will no longer use @ref{19d,,__int__()}.

@end deffn

@geindex PyLong_AsSsize_t (C function)
@anchor{c-api/long c PyLong_AsSsize_t}@anchor{4ecf}
@deffn {C 函式} @ref{c4c,,Py_ssize_t} PyLong_AsSsize_t (PyObject *pylong)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@geindex PY_SSIZE_T_MAX（C 巨集）
@geindex OverflowError（內建例外）

Return a C @ref{c4c,,Py_ssize_t} representation of `pylong'.  `pylong' must
be an instance of @ref{39c,,PyLongObject}.

Raise @ref{a78,,OverflowError} if the value of `pylong' is out of range for a
@ref{c4c,,Py_ssize_t}.

Returns @code{-1} on error.  Use @ref{1ba7,,PyErr_Occurred()} to disambiguate.
@end deffn

@geindex PyLong_AsUnsignedLong (C function)
@anchor{c-api/long c PyLong_AsUnsignedLong}@anchor{4ed0}
@deffn {C 函式} unsigned long PyLong_AsUnsignedLong (PyObject *pylong)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@geindex ULONG_MAX（C 巨集）
@geindex OverflowError（內建例外）

Return a C unsigned long representation of `pylong'.  `pylong'
must be an instance of @ref{39c,,PyLongObject}.

Raise @ref{a78,,OverflowError} if the value of `pylong' is out of range for a
unsigned long.

Returns @code{(unsigned long)-1} on error.
Use @ref{1ba7,,PyErr_Occurred()} to disambiguate.
@end deffn

@geindex PyLong_AsSize_t (C function)
@anchor{c-api/long c PyLong_AsSize_t}@anchor{4ece}
@deffn {C 函式} size_t PyLong_AsSize_t (PyObject *pylong)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@geindex SIZE_MAX（C 巨集）
@geindex OverflowError（內建例外）

Return a C @code{size_t} representation of `pylong'.  `pylong' must be
an instance of @ref{39c,,PyLongObject}.

Raise @ref{a78,,OverflowError} if the value of `pylong' is out of range for a
@code{size_t}.

Returns @code{(size_t)-1} on error.
Use @ref{1ba7,,PyErr_Occurred()} to disambiguate.
@end deffn

@geindex PyLong_AsUnsignedLongLong (C function)
@anchor{c-api/long c PyLong_AsUnsignedLongLong}@anchor{1495}
@deffn {C 函式} unsigned long long PyLong_AsUnsignedLongLong (PyObject *pylong)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@geindex OverflowError（內建例外）

Return a C unsigned long long representation of `pylong'.  `pylong'
must be an instance of @ref{39c,,PyLongObject}.

Raise @ref{a78,,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{1ba7,,PyErr_Occurred()} to disambiguate.


在 3.1 版的變更: A negative `pylong' now raises @ref{a78,,OverflowError}, not @ref{198,,TypeError}.

@end deffn

@geindex PyLong_AsUnsignedLongMask (C function)
@anchor{c-api/long c PyLong_AsUnsignedLongMask}@anchor{4ed1}
@deffn {C 函式} unsigned long PyLong_AsUnsignedLongMask (PyObject *obj)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return a C unsigned long representation of `obj'.  If `obj' is not
an instance of @ref{39c,,PyLongObject}, first call its @ref{19e,,__index__()}
method (if present) to convert it to a @ref{39c,,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{1ba7,,PyErr_Occurred()} to
disambiguate.


在 3.8 版的變更: Use @ref{19e,,__index__()} if available.



在 3.10 版的變更: This function will no longer use @ref{19d,,__int__()}.

@end deffn

@geindex PyLong_AsUnsignedLongLongMask (C function)
@anchor{c-api/long c PyLong_AsUnsignedLongLongMask}@anchor{1c93}
@deffn {C 函式} unsigned long long PyLong_AsUnsignedLongLongMask (PyObject *obj)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return a C unsigned long long representation of `obj'.  If `obj'
is not an instance of @ref{39c,,PyLongObject}, first call its
@ref{19e,,__index__()} method (if present) to convert it to a
@ref{39c,,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{1ba7,,PyErr_Occurred()}
to disambiguate.


在 3.8 版的變更: Use @ref{19e,,__index__()} if available.



在 3.10 版的變更: This function will no longer use @ref{19d,,__int__()}.

@end deffn

@geindex PyLong_AsInt32 (C function)
@geindex PyLong_AsInt64 (C function)
@anchor{c-api/long c PyLong_AsInt32}@anchor{39d}
@deffn {C 函式} int PyLong_AsInt32 (PyObject *obj, int32_t *value)
@anchor{c-api/long c PyLong_AsInt64}@anchor{39e}
@deffnx {C 函式} int PyLong_AsInt64 (PyObject *obj, int64_t *value)
` 為 @ref{76e,,穩定 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{39c,,PyLongObject}, first call its
@ref{19e,,__index__()} method (if present) to convert it to a
@ref{39c,,PyLongObject}.

If the `obj' value is out of range, raise an @ref{a78,,OverflowError}.

Set `*value' and return @code{0} on success.
Set an exception and return @code{-1} on error.

`value' must not be @code{NULL}.


在 3.14 版被加入.

@end deffn

@geindex PyLong_AsUInt32 (C function)
@geindex PyLong_AsUInt64 (C function)
@anchor{c-api/long c PyLong_AsUInt32}@anchor{39f}
@deffn {C 函式} int PyLong_AsUInt32 (PyObject *obj, uint32_t *value)
@anchor{c-api/long c PyLong_AsUInt64}@anchor{3a0}
@deffnx {C 函式} int PyLong_AsUInt64 (PyObject *obj, uint64_t *value)
` 為 @ref{76e,,穩定 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{39c,,PyLongObject}, first call its
@ref{19e,,__index__()} method (if present) to convert it to a
@ref{39c,,PyLongObject}.


@itemize *

@item 
If `obj' is negative, raise a @ref{2eb,,ValueError}.

@item 
If the `obj' value is out of range, raise an @ref{a78,,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}.


在 3.14 版被加入.

@end deffn

@geindex PyLong_AsDouble (C function)
@anchor{c-api/long c PyLong_AsDouble}@anchor{18d8}
@deffn {C 函式} double PyLong_AsDouble (PyObject *pylong)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return a C double representation of `pylong'.  `pylong' must be
an instance of @ref{39c,,PyLongObject}.

Raise @ref{a78,,OverflowError} if the value of `pylong' is out of range for a
double.

Returns @code{-1.0} on error.  Use @ref{1ba7,,PyErr_Occurred()} to disambiguate.
@end deffn

@geindex PyLong_AsVoidPtr (C function)
@anchor{c-api/long c PyLong_AsVoidPtr}@anchor{4ed2}
@deffn {C 函式} void *PyLong_AsVoidPtr (PyObject *pylong)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Convert a Python integer `pylong' to a C void pointer.
If `pylong' cannot be converted, an @ref{a78,,OverflowError} will be raised.  This
is only assured to produce a usable void pointer for values created
with @ref{4ed4,,PyLong_FromVoidPtr()}.

Returns @code{NULL} on error.  Use @ref{1ba7,,PyErr_Occurred()} to disambiguate.
@end deffn

@geindex PyLong_AsNativeBytes (C function)
@anchor{c-api/long c PyLong_AsNativeBytes}@anchor{5fe}
@deffn {C 函式} @ref{c4c,,Py_ssize_t} PyLong_AsNativeBytes (PyObject *pylong, void *buffer, Py_ssize_t n_bytes, int flags)
` 為 @ref{76e,,穩定 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: large buffers are padded with
zeroes.

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} 將永不被回傳。

Values are always copied as two's-complement.

使用範例：

@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

旗標

@tab

數值

@item

@geindex Py_ASNATIVEBYTES_DEFAULTS (C macro)
@anchor{c-api/long c Py_ASNATIVEBYTES_DEFAULTS}@anchor{50ec}
@deffn {C 巨集} Py_ASNATIVEBYTES_DEFAULTS
@end deffn

@tab

@code{-1}

@item

@geindex Py_ASNATIVEBYTES_BIG_ENDIAN (C macro)
@anchor{c-api/long c Py_ASNATIVEBYTES_BIG_ENDIAN}@anchor{50ed}
@deffn {C 巨集} Py_ASNATIVEBYTES_BIG_ENDIAN
@end deffn

@tab

@code{0}

@item

@geindex Py_ASNATIVEBYTES_LITTLE_ENDIAN (C macro)
@anchor{c-api/long c Py_ASNATIVEBYTES_LITTLE_ENDIAN}@anchor{50ee}
@deffn {C 巨集} Py_ASNATIVEBYTES_LITTLE_ENDIAN
@end deffn

@tab

@code{1}

@item

@geindex Py_ASNATIVEBYTES_NATIVE_ENDIAN (C macro)
@anchor{c-api/long c Py_ASNATIVEBYTES_NATIVE_ENDIAN}@anchor{50ef}
@deffn {C 巨集} Py_ASNATIVEBYTES_NATIVE_ENDIAN
@end deffn

@tab

@code{3}

@item

@geindex Py_ASNATIVEBYTES_UNSIGNED_BUFFER (C macro)
@anchor{c-api/long c Py_ASNATIVEBYTES_UNSIGNED_BUFFER}@anchor{50f0}
@deffn {C 巨集} Py_ASNATIVEBYTES_UNSIGNED_BUFFER
@end deffn

@tab

@code{4}

@item

@geindex Py_ASNATIVEBYTES_REJECT_NEGATIVE (C macro)
@anchor{c-api/long c Py_ASNATIVEBYTES_REJECT_NEGATIVE}@anchor{50f1}
@deffn {C 巨集} Py_ASNATIVEBYTES_REJECT_NEGATIVE
@end deffn

@tab

@code{8}

@item

@geindex Py_ASNATIVEBYTES_ALLOW_INDEX (C macro)
@anchor{c-api/long c Py_ASNATIVEBYTES_ALLOW_INDEX}@anchor{50f2}
@deffn {C 巨集} Py_ASNATIVEBYTES_ALLOW_INDEX
@end deffn

@tab

@code{16}

@end multitable


Specifying @code{Py_ASNATIVEBYTES_NATIVE_ENDIAN} will override any other endian
flags. Passing @code{2} is reserved.

By default, sufficient buffer will be requested to include a sign bit.
For example, when converting 128 with `n_bytes=1', the function will return
2 (or more) in order to store a zero sign bit.

If @code{Py_ASNATIVEBYTES_UNSIGNED_BUFFER} is specified, a zero sign bit
will be omitted from size calculations. This allows, for example, 128 to fit
in a single-byte buffer. If the destination buffer is later treated as
signed, a positive input value may become negative.
Note that the flag does not affect handling of negative values: for those,
space for a sign bit is always requested.

Specifying @code{Py_ASNATIVEBYTES_REJECT_NEGATIVE} causes an exception to be set
if `pylong' is negative. Without this flag, negative values will be copied
provided there is enough space for at least one sign bit, regardless of
whether @code{Py_ASNATIVEBYTES_UNSIGNED_BUFFER} was specified.

If @code{Py_ASNATIVEBYTES_ALLOW_INDEX} is specified and a non-integer value is
passed, its @ref{19e,,__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{198,,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


在 3.13 版被加入.

@end deffn

@geindex PyLong_GetSign (C function)
@anchor{c-api/long c PyLong_GetSign}@anchor{398}
@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{39c,,PyLongObject} or its subtype.


在 3.14 版被加入.

@end deffn

@geindex PyLong_IsPositive (C function)
@anchor{c-api/long c PyLong_IsPositive}@anchor{399}
@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{39c,,PyLongObject} or its subtype,
return @code{1} when it's positive and @code{0} otherwise.  Else set an
exception and return @code{-1}.


在 3.14 版被加入.

@end deffn

@geindex PyLong_IsNegative (C function)
@anchor{c-api/long c PyLong_IsNegative}@anchor{39a}
@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{39c,,PyLongObject} or its subtype,
return @code{1} when it's negative and @code{0} otherwise.  Else set an
exception and return @code{-1}.


在 3.14 版被加入.

@end deffn

@geindex PyLong_IsZero (C function)
@anchor{c-api/long c PyLong_IsZero}@anchor{39b}
@deffn {C 函式} int PyLong_IsZero (PyObject *obj)

Check if the integer object `obj' is zero.

If `obj' is an instance of @ref{39c,,PyLongObject} or its subtype,
return @code{1} when it's zero and @code{0} otherwise.  Else set an
exception and return @code{-1}.


在 3.14 版被加入.

@end deffn

@geindex PyLong_GetInfo (C function)
@anchor{c-api/long c PyLong_GetInfo}@anchor{4ed5}
@deffn {C 函式} @ref{5d7,,PyObject} *PyLong_GetInfo (void)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
On success, return a read only @ref{857,,named tuple}, that holds
information about Python's internal representation of integers.
See @ref{1494,,sys.int_info} for description of individual fields.

在失敗時，會回傳 @code{NULL} 並設定例外。


在 3.1 版被加入.

@end deffn

@geindex PyUnstable_Long_IsCompact (C function)
@anchor{c-api/long c PyUnstable_Long_IsCompact}@anchor{79f}
@deffn {C 函式} int PyUnstable_Long_IsCompact (const PyLongObject *op)

@cartouche
@quotation 這是 不穩定 API，它可能在小版本發布中沒有任何警告地被變更。 `這是 @ref{762,,不穩定 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{7a0,,PyUnstable_Long_CompactValue()}; for others fall back to a
@ref{4ece,,PyLong_As*} function or
@ref{5fe,,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.


在 3.12 版被加入.

@end deffn

@geindex PyUnstable_Long_CompactValue (C function)
@anchor{c-api/long c PyUnstable_Long_CompactValue}@anchor{7a0}
@deffn {C 函式} @ref{c4c,,Py_ssize_t} PyUnstable_Long_CompactValue (const PyLongObject *op)

@cartouche
@quotation 這是 不穩定 API，它可能在小版本發布中沒有任何警告地被變更。 `這是 @ref{762,,不穩定 API}，它可能在小版本發布中沒有任何警告地被變更。'
@end quotation
@end cartouche

If `op' is compact, as determined by @ref{79f,,PyUnstable_Long_IsCompact()},
return its value.

Otherwise, the return value is undefined.


在 3.12 版被加入.

@end deffn

@menu
* Export API:: 
* PyLongWriter API:: 

@end menu

@node Export API,PyLongWriter API,,整數物件
@anchor{c-api/long export-api}@anchor{50f3}
@subsubsection Export API



在 3.14 版被加入.


@geindex PyLongLayout (C struct)
@anchor{c-api/long c PyLongLayout}@anchor{50f4}
@deffn {C 結構} struct PyLongLayout

Layout of an array of "digits" ("limbs" in the GMP terminology), used to
represent absolute value for arbitrary precision integers.

Use @ref{3a5,,PyLong_GetNativeLayout()} to get the native layout of Python
@ref{19b,,int} objects, used internally for integers with "big enough"
absolute value.

See also @ref{1494,,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{50f5}
@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{50f6}
@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{50f7}
@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{50f8}
@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{3a5}
@deffn {C 函式} const @ref{50f4,,PyLongLayout} *PyLong_GetNativeLayout (void)

Get the native layout of Python @ref{19b,,int} objects.

See the @ref{50f4,,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 struct)
@anchor{c-api/long c PyLongExport}@anchor{50f9}
@deffn {C 結構} struct PyLongExport

Export of a Python @ref{19b,,int} object.

There are two cases:


@itemize *

@item 
If @ref{50fa,,digits} is @code{NULL}, only use the @ref{50fb,,value} member.

@item 
If @ref{50fa,,digits} is not @code{NULL}, use @ref{50fc,,negative},
@ref{50fd,,ndigits} and @ref{50fa,,digits} members.
@end itemize

@geindex PyLongExport.value (C member)
@anchor{c-api/long c PyLongExport value}@anchor{50fb}
@deffn {C 成員函數} int64_t value

The native integer value of the exported @ref{19b,,int} object.
Only valid if @ref{50fa,,digits} is @code{NULL}.
@end deffn

@geindex PyLongExport.negative (C member)
@anchor{c-api/long c PyLongExport negative}@anchor{50fc}
@deffn {C 成員函數} uint8_t negative

@code{1} if the number is negative, @code{0} otherwise.
Only valid if @ref{50fa,,digits} is not @code{NULL}.
@end deffn

@geindex PyLongExport.ndigits (C member)
@anchor{c-api/long c PyLongExport ndigits}@anchor{50fd}
@deffn {C 成員函數} @ref{c4c,,Py_ssize_t} ndigits

Number of digits in @ref{50fa,,digits} array.
Only valid if @ref{50fa,,digits} is not @code{NULL}.
@end deffn

@geindex PyLongExport.digits (C member)
@anchor{c-api/long c PyLongExport digits}@anchor{50fa}
@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{3a6}
@deffn {C 函式} int PyLong_Export (PyObject *obj, PyLongExport *export_long)

Export a Python @ref{19b,,int} object.

`export_long' must point to a @ref{50f9,,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{3a7,,PyLong_FreeExport()} must be called when the export is no longer
needed.

@quotation

`CPython 實作細節：' This function always succeeds if `obj' is a Python @ref{19b,,int} object
or a subclass.
@end quotation
@end deffn

@geindex PyLong_FreeExport (C function)
@anchor{c-api/long c PyLong_FreeExport}@anchor{3a7}
@deffn {C 函式} void PyLong_FreeExport (PyLongExport *export_long)

Release the export `export_long' created by @ref{3a6,,PyLong_Export()}.

`CPython 實作細節：' Calling @ref{3a7,,PyLong_FreeExport()} is optional if `export_long->digits'
is @code{NULL}.
@end deffn

@node PyLongWriter API,,Export API,整數物件
@anchor{c-api/long pylongwriter-api}@anchor{50fe}
@subsubsection PyLongWriter API


The @ref{50ff,,PyLongWriter} API can be used to import an integer.


在 3.14 版被加入.


@geindex PyLongWriter (C struct)
@anchor{c-api/long c PyLongWriter}@anchor{50ff}
@deffn {C 結構} struct PyLongWriter

A Python @ref{19b,,int} writer instance.

The instance must be destroyed by @ref{3a9,,PyLongWriter_Finish()} or
@ref{3aa,,PyLongWriter_Discard()}.
@end deffn

@geindex PyLongWriter_Create (C function)
@anchor{c-api/long c PyLongWriter_Create}@anchor{3a8}
@deffn {C 函式} @ref{50ff,,PyLongWriter} *PyLongWriter_Create (int negative, Py_ssize_t ndigits, void **digits)

Create a @ref{50ff,,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{3a9,,PyLongWriter_Finish()} to get
a Python @ref{19b,,int}.
The layout of `digits' is described by @ref{3a5,,PyLong_GetNativeLayout()}.

Digits must be in the range [@code{0}; @code{(1 << bits_per_digit) - 1}]
(where the @ref{50f5,,bits_per_digit} is the number of bits
per digit).
Any unused most significant digits must be set to @code{0}.

Alternately, call @ref{3aa,,PyLongWriter_Discard()} to destroy the writer
instance without creating an @ref{19b,,int} object.
@end deffn

@geindex PyLongWriter_Finish (C function)
@anchor{c-api/long c PyLongWriter_Finish}@anchor{3a9}
@deffn {C 函式} @ref{5d7,,PyObject} *PyLongWriter_Finish (PyLongWriter *writer)
`回傳值：新的參照。'
Finish a @ref{50ff,,PyLongWriter} created by @ref{3a8,,PyLongWriter_Create()}.

On success, return a Python @ref{19b,,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{3aa}
@deffn {C 函式} void PyLongWriter_Discard (PyLongWriter *writer)

Discard a @ref{50ff,,PyLongWriter} created by @ref{3a8,,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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Boolean（布林）物件,浮點數（Floating-Point）物件,整數物件,數值物件
@anchor{c-api/bool doc}@anchor{5100}@anchor{c-api/bool boolean-objects}@anchor{5101}@anchor{c-api/bool boolobjects}@anchor{5102}@anchor{c-api/bool translation-repo}@anchor{5103}
@subsubsection Boolean（布林）物件


Python 中的 boolean 是以整數子類別化來實現的。只有 @ref{5104,,Py_False} 和 @ref{5105,,Py_True} 兩個 boolean。因此一般的建立和刪除函式並不適用於 boolean。但下列巨集 (macro) 是可用的。

@geindex PyBool_Type (C var)
@anchor{c-api/bool c PyBool_Type}@anchor{4e19}
@deffn {C 變數} @ref{c93,,PyTypeObject} PyBool_Type
` 為 @ref{76e,,穩定 ABI 的一部分}.'
此 @ref{c93,,PyTypeObject} 實例代表 Python 的布林型別；它與 Python 層級中的 @ref{3c1,,bool} 是同一個物件。
@end deffn

@geindex PyBool_Check (C function)
@anchor{c-api/bool c PyBool_Check}@anchor{5106}
@deffn {C 函式} int PyBool_Check (PyObject *o)

如果 `o' 的型別為 @ref{4e19,,PyBool_Type} 則回傳真值。此函式總是會成功執行。
@end deffn

@geindex Py_False (C var)
@anchor{c-api/bool c Py_False}@anchor{5104}
@deffn {C 變數} @ref{5d7,,PyObject} *Py_False

Python 的 @code{False} 物件。此物件沒有任何方法且為@ref{290,,不滅的 (immortal)}。


在 3.12 版的變更: @ref{5104,,Py_False} 為@ref{290,,不滅的}。

@end deffn

@geindex Py_True (C var)
@anchor{c-api/bool c Py_True}@anchor{5105}
@deffn {C 變數} @ref{5d7,,PyObject} *Py_True

Python 的 @code{True} 物件。此物件沒有任何方法且為@ref{290,,不滅的}。


在 3.12 版的變更: @ref{5105,,Py_True} 為@ref{290,,不滅的}。

@end deffn

@geindex Py_RETURN_FALSE (C macro)
@anchor{c-api/bool c Py_RETURN_FALSE}@anchor{166a}
@deffn {C 巨集} Py_RETURN_FALSE

從函式回傳 @ref{5104,,Py_False}。
@end deffn

@geindex Py_RETURN_TRUE (C macro)
@anchor{c-api/bool c Py_RETURN_TRUE}@anchor{1669}
@deffn {C 巨集} Py_RETURN_TRUE

從函式回傳 @ref{5105,,Py_True}。
@end deffn

@geindex PyBool_FromLong (C function)
@anchor{c-api/bool c PyBool_FromLong}@anchor{4e18}
@deffn {C 函式} @ref{5d7,,PyObject} *PyBool_FromLong (long v)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
根據 `v' 的實際值來回傳 @ref{5105,,Py_True} 或者 @ref{5104,,Py_False}。
@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）物件,複數物件,Boolean（布林）物件,數值物件
@anchor{c-api/float doc}@anchor{5107}@anchor{c-api/float floating-point-objects}@anchor{5108}@anchor{c-api/float floatobjects}@anchor{5109}@anchor{c-api/float translation-repo}@anchor{510a}
@subsubsection 浮點數（Floating-Point）物件


@geindex object（物件）;floating-point（浮點）

@geindex PyFloatObject (C type)
@anchor{c-api/float c PyFloatObject}@anchor{510b}
@deffn {C 型別} type PyFloatObject

This subtype of @ref{5d7,,PyObject} represents a Python floating-point object.
@end deffn

@geindex PyFloat_Type (C var)
@anchor{c-api/float c PyFloat_Type}@anchor{4eb6}
@deffn {C 變數} @ref{c93,,PyTypeObject} PyFloat_Type
` 為 @ref{76e,,穩定 ABI 的一部分}.'
This instance of @ref{c93,,PyTypeObject} represents the Python floating-point
type.  This is the same object as @ref{196,,float} in the Python layer.
@end deffn

@geindex PyFloat_Check (C function)
@anchor{c-api/float c PyFloat_Check}@anchor{510c}
@deffn {C 函式} int PyFloat_Check (PyObject *p)

Return true if its argument is a @ref{510b,,PyFloatObject} or a subtype of
@ref{510b,,PyFloatObject}.  This function always succeeds.
@end deffn

@geindex PyFloat_CheckExact (C function)
@anchor{c-api/float c PyFloat_CheckExact}@anchor{510d}
@deffn {C 函式} int PyFloat_CheckExact (PyObject *p)

Return true if its argument is a @ref{510b,,PyFloatObject}, but not a subtype of
@ref{510b,,PyFloatObject}.  This function always succeeds.
@end deffn

@geindex PyFloat_FromString (C function)
@anchor{c-api/float c PyFloat_FromString}@anchor{4eb5}
@deffn {C 函式} @ref{5d7,,PyObject} *PyFloat_FromString (PyObject *str)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Create a @ref{510b,,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{4eb4}
@deffn {C 函式} @ref{5d7,,PyObject} *PyFloat_FromDouble (double v)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Create a @ref{510b,,PyFloatObject} object from `v', or @code{NULL} on failure.
@end deffn

@geindex PyFloat_AsDouble (C function)
@anchor{c-api/float c PyFloat_AsDouble}@anchor{c56}
@deffn {C 函式} double PyFloat_AsDouble (PyObject *pyfloat)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return a C double representation of the contents of `pyfloat'.  If
`pyfloat' is not a Python floating-point object but has a @ref{bb8,,__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{19e,,__index__()}.
This method returns @code{-1.0} upon failure, so one should call
@ref{1ba7,,PyErr_Occurred()} to check for errors.


在 3.8 版的變更: Use @ref{19e,,__index__()} if available.

@end deffn

@geindex PyFloat_AS_DOUBLE (C function)
@anchor{c-api/float c PyFloat_AS_DOUBLE}@anchor{510e}
@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{15e7}
@deffn {C 函式} @ref{5d7,,PyObject} *PyFloat_GetInfo (void)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{15e5}
@deffn {C 函式} double PyFloat_GetMax ()
` 為 @ref{76e,,穩定 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{15e6}
@deffn {C 函式} double PyFloat_GetMin ()
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return the minimum normalized positive float `DBL_MIN' as C double.
@end deffn

@menu
* Pack and Unpack functions:: 

@end menu

@node Pack and Unpack functions,,,浮點數（Floating-Point）物件
@anchor{c-api/float pack-and-unpack-functions}@anchor{510f}
@subsubsection Pack and Unpack functions


The pack and unpack functions provide an efficient platform-independent way to
store floating-point values as byte strings. The Pack routines produce a bytes
string from a C double, and the Unpack routines produce a C
double from such a bytes string. The suffix (2, 4 or 8) specifies the
number of bytes in the bytes string.

On platforms that appear to use IEEE 754 formats these functions work by
copying bits. On other platforms, the 2-byte format is identical to the IEEE
754 binary16 half-precision format, the 4-byte format (32-bit) is identical to
the IEEE 754 binary32 single precision format, and the 8-byte format to the
IEEE 754 binary64 double precision format, although the packing of INFs and
NaNs (if such things exist on the platform) isn't handled correctly, and
attempting to unpack a bytes string containing an IEEE INF or NaN will raise an
exception.

Note that NaNs type may not be preserved on IEEE platforms (silent NaN become
quiet), for example on x86 systems in 32-bit mode.

On non-IEEE platforms with more precision, or larger dynamic range, than IEEE
754 supports, not all values can be packed; on non-IEEE platforms with less
precision, or smaller dynamic range, not all values can be unpacked. What
happens in such cases is partly accidental (alas).


在 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{5110}
@subsubsection Pack functions


The pack routines write 2, 4 or 8 bytes, starting at `p'. `le' is an
int argument, non-zero if you want the bytes string in little-endian
format (exponent last, at @code{p+1}, @code{p+3}, or @code{p+6} @code{p+7}), zero if you
want big-endian format (exponent first, at `p'). The @code{PY_BIG_ENDIAN}
constant can be used to use the native endian: it is equal to @code{1} on big
endian processor, or @code{0} on little endian processor.

Return value: @code{0} if all is OK, @code{-1} if error (and an exception is set,
most likely @ref{a78,,OverflowError}).

There are two problems on non-IEEE platforms:


@itemize *

@item 
What this does is undefined if `x' is a NaN or infinity.

@item 
@code{-0.0} 和 @code{+0.0} 會產生同樣的位元組字串。
@end itemize

@geindex PyFloat_Pack2 (C function)
@anchor{c-api/float c PyFloat_Pack2}@anchor{961}
@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{962}
@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{963}
@deffn {C 函式} int PyFloat_Pack8 (double x, char *p, int le)

Pack a C double as the IEEE 754 binary64 double precision format.
@end deffn

@node Unpack functions,,Pack functions,Pack and Unpack functions
@anchor{c-api/float unpack-functions}@anchor{5111}
@subsubsection Unpack functions


The unpack routines read 2, 4 or 8 bytes, starting at `p'.  `le' is an
int argument, non-zero if the bytes string is in little-endian format
(exponent last, at @code{p+1}, @code{p+3} or @code{p+6} and @code{p+7}), zero if big-endian
(exponent first, at `p'). The @code{PY_BIG_ENDIAN} constant can be used to
use the native endian: it is equal to @code{1} on big endian processor, or @code{0}
on little endian processor.

Return value: The unpacked double.  On error, this is @code{-1.0} and
@ref{1ba7,,PyErr_Occurred()} is true (and an exception is set, most likely
@ref{a78,,OverflowError}).

Note that on a non-IEEE platform this will refuse to unpack a bytes string that
represents a NaN or infinity.

@geindex PyFloat_Unpack2 (C function)
@anchor{c-api/float c PyFloat_Unpack2}@anchor{964}
@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{965}
@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{966}
@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 複數物件,,浮點數（Floating-Point）物件,數值物件
@anchor{c-api/complex doc}@anchor{5112}@anchor{c-api/complex complex-number-objects}@anchor{5113}@anchor{c-api/complex complexobjects}@anchor{5114}@anchor{c-api/complex translation-repo}@anchor{5115}
@subsubsection 複數物件


@geindex object（物件）;complex number（複數）

從 C API 來看，Python 的複數物件被實作為兩種不同的型別：一種是公開給 Python 程式的 Python 物件，另一種是表示實際複數值的 C 結構。API 提供了與兩者一起作用的函式。

@menu
* 作為 C 結構的複數:: 
* 作為 Python 物件的複數:: 

@end menu

@node 作為 C 結構的複數,作為 Python 物件的複數,,複數物件
@anchor{c-api/complex complex-numbers-as-c-structures}@anchor{5116}
@subsubsection 作為 C 結構的複數


請注意，接受這些結構作為參數並將它們作為結果回傳的函式是`按值 (by value)' 執行的，而不是透過指標取消參照 (dereference) 它們。這在整個 API 中都是一致的。

@geindex Py_complex (C type)
@anchor{c-api/complex c Py_complex}@anchor{502d}
@deffn {C 型別} type Py_complex

相對於 Python 複數物件之數值部分的 C 結構。大多數處理複數物件的函式根據需求會使用這種型別的結構作為輸入或輸出值。

@geindex Py_complex.real (C member)
@geindex Py_complex.imag (C member)
@anchor{c-api/complex c Py_complex real}@anchor{5117}
@deffn {C 成員函數} double real
@anchor{c-api/complex c Py_complex imag}@anchor{5118}
@deffnx {C 成員函數} double imag
@end deffn

該結構被定義為：

@example
typedef struct @{
    double real;
    double imag;
@} Py_complex;
@end example
@end deffn

@geindex _Py_c_sum (C function)
@anchor{c-api/complex c _Py_c_sum}@anchor{5119}
@deffn {C 函式} @ref{502d,,Py_complex} _Py_c_sum (Py_complex left, Py_complex right)

以 C 的 @ref{502d,,Py_complex} 表示形式來回傳兩個複數之和。
@end deffn

@geindex _Py_c_diff (C function)
@anchor{c-api/complex c _Py_c_diff}@anchor{511a}
@deffn {C 函式} @ref{502d,,Py_complex} _Py_c_diff (Py_complex left, Py_complex right)

以 C 的 @ref{502d,,Py_complex} 表示形式來回傳兩個複數間的差。
@end deffn

@geindex _Py_c_neg (C function)
@anchor{c-api/complex c _Py_c_neg}@anchor{511b}
@deffn {C 函式} @ref{502d,,Py_complex} _Py_c_neg (Py_complex num)

以 C 的 @ref{502d,,Py_complex} 表示形式來回傳複數 `num' 的相反數 (negation)。
@end deffn

@geindex _Py_c_prod (C function)
@anchor{c-api/complex c _Py_c_prod}@anchor{511c}
@deffn {C 函式} @ref{502d,,Py_complex} _Py_c_prod (Py_complex left, Py_complex right)

以 C 的 @ref{502d,,Py_complex} 表示形式來回傳兩個複數的乘積。
@end deffn

@geindex _Py_c_quot (C function)
@anchor{c-api/complex c _Py_c_quot}@anchor{511d}
@deffn {C 函式} @ref{502d,,Py_complex} _Py_c_quot (Py_complex dividend, Py_complex divisor)

以 C 的 @ref{502d,,Py_complex} 表示形式來回傳兩個複數的商。

如果 `divisor' 為 null，則此方法會回傳零並將 @code{errno} 設定為 @code{EDOM}。
@end deffn

@geindex _Py_c_pow (C function)
@anchor{c-api/complex c _Py_c_pow}@anchor{185f}
@deffn {C 函式} @ref{502d,,Py_complex} _Py_c_pow (Py_complex num, Py_complex exp)

以 C 的 @ref{502d,,Py_complex} 表示形式來回傳 `num' 的 `exp' 次方的結果。

如果 `num' 為 null 且 `exp' 不是正實數，則此方法會回傳零並將 @code{errno} 設定為 @code{EDOM}。

Set @code{errno} to @code{ERANGE} on overflows.
@end deffn

@node 作為 Python 物件的複數,,作為 C 結構的複數,複數物件
@anchor{c-api/complex complex-numbers-as-python-objects}@anchor{511e}
@subsubsection 作為 Python 物件的複數


@geindex PyComplexObject (C type)
@anchor{c-api/complex c PyComplexObject}@anchor{511f}
@deffn {C 型別} type PyComplexObject

這個 @ref{5d7,,PyObject} 的子型別代表一個 Python 複數物件。
@end deffn

@geindex PyComplex_Type (C var)
@anchor{c-api/complex c PyComplex_Type}@anchor{4e46}
@deffn {C 變數} @ref{c93,,PyTypeObject} PyComplex_Type
` 為 @ref{76e,,穩定 ABI 的一部分}.'
這個 @ref{c93,,PyTypeObject} 的實例代表 Python 複數型別。它與 Python 層中的 @ref{197,,complex} 是同一個物件。
@end deffn

@geindex PyComplex_Check (C function)
@anchor{c-api/complex c PyComplex_Check}@anchor{5120}
@deffn {C 函式} int PyComplex_Check (PyObject *p)

如果其引數是一個 @ref{511f,,PyComplexObject} 或者是 @ref{511f,,PyComplexObject} 的子型別，則會回傳 true。這個函式不會失敗。
@end deffn

@geindex PyComplex_CheckExact (C function)
@anchor{c-api/complex c PyComplex_CheckExact}@anchor{5121}
@deffn {C 函式} int PyComplex_CheckExact (PyObject *p)

如果其引數是一個 @ref{511f,,PyComplexObject}，但不是 @ref{511f,,PyComplexObject} 的子型別，則會回傳 true。這個函式不會失敗。
@end deffn

@geindex PyComplex_FromCComplex (C function)
@anchor{c-api/complex c PyComplex_FromCComplex}@anchor{5122}
@deffn {C 函式} @ref{5d7,,PyObject} *PyComplex_FromCComplex (Py_complex v)
`回傳值：新的參照。'
從 C 的 @ref{502d,,Py_complex} 值建立一個新的 Python 複數物件。在錯誤時回傳 @code{NULL} 並設定例外。
@end deffn

@geindex PyComplex_FromDoubles (C function)
@anchor{c-api/complex c PyComplex_FromDoubles}@anchor{4e45}
@deffn {C 函式} @ref{5d7,,PyObject} *PyComplex_FromDoubles (double real, double imag)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
從 `real' 和 `imag' 回傳一個新的 @ref{511f,,PyComplexObject} 物件。在錯誤時回傳 @code{NULL} 並設定例外。
@end deffn

@geindex PyComplex_RealAsDouble (C function)
@anchor{c-api/complex c PyComplex_RealAsDouble}@anchor{1961}
@deffn {C 函式} double PyComplex_RealAsDouble (PyObject *op)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
以 C 的 double 形式回傳 `op' 的實部。

如果 `op' 不是 Python 複數物件，但有一個 @ref{7f8,,__complex__()} 方法，則首先會呼叫該方法將 `op' 轉換為 Python 複數物件。如果 @code{__complex__()} 並未定義，那麼它會回退到呼叫 @code{PyFloat_AsDouble()} 並回傳其結果。

失敗時，此方法回傳 @code{-1.0} 並設定例外，因此應該呼叫 @ref{1ba7,,PyErr_Occurred()} 來檢查錯誤。


在 3.13 版的變更: 如果可用則使用 @ref{7f8,,__complex__()}。

@end deffn

@geindex PyComplex_ImagAsDouble (C function)
@anchor{c-api/complex c PyComplex_ImagAsDouble}@anchor{1962}
@deffn {C 函式} double PyComplex_ImagAsDouble (PyObject *op)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
將 `op' 的虛部作為 C 的 double 回傳。

如果 `op' 不是 Python 複數物件，但有一個 @ref{7f8,,__complex__()} 方法，則首先會呼叫該方法將 `op' 轉換為 Python 複數物件。如果 @code{__complex__()} 並未定義，那麼它會回退到呼叫 @code{PyFloat_AsDouble()} 並於成功時回傳 @code{0.0}。

失敗時，此方法回傳 @code{-1.0} 並設定例外，因此應該呼叫 @ref{1ba7,,PyErr_Occurred()} 來檢查錯誤。


在 3.13 版的變更: 如果可用則使用 @ref{7f8,,__complex__()}。

@end deffn

@geindex PyComplex_AsCComplex (C function)
@anchor{c-api/complex c PyComplex_AsCComplex}@anchor{15e8}
@deffn {C 函式} @ref{502d,,Py_complex} PyComplex_AsCComplex (PyObject *op)

回傳複數 `op' 的 @ref{502d,,Py_complex} 值。

如果 `op' 不是 Python 複數物件，但有一個 @ref{7f8,,__complex__()} 方法，則首先會呼叫該方法將 `op' 轉換為 Python 複數物件。如果 @code{__complex__()} 並未定義，那麼它會回退到 @ref{bb8,,__float__()}。如果 @code{__float__()} 未定義，則它將繼續回退為 @ref{19e,,__index__()}。

失敗時，此方法回傳 @ref{502d,,Py_complex} 並將 @ref{5117,,real} 設為 @code{-1.0}，並設定例外，因此應該呼叫 @ref{1ba7,,PyErr_Occurred()} 來檢查錯誤。


在 3.8 版的變更: 如果可用則使用 @ref{19e,,__index__()}。

@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 序列物件,容器物件,數值物件,具體物件層
@anchor{c-api/concrete sequence-objects}@anchor{5123}@anchor{c-api/concrete sequenceobjects}@anchor{5124}
@subsection 序列物件


@geindex object（物件）;sequence（序列）

序列物件的一般操作在前一章節討論過了；此段落將討論 Python 語言特有的特定型別序列物件。

@c XXX sort out unicode, str, bytes and bytearray

@menu
* 位元組物件 (Bytes Objects): 位元組物件 Bytes Objects. 
* 位元組陣列物件 (Byte Array Objects): 位元組陣列物件 Byte Array Objects. 
* Unicode 物件與編解碼器:: 
* Tuple（元組）物件:: 
* Struct Sequence Objects:: 
* List（串列）物件:: 

@end menu

@node 位元組物件 Bytes Objects,位元組陣列物件 Byte Array Objects,,序列物件
@anchor{c-api/bytes doc}@anchor{5125}@anchor{c-api/bytes bytes-objects}@anchor{5126}@anchor{c-api/bytes bytesobjects}@anchor{5127}
@subsubsection 位元組物件 (Bytes Objects)


These functions raise @ref{198,,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{98d}
@deffn {C 型別} type PyBytesObject

This subtype of @ref{5d7,,PyObject} represents a Python bytes object.
@end deffn

@geindex PyBytes_Type (C var)
@anchor{c-api/bytes c PyBytes_Type}@anchor{4e26}
@deffn {C 變數} @ref{c93,,PyTypeObject} PyBytes_Type
` 為 @ref{76e,,穩定 ABI 的一部分}.'
This instance of @ref{c93,,PyTypeObject} represents the Python bytes type; it
is the same object as @ref{192,,bytes} in the Python layer.
@end deffn

@geindex PyBytes_Check (C function)
@anchor{c-api/bytes c PyBytes_Check}@anchor{1597}
@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{5128}
@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{4e24}
@deffn {C 函式} @ref{5d7,,PyObject} *PyBytes_FromString (const char *v)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return a new bytes object with a copy of the string `v' as value on success,
and @code{NULL} on failure.  The parameter `v' must not be @code{NULL}; it will not be
checked.
@end deffn

@geindex PyBytes_FromStringAndSize (C function)
@anchor{c-api/bytes c PyBytes_FromStringAndSize}@anchor{1598}
@deffn {C 函式} @ref{5d7,,PyObject} *PyBytes_FromStringAndSize (const char *v, Py_ssize_t len)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return a new bytes object with a copy of the string `v' as value and length
`len' on success, and @code{NULL} on failure.  If `v' is @code{NULL}, the contents of
the bytes object are uninitialized.
@end deffn

@geindex PyBytes_FromFormat (C function)
@anchor{c-api/bytes c PyBytes_FromFormat}@anchor{1cd3}
@deffn {C 函式} @ref{5d7,,PyObject} *PyBytes_FromFormat (const char *format, ...)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Take a C @code{printf()}-style `format' string and a variable number of
arguments, calculate the size of the resulting Python bytes object and return
a bytes object with the values formatted into it.  The variable arguments
must be C types and must correspond exactly to the format characters in the
`format' string.  The following format characters are allowed:

@c % XXX: This should be exactly the same as the table in PyErr_Format.

@c % One should just refer to the other.


@multitable {xxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

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

等價於 @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

等價於 @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

等價於 @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

等價於 @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{c4c,,Py_ssize_t}

@tab

等價於 @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

等價於 @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

等價於 @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

等價於 @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{4e22}
@deffn {C 函式} @ref{5d7,,PyObject} *PyBytes_FromFormatV (const char *format, va_list vargs)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Identical to @ref{1cd3,,PyBytes_FromFormat()} except that it takes exactly two
arguments.
@end deffn

@geindex PyBytes_FromObject (C function)
@anchor{c-api/bytes c PyBytes_FromObject}@anchor{4e23}
@deffn {C 函式} @ref{5d7,,PyObject} *PyBytes_FromObject (PyObject *o)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return the bytes representation of object `o' that implements the buffer
protocol.
@end deffn

@geindex PyBytes_Size (C function)
@anchor{c-api/bytes c PyBytes_Size}@anchor{4e25}
@deffn {C 函式} @ref{c4c,,Py_ssize_t} PyBytes_Size (PyObject *o)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return the length of the bytes in bytes object `o'.
@end deffn

@geindex PyBytes_GET_SIZE (C function)
@anchor{c-api/bytes c PyBytes_GET_SIZE}@anchor{5129}
@deffn {C 函式} @ref{c4c,,Py_ssize_t} PyBytes_GET_SIZE (PyObject *o)

和 @ref{4e25,,PyBytes_Size()} 類似，但不進行錯誤檢查。
@end deffn

@geindex PyBytes_AsString (C function)
@anchor{c-api/bytes c PyBytes_AsString}@anchor{a7e}
@deffn {C 函式} char *PyBytes_AsString (PyObject *o)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return a pointer to the contents of `o'.  The pointer
refers to the internal buffer of `o', which consists of @code{len(o) + 1}
bytes.  The last byte in the buffer is always null, regardless of
whether there are any other null bytes.  The data must not be
modified in any way, unless the object was just created using
@code{PyBytes_FromStringAndSize(NULL, size)}. It must not be deallocated.  If
`o' is not a bytes object at all, @ref{a7e,,PyBytes_AsString()} returns @code{NULL}
and raises @ref{198,,TypeError}.
@end deffn

@geindex PyBytes_AS_STRING (C function)
@anchor{c-api/bytes c PyBytes_AS_STRING}@anchor{512a}
@deffn {C 函式} char *PyBytes_AS_STRING (PyObject *string)

和 @ref{a7e,,PyBytes_AsString()} 類似，但不進行錯誤檢查。
@end deffn

@geindex PyBytes_AsStringAndSize (C function)
@anchor{c-api/bytes c PyBytes_AsStringAndSize}@anchor{4e1f}
@deffn {C 函式} int PyBytes_AsStringAndSize (PyObject *obj, char **buffer, Py_ssize_t *length)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return the null-terminated contents of the object `obj'
through the output variables `buffer' and `length'.
Returns @code{0} on success.

If `length' is @code{NULL}, the bytes object
may not contain embedded null bytes;
if it does, the function returns @code{-1} and a @ref{2eb,,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{4e1f,,PyBytes_AsStringAndSize()}
returns @code{-1} and raises @ref{198,,TypeError}.


在 3.5 版的變更: Previously, @ref{198,,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{4e20}
@deffn {C 函式} void PyBytes_Concat (PyObject **bytes, PyObject *newpart)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Create a new bytes object in `*bytes' containing the contents of `newpart'
appended to `bytes'; the caller will own the new reference.  The reference to
the old value of `bytes' will be stolen.  If the new object cannot be
created, the old reference to `bytes' will still be discarded and the value
of `*bytes' will be set to @code{NULL}; the appropriate exception will be set.
@end deffn

@geindex PyBytes_ConcatAndDel (C function)
@anchor{c-api/bytes c PyBytes_ConcatAndDel}@anchor{4e21}
@deffn {C 函式} void PyBytes_ConcatAndDel (PyObject **bytes, PyObject *newpart)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Create a new bytes object in `*bytes' containing the contents of `newpart'
appended to `bytes'.  This version releases the @ref{5da,,strong reference}
to `newpart' (i.e. decrements its reference count).
@end deffn

@geindex PyBytes_Join (C function)
@anchor{c-api/bytes c PyBytes_Join}@anchor{381}
@deffn {C 函式} @ref{5d7,,PyObject} *PyBytes_Join (PyObject *sep, PyObject *iterable)

類似 Python 中的 @code{sep.join(iterable)}。

`sep' must be Python @ref{192,,bytes} object.
(Note that @ref{13a3,,PyUnicode_Join()} accepts @code{NULL} separator and treats
it as a space, whereas @ref{381,,PyBytes_Join()} doesn't accept @code{NULL}
separator.)

`iterable' must be an iterable object yielding objects that implement the
@ref{260,,buffer protocol}.

On success, return a new @ref{192,,bytes} object.
On error, set an exception and return @code{NULL}.


在 3.14 版被加入.

@end deffn

@geindex _PyBytes_Resize (C function)
@anchor{c-api/bytes c _PyBytes_Resize}@anchor{1921}
@deffn {C 函式} int _PyBytes_Resize (PyObject **bytes, Py_ssize_t newsize)

Resize a bytes object. `newsize' will be the new length of the bytes object.
You can think of it as creating a new bytes object and destroying the old
one, only more efficiently.
Pass the address of an
existing bytes object as an lvalue (it may be written into), and the new size
desired.  On success, `*bytes' holds the resized bytes object and @code{0} is
returned; the address in `*bytes' may differ from its input value.  If the
reallocation fails, the original bytes object at `*bytes' is deallocated,
`*bytes' is set to @code{NULL}, @ref{181e,,MemoryError} is set, and @code{-1} is
returned.
@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 物件與編解碼器,位元組物件 Bytes Objects,序列物件
@anchor{c-api/bytearray doc}@anchor{512b}@anchor{c-api/bytearray byte-array-objects}@anchor{512c}@anchor{c-api/bytearray bytearrayobjects}@anchor{512d}@anchor{c-api/bytearray translation-repo}@anchor{512e}
@subsubsection 位元組陣列物件 (Byte Array Objects)


@geindex object（物件）;bytearray（位元組陣列）

@geindex PyByteArrayObject (C type)
@anchor{c-api/bytearray c PyByteArrayObject}@anchor{512f}
@deffn {C 型別} type PyByteArrayObject

這個 @ref{5d7,,PyObject} 的子型別代表了 Python 的位元組陣列物件。
@end deffn

@geindex PyByteArray_Type (C var)
@anchor{c-api/bytearray c PyByteArray_Type}@anchor{4e1e}
@deffn {C 變數} @ref{c93,,PyTypeObject} PyByteArray_Type
` 為 @ref{76e,,穩定 ABI 的一部分}.'
這個 @ref{c93,,PyTypeObject} 的實例代表了 Python 的位元組陣列型別；在 Python 層中的 @ref{343,,bytearray} 為同一個物件。
@end deffn

@menu
* 型別檢查巨集:: 
* 直接 API 函式:: 
* 巨集:: 

@end menu

@node 型別檢查巨集,直接 API 函式,,位元組陣列物件 Byte Array Objects
@anchor{c-api/bytearray type-check-macros}@anchor{5130}
@subsubsection 型別檢查巨集


@geindex PyByteArray_Check (C function)
@anchor{c-api/bytearray c PyByteArray_Check}@anchor{5131}
@deffn {C 函式} int PyByteArray_Check (PyObject *o)

如果物件 `o' 是一個位元組陣列物件，或者是位元組陣列型別的子型別的實例，則回傳真值。此函式總是會成功執行。
@end deffn

@geindex PyByteArray_CheckExact (C function)
@anchor{c-api/bytearray c PyByteArray_CheckExact}@anchor{5132}
@deffn {C 函式} int PyByteArray_CheckExact (PyObject *o)

如果物件 `o' 是一個位元組陣列物件，但不是位元組陣列型別的子型別的實例，則回傳真值。此函式總是會成功執行。
@end deffn

@node 直接 API 函式,巨集,型別檢查巨集,位元組陣列物件 Byte Array Objects
@anchor{c-api/bytearray direct-api-functions}@anchor{5133}
@subsubsection 直接 API 函式


@geindex PyByteArray_FromObject (C function)
@anchor{c-api/bytearray c PyByteArray_FromObject}@anchor{15a0}
@deffn {C 函式} @ref{5d7,,PyObject} *PyByteArray_FromObject (PyObject *o)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
由任意物件 `o' 回傳一個新的位元組陣列物件，並實作了@ref{260,,緩衝協定 (buffer protocol)}。

在失敗時，會回傳 @code{NULL} 並設定例外。
@end deffn

@geindex PyByteArray_FromStringAndSize (C function)
@anchor{c-api/bytearray c PyByteArray_FromStringAndSize}@anchor{15a1}
@deffn {C 函式} @ref{5d7,,PyObject} *PyByteArray_FromStringAndSize (const char *string, Py_ssize_t len)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
從 `string' 及其長度 `len' 建立一個新的位元組陣列物件。

在失敗時，會回傳 @code{NULL} 並設定例外。
@end deffn

@geindex PyByteArray_Concat (C function)
@anchor{c-api/bytearray c PyByteArray_Concat}@anchor{4e1b}
@deffn {C 函式} @ref{5d7,,PyObject} *PyByteArray_Concat (PyObject *a, PyObject *b)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
連接位元組陣列 `a' 和 `b'，並回傳一個包含結果的新位元組陣列。

在失敗時，會回傳 @code{NULL} 並設定例外。
@end deffn

@geindex PyByteArray_Size (C function)
@anchor{c-api/bytearray c PyByteArray_Size}@anchor{4e1d}
@deffn {C 函式} @ref{c4c,,Py_ssize_t} PyByteArray_Size (PyObject *bytearray)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
在檢查為 @code{NULL} 指標後，回傳 `bytearray' 的大小。
@end deffn

@geindex PyByteArray_AsString (C function)
@anchor{c-api/bytearray c PyByteArray_AsString}@anchor{4e1a}
@deffn {C 函式} char *PyByteArray_AsString (PyObject *bytearray)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
在檢查是否為 @code{NULL} 指標後，將 `bytearray' 的內容回傳為字元陣列。回傳的陣列總是會多附加一個空位元組。
@end deffn

@geindex PyByteArray_Resize (C function)
@anchor{c-api/bytearray c PyByteArray_Resize}@anchor{4e1c}
@deffn {C 函式} int PyByteArray_Resize (PyObject *bytearray, Py_ssize_t len)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
將 `bytearray' 的內部緩衝區大小調整為 `len'。失敗時會回傳 @code{-1} 並設定例外。


在 3.14 版的變更: 負的 `len' 現在會設定例外並回傳 -1。

@end deffn

@node 巨集,,直接 API 函式,位元組陣列物件 Byte Array Objects
@anchor{c-api/bytearray macros}@anchor{5134}
@subsubsection 巨集


這些巨集犧牲了安全性以換取速度，並且它們不會檢查指標。

@geindex PyByteArray_AS_STRING (C function)
@anchor{c-api/bytearray c PyByteArray_AS_STRING}@anchor{5135}
@deffn {C 函式} char *PyByteArray_AS_STRING (PyObject *bytearray)

與 @ref{4e1a,,PyByteArray_AsString()} 類似，但沒有錯誤檢查。
@end deffn

@geindex PyByteArray_GET_SIZE (C function)
@anchor{c-api/bytearray c PyByteArray_GET_SIZE}@anchor{5136}
@deffn {C 函式} @ref{c4c,,Py_ssize_t} PyByteArray_GET_SIZE (PyObject *bytearray)

與 @ref{4e1d,,PyByteArray_Size()} 類似，但沒有錯誤檢查。
@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 物件與編解碼器,Tuple（元組）物件,位元組陣列物件 Byte Array Objects,序列物件
@anchor{c-api/unicode doc}@anchor{13a1}@anchor{c-api/unicode translation-repo}@anchor{5137}@anchor{c-api/unicode unicode-objects-and-codecs}@anchor{5138}@anchor{c-api/unicode unicodeobjects}@anchor{5139}
@subsubsection Unicode 物件與編解碼器


@menu
* Unicode 物件:: 
* 內建編解碼器:: 
* Methods and Slot Functions:: 
* PyUnicodeWriter:: 
* 已棄用的 API:: 

@end menu

@node Unicode 物件,內建編解碼器,,Unicode 物件與編解碼器
@anchor{c-api/unicode unicode-objects}@anchor{513a}
@subsubsection Unicode 物件


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 表示法會在需要時建立並快取在 Unicode 物件中。

@cartouche
@quotation 備註 
自 Python 3.12 起，已移除 @ref{3de,,Py_UNICODE} 表示法，並標示為已棄用的 API。更多資訊請參閱 
@geindex Python Enhancement Proposals; PEP 623
PEP 623@footnote{https://peps.python.org/pep-0623/}。
@end quotation
@end cartouche

@menu
* Unicode 型別:: 
* Unicode Character Properties:: 
* Creating and accessing Unicode strings:: 
* Locale Encoding:: 
* 檔案系統編碼:: 
* wchar_t 支援:: 

@end menu

@node Unicode 型別,Unicode Character Properties,,Unicode 物件
@anchor{c-api/unicode unicode-type}@anchor{513b}
@subsubsection Unicode 型別


這些是 Python 中用於 Unicode 實作的基本 Unicode 物件型別：

@geindex PyUnicode_Type (C var)
@anchor{c-api/unicode c PyUnicode_Type}@anchor{4f89}
@deffn {C 變數} @ref{c93,,PyTypeObject} PyUnicode_Type
` 為 @ref{76e,,穩定 ABI 的一部分}.'
This instance of @ref{c93,,PyTypeObject} represents the Python Unicode type.
It is exposed to Python code as @ref{169,,str}.
@end deffn

@geindex PyUnicodeIter_Type (C var)
@anchor{c-api/unicode c PyUnicodeIter_Type}@anchor{4f5a}
@deffn {C 變數} @ref{c93,,PyTypeObject} PyUnicodeIter_Type
` 為 @ref{76e,,穩定 ABI 的一部分}.'
This instance of @ref{c93,,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{33c}
@deffn {C 型別} type Py_UCS4
@anchor{c-api/unicode c Py_UCS2}@anchor{1375}
@deffnx {C 型別} type Py_UCS2
@anchor{c-api/unicode c Py_UCS1}@anchor{1374}
@deffnx {C 型別} type Py_UCS1
` 為 @ref{76e,,穩定 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{33c,,Py_UCS4}.


在 3.3 版被加入.

@end deffn

@geindex PyASCIIObject (C type)
@geindex PyCompactUnicodeObject (C type)
@geindex PyUnicodeObject (C type)
@anchor{c-api/unicode c PyASCIIObject}@anchor{1376}
@deffn {C 型別} type PyASCIIObject
@anchor{c-api/unicode c PyCompactUnicodeObject}@anchor{1377}
@deffnx {C 型別} type PyCompactUnicodeObject
@anchor{c-api/unicode c PyUnicodeObject}@anchor{98f}
@deffnx {C 型別} type PyUnicodeObject

These subtypes of @ref{5d7,,PyObject} represent a Python Unicode object.  In
almost all cases, they shouldn't be used directly, since all API functions
that deal with Unicode objects take and return @ref{5d7,,PyObject} pointers.


在 3.3 版被加入.

@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{513c}
@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{513d}
@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{aa8}
@deffn {C 函式} @ref{c4c,,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).


在 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{137b}
@deffn {C 函式} @ref{1374,,Py_UCS1} *PyUnicode_1BYTE_DATA (PyObject *unicode)
@anchor{c-api/unicode c PyUnicode_2BYTE_DATA}@anchor{137c}
@deffnx {C 函式} @ref{1375,,Py_UCS2} *PyUnicode_2BYTE_DATA (PyObject *unicode)
@anchor{c-api/unicode c PyUnicode_4BYTE_DATA}@anchor{137d}
@deffnx {C 函式} @ref{33c,,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{137e,,PyUnicode_KIND()} to select the right function.


在 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{137f}
@deffn {C 巨集} PyUnicode_1BYTE_KIND
@anchor{c-api/unicode c PyUnicode_2BYTE_KIND}@anchor{1380}
@deffnx {C 巨集} PyUnicode_2BYTE_KIND
@anchor{c-api/unicode c PyUnicode_4BYTE_KIND}@anchor{1381}
@deffnx {C 巨集} PyUnicode_4BYTE_KIND

Return values of the @ref{137e,,PyUnicode_KIND()} macro.


在 3.3 版被加入.



在 3.12 版的變更: @code{PyUnicode_WCHAR_KIND} 已被移除。

@end deffn

@geindex PyUnicode_KIND (C function)
@anchor{c-api/unicode c PyUnicode_KIND}@anchor{137e}
@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).


在 3.3 版被加入.

@end deffn

@geindex PyUnicode_DATA (C function)
@anchor{c-api/unicode c PyUnicode_DATA}@anchor{137a}
@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).


在 3.3 版被加入.

@end deffn

@geindex PyUnicode_WRITE (C function)
@anchor{c-api/unicode c PyUnicode_WRITE}@anchor{1384}
@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{137e,,PyUnicode_KIND()} and @ref{137a,,PyUnicode_DATA()}
respectively. You must hold a reference to that string while calling
@code{PyUnicode_WRITE()}. All requirements of
@ref{1373,,PyUnicode_WriteChar()} also apply.

The function performs no checks for any of its requirements,
and is intended for usage in loops.


在 3.3 版被加入.

@end deffn

@geindex PyUnicode_READ (C function)
@anchor{c-api/unicode c PyUnicode_READ}@anchor{1382}
@deffn {C 函式} @ref{33c,,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{137a,,PyUnicode_DATA()}).  No checks or ready calls are performed.


在 3.3 版被加入.

@end deffn

@geindex PyUnicode_READ_CHAR (C function)
@anchor{c-api/unicode c PyUnicode_READ_CHAR}@anchor{1383}
@deffn {C 函式} @ref{33c,,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{1382,,PyUnicode_READ()} if you
do multiple consecutive reads.


在 3.3 版被加入.

@end deffn

@geindex PyUnicode_MAX_CHAR_VALUE (C function)
@anchor{c-api/unicode c PyUnicode_MAX_CHAR_VALUE}@anchor{1385}
@deffn {C 函式} @ref{33c,,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.


在 3.3 版被加入.

@end deffn

@geindex PyUnicode_IsIdentifier (C function)
@anchor{c-api/unicode c PyUnicode_IsIdentifier}@anchor{1c4f}
@deffn {C 函式} int PyUnicode_IsIdentifier (PyObject *unicode)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return @code{1} if the string is a valid identifier according to the language
definition, section @ref{2164,,Names (identifiers and keywords)}. Return @code{0} otherwise.


在 3.9 版的變更: The function does not call @ref{b71,,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{513e}
@deffn {C 函式} unsigned int PyUnicode_IS_ASCII (PyObject *unicode)

Return true if the string only contains ASCII characters.
Equivalent to @ref{ce0,,str.isascii()}.


在 3.2 版被加入.

@end deffn

@node Unicode Character Properties,Creating and accessing Unicode strings,Unicode 型別,Unicode 物件
@anchor{c-api/unicode unicode-character-properties}@anchor{513f}
@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{1bbb}
@deffn {C 函式} int Py_UNICODE_ISSPACE (Py_UCS4 ch)

根據 `ch' 是否為空白字元來回傳 @code{1} 或 @code{0}。
@end deffn

@geindex Py_UNICODE_ISLOWER (C function)
@anchor{c-api/unicode c Py_UNICODE_ISLOWER}@anchor{5140}
@deffn {C 函式} int Py_UNICODE_ISLOWER (Py_UCS4 ch)

根據 `ch' 是否為小寫字元來回傳 @code{1} 或 @code{0}。
@end deffn

@geindex Py_UNICODE_ISUPPER (C function)
@anchor{c-api/unicode c Py_UNICODE_ISUPPER}@anchor{5141}
@deffn {C 函式} int Py_UNICODE_ISUPPER (Py_UCS4 ch)

根據 `ch' 是否為大寫字元來回傳 @code{1} 或 @code{0}。
@end deffn

@geindex Py_UNICODE_ISTITLE (C function)
@anchor{c-api/unicode c Py_UNICODE_ISTITLE}@anchor{5142}
@deffn {C 函式} int Py_UNICODE_ISTITLE (Py_UCS4 ch)

根據 `ch' 是否為首字大寫字元來回傳 @code{1} 或 @code{0}。
@end deffn

@geindex Py_UNICODE_ISLINEBREAK (C function)
@anchor{c-api/unicode c Py_UNICODE_ISLINEBREAK}@anchor{5143}
@deffn {C 函式} int Py_UNICODE_ISLINEBREAK (Py_UCS4 ch)

根據 `ch' 是否為換行字元來回傳 @code{1} 或 @code{0}。
@end deffn

@geindex Py_UNICODE_ISDECIMAL (C function)
@anchor{c-api/unicode c Py_UNICODE_ISDECIMAL}@anchor{5144}
@deffn {C 函式} int Py_UNICODE_ISDECIMAL (Py_UCS4 ch)

根據 `ch' 是否為十進位字元來回傳 @code{1} 或 @code{0}。
@end deffn

@geindex Py_UNICODE_ISDIGIT (C function)
@anchor{c-api/unicode c Py_UNICODE_ISDIGIT}@anchor{5145}
@deffn {C 函式} int Py_UNICODE_ISDIGIT (Py_UCS4 ch)

根據 `ch' 是否為數字 (digit) 字元來回傳 @code{1} 或 @code{0}。
@end deffn

@geindex Py_UNICODE_ISNUMERIC (C function)
@anchor{c-api/unicode c Py_UNICODE_ISNUMERIC}@anchor{5146}
@deffn {C 函式} int Py_UNICODE_ISNUMERIC (Py_UCS4 ch)

根據 `ch' 是否為數值 (numeric) 字元來回傳 @code{1} 或 @code{0}。
@end deffn

@geindex Py_UNICODE_ISALPHA (C function)
@anchor{c-api/unicode c Py_UNICODE_ISALPHA}@anchor{5147}
@deffn {C 函式} int Py_UNICODE_ISALPHA (Py_UCS4 ch)

根據 `ch' 是否為字母字元來回傳 @code{1} 或 @code{0}。
@end deffn

@geindex Py_UNICODE_ISALNUM (C function)
@anchor{c-api/unicode c Py_UNICODE_ISALNUM}@anchor{5148}
@deffn {C 函式} int Py_UNICODE_ISALNUM (Py_UCS4 ch)

根據 `ch' 是否為字母數字 (alphanumeric) 字元來回傳 @code{1} 或 @code{0}。
@end deffn

@geindex Py_UNICODE_ISPRINTABLE (C function)
@anchor{c-api/unicode c Py_UNICODE_ISPRINTABLE}@anchor{5149}
@deffn {C 函式} int Py_UNICODE_ISPRINTABLE (Py_UCS4 ch)

根據 `ch' 是否為可列印字元（如 @ref{fd3,,str.isprintable()} 所定義）來回傳 @code{1} 或 @code{0}。
@end deffn

這些 API 可用於快速直接字元轉換：

@geindex Py_UNICODE_TOLOWER (C function)
@anchor{c-api/unicode c Py_UNICODE_TOLOWER}@anchor{514a}
@deffn {C 函式} @ref{33c,,Py_UCS4} Py_UNICODE_TOLOWER (Py_UCS4 ch)

回傳轉換為小寫的 `ch' 字元。
@end deffn

@geindex Py_UNICODE_TOUPPER (C function)
@anchor{c-api/unicode c Py_UNICODE_TOUPPER}@anchor{514b}
@deffn {C 函式} @ref{33c,,Py_UCS4} Py_UNICODE_TOUPPER (Py_UCS4 ch)

回傳轉換為大寫的 `ch' 字元。
@end deffn

@geindex Py_UNICODE_TOTITLE (C function)
@anchor{c-api/unicode c Py_UNICODE_TOTITLE}@anchor{514c}
@deffn {C 函式} @ref{33c,,Py_UCS4} Py_UNICODE_TOTITLE (Py_UCS4 ch)

回傳轉換為首字大寫的 `ch' 字元。
@end deffn

@geindex Py_UNICODE_TODECIMAL (C function)
@anchor{c-api/unicode c Py_UNICODE_TODECIMAL}@anchor{514d}
@deffn {C 函式} int Py_UNICODE_TODECIMAL (Py_UCS4 ch)

回傳轉換為十進位正整數的 `ch' 字元，若無法轉換則回傳 @code{-1}。此函式不會引發例外。
@end deffn

@geindex Py_UNICODE_TODIGIT (C function)
@anchor{c-api/unicode c Py_UNICODE_TODIGIT}@anchor{514e}
@deffn {C 函式} int Py_UNICODE_TODIGIT (Py_UCS4 ch)

回傳轉換為單一數字整數的 `ch' 字元，若無法轉換則回傳 @code{-1}。此函式不會引發例外。
@end deffn

@geindex Py_UNICODE_TONUMERIC (C function)
@anchor{c-api/unicode c Py_UNICODE_TONUMERIC}@anchor{514f}
@deffn {C 函式} double Py_UNICODE_TONUMERIC (Py_UCS4 ch)

回傳轉換為雙精度浮點數 (double) 的 `ch' 字元，若無法轉換則回傳 @code{-1.0}。此函式不會引發例外。
@end deffn

這些 API 可用於處理代理字元：

@geindex Py_UNICODE_IS_SURROGATE (C function)
@anchor{c-api/unicode c Py_UNICODE_IS_SURROGATE}@anchor{5150}
@deffn {C 函式} int Py_UNICODE_IS_SURROGATE (Py_UCS4 ch)

檢查 `ch' 是否為代理字元 (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{5151}
@deffn {C 函式} int Py_UNICODE_IS_HIGH_SURROGATE (Py_UCS4 ch)

檢查 `ch' 是否為高代理字元 (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{5152}
@deffn {C 函式} int Py_UNICODE_IS_LOW_SURROGATE (Py_UCS4 ch)

檢查 `ch' 是否為低代理字元 (low surrogate, @code{0xDC00 <= ch <= 0xDFFF})。
@end deffn

@geindex Py_UNICODE_JOIN_SURROGATES (C function)
@anchor{c-api/unicode c Py_UNICODE_JOIN_SURROGATES}@anchor{5153}
@deffn {C 函式} @ref{33c,,Py_UCS4} Py_UNICODE_JOIN_SURROGATES (Py_UCS4 high, Py_UCS4 low)

Join two surrogate code points and return a single @ref{33c,,Py_UCS4} value.
`high' and `low' are respectively the leading and trailing surrogates in a
surrogate pair. `high' must be in the range [0xD800; 0xDBFF] and `low' must
be in the range [0xDC00; 0xDFFF].
@end deffn

@node Creating and accessing Unicode strings,Locale Encoding,Unicode Character Properties,Unicode 物件
@anchor{c-api/unicode creating-and-accessing-unicode-strings}@anchor{5154}
@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{aa0}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_New (Py_ssize_t size, Py_UCS4 maxchar)
`回傳值：新的參照。'
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{1373,,PyUnicode_WriteChar()},
@ref{aa9,,PyUnicode_CopyCharacters()}, @ref{138e,,PyUnicode_Fill()},
@ref{1384,,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{a90,,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{3b1,,PyUnicodeWriter} API, or one of the @code{PyUnicode_From*}
functions below.


在 3.3 版被加入.

@end deffn

@geindex PyUnicode_FromKindAndData (C function)
@anchor{c-api/unicode c PyUnicode_FromKindAndData}@anchor{1378}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_FromKindAndData (int kind, const void *buffer, Py_ssize_t size)
`回傳值：新的參照。'
Create a new Unicode object with the given `kind' (possible values are
@ref{137f,,PyUnicode_1BYTE_KIND} etc., as returned by
@ref{137e,,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{1381,,PyUnicode_4BYTE_KIND}) and it consists only of codepoints in
the UCS1 range, it will be transformed into UCS1
(@ref{137f,,PyUnicode_1BYTE_KIND}).


在 3.3 版被加入.

@end deffn

@geindex PyUnicode_FromStringAndSize (C function)
@anchor{c-api/unicode c PyUnicode_FromStringAndSize}@anchor{4f81}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_FromStringAndSize (const char *str, Py_ssize_t size)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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.

此函式在以下情況下會引發 @ref{78e,,SystemError}：


@itemize *

@item 
`size' < 0，

@item 
`str' 為 @code{NULL} 且 `size' > 0
@end itemize


在 3.12 版的變更: `str' == @code{NULL} 且 `size' > 0 不再被允許。

@end deffn

@geindex PyUnicode_FromString (C function)
@anchor{c-api/unicode c PyUnicode_FromString}@anchor{4f80}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_FromString (const char *str)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{623}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_FromFormat (const char *format, ...)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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

旗標

@tab

含義

@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 或 unsigned long

@item

@code{ll}

@tab

long long 或 unsigned long long

@item

@code{j}

@tab

@code{intmax_t} 或 @code{uintmax_t}

@item

@code{z}

@tab

@code{size_t} 或 @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

字面 @code{%} 字元。

@item

@code{d}, @code{i}

@tab

Specified by the length modifier

@tab

一個有符號 C 整數的十進位表示法。

@item

@code{u}

@tab

Specified by the length modifier

@tab

一個無符號 C 整數的十進位表示法。

@item

@code{o}

@tab

Specified by the length modifier

@tab

一個無符號 C 整數的八進位表示法。

@item

@code{x}

@tab

Specified by the length modifier

@tab

一個無符號 C 整數的十六進位表示法（小寫）。

@item

@code{X}

@tab

Specified by the length modifier

@tab

一個無符號 C 整數的十六進位表示法（大寫）。

@item

@code{c}

@tab

int

@tab

一個單一字元。

@item

@code{s}

@tab

const char* 或 const wchar_t*

@tab

一個以 null 結尾的 C 字元陣列。

@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{5d7,,PyObject}*

@tab

呼叫 @ref{15dd,,ascii()} 的結果。

@item

@code{U}

@tab

@ref{5d7,,PyObject}*

@tab

一個 Unicode 物件。

@item

@code{V}

@tab

@ref{5d7,,PyObject}*、const char* 或 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{5d7,,PyObject}*

@tab

呼叫 @ref{122b,,PyObject_Str()} 的結果。

@item

@code{R}

@tab

@ref{5d7,,PyObject}*

@tab

呼叫 @ref{122a,,PyObject_Repr()} 的結果。

@item

@code{T}

@tab

@ref{5d7,,PyObject}*

@tab

Get the fully qualified name of an object type;
call @ref{60e,,PyType_GetFullyQualifiedName()}.

@item

@code{#T}

@tab

@ref{5d7,,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{c93,,PyTypeObject}*

@tab

Get the fully qualified name of a type;
call @ref{60e,,PyType_GetFullyQualifiedName()}.

@item

@code{#N}

@tab

@ref{c93,,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 版的變更: 新增對 @code{"%lld"} 和 @code{"%llu"} 的支援。



在 3.3 版的變更: 新增對 @code{"%li"}、@code{"%lli"} 和 @code{"%zi"} 的支援。



在 3.4 版的變更: 新增對 @code{"%s"}、@code{"%A"}、@code{"%U"}、@code{"%V"}、@code{"%S"}、@code{"%R"} 的寬度和精確度格式化支援。



在 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{78e,,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 版的變更: 新增對 @code{%T}、@code{%#T}、@code{%N} 和 @code{%#N} 格式的支援。

@end deffn

@geindex PyUnicode_FromFormatV (C function)
@anchor{c-api/unicode c PyUnicode_FromFormatV}@anchor{78d}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_FromFormatV (const char *format, va_list vargs)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Identical to @ref{623,,PyUnicode_FromFormat()} except that it takes exactly two
arguments.
@end deffn

@geindex PyUnicode_FromObject (C function)
@anchor{c-api/unicode c PyUnicode_FromObject}@anchor{4f7e}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_FromObject (PyObject *obj)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{5da,,strong reference} to the object.

Objects other than Unicode or its subtypes will cause a @ref{198,,TypeError}.
@end deffn

@geindex PyUnicode_FromOrdinal (C function)
@anchor{c-api/unicode c PyUnicode_FromOrdinal}@anchor{4f7f}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_FromOrdinal (int ordinal)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Create a Unicode Object from the given Unicode code point `ordinal'.

The ordinal must be in @code{range(0x110000)}. A @ref{2eb,,ValueError} is
raised in the case it is not.
@end deffn

@geindex PyUnicode_FromEncodedObject (C function)
@anchor{c-api/unicode c PyUnicode_FromEncodedObject}@anchor{4f7d}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_FromEncodedObject (PyObject *obj, const char *encoding, const char *errors)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Decode an encoded object `obj' to a Unicode object.

@ref{192,,bytes}, @ref{343,,bytearray} and other
@ref{193,,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{5155,,內建編解碼器} for details).

All other objects, including Unicode objects, cause a @ref{198,,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{4f62}
@deffn {C 函式} void PyUnicode_Append (PyObject **p_left, PyObject *right)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Append the string `right' to the end of `p_left'.
`p_left' must point to a @ref{5da,,strong reference} to a Unicode object;
@code{PyUnicode_Append()} releases ("steals") this reference.

於錯誤發生時，將 `*p_left' 設為 @code{NULL} 並設定例外。

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{4f63}
@deffn {C 函式} void PyUnicode_AppendAndDel (PyObject **p_left, PyObject *right)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
The function is similar to @ref{4f62,,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{19b3}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_BuildEncodingMap (PyObject *string)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{198,,TypeError} and
return @code{NULL} on invalid input.


在 3.2 版被加入.

@end deffn

@geindex PyUnicode_GetDefaultEncoding (C function)
@anchor{c-api/unicode c PyUnicode_GetDefaultEncoding}@anchor{4f82}
@deffn {C 函式} const char *PyUnicode_GetDefaultEncoding (void)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return the name of the default string encoding, @code{"utf-8"}.
See @ref{47cf,,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{aa7}
@deffn {C 函式} @ref{c4c,,Py_ssize_t} PyUnicode_GetLength (PyObject *unicode)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.7 版本開始.'
Return the length of the Unicode object, in code points.

發生錯誤時，設定例外並回傳 @code{-1}。


在 3.3 版被加入.

@end deffn

@geindex PyUnicode_CopyCharacters (C function)
@anchor{c-api/unicode c PyUnicode_CopyCharacters}@anchor{aa9}
@deffn {C 函式} @ref{c4c,,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{aa0,,PyUnicode_New()} for details.


在 3.3 版被加入.

@end deffn

@geindex PyUnicode_Resize (C function)
@anchor{c-api/unicode c PyUnicode_Resize}@anchor{4f84}
@deffn {C 函式} int PyUnicode_Resize (PyObject **unicode, Py_ssize_t length);
` 為 @ref{76e,,穩定 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{138e}
@deffn {C 函式} @ref{c4c,,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{aa0,,PyUnicode_New()} for details.

Return the number of written character, or return @code{-1} and raise an
exception on error.


在 3.3 版被加入.

@end deffn

@geindex PyUnicode_WriteChar (C function)
@anchor{c-api/unicode c PyUnicode_WriteChar}@anchor{1373}
@deffn {C 函式} int PyUnicode_WriteChar (PyObject *unicode, Py_ssize_t index, Py_UCS4 character)
` 為 @ref{76e,,穩定 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{1384,,PyUnicode_WRITE()} for a version that skips these checks,
making them your responsibility.

The string must not have been “used” yet.
See @ref{aa0,,PyUnicode_New()} for details.


在 3.3 版被加入.

@end deffn

@geindex PyUnicode_ReadChar (C function)
@anchor{c-api/unicode c PyUnicode_ReadChar}@anchor{1372}
@deffn {C 函式} @ref{33c,,Py_UCS4} PyUnicode_ReadChar (PyObject *unicode, Py_ssize_t index)
` 為 @ref{76e,,穩定 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{1383,,PyUnicode_READ_CHAR()}, which performs no error checking.

成功時回傳字元，發生錯誤時設定例外並回傳 @code{-1}。


在 3.3 版被加入.

@end deffn

@geindex PyUnicode_Substring (C function)
@anchor{c-api/unicode c PyUnicode_Substring}@anchor{aaa}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_Substring (PyObject *unicode, Py_ssize_t start, Py_ssize_t end)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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}.


在 3.3 版被加入.

@end deffn

@geindex PyUnicode_AsUCS4 (C function)
@anchor{c-api/unicode c PyUnicode_AsUCS4}@anchor{1379}
@deffn {C 函式} @ref{33c,,Py_UCS4} *PyUnicode_AsUCS4 (PyObject *unicode, Py_UCS4 *buffer, Py_ssize_t buflen, int copy_null)
` 為 @ref{76e,,穩定 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{78e,,SystemError} if `buflen' is smaller than the length of
`unicode').  `buffer' is returned on success.


在 3.3 版被加入.

@end deffn

@geindex PyUnicode_AsUCS4Copy (C function)
@anchor{c-api/unicode c PyUnicode_AsUCS4Copy}@anchor{aaf}
@deffn {C 函式} @ref{33c,,Py_UCS4} *PyUnicode_AsUCS4Copy (PyObject *unicode)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.7 版本開始.'
Copy the string `unicode' into a new UCS4 buffer that is allocated using
@ref{e5b,,PyMem_Malloc()}.  If this fails, @code{NULL} is returned with a
@ref{181e,,MemoryError} set.  The returned buffer always has an extra
null code point appended.


在 3.3 版被加入.

@end deffn

@node Locale Encoding,檔案系統編碼,Creating and accessing Unicode strings,Unicode 物件
@anchor{c-api/unicode locale-encoding}@anchor{5156}
@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{dbd}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_DecodeLocaleAndSize (const char *str, Py_ssize_t length, const char *errors)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{4f6d,,PyUnicode_DecodeFSDefaultAndSize()} to decode a string from
the @ref{756,,filesystem encoding and error handler}.

此函式會忽略 @ref{85f,,Python UTF-8 模式}。


@subsubheading 也參考


@ref{dbb,,Py_DecodeLocale()} 函式。



在 3.3 版被加入.



在 3.7 版的變更: The function now also uses the current locale encoding for the
@code{surrogateescape} error handler, except on Android. Previously, @ref{dbb,,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{4f6f}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_DecodeLocale (const char *str, const char *errors)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.7 版本開始.'
類似於 @ref{dbd,,PyUnicode_DecodeLocaleAndSize()}，但使用 @code{strlen()} 計算字串長度。


在 3.3 版被加入.

@end deffn

@geindex PyUnicode_EncodeLocale (C function)
@anchor{c-api/unicode c PyUnicode_EncodeLocale}@anchor{dbe}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_EncodeLocale (PyObject *unicode, const char *errors)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{192,,bytes} object. `unicode' cannot
contain embedded null characters.

Use @ref{1cf9,,PyUnicode_EncodeFSDefault()} to encode a string to the
@ref{756,,filesystem encoding and error handler}.

此函式會忽略 @ref{85f,,Python UTF-8 模式}。


@subsubheading 也參考


@ref{dbc,,Py_EncodeLocale()} 函式。



在 3.3 版被加入.



在 3.7 版的變更: The function now also uses the current locale encoding for the
@code{surrogateescape} error handler, except on Android. Previously,
@ref{dbc,,Py_EncodeLocale()}
was used for the @code{surrogateescape}, and the current locale encoding was
used for @code{strict}.

@end deffn

@node 檔案系統編碼,wchar_t 支援,Locale Encoding,Unicode 物件
@anchor{c-api/unicode file-system-encoding}@anchor{5157}
@subsubsection 檔案系統編碼


Functions encoding to and decoding from the @ref{756,,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{192,,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{f10}
@deffn {C 函式} int PyUnicode_FSConverter (PyObject *obj, void *result)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@ref{3d3,,PyArg_Parse* converter}: encode @ref{169,,str} objects -- obtained directly or
through the @ref{e46,,os.PathLike} interface -- to @ref{192,,bytes} using
@ref{1cf9,,PyUnicode_EncodeFSDefault()}; @ref{192,,bytes} objects are output as-is.
`result' must be an address of a C variable of type @ref{5d7,,PyObject}*
(or @ref{98d,,PyBytesObject}*).
On success, set the variable to a new @ref{5da,,strong reference} to
a @ref{5127,,bytes object} which must be released
when it is no longer used and return a non-zero value
(@ref{5030,,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}.


在 3.1 版被加入.



在 3.6 版的變更: 接受一個 @ref{59b,,path-like object}。

@end deffn

To decode file names to @ref{169,,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{790}
@deffn {C 函式} int PyUnicode_FSDecoder (PyObject *obj, void *result)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@ref{3d3,,PyArg_Parse* converter}: decode @ref{192,,bytes} objects -- obtained either
directly or indirectly through the @ref{e46,,os.PathLike} interface -- to
@ref{169,,str} using @ref{4f6d,,PyUnicode_DecodeFSDefaultAndSize()}; @ref{169,,str}
objects are output as-is.
`result' must be an address of a C variable of type @ref{5d7,,PyObject}*
(or @ref{98f,,PyUnicodeObject}*).
On success, set the variable to a new @ref{5da,,strong reference} to
a @ref{5139,,Unicode object} which must be released
when it is no longer used and return a non-zero value
(@ref{5030,,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}.


在 3.2 版被加入.



在 3.6 版的變更: 接受一個 @ref{59b,,path-like object}。

@end deffn

@geindex PyUnicode_DecodeFSDefaultAndSize (C function)
@anchor{c-api/unicode c PyUnicode_DecodeFSDefaultAndSize}@anchor{4f6d}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_DecodeFSDefaultAndSize (const char *str, Py_ssize_t size)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Decode a string from the @ref{756,,filesystem encoding and error handler}.

If you need to decode a string from the current locale encoding, use
@ref{dbd,,PyUnicode_DecodeLocaleAndSize()}.


@subsubheading 也參考


@ref{dbb,,Py_DecodeLocale()} 函式。



在 3.6 版的變更: The @ref{756,,filesystem error handler} is now used.

@end deffn

@geindex PyUnicode_DecodeFSDefault (C function)
@anchor{c-api/unicode c PyUnicode_DecodeFSDefault}@anchor{19da}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_DecodeFSDefault (const char *str)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Decode a null-terminated string from the @ref{756,,filesystem encoding and error handler}.

如果字串長度已知，請使用 @ref{4f6d,,PyUnicode_DecodeFSDefaultAndSize()}。


在 3.6 版的變更: The @ref{756,,filesystem error handler} is now used.

@end deffn

@geindex PyUnicode_EncodeFSDefault (C function)
@anchor{c-api/unicode c PyUnicode_EncodeFSDefault}@anchor{1cf9}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_EncodeFSDefault (PyObject *unicode)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Encode a Unicode object to the @ref{756,,filesystem encoding and error handler}, and return @ref{192,,bytes}. Note that the resulting @ref{192,,bytes}
object can contain null bytes.

If you need to encode a string to the current locale encoding, use
@ref{dbe,,PyUnicode_EncodeLocale()}.


@subsubheading 也參考


@ref{dbc,,Py_EncodeLocale()} 函式。



在 3.2 版被加入.



在 3.6 版的變更: The @ref{756,,filesystem error handler} is now used.

@end deffn

@node wchar_t 支援,,檔案系統編碼,Unicode 物件
@anchor{c-api/unicode wchar-t-support}@anchor{5158}
@subsubsection wchar_t 支援


對支援 @code{wchar_t} 的平台提供支援：

@geindex PyUnicode_FromWideChar (C function)
@anchor{c-api/unicode c PyUnicode_FromWideChar}@anchor{138d}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_FromWideChar (const wchar_t *wstr, Py_ssize_t size)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{1cff}
@deffn {C 函式} @ref{c4c,,Py_ssize_t} PyUnicode_AsWideChar (PyObject *unicode, wchar_t *wstr, Py_ssize_t size)
` 為 @ref{76e,,穩定 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{ab0}
@deffn {C 函式} wchar_t *PyUnicode_AsWideCharString (PyObject *unicode, Py_ssize_t *size)
` 為 @ref{76e,,穩定 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{2eb,,ValueError} is raised.

Returns a buffer allocated by @ref{1718,,PyMem_New} (use
@ref{1639,,PyMem_Free()} to free it) on success. On error, returns @code{NULL}
and `*size' is undefined. Raises a @ref{181e,,MemoryError} if memory allocation
is failed.


在 3.2 版被加入.



在 3.7 版的變更: Raises a @ref{2eb,,ValueError} if `size' is @code{NULL} and the wchar_t*
string contains null characters.

@end deffn

@node 內建編解碼器,Methods and Slot Functions,Unicode 物件,Unicode 物件與編解碼器
@anchor{c-api/unicode built-in-codecs}@anchor{5159}@anchor{c-api/unicode builtincodecs}@anchor{5155}
@subsubsection 內建編解碼器


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{169,,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{f10,,PyUnicode_FSConverter()} for encoding file names. This uses the
@ref{756,,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{2eb,,ValueError} is raised).

The codecs all use a similar interface.  Only deviations from the following
generic ones are documented for simplicity.

@menu
* 泛用編解碼器:: 
* UTF-8 編解碼器:: 
* UTF-32 編解碼器:: 
* UTF-16 編解碼器:: 
* UTF-7 編解碼器:: 
* Unicode-Escape Codecs:: 
* Raw-Unicode-Escape Codecs:: 
* Latin-1 編解碼器:: 
* ASCII 編解碼器:: 
* Character Map Codecs:: 
* Windows 的 MBCS 編解碼器:: 

@end menu

@node 泛用編解碼器,UTF-8 編解碼器,,內建編解碼器
@anchor{c-api/unicode generic-codecs}@anchor{515a}
@subsubsection 泛用編解碼器


The following macro is provided:

@geindex Py_UNICODE_REPLACEMENT_CHARACTER (C macro)
@anchor{c-api/unicode c Py_UNICODE_REPLACEMENT_CHARACTER}@anchor{515b}
@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

這些是泛用編解碼器的 API：

@geindex PyUnicode_Decode (C function)
@anchor{c-api/unicode c PyUnicode_Decode}@anchor{1c90}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_Decode (const char *str, Py_ssize_t size, const char *encoding, const char *errors)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{169,,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{4f65}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_AsEncodedString (PyObject *unicode, const char *encoding, const char *errors)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{ac9,,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 編解碼器,UTF-32 編解碼器,泛用編解碼器,內建編解碼器
@anchor{c-api/unicode utf-8-codecs}@anchor{515c}
@subsubsection UTF-8 編解碼器


這些是 UTF-8 編解碼器的 API：

@geindex PyUnicode_DecodeUTF8 (C function)
@anchor{c-api/unicode c PyUnicode_DecodeUTF8}@anchor{4f79}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_DecodeUTF8 (const char *str, Py_ssize_t size, const char *errors)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{1a5b}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_DecodeUTF8Stateful (const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
If `consumed' is @code{NULL}, behave like @ref{4f79,,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{138f}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_AsUTF8String (PyObject *unicode)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{a90}
@deffn {C 函式} const char *PyUnicode_AsUTF8AndSize (PyObject *unicode, Py_ssize_t *size)
` 為 @ref{76e,,穩定 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.

發生錯誤時，設定例外並將 `size' 設為 @code{-1}（如果不是 NULL），並回傳 @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.


在 3.3 版被加入.



在 3.7 版的變更: 回傳型別現在是 @code{const char *} 而不是 @code{char *}。



在 3.10 版的變更: This function is a part of the @ref{62f,,limited API}.

@end deffn

@geindex PyUnicode_AsUTF8 (C function)
@anchor{c-api/unicode c PyUnicode_AsUTF8}@anchor{422}
@deffn {C 函式} const char *PyUnicode_AsUTF8 (PyObject *unicode)

與 @ref{a90,,PyUnicode_AsUTF8AndSize()} 類似，但不儲存大小。

@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{a90,,PyUnicode_AsUTF8AndSize()}
instead.
@end quotation
@end cartouche


在 3.3 版被加入.



在 3.7 版的變更: 回傳型別現在是 @code{const char *} 而不是 @code{char *}。

@end deffn

@node UTF-32 編解碼器,UTF-16 編解碼器,UTF-8 編解碼器,內建編解碼器
@anchor{c-api/unicode utf-32-codecs}@anchor{515d}
@subsubsection UTF-32 編解碼器


這些是 UTF-32 編解碼器的 API：

@geindex PyUnicode_DecodeUTF32 (C function)
@anchor{c-api/unicode c PyUnicode_DecodeUTF32}@anchor{4f75}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_DecodeUTF32 (const char *str, Py_ssize_t size, const char *errors, int *byteorder)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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.

如果編解碼器引發例外則回傳 @code{NULL}。
@end deffn

@geindex PyUnicode_DecodeUTF32Stateful (C function)
@anchor{c-api/unicode c PyUnicode_DecodeUTF32Stateful}@anchor{4f76}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_DecodeUTF32Stateful (const char *str, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
If `consumed' is @code{NULL}, behave like @ref{4f75,,PyUnicode_DecodeUTF32()}. If
`consumed' is not @code{NULL}, @ref{4f76,,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{4f67}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_AsUTF32String (PyObject *unicode)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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 編解碼器,UTF-7 編解碼器,UTF-32 編解碼器,內建編解碼器
@anchor{c-api/unicode utf-16-codecs}@anchor{515e}
@subsubsection UTF-16 編解碼器


這些是 UTF-16 編解碼器的 API：

@geindex PyUnicode_DecodeUTF16 (C function)
@anchor{c-api/unicode c PyUnicode_DecodeUTF16}@anchor{4f73}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_DecodeUTF16 (const char *str, Py_ssize_t size, const char *errors, int *byteorder)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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.

如果編解碼器引發例外則回傳 @code{NULL}。
@end deffn

@geindex PyUnicode_DecodeUTF16Stateful (C function)
@anchor{c-api/unicode c PyUnicode_DecodeUTF16Stateful}@anchor{4f74}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_DecodeUTF16Stateful (const char *str, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
If `consumed' is @code{NULL}, behave like @ref{4f73,,PyUnicode_DecodeUTF16()}. If
`consumed' is not @code{NULL}, @ref{4f74,,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{4f66}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_AsUTF16String (PyObject *unicode)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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 編解碼器,Unicode-Escape Codecs,UTF-16 編解碼器,內建編解碼器
@anchor{c-api/unicode utf-7-codecs}@anchor{515f}
@subsubsection UTF-7 編解碼器


這些是 UTF-7 編解碼器的 API：

@geindex PyUnicode_DecodeUTF7 (C function)
@anchor{c-api/unicode c PyUnicode_DecodeUTF7}@anchor{4f77}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_DecodeUTF7 (const char *str, Py_ssize_t size, const char *errors)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{4f78}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_DecodeUTF7Stateful (const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
If `consumed' is @code{NULL}, behave like @ref{4f77,,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 編解碼器,內建編解碼器
@anchor{c-api/unicode unicode-escape-codecs}@anchor{5160}
@subsubsection Unicode-Escape Codecs


These are the "Unicode Escape" codec APIs:

@geindex PyUnicode_DecodeUnicodeEscape (C function)
@anchor{c-api/unicode c PyUnicode_DecodeUnicodeEscape}@anchor{4f7a}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_DecodeUnicodeEscape (const char *str, Py_ssize_t size, const char *errors)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{1390}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_AsUnicodeEscapeString (PyObject *unicode)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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 編解碼器,Unicode-Escape Codecs,內建編解碼器
@anchor{c-api/unicode raw-unicode-escape-codecs}@anchor{5161}
@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{4f72}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_DecodeRawUnicodeEscape (const char *str, Py_ssize_t size, const char *errors)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{1391}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_AsRawUnicodeEscapeString (PyObject *unicode)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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 編解碼器,ASCII 編解碼器,Raw-Unicode-Escape Codecs,內建編解碼器
@anchor{c-api/unicode latin-1-codecs}@anchor{5162}
@subsubsection Latin-1 編解碼器


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{4f6e}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_DecodeLatin1 (const char *str, Py_ssize_t size, const char *errors)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{1392}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_AsLatin1String (PyObject *unicode)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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 編解碼器,Character Map Codecs,Latin-1 編解碼器,內建編解碼器
@anchor{c-api/unicode ascii-codecs}@anchor{5163}
@subsubsection ASCII 編解碼器


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{4f6a}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_DecodeASCII (const char *str, Py_ssize_t size, const char *errors)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{1393}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_AsASCIIString (PyObject *unicode)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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,Windows 的 MBCS 編解碼器,ASCII 編解碼器,內建編解碼器
@anchor{c-api/unicode character-map-codecs}@anchor{5164}
@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{582,,__getitem__()} mapping interface; dictionaries and sequences work well.

這些是對映編解碼器的 API：

@geindex PyUnicode_DecodeCharmap (C function)
@anchor{c-api/unicode c PyUnicode_DecodeCharmap}@anchor{4f6b}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_DecodeCharmap (const char *str, Py_ssize_t length, PyObject *mapping, const char *errors)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{2500,,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{4f64}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_AsCharmapString (PyObject *unicode, PyObject *mapping)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{2500,,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{4f88}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_Translate (PyObject *unicode, PyObject *table, const char *errors)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{582,,__getitem__()} interface; dictionaries
and sequences work well.  Unmapped character ordinals (ones which cause a
@ref{2500,,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 Windows 的 MBCS 編解碼器,,Character Map Codecs,內建編解碼器
@anchor{c-api/unicode mbcs-codecs-for-windows}@anchor{5165}
@subsubsection Windows 的 MBCS 編解碼器


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{4f70}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_DecodeMBCS (const char *str, Py_ssize_t size, const char *errors)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{4f71}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_DecodeMBCSStateful (const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分} on Windows 自 3.7 版本開始.'
If `consumed' is @code{NULL}, behave like @ref{4f70,,PyUnicode_DecodeMBCS()}. If
`consumed' is not @code{NULL}, @ref{4f71,,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{4f6c}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_DecodeCodePageStateful (int code_page, const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分} on Windows 自 3.7 版本開始.'
Similar to @ref{4f71,,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{1394}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_AsMBCSString (PyObject *unicode)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{1395}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_EncodeCodePage (int code_page, PyObject *unicode, const char *errors)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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.


在 3.3 版被加入.

@end deffn

@node Methods and Slot Functions,PyUnicodeWriter,內建編解碼器,Unicode 物件與編解碼器
@anchor{c-api/unicode methods-and-slot-functions}@anchor{5166}@anchor{c-api/unicode unicodemethodsandslots}@anchor{5167}
@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.

如果發生例外，則回傳 @code{NULL} 或 @code{-1}。

@geindex PyUnicode_Concat (C function)
@anchor{c-api/unicode c PyUnicode_Concat}@anchor{13a2}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_Concat (PyObject *left, PyObject *right)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Concat two strings giving a new Unicode string.
@end deffn

@geindex PyUnicode_Split (C function)
@anchor{c-api/unicode c PyUnicode_Split}@anchor{4f86}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_Split (PyObject *unicode, PyObject *sep, Py_ssize_t maxsplit)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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.

於錯誤發生時回傳 @code{NULL} 並設定例外。

等價於 @ref{10a5,,str.split()}。
@end deffn

@geindex PyUnicode_RSplit (C function)
@anchor{c-api/unicode c PyUnicode_RSplit}@anchor{1810}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_RSplit (PyObject *unicode, PyObject *sep, Py_ssize_t maxsplit)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Similar to @ref{4f86,,PyUnicode_Split()}, but splitting will be done beginning
at the end of the string.

於錯誤發生時回傳 @code{NULL} 並設定例外。

等價於 @ref{1456,,str.rsplit()}。
@end deffn

@geindex PyUnicode_Splitlines (C function)
@anchor{c-api/unicode c PyUnicode_Splitlines}@anchor{4f87}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_Splitlines (PyObject *unicode, int keepends)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{1811}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_Partition (PyObject *unicode, PyObject *sep)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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' 不得為空。

於錯誤發生時回傳 @code{NULL} 並設定例外。

等價於 @ref{10a6,,str.partition()}。
@end deffn

@geindex PyUnicode_RPartition (C function)
@anchor{c-api/unicode c PyUnicode_RPartition}@anchor{1812}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_RPartition (PyObject *unicode, PyObject *sep)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Similar to @ref{1811,,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' 不得為空。

於錯誤發生時回傳 @code{NULL} 並設定例外。

等價於 @ref{1459,,str.rpartition()}。
@end deffn

@geindex PyUnicode_Join (C function)
@anchor{c-api/unicode c PyUnicode_Join}@anchor{13a3}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_Join (PyObject *separator, PyObject *seq)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{aac}
@deffn {C 函式} @ref{c4c,,Py_ssize_t} PyUnicode_Tailmatch (PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)
` 為 @ref{76e,,穩定 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{4f7b}
@deffn {C 函式} @ref{c4c,,Py_ssize_t} PyUnicode_Find (PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)
` 為 @ref{76e,,穩定 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{aad}
@deffn {C 函式} @ref{c4c,,Py_ssize_t} PyUnicode_FindChar (PyObject *unicode, Py_UCS4 ch, Py_ssize_t start, Py_ssize_t end, int direction)
` 為 @ref{76e,,穩定 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.


在 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{4f69}
@deffn {C 函式} @ref{c4c,,Py_ssize_t} PyUnicode_Count (PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end)
` 為 @ref{76e,,穩定 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{4f83}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_Replace (PyObject *unicode, PyObject *substr, PyObject *replstr, Py_ssize_t maxcount)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{aab}
@deffn {C 函式} int PyUnicode_Compare (PyObject *left, PyObject *right)
` 為 @ref{76e,,穩定 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{1ba7,,PyErr_Occurred()} to check for errors.


@subsubheading 也參考


@ref{3b0,,PyUnicode_Equal()} 函式。

@end deffn

@geindex PyUnicode_Equal (C function)
@anchor{c-api/unicode c PyUnicode_Equal}@anchor{3b0}
@deffn {C 函式} int PyUnicode_Equal (PyObject *a, PyObject *b)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.14 版本開始.'
測試兩個字串是否相等：


@itemize *

@item 
如果 `a' 等於 `b'，則回傳 @code{1}。

@item 
如果 `a' 不等於 `b'，則回傳 @code{0}。

@item 
Set a @ref{198,,TypeError} exception and return @code{-1} if `a' or `b' is not a
@ref{169,,str} object.
@end itemize

The function always succeeds if `a' and `b' are @ref{169,,str} objects.

The function works for @ref{169,,str} subclasses, but does not honor custom
@code{__eq__()} method.


@subsubheading 也參考


@ref{aab,,PyUnicode_Compare()} 函式。



在 3.14 版被加入.

@end deffn

@geindex PyUnicode_EqualToUTF8AndSize (C function)
@anchor{c-api/unicode c PyUnicode_EqualToUTF8AndSize}@anchor{611}
@deffn {C 函式} int PyUnicode_EqualToUTF8AndSize (PyObject *unicode, const char *string, Py_ssize_t size)
` 為 @ref{76e,,穩定 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.

此函式不會引發例外。


在 3.13 版被加入.

@end deffn

@geindex PyUnicode_EqualToUTF8 (C function)
@anchor{c-api/unicode c PyUnicode_EqualToUTF8}@anchor{612}
@deffn {C 函式} int PyUnicode_EqualToUTF8 (PyObject *unicode, const char *string)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.13 版本開始.'
Similar to @ref{611,,PyUnicode_EqualToUTF8AndSize()}, but compute `string'
length using @code{strlen()}.
If the Unicode object contains null characters, false (@code{0}) is returned.


在 3.13 版被加入.

@end deffn

@geindex PyUnicode_CompareWithASCIIString (C function)
@anchor{c-api/unicode c PyUnicode_CompareWithASCIIString}@anchor{1468}
@deffn {C 函式} int PyUnicode_CompareWithASCIIString (PyObject *unicode, const char *string)
` 為 @ref{76e,,穩定 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.

此函式不會引發例外。
@end deffn

@geindex PyUnicode_RichCompare (C function)
@anchor{c-api/unicode c PyUnicode_RichCompare}@anchor{4f85}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_RichCompare (PyObject *left, PyObject *right, int op)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Rich compare two Unicode strings and return one of the following:


@itemize *

@item 
@code{NULL} in case an exception was raised

@item 
@ref{5105,,Py_True} or @ref{5104,,Py_False} for successful comparisons

@item 
@ref{5067,,Py_NotImplemented} in case the type combination is unknown
@end itemize

Possible values for `op' are @ref{506e,,Py_GT}, @ref{506f,,Py_GE}, @ref{506c,,Py_EQ},
@ref{506d,,Py_NE}, @ref{506a,,Py_LT}, and @ref{506b,,Py_LE}.
@end deffn

@geindex PyUnicode_Format (C function)
@anchor{c-api/unicode c PyUnicode_Format}@anchor{4f7c}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_Format (PyObject *format, PyObject *args)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{4f68}
@deffn {C 函式} int PyUnicode_Contains (PyObject *unicode, PyObject *substr)
` 為 @ref{76e,,穩定 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{aa5}
@deffn {C 函式} void PyUnicode_InternInPlace (PyObject **p_unicode)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Intern the argument *@ref{aa5,,p_unicode} in place.  The argument must be the address of a
pointer variable pointing to a Python Unicode string object.  If there is an
existing interned string that is the same as *@ref{aa5,,p_unicode}, it sets *@ref{aa5,,p_unicode} to
it (releasing the reference to the old string object and creating a new
@ref{5da,,strong reference} to the interned string object), otherwise it leaves
*@ref{aa5,,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{169,,str} may not be interned, that is,
@ref{513d,,PyUnicode_CheckExact}(*@ref{aa5,,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{18e6}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicode_InternFromString (const char *str)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
A combination of @ref{4f80,,PyUnicode_FromString()} and
@ref{aa5,,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{290,,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{4f80,,PyUnicode_FromString()} and
@ref{aa5,,PyUnicode_InternInPlace()} directly.
@end deffn

@geindex PyUnicode_CHECK_INTERNED (C function)
@anchor{c-api/unicode c PyUnicode_CHECK_INTERNED}@anchor{5168}
@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,已棄用的 API,Methods and Slot Functions,Unicode 物件與編解碼器
@anchor{c-api/unicode pyunicodewriter}@anchor{5169}
@subsubsection PyUnicodeWriter


The @ref{3b1,,PyUnicodeWriter} API can be used to create a Python @ref{169,,str}
object.


在 3.14 版被加入.


@geindex PyUnicodeWriter (C type)
@anchor{c-api/unicode c PyUnicodeWriter}@anchor{3b1}
@deffn {C 型別} type PyUnicodeWriter

一個 Unicode 寫入器實例。

The instance must be destroyed by @ref{3b5,,PyUnicodeWriter_Finish()} on
success, or @ref{3b4,,PyUnicodeWriter_Discard()} on error.
@end deffn

@geindex PyUnicodeWriter_Create (C function)
@anchor{c-api/unicode c PyUnicodeWriter_Create}@anchor{3b2}
@deffn {C 函式} @ref{3b1,,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.

發生錯誤時，設定例外並回傳 @code{NULL}。
@end deffn

@geindex PyUnicodeWriter_Finish (C function)
@anchor{c-api/unicode c PyUnicodeWriter_Finish}@anchor{3b5}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnicodeWriter_Finish (PyUnicodeWriter *writer)

Return the final Python @ref{169,,str} object and destroy the writer instance.

發生錯誤時，設定例外並回傳 @code{NULL}。

The writer instance is invalid after this call.
@end deffn

@geindex PyUnicodeWriter_Discard (C function)
@anchor{c-api/unicode c PyUnicodeWriter_Discard}@anchor{3b4}
@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{3b8}
@deffn {C 函式} int PyUnicodeWriter_WriteChar (PyUnicodeWriter *writer, Py_UCS4 ch)

Write the single Unicode character `ch' into `writer'.

成功時回傳 @code{0}，發生錯誤時設定例外、保持寫入器不變，並回傳 @code{-1}。
@end deffn

@geindex PyUnicodeWriter_WriteUTF8 (C function)
@anchor{c-api/unicode c PyUnicodeWriter_WriteUTF8}@anchor{3bd}
@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.

成功時回傳 @code{0}，發生錯誤時設定例外、保持寫入器不變，並回傳 @code{-1}。

另請參閱 @ref{3b3,,PyUnicodeWriter_DecodeUTF8Stateful()}。
@end deffn

@geindex PyUnicodeWriter_WriteASCII (C function)
@anchor{c-api/unicode c PyUnicodeWriter_WriteASCII}@anchor{3b7}
@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.

成功時回傳 @code{0}，發生錯誤時設定例外、保持寫入器不變，並回傳 @code{-1}。


在 3.14 版被加入.

@end deffn

@geindex PyUnicodeWriter_WriteWideChar (C function)
@anchor{c-api/unicode c PyUnicodeWriter_WriteWideChar}@anchor{3be}
@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.

成功時回傳 @code{0}，發生錯誤時設定例外、保持寫入器不變，並回傳 @code{-1}。
@end deffn

@geindex PyUnicodeWriter_WriteUCS4 (C function)
@anchor{c-api/unicode c PyUnicodeWriter_WriteUCS4}@anchor{3bc}
@deffn {C 函式} int PyUnicodeWriter_WriteUCS4 (PyUnicodeWriter *writer, Py_UCS4 *str, Py_ssize_t size)

Writer the UCS4 string `str' into `writer'.

`size' is a number of UCS4 characters.

成功時回傳 @code{0}，發生錯誤時設定例外、保持寫入器不變，並回傳 @code{-1}。
@end deffn

@geindex PyUnicodeWriter_WriteStr (C function)
@anchor{c-api/unicode c PyUnicodeWriter_WriteStr}@anchor{3ba}
@deffn {C 函式} int PyUnicodeWriter_WriteStr (PyUnicodeWriter *writer, PyObject *obj)

Call @ref{122b,,PyObject_Str()} on `obj' and write the output into `writer'.

成功時回傳 @code{0}，發生錯誤時設定例外、保持寫入器不變，並回傳 @code{-1}。
@end deffn

@geindex PyUnicodeWriter_WriteRepr (C function)
@anchor{c-api/unicode c PyUnicodeWriter_WriteRepr}@anchor{3b9}
@deffn {C 函式} int PyUnicodeWriter_WriteRepr (PyUnicodeWriter *writer, PyObject *obj)

Call @ref{122a,,PyObject_Repr()} on `obj' and write the output into `writer'.

成功時回傳 @code{0}，發生錯誤時設定例外、保持寫入器不變，並回傳 @code{-1}。
@end deffn

@geindex PyUnicodeWriter_WriteSubstring (C function)
@anchor{c-api/unicode c PyUnicodeWriter_WriteSubstring}@anchor{3bb}
@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{169,,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.

成功時回傳 @code{0}，發生錯誤時設定例外、保持寫入器不變，並回傳 @code{-1}。
@end deffn

@geindex PyUnicodeWriter_Format (C function)
@anchor{c-api/unicode c PyUnicodeWriter_Format}@anchor{3b6}
@deffn {C 函式} int PyUnicodeWriter_Format (PyUnicodeWriter *writer, const char *format, ...)

類似於 @ref{623,,PyUnicode_FromFormat()}，但是直接將輸出寫入 `writer'。

成功時回傳 @code{0}，發生錯誤時設定例外、保持寫入器不變，並回傳 @code{-1}。
@end deffn

@geindex PyUnicodeWriter_DecodeUTF8Stateful (C function)
@anchor{c-api/unicode c PyUnicodeWriter_DecodeUTF8Stateful}@anchor{3b3}
@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{1a9e,,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.

成功時回傳 @code{0}，發生錯誤時設定例外、保持寫入器不變，並回傳 @code{-1}。

另請參閱 @ref{3bd,,PyUnicodeWriter_WriteUTF8()}。
@end deffn

@node 已棄用的 API,,PyUnicodeWriter,Unicode 物件與編解碼器
@anchor{c-api/unicode deprecated-api}@anchor{516a}
@subsubsection 已棄用的 API


以下 API 已棄用。

@geindex Py_UNICODE (C type)
@anchor{c-api/unicode c Py_UNICODE}@anchor{3de}
@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.



Deprecated since version 3.13, will be removed in version 3.15.

@end deffn

@geindex PyUnicode_READY (C function)
@anchor{c-api/unicode c PyUnicode_READY}@anchor{432}
@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.


在 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{516b}
@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.


在 3.3 版被加入.



在 3.14 版之後被棄用: This API does nothing since Python 3.12.
Previously, this could be called to check if
@ref{432,,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（元組）物件,Struct Sequence Objects,Unicode 物件與編解碼器,序列物件
@anchor{c-api/tuple doc}@anchor{516c}@anchor{c-api/tuple translation-repo}@anchor{516d}@anchor{c-api/tuple tuple-objects}@anchor{516e}@anchor{c-api/tuple tupleobjects}@anchor{516f}
@subsubsection Tuple（元組）物件


@geindex object（物件）;tuple（元組）

@geindex PyTupleObject (C type)
@anchor{c-api/tuple c PyTupleObject}@anchor{5014}
@deffn {C 型別} type PyTupleObject

This subtype of @ref{5d7,,PyObject} represents a Python tuple object.
@end deffn

@geindex PyTuple_Type (C var)
@anchor{c-api/tuple c PyTuple_Type}@anchor{4f47}
@deffn {C 變數} @ref{c93,,PyTypeObject} PyTuple_Type
` 為 @ref{76e,,穩定 ABI 的一部分}.'
This instance of @ref{c93,,PyTypeObject} represents the Python tuple type; it
is the same object as @ref{60c,,tuple} in the Python layer.
@end deffn

@geindex PyTuple_Check (C function)
@anchor{c-api/tuple c PyTuple_Check}@anchor{5170}
@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{5171}
@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{636}
@deffn {C 函式} @ref{5d7,,PyObject} *PyTuple_New (Py_ssize_t len)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return a new tuple object of size `len',
or @code{NULL} with an exception set on failure.
@end deffn

@geindex PyTuple_Pack (C function)
@anchor{c-api/tuple c PyTuple_Pack}@anchor{4f45}
@deffn {C 函式} @ref{5d7,,PyObject} *PyTuple_Pack (Py_ssize_t n, ...)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return a new tuple object of size `n',
or @code{NULL} with an exception set on failure. The tuple values
are initialized to the subsequent `n' C arguments pointing to Python objects.
@code{PyTuple_Pack(2, a, b)} is equivalent to @code{Py_BuildValue("(OO)", a, b)}.
@end deffn

@geindex PyTuple_Size (C function)
@anchor{c-api/tuple c PyTuple_Size}@anchor{4f46}
@deffn {C 函式} @ref{c4c,,Py_ssize_t} PyTuple_Size (PyObject *p)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Take a pointer to a tuple object, and return the size of that tuple.
On error, return @code{-1} and with an exception set.
@end deffn

@geindex PyTuple_GET_SIZE (C function)
@anchor{c-api/tuple c PyTuple_GET_SIZE}@anchor{5172}
@deffn {C 函式} @ref{c4c,,Py_ssize_t} PyTuple_GET_SIZE (PyObject *p)

Like @ref{4f46,,PyTuple_Size()}, but without error checking.
@end deffn

@geindex PyTuple_GetItem (C function)
@anchor{c-api/tuple c PyTuple_GetItem}@anchor{4d7f}
@deffn {C 函式} @ref{5d7,,PyObject} *PyTuple_GetItem (PyObject *p, Py_ssize_t pos)
`回傳值：借用參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return the object at position `pos' in the tuple pointed to by `p'.  If `pos' is
negative or out of bounds, return @code{NULL} and set an @ref{1729,,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{5da,,strong reference}, use
@ref{a91,,Py_NewRef(PyTuple_GetItem(...))}
or @ref{1cfb,,PySequence_GetItem()}.
@end deffn

@geindex PyTuple_GET_ITEM (C function)
@anchor{c-api/tuple c PyTuple_GET_ITEM}@anchor{5173}
@deffn {C 函式} @ref{5d7,,PyObject} *PyTuple_GET_ITEM (PyObject *p, Py_ssize_t pos)
`回傳值：借用參照。'
Like @ref{4d7f,,PyTuple_GetItem()}, but does no checking of its arguments.
@end deffn

@geindex PyTuple_GetSlice (C function)
@anchor{c-api/tuple c PyTuple_GetSlice}@anchor{4f44}
@deffn {C 函式} @ref{5d7,,PyObject} *PyTuple_GetSlice (PyObject *p, Py_ssize_t low, Py_ssize_t high)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return the slice of the tuple pointed to by `p' between `low' and `high',
or @code{NULL} with an exception set on failure.

This is the equivalent of the Python expression @code{p[low:high]}.
Indexing from the end of the tuple is not supported.
@end deffn

@geindex PyTuple_SetItem (C function)
@anchor{c-api/tuple c PyTuple_SetItem}@anchor{4d80}
@deffn {C 函式} int PyTuple_SetItem (PyObject *p, Py_ssize_t pos, PyObject *o)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Insert a reference to object `o' at position `pos' of the tuple pointed to by
`p'.  Return @code{0} on success.  If `pos' is out of bounds, return @code{-1}
and set an @ref{1729,,IndexError} exception.

@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{626}
@deffn {C 函式} void PyTuple_SET_ITEM (PyObject *p, Py_ssize_t pos, PyObject *o)

Like @ref{4d80,,PyTuple_SetItem()}, but does no error checking, and should `only' be
used to fill in brand new tuples.

Bounds checking is performed as an assertion if Python is built in
@ref{504,,debug mode} or @ref{625,,with assertions}.

@cartouche
@quotation 備註 
This function "steals" a reference to `o', and, unlike
@ref{4d80,,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{16ff}
@deffn {C 函式} int _PyTuple_Resize (PyObject **p, Py_ssize_t newsize)

Can be used to resize a tuple.  `newsize' will be the new length of the tuple.
Because tuples are `supposed' to be immutable, this should only be used if there
is only one reference to the object.  Do `not' use this if the tuple may already
be known to some other part of the code.  The tuple will always grow or shrink
at the end.  Think of this as destroying the old tuple and creating a new one,
only more efficiently.  Returns @code{0} on success. Client code should never
assume that the resulting value of @code{*p} will be the same as before calling
this function. If the object referenced by @code{*p} is replaced, the original
@code{*p} is destroyed.  On failure, returns @code{-1} and sets @code{*p} to @code{NULL}, and
raises @ref{181e,,MemoryError} or @ref{78e,,SystemError}.
@end deffn

@node Struct Sequence Objects,List（串列）物件,Tuple（元組）物件,序列物件
@anchor{c-api/tuple id1}@anchor{5174}@anchor{c-api/tuple struct-sequence-objects}@anchor{13c0}
@subsubsection Struct Sequence Objects


Struct sequence objects are the C equivalent of @ref{4db,,namedtuple()}
objects, i.e. a sequence whose items can also be accessed through attributes.
To create a struct sequence, you first have to create a specific struct sequence
type.

@geindex PyStructSequence_NewType (C function)
@anchor{c-api/tuple c PyStructSequence_NewType}@anchor{4f37}
@deffn {C 函式} @ref{c93,,PyTypeObject} *PyStructSequence_NewType (PyStructSequence_Desc *desc)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Create a new struct sequence type from the data in `desc', described below. Instances
of the resulting type can be created with @ref{4f36,,PyStructSequence_New()}.

失敗時回傳 @code{NULL} 並設定例外。
@end deffn

@geindex PyStructSequence_InitType (C function)
@anchor{c-api/tuple c PyStructSequence_InitType}@anchor{11fe}
@deffn {C 函式} void PyStructSequence_InitType (PyTypeObject *type, PyStructSequence_Desc *desc)

Initializes a struct sequence type `type' from `desc' in place.
@end deffn

@geindex PyStructSequence_InitType2 (C function)
@anchor{c-api/tuple c PyStructSequence_InitType2}@anchor{11fd}
@deffn {C 函式} int PyStructSequence_InitType2 (PyTypeObject *type, PyStructSequence_Desc *desc)

Like @ref{11fe,,PyStructSequence_InitType()}, but returns @code{0} on success
and @code{-1} with an exception set on failure.


在 3.4 版被加入.

@end deffn

@geindex PyStructSequence_Desc (C type)
@anchor{c-api/tuple c PyStructSequence_Desc}@anchor{daf}
@deffn {C 型別} type PyStructSequence_Desc
` 為 @ref{76e,,穩定 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{5175}
@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{5176}
@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{5177}
@deffn {C 成員函數} @ref{dae,,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{5178}
@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{dae}
@deffn {C 型別} type PyStructSequence_Field
` 為 @ref{76e,,穩定 ABI 的一部分} （包含所有成員）.'
Describes a field of a struct sequence. As a struct sequence is modeled as a
tuple, all fields are typed as @ref{5d7,,PyObject}*.  The index in the
@ref{5177,,fields} array of
the @ref{daf,,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{5179}
@deffn {C 成員函數} const char *name

Name for the field or @code{NULL} to end the list of named fields,
set to @ref{b70,,PyStructSequence_UnnamedField} to leave unnamed.
@end deffn

@geindex PyStructSequence_Field.doc (C member)
@anchor{c-api/tuple c PyStructSequence_Field doc}@anchor{517a}
@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{b70}
@deffn {C 變數} const char *const PyStructSequence_UnnamedField
` 為 @ref{76e,,穩定 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{4f36}
@deffn {C 函式} @ref{5d7,,PyObject} *PyStructSequence_New (PyTypeObject *type)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Creates an instance of `type', which must have been created with
@ref{4f37,,PyStructSequence_NewType()}.

失敗時回傳 @code{NULL} 並設定例外。
@end deffn

@geindex PyStructSequence_GetItem (C function)
@anchor{c-api/tuple c PyStructSequence_GetItem}@anchor{4f35}
@deffn {C 函式} @ref{5d7,,PyObject} *PyStructSequence_GetItem (PyObject *p, Py_ssize_t pos)
`回傳值：借用參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return the object at position `pos' in the struct sequence pointed to by `p'.

Bounds checking is performed as an assertion if Python is built in
@ref{504,,debug mode} or @ref{625,,with assertions}.
@end deffn

@geindex PyStructSequence_GET_ITEM (C function)
@anchor{c-api/tuple c PyStructSequence_GET_ITEM}@anchor{517b}
@deffn {C 函式} @ref{5d7,,PyObject} *PyStructSequence_GET_ITEM (PyObject *p, Py_ssize_t pos)
`回傳值：借用參照。'
Alias to @ref{4f35,,PyStructSequence_GetItem()}.


在 3.13 版的變更: Now implemented as an alias to @ref{4f35,,PyStructSequence_GetItem()}.

@end deffn

@geindex PyStructSequence_SetItem (C function)
@anchor{c-api/tuple c PyStructSequence_SetItem}@anchor{4f38}
@deffn {C 函式} void PyStructSequence_SetItem (PyObject *p, Py_ssize_t pos, PyObject *o)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Sets the field at index `pos' of the struct sequence `p' to value `o'.  Like
@ref{626,,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{504,,debug mode} or @ref{625,,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{517c}
@deffn {C 函式} void PyStructSequence_SET_ITEM (PyObject *p, Py_ssize_t *pos, PyObject *o)

Alias to @ref{4f38,,PyStructSequence_SetItem()}.


在 3.13 版的變更: Now implemented as an alias to @ref{4f38,,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（串列）物件,,Struct Sequence Objects,序列物件
@anchor{c-api/list doc}@anchor{517d}@anchor{c-api/list list-objects}@anchor{517e}@anchor{c-api/list listobjects}@anchor{517f}@anchor{c-api/list translation-repo}@anchor{5180}
@subsubsection List（串列）物件


@geindex object（物件）;list（串列）

@geindex PyListObject (C type)
@anchor{c-api/list c PyListObject}@anchor{5089}
@deffn {C 型別} type PyListObject

@ref{5d7,,PyObject} 的這個子型別表示 Python 的 list（串列）物件。
@end deffn

@geindex PyList_Type (C var)
@anchor{c-api/list c PyList_Type}@anchor{4da3}
@deffn {C 變數} @ref{c93,,PyTypeObject} PyList_Type
` 為 @ref{76e,,穩定 ABI 的一部分}.'
此 @ref{c93,,PyTypeObject} 實例表示 Python 的 list 型別。這與 Python 層中的 @ref{24d,,list} 是同一個物件。
@end deffn

@geindex PyList_Check (C function)
@anchor{c-api/list c PyList_Check}@anchor{5181}
@deffn {C 函式} int PyList_Check (PyObject *p)

如果 `p' 是一個 list 物件或者是 list 型別之子型別的實例，就回傳 true。這個函式永遠會成功執行。
@end deffn

@geindex PyList_CheckExact (C function)
@anchor{c-api/list c PyList_CheckExact}@anchor{5182}
@deffn {C 函式} int PyList_CheckExact (PyObject *p)

如果 `p' 是一個 list 物件但不是 list 型別的子型別的實例，就回傳 true。這個函式永遠會成功執行。
@end deffn

@geindex PyList_New (C function)
@anchor{c-api/list c PyList_New}@anchor{4dfa}
@deffn {C 函式} @ref{5d7,,PyObject} *PyList_New (Py_ssize_t len)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
成功時回傳長度為 `len' 的新串列，失敗時回傳 @code{NULL}。

@cartouche
@quotation 備註 
如果 `len' 大於零，則回傳的串列物件之項目將被設定為 @code{NULL}。因此，在使用 @ref{1830,,PyList_SetItem()} 或 @ref{627,,PyList_SET_ITEM()} 來將所有項目設定為一個真實物件前，你無法使用像是 @ref{1cfc,,PySequence_SetItem()} 的抽象 API 函式，也不能將物件暴露 (expose) 給 Python 程式碼。以下 API 在串列完全初始化之前是安全的：@ref{1830,,PyList_SetItem()} 和 @ref{627,,PyList_SET_ITEM()}。
@end quotation
@end cartouche
@end deffn

@geindex PyList_Size (C function)
@anchor{c-api/list c PyList_Size}@anchor{1611}
@deffn {C 函式} @ref{c4c,,Py_ssize_t} PyList_Size (PyObject *list)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@geindex built-in function（內建函式）;len

回傳 `list' 串列物件的長度；這相當於串列物件的 @code{len(list)}。
@end deffn

@geindex PyList_GET_SIZE (C function)
@anchor{c-api/list c PyList_GET_SIZE}@anchor{5183}
@deffn {C 函式} @ref{c4c,,Py_ssize_t} PyList_GET_SIZE (PyObject *list)

與 @ref{1611,,PyList_Size()} 類似，但沒有錯誤檢查。
@end deffn

@geindex PyList_GetItemRef (C function)
@anchor{c-api/list c PyList_GetItemRef}@anchor{5f6}
@deffn {C 函式} @ref{5d7,,PyObject} *PyList_GetItemRef (PyObject *list, Py_ssize_t index)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.13 版本開始.'
回傳 `list' 指向的串列中位於 `index' 位置的物件。該位置不可為負數；並不支援從串列尾末開始索引。如果 `index' 超出邊界範圍 (@code{<0 or >=len(list)}) 則回傳 @code{NULL} 並設定 @ref{1729,,IndexError} 例外。


在 3.13 版被加入.

@end deffn

@geindex PyList_GetItem (C function)
@anchor{c-api/list c PyList_GetItem}@anchor{5f7}
@deffn {C 函式} @ref{5d7,,PyObject} *PyList_GetItem (PyObject *list, Py_ssize_t index)
`回傳值：借用參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Like @ref{5f6,,PyList_GetItemRef()}, but returns a
@ref{3d5,,borrowed reference} instead of a @ref{5da,,strong reference}.
@end deffn

@geindex PyList_GET_ITEM (C function)
@anchor{c-api/list c PyList_GET_ITEM}@anchor{4e10}
@deffn {C 函式} @ref{5d7,,PyObject} *PyList_GET_ITEM (PyObject *list, Py_ssize_t i)
`回傳值：借用參照。'
與 @ref{5f7,,PyList_GetItem()} 類似，但沒有錯誤檢查。
@end deffn

@geindex PyList_SetItem (C function)
@anchor{c-api/list c PyList_SetItem}@anchor{1830}
@deffn {C 函式} int PyList_SetItem (PyObject *list, Py_ssize_t index, PyObject *item)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
將串列中索引 `index' 處的項目設定為 `item'。成功時回傳 @code{0}。如果 `index' 超出邊界範圍則回傳 @code{-1} 並設定一個 @ref{1729,,IndexError} 例外。

@cartouche
@quotation 備註 
此函式「竊取」對 `item' 的參照，並丟棄對串列中受影響位置上已存在項目的參照。
@end quotation
@end cartouche
@end deffn

@geindex PyList_SET_ITEM (C function)
@anchor{c-api/list c PyList_SET_ITEM}@anchor{627}
@deffn {C 函式} void PyList_SET_ITEM (PyObject *list, Py_ssize_t i, PyObject *o)

@ref{1830,,PyList_SetItem()} 的巨集形式，沒有錯誤檢查。這通常僅用於填充沒有已存在內容的新串列。

Bounds checking is performed as an assertion if Python is built in
@ref{504,,debug mode} or @ref{625,,with assertions}.

@cartouche
@quotation 備註 
該巨集「竊取」對 `item' 的參照，並且與 @ref{1830,,PyList_SetItem()} 不同的是，它`不會'丟棄對任意被替換項目的參照；`list' 中位置 `i' 的任何參照都將被洩漏 (leak)。
@end quotation
@end cartouche
@end deffn

@geindex PyList_Insert (C function)
@anchor{c-api/list c PyList_Insert}@anchor{182f}
@deffn {C 函式} int PyList_Insert (PyObject *list, Py_ssize_t index, PyObject *item)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
將項目 `item' 插入串列 `list' 中索引 `index' 的位置之前。如果成功則回傳 @code{0}；如果失敗則回傳 @code{-1} 並設定例外。類似於 @code{list.insert(index, item)}。
@end deffn

@geindex PyList_Append (C function)
@anchor{c-api/list c PyList_Append}@anchor{4ec7}
@deffn {C 函式} int PyList_Append (PyObject *list, PyObject *item)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
將物件 `item' 附加到串列 `list' 的最後面。如果成功則回傳 @code{0}；如果不成功，則回傳 @code{-1} 並設定例外。類似於 @code{list.append(item)}。
@end deffn

@geindex PyList_GetSlice (C function)
@anchor{c-api/list c PyList_GetSlice}@anchor{4ec9}
@deffn {C 函式} @ref{5d7,,PyObject} *PyList_GetSlice (PyObject *list, Py_ssize_t low, Py_ssize_t high)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
回傳 `list' 中的物件串列，其中包含 `low' 和 `high' `之間'的物件。如果沒有成功則回傳 @code{NULL} 並設定例外。類似於 @code{list[low:high]}。不支援從串列尾末開始索引。
@end deffn

@geindex PyList_SetSlice (C function)
@anchor{c-api/list c PyList_SetSlice}@anchor{4ecb}
@deffn {C 函式} int PyList_SetSlice (PyObject *list, Py_ssize_t low, Py_ssize_t high, PyObject *itemlist)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
將 `low' 和 `high' 之間的 `list' 切片設定為 `itemlist' 的內容。類似於 @code{list[low:high] = itemlist}。`itemlist' 可能為 @code{NULL}，表示分配一個空串列（切片刪除）。成功時回傳 @code{0}，失敗時則回傳 @code{-1}。不支援從串列尾末開始索引。
@end deffn

@geindex PyList_Extend (C function)
@anchor{c-api/list c PyList_Extend}@anchor{5f8}
@deffn {C 函式} int PyList_Extend (PyObject *list, PyObject *iterable)

Extend `list' with the contents of `iterable'.  This is the same as
@code{PyList_SetSlice(list, PY_SSIZE_T_MAX, PY_SSIZE_T_MAX, iterable)}
and analogous to @code{list.extend(iterable)} or @code{list += iterable}.

Raise an exception and return @code{-1} if `list' is not a @ref{24d,,list}
object. Return 0 on success.


在 3.13 版被加入.

@end deffn

@geindex PyList_Clear (C function)
@anchor{c-api/list c PyList_Clear}@anchor{5f9}
@deffn {C 函式} int PyList_Clear (PyObject *list)

Remove all items from `list'.  This is the same as
@code{PyList_SetSlice(list, 0, PY_SSIZE_T_MAX, NULL)} and analogous to
@code{list.clear()} or @code{del list[:]}.

Raise an exception and return @code{-1} if `list' is not a @ref{24d,,list}
object.  Return 0 on success.


在 3.13 版被加入.

@end deffn

@geindex PyList_Sort (C function)
@anchor{c-api/list c PyList_Sort}@anchor{4ecc}
@deffn {C 函式} int PyList_Sort (PyObject *list)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
對 `list' 的項目進行原地 (in place) 排序。成功時回傳 @code{0}，失敗時回傳 @code{-1}。這相當於 @code{list.sort()}。
@end deffn

@geindex PyList_Reverse (C function)
@anchor{c-api/list c PyList_Reverse}@anchor{4eca}
@deffn {C 函式} int PyList_Reverse (PyObject *list)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
原地反轉 `list' 的項目。成功時回傳 @code{0}，失敗時回傳 @code{-1}。這相當於 @code{list.reverse()}。
@end deffn

@geindex PyList_AsTuple (C function)
@anchor{c-api/list c PyList_AsTuple}@anchor{4ec8}
@deffn {C 函式} @ref{5d7,,PyObject} *PyList_AsTuple (PyObject *list)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
@geindex built-in function（內建函式）;tuple（元組）

回傳一個新的 tuple（元組）物件，其中包含 `list' 的內容；相當於 @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 容器物件,函式物件<2>,序列物件,具體物件層
@anchor{c-api/concrete container-objects}@anchor{5184}@anchor{c-api/concrete mapobjects}@anchor{5185}
@subsection 容器物件


@geindex object（物件）;mapping（對映）

@menu
* 字典物件:: 
* 集合物件:: 

@end menu

@node 字典物件,集合物件,,容器物件
@anchor{c-api/dict doc}@anchor{5186}@anchor{c-api/dict dictionary-objects}@anchor{5187}@anchor{c-api/dict dictobjects}@anchor{5188}
@subsubsection 字典物件


@geindex object（物件）;dictionary（字典）

@geindex PyDictObject (C type)
@anchor{c-api/dict c PyDictObject}@anchor{647}
@deffn {C 型別} type PyDictObject

@ref{5d7,,PyObject} 子型態代表一個 Python 字典物件。
@end deffn

@geindex PyDict_Type (C var)
@anchor{c-api/dict c PyDict_Type}@anchor{4e54}
@deffn {C 變數} @ref{c93,,PyTypeObject} PyDict_Type
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@ref{c93,,PyTypeObject} 實例代表一個 Python 字典型態。此與 Python 層中的 @ref{183,,dict} 為同一個物件。
@end deffn

@geindex PyDict_Check (C function)
@anchor{c-api/dict c PyDict_Check}@anchor{50c5}
@deffn {C 函式} int PyDict_Check (PyObject *p)

若 `p' 是一個字典物件或字典的子型態實例則會回傳 true。此函式每次都會執行成功。
@end deffn

@geindex PyDict_CheckExact (C function)
@anchor{c-api/dict c PyDict_CheckExact}@anchor{5189}
@deffn {C 函式} int PyDict_CheckExact (PyObject *p)

若 `p' 是一個字典物件但並不是一個字典子型態的實例，則回傳 true。此函式每次都會執行成功。
@end deffn

@geindex PyDict_New (C function)
@anchor{c-api/dict c PyDict_New}@anchor{4e52}
@deffn {C 函式} @ref{5d7,,PyObject} *PyDict_New ()
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
回傳一個新的空字典，或在失敗時回傳 @code{NULL}。
@end deffn

@geindex PyDictProxy_New (C function)
@anchor{c-api/dict c PyDictProxy_New}@anchor{4e4a}
@deffn {C 函式} @ref{5d7,,PyObject} *PyDictProxy_New (PyObject *mapping)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return a @ref{691,,types.MappingProxyType} object for a mapping which
enforces read-only behavior.  This is normally used to create a view to
prevent modification of the dictionary for non-dynamic class types.
@end deffn

@geindex PyDict_Clear (C function)
@anchor{c-api/dict c PyDict_Clear}@anchor{4e4b}
@deffn {C 函式} void PyDict_Clear (PyObject *p)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
清空現有字典中的所有鍵值對。
@end deffn

@geindex PyDict_Contains (C function)
@anchor{c-api/dict c PyDict_Contains}@anchor{5d6}
@deffn {C 函式} int PyDict_Contains (PyObject *p, PyObject *key)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Determine if dictionary `p' contains `key'.  If an item in `p' is matches
`key', return @code{1}, otherwise return @code{0}.  On error, return @code{-1}.
This is equivalent to the Python expression @code{key in p}.
@end deffn

@geindex PyDict_ContainsString (C function)
@anchor{c-api/dict c PyDict_ContainsString}@anchor{5d5}
@deffn {C 函式} int PyDict_ContainsString (PyObject *p, const char *key)

This is the same as @ref{5d6,,PyDict_Contains()}, but `key' is specified as a
const char* UTF-8 encoded bytes string, rather than a
@ref{5d7,,PyObject}*.


在 3.13 版被加入.

@end deffn

@geindex PyDict_Copy (C function)
@anchor{c-api/dict c PyDict_Copy}@anchor{65a}
@deffn {C 函式} @ref{5d7,,PyObject} *PyDict_Copy (PyObject *p)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return a new dictionary that contains the same key-value pairs as `p'.
@end deffn

@geindex PyDict_SetItem (C function)
@anchor{c-api/dict c PyDict_SetItem}@anchor{4d81}
@deffn {C 函式} int PyDict_SetItem (PyObject *p, PyObject *key, PyObject *val)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Insert `val' into the dictionary `p' with a key of `key'.  `key' must be
@ref{81d,,hashable}; if it isn't, @ref{198,,TypeError} will be raised. Return
@code{0} on success or @code{-1} on failure.  This function `does not' steal a
reference to `val'.
@end deffn

@geindex PyDict_SetItemString (C function)
@anchor{c-api/dict c PyDict_SetItemString}@anchor{18e7}
@deffn {C 函式} int PyDict_SetItemString (PyObject *p, const char *key, PyObject *val)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
This is the same as @ref{4d81,,PyDict_SetItem()}, but `key' is
specified as a const char* UTF-8 encoded bytes string,
rather than a @ref{5d7,,PyObject}*.
@end deffn

@geindex PyDict_DelItem (C function)
@anchor{c-api/dict c PyDict_DelItem}@anchor{4e4c}
@deffn {C 函式} int PyDict_DelItem (PyObject *p, PyObject *key)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Remove the entry in dictionary `p' with key `key'. `key' must be @ref{81d,,hashable};
if it isn't, @ref{198,,TypeError} is raised.
If `key' is not in the dictionary, @ref{5df,,KeyError} is raised.
Return @code{0} on success or @code{-1} on failure.
@end deffn

@geindex PyDict_DelItemString (C function)
@anchor{c-api/dict c PyDict_DelItemString}@anchor{4e4d}
@deffn {C 函式} int PyDict_DelItemString (PyObject *p, const char *key)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
This is the same as @ref{4e4c,,PyDict_DelItem()}, but `key' is
specified as a const char* UTF-8 encoded bytes string,
rather than a @ref{5d7,,PyObject}*.
@end deffn

@geindex PyDict_GetItemRef (C function)
@anchor{c-api/dict c PyDict_GetItemRef}@anchor{5d8}
@deffn {C 函式} int PyDict_GetItemRef (PyObject *p, PyObject *key, PyObject **result)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.13 版本開始.'
Return a new @ref{5da,,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{5da,,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 
錯誤發生時，引發一個例外並回傳 @code{-1}。
@end itemize


在 3.13 版被加入.


另見 @ref{5e2,,PyObject_GetItem()} 函式。
@end deffn

@geindex PyDict_GetItem (C function)
@anchor{c-api/dict c PyDict_GetItem}@anchor{620}
@deffn {C 函式} @ref{5d7,,PyObject} *PyDict_GetItem (PyObject *p, PyObject *key)
`回傳值：借用參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return a @ref{3d5,,borrowed reference} to the object from dictionary `p' which
has a key `key'.  Return @code{NULL} if the key `key' is missing `without'
setting an exception.

@cartouche
@quotation 備註 
Exceptions that occur while this calls @ref{cea,,__hash__()} and
@ref{ce9,,__eq__()} methods are silently ignored.
Prefer the @ref{5d9,,PyDict_GetItemWithError()} function instead.
@end quotation
@end cartouche


在 3.10 版的變更: Calling this API without an @ref{4d99,,attached thread state} had been allowed for historical
reason. It is no longer allowed.

@end deffn

@geindex PyDict_GetItemWithError (C function)
@anchor{c-api/dict c PyDict_GetItemWithError}@anchor{5d9}
@deffn {C 函式} @ref{5d7,,PyObject} *PyDict_GetItemWithError (PyObject *p, PyObject *key)
`回傳值：借用參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Variant of @ref{620,,PyDict_GetItem()} that does not suppress
exceptions. Return @code{NULL} `with' an exception set if an exception
occurred.  Return @code{NULL} `without' an exception set if the key
wasn't present.
@end deffn

@geindex PyDict_GetItemString (C function)
@anchor{c-api/dict c PyDict_GetItemString}@anchor{621}
@deffn {C 函式} @ref{5d7,,PyObject} *PyDict_GetItemString (PyObject *p, const char *key)
`回傳值：借用參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
This is the same as @ref{620,,PyDict_GetItem()}, but `key' is specified as a
const char* UTF-8 encoded bytes string, rather than a
@ref{5d7,,PyObject}*.

@cartouche
@quotation 備註 
Exceptions that occur while this calls @ref{cea,,__hash__()} and
@ref{ce9,,__eq__()} methods or while creating the temporary @ref{169,,str}
object are silently ignored.
Prefer using the @ref{5d9,,PyDict_GetItemWithError()} function with your own
@ref{4f80,,PyUnicode_FromString()} `key' instead.
@end quotation
@end cartouche
@end deffn

@geindex PyDict_GetItemStringRef (C function)
@anchor{c-api/dict c PyDict_GetItemStringRef}@anchor{41f}
@deffn {C 函式} int PyDict_GetItemStringRef (PyObject *p, const char *key, PyObject **result)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.13 版本開始.'
Similar to @ref{5d8,,PyDict_GetItemRef()}, but `key' is specified as a
const char* UTF-8 encoded bytes string, rather than a
@ref{5d7,,PyObject}*.


在 3.13 版被加入.

@end deffn

@geindex PyDict_SetDefault (C function)
@anchor{c-api/dict c PyDict_SetDefault}@anchor{5dc}
@deffn {C 函式} @ref{5d7,,PyObject} *PyDict_SetDefault (PyObject *p, PyObject *key, PyObject *defaultobj)
`回傳值：借用參照。'
This is the same as the Python-level @ref{1274,,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.


在 3.4 版被加入.

@end deffn

@geindex PyDict_SetDefaultRef (C function)
@anchor{c-api/dict c PyDict_SetDefaultRef}@anchor{5db}
@deffn {C 函式} int PyDict_SetDefaultRef (PyObject *p, PyObject *key, PyObject *default_value, PyObject **result)

Inserts `default_value' into the dictionary `p' with a key of `key' if the
key is not already present in the dictionary. If `result' is not @code{NULL},
then `*result' is set to a @ref{5da,,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.


在 3.13 版被加入.

@end deffn

@geindex PyDict_Pop (C function)
@anchor{c-api/dict c PyDict_Pop}@anchor{420}
@deffn {C 函式} int PyDict_Pop (PyObject *p, PyObject *key, PyObject **result)

Remove `key' from dictionary `p' and optionally return the removed value.
Do not raise @ref{5df,,KeyError} if the key missing.


@itemize -

@item 
If the key is present, set `*result' to a new reference to the removed
value if `result' is not @code{NULL}, and return @code{1}.

@item 
If the key is missing, set `*result' to @code{NULL} if `result' is not
@code{NULL}, and return @code{0}.

@item 
錯誤發生時，引發一個例外並回傳 @code{-1}。
@end itemize

Similar to @ref{5de,,dict.pop()}, but without the default value and
not raising @ref{5df,,KeyError} if the key missing.


在 3.13 版被加入.

@end deffn

@geindex PyDict_PopString (C function)
@anchor{c-api/dict c PyDict_PopString}@anchor{5dd}
@deffn {C 函式} int PyDict_PopString (PyObject *p, const char *key, PyObject **result)

Similar to @ref{420,,PyDict_Pop()}, but `key' is specified as a
const char* UTF-8 encoded bytes string, rather than a
@ref{5d7,,PyObject}*.


在 3.13 版被加入.

@end deffn

@geindex PyDict_Items (C function)
@anchor{c-api/dict c PyDict_Items}@anchor{4e4e}
@deffn {C 函式} @ref{5d7,,PyObject} *PyDict_Items (PyObject *p)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
回傳一個包含字典中所有項目的 @ref{5089,,PyListObject}。
@end deffn

@geindex PyDict_Keys (C function)
@anchor{c-api/dict c PyDict_Keys}@anchor{4e4f}
@deffn {C 函式} @ref{5d7,,PyObject} *PyDict_Keys (PyObject *p)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
回傳一個包含字典中所有鍵的 @ref{5089,,PyListObject}。
@end deffn

@geindex PyDict_Values (C function)
@anchor{c-api/dict c PyDict_Values}@anchor{4e56}
@deffn {C 函式} @ref{5d7,,PyObject} *PyDict_Values (PyObject *p)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
回傳一個包含字典 `p' 中所有值的 @ref{5089,,PyListObject}。
@end deffn

@geindex PyDict_Size (C function)
@anchor{c-api/dict c PyDict_Size}@anchor{4e53}
@deffn {C 函式} @ref{c4c,,Py_ssize_t} PyDict_Size (PyObject *p)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@geindex built-in function（內建函式）;len

回傳字典中項目的數量。此與於字典呼叫 @code{len(p)} 等效。
@end deffn

@geindex PyDict_Next (C function)
@anchor{c-api/dict c PyDict_Next}@anchor{18e9}
@deffn {C 函式} int PyDict_Next (PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Iterate over all key-value pairs in the dictionary `p'.  The
@ref{c4c,,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{5d7,,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.

舉例來說：

@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{1f4,,free-threaded}
build without external synchronization.  You can use
@ref{518a,,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

@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{3d5,,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{5da,,strong reference} (for example, using
@ref{a91,,Py_NewRef()}).
@end quotation
@end cartouche
@end deffn

@geindex PyDict_Merge (C function)
@anchor{c-api/dict c PyDict_Merge}@anchor{4e50}
@deffn {C 函式} int PyDict_Merge (PyObject *a, PyObject *b, int override)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Iterate over mapping object `b' adding key-value pairs to dictionary `a'.
`b' may be a dictionary, or any object supporting @ref{db0,,PyMapping_Keys()}
and @ref{5e2,,PyObject_GetItem()}. If `override' is true, existing pairs in `a'
will be replaced if a matching key is found in `b', otherwise pairs will
only be added if there is not a matching key in `a'. Return @code{0} on
success or @code{-1} if an exception was raised.
@end deffn

@geindex PyDict_Update (C function)
@anchor{c-api/dict c PyDict_Update}@anchor{4e55}
@deffn {C 函式} int PyDict_Update (PyObject *a, PyObject *b)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
This is the same as @code{PyDict_Merge(a, b, 1)} in C, and is similar to
@code{a.update(b)} in Python except that @ref{4e55,,PyDict_Update()} doesn't fall
back to the iterating over a sequence of key value pairs if the second
argument has no "keys" attribute.  Return @code{0} on success or @code{-1} if an
exception was raised.
@end deffn

@geindex PyDict_MergeFromSeq2 (C function)
@anchor{c-api/dict c PyDict_MergeFromSeq2}@anchor{4e51}
@deffn {C 函式} int PyDict_MergeFromSeq2 (PyObject *a, PyObject *seq2, int override)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Update or merge into dictionary `a', from the key-value pairs in `seq2'.
`seq2' must be an iterable object producing iterable objects of length 2,
viewed as key-value pairs.  In case of duplicate keys, the last wins if
`override' is true, else the first wins. Return @code{0} on success or @code{-1}
if an exception was raised. Equivalent Python (except for the return
value):

@example
def PyDict_MergeFromSeq2(a, seq2, override):
    for key, value in seq2:
        if override or key not in a:
            a[key] = value
@end example
@end deffn

@geindex PyDict_AddWatcher (C function)
@anchor{c-api/dict c PyDict_AddWatcher}@anchor{3ce}
@deffn {C 函式} int PyDict_AddWatcher (PyDict_WatchCallback callback)

Register `callback' as a dictionary watcher. Return a non-negative integer
id which must be passed to future calls to @ref{77d,,PyDict_Watch()}. In case
of error (e.g. no more watcher IDs available), return @code{-1} and set an
exception.


在 3.12 版被加入.

@end deffn

@geindex PyDict_ClearWatcher (C function)
@anchor{c-api/dict c PyDict_ClearWatcher}@anchor{518b}
@deffn {C 函式} int PyDict_ClearWatcher (int watcher_id)

Clear watcher identified by `watcher_id' previously returned from
@ref{3ce,,PyDict_AddWatcher()}. Return @code{0} on success, @code{-1} on error (e.g.
if the given `watcher_id' was never registered.)


在 3.12 版被加入.

@end deffn

@geindex PyDict_Watch (C function)
@anchor{c-api/dict c PyDict_Watch}@anchor{77d}
@deffn {C 函式} int PyDict_Watch (int watcher_id, PyObject *dict)

Mark dictionary `dict' as watched. The callback granted `watcher_id' by
@ref{3ce,,PyDict_AddWatcher()} will be called when `dict' is modified or
deallocated. Return @code{0} on success or @code{-1} on error.


在 3.12 版被加入.

@end deffn

@geindex PyDict_Unwatch (C function)
@anchor{c-api/dict c PyDict_Unwatch}@anchor{518c}
@deffn {C 函式} int PyDict_Unwatch (int watcher_id, PyObject *dict)

Mark dictionary `dict' as no longer watched. The callback granted
`watcher_id' by @ref{3ce,,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.


在 3.12 版被加入.

@end deffn

@geindex PyDict_WatchEvent (C type)
@anchor{c-api/dict c PyDict_WatchEvent}@anchor{518d}
@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}.


在 3.12 版被加入.

@end deffn

@geindex PyDict_WatchCallback (C type)
@anchor{c-api/dict c PyDict_WatchCallback}@anchor{518e}
@deffn {C 型別} typedef int (*PyDict_WatchCallback)(@ref{518d,,PyDict_WatchEvent} event, @ref{5d7,,PyObject} *dict, @ref{5d7,,PyObject} *key, @ref{5d7,,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{5ea,,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.


在 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 集合物件,,字典物件,容器物件
@anchor{c-api/set doc}@anchor{518f}@anchor{c-api/set set-objects}@anchor{5190}@anchor{c-api/set setobjects}@anchor{5191}@anchor{c-api/set translation-repo}@anchor{5192}
@subsubsection 集合物件


@geindex object（物件）;set（集合）
@geindex object（物件）;frozenset（凍結集合）

This section details the public API for @ref{184,,set} and @ref{7eb,,frozenset}
objects.  Any functionality not listed below is best accessed using either
the abstract object protocol (including @ref{638,,PyObject_CallMethod()},
@ref{1c55,,PyObject_RichCompareBool()}, @ref{434,,PyObject_Hash()},
@ref{122a,,PyObject_Repr()}, @ref{4f15,,PyObject_IsTrue()}, @ref{18e5,,PyObject_Print()}, and
@ref{4f14,,PyObject_GetIter()}) or the abstract number protocol (including
@ref{4ee8,,PyNumber_And()}, @ref{4f01,,PyNumber_Subtract()}, @ref{4efc,,PyNumber_Or()},
@ref{4f03,,PyNumber_Xor()}, @ref{4eed,,PyNumber_InPlaceAnd()},
@ref{4ef5,,PyNumber_InPlaceSubtract()}, @ref{4ef1,,PyNumber_InPlaceOr()}, and
@ref{4ef7,,PyNumber_InPlaceXor()}).

@geindex PySetObject (C type)
@anchor{c-api/set c PySetObject}@anchor{5193}
@deffn {C 型別} type PySetObject

This subtype of @ref{5d7,,PyObject} is used to hold the internal data for both
@ref{184,,set} and @ref{7eb,,frozenset} objects.  It is like a @ref{647,,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{4f2e}
@deffn {C 變數} @ref{c93,,PyTypeObject} PySet_Type
` 為 @ref{76e,,穩定 ABI 的一部分}.'
This is an instance of @ref{c93,,PyTypeObject} representing the Python
@ref{184,,set} type.
@end deffn

@geindex PyFrozenSet_Type (C var)
@anchor{c-api/set c PyFrozenSet_Type}@anchor{4eb7}
@deffn {C 變數} @ref{c93,,PyTypeObject} PyFrozenSet_Type
` 為 @ref{76e,,穩定 ABI 的一部分}.'
This is an instance of @ref{c93,,PyTypeObject} representing the Python
@ref{7eb,,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{5194}
@deffn {C 函式} int PySet_Check (PyObject *p)

Return true if `p' is a @ref{184,,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{5195}
@deffn {C 函式} int PyFrozenSet_Check (PyObject *p)

Return true if `p' is a @ref{7eb,,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{5196}
@deffn {C 函式} int PyAnySet_Check (PyObject *p)

Return true if `p' is a @ref{184,,set} object, a @ref{7eb,,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{a94}
@deffn {C 函式} int PySet_CheckExact (PyObject *p)

Return true if `p' is a @ref{184,,set} object but not an instance of a
subtype.  This function always succeeds.


在 3.10 版被加入.

@end deffn

@geindex PyAnySet_CheckExact (C function)
@anchor{c-api/set c PyAnySet_CheckExact}@anchor{5197}
@deffn {C 函式} int PyAnySet_CheckExact (PyObject *p)

Return true if `p' is a @ref{184,,set} object or a @ref{7eb,,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{5198}
@deffn {C 函式} int PyFrozenSet_CheckExact (PyObject *p)

Return true if `p' is a @ref{7eb,,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{163b}
@deffn {C 函式} @ref{5d7,,PyObject} *PySet_New (PyObject *iterable)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return a new @ref{184,,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{198,,TypeError} if `iterable' is not
actually iterable.  The constructor is also useful for copying a set
(@code{c=set(s)}).
@end deffn

@geindex PyFrozenSet_New (C function)
@anchor{c-api/set c PyFrozenSet_New}@anchor{163c}
@deffn {C 函式} @ref{5d7,,PyObject} *PyFrozenSet_New (PyObject *iterable)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return a new @ref{7eb,,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{198,,TypeError} if `iterable' is
not actually iterable.
@end deffn

The following functions and macros are available for instances of @ref{184,,set}
or @ref{7eb,,frozenset} or instances of their subtypes.

@geindex PySet_Size (C function)
@anchor{c-api/set c PySet_Size}@anchor{1640}
@deffn {C 函式} @ref{c4c,,Py_ssize_t} PySet_Size (PyObject *anyset)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@geindex built-in function（內建函式）;len

Return the length of a @ref{184,,set} or @ref{7eb,,frozenset} object. Equivalent to
@code{len(anyset)}.  Raises a @ref{78e,,SystemError} if `anyset' is not a
@ref{184,,set}, @ref{7eb,,frozenset}, or an instance of a subtype.
@end deffn

@geindex PySet_GET_SIZE (C function)
@anchor{c-api/set c PySet_GET_SIZE}@anchor{5199}
@deffn {C 函式} @ref{c4c,,Py_ssize_t} PySet_GET_SIZE (PyObject *anyset)

Macro form of @ref{1640,,PySet_Size()} without error checking.
@end deffn

@geindex PySet_Contains (C function)
@anchor{c-api/set c PySet_Contains}@anchor{163f}
@deffn {C 函式} int PySet_Contains (PyObject *anyset, PyObject *key)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return @code{1} if found, @code{0} if not found, and @code{-1} if an error is encountered.  Unlike
the Python @ref{15b1,,__contains__()} method, this function does not automatically
convert unhashable sets into temporary frozensets.  Raise a @ref{198,,TypeError} if
the `key' is unhashable. Raise @ref{78e,,SystemError} if `anyset' is not a
@ref{184,,set}, @ref{7eb,,frozenset}, or an instance of a subtype.
@end deffn

@geindex PySet_Add (C function)
@anchor{c-api/set c PySet_Add}@anchor{163d}
@deffn {C 函式} int PySet_Add (PyObject *set, PyObject *key)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Add `key' to a @ref{184,,set} instance.  Also works with @ref{7eb,,frozenset}
instances (like @ref{4d80,,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{198,,TypeError} if the `key' is
unhashable. Raise a @ref{181e,,MemoryError} if there is no room to grow.  Raise a
@ref{78e,,SystemError} if `set' is not an instance of @ref{184,,set} or its
subtype.
@end deffn

The following functions are available for instances of @ref{184,,set} or its
subtypes but not for instances of @ref{7eb,,frozenset} or its subtypes.

@geindex PySet_Discard (C function)
@anchor{c-api/set c PySet_Discard}@anchor{163e}
@deffn {C 函式} int PySet_Discard (PyObject *set, PyObject *key)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return @code{1} if found and removed, @code{0} if not found (no action taken), and @code{-1} if an
error is encountered.  Does not raise @ref{5df,,KeyError} for missing keys.  Raise a
@ref{198,,TypeError} if the `key' is unhashable.  Unlike the Python @ref{254a,,discard()}
method, this function does not automatically convert unhashable sets into
temporary frozensets. Raise @ref{78e,,SystemError} if `set' is not an
instance of @ref{184,,set} or its subtype.
@end deffn

@geindex PySet_Pop (C function)
@anchor{c-api/set c PySet_Pop}@anchor{4f2d}
@deffn {C 函式} @ref{5d7,,PyObject} *PySet_Pop (PyObject *set)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return a new reference to an arbitrary object in the `set', and removes the
object from the `set'.  Return @code{NULL} on failure.  Raise @ref{5df,,KeyError} if the
set is empty. Raise a @ref{78e,,SystemError} if `set' is not an instance of
@ref{184,,set} or its subtype.
@end deffn

@geindex PySet_Clear (C function)
@anchor{c-api/set c PySet_Clear}@anchor{4f2c}
@deffn {C 函式} int PySet_Clear (PyObject *set)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Empty an existing set of all elements. Return @code{0} on
success. Return @code{-1} and raise @ref{78e,,SystemError} if `set' is not an instance of
@ref{184,,set} or its subtype.
@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 函式物件<2>,其他物件<2>,容器物件,具體物件層
@anchor{c-api/concrete function-objects}@anchor{519a}@anchor{c-api/concrete otherobjects}@anchor{519b}
@subsection 函式物件


@menu
* 函式物件 (Function Objects): 函式物件 Function Objects. 
* 實例方法物件 (Instance Method Objects): 實例方法物件 Instance Method Objects. 
* 方法物件 (Method Objects): 方法物件 Method Objects. 
* Cell 物件:: 
* 程式碼物件: 程式碼物件<3>. 
* 程式碼物件旗標:: 
* 額外資訊:: 

@end menu

@node 函式物件 Function Objects,實例方法物件 Instance Method Objects,,函式物件<2>
@anchor{c-api/function doc}@anchor{519c}@anchor{c-api/function function-objects}@anchor{519d}@anchor{c-api/function id1}@anchor{519e}
@subsubsection 函式物件 (Function Objects)


@geindex object（物件）;function（函式）

這有一些特用於 Python 函式的函式。

@geindex PyFunctionObject (C type)
@anchor{c-api/function c PyFunctionObject}@anchor{77c}
@deffn {C 型別} type PyFunctionObject

用於函式的 C 結構。
@end deffn

@geindex PyFunction_Type (C var)
@anchor{c-api/function c PyFunction_Type}@anchor{519f}
@deffn {C 變數} @ref{c93,,PyTypeObject} PyFunction_Type

@geindex MethodType（types 模組中）

這是個 @ref{c93,,PyTypeObject} 的實例，且代表了 Python 函式型別，Python 程式設計者可透過 @code{types.FunctionType} 使用它。
@end deffn

@geindex PyFunction_Check (C function)
@anchor{c-api/function c PyFunction_Check}@anchor{51a0}
@deffn {C 函式} int PyFunction_Check (PyObject *o)

如果 `o' 是個函式物件（擁有 @ref{519f,,PyFunction_Type} 的型別）則回傳 true。參數必須不為 @code{NULL}。此函式必能成功執行。
@end deffn

@geindex PyFunction_New (C function)
@anchor{c-api/function c PyFunction_New}@anchor{51a1}
@deffn {C 函式} @ref{5d7,,PyObject} *PyFunction_New (PyObject *code, PyObject *globals)
`回傳值：新的參照。'
回傳一個與程式碼物件 `code' 相關聯的函式物件。`globals' 必須是一個帶有函式能夠存取的全域變數的字典。

函式的文件字串 (docstring) 和名稱是從程式碼物件所取得，@ref{21fc,,__module__} 是自 `globals' 所取得。引數預設值、標註 (annotation) 和閉包 (closure) 被設為 @code{NULL}，@ref{21fb,,__qualname__} 被設為和程式碼物件 @ref{2237,,co_qualname} 欄位相同的值。
@end deffn

@geindex PyFunction_NewWithQualName (C function)
@anchor{c-api/function c PyFunction_NewWithQualName}@anchor{51a2}
@deffn {C 函式} @ref{5d7,,PyObject} *PyFunction_NewWithQualName (PyObject *code, PyObject *globals, PyObject *qualname)
`回傳值：新的參照。'
和 @ref{51a1,,PyFunction_New()} 相似，但也允許函式物件 @ref{21fb,,__qualname__} 屬性的設定，`qualname' 應為一個 unicode 物件或是 @code{NULL}；如為 @code{NULL}，@code{__qualname__} 屬性會被設為與程式碼物件 @ref{2237,,co_qualname} 欄位相同的值。


在 3.3 版被加入.

@end deffn

@geindex PyFunction_GetCode (C function)
@anchor{c-api/function c PyFunction_GetCode}@anchor{51a3}
@deffn {C 函式} @ref{5d7,,PyObject} *PyFunction_GetCode (PyObject *op)
`回傳值：借用參照。'
回傳與程式碼物件相關的函式物件 `op'。
@end deffn

@geindex PyFunction_GetGlobals (C function)
@anchor{c-api/function c PyFunction_GetGlobals}@anchor{51a4}
@deffn {C 函式} @ref{5d7,,PyObject} *PyFunction_GetGlobals (PyObject *op)
`回傳值：借用參照。'
回傳與全域函式字典相關的函式物件 `op'。
@end deffn

@geindex PyFunction_GetModule (C function)
@anchor{c-api/function c PyFunction_GetModule}@anchor{51a5}
@deffn {C 函式} @ref{5d7,,PyObject} *PyFunction_GetModule (PyObject *op)
`回傳值：借用參照。'
回傳一個@ref{596,,函式物件} `op' 之 @ref{21fc,,__module__} 屬性的 @ref{3d5,,borrowed reference}，它可以是 `NULL'。

這通常是個包含模組名稱的@ref{169,,字串}，但可以被 Python 程式設為任何其他物件。
@end deffn

@geindex PyFunction_GetDefaults (C function)
@anchor{c-api/function c PyFunction_GetDefaults}@anchor{51a6}
@deffn {C 函式} @ref{5d7,,PyObject} *PyFunction_GetDefaults (PyObject *op)
`回傳值：借用參照。'
回傳函式物件 `op' 的引數預設值，這可以是一個含有多個引數的 tuple（元組）或 @code{NULL}。
@end deffn

@geindex PyFunction_SetDefaults (C function)
@anchor{c-api/function c PyFunction_SetDefaults}@anchor{51a7}
@deffn {C 函式} int PyFunction_SetDefaults (PyObject *op, PyObject *defaults)

設定函式物件 `op' 的引數預設值。`defaults' 必須是 @code{Py_None} 或一個 tuple。

引發 @ref{78e,,SystemError} 且在失敗時回傳 @code{-1}。
@end deffn

@geindex PyFunction_SetVectorcall (C function)
@anchor{c-api/function c PyFunction_SetVectorcall}@anchor{77b}
@deffn {C 函式} void PyFunction_SetVectorcall (PyFunctionObject *func, vectorcallfunc vectorcall)

為一個給定的函式物件 `func' 設定 vectorcall 欄位。

警告：使用此 API 的擴充套件必須保留未更改（預設）vectorcall 函式的行為！


在 3.12 版被加入.

@end deffn

@geindex PyFunction_GetKwDefaults (C function)
@anchor{c-api/function c PyFunction_GetKwDefaults}@anchor{51a8}
@deffn {C 函式} @ref{5d7,,PyObject} *PyFunction_GetKwDefaults (PyObject *op)
`回傳值：借用參照。'
回傳函式物件 `op' 的僅限關鍵字引數預設值，這可以是一個含有多個引數的字典或 @code{NULL}。
@end deffn

@geindex PyFunction_GetClosure (C function)
@anchor{c-api/function c PyFunction_GetClosure}@anchor{51a9}
@deffn {C 函式} @ref{5d7,,PyObject} *PyFunction_GetClosure (PyObject *op)
`回傳值：借用參照。'
回傳與函式物件 `op' 相關聯的閉包，這可以是個 @code{NULL} 或是一個包含 cell 物件的 tuple。
@end deffn

@geindex PyFunction_SetClosure (C function)
@anchor{c-api/function c PyFunction_SetClosure}@anchor{51aa}
@deffn {C 函式} int PyFunction_SetClosure (PyObject *op, PyObject *closure)

設定與函式物件 `op' 相關聯的閉包，`closure' 必須是 @code{Py_None} 或是一個包含 cell 物件的 tuple。

引發 @ref{78e,,SystemError} 且在失敗時回傳 @code{-1}。
@end deffn

@geindex PyFunction_GetAnnotations (C function)
@anchor{c-api/function c PyFunction_GetAnnotations}@anchor{1a76}
@deffn {C 函式} @ref{5d7,,PyObject} *PyFunction_GetAnnotations (PyObject *op)
`回傳值：借用參照。'
回傳函式物件 `op' 的標註，這可以是一個可變動的 (mutable) 字典或 @code{NULL}。
@end deffn

@geindex PyFunction_SetAnnotations (C function)
@anchor{c-api/function c PyFunction_SetAnnotations}@anchor{51ab}
@deffn {C 函式} int PyFunction_SetAnnotations (PyObject *op, PyObject *annotations)

設定函式物件 `op' 的標註，`annotations' 必須是一個字典或 @code{Py_None}。

引發 @ref{78e,,SystemError} 且在失敗時回傳 @code{-1}。
@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{51ac}
@deffn {C 函式} @ref{5d7,,PyObject} *PyFunction_GET_CODE (PyObject *op)
@anchor{c-api/function c PyFunction_GET_GLOBALS}@anchor{51ad}
@deffnx {C 函式} @ref{5d7,,PyObject} *PyFunction_GET_GLOBALS (PyObject *op)
@anchor{c-api/function c PyFunction_GET_MODULE}@anchor{51ae}
@deffnx {C 函式} @ref{5d7,,PyObject} *PyFunction_GET_MODULE (PyObject *op)
@anchor{c-api/function c PyFunction_GET_DEFAULTS}@anchor{51af}
@deffnx {C 函式} @ref{5d7,,PyObject} *PyFunction_GET_DEFAULTS (PyObject *op)
@anchor{c-api/function c PyFunction_GET_KW_DEFAULTS}@anchor{51b0}
@deffnx {C 函式} @ref{5d7,,PyObject} *PyFunction_GET_KW_DEFAULTS (PyObject *op)
@anchor{c-api/function c PyFunction_GET_CLOSURE}@anchor{51b1}
@deffnx {C 函式} @ref{5d7,,PyObject} *PyFunction_GET_CLOSURE (PyObject *op)
@anchor{c-api/function c PyFunction_GET_ANNOTATIONS}@anchor{51b2}
@deffnx {C 函式} @ref{5d7,,PyObject} *PyFunction_GET_ANNOTATIONS (PyObject *op)
`回傳值：借用參照。'
These functions are similar to their @code{PyFunction_Get*} counterparts, but
do not do type checking. Passing anything other than an instance of
@ref{519f,,PyFunction_Type} is undefined behavior.
@end deffn

@geindex PyFunction_AddWatcher (C function)
@anchor{c-api/function c PyFunction_AddWatcher}@anchor{51b3}
@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{51b4,,PyFunction_ClearWatcher()}.
In case of error (e.g. no more watcher IDs available),
return @code{-1} and set an exception.


在 3.12 版被加入.

@end deffn

@geindex PyFunction_ClearWatcher (C function)
@anchor{c-api/function c PyFunction_ClearWatcher}@anchor{51b4}
@deffn {C 函式} int PyFunction_ClearWatcher (int watcher_id)

Clear watcher identified by `watcher_id' previously returned from
@ref{51b3,,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.)


在 3.12 版被加入.

@end deffn

@geindex PyFunction_WatchEvent (C type)
@anchor{c-api/function c PyFunction_WatchEvent}@anchor{51b5}
@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


在 3.12 版被加入.

@end deffn

@geindex PyFunction_WatchCallback (C type)
@anchor{c-api/function c PyFunction_WatchCallback}@anchor{51b6}
@deffn {C 型別} typedef int (*PyFunction_WatchCallback)(@ref{51b5,,PyFunction_WatchEvent} event, @ref{77c,,PyFunctionObject} *func, @ref{5d7,,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{3d5,,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{5ea,,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.


在 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,函式物件<2>
@anchor{c-api/method doc}@anchor{51b7}@anchor{c-api/method instance-method-objects}@anchor{51b8}@anchor{c-api/method instancemethod-objects}@anchor{51b9}@anchor{c-api/method translation-repo}@anchor{51ba}
@subsubsection 實例方法物件 (Instance Method Objects)


@geindex object（物件）;instancemethod

實例方法是 @ref{166c,,PyCFunction} 的包裝器 (wrapper)，也是將 @ref{166c,,PyCFunction} 繫結 (bind) 到類別物件的一種新方式。它替代了原先對 @code{PyMethod_New(func, NULL, class)} 的呼叫。

@geindex PyInstanceMethod_Type (C var)
@anchor{c-api/method c PyInstanceMethod_Type}@anchor{51bb}
@deffn {C 變數} @ref{c93,,PyTypeObject} PyInstanceMethod_Type

@ref{c93,,PyTypeObject} 的實例代表 Python 實例方法型別。它不會公開 (expose) 給 Python 程式。
@end deffn

@geindex PyInstanceMethod_Check (C function)
@anchor{c-api/method c PyInstanceMethod_Check}@anchor{51bc}
@deffn {C 函式} int PyInstanceMethod_Check (PyObject *o)

如果 `o' 是一個實例方法物件（型別為 @ref{51bb,,PyInstanceMethod_Type}）則回傳 true。參數必須不為 @code{NULL}。此函式總是會成功執行。
@end deffn

@geindex PyInstanceMethod_New (C function)
@anchor{c-api/method c PyInstanceMethod_New}@anchor{51bd}
@deffn {C 函式} @ref{5d7,,PyObject} *PyInstanceMethod_New (PyObject *func)
`回傳值：新的參照。'
回傳一個新的實例方法物件，`func' 為任意可呼叫物件，在實例方法被呼叫時 `func' 函式也會被呼叫。
@end deffn

@geindex PyInstanceMethod_Function (C function)
@anchor{c-api/method c PyInstanceMethod_Function}@anchor{51be}
@deffn {C 函式} @ref{5d7,,PyObject} *PyInstanceMethod_Function (PyObject *im)
`回傳值：借用參照。'
回傳關聯到實例方法 `im' 的函式物件。
@end deffn

@geindex PyInstanceMethod_GET_FUNCTION (C function)
@anchor{c-api/method c PyInstanceMethod_GET_FUNCTION}@anchor{51bf}
@deffn {C 函式} @ref{5d7,,PyObject} *PyInstanceMethod_GET_FUNCTION (PyObject *im)
`回傳值：借用參照。'
巨集 (macro) 版本的 @ref{51be,,PyInstanceMethod_Function()}，忽略了錯誤檢查。
@end deffn

@node 方法物件 Method Objects,Cell 物件,實例方法物件 Instance Method Objects,函式物件<2>
@anchor{c-api/method id1}@anchor{51c0}@anchor{c-api/method method-objects}@anchor{51c1}
@subsubsection 方法物件 (Method Objects)


@geindex object（物件）;method（方法）

方法為繫結函式 (bound function) 物件。方法總是會被繫結到一個使用者定義類別的實例。未繫結方法（繫結到一個類別的方法）已不可用。

@geindex PyMethod_Type (C var)
@anchor{c-api/method c PyMethod_Type}@anchor{51c2}
@deffn {C 變數} @ref{c93,,PyTypeObject} PyMethod_Type

@geindex MethodType（types 模組中）

這個 @ref{c93,,PyTypeObject} 實例代表 Python 方法型別。它作為 @code{types.MethodType} 公開給 Python 程式。
@end deffn

@geindex PyMethod_Check (C function)
@anchor{c-api/method c PyMethod_Check}@anchor{51c3}
@deffn {C 函式} int PyMethod_Check (PyObject *o)

如果 `o' 是一個方法物件（型別為 @ref{51c2,,PyMethod_Type}）則回傳 true。參數必須不為 @code{NULL}。此函式總是會成功執行。
@end deffn

@geindex PyMethod_New (C function)
@anchor{c-api/method c PyMethod_New}@anchor{51c4}
@deffn {C 函式} @ref{5d7,,PyObject} *PyMethod_New (PyObject *func, PyObject *self)
`回傳值：新的參照。'
回傳一個新的方法物件，`func' 應為任意可呼叫物件，`self' 為該方法應繫結的實例。在方法被呼叫時，`func' 函式也會被呼叫。`self' 必須不為 @code{NULL}。
@end deffn

@geindex PyMethod_Function (C function)
@anchor{c-api/method c PyMethod_Function}@anchor{51c5}
@deffn {C 函式} @ref{5d7,,PyObject} *PyMethod_Function (PyObject *meth)
`回傳值：借用參照。'
回傳關聯到方法 `meth' 的函式物件。
@end deffn

@geindex PyMethod_GET_FUNCTION (C function)
@anchor{c-api/method c PyMethod_GET_FUNCTION}@anchor{51c6}
@deffn {C 函式} @ref{5d7,,PyObject} *PyMethod_GET_FUNCTION (PyObject *meth)
`回傳值：借用參照。'
巨集版本的 @ref{51c5,,PyMethod_Function()}，忽略了錯誤檢查。
@end deffn

@geindex PyMethod_Self (C function)
@anchor{c-api/method c PyMethod_Self}@anchor{51c7}
@deffn {C 函式} @ref{5d7,,PyObject} *PyMethod_Self (PyObject *meth)
`回傳值：借用參照。'
回傳關聯到方法 `meth' 的實例。
@end deffn

@geindex PyMethod_GET_SELF (C function)
@anchor{c-api/method c PyMethod_GET_SELF}@anchor{51c8}
@deffn {C 函式} @ref{5d7,,PyObject} *PyMethod_GET_SELF (PyObject *meth)
`回傳值：借用參照。'
巨集版本的 @ref{51c7,,PyMethod_Self()}，忽略了錯誤檢查。
@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 物件,程式碼物件<3>,方法物件 Method Objects,函式物件<2>
@anchor{c-api/cell doc}@anchor{51c9}@anchor{c-api/cell cell-objects}@anchor{908}@anchor{c-api/cell id1}@anchor{51ca}@anchor{c-api/cell translation-repo}@anchor{51cb}
@subsubsection Cell 物件


"Cell" 物件用於實現被多個作用域所參照 (reference) 的變數。對於每個這樣的變數，都會有個 cell 物件為了儲存該值而被建立；參照該值的每個 stack frame 中的區域性變數包含外部作用域的 cell 參照，它同樣使用了該變數。存取該值時，將使用 cell 中包含的值而不是 cell 物件本身。這種對 cell 物件的去除參照 (de-reference) 需要生成的位元組碼 (byte-code) 有支援；存取時不會自動去除參照。cell 物件在其他地方可能不太有用。

@geindex PyCellObject (C type)
@anchor{c-api/cell c PyCellObject}@anchor{51cc}
@deffn {C 型別} type PyCellObject

Cell 物件所用之 C 結構。
@end deffn

@geindex PyCell_Type (C var)
@anchor{c-api/cell c PyCell_Type}@anchor{51cd}
@deffn {C 變數} @ref{c93,,PyTypeObject} PyCell_Type

對應 cell 物件的物件型別。
@end deffn

@geindex PyCell_Check (C function)
@anchor{c-api/cell c PyCell_Check}@anchor{51ce}
@deffn {C 函式} int PyCell_Check (PyObject *ob)

如果 `ob' 是一個 cell 物件則回傳真值；`ob' 必須不為 @code{NULL}。此函式總是會成功執行。
@end deffn

@geindex PyCell_New (C function)
@anchor{c-api/cell c PyCell_New}@anchor{51cf}
@deffn {C 函式} @ref{5d7,,PyObject} *PyCell_New (PyObject *ob)
`回傳值：新的參照。'
建立並回傳一個包含 `ob' 的新 cell 物件。參數可以為 @code{NULL}。
@end deffn

@geindex PyCell_Get (C function)
@anchor{c-api/cell c PyCell_Get}@anchor{51d0}
@deffn {C 函式} @ref{5d7,,PyObject} *PyCell_Get (PyObject *cell)
`回傳值：新的參照。'
回傳 cell 物件 `cell' 的內容，其可能為 @code{NULL}。如果 `cell' 不是一個 cell 物件，則將回傳 @code{NULL} 並設定例外。
@end deffn

@geindex PyCell_GET (C function)
@anchor{c-api/cell c PyCell_GET}@anchor{51d1}
@deffn {C 函式} @ref{5d7,,PyObject} *PyCell_GET (PyObject *cell)
`回傳值：借用參照。'
回傳 cell 物件 `cell' 的內容，但是不檢查 `cell' 是否非 @code{NULL} 並且為一個 cell 物件。
@end deffn

@geindex PyCell_Set (C function)
@anchor{c-api/cell c PyCell_Set}@anchor{51d2}
@deffn {C 函式} int PyCell_Set (PyObject *cell, PyObject *value)

將 cell 物件 `cell' 的內容設為 `value'。這將釋放任何對 cell 物件目前內容的參照。`value' 可以為 @code{NULL}。`cell' 必須不為 @code{NULL}。

在成功時回傳 @code{0}。如果 `cell' 不是一個 cell 物件，則將設定例外並回傳 @code{-1}。
@end deffn

@geindex PyCell_SET (C function)
@anchor{c-api/cell c PyCell_SET}@anchor{aa2}
@deffn {C 函式} void PyCell_SET (PyObject *cell, PyObject *value)

將 cell 物件 `cell' 的值設為 `value'。不會調整參照計數，並且不會進行任何安全檢查；`cell' 必須為非 @code{NULL} 並且為一個 cell 物件。
@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 程式碼物件<3>,程式碼物件旗標,Cell 物件,函式物件<2>
@anchor{c-api/code doc}@anchor{51d3}@anchor{c-api/code code-objects}@anchor{51d4}@anchor{c-api/code codeobjects}@anchor{7cb}@anchor{c-api/code translation-repo}@anchor{51d5}
@subsubsection 程式碼物件


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{973}
@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{51d6}
@deffn {C 變數} @ref{c93,,PyTypeObject} PyCode_Type

This is an instance of @ref{c93,,PyTypeObject} representing the Python
@ref{4e1,,code object}.
@end deffn

@geindex PyCode_Check (C function)
@anchor{c-api/code c PyCode_Check}@anchor{51d7}
@deffn {C 函式} int PyCode_Check (PyObject *co)

Return true if `co' is a @ref{4e1,,code object}.
This function always succeeds.
@end deffn

@geindex PyCode_GetNumFree (C function)
@anchor{c-api/code c PyCode_GetNumFree}@anchor{51d8}
@deffn {C 函式} @ref{c4c,,Py_ssize_t} PyCode_GetNumFree (PyCodeObject *co)

Return the number of @ref{180c,,free (closure) variables}
in a code object.
@end deffn

@geindex PyUnstable_Code_GetFirstFree (C function)
@anchor{c-api/code c PyUnstable_Code_GetFirstFree}@anchor{61f}
@deffn {C 函式} int PyUnstable_Code_GetFirstFree (PyCodeObject *co)

@cartouche
@quotation 這是 不穩定 API，它可能在小版本發布中沒有任何警告地被變更。 `這是 @ref{762,,不穩定 API}，它可能在小版本發布中沒有任何警告地被變更。'
@end quotation
@end cartouche

Return the position of the first @ref{180c,,free (closure) variable}
in a code object.


在 3.13 版的變更: Renamed from @code{PyCode_GetFirstFree} as part of @ref{762,,不穩定的 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{51d9}
@deffn {C 函式} @ref{973,,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{762,,不穩定 API}，它可能在小版本發布中沒有任何警告地被變更。'
@end quotation
@end cartouche

Return a new code object.  If you need a dummy code object to create a frame,
use @ref{1551,,PyCode_NewEmpty()} instead.

Since the definition of the bytecode changes often, calling
@ref{51d9,,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 版的變更: 新增 @code{qualname} 和 @code{exceptiontable} 參數。


@geindex PyCode_New（C 函式）


在 3.12 版的變更: Renamed from @code{PyCode_New} as part of @ref{762,,不穩定的 C API}.
The old name is deprecated, but will remain available until the
signature changes again.

@end deffn

@geindex PyUnstable_Code_NewWithPosOnlyArgs (C function)
@anchor{c-api/code c PyUnstable_Code_NewWithPosOnlyArgs}@anchor{51da}
@deffn {C 函式} @ref{973,,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{762,,不穩定 API}，它可能在小版本發布中沒有任何警告地被變更。'
@end quotation
@end cartouche

Similar to @ref{51d9,,PyUnstable_Code_New()}, but with an extra "posonlyargcount" for positional-only arguments.
The same caveats that apply to @code{PyUnstable_Code_New} also apply to this function.

@geindex PyCode_NewWithPosOnlyArgs（C 函式）


在 3.8 版被加入: as @code{PyCode_NewWithPosOnlyArgs}



在 3.11 版的變更: 新增 @code{qualname} 和 @code{exceptiontable} 參數。



在 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{1551}
@deffn {C 函式} @ref{973,,PyCodeObject} *PyCode_NewEmpty (const char *filename, const char *funcname, int firstlineno)
`回傳值：新的參照。'
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{a80}
@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{986,,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{7ca}
@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.

如果函式成功則回傳 @code{1}，否則回傳 @code{0}。


在 3.11 版被加入.

@end deffn

@geindex PyCode_GetCode (C function)
@anchor{c-api/code c PyCode_GetCode}@anchor{974}
@deffn {C 函式} @ref{5d7,,PyObject} *PyCode_GetCode (PyCodeObject *co)

Equivalent to the Python code @code{getattr(co, 'co_code')}.
Returns a strong reference to a @ref{98d,,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.


在 3.11 版被加入.

@end deffn

@geindex PyCode_GetVarnames (C function)
@anchor{c-api/code c PyCode_GetVarnames}@anchor{975}
@deffn {C 函式} @ref{5d7,,PyObject} *PyCode_GetVarnames (PyCodeObject *co)

Equivalent to the Python code @code{getattr(co, 'co_varnames')}.
Returns a new reference to a @ref{5014,,PyTupleObject} containing the names of
the local variables. On error, @code{NULL} is returned and an exception
is raised.


在 3.11 版被加入.

@end deffn

@geindex PyCode_GetCellvars (C function)
@anchor{c-api/code c PyCode_GetCellvars}@anchor{976}
@deffn {C 函式} @ref{5d7,,PyObject} *PyCode_GetCellvars (PyCodeObject *co)

Equivalent to the Python code @code{getattr(co, 'co_cellvars')}.
Returns a new reference to a @ref{5014,,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.


在 3.11 版被加入.

@end deffn

@geindex PyCode_GetFreevars (C function)
@anchor{c-api/code c PyCode_GetFreevars}@anchor{977}
@deffn {C 函式} @ref{5d7,,PyObject} *PyCode_GetFreevars (PyCodeObject *co)

Equivalent to the Python code @code{getattr(co, 'co_freevars')}.
Returns a new reference to a @ref{5014,,PyTupleObject} containing the names of
the @ref{180c,,free (closure) variables}. On error, @code{NULL} is returned
and an exception is raised.


在 3.11 版被加入.

@end deffn

@geindex PyCode_AddWatcher (C function)
@anchor{c-api/code c PyCode_AddWatcher}@anchor{780}
@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{781,,PyCode_ClearWatcher()}.
In case of error (e.g. no more watcher IDs available),
return @code{-1} and set an exception.


在 3.12 版被加入.

@end deffn

@geindex PyCode_ClearWatcher (C function)
@anchor{c-api/code c PyCode_ClearWatcher}@anchor{781}
@deffn {C 函式} int PyCode_ClearWatcher (int watcher_id)

Clear watcher identified by `watcher_id' previously returned from
@ref{780,,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.)


在 3.12 版被加入.

@end deffn

@geindex PyCodeEvent (C type)
@anchor{c-api/code c PyCodeEvent}@anchor{51db}
@deffn {C 型別} type PyCodeEvent

Enumeration of possible code object watcher events:
- @code{PY_CODE_EVENT_CREATE}
- @code{PY_CODE_EVENT_DESTROY}


在 3.12 版被加入.

@end deffn

@geindex PyCode_WatchCallback (C type)
@anchor{c-api/code c PyCode_WatchCallback}@anchor{51dc}
@deffn {C 型別} typedef int (*PyCode_WatchCallback)(@ref{51db,,PyCodeEvent} event, @ref{973,,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{5ea,,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.


在 3.12 版被加入.

@end deffn

@node 程式碼物件旗標,額外資訊,程式碼物件<3>,函式物件<2>
@anchor{c-api/code c-codeobject-flags}@anchor{4fdb}@anchor{c-api/code code-object-flags}@anchor{51dd}
@subsubsection 程式碼物件旗標


Code objects contain a bit-field of flags, which can be retrieved as the
@ref{1848,,co_flags} Python attribute (for example using
@ref{5e7,,PyObject_GetAttrString()}), and set using a `flags' argument to
@ref{51d9,,PyUnstable_Code_New()} and similar functions.

Flags whose names start with @code{CO_FUTURE_} correspond to features normally
selectable by @ref{45b,,future statements}. These flags can be used in
@ref{4fd4,,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

旗標

@tab

意義

@item

@geindex CO_OPTIMIZED (C macro)
@anchor{c-api/code c CO_OPTIMIZED}@anchor{51de}
@deffn {C 巨集} CO_OPTIMIZED
@end deffn

@tab

@ref{490a,,inspect.CO_OPTIMIZED}

@item

@geindex CO_NEWLOCALS (C macro)
@anchor{c-api/code c CO_NEWLOCALS}@anchor{51df}
@deffn {C 巨集} CO_NEWLOCALS
@end deffn

@tab

@ref{490b,,inspect.CO_NEWLOCALS}

@item

@geindex CO_VARARGS (C macro)
@anchor{c-api/code c CO_VARARGS}@anchor{51e0}
@deffn {C 巨集} CO_VARARGS
@end deffn

@tab

@ref{490c,,inspect.CO_VARARGS}

@item

@geindex CO_VARKEYWORDS (C macro)
@anchor{c-api/code c CO_VARKEYWORDS}@anchor{51e1}
@deffn {C 巨集} CO_VARKEYWORDS
@end deffn

@tab

@ref{490d,,inspect.CO_VARKEYWORDS}

@item

@geindex CO_NESTED (C macro)
@anchor{c-api/code c CO_NESTED}@anchor{51e2}
@deffn {C 巨集} CO_NESTED
@end deffn

@tab

@ref{490e,,inspect.CO_NESTED}

@item

@geindex CO_GENERATOR (C macro)
@anchor{c-api/code c CO_GENERATOR}@anchor{51e3}
@deffn {C 巨集} CO_GENERATOR
@end deffn

@tab

@ref{490f,,inspect.CO_GENERATOR}

@item

@geindex CO_COROUTINE (C macro)
@anchor{c-api/code c CO_COROUTINE}@anchor{51e4}
@deffn {C 巨集} CO_COROUTINE
@end deffn

@tab

@ref{4910,,inspect.CO_COROUTINE}

@item

@geindex CO_ITERABLE_COROUTINE (C macro)
@anchor{c-api/code c CO_ITERABLE_COROUTINE}@anchor{51e5}
@deffn {C 巨集} CO_ITERABLE_COROUTINE
@end deffn

@tab

@ref{4911,,inspect.CO_ITERABLE_COROUTINE}

@item

@geindex CO_ASYNC_GENERATOR (C macro)
@anchor{c-api/code c CO_ASYNC_GENERATOR}@anchor{51e6}
@deffn {C 巨集} CO_ASYNC_GENERATOR
@end deffn

@tab

@ref{4912,,inspect.CO_ASYNC_GENERATOR}

@item

@geindex CO_HAS_DOCSTRING (C macro)
@anchor{c-api/code c CO_HAS_DOCSTRING}@anchor{51e7}
@deffn {C 巨集} CO_HAS_DOCSTRING
@end deffn

@tab

@ref{2245,,inspect.CO_HAS_DOCSTRING}

@item

@geindex CO_METHOD (C macro)
@anchor{c-api/code c CO_METHOD}@anchor{51e8}
@deffn {C 巨集} CO_METHOD
@end deffn

@tab

@ref{4913,,inspect.CO_METHOD}

@item

@geindex CO_FUTURE_DIVISION (C macro)
@anchor{c-api/code c CO_FUTURE_DIVISION}@anchor{51e9}
@deffn {C 巨集} CO_FUTURE_DIVISION
@end deffn

@tab

無效果（@ref{48b8,,__future__.division}）

@item

@geindex CO_FUTURE_ABSOLUTE_IMPORT (C macro)
@anchor{c-api/code c CO_FUTURE_ABSOLUTE_IMPORT}@anchor{51ea}
@deffn {C 巨集} CO_FUTURE_ABSOLUTE_IMPORT
@end deffn

@tab

無效果（@ref{48b9,,__future__.absolute_import}）

@item

@geindex CO_FUTURE_WITH_STATEMENT (C macro)
@anchor{c-api/code c CO_FUTURE_WITH_STATEMENT}@anchor{51eb}
@deffn {C 巨集} CO_FUTURE_WITH_STATEMENT
@end deffn

@tab

無效果（@ref{48ba,,__future__.with_statement}）

@item

@geindex CO_FUTURE_PRINT_FUNCTION (C macro)
@anchor{c-api/code c CO_FUTURE_PRINT_FUNCTION}@anchor{51ec}
@deffn {C 巨集} CO_FUTURE_PRINT_FUNCTION
@end deffn

@tab

無效果（@ref{48bb,,__future__.print_function}）

@item

@geindex CO_FUTURE_UNICODE_LITERALS (C macro)
@anchor{c-api/code c CO_FUTURE_UNICODE_LITERALS}@anchor{51ed}
@deffn {C 巨集} CO_FUTURE_UNICODE_LITERALS
@end deffn

@tab

無效果（@ref{48bc,,__future__.unicode_literals}）

@item

@geindex CO_FUTURE_GENERATOR_STOP (C macro)
@anchor{c-api/code c CO_FUTURE_GENERATOR_STOP}@anchor{51ee}
@deffn {C 巨集} CO_FUTURE_GENERATOR_STOP
@end deffn

@tab

無效果（@ref{48bd,,__future__.generator_stop}）

@item

@geindex CO_FUTURE_ANNOTATIONS (C macro)
@anchor{c-api/code c CO_FUTURE_ANNOTATIONS}@anchor{4fda}
@deffn {C 巨集} CO_FUTURE_ANNOTATIONS
@end deffn

@tab

@ref{48be,,__future__.annotations}

@end multitable


@node 額外資訊,,程式碼物件旗標,函式物件<2>
@anchor{c-api/code extra-information}@anchor{51ef}
@subsubsection 額外資訊


To support low-level extensions to frame evaluation, such as external
just-in-time compilers, it is possible to attach arbitrary extra data to
code objects.

These functions are part of the unstable C API tier:
this functionality is a CPython implementation detail, and the API
may change without deprecation warnings.

@geindex PyUnstable_Eval_RequestCodeExtraIndex (C function)
@anchor{c-api/code c PyUnstable_Eval_RequestCodeExtraIndex}@anchor{51f0}
@deffn {C 函式} @ref{c4c,,Py_ssize_t} PyUnstable_Eval_RequestCodeExtraIndex (freefunc free)

@cartouche
@quotation 這是 不穩定 API，它可能在小版本發布中沒有任何警告地被變更。 `這是 @ref{762,,不穩定 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{4f8f,,Py_DecRef()} when storing @ref{5d7,,PyObject}.

@geindex _PyEval_RequestCodeExtraIndex（C 函式）


在 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 PyUnstable_Code_GetExtra (C function)
@anchor{c-api/code c PyUnstable_Code_GetExtra}@anchor{51f1}
@deffn {C 函式} int PyUnstable_Code_GetExtra (PyObject *code, Py_ssize_t index, void **extra)

@cartouche
@quotation 這是 不穩定 API，它可能在小版本發布中沒有任何警告地被變更。 `這是 @ref{762,,不穩定 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.

@geindex _PyCode_GetExtra（C 函式）


在 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 PyUnstable_Code_SetExtra (C function)
@anchor{c-api/code c PyUnstable_Code_SetExtra}@anchor{51f2}
@deffn {C 函式} int PyUnstable_Code_SetExtra (PyObject *code, Py_ssize_t index, void *extra)

@cartouche
@quotation 這是 不穩定 API，它可能在小版本發布中沒有任何警告地被變更。 `這是 @ref{762,,不穩定 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.

@geindex _PyCode_SetExtra（C 函式）


在 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 其他物件<2>,,函式物件<2>,具體物件層
@anchor{c-api/concrete other-objects}@anchor{51f3}
@subsection 其他物件


@menu
* 檔案物件 (File Objects): 檔案物件 File Objects. 
* 模組物件:: 
* 模組定義:: 
* Creating extension modules dynamically:: 
* 支援的函式:: 
* 疊代器（Iterator）物件:: 
* Descriptor（描述器）物件:: 
* 切片物件:: 
* MemoryView 物件:: 
* 弱參照物件: 弱參照物件<2>. 
* Capsules: Capsules<2>. 
* Frame 物件:: 
* 產生器 (Generator) 物件: 產生器 Generator 物件. 
* Coroutine（協程）物件:: 
* 情境變數物件（Context Variables Objects）:: 
* DateTime 物件:: 
* 型別提示物件:: 

@end menu

@node 檔案物件 File Objects,模組物件,,其他物件<2>
@anchor{c-api/file doc}@anchor{51f4}@anchor{c-api/file file-objects}@anchor{51f5}@anchor{c-api/file fileobjects}@anchor{51f6}
@subsubsection 檔案物件 (File Objects)


@geindex object（物件）;file（檔案）

這些 API 是用於內建檔案物件的 Python 2 C API 的最小模擬 (minimal emulation)，它過去依賴於 C 標準函式庫對於緩衝 I/O (FILE*) 的支援。在 Python 3 中，檔案和串流使用新的 @ref{83,,io} 模組，它在作業系統的低階無緩衝 I/O 上定義了多個層級。下面描述的函式是這些新 API 的便捷 C 包裝器，主要用於直譯器中的內部錯誤報告；建議第三方程式碼改為存取 @ref{83,,io} API。

@geindex PyFile_FromFd (C function)
@anchor{c-api/file c PyFile_FromFd}@anchor{4eb0}
@deffn {C 函式} @ref{5d7,,PyObject} *PyFile_FromFd (int fd, const char *name, const char *mode, int buffering, const char *encoding, const char *errors, const char *newline, int closefd)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
從已打開檔案 `fd' 的檔案描述器建立一個 Python 檔案物件。引數 `name'、`encoding'、`errors' 和 `newline' 可以為 @code{NULL} 以使用預設值； `buffering' 可以是 `-1' 以使用預設值。 `name' 被忽略並保留以實作向後相容性。失敗時回傳 @code{NULL}。有關引數的更全面描述，請參閱 @ref{739,,io.open()} 函式文件。

@cartouche
@quotation 警告 
由於 Python 串流有自己的緩衝層，將它們與作業系統層級檔案描述器混合使用會產生各種問題（例如資料的排序不符合預期）。
@end quotation
@end cartouche


在 3.2 版的變更: 忽略 `name' 屬性。

@end deffn

@geindex PyObject_AsFileDescriptor (C function)
@anchor{c-api/file c PyObject_AsFileDescriptor}@anchor{4f09}
@deffn {C 函式} int PyObject_AsFileDescriptor (PyObject *p)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
回傳與 `p' 關聯的檔案描述器作為 int。如果物件是整數，則回傳其值。如果不是整數，則呼叫物件的 @ref{2b7e,,fileno()} 方法（如果存在）；該方法必須回傳一個整數，它作為檔案描述器值回傳。設定例外並在失敗時回傳 @code{-1}。
@end deffn

@geindex PyFile_GetLine (C function)
@anchor{c-api/file c PyFile_GetLine}@anchor{4eb1}
@deffn {C 函式} @ref{5d7,,PyObject} *PyFile_GetLine (PyObject *p, int n)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
@geindex EOFError（內建例外）

相當於 @code{p.readline([n])}，這個函式從物件 `p' 中讀取一行。 `p' 可以是檔案物件或任何具有 @ref{152a,,readline()} 方法的物件。如果 `n' 為 @code{0}，則不管該行的長度都只會讀取一行。如果 `n' 大於 @code{0}，則不會從檔案中讀取超過 `n' 個位元組；可以回傳該行的一部分。在這兩種情況下，如果立即到達檔案末尾，則回傳一個空字串。但是，如果 `n' 小於 @code{0}，無論長度如何，都會讀取一行，但如果立即到達檔案末尾，則會引發 @ref{14da,,EOFError}。
@end deffn

@geindex PyFile_SetOpenCodeHook (C function)
@anchor{c-api/file c PyFile_SetOpenCodeHook}@anchor{19e9}
@deffn {C 函式} int PyFile_SetOpenCodeHook (Py_OpenCodeHookFunction handler)

覆蓋 @ref{19e7,,io.open_code()} 的正常行為以透過提供的處理程式 (handler) 傳遞其參數。

The `handler' is a function of type:

@geindex Py_OpenCodeHookFunction (C type)
@anchor{c-api/file c Py_OpenCodeHookFunction}@anchor{51f7}
@deffn {C 型別} typedef @ref{5d7,,PyObject} *(*Py_OpenCodeHookFunction)(@ref{5d7,,PyObject}*, void*)

相當於 @ref{5d7,,PyObject} *(*)(@ref{5d7,,PyObject} *path, void *userData)，其中 `path' 保證為 @ref{98f,,PyUnicodeObject}。
@end deffn

`userData' 指標被傳遞到掛鉤函式 (hook function) 中。由於可能會從不同的執行環境 (runtime) 呼叫掛鉤函式，因此該指標不應直接指向 Python 狀態。

由於此掛鉤函式是在導入期間有意使用的，因此請避免在其執行期間導入新模組，除非它們已知有被凍結或在 @code{sys.modules} 中可用。

一旦設定了一個掛鉤函式，它就不能被刪除或替換，且後續對 @ref{19e9,,PyFile_SetOpenCodeHook()} 的呼叫將會失敗。失敗時，函式回傳 -1 且若直譯器已初始化便會設定例外。

在 @ref{45e,,Py_Initialize()} 之前呼叫此函式是安全的。

不帶引數地引發一個@ref{1b70,,稽核事件 (auditing event)} @code{setopencodehook}。


在 3.8 版被加入.

@end deffn

@geindex PyFile_WriteObject (C function)
@anchor{c-api/file c PyFile_WriteObject}@anchor{4eb2}
@deffn {C 函式} int PyFile_WriteObject (PyObject *obj, PyObject *p, int flags)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@geindex Py_PRINT_RAW（C 巨集）

將物件 `obj' 寫入檔案物件 `p'。 `flags' 唯一支援的旗標是 @ref{5068,,Py_PRINT_RAW}；如果有給定，則寫入物件的 @ref{169,,str()} 而不是 @ref{1c1,,repr()}。在成功回傳 @code{0} 或在失敗回傳 @code{-1}；將設定適當的例外。
@end deffn

@geindex PyFile_WriteString (C function)
@anchor{c-api/file c PyFile_WriteString}@anchor{4eb3}
@deffn {C 函式} int PyFile_WriteString (const char *s, PyObject *p)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
寫入字串 `s' 到 檔案物件 `p'。當成功時回傳 0，而當失敗時回傳 -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 模組物件,模組定義,檔案物件 File Objects,其他物件<2>
@anchor{c-api/module doc}@anchor{51f8}@anchor{c-api/module module-objects}@anchor{51f9}@anchor{c-api/module moduleobjects}@anchor{51fa}@anchor{c-api/module translation-repo}@anchor{51fb}
@subsubsection 模組物件


@geindex object（模組）;module（模組）

@geindex PyModule_Type (C var)
@anchor{c-api/module c PyModule_Type}@anchor{4ee5}
@deffn {C 變數} @ref{c93,,PyTypeObject} PyModule_Type
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@geindex MethodType（types 模組中）

This instance of @ref{c93,,PyTypeObject} represents the Python module type.  This
is exposed to Python programs as @code{types.ModuleType}.
@end deffn

@geindex PyModule_Check (C function)
@anchor{c-api/module c PyModule_Check}@anchor{51fc}
@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{51fd}
@deffn {C 函式} int PyModule_CheckExact (PyObject *p)

Return true if `p' is a module object, but not a subtype of
@ref{4ee5,,PyModule_Type}.  This function always succeeds.
@end deffn

@geindex PyModule_NewObject (C function)
@anchor{c-api/module c PyModule_NewObject}@anchor{4ee3}
@deffn {C 函式} @ref{5d7,,PyObject} *PyModule_NewObject (PyObject *name)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.7 版本開始.'
@geindex __name__（模組屬性）
@geindex __doc__（模組屬性）
@geindex __file__（模組屬性）
@geindex __package__（模組屬性）
@geindex __loader__（模組屬性）

Return a new module object with @ref{1583,,module.__name__} set to `name'.
The module's @code{__name__}, @ref{1b0a,,__doc__},
@ref{322,,__package__} and @ref{33a,,__loader__} attributes are
filled in (all but @code{__name__} are set to @code{None}). The caller is
responsible for setting a @ref{221b,,__file__} attribute.

在失敗時回傳 @code{NULL} 並設定例外。


在 3.3 版被加入.



在 3.4 版的變更: @ref{322,,__package__} 和 @ref{33a,,__loader__} 現在被設為 @code{None}。

@end deffn

@geindex PyModule_New (C function)
@anchor{c-api/module c PyModule_New}@anchor{4ee2}
@deffn {C 函式} @ref{5d7,,PyObject} *PyModule_New (const char *name)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
類似於 @ref{4ee3,,PyModule_NewObject()}，但名稱是以 UTF-8 編碼的字串，而非 Unicode 物件。
@end deffn

@geindex PyModule_GetDict (C function)
@anchor{c-api/module c PyModule_GetDict}@anchor{4edf}
@deffn {C 函式} @ref{5d7,,PyObject} *PyModule_GetDict (PyObject *module)
`回傳值：借用參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
@geindex __dict__（模組屬性）

Return the dictionary object that implements `module''s namespace; this object
is the same as the @ref{776,,__dict__} attribute of the module object.
If `module' is not a module object (or a subtype of a module object),
@ref{78e,,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{776,,__dict__}.
@end deffn

@geindex PyModule_GetNameObject (C function)
@anchor{c-api/module c PyModule_GetNameObject}@anchor{4ee1}
@deffn {C 函式} @ref{5d7,,PyObject} *PyModule_GetNameObject (PyObject *module)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.7 版本開始.'
@geindex __name__（模組屬性）
@geindex SystemError（內建例外）

Return `module''s @ref{1583,,__name__} value.  If the module does not
provide one, or if it is not a string, @ref{78e,,SystemError} is raised and
@code{NULL} is returned.


在 3.3 版被加入.

@end deffn

@geindex PyModule_GetName (C function)
@anchor{c-api/module c PyModule_GetName}@anchor{4ee0}
@deffn {C 函式} const char *PyModule_GetName (PyObject *module)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
類似於 @ref{4ee1,,PyModule_GetNameObject()}，但回傳以 @code{'utf-8'} 編碼的名稱。
@end deffn

@geindex PyModule_GetState (C function)
@anchor{c-api/module c PyModule_GetState}@anchor{b6e}
@deffn {C 函式} void *PyModule_GetState (PyObject *module)
` 為 @ref{76e,,穩定 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{b6d,,PyModuleDef.m_size}.
@end deffn

@geindex PyModule_GetDef (C function)
@anchor{c-api/module c PyModule_GetDef}@anchor{4ede}
@deffn {C 函式} @ref{b6b,,PyModuleDef} *PyModule_GetDef (PyObject *module)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return a pointer to the @ref{b6b,,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{1ba7,,PyErr_Occurred()} to tell this case apart from a mising
@code{PyModuleDef}.
@end deffn

@geindex PyModule_GetFilenameObject (C function)
@anchor{c-api/module c PyModule_GetFilenameObject}@anchor{42c}
@deffn {C 函式} @ref{5d7,,PyObject} *PyModule_GetFilenameObject (PyObject *module)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
@geindex __file__（模組屬性）
@geindex SystemError（內建例外）

Return the name of the file from which `module' was loaded using `module''s
@ref{221b,,__file__} attribute.  If this is not defined, or if it is not a
string, raise @ref{78e,,SystemError} and return @code{NULL}; otherwise return
a reference to a Unicode object.


在 3.2 版被加入.

@end deffn

@geindex PyModule_GetFilename (C function)
@anchor{c-api/module c PyModule_GetFilename}@anchor{42b}
@deffn {C 函式} const char *PyModule_GetFilename (PyObject *module)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
類似於 @ref{42c,,PyModule_GetFilenameObject()}，但回傳以 'utf-8' 編碼的檔案名稱。


在 3.2 版之後被棄用: @ref{42b,,PyModule_GetFilename()} raises @ref{880,,UnicodeEncodeError} on
unencodable filenames, use @ref{42c,,PyModule_GetFilenameObject()} instead.

@end deffn

@node 模組定義,Creating extension modules dynamically,模組物件,其他物件<2>
@anchor{c-api/module module-definitions}@anchor{51fe}@anchor{c-api/module pymoduledef}@anchor{51ff}
@subsubsection 模組定義


The functions in the previous section work on any module object, including
modules imported from Python code.

Modules defined using the C API typically use a `module definition',
@ref{b6b,,PyModuleDef} -- a statically allocated, constant “description" of
how a module should be created.

The definition is usually used to define an extension's “main” module object
(see @ref{4dc4,,Defining extension modules} for details).
It is also used to
@ref{5200,,create extension modules dynamically}.

Unlike @ref{4ee2,,PyModule_New()}, the definition allows management of
`module state' -- a piece of memory that is allocated and cleared together
with the module object.
Unlike the module's Python attributes, Python code cannot replace or delete
data stored in module state.

@geindex PyModuleDef (C type)
@anchor{c-api/module c PyModuleDef}@anchor{b6b}
@deffn {C 型別} type PyModuleDef
` 為 @ref{76e,,穩定 ABI 的一部分} （包含所有成員）.'
The module definition struct, which holds all 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.

@geindex PyModuleDef.m_base (C member)
@anchor{c-api/module c PyModuleDef m_base}@anchor{5201}
@deffn {C 成員函數} PyModuleDef_Base m_base

Always initialize this member to @code{PyModuleDef_HEAD_INIT}.
@end deffn

@geindex PyModuleDef.m_name (C member)
@anchor{c-api/module c PyModuleDef m_name}@anchor{5202}
@deffn {C 成員函數} const char *m_name

Name for the new module.
@end deffn

@geindex PyModuleDef.m_doc (C member)
@anchor{c-api/module c PyModuleDef m_doc}@anchor{5203}
@deffn {C 成員函數} const char *m_doc

Docstring for the module; usually a docstring variable created with
@ref{1c24,,PyDoc_STRVAR} is used.
@end deffn

@geindex PyModuleDef.m_size (C member)
@anchor{c-api/module c PyModuleDef m_size}@anchor{b6d}
@deffn {C 成員函數} @ref{c4c,,Py_ssize_t} m_size

Module state may be kept in a per-module memory area that can be
retrieved with @ref{b6e,,PyModule_GetState()}, rather than in static globals.
This makes modules safe for use in multiple sub-interpreters.

This memory area is allocated based on `m_size' on module creation,
and freed when the module object is deallocated, after the
@ref{b6a,,m_free} function has been called, if present.

Setting it to a non-negative value means that the module can be
re-initialized and specifies the additional amount of memory it requires
for its state.

Setting @code{m_size} to @code{-1} means that the module does not support
sub-interpreters, because it has global state.
Negative @code{m_size} is only allowed when using
@ref{4ffd,,legacy single-phase initialization}
or when @ref{5200,,creating modules dynamically}.

更多詳情請見 
@geindex Python Enhancement Proposals; PEP 3121
PEP 3121@footnote{https://peps.python.org/pep-3121/}。
@end deffn

@geindex PyModuleDef.m_methods (C member)
@anchor{c-api/module c PyModuleDef m_methods}@anchor{5204}
@deffn {C 成員函數} @ref{16cb,,PyMethodDef} *m_methods

A pointer to a table of module-level functions, described by
@ref{16cb,,PyMethodDef} values.  Can be @code{NULL} if no functions are present.
@end deffn

@geindex PyModuleDef.m_slots (C member)
@anchor{c-api/module c PyModuleDef m_slots}@anchor{5005}
@deffn {C 成員函數} @ref{5205,,PyModuleDef_Slot} *m_slots

An array of slot definitions for multi-phase initialization, terminated by
a @code{@{0, NULL@}} entry.
When using legacy single-phase initialization, `m_slots' must be @code{NULL}.


在 3.5 版的變更: 在 3.5 版本之前，這個成員總是被設為 @code{NULL}，並被定義為：

@quotation

@geindex PyModuleDef.m_slots.m_reload (C member)
@anchor{c-api/module c PyModuleDef m_slots m_reload}@anchor{5206}
@deffn {C 成員函數} @ref{4fa8,,inquiry} m_reload
@end deffn
@end quotation

@end deffn

@geindex PyModuleDef.m_traverse (C member)
@anchor{c-api/module c PyModuleDef m_traverse}@anchor{b68}
@deffn {C 成員函數} @ref{4fb7,,traverseproc} m_traverse

A traversal function to call during GC traversal of the module object, or
@code{NULL} if not needed.

This function is not called if the module state was requested but is not
allocated yet. This is the case immediately after the module is created
and before the module is executed (@ref{b6c,,Py_mod_exec} function). More
precisely, this function is not called if @ref{b6d,,m_size} is greater
than 0 and the module state (as returned by @ref{b6e,,PyModule_GetState()})
is @code{NULL}.


在 3.9 版的變更: No longer called before the module state is allocated.

@end deffn

@geindex PyModuleDef.m_clear (C member)
@anchor{c-api/module c PyModuleDef m_clear}@anchor{b69}
@deffn {C 成員函數} @ref{4fa8,,inquiry} m_clear

A clear function to call during GC clearing of the module object, or
@code{NULL} if not needed.

This function is not called if the module state was requested but is not
allocated yet. This is the case immediately after the module is created
and before the module is executed (@ref{b6c,,Py_mod_exec} function). More
precisely, this function is not called if @ref{b6d,,m_size} is greater
than 0 and the module state (as returned by @ref{b6e,,PyModule_GetState()})
is @code{NULL}.

Like @ref{4daa,,PyTypeObject.tp_clear}, this function is not `always'
called before a module is deallocated. For example, when reference
counting is enough to determine that an object is no longer used,
the cyclic garbage collector is not involved and
@ref{b6a,,m_free} is called directly.


在 3.9 版的變更: No longer called before the module state is allocated.

@end deffn

@geindex PyModuleDef.m_free (C member)
@anchor{c-api/module c PyModuleDef m_free}@anchor{b6a}
@deffn {C 成員函數} @ref{5207,,freefunc} m_free

A function to call during deallocation of the module object, or @code{NULL}
if not needed.

This function is not called if the module state was requested but is not
allocated yet. This is the case immediately after the module is created
and before the module is executed (@ref{b6c,,Py_mod_exec} function). More
precisely, this function is not called if @ref{b6d,,m_size} is greater
than 0 and the module state (as returned by @ref{b6e,,PyModule_GetState()})
is @code{NULL}.


在 3.9 版的變更: No longer called before the module state is allocated.

@end deffn
@end deffn

@menu
* 模組槽 (Module slots): 模組槽 Module slots. 

@end menu

@node 模組槽 Module slots,,,模組定義
@anchor{c-api/module module-slots}@anchor{5208}
@subsubsection 模組槽 (Module slots)


@geindex PyModuleDef_Slot (C type)
@anchor{c-api/module c PyModuleDef_Slot}@anchor{5205}
@deffn {C 型別} type PyModuleDef_Slot

@geindex PyModuleDef_Slot.slot (C member)
@anchor{c-api/module c PyModuleDef_Slot slot}@anchor{5209}
@deffn {C 成員函數} int slot

A slot ID, chosen from the available values explained below.
@end deffn

@geindex PyModuleDef_Slot.value (C member)
@anchor{c-api/module c PyModuleDef_Slot value}@anchor{520a}
@deffn {C 成員函數} void *value

Value of the slot, whose meaning depends on the slot ID.
@end deffn


在 3.5 版被加入.

@end deffn

The available slot types are:

@geindex Py_mod_create (C macro)
@anchor{c-api/module c Py_mod_create}@anchor{520b}
@deffn {C 巨集} Py_mod_create

Specifies a function that is called to create the module object itself.
The `value' pointer of this slot must point to a function of the signature:

@anchor{c-api/module c Py_mod_create create_module}@anchor{520c}
@deffn {C 函式} @ref{5d7,,PyObject} *create_module (PyObject *spec, PyModuleDef *def)
@end deffn

The function receives a @ref{2130,,ModuleSpec}
instance, as defined in 
@geindex Python Enhancement Proposals; PEP 451
PEP 451@footnote{https://peps.python.org/pep-0451/}, and the module definition.
It should return a new module object, or set an error
and return @code{NULL}.

This function should be kept minimal. In particular, it should not
call arbitrary Python code, as trying to import the same module again may
result in an infinite loop.

Multiple @code{Py_mod_create} slots may not be specified in one module
definition.

If @code{Py_mod_create} is not specified, the import machinery will create
a normal module object using @ref{4ee2,,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{4ee5,,PyModule_Type}. Any type can be used, as long as it supports
setting and getting import-related attributes.
However, only @code{PyModule_Type} instances may be returned if the
@code{PyModuleDef} has non-@code{NULL} @code{m_traverse}, @code{m_clear},
@code{m_free}; non-zero @code{m_size}; or slots other than @code{Py_mod_create}.
@end deffn

@geindex Py_mod_exec (C macro)
@anchor{c-api/module c Py_mod_exec}@anchor{b6c}
@deffn {C 巨集} Py_mod_exec

Specifies a function that is called to `execute' the module.
This is equivalent to executing the code of a Python module: typically,
this function adds classes and constants to the module.
The signature of the function is:

@anchor{c-api/module c Py_mod_exec exec_module}@anchor{520d}
@deffn {C 函式} int exec_module (PyObject *module)
@end deffn

If multiple @code{Py_mod_exec} slots are specified, they are processed in the
order they appear in the `m_slots' array.
@end deffn

@geindex Py_mod_multiple_interpreters (C macro)
@anchor{c-api/module c Py_mod_multiple_interpreters}@anchor{5000}
@deffn {C 巨集} Py_mod_multiple_interpreters

Specifies one of the following values:

@geindex Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED (C macro)
@anchor{c-api/module c Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED}@anchor{4d6c}
@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{520e}
@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{166,,隔離擴充模組}.)
@end deffn

@geindex Py_MOD_PER_INTERPRETER_GIL_SUPPORTED (C macro)
@anchor{c-api/module c Py_MOD_PER_INTERPRETER_GIL_SUPPORTED}@anchor{520f}
@deffn {C 巨集} Py_MOD_PER_INTERPRETER_GIL_SUPPORTED

The module supports being imported in subinterpreters,
even when they have their own GIL.
(See @ref{166,,隔離擴充模組}.)
@end deffn

This slot determines whether or not importing this module
in a subinterpreter will fail.

Multiple @code{Py_mod_multiple_interpreters} slots may not be specified
in one module definition.

If @code{Py_mod_multiple_interpreters} is not specified, the import
machinery defaults to @code{Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED}.


在 3.12 版被加入.

@end deffn

@geindex Py_mod_gil (C macro)
@anchor{c-api/module c Py_mod_gil}@anchor{47d}
@deffn {C 巨集} Py_mod_gil

Specifies one of the following values:

@geindex Py_MOD_GIL_USED (C macro)
@anchor{c-api/module c Py_MOD_GIL_USED}@anchor{5210}
@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{5211}
@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{494,,--disable-gil}.  Otherwise, it determines whether or not importing
this module will cause the GIL to be automatically enabled. See
@ref{467,,Free-threaded CPython} for more detail.

Multiple @code{Py_mod_gil} slots may not be specified in one module definition.

If @code{Py_mod_gil} is not specified, the import machinery defaults to
@code{Py_MOD_GIL_USED}.


在 3.13 版被加入.

@end deffn

@node Creating extension modules dynamically,支援的函式,模組定義,其他物件<2>
@anchor{c-api/module creating-extension-modules-dynamically}@anchor{5212}@anchor{c-api/module moduledef-dynamic}@anchor{5200}
@subsubsection Creating extension modules dynamically


The following functions may be used to create a module outside of an
extension's @ref{4ffc,,initialization function}.
They are also used in
@ref{4ffd,,single-phase initialization}.

@geindex PyModule_Create (C function)
@anchor{c-api/module c PyModule_Create}@anchor{5007}
@deffn {C 函式} @ref{5d7,,PyObject} *PyModule_Create (PyModuleDef *def)
`回傳值：新的參照。'
Create a new module object, given the definition in `def'.
This is a macro that calls @ref{4edd,,PyModule_Create2()} with
`module_api_version' set to @ref{47e5,,PYTHON_API_VERSION}, or
to @ref{5213,,PYTHON_ABI_VERSION} if using the
@ref{62f,,limited API}.
@end deffn

@geindex PyModule_Create2 (C function)
@anchor{c-api/module c PyModule_Create2}@anchor{4edd}
@deffn {C 函式} @ref{5d7,,PyObject} *PyModule_Create2 (PyModuleDef *def, int module_api_version)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{4d2,,RuntimeWarning} is emitted.

在失敗時回傳 @code{NULL} 並設定例外。

This function does not support slots.
The @ref{5005,,m_slots} member of `def' must be @code{NULL}.

@cartouche
@quotation 備註 
Most uses of this function should be using @ref{5007,,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{10ae}
@deffn {C 函式} @ref{5d7,,PyObject} *PyModule_FromDefAndSpec (PyModuleDef *def, PyObject *spec)
`回傳值：新的參照。'
This macro calls @ref{10af,,PyModule_FromDefAndSpec2()} with
`module_api_version' set to @ref{47e5,,PYTHON_API_VERSION}, or
to @ref{5213,,PYTHON_ABI_VERSION} if using the
@ref{62f,,limited API}.


在 3.5 版被加入.

@end deffn

@geindex PyModule_FromDefAndSpec2 (C function)
@anchor{c-api/module c PyModule_FromDefAndSpec2}@anchor{10af}
@deffn {C 函式} @ref{5d7,,PyObject} *PyModule_FromDefAndSpec2 (PyModuleDef *def, PyObject *spec, int module_api_version)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{4d2,,RuntimeWarning} is emitted.

在失敗時回傳 @code{NULL} 並設定例外。

Note that this does not process execution slots (@ref{b6c,,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{10ae,,PyModule_FromDefAndSpec()}
instead; only use this if you are sure you need it.
@end quotation
@end cartouche


在 3.5 版被加入.

@end deffn

@geindex PyModule_ExecDef (C function)
@anchor{c-api/module c PyModule_ExecDef}@anchor{10b0}
@deffn {C 函式} int PyModule_ExecDef (PyObject *module, PyModuleDef *def)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.7 版本開始.'
Process any execution slots (@ref{b6c,,Py_mod_exec}) given in `def'.


在 3.5 版被加入.

@end deffn

@geindex PYTHON_API_VERSION (C macro)
@anchor{c-api/module c PYTHON_API_VERSION}@anchor{47e5}
@deffn {C 巨集} PYTHON_API_VERSION

The C 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 PYTHON_ABI_VERSION (C macro)
@anchor{c-api/module c PYTHON_ABI_VERSION}@anchor{5213}
@deffn {C 巨集} PYTHON_ABI_VERSION

Defined as @code{3} for backwards compatibility.

Currently, this constant is not updated in new Python versions, and is not
useful for versioning. This may change in the future.
@end deffn

@node 支援的函式,疊代器（Iterator）物件,Creating extension modules dynamically,其他物件<2>
@anchor{c-api/module support-functions}@anchor{5214}
@subsubsection 支援的函式


The following functions are provided to help initialize a module
state.
They are intended for a module's execution slots (@ref{b6c,,Py_mod_exec}),
the initialization function for legacy @ref{4ffd,,single-phase initialization},
or code that creates modules dynamically.

@geindex PyModule_AddObjectRef (C function)
@anchor{c-api/module c PyModule_AddObjectRef}@anchor{602}
@deffn {C 函式} int PyModule_AddObjectRef (PyObject *module, const char *name, PyObject *value)
` 為 @ref{76e,,穩定 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
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{4f80,,PyUnicode_FromString()} and @ref{4f19,,PyObject_SetAttr()} directly.
For more details, see @ref{18e6,,PyUnicode_InternFromString()}, which may be
used internally to create a key object.


在 3.10 版被加入.

@end deffn

@geindex PyModule_Add (C function)
@anchor{c-api/module c PyModule_Add}@anchor{601}
@deffn {C 函式} int PyModule_Add (PyObject *module, const char *name, PyObject *value)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.13 版本開始.'
Similar to @ref{602,,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
if (PyModule_Add(module, "spam", PyBytes_FromString(value)) < 0) @{
    goto error;
@}
@end example


在 3.13 版被加入.

@end deffn

@geindex PyModule_AddObject (C function)
@anchor{c-api/module c PyModule_AddObject}@anchor{603}
@deffn {C 函式} int PyModule_AddObject (PyObject *module, const char *name, PyObject *value)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
類似於 @ref{602,,PyModule_AddObjectRef()}，但在成功時（如果回傳 @code{0}）會偷走對 `value' 的參照。

The new @ref{601,,PyModule_Add()} or @ref{602,,PyModule_AddObjectRef()}
functions are recommended, since it is
easy to introduce reference leaks by misusing the
@ref{603,,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{98a,,Py_XDECREF()} `value' manually on error.
@end quotation
@end cartouche

用法範例：

@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


在 3.13 版之後被棄用: @ref{603,,PyModule_AddObject()} 已被@ref{23d,,軟性棄用}。

@end deffn

@geindex PyModule_AddIntConstant (C function)
@anchor{c-api/module c PyModule_AddIntConstant}@anchor{1730}
@deffn {C 函式} int PyModule_AddIntConstant (PyObject *module, const char *name, long value)
` 為 @ref{76e,,穩定 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{1af0,,PyLong_FromLong()} and
@ref{602,,PyModule_AddObjectRef()}; see their documentation for details.
@end deffn

@geindex PyModule_AddStringConstant (C function)
@anchor{c-api/module c PyModule_AddStringConstant}@anchor{1731}
@deffn {C 函式} int PyModule_AddStringConstant (PyObject *module, const char *name, const char *value)
` 為 @ref{76e,,穩定 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{18e6,,PyUnicode_InternFromString()} and @ref{602,,PyModule_AddObjectRef()};
see their documentation for details.
@end deffn

@geindex PyModule_AddIntMacro (C macro)
@anchor{c-api/module c PyModule_AddIntMacro}@anchor{15ea}
@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{15e9}
@deffn {C 巨集} PyModule_AddStringMacro (module, macro)

將字串常數加入到 `module' 中。
@end deffn

@geindex PyModule_AddType (C function)
@anchor{c-api/module c PyModule_AddType}@anchor{b63}
@deffn {C 函式} int PyModule_AddType (PyObject *module, PyTypeObject *type)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.10 版本開始.'
Add a type object to `module'.
The type object is finalized by calling internally @ref{97a,,PyType_Ready()}.
The name of the type object is taken from the last component of
@ref{1ba8,,tp_name} after dot.
Return @code{-1} with an exception set on error, @code{0} on success.


在 3.9 版被加入.

@end deffn

@geindex PyModule_AddFunctions (C function)
@anchor{c-api/module c PyModule_AddFunctions}@anchor{4edc}
@deffn {C 函式} int PyModule_AddFunctions (PyObject *module, PyMethodDef *functions)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.7 版本開始.'
Add the functions from the @code{NULL} terminated `functions' array to `module'.
Refer to the @ref{16cb,,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{5003,,Multi-phase initialization},
@code{PyModule_Create}, or @code{PyModule_FromDefAndSpec}).
Some module authors may prefer defining functions in multiple
@ref{16cb,,PyMethodDef} arrays; in that case they should call this function
directly.


在 3.5 版被加入.

@end deffn

@geindex PyModule_SetDocString (C function)
@anchor{c-api/module c PyModule_SetDocString}@anchor{4ee4}
@deffn {C 函式} int PyModule_SetDocString (PyObject *module, const char *docstring)
` 為 @ref{76e,,穩定 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{5003,,Multi-phase initialization},
@code{PyModule_Create}, or @code{PyModule_FromDefAndSpec}).


在 3.5 版被加入.

@end deffn

@geindex PyUnstable_Module_SetGIL (C function)
@anchor{c-api/module c PyUnstable_Module_SetGIL}@anchor{498}
@deffn {C 函式} int PyUnstable_Module_SetGIL (PyObject *module, void *gil)

@cartouche
@quotation 這是 不穩定 API，它可能在小版本發布中沒有任何警告地被變更。 `這是 @ref{762,,不穩定 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{47d,,Py_mod_gil}. It must be called during `module''s initialization
function when using @ref{4ffd,,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{494,,--disable-gil}.
Return @code{-1} with an exception set on error, @code{0} on success.


在 3.13 版被加入.

@end deffn

@menu
* Module lookup (single-phase initialization): Module lookup single-phase initialization. 

@end menu

@node Module lookup single-phase initialization,,,支援的函式
@anchor{c-api/module module-lookup-single-phase-initialization}@anchor{5215}
@subsubsection Module lookup (single-phase initialization)


The legacy @ref{4ffd,,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{4f33}
@deffn {C 函式} @ref{5d7,,PyObject} *PyState_FindModule (PyModuleDef *def)
`回傳值：借用參照。'` 為 @ref{76e,,穩定 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{4f32,,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{4f32}
@deffn {C 函式} int PyState_AddModule (PyObject *module, PyModuleDef *def)
` 為 @ref{76e,,穩定 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{4f33,,PyState_FindModule()}.

Only effective on modules created using single-phase initialization.

Python calls @code{PyState_AddModule} automatically after importing a module
that uses @ref{4ffd,,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{4d99,,attached thread state}.

成功時回傳 @code{0}，在失敗時回傳 @code{-1} 並設定例外。


在 3.3 版被加入.

@end deffn

@geindex PyState_RemoveModule (C function)
@anchor{c-api/module c PyState_RemoveModule}@anchor{4f34}
@deffn {C 函式} int PyState_RemoveModule (PyModuleDef *def)
` 為 @ref{76e,,穩定 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{4d99,,attached thread state}.


在 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）物件,Descriptor（描述器）物件,支援的函式,其他物件<2>
@anchor{c-api/iterator doc}@anchor{5216}@anchor{c-api/iterator id1}@anchor{5217}@anchor{c-api/iterator iterator-objects}@anchor{5218}@anchor{c-api/iterator translation-repo}@anchor{5219}
@subsubsection 疊代器（Iterator）物件


Python 提供了兩種通用的疊代器 (iterator) 物件，第一種是序列疊代器 (sequence iterator)，適用於支援 @ref{582,,__getitem__()} 方法的任意序列，第二種是與可呼叫 (callable) 物件和哨兵值 (sentinel value) 一起使用，會呼叫序列中的每個可呼叫物件，當回傳哨兵值時就結束疊代。

@geindex PySeqIter_Type (C var)
@anchor{c-api/iterator c PySeqIter_Type}@anchor{4f1e}
@deffn {C 變數} @ref{c93,,PyTypeObject} PySeqIter_Type
` 為 @ref{76e,,穩定 ABI 的一部分}.'
此型別物件用於由 @ref{4f1d,,PySeqIter_New()} 所回傳的疊代器物件以及用於內建序列型別的內建函式 @ref{9d0,,iter()} 的單引數形式。
@end deffn

@geindex PySeqIter_Check (C function)
@anchor{c-api/iterator c PySeqIter_Check}@anchor{521a}
@deffn {C 函式} int PySeqIter_Check (PyObject *op)

Return true if the type of `op' is @ref{4f1e,,PySeqIter_Type}.  This function
always succeeds.
@end deffn

@geindex PySeqIter_New (C function)
@anchor{c-api/iterator c PySeqIter_New}@anchor{4f1d}
@deffn {C 函式} @ref{5d7,,PyObject} *PySeqIter_New (PyObject *seq)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return an iterator that works with a general sequence object, `seq'.  The
iteration ends when the sequence raises @ref{1729,,IndexError} for the subscripting
operation.
@end deffn

@geindex PyCallIter_Type (C var)
@anchor{c-api/iterator c PyCallIter_Type}@anchor{4e2b}
@deffn {C 變數} @ref{c93,,PyTypeObject} PyCallIter_Type
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Type object for iterator objects returned by @ref{4e2a,,PyCallIter_New()} and the
two-argument form of the @ref{9d0,,iter()} built-in function.
@end deffn

@geindex PyCallIter_Check (C function)
@anchor{c-api/iterator c PyCallIter_Check}@anchor{521b}
@deffn {C 函式} int PyCallIter_Check (PyObject *op)

Return true if the type of `op' is @ref{4e2b,,PyCallIter_Type}.  This
function always succeeds.
@end deffn

@geindex PyCallIter_New (C function)
@anchor{c-api/iterator c PyCallIter_New}@anchor{4e2a}
@deffn {C 函式} @ref{5d7,,PyObject} *PyCallIter_New (PyObject *callable, PyObject *sentinel)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Descriptor（描述器）物件,切片物件,疊代器（Iterator）物件,其他物件<2>
@anchor{c-api/descriptor doc}@anchor{521c}@anchor{c-api/descriptor descriptor-objects}@anchor{521d}@anchor{c-api/descriptor id1}@anchor{521e}@anchor{c-api/descriptor translation-repo}@anchor{521f}
@subsubsection Descriptor（描述器）物件


"Descriptor" 是描述物件某些屬性的物件，它們存在於型別物件的 dictionary（字典）中。

@c XXX document these!

@geindex PyProperty_Type (C var)
@anchor{c-api/descriptor c PyProperty_Type}@anchor{4f1c}
@deffn {C 變數} @ref{c93,,PyTypeObject} PyProperty_Type
` 為 @ref{76e,,穩定 ABI 的一部分}.'
內建 descriptor 型別的型別物件。
@end deffn

@geindex PyDescr_NewGetSet (C function)
@anchor{c-api/descriptor c PyDescr_NewGetSet}@anchor{4e48}
@deffn {C 函式} @ref{5d7,,PyObject} *PyDescr_NewGetSet (PyTypeObject *type, struct PyGetSetDef *getset)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@geindex PyDescr_NewMember (C function)
@anchor{c-api/descriptor c PyDescr_NewMember}@anchor{4e49}
@deffn {C 函式} @ref{5d7,,PyObject} *PyDescr_NewMember (PyTypeObject *type, struct PyMemberDef *meth)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@geindex PyDescr_NewMethod (C function)
@anchor{c-api/descriptor c PyDescr_NewMethod}@anchor{1c3e}
@deffn {C 函式} @ref{5d7,,PyObject} *PyDescr_NewMethod (PyTypeObject *type, struct PyMethodDef *meth)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@geindex PyDescr_NewWrapper (C function)
@anchor{c-api/descriptor c PyDescr_NewWrapper}@anchor{5220}
@deffn {C 函式} @ref{5d7,,PyObject} *PyDescr_NewWrapper (PyTypeObject *type, struct wrapperbase *wrapper, void *wrapped)
`回傳值：新的參照。'
@end deffn

@geindex PyDescr_NewClassMethod (C function)
@anchor{c-api/descriptor c PyDescr_NewClassMethod}@anchor{4e47}
@deffn {C 函式} @ref{5d7,,PyObject} *PyDescr_NewClassMethod (PyTypeObject *type, PyMethodDef *method)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@geindex PyDescr_IsData (C function)
@anchor{c-api/descriptor c PyDescr_IsData}@anchor{1bab}
@deffn {C 函式} int PyDescr_IsData (PyObject *descr)

如果 descriptor 物件 `descr' 描述的是一個資料屬性則回傳非零值，或者如果它描述的是一個方法則返回 @code{0}。`descr' 必須為一個 descriptor 物件；沒有錯誤檢查。
@end deffn

@geindex PyWrapper_New (C function)
@anchor{c-api/descriptor c PyWrapper_New}@anchor{4f8c}
@deffn {C 函式} @ref{5d7,,PyObject} *PyWrapper_New (PyObject*, PyObject*)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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 切片物件,MemoryView 物件,Descriptor（描述器）物件,其他物件<2>
@anchor{c-api/slice doc}@anchor{5221}@anchor{c-api/slice id1}@anchor{5222}@anchor{c-api/slice slice-objects}@anchor{5223}@anchor{c-api/slice translation-repo}@anchor{5224}
@subsubsection 切片物件


@geindex PySlice_Type (C var)
@anchor{c-api/slice c PySlice_Type}@anchor{4f31}
@deffn {C 變數} @ref{c93,,PyTypeObject} PySlice_Type
` 為 @ref{76e,,穩定 ABI 的一部分}.'
slice 物件的型別物件。這與 Python 層中的 @ref{68d,,slice} 相同。
@end deffn

@geindex PySlice_Check (C function)
@anchor{c-api/slice c PySlice_Check}@anchor{5225}
@deffn {C 函式} int PySlice_Check (PyObject *ob)

如果 `ob' 是 slice 物件，則回傳 true；`ob' 不能是 @code{NULL} 。此函式永遠成功。
@end deffn

@geindex PySlice_New (C function)
@anchor{c-api/slice c PySlice_New}@anchor{4f30}
@deffn {C 函式} @ref{5d7,,PyObject} *PySlice_New (PyObject *start, PyObject *stop, PyObject *step)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
以指定的值回傳一個新的切片物件。`start'、`stop' 及 `step' 參數會被用為同名的 slice 物件屬性值。任何值都可能是 @code{NULL}，在這種情況下，@code{None} 將用於相對應的屬性。

如果無法分配新物件，則回傳 @code{NULL} 並設定例外。
@end deffn

@geindex PySlice_GetIndices (C function)
@anchor{c-api/slice c PySlice_GetIndices}@anchor{4f2f}
@deffn {C 函式} int PySlice_GetIndices (PyObject *slice, Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
從 slice 物件 `slice' 讀取開始、停止和步進索引，假設序列長度為 `length'。將大於 `length' 的索引視為錯誤。

成功時回傳 @code{0}，錯誤時回傳 @code{-1}，並無例外設定（除非其中一個索引不是 @code{None} 並且未能轉換成整數，在這種情況下會回傳 @code{-1} ，並有設定例外）。

你可能不想使用此功能。


在 3.2 版的變更: 之前 `slice' 的參數型別是 @code{PySliceObject*} 。

@end deffn

@geindex PySlice_GetIndicesEx (C function)
@anchor{c-api/slice c PySlice_GetIndicesEx}@anchor{42f}
@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{76e,,穩定 ABI 的一部分}.'
可用來取代 @ref{4f2f,,PySlice_GetIndices()}。從假設序列長度為 `length' 的 slice 物件 `slice' 擷取開始、停止和步長索引，並將 slice 的長度存入 `slicelength'。超出範圍的索引會被剪切，剪切方式與一般切片的處理方式一致。

成功時回傳 @code{0} ，在失敗時回傳 @code{-1} 並設定例外。

@cartouche
@quotation 備註 
這個函式對於可調整大小的序列並不安全。它的呼叫應該被 @ref{430,,PySlice_Unpack()} 和 @ref{431,,PySlice_AdjustIndices()} 的組合取代，其中：

@example
if (PySlice_GetIndicesEx(slice, length, &start, &stop, &step, &slicelength) < 0) @{
    // return error
@}
@end example

被更換為：

@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 版的變更: 之前 `slice' 的參數型別是 @code{PySliceObject*} 。



在 3.6.1 版的變更: 如果 @code{Py_LIMITED_API} 沒有設定或設定為 @code{0x03050400} 和 @code{0x03060000} (不包括) 或 @code{0x03060100} 或更高的值 @code{PySlice_GetIndicesEx()} 是使用 @code{PySlice_Unpack()} 和 @code{PySlice_AdjustIndices()} 來實作一個巨集。引數 `start'、`stop' 和 `step' 會被計算多次。



在 3.6.1 版之後被棄用: 如果 @code{Py_LIMITED_API} 設定為小於 @code{0x03050400} 或介於 @code{0x03060000} 和 @code{0x03060100} 之間 (不包括邊界值) @code{PySlice_GetIndicesEx()} 是一個已廢棄的函式。

@end deffn

@geindex PySlice_Unpack (C function)
@anchor{c-api/slice c PySlice_Unpack}@anchor{430}
@deffn {C 函式} int PySlice_Unpack (PyObject *slice, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.7 版本開始.'
以 C 整數的形式從 slice 物件中抽取 start、stop 及 step 資料成員。將大於 @code{PY_SSIZE_T_MAX} 的值靜默減少為 @code{PY_SSIZE_T_MAX}，將小於 @code{PY_SSIZE_T_MIN} 的 start 和 stop 值靜默提升為 @code{PY_SSIZE_T_MIN}，將小於 @code{-PY_SSIZE_T_MAX} 的 step 值靜默提升為 @code{-PY_SSIZE_T_MAX}。

成功時回傳 @code{0}，在失敗時回傳 @code{-1} 並設定例外。


在 3.6.1 版被加入.

@end deffn

@geindex PySlice_AdjustIndices (C function)
@anchor{c-api/slice c PySlice_AdjustIndices}@anchor{431}
@deffn {C 函式} @ref{c4c,,Py_ssize_t} PySlice_AdjustIndices (Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t step)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.7 版本開始.'
假設序列長度為指定長度，調整開始/結束切片索引。超出範圍的索引會以與處理正常切片一致的方式切除。

回傳切片的長度。永遠成功。不呼叫 Python 程式碼。


在 3.6.1 版被加入.

@end deffn

@menu
* Ellipsis 物件: Ellipsis 物件<2>. 

@end menu

@node Ellipsis 物件<2>,,,切片物件
@anchor{c-api/slice ellipsis-object}@anchor{5226}
@subsubsection Ellipsis 物件


@geindex PyEllipsis_Type (C var)
@anchor{c-api/slice c PyEllipsis_Type}@anchor{4e57}
@deffn {C 變數} @ref{c93,,PyTypeObject} PyEllipsis_Type
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Python @ref{21dd,,Ellipsis} 物件的型別。與 Python 層中的 @ref{a4a,,types.EllipsisType} 相同。
@end deffn

@geindex Py_Ellipsis (C var)
@anchor{c-api/slice c Py_Ellipsis}@anchor{5227}
@deffn {C 變數} @ref{5d7,,PyObject} *Py_Ellipsis

Python @code{Ellipsis} 物件。這個物件沒有方法。就像 @ref{4d67,,Py_None} 一樣，它是一個 @ref{290,,immortal} 單一物件。


在 3.12 版的變更: @ref{5227,,Py_Ellipsis} 為不滅的 (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{509c}
@node MemoryView 物件,弱參照物件<2>,切片物件,其他物件<2>
@anchor{c-api/memoryview doc}@anchor{5228}@anchor{c-api/memoryview id1}@anchor{5229}@anchor{c-api/memoryview translation-repo}@anchor{522a}
@subsubsection MemoryView 物件


A @ref{165,,memoryview} object exposes the C level @ref{260,,buffer interface} as a Python object which can then be passed around like
any other object.

@geindex PyMemoryView_FromObject (C function)
@anchor{c-api/memoryview c PyMemoryView_FromObject}@anchor{4eda}
@deffn {C 函式} @ref{5d7,,PyObject} *PyMemoryView_FromObject (PyObject *obj)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{195a}
@deffn {C 巨集} PyBUF_READ

Flag to request a readonly buffer.
@end deffn

@geindex PyBUF_WRITE (C macro)
@anchor{c-api/memoryview c PyBUF_WRITE}@anchor{195b}
@deffn {C 巨集} PyBUF_WRITE

Flag to request a writable buffer.
@end deffn

@geindex PyMemoryView_FromMemory (C function)
@anchor{c-api/memoryview c PyMemoryView_FromMemory}@anchor{1371}
@deffn {C 函式} @ref{5d7,,PyObject} *PyMemoryView_FromMemory (char *mem, Py_ssize_t size, int flags)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.7 版本開始.'
Create a memoryview object using `mem' as the underlying buffer.
`flags' can be one of @ref{195a,,PyBUF_READ} or @ref{195b,,PyBUF_WRITE}.


在 3.3 版被加入.

@end deffn

@geindex PyMemoryView_FromBuffer (C function)
@anchor{c-api/memoryview c PyMemoryView_FromBuffer}@anchor{95d}
@deffn {C 函式} @ref{5d7,,PyObject} *PyMemoryView_FromBuffer (const Py_buffer *view)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.11 版本開始.'
Create a memoryview object wrapping the given buffer structure `view'.
For simple byte buffers, @ref{1371,,PyMemoryView_FromMemory()} is the preferred
function.
@end deffn

@geindex PyMemoryView_GetContiguous (C function)
@anchor{c-api/memoryview c PyMemoryView_GetContiguous}@anchor{4edb}
@deffn {C 函式} @ref{5d7,,PyObject} *PyMemoryView_GetContiguous (PyObject *obj, int buffertype, char order)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Create a memoryview object to a @ref{2535,,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{195a,,PyBUF_READ} or @ref{195b,,PyBUF_WRITE}.
@end deffn

@geindex PyMemoryView_Check (C function)
@anchor{c-api/memoryview c PyMemoryView_Check}@anchor{522b}
@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{165,,memoryview}.  This
function always succeeds.
@end deffn

@geindex PyMemoryView_GET_BUFFER (C function)
@anchor{c-api/memoryview c PyMemoryView_GET_BUFFER}@anchor{522c}
@deffn {C 函式} @ref{954,,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{522d}
@deffn {C 函式} @ref{5d7,,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{1371,,PyMemoryView_FromMemory()} or @ref{95d,,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)

@node 弱參照物件<2>,Capsules<2>,MemoryView 物件,其他物件<2>
@anchor{c-api/weakref doc}@anchor{522e}@anchor{c-api/weakref translation-repo}@anchor{522f}@anchor{c-api/weakref weak-reference-objects}@anchor{5230}@anchor{c-api/weakref weakrefobjects}@anchor{5070}
@subsubsection 弱參照物件


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{5231}
@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{5232}
@deffn {C 函式} int PyWeakref_CheckRef (PyObject *ob)

Return non-zero if `ob' is a reference object.  This function always succeeds.
@end deffn

@geindex PyWeakref_CheckProxy (C function)
@anchor{c-api/weakref c PyWeakref_CheckProxy}@anchor{5233}
@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{1b06}
@deffn {C 函式} @ref{5d7,,PyObject} *PyWeakref_NewRef (PyObject *ob, PyObject *callback)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{198,,TypeError}.
@end deffn

@geindex PyWeakref_NewProxy (C function)
@anchor{c-api/weakref c PyWeakref_NewProxy}@anchor{4f8b}
@deffn {C 函式} @ref{5d7,,PyObject} *PyWeakref_NewProxy (PyObject *ob, PyObject *callback)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 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{198,,TypeError}.
@end deffn

@geindex PyWeakref_GetRef (C function)
@anchor{c-api/weakref c PyWeakref_GetRef}@anchor{3dd}
@deffn {C 函式} int PyWeakref_GetRef (PyObject *ref, PyObject **pobj)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.13 版本開始.'
Get a @ref{5da,,strong reference} to the referenced object from a weak
reference, `ref', into `*pobj'.


@itemize *

@item 
On success, set `*pobj' to a new @ref{5da,,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


在 3.13 版被加入.

@end deffn

@geindex PyWeakref_GetObject (C function)
@anchor{c-api/weakref c PyWeakref_GetObject}@anchor{3db}
@deffn {C 函式} @ref{5d7,,PyObject} *PyWeakref_GetObject (PyObject *ref)
`回傳值：借用參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return a @ref{3d5,,borrowed reference} to the referenced object from a weak
reference, `ref'.  If the referent is no longer live, returns @code{Py_None}.

@cartouche
@quotation 備註 
This function returns a @ref{3d5,,borrowed reference} to the referenced object.
This means that you should always call @ref{788,,Py_INCREF()} on the object
except when it cannot be destroyed before the last usage of the borrowed
reference.
@end quotation
@end cartouche


Deprecated since version 3.13, will be removed in version 3.15: Use @ref{3dd,,PyWeakref_GetRef()} instead.

@end deffn

@geindex PyWeakref_GET_OBJECT (C function)
@anchor{c-api/weakref c PyWeakref_GET_OBJECT}@anchor{3dc}
@deffn {C 函式} @ref{5d7,,PyObject} *PyWeakref_GET_OBJECT (PyObject *ref)
`回傳值：借用參照。'
Similar to @ref{3db,,PyWeakref_GetObject()}, but does no error checking.


Deprecated since version 3.13, will be removed in version 3.15: Use @ref{3dd,,PyWeakref_GetRef()} instead.

@end deffn

@geindex PyWeakref_IsDead (C function)
@anchor{c-api/weakref c PyWeakref_IsDead}@anchor{184c}
@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.


在 3.14 版被加入.

@end deffn

@geindex PyObject_ClearWeakRefs (C function)
@anchor{c-api/weakref c PyObject_ClearWeakRefs}@anchor{78f}
@deffn {C 函式} void PyObject_ClearWeakRefs (PyObject *object)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
This function is called by the @ref{4d84,,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{18ee}
@deffn {C 函式} void PyUnstable_Object_ClearWeakRefsNoCallbacks (PyObject *object)

@cartouche
@quotation 這是 不穩定 API，它可能在小版本發布中沒有任何警告地被變更。 `這是 @ref{762,,不穩定 API}，它可能在小版本發布中沒有任何警告地被變更。'
@end quotation
@end cartouche

Clears the weakrefs for `object' without calling the callbacks.

This function is called by the @ref{4d84,,tp_dealloc} handler
for types with finalizers (i.e., @ref{11f8,,__del__()}).  The handler for
those objects first calls @ref{78f,,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{78f,,PyObject_ClearWeakRefs()} to clear weakrefs instead of this function.


在 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>,Frame 物件,弱參照物件<2>,其他物件<2>
@anchor{c-api/capsule doc}@anchor{5234}@anchor{c-api/capsule capsules}@anchor{28a1}@anchor{c-api/capsule id1}@anchor{5235}@anchor{c-api/capsule translation-repo}@anchor{5236}
@subsubsection Capsules


@geindex object（物件）;Capsule

Refer to @ref{1555,,Providing a C API for an Extension Module} for more information on using these objects.


在 3.1 版被加入.


@geindex PyCapsule (C type)
@anchor{c-api/capsule c PyCapsule}@anchor{1473}
@deffn {C 型別} type PyCapsule

This subtype of @ref{5d7,,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_Destructor (C type)
@anchor{c-api/capsule c PyCapsule_Destructor}@anchor{4e2d}
@deffn {C 型別} type PyCapsule_Destructor
` 為 @ref{76e,,穩定 ABI 的一部分}.'
The type of a destructor callback for a capsule.  Defined as:

@example
typedef void (*PyCapsule_Destructor)(PyObject *);
@end example

See @ref{4d8b,,PyCapsule_New()} for the semantics of PyCapsule_Destructor
callbacks.
@end deffn

@geindex PyCapsule_CheckExact (C function)
@anchor{c-api/capsule c PyCapsule_CheckExact}@anchor{5237}
@deffn {C 函式} int PyCapsule_CheckExact (PyObject *p)

Return true if its argument is a @ref{1473,,PyCapsule}.  This function always
succeeds.
@end deffn

@geindex PyCapsule_New (C function)
@anchor{c-api/capsule c PyCapsule_New}@anchor{4d8b}
@deffn {C 函式} @ref{5d7,,PyObject} *PyCapsule_New (void *pointer, const char *name, PyCapsule_Destructor destructor)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
Create a @ref{1473,,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{1b24,,PyCapsule_Import()}.
@end deffn

@geindex PyCapsule_GetPointer (C function)
@anchor{c-api/capsule c PyCapsule_GetPointer}@anchor{4e31}
@deffn {C 函式} void *PyCapsule_GetPointer (PyObject *capsule, const char *name)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Retrieve the `pointer' stored in the capsule.  On failure, set an exception
and return @code{NULL}.

The `name' parameter must compare exactly to the name stored in the capsule.
If the name stored in the capsule is @code{NULL}, the `name' passed in must also
be @code{NULL}.  Python uses the C function @code{strcmp()} to compare capsule
names.
@end deffn

@geindex PyCapsule_GetDestructor (C function)
@anchor{c-api/capsule c PyCapsule_GetDestructor}@anchor{4e2f}
@deffn {C 函式} @ref{4e2d,,PyCapsule_Destructor} PyCapsule_GetDestructor (PyObject *capsule)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return the current destructor stored in the capsule.  On failure, set an
exception and return @code{NULL}.

It is legal for a capsule to have a @code{NULL} destructor.  This makes a @code{NULL}
return code somewhat ambiguous; use @ref{1554,,PyCapsule_IsValid()} or
@ref{1ba7,,PyErr_Occurred()} to disambiguate.
@end deffn

@geindex PyCapsule_GetContext (C function)
@anchor{c-api/capsule c PyCapsule_GetContext}@anchor{4e2e}
@deffn {C 函式} void *PyCapsule_GetContext (PyObject *capsule)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return the current context stored in the capsule.  On failure, set an
exception and return @code{NULL}.

It is legal for a capsule to have a @code{NULL} context.  This makes a @code{NULL}
return code somewhat ambiguous; use @ref{1554,,PyCapsule_IsValid()} or
@ref{1ba7,,PyErr_Occurred()} to disambiguate.
@end deffn

@geindex PyCapsule_GetName (C function)
@anchor{c-api/capsule c PyCapsule_GetName}@anchor{4e30}
@deffn {C 函式} const char *PyCapsule_GetName (PyObject *capsule)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return the current name stored in the capsule.  On failure, set an exception
and return @code{NULL}.

It is legal for a capsule to have a @code{NULL} name.  This makes a @code{NULL} return
code somewhat ambiguous; use @ref{1554,,PyCapsule_IsValid()} or
@ref{1ba7,,PyErr_Occurred()} to disambiguate.
@end deffn

@geindex PyCapsule_Import (C function)
@anchor{c-api/capsule c PyCapsule_Import}@anchor{1b24}
@deffn {C 函式} void *PyCapsule_Import (const char *name, int no_block)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Import a pointer to a C object from a capsule attribute in a module.  The
`name' parameter should specify the full name to the attribute, as in
@code{module.attribute}.  The `name' stored in the capsule must match this
string exactly.

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{3da,,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{1554}
@deffn {C 函式} int PyCapsule_IsValid (PyObject *capsule, const char *name)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Determines whether or not `capsule' is a valid capsule.  A valid capsule is
non-@code{NULL}, passes @ref{5237,,PyCapsule_CheckExact()}, has a non-@code{NULL} pointer
stored in it, and its internal name matches the `name' parameter.  (See
@ref{4e31,,PyCapsule_GetPointer()} for information on how capsule names are
compared.)

In other words, if @ref{1554,,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{4e32}
@deffn {C 函式} int PyCapsule_SetContext (PyObject *capsule, void *context)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Set the context pointer inside `capsule' to `context'.

Return @code{0} on success.  Return nonzero and set an exception on failure.
@end deffn

@geindex PyCapsule_SetDestructor (C function)
@anchor{c-api/capsule c PyCapsule_SetDestructor}@anchor{4e33}
@deffn {C 函式} int PyCapsule_SetDestructor (PyObject *capsule, PyCapsule_Destructor destructor)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Set the destructor inside `capsule' to `destructor'.

Return @code{0} on success.  Return nonzero and set an exception on failure.
@end deffn

@geindex PyCapsule_SetName (C function)
@anchor{c-api/capsule c PyCapsule_SetName}@anchor{4e34}
@deffn {C 函式} int PyCapsule_SetName (PyObject *capsule, const char *name)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Set the name inside `capsule' to `name'.  If non-@code{NULL}, the name must
outlive the capsule.  If the previous `name' stored in the capsule was not
@code{NULL}, no attempt is made to free it.

Return @code{0} on success.  Return nonzero and set an exception on failure.
@end deffn

@geindex PyCapsule_SetPointer (C function)
@anchor{c-api/capsule c PyCapsule_SetPointer}@anchor{4e35}
@deffn {C 函式} int PyCapsule_SetPointer (PyObject *capsule, void *pointer)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Set the void pointer inside `capsule' to `pointer'.  The pointer may not be
@code{NULL}.

Return @code{0} on success.  Return nonzero and set an exception on failure.
@end deffn

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node Frame 物件,產生器 Generator 物件,Capsules<2>,其他物件<2>
@anchor{c-api/frame doc}@anchor{5238}@anchor{c-api/frame frame-objects}@anchor{5239}@anchor{c-api/frame translation-repo}@anchor{523a}
@subsubsection Frame 物件


@geindex PyFrameObject (C type)
@anchor{c-api/frame c PyFrameObject}@anchor{984}
@deffn {C 型別} type PyFrameObject
` 為 @ref{76e,,受限 API 的一部分} （做為一個不透明結構 (opaque struct)）.'
用來描述 frame 物件的 C 結構。

在這個結構中沒有公開的成員。


在 3.11 版的變更: The members of this structure were removed from the public C API.
Refer to the @ref{983,,What's New entry}
for details.

@end deffn

The @ref{1a78,,PyEval_GetFrame()} and @ref{989,,PyThreadState_GetFrame()} functions
can be used to get a frame object.

另請參閱 @ref{5045,,Reflection}。

@geindex PyFrame_Type (C var)
@anchor{c-api/frame c PyFrame_Type}@anchor{982}
@deffn {C 變數} @ref{c93,,PyTypeObject} PyFrame_Type

The type of frame objects.
It is the same object as @ref{1b09,,types.FrameType} in the Python layer.


在 3.11 版的變更: Previously, this type was only available after including
@code{<frameobject.h>}.

@end deffn

@geindex PyFrame_Check (C function)
@anchor{c-api/frame c PyFrame_Check}@anchor{980}
@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{981}
@deffn {C 函式} @ref{984,,PyFrameObject} *PyFrame_GetBack (PyFrameObject *frame)
`回傳值：新的參照。'
Get the `frame' next outer frame.

Return a @ref{5da,,strong reference}, or @code{NULL} if `frame' has no outer
frame.


在 3.9 版被加入.

@end deffn

@geindex PyFrame_GetBuiltins (C function)
@anchor{c-api/frame c PyFrame_GetBuiltins}@anchor{967}
@deffn {C 函式} @ref{5d7,,PyObject} *PyFrame_GetBuiltins (PyFrameObject *frame)
`回傳值：新的參照。'
取得 `frame' 的 @ref{224c,,f_builtins} 屬性。

回傳 @ref{5da,,strong reference}。結果不能為 @code{NULL}。


在 3.11 版被加入.

@end deffn

@geindex PyFrame_GetCode (C function)
@anchor{c-api/frame c PyFrame_GetCode}@anchor{985}
@deffn {C 函式} @ref{973,,PyCodeObject} *PyFrame_GetCode (PyFrameObject *frame)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.10 版本開始.'
Get the `frame' code.

回傳 @ref{5da,,strong reference}。

The result (frame code) cannot be @code{NULL}.


在 3.9 版被加入.

@end deffn

@geindex PyFrame_GetGenerator (C function)
@anchor{c-api/frame c PyFrame_GetGenerator}@anchor{968}
@deffn {C 函式} @ref{5d7,,PyObject} *PyFrame_GetGenerator (PyFrameObject *frame)
`回傳值：新的參照。'
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}.

回傳 @ref{5da,,strong reference} 或 @code{NULL}。


在 3.11 版被加入.

@end deffn

@geindex PyFrame_GetGlobals (C function)
@anchor{c-api/frame c PyFrame_GetGlobals}@anchor{969}
@deffn {C 函式} @ref{5d7,,PyObject} *PyFrame_GetGlobals (PyFrameObject *frame)
`回傳值：新的參照。'
取得 `frame' 的 @ref{224b,,f_globals} 屬性。

回傳 @ref{5da,,strong reference}。結果不能為 @code{NULL}。


在 3.11 版被加入.

@end deffn

@geindex PyFrame_GetLasti (C function)
@anchor{c-api/frame c PyFrame_GetLasti}@anchor{96a}
@deffn {C 函式} int PyFrame_GetLasti (PyFrameObject *frame)

取得 `frame' 的 @ref{a7f,,f_lasti} 屬性。

如果 @code{frame.f_lasti} 是 @code{None} 則回傳 -1。


在 3.11 版被加入.

@end deffn

@geindex PyFrame_GetVar (C function)
@anchor{c-api/frame c PyFrame_GetVar}@anchor{782}
@deffn {C 函式} @ref{5d7,,PyObject} *PyFrame_GetVar (PyFrameObject *frame, PyObject *name)
`回傳值：新的參照。'
取得 `frame' 的變數 `name'。


@itemize *

@item 
在成功時回傳變數值的 @ref{5da,,strong reference}。

@item 
如果變數不存在，則引發 @ref{450,,NameError} 並回傳 @code{NULL}。

@item 
在錯誤時引發例外並回傳 @code{NULL}。
@end itemize

`name' 的型別必須是 @ref{169,,str}。


在 3.12 版被加入.

@end deffn

@geindex PyFrame_GetVarString (C function)
@anchor{c-api/frame c PyFrame_GetVarString}@anchor{783}
@deffn {C 函式} @ref{5d7,,PyObject} *PyFrame_GetVarString (PyFrameObject *frame, const char *name)
`回傳值：新的參照。'
Similar to @ref{782,,PyFrame_GetVar()}, but the variable name is a C string
encoded in UTF-8.


在 3.12 版被加入.

@end deffn

@geindex PyFrame_GetLocals (C function)
@anchor{c-api/frame c PyFrame_GetLocals}@anchor{659}
@deffn {C 函式} @ref{5d7,,PyObject} *PyFrame_GetLocals (PyFrameObject *frame)
`回傳值：新的參照。'
Get the `frame''s @ref{4a0,,f_locals} attribute.
If the frame refers to an @ref{49c,,optimized scope}, this returns a
write-through proxy object that allows modifying the locals.
In all other cases (classes, modules, @ref{49d,,exec()}, @ref{49e,,eval()}) it returns
the mapping representing the frame locals directly (as described for
@ref{469,,locals()}).

回傳 @ref{5da,,strong reference}。


在 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{523b,,PyFrameLocalsProxy_Type}.

@end deffn

@geindex PyFrame_GetLineNumber (C function)
@anchor{c-api/frame c PyFrame_GetLineNumber}@anchor{986}
@deffn {C 函式} int PyFrame_GetLineNumber (PyFrameObject *frame)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.10 版本開始.'
Return the line number that `frame' is currently executing.
@end deffn

@menu
* Frame Locals Proxies:: 
* Internal Frames:: 

@end menu

@node Frame Locals Proxies,Internal Frames,,Frame 物件
@anchor{c-api/frame frame-locals-proxies}@anchor{523c}
@subsubsection Frame Locals Proxies



在 3.13 版被加入.


The @ref{4a0,,f_locals} attribute on a @ref{8e7,,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{523b}
@deffn {C 變數} @ref{c93,,PyTypeObject} PyFrameLocalsProxy_Type

The type of frame @ref{469,,locals()} proxy objects.
@end deffn

@geindex PyFrameLocalsProxy_Check (C function)
@anchor{c-api/frame c PyFrameLocalsProxy_Check}@anchor{523d}
@deffn {C 函式} int PyFrameLocalsProxy_Check (PyObject *obj)

Return non-zero if `obj' is a frame @ref{469,,locals()} proxy.
@end deffn

@node Internal Frames,,Frame Locals Proxies,Frame 物件
@anchor{c-api/frame internal-frames}@anchor{523e}
@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{18d3}
@deffn {C 結構} struct _PyInterpreterFrame

The interpreter's internal frame representation.


在 3.11 版被加入.

@end deffn

@geindex PyUnstable_InterpreterFrame_GetCode (C function)
@anchor{c-api/frame c PyUnstable_InterpreterFrame_GetCode}@anchor{523f}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnstable_InterpreterFrame_GetCode (struct _PyInterpreterFrame *frame);

@cartouche
@quotation 這是 不穩定 API，它可能在小版本發布中沒有任何警告地被變更。 `這是 @ref{762,,不穩定 API}，它可能在小版本發布中沒有任何警告地被變更。'
@end quotation
@end cartouche

@quotation

Return a @ref{5da,,strong reference} to the code object for the frame.
@end quotation


在 3.12 版被加入.

@end deffn

@geindex PyUnstable_InterpreterFrame_GetLasti (C function)
@anchor{c-api/frame c PyUnstable_InterpreterFrame_GetLasti}@anchor{5240}
@deffn {C 函式} int PyUnstable_InterpreterFrame_GetLasti (struct _PyInterpreterFrame *frame);

@cartouche
@quotation 這是 不穩定 API，它可能在小版本發布中沒有任何警告地被變更。 `這是 @ref{762,,不穩定 API}，它可能在小版本發布中沒有任何警告地被變更。'
@end quotation
@end cartouche

Return the byte offset into the last executed instruction.


在 3.12 版被加入.

@end deffn

@geindex PyUnstable_InterpreterFrame_GetLine (C function)
@anchor{c-api/frame c PyUnstable_InterpreterFrame_GetLine}@anchor{5241}
@deffn {C 函式} int PyUnstable_InterpreterFrame_GetLine (struct _PyInterpreterFrame *frame);

@cartouche
@quotation 這是 不穩定 API，它可能在小版本發布中沒有任何警告地被變更。 `這是 @ref{762,,不穩定 API}，它可能在小版本發布中沒有任何警告地被變更。'
@end quotation
@end cartouche

Return the currently executing line number, or -1 if there is no line number.


在 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 物件,Coroutine（協程）物件,Frame 物件,其他物件<2>
@anchor{c-api/gen doc}@anchor{5242}@anchor{c-api/gen gen-objects}@anchor{5243}@anchor{c-api/gen generator-objects}@anchor{5244}@anchor{c-api/gen translation-repo}@anchor{5245}
@subsubsection 產生器 (Generator) 物件


產生器物件是 Python 用來實現產生器疊代器 (generator iterator) 的物件。它們通常透過疊代會產生值的函式來建立，而不是顯式呼叫 @ref{5246,,PyGen_New()} 或 @ref{5247,,PyGen_NewWithQualName()}。

@geindex PyGenObject (C type)
@anchor{c-api/gen c PyGenObject}@anchor{5248}
@deffn {C 型別} type PyGenObject

用於產生器物件的 C 結構。
@end deffn

@geindex PyGen_Type (C var)
@anchor{c-api/gen c PyGen_Type}@anchor{5249}
@deffn {C 變數} @ref{c93,,PyTypeObject} PyGen_Type

與產生器物件對應的型別物件。
@end deffn

@geindex PyGen_Check (C function)
@anchor{c-api/gen c PyGen_Check}@anchor{524a}
@deffn {C 函式} int PyGen_Check (PyObject *ob)

如果 `ob' 是一個產生器 (generator) 物件則回傳真值；`ob' 必須不為 @code{NULL}。此函式總是會成功執行。
@end deffn

@geindex PyGen_CheckExact (C function)
@anchor{c-api/gen c PyGen_CheckExact}@anchor{524b}
@deffn {C 函式} int PyGen_CheckExact (PyObject *ob)

如果 `ob' 的型別是 @ref{5249,,PyGen_Type} 則回傳真值；`ob' 必須不為 @code{NULL}。此函式總是會成功執行。
@end deffn

@geindex PyGen_New (C function)
@anchor{c-api/gen c PyGen_New}@anchor{5246}
@deffn {C 函式} @ref{5d7,,PyObject} *PyGen_New (PyFrameObject *frame)
`回傳值：新的參照。'
基於 `frame' 物件建立並回傳一個新的產生器物件。此函式會取走一個對 `frame' 的參照 (reference)。引數必須不為 @code{NULL}。
@end deffn

@geindex PyGen_NewWithQualName (C function)
@anchor{c-api/gen c PyGen_NewWithQualName}@anchor{5247}
@deffn {C 函式} @ref{5d7,,PyObject} *PyGen_NewWithQualName (PyFrameObject *frame, PyObject *name, PyObject *qualname)
`回傳值：新的參照。'
基於 `frame' 物件建立並回傳一個新的產生器物件，其中 @code{__name__} 和 @code{__qualname__} 設為 `name' 和 `qualname'。此函式會取走一個對 `frame' 的參照。`frame' 引數必須不為 @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 Coroutine（協程）物件,情境變數物件（Context Variables Objects）,產生器 Generator 物件,其他物件<2>
@anchor{c-api/coro doc}@anchor{524c}@anchor{c-api/coro coro-objects}@anchor{10cb}@anchor{c-api/coro coroutine-objects}@anchor{524d}@anchor{c-api/coro translation-repo}@anchor{524e}
@subsubsection Coroutine（協程）物件



在 3.5 版被加入.


Coroutine 物件是那些以 @code{async} 關鍵字來宣告的函式所回傳的物件。

@geindex PyCoroObject (C type)
@anchor{c-api/coro c PyCoroObject}@anchor{524f}
@deffn {C 型別} type PyCoroObject

用於 coroutine 物件的 C 結構。
@end deffn

@geindex PyCoro_Type (C var)
@anchor{c-api/coro c PyCoro_Type}@anchor{5250}
@deffn {C 變數} @ref{c93,,PyTypeObject} PyCoro_Type

與 coroutine 物件對應的型別物件。
@end deffn

@geindex PyCoro_CheckExact (C function)
@anchor{c-api/coro c PyCoro_CheckExact}@anchor{5251}
@deffn {C 函式} int PyCoro_CheckExact (PyObject *ob)

如果 `ob' 的型別是 @ref{5250,,PyCoro_Type} 則回傳真值；`ob' 必須不為 @code{NULL}。此函式總是會執行成功。
@end deffn

@geindex PyCoro_New (C function)
@anchor{c-api/coro c PyCoro_New}@anchor{5252}
@deffn {C 函式} @ref{5d7,,PyObject} *PyCoro_New (PyFrameObject *frame, PyObject *name, PyObject *qualname)
`回傳值：新的參照。'
基於 `frame' 物件來建立並回傳一個新的 coroutine 物件，其中 @code{__name__} 和 @code{__qualname__} 被設為 `name' 和 `qualname'。此函式會取得一個對 `frame' 的參照 (reference)。`frame' 引數必須不為 @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）,DateTime 物件,Coroutine（協程）物件,其他物件<2>
@anchor{c-api/contextvars doc}@anchor{5253}@anchor{c-api/contextvars context-variables-objects}@anchor{5254}@anchor{c-api/contextvars contextvarsobjects}@anchor{ce7}@anchor{c-api/contextvars translation-repo}@anchor{5255}
@subsubsection 情境變數物件（Context Variables Objects）

@anchor{c-api/contextvars contextvarsobjects-pointertype-change}@anchor{e1a}

在 3.7 版被加入.



在 3.7.1 版的變更: 

@cartouche
@quotation 備註 
在 Python 3.7.1 中所有情境變數 C API 的簽名都被`改為'使用 @ref{5d7,,PyObject} 指標，而不是 @ref{5256,,PyContext}、@ref{5257,,PyContextVar} 或 @ref{5258,,PyContextToken}，例如：

@example
// 在 3.7.0：
PyContext *PyContext_New(void);

// 在 3.7.1+：
PyObject *PyContext_New(void);
@end example

更多細節請見 bpo-34762@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34762}。
@end quotation
@end cartouche


本節詳述 @ref{28,,contextvars} 模組的公開 C API。

@geindex PyContext (C type)
@anchor{c-api/contextvars c PyContext}@anchor{5256}
@deffn {C 型別} type PyContext

用來代表 @ref{177,,contextvars.Context} 物件的 C 結構。
@end deffn

@geindex PyContextVar (C type)
@anchor{c-api/contextvars c PyContextVar}@anchor{5257}
@deffn {C 型別} type PyContextVar

用來代表 @ref{17f0,,contextvars.ContextVar} 物件的 C 結構。
@end deffn

@geindex PyContextToken (C type)
@anchor{c-api/contextvars c PyContextToken}@anchor{5258}
@deffn {C 型別} type PyContextToken

用來代表 @ref{1e2,,contextvars.Token} 物件的 C 結構。
@end deffn

@geindex PyContext_Type (C var)
@anchor{c-api/contextvars c PyContext_Type}@anchor{5259}
@deffn {C 變數} @ref{c93,,PyTypeObject} PyContext_Type

代表 `context' 型別的型別物件。
@end deffn

@geindex PyContextVar_Type (C var)
@anchor{c-api/contextvars c PyContextVar_Type}@anchor{525a}
@deffn {C 變數} @ref{c93,,PyTypeObject} PyContextVar_Type

代表 `情境變數' 型別的型別物件。
@end deffn

@geindex PyContextToken_Type (C var)
@anchor{c-api/contextvars c PyContextToken_Type}@anchor{525b}
@deffn {C 變數} @ref{c93,,PyTypeObject} PyContextToken_Type

代表 `情境變數 token' 型別的型別物件。
@end deffn

型別檢查巨集：

@geindex PyContext_CheckExact (C function)
@anchor{c-api/contextvars c PyContext_CheckExact}@anchor{525c}
@deffn {C 函式} int PyContext_CheckExact (PyObject *o)

如果 `o' 的型別為 @ref{5259,,PyContext_Type} 則回傳 true。`o' 不得為 @code{NULL}。此函式一定會成功回傳。
@end deffn

@geindex PyContextVar_CheckExact (C function)
@anchor{c-api/contextvars c PyContextVar_CheckExact}@anchor{525d}
@deffn {C 函式} int PyContextVar_CheckExact (PyObject *o)

如果 `o' 的類型為 @ref{525a,,PyContextVar_Type} 則回傳 true。`o' 不得為 @code{NULL}。此函式一定會成功回傳。
@end deffn

@geindex PyContextToken_CheckExact (C function)
@anchor{c-api/contextvars c PyContextToken_CheckExact}@anchor{525e}
@deffn {C 函式} int PyContextToken_CheckExact (PyObject *o)

如果 `o' 的類型為 @ref{525b,,PyContextToken_Type} 則回傳 true。 `o' 不得為 @code{NULL}。此函式一定會成功回傳。
@end deffn

情境物件管理函式：

@geindex PyContext_New (C function)
@anchor{c-api/contextvars c PyContext_New}@anchor{525f}
@deffn {C 函式} @ref{5d7,,PyObject} *PyContext_New (void)
`回傳值：新的參照。'
建立一個新的空的情境物件。 如果發生錯誤，則回傳 @code{NULL}。
@end deffn

@geindex PyContext_Copy (C function)
@anchor{c-api/contextvars c PyContext_Copy}@anchor{5260}
@deffn {C 函式} @ref{5d7,,PyObject} *PyContext_Copy (PyObject *ctx)
`回傳值：新的參照。'
建立傳入的 `ctx' 情境物件的淺層複製 (shallow copy)。如果發生錯誤，則回傳 @code{NULL}。
@end deffn

@geindex PyContext_CopyCurrent (C function)
@anchor{c-api/contextvars c PyContext_CopyCurrent}@anchor{5261}
@deffn {C 函式} @ref{5d7,,PyObject} *PyContext_CopyCurrent (void)
`回傳值：新的參照。'
建立目前執行緒上的情境的淺層複製。如果發生錯誤，則回傳 @code{NULL}。
@end deffn

@geindex PyContext_Enter (C function)
@anchor{c-api/contextvars c PyContext_Enter}@anchor{5262}
@deffn {C 函式} int PyContext_Enter (PyObject *ctx)

設定 `ctx' 為目前執行緒上的目前情境。成功時回傳 @code{0}，錯誤時回傳 @code{-1}。
@end deffn

@geindex PyContext_Exit (C function)
@anchor{c-api/contextvars c PyContext_Exit}@anchor{5263}
@deffn {C 函式} int PyContext_Exit (PyObject *ctx)

關閉 `ctx' 情境，並將目前執行緒的目前情境設回之前的情境。 成功時回傳 @code{0}，錯誤時回傳 @code{-1}。
@end deffn

@geindex PyContext_AddWatcher (C function)
@anchor{c-api/contextvars c PyContext_AddWatcher}@anchor{18eb}
@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{18ec,,PyContext_ClearWatcher()}.
In case of error (e.g. no more watcher IDs available),
return @code{-1} and set an exception.


在 3.14 版被加入.

@end deffn

@geindex PyContext_ClearWatcher (C function)
@anchor{c-api/contextvars c PyContext_ClearWatcher}@anchor{18ec}
@deffn {C 函式} int PyContext_ClearWatcher (int watcher_id)

Clear watcher identified by `watcher_id' previously returned from
@ref{18eb,,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.)


在 3.14 版被加入.

@end deffn

@geindex PyContextEvent (C type)
@anchor{c-api/contextvars c PyContextEvent}@anchor{5264}
@deffn {C 型別} type PyContextEvent

Enumeration of possible context object watcher events:


@itemize -

@item 
@code{Py_CONTEXT_SWITCHED}: The @ref{18cb,,current context} has switched to a
different context.  The object passed to the watch callback is the
now-current @ref{177,,contextvars.Context} object, or None if no context is
current.
@end itemize


在 3.14 版被加入.

@end deffn

@geindex PyContext_WatchCallback (C type)
@anchor{c-api/contextvars c PyContext_WatchCallback}@anchor{5265}
@deffn {C 型別} typedef int (*PyContext_WatchCallback)(@ref{5264,,PyContextEvent} event, @ref{5d7,,PyObject} *obj)

Context object watcher callback function.  The object passed to the callback
is event-specific; see @ref{5264,,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{5e9,,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.


在 3.14 版被加入.

@end deffn

情境變數函式：

@geindex PyContextVar_New (C function)
@anchor{c-api/contextvars c PyContextVar_New}@anchor{5266}
@deffn {C 函式} @ref{5d7,,PyObject} *PyContextVar_New (const char *name, PyObject *def)
`回傳值：新的參照。'
建立一個新的 @code{ContextVar} 物件。`name' 參數用於自我檢查（introspection）和除錯目的。`def' 參數指定情境變數的預設值，亦可用 @code{NULL} 表示沒有預設值。 如果發生錯誤，此函式會回傳 @code{NULL}。
@end deffn

@geindex PyContextVar_Get (C function)
@anchor{c-api/contextvars c PyContextVar_Get}@anchor{5267}
@deffn {C 函式} int PyContextVar_Get (PyObject *var, PyObject *default_value, PyObject **value)

取得情境變數的值。如果在查找過程中發生錯誤則回傳 @code{-1}，如果沒有發生錯誤則無論是否找到值都會回傳 @code{0}。

如果找到情境變數，`value' 將會是指向它的指標。如果 `沒有' 找到情境變數，`value' 將會指到：


@itemize -

@item 
`default_value' 預設值，但前提是預設值不是 @code{NULL}；

@item 
`var' 的預設值，但前提是預設值不是 @code{NULL}；

@item 
@code{NULL}
@end itemize

除了 @code{NULL} 之外，此函式會回傳一個新的參照（reference）。
@end deffn

@geindex PyContextVar_Set (C function)
@anchor{c-api/contextvars c PyContextVar_Set}@anchor{5268}
@deffn {C 函式} @ref{5d7,,PyObject} *PyContextVar_Set (PyObject *var, PyObject *value)
`回傳值：新的參照。'
在目前的情境中將 `var' 的值設為 `value'。會回傳一個用來代表此變更的新 token 物件，如果發生錯誤則回傳 @code{NULL}。
@end deffn

@geindex PyContextVar_Reset (C function)
@anchor{c-api/contextvars c PyContextVar_Reset}@anchor{5269}
@deffn {C 函式} int PyContextVar_Reset (PyObject *var, PyObject *token)

將 `var' 情境變數的狀態設回之前的狀態，亦即上一次回傳 token 的 @ref{5268,,PyContextVar_Set()} 被呼叫前的狀態。此函式在成功時回傳 @code{0}，錯誤時回傳 @code{-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 DateTime 物件,型別提示物件,情境變數物件（Context Variables Objects）,其他物件<2>
@anchor{c-api/datetime doc}@anchor{526a}@anchor{c-api/datetime datetime-objects}@anchor{526b}@anchor{c-api/datetime datetimeobjects}@anchor{504e}@anchor{c-api/datetime translation-repo}@anchor{526c}
@subsubsection DateTime 物件


@ref{34,,datetime} 模組提供各種日期和時間物件。在使用任何這些函式之前，必須將標頭檔 @code{datetime.h} 引入於原始碼中（請注意，@code{Python.h} 並無引入該標頭檔），且巨集 @code{PyDateTime_IMPORT} 必須被叫用，而這通常作為模組初始化函式的一部分。該巨集將指向 C 結構的指標放入靜態變數 @code{PyDateTimeAPI} 中，該變數會被以下巨集使用。

@geindex PyDateTime_Date (C type)
@anchor{c-api/datetime c PyDateTime_Date}@anchor{526d}
@deffn {C 型別} type PyDateTime_Date

此 @ref{5d7,,PyObject} 子型別代表 Python date 物件
@end deffn

@geindex PyDateTime_DateTime (C type)
@anchor{c-api/datetime c PyDateTime_DateTime}@anchor{526e}
@deffn {C 型別} type PyDateTime_DateTime

此 @ref{5d7,,PyObject} 子型別代表 Python datetime 物件
@end deffn

@geindex PyDateTime_Time (C type)
@anchor{c-api/datetime c PyDateTime_Time}@anchor{526f}
@deffn {C 型別} type PyDateTime_Time

此 @ref{5d7,,PyObject} 子型別代表 Python time 物件
@end deffn

@geindex PyDateTime_Delta (C type)
@anchor{c-api/datetime c PyDateTime_Delta}@anchor{5270}
@deffn {C 型別} type PyDateTime_Delta

此 @ref{5d7,,PyObject} 子型別代表兩個 datetime 物件的差值
@end deffn

@geindex PyDateTime_DateType (C var)
@anchor{c-api/datetime c PyDateTime_DateType}@anchor{5271}
@deffn {C 變數} @ref{c93,,PyTypeObject} PyDateTime_DateType

此 @ref{c93,,PyTypeObject} 實例代表 Python date 型別，與 Python layer 中的 @ref{1fa,,datetime.date} 是同一物件
@end deffn

@geindex PyDateTime_DateTimeType (C var)
@anchor{c-api/datetime c PyDateTime_DateTimeType}@anchor{5272}
@deffn {C 變數} @ref{c93,,PyTypeObject} PyDateTime_DateTimeType

此 @ref{c93,,PyTypeObject} 實例代表 Python datetime 型別，與 Python layer 中的 @ref{4dd,,datetime.datetime} 是同一物件
@end deffn

@geindex PyDateTime_TimeType (C var)
@anchor{c-api/datetime c PyDateTime_TimeType}@anchor{5273}
@deffn {C 變數} @ref{c93,,PyTypeObject} PyDateTime_TimeType

此 @ref{c93,,PyTypeObject} 實例代表 Python time 型別，與 Python layer 中的 @ref{277c,,datetime.datetime.time} 是同一物件
@end deffn

@geindex PyDateTime_DeltaType (C var)
@anchor{c-api/datetime c PyDateTime_DeltaType}@anchor{5274}
@deffn {C 變數} @ref{c93,,PyTypeObject} PyDateTime_DeltaType

此 @ref{c93,,PyTypeObject} 實例代表 Python 兩個 datetime 物件的型別，與 Python layer 中的 @ref{bba,,datetime.timedelta} 是同一物件
@end deffn

@geindex PyDateTime_TZInfoType (C var)
@anchor{c-api/datetime c PyDateTime_TZInfoType}@anchor{5275}
@deffn {C 變數} @ref{c93,,PyTypeObject} PyDateTime_TZInfoType

此 @ref{c93,,PyTypeObject} 實例代表 Python 時區資訊型別，與 Python layer 中的 @ref{7ef,,datetime.tzinfo} 是同一物件
@end deffn

用於存取 UTC 單例 (singleton) 的巨集：

@geindex PyDateTime_TimeZone_UTC (C var)
@anchor{c-api/datetime c PyDateTime_TimeZone_UTC}@anchor{db7}
@deffn {C 變數} @ref{5d7,,PyObject} *PyDateTime_TimeZone_UTC

回傳表示 UTC 的時區單例，是與 @ref{820,,datetime.timezone.utc} 相同的物件。


在 3.7 版被加入.

@end deffn

型別檢查巨集：

@geindex PyDate_Check (C function)
@anchor{c-api/datetime c PyDate_Check}@anchor{5276}
@deffn {C 函式} int PyDate_Check (PyObject *ob)

如果 `ob' 的型別為 @ref{5271,,PyDateTime_DateType} 或 @code{PyDateTime_DateType} 的子型別，則回傳 true。 `ob' 不得為 @code{NULL}。這個函式一定會執行成功。
@end deffn

@geindex PyDate_CheckExact (C function)
@anchor{c-api/datetime c PyDate_CheckExact}@anchor{5277}
@deffn {C 函式} int PyDate_CheckExact (PyObject *ob)

如果 `ob' 的型別為 @ref{5271,,PyDateTime_DateType}，則回傳 true。 `ob' 不得為 @code{NULL}。這個函式一定會執行成功。
@end deffn

@geindex PyDateTime_Check (C function)
@anchor{c-api/datetime c PyDateTime_Check}@anchor{5278}
@deffn {C 函式} int PyDateTime_Check (PyObject *ob)

如果 `ob' 的型別為 @ref{5272,,PyDateTime_DateTimeType} 或 @code{PyDateTime_DateTimeType} 的子型別，則回傳 true。`ob' 不得為 @code{NULL}。這個函式一定會執行成功。
@end deffn

@geindex PyDateTime_CheckExact (C function)
@anchor{c-api/datetime c PyDateTime_CheckExact}@anchor{5279}
@deffn {C 函式} int PyDateTime_CheckExact (PyObject *ob)

如果 `ob' 的型別為 @ref{5272,,PyDateTime_DateTimeType}，則回傳 true。`ob' 不得為 @code{NULL}。這個函式一定會執行成功。
@end deffn

@geindex PyTime_Check (C function)
@anchor{c-api/datetime c PyTime_Check}@anchor{527a}
@deffn {C 函式} int PyTime_Check (PyObject *ob)

如果 `ob' 的型別為 @ref{5273,,PyDateTime_TimeType} 或 @code{PyDateTime_TimeType} 的子型別，則回傳 true。`ob' 不得為 @code{NULL}。這個函式一定會執行成功。
@end deffn

@geindex PyTime_CheckExact (C function)
@anchor{c-api/datetime c PyTime_CheckExact}@anchor{527b}
@deffn {C 函式} int PyTime_CheckExact (PyObject *ob)

如果 `ob' 的型別為 @ref{5273,,PyDateTime_TimeType}，則回傳 true。`ob' 不得為 @code{NULL}。這個函式一定會執行成功。
@end deffn

@geindex PyDelta_Check (C function)
@anchor{c-api/datetime c PyDelta_Check}@anchor{527c}
@deffn {C 函式} int PyDelta_Check (PyObject *ob)

如果 `ob' 的型別為 @ref{5274,,PyDateTime_DeltaType} 或 @code{PyDateTime_DeltaType} 的子型別，則回傳 true。`ob' 不得為 @code{NULL}。這個函式一定會執行成功。
@end deffn

@geindex PyDelta_CheckExact (C function)
@anchor{c-api/datetime c PyDelta_CheckExact}@anchor{527d}
@deffn {C 函式} int PyDelta_CheckExact (PyObject *ob)

如果 `ob' 的型別為 @ref{5274,,PyDateTime_DeltaType}，則回傳 true。`ob' 不得為 @code{NULL}。這個函式一定會執行成功。
@end deffn

@geindex PyTZInfo_Check (C function)
@anchor{c-api/datetime c PyTZInfo_Check}@anchor{527e}
@deffn {C 函式} int PyTZInfo_Check (PyObject *ob)

如果 `ob' 的型別為 @ref{5275,,PyDateTime_TZInfoType} 或 @code{PyDateTime_TZInfoType} 的子型別，則回傳 true。`ob' 不得為 @code{NULL}。這個函式一定會執行成功。
@end deffn

@geindex PyTZInfo_CheckExact (C function)
@anchor{c-api/datetime c PyTZInfo_CheckExact}@anchor{527f}
@deffn {C 函式} int PyTZInfo_CheckExact (PyObject *ob)

如果 `ob' 的型別為 @ref{5275,,PyDateTime_TZInfoType}，則回傳 true。 `ob' 不得為 @code{NULL}。這個函式一定會執行成功。
@end deffn

建立物件的巨集：

@geindex PyDate_FromDate (C function)
@anchor{c-api/datetime c PyDate_FromDate}@anchor{5280}
@deffn {C 函式} @ref{5d7,,PyObject} *PyDate_FromDate (int year, int month, int day)
`回傳值：新的參照。'
回傳一個有特定年、月、日的物件 @ref{1fa,,datetime.date}。
@end deffn

@geindex PyDateTime_FromDateAndTime (C function)
@anchor{c-api/datetime c PyDateTime_FromDateAndTime}@anchor{5281}
@deffn {C 函式} @ref{5d7,,PyObject} *PyDateTime_FromDateAndTime (int year, int month, int day, int hour, int minute, int second, int usecond)
`回傳值：新的參照。'
回傳一個有特定年、月、日、時、分、秒、微秒的物件 @ref{4dd,,datetime.datetime}。
@end deffn

@geindex PyDateTime_FromDateAndTimeAndFold (C function)
@anchor{c-api/datetime c PyDateTime_FromDateAndTimeAndFold}@anchor{5282}
@deffn {C 函式} @ref{5d7,,PyObject} *PyDateTime_FromDateAndTimeAndFold (int year, int month, int day, int hour, int minute, int second, int usecond, int fold)
`回傳值：新的參照。'
回傳一個有特定年、月、日、時、分、秒、微秒與 fold（時間折疊）的物件 @ref{4dd,,datetime.datetime}。


在 3.6 版被加入.

@end deffn

@geindex PyTime_FromTime (C function)
@anchor{c-api/datetime c PyTime_FromTime}@anchor{5283}
@deffn {C 函式} @ref{5d7,,PyObject} *PyTime_FromTime (int hour, int minute, int second, int usecond)
`回傳值：新的參照。'
回傳一個有特定時、分、秒、微秒的物件 @ref{1fa,,datetime.date}。
@end deffn

@geindex PyTime_FromTimeAndFold (C function)
@anchor{c-api/datetime c PyTime_FromTimeAndFold}@anchor{5284}
@deffn {C 函式} @ref{5d7,,PyObject} *PyTime_FromTimeAndFold (int hour, int minute, int second, int usecond, int fold)
`回傳值：新的參照。'
回傳一個有特定時、分、秒、微秒與 fold（時間折疊）的物件 @ref{1fb,,datetime.time}。


在 3.6 版被加入.

@end deffn

@geindex PyDelta_FromDSU (C function)
@anchor{c-api/datetime c PyDelta_FromDSU}@anchor{5285}
@deffn {C 函式} @ref{5d7,,PyObject} *PyDelta_FromDSU (int days, int seconds, int useconds)
`回傳值：新的參照。'
回傳一個 @ref{bba,,datetime.timedelta} 物件，表示給定的天數、秒數和微秒數。執行標準化 (normalization) 以便生成的微秒數和秒數位於 @ref{bba,,datetime.timedelta} 物件記錄的範圍內。
@end deffn

@geindex PyTimeZone_FromOffset (C function)
@anchor{c-api/datetime c PyTimeZone_FromOffset}@anchor{db5}
@deffn {C 函式} @ref{5d7,,PyObject} *PyTimeZone_FromOffset (PyObject *offset)
`回傳值：新的參照。'
回傳一個 @ref{12c0,,datetime.timezone} 物件，其未命名的固定偏移量由 `offset' 引數表示。


在 3.7 版被加入.

@end deffn

@geindex PyTimeZone_FromOffsetAndName (C function)
@anchor{c-api/datetime c PyTimeZone_FromOffsetAndName}@anchor{db6}
@deffn {C 函式} @ref{5d7,,PyObject} *PyTimeZone_FromOffsetAndName (PyObject *offset, PyObject *name)
`回傳值：新的參照。'
回傳一個 @ref{12c0,,datetime.timezone} 物件，其固定偏移量由 `offset' 引數表示，並帶有 tzname `name'。


在 3.7 版被加入.

@end deffn

從 date 物件中提取欄位的巨集。引數必須是個 @ref{526d,,PyDateTime_Date} 的實例，包括子類別（例如 @ref{526e,,PyDateTime_DateTime}）。引數不得為 @code{NULL}，並且不會檢查型別：

@geindex PyDateTime_GET_YEAR (C function)
@anchor{c-api/datetime c PyDateTime_GET_YEAR}@anchor{5286}
@deffn {C 函式} int PyDateTime_GET_YEAR (PyDateTime_Date *o)

回傳年份，為正整數。
@end deffn

@geindex PyDateTime_GET_MONTH (C function)
@anchor{c-api/datetime c PyDateTime_GET_MONTH}@anchor{5287}
@deffn {C 函式} int PyDateTime_GET_MONTH (PyDateTime_Date *o)

回傳月份，為正整數，從 1 到 12。
@end deffn

@geindex PyDateTime_GET_DAY (C function)
@anchor{c-api/datetime c PyDateTime_GET_DAY}@anchor{5288}
@deffn {C 函式} int PyDateTime_GET_DAY (PyDateTime_Date *o)

回傳日期，為正整數，從 1 到 31。
@end deffn

從 datetime 物件中提取欄位的巨集。引數必須是個 @ref{526e,,PyDateTime_DateTime} 的實例，包括子類別。引數不得為 @code{NULL}，並且不會檢查型別：

@geindex PyDateTime_DATE_GET_HOUR (C function)
@anchor{c-api/datetime c PyDateTime_DATE_GET_HOUR}@anchor{5289}
@deffn {C 函式} int PyDateTime_DATE_GET_HOUR (PyDateTime_DateTime *o)

回傳小時，為正整數，從 0 到 23。
@end deffn

@geindex PyDateTime_DATE_GET_MINUTE (C function)
@anchor{c-api/datetime c PyDateTime_DATE_GET_MINUTE}@anchor{528a}
@deffn {C 函式} int PyDateTime_DATE_GET_MINUTE (PyDateTime_DateTime *o)

回傳分鐘，為正整數，從 0 到 59。
@end deffn

@geindex PyDateTime_DATE_GET_SECOND (C function)
@anchor{c-api/datetime c PyDateTime_DATE_GET_SECOND}@anchor{528b}
@deffn {C 函式} int PyDateTime_DATE_GET_SECOND (PyDateTime_DateTime *o)

回傳秒，為正整數，從0 到59。
@end deffn

@geindex PyDateTime_DATE_GET_MICROSECOND (C function)
@anchor{c-api/datetime c PyDateTime_DATE_GET_MICROSECOND}@anchor{528c}
@deffn {C 函式} int PyDateTime_DATE_GET_MICROSECOND (PyDateTime_DateTime *o)

回傳微秒，為正整數，從 0 到 999999。
@end deffn

@geindex PyDateTime_DATE_GET_FOLD (C function)
@anchor{c-api/datetime c PyDateTime_DATE_GET_FOLD}@anchor{528d}
@deffn {C 函式} int PyDateTime_DATE_GET_FOLD (PyDateTime_DateTime *o)

回傳 fold，為 0 或 1 的正整數。


在 3.6 版被加入.

@end deffn

@geindex PyDateTime_DATE_GET_TZINFO (C function)
@anchor{c-api/datetime c PyDateTime_DATE_GET_TZINFO}@anchor{a8c}
@deffn {C 函式} @ref{5d7,,PyObject} *PyDateTime_DATE_GET_TZINFO (PyDateTime_DateTime *o)

回傳 tzinfo（可能是 @code{None}）。


在 3.10 版被加入.

@end deffn

從 time 物件中提取欄位的巨集。引數必須是個 @ref{526f,,PyDateTime_Time} 的實例，包括子類別。引數不得為 @code{NULL}，並且不會檢查型別：

@geindex PyDateTime_TIME_GET_HOUR (C function)
@anchor{c-api/datetime c PyDateTime_TIME_GET_HOUR}@anchor{528e}
@deffn {C 函式} int PyDateTime_TIME_GET_HOUR (PyDateTime_Time *o)

回傳小時，為正整數，從 0 到 23。
@end deffn

@geindex PyDateTime_TIME_GET_MINUTE (C function)
@anchor{c-api/datetime c PyDateTime_TIME_GET_MINUTE}@anchor{528f}
@deffn {C 函式} int PyDateTime_TIME_GET_MINUTE (PyDateTime_Time *o)

回傳分鐘，為正整數，從 0 到 59。
@end deffn

@geindex PyDateTime_TIME_GET_SECOND (C function)
@anchor{c-api/datetime c PyDateTime_TIME_GET_SECOND}@anchor{5290}
@deffn {C 函式} int PyDateTime_TIME_GET_SECOND (PyDateTime_Time *o)

回傳秒，為正整數，從0 到59。
@end deffn

@geindex PyDateTime_TIME_GET_MICROSECOND (C function)
@anchor{c-api/datetime c PyDateTime_TIME_GET_MICROSECOND}@anchor{5291}
@deffn {C 函式} int PyDateTime_TIME_GET_MICROSECOND (PyDateTime_Time *o)

回傳微秒，為正整數，從 0 到 999999。
@end deffn

@geindex PyDateTime_TIME_GET_FOLD (C function)
@anchor{c-api/datetime c PyDateTime_TIME_GET_FOLD}@anchor{5292}
@deffn {C 函式} int PyDateTime_TIME_GET_FOLD (PyDateTime_Time *o)

回傳 fold，為 0 或 1 的正整數。


在 3.6 版被加入.

@end deffn

@geindex PyDateTime_TIME_GET_TZINFO (C function)
@anchor{c-api/datetime c PyDateTime_TIME_GET_TZINFO}@anchor{a8d}
@deffn {C 函式} @ref{5d7,,PyObject} *PyDateTime_TIME_GET_TZINFO (PyDateTime_Time *o)

回傳 tzinfo（可能是 @code{None}）。


在 3.10 版被加入.

@end deffn

從 time delta 物件中提取欄位的巨集。引數必須是個 @ref{5270,,PyDateTime_Delta} 的實例，包括子類別。引數不能為 @code{NULL}，並且不會檢查型別：

@geindex PyDateTime_DELTA_GET_DAYS (C function)
@anchor{c-api/datetime c PyDateTime_DELTA_GET_DAYS}@anchor{5293}
@deffn {C 函式} int PyDateTime_DELTA_GET_DAYS (PyDateTime_Delta *o)

以 -999999999 到 999999999 之間的整數形式回傳天數。


在 3.3 版被加入.

@end deffn

@geindex PyDateTime_DELTA_GET_SECONDS (C function)
@anchor{c-api/datetime c PyDateTime_DELTA_GET_SECONDS}@anchor{5294}
@deffn {C 函式} int PyDateTime_DELTA_GET_SECONDS (PyDateTime_Delta *o)

以 0 到 86399 之間的整數形式回傳秒數。


在 3.3 版被加入.

@end deffn

@geindex PyDateTime_DELTA_GET_MICROSECONDS (C function)
@anchor{c-api/datetime c PyDateTime_DELTA_GET_MICROSECONDS}@anchor{5295}
@deffn {C 函式} int PyDateTime_DELTA_GET_MICROSECONDS (PyDateTime_Delta *o)

以 0 到 999999 之間的整數形式回傳微秒數。


在 3.3 版被加入.

@end deffn

為了方便模組實作 DB API 的巨集：

@geindex PyDateTime_FromTimestamp (C function)
@anchor{c-api/datetime c PyDateTime_FromTimestamp}@anchor{5296}
@deffn {C 函式} @ref{5d7,,PyObject} *PyDateTime_FromTimestamp (PyObject *args)
`回傳值：新的參照。'
給定一個適合傳遞給 @ref{70b,,datetime.datetime.fromtimestamp()} 的引數元組，建立並回傳一個新的 @ref{4dd,,datetime.datetime} 物件。
@end deffn

@geindex PyDate_FromTimestamp (C function)
@anchor{c-api/datetime c PyDate_FromTimestamp}@anchor{1cb9}
@deffn {C 函式} @ref{5d7,,PyObject} *PyDate_FromTimestamp (PyObject *args)
`回傳值：新的參照。'
給定一個適合傳遞給 @ref{dc8,,datetime.date.fromtimestamp()} 的引數元組，建立並回傳一個新的 @ref{1fa,,datetime.date} 物件。
@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 物件,其他物件<2>
@anchor{c-api/typehints doc}@anchor{5297}@anchor{c-api/typehints objects-for-type-hinting}@anchor{5298}@anchor{c-api/typehints translation-repo}@anchor{5299}@anchor{c-api/typehints typehintobjects}@anchor{529a}
@subsubsection 型別提示物件


提供了數個用於型別提示的內建型別。目前有兩種 -- @ref{8b8,,GenericAlias} 和 @ref{9be,,Union}。只有 @code{GenericAlias} 有公開 (expose) 給 C。

@geindex Py_GenericAlias (C function)
@anchor{c-api/typehints c Py_GenericAlias}@anchor{4f90}
@deffn {C 函式} @ref{5d7,,PyObject} *Py_GenericAlias (PyObject *origin, PyObject *args)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.9 版本開始.'
建立一個 @ref{8b8,,GenericAlias} 物件，等同於呼叫 Python 的 @ref{9e5,,types.GenericAlias} class。 `origin' 和 `args' 引數分別設定了 @code{GenericAlias} 的 @code{__origin__} 與 @code{__args__} 屬性。`origin' 應該要是個 @ref{c93,,PyTypeObject}* 且 `args' 可以是個 @ref{5014,,PyTupleObject}* 或任意 @code{PyObject*}。如果傳入的 `args' 不是個 tuple（元組），則會自動建立一個長度為 1 的 tuple 且 @code{__args__} 會被設為 @code{(args,)}。只會進行最少的引數檢查，所以即便 `origin' 不是個型別，函式也會不會失敗。 @code{GenericAlias} 的 @code{__parameters__} 屬性會自 @code{__args__} 惰性地建立 (constructed lazily)。當失敗時，會引發一個例外並回傳 @code{NULL}。

以下是個讓一個擴充型別泛用化 (generic) 的例子：

@example
...
static PyMethodDef my_obj_methods[] = @{
    // 其他方法。
    ...
    @{"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS, "See PEP 585"@}
    ...
@}
@end example


@subsubheading 也參考


資料模型方法 @ref{93b,,__class_getitem__()}。



在 3.9 版被加入.

@end deffn

@geindex Py_GenericAliasType (C var)
@anchor{c-api/typehints c Py_GenericAliasType}@anchor{4f91}
@deffn {C 變數} @ref{c93,,PyTypeObject} Py_GenericAliasType
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.9 版本開始.'
@ref{4f90,,Py_GenericAlias()} 所回傳該物件的 C 型別。等價於 Python 中的 @ref{9e5,,types.GenericAlias}。


在 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)

@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 參考手冊
@anchor{c-api/init doc}@anchor{529b}@anchor{c-api/init initialization}@anchor{529c}@anchor{c-api/init initialization-finalization-and-threads}@anchor{529d}@anchor{c-api/init translation-repo}@anchor{529e}
@section 初始化、終結化與執行緒


關於如何在初始化之前設定直譯器的細節，請參見 @ref{63e,,Python 初始化設定}。

@menu
* Python 初始化之前:: 
* Global configuration variables:: 
* Initializing and finalizing the interpreter:: 
* Process-wide parameters:: 
* Thread State and the Global Interpreter Lock:: 
* Sub-interpreter support:: 
* Asynchronous Notifications:: 
* Profiling and Tracing:: 
* Reference tracing:: 
* Advanced Debugger Support:: 
* Thread Local Storage Support:: 
* Synchronization Primitives:: 

@end menu

@node Python 初始化之前,Global configuration variables,,初始化、終結化與執行緒
@anchor{c-api/init before-python-initialization}@anchor{529f}@anchor{c-api/init pre-init-safe}@anchor{db9}
@subsection Python 初始化之前


In an application embedding  Python, the @ref{45e,,Py_Initialize()} function must
be called before using any other Python/C API functions; with the exception of
a few functions and the @ref{52a0,,global configuration variables}.

The following functions can be safely called before Python is initialized:


@itemize *

@item 
Functions that initialize the interpreter:


@itemize *

@item 
@ref{45e,,Py_Initialize()}

@item 
@ref{4f97,,Py_InitializeEx()}

@item 
@ref{3f5,,Py_InitializeFromConfig()}

@item 
@ref{baf,,Py_BytesMain()}

@item 
@ref{e19,,Py_Main()}

@item 
the runtime pre-initialization functions covered in @ref{63e,,Python 初始化設定}
@end itemize

@item 
Configuration functions:


@itemize *

@item 
@ref{1a5f,,PyImport_AppendInittab()}

@item 
@ref{1a60,,PyImport_ExtendInittab()}

@item 
@code{PyInitFrozenExtensions()}

@item 
@ref{7a1,,PyMem_SetAllocator()}

@item 
@ref{e5f,,PyMem_SetupDebugHooks()}

@item 
@ref{52a1,,PyObject_SetArenaAllocator()}

@item 
@ref{190b,,Py_SetProgramName()}

@item 
@ref{190a,,Py_SetPythonHome()}

@item 
@ref{3f2,,PySys_ResetWarnOptions()}

@item 
the configuration functions covered in @ref{63e,,Python 初始化設定}
@end itemize

@item 
Informative functions:


@itemize *

@item 
@ref{4e02,,Py_IsInitialized()}

@item 
@ref{52a2,,PyMem_GetAllocator()}

@item 
@ref{52a3,,PyObject_GetArenaAllocator()}

@item 
@ref{1629,,Py_GetBuildInfo()}

@item 
@ref{4f92,,Py_GetCompiler()}

@item 
@ref{4f93,,Py_GetCopyright()}

@item 
@ref{4f94,,Py_GetPlatform()}

@item 
@ref{4f95,,Py_GetVersion()}

@item 
@ref{4e02,,Py_IsInitialized()}
@end itemize

@item 
Utilities:


@itemize *

@item 
@ref{dbb,,Py_DecodeLocale()}

@item 
the status reporting and utility functions covered in @ref{63e,,Python 初始化設定}
@end itemize

@item 
Memory allocators:


@itemize *

@item 
@ref{629,,PyMem_RawMalloc()}

@item 
@ref{62b,,PyMem_RawRealloc()}

@item 
@ref{62a,,PyMem_RawCalloc()}

@item 
@ref{62c,,PyMem_RawFree()}
@end itemize

@item 
Synchronization:


@itemize *

@item 
@ref{5c8,,PyMutex_Lock()}

@item 
@ref{5c9,,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{dbc,,Py_EncodeLocale()}, @ref{3e1,,Py_GetPath()},
@ref{3e3,,Py_GetPrefix()}, @ref{3e7,,Py_GetExecPrefix()},
@ref{3ea,,Py_GetProgramFullPath()}, @ref{3ed,,Py_GetPythonHome()},
@ref{3ec,,Py_GetProgramName()}, @ref{190e,,PyEval_InitThreads()}, and
@ref{bb3,,Py_RunMain()}.
@end quotation
@end cartouche

@node Global configuration variables,Initializing and finalizing the interpreter,Python 初始化之前,初始化、終結化與執行緒
@anchor{c-api/init global-conf-vars}@anchor{52a0}@anchor{c-api/init global-configuration-variables}@anchor{52a4}
@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{1fe1,,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{404,,Py_BytesWarningFlag}
to 1 and @code{-bb} sets @ref{404,,Py_BytesWarningFlag} to 2.

@geindex Py_BytesWarningFlag (C var)
@anchor{c-api/init c Py_BytesWarningFlag}@anchor{404}
@deffn {C 變數} int Py_BytesWarningFlag

This API is kept for backward compatibility: setting
@ref{405,,PyConfig.bytes_warning} should be used instead, see @ref{63e,,Python Initialization Configuration}.

Issue a warning when comparing @ref{192,,bytes} or @ref{343,,bytearray} with
@ref{169,,str} or @ref{192,,bytes} with @ref{19b,,int}.  Issue an error if greater
or equal to @code{2}.

由 @ref{7f2,,-b} 選項設定。


Deprecated since version 3.12, will be removed in version 3.15.

@end deffn

@geindex Py_DebugFlag (C var)
@anchor{c-api/init c Py_DebugFlag}@anchor{3f6}
@deffn {C 變數} int Py_DebugFlag

This API is kept for backward compatibility: setting
@ref{3f7,,PyConfig.parser_debug} should be used instead, see @ref{63e,,Python Initialization Configuration}.

Turn on parser debugging output (for expert only, depending on compilation
options).

由 @ref{1fe9,,-d} 選項與 
@geindex PYTHONDEBUG
@geindex 環境變數; PYTHONDEBUG
@ref{1fea,,PYTHONDEBUG} 環境變數設定。


Deprecated since version 3.12, will be removed in version 3.15.

@end deffn

@geindex Py_DontWriteBytecodeFlag (C var)
@anchor{c-api/init c Py_DontWriteBytecodeFlag}@anchor{40a}
@deffn {C 變數} int Py_DontWriteBytecodeFlag

This API is kept for backward compatibility: setting
@ref{40b,,PyConfig.write_bytecode} should be used instead, see @ref{63e,,Python Initialization Configuration}.

If set to non-zero, Python won't try to write @code{.pyc} files on the
import of source modules.

由 @ref{15c4,,-B} 選項與 
@geindex PYTHONDONTWRITEBYTECODE
@geindex 環境變數; PYTHONDONTWRITEBYTECODE
@ref{15c5,,PYTHONDONTWRITEBYTECODE} 環境變數設定。


Deprecated since version 3.12, will be removed in version 3.15.

@end deffn

@geindex Py_FrozenFlag (C var)
@anchor{c-api/init c Py_FrozenFlag}@anchor{406}
@deffn {C 變數} int Py_FrozenFlag

This API is kept for backward compatibility: setting
@ref{407,,PyConfig.pathconfig_warnings} should be used instead, see
@ref{63e,,Python Initialization Configuration}.

Suppress error messages when calculating the module search path in
@ref{3e1,,Py_GetPath()}.

Private flag used by @code{_freeze_module} and @code{frozenmain} programs.


Deprecated since version 3.12, will be removed in version 3.15.

@end deffn

@geindex Py_HashRandomizationFlag (C var)
@anchor{c-api/init c Py_HashRandomizationFlag}@anchor{410}
@deffn {C 變數} int Py_HashRandomizationFlag

This API is kept for backward compatibility: setting
@ref{412,,PyConfig.hash_seed} and @ref{411,,PyConfig.use_hash_seed} should
be used instead, see @ref{63e,,Python Initialization Configuration}.

如果環境變數 
@geindex PYTHONHASHSEED
@geindex 環境變數; PYTHONHASHSEED
@ref{1278,,PYTHONHASHSEED} 被設定為一個非空字串則設為 @code{1}。

If the flag is non-zero, read the 
@geindex PYTHONHASHSEED
@geindex 環境變數; PYTHONHASHSEED
@ref{1278,,PYTHONHASHSEED} environment
variable to initialize the secret hash seed.


Deprecated since version 3.12, will be removed in version 3.15.

@end deffn

@geindex Py_IgnoreEnvironmentFlag (C var)
@anchor{c-api/init c Py_IgnoreEnvironmentFlag}@anchor{408}
@deffn {C 變數} int Py_IgnoreEnvironmentFlag

This API is kept for backward compatibility: setting
@ref{409,,PyConfig.use_environment} should be used instead, see
@ref{63e,,Python Initialization Configuration}.

忽略所有可能被設定的 @code{PYTHON*} 環境變數，例如 
@geindex PYTHONPATH
@geindex 環境變數; PYTHONPATH
@ref{1218,,PYTHONPATH} 與 
@geindex PYTHONHOME
@geindex 環境變數; PYTHONHOME
@ref{3ee,,PYTHONHOME}。

由 @ref{b4d,,-E} 與 @ref{b4e,,-I} 選項設定。


Deprecated since version 3.12, will be removed in version 3.15.

@end deffn

@geindex Py_InspectFlag (C var)
@anchor{c-api/init c Py_InspectFlag}@anchor{3fe}
@deffn {C 變數} int Py_InspectFlag

This API is kept for backward compatibility: setting
@ref{3ff,,PyConfig.inspect} should be used instead, see
@ref{63e,,Python Initialization Configuration}.

When a script is passed as first argument or the @ref{1a8,,-c} option is used,
enter interactive mode after executing the script or the command, even when
@ref{758,,sys.stdin} does not appear to be a terminal.

由 @ref{16cf,,-i} 選項與 
@geindex PYTHONINSPECT
@geindex 環境變數; PYTHONINSPECT
@ref{16ce,,PYTHONINSPECT} 環境變數設定。


Deprecated since version 3.12, will be removed in version 3.15.

@end deffn

@geindex Py_InteractiveFlag (C var)
@anchor{c-api/init c Py_InteractiveFlag}@anchor{3fc}
@deffn {C 變數} int Py_InteractiveFlag

This API is kept for backward compatibility: setting
@ref{3fd,,PyConfig.interactive} should be used instead, see
@ref{63e,,Python Initialization Configuration}.

由 @ref{16cf,,-i} 選項設定。


Deprecated since version 3.12, will be removed in version 3.15.

@end deffn

@geindex Py_IsolatedFlag (C var)
@anchor{c-api/init c Py_IsolatedFlag}@anchor{413}
@deffn {C 變數} int Py_IsolatedFlag

This API is kept for backward compatibility: setting
@ref{414,,PyConfig.isolated} should be used instead, see
@ref{63e,,Python Initialization Configuration}.

Run Python in isolated mode. In isolated mode @ref{3e2,,sys.path} contains
neither the script's directory nor the user's site-packages directory.

由 @ref{16cf,,-i} 選項設定。


在 3.4 版被加入.



Deprecated since version 3.12, will be removed in version 3.15.

@end deffn

@geindex Py_LegacyWindowsFSEncodingFlag (C var)
@anchor{c-api/init c Py_LegacyWindowsFSEncodingFlag}@anchor{415}
@deffn {C 變數} int Py_LegacyWindowsFSEncodingFlag

This API is kept for backward compatibility: setting
@ref{416,,PyPreConfig.legacy_windows_fs_encoding} should be used instead, see
@ref{63e,,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{756,,filesystem encoding and error handler}.

如果環境變數 
@geindex PYTHONLEGACYWINDOWSFSENCODING
@geindex 環境變數; PYTHONLEGACYWINDOWSFSENCODING
@ref{33e,,PYTHONLEGACYWINDOWSFSENCODING} 被設定為一個非空字串則設為 @code{1}。

更多詳情請見 
@geindex Python Enhancement Proposals; PEP 529
PEP 529@footnote{https://peps.python.org/pep-0529/}。

@ref{2006,,可用性}: Windows.


Deprecated since version 3.12, will be removed in version 3.15.

@end deffn

@geindex Py_LegacyWindowsStdioFlag (C var)
@anchor{c-api/init c Py_LegacyWindowsStdioFlag}@anchor{417}
@deffn {C 變數} int Py_LegacyWindowsStdioFlag

This API is kept for backward compatibility: setting
@ref{418,,PyConfig.legacy_windows_stdio} should be used instead, see
@ref{63e,,Python Initialization Configuration}.

If the flag is non-zero, use @ref{1510,,io.FileIO} instead of
@code{io._WindowsConsoleIO} for @ref{df,,sys} standard streams.

Set to @code{1} if the 
@geindex PYTHONLEGACYWINDOWSSTDIO
@geindex 環境變數; PYTHONLEGACYWINDOWSSTDIO
@ref{e50,,PYTHONLEGACYWINDOWSSTDIO} environment
variable is set to a non-empty string.

更多詳情請見 
@geindex Python Enhancement Proposals; PEP 528
PEP 528@footnote{https://peps.python.org/pep-0528/}。

@ref{2006,,可用性}: Windows.


Deprecated since version 3.12, will be removed in version 3.15.

@end deffn

@geindex Py_NoSiteFlag (C var)
@anchor{c-api/init c Py_NoSiteFlag}@anchor{402}
@deffn {C 變數} int Py_NoSiteFlag

This API is kept for backward compatibility: setting
@ref{403,,PyConfig.site_import} should be used instead, see
@ref{63e,,Python Initialization Configuration}.

Disable the import of the module @ref{cc,,site} and the site-dependent
manipulations of @ref{3e2,,sys.path} that it entails.  Also disable these
manipulations if @ref{cc,,site} is explicitly imported later (call
@ref{1fee,,site.main()} if you want them to be triggered).

由 @ref{13a9,,-S} 選項設定。


Deprecated since version 3.12, will be removed in version 3.15.

@end deffn

@geindex Py_NoUserSiteDirectory (C var)
@anchor{c-api/init c Py_NoUserSiteDirectory}@anchor{40c}
@deffn {C 變數} int Py_NoUserSiteDirectory

This API is kept for backward compatibility: setting
@ref{40d,,PyConfig.user_site_directory} should be used instead, see
@ref{63e,,Python Initialization Configuration}.

Don't add the @ref{1fed,,user site-packages directory} to
@ref{3e2,,sys.path}.

由 @ref{1586,,-s} 選項、@ref{b4e,,-I} 選項與 
@geindex PYTHONNOUSERSITE
@geindex 環境變數; PYTHONNOUSERSITE
@ref{1587,,PYTHONNOUSERSITE} 環境變數設定。


Deprecated since version 3.12, will be removed in version 3.15.

@end deffn

@geindex Py_OptimizeFlag (C var)
@anchor{c-api/init c Py_OptimizeFlag}@anchor{400}
@deffn {C 變數} int Py_OptimizeFlag

This API is kept for backward compatibility: setting
@ref{401,,PyConfig.optimization_level} should be used instead, see
@ref{63e,,Python Initialization Configuration}.

由 @ref{18c,,-O} 選項與 
@geindex PYTHONOPTIMIZE
@geindex 環境變數; PYTHONOPTIMIZE
@ref{1feb,,PYTHONOPTIMIZE} 環境變數設定。


Deprecated since version 3.12, will be removed in version 3.15.

@end deffn

@geindex Py_QuietFlag (C var)
@anchor{c-api/init c Py_QuietFlag}@anchor{3fa}
@deffn {C 變數} int Py_QuietFlag

This API is kept for backward compatibility: setting
@ref{3fb,,PyConfig.quiet} should be used instead, see @ref{63e,,Python Initialization Configuration}.

Don't display the copyright and version messages even in interactive mode.

由 @ref{1fec,,-q} 選項設定。


在 3.2 版被加入.



Deprecated since version 3.12, will be removed in version 3.15.

@end deffn

@geindex Py_UnbufferedStdioFlag (C var)
@anchor{c-api/init c Py_UnbufferedStdioFlag}@anchor{40e}
@deffn {C 變數} int Py_UnbufferedStdioFlag

This API is kept for backward compatibility: setting
@ref{40f,,PyConfig.buffered_stdio} should be used instead, see @ref{63e,,Python Initialization Configuration}.

Force the stdout and stderr streams to be unbuffered.

由 @ref{1c56,,-u} 選項與 
@geindex PYTHONUNBUFFERED
@geindex 環境變數; PYTHONUNBUFFERED
@ref{1c57,,PYTHONUNBUFFERED} 環境變數設定。


Deprecated since version 3.12, will be removed in version 3.15.

@end deffn

@geindex Py_VerboseFlag (C var)
@anchor{c-api/init c Py_VerboseFlag}@anchor{3f8}
@deffn {C 變數} int Py_VerboseFlag

This API is kept for backward compatibility: setting
@ref{3f9,,PyConfig.verbose} should be used instead, see @ref{63e,,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.

由 @ref{161c,,-v} 選項與 
@geindex PYTHONVERBOSE
@geindex 環境變數; PYTHONVERBOSE
@ref{1fef,,PYTHONVERBOSE} 環境變數設定。


Deprecated since version 3.12, will be removed in version 3.15.

@end deffn

@node Initializing and finalizing the interpreter,Process-wide parameters,Global configuration variables,初始化、終結化與執行緒
@anchor{c-api/init initializing-and-finalizing-the-interpreter}@anchor{52a5}
@subsection Initializing and finalizing the interpreter


@geindex Py_Initialize (C function)
@anchor{c-api/init c Py_Initialize}@anchor{45e}
@deffn {C 函式} void Py_Initialize ()
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@geindex PyEval_InitThreads()
@geindex modules（sys 模組中）
@geindex path（sys 模組中）
@geindex 模組;builtins（內建）
@geindex 模組;__main__
@geindex 模組;sys
@geindex 模組;search（搜尋）;path（路徑）
@geindex Py_FinalizeEx（C 函式）

Initialize the Python interpreter.  In an application embedding  Python,
this should be called before using any other Python/C API functions; see
@ref{db9,,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{df,,sys}.
It also initializes the module search path (@code{sys.path}). It does not set
@code{sys.argv}; use the @ref{63e,,Python Initialization Configuration}
API for that. This is a no-op when called for a second time (without calling
@ref{f0c,,Py_FinalizeEx()} first).  There is no return value; it is a fatal
error if the initialization fails.

Use @ref{3f5,,Py_InitializeFromConfig()} to customize the
@ref{63e,,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/init c Py_InitializeEx}@anchor{4f97}
@deffn {C 函式} void Py_InitializeEx (int initsigs)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
This function works like @ref{45e,,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{3f5,,Py_InitializeFromConfig()} to customize the
@ref{63e,,Python Initialization Configuration}.
@end deffn

@geindex Py_InitializeFromConfig (C function)
@anchor{c-api/init c Py_InitializeFromConfig}@anchor{3f5}
@deffn {C 函式} @ref{b9b,,PyStatus} Py_InitializeFromConfig (const PyConfig *config)

Initialize Python from `config' configuration, as described in
@ref{52a6,,Initialization with PyConfig}.

See the @ref{63e,,Python 初始化設定} section for details on pre-initializing the
interpreter, populating the runtime configuration structure, and querying
the returned status structure.
@end deffn

@geindex Py_IsInitialized (C function)
@anchor{c-api/init c Py_IsInitialized}@anchor{4e02}
@deffn {C 函式} int Py_IsInitialized ()
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return true (nonzero) when the Python interpreter has been initialized, false
(zero) if not.  After @ref{f0c,,Py_FinalizeEx()} is called, this returns false until
@ref{45e,,Py_Initialize()} is called again.
@end deffn

@geindex Py_IsFinalizing (C function)
@anchor{c-api/init c Py_IsFinalizing}@anchor{5f5}
@deffn {C 函式} int Py_IsFinalizing ()
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.13 版本開始.'
Return true (non-zero) if the main Python interpreter is
@ref{474,,shutting down}. Return false (zero) otherwise.


在 3.13 版被加入.

@end deffn

@geindex Py_FinalizeEx (C function)
@anchor{c-api/init c Py_FinalizeEx}@anchor{f0c}
@deffn {C 函式} int Py_FinalizeEx ()
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.6 版本開始.'
Undo all initializations made by @ref{45e,,Py_Initialize()} and subsequent use of
Python/C API functions, and destroy all sub-interpreters (see
@ref{1a72,,Py_NewInterpreter()} below) that were created and not yet destroyed since
the last call to @ref{45e,,Py_Initialize()}.  This is a no-op when called for a second
time (without calling @ref{45e,,Py_Initialize()} again first).

Since this is the reverse of @ref{45e,,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{bb3,,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 preveiously allocated PyObjects before using them in subsequent calls to
@ref{45e,,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{11f8,,__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{45e,,Py_Initialize()} and @ref{f0c,,Py_FinalizeEx()}
more than once.  @ref{f0c,,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.

引發一個不附帶引數的@ref{1b70,,稽核事件} @code{cpython._PySys_ClearAuditHooks}。


在 3.6 版被加入.

@end deffn

@geindex Py_Finalize (C function)
@anchor{c-api/init c Py_Finalize}@anchor{45d}
@deffn {C 函式} void Py_Finalize ()
` 為 @ref{76e,,穩定 ABI 的一部分}.'
This is a backwards-compatible version of @ref{f0c,,Py_FinalizeEx()} that
disregards the return value.
@end deffn

@geindex Py_BytesMain (C function)
@anchor{c-api/init c Py_BytesMain}@anchor{baf}
@deffn {C 函式} int Py_BytesMain (int argc, char **argv)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.8 版本開始.'
Similar to @ref{e19,,Py_Main()} but `argv' is an array of bytes strings,
allowing the calling application to delegate the text decoding step to
the CPython runtime.


在 3.8 版被加入.

@end deffn

@geindex Py_Main (C function)
@anchor{c-api/init c Py_Main}@anchor{e19}
@deffn {C 函式} int Py_Main (int argc, wchar_t **argv)
` 為 @ref{76e,,穩定 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{1202,,命令列}.

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{dbb,,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{bb3,,Py_RunMain()}.

In terms of the CPython runtime configuration APIs documented in the
@ref{63e,,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{45e,,Py_Initialize()}, @ref{4f97,,Py_InitializeEx()} or
@ref{3f5,,Py_InitializeFromConfig()} directly, and all settings will be applied
as described elsewhere in this documentation. If this function is instead
called `after' a preceding runtime initialization API call, then exactly
which environmental and command line configuration settings will be updated
is version dependent (as it depends on which settings correctly support
being modified after they have already been set once when the runtime was
first initialized).
@end deffn

@geindex Py_RunMain (C function)
@anchor{c-api/init c Py_RunMain}@anchor{bb3}
@deffn {C 函式} int Py_RunMain (void)

Executes the main module in a fully configured CPython runtime.

Executes the command (@ref{52a7,,PyConfig.run_command}), the script
(@ref{52a8,,PyConfig.run_filename}) or the module
(@ref{52a9,,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{3ff,,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{f37,,SystemExit}, or @code{1}
for any other unhandled exception.

If @ref{3ff,,PyConfig.inspect} is set (such as when the @ref{16cf,,-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{f37,,SystemExit}, as specified above.

This function always finalizes the Python interpreter before it returns.

See @ref{52aa,,Python Configuration} for an example of a
customized Python that always runs in isolated mode using
@ref{bb3,,Py_RunMain()}.
@end deffn

@geindex PyUnstable_AtExit (C function)
@anchor{c-api/init c PyUnstable_AtExit}@anchor{1865}
@deffn {C 函式} int PyUnstable_AtExit (PyInterpreterState *interp, void (*func)(void*), void *data)

@cartouche
@quotation 這是 不穩定 API，它可能在小版本發布中沒有任何警告地被變更。 `這是 @ref{762,,不穩定 API}，它可能在小版本發布中沒有任何警告地被變更。'
@end quotation
@end cartouche

Register an @ref{d,,atexit} callback for the target interpreter `interp'.
This is similar to @ref{4f8d,,Py_AtExit()}, but takes an explicit interpreter and
data pointer for the callback.

There must be an @ref{4d99,,attached thread state} for `interp'.


在 3.13 版被加入.

@end deffn

@node Process-wide parameters,Thread State and the Global Interpreter Lock,Initializing and finalizing the interpreter,初始化、終結化與執行緒
@anchor{c-api/init process-wide-parameters}@anchor{52ab}
@subsection Process-wide parameters


@geindex Py_SetProgramName (C function)
@anchor{c-api/init c Py_SetProgramName}@anchor{190b}
@deffn {C 函式} void Py_SetProgramName (const wchar_t *name)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@geindex Py_Initialize()
@geindex main()
@geindex Py_GetPath()

This API is kept for backward compatibility: setting
@ref{3f0,,PyConfig.program_name} should be used instead, see @ref{63e,,Python Initialization Configuration}.

This function should be called before @ref{45e,,Py_Initialize()} is called for
the first time, if it is called at all.  It tells the interpreter the value
of the @code{argv[0]} argument to the @code{main()} function of the program
(converted to wide characters).
This is used by @ref{3e1,,Py_GetPath()} and some other functions below to find
the Python run-time libraries relative to the interpreter executable.  The
default value is @code{'python'}.  The argument should point to a
zero-terminated wide character string in static storage whose contents will not
change for the duration of the program's execution.  No code in the Python
interpreter will change the contents of this storage.

Use @ref{dbb,,Py_DecodeLocale()} to decode a bytes string to get a
wchar_t* string.


Deprecated since version 3.11, will be removed in version 3.15.

@end deffn

@geindex Py_GetProgramName (C function)
@anchor{c-api/init c Py_GetProgramName}@anchor{3ec}
@deffn {C 函式} wchar_t *Py_GetProgramName ()
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return the program name set with @ref{3f0,,PyConfig.program_name}, or the default.
The returned string points into static storage; the caller should not modify its
value.

此函式不應該在 @ref{45e,,Py_Initialize()} 之前呼叫，否則會回傳 @code{NULL}。


在 3.10 版的變更: 如果在 @ref{45e,,Py_Initialize()} 之前呼叫，現在會回傳 @code{NULL}。



Deprecated since version 3.13, will be removed in version 3.15: Use @ref{37a,,PyConfig_Get("executable")}
(@ref{3eb,,sys.executable}) instead.

@end deffn

@geindex Py_GetPrefix (C function)
@anchor{c-api/init c Py_GetPrefix}@anchor{3e3}
@deffn {C 函式} wchar_t *Py_GetPrefix ()
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return the `prefix' for installed platform-independent files. This is derived
through a number of complicated rules from the program name set with
@ref{3f0,,PyConfig.program_name} and some environment variables; for example, if the
program name is @code{'/usr/local/bin/python'}, the prefix is @code{'/usr/local'}. The
returned string points into static storage; the caller should not modify its
value.  This corresponds to the @code{prefix} variable in the top-level
@code{Makefile} and the @ref{2015,,--prefix} argument to the @code{configure}
script at build time.  The value is available to Python code as @code{sys.base_prefix}.
It is only useful on Unix.  See also the next function.

此函式不應該在 @ref{45e,,Py_Initialize()} 之前呼叫，否則會回傳 @code{NULL}。


在 3.10 版的變更: 如果在 @ref{45e,,Py_Initialize()} 之前呼叫，現在會回傳 @code{NULL}。



Deprecated since version 3.13, will be removed in version 3.15: Use @ref{37a,,PyConfig_Get("base_prefix")}
(@ref{3e4,,sys.base_prefix}) instead. Use @ref{37a,,PyConfig_Get("prefix")} (@ref{3e6,,sys.prefix}) if @ref{3e5,,virtual environments} need to be handled.

@end deffn

@geindex Py_GetExecPrefix (C function)
@anchor{c-api/init c Py_GetExecPrefix}@anchor{3e7}
@deffn {C 函式} wchar_t *Py_GetExecPrefix ()
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return the `exec-prefix' for installed platform-`dependent' files.  This is
derived through a number of complicated rules from the program name set with
@ref{3f0,,PyConfig.program_name} and some environment variables; for example, if the
program name is @code{'/usr/local/bin/python'}, the exec-prefix is
@code{'/usr/local'}.  The returned string points into static storage; the caller
should not modify its value.  This corresponds to the @code{exec_prefix}
variable in the top-level @code{Makefile} and the @code{--exec-prefix}
argument to the @code{configure} script at build  time.  The value is
available to Python code as @code{sys.base_exec_prefix}.  It is only useful on
Unix.

Background: The exec-prefix differs from the prefix when platform dependent
files (such as executables and shared libraries) are installed in a different
directory tree.  In a typical installation, platform dependent files may be
installed in the @code{/usr/local/plat} subtree while platform independent may
be installed in @code{/usr/local}.

Generally speaking, a platform is a combination of hardware and software
families, e.g.  Sparc machines running the Solaris 2.x operating system are
considered the same platform, but Intel machines running Solaris 2.x are another
platform, and Intel machines running Linux are yet another platform.  Different
major revisions of the same operating system generally also form different
platforms.  Non-Unix operating systems are a different story; the installation
strategies on those systems are so different that the prefix and exec-prefix are
meaningless, and set to the empty string. Note that compiled Python bytecode
files are platform independent (but not independent from the Python version by
which they were compiled!).

System administrators will know how to configure the @code{mount} or
@code{automount} programs to share @code{/usr/local} between platforms
while having @code{/usr/local/plat} be a different filesystem for each
platform.

此函式不應該在 @ref{45e,,Py_Initialize()} 之前呼叫，否則會回傳 @code{NULL}。


在 3.10 版的變更: 如果在 @ref{45e,,Py_Initialize()} 之前呼叫，現在會回傳 @code{NULL}。



Deprecated since version 3.13, will be removed in version 3.15: Use @ref{37a,,PyConfig_Get("base_exec_prefix")}
(@ref{3e8,,sys.base_exec_prefix}) instead. Use
@ref{37a,,PyConfig_Get("exec_prefix")}
(@ref{3e9,,sys.exec_prefix}) if @ref{3e5,,virtual environments} need
to be handled.

@end deffn

@geindex Py_GetProgramFullPath (C function)
@anchor{c-api/init c Py_GetProgramFullPath}@anchor{3ea}
@deffn {C 函式} wchar_t *Py_GetProgramFullPath ()
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@geindex executable（sys 模組中）

Return the full program name of the Python executable; this is  computed as a
side-effect of deriving the default module search path  from the program name
(set by @ref{3f0,,PyConfig.program_name}). The returned string points into
static storage; the caller should not modify its value.  The value is available
to Python code as @code{sys.executable}.

此函式不應該在 @ref{45e,,Py_Initialize()} 之前呼叫，否則會回傳 @code{NULL}。


在 3.10 版的變更: 如果在 @ref{45e,,Py_Initialize()} 之前呼叫，現在會回傳 @code{NULL}。



Deprecated since version 3.13, will be removed in version 3.15: Use @ref{37a,,PyConfig_Get("executable")}
(@ref{3eb,,sys.executable}) instead.

@end deffn

@geindex Py_GetPath (C function)
@anchor{c-api/init c Py_GetPath}@anchor{3e1}
@deffn {C 函式} wchar_t *Py_GetPath ()
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@geindex 模組;search（搜尋）;path（路徑）
@geindex path（sys 模組中）

Return the default module search path; this is computed from the program name
(set by @ref{3f0,,PyConfig.program_name}) and some environment variables.
The returned string consists of a series of directory names separated by a
platform dependent delimiter character.  The delimiter character is @code{':'}
on Unix and macOS, @code{';'} on Windows.  The returned string points into
static storage; the caller should not modify its value.  The list
@ref{3e2,,sys.path} is initialized with this value on interpreter startup; it
can be (and usually is) modified later to change the search path for loading
modules.

此函式不應該在 @ref{45e,,Py_Initialize()} 之前呼叫，否則會回傳 @code{NULL}。

@c XXX should give the exact rules


在 3.10 版的變更: 如果在 @ref{45e,,Py_Initialize()} 之前呼叫，現在會回傳 @code{NULL}。



Deprecated since version 3.13, will be removed in version 3.15: Use @ref{37a,,PyConfig_Get("module_search_paths")}
(@ref{3e2,,sys.path}) instead.

@end deffn

@geindex Py_GetVersion (C function)
@anchor{c-api/init c Py_GetVersion}@anchor{4f95}
@deffn {C 函式} const char *Py_GetVersion ()
` 為 @ref{76e,,穩定 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（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{497,,sys.version}.

另請參閱 @ref{37f,,Py_Version} 常數。
@end deffn

@geindex Py_GetPlatform (C function)
@anchor{c-api/init c Py_GetPlatform}@anchor{4f94}
@deffn {C 函式} const char *Py_GetPlatform ()
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@geindex platform（sys 模組中）

Return the platform identifier for the current platform.  On Unix, this is
formed from the "official" name of the operating system, converted to lower
case, followed by the major revision number; e.g., for Solaris 2.x, which is
also known as SunOS 5.x, the value is @code{'sunos5'}.  On macOS, it is
@code{'darwin'}.  On Windows, it is @code{'win'}.  The returned string points into
static storage; the caller should not modify its value.  The value is available
to Python code as @code{sys.platform}.
@end deffn

@geindex Py_GetCopyright (C function)
@anchor{c-api/init c Py_GetCopyright}@anchor{4f93}
@deffn {C 函式} const char *Py_GetCopyright ()
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return the official copyright string for the current Python version, for example

@code{'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam'}

@geindex copyright（sys 模組中）

The returned string points into static storage; the caller should not modify its
value.  The value is available to Python code as @code{sys.copyright}.
@end deffn

@geindex Py_GetCompiler (C function)
@anchor{c-api/init c Py_GetCompiler}@anchor{4f92}
@deffn {C 函式} const char *Py_GetCompiler ()
` 為 @ref{76e,,穩定 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（sys 模組中）

The returned string points into static storage; the caller should not modify its
value.  The value is available to Python code as part of the variable
@code{sys.version}.
@end deffn

@geindex Py_GetBuildInfo (C function)
@anchor{c-api/init c Py_GetBuildInfo}@anchor{1629}
@deffn {C 函式} const char *Py_GetBuildInfo ()
` 為 @ref{76e,,穩定 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（sys 模組中）

The returned string points into static storage; the caller should not modify its
value.  The value is available to Python code as part of the variable
@code{sys.version}.
@end deffn

@geindex PySys_SetArgvEx (C function)
@anchor{c-api/init c PySys_SetArgvEx}@anchor{190c}
@deffn {C 函式} void PySys_SetArgvEx (int argc, wchar_t **argv, int updatepath)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@geindex main()
@geindex Py_FatalError()
@geindex argv（sys 模組中）

This API is kept for backward compatibility: setting
@ref{3ef,,PyConfig.argv}, @ref{1bdd,,PyConfig.parse_argv} and
@ref{96f,,PyConfig.safe_path} should be used instead, see @ref{63e,,Python Initialization Configuration}.

Set @ref{1465,,sys.argv} based on `argc' and `argv'.  These parameters are
similar to those passed to the program's @code{main()} function with the
difference that the first entry should refer to the script file to be
executed rather than the executable hosting the Python interpreter.  If there
isn't a script that will be run, the first entry in `argv' can be an empty
string.  If this function fails to initialize @ref{1465,,sys.argv}, a fatal
condition is signalled using @ref{b71,,Py_FatalError()}.

If `updatepath' is zero, this is all the function does.  If `updatepath'
is non-zero, the function also modifies @ref{3e2,,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{3e2,,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{3e2,,sys.path}, which is the same as prepending the current working
directory (@code{"."}).
@end itemize

Use @ref{dbb,,Py_DecodeLocale()} to decode a bytes string to get a
wchar_t* string.

See also @ref{a8b,,PyConfig.orig_argv} and @ref{3ef,,PyConfig.argv}
members of the @ref{63e,,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{3e2,,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{3e2,,sys.path} element after having called
@ref{190d,,PySys_SetArgv()}, for example using:

@example
PyRun_SimpleString("import sys; sys.path.pop(0)\n");
@end example
@end quotation
@end cartouche


在 3.1.3 版被加入.


@c XXX impl. doesn't seem consistent in allowing ``0``/``NULL`` for the params;
@c check w/ Guido.


Deprecated since version 3.11, will be removed in version 3.15.

@end deffn

@geindex PySys_SetArgv (C function)
@anchor{c-api/init c PySys_SetArgv}@anchor{190d}
@deffn {C 函式} void PySys_SetArgv (int argc, wchar_t **argv)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
This API is kept for backward compatibility: setting
@ref{3ef,,PyConfig.argv} and @ref{1bdd,,PyConfig.parse_argv} should be used
instead, see @ref{63e,,Python Initialization Configuration}.

This function works like @ref{190c,,PySys_SetArgvEx()} with `updatepath' set
to @code{1} unless the @code{python} interpreter was started with the
@ref{b4e,,-I}.

Use @ref{dbb,,Py_DecodeLocale()} to decode a bytes string to get a
wchar_t* string.

See also @ref{a8b,,PyConfig.orig_argv} and @ref{3ef,,PyConfig.argv}
members of the @ref{63e,,Python Initialization Configuration}.


在 3.4 版的變更: The `updatepath' value depends on @ref{b4e,,-I}.



Deprecated since version 3.11, will be removed in version 3.15.

@end deffn

@geindex Py_SetPythonHome (C function)
@anchor{c-api/init c Py_SetPythonHome}@anchor{190a}
@deffn {C 函式} void Py_SetPythonHome (const wchar_t *home)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
This API is kept for backward compatibility: setting
@ref{3f1,,PyConfig.home} should be used instead, see @ref{63e,,Python Initialization Configuration}.

Set the default "home" directory, that is, the location of the standard
Python libraries.  See 
@geindex PYTHONHOME
@geindex 環境變數; PYTHONHOME
@ref{3ee,,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{dbb,,Py_DecodeLocale()} to decode a bytes string to get a
wchar_t* string.


Deprecated since version 3.11, will be removed in version 3.15.

@end deffn

@geindex Py_GetPythonHome (C function)
@anchor{c-api/init c Py_GetPythonHome}@anchor{3ed}
@deffn {C 函式} wchar_t *Py_GetPythonHome ()
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return the default "home", that is, the value set by
@ref{3f1,,PyConfig.home}, or the value of the 
@geindex PYTHONHOME
@geindex 環境變數; PYTHONHOME
@ref{3ee,,PYTHONHOME}
environment variable if it is set.

此函式不應該在 @ref{45e,,Py_Initialize()} 之前呼叫，否則會回傳 @code{NULL}。


在 3.10 版的變更: 如果在 @ref{45e,,Py_Initialize()} 之前呼叫，現在會回傳 @code{NULL}。



Deprecated since version 3.13, will be removed in version 3.15: 改為使用 @ref{37a,,PyConfig_Get("home")} 或 
@geindex PYTHONHOME
@geindex 環境變數; PYTHONHOME
@ref{3ee,,PYTHONHOME} 環境變數。

@end deffn

@node Thread State and the Global Interpreter Lock,Sub-interpreter support,Process-wide parameters,初始化、終結化與執行緒
@anchor{c-api/init thread-state-and-the-global-interpreter-lock}@anchor{52ac}@anchor{c-api/init threads}@anchor{52ad}
@subsection Thread State and the Global Interpreter Lock


@geindex global interpreter lock（全域直譯器鎖）
@geindex interpreter lock（直譯器鎖）
@geindex lock@comma{} interpreter（鎖、直譯器）

Unless on a @ref{1f4,,free-threaded} build of @ref{8fd,,CPython},
the Python interpreter is not fully thread-safe.  In order to support
multi-threaded Python programs, there's a global lock, called the @ref{46e,,global interpreter lock} or @ref{164,,GIL}, that must be held by the current thread before
it can safely access Python objects. Without the lock, even the simplest
operations could cause problems in a multi-threaded program: for example, when
two threads simultaneously increment the reference count of the same object, the
reference count could end up being incremented only once instead of twice.

@geindex setswitchinterval （sys 模組中）

Therefore, the rule exists that only the thread that has acquired the
@ref{164,,GIL} may operate on Python objects or call Python/C API functions.
In order to emulate concurrency of execution, the interpreter regularly
tries to switch threads (see @ref{b3b,,sys.setswitchinterval()}).  The lock is also
released around potentially blocking I/O operations like reading or writing
a file, so that other Python threads can run in the meantime.

@geindex PyThreadState（C 型別）

The Python interpreter keeps some thread-specific bookkeeping information
inside a data structure called @ref{988,,PyThreadState}, known as a @ref{17c4,,thread state}.
Each OS thread has a thread-local pointer to a @ref{988,,PyThreadState}; a thread state
referenced by this pointer is considered to be @ref{4d99,,attached}.

A thread can only have one @ref{4d99,,attached thread state} at a time. An attached
thread state is typically analogous with holding the @ref{164,,GIL}, except on
@ref{1f4,,free-threaded} builds.  On builds with the @ref{164,,GIL} enabled,
@ref{4d99,,attaching} a thread state will block until the @ref{164,,GIL}
can be acquired. However,  even on builds with the @ref{164,,GIL} disabled, it is still required
to have an attached thread state to call most of the C API.

In general, there will always be an @ref{4d99,,attached thread state} when using Python's C API.
Only in some specific cases (such as in a @ref{4d85,,Py_BEGIN_ALLOW_THREADS} block) will the
thread not have an attached thread state. If uncertain, check if @ref{421,,PyThreadState_GetUnchecked()} returns
@code{NULL}.

@menu
* Detaching the thread state from extension code:: 
* Non-Python created threads:: 
* Supporting subinterpreters in non-Python threads:: 
* Cautions about fork(): Cautions about fork. 
* Cautions regarding runtime finalization:: 
* 高階 API:: 
* 低階 API:: 

@end menu

@node Detaching the thread state from extension code,Non-Python created threads,,Thread State and the Global Interpreter Lock
@anchor{c-api/init detaching-the-thread-state-from-extension-code}@anchor{52ae}
@subsubsection Detaching the thread state from extension code


Most extension code manipulating the @ref{17c4,,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 巨集）
@geindex Py_END_ALLOW_THREADS（C 巨集）

The @ref{4d85,,Py_BEGIN_ALLOW_THREADS} macro opens a new block and declares a
hidden local variable; the @ref{c76,,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 函式）
@geindex PyEval_SaveThread（C 函式）

Here is how these functions work:

The @ref{4d99,,attached thread state} holds the @ref{164,,GIL} for the entire interpreter. When detaching
the @ref{4d99,,attached thread state}, the @ref{164,,GIL} is released, allowing other threads to attach
a thread state to their own thread, thus getting the @ref{164,,GIL} and can start executing.
The pointer to the prior @ref{4d99,,attached thread state} is stored as a local variable.
Upon reaching @ref{c76,,Py_END_ALLOW_THREADS}, the thread state that was
previously @ref{4d99,,attached} is passed to @ref{640,,PyEval_RestoreThread()}.
This function will block until another releases its @ref{4d99,,thread state},
thus allowing the old @ref{4d99,,thread state} to get re-attached and the
C API can be called again.

For @ref{1f4,,free-threaded} builds, the @ref{164,,GIL} is normally
out of the question, but detaching the @ref{4d99,,thread state} is still required
for blocking I/O and long operations. The difference is that threads don't have to wait for the @ref{164,,GIL}
to be released to attach their thread state, allowing true multi-core parallelism.

@cartouche
@quotation 備註 
Calling system I/O functions is the most common use case for detaching
the @ref{4d99,,thread state}, but it can also be useful before calling
long-running computations which don't need access to Python objects, such
as compression or cryptographic functions operating over memory buffers.
For example, the standard @ref{139,,zlib} and @ref{6c,,hashlib} modules detach the
@ref{4d99,,thread state} when compressing or hashing data.
@end quotation
@end cartouche

@node Non-Python created threads,Supporting subinterpreters in non-Python threads,Detaching the thread state from extension code,Thread State and the Global Interpreter Lock
@anchor{c-api/init gilstate}@anchor{52af}@anchor{c-api/init non-python-created-threads}@anchor{52b0}
@subsubsection Non-Python created threads


When threads are created using the dedicated Python APIs (such as the
@ref{f3,,threading} module), a thread state is automatically associated to them
and the code showed above is therefore correct.  However, when threads are
created from C (for example by a third-party library with its own thread
management), they don't hold the @ref{164,,GIL}, because they don't have an
@ref{4d99,,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 an @ref{4d99,,attached thread state} before you can start using the Python/C
API.  When you are done, you should detach the @ref{4d99,,thread state}, and
finally free it.

The @ref{642,,PyGILState_Ensure()} and @ref{643,,PyGILState_Release()} functions do
all of the above automatically.  The typical idiom for calling into Python
from a C thread is:

@example
PyGILState_STATE gstate;
gstate = PyGILState_Ensure();

/* Perform Python actions here. */
result = CallSomeFunction();
/* evaluate result or handle exception */

/* Release the thread. No Python API allowed beyond this point. */
PyGILState_Release(gstate);
@end example

Note that the @code{PyGILState_*} functions assume there is only one global
interpreter (created automatically by @ref{45e,,Py_Initialize()}).  Python
supports the creation of additional interpreters (using
@ref{1a72,,Py_NewInterpreter()}), but mixing multiple interpreters and the
@code{PyGILState_*} API is unsupported. This is because @ref{642,,PyGILState_Ensure()}
and similar functions default to @ref{4d99,,attaching} a
@ref{17c4,,thread state} for the main interpreter, meaning that the thread can't safely
interact with the calling subinterpreter.

@node Supporting subinterpreters in non-Python threads,Cautions about fork,Non-Python created threads,Thread State and the Global Interpreter Lock
@anchor{c-api/init supporting-subinterpreters-in-non-python-threads}@anchor{52b1}
@subsubsection Supporting subinterpreters in non-Python threads


If you would like to support subinterpreters with non-Python created threads, you
must use the @code{PyThreadState_*} API instead of the traditional @code{PyGILState_*}
API.

In particular, you must store the interpreter state from the calling
function and pass it to @ref{4f40,,PyThreadState_New()}, which will ensure that
the @ref{17c4,,thread state} is targeting the correct interpreter:

@example
/* The return value of PyInterpreterState_Get() from the
   function that created this thread. */
PyInterpreterState *interp = ThreadData->interp;
PyThreadState *tstate = PyThreadState_New(interp);
PyThreadState_Swap(tstate);

/* GIL of the subinterpreter is now held.
   Perform Python actions here. */
result = CallSomeFunction();
/* evaluate result or handle exception */

/* Destroy the thread state. No Python API allowed beyond this point. */
PyThreadState_Clear(tstate);
PyThreadState_DeleteCurrent();
@end example

@node Cautions about fork,Cautions regarding runtime finalization,Supporting subinterpreters in non-Python threads,Thread State and the Global Interpreter Lock
@anchor{c-api/init cautions-about-fork}@anchor{52b2}@anchor{c-api/init fork-and-threads}@anchor{5010}
@subsubsection Cautions about fork()


Another important thing to note about threads is their behaviour in the face
of the C @code{fork()} call. On most systems with @code{fork()}, after a
process forks only the thread that issued the fork will exist.  This has a
concrete impact both on how locks must be handled and on all stored state
in CPython's runtime.

The fact that only the "current" thread remains
means any locks held by other threads will never be released. Python solves
this for @ref{4b0,,os.fork()} by acquiring the locks it uses internally before
the fork, and releasing them afterwards. In addition, it resets any
@ref{34d9,,Lock 物件} in the child. When extending or embedding Python, there
is no way to inform Python of additional (non-Python) locks that need to be
acquired before or reset after a fork. OS facilities such as
@code{pthread_atfork()} would need to be used to accomplish the same thing.
Additionally, when extending or embedding Python, calling @code{fork()}
directly rather than through @ref{4b0,,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{42e,,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{4b0,,os.fork()}
does.  This means finalizing all other @ref{988,,PyThreadState} objects
belonging to the current interpreter and all other
@ref{ab1,,PyInterpreterState} objects.  Due to this and the special
nature of the @ref{163,,"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 Cautions regarding runtime finalization,高階 API,Cautions about fork,Thread State and the Global Interpreter Lock
@anchor{c-api/init cautions-regarding-runtime-finalization}@anchor{52b3}@anchor{c-api/init id1}@anchor{52b4}
@subsubsection Cautions regarding runtime finalization


In the late stage of @ref{474,,interpreter shutdown}, after attempting to wait for
non-daemon threads to exit (though this can be interrupted by
@ref{bbc,,KeyboardInterrupt}) and running the @ref{d,,atexit} functions, the runtime
is marked as `finalizing': @ref{5f5,,Py_IsFinalizing()} and
@ref{c77,,sys.is_finalizing()} return true.  At this point, only the `finalization
thread' that initiated finalization (typically the main thread) is allowed to
acquire the @ref{164,,GIL}.

If any thread, other than the finalization thread, attempts to attach a @ref{17c4,,thread state}
during finalization, either explicitly or
implicitly, the thread enters `a permanently blocked state'
where it remains until the program exits.  In most cases this is harmless, but this can result
in deadlock if a later stage of finalization attempts to acquire a lock owned by the
blocked thread, or otherwise waits on the blocked thread.

Gross? Yes. This prevents random crashes and/or unexpectedly skipped C++
finalizations further up the call stack when such threads were forcibly exited
here in CPython 3.13 and earlier. The CPython runtime @ref{17c4,,thread state} C APIs
have never had any error reporting or handling expectations at @ref{17c4,,thread state}
attachment time that would've allowed for graceful exit from this situation. Changing that
would require new stable C APIs and rewriting the majority of C code in the
CPython ecosystem to use those with error handling.

@node 高階 API,低階 API,Cautions regarding runtime finalization,Thread State and the Global Interpreter Lock
@anchor{c-api/init high-level-api}@anchor{52b5}
@subsubsection 高階 API


These are the most commonly used types and functions when writing C extension
code, or when embedding the Python interpreter:

@geindex PyInterpreterState (C type)
@anchor{c-api/init c PyInterpreterState}@anchor{ab1}
@deffn {C 型別} type PyInterpreterState
` 為 @ref{76e,,受限 API 的一部分} （做為一個不透明結構 (opaque struct)）.'
This data structure represents the state shared by a number of cooperating
threads.  Threads belonging to the same interpreter share their module
administration and a few other internal items. There are no public members in
this structure.

Threads belonging to different interpreters initially share nothing, except
process state like available memory, open file descriptors and such.  The global
interpreter lock is also shared by all threads, regardless of to which
interpreter they belong.


在 3.12 版的變更: 
@geindex Python Enhancement Proposals; PEP 684
PEP 684@footnote{https://peps.python.org/pep-0684/} introduced the possibility
of a @ref{52b6,,per-interpreter GIL}.
See @ref{682,,Py_NewInterpreterFromConfig()}.

@end deffn

@geindex PyThreadState (C type)
@anchor{c-api/init c PyThreadState}@anchor{988}
@deffn {C 型別} type PyThreadState
` 為 @ref{76e,,受限 API 的一部分} （做為一個不透明結構 (opaque struct)）.'
This data structure represents the state of a single thread.  The only public
data member is:

@geindex PyThreadState.interp (C member)
@anchor{c-api/init c PyThreadState interp}@anchor{52b7}
@deffn {C 成員函數} @ref{ab1,,PyInterpreterState} *interp

This thread's interpreter state.
@end deffn
@end deffn

@geindex PyEval_InitThreads (C function)
@anchor{c-api/init c PyEval_InitThreads}@anchor{190e}
@deffn {C 函式} void PyEval_InitThreads ()
` 為 @ref{76e,,穩定 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 版的變更: 此函式現在不會做任何事情。



在 3.7 版的變更: This function is now called by @ref{45e,,Py_Initialize()}, so you don't
have to call it yourself anymore.



在 3.2 版的變更: This function cannot be called before @ref{45e,,Py_Initialize()} anymore.



在 3.9 版之後被棄用.


@geindex 模組;_thread
@end deffn

@geindex PyEval_SaveThread (C function)
@anchor{c-api/init c PyEval_SaveThread}@anchor{63f}
@deffn {C 函式} @ref{988,,PyThreadState} *PyEval_SaveThread ()
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Detach the @ref{4d99,,attached thread state} and return it.
The thread will have no @ref{17c4,,thread state} upon returning.
@end deffn

@geindex PyEval_RestoreThread (C function)
@anchor{c-api/init c PyEval_RestoreThread}@anchor{640}
@deffn {C 函式} void PyEval_RestoreThread (PyThreadState *tstate)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Set the @ref{4d99,,attached thread state} to `tstate'.
The passed @ref{17c4,,thread state} `should not' be @ref{4d99,,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{52b3,,Cautions regarding runtime 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/init c PyThreadState_Get}@anchor{60d}
@deffn {C 函式} @ref{988,,PyThreadState} *PyThreadState_Get ()
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return the @ref{4d99,,attached thread state}. If the thread has no attached
thread state, (such as when inside of @ref{4d85,,Py_BEGIN_ALLOW_THREADS}
block), then this issues a fatal error (so that the caller needn't check
for @code{NULL}).

也請見 @ref{421,,PyThreadState_GetUnchecked()}。
@end deffn

@geindex PyThreadState_GetUnchecked (C function)
@anchor{c-api/init c PyThreadState_GetUnchecked}@anchor{421}
@deffn {C 函式} @ref{988,,PyThreadState} *PyThreadState_GetUnchecked ()

Similar to @ref{60d,,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.


在 3.13 版被加入: In Python 3.5 to 3.12, the function was private and known as
@code{_PyThreadState_UncheckedGet()}.

@end deffn

@geindex PyThreadState_Swap (C function)
@anchor{c-api/init c PyThreadState_Swap}@anchor{4f41}
@deffn {C 函式} @ref{988,,PyThreadState} *PyThreadState_Swap (PyThreadState *tstate)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Set the @ref{4d99,,attached thread state} to `tstate', and return the
@ref{17c4,,thread state} that was attached prior to calling.

This function is safe to call without an @ref{4d99,,attached thread state}; it
will simply return @code{NULL} indicating that there was no prior thread state.


@subsubheading 也參考


@ref{4e6a,,PyEval_ReleaseThread()}


@cartouche
@quotation 備註 
Similar to @ref{642,,PyGILState_Ensure()}, this function will hang the
thread if the runtime is finalizing.
@end quotation
@end cartouche
@end deffn

The following functions use thread-local storage, and are not compatible
with sub-interpreters:

@geindex PyGILState_STATE (C type)
@anchor{c-api/init c PyGILState_STATE}@anchor{4eb9}
@deffn {C 型別} type PyGILState_STATE
` 為 @ref{76e,,穩定 ABI 的一部分}.'
The type of the value returned by @ref{642,,PyGILState_Ensure()} and passed to
@ref{643,,PyGILState_Release()}.

@geindex PyGILState_STATE.PyGILState_LOCKED (C enumerator)
@anchor{c-api/init c PyGILState_STATE PyGILState_LOCKED}@anchor{52b8}
@deffn {C Enumerator} enumerator PyGILState_LOCKED

The GIL was already held when @ref{642,,PyGILState_Ensure()} was called.
@end deffn

@geindex PyGILState_STATE.PyGILState_UNLOCKED (C enumerator)
@anchor{c-api/init c PyGILState_STATE PyGILState_UNLOCKED}@anchor{52b9}
@deffn {C Enumerator} enumerator PyGILState_UNLOCKED

The GIL was not held when @ref{642,,PyGILState_Ensure()} was called.
@end deffn
@end deffn

@geindex PyGILState_Ensure (C function)
@anchor{c-api/init c PyGILState_Ensure}@anchor{642}
@deffn {C 函式} @ref{4eb9,,PyGILState_STATE} PyGILState_Ensure ()
` 為 @ref{76e,,穩定 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{4d99,,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{643,,PyGILState_Release()}. In general, other
thread-related APIs may be used between @ref{642,,PyGILState_Ensure()} and
@ref{643,,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{4d85,,Py_BEGIN_ALLOW_THREADS} and @ref{c76,,Py_END_ALLOW_THREADS} macros is
acceptable.

The return value is an opaque "handle" to the @ref{4d99,,attached thread state} when
@ref{642,,PyGILState_Ensure()} was called, and must be passed to
@ref{643,,PyGILState_Release()} to ensure Python is left in the same state. Even
though recursive calls are allowed, these handles `cannot' be shared - each
unique call to @ref{642,,PyGILState_Ensure()} must save the handle for its call
to @ref{643,,PyGILState_Release()}.

When the function returns, there will be an @ref{4d99,,attached thread state}
and the thread will be able to call arbitrary Python code.  Failure is a fatal error.

@cartouche
@quotation 警告 
Calling this function when the runtime is finalizing is unsafe. Doing
so will either hang the thread until the program ends, or fully crash
the interpreter in rare cases. Refer to
@ref{52b3,,Cautions regarding runtime 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 PyGILState_Release (C function)
@anchor{c-api/init c PyGILState_Release}@anchor{643}
@deffn {C 函式} void PyGILState_Release (PyGILState_STATE)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Release any resources previously acquired.  After this call, Python's state will
be the same as it was prior to the corresponding @ref{642,,PyGILState_Ensure()} call
(but generally this state will be unknown to the caller, hence the use of the
GILState API).

Every call to @ref{642,,PyGILState_Ensure()} must be matched by a call to
@ref{643,,PyGILState_Release()} on the same thread.
@end deffn

@geindex PyGILState_GetThisThreadState (C function)
@anchor{c-api/init c PyGILState_GetThisThreadState}@anchor{4eb8}
@deffn {C 函式} @ref{988,,PyThreadState} *PyGILState_GetThisThreadState ()
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Get the @ref{4d99,,attached thread state} for this thread.  May return @code{NULL} if no
GILState API has been used on the current thread.  Note that the main thread
always has such a thread-state, even if no auto-thread-state call has been
made on the main thread.  This is mainly a helper/diagnostic function.

@cartouche
@quotation 備註 
This function may return non-@code{NULL} even when the @ref{17c4,,thread state}
is detached.
Prefer @ref{60d,,PyThreadState_Get()} or @ref{421,,PyThreadState_GetUnchecked()}
for most cases.
@end quotation
@end cartouche


@subsubheading 也參考


@ref{60d,,PyThreadState_Get()}

@end deffn

@geindex PyGILState_Check (C function)
@anchor{c-api/init c PyGILState_Check}@anchor{52ba}
@deffn {C 函式} int PyGILState_Check ()

Return @code{1} if the current thread is holding the @ref{164,,GIL} and @code{0} otherwise.
This function can be called from any thread at any time.
Only if it has had its @ref{4d99,,thread state} initialized
via @ref{642,,PyGILState_Ensure()} will it return @code{1}.
This is mainly a helper/diagnostic function.  It can be useful
for example in callback contexts or memory allocation functions when
knowing that the @ref{164,,GIL} is locked can allow the caller to perform sensitive
actions or otherwise behave differently.

@cartouche
@quotation 備註 
If the current Python process has ever created a subinterpreter, this
function will `always' return @code{1}. Prefer @ref{421,,PyThreadState_GetUnchecked()}
for most cases.
@end quotation
@end cartouche


在 3.4 版被加入.

@end deffn

The following macros are normally used without a trailing semicolon; look for
example usage in the Python source distribution.

@geindex Py_BEGIN_ALLOW_THREADS (C macro)
@anchor{c-api/init c Py_BEGIN_ALLOW_THREADS}@anchor{4d85}
@deffn {C 巨集} Py_BEGIN_ALLOW_THREADS
` 為 @ref{76e,,穩定 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{c76,,Py_END_ALLOW_THREADS} macro.  See above for further discussion of this
macro.
@end deffn

@geindex Py_END_ALLOW_THREADS (C macro)
@anchor{c-api/init c Py_END_ALLOW_THREADS}@anchor{c76}
@deffn {C 巨集} Py_END_ALLOW_THREADS
` 為 @ref{76e,,穩定 ABI 的一部分}.'
This macro expands to @code{PyEval_RestoreThread(_save); @}}. Note that it contains
a closing brace; it must be matched with an earlier
@ref{4d85,,Py_BEGIN_ALLOW_THREADS} macro.  See above for further discussion of
this macro.
@end deffn

@geindex Py_BLOCK_THREADS (C macro)
@anchor{c-api/init c Py_BLOCK_THREADS}@anchor{4f8e}
@deffn {C 巨集} Py_BLOCK_THREADS
` 為 @ref{76e,,穩定 ABI 的一部分}.'
This macro expands to @code{PyEval_RestoreThread(_save);}: it is equivalent to
@ref{c76,,Py_END_ALLOW_THREADS} without the closing brace.
@end deffn

@geindex Py_UNBLOCK_THREADS (C macro)
@anchor{c-api/init c Py_UNBLOCK_THREADS}@anchor{4f9a}
@deffn {C 巨集} Py_UNBLOCK_THREADS
` 為 @ref{76e,,穩定 ABI 的一部分}.'
This macro expands to @code{_save = PyEval_SaveThread();}: it is equivalent to
@ref{4d85,,Py_BEGIN_ALLOW_THREADS} without the opening brace and variable
declaration.
@end deffn

@node 低階 API,,高階 API,Thread State and the Global Interpreter Lock
@anchor{c-api/init low-level-api}@anchor{52bb}
@subsubsection 低階 API


All of the following functions must be called after @ref{45e,,Py_Initialize()}.


在 3.7 版的變更: @ref{45e,,Py_Initialize()} now initializes the @ref{164,,GIL}
and sets an @ref{4d99,,attached thread state}.


@geindex PyInterpreterState_New (C function)
@anchor{c-api/init c PyInterpreterState_New}@anchor{460d}
@deffn {C 函式} @ref{ab1,,PyInterpreterState} *PyInterpreterState_New ()
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Create a new interpreter state object.  An @ref{4d99,,attached thread state} is not needed,
but may optionally exist if it is necessary to serialize calls to this
function.

引發一個不附帶引數的@ref{1b70,,稽核事件} @code{cpython.PyInterpreterState_New}。
@end deffn

@geindex PyInterpreterState_Clear (C function)
@anchor{c-api/init c PyInterpreterState_Clear}@anchor{460c}
@deffn {C 函式} void PyInterpreterState_Clear (PyInterpreterState *interp)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Reset all information in an interpreter state object.  There must be
an @ref{4d99,,attached thread state} for the interpreter.

引發一個不附帶引數的@ref{1b70,,稽核事件} @code{cpython.PyInterpreterState_Clear}。
@end deffn

@geindex PyInterpreterState_Delete (C function)
@anchor{c-api/init c PyInterpreterState_Delete}@anchor{4ec5}
@deffn {C 函式} void PyInterpreterState_Delete (PyInterpreterState *interp)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Destroy an interpreter state object.  There `should not' be an
@ref{4d99,,attached thread state} for the target interpreter. The interpreter
state must have been reset with a previous call to @ref{460c,,PyInterpreterState_Clear()}.
@end deffn

@geindex PyThreadState_New (C function)
@anchor{c-api/init c PyThreadState_New}@anchor{4f40}
@deffn {C 函式} @ref{988,,PyThreadState} *PyThreadState_New (PyInterpreterState *interp)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Create a new thread state object belonging to the given interpreter object.
An @ref{4d99,,attached thread state} is not needed.
@end deffn

@geindex PyThreadState_Clear (C function)
@anchor{c-api/init c PyThreadState_Clear}@anchor{18ea}
@deffn {C 函式} void PyThreadState_Clear (PyThreadState *tstate)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Reset all information in a @ref{17c4,,thread state} object.  `tstate'
must be @ref{4d99,,attached}


在 3.9 版的變更: This function now calls the @code{PyThreadState.on_delete} callback.
Previously, that happened in @ref{1c52,,PyThreadState_Delete()}.



在 3.13 版的變更: The @code{PyThreadState.on_delete} callback was removed.

@end deffn

@geindex PyThreadState_Delete (C function)
@anchor{c-api/init c PyThreadState_Delete}@anchor{1c52}
@deffn {C 函式} void PyThreadState_Delete (PyThreadState *tstate)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Destroy a @ref{17c4,,thread state} object.  `tstate' should not
be @ref{4d99,,attached} to any thread.
`tstate' must have been reset with a previous call to
@ref{18ea,,PyThreadState_Clear()}.
@end deffn

@geindex PyThreadState_DeleteCurrent (C function)
@anchor{c-api/init c PyThreadState_DeleteCurrent}@anchor{1c81}
@deffn {C 函式} void PyThreadState_DeleteCurrent (void)

Detach the @ref{4d99,,attached thread state} (which must have been reset
with a previous call to @ref{18ea,,PyThreadState_Clear()}) and then destroy it.

No @ref{17c4,,thread state} will be @ref{4d99,,attached} upon
returning.
@end deffn

@geindex PyThreadState_GetFrame (C function)
@anchor{c-api/init c PyThreadState_GetFrame}@anchor{989}
@deffn {C 函式} @ref{984,,PyFrameObject} *PyThreadState_GetFrame (PyThreadState *tstate)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.10 版本開始.'
Get the current frame of the Python thread state `tstate'.

Return a @ref{5da,,strong reference}. Return @code{NULL} if no frame is currently
executing.

也請見 @ref{1a78,,PyEval_GetFrame()}。

`tstate' must not be @code{NULL}, and must be @ref{4d99,,attached}.


在 3.9 版被加入.

@end deffn

@geindex PyThreadState_GetID (C function)
@anchor{c-api/init c PyThreadState_GetID}@anchor{b61}
@deffn {C 函式} uint64_t PyThreadState_GetID (PyThreadState *tstate)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.10 版本開始.'
Get the unique @ref{17c4,,thread state} identifier of the Python thread state `tstate'.

`tstate' must not be @code{NULL}, and must be @ref{4d99,,attached}.


在 3.9 版被加入.

@end deffn

@geindex PyThreadState_GetInterpreter (C function)
@anchor{c-api/init c PyThreadState_GetInterpreter}@anchor{b60}
@deffn {C 函式} @ref{ab1,,PyInterpreterState} *PyThreadState_GetInterpreter (PyThreadState *tstate)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.10 版本開始.'
Get the interpreter of the Python thread state `tstate'.

`tstate' must not be @code{NULL}, and must be @ref{4d99,,attached}.


在 3.9 版被加入.

@end deffn

@geindex PyThreadState_EnterTracing (C function)
@anchor{c-api/init c PyThreadState_EnterTracing}@anchor{952}
@deffn {C 函式} void PyThreadState_EnterTracing (PyThreadState *tstate)

Suspend tracing and profiling in the Python thread state `tstate'.

Resume them using the @ref{953,,PyThreadState_LeaveTracing()} function.


在 3.11 版被加入.

@end deffn

@geindex PyThreadState_LeaveTracing (C function)
@anchor{c-api/init c PyThreadState_LeaveTracing}@anchor{953}
@deffn {C 函式} void PyThreadState_LeaveTracing (PyThreadState *tstate)

Resume tracing and profiling in the Python thread state `tstate' suspended
by the @ref{952,,PyThreadState_EnterTracing()} function.

See also @ref{65b,,PyEval_SetTrace()} and @ref{16f1,,PyEval_SetProfile()}
functions.


在 3.11 版被加入.

@end deffn

@geindex PyInterpreterState_Get (C function)
@anchor{c-api/init c PyInterpreterState_Get}@anchor{644}
@deffn {C 函式} @ref{ab1,,PyInterpreterState} *PyInterpreterState_Get (void)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.9 版本開始.'
Get the current interpreter.

Issue a fatal error if there no @ref{4d99,,attached thread state}.
It cannot return NULL.


在 3.9 版被加入.

@end deffn

@geindex PyInterpreterState_GetID (C function)
@anchor{c-api/init c PyInterpreterState_GetID}@anchor{dba}
@deffn {C 函式} int64_t PyInterpreterState_GetID (PyInterpreterState *interp)
` 為 @ref{76e,,穩定 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.

呼叫者必須擁有一個 @ref{4d99,,attached thread state}。


在 3.7 版被加入.

@end deffn

@geindex PyInterpreterState_GetDict (C function)
@anchor{c-api/init c PyInterpreterState_GetDict}@anchor{4ec6}
@deffn {C 函式} @ref{5d7,,PyObject} *PyInterpreterState_GetDict (PyInterpreterState *interp)
`回傳值：借用參照。'` 為 @ref{76e,,穩定 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{b6e,,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.


在 3.8 版被加入.

@end deffn

@geindex _PyFrameEvalFunction (C type)
@anchor{c-api/init c _PyFrameEvalFunction}@anchor{972}
@deffn {C 型別} typedef @ref{5d7,,PyObject} *(*_PyFrameEvalFunction)(@ref{988,,PyThreadState} *tstate, @ref{18d3,,_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/init c _PyInterpreterState_GetEvalFrameFunc}@anchor{1c40}
@deffn {C 函式} @ref{972,,_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".


在 3.9 版被加入.

@end deffn

@geindex _PyInterpreterState_SetEvalFrameFunc (C function)
@anchor{c-api/init c _PyInterpreterState_SetEvalFrameFunc}@anchor{1c41}
@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".


在 3.9 版被加入.

@end deffn

@geindex PyThreadState_GetDict (C function)
@anchor{c-api/init c PyThreadState_GetDict}@anchor{4f3f}
@deffn {C 函式} @ref{5d7,,PyObject} *PyThreadState_GetDict ()
`回傳值：借用參照。'` 為 @ref{76e,,穩定 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{17c4,,thread state}
is @ref{4d99,,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 PyThreadState_SetAsyncExc (C function)
@anchor{c-api/init c PyThreadState_SetAsyncExc}@anchor{db8}
@deffn {C 函式} int PyThreadState_SetAsyncExc (unsigned long id, PyObject *exc)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Asynchronously raise an exception in a thread. The `id' argument is the thread
id of the target thread; `exc' is the exception object to be raised. This
function does not steal any references to `exc'. To prevent naive misuse, you
must write your own C extension to call this.  Must be called with an @ref{4d99,,attached thread state}.
Returns the number of thread states modified; this is normally one, but will be
zero if the thread id isn't found.  If `exc' is @code{NULL}, the pending
exception (if any) for the thread is cleared. This raises no exceptions.


在 3.7 版的變更: The type of the `id' parameter changed from long to
unsigned long.

@end deffn

@geindex PyEval_AcquireThread (C function)
@anchor{c-api/init c PyEval_AcquireThread}@anchor{641}
@deffn {C 函式} void PyEval_AcquireThread (PyThreadState *tstate)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@ref{4d99,,Attach} `tstate' to the current thread,
which must not be @code{NULL} or already @ref{4d99,,attached}.

The calling thread must not already have an @ref{4d99,,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{52b3,,Cautions regarding runtime finalization} for more details.
@end quotation
@end cartouche


在 3.8 版的變更: Updated to be consistent with @ref{640,,PyEval_RestoreThread()},
@ref{c76,,Py_END_ALLOW_THREADS()}, and @ref{642,,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{640,,PyEval_RestoreThread()} is a higher-level function which is always
available (even when threads have not been initialized).
@end deffn

@geindex PyEval_ReleaseThread (C function)
@anchor{c-api/init c PyEval_ReleaseThread}@anchor{4e6a}
@deffn {C 函式} void PyEval_ReleaseThread (PyThreadState *tstate)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Detach the @ref{4d99,,attached thread state}.
The `tstate' argument, which must not be @code{NULL}, is only used to check
that it represents the @ref{4d99,,attached thread state} --- if it isn't, a fatal error is
reported.

@ref{63f,,PyEval_SaveThread()} is a higher-level function which is always
available (even when threads have not been initialized).
@end deffn

@node Sub-interpreter support,Asynchronous Notifications,Thread State and the Global Interpreter Lock,初始化、終結化與執行緒
@anchor{c-api/init id2}@anchor{52bc}@anchor{c-api/init sub-interpreter-support}@anchor{163}
@subsection Sub-interpreter support


While in most uses, you will only embed a single Python interpreter, there
are cases where you need to create several independent interpreters in the
same process and perhaps even in the same thread. Sub-interpreters allow
you to do that.

The "main" interpreter is the first one created when the runtime initializes.
It is usually the only Python interpreter in a process.  Unlike sub-interpreters,
the main interpreter has unique process-global responsibilities like signal
handling.  It is also responsible for execution during runtime initialization and
is usually the active interpreter during runtime finalization.  The
@ref{52bd,,PyInterpreterState_Main()} function returns a pointer to its state.

You can switch between sub-interpreters using the @ref{4f41,,PyThreadState_Swap()}
function. You can create and destroy them using the following functions:

@geindex PyInterpreterConfig (C type)
@anchor{c-api/init c PyInterpreterConfig}@anchor{787}
@deffn {C 型別} type PyInterpreterConfig

Structure containing most parameters to configure a sub-interpreter.
Its values are used only in @ref{682,,Py_NewInterpreterFromConfig()} and
never modified by the runtime.


在 3.12 版被加入.


Structure fields:

@geindex PyInterpreterConfig.use_main_obmalloc (C member)
@anchor{c-api/init c PyInterpreterConfig use_main_obmalloc}@anchor{47d0}
@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{52be,,check_multi_interp_extensions}
must be @code{1} (non-zero).
If this is @code{1} then @ref{52bf,,gil}
must not be @ref{52c0,,PyInterpreterConfig_OWN_GIL}.
@end deffn

@geindex PyInterpreterConfig.allow_fork (C member)
@anchor{c-api/init c PyInterpreterConfig allow_fork}@anchor{52c1}
@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{dc,,subprocess} module still works
when fork is disallowed.
@end deffn

@geindex PyInterpreterConfig.allow_exec (C member)
@anchor{c-api/init c PyInterpreterConfig allow_exec}@anchor{52c2}
@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{2ecb,,os.execv()}) in any thread
where the sub-interpreter is currently active.
Otherwise exec is unrestricted.

Note that the @ref{dc,,subprocess} module still works
when exec is disallowed.
@end deffn

@geindex PyInterpreterConfig.allow_threads (C member)
@anchor{c-api/init c PyInterpreterConfig allow_threads}@anchor{52c3}
@deffn {C 成員函數} int allow_threads

If this is @code{0} then the sub-interpreter's @ref{f3,,threading} module
won't create threads.
Otherwise threads are allowed.
@end deffn

@geindex PyInterpreterConfig.allow_daemon_threads (C member)
@anchor{c-api/init c PyInterpreterConfig allow_daemon_threads}@anchor{52c4}
@deffn {C 成員函數} int allow_daemon_threads

If this is @code{0} then the sub-interpreter's @ref{f3,,threading} module
won't create daemon threads.
Otherwise daemon threads are allowed (as long as
@ref{52c3,,allow_threads} is non-zero).
@end deffn

@geindex PyInterpreterConfig.check_multi_interp_extensions (C member)
@anchor{c-api/init c PyInterpreterConfig check_multi_interp_extensions}@anchor{52be}
@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{5000,,Py_mod_multiple_interpreters}.)

This must be @code{1} (non-zero) if
@ref{47d0,,use_main_obmalloc} is @code{0}.
@end deffn

@geindex PyInterpreterConfig.gil (C member)
@anchor{c-api/init c PyInterpreterConfig gil}@anchor{52bf}
@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/init c PyInterpreterConfig_DEFAULT_GIL}@anchor{52c5}
@deffn {C 巨集} PyInterpreterConfig_DEFAULT_GIL

Use the default selection (@ref{52c6,,PyInterpreterConfig_SHARED_GIL}).
@end deffn

@geindex PyInterpreterConfig_SHARED_GIL (C macro)
@anchor{c-api/init c PyInterpreterConfig_SHARED_GIL}@anchor{52c6}
@deffn {C 巨集} PyInterpreterConfig_SHARED_GIL

Use (share) the main interpreter's GIL.
@end deffn

@geindex PyInterpreterConfig_OWN_GIL (C macro)
@anchor{c-api/init c PyInterpreterConfig_OWN_GIL}@anchor{52c0}
@deffn {C 巨集} PyInterpreterConfig_OWN_GIL

Use the sub-interpreter's own GIL.
@end deffn

If this is @ref{52c0,,PyInterpreterConfig_OWN_GIL} then
@ref{47d0,,PyInterpreterConfig.use_main_obmalloc} must be @code{0}.
@end deffn
@end deffn

@geindex Py_NewInterpreterFromConfig (C function)
@anchor{c-api/init c Py_NewInterpreterFromConfig}@anchor{682}
@deffn {C 函式} @ref{b9b,,PyStatus} Py_NewInterpreterFromConfig (PyThreadState **tstate_p, const PyInterpreterConfig *config)

@geindex 模組;builtins（內建）
@geindex 模組;__main__
@geindex 模組;sys
@geindex stdout（sys 模組中）
@geindex stderr（sys 模組中）
@geindex stdin（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{df,,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{17c4,,thread state}
created in the new sub-interpreter.  This thread state is
@ref{4d99,,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
@ref{4d99,,attached thread state}, which might not exist.

Like all other Python/C API functions, an @ref{4d99,,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 @ref{4d99,,attached}.
If the sub-interpreter is created with its own @ref{164,,GIL} then the
@ref{4d99,,attached thread state} of the calling interpreter will be detached.
When the function returns, the new interpreter's @ref{17c4,,thread state}
will be @ref{4d99,,attached} to the current thread and
the previous interpreter's @ref{4d99,,attached thread state} will remain detached.


在 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{ab1,,PyInterpreterState} values.  A read-only copy of the config
may be stored internally on the @ref{ab1,,PyInterpreterState}.

@geindex Py_FinalizeEx（C 函式）
@geindex Py_Initialize（C 函式）

Extension modules are shared between (sub-)interpreters as follows:


@itemize *

@item 
For modules using multi-phase initialization,
e.g. @ref{10ae,,PyModule_FromDefAndSpec()}, a separate module object is
created and initialized for each interpreter.
Only C-level static and global variables are shared between these
module objects.

@item 
For modules using single-phase initialization,
e.g. @ref{5007,,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{52c7,,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{f0c,,Py_FinalizeEx()} and @ref{45e,,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（os 模組中）
@end deffn

@geindex Py_NewInterpreter (C function)
@anchor{c-api/init c Py_NewInterpreter}@anchor{1a72}
@deffn {C 函式} @ref{988,,PyThreadState} *Py_NewInterpreter (void)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@geindex 模組;builtins（內建）
@geindex 模組;__main__
@geindex 模組;sys
@geindex stdout（sys 模組中）
@geindex stderr（sys 模組中）
@geindex stdin（sys 模組中）

Create a new sub-interpreter.  This is essentially just a wrapper
around @ref{682,,Py_NewInterpreterFromConfig()} with a config that
preserves the existing behavior.  The result is an unisolated
sub-interpreter that shares the main interpreter's GIL, allows
fork/exec, allows daemon threads, and allows single-phase init
modules.
@end deffn

@geindex Py_EndInterpreter (C function)
@anchor{c-api/init c Py_EndInterpreter}@anchor{17c3}
@deffn {C 函式} void Py_EndInterpreter (PyThreadState *tstate)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@geindex Py_FinalizeEx（C 函式）

Destroy the (sub-)interpreter represented by the given @ref{17c4,,thread state}.
The given thread state must be @ref{4d99,,attached}.
When the call returns, there will be no @ref{4d99,,attached thread state}.
All thread states associated with this interpreter are destroyed.

@ref{f0c,,Py_FinalizeEx()} will destroy all sub-interpreters that
haven't been explicitly destroyed at that point.
@end deffn

@menu
* 直譯器各別持有的 GIL:: 
* Bugs and caveats:: 

@end menu

@node 直譯器各別持有的 GIL,Bugs and caveats,,Sub-interpreter support
@anchor{c-api/init a-per-interpreter-gil}@anchor{52c8}@anchor{c-api/init per-interpreter-gil}@anchor{52b6}
@subsubsection 直譯器各別持有的 GIL


Using @ref{682,,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{290,,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.


在 3.12 版被加入.


@node Bugs and caveats,,直譯器各別持有的 GIL,Sub-interpreter support
@anchor{c-api/init bugs-and-caveats}@anchor{52c7}
@subsubsection Bugs and caveats


Because sub-interpreters (and the main interpreter) are part of the same
process, the insulation between them isn't perfect --- for example, using
low-level file operations like  @ref{d63,,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{642,,PyGILState_Ensure()} and @ref{643,,PyGILState_Release()} calls.
Furthermore, extensions (such as @ref{2e,,ctypes}) using these APIs to allow calling
of Python code from non-Python created threads will probably be broken when using
sub-interpreters.

@node Asynchronous Notifications,Profiling and Tracing,Sub-interpreter support,初始化、終結化與執行緒
@anchor{c-api/init asynchronous-notifications}@anchor{52c9}
@subsection Asynchronous Notifications


A mechanism is provided to make asynchronous notifications to the main
interpreter thread.  These notifications take the form of a function
pointer and a void pointer argument.

@geindex Py_AddPendingCall (C function)
@anchor{c-api/init c Py_AddPendingCall}@anchor{b6f}
@deffn {C 函式} int Py_AddPendingCall (int (*func)(void*), void *arg)
` 為 @ref{76e,,穩定 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{4a5,,bytecode} boundary;

@item 
with the main thread holding an @ref{4d99,,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{4d99,,thread state} is detached.

This function doesn't need an @ref{4d99,,attached thread state}. However, to call this
function in a subinterpreter, the caller must have an @ref{4d99,,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 the @ref{52af,,PyGILState API}.
@end quotation
@end cartouche


在 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

@node Profiling and Tracing,Reference tracing,Asynchronous Notifications,初始化、終結化與執行緒
@anchor{c-api/init profiling}@anchor{52ca}@anchor{c-api/init profiling-and-tracing}@anchor{52cb}
@subsection Profiling and Tracing


The Python interpreter provides some low-level support for attaching profiling
and execution tracing facilities.  These are used for profiling, debugging, and
coverage analysis tools.

This C interface allows the profiling or tracing code to avoid the overhead of
calling through Python-level callable objects, making a direct C function call
instead.  The essential attributes of the facility have not changed; the
interface allows trace functions to be installed per-thread, and the basic
events reported to the trace function are the same as had been reported to the
Python-level trace functions in previous versions.

@geindex Py_tracefunc (C type)
@anchor{c-api/init c Py_tracefunc}@anchor{52cc}
@deffn {C 型別} typedef int (*Py_tracefunc)(@ref{5d7,,PyObject} *obj, @ref{984,,PyFrameObject} *frame, int what, @ref{5d7,,PyObject} *arg)

The type of the trace function registered using @ref{16f1,,PyEval_SetProfile()} and
@ref{65b,,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{52cd,,PyTrace_CALL},
@ref{52ce,,PyTrace_EXCEPTION}, @ref{52cf,,PyTrace_LINE}, @ref{52d0,,PyTrace_RETURN},
@ref{52d1,,PyTrace_C_CALL}, @ref{52d2,,PyTrace_C_EXCEPTION}, @ref{52d3,,PyTrace_C_RETURN},
or @ref{52d4,,PyTrace_OPCODE}, and `arg' depends on the value of `what':


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

`what' 的值

@tab

`arg' 的含義

@item

@ref{52cd,,PyTrace_CALL}

@tab

Always @ref{4d67,,Py_None}.

@item

@ref{52ce,,PyTrace_EXCEPTION}

@tab

Exception information as returned by
@ref{893,,sys.exc_info()}.

@item

@ref{52cf,,PyTrace_LINE}

@tab

Always @ref{4d67,,Py_None}.

@item

@ref{52d0,,PyTrace_RETURN}

@tab

Value being returned to the caller,
or @code{NULL} if caused by an exception.

@item

@ref{52d1,,PyTrace_C_CALL}

@tab

被呼叫的函式物件。

@item

@ref{52d2,,PyTrace_C_EXCEPTION}

@tab

被呼叫的函式物件。

@item

@ref{52d3,,PyTrace_C_RETURN}

@tab

被呼叫的函式物件。

@item

@ref{52d4,,PyTrace_OPCODE}

@tab

Always @ref{4d67,,Py_None}.

@end multitable

@end deffn

@geindex PyTrace_CALL (C var)
@anchor{c-api/init c PyTrace_CALL}@anchor{52cd}
@deffn {C 變數} int PyTrace_CALL

The value of the `what' parameter to a @ref{52cc,,Py_tracefunc} function when a new
call to a function or method is being reported, or a new entry into a generator.
Note that the creation of the iterator for a generator function is not reported
as there is no control transfer to the Python bytecode in the corresponding
frame.
@end deffn

@geindex PyTrace_EXCEPTION (C var)
@anchor{c-api/init c PyTrace_EXCEPTION}@anchor{52ce}
@deffn {C 變數} int PyTrace_EXCEPTION

The value of the `what' parameter to a @ref{52cc,,Py_tracefunc} function when an
exception has been raised.  The callback function is called with this value for
`what' when after any bytecode is processed after which the exception becomes
set within the frame being executed.  The effect of this is that as exception
propagation causes the Python stack to unwind, the callback is called upon
return to each frame as the exception propagates.  Only trace functions receives
these events; they are not needed by the profiler.
@end deffn

@geindex PyTrace_LINE (C var)
@anchor{c-api/init c PyTrace_LINE}@anchor{52cf}
@deffn {C 變數} int PyTrace_LINE

The value passed as the `what' parameter to a @ref{52cc,,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{dd1,,f_trace_lines} to
`0' on that frame.
@end deffn

@geindex PyTrace_RETURN (C var)
@anchor{c-api/init c PyTrace_RETURN}@anchor{52d0}
@deffn {C 變數} int PyTrace_RETURN

The value for the `what' parameter to @ref{52cc,,Py_tracefunc} functions when a
call is about to return.
@end deffn

@geindex PyTrace_C_CALL (C var)
@anchor{c-api/init c PyTrace_C_CALL}@anchor{52d1}
@deffn {C 變數} int PyTrace_C_CALL

The value for the `what' parameter to @ref{52cc,,Py_tracefunc} functions when a C
function is about to be called.
@end deffn

@geindex PyTrace_C_EXCEPTION (C var)
@anchor{c-api/init c PyTrace_C_EXCEPTION}@anchor{52d2}
@deffn {C 變數} int PyTrace_C_EXCEPTION

The value for the `what' parameter to @ref{52cc,,Py_tracefunc} functions when a C
function has raised an exception.
@end deffn

@geindex PyTrace_C_RETURN (C var)
@anchor{c-api/init c PyTrace_C_RETURN}@anchor{52d3}
@deffn {C 變數} int PyTrace_C_RETURN

The value for the `what' parameter to @ref{52cc,,Py_tracefunc} functions when a C
function has returned.
@end deffn

@geindex PyTrace_OPCODE (C var)
@anchor{c-api/init c PyTrace_OPCODE}@anchor{52d4}
@deffn {C 變數} int PyTrace_OPCODE

The value for the `what' parameter to @ref{52cc,,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{dd2,,f_trace_opcodes} to `1' on the frame.
@end deffn

@geindex PyEval_SetProfile (C function)
@anchor{c-api/init c PyEval_SetProfile}@anchor{16f1}
@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{52cf,,PyTrace_LINE}
@ref{52d4,,PyTrace_OPCODE} and @ref{52ce,,PyTrace_EXCEPTION}.

另請參閱 @ref{16f2,,sys.setprofile()} 函式。

呼叫者必須擁有一個 @ref{4d99,,attached thread state}。
@end deffn

@geindex PyEval_SetProfileAllThreads (C function)
@anchor{c-api/init c PyEval_SetProfileAllThreads}@anchor{77a}
@deffn {C 函式} void PyEval_SetProfileAllThreads (Py_tracefunc func, PyObject *obj)

Like @ref{16f1,,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.

呼叫者必須擁有一個 @ref{4d99,,attached thread state}。

As @ref{16f1,,PyEval_SetProfile()}, this function ignores any exceptions raised while
setting the profile functions in all threads.
@end deffn


在 3.12 版被加入.


@geindex PyEval_SetTrace (C function)
@anchor{c-api/init c PyEval_SetTrace}@anchor{65b}
@deffn {C 函式} void PyEval_SetTrace (Py_tracefunc func, PyObject *obj)

Set the tracing function to `func'.  This is similar to
@ref{16f1,,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{65b,,PyEval_SetTrace()}
will not receive @ref{52d1,,PyTrace_C_CALL}, @ref{52d2,,PyTrace_C_EXCEPTION} or
@ref{52d3,,PyTrace_C_RETURN} as a value for the `what' parameter.

也請見 @ref{2e1,,sys.settrace()} 函式。

呼叫者必須擁有一個 @ref{4d99,,attached thread state}。
@end deffn

@geindex PyEval_SetTraceAllThreads (C function)
@anchor{c-api/init c PyEval_SetTraceAllThreads}@anchor{65c}
@deffn {C 函式} void PyEval_SetTraceAllThreads (Py_tracefunc func, PyObject *obj)

Like @ref{65b,,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.

呼叫者必須擁有一個 @ref{4d99,,attached thread state}。

As @ref{65b,,PyEval_SetTrace()}, this function ignores any exceptions raised while
setting the trace functions in all threads.
@end deffn


在 3.12 版被加入.


@node Reference tracing,Advanced Debugger Support,Profiling and Tracing,初始化、終結化與執行緒
@anchor{c-api/init reference-tracing}@anchor{52d5}
@subsection Reference tracing



在 3.13 版被加入.


@geindex PyRefTracer (C type)
@anchor{c-api/init c PyRefTracer}@anchor{52d6}
@deffn {C 型別} typedef int (*PyRefTracer)(@ref{5d7,,PyObject}*, int event, void *data)

The type of the trace function registered using @ref{608,,PyRefTracer_SetTracer()}.
The first parameter is a Python object that has been just created (when `event'
is set to @ref{52d7,,PyRefTracer_CREATE}) or about to be destroyed (when `event'
is set to @ref{52d8,,PyRefTracer_DESTROY}). The `data' argument is the opaque pointer
that was provided when @ref{608,,PyRefTracer_SetTracer()} was called.
@end deffn


在 3.13 版被加入.


@geindex PyRefTracer_CREATE (C var)
@anchor{c-api/init c PyRefTracer_CREATE}@anchor{52d7}
@deffn {C 變數} int PyRefTracer_CREATE

The value for the `event' parameter to @ref{52d6,,PyRefTracer} functions when a Python
object has been created.
@end deffn

@geindex PyRefTracer_DESTROY (C var)
@anchor{c-api/init c PyRefTracer_DESTROY}@anchor{52d8}
@deffn {C 變數} int PyRefTracer_DESTROY

The value for the `event' parameter to @ref{52d6,,PyRefTracer} functions when a Python
object has been destroyed.
@end deffn

@geindex PyRefTracer_SetTracer (C function)
@anchor{c-api/init c PyRefTracer_SetTracer}@anchor{608}
@deffn {C 函式} int PyRefTracer_SetTracer (PyRefTracer tracer, void *data)

Register a reference tracer function. The function will be called when a new
Python has been created or when an object is going to be destroyed. If
`data' is provided it must be an opaque pointer that will be provided when
the tracer function is called. Return @code{0} on success. Set an exception and
return @code{-1} on error.

Not that tracer functions `must not' create Python objects inside or
otherwise the call will be re-entrant. The tracer also `must not' clear
any existing exception or set an exception.  A @ref{17c4,,thread state} will be active
every time the tracer function is called.

There must be an @ref{4d99,,attached thread state} when calling this function.
@end deffn


在 3.13 版被加入.


@geindex PyRefTracer_GetTracer (C function)
@anchor{c-api/init c PyRefTracer_GetTracer}@anchor{609}
@deffn {C 函式} @ref{52d6,,PyRefTracer} PyRefTracer_GetTracer (void **data)

Get the registered reference tracer function and the value of the opaque data
pointer that was registered when @ref{608,,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{4d99,,attached thread state} when calling this function.
@end deffn


在 3.13 版被加入.


@node Advanced Debugger Support,Thread Local Storage Support,Reference tracing,初始化、終結化與執行緒
@anchor{c-api/init advanced-debugger-support}@anchor{52d9}@anchor{c-api/init advanced-debugging}@anchor{52da}
@subsection Advanced Debugger Support


These functions are only intended to be used by advanced debugging tools.

@geindex PyInterpreterState_Head (C function)
@anchor{c-api/init c PyInterpreterState_Head}@anchor{16f3}
@deffn {C 函式} @ref{ab1,,PyInterpreterState} *PyInterpreterState_Head ()

Return the interpreter state object at the head of the list of all such objects.
@end deffn

@geindex PyInterpreterState_Main (C function)
@anchor{c-api/init c PyInterpreterState_Main}@anchor{52bd}
@deffn {C 函式} @ref{ab1,,PyInterpreterState} *PyInterpreterState_Main ()

Return the main interpreter state object.
@end deffn

@geindex PyInterpreterState_Next (C function)
@anchor{c-api/init c PyInterpreterState_Next}@anchor{16f4}
@deffn {C 函式} @ref{ab1,,PyInterpreterState} *PyInterpreterState_Next (PyInterpreterState *interp)

Return the next interpreter state object after `interp' from the list of all
such objects.
@end deffn

@geindex PyInterpreterState_ThreadHead (C function)
@anchor{c-api/init c PyInterpreterState_ThreadHead}@anchor{16f5}
@deffn {C 函式} @ref{988,,PyThreadState} *PyInterpreterState_ThreadHead (PyInterpreterState *interp)

Return the pointer to the first @ref{988,,PyThreadState} object in the list of
threads associated with the interpreter `interp'.
@end deffn

@geindex PyThreadState_Next (C function)
@anchor{c-api/init c PyThreadState_Next}@anchor{16f6}
@deffn {C 函式} @ref{988,,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{ab1,,PyInterpreterState} object.
@end deffn

@node Thread Local Storage Support,Synchronization Primitives,Advanced Debugger Support,初始化、終結化與執行緒
@anchor{c-api/init thread-local-storage}@anchor{52db}@anchor{c-api/init thread-local-storage-support}@anchor{52dc}
@subsection Thread Local Storage Support


The Python interpreter provides low-level support for thread-local storage
(TLS) which wraps the underlying native TLS implementation to support the
Python-level thread local storage API (@ref{17df,,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{17c4,,thread state} does `not' need to be @ref{4d99,,attached}
when calling these functions; they suppl 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{5d7,,PyObject}*, these
functions don't do refcount operations on them either.
@end quotation
@end cartouche

@menu
* Thread Specific Storage (TSS) API: Thread Specific Storage TSS API. 
* 執行緒局部儲存 (Thread Local Storage@comma{} TLS) API：: 執行緒局部儲存 Thread Local Storage TLS API：. 

@end menu

@node Thread Specific Storage TSS API,執行緒局部儲存 Thread Local Storage TLS API：,,Thread Local Storage Support
@anchor{c-api/init thread-specific-storage-api}@anchor{ccc}@anchor{c-api/init thread-specific-storage-tss-api}@anchor{52dd}
@subsubsection Thread Specific Storage (TSS) API


TSS API is introduced to supersede the use of the existing TLS API within the
CPython interpreter.  This API uses a new type @ref{ccd,,Py_tss_t} instead of
int to represent thread keys.


在 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/init c Py_tss_t}@anchor{ccd}
@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{76e,,Py_LIMITED_API} is not defined, static allocation of
this type by @ref{52de,,Py_tss_NEEDS_INIT} is allowed.
@end deffn

@geindex Py_tss_NEEDS_INIT (C macro)
@anchor{c-api/init c Py_tss_NEEDS_INIT}@anchor{52de}
@deffn {C 巨集} Py_tss_NEEDS_INIT

This macro expands to the initializer for @ref{ccd,,Py_tss_t} variables.
Note that this macro won't be defined with @ref{76e,,Py_LIMITED_API}.
@end deffn

@menu
* Dynamic Allocation:: 
* 方法: 方法<2>. 

@end menu

@node Dynamic Allocation,方法<2>,,Thread Specific Storage TSS API
@anchor{c-api/init dynamic-allocation}@anchor{52df}
@subsubsection Dynamic Allocation


Dynamic allocation of the @ref{ccd,,Py_tss_t}, required in extension modules
built with @ref{76e,,Py_LIMITED_API}, where static allocation of this type
is not possible due to its implementation being opaque at build time.

@geindex PyThread_tss_alloc (C function)
@anchor{c-api/init c PyThread_tss_alloc}@anchor{436}
@deffn {C 函式} @ref{ccd,,Py_tss_t} *PyThread_tss_alloc ()
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.7 版本開始.'
Return a value which is the same state as a value initialized with
@ref{52de,,Py_tss_NEEDS_INIT}, or @code{NULL} in the case of dynamic allocation
failure.
@end deffn

@geindex PyThread_tss_free (C function)
@anchor{c-api/init c PyThread_tss_free}@anchor{438}
@deffn {C 函式} void PyThread_tss_free (Py_tss_t *key)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.7 版本開始.'
Free the given `key' allocated by @ref{436,,PyThread_tss_alloc()}, after
first calling @ref{43e,,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 方法<2>,,Dynamic Allocation,Thread Specific Storage TSS API
@anchor{c-api/init methods}@anchor{52e0}
@subsubsection 方法


The parameter `key' of these functions must not be @code{NULL}.  Moreover, the
behaviors of @ref{43a,,PyThread_tss_set()} and @ref{43c,,PyThread_tss_get()} are
undefined if the given @ref{ccd,,Py_tss_t} has not been initialized by
@ref{4f42,,PyThread_tss_create()}.

@geindex PyThread_tss_is_created (C function)
@anchor{c-api/init c PyThread_tss_is_created}@anchor{4f43}
@deffn {C 函式} int PyThread_tss_is_created (Py_tss_t *key)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.7 版本開始.'
Return a non-zero value if the given @ref{ccd,,Py_tss_t} has been initialized
by @ref{4f42,,PyThread_tss_create()}.
@end deffn

@geindex PyThread_tss_create (C function)
@anchor{c-api/init c PyThread_tss_create}@anchor{4f42}
@deffn {C 函式} int PyThread_tss_create (Py_tss_t *key)
` 為 @ref{76e,,穩定 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{52de,,Py_tss_NEEDS_INIT}.  This function can be called
repeatedly on the same key -- calling it on an already initialized key is a
no-op and immediately returns success.
@end deffn

@geindex PyThread_tss_delete (C function)
@anchor{c-api/init c PyThread_tss_delete}@anchor{43e}
@deffn {C 函式} void PyThread_tss_delete (Py_tss_t *key)
` 為 @ref{76e,,穩定 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{4f42,,PyThread_tss_create()}. This function can be called repeatedly on
the same key -- calling it on an already destroyed key is a no-op.
@end deffn

@geindex PyThread_tss_set (C function)
@anchor{c-api/init c PyThread_tss_set}@anchor{43a}
@deffn {C 函式} int PyThread_tss_set (Py_tss_t *key, void *value)
` 為 @ref{76e,,穩定 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/init c PyThread_tss_get}@anchor{43c}
@deffn {C 函式} void *PyThread_tss_get (Py_tss_t *key)
` 為 @ref{76e,,穩定 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 執行緒局部儲存 Thread Local Storage TLS API：,,Thread Specific Storage TSS API,Thread Local Storage Support
@anchor{c-api/init thread-local-storage-api}@anchor{ccb}@anchor{c-api/init thread-local-storage-tls-api}@anchor{52e1}
@subsubsection 執行緒局部儲存 (Thread Local Storage, TLS) API：



在 3.7 版之後被棄用: This API is superseded by
@ref{ccc,,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{435,,PyThread_create_key()} will return immediately with a failure status,
and the other TLS functions will all be no-ops on such platforms.
@end quotation
@end cartouche

Due to the compatibility problem noted above, this version of the API should not
be used in new code.

@geindex PyThread_create_key (C function)
@anchor{c-api/init c PyThread_create_key}@anchor{435}
@deffn {C 函式} int PyThread_create_key ()
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@geindex PyThread_delete_key (C function)
@anchor{c-api/init c PyThread_delete_key}@anchor{437}
@deffn {C 函式} void PyThread_delete_key (int key)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@geindex PyThread_set_key_value (C function)
@anchor{c-api/init c PyThread_set_key_value}@anchor{439}
@deffn {C 函式} int PyThread_set_key_value (int key, void *value)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@geindex PyThread_get_key_value (C function)
@anchor{c-api/init c PyThread_get_key_value}@anchor{43b}
@deffn {C 函式} void *PyThread_get_key_value (int key)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@geindex PyThread_delete_key_value (C function)
@anchor{c-api/init c PyThread_delete_key_value}@anchor{43d}
@deffn {C 函式} void PyThread_delete_key_value (int key)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@geindex PyThread_ReInitTLS (C function)
@anchor{c-api/init c PyThread_ReInitTLS}@anchor{43f}
@deffn {C 函式} void PyThread_ReInitTLS ()
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@node Synchronization Primitives,,Thread Local Storage Support,初始化、終結化與執行緒
@anchor{c-api/init synchronization-primitives}@anchor{52e2}
@subsection Synchronization Primitives


The C-API provides a basic mutual exclusion lock.

@geindex PyMutex (C type)
@anchor{c-api/init c PyMutex}@anchor{47f}
@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


在 3.13 版被加入.

@end deffn

@geindex PyMutex_Lock (C function)
@anchor{c-api/init c PyMutex_Lock}@anchor{5c8}
@deffn {C 函式} void PyMutex_Lock (PyMutex *m)

Lock mutex `m'.  If another thread has already locked it, the calling
thread will block until the mutex is unlocked.  While blocked, the thread
will temporarily detach the @ref{4d99,,thread state} if one exists.


在 3.13 版被加入.

@end deffn

@geindex PyMutex_Unlock (C function)
@anchor{c-api/init c PyMutex_Unlock}@anchor{5c9}
@deffn {C 函式} void PyMutex_Unlock (PyMutex *m)

Unlock mutex `m'. The mutex must be locked --- otherwise, the function will
issue a fatal error.


在 3.13 版被加入.

@end deffn

@geindex PyMutex_IsLocked (C function)
@anchor{c-api/init c PyMutex_IsLocked}@anchor{461}
@deffn {C 函式} int PyMutex_IsLocked (PyMutex *m)

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


在 3.14 版被加入.

@end deffn

@menu
* Python Critical Section API:: 

@end menu

@node Python Critical Section API,,,Synchronization Primitives
@anchor{c-api/init id3}@anchor{52e3}@anchor{c-api/init python-critical-section-api}@anchor{52e4}
@subsubsection Python Critical Section API


The critical section API provides a deadlock avoidance layer on top of
per-object locks for @ref{1f4,,free-threaded} CPython.  They are
intended to replace reliance on the @ref{46e,,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{24d,,list} and @ref{183,,dict} because their public C-APIs
already use critical sections internally, with the notable
exception of @ref{18e9,,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{47f,,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{47f,,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{5d7,,PyObject} -- for example, when working with a C type that
does not extend or wrap @ref{5d7,,PyObject} but still needs to call into the C
API in a manner that might lead to deadlocks.

The functions and structs used by the macros are exposed for cases
where C macros are not available. They should only be used as in the
given macro expansions. Note that the sizes and contents of the structures may
change in future Python versions.

@cartouche
@quotation 備註 
Operations that need to lock two objects at once must use
@ref{52e5,,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
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{792,,Py_SETREF} calls @ref{789,,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{63f,,PyEval_SaveThread()}.

@geindex Py_BEGIN_CRITICAL_SECTION (C macro)
@anchor{c-api/init c Py_BEGIN_CRITICAL_SECTION}@anchor{518a}
@deffn {C 巨集} Py_BEGIN_CRITICAL_SECTION (op)

Acquires the per-object lock for the object `op' and begins a
critical section.

In the free-threaded build, this macro expands to:

@example
@{
    PyCriticalSection _py_cs;
    PyCriticalSection_Begin(&_py_cs, (PyObject*)(op))
@end example

In the default build, this macro expands to @code{@{}.


在 3.13 版被加入.

@end deffn

@geindex Py_BEGIN_CRITICAL_SECTION_MUTEX (C macro)
@anchor{c-api/init c Py_BEGIN_CRITICAL_SECTION_MUTEX}@anchor{52e6}
@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{518a,,Py_BEGIN_CRITICAL_SECTION}, there is no cast for
the argument of the macro - it must be a @ref{47f,,PyMutex} pointer.

On the default build, this macro expands to @code{@{}.


在 3.14 版被加入.

@end deffn

@geindex Py_END_CRITICAL_SECTION (C macro)
@anchor{c-api/init c Py_END_CRITICAL_SECTION}@anchor{52e7}
@deffn {C 巨集} Py_END_CRITICAL_SECTION ()

Ends the critical section and releases the per-object lock.

In the free-threaded build, this macro expands to:

@example
    PyCriticalSection_End(&_py_cs);
@}
@end example

In the default build, this macro expands to @code{@}}.


在 3.13 版被加入.

@end deffn

@geindex Py_BEGIN_CRITICAL_SECTION2 (C macro)
@anchor{c-api/init c Py_BEGIN_CRITICAL_SECTION2}@anchor{52e5}
@deffn {C 巨集} Py_BEGIN_CRITICAL_SECTION2 (a, b)

Acquires the per-objects locks for the objects `a' and `b' and begins a
critical section.  The locks are acquired in a consistent order (lowest
address first) to avoid lock ordering deadlocks.

In the free-threaded build, this macro expands to:

@example
@{
    PyCriticalSection2 _py_cs2;
    PyCriticalSection2_Begin(&_py_cs2, (PyObject*)(a), (PyObject*)(b))
@end example

In the default build, this macro expands to @code{@{}.


在 3.13 版被加入.

@end deffn

@geindex Py_BEGIN_CRITICAL_SECTION2_MUTEX (C macro)
@anchor{c-api/init c Py_BEGIN_CRITICAL_SECTION2_MUTEX}@anchor{52e8}
@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, this macro expands to:

@example
@{
     PyCriticalSection2 _py_cs2;
     PyCriticalSection2_BeginMutex(&_py_cs2, m1, m2)
@end example

Note that unlike @ref{52e5,,Py_BEGIN_CRITICAL_SECTION2}, there is no cast for
the arguments of the macro - they must be @ref{47f,,PyMutex} pointers.

On the default build, this macro expands to @code{@{}.


在 3.14 版被加入.

@end deffn

@geindex Py_END_CRITICAL_SECTION2 (C macro)
@anchor{c-api/init c Py_END_CRITICAL_SECTION2}@anchor{52e9}
@deffn {C 巨集} Py_END_CRITICAL_SECTION2 ()

Ends the critical section and releases the per-object locks.

In the free-threaded build, this macro expands to:

@example
    PyCriticalSection2_End(&_py_cs2);
@}
@end example

In the default build, this macro expands to @code{@}}.


在 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 初始化設定,記憶體管理,初始化、終結化與執行緒,Python/C API 參考手冊
@anchor{c-api/init_config doc}@anchor{52ea}@anchor{c-api/init_config init-config}@anchor{63e}@anchor{c-api/init_config python-initialization-configuration}@anchor{52eb}@anchor{c-api/init_config translation-repo}@anchor{52ec}
@section Python 初始化設定


@menu
* PyInitConfig C API:: 
* Configuration Options:: 
* Runtime Python configuration API:: 
* PyConfig C API:: 
* Py_GetArgcArgv(): Py_GetArgcArgv. 
* Delaying main module execution:: 

@end menu

@node PyInitConfig C API,Configuration Options,,Python 初始化設定
@anchor{c-api/init_config pyinitconfig-api}@anchor{377}@anchor{c-api/init_config pyinitconfig-c-api}@anchor{52ed}
@subsection PyInitConfig C API



在 3.14 版被加入.


Python 可以使用 @ref{384,,Py_InitializeFromInitConfig()} 來初始化。

The @ref{bb3,,Py_RunMain()} function can be used to write a customized Python
program.

See also @ref{529c,,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
* 範例: 範例<53>. 
* 建立設定:: 
* 錯誤處理: 錯誤處理<2>. 
* Get Options:: 
* Set Options:: 
* 模組: 模組<5>. 
* 初始化 Python:: 

@end menu

@node 範例<53>,建立設定,,PyInitConfig C API
@anchor{c-api/init_config example}@anchor{52ee}
@subsubsection 範例


Example of customized Python always running with the @ref{503,,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 建立設定,錯誤處理<2>,範例<53>,PyInitConfig C API
@anchor{c-api/init_config create-config}@anchor{52ef}
@subsubsection 建立設定


@geindex PyInitConfig (C struct)
@anchor{c-api/init_config c PyInitConfig}@anchor{52f0}
@deffn {C 結構} 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{385}
@deffn {C 函式} @ref{52f0,,PyInitConfig} *PyInitConfig_Create (void)

Create a new initialization configuration using @ref{52f1,,Isolated Configuration} default values.

It must be freed by @ref{386,,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{386}
@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 錯誤處理<2>,Get Options,建立設定,PyInitConfig C API
@anchor{c-api/init_config error-handling}@anchor{52f2}
@subsubsection 錯誤處理


@geindex PyInitConfig_GetError (C function)
@anchor{c-api/init_config c PyInitConfig_GetError}@anchor{388}
@deffn {C 函式} int PyInitConfig_GetError (PyInitConfig *config, const char **err_msg)

取得 `config' 錯誤訊息。


@itemize *

@item 
如果設定了錯誤，則設置 `*err_msg' 並回傳 @code{1}。

@item 
如果沒有設定錯誤，則設定 `*err_msg' 為 @code{NULL} 並回傳 @code{0}。
@end itemize

錯誤訊息是 UTF-8 編碼的字串。

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{389}
@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,錯誤處理<2>,PyInitConfig C API
@anchor{c-api/init_config get-options}@anchor{52f3}
@subsubsection Get Options


The configuration option `name' parameter must be a non-NULL null-terminated
UTF-8 encoded string. See @ref{52f4,,Configuration Options}.

@geindex PyInitConfig_HasOption (C function)
@anchor{c-api/init_config c PyInitConfig_HasOption}@anchor{38d}
@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{38a}
@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{38b}
@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{38c}
@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{387}
@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,模組<5>,Get Options,PyInitConfig C API
@anchor{c-api/init_config set-options}@anchor{52f5}
@subsubsection Set Options


The configuration option `name' parameter must be a non-NULL null-terminated
UTF-8 encoded string. See @ref{52f4,,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{38e}
@deffn {C 函式} int PyInitConfig_SetInt (PyInitConfig *config, const char *name, int64_t value)

Set an integer configuration option.


@itemize *

@item 
成功時回傳 @code{0}。

@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{38f}
@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 
成功時回傳 @code{0}。

@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{390}
@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 
成功時回傳 @code{0}。

@item 
Set an error in `config' and return @code{-1} on error.
@end itemize
@end deffn

@node 模組<5>,初始化 Python,Set Options,PyInitConfig C API
@anchor{c-api/init_config module}@anchor{52f6}
@subsubsection 模組


@geindex PyInitConfig_AddModule (C function)
@anchor{c-api/init_config c PyInitConfig_AddModule}@anchor{379}
@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 
成功時回傳 @code{0}。

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

和 @ref{1a5f,,PyImport_AppendInittab()} 函式類似。
@end deffn

@node 初始化 Python,,模組<5>,PyInitConfig C API
@anchor{c-api/init_config initialize-python}@anchor{52f7}
@subsubsection 初始化 Python


@geindex Py_InitializeFromInitConfig (C function)
@anchor{c-api/init_config c Py_InitializeFromInitConfig}@anchor{384}
@deffn {C 函式} int Py_InitializeFromInitConfig (PyInitConfig *config)

Initialize Python from the initialization configuration.


@itemize *

@item 
成功時回傳 @code{0}。

@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 初始化設定
@anchor{c-api/init_config configuration-options}@anchor{52f8}@anchor{c-api/init_config pyinitconfig-opts}@anchor{52f4}
@subsection Configuration Options



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

選項

@tab

PyConfig/PyPreConfig 成員

@tab

Type

@tab

Visibility

@item

@code{"allocator"}

@tab

@ref{52f9,,allocator}

@tab

@code{int}

@tab

唯讀

@item

@code{"argv"}

@tab

@ref{3ef,,argv}

@tab

@code{list[str]}

@tab

公開

@item

@code{"base_exec_prefix"}

@tab

@ref{52fa,,base_exec_prefix}

@tab

@code{str}

@tab

公開

@item

@code{"base_executable"}

@tab

@ref{52fb,,base_executable}

@tab

@code{str}

@tab

公開

@item

@code{"base_prefix"}

@tab

@ref{52fc,,base_prefix}

@tab

@code{str}

@tab

公開

@item

@code{"buffered_stdio"}

@tab

@ref{40f,,buffered_stdio}

@tab

@code{bool}

@tab

唯讀

@item

@code{"bytes_warning"}

@tab

@ref{405,,bytes_warning}

@tab

@code{int}

@tab

公開

@item

@code{"check_hash_pycs_mode"}

@tab

@ref{52fd,,check_hash_pycs_mode}

@tab

@code{str}

@tab

唯讀

@item

@code{"code_debug_ranges"}

@tab

@ref{52fe,,code_debug_ranges}

@tab

@code{bool}

@tab

唯讀

@item

@code{"coerce_c_locale"}

@tab

@ref{52ff,,coerce_c_locale}

@tab

@code{bool}

@tab

唯讀

@item

@code{"coerce_c_locale_warn"}

@tab

@ref{5300,,coerce_c_locale_warn}

@tab

@code{bool}

@tab

唯讀

@item

@code{"configure_c_stdio"}

@tab

@ref{5301,,configure_c_stdio}

@tab

@code{bool}

@tab

唯讀

@item

@code{"configure_locale"}

@tab

@ref{5302,,configure_locale}

@tab

@code{bool}

@tab

唯讀

@item

@code{"cpu_count"}

@tab

@ref{5303,,cpu_count}

@tab

@code{int}

@tab

公開

@item

@code{"dev_mode"}

@tab

@ref{5304,,dev_mode}

@tab

@code{bool}

@tab

唯讀

@item

@code{"dump_refs"}

@tab

@ref{5305,,dump_refs}

@tab

@code{bool}

@tab

唯讀

@item

@code{"dump_refs_file"}

@tab

@ref{5306,,dump_refs_file}

@tab

@code{str}

@tab

唯讀

@item

@code{"exec_prefix"}

@tab

@ref{5307,,exec_prefix}

@tab

@code{str}

@tab

公開

@item

@code{"executable"}

@tab

@ref{63d,,executable}

@tab

@code{str}

@tab

公開

@item

@code{"faulthandler"}

@tab

@ref{5308,,faulthandler}

@tab

@code{bool}

@tab

唯讀

@item

@code{"filesystem_encoding"}

@tab

@ref{419,,filesystem_encoding}

@tab

@code{str}

@tab

唯讀

@item

@code{"filesystem_errors"}

@tab

@ref{41a,,filesystem_errors}

@tab

@code{str}

@tab

唯讀

@item

@code{"hash_seed"}

@tab

@ref{412,,hash_seed}

@tab

@code{int}

@tab

唯讀

@item

@code{"home"}

@tab

@ref{3f1,,home}

@tab

@code{str}

@tab

唯讀

@item

@code{"import_time"}

@tab

@ref{5309,,import_time}

@tab

@code{int}

@tab

唯讀

@item

@code{"inspect"}

@tab

@ref{3ff,,inspect}

@tab

@code{bool}

@tab

公開

@item

@code{"install_signal_handlers"}

@tab

@ref{ab2,,install_signal_handlers}

@tab

@code{bool}

@tab

唯讀

@item

@code{"int_max_str_digits"}

@tab

@ref{530a,,int_max_str_digits}

@tab

@code{int}

@tab

公開

@item

@code{"interactive"}

@tab

@ref{3fd,,interactive}

@tab

@code{bool}

@tab

公開

@item

@code{"isolated"}

@tab

@ref{414,,isolated}

@tab

@code{bool}

@tab

唯讀

@item

@code{"legacy_windows_fs_encoding"}

@tab

@ref{416,,legacy_windows_fs_encoding}

@tab

@code{bool}

@tab

唯讀

@item

@code{"legacy_windows_stdio"}

@tab

@ref{418,,legacy_windows_stdio}

@tab

@code{bool}

@tab

唯讀

@item

@code{"malloc_stats"}

@tab

@ref{530b,,malloc_stats}

@tab

@code{bool}

@tab

唯讀

@item

@code{"module_search_paths"}

@tab

@ref{63b,,module_search_paths}

@tab

@code{list[str]}

@tab

公開

@item

@code{"optimization_level"}

@tab

@ref{401,,optimization_level}

@tab

@code{int}

@tab

公開

@item

@code{"orig_argv"}

@tab

@ref{a8b,,orig_argv}

@tab

@code{list[str]}

@tab

唯讀

@item

@code{"parse_argv"}

@tab

@ref{1bdd,,parse_argv}

@tab

@code{bool}

@tab

唯讀

@item

@code{"parser_debug"}

@tab

@ref{3f7,,parser_debug}

@tab

@code{bool}

@tab

公開

@item

@code{"pathconfig_warnings"}

@tab

@ref{407,,pathconfig_warnings}

@tab

@code{bool}

@tab

唯讀

@item

@code{"perf_profiling"}

@tab

@ref{530c,,perf_profiling}

@tab

@code{bool}

@tab

唯讀

@item

@code{"platlibdir"}

@tab

@ref{1bf3,,platlibdir}

@tab

@code{str}

@tab

公開

@item

@code{"prefix"}

@tab

@ref{530d,,prefix}

@tab

@code{str}

@tab

公開

@item

@code{"surrogateescape"}

@tab

@ref{3f0,,program_name}

@tab

@code{str}

@tab

唯讀

@item

@code{"pycache_prefix"}

@tab

@ref{530e,,pycache_prefix}

@tab

@code{str}

@tab

公開

@item

@code{"quiet"}

@tab

@ref{3fb,,quiet}

@tab

@code{bool}

@tab

公開

@item

@code{"run_command"}

@tab

@ref{52a7,,run_command}

@tab

@code{str}

@tab

唯讀

@item

@code{"run_filename"}

@tab

@ref{52a8,,run_filename}

@tab

@code{str}

@tab

唯讀

@item

@code{"run_module"}

@tab

@ref{52a9,,run_module}

@tab

@code{str}

@tab

唯讀

@item

@code{"run_presite"}

@tab

@ref{530f,,run_presite}

@tab

@code{str}

@tab

唯讀

@item

@code{"safe_path"}

@tab

@ref{96f,,safe_path}

@tab

@code{bool}

@tab

唯讀

@item

@code{"show_ref_count"}

@tab

@ref{5310,,show_ref_count}

@tab

@code{bool}

@tab

唯讀

@item

@code{"site_import"}

@tab

@ref{403,,site_import}

@tab

@code{bool}

@tab

唯讀

@item

@code{"skip_source_first_line"}

@tab

@ref{5311,,skip_source_first_line}

@tab

@code{bool}

@tab

唯讀

@item

@code{"stdio_encoding"}

@tab

@ref{63c,,stdio_encoding}

@tab

@code{str}

@tab

唯讀

@item

@code{"stdio_errors"}

@tab

@ref{47df,,stdio_errors}

@tab

@code{str}

@tab

唯讀

@item

@code{"stdlib_dir"}

@tab

@ref{5312,,stdlib_dir}

@tab

@code{str}

@tab

公開

@item

@code{"tracemalloc"}

@tab

@ref{5313,,tracemalloc}

@tab

@code{int}

@tab

唯讀

@item

@code{"use_environment"}

@tab

@ref{409,,use_environment}

@tab

@code{bool}

@tab

公開

@item

@code{"use_frozen_modules"}

@tab

@ref{5314,,use_frozen_modules}

@tab

@code{bool}

@tab

唯讀

@item

@code{"use_hash_seed"}

@tab

@ref{411,,use_hash_seed}

@tab

@code{bool}

@tab

唯讀

@item

@code{"use_system_logger"}

@tab

@ref{2135,,use_system_logger}

@tab

@code{bool}

@tab

唯讀

@item

@code{"user_site_directory"}

@tab

@ref{40d,,user_site_directory}

@tab

@code{bool}

@tab

唯讀

@item

@code{"utf8_mode"}

@tab

@ref{41b,,utf8_mode}

@tab

@code{bool}

@tab

唯讀

@item

@code{"verbose"}

@tab

@ref{3f9,,verbose}

@tab

@code{int}

@tab

公開

@item

@code{"warn_default_encoding"}

@tab

@ref{5315,,warn_default_encoding}

@tab

@code{bool}

@tab

唯讀

@item

@code{"warnoptions"}

@tab

@ref{639,,warnoptions}

@tab

@code{list[str]}

@tab

公開

@item

@code{"write_bytecode"}

@tab

@ref{40b,,write_bytecode}

@tab

@code{bool}

@tab

公開

@item

@code{"xoptions"}

@tab

@ref{63a,,xoptions}

@tab

@code{dict[str, str]}

@tab

公開

@item

@code{"_pystats"}

@tab

@ref{5316,,_pystats}

@tab

@code{bool}

@tab

唯讀

@end multitable


Visibility:


@itemize *

@item 
Public: Can by get by @ref{37a,,PyConfig_Get()} and set by
@ref{37b,,PyConfig_Set()}.

@item 
Read-only: Can by get by @ref{37a,,PyConfig_Get()}, but cannot be set by
@ref{37b,,PyConfig_Set()}.
@end itemize

@node Runtime Python configuration API,PyConfig C API,Configuration Options,Python 初始化設定
@anchor{c-api/init_config runtime-python-configuration-api}@anchor{5317}
@subsection Runtime Python configuration API


At runtime, it's possible to get and set configuration options using
@ref{37a,,PyConfig_Get()} and  @ref{37b,,PyConfig_Set()} functions.

The configuration option `name' parameter must be a non-NULL null-terminated
UTF-8 encoded string. See @ref{52f4,,Configuration Options}.

Some options are read from the @ref{df,,sys} attributes. For example, the option
@code{"argv"} is read from @ref{1465,,sys.argv}.

@geindex PyConfig_Get (C function)
@anchor{c-api/init_config c PyConfig_Get}@anchor{37a}
@deffn {C 函式} @ref{5d7,,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{4d99,,attached thread state}. The function cannot
be called before Python initialization nor after Python finalization.


在 3.14 版被加入.

@end deffn

@geindex PyConfig_GetInt (C function)
@anchor{c-api/init_config c PyConfig_GetInt}@anchor{382}
@deffn {C 函式} int PyConfig_GetInt (const char *name, int *value)

Similar to @ref{37a,,PyConfig_Get()}, but get the value as a C int.


@itemize *

@item 
成功時回傳 @code{0}。

@item 
Set an exception and return @code{-1} on error.
@end itemize


在 3.14 版被加入.

@end deffn

@geindex PyConfig_Names (C function)
@anchor{c-api/init_config c PyConfig_Names}@anchor{383}
@deffn {C 函式} @ref{5d7,,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{4d99,,attached thread state}. The function cannot
be called before Python initialization nor after Python finalization.


在 3.14 版被加入.

@end deffn

@geindex PyConfig_Set (C function)
@anchor{c-api/init_config c PyConfig_Set}@anchor{37b}
@deffn {C 函式} int PyConfig_Set (const char *name, PyObject *value)

Set the current runtime value of a configuration option.


@itemize *

@item 
如果沒有選項 `name'，則引發 @ref{2eb,,ValueError}。

@item 
如果 `value' 是無效值，則引發 @ref{2eb,,ValueError}。

@item 
如果選項是唯讀的（無法設定），則引發 @ref{2eb,,ValueError}。

@item 
Raise a @ref{198,,TypeError} if `value' has not the proper type.
@end itemize

The caller must have an @ref{4d99,,attached thread state}. The function cannot
be called before Python initialization nor after Python finalization.

Raises an @ref{1b70,,auditing event} @code{cpython.PyConfig_Set} with arguments @code{name}, @code{value}.


在 3.14 版被加入.

@end deffn

@node PyConfig C API,Py_GetArgcArgv,Runtime Python configuration API,Python 初始化設定
@anchor{c-api/init_config pyconfig-api}@anchor{378}@anchor{c-api/init_config pyconfig-c-api}@anchor{5318}
@subsection PyConfig C API



在 3.8 版被加入.


Python can be initialized with @ref{3f5,,Py_InitializeFromConfig()} and the
@ref{3f4,,PyConfig} structure. It can be preinitialized with
@ref{41c,,Py_PreInitialize()} and the @ref{b9a,,PyPreConfig} structure.

There are two kinds of configuration:


@itemize *

@item 
The @ref{52aa,,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{52f1,,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{bb3,,Py_RunMain()} function can be used to write a customized Python
program.

See also @ref{529c,,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
* 範例: 範例<54>. 
* PyWideStringList:: 
* PyStatus:: 
* PyPreConfig:: 
* Preinitialize Python with PyPreConfig:: 
* PyConfig:: 
* Initialization with PyConfig:: 
* Isolated Configuration:: 
* Python Configuration:: 
* Python 路徑配置:: 

@end menu

@node 範例<54>,PyWideStringList,,PyConfig C API
@anchor{c-api/init_config id1}@anchor{5319}
@subsubsection 範例


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,範例<54>,PyConfig C API
@anchor{c-api/init_config pywidestringlist}@anchor{531a}
@subsubsection PyWideStringList


@geindex PyWideStringList (C type)
@anchor{c-api/init_config c PyWideStringList}@anchor{b9c}
@deffn {C 型別} type PyWideStringList

@code{wchar_t*} 字串串列。

If `length' is non-zero, `items' must be non-@code{NULL} and all strings must be
non-@code{NULL}.

方法：

@geindex PyWideStringList_Append (C function)
@anchor{c-api/init_config c PyWideStringList_Append}@anchor{bad}
@deffn {C 函式} @ref{b9b,,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{bae}
@deffn {C 函式} @ref{b9b,,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{531b}
@deffn {C 成員函數} @ref{c4c,,Py_ssize_t} length

串列長度。
@end deffn

@geindex PyWideStringList.items (C member)
@anchor{c-api/init_config c PyWideStringList items}@anchor{531c}
@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{531d}
@subsubsection PyStatus


@geindex PyStatus (C type)
@anchor{c-api/init_config c PyStatus}@anchor{b9b}
@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{531e}
@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{531f}
@deffn {C 成員函數} const char *err_msg

錯誤訊息。
@end deffn

@geindex PyStatus.func (C member)
@anchor{c-api/init_config c PyStatus func}@anchor{5320}
@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{bac}
@deffn {C 函式} @ref{b9b,,PyStatus} PyStatus_Ok (void)

成功。
@end deffn

@geindex PyStatus_Error (C function)
@anchor{c-api/init_config c PyStatus_Error}@anchor{ba6}
@deffn {C 函式} @ref{b9b,,PyStatus} PyStatus_Error (const char *err_msg)

附帶訊息的初始化錯誤。

`err_msg' 不可為 @code{NULL}。
@end deffn

@geindex PyStatus_NoMemory (C function)
@anchor{c-api/init_config c PyStatus_NoMemory}@anchor{bab}
@deffn {C 函式} @ref{b9b,,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{ba8}
@deffn {C 函式} @ref{b9b,,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{ba7}
@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{bb0,,Py_ExitStatusException()} for example.
@end deffn

@geindex PyStatus_IsError (C function)
@anchor{c-api/init_config c PyStatus_IsError}@anchor{ba9}
@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{baa}
@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{bb0}
@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
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{5321}
@subsubsection PyPreConfig


@geindex PyPreConfig (C type)
@anchor{c-api/init_config c PyPreConfig}@anchor{b9a}
@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{ba5}
@deffn {C 函式} void PyPreConfig_InitPythonConfig (PyPreConfig *preconfig)

Initialize the preconfiguration with @ref{52aa,,Python Configuration}.
@end deffn

@geindex PyPreConfig_InitIsolatedConfig (C function)
@anchor{c-api/init_config c PyPreConfig_InitIsolatedConfig}@anchor{ba4}
@deffn {C 函式} void PyPreConfig_InitIsolatedConfig (PyPreConfig *preconfig)

Initialize the preconfiguration with @ref{52f1,,Isolated Configuration}.
@end deffn

Structure fields:

@geindex PyPreConfig.allocator (C member)
@anchor{c-api/init_config c PyPreConfig allocator}@anchor{52f9}
@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{2002,,default memory allocators}.

@item 
@code{PYMEM_ALLOCATOR_DEBUG} (@code{2}): @ref{2002,,default memory allocators} with @ref{2005,,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{2005,,debug hooks}.

@item 
@code{PYMEM_ALLOCATOR_PYMALLOC} (@code{5}): @ref{f06,,Python pymalloc memory allocator}.

@item 
@code{PYMEM_ALLOCATOR_PYMALLOC_DEBUG} (@code{6}): @ref{f06,,Python pymalloc memory allocator} with @ref{2005,,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{2005,,debug hooks}.
@end itemize

@code{PYMEM_ALLOCATOR_PYMALLOC} and @code{PYMEM_ALLOCATOR_PYMALLOC_DEBUG} are
not supported if Python is @ref{2064,,configured using --without-pymalloc}.

@code{PYMEM_ALLOCATOR_MIMALLOC} and @code{PYMEM_ALLOCATOR_MIMALLOC_DEBUG} are
not supported if Python is @ref{2063,,configured using --without-mimalloc} or if the underlying atomic support isn't
available.

請見@ref{5322,,記憶體管理}。

預設：@code{PYMEM_ALLOCATOR_NOT_SET}。
@end deffn

@geindex PyPreConfig.configure_locale (C member)
@anchor{c-api/init_config c PyPreConfig configure_locale}@anchor{5302}
@deffn {C 成員函數} int configure_locale

Set the LC_CTYPE locale to the user preferred locale.

If equals to @code{0}, set @ref{52ff,,coerce_c_locale} and
@ref{5300,,coerce_c_locale_warn} members to @code{0}.

請見 @ref{545,,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{52ff}
@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.

請見 @ref{545,,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{5300}
@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{5323}
@deffn {C 成員函數} int dev_mode

@ref{503,,Python Development Mode}: see
@ref{5304,,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{5324}
@deffn {C 成員函數} int isolated

Isolated mode: see @ref{414,,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{416}
@deffn {C 成員函數} int legacy_windows_fs_encoding

如果不為 0：


@itemize *

@item 
將 @ref{41b,,PyPreConfig.utf8_mode} 設為 @code{0}、

@item 
將 @ref{419,,PyConfig.filesystem_encoding} 設為 @code{"mbcs"}、

@item 
將 @ref{41a,,PyConfig.filesystem_errors} 設為 @code{"replace"}。
@end itemize

Initialized from the 
@geindex PYTHONLEGACYWINDOWSFSENCODING
@geindex 環境變數; PYTHONLEGACYWINDOWSFSENCODING
@ref{33e,,PYTHONLEGACYWINDOWSFSENCODING} environment
variable value.

Only available on Windows. @code{#ifdef MS_WINDOWS} macro can be used for
Windows specific code.

預設：@code{0}。
@end deffn

@geindex PyPreConfig.parse_argv (C member)
@anchor{c-api/init_config c PyPreConfig parse_argv}@anchor{5325}
@deffn {C 成員函數} int parse_argv

If non-zero, @ref{bb1,,Py_PreInitializeFromArgs()} and
@ref{bb2,,Py_PreInitializeFromBytesArgs()} parse their @code{argv} argument the
same way the regular Python parses command line arguments: see
@ref{1202,,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{5326}
@deffn {C 成員函數} int use_environment

Use @ref{800,,environment variables}? See
@ref{409,,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{41b}
@deffn {C 成員函數} int utf8_mode

If non-zero, enable the @ref{85f,,Python UTF-8 Mode}.

Set to @code{0} or @code{1} by the @ref{16f,,-X utf8} command line option
and the 
@geindex PYTHONUTF8
@geindex 環境變數; PYTHONUTF8
@ref{cc6,,PYTHONUTF8} environment variable.

Also set to @code{1} if the @code{LC_CTYPE} locale is @code{C} or @code{POSIX}.

Default: @code{-1} in Python config and @code{0} in isolated config.
@end deffn
@end deffn

@node Preinitialize Python with PyPreConfig,PyConfig,PyPreConfig,PyConfig C API
@anchor{c-api/init_config c-preinit}@anchor{4183}@anchor{c-api/init_config preinitialize-python-with-pypreconfig}@anchor{5327}
@subsubsection Preinitialize Python with PyPreConfig


The preinitialization of Python:


@itemize *

@item 
Set the Python memory allocators (@ref{52f9,,PyPreConfig.allocator})

@item 
Configure the LC_CTYPE locale (@ref{545,,locale encoding})

@item 
Set the @ref{85f,,Python UTF-8 Mode}
(@ref{41b,,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{41c}
@deffn {C 函式} @ref{b9b,,PyStatus} Py_PreInitialize (const PyPreConfig *preconfig)

Preinitialize Python from `preconfig' preconfiguration.

`preconfig' 不可為 @code{NULL}。
@end deffn

@geindex Py_PreInitializeFromBytesArgs (C function)
@anchor{c-api/init_config c Py_PreInitializeFromBytesArgs}@anchor{bb2}
@deffn {C 函式} @ref{b9b,,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{5325,,parse_argv} of `preconfig' is non-zero.

`preconfig' 不可為 @code{NULL}。
@end deffn

@geindex Py_PreInitializeFromArgs (C function)
@anchor{c-api/init_config c Py_PreInitializeFromArgs}@anchor{bb1}
@deffn {C 函式} @ref{b9b,,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{5325,,parse_argv} of `preconfig' is non-zero.

`preconfig' 不可為 @code{NULL}。
@end deffn

The caller is responsible to handle exceptions (error or exit) using
@ref{ba7,,PyStatus_Exception()} and @ref{bb0,,Py_ExitStatusException()}.

For @ref{52aa,,Python Configuration}
(@ref{ba5,,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{16f,,-X utf8} command line option
enables the @ref{85f,,Python UTF-8 Mode}.

@code{PyMem_SetAllocator()} can be called after @ref{41c,,Py_PreInitialize()} and
before @ref{3f5,,Py_InitializeFromConfig()} to install a custom memory allocator.
It can be called before @ref{41c,,Py_PreInitialize()} if
@ref{52f9,,PyPreConfig.allocator} is set to @code{PYMEM_ALLOCATOR_NOT_SET}.

Python memory allocation functions like @ref{629,,PyMem_RawMalloc()} must not be
used before the Python preinitialization, whereas calling directly @code{malloc()}
and @code{free()} is always safe. @ref{dbb,,Py_DecodeLocale()} must not be called
before the Python preinitialization.

Example using the preinitialization to enable
the @ref{85f,,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{5328}
@subsubsection PyConfig


@geindex PyConfig (C type)
@anchor{c-api/init_config c PyConfig}@anchor{3f4}
@deffn {C 型別} type PyConfig

Structure containing most parameters to configure Python.

When done, the @ref{b9d,,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{b9f}
@deffn {C 函式} void PyConfig_InitPythonConfig (PyConfig *config)

Initialize configuration with the @ref{52aa,,Python Configuration}.
@end deffn

@geindex PyConfig_InitIsolatedConfig (C function)
@anchor{c-api/init_config c PyConfig_InitIsolatedConfig}@anchor{b9e}
@deffn {C 函式} void PyConfig_InitIsolatedConfig (PyConfig *config)

Initialize configuration with the @ref{52f1,,Isolated Configuration}.
@end deffn

@geindex PyConfig_SetString (C function)
@anchor{c-api/init_config c PyConfig_SetString}@anchor{ba3}
@deffn {C 函式} @ref{b9b,,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{4183,,Preinitialize Python} if needed.
@end deffn

@geindex PyConfig_SetBytesString (C function)
@anchor{c-api/init_config c PyConfig_SetBytesString}@anchor{ba2}
@deffn {C 函式} @ref{b9b,,PyStatus} PyConfig_SetBytesString (PyConfig *config, wchar_t *const *config_str, const char *str)

Decode `str' using @ref{dbb,,Py_DecodeLocale()} and set the result into
@code{*config_str}.

@ref{4183,,Preinitialize Python} if needed.
@end deffn

@geindex PyConfig_SetArgv (C function)
@anchor{c-api/init_config c PyConfig_SetArgv}@anchor{ba0}
@deffn {C 函式} @ref{b9b,,PyStatus} PyConfig_SetArgv (PyConfig *config, int argc, wchar_t *const *argv)

Set command line arguments (@ref{3ef,,argv} member of
`config') from the `argv' list of wide character strings.

@ref{4183,,Preinitialize Python} if needed.
@end deffn

@geindex PyConfig_SetBytesArgv (C function)
@anchor{c-api/init_config c PyConfig_SetBytesArgv}@anchor{ba1}
@deffn {C 函式} @ref{b9b,,PyStatus} PyConfig_SetBytesArgv (PyConfig *config, int argc, char *const *argv)

Set command line arguments (@ref{3ef,,argv} member of
`config') from the `argv' list of bytes strings. Decode bytes using
@ref{dbb,,Py_DecodeLocale()}.

@ref{4183,,Preinitialize Python} if needed.
@end deffn

@geindex PyConfig_SetWideStringList (C function)
@anchor{c-api/init_config c PyConfig_SetWideStringList}@anchor{1c92}
@deffn {C 函式} @ref{b9b,,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{4183,,Preinitialize Python} if needed.
@end deffn

@geindex PyConfig_Read (C function)
@anchor{c-api/init_config c PyConfig_Read}@anchor{98b}
@deffn {C 函式} @ref{b9b,,PyStatus} PyConfig_Read (PyConfig *config)

Read all Python configuration.

Fields which are already initialized are left unchanged.

Fields for @ref{aa1,,path configuration} are no longer
calculated or modified when calling this function, as of Python 3.11.

The @ref{98b,,PyConfig_Read()} function only parses
@ref{3ef,,PyConfig.argv} arguments once: @ref{1bdd,,PyConfig.parse_argv}
is set to @code{2} after arguments are parsed. Since Python arguments are
stripped from @ref{3ef,,PyConfig.argv}, parsing arguments twice would
parse the application options as Python options.

@ref{4183,,Preinitialize Python} if needed.


在 3.10 版的變更: The @ref{3ef,,PyConfig.argv} arguments are now only parsed once,
@ref{1bdd,,PyConfig.parse_argv} is set to @code{2} after arguments are
parsed, and arguments are only parsed if
@ref{1bdd,,PyConfig.parse_argv} equals @code{1}.



在 3.11 版的變更: @ref{98b,,PyConfig_Read()} no longer calculates all paths, and so fields
listed under @ref{aa1,,Python Path Configuration} may
no longer be updated until @ref{3f5,,Py_InitializeFromConfig()} is
called.

@end deffn

@geindex PyConfig_Clear (C function)
@anchor{c-api/init_config c PyConfig_Clear}@anchor{b9d}
@deffn {C 函式} void PyConfig_Clear (PyConfig *config)

Release configuration memory.
@end deffn

Most @code{PyConfig} methods @ref{4183,,preinitialize Python} if needed.
In that case, the Python preinitialization configuration
(@ref{b9a,,PyPreConfig}) in based on the @ref{3f4,,PyConfig}. If configuration
fields which are in common with @ref{b9a,,PyPreConfig} are tuned, they must
be set before calling a @ref{3f4,,PyConfig} method:


@itemize *

@item 
@ref{5304,,PyConfig.dev_mode}

@item 
@ref{414,,PyConfig.isolated}

@item 
@ref{1bdd,,PyConfig.parse_argv}

@item 
@ref{409,,PyConfig.use_environment}
@end itemize

Moreover, if @ref{ba0,,PyConfig_SetArgv()} or @ref{ba1,,PyConfig_SetBytesArgv()}
is used, this method must be called before other methods, since the
preinitialization configuration depends on command line arguments (if
@ref{1bdd,,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{3ef}
@deffn {C 成員函數} @ref{b9c,,PyWideStringList} argv

@geindex main()
@geindex argv (in module sys)

Set @ref{1465,,sys.argv} command line arguments based on
@ref{3ef,,argv}.  These parameters are similar to those passed
to the program's @code{main()} function with the difference that the
first entry should refer to the script file to be executed rather than
the executable hosting the Python interpreter.  If there isn't a script
that will be run, the first entry in @ref{3ef,,argv} can be an
empty string.

Set @ref{1bdd,,parse_argv} to @code{1} to parse
@ref{3ef,,argv} the same way the regular Python parses Python
command line arguments and then to strip Python arguments from
@ref{3ef,,argv}.

If @ref{3ef,,argv} is empty, an empty string is added to
ensure that @ref{1465,,sys.argv} always exists and is never empty.

預設值：@code{NULL}。

另請參閱 @ref{a8b,,orig_argv} 成員。
@end deffn

@geindex PyConfig.safe_path (C member)
@anchor{c-api/init_config c PyConfig safe_path}@anchor{96f}
@deffn {C 成員函數} int safe_path

If equals to zero, @code{Py_RunMain()} prepends a potentially unsafe path to
@ref{3e2,,sys.path} at startup:


@itemize *

@item 
If @ref{3ef,,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{7ba,,-P} command line option and the
@geindex PYTHONSAFEPATH
@geindex 環境變數; PYTHONSAFEPATH
@ref{7bb,,PYTHONSAFEPATH} environment variable.

Default: @code{0} in Python config, @code{1} in isolated config.


在 3.11 版被加入.

@end deffn

@geindex PyConfig.base_exec_prefix (C member)
@anchor{c-api/init_config c PyConfig base_exec_prefix}@anchor{52fa}
@deffn {C 成員函數} wchar_t *base_exec_prefix

@ref{3e8,,sys.base_exec_prefix}。

預設值：@code{NULL}。

Part of the @ref{aa1,,Python Path Configuration} output.

也請見 @ref{5307,,PyConfig.exec_prefix}
@end deffn

@geindex PyConfig.base_executable (C member)
@anchor{c-api/init_config c PyConfig base_executable}@anchor{52fb}
@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{63d,,PyConfig.executable} if @code{NULL}.

預設值：@code{NULL}。

Part of the @ref{aa1,,Python Path Configuration} output.

也請見 @ref{63d,,PyConfig.executable}
@end deffn

@geindex PyConfig.base_prefix (C member)
@anchor{c-api/init_config c PyConfig base_prefix}@anchor{52fc}
@deffn {C 成員函數} wchar_t *base_prefix

@ref{3e4,,sys.base_prefix}。

預設值：@code{NULL}。

Part of the @ref{aa1,,Python Path Configuration} output.

也請見 @ref{530d,,PyConfig.prefix}
@end deffn

@geindex PyConfig.buffered_stdio (C member)
@anchor{c-api/init_config c PyConfig buffered_stdio}@anchor{40f}
@deffn {C 成員函數} int buffered_stdio

If equals to @code{0} and @ref{5301,,configure_c_stdio} is non-zero,
disable buffering on the C streams stdout and stderr.

Set to @code{0} by the @ref{1c56,,-u} command line option and the
@geindex PYTHONUNBUFFERED
@geindex 環境變數; PYTHONUNBUFFERED
@ref{1c57,,PYTHONUNBUFFERED} environment variable.

stdin is always opened in buffered mode.

預設值：@code{1}。
@end deffn

@geindex PyConfig.bytes_warning (C member)
@anchor{c-api/init_config c PyConfig bytes_warning}@anchor{405}
@deffn {C 成員函數} int bytes_warning

If equals to @code{1}, issue a warning when comparing @ref{192,,bytes} or
@ref{343,,bytearray} with @ref{169,,str}, or comparing @ref{192,,bytes} with
@ref{19b,,int}.

If equal or greater to @code{2}, raise a @ref{e17,,BytesWarning} exception in these
cases.

Incremented by the @ref{7f2,,-b} command line option.

預設：@code{0}。
@end deffn

@geindex PyConfig.warn_default_encoding (C member)
@anchor{c-api/init_config c PyConfig warn_default_encoding}@anchor{5315}
@deffn {C 成員函數} int warn_default_encoding

If non-zero, emit a @ref{1ff5,,EncodingWarning} warning when @ref{9b7,,io.TextIOWrapper}
uses its default encoding. See @ref{2007,,選擇性加入的編碼警告} for details.

預設：@code{0}。


在 3.10 版被加入.

@end deffn

@geindex PyConfig.code_debug_ranges (C member)
@anchor{c-api/init_config c PyConfig code_debug_ranges}@anchor{52fe}
@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{7cc,,PYTHONNODEBUGRANGES} environment variable
and by the @ref{16f,,-X no_debug_ranges} command line option.

預設值：@code{1}。


在 3.11 版被加入.

@end deffn

@geindex PyConfig.check_hash_pycs_mode (C member)
@anchor{c-api/init_config c PyConfig check_hash_pycs_mode}@anchor{52fd}
@deffn {C 成員函數} wchar_t *check_hash_pycs_mode

Control the validation behavior of hash-based @code{.pyc} files:
value of the @ref{1fe8,,--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

預設：@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{5301}
@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{40f,,buffered_stdio} equals zero, disable buffering
of stdin, stdout and stderr streams.

@item 
If @ref{3fd,,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{5304}
@deffn {C 成員函數} int dev_mode

If non-zero, enable the @ref{503,,Python Development Mode}.

Set to @code{1} by the @ref{16f,,-X dev} option and the
@geindex PYTHONDEVMODE
@geindex 環境變數; PYTHONDEVMODE
@ref{cde,,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{5305}
@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{b95,,PYTHONDUMPREFS} environment variable.

Needs a special build of Python with the @code{Py_TRACE_REFS} macro defined:
see the @ref{62e,,configure --with-trace-refs option}.

預設：@code{0}。
@end deffn

@geindex PyConfig.dump_refs_file (C member)
@anchor{c-api/init_config c PyConfig dump_refs_file}@anchor{5306}
@deffn {C 成員函數} wchar_t *dump_refs_file

Filename where to dump Python references.

由 
@geindex PYTHONDUMPREFSFILE
@geindex 環境變數; PYTHONDUMPREFSFILE
@ref{1b49,,PYTHONDUMPREFSFILE} 環境變數設定。

預設值：@code{NULL}。


在 3.11 版被加入.

@end deffn

@geindex PyConfig.exec_prefix (C member)
@anchor{c-api/init_config c PyConfig exec_prefix}@anchor{5307}
@deffn {C 成員函數} wchar_t *exec_prefix

The site-specific directory prefix where the platform-dependent Python
files are installed: @ref{3e9,,sys.exec_prefix}.

預設值：@code{NULL}。

Part of the @ref{aa1,,Python Path Configuration} output.

也請見 @ref{52fa,,PyConfig.base_exec_prefix}
@end deffn

@geindex PyConfig.executable (C member)
@anchor{c-api/init_config c PyConfig executable}@anchor{63d}
@deffn {C 成員函數} wchar_t *executable

The absolute path of the executable binary for the Python interpreter:
@ref{3eb,,sys.executable}.

預設值：@code{NULL}。

Part of the @ref{aa1,,Python Path Configuration} output.

也請見 @ref{52fb,,PyConfig.base_executable}
@end deffn

@geindex PyConfig.faulthandler (C member)
@anchor{c-api/init_config c PyConfig faulthandler}@anchor{5308}
@deffn {C 成員函數} int faulthandler

Enable faulthandler?

If non-zero, call @ref{20f,,faulthandler.enable()} at startup.

Set to @code{1} by @ref{16f,,-X faulthandler} and the
@geindex PYTHONFAULTHANDLER
@geindex 環境變數; PYTHONFAULTHANDLER
@ref{1280,,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{419}
@deffn {C 成員函數} wchar_t *filesystem_encoding

@ref{756,,Filesystem encoding}:
@ref{e4e,,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{416,,legacy_windows_fs_encoding} of
@ref{b9a,,PyPreConfig} is non-zero.

Default encoding on other platforms:


@itemize *

@item 
@code{"utf-8"} if @ref{41b,,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{545,,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"}.

另請參閱 @ref{41a,,filesystem_errors} 成員。
@end deffn

@geindex PyConfig.filesystem_errors (C member)
@anchor{c-api/init_config c PyConfig filesystem_errors}@anchor{41a}
@deffn {C 成員函數} wchar_t *filesystem_errors

@ref{756,,Filesystem error handler}:
@ref{edd,,sys.getfilesystemencodeerrors()}.

On Windows: use @code{"surrogatepass"} by default, or @code{"replace"}  if
@ref{416,,legacy_windows_fs_encoding} of
@ref{b9a,,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"}（僅支援 UTF-8 編碼）
@end itemize

另請參閱 @ref{419,,filesystem_encoding} 成員。
@end deffn

@geindex PyConfig.use_frozen_modules (C member)
@anchor{c-api/init_config c PyConfig use_frozen_modules}@anchor{5314}
@deffn {C 成員函數} int use_frozen_modules

If non-zero, use frozen modules.

由 
@geindex PYTHON_FROZEN_MODULES
@geindex 環境變數; PYTHON_FROZEN_MODULES
@ref{4a8,,PYTHON_FROZEN_MODULES} 環境變數設定。

Default: @code{1} in a release build, or @code{0} in a @ref{504,,debug build}.
@end deffn

@geindex PyConfig.hash_seed (C member)
@anchor{c-api/init_config c PyConfig hash_seed}@anchor{412}
@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{411}
@deffn {C 成員函數} int use_hash_seed

Randomized hash function seed.

If @ref{411,,use_hash_seed} is zero, a seed is chosen randomly
at Python startup, and @ref{412,,hash_seed} is ignored.

由 
@geindex PYTHONHASHSEED
@geindex 環境變數; PYTHONHASHSEED
@ref{1278,,PYTHONHASHSEED} 環境變數設定。

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{3f1}
@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{3ee,,PYTHONHOME}).

由 
@geindex PYTHONHOME
@geindex 環境變數; PYTHONHOME
@ref{3ee,,PYTHONHOME} 環境變數設定。

預設值：@code{NULL}。

Part of the @ref{aa1,,Python Path Configuration} input.
@end deffn

@geindex PyConfig.import_time (C member)
@anchor{c-api/init_config c PyConfig import_time}@anchor{5309}
@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.

由 @ref{16f,,-X importtime} 選項與 
@geindex PYTHONPROFILEIMPORTTIME
@geindex 環境變數; PYTHONPROFILEIMPORTTIME
@ref{ce4,,PYTHONPROFILEIMPORTTIME} 環境變數設定。

預設：@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{3ff}
@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{758,,sys.stdin} does not appear to
be a terminal.

Incremented by the @ref{16cf,,-i} command line option. Set to @code{1} if the
@geindex PYTHONINSPECT
@geindex 環境變數; PYTHONINSPECT
@ref{16ce,,PYTHONINSPECT} environment variable is non-empty.

預設：@code{0}。
@end deffn

@geindex PyConfig.install_signal_handlers (C member)
@anchor{c-api/init_config c PyConfig install_signal_handlers}@anchor{ab2}
@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{3fd}
@deffn {C 成員函數} int interactive

If greater than @code{0}, enable the interactive mode (REPL).

Incremented by the @ref{16cf,,-i} command line option.

預設：@code{0}。
@end deffn

@geindex PyConfig.int_max_str_digits (C member)
@anchor{c-api/init_config c PyConfig int_max_str_digits}@anchor{530a}
@deffn {C 成員函數} int int_max_str_digits

Configures the @ref{804,,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{2586,,sys.int_info.default_max_str_digits}).  A value of @code{0}
disables the limitation.  Values greater than zero but less than 640
(@ref{47dd,,sys.int_info.str_digits_check_threshold}) are unsupported and
will produce an error.

Configured by the @ref{16f,,-X int_max_str_digits} command line
flag or the 
@geindex PYTHONINTMAXSTRDIGITS
@geindex 環境變數; PYTHONINTMAXSTRDIGITS
@ref{1a79,,PYTHONINTMAXSTRDIGITS} environment variable.

Default: @code{-1} in Python mode.  4300
(@ref{2586,,sys.int_info.default_max_str_digits}) in isolated mode.


在 3.12 版被加入.

@end deffn

@geindex PyConfig.cpu_count (C member)
@anchor{c-api/init_config c PyConfig cpu_count}@anchor{5303}
@deffn {C 成員函數} int cpu_count

If the value of @ref{5303,,cpu_count} is not @code{-1} then it will
override the return values of @ref{4d6,,os.cpu_count()},
@ref{4d5,,os.process_cpu_count()}, and @ref{116a,,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{519,,PYTHON_CPU_COUNT} environment variable.

預設值：@code{1}。


在 3.13 版被加入.

@end deffn

@geindex PyConfig.isolated (C member)
@anchor{c-api/init_config c PyConfig isolated}@anchor{414}
@deffn {C 成員函數} int isolated

If greater than @code{0}, enable isolated mode:


@itemize *

@item 
Set @ref{96f,,safe_path} to @code{1}:
don't prepend a potentially unsafe path to @ref{3e2,,sys.path} at Python
startup, such as the current directory, the script's directory or an
empty string.

@item 
將 @ref{409,,use_environment} 設定為 @code{0}：忽略 @code{PYTHON} 環境變數。

@item 
Set @ref{40d,,user_site_directory} to @code{0}: don't add the user
site directory to @ref{3e2,,sys.path}.

@item 
Python REPL doesn't import @ref{bf,,readline} nor enable default readline
configuration on interactive prompts.
@end itemize

Set to @code{1} by the @ref{b4e,,-I} command line option.

Default: @code{0} in Python mode, @code{1} in isolated mode.

See also the @ref{52f1,,Isolated Configuration} and
@ref{5324,,PyPreConfig.isolated}.
@end deffn

@geindex PyConfig.legacy_windows_stdio (C member)
@anchor{c-api/init_config c PyConfig legacy_windows_stdio}@anchor{418}
@deffn {C 成員函數} int legacy_windows_stdio

If non-zero, use @ref{1510,,io.FileIO} instead of
@code{io._WindowsConsoleIO} for @ref{758,,sys.stdin}, @ref{cc4,,sys.stdout}
and @ref{b2a,,sys.stderr}.

Set to @code{1} if the 
@geindex PYTHONLEGACYWINDOWSSTDIO
@geindex 環境變數; PYTHONLEGACYWINDOWSSTDIO
@ref{e50,,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.

預設：@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{530b}
@deffn {C 成員函數} int malloc_stats

If non-zero, dump statistics on @ref{f06,,Python pymalloc memory allocator} at exit.

Set to @code{1} by the 
@geindex PYTHONMALLOCSTATS
@geindex 環境變數; PYTHONMALLOCSTATS
@ref{1dfe,,PYTHONMALLOCSTATS} environment variable.

The option is ignored if Python is @ref{2064,,configured using the --without-pymalloc option}.

預設：@code{0}。
@end deffn

@geindex PyConfig.platlibdir (C member)
@anchor{c-api/init_config c PyConfig platlibdir}@anchor{1bf3}
@deffn {C 成員函數} wchar_t *platlibdir

Platform library directory name: @ref{b29,,sys.platlibdir}.

Set by the 
@geindex PYTHONPLATLIBDIR
@geindex 環境變數; PYTHONPLATLIBDIR
@ref{1bf5,,PYTHONPLATLIBDIR} environment variable.

Default: value of the @code{PLATLIBDIR} macro which is set by the
@ref{202d,,configure --with-platlibdir option}
(default: @code{"lib"}, or @code{"DLLs"} on Windows).

Part of the @ref{aa1,,Python Path Configuration} input.


在 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{5329}
@deffn {C 成員函數} wchar_t *pythonpath_env

Module search paths (@ref{3e2,,sys.path}) as a string separated by @code{DELIM}
(@ref{1ffb,,os.pathsep}).

Set by the 
@geindex PYTHONPATH
@geindex 環境變數; PYTHONPATH
@ref{1218,,PYTHONPATH} environment variable.

預設值：@code{NULL}。

Part of the @ref{aa1,,Python Path Configuration} input.
@end deffn

@geindex PyConfig.module_search_paths (C member)
@anchor{c-api/init_config c PyConfig module_search_paths}@anchor{63b}
@deffn {C 成員函數} @ref{b9c,,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{7fe}
@deffn {C 成員函數} int module_search_paths_set

Module search paths: @ref{3e2,,sys.path}.

If @ref{7fe,,module_search_paths_set} is equal to @code{0},
@ref{3f5,,Py_InitializeFromConfig()} will replace
@ref{63b,,module_search_paths} and sets
@ref{7fe,,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{aa1,,Python Path Configuration} output.
@end deffn

@geindex PyConfig.optimization_level (C member)
@anchor{c-api/init_config c PyConfig optimization_level}@anchor{401}
@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{18c,,-O} command line option. Set to the
@geindex PYTHONOPTIMIZE
@geindex 環境變數; PYTHONOPTIMIZE
@ref{1feb,,PYTHONOPTIMIZE} environment variable value.

預設：@code{0}。
@end deffn

@geindex PyConfig.orig_argv (C member)
@anchor{c-api/init_config c PyConfig orig_argv}@anchor{a8b}
@deffn {C 成員函數} @ref{b9c,,PyWideStringList} orig_argv

The list of the original command line arguments passed to the Python
executable: @ref{a3a,,sys.orig_argv}.

If @ref{a8b,,orig_argv} list is empty and
@ref{3ef,,argv} is not a list only containing an empty
string, @ref{98b,,PyConfig_Read()} copies @ref{3ef,,argv} into
@ref{a8b,,orig_argv} before modifying
@ref{3ef,,argv} (if @ref{1bdd,,parse_argv} is
non-zero).

See also the @ref{3ef,,argv} member and the
@ref{1c0b,,Py_GetArgcArgv()} function.

Default: empty list.


在 3.10 版被加入.

@end deffn

@geindex PyConfig.parse_argv (C member)
@anchor{c-api/init_config c PyConfig parse_argv}@anchor{1bdd}
@deffn {C 成員函數} int parse_argv

Parse command line arguments?

If equals to @code{1}, parse @ref{3ef,,argv} the same way the regular
Python parses @ref{1202,,command line arguments}, and strip
Python arguments from @ref{3ef,,argv}.

The @ref{98b,,PyConfig_Read()} function only parses
@ref{3ef,,PyConfig.argv} arguments once: @ref{1bdd,,PyConfig.parse_argv}
is set to @code{2} after arguments are parsed. Since Python arguments are
stripped from @ref{3ef,,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{3ef,,PyConfig.argv} arguments are now only parsed if
@ref{1bdd,,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{3f7}
@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{1fe9,,-d} command line option. Set to the
@geindex PYTHONDEBUG
@geindex 環境變數; PYTHONDEBUG
@ref{1fea,,PYTHONDEBUG} environment variable value.

Needs a @ref{504,,debug build of Python} (the @code{Py_DEBUG} macro
must be defined).

預設：@code{0}。
@end deffn

@geindex PyConfig.pathconfig_warnings (C member)
@anchor{c-api/init_config c PyConfig pathconfig_warnings}@anchor{407}
@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{aa1,,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{530d}
@deffn {C 成員函數} wchar_t *prefix

The site-specific directory prefix where the platform independent Python
files are installed: @ref{3e6,,sys.prefix}.

預設值：@code{NULL}。

Part of the @ref{aa1,,Python Path Configuration} output.

也請見 @ref{52fc,,PyConfig.base_prefix}
@end deffn

@geindex PyConfig.program_name (C member)
@anchor{c-api/init_config c PyConfig program_name}@anchor{3f0}
@deffn {C 成員函數} wchar_t *program_name

Program name used to initialize @ref{63d,,executable} and in
early error messages during Python initialization.


@itemize *

@item 
On macOS, use 
@geindex PYTHONEXECUTABLE
@geindex 環境變數; PYTHONEXECUTABLE
@ref{1fff,,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{3ef,,argv} if available and
non-empty.

@item 
Otherwise, use @code{L"python"} on Windows, or @code{L"python3"} on other
platforms.
@end itemize

預設值：@code{NULL}。

Part of the @ref{aa1,,Python Path Configuration} input.
@end deffn

@geindex PyConfig.pycache_prefix (C member)
@anchor{c-api/init_config c PyConfig pycache_prefix}@anchor{530e}
@deffn {C 成員函數} wchar_t *pycache_prefix

Directory where cached @code{.pyc} files are written:
@ref{b93,,sys.pycache_prefix}.

Set by the @ref{16f,,-X pycache_prefix=PATH} command line option and
the 
@geindex PYTHONPYCACHEPREFIX
@geindex 環境變數; PYTHONPYCACHEPREFIX
@ref{b92,,PYTHONPYCACHEPREFIX} environment variable.
The command-line option takes precedence.

If @code{NULL}, @ref{b93,,sys.pycache_prefix} is set to @code{None}.

預設值：@code{NULL}。
@end deffn

@geindex PyConfig.quiet (C member)
@anchor{c-api/init_config c PyConfig quiet}@anchor{3fb}
@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{1fec,,-q} command line option.

預設：@code{0}。
@end deffn

@geindex PyConfig.run_command (C member)
@anchor{c-api/init_config c PyConfig run_command}@anchor{52a7}
@deffn {C 成員函數} wchar_t *run_command

Value of the @ref{1a8,,-c} command line option.

Used by @ref{bb3,,Py_RunMain()}.

預設值：@code{NULL}。
@end deffn

@geindex PyConfig.run_filename (C member)
@anchor{c-api/init_config c PyConfig run_filename}@anchor{52a8}
@deffn {C 成員函數} wchar_t *run_filename

Filename passed on the command line: trailing command line argument
without @ref{1a8,,-c} or @ref{23c,,-m}. It is used by the
@ref{bb3,,Py_RunMain()} function.

For example, it is set to @code{script.py} by the @code{python3 script.py arg}
command line.

也請見 @ref{5311,,PyConfig.skip_source_first_line} 選項。

預設值：@code{NULL}。
@end deffn

@geindex PyConfig.run_module (C member)
@anchor{c-api/init_config c PyConfig run_module}@anchor{52a9}
@deffn {C 成員函數} wchar_t *run_module

Value of the @ref{23c,,-m} command line option.

Used by @ref{bb3,,Py_RunMain()}.

預設值：@code{NULL}。
@end deffn

@geindex PyConfig.run_presite (C member)
@anchor{c-api/init_config c PyConfig run_presite}@anchor{530f}
@deffn {C 成員函數} wchar_t *run_presite

@code{package.module} path to module that should be imported before
@code{site.py} is run.

Set by the @ref{16f,,-X presite=package.module} command-line
option and the 
@geindex PYTHON_PRESITE
@geindex 環境變數; PYTHON_PRESITE
@ref{1ff6,,PYTHON_PRESITE} environment variable.
The command-line option takes precedence.

Needs a @ref{504,,debug build of Python} (the @code{Py_DEBUG} macro
must be defined).

預設值：@code{NULL}。
@end deffn

@geindex PyConfig.show_ref_count (C member)
@anchor{c-api/init_config c PyConfig show_ref_count}@anchor{5310}
@deffn {C 成員函數} int show_ref_count

Show total reference count at exit (excluding @ref{290,,immortal} objects)?

Set to @code{1} by @ref{16f,,-X showrefcount} command line option.

Needs a @ref{504,,debug build of Python} (the @code{Py_REF_DEBUG}
macro must be defined).

預設：@code{0}。
@end deffn

@geindex PyConfig.site_import (C member)
@anchor{c-api/init_config c PyConfig site_import}@anchor{403}
@deffn {C 成員函數} int site_import

Import the @ref{cc,,site} module at startup?

If equal to zero, disable the import of the module site and the
site-dependent manipulations of @ref{3e2,,sys.path} that it entails.

Also disable these manipulations if the @ref{cc,,site} module is explicitly
imported later (call @ref{1fee,,site.main()} if you want them to be triggered).

Set to @code{0} by the @ref{13a9,,-S} command line option.

@ref{895,,sys.flags.no_site} is set to the inverted value of
@ref{403,,site_import}.

預設值：@code{1}。
@end deffn

@geindex PyConfig.skip_source_first_line (C member)
@anchor{c-api/init_config c PyConfig skip_source_first_line}@anchor{5311}
@deffn {C 成員函數} int skip_source_first_line

If non-zero, skip the first line of the @ref{52a8,,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{1ff2,,-x} command line option.

預設：@code{0}。
@end deffn

@geindex PyConfig.stdio_encoding (C member)
@anchor{c-api/init_config c PyConfig stdio_encoding}@anchor{63c}
@deffn {C 成員函數} wchar_t *stdio_encoding
@end deffn

@geindex PyConfig.stdio_errors (C member)
@anchor{c-api/init_config c PyConfig stdio_errors}@anchor{47df}
@deffn {C 成員函數} wchar_t *stdio_errors

Encoding and encoding errors of @ref{758,,sys.stdin}, @ref{cc4,,sys.stdout} and
@ref{b2a,,sys.stderr} (but @ref{b2a,,sys.stderr} always uses
@code{"backslashreplace"} error handler).

Use the 
@geindex PYTHONIOENCODING
@geindex 環境變數; PYTHONIOENCODING
@ref{1205,,PYTHONIOENCODING} environment variable if it is
non-empty.

Default encoding:


@itemize *

@item 
@code{"UTF-8"} if @ref{41b,,PyPreConfig.utf8_mode} is non-zero.

@item 
Otherwise, use the @ref{545,,locale encoding}.
@end itemize

Default error handler:


@itemize *

@item 
On Windows: use @code{"surrogateescape"}.

@item 
@code{"surrogateescape"} if @ref{41b,,PyPreConfig.utf8_mode} is non-zero,
or if the LC_CTYPE locale is "C" or "POSIX".

@item 
@code{"strict"} otherwise.
@end itemize

也請見 @ref{418,,PyConfig.legacy_windows_stdio}。
@end deffn

@geindex PyConfig.tracemalloc (C member)
@anchor{c-api/init_config c PyConfig tracemalloc}@anchor{5313}
@deffn {C 成員函數} int tracemalloc

Enable tracemalloc?

If non-zero, call @ref{1ff3,,tracemalloc.start()} at startup.

Set by @ref{16f,,-X tracemalloc=N} command line option and by the
@geindex PYTHONTRACEMALLOC
@geindex 環境變數; PYTHONTRACEMALLOC
@ref{1ff4,,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{530c}
@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{16f,,-X perf} command-line option and the
@geindex PYTHONPERFSUPPORT
@geindex 環境變數; PYTHONPERFSUPPORT
@ref{692,,PYTHONPERFSUPPORT} environment variable.

Set to @code{2} by the @ref{16f,,-X perf_jit} command-line option and
the 
@geindex PYTHON_PERF_JIT_SUPPORT
@geindex 環境變數; PYTHON_PERF_JIT_SUPPORT
@ref{4aa,,PYTHON_PERF_JIT_SUPPORT} environment variable.

預設值：@code{1}。


@subsubheading 也參考


See @ref{4a9,,Python 對 Linux perf 分析器的支援} for more information.



在 3.12 版被加入.

@end deffn

@geindex PyConfig.stdlib_dir (C member)
@anchor{c-api/init_config c PyConfig stdlib_dir}@anchor{5312}
@deffn {C 成員函數} wchar_t *stdlib_dir

Directory of the Python standard library.

預設值：@code{NULL}。


在 3.11 版被加入.

@end deffn

@geindex PyConfig.use_environment (C member)
@anchor{c-api/init_config c PyConfig use_environment}@anchor{409}
@deffn {C 成員函數} int use_environment

Use @ref{800,,environment variables}?

If equals to zero, ignore the @ref{800,,environment variables}.

Set to @code{0} by the @ref{b4d,,-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{2135}
@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).


在 3.14 版被加入.

@end deffn

@geindex PyConfig.user_site_directory (C member)
@anchor{c-api/init_config c PyConfig user_site_directory}@anchor{40d}
@deffn {C 成員函數} int user_site_directory

If non-zero, add the user site directory to @ref{3e2,,sys.path}.

Set to @code{0} by the @ref{1586,,-s} and @ref{b4e,,-I} command line options.

Set to @code{0} by the 
@geindex PYTHONNOUSERSITE
@geindex 環境變數; PYTHONNOUSERSITE
@ref{1587,,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{3f9}
@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{161c,,-v} command line option.

Set by the 
@geindex PYTHONVERBOSE
@geindex 環境變數; PYTHONVERBOSE
@ref{1fef,,PYTHONVERBOSE} environment variable value.

預設：@code{0}。
@end deffn

@geindex PyConfig.warnoptions (C member)
@anchor{c-api/init_config c PyConfig warnoptions}@anchor{639}
@deffn {C 成員函數} @ref{b9c,,PyWideStringList} warnoptions

Options of the @ref{118,,warnings} module to build warnings filters, lowest
to highest priority: @ref{3f3,,sys.warnoptions}.

The @ref{118,,warnings} module adds @ref{3f3,,sys.warnoptions} in the reverse
order: the last @ref{639,,PyConfig.warnoptions} item becomes the first
item of @code{warnings.filters} which is checked first (highest
priority).

The @ref{abc,,-W} command line options adds its value to
@ref{639,,warnoptions}, it can be used multiple times.

The 
@geindex PYTHONWARNINGS
@geindex 環境變數; PYTHONWARNINGS
@ref{d9e,,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{40b}
@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{15c4,,-B} command line option and the
@geindex PYTHONDONTWRITEBYTECODE
@geindex 環境變數; PYTHONDONTWRITEBYTECODE
@ref{15c5,,PYTHONDONTWRITEBYTECODE} environment variable.

@ref{47a9,,sys.dont_write_bytecode} is initialized to the inverted value of
@ref{40b,,write_bytecode}.

預設值：@code{1}。
@end deffn

@geindex PyConfig.xoptions (C member)
@anchor{c-api/init_config c PyConfig xoptions}@anchor{63a}
@deffn {C 成員函數} @ref{b9c,,PyWideStringList} xoptions

Values of the @ref{16f,,-X} command line options: @ref{1ff8,,sys._xoptions}.

Default: empty list.
@end deffn

@geindex PyConfig._pystats (C member)
@anchor{c-api/init_config c PyConfig _pystats}@anchor{5316}
@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{1a77,,--enable-pystats}.

預設：@code{0}。
@end deffn
@end deffn

If @ref{1bdd,,parse_argv} is non-zero, @ref{3ef,,argv}
arguments are parsed the same way the regular Python parses @ref{1202,,command line arguments}, and Python arguments are stripped from
@ref{3ef,,argv}.

The @ref{63a,,xoptions} options are parsed to set other options: see
the @ref{16f,,-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{52a6}@anchor{c-api/init_config initialization-with-pyconfig}@anchor{532a}
@subsubsection Initialization with PyConfig


Initializing the interpreter from a populated configuration struct is handled
by calling @ref{3f5,,Py_InitializeFromConfig()}.

The caller is responsible to handle exceptions (error or exit) using
@ref{ba7,,PyStatus_Exception()} and @ref{bb0,,Py_ExitStatusException()}.

If @ref{31cd,,PyImport_FrozenModules()}, @ref{1a5f,,PyImport_AppendInittab()} or
@ref{1a60,,PyImport_ExtendInittab()} are used, they must be set or called after
Python preinitialization and before the Python initialization. If Python is
initialized multiple times, @ref{1a5f,,PyImport_AppendInittab()} or
@ref{1a60,,PyImport_ExtendInittab()} must be called before each Python
initialization.

The current configuration (@code{PyConfig} type) is stored in
@code{PyInterpreterState.config}.

Example setting the program name:

@example
void init_python(void)
@{
    PyStatus status;

    PyConfig config;
    PyConfig_InitPythonConfig(&config);

    /* Set the program name. Implicitly preinitialize Python. */
    status = PyConfig_SetString(&config, &config.program_name,
                                L"/path/to/my_program");
    if (PyStatus_Exception(status)) @{
        goto exception;
    @}

    status = Py_InitializeFromConfig(&config);
    if (PyStatus_Exception(status)) @{
        goto exception;
    @}
    PyConfig_Clear(&config);
    return;

exception:
    PyConfig_Clear(&config);
    Py_ExitStatusException(status);
@}
@end example

More complete example modifying the default configuration, read the
configuration, and then override some parameters. Note that since
3.11, many parameters are not calculated until initialization, and
so values cannot be read from the configuration structure. Any values
set before initialize is called will be left unchanged by
initialization:

@example
PyStatus init_python(const char *program_name)
@{
    PyStatus status;

    PyConfig config;
    PyConfig_InitPythonConfig(&config);

    /* Set the program name before reading the configuration
       (decode byte string from the locale encoding).

       Implicitly preinitialize Python. */
    status = PyConfig_SetBytesString(&config, &config.program_name,
                                     program_name);
    if (PyStatus_Exception(status)) @{
        goto done;
    @}

    /* Read all configuration at once */
    status = PyConfig_Read(&config);
    if (PyStatus_Exception(status)) @{
        goto done;
    @}

    /* Specify sys.path explicitly */
    /* If you want to modify the default set of paths, finish
       initialization first and then use PySys_GetObject("path") */
    config.module_search_paths_set = 1;
    status = PyWideStringList_Append(&config.module_search_paths,
                                     L"/path/to/stdlib");
    if (PyStatus_Exception(status)) @{
        goto done;
    @}
    status = PyWideStringList_Append(&config.module_search_paths,
                                     L"/path/to/more/modules");
    if (PyStatus_Exception(status)) @{
        goto done;
    @}

    /* Override executable computed by PyConfig_Read() */
    status = PyConfig_SetString(&config, &config.executable,
                                L"/path/to/my_executable");
    if (PyStatus_Exception(status)) @{
        goto done;
    @}

    status = Py_InitializeFromConfig(&config);

done:
    PyConfig_Clear(&config);
    return status;
@}
@end example

@node Isolated Configuration,Python Configuration,Initialization with PyConfig,PyConfig C API
@anchor{c-api/init_config init-isolated-conf}@anchor{52f1}@anchor{c-api/init_config isolated-configuration}@anchor{532b}
@subsubsection Isolated Configuration


@ref{ba4,,PyPreConfig_InitIsolatedConfig()} and
@ref{b9e,,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{3ef,,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{3f1,,PyConfig.home} is specified
to avoid computing the default path configuration.

@node Python Configuration,Python 路徑配置,Isolated Configuration,PyConfig C API
@anchor{c-api/init_config init-python-config}@anchor{52aa}@anchor{c-api/init_config python-configuration}@anchor{532c}
@subsubsection Python Configuration


@ref{ba5,,PyPreConfig_InitPythonConfig()} and @ref{b9f,,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{85f,,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{cc6,,PYTHONUTF8} and
@geindex PYTHONCOERCECLOCALE
@geindex 環境變數; PYTHONCOERCECLOCALE
@ref{cc3,,PYTHONCOERCECLOCALE} environment variables.

@node Python 路徑配置,,Python Configuration,PyConfig C API
@anchor{c-api/init_config init-path-config}@anchor{aa1}@anchor{c-api/init_config python-path-configuration}@anchor{532d}
@subsubsection Python 路徑配置


@ref{3f4,,PyConfig} contains multiple fields for the path configuration:


@itemize *

@item 
Path configuration inputs:


@itemize *

@item 
@ref{3f1,,PyConfig.home}

@item 
@ref{1bf3,,PyConfig.platlibdir}

@item 
@ref{407,,PyConfig.pathconfig_warnings}

@item 
@ref{3f0,,PyConfig.program_name}

@item 
@ref{5329,,PyConfig.pythonpath_env}

@item 
current working directory: to get absolute paths

@item 
@code{PATH} environment variable to get the program full path
(from @ref{3f0,,PyConfig.program_name})

@item 
@code{__PYVENV_LAUNCHER__} 環境變數

@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{52fa,,PyConfig.base_exec_prefix}

@item 
@ref{52fb,,PyConfig.base_executable}

@item 
@ref{52fc,,PyConfig.base_prefix}

@item 
@ref{5307,,PyConfig.exec_prefix}

@item 
@ref{63d,,PyConfig.executable}

@item 
@ref{7fe,,PyConfig.module_search_paths_set},
@ref{63b,,PyConfig.module_search_paths}

@item 
@ref{530d,,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{7fe,,module_search_paths_set} is equal to @code{0},
@ref{63b,,module_search_paths} is overridden and
@ref{7fe,,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{407,,pathconfig_warnings} to @code{0} to suppress warnings when
calculating the path configuration (Unix only, Windows does not log any warning).

If @ref{52fc,,base_prefix} or @ref{52fa,,base_exec_prefix}
fields are not set, they inherit their value from @ref{530d,,prefix}
and @ref{5307,,exec_prefix} respectively.

@ref{bb3,,Py_RunMain()} 和 @ref{e19,,Py_Main()} 會修改 @ref{3e2,,sys.path}：


@itemize *

@item 
If @ref{52a8,,run_filename} is set and is a directory which contains a
@code{__main__.py} script, prepend @ref{52a8,,run_filename} to
@ref{3e2,,sys.path}.

@item 
如果 @ref{414,,isolated} 為零：


@itemize *

@item 
If @ref{52a9,,run_module} is set, prepend the current directory
to @ref{3e2,,sys.path}. Do nothing if the current directory cannot be read.

@item 
If @ref{52a8,,run_filename} is set, prepend the directory of the
filename to @ref{3e2,,sys.path}.

@item 
Otherwise, prepend an empty string to @ref{3e2,,sys.path}.
@end itemize
@end itemize

If @ref{403,,site_import} is non-zero, @ref{3e2,,sys.path} can be
modified by the @ref{cc,,site} module. If
@ref{40d,,user_site_directory} is non-zero and the user's
site-package directory exists, the @ref{cc,,site} module appends the user's
site-package directory to @ref{3e2,,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）
@end itemize

If a @code{._pth} file is present:


@itemize *

@item 
將 @ref{414,,isolated} 設定為 @code{1}。

@item 
將 @ref{409,,use_environment} 設定為 @code{0}。

@item 
將 @ref{403,,site_import} 設定為 @code{0}。

@item 
將 @ref{96f,,safe_path} 設定為 @code{1}。
@end itemize

If @ref{3f1,,home} is not set and a @code{pyvenv.cfg} file is present in
the same directory as @ref{63d,,executable}, or its parent,
@ref{530d,,prefix} and @ref{5307,,exec_prefix} are set that
location. When this happens, @ref{52fc,,base_prefix} and
@ref{52fa,,base_exec_prefix} still keep their value, pointing to the
base installation. See @ref{476b,,虛擬環境} for more
information.

The @code{__PYVENV_LAUNCHER__} environment variable is used to set
@ref{52fb,,PyConfig.base_executable}.


在 3.14 版的變更: @ref{530d,,prefix}, and @ref{5307,,exec_prefix}, are now
set to the @code{pyvenv.cfg} directory. This was previously done by @ref{cc,,site},
therefore affected by @ref{13a9,,-S}.


@node Py_GetArgcArgv,Delaying main module execution,PyConfig C API,Python 初始化設定
@anchor{c-api/init_config py-getargcargv}@anchor{532e}
@subsection Py_GetArgcArgv()


@geindex Py_GetArgcArgv (C function)
@anchor{c-api/init_config c Py_GetArgcArgv}@anchor{1c0b}
@deffn {C 函式} void Py_GetArgcArgv (int *argc, wchar_t ***argv)

Get the original command line arguments, before Python modified them.

也請參與 @ref{a8b,,PyConfig.orig_argv} 成員。
@end deffn

@node Delaying main module execution,,Py_GetArgcArgv,Python 初始化設定
@anchor{c-api/init_config delaying-main-module-execution}@anchor{532f}
@subsection Delaying main module execution


In some embedding use cases, it may be desirable to separate interpreter initialization
from the execution of the main module.

This separation can be achieved by setting @code{PyConfig.run_command} to the empty
string during initialization (to prevent the interpreter from dropping into the
interactive prompt), and then subsequently executing the desired main module
code using @code{__main__.__dict__} as the global namespace.

@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 參考手冊
@anchor{c-api/memory doc}@anchor{5330}@anchor{c-api/memory memory}@anchor{5322}@anchor{c-api/memory memory-management}@anchor{5331}@anchor{c-api/memory translation-repo}@anchor{5332}
@section 記憶體管理


@menu
* 總覽: 總覽<2>. 
* Allocator Domains:: 
* Raw 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:: 
* 範例: 範例<55>. 

@end menu

@node 總覽<2>,Allocator Domains,,記憶體管理
@anchor{c-api/memory memoryoverview}@anchor{5333}@anchor{c-api/memory overview}@anchor{5334}
@subsection 總覽


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 函式）
@geindex calloc（C 函式）
@geindex realloc（C 函式）
@geindex free（C 函式）

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{e59,,PYTHONMALLOC} environment variable can be used to configure
the memory allocators used by Python.

The 
@geindex PYTHONMALLOCSTATS
@geindex 環境變數; PYTHONMALLOCSTATS
@ref{1dfe,,PYTHONMALLOCSTATS} environment variable can be used to print
statistics of the @ref{f06,,pymalloc memory allocator} every time a
new pymalloc object arena is created, and on shutdown.


@node Allocator Domains,Raw Memory Interface,總覽<2>,記憶體管理
@anchor{c-api/memory allocator-domains}@anchor{5335}
@subsection Allocator Domains

@anchor{c-api/memory id1}@anchor{5336}
All allocating functions belong to one of three different "domains" (see also
@ref{5337,,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{2002,,here}.
The APIs used to allocate and free a block of memory must be from the same domain.
For example, @ref{1639,,PyMem_Free()} must be used to free memory allocated using @ref{e5b,,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{4d99,,attached thread state}. The memory
is requested directly from the system. See @ref{5338,,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{4d99,,attached thread state}. The memory is taken from the Python private heap.
See @ref{5339,,Memory Interface}.

@item 
Object domain: intended for allocating memory for Python objects. The
memory is taken from the Python private heap. See @ref{533a,,Object allocators}.
@end itemize

@cartouche
@quotation 備註 
The @ref{1f4,,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{e5b,,PyMem_Malloc()},
@ref{629,,PyMem_RawMalloc()}, or @code{malloc()}, but not @ref{e5d,,PyObject_Malloc()}.

See @ref{533b,,Memory Allocation APIs}.
@end quotation
@end cartouche

@node Raw Memory Interface,記憶體介面,Allocator Domains,記憶體管理
@anchor{c-api/memory raw-memory-interface}@anchor{533c}@anchor{c-api/memory raw-memoryinterface}@anchor{5338}
@subsection Raw Memory Interface


The following function sets are wrappers to the system allocator. These
functions are thread-safe, so a @ref{17c4,,thread state} does not
need to be @ref{4d99,,attached}.

The @ref{2002,,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.


在 3.4 版被加入.


@geindex PyMem_RawMalloc (C function)
@anchor{c-api/memory c PyMem_RawMalloc}@anchor{629}
@deffn {C 函式} void *PyMem_RawMalloc (size_t n)
` 為 @ref{76e,,穩定 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{62a}
@deffn {C 函式} void *PyMem_RawCalloc (size_t nelem, size_t elsize)
` 為 @ref{76e,,穩定 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.


在 3.5 版被加入.

@end deffn

@geindex PyMem_RawRealloc (C function)
@anchor{c-api/memory c PyMem_RawRealloc}@anchor{62b}
@deffn {C 函式} void *PyMem_RawRealloc (void *p, size_t n)
` 為 @ref{76e,,穩定 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{629,,PyMem_RawMalloc()}, @ref{62b,,PyMem_RawRealloc()} or
@ref{62a,,PyMem_RawCalloc()}.

If the request fails, @ref{62b,,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{62c}
@deffn {C 函式} void PyMem_RawFree (void *p)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.13 版本開始.'
Frees the memory block pointed to by `p', which must have been returned by a
previous call to @ref{629,,PyMem_RawMalloc()}, @ref{62b,,PyMem_RawRealloc()} or
@ref{62a,,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 記憶體介面,Object allocators,Raw Memory Interface,記憶體管理
@anchor{c-api/memory memory-interface}@anchor{533d}@anchor{c-api/memory memoryinterface}@anchor{5339}
@subsection 記憶體介面


The following function sets, modeled after the ANSI C standard, but specifying
behavior when requesting zero bytes, are available for allocating and releasing
memory from the Python heap.

The @ref{2002,,default memory allocator} uses the
@ref{f06,,pymalloc memory allocator}.

@cartouche
@quotation 警告 
There must be an @ref{4d99,,attached thread state} when using these functions.
@end quotation
@end cartouche


在 3.6 版的變更: The default allocator is now pymalloc instead of system @code{malloc()}.


@geindex PyMem_Malloc (C function)
@anchor{c-api/memory c PyMem_Malloc}@anchor{e5b}
@deffn {C 函式} void *PyMem_Malloc (size_t n)
` 為 @ref{76e,,穩定 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{10a8}
@deffn {C 函式} void *PyMem_Calloc (size_t nelem, size_t elsize)
` 為 @ref{76e,,穩定 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.


在 3.5 版被加入.

@end deffn

@geindex PyMem_Realloc (C function)
@anchor{c-api/memory c PyMem_Realloc}@anchor{122d}
@deffn {C 函式} void *PyMem_Realloc (void *p, size_t n)
` 為 @ref{76e,,穩定 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{e5b,,PyMem_Malloc()}, @ref{122d,,PyMem_Realloc()} or @ref{10a8,,PyMem_Calloc()}.

If the request fails, @ref{122d,,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{1639}
@deffn {C 函式} void PyMem_Free (void *p)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Frees the memory block pointed to by `p', which must have been returned by a
previous call to @ref{e5b,,PyMem_Malloc()}, @ref{122d,,PyMem_Realloc()} or
@ref{10a8,,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{1718}
@deffn {C 巨集} PyMem_New (TYPE, n)

Same as @ref{e5b,,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{533e}
@deffn {C 巨集} PyMem_Resize (p, TYPE, n)

Same as @ref{122d,,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{1719}
@deffn {C 函式} void PyMem_Del (void *p)

和 @ref{1639,,PyMem_Free()} 相同。
@end deffn

In addition, the following macro sets are provided for calling the Python memory
allocator directly, without involving the C API functions listed above. However,
note that their use does not preserve binary compatibility across Python
versions and is therefore deprecated in extension modules.


@itemize *

@item 
@code{PyMem_MALLOC(size)}

@item 
@code{PyMem_NEW(type, size)}

@item 
@code{PyMem_REALLOC(ptr, size)}

@item 
@code{PyMem_RESIZE(ptr, type, size)}

@item 
@code{PyMem_FREE(ptr)}

@item 
@code{PyMem_DEL(ptr)}
@end itemize

@node Object allocators,Default Memory Allocators,記憶體介面,記憶體管理
@anchor{c-api/memory object-allocators}@anchor{533f}@anchor{c-api/memory objectinterface}@anchor{533a}
@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{5340,,Customize Memory Allocators} section.
@end quotation
@end cartouche

The @ref{2002,,default object allocator} uses the
@ref{f06,,pymalloc memory allocator}.

@cartouche
@quotation 警告 
There must be an @ref{4d99,,attached thread state} when using these functions.
@end quotation
@end cartouche

@geindex PyObject_Malloc (C function)
@anchor{c-api/memory c PyObject_Malloc}@anchor{e5d}
@deffn {C 函式} void *PyObject_Malloc (size_t n)
` 為 @ref{76e,,穩定 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{10a9}
@deffn {C 函式} void *PyObject_Calloc (size_t nelem, size_t elsize)
` 為 @ref{76e,,穩定 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.


在 3.5 版被加入.

@end deffn

@geindex PyObject_Realloc (C function)
@anchor{c-api/memory c PyObject_Realloc}@anchor{163a}
@deffn {C 函式} void *PyObject_Realloc (void *p, size_t n)
` 為 @ref{76e,,穩定 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{e5d,,PyObject_Malloc()}, @ref{163a,,PyObject_Realloc()} or @ref{10a9,,PyObject_Calloc()}.

If the request fails, @ref{163a,,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{e5a}
@deffn {C 函式} void PyObject_Free (void *p)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Frees the memory block pointed to by `p', which must have been returned by a
previous call to @ref{e5d,,PyObject_Malloc()}, @ref{163a,,PyObject_Realloc()} or
@ref{10a9,,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{4d97,,tp_free} slot instead.

Do not use this for memory allocated by @ref{c90,,PyObject_GC_New} or
@ref{c91,,PyObject_GC_NewVar}; use @ref{16f7,,PyObject_GC_Del()} instead.


@subsubheading 也參考



@itemize *

@item 
@ref{16f7,,PyObject_GC_Del()} is the equivalent of this function for memory
allocated by types that support garbage collection.

@item 
@ref{e5d,,PyObject_Malloc()}

@item 
@ref{163a,,PyObject_Realloc()}

@item 
@ref{10a9,,PyObject_Calloc()}

@item 
@ref{b73,,PyObject_New}

@item 
@ref{b74,,PyObject_NewVar}

@item 
@ref{c58,,PyType_GenericAlloc()}

@item 
@ref{4d97,,tp_free}
@end itemize

@end deffn

@node Default Memory Allocators,Customize Memory Allocators,Object allocators,記憶體管理
@anchor{c-api/memory default-memory-allocators}@anchor{2002}@anchor{c-api/memory id2}@anchor{5341}
@subsection Default Memory Allocators


Default memory allocators:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx} 
@headitem

配置

@tab

名稱

@tab

PyMem_RawMalloc

@tab

PyMem_Malloc

@tab

PyObject_Malloc

@item

Release build

@tab

@code{"pymalloc"}

@tab

@code{malloc}

@tab

@code{pymalloc}

@tab

@code{pymalloc}

@item

Debug build

@tab

@code{"pymalloc_debug"}

@tab

@code{malloc} + debug

@tab

@code{pymalloc} + debug

@tab

@code{pymalloc} + debug

@item

Release build, without pymalloc

@tab

@code{"malloc"}

@tab

@code{malloc}

@tab

@code{malloc}

@tab

@code{malloc}

@item

Debug build, without pymalloc

@tab

@code{"malloc_debug"}

@tab

@code{malloc} + debug

@tab

@code{malloc} + debug

@tab

@code{malloc} + debug

@end multitable


Legend:


@itemize *

@item 
Name: value for 
@geindex PYTHONMALLOC
@geindex 環境變數; PYTHONMALLOC
@ref{e59,,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{f06,,pymalloc memory allocator}.

@item 
@code{mimalloc}: @ref{2004,,mimalloc memory allocator}.  The pymalloc
allocator will be used if mimalloc support isn't available.

@item 
"+ debug": with @ref{2005,,debug hooks on the Python memory allocators}.

@item 
"Debug build": @ref{504,,Python build in debug mode}.
@end itemize

@node Customize Memory Allocators,Debug hooks on the Python memory allocators,Default Memory Allocators,記憶體管理
@anchor{c-api/memory customize-memory-allocators}@anchor{5340}@anchor{c-api/memory id3}@anchor{5342}
@subsection Customize Memory Allocators



在 3.4 版被加入.


@geindex PyMemAllocatorEx (C type)
@anchor{c-api/memory c PyMemAllocatorEx}@anchor{10c9}
@deffn {C 型別} type PyMemAllocatorEx

Structure used to describe a memory block allocator. The structure has
the following fields:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

欄位

@tab

意義

@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{10c9,,PyMemAllocatorEx} and a new @code{calloc} field was added.

@end deffn

@geindex PyMemAllocatorDomain (C type)
@anchor{c-api/memory c PyMemAllocatorDomain}@anchor{5337}
@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{2003}
@deffn {C 巨集} PYMEM_DOMAIN_RAW

函式：


@itemize *

@item 
@ref{629,,PyMem_RawMalloc()}

@item 
@ref{62b,,PyMem_RawRealloc()}

@item 
@ref{62a,,PyMem_RawCalloc()}

@item 
@ref{62c,,PyMem_RawFree()}
@end itemize
@end deffn

@geindex PYMEM_DOMAIN_MEM (C macro)
@anchor{c-api/memory c PYMEM_DOMAIN_MEM}@anchor{e5e}
@deffn {C 巨集} PYMEM_DOMAIN_MEM

函式：


@itemize *

@item 
@ref{e5b,,PyMem_Malloc()},

@item 
@ref{122d,,PyMem_Realloc()}

@item 
@ref{10a8,,PyMem_Calloc()}

@item 
@ref{1639,,PyMem_Free()}
@end itemize
@end deffn

@geindex PYMEM_DOMAIN_OBJ (C macro)
@anchor{c-api/memory c PYMEM_DOMAIN_OBJ}@anchor{e5c}
@deffn {C 巨集} PYMEM_DOMAIN_OBJ

函式：


@itemize *

@item 
@ref{e5d,,PyObject_Malloc()}

@item 
@ref{163a,,PyObject_Realloc()}

@item 
@ref{10a9,,PyObject_Calloc()}

@item 
@ref{e5a,,PyObject_Free()}
@end itemize
@end deffn
@end deffn

@geindex PyMem_GetAllocator (C function)
@anchor{c-api/memory c PyMem_GetAllocator}@anchor{52a2}
@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{7a1}
@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{2003,,PYMEM_DOMAIN_RAW} domain, the allocator must be
thread-safe: a @ref{17c4,,thread state} is not @ref{4d99,,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{164,,GIL}.

If the new allocator is not a hook (does not call the previous allocator),
the @ref{e5f,,PyMem_SetupDebugHooks()} function must be called to reinstall the
debug hooks on top on the new allocator.

See also @ref{52f9,,PyPreConfig.allocator} and @ref{4183,,Preinitialize Python with PyPreConfig}.

@cartouche
@quotation 警告 
@ref{7a1,,PyMem_SetAllocator()} does have the following contract:


@itemize *

@item 
It can be called after @ref{41c,,Py_PreInitialize()} and before
@ref{3f5,,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{4d99,,attached thread state}).
See @ref{5336,,the section on allocator domains} for more
information.

@item 
If called after Python has finish initializing (after
@ref{3f5,,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{e5f}
@deffn {C 函式} void PyMem_SetupDebugHooks (void)

Setup @ref{2005,,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,記憶體管理
@anchor{c-api/memory debug-hooks-on-the-python-memory-allocators}@anchor{5343}@anchor{c-api/memory pymem-debug-hooks}@anchor{2005}
@subsection Debug hooks on the Python memory allocators


When @ref{504,,Python is built in debug mode}, the
@ref{e5f,,PyMem_SetupDebugHooks()} function is called at the @ref{4183,,Python preinitialization} to setup debug hooks on Python memory allocators
to detect memory errors.

The 
@geindex PYTHONMALLOC
@geindex 環境變數; PYTHONMALLOC
@ref{e59,,PYTHONMALLOC} environment variable can be used to install debug
hooks on a Python compiled in release mode (ex: @code{PYTHONMALLOC=debug}).

The @ref{e5f,,PyMem_SetupDebugHooks()} function can be used to set debug hooks
after calling @ref{7a1,,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 檢查：


@itemize -

@item 
Detect API violations. For example, detect if @ref{e5a,,PyObject_Free()} is
called on a memory block allocated by @ref{e5b,,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{4d99,,attached thread state} when
allocator functions of @ref{e5c,,PYMEM_DOMAIN_OBJ} (ex:
@ref{e5d,,PyObject_Malloc()}) and @ref{e5e,,PYMEM_DOMAIN_MEM} (ex:
@ref{e5b,,PyMem_Malloc()}) domains are called.
@end itemize

On error, the debug hooks use the @ref{105,,tracemalloc} module to get the
traceback where a memory block was allocated. The traceback is only displayed
if @ref{105,,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{2003,,PYMEM_DOMAIN_RAW}.

@item 
@code{'m'} for @ref{e5e,,PYMEM_DOMAIN_MEM}.

@item 
@code{'o'} for @ref{e5c,,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{e5f,,PyMem_SetupDebugHooks()} function now also works on Python
compiled in release mode.  On error, the debug hooks now use
@ref{105,,tracemalloc} to get the traceback where a memory block was allocated.
The debug hooks now also check if there is an @ref{4d99,,attached thread state} when
functions of @ref{e5c,,PYMEM_DOMAIN_OBJ} and @ref{e5e,,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,記憶體管理
@anchor{c-api/memory pymalloc}@anchor{f06}@anchor{c-api/memory the-pymalloc-allocator}@anchor{5344}
@subsection The pymalloc allocator


Python has a `pymalloc' allocator optimized for small objects (smaller or equal
to 512 bytes) with a short lifetime. It uses memory mappings called "arenas"
with a fixed size of either 256 KiB on 32-bit platforms or 1 MiB on 64-bit
platforms. It falls back to @ref{629,,PyMem_RawMalloc()} and
@ref{62b,,PyMem_RawRealloc()} for allocations larger than 512 bytes.

`pymalloc' is the @ref{2002,,default allocator} of the
@ref{e5e,,PYMEM_DOMAIN_MEM} (ex: @ref{e5b,,PyMem_Malloc()}) and
@ref{e5c,,PYMEM_DOMAIN_OBJ} (ex: @ref{e5d,,PyObject_Malloc()}) domains.

The arena allocator uses the following functions:


@itemize *

@item 
Windows 上的 @code{VirtualAlloc()} 和 @code{VirtualFree()}，

@item 
如果可用，則使用 @code{mmap()} 和 @code{munmap()}，

@item 
否則使用 @code{malloc()} 和 @code{free()}。
@end itemize

This allocator is disabled if Python is configured with the
@ref{2064,,--without-pymalloc} option. It can also be disabled at runtime using
the 
@geindex PYTHONMALLOC
@geindex 環境變數; PYTHONMALLOC
@ref{e59,,PYTHONMALLOC} environment variable (ex: @code{PYTHONMALLOC=malloc}).

Typically, it makes sense to disable the pymalloc allocator when building
Python with AddressSanitizer (@ref{206d,,--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{5345}
@subsubsection Customize pymalloc Arena Allocator



在 3.4 版被加入.


@geindex PyObjectArenaAllocator (C type)
@anchor{c-api/memory c PyObjectArenaAllocator}@anchor{5346}
@deffn {C 型別} type PyObjectArenaAllocator

Structure used to describe an arena allocator. The structure has
three fields:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

欄位

@tab

意義

@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{52a3}
@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{52a1}
@deffn {C 函式} void PyObject_SetArenaAllocator (PyObjectArenaAllocator *allocator)

Set the arena allocator.
@end deffn

@node The mimalloc allocator,tracemalloc C API,The pymalloc allocator,記憶體管理
@anchor{c-api/memory mimalloc}@anchor{2004}@anchor{c-api/memory the-mimalloc-allocator}@anchor{5347}
@subsection The mimalloc allocator



在 3.13 版被加入.


Python supports the mimalloc allocator when the underlying platform support is available.
mimalloc "is a general purpose allocator with excellent performance characteristics.
Initially developed by Daan Leijen for the runtime systems of the Koka and Lean languages."

@node tracemalloc C API,範例<55>,The mimalloc allocator,記憶體管理
@anchor{c-api/memory tracemalloc-c-api}@anchor{5348}
@subsection tracemalloc C API



在 3.7 版被加入.


@geindex PyTraceMalloc_Track (C function)
@anchor{c-api/memory c PyTraceMalloc_Track}@anchor{daa}
@deffn {C 函式} int PyTraceMalloc_Track (unsigned int domain, uintptr_t ptr, size_t size)

Track an allocated memory block in the @ref{105,,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{dab}
@deffn {C 函式} int PyTraceMalloc_Untrack (unsigned int domain, uintptr_t ptr)

Untrack an allocated memory block in the @ref{105,,tracemalloc} module.
Do nothing if the block was not tracked.

Return @code{-2} if tracemalloc is disabled, otherwise return @code{0}.
@end deffn

@node 範例<55>,,tracemalloc C API,記憶體管理
@anchor{c-api/memory examples}@anchor{5349}@anchor{c-api/memory memoryexamples}@anchor{534a}
@subsection 範例


Here is the example from section @ref{5333,,總覽}, 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{b73,,PyObject_New},
@ref{b74,,PyObject_NewVar} and @ref{e5a,,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 物件實作支援,API 和 ABI 版本管理,記憶體管理,Python/C API 參考手冊
@anchor{c-api/objimpl doc}@anchor{534b}@anchor{c-api/objimpl newtypes}@anchor{534c}@anchor{c-api/objimpl object-implementation-support}@anchor{534d}@anchor{c-api/objimpl translation-repo}@anchor{534e}
@section 物件實作支援


本章節說明在定義新的物件型別時所使用的函式、型別和巨集。

@menu
* 在 heap 上分配物件:: 
* 物件生命週期:: 
* 通用物件結構:: 
* 型別物件結構:: 
* 循環垃圾回收的支援:: 

@end menu

@node 在 heap 上分配物件,物件生命週期,,物件實作支援
@anchor{c-api/allocation doc}@anchor{534f}@anchor{c-api/allocation allocating-objects}@anchor{5350}@anchor{c-api/allocation allocating-objects-on-the-heap}@anchor{5351}
@subsection 在 heap 上分配物件


@geindex _PyObject_New (C function)
@anchor{c-api/allocation c _PyObject_New}@anchor{5352}
@deffn {C 函式} @ref{5d7,,PyObject} *_PyObject_New (PyTypeObject *type)
`回傳值：新的參照。'
@end deffn

@geindex _PyObject_NewVar (C function)
@anchor{c-api/allocation c _PyObject_NewVar}@anchor{5353}
@deffn {C 函式} @ref{458f,,PyVarObject} *_PyObject_NewVar (PyTypeObject *type, Py_ssize_t size)
`回傳值：新的參照。'
@end deffn

@geindex PyObject_Init (C function)
@anchor{c-api/allocation c PyObject_Init}@anchor{c57}
@deffn {C 函式} @ref{5d7,,PyObject} *PyObject_Init (PyObject *op, PyTypeObject *type)
`回傳值：借用參照。'` 為 @ref{76e,,穩定 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{8b7,,__init__()} method (@ref{79a,,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{4d98,,tp_alloc} where possible.
For implementing @code{tp_alloc} for your type, prefer
@ref{c58,,PyType_GenericAlloc()} or @ref{b73,,PyObject_New()}.

@cartouche
@quotation 備註 
This function only initializes the object's memory corresponding to the
initial @ref{5d7,,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{1c0a}
@deffn {C 函式} @ref{458f,,PyVarObject} *PyObject_InitVar (PyVarObject *op, PyTypeObject *type, Py_ssize_t size)
`回傳值：借用參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
它會做到 @ref{c57,,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{b73}
@deffn {C 巨集} PyObject_New (TYPE, typeobj)

使用 C 結構型別 `TYPE' 和 Python 型別物件 `typeobj' (@code{PyTypeObject*}) 分配一個新的 Python 物件。它會呼叫 @ref{e5d,,PyObject_Malloc()} 來分配記憶體，並且會像 @ref{c57,,PyObject_Init()} 一樣初始化它。呼叫者會擁有該物件的唯一參照（也就是它的參照計數會是 1）。

Avoid calling this directly to allocate memory for an object; call the type's
@ref{4d98,,tp_alloc} slot instead.

When populating a type's @ref{4d98,,tp_alloc} slot,
@ref{c58,,PyType_GenericAlloc()} is preferred over a custom function that
simply calls this macro.

這個巨集不會呼叫 @ref{4d98,,tp_alloc}、@ref{798,,tp_new} (@ref{799,,__new__()})、或 @ref{79a,,tp_init} (@ref{8b7,,__init__()})。

這不能用於有在 @ref{1b73,,tp_flags} 中設定 @ref{978,,Py_TPFLAGS_HAVE_GC} 的物件；請改用 @ref{c90,,PyObject_GC_New}。

Memory allocated by this macro must be freed with @ref{e5a,,PyObject_Free()}
(usually called via the object's @ref{4d97,,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{79a,,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{e5a,,PyObject_Free()}

@item 
@ref{c90,,PyObject_GC_New}

@item 
@ref{c58,,PyType_GenericAlloc()}

@item 
@ref{4d98,,tp_alloc}
@end itemize

@end deffn

@geindex PyObject_NewVar (C macro)
@anchor{c-api/allocation c PyObject_NewVar}@anchor{b74}
@deffn {C 巨集} PyObject_NewVar (TYPE, typeobj, size)

和 @ref{b73,,PyObject_New} 類似，但有以下差異：


@itemize *

@item 
It allocates enough memory for the `TYPE' structure plus `size'
(@code{Py_ssize_t}) fields of the size given by the
@ref{226d,,tp_itemsize} field of `typeobj'.

@item 
記憶體會像 @ref{1c0a,,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{4d98,,tp_alloc} slot instead.

When populating a type's @ref{4d98,,tp_alloc} slot,
@ref{c58,,PyType_GenericAlloc()} is preferred over a custom function that
simply calls this macro.

這不能用於有在 @ref{1b73,,tp_flags} 中設定 @ref{978,,Py_TPFLAGS_HAVE_GC} 的物件；請改用 @ref{c91,,PyObject_GC_NewVar}。

Memory allocated by this function must be freed with @ref{e5a,,PyObject_Free()}
(usually called via the object's @ref{4d97,,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{79a,,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{e5a,,PyObject_Free()}

@item 
@ref{c91,,PyObject_GC_NewVar}

@item 
@ref{c58,,PyType_GenericAlloc()}

@item 
@ref{4d98,,tp_alloc}
@end itemize

@end deffn

@geindex PyObject_Del (C function)
@anchor{c-api/allocation c PyObject_Del}@anchor{16c5}
@deffn {C 函式} void PyObject_Del (void *op)

和 @ref{e5a,,PyObject_Free()} 相同。
@end deffn

@geindex _Py_NoneStruct (C var)
@anchor{c-api/allocation c _Py_NoneStruct}@anchor{5354}
@deffn {C 變數} @ref{5d7,,PyObject} _Py_NoneStruct

這個物件像是 Python 中的 @code{None}。它只應該透過 @ref{4d67,,Py_None} 巨集來存取，該巨集的拿到指向該物件的指標。
@end deffn


@subsubheading 也參考



@table @asis

@item @ref{51fa,,模組物件}

分配記憶體和建立擴充模組。
@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 物件生命週期,通用物件結構,在 heap 上分配物件,物件實作支援
@anchor{c-api/lifecycle doc}@anchor{5355}@anchor{c-api/lifecycle life-cycle}@anchor{5356}@anchor{c-api/lifecycle object-life-cycle}@anchor{5357}@anchor{c-api/lifecycle translation-repo}@anchor{5358}
@subsection 物件生命週期


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{b7b,,型別物件結構} for details about a particular slot.

@menu
* 生命事件:: 
* Cyclic Isolate Destruction:: 
* 函式: 函式<14>. 

@end menu

@node 生命事件,Cyclic Isolate Destruction,,物件生命週期
@anchor{c-api/lifecycle life-events}@anchor{5359}
@subsubsection 生命事件


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}


說明：


@itemize *

@item 
當一個新物件透過其型別來建構時：


@enumerate 

@item 
@ref{798,,tp_new} 會被呼叫來建立一個新物件。

@item 
@ref{4d98,,tp_alloc} is directly called by
@ref{798,,tp_new} to allocate the memory for the new
object.

@item 
@ref{79a,,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{799,,__new__()}.
@end enumerate

@item 
在 @code{tp_init} 完成後，該物件即可使用。

@item 
在最後一個對物件的參照被移除一段時間後：


@enumerate 

@item 
If an object is not marked as `finalized', it might be finalized by
marking it as `finalized' and calling its
@ref{c94,,tp_finalize} function.  Python does
`not' finalize an object when the last reference to it is deleted; use
@ref{535a,,PyObject_CallFinalizerFromDealloc()} to ensure that
@ref{c94,,tp_finalize} is always called.

@item 
If the object is marked as finalized,
@ref{4daa,,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{4d84,,tp_dealloc} is called to destroy the object.
To avoid code duplication, @ref{4d84,,tp_dealloc} typically
calls into @ref{4daa,,tp_clear} to free up the object's
references.

@item 
When @ref{4d84,,tp_dealloc} finishes object destruction,
it directly calls @ref{4d97,,tp_free} (usually set to
@ref{e5a,,PyObject_Free()} or @ref{16f7,,PyObject_GC_Del()} automatically as
appropriate for the type) to deallocate the memory.
@end enumerate

@item 
The @ref{c94,,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{4daa,,tp_clear} and
@ref{4d84,,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{978,,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{4d84,,tp_dealloc} can optionally call
@ref{c94,,tp_finalize} via
@ref{535a,,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 @ref{4d84,,tp_dealloc} documentation
for example code.

@item 
If the object is a member of a @ref{535b,,cyclic isolate} and either
@ref{4daa,,tp_clear} fails to break the reference cycle or
the cyclic isolate is not detected (perhaps @ref{48c6,,gc.disable()} was called,
or the @ref{978,,Py_TPFLAGS_HAVE_GC} flag was erroneously omitted in one
of the involved types), the objects remain indefinitely uncollectable
(they "leak").  See @ref{13c2,,gc.garbage}.
@end itemize

If the object is marked as supporting garbage collection (the
@ref{978,,Py_TPFLAGS_HAVE_GC} flag is set in
@ref{1b73,,tp_flags}), the following events are also possible:


@itemize *

@item 
The garbage collector occasionally calls
@ref{979,,tp_traverse} to identify @ref{535b,,cyclic isolates}.

@item 
When the garbage collector discovers a @ref{535b,,cyclic isolate}, it
finalizes one of the objects in the group by marking it as `finalized' and
calling its @ref{c94,,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{c94,,tp_finalize} is permitted to resurrect the object
by adding a reference from outside the @ref{535b,,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{535b,,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{4daa,,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,函式<14>,生命事件,物件生命週期
@anchor{c-api/lifecycle cyclic-isolate-destruction}@anchor{535c}
@subsubsection Cyclic Isolate Destruction


Listed below are the stages of life of a hypothetical @ref{535b,,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{c94,,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{164,,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{13c2,,gc.garbage}).  It is a bug if a cyclic isolate
reaches this stage---it means the @ref{4daa,,tp_clear} methods
of the participating objects have failed to break the reference cycle as
required.
@end enumerate

If @ref{4daa,,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
@ref{4daa,,tp_clear} is called to partially destroy the objects
enough to detangle them from each other, then
@ref{4d84,,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{4daa,,tp_clear} (if
called) and concludes with @ref{4d84,,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{c94,,tp_finalize} and @ref{4daa,,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
@ref{c94,,tp_finalize} and @ref{4daa,,tp_clear} as
needed to destroy a cyclic isolate; this may change in a future version.

@node 函式<14>,,Cyclic Isolate Destruction,物件生命週期
@anchor{c-api/lifecycle functions}@anchor{535d}
@subsubsection 函式


要分配和釋放記憶體，請參見 @ref{5350,,在 heap 上分配物件}。

@geindex PyObject_CallFinalizer (C function)
@anchor{c-api/lifecycle c PyObject_CallFinalizer}@anchor{535e}
@deffn {C 函式} void PyObject_CallFinalizer (PyObject *op)

Finalizes the object as described in @ref{c94,,tp_finalize}.
Call this function (or @ref{535a,,PyObject_CallFinalizerFromDealloc()}) instead
of calling @ref{c94,,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{978,,Py_TPFLAGS_HAVE_GC} flag is set); this may
change in the future.
@end deffn

@geindex PyObject_CallFinalizerFromDealloc (C function)
@anchor{c-api/lifecycle c PyObject_CallFinalizerFromDealloc}@anchor{535a}
@deffn {C 函式} int PyObject_CallFinalizerFromDealloc (PyObject *op)

Same as @ref{535e,,PyObject_CallFinalizer()} but meant to be called at the
beginning of the object's destructor (@ref{4d84,,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.


@subsubheading 也參考


@ref{4d84,,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 通用物件結構,型別物件結構,物件生命週期,物件實作支援
@anchor{c-api/structures doc}@anchor{535f}@anchor{c-api/structures common-object-structures}@anchor{5360}@anchor{c-api/structures common-structs}@anchor{5361}@anchor{c-api/structures translation-repo}@anchor{5362}
@subsection 通用物件結構


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:: 
* 實作函式與方法:: 
* Accessing attributes of extension types:: 

@end menu

@node Base object types and macros,實作函式與方法,,通用物件結構
@anchor{c-api/structures base-object-types-and-macros}@anchor{5363}
@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{5d7,,PyObject} and @ref{458f,,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{4fdd,,reference counting}.

@geindex PyObject (C type)
@anchor{c-api/structures c PyObject}@anchor{5d7}
@deffn {C 型別} type PyObject
` 為 @ref{76e,,受限 API 的一部分}. （只有部分成員是穩定 ABI 的一部分。）'
All object types are extensions of this type.  This is a type which
contains the information Python needs to treat a pointer to an object as an
object.  In a normal "release" build, it contains only the object's
reference count and a pointer to the corresponding type object.
Nothing is actually declared to be a @ref{5d7,,PyObject}, but every pointer
to a Python object can be cast to a @ref{5d7,,PyObject}*.

The members must not be accessed directly; instead use macros such as
@ref{2cf,,Py_REFCNT} and @ref{3c7,,Py_TYPE}.

@geindex PyObject.ob_refcnt (C member)
@anchor{c-api/structures c PyObject ob_refcnt}@anchor{a96}
@deffn {C 成員函數} @ref{c4c,,Py_ssize_t} ob_refcnt
` 為 @ref{76e,,穩定 ABI 的一部分}.'
The object's reference count, as returned by @ref{2cf,,Py_REFCNT}.
Do not use this field directly; instead use functions and macros such as
@code{Py_REFCNT}, @ref{788,,Py_INCREF()} and @ref{4f8f,,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{4d95}
@deffn {C 成員函數} @ref{c93,,PyTypeObject} *ob_type
` 為 @ref{76e,,穩定 ABI 的一部分}.'
The object's type.
Do not use this field directly; use @ref{3c7,,Py_TYPE} and
@ref{97c,,Py_SET_TYPE()} instead.
@end deffn
@end deffn

@geindex PyVarObject (C type)
@anchor{c-api/structures c PyVarObject}@anchor{458f}
@deffn {C 型別} type PyVarObject
` 為 @ref{76e,,受限 API 的一部分}. （只有部分成員是穩定 ABI 的一部分。）'
An extension of @ref{5d7,,PyObject} that adds the
@ref{4f8a,,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{97d,,Py_SIZE}, @ref{2cf,,Py_REFCNT} and
@ref{3c7,,Py_TYPE}.

@geindex PyVarObject.ob_size (C member)
@anchor{c-api/structures c PyVarObject ob_size}@anchor{4f8a}
@deffn {C 成員函數} @ref{c4c,,Py_ssize_t} ob_size
` 為 @ref{76e,,穩定 ABI 的一部分}.'
A size field, whose contents should be considered an object's internal
implementation detail.

Do not use this field directly; use @ref{97d,,Py_SIZE} instead.

Object creation functions such as @ref{b74,,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{97e,,Py_SET_SIZE}.

To get an object's publicly exposed length, as returned by
the Python function @ref{839,,len()}, use @ref{4f16,,PyObject_Length()}
instead.
@end deffn
@end deffn

@geindex PyObject_HEAD (C macro)
@anchor{c-api/structures c PyObject_HEAD}@anchor{14de}
@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{5d7,,PyObject} above.
@end deffn

@geindex PyObject_VAR_HEAD (C macro)
@anchor{c-api/structures c PyObject_VAR_HEAD}@anchor{5364}
@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

請見上面 @ref{458f,,PyVarObject} 的文件。
@end deffn

@geindex PyBaseObject_Type (C var)
@anchor{c-api/structures c PyBaseObject_Type}@anchor{4e17}
@deffn {C 變數} @ref{c93,,PyTypeObject} PyBaseObject_Type
` 為 @ref{76e,,穩定 ABI 的一部分}.'
The base class of all other objects, the same as @ref{c75,,object} in Python.
@end deffn

@geindex Py_Is (C function)
@anchor{c-api/structures c Py_Is}@anchor{a97}
@deffn {C 函式} int Py_Is (PyObject *x, PyObject *y)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.10 版本開始.'
Test if the `x' object is the `y' object, the same as @code{x is y} in Python.


在 3.10 版被加入.

@end deffn

@geindex Py_IsNone (C function)
@anchor{c-api/structures c Py_IsNone}@anchor{a98}
@deffn {C 函式} int Py_IsNone (PyObject *x)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.10 版本開始.'
Test if an object is the @code{None} singleton,
the same as @code{x is None} in Python.


在 3.10 版被加入.

@end deffn

@geindex Py_IsTrue (C function)
@anchor{c-api/structures c Py_IsTrue}@anchor{a99}
@deffn {C 函式} int Py_IsTrue (PyObject *x)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.10 版本開始.'
Test if an object is the @code{True} singleton,
the same as @code{x is True} in Python.


在 3.10 版被加入.

@end deffn

@geindex Py_IsFalse (C function)
@anchor{c-api/structures c Py_IsFalse}@anchor{a9a}
@deffn {C 函式} int Py_IsFalse (PyObject *x)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.10 版本開始.'
Test if an object is the @code{False} singleton,
the same as @code{x is False} in Python.


在 3.10 版被加入.

@end deffn

@geindex Py_TYPE (C function)
@anchor{c-api/structures c Py_TYPE}@anchor{3c7}
@deffn {C 函式} @ref{c93,,PyTypeObject} *Py_TYPE (PyObject *o)
`回傳值：借用參照。'` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.14 版本開始.'
Get the type of the Python object `o'.

The returned reference is @ref{3d5,,borrowed} from `o'.
Do not release it with @ref{789,,Py_DECREF()} or similar.


在 3.11 版的變更: @ref{3c7,,Py_TYPE()} is changed to an inline static function.
The parameter type is no longer const @ref{5d7,,PyObject}*.

@end deffn

@geindex Py_IS_TYPE (C function)
@anchor{c-api/structures c Py_IS_TYPE}@anchor{1aca}
@deffn {C 函式} int Py_IS_TYPE (PyObject *o, PyTypeObject *type)

Return non-zero if the object `o' type is `type'. Return zero otherwise.
Equivalent to: @code{Py_TYPE(o) == type}.


在 3.9 版被加入.

@end deffn

@geindex Py_SET_TYPE (C function)
@anchor{c-api/structures c Py_SET_TYPE}@anchor{97c}
@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{16a1,,__class__}
using @ref{18e8,,PyObject_SetAttrString()} or similar.

Note that assigning an incompatible type can lead to undefined behavior.

If `type' is a @ref{b55,,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.


在 3.9 版被加入.

@end deffn

@geindex Py_SIZE (C function)
@anchor{c-api/structures c Py_SIZE}@anchor{97d}
@deffn {C 函式} @ref{c4c,,Py_ssize_t} Py_SIZE (PyVarObject *o)

Get the @ref{4f8a,,ob_size} field of `o'.


在 3.11 版的變更: @ref{97d,,Py_SIZE()} is changed to an inline static function.
The parameter type is no longer const @ref{458f,,PyVarObject}*.

@end deffn

@geindex Py_SET_SIZE (C function)
@anchor{c-api/structures c Py_SET_SIZE}@anchor{97e}
@deffn {C 函式} void Py_SET_SIZE (PyVarObject *o, Py_ssize_t size)

Set the @ref{4f8a,,ob_size} field of `o' to `size'.


在 3.9 版被加入.

@end deffn

@geindex PyObject_HEAD_INIT (C macro)
@anchor{c-api/structures c PyObject_HEAD_INIT}@anchor{5365}
@deffn {C 巨集} PyObject_HEAD_INIT (type)

This is a macro which expands to initialization values for a new
@ref{5d7,,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{5366}
@deffn {C 巨集} PyVarObject_HEAD_INIT (type, size)

This is a macro which expands to initialization values for a new
@ref{458f,,PyVarObject} type, including the @ref{4f8a,,ob_size} field.
This macro expands to:

@example
_PyObject_EXTRA_INIT
1, type, size,
@end example
@end deffn

@node 實作函式與方法,Accessing attributes of extension types,Base object types and macros,通用物件結構
@anchor{c-api/structures implementing-functions-and-methods}@anchor{5367}
@subsubsection 實作函式與方法


@geindex PyCFunction (C type)
@anchor{c-api/structures c PyCFunction}@anchor{166c}
@deffn {C 型別} type PyCFunction
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Type of the functions used to implement most Python callables in C.
Functions of this type take two @ref{5d7,,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{4e29}
@deffn {C 型別} type PyCFunctionWithKeywords
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Type of the functions used to implement Python callables in C
with signature @ref{5368,,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{4e27}
@deffn {C 型別} type PyCFunctionFast
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.13 版本開始.'
Type of the functions used to implement Python callables in C
with signature @ref{18f5,,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{4e28}
@deffn {C 型別} type PyCFunctionFastWithKeywords
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.13 版本開始.'
Type of the functions used to implement Python callables in C
with signature @ref{5369,,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{960}
@deffn {C 型別} type PyCMethod

Type of the functions used to implement Python callables in C
with signature @ref{1958,,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


在 3.9 版被加入.

@end deffn

@geindex PyMethodDef (C type)
@anchor{c-api/structures c PyMethodDef}@anchor{16cb}
@deffn {C 型別} type PyMethodDef
` 為 @ref{76e,,穩定 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{4db1}
@deffn {C 成員函數} const char *ml_name

Name of the method.
@end deffn

@geindex PyMethodDef.ml_meth (C member)
@anchor{c-api/structures c PyMethodDef ml_meth}@anchor{536a}
@deffn {C 成員函數} @ref{166c,,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{536b}
@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{536c}
@deffn {C 成員函數} const char *ml_doc

Points to the contents of the docstring.
@end deffn
@end deffn

The @ref{536a,,ml_meth} is a C function pointer.
The functions may be of different
types, but they always return @ref{5d7,,PyObject}*.  If the function is not of
the @ref{166c,,PyCFunction}, the compiler will require a cast in the method table.
Even though @ref{166c,,PyCFunction} defines the first parameter as
@ref{5d7,,PyObject}*, it is common that the method implementation uses the
specific C type of the `self' object.

The @ref{536b,,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{16fc}
@deffn {C 巨集} METH_VARARGS

This is the typical calling convention, where the methods have the type
@ref{166c,,PyCFunction}. The function expects two @ref{5d7,,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{3bf,,PyArg_ParseTuple()} or @ref{16fa,,PyArg_UnpackTuple()}.
@end deffn

@geindex METH_KEYWORDS (C macro)
@anchor{c-api/structures c METH_KEYWORDS}@anchor{4d6a}
@deffn {C 巨集} METH_KEYWORDS

Can only be used in certain combinations with other flags:
@ref{5368,,METH_VARARGS | METH_KEYWORDS},
@ref{5369,,METH_FASTCALL | METH_KEYWORDS} and
@ref{1958,,METH_METHOD | METH_FASTCALL | METH_KEYWORDS}.
@end deffn
@anchor{c-api/structures meth-varargs-meth-keywords}@anchor{5368}

@table @asis

@item @ref{16fc,,METH_VARARGS} | @ref{4d6a,,METH_KEYWORDS}

Methods with these flags must be of type @ref{4e29,,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{61c,,PyArg_ParseTupleAndKeywords()}.
@end table

@geindex METH_FASTCALL (C macro)
@anchor{c-api/structures c METH_FASTCALL}@anchor{18f5}
@deffn {C 巨集} METH_FASTCALL

Fast calling convention supporting only positional arguments.
The methods have the type @ref{4e27,,PyCFunctionFast}.
The first parameter is `self', the second parameter is a C array
of @ref{5d7,,PyObject}* values indicating the arguments and the third
parameter is the number of arguments (the length of the array).


在 3.7 版被加入.



在 3.10 版的變更: @code{METH_FASTCALL} is now part of the @ref{4e0e,,stable ABI}.

@end deffn
@anchor{c-api/structures meth-fastcall-meth-keywords}@anchor{5369}

@table @asis

@item @ref{18f5,,METH_FASTCALL} | @ref{4d6a,,METH_KEYWORDS}

Extension of @ref{18f5,,METH_FASTCALL} supporting also keyword arguments,
with methods of type @ref{4e28,,PyCFunctionFastWithKeywords}.
Keyword arguments are passed the same way as in the
@ref{76d,,vectorcall protocol}:
there is an additional fourth @ref{5d7,,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.


在 3.7 版被加入.

@end table

@geindex METH_METHOD (C macro)
@anchor{c-api/structures c METH_METHOD}@anchor{b5f}
@deffn {C 巨集} METH_METHOD

Can only be used in the combination with other flags:
@ref{1958,,METH_METHOD | METH_FASTCALL | METH_KEYWORDS}.
@end deffn
@anchor{c-api/structures meth-method-meth-fastcall-meth-keywords}@anchor{1958}

@table @asis

@item @ref{b5f,,METH_METHOD} | @ref{18f5,,METH_FASTCALL} | @ref{4d6a,,METH_KEYWORDS}

Extension of @ref{5369,,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{960,,PyCMethod}, the same as for
@code{METH_FASTCALL | METH_KEYWORDS} with @code{defining_class} argument added after
@code{self}.


在 3.9 版被加入.

@end table

@geindex METH_NOARGS (C macro)
@anchor{c-api/structures c METH_NOARGS}@anchor{16c8}
@deffn {C 巨集} METH_NOARGS

Methods without parameters don't need to check whether arguments are given if
they are listed with the @ref{16c8,,METH_NOARGS} flag.  They need to be of type
@ref{166c,,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{19dc,,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{16fb}
@deffn {C 巨集} METH_O

Methods with a single object argument can be listed with the @ref{16fb,,METH_O}
flag, instead of invoking @ref{3bf,,PyArg_ParseTuple()} with a @code{"O"} argument.
They have the type @ref{166c,,PyCFunction}, with the `self' parameter, and a
@ref{5d7,,PyObject}* parameter representing the single argument.
@end deffn

These two constants are not used to indicate the calling convention but the
binding when use with methods of classes.  These may not be used for functions
defined for modules.  At most one of these flags may be set for any given
method.

@geindex METH_CLASS (C macro)
@anchor{c-api/structures c METH_CLASS}@anchor{16c9}
@deffn {C 巨集} METH_CLASS

@geindex built-in function（內建函式）;classmethod

The method will be passed the type object as the first parameter rather
than an instance of the type.  This is used to create `class methods',
similar to what is created when using the @ref{489,,classmethod()} built-in
function.
@end deffn

@geindex METH_STATIC (C macro)
@anchor{c-api/structures c METH_STATIC}@anchor{16ca}
@deffn {C 巨集} METH_STATIC

@geindex built-in function（內建函式）;staticmethod

The method will be passed @code{NULL} as the first parameter rather than an
instance of the type.  This is used to create `static methods', similar to
what is created when using the @ref{451,,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{166b}
@deffn {C 巨集} METH_COEXIST

The method will be loaded in place of existing definitions.  Without
`METH_COEXIST', the default is to skip repeated definitions.  Since slot
wrappers are loaded before the method table, the existence of a
`sq_contains' slot, for example, would generate a wrapped method named
@ref{15b1,,__contains__()} and preclude the loading of a corresponding
PyCFunction with the same name.  With the flag defined, the PyCFunction
will be loaded in place of the wrapper object and will co-exist with the
slot.  This is helpful because calls to PyCFunctions are optimized more
than wrapper object calls.
@end deffn

@geindex PyCMethod_New (C function)
@anchor{c-api/structures c PyCMethod_New}@anchor{1ba3}
@deffn {C 函式} @ref{5d7,,PyObject} *PyCMethod_New (PyMethodDef *ml, PyObject *self, PyObject *module, PyTypeObject *cls)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.9 版本開始.'
Turn `ml' into a Python @ref{2c2e,,callable} object.
The caller must ensure that `ml' outlives the @ref{2c2e,,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{2c2e,,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{87e,,None} or @code{NULL}.


@subsubheading 也參考


@ref{21fc,,function.__module__}


The `cls' parameter will be passed as the `defining_class'
argument to the C function.
Must be set if @ref{b5f,,METH_METHOD} is set on @code{ml->ml_flags}.


在 3.9 版被加入.

@end deffn

@geindex PyCFunction_NewEx (C function)
@anchor{c-api/structures c PyCFunction_NewEx}@anchor{1c3f}
@deffn {C 函式} @ref{5d7,,PyObject} *PyCFunction_NewEx (PyMethodDef *ml, PyObject *self, PyObject *module)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分}.'
等價於 @code{PyCMethod_New(ml, self, module, NULL)}。
@end deffn

@geindex PyCFunction_New (C function)
@anchor{c-api/structures c PyCFunction_New}@anchor{1ba9}
@deffn {C 函式} @ref{5d7,,PyObject} *PyCFunction_New (PyMethodDef *ml, PyObject *self)
`回傳值：新的參照。'` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.4 版本開始.'
等價於 @code{PyCMethod_New(ml, self, NULL, NULL)}。
@end deffn

@node Accessing attributes of extension types,,實作函式與方法,通用物件結構
@anchor{c-api/structures accessing-attributes-of-extension-types}@anchor{536d}
@subsubsection Accessing attributes of extension types


@geindex PyMemberDef (C type)
@anchor{c-api/structures c PyMemberDef}@anchor{76a}
@deffn {C 型別} type PyMemberDef
` 為 @ref{76e,,穩定 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{4d9a,,tp_members} slot.

Its fields are, in order:

@geindex PyMemberDef.name (C member)
@anchor{c-api/structures c PyMemberDef name}@anchor{536e}
@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{4db2}
@deffn {C 成員函數} int type

The type of the member in the C struct.
See @ref{193f,,Member types} for the possible values.
@end deffn

@geindex PyMemberDef.offset (C member)
@anchor{c-api/structures c PyMemberDef offset}@anchor{536f}
@deffn {C 成員函數} @ref{c4c,,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{4db3}
@deffn {C 成員函數} int flags

Zero or more of the @ref{5370,,Member flags}, combined using bitwise OR.
@end deffn

@geindex PyMemberDef.doc (C member)
@anchor{c-api/structures c PyMemberDef doc}@anchor{5371}
@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{1ac0,,PyDoc_STR}.
@end deffn

By default (when @ref{4db3,,flags} is @code{0}), members allow
both read and write access.
Use the @ref{7a7,,Py_READONLY} flag for read-only access.
Certain types, like @ref{5372,,Py_T_STRING}, imply @ref{7a7,,Py_READONLY}.
Only @ref{7aa,,Py_T_OBJECT_EX} (and legacy @ref{7a9,,T_OBJECT}) members can
be deleted.
@anchor{c-api/structures pymemberdef-offsets}@anchor{50d9}
For heap-allocated types (created using @ref{796,,PyType_FromSpec()} or similar),
@code{PyMemberDef} may contain a definition for the special member
@code{"__vectorcalloffset__"}, corresponding to
@ref{5077,,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{50d8,,tp_dictoffset} and
@ref{b76,,tp_weaklistoffset} can be defined similarly using
@code{"__dictoffset__"} and @code{"__weaklistoffset__"} members, but extensions
are strongly encouraged to use @ref{607,,Py_TPFLAGS_MANAGED_DICT} and
@ref{775,,Py_TPFLAGS_MANAGED_WEAKREF} instead.


在 3.12 版的變更: @code{PyMemberDef} is always available.
Previously, it required including @code{"structmember.h"}.



在 3.14 版的變更: @ref{769,,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{7a3}
@deffn {C 函式} @ref{5d7,,PyObject} *PyMember_GetOne (const char *obj_addr, struct PyMemberDef *m)
` 為 @ref{76e,,穩定 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{7a4}
@deffn {C 函式} int PyMember_SetOne (char *obj_addr, struct PyMemberDef *m, PyObject *o)
` 為 @ref{76e,,穩定 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{5373}@anchor{c-api/structures pymemberdef-flags}@anchor{5370}
@subsubsection Member flags


The following flags can be used with @ref{4db3,,PyMemberDef.flags}:

@geindex Py_READONLY (C macro)
@anchor{c-api/structures c Py_READONLY}@anchor{7a7}
@deffn {C 巨集} Py_READONLY

不可寫入。
@end deffn

@geindex Py_AUDIT_READ (C macro)
@anchor{c-api/structures c Py_AUDIT_READ}@anchor{7a8}
@deffn {C 巨集} Py_AUDIT_READ

Emit an @code{object.__getattr__} @ref{1b27,,audit event}
before reading.
@end deffn

@geindex Py_RELATIVE_OFFSET (C macro)
@anchor{c-api/structures c Py_RELATIVE_OFFSET}@anchor{769}
@deffn {C 巨集} Py_RELATIVE_OFFSET

Indicates that the @ref{536f,,offset} of this @code{PyMemberDef}
entry indicates an offset from the subclass-specific data, rather than
from @code{PyObject}.

Can only be used as part of @ref{4d9a,,Py_tp_members}
@ref{4f4a,,slot} when creating a class using negative
@ref{763,,basicsize}.
It is mandatory in that case.

This flag is only used in @ref{4f4a,,PyType_Slot}.
When setting @ref{4d9a,,tp_members} during
class creation, Python clears it and sets
@ref{536f,,PyMemberDef.offset} to the offset from the @code{PyObject} struct.
@end deffn

@geindex READ_RESTRICTED（C 巨集）
@geindex WRITE_RESTRICTED（C 巨集）
@geindex RESTRICTED（C 巨集）


在 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{7a8,,Py_AUDIT_READ}; @code{WRITE_RESTRICTED} does nothing.


@geindex READONLY（C 巨集）


在 3.12 版的變更: The @code{READONLY} macro was renamed to @ref{7a7,,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{5374}@anchor{c-api/structures pymemberdef-types}@anchor{193f}
@subsubsection Member types


@ref{4db2,,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{198,,TypeError} or
@ref{2eb,,ValueError} is raised.

Unless marked (D), attributes defined this way cannot be deleted
using e.g. @ref{1a62,,del} or @ref{2460,,delattr()}.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

巨集名稱

@tab

C type

@tab

Python type

@item

@geindex Py_T_BYTE (C macro)
@anchor{c-api/structures c Py_T_BYTE}@anchor{5375}
@deffn {C 巨集} Py_T_BYTE
@end deffn

@tab

char

@tab

@ref{19b,,int}

@item

@geindex Py_T_SHORT (C macro)
@anchor{c-api/structures c Py_T_SHORT}@anchor{5376}
@deffn {C 巨集} Py_T_SHORT
@end deffn

@tab

short

@tab

@ref{19b,,int}

@item

@geindex Py_T_INT (C macro)
@anchor{c-api/structures c Py_T_INT}@anchor{7a5}
@deffn {C 巨集} Py_T_INT
@end deffn

@tab

int

@tab

@ref{19b,,int}

@item

@geindex Py_T_LONG (C macro)
@anchor{c-api/structures c Py_T_LONG}@anchor{5377}
@deffn {C 巨集} Py_T_LONG
@end deffn

@tab

long

@tab

@ref{19b,,int}

@item

@geindex Py_T_LONGLONG (C macro)
@anchor{c-api/structures c Py_T_LONGLONG}@anchor{5378}
@deffn {C 巨集} Py_T_LONGLONG
@end deffn

@tab

long long

@tab

@ref{19b,,int}

@item

@geindex Py_T_UBYTE (C macro)
@anchor{c-api/structures c Py_T_UBYTE}@anchor{5379}
@deffn {C 巨集} Py_T_UBYTE
@end deffn

@tab

unsigned char

@tab

@ref{19b,,int}

@item

@geindex Py_T_UINT (C macro)
@anchor{c-api/structures c Py_T_UINT}@anchor{537a}
@deffn {C 巨集} Py_T_UINT
@end deffn

@tab

unsigned int

@tab

@ref{19b,,int}

@item

@geindex Py_T_USHORT (C macro)
@anchor{c-api/structures c Py_T_USHORT}@anchor{537b}
@deffn {C 巨集} Py_T_USHORT
@end deffn

@tab

unsigned short

@tab

@ref{19b,,int}

@item

@geindex Py_T_ULONG (C macro)
@anchor{c-api/structures c Py_T_ULONG}@anchor{537c}
@deffn {C 巨集} Py_T_ULONG
@end deffn

@tab

unsigned long

@tab

@ref{19b,,int}

@item

@geindex Py_T_ULONGLONG (C macro)
@anchor{c-api/structures c Py_T_ULONGLONG}@anchor{537d}
@deffn {C 巨集} Py_T_ULONGLONG
@end deffn

@tab

unsigned long long

@tab

@ref{19b,,int}

@item

@geindex Py_T_PYSSIZET (C macro)
@anchor{c-api/structures c Py_T_PYSSIZET}@anchor{537e}
@deffn {C 巨集} Py_T_PYSSIZET
@end deffn

@tab

@ref{c4c,,Py_ssize_t}

@tab

@ref{19b,,int}

@item

@geindex Py_T_FLOAT (C macro)
@anchor{c-api/structures c Py_T_FLOAT}@anchor{537f}
@deffn {C 巨集} Py_T_FLOAT
@end deffn

@tab

float

@tab

@ref{196,,float}

@item

@geindex Py_T_DOUBLE (C macro)
@anchor{c-api/structures c Py_T_DOUBLE}@anchor{7a6}
@deffn {C 巨集} Py_T_DOUBLE
@end deffn

@tab

double

@tab

@ref{196,,float}

@item

@geindex Py_T_BOOL (C macro)
@anchor{c-api/structures c Py_T_BOOL}@anchor{5380}
@deffn {C 巨集} Py_T_BOOL
@end deffn

@tab

char （寫成 0 或 1）

@tab

@ref{3c1,,bool}

@item

@geindex Py_T_STRING (C macro)
@anchor{c-api/structures c Py_T_STRING}@anchor{5372}
@deffn {C 巨集} Py_T_STRING
@end deffn

@tab

const char* (*)

@tab

@ref{169,,str} (RO)

@item

@geindex Py_T_STRING_INPLACE (C macro)
@anchor{c-api/structures c Py_T_STRING_INPLACE}@anchor{5381}
@deffn {C 巨集} Py_T_STRING_INPLACE
@end deffn

@tab

const char[] (*)

@tab

@ref{169,,str} (RO)

@item

@geindex Py_T_CHAR (C macro)
@anchor{c-api/structures c Py_T_CHAR}@anchor{5382}
@deffn {C 巨集} Py_T_CHAR
@end deffn

@tab

char (0-127)

@tab

@ref{169,,str} (**)

@item

@geindex Py_T_OBJECT_EX (C macro)
@anchor{c-api/structures c Py_T_OBJECT_EX}@anchor{7aa}
@deffn {C 巨集} Py_T_OBJECT_EX
@end deffn

@tab

@ref{5d7,,PyObject}*

@tab

@ref{c75,,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{7a7,,Py_READONLY}.

(D): Can be deleted, in which case the pointer is set to @code{NULL}.
Reading a @code{NULL} pointer raises @ref{5e8,,AttributeError}.
@end quotation

@geindex T_BYTE（C 巨集）
@geindex T_SHORT（C 巨集）
@geindex T_INT（C 巨集）
@geindex T_LONG（C 巨集）
@geindex T_LONGLONG（C 巨集）
@geindex T_UBYTE（C 巨集）
@geindex T_USHORT（C 巨集）
@geindex T_UINT（C 巨集）
@geindex T_ULONG（C 巨集）
@geindex T_ULONGULONG（C 巨集）
@geindex T_PYSSIZET（C 巨集）
@geindex T_FLOAT（C 巨集）
@geindex T_DOUBLE（C 巨集）
@geindex T_BOOL（C 巨集）
@geindex T_CHAR（C 巨集）
@geindex T_STRING（C 巨集）
@geindex T_STRING_INPLACE（C 巨集）
@geindex T_OBJECT_EX（C 巨集）
@geindex structmember.h


在 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{7a9}
@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{7ab}
@deffn {C 巨集} T_NONE

Always @code{None}. Must be used with @ref{7a7,,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{5383}
@subsubsection Defining Getters and Setters


@geindex PyGetSetDef (C type)
@anchor{c-api/structures c PyGetSetDef}@anchor{dad}
@deffn {C 型別} type PyGetSetDef
` 為 @ref{76e,,穩定 ABI 的一部分} （包含所有成員）.'
Structure to define property-like access for a type. See also description of
the @ref{4d9f,,PyTypeObject.tp_getset} slot.

@geindex PyGetSetDef.name (C member)
@anchor{c-api/structures c PyGetSetDef name}@anchor{5384}
@deffn {C 成員函數} const char *name

屬性名稱
@end deffn

@geindex PyGetSetDef.get (C member)
@anchor{c-api/structures c PyGetSetDef get}@anchor{5385}
@deffn {C 成員函數} @ref{4fa5,,getter} get

C function to get the attribute.
@end deffn

@geindex PyGetSetDef.set (C member)
@anchor{c-api/structures c PyGetSetDef set}@anchor{5386}
@deffn {C 成員函數} @ref{4fb3,,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{5387}
@deffn {C 成員函數} const char *doc

可選的文件字串
@end deffn

@geindex PyGetSetDef.closure (C member)
@anchor{c-api/structures c PyGetSetDef closure}@anchor{5388}
@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{4fa5}
@deffn {C 型別} typedef @ref{5d7,,PyObject} *(*getter)(@ref{5d7,,PyObject}*, void*)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
The @code{get} function takes one @ref{5d7,,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{4fb3}
@deffn {C 型別} typedef int (*setter)(@ref{5d7,,PyObject}*, @ref{5d7,,PyObject}*, void*)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@code{set} functions take two @ref{5d7,,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 型別物件結構,循環垃圾回收的支援,通用物件結構,物件實作支援
@anchor{c-api/typeobj doc}@anchor{5389}@anchor{c-api/typeobj translation-repo}@anchor{538a}@anchor{c-api/typeobj type-object-structures}@anchor{538b}@anchor{c-api/typeobj type-structs}@anchor{b7b}
@subsection 型別物件結構


Perhaps one of the most important structures of the Python object system is the
structure that defines a new type: the @ref{c93,,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{538c,,範例}
section provides at-a-glance insight into the meaning and use of
@ref{c93,,PyTypeObject}.

@menu
* Quick Reference:: 
* PyTypeObject Definition:: 
* PyObject Slots:: 
* PyVarObject Slots:: 
* PyTypeObject Slots:: 
* 靜態型別:: 
* 堆積型別:: 
* Number Object Structures:: 
* 對映物件結構:: 
* 序列物件結構:: 
* 緩衝區物件結構:: 
* 非同步物件結構:: 
* Slot Type typedefs:: 
* 範例: 範例<56>. 

@end menu

@node Quick Reference,PyTypeObject Definition,,型別物件結構
@anchor{c-api/typeobj quick-reference}@anchor{538d}
@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{538e}@anchor{c-api/typeobj tp-slots-table}@anchor{538f}
@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{5390,,Type}

@tab

special
methods/attrs

@tab

Info @footnote{
Columns:

`"O"':  set on @ref{4e17,,PyBaseObject_Type}

`"T"':  set on @ref{768,,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{1ba8,,tp_name}

@tab

const char *

@tab

__name__

@tab

X

@tab

X

@tab

@tab

@item

@ref{b75,,tp_basicsize}

@tab

@ref{c4c,,Py_ssize_t}

@tab

@tab

X

@tab

X

@tab

@tab

X

@item

@ref{226d,,tp_itemsize}

@tab

@ref{c4c,,Py_ssize_t}

@tab

@tab

@tab

X

@tab

@tab

X

@item

@ref{4d84,,tp_dealloc}

@tab

@ref{4fa0,,destructor}

@tab

@tab

X

@tab

X

@tab

@tab

X

@item

@ref{5077,,tp_vectorcall_offset}

@tab

@ref{c4c,,Py_ssize_t}

@tab

@tab

@tab

X

@tab

@tab

X

@item

(@ref{4db5,,tp_getattr})

@tab

@ref{4fa1,,getattrfunc}

@tab

__getattribute__,
__getattr__

@tab

@tab

@tab

@tab

G

@item

(@ref{4db6,,tp_setattr})

@tab

@ref{4fb1,,setattrfunc}

@tab

__setattr__,
__delattr__

@tab

@tab

@tab

@tab

G

@item

@ref{10ca,,tp_as_async}

@tab

@ref{50d6,,PyAsyncMethods} *

@tab

@ref{5391,,sub-slots}

@tab

@tab

@tab

@tab

%

@item

@ref{4dac,,tp_repr}

@tab

@ref{4faf,,reprfunc}

@tab

__repr__

@tab

X

@tab

X

@tab

@tab

X

@item

@ref{b79,,tp_as_number}

@tab

@ref{1615,,PyNumberMethods} *

@tab

@ref{5391,,sub-slots}

@tab

@tab

@tab

@tab

%

@item

@ref{5392,,tp_as_sequence}

@tab

@ref{4dbc,,PySequenceMethods} *

@tab

@ref{5391,,sub-slots}

@tab

@tab

@tab

@tab

%

@item

@ref{5393,,tp_as_mapping}

@tab

@ref{4dbd,,PyMappingMethods} *

@tab

@ref{5391,,sub-slots}

@tab

@tab

@tab

@tab

%

@item

@ref{4dbe,,tp_hash}

@tab

@ref{4fa6,,hashfunc}

@tab

__hash__

@tab

X

@tab

@tab

@tab

G

@item

@ref{774,,tp_call}

@tab

@ref{4fb6,,ternaryfunc}

@tab

__call__

@tab

@tab

X

@tab

@tab

X

@item

@ref{4dad,,tp_str}

@tab

@ref{4faf,,reprfunc}

@tab

__str__

@tab

X

@tab

@tab

@tab

X

@item

@ref{19b5,,tp_getattro}

@tab

@ref{4fa2,,getattrofunc}

@tab

__getattribute__,
__getattr__

@tab

X

@tab

X

@tab

@tab

G

@item

@ref{4db0,,tp_setattro}

@tab

@ref{4fb2,,setattrofunc}

@tab

__setattr__,
__delattr__

@tab

X

@tab

X

@tab

@tab

G

@item

@ref{b77,,tp_as_buffer}

@tab

@ref{50dd,,PyBufferProcs} *

@tab

@ref{5391,,sub-slots}

@tab

@tab

@tab

@tab

%

@item

@ref{1b73,,tp_flags}

@tab

unsigned long

@tab

@tab

X

@tab

X

@tab

@tab

?

@item

@ref{4d93,,tp_doc}

@tab

const char *

@tab

__doc__

@tab

X

@tab

X

@tab

@tab

@item

@ref{979,,tp_traverse}

@tab

@ref{4fb7,,traverseproc}

@tab

@tab

@tab

X

@tab

@tab

G

@item

@ref{4daa,,tp_clear}

@tab

@ref{4fa8,,inquiry}

@tab

@tab

@tab

X

@tab

@tab

G

@item

@ref{4db8,,tp_richcompare}

@tab

@ref{4fb0,,richcmpfunc}

@tab

__lt__,
__le__,
__eq__,
__ne__,
__gt__,
__ge__

@tab

X

@tab

@tab

@tab

G

@item

(@ref{b76,,tp_weaklistoffset})

@tab

@ref{c4c,,Py_ssize_t}

@tab

@tab

@tab

X

@tab

@tab

?

@item

@ref{16e3,,tp_iter}

@tab

@ref{4fa4,,getiterfunc}

@tab

__iter__

@tab

@tab

@tab

@tab

X

@item

@ref{16e4,,tp_iternext}

@tab

@ref{4fa9,,iternextfunc}

@tab

__next__

@tab

@tab

@tab

@tab

X

@item

@ref{4d9c,,tp_methods}

@tab

@ref{16cb,,PyMethodDef} []

@tab

@tab

X

@tab

X

@tab

@tab

@item

@ref{4d9a,,tp_members}

@tab

@ref{76a,,PyMemberDef} []

@tab

@tab

@tab

X

@tab

@tab

@item

@ref{4d9f,,tp_getset}

@tab

@ref{dad,,PyGetSetDef} []

@tab

@tab

X

@tab

X

@tab

@tab

@item

@ref{2227,,tp_base}

@tab

@ref{c93,,PyTypeObject} *

@tab

__base__

@tab

@tab

@tab

X

@tab

@item

@ref{19de,,tp_dict}

@tab

@ref{5d7,,PyObject} *

@tab

__dict__

@tab

@tab

@tab

?

@tab

@item

@ref{5394,,tp_descr_get}

@tab

@ref{4f9e,,descrgetfunc}

@tab

__get__

@tab

@tab

@tab

@tab

X

@item

@ref{1bac,,tp_descr_set}

@tab

@ref{4f9f,,descrsetfunc}

@tab

__set__,
__delete__

@tab

@tab

@tab

@tab

X

@item

(@ref{50d8,,tp_dictoffset})

@tab

@ref{c4c,,Py_ssize_t}

@tab

@tab

@tab

X

@tab

@tab

?

@item

@ref{79a,,tp_init}

@tab

@ref{4fa7,,initproc}

@tab

__init__

@tab

X

@tab

X

@tab

@tab

X

@item

@ref{4d98,,tp_alloc}

@tab

@ref{4f9c,,allocfunc}

@tab

@tab

X

@tab

@tab

?

@tab

?

@item

@ref{798,,tp_new}

@tab

@ref{4fab,,newfunc}

@tab

__new__

@tab

X

@tab

X

@tab

?

@tab

?

@item

@ref{4d97,,tp_free}

@tab

@ref{5207,,freefunc}

@tab

@tab

X

@tab

X

@tab

?

@tab

?

@item

@ref{5395,,tp_is_gc}

@tab

@ref{4fa8,,inquiry}

@tab

@tab

@tab

X

@tab

@tab

X

@item

<@ref{5396,,tp_bases}>

@tab

@ref{5d7,,PyObject} *

@tab

__bases__

@tab

@tab

@tab

~

@tab

@item

<@ref{50da,,tp_mro}>

@tab

@ref{5d7,,PyObject} *

@tab

__mro__

@tab

@tab

@tab

~

@tab

@item

[@ref{50db,,tp_cache}]

@tab

@ref{5d7,,PyObject} *

@tab

@tab

@tab

@tab

@tab

@item

[@ref{78b,,tp_subclasses}]

@tab

void *

@tab

__subclasses__

@tab

@tab

@tab

@tab

@item

[@ref{50dc,,tp_weaklist}]

@tab

@ref{5d7,,PyObject} *

@tab

@tab

@tab

@tab

@tab

@item

(@ref{5397,,tp_del})

@tab

@ref{4fa0,,destructor}

@tab

@tab

@tab

@tab

@tab

@item

[@ref{5398,,tp_version_tag}]

@tab

unsigned int

@tab

@tab

@tab

@tab

@tab

@item

@ref{c94,,tp_finalize}

@tab

@ref{4fa0,,destructor}

@tab

__del__

@tab

@tab

@tab

@tab

X

@item

@ref{18e4,,tp_vectorcall}

@tab

@ref{772,,vectorcallfunc}

@tab

@tab

@tab

@tab

@tab

@item

[@ref{5399,,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{539a}@anchor{c-api/typeobj sub-slots}@anchor{5391}
@subsubsection sub-slots



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxx} 
@headitem

Slot

@tab

@ref{5390,,Type}

@tab

special
methods

@item

@ref{539b,,am_await}

@tab

@ref{4fb8,,unaryfunc}

@tab

__await__

@item

@ref{539c,,am_aiter}

@tab

@ref{4fb8,,unaryfunc}

@tab

__aiter__

@item

@ref{539d,,am_anext}

@tab

@ref{4fb8,,unaryfunc}

@tab

__anext__

@item

@ref{539e,,am_send}

@tab

@ref{539f,,sendfunc}

@tab

@item

@tab

@tab

@item

@ref{50cf,,nb_add}

@tab

@ref{4f9d,,binaryfunc}

@tab

__add__
__radd__

@item

@ref{53a0,,nb_inplace_add}

@tab

@ref{4f9d,,binaryfunc}

@tab

__iadd__

@item

@ref{53a1,,nb_subtract}

@tab

@ref{4f9d,,binaryfunc}

@tab

__sub__
__rsub__

@item

@ref{53a2,,nb_inplace_subtract}

@tab

@ref{4f9d,,binaryfunc}

@tab

__isub__

@item

@ref{53a3,,nb_multiply}

@tab

@ref{4f9d,,binaryfunc}

@tab

__mul__
__rmul__

@item

@ref{53a4,,nb_inplace_multiply}

@tab

@ref{4f9d,,binaryfunc}

@tab

__imul__

@item

@ref{53a5,,nb_remainder}

@tab

@ref{4f9d,,binaryfunc}

@tab

__mod__
__rmod__

@item

@ref{53a6,,nb_inplace_remainder}

@tab

@ref{4f9d,,binaryfunc}

@tab

__imod__

@item

@ref{53a7,,nb_divmod}

@tab

@ref{4f9d,,binaryfunc}

@tab

__divmod__
__rdivmod__

@item

@ref{53a8,,nb_power}

@tab

@ref{4fb6,,ternaryfunc}

@tab

__pow__
__rpow__

@item

@ref{53a9,,nb_inplace_power}

@tab

@ref{4fb6,,ternaryfunc}

@tab

__ipow__

@item

@ref{53aa,,nb_negative}

@tab

@ref{4fb8,,unaryfunc}

@tab

__neg__

@item

@ref{53ab,,nb_positive}

@tab

@ref{4fb8,,unaryfunc}

@tab

__pos__

@item

@ref{53ac,,nb_absolute}

@tab

@ref{4fb8,,unaryfunc}

@tab

__abs__

@item

@ref{53ad,,nb_bool}

@tab

@ref{4fa8,,inquiry}

@tab

__bool__

@item

@ref{53ae,,nb_invert}

@tab

@ref{4fb8,,unaryfunc}

@tab

__invert__

@item

@ref{53af,,nb_lshift}

@tab

@ref{4f9d,,binaryfunc}

@tab

__lshift__
__rlshift__

@item

@ref{53b0,,nb_inplace_lshift}

@tab

@ref{4f9d,,binaryfunc}

@tab

__ilshift__

@item

@ref{53b1,,nb_rshift}

@tab

@ref{4f9d,,binaryfunc}

@tab

__rshift__
__rrshift__

@item

@ref{53b2,,nb_inplace_rshift}

@tab

@ref{4f9d,,binaryfunc}

@tab

__irshift__

@item

@ref{53b3,,nb_and}

@tab

@ref{4f9d,,binaryfunc}

@tab

__and__
__rand__

@item

@ref{53b4,,nb_inplace_and}

@tab

@ref{4f9d,,binaryfunc}

@tab

__iand__

@item

@ref{53b5,,nb_xor}

@tab

@ref{4f9d,,binaryfunc}

@tab

__xor__
__rxor__

@item

@ref{53b6,,nb_inplace_xor}

@tab

@ref{4f9d,,binaryfunc}

@tab

__ixor__

@item

@ref{53b7,,nb_or}

@tab

@ref{4f9d,,binaryfunc}

@tab

__or__
__ror__

@item

@ref{53b8,,nb_inplace_or}

@tab

@ref{4f9d,,binaryfunc}

@tab

__ior__

@item

@ref{53b9,,nb_int}

@tab

@ref{4fb8,,unaryfunc}

@tab

__int__

@item

@ref{53ba,,nb_reserved}

@tab

void *

@tab

@item

@ref{53bb,,nb_float}

@tab

@ref{4fb8,,unaryfunc}

@tab

__float__

@item

@ref{53bc,,nb_floor_divide}

@tab

@ref{4f9d,,binaryfunc}

@tab

__floordiv__

@item

@ref{53bd,,nb_inplace_floor_divide}

@tab

@ref{4f9d,,binaryfunc}

@tab

__ifloordiv__

@item

@ref{53be,,nb_true_divide}

@tab

@ref{4f9d,,binaryfunc}

@tab

__truediv__

@item

@ref{53bf,,nb_inplace_true_divide}

@tab

@ref{4f9d,,binaryfunc}

@tab

__itruediv__

@item

@ref{1614,,nb_index}

@tab

@ref{4fb8,,unaryfunc}

@tab

__index__

@item

@ref{53c0,,nb_matrix_multiply}

@tab

@ref{4f9d,,binaryfunc}

@tab

__matmul__
__rmatmul__

@item

@ref{53c1,,nb_inplace_matrix_multiply}

@tab

@ref{4f9d,,binaryfunc}

@tab

__imatmul__

@item

@tab

@tab

@item

@ref{53c2,,mp_length}

@tab

@ref{4faa,,lenfunc}

@tab

__len__

@item

@ref{1be2,,mp_subscript}

@tab

@ref{4f9d,,binaryfunc}

@tab

__getitem__

@item

@ref{53c3,,mp_ass_subscript}

@tab

@ref{4fac,,objobjargproc}

@tab

__setitem__,
__delitem__

@item

@tab

@tab

@item

@ref{50d7,,sq_length}

@tab

@ref{4faa,,lenfunc}

@tab

__len__

@item

@ref{53c4,,sq_concat}

@tab

@ref{4f9d,,binaryfunc}

@tab

__add__

@item

@ref{53c5,,sq_repeat}

@tab

@ref{4fb4,,ssizeargfunc}

@tab

__mul__

@item

@ref{1be1,,sq_item}

@tab

@ref{4fb4,,ssizeargfunc}

@tab

__getitem__

@item

@ref{53c6,,sq_ass_item}

@tab

@ref{4fb5,,ssizeobjargproc}

@tab

__setitem__
__delitem__

@item

@ref{53c7,,sq_contains}

@tab

@ref{4fad,,objobjproc}

@tab

__contains__

@item

@ref{53c8,,sq_inplace_concat}

@tab

@ref{4f9d,,binaryfunc}

@tab

__iadd__

@item

@ref{53c9,,sq_inplace_repeat}

@tab

@ref{4fb4,,ssizeargfunc}

@tab

__imul__

@item

@tab

@tab

@item

@ref{95e,,bf_getbuffer}

@tab

@ref{4fa3,,getbufferproc()}

@tab

__buffer__

@item

@ref{95f,,bf_releasebuffer}

@tab

@ref{4fae,,releasebufferproc()}

@tab

__release_buffer__

@end multitable


@node slot typedefs,,sub-slots,Quick Reference
@anchor{c-api/typeobj slot-typedefs}@anchor{53ca}@anchor{c-api/typeobj slot-typedefs-table}@anchor{5390}
@subsubsection slot typedefs



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

typedef

@tab

Parameter Types

@tab

Return Type

@item

@ref{4f9c,,allocfunc}

@tab


@display
@ref{c93,,PyTypeObject} *@w{ }
@ref{c4c,,Py_ssize_t}@w{ }
@end display



@tab

@ref{5d7,,PyObject} *

@item

@ref{4fa0,,destructor}

@tab

@ref{5d7,,PyObject} *

@tab

void

@item

@ref{5207,,freefunc}

@tab

void *

@tab

void

@item

@ref{4fb7,,traverseproc}

@tab


@display
@ref{5d7,,PyObject} *@w{ }
@ref{4fb9,,visitproc}@w{ }
void *@w{ }
@end display



@tab

int

@item

@ref{4fab,,newfunc}

@tab


@display
@ref{c93,,PyTypeObject} *@w{ }
@ref{5d7,,PyObject} *@w{ }
@ref{5d7,,PyObject} *@w{ }
@end display



@tab

@ref{5d7,,PyObject} *

@item

@ref{4fa7,,initproc}

@tab


@display
@ref{5d7,,PyObject} *@w{ }
@ref{5d7,,PyObject} *@w{ }
@ref{5d7,,PyObject} *@w{ }
@end display



@tab

int

@item

@ref{4faf,,reprfunc}

@tab

@ref{5d7,,PyObject} *

@tab

@ref{5d7,,PyObject} *

@item

@ref{4fa1,,getattrfunc}

@tab


@display
@ref{5d7,,PyObject} *@w{ }
const char *@w{ }
@end display



@tab

@ref{5d7,,PyObject} *

@item

@ref{4fb1,,setattrfunc}

@tab


@display
@ref{5d7,,PyObject} *@w{ }
const char *@w{ }
@ref{5d7,,PyObject} *@w{ }
@end display



@tab

int

@item

@ref{4fa2,,getattrofunc}

@tab


@display
@ref{5d7,,PyObject} *@w{ }
@ref{5d7,,PyObject} *@w{ }
@end display



@tab

@ref{5d7,,PyObject} *

@item

@ref{4fb2,,setattrofunc}

@tab


@display
@ref{5d7,,PyObject} *@w{ }
@ref{5d7,,PyObject} *@w{ }
@ref{5d7,,PyObject} *@w{ }
@end display



@tab

int

@item

@ref{4f9e,,descrgetfunc}

@tab


@display
@ref{5d7,,PyObject} *@w{ }
@ref{5d7,,PyObject} *@w{ }
@ref{5d7,,PyObject} *@w{ }
@end display



@tab

@ref{5d7,,PyObject} *

@item

@ref{4f9f,,descrsetfunc}

@tab


@display
@ref{5d7,,PyObject} *@w{ }
@ref{5d7,,PyObject} *@w{ }
@ref{5d7,,PyObject} *@w{ }
@end display



@tab

int

@item

@ref{4fa6,,hashfunc}

@tab

@ref{5d7,,PyObject} *

@tab

Py_hash_t

@item

@ref{4fb0,,richcmpfunc}

@tab


@display
@ref{5d7,,PyObject} *@w{ }
@ref{5d7,,PyObject} *@w{ }
int@w{ }
@end display



@tab

@ref{5d7,,PyObject} *

@item

@ref{4fa4,,getiterfunc}

@tab

@ref{5d7,,PyObject} *

@tab

@ref{5d7,,PyObject} *

@item

@ref{4fa9,,iternextfunc}

@tab

@ref{5d7,,PyObject} *

@tab

@ref{5d7,,PyObject} *

@item

@ref{4faa,,lenfunc}

@tab

@ref{5d7,,PyObject} *

@tab

@ref{c4c,,Py_ssize_t}

@item

@ref{4fa3,,getbufferproc}

@tab


@display
@ref{5d7,,PyObject} *@w{ }
@ref{954,,Py_buffer} *@w{ }
int@w{ }
@end display



@tab

int

@item

@ref{4fae,,releasebufferproc}

@tab


@display
@ref{5d7,,PyObject} *@w{ }
@ref{954,,Py_buffer} *@w{ }
@end display



@tab

void

@item

@ref{4fa8,,inquiry}

@tab

@ref{5d7,,PyObject} *

@tab

int

@item

@ref{4fb8,,unaryfunc}

@tab


@display
@ref{5d7,,PyObject} *@w{ }
@end display



@tab

@ref{5d7,,PyObject} *

@item

@ref{4f9d,,binaryfunc}

@tab


@display
@ref{5d7,,PyObject} *@w{ }
@ref{5d7,,PyObject} *@w{ }
@end display



@tab

@ref{5d7,,PyObject} *

@item

@ref{4fb6,,ternaryfunc}

@tab


@display
@ref{5d7,,PyObject} *@w{ }
@ref{5d7,,PyObject} *@w{ }
@ref{5d7,,PyObject} *@w{ }
@end display



@tab

@ref{5d7,,PyObject} *

@item

@ref{4fb4,,ssizeargfunc}

@tab


@display
@ref{5d7,,PyObject} *@w{ }
@ref{c4c,,Py_ssize_t}@w{ }
@end display



@tab

@ref{5d7,,PyObject} *

@item

@ref{4fb5,,ssizeobjargproc}

@tab


@display
@ref{5d7,,PyObject} *@w{ }
@ref{c4c,,Py_ssize_t}@w{ }
@ref{5d7,,PyObject} *@w{ }
@end display



@tab

int

@item

@ref{4fad,,objobjproc}

@tab


@display
@ref{5d7,,PyObject} *@w{ }
@ref{5d7,,PyObject} *@w{ }
@end display



@tab

int

@item

@ref{4fac,,objobjargproc}

@tab


@display
@ref{5d7,,PyObject} *@w{ }
@ref{5d7,,PyObject} *@w{ }
@ref{5d7,,PyObject} *@w{ }
@end display



@tab

int

@end multitable


更多細節請見下方的 @ref{53cb,,Slot Type typedefs}。

@node PyTypeObject Definition,PyObject Slots,Quick Reference,型別物件結構
@anchor{c-api/typeobj pytypeobject-definition}@anchor{53cc}
@subsubsection PyTypeObject Definition


The structure definition for @ref{c93,,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,型別物件結構
@anchor{c-api/typeobj pyobject-slots}@anchor{53cd}
@subsubsection PyObject Slots


The type object structure extends the @ref{458f,,PyVarObject} structure. The
@ref{4f8a,,ob_size} field is used for dynamic types (created by @code{type_new()},
usually called from a class statement). Note that @ref{768,,PyType_Type} (the
metatype) initializes @ref{226d,,tp_itemsize}, which means that its instances (i.e.
type objects) `must' have the @ref{4f8a,,ob_size} field.

@ref{a96,,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{97b,,statically allocated type objects}, the type's instances (objects whose @ref{4d95,,ob_type}
points back to the type) do `not' count as references.  But for
@ref{b55,,dynamically allocated type objects}, the instances `do'
count as references.

`Inheritance:'

This field is not inherited by subtypes.
@end quotation

@ref{4d95,,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{97a,,PyType_Ready()} checks if @ref{4d95,,ob_type} is @code{NULL}, and if so,
initializes it to the @ref{4d95,,ob_type} field of the base class.
@ref{97a,,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,型別物件結構
@anchor{c-api/typeobj pyvarobject-slots}@anchor{53ce}
@subsubsection PyVarObject Slots


@ref{4f8a,,PyVarObject.ob_size}

@quotation

For @ref{97b,,statically allocated type objects}, this should be
initialized to zero. For @ref{b55,,dynamically allocated type objects}, this field has a special internal meaning.

This field should be accessed using the @ref{97d,,Py_SIZE()} macro.

`Inheritance:'

This field is not inherited by subtypes.
@end quotation

@node PyTypeObject Slots,靜態型別,PyVarObject Slots,型別物件結構
@anchor{c-api/typeobj pytypeobject-slots}@anchor{53cf}
@subsubsection PyTypeObject Slots


Each slot has a section describing inheritance.  If @ref{97a,,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{4e17,,PyBaseObject_Type}
and @ref{768,,PyType_Type} effectively act as defaults.)

@geindex PyTypeObject.tp_name (C member)
@anchor{c-api/typeobj c PyTypeObject tp_name}@anchor{1ba8}
@deffn {C 成員函數} const char *@ref{c93,,PyTypeObject}.tp_name

Pointer to a NUL-terminated string containing the name of the type. For types
that are accessible as module globals, the string should be the full module
name, followed by a dot, followed by the type name; for built-in types, it
should be just the type name.  If the module is a submodule of a package, the
full package name is part of the full module name.  For example, a type named
@code{T} defined in module @code{M} in subpackage @code{Q} in package @code{P}
should have the @ref{1ba8,,tp_name} initializer @code{"P.Q.M.T"}.

For @ref{b55,,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{97b,,statically allocated type objects},
the `tp_name' field should contain a dot.
Everything before the last dot is made accessible as the @ref{60f,,__module__}
attribute, and everything after the last dot is made accessible as the
@ref{169f,,__name__} attribute.

If no dot is present, the entire @ref{1ba8,,tp_name} field is made accessible as the
@ref{169f,,__name__} attribute, and the @ref{60f,,__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{c93,,PyTypeObject()} (other than potentially
@ref{226d,,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{b75}
@deffn {C 成員函數} @ref{c4c,,Py_ssize_t} @ref{c93,,PyTypeObject}.tp_basicsize
@anchor{c-api/typeobj c PyTypeObject tp_itemsize}@anchor{226d}
@deffnx {C 成員函數} @ref{c4c,,Py_ssize_t} @ref{c93,,PyTypeObject}.tp_itemsize

These fields allow calculating the size in bytes of instances of the type.

There are two kinds of types: types with fixed-length instances have a zero
@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{19f7,,PyUnstable_Object_GC_NewWithExtraData()}.)

For a type with variable-length instances, the instances must have an
@ref{4f8a,,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{b74,,PyObject_NewVar()} will take the value of N as an
argument, and store in the instance's @ref{4f8a,,ob_size} field.
Note that the @ref{4f8a,,ob_size} field may later be used for
other purposes. For example, @ref{19b,,int} instances use the bits of
@ref{4f8a,,ob_size} in an implementation-defined
way; the underlying storage and its size should be accessed using
@ref{3a6,,PyLong_Export()}.

@cartouche
@quotation 備註 
The @ref{4f8a,,ob_size} field should be accessed using
the @ref{97d,,Py_SIZE()} and @ref{97e,,Py_SET_SIZE()} macros.
@end quotation
@end cartouche

Also, the presence of an @ref{4f8a,,ob_size} field in the
instance layout doesn't mean that the instance structure is variable-length.
For example, the @ref{24d,,list} type has fixed-length instances, yet those
instances have a @ref{4f8a,,ob_size} field.
(As with @ref{19b,,int}, avoid reading lists' @code{ob_size} directly.
Call @ref{1611,,PyList_Size()} instead.)

The @code{tp_basicsize} includes size needed for data of the type's
@ref{2227,,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{c75,,object}, this struct must
include @ref{5d7,,PyObject} or @ref{458f,,PyVarObject} (depending on
whether @ref{4f8a,,ob_size} should be included). These are
usually defined by the macro @ref{14de,,PyObject_HEAD} or
@ref{5364,,PyObject_VAR_HEAD}, respectively.

The basic size does not include the GC header size, as that header is not
part of @ref{14de,,PyObject_HEAD}.

For cases where struct used to declare the base type is unknown,
see @ref{763,,PyType_Spec.basicsize} and @ref{76b,,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{14de,,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{97a,,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{226d,,tp_itemsize}, it is generally not safe to set
@ref{226d,,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{4d84}
@deffn {C 成員函數} @ref{4fa0,,destructor} @ref{c93,,PyTypeObject}.tp_dealloc

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{791,,Py_CLEAR()}), free all memory buffers owned by the
instance, and call the type's @ref{4d97,,tp_free} function to
free the object itself.

If you may call functions that may set the error indicator, you must use
@ref{427,,PyErr_GetRaisedException()} and @ref{42a,,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{5e9,,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{c94,,tp_finalize}) subsequently resurrects the
object.

@item 
An object will not be destroyed while it is being automatically finalized
(@ref{c94,,tp_finalize}) or automatically cleared
(@ref{4daa,,tp_clear}).
@end itemize

CPython currently destroys an object immediately from @ref{789,,Py_DECREF()}
when the new reference count is zero, but this may change in a future
version.

It is recommended to call @ref{535a,,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{978,,Py_TPFLAGS_HAVE_GC}
flag is set), the destructor should call @ref{16f9,,PyObject_GC_UnTrack()}
before clearing any member fields.

It is permissible to call @ref{4daa,,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{aa3,,Py_TPFLAGS_HEAPTYPE}), the
deallocator should release the owned reference to its type object (via
@ref{789,,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{5ea,,PyErr_WriteUnraisable()}).

範例：

@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{4d99,,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{5356,,物件生命週期} 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{5077}
@deffn {C 成員函數} @ref{c4c,,Py_ssize_t} @ref{c93,,PyTypeObject}.tp_vectorcall_offset

An optional offset to a per-instance function that implements calling
the object using the @ref{76d,,vectorcall protocol},
a more efficient alternative
of the simpler @ref{774,,tp_call}.

This field is only used if the flag @ref{76f,,Py_TPFLAGS_HAVE_VECTORCALL}
is set. If so, this must be a positive integer containing the offset in the
instance of a @ref{772,,vectorcallfunc} pointer.

The `vectorcallfunc' pointer may be @code{NULL}, in which case the instance behaves
as if @ref{76f,,Py_TPFLAGS_HAVE_VECTORCALL} was not set: calling the instance
falls back to @ref{774,,tp_call}.

Any class that sets @code{Py_TPFLAGS_HAVE_VECTORCALL} must also set
@ref{774,,tp_call} and make sure its behaviour is consistent
with the `vectorcallfunc' function.
This can be done by setting `tp_call' to @ref{771,,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{b55,,mutable heap types} to implement the vectorcall
protocol.
When a user sets @ref{773,,__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{76f,,Py_TPFLAGS_HAVE_VECTORCALL} flag.


`Inheritance:'

This field is always inherited.
However, the @ref{76f,,Py_TPFLAGS_HAVE_VECTORCALL} flag is not
always inherited. If it's not set, then the subclass won't use
@ref{76d,,vectorcall}, except when
@ref{771,,PyVectorcall_Call()} is explicitly called.
@end deffn

@geindex PyTypeObject.tp_getattr (C member)
@anchor{c-api/typeobj c PyTypeObject tp_getattr}@anchor{4db5}
@deffn {C 成員函數} @ref{4fa1,,getattrfunc} @ref{c93,,PyTypeObject}.tp_getattr

An optional pointer to the get-attribute-string function.

此欄位已被棄用。當它被定義時，它應該指向一個與 @ref{19b5,,tp_getattro} 行為相同但使用 C 字串而非 Python 字串物件來提供屬性名稱的函式。

`Inheritance:'

群組：@ref{4db5,,tp_getattr}、@ref{19b5,,tp_getattro}

This field is inherited by subtypes together with @ref{19b5,,tp_getattro}: a subtype
inherits both @ref{4db5,,tp_getattr} and @ref{19b5,,tp_getattro} from its base type when
the subtype's @ref{4db5,,tp_getattr} and @ref{19b5,,tp_getattro} are both @code{NULL}.
@end deffn

@geindex PyTypeObject.tp_setattr (C member)
@anchor{c-api/typeobj c PyTypeObject tp_setattr}@anchor{4db6}
@deffn {C 成員函數} @ref{4fb1,,setattrfunc} @ref{c93,,PyTypeObject}.tp_setattr

An optional pointer to the function for setting and deleting attributes.

此欄位已被棄用。當它被定義時，它應該指向一個與 @ref{4db0,,tp_setattro} 行為相同但使用 C 字串而非 Python 字串物件來提供屬性名稱的函式。

`Inheritance:'

群組：@ref{4db6,,tp_setattr}、@ref{4db0,,tp_setattro}

This field is inherited by subtypes together with @ref{4db0,,tp_setattro}: a subtype
inherits both @ref{4db6,,tp_setattr} and @ref{4db0,,tp_setattro} from its base type when
the subtype's @ref{4db6,,tp_setattr} and @ref{4db0,,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{10ca}
@deffn {C 成員函數} @ref{50d6,,PyAsyncMethods} *@ref{c93,,PyTypeObject}.tp_as_async

Pointer to an additional structure that contains fields relevant only to
objects which implement @ref{4c4,,awaitable} and @ref{4c2,,asynchronous iterator}
protocols at the C-level.  See @ref{53d0,,非同步物件結構} for details.


在 3.5 版被加入: 以前稱為 @code{tp_compare} 和 @code{tp_reserved}。


`Inheritance:'

The @ref{10ca,,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{4dac}
@deffn {C 成員函數} @ref{4faf,,reprfunc} @ref{c93,,PyTypeObject}.tp_repr

@geindex built-in function（內建函式）;repr

An optional pointer to a function that implements the built-in function
@ref{1c1,,repr()}.

函式簽名與 @ref{122a,,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{49e,,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.

`預設：'

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{b79}
@deffn {C 成員函數} @ref{1615,,PyNumberMethods} *@ref{c93,,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{53d1,,Number Object Structures}.

`Inheritance:'

The @ref{b79,,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{5392}
@deffn {C 成員函數} @ref{4dbc,,PySequenceMethods} *@ref{c93,,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{53d2,,序列物件結構}.

`Inheritance:'

The @ref{5392,,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{5393}
@deffn {C 成員函數} @ref{4dbd,,PyMappingMethods} *@ref{c93,,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{53d3,,對映物件結構}.

`Inheritance:'

The @ref{5393,,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{4dbe}
@deffn {C 成員函數} @ref{4fa6,,hashfunc} @ref{c93,,PyTypeObject}.tp_hash

@geindex built-in function（內建函式）;hash（雜湊）

An optional pointer to a function that implements the built-in function
@ref{7fa,,hash()}.

函式簽名與 @ref{434,,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{4db8,,tp_richcompare} is not set),
an attempt to take the hash of the object raises @ref{198,,TypeError}.
This is the same as setting it to @ref{15be,,PyObject_HashNotImplemented()}.

This field can be set explicitly to @ref{15be,,PyObject_HashNotImplemented()} to
block inheritance of the hash method from a parent type. This is interpreted
as the equivalent of @code{__hash__ = None} at the Python level, causing
@code{isinstance(o, collections.Hashable)} to correctly return @code{False}. Note
that the converse is also true - setting @code{__hash__ = None} on a class at
the Python level will result in the @code{tp_hash} slot being set to
@ref{15be,,PyObject_HashNotImplemented()}.

`Inheritance:'

群組：@ref{4dbe,,tp_hash}、@ref{4db8,,tp_richcompare}

This field is inherited by subtypes together with
@ref{4db8,,tp_richcompare}: a subtype inherits both of
@ref{4db8,,tp_richcompare} and @ref{4dbe,,tp_hash}, when the subtype's
@ref{4db8,,tp_richcompare} and @ref{4dbe,,tp_hash} are both @code{NULL}.

`預設：'

@ref{4e17,,PyBaseObject_Type} 會使用 @ref{604,,PyObject_GenericHash()}。
@end deffn

@geindex PyTypeObject.tp_call (C member)
@anchor{c-api/typeobj c PyTypeObject tp_call}@anchor{774}
@deffn {C 成員函數} @ref{4fb6,,ternaryfunc} @ref{c93,,PyTypeObject}.tp_call

An optional pointer to a function that implements calling the object.  This
should be @code{NULL} if the object is not callable.  The signature is the same as
for @ref{635,,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{4dad}
@deffn {C 成員函數} @ref{4faf,,reprfunc} @ref{c93,,PyTypeObject}.tp_str

An optional pointer to a function that implements the built-in operation
@ref{169,,str()}.  (Note that @ref{169,,str} is a type now, and @ref{169,,str()} calls the
constructor for that type.  This constructor calls @ref{122b,,PyObject_Str()} to do
the actual work, and @ref{122b,,PyObject_Str()} will call this handler.)

函式簽名與 @ref{122b,,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{1170,,print()} function.

`Inheritance:'

This field is inherited by subtypes.

`預設：'

When this field is not set, @ref{122a,,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{19b5}
@deffn {C 成員函數} @ref{4fa2,,getattrofunc} @ref{c93,,PyTypeObject}.tp_getattro

An optional pointer to the get-attribute function.

函式簽名與 @ref{5e6,,PyObject_GetAttr()} 相同：

@example
PyObject *tp_getattro(PyObject *self, PyObject *attr);
@end example

It is usually convenient to set this field to @ref{4f10,,PyObject_GenericGetAttr()},
which implements the normal way of looking for object attributes.

`Inheritance:'

群組：@ref{4db5,,tp_getattr}、@ref{19b5,,tp_getattro}

This field is inherited by subtypes together with @ref{4db5,,tp_getattr}: a subtype
inherits both @ref{4db5,,tp_getattr} and @ref{19b5,,tp_getattro} from its base type when
the subtype's @ref{4db5,,tp_getattr} and @ref{19b5,,tp_getattro} are both @code{NULL}.

`預設：'

@ref{4e17,,PyBaseObject_Type} 會使用 @ref{4f10,,PyObject_GenericGetAttr()}。
@end deffn

@geindex PyTypeObject.tp_setattro (C member)
@anchor{c-api/typeobj c PyTypeObject tp_setattro}@anchor{4db0}
@deffn {C 成員函數} @ref{4fb2,,setattrofunc} @ref{c93,,PyTypeObject}.tp_setattro

An optional pointer to the function for setting and deleting attributes.

函式簽名與 @ref{4f19,,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{4f11,,PyObject_GenericSetAttr()}, which implements the normal
way of setting object attributes.

`Inheritance:'

群組：@ref{4db6,,tp_setattr}、@ref{4db0,,tp_setattro}

This field is inherited by subtypes together with @ref{4db6,,tp_setattr}: a subtype
inherits both @ref{4db6,,tp_setattr} and @ref{4db0,,tp_setattro} from its base type when
the subtype's @ref{4db6,,tp_setattr} and @ref{4db0,,tp_setattro} are both @code{NULL}.

`預設：'

@ref{4e17,,PyBaseObject_Type} uses @ref{4f11,,PyObject_GenericSetAttr()}.
@end deffn

@geindex PyTypeObject.tp_as_buffer (C member)
@anchor{c-api/typeobj c PyTypeObject tp_as_buffer}@anchor{b77}
@deffn {C 成員函數} @ref{50dd,,PyBufferProcs} *@ref{c93,,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{5099,,緩衝區物件結構}.

`Inheritance:'

The @ref{b77,,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{1b73}
@deffn {C 成員函數} unsigned long @ref{c93,,PyTypeObject}.tp_flags

This field is a bit mask of various flags.  Some flags indicate variant
semantics for certain situations; others are used to indicate that certain
fields in the type object (or in the extension structures referenced via
@ref{b79,,tp_as_number}, @ref{5392,,tp_as_sequence}, @ref{5393,,tp_as_mapping}, and
@ref{b77,,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{978,,Py_TPFLAGS_HAVE_GC} flag bit is inherited together with
the @ref{979,,tp_traverse} and @ref{4daa,,tp_clear} fields, i.e. if the
@ref{978,,Py_TPFLAGS_HAVE_GC} flag bit is clear in the subtype and the
@ref{979,,tp_traverse} and @ref{4daa,,tp_clear} fields in the subtype exist and have
@code{NULL} values.

@c XXX are most flag bits *really* inherited individually?

`預設：'

@ref{4e17,,PyBaseObject_Type} 使用 @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{1b73,,tp_flags} field.  The macro
@ref{1c08,,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{aa3}
@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{796,,PyType_FromSpec()}.  In this
case, the @ref{4d95,,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{53d4,,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{4d9d}
@deffn {C 巨集} Py_TPFLAGS_BASETYPE

This bit is set when the type can be used as the base type of another type.  If
this bit is clear, the type cannot be subtyped (similar to a "final" class in
Java).

`Inheritance:'

???
@end deffn

@geindex Py_TPFLAGS_READY (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_READY}@anchor{53d5}
@deffn {C 巨集} Py_TPFLAGS_READY

This bit is set when the type object has been fully initialized by
@ref{97a,,PyType_Ready()}.

`Inheritance:'

???
@end deffn

@geindex Py_TPFLAGS_READYING (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_READYING}@anchor{53d6}
@deffn {C 巨集} Py_TPFLAGS_READYING

This bit is set while @ref{97a,,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{978}
@deffn {C 巨集} Py_TPFLAGS_HAVE_GC

This bit is set when the object supports garbage collection.  If this bit
is set, memory for new instances (see @ref{4d98,,tp_alloc})
must be allocated using @ref{c90,,PyObject_GC_New} or
@ref{c58,,PyType_GenericAlloc()} and deallocated (see
@ref{4d97,,tp_free}) using @ref{16f7,,PyObject_GC_Del()}.  More
information in section @ref{53d4,,循環垃圾回收的支援}.

`Inheritance:'

Group: @ref{978,,Py_TPFLAGS_HAVE_GC}, @ref{979,,tp_traverse}, @ref{4daa,,tp_clear}

The @ref{978,,Py_TPFLAGS_HAVE_GC} flag bit is inherited
together with the @ref{979,,tp_traverse} and @ref{4daa,,tp_clear}
fields, i.e.  if the @ref{978,,Py_TPFLAGS_HAVE_GC} flag bit is
clear in the subtype and the @ref{979,,tp_traverse} and
@ref{4daa,,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{4d92}
@deffn {C 巨集} Py_TPFLAGS_DEFAULT

This is a bitmask of all the bits that pertain to the existence of certain
fields in the type object and its extension structures. Currently, it includes
the following bits: @code{Py_TPFLAGS_HAVE_STACKLESS_EXTENSION}.

`Inheritance:'

???
@end deffn

@geindex Py_TPFLAGS_METHOD_DESCRIPTOR (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_METHOD_DESCRIPTOR}@anchor{507f}
@deffn {C 巨集} Py_TPFLAGS_METHOD_DESCRIPTOR

This bit indicates that objects behave like unbound methods.

如果此旗標為 @code{type(meth)} 所設定，則：


@itemize -

@item 
@code{meth.__get__(obj, cls)(*args, **kwds)}（其中 @code{obj} 並非 None）必須等價於 @code{meth(obj, *args, **kwds)}。

@item 
@code{meth.__get__(None, cls)(*args, **kwds)} 必須等價於 @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}.


在 3.8 版被加入.


`Inheritance:'

This flag is never inherited by types without the
@ref{3cd,,Py_TPFLAGS_IMMUTABLETYPE} flag set.  For extension types, it is
inherited whenever @ref{5394,,tp_descr_get} is inherited.
@end deffn

@geindex Py_TPFLAGS_MANAGED_DICT (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_MANAGED_DICT}@anchor{607}
@deffn {C 巨集} Py_TPFLAGS_MANAGED_DICT

This bit indicates that instances of the class have a @ref{776,,__dict__}
attribute, and that the space for the dictionary is managed by the VM.

如果有設定此旗標，則也應該設定 @ref{978,,Py_TPFLAGS_HAVE_GC}。

The type traverse function must call @ref{605,,PyObject_VisitManagedDict()}
and its clear function must call @ref{606,,PyObject_ClearManagedDict()}.


在 3.12 版被加入.


`Inheritance:'

This flag is inherited unless the
@ref{50d8,,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{775}
@deffn {C 巨集} Py_TPFLAGS_MANAGED_WEAKREF

This bit indicates that instances of the class should be weakly
referenceable.


在 3.12 版被加入.


`Inheritance:'

This flag is inherited unless the
@ref{b76,,tp_weaklistoffset} field is set in a superclass.
@end deffn

@geindex Py_TPFLAGS_ITEMS_AT_END (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_ITEMS_AT_END}@anchor{766}
@deffn {C 巨集} Py_TPFLAGS_ITEMS_AT_END

Only usable with variable-size types, i.e. ones with non-zero
@ref{226d,,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.


在 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{53d7}
@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{53d8}
@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{53d9}
@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{53da}
@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{53db}
@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{53dc}
@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{53dd}
@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{53de}
@deffn {C 巨集} Py_TPFLAGS_TYPE_SUBCLASS

These flags are used by functions such as
@ref{50e9,,PyLong_Check()} to quickly determine if a type is a subclass
of a built-in type; such specific checks are faster than a generic
check, like @ref{10a1,,PyObject_IsInstance()}. Custom types that inherit
from built-ins should have their @ref{1b73,,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{425}
@deffn {C 巨集} Py_TPFLAGS_HAVE_FINALIZE

This bit is set when the @ref{c94,,tp_finalize} slot is present in the
type structure.


在 3.4 版被加入.



在 3.8 版之後被棄用: This flag isn't necessary anymore, as the interpreter assumes the
@ref{c94,,tp_finalize} slot is always present in the
type structure.

@end deffn

@geindex Py_TPFLAGS_HAVE_VECTORCALL (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_HAVE_VECTORCALL}@anchor{76f}
@deffn {C 巨集} Py_TPFLAGS_HAVE_VECTORCALL

This bit is set when the class implements
the @ref{76d,,vectorcall protocol}.
See @ref{5077,,tp_vectorcall_offset} for details.

`Inheritance:'

This bit is inherited if @ref{774,,tp_call} is also
inherited.


在 3.9 版被加入.



在 3.12 版的變更: This flag is now removed from a class when the class's
@ref{773,,__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{3cd}
@deffn {C 巨集} Py_TPFLAGS_IMMUTABLETYPE

This bit is set for type objects that are immutable: type attributes cannot be set nor deleted.

@ref{97a,,PyType_Ready()} automatically applies this flag to
@ref{97b,,static types}.

`Inheritance:'

This flag is not inherited.


在 3.10 版被加入.

@end deffn

@geindex Py_TPFLAGS_DISALLOW_INSTANTIATION (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_DISALLOW_INSTANTIATION}@anchor{79b}
@deffn {C 巨集} Py_TPFLAGS_DISALLOW_INSTANTIATION

Disallow creating instances of the type: set
@ref{798,,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{97a,,PyType_Ready()} is called on the type.

The flag is set automatically on @ref{97b,,static types} if
@ref{2227,,tp_base} is NULL or @code{&PyBaseObject_Type} and
@ref{798,,tp_new} is NULL.

`Inheritance:'

This flag is not inherited.
However, subclasses will not be instantiable unless they provide a
non-NULL @ref{798,,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{13b7,,abstract base class}),
do not use this flag.
Instead, make @ref{798,,tp_new} only succeed for
subclasses.
@end quotation
@end cartouche


在 3.10 版被加入.

@end deffn

@geindex Py_TPFLAGS_MAPPING (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_MAPPING}@anchor{1b5a}
@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{a07,,match} block. It is automatically
set when registering or subclassing @ref{abe,,collections.abc.Mapping}, and
unset when registering @ref{13c5,,collections.abc.Sequence}.

@cartouche
@quotation 備註 
@ref{1b5a,,Py_TPFLAGS_MAPPING} and @ref{1b5b,,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{1b5b,,Py_TPFLAGS_SEQUENCE}.


@subsubheading 也參考


@geindex Python Enhancement Proposals; PEP 634
PEP 634@footnote{https://peps.python.org/pep-0634/} -- Structural Pattern Matching: Specification



在 3.10 版被加入.

@end deffn

@geindex Py_TPFLAGS_SEQUENCE (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_SEQUENCE}@anchor{1b5b}
@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{a07,,match} block. It is automatically
set when registering or subclassing @ref{13c5,,collections.abc.Sequence}, and
unset when registering @ref{abe,,collections.abc.Mapping}.

@cartouche
@quotation 備註 
@ref{1b5a,,Py_TPFLAGS_MAPPING} and @ref{1b5b,,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{1b5a,,Py_TPFLAGS_MAPPING}.


@subsubheading 也參考


@geindex Python Enhancement Proposals; PEP 634
PEP 634@footnote{https://peps.python.org/pep-0634/} -- Structural Pattern Matching: Specification



在 3.10 版被加入.

@end deffn

@geindex Py_TPFLAGS_VALID_VERSION_TAG (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_VALID_VERSION_TAG}@anchor{53df}
@deffn {C 巨集} Py_TPFLAGS_VALID_VERSION_TAG

Internal. Do not set or unset this flag.
To indicate that a class has changed call @ref{1aaa,,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
@end deffn

@geindex PyTypeObject.tp_doc (C member)
@anchor{c-api/typeobj c PyTypeObject tp_doc}@anchor{4d93}
@deffn {C 成員函數} const char *@ref{c93,,PyTypeObject}.tp_doc

An optional pointer to a NUL-terminated C string giving the docstring for this
type object.  This is exposed as the @ref{1f5c,,__doc__} attribute on the
type and instances of the type.

`Inheritance:'

此欄位不會被子型別繼承。
@end deffn

@geindex PyTypeObject.tp_traverse (C member)
@anchor{c-api/typeobj c PyTypeObject tp_traverse}@anchor{979}
@deffn {C 成員函數} @ref{4fb7,,traverseproc} @ref{c93,,PyTypeObject}.tp_traverse

An optional pointer to a traversal function for the garbage collector.  This is
only used if the @ref{978,,Py_TPFLAGS_HAVE_GC} flag bit is set.  The signature is:

@example
int tp_traverse(PyObject *self, visitproc visit, void *arg);
@end example

More information about Python's garbage collection scheme can be found
in section @ref{53d4,,循環垃圾回收的支援}.

The @ref{979,,tp_traverse} pointer is used by the garbage collector to detect
reference cycles. A typical implementation of a @ref{979,,tp_traverse} function
simply calls @ref{4da1,,Py_VISIT()} on each of the instance's members that are Python
objects that the instance owns. For example, this is function @code{local_traverse()} from the
@code{_thread} extension module:

@example
static int
local_traverse(PyObject *op, visitproc visit, void *arg)
@{
    localobject *self = (localobject *) op;
    Py_VISIT(self->args);
    Py_VISIT(self->kw);
    Py_VISIT(self->dict);
    return 0;
@}
@end example

Note that @ref{4da1,,Py_VISIT()} is called only on those members that can participate
in reference cycles.  Although there is also a @code{self->key} member, it can only
be @code{NULL} or a Python string and therefore cannot be part of a reference cycle.

On the other hand, even if you know a member can never be part of a cycle, as a
debugging aid you may want to visit it anyway just so the @ref{64,,gc} module's
@ref{9ff,,get_referents()} function will include it.

Heap types (@ref{aa3,,Py_TPFLAGS_HEAPTYPE}) must visit their type with:

@example
Py_VISIT(Py_TYPE(self));
@end example

It is only needed since Python 3.9. To support Python 3.8 and older, this
line must be conditional:

@example
#if PY_VERSION_HEX >= 0x03090000
    Py_VISIT(Py_TYPE(self));
#endif
@end example

If the @ref{607,,Py_TPFLAGS_MANAGED_DICT} bit is set in the
@ref{1b73,,tp_flags} field, the traverse function must call
@ref{605,,PyObject_VisitManagedDict()} like this:

@example
PyObject_VisitManagedDict((PyObject*)self, visit, arg);
@end example

@cartouche
@quotation 警告 
When implementing @ref{979,,tp_traverse}, only the
members that the instance `owns' (by having @ref{5da,,strong references} to them) must be
visited. For instance, if an object supports weak references via the
@ref{50dc,,tp_weaklist} slot, the pointer supporting
the linked list (what `tp_weaklist' points to) must `not' be
visited as the instance does not directly own the weak references to itself
(the weakreference list is there to support the weak reference machinery,
but the instance has no strong reference to the elements inside it, as they
are allowed to be removed even if the instance is still alive).
@end quotation
@end cartouche

Note that @ref{4da1,,Py_VISIT()} requires the `visit' and `arg' parameters to
@code{local_traverse()} to have these specific names; don't name them just
anything.

Instances of @ref{b55,,heap-allocated types} hold a reference to
their type. Their traversal function must therefore either visit
@ref{3c7,,Py_TYPE(self)}, or delegate this responsibility by
calling @code{tp_traverse} of another heap-allocated type (such as a
heap-allocated superclass).
If they do not, the type object may not be garbage-collected.

@cartouche
@quotation 備註 
@ref{979,,tp_traverse} 函式可以從任何執行緒呼叫。
@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.


`Inheritance:'

Group: @ref{978,,Py_TPFLAGS_HAVE_GC}, @ref{979,,tp_traverse}, @ref{4daa,,tp_clear}

This field is inherited by subtypes together with @ref{4daa,,tp_clear} and the
@ref{978,,Py_TPFLAGS_HAVE_GC} flag bit: the flag bit, @ref{979,,tp_traverse}, and
@ref{4daa,,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{4daa}
@deffn {C 成員函數} @ref{4fa8,,inquiry} @ref{c93,,PyTypeObject}.tp_clear

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{535b,,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{4d84,,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{791,,Py_CLEAR()}.)

Any non-trivial cleanup should be performed in
@ref{c94,,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{535b,,cyclic isolate} may remain indefinitely
uncollectable ("leak").  See @ref{13c2,,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 備註 
@ref{4daa,,tp_clear} 函式可以從任何執行緒呼叫。
@end quotation
@end cartouche

@cartouche
@quotation 備註 
An object is not guaranteed to be automatically cleared before its
destructor (@ref{4d84,,tp_dealloc}) is called.
@end quotation
@end cartouche

This function differs from the destructor
(@ref{4d84,,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{4d97,,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{4d97,,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{535b,,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{535b,,cyclic isolate}.

@item 
Python will not automatically clear an object if it has not been
automatically finalized (see @ref{c94,,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{535b,,cyclic isolate}, Python will not
automatically clear it if any member of the cyclic isolate has not yet
been automatically finalized (@ref{c94,,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{535b,,cyclic isolate}, but future versions might
clear objects regularly before their destruction.

Taken together, all @ref{4daa,,tp_clear} functions in the
system must combine to break all reference cycles.  This is subtle, and if
in any doubt supply a @ref{4daa,,tp_clear} function.  For
example, the tuple type does not implement a
@ref{4daa,,tp_clear} function, because it's possible to prove
that no reference cycle can be composed entirely of tuples.  Therefore the
@ref{4daa,,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
@ref{4daa,,tp_clear}.

Implementations of @ref{4daa,,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{791,,Py_CLEAR()} macro should be used, because clearing references is
delicate:  the reference to the contained object must not be released
(via @ref{789,,Py_DECREF()}) until
after the pointer to the contained object is set to @code{NULL}.  This is because
releasing the reference may cause the contained object to become trash,
triggering a chain of reclamation activity that may include invoking arbitrary
Python code (due to finalizers, or weakref callbacks, associated with the
contained object). If it's possible for such code to reference `self' again,
it's important that the pointer to the contained object be @code{NULL} at that time,
so that `self' knows the contained object can no longer be used.  The
@ref{791,,Py_CLEAR()} macro performs the operations in a safe order.

If the @ref{607,,Py_TPFLAGS_MANAGED_DICT} bit is set in the
@ref{1b73,,tp_flags} field, the clear function must call
@ref{606,,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{53d4,,循環垃圾回收的支援}.

`Inheritance:'

Group: @ref{978,,Py_TPFLAGS_HAVE_GC}, @ref{979,,tp_traverse}, @ref{4daa,,tp_clear}

This field is inherited by subtypes together with @ref{979,,tp_traverse} and the
@ref{978,,Py_TPFLAGS_HAVE_GC} flag bit: the flag bit, @ref{979,,tp_traverse}, and
@ref{4daa,,tp_clear} are all inherited from the base type if they are all zero in
the subtype.


@subsubheading 也參考


@ref{5356,,物件生命週期} 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{4db8}
@deffn {C 成員函數} @ref{4fb0,,richcmpfunc} @ref{c93,,PyTypeObject}.tp_richcompare

An optional pointer to the rich comparison function, whose signature is:

@example
PyObject *tp_richcompare(PyObject *self, PyObject *other, int op);
@end example

The first parameter is guaranteed to be an instance of the type
that is defined by @ref{c93,,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{4db8,,tp_richcompare} and for @ref{4db9,,PyObject_RichCompare()}:


@multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxx} 
@headitem

常數

@tab

Comparison

@item

@geindex Py_LT (C macro)
@anchor{c-api/typeobj c Py_LT}@anchor{506a}
@deffn {C 巨集} Py_LT
@end deffn

@tab

@code{<}

@item

@geindex Py_LE (C macro)
@anchor{c-api/typeobj c Py_LE}@anchor{506b}
@deffn {C 巨集} Py_LE
@end deffn

@tab

@code{<=}

@item

@geindex Py_EQ (C macro)
@anchor{c-api/typeobj c Py_EQ}@anchor{506c}
@deffn {C 巨集} Py_EQ
@end deffn

@tab

@code{==}

@item

@geindex Py_NE (C macro)
@anchor{c-api/typeobj c Py_NE}@anchor{506d}
@deffn {C 巨集} Py_NE
@end deffn

@tab

@code{!=}

@item

@geindex Py_GT (C macro)
@anchor{c-api/typeobj c Py_GT}@anchor{506e}
@deffn {C 巨集} Py_GT
@end deffn

@tab

@code{>}

@item

@geindex Py_GE (C macro)
@anchor{c-api/typeobj c Py_GE}@anchor{506f}
@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{da8}
@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{4db9,,PyObject_RichCompare()}.

The returned value is a new @ref{5da,,strong reference}.

On error, sets an exception and returns @code{NULL} from the function.


在 3.7 版被加入.

@end deffn

`Inheritance:'

群組：@ref{4dbe,,tp_hash}、@ref{4db8,,tp_richcompare}

This field is inherited by subtypes together with @ref{4dbe,,tp_hash}:
a subtype inherits @ref{4db8,,tp_richcompare} and @ref{4dbe,,tp_hash} when
the subtype's @ref{4db8,,tp_richcompare} and @ref{4dbe,,tp_hash} are both
@code{NULL}.

`預設：'

@ref{4e17,,PyBaseObject_Type} provides a @ref{4db8,,tp_richcompare}
implementation, which may be inherited.  However, if only
@ref{4dbe,,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{b76}
@deffn {C 成員函數} @ref{c4c,,Py_ssize_t} @ref{c93,,PyTypeObject}.tp_weaklistoffset

While this field is still supported, @ref{775,,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{78f,,PyObject_ClearWeakRefs()} and the @code{PyWeakref_*} functions.  The
instance structure needs to include a field of type @ref{5d7,,PyObject}* which is
initialized to @code{NULL}.

Do not confuse this field with @ref{50dc,,tp_weaklist}; that is the list head for
weak references to the type object itself.

It is an error to set both the @ref{775,,Py_TPFLAGS_MANAGED_WEAKREF} bit and
@ref{b76,,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{b76,,tp_weaklistoffset}, this should not be a problem.

`預設：'

If the @ref{775,,Py_TPFLAGS_MANAGED_WEAKREF} bit is set in the
@ref{1b73,,tp_flags} field, then
@ref{b76,,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{16e3}
@deffn {C 成員函數} @ref{4fa4,,getiterfunc} @ref{c93,,PyTypeObject}.tp_iter

An optional pointer to a function that returns an @ref{4c3,,iterator} for the
object.  Its presence normally signals that the instances of this type are
@ref{1428,,iterable} (although sequences may be iterable without this function).

This function has the same signature as @ref{4f14,,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{16e4}
@deffn {C 成員函數} @ref{4fa9,,iternextfunc} @ref{c93,,PyTypeObject}.tp_iternext

An optional pointer to a function that returns the next item in an
@ref{4c3,,iterator}. The signature is:

@example
PyObject *tp_iternext(PyObject *self);
@end example

When the iterator is exhausted, it must return @code{NULL}; a @ref{df0,,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{16e3,,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{397,,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{4d9c}
@deffn {C 成員函數} struct @ref{16cb,,PyMethodDef} *@ref{c93,,PyTypeObject}.tp_methods

An optional pointer to a static @code{NULL}-terminated array of @ref{16cb,,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{19de,,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{4d9a}
@deffn {C 成員函數} struct @ref{76a,,PyMemberDef} *@ref{c93,,PyTypeObject}.tp_members

An optional pointer to a static @code{NULL}-terminated array of @ref{76a,,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{19de,,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{4d9f}
@deffn {C 成員函數} struct @ref{dad,,PyGetSetDef} *@ref{c93,,PyTypeObject}.tp_getset

An optional pointer to a static @code{NULL}-terminated array of @ref{dad,,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{19de,,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{2227}
@deffn {C 成員函數} @ref{c93,,PyTypeObject} *@ref{c93,,PyTypeObject}.tp_base

An optional pointer to a base type from which type properties are inherited.  At
this level, only single inheritance is supported; multiple inheritance require
dynamically creating a type object by calling the metatype.

@cartouche
@quotation 備註 
@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{4d94,,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{4e17,,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{2227,,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).

`預設：'

This field defaults to @code{&PyBaseObject_Type} (which to Python
programmers is known as the type @ref{c75,,object}).
@end deffn

@geindex PyTypeObject.tp_dict (C member)
@anchor{c-api/typeobj c PyTypeObject tp_dict}@anchor{19de}
@deffn {C 成員函數} @ref{5d7,,PyObject} *@ref{c93,,PyTypeObject}.tp_dict

The type's dictionary is stored here by @ref{97a,,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{97a,,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{228f,,__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{19dd,,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{19dd,,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).

`預設：'

If this field is @code{NULL}, @ref{97a,,PyType_Ready()} will assign a new
dictionary to it.

@cartouche
@quotation 警告 
It is not safe to use @ref{4d81,,PyDict_SetItem()} on or otherwise modify
@ref{19de,,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{5394}
@deffn {C 成員函數} @ref{4f9e,,descrgetfunc} @ref{c93,,PyTypeObject}.tp_descr_get

An optional pointer to a "descriptor get" function.

The function signature is:

@example
PyObject * tp_descr_get(PyObject *self, PyObject *obj, PyObject *type);
@end example

@c XXX explain more?

`Inheritance:'

This field is inherited by subtypes.
@end deffn

@geindex PyTypeObject.tp_descr_set (C member)
@anchor{c-api/typeobj c PyTypeObject tp_descr_set}@anchor{1bac}
@deffn {C 成員函數} @ref{4f9f,,descrsetfunc} @ref{c93,,PyTypeObject}.tp_descr_set

An optional pointer to a function for setting and deleting
a descriptor's value.

The function signature is:

@example
int tp_descr_set(PyObject *self, PyObject *obj, PyObject *value);
@end example

The `value' argument is set to @code{NULL} to delete the value.

@c XXX explain more?

`Inheritance:'

This field is inherited by subtypes.
@end deffn

@geindex PyTypeObject.tp_dictoffset (C member)
@anchor{c-api/typeobj c PyTypeObject tp_dictoffset}@anchor{50d8}
@deffn {C 成員函數} @ref{c4c,,Py_ssize_t} @ref{c93,,PyTypeObject}.tp_dictoffset

While this field is still supported, @ref{607,,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{4f10,,PyObject_GenericGetAttr()}.

Do not confuse this field with @ref{19de,,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{50d8,,tp_dictoffset} should be regarded as write-only.
To get the pointer to the dictionary call @ref{1bef,,PyObject_GenericGetDict()}.
Calling @ref{1bef,,PyObject_GenericGetDict()} may need to allocate memory for the
dictionary, so it is may be more efficient to call @ref{5e6,,PyObject_GetAttr()}
when accessing an attribute on the object.

It is an error to set both the @ref{607,,Py_TPFLAGS_MANAGED_DICT} bit and
@ref{50d8,,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{607,,Py_TPFLAGS_MANAGED_DICT}.

`預設：'

This slot has no default.  For @ref{97b,,static types}, if the
field is @code{NULL} then no @ref{776,,__dict__} gets created for instances.

If the @ref{607,,Py_TPFLAGS_MANAGED_DICT} bit is set in the
@ref{1b73,,tp_flags} field, then
@ref{50d8,,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{79a}
@deffn {C 成員函數} @ref{4fa7,,initproc} @ref{c93,,PyTypeObject}.tp_init

An optional pointer to an instance initialization function.

This function corresponds to the @ref{8b7,,__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{8b7,,__init__()}.

The @ref{79a,,tp_init} function, if not @code{NULL}, is called when an instance is
created normally by calling its type, after the type's @ref{798,,tp_new} function
has returned an instance of the type.  If the @ref{798,,tp_new} function returns an
instance of some other type that is not a subtype of the original type, no
@ref{79a,,tp_init} function is called; if @ref{798,,tp_new} returns an instance of a
subtype of the original type, the subtype's @ref{79a,,tp_init} is called.

Returns @code{0} on success, @code{-1} and sets an exception on error.

`Inheritance:'

This field is inherited by subtypes.

`預設：'

For @ref{97b,,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{4d98}
@deffn {C 成員函數} @ref{4f9c,,allocfunc} @ref{c93,,PyTypeObject}.tp_alloc

An optional pointer to an instance allocation function.

The function signature is:

@example
PyObject *tp_alloc(PyTypeObject *self, Py_ssize_t nitems);
@end example

`Inheritance:'

Static subtypes inherit this slot, which will be
@ref{c58,,PyType_GenericAlloc()} if inherited from @ref{c75,,object}.

@ref{b55,,Heap subtypes} do not inherit this slot.

`預設：'

For heap subtypes, this field is always set to
@ref{c58,,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{798}
@deffn {C 成員函數} @ref{4fab,,newfunc} @ref{c93,,PyTypeObject}.tp_new

An optional pointer to an instance creation function.

The function signature is:

@example
PyObject *tp_new(PyTypeObject *subtype, PyObject *args, PyObject *kwds);
@end example

The `subtype' argument is the type of the object being created; the `args' and
`kwds' arguments represent positional and keyword arguments of the call to the
type.  Note that `subtype' doesn't have to equal the type whose @ref{798,,tp_new}
function is called; it may be a subtype of that type (but not an unrelated
type).

The @ref{798,,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{79a,,tp_init} handler.  A good
rule of thumb is that for immutable types, all initialization should take place
in @ref{798,,tp_new}, while for mutable types, most initialization should be
deferred to @ref{79a,,tp_init}.

Set the @ref{79b,,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{97b,,static types} whose @ref{2227,,tp_base}
is @code{NULL} or @code{&PyBaseObject_Type}.

`預設：'

For @ref{97b,,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{4d97}
@deffn {C 成員函數} @ref{5207,,freefunc} @ref{c93,,PyTypeObject}.tp_free

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{4d98,,tp_alloc}.

`Inheritance:'

Static subtypes inherit this slot, which will be @ref{e5a,,PyObject_Free()} if
inherited from @ref{c75,,object}.  Exception: If the type supports garbage
collection (i.e., the @ref{978,,Py_TPFLAGS_HAVE_GC} flag is set in
@ref{1b73,,tp_flags}) and it would inherit
@ref{e5a,,PyObject_Free()}, then this slot is not inherited but instead defaults
to @ref{16f7,,PyObject_GC_Del()}.

@ref{b55,,Heap subtypes} do not inherit this slot.

`預設：'

For @ref{b55,,heap subtypes}, this slot defaults to a deallocator suitable to match
@ref{c58,,PyType_GenericAlloc()} and the value of the
@ref{978,,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{5395}
@deffn {C 成員函數} @ref{4fa8,,inquiry} @ref{c93,,PyTypeObject}.tp_is_gc

An optional pointer to a function called by the garbage collector.

The garbage collector needs to know whether a particular object is collectible
or not.  Normally, it is sufficient to look at the object's type's
@ref{1b73,,tp_flags} field, and check the @ref{978,,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{768,,PyType_Type}, defines this function to distinguish between statically
and @ref{b55,,dynamically allocated types}.)

`Inheritance:'

This field is inherited by subtypes.

`預設：'

This slot has no default.  If this field is @code{NULL},
@ref{978,,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{5396}
@deffn {C 成員函數} @ref{5d7,,PyObject} *@ref{c93,,PyTypeObject}.tp_bases

Tuple of base types.

This field should be set to @code{NULL} and treated as read-only.
Python will fill it in when the type is @ref{97a,,initialized}.

For dynamically created classes, the @code{Py_tp_bases}
@ref{4f4a,,slot} can be used instead of the `bases' argument
of @ref{797,,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{50da}
@deffn {C 成員函數} @ref{5d7,,PyObject} *@ref{c93,,PyTypeObject}.tp_mro

Tuple containing the expanded set of base types, starting with the type itself
and ending with @ref{c75,,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{97a,,initialized}.

`Inheritance:'

This field is not inherited; it is calculated fresh by
@ref{97a,,PyType_Ready()}.
@end deffn

@geindex PyTypeObject.tp_cache (C member)
@anchor{c-api/typeobj c PyTypeObject tp_cache}@anchor{50db}
@deffn {C 成員函數} @ref{5d7,,PyObject} *@ref{c93,,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{78b}
@deffn {C 成員函數} void *@ref{c93,,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{78c,,__subclasses__()}.


在 3.12 版的變更: For some types, this field does not hold a valid @ref{5d7,,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{50dc}
@deffn {C 成員函數} @ref{5d7,,PyObject} *@ref{c93,,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{5397}
@deffn {C 成員函數} @ref{4fa0,,destructor} @ref{c93,,PyTypeObject}.tp_del

此欄位已被棄用。請改用 @ref{c94,,tp_finalize}。
@end deffn

@geindex PyTypeObject.tp_version_tag (C member)
@anchor{c-api/typeobj c PyTypeObject tp_version_tag}@anchor{5398}
@deffn {C 成員函數} unsigned int @ref{c93,,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{c94}
@deffn {C 成員函數} @ref{4fa0,,destructor} @ref{c93,,PyTypeObject}.tp_finalize

An optional pointer to an instance finalization function.  This is the C
implementation of the @ref{11f8,,__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{4daa,,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{4daa,,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{4d84,,tp_dealloc}) is called.  It is
recommended to call @ref{535a,,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{c94,,tp_finalize} function can be called from any
thread, although the @ref{164,,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{11f8,,__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{978,,Py_TPFLAGS_HAVE_GC} flag is set in
@ref{1b73,,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{535b,,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{535e,,PyObject_CallFinalizer()} or
@ref{535a,,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{535b,,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{978,,Py_TPFLAGS_HAVE_GC} flag is not set.  Such objects can still be
manually finalized by calling @ref{535e,,PyObject_CallFinalizer()} or
@ref{535a,,PyObject_CallFinalizerFromDealloc()}.

@item 
Python will not automatically finalize any two members of a @ref{535b,,cyclic isolate} concurrently.

@item 
Python will not automatically finalize an object after it has
automatically cleared (@ref{4daa,,tp_clear}) the object.

@item 
If an object is a member of a @ref{535b,,cyclic isolate}, Python will not
automatically finalize it after automatically clearing (see
@ref{4daa,,tp_clear}) any other member.

@item 
Python will automatically finalize every member of a @ref{535b,,cyclic isolate} before it automatically clears (see
@ref{4daa,,tp_clear}) any of them.

@item 
If Python is going to automatically clear an object
(@ref{4daa,,tp_clear}), it will automatically finalize the
object first.
@end itemize

Python currently only automatically finalizes objects that are members of a
@ref{535b,,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{535e,,PyObject_CallFinalizer()} or
@ref{535a,,PyObject_CallFinalizerFromDealloc()} instead.

@ref{c94,,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{427,,PyErr_GetRaisedException()} and restore the exception at the end by
calling @ref{42a,,PyErr_SetRaisedException()}.  If an exception is encountered
in the middle of the finalizer, log and clear it with
@ref{5ea,,PyErr_WriteUnraisable()} or @ref{5e9,,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.


在 3.4 版被加入.



在 3.8 版的變更: Before version 3.8 it was necessary to set the
@ref{425,,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{5356,,物件生命週期} for details about how this slot relates to other
slots.

@item 
@ref{535e,,PyObject_CallFinalizer()}

@item 
@ref{535a,,PyObject_CallFinalizerFromDealloc()}
@end itemize

@end deffn

@geindex PyTypeObject.tp_vectorcall (C member)
@anchor{c-api/typeobj c PyTypeObject tp_vectorcall}@anchor{18e4}
@deffn {C 成員函數} @ref{772,,vectorcallfunc} @ref{c93,,PyTypeObject}.tp_vectorcall

A @ref{76d,,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{76d,,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{768,,PyType_Type}->tp_call, which:


@itemize -

@item 
呼叫 @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 
回傳 @code{tp_new} 的結果。
@end itemize

Typically, @code{tp_vectorcall} is overridden to optimize this process
for specific @ref{798,,tp_new} and
@ref{79a,,tp_init}.
When doing this for user-subclassable types, note that both can be
overridden (using @ref{799,,__new__()} and
@ref{8b7,,__init__()}, respectively).
@end quotation
@end cartouche

`Inheritance:'

This field is never inherited.


在 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{5399}
@deffn {C 成員函數} unsigned char @ref{c93,,PyTypeObject}.tp_watched

Internal. Do not use.


在 3.12 版被加入.

@end deffn

@node 靜態型別,堆積型別,PyTypeObject Slots,型別物件結構
@anchor{c-api/typeobj id4}@anchor{53e0}@anchor{c-api/typeobj static-types}@anchor{97b}
@subsubsection 靜態型別


Traditionally, types defined in C code are `static', that is,
a static @ref{c93,,PyTypeObject} structure is defined directly in code
and initialized using @ref{97a,,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{163,,sub-interpreters}, so they should not
include any subinterpreter-specific state.
@end itemize

Also, since @ref{c93,,PyTypeObject} is only part of the @ref{62f,,Limited API} as an opaque struct, any extension modules using static types must be
compiled for a specific Python minor version.

@node 堆積型別,Number Object Structures,靜態型別,型別物件結構
@anchor{c-api/typeobj heap-types}@anchor{b55}@anchor{c-api/typeobj id5}@anchor{53e1}
@subsubsection 堆積型別


An alternative to @ref{97b,,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{aa3,,Py_TPFLAGS_HEAPTYPE}
flag set.

This is done by filling a @ref{19db,,PyType_Spec} structure and calling
@ref{796,,PyType_FromSpec()}, @ref{797,,PyType_FromSpecWithBases()},
@ref{76c,,PyType_FromModuleAndSpec()}, or @ref{76b,,PyType_FromMetaclass()}.

@node Number Object Structures,對映物件結構,堆積型別,型別物件結構
@anchor{c-api/typeobj number-object-structures}@anchor{53e2}@anchor{c-api/typeobj number-structs}@anchor{53d1}
@subsubsection Number Object Structures


@geindex PyNumberMethods (C type)
@anchor{c-api/typeobj c PyNumberMethods}@anchor{1615}
@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{5082,,數字協定} 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{53ba,,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{50cf}
@deffn {C 成員函數} @ref{4f9d,,binaryfunc} @ref{1615,,PyNumberMethods}.nb_add
@end deffn

@geindex PyNumberMethods.nb_subtract (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_subtract}@anchor{53a1}
@deffn {C 成員函數} @ref{4f9d,,binaryfunc} @ref{1615,,PyNumberMethods}.nb_subtract
@end deffn

@geindex PyNumberMethods.nb_multiply (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_multiply}@anchor{53a3}
@deffn {C 成員函數} @ref{4f9d,,binaryfunc} @ref{1615,,PyNumberMethods}.nb_multiply
@end deffn

@geindex PyNumberMethods.nb_remainder (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_remainder}@anchor{53a5}
@deffn {C 成員函數} @ref{4f9d,,binaryfunc} @ref{1615,,PyNumberMethods}.nb_remainder
@end deffn

@geindex PyNumberMethods.nb_divmod (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_divmod}@anchor{53a7}
@deffn {C 成員函數} @ref{4f9d,,binaryfunc} @ref{1615,,PyNumberMethods}.nb_divmod
@end deffn

@geindex PyNumberMethods.nb_power (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_power}@anchor{53a8}
@deffn {C 成員函數} @ref{4fb6,,ternaryfunc} @ref{1615,,PyNumberMethods}.nb_power
@end deffn

@geindex PyNumberMethods.nb_negative (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_negative}@anchor{53aa}
@deffn {C 成員函數} @ref{4fb8,,unaryfunc} @ref{1615,,PyNumberMethods}.nb_negative
@end deffn

@geindex PyNumberMethods.nb_positive (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_positive}@anchor{53ab}
@deffn {C 成員函數} @ref{4fb8,,unaryfunc} @ref{1615,,PyNumberMethods}.nb_positive
@end deffn

@geindex PyNumberMethods.nb_absolute (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_absolute}@anchor{53ac}
@deffn {C 成員函數} @ref{4fb8,,unaryfunc} @ref{1615,,PyNumberMethods}.nb_absolute
@end deffn

@geindex PyNumberMethods.nb_bool (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_bool}@anchor{53ad}
@deffn {C 成員函數} @ref{4fa8,,inquiry} @ref{1615,,PyNumberMethods}.nb_bool
@end deffn

@geindex PyNumberMethods.nb_invert (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_invert}@anchor{53ae}
@deffn {C 成員函數} @ref{4fb8,,unaryfunc} @ref{1615,,PyNumberMethods}.nb_invert
@end deffn

@geindex PyNumberMethods.nb_lshift (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_lshift}@anchor{53af}
@deffn {C 成員函數} @ref{4f9d,,binaryfunc} @ref{1615,,PyNumberMethods}.nb_lshift
@end deffn

@geindex PyNumberMethods.nb_rshift (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_rshift}@anchor{53b1}
@deffn {C 成員函數} @ref{4f9d,,binaryfunc} @ref{1615,,PyNumberMethods}.nb_rshift
@end deffn

@geindex PyNumberMethods.nb_and (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_and}@anchor{53b3}
@deffn {C 成員函數} @ref{4f9d,,binaryfunc} @ref{1615,,PyNumberMethods}.nb_and
@end deffn

@geindex PyNumberMethods.nb_xor (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_xor}@anchor{53b5}
@deffn {C 成員函數} @ref{4f9d,,binaryfunc} @ref{1615,,PyNumberMethods}.nb_xor
@end deffn

@geindex PyNumberMethods.nb_or (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_or}@anchor{53b7}
@deffn {C 成員函數} @ref{4f9d,,binaryfunc} @ref{1615,,PyNumberMethods}.nb_or
@end deffn

@geindex PyNumberMethods.nb_int (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_int}@anchor{53b9}
@deffn {C 成員函數} @ref{4fb8,,unaryfunc} @ref{1615,,PyNumberMethods}.nb_int
@end deffn

@geindex PyNumberMethods.nb_reserved (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_reserved}@anchor{53ba}
@deffn {C 成員函數} void *@ref{1615,,PyNumberMethods}.nb_reserved
@end deffn

@geindex PyNumberMethods.nb_float (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_float}@anchor{53bb}
@deffn {C 成員函數} @ref{4fb8,,unaryfunc} @ref{1615,,PyNumberMethods}.nb_float
@end deffn

@geindex PyNumberMethods.nb_inplace_add (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_inplace_add}@anchor{53a0}
@deffn {C 成員函數} @ref{4f9d,,binaryfunc} @ref{1615,,PyNumberMethods}.nb_inplace_add
@end deffn

@geindex PyNumberMethods.nb_inplace_subtract (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_inplace_subtract}@anchor{53a2}
@deffn {C 成員函數} @ref{4f9d,,binaryfunc} @ref{1615,,PyNumberMethods}.nb_inplace_subtract
@end deffn

@geindex PyNumberMethods.nb_inplace_multiply (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_inplace_multiply}@anchor{53a4}
@deffn {C 成員函數} @ref{4f9d,,binaryfunc} @ref{1615,,PyNumberMethods}.nb_inplace_multiply
@end deffn

@geindex PyNumberMethods.nb_inplace_remainder (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_inplace_remainder}@anchor{53a6}
@deffn {C 成員函數} @ref{4f9d,,binaryfunc} @ref{1615,,PyNumberMethods}.nb_inplace_remainder
@end deffn

@geindex PyNumberMethods.nb_inplace_power (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_inplace_power}@anchor{53a9}
@deffn {C 成員函數} @ref{4fb6,,ternaryfunc} @ref{1615,,PyNumberMethods}.nb_inplace_power
@end deffn

@geindex PyNumberMethods.nb_inplace_lshift (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_inplace_lshift}@anchor{53b0}
@deffn {C 成員函數} @ref{4f9d,,binaryfunc} @ref{1615,,PyNumberMethods}.nb_inplace_lshift
@end deffn

@geindex PyNumberMethods.nb_inplace_rshift (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_inplace_rshift}@anchor{53b2}
@deffn {C 成員函數} @ref{4f9d,,binaryfunc} @ref{1615,,PyNumberMethods}.nb_inplace_rshift
@end deffn

@geindex PyNumberMethods.nb_inplace_and (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_inplace_and}@anchor{53b4}
@deffn {C 成員函數} @ref{4f9d,,binaryfunc} @ref{1615,,PyNumberMethods}.nb_inplace_and
@end deffn

@geindex PyNumberMethods.nb_inplace_xor (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_inplace_xor}@anchor{53b6}
@deffn {C 成員函數} @ref{4f9d,,binaryfunc} @ref{1615,,PyNumberMethods}.nb_inplace_xor
@end deffn

@geindex PyNumberMethods.nb_inplace_or (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_inplace_or}@anchor{53b8}
@deffn {C 成員函數} @ref{4f9d,,binaryfunc} @ref{1615,,PyNumberMethods}.nb_inplace_or
@end deffn

@geindex PyNumberMethods.nb_floor_divide (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_floor_divide}@anchor{53bc}
@deffn {C 成員函數} @ref{4f9d,,binaryfunc} @ref{1615,,PyNumberMethods}.nb_floor_divide
@end deffn

@geindex PyNumberMethods.nb_true_divide (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_true_divide}@anchor{53be}
@deffn {C 成員函數} @ref{4f9d,,binaryfunc} @ref{1615,,PyNumberMethods}.nb_true_divide
@end deffn

@geindex PyNumberMethods.nb_inplace_floor_divide (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_inplace_floor_divide}@anchor{53bd}
@deffn {C 成員函數} @ref{4f9d,,binaryfunc} @ref{1615,,PyNumberMethods}.nb_inplace_floor_divide
@end deffn

@geindex PyNumberMethods.nb_inplace_true_divide (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_inplace_true_divide}@anchor{53bf}
@deffn {C 成員函數} @ref{4f9d,,binaryfunc} @ref{1615,,PyNumberMethods}.nb_inplace_true_divide
@end deffn

@geindex PyNumberMethods.nb_index (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_index}@anchor{1614}
@deffn {C 成員函數} @ref{4fb8,,unaryfunc} @ref{1615,,PyNumberMethods}.nb_index
@end deffn

@geindex PyNumberMethods.nb_matrix_multiply (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_matrix_multiply}@anchor{53c0}
@deffn {C 成員函數} @ref{4f9d,,binaryfunc} @ref{1615,,PyNumberMethods}.nb_matrix_multiply
@end deffn

@geindex PyNumberMethods.nb_inplace_matrix_multiply (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_inplace_matrix_multiply}@anchor{53c1}
@deffn {C 成員函數} @ref{4f9d,,binaryfunc} @ref{1615,,PyNumberMethods}.nb_inplace_matrix_multiply
@end deffn

@node 對映物件結構,序列物件結構,Number Object Structures,型別物件結構
@anchor{c-api/typeobj mapping-object-structures}@anchor{53e3}@anchor{c-api/typeobj mapping-structs}@anchor{53d3}
@subsubsection 對映物件結構


@geindex PyMappingMethods (C type)
@anchor{c-api/typeobj c PyMappingMethods}@anchor{4dbd}
@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{53c2}
@deffn {C 成員函數} @ref{4faa,,lenfunc} @ref{4dbd,,PyMappingMethods}.mp_length

This function is used by @ref{1cfe,,PyMapping_Size()} and
@ref{4f1a,,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{1be2}
@deffn {C 成員函數} @ref{4f9d,,binaryfunc} @ref{4dbd,,PyMappingMethods}.mp_subscript

This function is used by @ref{5e2,,PyObject_GetItem()} and
@ref{4f23,,PySequence_GetSlice()}, and has the same signature as
@code{PyObject_GetItem()}.  This slot must be filled for the
@ref{4ed7,,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{53c3}
@deffn {C 成員函數} @ref{4fac,,objobjargproc} @ref{4dbd,,PyMappingMethods}.mp_ass_subscript

This function is used by @ref{4df9,,PyObject_SetItem()},
@ref{4f0c,,PyObject_DelItem()}, @ref{4f2a,,PySequence_SetSlice()} and
@ref{4f22,,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 序列物件結構,緩衝區物件結構,對映物件結構,型別物件結構
@anchor{c-api/typeobj sequence-object-structures}@anchor{53e4}@anchor{c-api/typeobj sequence-structs}@anchor{53d2}
@subsubsection 序列物件結構


@geindex PySequenceMethods (C type)
@anchor{c-api/typeobj c PySequenceMethods}@anchor{4dbc}
@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{50d7}
@deffn {C 成員函數} @ref{4faa,,lenfunc} @ref{4dbc,,PySequenceMethods}.sq_length

This function is used by @ref{1cfa,,PySequence_Size()} and
@ref{4f1a,,PyObject_Size()}, and has the same signature.  It is also used for
handling negative indices via the @ref{1be1,,sq_item}
and the @ref{53c6,,sq_ass_item} slots.
@end deffn

@geindex PySequenceMethods.sq_concat (C member)
@anchor{c-api/typeobj c PySequenceMethods sq_concat}@anchor{53c4}
@deffn {C 成員函數} @ref{4f9d,,binaryfunc} @ref{4dbc,,PySequenceMethods}.sq_concat

This function is used by @ref{4f20,,PySequence_Concat()} and has the same
signature.  It is also used by the @code{+} operator, after trying the numeric
addition via the @ref{50cf,,nb_add} slot.
@end deffn

@geindex PySequenceMethods.sq_repeat (C member)
@anchor{c-api/typeobj c PySequenceMethods sq_repeat}@anchor{53c5}
@deffn {C 成員函數} @ref{4fb4,,ssizeargfunc} @ref{4dbc,,PySequenceMethods}.sq_repeat

This function is used by @ref{4f29,,PySequence_Repeat()} and has the same
signature.  It is also used by the @code{*} operator, after trying numeric
multiplication via the @ref{53a3,,nb_multiply} slot.
@end deffn

@geindex PySequenceMethods.sq_item (C member)
@anchor{c-api/typeobj c PySequenceMethods sq_item}@anchor{1be1}
@deffn {C 成員函數} @ref{4fb4,,ssizeargfunc} @ref{4dbc,,PySequenceMethods}.sq_item

This function is used by @ref{1cfb,,PySequence_GetItem()} and has the same
signature.  It is also used by @ref{5e2,,PyObject_GetItem()}, after trying
the subscription via the @ref{1be2,,mp_subscript} slot.
This slot must be filled for the @ref{4f1f,,PySequence_Check()}
function to return @code{1}, it can be @code{NULL} otherwise.

Negative indexes are handled as follows: if the @ref{50d7,,sq_length} slot is
filled, it is called and the sequence length is used to compute a positive
index which is passed to  @ref{1be1,,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{53c6}
@deffn {C 成員函數} @ref{4fb5,,ssizeobjargproc} @ref{4dbc,,PySequenceMethods}.sq_ass_item

This function is used by @ref{1cfc,,PySequence_SetItem()} and has the same
signature.  It is also used by @ref{4df9,,PyObject_SetItem()} and
@ref{4f0c,,PyObject_DelItem()}, after trying the item assignment and deletion
via the @ref{53c3,,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{53c7}
@deffn {C 成員函數} @ref{4fad,,objobjproc} @ref{4dbc,,PySequenceMethods}.sq_contains

This function may be used by @ref{3d7,,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{53c8}
@deffn {C 成員函數} @ref{4f9d,,binaryfunc} @ref{4dbc,,PySequenceMethods}.sq_inplace_concat

This function is used by @ref{4f24,,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{4f20,,PySequence_Concat()}.  It is also used by the
augmented assignment @code{+=}, after trying numeric in-place addition
via the @ref{53a0,,nb_inplace_add} slot.
@end deffn

@geindex PySequenceMethods.sq_inplace_repeat (C member)
@anchor{c-api/typeobj c PySequenceMethods sq_inplace_repeat}@anchor{53c9}
@deffn {C 成員函數} @ref{4fb4,,ssizeargfunc} @ref{4dbc,,PySequenceMethods}.sq_inplace_repeat

This function is used by @ref{4f25,,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{4f29,,PySequence_Repeat()}.  It is also used by the
augmented assignment @code{*=}, after trying numeric in-place multiplication
via the @ref{53a4,,nb_inplace_multiply} slot.
@end deffn

@node 緩衝區物件結構,非同步物件結構,序列物件結構,型別物件結構
@anchor{c-api/typeobj buffer-object-structures}@anchor{53e5}@anchor{c-api/typeobj buffer-structs}@anchor{5099}
@subsubsection 緩衝區物件結構


@geindex PyBufferProcs (C type)
@anchor{c-api/typeobj c PyBufferProcs}@anchor{50dd}
@deffn {C 型別} type PyBufferProcs

This structure holds pointers to the functions required by the
@ref{260,,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{95e}
@deffn {C 成員函數} @ref{4fa3,,getbufferproc} @ref{50dd,,PyBufferProcs}.bf_getbuffer

函式的簽名為：

@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{1adb,,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 
回傳 @code{0}。
@end enumerate

If `exporter' is part of a chain or tree of buffer providers, two main
schemes can be used:


@itemize *

@item 
Re-export: Each member of the tree acts as the exporting object and
sets view->obj to a new reference to itself.

@item 
Redirect: The buffer request is redirected to the root object of the
tree. Here, view->obj will be a new reference to the root
object.
@end itemize

The individual fields of `view' are described in section
@ref{509a,,Buffer structure}, the rules how an exporter
must react to specific requests are in section
@ref{4915,,Buffer request types}.

All memory pointed to in the @ref{954,,Py_buffer} structure belongs to
the exporter and must remain valid until there are no consumers left.
@ref{50a4,,format}, @ref{50a6,,shape},
@ref{509e,,strides}, @ref{50a8,,suboffsets}
and @ref{50ab,,internal}
are read-only for the consumer.

@ref{95c,,PyBuffer_FillInfo()} provides an easy way of exposing a simple
bytes buffer while dealing correctly with all request types.

@ref{632,,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{95f}
@deffn {C 成員函數} @ref{4fae,,releasebufferproc} @ref{50dd,,PyBufferProcs}.bf_releasebuffer

函式的簽名為：

@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{95f,,PyBufferProcs.bf_releasebuffer} may be
@code{NULL}. Otherwise, a standard implementation of this function will take
these optional steps:


@enumerate 

@item 
Decrement an internal counter for the number of exports.

@item 
If the counter is @code{0}, free all memory associated with `view'.
@end enumerate

The exporter MUST use the @ref{50ab,,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{633,,PyBuffer_Release()} (this scheme is
useful for breaking reference cycles).

@ref{633,,PyBuffer_Release()} is the interface for the consumer that
wraps this function.
@end deffn

@node 非同步物件結構,Slot Type typedefs,緩衝區物件結構,型別物件結構
@anchor{c-api/typeobj async-object-structures}@anchor{53e6}@anchor{c-api/typeobj async-structs}@anchor{53d0}
@subsubsection 非同步物件結構



在 3.5 版被加入.


@geindex PyAsyncMethods (C type)
@anchor{c-api/typeobj c PyAsyncMethods}@anchor{50d6}
@deffn {C 型別} type PyAsyncMethods

This structure holds pointers to the functions required to implement
@ref{4c4,,awaitable} and @ref{4c2,,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{539b}
@deffn {C 成員函數} @ref{4fb8,,unaryfunc} @ref{50d6,,PyAsyncMethods}.am_await

函式的簽名為：

@example
PyObject *am_await(PyObject *self);
@end example

The returned object must be an @ref{4c3,,iterator}, i.e. @ref{1baa,,PyIter_Check()}
must return @code{1} for it.

This slot may be set to @code{NULL} if an object is not an @ref{4c4,,awaitable}.
@end deffn

@geindex PyAsyncMethods.am_aiter (C member)
@anchor{c-api/typeobj c PyAsyncMethods am_aiter}@anchor{539c}
@deffn {C 成員函數} @ref{4fb8,,unaryfunc} @ref{50d6,,PyAsyncMethods}.am_aiter

函式的簽名為：

@example
PyObject *am_aiter(PyObject *self);
@end example

Must return an @ref{4c2,,asynchronous iterator} object.
See @ref{17fd,,__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{539d}
@deffn {C 成員函數} @ref{4fb8,,unaryfunc} @ref{50d6,,PyAsyncMethods}.am_anext

函式的簽名為：

@example
PyObject *am_anext(PyObject *self);
@end example

Must return an @ref{4c4,,awaitable} object.
See @ref{17fd,,__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{539e}
@deffn {C 成員函數} @ref{539f,,sendfunc} @ref{50d6,,PyAsyncMethods}.am_send

函式的簽名為：

@example
PySendResult am_send(PyObject *self, PyObject *arg, PyObject **result);
@end example

See @ref{a8f,,PyIter_Send()} for details.
This slot may be set to @code{NULL}.


在 3.10 版被加入.

@end deffn

@node Slot Type typedefs,範例<56>,非同步物件結構,型別物件結構
@anchor{c-api/typeobj id6}@anchor{53cb}@anchor{c-api/typeobj slot-type-typedefs}@anchor{53e7}
@subsubsection Slot Type typedefs


@geindex allocfunc (C type)
@anchor{c-api/typeobj c allocfunc}@anchor{4f9c}
@deffn {C 型別} typedef @ref{5d7,,PyObject} *(*allocfunc)(@ref{c93,,PyTypeObject} *cls, @ref{c4c,,Py_ssize_t} nitems)
` 為 @ref{76e,,穩定 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{a96,,ob_refcnt} set to @code{1} and @ref{4d95,,ob_type} set to the type argument.  If
the type's @ref{226d,,tp_itemsize} is non-zero, the object's @ref{4f8a,,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{b75,,tp_basicsize}.

This function should not do any other instance initialization, not even to
allocate additional memory; that should be done by @ref{798,,tp_new}.
@end deffn

@geindex destructor (C type)
@anchor{c-api/typeobj c destructor}@anchor{4fa0}
@deffn {C 型別} typedef void (*destructor)(@ref{5d7,,PyObject}*)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@geindex freefunc (C type)
@anchor{c-api/typeobj c freefunc}@anchor{5207}
@deffn {C 型別} typedef void (*freefunc)(void*)

請見 @ref{4d97,,tp_free}。
@end deffn

@geindex newfunc (C type)
@anchor{c-api/typeobj c newfunc}@anchor{4fab}
@deffn {C 型別} typedef @ref{5d7,,PyObject} *(*newfunc)(@ref{c93,,PyTypeObject}*, @ref{5d7,,PyObject}*, @ref{5d7,,PyObject}*)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
請見 @ref{798,,tp_new}。
@end deffn

@geindex initproc (C type)
@anchor{c-api/typeobj c initproc}@anchor{4fa7}
@deffn {C 型別} typedef int (*initproc)(@ref{5d7,,PyObject}*, @ref{5d7,,PyObject}*, @ref{5d7,,PyObject}*)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
請見 @ref{79a,,tp_init}。
@end deffn

@geindex reprfunc (C type)
@anchor{c-api/typeobj c reprfunc}@anchor{4faf}
@deffn {C 型別} typedef @ref{5d7,,PyObject} *(*reprfunc)(@ref{5d7,,PyObject}*)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
請見 @ref{4dac,,tp_repr}。
@end deffn

@geindex getattrfunc (C type)
@anchor{c-api/typeobj c getattrfunc}@anchor{4fa1}
@deffn {C 型別} typedef @ref{5d7,,PyObject} *(*getattrfunc)(@ref{5d7,,PyObject} *self, char *attr)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return the value of the named attribute for the object.
@end deffn

@geindex setattrfunc (C type)
@anchor{c-api/typeobj c setattrfunc}@anchor{4fb1}
@deffn {C 型別} typedef int (*setattrfunc)(@ref{5d7,,PyObject} *self, char *attr, @ref{5d7,,PyObject} *value)
` 為 @ref{76e,,穩定 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{4fa2}
@deffn {C 型別} typedef @ref{5d7,,PyObject} *(*getattrofunc)(@ref{5d7,,PyObject} *self, @ref{5d7,,PyObject} *attr)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Return the value of the named attribute for the object.

請見 @ref{19b5,,tp_getattro}。
@end deffn

@geindex setattrofunc (C type)
@anchor{c-api/typeobj c setattrofunc}@anchor{4fb2}
@deffn {C 型別} typedef int (*setattrofunc)(@ref{5d7,,PyObject} *self, @ref{5d7,,PyObject} *attr, @ref{5d7,,PyObject} *value)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Set the value of the named attribute for the object.
The value argument is set to @code{NULL} to delete the attribute.

請見 @ref{4db0,,tp_setattro}。
@end deffn

@geindex descrgetfunc (C type)
@anchor{c-api/typeobj c descrgetfunc}@anchor{4f9e}
@deffn {C 型別} typedef @ref{5d7,,PyObject} *(*descrgetfunc)(@ref{5d7,,PyObject}*, @ref{5d7,,PyObject}*, @ref{5d7,,PyObject}*)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
請見 @ref{5394,,tp_descr_get}。
@end deffn

@geindex descrsetfunc (C type)
@anchor{c-api/typeobj c descrsetfunc}@anchor{4f9f}
@deffn {C 型別} typedef int (*descrsetfunc)(@ref{5d7,,PyObject}*, @ref{5d7,,PyObject}*, @ref{5d7,,PyObject}*)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
請見 @ref{1bac,,tp_descr_set}。
@end deffn

@geindex hashfunc (C type)
@anchor{c-api/typeobj c hashfunc}@anchor{4fa6}
@deffn {C 型別} typedef @ref{1464,,Py_hash_t} (*hashfunc)(@ref{5d7,,PyObject}*)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
請見 @ref{4dbe,,tp_hash}。
@end deffn

@geindex richcmpfunc (C type)
@anchor{c-api/typeobj c richcmpfunc}@anchor{4fb0}
@deffn {C 型別} typedef @ref{5d7,,PyObject} *(*richcmpfunc)(@ref{5d7,,PyObject}*, @ref{5d7,,PyObject}*, int)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
請見 @ref{4db8,,tp_richcompare}。
@end deffn

@geindex getiterfunc (C type)
@anchor{c-api/typeobj c getiterfunc}@anchor{4fa4}
@deffn {C 型別} typedef @ref{5d7,,PyObject} *(*getiterfunc)(@ref{5d7,,PyObject}*)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
請見 @ref{16e3,,tp_iter}。
@end deffn

@geindex iternextfunc (C type)
@anchor{c-api/typeobj c iternextfunc}@anchor{4fa9}
@deffn {C 型別} typedef @ref{5d7,,PyObject} *(*iternextfunc)(@ref{5d7,,PyObject}*)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
請見 @ref{16e4,,tp_iternext}。
@end deffn

@geindex lenfunc (C type)
@anchor{c-api/typeobj c lenfunc}@anchor{4faa}
@deffn {C 型別} typedef @ref{c4c,,Py_ssize_t} (*lenfunc)(@ref{5d7,,PyObject}*)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@geindex getbufferproc (C type)
@anchor{c-api/typeobj c getbufferproc}@anchor{4fa3}
@deffn {C 型別} typedef int (*getbufferproc)(@ref{5d7,,PyObject}*, @ref{954,,Py_buffer}*, int)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.12 版本開始.'
@end deffn

@geindex releasebufferproc (C type)
@anchor{c-api/typeobj c releasebufferproc}@anchor{4fae}
@deffn {C 型別} typedef void (*releasebufferproc)(@ref{5d7,,PyObject}*, @ref{954,,Py_buffer}*)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.12 版本開始.'
@end deffn

@geindex unaryfunc (C type)
@anchor{c-api/typeobj c unaryfunc}@anchor{4fb8}
@deffn {C 型別} typedef @ref{5d7,,PyObject} *(*unaryfunc)(@ref{5d7,,PyObject}*)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@geindex binaryfunc (C type)
@anchor{c-api/typeobj c binaryfunc}@anchor{4f9d}
@deffn {C 型別} typedef @ref{5d7,,PyObject} *(*binaryfunc)(@ref{5d7,,PyObject}*, @ref{5d7,,PyObject}*)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@geindex sendfunc (C type)
@anchor{c-api/typeobj c sendfunc}@anchor{539f}
@deffn {C 型別} typedef @ref{5095,,PySendResult} (*sendfunc)(@ref{5d7,,PyObject}*, @ref{5d7,,PyObject}*, @ref{5d7,,PyObject}**)

請見 @ref{539e,,am_send}。
@end deffn

@geindex ternaryfunc (C type)
@anchor{c-api/typeobj c ternaryfunc}@anchor{4fb6}
@deffn {C 型別} typedef @ref{5d7,,PyObject} *(*ternaryfunc)(@ref{5d7,,PyObject}*, @ref{5d7,,PyObject}*, @ref{5d7,,PyObject}*)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@geindex ssizeargfunc (C type)
@anchor{c-api/typeobj c ssizeargfunc}@anchor{4fb4}
@deffn {C 型別} typedef @ref{5d7,,PyObject} *(*ssizeargfunc)(@ref{5d7,,PyObject}*, @ref{c4c,,Py_ssize_t})
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@geindex ssizeobjargproc (C type)
@anchor{c-api/typeobj c ssizeobjargproc}@anchor{4fb5}
@deffn {C 型別} typedef int (*ssizeobjargproc)(@ref{5d7,,PyObject}*, @ref{c4c,,Py_ssize_t}, @ref{5d7,,PyObject}*)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@geindex objobjproc (C type)
@anchor{c-api/typeobj c objobjproc}@anchor{4fad}
@deffn {C 型別} typedef int (*objobjproc)(@ref{5d7,,PyObject}*, @ref{5d7,,PyObject}*)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@geindex objobjargproc (C type)
@anchor{c-api/typeobj c objobjargproc}@anchor{4fac}
@deffn {C 型別} typedef int (*objobjargproc)(@ref{5d7,,PyObject}*, @ref{5d7,,PyObject}*, @ref{5d7,,PyObject}*)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
@end deffn

@node 範例<56>,,Slot Type typedefs,型別物件結構
@anchor{c-api/typeobj examples}@anchor{53e8}@anchor{c-api/typeobj typedef-examples}@anchor{538c}
@subsubsection 範例


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{4d8d,,擴充型別定義教學} and @ref{4da6,,Defining Extension Types; Assorted Topics}.

A basic @ref{97b,,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{79b,,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{97b,,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{97b,,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 循環垃圾回收的支援,,型別物件結構,物件實作支援
@anchor{c-api/gcsupport doc}@anchor{53e9}@anchor{c-api/gcsupport supporting-cycle-detection}@anchor{53d4}@anchor{c-api/gcsupport supporting-cyclic-garbage-collection}@anchor{53ea}@anchor{c-api/gcsupport translation-repo}@anchor{53eb}
@subsection 循環垃圾回收的支援


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{1b73,,tp_flags} field of the type object must
include the @ref{978,,Py_TPFLAGS_HAVE_GC} and provide an implementation of the
@ref{979,,tp_traverse} handler.  If instances of the type are mutable, a
@ref{4daa,,tp_clear} implementation must also be provided.


@table @asis

@item @ref{978,,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{c90,,PyObject_GC_New}
or @ref{c91,,PyObject_GC_NewVar}.

@item 
Once all the fields which may contain references to other containers are
initialized, it must call @ref{16f8,,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{16f9,,PyObject_GC_UnTrack()} must be called.

@item 
The object's memory must be deallocated using @ref{16f7,,PyObject_GC_Del()}.

@cartouche
@quotation 警告 
If a type adds the Py_TPFLAGS_HAVE_GC, then it `must' implement at least
a @ref{979,,tp_traverse} handler or explicitly use one
from its subclass or subclasses.

When calling @ref{97a,,PyType_Ready()} or some of the APIs that indirectly
call it like @ref{797,,PyType_FromSpecWithBases()} or
@ref{796,,PyType_FromSpec()} the interpreter will automatically populate the
@ref{1b73,,tp_flags}, @ref{979,,tp_traverse}
and @ref{4daa,,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{978,,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{c90}
@deffn {C 巨集} PyObject_GC_New (TYPE, typeobj)

Analogous to @ref{b73,,PyObject_New} but for container objects with the
@ref{978,,Py_TPFLAGS_HAVE_GC} flag set.

Do not call this directly to allocate memory for an object; call the type's
@ref{4d98,,tp_alloc} slot instead.

When populating a type's @ref{4d98,,tp_alloc} slot,
@ref{c58,,PyType_GenericAlloc()} is preferred over a custom function that
simply calls this macro.

Memory allocated by this macro must be freed with
@ref{16f7,,PyObject_GC_Del()} (usually called via the object's
@ref{4d97,,tp_free} slot).


@subsubheading 也參考



@itemize *

@item 
@ref{16f7,,PyObject_GC_Del()}

@item 
@ref{b73,,PyObject_New}

@item 
@ref{c58,,PyType_GenericAlloc()}

@item 
@ref{4d98,,tp_alloc}
@end itemize

@end deffn

@geindex PyObject_GC_NewVar (C macro)
@anchor{c-api/gcsupport c PyObject_GC_NewVar}@anchor{c91}
@deffn {C 巨集} PyObject_GC_NewVar (TYPE, typeobj, size)

Analogous to @ref{b74,,PyObject_NewVar} but for container objects with the
@ref{978,,Py_TPFLAGS_HAVE_GC} flag set.

Do not call this directly to allocate memory for an object; call the type's
@ref{4d98,,tp_alloc} slot instead.

When populating a type's @ref{4d98,,tp_alloc} slot,
@ref{c58,,PyType_GenericAlloc()} is preferred over a custom function that
simply calls this macro.

Memory allocated by this macro must be freed with
@ref{16f7,,PyObject_GC_Del()} (usually called via the object's
@ref{4d97,,tp_free} slot).


@subsubheading 也參考



@itemize *

@item 
@ref{16f7,,PyObject_GC_Del()}

@item 
@ref{b74,,PyObject_NewVar}

@item 
@ref{c58,,PyType_GenericAlloc()}

@item 
@ref{4d98,,tp_alloc}
@end itemize

@end deffn

@geindex PyUnstable_Object_GC_NewWithExtraData (C function)
@anchor{c-api/gcsupport c PyUnstable_Object_GC_NewWithExtraData}@anchor{19f7}
@deffn {C 函式} @ref{5d7,,PyObject} *PyUnstable_Object_GC_NewWithExtraData (PyTypeObject *type, size_t extra_size)

@cartouche
@quotation 這是 不穩定 API，它可能在小版本發布中沒有任何警告地被變更。 `這是 @ref{762,,不穩定 API}，它可能在小版本發布中沒有任何警告地被變更。'
@end quotation
@end cartouche

Analogous to @ref{c90,,PyObject_GC_New} but allocates `extra_size'
bytes at the end of the object (at offset
@ref{b75,,tp_basicsize}).
The allocated memory is initialized to zeros,
except for the @ref{5d7,,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{16f7,,PyObject_GC_Del()} (usually called via the object's
@ref{4d97,,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{458f,,PyVarObject} and @ref{226d,,tp_itemsize}
instead.
@end quotation
@end cartouche


在 3.12 版被加入.

@end deffn

@geindex PyObject_GC_Resize (C macro)
@anchor{c-api/gcsupport c PyObject_GC_Resize}@anchor{19fc}
@deffn {C 巨集} PyObject_GC_Resize (TYPE, op, newsize)

Resize an object allocated by @ref{b74,,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{458f,,PyVarObject}*
and must not be tracked by the collector yet.
`newsize' must be of type @ref{c4c,,Py_ssize_t}.
@end deffn

@geindex PyObject_GC_Track (C function)
@anchor{c-api/gcsupport c PyObject_GC_Track}@anchor{16f8}
@deffn {C 函式} void PyObject_GC_Track (PyObject *op)
` 為 @ref{76e,,穩定 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{979,,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{b72}
@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{b64}
@deffn {C 函式} int PyObject_GC_IsTracked (PyObject *op)
` 為 @ref{76e,,穩定 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{150e,,gc.is_tracked()}.


在 3.9 版被加入.

@end deffn

@geindex PyObject_GC_IsFinalized (C function)
@anchor{c-api/gcsupport c PyObject_GC_IsFinalized}@anchor{b65}
@deffn {C 函式} int PyObject_GC_IsFinalized (PyObject *op)
` 為 @ref{76e,,穩定 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{af0,,gc.is_finalized()}.


在 3.9 版被加入.

@end deffn

@geindex PyObject_GC_Del (C function)
@anchor{c-api/gcsupport c PyObject_GC_Del}@anchor{16f7}
@deffn {C 函式} void PyObject_GC_Del (void *op)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Releases memory allocated to an object using @ref{c90,,PyObject_GC_New} or
@ref{c91,,PyObject_GC_NewVar}.

Do not call this directly to free an object's memory; call the type's
@ref{4d97,,tp_free} slot instead.

Do not use this for memory allocated by @ref{b73,,PyObject_New},
@ref{b74,,PyObject_NewVar}, or related allocation functions; use
@ref{e5a,,PyObject_Free()} instead.


@subsubheading 也參考



@itemize *

@item 
@ref{e5a,,PyObject_Free()} is the non-GC equivalent of this function.

@item 
@ref{c90,,PyObject_GC_New}

@item 
@ref{c91,,PyObject_GC_NewVar}

@item 
@ref{c58,,PyType_GenericAlloc()}

@item 
@ref{4d97,,tp_free}
@end itemize

@end deffn

@geindex PyObject_GC_UnTrack (C function)
@anchor{c-api/gcsupport c PyObject_GC_UnTrack}@anchor{16f9}
@deffn {C 函式} void PyObject_GC_UnTrack (void *op)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Remove the object `op' from the set of container objects tracked by the
collector.  Note that @ref{16f8,,PyObject_GC_Track()} can be called again on
this object to add it back to the set of tracked objects.  The deallocator
(@ref{4d84,,tp_dealloc} handler) should call this for the object before any of
the fields used by the @ref{979,,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{979,,tp_traverse} handler accepts a function parameter of this type:

@geindex visitproc (C type)
@anchor{c-api/gcsupport c visitproc}@anchor{4fb9}
@deffn {C 型別} typedef int (*visitproc)(@ref{5d7,,PyObject} *object, void *arg)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Type of the visitor function passed to the @ref{979,,tp_traverse} handler.
The function should be called with an object to traverse as `object' and
the third parameter to the @ref{979,,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{979,,tp_traverse} handler must have the following type:

@geindex traverseproc (C type)
@anchor{c-api/gcsupport c traverseproc}@anchor{4fb7}
@deffn {C 型別} typedef int (*traverseproc)(@ref{5d7,,PyObject} *self, @ref{4fb9,,visitproc} visit, void *arg)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Traversal function for a container object.  Implementations must call the
`visit' function for each object directly contained by `self', with the
parameters to `visit' being the contained object and the `arg' value passed
to the handler.  The `visit' function must not be called with a @code{NULL}
object argument.  If `visit' returns a non-zero value that value should be
returned immediately.
@end deffn

To simplify writing @ref{979,,tp_traverse} handlers, a @ref{4da1,,Py_VISIT()} macro is
provided.  In order to use this macro, the @ref{979,,tp_traverse} implementation
must name its arguments exactly `visit' and `arg':

@geindex Py_VISIT (C macro)
@anchor{c-api/gcsupport c Py_VISIT}@anchor{4da1}
@deffn {C 巨集} Py_VISIT (o)

If the @ref{5d7,,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.
Using this macro, @ref{979,,tp_traverse} handlers
look like:

@example
static int
my_traverse(Noddy *self, visitproc visit, void *arg)
@{
    Py_VISIT(self->foo);
    Py_VISIT(self->bar);
    return 0;
@}
@end example
@end deffn

The @ref{4daa,,tp_clear} handler must be of the @ref{4fa8,,inquiry} type, or @code{NULL}
if the object is immutable.

@geindex inquiry (C type)
@anchor{c-api/gcsupport c inquiry}@anchor{4fa8}
@deffn {C 型別} typedef int (*inquiry)(@ref{5d7,,PyObject} *self)
` 為 @ref{76e,,穩定 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{789,,Py_DECREF()} on a reference).  The
collector will call this method if it detects that this object is involved
in a reference cycle.
@end deffn

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

@end menu

@node Controlling the Garbage Collector State,Querying Garbage Collector State,,循環垃圾回收的支援
@anchor{c-api/gcsupport controlling-the-garbage-collector-state}@anchor{53ec}
@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{b7c}
@deffn {C 函式} @ref{c4c,,Py_ssize_t} PyGC_Collect (void)
` 為 @ref{76e,,穩定 ABI 的一部分}.'
Perform a full garbage collection, if the garbage collector is enabled.
(Note that @ref{1b3,,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{502,,sys.unraisablehook}.
This function does not raise exceptions.
@end deffn

@geindex PyGC_Enable (C function)
@anchor{c-api/gcsupport c PyGC_Enable}@anchor{a9b}
@deffn {C 函式} int PyGC_Enable (void)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.10 版本開始.'
Enable the garbage collector: similar to @ref{48c5,,gc.enable()}.
Returns the previous state, 0 for disabled and 1 for enabled.


在 3.10 版被加入.

@end deffn

@geindex PyGC_Disable (C function)
@anchor{c-api/gcsupport c PyGC_Disable}@anchor{a9c}
@deffn {C 函式} int PyGC_Disable (void)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.10 版本開始.'
Disable the garbage collector: similar to @ref{48c6,,gc.disable()}.
Returns the previous state, 0 for disabled and 1 for enabled.


在 3.10 版被加入.

@end deffn

@geindex PyGC_IsEnabled (C function)
@anchor{c-api/gcsupport c PyGC_IsEnabled}@anchor{a9d}
@deffn {C 函式} int PyGC_IsEnabled (void)
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.10 版本開始.'
Query the state of the garbage collector: similar to @ref{48c7,,gc.isenabled()}.
Returns the current state, 0 for disabled and 1 for enabled.


在 3.10 版被加入.

@end deffn

@node Querying Garbage Collector State,,Controlling the Garbage Collector State,循環垃圾回收的支援
@anchor{c-api/gcsupport querying-garbage-collector-state}@anchor{53ed}
@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{53ee}
@deffn {C 函式} void PyUnstable_GC_VisitObjects (gcvisitobjects_t callback, void *arg)

@cartouche
@quotation 這是 不穩定 API，它可能在小版本發布中沒有任何警告地被變更。 `這是 @ref{762,,不穩定 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


在 3.12 版被加入.

@end deffn

@geindex gcvisitobjects_t (C type)
@anchor{c-api/gcsupport c gcvisitobjects_t}@anchor{53ef}
@deffn {C 型別} typedef int (*gcvisitobjects_t)(@ref{5d7,,PyObject} *object, void *arg)

Type of the visitor function to be passed to @ref{53ee,,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.


在 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 和 ABI 版本管理,監控 C API,物件實作支援,Python/C API 參考手冊
@anchor{c-api/apiabiversion doc}@anchor{53f0}@anchor{c-api/apiabiversion api-and-abi-versioning}@anchor{53f1}@anchor{c-api/apiabiversion apiabiversion}@anchor{47da}@anchor{c-api/apiabiversion translation-repo}@anchor{53f2}
@section API 和 ABI 版本管理


@menu
* Build-time version constants:: 
* Run-time version:: 
* Bit-packing macros:: 

@end menu

@node Build-time version constants,Run-time version,,API 和 ABI 版本管理
@anchor{c-api/apiabiversion build-time-version-constants}@anchor{53f3}
@subsection Build-time version constants


CPython 透過以下巨集 (macro) 公開其版本號。請注意，對應到的是`建置 (built)' 所用到的版本。關於`run time' 所使用的版本，請見 @ref{37f,,Py_Version}。

關於跨版本 API 和 ABI 穩定性的討論，請見 @ref{76e,,C API 穩定性}。

@geindex PY_MAJOR_VERSION (C macro)
@anchor{c-api/apiabiversion c PY_MAJOR_VERSION}@anchor{53f4}
@deffn {C 巨集} PY_MAJOR_VERSION

在 @code{3.4.1a2} 中的 @code{3}。
@end deffn

@geindex PY_MINOR_VERSION (C macro)
@anchor{c-api/apiabiversion c PY_MINOR_VERSION}@anchor{53f5}
@deffn {C 巨集} PY_MINOR_VERSION

在 @code{3.4.1a2} 中的 @code{4}。
@end deffn

@geindex PY_MICRO_VERSION (C macro)
@anchor{c-api/apiabiversion c PY_MICRO_VERSION}@anchor{53f6}
@deffn {C 巨集} PY_MICRO_VERSION

在 @code{3.4.1a2} 中的 @code{1}。
@end deffn

@geindex PY_RELEASE_LEVEL (C macro)
@anchor{c-api/apiabiversion c PY_RELEASE_LEVEL}@anchor{53f7}
@deffn {C 巨集} PY_RELEASE_LEVEL

在 @code{3.4.1a2} 中的 @code{a}。@code{0xA} 代表 alpha 版本、@code{0xB} 代表 beta 版本、@code{0xC} 為發布候選版本、@code{0xF} 則為最終版。
@end deffn

@geindex PY_RELEASE_SERIAL (C macro)
@anchor{c-api/apiabiversion c PY_RELEASE_SERIAL}@anchor{53f8}
@deffn {C 巨集} PY_RELEASE_SERIAL

在 @code{3.4.1a2} 中的 @code{2}。零則為最終發布版本。
@end deffn

@geindex PY_VERSION_HEX (C macro)
@anchor{c-api/apiabiversion c PY_VERSION_HEX}@anchor{380}
@deffn {C 巨集} PY_VERSION_HEX

被編碼為單一整數的 Python 版本號。詳見 @ref{37e,,Py_PACK_FULL_VERSION()} 以了解編碼詳細資訊。

使用它進行數值比較，例如 @code{#if PY_VERSION_HEX >= ...}。
@end deffn

@node Run-time version,Bit-packing macros,Build-time version constants,API 和 ABI 版本管理
@anchor{c-api/apiabiversion run-time-version}@anchor{53f9}
@subsection Run-time version


@geindex Py_Version (C var)
@anchor{c-api/apiabiversion c Py_Version}@anchor{37f}
@deffn {C 變數} const unsigned long Py_Version
` 為 @ref{76e,,穩定 ABI 的一部分} 自 3.11 版本開始.'
編碼為單個常數整數的 Python runtime 版本號。詳見 @ref{37e,,Py_PACK_FULL_VERSION()} 以了解編碼詳細資訊。這包含在 runtime 使用的 Python 版本。

使用它進行數值比較，例如 @code{if (Py_Version >= ...)}。


在 3.11 版被加入.

@end deffn

@node Bit-packing macros,,Run-time version,API 和 ABI 版本管理
@anchor{c-api/apiabiversion bit-packing-macros}@anchor{53fa}
@subsection Bit-packing macros


@geindex Py_PACK_FULL_VERSION (C function)
@anchor{c-api/apiabiversion c Py_PACK_FULL_VERSION}@anchor{37e}
@deffn {C 函式} uint32_t Py_PACK_FULL_VERSION (int major, int minor, int micro, int release_level, int release_serial)
` 為 @ref{76e,,穩定 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

引數

@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


例如：


@multitable {xxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxx} 
@headitem

版本

@tab

@code{Py_PACK_FULL_VERSION} 引數

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


在 3.14 版被加入.

@end deffn

@geindex Py_PACK_VERSION (C function)
@anchor{c-api/apiabiversion c Py_PACK_VERSION}@anchor{37d}
@deffn {C 函式} uint32_t Py_PACK_VERSION (int major, int minor)
` 為 @ref{76e,,穩定 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.


在 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 監控 C API,Generating Execution Events,API 和 ABI 版本管理,Python/C API 參考手冊
@anchor{c-api/monitoring doc}@anchor{53fb}@anchor{c-api/monitoring c-api-monitoring}@anchor{480}@anchor{c-api/monitoring monitoring-c-api}@anchor{53fc}@anchor{c-api/monitoring translation-repo}@anchor{53fd}
@section 監控 C API


於 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{e0,,sys.monitoring}.

@node Generating Execution Events,,監控 C API,Python/C API 參考手冊
@anchor{c-api/monitoring generating-execution-events}@anchor{53fe}
@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{e0,,sys.monitoring}
for details about the signatures of the different event callbacks).
The @code{codelike} argument should be an instance of @ref{32e,,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{5b6}
@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.

關於事件的敘述請見 @ref{e0,,sys.monitoring}。

@geindex PyMonitoring_FirePyStartEvent (C function)
@anchor{c-api/monitoring c PyMonitoring_FirePyStartEvent}@anchor{5b7}
@deffn {C 函式} int PyMonitoring_FirePyStartEvent (PyMonitoringState *state, PyObject *codelike, int32_t offset)

發出一個 @code{PY_START} 事件。
@end deffn

@geindex PyMonitoring_FirePyResumeEvent (C function)
@anchor{c-api/monitoring c PyMonitoring_FirePyResumeEvent}@anchor{5b8}
@deffn {C 函式} int PyMonitoring_FirePyResumeEvent (PyMonitoringState *state, PyObject *codelike, int32_t offset)

發出一個 @code{PY_RESUME} 事件。
@end deffn

@geindex PyMonitoring_FirePyReturnEvent (C function)
@anchor{c-api/monitoring c PyMonitoring_FirePyReturnEvent}@anchor{5b9}
@deffn {C 函式} int PyMonitoring_FirePyReturnEvent (PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *retval)

發出一個 @code{PY_RETURN} 事件。
@end deffn

@geindex PyMonitoring_FirePyYieldEvent (C function)
@anchor{c-api/monitoring c PyMonitoring_FirePyYieldEvent}@anchor{5ba}
@deffn {C 函式} int PyMonitoring_FirePyYieldEvent (PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *retval)

發出一個 @code{PY_YIELD} 事件。
@end deffn

@geindex PyMonitoring_FireCallEvent (C function)
@anchor{c-api/monitoring c PyMonitoring_FireCallEvent}@anchor{5bb}
@deffn {C 函式} int PyMonitoring_FireCallEvent (PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *callable, PyObject *arg0)

發出一個 @code{CALL} 事件。
@end deffn

@geindex PyMonitoring_FireLineEvent (C function)
@anchor{c-api/monitoring c PyMonitoring_FireLineEvent}@anchor{5bc}
@deffn {C 函式} int PyMonitoring_FireLineEvent (PyMonitoringState *state, PyObject *codelike, int32_t offset, int lineno)

發出一個 @code{LINE} 事件。
@end deffn

@geindex PyMonitoring_FireJumpEvent (C function)
@anchor{c-api/monitoring c PyMonitoring_FireJumpEvent}@anchor{5bd}
@deffn {C 函式} int PyMonitoring_FireJumpEvent (PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *target_offset)

發出一個 @code{JUMP} 事件。
@end deffn

@geindex PyMonitoring_FireBranchLeftEvent (C function)
@anchor{c-api/monitoring c PyMonitoring_FireBranchLeftEvent}@anchor{3ab}
@deffn {C 函式} int PyMonitoring_FireBranchLeftEvent (PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *target_offset)

發出一個 @code{BRANCH_LEFT} 事件。
@end deffn

@geindex PyMonitoring_FireBranchRightEvent (C function)
@anchor{c-api/monitoring c PyMonitoring_FireBranchRightEvent}@anchor{3ac}
@deffn {C 函式} int PyMonitoring_FireBranchRightEvent (PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *target_offset)

發出一個 @code{BRANCH_RIGHT} 事件。
@end deffn

@geindex PyMonitoring_FireCReturnEvent (C function)
@anchor{c-api/monitoring c PyMonitoring_FireCReturnEvent}@anchor{5be}
@deffn {C 函式} int PyMonitoring_FireCReturnEvent (PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *retval)

發出一個 @code{C_RETURN} 事件。
@end deffn

@geindex PyMonitoring_FirePyThrowEvent (C function)
@anchor{c-api/monitoring c PyMonitoring_FirePyThrowEvent}@anchor{5bf}
@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{427,,PyErr_GetRaisedException()}).
@end deffn

@geindex PyMonitoring_FireRaiseEvent (C function)
@anchor{c-api/monitoring c PyMonitoring_FireRaiseEvent}@anchor{5c0}
@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{427,,PyErr_GetRaisedException()}).
@end deffn

@geindex PyMonitoring_FireCRaiseEvent (C function)
@anchor{c-api/monitoring c PyMonitoring_FireCRaiseEvent}@anchor{5c1}
@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{427,,PyErr_GetRaisedException()}).
@end deffn

@geindex PyMonitoring_FireReraiseEvent (C function)
@anchor{c-api/monitoring c PyMonitoring_FireReraiseEvent}@anchor{5c2}
@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{427,,PyErr_GetRaisedException()}).
@end deffn

@geindex PyMonitoring_FireExceptionHandledEvent (C function)
@anchor{c-api/monitoring c PyMonitoring_FireExceptionHandledEvent}@anchor{5c3}
@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{427,,PyErr_GetRaisedException()}).
@end deffn

@geindex PyMonitoring_FirePyUnwindEvent (C function)
@anchor{c-api/monitoring c PyMonitoring_FirePyUnwindEvent}@anchor{5c4}
@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{427,,PyErr_GetRaisedException()}).
@end deffn

@geindex PyMonitoring_FireStopIterationEvent (C function)
@anchor{c-api/monitoring c PyMonitoring_FireStopIterationEvent}@anchor{5c5}
@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{df0,,StopIteration}, it is used. Otherwise,
a new @ref{df0,,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{53ff}
@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{5c6}
@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.

`event_types' 的巨集有：

@c The table is here to make the docs searchable, and to allow automatic
@c links to the identifiers.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

巨集

@tab

事件

@item

@geindex PY_MONITORING_EVENT_BRANCH_LEFT (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_BRANCH_LEFT}@anchor{5400}
@deffn {C 巨集} PY_MONITORING_EVENT_BRANCH_LEFT
@end deffn

@tab

@ref{295,,BRANCH_LEFT}

@item

@geindex PY_MONITORING_EVENT_BRANCH_RIGHT (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_BRANCH_RIGHT}@anchor{5401}
@deffn {C 巨集} PY_MONITORING_EVENT_BRANCH_RIGHT
@end deffn

@tab

@ref{296,,BRANCH_RIGHT}

@item

@geindex PY_MONITORING_EVENT_CALL (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_CALL}@anchor{5402}
@deffn {C 巨集} PY_MONITORING_EVENT_CALL
@end deffn

@tab

@ref{1912,,CALL}

@item

@geindex PY_MONITORING_EVENT_C_RAISE (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_C_RAISE}@anchor{5403}
@deffn {C 巨集} PY_MONITORING_EVENT_C_RAISE
@end deffn

@tab

@ref{47f1,,C_RAISE}

@item

@geindex PY_MONITORING_EVENT_C_RETURN (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_C_RETURN}@anchor{5404}
@deffn {C 巨集} PY_MONITORING_EVENT_C_RETURN
@end deffn

@tab

@ref{47f2,,C_RETURN}

@item

@geindex PY_MONITORING_EVENT_EXCEPTION_HANDLED (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_EXCEPTION_HANDLED}@anchor{5405}
@deffn {C 巨集} PY_MONITORING_EVENT_EXCEPTION_HANDLED
@end deffn

@tab

@ref{47f3,,EXCEPTION_HANDLED}

@item

@geindex PY_MONITORING_EVENT_INSTRUCTION (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_INSTRUCTION}@anchor{5406}
@deffn {C 巨集} PY_MONITORING_EVENT_INSTRUCTION
@end deffn

@tab

@ref{47f4,,INSTRUCTION}

@item

@geindex PY_MONITORING_EVENT_JUMP (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_JUMP}@anchor{5407}
@deffn {C 巨集} PY_MONITORING_EVENT_JUMP
@end deffn

@tab

@ref{47f5,,JUMP}

@item

@geindex PY_MONITORING_EVENT_LINE (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_LINE}@anchor{5408}
@deffn {C 巨集} PY_MONITORING_EVENT_LINE
@end deffn

@tab

@ref{47f6,,LINE}

@item

@geindex PY_MONITORING_EVENT_PY_RESUME (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_PY_RESUME}@anchor{5409}
@deffn {C 巨集} PY_MONITORING_EVENT_PY_RESUME
@end deffn

@tab

@ref{47f7,,PY_RESUME}

@item

@geindex PY_MONITORING_EVENT_PY_RETURN (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_PY_RETURN}@anchor{540a}
@deffn {C 巨集} PY_MONITORING_EVENT_PY_RETURN
@end deffn

@tab

@ref{47f8,,PY_RETURN}

@item

@geindex PY_MONITORING_EVENT_PY_START (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_PY_START}@anchor{540b}
@deffn {C 巨集} PY_MONITORING_EVENT_PY_START
@end deffn

@tab

@ref{47f9,,PY_START}

@item

@geindex PY_MONITORING_EVENT_PY_THROW (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_PY_THROW}@anchor{540c}
@deffn {C 巨集} PY_MONITORING_EVENT_PY_THROW
@end deffn

@tab

@ref{17d4,,PY_THROW}

@item

@geindex PY_MONITORING_EVENT_PY_UNWIND (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_PY_UNWIND}@anchor{540d}
@deffn {C 巨集} PY_MONITORING_EVENT_PY_UNWIND
@end deffn

@tab

@ref{47fa,,PY_UNWIND}

@item

@geindex PY_MONITORING_EVENT_PY_YIELD (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_PY_YIELD}@anchor{540e}
@deffn {C 巨集} PY_MONITORING_EVENT_PY_YIELD
@end deffn

@tab

@ref{47fb,,PY_YIELD}

@item

@geindex PY_MONITORING_EVENT_RAISE (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_RAISE}@anchor{540f}
@deffn {C 巨集} PY_MONITORING_EVENT_RAISE
@end deffn

@tab

@ref{18d7,,RAISE}

@item

@geindex PY_MONITORING_EVENT_RERAISE (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_RERAISE}@anchor{5410}
@deffn {C 巨集} PY_MONITORING_EVENT_RERAISE
@end deffn

@tab

@ref{47fd,,RERAISE}

@item

@geindex PY_MONITORING_EVENT_STOP_ITERATION (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_STOP_ITERATION}@anchor{5411}
@deffn {C 巨集} PY_MONITORING_EVENT_STOP_ITERATION
@end deffn

@tab

@ref{47fc,,STOP_ITERATION}

@end multitable

@end deffn

@geindex PyMonitoring_ExitScope (C function)
@anchor{c-api/monitoring c PyMonitoring_ExitScope}@anchor{5c7}
@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{5412}
@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{4801,,local event}.


在 3.13 版被加入.



在 3.14 版之後被棄用: This function is @ref{23d,,soft deprecated}.

@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 安裝 Python 模組,Python 如何達成任務,Python/C API 參考手冊,Top
@anchor{installing/index doc}@anchor{5413}@anchor{installing/index installing-index}@anchor{10f3}@anchor{installing/index installing-python-modules}@anchor{5414}@anchor{installing/index translation-repo}@anchor{5415}
@chapter 安裝 Python 模組


@*電子郵件: 
@email{distutils-sig@@python.org}


作為一個普及的開源開發專案，Python 有一個活躍的支持社群，由其貢獻者及使用者組成，而他們也讓他們的軟體可被其他 Python 開發者在開源授權條款下使用。

這樣可以讓 Python 使用者們有效地共享和合作，並受益於其他人對常見（有時甚至是罕見）的問題已經建立的解決方案，更可以在公用社群中潛在地貢獻他們自己的解決方案。

這份指南涵蓋了上述過程中的安裝部分。如果是要建立及分享你自己的 Python 專案，請參考 Python packaging user guide@footnote{https://packaging.python.org/en/latest/tutorials/packaging-projects/}。

@cartouche
@quotation 備註 
對於企業和其他機構的使用者，要注意到，許多組織對於使用和貢獻開源軟體都有自己的政策。在開始使用配備 Python 的發布及安裝工具時，請將那些政策納入考量。
@end quotation
@end cartouche

@menu
* 關鍵術語:: 
* 基本用法: 基本用法<5>. 
* 我該如何...？: 我該如何 ？. 
* 常見的安裝問題:: 

@end menu

@node 關鍵術語,基本用法<5>,,安裝 Python 模組
@anchor{installing/index key-terms}@anchor{5416}
@section 關鍵術語



@itemize *

@item 
@code{pip} 是首選的安裝程式。從 Python 3.4 開始，它被預設包含在 Python 二進制安裝程式中。

@item 
`virtual environment（虛擬環境）'是一種半隔離的 Python 環境，可以為某個特定應用程式安裝其所需的套件，而不用在整個系統上安裝它們。

@item 
@code{venv} 是建立虛擬環境的標準工具，它從 Python 3.3 開始成為 Python 的一部分。從 Python 3.4 開始，它會預設地安裝 @code{pip} 到所有被建立的虛擬環境。

@item 
@code{virtualenv} 是 @code{venv} 的一個第三方替代方案（及其前身）。它使虛擬環境可以在 Python 3.4 之前的版本被使用，那些版本要不是根本沒提供 @code{venv}，就是無法自動安裝 @code{pip} 到所建立的環境中。

@item 
Python 套件索引 (Python Package Index)@footnote{https://pypi.org} 是開源授權套件的一個公共儲存庫，其中的套件皆可被其他 Python 使用者所使用。

@item 
Python 封裝管理站 (Python Packaging Authority)@footnote{https://www.pypa.io/} 是一個由開發者和說明文件作者組成的團隊，負責維護及改進標準封裝工具，以及相關的元資料 (metadata) 和檔案格式標準。他們在 GitHub@footnote{https://github.com/pypa} 平台上維護各種工具、說明文件及問題追蹤系統。

@item 
@code{distutils} 是最早的建置和發布系統，於 1998 年首次被加入 Python 標準函式庫。雖然直接使用 @code{distutils} 的方式已經被逐步淘汰，它仍然是現今封裝和發布的基礎結構根基，而且它不僅仍然是標準函式庫的一部分，它的名稱也以其他的方式存活著（例如：用於協調 Python 封裝標準開發的郵寄清單就是以它命名）。
@end itemize


在 3.5 版的變更: 對於建立虛擬環境，現在推薦使用 @code{venv}。



@subsubheading 也參考


Python 封裝使用者指南：建立和使用虛擬環境@footnote{https://packaging.python.org/installing/#creating-virtual-environments}


@node 基本用法<5>,我該如何 ？,關鍵術語,安裝 Python 模組
@anchor{installing/index basic-usage}@anchor{5417}
@section 基本用法


標準封裝工具皆是以能從命令列使用的方式被設計的。

以下指令將從 Python 套件索引安裝一個模組的最新版本及其依賴套件 (dependencies)：

@example
python -m pip install SomePackage
@end example

@cartouche
@quotation 備註 
對於 POSIX 使用者（包括 macOS 和 Linux 使用者），本指南中的範例皆假設有使用 @ref{1fb4,,virtual environment}。

對於 Windows 使用者，本指南中的範例皆假設在安裝 Python 時，「可調整系統 PATH 環境變數」的選項已被選取。
@end quotation
@end cartouche

在命令列中直接指定一個明確的或最小的版本也是可行的。當使用像是 @code{>}、@code{<} 的比較運算子，或某些可被 shell 所解釋的其他特殊字元時，套件名稱與版本編號應該要放在雙引號內：

@example
python -m pip install SomePackage==1.0.4    # 明確版本
python -m pip install "SomePackage>=1.0.4"  # 最小版本
@end example

通常，如果一個合適的模組已被安裝，嘗試再次安裝它將不會有任何效果。要升級現有的模組就必須明確地請求：

@example
python -m pip install --upgrade SomePackage
@end example

關於 @code{pip} 及其能力的更多資訊和資源，可以在 Python 封裝使用者指南@footnote{https://packaging.python.org}中找到。

虛擬環境的建立是使用 @ref{117,,venv} 模組來完成。要在一個已啟用的虛擬環境中安裝套件，可使用前面展示的指令。


@subsubheading 也參考


Python 封裝使用者指南：安裝 Python 發布套件@footnote{https://packaging.python.org/installing/}


@node 我該如何 ？,常見的安裝問題,基本用法<5>,安裝 Python 模組
@anchor{installing/index how-do-i}@anchor{5418}
@section 我該如何...？


接下來是關於一些常見任務的快速解答或連結。

@menu
* ...在 Python 3.4 之前的 Python 版本中安裝 pip？: 在 Python 3 4 之前的 Python 版本中安裝 pip？. 
* ...只為目前的使用者安裝套件？: 只為目前的使用者安裝套件？. 
* ...安裝科學的 Python 套件？: 安裝科學的 Python 套件？. 
* ...平行安裝多個 Python 版本並使用它們？: 平行安裝多個 Python 版本並使用它們？. 

@end menu

@node 在 Python 3 4 之前的 Python 版本中安裝 pip？,只為目前的使用者安裝套件？,,我該如何 ？
@anchor{installing/index install-pip-in-versions-of-python-prior-to-python-3-4}@anchor{5419}
@subsection ...在 Python 3.4 之前的 Python 版本中安裝 @code{pip}？


Python 是從 Python 3.4 才開始綁定 @code{pip} 的。對於更早的版本，@code{pip} 需要被「自助安裝 (bootstrapped)」，請參考 Python 封裝使用者指南中的說明。


@subsubheading 也參考


Python 封裝使用者指南：安裝套件的需求@footnote{https://packaging.python.org/installing/#requirements-for-installing-packages}


@c installing-per-user-installation:

@node 只為目前的使用者安裝套件？,安裝科學的 Python 套件？,在 Python 3 4 之前的 Python 版本中安裝 pip？,我該如何 ？
@anchor{installing/index install-packages-just-for-the-current-user}@anchor{541a}
@subsection ...只為目前的使用者安裝套件？


把 @code{--user} 選項傳給 @code{python -m pip install}，這樣將會只為目前使用者而非系統的所有使用者安裝套件。

@node 安裝科學的 Python 套件？,平行安裝多個 Python 版本並使用它們？,只為目前的使用者安裝套件？,我該如何 ？
@anchor{installing/index install-scientific-python-packages}@anchor{541b}
@subsection ...安裝科學的 Python 套件？


許多科學類 Python 套件都有複雜的二進制依賴套件，且目前不太容易直接使用 @code{pip} 安裝。目前為止，使用其他方法@footnote{https://packaging.python.org/science/}而非嘗試用 @code{pip} 來安裝它們，對使用者來說通常會更簡單。


@subsubheading 也參考


Python 封裝使用者指南：安裝科學套件@footnote{https://packaging.python.org/science/}


@node 平行安裝多個 Python 版本並使用它們？,,安裝科學的 Python 套件？,我該如何 ？
@anchor{installing/index work-with-multiple-versions-of-python-installed-in-parallel}@anchor{541c}
@subsection ...平行安裝多個 Python 版本並使用它們？


在 Linux、macOS 以及其他 POSIX 系統中，使用帶有版本編號的 Python 指令並結合 @code{-m} 開關參數 (switch)，來運行 @code{pip} 的適當副本：

@example
python2   -m pip install SomePackage  # 預設 Python 2
python2.7 -m pip install SomePackage  # 指定 Python 2.7
python3   -m pip install SomePackage  # 預設 Python 3
python3.4 -m pip install SomePackage  # 指定 Python 3.4
@end example

使用帶有合適版本編號的 @code{pip} 指令，也是可行的。

在 Windows 中，使用 Python 啟動指令 @code{py} 並結合 @code{-m} 開關參數 (switch)：

@example
py -2   -m pip install SomePackage  # 預設 Python 2
py -2.7 -m pip install SomePackage  # 指定 Python 2.7
py -3   -m pip install SomePackage  # 預設 Python 3
py -3.4 -m pip install SomePackage  # 指定 Python 3.4
@end example

@c other questions:
@c 
@c Once the Development & Deployment part of PPUG is fleshed out, some of
@c those sections should be linked from new questions here (most notably,
@c we should have a question about avoiding depending on PyPI that links to
@c https://packaging.python.org/en/latest/guides/index-mirrors-and-caches/)

@node 常見的安裝問題,,我該如何 ？,安裝 Python 模組
@anchor{installing/index common-installation-issues}@anchor{541d}
@section 常見的安裝問題


@menu
* 在 Linux 上安裝套件至系統 Python:: 
* 未安裝 pip:: 
* 安裝二進制擴充 (binary extension): 安裝二進制擴充 binary extension. 

@end menu

@node 在 Linux 上安裝套件至系統 Python,未安裝 pip,,常見的安裝問題
@anchor{installing/index installing-into-the-system-python-on-linux}@anchor{541e}
@subsection 在 Linux 上安裝套件至系統 Python


在 Linux 系統，Python 的某個安裝版本通常會被內含在 Linux 的發行版中。要安裝套件到這個 Python 版本上需要系統的 root 權限，並且可能會干擾到系統套件管理器的運作。如果其他系統組件非預期地以 @code{pip} 被升級，也會干擾這些組件的運作。

在這樣的系統上，以 @code{pip} 安裝套件時，通常較好的方式是使用虛擬環境，或以個別使用者安裝。

@node 未安裝 pip,安裝二進制擴充 binary extension,在 Linux 上安裝套件至系統 Python,常見的安裝問題
@anchor{installing/index pip-not-installed}@anchor{541f}
@subsection 未安裝 pip


@code{pip} 沒有預設被安裝也是有可能的。一個潛在的解法是：

@example
python -m ensurepip --default-pip
@end example

這裡還有其他關於安裝 pip@footnote{https://packaging.python.org/en/latest/tutorials/installing-packages/#ensure-pip-setuptools-and-wheel-are-up-to-date}的資源。

@node 安裝二進制擴充 binary extension,,未安裝 pip,常見的安裝問題
@anchor{installing/index installing-binary-extensions}@anchor{5420}
@subsection 安裝二進制擴充 (binary extension)


Python 基本上相當倚賴以原始碼為基礎的發布方式，也會期望使用者在安裝過程的某個階段，從原始碼來編譯擴充模組。

隨著引入對二進制 @code{wheel} 格式的支援，以及透過 Python 套件索引能夠至少在 Windows 和 macOS 發布 wheel 檔案，這個問題預期將會逐漸消失，因為使用者將能夠更頻繁地安裝預建置 (pre-built) 的擴充，而不再需要自己建置它們。

有一些解決方案，可用來安裝那些還無法以預建置的 @code{wheel} 檔案被使用的科學軟體@footnote{https://packaging.python.org/science/}，這些方案也有助於取得其他的二進制擴充，且無需在本機對它們進行建置。


@subsubheading 也參考


Python 封裝使用者指南：二進制擴充@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 如何達成任務,Python 常見問題,安裝 Python 模組,Top
@anchor{howto/index doc}@anchor{5421}@anchor{howto/index how-tos}@anchor{5422}@anchor{howto/index python-howtos}@anchor{5423}@anchor{howto/index translation-repo}@anchor{5424}
@chapter Python 如何達成任務


「Python 如何達成任務 (HOWTOs)」是一系列的說明文件，其內容會深度地涵蓋某些特定的主題。以 Linux 說明文件專案的 HOWTO 系列為模範，本系列的目標是提供比 Python 函式庫參考手冊更實用的說明文件。

@menu
* asyncio 的概念性總覽:: 
* 遷移延伸模組到 Python 3:: 
* Curses Programming with Python:: 
* 描述器 (Descriptor) 指南: 描述器 Descriptor 指南. 
* 使用 GDB 來為 C API 擴充功能和 CPython 內部偵錯:: 
* Enum HOWTO:: 
* 函式程式設計 HOWTO:: 
* 如何使用 Logging 模組:: 
* Logging Cookbook:: 
* 如何使用正規表示式:: 
* Socket 程式設計指南:: 
* 排序技法:: 
* Unicode HOWTO:: 
* 如何使用 urllib 套件取得網路資源:: 
* ipaddress 模組介紹:: 
* 使用 DTrace 和 SystemTap 檢測 CPython:: 
* Python 對 Linux perf 分析器的支援:: 
* 註釋 (annotation) 最佳實踐: 註釋 annotation 最佳實踐. 
* 隔離擴充模組:: 
* 計時器檔案描述器 (timerfd) 指南: 計時器檔案描述器 timerfd 指南. 
* The Python 2.3 Method Resolution Order: The Python 2 3 Method Resolution Order. 
* Python 自由執行緒的支援:: 
* 支援自由執行緒的 C API 擴充:: 
* Remote debugging attachment protocol:: 
* Permission requirements:: 
* Locating the PyRuntime structure:: 
* 讀取 _Py_DebugOffsets:: 
* Locating the interpreter and thread state:: 
* Writing control information:: 
* Summary:: 

@end menu

@node asyncio 的概念性總覽,遷移延伸模組到 Python 3,,Python 如何達成任務
@anchor{howto/a-conceptual-overview-of-asyncio doc}@anchor{5425}@anchor{howto/a-conceptual-overview-of-asyncio a-conceptual-overview-of-asyncio}@anchor{366c}@anchor{howto/a-conceptual-overview-of-asyncio id1}@anchor{5426}
@section @code{asyncio} 的概念性總覽


This @ref{5422,,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,,asyncio 的概念性總覽
@anchor{howto/a-conceptual-overview-of-asyncio a-conceptual-overview-part-1-the-high-level}@anchor{5427}
@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
* 事件迴圈: 事件迴圈<2>. 
* 非同步函式與協程:: 
* Tasks:: 
* await:: 

@end menu

@node 事件迴圈<2>,非同步函式與協程,,A conceptual overview part 1 the high-level
@anchor{howto/a-conceptual-overview-of-asyncio event-loop}@anchor{5428}
@subsubsection 事件迴圈


Everything in @code{asyncio} happens relative to the event loop.
It's the star of the show.
It's like an orchestra conductor.
It's behind the scenes managing resources.
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 worker bees.

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.

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 非同步函式與協程,Tasks,事件迴圈<2>,A conceptual overview part 1 the high-level
@anchor{howto/a-conceptual-overview-of-asyncio asynchronous-functions-and-coroutines}@anchor{5429}
@subsubsection 非同步函式與協程


這是一個基本的、無聊的 Python 函式：

@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{7e6,,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{366d,,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{1084,,types.CoroutineType} (native coroutine).
Note that coroutines can also exist as instances of
@ref{fd8,,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{dd4,,generators} and
@ref{125c,,generator functions}.
Recall, a generator function is a function that @ref{bb9,,yield}s, like this
one:

@example
def get_random_number():
    # 這是個很爛的隨機數產生器！
    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{9d1,,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,await,非同步函式與協程,A conceptual overview part 1 the high-level
@anchor{howto/a-conceptual-overview-of-asyncio tasks}@anchor{542a}
@subsubsection Tasks


Roughly speaking, @ref{369f,,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{18d,,await}.
The recommended way to create tasks is via @ref{1c9,,asyncio.create_task()}.

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

Since there's only one event loop (in each thread), @code{asyncio} takes care of
associating the task with the event loop for you. As such, there's no need
to specify the event loop.

@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{2f2,,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,A conceptual overview part 1 the high-level
@anchor{howto/a-conceptual-overview-of-asyncio await}@anchor{542b}
@subsubsection await


@ref{18d,,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.

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.

`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{2f2,,asyncio.run()} can help you detect such occurrences via the
@code{debug=True} flag, which enables
@ref{2001,,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.
That might sound minor, but in a large program with many @code{await} statements and a deep
call stack, that overhead can add up to a meaningful performance drag.

@node A conceptual overview part 2 the nuts and bolts,,A conceptual overview part 1 the high-level,asyncio 的概念性總覽
@anchor{howto/a-conceptual-overview-of-asyncio a-conceptual-overview-part-2-the-nuts-and-bolts}@anchor{542c}
@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{542d}
@subsubsection The inner workings of coroutines


@code{asyncio} leverages four components to pass around control.

@ref{22c9,,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{233f,,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{f70,,__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{df0,,StopIteration} exception with the
return value attached in the @ref{22c6,,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{2343,,async generator function}, a
different beast entirely.

2. What about a @ref{233f,,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.
Initially @code{yield} was barred as well, but was re-accepted to allow for
async generators.
Despite that, @code{yield from} and @code{await} effectively do the same thing.
@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{542e}
@subsubsection Futures


A @ref{377a,,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{1c7,,asyncio.Task} subclasses @ref{dc1,,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{542f}
@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{c5b,,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{36a2,,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 遷移延伸模組到 Python 3,Curses Programming with Python,asyncio 的概念性總覽,Python 如何達成任務
@anchor{howto/cporting doc}@anchor{5430}@anchor{howto/cporting cporting-howto}@anchor{14e1}@anchor{howto/cporting porting-extension-modules-to-python-3}@anchor{5431}@anchor{howto/cporting translation-repo}@anchor{5432}
@section 遷移延伸模組到 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{4d56,,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 指南,遷移延伸模組到 Python 3,Python 如何達成任務
@anchor{howto/curses doc}@anchor{5433}@anchor{howto/curses curses-howto}@anchor{3314}@anchor{howto/curses curses-programming-with-python}@anchor{5434}@anchor{howto/curses translation-repo}@anchor{5435}
@section Curses Programming with Python


@*作者: 
A.M. Kuchling, Eric S. Raymond


@*發佈版本: 
2.04


@subsubheading 摘要



This document describes how to use the @ref{2f,,curses} extension
module to control text-mode displays.

@menu
* What is curses?:: 
* Starting and ending a curses application:: 
* Windows and Pads:: 
* Displaying Text:: 
* 使用者輸入:: 
* 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{5436}
@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{2f,,curses}
module.  A ported version called UniCurses@footnote{https://pypi.org/project/UniCurses/} is available.

@menu
* Python curses 模組:: 

@end menu

@node Python curses 模組,,,What is curses?
@anchor{howto/curses the-python-curses-module}@anchor{5437}
@subsubsection Python curses 模組


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{332a,,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{5438}
@subsection Starting and ending a curses application


Before doing anything, curses must be initialized.  This is done by
calling the @ref{187a,,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{3351,,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{33c9,,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{332d,,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{c6a,,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{c6a,,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{8f0,,try}...@ref{1ab,,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 windows-and-pads}@anchor{5439}
@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{187a,,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{334f,,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{fe7,,curses.LINES} and @ref{fe8,,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{332b,,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{3329,,noutrefresh()} method of each window
to update an underlying data structure representing the desired
state of the screen.

@item 
Calls the function @ref{3328,,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,使用者輸入,Windows and Pads,Curses Programming with Python
@anchor{howto/curses displaying-text}@anchor{543a}
@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{332a,,addstr()} accept multiple argument forms.  Usually there
are four different forms.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Form

@tab

描述

@item

`str' 或 `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' 或 `ch'

@tab

Move to position `y,x' within the window, and
display `str' or `ch'

@item

`y'、`x'、`str' 或 `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{332a,,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{1297,,encoding} attribute; this defaults to
the default system encoding as returned by @ref{328,,locale.getencoding()}.

The @ref{336a,,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{3436,,ACS_PLMINUS} is a +/-
symbol, and @ref{3374,,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{3322,,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{543b}
@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

屬性

@tab

描述

@item

@ref{33b5,,A_BLINK}

@tab

Blinking text

@item

@ref{33b6,,A_BOLD}

@tab

Extra bright or bold text

@item

@ref{33b7,,A_DIM}

@tab

Half bright text

@item

@ref{3320,,A_REVERSE}

@tab

Reverse-video text

@item

@ref{331f,,A_STANDOUT}

@tab

The best highlighting mode available

@item

@ref{33bb,,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{335b,,start_color()} function soon
after calling @ref{187a,,initscr()}, to initialize the default color set
(the @ref{c6a,,curses.wrapper()} function does this automatically).  Once that's
done, the @ref{3340,,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{331e,,color_pair()}
function; this can be bitwise-OR'ed with other attributes such as
@ref{3320,,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{335b,,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{2f,,curses}
module defines named constants for each of these colors:
@ref{3448,,curses.COLOR_BLACK}, @ref{344d,,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{331b,,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 使用者輸入,For More Information,Displaying Text,Curses Programming with Python
@anchor{howto/curses user-input}@anchor{543c}
@subsection 使用者輸入


The C curses library offers only very simple input mechanisms. Python's
@ref{2f,,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{17a8,,getch()} refreshes the screen and then waits for
the user to hit a key, displaying the key if @ref{332c,,echo()} has been
called earlier.  You can optionally specify a coordinate to which
the cursor should be moved before pausing.

@item 
@ref{3388,,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{339c,,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{3344,,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{33da,,curses.KEY_PPAGE},
@ref{33cb,,curses.KEY_HOME}, or @ref{33c9,,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{30,,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{3490,,curses.ascii.ctrl()} returns the
control character corresponding to its argument.

There's also a method to retrieve an entire string,
@ref{17bb,,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{32,,curses.textpad} module supplies a text box that supports an
Emacs-like set of keybindings.  Various methods of the
@ref{3451,,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{32,,curses.textpad} for more details.

@node For More Information,,使用者輸入,Curses Programming with Python
@anchor{howto/curses for-more-information}@anchor{543d}
@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{2f,,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{3422,,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 
ncurses 使用者手冊@footnote{https://linux.die.net/man/3/ncurses}

@item 
ncurses 問答集@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 指南,使用 GDB 來為 C API 擴充功能和 CPython 內部偵錯,Curses Programming with Python,Python 如何達成任務
@anchor{howto/descriptor doc}@anchor{543e}@anchor{howto/descriptor descriptor-guide}@anchor{543f}@anchor{howto/descriptor descriptorhowto}@anchor{16e1}@anchor{howto/descriptor translation-repo}@anchor{5440}
@section 描述器 (Descriptor) 指南


@*作者: 
Raymond Hettinger


@*聯絡方式: 
<python at rcn dot com>


@ref{17fc,,描述器}讓物件自訂屬性能夠被查找、儲存和刪除。

此指南有四個主要章節：


@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{489,,classmethod()}, @ref{451,,staticmethod()}, @ref{4ae,,property()}, and
@ref{7f0,,__slots__}.
@end enumerate

@menu
* Primer:: 
* Complete Practical Example:: 
* Technical Tutorial:: 
* Pure Python Equivalents:: 

@end menu

@node Primer,Complete Practical Example,,描述器 Descriptor 指南
@anchor{howto/descriptor primer}@anchor{5441}
@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{5442}
@subsubsection Simple example: A descriptor that returns a constant


The @code{Ten} class is a descriptor whose @ref{16dc,,__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{5443}
@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{16dc,,__get__()}.  The `self'
parameter is `size', an instance of `DirectorySize'.  The `obj' parameter is
either `g' or `s', an instance of `Directory'.  It is the `obj' parameter that
lets the @ref{16dc,,__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{5444}
@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{16dc,,__get__()} and @ref{2267,,__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{5445}
@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{e43,,__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{e43,,__set_name__()} so that the field names would be recorded.  Here
we call @ref{1ceb,,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{5446}
@subsubsection Closing thoughts


A @ref{17fc,,descriptor} is what we call any object that defines @ref{16dc,,__get__()},
@ref{2267,,__set__()}, or @ref{18b6,,__delete__()}.

Optionally, descriptors can have a @ref{e43,,__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{489,,classmethod()}, @ref{451,,staticmethod()},
@ref{4ae,,property()}, and @ref{75c,,functools.cached_property()} are all implemented as
descriptors.

@node Complete Practical Example,Technical Tutorial,Primer,描述器 Descriptor 指南
@anchor{howto/descriptor complete-practical-example}@anchor{5447}
@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{5448}
@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{13b7,,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{5449}
@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{19b,,int} or
@ref{196,,float}.  Optionally, it verifies that a value is between a given
minimum or maximum.

@item 
@code{String} verifies that a value is a @ref{169,,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{544a}
@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 指南
@anchor{howto/descriptor technical-tutorial}@anchor{544b}
@subsection Technical Tutorial


What follows is a more technical tutorial for the mechanics and details of how
descriptors work.

@menu
* 摘要:: 
* Definition and introduction:: 
* 描述器協定:: 
* Overview of descriptor invocation:: 
* Invocation from an instance:: 
* Invocation from a class:: 
* Invocation from super:: 
* Summary of invocation logic:: 
* Automatic name notification:: 
* ORM 範例:: 

@end menu

@node 摘要,Definition and introduction,,Technical Tutorial
@anchor{howto/descriptor abstract}@anchor{544c}
@subsubsection 摘要


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,描述器協定,摘要,Technical Tutorial
@anchor{howto/descriptor definition-and-introduction}@anchor{544d}
@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{16dc,,__get__()}, @ref{2267,,__set__()},
and @ref{18b6,,__delete__()}.  If any of those methods are defined for an
attribute, it is said to be a @ref{17fc,,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{1a6,,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 描述器協定,Overview of descriptor invocation,Definition and introduction,Technical Tutorial
@anchor{howto/descriptor descriptor-protocol}@anchor{544e}
@subsubsection 描述器協定


@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{2267,,__set__()} or @ref{18b6,,__delete__()}, it is considered
a data descriptor.  Descriptors that only define @ref{16dc,,__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{16dc,,__get__()} and
@ref{2267,,__set__()} with the @ref{2267,,__set__()} raising an @ref{5e8,,AttributeError} when
called.  Defining the @ref{2267,,__set__()} method with an exception raising
placeholder is enough to make it a data descriptor.

@node Overview of descriptor invocation,Invocation from an instance,描述器協定,Technical Tutorial
@anchor{howto/descriptor overview-of-descriptor-invocation}@anchor{544f}
@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{776,,__dict__}, its @ref{16dc,,__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{5450}
@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{6f3,,__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{dc6,,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 = object()
    objtype = type(obj)
    cls_var = find_name_in_mro(objtype, name, null)
    descr_get = getattr(type(cls_var), '__get__', null)
    if descr_get is not null:
        if (hasattr(type(cls_var), '__set__')
            or hasattr(type(cls_var), '__delete__')):
            return descr_get(cls_var, obj, objtype)     # data descriptor
    if hasattr(obj, '__dict__') and name in vars(obj):
        return vars(obj)[name]                          # instance variable
    if descr_get is not null:
        return descr_get(cls_var, obj, objtype)         # non-data descriptor
    if cls_var is not null:
        return cls_var                                  # class variable
    raise AttributeError(name)
@end example

@c # Test the fidelity of object_getattribute() by comparing it with the
@c # normal object.__getattribute__().  The former will be accessed by
@c # square brackets and the latter by the dot operator.
@c 
@c class Object:
@c 
@c     def __getitem__(obj, name):
@c         try:
@c             return object_getattribute(obj, name)
@c         except AttributeError:
@c             if not hasattr(type(obj), '__getattr__'):
@c                 raise
@c         return type(obj).__getattr__(obj, name)             # __getattr__
@c 
@c class DualOperator(Object):
@c 
@c     x = 10
@c 
@c     def __init__(self, z):
@c         self.z = z
@c 
@c     @property
@c     def p2(self):
@c         return 2 * self.x
@c 
@c     @property
@c     def p3(self):
@c         return 3 * self.x
@c 
@c     def m5(self, y):
@c         return 5 * y
@c 
@c     def m7(self, y):
@c         return 7 * y
@c 
@c     def __getattr__(self, name):
@c         return ('getattr_hook', self, name)
@c 
@c class DualOperatorWithSlots:
@c 
@c     __getitem__ = Object.__getitem__
@c 
@c     __slots__ = ['z']
@c 
@c     x = 15
@c 
@c     def __init__(self, z):
@c         self.z = z
@c 
@c     @property
@c     def p2(self):
@c         return 2 * self.x
@c 
@c     def m5(self, y):
@c         return 5 * y
@c 
@c     def __getattr__(self, name):
@c         return ('getattr_hook', self, name)
@c 
@c class D1:
@c     def __get__(self, obj, objtype=None):
@c         return type(self), obj, objtype
@c 
@c class U1:
@c     x = D1()
@c 
@c class U2(U1):
@c     pass

@c >>> a = DualOperator(11)
@c >>> vars(a).update(p3 = '_p3', m7 = '_m7')
@c >>> a.x == a['x'] == 10
@c True
@c >>> a.z == a['z'] == 11
@c True
@c >>> a.p2 == a['p2'] == 20
@c True
@c >>> a.p3 == a['p3'] == 30
@c True
@c >>> a.m5(100) == a.m5(100) == 500
@c True
@c >>> a.m7 == a['m7'] == '_m7'
@c True
@c >>> a.g == a['g'] == ('getattr_hook', a, 'g')
@c True
@c 
@c >>> b = DualOperatorWithSlots(22)
@c >>> b.x == b['x'] == 15
@c True
@c >>> b.z == b['z'] == 22
@c True
@c >>> b.p2 == b['p2'] == 30
@c True
@c >>> b.m5(200) == b['m5'](200) == 1000
@c True
@c >>> b.g == b['g'] == ('getattr_hook', b, 'g')
@c True
@c 
@c >>> u2 = U2()
@c >>> object_getattribute(u2, 'x') == u2.x == (D1, u2, U2)
@c True

Note, there is no @ref{6f3,,__getattr__()} hook in the @ref{dc6,,__getattribute__()}
code.  That is why calling @ref{dc6,,__getattribute__()} directly or with
@code{super().__getattribute__} will bypass @ref{6f3,,__getattr__()} entirely.

Instead, it is the dot operator and the @ref{dc5,,getattr()} function that are
responsible for invoking @ref{6f3,,__getattr__()} whenever @ref{dc6,,__getattribute__()}
raises an @ref{5e8,,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{5451}
@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{248c,,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/3.14/Objects/typeobject.c}.

@node Invocation from super,Summary of invocation logic,Invocation from a class,Technical Tutorial
@anchor{howto/descriptor invocation-from-super}@anchor{5452}
@subsubsection Invocation from super


The logic for super's dotted lookup is in the @ref{dc6,,__getattribute__()} method for
object returned by @ref{1a6,,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/3.14/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{5453}
@subsubsection Summary of invocation logic


The mechanism for descriptors is embedded in the @ref{dc6,,__getattribute__()}
methods for @ref{c75,,object}, @ref{f3f,,type}, and @ref{1a6,,super()}.

要記住的重點是：


@itemize *

@item 
Descriptors are invoked by the @ref{dc6,,__getattribute__()} method.

@item 
Classes inherit this machinery from @ref{c75,,object}, @ref{f3f,,type}, or
@ref{1a6,,super()}.

@item 
Overriding @ref{dc6,,__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{16dc,,__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 範例,Summary of invocation logic,Technical Tutorial
@anchor{howto/descriptor automatic-name-notification}@anchor{5454}
@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{f3f,,type} metaclass
scans the dictionary of the new class.  If any of the entries are descriptors
and if they define @ref{e43,,__set_name__()}, that method is called with two
arguments.  The `owner' is the class where the descriptor is used, and the
`name' is the class variable the descriptor was assigned to.

The implementation details are in @code{type_new()} and
@code{set_names()} in Objects/typeobject.c@footnote{https://github.com/python/cpython/tree/3.14/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{e43,,__set_name__()} will need to be called manually.

@node ORM 範例,,Automatic name notification,Technical Tutorial
@anchor{howto/descriptor orm-example}@anchor{5455}
@subsubsection ORM 範例


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 指南
@anchor{howto/descriptor pure-python-equivalents}@anchor{5456}
@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{5457}
@subsubsection Properties


Calling @ref{4ae,,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{4ae,,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{4ae,,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{4ae,,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{5458}
@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{1ab1,,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{16dc,,__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{1bf6,,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{16dc,,__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{16dc,,__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{16dc,,__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{5459}
@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{16dc,,__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

函式

@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{545a}
@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{451,,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{121d,,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{14d5,,__name__}, @ref{21fb,,__qualname__},
and @ref{13da,,__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{545b}
@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{24e,,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{489,,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{121d,,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{14d5,,__name__},
@ref{21fb,,__qualname__}, @ref{13da,,__doc__},
and @ref{13d9,,__annotations__}.

@node Member objects and __slots__,,Class methods,Pure Python Equivalents
@anchor{howto/descriptor member-objects-and-slots}@anchor{545c}
@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{75c,,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 = object()

class Member:

    def __init__(self, name, clsname, offset):
        'Emulate PyMemberDef in Include/structmember.h'
        # Also see descr_new() in Objects/descrobject.c
        self.name = name
        self.clsname = clsname
        self.offset = offset

    def __get__(self, obj, objtype=None):
        'Emulate member_get() in Objects/descrobject.c'
        # Also see PyMember_GetOne() in Python/structmember.c
        if obj is None:
            return self
        value = obj._slotvalues[self.offset]
        if value is null:
            raise AttributeError(self.name)
        return value

    def __set__(self, obj, value):
        'Emulate member_set() in Objects/descrobject.c'
        obj._slotvalues[self.offset] = value

    def __delete__(self, obj):
        'Emulate member_delete() in Objects/descrobject.c'
        value = obj._slotvalues[self.offset]
        if value is null:
            raise AttributeError(self.name)
        obj._slotvalues[self.offset] = null

    def __repr__(self):
        'Emulate member_repr() in Objects/descrobject.c'
        return f'<Member @{self.name!r@} of @{self.clsname!r@}>'
@end example

The @code{type.__new__()} method takes care of adding member objects to class
variables:

@example
class Type(type):
    'Simulate how the type metaclass adds member objects for slots'

    def __new__(mcls, clsname, bases, mapping, **kwargs):
        'Emulate type_new() in Objects/typeobject.c'
        # type_new() calls PyTypeReady() which calls add_methods()
        slot_names = mapping.get('slot_names', [])
        for offset, name in enumerate(slot_names):
            mapping[name] = Member(name, clsname, offset)
        return type.__new__(mcls, clsname, bases, mapping, **kwargs)
@end example

The @ref{799,,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{2282,,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 使用 GDB 來為 C API 擴充功能和 CPython 內部偵錯,Enum HOWTO,描述器 Descriptor 指南,Python 如何達成任務
@anchor{howto/gdb_helpers doc}@anchor{545d}@anchor{howto/gdb_helpers debugging-c-api-extensions-and-cpython-internals-with-gdb}@anchor{545e}@anchor{howto/gdb_helpers gdb}@anchor{545f}@anchor{howto/gdb_helpers translation-repo}@anchor{5460}
@section 使用 GDB 來為 C API 擴充功能和 CPython 內部偵錯


本文件解釋如何將 Python GDB 擴充功能 @code{python-gdb.py} 與 GDB 偵錯器一起使用來為 CPython 擴充功能和 CPython 直譯器本身偵錯。

在為崩潰或死鎖等低階問題幀錯時，低階偵錯器（例如 GDB）對於診斷和修正問題非常有用。預設情況下，GDB（或其任何前端）不支援特定於 CPython 直譯器的高階資訊。

@code{python-gdb.py} 擴充功能將 CPython 直譯器資訊新增至 GDB。此擴充有助於內省 (introspect) 目前執行的 Python 函式的堆疊。給定一個由 @ref{5d7,,PyObject}* 指標表示的 Python 物件，擴充功能會顯示該物件的型別和值。

正在開發 CPython 擴充功能或修補用 C 編寫之 CPython 部分的開發人員可以使用本文件來學習如何將 @code{python-gdb.py} 擴充功能與 GDB 一起使用。

@cartouche
@quotation 備註 
本文件假設你熟悉 GDB 和 CPython C API 的基礎知識。它整合了 devguide@footnote{https://devguide.python.org} 和 Python wiki@footnote{https://wiki.python.org/moin/DebuggingWithGdb} 的指引。
@end quotation
@end cartouche

@menu
* 先決條件:: 
* 使用偵錯建置與使用開發模式:: 
* 使用 python-gdb 擴充功能:: 
* 與 GDB 指令一起使用:: 

@end menu

@node 先決條件,使用偵錯建置與使用開發模式,,使用 GDB 來為 C API 擴充功能和 CPython 內部偵錯
@anchor{howto/gdb_helpers prerequisites}@anchor{5461}
@subsection 先決條件


你需要有：


@itemize -

@item 
GDB 7 或更之後的版本。（對於早期版本的 GDB，請參閱 Python 3.11 或更早版本的原始程式碼中的 @code{Misc/gdbinit}。）

@item 
對 Python 和你在偵錯的任何擴充功能來說的與 GDB 相容的偵錯資訊。

@item 
@code{python-gdb.py} 擴充。
@end itemize

該擴充功能是用 Python 建置的，但可能會單獨發布或根本不發布。以下我們將一些常見系統的提示作為範例。請注意，即使說明與你的系統匹配，它們也可能已過時。

@menu
* 使用從原始碼建置的 Python 進行設定:: 
* 從 Linux 發行版設定 Python:: 

@end menu

@node 使用從原始碼建置的 Python 進行設定,從 Linux 發行版設定 Python,,先決條件
@anchor{howto/gdb_helpers setup-with-python-built-from-source}@anchor{5462}
@subsubsection 使用從原始碼建置的 Python 進行設定


當你從原始程式碼建立 CPython 時，偵錯資訊應該可用，並且建置應該將 @code{python-gdb.py} 檔案新增至儲存庫的根目錄中。

若要啟用支援，你必須將包含 @code{python-gdb.py} 的目錄新增至 GDB 的 "auto-load-safe-path"。如果你還沒有這樣做，最新版本的 GDB 將列印警告，其中包含有關如何執行此操作的說明。

@cartouche
@quotation 備註 
如果你沒有看到適合你的 GDB 版本的說明，請將其放入你的設定檔中（@code{~/.gdbinit} 或 @code{~/.config/gdb/gdbinit}）：

@example
add-auto-load-safe-path /path/to/cpython
@end example

你也可以新增多個路徑，要以 @code{:} 分隔。
@end quotation
@end cartouche

@node 從 Linux 發行版設定 Python,,使用從原始碼建置的 Python 進行設定,先決條件
@anchor{howto/gdb_helpers setup-for-python-from-a-linux-distro}@anchor{5463}
@subsubsection 從 Linux 發行版設定 Python


大多數 Linux 系統在名為 @code{python-debuginfo}、@code{python-dbg} 或類似的套件中提供系統 Python 的偵錯資訊。例如：


@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

在最近的幾個 Linux 系統上，GDB 可以使用 `debuginfod' 自動下載偵錯符號。但是這不會安裝 @code{python-gdb.py} 擴充功能；你通常需要另外安裝偵錯資訊套件。

@node 使用偵錯建置與使用開發模式,使用 python-gdb 擴充功能,先決條件,使用 GDB 來為 C API 擴充功能和 CPython 內部偵錯
@anchor{howto/gdb_helpers using-the-debug-build-and-development-mode}@anchor{5464}
@subsection 使用偵錯建置與使用開發模式


為了更輕鬆地進行偵錯，你可能需要：


@itemize -

@item 
使用 Python 的@ref{504,,偵錯建置}。（從原始碼建置時，請使用 @code{configure --with-pydebug}。在 Linux 發行版上，安裝並執行諸如 @code{python-debug} 或 @code{python-dbg} 之類的套件（如果可用））。

@item 
使用 runtime @ref{503,,開發模式} (@code{-X dev})。
@end itemize

兩者都啟用額外的斷言 (assertion) 並停用一些最佳化。有時這會隱藏你試圖想尋找的錯誤，但在大多數情況下，它們會使過程變得更容易。

@node 使用 python-gdb 擴充功能,與 GDB 指令一起使用,使用偵錯建置與使用開發模式,使用 GDB 來為 C API 擴充功能和 CPython 內部偵錯
@anchor{howto/gdb_helpers using-the-python-gdb-extension}@anchor{5465}
@subsection 使用 @code{python-gdb} 擴充功能


載入擴充功能後，它提供兩個主要功能：Python 值的漂亮列印器和附加命令。

@menu
* 漂亮列印器:: 
* py-list:: 
* py-up 和 py-down:: 
* py-bt:: 
* py-print:: 
* py-locals:: 

@end menu

@node 漂亮列印器,py-list,,使用 python-gdb 擴充功能
@anchor{howto/gdb_helpers pretty-printers}@anchor{5466}
@subsubsection 漂亮列印器


這是啟用此擴充功能時 GDB 回溯 (backtrace) 的樣子（有被截斷）：

@example
#0  0x000000000041a6b1 in PyObject_Malloc (nbytes=Cannot access memory at address 0x7fffff7fefe8
) at Objects/obmalloc.c:748
#1  0x000000000041b7c0 in _PyObject_DebugMallocApi (id=111 'o', nbytes=24) at Objects/obmalloc.c:1445
#2  0x000000000041b717 in _PyObject_DebugMalloc (nbytes=24) at Objects/obmalloc.c:1412
#3  0x000000000044060a in _PyUnicode_New (length=11) at Objects/unicodeobject.c:346
#4  0x00000000004466aa in PyUnicodeUCS2_DecodeUTF8Stateful (s=0x5c2b8d "__lltrace__", size=11, errors=0x0, consumed=
    0x0) at Objects/unicodeobject.c:2531
#5  0x0000000000446647 in PyUnicodeUCS2_DecodeUTF8 (s=0x5c2b8d "__lltrace__", size=11, errors=0x0)
    at Objects/unicodeobject.c:2495
#6  0x0000000000440d1b in PyUnicodeUCS2_FromStringAndSize (u=0x5c2b8d "__lltrace__", size=11)
    at Objects/unicodeobject.c:551
#7  0x0000000000440d94 in PyUnicodeUCS2_FromString (u=0x5c2b8d "__lltrace__") at Objects/unicodeobject.c:569
#8  0x0000000000584abd in PyDict_GetItemString (v=
    @{'Yuck': <type at remote 0xad4730>, '__builtins__': <module at remote 0x7ffff7fd5ee8>, '__file__': 'Lib/test/crashers/nasty_eq_vs_dict.py', '__package__': None, 'y': <Yuck(i=0) at remote 0xaacd80>, 'dict': @{0: 0, 1: 1, 2: 2, 3: 3@}, '__cached__': None, '__name__': '__main__', 'z': <Yuck(i=0) at remote 0xaace60>, '__doc__': None@}, key=
    0x5c2b8d "__lltrace__") at Objects/dictobject.c:2171
@end example

請注意 @code{PyDict_GetItemString} 的字典引數如何顯示為其 @code{repr()}，而不是不透明的 @code{PyObject *} 指標。

該擴充功能透過為 @code{PyObject *} 型別的值提供自訂列印例程來運作。如果需要存取物件較低階的詳細資訊，請將值轉換為適當型別的指標。例如：

@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

請注意，漂亮列印器其實並不呼叫 @code{repr()}。對於基本型別，他們嘗試緊密匹配其結果。

一個可能令人困惑的地方是，某些型別的自訂列印器看起來很像 GDB 標準類型的內建列印器。例如，Python @code{int} (@ref{39c,,PyLongObject}*) 的漂亮列印器給出的表示法無法與常規機器層級整數之其一區分：

@example
(gdb) p some_machine_integer
$3 = 42

(gdb) p some_python_integer
$4 = 42
@end example

可以透過轉換 (cast) 為 @ref{39c,,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

使用 @code{str} 型別時也可能會出現類似的困惑，其中的輸出看起來很像對於 @code{char *} 的 gdb 內建列印器 ：

@example
(gdb) p ptr_to_python_str
$6 = '__builtins__'
@end example

@code{str} 實例的漂亮列印器預設使用單引號（Python 的 @code{repr} 對於字串也是如此），而 @code{char *} 值的標準列印器使用雙引號並包含十六進位位址：

@example
(gdb) p ptr_to_char_star
$7 = 0x6d72c0 "hello world"
@end example

同樣，可以透過轉換為 @ref{98f,,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 和 py-down,漂亮列印器,使用 python-gdb 擴充功能
@anchor{howto/gdb_helpers py-list}@anchor{5467}
@subsubsection @code{py-list}


@quotation

該擴充功能新增了一個 @code{py-list} 命令，該命令列出了所選執行緒中目前 frame 的 Python 原始程式碼（如果有）。目前的列會標有 ">"：

@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

使用 @code{py-list START} 列出 Python 原始碼中不同的列號，使用 @code{py-list START,END} 列出 Python 原始碼中特定範圍的列。
@end quotation

@node py-up 和 py-down,py-bt,py-list,使用 python-gdb 擴充功能
@anchor{howto/gdb_helpers py-up-and-py-down}@anchor{5468}
@subsubsection @code{py-up} 和 @code{py-down}


@quotation

@code{py-up} 和 @code{py-down} 命令類似於 GDB 的常規 @code{up} 和 @code{down} 命令，但嘗試在 CPython frame 層級移動，而不是 C frame。

GDB 並不總是能夠讀取相關的 frame 資訊，這取決於編譯 CPython 的最佳化等級。在內部，這些指令會尋找正在執行預設 frame 計算 (evaluation) 函式（即 CPython 中迴圈的核心位元組碼直譯器）的 C frame，並尋找相關 @code{PyFrameObject *} 的值。

它們在執行緒內發出（於 C 層級的）frame 編號。

例如：

@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

所以現在我們處於 Python 堆疊的頂端。

frame 編號與 GDB 標準 @code{backtrace} 指令顯示的 frame 編號相對應。此指令會跳過不執行 Python 程式碼的 C frame。

回到下面：

@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

我們現在處於 Python 堆疊的底部。

請注意，在 Python 3.12 及更高版本中，同一個 C 堆疊 frame 可用於多個 Python 堆疊 frame。這意味著 @code{py-up} 和 @code{py-down} 可以一次移動多個 Python frame。例如：

@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 和 py-down,使用 python-gdb 擴充功能
@anchor{howto/gdb_helpers py-bt}@anchor{5469}
@subsubsection @code{py-bt}


@quotation

@code{py-bt} 指令嘗試顯示目前執行緒的 Python 層級回溯。

例如：

@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,使用 python-gdb 擴充功能
@anchor{howto/gdb_helpers py-print}@anchor{546a}
@subsubsection @code{py-print}


@quotation

@code{py-print} 命令查找 Python 名稱並嘗試列印它。它在目前執行緒中尋找局部變數，然後是全域變數，最後是內建變數：

@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

如果目前 C frame 對應多個 Python frame，則 @code{py-print} 僅考慮第一個。
@end quotation

@node py-locals,,py-print,使用 python-gdb 擴充功能
@anchor{howto/gdb_helpers py-locals}@anchor{546b}
@subsubsection @code{py-locals}


@quotation

@code{py-locals} 命令尋找所選執行緒中目前 Python frame 內的所有 Python 局部變數，並列印它們的表示：

@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

如果目前 C frame 對應於多個 Python frame，則會顯示所有這些 frame 的局部變數：

@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 與 GDB 指令一起使用,,使用 python-gdb 擴充功能,使用 GDB 來為 C API 擴充功能和 CPython 內部偵錯
@anchor{howto/gdb_helpers use-with-gdb-commands}@anchor{546c}
@subsection 與 GDB 指令一起使用


擴充命令補充了 GDB 的內建命令。例如，你可以將 @code{py-bt} 顯示的 frame 編號與 @code{frame} 命令一同使用來跳到所選執行緒中的特定 frame，如下所示：

@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        # 在暫時改變 CWD 到一個臨時且可寫入的目錄的
1544        # 情境管理器中運行測試。
1545        # 如果無法建立或更改 CWD，則使用原始的 CWD。
1546        # 原始 CWD 可從 test_support.SAVEDCWD 獲得。
1547        with test_support.temp_cwd(TESTCWD, quiet=True):
>1548            main()
@end example

@code{info threads} 命令將為你提供行程內的執行緒串列，你可以使用 @code{thread} 命令選擇不同的執行緒：

@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

你可以使用 @code{thread apply all COMMAND}（或簡短地用 @code{t a a COMMAND}）在所有執行緒上執行命令。使用 @code{py-bt} 你可以看到每個執行緒在 Python 層級正在做什麼：

@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,函式程式設計 HOWTO,使用 GDB 來為 C API 擴充功能和 CPython 內部偵錯,Python 如何達成任務
@anchor{howto/enum doc}@anchor{546d}@anchor{howto/enum enum-howto}@anchor{546e}@anchor{howto/enum id1}@anchor{546f}@anchor{howto/enum translation-repo}@anchor{5470}
@section Enum HOWTO

@anchor{howto/enum enum-basic-tutorial}@anchor{28d5}
An @ref{83b,,Enum} is a set of symbolic names bound to unique values.  They are
similar to global variables, but they offer a more useful @ref{1c1,,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{83b,,Enum} is as simple as writing a class that
inherits from @ref{83b,,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>>> 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{1fa,,datetime.date}
has two methods for returning the weekday:
@ref{276d,,weekday()} and @ref{276e,,isoweekday()}.
The difference is that one of them counts from 0-6 and the other from 1-7.
Rather than keep track of that ourselves we can add a method to the @code{Weekday}
enum to extract the day from the @ref{1fa,,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
>>> from datetime import date
>>> Weekday.from_date(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{24d,,list} -- we could use a different type
of @ref{83b,,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{82e,,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{82e,,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{82e,,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{e96,,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:: 
* 比較:: 
* Allowed members and attributes of enumerations:: 
* Restricted Enum subclassing:: 
* Dataclass support:: 
* Pickling:: 
* Functional API: Functional API<3>. 
* Derived Enumerations:: 
* When to use __new__() vs. __init__(): When to use __new__ vs __init__. 
* Enums 和 Flags 有何不同？:: 
* Enum Cookbook:: 
* 子類別化 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{28d6}@anchor{howto/enum programmatic-access-to-enumeration-members-and-their-attributes}@anchor{5471}
@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{5472}
@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{5473}
@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{28db,,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,Ensuring unique enumeration values,Enum HOWTO
@anchor{howto/enum using-automatic-values}@anchor{5474}
@subsection Using automatic values


If the exact value is unimportant you can use @ref{e96,,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{28ef,,_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{28ef,,_generate_next_value_()} method must be defined before any members.
@end quotation
@end cartouche

@node Iteration,比較,Using automatic values,Enum HOWTO
@anchor{howto/enum iteration}@anchor{5475}
@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 比較,Allowed members and attributes of enumerations,Iteration,Enum HOWTO
@anchor{howto/enum comparisons}@anchor{5476}
@subsection 比較


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{5477,,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

Comparisons against non-enumeration values will always compare not equal
(again, @ref{ed6,,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,比較,Enum HOWTO
@anchor{howto/enum allowed-members-and-attributes-of-enumerations}@anchor{5478}
@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{5479,,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

然後：

@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{829,,__str__()},
@ref{228f,,__add__()}, etc.), descriptors (methods are also descriptors), and
variable names listed in @ref{28ed,,_ignore_}.

Note:  if your enumeration defines @ref{799,,__new__()} and/or @ref{8b7,,__init__()},
any value(s) given to the enum member will be passed into those methods.
See @ref{547a,,Planet} for an example.

@cartouche
@quotation 備註 
The @ref{799,,__new__()} method, if defined, is used during creation of the Enum
members; it is then replaced by Enum's @ref{799,,__new__()} which is used after
class creation for lookup of existing members.  See @ref{547b,,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{547c}
@subsection Restricted Enum subclassing


A new @ref{83b,,Enum} class must have one base enum class, up to one concrete
data type, and as many @ref{c75,,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

但這是允許的：

@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{547d,,OrderedEnum} for an example.)

@node Dataclass support,Pickling,Restricted Enum subclassing,Enum HOWTO
@anchor{howto/enum dataclass-support}@anchor{547e}@anchor{howto/enum enum-dataclass-support}@anchor{1a3f}
@subsection Dataclass support


When inheriting from a @ref{4dc,,dataclass},
the @ref{1a40,,__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{4dc,,dataclass()} argument @code{repr=False}
to use the standard @ref{1c1,,repr()}.


在 3.12 版的變更: Only the dataclass fields are shown in the value area, not the dataclass'
name.


@cartouche
@quotation 備註 
Adding @ref{4dc,,dataclass()} decorator to @ref{83b,,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               # 不要這樣做，這並不合理
... class Color(Enum):
...    RED = 1
...    BLUE = 2
...
>>> Color.RED is Color.BLUE
False
>>> Color.RED == Color.BLUE  # 問題在此：它們不應該相等
True
@end example
@end quotation
@end cartouche

@node Pickling,Functional API<3>,Dataclass support,Enum HOWTO
@anchor{howto/enum pickling}@anchor{547f}
@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{18d2,,__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<3>,Derived Enumerations,Pickling,Enum HOWTO
@anchor{howto/enum functional-api}@anchor{5479}
@subsection Functional API


The @ref{83b,,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{4db,,namedtuple}. The first
argument of the call to @ref{83b,,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{83b,,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{2225,,__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<3>,Enum HOWTO
@anchor{howto/enum derived-enumerations}@anchor{5480}
@subsection Derived Enumerations


@menu
* IntEnum:: 
* StrEnum:: 
* IntFlag:: 
* Flag:: 
* 其他: 其他<2>. 

@end menu

@node IntEnum,StrEnum,,Derived Enumerations
@anchor{howto/enum intenum}@anchor{5477}
@subsubsection IntEnum


The first variation of @ref{83b,,Enum} that is provided is also a subclass of
@ref{19b,,int}.  Members of an @ref{ed6,,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{83b,,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{ed6,,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{5481}
@subsubsection StrEnum


The second variation of @ref{83b,,Enum} that is provided is also a subclass of
@ref{169,,str}.  Members of a @ref{826,,StrEnum} can be compared to strings;
by extension, string enumerations of different types can also be compared
to each other.


在 3.11 版被加入.


@node IntFlag,Flag,StrEnum,Derived Enumerations
@anchor{howto/enum intflag}@anchor{5482}
@subsubsection IntFlag


The next variation of @ref{83b,,Enum} provided, @ref{e95,,IntFlag}, is also based
on @ref{19b,,int}.  The difference being @ref{e95,,IntFlag} members can be combined
using the bitwise operators (&, |, ^, ~) and the result is still an
@ref{e95,,IntFlag} member, if possible.  Like @ref{ed6,,IntEnum}, @ref{e95,,IntFlag}
members are also integers and can be used wherever an @ref{19b,,int} is used.

@cartouche
@quotation 備註 
Any operation on an @ref{e95,,IntFlag} member besides the bit-wise operations will
lose the @ref{e95,,IntFlag} membership.

Bit-wise operations that result in invalid @ref{e95,,IntFlag} values will lose the
@ref{e95,,IntFlag} membership.  See @ref{82f,,FlagBoundary} for
details.
@end quotation
@end cartouche


在 3.6 版被加入.



在 3.11 版的變更.


Sample @ref{e95,,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{e95,,IntFlag} and @ref{83b,,Enum} is that
if no flags are set (the value is 0), its boolean evaluation is @ref{d23,,False}:

@example
>>> Perm.R & Perm.X
<Perm: 0>
>>> bool(Perm.R & Perm.X)
False
@end example

Because @ref{e95,,IntFlag} members are also subclasses of @ref{19b,,int} they can
be combined with them (but may lose @ref{e95,,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{e95,,IntFlag} member with a
positive value:

@example
>>> (~Perm.X).value == (Perm.R|Perm.W).value == 6
True
@end example
@end quotation
@end cartouche

@ref{e95,,IntFlag} 成員也可以被疊代：

@example
>>> list(RW)
[<Perm.R: 4>, <Perm.W: 2>]
@end example


在 3.11 版被加入.


@node Flag,其他<2>,IntFlag,Derived Enumerations
@anchor{howto/enum flag}@anchor{5483}
@subsubsection Flag


The last variation is @ref{82e,,Flag}.  Like @ref{e95,,IntFlag}, @ref{82e,,Flag}
members can be combined using the bitwise operators (&, |, ^, ~).  Unlike
@ref{e95,,IntFlag}, they cannot be combined with, nor compared against, any
other @ref{82e,,Flag} enumeration, nor @ref{19b,,int}.  While it is possible to
specify the values directly it is recommended to use @ref{e96,,auto} as the
value and let @ref{82e,,Flag} select an appropriate value.


在 3.6 版被加入.


Like @ref{e95,,IntFlag}, if a combination of @ref{82e,,Flag} members results in no
flags being set, the boolean evaluation is @ref{d23,,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{82e,,Flag} 成員也可以被疊代：

@example
>>> purple = Color.RED | Color.BLUE
>>> list(purple)
[<Color.RED: 1>, <Color.BLUE: 2>]
@end example


在 3.11 版被加入.


@cartouche
@quotation 備註 
For the majority of new code, @ref{83b,,Enum} and @ref{82e,,Flag} are strongly
recommended, since @ref{ed6,,IntEnum} and @ref{e95,,IntFlag} break some
semantic promises of an enumeration (by being comparable to integers, and
thus by transitivity to other unrelated enumerations).  @ref{ed6,,IntEnum}
and @ref{e95,,IntFlag} should be used only in cases where @ref{83b,,Enum} and
@ref{82e,,Flag} will not do; for example, when integer constants are replaced
with enumerations, or for interoperability with other systems.
@end quotation
@end cartouche

@node 其他<2>,,Flag,Derived Enumerations
@anchor{howto/enum others}@anchor{5484}
@subsubsection 其他


While @ref{ed6,,IntEnum} is part of the @ref{5a,,enum} module, it would be very
simple to implement independently:

@example
class IntEnum(int, ReprEnum):   # 或用 Enum 取代 ReprEnum
    pass
@end example

This demonstrates how similar derived enumerations can be defined; for example
a @code{FloatEnum} that mixes in @ref{196,,float} instead of @ref{19b,,int}.

一些規則：


@enumerate 

@item 
When subclassing @ref{83b,,Enum}, mix-in types must appear before the
@ref{83b,,Enum} class itself in the sequence of bases, as in the @ref{ed6,,IntEnum}
example above.

@item 
Mix-in types must be subclassable. For example, @ref{3c1,,bool} and
@ref{b34,,range} are not subclassable and will throw an error during Enum
creation if used as the mix-in type.

@item 
While @ref{83b,,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{19b,,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{28e8,,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{799,,__new__()}, or a
@ref{4dc,,dataclass}

@item 
%-style formatting:  @code{%s} and @code{%r} call the @ref{83b,,Enum} class's
@ref{829,,__str__()} and @ref{828,,__repr__()} respectively; other codes (such as
@code{%i} or @code{%h} for IntEnum) treat the enum member as its mixed-in type.

@item 
@ref{19a,,Formatted string literals}, @ref{82c,,str.format()},
and @ref{199,,format()} will use the enum's @ref{829,,__str__()} method.
@end enumerate

@cartouche
@quotation 備註 
Because @ref{ed6,,IntEnum}, @ref{e95,,IntFlag}, and @ref{826,,StrEnum} are
designed to be drop-in replacements for existing constants, their
@ref{829,,__str__()} method has been reset to their data types'
@ref{829,,__str__()} method.
@end quotation
@end cartouche

@node When to use __new__ vs __init__,Enums 和 Flags 有何不同？,Derived Enumerations,Enum HOWTO
@anchor{howto/enum new-vs-init}@anchor{547b}@anchor{howto/enum when-to-use-new-vs-init}@anchor{5485}
@subsection When to use @code{__new__()} vs. @code{__init__()}


@ref{799,,__new__()} must be used whenever you want to customize the actual value of
the @ref{83b,,Enum} member.  Any other modifications may go in either
@ref{799,,__new__()} or @ref{8b7,,__init__()}, with @ref{8b7,,__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

@menu
* Finer Points:: 

@end menu

@node Finer Points,,,When to use __new__ vs __init__
@anchor{howto/enum finer-points}@anchor{5486}
@subsubsection Finer Points


@menu
* 有支援的 __dunder__ 名稱:: 
* 有支援的 _sunder_ 名稱:: 
* _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:: 
* Flag 的成員組合:: 
* Flag and IntFlag minutia:: 

@end menu

@node 有支援的 __dunder__ 名稱,有支援的 _sunder_ 名稱,,Finer Points
@anchor{howto/enum supported-dunder-names}@anchor{5487}
@subsubsection 有支援的 @code{__dunder__} 名稱


@ref{28e5,,__members__} is a read-only ordered mapping of @code{member_name}:@code{member}
items.  It is only available on the class.

@ref{799,,__new__()}, if specified, must create and return the enum members; it is
also a very good idea to set the member's @ref{28eb,,_value_} appropriately.  Once
all the members are created it is no longer used.

@node 有支援的 _sunder_ 名稱,_Private__names,有支援的 __dunder__ 名稱,Finer Points
@anchor{howto/enum supported-sunder-names}@anchor{5488}
@subsubsection 有支援的 @code{_sunder_} 名稱



@itemize -

@item 
@ref{28ea,,_name_} -- 成員的名稱

@item 
@ref{28eb,,_value_} -- value of the member; can be set in @code{__new__}

@item 
@ref{28f2,,_missing_()} -- a lookup function used when a value is not found;
may be overridden

@item 
@ref{28ed,,_ignore_} -- a list of names, either as a @ref{24d,,list} or a
@ref{169,,str}, that will not be transformed into members, and will be removed
from the final class

@item 
@ref{28ef,,_generate_next_value_()} -- used to get an appropriate value for
an enum member; may be overridden

@item 
@ref{28f3,,_add_alias_()} -- adds a new name as an alias to an existing
member.

@item 
@ref{28f4,,_add_value_alias_()} -- adds a new value as an alias to an
existing member.  See @ref{5489,,MultiValueEnum} for an example.

@cartouche
@quotation 備註 
For standard @ref{83b,,Enum} classes the next value chosen is the highest
value seen incremented by one.

For @ref{82e,,Flag} classes the next value chosen will be the next highest
power-of-two.
@end quotation
@end cartouche


在 3.13 版的變更: Prior versions would use the last seen value instead of the highest value.

@end itemize


在 3.6 版被加入: @code{_missing_}、@code{_order_}、@code{_generate_next_value_}



在 3.7 版被加入: @code{_ignore_}



在 3.13 版被加入: @code{_add_alias_}、@code{_add_value_alias_}


To help keep Python 2 / Python 3 code in sync an @ref{28ec,,_order_} attribute can
be provided.  It will be checked against the actual order of the enumeration
and raise an error if the two do not match:

@example
>>> class Color(Enum):
...     _order_ = 'RED GREEN BLUE'
...     RED = 1
...     BLUE = 3
...     GREEN = 2
...
Traceback (most recent call last):
...
TypeError: member order does not match _order_:
  ['RED', 'BLUE', 'GREEN']
  ['RED', 'GREEN', 'BLUE']
@end example

@cartouche
@quotation 備註 
In Python 2 code the @ref{28ec,,_order_} attribute is necessary as definition
order is lost before it can be recorded.
@end quotation
@end cartouche

@node _Private__names,Enum member type,有支援的 _sunder_ 名稱,Finer Points
@anchor{howto/enum private-names}@anchor{548a}
@subsubsection _Private__names


@ref{1f6a,,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{548b}
@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{548c}
@subsubsection Creating members that are mixed with other data types


When subclassing other data types, such as @ref{19b,,int} or @ref{169,,str}, with
an @ref{83b,,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      # 所以 x='11' 且 base=16
...
>>> MyEnum.example.value        # 且 hex(11) 為...
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{548d}
@subsubsection Boolean value of @code{Enum} classes and members


Enum classes that are mixed with non-@ref{83b,,Enum} types (such as
@ref{19b,,int}, @ref{169,,str}, etc.) are evaluated according to the mixed-in
type's rules; otherwise, all members evaluate as @ref{e02,,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{83b,,Enum} classes always evaluate as @ref{e02,,True}.

@node Enum classes with methods,Flag 的成員組合,Boolean value of Enum classes and members,Finer Points
@anchor{howto/enum enum-classes-with-methods}@anchor{548e}
@subsubsection @code{Enum} classes with methods


If you give your enum subclass extra methods, like the @ref{547a,,Planet}
class below, those methods will show up in a @ref{83d,,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 Flag 的成員組合,Flag and IntFlag minutia,Enum classes with methods,Finer Points
@anchor{howto/enum combining-members-of-flag}@anchor{548f}
@subsubsection @code{Flag} 的成員組合


Iterating over a combination of @ref{82e,,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,,Flag 的成員組合,Finer Points
@anchor{howto/enum flag-and-intflag-minutia}@anchor{5490}
@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  # 效果為 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)  # 或 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 --> 當遇到無效值時引發例外

@item 
CONFORM --> 捨棄任何無效位元

@item 
EJECT --> 失去 Flag 狀態並成為具有給定值的普通 int

@item 
KEEP --> 保留額外位元


@itemize -

@item 
保留 Flag 狀態和額外位元

@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 Enums 和 Flags 有何不同？,Enum Cookbook,When to use __new__ vs __init__,Enum HOWTO
@anchor{howto/enum enum-class-differences}@anchor{28d8}@anchor{howto/enum how-are-enums-and-flags-different}@anchor{5491}
@subsection Enums 和 Flags 有何不同？


Enums have a custom metaclass that affects many aspects of both derived @ref{83b,,Enum}
classes and their instances (members).

@menu
* Enum 類別:: 
* Flag 類別:: 
* Enum Members (aka instances): Enum Members aka instances. 
* Flag 成員:: 

@end menu

@node Enum 類別,Flag 類別,,Enums 和 Flags 有何不同？
@anchor{howto/enum enum-classes}@anchor{5492}
@subsubsection Enum 類別


The @ref{4f2,,EnumType} metaclass is responsible for providing the
@ref{15b1,,__contains__()}, @ref{176b,,__dir__()}, @ref{e64,,__iter__()} and other methods that
allow one to do things with an @ref{83b,,Enum} class that fail on a typical
class, such as @code{list(Color)} or @code{some_enum_var in Color}.  @ref{4f2,,EnumType} is
responsible for ensuring that various other methods on the final @ref{83b,,Enum}
class are correct (such as @ref{799,,__new__()}, @ref{fcf,,__getnewargs__()},
@ref{829,,__str__()} and @ref{828,,__repr__()}).

@node Flag 類別,Enum Members aka instances,Enum 類別,Enums 和 Flags 有何不同？
@anchor{howto/enum flag-classes}@anchor{5493}
@subsubsection Flag 類別


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{83b,,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 成員,Flag 類別,Enums 和 Flags 有何不同？
@anchor{howto/enum enum-members-aka-instances}@anchor{5494}
@subsubsection Enum Members (aka instances)


The most interesting thing about enum members is that they are singletons.
@ref{4f2,,EnumType} creates them all while it is creating the enum class itself,
and then puts a custom @ref{799,,__new__()} in place to ensure that no new ones are
ever instantiated by returning only the existing member instances.

@node Flag 成員,,Enum Members aka instances,Enums 和 Flags 有何不同？
@anchor{howto/enum flag-members}@anchor{5495}
@subsubsection Flag 成員


Flag members can be iterated over just like the @ref{82e,,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,子類別化 EnumType,Enums 和 Flags 有何不同？,Enum HOWTO
@anchor{howto/enum enum-cookbook}@anchor{28d7}@anchor{howto/enum id2}@anchor{5496}
@subsection Enum Cookbook


While @ref{83b,,Enum}, @ref{ed6,,IntEnum}, @ref{826,,StrEnum}, @ref{82e,,Flag}, and
@ref{e95,,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
* 省略值:: 
* OrderedEnum:: 
* DuplicateFreeEnum:: 
* MultiValueEnum:: 
* Planet:: 
* TimePeriod:: 

@end menu

@node 省略值,OrderedEnum,,Enum Cookbook
@anchor{howto/enum omitting-values}@anchor{5497}
@subsubsection 省略值


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{e96,,auto} for the value

@item 
use instances of @ref{c75,,object} as the value

@item 
use a descriptive string as the value

@item 
use a tuple as the value and a custom @ref{799,,__new__()} to replace the
tuple with an @ref{19b,,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
* 使用 auto:: 
* 使用 object:: 
* Using a descriptive string:: 
* 使用自訂的 __new__(): 使用自訂的 __new__. 

@end menu

@node 使用 auto,使用 object,,省略值
@anchor{howto/enum using-auto}@anchor{5498}
@subsubsection 使用 @code{auto}


使用 @ref{e96,,auto} 會像這樣：

@example
>>> class Color(Enum):
...     RED = auto()
...     BLUE = auto()
...     GREEN = auto()
...
>>> Color.GREEN
<Color.GREEN: 3>
@end example

@node 使用 object,Using a descriptive string,使用 auto,省略值
@anchor{howto/enum using-object}@anchor{5499}
@subsubsection 使用 @code{object}


使用 @ref{c75,,object} 會像這樣：

@example
>>> class Color(Enum):
...     RED = object()
...     GREEN = object()
...     BLUE = object()
...
>>> Color.GREEN
<Color.GREEN: <object object at 0x...>>
@end example

This is also a good example of why you might want to write your own
@ref{828,,__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,使用自訂的 __new__,使用 object,省略值
@anchor{howto/enum using-a-descriptive-string}@anchor{549a}
@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 使用自訂的 __new__,,Using a descriptive string,省略值
@anchor{howto/enum using-a-custom-new}@anchor{549b}
@subsubsection 使用自訂的 @code{__new__()}


Using an auto-numbering @ref{799,,__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):      # 這是和上面相比唯一的變更
...         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{799,,__new__()} method, if defined, is used during creation of the Enum
members; it is then replaced by Enum's @ref{799,,__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,省略值,Enum Cookbook
@anchor{howto/enum orderedenum}@anchor{547d}
@subsubsection OrderedEnum


An ordered enumeration that is not based on @ref{ed6,,IntEnum} and so maintains
the normal @ref{83b,,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{549c}
@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{28db,,unique()} decorator can be used instead.
@end quotation
@end cartouche

@node MultiValueEnum,Planet,DuplicateFreeEnum,Enum Cookbook
@anchor{howto/enum multivalueenum}@anchor{5489}
@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{547a}
@subsubsection Planet


If @ref{799,,__new__()} or @ref{8b7,,__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       # 以公斤表示
...         self.radius = radius   # 以公尺表示
...     @@property
...     def surface_gravity(self):
...         # 萬有引力常數  (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{28ee}@anchor{howto/enum timeperiod}@anchor{549d}
@subsubsection TimePeriod


An example to show the @ref{28ed,,_ignore_} attribute in use:

@example
>>> from datetime import timedelta
>>> class Period(timedelta, Enum):
...     "不同長度的時間"
...     _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 子類別化 EnumType,,Enum Cookbook,Enum HOWTO
@anchor{howto/enum enumtype-examples}@anchor{28de}@anchor{howto/enum subclassing-enumtype}@anchor{549e}
@subsection 子類別化 EnumType


While most enum needs can be met by customizing @ref{83b,,Enum} subclasses,
either with class decorators or custom functions, @ref{4f2,,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 函式程式設計 HOWTO,如何使用 Logging 模組,Enum HOWTO,Python 如何達成任務
@anchor{howto/functional doc}@anchor{549f}@anchor{howto/functional functional-howto}@anchor{54a0}@anchor{howto/functional functional-programming-howto}@anchor{54a1}@anchor{howto/functional translation-repo}@anchor{54a2}
@section 函式程式設計 HOWTO


@*作者: 
A. M. Kuchling


@*發佈版本: 
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{4c3,,iterator}s and @ref{125c,,generator}s and relevant library modules such as
@ref{85,,itertools} and @ref{63,,functools}.

@menu
* 簡介: 簡介<11>. 
* 疊代器:: 
* 產生器運算式與串列綜合運算式:: 
* 產生器:: 
* 內建函式: 內建函式<3>. 
* itertools 模組:: 
* functools 模組:: 
* Small functions and the lambda expression:: 
* Revision History and Acknowledgements:: 
* References: References<2>. 

@end menu

@node 簡介<11>,疊代器,,函式程式設計 HOWTO
@anchor{howto/functional introduction}@anchor{54a3}
@subsection 簡介


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{54a4,,疊代器}.

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{1170,,print()} or @ref{8a4,,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 
容易除錯與測試。
@end itemize

@menu
* 形式可證明性:: 
* 模組化:: 
* 容易除錯與測試:: 
* 可組合性:: 

@end menu

@node 形式可證明性,模組化,,簡介<11>
@anchor{howto/functional formal-provability}@anchor{54a5}
@subsubsection 形式可證明性


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 模組化,容易除錯與測試,形式可證明性,簡介<11>
@anchor{howto/functional modularity}@anchor{54a6}
@subsubsection 模組化


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 容易除錯與測試,可組合性,模組化,簡介<11>
@anchor{howto/functional ease-of-debugging-and-testing}@anchor{54a7}
@subsubsection 容易除錯與測試


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 可組合性,,容易除錯與測試,簡介<11>
@anchor{howto/functional composability}@anchor{54a8}
@subsubsection 可組合性


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 疊代器,產生器運算式與串列綜合運算式,簡介<11>,函式程式設計 HOWTO
@anchor{howto/functional functional-howto-iterators}@anchor{54a4}@anchor{howto/functional iterators}@anchor{54a9}
@subsection 疊代器


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{14ce,,__next__()} that takes no arguments and always returns the next
element of the stream.  If there are no more elements in the stream,
@ref{14ce,,__next__()} must raise the @ref{df0,,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{9d0,,iter()} function takes an arbitrary object and tries to return
an iterator that will return the object's contents or elements, raising
@ref{198,,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{1428,,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{348,,for} statement.  In the statement @code{for X in Y},
Y must be an iterator or some object for which @ref{9d0,,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{24d,,list()} or
@ref{60c,,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{1107,,max()} and @ref{1106,,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; @ref{1107,,max()}, @ref{1106,,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{14ce,,__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,,,疊代器
@anchor{howto/functional data-types-that-support-iterators}@anchor{54aa}
@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{9d0,,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{9d0,,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{9ca,,values()} or @ref{9cb,,items()} methods to get an appropriate
iterator.

The @ref{183,,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{1f6d,,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 產生器運算式與串列綜合運算式,產生器,疊代器,函式程式設計 HOWTO
@anchor{howto/functional generator-expressions-and-list-comprehensions}@anchor{54ab}
@subsection 產生器運算式與串列綜合運算式


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{'}]

>>> # 產生器運算式 -- 回傳疊代器
>>> stripped_iter = (line.strip() for line in line_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
# 語法錯誤
[x, y for x in seq1 for y in seq2]
# 正確
[(x, y) for x in seq1 for y in seq2]
@end example

@node 產生器,內建函式<3>,產生器運算式與串列綜合運算式,函式程式設計 HOWTO
@anchor{howto/functional generators}@anchor{54ac}
@subsection 產生器


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.

以下是最簡單的產生器函式範例：

@example
>>> def generate_ints(N):
...    for i in range(N):
...        yield i
@end example

Any function containing a @ref{bb9,,yield} keyword is a generator function;
this is detected by Python's @ref{4a5,,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{1f75,,__next__()} method, the function will resume
executing.

以下是 @code{generate_ints()} 產生器的使用範例：

@example
>>> gen = generate_ints(3)
>>> gen
<generator object generate_ints at ...>
>>> next(gen)
0
>>> next(gen)
1
>>> next(gen)
2
>>> next(gen)
Traceback (most recent call last):
  File "stdin", line 1, in <module>
  File "stdin", line 2, in generate_ints
StopIteration
@end example

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{1f75,,__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{14ce,,__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/3.14/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,,,產生器
@anchor{howto/functional passing-values-into-a-generator}@anchor{54ad}
@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{bb9,,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{22c9,,send(value)} method.  This method resumes the generator's code and the
@code{yield} expression returns the specified value.  If the regular
@ref{1f75,,__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 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{22c9,,send()} method will be the only method used to resume your
generator function.

In addition to @ref{22c9,,send()}, there are two other methods on
generators:


@itemize *

@item 
@ref{715,,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{19b7,,close()} sends a @ref{15bf,,GeneratorExit} exception to the
generator to terminate the iteration.  On receiving this exception, the
generator's code must either raise @ref{15bf,,GeneratorExit} or
@ref{df0,,StopIteration}; catching the exception and doing anything else is
illegal and will trigger a @ref{244,,RuntimeError}.  @ref{19b7,,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{15bf,,GeneratorExit} occurs, I suggest
using a @code{try: ... finally:} suite instead of catching @ref{15bf,,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 內建函式<3>,itertools 模組,產生器,函式程式設計 HOWTO
@anchor{howto/functional built-in-functions}@anchor{54ae}
@subsection 內建函式


Let's look in more detail at built-in functions often used with iterators.

Two of Python's built-in functions, @ref{19f,,map()} and @ref{a5d,,filter()} duplicate the
features of generator expressions:


@table @asis

@item @ref{19f,,map(f@comma{} iterA@comma{} iterB@comma{} ...)} 回傳一個元素為序列的疊代器

@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{a5d,,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 @ref{a5d,,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{1675,,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{1675,,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{dc2,,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{dc3,,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{248a,,排序技法}.)

The @ref{1618,,any(iter)} and @ref{1619,,all(iter)} built-ins look at the
truth values of an iterable's contents.  @ref{1618,,any()} returns @code{True} if any element
in the iterable is a true value, and @ref{1619,,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{1a0,,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 itertools 模組,functools 模組,內建函式<3>,函式程式設計 HOWTO
@anchor{howto/functional the-itertools-module}@anchor{54af}
@subsection itertools 模組


The @ref{85,,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
* 建立新的疊代器:: 
* Calling functions on elements:: 
* Selecting elements:: 
* Combinatoric functions:: 
* Grouping elements:: 

@end menu

@node 建立新的疊代器,Calling functions on elements,,itertools 模組
@anchor{howto/functional creating-new-iterators}@anchor{54b0}
@subsubsection 建立新的疊代器


@ref{1484,,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{2a54,,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{17d9,,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{248b,,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{d3b,,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{2a59,,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,建立新的疊代器,itertools 模組
@anchor{howto/functional calling-functions-on-elements}@anchor{54b1}
@subsubsection Calling functions on elements


The @ref{a3,,operator} module contains a set of functions corresponding to Python's
operators.  Some examples are @ref{2a80,,operator.add(a@comma{} b)} (adds
two values), @ref{2a70,,operator.ne(a@comma{} b)} (same as @code{a != b}), and
@ref{102e,,operator.attrgetter('id')}
(returns a callable that fetches the @code{.id} attribute).

@ref{12e5,,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,itertools 模組
@anchor{howto/functional selecting-elements}@anchor{54b2}
@subsubsection Selecting elements


Another group of functions chooses a subset of an iterator's elements based on a
predicate.

@ref{2477,,itertools.filterfalse(predicate@comma{} iter)} is the
opposite of @ref{a5d,,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{2a58,,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{2a56,,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{1483,,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,itertools 模組
@anchor{howto/functional combinatoric-functions}@anchor{54b3}
@subsubsection Combinatoric functions


The @ref{1512,,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{1bcf,,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{1482,,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,itertools 模組
@anchor{howto/functional grouping-elements}@anchor{54b4}
@subsubsection Grouping elements


The last function I'll discuss, @ref{2a57,,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{2a57,,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{2a57,,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 functools 模組,Small functions and the lambda expression,itertools 模組,函式程式設計 HOWTO
@anchor{howto/functional the-functools-module}@anchor{54b5}
@subsection functools 模組


The @ref{63,,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{217,,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{217,,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.

以下是個很小但實際的範例：

@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{21a,,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.  @ref{21a,,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{198,,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{2a80,,operator.add()} with @ref{21a,,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{68e,,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{21a,,functools.reduce()}, though, it can be clearer to just
write the obvious @ref{348,,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{be7,,itertools.accumulate(iterable@comma{} func=operator.add)}.  It performs the same calculation, but instead of
returning only the final result, @ref{be7,,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
* operator 模組:: 

@end menu

@node operator 模組,,,functools 模組
@anchor{howto/functional the-operator-module}@anchor{54b6}
@subsubsection operator 模組


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 
數學運算：@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,functools 模組,函式程式設計 HOWTO
@anchor{howto/functional small-functions-and-the-lambda-expression}@anchor{54b7}
@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{149e,,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{68e,,sum()} built-in and a generator expression:

@example
total = sum(b for a, b in items)
@end example

Many uses of @ref{21a,,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<2>,Small functions and the lambda expression,函式程式設計 HOWTO
@anchor{howto/functional revision-history-and-acknowledgements}@anchor{54b8}
@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<2>,,Revision History and Acknowledgements,函式程式設計 HOWTO
@anchor{howto/functional references}@anchor{54b9}
@subsection References


@menu
* General:: 
* Python 特有的:: 
* Python 說明文件:: 

@end menu

@node General,Python 特有的,,References<2>
@anchor{howto/functional general}@anchor{54ba}
@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}: 協程 (coroutines) 的條目。

@indicateurl{https://en.wikipedia.org/wiki/Partial_application}: 偏函式 (partial application) 概念的條目。

@indicateurl{https://en.wikipedia.org/wiki/Currying}: currying 概念的條目。

@node Python 特有的,Python 說明文件,General,References<2>
@anchor{howto/functional python-specific}@anchor{54bb}
@subsubsection Python 特有的


@indicateurl{https://gnosis.cx/TPiP/}: The first chapter of David Mertz's book
@cite{Text Processing in Python} discusses functional programming
for text processing, in the section titled "Utilizing Higher-Order Functions in
Text Processing".

Mertz 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 說明文件,,Python 特有的,References<2>
@anchor{howto/functional python-documentation}@anchor{54bc}
@subsubsection Python 說明文件


@ref{85,,itertools} 模組的說明文件。

@ref{63,,functools} 模組的說明文件。

@ref{a3,,operator} 模組的說明文件。

@geindex Python Enhancement Proposals; PEP 289
PEP 289@footnote{https://peps.python.org/pep-0289/}：「產生器運算式 (Generator Expressions)」

@geindex Python Enhancement Proposals; PEP 342
PEP 342@footnote{https://peps.python.org/pep-0342/}: "Coroutines via Enhanced Generators" 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 模組,Logging Cookbook,函式程式設計 HOWTO,Python 如何達成任務
@anchor{howto/logging doc}@anchor{54bd}@anchor{howto/logging id1}@anchor{54be}@anchor{howto/logging logging-howto}@anchor{54bf}@anchor{howto/logging translation-repo}@anchor{54c0}
@section 如何使用 Logging 模組


@*作者: 
Vinay Sajip <vinay_sajip at red-dove dot com>

@anchor{howto/logging logging-basic-tutorial}@anchor{13f6}
This page contains tutorial information. For links to reference information and a
logging cookbook, please see @ref{54c1,,其他資源}.

@menu
* 基礎 Logging 指南:: 
* Advanced Logging Tutorial:: 
* Logging Levels: Logging Levels<2>. 
* Useful Handlers:: 
* Exceptions raised during logging:: 
* Using arbitrary objects as messages:: 
* 最佳化: 最佳化<19>. 
* 其他資源: 其他資源<2>. 

@end menu

@node 基礎 Logging 指南,Advanced Logging Tutorial,,如何使用 Logging 模組
@anchor{howto/logging basic-logging-tutorial}@anchor{54c2}
@subsection 基礎 Logging 指南


軟體執行時，追蹤有什麼事件發生的動作稱為 Logging。軟體開發者會使用 Logging 這樣的機制是因為想知道在運行過程中是否有特定的事件發生。事件會被一段訊息所描述。這段訊息可能包含一些因為此事件發生而改變的資料。開發者也可以指派事件的重要程度，重要程度有時候也會被稱作 `程度' 或是 `嚴重性' 。

@menu
* 什麼時候使用 logging:: 
* 一個簡單範例: 一個簡單範例<2>. 
* Logging to a file:: 
* Logging variable data:: 
* Changing the format of displayed messages:: 
* Displaying the date/time in messages:: 
* Next Steps:: 

@end menu

@node 什麼時候使用 logging,一個簡單範例<2>,,基礎 Logging 指南
@anchor{howto/logging when-to-use-logging}@anchor{54c3}
@subsubsection 什麼時候使用 logging


You can access logging functionality by creating a logger via @code{logger =
getLogger(__name__)}, and then calling the logger's @ref{1026,,debug()},
@ref{3011,,info()}, @ref{19c6,,warning()}, @ref{3013,,error()} and
@ref{1025,,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{1170,,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{3011,,info()} (or
@ref{1026,,debug()} method for very
detailed output for diagnostic
purposes)

@item

Issue a warning regarding a
particular runtime event

@tab

@ref{170d,,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{19c6,,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

引發一個例外

@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{3013,,error()},
@ref{1024,,exception()} or
@ref{1025,,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 一個簡單範例<2>,Logging to a file,什麼時候使用 logging,基礎 Logging 指南
@anchor{howto/logging a-simple-example}@anchor{54c4}@anchor{howto/logging howto-minimal-example}@anchor{54c5}
@subsubsection 一個簡單範例


一個非常簡單的例子是：

@example
import logging
logging.warning('Watch out!')  # 將會印出訊息至控制台
logging.info('I told you so')  # 不會印出任何東西
@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{bea,,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,一個簡單範例<2>,基礎 Logging 指南
@anchor{howto/logging logging-to-a-file}@anchor{54c6}
@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{315,,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 @ref{315,,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{bea,,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{bea,,basicConfig()} should come `before' any calls to a logger's
methods such as @ref{1026,,debug()}, @ref{3011,,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,基礎 Logging 指南
@anchor{howto/logging logging-variable-data}@anchor{54c7}
@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{82c,,str.format()} and @ref{890,,string.Template}. These newer formatting
options `are' supported, but exploring them is outside the scope of this
tutorial: see @ref{3030,,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,基礎 Logging 指南
@anchor{howto/logging changing-the-format-of-displayed-messages}@anchor{54c8}
@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{3010,,LogRecord 屬性}, 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,基礎 Logging 指南
@anchor{howto/logging displaying-the-date-time-in-messages}@anchor{54c9}
@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{13ea,,time.strftime()}.

@node Next Steps,,Displaying the date/time in messages,基礎 Logging 指南
@anchor{howto/logging next-steps}@anchor{54ca}
@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{13f8,,Logging Cookbook}.

@node Advanced Logging Tutorial,Logging Levels<2>,基礎 Logging 指南,如何使用 Logging 模組
@anchor{howto/logging advanced-logging-tutorial}@anchor{54cb}@anchor{howto/logging logging-advanced-tutorial}@anchor{13f7}
@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{11e1,,LogRecord} instance.

Logging is performed by calling methods on instances of the @ref{d3e,,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{3012,,debug()}, @ref{303b,,info()}, @ref{352,,warning()},
@ref{304f,,error()} and @ref{3050,,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{bea,,basicConfig()} as in the
tutorial examples. If you call the functions  @ref{3012,,debug()}, @ref{303b,,info()},
@ref{352,,warning()}, @ref{304f,,error()} and @ref{3050,,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{bea,,basicConfig()} for messages is:

@example
severity:logger name:message
@end example

You can change this by passing a format string to @ref{bea,,basicConfig()} with the
`format' keyword argument. For all options regarding how a format string is
constructed, see @ref{302d,,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{54cc}
@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{54cd}
@subsubsection Loggers


@ref{d3e,,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{1687,,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{300b,,Logger.addHandler()} and @ref{300c,,Logger.removeHandler()} add and remove
handler objects from the logger object.  Handlers are covered in more detail
in @ref{54ce,,Handlers}.

@item 
@ref{3014,,Logger.addFilter()} and @ref{3015,,Logger.removeFilter()} add and remove filter
objects from the logger object.  Filters are covered in more detail in
@ref{3038,,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{1026,,Logger.debug()}, @ref{3011,,Logger.info()}, @ref{19c6,,Logger.warning()},
@ref{3013,,Logger.error()}, and @ref{1025,,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{1024,,Logger.exception()} creates a log message similar to
@ref{3013,,Logger.error()}.  The difference is that @ref{1024,,Logger.exception()} dumps a
stack trace along with it.  Call this method only from an exception handler.

@item 
@ref{1023,,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{b50,,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 @ref{b50,,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{54ce}@anchor{howto/logging handlers}@anchor{54cf}
@subsubsection Handlers


@ref{168a,,Handler} objects are responsible for dispatching the
appropriate log messages (based on the log messages' severity) to the handler's
specified destination.  @ref{d3e,,Logger} objects can add zero or more handler
objects to themselves with an @ref{300b,,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{54d0,,Useful Handlers}); the tutorials use mainly @ref{13f9,,StreamHandler} and
@ref{1b55,,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{3022,,setLevel()} method, just as in logger objects, specifies the
lowest severity that will be dispatched to the appropriate destination.  Why
are there two @ref{3022,,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{3023,,setFormatter()} selects a Formatter object for this handler to
use.

@item 
@ref{3024,,addFilter()} and @ref{3025,,removeFilter()} respectively
configure and deconfigure filter objects on handlers.
@end itemize

Application code should not directly instantiate and use instances of
@ref{168a,,Handler}.  Instead, the @ref{168a,,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{54d1}
@subsubsection Formatters


Formatter objects configure the final order, structure, and contents of the log
message.  Unlike the base @ref{168a,,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{54d2}
@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{3010,,LogRecord 屬性}. If the style is @code{'@{'}, the message
format string is assumed to be compatible with @ref{82c,,str.format()} (using
keyword arguments), while if the style is @code{'$'} then the message format string
should conform to what is expected by @ref{1f9c,,string.Template.substitute()}.


在 3.2 版的變更: 新增 @code{style} 參數。


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{16ed,,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 @ref{16ed,,time.localtime()} or
@ref{13c1,,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{54d3}
@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{d40,,fileConfig()}
function.

@item 
Creating a dictionary of configuration information and passing it
to the @ref{13b1,,dictConfig()} function.
@end enumerate

For the reference documentation on the last two options, see
@ref{14f2,,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{d40,,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 @ref{d40,,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{13b1,,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{308f,,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{14f2,,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{54d4}
@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{13fb,,lastResort}. This internal handler is not associated with any
logger, and acts like a @ref{13f9,,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{13fa,,raiseExceptions} is @code{False} (production mode), the event is
silently dropped.

@item 
If @ref{13fa,,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{13fb,,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{54d5}@anchor{howto/logging library-config}@anchor{308c}
@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{1485,,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{1485,,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 模組
@anchor{howto/logging logging-levels}@anchor{54d6}
@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{11e1,,LogRecord}
class. When a logger decides to actually log an event, a
@ref{11e1,,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{168a,,Handler}
class. Handlers are responsible for ensuring that a logged message (in the form
of a @ref{11e1,,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
@ref{11e1,,LogRecord} instances intended for particular destinations. Each logger
can have zero, one or more handlers associated with it (via the
@ref{300b,,addHandler()} method of @ref{d3e,,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{302b,,emit()} method is used
to send the message to its destination. Most user-defined subclasses of
@ref{168a,,Handler} will need to override this @ref{302b,,emit()}.

@menu
* Custom Levels:: 

@end menu

@node Custom Levels,,,Logging Levels<2>
@anchor{howto/logging custom-levels}@anchor{3054}@anchor{howto/logging id2}@anchor{54d7}
@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 模組
@anchor{howto/logging id3}@anchor{54d8}@anchor{howto/logging useful-handlers}@anchor{54d0}
@subsection Useful Handlers


In addition to the base @ref{168a,,Handler} class, many useful subclasses are
provided:


@enumerate 

@item 
@ref{13f9,,StreamHandler} instances send messages to streams (file-like
objects).

@item 
@ref{1b55,,FileHandler} instances send messages to disk files.

@item 
@ref{3093,,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{18a8,,RotatingFileHandler} or
@ref{115c,,TimedRotatingFileHandler}.

@item 
@ref{18a8,,RotatingFileHandler} instances send messages to disk
files, with support for maximum log file sizes and log file rotation.

@item 
@ref{115c,,TimedRotatingFileHandler} instances send messages to
disk files, rotating the log file at certain timed intervals.

@item 
@ref{115d,,SocketHandler} instances send messages to TCP/IP
sockets. Since 3.4, Unix domain sockets are also supported.

@item 
@ref{115e,,DatagramHandler} instances send messages to UDP
sockets. Since 3.4, Unix domain sockets are also supported.

@item 
@ref{1828,,SMTPHandler} instances send messages to a designated
email address.

@item 
@ref{865,,SysLogHandler} instances send messages to a Unix
syslog daemon, possibly on a remote machine.

@item 
@ref{30b9,,NTEventLogHandler} instances send messages to a
Windows NT/2000/XP event log.

@item 
@ref{3072,,MemoryHandler} instances send messages to a buffer
in memory, which is flushed whenever specific criteria are met.

@item 
@ref{1027,,HTTPHandler} instances send messages to an HTTP
server using either @code{GET} or @code{POST} semantics.

@item 
@ref{308f,,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{1a90,,QueueHandler} instances send messages to a queue, such as
those implemented in the @ref{bb,,queue} or @ref{98,,multiprocessing} modules.

@item 
@ref{1485,,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{308c,,Configuring Logging for a Library} for
more information.
@end enumerate


在 3.1 版被加入: The @ref{1485,,NullHandler} class.



在 3.2 版被加入: The @ref{1a90,,QueueHandler} class.


The @ref{1485,,NullHandler}, @ref{13f9,,StreamHandler} and @ref{1b55,,FileHandler}
classes are defined in the core logging package. The other handlers are
defined in a sub-module, @ref{8d,,logging.handlers}. (There is also another
sub-module, @ref{8c,,logging.config}, for configuration functionality.)

Logged messages are formatted for presentation through instances of the
@ref{168b,,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{3034,,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{13fc,,Filter} can be added to both @ref{d3e,,Logger} and
@ref{168a,,Handler} instances (through their @ref{3024,,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{13fc,,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 模組
@anchor{howto/logging exceptions-raised-during-logging}@anchor{54d9}@anchor{howto/logging logging-exceptions}@anchor{54da}
@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{f37,,SystemExit} and @ref{bbc,,KeyboardInterrupt} exceptions are never
swallowed. Other exceptions which occur during the @ref{302b,,emit()} method
of a @ref{168a,,Handler} subclass are passed to its @ref{302a,,handleError()}
method.

The default implementation of @ref{302a,,handleError()} in @ref{168a,,Handler}
checks to see if a module-level variable, @ref{13fa,,raiseExceptions}, is set. If
set, a traceback is printed to @ref{b2a,,sys.stderr}. If not set, the exception is
swallowed.

@cartouche
@quotation 備註 
The default value of @ref{13fa,,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 @ref{13fa,,raiseExceptions} to
@code{False} for production usage.
@end quotation
@end cartouche

@node Using arbitrary objects as messages,最佳化<19>,Exceptions raised during logging,如何使用 Logging 模組
@anchor{howto/logging arbitrary-object-messages}@anchor{3040}@anchor{howto/logging using-arbitrary-objects-as-messages}@anchor{54db}
@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{829,,__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{115d,,SocketHandler} emits an event by pickling it and sending it
over the wire.

@node 最佳化<19>,其他資源<2>,Using arbitrary objects as messages,如何使用 Logging 模組
@anchor{howto/logging optimization}@anchor{54dc}
@subsection 最佳化


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{14f7,,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{14f7,,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 @ref{14f7,,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{8e8,,sys._getframe()}, which
may help to speed up your code in environments
like PyPy (which can't speed up code that uses
@ref{8e8,,sys._getframe()}).

@item

Threading information.

@tab

將 @code{logging.logThreads} 設為 @code{False}。

@item

目前的行程 ID (@ref{2eb3,,os.getpid()})

@tab

將 @code{logging.logProcesses} 設為 @code{False}。

@item

Current process name when using @code{multiprocessing}
to manage multiple processes.

@tab

將 @code{logging.logMultiprocessing} 設為 @code{False}。

@item

Current @ref{1c7,,asyncio.Task} name when using
@code{asyncio}.

@tab

將 @code{logging.logAsyncioTasks} 設為 @code{False}。

@end multitable


Also note that the core logging module only includes the basic handlers. If
you don't import @ref{8d,,logging.handlers} and @ref{8c,,logging.config}, they won't
take up any memory.

@node 其他資源<2>,,最佳化<19>,如何使用 Logging 模組
@anchor{howto/logging other-resources}@anchor{54dd}@anchor{howto/logging tutorial-ref-links}@anchor{54c1}
@subsection 其他資源



@subsubheading 也參考



@table @asis

@item @ref{8b,,logging} 模組

API reference for the logging module.

@item @ref{8c,,logging.config} 模組

Configuration API for the logging module.

@item @ref{8d,,logging.handlers} 模組

Useful handlers included with the logging module.
@end table

@ref{13f8,,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,如何使用正規表示式,如何使用 Logging 模組,Python 如何達成任務
@anchor{howto/logging-cookbook doc}@anchor{54de}@anchor{howto/logging-cookbook id1}@anchor{54df}@anchor{howto/logging-cookbook logging-cookbook}@anchor{13f8}@anchor{howto/logging-cookbook translation-repo}@anchor{54e0}
@section Logging Cookbook


@*作者: 
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{54e1,,其他資源}.

@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:: 
* 其他資源: 其他資源<3>. 

@end menu

@node Using logging in multiple modules,Logging from multiple threads,,Logging Cookbook
@anchor{howto/logging-cookbook using-logging-in-multiple-modules}@anchor{54e2}
@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{54e3}
@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{54e4}
@subsection Multiple handlers and formatters


Loggers are plain Python objects.  The @ref{300b,,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{54e5}@anchor{howto/logging-cookbook multiple-destinations}@anchor{54e6}
@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('@w{'}).addHandler(console)

# Now, we can log to the root logger, or any other logger. First the root...
logging.info('Jackdaws love my big sphinx of quartz.')

# Now, define a couple of other loggers which might represent areas in your
# application:

logger1 = logging.getLogger('myapp.area1')
logger2 = logging.getLogger('myapp.area2')

logger1.debug('Quick zephyrs blow, vexing daft Jim.')
logger1.info('How quickly daft jumping zebras vex.')
logger2.warning('Jail zesty vixen who grabbed pay from quack.')
logger2.error('The five boxing wizards jump quickly.')
@end example

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{54e7}@anchor{howto/logging-cookbook custom-level-handling}@anchor{54e8}
@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{54e9}
@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{37f4}@anchor{howto/logging-cookbook dealing-with-handlers-that-block}@anchor{54ea}
@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{1828,,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{115d,,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{1a90,,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{3521,,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{242,,QueueListener}, which has been
designed as the counterpart to @ref{1a90,,QueueHandler}.  A
@ref{242,,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{242,,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{242,,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{242,,QueueListener} can be started (and stopped) via the
@ref{186,,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{54eb}@anchor{howto/logging-cookbook sending-and-receiving-logging-events-across-a-network}@anchor{54ec}
@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{115d,,SocketHandler} instance to the root logger at the sending end:

@example
import logging, logging.handlers

rootLogger = logging.getLogger('@w{'})
rootLogger.setLevel(logging.DEBUG)
socketHandler = logging.handlers.SocketHandler('localhost',
                    logging.handlers.DEFAULT_TCP_LOGGING_PORT)
# don't bother with a formatter, since a socket handler sends the event as
# an unformatted pickle
rootLogger.addHandler(socketHandler)

# Now, we can log to the root logger, or any other logger. First the root...
logging.info('Jackdaws love my big sphinx of quartz.')

# Now, define a couple of other loggers which might represent areas in your
# application:

logger1 = logging.getLogger('myapp.area1')
logger2 = logging.getLogger('myapp.area2')

logger1.debug('Quick zephyrs blow, vexing daft Jim.')
logger1.info('How quickly daft jumping zebras vex.')
logger2.warning('Jail zesty vixen who grabbed pay from quack.')
logger2.error('The five boxing wizards jump quickly.')
@end example

At the receiving end, you can set up a receiver using the @ref{d2,,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{30aa,,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{54ed}
@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

檔案

@tab

目的

@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{54ee}@anchor{howto/logging-cookbook context-info}@anchor{3047}
@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{d3e,,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 @ref{d3e,,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 @ref{d3e,,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{54ef}
@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{14f6,,LoggerAdapter} class.
This class is designed to look like a @ref{d3e,,Logger}, so that you can call
@ref{3012,,debug()}, @ref{303b,,info()}, @ref{352,,warning()}, @ref{304f,,error()},
@ref{1688,,exception()}, @ref{3050,,critical()} and @ref{3051,,log()}. These methods have the
same signatures as their counterparts in @ref{d3e,,Logger}, so you can use the
two types of instances interchangeably.

When you create an instance of @ref{14f6,,LoggerAdapter}, you pass it a
@ref{d3e,,Logger} instance and a dict-like object which contains your contextual
information. When you call one of the logging methods on an instance of
@ref{14f6,,LoggerAdapter}, it delegates the call to the underlying instance of
@ref{d3e,,Logger} passed to its constructor, and arranges to pass the contextual
information in the delegated call. Here's a snippet from the code of
@ref{14f6,,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{3048,,process()} method of @ref{14f6,,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{11e1,,LogRecord} instance's __dict__, allowing you to use
customized strings with your @ref{168b,,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{14f6,,LoggerAdapter} and override
@ref{3048,,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{54f0}
@subsubsection Using objects other than dicts to pass contextual information


You don't need to pass an actual dict to a @ref{14f6,,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{303c}@anchor{howto/logging-cookbook using-filters-to-impart-contextual-information}@anchor{54f1}
@subsubsection Using Filters to impart contextual information


You can also add contextual information to log output using a user-defined
@ref{13fc,,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{168b,,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{17df,,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{54f2}
@subsection Use of @code{contextvars}


Since Python 3.7, the @ref{28,,contextvars} module has provided context-local storage
which works for both @ref{f3,,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{54f3}
@subsection Imparting contextual information in handlers


Each @ref{168a,,Handler} has its own chain of filters.
If you want to add contextual information to a @ref{11e1,,LogRecord} without leaking
it to other handlers, you can use a filter that returns
a new @ref{11e1,,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{54f4}@anchor{howto/logging-cookbook multiple-processes}@anchor{54f5}
@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{115d,,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{54eb,,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{17d2,,Lock}
class from the @ref{98,,multiprocessing} module to serialize access to the
file from your processes. The stdlib @ref{1b55,,FileHandler} and subclasses do
not make use of @ref{98,,multiprocessing}.

Alternatively, you can use a @code{Queue} and a @ref{1a90,,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
* 使用 concurrent.futures.ProcessPoolExecutor: 使用 concurrent futures ProcessPoolExecutor. 
* Deploying Web applications using Gunicorn and uWSGI:: 

@end menu

@node 使用 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{54f6}
@subsubsection 使用 concurrent.futures.ProcessPoolExecutor


If you want to use @ref{1d6,,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,,使用 concurrent futures ProcessPoolExecutor,Logging to a single file from multiple processes
@anchor{howto/logging-cookbook deploying-web-applications-using-gunicorn-and-uwsgi}@anchor{54f7}
@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{115d,,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{54ed,,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{54f8}
@subsection Using file rotation


@c (see <https://pymotw.com/3/logging/>)

Sometimes you want to let a log file grow to a certain size, then open a new
file and log to that. You may want to keep a certain number of these files, and
when that many files have been created, rotate the files so that the number of
files and the size of the files both remain bounded. For this usage pattern, the
logging package provides a @ref{18a8,,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{54f9}@anchor{howto/logging-cookbook use-of-alternative-formatting-styles}@anchor{54fa}
@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{890,,string.Template} (added in Python 2.4) and @ref{82c,,str.format()}
(added in Python 2.6).

Logging (as of 3.2) provides improved support for these two additional
formatting styles. The @ref{168b,,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{82c,,str.format()} or @ref{890,,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{82c,,str.format()} or
@ref{890,,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{165e,,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{14f6,,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{54fb}@anchor{howto/logging-cookbook customizing-logrecord}@anchor{54fc}
@subsection Customizing @code{LogRecord}


Every logging event is represented by a @ref{11e1,,LogRecord} instance.
When an event is logged and not filtered out by a logger's level, a
@ref{11e1,,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{3019,,Logger.makeRecord()}, which is called in the normal process of
logging an event. This invoked @ref{11e1,,LogRecord} directly to create an
instance.

@item 
@ref{303f,,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{115d,,SocketHandler}, or in JSON form via an
@ref{1027,,HTTPHandler}).
@end itemize

This has usually meant that if you need to do anything special with a
@ref{11e1,,LogRecord}, you've had to do one of the following.


@itemize *

@item 
Create your own @ref{d3e,,Logger} subclass, which overrides
@ref{3019,,Logger.makeRecord()}, and set it using @ref{304e,,setLoggerClass()}
before any loggers that you care about are instantiated.

@item 
Add a @ref{13fc,,Filter} to a logger or handler, which does the
necessary special manipulation you need when its
@ref{303a,,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{d3e,,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{11e1,,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{1485,,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{11e1,,LogRecord} creation is done through a
factory, which you can specify. The factory is just a callable you can set with
@ref{3043,,setLogRecordFactory()}, and interrogate with
@ref{3042,,getLogRecordFactory()}. The factory is invoked with the same
signature as the @ref{11e1,,LogRecord} constructor, as @ref{11e1,,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{13fc,,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{54fd}@anchor{howto/logging-cookbook zeromq-handlers}@anchor{54fe}
@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{54ff}
@subsubsection Subclass @code{QueueHandler}


You can use a @ref{1a90,,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{5500}
@subsubsection Subclass @code{QueueListener}


You can also subclass @ref{242,,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{5501}@anchor{howto/logging-cookbook subclassing-queuehandler-and-queuelistener-a-pynng-example}@anchor{5502}
@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{5503}
@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{5504}
@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{5505}
@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{13b1,,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{3099}@anchor{howto/logging-cookbook using-a-rotator-and-namer-to-customize-log-rotation-processing}@anchor{5506}
@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{5507}
@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{5508}
@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{865,,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{168b,,Formatter} instance to your
@ref{865,,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{5509}
@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{550a}@anchor{howto/logging-cookbook customizing-handlers-with-dictconfig}@anchor{550b}
@subsection Customizing handlers with @code{dictConfig()}


There are times when you want to customize logging handlers in particular ways,
and if you use @ref{13b1,,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{543,,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{13b1,,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{543,,shutil.chown()}
makes an appearance. This approach should work with any Python version that
supports @ref{13b1,,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{12ef,,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{13b1,,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{524,,os.chmod()}.

Of course, the approach could also be extended to types of handler other than a
@ref{1b55,,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{3030}@anchor{howto/logging-cookbook using-particular-formatting-styles-throughout-your-application}@anchor{550c}
@subsection Using particular formatting styles throughout your application


In Python 3.2, the @ref{168b,,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{82c,,str.format()} and @ref{890,,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{1026,,debug()}, @ref{3011,,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{82c,,str.format()} or @ref{890,,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{550d}
@subsubsection Using LogRecord factories


In Python 3.2, along with the @ref{168b,,Formatter} changes mentioned
above, the logging package gained the ability to allow users to set their own
@ref{11e1,,LogRecord} subclasses, using the @ref{3043,,setLogRecordFactory()} function.
You can use this to set your own subclass of @ref{11e1,,LogRecord}, which does the
Right Thing by overriding the @ref{3041,,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{3043,,setLogRecordFactory()} and
@ref{11e1,,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{550e}
@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{3040,,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{169,,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{82c,,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{890,,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{550f}@anchor{howto/logging-cookbook filters-dictconfig}@anchor{5510}
@subsection Configuring filters with @code{dictConfig()}


You `can' configure filters using @ref{13b1,,dictConfig()}, though it
might not be obvious at first glance how to do it (hence this recipe). Since
@ref{13fc,,Filter} is the only filter class included in the standard
library, and it is unlikely to cater to many requirements (it's only there as a
base class), you will typically need to define your own @ref{13fc,,Filter}
subclass with an overridden @ref{303a,,filter()} method. To do this,
specify the @code{()} key in the configuration dictionary for the filter,
specifying a callable which will be used to create the filter (a class is the
most obvious, but you can provide any callable which returns a
@ref{13fc,,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{306f,,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{3063,,User-defined objects} for more
information on how logging supports using user-defined objects in its
configuration, and see the other cookbook recipe @ref{550a,,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{5511}@anchor{howto/logging-cookbook customized-exception-formatting}@anchor{5512}
@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{104,,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{5513}@anchor{howto/logging-cookbook spoken-messages}@anchor{5514}
@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{dc,,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{5515}@anchor{howto/logging-cookbook buffering-logging-messages-and-outputting-them-conditionally}@anchor{5516}
@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{3072,,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{13f9,,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{5517}@anchor{howto/logging-cookbook sending-logging-messages-to-email-with-buffering}@anchor{5518}
@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{30c5,,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{5519}@anchor{howto/logging-cookbook utc-formatting}@anchor{551a}
@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{168b,,Formatter}. If you want to do that via configuration, you can
use the @ref{13b1,,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{551b}@anchor{howto/logging-cookbook using-a-context-manager-for-selective-logging}@anchor{551c}
@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{551d}@anchor{howto/logging-cookbook starter-template}@anchor{551e}
@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{551f}@anchor{howto/logging-cookbook qt-gui}@anchor{5520}
@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{f3,,threading} module, as there are circumstances where one has to use
@code{QThread}, which offers better integration with other @code{Qt} components.

The code should work with recent releases of any of @code{PySide6}, @code{PyQt6},
@code{PySide2} or @code{PyQt5}. You should be able to adapt the approach to earlier
versions of Qt. Please refer to the comments in the code snippet for more
detailed information.

@example
import datetime
import logging
import random
import sys
import time

# Deal with minor differences between different Qt packages
try:
    from PySide6 import QtCore, QtGui, QtWidgets
    Signal = QtCore.Signal
    Slot = QtCore.Slot
except ImportError:
    try:
        from PyQt6 import QtCore, QtGui, QtWidgets
        Signal = QtCore.pyqtSignal
        Slot = QtCore.pyqtSlot
    except ImportError:
        try:
            from PySide2 import QtCore, QtGui, QtWidgets
            Signal = QtCore.Signal
            Slot = QtCore.Slot
        except ImportError:
            from PyQt5 import QtCore, QtGui, QtWidgets
            Signal = QtCore.pyqtSignal
            Slot = QtCore.pyqtSlot

logger = logging.getLogger(__name__)


#
# Signals need to be contained in a QObject or subclass in order to be correctly
# initialized.
#
class Signaller(QtCore.QObject):
    signal = Signal(str, logging.LogRecord)

#
# Output to a Qt GUI is only supposed to happen on the main thread. So, this
# handler is designed to take a slot function which is set up to run in the main
# thread. In this example, the function takes a string argument which is a
# formatted log message, and the log record which generated it. The formatted
# string is just a convenience - you could format a string for output any way
# you like in the slot function itself.
#
# You specify the slot function to do whatever GUI updates you want. The handler
# doesn't know or care about specific UI elements.
#
class QtHandler(logging.Handler):
    def __init__(self, slotfunc, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.signaller = Signaller()
        self.signaller.signal.connect(slotfunc)

    def emit(self, record):
        s = self.format(record)
        self.signaller.signal.emit(s, record)

#
# This example uses QThreads, which means that the threads at the Python level
# are named something like "Dummy-1". The function below gets the Qt name of the
# current thread.
#
def ctname():
    return QtCore.QThread.currentThread().objectName()


#
# Used to generate random levels for logging.
#
LEVELS = (logging.DEBUG, logging.INFO, logging.WARNING, logging.ERROR,
          logging.CRITICAL)

#
# This worker class represents work that is done in a thread separate to the
# main thread. The way the thread is kicked off to do work is via a button press
# that connects to a slot in the worker.
#
# Because the default threadName value in the LogRecord isn't much use, we add
# a qThreadName which contains the QThread name as computed above, and pass that
# value in an "extra" dictionary which is used to update the LogRecord with the
# QThread name.
#
# This example worker just outputs messages sequentially, interspersed with
# random delays of the order of a few seconds.
#
class Worker(QtCore.QObject):
    @@Slot()
    def start(self):
        extra = @{'qThreadName': ctname() @}
        logger.debug('Started work', extra=extra)
        i = 1
        # Let the thread run until interrupted. This allows reasonably clean
        # thread termination.
        while not QtCore.QThread.currentThread().isInterruptionRequested():
            delay = 0.5 + random.random() * 2
            time.sleep(delay)
            try:
                if random.random() < 0.1:
                    raise ValueError('Exception raised: %d' % i)
                else:
                    level = random.choice(LEVELS)
                    logger.log(level, 'Message after delay of %3.1f: %d', delay, i, extra=extra)
            except ValueError as e:
                logger.exception('Failed: %s', e, extra=extra)
            i += 1

#
# Implement a simple UI for this cookbook example. This contains:
#
# * A read-only text edit window which holds formatted log messages
# * A button to start work and log stuff in a separate thread
# * A button to log something from the main thread
# * A button to clear the log window
#
class Window(QtWidgets.QWidget):

    COLORS = @{
        logging.DEBUG: 'black',
        logging.INFO: 'blue',
        logging.WARNING: 'orange',
        logging.ERROR: 'red',
        logging.CRITICAL: 'purple',
    @}

    def __init__(self, app):
        super().__init__()
        self.app = app
        self.textedit = te = QtWidgets.QPlainTextEdit(self)
        # Set whatever the default monospace font is for the platform
        f = QtGui.QFont('nosuchfont')
        if hasattr(f, 'Monospace'):
            f.setStyleHint(f.Monospace)
        else:
            f.setStyleHint(f.StyleHint.Monospace)  # for Qt6
        te.setFont(f)
        te.setReadOnly(True)
        PB = QtWidgets.QPushButton
        self.work_button = PB('Start background work', self)
        self.log_button = PB('Log a message at a random level', self)
        self.clear_button = PB('Clear log window', self)
        self.handler = h = QtHandler(self.update_status)
        # Remember to use qThreadName rather than threadName in the format string.
        fs = '%(asctime)s %(qThreadName)-12s %(levelname)-8s %(message)s'
        formatter = logging.Formatter(fs)
        h.setFormatter(formatter)
        logger.addHandler(h)
        # Set up to terminate the QThread when we exit
        app.aboutToQuit.connect(self.force_quit)

        # Lay out all the widgets
        layout = QtWidgets.QVBoxLayout(self)
        layout.addWidget(te)
        layout.addWidget(self.work_button)
        layout.addWidget(self.log_button)
        layout.addWidget(self.clear_button)
        self.setFixedSize(900, 400)

        # Connect the non-worker slots and signals
        self.log_button.clicked.connect(self.manual_update)
        self.clear_button.clicked.connect(self.clear_display)

        # Start a new worker thread and connect the slots for the worker
        self.start_thread()
        self.work_button.clicked.connect(self.worker.start)
        # Once started, the button should be disabled
        self.work_button.clicked.connect(lambda : self.work_button.setEnabled(False))

    def start_thread(self):
        self.worker = Worker()
        self.worker_thread = QtCore.QThread()
        self.worker.setObjectName('Worker')
        self.worker_thread.setObjectName('WorkerThread')  # for qThreadName
        self.worker.moveToThread(self.worker_thread)
        # This will start an event loop in the worker thread
        self.worker_thread.start()

    def kill_thread(self):
        # Just tell the worker to stop, then tell it to quit and wait for that
        # to happen
        self.worker_thread.requestInterruption()
        if self.worker_thread.isRunning():
            self.worker_thread.quit()
            self.worker_thread.wait()
        else:
            print('worker has already exited.')

    def force_quit(self):
        # For use when the window is closed
        if self.worker_thread.isRunning():
            self.kill_thread()

    # The functions below update the UI and run in the main thread because
    # that's where the slots are set up

    @@Slot(str, logging.LogRecord)
    def update_status(self, status, record):
        color = self.COLORS.get(record.levelno, 'black')
        s = '<pre><font color="%s">%s</font></pre>' % (color, status)
        self.textedit.appendHtml(s)

    @@Slot()
    def manual_update(self):
        # This function uses the formatted message passed in, but also uses
        # information from the record to format the message in an appropriate
        # color according to its severity (level).
        level = random.choice(LEVELS)
        extra = @{'qThreadName': ctname() @}
        logger.log(level, 'Manually logged!', extra=extra)

    @@Slot()
    def clear_display(self):
        self.textedit.clear()


def main():
    QtCore.QThread.currentThread().setObjectName('MainThread')
    logging.getLogger().setLevel(logging.DEBUG)
    app = QtWidgets.QApplication(sys.argv)
    example = Window(app)
    example.show()
    if hasattr(app, 'exec'):
        rc = app.exec()
    else:
        rc = app.exec_()
    sys.exit(rc)

if __name__=='__main__':
    main()
@end example

@node Logging to syslog with RFC5424 support,How to treat a logger like an output stream,A Qt GUI for logging,Logging Cookbook
@anchor{howto/logging-cookbook logging-to-syslog-with-rfc5424-support}@anchor{5521}
@subsection Logging to syslog with RFC5424 support


Although 
@geindex RFC; RFC 5424
RFC 5424@footnote{https://datatracker.ietf.org/doc/html/rfc5424.html} dates from 2009, most syslog servers are configured by default to
use the older 
@geindex RFC; RFC 3164
RFC 3164@footnote{https://datatracker.ietf.org/doc/html/rfc3164.html}, which hails from 2001. When @code{logging} was added to Python
in 2003, it supported the earlier (and only existing) protocol at the time. Since
RFC5424 came out, as there has not been widespread deployment of it in syslog
servers, the @ref{865,,SysLogHandler} functionality has not been
updated.

RFC 5424 contains some useful features such as support for structured data, and if you
need to be able to log to a syslog server with support for it, you can do so with a
subclassed handler which looks something like this:

@example
import datetime
import logging.handlers
import re
import socket
import time

class SysLogHandler5424(logging.handlers.SysLogHandler):

    tz_offset = re.compile(r'([+-]\d@{2@})(\d@{2@})$')
    escaped = re.compile(r'([\]"\\])')

    def __init__(self, *args, **kwargs):
        self.msgid = kwargs.pop('msgid', None)
        self.appname = kwargs.pop('appname', None)
        super().__init__(*args, **kwargs)

    def format(self, record):
        version = 1
        asctime = datetime.datetime.fromtimestamp(record.created).isoformat()
        m = self.tz_offset.match(time.strftime('%z'))
        has_offset = False
        if m and time.timezone:
            hrs, mins = m.groups()
            if int(hrs) or int(mins):
                has_offset = True
        if not has_offset:
            asctime += 'Z'
        else:
            asctime += f'@{hrs@}:@{mins@}'
        try:
            hostname = socket.gethostname()
        except Exception:
            hostname = '-'
        appname = self.appname or '-'
        procid = record.process
        msgid = '-'
        msg = super().format(record)
        sdata = '-'
        if hasattr(record, 'structured_data'):
            sd = record.structured_data
            # This should be a dict where the keys are SD-ID and the value is a
            # dict mapping PARAM-NAME to PARAM-VALUE (refer to the RFC for what these
            # mean)
            # There's no error checking here - it's purely for illustration, and you
            # can adapt this code for use in production environments
            parts = []

            def replacer(m):
                g = m.groups()
                return '\\' + g[0]

            for sdid, dv in sd.items():
                part = f'[@{sdid@}'
                for k, v in dv.items():
                    s = str(v)
                    s = self.escaped.sub(replacer, s)
                    part += f' @{k@}="@{s@}"'
                part += ']'
                parts.append(part)
            sdata = '@w{'}.join(parts)
        return f'@{version@} @{asctime@} @{hostname@} @{appname@} @{procid@} @{msgid@} @{sdata@} @{msg@}'
@end example

You'll need to be familiar with RFC 5424 to fully understand the above code, and it
may be that you have slightly different needs (e.g. for how you pass structural data
to the log). Nevertheless, the above should be adaptable to your speciric needs. With
the above handler, you'd pass structured data using something like this:

@example
sd = @{
    'foo@@12345': @{'bar': 'baz', 'baz': 'bozz', 'fizz': r'buzz'@},
    'foo@@54321': @{'rab': 'baz', 'zab': 'bozz', 'zzif': r'buzz'@}
@}
extra = @{'structured_data': sd@}
i = 1
logger.debug('Message %d', i, extra=extra)
@end example

@node How to treat a logger like an output stream,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{5522}
@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{bea,,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{bea,,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{5523}
@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,其他資源<3>,How to uniformly handle newlines in logging output,Logging Cookbook
@anchor{howto/logging-cookbook patterns-to-avoid}@anchor{5524}
@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{5525}
@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{54f5,,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{5526}
@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{5527}
@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{1485,,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{5528}
@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{3047,,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 其他資源<3>,,Patterns to avoid,Logging Cookbook
@anchor{howto/logging-cookbook cookbook-ref-links}@anchor{54e1}@anchor{howto/logging-cookbook other-resources}@anchor{5529}
@subsection 其他資源



@subsubheading 也參考



@table @asis

@item @ref{8b,,logging} 模組

API reference for the logging module.

@item @ref{8c,,logging.config} 模組

Configuration API for the logging module.

@item @ref{8d,,logging.handlers} 模組

Useful handlers included with the logging module.
@end table

@ref{13f6,,基礎教學}

@ref{13f7,,進階教學}


@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node 如何使用正規表示式,Socket 程式設計指南,Logging Cookbook,Python 如何達成任務
@anchor{howto/regex doc}@anchor{552a}@anchor{howto/regex regex-howto}@anchor{260d}@anchor{howto/regex regular-expression-howto}@anchor{552b}@anchor{howto/regex translation-repo}@anchor{552c}
@section 如何使用正規表示式


@*作者: 
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 摘要



此文件為如何在 Python 中使用 @ref{be,,re} 模組來撰寫正規表示式的入門指導。進階使用及參考文件請見函式庫參考一章。

@menu
* 簡介: 簡介<12>. 
* Simple Patterns:: 
* Using Regular Expressions:: 
* More Pattern Power:: 
* Modifying Strings:: 
* Common Problems:: 
* Feedback:: 

@end menu

@node 簡介<12>,Simple Patterns,,如何使用正規表示式
@anchor{howto/regex introduction}@anchor{552d}
@subsection 簡介


正規表示式 (也稱為 REs、regexes 或 regex patterns) 是一個輕量且高專業化的程式語言。在 Python 中可透過內建的 @ref{be,,re}  模組直接使用。你可以使用此輕量化的語言針對想要匹配的一組字串撰寫規則，這組字串可能包含了英語句子、e-mail 地址、TeX 命令或任何東西。你可以檢查如「這組字串是否匹配這個規則？」或「這組字串中是否有任一處匹配這個規則？」。除此之外，你也可以使用 REs 來修改或是切割字串。

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,簡介<12>,如何使用正規表示式
@anchor{howto/regex simple-patterns}@anchor{552e}
@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{552f}
@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{10b,,unicodedata} module.  You can use the more
restricted definition of @code{\w} in a string pattern by supplying the
@ref{838,,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{926,,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{260e,,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{5530}
@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

6

@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,如何使用正規表示式
@anchor{howto/regex using-regular-expressions}@anchor{5531}
@subsection Using Regular Expressions


Now that we've looked at some simple regular expressions, how do we actually use
them in Python?  The @ref{be,,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:: 
* 模組層級函式: 模組層級函式<2>. 
* Compilation Flags:: 

@end menu

@node Compiling Regular Expressions,The Backslash Plague,,Using Regular Expressions
@anchor{howto/regex compiling-regular-expressions}@anchor{5532}
@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{dc9,,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{dc9,,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{be,,re} module is simply a C extension module
included with Python, just like the @ref{d1,,socket} or @ref{139,,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{5533}@anchor{howto/regex the-backslash-plague}@anchor{5534}
@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{dc9,,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{dc9,,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{1a3,,DeprecationWarning} and will eventually become a @ref{18e,,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,模組層級函式<2>,The Backslash Plague,Using Regular Expressions
@anchor{howto/regex performing-matches}@anchor{5535}
@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{be,,re} docs
for a complete listing.


@multitable {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

方法/屬性

@tab

Purpose

@item

@code{match()}

@tab

Determine if the RE matches at the beginning
of the string.

@item

@code{search()}

@tab

Scan through a string, looking for any
location where this RE matches.

@item

@code{findall()}

@tab

Find all substrings where the RE matches, and
returns them as a list.

@item

@code{finditer()}

@tab

Find all substrings where the RE matches, and
returns them as an @ref{4c3,,iterator}.

@end multitable


@ref{261f,,match()} and @ref{2620,,search()} return @code{None} if no match can be found.  If
they're successful, a @ref{1183,,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{be,,re}
module.

This HOWTO uses the standard Python interpreter for its examples. First, run the
Python interpreter, import the @ref{be,,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{261f,,match()} should return @code{None} in this case, which will cause the
interpreter to print no output.  You can explicitly print the result of
@code{match()} to make this clear.

@example
>>> p.match("")
>>> print(p.match(""))
None
@end example

Now, let's try it on a string that it should match, such as @code{tempo}.  In this
case, @ref{261f,,match()} will return a @ref{1183,,match object}, so you
should store the result in a variable for later use.

@example
>>> m = p.match('tempo')
>>> m
<re.Match object; span=(0, 5), match='tempo'>
@end example

Now you can query the @ref{1183,,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

方法/屬性

@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{1226,,group()} returns the substring that was matched by the RE.  @ref{2632,,start()}
and @ref{2633,,end()} return the starting and ending index of the match. @ref{2634,,span()}
returns both start and end indexes in a single tuple.  Since the @ref{261f,,match()}
method only checks if the RE matches at the start of a string, @code{start()}
will always be zero.  However, the @ref{2620,,search()} method of patterns
scans through the string, so  the match may not start at zero in that
case.

@example
>>> print(p.match('::: message'))
None
>>> m = p.search('::: message'); print(m)
<re.Match object; span=(4, 11), match='message'>
>>> m.group()
'message'
>>> m.span()
(4, 11)
@end example

In actual programs, the most common style is to store the
@ref{1183,,match object} in a variable, and then check if it was
@code{None}.  This usually looks like:

@example
p = re.compile( ... )
m = p.match( '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{2626,,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{1a3,,DeprecationWarning} and will eventually become a @ref{18e,,SyntaxError}.  See
@ref{5534,,The Backslash Plague}.

@ref{2626,,findall()} has to create the entire list before it can be returned as the
result.  The @ref{2627,,finditer()} method returns a sequence of
@ref{1183,,match object} instances as an @ref{4c3,,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 模組層級函式<2>,Compilation Flags,Performing Matches,Using Regular Expressions
@anchor{howto/regex module-level-functions}@anchor{5536}
@subsubsection 模組層級函式


You don't have to create a pattern object and call its methods; the
@ref{be,,re} module also provides top-level functions called @ref{142e,,match()},
@ref{142d,,search()}, @ref{1225,,findall()}, @ref{59d,,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{1183,,match object} instance.

@example
>>> print(re.match(r'From\s+', 'Fromage amk'))
None
>>> re.match(r'From\s+', 'From amk Thu May 14 19:12:10 1998')
<re.Match object; span=(0, 5), match='From '>
@end example

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,,模組層級函式<2>,Using Regular Expressions
@anchor{howto/regex compilation-flags}@anchor{5537}
@subsubsection Compilation Flags


Compilation flags let you modify some aspects of how regular expressions work.
Flags are available in the @ref{be,,re} module under two names, a long name such as
@ref{19e5,,IGNORECASE} and a short, one-letter form such as @ref{2611,,I}.  (If you're
familiar with Perl's pattern modifiers, the one-letter forms use the same
letters; the short form of @ref{261d,,re.VERBOSE} is @ref{2616,,re.X}, for example.)
Multiple flags can be specified by bitwise OR-ing them; @code{re.I | re.M} sets
both the @ref{2611,,I} and @ref{2613,,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

旗標

@tab

含義

@item

@ref{838,,ASCII}, @ref{2610,,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{260e,,DOTALL}, @ref{2614,,S}

@tab

Make @code{.} match any character, including
newlines.

@item

@ref{19e5,,IGNORECASE}, @ref{2611,,I}

@tab

Do case-insensitive matches.

@item

@ref{d5b,,LOCALE}, @ref{2612,,L}

@tab

Do a locale-aware match.

@item

@ref{260f,,MULTILINE}, @ref{2613,,M}

@tab

Multi-line matching, affecting @code{^} and
@code{$}.

@item

@ref{261d,,VERBOSE}, @ref{2616,,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{838,,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{19e5,,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{d5b,,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{d5b,,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{5538,,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 or preceded by an unescaped
backslash.

For example, here's a RE that uses @ref{261d,,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{261d,,re.VERBOSE}.
@end deffn

@node More Pattern Power,Modifying Strings,Using Regular Expressions,如何使用正規表示式
@anchor{howto/regex more-pattern-power}@anchor{5539}
@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{553a}@anchor{howto/regex more-metacharacters}@anchor{5538}
@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{260f,,MULTILINE} flag has been
set, this will only match at the beginning of the string.  In @ref{260f,,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{260f,,MULTILINE} mode,
@code{\A} and @code{^} are effectively the same.  In @ref{260f,,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{553b}
@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.match('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{1226,,group()}, @ref{2632,,start()}, @ref{2633,,end()}, and
@ref{2634,,span()}.  Groups are
numbered starting with 0.  Group 0 is always present; it's the whole RE, so
@ref{1183,,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.match('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.match('abcd')
>>> m.group(0)
'abcd'
>>> m.group(1)
'abc'
>>> m.group(2)
'b'
@end example

@ref{1226,,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{1227,,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{553c}
@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.match("([abc])+", "abc")
>>> m.groups()
('c',)
>>> m = re.match("(?:[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{1183,,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{2631,,groupdict()}:

@example
>>> m = re.match(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{78,,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{553d}
@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,如何使用正規表示式
@anchor{howto/regex modifying-strings}@anchor{553e}
@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

方法/屬性

@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: Search and Replace<2>. 

@end menu

@node Splitting Strings,Search and Replace<2>,,Modifying Strings
@anchor{howto/regex splitting-strings}@anchor{553f}
@subsubsection Splitting Strings


The @ref{2625,,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{10a5,,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{59c,,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{59c,,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<2>,,Splitting Strings,Modifying Strings
@anchor{howto/regex search-and-replace}@anchor{5540}
@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{2628,,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{2628,,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{2629,,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{1183,,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{59d,,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,如何使用正規表示式
@anchor{howto/regex common-problems}@anchor{5541}
@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:: 
* match() versus search(): match versus search. 
* Greedy versus Non-Greedy:: 
* Using re.VERBOSE: Using re VERBOSE. 

@end menu

@node Use String Methods,match versus search,,Common Problems
@anchor{howto/regex use-string-methods}@anchor{5542}
@subsubsection Use String Methods


Sometimes using the @ref{be,,re} module is a mistake.  If you're matching a fixed
string, or a single character class, and you're not using any @ref{be,,re} features
such as the @ref{19e5,,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{59d,,re.sub()} seems like the
function to use for this, but consider the @ref{4b3,,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{24f6,,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{be,,re} module, consider whether your problem
can be solved with a faster and simpler string method.

@node match versus search,Greedy versus Non-Greedy,Use String Methods,Common Problems
@anchor{howto/regex match-versus-search}@anchor{5543}
@subsubsection match() versus search()


The @ref{142e,,match()} function only checks if the RE matches at the beginning of the
string while @ref{142d,,search()} will scan forward through the string for a match.
It's important to keep this distinction in mind.  Remember,  @code{match()} will
only report a successful match which will start at 0; if the match wouldn't
start at zero,  @code{match()} will `not' report it.

@example
>>> print(re.match('super', 'superstition').span())
(0, 5)
>>> print(re.match('super', 'insuperable'))
None
@end example

On the other hand, @ref{142d,,search()} will scan 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

Sometimes you'll be tempted to keep using @ref{142e,,re.match()}, and just add @code{.*}
to the front of your RE.  Resist this temptation and use @ref{142d,,re.search()}
instead.  The regular expression compiler does some analysis of REs in order to
speed up the process of looking for a match.  One such analysis figures out what
the first character of a match must be; for example, a pattern starting with
@code{Crow} must match starting with a @code{'C'}.  The analysis lets the engine
quickly scan through the string looking for the starting character, only trying
the full match if a @code{'C'} is found.

Adding @code{.*} defeats this optimization, requiring scanning to the end of the
string and then backtracking to find a match for the rest of the RE.  Use
@ref{142d,,re.search()} instead.

@node Greedy versus Non-Greedy,Using re VERBOSE,match versus search,Common Problems
@anchor{howto/regex greedy-versus-non-greedy}@anchor{5544}
@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.match('<.*>', s).span())
(0, 32)
>>> print(re.match('<.*>', 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.match('<.*?>', 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{5545}
@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{261d,,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,如何使用正規表示式
@anchor{howto/regex feedback}@anchor{5546}
@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 author.

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 程式設計指南,排序技法,如何使用正規表示式,Python 如何達成任務
@anchor{howto/sockets doc}@anchor{5547}@anchor{howto/sockets socket-howto}@anchor{3857}@anchor{howto/sockets socket-programming-howto}@anchor{5548}@anchor{howto/sockets translation-repo}@anchor{5549}
@section Socket 程式設計指南


@*作者: 
Gordon McMillan


@subsubheading 摘要



Sockets 在各處都被廣泛使用，但卻是一項被誤解最嚴重的技術之一。這是一篇對 sockets 的概論介紹。這並不是一個完整的教學指南 - 你還需要做許多準備才能讓 sockets 正常運作。這篇文章也沒有包含細節（其中有非常多的細節），但我希望這篇文章能夠讓你有足夠的背景知識，以便開始正確的使用 sockets 程式設計。

@menu
* Sockets:: 
* 建立一個 Socket:: 
* 使用一個 Socket:: 
* 結束連線:: 
* 非阻塞的 Sockets:: 

@end menu

@node Sockets,建立一個 Socket,,Socket 程式設計指南
@anchor{howto/sockets sockets}@anchor{554a}
@subsection Sockets


我只會討論關於 INET（例如：IPv4）的 sockets，但它們涵蓋了幾乎 99% 的 sockets 使用場景。而我也將僅討論關於 STREAM（比如：TCP）類型的 sockets - 除非你真的知道你在做什麼（在這種情況下，這份指南可能不適合你），使用 STREAM 類型的 socket 會獲得比其他 sockets 類型更好的表現和性能。我將會嘗試解釋 socket 是什麼，以及如何使用阻塞 (blocking) 和非阻塞 (non-blocking) sockets 的一些建議。但首先我會先談論阻塞 sockets。在處理非阻塞 sockets 之前，你需要了解它們的工作原理。

要理解這些東西的困難點之一在於 "scoket" 可以代表多種具有些微差異的東西，這主要取決於上下文。所以首先，讓我們先區分「用戶端 (client)」socket 和「伺服器端 (server)」socket 的差別，「用戶端」socket 表示通訊的一端，「伺服器端」socket 更像是一個電話總機接線員。用戶端應用程式（例如：你的瀏覽器）只能使用「用戶端」socket; 它所連接的網路伺服器則同時使用「伺服器端」socket 和 「用戶端」socket 來進行通訊。

@menu
* 歷史:: 

@end menu

@node 歷史,,,Sockets
@anchor{howto/sockets history}@anchor{554b}
@subsubsection 歷史


在各種形式的 @abbr{IPC,Inter Process Communication} 中，sockets 是最受歡迎的。在任何特定的平台上，可能會存在其他更快速的 IPC 形式，但對於跨平台通訊來說，sockets 是唯一的選擇。

Sockets 作為 Unix 的 BSD 分支的一部分在 Berkeley 被發明出來。它們隨著網際網路的普及而迅速蔓延開來。這是有很好的理由 — sockets 和 INET 的結合讓世界各地任何的機器之間的通訊變得非常簡單（至少與其它方案相比是如此）。

@node 建立一個 Socket,使用一個 Socket,Sockets,Socket 程式設計指南
@anchor{howto/sockets creating-a-socket}@anchor{554c}
@subsection 建立一個 Socket


大致上來說，當你點擊了帶你來到這個頁面的連結時，你的瀏覽器做了以下的操作：

@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

當 @code{connect} 完成時，這個 socket @code{s} 可以用來發送請求來取得頁面的文本。同一個 socket 也會讀取回傳值，然後再被銷毀。是的，會被銷毀。用戶端 socket 通常只用來做一次交換（或是一小組連續交換）。

網路伺服器 (web 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

有幾件事需要注意：我們使用了 @code{socket.gethostname()}，這樣 socket 才能對外部網路可見。如果我們使用了 @code{s.bind(('localhost', 80))} 或 @code{s.bind(('127.0.0.1', 80))}，我們會得到一個「伺服器端」socket，但是只能在同一台機器內可見。@code{s.bind(('@w{'}, 80))} 指定 socket 可以透過機器的任何地址存取。

第二個要注意的是：數字小的連接埠 (port) 通常保留給「廣為人知的」服務（HTTP、SNMP等）。如果你只是想執行程式，可以使用一個數字較大的連接埠（4 位數字）。

最後，@code{listen} 引數告訴 socket 函式庫 (library)，我們希望在佇列 (queue) 中累積達 5 個（正常的最大值）連線請求後再拒絕外部連線。如果其餘的程式碼編寫正確，這應該足夠了。

現在我們有一個監聽 80 連接埠的「伺服器端」socket 了，我們可以進入網路伺服器的主迴圈了：

@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

事實上，有三種方法可以讓這個迴圈運作 - 分配一個執行緒 (thread) 來處理 @code{clientsocket} 、建立一個新行程 (process) 來處理 @code{clientsocket}，或者將這個程式重新改寫成使用非阻塞 socket，並使用 @code{select} 在我們的「伺服器端」socket 和任何有效的 @code{clientsocket} 之間進行多工處理。稍後將會更詳細的介紹。現在最重要的是理解：這就是「伺服器端」socket 做的`所有' 事情。它不會發送任何資料、也不接收任何資料，它只會建立「伺服器端」socket。每個 @code{clientsocket} 都是為了回應某些`其他' @code{connect()} 到我們綁定的主機上的「用戶端」socket。一但 @code{clientsocket} 建立完成，就會繼續監聽更多的連線請求。兩個「用戶端」可以隨意的通訊 - 它們使用的是一些動態分配的連接埠，會在通訊結束的時候被回收並重新利用。

@menu
* IPC:: 

@end menu

@node IPC,,,建立一個 Socket
@anchor{howto/sockets ipc}@anchor{554d}
@subsubsection IPC


如果你需要在一台機器上的兩個行程間進行快速的行程間通訊 (IPC)，你應該考慮使用管道 (pipes) 或共享記憶體 (shared memory)。如果你確定要使用 AF_INET sockets，請將「伺服器端」socket 綁定到 @code{'localhost'}。在大多數平台上，這樣將會繞過幾個網路程式碼層，並且速度會更快一些。


@subsubheading 也參考


@ref{98,,multiprocessing} 將跨平台行程間通訊整合到更高層的 API 中。


@node 使用一個 Socket,結束連線,建立一個 Socket,Socket 程式設計指南
@anchor{howto/sockets using-a-socket}@anchor{554e}
@subsection 使用一個 Socket


首先需要注意，網頁瀏覽器的「用戶端」socket 和網路伺服器的「用戶端」socket 是非常類似的。也就是說，這是一個「點對點 (peer to peer)」的通訊方式，或者也可以說`作為設計者，你必須決定通訊的規則'。通常情況下，@code{connect} 的 socket 會通過發送一個請求或者信號來開始一次通訊。但這屬於設計決策，而不是 socket 的規則。

現在有兩組可供通訊使用的動詞。你可以使用 @code{send} 和 @code{recv}，或者可以將用戶端 socket 轉換成類似檔案的形式，並使用 @code{read} 和 @code{write}。後者是 Java 中呈現 socket 的方式。我不打算在這裡討論它，只是提醒你需要在 socket 上使用 @code{flush}。這些是緩衝的「檔案」，一個常見的錯誤是使用 @code{write} 寫入某些內容，然後直接 @code{read} 回覆。如果不使用 @code{flush}，你可能會一直等待這個回覆，因為請求可能還在你的輸出緩衝中。

現在我們來到 sockets 的主要障礙 - @code{send} 和 @code{recv} 操作的是網路緩衝區。他們不一定會處理你提供給它們的所有位元組（或者是你期望它處理的位元組），因為它們主要的重點是處理網路緩衝區。一般來說，它們會在關聯的網路衝區已滿 (@code{send}) 或已清空 (@code{recv}) 時回傳，然後告訴你它們處理了多少位元組。`你' 的責任是一直呼叫它們直到你所有的訊息處理完成。

當 @code{recv} 回傳「零位元組 (0 bytes)」時，就表示另一端已經關閉（或著正在關閉）連線。你再也不能從這個連線上取得任何資料了。你可能還是可以成功發送資料；我稍後會對此進行更詳細的解釋。

像 HTTP 這樣的協定只使用一個 socket 進行一次傳輸，用戶端發送一個請求，然後讀取一個回覆。就這樣，然後這個 socket 就會被銷毀。這表示者用戶端可以通過接收「零位元組」來檢測回覆的結束。

但是如果你打算在之後的傳輸中重新利用 socket 的話，你需要明白`socket 中是不存在' @abbr{EOT （傳輸結束）}。重申一次：如果一個 socket 的 @code{send} 或 @code{recv} 處理了「零位元組」後回傳，表示連線已經斷開。如果連線`沒有' 斷開，你可能會永遠處於等待 @code{recv} 的狀態，因為（就目前來說）socket `不會' 告訴你沒有更多資料可以讀取了。現在，如果你稍微思考一下，你就會意識到 socket 的一個基本事實：`訊息要麼是一個固定的長度（不好的做法），要麼是可以被分隔的（普通的做法），要麼是指定其長度（更好地做法），要麼通過關閉連線來結束。'完全由你來決定要使用哪種方式（但有些方法比其他方法來的更好）。

假設你不想結束連線，最簡單的方式就是使用固定長度的訊息：

@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

發送部分的程式碼幾乎可用於任何訊息的傳送方式 - 在 Python 中你發送一個字串，可以用 @code{len()} 來確認他的長度（即使字串包含了 @code{\0} 字元）。在這裡，主要是接收的程式碼變得更複雜一些。（在 C 語言中，情況沒有變得更糟，只是如果訊息中包含了 @code{\0} 字元，你就不能使用 @code{strlen} 函式。）

最簡單的改進方法是將訊息的第一個字元表示訊息的類型，並根據訊息的類型來決定訊息的長度。現在你需要使用兩次 @code{recv} - 第一次用於接收（至少）第一個字元來得知長度，第二次用於在迴圈中接收剩下的訊息。如果你決定使用分隔符號的方式，你將會以某個任意的區塊大小進行接收（4096 或 8192 通常是網路緩衝區大小的良好選擇），並在收到的內容中掃描分隔符號。

需要注意的一個複雜情況是，如果你的通訊協定允許連續發送多個訊息（沒有任何回應），並且你傳遞給 @code{recv} 函式一個任意的區塊大小，最後有可能讀取到下一條訊息的開頭。你需要將其放在一旁並保留下來，直到需要使用的時候。

使用長度作為訊息的前綴（例如，使用 5 個數字字元表示）會變得更複雜，因為（信不信由你）你可能無法在一次 @code{recv} 中獲得所有 5 個字元。在一般使用下，可能不會有這個狀況，但在高負載的網路下，除非使用兩個 @code{recv} （第一個用於確定長度，第二個用於取得訊息的資料部分），否則你的程式碼很快就會出現錯誤。這令人非常頭痛。同樣的情況也會讓你發現 @code{send} 並不總能在一次傳輸中完全清除所有內容。儘管已經閱讀了這篇文章，但最終還是無法解決！

為了節省篇幅、培養你的技能（並保持我的競爭優勢），這些改進方法留給讀者自行練習。現在讓我們開始進行清理工作。

@menu
* 二進位資料:: 

@end menu

@node 二進位資料,,,使用一個 Socket
@anchor{howto/sockets binary-data}@anchor{554f}
@subsubsection 二進位資料


使用 socket 傳輸二進位資料完全是可行的。最主要的問題在於不同機器使用不同的二進位資料格式。例如，網路二進位順序@footnote{https://en.wikipedia.org/wiki/Endianness#Networking} 採用的是「大端序 big-endian」，所以一個值為 @code{1} 的 16 位元整數會表示成兩個 16 進位的位元組 @code{00 01}。然而大多數常見的處理器 (x86/AMD64，ARM，RISC-V) 採用的是「小端序 little-endian」，所以相同的 @code{1} 會被表示成 @code{01 00}。（譯者注：將一個多位數的低位放在較小的位址處，高位放在較大的位址處，則稱小端序；反之則稱大端序。）

Socket 函式庫提供了用於轉換 16 位元和 32 位元整數的函式 - @code{ntohl, htonl, ntohs, htons}，其中 "n" 表示 `network'，"h" 表示 `host'，"s" 表示 `short'，"l" 表示 `long'。當網路的位元組順序和主機位元組順序相同時，這些函式不會做任何操作，但當主機的位元組順序相反時，這些函式會適當的交換位元組順序。

在現今的 64 位元機器中，二進位資料的 ASCII 表示通常會比二進位表示要小，這是因為在很多情況下，大多數整數的值為 0 或者 1。例如，字串形式的 @code{"0"} 是兩個位元組，而完整的 64 位元整數則是 8 個位元組。當然，這對固定長度的訊息來說不太適合，需要自行決定。

@node 結束連線,非阻塞的 Sockets,使用一個 Socket,Socket 程式設計指南
@anchor{howto/sockets disconnecting}@anchor{5550}
@subsection 結束連線


嚴格來說，在關閉 socket 前，你應該使用 @code{shutdown} 函式。@code{shutdown} 函式是發送給 socket 另一端的一個提醒。根據你傳遞的引數，它可以表示「我不會再發送任何訊息了，但我仍然會持續監聽」，或者是「我不會再繼續監聽了，真讚！」。然而，大多數的 socket 函式庫或程式設計師都習慣忽略這種禮節，因為通常情況下 @code{close} 跟 @code{shutdown(); close()} 是一樣的。所以在大多數情況下，不需要再特地使用 @code{shutdown} 了。

有效使用 @code{shutdown} 的一種方式是在類似 HTTP 的交換中，用戶端發送請求後，然後使用 @code{shutdown(1)}。這告訴伺服器「這個用戶端已經發送完成，但仍可以接收」。伺服器可以通過接收「零位元組」來檢測 "EOF"。這樣它就可以確定已經接收到完整的請求。伺服器發送回覆，如果 @code{send} 成功完成，那麼用戶端確實在持續接收。

Python 更進一步地採取自動關閉的步驟，並且當 socket 被垃圾回收機制回收時，如果需要的話，他會自動執行 @code{close}。但依賴這個機制是一個非常不好的習慣，如果你的 socket 在沒有 @code{close} 的情況下消失了，那麼另一端的 socket 可能會認為你只是慢了一步，而無期限的等待。`請務必' 在使用完畢後使用 @code{close} 關閉你的 sockets。

@menu
* Sockets 何時銷毀:: 

@end menu

@node Sockets 何時銷毀,,,結束連線
@anchor{howto/sockets when-sockets-die}@anchor{5551}
@subsubsection Sockets 何時銷毀


使用阻塞式 socket 最糟糕的地方可能是在另一端突然強制關閉（未執行 @code{close}）的情況下會發生什麼？你的 socket 很可能會處於阻塞狀態。TCP 是一種可靠的協定，它在放棄連線之前會等待很長很長的時間。如果你正在使用執行緒，整個執行緒基本上已經無法使用。在這方面，你無法做太多事情。只要你不做一些愚蠢的事情，比如在執行阻塞式讀取時持有一個鎖，那麼執行緒並不會消耗太多資源。`不要'試圖終止執行緒 - 執行緒比行程更有效的部分原因是它們避免了與自動回收資源相關的開銷。換句話說，如果你確實設法終止了執行緒，整個行程可能會出現問題。

@node 非阻塞的 Sockets,,結束連線,Socket 程式設計指南
@anchor{howto/sockets non-blocking-sockets}@anchor{5552}
@subsection 非阻塞的 Sockets


如果你已經理解了前面的內容，你已經知道了大部分關於使用 sockets 的機制的所需知識，你仍然會以非常相似的方式使用相同的函式。就這樣而已，如果你做的對，你的程式就會是近乎完美的。

在 Python 中可以使用 @code{socket.setblocking(False)} 來設定為非阻塞。在 C 的作法更為複雜（例如，你需要在 BSD 風格的 @code{O_NONBLOCK} 和幾乎沒有區別的 POSIX 風格的 @code{O_NDELAY} 之間做出選擇，這與 @code{TCP_NODELAY} 完全不同），但基本思想是一樣的，你要在建立 socket 後但在使用它之前執行此操作。（實際上，如果你願意的話，你甚至可以來回切換。）

主要的機制差異在於 @code{send}、@code{recv}、@code{connect} 和 @code{accept} 可能在沒有執行任何操作的情況下就回傳了。你當然有多種選擇。你可以檢查回傳值和錯誤代碼，但這些操作通常會讓自己抓狂。如果你不相信我，不妨試試看。你的應用程式會變得臃腫、錯誤百出，並且占用 CPU。所以，讓我們跳過無腦的解決方案，使用正確的方式。

使用 @code{select}。

在 C 中，編寫 @code{select} 是非常複雜的，但在 Python 中，這很簡單，並與 C 的版本非常類似，如果你理解了 Python 中的 @code{select}，在 C 中處理它時也不會有太大的困難：

@example
ready_to_read, ready_to_write, in_error = \
               select.select(
                  potential_readers,
                  potential_writers,
                  potential_errs,
                  timeout)
@end example

你傳遞給 @code{select} 三個列表：第一個列表包含你可能想要嘗試讀取的所有 sockets；第二個包含所有你可能想要嘗試寫入的 sockets，最後一個（通常為空）包含你想要檢查錯誤的 sockets。你應該注意，一個 socket 可以同時存在於多個列表中。@code{select} 呼叫是阻塞的，但你可以設置超時。通常這是一個明智的做法 - 除非有充分的理由，否則給它一個很長的超時（比如一分鐘）。

作為回傳，你將獲得三個列表。它們包含實際上可讀取、可寫入和出錯的 sockets。這些列表中的每一個都是你傳入的相應列表的子集（可能為空）。

如果一個 socket 在輸出的可讀列表中，你可以幾乎確定，在這個業務中我們能夠得到的最接近確定的事情是，對該 socket 的 @code{recv} 呼叫將會回傳一些`內容'。對於可寫列表，也是同樣的想法。你將能夠發送一些 `內容'。也許不是全部，但`一些內容'總比什麼都沒有好。（實際上，任何比較正常的 socket 都會以可寫的方式回傳 - 這只是意味者「外送網路 (outbound network)」的緩衝空間是可用的。）

如果你有一個「伺服器端」socket，請將其放在 potential_readers 列表中，如果它在可讀列表中出現，你的 @code{accept} 呼叫（幾乎可以確定）會成功。如果你建立了一個新的 socket 去 @code{connect} 到其他地方，請將它放在 potential_writers 列表中，如果它在可寫列表中出現，那麼他有可能已經連接上了。

實際上，即使是使用阻塞式 socket 的情況下，@code{select} 也很方便。這是一種判斷是否會被阻塞的方法之一 - 當緩衝區中有某些內容時， socket 會回傳為可讀。然而，這仍然無法解決判斷另一端是否完成，或者只是忙於其他事情的問題。

`可移植性警告'：在 Unix 上，@code{select} 同時適用於 sockets 和文件。但請不要在 Windows 上嘗試這麼做，在 Windows 上，@code{select} 只適用於 sockets。同時，請注意，在 C 語言中，許多更進階的 socket 選項在 Windows 上有不同的實現方式。實際上，在 Windows 上，我通常會使用執行緒（這非常，非常有效）與我的 sockets 一起使用。

@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,Socket 程式設計指南,Python 如何達成任務
@anchor{howto/sorting doc}@anchor{5553}@anchor{howto/sorting sorting-techniques}@anchor{5554}@anchor{howto/sorting sortinghowto}@anchor{248a}@anchor{howto/sorting translation-repo}@anchor{5555}
@section 排序技法


@*作者: 
Andrew Dalke 和 Raymond Hettinger


Python 的串列有一個內建的 @ref{dc3,,list.sort()} 方法可以原地 (in-place) 排序該串列，也有一個內建的 @ref{dc2,,sorted()} 函式可以排序可疊代物件 (iterable) 並建立一個新的排序好的串列。

在這份文件裡，我們探索使用 Python 排序資料的各種方法。

@menu
* 基礎排序:: 
* 鍵函式 (key functions): 鍵函式 key functions. 
* Operator 模組函式以及部份函式 (partial function) 評估: Operator 模組函式以及部份函式 partial function 評估. 
* 升冪與降冪:: 
* 排序穩定性與複合排序:: 
* 裝飾-排序-移除裝飾 (decorate-sort-undecorate): 裝飾-排序-移除裝飾 decorate-sort-undecorate. 
* 比較函式 (comparison functions): 比較函式 comparison functions. 
* Strategies For Unorderable Types and Values:: 
* 雜項說明:: 
* 部份排序:: 

@end menu

@node 基礎排序,鍵函式 key functions,,排序技法
@anchor{howto/sorting sorting-basics}@anchor{5556}
@subsection 基礎排序


單純的升冪排序很容易做到：只要呼叫 @ref{dc2,,sorted()} 函式，它會回傳一個新的串列：

@example
>>> sorted([5, 2, 3, 1, 4])
[1, 2, 3, 4, 5]
@end example

你也可以使用 @ref{dc3,,list.sort()} 方法，它會原地排序串列（並回傳 @code{None} 以避免混淆）。它通常會比 @ref{dc2,,sorted()} 來得不方便——但如果你不需要保留原始串列的話，它會稍微有效率一點。

@example
>>> a = [5, 2, 3, 1, 4]
>>> a.sort()
>>> a
[1, 2, 3, 4, 5]
@end example

另一個差異是 @ref{dc3,,list.sort()} 方法只有定義在串列上，而 @ref{dc2,,sorted()} 函式可以接受任何可疊代物件。

@example
>>> sorted(@{1: 'D', 2: 'B', 3: 'B', 4: 'E', 5: 'A'@})
[1, 2, 3, 4, 5]
@end example

@node 鍵函式 key functions,Operator 模組函式以及部份函式 partial function 評估,基礎排序,排序技法
@anchor{howto/sorting key-functions}@anchor{5557}
@subsection 鍵函式 (key functions)


@ref{dc3,,list.sort()} 方法和 @ref{dc2,,sorted()}、@ref{1106,,min()}、@ref{1107,,max()}、@ref{2855,,heapq.nsmallest()} 及 @ref{2854,,heapq.nlargest()} 函式都有一個參數 `key' 可以指定一個函式（或其它可呼叫物件 (callable)），其會在每個串列元素做比較前被呼叫。

例如使用 @ref{fd1,,str.casefold()} 來做不區分大小寫的字串比對：

@example
>>> sorted("This is a test string from Andrew".split(), key=str.casefold)
['a', 'Andrew', 'from', 'is', 'string', 'test', 'This']
@end example

參數 `key' 的值必須是一個函式（或其它可呼叫物件），且這個函式接受單一引數並回傳一個用來排序的鍵。因為對每個輸入來說鍵函式只會被呼叫一次，所以這個做法是快速的。

一個常見的模式是在排序複雜物件的時候使用一部分物件的索引值當作鍵，例如：

@example
>>> student_tuples = [
...     ('john', 'A', 15),
...     ('jane', 'B', 12),
...     ('dave', 'B', 10),
... ]
>>> sorted(student_tuples, key=lambda student: student[2])   # 依照年齡排序
[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]
@end 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)   # 依照年齡排序
[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]
@end example

具有命名屬性的物件可以如上方的方式使用一個常規的類別建立，或是他們可以是 @ref{4dc,,dataclass} 的實例或是一個 @ref{857,,named tuple}。

@node Operator 模組函式以及部份函式 partial function 評估,升冪與降冪,鍵函式 key functions,排序技法
@anchor{howto/sorting operator-module-functions-and-partial-function-evaluation}@anchor{5558}
@subsection Operator 模組函式以及部份函式 (partial function) 評估


上述的@ref{1001,,鍵函式}模式非常常見，所以 Python 提供了方便的函式讓物件存取更簡單且快速。@ref{a3,,operator} 模組裡有 @ref{c4e,,itemgetter()}、@ref{102e,,attrgetter()} 及 @ref{102f,,methodcaller()} 函式可以使用。

使用這些函式讓上面的範例變得更簡單且快速：

@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

operator 模組的函式允許多層的排序，例如先用 `grade' 排序再用 `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

模組 @ref{63,,functools} 提供了另一個製作鍵函式的好用工具。@ref{217,,partial()} 函式可以減少多引數函式的引數數目@footnote{https://en.wikipedia.org/wiki/Arity}，使其更適合作為鍵函式使用。

@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 升冪與降冪,排序穩定性與複合排序,Operator 模組函式以及部份函式 partial function 評估,排序技法
@anchor{howto/sorting ascending-and-descending}@anchor{5559}
@subsection 升冪與降冪


@ref{dc3,,list.sort()} 和 @ref{dc2,,sorted()} 都有一個 boolean 參數 `reverse' 用來表示是否要降冪排序。例如將學生資料依據 `age' 做降冪排序：

@example
>>> sorted(student_tuples, key=itemgetter(2), reverse=True)
[('john', 'A', 15), ('jane', 'B', 12), ('dave', 'B', 10)]

>>> sorted(student_objects, key=attrgetter('age'), reverse=True)
[('john', 'A', 15), ('jane', 'B', 12), ('dave', 'B', 10)]
@end example

@node 排序穩定性與複合排序,裝飾-排序-移除裝飾 decorate-sort-undecorate,升冪與降冪,排序技法
@anchor{howto/sorting sort-stability-and-complex-sorts}@anchor{555a}
@subsection 排序穩定性與複合排序


排序保證是穩定的@footnote{https://en.wikipedia.org/wiki/Sorting_algorithm#Stability}，意思是當有多筆資料有相同的鍵，它們會維持原來的順序。

@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

可以注意到有兩筆資料的鍵都是 `blue'，它們會維持本來的順序，即 @code{('blue', 1)} 保證在 @code{('blue', 2)} 前面。

這個美妙的特性讓你可以用一連串的排序來作出複合排序。例如對學生資料用 `grade' 做降冪排序再用 `age' 做升冪排序，你可以先用 `age' 排序一遍再用 `grade' 排序一遍：

@example
>>> s = sorted(student_objects, key=attrgetter('age'))     # 依照次要鍵排序
>>> sorted(s, key=attrgetter('grade'), reverse=True)       # 現在依照主要鍵降冪排序
[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]
@end example

這可以抽出一個包裝函式 (wrapper function)，接受一個串列及多個欄位及升降冪的元組為引數，來對這個串列排序多遍。

@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

Python 裡使用的 Timsort@footnote{https://en.wikipedia.org/wiki/Timsort} 演算法，因為能利用資料集裡已經有的順序，可以有效率地做多次排序。

@node 裝飾-排序-移除裝飾 decorate-sort-undecorate,比較函式 comparison functions,排序穩定性與複合排序,排序技法
@anchor{howto/sorting decorate-sort-undecorate}@anchor{555b}
@subsection 裝飾-排序-移除裝飾 (decorate-sort-undecorate)


這個用語的來源是因為它做了以下三件事情：


@itemize *

@item 
首先，原始串列會裝飾 (decorated) 上新的值用來控制排序的順序。

@item 
接下來，排序裝飾過的串列。

@item 
最後，裝飾會被移除，並以新的順序產生一個只包含原始值的串列。
@end itemize

例如用上面說的方式來以 `grade' 排序學生資料：

@example
>>> decorated = [(student.grade, i, student) for i, student in enumerate(student_objects)]
>>> decorated.sort()
>>> [student for grade, i, student in decorated]               # 移除裝飾
[('john', 'A', 15), ('jane', 'B', 12), ('dave', 'B', 10)]
@end example

這個方式會有效是因為元組是依照字典順序 (lexicographically) 來比較，先比較第一個項目，如果一樣再比較第二個項目，並依此類推。

在所有情況下都把索引 `i' 加入已裝飾的串列並不是絕對需要的，但這樣做會有兩個好處：


@itemize *

@item 
排序會是穩定的 -- 如果兩個項目有相同的鍵，它們在排序好的串列中會保持原來的順序。

@item 
原始項目不需要是可以比較的，因為最多只會用到前兩個項目就能決定裝飾過的元組的順序。例如原始串列可以包含不能直接用來排序的複數。
@end itemize

這個用語的另一個名字是 Schwartzian transform@footnote{https://en.wikipedia.org/wiki/Schwartzian_transform}，是由於 Randal L. Schwartz 讓這個方法在 Perl 程式設計師間普及。

而因為 Python 的排序提供了鍵函式，已經不太需要用到這個方法了。

@node 比較函式 comparison functions,Strategies For Unorderable Types and Values,裝飾-排序-移除裝飾 decorate-sort-undecorate,排序技法
@anchor{howto/sorting comparison-functions}@anchor{555c}
@subsection 比較函式 (comparison functions)


不像鍵函式回傳一個用來排序的值，比較函式計算兩個輸入間的相對順序。

例如天秤@footnote{https://upload.wikimedia.org/wikipedia/commons/1/17/Balance_à_tabac_1850.JPG}比較兩邊樣本並給出相對的順序：較輕、相同或較重。同樣地，像是 @code{cmp(a, b)} 這樣的比較函式會回傳負數代表小於、0 代表輸入相同或正數代表大於。

當從其它語言翻譯演算法的時候常看到比較函式。有些函式庫也會提供比較函式作為其 API 的一部份，例如 @ref{4185,,locale.strcoll()} 就是一個比較函式。

為了滿足這些情境，Python 提供 @ref{13db,,functools.cmp_to_key} 來包裝比較函式，讓其可以當作鍵函式來使用：

@example
sorted(words, key=cmp_to_key(strcoll))  # 理解語系的排序順序
@end example

@node Strategies For Unorderable Types and Values,雜項說明,比較函式 comparison functions,排序技法
@anchor{howto/sorting strategies-for-unorderable-types-and-values}@anchor{555d}
@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{198,,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{198,,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 雜項說明,部份排序,Strategies For Unorderable Types and Values,排序技法
@anchor{howto/sorting odds-and-ends}@anchor{555e}
@subsection 雜項說明



@itemize *

@item 
要處理能理解本地語系 (locale aware) 的排序可以使用 @ref{1753,,locale.strxfrm()} 當作鍵函式，或 @ref{4185,,locale.strcoll()} 當作比較函式。這樣做是必要的，因為在不同文化中就算是相同的字母，按「字母順序」排序的結果也各不相同。

@item 
`reverse' 參數依然會維持排序穩定性（即有相同鍵的資料會保持原來順序）。有趣的是，不加這個參數也可以模擬這個效果，只要使用內建的 @ref{a5e,,reversed()} 函式兩次：

@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 
排序時會使用 @code{<} 來比較兩個物件，因此要在類別裡面加入排序順序比較規則是簡單的，只要透過定義 @ref{14a1,,__lt__()} 方法：

@example
>>> Student.__lt__ = lambda self, other: self.age < other.age
>>> sorted(student_objects)
[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]
@end example

然而，請注意，當 @ref{14a1,,__lt__()} 沒有被實作時，@code{<} 可以回退 (fall back) 使用 @ref{150c,,__gt__()}（有關技術上的細節資訊請看 @ref{14a1,,object.__lt__()} ）。為了避免意外發生，
@geindex Python Enhancement Proposals; PEP 8
PEP 8@footnote{https://peps.python.org/pep-0008/} 建議所有六種的比較函式都需要被實作。裝飾器 @ref{113d,,total_ordering()} 被提供用來讓任務更為簡單。

@item 
鍵函式不需要直接依賴用來排序的物件。鍵函式也可以存取外部資源，例如如果學生成績儲存在字典裡，它可以用來排序一個單獨的學生姓名串列：

@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 部份排序,,雜項說明,排序技法
@anchor{howto/sorting partial-sorts}@anchor{555f}
@subsection 部份排序


有些應用程式只需要排序部份的資料。基礎函式庫提供相較做完整排序更為輕鬆的多項工具：


@itemize *

@item 
@ref{1106,,min()} 以及 @ref{1107,,max()} 會分別回傳最小值及最大值。這些函式會將輸入資料進行一次傳遞且幾乎無須輔助記憶體。

@item 
@ref{2855,,heapq.nsmallest()} 以及 @ref{2854,,heapq.nlargest()} 會分別回傳 `n' 個最小值及最大值。這些函式會將資料進行一次傳遞且一次只會保留 `n' 個元素在記憶體中。對於相對於輸入數量較小的 `n' 個值，這些函式進行的比較比完整排序要少得多。

@item 
@ref{16b0,,heapq.heappush()} 和 @ref{16b1,,heapq.heappop()} 會建立並維持一個部份排序的資料排列，將最小的元素保持在位置 @code{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 Unicode HOWTO,如何使用 urllib 套件取得網路資源,排序技法,Python 如何達成任務
@anchor{howto/unicode doc}@anchor{5560}@anchor{howto/unicode id1}@anchor{5561}@anchor{howto/unicode translation-repo}@anchor{5562}@anchor{howto/unicode unicode-howto}@anchor{14a5}
@section Unicode HOWTO


@*發佈版本: 
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:: 
* 致謝: 致謝<10>. 

@end menu

@node Introduction to Unicode,Python's Unicode Support,,Unicode HOWTO
@anchor{howto/unicode introduction-to-unicode}@anchor{5563}
@subsection Introduction to Unicode


@menu
* 定義:: 
* Encodings:: 
* References: References<3>. 

@end menu

@node 定義,Encodings,,Introduction to Unicode
@anchor{howto/unicode definitions}@anchor{5564}
@subsubsection 定義


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<3>,定義,Introduction to Unicode
@anchor{howto/unicode encodings}@anchor{5565}
@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<3>,,Encodings,Introduction to Unicode
@anchor{howto/unicode references}@anchor{5566}
@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{5567}
@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<4>. 

@end menu

@node The String Type,Converting to Bytes,,Python's Unicode Support
@anchor{howto/unicode the-string-type}@anchor{5568}
@subsubsection The String Type


Since Python 3.0, the language's @ref{169,,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{aca,,decode()} method of
@ref{192,,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{bff,,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{fb3,,標準編碼} 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{193e,,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{21ef,,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{5569}
@subsubsection Converting to Bytes


The opposite method of @ref{aca,,bytes.decode()} is @ref{ac9,,str.encode()},
which returns a @ref{192,,bytes} representation of the Unicode string, encoded in the
requested `encoding'.

The `errors' parameter is the same as the parameter of the
@ref{aca,,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 @ref{1c,,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{556a}
@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{193e,,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 unicode-properties}@anchor{556b}
@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{556c}
@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{fd1,,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{10b,,unicodedata} module's
@ref{8dc,,normalize()} function that converts strings to one
of several normal forms, where letters followed by a combining character are
replaced with single characters.  @ref{8dc,,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{8dc,,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{fd1,,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<4>,Comparing Strings,Python's Unicode Support
@anchor{howto/unicode unicode-regular-expressions}@anchor{556d}
@subsubsection Unicode Regular Expressions


The regular expressions supported by the @ref{be,,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{838,,re.ASCII} flag to
@ref{dc9,,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{838,,re.ASCII} is supplied,
and @code{\s} will match either Unicode whitespace characters or
@code{[ \t\n\r\f\v]}.

@node References<4>,,Unicode Regular Expressions,Python's Unicode Support
@anchor{howto/unicode id2}@anchor{556e}
@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{169,,str} type is described in the Python library reference at
@ref{1ea8,,Text Sequence Type --- str}.

@ref{10b,,unicodedata} 模組的文件。

@ref{1c,,codecs} 模組的文件。

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,致謝<10>,Python's Unicode Support,Unicode HOWTO
@anchor{howto/unicode reading-and-writing-unicode-data}@anchor{556f}
@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{315,,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{1f33,,read()} and
@ref{1f22,,write()}.  This works through @ref{315,,open()}'s `encoding' and
`errors' parameters which are interpreted just like those in @ref{ac9,,str.encode()}
and @ref{aca,,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<5>. 

@end menu

@node Unicode filenames,Tips for Writing Unicode-aware Programs,,Reading and Writing Unicode Data
@anchor{howto/unicode unicode-filenames}@anchor{5570}
@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{756,,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{e4e,,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{26d,,os.stat()} will also accept Unicode
filenames.

The @ref{12fb,,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?  @ref{12fb,,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{756,,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<5>,Unicode filenames,Reading and Writing Unicode Data
@anchor{howto/unicode tips-for-writing-unicode-aware-programs}@anchor{5571}
@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{198,,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{5572}
@subsubsection Converting Between File Encodings


The @ref{1c9d,,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{1c9d,,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{5573}
@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<5>,,Tips for Writing Unicode-aware Programs,Reading and Writing Unicode Data
@anchor{howto/unicode id3}@anchor{5574}
@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 致謝<10>,,Reading and Writing Unicode Data,Unicode HOWTO
@anchor{howto/unicode acknowledgements}@anchor{5575}
@subsection 致謝


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 如何使用 urllib 套件取得網路資源,ipaddress 模組介紹,Unicode HOWTO,Python 如何達成任務
@anchor{howto/urllib2 doc}@anchor{5576}@anchor{howto/urllib2 howto-fetch-internet-resources-using-the-urllib-package}@anchor{5577}@anchor{howto/urllib2 translation-repo}@anchor{5578}@anchor{howto/urllib2 urllib-howto}@anchor{3e43}
@section 如何使用 urllib 套件取得網路資源


@*作者: 
Michael Foord@footnote{https://agileabstractions.com/}


@menu
* 簡介: 簡介<13>. 
* 從 URL 取得資源:: 
* Handling Exceptions:: 
* info and geturl:: 
* Openers and Handlers:: 
* Basic Authentication:: 
* Proxies:: 
* Sockets and Layers:: 
* 註腳:: 

@end menu

@node 簡介<13>,從 URL 取得資源,,如何使用 urllib 套件取得網路資源
@anchor{howto/urllib2 introduction}@anchor{5579}
@subsection 簡介


@subsubheading Related Articles



以下這些與 Python 有關的文章說不定能幫到你:


@itemize *

@item 
Basic Authentication@footnote{https://web.archive.org/web/20201215133350/http://www.voidspace.org.uk/python/articles/authentication.shtml}

@quotation

以 Python 為例的 `Basic Authentication' 教學。
@end quotation
@end itemize

`urllib.request' 是一個用來從 URLs (Uniform Resource Locators) 取得資料的Python模組。它提供一個了非常簡單的介面能接受多種不同的協定，`urlopen' 函式。也提供了較複雜的介面用於處理一些常見的狀況，例如：基本的 authentication、cookies、proxies 等等，這些都可以由 handler 或 opener 物件操作。

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.

一般情形下 `urlopen' 是非常容易使用的，但當你遇到錯誤或者較複雜的情況下，你可能需要對超文本協定 (HyperText Transfer Protocol) 有一定的了解。最完整且具參考價值的是 
@geindex RFC; RFC 2616
RFC 2616@footnote{https://datatracker.ietf.org/doc/html/rfc2616.html}，不過它是一份技術文件並不容易閱讀，以下的教學會提供足夠的 HTTP 知識來幫助你使用 `urllib'。這份教學並非要取代 @ref{111,,urllib.request} 這份文件，你還是會需要它。

@node 從 URL 取得資源,Handling Exceptions,簡介<13>,如何使用 urllib 套件取得網路資源
@anchor{howto/urllib2 fetching-urls}@anchor{557a}
@subsection 從 URL 取得資源


以下是使用 urllib.request 最簡單的方法:

@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{c49,,shutil.copyfileobj()} and
@ref{6e6,,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,,從 URL 取得資源
@anchor{howto/urllib2 data}@anchor{557b}
@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{110,,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,從 URL 取得資源
@anchor{howto/urllib2 headers}@anchor{557c}
@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{557d,,info and geturl}
which comes after we have a look at what happens when things go wrong.

@node Handling Exceptions,info and geturl,從 URL 取得資源,如何使用 urllib 套件取得網路資源
@anchor{howto/urllib2 handling-exceptions}@anchor{557e}
@subsection Handling Exceptions


`urlopen' raises @ref{2be,,URLError} when it cannot handle a response (though as
usual with Python APIs, built-in exceptions such as @ref{2eb,,ValueError},
@ref{198,,TypeError} etc. may also be raised).

@ref{11d9,,HTTPError} is the subclass of @ref{2be,,URLError} raised in the specific case of
HTTP URLs.

The exception classes are exported from the @ref{10f,,urllib.error} module.

@menu
* URLError:: 
* HTTPError:: 
* Wrapping it Up:: 

@end menu

@node URLError,HTTPError,,Handling Exceptions
@anchor{howto/urllib2 urlerror}@anchor{557f}
@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.

例如：

@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{5580}
@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{11d9,,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{11d9,,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{5581}
@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{3e68,,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{11d9,,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{5582}
@subsubsection Wrapping it Up


So if you want to be prepared for @ref{11d9,,HTTPError} `or' @ref{2be,,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{5583}
@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{11d9,,HTTPError}.
@end quotation
@end cartouche

@node Number 2,,Number 1,Wrapping it Up
@anchor{howto/urllib2 number-2}@anchor{5584}
@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,如何使用 urllib 套件取得網路資源
@anchor{howto/urllib2 info-and-geturl}@anchor{557d}
@subsection info and geturl


The response returned by urlopen (or the @ref{11d9,,HTTPError} instance) has two
useful methods @code{info()} and @code{geturl()} and is defined in the module
@ref{112,,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{3e81,,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,如何使用 urllib 套件取得網路資源
@anchor{howto/urllib2 openers-and-handlers}@anchor{5585}
@subsection Openers and Handlers


When you fetch a URL you use an opener (an instance of the perhaps
confusingly named @ref{3dd1,,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,如何使用 urllib 套件取得網路資源
@anchor{howto/urllib2 id5}@anchor{5586}
@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"}.

例如

@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,如何使用 urllib 套件取得網路資源
@anchor{howto/urllib2 proxies}@anchor{5587}
@subsection Proxies


`urllib' will auto-detect your proxy settings and use those. This is through
the @code{ProxyHandler}, which is part of the normal handler chain when a proxy
setting is detected.  Normally that's a good thing, but there are occasions
when it may not be helpful @footnote{
In my case I have to use a proxy to access the internet at work. If you
attempt to fetch `localhost' URLs through this proxy it blocks them. IE
is set to use the proxy, which urllib picks up on. In order to test
scripts with a localhost server, I have to prevent urllib from using
the proxy.
}. One way to do this is to setup our own
@code{ProxyHandler}, with no proxies defined. This is done using similar steps to
setting up a Basic Authentication@footnote{https://web.archive.org/web/20201215133350/http://www.voidspace.org.uk/python/articles/authentication.shtml} handler:

@example
>>> proxy_support = urllib.request.ProxyHandler(@{@})
>>> opener = urllib.request.build_opener(proxy_support)
>>> urllib.request.install_opener(opener)
@end example

@cartouche
@quotation 備註 
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{3dce,,getproxies()}.
@end quotation
@end cartouche

@node Sockets and Layers,註腳,Proxies,如何使用 urllib 套件取得網路資源
@anchor{howto/urllib2 sockets-and-layers}@anchor{5588}
@subsection Sockets and Layers


The Python support for fetching resources from the web is layered.  urllib uses
the @ref{73,,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 註腳,,Sockets and Layers,如何使用 urllib 套件取得網路資源
@anchor{howto/urllib2 footnotes}@anchor{5589}
@subsection 註腳


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 ipaddress 模組介紹,使用 DTrace 和 SystemTap 檢測 CPython,如何使用 urllib 套件取得網路資源,Python 如何達成任務
@anchor{howto/ipaddress doc}@anchor{558a}@anchor{howto/ipaddress an-introduction-to-the-ipaddress-module}@anchor{558b}@anchor{howto/ipaddress ipaddress-howto}@anchor{4081}@anchor{howto/ipaddress translation-repo}@anchor{558c}
@section ipaddress 模組介紹


@*作者: 
Peter Moody


@*作者: 
Nick Coghlan


@subsubheading 總攬



這份文件旨在為 @ref{84,,ipaddress} 模組提供一個初步介紹。文件主要針對那些不熟悉 IP 網路術語的使用者，但對想要了解 @ref{84,,ipaddress} 模組如何表示 IP 網址概念的網路工程師也可能有用。

@menu
* 建立 Address/Network/Interface 物件:: 
* 檢視 Address/Network/Interface 物件:: 
* Networks as lists of Addresses:: 
* 比較: 比較<2>. 
* Using IP Addresses with other modules:: 
* Getting more detail when instance creation fails:: 

@end menu

@node 建立 Address/Network/Interface 物件,檢視 Address/Network/Interface 物件,,ipaddress 模組介紹
@anchor{howto/ipaddress creating-address-network-interface-objects}@anchor{558d}
@subsection 建立 Address/Network/Interface 物件


Since @ref{84,,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
@ref{84,,ipaddress} to create objects from strings and integers.

@menu
* A Note on IP Versions:: 
* IP Host Addresses:: 
* 定義網路:: 
* Host Interfaces:: 

@end menu

@node A Note on IP Versions,IP Host Addresses,,建立 Address/Network/Interface 物件
@anchor{howto/ipaddress a-note-on-ip-versions}@anchor{558e}
@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,定義網路,A Note on IP Versions,建立 Address/Network/Interface 物件
@anchor{howto/ipaddress ip-host-addresses}@anchor{558f}
@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{4083,,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 定義網路,Host Interfaces,IP Host Addresses,建立 Address/Network/Interface 物件
@anchor{howto/ipaddress defining-networks}@anchor{5590}
@subsubsection 定義網路


Host addresses are usually grouped together into IP networks, so
@ref{84,,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{2eb,,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,,定義網路,建立 Address/Network/Interface 物件
@anchor{howto/ipaddress host-interfaces}@anchor{5591}
@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{84,,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 檢視 Address/Network/Interface 物件,Networks as lists of Addresses,建立 Address/Network/Interface 物件,ipaddress 模組介紹
@anchor{howto/ipaddress inspecting-address-network-interface-objects}@anchor{5592}
@subsection 檢視 Address/Network/Interface 物件


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{84,,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,比較<2>,檢視 Address/Network/Interface 物件,ipaddress 模組介紹
@anchor{howto/ipaddress networks-as-lists-of-addresses}@anchor{5593}
@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:
    # 做某些事情
@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 比較<2>,Using IP Addresses with other modules,Networks as lists of Addresses,ipaddress 模組介紹
@anchor{howto/ipaddress comparisons}@anchor{5594}
@subsection 比較


@ref{84,,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{198,,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,比較<2>,ipaddress 模組介紹
@anchor{howto/ipaddress using-ip-addresses-with-other-modules}@anchor{5595}
@subsection Using IP Addresses with other modules


Other modules that use IP addresses (such as @ref{d1,,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,ipaddress 模組介紹
@anchor{howto/ipaddress getting-more-detail-when-instance-creation-fails}@anchor{5596}
@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{2eb,,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{2eb,,ValueError} subclasses @ref{4088,,ipaddress.AddressValueError} and
@ref{40a9,,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{2eb,,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 使用 DTrace 和 SystemTap 檢測 CPython,Python 對 Linux perf 分析器的支援,ipaddress 模組介紹,Python 如何達成任務
@anchor{howto/instrumentation doc}@anchor{5597}@anchor{howto/instrumentation instrumentation}@anchor{e61}@anchor{howto/instrumentation instrumenting-cpython-with-dtrace-and-systemtap}@anchor{5598}@anchor{howto/instrumentation translation-repo}@anchor{5599}
@section 使用 DTrace 和 SystemTap 檢測 CPython


@*作者: 
David Malcolm


@*作者: 
Łukasz Langa


DTrace 和 SystemTap 都是監測工具，各自都提供了一種檢查電腦系統之行程 (process) 正在執行什麼操作的方法。它們都使用了領域限定 (domain-specific) 的語言，允許使用者編寫以下腳本：


@itemize -

@item 
過濾要觀察的行程

@item 
收集來自感興趣之行程的資料

@item 
以這些資料產生報告
@end itemize

從 Python 3.6 開始，CPython 可以使用嵌入式「標記 (marker)」（也稱為「探針 (probe)」）建置，可以透過 DTrace 或 SystemTap 腳本進行觀察，從而更輕鬆地監視系統之 CPython 行程正在執行的操作。

DTrace 標記是 CPython 直譯器的實作細節。不保證 CPython 版本之間的探針相容性。更改 CPython 版本時，DTrace 腳本可能會停止運作或錯誤地運作，而不會發出警告。

@menu
* 啟用靜態標記:: 
* 靜態 DTrace 探針:: 
* 靜態 SystemTap 標記:: 
* 可用的靜態標記:: 
* SystemTap Tapsets:: 
* 範例: 範例<57>. 

@end menu

@node 啟用靜態標記,靜態 DTrace 探針,,使用 DTrace 和 SystemTap 檢測 CPython
@anchor{howto/instrumentation enabling-the-static-markers}@anchor{559a}
@subsection 啟用靜態標記


macOS 內建了對 DTrace 的支援。在 Linux 上，為了建置帶有 SystemTap 嵌入標記的 CPython，必須安裝 SystemTap 開發工具。

在 Linux 機器上，這可以透過以下方式完成：

@example
$ yum install systemtap-sdt-devel
@end example

或是：

@example
$ sudo apt-get install systemtap-sdt-dev
@end example

然後 CPython 必須使用@ref{206c,,配置 --with-dtrace 選項}：

@example
checking for --with-dtrace... yes
@end example

在 macOS 上，你可以透過在後台運行 Python 行程並列出 Python 發布者 (provider) 所提供的所有可用探針，以列出可用的 DTrace 探針：

@example
$ python3.6 -q &
$ sudo dtrace -l -P python$!  # 或 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

在 Linux 上，你可以透過查看二進位建置檔案中是否包含 ".note.stapsdt" 部分來驗證 SystemTap 靜態標記是否存在。

@example
$ readelf -S ./python | grep .note.stapsdt
[30] .note.stapsdt        NOTE         0000000000000000 00308d78
@end example

如果你已將 Python 建置為共享函式庫（使用 @ref{a5c,,--enable-shared} 配置選項），則需要在共享函式庫中查找。例如：

@example
$ readelf -S libpython3.3dm.so.1.0 | grep .note.stapsdt
[29] .note.stapsdt        NOTE         0000000000000000 00365b68
@end example

足夠現代化的 readelf 可以印出元資料 (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

上述元資料包含 SystemTap 的資訊，描述了它如何修補策略性放置的機器碼指令以啟用 SystemTap 腳本使用的追蹤 hook。

@node 靜態 DTrace 探針,靜態 SystemTap 標記,啟用靜態標記,使用 DTrace 和 SystemTap 檢測 CPython
@anchor{howto/instrumentation static-dtrace-probes}@anchor{559b}
@subsection 靜態 DTrace 探針


以下範例示範 DTrace 腳本可用於顯示 Python 腳本的呼叫/回傳階層結構，僅在名為 "start" 的函式的呼叫內進行追蹤。換句話說，引入時的函式呼叫不會被列出：

@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

可以這樣呼叫：

@example
$ sudo dtrace -q -s call_stack.d -c "python3.6 script.py"
@end example

輸出如下所示：

@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 靜態 SystemTap 標記,可用的靜態標記,靜態 DTrace 探針,使用 DTrace 和 SystemTap 檢測 CPython
@anchor{howto/instrumentation static-systemtap-markers}@anchor{559c}
@subsection 靜態 SystemTap 標記


使用 SystemTap 整合的低階方法是直接使用靜態標記。這會需要你明確聲明包含它們的二進位檔案。

例如，此 SystemTap 腳本可用於顯示 Python 腳本的呼叫/回傳階層結構：

@example
probe process("python").mark("function__entry") @{
     filename = user_string($arg1);
     funcname = user_string($arg2);
     lineno = $arg3;

     printf("%s => %s in %s:%d\\n",
            thread_indent(1), funcname, filename, lineno);
@}

probe process("python").mark("function__return") @{
    filename = user_string($arg1);
    funcname = user_string($arg2);
    lineno = $arg3;

    printf("%s <= %s in %s:%d\\n",
           thread_indent(-1), funcname, filename, lineno);
@}
@end example

可以這樣呼叫：

@example
$ stap \
  show-call-hierarchy.stp \
  -c "./python test.py"
@end example

輸出如下所示：

@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

其中的行 (column) 是：


@itemize -

@item 
自腳本開始以來的時間（以微秒為單位）

@item 
可執行檔案的名稱

@item 
行程的 PID
@end itemize

其餘部分表示腳本執行時的呼叫/回傳階層結構。

對於以 @ref{a5c,,--enable-shared} 建置的 CPython，標記被包含在 libpython 共享函式庫中，並且探針的帶點路徑 (dotted path) 需要反映這一點。例如，上面範例中的這一列：

@example
probe process("python").mark("function__entry") @{
@end example

應該改為讀取：

@example
probe process("python").library("libpython3.6dm.so.1.0").mark("function__entry") @{
@end example

（假設 CPython 3.6 的@ref{504,,除錯建置版本}）

@node 可用的靜態標記,SystemTap Tapsets,靜態 SystemTap 標記,使用 DTrace 和 SystemTap 檢測 CPython
@anchor{howto/instrumentation available-static-markers}@anchor{559d}@anchor{howto/instrumentation static-markers}@anchor{dac}
@subsection 可用的靜態標記



@deffn {Object} function__entry(str filename, str funcname, int lineno)

該標記表示 Python 函式的執行已經開始。它僅針對純 Python（位元組碼）函式觸發。

檔案名稱、函式名稱和列號作為位置引數提供給追蹤腳本，必須使用 @code{$arg1}、@code{$arg2}、@code{$arg3} 來存取：

@quotation


@itemize *

@item 
@code{$arg1} : @code{(const char *)} 檔案名稱，可使用 @code{user_string($arg1)} 存取

@item 
@code{$arg2} ：@code{(const char *)} 函式名稱，可使用 @code{user_string($arg2)} 存取

@item 
@code{$arg3} : @code{int} 列號
@end itemize
@end quotation
@end deffn


@deffn {Object} function__return(str filename, str funcname, int lineno)

該標記與 @code{function__entry()} 相反，表示 Python 函式的執行已結束（透過 @code{return} 或透過例外）。它僅針對純 Python（位元組碼）函式觸發。

引數與 @code{function__entry()} 相同
@end deffn


@deffn {Object} line(str filename, str funcname, int lineno)

該標記表示一列 Python 即將被執行。它相當於使用 Python 分析器來逐行追蹤。它不在 C 函式內觸發。

引數與 @code{function__entry()} 相同。
@end deffn


@deffn {Object} gc__start(int generation)

當 Python 直譯器開始垃圾回收 (garbage collection) 週期時觸發。@code{arg0} 是要掃描的一代 (generation)，如 @ref{1b3,,gc.collect()}。
@end deffn


@deffn {Object} gc__done(long collected)

當 Python 直譯器完成垃圾回收週期時觸發。@code{arg0} 是收集到的物件數量。
@end deffn


@deffn {Object} import__find__load__start(str modulename)

在 @ref{7b,,importlib} 嘗試查找並載入模組之前觸發。@code{arg0} 是模組名稱。


在 3.7 版被加入.

@end deffn


@deffn {Object} import__find__load__done(str modulename, int found)

在呼叫 @ref{7b,,importlib} 的 find_and_load 函式後觸發。 @code{arg0} 是模組名稱，@code{arg1} 代表模組是否已成功載入。


在 3.7 版被加入.

@end deffn


@deffn {Object} audit(str event, void *tuple)

當呼叫 @ref{1882,,sys.audit()} 或 @ref{60b,,PySys_Audit()} 時觸發。@code{arg0} 是 C 字串形式的事件名稱，@code{arg1} 是指向元組 (tuple) 物件的 @ref{5d7,,PyObject} 指標。


在 3.8 版被加入.

@end deffn

@node SystemTap Tapsets,範例<57>,可用的靜態標記,使用 DTrace 和 SystemTap 檢測 CPython
@anchor{howto/instrumentation systemtap-tapsets}@anchor{559e}
@subsection SystemTap Tapsets


使用 SystemTap 整合的高階方法是使用 "tapset"：SystemTap 相當於一個函式庫，它隱藏了靜態標記的一些低階詳細資訊。

這是一個 tapset 檔案，是基於 CPython 的非共享建置版本：

@example
/*
   提供一個更高階、在 function__entry 和 function__return 標記上的包裝：
 \*/
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

如果此檔案是安裝在 SystemTap 的 tapset 目錄中（例如 @code{/usr/share/systemtap/tapset}），則這些額外的探測點將可被使用：


@deffn {Object} python.function.entry(str filename, str funcname, int lineno, frameptr)

該探測點表示 Python 函式的執行已經開始。它僅針對純 Python（位元組碼）函式觸發。
@end deffn


@deffn {Object} python.function.return(str filename, str funcname, int lineno, frameptr)

這個探測點與 @code{python.function.return} 相反，表示 Python 函式的執行已經結束（透過 @code{return} 或者透過例外）。它僅針對純 Python（位元組碼）函式觸發。
@end deffn

@node 範例<57>,,SystemTap Tapsets,使用 DTrace 和 SystemTap 檢測 CPython
@anchor{howto/instrumentation examples}@anchor{559f}
@subsection 範例


此 SystemTap 腳本使用上面的 tapset 來更清晰地實作上面給出的追蹤 Python 函式呼叫階層結構的範例，而無需直接命名靜態標記：

@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

以下腳本使用上面的 tapset 來提供所有正在運行之 CPython 程式碼的近乎最高層視角，顯示整個系統中每秒最常被進入的 20 個位元組碼幀 (bytecode frame)：

@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 對 Linux perf 分析器的支援,註釋 annotation 最佳實踐,使用 DTrace 和 SystemTap 檢測 CPython,Python 如何達成任務
@anchor{howto/perf_profiling doc}@anchor{19fb}@anchor{howto/perf_profiling perf-profiling}@anchor{4a9}@anchor{howto/perf_profiling python-support-for-the-linux-perf-profiler}@anchor{55a0}@anchor{howto/perf_profiling translation-repo}@anchor{55a1}
@section Python 對 Linux @code{perf} 分析器的支援


@*作者: 
Pablo Galindo


Linux 性能分析器 (Linux perf profiler)@footnote{https://perf.wiki.kernel.org} 是一個非常強大的工具，可讓你分析並取得有關應用程式的性能資訊。@code{perf} 還擁有一個非常活躍的工具生態系統，有助於分析其生成的資料。

在 Python 應用程式中使用 @code{perf} 分析器的主要問題是 @code{perf} 僅取得有關原生符號的資訊，即用 C 編寫的函式和程式的名稱。這表示程式碼中的 Python 函式名稱和檔案名稱不會出現在 @code{perf} 的輸出中。

從 Python 3.12 開始，直譯器可以在特殊模式下執行，該模式允許 Python 函式出現在 @code{perf} 分析器的輸出中。啟用此模式後，直譯器將在執行每個 Python 函式之前插入 (interpose) 一小段動態編譯的程式碼，並使用 @ref{5053,,perf map 檔案}來告訴 @code{perf} 這段程式碼與相關聯的 Python 函式間的關係。

@cartouche
@quotation 備註 
目前對 @code{perf} 分析器的支援僅適用於 Linux 的特定架構上。檢查 @code{configure} 建構步驟的輸出或檢查 @code{python -m sysconfig | grep HAVE_PERF_TRAMPOLINE} 的輸出來查看你的系統是否支援。
@end quotation
@end cartouche

例如，參考以下腳本：

@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

我們可以執行 @code{perf} 以 9999 赫茲取樣 CPU 堆疊追蹤 (stack trace)：

@example
$ perf record -F 9999 -g -o perf.data python my_script.py
@end example

然後我們可以使用 @code{perf report} 來分析資料：

@example
$ perf report --stdio -n -g

# Children      Self       Samples  Command     Shared Object       Symbol
# ........  ........  ............  ..........  ..................  ..........................................
#
    91.08%     0.00%             0  python.exe  python.exe          [.] _start
            |
            ---_start
            |
                --90.71%--__libc_start_main
                        Py_BytesMain
                        |
                        |--56.88%--pymain_run_python.constprop.0
                        |          |
                        |          |--56.13%--_PyRun_AnyFileObject
                        |          |          _PyRun_SimpleFileObject
                        |          |          |
                        |          |          |--55.02%--run_mod
                        |          |          |          |
                        |          |          |           --54.65%--PyEval_EvalCode
                        |          |          |                     _PyEval_EvalFrameDefault
                        |          |          |                     PyObject_Vectorcall
                        |          |          |                     _PyEval_Vector
                        |          |          |                     _PyEval_EvalFrameDefault
                        |          |          |                     PyObject_Vectorcall
                        |          |          |                     _PyEval_Vector
                        |          |          |                     _PyEval_EvalFrameDefault
                        |          |          |                     PyObject_Vectorcall
                        |          |          |                     _PyEval_Vector
                        |          |          |                     |
                        |          |          |                     |--51.67%--_PyEval_EvalFrameDefault
                        |          |          |                     |          |
                        |          |          |                     |          |--11.52%--_PyLong_Add
                        |          |          |                     |          |          |
                        |          |          |                     |          |          |--2.97%--_PyObject_Malloc
...
@end example

如你所見，Python 函式未顯示在輸出中，僅顯示 @code{_Py_Eval_EvalFrameDefault} （為 Python 位元組碼 (bytecode) 求值的函式）。不幸的是，這不是很有用，因為所有 Python 函式都使用相同的 C 函式來替位元組碼求值，因此我們無法知道哪個 Python 函式是對應於哪個位元組碼計算函式。

作為替代，如果我們在啟用 @code{perf} 支援的情況下執行相同的實驗，我們會得到：

@example
$ perf report --stdio -n -g

# Children      Self       Samples  Command     Shared Object       Symbol
# ........  ........  ............  ..........  ..................  .....................................................................
#
    90.58%     0.36%             1  python.exe  python.exe          [.] _start
            |
            ---_start
            |
                --89.86%--__libc_start_main
                        Py_BytesMain
                        |
                        |--55.43%--pymain_run_python.constprop.0
                        |          |
                        |          |--54.71%--_PyRun_AnyFileObject
                        |          |          _PyRun_SimpleFileObject
                        |          |          |
                        |          |          |--53.62%--run_mod
                        |          |          |          |
                        |          |          |           --53.26%--PyEval_EvalCode
                        |          |          |                     py::<module>:/src/script.py
                        |          |          |                     _PyEval_EvalFrameDefault
                        |          |          |                     PyObject_Vectorcall
                        |          |          |                     _PyEval_Vector
                        |          |          |                     py::baz:/src/script.py
                        |          |          |                     _PyEval_EvalFrameDefault
                        |          |          |                     PyObject_Vectorcall
                        |          |          |                     _PyEval_Vector
                        |          |          |                     py::bar:/src/script.py
                        |          |          |                     _PyEval_EvalFrameDefault
                        |          |          |                     PyObject_Vectorcall
                        |          |          |                     _PyEval_Vector
                        |          |          |                     py::foo:/src/script.py
                        |          |          |                     |
                        |          |          |                     |--51.81%--_PyEval_EvalFrameDefault
                        |          |          |                     |          |
                        |          |          |                     |          |--13.77%--_PyLong_Add
                        |          |          |                     |          |          |
                        |          |          |                     |          |          |--3.26%--_PyObject_Malloc
@end example

@menu
* 如何啟用 perf 分析支援:: 
* 如何獲得最佳結果:: 
* How to work without frame pointers:: 

@end menu

@node 如何啟用 perf 分析支援,如何獲得最佳結果,,Python 對 Linux perf 分析器的支援
@anchor{howto/perf_profiling how-to-enable-perf-profiling-support}@anchor{55a2}
@subsection 如何啟用 @code{perf} 分析支援


要啟用 @code{perf} 分析支援，可以在一開始就使用環境變數 
@geindex PYTHONPERFSUPPORT
@geindex 環境變數; PYTHONPERFSUPPORT
@ref{692,,PYTHONPERFSUPPORT} 或使用 @ref{16f,,-X perf} 選項，也可以使用 @ref{693,,sys.activate_stack_trampoline()} 和 @ref{694,,sys.deactivate_stack_trampoline()} 來動態啟用。

@code{sys} 函式優先於 @code{-X} 選項、@code{-X} 選項優先於環境變數。

例如，使用環境變數：

@example
$ PYTHONPERFSUPPORT=1 perf record -F 9999 -g -o perf.data python my_script.py
$ perf report -g -i perf.data
@end example

例如，使用 @code{-X} 選項：

@example
$ perf record -F 9999 -g -o perf.data python -X perf my_script.py
$ perf report -g -i perf.data
@end example

例如，在 @code{example.py} 檔案中使用 @ref{df,,sys} API：

@example
import sys

sys.activate_stack_trampoline("perf")
do_profiled_stuff()
sys.deactivate_stack_trampoline()

non_profiled_stuff()
@end example

...然後：

@example
$ perf record -F 9999 -g -o perf.data python ./example.py
$ perf report -g -i perf.data
@end example

@node 如何獲得最佳結果,How to work without frame pointers,如何啟用 perf 分析支援,Python 對 Linux perf 分析器的支援
@anchor{howto/perf_profiling how-to-obtain-the-best-results}@anchor{55a3}
@subsection 如何獲得最佳結果


為了獲得最佳結果，應使用 @code{CFLAGS="-fno-omit-frame-pointer -mno-omit-leaf-frame-pointer"} 來進行 Python 編譯，因為這能允許分析器僅使用 frame 指標而不是 DWARF 除錯資訊來解析 (unwind)。這是因為，由於插入以允許 @code{perf} 支援的程式碼是動態生成的，因此它沒有任何可用的 DWARF 除錯資訊。

你可以透過執行以下指令來檢查你的系統是否已使用此旗標進行編譯：

@example
$ python -m sysconfig | grep 'no-omit-frame-pointer'
@end example

如果你沒有看到任何輸出，則表示你的直譯器尚未使用 frame 指標進行編譯，因此它可能無法在 @code{perf} 的輸出中顯示 Python 函式。

@node How to work without frame pointers,,如何獲得最佳結果,Python 對 Linux perf 分析器的支援
@anchor{howto/perf_profiling how-to-work-without-frame-pointers}@anchor{55a4}
@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{4aa,,PYTHON_PERF_JIT_SUPPORT} or the @ref{16f,,-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

或使用環境變數：

@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 註釋 annotation 最佳實踐,隔離擴充模組,Python 對 Linux perf 分析器的支援,Python 如何達成任務
@anchor{howto/annotations doc}@anchor{55a5}@anchor{howto/annotations annotations-best-practices}@anchor{55a6}@anchor{howto/annotations annotations-howto}@anchor{9d2}@anchor{howto/annotations translation-repo}@anchor{55a7}
@section 註釋 (annotation) 最佳實踐


@*作者: 
Larry Hastings


@subsubheading 摘要



本文件旨在封裝 (encapsulate) 使用註釋字典 (annotations dicts) 的最佳實踐。如果你寫 Python 程式碼並在調查 Python 物件上的 @code{__annotations__} ，我們鼓勵你遵循下面描述的準則。

本文件分為四個部分：在 Python 3.10 及更高版本中存取物件註釋的最佳實踐、在 Python 3.9 及更早版本中存取物件註釋的最佳實踐、適用於任何Python 版本 @code{__annotations__} 的最佳實踐，以及 @code{__annotations__} 的奇異之處。

請注意，本文件是特別說明 @code{__annotations__} 的使用，而非`如何使用'註釋。如果你正在尋找如何在你的程式碼中使用「型別提示 (type hint)」的資訊，請查閱模組 (module) @ref{10a,,typing}。

@menu
* 在 Python 3.10 及更高版本中存取物件的註釋字典: 在 Python 3 10 及更高版本中存取物件的註釋字典. 
* 在 Python 3.9 及更早版本中存取物件的註釋字典: 在 Python 3 9 及更早版本中存取物件的註釋字典. 
* 手動取消字串化註釋:: 
* 任何 Python 版本中 __annotations__ 的最佳實踐:: 
* __annotations__ 奇異之處:: 

@end menu

@node 在 Python 3 10 及更高版本中存取物件的註釋字典,在 Python 3 9 及更早版本中存取物件的註釋字典,,註釋 annotation 最佳實踐
@anchor{howto/annotations accessing-the-annotations-dict-of-an-object-in-python-3-10-and-newer}@anchor{55a8}
@subsection 在 Python 3.10 及更高版本中存取物件的註釋字典


Python 3.10 在標準函式庫中新增了一個新函式：@ref{a0d,,inspect.get_annotations()}。在 Python 3.10 到 3.13，呼叫此函式是存取任何支援註釋的物件的註釋字典的最佳實踐。此函式也可以為你「取消字串化 (un-stringize)」字串化註釋。

In Python 3.14, there is a new @ref{6,,annotationlib} module
with functionality for working with annotations. This
includes a @ref{457,,annotationlib.get_annotations()} function,
which supersedes @ref{a0d,,inspect.get_annotations()}.

若由於某種原因 @ref{a0d,,inspect.get_annotations()} 對你的場合不可行，你可以手動存取 @code{__annotations__} 資料成員。 Python 3.10 中的最佳實踐也已經改變：從 Python 3.10 開始，保證 @code{o.__annotations__} `始終'適用於 Python 函式、類別 (class) 和模組。如果你確定正在檢查的物件是這三個`特定'物件之一，你可以簡單地使用 @code{o.__annotations__} 來取得物件的註釋字典。

但是，其他型別的 callable（可呼叫物件）（例如，由 @ref{217,,functools.partial()} 建立的 callable）可能沒有定義 @code{__annotations__} 屬性 (attribute)。當存取可能未知的物件的 @code{__annotations__} 時，Python 3.10 及更高版本中的最佳實踐是使用三個參數呼叫 @ref{dc5,,getattr()}，例如 @code{getattr(o, '__annotations__', None)}。

在 Python 3.10 之前，存取未定義註釋但具有註釋的父類別的類別上的 @code{__annotations__} 將傳回父類別的 @code{__annotations__}。在 Python 3.10 及更高版本中，子類別的註釋將會是一個空字典。

@node 在 Python 3 9 及更早版本中存取物件的註釋字典,手動取消字串化註釋,在 Python 3 10 及更高版本中存取物件的註釋字典,註釋 annotation 最佳實踐
@anchor{howto/annotations accessing-the-annotations-dict-of-an-object-in-python-3-9-and-older}@anchor{55a9}
@subsection 在 Python 3.9 及更早版本中存取物件的註釋字典


在 Python 3.9 及更早版本中，存取物件的註釋字典比新版本複雜得多。問題出在於這些舊版 Python 中有設計缺陷，特別是與類別註釋有關的設計缺陷。

存取其他物件（如函式、其他 callable 和模組）的註釋字典的最佳實踐與 3.10 的最佳實踐相同，假設你沒有呼叫 @ref{a0d,,inspect.get_annotations()}：你應該使用三個：參數 @ref{dc5,,getattr()} 來存取物件的 @code{__annotations__} 屬性。

不幸的是，這不是類別的最佳實踐。問題是，由於 @code{__annotations__} 在類別上是選填的 (optional)，並且因為類別可以從其基底類別 (base class) 繼承屬性，所以存取類別的 @code{__annotations__} 屬性可能會無意中回傳`基底類別的註釋字典。'舉例來說：

@example
class Base:
    a: int = 3
    b: str = 'abc'

class Derived(Base):
    pass

print(Derived.__annotations__)
@end example

這將印出 (print) 來自 @code{Base} 的註釋字典，而不是 @code{Derived}。

如果你正在檢查的物件是一個類別 (@code{isinstance(o, type)})，你的程式碼將必須有一個單獨的程式碼路徑。在這種情況下，最佳實踐依賴 Python 3.9 及之前版本的實作細節 (implementation detail)：如果一個類別定義了註釋，它們將儲存在該類別的 @ref{e52,,__dict__} 字典中。由於類別可能定義了註釋，也可能沒有定義，因此最佳實踐是在類別字典上呼叫 @ref{1efb,,get()} 方法。

總而言之，以下是一些範例程式碼，可以安全地存取 Python 3.9 及先前版本中任意物件上的 @code{__annotations__} 屬性：

@example
if isinstance(o, type):
    ann = o.__dict__.get('__annotations__', None)
else:
    ann = getattr(o, '__annotations__', None)
@end example

運行此程式碼後，@code{ann} 應該是字典或 @code{None}。我們鼓勵你在進一步檢查之前使用 @ref{2ad,,isinstance()} 仔細檢查 @code{ann} 的型別。

請注意，某些外來 (exotic) 或格式錯誤 (malform) 的型別物件可能沒有 @ref{e52,,__dict__} 屬性，因此為了額外的安全，你可能還希望使用 @ref{dc5,,getattr()} 來存取 @code{__dict__}。

@node 手動取消字串化註釋,任何 Python 版本中 __annotations__ 的最佳實踐,在 Python 3 9 及更早版本中存取物件的註釋字典,註釋 annotation 最佳實踐
@anchor{howto/annotations manually-un-stringizing-stringized-annotations}@anchor{55aa}
@subsection 手動取消字串化註釋


在某些註釋可能被「字串化」的情況下，並且你希望評估這些字串以產生它們表示的 Python 值，最好呼叫 @ref{a0d,,inspect.get_annotations()} 來為你完成這項工作。

如果你使用的是 Python 3.9 或更早版本，或者由於某種原因你無法使用 @ref{a0d,,inspect.get_annotations()}，則需要複製其邏輯。我們鼓勵你檢查目前 Python 版本中 @ref{a0d,,inspect.get_annotations()} 的實作並遵循類似的方法。

簡而言之，如果你希望評估任意物件 @code{o} 上的字串化註釋：


@itemize *

@item 
如果 @code{o} 是一個模組，則在呼叫 @ref{49e,,eval()} 時使用 @code{o.__dict__} 作為@code{全域變數}。

@item 
如果 @code{o} 是一個類別，當呼叫 @ref{49e,,eval()} 時，則使用 @code{sys.modules[o.__module__].__dict__} 作為@code{全域變數}，使用 @code{dict(vars(o))} 作為@code{區域變數}。

@item 
如果 @code{o} 是使用 @ref{121d,,functools.update_wrapper()}、@ref{1158,,functools.wraps()} 或 @ref{217,,functools.partial()} 包裝的 callable ，請依據需求，透過存取 @code{o.__wrapped__} 或 @code{o.func} 來疊代解開它，直到找到根解包函式。

@item 
如果 @code{o} 是 callable（但不是類別），則在呼叫 @ref{49e,,eval()} 時使用 @ref{14d4,,o.__globals__} 作為全域變數。
@end itemize

然而，並非所有用作註釋的字串值都可以透過 @ref{49e,,eval()} 成功轉換為 Python 值。理論上，字串值可以包含任何有效的字串，並且在實踐中，型別提示存在有效的用例，需要使用特定「無法」評估的字串值進行註釋。例如：


@itemize *

@item 
在 Python 3.10 支援 
@geindex Python Enhancement Proposals; PEP 604
PEP 604@footnote{https://peps.python.org/pep-0604/} 聯合型別 (union type) @code{|} 之前使用它。

@item 
Runtime 中不需要的定義，僅在 @ref{eeb,,typing.TYPE_CHECKING} 為 true 時匯入。
@end itemize

如果 @ref{49e,,eval()} 嘗試計算這類型的值，它將失敗並引發例外。因此，在設計使用註釋的函式庫 API 時，建議僅在呼叫者 (caller) 明確請求時嘗試評估字串值。

@node 任何 Python 版本中 __annotations__ 的最佳實踐,__annotations__ 奇異之處,手動取消字串化註釋,註釋 annotation 最佳實踐
@anchor{howto/annotations best-practices-for-annotations-in-any-python-version}@anchor{55ab}
@subsection 任何 Python 版本中 @code{__annotations__} 的最佳實踐



@itemize *

@item 
你應該避免直接指派給物件的 @code{__annotations__} 成員。讓 Python 管理設定 @code{__annotations__}。

@item 
如果你直接指派給物件的 @code{__annotations__} 成員，則應始終將其設為 @code{dict} 物件。

@item 
You should avoid accessing @code{__annotations__} directly on any object.
Instead, use @ref{457,,annotationlib.get_annotations()} (Python 3.14+)
or @ref{a0d,,inspect.get_annotations()} (Python 3.10+).

@item 
如果直接存取物件的 @code{__annotations__} 成員，則應確保它是字典，然後再嘗試檢查其內容。

@item 
你應該避免修改 @code{__annotations__} 字典。

@item 
你應該避免刪除物件的 @code{__annotations__} 屬性。
@end itemize

@node __annotations__ 奇異之處,,任何 Python 版本中 __annotations__ 的最佳實踐,註釋 annotation 最佳實踐
@anchor{howto/annotations annotations-quirks}@anchor{55ac}
@subsection @code{__annotations__} 奇異之處


在 Python 3 的所有版本中，如果沒有在該物件上定義註釋，則函式物件會延遲建立 (lazy-create) 註釋字典。你可以使用 @code{del fn.__annotations__} 刪除 @code{__annotations__} 屬性，但如果你隨後存取 @code{fn.__annotations__}，該物件將建立一個新的空字典，它將作為註釋儲存並傳回。在函式延遲建立註釋字典之前刪除函式上的註釋將拋出 @code{AttributeError}；連續兩次使用 @code{del fn.__annotations__} 保證總是拋出 @code{AttributeError} 。

上一段的所有內容也適用於 Python 3.10 及更高版本中的類別和模組物件。

在 Python 3 的所有版本中，你可以將函式物件上的 @code{__annotations__} 設定為 @code{None}。但是，隨後使用 @code{fn.__annotations__} 存取該物件上的註釋將根據本節第一段的內容延遲建立一個空字典。對於任何 Python 版本中的模組和類別來說，情況`並非如此'；這些物件允許將  @code{__annotations__} 設定為任何 Python 值，並且將保留設定的任何值。

如果 Python 為你字串化你的註釋（使用 @code{from __future__ import annotations}），並且你指定一個字串作為註釋，則該字串本身將被引用。實際上，註釋被引用了`兩次。'例如：

@example
from __future__ import annotations
def foo(a: "str"): pass

print(foo.__annotations__)
@end example

這會印出 @code{@{'a': "'str'"@}}。這不應該被認為是一個「奇異的事」，他在這裡被簡單提及，因為他可能會讓人意想不到。

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{457,,annotationlib.get_annotations()} on Python 3.14+ or
@ref{a0d,,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{e52,,__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{f3f,,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 隔離擴充模組,計時器檔案描述器 timerfd 指南,註釋 annotation 最佳實踐,Python 如何達成任務
@anchor{howto/isolating-extensions doc}@anchor{55ad}@anchor{howto/isolating-extensions isolating-extension-modules}@anchor{55ae}@anchor{howto/isolating-extensions isolating-extensions-howto}@anchor{166}@anchor{howto/isolating-extensions translation-repo}@anchor{55af}
@section 隔離擴充模組


@subsubheading 摘要



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:: 
* 背景: 背景<2>. 
* Making Modules Safe with Multiple Interpreters:: 
* Heap Types:: 
* Open Issues:: 

@end menu

@node Who should read this,背景<2>,,隔離擴充模組
@anchor{howto/isolating-extensions who-should-read-this}@anchor{55b0}
@subsection Who should read this


This guide is written for maintainers of @ref{1e85,,C-API} extensions
who would like to make that extension safer to use in applications where
Python itself is used as a library.

@node 背景<2>,Making Modules Safe with Multiple Interpreters,Who should read this,隔離擴充模組
@anchor{howto/isolating-extensions background}@anchor{55b1}
@subsection 背景


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{4f97,,Py_InitializeEx()}/@ref{f0c,,Py_FinalizeEx()}
cycles, and

@item 
in parallel, managing "sub-interpreters" using
@ref{1a72,,Py_NewInterpreter()}/@ref{17c3,,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,,背景<2>
@anchor{howto/isolating-extensions enter-per-module-state}@anchor{55b2}
@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{5d7,,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,背景<2>
@anchor{howto/isolating-extensions isolated-module-objects}@anchor{55b3}
@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  # 建立一個新的模組物件
>>> 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{55b4,,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,背景<2>
@anchor{howto/isolating-extensions surprising-edge-cases}@anchor{55b5}
@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{55b3,,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>,隔離擴充模組
@anchor{howto/isolating-extensions making-modules-safe-with-multiple-interpreters}@anchor{55b6}
@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{55b4}
@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{4fff,,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{55b7}
@subsubsection Managing Per-Module State


To use per-module state, use
@ref{5003,,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{1abb,,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{4fff}@anchor{howto/isolating-extensions opt-out-limiting-to-one-module-object-per-process}@anchor{55b8}
@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{b69,,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{f0c,,Py_FinalizeEx()}) and re-initialization
(@ref{45e,,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{55b9}
@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,Open Issues,Making Modules Safe with Multiple Interpreters,隔離擴充模組
@anchor{howto/isolating-extensions heap-types}@anchor{55ba}
@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
@anchor{howto/isolating-extensions changing-static-types-to-heap-types}@anchor{55bb}
@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{3cd,,Py_TPFLAGS_IMMUTABLETYPE} flag to prevent mutability.

@item 
Heap types inherit @ref{798,,tp_new} by default,
so it may become possible to instantiate them from Python code.
You can prevent this with the @ref{79b,,Py_TPFLAGS_DISALLOW_INSTANTIATION} flag.
@end itemize

@node Defining Heap Types,Garbage-Collection Protocol,Changing Static Types to Heap Types,Heap Types
@anchor{howto/isolating-extensions defining-heap-types}@anchor{55bc}
@subsubsection Defining Heap Types


Heap types can be created by filling a @ref{19db,,PyType_Spec} structure, a
description or "blueprint" of a class, and calling
@ref{76c,,PyType_FromModuleAndSpec()} to construct a new class object.

@cartouche
@quotation 備註 
Other functions, like @ref{796,,PyType_FromSpec()}, can also create
heap types, but @ref{76c,,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
@anchor{howto/isolating-extensions garbage-collection-protocol}@anchor{55bd}
@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{978,,Py_TPFLAGS_HAVE_GC} flag.

@item 
Define a traverse function using @code{Py_tp_traverse}, which
visits the type (e.g. using @code{Py_VISIT(Py_TYPE(self))}).
@end itemize

Please refer to the documentation of
@ref{978,,Py_TPFLAGS_HAVE_GC} and @ref{979,,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:: 
* 定義 tp_dealloc:: 
* Not overriding tp_free:: 
* 避免使用 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{55be}
@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{37f,,Py_Version} was only added in Python 3.11.
As a replacement, use:


@itemize *

@item 
@ref{380,,PY_VERSION_HEX}, if not using the stable ABI, or

@item 
@ref{8a7,,sys.version_info} (via @ref{622,,PySys_GetObject()} and
@ref{3bf,,PyArg_ParseTuple()}).
@end itemize

@node Delegating tp_traverse,定義 tp_dealloc,tp_traverse in Python 3 8 and lower,Garbage-Collection Protocol
@anchor{howto/isolating-extensions delegating-tp-traverse}@anchor{55bf}
@subsubsection Delegating @code{tp_traverse}


If your traverse function delegates to the @ref{979,,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{798,,tp_new} and @ref{4daa,,tp_clear}.

@node 定義 tp_dealloc,Not overriding tp_free,Delegating tp_traverse,Garbage-Collection Protocol
@anchor{howto/isolating-extensions defining-tp-dealloc}@anchor{55c0}
@subsubsection 定義 @code{tp_dealloc}


If your type has a custom @ref{4d84,,tp_dealloc} function,
it needs to:


@itemize -

@item 
call @ref{16f9,,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,避免使用 PyObject_New,定義 tp_dealloc,Garbage-Collection Protocol
@anchor{howto/isolating-extensions not-overriding-tp-free}@anchor{55c1}
@subsubsection Not overriding @code{tp_free}


The @ref{4d97,,tp_free} slot of a heap type must be set to
@ref{16f7,,PyObject_GC_Del()}.
This is the default; do not override it.

@node 避免使用 PyObject_New,,Not overriding tp_free,Garbage-Collection Protocol
@anchor{howto/isolating-extensions avoiding-pyobject-new}@anchor{55c2}
@subsubsection 避免使用 @code{PyObject_New}


GC-tracked objects need to be allocated using GC-aware functions.

If you use @ref{b73,,PyObject_New()} or @ref{b74,,PyObject_NewVar()}:


@itemize -

@item 
Get and call type's @ref{4d98,,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{c90,,PyObject_GC_New()} or @ref{c91,,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
@anchor{howto/isolating-extensions module-state-access-from-classes}@anchor{55c3}
@subsubsection Module State Access from Classes


If you have a type object defined with @ref{76c,,PyType_FromModuleAndSpec()},
you can call @ref{b5d,,PyType_GetModule()} to get the associated module, and then
@ref{b6e,,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{b5e,,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
@anchor{howto/isolating-extensions module-state-access-from-regular-methods}@anchor{55c4}
@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{1958,,METH_METHOD | METH_FASTCALL | METH_KEYWORDS}
@ref{16cb,,calling convention}
and the corresponding @ref{960,,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{b5e,,PyType_GetModuleState()} to get
the state of its associated module.

舉例來說：

@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
@anchor{howto/isolating-extensions module-state-access-from-slot-methods-getters-and-setters}@anchor{55c5}
@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{50cf,,nb_add} for @ref{228f,,__add__} or
@ref{798,,tp_new} for initialization—have a very simple API that
doesn't allow passing in the defining class, unlike with @ref{960,,PyCMethod}.
The same goes for getters and setters defined with
@ref{dad,,PyGetSetDef}.

To access the module state in these cases, use the
@ref{62d,,PyType_GetModuleByDef()} function, and pass in the module definition.
Once you have the module, call @ref{b6e,,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{248c,,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
@anchor{howto/isolating-extensions lifetime-of-the-module-state}@anchor{55c6}
@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{76c,,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,隔離擴充模組
@anchor{howto/isolating-extensions open-issues}@anchor{55c7}
@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{55c8}
@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{55c9}
@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 計時器檔案描述器 timerfd 指南,The Python 2 3 Method Resolution Order,隔離擴充模組,Python 如何達成任務
@anchor{howto/timerfd doc}@anchor{55ca}@anchor{howto/timerfd timer-file-descriptor-howto}@anchor{55cb}@anchor{howto/timerfd timerfd-howto}@anchor{55cc}@anchor{howto/timerfd translation-repo}@anchor{55cd}
@section 計時器檔案描述器 (timerfd) 指南


@*發佈版本: 
1.13


此篇指南探討 Python 對 Linux 計時器檔案描述器的支援。

@menu
* 範例: 範例<58>. 

@end menu

@node 範例<58>,,,計時器檔案描述器 timerfd 指南
@anchor{howto/timerfd examples}@anchor{55ce}
@subsection 範例


以下範例顯示如何使用計時器檔案描述器來每秒執行函式兩次：

@example
# 實際腳本應該使用非阻塞計時器，
# 在這裡為了簡單起見我們使用阻塞計時器。
import os, time

# 建立計時器檔案描述器
fd = os.timerfd_create(time.CLOCK_REALTIME)

# 在 1 秒後開始計時器，間隔為半秒
os.timerfd_settime(fd, initial=1, interval=0.5)

try:
    # 處理計時器事件四次。
    for _ in range(4):
        # read() 會阻塞直到計時器到期
        _ = os.read(fd, 8)
        print("Timer expired")
finally:
    # 記得關閉計時器檔案描述器！
    os.close(fd)
@end example

為了避免由 @ref{196,,float} 型別造成的精度損失，計時器檔案描述器允許使用函式的 @code{_ns} 變體以整數奈秒為單位指定初始到期時間和間隔。

此範例展示如何將 @ref{118f,,epoll()} 與計時器檔案描述器一起使用，用於等待檔案描述器直到它準備好讀取：

@example
import os, time, select, socket, sys

# 建立 epoll 物件
ep = select.epoll()

# 在此範例中，使用回送位址 (loopback address) 向伺服器發送 "stop" 命令。
#
# $ 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)

# 以非阻塞模式建立計時器檔案描述器。
num = 3
fds = []
for _ in range(num):
    fd = os.timerfd_create(time.CLOCK_REALTIME, flags=os.TFD_NONBLOCK)
    fds.append(fd)
    # 為讀取事件註冊計時器檔案描述器
    ep.register(fd, select.EPOLLIN)

# 使用 os.timerfd_settime_ns() 以奈秒為單位啟動計時器。
# 計時器 1 每 0.25 秒觸發一次；計時器 2 每 0.5 秒觸發一次；以此類推
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:
        # 等待計時器在 3 秒內到期。
        # epoll.poll() 回傳一個 (fd, event) 配對的串列。
        # fd 是檔案描述器。
        # sock 和 conn[=socket.accept() 的回傳值] 是 socket 物件，不是檔案描述器。
        # 所以要使用 sock.fileno() 和 conn.fileno() 來取得檔案描述器。
        events = ep.poll(timeout)

        # 如果同時有多個計時器檔案描述器準備好讀取，
        # epoll.poll() 會回傳一個 (fd, event) 配對的串列。
        #
        # 在此範例設定中，
        #    第 1 個計時器在 0.25 秒內每 0.25 秒觸發一次。(0.25, 0.5, 0.75, 1.0, ...)
        #    第 2 個計時器在 0.5 秒內每 0.5 秒觸發一次。(0.5, 1.0, 1.5, 2.0, ...)
        #    第 3 個計時器在 0.75 秒內每 0.75 秒觸發一次。(0.75, 1.5, 2.25, 3.0, ...)
        #
        #    在 0.25 秒時，只有第 1 個計時器觸發。
        #    在 0.5 秒時，第 1 個計時器和第 2 個計時器同時觸發。
        #    在 0.75 秒時，第 1 個計時器和第 3 個計時器同時觸發。
        #    在 1.5 秒時，第 1、2、3 個計時器同時觸發。
        #
        # 如果計時器檔案描述器自上次 os.read() 呼叫以來被觸發多次，
        # os.read() 會以主機類別位元組順序回傳被觸發次數。
        print(f"Signaled events=@{events@}")
        for fd, event in events:
            if event & select.EPOLLIN:
                if fd == sock.fileno():
                    # 檢查是否有連線請求。
                    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():
                    # 檢查是否有資料要讀取。
                    print(f"Reading data @{fd@}")
                    data = conn.recv(1024)
                    if data:
                        # 為了安全起見，你應該捕獲 UnicodeDecodeError 例外。
                        cmd = data.decode()
                        if cmd.startswith("stop"):
                            print(f"Stopping server")
                            is_active = False
                        else:
                            print(f"Unknown command: @{cmd@}")
                    else:
                        # 沒有更多資料，關閉連線
                        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

此範例展示如何將 @ref{f9b,,select()} 與計時器檔案描述器一起使用，用於等待檔案描述器直到它準備好讀取：

@example
import os, time, select, socket, sys

# 在此範例中，使用回送位址向伺服器發送 "stop" 命令。
#
# $ 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)

# 以非阻塞模式建立計時器檔案描述器。
num = 3
fds = [os.timerfd_create(time.CLOCK_REALTIME, flags=os.TFD_NONBLOCK)
       for _ in range(num)]
select_fds = fds + [sock]

# 使用 os.timerfd_settime() 以秒為單位啟動計時器。
# 計時器 1 每 0.25 秒觸發一次；計時器 2 每 0.5 秒觸發一次；以此類推
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:
       # 等待計時器在 3 秒內到期。
       # select.select() 回傳檔案描述器或物件的串列。
       rfd, wfd, xfd = select.select(select_fds, select_fds, select_fds, timeout)
       for fd in rfd:
           if fd == sock:
               # 檢查是否有連線請求。
               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:
               # 檢查是否有資料要讀取。
               print(f"Reading data @{fd@}")
               data = conn.recv(1024)
               if data:
                   # 為了安全起見，你應該捕獲 UnicodeDecodeError 例外。
                   cmd = data.decode()
                   if cmd.startswith("stop"):
                       print(f"Stopping server")
                       is_active = False
                   else:
                       print(f"Unknown command: @{cmd@}")
               else:
                   # 沒有更多資料，關閉連線
                   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 自由執行緒的支援,計時器檔案描述器 timerfd 指南,Python 如何達成任務
@anchor{howto/mro doc}@anchor{55cf}@anchor{howto/mro python-2-3-mro}@anchor{169e}@anchor{howto/mro the-python-2-3-method-resolution-order}@anchor{55d0}@anchor{howto/mro translation-repo}@anchor{55d1}
@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/}.

@*摘要: 
`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

致謝

@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:: 
* 範例: 範例<59>. 
* 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{55d2}
@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,範例<59>,The beginning,The Python 2 3 Method Resolution Order
@anchor{howto/mro the-c3-method-resolution-order}@anchor{55d3}
@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 範例<59>,Bad Method Resolution Orders,The C3 Method Resolution Order,The Python 2 3 Method Resolution Order
@anchor{howto/mro examples}@anchor{55d4}
@subsection 範例


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{222b,,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,範例<59>,The Python 2 3 Method Resolution Order
@anchor{howto/mro bad-method-resolution-orders}@anchor{55d5}
@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{55d6}
@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{55d7}
@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 自由執行緒的支援,支援自由執行緒的 C API 擴充,The Python 2 3 Method Resolution Order,Python 如何達成任務
@anchor{howto/free-threading-python doc}@anchor{55d8}@anchor{howto/free-threading-python freethreading-python-howto}@anchor{55d9}@anchor{howto/free-threading-python python-support-for-free-threading}@anchor{55da}@anchor{howto/free-threading-python translation-repo}@anchor{55db}
@section Python 自由執行緒的支援


Starting with the 3.13 release, CPython has support for a build of
Python called @ref{1f4,,free threading} where the @ref{46e,,global interpreter lock}
(GIL) is disabled.  Free-threaded execution allows for full utilization of the
available processing power by running threads in parallel on available CPU cores.
While not all software will benefit from this automatically, programs
designed with threading in mind will run faster on multi-core hardware.

The free-threaded mode is working and continues to be improved, but
there is some additional overhead in single-threaded workloads compared
to the regular build. Additionally, third-party packages, in particular ones
with an @ref{2115,,extension module}, may not be ready for use in a
free-threaded build, and will re-enable the @ref{164,,GIL}.

This document describes the implications of free threading
for Python code.  See @ref{55dc,,支援自由執行緒的 C API 擴充} 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
* 安裝: 安裝<2>. 
* Identifying free-threaded Python:: 
* The global interpreter lock in free-threaded Python:: 
* 執行緒安全: 執行緒安全<2>. 
* 已知限制:: 
* Behavioral changes:: 

@end menu

@node 安裝<2>,Identifying free-threaded Python,,Python 自由執行緒的支援
@anchor{howto/free-threading-python installation}@anchor{55dd}
@subsection 安裝


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{494,,--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,安裝<2>,Python 自由執行緒的支援
@anchor{howto/free-threading-python identifying-free-threaded-python}@anchor{55de}
@subsection Identifying free-threaded Python


To check if the current interpreter supports free-threading, @ref{496,,python -VV}
and @ref{497,,sys.version} contain "free-threading build".
The new @ref{47de,,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,執行緒安全<2>,Identifying free-threaded Python,Python 自由執行緒的支援
@anchor{howto/free-threading-python the-global-interpreter-lock-in-free-threaded-python}@anchor{55df}
@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{495,,PYTHON_GIL} or
the command-line option @ref{16f,,-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 執行緒安全<2>,已知限制,The global interpreter lock in free-threaded Python,Python 自由執行緒的支援
@anchor{howto/free-threading-python thread-safety}@anchor{55e0}
@subsection 執行緒安全


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{183,,dict}, @ref{24d,,list}, and @ref{184,,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{1943,,threading.Lock} or other synchronization
primitives instead of relying on the internal locks of built-in types, when
possible.
@end quotation
@end cartouche

@node 已知限制,Behavioral changes,執行緒安全<2>,Python 自由執行緒的支援
@anchor{howto/free-threading-python known-limitations}@anchor{55e1}
@subsection 已知限制


This section describes known limitations of the free-threaded CPython build.

@menu
* 不滅化 (Immortalization): 不滅化 Immortalization. 
* Frame objects: Frame objects<2>. 
* 疊代器: 疊代器<2>. 
* 單執行緒效能:: 

@end menu

@node 不滅化 Immortalization,Frame objects<2>,,已知限制
@anchor{howto/free-threading-python immortalization}@anchor{55e2}
@subsubsection 不滅化 (Immortalization)


The free-threaded build of the 3.13 release makes some objects @ref{290,,immortal}.
Immortal objects are not deallocated and have reference counts that are
never modified.  This is done to avoid reference count contention that would
prevent efficient multi-threaded scaling.

An object will be made immortal when a new thread is started for the first time
after the main thread is running.  The following objects are immortalized:


@itemize *

@item 
在模組層級宣告的@ref{596,,函式}物件

@item 
@ref{1f6e,,方法}描述器

@item 
@ref{4e1,,程式碼}物件

@item 
@ref{192d,,模組}物件及其字典

@item 
@ref{220d,,類別}（型別物件）
@end itemize

Because immortal objects are never deallocated, applications that create many
objects of these types may see increased memory usage.  This is expected to be
addressed in the 3.14 release.

Additionally, numeric and string literals in the code as well as strings
returned by @ref{14dc,,sys.intern()} are also immortalized.  This behavior is
expected to remain in the 3.14 free-threaded build.

@node Frame objects<2>,疊代器<2>,不滅化 Immortalization,已知限制
@anchor{howto/free-threading-python frame-objects}@anchor{55e3}
@subsubsection Frame objects


It is not safe to access @ref{8e7,,frame} objects from other
threads and doing so may cause your program to crash .  This means that
@ref{162a,,sys._current_frames()} is generally not safe to use in a free-threaded
build.  Functions like @ref{8e9,,inspect.currentframe()} and @ref{8e8,,sys._getframe()}
are generally safe as long as the resulting frame object is not passed to
another thread.

@node 疊代器<2>,單執行緒效能,Frame objects<2>,已知限制
@anchor{howto/free-threading-python iterators}@anchor{55e4}
@subsubsection 疊代器


Sharing the same iterator object between multiple threads is generally not
safe and threads may see duplicate or missing elements when iterating or crash
the interpreter.

@node 單執行緒效能,,疊代器<2>,已知限制
@anchor{howto/free-threading-python single-threaded-performance}@anchor{55e5}
@subsubsection 單執行緒效能


The free-threaded build has additional overhead when executing Python code
compared to the default GIL-enabled build.  In 3.13, this overhead is about
40% on the pyperformance@footnote{https://pyperformance.readthedocs.io/} suite.
Programs that spend most of their time in C extensions or I/O will see
less of an impact.  The largest impact is because the specializing adaptive
interpreter (
@geindex Python Enhancement Proposals; PEP 659
PEP 659@footnote{https://peps.python.org/pep-0659/}) is disabled in the free-threaded build.  We expect
to re-enable it in a thread-safe way in the 3.14 release.  This overhead is
expected to be reduced in upcoming Python release.   We are aiming for an
overhead of 10% or less on the pyperformance suite compared to the default
GIL-enabled build.

@node Behavioral changes,,已知限制,Python 自由執行緒的支援
@anchor{howto/free-threading-python behavioral-changes}@anchor{55e6}
@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{55e7}
@subsubsection Context variables


In the free-threaded build, the flag @ref{175,,thread_inherit_context}
is set to true by default which causes threads created with
@ref{176,,threading.Thread} to start with a copy of the
@ref{177,,Context()} of the caller of
@ref{178,,start()}.  In the default GIL-enabled build, the flag
defaults to false so threads start with an
empty @ref{177,,Context()}.

@node Warning filters,,Context variables,Behavioral changes
@anchor{howto/free-threading-python warning-filters}@anchor{55e8}
@subsubsection Warning filters


In the free-threaded build, the flag @ref{18a,,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{179,,warnings.catch_warnings}
context manager uses a context variable for warning filters.  If the flag is
false then @ref{179,,catch_warnings} modifies the global filters list,
which is not thread-safe.  See the @ref{118,,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 擴充,Remote debugging attachment protocol,Python 自由執行緒的支援,Python 如何達成任務
@anchor{howto/free-threading-extensions doc}@anchor{55e9}@anchor{howto/free-threading-extensions c-api-extension-support-for-free-threading}@anchor{55ea}@anchor{howto/free-threading-extensions freethreading-extensions-howto}@anchor{55dc}@anchor{howto/free-threading-extensions translation-repo}@anchor{55eb}
@section 支援自由執行緒的 C API 擴充


Starting with the 3.13 release, CPython has support for running with
the @ref{46e,,global interpreter lock} (GIL) disabled in a configuration
called @ref{1f4,,free threading}.  This document describes how to adapt C API
extensions to support free threading.

@menu
* Identifying the Free-Threaded Build in C:: 
* 模組初始化:: 
* General API Guidelines:: 
* 借用參照:: 
* 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,模組初始化,,支援自由執行緒的 C API 擴充
@anchor{howto/free-threading-extensions identifying-the-free-threaded-build-in-c}@anchor{55ec}
@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{174,,sysconfig.get_config_var()} function
can be used to determine whether the current running interpreter had the
macro defined.
@end quotation
@end cartouche

@node 模組初始化,General API Guidelines,Identifying the Free-Threaded Build in C,支援自由執行緒的 C API 擴充
@anchor{howto/free-threading-extensions module-initialization}@anchor{55ed}
@subsection 模組初始化


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): 單一階段初始化 Single-Phase Initialization. 

@end menu

@node Multi-Phase Initialization,單一階段初始化 Single-Phase Initialization,,模組初始化
@anchor{howto/free-threading-extensions multi-phase-initialization}@anchor{55ee}
@subsubsection Multi-Phase Initialization


Extensions that use multi-phase initialization (i.e.,
@ref{4d6b,,PyModuleDef_Init()}) should add a @ref{47d,,Py_mod_gil} slot in the
module definition.  If your extension supports older versions of CPython,
you should guard the slot with a @ref{380,,PY_VERSION_HEX} check.

@example
static struct PyModuleDef_Slot module_slots[] = @{
    ...
#if PY_VERSION_HEX >= 0x030D0000
    @{Py_mod_gil, Py_MOD_GIL_NOT_USED@},
#endif
    @{0, NULL@}
@};

static struct PyModuleDef moduledef = @{
    PyModuleDef_HEAD_INIT,
    .m_slots = module_slots,
    ...
@};
@end example

@node 單一階段初始化 Single-Phase Initialization,,Multi-Phase Initialization,模組初始化
@anchor{howto/free-threading-extensions single-phase-initialization}@anchor{55ef}
@subsubsection 單一階段初始化 (Single-Phase Initialization)


Extensions that use single-phase initialization (i.e.,
@ref{5007,,PyModule_Create()}) should call @ref{498,,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,借用參照,模組初始化,支援自由執行緒的 C API 擴充
@anchor{howto/free-threading-extensions general-api-guidelines}@anchor{55f0}
@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{4e10,,PyList_GET_ITEM},
@ref{627,,PyList_SET_ITEM}, and macros like
@ref{3c8,,PySequence_Fast_GET_SIZE} that use the object returned by
@ref{1817,,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{3d5,,borrowed references} may not be thread-safe if
the containing object is modified concurrently.  See the section on
@ref{55f1,,borrowed references} for more information.
@end itemize

@menu
* 容器執行緒安全性:: 

@end menu

@node 容器執行緒安全性,,,General API Guidelines
@anchor{howto/free-threading-extensions container-thread-safety}@anchor{55f2}
@subsubsection 容器執行緒安全性


Containers like @ref{5089,,PyListObject},
@ref{647,,PyDictObject}, and @ref{5193,,PySetObject} perform internal locking
in the free-threaded build.  For example, the @ref{4ec7,,PyList_Append()} will
lock the list before appending an item.

@menu
* PyDict_Next:: 

@end menu

@node PyDict_Next,,,容器執行緒安全性
@anchor{howto/free-threading-extensions id1}@anchor{55f3}@anchor{howto/free-threading-extensions pydict-next}@anchor{55f4}
@subsubsection @code{PyDict_Next}


A notable exception is @ref{18e9,,PyDict_Next()}, which does not lock the
dictionary.  You should use @ref{518a,,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 借用參照,Memory Allocation APIs,General API Guidelines,支援自由執行緒的 C API 擴充
@anchor{howto/free-threading-extensions borrowed-references}@anchor{55f5}
@subsection 借用參照

@anchor{howto/free-threading-extensions id2}@anchor{55f1}
Some C API functions return @ref{3d5,,borrowed references}.
These APIs are not thread-safe if the containing object is modified
concurrently.  For example, it's not safe to use @ref{5f7,,PyList_GetItem()}
if the list may be modified concurrently.

The following table lists some borrowed reference APIs and their replacements
that return @ref{5da,,strong references}.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

借用參照 API

@tab

強參照 API

@item

@ref{5f7,,PyList_GetItem()}

@tab

@ref{5f6,,PyList_GetItemRef()}

@item

@ref{4e10,,PyList_GET_ITEM()}

@tab

@ref{5f6,,PyList_GetItemRef()}

@item

@ref{620,,PyDict_GetItem()}

@tab

@ref{5d8,,PyDict_GetItemRef()}

@item

@ref{5d9,,PyDict_GetItemWithError()}

@tab

@ref{5d8,,PyDict_GetItemRef()}

@item

@ref{621,,PyDict_GetItemString()}

@tab

@ref{41f,,PyDict_GetItemStringRef()}

@item

@ref{5dc,,PyDict_SetDefault()}

@tab

@ref{5db,,PyDict_SetDefaultRef()}

@item

@ref{18e9,,PyDict_Next()}

@tab

none (see @ref{55f4,,PyDict_Next})

@item

@ref{3db,,PyWeakref_GetObject()}

@tab

@ref{3dd,,PyWeakref_GetRef()}

@item

@ref{3dc,,PyWeakref_GET_OBJECT()}

@tab

@ref{3dd,,PyWeakref_GetRef()}

@item

@ref{5f4,,PyImport_AddModule()}

@tab

@ref{5f3,,PyImport_AddModuleRef()}

@item

@ref{51d1,,PyCell_GET()}

@tab

@ref{51d0,,PyCell_Get()}

@end multitable


Not all APIs that return borrowed references are problematic.  For
example, @ref{4d7f,,PyTuple_GetItem()} is safe because tuples are immutable.
Similarly, not all uses of the above APIs are problematic.  For example,
@ref{620,,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,借用參照,支援自由執行緒的 C API 擴充
@anchor{howto/free-threading-extensions free-threaded-memory-allocation}@anchor{533b}@anchor{howto/free-threading-extensions memory-allocation-apis}@anchor{55f6}
@subsection Memory Allocation APIs


Python's memory management C API provides functions in three different
@ref{5336,,allocation domains}: "raw", "mem", and "object".
For thread-safety, the free-threaded build requires that only Python objects
are allocated using the object domain, and that all Python object are
allocated using that domain.  This differs from the prior Python versions,
where this was only a best practice and not a hard requirement.

@cartouche
@quotation 備註 
Search for uses of @ref{e5d,,PyObject_Malloc()} in your
extension and check that the allocated memory is used for Python objects.
Use @ref{e5b,,PyMem_Malloc()} to allocate buffers instead of
@ref{e5d,,PyObject_Malloc()}.
@end quotation
@end cartouche

@node Thread State and GIL APIs,Protecting Internal Extension State,Memory Allocation APIs,支援自由執行緒的 C API 擴充
@anchor{howto/free-threading-extensions thread-state-and-gil-apis}@anchor{55f7}
@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{642,,PyGILState_Ensure()} 和 @ref{643,,PyGILState_Release()}

@item 
@ref{63f,,PyEval_SaveThread()} 和 @ref{640,,PyEval_RestoreThread()}

@item 
@ref{4d85,,Py_BEGIN_ALLOW_THREADS} 和 @ref{c76,,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{164,,GIL} is disabled.  For example, if you
create a thread outside of Python, you must call @ref{642,,PyGILState_Ensure()}
before calling into the Python API to ensure that the thread has a valid
Python thread state.

You should continue to call @ref{63f,,PyEval_SaveThread()} or
@ref{4d85,,Py_BEGIN_ALLOW_THREADS} around blocking operations, such as I/O or
lock acquisitions, to allow other threads to run the
@ref{1765,,cyclic garbage collector}.

@node Protecting Internal Extension State,Critical Sections,Thread State and GIL APIs,支援自由執行緒的 C API 擴充
@anchor{howto/free-threading-extensions protecting-internal-extension-state}@anchor{55f8}
@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 擴充
@anchor{howto/free-threading-extensions critical-sections}@anchor{55f9}
@subsection Critical Sections

@anchor{howto/free-threading-extensions id3}@anchor{55fa}
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:: 

@end menu

@node What Are Critical Sections?,Using Critical Sections,,Critical Sections
@anchor{howto/free-threading-extensions what-are-critical-sections}@anchor{55fb}
@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{4d81,,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{55fc}
@subsubsection Using Critical Sections


The primary APIs for using critical sections are:


@itemize *

@item 
@ref{518a,,Py_BEGIN_CRITICAL_SECTION} and @ref{52e7,,Py_END_CRITICAL_SECTION} -
For locking a single object

@item 
@ref{52e5,,Py_BEGIN_CRITICAL_SECTION2} and @ref{52e9,,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{55fd}
@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{55fe}
@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{52e5,,Py_BEGIN_CRITICAL_SECTION2} to lock two objects simultaneously.

Note that the locks described above are only @code{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,,Deadlock Avoidance,Critical Sections
@anchor{howto/free-threading-extensions important-considerations}@anchor{55ff}
@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{52e5,,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 Building Extensions for the Free-Threaded Build,,Critical Sections,支援自由執行緒的 C API 擴充
@anchor{howto/free-threading-extensions building-extensions-for-the-free-threaded-build}@anchor{5600}
@subsection Building Extensions for the Free-Threaded Build


C API extensions need to be built specifically for the free-threaded build.
The wheels, shared libraries, and binaries are indicated by a @code{t} suffix.


@itemize *

@item 
pypa/manylinux@footnote{https://github.com/pypa/manylinux} supports the
free-threaded build, with the @code{t} suffix, such as @code{python3.13t}.

@item 
pypa/cibuildwheel@footnote{https://github.com/pypa/cibuildwheel} supports the
free-threaded build if you set
CIBW_ENABLE to cpython-freethreading@footnote{https://cibuildwheel.pypa.io/en/stable/options/#enable}.
@end itemize

@menu
* Limited C API and Stable ABI:: 
* Windows: Windows<83>. 

@end menu

@node Limited C API and Stable ABI,Windows<83>,,Building Extensions for the Free-Threaded Build
@anchor{howto/free-threading-extensions limited-c-api-and-stable-abi}@anchor{5601}
@subsubsection Limited C API and Stable ABI


The free-threaded build does not currently support the
@ref{62f,,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<83>,,Limited C API and Stable ABI,Building Extensions for the Free-Threaded Build
@anchor{howto/free-threading-extensions windows}@anchor{5602}
@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 擴充,Python 如何達成任務
@anchor{howto/remote_debugging doc}@anchor{5603}@anchor{howto/remote_debugging remote-debugging}@anchor{5604}@anchor{howto/remote_debugging remote-debugging-attachment-protocol}@anchor{5605}@anchor{howto/remote_debugging translation-repo}@anchor{5606}
@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.

@node Permission requirements,Locating the PyRuntime structure,Remote debugging attachment protocol,Python 如何達成任務
@anchor{howto/remote_debugging id1}@anchor{5607}@anchor{howto/remote_debugging permission-requirements}@anchor{5608}
@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 
選擇你的使用者帳戶。

@item 
In `Permissions', check `Read' or `Full control' as needed.

@item 
點擊 `Apply'，然後點擊 `OK' 來確認。
@end enumerate
@end quotation

@cartouche
@quotation 備註 
Ensure you've satisfied all @ref{5608,,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{16d,,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,讀取 _Py_DebugOffsets,Permission requirements,Python 如何達成任務
@anchor{howto/remote_debugging locating-the-pyruntime-structure}@anchor{5609}
@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

以下是一個範例實作：

@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)


在 macOS 上找 @code{PyRuntime} 結構：


@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

以下是一個範例實作：

@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)


在 Windows 上找 @code{PyRuntime} 結構：


@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

以下是一個範例實作：

@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 讀取 _Py_DebugOffsets,Locating the interpreter and thread state,Locating the PyRuntime structure,Python 如何達成任務
@anchor{howto/remote_debugging reading-py-debugoffsets}@anchor{560a}
@section 讀取 _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,讀取 _Py_DebugOffsets,Python 如何達成任務
@anchor{howto/remote_debugging locating-the-interpreter-and-thread-state}@anchor{560b}
@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 如何達成任務
@anchor{howto/remote_debugging writing-control-information}@anchor{560c}
@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

以下是一個範例實作：

@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,,Writing control information,Python 如何達成任務
@anchor{howto/remote_debugging summary}@anchor{560d}
@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

@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{366c,,asyncio 的概念性總覽}

@item 
@ref{9d2,,註釋 (annotation) 最佳實踐}

@item 
@ref{3221,,Argparse 教學}

@item 
@ref{16e1,,描述器 (Descriptor) 指南}

@item 
@ref{546e,,Enum HOWTO}

@item 
@ref{54a0,,函式程式設計 HOWTO}

@item 
@ref{4081,,ipaddress 模組介紹}

@item 
@ref{54bf,,如何使用 Logging 模組}

@item 
@ref{13f8,,Logging Cookbook}

@item 
@ref{260d,,如何使用正規表示式}

@item 
@ref{248a,,排序技法}

@item 
@ref{14a5,,Unicode HOWTO}

@item 
@ref{3e43,,如何使用 urllib 套件取得網路資源}
@end itemize

進階開發：


@itemize *

@item 
@ref{3314,,Curses Programming with Python}

@item 
@ref{55d9,,Python 自由執行緒的支援}

@item 
@ref{55dc,,支援自由執行緒的 C API 擴充}

@item 
@ref{166,,隔離擴充模組}

@item 
@ref{169e,,The Python 2.3 Method Resolution Order}

@item 
@ref{3857,,Socket 程式設計指南}

@item 
@ref{55cc,,計時器檔案描述器 (timerfd) 指南}

@item 
@ref{14e1,,遷移延伸模組到 Python 3}
@end itemize

偵錯與效能分析：


@itemize *

@item 
@ref{545f,,使用 GDB 來為 C API 擴充功能和 CPython 內部偵錯}

@item 
@ref{e61,,使用 DTrace 和 SystemTap 檢測 CPython}

@item 
@ref{4a9,,Python 對 Linux perf 分析器的支援}

@item 
@ref{5604,,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 常見問題,已棄用項目,Python 如何達成任務,Top
@anchor{faq/index doc}@anchor{560e}@anchor{faq/index faq-index}@anchor{1fbb}@anchor{faq/index python-frequently-asked-questions}@anchor{560f}@anchor{faq/index translation-repo}@anchor{5610}
@chapter Python 常見問題


@menu
* 一般的 Python 常見問答集:: 
* 程式開發常見問答集:: 
* 設計和歷史常見問答集:: 
* 函式庫和擴充功能的常見問題:: 
* 擴充/嵌入常見問題集:: 
* 在 Windows 使用 Python 的常見問答集:: 
* 圖形使用者介面常見問答集:: 
* 「為什麼 Python 被安裝在我的機器上？」常見問答集:: 

@end menu

@node 一般的 Python 常見問答集,程式開發常見問答集,,Python 常見問題
@anchor{faq/general doc}@anchor{5611}@anchor{faq/general general-python-faq}@anchor{5612}
@section 一般的 Python 常見問答集



@menu
* 一般資訊:: 
* 在真實世界中的 Python:: 

@end menu

@node 一般資訊,在真實世界中的 Python,,一般的 Python 常見問答集
@anchor{faq/general general-information}@anchor{5613}
@subsection 一般資訊


@menu
* 什麼是 Python？:: 
* 什麼是 Python 軟體基金會？:: 
* 使用 Python 時有任何版權限制嗎？:: 
* 當初為什麼 Python 會被創造出來？:: 
* 什麼是 Python 擅長的事情？:: 
* Python 的版本編號系統是如何運作的？:: 
* 我要如何得到 Python 的原始碼複本？:: 
* 我要如何取得 Python 的說明文件？:: 
* 我從來沒有寫過程式，有沒有 Python 的教學？:: 
* 有沒有 Python 專屬的新聞群組或郵件討論群？:: 
* 如何取得 Python 的 beta 測試版本？:: 
* 如何提交 Python 的錯誤報告和修補程式？:: 
* 是否有關於 Python 的任何已出版文章可供參考？:: 
* 有沒有關於 Python 的書？:: 
* www.python.org 的真實位置在哪裡？: www python org 的真實位置在哪裡？. 
* 為什麼要取名為 Python？:: 
* 我需要喜歡「Monty Python 的飛行馬戲團」嗎？:: 

@end menu

@node 什麼是 Python？,什麼是 Python 軟體基金會？,,一般資訊
@anchor{faq/general what-is-python}@anchor{5614}
@subsubsection 什麼是 Python？


Python 是一種直譯的、互動的、物件導向的程式設計語言。它結合了模組、例外、動態型別 (dynamic typing)、非常高階的動態資料型別，以及 class（類別）。它能支援物件導向程式設計之外的多種程式設計典範，例如程序式 (procedural) 和函式語言 (functional) 程式設計。Python 結合了卓越的功能與非常清晰的語法。它有許多系統呼叫和函式庫的介面，以及各種視窗系統的介面，並且在 C 或 C++ 中可以擴充。它還可以作為一種擴充語言，使用於需要可程式化介面 (programmable interface) 的應用程式。最後，Python 是可攜的 (portable)：它能運行在許多 Unix 的變體上，包括 Linux 和 macOS，也能運行在 Windows 上。

要尋找更多內容，請從 @ref{1e83,,Python 教學}開始。Python 初學者指南@footnote{https://wiki.python.org/moin/BeginnersGuide}可連結到其他介紹式教學以及學習 Python 的資源。

@node 什麼是 Python 軟體基金會？,使用 Python 時有任何版權限制嗎？,什麼是 Python？,一般資訊
@anchor{faq/general what-is-the-python-software-foundation}@anchor{5615}
@subsubsection 什麼是 Python 軟體基金會？


Python 軟體基金會 (Python Software Foundation) 是一個獨立的非營利性組織，它擁有 Python 2.1 版與之後各版本的版權。PSF 的使命在於推展 Python 程式設計語言相關的開放原始碼技術，以及宣傳 Python 的使用。PSF 首頁的網址是 @indicateurl{https://www.python.org/psf/}。

在美國捐款給 PSF 是免稅的。如果你使用了 Python 且發現它很有用，請至 PSF 捐款頁面@footnote{https://www.python.org/psf/donations/}為它做出貢獻。

@node 使用 Python 時有任何版權限制嗎？,當初為什麼 Python 會被創造出來？,什麼是 Python 軟體基金會？,一般資訊
@anchor{faq/general are-there-copyright-restrictions-on-the-use-of-python}@anchor{5616}
@subsubsection 使用 Python 時有任何版權限制嗎？


你可以對原始碼做任何你想做的事情，只要你保留版權，並且在你製作的任何關於 Python 的說明文件中顯示這些版權即可。如果你遵守版權規則，就可以將 Python 用於商業用途，以原始碼或二進制形式（修改或未修改）銷售 Python 的複本，或者以某種形式銷售內含 Python 的產品。當然，我們仍然會想要知道所有的 Python 商業用途。

請參閱 授權頁面@footnote{https://docs.python.org/3/license.html}，查詢更深入的說明和 PSF 授權全文的連結。

Python 標誌是註冊商標，在某些情況下需要許可才能使用它。請參閱商標使用政策@footnote{https://www.python.org/psf/trademarks/}以取得更多資訊。

@node 當初為什麼 Python 會被創造出來？,什麼是 Python 擅長的事情？,使用 Python 時有任何版權限制嗎？,一般資訊
@anchor{faq/general why-was-python-created-in-the-first-place}@anchor{5617}
@subsubsection 當初為什麼 Python 會被創造出來？


以下是由 Guido van Rossum 所撰寫，關於這一切如何開始的`非常'簡短的摘要：

@quotation

我在 CWI 的 ABC 小組中擁有實作直譯語言方面的豐富經驗，而透過與該小組的合作，我學到了很多關於語言設計的知識。這是許多 Python 功能的起源，包括使用縮排進行陳述式分組以及納入非常高階的資料型別（儘管在 Python 中的細節都已經不同）。

我對 ABC 語言有一些牢騷，但我也喜歡它的許多功能。想要擴充 ABC 語言（或其實作）來去除我的抱怨是不可能的。事實上，缺乏可擴充性就是它最大的問題之一。我有一些使用 Modula-2+ 的經驗，也與 Modula-3 的設計者交談過，並閱讀了 Modula-3 的報告。Modula-3 就是用於例外及另外一些 Python 功能的語法和語義的起源。

我當時正在 CWI 的 Amoeba 分散式作業系統小組工作。我們需要一種比編寫 C 程式或 Bourne shell 腳本更好的方法來進行系統管理，因為 Amoeba 有自己的系統呼叫介面，而它無法簡單地從 Bourne shell 進行存取。我在 Amoeba 中處理錯誤的經驗，使我深切地意識到例外作為程式設計語言功能的重要性。

我突然想到，一種具有類似 ABC 的語法但可以存取 Amoeba 系統呼叫的腳本語言將能滿足該需求。我了解編寫 Amoeba 專用語言是愚蠢的，所以我決定，我需要一種可以廣泛擴充的語言。

在 1989 年的聖誕節假期，我有很多自由時間，所以我決定來嘗試一下。在接下來的一年裡，雖然我大部分時間仍然在為此而努力，但 Python 在 Amoeba 專案中的使用得到了越來越多的成功，且同事們的回饋也使我為它增加了許多早期的改進。

在 1991 年 2月，經過一年多的發展，我決定將它發表到 USENET。其他的記錄都在 @code{Misc/HISTORY} 檔案中。
@end quotation

@node 什麼是 Python 擅長的事情？,Python 的版本編號系統是如何運作的？,當初為什麼 Python 會被創造出來？,一般資訊
@anchor{faq/general what-is-python-good-for}@anchor{5618}
@subsubsection 什麼是 Python 擅長的事情？


Python 是一種高階的、用途廣泛的程式設計語言，可以用來解決許多不同類型的問題。

這個語言提供了一個大型的標準函式庫，涵蓋了字串處理（正規表示式、Unicode、檔案之間的差異計算）、網際網路協定（HTTP、FTP、SMTP、XML-RPC、POP、IMAP）、軟體工程（單元測試、日誌記錄、效能分析、剖析 Python 程式碼）以及作業系統介面（系統呼叫、檔案系統、TCP/IP 插座 (socket)）等領域。請查看 @ref{149,,Python 標準函式庫 (Standard Library)} 的目錄，以了解可用的函式。此外，還有各式各樣的第三方擴充。請查詢 Python 套件索引 (Python Package Index)@footnote{https://pypi.org} 來尋找你有興趣的套件。

@node Python 的版本編號系統是如何運作的？,我要如何得到 Python 的原始碼複本？,什麼是 Python 擅長的事情？,一般資訊
@anchor{faq/general faq-version-numbering-scheme}@anchor{5619}@anchor{faq/general how-does-the-python-version-numbering-scheme-work}@anchor{561a}
@subsubsection Python 的版本編號系統是如何運作的？


Python 各版本會被編號為 "A.B.C" 或 "A.B"：


@itemize *

@item 
`A' 為主要版本編號 -- 它只會在語言中有真正重大的變更時才會增加。

@item 
`B' 為次要版本編號 -- 只有在影響範圍較小的變更出現時增加。

@item 
`C' 為微小版本編號 —- 會在每個錯誤修正發布 (bugfix release) 增加。
@end itemize

並非所有的發布版本都是錯誤修正發布版本。在一個新功能發布版本的準備階段，會發布一系列開發版本，標示為 alpha、beta 或候選發布版本 (release candidate)。Alpha 是介面尚未最終化的早期發布版本；看到兩個 alpha 發布版本之間的介面變更並不會令人意外。Beta 則更為穩定，保留了現有的介面，但可能會增加新的模組，而候選發布版本會被凍結，除了需要修正關鍵錯誤之外，不會再進行任何變更。

Alpha、beta 和候選發布版本都有一個額外的後綴：


@itemize *

@item 
Alpha 版本的後綴是 "aN"，其中 `N' 是某個較小的數字。

@item 
Beta 版本的後綴是 "bN"，其中 `N' 是某個較小的數字。

@item 
候選發布版本的後綴是 "rcN"，其中 `N' 是某個較小的數字。
@end itemize

換句話說，所有標記為 `2.0aN' 的版本都在標記為 `2.0bN' 的版本之前，而 `2.0bN' 版本都在標記為 `2.0rcN' 的版本之前，而`它們'都是在 2.0 版之前。

你還可以找到帶有「+」後綴的版本編號，例如「2.2+」。這些是未發布的版本，直接從 CPython 的開發儲存庫被建置。實際上，在每一次的最終次要版本發布完成之後，版本編號將會被增加到下一個次要版本，並成為「a0」版，例如「2.4a0」。

請參閱開發人員指南@footnote{https://devguide.python.org/developer-workflow/development-cycle/}以獲得更多關於開發週期的資訊，並參閱 
@geindex Python Enhancement Proposals; PEP 387
PEP 387@footnote{https://peps.python.org/pep-0387/} 以瞭解更多關於 Python 的向後相容性政策。另外，也請查看 @ref{497,,sys.version}、@ref{47d9,,sys.hexversion} 和 @ref{8a7,,sys.version_info} 的說明文件。

@node 我要如何得到 Python 的原始碼複本？,我要如何取得 Python 的說明文件？,Python 的版本編號系統是如何運作的？,一般資訊
@anchor{faq/general how-do-i-obtain-a-copy-of-the-python-source}@anchor{561b}
@subsubsection 我要如何得到 Python 的原始碼複本？


最新的 Python 原始碼發行版永遠可以從 python.org 取得，在 @indicateurl{https://www.python.org/downloads/}。最新的開發中原始碼可以在 @indicateurl{https://github.com/python/cpython/} 取得。

原始碼發行版是一個以 gzip 壓縮的 tar 檔，它包含完整的 C 原始碼、Sphinx 格式的說明文件、Python 函式庫模組、範例程式，以及幾個好用的可自由發行軟體。該原始碼在大多數 UNIX 平台上，都是可以立即編譯及運行的。

關於取得和編譯原始碼的詳細資訊，請參閱 Python 開發人員指南中的 "Getting Started" 段落@footnote{https://devguide.python.org/setup/}。

@node 我要如何取得 Python 的說明文件？,我從來沒有寫過程式，有沒有 Python 的教學？,我要如何得到 Python 的原始碼複本？,一般資訊
@anchor{faq/general how-do-i-get-documentation-on-python}@anchor{561c}
@subsubsection 我要如何取得 Python 的說明文件？


Python 目前穩定版本的標準說明文件可在 @indicateurl{https://docs.python.org/3/} 找到。EPUB、純文字和可下載的 HTML 版本也可在 @indicateurl{https://docs.python.org/3/download.html} 找到。

說明文件是以 reStructuredText 格式編寫，並由 Sphinx 說明文件工具@footnote{https://sphinx-doc.org/}處理。說明文件的 reStructuredText 原始碼是 Python 原始碼發行版的一部分。

@node 我從來沒有寫過程式，有沒有 Python 的教學？,有沒有 Python 專屬的新聞群組或郵件討論群？,我要如何取得 Python 的說明文件？,一般資訊
@anchor{faq/general i-ve-never-programmed-before-is-there-a-python-tutorial}@anchor{561d}
@subsubsection 我從來沒有寫過程式，有沒有 Python 的教學？


有許多可用的教學和書籍。標準說明文件包括 @ref{1e83,,Python 教學}。

要尋找 Python 程式設計初學者的資訊，包括教學資源列表，請參閱初學者指南@footnote{https://wiki.python.org/moin/BeginnersGuide}。

@node 有沒有 Python 專屬的新聞群組或郵件討論群？,如何取得 Python 的 beta 測試版本？,我從來沒有寫過程式，有沒有 Python 的教學？,一般資訊
@anchor{faq/general is-there-a-newsgroup-or-mailing-list-devoted-to-python}@anchor{561e}
@subsubsection 有沒有 Python 專屬的新聞群組或郵件討論群？


有一個新聞群組 (newsgroup)，@code{comp.lang.python}，也有一個郵件討論群 (mailing list)，python-list@footnote{https://mail.python.org/mailman/listinfo/python-list}。新聞群組和郵件討論群是彼此相通的——如果你能閱讀新聞，則無需加入郵件討論群。@code{comp.lang.python} 的流量很高，每天會收到數百篇文章，而 Usenet 的讀者通常較能夠處理這樣的文章數量。

新的軟體發布版本及事件的通知，可以在 comp.lang.python.announce 中找到，這是一個低流量的精選討論群，每天收到大約五篇文章。它也能從 python-announce 郵件討論群@footnote{https://mail.python.org/mailman3/lists/python-announce-list.python.org/}的頁面中訂閱。

關於其他郵件討論群和新聞群組的更多資訊，可以在 @indicateurl{https://www.python.org/community/lists/} 中找到。

@node 如何取得 Python 的 beta 測試版本？,如何提交 Python 的錯誤報告和修補程式？,有沒有 Python 專屬的新聞群組或郵件討論群？,一般資訊
@anchor{faq/general how-do-i-get-a-beta-test-version-of-python}@anchor{561f}
@subsubsection 如何取得 Python 的 beta 測試版本？


Alpha 和 beta 發布版本可以從 @indicateurl{https://www.python.org/downloads/} 取得。所有的發布版本都會在 comp.lang.python 和 comp.lang.python.announce 新聞群組上宣布，也會在 Python 首頁 @indicateurl{https://www.python.org/} 中宣布；RSS 新聞摘要也是可使用的。

你也可以藉由 Git 來存取 Python 的開發版本。更多詳細資訊，請參閱 Python 開發人員指南@footnote{https://devguide.python.org/}。

@node 如何提交 Python 的錯誤報告和修補程式？,是否有關於 Python 的任何已出版文章可供參考？,如何取得 Python 的 beta 測試版本？,一般資訊
@anchor{faq/general how-do-i-submit-bug-reports-and-patches-for-python}@anchor{5620}
@subsubsection 如何提交 Python 的錯誤報告和修補程式？


要回報一個錯誤 (bug) 或提交一個修補程式 (patch)，請使用於 @indicateurl{https://github.com/python/cpython/issues} 的問題追蹤系統。

關於如何開發 Python 的更多資訊，請參閱 Python 開發人員指南@footnote{https://devguide.python.org/}。

@node 是否有關於 Python 的任何已出版文章可供參考？,有沒有關於 Python 的書？,如何提交 Python 的錯誤報告和修補程式？,一般資訊
@anchor{faq/general are-there-any-published-articles-about-python-that-i-can-reference}@anchor{5621}
@subsubsection 是否有關於 Python 的任何已出版文章可供參考？


也許最好是引用你最喜歡的關於 Python 的書。

最早討論 Python 的文章@footnote{https://ir.cwi.nl/pub/18204}是在 1991 年寫的，但現在來看已經過時了。

@quotation

Guido van Rossum 和 Jelke de Boer，「使用 Python 程式設計語言互動式測試遠端伺服器」，CWI 季刊，第 4 卷，第 4 期（1991 年 12 月），阿姆斯特丹，第 283–303 頁。
@end quotation

@node 有沒有關於 Python 的書？,www python org 的真實位置在哪裡？,是否有關於 Python 的任何已出版文章可供參考？,一般資訊
@anchor{faq/general are-there-any-books-on-python}@anchor{5622}
@subsubsection 有沒有關於 Python 的書？


有，很多書已經出版，也有更多正在出版中的書。請參閱 python.org 的 wiki 在 @indicateurl{https://wiki.python.org/moin/PythonBooks} 頁面中的書目清單。

你也可以在網路書店搜尋關鍵字「Python」，並過濾掉 Monty Python 的結果；或者可以搜尋「Python」和「語言」。

@node www python org 的真實位置在哪裡？,為什麼要取名為 Python？,有沒有關於 Python 的書？,一般資訊
@anchor{faq/general where-in-the-world-is-www-python-org-located}@anchor{5623}
@subsubsection www.python.org 的真實位置在哪裡？


Python 專案的基礎建設遍佈世界各地，由 Python 基礎建設團隊管理。詳細資訊在此@footnote{https://infra.psf.io}。

@node 為什麼要取名為 Python？,我需要喜歡「Monty Python 的飛行馬戲團」嗎？,www python org 的真實位置在哪裡？,一般資訊
@anchor{faq/general why-is-it-called-python}@anchor{5624}
@subsubsection 為什麼要取名為 Python？


當 Guido van Rossum 開始實作 Python 時，他也正在閱讀 1970 年代 BBC 喜劇節目「Monty Python 的飛行馬戲團」@footnote{https://en.wikipedia.org/wiki/Monty_Python}的出版劇本。Van Rossum 認為他需要一個簡短、獨特且略帶神秘的名字，因此他決定將該語言稱為 Python。

@node 我需要喜歡「Monty Python 的飛行馬戲團」嗎？,,為什麼要取名為 Python？,一般資訊
@anchor{faq/general do-i-have-to-like-monty-python-s-flying-circus}@anchor{5625}
@subsubsection 我需要喜歡「Monty Python 的飛行馬戲團」嗎？


不需要，但它有幫助。:)

@node 在真實世界中的 Python,,一般資訊,一般的 Python 常見問答集
@anchor{faq/general python-in-the-real-world}@anchor{5626}
@subsection 在真實世界中的 Python


@menu
* Python 的穩定性如何？:: 
* 有多少人在使用 Python？:: 
* 有沒有任何重要的專案使用 Python 完成開發？:: 
* Python 未來預期會有哪些新的開發？:: 
* 對 Python 提出不相容的變更建議是否適當？:: 
* Python 對於入門的程式設計師而言是否為好的語言？:: 

@end menu

@node Python 的穩定性如何？,有多少人在使用 Python？,,在真實世界中的 Python
@anchor{faq/general how-stable-is-python}@anchor{5627}
@subsubsection Python 的穩定性如何？


非常穩定。自從 1991 年開始，大約每隔 6 到 18 個月都會發布新的穩定版本，而且這看起來會繼續進行。從 3.9 版開始，Python 每隔 12 個月將會釋出一個新功能發行版本 (
@geindex Python Enhancement Proposals; PEP 602
PEP 602@footnote{https://peps.python.org/pep-0602/})。

開發人員會釋出針對先前版本的錯誤修正發布版本，因此現有發布版本的穩定性會逐漸提高。錯誤修正發布版本是由版本編號的第三個部分表示（例如 3.5.3，3.6.2），這些版本會被用於改善穩定性；在錯誤修正發布版本中，只會包含針對已知問題的修正，並且會保證介面在一系列的錯誤修正發布版本中維持不變。

最新的穩定發布版本隨時都可以在 Python 下載頁面@footnote{https://www.python.org/downloads/}上找到。Python 3.x 是推薦的版本，並且被大多數廣泛使用的函式庫所支援。Python 2.x 
@geindex Python Enhancement Proposals; PEP 0373
已不再被維護@footnote{https://peps.python.org/pep-0373/}。

@node 有多少人在使用 Python？,有沒有任何重要的專案使用 Python 完成開發？,Python 的穩定性如何？,在真實世界中的 Python
@anchor{faq/general how-many-people-are-using-python}@anchor{5628}
@subsubsection 有多少人在使用 Python？


可能有幾百萬個使用者，但實際的數量是難以確定的。

Python 是可以免費下載的，所以不會有銷售數據，而且它可以從許多不同的網站取得，並與許多 Linux 發行版套裝在一起，所以下載次數的統計也無法反映完整的情況。

comp.lang.python 新聞群組非常活躍，但並非所有 Python 使用者都會在該群組發表文章或甚至閱讀它。

@node 有沒有任何重要的專案使用 Python 完成開發？,Python 未來預期會有哪些新的開發？,有多少人在使用 Python？,在真實世界中的 Python
@anchor{faq/general have-any-significant-projects-been-done-in-python}@anchor{5629}
@subsubsection 有沒有任何重要的專案使用 Python 完成開發？


要查看使用 Python 的專案清單，請參閱 @indicateurl{https://www.python.org/about/success}。藉由查詢過去的 Python 會議記錄@footnote{https://www.python.org/community/workshops/}可以看見來自許多不同公司和組織的貢獻。

備受矚目的 Python 專案包括 Mailman 郵件討論群管理員@footnote{https://www.list.org}和 Zope 應用程式伺服器@footnote{https://www.zope.dev}。有一些 Linux 發行版，最著名的是 Red Hat@footnote{https://www.redhat.com}，已經用 Python 編寫了部分或全部的安裝程式及系統管理軟體。內部使用 Python 的公司包括 Google、Yahoo 和 Lucasfilm Ltd。

@node Python 未來預期會有哪些新的開發？,對 Python 提出不相容的變更建議是否適當？,有沒有任何重要的專案使用 Python 完成開發？,在真實世界中的 Python
@anchor{faq/general what-new-developments-are-expected-for-python-in-the-future}@anchor{562a}
@subsubsection Python 未來預期會有哪些新的開發？


請至 @indicateurl{https://peps.python.org/} 參閱 Python 增強提案 (Python Enhancement Proposal, PEP)。PEP 是用來描述一項被建議的 Python 新功能的設計文件，它提供了簡潔的技術規範及基本原理。請尋找一篇名為「Python X.Y Release Schedule（發布時程表）」的 PEP，其中 X.Y 是一個尚未公開發布的版本。

新的開發會在 python-dev 郵件討論群@footnote{https://mail.python.org/mailman3/lists/python-dev.python.org/}中討論。

@node 對 Python 提出不相容的變更建議是否適當？,Python 對於入門的程式設計師而言是否為好的語言？,Python 未來預期會有哪些新的開發？,在真實世界中的 Python
@anchor{faq/general is-it-reasonable-to-propose-incompatible-changes-to-python}@anchor{562b}
@subsubsection 對 Python 提出不相容的變更建議是否適當？


一般來說，不適當。全世界已經有數百萬行 Python 程式碼，因此在語言中的任何變更，若會使現有程式的一小部分成為無效，它都是不被允許的。即使你可以提供轉換程式，仍然會有需要更新全部說明文件的問題；市面上已經有很多介紹 Python 的書，而我們不想一下子就把它們都變為無效。

如果一項功能必須被變更，那麼一定要提供逐步升級的路徑。
@geindex Python Enhancement Proposals; PEP 5
PEP 5@footnote{https://peps.python.org/pep-0005/} 描述了要引進反向不相容 (backward-incompatible) 的變更，同時也要對使用者的擾亂最小化，所需遵循的程序。

@node Python 對於入門的程式設計師而言是否為好的語言？,,對 Python 提出不相容的變更建議是否適當？,在真實世界中的 Python
@anchor{faq/general is-python-a-good-language-for-beginning-programmers}@anchor{562c}
@subsubsection Python 對於入門的程式設計師而言是否為好的語言？


是的。

學生們仍然普遍地會從一種程序語言和靜態型別語言 (statically typed language) 開始入門，這些語言像是 Pascal、C，或是 C++ 或 Java 的某個子集。透過學習 Python 作為他們的第一個語言，學生們可能會學得更好。Python 具有非常簡單且一致的語法和一個大型的標準函式庫，最重要的是，在入門程式設計課程中使用 Python 可以讓學生專注於重要的程式設計技巧，例如問題的分解和資料型別的設計。使用 Python，可以快速地向學生介紹基本觀念，例如迴圈和程序。他們甚至可能在第一堂課中就學到使用者自訂的物件。

對於以前從未進行過程式設計的學生來說，使用靜態型別語言似乎是不自然的。它使學生必須掌握額外的複雜性，並減慢了課程的節奏。學生們正在試圖學著像電腦一樣思考、分解問題、設計一致的介面，並封裝資料。雖然從長遠來看，學習使用靜態型別語言很重要，但在學生的第一堂程式設計課程中，它不一定是最好的課程主題。

Python 的許多其他面向使它成為一種很好的第一語言。像 Java 一樣，Python 有一個大型的標準函式庫，因此學生可以在課程的早期就被指派程式設計的專案，且這些專案能夠`做'一些事情。指派的內容不會侷限於標準的四功能計算機和平衡檢驗程式。透過使用標準函式庫，學生可以在學習程式設計基礎知識的同時，獲得處理真實應用程式的滿足感。使用標準函式庫還可以教導學生程式碼再使用 (code reuse) 的課題。像是 PyGame 等第三方模組也有助於延伸學生的學習領域。

Python 的互動式直譯器使學生能夠在程式設計時測試語言的功能。他們可以開著一個運行直譯器的視窗，同時在另一個視窗中輸入他們的程式原始碼。如果他們不記得 list（串列）的 method（方法），他們可以像這樣做：

@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

有了直譯器，當學生正在程式設計時，說明文件永遠都不會遠離他們。

Python 也有很好的 IDE。IDLE 是 Python 的一個跨平臺 IDE，它以 Python 編寫並使用 Tkinter。Emacs 使用者會很高興知道 Emacs 有一個非常好的 Python 模式。這些程式設計環境全部都能提供語法突顯 (syntax highlighting)、自動縮排，以及在編寫程式時存取互動式直譯器。要查看 Python 編輯環境的完整清單，請參閱 Python wiki@footnote{https://wiki.python.org/moin/PythonEditors}。

如果你想討論 Python 在教育領域中的使用，你可能會有興趣加入 edu-sig 郵件討論群@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 程式開發常見問答集,設計和歷史常見問答集,一般的 Python 常見問答集,Python 常見問題
@anchor{faq/programming doc}@anchor{562d}@anchor{faq/programming programming-faq}@anchor{562e}@anchor{faq/programming translation-repo}@anchor{562f}
@section 程式開發常見問答集



@menu
* 常見問題:: 
* 核心語言:: 
* 數字和字串:: 
* 效能: 效能<3>. 
* 序列（元組/串列）:: 
* 物件:: 
* 模組: 模組<6>. 

@end menu

@node 常見問題,核心語言,,程式開發常見問答集
@anchor{faq/programming general-questions}@anchor{5630}
@subsection 常見問題


@menu
* 是否有可以使用在程式碼階段@comma{}具有中斷點@comma{}步驟執行等功能的除錯器？: 是否有可以使用在程式碼階段 具有中斷點 步驟執行等功能的除錯器？. 
* 有沒有工具能夠幫忙找 bug 或執行靜態分析？:: 
* 如何從 Python 腳本建立獨立的二進位檔案？:: 
* Python 程式碼是否有編碼標準或風格指南？:: 

@end menu

@node 是否有可以使用在程式碼階段 具有中斷點 步驟執行等功能的除錯器？,有沒有工具能夠幫忙找 bug 或執行靜態分析？,,常見問題
@anchor{faq/programming is-there-a-source-code-level-debugger-with-breakpoints-single-stepping-etc}@anchor{5631}
@subsubsection 是否有可以使用在程式碼階段,具有中斷點,步驟執行等功能的除錯器？


有的。

下面描述了幾個 Python 除錯器，內建函式 @ref{271,,breakpoint()} 允許你進入其中任何一個。

pdb 模組是一個簡單但足夠的 Python 控制台模式除錯器。它是標準 Python 函式庫的一部分，並@ref{aa,,記錄在函式庫參考手冊}中。你也可以參考 pdb 的程式碼作為範例來編寫自己的除錯器。

IDLE 交互式開發環境，它是標準 Python 發行版的一部分（通常作為 Tools/scripts/idle3@footnote{https://github.com/python/cpython/blob/main/Tools/scripts/idle3} 提供），包括一個圖形除錯器。

PythonWin 是一個 Python IDE，它包含一個基於 pdb 的 GUI 除錯器。 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/} 是一個基於 PyQt 和 Scintilla 編輯元件所建構的 IDE。

trepan3k@footnote{https://github.com/rocky/python3-trepan/} 是一個類似 gdb 的除錯器。

Visual Studio Code@footnote{https://code.visualstudio.com/} 是一個整合了版本控制軟體與除錯工具的 IDE。

有數個商業化Python整合化開發工具包含圖形除錯功能。這些包含：


@itemize *

@item 
Wing IDE@footnote{https://wingware.com/}

@item 
Komodo IDE@footnote{https://www.activestate.com/products/komodo-ide/}

@item 
PyCharm@footnote{https://www.jetbrains.com/pycharm/}
@end itemize

@node 有沒有工具能夠幫忙找 bug 或執行靜態分析？,如何從 Python 腳本建立獨立的二進位檔案？,是否有可以使用在程式碼階段 具有中斷點 步驟執行等功能的除錯器？,常見問題
@anchor{faq/programming are-there-tools-to-help-find-bugs-or-perform-static-analysis}@anchor{5632}
@subsubsection 有沒有工具能夠幫忙找 bug 或執行靜態分析？


有的。

Pylint@footnote{https://pylint.pycqa.org/en/latest/index.html} 和 Pyflakes@footnote{https://github.com/PyCQA/pyflakes} 進行基本檢查以幫助你儘早抓出錯誤。

靜態型別檢查器，例如 Mypy@footnote{https://mypy-lang.org/}、Pyre@footnote{https://pyre-check.org/} 和 Pytype@footnote{https://github.com/google/pytype} 可以檢查 Python 原始碼中的型別提示。

@node 如何從 Python 腳本建立獨立的二進位檔案？,Python 程式碼是否有編碼標準或風格指南？,有沒有工具能夠幫忙找 bug 或執行靜態分析？,常見問題
@anchor{faq/programming faq-create-standalone-binary}@anchor{5633}@anchor{faq/programming how-can-i-create-a-stand-alone-binary-from-a-python-script}@anchor{5634}
@subsubsection 如何從 Python 腳本建立獨立的二進位檔案？


You don't need the ability to compile Python to C code if all you want is a
stand-alone program that users can download and run without having to install
the Python distribution first.  There are a number of tools that determine the
set of modules required by a program and bind these modules together with a
Python binary to produce a single executable.

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.

It works by scanning your source recursively for import statements (in both
forms) and looking for the modules in the standard Python path as well as in the
source directory (for built-in modules).  It then turns the bytecode for modules
written in Python into C code (array initializers that can be turned into code
objects using the marshal module) and creates a custom-made config file that
only contains those built-in modules which are actually used in the program.  It
then compiles the generated C code and links it with the rest of the Python
interpreter to form a self-contained binary which acts exactly like your script.

以下套件可以幫助建立 console 和 GUI 可執行檔案：


@itemize *

@item 
Nuitka@footnote{https://nuitka.net/}（跨平台）

@item 
PyInstaller@footnote{https://pyinstaller.org/}（跨平台）

@item 
PyOxidizer@footnote{https://pyoxidizer.readthedocs.io/en/stable/}（跨平台）

@item 
cx_Freeze@footnote{https://marcelotduarte.github.io/cx_Freeze/}（跨平台）

@item 
py2app@footnote{https://github.com/ronaldoussoren/py2app}（僅限 macOS）

@item 
py2exe@footnote{https://www.py2exe.org/}（僅限 Windows）
@end itemize

@node Python 程式碼是否有編碼標準或風格指南？,,如何從 Python 腳本建立獨立的二進位檔案？,常見問題
@anchor{faq/programming are-there-coding-standards-or-a-style-guide-for-python-programs}@anchor{5635}
@subsubsection Python 程式碼是否有編碼標準或風格指南？


是的。標準函式庫模組所需的編碼風格稱為 
@geindex Python Enhancement Proposals; PEP 8
PEP 8@footnote{https://peps.python.org/pep-0008/}。

@node 核心語言,數字和字串,常見問題,程式開發常見問答集
@anchor{faq/programming core-language}@anchor{5636}
@subsection 核心語言


@menu
* 為什麼當變數有值時，我仍得到錯誤訊息 UnboundLocalError？:: 
* Python 的區域變數和全域變數有什麼規則？:: 
* 為什麼以不同的值在迴圈中定義的 lambda 都回傳相同的結果？:: 
* 如何跨模組共享全域變數？:: 
* 在模組中使用 import 的「最佳實踐」有哪些？:: 
* 為什麼物件之間共享預設值？:: 
* How can I pass optional or keyword parameters from one function to another?:: 
* 引數 (arguments) 和參數 (parameters) 有什麼區別？: 引數 arguments 和參數 parameters 有什麼區別？. 
* 為什麼更改串列 'y' 也會更改串列 'x'？:: 
* 如何編寫帶有輸出參數的函式（透過傳參照呼叫 (call by reference)）？: 如何編寫帶有輸出參數的函式（透過傳參照呼叫 call by reference ）？. 
* 你如何在 Python 中建立高階函式？:: 
* 如何在 Python 中複製物件？:: 
* 如何找到物件的方法或屬性？:: 
* 我的程式碼如何發現物件的名稱？:: 
* 逗號運算子的優先級是什麼？:: 
* 是否有等效於 C 的 "?;" 三元運算子？: 是否有等效於 C 的 "? " 三元運算子？. 
* Is it possible to write obfuscated one-liners in Python?:: 
* 函式參數串列中的斜線 (/) 是什麼意思？: 函式參數串列中的斜線 / 是什麼意思？. 

@end menu

@node 為什麼當變數有值時，我仍得到錯誤訊息 UnboundLocalError？,Python 的區域變數和全域變數有什麼規則？,,核心語言
@anchor{faq/programming faq-unboundlocalerror}@anchor{22db}@anchor{faq/programming why-am-i-getting-an-unboundlocalerror-when-the-variable-has-a-value}@anchor{5637}
@subsubsection 為什麼當變數有值時，我仍得到錯誤訊息 UnboundLocalError？


It can be a surprise to get the @ref{172a,,UnboundLocalError} in previously working
code when it is modified by adding an assignment statement somewhere in
the body of a function.

這段程式碼:

@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: local variable 'x' referenced before assignment
@end example

This is because when you make an assignment to a variable in a scope, that
variable becomes local to that scope and shadows any similarly named variable
in the outer scope.  Since the last statement in foo assigns a new value to
@code{x}, the compiler recognizes it as a local variable.  Consequently when the
earlier @code{print(x)} attempts to print the uninitialized local variable and
an error results.

在上面的範例中，你可以透過將其聲明為全域變數來存取外部範圍變數：

@example
>>> x = 10
>>> def foobar():
...     global x
...     print(x)
...     x += 1
...
>>> foobar()
10
@end example

This explicit declaration is required in order to remind you that (unlike the
superficially analogous situation with class and instance variables) you are
actually modifying the value of the variable in the outer scope:

@example
>>> print(x)
11
@end example

你可以使用 @ref{14a8,,nonlocal} 關鍵字在巢狀作用域內做類似的事情：

@example
>>> def foo():
...    x = 10
...    def bar():
...        nonlocal x
...        print(x)
...        x += 1
...    bar()
...    print(x)
...
>>> foo()
10
11
@end example

@node Python 的區域變數和全域變數有什麼規則？,為什麼以不同的值在迴圈中定義的 lambda 都回傳相同的結果？,為什麼當變數有值時，我仍得到錯誤訊息 UnboundLocalError？,核心語言
@anchor{faq/programming what-are-the-rules-for-local-and-global-variables-in-python}@anchor{5638}
@subsubsection Python 的區域變數和全域變數有什麼規則？


In Python, variables that are only referenced inside a function are implicitly
global.  If a variable is assigned a value anywhere within the function's body,
it's assumed to be a local unless explicitly declared as global.

Though a bit surprising at first, a moment's consideration explains this.  On
one hand, requiring @ref{4a7,,global} for assigned variables provides a bar
against unintended side-effects.  On the other hand, if @code{global} was required
for all global references, you'd be using @code{global} all the time.  You'd have
to declare as global every reference to a built-in function or to a component of
an imported module.  This clutter would defeat the usefulness of the @code{global}
declaration for identifying side-effects.

@node 為什麼以不同的值在迴圈中定義的 lambda 都回傳相同的結果？,如何跨模組共享全域變數？,Python 的區域變數和全域變數有什麼規則？,核心語言
@anchor{faq/programming why-do-lambdas-defined-in-a-loop-with-different-values-all-return-the-same-result}@anchor{5639}
@subsubsection 為什麼以不同的值在迴圈中定義的 lambda 都回傳相同的結果？


假設你使用 for 迴圈來定義幾個不同的 lambda（甚至是普通函式），例如：

@example
>>> squares = []
>>> for x in range(5):
...     squares.append(lambda: x**2)
@end example

這會提供一個包含五個計算 @code{x**2} 的 lambda 串列。你可能會預期在呼叫它時，它們會分別回傳 @code{0}、@code{1}、@code{4}、@code{9} 和 @code{16}，然而當你實際嘗試你會發現它們都回傳 @code{16}：

@example
>>> squares[2]()
16
>>> squares[4]()
16
@end example

發生這種情況是因為 @code{x} 不是 lambda 的局部變數，而是在外部作用域中定義的，且是在呼叫 lambda 時才會存取它，並非於定義時就會存取。在迴圈結束時，@code{x} 的值為 @code{4}，因此所有函式都回傳 @code{4**2}，即為 @code{16}。你還可以透過更改 @code{x} 的值來驗證這一點，並查看 lambda 運算式的結果如何變化：

@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

Here, @code{n=x} creates a new variable @code{n} local to the lambda and computed
when the lambda is defined so that it has the same value that @code{x} had at
that point in the loop.  This means that the value of @code{n} will be @code{0}
in the first lambda, @code{1} in the second, @code{2} in the third, and so on.
Therefore each lambda will now return the correct result:

@example
>>> squares[2]()
4
>>> squares[4]()
16
@end example

請注意，此行為並非 lambda 所特有，也適用於常規函式。

@node 如何跨模組共享全域變數？,在模組中使用 import 的「最佳實踐」有哪些？,為什麼以不同的值在迴圈中定義的 lambda 都回傳相同的結果？,核心語言
@anchor{faq/programming how-do-i-share-global-variables-across-modules}@anchor{563a}
@subsubsection 如何跨模組共享全域變數？


The canonical way to share information across modules within a single program is
to create a special module (often called config or cfg).  Just import the config
module in all modules of your application; the module then becomes available as
a global name.  Because there is only one instance of each module, any changes
made to the module object get reflected everywhere.  For example:

config.py：

@example
x = 0   # 'x' 配置設定的預設值
@end example

mod.py：

@example
import config
config.x = 1
@end example

main.py：

@example
import config
import mod
print(config.x)
@end example

請注意，出於同樣的原因，使用模組也是實作單例設計模式的基礎。

@node 在模組中使用 import 的「最佳實踐」有哪些？,為什麼物件之間共享預設值？,如何跨模組共享全域變數？,核心語言
@anchor{faq/programming what-are-the-best-practices-for-using-import-in-a-module}@anchor{563b}
@subsubsection 在模組中使用 import 的「最佳實踐」有哪些？


In general, don't use @code{from modulename import *}.  Doing so clutters the
importer's namespace, and makes it much harder for linters to detect undefined
names.

Import modules at the top of a file.  Doing so makes it clear what other modules
your code requires and avoids questions of whether the module name is in scope.
Using one import per line makes it easy to add and delete module imports, but
using multiple imports per line uses less screen space.

It's good practice if you import modules in the following order:


@enumerate 

@item 
標準函式庫模組 —— 例如 @ref{df,,sys}、@ref{a5,,os}、@ref{7,,argparse}、@ref{be,,re}

@item 
third-party library modules (anything installed in Python's site-packages
directory) -- e.g. @code{dateutil}, @code{requests}, @code{PIL.Image}

@item 
本地開發的模組
@end enumerate

It is sometimes necessary to move imports to a function or class to avoid
problems with circular imports.  Gordon McMillan says:

@quotation

Circular imports are fine where both modules use the "import <module>" form
of import.  They fail when the 2nd module wants to grab a name out of the
first ("from module import name") and the import is at the top level.  That's
because names in the 1st are not yet available, because the first module is
busy importing the 2nd.
@end quotation

In this case, if the second module is only used in one function, then the import
can easily be moved into that function.  By the time the import is called, the
first module will have finished initializing, and the second module can do its
import.

It may also be necessary to move imports out of the top level of code if some of
the modules are platform-specific.  In that case, it may not even be possible to
import all of the modules at the top of the file.  In this case, importing the
correct modules in the corresponding platform-specific code is a good option.

Only move imports into a local scope, such as inside a function definition, if
it's necessary to solve a problem such as avoiding a circular import or are
trying to reduce the initialization time of a module.  This technique is
especially helpful if many of the imports are unnecessary depending on how the
program executes.  You may also want to move imports into a function if the
modules are only ever used in that function.  Note that loading a module the
first time may be expensive because of the one time initialization of the
module, but loading a module multiple times is virtually free, costing only a
couple of dictionary lookups.  Even if the module name has gone out of scope,
the module is probably available in @ref{17c0,,sys.modules}.

@node 為什麼物件之間共享預設值？,How can I pass optional or keyword parameters from one function to another?,在模組中使用 import 的「最佳實踐」有哪些？,核心語言
@anchor{faq/programming why-are-default-values-shared-between-objects}@anchor{563c}
@subsubsection 為什麼物件之間共享預設值？


這種類型的錯誤通常會困擾新手程式員。像是這個函式：

@example
def foo(mydict=@{@}):  # 危險：所有呼叫共享對字典的參照
    ... 計算一些東西 ...
    mydict[key] = value
    return mydict
@end example

第一次呼叫此函式時， @code{mydict} 包含一個項目。第二次後 @code{mydict} 包含兩個項目，因為當 @code{foo()} 開始執行時，@code{mydict} 以其中已有的項目開始。

It is often expected that a function call creates new objects for default
values. This is not what happens. Default values are created exactly once, when
the function is defined.  If that object is changed, like the dictionary in this
example, subsequent calls to the function will refer to this changed object.

By definition, immutable objects such as numbers, strings, tuples, and @code{None},
are safe from change. Changes to mutable objects such as dictionaries, lists,
and class instances can lead to confusion.

由於這個特性，不使用可變物件作為預設值是一個很好的程式設計習慣，而是應使用 @code{None} 作為預設值，並在函式內部檢查參數是否為 @code{None}，再建立一個新的串列/字典/或其他東西。例如，不要這樣寫：

@example
def foo(mydict=@{@}):
    ...
@end example

而是寫成：

@example
def foo(mydict=None):
    if mydict is None:
        mydict = @{@}  # 為區域命名空間建立一個新字典
@end example

This feature can be useful.  When you have a function that's time-consuming to
compute, a common technique is to cache the parameters and the resulting value
of each call to the function, and return the cached value if the same value is
requested again.  This is called "memoizing", and can be implemented like this:

@example
# 呼叫者只能提供兩個參數，並選擇性地透過關鍵字傳遞 _cache
def expensive(arg1, arg2, *, _cache=@{@}):
    if (arg1, arg2) in _cache:
        return _cache[(arg1, arg2)]

    # Calculate the value
    result = ... expensive computation ...
    _cache[(arg1, arg2)] = result           # 將結果儲存在快取中
    return result
@end example

你可以使用包含字典的全域變數而不是預設值；這取決於喜好。

@node How can I pass optional or keyword parameters from one function to another?,引數 arguments 和參數 parameters 有什麼區別？,為什麼物件之間共享預設值？,核心語言
@anchor{faq/programming how-can-i-pass-optional-or-keyword-parameters-from-one-function-to-another}@anchor{563d}
@subsubsection How can I pass optional or keyword parameters from one function to another?


Collect the arguments using the @code{*} and @code{**} specifiers in the function's
parameter list; this gives you the positional arguments as a tuple and the
keyword arguments as a dictionary.  You can then pass these arguments when
calling another function by using @code{*} and @code{**}:

@example
def f(x, *args, **kwargs):
    ...
    kwargs['width'] = '14.3c'
    ...
    g(x, *args, **kwargs)
@end example

@geindex argument（引數）;與 parameter（參數）的差異
@geindex parameter（參數）;與 argument（引數）的差異

@node 引數 arguments 和參數 parameters 有什麼區別？,為什麼更改串列 'y' 也會更改串列 'x'？,How can I pass optional or keyword parameters from one function to another?,核心語言
@anchor{faq/programming faq-argument-vs-parameter}@anchor{563e}@anchor{faq/programming what-is-the-difference-between-arguments-and-parameters}@anchor{563f}
@subsubsection 引數 (arguments) 和參數 (parameters) 有什麼區別？


@ref{21fd,,參數}由出現在函式定義中的名稱定義，而@ref{673,,引數}是呼叫函式時實際傳遞給函式的值。參數定義函式可以接受的@ref{21fd,,引數種類}。例如，給定以下函式定義：

@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'？,如何編寫帶有輸出參數的函式（透過傳參照呼叫 call by reference ）？,引數 arguments 和參數 parameters 有什麼區別？,核心語言
@anchor{faq/programming why-did-changing-list-y-also-change-list-x}@anchor{5640}
@subsubsection 為什麼更改串列 'y' 也會更改串列 'x'？


如果你寫了像這樣的程式碼：

@example
>>> x = []
>>> y = x
>>> y.append(10)
>>> y
[10]
>>> x
[10]
@end example

你可能想知道為什麼將一個元素附加到 @code{y} 時也會改變 @code{x}。

產生這個結果的原因有兩個：


@enumerate 

@item 
Variables are simply names that refer to objects.  Doing @code{y = x} doesn't
create a copy of the list -- it creates a new variable @code{y} that refers to
the same object @code{x} refers to.  This means that there is only one object
(the list), and both @code{x} and @code{y} refer to it.

@item 
list 是 @ref{1eac,,mutable}，這意味著你可以變更它們的內容。
@end enumerate

After the call to @ref{2288,,append()}, the content of the mutable object has
changed from @code{[]} to @code{[10]}.  Since both the variables refer to the same
object, using either name accesses the modified value @code{[10]}.

如果我們改為賦予一個不可變物件給 @code{x}：

@example
>>> x = 5  # 整數為不可變的
>>> y = x
>>> x = x + 1  # 5 不可變，在這邊會建立一個新物件
>>> x
6
>>> y
5
@end example

we can see that in this case @code{x} and @code{y} are not equal anymore.  This is
because integers are @ref{1ea7,,immutable}, and when we do @code{x = x + 1} we are not
mutating the int @code{5} by incrementing its value; instead, we are creating a
new object (the int @code{6}) and assigning it to @code{x} (that is, changing which
object @code{x} refers to).  After this assignment we have two objects (the ints
@code{6} and @code{5}) and two variables that refer to them (@code{x} now refers to
@code{6} but @code{y} still refers to @code{5}).

Some operations (for example @code{y.append(10)} and @code{y.sort()}) mutate the
object, whereas superficially similar operations (for example @code{y = y + [10]}
and @ref{dc2,,sorted(y)}) create a new object.  In general in Python (and in all cases
in the standard library) a method that mutates an object will return @code{None}
to help avoid getting the two types of operations confused.  So if you
mistakenly write @code{y.sort()} thinking it will give you a sorted copy of @code{y},
you'll instead end up with @code{None}, which will likely cause your program to
generate an easily diagnosed error.

However, there is one class of operations where the same operation sometimes
has different behaviors with different types:  the augmented assignment
operators.  For example, @code{+=} mutates lists but not tuples or ints (@code{a_list
+= [1, 2, 3]} is equivalent to @code{a_list.extend([1, 2, 3])} and mutates
@code{a_list}, whereas @code{some_tuple += (1, 2, 3)} and @code{some_int += 1} create
new objects).

換句話說：


@itemize *

@item 
If we have a mutable object (@ref{24d,,list}, @ref{183,,dict}, @ref{184,,set},
etc.), 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 (@ref{169,,str}, @ref{19b,,int}, @ref{60c,,tuple},
etc.), 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

If you want to know if two variables refer to the same object or not, you can
use the @ref{34a,,is} operator, or the built-in function @ref{161a,,id()}.

@node 如何編寫帶有輸出參數的函式（透過傳參照呼叫 call by reference ）？,你如何在 Python 中建立高階函式？,為什麼更改串列 'y' 也會更改串列 'x'？,核心語言
@anchor{faq/programming how-do-i-write-a-function-with-output-parameters-call-by-reference}@anchor{5641}
@subsubsection 如何編寫帶有輸出參數的函式（透過傳參照呼叫 (call by reference)）？


請記住，在 Python 中引數是透過賦值傳遞的。由於賦值只是建立對物件的參照，因此呼叫者和被呼叫者的引數名稱之間沒有別名，因此本身沒有傳參照呼叫。你可以透過多種方式實作所需的效果。


@enumerate 

@item 
透過回傳結果的元組：

@example
>>> def func1(a, b):
...     a = 'new-value'        # a 和 b 為區域名稱
...     b = b + 1              # 賦值到新物件
...     return a, b            # 回傳新值
...
>>> x, y = 'old-value', 99
>>> func1(x, y)
('new-value', 100)
@end example

這幾乎都會是最清楚的方案。

@item 
透過使用全域變數。這不是執行緒安全的，所以不推薦。

@item 
透過傳遞一個可變的（可於原地 (in-place) 改變的）物件：

@example
>>> def func2(a):
...     a[0] = 'new-value'     # 'a' 參照一個可變的串列
...     a[1] = a[1] + 1        # 改變共享的物件
...
>>> args = ['old-value', 99]
>>> func2(args)
>>> args
['new-value', 100]
@end example

@item 
透過傳入一個發生改變的字典：

@example
>>> def func3(args):
...     args['a'] = 'new-value'     # args 是可變字典
...     args['b'] = args['b'] + 1   # 原地改變它
...
>>> 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 是可變命名空間
...     args.b = args.b + 1         # 原地改變物件
...
>>> args = Namespace(a='old-value', b=99)
>>> func4(args)
>>> vars(args)
@{'a': 'new-value', 'b': 100@}
@end example

幾乎不會有要讓事情變得如此複雜的充分理由。
@end enumerate

你最好的選擇是回傳一個包含多個結果的元組。

@node 你如何在 Python 中建立高階函式？,如何在 Python 中複製物件？,如何編寫帶有輸出參數的函式（透過傳參照呼叫 call by reference ）？,核心語言
@anchor{faq/programming how-do-you-make-a-higher-order-function-in-python}@anchor{5642}
@subsubsection 你如何在 Python 中建立高階函式？


你有兩種選擇：可以使用巢狀作用域，也可以使用可呼叫物件。例如，假設你想定義 @code{linear(a,b)}，它會回傳 @code{a*x+b} 計算值的函式 @code{f(x)}。使用巢狀作用域：

@example
def linear(a, b):
    def result(x):
        return a * x + b
    return result
@end example

或者使用可呼叫物件：

@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

給定一個可呼叫物件，其中 @code{taxes(10e6) == 0.3 * 10e6 + 2}。

The callable object approach has the disadvantage that it is a bit slower and
results in slightly longer code.  However, note that a collection of callables
can share their signature via inheritance:

@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 中建立高階函式？,核心語言
@anchor{faq/programming how-do-i-copy-an-object-in-python}@anchor{5643}
@subsubsection 如何在 Python 中複製物件？


In general, try @ref{750,,copy.copy()} or @ref{d5d,,copy.deepcopy()} for the general case.
Not all objects can be copied, but most can.

Some objects can be copied more easily.  Dictionaries have a @ref{dc4,,copy()}
method:

@example
newdict = olddict.copy()
@end example

序列可以透過切片 (slicing) 複製：

@example
new_l = l[:]
@end example

@node 如何找到物件的方法或屬性？,我的程式碼如何發現物件的名稱？,如何在 Python 中複製物件？,核心語言
@anchor{faq/programming how-can-i-find-the-methods-or-attributes-of-an-object}@anchor{5644}
@subsubsection 如何找到物件的方法或屬性？


For an instance @code{x} of a user-defined class, @ref{83d,,dir(x)} returns an alphabetized
list of the names containing the instance attributes and methods and attributes
defined by its class.

@node 我的程式碼如何發現物件的名稱？,逗號運算子的優先級是什麼？,如何找到物件的方法或屬性？,核心語言
@anchor{faq/programming how-can-my-code-discover-the-name-of-an-object}@anchor{5645}
@subsubsection 我的程式碼如何發現物件的名稱？


Generally speaking, it can't, because objects don't really have names.
Essentially, assignment always binds a name to a value; the same is true of
@code{def} and @code{class} statements, but in that case the value is a
callable. Consider the following code:

@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

Arguably the class has a name: even though it is bound to two names and invoked
through the name @code{B} the created instance is still reported as an instance of
class @code{A}.  However, it is impossible to say whether the instance's name is @code{a} or
@code{b}, since both names are bound to the same value.

Generally speaking it should not be necessary for your code to "know the names"
of particular values. Unless you are deliberately writing introspective
programs, this is usually an indication that a change of approach might be
beneficial.

在 comp.lang.python 中，Fredrik Lundh 曾針對這個問題給出了一個極好的比喻：

@quotation

就像你在門廊上發現的那隻貓的名字一樣：貓（物件）本身不能告訴你它的名字，它也不關心 - 所以找出它叫什麼的唯一方法是詢問所有鄰居（命名空間）是否是他們的貓（物件）...

....如果你發現它有很多名字，或者根本沒有名字，請不要感到驚訝！
@end quotation

@node 逗號運算子的優先級是什麼？,是否有等效於 C 的 "? " 三元運算子？,我的程式碼如何發現物件的名稱？,核心語言
@anchor{faq/programming what-s-up-with-the-comma-operator-s-precedence}@anchor{5646}
@subsubsection 逗號運算子的優先級是什麼？


Comma is not an operator in Python.  Consider this session:

@example
>>> "a" in "b", "a"
(False, 'a')
@end example

Since the comma is not an operator, but a separator between expressions the
above is evaluated as if you had entered:

@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{+=} etc).  They
are not truly operators but syntactic delimiters in assignment statements.

@node 是否有等效於 C 的 "? " 三元運算子？,Is it possible to write obfuscated one-liners in Python?,逗號運算子的優先級是什麼？,核心語言
@anchor{faq/programming is-there-an-equivalent-of-c-s-ternary-operator}@anchor{5647}
@subsubsection 是否有等效於 C 的 "?:" 三元運算子？


有的，語法如下：

@example
[on_true] if [expression] else [on_false]

x, y = 50, 25
small = x if x < y else y
@end example

Before this syntax was introduced in Python 2.5, a common idiom was to use
logical operators:

@example
[expression] and [on_true] or [on_false]
@end example

However, this idiom is unsafe, as it can give wrong results when `on_true'
has a false boolean value.  Therefore, it is always better to use
the @code{... if ... else ...} form.

@node Is it possible to write obfuscated one-liners in Python?,函式參數串列中的斜線 / 是什麼意思？,是否有等效於 C 的 "? " 三元運算子？,核心語言
@anchor{faq/programming is-it-possible-to-write-obfuscated-one-liners-in-python}@anchor{5648}
@subsubsection Is it possible to write obfuscated one-liners in Python?


Yes.  Usually this is done by nesting @ref{149e,,lambda} within
@code{lambda}.  See the following three examples, slightly adapted from 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 函式參數串列中的斜線 / 是什麼意思？,,Is it possible to write obfuscated one-liners in Python?,核心語言
@anchor{faq/programming faq-positional-only-arguments}@anchor{2480}@anchor{faq/programming what-does-the-slash-in-the-parameter-list-of-a-function-mean}@anchor{5649}
@subsubsection 函式參數串列中的斜線 (/) 是什麼意思？


A slash in the argument list of a function denotes that the parameters prior to
it are positional-only.  Positional-only parameters are the ones without an
externally usable name.  Upon calling a function that accepts positional-only
parameters, arguments are mapped to parameters based solely on their position.
For example, @ref{b90,,divmod()} is a function that accepts positional-only
parameters. Its documentation looks like this:

@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{b90,,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 數字和字串,效能<3>,核心語言,程式開發常見問答集
@anchor{faq/programming numbers-and-strings}@anchor{564a}
@subsection 數字和字串


@menu
* 如何指定十六進位和八進位整數？:: 
* 為什麼 -22 // 10 回傳 -3？:: 
* How do I get int literal attribute instead of SyntaxError?:: 
* 如何將字串轉換為數字？:: 
* 如何將數字轉換為字串？:: 
* 如何原地修改字串？:: 
* 如何使用字串呼叫函式/方法？:: 
* Is there an equivalent to Perl's chomp() for removing trailing newlines from strings?: Is there an equivalent to Perl's chomp for removing trailing newlines from strings?. 
* Is there a scanf() or sscanf() equivalent?: Is there a scanf or sscanf equivalent?. 
* What does UnicodeDecodeError or UnicodeEncodeError error mean?:: 
* Can I end a raw string with an odd number of backslashes?:: 

@end menu

@node 如何指定十六進位和八進位整數？,為什麼 -22 // 10 回傳 -3？,,數字和字串
@anchor{faq/programming how-do-i-specify-hexadecimal-and-octal-integers}@anchor{564b}
@subsubsection 如何指定十六進位和八進位整數？


To specify an octal digit, precede the octal value with a zero, and then a lower
or uppercase "o".  For example, to set the variable "a" to the octal value "10"
(8 in decimal), type:

@example
>>> a = 0o10
>>> a
8
@end example

Hexadecimal is just as easy.  Simply precede the hexadecimal number with a zero,
and then a lower or uppercase "x".  Hexadecimal digits can be specified in lower
or uppercase.  For example, in the Python interpreter:

@example
>>> a = 0xa5
>>> a
165
>>> b = 0XB2
>>> b
178
@end example

@node 為什麼 -22 // 10 回傳 -3？,How do I get int literal attribute instead of SyntaxError?,如何指定十六進位和八進位整數？,數字和字串
@anchor{faq/programming why-does-22-10-return-3}@anchor{564c}
@subsubsection 為什麼 -22 // 10 回傳 -3？


It's primarily driven by the desire that @code{i % j} have the same sign as @code{j}.
If you want that, and also want:

@example
i == (i // j) * j + (i % j)
@end example

那麼整數除法必須回傳向下取整的結果。 C 還要求保留​​該識別性，然後截斷 @code{i // j} 的編譯器需要使 @code{i % j} 具有與 @code{i} 相同的符號。

There are few real use cases for @code{i % j} when @code{j} is negative.  When @code{j}
is positive, there are many, and in virtually all of them it's more useful for
@code{i % j} to be @code{>= 0}.  If the clock says 10 now, what did it say 200 hours
ago?  @code{-190 % 12 == 2} is useful; @code{-190 % 12 == -10} is a bug waiting to
bite.

@node How do I get int literal attribute instead of SyntaxError?,如何將字串轉換為數字？,為什麼 -22 // 10 回傳 -3？,數字和字串
@anchor{faq/programming how-do-i-get-int-literal-attribute-instead-of-syntaxerror}@anchor{564d}
@subsubsection How do I get int literal attribute instead of SyntaxError?


嘗試以正常方式查找 @code{int} 字面值屬性會給出一個 @ref{18e,,SyntaxError}，因為句點被視為小數點：

@example
>>> 1.__class__
  File "<stdin>", line 1
  1.__class__
   ^
SyntaxError: invalid decimal literal
@end example

解決方式是用空格或圓括號將字面值與句點分開。

@example
>>> 1 .__class__
<class 'int'>
>>> (1).__class__
<class 'int'>
@end example

@node 如何將字串轉換為數字？,如何將數字轉換為字串？,How do I get int literal attribute instead of SyntaxError?,數字和字串
@anchor{faq/programming how-do-i-convert-a-string-to-a-number}@anchor{564e}
@subsubsection 如何將字串轉換為數字？


For integers, use the built-in @ref{19b,,int()} type constructor, e.g. @code{int('144')
== 144}.  Similarly, @ref{196,,float()} converts to a floating-point number,
e.g. @code{float('144') == 144.0}.

By default, these interpret the number as decimal, so that @code{int('0144') ==
144} holds true, and @code{int('0x144')} raises @ref{2eb,,ValueError}. @code{int(string,
base)} takes the base to convert from as a second optional argument, so @code{int(
'0x144', 16) == 324}.  If the base is specified as 0, the number is interpreted
using Python's rules: a leading '0o' indicates octal, and '0x' indicates a hex
number.

Do not use the built-in function @ref{49e,,eval()} if all you need is to convert
strings to numbers.  @ref{49e,,eval()} will be significantly slower and it presents a
security risk: someone could pass you a Python expression that might have
unwanted side effects.  For example, someone could pass
@code{__import__('os').system("rm -rf $HOME")} which would erase your home
directory.

@ref{49e,,eval()} also has the effect of interpreting numbers as Python expressions,
so that e.g. @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{564f}
@subsubsection 如何將數字轉換為字串？


To convert, e.g., the number @code{144} to the string @code{'144'}, use the built-in type
constructor @ref{169,,str()}.  If you want a hexadecimal or octal representation, use
the built-in functions @ref{14d0,,hex()} or @ref{14cf,,oct()}.  For fancy formatting, see
the @ref{19a,,f-string（f 字串）} and @ref{1593,,格式化文字語法} sections,
e.g. @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{5650}
@subsubsection 如何原地修改字串？


這沒辦法做到，因為字串是不可變的。在大多數情況下，你應以要拿來組裝的各個部分建構出一個新字串。但是如果你需要一個能夠原地修改 unicode 資料的物件，請嘗試使用 @ref{1124,,io.StringIO} 物件或 @ref{8,,array} 模組：

@example
>>> import io
>>> s = "Hello, world"
>>> sio = io.StringIO(s)
>>> sio.getvalue()
'Hello, world'
>>> sio.seek(7)
7
>>> sio.write("there!")
6
>>> sio.getvalue()
'Hello, there!'

>>> import array
>>> a = array.array('w', s)
>>> print(a)
array('w', 'Hello, world')
>>> a[0] = 'y'
>>> print(a)
array('w', 'yello, world')
>>> a.tounicode()
'yello, world'
@end example

@node 如何使用字串呼叫函式/方法？,Is there an equivalent to Perl's chomp for removing trailing newlines from strings?,如何原地修改字串？,數字和字串
@anchor{faq/programming how-do-i-use-strings-to-call-functions-methods}@anchor{5651}
@subsubsection 如何使用字串呼叫函式/方法？


有各式各樣的技法。


@itemize *

@item 
The best is to use a dictionary that maps strings to functions.  The primary
advantage of this technique is that the strings do not need to match the names
of the functions.  This is also the primary technique used to emulate a case
construct:

@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{dc5,,getattr()}：

@example
import foo
getattr(foo, 'bar')()
@end example

請注意 @ref{dc5,,getattr()} 適用於任何物件，包括類別、類別實例、模組等。

這在標準函式庫中的幾個地方被使用，如：

@example
class Foo:
    def do_foo(self):
        ...

    def do_bar(self):
        ...

f = getattr(foo_instance, 'do_' + opname)
f()
@end example

@item 
使用 @ref{469,,locals()} 解析函式名稱：

@example
def myFunc():
    print("hello")

fname = "myFunc"

f = locals()[fname]
f()
@end example
@end itemize

@node Is there an equivalent to Perl's chomp for removing trailing newlines from strings?,Is there a scanf or sscanf equivalent?,如何使用字串呼叫函式/方法？,數字和字串
@anchor{faq/programming is-there-an-equivalent-to-perl-s-chomp-for-removing-trailing-newlines-from-strings}@anchor{5652}
@subsubsection Is there an equivalent to Perl's @code{chomp()} for removing trailing newlines from strings?


You can use @code{S.rstrip("\r\n")} to remove all occurrences of any line
terminator from the end of the string @code{S} without removing other trailing
whitespace.  If the string @code{S} represents more than one line, with several
empty lines at the end, the line terminators for all the blank lines will
be removed:

@example
>>> lines = ("line 1 \r\n"
...          "\r\n"
...          "\r\n")
>>> lines.rstrip("\n\r")
'line 1 '
@end example

Since this is typically only desired when reading text one line at a time, using
@code{S.rstrip()} this way works well.

@node Is there a scanf or sscanf equivalent?,What does UnicodeDecodeError or UnicodeEncodeError error mean?,Is there an equivalent to Perl's chomp for removing trailing newlines from strings?,數字和字串
@anchor{faq/programming is-there-a-scanf-or-sscanf-equivalent}@anchor{5653}
@subsubsection Is there a @code{scanf()} or @code{sscanf()} equivalent?


Not as such.

For simple input parsing, the easiest approach is usually to split the line into
whitespace-delimited words using the @ref{10a5,,split()} method of string objects
and then convert decimal strings to numeric values using @ref{19b,,int()} or
@ref{196,,float()}.  @code{split()} supports an optional "sep" parameter which is useful
if the line uses something other than whitespace as a separator.

For more complicated input parsing, regular expressions are more powerful
than C's @code{sscanf} and better suited for the task.

@node What does UnicodeDecodeError or UnicodeEncodeError error mean?,Can I end a raw string with an odd number of backslashes?,Is there a scanf or sscanf equivalent?,數字和字串
@anchor{faq/programming what-does-unicodedecodeerror-or-unicodeencodeerror-error-mean}@anchor{5654}
@subsubsection What does @code{UnicodeDecodeError} or @code{UnicodeEncodeError} error mean?


請參閱 @ref{14a5,,Unicode HOWTO}。

@node Can I end a raw string with an odd number of backslashes?,,What does UnicodeDecodeError or UnicodeEncodeError error mean?,數字和字串
@anchor{faq/programming can-i-end-a-raw-string-with-an-odd-number-of-backslashes}@anchor{5655}@anchor{faq/programming faq-programming-raw-string-backslash}@anchor{1ea6}
@subsubsection Can I end a raw string with an odd number of backslashes?


A raw string ending with an odd number of backslashes will escape the string's quote:

@example
>>> r'C:\this\will\not\work\'
  File "<stdin>", line 1
    r'C:\this\will\not\work\'
    ^
SyntaxError: unterminated string literal (detected at line 1)
@end example

There are several workarounds for this. One is to use regular strings and double
the backslashes:

@example
>>> 'C:\\this\\will\\work\\'
'C:\\this\\will\\work\\'
@end example

Another is to concatenate a regular string containing an escaped backslash to the
raw string:

@example
>>> r'C:\this\will\work' '\\'
'C:\\this\\will\\work\\'
@end example

It is also possible to use @ref{1900,,os.path.join()} to append a backslash on Windows:

@example
>>> os.path.join(r'C:\this\will\work', '@w{'})
'C:\\this\\will\\work\\'
@end example

Note that while a backslash will "escape" a quote for the purposes of
determining where the raw string ends, no escaping occurs when interpreting the
value of the raw string. That is, the backslash remains present in the value of
the raw string:

@example
>>> r'backslash\'preserved'
"backslash\\'preserved"
@end example

Also see the specification in the @ref{2163,,language reference}.

@node 效能<3>,序列（元組/串列）,數字和字串,程式開發常見問答集
@anchor{faq/programming performance}@anchor{5656}
@subsection 效能


@menu
* 我的程式太慢了。我該如何加快速度？:: 
* What is the most efficient way to concatenate many strings together?:: 

@end menu

@node 我的程式太慢了。我該如何加快速度？,What is the most efficient way to concatenate many strings together?,,效能<3>
@anchor{faq/programming my-program-is-too-slow-how-do-i-speed-it-up}@anchor{5657}
@subsubsection 我的程式太慢了。我該如何加快速度？


That's a tough one, in general.  First, here are a list of things to
remember before diving further:


@itemize *

@item 
Performance characteristics vary across Python implementations.  This FAQ
focuses on @ref{8fd,,CPython}.

@item 
Behaviour can vary across operating systems, especially when talking about
I/O or multi-threading.

@item 
You should always find the hot spots in your program `before' attempting to
optimize any code (see the @ref{b4,,profile} module).

@item 
Writing benchmark scripts will allow you to iterate quickly when searching
for improvements (see the @ref{f5,,timeit} module).

@item 
It is highly recommended to have good code coverage (through unit testing
or any other technique) before potentially introducing regressions hidden
in sophisticated optimizations.
@end itemize

That being said, there are many tricks to speed up Python code.  Here are
some general principles which go a long way towards reaching acceptable
performance levels:


@itemize *

@item 
Making your algorithms faster (or changing to faster ones) can yield
much larger benefits than trying to sprinkle micro-optimization tricks
all over your code.

@item 
Use the right data structures.  Study documentation for the @ref{2499,,內建型別}
and the @ref{1e,,collections} module.

@item 
When the standard library provides a primitive for doing something, it is
likely (although not guaranteed) to be faster than any alternative you
may come up with.  This is doubly true for primitives written in C, such
as builtins and some extension types.  For example, be sure to use
either the @ref{dc3,,list.sort()} built-in method or the related @ref{dc2,,sorted()}
function to do sorting (and see the @ref{248a,,排序技法} for examples
of moderately advanced usage).

@item 
Abstractions tend to create indirections and force the interpreter to work
more.  If the levels of indirection outweigh the amount of useful work
done, your program will be slower.  You should avoid excessive abstraction,
especially under the form of tiny functions or methods (which are also often
detrimental to readability).
@end itemize

If you have reached the limit of what pure Python can allow, there are tools
to take you further away.  For example, Cython@footnote{https://cython.org} can
compile a slightly modified version of Python code into a C extension, and
can be used on many different platforms.  Cython can take advantage of
compilation (and optional type annotations) to make your code significantly
faster than when interpreted.  If you are confident in your C programming
skills, you can also @ref{1e84,,write a C extension module}
yourself.


@subsubheading 也參考


有個 wiki 頁面專門介紹效能改進小提示@footnote{https://wiki.python.org/moin/PythonSpeed/PerformanceTips}。


@node What is the most efficient way to concatenate many strings together?,,我的程式太慢了。我該如何加快速度？,效能<3>
@anchor{faq/programming efficient-string-concatenation}@anchor{5658}@anchor{faq/programming what-is-the-most-efficient-way-to-concatenate-many-strings-together}@anchor{5659}
@subsubsection What is the most efficient way to concatenate many strings together?


@ref{169,,str} and @ref{192,,bytes} objects are immutable, therefore concatenating
many strings together is inefficient as each concatenation creates a new
object.  In the general case, the total runtime cost is quadratic in the
total string length.

To accumulate many @ref{169,,str} objects, the recommended idiom is to place
them into a list and call @ref{24b9,,str.join()} at the end:

@example
chunks = []
for s in my_strings:
    chunks.append(s)
result = '@w{'}.join(chunks)
@end example

(another reasonably efficient idiom is to use @ref{1124,,io.StringIO})

To accumulate many @ref{192,,bytes} objects, the recommended idiom is to extend
a @ref{343,,bytearray} object using in-place concatenation (the @code{+=} operator):

@example
result = bytearray()
for b in my_bytes_objects:
    result += b
@end example

@node 序列（元組/串列）,物件,效能<3>,程式開發常見問答集
@anchor{faq/programming sequences-tuples-lists}@anchor{565a}
@subsection 序列（元組/串列）


@menu
* 如何在元組和串列之間進行轉換？:: 
* 什麼是負索引？:: 
* How do I iterate over a sequence in reverse order?:: 
* 如何從串列中刪除重複項？:: 
* 如何從串列中刪除多個項目:: 
* How do you make an array in Python?:: 
* 如何建立多維度串列？:: 
* 如何將方法或函式應用於物件序列？:: 
* 為什麼 a_tuple[i] += ['item'] 做加法時會引發例外？:: 
* 我想做一個複雜的排序：你能用 Python 做一個 Schwartzian 變換嗎？:: 
* 如何根據另一個串列中的值對一個串列進行排序？:: 

@end menu

@node 如何在元組和串列之間進行轉換？,什麼是負索引？,,序列（元組/串列）
@anchor{faq/programming how-do-i-convert-between-tuples-and-lists}@anchor{565b}
@subsubsection 如何在元組和串列之間進行轉換？


型別建構函式 @code{tuple(seq)} 將任何序列（實際上是任何可疊代物件）轉換為具有相同順序的相同項的元組。

For example, @code{tuple([1, 2, 3])} yields @code{(1, 2, 3)} and @code{tuple('abc')}
yields @code{('a', 'b', 'c')}.  If the argument is a tuple, it does not make a copy
but returns the same object, so it is cheap to call @ref{60c,,tuple()} when you
aren't sure that an object is already a tuple.

The type constructor @code{list(seq)} converts any sequence or iterable into a list
with the same items in the same order.  For example, @code{list((1, 2, 3))} yields
@code{[1, 2, 3]} and @code{list('abc')} yields @code{['a', 'b', 'c']}.  If the argument
is a list, it makes a copy just like @code{seq[:]} would.

@node 什麼是負索引？,How do I iterate over a sequence in reverse order?,如何在元組和串列之間進行轉換？,序列（元組/串列）
@anchor{faq/programming what-s-a-negative-index}@anchor{565c}
@subsubsection 什麼是負索引？


Python sequences are indexed with positive numbers and negative numbers.  For
positive numbers 0 is the first index 1 is the second index and so forth.  For
negative indices -1 is the last index and -2 is the penultimate (next to last)
index and so forth.  Think of @code{seq[-n]} as the same as @code{seq[len(seq)-n]}.

Using negative indices can be very convenient.  For example @code{S[:-1]} is all of
the string except for its last character, which is useful for removing the
trailing newline from a string.

@node How do I iterate over a sequence in reverse order?,如何從串列中刪除重複項？,什麼是負索引？,序列（元組/串列）
@anchor{faq/programming how-do-i-iterate-over-a-sequence-in-reverse-order}@anchor{565d}
@subsubsection How do I iterate over a sequence in reverse order?


Use the @ref{a5e,,reversed()} built-in function:

@example
for x in reversed(sequence):
    ...  # do something with x ...
@end example

This won't touch your original sequence, but build a new copy with reversed
order to iterate over.

@node 如何從串列中刪除重複項？,如何從串列中刪除多個項目,How do I iterate over a sequence in reverse order?,序列（元組/串列）
@anchor{faq/programming how-do-you-remove-duplicates-from-a-list}@anchor{565e}
@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

如果串列的所有元素都可以做為集合的鍵（即它們都必須是 @ref{81d,,hashable}），那這通常會更快：

@example
mylist = list(set(mylist))
@end example

這會將串列轉換為一個集合，從而刪除重複項，然後再轉換回串列。

@node 如何從串列中刪除多個項目,How do you make an array in Python?,如何從串列中刪除重複項？,序列（元組/串列）
@anchor{faq/programming how-do-you-remove-multiple-items-from-a-list}@anchor{565f}
@subsubsection 如何從串列中刪除多個項目


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

The list comprehension may be fastest.

@node How do you make an array in Python?,如何建立多維度串列？,如何從串列中刪除多個項目,序列（元組/串列）
@anchor{faq/programming how-do-you-make-an-array-in-python}@anchor{5660}
@subsubsection How do you make an array in Python?


Use a list:

@example
["this", 1, "is", "an", "array"]
@end example

Lists are equivalent to C or Pascal arrays in their time complexity; the primary
difference is that a Python list can contain objects of many different types.

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.

To get Lisp-style linked lists, you can emulate `cons cells' using tuples:

@example
lisp_list = ("like",  ("this",  ("example", None) ) )
@end example

If mutability is desired, you could use lists instead of tuples.  Here the
analogue of a Lisp `car' is @code{lisp_list[0]} and the analogue of `cdr' is
@code{lisp_list[1]}.  Only do this if you're sure you really need to, because it's
usually a lot slower than using Python lists.

@node 如何建立多維度串列？,如何將方法或函式應用於物件序列？,How do you make an array in Python?,序列（元組/串列）
@anchor{faq/programming faq-multidimensional-list}@anchor{24b8}@anchor{faq/programming how-do-i-create-a-multidimensional-list}@anchor{5661}
@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 個對長度為 2 的相同串列的參照。對其中一列的變更也將顯示在所有其他列中，而這幾乎不會是你想要的。

建議的方法是先建立所需長度的串列，然後用新建立的串列填充每個元素：

@example
A = [None] * 3
for i in range(3):
    A[i] = [None] * 2
@end example

這會產生一個包含 3 個長度為 2 的不同串列的串列。你也可以使用串列綜合運算式：

@example
w, h = 2, 3
A = [[None] * w for i in range(h)]
@end example

或者你也可以使用提供矩陣資料型別的擴充套件；NumPy@footnote{https://numpy.org/} 是其中最著名的一個。

@node 如何將方法或函式應用於物件序列？,為什麼 a_tuple[i] += ['item'] 做加法時會引發例外？,如何建立多維度串列？,序列（元組/串列）
@anchor{faq/programming how-do-i-apply-a-method-or-function-to-a-sequence-of-objects}@anchor{5662}
@subsubsection 如何將方法或函式應用於物件序列？


To call a method or function and accumulate the return values is a list,
a @ref{8d5,,list comprehension} is an elegant solution:

@example
result = [obj.method() for obj in mylist]

result = [function(obj) for obj in mylist]
@end example

To just run the method or function without saving the return values,
a plain @ref{348,,for} loop will suffice:

@example
for obj in mylist:
    obj.method()

for obj in mylist:
    function(obj)
@end example

@node 為什麼 a_tuple[i] += ['item'] 做加法時會引發例外？,我想做一個複雜的排序：你能用 Python 做一個 Schwartzian 變換嗎？,如何將方法或函式應用於物件序列？,序列（元組/串列）
@anchor{faq/programming faq-augmented-assignment-tuple-error}@anchor{22b1}@anchor{faq/programming why-does-a-tuple-i-item-raise-an-exception-when-the-addition-works}@anchor{5663}
@subsubsection 為什麼 a_tuple[i] += ['item'] 做加法時會引發例外？


This is because of a combination of the fact that augmented assignment
operators are `assignment' operators, and the difference between mutable and
immutable objects in Python.

This discussion applies in general when augmented assignment operators are
applied to elements of a tuple that point to mutable objects, but we'll use
a @code{list} and @code{+=} as our exemplar.

如果你寫了：

@example
>>> a_tuple = (1, 2)
>>> a_tuple[0] += 1
Traceback (most recent call last):
   ...
TypeError: 'tuple' object does not support item assignment
@end example

The reason for the exception should be immediately clear: @code{1} is added to the
object @code{a_tuple[0]} points to (@code{1}), producing the result object, @code{2},
but when we attempt to assign the result of the computation, @code{2}, to element
@code{0} of the tuple, we get an error because we can't change what an element of
a tuple points to.

這個增強賦值陳述式在背後大致是做這些事情：

@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

It is the assignment part of the operation that produces the error, since a
tuple is immutable.

當你寫這樣的東西時：

@example
>>> a_tuple = (['foo'], 'bar')
>>> a_tuple[0] += ['item']
Traceback (most recent call last):
  ...
TypeError: 'tuple' object does not support item assignment
@end example

The exception is a bit more surprising, and even more surprising is the fact
that even though there was an error, the append worked:

@example
>>> a_tuple[0]
['foo', 'item']
@end example

To see why this happens, you need to know that (a) if an object implements an
@ref{2291,,__iadd__()} magic method, it gets called when the @code{+=} augmented
assignment
is executed, and its return value is what gets used in the assignment statement;
and (b) for lists, @code{__iadd__()} is equivalent to calling
@ref{228b,,extend()} on the list and returning the list.
That's why we say that for lists, @code{+=} is a "shorthand" for @ref{5fa,,list.extend()}:

@example
>>> a_list = []
>>> a_list += [1]
>>> a_list
[1]
@end example

這等價於：

@example
>>> result = a_list.__iadd__([1])
>>> a_list = result
@end example

The object pointed to by a_list has been mutated, and the pointer to the
mutated object is assigned back to @code{a_list}.  The end result of the
assignment is a no-op, since it is a pointer to the same object that @code{a_list}
was previously pointing to, but the assignment still happens.

因此，在我們的元組範例中，發生的事情等同於：

@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

The @code{__iadd__()} succeeds, and thus the list is extended, but even though
@code{result} points to the same object that @code{a_tuple[0]} already points to,
that final assignment still results in an error, because tuples are immutable.

@node 我想做一個複雜的排序：你能用 Python 做一個 Schwartzian 變換嗎？,如何根據另一個串列中的值對一個串列進行排序？,為什麼 a_tuple[i] += ['item'] 做加法時會引發例外？,序列（元組/串列）
@anchor{faq/programming i-want-to-do-a-complicated-sort-can-you-do-a-schwartzian-transform-in-python}@anchor{5664}
@subsubsection 我想做一個複雜的排序：你能用 Python 做一個 Schwartzian 變換嗎？


The technique, attributed to Randal Schwartz of the Perl community, sorts the
elements of a list by a metric which maps each element to its "sort value". In
Python, use the @code{key} argument for the @ref{dc3,,list.sort()} method:

@example
Isorted = L[:]
Isorted.sort(key=lambda s: int(s[10:15]))
@end example

@node 如何根據另一個串列中的值對一個串列進行排序？,,我想做一個複雜的排序：你能用 Python 做一個 Schwartzian 變換嗎？,序列（元組/串列）
@anchor{faq/programming how-can-i-sort-one-list-by-values-from-another-list}@anchor{5665}
@subsubsection 如何根據另一個串列中的值對一個串列進行排序？


將它們合併到一個元組疊代器中，對結果的串列進行排序，然後挑選出你想要的元素。

@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 物件,模組<6>,序列（元組/串列）,程式開發常見問答集
@anchor{faq/programming objects}@anchor{5666}
@subsection 物件


@menu
* 什麼是類別 (class)？: 什麼是類別 class ？. 
* 什麼是方法 (method)？: 什麼是方法 method ？. 
* 什麼是 self？:: 
* 如何檢查物件是否是給定類別的實例或其子類別的實例？:: 
* 什麼是委派 (delegation)？: 什麼是委派 delegation ？. 
* How do I call a method defined in a base class from a derived class that extends it?:: 
* 我可以如何組織我的程式碼以使得更改基底類別變的更容易？:: 
* 如何建立靜態類別資料和靜態類別方法？:: 
* 如何在 Python 中多載 (overload) 建構函式（或方法）？: 如何在 Python 中多載 overload 建構函式（或方法）？. 
* 我嘗試使用 __spam，但收到有關 _SomeClassName__spam 的錯誤。:: 
* 我的類別定義了 __del__ 但是當我刪除物件時它沒有被呼叫。:: 
* 我該如何取得給定類別的所有實例的串列？:: 
* 為什麼 id() 的結果看起來不唯一？: 為什麼 id 的結果看起來不唯一？. 
* 我什麼時候可以依靠 is 運算子進行識別性測試？:: 
* 子類別如何控制不可變實例中儲存的資料？:: 
* 如何快取方法呼叫？:: 

@end menu

@node 什麼是類別 class ？,什麼是方法 method ？,,物件
@anchor{faq/programming what-is-a-class}@anchor{5667}
@subsubsection 什麼是類別 (class)？


A class is the particular object type created by executing a class statement.
Class objects are used as templates to create instance objects, which embody
both the data (attributes) and code (methods) specific to a datatype.

A class can be based on one or more other classes, called its base class(es). It
then inherits the attributes and methods of its base classes. This allows an
object model to be successively refined by inheritance.  You might have a
generic @code{Mailbox} class that provides basic accessor methods for a mailbox,
and subclasses such as @code{MboxMailbox}, @code{MaildirMailbox}, @code{OutlookMailbox}
that handle various specific mailbox formats.

@node 什麼是方法 method ？,什麼是 self？,什麼是類別 class ？,物件
@anchor{faq/programming what-is-a-method}@anchor{5668}
@subsubsection 什麼是方法 (method)？


A method is a function on some object @code{x} that you normally call as
@code{x.name(arguments...)}.  Methods are defined as functions inside the class
definition:

@example
class C:
    def meth(self, arg):
        return arg * 2 + self.attribute
@end example

@node 什麼是 self？,如何檢查物件是否是給定類別的實例或其子類別的實例？,什麼是方法 method ？,物件
@anchor{faq/programming what-is-self}@anchor{5669}
@subsubsection 什麼是 self？


Self 只是方法第一個引數的約定名稱。對於所定義類別的某個實例 @code{x}，一個定義為 @code{meth(self, a, b, c)} 的方法應該以 @code{x.meth(a, b, c)} 形式來呼叫；被呼叫的方法會認為它是以 @code{meth(x, a, b, c)} 來呼叫的。

另請參閱 @ref{566a,,為何「self」在方法 (method) 定義和呼叫時一定要明確使用？}。

@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{566b}
@subsubsection 如何檢查物件是否是給定類別的實例或其子類別的實例？


Use the built-in function @ref{2ad,,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, e.g. @code{isinstance(obj, (class1, class2, ...))}, and can also
check whether an object is one of Python's built-in types, e.g.
@code{isinstance(obj, str)} or @code{isinstance(obj, (int, float, complex))}.

請注意，@ref{2ad,,isinstance()} 還會檢查來自@ref{13b7,,抽象基底類別 (abstract base class)} 的虛擬繼承。因此對已註冊類別的檢驗會回傳 @code{True}，即使沒有直接或間接繼承自它。要測試「真正繼承」，請掃描該類別的 @ref{184a,,MRO}：

@example
from collections.abc import Mapping

class P:
     pass

class C(P):
    pass

Mapping.register(P)
@end example

@example
>>> c = C()
>>> isinstance(c, C)        # 直接
True
>>> isinstance(c, P)        # 間接
True
>>> isinstance(c, Mapping)  # 虛擬
True

# 實際的繼承鏈結
>>> type(c).__mro__
(<class 'C'>, <class 'P'>, <class 'object'>)

# 「真正繼承」的檢驗
>>> Mapping in type(c).__mro__
False
@end example

Note that most programs do not use @ref{2ad,,isinstance()} on user-defined classes
very often.  If you are developing the classes yourself, a more proper
object-oriented style is to define methods on the classes that encapsulate a
particular behaviour, instead of checking the object's class and doing a
different thing based on what class it is.  For example, if you have a function
that does something:

@example
def search(obj):
    if isinstance(obj, Mailbox):
        ...  # 搜尋信箱的程式碼
    elif isinstance(obj, Document):
        ...  # 搜尋文件的程式碼
    elif ...
@end example

更好的方法是在所有類別上定義一個 @code{search()} 方法然後呼叫它：

@example
class Mailbox:
    def search(self):
        ...  # 搜尋信箱的程式碼

class Document:
    def search(self):
        ...  # 搜尋文件的程式碼

obj.search()
@end example

@node 什麼是委派 delegation ？,How do I call a method defined in a base class from a derived class that extends it?,如何檢查物件是否是給定類別的實例或其子類別的實例？,物件
@anchor{faq/programming what-is-delegation}@anchor{566c}
@subsubsection 什麼是委派 (delegation)？


委派是一種物件導向的技法（也稱為設計模式）。假設你有一個物件 @code{x} 並且只想更改其中一個方法的行為。你可以建立一個新類別，它提供你想改變的那個方法的新實作，並將所有其他方法委派給 @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

Here the @code{UpperOut} class redefines the @code{write()} method to convert the
argument string to uppercase before calling the underlying
@code{self._outfile.write()} method.  All other methods are delegated to the
underlying @code{self._outfile} object.  The delegation is accomplished via the
@ref{6f3,,__getattr__()} method; consult @ref{2261,,the language reference}
for more information about controlling attribute access.

Note that for more general cases delegation can get trickier. When attributes
must be set as well as retrieved, the class must define a @ref{222d,,__setattr__()}
method too, and it must do so carefully.  The basic implementation of
@code{__setattr__()} is roughly equivalent to the following:

@example
class X:
    ...
    def __setattr__(self, name, value):
        self.__dict__[name] = value
    ...
@end example

許多 @ref{222d,,__setattr__()} 的實作會呼叫 @code{object.__setattr__()} 以設定 self 的屬性，而不會導致無限遞迴。

@example
class X:
    def __setattr__(self, name, value):
        # 自訂邏輯放在這裡...
        object.__setattr__(self, name, value)
@end example

Alternatively, it is possible to set attributes by inserting
entries into @ref{776,,self.__dict__} directly.

@node How do I call a method defined in a base class from a derived class that extends it?,我可以如何組織我的程式碼以使得更改基底類別變的更容易？,什麼是委派 delegation ？,物件
@anchor{faq/programming how-do-i-call-a-method-defined-in-a-base-class-from-a-derived-class-that-extends-it}@anchor{566d}
@subsubsection How do I call a method defined in a base class from a derived class that extends it?


使用內建的 @ref{1a6,,super()} 函式：

@example
class Derived(Base):
    def meth(self):
        super().meth()  # 呼叫 Base.meth
@end example

In the example, @ref{1a6,,super()} will automatically determine the instance from
which it was called (the @code{self} value), look up the @ref{248c,,method resolution order} (MRO) with @code{type(self).__mro__}, and return the next in line after
@code{Derived} in the MRO: @code{Base}.

@node 我可以如何組織我的程式碼以使得更改基底類別變的更容易？,如何建立靜態類別資料和靜態類別方法？,How do I call a method defined in a base class from a derived class that extends it?,物件
@anchor{faq/programming how-can-i-organize-my-code-to-make-it-easier-to-change-the-base-class}@anchor{566e}
@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 (e.g. depending on availability
of resources) which base class to use.  Example:

@example
class Base:
    ...

BaseAlias = Base

class Derived(BaseAlias):
    ...
@end example

@node 如何建立靜態類別資料和靜態類別方法？,如何在 Python 中多載 overload 建構函式（或方法）？,我可以如何組織我的程式碼以使得更改基底類別變的更容易？,物件
@anchor{faq/programming how-do-i-create-static-class-data-and-static-class-methods}@anchor{566f}
@subsubsection 如何建立靜態類別資料和靜態類別方法？


Python 支援靜態資料和靜態方法（在 C++ 或 Java 的意義上）。

對於靜態資料，只需定義一個類別屬性即可。要為屬性分配新值，你必須在分配中顯式使用類別名稱：

@example
class C:
    count = 0   # C.__init__ 被呼叫的次數

    def __init__(self):
        C.count = C.count + 1

    def getcount(self):
        return C.count  # 或回傳 self.count
@end example

@code{c.count} 還指代任何 @code{c} 的 @code{C.count} 使得 @code{isinstance(c, C)} 成立，除非被 @code{c} 本身或某些人覆蓋從 @code{c.__class__} 回到 @code{C} 的基底類別搜尋路徑上的類別。

Caution: within a method of C, an assignment like @code{self.count = 42} creates a
new and unrelated instance named "count" in @code{self}'s own dict.  Rebinding of a
class-static data name must always specify the class whether inside a method or
not:

@example
C.count = 314
@end example

靜態方法是可能的：

@example
class C:
    @@staticmethod
    def static(arg1, arg2, arg3):
        # 沒有 'self' 參數！
        ...
@end example

However, a far more straightforward way to get the effect of a static method is
via a simple module-level function:

@example
def getcount():
    return C.count
@end example

If your code is structured so as to define one class (or tightly related class
hierarchy) per module, this supplies the desired encapsulation.

@node 如何在 Python 中多載 overload 建構函式（或方法）？,我嘗試使用 __spam，但收到有關 _SomeClassName__spam 的錯誤。,如何建立靜態類別資料和靜態類別方法？,物件
@anchor{faq/programming how-can-i-overload-constructors-or-methods-in-python}@anchor{5670}
@subsubsection 如何在 Python 中多載 (overload) 建構函式（或方法）？


這個答案實際上適用於所有方法，但這個問題通常會先出現在建構函式的情境中。

在 C++ 中你會寫成

@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

這並不完全等價，但在實際情況中已夠接近。

你也可以嘗試長度可變的引數串列，例如：

@example
def __init__(self, *args):
    ...
@end example

相同的手段適用於所有方法的定義。

@node 我嘗試使用 __spam，但收到有關 _SomeClassName__spam 的錯誤。,我的類別定義了 __del__ 但是當我刪除物件時它沒有被呼叫。,如何在 Python 中多載 overload 建構函式（或方法）？,物件
@anchor{faq/programming i-try-to-use-spam-and-i-get-an-error-about-someclassname-spam}@anchor{5671}
@subsubsection 我嘗試使用 __spam，但收到有關 _SomeClassName__spam 的錯誤。


帶有雙前導底線的變數名會被「破壞 (mangled)」以做為提供定義類別私有變數的一個簡單但有效的方法。@code{__spam} 形式的任何識別字（至少兩個前導底線，最多一個尾隨底線）在文字上會被替換為 @code{_classname__spam}，其中 @code{classname} 是目前類別之所有前導底線被去除的名稱。

The identifier can be used unchanged within the class, but to access it outside
the class, the mangled name must be used:

@example
class A:
    def __one(self):
        return 1
    def two(self):
        return 2 * self.__one()

class B(A):
    def three(self):
        return 3 * self._A__one()

four = 4 * A()._A__one()
@end example

In particular, this does not guarantee privacy since an outside user can still
deliberately access the private attribute; many Python programmers never bother
to use private variable names at all.


@subsubheading 也參考


The @ref{1f6a,,private name mangling specifications}
for details and special cases.


@node 我的類別定義了 __del__ 但是當我刪除物件時它沒有被呼叫。,我該如何取得給定類別的所有實例的串列？,我嘗試使用 __spam，但收到有關 _SomeClassName__spam 的錯誤。,物件
@anchor{faq/programming my-class-defines-del-but-it-is-not-called-when-i-delete-the-object}@anchor{5672}
@subsubsection 我的類別定義了 __del__ 但是當我刪除物件時它沒有被呼叫。


這有幾個可能的原因。

@ref{1a62,,del} 陳述式不一定會呼叫 @ref{11f8,,__del__()} -- 它只是減少物件的參照計數，如果達到零則呼叫 @code{__del__()}。

If your data structures contain circular links (e.g. a tree where each child has
a parent reference and each parent has a list of children) the reference counts
will never go back to zero.  Once in a while Python runs an algorithm to detect
such cycles, but the garbage collector might run some time after the last
reference to your data structure vanishes, so your @code{__del__()} method may be
called at an inconvenient and random time. This is inconvenient if you're trying
to reproduce a problem. Worse, the order in which object's @code{__del__()}
methods are executed is arbitrary.  You can run @ref{1b3,,gc.collect()} to force a
collection, but there `are' pathological cases where objects will never be
collected.

Despite the cycle collector, it's still a good idea to define an explicit
@code{close()} method on objects to be called whenever you're done with them.  The
@code{close()} method can then remove attributes that refer to subobjects.  Don't
call @code{__del__()} directly -- @code{__del__()} should call @code{close()} and
@code{close()} should make sure that it can be called more than once for the same
object.

Another way to avoid cyclical references is to use the @ref{11a,,weakref} module,
which allows you to point to objects without incrementing their reference count.
Tree data structures, for instance, should use weak references for their parent
and sibling references (if they need them!).

@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{b2a,,sys.stderr}。

@node 我該如何取得給定類別的所有實例的串列？,為什麼 id 的結果看起來不唯一？,我的類別定義了 __del__ 但是當我刪除物件時它沒有被呼叫。,物件
@anchor{faq/programming how-do-i-get-a-list-of-all-instances-of-a-given-class}@anchor{5673}
@subsubsection 我該如何取得給定類別的所有實例的串列？


Python 不會追蹤類別（或內建型別）的所有實例。你可以將類別的建構函式進行改寫，以透過保留對每個實例之弱參照串列來追蹤所有實例。

@node 為什麼 id 的結果看起來不唯一？,我什麼時候可以依靠 is 運算子進行識別性測試？,我該如何取得給定類別的所有實例的串列？,物件
@anchor{faq/programming why-does-the-result-of-id-appear-to-be-not-unique}@anchor{5674}
@subsubsection 為什麼 @code{id()} 的結果看起來不唯一？


The @ref{161a,,id()} builtin returns an integer that is guaranteed to be unique during
the lifetime of the object.  Since in CPython, this is the object's memory
address, it happens frequently that after an object is deleted from memory, the
next freshly created object is allocated at the same position in memory.  This
is illustrated by this example:

@example
>>> id(1000)
13901272
>>> id(2000)
13901272
@end example

The two ids belong to different integer objects that are created before, and
deleted immediately after execution of the @code{id()} call.  To be sure that
objects whose id you want to examine are still alive, create another reference
to the object:

@example
>>> a = 1000; b = 2000
>>> id(a)
13901272
>>> id(b)
13891296
@end example

@node 我什麼時候可以依靠 is 運算子進行識別性測試？,子類別如何控制不可變實例中儲存的資料？,為什麼 id 的結果看起來不唯一？,物件
@anchor{faq/programming when-can-i-rely-on-identity-tests-with-the-is-operator}@anchor{5675}
@subsubsection 我什麼時候可以依靠 `is' 運算子進行識別性測試？


@code{is} 運算子測試物件識別性。測試 @code{a is b} 等同於 @code{id(a) == id(b)} 。

識別性測試最重要的屬性是物件始終與自身相同， @code{a is a} 總是回傳 @code{True} 。識別性測試通常比相等性測試更快。與相等性測試不同，識別性測試保證回傳布林值 @code{True} 或 @code{False} 。

然而，`只有'當物件識別性得到保證時，識別性測試才能代替相等性測試。一般來說，保證識別性的情況有以下三種：


@enumerate 

@item 
Assignments create new names but do not change object identity.  After the
assignment @code{new = old}, it is guaranteed that @code{new is old}.

@item 
Putting an object in a container that stores object references does not
change object identity.  After the list assignment @code{s[0] = x}, it is
guaranteed that @code{s[0] is x}.

@item 
If an object is a singleton, it means that only one instance of that object
can exist.  After the assignments @code{a = None} and @code{b = None}, it is
guaranteed that @code{a is b} because @code{None} is a singleton.
@end enumerate

在大多數其他情況下，識別性測試是不可取的，相等性測試是首選。特別是，識別性測試不應用於檢查常數，例如不能保證是單例的 @ref{19b,,int} 和 @ref{169,,str}：

@example
>>> a = 1000
>>> b = 500
>>> c = b + 500
>>> a is c
False

>>> a = 'Python'
>>> b = 'Py'
>>> c = b + 'thon'
>>> a is c
False
@end example

同樣地，可變容器的新實例永遠不會相同：

@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} 的首選方法。這在程式碼中讀起來像簡單的英語，並避免與其他可能具有評估為 false 的布林值的物件混淆。

@item 
Detecting optional arguments can be tricky when @code{None} is a valid input
value.  In those situations, you can create a singleton sentinel object
guaranteed to be distinct from other objects.  For example, here is how
to implement a method that behaves like @ref{5de,,dict.pop()}:

@example
_sentinel = object()

def pop(self, key, default=_sentinel):
    if key in self:
        value = self[key]
        del self[key]
        return value
    if default is _sentinel:
        raise KeyError(key)
    return default
@end example

@item 
容器實作有時需要透過識別性測試來增強相等性測試。這可以防止程式碼被諸如 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{5676}
@subsubsection 子類別如何控制不可變實例中儲存的資料？


When subclassing an immutable type, override the @ref{799,,__new__()} method
instead of the @ref{8b7,,__init__()} method.  The latter only runs `after' an
instance is created, which is too late to alter data in an immutable
instance.

所有這些不可變類別都具有與其父類別不同的簽名：

@example
from datetime import date

class FirstOfMonthDate(date):
    "總是選擇每個月的第一天"
    def __new__(cls, year, month, day):
        return super().__new__(cls, year, month, 1)

class NamedInt(int):
    "允許一些數字的文字名稱"
    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):
    "將 str 轉換成適合作為 URL 路徑的名稱"
    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{2a61}@anchor{faq/programming how-do-i-cache-method-calls}@anchor{5677}
@subsubsection 如何快取方法呼叫？


The two principal tools for caching methods are
@ref{75c,,functools.cached_property()} and @ref{bd9,,functools.lru_cache()}.  The
former stores results at the instance level and the latter at the class
level.

The `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 advantage is that when an instance is no longer used, the cached
method result will be released right away.  The disadvantage is that if
instances accumulate, so too will the accumulated method results.  They
can grow without bound.

`lru_cache' 方法適用於具有@ref{81d,,可雜湊}引數的方法。除非特別努力傳遞弱參照，否則它會建立對實例的參照。

The advantage of the least recently used algorithm is that the cache is
bounded by the specified `maxsize'.  The disadvantage is that instances
are kept alive until they age out of the cache or until the cache is
cleared.

這個例子展示了各種技術：

@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 `cached_property' approach
can't be made to work because it cannot detect changes to the
attributes.

To make the `lru_cache' approach work when the `station_id' is mutable,
the class needs to define the @ref{ce9,,__eq__()} and @ref{cea,,__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 模組<6>,,物件,程式開發常見問答集
@anchor{faq/programming modules}@anchor{5678}
@subsection 模組


@menu
* 如何建立 .pyc 檔案？: 如何建立 pyc 檔案？. 
* 如何找到目前模組名稱？:: 
* 要怎樣才能擁有相互引入的模組？:: 
* __import__('x.y.z') 回傳 <module 'x'>，那我怎麼得到 z？: __import__ 'x y z' 回傳 <module 'x'>，那我怎麼得到 z？. 
* 當我編輯需要引入的模組並重新引入它時，更動沒有反應出來。為什麼會這樣？:: 

@end menu

@node 如何建立 pyc 檔案？,如何找到目前模組名稱？,,模組<6>
@anchor{faq/programming how-do-i-create-a-pyc-file}@anchor{5679}
@subsubsection 如何建立 .pyc 檔案？


When a module is imported for the first time (or when the source file has
changed since the current compiled file was created) a @code{.pyc} file containing
the compiled code should be created in a @code{__pycache__} subdirectory of the
directory containing the @code{.py} file.  The @code{.pyc} file will have a
filename that starts with the same name as the @code{.py} file, and ends with
@code{.pyc}, with a middle component that depends on the particular @code{python}
binary that created it.  (See 
@geindex Python Enhancement Proposals; PEP 3147
PEP 3147@footnote{https://peps.python.org/pep-3147/} for details.)

One reason that a @code{.pyc} file may not be created is a permissions problem
with the directory containing the source file, meaning that the @code{__pycache__}
subdirectory cannot be created. This can happen, for example, if you develop as
one user but run as another, such as if you are testing with a web server.

Unless the 
@geindex PYTHONDONTWRITEBYTECODE
@geindex 環境變數; PYTHONDONTWRITEBYTECODE
@ref{15c5,,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, etc...) 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{foo} 建立一個 @code{.pyc} 檔案 —— 也就是說，要為一個未引入的模組建立一個 @code{.pyc} 檔案 —— 你可以使用 @ref{b8,,py_compile} 和 @ref{21,,compileall} 模組。

@ref{b8,,py_compile} 模組允許手動編譯任何模組。其中一種方法是在該模組中以交互方式使用 @code{compile()} 函式：

@example
>>> import py_compile
>>> py_compile.compile('foo.py')
@end example

這會將 @code{.pyc} 寫入與 @code{foo.py} 相同位置的 @code{__pycache__} 子目錄（或者你可以使用可選參數 @code{cfile} 覆蓋它）。

You can also automatically compile all files in a directory or directories using
the @ref{21,,compileall} module.  You can do it from the shell prompt by running
@code{compileall.py} and providing the path of a directory containing Python files
to compile:

@example
python -m compileall .
@end example

@node 如何找到目前模組名稱？,要怎樣才能擁有相互引入的模組？,如何建立 pyc 檔案？,模組<6>
@anchor{faq/programming how-do-i-find-the-current-module-name}@anchor{567a}
@subsubsection 如何找到目前模組名稱？


A module can find out its own module name by looking at the predefined global
variable @code{__name__}.  If this has the value @code{'__main__'}, the program is
running as a script.  Many modules that are usually used by importing them also
provide a command-line interface or a self-test, and only execute this code
after checking @code{__name__}:

@example
def main():
    print('Running test...')
    ...

if __name__ == '__main__':
    main()
@end example

@node 要怎樣才能擁有相互引入的模組？,__import__ 'x y z' 回傳 <module 'x'>，那我怎麼得到 z？,如何找到目前模組名稱？,模組<6>
@anchor{faq/programming how-can-i-have-modules-that-mutually-import-each-other}@anchor{567b}
@subsubsection 要怎樣才能擁有相互引入的模組？


假設你有以下模組：

@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 
主要引入 @code{foo}

@item 
建立了 @code{foo} 的空全域變數

@item 
@code{foo} 被編譯並開始執行

@item 
@code{foo} 引入 @code{bar}

@item 
建立了 @code{bar} 的空全域變數

@item 
@code{bar} 已被編譯並開始執行

@item 
@code{bar} 引入 @code{foo}（這是一個空操作，因為已經有一個名為 @code{foo} 的模組）

@item 
引入機制嘗試從 @code{foo} 全域變數中讀取 @code{foo_var}，以設定 @code{bar.foo_var = foo.foo_var}
@end itemize

最後一步失敗了，因為 Python 還沒有完成對 @code{foo} 的直譯，而 @code{foo} 的全域符號字典仍然是空的。

The same thing happens when you use @code{import foo}, and then try to access
@code{foo.foo_var} in global code.

此問題有（至少）三種可能的解決方法。

Guido van Rossum recommends avoiding all uses of @code{from <module> import ...},
and placing all code inside functions.  Initializations of global variables and
class variables should use constants or built-in functions only.  This means
everything from an imported module is referenced as @code{<module>.<name>}.

Jim Roskind 建議在每個模組中按以下順序執行各個步驟：


@itemize *

@item 
exports (globals, functions, and classes that don't need imported base
classes)

@item 
@code{import} 陳述式

@item 
活躍程式碼（包括從引入值初始化的全域變數）。
@end itemize

Van Rossum 不太喜歡這種方法，因為引入出現在一個奇怪的地方，但它確實有效。

Matthias Urlichs 建議重組 (restructuring) 你的程式碼，以便打從一開始就不需要遞迴引入。

這些方案並不衝突。

@node __import__ 'x y z' 回傳 <module 'x'>，那我怎麼得到 z？,當我編輯需要引入的模組並重新引入它時，更動沒有反應出來。為什麼會這樣？,要怎樣才能擁有相互引入的模組？,模組<6>
@anchor{faq/programming import-x-y-z-returns-module-x-how-do-i-get-z}@anchor{567c}
@subsubsection __import__('x.y.z') 回傳 <module 'x'>，那我怎麼得到 z？


Consider using the convenience function @ref{735,,import_module()} from
@ref{7b,,importlib} instead:

@example
z = importlib.import_module('x.y.z')
@end example

@node 當我編輯需要引入的模組並重新引入它時，更動沒有反應出來。為什麼會這樣？,,__import__ 'x y z' 回傳 <module 'x'>，那我怎麼得到 z？,模組<6>
@anchor{faq/programming when-i-edit-an-imported-module-and-reimport-it-the-changes-don-t-show-up-why-does-this-happen}@anchor{567d}
@subsubsection 當我編輯需要引入的模組並重新引入它時，更動沒有反應出來。為什麼會這樣？


For reasons of efficiency as well as consistency, Python only reads the module
file on the first time a module is imported.  If it didn't, in a program
consisting of many modules where each one imports the same basic module, the
basic module would be parsed and re-parsed many times.  To force re-reading of a
changed module, do this:

@example
import importlib
import modname
importlib.reload(modname)
@end example

警告：此技術並非 100% 萬無一失。尤其是包含像這樣陳述式的模組：

@example
from modname import some_objects
@end example

will continue to work with the old version of the imported objects.  If the
module contains class definitions, existing class instances will `not' be
updated to use the new class definition.  This can result in the following
paradoxical behaviour:

@example
>>> import importlib
>>> import cls
>>> c = cls.C()                # 建立一個 C 的實例
>>> importlib.reload(cls)
<module 'cls' from 'cls.py'>
>>> isinstance(c, cls.C)       # isinstance 為 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 設計和歷史常見問答集,函式庫和擴充功能的常見問題,程式開發常見問答集,Python 常見問題
@anchor{faq/design doc}@anchor{567e}@anchor{faq/design design-and-history-faq}@anchor{567f}@anchor{faq/design translation-repo}@anchor{5680}
@section 設計和歷史常見問答集



@menu
* 為什麼 Python 使用縮排將陳述式進行分組？:: 
* 為什麼我會從簡單的數學運算得到奇怪的結果？:: 
* 為何浮點數運算如此不精確？:: 
* 為什麼 Python 字串不可變動？:: 
* 為何「self」在方法 (method) 定義和呼叫時一定要明確使用？: 為何「self」在方法 method 定義和呼叫時一定要明確使用？. 
* 為何我不能在運算式 (expression) 中使用指派運算？: 為何我不能在運算式 expression 中使用指派運算？. 
* 為何 Python 對於一些功能實作使用方法（像是 list.index()），另一些使用函式（像是 len(list)）？: 為何 Python 對於一些功能實作使用方法（像是 list index ），另一些使用函式（像是 len list ）？. 
* 為何 join() 是字串方法而非串列 (list) 或元組 (tuple) 方法？: 為何 join 是字串方法而非串列 list 或元組 tuple 方法？. 
* 例外處理有多快？:: 
* 為什麼 Python 內沒有 switch 或 case 陳述式？:: 
* 為何不能在直譯器上模擬執行緒，而要使用作業系統的特定實作方式？:: 
* 為何 lambda 運算式不能包含陳述式？:: 
* Python 可以被編譯成機器語言、C 語言或其他種語言嗎？:: 
* Python 如何管理記憶體？:: 
* 為何 CPython 不使用更多傳統的垃圾回收機制？:: 
* 當 CPython 結束時，為何所有的記憶體不會被釋放？:: 
* 為何要把元組 (tuple) 和串列 (list) 分成兩個資料型態？: 為何要把元組 tuple 和串列 list 分成兩個資料型態？. 
* 串列 (list) 在 CPython 中是怎麼實作的？: 串列 list 在 CPython 中是怎麼實作的？. 
* 字典 (dictionaries) 在 CPython 中是怎麼實作的？: 字典 dictionaries 在 CPython 中是怎麼實作的？. 
* 為何字典的鍵一定是不可變的？:: 
* 為何 list.sort() 不是回傳排序過的串列？: 為何 list sort 不是回傳排序過的串列？. 
* 如何在 Python 中指定和強制使用一個介面規範 (interface spec)？: 如何在 Python 中指定和強制使用一個介面規範 interface spec ？. 
* 為何沒有 goto 語法？:: 
* 為何純字串 (r-string) 不能以反斜線結尾？: 為何純字串 r-string 不能以反斜線結尾？. 
* 為何 Python 沒有屬性賦值的 with 陳述式？:: 
* 為何產生器 (generator) 不支援 with 陳述式？: 為何產生器 generator 不支援 with 陳述式？. 
* 為何 if、while、def、class 陳述式裡需要冒號？:: 
* 為何 Python 允許在串列和元組末端加上逗號？:: 

@end menu

@node 為什麼 Python 使用縮排將陳述式進行分組？,為什麼我會從簡單的數學運算得到奇怪的結果？,,設計和歷史常見問答集
@anchor{faq/design why-does-python-use-indentation-for-grouping-of-statements}@anchor{5681}
@subsection 為什麼 Python 使用縮排將陳述式進行分組？


Guido van Rossum 相信使用縮排來分組超級優雅，並且對提高一般 Python 程式的清晰度有許多貢獻。許多人在學習一段時間之後就愛上了這個功能。

因為沒有開始/結束括號，因此剖析器和人類讀者感知到的分組就不存在分歧。偶爾 C 語言的程式設計師會遇到這樣的程式碼片段：

@example
if (x <= y)
        x++;
        y--;
z++;
@end example

如果條件為真，只有 @code{x++} 陳述式會被執行，但縮排會讓很多人對他有不同的理解。即使是資深的 C 語言開發者有時也會盯著他許久，思考為何即便 @code{x > y}，但 @code{y} 還是減少了。

因為沒有開頭與結尾的括號，Python 比起其他語言會更不容易遇到程式碼風格的衝突。在 C 語言中，有多種不同的方法來放置花括號。在習慣讀寫特定風格後，去讀（或是必須去寫）另一種風格會覺得不太舒服。

很多程式碼風格會把 begin/end 獨立放在一行。這會讓程式碼很長且浪費珍貴的螢幕空間，要概覽程式時也變得較為困難。理想上來說，一個函式應該要佔一個螢幕（大概 20 至 30 行）。20 行的 Python 程式碼比起 20 行的 C 程式碼可以做更多事。雖然沒有開頭與結尾的括號並非單一原因（沒有變數宣告及高階的資料型別同樣有關），但縮排式的語法確實給了幫助。

@node 為什麼我會從簡單的數學運算得到奇怪的結果？,為何浮點數運算如此不精確？,為什麼 Python 使用縮排將陳述式進行分組？,設計和歷史常見問答集
@anchor{faq/design why-am-i-getting-strange-results-with-simple-arithmetic-operations}@anchor{5682}
@subsection 為什麼我會從簡單的數學運算得到奇怪的結果？


請見下一個問題。

@node 為何浮點數運算如此不精確？,為什麼 Python 字串不可變動？,為什麼我會從簡單的數學運算得到奇怪的結果？,設計和歷史常見問答集
@anchor{faq/design why-are-floating-point-calculations-so-inaccurate}@anchor{5683}
@subsection 為何浮點數運算如此不精確？


使用者時常對這樣的結果感到驚訝：

@example
>>> 1.2 - 1.0
0.19999999999999996
@end example

然後認為這是 Python 的 bug，但這並不是。這跟 Python 幾乎沒有關係，而是和底層如何處理浮點數有關係。

CPython 的 @ref{196,,float} 型別使用了 C 的 @code{double} 型別來儲存。一個 @ref{196,,float} 物件的值會以固定的精度（通常為 53 位元）存為二進制浮點數，Python 使用 C 來運算浮點數，而他的結果會依處理器中的硬體實作方式來決定。這表示就浮點數運算來說，Python 和 C、Java 等很多受歡迎的語言有一樣的行為。

很多數字可以簡單地寫成十進位表示，但卻無法簡單地以二進制浮點數表示。比方說，在以下程式碼執行後：

@example
>>> x = 1.2
@end example

@code{x} 裡的值是一個（很接近）1.2 的估計值，但並非精確地等於 1.2。以一般的電腦來說，他實際儲存的值是：

@example
1.0011001100110011001100110011001100110011001100110011 (binary)
@end example

而這個值正是：

@example
1.1999999999999999555910790149937383830547332763671875 (decimal)
@end example

53 位元的精度讓 Python 可以有 15 至 16 小數位的準確度。

要更完全的解釋可以查閱在 Python 教學的@ref{1fc7,,浮點運算}一章。

@node 為什麼 Python 字串不可變動？,為何「self」在方法 method 定義和呼叫時一定要明確使用？,為何浮點數運算如此不精確？,設計和歷史常見問答集
@anchor{faq/design why-are-python-strings-immutable}@anchor{5684}
@subsection 為什麼 Python 字串不可變動？


有許多優點。

其一是效能：知道字串不可變動後，我們就可以在創造他的時候就分配好空間，而後他的儲存空間需求就是固定不變的。這也是元組 (tuple) 和串列 (list) 相異的其中一個原因。

另一個優點是在 Python 中，字串和數字一樣「基本」。沒有任何行為會把 8 這個數值改成其他數值；同理，在 Python 中也沒有任何行為會修改字串「eight」。

@node 為何「self」在方法 method 定義和呼叫時一定要明確使用？,為何我不能在運算式 expression 中使用指派運算？,為什麼 Python 字串不可變動？,設計和歷史常見問答集
@anchor{faq/design why-must-self-be-used-explicitly-in-method-definitions-and-calls}@anchor{5685}@anchor{faq/design why-self}@anchor{566a}
@subsection 為何「self」在方法 (method) 定義和呼叫時一定要明確使用？


此構想從 Modula-3 而來。因為許多原因，他可以說是非常實用。

第一，這樣可以更明顯表現出你在用方法 (method) 或是實例 (instance) 的屬性，而非一個區域變數。即使不知道類別 (class) 的定義，當看到 @code{self.x} 或 @code{self.meth()}，就會很清楚地知道是正在使用實例的變數或是方法。在 C++ 裡，你可以藉由沒有區域變數宣告來判斷這件事 ── 但在 Python 裡沒有區域變數宣告，所以你必須去看類別的定義來確定。有些 C++ 和 Java 的程式碼規格要求要在實例屬性的名稱加上前綴 @code{m_}，所以這種明確性在那些語言也是很好用的。

第二，當你想明確地使用或呼叫在某個類別裡的方法的時候，你不需要特殊的語法。在 C++ 裡，如果你想用一個在繼承類別時被覆寫的基底類別方法，必須要用 @code{::} 運算子 -- 但在 Python 裡，你可以直接寫成 @code{baseclass.methodname(self, <argument list>)}。這在 @ref{8b7,,__init__()} 方法很好用，特別是在一個繼承的類別要擴充基底類別的方法而要呼叫他時。

最後，他解決了關於實例變數指派的語法問題：因為區域變數在 Python 是（定義為）在函式內被指派值的變數（且沒有被明確宣告成全域），所以會需要一個方法來告訴直譯器這個指派運算是針對實例變數，而非針對區域變數，這在語法層面處理較好（為了效率）。C++ 用宣告解決了這件事，但 Python 沒有，而為了這個原因而引入變數宣告機制又略嫌浪費。但使用明確的 @code{self.var} 就可以把這個問題圓滿解決。同理，在用實例變數的時候必須寫成 @code{self.var} 即代表對於在方法中不特定的名稱不需要去看實例的內容。換句話說，區域變數和實例變數存在於兩個不同的命名空間 (namespace)，而你需要告訴 Python 要使用哪一個。

@node 為何我不能在運算式 expression 中使用指派運算？,為何 Python 對於一些功能實作使用方法（像是 list index ），另一些使用函式（像是 len list ）？,為何「self」在方法 method 定義和呼叫時一定要明確使用？,設計和歷史常見問答集
@anchor{faq/design id2}@anchor{5686}@anchor{faq/design why-can-t-i-use-an-assignment-in-an-expression}@anchor{1eff}
@subsection 為何我不能在運算式 (expression) 中使用指派運算？


從 Python 3.8 開始，你可以這麼做了！

指派運算式使用海象運算子 @code{:=} 來在運算式中指派變數值：

@example
while chunk := fp.read(200):
   print(chunk)
@end example

更多資訊請見 
@geindex Python Enhancement Proposals; PEP 572
PEP 572@footnote{https://peps.python.org/pep-0572/}。

@node 為何 Python 對於一些功能實作使用方法（像是 list index ），另一些使用函式（像是 len list ）？,為何 join 是字串方法而非串列 list 或元組 tuple 方法？,為何我不能在運算式 expression 中使用指派運算？,設計和歷史常見問答集
@anchor{faq/design why-does-python-use-methods-for-some-functionality-e-g-list-index-but-functions-for-other-e-g-len-list}@anchor{5687}
@subsection 為何 Python 對於一些功能實作使用方法（像是 list.index()），另一些使用函式（像是 len(list)）？


如 Guido 所說：

@quotation

（一） 對一些運算來說，前綴寫法看起來會比後綴寫法好 ── 前綴（和中綴！）運算在數學上有更久遠的傳統，這些符號在視覺上幫助數學家們更容易思考問題。想想把 x*(a+b) 這種式子展開成 x*a + x*b 的簡單，再比較一下古老的圈圈符號記法的笨拙就知道了。

（二） 當我看到一段程式碼寫著 len(x)，我`知道'他要找某個東西的長度。這告訴了我兩件事：結果是一個整數、參數是某種容器。相對地，當我看到 x.len()，我必須先知道 x 是某種容器，並實作了一個介面或是繼承了一個有標準 len() 的類別。遇到一個沒有實作對映 (mapping) 的類別卻有 get() 或 keys() 方法，或是不是檔案但卻有 write() 方法時，我們偶爾會覺得困惑。


@center --- @indicateurl{https://mail.python.org/pipermail/python-3000/2006-November/004643.html}

@end quotation

@node 為何 join 是字串方法而非串列 list 或元組 tuple 方法？,例外處理有多快？,為何 Python 對於一些功能實作使用方法（像是 list index ），另一些使用函式（像是 len list ）？,設計和歷史常見問答集
@anchor{faq/design why-is-join-a-string-method-instead-of-a-list-or-tuple-method}@anchor{5688}
@subsection 為何 join() 是字串方法而非串列 (list) 或元組 (tuple) 方法？


自 Python 1.6 之後，字串變得很像其他標準的型別，也在此時，一些可以和字串模組的函式有相同功能的方法也被加入。大多數的新方法都被廣泛接受，但有一個方法似乎讓一些程式人員不舒服：

@example
", ".join(['1', '2', '4', '8', '16'])
@end example

結果是：

@example
"1, 2, 4, 8, 16"
@end example

通常有兩個反對這個用法的論點。

第一項這麼說：「用字串文本 (string literal) （字串常數）看起來真的很醜」，也許真的如此，但字串文本就只是一個固定值。如果方法可以用在值為字串的變數上，那沒道理字串文本不能被使用。

第二個反對意見通常是：「我是在叫一個序列把它的成員用一個字串常數連接起來」。但很遺憾地，你並不是在這樣做。因為某種原因，把 @ref{10a5,,split()} 當成字串方法比較簡單，因為這樣我們可以輕易地看到：

@example
"1, 2, 4, 8, 16".split(", ")
@end example

這是在叫一個字串文本回傳由指定的分隔符號（或是預設為空白）分出的子字串的指令。

@ref{24b9,,join()} 是一個字串方法，因為在用他的時候，你是告訴分隔字串去走遍整個字串序列，並將自己插入到相鄰的兩項之間。這個方法的參數可以是任何符合序列規則的物件，包括自定義的新類別。在 bytes 和 bytearray 物件也有類似的方法可用。

@node 例外處理有多快？,為什麼 Python 內沒有 switch 或 case 陳述式？,為何 join 是字串方法而非串列 list 或元組 tuple 方法？,設計和歷史常見問答集
@anchor{faq/design how-fast-are-exceptions}@anchor{5689}
@subsection 例外處理有多快？


如果沒有例外被丟出，一個 @ref{8f0,,try}/@ref{1ab,,except} 區塊是非常有效率的。事實上，抓捕例外要付出昂貴的代價。在 Python 2.0 以前，這樣使用是相當常見的：

@example
try:
    value = mydict[key]
except KeyError:
    mydict[key] = getvalue(key)
    value = mydict[key]
@end example

這只有在你預料這個字典大多數時候都有鍵的時候才合理。如果並非如此，你應該寫成：

@example
if key in mydict:
    value = mydict[key]
else:
    value = mydict[key] = getvalue(key)
@end example

單就這個情況來說，你也可以用 @code{value = dict.setdefault(key, getvalue(key))}，不過只有在 @code{getvalue()} 代價不大的時候才能用，畢竟他每次都會被執行。

@node 為什麼 Python 內沒有 switch 或 case 陳述式？,為何不能在直譯器上模擬執行緒，而要使用作業系統的特定實作方式？,例外處理有多快？,設計和歷史常見問答集
@anchor{faq/design why-isn-t-there-a-switch-or-case-statement-in-python}@anchor{568a}
@subsection 為什麼 Python 內沒有 switch 或 case 陳述式？


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

如果可能性很多，你可以用字典去對映要呼叫的函式。舉例來說：

@example
if key in mydict:
    value = mydict[key]
else:
    value = mydict[key] = getvalue(key)
@end example

對於呼叫物件裡的方法，你可以利用內建用來找尋特定方法的函式 @ref{dc5,,getattr()} 來做進一步的簡化：

@example
class MyVisitor:
    def visit_a(self):
        ...

    def dispatch(self, value):
        method_name = 'visit_' + str(value)
        method = getattr(self, method_name)
        method()
@end example

我們建議在方法名稱加上前綴，以這個例子來說是 像是 @code{visit_}。沒有前綴的話，一旦收到從不信任來源的值，攻擊者便可以隨意呼叫在你的專案內的方法。

Imitating switch with fallthrough, as with C's switch-case-default,
is possible, much harder, and less needed.

@node 為何不能在直譯器上模擬執行緒，而要使用作業系統的特定實作方式？,為何 lambda 運算式不能包含陳述式？,為什麼 Python 內沒有 switch 或 case 陳述式？,設計和歷史常見問答集
@anchor{faq/design can-t-you-emulate-threads-in-the-interpreter-instead-of-relying-on-an-os-specific-thread-implementation}@anchor{568b}
@subsection 為何不能在直譯器上模擬執行緒，而要使用作業系統的特定實作方式？


答案一：很不幸地，直譯器對每個 Python 的堆疊框 (stack frame) 會推至少一個 C 的堆疊框。同時，擴充套件可以隨時呼叫 Python，因此完整的實作必須要支援 C 的執行緒。

答案二：幸運地，無堆疊 (Stackless) Python@footnote{https://github.com/stackless-dev/stackless/wiki} 完全重新設計了直譯器迴圈，並避免了 C 堆疊。

@node 為何 lambda 運算式不能包含陳述式？,Python 可以被編譯成機器語言、C 語言或其他種語言嗎？,為何不能在直譯器上模擬執行緒，而要使用作業系統的特定實作方式？,設計和歷史常見問答集
@anchor{faq/design why-can-t-lambda-expressions-contain-statements}@anchor{568c}
@subsection 為何 lambda 運算式不能包含陳述式？


Python 的 lambda 運算式不能包含陳述式是因為 Python 的語法框架無法處理包在運算式中的陳述式。然而，在 Python 裡這並不是一個嚴重的問題。不像在其他語言中有獨立功能的 lambda，Python 的 lambda 只是一個在你懶得定義函式時可用的一個簡寫表達法。

函式已經是 Python 裡的一級物件 (first class objects)，而且可以在區域範圍內被宣告。因此唯一用 lambda 而非區域性的函式的優點就是你不需要多想一個函式名稱 — 但這樣就會是一個區域變數被指定成函式物件（和 lambda 運算式的結果同類）！

@node Python 可以被編譯成機器語言、C 語言或其他種語言嗎？,Python 如何管理記憶體？,為何 lambda 運算式不能包含陳述式？,設計和歷史常見問答集
@anchor{faq/design can-python-be-compiled-to-machine-code-c-or-some-other-language}@anchor{568d}
@subsection Python 可以被編譯成機器語言、C 語言或其他種語言嗎？


Cython@footnote{https://cython.org/} 可以編譯一個調整過有選擇性註解的 Python 版本。Nuitka@footnote{https://nuitka.net/} 是一個有潛力編譯器，可以把 Python 編譯成 C++，他的目標是支援完整的 Python 語言。

@node Python 如何管理記憶體？,為何 CPython 不使用更多傳統的垃圾回收機制？,Python 可以被編譯成機器語言、C 語言或其他種語言嗎？,設計和歷史常見問答集
@anchor{faq/design how-does-python-manage-memory}@anchor{568e}
@subsection Python 如何管理記憶體？


Python 記憶體管理的細節取決於實作。Python 的標準實作 @ref{8fd,,CPython} 使用參照計次 (reference counting) 來偵測不再被存取的物件，並用另一個機制來收集參照循環 (reference cycle)、定期執行循環偵測演算法來找不再使用的循環並刪除相關物件。 @ref{64,,gc} 模組提供了可以執行垃圾收集、抓取除錯統計數據和調整收集器參數的函式。

然而，在其他實作（像是 Jython@footnote{https://www.jython.org} 或 PyPy@footnote{https://pypy.org}）中，會使用像是成熟的垃圾收集器等不同機制。如果你的 Python 程式碼的表現取決於參照計次的實作，這個相異處會導致一些微小的移植問題。

在一些 Python 實作中，下面這段程式碼（在 CPython 可以正常運作）可能會把檔案描述子 (file descriptor) 用盡：

@example
for file in very_long_list_of_files:
    f = open(file)
    c = f.read(1)
@end example

實際上，使用 CPython 的參照計次和解構方案 (destructor scheme)，每個對 @code{f} 的新指派都會關閉前面打開的檔案。然而用傳統的垃圾回收 (GC) 的話，這些檔案物件只會在不固定且有可能很長的時間後被收集（並關閉）。

如果你希望你的程式碼在任何 Python 實作版本中都可以運作，那你應該清楚地關閉檔案或是使用 @ref{186,,with} 陳述式，如此一來，不用管記憶體管理的方法，他也會正常運作：

@example
for file in very_long_list_of_files:
    with open(file) as f:
        c = f.read(1)
@end example

@node 為何 CPython 不使用更多傳統的垃圾回收機制？,當 CPython 結束時，為何所有的記憶體不會被釋放？,Python 如何管理記憶體？,設計和歷史常見問答集
@anchor{faq/design why-doesn-t-cpython-use-a-more-traditional-garbage-collection-scheme}@anchor{568f}
@subsection 為何 CPython 不使用更多傳統的垃圾回收機制？


第一，這並不是 C 的標準功能，因此他的可攜性低。（對，我們知道 Boehm GC 函式庫。他有可相容於`大多數'平台的組合語言程式碼，但依然不是全部，而即便它大多數是通透的，也並不完全，要讓它跟 Python 相容還是需要做一些修補。）

傳統的垃圾收集 (GC) 在 Python 被嵌入其他應用程式時也成了一個問題。在獨立的 Python 程式裡當然可以把標準的 @code{malloc()} 和 @code{free()} 換成 GC 函式庫提供的其他版本；但一個嵌著 Python 的應用程式可能想用`自己'的 malloc() 和 free() 替代品，而不是用 Python 的。以現在來說，CPython 和實作 malloc() 和 free() 的程式相處融洽。

@node 當 CPython 結束時，為何所有的記憶體不會被釋放？,為何要把元組 tuple 和串列 list 分成兩個資料型態？,為何 CPython 不使用更多傳統的垃圾回收機制？,設計和歷史常見問答集
@anchor{faq/design why-isn-t-all-memory-freed-when-cpython-exits}@anchor{5690}
@subsection 當 CPython 結束時，為何所有的記憶體不會被釋放？


當離開 Python 時，從 Python 模組的全域命名空間來的物件並非總是會被釋放。在有循環引用的時候，這可能會發生。有些記憶體是被 C 函式庫取用的，他們不可能被釋放（例如：像是 Purify 之類的工具會抱怨）。然而，Python 在關閉的時候會積極清理記憶體並嘗試刪除每個物件。

如果你想要強迫 Python 在釋放記憶體時刪除特定的東西，你可以用 @ref{d,,atexit} 模組來執行會強制刪除的函式。

@node 為何要把元組 tuple 和串列 list 分成兩個資料型態？,串列 list 在 CPython 中是怎麼實作的？,當 CPython 結束時，為何所有的記憶體不會被釋放？,設計和歷史常見問答集
@anchor{faq/design why-are-there-separate-tuple-and-list-data-types}@anchor{5691}
@subsection 為何要把元組 (tuple) 和串列 (list) 分成兩個資料型態？


串列和元組在很多方面相當相似，但通常用在完全不同的地方。元組可以想成 Pascal 的 @code{record} 或是 C 的 @code{struct}，是一小群相關聯但可能是不同型別的資料集合，以一組為單位進行操作。舉例來說，一個笛卡兒坐標系可以適當地表示成一個有二或三個值的元組。

另一方面，串列更像是其他語言的陣列 (array)。他可以有不固定個同類別物件，且為逐項操作。舉例來說，@ref{12fb,,os.listdir('.')} 回傳當下目錄裡的檔案，以包含字串的串列表示。如果你新增了幾個檔案到這個目錄，一般來說操作結果的函式也會正常運作。

元組則是不可變的，代表一旦元組被建立，你就不能夠改變裡面的任何一個值。而串列可變，所以你可以改變裡面的元素。只有不可變的元素可以成為字典的鍵，所以只能把元組當成鍵，而串列則不行。

@node 串列 list 在 CPython 中是怎麼實作的？,字典 dictionaries 在 CPython 中是怎麼實作的？,為何要把元組 tuple 和串列 list 分成兩個資料型態？,設計和歷史常見問答集
@anchor{faq/design how-are-lists-implemented-in-cpython}@anchor{5692}
@subsection 串列 (list) 在 CPython 中是怎麼實作的？


CPython 的串列 (list) 事實上是可變長度的陣列 (array)，而不是像 Lisp 語言的鏈接串列 (linked list)。實作上，他是一個連續的物件參照 (reference) 陣列，並把指向此陣列的指標 (pointer) 和陣列長度存在串列的標頭結構內。

因此，用索引來找串列特定項 @code{a[i]} 的代價和串列大小或是索引值無關。

當新物件被新增或插入時，陣列會被調整大小。為了改善多次加入物件的效率，我們有用一些巧妙的方法，當陣列必須變大時，會多收集一些額外的空間，接下來幾次新增時就不需要再調整大小了。

@node 字典 dictionaries 在 CPython 中是怎麼實作的？,為何字典的鍵一定是不可變的？,串列 list 在 CPython 中是怎麼實作的？,設計和歷史常見問答集
@anchor{faq/design how-are-dictionaries-implemented-in-cpython}@anchor{5693}
@subsection 字典 (dictionaries) 在 CPython 中是怎麼實作的？


CPython 的字典是用可調整大小的雜湊表 (hash table) 實作的。比起 B 樹 (B-tree)，在搜尋（目前為止最常見的操作）方面有更好的表現，實作上也較為簡單。

字典利用內建 @ref{7fa,,hash()} 函式，對每個鍵做雜湊計算。雜湊結果依據鍵的值和個別執行緒 (processes) 的種子而有相當大的差距。例如，@code{'Python'} 的雜湊是 @code{-539294296}，而只差一個字的 @code{'python'} 則是 @code{1142331976}。雜湊結果接著被用來計算值在內部陣列儲存的位置。假設你存的鍵都有不同的雜湊值，那字典只需要常數時間 — 用大 O 表示法 (Big-O notation) 就是 `O'(1) — 來找任意一個鍵。

@node 為何字典的鍵一定是不可變的？,為何 list sort 不是回傳排序過的串列？,字典 dictionaries 在 CPython 中是怎麼實作的？,設計和歷史常見問答集
@anchor{faq/design why-must-dictionary-keys-be-immutable}@anchor{5694}
@subsection 為何字典的鍵一定是不可變的？


實作字典用的雜湊表是根據鍵的值做計算從而找到鍵的。如果鍵可變的話，他的值就可以改變，則雜湊的結果也會一起變動。但改變鍵的物件的人無從得知他被用來當成字典的鍵，所以無法修改字典的內容。然後，當你嘗試在字典中尋找這個物件時，因為雜湊值不同的緣故，你找不到他。而如果你嘗試用舊的值去尋找，也一樣找不到，因為他的雜湊結果和原先物件不同。

如果你想要用串列作為字典的索引，把他轉換成元組即可。@code{tuple(L)} 函式會建立一個和串列 @code{L} 一樣內容的元組。而元組是不可變的，所以可以用來當成字典的鍵。

也有人提出一些不能接受的方法：


@itemize -

@item 
用串列的記憶體位址（物件 id）來雜湊。這不會成功，因為你如果用同樣的值建立一個新的串列，是找不到的。舉例來說：

@example
mydict = @{[1, 2]: '12'@}
print(mydict[[1, 2]])
@end example

這將會導致 @ref{5df,,KeyError} 例外，因為 @code{[1, 2]} 的 id 在第一行和第二行是不同的。換句話說，字典的鍵應該要用 @code{==} 來做比較，而不是用 @ref{34a,,is}。

@item 
複製一個串列作為鍵。這一樣不會成功，因為串列是可變的，他可以包含自己的參照，所以複製會形成一個無窮迴圈。

@item 
允許串列作為鍵，但告訴使用者不要更動他。當你不小心忘記或是更動了這個串列，會產生一種難以追蹤的 bug。他同時也違背了一項字典的重要定則：在 @code{d.keys()} 的每個值都可以當成字典的鍵。

@item 
一旦串列被當成鍵，把他標記成只能讀取。問題是，這不只要避免最上層的物件改變值，就像用元組包含串列來做為鍵。把一個物件當成鍵，需要將從他開始可以接觸到的所有物件都標記成只能讀取 — 所以再一次，自己參照自己的物件會導致無窮迴圈。
@end itemize

如果你需要的話，這裡有個小技巧可以幫你，但請自己承擔風險：你可以把一個可變物件包裝進一個有 @ref{ce9,,__eq__()} 和 @ref{cea,,__hash__()} 方法的類別實例。只要這種包裝物件還存在於字典（或其他類似結構）中，你就必須確定在字典（或其他用雜湊為基底的結構）中他們的雜湊值會保持恆定。

@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

請注意，雜湊的計算可能變得複雜，因為有串列成員不可雜湊 (unhashable) 和算術溢位的可能性。

此外，不管物件是否在字典中，如果 @code{o1 == o2}（即 @code{o1.__eq__(o2) is True}），則 @code{hash(o1) == hash(o2)}（即 @code{o1.__hash__() == o2.__hash__()}），這個事實必須要成立。如果無法滿足這項限制，那字典和其他用雜湊為基底的結構會出現不正常的行為。

至於 @code{ListWrapper}，只要這個包裝過的物件在字典中，裡面的串列就不能改變以避免不正常的事情發生。除非你已經謹慎思考過你的需求和無法滿足條件的後果，不然請不要這麼做。請自行注意。

@node 為何 list sort 不是回傳排序過的串列？,如何在 Python 中指定和強制使用一個介面規範 interface spec ？,為何字典的鍵一定是不可變的？,設計和歷史常見問答集
@anchor{faq/design why-doesn-t-list-sort-return-the-sorted-list}@anchor{5695}
@subsection 為何 list.sort() 不是回傳排序過的串列？


在重視效能的情況下，把串列複製一份有些浪費。因此，@ref{dc3,,list.sort()} 直接在串列裡做排序。為了提醒你這件事，他不會回傳排序過的串列。這樣一來，當你需要排序過和未排序過的串列時，你就不會被誤導而不小心覆蓋掉串列。

如果你想要他回傳新的串列，那可以改用內建的 @ref{dc2,,sorted()}。他會用提供的可疊代物件 (iterable) 來排序建立新串列，並回傳之。例如，以下這個範例會說明如何有序地疊代字典的鍵：

@example
for key in sorted(mydict):
    ...  # do whatever with mydict[key]...
@end example

@node 如何在 Python 中指定和強制使用一個介面規範 interface spec ？,為何沒有 goto 語法？,為何 list sort 不是回傳排序過的串列？,設計和歷史常見問答集
@anchor{faq/design how-do-you-specify-and-enforce-an-interface-spec-in-python}@anchor{5696}
@subsection 如何在 Python 中指定和強制使用一個介面規範 (interface spec)？


像是 C++ 和 Java 等語言提供了模組的介面規範，他描述了該模組的方法和函式的原型。很多人認為這種在編譯時強制執行的介面規範在建構大型程式時十分有幫助。

Python 2.6 加入了 @ref{4,,abc} 模組，讓你可以定義抽象基底類別 (Abstract Base Class, ABC)。你可以使用 @ref{2ad,,isinstance()} 和 @ref{9bd,,issubclass()} 來確認一個實例或是類別是否實作了某個抽象基底類別。而 @ref{1f,,collections.abc} 模組定義了一系列好用的抽象基底類別，像是 @ref{2558,,Iterable}、@ref{255a,,Container} 和 @ref{12ad,,MutableMapping}。

對 Python 來說，很多介面規範的優點可以用對元件適當的測試規則來達到。

一個針對模組的好測試套件提供了迴歸測試 (regression testing)，並作為模組介面規範和一組範例。許多 Python 模組可以直接當成腳本執行，並提供簡單的「自我測試」。即便模組使用了複雜的外部介面，他依然可以用外部介面的簡單的「樁」(stub) 模擬來獨立測試。@ref{3e,,doctest} 和 @ref{10c,,unittest} 模組或第三方的測試框架可以用來建構詳盡徹底的測試套件來測試模組裡的每一行程式碼。

就像介面規範一樣，一個適當的測試規則在建造大型又複雜的 Python 應用程式時可以幫上忙。事實上，他可能可以有更好的表現，因為介面規範無法測試程式的特定屬性。舉例來說，@ref{8d4,,list.append()} 方法應該要在某個內部的串列最後面加上新的元素，而介面規範沒辦法測試你的 @ref{8d4,,list.append()} 是不是真的有正確的實作，但這在測試套件裡是件很簡單的事。

撰寫測試套件相當有幫助，而你會像要把程式碼設計成好測試的樣子。測試驅動開發 (test-driven development) 是一個越來越受歡迎的設計方法，他要求先完成部分的測試套件，再去撰寫真的要用的程式碼。當然 Python 也允許你草率地不寫任何測試。

@node 為何沒有 goto 語法？,為何純字串 r-string 不能以反斜線結尾？,如何在 Python 中指定和強制使用一個介面規範 interface spec ？,設計和歷史常見問答集
@anchor{faq/design why-is-there-no-goto}@anchor{5697}
@subsection 為何沒有 goto 語法？


在 1970 年代，人們了解到沒有限制的 goto 會導致混亂、難以理解和修改的「義大利麵」程式碼 ("spaghetti" code)。在高階語言裡，這也是不需要的，因為有方法可以做邏輯分支（以 Python 來說，用 @ref{181,,if} 陳述式和 @ref{34b,,or}、@ref{347,,and} 及 @ref{181,,if}/@ref{17c,,else} 運算式）和迴圈（用 @ref{18d6,,while} 和 @ref{348,,for} 陳述式，可能會有 @ref{180,,continue} 和 @ref{17f,,break}）。

我們也可以用例外來做「結構化的 goto」，這甚至可以跨函式呼叫。很多人覺得例外可以方便地模擬在 C、Fortran 和其他語言裡各種合理使用的 @code{go} 和 @code{goto}。例如：

@example
class label(Exception): pass  # declare a label

try:
    ...
    if condition: raise label()  # goto label
    ...
except label:  # where to goto
    pass
...
@end example

這依然不能讓你跳進迴圈內，這通常被認為是對 @code{goto} 的濫用。請小心使用。

@node 為何純字串 r-string 不能以反斜線結尾？,為何 Python 沒有屬性賦值的 with 陳述式？,為何沒有 goto 語法？,設計和歷史常見問答集
@anchor{faq/design why-can-t-raw-strings-r-strings-end-with-a-backslash}@anchor{5698}
@subsection 為何純字串 (r-string) 不能以反斜線結尾？


更精確地來說，他不能以奇數個反斜線結尾：尾端未配對的反斜線會使結尾的引號被轉義 (escapes)，變成一個未結束的字串。

設計出純字串是為了提供有自己反斜線跳脫處理的處理器（主要是正規表示式）一個方便的輸入方式。這種處理器會把未配對的結尾反斜線當成錯誤，所以純字串不允許如此。相對地，他讓你用一個反斜線跳脫引號。這些規則在他們預想的目的上正常地運作。

如果你嘗試建立 Windows 的路徑名稱，請注意 Windows 系統指令也接受一般斜線：

@example
f = open("/mydir/file.txt")  # works fine!
@end example

如果你嘗試建立 DOS 指令的路徑名稱，試試看使用以下的範例：

@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 為何 Python 沒有屬性賦值的 with 陳述式？,為何產生器 generator 不支援 with 陳述式？,為何純字串 r-string 不能以反斜線結尾？,設計和歷史常見問答集
@anchor{faq/design why-doesn-t-python-have-a-with-statement-for-attribute-assignments}@anchor{5699}
@subsection 為何 Python 沒有屬性賦值的 with 陳述式？


Python 的 @ref{186,,with} 陳述式包裝了一區塊程式的執行，在進入和離開該區塊時執行程式碼。一些語言會有像如下的結構：

@example
with obj:
    a = 1               # equivalent to obj.a = 1
    total = total + 1   # obj.total = obj.total + 1
@end example

但在 Python，這種結構是模糊的。

在其他語言裡，像是 Object Pascal、Delphi 和 C++，使用的是靜態型別，所以我們可以清楚地知道是哪一個成員被指派值。這是靜態型別的重點 — 在編譯的時候，編譯器`永遠'都知道每個變數的作用域 (scope)。

Python 使用的是動態型別。所以我們不可能提前知道在執行時哪個屬性會被使用到。成員屬性可能在執行時從物件中被新增或移除。這使得如果簡單來看的話，我們無法得知以下哪個屬性會被使用：區域的、全域的、或是成員屬性？

以下列不完整的程式碼為例：

@example
def foo(a):
    with a:
        print(x)
@end example

這段程式碼假設 @code{a} 有一個叫做 @code{x} 的成員屬性。然後，Python 裡並沒有任何跡象告訴直譯器這件事。在假設「a」是一個整數的話，那會發生什麼事？如果有一個全域變數稱為 @code{x}，那在這個 @ref{186,,with} 區塊會被使用嗎？如你所見，Python 動態的天性使得這種選擇更加困難。

然而 @ref{186,,with} 陳述式或類似的語言特性（減少程式碼量）的主要好處可以透過賦值來達成。相較於這樣寫：

@example
function(args).mydict[index][index].a = 21
function(args).mydict[index][index].b = 42
function(args).mydict[index][index].c = 63
@end example

應該寫成這樣：

@example
ref = function(args).mydict[index][index]
ref.a = 21
ref.b = 42
ref.c = 63
@end example

這也有提升執行速度的副作用，因為 Python 的名稱綁定解析會在執行的時候發生，而第二版只需要執行解析一次即可。

類似的提案包括引入語法以進一步減少程式碼量，例如使用「前導點 (leading dot)」，但這些提案已被捨棄，以維持程式的明確性（參閱 @indicateurl{https://mail.python.org/pipermail/python-ideas/2016-May/040070.html}）。

@node 為何產生器 generator 不支援 with 陳述式？,為何 if、while、def、class 陳述式裡需要冒號？,為何 Python 沒有屬性賦值的 with 陳述式？,設計和歷史常見問答集
@anchor{faq/design why-don-t-generators-support-the-with-statement}@anchor{569a}
@subsection 為何產生器 (generator) 不支援 with 陳述式？


出於技術原因，把產生器直接用作情境 (context) 管理器會無法正常運作。因為通常來說，產生器是被當成疊代器 (iterator)，到最後完成時不需要被手動關閉。但如果你需要的話，你可以在 @ref{186,,with} 陳述式裡用 @ref{1581,,contextlib.closing(generator)} 來包裝他。

@node 為何 if、while、def、class 陳述式裡需要冒號？,為何 Python 允許在串列和元組末端加上逗號？,為何產生器 generator 不支援 with 陳述式？,設計和歷史常見問答集
@anchor{faq/design why-are-colons-required-for-the-if-while-def-class-statements}@anchor{569b}
@subsection 為何 if、while、def、class 陳述式裡需要冒號？


需要冒號主要是為了增加可讀性（由 ABC 語言的實驗得知）。試想如下範例：

@example
if a == b
    print(a)
@end example

以及：

@example
if a == b:
    print(a)
@end example

注意第二個例子稍微易讀一些的原因。可以更進一步觀察，一個冒號是如何放在這個 FAQ 答案的例子裡的，這是標準的英文用法。

另一個小原因是冒號會使編輯器更容易做語法突顯，他們只需要看冒號的位置就可以決定是否需要更多縮排，而不用做更多繁複精密的程式碼剖析。

@node 為何 Python 允許在串列和元組末端加上逗號？,,為何 if、while、def、class 陳述式裡需要冒號？,設計和歷史常見問答集
@anchor{faq/design why-does-python-allow-commas-at-the-end-of-lists-and-tuples}@anchor{569c}
@subsection 為何 Python 允許在串列和元組末端加上逗號？


Python 允許你在串列、元組和字典的結尾加上逗號：

@example
[1, 2, 3,]
('a', 'b', 'c',)
d = @{
    "A": [1, 5],
    "B": [6, 7],  # last trailing comma is optional but good style
@}
@end example

這有許多原因可被允許。

當你要把串列、元組或字典的值寫成多行時，這樣做會讓你新增元素時較為方便，因為你不需要在前一行加上逗號。這幾行的值也可以被重新排序，而不會導致語法錯誤。

不小心遺漏了逗號會導致難以發現的錯誤，例如：

@example
x = [
  "fee",
  "fie"
  "foo",
  "fum"
]
@end example

這個串列看起來有四個元素，但他其實只有三個：「fee」、「fiefoo」、「fum」。永遠記得加上逗號以避免這種錯誤。

允許結尾逗號也讓生成的程式碼更容易產生。

@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{faq/library doc}@anchor{569d}@anchor{faq/library library-and-extension-faq}@anchor{569e}@anchor{faq/library translation-repo}@anchor{569f}
@section 函式庫和擴充功能的常見問題



@menu
* 常見函式問題:: 
* 常見課題:: 
* 執行緒:: 
* 輸入與輸出:: 
* 網路 (Network)/網際網路 (Internet) 程式: 網路 Network /網際網路 Internet 程式. 
* 資料庫:: 
* 數學和數值:: 

@end menu

@node 常見函式問題,常見課題,,函式庫和擴充功能的常見問題
@anchor{faq/library general-library-questions}@anchor{56a0}
@subsection 常見函式問題


@menu
* 我如何找到執行任務 X 的模組或應用程式？:: 
* 哪裡可以找到 math.py (socket.py@comma{} regex.py@comma{} 等...) 來源檔案？: 哪裡可以找到 math py socket py regex py 等 來源檔案？. 
* 我如何使 Python script 執行在 Unix？:: 
* 是否有適用於 Python 的 curses/termcap 套件？:: 
* Python 中是否有等同於 C 的 onexit() 的函式？: Python 中是否有等同於 C 的 onexit 的函式？. 
* 為什麼我的訊號處理程式不起作用？:: 

@end menu

@node 我如何找到執行任務 X 的模組或應用程式？,哪裡可以找到 math py socket py regex py 等 來源檔案？,,常見函式問題
@anchor{faq/library how-do-i-find-a-module-or-application-to-perform-task-x}@anchor{56a1}
@subsubsection 我如何找到執行任務 X 的模組或應用程式？


查看@ref{149,,函式庫參照}以了解是否有相關的標準函式庫模組。 （當你熟悉標準函式庫中的內容後就可以能跳過這一步。）

對於第三方套件，搜尋 Python 套件索引@footnote{https://pypi.org}或嘗試使用 Google@footnote{https://www.google.com} 或其他網路搜尋引擎。搜尋 "Python" 加上你感興趣主題的一兩個關鍵字，通常能夠找到有用的東西。

@node 哪裡可以找到 math py socket py regex py 等 來源檔案？,我如何使 Python script 執行在 Unix？,我如何找到執行任務 X 的模組或應用程式？,常見函式問題
@anchor{faq/library where-is-the-math-py-socket-py-regex-py-etc-source-file}@anchor{56a2}
@subsubsection 哪裡可以找到 math.py (socket.py, regex.py, 等...) 來源檔案？


If you can't find a source file for a module it may be a built-in or
dynamically loaded module implemented in C, C++ or other compiled language.
In this case you may not have the source file or it may be something like
@code{mathmodule.c}, somewhere in a C source directory (not on the Python Path).

有（至少）三種 Python 模組：


@enumerate 

@item 
以 Python 編寫的模組 (.py)；

@item 
用 C 編寫並動態載入的模組（.dll、.pyd、.so、.sl 等）；

@item 
用 C 編寫並與直譯器鏈接的模組；要獲得這些 list，請輸入：

@example
import sys
print(sys.builtin_module_names)
@end example
@end enumerate

@node 我如何使 Python script 執行在 Unix？,是否有適用於 Python 的 curses/termcap 套件？,哪裡可以找到 math py socket py regex py 等 來源檔案？,常見函式問題
@anchor{faq/library how-do-i-make-a-python-script-executable-on-unix}@anchor{56a3}
@subsubsection 我如何使 Python script 執行在 Unix？


You need to do two things: the script file's mode must be executable and the
first line must begin with @code{#!} followed by the path of the Python
interpreter.

第一個是透過執行 @code{chmod +x scriptfile} 或者可能是 @code{chmod 755 scriptfile} 來完成的。

第二個則可以透過多種方式完成。最直接的方法是寫：

@example
#!/usr/local/bin/python
@end example

作為檔案的第一行，使用 Python 直譯器安裝在你的平台上的路徑名稱。

If you would like the script to be independent of where the Python interpreter
lives, you can use the @code{env} program.  Almost all Unix variants support
the following, assuming the Python interpreter is in a directory on the user's
@geindex PATH
@geindex 環境變數; PATH
@code{PATH}:

@example
#!/usr/bin/env python
@end example

`不要'對 CGI 腳本執行此操作。CGI 腳本的 
@geindex PATH
@geindex 環境變數; PATH
@code{PATH} 變數通常非常小，因此你需要使用直譯器的實際絕對路徑名稱。

Occasionally, a user's environment is so full that the @code{/usr/bin/env}
program fails; or there's no env program at all.  In that case, you can try the
following hack (due to Alex Rezinsky):

@example
#! /bin/sh
""":"
exec python $0 $@{1+"$@@"@}
"""
@end example

次要缺點是這定義了腳本的 __doc__ 字串。但是你可以透過新增下面這一行來解決這個問題：

@example
__doc__ = """...Whatever..."""
@end example

@node 是否有適用於 Python 的 curses/termcap 套件？,Python 中是否有等同於 C 的 onexit 的函式？,我如何使 Python script 執行在 Unix？,常見函式問題
@anchor{faq/library is-there-a-curses-termcap-package-for-python}@anchor{56a4}
@subsubsection 是否有適用於 Python 的 curses/termcap 套件？


@c XXX curses *is* built by default, isn't it?

For Unix variants: The standard Python source distribution comes with a curses
module in the Modules@footnote{https://github.com/python/cpython/tree/3.14/Modules} subdirectory, though it's not compiled by default.
(Note that this is not available in the Windows distribution -- there is no
curses module for Windows.)

The @ref{2f,,curses} module supports basic curses features as well as many additional
functions from ncurses and SYSV curses such as colour, alternative character set
support, pads, and mouse support. This means the module isn't 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.

@node Python 中是否有等同於 C 的 onexit 的函式？,為什麼我的訊號處理程式不起作用？,是否有適用於 Python 的 curses/termcap 套件？,常見函式問題
@anchor{faq/library is-there-an-equivalent-to-c-s-onexit-in-python}@anchor{56a5}
@subsubsection Python 中是否有等同於 C 的 onexit() 的函式？


@ref{d,,atexit} 模組提供了一個類似於 C @code{onexit()} 的註冊函式。

@node 為什麼我的訊號處理程式不起作用？,,Python 中是否有等同於 C 的 onexit 的函式？,常見函式問題
@anchor{faq/library why-don-t-my-signal-handlers-work}@anchor{56a6}
@subsubsection 為什麼我的訊號處理程式不起作用？


最常見的問題是訊號處理程式是用錯誤的引數串列聲明的。它以以下形式來呼叫：

@example
handler(signum, frame)
@end example

所以它應該用兩個參數聲明：

@example
def handler(signum, frame):
    ...
@end example

@node 常見課題,執行緒,常見函式問題,函式庫和擴充功能的常見問題
@anchor{faq/library common-tasks}@anchor{56a7}
@subsection 常見課題


@menu
* 如何測試 Python 程式或元件？:: 
* 如何從文件字串建立文件？:: 
* How do I get a single keypress at a time?:: 

@end menu

@node 如何測試 Python 程式或元件？,如何從文件字串建立文件？,,常見課題
@anchor{faq/library how-do-i-test-a-python-program-or-component}@anchor{56a8}
@subsubsection 如何測試 Python 程式或元件？


Python comes with two testing frameworks.  The @ref{3e,,doctest} module finds
examples in the docstrings for a module and runs them, comparing the output with
the expected output given in the docstring.

@ref{10c,,unittest} 模組是一個更炫目的測試框架，它以 Java 和 Smalltalk 測試框架為模型。

To make testing easier, you should use good modular design in your program.
Your program should have almost all functionality
encapsulated in either functions or class methods -- and this sometimes has the
surprising and delightful effect of making the program run faster (because local
variable accesses are faster than global accesses).  Furthermore the program
should avoid depending on mutating global variables, since this makes testing
much more difficult to do.

The "global main logic" of your program may be as simple as

@example
if __name__ == "__main__":
    main_logic()
@end example

at the bottom of the main module of your program.

Once your program is organized as a tractable collection of function and class
behaviours, you should write test functions that exercise the behaviours.  A
test suite that automates a sequence of tests can be associated with each module.
This sounds like a lot of work, but since Python is so terse and flexible it's
surprisingly easy.  You can make coding much more pleasant and fun by writing
your test functions in parallel with the "production code", since this makes it
easy to find bugs and even design flaws earlier.

"Support modules" that are not intended to be the main module of a program may
include a self-test of the module.

@example
if __name__ == "__main__":
    self_test()
@end example

Even programs that interact with complex external interfaces may be tested when
the external interfaces are unavailable by using "fake" interfaces implemented
in Python.

@node 如何從文件字串建立文件？,How do I get a single keypress at a time?,如何測試 Python 程式或元件？,常見課題
@anchor{faq/library how-do-i-create-documentation-from-doc-strings}@anchor{56a9}
@subsubsection 如何從文件字串建立文件？


The @ref{ba,,pydoc} module can create HTML from the doc strings in your Python
source code.  An alternative for creating API documentation purely from
docstrings is epydoc@footnote{https://epydoc.sourceforge.net/}.  Sphinx@footnote{https://www.sphinx-doc.org} can also include docstring content.

@node How do I get a single keypress at a time?,,如何從文件字串建立文件？,常見課題
@anchor{faq/library how-do-i-get-a-single-keypress-at-a-time}@anchor{56aa}
@subsubsection How do I get a single keypress at a time?


對於 Unix 變體有幾種解決方案。使用 curses 執行此操作很直觀，但 curses 是一個學習成本較大的模組。

@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 執行緒,輸入與輸出,常見課題,函式庫和擴充功能的常見問題
@anchor{faq/library threads}@anchor{56ab}
@subsection 執行緒


@menu
* 如何使用執行緒編寫程式？:: 
* 我的執行緒似乎都沒有運行：為什麼？:: 
* How do I parcel out work among a bunch of worker threads?:: 
* 什麼樣的全域值變化是執行緒安全的？:: 
* 不能擺脫全域直譯器鎖嗎？:: 

@end menu

@node 如何使用執行緒編寫程式？,我的執行緒似乎都沒有運行：為什麼？,,執行緒
@anchor{faq/library how-do-i-program-using-threads}@anchor{56ac}
@subsubsection 如何使用執行緒編寫程式？


Be sure to use the @ref{f3,,threading} module and not the @ref{2,,_thread} module.
The @ref{f3,,threading} module builds convenient abstractions on top of the
low-level primitives provided by the @ref{2,,_thread} module.

@node 我的執行緒似乎都沒有運行：為什麼？,How do I parcel out work among a bunch of worker threads?,如何使用執行緒編寫程式？,執行緒
@anchor{faq/library none-of-my-threads-seem-to-run-why}@anchor{56ad}
@subsubsection 我的執行緒似乎都沒有運行：為什麼？


As soon as the main thread exits, all threads are killed.  Your main thread is
running too quickly, giving the threads no time to do any work.

一個簡單的修復方式是在程式末尾新增一個足夠長的 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

But now (on many platforms) the threads don't run in parallel, but appear to run
sequentially, one at a time!  The reason is that the OS thread scheduler doesn't
start a new thread until the previous thread is blocked.

一個簡單的修復方式是在運行函式的開頭新增一個小 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

Instead of trying to guess a good delay value for @ref{8a4,,time.sleep()},
it's better to use some kind of semaphore mechanism.  One idea is to use the
@ref{bb,,queue} module to create a queue object, let each thread append a token to
the queue when it finishes, and let the main thread read as many tokens from the
queue as there are threads.

@node How do I parcel out work among a bunch of worker threads?,什麼樣的全域值變化是執行緒安全的？,我的執行緒似乎都沒有運行：為什麼？,執行緒
@anchor{faq/library how-do-i-parcel-out-work-among-a-bunch-of-worker-threads}@anchor{56ae}
@subsubsection How do I parcel out work among a bunch of worker threads?


The easiest way is to use the @ref{24,,concurrent.futures} module,
especially the @ref{941,,ThreadPoolExecutor} class.

Or, if you want fine control over the dispatching algorithm, you can write
your own logic manually.  Use the @ref{bb,,queue} module to create a queue
containing a list of jobs.  The @ref{158c,,Queue} class maintains a
list of objects and has a @code{.put(obj)} method that adds items to the queue and
a @code{.get()} method to return them.  The class will take care of the locking
necessary to ensure that each job is handed out exactly once.

這是一個簡單的例子：

@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

Consult the module's documentation for more details; the @ref{158c,,Queue}
class provides a featureful interface.

@node 什麼樣的全域值變化是執行緒安全的？,不能擺脫全域直譯器鎖嗎？,How do I parcel out work among a bunch of worker threads?,執行緒
@anchor{faq/library what-kinds-of-global-value-mutation-are-thread-safe}@anchor{56af}
@subsubsection 什麼樣的全域值變化是執行緒安全的？


A @ref{46e,,global interpreter lock} (GIL) is used internally to ensure that only one
thread runs in the Python VM at a time.  In general, Python offers to switch
among threads only between bytecode instructions; how frequently it switches can
be set via @ref{b3b,,sys.setswitchinterval()}.  Each bytecode instruction and
therefore all the C implementation code reached from each instruction is
therefore atomic from the point of view of a Python program.

In theory, this means an exact accounting requires an exact understanding of the
PVM bytecode implementation.  In practice, it means that operations on shared
variables of built-in data types (ints, lists, dicts, etc) that "look atomic"
really are.

For example, the following operations are all atomic (L, L1, L2 are lists, D,
D1, D2 are dicts, x, y are objects, i, j are ints):

@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

Operations that replace other objects may invoke those other objects'
@ref{11f8,,__del__()} method when their reference count reaches zero, and that can
affect things.  This is especially true for the mass updates to dictionaries and
lists.  When in doubt, use a mutex!

@node 不能擺脫全域直譯器鎖嗎？,,什麼樣的全域值變化是執行緒安全的？,執行緒
@anchor{faq/library can-t-we-get-rid-of-the-global-interpreter-lock}@anchor{56b0}
@subsubsection 不能擺脫全域直譯器鎖嗎？


The @ref{46e,,global interpreter lock} (GIL) is often seen as a hindrance to Python's
deployment on high-end multiprocessor server machines, because a multi-threaded
Python program effectively only uses one CPU, due to the insistence that
(almost) all Python code can only run while the GIL is held.

With the approval of 
@geindex Python Enhancement Proposals; PEP 703
PEP 703@footnote{https://peps.python.org/pep-0703/} work is now underway to remove the GIL from the
CPython implementation of Python.  Initially it will be implemented as an
optional compiler flag when building the interpreter, and so separate
builds will be available with and without the GIL.  Long-term, the hope is
to settle on a single build, once the performance implications of removing the
GIL are fully understood.  Python 3.13 is likely to be the first release
containing this work, although it may not be completely functional in this
release.

The current work to remove the GIL is based on a
fork of Python 3.9 with the GIL removed@footnote{https://github.com/colesbury/nogil}
by Sam Gross.
Prior to that,
in the days of Python 1.5, Greg Stein actually implemented a comprehensive
patch set (the "free threading" patches) that removed the GIL and replaced it
with fine-grained locking.  Adam Olsen did a similar experiment
in his python-safethread@footnote{https://code.google.com/archive/p/python-safethread}
project.  Unfortunately, both of these earlier experiments exhibited a sharp
drop in single-thread
performance (at least 30% slower), due to the amount of fine-grained locking
necessary to compensate for the removal of the GIL.  The Python 3.9 fork
is the first attempt at removing the GIL with an acceptable performance
impact.

The presence of the GIL in current Python releases
doesn't mean that you can't make good use of Python on multi-CPU machines!
You just have to be creative with dividing the work up between multiple
`processes' rather than multiple `threads'.  The
@ref{1d6,,ProcessPoolExecutor} class in the new
@ref{24,,concurrent.futures} module provides an easy way of doing so; the
@ref{98,,multiprocessing} module provides a lower-level API in case you want
more control over dispatching of tasks.

Judicious use of C extensions will also help; if you use a C extension to
perform a time-consuming task, the extension can release the GIL while the
thread of execution is in the C code and allow other threads to get some work
done.  Some standard library modules such as @ref{139,,zlib} and @ref{6c,,hashlib}
already do this.

減少 GIL 影響的另一種方法是將 GIL 設置為直譯器各自狀態的鎖 (per-interpreter-state lock)，而不是真正的全域鎖。這在 @ref{668,,Python 3.12 中首次實現}，並且可於 C API 中使用。預計 Python 3.13 將會提供其 Python 介面。目前主要的限制可能是第三方擴充模組，因為實作時必須考慮到多個直譯器才能使用，因此許多舊的擴充模組將無法使用。

@node 輸入與輸出,網路 Network /網際網路 Internet 程式,執行緒,函式庫和擴充功能的常見問題
@anchor{faq/library input-and-output}@anchor{56b1}
@subsection 輸入與輸出


@menu
* 如何刪除檔案？（以及其他檔案問題...）: 如何刪除檔案？（以及其他檔案問題 ）. 
* 如何複製檔案？:: 
* 如何讀取（或寫入）二進位制資料？:: 
* 我似乎無法在用 os.popen() 建立的 pipe 上使用 os.read()；為什麼？: 我似乎無法在用 os popen 建立的 pipe 上使用 os read ；為什麼？. 
* 如何存取序列 (RS232) 連接埠？: 如何存取序列 RS232 連接埠？. 
* 為什麼關閉 sys.stdout (stdin@comma{} stderr) 並沒有真正關閉它？: 為什麼關閉 sys stdout stdin stderr 並沒有真正關閉它？. 

@end menu

@node 如何刪除檔案？（以及其他檔案問題 ）,如何複製檔案？,,輸入與輸出
@anchor{faq/library how-do-i-delete-a-file-and-other-file-questions}@anchor{56b2}
@subsubsection 如何刪除檔案？（以及其他檔案問題...）


Use @code{os.remove(filename)} or @code{os.unlink(filename)}; for documentation, see
the @ref{a5,,os} module.  The two functions are identical; @ref{12f6,,unlink()} is simply
the name of the Unix system call for this function.

To remove a directory, use @ref{12f4,,os.rmdir()}; use @ref{526,,os.mkdir()} to create one.
@code{os.makedirs(path)} will create any intermediate directories in @code{path} that
don't exist. @code{os.removedirs(path)} will remove intermediate directories as
long as they're empty; if you want to delete an entire directory tree and its
contents, use @ref{354,,shutil.rmtree()}.

要重新命名檔案，請使用 @code{os.rename(old_path, new_path)}。

To truncate a file, open it using @code{f = open(filename, "rb+")}, and use
@code{f.truncate(offset)}; offset defaults to the current seek position.  There's
also @code{os.ftruncate(fd, offset)} for files opened with @ref{f8d,,os.open()}, where
`fd' is the file descriptor (a small integer).

@ref{ca,,shutil} 模組還包含許多用於檔案處理的函式，包括 @ref{c45,,copyfile()}、@ref{c15,,copytree()} 和 @ref{354,,rmtree()}。

@node 如何複製檔案？,如何讀取（或寫入）二進位制資料？,如何刪除檔案？（以及其他檔案問題 ）,輸入與輸出
@anchor{faq/library how-do-i-copy-a-file}@anchor{56b3}
@subsubsection 如何複製檔案？


The @ref{ca,,shutil} module contains a @ref{c45,,copyfile()} function.
Note that on Windows NTFS volumes, it does not copy
alternate data streams@footnote{https://en.wikipedia.org/wiki/NTFS#Alternate_data_stream_(ADS)}
nor resource forks@footnote{https://en.wikipedia.org/wiki/Resource_fork}
on macOS HFS+ volumes, though both are now rarely used.
It also doesn't copy file permissions and metadata, though using
@ref{c47,,shutil.copy2()} instead will preserve most (though not all) of it.

@node 如何讀取（或寫入）二進位制資料？,我似乎無法在用 os popen 建立的 pipe 上使用 os read ；為什麼？,如何複製檔案？,輸入與輸出
@anchor{faq/library how-do-i-read-or-write-binary-data}@anchor{56b4}
@subsubsection 如何讀取（或寫入）二進位制資料？


To read or write complex binary data formats, it's best to use the @ref{db,,struct}
module.  It allows you to take a string containing binary data (usually numbers)
and convert it to Python objects; and vice versa.

For example, the following code reads two 2-byte integers and one 4-byte integer
in big-endian format from a file:

@example
import struct

with open(filename, "rb") as f:
    s = f.read(8)
    x, y, z = struct.unpack(">hhl", s)
@end example

The '>' in the format string forces big-endian data; the letter 'h' reads one
"short integer" (2 bytes), and 'l' reads one "long integer" (4 bytes) from the
string.

For data that is more regular (e.g. a homogeneous list of ints or floats),
you can also use the @ref{8,,array} module.

@cartouche
@quotation 備註 
To read and write binary data, it is mandatory to open the file in
binary mode (here, passing @code{"rb"} to @ref{315,,open()}).  If you use
@code{"r"} instead (the default), the file will be open in text mode
and @code{f.read()} will return @ref{169,,str} objects rather than
@ref{192,,bytes} objects.
@end quotation
@end cartouche

@node 我似乎無法在用 os popen 建立的 pipe 上使用 os read ；為什麼？,如何存取序列 RS232 連接埠？,如何讀取（或寫入）二進位制資料？,輸入與輸出
@anchor{faq/library i-can-t-seem-to-use-os-read-on-a-pipe-created-with-os-popen-why}@anchor{56b5}
@subsubsection 我似乎無法在用 os.popen() 建立的 pipe 上使用 os.read()；為什麼？


@ref{f90,,os.read()} is a low-level function which takes a file descriptor, a small
integer representing the opened file.  @ref{319,,os.popen()} creates a high-level
file object, the same type returned by the built-in @ref{315,,open()} function.
Thus, to read `n' bytes from a pipe `p' created with @ref{319,,os.popen()}, you need to
use @code{p.read(n)}.

@node 如何存取序列 RS232 連接埠？,為什麼關閉 sys stdout stdin stderr 並沒有真正關閉它？,我似乎無法在用 os popen 建立的 pipe 上使用 os read ；為什麼？,輸入與輸出
@anchor{faq/library how-do-i-access-the-serial-rs232-port}@anchor{56b6}
@subsubsection 如何存取序列 (RS232) 連接埠？


對於 Win32、OSX、Linux、BSD、Jython、IronPython：

@quotation

pyserial@footnote{https://pypi.org/project/pyserial/}
@end quotation

對於 Unix，請參閱 Mitch Chapman 的 Usenet 貼文：

@quotation

@indicateurl{https://groups.google.com/groups?selm=34A04430.CF9@@ohioee.com}
@end quotation

@node 為什麼關閉 sys stdout stdin stderr 並沒有真正關閉它？,,如何存取序列 RS232 連接埠？,輸入與輸出
@anchor{faq/library why-doesn-t-closing-sys-stdout-stdin-stderr-really-close-it}@anchor{56b7}
@subsubsection 為什麼關閉 sys.stdout (stdin, stderr) 並沒有真正關閉它？


Python @ref{13c4,,檔案物件}是低階 C 檔案描述器的高階抽象層。

For most file objects you create in Python via the built-in @ref{315,,open()}
function, @code{f.close()} marks the Python file object as being closed from
Python's point of view, and also arranges to close the underlying C file
descriptor.  This also happens automatically in @code{f}'s destructor, when
@code{f} becomes garbage.

But stdin, stdout and stderr are treated specially by Python, because of the
special status also given to them by C.  Running @code{sys.stdout.close()} marks
the Python-level file object as being closed, but does `not' close the
associated C file descriptor.

To close the underlying C file descriptor for one of these three, you should
first be sure that's what you really want to do (e.g., you may confuse
extension modules trying to do I/O).  If it is, use @ref{d63,,os.close()}:

@example
os.close(stdin.fileno())
os.close(stdout.fileno())
os.close(stderr.fileno())
@end example

或者你可以分別使用數字常數 0、1 和 2。

@node 網路 Network /網際網路 Internet 程式,資料庫,輸入與輸出,函式庫和擴充功能的常見問題
@anchor{faq/library network-internet-programming}@anchor{56b8}
@subsection 網路 (Network)/網際網路 (Internet) 程式


@menu
* Python 有哪些 WWW 工具？:: 
* 我應該使用什麼模組來輔助產生 HTML？:: 
* 如何從 Python 腳本發送郵件？:: 
* 如何避免阻塞 socket 的 connect() 方法？: 如何避免阻塞 socket 的 connect 方法？. 

@end menu

@node Python 有哪些 WWW 工具？,我應該使用什麼模組來輔助產生 HTML？,,網路 Network /網際網路 Internet 程式
@anchor{faq/library what-www-tools-are-there-for-python}@anchor{56b9}
@subsubsection Python 有哪些 WWW 工具？


See the chapters titled @ref{3d78,,網路協定 (Internet protocols) 及支援} and @ref{3967,,網際網路資料處理} in the Library
Reference Manual.  Python has many modules that will help you build server-side
and client-side web systems.

@c XXX check if wiki page is still up to date

Paul Boddie 有在 @indicateurl{https://wiki.python.org/moin/WebProgramming}維護可用框架的摘要。

@node 我應該使用什麼模組來輔助產生 HTML？,如何從 Python 腳本發送郵件？,Python 有哪些 WWW 工具？,網路 Network /網際網路 Internet 程式
@anchor{faq/library what-module-should-i-use-to-help-with-generating-html}@anchor{56ba}
@subsubsection 我應該使用什麼模組來輔助產生 HTML？


@c XXX add modern template languages

你可以在 "網頁程式維基頁面 <@indicateurl{https://wiki.python.org/moin/WebProgramming}>" 上找到一組有用的鏈接。

@node 如何從 Python 腳本發送郵件？,如何避免阻塞 socket 的 connect 方法？,我應該使用什麼模組來輔助產生 HTML？,網路 Network /網際網路 Internet 程式
@anchor{faq/library how-do-i-send-mail-from-a-python-script}@anchor{56bb}
@subsubsection 如何從 Python 腳本發送郵件？


使用標準函式庫模組 @ref{cf,,smtplib}。

Here's a very simple interactive mail sender that uses it.  This method will
work on any host that supports an SMTP listener.

@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

使用 sendmail 是僅適用於 Unix 的替代方案。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 如何避免阻塞 socket 的 connect 方法？,,如何從 Python 腳本發送郵件？,網路 Network /網際網路 Internet 程式
@anchor{faq/library how-do-i-avoid-blocking-in-the-connect-method-of-a-socket}@anchor{56bc}
@subsubsection 如何避免阻塞 socket 的 connect() 方法？


@ref{c6,,select} 模組通常用於幫助處理 socket 上的非同步 I/O。

To prevent the TCP connect from blocking, you can set the socket to non-blocking
mode.  Then when you do the @ref{f9e,,connect()},
you will either connect immediately
(unlikely) or get an exception that contains the error number as @code{.errno}.
@code{errno.EINPROGRESS} indicates that the connection is in progress, but hasn't
finished yet.  Different OSes will return different values, so you're going to
have to check what's returned on your system.

You can use the @ref{172d,,connect_ex()} method
to avoid creating an exception.
It will just return the errno value.
To poll, you can call @ref{172d,,connect_ex()} again later
-- @code{0} or @code{errno.EISCONN} indicate that you're connected -- or you can pass this
socket to @ref{f9b,,select.select()} to check if it's writable.

@cartouche
@quotation 備註 
@ref{b,,asyncio} 模組提供了一個通用的單執行緒並發非同步函式庫，可用於編寫非阻塞網路程式碼。第三方 Twisted@footnote{https://twisted.org/} 函式庫是一種流行且功能豐富的替代方案。
@end quotation
@end cartouche

@node 資料庫,數學和數值,網路 Network /網際網路 Internet 程式,函式庫和擴充功能的常見問題
@anchor{faq/library databases}@anchor{56bd}
@subsection 資料庫


@menu
* Python 中是否有任何資料庫套件的介面？:: 
* 你如何在 Python 中實作持久性物件？:: 

@end menu

@node Python 中是否有任何資料庫套件的介面？,你如何在 Python 中實作持久性物件？,,資料庫
@anchor{faq/library are-there-any-interfaces-to-database-packages-in-python}@anchor{56be}
@subsubsection Python 中是否有任何資料庫套件的介面？


有的。

Interfaces to disk-based hashes such as @ref{38,,DBM} and @ref{37,,GDBM} are also included with standard Python.  There is also the
@ref{d4,,sqlite3} module, which provides a lightweight disk-based relational
database.

Support for most relational databases is available.  See the
DatabaseProgramming wiki page@footnote{https://wiki.python.org/moin/DatabaseProgramming} for details.

@node 你如何在 Python 中實作持久性物件？,,Python 中是否有任何資料庫套件的介面？,資料庫
@anchor{faq/library how-do-you-implement-persistent-objects-in-python}@anchor{56bf}
@subsubsection 你如何在 Python 中實作持久性物件？


The @ref{ab,,pickle} library module solves this in a very general way (though you
still can't store things like open files, sockets or windows), and the
@ref{c8,,shelve} library module uses pickle and (g)dbm to create persistent
mappings containing arbitrary Python objects.

@node 數學和數值,,資料庫,函式庫和擴充功能的常見問題
@anchor{faq/library mathematics-and-numerics}@anchor{56c0}
@subsection 數學和數值


@menu
* 如何在 Python 中生成隨機數？:: 

@end menu

@node 如何在 Python 中生成隨機數？,,,數學和數值
@anchor{faq/library how-do-i-generate-random-numbers-in-python}@anchor{56c1}
@subsubsection 如何在 Python 中生成隨機數？


標準模組 @ref{bd,,random} 實作了一個隨機數生成器。用法很簡單：

@example
import random
random.random()
@end example

這將回傳 [0, 1) 範圍內的隨機浮點數。

該模組中還有許多其他專用生成器，例如：


@itemize *

@item 
@code{randrange(a, b)} 會選擇 [a, b) 範圍內的一個整數。

@item 
@code{uniform(a, b)} 會選擇 [a, b) 範圍內的浮點數。

@item 
@code{normalvariate(mean, sdev)} 對常態（高斯）分佈進行取樣 (sample)。
@end itemize

一些更高階的函式會直接對序列進行操作，例如：


@itemize *

@item 
@code{choice(S)} 會從給定序列中選擇一個隨機元素。

@item 
@code{shuffle(L)} 會原地 (in-place) 打亂 list，即隨機排列它。
@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 擴充/嵌入常見問題集,在 Windows 使用 Python 的常見問答集,函式庫和擴充功能的常見問題,Python 常見問題
@anchor{faq/extending doc}@anchor{56c2}@anchor{faq/extending extending-embedding-faq}@anchor{56c3}@anchor{faq/extending translation-repo}@anchor{56c4}
@section 擴充/嵌入常見問題集



@c XXX need review for Python 3.

@menu
* 我可以在 C 中建立自己的函式嗎？:: 
* 我可以在 C++ 中建立自己的函式嗎？:: 
* 寫 C 很難；還有其他選擇嗎？:: 
* 如何從 C 執行任意 Python 陳述式？:: 
* 如何計算來自 C 的任意 Python 運算式？:: 
* 如何從 Python 物件中提取 C 值？:: 
* 如何使用 Py_BuildValue() 建立任意長度的元組？: 如何使用 Py_BuildValue 建立任意長度的元組？. 
* 如何從 C 呼叫物件的方法？:: 
* 我如何捕捉 PyErr_Print() 的輸出（或任何印出到 stdout/stderr 的東西）？: 我如何捕捉 PyErr_Print 的輸出（或任何印出到 stdout/stderr 的東西）？. 
* 如何從 C 存取用 Python 編寫的模組？:: 
* 我如何從 Python 介接到 C++ 物件？:: 
* 我使用安裝檔案新增了一個模組，但 make 失敗了；為什麼？:: 
* 如何為擴充套件除錯？:: 
* 我想在我的 Linux 系統上編譯一個 Python 模組，但是缺少一些檔案。為什麼？:: 
* 如何從「無效輸入」區分出「不完整輸入」？:: 
* 如何找到未定義的 g++ 符號 __builtin_new 或 __pure_virtual？:: 
* 我可以用一些用 C 實作的方法和用 Python 實作的其他方法（例如透過繼承）建立一個物件類別嗎？:: 

@end menu

@node 我可以在 C 中建立自己的函式嗎？,我可以在 C++ 中建立自己的函式嗎？,,擴充/嵌入常見問題集
@anchor{faq/extending can-i-create-my-own-functions-in-c}@anchor{56c5}
@subsection 我可以在 C 中建立自己的函式嗎？


是的，你可以在 C 中建立包含函式、變數、例外甚至新型別的內建模組，@ref{1e84,,擴充和嵌入 Python 直譯器} 文件中有相關說明。

大多數中級或進階 Python 書籍也會涵蓋這個主題。

@node 我可以在 C++ 中建立自己的函式嗎？,寫 C 很難；還有其他選擇嗎？,我可以在 C 中建立自己的函式嗎？,擴充/嵌入常見問題集
@anchor{faq/extending id2}@anchor{56c6}
@subsection 我可以在 C++ 中建立自己的函式嗎？


是的，可使用 C++ 中的 C 相容性功能。將 @code{extern "C" @{ ... @}} 放在 Python 引入檔案周圍，並將 @code{extern "C"} 放在每個將由 Python 直譯器呼叫的函式之前。但具有構造函式的全域或靜態 C++ 物件可能不是一個好主意。

@node 寫 C 很難；還有其他選擇嗎？,如何從 C 執行任意 Python 陳述式？,我可以在 C++ 中建立自己的函式嗎？,擴充/嵌入常見問題集
@anchor{faq/extending c-wrapper-software}@anchor{56c7}@anchor{faq/extending writing-c-is-hard-are-there-any-alternatives}@anchor{56c8}
@subsection 寫 C 很難；還有其他選擇嗎？


There are a number of alternatives to writing your own C extensions, depending
on what you're trying to do. @ref{4d56,,Recommended third party tools}
offer both simpler and more sophisticated approaches to creating C and C++
extensions for Python.

@node 如何從 C 執行任意 Python 陳述式？,如何計算來自 C 的任意 Python 運算式？,寫 C 很難；還有其他選擇嗎？,擴充/嵌入常見問題集
@anchor{faq/extending how-can-i-execute-arbitrary-python-statements-from-c}@anchor{56c9}
@subsection 如何從 C 執行任意 Python 陳述式？


執行此操作的最高階函式是 @ref{4dd3,,PyRun_SimpleString()}，它接受一個要在模組 @code{__main__} 的情境中執行的單一字串引數，成功時回傳 @code{0}，發生例外（包括 @ref{18e,,SyntaxError}）時回傳 @code{-1}。如果你想要更多控制，請使用 @ref{1c89,,PyRun_String()}；請參閱 @code{Python/pythonrun.c} 中 @ref{4dd3,,PyRun_SimpleString()} 的原始碼。

@node 如何計算來自 C 的任意 Python 運算式？,如何從 Python 物件中提取 C 值？,如何從 C 執行任意 Python 陳述式？,擴充/嵌入常見問題集
@anchor{faq/extending how-can-i-evaluate-an-arbitrary-python-expression-from-c}@anchor{56ca}
@subsection 如何計算來自 C 的任意 Python 運算式？


呼叫前一個問題中的 @ref{1c89,,PyRun_String()} 函式，並使用起始符號 @ref{4fbe,,Py_eval_input}；它會剖析一個運算式，計算它並回傳它的值。

@node 如何從 Python 物件中提取 C 值？,如何使用 Py_BuildValue 建立任意長度的元組？,如何計算來自 C 的任意 Python 運算式？,擴充/嵌入常見問題集
@anchor{faq/extending how-do-i-extract-c-values-from-a-python-object}@anchor{56cb}
@subsection 如何從 Python 物件中提取 C 值？


這取決於物件的型別。如果它是一個元組，@ref{4f46,,PyTuple_Size()} 會回傳它的長度，@ref{4d7f,,PyTuple_GetItem()} 則回傳指定索引的項目。串列具有類似的函式 @ref{1611,,PyList_Size()} 和 @ref{5f7,,PyList_GetItem()}。

對於位元組，@ref{4e25,,PyBytes_Size()} 會回傳它的長度，@ref{4e1f,,PyBytes_AsStringAndSize()} 則提供指向該值與該長度的指標。請注意，Python 位元組物件可能包含空位元組，因此不應使用 C 的 @code{strlen()}。

要測試物件的型別，首先確保它不是 @code{NULL}，然後再使用 @ref{1597,,PyBytes_Check()}、@ref{5170,,PyTuple_Check()}、@ref{5181,,PyList_Check()} 等函式。

還有一個針對 Python 物件的高階 API，它由所謂的「抽象」介面所提供 —— 請閱讀 @code{Include/abstract.h} 以了解更多詳細資訊。它允許使用 @ref{4f27,,PySequence_Length()}、@ref{1cfb,,PySequence_GetItem()} 等函式的呼叫以及許多其他有用的協定，例如數值（@ref{a8a,,PyNumber_Index()} 等）和 PyMapping API 中的對映，來與任何類型的 Python 序列做介接。

@node 如何使用 Py_BuildValue 建立任意長度的元組？,如何從 C 呼叫物件的方法？,如何從 Python 物件中提取 C 值？,擴充/嵌入常見問題集
@anchor{faq/extending how-do-i-use-py-buildvalue-to-create-a-tuple-of-arbitrary-length}@anchor{56cc}
@subsection 如何使用 Py_BuildValue() 建立任意長度的元組？


這無法做到。請改用 @ref{4f45,,PyTuple_Pack()}。

@node 如何從 C 呼叫物件的方法？,我如何捕捉 PyErr_Print 的輸出（或任何印出到 stdout/stderr 的東西）？,如何使用 Py_BuildValue 建立任意長度的元組？,擴充/嵌入常見問題集
@anchor{faq/extending how-do-i-call-an-object-s-method-from-c}@anchor{56cd}
@subsection 如何從 C 呼叫物件的方法？


@ref{638,,PyObject_CallMethod()} 函式可用於呼叫物件的任意方法。參數是物件、要呼叫的方法名稱、與 @ref{3c0,,Py_BuildValue()} 一起使用的格式字串，以及引數值：

@example
PyObject *
PyObject_CallMethod(PyObject *object, const char *method_name,
                    const char *arg_format, ...);
@end example

這適用於任何具有方法的物件 —— 無論是內建的還是使用者定義的。你負責最終為回傳值來 @ref{789,,Py_DECREF()}。

例如，使用引數 10、0 呼叫檔案物件的 "seek" 方法（假設檔案物件指標為 "f"）：

@example
res = PyObject_CallMethod(f, "seek", "(ii)", 10, 0);
if (res == NULL) @{
        ... 發生一個例外 ...
@}
else @{
        Py_DECREF(res);
@}
@end example

請注意，由於 @ref{4d74,,PyObject_CallObject()} `總是'需要一個元組作為引數列表，若要呼叫一個不帶引數的函式，要傳遞 "()" 作為格式，並呼叫一個帶有一個引數的函式，將引數括起來在括號中，例如 "(i)"。

@node 我如何捕捉 PyErr_Print 的輸出（或任何印出到 stdout/stderr 的東西）？,如何從 C 存取用 Python 編寫的模組？,如何從 C 呼叫物件的方法？,擴充/嵌入常見問題集
@anchor{faq/extending how-do-i-catch-the-output-from-pyerr-print-or-anything-that-prints-to-stdout-stderr}@anchor{56ce}
@subsection 我如何捕捉 PyErr_Print() 的輸出（或任何印出到 stdout/stderr 的東西）？


在 Python 程式碼中定義一個支援 @code{write()} 方法的物件。將此物件分配給 @ref{cc4,,sys.stdout} 和 @ref{b2a,,sys.stderr}。呼叫 print_error，或者只允許標準的回溯機制起作用。然後，輸出將會傳送到你的 @code{write()} 方法所指定的位置。

最簡單的方法是使用 @ref{1124,,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 如何從 C 存取用 Python 編寫的模組？,我如何從 Python 介接到 C++ 物件？,我如何捕捉 PyErr_Print 的輸出（或任何印出到 stdout/stderr 的東西）？,擴充/嵌入常見問題集
@anchor{faq/extending how-do-i-access-a-module-written-in-python-from-c}@anchor{56cf}
@subsection 如何從 C 存取用 Python 編寫的模組？


你可以取得指向模組物件的指標，如下所示：

@example
module = PyImport_ImportModule("<modulename>");
@end example

如果模組還沒有被引入（即它還沒有出現在 @ref{17c0,,sys.modules} 中），這會初始化模組；否則它只回傳 @code{sys.modules["<modulename>"]} 的值。請注意，它不會將模組輸入任何命名空間——它只會確保它已被初始化並儲存在 @ref{17c0,,sys.modules} 中。

然後你可以存取模組的屬性（即模組中定義的任何名稱），如下所示：

@example
attr = PyObject_GetAttrString(module, "<attrname>");
@end example

呼叫 @ref{18e8,,PyObject_SetAttrString()} 來分配模組中的變數也有效。

@node 我如何從 Python 介接到 C++ 物件？,我使用安裝檔案新增了一個模組，但 make 失敗了；為什麼？,如何從 C 存取用 Python 編寫的模組？,擴充/嵌入常見問題集
@anchor{faq/extending how-do-i-interface-to-c-objects-from-python}@anchor{56d0}
@subsection 我如何從 Python 介接到 C++ 物件？


根據你的要求不同而有多種不同方法。要手動執行此操作，請先閱讀@ref{1e84,,「擴充和嵌入」說明文件}。對於 Python run-time 系統，C 和 C++ 之間並沒有太多區別 —— 因此圍繞 C 結構（指標）型別來構建新 Python 型別的策略也適用於 C++ 物件。

對於 C++ 函式庫，請參閱 @ref{56c7,,寫 C 很難；還有其他選擇嗎？}。

@node 我使用安裝檔案新增了一個模組，但 make 失敗了；為什麼？,如何為擴充套件除錯？,我如何從 Python 介接到 C++ 物件？,擴充/嵌入常見問題集
@anchor{faq/extending i-added-a-module-using-the-setup-file-and-the-make-fails-why}@anchor{56d1}
@subsection 我使用安裝檔案新增了一個模組，但 make 失敗了；為什麼？


安裝程式必須以換行符結尾，如果那裡沒有換行符，構建過程將失敗。（解決這個問題需要一些醜陋的 shell 腳本 hackery，而且這個錯誤很小，似乎不值得付出努力。）

@node 如何為擴充套件除錯？,我想在我的 Linux 系統上編譯一個 Python 模組，但是缺少一些檔案。為什麼？,我使用安裝檔案新增了一個模組，但 make 失敗了；為什麼？,擴充/嵌入常見問題集
@anchor{faq/extending how-do-i-debug-an-extension}@anchor{56d2}
@subsection 如何為擴充套件除錯？


將 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 我想在我的 Linux 系統上編譯一個 Python 模組，但是缺少一些檔案。為什麼？,如何從「無效輸入」區分出「不完整輸入」？,如何為擴充套件除錯？,擴充/嵌入常見問題集
@anchor{faq/extending i-want-to-compile-a-python-module-on-my-linux-system-but-some-files-are-missing-why}@anchor{56d3}
@subsection 我想在我的 Linux 系統上編譯一個 Python 模組，但是缺少一些檔案。為什麼？


大多數打包版本的 Python 省略了編譯 Python 擴充所需的一些檔案。

在 Red Hat 上，請安裝 python3-devel RPM 來取得必要的檔案。

對於 Debian，運行 @code{apt-get install python3-dev}。

@node 如何從「無效輸入」區分出「不完整輸入」？,如何找到未定義的 g++ 符號 __builtin_new 或 __pure_virtual？,我想在我的 Linux 系統上編譯一個 Python 模組，但是缺少一些檔案。為什麼？,擴充/嵌入常見問題集
@anchor{faq/extending how-do-i-tell-incomplete-input-from-invalid-input}@anchor{56d4}
@subsection 如何從「無效輸入」區分出「不完整輸入」？


有時你會想模擬 Python 交互式直譯器的行為，當輸入不完整時（例如，當你輸入了 "if" 陳述式的開頭或者你沒有關閉你的括號或三重字串引號）它會給你一個繼續提示字元，但是當輸入無效時，它會立即為你提供語法錯誤訊息。

在 Python 中，你可以使用 @ref{1d,,codeop} 模組，它充分模擬了剖析器 (parser) 的行為。像是 IDLE 就有使用它。

在 C 中執行此操作的最簡單方法是呼叫 @ref{4fc5,,PyRun_InteractiveLoop()}（可能是在單獨的執行緒中）並讓 Python 直譯器為你處理輸入。你還可以將 @ref{79e,,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{56d5}
@subsection 如何找到未定義的 g++ 符號 __builtin_new 或 __pure_virtual？


要動態載入 g++ 擴充模組，你必須重新編譯 Python，並使用 g++ 重新鏈接它（更改 Python 模組 Makefile 中的 LINKCC），且使用 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{56d6}
@subsection 我可以用一些用 C 實作的方法和用 Python 實作的其他方法（例如透過繼承）建立一個物件類別嗎？


是的，你可以繼承內建類別，例如 @ref{19b,,int}、@ref{24d,,list}、@ref{183,,dict} 等。

Boost Python 函式庫（BPL，@indicateurl{https://www.boost.org/libs/python/doc/index.html}）提供了一種從 C++ 執行此操作的方法（即你可以使用 BPL 來繼承用 C++ 編寫的擴充類別）。

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node 在 Windows 使用 Python 的常見問答集,圖形使用者介面常見問答集,擴充/嵌入常見問題集,Python 常見問題
@anchor{faq/windows doc}@anchor{56d7}@anchor{faq/windows python-on-windows-faq}@anchor{56d8}@anchor{faq/windows translation-repo}@anchor{56d9}@anchor{faq/windows windows-faq}@anchor{56da}
@section 在 Windows 使用 Python 的常見問答集



@c XXX need review for Python 3.
@c XXX need review for Windows Vista/Seven?

@menu
* 如何在 Windows 作業系統裡運行 Python 程式？:: 
* 如何使 Python 腳本可以執行？:: 
* 為什麼 Python 有時需要這麼長的時間才能開始？:: 
* 如何從 Python 腳本製作可執行檔？:: 
* *.pyd 檔是否與 DLL 相同？: * pyd 檔是否與 DLL 相同？. 
* 如何將 Python 嵌入 Windows 應用程式中？:: 
* 如何防止編輯器在我的 Python 原始碼中插入 tab？:: 
* 如何在不阻塞的情況下檢查 keypress？:: 
* 如何解決遺漏 api-ms-win-crt-runtime-l1-1-0.dll 的錯誤？: 如何解決遺漏 api-ms-win-crt-runtime-l1-1-0 dll 的錯誤？. 

@end menu

@node 如何在 Windows 作業系統裡運行 Python 程式？,如何使 Python 腳本可以執行？,,在 Windows 使用 Python 的常見問答集
@anchor{faq/windows faq-run-program-under-windows}@anchor{56db}@anchor{faq/windows how-do-i-run-a-python-program-under-windows}@anchor{56dc}
@subsection 如何在 Windows 作業系統裡運行 Python 程式？


這個問題的答案可能有點複雜。如果你經常使用「命令提示字元」執行程式，那這對你來說不會是什麼難事。如果不然，那就需要更仔細的說明了。

除非你使用某種整合開發環境，否則你最終將會在所謂的「命令提示字元視窗」中 `打字輸入' Windows 命令。通常，你可以透過從搜尋欄中搜尋 @code{cmd} 來建立這樣的視窗。你應該能夠認出何時已啟動這樣的視窗，因為你將看到 Windows「命令提示字元」，它通常看起來像這樣：

@example
C:\>
@end example

第一個字母可能不一樣，且後面也可能還有其他內容，因此你可能會很容易看到類似以下的文字：

@example
D:\YourName\Projects\Python>
@end example

取決於你的電腦如何被設置，以及你最近對它所做的其他操作。一旦你啟動了這樣一個視窗，你就即將可以運行 Python 程式了。

你需要了解，你的 Python 腳本必須被另一個稱為 Python `直譯器'的程序來處理。直譯器會讀取你的腳本，將其編譯為位元組碼，然後執行該位元組碼以運行你的程式。那麼，你要如何安排直譯器來處理你的 Python 呢？

首先，你需要確保你的命令視窗會將單字 "py" 識別為啟動直譯器的指令。如果你已經開啟一個命令視窗，則你應該試試輸入命令 @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

你已經啟動直譯器中的「互動模式」。這表示你能夠以互動方式輸入 Python 陳述式或運算式，並在等待時執行或計算它們。這是 Python 最強大的功能之一。輸入你所選的幾個運算式並查看結果，可以檢驗此功能：

@example
>>> print("Hello")
Hello
>>> "Hello" * 3
'HelloHelloHello'
@end example

許多人將互動模式作為方便但可高度程式化的計算機。如果你要結束互動式 Python 對話，請呼叫 @ref{2495,,exit()} 函式或是按住 @code{Ctrl} 鍵再輸入 @code{Z}，然後按下 "@code{Enter}" 鍵以返回 Windows 命令提示字元。

你可能還會發現你有一個開始功能表項目，像是：開始 ‣ 所有程式 ‣ Python 3.x ‣ Python（命令行），它會讓你在一個新視窗中看到 @code{>>>} 提示字元。如果是這樣，該視窗將在你呼叫 @ref{2495,,exit()} 函式或輸入 @code{Ctrl}-@code{Z} 字元後消失；Windows 正在該視窗中運行單一個「python」命令，並在你終止直譯器時將其關閉。

現在我們知道 @code{py} 命令已被識別，而你可以將你的 Python 腳本提供給它。你必須為 Python 腳本給定絕對路徑或相對路徑。假設你的 Python 腳本位於桌面上，並被命名為 @code{hello.py}，且你的命令提示字元在你的家目錄 (home directory) 中順利地被開啟，那麼你就會看到類似以下的內容：

@example
C:\Users\YourName>
@end example

因此，現在你將透過鍵入 @code{py} 加上腳本路徑，來使用 @code{py} 命令將你的腳本提供給 Python：

@example
C:\Users\YourName> py Desktop\hello.py
hello
@end example

@node 如何使 Python 腳本可以執行？,為什麼 Python 有時需要這麼長的時間才能開始？,如何在 Windows 作業系統裡運行 Python 程式？,在 Windows 使用 Python 的常見問答集
@anchor{faq/windows how-do-i-make-python-scripts-executable}@anchor{56dd}
@subsection 如何使 Python 腳本可以執行？


在 Windows 上，標準的 Python 安裝程式已將 .py 副檔名與一種檔案類型 (Python.File) 進行關聯，並為該檔案類型提供一個開啟命令來運行直譯器 (@code{D:\Program Files\Python\python.exe "%1" %*})。這足以使腳本能以類似 'foo.py' 的形式從命令提示字元被執行。如果你希望能夠簡單地輸入 'foo' 來執行腳本，而不用加上副檔名，則需要將 .py 新增至 PATHEXT 環境變數中。

@node 為什麼 Python 有時需要這麼長的時間才能開始？,如何從 Python 腳本製作可執行檔？,如何使 Python 腳本可以執行？,在 Windows 使用 Python 的常見問答集
@anchor{faq/windows why-does-python-sometimes-take-so-long-to-start}@anchor{56de}
@subsection 為什麼 Python 有時需要這麼長的時間才能開始？


通常 Python 在 Windows 上啟動得非常快，但偶爾會有一些錯誤報告，內容是 Python 突然開始需要很長的時間才能啟動。這種情形更令人費解，因為 Python 在其他 Windows 系統上可以正常工作，而那些系統似乎也有相同的配置。

這個問題可能是由發生此問題的電腦上的病毒檢查軟體配置錯誤所引起的。目前已知某些病毒掃描程式，在它們被配置為監視來自檔案系統的所有讀取時，會引入兩個數量級的啟動負擔。請試著檢查你系統上的病毒掃描軟體配置，以確保它們的配置確實相同。當 McAfee 被配置為掃描所有檔案系統的讀取活動時，它是一個特定的違規者。

@node 如何從 Python 腳本製作可執行檔？,* pyd 檔是否與 DLL 相同？,為什麼 Python 有時需要這麼長的時間才能開始？,在 Windows 使用 Python 的常見問答集
@anchor{faq/windows how-do-i-make-an-executable-from-a-python-script}@anchor{56df}
@subsection 如何從 Python 腳本製作可執行檔？


請參閱@ref{5633,,如何從 Python 腳本建立獨立的二進位檔案？}該章節列出了用於製作可執行檔的工具清單。

@node * pyd 檔是否與 DLL 相同？,如何將 Python 嵌入 Windows 應用程式中？,如何從 Python 腳本製作可執行檔？,在 Windows 使用 Python 的常見問答集
@anchor{faq/windows is-a-pyd-file-the-same-as-a-dll}@anchor{56e0}
@subsection @code{*.pyd} 檔是否與 DLL 相同？


是的，.pyd 檔類似於 dll，但也有一些區別。如果你有一個名為 @code{foo.pyd} 的 DLL，則它必須具有函式 @code{PyInit_foo()}。接著你可以將 "import foo" 寫入 Python 腳本，Python 將會搜尋 foo.pyd（以及 foo.py、foo.pyc），如果 Python 找到它，將會嘗試呼叫 @code{PyInit_foo()} 來將它初始化。你並不會將你的 .exe 與 foo.lib 連結 (link)，因為這會導致 Windows 要求 DLL 的存在。

請注意，foo.pyd 的搜尋路徑是 PYTHONPATH，與 Windows 用於搜尋 foo.dll 的路徑不同。此外，foo.pyd 不需存在即可運行你的程式，然而如果你將程式連結了一個 dll，則該 dll 會是必要的。當然，如果你想要 @code{import foo}，foo.pyd 就是必要的。在 DLL 中，連結是以 @code{__declspec(dllexport)} 在原始碼中被宣告。在 .pyd 中，連結是在一個可用函式的 list（串列）中被定義。

@node 如何將 Python 嵌入 Windows 應用程式中？,如何防止編輯器在我的 Python 原始碼中插入 tab？,* pyd 檔是否與 DLL 相同？,在 Windows 使用 Python 的常見問答集
@anchor{faq/windows how-can-i-embed-python-into-a-windows-application}@anchor{56e1}
@subsection 如何將 Python 嵌入 Windows 應用程式中？


在 Windows 應用程式中嵌入 Python 直譯器的過程可以總結如下：


@enumerate 

@item 
`不要'直接將 Python 建置到你的 .exe 檔中。在 Windows 上，Python 必須是一個 DLL 來處理模組的 import，而那些模組本身也是 DLL。（這是第一個未正式記載的關鍵事實。）請改為連結到 @code{python`NN'.dll}；它通常被安裝在 @code{C:\Windows\System} 中。`NN' 是 Python 版本，例如 "33" 就是指 Python 3.3。

你可以透過兩種不同的方式連結到 Python。載入時連結 (load-time linking) 表示要連結到 @code{python`NN'.lib}，而執行環境連結 (run-time linking) 表示要連結到 @code{python`NN'.dll}。（一般註解：@code{python`NN'.lib} 是 @code{python`NN'.dll} 相對應的所謂 "import lib"。它只會為鏈接器定義符號。）

執行環境連結大大簡化了連結選項；所有事情都會發生在執行環境。你的程式碼必須使用 Windows @code{LoadLibraryEx()} 常式 (routine) 來載入 @code{python`NN'.dll}。該程式碼也必須用 Windows @code{GetProcAddress()} 常式所取得的指標，來使用 @code{python`NN'.dll} 中的（即為 Python C API 的）存取常式和資料。對於任何呼叫 Python C API 常式的 C 程式碼，巨集可以讓使用這些指標的過程透明化。

@c XXX what about static linking?

@item 
如果你使用 SWIG，則可輕鬆地建立一個 Python 「擴充模組」，該模組將使應用程式的資料和 method（方法）可供 Python 使用。SWIG 會為你處理幾乎所有的繁瑣細節。結果就是，你會將 C 程式碼連結`到'你的 .exe 檔裡（！）你`不必'建立 DLL 檔，而這也簡化了連結。

@item 
SWIG 將建立一個 init 函式（一個 C 函式），其名稱取決於擴充模組的名稱。例如，如果模組的名稱是 leo，則該 init 函式會命名為 initleo()。如果你使用 SWIG shadow class（類別），則 init 函式會命名為 initleoc()。這會初始化被 shadow class 所用的大多數隱藏的 helper class。

你可以將步驟 2 中的 C 程式碼連結到 .exe 檔中的原因是，呼叫初始化函式就等效於 import 模組進 Python！（這是第二個未正式記載的關鍵事實。）

@item 
簡而言之，你可以使用以下程式碼，以你的擴充模組初始化 Python 直譯器。

@example
#include <Python.h>
...
Py_Initialize();  // 初始化 Python。
initmyAppc();  // 初始化（引入）幫助類別。
PyRun_SimpleString("import myApp");  // 引入 shadow 類別。
@end example

@item 
Python 的 C API 有兩個問題，如果你使用 MSVC（用於建置 pythonNN.dll 的編譯器）以外的編譯器，這些問題將會變得明顯。

問題 1：使用 @code{FILE *} 引數的所謂「非常高階」的函式，在多編譯器 (multi-compiler) 的環境中會無法作用，因為每個編譯器對 @code{struct FILE} 的概念不同。從實作的觀點來看，這些都是非常_低階_的函式。

問題 2：SWIG 在為 void 函式產生包裝函式 (wrapper) 時會產生以下程式碼：

@example
Py_INCREF(Py_None);
_resultobj = Py_None;
return _resultobj;
@end example

唉，Py_None 是一個巨集，它會延伸到一個參照，指向 pythonNN.dll 內部的一種稱為 _Py_NoneStruct 的複雜資料結構。同樣的，此程式碼在多編譯器環境中將會失效。請將此類程式碼替換為：

@example
return Py_BuildValue("");
@end example

有可能可以使用 SWIG 的 @code{%typemap} 命令以自動進行程式碼變更，雖然我未曾這樣正常運作過（我是一個完全的 SWIG 新手）。

@item 
使用 Python shell 腳本從你的 Windows 應用程式內部建造一個 Python 直譯器視窗不是一個好主意；該視窗將會獨立於你的應用程式視窗系統。與其如此，你（或 wxPythonWindow class）應該要建立一個「本機」直譯器視窗。將該視窗連接到 Python 直譯器是很容易的。你可以將 Python 的 i/o 重定向 (redirect) 到可支援讀取和寫入的任何物件，因此你只需要一個包含 read() 和 write() method 的 Python 物件（在你的擴充模組中被定義）就可以了。
@end enumerate

@node 如何防止編輯器在我的 Python 原始碼中插入 tab？,如何在不阻塞的情況下檢查 keypress？,如何將 Python 嵌入 Windows 應用程式中？,在 Windows 使用 Python 的常見問答集
@anchor{faq/windows how-do-i-keep-editors-from-inserting-tabs-into-my-python-source}@anchor{56e2}
@subsection 如何防止編輯器在我的 Python 原始碼中插入 tab？


FAQ 不建議使用 tab，且 Python 風格指南 
@geindex Python Enhancement Proposals; PEP 8
PEP 8@footnote{https://peps.python.org/pep-0008/} 建議在分散式 Python 程式碼使用 4 個空格；這也是 Emacs 的 python 模式預設值。

在任何編輯器下，將 tab 和空格混合都是一個壞主意。MSVC 在這方面也是一樣，且可以輕鬆配置為使用空格：選擇工具 ‣ 選項 ‣ Tabs，然後對於「預設」檔案類型，將「Tab 大小」和「縮排大小」設定為 4，然後選擇「插入空格」單選鈕。

如果混合 tab 和空格造成前導空白字元出現問題，則 Python 會引發 @ref{9a4,,IndentationError} 或 @ref{75e,,TabError}。你也可以運行 @ref{e3,,tabnanny} 模組，在批次模式下檢查目錄樹。

@node 如何在不阻塞的情況下檢查 keypress？,如何解決遺漏 api-ms-win-crt-runtime-l1-1-0 dll 的錯誤？,如何防止編輯器在我的 Python 原始碼中插入 tab？,在 Windows 使用 Python 的常見問答集
@anchor{faq/windows how-do-i-check-for-a-keypress-without-blocking}@anchor{56e3}
@subsection 如何在不阻塞的情況下檢查 keypress？


使用 @ref{97,,msvcrt} 模組。這是一個標準的 Windows 專用擴充模組。它定義了一個函式 @code{kbhit()}，該函式會檢查是否出現鍵盤打擊 (keyboard hit)，以及函式 @code{getch()}，該函式會取得一個字元且不會將其印出。

@node 如何解決遺漏 api-ms-win-crt-runtime-l1-1-0 dll 的錯誤？,,如何在不阻塞的情況下檢查 keypress？,在 Windows 使用 Python 的常見問答集
@anchor{faq/windows how-do-i-solve-the-missing-api-ms-win-crt-runtime-l1-1-0-dll-error}@anchor{56e4}
@subsection 如何解決遺漏 api-ms-win-crt-runtime-l1-1-0.dll 的錯誤？


使用 Windows 8.1 或更早版本時，若尚未安裝所有的更新，則可能會在 Python 3.5 以上的版本發生這種情況。首先要確保你的作業系統仍受支援並且是最新的，如果這無法解決問題，請造訪  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 圖形使用者介面常見問答集,「為什麼 Python 被安裝在我的機器上？」常見問答集,在 Windows 使用 Python 的常見問答集,Python 常見問題
@anchor{faq/gui doc}@anchor{56e5}@anchor{faq/gui graphic-user-interface-faq}@anchor{56e6}@anchor{faq/gui translation-repo}@anchor{56e7}
@section 圖形使用者介面常見問答集



@c XXX need review for Python 3.

@menu
* 圖形使用者介面 (GUI) 的常見問題: 圖形使用者介面 GUI 的常見問題. 
* Python 有哪些 GUI 套件？:: 
* Tkinter 的問答:: 

@end menu

@node 圖形使用者介面 GUI 的常見問題,Python 有哪些 GUI 套件？,,圖形使用者介面常見問答集
@anchor{faq/gui general-gui-questions}@anchor{56e8}
@subsection 圖形使用者介面 (GUI) 的常見問題


@node Python 有哪些 GUI 套件？,Tkinter 的問答,圖形使用者介面 GUI 的常見問題,圖形使用者介面常見問答集
@anchor{faq/gui what-gui-toolkits-exist-for-python}@anchor{56e9}
@subsection Python 有哪些 GUI 套件？


Python 的標準版本會包含一個 Tcl/Tk 小工具集 (widget set) 的物件導向介面，稱為 @ref{419c,,tkinter}。這可能是最容易安裝（因為它已包含在 Python 的大多數二進制發行版本@footnote{https://www.python.org/downloads/}中）和使用的。有關 Tk 的詳細資訊（包含指向原始碼的指標），請參閱 Tcl/Tk 首頁@footnote{https://www.tcl.tk}。Tcl/Tk 在 macOS、Windows 和 Unix 平台上是完全可攜 (portable) 的。

根據你要使用的平台，還有其他幾種選擇。在 python wiki 上可以找到一份跨平台的@footnote{https://wiki.python.org/moin/GuiProgramming#Cross-Platform_Frameworks}以及各平台專屬的@footnote{https://wiki.python.org/moin/GuiProgramming#Platform-specific_Frameworks} GUI 框架清單。

@node Tkinter 的問答,,Python 有哪些 GUI 套件？,圖形使用者介面常見問答集
@anchor{faq/gui tkinter-questions}@anchor{56ea}
@subsection Tkinter 的問答


@menu
* 如何凍結 Tkinter 應用程式？:: 
* 是否可以在等待 I/O 時處理 Tk 事件？:: 
* 我無法讓鍵繫結 (key binding) 在 Tkinter 中作用：為什麼？: 我無法讓鍵繫結 key binding 在 Tkinter 中作用：為什麼？. 

@end menu

@node 如何凍結 Tkinter 應用程式？,是否可以在等待 I/O 時處理 Tk 事件？,,Tkinter 的問答
@anchor{faq/gui how-do-i-freeze-tkinter-applications}@anchor{56eb}
@subsubsection 如何凍結 Tkinter 應用程式？


凍結 (freeze) 是一個能建立獨立應用程式的工具。在凍結 Tkinter 應用程式時，該應用程式不是真正的獨立，因為該應用程式仍然需要 Tcl 和 Tk 函式庫。

將應用程式與 Tcl 和 Tk 函式庫一併發送是一種解決方法，並在執行環境 (run-time) 使用 @code{TCL_LIBRARY} 和 @code{TK_LIBRARY} 環境變數來指向該函式庫。

各種第三方凍結函式庫，例如 py2exe 和 cx_Freeze，都有內建了對 Tkinter 應用程式的處理。

@node 是否可以在等待 I/O 時處理 Tk 事件？,我無法讓鍵繫結 key binding 在 Tkinter 中作用：為什麼？,如何凍結 Tkinter 應用程式？,Tkinter 的問答
@anchor{faq/gui can-i-have-tk-events-handled-while-waiting-for-i-o}@anchor{56ec}
@subsubsection 是否可以在等待 I/O 時處理 Tk 事件？


在 Windows 以外的平台上是可以的，你甚至不需要執行緒！但是，你必須稍微調整你的 I/O 程式碼。Tk 具有等效於 Xt 的 @code{XtAddInput()} 的函式呼叫，它能讓你記錄一個回呼 (callback) 函式，當 I/O 在一個檔案描述符 (file descriptor) 上可進行時，該函式將會從 Tk mainloop 被呼叫。請參閱@ref{41ba,,檔案處理常式}。

@node 我無法讓鍵繫結 key binding 在 Tkinter 中作用：為什麼？,,是否可以在等待 I/O 時處理 Tk 事件？,Tkinter 的問答
@anchor{faq/gui i-can-t-get-key-bindings-to-work-in-tkinter-why}@anchor{56ed}
@subsubsection 我無法讓鍵繫結 (key binding) 在 Tkinter 中作用：為什麼？


一個經常聽到的抱怨是，儘管事件處理程式 (event handler) 已經@ref{41b5,,繫結}到帶有 @code{bind()} method 的事件，但在按下相應的鍵時，該事件也沒有被處理。

最常見的原因是，繫結到的小工具並沒有「鍵盤焦點 (keyboard focus)」。請查看 Tk 說明文件中關於焦點命令的敘述。通常，點擊一個小工具，會讓它得到鍵盤焦點（但不適用於標籤；請參閱 takefocus 選項）。

@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{faq/installed doc}@anchor{56ee}@anchor{faq/installed translation-repo}@anchor{56ef}@anchor{faq/installed why-is-python-installed-on-my-computer-faq}@anchor{56f0}
@section 「為什麼 Python 被安裝在我的機器上？」常見問答集


@menu
* 什麼是 Python？: 什麼是 Python？<2>. 
* 為什麼 Python 被安裝在我的機器上?:: 
* 我能夠自行刪除 Python 嗎？:: 

@end menu

@node 什麼是 Python？<2>,為什麼 Python 被安裝在我的機器上?,,「為什麼 Python 被安裝在我的機器上？」常見問答集
@anchor{faq/installed what-is-python}@anchor{56f1}
@subsection 什麼是 Python？


Python 是一種程式語言。它被使用於不同種類的應用程式中。因為 Python 屬於容易學習的語言，它在一些高中和大學課程中被用作介紹程式語言的工具；但它也被專業的軟體開發人員所使用，例如 Google、美國太空總署與盧卡斯電影公司。

若你想學習更多關於 Python 的知識，可以先從 Python 初學者指引@footnote{https://wiki.python.org/moin/BeginnersGuide}開始閱讀。

@node 為什麼 Python 被安裝在我的機器上?,我能夠自行刪除 Python 嗎？,什麼是 Python？<2>,「為什麼 Python 被安裝在我的機器上？」常見問答集
@anchor{faq/installed why-is-python-installed-on-my-machine}@anchor{56f2}
@subsection 為什麼 Python 被安裝在我的機器上?


若你發現曾安裝 Python 於系統中，但不記得何時安裝過，那有可能是透過以下幾種途徑安裝的。


@itemize *

@item 
也許其他使用此電腦的使用者想要學習撰寫程式並且安裝了 Python；你需要回想一下誰曾經使用此機器且可能進行安裝。

@item 
安裝於機器的第三方應用程式可能以 Python 語言撰寫並且安裝了 Python。這樣的應用程式並不少，從 GUI 程式到網路伺服器和管理者腳本都有。

@item 
一些安裝 Windows 的機器也被安裝 Python。截至撰寫此文件的當下，我們得知 HP 與 Compaq 出廠的機器都預設安裝 Python。顯然的 HP 與 Compaq 部分的管理工具程式是透過 Python 語言所撰寫。

@item 
許多相容於 Unix 系統，例如 macOS 和一些 Linux 發行版本預設安裝 Python；它被包含在基礎安裝內。
@end itemize

@node 我能夠自行刪除 Python 嗎？,,為什麼 Python 被安裝在我的機器上?,「為什麼 Python 被安裝在我的機器上？」常見問答集
@anchor{faq/installed can-i-delete-python}@anchor{56f3}
@subsection 我能夠自行刪除 Python 嗎？


需要依據 Python 的安裝方式決定。

若有人是有意地安裝 Python，你可自行移除移除它，這不會造成其他影響。Windows 作業系統中，請於控制台 (Control Panel) 中尋找新增/移除程式來解除安裝。

若 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 已棄用項目,術語表,Python 常見問題,Top
@anchor{deprecations/index doc}@anchor{56f4}@anchor{deprecations/index deprecations}@anchor{56f5}@anchor{deprecations/index translation-repo}@anchor{56f6}
@chapter 已棄用項目


@menu
* Python 3.15 中待移除的項目: Python 3 15 中待移除的項目<7>. 
* Python 3.16 中待移除的項目: Python 3 16 中待移除的項目<7>. 
* Python 3.17 中待移除的項目: Python 3 17 中待移除的項目<4>. 
* Python 3.19 中待移除的項目: Python 3 19 中待移除的項目<2>. 
* 未來版本中的待移除項目: 未來版本中的待移除項目<7>. 
* C API 的棄用項目:: 

@end menu

@node Python 3 15 中待移除的項目<7>,Python 3 16 中待移除的項目<7>,,已棄用項目
@anchor{deprecations/index pending-removal-in-python-3-15}@anchor{56f7}
@section Python 3.15 中待移除的項目



@itemize *

@item 
引入系統 (import system)：


@itemize *

@item 
在模組上設定 @ref{320,,__cached__} 而沒有設定 @ref{321,,__spec__.cached} 的做法已被棄用。在 Python 3.15 中，引入系統或標準函式庫將不再設定或考慮 @code{__cached__}。(gh-97879@footnote{https://github.com/python/cpython/issues/97879})

@item 
在模組上設定 @ref{322,,__package__} 而沒有設定 @ref{323,,__spec__.parent} 的做法已被棄用。在 Python 3.15 中，引入系統或標準函式庫將不再設定或考慮 @code{__package__}。(gh-97879@footnote{https://github.com/python/cpython/issues/97879})
@end itemize

@item 
@ref{2e,,ctypes}：


@itemize *

@item 
自 Python 3.13 起，未記錄的 @code{ctypes.SetPointerType()} 函式已被棄用。
@end itemize

@item 
@ref{76,,http.server}：


@itemize *

@item 
過時且很少使用的 @ref{324,,CGIHTTPRequestHandler} 自 Python 3.13 起已被棄用。不存在直接的替代。`任何東西'都比 CGI 更好地將 Web 伺服器與請求處理程序介接起來。

@item 
自 Python 3.13 起，@code{python -m http.server} 命令列介面的 @code{--cgi} 旗標已被棄用。
@end itemize

@item 
@ref{7b,,importlib}：


@itemize *

@item 
@code{load_module()} method：請改用 @code{exec_module()}。
@end itemize

@item 
@ref{8a,,locale}：


@itemize *

@item 
@ref{325,,getdefaultlocale()} 已在 Python 3.11 中被棄用，原本計劃在 Python 3.13 中移除 (gh-90817@footnote{https://github.com/python/cpython/issues/90817})，但被延後至 Python 3.15。請改用 @ref{326,,getlocale()}、@ref{327,,setlocale()} 和 @ref{328,,getencoding()}。 (由 Hugo van Kemenade 於 gh-111187@footnote{https://github.com/python/cpython/issues/111187} 貢獻。)
@end itemize

@item 
@ref{a8,,pathlib}：


@itemize *

@item 
@ref{329,,PurePath.is_reserved()} 已自 Python 3.13 被棄用。請用 @ref{32a,,os.path.isreserved()} 來偵測 Windows 上的保留路徑。
@end itemize

@item 
@ref{af,,platform}：


@itemize *

@item 
自 Python 3.13 起，@ref{32b,,java_ver()} 已被棄用。此函式僅對 Jython 支援有用，具有令人困惑的 API，基本上未經測試。
@end itemize

@item 
@ref{e1,,sysconfig}：


@itemize *

@item 
@ref{32c,,sysconfig.is_python_build()} 的 `check_home' 引數自 Python 3.12 起已被棄用。
@end itemize

@item 
@ref{f3,,threading}：


@itemize *

@item 
@ref{32d,,RLock()} 在 Python 3.15 中將不接受任何引數。自 Python 3.14 起，傳遞任何引數的用法已被棄用，因為 Python 版本不允許任何引數，但 C 版本允許任意數量的位置或關鍵字引數，並忽略每個引數。
@end itemize

@item 
@ref{109,,types}：


@itemize *

@item 
@ref{32e,,types.CodeType}：自 3.10 起，存取 @ref{32f,,co_lnotab} 已在 
@geindex Python Enhancement Proposals; PEP 626
PEP 626@footnote{https://peps.python.org/pep-0626/} 中被棄用，並計劃在 3.12 中移除，但只在 3.12 中於適當時發出 @ref{1a3,,DeprecationWarning}。可能在 3.15 中移除。（由 Nikita Sobolev 於 gh-101866@footnote{https://github.com/python/cpython/issues/101866} 貢獻。）
@end itemize

@item 
@ref{10a,,typing}：


@itemize *

@item 
用於建立 @ref{330,,NamedTuple} 類別的未以文件記錄之關鍵字引數語法 (@code{Point = NamedTuple("Point", x=int, y=int)}) 已自 Python 3.13 棄用。請改用基於類別的語法或函式語法 (functional syntax)。

@item 
當使用 @ref{331,,TypedDict} 的函式語法時，未傳遞值給 `fields' 參數 (@code{TD = TypedDict("TD")}) 或傳遞 @code{None} (@code{TD = TypedDict("TD", None)}) 的做法自 Python 3.13 起已被棄用。請使用 @code{class TD(TypedDict): pass} 或 @code{TD = TypedDict("TD", @{@})} 來建立具有零個欄位的 TypedDict。

@item 
自 Python 3.13 起，@ref{332,,typing.no_type_check_decorator()} 裝飾器函式已被棄用。在 @ref{10a,,typing} 模組中使用了八年之後，它尚未得到任何主要型別檢查器的支援。
@end itemize

@item 
@ref{119,,wave}：


@itemize *

@item 
已棄用 @ref{333,,Wave_read} 和 @ref{334,,Wave_write} 類別的 @ref{335,,getmark()}、@code{setmark()} 和 @ref{336,,getmarkers()} 方法自 Python 3.13 被棄用。
@end itemize

@item 
@ref{138,,zipimport}：


@itemize *

@item 
@ref{337,,load_module()} 自 Python 3.10 被棄用。請改用 @ref{338,,exec_module()}。（由 Jiahao Li 於 gh-125746@footnote{https://github.com/python/cpython/issues/125746} 貢獻。）
@end itemize
@end itemize

@node Python 3 16 中待移除的項目<7>,Python 3 17 中待移除的項目<4>,Python 3 15 中待移除的項目<7>,已棄用項目
@anchor{deprecations/index pending-removal-in-python-3-16}@anchor{56f8}
@section Python 3.16 中待移除的項目



@itemize *

@item 
引入系統 (import system)：


@itemize *

@item 
在模組上設定 @ref{33a,,__loader__} 而沒有設定 @ref{33b,,__spec__.loader} 的做法將於 Python 3.16 被棄用。在 Python 3.16 中，引入系統或標準函式庫將不再設定或考慮 @code{__loader__}。
@end itemize

@item 
@ref{8,,array}：


@itemize *

@item 
自 Python 3.3 起，@code{'u'} 格式碼 (@code{wchar_t}) 在文件中已被棄用，自 Python 3.13 起在 runtime 已被棄用。請使用 @code{'w'} 格式碼 (@ref{33c,,Py_UCS4}) 來取代 Unicode 字元。
@end itemize

@item 
@ref{b,,asyncio}：


@itemize *

@item 
@code{asyncio.iscoroutinefunction()} 已被棄用並將在 Python 3.16 中移除；請改用 @ref{30c,,inspect.iscoroutinefunction()}。（由 Jiahao Li 和 Kumar Aditya 於 gh-122875@footnote{https://github.com/python/cpython/issues/122875} 貢獻。）

@item 
@ref{b,,asyncio} 策略系統已被棄用並將在 Python 3.16 中移除。特別是以下類別和函式已被棄用：


@itemize *

@item 
@ref{30d,,asyncio.AbstractEventLoopPolicy}

@item 
@ref{30e,,asyncio.DefaultEventLoopPolicy}

@item 
@ref{30f,,asyncio.WindowsSelectorEventLoopPolicy}

@item 
@ref{310,,asyncio.WindowsProactorEventLoopPolicy}

@item 
@ref{311,,asyncio.get_event_loop_policy()}

@item 
@ref{312,,asyncio.set_event_loop_policy()}
@end itemize

使用者應該使用 @ref{2f2,,asyncio.run()} 或 @ref{2f4,,asyncio.Runner} 搭配 `loop_factory' 來使用所需的事件迴圈實作。

例如在 Windows 上使用 @ref{313,,asyncio.SelectorEventLoop}：

@example
import asyncio

async def main():
    ...

asyncio.run(main(), loop_factory=asyncio.SelectorEventLoop)
@end example

（由 Kumar Aditya 於 gh-127949@footnote{https://github.com/python/cpython/issues/127949} 貢獻。）
@end itemize

@item 
@ref{13,,builtins}：


@itemize *

@item 
自 Python 3.12 起，布林型別的位元反轉 @code{~True} 或 @code{~False} 已被棄用，因為它會產生不預期且不直觀的結果（@code{-2} 和 @code{-1}）。使用 @code{not x} 代替布林值的邏輯否定。在極少數情況下，你需要對底層的整數進行位元反轉，請明確轉換為 @code{~int(x)} (@code{~int(x)})。
@end itemize

@item 
@ref{63,,functools}：


@itemize *

@item 
自 Python 3.14 起，使用 `function' 或 `sequence' 關鍵字引數呼叫 @ref{21a,,functools.reduce()} 的 Python 實作已被棄用。
@end itemize

@item 
@ref{8b,,logging}：

對具有 `strm' 引數的自訂日誌記錄處理函式的支援已被棄用，並計劃在 Python 3.16 中移除。請改用 `stream' 引數。（由 Mariusz Felisiak 於 gh-115032@footnote{https://github.com/python/cpython/issues/115032} 貢獻。）

@item 
@ref{93,,mimetypes}：


@itemize *

@item 
有效的副檔名以 '.' 開頭或對 @ref{318,,mimetypes.MimeTypes.add_type()} 為空字串。未加點的副檔名已被棄用，並將在 Python 3.16 中引發 @ref{2eb,,ValueError}。（由 Hugo van Kemenade 於 gh-75223@footnote{https://github.com/python/cpython/issues/75223} 貢獻。）
@end itemize

@item 
@ref{ca,,shutil}：


@itemize *

@item 
自 Python 3.14 起，@code{ExecError} 例外已被棄用。自 Python 3.4 以來，它尚未被 @code{shutil} 中的任何函式使用，現在是 @ref{244,,RuntimeError} 的別名。
@end itemize

@item 
@ref{de,,symtable}：


@itemize *

@item 
自 Python 3.14 起，@ref{31c,,Class.get_methods} 方法已被棄用。
@end itemize

@item 
@ref{df,,sys}：


@itemize *

@item 
自 Python 3.13 起，@ref{33d,,_enablelegacywindowsfsencoding()} 函式已被棄用。請改用 
@geindex PYTHONLEGACYWINDOWSFSENCODING
@geindex 環境變數; PYTHONLEGACYWINDOWSFSENCODING
@ref{33e,,PYTHONLEGACYWINDOWSFSENCODING} 環境變數。
@end itemize

@item 
@ref{e1,,sysconfig}：


@itemize *

@item 
自 Python 3.14 起，@code{sysconfig.expand_makefile_vars()} 函式已被棄用。請改用 @ref{33f,,sysconfig.get_paths()} 的 @code{vars} 引數。
@end itemize

@item 
@ref{e4,,tarfile}：


@itemize *

@item 
自 Python 3.13 起，未以文件記錄和未被使用的 @code{TarFile.tarfile} 屬性已被棄用。
@end itemize
@end itemize

@node Python 3 17 中待移除的項目<4>,Python 3 19 中待移除的項目<2>,Python 3 16 中待移除的項目<7>,已棄用項目
@anchor{deprecations/index pending-removal-in-python-3-17}@anchor{56f9}
@section Python 3.17 中待移除的項目



@itemize *

@item 
@ref{1f,,collections.abc}：


@itemize -

@item 
@ref{341,,collections.abc.ByteString} 預計在 Python 3.17 中移除。

使用 @code{isinstance(obj, collections.abc.Buffer)} 來測試 @code{obj} 是否在 runtime 實作了@ref{260,,緩衝區協定}。在型別註解的使用中，請用 @ref{342,,Buffer} 或明確指定你的程式碼所支援型別的聯集（例如 @code{bytes | bytearray | memoryview}）。

@code{ByteString} 最初被設計為一個抽象類別，以作為 @ref{192,,bytes} 和 @ref{343,,bytearray} 的超型別 (supertype)。然而由於 ABC 從未擁有任何方法，知道一個物件是 @code{ByteString} 的實例從未真正告訴你任何關於該物件的有用資訊。其他常見的緩衝區型別如 @ref{165,,memoryview} 也從未被理解為 @code{ByteString} 的子型別（無論是在 runtime 還是由靜態型別檢查器）。

更多細節請見 
@geindex Python Enhancement Proposals; PEP 688#current-options
PEP 688@footnote{https://peps.python.org/pep-0688/#current-options}。（由 Shantanu Jain 於 gh-91896@footnote{https://github.com/python/cpython/issues/91896} 貢獻。）
@end itemize

@item 
@ref{10a,,typing}：


@itemize -

@item 
在 Python 3.14 之前，舊式聯集是使用私有類別 @code{typing._UnionGenericAlias} 實作的。這個類別不再被需要，但為了向後相容性而保留，並計劃將在 Python 3.17 中移除。使用者應該改用文件中記錄的內省輔助函式，例如 @ref{2ab,,typing.get_origin()} 和 @ref{2ac,,typing.get_args()}，或者依賴私有實作細節。

@item 
@ref{344,,typing.ByteString} 自 Python 3.9 起已被棄用，預計在 Python 3.17 中移除。

使用 @code{isinstance(obj, collections.abc.Buffer)} 來測試 @code{obj} 是否在 runtime 實作了@ref{260,,緩衝區協定}。在型別註解的使用中，請用 @ref{342,,Buffer} 或明確指定你的程式碼所支援型別的聯集（例如 @code{bytes | bytearray | memoryview}）。

@code{ByteString} 最初被設計為一個抽象類別，以作為 @ref{192,,bytes} 和 @ref{343,,bytearray} 的超型別 (supertype)。然而由於 ABC 從未擁有任何方法，知道一個物件是 @code{ByteString} 的實例從未真正告訴你任何關於該物件的有用資訊。其他常見的緩衝區型別如 @ref{165,,memoryview} 也從未被理解為 @code{ByteString} 的子型別（無論是在 runtime 還是由靜態型別檢查器）。

更多細節請見 
@geindex Python Enhancement Proposals; PEP 688#current-options
PEP 688@footnote{https://peps.python.org/pep-0688/#current-options}。（由 Shantanu Jain 於 gh-91896@footnote{https://github.com/python/cpython/issues/91896} 貢獻。）
@end itemize
@end itemize

@node Python 3 19 中待移除的項目<2>,未來版本中的待移除項目<7>,Python 3 17 中待移除的項目<4>,已棄用項目
@anchor{deprecations/index pending-removal-in-python-3-19}@anchor{56fa}
@section Python 3.19 中待移除的項目



@itemize *

@item 
@ref{2e,,ctypes}：


@itemize *

@item 
在非 Windows 平台上，透過設定 @ref{316,,_pack_} 而沒有設定 @ref{1e7,,_layout_} 來隱式地切換到與 MSVC 相容的結構佈局。
@end itemize
@end itemize

@node 未來版本中的待移除項目<7>,C API 的棄用項目,Python 3 19 中待移除的項目<2>,已棄用項目
@anchor{deprecations/index pending-removal-in-future-versions}@anchor{56fb}
@section 未來版本中的待移除項目


以下 API 將在未來被移除，雖然目前尚未安排移除日期。


@itemize *

@item 
@ref{7,,argparse}：


@itemize *

@item 
巢狀引數群組和巢狀互斥群組已被棄用。

@item 
將未以文件記錄的關鍵字引數 `prefix_chars' 傳遞給 @ref{2ea,,add_argument_group()} 的做法現在已被棄用。

@item 
@ref{30b,,argparse.FileType} 型別轉換器已被棄用。
@end itemize

@item 
@ref{13,,builtins}：


@itemize *

@item 
產生器：@code{throw(type, exc, tb)} 和 @code{athrow(type, exc, tb)} 簽名已被棄用：請改用 @code{throw(exc)} 和 @code{athrow(exc)}，為單引數簽名。

@item 
目前 Python 接受數值字面值後面立即接關鍵字，例如 @code{0in x}、@code{1or x}、@code{0if 1else 2}。它讓運算式模糊且容易混淆，如 @code{[0x1for x in y]}（可以解釋為 @code{[0x1 for x in y]} 或 @code{[0x1f or x in y]}）。如果數值字面值後立即接 @ref{347,,and}、@ref{17c,,else}、@ref{348,,for}、@ref{181,,if}、@ref{349,,in}、@ref{34a,,is} 和 @ref{34b,,or} 之一的關鍵字，則會引發語法警告。在未來版本中，它將被更改為語法錯誤。(gh-87999@footnote{https://github.com/python/cpython/issues/87999})

@item 
@code{__index__()} 和 @code{__int__()} 方法回傳非 int 型別的支援：這些方法將需要回傳 @ref{19b,,int} 的嚴格子類別實例。

@item 
回傳 @ref{196,,float} 嚴格子類別 @code{__float__()} 方法的支援：這些方法將需要回傳 @ref{196,,float} 的實例。

@item 
回傳 @ref{197,,complex} 嚴格子類別 @code{__complex__()} 方法的支援：這些方法將需要回傳 @ref{197,,complex} 的實例。

@item 
將 @code{int()} 委派給 @code{__trunc__()} 方法。

@item 
在 @ref{197,,complex()} 建構子中將複數作為 `real' 或 `imag' 引數傳遞現在已被棄用；它應該只作為單個位置引數傳遞。 (由 Serhiy Storchaka 於 gh-109218@footnote{https://github.com/python/cpython/issues/109218} 貢獻。)
@end itemize

@item 
@ref{15,,calendar}：@code{calendar.January} 和 @code{calendar.February} 常數已被棄用並被 @ref{34c,,calendar.JANUARY} 和 @ref{34d,,calendar.FEBRUARY} 取代。 (由 Prince Roshan 於 gh-103636@footnote{https://github.com/python/cpython/issues/103636} 貢獻。)

@item 
@ref{1c,,codecs}：請改用 @ref{315,,open()} 而非 @ref{314,,codecs.open()}。(gh-133038@footnote{https://github.com/python/cpython/issues/133038})

@item 
@ref{32f,,codeobject.co_lnotab}：請改用 @ref{34e,,codeobject.co_lines()} 方法。

@item 
@ref{34,,datetime}：


@itemize *

@item 
@ref{34f,,utcnow()}：請改用 @code{datetime.datetime.now(tz=datetime.UTC)}。

@item 
@ref{350,,utcfromtimestamp()}：請改用 @code{datetime.datetime.fromtimestamp(timestamp, tz=datetime.UTC)}。
@end itemize

@item 
@ref{67,,gettext}：複數值必須是整數。

@item 
@ref{7b,,importlib}：


@itemize *

@item 
@ref{351,,cache_from_source()} `debug_override' 參數已被棄用：請改用 `optimization' 參數。
@end itemize

@item 
@ref{7e,,importlib.metadata}：


@itemize *

@item 
@code{EntryPoints} 元組介面。

@item 
回傳值上的隱式 @code{None}。
@end itemize

@item 
@ref{8b,,logging}：自 Python 3.3 起，@code{warn()} 方法已被棄用，請改用 @ref{352,,warning()}。

@item 
@ref{8f,,mailbox}：已棄用 StringIO 輸入和文本模式，請改用 BytesIO 和二進位模式。

@item 
@ref{a5,,os}：在多執行緒行程中呼叫 @ref{353,,os.register_at_fork()}。

@item 
@code{pydoc.ErrorDuringImport}：`exc_info' 參數的元組值已被棄用，請用例外實例。

@item 
@ref{be,,re}：現在對正規表示式中的數值群組參照和群組名稱用了更嚴格的規則。現在只有 ASCII 數碼序列被接受作為數值參照。位元組模式和替換字串中的群組名稱現在只能包含 ASCII 字母、數碼和底線。（由 Serhiy Storchaka 於 gh-91760@footnote{https://github.com/python/cpython/issues/91760} 貢獻。）

@item 
@code{sre_compile}、@code{sre_constants} 和 @code{sre_parse} 模組。

@item 
@ref{ca,,shutil}：@ref{354,,rmtree()} 的 `onerror' 參數在 Python 3.12 中已被棄用；請改用 `onexc' 參數。

@item 
@ref{d5,,ssl} 選項和協定：


@itemize *

@item 
不帶協定引數的 @ref{355,,ssl.SSLContext} 已被棄用。

@item 
@ref{355,,ssl.SSLContext}：@ref{356,,set_npn_protocols()} 和 @code{selected_npn_protocol()} 已被棄用：請改用 ALPN。

@item 
@code{ssl.OP_NO_SSL*} 選項

@item 
@code{ssl.OP_NO_TLS*} 選項

@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{f3,,threading} 方法：


@itemize *

@item 
@code{threading.Condition.notifyAll()}：請用 @ref{357,,notify_all()}。

@item 
@code{threading.Event.isSet()}：請用 @ref{358,,is_set()}。

@item 
@code{threading.Thread.isDaemon()}、@ref{359,,threading.Thread.setDaemon()}：請用 @ref{35a,,threading.Thread.daemon} 屬性。

@item 
@code{threading.Thread.getName()}、@ref{35b,,threading.Thread.setName()}：請用 @ref{2a0,,threading.Thread.name} 屬性。

@item 
@code{threading.currentThread()}：請用 @ref{35c,,threading.current_thread()}。

@item 
@code{threading.activeCount()}：請用 @ref{35d,,threading.active_count()}。
@end itemize

@item 
@ref{35e,,typing.Text} (gh-92332@footnote{https://github.com/python/cpython/issues/92332})。

@item 
內部類別 @code{typing._UnionGenericAlias} 不再用於實作 @ref{2a8,,typing.Union}。為了保持與此私有類別使用者的相容性，直到至少 Python 3.17 都將提供一個相容性 shim。（由 Jelle Zijlstra 於 gh-105499@footnote{https://github.com/python/cpython/issues/105499} 貢獻。）

@item 
@ref{35f,,unittest.IsolatedAsyncioTestCase}：從測試案例中回傳非 @code{None} 的值已被棄用。

@item 
@ref{110,,urllib.parse} 已棄用函式：請改用 @ref{360,,urlparse()}。


@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{11e,,wsgiref}：@code{SimpleHandler.stdout.write()} 不應該進行部分寫入。

@item 
@ref{12b,,xml.etree.ElementTree}：已棄用對 @ref{361,,Element} 的真值測試。在未來版本中，它將始終回傳 @code{True}。請改用明確的 @code{len(elem)} 或 @code{elem is not None} 測試。

@item 
@ref{292,,sys._clear_type_cache()} 已被棄用：請改用 @ref{362,,sys._clear_internal_caches()}。
@end itemize

@node C API 的棄用項目,,未來版本中的待移除項目<7>,已棄用項目
@anchor{deprecations/index c-api-deprecations}@anchor{56fc}
@section C API 的棄用項目


@menu
* Python 3.15 中待移除的項目: Python 3 15 中待移除的項目<8>. 
* Python 3.18 中待移除的項目: Python 3 18 中待移除的項目<3>. 
* 未來版本中的待移除項目: 未來版本中的待移除項目<8>. 

@end menu

@node Python 3 15 中待移除的項目<8>,Python 3 18 中待移除的項目<3>,,C API 的棄用項目
@anchor{deprecations/index id1}@anchor{56fd}
@subsection Python 3.15 中待移除的項目



@itemize *

@item 
@ref{3d9,,PyImport_ImportModuleNoBlock()}：請改用 @ref{3da,,PyImport_ImportModule()}。

@item 
@ref{3db,,PyWeakref_GetObject()} 和 @ref{3dc,,PyWeakref_GET_OBJECT()}：請改用 @ref{3dd,,PyWeakref_GetRef()}。可以使用 pythoncapi-compat 專案@footnote{https://github.com/python/pythoncapi-compat/}來為 Python 3.12 和更早版本取得 @ref{3dd,,PyWeakref_GetRef()}。

@item 
@ref{3de,,Py_UNICODE} 型別與 @code{Py_UNICODE_WIDE} 巨集：請改用 @code{wchar_t}。

@item 
@code{PyUnicode_AsDecodedObject()}：請改用 @ref{3df,,PyCodec_Decode()}。

@item 
@code{PyUnicode_AsDecodedUnicode()}：請改用 @ref{3df,,PyCodec_Decode()}；請注意某些編解碼器（例如 "base64"）可能會回傳非 @ref{169,,str} 的型別，例如 @ref{192,,bytes}。

@item 
@code{PyUnicode_AsEncodedObject()}：請改用 @ref{3e0,,PyCodec_Encode()}。

@item 
@code{PyUnicode_AsEncodedUnicode()}：請改用 @ref{3e0,,PyCodec_Encode()}；請注意某些編解碼器（例如 "base64"）可能會回傳非 @ref{192,,bytes} 的型別，例如 @ref{169,,str}。

@item 
Python 初始化函式，自 Python 3.13 起已被棄用：


@itemize *

@item 
@ref{3e1,,Py_GetPath()}：請改用 @ref{37a,,PyConfig_Get("module_search_paths")} (@ref{3e2,,sys.path})。

@item 
@ref{3e3,,Py_GetPrefix()}：請改用 @ref{37a,,PyConfig_Get("base_prefix")} (@ref{3e4,,sys.base_prefix})。如果需要處理@ref{3e5,,虛擬環境}，請改用 @ref{37a,,PyConfig_Get("prefix")} (@ref{3e6,,sys.prefix})。

@item 
@ref{3e7,,Py_GetExecPrefix()}：請改用 @ref{37a,,PyConfig_Get("base_exec_prefix")} (@ref{3e8,,sys.base_exec_prefix})。如果需要處理@ref{3e5,,虛擬環境}，請改用 @ref{37a,,PyConfig_Get("exec_prefix")} (@ref{3e9,,sys.exec_prefix})。

@item 
@ref{3ea,,Py_GetProgramFullPath()}：請改用 @ref{37a,,PyConfig_Get("executable")} (@ref{3eb,,sys.executable})。

@item 
@ref{3ec,,Py_GetProgramName()}：請改用 @ref{37a,,PyConfig_Get("executable")} (@ref{3eb,,sys.executable})。

@item 
@ref{3ed,,Py_GetPythonHome()}：請改用 @ref{37a,,PyConfig_Get("home")} 或 
@geindex PYTHONHOME
@geindex 環境變數; PYTHONHOME
@ref{3ee,,PYTHONHOME} 環境變數。
@end itemize

pythoncapi-compat 專案@footnote{https://github.com/python/pythoncapi-compat/} 可以用來為 Python 3.13 和更早版本取得 @ref{37a,,PyConfig_Get()}。

@item 
用於配置 Python 初始化的函式，自 Python 3.11 起已被棄用：


@itemize *

@item 
@code{PySys_SetArgvEx()}：請改用 @ref{3ef,,PyConfig.argv}。

@item 
@code{PySys_SetArgv()}：請改用 @ref{3ef,,PyConfig.argv}。

@item 
@code{Py_SetProgramName()}：請改用 @ref{3f0,,PyConfig.program_name}。

@item 
@code{Py_SetPythonHome()}：請改用 @ref{3f1,,PyConfig.home}。

@item 
@ref{3f2,,PySys_ResetWarnOptions()}：請改為清除 @ref{3f3,,sys.warnoptions} 和 @code{warnings.filters}。
@end itemize

應改用帶有 @ref{3f4,,PyConfig} 的 @ref{3f5,,Py_InitializeFromConfig()} API。

@item 
全域配置變數：


@itemize *

@item 
@ref{3f6,,Py_DebugFlag}：請改用 @ref{3f7,,PyConfig.parser_debug} 或 @ref{37a,,PyConfig_Get("parser_debug")}。

@item 
@ref{3f8,,Py_VerboseFlag}：請改用 @ref{3f9,,PyConfig.verbose} 或 @ref{37a,,PyConfig_Get("verbose")}。

@item 
@ref{3fa,,Py_QuietFlag}：請改用 @ref{3fb,,PyConfig.quiet} 或 @ref{37a,,PyConfig_Get("quiet")}。

@item 
@ref{3fc,,Py_InteractiveFlag}：請改用 @ref{3fd,,PyConfig.interactive} 或 @ref{37a,,PyConfig_Get("interactive")}。

@item 
@ref{3fe,,Py_InspectFlag}：請改用 @ref{3ff,,PyConfig.inspect} 或 @ref{37a,,PyConfig_Get("inspect")}。

@item 
@ref{400,,Py_OptimizeFlag}：請改用 @ref{401,,PyConfig.optimization_level} 或 @ref{37a,,PyConfig_Get("optimization_level")}。

@item 
@ref{402,,Py_NoSiteFlag}：請改用 @ref{403,,PyConfig.site_import} 或 @ref{37a,,PyConfig_Get("site_import")}。

@item 
@ref{404,,Py_BytesWarningFlag}：請改用 @ref{405,,PyConfig.bytes_warning} 或 @ref{37a,,PyConfig_Get("bytes_warning")}。

@item 
@ref{406,,Py_FrozenFlag}：請改用 @ref{407,,PyConfig.pathconfig_warnings} 或 @ref{37a,,PyConfig_Get("pathconfig_warnings")}。

@item 
@ref{408,,Py_IgnoreEnvironmentFlag}：請改用 @ref{409,,PyConfig.use_environment} 或 @ref{37a,,PyConfig_Get("use_environment")}。

@item 
@ref{40a,,Py_DontWriteBytecodeFlag}：請改用 @ref{40b,,PyConfig.write_bytecode} 或 @ref{37a,,PyConfig_Get("write_bytecode")}。

@item 
@ref{40c,,Py_NoUserSiteDirectory}：請改用 @ref{40d,,PyConfig.user_site_directory} 或 @ref{37a,,PyConfig_Get("user_site_directory")}。

@item 
@ref{40e,,Py_UnbufferedStdioFlag}：請改用 @ref{40f,,PyConfig.buffered_stdio} 或 @ref{37a,,PyConfig_Get("buffered_stdio")}。

@item 
@ref{410,,Py_HashRandomizationFlag}：請改用 @ref{411,,PyConfig.use_hash_seed} 和 @ref{412,,PyConfig.hash_seed} 或 @ref{37a,,PyConfig_Get("hash_seed")}。

@item 
@ref{413,,Py_IsolatedFlag}：請改用 @ref{414,,PyConfig.isolated} 或 @ref{37a,,PyConfig_Get("isolated")}。

@item 
@ref{415,,Py_LegacyWindowsFSEncodingFlag}：請改用 @ref{416,,PyPreConfig.legacy_windows_fs_encoding} 或 @ref{37a,,PyConfig_Get("legacy_windows_fs_encoding")}。

@item 
@ref{417,,Py_LegacyWindowsStdioFlag}：請改用 @ref{418,,PyConfig.legacy_windows_stdio} 或 @ref{37a,,PyConfig_Get("legacy_windows_stdio")}。

@item 
@code{Py_FileSystemDefaultEncoding}、@code{Py_HasFileSystemDefaultEncoding}：請改用 @ref{419,,PyConfig.filesystem_encoding} 或 @ref{37a,,PyConfig_Get("filesystem_encoding")}。

@item 
@code{Py_FileSystemDefaultEncodeErrors}：請改用 @ref{41a,,PyConfig.filesystem_errors} 或 @ref{37a,,PyConfig_Get("filesystem_errors")}。

@item 
@code{Py_UTF8Mode}：請改用 @ref{41b,,PyPreConfig.utf8_mode} 或 @ref{37a,,PyConfig_Get("utf8_mode")}。（請參閱 @ref{41c,,Py_PreInitialize()}）
@end itemize

應改用帶有 @ref{3f4,,PyConfig} 的 @ref{3f5,,Py_InitializeFromConfig()} API 來設定這些選項。或者也可以使用 @ref{37a,,PyConfig_Get()} 在執行時取得這些選項。
@end itemize

@node Python 3 18 中待移除的項目<3>,未來版本中的待移除項目<8>,Python 3 15 中待移除的項目<8>,C API 的棄用項目
@anchor{deprecations/index pending-removal-in-python-3-18}@anchor{56fe}
@subsection Python 3.18 中待移除的項目



@itemize *

@item 
以下私有函式已被棄用，並計劃在 Python 3.18 中移除：


@itemize *

@item 
@code{_PyBytes_Join()}：請改用 @ref{381,,PyBytes_Join()}。

@item 
@code{_PyDict_GetItemStringWithError()}：請改用 @ref{41f,,PyDict_GetItemStringRef()}。

@item 
@code{_PyDict_Pop()}：請改用 @ref{420,,PyDict_Pop()}。

@item 
@code{_PyLong_Sign()}：請改用 @ref{398,,PyLong_GetSign()}。

@item 
@code{_PyLong_FromDigits()} 和 @code{_PyLong_New()}：請改用 @ref{3a8,,PyLongWriter_Create()}。

@item 
@code{_PyThreadState_UncheckedGet()}：請改用 @ref{421,,PyThreadState_GetUnchecked()}。

@item 
@code{_PyUnicode_AsString()}：請改用 @ref{422,,PyUnicode_AsUTF8()}。

@item 
@code{_PyUnicodeWriter_Init()}：將 @code{_PyUnicodeWriter_Init(&writer)} 替換為 @ref{3b2,,writer = PyUnicodeWriter_Create(0)}。

@item 
@code{_PyUnicodeWriter_Finish()}：將 @code{_PyUnicodeWriter_Finish(&writer)} 替換為 @ref{3b5,,PyUnicodeWriter_Finish(writer)}。

@item 
@code{_PyUnicodeWriter_Dealloc()}：將 @code{_PyUnicodeWriter_Dealloc(&writer)} 替換為 @ref{3b4,,PyUnicodeWriter_Discard(writer)}。

@item 
@code{_PyUnicodeWriter_WriteChar()}：將 @code{_PyUnicodeWriter_WriteChar(&writer, ch)} 替換為 @ref{3b8,,PyUnicodeWriter_WriteChar(writer@comma{} ch)}。

@item 
@code{_PyUnicodeWriter_WriteStr()}：將 @code{_PyUnicodeWriter_WriteStr(&writer, str)} 替換為 @ref{3ba,,PyUnicodeWriter_WriteStr(writer@comma{} str)}。

@item 
@code{_PyUnicodeWriter_WriteSubstring()}：將 @code{_PyUnicodeWriter_WriteSubstring(&writer, str, start, end)} 替換為 @ref{3bb,,PyUnicodeWriter_WriteSubstring(writer@comma{} str@comma{} start@comma{} end)}。

@item 
@code{_PyUnicodeWriter_WriteASCIIString()}：將 @code{_PyUnicodeWriter_WriteASCIIString(&writer, str)} 替換為 @ref{3b7,,PyUnicodeWriter_WriteASCII(writer@comma{} str)}。

@item 
@code{_PyUnicodeWriter_WriteLatin1String()}：將 @code{_PyUnicodeWriter_WriteLatin1String(&writer, str)} 替換為 @ref{3bd,,PyUnicodeWriter_WriteUTF8(writer@comma{} str)}。

@item 
@code{_PyUnicodeWriter_Prepare()}：（無替代方案）。

@item 
@code{_PyUnicodeWriter_PrepareKind()}：（無替代方案）。

@item 
@code{_Py_HashPointer()}：請改用 @ref{423,,Py_HashPointer()}。

@item 
@code{_Py_fopen_obj()}：請改用 @ref{391,,Py_fopen()}。
@end itemize

可以使用 pythoncapi-compat project@footnote{https://github.com/python/pythoncapi-compat/} 來取得這些於 Python 3.13 及更早版本的新公開函式。（由 Victor Stinner 在 gh-128863@footnote{https://github.com/python/cpython/issues/128863} 貢獻）
@end itemize

@node 未來版本中的待移除項目<8>,,Python 3 18 中待移除的項目<3>,C API 的棄用項目
@anchor{deprecations/index id2}@anchor{56ff}
@subsection 未來版本中的待移除項目


下列 API 已被棄用並將會被移除，不過目前尚未訂定移除日期。


@itemize *

@item 
@ref{425,,Py_TPFLAGS_HAVE_FINALIZE}：自 Python 3.8 起不再需要

@item 
@ref{426,,PyErr_Fetch()}：請改用 @ref{427,,PyErr_GetRaisedException()}。

@item 
@ref{428,,PyErr_NormalizeException()}：請改用 @ref{427,,PyErr_GetRaisedException()}。

@item 
@ref{429,,PyErr_Restore()}：請改用 @ref{42a,,PyErr_SetRaisedException()}。

@item 
@ref{42b,,PyModule_GetFilename()}：請改用 @ref{42c,,PyModule_GetFilenameObject()}。

@item 
@ref{42d,,PyOS_AfterFork()}：請改用 @ref{42e,,PyOS_AfterFork_Child()}。

@item 
@ref{42f,,PySlice_GetIndicesEx()}：請改用 @ref{430,,PySlice_Unpack()} 和 @ref{431,,PySlice_AdjustIndices()}。

@item 
@ref{432,,PyUnicode_READY()}：自 Python 3.12 起不再需要

@item 
@code{PyErr_Display()}：請改用 @ref{433,,PyErr_DisplayException()}。

@item 
@code{_PyErr_ChainExceptions()}：請改用 @code{_PyErr_ChainExceptions1}。

@item 
@code{PyBytesObject.ob_shash} 成員：請改為呼叫 @ref{434,,PyObject_Hash()}。

@item 
執行緒局部儲存 (Thread Local Storage, TLS) API：


@itemize *

@item 
@ref{435,,PyThread_create_key()}：請改用 @ref{436,,PyThread_tss_alloc()}。

@item 
@ref{437,,PyThread_delete_key()}：請改用 @ref{438,,PyThread_tss_free()}。

@item 
@ref{439,,PyThread_set_key_value()}：請改用 @ref{43a,,PyThread_tss_set()}。

@item 
@ref{43b,,PyThread_get_key_value()}：請改用 @ref{43c,,PyThread_tss_get()}。

@item 
@ref{43d,,PyThread_delete_key_value()}：請改用 @ref{43e,,PyThread_tss_delete()}。

@item 
@ref{43f,,PyThread_ReInitTLS()}：自 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 術語表,關於這份說明文件,已棄用項目,Top
@anchor{glossary doc}@anchor{5700}@anchor{glossary glossary}@anchor{1e86}@anchor{glossary id1}@anchor{5701}@anchor{glossary translation-repo}@anchor{5702}
@chapter 術語表


@c if you add new entries, keep the alphabetical sorting!


@table @asis
@anchor{glossary term-0}@anchor{48d}
@geindex >>>

@item @code{>>>}

@ref{1b5,,互動式} shell 的預設 Python 提示字元。常見於能在直譯器中以互動方式被執行的程式碼範例。
@anchor{glossary term-}@anchor{48e}
@geindex ...

@item @code{...}

可以表示：


@itemize *

@item 
在一個被縮排的程式碼區塊、在一對匹配的左右定界符（delimiter，例如括號、方括號、花括號或三引號）內部，或是在指定一個裝飾器 (decorator) 之後，要輸入程式碼時，@ref{1b5,,互動式} shell 顯示的預設 Python 提示字元。
@end itemize

@geindex ...;刪節號字面值


@itemize *

@item 
The three dots form of the @ref{1ec5,,Ellipsis} object.
@end itemize
@anchor{glossary term-abstract-base-class}@anchor{13b7}
@geindex abstract base class（抽象基底類別）

@item abstract base class（抽象基底類別）

抽象基底類別（又稱為 ABC）提供了一種定義介面的方法，作為 @ref{5703,,duck-typing}（鴨子型別）的補充。其他類似的技術，像是 @ref{6f2,,hasattr()}，則顯得笨拙或是帶有細微的錯誤（例如使用@ref{2263,,魔術方法 (magic method)}）。ABC 採用虛擬的 subclass（子類別），它們並不繼承自另一個 class（類別），但仍可被 @ref{2ad,,isinstance()} 及 @ref{9bd,,issubclass()} 辨識；請參閱 @ref{4,,abc} 模組的說明文件。Python 有許多內建的 ABC，用於資料結構（在 @ref{1f,,collections.abc} 模組）、數字（在 @ref{a2,,numbers} 模組）、串流（在 @ref{83,,io} 模組）及 import 尋檢器和載入器（在 @ref{7c,,importlib.abc} 模組）。你可以使用 @ref{4,,abc} 模組建立自己的 ABC。
@anchor{glossary term-annotate-function}@anchor{15d}
@geindex annotate function（註釋函式）

@item annotate function（註釋函式）

A function that can be called to retrieve the @ref{15c,,annotations}
of an object. This function is accessible as the @ref{18df,,__annotate__}
attribute of functions, classes, and modules. Annotate functions are a
subset of @ref{43a7,,evaluate functions}.
@anchor{glossary term-annotation}@anchor{15c}
@geindex annotation（註釋）

@item annotation（註釋）

一個與變數、class 屬性、函式的參數或回傳值相關聯的標籤。照慣例，它被用來作為 @ref{227d,,type hint}（型別提示）。

在 runtime 的區域變數註釋無法被存取，但全域變數、類別屬性和函式的註釋，分別能夠以對模組、類別和函式呼叫 @ref{457,,annotationlib.get_annotations()} 來取得。

請參閱 @ref{f4c,,variable annotation}、@ref{1ee2,,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{9d2,,註釋 (annotation) 最佳實踐}。
@anchor{glossary term-argument}@anchor{673}
@geindex argument（引數）

@item argument（引數）

呼叫函式時被傳遞給 @ref{235d,,function}（或 @ref{17e2,,method}）的值。引數有兩種：


@itemize *

@item 
`關鍵字引數 (keyword argument)'：在函式呼叫中，以識別字（identifier，例如 @code{name=}）開頭的引數，或是以 @code{**} 後面 dictionary（字典）內的值被傳遞的引數。例如，@code{3} 和 @code{5} 都是以下 @ref{197,,complex()} 呼叫中的關鍵字引數：

@example
complex(real=3, imag=5)
complex(**@{'real': 3, 'imag': 5@})
@end example

@item 
`位置引數 (positional argument)'：不是關鍵字引數的引數。位置引數可在一個引數列表的起始處出現，和（或）作為 @code{*} 之後的 @ref{1428,,iterable}（可疊代物件）中的元素被傳遞。例如，@code{3} 和 @code{5} 都是以下呼叫中的位置引數：

@example
complex(3, 5)
complex(*(3, 5))
@end example
@end itemize

引數會被指定給函式主體中的附名區域變數。關於支配這個指定過程的規則，請參閱@ref{f78,,Calls}章節。在語法上，任何運算式都可以被用來表示一個引數；其評估值會被指定給區域變數。

另請參閱術語表的 @ref{21fd,,parameter}（參數）條目、常見問題中的@ref{563e,,引數和參數之間的差異}，以及 
@geindex Python Enhancement Proposals; PEP 362
PEP 362@footnote{https://peps.python.org/pep-0362/}。
@anchor{glossary term-asynchronous-context-manager}@anchor{7e8}
@geindex asynchronous context manager（非同步情境管理器）

@item asynchronous context manager（非同步情境管理器）

一個可以控制 @ref{185,,async with} 陳述式中所見環境的物件，而它是透過定義 @ref{22cd,,__aenter__()} 和 @ref{18f8,,__aexit__()} method（方法）來控制的。由 
@geindex Python Enhancement Proposals; PEP 492
PEP 492@footnote{https://peps.python.org/pep-0492/} 引入。
@anchor{glossary term-asynchronous-generator}@anchor{2342}
@geindex asynchronous generator（非同步產生器）

@item asynchronous generator（非同步產生器）

一個會回傳 @ref{47d1,,asynchronous generator iterator}（非同步產生器疊代器）的函式。它看起來像一個以 @ref{7e6,,async def} 定義的協程函式 (coroutine function)，但不同的是它包含了 @ref{bb9,,yield} 運算式，能生成一系列可用於 @ref{c98,,async for} 迴圈的值。

這個術語通常用來表示一個非同步產生器函式，但在某些情境中，也可能是表示`非同步產生器疊代器 (asynchronous generator iterator)'。萬一想表達的意思不夠清楚，那就使用完整的術語，以避免歧義。

一個非同步產生器函式可能包含 @ref{18d,,await} 運算式，以及 @ref{c98,,async for} 和 @ref{185,,async with} 陳述式。
@anchor{glossary term-asynchronous-generator-iterator}@anchor{47d1}
@geindex asynchronous generator iterator（非同步產生器疊代器）

@item asynchronous generator iterator（非同步產生器疊代器）

一個由 @ref{2342,,asynchronous generator}（非同步產生器）函式所建立的物件。

這是一個 @ref{4c2,,asynchronous iterator}（非同步疊代器），當它以 @ref{17fd,,__anext__()} method 被呼叫時，會回傳一個可等待物件 (awaitable object)，該物件將執行非同步產生器的函式主體，直到遇到下一個 @ref{bb9,,yield} 運算式。

每個 @ref{bb9,,yield} 會暫停處理程序，並記住執行狀態（包括區域變數及擱置中的 try 陳述式）。當`非同步產生器疊代器'以另一個被 @ref{17fd,,__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{f6f}
@geindex asynchronous iterable（非同步可疊代物件）

@item asynchronous iterable（非同步可疊代物件）

一個物件，它可以在 @ref{c98,,async for} 陳述式中被使用。必須從它的 @ref{df1,,__aiter__()} method 回傳一個 @ref{4c2,,asynchronous iterator}（非同步疊代器）。由 
@geindex Python Enhancement Proposals; PEP 492
PEP 492@footnote{https://peps.python.org/pep-0492/} 引入。
@anchor{glossary term-asynchronous-iterator}@anchor{4c2}
@geindex asynchronous iterator（非同步疊代器）

@item asynchronous iterator（非同步疊代器）

一個實作 @ref{df1,,__aiter__()} 和 @ref{17fd,,__anext__()} method 的物件。@ref{17fd,,__anext__()} 必須回傳一個 @ref{4c4,,awaitable}（可等待物件）。@ref{c98,,async for} 會解析非同步疊代器的 @ref{17fd,,__anext__()} method 所回傳的可等待物件，直到它引發 @ref{1cd7,,StopAsyncIteration} 例外。由 
@geindex Python Enhancement Proposals; PEP 492
PEP 492@footnote{https://peps.python.org/pep-0492/} 引入。
@anchor{glossary term-attached-thread-state}@anchor{4d99}
@geindex attached thread state

@item attached thread state

A @ref{17c4,,thread state} that is active for the current OS thread.

When a @ref{17c4,,thread state} is attached, the OS thread has
access to the full Python C API and can safely invoke the
bytecode interpreter.

Unless a function explicitly notes otherwise, attempting to call
the C API without an attached thread state will result in a fatal
error or undefined behavior.  A thread state can be attached and detached
explicitly by the user through the C API, or implicitly by the runtime,
including during blocking C calls and by the bytecode interpreter in between
calls.

On most builds of Python, having an attached thread state implies that the
caller holds the @ref{164,,GIL} for the current interpreter, so only
one OS thread can have an attached thread state at a given moment. In
@ref{1f4,,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{27ba}
@geindex attribute（屬性）

@item attribute（屬性）

一個與某物件相關聯的值，該值大多能透過使用點分隔運算式 (dotted expression) 的名稱被參照。例如，如果物件 `o' 有一個屬性 `a'，則該屬性能以 `o.a' 被參照。

如果一個物件允許，給予該物件一個名稱不是由@ref{2164,,Names (identifiers and keywords)}所定義之識別符 (identifier) 的屬性是有可能的，例如使用 @ref{2467,,setattr()}。像這樣的屬性將無法使用點分隔運算式來存取，而是需要使用 @ref{dc5,,getattr()} 來取得它。
@anchor{glossary term-awaitable}@anchor{4c4}
@geindex awaitable（可等待物件）

@item awaitable（可等待物件）

一個可以在 @ref{18d,,await} 運算式中被使用的物件。它可以是一個 @ref{6b2,,coroutine}（協程），或是一個有 @ref{f70,,__await__()} method 的物件。另請參閱 
@geindex Python Enhancement Proposals; PEP 492
PEP 492@footnote{https://peps.python.org/pep-0492/}。
@anchor{glossary term-BDFL}@anchor{5704}
@geindex BDFL

@item BDFL

Benevolent Dictator For Life（終身仁慈獨裁者），又名 Guido van Rossum@footnote{https://gvanrossum.github.io/}，Python 的創造者。
@anchor{glossary term-binary-file}@anchor{1f35}
@geindex binary file（二進位檔案）

@item binary file（二進位檔案）

一個能夠讀取和寫入 @ref{193,,bytes-like objects}（類位元組串物件）的 @ref{13c4,,file object}（檔案物件）。二進位檔案的例子有：以二進位模式（@code{'rb'}、@code{'wb'} 或 @code{'rb+'}）開啟的檔案、@ref{758,,sys.stdin.buffer}、@ref{cc4,,sys.stdout.buffer}，以及 @ref{109f,,io.BytesIO} 和 @ref{654,,gzip.GzipFile} 實例。

另請參閱 @ref{1f34,,text file}（文字檔案），它是一個能夠讀取和寫入 @ref{169,,str} 物件的檔案物件。
@anchor{glossary term-borrowed-reference}@anchor{3d5}
@geindex borrowed reference（借用參照）

@item borrowed reference（借用參照）

在 Python 的 C API 中，借用參照是一個對物件的參照，其中使用該物件的程式碼並不擁有這個參照。如果該物件被銷毀，它會成為一個迷途指標 (dangling pointer)。例如，一次垃圾回收 (garbage collection) 可以移除對物件的最後一個 @ref{5da,,strong reference}（強參照），而將該物件銷毀。

對 @ref{3d5,,borrowed reference} 呼叫 @ref{788,,Py_INCREF()} 以將它原地 (in-place) 轉換為 @ref{5da,,strong reference} 是被建議的做法，除非該物件不能在最後一次使用借用參照之前被銷毀。@ref{a91,,Py_NewRef()} 函式可用於建立一個新的 @ref{5da,,strong reference}。
@anchor{glossary term-bytes-like-object}@anchor{193}
@geindex bytes-like object（類位元組串物件）

@item bytes-like object（類位元組串物件）

一個支援@ref{260,,緩衝協定 (Buffer Protocol)}且能夠匯出 C-@ref{2535,,contiguous} 緩衝區的物件。這包括所有的 @ref{192,,bytes}、@ref{343,,bytearray} 和 @ref{4b9,,array.array} 物件，以及許多常見的 @ref{165,,memoryview} 物件。類位元組串物件可用於處理二進位資料的各種運算；這些運算包括壓縮、儲存至二進位檔案和透過 socket（插座）發送。

有些運算需要二進位資料是可變的。說明文件通常會將這些物件稱為「可讀寫的類位元組串物件」。可變緩衝區的物件包括 @ref{343,,bytearray}，以及 @ref{343,,bytearray} 的 @ref{165,,memoryview}。其他的運算需要讓二進位資料被儲存在不可變物件（「唯讀的類位元組串物件」）中；這些物件包括 @ref{192,,bytes}，以及 @ref{192,,bytes} 物件的 @ref{165,,memoryview}。
@anchor{glossary term-bytecode}@anchor{4a5}
@geindex bytecode（位元組碼）

@item bytecode（位元組碼）

Python 的原始碼會被編譯成位元組碼，它是 Python 程式在 CPython 直譯器中的內部表示法。該位元組碼也會被暫存在 @code{.pyc} 檔案中，以便第二次執行同一個檔案時能夠更快速（可以不用從原始碼重新編譯為位元組碼）。這種「中間語言 (intermediate language)」據說是運行在一個 @ref{3911,,virtual machine}（虛擬機器）上，該虛擬機器會執行與每個位元組碼對應的機器碼 (machine code)。要注意的是，位元組碼理論上是無法在不同的 Python 虛擬機器之間運作的，也不能在不同版本的 Python 之間保持穩定。

位元組碼的指令列表可以在 @ref{7c8,,dis 模組}的說明文件中找到。
@anchor{glossary term-callable}@anchor{2c2e}
@geindex callable（可呼叫物件）

@item callable（可呼叫物件）

一個 callable 是可以被呼叫的物件，呼叫時可能以下列形式帶有一組引數（請見 @ref{673,,argument}）：

@example
callable(argument1, argument2, argumentN)
@end example

一個 @ref{235d,,function} 與其延伸的 @ref{17e2,,method} 都是 callable。一個有實作 @ref{773,,__call__()} 方法的 class 之實例也是個 callable。
@anchor{glossary term-callback}@anchor{2c4f}
@geindex callback（回呼）

@item callback（回呼）

作為引數被傳遞的一個副程式 (subroutine) 函式，會在未來的某個時間點被執行。
@anchor{glossary term-class}@anchor{1be7}
@geindex class（類別）

@item class（類別）

一個用於建立使用者定義物件的模板。Class 的定義通常會包含 method 的定義，這些 method 可以在 class 的實例上進行操作。
@anchor{glossary term-class-variable}@anchor{5705}
@geindex class variable（類別變數）

@item class variable（類別變數）

一個在 class 中被定義，且應該只能在 class 層次（意即不是在 class 的實例中）被修改的變數。
@anchor{glossary term-closure-variable}@anchor{180c}
@geindex closure variable（閉包變數）

@item closure variable（閉包變數）

從外部作用域中定義且從@ref{223e,,巢狀作用域}參照的@ref{22d8,,自由變數}，不是於 runtime 從全域或內建命名空間解析。可以使用 @ref{14a8,,nonlocal} 關鍵字明確定義以允許寫入存取，或者如果僅需讀取變數則隱式定義即可。

例如在下面程式碼中的 @code{inner} 函式中，@code{x} 和 @code{print} 都是@ref{22d8,,自由變數}，但只有 @code{x} 是`閉包變數'：

@example
def outer():
    x = 0
    def inner():
        nonlocal x
        x += 1
        print(x)
    return inner
@end example

由於 @ref{21f9,,codeobject.co_freevars} 屬性（儘管名稱如此，但它僅包含閉包變數的名稱，而不是列出所有參照的自由變數），當預期含義是特指閉包變數時，有時候甚至也會使用更通用的@ref{22d8,,自由變數}一詞。
@anchor{glossary term-complex-number}@anchor{5706}
@geindex complex number（複數）

@item complex number（複數）

一個我們熟悉的實數系統的擴充，在此所有數字都會被表示為一個實部和一個虛部之和。虛數就是虛數單位（@code{-1} 的平方根）的實數倍，此單位通常在數學中被寫為 @code{i}，在工程學中被寫為 @code{j}。Python 內建了對複數的支援，它是用後者的記法來表示複數；虛部會帶著一個後綴的 @code{j} 被編寫，例如 @code{3+1j}。若要將 @ref{92,,math} 模組內的工具等效地用於複數，請使用 @ref{19,,cmath} 模組。複數的使用是一個相當進階的數學功能。如果你沒有察覺到對它們的需求，那麼幾乎能確定你可以安全地忽略它們。
@anchor{glossary term-context}@anchor{18ca}
@geindex context（情境）

@item context（情境）

This term has different meanings depending on where and how it is used.
Some common meanings:


@itemize *

@item 
The temporary state or environment established by a @ref{1e1,,context manager} via a @ref{186,,with} statement.

@item 
The collection of key­value bindings associated with a particular
@ref{177,,contextvars.Context} object and accessed via
@ref{17f0,,ContextVar} objects.  Also see @ref{5707,,context variable}.

@item 
一個 @ref{177,,contextvars.Context} 物件。另請參閱 @ref{18cb,,current context}。
@end itemize
@anchor{glossary term-context-management-protocol}@anchor{18cc}
@geindex context management protocol（情境管理協定）

@item context management protocol（情境管理協定）

由 @ref{186,,with} 陳述式所呼叫的 @ref{7dd,,__enter__()} 和 @ref{1501,,__exit__()} 方法。另請參閱 
@geindex Python Enhancement Proposals; PEP 343
PEP 343@footnote{https://peps.python.org/pep-0343/}。
@anchor{glossary term-context-manager}@anchor{1e1}
@geindex context manager（情境管理器）

@item context manager（情境管理器）

An object which implements the @ref{18cc,,context management protocol} and
controls the environment seen in a @ref{186,,with} statement.  See
@geindex Python Enhancement Proposals; PEP 343
PEP 343@footnote{https://peps.python.org/pep-0343/}.
@anchor{glossary term-context-variable}@anchor{5707}
@geindex context variable（情境變數）

@item context variable（情境變數）

A variable whose value depends on which context is the @ref{18cb,,current context}.  Values are accessed via @ref{17f0,,contextvars.ContextVar}
objects.  Context variables are primarily used to isolate state between
concurrent asynchronous tasks.
@anchor{glossary term-contiguous}@anchor{2535}
@geindex contiguous（連續的）

@item contiguous（連續的）

@geindex C-contiguous（C 連續的）
@geindex Fortran contiguous（Fortran 連續的）

如果一個緩衝區是 `C-contiguous' 或是 `Fortran contiguous'，則它會確切地被視為是連續的。零維 (zero-dimensional) 的緩衝區都是 C 及 Fortran contiguous。在一維 (one-dimensional) 陣列中，各項目必須在記憶體中彼此相鄰地排列，而其索引順序是從零開始遞增。在多維的 (multidimensional) C-contiguous 陣列中，按記憶體位址的順序瀏覽各個項目時，最後一個索引的變化最快。然而，在 Fortran contiguous 陣列中，第一個索引的變化最快。
@anchor{glossary term-coroutine}@anchor{6b2}
@geindex coroutine（協程）

@item coroutine（協程）

協程是副程式 (subroutine) 的一種更為廣義的形式。副程式是在某個時間點被進入並在另一個時間點被退出。協程可以在許多不同的時間點被進入、退出和回復。它們能夠以 @ref{7e6,,async def} 陳述式被實作。另請參閱 
@geindex Python Enhancement Proposals; PEP 492
PEP 492@footnote{https://peps.python.org/pep-0492/}。
@anchor{glossary term-coroutine-function}@anchor{f6e}
@geindex coroutine function（協程函式）

@item coroutine function（協程函式）

一個回傳 @ref{6b2,,coroutine}（協程）物件的函式。一個協程函式能以 @ref{7e6,,async def} 陳述式被定義，並可能會包含 @ref{18d,,await}、@ref{c98,,async for} 和 @ref{185,,async with} 關鍵字。這些關鍵字由 
@geindex Python Enhancement Proposals; PEP 492
PEP 492@footnote{https://peps.python.org/pep-0492/} 引入。
@anchor{glossary term-CPython}@anchor{8fd}
@geindex CPython

@item CPython

Python 程式語言的標準實作 (canonical implementation)，被發布在 python.org@footnote{https://www.python.org} 上。「CPython」這個術語在必要時被使用，以區分此實作與其它語言的實作，例如 Jython 或 IronPython。
@anchor{glossary term-current-context}@anchor{18cb}
@geindex current context

@item current context

The @ref{18ca,,context} (@ref{177,,contextvars.Context} object) that is
currently used by @ref{17f0,,ContextVar} objects to access (get
or set) the values of @ref{5707,,context variables}.  Each
thread has its own current context.  Frameworks for executing asynchronous
tasks (see @ref{b,,asyncio}) associate each task with a context which
becomes the current context whenever the task starts or resumes execution.
@anchor{glossary term-cyclic-isolate}@anchor{535b}
@geindex cyclic isolate

@item cyclic isolate

A subgroup of one or more objects that reference each other in a reference
cycle, but are not referenced by objects outside the group.  The goal of
the @ref{1765,,cyclic garbage collector} is to identify these groups and break the reference
cycles so that the memory can be reclaimed.
@anchor{glossary term-decorator}@anchor{932}
@geindex decorator（裝飾器）

@item decorator（裝飾器）

一個函式，它會回傳另一個函式，通常它會使用 @code{@@wrapper} 語法，被應用為一種函式的變換 (function transformation)。裝飾器的常見範例是 @ref{489,,classmethod()} 和 @ref{451,,staticmethod()}。

裝飾器語法只是語法糖。以下兩個函式定義在語義上是等效的：

@example
def f(arg):
    ...
f = staticmethod(f)

@@staticmethod
def f(arg):
    ...
@end example

Class 也存在相同的概念，但在那裡比較不常用。關於裝飾器的更多內容，請參閱@ref{1ee1,,函式定義}和 @ref{14d8,,class 定義}的說明文件。
@anchor{glossary term-descriptor}@anchor{17fc}
@geindex descriptor（描述器）

@item descriptor（描述器）

任何定義了 @ref{16dc,,__get__()}、@ref{2267,,__set__()} 或 @ref{18b6,,__delete__()} method 的物件。當一個 class 屬性是一個描述器時，它的特殊連結行為會在屬性查找時被觸發。通常，使用 `a.b' 來取得、設定或刪除某個屬性時，會在 `a' 的 class 字典中查找名稱為 `b' 的物件，但如果 `b' 是一個描述器，則相對應的描述器 method 會被呼叫。對描述器的理解是深入理解 Python 的關鍵，因為它們是許多功能的基礎，這些功能包括函式、method、屬性 (property)、class method、靜態 method，以及對 super class（父類別）的參照。

關於描述器 method 的更多資訊，請參閱@ref{e44,,實作描述器}或@ref{16e1,,描述器使用指南}。
@anchor{glossary term-dictionary}@anchor{2287}
@geindex dictionary（字典）

@item dictionary（字典）

一個關聯陣列 (associative array)，其中任意的鍵會被對映到值。鍵可以是任何帶有 @ref{cea,,__hash__()} 和 @ref{ce9,,__eq__()} method 的物件。在 Perl 中被稱為雜湊 (hash)。
@anchor{glossary term-dictionary-comprehension}@anchor{5708}
@geindex dictionary comprehension（字典綜合運算）

@item dictionary comprehension（字典綜合運算）

一種緊密的方法，用來處理一個可疊代物件中的全部或部分元素，並將處理結果以一個字典回傳。@code{results = @{n: n ** 2 for n in range(10)@}} 會產生一個字典，它包含了鍵 @code{n} 對映到值 @code{n ** 2}。請參閱@ref{7e5,,Displays for lists@comma{} sets and dictionaries}。
@anchor{glossary term-dictionary-view}@anchor{283d}
@geindex dictionary view（字典檢視）

@item dictionary view（字典檢視）

從 @ref{9c9,,dict.keys()}、@ref{9ca,,dict.values()} 及 @ref{9cb,,dict.items()} 回傳的物件被稱為字典檢視。它們提供了字典中項目的動態檢視，這表示當字典有變動時，該檢視會反映這些變動。若要強制將字典檢視轉為完整的 list（串列），須使用 @code{list(dictview)}。請參閱@ref{254e,,字典視圖物件}。
@anchor{glossary term-docstring}@anchor{242f}
@geindex docstring（說明字串）

@item docstring（說明字串）

一個在 class、函式或模組中，作為第一個運算式出現的字串文本。雖然它在套件執行時會被忽略，但它會被編譯器辨識，並被放入所屬 class、函式或模組的 @ref{b18,,__doc__} 屬性中。由於說明字串可以透過內省 (introspection) 來瀏覽，因此它是物件的說明文件存放的標準位置。
@anchor{glossary term-duck-typing}@anchor{5703}
@geindex duck-typing（鴨子型別）

@item duck-typing（鴨子型別）

一種程式設計風格，它不是藉由檢查一個物件的型別來確定它是否具有正確的介面；取而代之的是，method 或屬性會單純地被呼叫或使用。（「如果它看起來像一隻鴨子而且叫起來像一隻鴨子，那麼它一定是一隻鴨子。」）因為強調介面而非特定型別，精心設計的程式碼能讓多形替代 (polymorphic substitution) 來增進它的靈活性。鴨子型別要避免使用 @ref{f3f,,type()} 或 @ref{2ad,,isinstance()} 進行測試。（但是請注意，鴨子型別可以用@ref{13b7,,抽象基底類別 (abstract base class)} 來補充。）然而，它通常會採用 @ref{6f2,,hasattr()} 測試，或是 @ref{2f2b,,EAFP} 程式設計風格。
@anchor{glossary term-dunder}@anchor{5709}
@geindex dunder（雙底線）

@item dunder（雙底線）

一個非正式的縮寫，代表「雙底線 (double underscore)」，當談論到@ref{1b62,,特殊方法}時使用。例如，@code{__init__} 通常被叫做 "dunder init"。
@anchor{glossary term-EAFP}@anchor{2f2b}
@geindex EAFP

@item EAFP

Easier to ask for forgiveness than permission.（請求寬恕比請求許可更容易。）這種常見的 Python 編碼風格會先假設有效的鍵或屬性的存在，並在該假設被推翻時再捕獲例外。這種乾淨且快速的風格，其特色是存在許多的 @ref{8f0,,try} 和 @ref{1ab,,except} 陳述式。該技術與許多其他語言（例如 C）常見的 @ref{570a,,LBYL} 風格形成了對比。
@anchor{glossary term-evaluate-function}@anchor{43a7}
@geindex evaluate function（求值函式）

@item evaluate function（求值函式）

A function that can be called to evaluate a lazily evaluated attribute
of an object, such as the value of type aliases created with the @ref{665,,type}
statement.
@anchor{glossary term-expression}@anchor{2281}
@geindex expression（運算式）

@item expression（運算式）

一段可以被評估並求值的語法。換句話說，一個運算式就是文字、名稱、屬性存取、運算子或函式呼叫等運算式元件的累積，而這些元件都能回傳一個值。與許多其他語言不同的是，並非所有的 Python 語言構造都是運算式。另外有一些 @ref{2aae,,statement}（陳述式）不能被用作運算式，例如 @ref{18d6,,while}。賦值 (assignment) 也是陳述式，而不是運算式。
@anchor{glossary term-extension-module}@anchor{2115}
@geindex extension module（擴充模組）

@item extension module（擴充模組）

一個以 C 或 C++ 編寫的模組，它使用 Python 的 C API 來與核心及使用者程式碼進行互動。
@anchor{glossary term-f-string}@anchor{663}
@geindex f-string（f 字串）

@item f-string（f 字串）@anchor{glossary term-f-strings}@anchor{570b}
@geindex f-strings（f 字串）

@itemx f-strings（f 字串）

以 @code{f} 或 @code{F} 為前綴的字串文本通常被稱為「f 字串」，它是@ref{19a,,格式化的字串文本}的縮寫。另請參閱 
@geindex Python Enhancement Proposals; PEP 498
PEP 498@footnote{https://peps.python.org/pep-0498/}。
@anchor{glossary term-file-object}@anchor{13c4}
@geindex file object（檔案物件）

@item file object（檔案物件）

一個讓使用者透過檔案導向 (file-oriented) API（如 @code{read()} 或 @code{write()} 等 method）來操作底層資源的物件。根據檔案物件被建立的方式，它能夠協調對真實磁碟檔案或是其他類型的儲存器或通訊裝置（例如標準輸入／輸出、記憶體內緩衝區、socket（插座）、管線 (pipe) 等）的存取。檔案物件也被稱為`類檔案物件 (file-like object)' 或`串流 (stream)'。

實際上，有三種檔案物件：原始的@ref{1f35,,二進位檔案}、緩衝的@ref{1f35,,二進位檔案}和@ref{1f34,,文字檔案}。它們的介面在 @ref{83,,io} 模組中被定義。建立檔案物件的標準方法是使用 @ref{315,,open()} 函式。
@anchor{glossary term-file-like-object}@anchor{28ad}
@geindex file-like object（類檔案物件）

@item file-like object（類檔案物件）

@ref{13c4,,file object}（檔案物件）的同義字。
@anchor{glossary term-filesystem-encoding-and-error-handler}@anchor{756}
@geindex filesystem encoding and error handler（檔案系統編碼和錯誤處理函式）

@item filesystem encoding and error handler（檔案系統編碼和錯誤處理函式）

Python 所使用的一種編碼和錯誤處理函式，用來解碼來自作業系統的位元組，以及將 Unicode 編碼到作業系統。

檔案系統編碼必須保證能成功解碼所有小於 128 的位元組。如果檔案系統編碼無法提供此保證，則 API 函式會引發 @ref{460,,UnicodeError}。

@ref{e4e,,sys.getfilesystemencoding()} 和 @ref{edd,,sys.getfilesystemencodeerrors()} 函式可用於取得檔案系統編碼和錯誤處理函式。

@ref{756,,filesystem encoding and error handler}（檔案系統編碼和錯誤處理函式）會在 Python 啟動時由 @ref{98b,,PyConfig_Read()} 函式來配置：請參閱 @ref{419,,filesystem_encoding}，以及 @ref{3f4,,PyConfig} 的成員 @ref{41a,,filesystem_errors}。

另請參閱 @ref{545,,locale encoding}（區域編碼）。
@anchor{glossary term-finder}@anchor{221c}
@geindex finder（尋檢器）

@item finder（尋檢器）

一個物件，它會嘗試為正在被 import 的模組尋找 @ref{1978,,loader}（載入器）。

有兩種類型的尋檢器：@ref{126b,,元路徑尋檢器 (meta path finder)} 會使用 @ref{f22,,sys.meta_path}，而@ref{126c,,路徑項目尋檢器 (path entry finder)} 會使用 @ref{121f,,sys.path_hooks}。

請參閱 @ref{22f6,,尋檢器 (Finder) 與載入器 (Loader)} 和 @ref{7b,,importlib} 以了解更多細節。
@anchor{glossary term-floor-division}@anchor{b35}
@geindex floor division（向下取整除法）

@item floor division（向下取整除法）

向下無條件捨去到最接近整數的數學除法。向下取整除法的運算子是 @code{//}。例如，運算式 @code{11 // 4} 的計算結果為 @code{2}，與 float（浮點數）真除法所回傳的 @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{1f4}
@geindex free threading（自由執行緒）

@item free threading（自由執行緒）

為一種執行緒模型，多個執行緒可以在同一直譯器中同時運行 Python 位元組碼。這與@ref{46e,,全域直譯器鎖}形成對比，後者一次只允許一個執行緒執行 Python 位元組碼。請參閱 
@geindex Python Enhancement Proposals; PEP 703
PEP 703@footnote{https://peps.python.org/pep-0703/}。
@anchor{glossary term-free-variable}@anchor{22d8}
@geindex free variable（自由變數）

@item free variable（自由變數）

Formally, as defined in the @ref{22d5,,language execution model}, a free
variable is any variable used in a namespace which is not a local variable in that
namespace. See @ref{180c,,closure variable} for an example.
Pragmatically, due to the name of the @ref{21f9,,codeobject.co_freevars} attribute,
the term is also sometimes used as a synonym for @ref{180c,,closure variable}.
@anchor{glossary term-function}@anchor{235d}
@geindex function（函式）

@item function（函式）

一連串的陳述式，它能夠向呼叫者回傳一些值。它也可以被傳遞零個或多個@ref{673,,引數}，這些引數可被使用於函式本體的執行。另請參閱 @ref{21fd,,parameter}（參數）、@ref{17e2,,method}（方法），以及@ref{1ee1,,函式定義}章節。
@anchor{glossary term-function-annotation}@anchor{1ee2}
@geindex function annotation（函式註釋）

@item function annotation（函式註釋）

函式參數或回傳值的一個 @ref{15c,,annotation}（註釋）。

函式註釋通常被使用於@ref{227d,,型別提示}：例如，這個函式預期會得到兩個 @ref{19b,,int} 引數，並會有一個 @ref{19b,,int} 回傳值：

@example
def sum_two_numbers(a: int, b: int) -> int:
   return a + b
@end example

函式註釋的語法在@ref{1ee1,,函式定義}章節有詳細解釋。

請參閱 @ref{f4c,,variable annotation} 和 
@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/}，皆有此功能的描述。關於註釋的最佳實踐方法，另請參閱 @ref{9d2,,註釋 (annotation) 最佳實踐}。
@anchor{glossary term-__future__}@anchor{fa8}
@geindex __future__

@item __future__

@ref{45b,,future 陳述式}：@code{from __future__ import <feature>}，會指示編譯器使用那些在 Python 未來的發布版本中將成為標準的語法或語義，來編譯目前的模組。而 @ref{0,,__future__} 模組則記錄了 `feature（功能）'可能的值。透過 import 此模組並對其變數求值，你可以看見一個新的功能是何時首次被新增到此語言中，以及它何時將會（或已經）成為預設的功能：

@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{1765}
@geindex garbage collection（垃圾回收）

@item garbage collection（垃圾回收）

當記憶體不再被使用時，將其釋放的過程。Python 執行垃圾回收，是透過參照計數 (reference counting)，以及一個能夠檢測和中斷參照循環 (reference cycle) 的循環垃圾回收器 (cyclic garbage collector) 來完成。垃圾回收器可以使用 @ref{64,,gc} 模組對其進行控制。

@geindex generator（產生器）
@anchor{glossary term-generator}@anchor{125c}
@geindex generator（產生器）

@item generator（產生器）

一個會回傳 @ref{dd4,,generator iterator}（產生器疊代器）的函式。它看起來像一個正常的函式，但不同的是它包含了 @ref{bb9,,yield} 運算式，能產生一系列的值，這些值可用於 for 迴圈，或是以 @ref{9d1,,next()} 函式，每次檢索其中的一個值。

這個術語通常用來表示一個產生器函式，但在某些情境中，也可能是表示`產生器疊代器'。萬一想表達的意思不夠清楚，那就使用完整的術語，以避免歧義。
@anchor{glossary term-generator-iterator}@anchor{dd4}
@geindex generator iterator（產生器疊代器）

@item generator iterator（產生器疊代器）

一個由 @ref{125c,,generator}（產生器）函式所建立的物件。

每個 @ref{bb9,,yield} 會暫停處理程序，並記住執行狀態（包括區域變數及擱置中的 try 陳述式）。當`產生器疊代器'回復時，它會從停止的地方繼續執行（與那些每次呼叫時都要重新開始的函式有所不同）。

@geindex generator expression（產生器運算式）
@anchor{glossary term-generator-expression}@anchor{570c}
@geindex generator expression（產生器運算式）

@item generator expression（產生器運算式）

一個會回傳@ref{4c3,,疊代器}的@ref{2281,,運算式}。它看起來像一個正常的運算式，後面接著一個 @code{for} 子句，該子句定義了迴圈變數、範圍以及一個選擇性的 @code{if} 子句。該組合運算式會為外層函式產生多個值：

@example
>>> sum(i*i for i in range(10))         # 平方之和 0, 1, 4, ... 81
285
@end example
@anchor{glossary term-generic-function}
@geindex generic function（泛型函式）

@item generic function（泛型函式）

一個由多個函式組成的函式，該函式會對不同的型別實作相同的運算。呼叫期間應該使用哪種實作，是由調度演算法 (dispatch algorithm) 來決定。

另請參閱 @ref{bdc,,single dispatch}（單一調度）術語表條目、@ref{844,,functools.singledispatch()} 裝飾器和 
@geindex Python Enhancement Proposals; PEP 443
PEP 443@footnote{https://peps.python.org/pep-0443/}。
@anchor{glossary term-generic-type}@anchor{1a1}
@geindex generic type（泛型型別）

@item generic type（泛型型別）

一個能夠被參數化 (parameterized) 的 @ref{1be8,,type}（型別）；通常是一個 @ref{2286,,容器型別}，像是 @ref{24d,,list} 和 @ref{183,,dict}。它被用於@ref{227d,,型別提示}和@ref{15c,,註釋}。

詳情請參閱@ref{8b8,,泛型別名型別}、
@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/} 和 @ref{10a,,typing} 模組。
@anchor{glossary term-GIL}@anchor{164}
@geindex GIL

@item GIL

請參閱 @ref{46e,,global interpreter lock}（全域直譯器鎖）。
@anchor{glossary term-global-interpreter-lock}@anchor{46e}
@geindex global interpreter lock（全域直譯器鎖）

@item global interpreter lock（全域直譯器鎖）

@ref{8fd,,CPython} 直譯器所使用的機制，用以確保每次都只有一個執行緒能執行 Python 的 @ref{4a5,,bytecode}（位元組碼）。透過使物件模型（包括關鍵的內建型別，如 @ref{183,,dict}）自動地避免並行存取 (concurrent access) 的危險，此機制可以簡化 CPython 的實作。鎖定整個直譯器，會使直譯器更容易成為多執行緒 (multi-threaded)，但代價是會犧牲掉多處理器的機器能夠提供的一大部分平行性 (parallelism)。

然而，有些擴充模組，無論是標準的或是第三方的，它們被設計成在執行壓縮或雜湊等計算密集 (computationally intensive) 的任務時，可以解除 GIL。另外，在執行 I/O 時，GIL 總是會被解除。

從 Python 3.13 開始可以使用 @ref{494,,--disable-gil} 建置設定來停用 GIL。使用此選項建立 Python 後，必須使用 @ref{16f,,-X gil=0} 來執行程式碼，或者設定 
@geindex PYTHON_GIL
@geindex 環境變數; PYTHON_GIL
@ref{495,,PYTHON_GIL=0} 環境變數後再執行程式碼。此功能可以提高多執行緒應用程式的效能，並使多核心 CPU 的高效使用變得更加容易。有關更多詳細資訊，請參閱 
@geindex Python Enhancement Proposals; PEP 703
PEP 703@footnote{https://peps.python.org/pep-0703/}。

In prior versions of Python's C API, a function might declare that it
requires the GIL to be held in order to use it. This refers to having an
@ref{4d99,,attached thread state}.
@anchor{glossary term-hash-based-pyc}@anchor{570d}
@geindex hash-based pyc（雜湊架構的 pyc）

@item hash-based pyc（雜湊架構的 pyc）

一個位元組碼 (bytecode) 暫存檔，它使用雜湊值而不是對應原始檔案的最後修改時間，來確定其有效性。請參閱@ref{7fb,,Cached bytecode invalidation}。
@anchor{glossary term-hashable}@anchor{81d}
@geindex hashable（可雜湊的）

@item hashable（可雜湊的）

如果一個物件有一個雜湊值，該值在其生命週期中永不改變（它需要一個 @ref{cea,,__hash__()} method），且可與其他物件互相比較（它需要一個 @ref{ce9,,__eq__()} method），那麼它就是一個`可雜湊'物件。比較結果為相等的多個可雜湊物件，它們必須擁有相同的雜湊值。

可雜湊性 (hashability) 使一個物件可用作 dictionary（字典）的鍵和 set（集合）的成員，因為這些資料結構都在其內部使用了雜湊值。

大多數的 Python 不可變內建物件都是可雜湊的；可變的容器（例如 list 或 dictionary）並不是；而不可變的容器（例如 tuple（元組）和 frozenset），只有當它們的元素是可雜湊的，它們本身才是可雜湊的。若物件是使用者自定 class 的實例，則這些物件會被預設為可雜湊的。它們在互相比較時都是不相等的（除非它們與自己比較），而它們的雜湊值則是衍生自它們的 @ref{161a,,id()}。
@anchor{glossary term-IDLE}@anchor{570e}
@geindex IDLE

@item IDLE

Python 的 Integrated Development and Learning Environment（整合開發與學習環境）。@ref{1210,,IDLE --- Python 編輯器與 shell} 是一個基本的編輯器和直譯器環境，它和 Python 的標準發行版本一起被提供。
@anchor{glossary term-immortal}@anchor{290}
@geindex immortal（不滅）

@item immortal（不滅）

`不滅物件 (Immortal objects)' 是 
@geindex Python Enhancement Proposals; PEP 683
PEP 683@footnote{https://peps.python.org/pep-0683/} 引入的 CPython 實作細節。

如果一個物件是不滅的，它的@ref{4d91,,參照計數}永遠不會被修改，因此在直譯器運行時它永遠不會被釋放。例如，@ref{e02,,True} 和 @ref{87e,,None} 在 CPython 中是不滅的。

Immortal objects can be identified via @ref{28f,,sys._is_immortal()}, or
via @ref{3c2,,PyUnstable_IsImmortal()} in the C API.
@anchor{glossary term-immutable}@anchor{1ea7}
@geindex immutable（不可變物件）

@item immutable（不可變物件）

一個具有固定值的物件。不可變物件包括數字、字串和 tuple（元組）。這類物件是不能被改變的。如果一個不同的值必須被儲存，則必須建立一個新的物件。它們在需要恆定雜湊值的地方，扮演重要的角色，例如 dictionary（字典）中的一個鍵。
@anchor{glossary term-import-path}@anchor{22f9}
@geindex import path（引入路徑）

@item import path（引入路徑）

一個位置（或@ref{2307,,路徑項目}）的列表，而那些位置就是在 import 模組時，會被 @ref{22fc,,path based finder}（基於路徑的尋檢器）搜尋模組的位置。在 import 期間，此位置列表通常是來自 @ref{3e2,,sys.path}，但對於子套件 (subpackage) 而言，它也可能是來自父套件的 @code{__path__} 屬性。
@anchor{glossary term-importing}@anchor{22ec}
@geindex importing（引入）

@item importing（引入）

一個過程。一個模組中的 Python 程式碼可以透過此過程，被另一個模組中的 Python 程式碼使用。
@anchor{glossary term-importer}@anchor{22f8}
@geindex importer（引入器）

@item importer（引入器）

一個能夠尋找及載入模組的物件；它既是 @ref{221c,,finder}（尋檢器）也是 @ref{1978,,loader}（載入器）物件。
@anchor{glossary term-interactive}@anchor{1b5}
@geindex interactive（互動的）

@item interactive（互動的）

Python 有一個互動式直譯器，這表示你可以在直譯器的提示字元輸入陳述式和運算式，立即執行它們並且看到它們的結果。只要啟動 @code{python}，不需要任何引數（可能藉由從你的電腦的主選單選擇它）。這是測試新想法或檢查模組和包的非常強大的方法（請記住help(x)）。更多互動式模式相關資訊請見 @ref{48f,,互動模式}。
@anchor{glossary term-interpreted}@anchor{570f}
@geindex interpreted（直譯的）

@item interpreted（直譯的）

Python 是一種直譯語言，而不是編譯語言，不過這個區分可能有些模糊，因為有位元組碼 (bytecode) 編譯器的存在。這表示原始檔案可以直接被運行，而不需明確地建立另一個執行檔，然後再執行它。直譯語言通常比編譯語言有更短的開發／除錯週期，不過它們的程式通常也運行得較慢。另請參閱 @ref{1b5,,interactive}（互動的）。
@anchor{glossary term-interpreter-shutdown}@anchor{474}
@geindex interpreter shutdown（直譯器關閉）

@item interpreter shutdown（直譯器關閉）

當 Python 直譯器被要求關閉時，它會進入一個特殊階段，在此它逐漸釋放所有被配置的資源，例如模組和各種關鍵內部結構。它也會多次呼叫@ref{1765,,垃圾回收器 (garbage collector)}。這能夠觸發使用者自定的解構函式 (destructor) 或弱引用的回呼 (weakref callback)，並執行其中的程式碼。在關閉階段被執行的程式碼會遇到各種例外，因為它所依賴的資源可能不再有作用了（常見的例子是函式庫模組或是警告機制）。

直譯器關閉的主要原因，是 @code{__main__} 模組或正被運行的腳本已經執行完成。
@anchor{glossary term-iterable}@anchor{1428}
@geindex iterable（可疊代物件）

@item iterable（可疊代物件）

一種能夠一次回傳一個其中成員的物件。可疊代物件的例子包括所有的序列型別（像是 @ref{24d,,list}、@ref{169,,str} 和 @ref{60c,,tuple}）和某些非序列型別，像是 @ref{183,,dict}、@ref{13c4,,檔案物件}，以及你所定義的任何 class 物件，只要那些 class 有實作 @ref{70f,,sequence}（序列）語意的 @ref{e64,,__iter__()} 或是 @ref{582,,__getitem__()} method，該物件就是可疊代物件。

可疊代物件可用於 @ref{348,,for} 迴圈和許多其他需要一個序列的地方 (@ref{1a0,,zip()}、@ref{19f,,map()}...)。當一個可疊代物件作為引數被傳遞給內建函式 @ref{9d0,,iter()} 時，它會為該物件回傳一個疊代器。此疊代器適用於針對一組值進行一遍 (one pass) 運算。使用疊代器時，通常不一定要呼叫 @ref{9d0,,iter()} 或自行處理疊代器物件。@ref{348,,for} 陳述式會自動地為你處理這些事，它會建立一個暫時性的未命名變數，用於在迴圈期間保有該疊代器。另請參閱 @ref{4c3,,iterator}（疊代器）、@ref{70f,,sequence}（序列）和 @ref{125c,,generator}（產生器）。
@anchor{glossary term-iterator}@anchor{4c3}
@geindex iterator（疊代器）

@item iterator（疊代器）

一個表示資料流的物件。重複地呼叫疊代器的 @ref{14ce,,__next__()} method（或是將它傳遞給內建函式 @ref{9d1,,next()}）會依序回傳資料流中的各項目。當不再有資料時，則會引發 @ref{df0,,StopIteration} 例外。此時，該疊代器物件已被用盡，而任何對其 @code{__next__()} method 的進一步呼叫，都只會再次引發 @ref{df0,,StopIteration}。疊代器必須有一個 @ref{1f74,,__iter__()} method，它會回傳疊代器物件本身，所以每個疊代器也都是可疊代物件，且可以用於大多數適用其他可疊代物件的場合。一個明顯的例外，是嘗試多遍疊代 (multiple iteration passes) 的程式碼。一個容器物件（像是 @ref{24d,,list}）在每次你將它傳遞給 @ref{9d0,,iter()} 函式或在 @ref{348,,for} 迴圈中使用它時，都會產生一個全新的疊代器。使用疊代器嘗試此事（多遍疊代）時，只會回傳在前一遍疊代中被用過的、同一個已被用盡的疊代器物件，使其看起來就像一個空的容器。

在@ref{2481,,疊代器型別}文中可以找到更多資訊。

CPython 並不是始終如一地都會檢查「疊代器有定義 @ref{1f74,,__iter__()}」這個規定。另請注意，free-threading（自由執行緒）CPython 不保證疊代器操作的執行緒安全。
@anchor{glossary term-key-function}@anchor{1001}
@geindex key function（鍵函式）

@item key function（鍵函式）

鍵函式或理序函式 (collation function) 是一個可呼叫 (callable) 函式，它會回傳一個用於排序 (sorting) 或定序 (ordering) 的值。例如，@ref{1753,,locale.strxfrm()} 被用來產生一個了解區域特定排序慣例的排序鍵。

Python 中的許多工具，都接受以鍵函式來控制元素被定序或分組的方式。它們包括 @ref{1106,,min()}、@ref{1107,,max()}、@ref{dc2,,sorted()}、@ref{dc3,,list.sort()}、@ref{1000,,heapq.merge()}、@ref{2855,,heapq.nsmallest()}、@ref{2854,,heapq.nlargest()} 和 @ref{2a57,,itertools.groupby()}。

有幾種方法可以建立一個鍵函式。例如，@ref{1aa5,,str.lower()} method 可以作為不分大小寫排序的鍵函式。或者，一個鍵函式也可以從 @ref{149e,,lambda} 運算式被建造，例如 @code{lambda r: (r[0], r[2])}。另外，@ref{102e,,operator.attrgetter()}、@ref{c4e,,operator.itemgetter()} 和 @ref{102f,,operator.methodcaller()} 為三個鍵函式的建構函式 (constructor)。關於如何建立和使用鍵函式的範例，請參閱@ref{248a,,如何排序}。
@anchor{glossary term-keyword-argument}@anchor{f09}
@geindex keyword argument（關鍵字引數）

@item keyword argument（關鍵字引數）

請參閱 @ref{673,,argument}（引數）。
@anchor{glossary term-lambda}@anchor{2a65}
@geindex lambda

@item lambda

由單一 @ref{2281,,expression}（運算式）所組成的一個匿名行內函式 (inline function)，於該函式被呼叫時求值。建立 lambda 函式的語法是 @code{lambda [parameters]: expression}
@anchor{glossary term-LBYL}@anchor{570a}
@geindex LBYL

@item LBYL

Look before you leap.（三思而後行。）這種編碼風格會在進行呼叫或查找之前，明確地測試先決條件。這種風格與 @ref{2f2b,,EAFP} 方式形成對比，且它的特色是會有許多 @ref{181,,if} 陳述式的存在。

在一個多執行緒環境中，LBYL 方式有在「三思」和「後行」之間引入了競爭條件 (race condition) 的風險。例如以下程式碼 @code{if key in mapping: return mapping[key]}，如果另一個執行緒在測試之後但在查找之前，從 `mapping' 中移除了 `key'，則該程式碼就會失效。這個問題可以用鎖 (lock) 或使用 EAFP 編碼方式來解決。
@anchor{glossary term-lexical-analyzer}@anchor{2156}
@geindex lexical analyzer（詞法分析器）

@item lexical analyzer（詞法分析器）

tokenizer 的正式名稱；請參閱 @ref{214c,,token}。
@anchor{glossary term-list}@anchor{5710}
@geindex list（串列）

@item list（串列）

一個 Python 內建的 @ref{70f,,sequence} （序列）。儘管它的名字是 list，它其實更類似其他語言中的一個陣列 (array) 而較不像一個鏈結串列 (linked list)，因為存取元素的時間複雜度是 `O'(1)。
@anchor{glossary term-list-comprehension}@anchor{8d5}
@geindex list comprehension（串列綜合運算）

@item list comprehension（串列綜合運算）

一種用來處理一個序列中的全部或部分元素，並將處理結果以一個 list 回傳的簡要方法。@code{result = ['@{:#04x@}'.format(x) for x in range(256) if x % 2 == 0]} 會產生一個字串 list，其中包含 0 到 255 範圍內，所有偶數的十六進位數 (0x..)。@ref{181,,if} 子句是選擇性的。如果省略它，則 @code{range(256)} 中的所有元素都會被處理。
@anchor{glossary term-loader}@anchor{1978}
@geindex loader（載入器）

@item loader（載入器）

一個能夠載入模組的物件。它必須定義 @code{exec_module()} 和 @code{create_module()} 方法以實作 @ref{10c2,,Loader} 介面。載入器通常是被 @ref{221c,,finder}（尋檢器）回傳。更多細節請參閱：


@itemize *

@item 
@ref{22f6,,尋檢器 (Finder) 與載入器 (Loader)}

@item 
@ref{10c2,,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{545}
@geindex locale encoding（區域編碼）

@item locale encoding（區域編碼）

在 Unix 上，它是 LC_CTYPE 區域設定的編碼。它可以用 @ref{327,,locale.setlocale(locale.LC_CTYPE@comma{} new_locale)} 來設定。

在 Windows 上，它是 ANSI 碼頁（code page，例如 @code{"cp1252"}）。

在 Android 和 VxWorks 上，Python 使用 @code{"utf-8"} 作為區域編碼。

@ref{328,,locale.getencoding()} 可以用來取得區域編碼。

也請參考 @ref{756,,filesystem encoding and error handler}。
@anchor{glossary term-magic-method}@anchor{4521}
@geindex magic method（魔術方法）

@item magic method（魔術方法）

@geindex magic;method（方法）

@ref{1b62,,special method}（特殊方法）的一個非正式同義詞。
@anchor{glossary term-mapping}@anchor{13bc}
@geindex mapping（對映）

@item mapping（對映）

一個容器物件，它支援任意鍵的查找，且能實作 @ref{a6f,,abstract base classes（抽象基底類別）}中，@ref{abe,,collections.abc.Mapping} 或 @ref{12ad,,collections.abc.MutableMapping} 所指定的 method。範例包括 @ref{183,,dict}、@ref{13bd,,collections.defaultdict}、@ref{7ec,,collections.OrderedDict} 和 @ref{1292,,collections.Counter}。
@anchor{glossary term-meta-path-finder}@anchor{126b}
@geindex meta path finder（元路徑尋檢器）

@item meta path finder（元路徑尋檢器）

一種經由搜尋 @ref{f22,,sys.meta_path} 而回傳的 @ref{221c,,finder}（尋檢器）。元路徑尋檢器與@ref{126c,,路徑項目尋檢器 (path entry finder)} 相關但是不同。

關於元路徑尋檢器實作的 method，請參閱 @ref{a67,,importlib.abc.MetaPathFinder}。
@anchor{glossary term-metaclass}@anchor{2282}
@geindex metaclass（元類別）

@item metaclass（元類別）

一種 class 的 class。Class 定義過程會建立一個 class 名稱、一個 class dictionary（字典），以及一個 base class（基底類別）的列表。Metaclass 負責接受這三個引數，並建立該 class。大多數的物件導向程式語言會提供一個預設的實作。Python 的特別之處在於它能夠建立自訂的 metaclass。大部分的使用者從未需要此工具，但是當需要時，metaclass 可以提供強大且優雅的解決方案。它們已被用於記錄屬性存取、增加執行緒安全性、追蹤物件建立、實作單例模式 (singleton)，以及許多其他的任務。

更多資訊可以在@ref{2270,,Metaclasses}章節中找到。
@anchor{glossary term-method}@anchor{17e2}
@geindex method（方法）

@item method（方法）

一個在 class 本體內被定義的函式。如果 method 作為其 class 實例的一個屬性被呼叫，則它將會得到該實例物件成為它的第一個 @ref{673,,argument}（引數）（此引數通常被稱為 @code{self}）。請參閱 @ref{235d,,function}（函式）和 @ref{223e,,nested scope}（巢狀作用域）。
@anchor{glossary term-method-resolution-order}@anchor{248c}
@geindex method resolution order（方法解析順序）

@item method resolution order（方法解析順序）

方法解析順序是在查找某個成員的過程中，base class（基底類別）被搜尋的順序。關於 Python 自 2.3 版直譯器所使用的演算法細節，請參閱 @ref{169e,,The Python 2.3 Method Resolution Order}。
@anchor{glossary term-module}@anchor{192d}
@geindex module（模組）

@item module（模組）

一個擔任 Python 程式碼的組織單位 (organizational unit) 的物件。模組有一個命名空間，它包含任意的 Python 物件。模組是藉由 @ref{22ec,,importing} 的過程，被載入至 Python。

另請參閱 @ref{233,,package}（套件）。
@anchor{glossary term-module-spec}@anchor{2215}
@geindex module spec（模組規格）

@item module spec（模組規格）

一個命名空間，它包含用於載入模組的 import 相關資訊。它是 @ref{2130,,importlib.machinery.ModuleSpec} 的一個實例。

另請參閱 @ref{2218,,模組規格}。
@anchor{glossary term-MRO}@anchor{184a}
@geindex MRO

@item MRO

請參閱 @ref{248c,,method resolution order}（方法解析順序）。
@anchor{glossary term-mutable}@anchor{1eac}
@geindex mutable（可變物件）

@item mutable（可變物件）

可變物件可以改變它們的值，但維持它們的 @ref{161a,,id()}。另請參閱 @ref{1ea7,,immutable}（不可變物件）。
@anchor{glossary term-named-tuple}@anchor{857}
@geindex named tuple（附名元組）

@item named tuple（附名元組）

術語「named tuple（附名元組）」是指從 tuple 繼承的任何型別或 class，且它的可索引 (indexable) 元素也可以用附名屬性來存取。這些型別或 class 也可以具有其他的特性。

有些內建型別是 named tuple，包括由 @ref{16ed,,time.localtime()} 和 @ref{26d,,os.stat()} 回傳的值。另一個例子是 @ref{1c98,,sys.float_info}：

@example
>>> sys.float_info[1]                   # 以索引存取
1024
>>> sys.float_info.max_exp              # 以欄位名稱存取
1024
>>> isinstance(sys.float_info, tuple)   # 屬於 tuple 型別
True
@end example

有些 named tuple 是內建型別（如上例）。或者，一個 named tuple 也可以從一個正規的 class 定義來建立，只要該 class 是繼承自 @ref{60c,,tuple}，且定義了附名欄位 (named field) 即可。這類的 class 可以手工編寫、可以繼承自 @ref{330,,typing.NamedTuple} 來建立，也可以使用工廠函式 (factory function) @ref{4db,,collections.namedtuple()} 來建立。後者技術也增加了一些額外的 method，這些 method 可能是在手寫或內建的 named tuple 中，無法找到的。
@anchor{glossary term-namespace}@anchor{1f06}
@geindex namespace（命名空間）

@item namespace（命名空間）

變數被儲存的地方。命名空間是以 dictionary（字典）被實作。有區域的、全域的及內建的命名空間，而在物件中（在 method 中）也有巢狀的命名空間。命名空間藉由防止命名衝突，來支援模組化。例如，函式 @ref{315,,builtins.open} 和 @ref{f8d,,os.open()} 是透過它們的命名空間來區分彼此。命名空間也藉由明確地區分是哪個模組在實作一個函式，來增進可讀性及可維護性。例如，寫出 @ref{1474,,random.seed()} 或 @ref{d3b,,itertools.islice()} 明確地表示，這些函式分別是由 @ref{bd,,random} 和 @ref{85,,itertools} 模組在實作。
@anchor{glossary term-namespace-package}@anchor{2b2}
@geindex namespace package（命名空間套件）

@item namespace package（命名空間套件）

一個 @ref{233,,package}（套件），它只能作為子套件 (subpackage) 的一個容器。命名空間套件可能沒有實體的表示法，而且具體來說它們不像是一個 @ref{22f0,,regular package}（正規套件），因為它們並沒有 @code{__init__.py} 這個檔案。

命名空間套件允許數個可獨立安裝的套件擁有一個共同的父套件。除此之外，建議使用 @ref{22f0,,regular package}。

更多資訊，請參閱 
@geindex Python Enhancement Proposals; PEP 420
PEP 420@footnote{https://peps.python.org/pep-0420/} 和 @ref{22f2,,命名空間套件}。

另請參閱 @ref{192d,,module}（模組）。
@anchor{glossary term-nested-scope}@anchor{223e}
@geindex nested scope（巢狀作用域）

@item nested scope（巢狀作用域）

能夠參照外層定義 (enclosing definition) 中的變數的能力。舉例來說，一個函式如果是在另一個函式中被定義，則它便能夠參照外層函式中的變數。請注意，在預設情況下，巢狀作用域僅適用於參照，而無法用於賦值。區域變數能在最內層作用域中讀取及寫入。同樣地，全域變數是在全域命名空間中讀取及寫入。@ref{14a8,,nonlocal} 容許對外層作用域進行寫入。
@anchor{glossary term-new-style-class}@anchor{2bbd}
@geindex new-style class（新式類別）

@item new-style class（新式類別）

一個舊名，它是指現在所有的 class 物件所使用的 class 風格。在早期的 Python 版本中，只有新式 class 才能使用 Python 較新的、多樣的功能，像是 @ref{16df,,__slots__}、描述器 (descriptor)、屬性 (property)、@ref{dc6,,__getattribute__()}、class method（類別方法）和 static method（靜態方法）。
@anchor{glossary term-object}@anchor{5711}
@geindex object（物件）

@item object（物件）

具有狀態（屬性或值）及被定義的行為（method）的任何資料。它也是任何 @ref{2bbd,,new-style class}（新式類別）的最終 base class（基底類別）。
@anchor{glossary term-optimized-scope}@anchor{49c}
@geindex optimized scope（最佳化作用域）

@item optimized scope（最佳化作用域）

A scope where target local variable names are reliably known to the
compiler when the code is compiled, allowing optimization of read and
write access to these names. The local namespaces for functions,
generators, coroutines, comprehensions, and generator expressions are
optimized in this fashion. Note: most interpreter optimizations are
applied to all scopes, only those relying on a known set of local
and nonlocal variable names are restricted to optimized scopes.
@anchor{glossary term-package}@anchor{233}
@geindex package（套件）

@item package（套件）

一個 Python 的 @ref{192d,,module}（模組），它可以包含子模組 (submodule) 或是遞迴的子套件 (subpackage)。技術上而言，套件就是具有 @code{__path__} 屬性的一個 Python 模組。

另請參閱 @ref{22f0,,regular package}（正規套件）和 @ref{2b2,,namespace package}（命名空間套件）。
@anchor{glossary term-parameter}@anchor{21fd}
@geindex parameter（參數）

@item parameter（參數）

在 @ref{235d,,function}（函式）或 method 定義中的一個命名實體 (named entity)，它指明該函式能夠接受的一個 @ref{673,,argument}（引數），或在某些情況下指示多個引數。共有有五種不同的參數類型：


@itemize *

@item 
`positional-or-keyword'（位置或關鍵字）：指明一個可以@ref{673,,按照位置}或是作為@ref{673,,關鍵字引數}被傳遞的引數。這是參數的預設類型，例如以下的 `foo' 和 `bar'：

@example
def func(foo, bar=None): ...
@end example
@end itemize
@anchor{glossary positional-only-parameter}@anchor{c6f}

@itemize *

@item 
`positional-only'（僅限位置）：指明一個只能按照位置被提供的引數。在函式定義的參數列表中包含一個 @code{/} 字元，就可以在該字元前面定義僅限位置參數，例如以下的 `posonly1' 和 `posonly2'：

@example
def func(posonly1, posonly2, /, positional_or_keyword): ...
@end example
@end itemize
@anchor{glossary keyword-only-parameter}@anchor{59f}

@itemize *

@item 
`keyword-only'（僅限關鍵字）：指明一個只能以關鍵字被提供的引數。在函式定義的參數列表中，包含一個任意數量位置參數 (var-positional parameter) 或是單純的 @code{*} 字元，就可以在其後方定義僅限關鍵字參數，例如以下的 `kw_only1' 和 `kw_only2'：

@example
def func(arg, *, kw_only1, kw_only2): ...
@end example

@item 
`var-positional'（任意數量位置）：指明一串能以任意序列被提供的位置引數（在已被其他參數接受的任何位置引數之外）。這類參數是透過在其參數名稱字首加上 @code{*} 來定義的，例如以下的 `args'：

@example
def func(*args, **kwargs): ...
@end example

@item 
`var-keyword'（任意數量關鍵字）：指明可被提供的任意數量關鍵字引數（在已被其他參數接受的任何關鍵字引數之外）。這類參數是透過在其參數名稱字首加上 @code{**} 來定義的，例如上面範例中的 `kwargs'。
@end itemize

參數可以指明引數是選擇性的或必需的，也可以為一些選擇性的引數指定預設值。

另請參閱術語表的 @ref{673,,argument}（引數）條目、常見問題中的@ref{563e,,引數和參數之間的差異}、@ref{4df,,inspect.Parameter} class、@ref{1ee1,,函式定義}章節，以及 
@geindex Python Enhancement Proposals; PEP 362
PEP 362@footnote{https://peps.python.org/pep-0362/}。
@anchor{glossary term-path-entry}@anchor{2307}
@geindex path entry（路徑項目）

@item path entry（路徑項目）

在 @ref{22f9,,import path}（引入路徑）中的一個位置，而 @ref{22fc,,path based finder} （基於路徑的尋檢器）會參考該位置來尋找要 import 的模組。
@anchor{glossary term-path-entry-finder}@anchor{126c}
@geindex path entry finder（路徑項目尋檢器）

@item path entry finder（路徑項目尋檢器）

被 @ref{121f,,sys.path_hooks} 中的一個可呼叫物件 (callable)（意即一個 @ref{2309,,path entry hook}）所回傳的一種 @ref{221c,,finder}，它知道如何以一個 @ref{2307,,path entry}定位模組。

關於路徑項目尋檢器實作的 method，請參閱 @ref{a68,,importlib.abc.PathEntryFinder}。
@anchor{glossary term-path-entry-hook}@anchor{2309}
@geindex path entry hook（路徑項目鉤）

@item path entry hook（路徑項目鉤）

在 @ref{121f,,sys.path_hooks} 列表中的一個可呼叫物件 (callable)，若它知道如何在一個特定的 @ref{2307,,path entry} 中尋找模組，則會回傳一個 @ref{126c,,path entry finder}（路徑項目尋檢器）。
@anchor{glossary term-path-based-finder}@anchor{22fc}
@geindex path based finder（基於路徑的尋檢器）

@item path based finder（基於路徑的尋檢器）

預設的@ref{126b,,元路徑尋檢器 (meta path finder)} 之一，它會在一個 @ref{22f9,,import path} 中搜尋模組。
@anchor{glossary term-path-like-object}@anchor{59b}
@geindex path-like object（類路徑物件）

@item path-like object（類路徑物件）

一個表示檔案系統路徑的物件。類路徑物件可以是一個表示路徑的 @ref{169,,str} 或 @ref{192,,bytes} 物件，或是一個實作 @ref{e46,,os.PathLike} 協定的物件。透過呼叫 @ref{e48,,os.fspath()} 函式，一個支援 @ref{e46,,os.PathLike} 協定的物件可以被轉換為 @ref{169,,str} 或 @ref{192,,bytes} 檔案系統路徑；而 @ref{e49,,os.fsdecode()} 及 @ref{e4a,,os.fsencode()} 則分別可用於確保 @ref{169,,str} 及 @ref{192,,bytes} 的結果。由 
@geindex Python Enhancement Proposals; PEP 519
PEP 519@footnote{https://peps.python.org/pep-0519/} 引入。
@anchor{glossary term-PEP}@anchor{5712}
@geindex PEP

@item PEP

Python Enhancement Proposal（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{22f3}
@geindex portion（部分）

@item portion（部分）

在單一目錄中的一組檔案（也可能儲存在一個 zip 檔中），這些檔案能對一個命名空間套件 (namespace package) 有所貢獻，如同 
@geindex Python Enhancement Proposals; PEP 420
PEP 420@footnote{https://peps.python.org/pep-0420/} 中的定義。
@anchor{glossary term-positional-argument}@anchor{f0a}
@geindex positional argument（位置引數）

@item positional argument（位置引數）

請參閱 @ref{673,,argument}（引數）。
@anchor{glossary term-provisional-API}@anchor{3cf}
@geindex provisional API（暫行 API）

@item provisional API（暫行 API）

暫行 API 是指，從標準函式庫的向後相容性 (backwards compatibility) 保證中，故意被排除的 API。雖然此類介面，只要它們被標示為暫行的，理論上並不會有重大的變更，但如果核心開發人員認為有必要，也可能會出現向後不相容的變更（甚至包括移除該介面）。這種變更並不會無端地產生——只有 API 被納入之前未察覺的嚴重基本缺陷被揭露時，它們才會發生。

即使對於暫行 API，向後不相容的變更也會被視為「最後的解決方案」——對於任何被發現的問題，仍然會盡可能找出一個向後相容的解決方案。

這個過程使得標準函式庫能隨著時間不斷進化，而避免耗費過長的時間去鎖定有問題的設計錯誤。請參閱 
@geindex Python Enhancement Proposals; PEP 411
PEP 411@footnote{https://peps.python.org/pep-0411/} 了解更多細節。
@anchor{glossary term-provisional-package}@anchor{123d}
@geindex provisional package（暫行套件）

@item provisional package（暫行套件）

請參閱 @ref{3cf,,provisional API}（暫行 API）。
@anchor{glossary term-Python-3000}@anchor{5713}
@geindex Python 3000

@item Python 3000

Python 3.x 系列版本的暱稱（很久以前創造的，當時第 3 版的發布是在遙遠的未來。）也可以縮寫為「Py3k」。
@anchor{glossary term-Pythonic}@anchor{5714}
@geindex Pythonic（Python 風格的）

@item Pythonic（Python 風格的）

一個想法或一段程式碼，它應用了 Python 語言最常見的慣用語，而不是使用其他語言常見的概念來實作程式碼。例如，Python 中常見的一種習慣用法，是使用一個 @ref{348,,for} 陳述式，對一個可疊代物件的所有元素進行迴圈。許多其他語言並沒有這種類型的架構，所以不熟悉 Python 的人有時會使用一個數值計數器來代替：

@example
for i in range(len(food)):
    print(food[i])
@end example

相較之下，以下方法更簡潔、更具有 Python 風格：

@example
for piece in food:
    print(piece)
@end example
@anchor{glossary term-qualified-name}@anchor{1bf6}
@geindex qualified name（限定名稱）

@item qualified name（限定名稱）

一個「點分隔名稱」，它顯示從一個模組的全域作用域到該模組中定義的 class、函式或 method 的「路徑」，如 
@geindex Python Enhancement Proposals; PEP 3155
PEP 3155@footnote{https://peps.python.org/pep-3155/} 中的定義。對於頂層的函式和 class 而言，限定名稱與其物件名稱相同：

@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

當用於引用模組時，`完全限定名稱 (fully qualified name)' 是表示該模組的完整點分隔路徑，包括任何的父套件，例如 @code{email.mime.text}：

@example
>>> import email.mime.text
>>> email.mime.text.__name__
'email.mime.text'
@end example
@anchor{glossary term-reference-count}@anchor{4d91}
@geindex reference count（參照計數）

@item reference count（參照計數）

對於一個物件的參照次數。當一個物件的參照計數下降到零時，它會被解除配置 (deallocated)。有些物件是「@ref{290,,不滅的} (immortal)」並擁有不會被改變的參照計數，也因此永遠不會被解除配置。參照計數通常在 Python 程式碼中看不到，但它卻是 @ref{8fd,,CPython} 實作的一個關鍵元素。程式設計師可以呼叫 @ref{2ce,,getrefcount()} 函式來回傳一個特定物件的參照計數。

在 @ref{8fd,,CPython} 中，參照計數不被視為穩定或明確定義的值；對物件的參照數量，以及該數量如何受到 Python 程式碼的影響，在不同版本之間可能會有所不同。
@anchor{glossary term-regular-package}@anchor{22f0}
@geindex regular package（正規套件）

@item regular package（正規套件）

一個傳統的 @ref{233,,package}（套件），例如一個包含 @code{__init__.py} 檔案的目錄。

另請參閱 @ref{2b2,,namespace package}（命名空間套件）。
@anchor{glossary term-REPL}@anchor{48c}
@geindex REPL

@item REPL

「read-eval-print 迴圈 (read–eval–print loop)」的縮寫，是@ref{1b5,,互動式}直譯器 shell 的另一個名稱。
@anchor{glossary term-__slots__}@anchor{7f0}
@geindex __slots__

@item __slots__

在 class 內部的一個宣告，它藉由預先宣告實例屬性的空間，以及消除實例 dictionary（字典），來節省記憶體。雖然該技術很普遍，但它有點難以正確地使用，最好保留給那種在一個記憶體關鍵 (memory-critical) 的應用程式中存在大量實例的罕見情況。
@anchor{glossary term-sequence}@anchor{70f}
@geindex sequence（序列）

@item sequence（序列）

一個 @ref{1428,,iterable}（可疊代物件），它透過 @ref{582,,__getitem__()} special method（特殊方法），使用整數索引來支援高效率的元素存取，並定義了一個 @ref{2260,,__len__()} method 來回傳該序列的長度。一些內建序列型別包括 @ref{24d,,list}、@ref{169,,str}、@ref{60c,,tuple} 和 @ref{192,,bytes}。請注意，雖然 @ref{183,,dict} 也支援 @ref{582,,__getitem__()} 和 @code{__len__()}，但它被視為對映 (mapping) 而不是序列，因為其查找方式是使用任意的 @ref{81d,,hashable} 鍵，而不是整數。

抽象基底類別 (abstract base class) @ref{13c5,,collections.abc.Sequence} 定義了一個更加豐富的介面，並不僅止於 @ref{582,,__getitem__()} 和 @ref{2260,,__len__()}，還增加了 @ref{228a,,count()}、@ref{18da,,index()}、@ref{15b1,,__contains__()} 和 @ref{e81,,__reversed__()}。實作此擴充介面的型別，可以使用 @ref{1289,,register()} 被明確地註冊。更多關於序列方法的文件，請見@ref{24b7,,常見序列操作}。
@anchor{glossary term-set-comprehension}@anchor{5715}
@geindex set comprehension（集合綜合運算）

@item set comprehension（集合綜合運算）

一種緊密的方法，用來處理一個可疊代物件中的全部或部分元素，並將處理結果以一個 set 回傳。@code{results = @{c for c in 'abracadabra' if c not in 'abc'@}} 會產生一個字串 set：@code{@{'r', 'd'@}}。請參閱@ref{7e5,,Displays for lists@comma{} sets and dictionaries}。
@anchor{glossary term-single-dispatch}@anchor{bdc}
@geindex single dispatch（單一調度）

@item single dispatch（單一調度）

@ref{bdb,,generic function}（泛型函式）調度的一種形式，在此，實作的選擇是基於單一引數的型別。
@anchor{glossary term-slice}@anchor{2489}
@geindex slice（切片）

@item slice（切片）

一個物件，它通常包含一段 @ref{70f,,sequence}（序列）的某一部分。建立一段切片的方法是使用下標符號 (subscript notation) @code{[]}，若要給出多個數字，則在數字之間使用冒號，例如 @code{variable_name[1:3:5]}。在括號（下標）符號的內部，會使用 @ref{68d,,slice} 物件。
@anchor{glossary term-soft-deprecated}@anchor{23d}
@geindex soft deprecated（軟性棄用）

@item soft deprecated（軟性棄用）

被軟性棄用的 API 代表不應再用於新程式碼中，但在現有程式碼中繼續使用它仍會是安全的。API 仍會以文件記錄並會被測試，但不會被繼續改進。

與正常棄用不同，軟性棄用沒有刪除 API 的規劃，也不會發出警告。

請參閱 PEP 387：軟性棄用@footnote{https://peps.python.org/pep-0387/#soft-deprecation}。
@anchor{glossary term-special-method}@anchor{1b62}
@geindex special method（特殊方法）

@item special method（特殊方法）

@geindex special;method（方法）

一種會被 Python 自動呼叫的 method，用於對某種型別執行某種運算，例如加法。這種 method 的名稱會在開頭和結尾有兩個下底線。Special method 在@ref{e63,,Special method names}中有詳細說明。
@anchor{glossary term-standard-library}@anchor{5716}
@geindex 標準函式庫

@item 標準函式庫

包含@ref{233,,套件}、@ref{192d,,模組}和@ref{2115,,擴充模組}的集合，它們是作為官方 Python 直譯器套件的一部分來發行。該集合的成員可能會因平台、可用的系統函式庫或其他條件而有所不同。相關文件可以在 @ref{149,,Python 標準函式庫 (Standard Library)} 中找到。

請參閱 @ref{a3b,,sys.stdlib_module_names} 以取得所有可能的標準函式庫模組名稱的列表。
@anchor{glossary term-statement}@anchor{2aae}
@geindex statement（陳述式）

@item statement（陳述式）

陳述式是一個套組（suite，一個程式碼「區塊」）中的一部分。陳述式可以是一個 @ref{2281,,expression}（運算式），或是含有關鍵字（例如 @ref{181,,if}、@ref{18d6,,while} 或 @ref{348,,for}）的多種結構之一。
@anchor{glossary term-static-type-checker}@anchor{56e}
@geindex static type checker（靜態型別檢查器）

@item static type checker（靜態型別檢查器）

會讀取 Python 程式碼並分析的外部工具，能夠找出錯誤，像是使用了不正確的型別。另請參閱@ref{227d,,型別提示 (type hints)} 以及 @ref{10a,,typing} 模組。
@anchor{glossary term-stdlib}@anchor{5717}
@geindex stdlib（標準函式庫）

@item stdlib（標準函式庫）

@ref{5716,,standard library} 的縮寫。
@anchor{glossary term-strong-reference}@anchor{5da}
@geindex strong reference（強參照）

@item strong reference（強參照）

在 Python 的 C API 中，強參照是對物件的參照，該物件為持有該參照的程式碼所擁有。建立參照時透過呼叫 @ref{788,,Py_INCREF()} 來獲得強參照、刪除參照時透過 @ref{789,,Py_DECREF()} 釋放強參照。

@ref{a91,,Py_NewRef()} 函式可用於建立一個對物件的強參照。通常，在退出強參照的作用域之前，必須在該強參照上呼叫 @ref{789,,Py_DECREF()} 函式，以避免洩漏一個參照。

另請參閱 @ref{3d5,,borrowed reference}（借用參照）。
@anchor{glossary term-t-string}@anchor{5718}
@geindex t-string（t 字串）

@item t-string（t 字串）@anchor{glossary term-t-strings}@anchor{5719}
@geindex t-strings（t 字串）

@itemx t-strings（t 字串）

以 @code{t} 或 @code{T} 為前綴的字串文本通常被稱為「t 字串」，它是@ref{1780,,模板化的字串文本}的縮寫。
@anchor{glossary term-text-encoding}@anchor{2486}
@geindex text encoding（文字編碼）

@item text encoding（文字編碼）

Python 中的字串是一個 Unicode 編碼位置 (code point) 的序列（範圍在 @code{U+0000} -- @code{U+10FFFF} 之間）。若要儲存或傳送一個字串，它必須被序列化為一個位元組序列。

將一個字串序列化為位元組序列，稱為「編碼」，而從位元組序列重新建立該字串則稱為「解碼 (decoding)」。

有多種不同的文字序列化編解碼器 (@ref{fb3,,codecs})，它們被統稱為「文字編碼」。
@anchor{glossary term-text-file}@anchor{1f34}
@geindex text file（文字檔案）

@item text file（文字檔案）

一個能夠讀取和寫入 @ref{169,,str} 物件的一個 @ref{13c4,,file object}（檔案物件）。通常，文字檔案實際上是存取位元組導向的資料流 (byte-oriented datastream) 並會自動處理 @ref{2486,,text encoding}（文字編碼）。文字檔案的例子有：以文字模式（@code{'r'} 或 @code{'w'}）開啟的檔案、@ref{758,,sys.stdin}、@ref{cc4,,sys.stdout} 以及 @ref{1124,,io.StringIO} 的實例。

另請參閱 @ref{1f35,,binary file}（二進位檔案），它是一個能夠讀取和寫入@ref{193,,類位元組串物件 (bytes-like object)} 的檔案物件。
@anchor{glossary term-thread-state}@anchor{17c4}
@geindex thread state

@item thread state

The information used by the @ref{8fd,,CPython} runtime to run in an OS thread.
For example, this includes the current exception, if any, and the
state of the bytecode interpreter.

Each thread state is bound to a single OS thread, but threads may have
many thread states available.  At most, one of them may be
@ref{4d99,,attached} at once.

An @ref{4d99,,attached thread state} is required to call most
of Python's C API, unless a function explicitly documents otherwise.
The bytecode interpreter only runs under an attached thread state.

Each thread state belongs to a single interpreter, but each interpreter
may have many thread states, including multiple for the same OS thread.
Thread states from multiple interpreters may be bound to the same
thread, but only one can be @ref{4d99,,attached} in
that thread at any given moment.

See @ref{52ad,,Thread State and the Global Interpreter Lock} for more
information.
@anchor{glossary term-token}@anchor{214c}
@geindex token

@item token

原始碼的小單位，由 @ref{2159,,詞法分析器} （也稱為 `tokenizer'）產生。名稱、數字、字串、運算子、換行符號等都以 token 表示。

@ref{101,,tokenize} 模組公開了 Python 的詞法分析器。@ref{100,,token} 模組包含各種 token 類型的資訊。
@anchor{glossary term-triple-quoted-string}@anchor{571a}
@geindex triple-quoted string（三引號內字串）

@item triple-quoted string（三引號內字串）

由三個雙引號 (") 或單引號 (') 的作為邊界的一個字串。雖然它們並沒有提供異於單引號字串的任何額外功能，但基於許多原因，它們仍是很有用的。它們讓你可以在字串中包含未跳脫 (unescaped) 的單引號和雙引號，而且它們不需使用連續字元 (continuation character) 就可以跨越多行，這使得它們在編寫說明字串時特別有用。
@anchor{glossary term-type}@anchor{1be8}
@geindex type（型別）

@item type（型別）

一個 Python 物件的型別決定了它是什麼類型的物件；每個物件都有一個型別。一個物件的型別可以用它的 @ref{16a1,,__class__} 屬性來存取，或以 @code{type(obj)} 來檢索。
@anchor{glossary term-type-alias}@anchor{666}
@geindex type alias（型別別名）

@item type alias（型別別名）

一個型別的同義詞，透過將型別指定給一個識別符 (identifier) 來建立。

型別別名對於簡化@ref{227d,,型別提示 (type hint)} 很有用。例如：

@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{10a,,typing} 和 
@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/}，有此功能的描述。
@anchor{glossary term-type-hint}@anchor{227d}
@geindex type hint（型別提示）

@item type hint（型別提示）

一種 @ref{15c,,annotation}（註釋），它指定一個變數、一個 class 屬性或一個函式的參數或回傳值的預期型別。

型別提示是選擇性的，而不是被 Python 強制的，但它們對@ref{56e,,靜態型別檢查器 (static type checkers)}很有用，並能協助 IDE 完成程式碼的補全 (completion) 和重構 (refactoring)。

全域變數、class 屬性和函式（不含區域變數）的型別提示，都可以使用 @ref{8b9,,typing.get_type_hints()} 來存取。

請參閱 @ref{10a,,typing} 和 
@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/}，有此功能的描述。
@anchor{glossary term-universal-newlines}@anchor{f30}
@geindex universal newlines（通用換行字元）

@item universal newlines（通用換行字元）

一種解譯文字流 (text stream) 的方式，會將以下所有的情況識別為一行的結束：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{24d2,,bytes.splitlines()} 的附加用途。
@anchor{glossary term-variable-annotation}@anchor{f4c}
@geindex variable annotation（變數註釋）

@item variable annotation（變數註釋）

一個變數或 class 屬性的 @ref{15c,,annotation}（註釋）。

註釋變數或 class 屬性時，賦值是選擇性的：

@example
class C:
    field: 'annotation'
@end example

變數註釋通常用於@ref{227d,,型別提示 (type hint)}：例如，這個變數預期會取得 @ref{19b,,int}（整數）值：

@example
count: int = 0
@end example

變數註釋的語法在@ref{23b3,,註釋賦值陳述式}章節有詳細的解釋。

請參閱 @ref{1ee2,,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{9d2,,註釋 (annotation) 最佳實踐}。
@anchor{glossary term-virtual-environment}@anchor{1fb4}
@geindex virtual environment（虛擬環境）

@item virtual environment（虛擬環境）

一個協作隔離 (cooperatively isolated) 的執行環境，能讓 Python 的使用者和應用程式得以安裝和升級 Python 發佈套件，而不會對同一個系統上運行的其他 Python 應用程式的行為產生干擾。

另請參閱 @ref{117,,venv}。
@anchor{glossary term-virtual-machine}@anchor{3911}
@geindex virtual machine（虛擬機器）

@item virtual machine（虛擬機器）

一部完全由軟體所定義的電腦 (computer)。Python 的虛擬機器會執行由 @ref{4a5,,bytecode}（位元組碼）編譯器所發出的位元組碼。
@anchor{glossary term-walrus-operator}@anchor{571b}
@geindex walrus operator（海象運算子）

@item walrus operator（海象運算子）

A light-hearted way to refer to the @ref{2385,,assignment expression} operator @code{:=} because it looks a bit like a
walrus if you turn your head.
@anchor{glossary term-Zen-of-Python}@anchor{571c}
@geindex Zen of Python（Python 之禪）

@item Zen of Python（Python 之禪）

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 關於這份說明文件,處理錯誤 Bug,術語表,Top
@anchor{about doc}@anchor{571d}@anchor{about about-this-documentation}@anchor{571e}@anchor{about translation-repo}@anchor{571f}
@chapter 關於這份說明文件


Python 說明文件是透過使用 Sphinx@footnote{https://www.sphinx-doc.org/}（一個原為 Python 而生的文件產生器、目前是以獨立專案形式來維護）將使用 reStructuredText@footnote{https://docutils.sourceforge.io/rst.html} 撰寫的原始檔轉換而成。

@c In the online version of these documents, you can submit comments and suggest
@c changes directly on the documentation pages.

如同 Python 自身，透過自願者的努力下產出文件與封裝後自動化執行工具。若想要回報臭蟲，請見 @ref{4de1,,處理錯誤 (Bug)} 頁面，內含相關資訊。我們永遠歡迎新的自願者加入！

致謝：


@itemize *

@item 
Fred L. Drake, Jr.，原始 Python 文件工具集的創造者以及一大部份內容的作者；

@item 
創造 reStructuredText 和 Docutils 工具組的 Docutils@footnote{https://docutils.sourceforge.io/} 專案；

@item 
Fredrik Lundh 先生，Sphinx 從他的 Alternative Python Reference 計劃中獲得許多的好主意。
@end itemize

@menu
* Python 文件的貢獻者們:: 

@end menu

@node Python 文件的貢獻者們,,,關於這份說明文件
@anchor{about contributors-to-the-python-documentation}@anchor{5720}
@section Python 文件的貢獻者們


許多人都曾為 Python 這門語言、Python 標準函式庫和 Python 說明文件貢獻過。Python 所發佈的原始碼中含有部份貢獻者的清單，請見 Misc/ACKS@footnote{https://github.com/python/cpython/tree/3.14/Misc/ACKS} 。

正因為 Python 社群的撰寫與貢獻才有這份這麼棒的說明文件 -- 感謝所有貢獻過的人們！

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)

@node 處理錯誤 Bug,版權宣告,關於這份說明文件,Top
@anchor{bugs doc}@anchor{5721}@anchor{bugs dealing-with-bugs}@anchor{5722}@anchor{bugs reporting-bugs}@anchor{4de1}@anchor{bugs translation-repo}@anchor{5723}
@chapter 處理錯誤 (Bug)


Python 已經是一個以穩定著稱的成熟程式語言。為了維持「穩定」的信譽，開發者們想知道任何你在 Python 中發現的缺失。

有時候自己直接修復錯誤並且送出一個修正給 Python 會比較快，因為這樣會加速流程而且不會困擾到太多人。學習如何@ref{5724,,貢獻給 Python}。

@menu
* 說明文件的錯誤:: 
* 使用 Python 問題追蹤系統:: 
* 開始讓自己貢獻 Python:: 

@end menu

@node 說明文件的錯誤,使用 Python 問題追蹤系統,,處理錯誤 Bug
@anchor{bugs documentation-bugs}@anchor{5725}
@section 說明文件的錯誤


如果你在這份說明文件中發現了錯誤並想要提出改進方案，請將錯誤報告提交到@ref{551,,錯誤追蹤系統 (issue tracker)}。如果你有相應的修正建議，請一併提交。（譯者註：如果是繁體中文說明文件翻譯相關的錯誤，請提交到 @indicateurl{https://github.com/python/python-docs-zh-tw/issues}。）

如果錯誤或建議的改進涉及此文件的翻譯，請將報告提交到翻譯存儲庫@footnote{https://github.com/python/python-docs-zh-tw}。

你也可以在我們的說明文件 Discourse 討論區@footnote{https://discuss.python.org/c/documentation/26}中新增一個討論事項。

如果你發現文件主題 (HTML / CSS / JavaScript) 中存在錯誤，請在 python-doc-theme 問題追蹤系統@footnote{https://github.com/python/python-docs-theme}上提交錯誤報告。


@subsubheading 也參考



@table @asis

@item 說明文件錯誤@footnote{https://github.com/python/cpython/issues?q=is%3Aissue+is%3Aopen+label%3Adocs}

一系列已被提交至 Python 問題追蹤系統的有關說明文件的錯誤。

@item 問題追蹤系統@footnote{https://devguide.python.org/tracker/}

在追蹤系統上回報改進建議的過程簡介。

@item 貢獻說明文件@footnote{https://devguide.python.org/docquality/#helping-with-documentation}

給有意成為 Python 說明文件貢獻者的綜合指南。

@item 說明文件翻譯@footnote{https://devguide.python.org/documentation/translating/}

一份 GitHub 網頁的清單，裡面有各個說明文件翻譯團隊的連結，以及他們的主要聯絡人。
@end table


@node 使用 Python 問題追蹤系統,開始讓自己貢獻 Python,說明文件的錯誤,處理錯誤 Bug
@anchor{bugs using-the-python-issue-tracker}@anchor{5726}@anchor{bugs using-the-tracker}@anchor{551}
@section 使用 Python 問題追蹤系統


對於 Python 本身的問題報告，應該透過 GitHub 問題追蹤系統 (@indicateurl{https://github.com/python/cpython/issues}) 提交。這個 GitHub 問題追蹤系統提供了一個網頁表單，可以輸入並提交相關資訊給開發者。

填寫報告的第一步，是確認該問題是否已經被回報過了。這樣做的好處，除了可以節省開發者的時間，也能讓你了解目前關於該問題的處理進度；有可能已經在下一個發行版本中修正了這個問題，也有可能需要更詳細的資訊（在這種情況下，如果可以，非常歡迎你提供資訊！）。要確認是否重複回報，請使用頁面頂端的搜尋框來搜尋追蹤系統。

如果你想回報的問題還沒有在問題列表出現過，請登入 GitHub。如果你還沒有 GitHub 帳戶，請點選「Sign up」連結來建立一個新的帳戶。你無法以匿名方式提交錯誤報告。

如果已經登入，那你就可以提交問題了。請點選列表頂端區域的「New issue」按鈕，來回報一個新的問題。

提交的表單中有兩個欄位，「Title」及「Comment」。

在「Title」欄位，輸入對該問題`非常'簡短的描述；最好少於十個單字。

在「Comment」欄位，請詳細描述該問題，包括你預期發生的情況和實際發生的情況。請確定說明中包含了涉及到的任何擴充模組，以及你當時所使用的硬體和軟體平台（視情況而定，可以附上版本資訊）。

每一份問題報告都會被一位開發人員查核，並由他決定要做出什麼變更來修正這個問題。每當該問題有修正動作時，你會收到更新回報。


@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 問題追蹤系統,處理錯誤 Bug
@anchor{bugs contributing-to-python}@anchor{5724}@anchor{bugs getting-started-contributing-to-python-yourself}@anchor{5727}
@section 開始讓自己貢獻 Python


除了只是回報你所發現的錯誤之外，同樣也歡迎你提交修正它們的修補程式 (patch)。你可以在 Python 開發者指南@footnote{https://mail.python.org/mailman3/lists/core-mentorship.python.org/}中找到如何開始修補 Python 的更多資訊。如果你有任何問題，核心導師郵寄清單@footnote{https://devguide.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 版權宣告,沿革與授權,處理錯誤 Bug,Top
@anchor{copyright doc}@anchor{5728}@anchor{copyright copyright}@anchor{5729}@anchor{copyright translation-repo}@anchor{572a}
@chapter 版權宣告


Python 和這份說明文件的版權：

Copyright © 2001 Python 軟體基金會。保留所有權利。

Copyright © 2000 BeOpen.com 保留所有權利。

Copyright © 1995-2000 Corporation for National Research Initiatives 保留所有權利。

Copyright © 1991-1995 Stichting Mathematisch Centrum 保留所有權利。


__________________________________________________________________


完整的授權條款資訊請參見@ref{572b,,沿革與授權}。

@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
@anchor{license doc}@anchor{572c}@anchor{license history-and-license}@anchor{572b}@anchor{license id1}@anchor{572d}@anchor{license translation-repo}@anchor{572e}
@chapter 沿革與授權


@menu
* 軟體沿革:: 
* 關於存取或以其他方式使用 Python 的合約條款:: 
* 被收錄軟體的授權與致謝:: 

@end menu

@node 軟體沿革,關於存取或以其他方式使用 Python 的合約條款,,沿革與授權
@anchor{license history-of-the-software}@anchor{572f}
@section 軟體沿革


Python 是由荷蘭數學和計算機科學研究學會（CWI，見 @indicateurl{https://www.cwi.nl}）的 Guido van Rossum 於 1990 年代早期所創造，目的是作為一種稱為 ABC 語言的後繼者。儘管 Python 包含了許多來自其他人的貢獻，Guido 仍是其主要作者。

1995 年，Guido 在維吉尼亞州雷斯頓的國家創新研究公司（CNRI，見 @indicateurl{https://www.cnri.reston.va.us}）繼續他在 Python 的工作，並在那裡發佈了該軟體的多個版本。

2000 年五月，Guido 和 Python 核心開發團隊轉移到 BeOpen.com 並成立了 BeOpen PythonLabs 團隊。同年十月，PythonLabs 團隊轉移到 Digital Creations，後來成為 Zope Corporation。2001 年，Python 軟體基金會（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 相容並不表示我們是在 GPL 下發佈 Python。不像 GPL，所有的 Python 授權都可以讓你發佈修改後的版本，但不一定要使你的變更成為開源。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{5730}
@section 關於存取或以其他方式使用 Python 的合約條款


Python 軟體和說明文件的授權是基於 Python 軟體基金會授權第二版 (Python Software Foundation License Version 2)。

從 Python 3.8.6 開始，說明文件中的範例、程式庫和其他程式碼，是被雙重授權 (dual licensed) 於 PSF 授權第二版以及 @ref{5731,,Zero-Clause BSD 授權}。

有些被納入 Python 中的軟體是基於不同的授權。這些授權將會與其授權之程式碼一起被列出。關於這些授權的不完整清單，請參閱@ref{5732,,被收錄軟體的授權與致謝}。

@menu
* PYTHON SOFTWARE FOUNDATION LICENSE VERSION 2:: 
* BEOPEN.COM LICENSE AGREEMENT FOR PYTHON 2.0: BEOPEN COM LICENSE AGREEMENT FOR PYTHON 2 0. 
* CNRI LICENSE AGREEMENT FOR PYTHON 1.6.1: CNRI LICENSE AGREEMENT FOR PYTHON 1 6 1. 
* CWI LICENSE AGREEMENT FOR PYTHON 0.9.0 THROUGH 1.2: CWI LICENSE AGREEMENT FOR PYTHON 0 9 0 THROUGH 1 2. 
* ZERO-CLAUSE BSD LICENSE FOR CODE IN THE PYTHON DOCUMENTATION:: 

@end menu

@node PYTHON SOFTWARE FOUNDATION LICENSE VERSION 2,BEOPEN COM LICENSE AGREEMENT FOR PYTHON 2 0,,關於存取或以其他方式使用 Python 的合約條款
@anchor{license psf-license}@anchor{5733}@anchor{license python-software-foundation-license-version-2}@anchor{5734}
@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 LICENSE AGREEMENT FOR PYTHON 2 0,CNRI LICENSE AGREEMENT FOR PYTHON 1 6 1,PYTHON SOFTWARE FOUNDATION LICENSE VERSION 2,關於存取或以其他方式使用 Python 的合約條款
@anchor{license beopen-com-license-agreement-for-python-2-0}@anchor{5735}
@subsection BEOPEN.COM LICENSE AGREEMENT FOR PYTHON 2.0


BEOPEN PYTHON OPEN SOURCE LICENSE AGREEMENT VERSION 1

@example
1. This LICENSE AGREEMENT is between BeOpen.com ("BeOpen"), having an office at
   160 Saratoga Avenue, Santa Clara, CA 95051, and the Individual or Organization
   ("Licensee") accessing and otherwise using this software in source or binary
   form and its associated documentation ("the Software").

2. Subject to the terms and conditions of this BeOpen Python License Agreement,
   BeOpen hereby grants Licensee a non-exclusive, royalty-free, world-wide license
   to reproduce, analyze, test, perform and/or display publicly, prepare derivative
   works, distribute, and otherwise use the Software alone or in any derivative
   version, provided, however, that the BeOpen Python License is retained in the
   Software, alone or in any derivative version prepared by Licensee.

3. BeOpen is making the Software available to Licensee on an "AS IS" basis.
   BEOPEN MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED.  BY WAY OF
   EXAMPLE, BUT NOT LIMITATION, BEOPEN MAKES NO AND DISCLAIMS ANY REPRESENTATION OR
   WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE
   USE OF THE SOFTWARE WILL NOT INFRINGE ANY THIRD PARTY RIGHTS.

4. BEOPEN SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF THE SOFTWARE FOR
   ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF USING,
   MODIFYING OR DISTRIBUTING THE SOFTWARE, OR ANY DERIVATIVE THEREOF, EVEN IF
   ADVISED OF THE POSSIBILITY THEREOF.

5. This License Agreement will automatically terminate upon a material breach of
   its terms and conditions.

6. This License Agreement shall be governed by and interpreted in all respects
   by the law of the State of California, excluding conflict of law provisions.
   Nothing in this License Agreement shall be deemed to create any relationship of
   agency, partnership, or joint venture between BeOpen and Licensee.  This License
   Agreement does not grant permission to use BeOpen trademarks or trade names in a
   trademark sense to endorse or promote products or services of Licensee, or any
   third party.  As an exception, the "BeOpen Python" logos available at
   @indicateurl{http://www.pythonlabs.com/logos.html} may be used according to the permissions
   granted on that web page.

7. By copying, installing or otherwise using the software, Licensee agrees to be
   bound by the terms and conditions of this License Agreement.
@end example

@node CNRI LICENSE AGREEMENT FOR PYTHON 1 6 1,CWI LICENSE AGREEMENT FOR PYTHON 0 9 0 THROUGH 1 2,BEOPEN COM LICENSE AGREEMENT FOR PYTHON 2 0,關於存取或以其他方式使用 Python 的合約條款
@anchor{license cnri-license-agreement-for-python-1-6-1}@anchor{5736}
@subsection CNRI LICENSE AGREEMENT FOR 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 LICENSE AGREEMENT FOR PYTHON 0 9 0 THROUGH 1 2,ZERO-CLAUSE BSD LICENSE FOR CODE IN THE PYTHON DOCUMENTATION,CNRI LICENSE AGREEMENT FOR PYTHON 1 6 1,關於存取或以其他方式使用 Python 的合約條款
@anchor{license cwi-license-agreement-for-python-0-9-0-through-1-2}@anchor{5737}
@subsection CWI LICENSE AGREEMENT FOR PYTHON 0.9.0 THROUGH 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 LICENSE FOR CODE IN THE PYTHON DOCUMENTATION,,CWI LICENSE AGREEMENT FOR PYTHON 0 9 0 THROUGH 1 2,關於存取或以其他方式使用 Python 的合約條款
@anchor{license bsd0}@anchor{5731}@anchor{license zero-clause-bsd-license-for-code-in-the-python-documentation}@anchor{5738}
@subsection ZERO-CLAUSE BSD LICENSE FOR CODE IN THE PYTHON DOCUMENTATION


@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{5739}@anchor{license otherlicenses}@anchor{5732}
@section 被收錄軟體的授權與致謝


本節是一個不完整但持續增加的授權與致謝清單，對象是在 Python 發佈版本中所收錄的第三方軟體。

@menu
* Mersenne Twister:: 
* Sockets: Sockets<2>. 
* 非同步 socket 服務:: 
* Cookie 管理:: 
* 執行追蹤:: 
* UUencode 與 UUdecode 函式:: 
* XML 遠端程序呼叫:: 
* test_epoll:: 
* Select kqueue:: 
* SipHash24:: 
* strtod 與 dtoa:: 
* OpenSSL: OpenSSL<2>. 
* expat:: 
* libffi:: 
* zlib: zlib<4>. 
* cfuhash:: 
* libmpdec:: 
* W3C C14N 測試套件:: 
* mimalloc:: 
* asyncio: asyncio<15>. 
* Global Unbounded Sequences (GUS): Global Unbounded Sequences GUS. 
* Zstandard bindings:: 

@end menu

@node Mersenne Twister,Sockets<2>,,被收錄軟體的授權與致謝
@anchor{license mersenne-twister}@anchor{573a}
@subsection Mersenne Twister


@ref{bd,,random} 模組底下的 @code{_random} C 擴充程式包含了以 @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{573b}
@subsection Sockets


@ref{d1,,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{573c}
@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{573d}
@subsection Cookie 管理


@ref{75,,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{573e}
@subsection 執行追蹤


@ref{103,,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{573f}
@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{5740}
@subsection XML 遠端程序呼叫


@ref{134,,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,Select kqueue,XML 遠端程序呼叫,被收錄軟體的授權與致謝
@anchor{license test-epoll}@anchor{5741}
@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 Select kqueue,SipHash24,test_epoll,被收錄軟體的授權與致謝
@anchor{license select-kqueue}@anchor{5742}
@subsection Select kqueue


@ref{c6,,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,Select kqueue,被收錄軟體的授權與致謝
@anchor{license siphash24}@anchor{5743}
@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{5744}
@subsection strtod 與 dtoa


@code{Python/dtoa.c} 檔案提供了 C 的 dtoa 和 strtod 函式，用於將 C 的雙精度浮點數和字串互相轉換。該檔案是衍生自 David M. Gay 建立的同名檔案，後者現在可以從 @indicateurl{https://web.archive.org/web/20220517033456/http://www.netlib.org/fp/dtoa.c} 下載。於 2009 年 3 月 16 日所檢索的原始檔案包含以下版權與授權聲明：

@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{5745}
@subsection OpenSSL


如果 OpenSSL 函式庫可被作業系統使用，則 @ref{6c,,hashlib}、@ref{b2,,posix}、@ref{d5,,ssl} 模組會使用它來提升效能。此外，因為 Windows 和 macOS 的 Python 安裝程式可能包含 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{5746}
@subsection expat


除非在建置 @ref{12c,,pyexpat} 擴充時設定為 @code{--with-system-expat}，否則該擴充會用一個內含 expat 原始碼的副本來建置：

@example
Copyright (c) 1998, 1999, 2000 Thai Open Source Software Center Ltd
                               and Clark Cooper

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
@end example

@node libffi,zlib<4>,expat,被收錄軟體的授權與致謝
@anchor{license libffi}@anchor{5747}
@subsection libffi


除非在建置 @code{_ctypes} 模組底下 @code{_ctypes} 擴充程式時設定為 @code{--with-system-libffi}，否則該擴充會用一個內含 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<4>,cfuhash,libffi,被收錄軟體的授權與致謝
@anchor{license zlib}@anchor{5748}
@subsection zlib


如果在系統上找到的 zlib 版本太舊以致於無法用於建置 @ref{139,,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<4>,被收錄軟體的授權與致謝
@anchor{license cfuhash}@anchor{5749}
@subsection cfuhash


@ref{105,,tracemalloc} 使用的雜湊表 (hash table) 實作，是以 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{574a}
@subsection libmpdec


除非在建置 @ref{3a,,decimal} 模組底下 @code{_decimal} C 擴充程式時設定為 @code{--with-system-libmpdec}，否則該模組會用一個內含 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{574b}
@subsection W3C C14N 測試套件


@ref{e8,,test} 程式包中的 C14N 2.0 測試套件 (@code{Lib/test/xmltestdata/c14n-20/}) 是從 W3C 網站 @indicateurl{https://www.w3.org/TR/xml-c14n2-testcases/} 被檢索，且是基於 3-clause 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<15>,W3C C14N 測試套件,被收錄軟體的授權與致謝
@anchor{license mimalloc}@anchor{574c}@anchor{license mimalloc-license}@anchor{64e}
@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<15>,Global Unbounded Sequences GUS,mimalloc,被收錄軟體的授權與致謝
@anchor{license asyncio}@anchor{574d}
@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 Global Unbounded Sequences GUS,Zstandard bindings,asyncio<15>,被收錄軟體的授權與致謝
@anchor{license global-unbounded-sequences-gus}@anchor{574e}
@subsection Global Unbounded Sequences (GUS)


The file @code{Python/qsbr.c} is adapted from FreeBSD's "Global Unbounded
Sequences" safe memory reclamation scheme in
subr_smr.c@footnote{https://github.com/freebsd/freebsd-src/blob/main/sys/kern/subr_smr.c}.
The file is distributed under the 2-Clause BSD License:

@example
Copyright (c) 2019,2020 Jeffrey Roberson <jeff@@FreeBSD.org>

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
   notice unmodified, this list of conditions, and the following
   disclaimer.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR "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 bindings,,Global Unbounded Sequences GUS,被收錄軟體的授權與致謝
@anchor{license zstandard-bindings}@anchor{574f}
@subsection Zstandard bindings


Zstandard bindings in @code{Modules/_zstd} and @code{Lib/compression/zstd}
are based on code from the
pyzstd library@footnote{https://github.com/Rogdham/pyzstd/}, copyright Ma Lin and
contributors. The pyzstd code is distributed under the 3-Clause BSD License:

@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

@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.
* cProfile: 2b. 
* crypt: 2c. Removed in 3.13.
* csv: 2d. Write and read tabular data to and from delimited
                        files.
* ctypes: 2e. A foreign function library for Python.
* curses: 2f. An interface to the curses library@comma{} providing
                        portable terminal handling.
* curses.ascii: 30. Constants and set-membership functions for ASCII
                        characters.
* curses.panel: 31. A panel stack extension that adds depth to curses
                        windows.
* curses.textpad: 32. Emacs-like input editing in a curses window.
* dataclasses: 33. Generate special methods on user-defined classes.
* datetime: 34. Basic date and time types.
* dbm: 35. Interfaces to various Unix "database" formats.
* dbm.dumb: 36. Portable implementation of the simple DBM interface.
* dbm.gnu: 37. GNU database manager
* dbm.ndbm: 38. The New Database Manager
* dbm.sqlite3: 39. SQLite backend for dbm
* decimal: 3a. Implementation of the General Decimal Arithmetic
                        Specification.
* difflib: 3b. Helpers for computing differences between objects.
* dis: 3c. Disassembler for Python bytecode.
* distutils: 3d. Removed in 3.12.
* doctest: 3e. Test pieces of code within docstrings.
* email: 3f. Package supporting the parsing@comma{}
                        manipulating@comma{} and generating email messages.
* email.charset: 40. Character Sets
* email.contentmanager: 41. Storing and Retrieving Content from MIME Parts
* email.encoders: 42. Encoders for email message payloads.
* email.errors: 43. The exception classes used by the email package.
* email.generator: 44. Generate flat text email messages from a message
                        structure.
* email.header: 45. Representing non-ASCII headers
* email.headerregistry: 46. Automatic Parsing of headers based on the field name
* email.iterators: 47. Iterate over a message object tree.
* email.message: 48. The base class representing email messages.
* email.mime: 49. Build MIME messages.
* email.mime.application: 4a. 
* email.mime.audio: 4b. 
* email.mime.base: 4c. 
* email.mime.image: 4d. 
* email.mime.message: 4e. 
* email.mime.multipart: 4f. 
* email.mime.nonmultipart: 50. 
* email.mime.text: 51. 
* email.parser: 52. Parse flat text email messages to produce a message
                        object structure.
* email.policy: 53. Controlling the parsing and generating of messages
* email.utils: 54. Miscellaneous email package utilities.
* encodings: 55. Encodings package
* encodings.idna: 56. Internationalized Domain Names implementation
* encodings.mbcs: 57. Windows ANSI codepage
* encodings.utf_8_sig: 58. UTF-8 codec with BOM signature
* ensurepip: 59. Bootstrapping the "pip" installer into an existing
                        Python installation or virtual environment.
* enum: 5a. Implementation of an enumeration class.
* errno: 5b. Standard errno system symbols.
* faulthandler: 5c. Dump the Python traceback.
* fcntl: 5d. The fcntl() and ioctl() system calls.
* filecmp: 5e. Compare files efficiently.
* fileinput: 5f. Loop over standard input or a list of files.
* fnmatch: 60. Unix shell style filename pattern matching.
* fractions: 61. Rational numbers.
* ftplib: 62. FTP protocol client (requires sockets).
* functools: 63. Higher-order functions and operations on callable
                        objects.
* gc: 64. Interface to the cycle-detecting garbage collector.
* getopt: 65. Portable parser for command line options; support both
                        short and long option names.
* getpass: 66. Portable reading of passwords and retrieval of the
                        userid.
* gettext: 67. Multilingual internationalization services.
* glob: 68. Unix shell style pathname pattern expansion.
* graphlib: 69. Functionality to operate with graph-like structures
* grp: 6a. The group database (getgrnam() and friends).
* gzip: 6b. Interfaces for gzip compression and decompression
                        using file objects.
* hashlib: 6c. Secure hash and message digest algorithms.
* heapq: 6d. Heap queue algorithm (a.k.a. priority queue).
* hmac: 6e. Keyed-Hashing for Message Authentication (HMAC)
                        implementation
* html: 6f. Helpers for manipulating HTML.
* html.entities: 70. Definitions of HTML general entities.
* html.parser: 71. A simple parser that can handle HTML and XHTML.
* http: 72. HTTP status codes and messages
* http.client: 73. HTTP and HTTPS protocol client (requires sockets).
* http.cookiejar: 74. Classes for automatic handling of HTTP cookies.
* http.cookies: 75. Support for HTTP state management (cookies).
* http.server: 76. HTTP server and request handlers.
* idlelib: 77. Implementation package for the IDLE shell/editor.
* imaplib: 78. IMAP4 protocol client (requires sockets).
* imghdr: 79. Removed in 3.13.
* imp: 7a. Removed in 3.12.
* importlib: 7b. The implementation of the import machinery.
* importlib.abc: 7c. Abstract base classes related to import
* importlib.machinery: 7d. Importers and path hooks
* importlib.metadata: 7e. Accessing package metadata
* importlib.resources: 7f. Package resource reading@comma{} opening@comma{} and
                        access
* importlib.resources.abc: 80. Abstract base classes for resources
* importlib.util: 81. Utility code for importers
* inspect: 82. Extract information and source code from live objects.
* io: 83. Core tools for working with streams.
* ipaddress: 84. IPv4/IPv6 manipulation library.
* itertools: 85. Functions creating iterators for efficient looping.
* json: 86. Encode and decode the JSON format.
* json.tool: 87. A command-line interface to validate and pretty-print
                        JSON.
* keyword: 88. Test whether a string is a keyword in Python.
* linecache: 89. Provides random access to individual lines from text
                        files.
* locale: 8a. Internationalization services.
* logging: 8b. Flexible event logging system for applications.
* logging.config: 8c. Configuration of the logging module.
* logging.handlers: 8d. Handlers for the logging module.
* lzma: 8e. A Python wrapper for the liblzma compression library.
* mailbox: 8f. Manipulate mailboxes in various formats
* mailcap: 90. Removed in 3.13.
* marshal: 91. Convert Python objects to streams of bytes and back
                        (with different constraints).
* math: 92. Mathematical functions (sin() etc.).
* 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. Python source profiler.
* pstats: b5. Statistics object for use with the profiler.
* pty: b6. Pseudo-Terminal Handling for Unix.
* pwd: b7. The password database (getpwnam() and friends).
* py_compile: b8. Generate byte-code files from Python source files.
* pyclbr: b9. Supports information extraction for a Python module
                        browser.
* pydoc: ba. Documentation generator and online help system.
* queue: bb. A synchronized queue class.
* quopri: bc. Encode and decode files using the MIME quoted-
                        printable encoding.
* random: bd. Generate pseudo-random numbers with various common
                        distributions.
* re: be. Regular expression operations.
* readline: bf. GNU readline support for Python.
* reprlib: c0. Alternate repr() implementation with size limits.
* resource: c1. An interface to provide resource usage information on
                        the current process.
* rlcompleter: c2. Python identifier completion@comma{} suitable for the
                        GNU readline library.
* runpy: c3. Locate and run Python modules without importing them
                        first.
* sched: c4. General purpose event scheduler.
* secrets: c5. Generate secure random numbers for managing secrets.
* select: c6. Wait for I/O completion on multiple streams.
* selectors: c7. High-level I/O multiplexing.
* shelve: c8. Python object persistence.
* shlex: c9. Simple lexical analysis for Unix shell-like languages.
* shutil: ca. High-level file operations@comma{} including copying.
* signal: cb. Set handlers for asynchronous events.
* site: cc. Module responsible for site-specific configuration.
* sitecustomize: cd. 
* smtpd: ce. Removed in 3.12.
* smtplib: cf. SMTP protocol client (requires sockets).
* sndhdr: d0. Removed in 3.13.
* socket: d1. Low-level networking interface.
* socketserver: d2. A framework for network servers.
* spwd: d3. Removed in 3.13.
* sqlite3: d4. A DB-API 2.0 implementation using SQLite 3.x.
* ssl: d5. TLS/SSL wrapper for socket objects
* stat: d6. Utilities for interpreting the results of
                        os.stat()@comma{} os.lstat() and os.fstat().
* statistics: d7. Mathematical statistics functions
* string: d8. Common string operations.
* string.templatelib: d9. Support for template string literals.
* stringprep: da. String preparation@comma{} as per RFC 3453
* struct: db. Interpret bytes as packed binary data.
* subprocess: dc. Subprocess management.
* sunau: dd. Removed in 3.13.
* symtable: de. Interface to the compiler's internal symbol tables.
* sys: df. Access system-specific parameters and functions.
* sys.monitoring: e0. Access and control event monitoring
* sysconfig: e1. Python's configuration information
* syslog: e2. An interface to the Unix syslog library routines.
* tabnanny: e3. Tool for detecting white space related problems in
                        Python source files in a directory tree.
* tarfile: e4. Read and write tar-format archive files.
* telnetlib: e5. Removed in 3.13.
* tempfile: e6. Generate temporary files and directories.
* termios: e7. POSIX style tty control.
* test: e8. Regression tests package containing the testing suite
                        for Python.
* test.regrtest: e9. Drives the regression test suite.
* test.support: ea. Support for Python's regression test suite.
* test.support.bytecode_helper: eb. Support tools for testing correct bytecode
                                generation.
* test.support.import_helper: ec. Support for import tests.
* test.support.os_helper: ed. Support for os tests.
* test.support.script_helper: ee. Support for Python's script execution tests.
* test.support.socket_helper: ef. Support for socket tests.
* test.support.threading_helper: f0. Support for threading tests.
* test.support.warnings_helper: f1. Support for warnings tests.
* textwrap: f2. Text wrapping and filling
* threading: f3. Thread-based parallelism.
* time: f4. Time access and conversions.
* timeit: f5. Measure the execution time of small code snippets.
* tkinter: f6. Interface to Tcl/Tk for graphical user interfaces
* tkinter.colorchooser: f7. Color choosing dialog
* tkinter.commondialog: f8. Tkinter base class for dialogs
* tkinter.dnd: f9. Tkinter drag-and-drop interface
* tkinter.filedialog: fa. Dialog classes for file selection
* tkinter.font: fb. Tkinter font-wrapping class
* tkinter.messagebox: fc. Various types of alert dialogs
* tkinter.scrolledtext: fd. Text widget with a vertical scroll bar.
* tkinter.simpledialog: fe. Simple dialog windows
* tkinter.ttk: ff. Tk themed widget set
* token: 100. Constants representing terminal nodes of the parse
                        tree.
* tokenize: 101. Lexical scanner for Python source code.
* tomllib: 102. Parse TOML files.
* trace: 103. Trace or track Python statement execution.
* traceback: 104. Print or retrieve a stack traceback.
* tracemalloc: 105. Trace memory allocations.
* tty: 106. Utility functions that perform common terminal control
                        operations.
* turtle: 107. An educational framework for simple graphics
                        applications
* turtledemo: 108. A viewer for example turtle scripts
* types: 109. Names for built-in types.
* typing: 10a. Support for type hints (see :pep:`484`).
* unicodedata: 10b. Access the Unicode Database.
* unittest: 10c. Unit testing framework for Python.
* unittest.mock: 10d. Mock object library.
* urllib: 10e. 
* urllib.error: 10f. Exception classes raised by urllib.request.
* urllib.parse: 110. Parse URLs into or assemble them from components.
* urllib.request: 111. Extensible library for opening URLs.
* urllib.response: 112. Response classes used by urllib.
* urllib.robotparser: 113. Load a robots.txt file and answer questions about
                        fetchability of other URLs.
* usercustomize: 114. 
* uu: 115. Removed in 3.13.
* uuid: 116. UUID objects (universally unique identifiers)
                        according to RFC 9562
* venv: 117. Creation of virtual environments.
* warnings: 118. Issue warning messages and control their disposition.
* wave: 119. Provide an interface to the WAV sound format.
* weakref: 11a. Support for weak references and weak dictionaries.
* webbrowser: 11b. Easy-to-use controller for web browsers.
* winreg: 11c. Routines and objects for manipulating the Windows
                        registry.
* winsound: 11d. Access to the sound-playing machinery for Windows.
* wsgiref: 11e. WSGI Utilities and Reference Implementation.
* wsgiref.handlers: 11f. WSGI server/gateway base classes.
* wsgiref.headers: 120. WSGI response header tools.
* wsgiref.simple_server: 121. A simple WSGI HTTP server.
* wsgiref.types: 122. WSGI types for static type checking
* wsgiref.util: 123. WSGI environment utilities.
* wsgiref.validate: 124. WSGI conformance checker.
* xdrlib: 125. Removed in 3.13.
* xml: 126. Package containing XML processing modules
* xml.dom: 127. Document Object Model API for Python.
* xml.dom.minidom: 128. Minimal Document Object Model (DOM) implementation.
* xml.dom.pulldom: 129. Support for building partial DOM trees from SAX
                        events.
* xml.etree.ElementInclude: 12a. 
* xml.etree.ElementTree: 12b. Implementation of the ElementTree API.
* xml.parsers.expat: 12c. An interface to the Expat non-validating XML parser.
* xml.parsers.expat.errors: 12d. 
* xml.parsers.expat.model: 12e. 
* xml.sax: 12f. Package containing SAX2 base classes and convenience
                        functions.
* xml.sax.handler: 130. Base classes for SAX event handlers.
* xml.sax.saxutils: 131. Convenience functions and classes for use with SAX.
* xml.sax.xmlreader: 132. Interface which SAX-compliant XML parsers must
                        implement.
* xmlrpc: 133. Server and client modules implementing XML-RPC.
* xmlrpc.client: 134. XML-RPC client access.
* xmlrpc.server: 135. Basic XML-RPC server implementations.
* zipapp: 136. Manage executable Python zip archives
* zipfile: 137. Read and write ZIP-format archive files.
* zipimport: 138. Support for importing Python modules from ZIP
                        archives.
* zlib: 139. Low-level interface to compression and decompression
                        routines compatible with gzip.
* zoneinfo: 13a. IANA time zone support
@end menu


@node 索引,,Python 模組索引,Top
@unnumbered 索引


@printindex ge

@anchor{library/unittest unittest tearDownModule}@w{                              }
@anchor{1537}@w{                              }
@anchor{library/ctypes audit_event_ctypes_memoryview_at_0}@w{                              }
@anchor{using/cmdline audit_event_cpython_run_stdin_1}@w{                              }
@anchor{library/asyncio audit_event_cpython_run_stdin_2}@w{                              }
@anchor{library/time audit_event_time_sleep_0}@w{                              }
@anchor{library/stdtypes list append}@w{                              }
@anchor{4613}@w{                              }
@anchor{19ac}@w{                              }
@anchor{460f}@w{                              }
@anchor{using/cmdline audit_event_cpython_run_stdin_0}@w{                              }
@anchor{library/stdtypes list remove}@w{                              }
@anchor{5fa}@w{                              }
@anchor{8d4}@w{                              }
@anchor{library/stdtypes range index}@w{                              }
@anchor{4610}@w{                              }
@anchor{library/sys script_path}@w{                              }
@anchor{library/stdtypes list insert}@w{                              }
@anchor{460b}@w{                              }
@anchor{5fb}@w{                              }
@anchor{library/_thread start_new_thread}@w{                              }
@anchor{1399}@w{                              }
@anchor{library/stdtypes tuple count}@w{                              }
@anchor{library/stdtypes list extend}@w{                              }
@anchor{461a}@w{                              }
@anchor{4611}@w{                              }
@anchor{460e}@w{                              }
@anchor{15bb}@w{                              }
@anchor{15ba}@w{                              }
@anchor{1eed}@w{                              }
@anchor{4612}@w{                              }
@anchor{18d9}@w{                              }
@anchor{461c}@w{                              }
@anchor{library/stdtypes list pop}@w{                              }
@anchor{library/sys audit_event_cpython_remote_debugger_script_0}@w{                              }
@anchor{library/stdtypes tuple index}@w{                              }
@anchor{library/stdtypes list clear}@w{                              }
@anchor{using/cmdline audit_event_cpython_run_file_0}@w{                              }

@c %**end of body
@bye
